cascade-ai 0.79.0 → 0.80.0

package/dist/index.js

@@ -11623,7 +11623,7 @@ function reconcilePrice(model, live) {
 }
 
 // src/constants.ts
-var CASCADE_VERSION = "0.79.0";
+var CASCADE_VERSION = "0.80.0";
 var CASCADE_CONFIG_DIR = ".cascade";
 var CASCADE_MD_FILE = "CASCADE.md";
 var CASCADE_IGNORE_FILE = ".cascadeignore";
@@ -34977,11 +34977,13 @@ async function discoverMcpTools(servers) {
 }
 
 // src/browser/lease.ts
+var HUMAN_ACTOR = "__human__";
+var HUMAN_IDLE_MS = 12e4;
 var LEASE_DEADLOCK_CEILING_MS = 3e5;
 var QUEUE_WAIT_MS = 18e4;
 var MAX_QUEUED = 8;
 var ACTION_HANDOFF_MS = 2e3;
-var ACTION_HANDOFF_POLL_MS = 25;
+var HANDBACK_RETRY_MS = 25;
 var BrowserLease = class {
   actor = null;
   session = null;
@@ -35000,6 +35002,51 @@ var BrowserLease = class {
    * took the slot may release it.
    */
   action = null;
+  /** Whether the current action slot represents activity by its holder. */
+  actionCountsAsHumanActivity = false;
+  /**
+   * The human action that has already consumed its one idle-deadline grace.
+   * A single wedged CDP request must not look like fresh activity every two
+   * minutes forever. The first deadline may yield to an event that began before
+   * it; a second deadline for that SAME event becomes a pending lapse instead.
+   */
+  idleGraceAction = null;
+  /** Release the human hold as soon as this overlong action finally unwinds. */
+  idleLapseAfterAction = null;
+  /**
+   * Everyone waiting for that slot, IN THE ORDER THEY ASKED.
+   *
+   * A queue rather than a poll, and the ordering is the whole reason for it.
+   * `acquireActionSlot` used to spin on a 25ms timer, which decides nothing
+   * about who goes first: each waiter checks on its own phase, so the one that
+   * asked SECOND can find the slot free a full poll ahead of the one that asked
+   * first. The person types one event per keypress — `{ kind: 'text', text }`
+   * carries a single character — so that reordering is not a theoretical
+   * unfairness, it is "passowrd" appearing in the box.
+   *
+   * The slot is handed straight from `endAction` to the head of this line while
+   * still synchronous, so nothing can slip in between the two, and a waiter
+   * that reaches the front never has to be told the slot is already taken.
+   */
+  actionQueue = [];
+  /** Lapses a human hold nobody is using. See `HUMAN_IDLE_MS`. */
+  humanTimer = null;
+  /**
+   * The person ASKED for the hold to end and it could not end yet.
+   *
+   * Kept as a request rather than only a retry timer, because the retry shares
+   * `humanTimer` with the idle deadline: an authorised event settling after the
+   * request would otherwise call `touch()`, re-arm that timer for a full idle
+   * interval, and quietly cancel a handback the person had already asked for.
+   * "Give it back" is not undone by activity that was already under way when
+   * they said it.
+   *
+   * Explicit requests ONLY. An idle expiry must never set this: a deadline that
+   * lands on the person's own in-flight event is evidence they were THERE, and
+   * recording it here made `touch()` bail afterwards, so the hold dropped the
+   * instant a fresh interaction finished. See `lapse()`.
+   */
+  handBackWanted = false;
   isRevoked;
   onChange;
   constructor(options = {}) {
@@ -35010,6 +35057,20 @@ var BrowserLease = class {
   get holderActor() {
     return this.actor;
   }
+  /** Whether a person, rather than the agent, is driving the page right now. */
+  get heldByHuman() {
+    return this.actor === HUMAN_ACTOR;
+  }
+  /**
+   * Whether THIS actor is the one holding the browser right now.
+   *
+   * For asking again after a wait. `acquire` is re-entrant for the holder, so
+   * "I was granted the lease" is a fact about the moment it was granted and
+   * says nothing about the moment the caller finally gets to act.
+   */
+  heldBy(actorId) {
+    return this.actor === actorId;
+  }
   get holderSession() {
     return this.session;
   }
@@ -35036,6 +35097,7 @@ var BrowserLease = class {
    * the same worker coming back for its next step must not queue behind itself.
    */
   async acquire(actorId, sessionId, signal) {
+    if (this.actor === HUMAN_ACTOR && actorId !== HUMAN_ACTOR) return "human";
     if (this.actor === null || this.actor === actorId) {
       this.actor = actorId;
       this.session = sessionId;
@@ -35076,6 +35138,105 @@ var BrowserLease = class {
     if (this.action) return;
     if (this.actor === actorId) this.release();
   }
+  /**
+   * Give the browser to the person watching it.
+   *
+   * Callers must have waited the in-flight action out first — see
+   * `acquireActionSlot`. This does not interrupt one, because it cannot: a
+   * Playwright call already inside the page finishes whatever it started, and
+   * taking the lease off it would only mean the person and a still-running
+   * `fill` were both touching the same form. Waiting is what makes "you have
+   * control" true when the UI says it.
+   *
+   * Every queued worker is turned away rather than left in line, for the same
+   * reason `acquire` refuses: they were planned against a page the person is
+   * about to change.
+   */
+  takeOver(sessionId) {
+    for (let i = this.waiting.length - 1; i >= 0; i--) this.waiting[i].settle("human");
+    this.clearCeiling();
+    this.actor = HUMAN_ACTOR;
+    this.session = sessionId;
+    this.touch();
+    this.onChange();
+  }
+  /**
+   * The person is still there — anything they did counts.
+   *
+   * Called per authorised input rather than on a heartbeat, so the hold is
+   * extended by USE and not merely by a tab being open. A left-open panel on a
+   * forgotten laptop stops holding a billed session two minutes later.
+   */
+  touch() {
+    if (this.actor !== HUMAN_ACTOR) return;
+    if (this.handBackWanted) return;
+    this.armIdle();
+  }
+  /** (Re)start the idle interval. The only place the deadline is set. */
+  armIdle() {
+    this.clearHumanIdle();
+    this.humanTimer = setTimeout(() => {
+      this.lapse();
+    }, HUMAN_IDLE_MS);
+    this.humanTimer.unref?.();
+  }
+  /**
+   * The idle deadline came round.
+   *
+   * Both ways a hold ends obey the same rule — never while one of the person's
+   * own events is still landing — but they resolve that clash in OPPOSITE
+   * directions, and routing the lapse through `handBack()` collapsed them into
+   * one. An event in flight BEGAN before this deadline, which makes it evidence
+   * the person was there; deferring the lapse and then releasing the moment
+   * that event lands ends the hold immediately after a fresh interaction, which
+   * is the precise opposite of what an idle deadline measures. So an
+   * interrupted lapse yields: the interval starts again, and the next silence
+   * decides.
+   *
+   * `handBack()` keeps the deferral instead, because "Give it back" is a
+   * decision and activity already under way when it was made does not withdraw
+   * it. Same rule, different answer, which is why they are different methods.
+   */
+  lapse() {
+    if (this.actor !== HUMAN_ACTOR) return;
+    if (this.action && this.actionCountsAsHumanActivity) {
+      if (this.idleGraceAction !== this.action) {
+        this.idleGraceAction = this.action;
+        this.armIdle();
+      } else {
+        this.idleLapseAfterAction = this.action;
+        this.clearHumanIdle();
+      }
+      return;
+    }
+    this.release();
+  }
+  /**
+   * The person hands the browser back, or their hold lapses.
+   *
+   * Answers whether there was a human hold to end, so a caller can tell a real
+   * handback from a duplicate click or a lapse that already happened.
+   */
+  handBack() {
+    if (this.actor !== HUMAN_ACTOR) return false;
+    if (this.action) {
+      this.handBackWanted = true;
+      this.clearHumanIdle();
+      this.humanTimer = setTimeout(() => {
+        this.handBack();
+      }, HANDBACK_RETRY_MS);
+      this.humanTimer.unref?.();
+      return false;
+    }
+    this.release();
+    return true;
+  }
+  clearHumanIdle() {
+    if (this.humanTimer) {
+      clearTimeout(this.humanTimer);
+      this.humanTimer = null;
+    }
+  }
   /** Drop every queued waiter belonging to a run, and the lease if it holds it. */
   dropRun(sessionId) {
     for (let i = this.waiting.length - 1; i >= 0; i--) {
@@ -35091,6 +35252,10 @@ var BrowserLease = class {
   /** Hand the browser to the next actor in line, if any. */
   release() {
     this.clearCeiling();
+    this.clearHumanIdle();
+    this.handBackWanted = false;
+    this.idleGraceAction = null;
+    this.idleLapseAfterAction = null;
     this.actor = null;
     this.session = null;
     let next = this.waiting.shift();
@@ -35119,33 +35284,111 @@ var BrowserLease = class {
       this.ceilingTimer = null;
     }
   }
-  /** Take the per-action slot, or null when one is already running. */
-  beginAction() {
+  /**
+   * Take the per-action slot, or null when one is already running.
+   *
+   * PRIVATE, so the queue is the only way in. A caller that could take the slot
+   * without joining the line would be exactly the jump-the-queue the ordering
+   * is there to prevent.
+   */
+  beginAction(countsAsHumanActivity = true) {
     if (this.action) return null;
     const token = /* @__PURE__ */ Symbol("browser-action");
     this.action = token;
+    this.actionCountsAsHumanActivity = countsAsHumanActivity;
     return token;
   }
-  /** Release the slot, but only for the action that took it. */
+  /**
+   * Release the slot, but only for the action that took it.
+   *
+   * Hands it to the head of the line rather than merely clearing it, and does
+   * so SYNCHRONOUSLY: the waiter's `beginAction` runs before this call returns,
+   * so there is no window in which the slot is free and somebody who asked
+   * later can take it.
+   */
   endAction(token) {
     if (this.action !== token) return false;
+    const lapseNow = this.actor === HUMAN_ACTOR && this.idleLapseAfterAction === token;
     this.action = null;
+    this.actionCountsAsHumanActivity = false;
+    if (this.idleGraceAction === token) this.idleGraceAction = null;
+    if (this.idleLapseAfterAction === token) this.idleLapseAfterAction = null;
+    if (lapseNow) this.release();
+    this.actionQueue.shift()?.();
     return true;
   }
   /**
-   * Wait, briefly, for an outgoing action to unwind.
+   * Take the slot only if it is free RIGHT NOW, never joining the line.
+   *
+   * For input that is a SAMPLE rather than a decision — pointer movement. A
+   * click or a keystroke is a thing the person meant to do and has to happen,
+   * so it waits its turn; a pointer position is one of many on the way
+   * somewhere, and one that cannot be applied now is worth less than the one
+   * behind it. Queueing them is actively harmful: on an endpoint slower than
+   * the client's sampling interval the backlog grows, and the click behind it
+   * can age out against `acquireActionSlot`'s bound and be refused — movement
+   * costing the person the action they actually intended.
+   *
+   * The queue length is checked as well as the slot, so a sample cannot step
+   * over a click that is already waiting.
+   */
+  tryActionSlot() {
+    if (this.action || this.actionQueue.length > 0) return null;
+    return this.beginAction();
+  }
+  /**
+   * Take the per-action slot, waiting in line for it if somebody has it.
    *
    * A release can hand the browser on while the previous holder's abort is
    * still propagating through an awaited navigation. That is a handoff, not a
-   * conflict, so it is waited out rather than refused — but bounded, because a
-   * wedged action must not pin the queue.
-   */
-  async awaitActionSlot() {
-    for (let waited = 0; waited < ACTION_HANDOFF_MS; waited += ACTION_HANDOFF_POLL_MS) {
-      if (!this.action) return true;
-      await new Promise((r) => setTimeout(r, ACTION_HANDOFF_POLL_MS));
-    }
-    return this.action === null;
+   * conflict, so it is normally bounded: a wedged action must not pin an agent
+   * or a takeover forever. Human discrete input is the exception and passes
+   * `null`: once a click, key or committed text has been accepted into this
+   * ordered queue, expiring it merely because earlier accepted input took more
+   * than two seconds silently truncates what the person typed.
+   *
+   * Waiting and TAKING are one step, which they deliberately were not before:
+   * the wait used to answer "the slot looks free" and leave the caller to call
+   * `beginAction` afterwards. Two callers woken by the same release both saw it
+   * free, and the loser was told "another action is already running" — a
+   * refusal for having asked first. Granting it here means whoever reaches the
+   * front of the line gets it, and everybody else is still waiting rather than
+   * refused.
+   *
+   * `null` as a RESULT means a bounded wait ran out OR a caller-supplied queue
+   * cap refused a new waiter. `null` as `withinMs` means an ACCEPTED operation
+   * is intentionally unbounded by time and will leave the queue only when its
+   * turn arrives; it does not require accepting infinitely many operations.
+   * `countsAsHumanActivity=false` is for
+   * lifecycle barriers: they still serialize, but an idle deadline must not
+   * mistake framework cleanup for evidence that the person is present.
+   */
+  async acquireActionSlot(withinMs = ACTION_HANDOFF_MS, countsAsHumanActivity = true, maxQueued = null) {
+    if (!this.action && this.actionQueue.length === 0) {
+      return this.beginAction(countsAsHumanActivity);
+    }
+    if (maxQueued !== null && this.actionQueue.length >= maxQueued) return null;
+    return await new Promise((resolve2) => {
+      let done = false;
+      let timer;
+      const wake = () => {
+        if (done) return;
+        done = true;
+        if (timer) clearTimeout(timer);
+        resolve2(this.beginAction(countsAsHumanActivity));
+      };
+      if (withinMs !== null) {
+        timer = setTimeout(() => {
+          if (done) return;
+          done = true;
+          const i = this.actionQueue.indexOf(wake);
+          if (i >= 0) this.actionQueue.splice(i, 1);
+          resolve2(null);
+        }, withinMs);
+        timer.unref?.();
+      }
+      this.actionQueue.push(wake);
+    });
   }
   /**
    * Queue one actor, resolving when it gets the browser or is turned away.
@@ -35180,7 +35423,28 @@ var BrowserLease = class {
 };
 
 // src/browser/remote/controller.ts
+var KEYS = {
+  Enter: { code: 13, text: "\r" },
+  Tab: { code: 9 },
+  Backspace: { code: 8 },
+  Delete: { code: 46 },
+  Escape: { code: 27 },
+  ArrowUp: { code: 38 },
+  ArrowDown: { code: 40 },
+  ArrowLeft: { code: 37 },
+  ArrowRight: { code: 39 },
+  Home: { code: 36 },
+  End: { code: 35 },
+  PageUp: { code: 33 },
+  PageDown: { code: 34 }
+};
+var BUTTONS = { left: 1, middle: 4, right: 2 };
+var SCREENCAST = { format: "jpeg", quality: 60, maxWidth: 1280, maxHeight: 800 };
 var ACTION_TIMEOUT_MS = 3e4;
+var RESTORE_FRAME_MS = 2e3;
+var MAX_HUMAN_INPUT_QUEUE = 64;
+var MAX_CAPTURE_TRANSITION_QUEUE = 16;
+var MAX_WATCH_LIFECYCLE_QUEUE = 16;
 var RemoteBrowserController = class {
   provider;
   maxSessions;
@@ -35193,6 +35457,17 @@ var RemoteBrowserController = class {
    * bearer capability for a browser somebody else is driving.
    */
   liveViewListeners = /* @__PURE__ */ new Map();
+  /**
+   * Told when a run's browser changes hands, or stops being pictured.
+   *
+   * Needed because a takeover can end without anybody asking. The hold lapses
+   * on its own after `HUMAN_IDLE_MS`, and a client left believing it still has
+   * control would keep sending input into a lease it no longer holds — every
+   * event refused, with nothing on screen saying why.
+   */
+  controlListeners = /* @__PURE__ */ new Map();
+  /** What each run's listener was last told, so unchanged states stay quiet. */
+  controlAnnounced = /* @__PURE__ */ new Map();
   /** An embedder that wants every run's live view, told which run each is. */
   onLiveViewAll;
   runs = /* @__PURE__ */ new Map();
@@ -35202,7 +35477,7 @@ var RemoteBrowserController = class {
    * Counted alongside `runs` against the cap. Without it the limit was a
    * check-then-act across four awaits, and simultaneous first uses both won.
    */
-  opening = /* @__PURE__ */ new Set();
+  opening = /* @__PURE__ */ new Map();
   /**
    * A run's stop signal, created when its slot is reserved.
    *
@@ -35235,7 +35510,7 @@ var RemoteBrowserController = class {
    * own teardown settles, so a later, genuine re-open of the same run id
    * never collides with one still in flight.
    */
-  closing = /* @__PURE__ */ new Set();
+  closing = /* @__PURE__ */ new Map();
   /** Runs the user has stopped, by run id — same meaning as on the desktop. */
   revoked = /* @__PURE__ */ new Set();
   /**
@@ -35253,11 +35528,38 @@ var RemoteBrowserController = class {
     const asked = Math.max(1, options.maxSessions ?? 1);
     this.maxSessions = options.provider.isolatesSessions ? asked : 1;
     this.onLiveViewAll = options.onLiveView;
+    this.ready = options.ready;
   }
+  /**
+   * The predecessor's teardown, until it has been waited for once.
+   *
+   * Cleared as soon as it settles so the wait is not re-entered on every open
+   * — and so the promise itself is not retained for the life of the process.
+   */
+  ready;
+  /**
+   * This controller has been retired and will never open anything again.
+   *
+   * Stronger than "its runs were ended", and it has to be. A caller parked on
+   * the `ready` gate above is invisible to `dispose()` — it holds no run and
+   * has reserved no slot, because it has not got that far — so a SECOND
+   * settings change, arriving while the first retirement is still settling,
+   * found nothing to wait for and let the newest controller start immediately.
+   * The parked caller then woke up on a controller nobody holds a reference to
+   * and allocated a session against the superseded configuration, with the
+   * newest controller free to allocate its own.
+   *
+   * Set synchronously at the top of `dispose`, so anything already waiting is
+   * excluded the moment retirement begins rather than when it finishes.
+   */
+  retired = false;
   leaseFor(runId) {
     let lease = this.leases.get(runId);
     if (!lease) {
-      lease = new BrowserLease({ isRevoked: (id) => this.revoked.has(id) });
+      lease = new BrowserLease({
+        isRevoked: (id) => this.revoked.has(id),
+        onChange: () => this.announceControl(runId)
+      });
       lease.setLifecycleReleaseWired(true);
       this.leases.set(runId, lease);
     }
@@ -35274,6 +35576,44 @@ var RemoteBrowserController = class {
   offLiveViewFor(runKey) {
     this.liveViewListeners.delete(runKey);
   }
+  onControlFor(runKey, listener) {
+    this.controlListeners.set(runKey, listener);
+  }
+  offControlFor(runKey) {
+    this.controlListeners.delete(runKey);
+    this.controlAnnounced.delete(runKey);
+  }
+  /**
+   * Say who has the browser, but only when the answer has changed.
+   *
+   * The lease reports every ownership change, and during ordinary work that is
+   * one per action as workers take it and give it back. None of those are
+   * interesting to a viewer — the agent had it before and has it now — and
+   * emitting them would put a socket message on every click the agent makes.
+   */
+  announceControl(runId, force = false) {
+    const listener = this.controlListeners.get(runId);
+    if (!listener) return;
+    const held = this.runs.get(runId);
+    const state = {
+      human: this.leases.get(runId)?.heldByHuman === true,
+      capturing: held?.capturing === true,
+      // A receipt vouches for a VIEW, so it stops meaning anything the moment
+      // there is no view. `stopWatching` clears the session without bumping the
+      // watch — deliberately, since replacing the consumer is what a new watch
+      // is about — so the receipt stayed matched across the whole detach and
+      // re-attach, which `beginWatching` performs on every reconnect and every
+      // return to a conversation. Announced `confirmed` through that window,
+      // the client mounted and FOCUSED the blind keyboard surface over a page
+      // no session was serving: keystrokes meant for the composer went to a
+      // remote page that could only refuse them.
+      confirmed: held?.screencast !== void 0 && held.watchGen !== void 0 && held.seenGen === held.watchGen
+    };
+    const key = `${state.human}:${state.capturing}:${state.confirmed}`;
+    if (!force && this.controlAnnounced.get(runId) === key) return;
+    this.controlAnnounced.set(runId, key);
+    listener(state);
+  }
   /**
    * Tell a run's listener what its browser situation is.
    *
@@ -35294,22 +35634,681 @@ var RemoteBrowserController = class {
    * allocated and billed until the whole run ended, for a run that has just
    * been stopped.
    */
-  async releaseIfIdle(runId) {
+  async releaseIfIdle(runId, releaseSlot) {
     const held = this.runs.get(runId);
-    if (!held) return;
+    if (!held) {
+      releaseSlot?.();
+      return;
+    }
     this.runs.delete(runId);
-    this.closing.add(runId);
-    await this.teardown(runId, held);
+    const teardown = this.teardown(runId, held);
+    releaseSlot?.();
+    await teardown;
   }
   /** Release every run's session. For when the deployment's config changes. */
   async dispose() {
-    const ids = /* @__PURE__ */ new Set([...this.runs.keys(), ...this.opening]);
+    this.retired = true;
+    const opening = [...this.opening.values()];
+    const ids = /* @__PURE__ */ new Set([...this.runs.keys(), ...this.opening.keys()]);
     await Promise.all([...ids].map((runId) => this.endRun(runId)));
+    await Promise.all(opening.map((open) => open.catch(() => {
+    })));
+    await Promise.all([...this.closing.values()].map((done) => done.catch(() => {
+    })));
   }
   /** A worker finished; it will never ask for the browser again. */
   actorEnded(actorId) {
     for (const lease of this.leases.values()) lease.actorEnded(actorId);
   }
+  /**
+   * Start streaming this run's page to whoever is watching it.
+   *
+   * Nothing streams until someone asks. That is the whole reason this is a
+   * method rather than something `open()` does: an unwatched run would
+   * otherwise pay to encode frames nobody sees, on every run, forever — and on
+   * a metered provider it would pay for the bandwidth too.
+   *
+   * Frames are ACKED after they are handed on, never before. Chrome sends the
+   * next frame only once the previous is acknowledged, so this bounds it to one
+   * outstanding frame against OUR OWN handling. It does not reach further than
+   * that, and an earlier version of this comment claimed it did: `onFrame` ends
+   * at a socket emit, which hands the JPEG to a transport rather than to a
+   * viewer, so the ack says nothing about what the person actually received.
+   * Bounding the rest of the path is the transport's job — see `emitFrame`,
+   * where frames go out lossy so a slow connection drops pictures instead of
+   * banking stale ones. Dropping the ack stops the stream dead, which is why it
+   * is best-effort but unconditional.
+   *
+   * Returns false when there is nothing to watch — the run has no browser, or
+   * it is already being watched. Callers use that to avoid promising a viewer
+   * a stream that will never arrive.
+   */
+  async startWatching(runId, onFrame) {
+    const held = this.runs.get(runId);
+    if (!held) return false;
+    return await this.queueWatch(held, async () => {
+      held.onFrame = onFrame;
+      held.watchGen = (held.watchGen ?? 0) + 1;
+      if (held.screencast) {
+        this.announceControl(runId);
+        return true;
+      }
+      const attached = await this.attachScreencast(runId, held, onFrame);
+      if (!attached && held.onFrame === onFrame) held.onFrame = void 0;
+      return attached !== null;
+    });
+  }
+  /**
+   * Run one watch or unwatch after every one already asked for.
+   *
+   * The chain is kept non-rejecting on purpose: a failed attach must not poison
+   * every later request for this run, which is what a bare `.then` chain would
+   * do. The caller still sees its own failure, because that is the promise
+   * returned rather than the one stored.
+   */
+  queueWatch(held, op) {
+    const depth = held.watchQueueDepth ?? 0;
+    if (held.watchCollapsedPromise || depth >= MAX_WATCH_LIFECYCLE_QUEUE) {
+      held.watchCollapsed = op;
+      if (!held.watchCollapsedPromise) {
+        const drain = async () => {
+          let result;
+          while (held.watchCollapsed) {
+            const latest = held.watchCollapsed;
+            held.watchCollapsed = void 0;
+            try {
+              result = await latest();
+            } catch {
+            }
+          }
+          return result;
+        };
+        const tail = (held.watchQueue ?? Promise.resolve()).then(drain, drain);
+        let tracked;
+        tracked = tail.finally(() => {
+          if (held.watchCollapsedPromise === tracked) {
+            held.watchCollapsedPromise = void 0;
+            held.watchCollapsed = void 0;
+          }
+        });
+        held.watchCollapsedPromise = tracked;
+        held.watchQueue = tracked.catch(() => {
+        });
+      }
+      return held.watchCollapsedPromise;
+    }
+    held.watchQueueDepth = depth + 1;
+    const mine = (held.watchQueue ?? Promise.resolve()).then(op, op);
+    const counted = mine.finally(() => {
+      held.watchQueueDepth = Math.max(0, (held.watchQueueDepth ?? 1) - 1);
+    });
+    held.watchQueue = counted.catch(() => {
+    });
+    return counted;
+  }
+  /**
+   * Attach at most one physical CDP screencast session at a time.
+   *
+   * `startWatching()` already serializes watcher lifecycle through `watchQueue`,
+   * but the agent's detached-hidden restore cannot join that queue: it holds the
+   * action slot, while an earlier unwatch may be waiting for exactly that slot.
+   * Sharing only the physical attach closes the two-session race without making
+   * watcher teardown and agent mutation wait on each other in a cycle.
+   *
+   * A real watcher claims `onFrame` immediately, before it waits for an attach
+   * already started by the agent. The lower-level attach never writes the sink,
+   * so finishing an older temporary attempt cannot overwrite a newer viewer.
+   */
+  async attachScreencast(runId, held, onFrame, popupDetachGen) {
+    const consumerIntent = onFrame && popupDetachGen !== void 0 ? popupDetachGen : void 0;
+    if (onFrame) held.onFrame = onFrame;
+    if (held.screencast && held.screencastPage === held.page) return held.screencast;
+    const targetPage = held.page;
+    const existing = held.attaching;
+    if (existing) {
+      const existingPage = held.attachingPage;
+      await existing.catch(() => null);
+      if (held.page !== targetPage || existingPage !== targetPage) {
+        return this.attachScreencast(runId, held, onFrame, popupDetachGen);
+      }
+      const cdp = held.screencastPage === targetPage ? held.screencast ?? null : null;
+      if (consumerIntent !== void 0 && (held.watchDetachGen ?? 0) !== consumerIntent) return null;
+      if (cdp && onFrame) held.onFrame = onFrame;
+      return cdp;
+    }
+    if (held.screencast && held.screencastPage !== targetPage) {
+      const stale = held.screencast;
+      held.screencast = void 0;
+      held.screencastPage = void 0;
+      await stale.send("Page.stopScreencast").catch(() => {
+      });
+      await stale.detach().catch(() => {
+      });
+    }
+    const attempt = this.attachScreencastFresh(runId, held, targetPage, consumerIntent);
+    held.attaching = attempt;
+    held.attachingPage = targetPage;
+    try {
+      const cdp = await attempt;
+      if (consumerIntent !== void 0 && (held.watchDetachGen ?? 0) !== consumerIntent) return null;
+      if (cdp && onFrame) held.onFrame = onFrame;
+      return cdp;
+    } finally {
+      if (held.attaching === attempt) {
+        held.attaching = void 0;
+        held.attachingPage = void 0;
+      }
+    }
+  }
+  /** Open one new CDP session and start the stream when it is safe to do so. */
+  async attachScreencastFresh(runId, held, targetPage, consumerIntent) {
+    const safetyGate = held.hiddenByHolder === true || held.visibilityUnconfirmed === true;
+    let cdp;
+    try {
+      cdp = await targetPage.context().newCDPSession(targetPage);
+    } catch {
+      if (!safetyGate) {
+        held.visibilityUnconfirmed = false;
+        held.capturing = true;
+        this.announceControl(runId);
+      }
+      return null;
+    }
+    if (held.page !== targetPage) {
+      await cdp.detach().catch(() => {
+      });
+      return null;
+    }
+    cdp.on("Page.screencastFrame", ((e) => {
+      if (held.page === targetPage && typeof e?.data === "string") {
+        const width = e.metadata?.deviceWidth ?? 0;
+        const height = e.metadata?.deviceHeight ?? 0;
+        held.metricsStale = true;
+        if (held.visibilityUnconfirmed) {
+          held.visibilityUnconfirmed = false;
+          if (held.capturing !== true) {
+            held.capturing = true;
+            this.announceControl(runId);
+          }
+        }
+        const ping = held.framePing;
+        held.framePing = void 0;
+        ping?.();
+        const deliver = held.onFrame;
+        if (deliver) {
+          deliver({ data: e.data, width, height, generation: held.watchGen ?? 0 });
+        }
+      }
+      void cdp.send("Page.screencastFrameAck", { sessionId: e?.sessionId }).catch(() => {
+      });
+    }));
+    const paused = held.hiddenByHolder === true;
+    if (!paused) {
+      try {
+        await cdp.send("Page.startScreencast", { ...SCREENCAST });
+      } catch {
+        if (!safetyGate) {
+          held.visibilityUnconfirmed = false;
+          held.capturing = true;
+          this.announceControl(runId);
+        } else {
+          held.capturing = false;
+          this.announceControl(runId);
+        }
+        await cdp.detach().catch(() => {
+        });
+        return null;
+      }
+    }
+    if (held.page !== targetPage) {
+      if (!paused) await cdp.send("Page.stopScreencast").catch(() => {
+      });
+      await cdp.detach().catch(() => {
+      });
+      return null;
+    }
+    if (consumerIntent !== void 0 && (held.watchDetachGen ?? 0) !== consumerIntent) {
+      if (!paused) await cdp.send("Page.stopScreencast").catch(() => {
+      });
+      await cdp.detach().catch(() => {
+      });
+      return null;
+    }
+    held.screencast = cdp;
+    held.screencastPage = targetPage;
+    held.capturing = !paused;
+    held.hiddenByHolder = paused;
+    this.announceControl(runId);
+    return cdp;
+  }
+  /** Nobody is watching any more: stop paying to render frames. */
+  async stopWatching(runId) {
+    const held = this.runs.get(runId);
+    if (!held) return;
+    held.watchDetachGen = (held.watchDetachGen ?? 0) + 1;
+    held.onFrame = void 0;
+    await this.queueWatch(held, async () => {
+      const cdp = held.screencast;
+      held.onFrame = void 0;
+      if (!cdp) return;
+      held.screencast = void 0;
+      held.screencastPage = void 0;
+      held.capturing = false;
+      this.announceControl(runId);
+      const lease = this.leases.get(runId);
+      const token = lease ? await lease.acquireActionSlot(null, false) : null;
+      if (lease && !token) return;
+      try {
+        await cdp.send("Page.stopScreencast").catch(() => {
+        });
+        await cdp.detach().catch(() => {
+        });
+      } finally {
+        if (token && lease) lease.endAction(token);
+      }
+    });
+  }
+  /**
+   * Suspend or resume the picture without giving up control.
+   *
+   * The credential case, and the only reason this is separate from watching. A
+   * person who has taken the page over to sign in is about to type a password
+   * into a field whose contents are echoed as dots — but a password manager's
+   * dropdown, a "show password" toggle, a one-time code in plain text and the
+   * confirmation page afterwards are not, and all of them would otherwise be
+   * encoded into frames and sent across the network.
+   *
+   * What this does NOT do is hide anything from the agent: it stops the
+   * picture, not the page. Nothing about a suspended capture would stop a
+   * `extract_text` from reading the same screen — it is the lease that stops
+   * that, by refusing the agent for as long as the person holds it.
+   *
+   * Answers whether frames are flowing afterwards, which is what a UI needs to
+   * show and is not always what was asked for: a run with nobody watching has
+   * no session to suspend.
+   */
+  async setCapture(runId, on) {
+    const held = this.runs.get(runId);
+    const cdp = held?.screencast;
+    const watch = held?.watchGen;
+    if (!held || !cdp) return false;
+    const lease = this.leaseFor(runId);
+    if (!on && !lease.heldByHuman) return held.capturing === true;
+    if (!on && (watch === void 0 || held.seenGen !== watch)) {
+      return held.capturing === true;
+    }
+    if (held.capturing === on) {
+      if (lease.heldByHuman) lease.touch();
+      return on;
+    }
+    const token = await lease.acquireActionSlot(null, true, MAX_CAPTURE_TRANSITION_QUEUE);
+    if (!token) return held.capturing === true;
+    try {
+      if (!on && !lease.heldByHuman) return held.capturing === true;
+      if (!on && (held.screencast !== cdp || held.watchGen !== watch)) {
+        return held.capturing === true;
+      }
+      if (!on && (watch === void 0 || held.seenGen !== watch)) {
+        return held.capturing === true;
+      }
+      const target = on ? held.screencast : cdp;
+      if (!target) {
+        if (on) {
+          held.hiddenByHolder = false;
+          if (lease.heldByHuman) lease.touch();
+        }
+        return held.capturing === true;
+      }
+      const now = await this.applyCapture(runId, held, target, on);
+      if (lease.heldByHuman) lease.touch();
+      return now;
+    } finally {
+      lease.endAction(token);
+    }
+  }
+  /**
+   * The capture transition itself, with no lease bookkeeping.
+   *
+   * Separate because the agent's restore in `act()` already holds the action
+   * slot — taking it again there would deadlock against itself, and the whole
+   * point of that call site is that it happens INSIDE the agent's turn.
+   *
+   * `confirmWithFrame` is used only by the agent's visibility gate. There, a
+   * successful CDP command is not enough: the externally visible state remains
+   * paused until a frame arrives, and the frame handler is the only code that
+   * promotes it to capturing. This makes a restore timeout sticky rather than
+   * a one-action refusal.
+   */
+  async applyCapture(runId, held, cdp, on, confirmWithFrame = false) {
+    if (held.capturing === on && !(on && confirmWithFrame && held.visibilityUnconfirmed)) return on;
+    const wasUnconfirmed = held.visibilityUnconfirmed === true;
+    const wasCapturing = held.capturing === true;
+    if (on) held.visibilityUnconfirmed = true;
+    try {
+      if (on) await cdp.send("Page.startScreencast", { ...SCREENCAST });
+      else await cdp.send("Page.stopScreencast");
+      if (on) {
+        if (!confirmWithFrame) held.capturing = true;
+      } else {
+        held.visibilityUnconfirmed = false;
+        held.capturing = false;
+      }
+      held.hiddenByHolder = !on;
+      this.announceControl(runId);
+    } catch {
+      if (on) {
+        held.visibilityUnconfirmed = wasUnconfirmed;
+        held.capturing = wasCapturing;
+        this.announceControl(runId);
+      }
+      return held.capturing === true && !held.visibilityUnconfirmed;
+    }
+    return on;
+  }
+  /**
+   * Wait, briefly, for Chrome to produce a frame.
+   *
+   * `Page.startScreencast` resolves when the command is accepted, which is not
+   * when a picture exists. The agent's visibility gate — "the page must be
+   * VISIBLE before anything changes it" — was therefore satisfied by a request
+   * rather than by a repaint, and the agent could click while the panel was
+   * still showing the page from before it was hidden, or nothing at all.
+   *
+   * A frame rather than a client receipt, deliberately. A receipt would prove
+   * somebody SAW it, which is stronger — and would make the agent's progress
+   * depend on a viewer that may not exist: this path runs after a handback or a
+   * lapse, when there may be nobody watching at all, and an agent that stalls
+   * because a tab was closed is a worse failure than the one being fixed. What
+   * this does guarantee is ours to guarantee: the stream is producing again.
+   *
+   * Bounded, and the bound rests on the property rounds 14 and 15 already rely
+   * on — a screencast that has just been started emits its first frame at once,
+   * whatever the page is doing. If one does not arrive, the picture genuinely
+   * has not come back, and the caller refuses on the same trade it already
+   * makes when the restore itself fails.
+   */
+  nextFrame(held, withinMs = RESTORE_FRAME_MS) {
+    return new Promise((resolve2) => {
+      const timer = setTimeout(() => {
+        if (held.framePing === ping) held.framePing = void 0;
+        resolve2(false);
+      }, withinMs);
+      timer.unref?.();
+      const ping = () => {
+        clearTimeout(timer);
+        resolve2(true);
+      };
+      held.framePing = ping;
+    });
+  }
+  /** Whether a person is driving this run's browser right now. */
+  humanHolds(runId) {
+    return this.leases.get(runId)?.heldByHuman === true;
+  }
+  /**
+   * Hand this run's browser to the person watching it.
+   *
+   * The wait is the substance. An agent action already inside Playwright cannot
+   * be interrupted — `click` waits for its element to become actionable and
+   * then clicks, whatever anyone decided in the meantime — so a takeover that
+   * returned immediately would put the person on a page an action was still
+   * about to change. Bounded by the action ceiling, because that is the longest
+   * an action can legitimately take; past it something is wedged, and saying so
+   * is better than a spinner that never resolves.
+   *
+   * Idempotent for someone who already holds it: a second click of Take control
+   * just says they are still there.
+   */
+  async takeOver(runId) {
+    if (this.revoked.has(runId)) {
+      return { ok: false, detail: "Browser control was stopped for this run." };
+    }
+    const requested = this.runs.get(runId);
+    if (!requested) {
+      return { ok: false, detail: "This run has no browser open." };
+    }
+    const requestedCdp = requested.screencast;
+    const requestedWatch = requested.watchGen;
+    if (!requestedCdp || requestedWatch === void 0 || !requested.onFrame) {
+      return { ok: false, detail: "This browser is not being watched right now." };
+    }
+    const lease = this.leaseFor(runId);
+    if (lease.heldByHuman) {
+      lease.touch();
+      this.announceControl(runId, true);
+      return { ok: true };
+    }
+    const token = await lease.acquireActionSlot(ACTION_TIMEOUT_MS);
+    if (!token) {
+      return {
+        ok: false,
+        detail: "The agent is still finishing an action on this page. Try again in a moment."
+      };
+    }
+    try {
+      const held = this.runs.get(runId);
+      if (this.revoked.has(runId)) {
+        return { ok: false, detail: "Browser control was stopped for this run." };
+      }
+      if (!held || held.page.isClosed()) {
+        return { ok: false, detail: "That browser closed while you were waiting for it." };
+      }
+      if (held.screencast !== requestedCdp || held.watchGen !== requestedWatch || !held.onFrame) {
+        return { ok: false, detail: "The browser view changed while you were waiting. Take control again from the current view." };
+      }
+      lease.takeOver(runId);
+    } finally {
+      lease.endAction(token);
+    }
+    return { ok: true };
+  }
+  /** The person is done. Answers whether they were holding it at all. */
+  /**
+   * The viewer confirms it received a picture of this run's page.
+   *
+   * Reliable, one per watch, and the only thing that opens Hide. Checked
+   * against the CURRENT watch: a receipt that names an older one is from a
+   * viewer that has since been replaced, and vouching for its successor is the
+   * reconnect hole this counter exists to close.
+   */
+  frameSeen(runId, generation) {
+    const held = this.runs.get(runId);
+    if (!held) return;
+    if (typeof generation !== "number" || !Number.isFinite(generation)) return;
+    if (held.watchGen === void 0 || generation !== held.watchGen) return;
+    if (held.seenGen === generation) return;
+    held.seenGen = generation;
+    this.announceControl(runId);
+  }
+  handBack(runId) {
+    return this.leases.get(runId)?.handBack() === true;
+  }
+  /**
+   * One thing the person did to the page.
+   *
+   * Authorised per event, not per session. A takeover is not a channel that
+   * stays open once opened: between two clicks the run can be stopped, the hold
+   * can lapse, the page can close, and each of those has to stop the NEXT
+   * event rather than be noticed at the end. So every event re-checks that this
+   * run is live and that the lease is still the person's, and every accepted
+   * event says so by extending the hold.
+   */
+  async input(runId, event) {
+    const held = this.runs.get(runId);
+    const cdp = held?.screencast;
+    const watch = held?.watchGen;
+    if (!held || held.page.isClosed()) return { ok: false, detail: "This run has no browser open." };
+    const page2 = held.page;
+    const pageGeneration = held.generation;
+    if (!cdp) return { ok: false, detail: "Nothing is streaming this browser, so it cannot be driven." };
+    const lease = this.leaseFor(runId);
+    if (!lease.heldByHuman) {
+      return { ok: false, detail: "You do not have control of this browser. Take control first." };
+    }
+    if (held.capturing !== true && (held.watchGen === void 0 || held.seenGen !== held.watchGen)) {
+      return { ok: false, detail: "Show the page before typing into it \u2014 this view has not seen it yet." };
+    }
+    const sampled = event.kind === "move";
+    const token = sampled ? lease.tryActionSlot() : await lease.acquireActionSlot(null, true, MAX_HUMAN_INPUT_QUEUE);
+    if (!token) {
+      if (sampled) return { ok: true };
+      return { ok: false, detail: "Too many browser inputs are already waiting. Let the page catch up, then try again." };
+    }
+    try {
+      if (!lease.heldByHuman) {
+        return { ok: false, detail: "Your control of this browser ended while that was waiting." };
+      }
+      if (held.page !== page2 || held.generation !== pageGeneration) {
+        return { ok: false, detail: "The page changed while that input was waiting, so it did not land." };
+      }
+      if (held.screencast !== cdp || held.watchGen !== watch) {
+        return { ok: false, detail: "The view you were driving is gone, so that did not land." };
+      }
+      const pagesBefore = new Set(held.page.context().pages());
+      await this.dispatch(cdp, held, event);
+      await this.followOpenedPage(runId, held, pagesBefore);
+    } catch (err) {
+      return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    } finally {
+      lease.endAction(token);
+    }
+    lease.touch();
+    return { ok: true };
+  }
+  /**
+   * The page's own coordinate space, measured rather than inferred.
+   *
+   * Cached, because a click should not cost a round trip, and invalidated by
+   * the frame metadata changing shape — which arrives free with every frame. A
+   * failed measurement falls back to the last good one rather than to a guess:
+   * a stale viewport is off by a resize, an invented one is off by anything.
+   */
+  async pageViewport(held, cdp) {
+    if (held.viewport && !held.metricsStale) return held.viewport;
+    try {
+      const metrics = await cdp.send("Page.getLayoutMetrics");
+      const width = metrics?.cssVisualViewport?.clientWidth;
+      const height = metrics?.cssVisualViewport?.clientHeight;
+      if (typeof width === "number" && typeof height === "number" && width > 0 && height > 0) {
+        held.viewport = { width, height };
+        held.metricsStale = false;
+        return held.viewport;
+      }
+    } catch {
+    }
+    return null;
+  }
+  /**
+   * Turn one authorised event into CDP calls. Coordinates arrive normalised.
+   *
+   * A switch with a default that REFUSES, rather than a chain of ifs ending in
+   * the click branch. This is a mutation boundary reached from a socket, so the
+   * question is not what a well-formed event does but what a malformed one
+   * does: the chain answered "clicks", which meant a version-skewed client
+   * sending `{ kind: 'drag', x, y }` pressed the mouse on a real page, and a
+   * kind with no coordinates at all clamped to 0 and clicked the top-left
+   * corner. Unknown input has to fail closed.
+   *
+   * The `never` in the default is the other half: adding a member to
+   * `BrowserInput` without handling it here stops compiling, so the next kind
+   * cannot silently inherit whatever the last branch happened to be.
+   */
+  async dispatch(cdp, held, event) {
+    switch (event.kind) {
+      case "text": {
+        if (typeof event.text !== "string") {
+          throw new Error("That is not text that can be typed into the page.");
+        }
+        const text = event.text.slice(0, 4e3);
+        if (!text) return;
+        await cdp.send("Input.insertText", { text });
+        return;
+      }
+      case "key": {
+        const modifiers = event.modifiers;
+        if (modifiers !== void 0) {
+          if (!Array.isArray(modifiers) || modifiers.some((m) => m !== "Control" && m !== "Meta" && m !== "Shift") || new Set(modifiers).size !== modifiers.length) {
+            throw new Error("That editing shortcut has invalid modifiers.");
+          }
+          const primary = modifiers.filter((m) => m === "Control" || m === "Meta");
+          const shifted = modifiers.includes("Shift");
+          if (primary.length !== 1) {
+            throw new Error("That editing shortcut cannot be sent to the page.");
+          }
+          const key = typeof event.key === "string" ? event.key : "";
+          const lower = key.toLowerCase();
+          const shortcut = lower === "a" && !shifted ? { key: "a", code: "KeyA", vk: 65 } : lower === "z" ? { key: "z", code: "KeyZ", vk: 90 } : lower === "y" && !shifted ? { key: "y", code: "KeyY", vk: 89 } : key === "Backspace" && !shifted ? { key: "Backspace", code: "Backspace", vk: 8 } : key === "Delete" && !shifted ? { key: "Delete", code: "Delete", vk: 46 } : void 0;
+          if (!shortcut) {
+            throw new Error(`That editing shortcut is not supported for the remote page: ${key}`);
+          }
+          const modifierBits = (primary[0] === "Control" ? 2 : 4) | (shifted ? 8 : 0);
+          const base2 = {
+            key: shortcut.key,
+            code: shortcut.code,
+            windowsVirtualKeyCode: shortcut.vk,
+            nativeVirtualKeyCode: shortcut.vk,
+            modifiers: modifierBits
+          };
+          await cdp.send("Input.dispatchKeyEvent", { ...base2, type: "rawKeyDown" });
+          await cdp.send("Input.dispatchKeyEvent", { ...base2, type: "keyUp" });
+          return;
+        }
+        const spec = typeof event.key === "string" && Object.hasOwn(KEYS, event.key) ? KEYS[event.key] : void 0;
+        if (!spec) throw new Error(`That key cannot be sent to the page: ${String(event.key)}`);
+        const base = {
+          key: event.key,
+          code: event.key,
+          windowsVirtualKeyCode: spec.code,
+          nativeVirtualKeyCode: spec.code,
+          ...spec.text ? { text: spec.text } : {}
+        };
+        await cdp.send("Input.dispatchKeyEvent", { ...base, type: spec.text ? "keyDown" : "rawKeyDown" });
+        await cdp.send("Input.dispatchKeyEvent", { ...base, type: "keyUp" });
+        return;
+      }
+      case "move":
+      case "scroll":
+      case "click": {
+        const view = await this.pageViewport(held, cdp);
+        if (!view) throw new Error("The page has not been measured yet, so a click cannot be placed on it.");
+        const x = coordinate(event.x, "horizontal position") * view.width;
+        const y = coordinate(event.y, "vertical position") * view.height;
+        if (event.kind === "move") {
+          await cdp.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y, button: "none", buttons: 0 });
+          return;
+        }
+        if (event.kind === "scroll") {
+          await cdp.send("Input.dispatchMouseEvent", {
+            type: "mouseWheel",
+            x,
+            y,
+            button: "none",
+            buttons: 0,
+            deltaX: 0,
+            deltaY: scrollDelta(event.deltaY)
+          });
+          return;
+        }
+        if (event.button !== void 0 && !Object.hasOwn(BUTTONS, event.button)) {
+          throw new Error(`That is not a mouse button: ${String(event.button)}`);
+        }
+        const button = event.button ?? "left";
+        const buttons = BUTTONS[button];
+        if (event.clicks !== void 0 && (typeof event.clicks !== "number" || !Number.isFinite(event.clicks))) {
+          throw new Error("That is not a number of clicks.");
+        }
+        const clickCount = Math.min(Math.max(Math.trunc(event.clicks ?? 1), 1), 3);
+        await cdp.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y, button: "none", buttons: 0 });
+        await cdp.send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button, buttons, clickCount });
+        await cdp.send("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button, buttons: 0, clickCount });
+        return;
+      }
+      default: {
+        const unknown = event;
+        throw new Error(`That is not something that can be done to the page: ${unknown?.kind ?? "an event with no kind"}`);
+      }
+    }
+  }
   /** The user stopped this run. Refuses further actions and clears its queue. */
   stopRun(runId) {
     this.revoked.add(runId);
@@ -35318,7 +36317,6 @@ var RemoteBrowserController = class {
     const held = this.runs.get(runId);
     if (!held) return;
     this.runs.delete(runId);
-    this.closing.add(runId);
     void this.teardown(runId, held);
   }
   /** A run ended: release its browser rather than pay for an idle session. */
@@ -35331,7 +36329,6 @@ var RemoteBrowserController = class {
       return;
     }
     this.runs.delete(runId);
-    this.closing.add(runId);
     await this.teardown(runId, held);
     this.forgetRun(runId);
   }
@@ -35341,6 +36338,7 @@ var RemoteBrowserController = class {
     this.leases.delete(runId);
     this.aborts.delete(runId);
     this.liveViewListeners.delete(runId);
+    this.offControlFor(runId);
   }
   /**
    * Let go of one run's browser.
@@ -35352,6 +36350,17 @@ var RemoteBrowserController = class {
   async disposeRun(runId, held) {
     held.abort.abort();
     this.announceLiveView(runId, void 0, false);
+    await held.watchQueue?.catch(() => {
+    });
+    const watching = held.screencast;
+    held.screencast = void 0;
+    held.screencastPage = void 0;
+    if (watching) {
+      await watching.send("Page.stopScreencast").catch(() => {
+      });
+      await watching.detach().catch(() => {
+      });
+    }
     await held.ownedContext?.close().catch(() => {
     });
     await held.browser.close().catch(() => {
@@ -35367,12 +36376,12 @@ var RemoteBrowserController = class {
    * guarantees the removal happens, success or failure, so a disposal that
    * throws cannot leave the slot counted against the pool forever.
    */
-  async teardown(runId, held) {
-    try {
-      await this.disposeRun(runId, held);
-    } finally {
+  teardown(runId, held) {
+    const done = this.disposeRun(runId, held).finally(() => {
       this.closing.delete(runId);
-    }
+    });
+    this.closing.set(runId, done);
+    return done;
   }
   async act(action, context) {
     const runId = context.sessionId;
@@ -35386,7 +36395,9 @@ var RemoteBrowserController = class {
     if (context.signal?.aborted) {
       return { ok: false, detail: "The run was cancelled." };
     }
-    const planned = this.runs.get(runId)?.generation ?? 0;
+    const plannedRun = this.runs.get(runId);
+    const planned = plannedRun?.generation ?? 0;
+    const recoveringClosedPage = plannedRun?.page.isClosed() === true;
     const lease_ = this.leaseFor(runId);
     const lease = await lease_.acquire(actor, runId, context.signal);
     if (lease !== "granted") {
@@ -35400,28 +36411,96 @@ var RemoteBrowserController = class {
       lease_.releaseIfHeldBy(actor);
       return { ok: false, detail: "The run was cancelled." };
     }
-    if (!await lease_.awaitActionSlot()) {
+    const token = await lease_.acquireActionSlot();
+    if (!token) {
       lease_.releaseIfHeldBy(actor);
       return { ok: false, detail: "Another browser action is still finishing. Try again." };
     }
-    const token = lease_.beginAction();
-    if (!token) {
-      return { ok: false, detail: "Another browser action is already running. Wait for it to finish." };
+    if (!lease_.heldBy(actor)) {
+      lease_.endAction(token);
+      return { ok: false, detail: refusal(lease_.heldByHuman ? "human" : "off") };
     }
+    let temporaryCapture;
     try {
       const held = await this.open(runId, context.signal);
       if (this.revoked.has(runId)) {
-        await this.releaseIfIdle(runId);
+        await this.releaseIfIdle(runId, () => lease_.endAction(token));
         return { ok: false, detail: "The user stopped browser control for this run." };
       }
       if (context.signal?.aborted || held.abort.signal.aborted) {
-        await this.releaseIfIdle(runId);
+        await this.releaseIfIdle(runId, () => lease_.endAction(token));
         return { ok: false, detail: "The run was cancelled." };
       }
-      return await this.perform(held, action, planned);
+      if ((held.hiddenByHolder === true || held.visibilityUnconfirmed === true) && !held.screencast) {
+        const watchGen = held.watchGen;
+        let cdp = null;
+        try {
+          cdp = await this.attachScreencast(runId, held);
+        } catch {
+        }
+        if (!cdp) {
+          return {
+            ok: false,
+            detail: "The page could not be shown again, so nothing was done to it."
+          };
+        }
+        if (held.onFrame === void 0 && held.watchGen === watchGen) {
+          temporaryCapture = { held, cdp, watchGen };
+        }
+      }
+      if (held.screencast && (held.capturing === false || held.visibilityUnconfirmed === true)) {
+        const cdp = held.screencast;
+        if (held.capturing === true) {
+          await cdp.send("Page.stopScreencast").catch(() => {
+          });
+          held.capturing = false;
+          this.announceControl(runId);
+        }
+        const drawn = this.nextFrame(held);
+        if (!await this.applyCapture(runId, held, cdp, true, true)) {
+          return {
+            ok: false,
+            detail: "The page could not be shown again, so nothing was done to it."
+          };
+        }
+        if (!await drawn) {
+          held.visibilityUnconfirmed = true;
+          held.capturing = false;
+          await cdp.send("Page.stopScreencast").catch(() => {
+          });
+          this.announceControl(runId);
+          return {
+            ok: false,
+            detail: "The page did not come back on screen, so nothing was done to it."
+          };
+        }
+        if (this.revoked.has(runId)) {
+          await this.releaseIfIdle(runId, () => lease_.endAction(token));
+          return { ok: false, detail: "The user stopped browser control for this run." };
+        }
+        if (context.signal?.aborted || held.abort.signal.aborted) {
+          await this.releaseIfIdle(runId, () => lease_.endAction(token));
+          return { ok: false, detail: "The run was cancelled." };
+        }
+      }
+      return await this.perform(runId, held, action, recoveringClosedPage ? held.generation : planned);
     } catch (err) {
       return { ok: false, detail: err instanceof Error ? err.message : String(err) };
     } finally {
+      if (temporaryCapture) {
+        const { held, cdp, watchGen } = temporaryCapture;
+        if (held.screencast === cdp && held.onFrame === void 0 && held.watchGen === watchGen && held.hiddenByHolder === false && held.visibilityUnconfirmed === false && held.capturing === true) {
+          held.onFrame = void 0;
+          held.screencast = void 0;
+          held.screencastPage = void 0;
+          held.capturing = true;
+          this.announceControl(runId);
+          await cdp.send("Page.stopScreencast").catch(() => {
+          });
+          await cdp.detach().catch(() => {
+          });
+        }
+      }
       lease_.endAction(token);
       if (context.signal?.aborted || this.revoked.has(runId)) lease_.releaseIfHeldBy(actor);
     }
@@ -35437,22 +36516,40 @@ var RemoteBrowserController = class {
    * it out changed no test. Two copies of a cap invite them to disagree.
    */
   async open(runId, signal) {
+    if (this.ready) {
+      const settling = this.ready;
+      try {
+        await settling;
+      } catch {
+      }
+      if (this.ready === settling) this.ready = void 0;
+    }
     const existing = this.runs.get(runId);
     if (existing && !existing.page.isClosed()) return existing;
+    if (existing && existing.page.isClosed()) {
+      const fallback = existing.page.context().pages().filter((p) => !p.isClosed()).at(-1);
+      if (fallback) {
+        await this.adoptPage(runId, existing, fallback);
+        return existing;
+      }
+    }
     if (existing) {
       this.runs.delete(runId);
-      this.closing.add(runId);
       await this.teardown(runId, existing);
     }
+    if (this.retired) {
+      throw new Error("The browser settings changed while this action was waiting. Try again.");
+    }
     if (this.runs.size + this.opening.size + this.closing.size >= this.maxSessions) {
       throw new Error(
         `All ${this.maxSessions} browser session${this.maxSessions === 1 ? "" : "s"} are in use by other runs. Try again when one finishes, or raise the session limit in settings.`
       );
     }
-    this.opening.add(runId);
     if (!this.aborts.has(runId)) this.aborts.set(runId, new AbortController());
+    const opening = this.openReserved(runId, signal);
+    this.opening.set(runId, opening);
     try {
-      return await this.openReserved(runId, signal);
+      return await opening;
     } finally {
       this.opening.delete(runId);
     }
@@ -35463,9 +36560,9 @@ var RemoteBrowserController = class {
     const abort = this.aborts.get(runId)?.signal;
     const creationSignal = signal && abort ? AbortSignal.any([signal, abort]) : signal ?? abort;
     const session = await this.provider.createSession(creationSignal);
-    this.announceLiveView(runId, session.liveViewUrl, true);
     let browser;
     let owned;
+    let held;
     try {
       browser = await playwright.chromium.connectOverCDP(session.cdpUrl);
       owned = this.provider.isolatesSessions ? void 0 : await browser.newContext();
@@ -35473,15 +36570,10 @@ var RemoteBrowserController = class {
       const page2 = owned ? await owned.newPage() : context.pages()[0] ?? await context.newPage();
       const abort2 = this.aborts.get(runId);
       if (!abort2) throw new Error("The run ended while its browser was still opening.");
-      const held = { session, browser, page: page2, generation: 0, abort: abort2, ...owned ? { ownedContext: owned } : {} };
-      page2.on("framenavigated", ((frame) => {
-        if (frame !== page2.mainFrame()) return;
-        held.generation += 1;
-      }));
+      held = { session, browser, page: page2, generation: 0, abort: abort2, ...owned ? { ownedContext: owned } : {} };
+      this.trackPageNavigation(runId, held, page2);
       this.runs.set(runId, held);
-      return held;
     } catch (err) {
-      this.announceLiveView(runId, void 0, false);
       await owned?.close().catch(() => {
       });
       await browser?.close().catch(() => {
@@ -35490,8 +36582,74 @@ var RemoteBrowserController = class {
       });
       throw err;
     }
+    this.announceLiveView(runId, session.liveViewUrl, true);
+    return held;
+  }
+  /** Count main-frame navigation only while this page is the run's active page. */
+  trackPageNavigation(runId, held, page2) {
+    page2.on("framenavigated", ((frame) => {
+      if (held.page !== page2 || frame !== page2.mainFrame()) return;
+      held.generation += 1;
+      if (held.onFrame && held.watchGen !== void 0) {
+        held.watchGen += 1;
+        this.announceControl(runId);
+      }
+    }));
+  }
+  /**
+   * Follow a page opened by the action that just finished.
+   *
+   * A popup/new tab is part of the same user gesture (OAuth is the common
+   * example). Keeping `held.page` and the screencast on its opener makes the
+   * new page both invisible and impossible to drive. This runs while the SAME
+   * action slot is still held, after the opening click/key has fully landed, so
+   * no later human/agent event can slip between detecting the popup and moving
+   * the view to it.
+   */
+  async followOpenedPage(runId, held, before) {
+    if (this.runs.get(runId) !== held || held.abort.signal.aborted) return;
+    const candidates = held.page.context().pages().filter((p) => !p.isClosed() && !before.has(p));
+    const next = candidates.at(-1);
+    if (!next || next === held.page) return;
+    await this.adoptPage(runId, held, next);
+  }
+  /**
+   * Make one live page the run's controlled/viewed page. Used in both
+   * directions: into a popup opened by an action, and back to another surviving
+   * page when that popup closes itself after OAuth/login completion.
+   */
+  async adoptPage(runId, held, next) {
+    if (next === held.page || next.isClosed()) return;
+    held.page = next;
+    held.generation += 1;
+    held.viewport = void 0;
+    held.metricsStale = true;
+    this.trackPageNavigation(runId, held, next);
+    const deliver = held.onFrame;
+    if (deliver) {
+      held.watchGen = (held.watchGen ?? 0) + 1;
+      held.visibilityUnconfirmed = true;
+      held.capturing = false;
+      this.announceControl(runId);
+      await this.attachScreencast(runId, held, deliver, held.watchDetachGen ?? 0);
+      return;
+    }
+    const pending = held.attaching;
+    if (pending) await pending.catch(() => null);
+    if (held.screencast && held.screencastPage !== next) {
+      const stale = held.screencast;
+      held.screencast = void 0;
+      held.screencastPage = void 0;
+      await stale.send("Page.stopScreencast").catch(() => {
+      });
+      await stale.detach().catch(() => {
+      });
+    }
+    held.visibilityUnconfirmed = false;
+    held.capturing = held.hiddenByHolder !== true;
+    this.announceControl(runId);
   }
-  async perform(held, action, planned) {
+  async perform(runId, held, action, planned) {
     const { page: page2 } = held;
     const stoppable = async (work) => {
       if (held.abort.signal.aborted) throw new Error("The user stopped browser control for this run.");
@@ -35513,10 +36671,10 @@ var RemoteBrowserController = class {
       }
     };
     const timeout = Math.min(action.timeoutMs ?? 1e4, ACTION_TIMEOUT_MS);
-    const where = async () => ({
-      url: page2.url(),
-      title: await page2.title().catch(() => "")
-    });
+    const where = async () => {
+      const current = held.page;
+      return { url: current.url(), title: await current.title().catch(() => "") };
+    };
     if (action.kind !== "navigate" && held.generation !== planned) {
       return {
         ok: false,
@@ -35533,15 +36691,20 @@ var RemoteBrowserController = class {
         await stoppable(page2.goto(target, { timeout: ACTION_TIMEOUT_MS, waitUntil: "domcontentloaded" }));
         return { ok: true, detail: `Opened ${target}`, ...await where() };
       }
-      case "click":
+      case "click": {
+        const pagesBefore = new Set(page2.context().pages());
         await stoppable(page2.click(action.selector, { timeout }));
+        await this.followOpenedPage(runId, held, pagesBefore);
         return { ok: true, detail: `Clicked ${action.selector}`, ...await where() };
+      }
       case "fill":
         await stoppable(page2.fill(action.selector, action.value ?? "", { timeout }));
         return { ok: true, detail: `Filled ${action.selector}`, ...await where() };
       case "press": {
+        const pagesBefore = new Set(page2.context().pages());
         if (action.selector) await stoppable(page2.press(action.selector, action.key, { timeout }));
         else await stoppable(page2.keyboard.press(action.key));
+        await this.followOpenedPage(runId, held, pagesBefore);
         return { ok: true, detail: `Pressed ${action.key}`, ...await where() };
       }
       case "wait_for":
@@ -35557,10 +36720,25 @@ var RemoteBrowserController = class {
   }
 };
 function refusal(result) {
+  if (result === "human") {
+    return "The user has taken control of this browser. Stop using it and tell them what you were about to do.";
+  }
   if (result === "off") return "Browser control was turned off while this action waited for the browser.";
   if (result === "cancelled") return "The run was cancelled while waiting for the browser.";
   return "The browser is in use by another part of this run and did not come free in time. Try again, or do something else first.";
 }
+function coordinate(n, what) {
+  if (typeof n !== "number" || !Number.isFinite(n)) {
+    throw new Error(`That ${what} is not a position on the page.`);
+  }
+  return Math.min(Math.max(n, 0), 1);
+}
+function scrollDelta(n) {
+  if (typeof n !== "number" || !Number.isFinite(n)) {
+    throw new Error("That scroll has no distance to travel.");
+  }
+  return Math.min(Math.max(n, -2e3), 2e3);
+}
 async function loadPlaywright() {
   try {
     return await import('playwright');