# Taking over a job

Open a live browser on a parked job, finish what the program could not, and turn what you did into steps the next run can take.

Taking over a job opens a fresh browser at the point a parked job stopped and streams it to you, so
you can finish by hand what the program could not. What you do is recorded and offered back as
proposals, so the next run can do it alone.

## When to use it

Some pages need a person: a dialog with no label anyone could recognise, a check that only makes
sense to a human, a login that changed overnight. When a job parks on one of those
(`needs_attention`) or is waiting for a value (`awaiting_input`), take it over.

Try the cheaper answers first: a proposal on the attention card often fixes the job in one click,
and a job waiting for a one-time code only needs the code. Take over when neither is enough.

## 1. Start a takeover

From the panel, press **Take over** on the job's card in **Attention**, or on the job's page. From
code:

```bash
curl -X POST https://api.kaab.ist/v1/jobs/job_…/takeover \
  -H "Authorization: Bearer sk_live_…"
```

```json
{ "live_url": "https://app.kaab.ist/live/lv_…?t=…", "token": "…", "expires_in": 900 }
```

Open `live_url` in a browser, or hand it to the person who should finish the job. Behind it,
Kaabist has already:

1. placed a browser on one of its pods (if none is free within ten seconds you get
   `503 live_unavailable`; try again shortly),
2. restored the job's checkpoint into it: cookies, local storage, the page it was on,
3. checked that the page is where the job stopped. If it is not (a session that aged out, say),
   the browser goes back to where the session was established and the live view tells you so.

The token is good for 15 minutes; the panel refreshes it for you. A session never outlives an hour,
and one nobody is watching ends after about five minutes.

## 2. Drive it

The live view is headed **Take over**, with **Open the job** beside the title. The page fills the
left side, under a toolbar with a **Use the page** / **Inspect** switch, back, reload, the address
bar and a connection badge. A rail on the right shows, from the top:

- a reminder that what you do here is recorded and becomes a proposal;
- the program, the job and why it parked;
- the step it stopped at, with "Continue once the page shows what the step expects.";
- notices from the obstacle probe, such as "Something covers the page. Close it, then continue.";
- the three buttons of step 3.

The page is the real page: click, type, scroll, open links. **Inspect** switches to pick mode to
look at an element without clicking it. A dialog the page shows is dismissed and reported, and
downloads are not available here. Only one viewer at a time: opening the same session elsewhere
moves it there, and the first view says "Opened elsewhere". A dropped connection reconnects by
itself; **Reconnect** tries again by hand.

Everything you do is recorded: the elements you clicked, what you typed, where you navigated.
**Passwords are never recorded**: a value typed into a password field is written down as a
reference to the program's secret input (`{{inputs.password}}`), never as the value.

## 3. Finish

| Button | What happens |
|---|---|
| **Continue the job from here** | The page as you left it becomes the job's new checkpoint and the job resumes from it. |
| **Abort the job** | The job is canceled. |
| **Close (leave it parked)** | The live browser goes away; the job stays parked, and you can take it over again. |

`POST /v1/jobs/{id}/resume` with `{ "continue": true }` does the same as **Continue the job from
here** from code.

After **Continue**, the rail says "The job continues" with a link to follow it, and lists the
proposals your takeover produced, each with a **Review** link.

## 4. What it teaches

On **Continue** your actions become proposals on the program version, never applied by themselves:

- an `insert_steps` proposal at the step that parked, with the steps you took, each element
  described by several locators so the next run finds it even if the page shifts a little;
- a `dismiss` proposal for each dialog you closed by hand, so the obstacle layer can close it next
  time (approve it with `remember: "site"`).

Review them in the panel's **Review** queue or through the
[proposals API](https://docs.kaab.ist/reference/api/proposals/list-proposals).

## Hosted takeovers

A [hosted resolve page](https://docs.kaab.ist/guides/hosted-resolve) can offer a takeover to your own end user. Their
live view is restricted to the page the job is on: no address bar, no tabs, no session export, and
the link lapses with the resolve page.

## Worked example

A shop at `https://shop.example.com` starts showing a dialog over its product pages that only an
unlabelled corner glyph closes, which no heuristic recognises:

1. A program that reads `https://shop.example.com/p/1` runs. The job parks `needs_attention` with
   the reason `obstacle`; **Attention** shows it under "Blocked by something on the page".
2. Press **Take over**. The live view shows the product page under the dialog, and the rail's notice
   says something covers the page.
3. Click the corner glyph. The dialog closes, and the price is visible.
4. Press **Continue the job from here**. The job succeeds, and the rail lists a `dismiss` proposal
   for the dialog and an `insert_steps` proposal with your click.
5. Approve the `dismiss` proposal in **Review** with **Remember for this site**: the next job on
   that site closes the dialog without parking.

## Pitfalls

- **Pressing Continue too early.** The job resumes from the page as you left it; if the step's
  expectation does not hold there, it parks again. Wait until the page shows what the step expects.
- **Sharing a live link widely.** Anyone with `live_url` can drive the browser until it expires.
  Send it to one person.
- **Leaving the view open and walking away.** A session nobody watches ends after about five
  minutes, and the job stays parked.
- **Expecting the fix to apply by itself.** Takeover steps are proposals; approve them, or the next
  run parks in the same place.

## Reference

- [Take over a job](https://docs.kaab.ist/reference/api/jobs/takeover-job), [resume a job](https://docs.kaab.ist/reference/api/jobs/resume-job)
- [List proposals](https://docs.kaab.ist/reference/api/proposals/list-proposals),
  [approve a proposal](https://docs.kaab.ist/reference/api/proposals/approve-proposal)
- [Attention reasons](https://docs.kaab.ist/reference/codes#attention-reasons)
- [Human-in-the-loop](https://docs.kaab.ist/concepts/human-in-the-loop)