@withbuddi/buddi 0.1.0-pre.37 → 0.1.0-pre.39

package/node_modules/@buddi/tool-browser/dist/service.js

@@ -1,51 +1,55 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, writeFile, rename } from 'node:fs/promises';
-import path from 'node:path';
 import { FORM_KIND, NATIVE_KIND, fieldBoundTo, secretKindFor, takeDelivered } from './secrets.js';
-import { APP_BEHIND, BrowserPreconditionError, UNTRUSTED, observedLine } from './types.js';
+import { LOGIN_GONE, LOGIN_GRACE_MS, APP_BEHIND, BrowserOpenedError, BrowserPreconditionError, UNTRUSTED, observedLine } from './types.js';
+import { ownerCard, siteOf } from './routes.js';
+import { missionMark } from './telemetry.js';
 /**
- * "The owner stopped the browser", said where the owner can undo it.
- *
- * The *fact* is one sentence; the way back differs by surface, and the surface
- * is already on the tool context (`ctx.surface`), so the plugin says it rather
- * than leaving a relay to guess. On Telegram the way back is a command in the
- * same chat; everywhere else it is the dashboard's own Settings page, which is
- * where the Stop button lives.
+ * Said when the owner has stopped agents' browsing. On Telegram the way back
+ * is a command in the same chat; everywhere else the Resume card in the chat
+ * itself, or Settings.
  */
-/** Said when control paused: the tab or window is gone, or the page kept failing to answer. The way back depends on where the owner is. */
+export function browserStoppedMessage(surface) {
+    return surface?.id === 'telegram'
+        ? 'The owner stopped agents\' browsing. Tap Resume on the card, or send /browser resume here.'
+        : 'The owner stopped agents\' browsing. Tap Resume on the card in this chat to let agents look again.';
+}
+/** Kept for the surfaces that still name it: the owner has the page in their hands. */
 export function browserPausedMessage(surface) {
     return surface?.id === 'telegram'
-        ? 'Control is paused: the page closed or stopped answering. Send /browser resume here, then ask again for a fresh look.'
-        : 'Control is paused. Ask the owner to inspect the selected app/window and the reported cause, then use Resume access and ask for a fresh observation.';
+        ? 'You have the page. Give it back from the dashboard, or send /browser resume here.'
+        : 'You have the page. Give it back when you are done and the agent carries on.';
 }
-/**
- * Said when an observation did not answer and control stays with the agent.
- * A slow page is something the model can wait out itself, so there is nothing
- * for the owner to do and the wording is the same on every surface.
- */
+/** A page that did not answer after every retry: said once, never as an instruction to retry. */
 export function browserWaitMessage(_surface) {
-    return 'The page has not answered yet. Wait a few seconds and observe again.';
+    return 'The page did not answer after several tries.';
 }
-/** An observation failure that no waiting fixes: the tab or window it was reading is gone. */
-const SCREEN_GONE = /\b(tab|window)\b[^.]*\b(closed|gone)\b|has been closed|target closed/i;
-/** A gone tab the driver can replace by itself ("observe again to continue in a new one") is not a screen lost. */
-const SCREEN_REPLACEABLE = /observe again to continue in a new one/i;
-/** The extension's refusal to act in the tab the owner is viewing (extension commands.ts, `WATCHED`). */
+/** The extension's last word after waiting for the owner to leave their tab (extension commands.ts, `WATCHED`). */
 const OWNER_WATCHING = /You are looking at this tab/i;
-/** What the model is told instead: one ask of the owner, not a retry. */
-export const OWNER_WATCHING_MESSAGE = 'The owner is looking at that tab. Ask them to switch to another tab or window, then try once more.';
-/** Consecutive observation failures on one session before control pauses. */
-const MAX_OBSERVATION_FAILURES = 3;
-export function browserStoppedMessage(surface) {
-    return surface?.id === 'telegram'
-        ? 'The owner stopped the browser. Only the owner can enable it again — send /browser resume here.'
-        : 'The owner stopped the browser. Only the owner can enable it again in the dashboard, on the Settings page.';
-}
-/** Already classified: do not retry observation or overwrite the paused state. */
-class ObservationFailure extends Error {
+/** What the agent is told instead: no ask, no retry loop; the bar in the tab already asks the owner. */
+export const OWNER_WATCHING_MESSAGE = 'The owner is looking at that tab, and the bar in it asks them whether you may carry on there. Nothing was done. Work on something else for a moment, then try again.';
+/** An observation failure no waiting fixes: the tab or window it was reading is gone. */
+const SCREEN_GONE = /\b(tab|window)\b[^.]*\b(closed|gone)\b|has been closed|target closed/i;
+/** The waits before each re-read when the page gave no answer: 0.5, 1, 2, 4 and 8 seconds (six attempts in all). */
+export const RETRY_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];
+/** Targeting refusals in a row before the task asks the owner whether to keep going. */
+export const MAX_TARGETING_FAILURES = 8;
+/** The task's budget: actions and minutes, renewed by any owner touch in the conversation. */
+export const DEFAULT_MAX_STEPS = 200;
+export const DEFAULT_LIFETIME_MS = 60 * 60_000;
+/** How long a run stays parked on its page waiting for the owner's card. */
+export const PARK_MS = 60 * 60_000;
+/** A route by the mode name the dashboard and Telegram already know. */
+export function modeOf(route) {
+    return route === 'chrome' ? 'extension' : route === 'apps' ? 'computer' : 'playwright';
 }
-/** One host controller shared by all registry instances/surfaces in serve.
- * CLI processes are deliberately unavailable, not a second browser owner. */
+/**
+ * One conversation's page on one route.
+ *
+ * Every action returns the page as it is afterwards. Refusals that used to
+ * stop the task are retried here (a slow page, a stale ref, a redirect) or
+ * become one card the owner answers (an input that may not have landed, the
+ * budget). Only the owner's own take-over pauses a page.
+ */
 export class BrowserService {
     driver;
     options;
@@ -55,81 +59,112 @@ export class BrowserService {
     #observation;
     #picture;
     #busy = false;
-    /**
-     * The screen this session had is gone.
-     *
-     * Set when a take-over had to close the driver to end the action in flight,
-     * and cleared by resume. Belt to `handReady`'s braces: a hand offered over
-     * nothing is a live view that never paints its first frame, and the owner
-     * has no way to tell that from a slow link.
-     */
     #handless = false;
+    /** The owner holds the page in place (their Chrome brought it forward): no frames, no hand. */
+    #held = false;
+    /** The page the owner last held in place, and until when a Save they tapped there still counts (the driver's grace). */
+    #lastHeld;
+    /** Who waits for the action in flight to settle (a Give it back pressed while it stops). */
+    #settleWaiters = [];
     #controller;
     #expiry;
     #lastAction;
     #message;
-    #preconditionFailures = 0;
-    #observationFailures = 0;
-    #needsObservation = false;
-    #spent = new Set();
+    #targetingFailures = 0;
+    #card;
+    /** Where the page last was, so a closed tab or a new request re-opens it rather than stopping. */
+    #lastUrl;
+    #lastActivity = 0;
+    #tail = Promise.resolve();
     #controlTail = Promise.resolve();
-    #diskTail = Promise.resolve();
     constructor(driver, options = {}) {
         this.driver = driver;
         this.options = options;
     }
     #now() { return this.options.now?.() ?? Date.now(); }
-    /** When buddi took this observation, so the model can tell the newest from an older one. */
-    #stamp(observation) {
-        return { ...observation, observedAt: new Date(this.#now()).toISOString() };
+    get #route() { return this.options.route ?? (this.options.allowOpen ? 'apps' : 'own'); }
+    #sleep(ms) { return this.options.sleep ? this.options.sleep(ms) : new Promise((resolve) => setTimeout(resolve, ms)); }
+    #stamp(observation) { return { ...observation, observedAt: new Date(this.#now()).toISOString() }; }
+    #stop(cause, ctx, recovered) {
+        this.options.telemetry?.stop(cause, { route: this.#route, ...(ctx?.agentId ? { agent: ctx.agentId } : {}), ...(ctx?.surface?.id ? { surface: ctx.surface.id } : {}), ...missionMark(ctx),
+            ...(siteOf(this.#observation?.url ?? this.#lastUrl) ? { host: siteOf(this.#observation?.url ?? this.#lastUrl) } : {}), ...(recovered ? { recovered } : {}) });
     }
     async enable() {
         if (this.#enabled)
             return;
-        if (this.options.controlFile) {
-            try {
-                const state = JSON.parse(await readFile(this.options.controlFile, 'utf8'));
-                this.#state = state.stopped ? 'stopped' : 'idle';
-            }
-            catch (error) {
-                if (error.code !== 'ENOENT')
-                    throw error;
-                this.#state = 'idle';
-            }
-        }
-        else
-            this.#state = 'idle';
+        // Take over pressed in the page's own bar is the Canvas button.
+        this.driver.onOwnerTakeover?.(() => {
+            const id = this.#session?.id;
+            if (!id)
+                return;
+            if (this.options.requestTakeover)
+                this.options.requestTakeover(id);
+            else
+                void this.control('takeover').catch(() => undefined);
+        });
+        // Give it back pressed in the held tab's bar is the Canvas's Give it back.
+        this.driver.onOwnerGiveBack?.(() => {
+            const id = this.#session?.id;
+            if (!id || this.#state !== 'paused')
+                return;
+            if (this.options.requestResume)
+                this.options.requestResume(id);
+            else
+                void this.control('resume').catch(() => undefined);
+        });
+        // A sign-in the owner made on the page they hold: the keeper asks them, never a model.
+        // A Save the owner tapped in their Chrome a beat after Give it back still counts, for the page they held, within the driver's grace.
+        this.driver.onLoginSeen?.((login) => {
+            const live = this.#state === 'paused' ? this.#session?.id : undefined;
+            if (login.decision === 'check' && !live)
+                return Promise.resolve({ ask: 'none' });
+            const recent = !live && login.decision && this.#lastHeld && this.#now() < this.#lastHeld.until ? this.#lastHeld.id : undefined;
+            const id = live ?? recent;
+            if (!id)
+                return login.decision ? Promise.resolve({ saved: false, reason: LOGIN_GONE }) : undefined;
+            return this.options.loginSeen?.(id, login);
+        });
+        this.#state = 'idle';
         this.#enabled = true;
     }
     status(_scope) {
         const { tree: _tree, targets: _targets, ...page } = this.#observation ?? {};
-        const { ownerId: _owner, ...session } = this.#session ?? {};
+        const session = this.#session ? (({ ownerId: _o, startedAt: _s, actions: _a, cards: _c, ...rest }) => rest)(this.#session) : undefined;
         return { state: this.#state, enabled: this.#enabled, busy: this.#busy,
-            ...(this.#session ? { session: session } : {}),
+            ...(session ? { session: { ...session, route: this.#route }, route: this.#route, mode: modeOf(this.#route) } : {}),
             ...(this.#observation ? { page: page } : {}),
+            ...(this.#card ? { needsOwner: this.#card } : {}),
+            ...(this.#state === 'paused' && this.#held && this.driver.holdsInPlace ? { held: { by: 'owner', where: this.driver.holdsInPlace } } : {}),
             lastAction: this.#lastAction, message: this.#message, hasScreenshot: !!this.#picture };
     }
     screenshot(_sessionId) { return this.#picture; }
+    /** The card this page waits on, if any. */
+    get card() { return this.#card; }
+    /** Where this page is, or was. */
+    get lastUrl() { return this.#observation?.url ?? this.#lastUrl; }
+    /** The latest page, with its tree: what the route's post-processing reads. */
+    get observation() { return this.#observation; }
+    get busy() { return this.#busy; }
+    /** Where this conversation's page was before it was let go, so the next action opens it again there. */
+    seed(url) { this.#lastUrl ??= url; }
+    /** No action for this long: a page a waiting conversation may take over. */
+    idleFor() { return this.#busy || this.#state === 'paused' || this.#card ? 0 : this.#now() - this.#lastActivity; }
     /**
-     * The remote hand, and only while the owner holds this screen.
-     *
-     * Paused is the take-over state, so it is also the only state in which a
-     * dashboard may drive: an agent mid-action and a hand on the same page would
-     * be two drivers, and the evidence rules here assume exactly one.
+     * The remote hand, and only while the owner holds this screen. Paused is the
+     * take-over state, the only one in which a dashboard may drive.
      */
     hand(_scope) {
+        if (this.#held && this.#state === 'paused')
+            return { supported: false, message: 'The page is in front of you in your Chrome.' };
         if (this.driver.supportsHand === false || !this.driver.hand) {
-            return { supported: false, message: this.driver.handMessage ?? 'Take over at the computer for this mode.' };
+            return { supported: false, message: this.driver.handMessage ?? 'Take over at the computer for this route.' };
         }
         if (!this.#session)
-            return { supported: true, message: 'No agent is driving this screen.' };
+            return { supported: true, message: 'No agent is looking at this page.' };
         if (this.#state !== 'paused')
             return { supported: true, message: 'Take over first, then you can drive.' };
-        // Paused is not the same as paintable. A take-over that interrupted an
-        // action closed the screen that action was on, and a hand offered over
-        // nothing is a live view that never draws its first frame.
         if (this.#handless || this.driver.handReady?.() === false) {
-            return { supported: true, message: this.#message ?? 'There is no screen to drive. Resume and ask the agent to open the page again.' };
+            return { supported: true, message: this.#message ?? 'There is no screen to drive. Give it back and the agent opens the page again.' };
         }
         return { supported: true, hand: this.driver.hand };
     }
@@ -138,120 +173,195 @@ export class BrowserService {
         if (!session || session.ownerId !== input.ownerId || session.agentId !== input.agentId || session.conversationId !== input.previousConversationId)
             return false;
         if (!this.#enabled || this.#busy || !['running', 'paused'].includes(this.#state))
-            throw new Error('Wait for computer/browser control to settle before continuing the conversation.');
-        if (Date.parse(session.expiresAt) <= this.#now())
-            return false;
-        this.#spent.add(session.requestId);
+            throw new Error('Wait for the page to settle before continuing the conversation.');
         session.conversationId = input.conversationId;
         this.#observation = undefined;
         this.#picture = undefined;
-        this.#needsObservation = true;
-        this.#message = 'Task continued after conversation rollover. Observe the current page before acting. Human takeover, if active, still requires owner resume.';
+        this.#message = 'Task continued after conversation rollover. The next action returns the current page.';
         return true;
     }
-    async execute(command, ctx) {
+    /**
+     * Put the page on a card and wait for the owner. The run stops (the tool's
+     * result carries the card) and the page stays open for at least an hour.
+     */
+    park(kind, facts = {}) {
+        const card = ownerCard(kind, { site: siteOf(this.lastUrl), ...facts });
+        this.#card = card;
+        if (this.#session)
+            this.#session.cards++;
+        this.#schedule(Math.max(Date.parse(this.#session?.expiresAt ?? '') || 0, this.#now()) + Math.max(this.options.parkMs ?? PARK_MS, PARK_MS) - this.#now());
+        return card;
+    }
+    #cardResult(card, dispatched, message) {
+        return { completed: false, dispatched, needsOwner: card, notice: UNTRUSTED,
+            message: message ?? `Waiting for the owner: "${card.title}" Say that in one sentence and stop; the card in the chat has the buttons. The page stays open; you continue when they answer.`,
+            ...(this.#observation ? { observation: this.#observation } : {}) };
+    }
+    /**
+     * The owner spoke or tapped in this conversation: the budget renews (200
+     * actions, an hour) and a waiting card is cleared. Returns the card it
+     * cleared, so the caller can act on the answer (take over, use Chrome).
+     */
+    renew() {
+        const card = this.#card;
+        this.#card = undefined;
+        this.#targetingFailures = 0;
+        if (this.#session) {
+            this.#session.steps = 0;
+            this.#session.maxSteps = this.options.maxSteps ?? DEFAULT_MAX_STEPS;
+            const expiresAt = this.#now() + (this.options.lifetimeMs ?? DEFAULT_LIFETIME_MS);
+            this.#session.expiresAt = new Date(expiresAt).toISOString();
+            this.#schedule(expiresAt - this.#now() + Math.max(this.options.parkMs ?? PARK_MS, PARK_MS));
+        }
+        return card;
+    }
+    #schedule(ms) {
+        clearTimeout(this.#expiry);
+        this.#expiry = setTimeout(() => { void this.#release('expired'); }, Math.max(1, ms));
+        this.#expiry.unref?.();
+    }
+    #open(request, ctx) {
+        const lifetime = this.options.lifetimeMs ?? DEFAULT_LIFETIME_MS;
+        if (!this.#session) {
+            const expiresAt = this.#now() + lifetime;
+            this.#session = { id: randomUUID(), ownerId: ctx.buddi.owner.id, agentId: ctx.agentId, conversationId: ctx.conversationId,
+                requestId: request?.id ?? 'unattended', task: (request?.text ?? 'An unattended task').slice(0, 4000),
+                expiresAt: new Date(expiresAt).toISOString(), steps: 0, maxSteps: this.options.maxSteps ?? DEFAULT_MAX_STEPS,
+                startedAt: this.#now(), actions: 0, cards: 0 };
+            this.#schedule(lifetime + Math.max(this.options.parkMs ?? PARK_MS, PARK_MS));
+            return;
+        }
+        // A new owner message is an owner touch: the same page, a fresh budget.
+        if (request && this.#session.requestId !== request.id) {
+            this.#session.requestId = request.id;
+            this.#session.task = request.text.slice(0, 4000);
+            this.renew();
+        }
+    }
+    /** One action at a time per page: a second call waits for the first rather than being refused. */
+    #serial(run) {
+        const next = this.#tail.then(run, run);
+        this.#tail = next.catch(() => { });
+        return next;
+    }
+    execute(command, ctx) {
+        return this.#serial(() => this.#execute(command, ctx));
+    }
+    async #execute(command, ctx) {
         ctx.signal?.throwIfAborted();
         const request = ctx.ownerRequest;
-        if (!request || !request.id || !request.text.trim() || request.expiresAt <= this.#now() ||
-            !ctx.agentId || !ctx.conversationId || (ctx.delegationDepth ?? 0) > 0) {
-            throw new Error('A current authenticated owner request is required.');
-        }
+        if (!ctx.agentId || !ctx.conversationId)
+            throw new Error('A browser action belongs to an agent and a conversation.');
         if (!this.#enabled)
             throw new Error('Browser driving is available through buddi serve (dashboard or Telegram), not a separate CLI process.');
         if (this.#state === 'stopped')
             throw new Error(browserStoppedMessage(ctx.surface));
-        if (this.#busy)
-            throw new Error('Browser is busy; overlapping actions are refused.');
         if (this.#session && (this.#session.ownerId !== ctx.buddi.owner.id || this.#session.agentId !== ctx.agentId || this.#session.conversationId !== ctx.conversationId)) {
-            throw new Error('Another agent/conversation owns the browser. Ask the owner to release it from the dashboard.');
+            throw new Error('Another conversation owns this page.');
         }
-        if (this.#spent.has(request.id))
-            throw new Error('This browser request has ended. A new owner message is required.');
         if (command.action === 'close') {
-            this.#spent.add(request.id);
             await this.#release('idle');
             return { closed: true, notice: UNTRUSTED };
         }
-        if (this.#state === 'paused')
-            throw new Error('Browser is under human control or needs inspection. Wait for the owner to resume in the dashboard, then observe.');
-        // Computer mode's open only brings an app forward, then observes: nothing earlier is replayed.
-        // navigate still waits for a fresh look, since it loads a page.
-        const reopens = this.options.allowOpen === true && command.action === 'open';
-        if (this.#needsObservation && command.action !== 'observe' && !reopens)
-            throw new Error('A fresh observation is required: observe the current page before acting. Do not replay an earlier action.');
-        if (!this.#session || this.#session.requestId !== request.id) {
-            if (!this.#session && command.action !== 'navigate' && !(this.options.allowOpen && command.action === 'open'))
-                throw new Error('Start with navigate, or open an allowed application in computer mode.');
-            this.#rekey(request, ctx.agentId, ctx.conversationId, ctx.buddi.owner.id);
+        if (this.#state === 'paused') {
+            throw new Error('The owner has this page in their hands. Wait for them to give it back; you continue when they do.');
+        }
+        // Parked on a card: nothing is done until the owner answers it.
+        if (this.#card) {
+            this.#open(request, ctx);
+            if (this.#card)
+                return this.#cardResult(this.#card, false);
+        }
+        let run = command;
+        let reopened = false;
+        if (!this.#session && command.action !== 'navigate' && command.action !== 'open') {
+            // No page yet, or the last one was let go: open it again where it was.
+            if (!this.#lastUrl || this.#route === 'apps') {
+                this.#stop('start-with-navigate', ctx);
+                return { completed: false, dispatched: false, notice: UNTRUSTED, message: 'No page is open in this conversation yet. Navigate to the website first.' };
+            }
+            this.#stop('request-ended', ctx);
+            run = { action: 'navigate', url: this.#lastUrl };
+            reopened = true;
         }
+        this.#open(request, ctx);
         const active = this.#session;
-        if (!active || Date.parse(active.expiresAt) <= this.#now() || active.steps >= active.maxSteps) {
-            await this.#release('expired');
-            throw new Error('Browser task reached its time or step limit. Ask the owner for a new request.');
+        if (active.steps >= active.maxSteps || Date.parse(active.expiresAt) <= this.#now()) {
+            this.#stop('budget', ctx);
+            return this.#cardResult(this.park('budget'), false);
+        }
+        // The observation is the latest one unless the agent named another.
+        if (['click', 'fill', 'select', 'press', 'scroll'].includes(run.action) && run.observation === undefined && this.#observation) {
+            run = { ...run, observation: this.#observation.id };
         }
         ++active.steps;
+        ++active.actions;
         this.#busy = true;
-        this.#lastAction = command.action; // Never record form values here.
+        this.#lastAction = run.action; // Never record form values here.
+        this.#lastActivity = this.#now();
         this.#message = undefined;
         const controller = new AbortController();
         this.#controller = controller;
         const cancel = () => {
             controller.abort(ctx.signal?.reason ?? new Error('Browser action stopped.'));
-            this.#spent.add(request.id);
-            void this.#release('stopped');
-            void this.#persistStop(true).catch(() => { });
+            void this.#release('idle');
         };
         ctx.signal?.addEventListener('abort', cancel, { once: true });
         try {
             this.#state = 'starting';
             await this.driver.start();
             controller.signal.throwIfAborted();
-            ctx.signal?.throwIfAborted();
             this.#state = 'running';
-            await this.driver.perform(command);
-            if (command.action !== 'observe')
-                this.#preconditionFailures = 0;
+            await this.driver.perform(run);
+            const note = this.driver.takeNote?.();
+            if (note)
+                this.#message = note;
+            if (run.action !== 'observe')
+                this.#targetingFailures = 0;
             controller.signal.throwIfAborted();
-            // Once input succeeds, observation loss must not invite replaying it.
-            // For an observe-only command, however, observation IS the whole action.
-            try {
-                const observation = await this.driver.observe();
-                const picture = await this.driver.screenshot();
-                controller.signal.throwIfAborted();
-                this.#observation = this.#stamp(observation);
-                this.#picture = picture;
-                this.#needsObservation = false;
-                this.#observationFailures = 0;
+            const seen = await this.#look(controller, ctx);
+            if (!seen) {
+                // Six reads over fifteen seconds and nothing: one card, not a loop.
+                this.#stop('observation-failures', ctx, 'card');
+                return this.#cardResult(this.park('uncertain'), run.action !== 'observe');
             }
-            catch (error) {
-                controller.signal.throwIfAborted();
-                const cause = error instanceof Error ? error.message : String(error);
-                const paused = this.#observationFailed(cause);
-                // The extension's final error already says to wait and observe again; do not say it twice.
-                // The app pushed behind already says how to bring it back.
-                const recovery = paused ? browserPausedMessage(ctx.surface) : APP_BEHIND.test(cause) || /observe again\.?$/i.test(cause.trim()) ? '' : browserWaitMessage(ctx.surface);
-                this.#message = `${command.action === 'observe' ? 'Observation failed' : 'Action completed, but observation failed'}: ${cause.replace(/\.$/, '')}.${recovery ? ` ${recovery}` : ''}${command.action === 'observe' ? '' : ' Do not repeat the action; its effect may already have happened.'}`;
-                const result = { completed: command.action !== 'observe', observed: false, error: cause,
-                    state: this.#state, recovery, message: this.#message, notice: UNTRUSTED };
-                if (command.action === 'observe')
-                    throw new ObservationFailure(JSON.stringify(result));
-                return result;
-            }
-            controller.signal.throwIfAborted();
             const observed = observedLine(this.#observation.observedAt);
+            if (reopened) {
+                const asked = command.action;
+                return { completed: false, dispatched: false, notice: UNTRUSTED, observation: this.#observation,
+                    message: `${observed} No page was open, so I opened ${siteOf(this.#lastUrl) ?? 'the last page'} again. Nothing else was done; ${asked === 'observe' ? 'here it is' : 'act on this page now'}.` };
+            }
             return { completed: true, notice: UNTRUSTED, observation: this.#observation, message: this.#message ? `${observed} ${this.#message}` : observed };
         }
         catch (error) {
-            if (error instanceof ObservationFailure)
+            if (controller.signal.aborted)
                 throw error;
-            if (!controller.signal.aborted && error instanceof BrowserPreconditionError) {
-                await this.#precondition(controller, error);
+            const message = error instanceof Error ? error.message : String(error);
+            if (error instanceof BrowserPreconditionError)
+                return await this.#precondition(controller, error, ctx);
+            this.#state = 'running';
+            if (error instanceof BrowserOpenedError) {
+                // The page opened and a later step failed: hand back the page, not just the error.
+                const site = siteOf(error.page.url) ?? 'the page';
+                const failed = message.replace(/\.$/, '');
+                if (error.page.url)
+                    this.#lastUrl = error.page.url;
+                const seen = await this.#look(controller, ctx).catch(() => false);
+                if (seen) {
+                    return { completed: false, dispatched: true, notice: UNTRUSTED, observation: this.#observation,
+                        message: `${observedLine(this.#observation.observedAt)} Opened ${site}, then this failed: ${failed}. Carry on from this page; don't open it again.` };
+                }
+                this.#message = `Opened ${site} in a tab, then this failed: ${failed}.`;
+                throw new Error(this.#message);
             }
-            if (!controller.signal.aborted) {
-                this.#state = error instanceof BrowserPreconditionError ? 'running'
-                    : ['click', 'fill', 'select', 'press'].includes(command.action) ? 'paused' : 'error';
-                this.#message = `${error instanceof Error ? error.message : String(error)}${this.#state === 'paused' ? ' The action may have partially completed. Inspect it before resuming; do not repeat a submission.' : ''}`;
+            if (['click', 'fill', 'select', 'press'].includes(run.action)) {
+                // The input may have landed part-way: the owner looks, or tells the agent to judge from the page.
+                this.#stop('uncertain-input', ctx, 'card');
+                this.#observation = undefined;
+                this.#picture = undefined;
+                return this.#cardResult(this.park('uncertain'), true, `${message.replace(/\.$/, '')}. I'm not sure that went through. Say so in one sentence and stop; the card asks the owner whether to look.`);
             }
+            this.#message = message;
             throw error;
         }
         finally {
@@ -259,204 +369,177 @@ export class BrowserService {
             if (this.#controller === controller)
                 this.#controller = undefined;
             this.#busy = false;
+            this.#settled();
         }
     }
     /**
-     * An observation that did not come back. Usually a page still loading or
-     * busy, which the agent can wait out and observe again, so control stays
-     * with it and the next action must be a fresh observation. Control pauses
-     * only when the tab or window is gone, or on the third failure in a row.
-     * Returns whether it paused.
+     * Read the page, re-reading at 0.5, 1, 2, 4 and 8 seconds when it does not
+     * answer. A closed tab is opened again at its last address once. False when
+     * all six reads failed. The app pushed behind the owner's window is said
+     * straight away: open brings it back and no wait helps.
      */
-    #observationFailed(cause) {
-        this.#observation = undefined;
-        this.#picture = undefined;
-        this.#needsObservation = true;
-        // The owner's window in front of the app is not a failing screen: the agent brings it back with open.
-        if (APP_BEHIND.test(cause)) {
-            if (this.#state !== 'paused')
-                this.#state = 'running';
-            return false;
+    async #look(controller, ctx) {
+        const delays = this.options.retryDelays ?? RETRY_DELAYS_MS;
+        let reopened = false;
+        let counted = false;
+        for (let attempt = 0; attempt <= delays.length; attempt++) {
+            if (attempt > 0)
+                await this.#sleep(delays[attempt - 1]);
+            controller.signal.throwIfAborted();
+            try {
+                const observation = await this.driver.observe();
+                const picture = await this.driver.screenshot();
+                controller.signal.throwIfAborted();
+                this.#observation = this.#stamp(observation);
+                this.#picture = picture;
+                if (observation.url)
+                    this.#lastUrl = observation.url;
+                return true;
+            }
+            catch (error) {
+                controller.signal.throwIfAborted();
+                const cause = error instanceof Error ? error.message : String(error);
+                this.#observation = undefined;
+                this.#picture = undefined;
+                if (APP_BEHIND.test(cause)) {
+                    this.#stop('app-behind', ctx);
+                    throw new BrowserPreconditionError(cause);
+                }
+                if (SCREEN_GONE.test(cause) && !reopened && this.#lastUrl && this.#route !== 'apps') {
+                    reopened = true;
+                    this.#stop('screen-gone', ctx);
+                    try {
+                        await this.driver.perform({ action: 'navigate', url: this.#lastUrl });
+                    }
+                    catch { /* the next read says */ }
+                    continue;
+                }
+                if (!counted) {
+                    counted = true;
+                    this.#stop('page-not-answered', ctx);
+                }
+            }
         }
-        const paused = ++this.#observationFailures >= MAX_OBSERVATION_FAILURES || (SCREEN_GONE.test(cause) && !SCREEN_REPLACEABLE.test(cause));
-        this.#state = paused ? 'paused' : 'running';
-        return paused;
+        return false;
     }
     /**
-     * A new owner message continues the session under that message's request:
-     * the old one is spent, the step budget and the failure count reset, and the
-     * expiry runs from now. The session id survives, so the conversation still
-     * owns the same screen it always did.
+     * Refused before anything was dispatched: a stale observation, a ref that
+     * no longer matches, a page that moved. The tool looks again and answers
+     * with the fresh page; nothing pauses. Eight in a row asks the owner
+     * whether to keep going. The owner looking at the tab and the app behind
+     * their window are said as what they are.
      */
-    #rekey(request, agentId, conversationId, ownerId) {
-        const expiresAt = Math.min(request.expiresAt, this.#now() + (this.options.lifetimeMs ?? 20 * 60_000));
-        if (this.#session)
-            this.#spent.add(this.#session.requestId);
-        this.#preconditionFailures = 0;
-        this.#session = { id: this.#session?.id ?? randomUUID(), ownerId, agentId,
-            conversationId, requestId: request.id, task: request.text.slice(0, 4000),
-            expiresAt: new Date(expiresAt).toISOString(), steps: 0, maxSteps: this.options.maxSteps ?? 80 };
-        clearTimeout(this.#expiry);
-        this.#expiry = setTimeout(() => { void this.#release('expired'); }, Math.max(1, expiresAt - this.#now()));
-        this.#expiry.unref?.();
-    }
-    /**
-     * The precondition path every refused action takes, `browser.act`'s and the
-     * secret tools' alike: count the failure, pause on the third, and recover
-     * fresh evidence so the next call acts on what the page now shows rather
-     * than on the stale arguments. Nothing was dispatched for any of these.
-     */
-    async #precondition(controller, error) {
+    async #precondition(controller, error, ctx) {
+        this.#state = 'running';
         if (OWNER_WATCHING.test(error.message)) {
-            // Not a targeting failure and nothing waiting fixes: only the owner
-            // moving to another tab does. No pause and no count; the next action
-            // must observe first, so the model asks once instead of retrying.
+            this.#stop('owner-watching', ctx);
             this.#message = OWNER_WATCHING_MESSAGE;
-            this.#state = 'running';
-            this.#needsObservation = true;
-            throw new BrowserPreconditionError(JSON.stringify({ error: OWNER_WATCHING_MESSAGE, dispatched: false,
-                recovery: 'Ask the owner now and wait for their answer. Do not retry by yourself.' }));
+            throw new BrowserPreconditionError(JSON.stringify({ error: OWNER_WATCHING_MESSAGE, dispatched: false }));
         }
         if (APP_BEHIND.test(error.message)) {
-            // The owner's own window came forward (typing in the dashboard does it).
-            // Not a targeting failure and nothing for the owner to do: the agent
-            // calls open for the same app. No count, no pause, and no recovery
-            // observation, which would only be refused the same way.
             this.#message = error.message;
-            this.#state = 'running';
             this.#observation = undefined;
             this.#picture = undefined;
-            this.#needsObservation = true;
             throw new BrowserPreconditionError(JSON.stringify({ error: error.message, dispatched: false,
-                recovery: 'Call browser.act open with the same app now; it needs no approval. Then observe and continue.' }));
+                recovery: 'Call browser.act open with the same app now; it needs no approval. It returns the app as it is.' }));
         }
+        const cause = /stale|latest observation/i.test(error.message) ? 'stale-observation'
+            : /changed since|moved|redirect|different page/i.test(error.message) ? 'redirect' : 'stale-ref';
+        this.#stop(cause, ctx);
         this.#message = error.message;
-        this.#state = ++this.#preconditionFailures >= 3 ? 'paused' : 'running';
-        if (this.#state === 'paused')
-            this.#message += ' Repeated targeting failures: ask the owner to inspect and resume. No input was dispatched.';
-        // Recover evidence, never replay input. Keep this a failed tool result
-        // so the runtime skips any remaining sequential calls in this batch.
-        try {
-            const observation = await this.driver.observe();
-            const picture = await this.driver.screenshot();
-            controller.signal.throwIfAborted();
-            this.#observation = this.#stamp(observation);
-            this.#picture = picture;
-            this.#observationFailures = 0;
-        }
-        catch (observationError) {
-            controller.signal.throwIfAborted();
-            const cause = observationError instanceof Error ? observationError.message : String(observationError);
-            const targeting = this.#state === 'paused';
-            const paused = this.#observationFailed(cause) || targeting;
-            if (paused)
-                this.#state = 'paused';
-            this.#message += ` Recovery observation failed: ${cause.replace(/\.$/, '')}.${paused ? ' Inspect the selected app/window and this error, then resume and observe. Do not retry while paused.' : APP_BEHIND.test(cause) ? '' : ` ${browserWaitMessage()}`}`;
+        if (++this.#targetingFailures >= MAX_TARGETING_FAILURES) {
+            this.#stop('targeting-cap', ctx, 'card');
+            return this.#cardResult(this.park('budget'), false);
         }
-        throw new BrowserPreconditionError(JSON.stringify({ error: this.#message, dispatched: false,
-            ...(this.#observation?.observedAt ? { message: observedLine(this.#observation.observedAt) } : {}),
-            recovery: this.#state === 'paused' ? 'Wait for owner resume. Do not retry.' : this.#needsObservation ? (APP_BEHIND.test(this.#message) ? 'Call browser.act open with the same app; it needs no approval. Then observe.' : browserWaitMessage()) : 'Re-evaluate using the fresh observation below. Prefer target:{ref:"..."} and this observation.id. Do not guess an index or reuse the previous observation.',
-            observation: this.#observation }));
+        const seen = await this.#look(controller, ctx).catch(() => false);
+        throw new BrowserPreconditionError(JSON.stringify({ error: error.message, dispatched: false,
+            ...(seen && this.#observation?.observedAt ? { message: `${observedLine(this.#observation.observedAt)} The page changed; here it is now.` } : {}),
+            recovery: seen ? 'Nothing was done. Re-evaluate from the page below and act on it; prefer target:{ref:"..."} from it.' : browserWaitMessage(),
+            ...(seen ? { observation: this.#observation } : {}) }));
     }
     /**
-     * The authority shell the secret tools run under: exactly `execute`'s gates —
-     * the same authenticated owner request, the same single-owner lock, the same
-     * stopped/busy/paused/fresh-evidence refusals, the same step and expiry
-     * budget — and its start sequence and precondition path. A secret fill is a
-     * browser action like any other; only the value's route differs.
+     * The authority shell the secret tools run under: the same page, budget and
+     * card rules as `execute`. A secret fill is a browser action like any other;
+     * only the value's route differs.
      */
-    async #under(ctx, action, run) {
-        ctx.signal?.throwIfAborted();
-        const request = ctx.ownerRequest;
-        if (!request || !request.id || !request.text.trim() || request.expiresAt <= this.#now() ||
-            !ctx.agentId || !ctx.conversationId || (ctx.delegationDepth ?? 0) > 0) {
-            throw new Error('A current authenticated owner request is required.');
-        }
-        if (!this.#enabled)
-            throw new Error('Browser driving is available through buddi serve (dashboard or Telegram), not a separate CLI process.');
-        if (this.#state === 'stopped')
-            throw new Error(browserStoppedMessage(ctx.surface));
-        if (this.#busy)
-            throw new Error('Browser is busy; overlapping actions are refused.');
-        if (this.#session && (this.#session.ownerId !== ctx.buddi.owner.id || this.#session.agentId !== ctx.agentId || this.#session.conversationId !== ctx.conversationId)) {
-            throw new Error('Another agent/conversation owns the browser. Ask the owner to release it from the dashboard.');
-        }
-        if (this.#spent.has(request.id))
-            throw new Error('This browser request has ended. A new owner message is required.');
-        if (this.#state === 'paused')
-            throw new Error('Browser is under human control or needs inspection. Wait for the owner to resume in the dashboard, then observe.');
-        if (this.#needsObservation)
-            throw new Error('A fresh observation is required: observe the current page before acting. Do not replay an earlier action.');
-        if (!this.#session)
-            throw new Error('Start with navigate, or open an allowed application, and observe before using a secret here.');
-        if (this.#session.requestId !== request.id)
-            this.#rekey(request, ctx.agentId, ctx.conversationId, ctx.buddi.owner.id);
-        const active = this.#session;
-        if (!active || Date.parse(active.expiresAt) <= this.#now() || active.steps >= active.maxSteps) {
-            await this.#release('expired');
-            throw new Error('Browser task reached its time or step limit. Ask the owner for a new request.');
-        }
-        ++active.steps;
-        this.#busy = true;
-        this.#lastAction = action;
-        this.#message = undefined;
-        const controller = new AbortController();
-        this.#controller = controller;
-        const cancel = () => {
-            controller.abort(ctx.signal?.reason ?? new Error('Browser action stopped.'));
-            this.#spent.add(request.id);
-            void this.#release('stopped');
-            void this.#persistStop(true).catch(() => { });
-        };
-        ctx.signal?.addEventListener('abort', cancel, { once: true });
-        try {
-            this.#state = 'starting';
-            await this.driver.start();
-            controller.signal.throwIfAborted();
+    #under(ctx, action, run) {
+        return this.#serial(async () => {
             ctx.signal?.throwIfAborted();
-            this.#state = 'running';
-            return await run(controller);
-        }
-        catch (error) {
-            if (!controller.signal.aborted && error instanceof BrowserPreconditionError) {
-                await this.#precondition(controller, error);
+            if (!ctx.agentId || !ctx.conversationId)
+                throw new Error('A browser action belongs to an agent and a conversation.');
+            if (!this.#enabled)
+                throw new Error('Browser driving is available through buddi serve (dashboard or Telegram), not a separate CLI process.');
+            if (this.#state === 'stopped')
+                throw new Error(browserStoppedMessage(ctx.surface));
+            if (this.#session && (this.#session.ownerId !== ctx.buddi.owner.id || this.#session.agentId !== ctx.agentId || this.#session.conversationId !== ctx.conversationId)) {
+                throw new Error('Another conversation owns this page.');
             }
-            if (!controller.signal.aborted) {
-                // A failed fill or a failed typing is an uncertain input: the value may
-                // be part-way into the field, so the session pauses rather than invites
-                // a repeat, exactly as a fill or a click does.
-                this.#state = 'paused';
-                this.#message = `${error instanceof Error ? error.message : String(error)} The action may have partially completed. Inspect it before resuming; do not repeat a submission.`;
+            if (this.#state === 'paused')
+                throw new Error('The owner has this page in their hands. Wait for them to give it back.');
+            if (!this.#session)
+                throw new Error('Open the page with browser.act navigate before using a secret here.');
+            this.#open(ctx.ownerRequest, ctx);
+            if (this.#card)
+                return this.#cardResult(this.#card, false);
+            const active = this.#session;
+            if (active.steps >= active.maxSteps || Date.parse(active.expiresAt) <= this.#now()) {
+                this.#stop('budget', ctx);
+                return this.#cardResult(this.park('budget'), false);
             }
-            throw error;
-        }
-        finally {
-            ctx.signal?.removeEventListener('abort', cancel);
-            if (this.#controller === controller)
-                this.#controller = undefined;
-            this.#busy = false;
-        }
+            ++active.steps;
+            ++active.actions;
+            this.#busy = true;
+            this.#lastAction = action;
+            this.#lastActivity = this.#now();
+            this.#message = undefined;
+            const controller = new AbortController();
+            this.#controller = controller;
+            const cancel = () => { controller.abort(ctx.signal?.reason ?? new Error('Browser action stopped.')); void this.#release('idle'); };
+            ctx.signal?.addEventListener('abort', cancel, { once: true });
+            try {
+                this.#state = 'starting';
+                await this.driver.start();
+                controller.signal.throwIfAborted();
+                this.#state = 'running';
+                return await run(controller);
+            }
+            catch (error) {
+                if (controller.signal.aborted)
+                    throw error;
+                if (error instanceof BrowserPreconditionError)
+                    return await this.#precondition(controller, error, ctx);
+                // The value may be part-way into the field: the owner looks.
+                this.#state = 'running';
+                this.#stop('uncertain-input', ctx, 'card');
+                return this.#cardResult(this.park('uncertain'), true, `${error instanceof Error ? error.message.replace(/\.$/, '') : String(error)}. I'm not sure that went through.`);
+            }
+            finally {
+                ctx.signal?.removeEventListener('abort', cancel);
+                if (this.#controller === controller)
+                    this.#controller = undefined;
+                this.#busy = false;
+                this.#settled();
+            }
+        });
+    }
+    /** After a fill or typing the page changed: answer with it, as every action does. */
+    async #after(controller, ctx, result) {
+        const seen = await this.#look(controller, ctx).catch(() => false);
+        return seen ? { ...result, observation: this.#observation, message: observedLine(this.#observation.observedAt) } : result;
     }
     /**
      * One owner secret into one field of the page this conversation drives
-     * (docs/owner-secrets.md §3, §4).
-     *
-     * The order is the security argument. The driver reads the field's frame
-     * origin, its password mark and its accessible name from the live page — the
-     * backend reports, the agent never claims (§8) — then core finds the binding,
-     * the destination checks that target against it, the rule is applied and the
-     * vault read, and the destination's `deliver` parks the value against the use
-     * id. Only then does the driver fill, re-checking the origin once more
-     * against what the use was delivered for. The result is `{ filled: true }`
-     * or a pending card; a refusal is the refusal's own sentence, and a value
-     * appears in none of them.
+     * (docs/owner-secrets.md §3, §4). The driver reads the field's frame origin,
+     * its password mark and its name from the live page; core finds the binding
+     * and the destination checks it; the value crosses only into the fill.
      */
     async secretFill(input, ctx) {
-        return this.#under(ctx, 'secret.fill', async () => {
+        return this.#under(ctx, 'secret.fill', async (controller) => {
             if (typeof this.driver.secretFieldInfo !== 'function' || typeof this.driver.secretFillField !== 'function') {
-                throw new BrowserPreconditionError('secret.fill works in Playwright browser automation or in the buddi extension mode; this mode has no page fields to fill. Switch modes on the dashboard Settings page.');
+                throw new BrowserPreconditionError('secret.fill works on web pages (buddi\'s own browser or your Chrome); an app window has no page fields to fill.');
             }
-            const facts = await this.driver.secretFieldInfo(input.observation, input.ref);
+            const observation = input.observation ?? this.#observation?.id ?? '';
+            const facts = await this.driver.secretFieldInfo(observation, input.ref);
             const secrets = ctx.buddi?.secrets;
             if (secrets === undefined)
                 throw new Error('This plugin has no secrets area; the owner updates the browser plugin to one that declares it.');
@@ -464,12 +547,10 @@ export class BrowserService {
             if (secret === undefined) {
                 throw new BrowserPreconditionError(`There is no secret named "${input.name}" bound to this browser's destinations. The owner keeps one in Settings, under Keys and secrets.`);
             }
-            // A visible field on an origin the owner bound as browser.field takes
-            // that binding; the card then names the field (§3).
             const visibleField = !secret.totp && !facts.password && fieldBoundTo(secret.bindings, facts.origin);
             const kind = secretKindFor(secret.totp, facts.password, visibleField);
             if (kind === FORM_KIND && facts.name.trim() === '') {
-                throw new BrowserPreconditionError('That field has no name the page gives it, so it cannot be a form-field destination. Observe again, or ask the owner to bind the secret to the page instead.');
+                throw new BrowserPreconditionError('That field has no name the page gives it, so it cannot be a form-field destination. Pick another ref, or ask the owner to bind the secret to the page instead.');
             }
             const named = { origin: facts.origin, field: facts.name };
             const target = kind === FORM_KIND || (visibleField && facts.name.trim() !== '') ? named : facts.origin;
@@ -482,26 +563,15 @@ export class BrowserService {
             const value = takeDelivered(outcome.use);
             if (value === undefined)
                 throw new Error('The use delivered nothing to fill with. Ask for the secret again.');
-            await this.driver.secretFillField(input.observation, input.ref, value, facts.origin);
-            this.#needsObservation = true; // The field just changed; the next action observes first.
-            return { filled: true };
+            await this.driver.secretFillField(observation, input.ref, value, facts.origin);
+            return this.#after(controller, ctx, { filled: true });
         });
     }
-    /**
-     * One owner secret typed into the focused field of the focused app
-     * (owner-secrets.md §3, native typing).
-     *
-     * The bundle id is the backend's answer about whatever app is in front right
-     * now, and the helper re-checks it before the first keystroke, so an app
-     * switch between the owner's approval and the typing refuses with nothing
-     * typed. There is no observed target here — the field is whatever the owner
-     * left focused — which is why the destination's loosest rule is a card every
-     * time.
-     */
+    /** One owner secret typed into the focused field of the focused app (owner-secrets.md §3, native typing). */
     async secretType(input, ctx) {
-        return this.#under(ctx, 'secret.type', async () => {
+        return this.#under(ctx, 'secret.type', async (controller) => {
             if (typeof this.driver.focusedBundleId !== 'function' || typeof this.driver.nativeType !== 'function') {
-                throw new BrowserPreconditionError('secret.type works in Computer mode, which types into the focused app on this machine through macOS accessibility; this mode has no native typing. Switch modes on the dashboard Settings page.');
+                throw new BrowserPreconditionError('secret.type types into an app on this machine; a web page takes secret.fill instead.');
             }
             const bundleId = await this.driver.focusedBundleId();
             if (!bundleId)
@@ -519,32 +589,36 @@ export class BrowserService {
             if (value === undefined)
                 throw new Error('The use delivered nothing to type. Ask for the secret again.');
             await this.driver.nativeType(value);
-            this.#needsObservation = true; // The screen just changed; the next action observes first.
-            return { typed: true };
+            return this.#after(controller, ctx, { typed: true });
         });
     }
-    async #persistStop(stopped) {
-        if (!this.options.controlFile)
-            return;
-        const file = this.options.controlFile;
-        const write = async () => {
-            await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
-            const temp = `${file}.${randomUUID()}.tmp`;
-            await writeFile(temp, JSON.stringify({ stopped }), { mode: 0o600 });
-            await rename(temp, file);
-        };
-        const next = this.#diskTail.then(write, write);
-        this.#diskTail = next.catch(() => { });
-        await next;
+    #markHeldEnd() {
+        const id = this.#session?.id;
+        if (id)
+            this.#lastHeld = { id, until: this.#now() + LOGIN_GRACE_MS };
+    }
+    /** The action in flight went (its `finally` ran): whoever waited on it hears. */
+    #settled() {
+        for (const resolve of this.#settleWaiters.splice(0))
+            resolve();
     }
     /**
-     * Stop the action, keep the screen if the driver can.
-     *
-     * True when there is still something to drive afterwards. A driver with no
-     * `interrupt` — or one whose page really did go — has its screen closed
-     * instead, which is the old behaviour and still the honest answer when there
-     * is nothing left to paint.
+     * The interrupted action, stopped and gone: abort it again, interrupt the
+     * driver, and wait for its `finally` — at most a few seconds, because a give
+     * back must not hang on an action that will not finish.
      */
+    async #settle(limitMs = 10_000) {
+        this.#controller?.abort(new Error('Owner took control during an action. Inspect the site before retrying.'));
+        const gone = new Promise((resolve) => { this.#settleWaiters.push(resolve); });
+        if (this.driver.interrupt)
+            await this.#interrupt().catch(() => false);
+        if (!this.#busy)
+            return;
+        let timer;
+        await Promise.race([gone, new Promise((resolve) => { timer = setTimeout(resolve, limitMs); timer.unref?.(); })]);
+        clearTimeout(timer);
+    }
+    /** Stop the action, keep the screen if the driver can. True when there is still something to drive. */
     async #interrupt() {
         if (!this.driver.interrupt) {
             await this.driver.close().catch(() => { });
@@ -560,11 +634,20 @@ export class BrowserService {
         return this.driver.handReady?.() !== false;
     }
     async #release(state) {
-        this.#needsObservation = false;
+        const session = this.#session;
+        if (session && this.options.telemetry) {
+            this.options.telemetry.record({ type: 'browser.task', outcome: this.#card ? (this.#card.kind === 'budget' ? 'budget' : 'needs-owner') : state === 'stopped' ? 'stopped' : 'done',
+                actions: session.actions, seconds: Math.round((this.#now() - session.startedAt) / 1000), cards: session.cards, agent: session.agentId, route: this.#route, ...(session.requestId === 'unattended' ? { mission: true } : {}) });
+        }
+        if (this.#observation?.url)
+            this.#lastUrl = this.#observation.url;
         this.#handless = false;
+        if (this.#held) {
+            this.#markHeldEnd();
+            this.#held = false;
+            this.driver.resume?.();
+        }
         this.#state = state;
-        if (this.#session)
-            this.#spent.add(this.#session.requestId);
         this.#controller?.abort(new Error(`Browser ${state}. An in-flight submission may have completed; inspect before retrying.`));
         clearTimeout(this.#expiry);
         this.#session = undefined;
@@ -572,69 +655,89 @@ export class BrowserService {
         this.#picture = undefined;
         this.#lastAction = undefined;
         this.#message = undefined;
-        this.#preconditionFailures = 0;
-        this.#observationFailures = 0;
+        this.#card = undefined;
+        this.#targetingFailures = 0;
         await this.driver.close();
     }
+    /**
+     * Take over a page in the owner's own Chrome: no stream, the tab itself.
+     * An action in flight is abandoned first (the tab is kept), then the tab is
+     * brought to the front of their Chrome with its bar saying buddi waits.
+     * When Chrome cannot do that (closed, an extension too old to know how),
+     * the page stays paused and the message says where it is instead.
+     */
+    async #holdInPlace() {
+        this.#held = false;
+        if (this.#busy) {
+            this.#controller?.abort(new Error('Owner took control during an action. Inspect the site before retrying.'));
+            this.#picture = undefined;
+            this.#observation = undefined;
+            await this.#interrupt();
+        }
+        try {
+            await this.driver.takeover?.();
+            this.#held = true;
+            this.#message = 'The page is in front of you in your Chrome. Give it back when you are done.';
+        }
+        catch (error) {
+            const why = error instanceof Error ? error.message.replace(/\.$/, '') : String(error);
+            this.#message = `Your Chrome couldn't bring the page forward (${why}). It is in the buddi tab group there; give it back when you are done.`;
+        }
+    }
     /** Only authenticated owner UI handlers call this; it is not an agent tool. */
     control(action, expectedSessionId) {
         const run = async () => {
             if (!this.#enabled)
                 throw new Error('The host browser service is unavailable.');
             if (expectedSessionId !== undefined && this.#session?.id !== expectedSessionId) {
-                throw new Error('The browser session changed. Refresh before controlling it.');
+                throw new Error('The page changed. Refresh before controlling it.');
             }
             if (action === 'stop') {
-                // Revoke in memory before disk IO, so a pending call cannot race it.
-                const closing = this.#release('stopped');
-                await this.#persistStop(true);
-                await closing;
+                await this.#release('stopped');
             }
             else if (action === 'takeover') {
                 this.#state = 'paused';
                 this.#message = undefined;
-                if (this.#busy) {
-                    // The owner presses Take over *because* the agent is working: it
-                    // reached a login, an MFA prompt or a consent banner and is still
-                    // going round on it. That page is the whole point of the button, so
-                    // the action is abandoned and the page is kept. Every branch of
-                    // `execute` that would otherwise decide what this failure means is
-                    // guarded by `controller.signal.aborted`, so aborting here is also
-                    // what stops the interrupted command from overwriting `paused`.
+                this.#card = undefined;
+                if (this.driver.holdsInPlace) {
+                    await this.#holdInPlace();
+                }
+                else if (this.#busy) {
+                    // Take over is pressed most often *while* the agent works on a login:
+                    // the action is abandoned and the page kept, when the driver can.
                     this.#controller?.abort(new Error('Owner took control during an action. Inspect the site before retrying.'));
                     this.#picture = undefined;
                     this.#observation = undefined;
-                    this.#needsObservation = !!this.#session;
                     const kept = await this.#interrupt();
                     this.#handless = !kept;
                     this.#message = kept
-                        ? 'The in-flight action was interrupted; the page is still open and yours to use. Resume here when ready, then ask the agent to observe.'
-                        : this.driver.preservesWindows ? 'Computer input was interrupted. Your apps remain open. Inspect the result, resume, then ask the agent to observe.' : 'The in-flight action was interrupted and the window closed. Resume and ask the agent to navigate again.';
+                        ? 'The action in flight was stopped; the page is yours. Give it back when you are done.'
+                        : this.driver.preservesWindows ? 'Computer input was interrupted. Your apps remain open. Give it back when you are done.' : 'The action in flight was stopped and the window closed. Give it back and the agent opens the page again.';
                 }
                 else {
                     await this.driver.takeover?.();
-                    this.#message = this.driver.preservesWindows ? 'Computer control is paused. Use the selected app, then resume here and ask the agent to observe.' : 'Use this conversation’s host tab for login or manual work. Resume here when ready, then ask the agent to observe.';
+                    this.#message = this.driver.preservesWindows ? 'The app is yours. Give it back when you are done.' : 'The page is yours. Give it back when you are done.';
                 }
             }
             else if (action === 'resume') {
+                // Given back while the interrupted action is still stopping: stop it for good and wait for it, then give back. Never a refusal:
+                // the owner's Chrome has already taken its bar down.
                 if (this.#busy)
-                    throw new Error('Wait for the interrupted action to settle before resuming.');
-                await this.#persistStop(false);
+                    await this.#settle();
+                if (this.#held)
+                    this.#markHeldEnd();
                 this.driver.resume?.();
                 this.#handless = false;
-                this.#preconditionFailures = 0;
-                this.#observationFailures = 0;
+                this.#held = false;
                 this.#observation = undefined;
                 this.#picture = undefined;
-                this.#needsObservation = !!this.#session;
-                if (this.#session && Date.parse(this.#session.expiresAt) <= this.#now())
-                    await this.#release('idle');
+                // The owner acted: a fresh budget, and the agent's next action returns the page as the owner left it.
+                this.renew();
                 this.#state = this.#session ? 'running' : 'idle';
-                this.#message = 'Ready. Send a new message to the agent to continue.';
+                this.#message = 'Given back. The agent carries on from the page as you left it.';
             }
             else {
-                const stopped = this.#state === 'stopped';
-                await this.#release(stopped ? 'stopped' : 'idle');
+                await this.#release(this.#state === 'stopped' ? 'stopped' : 'idle');
             }
             return this.status();
         };