cascade-ai 0.79.0 → 0.81.0

package/dist/index.cjs

@@ -11669,7 +11669,7 @@ function reconcilePrice(model, live) {
 }
 
 // src/constants.ts
-var CASCADE_VERSION = "0.79.0";
+var CASCADE_VERSION = "0.81.0";
 var CASCADE_CONFIG_DIR = ".cascade";
 var CASCADE_MD_FILE = "CASCADE.md";
 var CASCADE_IGNORE_FILE = ".cascadeignore";
@@ -30907,8 +30907,95 @@ function requiredFieldFor(kind, input) {
   }
 }
 
+// src/tools/ask-user.ts
+var MAX_QUESTIONS = 5;
+var MAX_OPTIONS = 6;
+var AskUserTool = class extends BaseTool {
+  name = "ask_user";
+  description = "Ask the person a short questionnaire when their request is genuinely ambiguous, instead of guessing. Use it when two readings of the request would produce materially different work \u2014 which account, which date range, whether to include drafts \u2014 and NOT for anything you can settle yourself or from the conversation. Ask everything you need in ONE call: several questions together read as a form, the same questions one per turn read as an interrogation. You may get no answer (nobody is watching, or they did not reply); if so, proceed on your best reading and say which assumption you made.";
+  inputSchema = {
+    type: "object",
+    properties: {
+      questions: {
+        type: "array",
+        minItems: 1,
+        maxItems: MAX_QUESTIONS,
+        description: `The questions to ask together (at most ${MAX_QUESTIONS}).`,
+        items: {
+          type: "object",
+          properties: {
+            prompt: { type: "string", description: "The question, as you would say it to them." },
+            kind: {
+              type: "string",
+              enum: ["choice", "multi", "text"],
+              description: "choice = pick one, multi = pick any that apply, text = free-form answer."
+            },
+            options: {
+              type: "array",
+              items: { type: "string" },
+              description: `The answers to offer, for choice and multi (at most ${MAX_OPTIONS}). Omit for text.`
+            }
+          },
+          required: ["prompt", "kind"]
+        }
+      }
+    },
+    required: ["questions"]
+  };
+  ask;
+  constructor(ask) {
+    super();
+    this.ask = ask;
+  }
+  // Asking a question changes nothing, so it needs no approval gate: a prompt
+  // asking permission to show a prompt is a tax on the behaviour we want.
+  isDangerous() {
+    return false;
+  }
+  async execute(input, options) {
+    const raw = Array.isArray(input["questions"]) ? input["questions"] : [];
+    const questions = [];
+    for (const [i, q] of raw.slice(0, MAX_QUESTIONS).entries()) {
+      const item = q ?? {};
+      const prompt = typeof item["prompt"] === "string" ? item["prompt"].trim() : "";
+      if (!prompt) continue;
+      const kind = item["kind"] === "multi" || item["kind"] === "text" ? item["kind"] : "choice";
+      const options_ = Array.isArray(item["options"]) ? item["options"].filter((o) => typeof o === "string" && o.trim() !== "").slice(0, MAX_OPTIONS) : [];
+      const resolved = kind !== "text" && options_.length < 2 ? "text" : kind;
+      questions.push({
+        // Positional, and assigned HERE. Letting the model supply ids invites
+        // two questions sharing one, and the second answer would overwrite the
+        // first with nothing to say it had.
+        id: `q${i + 1}`,
+        prompt,
+        kind: resolved,
+        ...resolved === "text" ? {} : { options: options_ }
+      });
+    }
+    if (questions.length === 0) {
+      return "Error: ask_user needs at least one question with a prompt.";
+    }
+    const result = await this.ask(questions, options.signal);
+    if (result.outcome !== "answered" || result.answers.length === 0) {
+      const why = result.outcome === "no-listener" ? "There is nobody watching this run to answer" : result.outcome === "aborted" ? "The run was stopped while the question was open" : result.outcome === "answered" ? "They saw the questions and chose not to answer" : "They did not answer in time";
+      return `${why}. Proceed on your best reading of the request, and say plainly which assumption you made.`;
+    }
+    const byId = new Map(result.answers.map((a) => [a.id, a.value]));
+    const lines = questions.map((q) => {
+      const value = byId.get(q.id);
+      const said = Array.isArray(value) ? value.join(", ") : value;
+      return `${q.prompt}
+  \u2192 ${said && said.length > 0 ? said : "(no answer given)"}`;
+    });
+    return `They answered:
+
+${lines.join("\n\n")}`;
+  }
+};
+
 // src/core/cascade.ts
 var ESCALATION_DECISION_TIMEOUT_MS = 5 * 6e4;
+var CLARIFICATION_TIMEOUT_MS = 2 * 6e4;
 function buildContextualPrompt(prompt, history = []) {
   const recent = history.slice(-6);
   if (recent.length === 0) return prompt;
@@ -31187,6 +31274,112 @@ var Cascade = class _Cascade extends EventEmitter__default.default {
   // timeout. Same class of bug as the twelve-failover dead-model race: a wave
   // is concurrent, so per-run singletons are never safe inside it.
   pendingEscalations = /* @__PURE__ */ new Map();
+  /**
+   * Questionnaires waiting on a person, keyed by request id.
+   *
+   * Exactly the shape `pendingEscalations` uses, and for the same reason: the
+   * answer, the timeout and the abort all race, and one settle path guarded by
+   * the map delete is what makes the first of them win.
+   */
+  pendingClarifications = /* @__PURE__ */ new Map();
+  /**
+   * Put a gate's opening question to its listeners, and NOTICE when one fails.
+   *
+   * `emit` cannot do this job. It calls listeners synchronously and discards
+   * what they return, so an `async` listener — the ordinary shape for anything
+   * that has to reach a socket or a UI — does not fail in a way `emit` reports:
+   * it returns a REJECTED PROMISE that nobody is holding. The `try` around the
+   * emit sees nothing, the gate is never told delivery failed, and it parks for
+   * its full timeout while Node raises an unhandled rejection that can take the
+   * process down.
+   *
+   * `onFailed` is called for either shape, and it is safe to call more than
+   * once: both gates route it to `settle`, which is guarded by a map delete, so
+   * the first failure wins and the rest are no-ops.
+   *
+   * PER LISTENER, not around the loop. `emit` stops dispatching at the first
+   * throw, so one broken host used to cost a working one its notification —
+   * the same reason `announceLiveView` delivers its two listeners separately.
+   * A synchronous failure settles the gate once the whole snapshot has been
+   * delivered; an asynchronous one settles it when the rejection arrives, which
+   * is still far better than the window-long park it replaces.
+   *
+   * SETTLED AFTER THE LOOP, not inside it, and that is not tidiness. `onFailed`
+   * settles the gate, and settling emits the gate's CLOSURE — so failing
+   * mid-dispatch announced "this request is over" and then went on handing the
+   * OPENING event to the listeners after it. A host later in the list would
+   * draw a form whose only closure notification had already gone past, and it
+   * would stand there forever. Deliver to everyone, then decide.
+   *
+   * `rawListeners`, NOT `listeners`. Bypassing `emit` means taking on what
+   * `emit` was doing, and `once` is the part that bites: `listeners()` hands
+   * back the UNWRAPPED callback, so calling it never runs the wrapper that
+   * deregisters it. A host that asked to be told once would be told every
+   * time — and told through a transport it had set up for one gate only.
+   * `rawListeners()` returns the wrapper, which removes the registration and
+   * passes the underlying listener's return value straight through, so the
+   * promise below is still the one being observed. Verified against Node.
+   *
+   * `.call(this, …)`, which is the third thing `emit` was doing. EventEmitter
+   * invokes listeners with the emitter as the receiver, so
+   * `function () { this.resolveClarification(...) }` is a legitimate host — and
+   * calling it bare gave it `this === undefined`, which throws, which this
+   * would then have read as the host failing to receive the question and
+   * settled the gate unanswered. A working listener turned into a delivery
+   * failure by the thing delivering it.
+   */
+  deliverGate(event, payload, onFailed) {
+    let delivered = false;
+    let threw = false;
+    const pending = [];
+    for (const listener of this.rawListeners(event)) {
+      try {
+        const out = listener.call(this, payload);
+        if (out && typeof out.then === "function") {
+          pending.push(Promise.resolve(out).then(() => true, () => false));
+        } else {
+          delivered = true;
+        }
+      } catch {
+        threw = true;
+      }
+    }
+    if (delivered) return;
+    if (pending.length === 0) {
+      if (threw) onFailed();
+      return;
+    }
+    void Promise.all(pending).then((results) => {
+      if (!results.some(Boolean)) onFailed();
+    });
+  }
+  /**
+   * Tell listeners something that is over, and let none of them make it worse.
+   *
+   * The closing half of the gate family — `clarification:closed`,
+   * `clarification:timeout`, `escalation:closed`, `escalation:timeout`. Each
+   * was already wrapped in a `try` for the synchronous case, and each had the
+   * same hole `deliverGate` had before last round: `emit` discards what a
+   * listener returns, so an `async` host fails by returning a rejected promise
+   * nobody is holding and Node raises an unhandled rejection.
+   *
+   * There is nothing to settle here — the gate is already closed, which is the
+   * whole message — so unlike `deliverGate` this reports to no one. It exists
+   * so that the four informational emits cannot take the process down, and so
+   * the rule is written once rather than four times.
+   */
+  announceGateClosed(event, payload) {
+    for (const listener of this.rawListeners(event)) {
+      try {
+        const out = listener.call(this, payload);
+        if (out && typeof out.then === "function") {
+          void Promise.resolve(out).catch(() => {
+          });
+        }
+      } catch {
+      }
+    }
+  }
   async requestEscalationDecision(ctx, taskId, signal) {
     if (this.config.autonomy === "auto") return { action: "skip", automatic: true };
     if (this.listenerCount("escalation:decision-required") === 0) return { action: "skip", automatic: true };
@@ -31199,23 +31392,28 @@ var Cascade = class _Cascade extends EventEmitter__default.default {
         if (timeout) clearTimeout(timeout);
         signal?.removeEventListener("abort", onAbort);
         resolve2(decision);
+        this.announceGateClosed("escalation:closed", { taskId, requestId, sectionId: ctx.sectionId });
       };
       const onAbort = () => settle({ action: "skip", automatic: true });
       signal?.addEventListener("abort", onAbort, { once: true });
       timeout = setTimeout(() => {
-        this.emit("escalation:timeout", { taskId, requestId, sectionId: ctx.sectionId });
         settle({ action: "timeout" });
+        this.announceGateClosed("escalation:timeout", { taskId, requestId, sectionId: ctx.sectionId });
       }, ESCALATION_DECISION_TIMEOUT_MS);
       this.pendingEscalations.set(requestId, settle);
-      this.emit("escalation:decision-required", {
-        taskId,
-        requestId,
-        sectionId: ctx.sectionId,
-        sectionTitle: ctx.sectionTitle,
-        issues: ctx.issues,
-        summary: ctx.summary,
-        timeoutMs: ESCALATION_DECISION_TIMEOUT_MS
-      });
+      this.deliverGate(
+        "escalation:decision-required",
+        {
+          taskId,
+          requestId,
+          sectionId: ctx.sectionId,
+          sectionTitle: ctx.sectionTitle,
+          issues: ctx.issues,
+          summary: ctx.summary,
+          timeoutMs: ESCALATION_DECISION_TIMEOUT_MS
+        },
+        () => settle({ action: "skip", automatic: true })
+      );
     });
   }
   /**
@@ -31252,6 +31450,73 @@ var Cascade = class _Cascade extends EventEmitter__default.default {
   releasePendingEscalations(action = "skip") {
     for (const settle of Array.from(this.pendingEscalations.values())) settle({ action, automatic: true });
   }
+  // ── Clarification: asking instead of assuming ───────────────────────
+  // The same gate shape as the escalation above, and for the same reasons. The
+  // difference that matters: an unanswered escalation SKIPS a section, while an
+  // unanswered question just means the model proceeds on its own reading — so
+  // every non-answer here is benign, and none of them may park the run.
+  /**
+   * Put a questionnaire to whoever is watching, if anybody is.
+   *
+   * Returns `no-listener` rather than waiting when there is nothing attached to
+   * answer — a scheduled run, an API caller with no socket, an autonomous run
+   * that has already said it wants no prompts. That check is the whole reason
+   * this can be offered to the model at all: a tool that might hang a headless
+   * run forever is a tool that cannot be registered.
+   */
+  async askUser(questions, signal) {
+    const none = (outcome) => ({ outcome, answers: [] });
+    if (this.unattended) return none("no-listener");
+    if (this.config.autonomy === "auto") return none("no-listener");
+    if (this.listenerCount("clarification:required") === 0) return none("no-listener");
+    if (signal?.aborted) return none("aborted");
+    const requestId = crypto.randomUUID();
+    return await new Promise((resolve2) => {
+      let timeout;
+      const settle = (result) => {
+        if (!this.pendingClarifications.delete(requestId)) return;
+        if (timeout) clearTimeout(timeout);
+        signal?.removeEventListener("abort", onAbort);
+        resolve2(result);
+        this.announceGateClosed("clarification:closed", { requestId });
+      };
+      const onAbort = () => settle(none("aborted"));
+      signal?.addEventListener("abort", onAbort, { once: true });
+      timeout = setTimeout(() => {
+        settle(none("timeout"));
+        this.announceGateClosed("clarification:timeout", { requestId });
+      }, CLARIFICATION_TIMEOUT_MS);
+      this.pendingClarifications.set(requestId, settle);
+      this.deliverGate(
+        "clarification:required",
+        { requestId, questions, timeoutMs: CLARIFICATION_TIMEOUT_MS },
+        () => settle(none("no-listener"))
+      );
+    });
+  }
+  /**
+   * Answer a questionnaire from a REPL / dashboard / cloud listener.
+   *
+   * `requestId` comes back on the `clarification:required` event and is what
+   * makes an answer land on the question that asked. Optional for a host with
+   * only one in flight, matching `resolveEscalation`: without it the oldest
+   * outstanding request is answered, which is correct whenever there is one.
+   */
+  resolveClarification(answers, requestId) {
+    const result = { outcome: "answered", answers };
+    if (requestId) {
+      this.pendingClarifications.get(requestId)?.(result);
+      return;
+    }
+    const oldest = this.pendingClarifications.keys().next();
+    if (!oldest.done) this.pendingClarifications.get(oldest.value)?.(result);
+  }
+  /** Release every parked questionnaire — run teardown, so none outlive the run. */
+  releasePendingClarifications() {
+    for (const settle of Array.from(this.pendingClarifications.values())) {
+      settle({ outcome: "aborted", answers: [] });
+    }
+  }
   /**
    * Resolve a pending boardroom plan approval from a REPL / dashboard listener.
    * An optional `note` re-plans and re-asks; an optional `editedPlan` is applied
@@ -31276,12 +31541,14 @@ var Cascade = class _Cascade extends EventEmitter__default.default {
       const timeout = setTimeout(() => {
         if (this.pendingContextApproval) {
           this.pendingContextApproval = void 0;
+          this.announceGateClosed("context:approval-closed", {});
           resolve2(true);
         }
       }, 12e4);
       this.pendingContextApproval = (approved) => {
         clearTimeout(timeout);
         this.pendingContextApproval = void 0;
+        this.announceGateClosed("context:approval-closed", {});
         resolve2(approved);
       };
       this.emit("context:approval-required", info);
@@ -31472,6 +31739,34 @@ ${input}` }],
     if ((this.config.tools?.disabledTools ?? []).includes("browser_control")) return;
     this.toolRegistry.register(new BrowserControlTool(controller, release));
   }
+  /**
+   * Declare that this host can put a questionnaire to a person and answer it.
+   *
+   * Explicit, and NOT done at construction, because registering a tool is a
+   * promise the host has to keep. A host that registers `ask_user` without
+   * listening for `clarification:required` gives the model a tool that always
+   * answers "there is nobody watching this run" — while a person sits at the
+   * terminal looking at it. That is worse than not offering the tool at all:
+   * it costs a round trip and then tells the model something false.
+   *
+   * Only `cloud/server` bridges the protocol today. The CLI REPL and the
+   * dashboard do not, so they do not call this, and their models are not shown
+   * a capability nobody can serve. Wiring either of them is a matter of
+   * listening for the event and calling `resolveClarification`, then calling
+   * this.
+   *
+   * Still gated on the same conditions as the call itself, and `askUser`
+   * re-checks them: `setUnattended` can land after this, so the tool can be
+   * registered for a run that later turns out to have nobody on it. Then it
+   * answers `no-listener` and the model proceeds on its own reading, which is
+   * the same defence-in-depth `BrowserControlTool.revoke` provides.
+   */
+  enableClarification() {
+    if (this.unattended) return;
+    if (this.config.autonomy === "auto") return;
+    if ((this.config.tools?.disabledTools ?? []).includes("ask_user")) return;
+    this.toolRegistry.register(new AskUserTool((questions, signal) => this.askUser(questions, signal)));
+  }
   registerMediaTools(workspacePath) {
     const denied = new Set(this.config.tools?.disabledTools ?? []);
     const permitted = (name) => !denied.has(name);
@@ -32417,6 +32712,10 @@ ${finalOutput}` : ""
         this.releasePendingEscalations();
       } catch {
       }
+      try {
+        this.releasePendingClarifications();
+      } catch {
+      }
       this.router.restoreTierModels();
       this.router.setRunSignal(void 0);
       if (this.taskAnalyzer) {
@@ -35023,11 +35322,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;
@@ -35046,6 +35347,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 = {}) {
@@ -35056,6 +35402,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;
   }
@@ -35082,6 +35442,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;
@@ -35122,6 +35483,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--) {
@@ -35137,6 +35597,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();
@@ -35165,33 +35629,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.
@@ -35226,7 +35768,35 @@ 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;
+function notify(deliver) {
+  try {
+    void Promise.resolve(deliver()).catch(() => {
+    });
+  } catch {
+  }
+}
 var RemoteBrowserController = class {
   provider;
   maxSessions;
@@ -35239,8 +35809,49 @@ 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;
+  /** Told when a provider session could not be handed back. See `disposeRun`. */
+  onReleaseFailed;
+  /**
+   * Tell the observer a session leaked, without letting it become the leak.
+   *
+   * Guarded, because this runs inside a `.catch` on the release: an observer
+   * that throws — a logging or telemetry sink that is momentarily unavailable
+   * is the ordinary case — would turn its own failure into a fresh rejection
+   * from `disposeRun`, so `endRun` would reject before `forgetRun` and the
+   * fire-and-forget `stopRun` path would raise an unhandled rejection.
+   *
+   * That is precisely the guarantee this whole change claims to preserve: a
+   * release that fails must never fail the run. Reporting it cannot be the
+   * thing that breaks it.
+   *
+   * TWO WAYS TO FAIL, not one. The `try` catches a synchronous throw; an
+   * `async` sink — which is what a telemetry or logging callback usually is —
+   * fails by returning a REJECTED PROMISE, which no `try` around a call that is
+   * never awaited can see. Node then raises an unhandled rejection and can take
+   * the process down: the observer would not merely have failed to report the
+   * leak, it would have killed the run, which is the one outcome this function
+   * exists to prevent, reached through the door the guard did not cover.
+   *
+   * Not awaited, though. The caller is a `.catch` on the release and is not
+   * going to wait for a telemetry round trip; attaching a handler is what makes
+   * the rejection observed, which is the whole requirement.
+   */
+  reportReleaseFailure(runId, sessionId, err, expiresInMs) {
+    notify(() => this.onReleaseFailed?.(runId, sessionId, err, expiresInMs));
+  }
   runs = /* @__PURE__ */ new Map();
   /**
    * Runs that have a pool slot but no browser yet.
@@ -35248,7 +35859,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.
    *
@@ -35281,7 +35892,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();
   /**
@@ -35299,11 +35910,39 @@ var RemoteBrowserController = class {
     const asked = Math.max(1, options.maxSessions ?? 1);
     this.maxSessions = options.provider.isolatesSessions ? asked : 1;
     this.onLiveViewAll = options.onLiveView;
+    this.onReleaseFailed = options.onReleaseFailed;
+    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);
     }
@@ -35320,6 +35959,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);
+    notify(() => listener(state));
+  }
   /**
    * Tell a run's listener what its browser situation is.
    *
@@ -35329,9 +36006,32 @@ var RemoteBrowserController = class {
    * apart — and would drop the Stop control for the first as if it were the
    * second.
    */
+  /*
+   * Guarded HERE rather than at the call sites, which is the point.
+   *
+   * This is the fifth place in this changeset where a notification could take
+   * down the thing it was notifying about — after the release observer,
+   * `clarification:closed`, `clarification:timeout` and `escalation:timeout`.
+   * The first four were fixed one door at a time, which is how a fifth door
+   * came to exist: the announcement added on the reuse path propagated out of
+   * `open()`, `act()` caught it as an action failure, and every later action
+   * against a perfectly healthy browser was skipped.
+   *
+   * Putting the guard at the source closes all four call sites at once and
+   * leaves no door for a sixth. The worst of them is not the reported one:
+   * `disposeRun` announces `active: false` as its FIRST statement, so a
+   * throwing listener aborted teardown before the screencast was stopped, the
+   * context closed, or the session handed back — leaking the provider session
+   * and never reaching `reportReleaseFailure`. The leak report would have been
+   * skipped by exactly the failure it exists to report.
+   *
+   * Two separate guards, not one around both: these are different listeners —
+   * the per-run panel and the global observer — and one failing must not cost
+   * the other its notification.
+   */
   announceLiveView(runId, liveViewUrl, active) {
-    this.liveViewListeners.get(runId)?.({ active, ...liveViewUrl ? { liveViewUrl } : {} });
-    this.onLiveViewAll?.(runId, liveViewUrl);
+    notify(() => this.liveViewListeners.get(runId)?.({ active, ...liveViewUrl ? { liveViewUrl } : {} }));
+    notify(() => this.onLiveViewAll?.(runId, liveViewUrl));
   }
   /**
    * Hand back a session the run turned out not to want.
@@ -35340,22 +36040,682 @@ 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) {
+          const frame = { data: e.data, width, height, generation: held.watchGen ?? 0 };
+          notify(() => deliver(frame));
+        }
+      }
+      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);
@@ -35364,7 +36724,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. */
@@ -35377,7 +36736,6 @@ var RemoteBrowserController = class {
       return;
     }
     this.runs.delete(runId);
-    this.closing.add(runId);
     await this.teardown(runId, held);
     this.forgetRun(runId);
   }
@@ -35387,6 +36745,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.
@@ -35398,12 +36757,22 @@ 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(() => {
     });
-    await this.provider.endSession(held.session.id).catch(() => {
-    });
+    await this.provider.endSession(held.session.id).catch((err) => this.reportReleaseFailure(runId, held.session.id, err, held.session.expiresInMs));
   }
   /**
    * Run `disposeRun`, with the run id counted in `closing` until it settles.
@@ -35413,12 +36782,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;
@@ -35432,7 +36801,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") {
@@ -35446,28 +36817,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);
     }
@@ -35483,22 +36922,46 @@ 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()) {
+      this.announceLiveView(runId, existing.session.liveViewUrl, true);
+      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);
+        if (this.runs.get(runId) === existing && !existing.abort.signal.aborted) {
+          this.announceLiveView(runId, existing.session.liveViewUrl, true);
+        }
+        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);
     }
@@ -35509,9 +36972,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();
@@ -35519,25 +36982,85 @@ 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(() => {
       });
-      await this.provider.endSession(session.id).catch(() => {
-      });
+      await this.provider.endSession(session.id).catch((releaseErr) => this.reportReleaseFailure(runId, session.id, releaseErr, session.expiresInMs));
       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);
+      }
+    }));
   }
-  async perform(held, action, planned) {
+  /**
+   * 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(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.");
@@ -35559,10 +37082,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,
@@ -35579,15 +37102,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":
@@ -35603,10 +37131,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');
@@ -35657,6 +37200,139 @@ function isCdpEndpoint(url) {
 
 // src/browser/remote/steel.ts
 var DEFAULT_BASE = "https://api.steel.dev";
+function isHostedSteel(url) {
+  if (!url) return true;
+  try {
+    return hostKey(new URL(url).hostname) === hostKey(new URL(DEFAULT_BASE).hostname);
+  } catch {
+    return false;
+  }
+}
+function isUsableSteelBase(url) {
+  try {
+    const u = new URL(url);
+    if (u.protocol !== "http:" && u.protocol !== "https:") return false;
+    if (u.username !== "" || u.password !== "") return false;
+    const built = new URL(withoutTrailingSlashes(url) + PROBE_PATH);
+    if (FETCH_BLOCKED_PORTS.has(built.port)) return false;
+    if (built.search !== "" || built.hash !== "") return false;
+    if (!built.pathname.endsWith(PROBE_PATH)) return false;
+    if (isHostedSteel(url)) {
+      if (built.pathname !== PROBE_PATH) return false;
+      if (u.protocol !== "https:") return false;
+      if (built.port !== "") return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isUsableSteelKey(apiKey) {
+  for (const ch of apiKey) {
+    const c = ch.codePointAt(0) ?? 0;
+    if (c === 9) continue;
+    if (c >= 32 && c <= 126) continue;
+    if (c >= 128 && c <= 255) continue;
+    return false;
+  }
+  return true;
+}
+var API_KEY_HEADER = "steel-api-key";
+var FETCH_BLOCKED_PORTS = /* @__PURE__ */ new Set([
+  "1",
+  "7",
+  "9",
+  "11",
+  "13",
+  "15",
+  "17",
+  "19",
+  "20",
+  "21",
+  "22",
+  "23",
+  "25",
+  "37",
+  "42",
+  "43",
+  "53",
+  "69",
+  "77",
+  "79",
+  "87",
+  "95",
+  "101",
+  "102",
+  "103",
+  "104",
+  "109",
+  "110",
+  "111",
+  "113",
+  "115",
+  "117",
+  "119",
+  "123",
+  "135",
+  "137",
+  "139",
+  "143",
+  "161",
+  "179",
+  "389",
+  "427",
+  "465",
+  "512",
+  "513",
+  "514",
+  "515",
+  "526",
+  "530",
+  "531",
+  "532",
+  "540",
+  "548",
+  "554",
+  "556",
+  "563",
+  "587",
+  "601",
+  "636",
+  "989",
+  "990",
+  "993",
+  "995",
+  "1719",
+  "1720",
+  "1723",
+  "2049",
+  "3659",
+  "4045",
+  "4190",
+  "5060",
+  "5061",
+  "6000",
+  "6566",
+  "6665",
+  "6666",
+  "6667",
+  "6668",
+  "6669",
+  "6679",
+  "6697",
+  "10080"
+]);
+var PROBE_PATH = "/v1/sessions";
+function withoutTrailingSlashes(value) {
+  let out = value;
+  while (out.endsWith("/")) out = out.slice(0, -1);
+  return out;
+}
+function hostKey(hostname) {
+  let host = hostname.toLowerCase();
+  while (host.endsWith(".")) host = host.slice(0, -1);
+  return host;
+}
 var CREATE_TIMEOUT_MS = 6e4;
 var SteelProvider = class {
   name = "Steel";
@@ -35666,9 +37342,7 @@ var SteelProvider = class {
   base;
   apiKey;
   constructor(opts = {}) {
-    let base = opts.url || DEFAULT_BASE;
-    while (base.endsWith("/")) base = base.slice(0, -1);
-    this.base = base;
+    this.base = withoutTrailingSlashes(opts.url || DEFAULT_BASE);
     this.apiKey = opts.apiKey;
   }
   async createSession(signal) {
@@ -35679,14 +37353,15 @@ var SteelProvider = class {
     return {
       id: details.id,
       cdpUrl: details.websocketUrl,
-      ...details.debugUrl ? { liveViewUrl: details.debugUrl } : {}
+      ...details.debugUrl ? { liveViewUrl: details.debugUrl } : {},
+      // Carried through because it explains an otherwise mysterious death. A
+      // session nobody released dies at exactly this number, and without it a
+      // leak looks identical to an orderly shutdown.
+      ...typeof details.timeout === "number" ? { expiresInMs: details.timeout } : {}
     };
   }
   async endSession(id) {
-    try {
-      await this.call("POST", `/v1/sessions/${encodeURIComponent(id)}/release`, void 0, {});
-    } catch {
-    }
+    await this.call("POST", `/v1/sessions/${encodeURIComponent(id)}/release`, void 0, {});
   }
   async call(method, path30, signal, body) {
     const timeout = AbortSignal.timeout(CREATE_TIMEOUT_MS);
@@ -35697,7 +37372,7 @@ var SteelProvider = class {
         "content-type": "application/json",
         // Sent only when configured — the self-hosted API takes no key, and an
         // empty header is worse than none.
-        ...this.apiKey ? { "steel-api-key": this.apiKey } : {}
+        ...this.apiKey ? { [API_KEY_HEADER]: this.apiKey } : {}
       },
       body: JSON.stringify(body),
       signal: composed
@@ -36363,6 +38038,7 @@ function applySyncBundle(bundle, config, cleanup) {
 
 exports.AZURE_BASE_MODELS = AZURE_BASE_MODELS;
 exports.AZURE_BASE_URL_TEMPLATE = AZURE_BASE_URL_TEMPLATE;
+exports.AskUserTool = AskUserTool;
 exports.AuditLogger = AuditLogger;
 exports.BrowserControlTool = BrowserControlTool;
 exports.BrowserLease = BrowserLease;
@@ -36494,7 +38170,10 @@ exports.inferAzureBaseModel = inferAzureBaseModel;
 exports.inlineRuns = inlineRuns;
 exports.isCdpEndpoint = isCdpEndpoint;
 exports.isDocumentFormat = isDocumentFormat;
+exports.isHostedSteel = isHostedSteel;
 exports.isMcpToolName = isMcpToolName;
+exports.isUsableSteelBase = isUsableSteelBase;
+exports.isUsableSteelKey = isUsableSteelKey;
 exports.matchImageLine = matchImageLine;
 exports.mcpServerPrefix = mcpServerPrefix;
 exports.mcpToolName = mcpToolName;