ptbk 0.119.0-70 → 0.119.0-71

package/README.md

@@ -11,6 +11,7 @@
   <a href="#quickstart"><strong>Quickstart</strong></a> ·
   <a href="#deploy-to-your-own-server"><strong>Deploy</strong></a> ·
   <a href="https://www.ptbk.io/en"><strong>Website</strong></a> ·
+  <a href="design/README.md"><strong>Brand</strong></a> ·
   <a href="specs/_main.md"><strong>Specifications</strong></a> ·
   <a href="https://www.ptbk.io/en/partnership"><strong>For partners</strong></a>
 </p>
@@ -63,10 +64,12 @@ Agents explicitly call you with `+@User` when they need a response. Viewing that
 
 A background engine [updates itself](specs/cli/updates.md) when it has no other work: stable minor and patch releases of its major version, or a running prerelease to its stable release. It never installs a version your `ptbk.json` `updates` pin or range excludes, or one that needs a newer Node.js than your host runs, and you can switch it off on the dashboard's System page. Release signing and rollout delays are still being agreed with the platform, so your host access and backups still matter.
 
-**Windows:** download the EXE from [GitHub Releases](https://github.com/webgptorg/promptbook/releases), or follow the [installation guide](https://www.ptbk.io/en/open-source). The installer offers the local desktop client (selected by default), Codex and Claude Code. The desktop uses the same engine and initializer as the CLI, with an embedded CLI terminal; closing a window leaves your engines running. CLI-only installation remains available.
+**Windows:** download the EXE from [GitHub Releases](https://github.com/webgptorg/promptbook/releases), or follow the [installation guide](https://www.ptbk.io/en/open-source). The installer offers the local desktop client (selected by default). Open the app to set up your project and choose AI tools. The desktop uses the same engine and initializer as the CLI, with an embedded CLI terminal; closing a window leaves your engines running. CLI-only installation remains available.
 
 **macOS:** download the matching DMG from [GitHub Releases](https://github.com/webgptorg/promptbook/releases). Choose `arm64` for Apple Silicon or `x64` for Intel, then drag Promptbook into Applications. Node.js, npm and the matching engine are included. Project setup uses Git from your Mac, such as Git from the Xcode Command Line Tools. See the [desktop installation guide](apps/desktop/README.md#macos-installation) for signing and login details.
 
+**Android preview:** download the ARM64 APK from [GitHub Releases](https://github.com/webgptorg/promptbook/releases). It includes the local engine, Node.js, Git and Gemini CLI. The app runs the engine in an Android foreground service and opens the project dashboard. See the [Android installation guide](apps/android/README.md) for setup and signing details.
+
 ## Deploy to your own server
 
 **A clean Ubuntu 24.04 LTS x86-64 server** with systemd, outbound HTTPS and root or sudo access over SSH needs no preinstalled Node.js, npm, Git, Chrome or AI harness: use the [one-command installation](#clean-ubuntu-vps). It prepares the server through the [shared installer](deploy/ubuntu/install.sh) and opens `ptbk init` as a dedicated non-sudo `promptbook` user. Sign-in to Codex or Claude Code is finished on your phone or computer; see the [server guide](deploy/README.md#finish-setup-over-ssh).

package/dist/browser/browser.d.ts

@@ -5,6 +5,7 @@ import type { ControlOutcome } from '../service/actions.js';
 import { promptbookAppData } from '../common/app-data.js';
 import { BrowserRecorder } from './recording.js';
 import { BrowserPools, profileOwnerPid } from './pool.js';
+import { TabReservations } from './tab-reservations.js';
 import { type SignInPage } from '../wallet/wallet.js';
 /**
  * Pressed-button bit of each mouse button in DevTools mouse events.
@@ -96,11 +97,26 @@ declare class CdpConnection {
     waitFor(method: string | readonly string[], timeoutMs: number, sessionId?: string): Promise<Record<string, unknown> | undefined>;
     /** Subscribes to protocol events; returns the unsubscribe function. */
     on(listener: (message: Record<string, unknown>) => void): () => void;
-    /** Notifies when the connection closes (browser exit or crash). */
-    onClose(listener: () => void): void;
+    /** Notifies when the connection closes (browser exit or crash); returns the unsubscribe function. */
+    onClose(listener: () => void): () => void;
+    /** Commands of one session still waiting for their result (an operation in flight on that tab). */
+    pendingFor(sessionId: string): number;
     /** Closes the socket (an intentional close does not notify close listeners). */
     close(): void;
 }
+/**
+ * The DevTools protocol connection of an engine's shared browser as the tab-control session uses it.
+ *
+ * @private project browser
+ */
+export type CdpLink = Pick<CdpConnection, 'send' | 'on' | 'waitFor' | 'onClose' | 'pendingFor'>;
+/**
+ * How long the set of user-controlled tabs of a profile is reused before it is read again (every engine sharing the
+ * profile notices a new reservation within this bound; control starts only after it).
+ *
+ * @private project browser
+ */
+export declare const RESERVATION_CACHE_MS = 300;
 /**
  * Observed health of one named browser's connection (engine-owned diagnosis and recovery; never inferred from
  * configuration).
@@ -149,7 +165,7 @@ export declare class ProjectBrowser {
     private readonly recordingEnabled;
     private readonly pools;
     /** This engine's identity in the pool. */
-    private readonly instanceId;
+    readonly instanceId: string;
     private connection?;
     /** The pool record this connection was made through (process, endpoint, actual mode). */
     private record?;
@@ -164,6 +180,14 @@ export declare class ProjectBrowser {
     private health;
     /** Tabs of this engine's active tasks, by task scope. */
     private readonly sessions;
+    /** The shared browser-control boundary of the profile (user-controlled tabs of every connected engine). */
+    readonly reservations: TabReservations;
+    /** The user-controlled tabs as last read (briefly reused). */
+    private reservedCache?;
+    /** Called before this engine disconnects (user-controlled tabs are closed rather than left to another engine). */
+    beforeDisconnect?: () => Promise<void>;
+    /** Checks the shared reservations while connected. */
+    private reservationWatch?;
     constructor(project: Project, 
     /** Name of the browser tool this instance serves. */
     name: string, target: () => BrowserTarget | undefined, env: NodeJS.ProcessEnv, 
@@ -171,6 +195,33 @@ export declare class ProjectBrowser {
     onChange?: () => void, recordingEnabled?: () => boolean, pools?: BrowserPools, 
     /** This engine's identity in the pool. */
     instanceId?: string);
+    /** The project directory of this engine. */
+    get projectRoot(): string;
+    /** The actual profile directory of the current connection. */
+    get profile(): string | undefined;
+    /**
+     * Tabs of this profile a user controls now, across every engine connected to it (reused for a short bound, so
+     * every engine notices a new reservation before the user's control starts).
+     */
+    reservedTabs(): Promise<ReadonlySet<string>>;
+    /** Forgets the cached reservations (this engine just changed one). */
+    invalidateReservations(): void;
+    /** The open tabs of the shared browser with the task of this engine working in each (for choosing a tab to control). */
+    pages(): Promise<Array<BrowserTab & {
+        readonly task?: string;
+        readonly reserved: boolean;
+    }>>;
+    /** The task of this engine working in a tab. */
+    ownerOf(targetId: string): TaskBrowser | undefined;
+    /** The connection the tab-control session uses. */
+    link(): Promise<CdpLink>;
+    /** A user handed a tab back: tasks that gave it up are told to revalidate it before acting on it. */
+    handedBack(targetId: string, url: string | undefined): void;
+    /**
+     * The agent operation in flight on a tab, if any: its task's session still waits for DevTools results there (the
+     * user's control starts at the next safe boundary).
+     */
+    busyOn(targetId: string): boolean;
     /** Configuration of the next use: the retained one while tasks use the connection, otherwise the saved one. */
     private config;
     /** Whether active tasks of this engine use this browser. */
@@ -221,6 +272,11 @@ export declare class ProjectBrowser {
      * is never killed.
      */
     kill(): Promise<ControlOutcome>;
+    /**
+     * A profile-wide operation conflicts with a tab a user controls: it is deferred (not applied) until that tab is
+     * handed back or its use ended, so the user's session is never cut off by automation.
+     */
+    private controlledElsewhere;
     /** Opens https://github.com/ in the actual shared browser to show that it works (a visible window keeps the tab). */
     testTab(): Promise<ControlOutcome>;
     /**
@@ -232,6 +288,10 @@ export declare class ProjectBrowser {
     private connectWithRecovery;
     /** One connection attempt to the configured profile's shared browser. */
     private connectOnce;
+    /** Tasks working in a tab a user now controls give it up (once no operation of theirs is in flight on it). */
+    private enforceReservations;
+    /** A user takes control of a tab from this engine: the task working in it gives it up now. */
+    yieldToUser(targetId: string): Promise<void>;
     /** Forgets the connection and every task tab of it (the shared process itself is not touched). */
     private dropConnection;
     /** Handles a lost connection: task tabs end, the next use reconnects (relaunching the process if needed). */
@@ -248,6 +308,12 @@ export declare class ProjectBrowser {
     /** Disconnects this engine from the shared browser; the process closes when it was the last managed connection. */
     disconnect(): Promise<void>;
 }
+/**
+ * The address an address-bar entry opens: an entry without a scheme is a website (plain HTTP for local addresses).
+ *
+ * @private project browser
+ */
+export declare function browserAddress(input: string): string;
 /**
  * One task's work in a named browser: its own tabs in the shared process (independent tasks work concurrently, never in
  * each other's tabs), its recording and every page action an agent performs. Tabs are separate, cookies and accounts
@@ -272,6 +338,12 @@ export declare class TaskBrowser {
     readonly recorder: BrowserRecorder;
     /** URL the task works on (diagnostics). */
     url?: string;
+    /** What the agent learns with its next page result (a tab the user took or returned). */
+    private notice?;
+    /** The recording is paused because the user took the tab this task worked in. */
+    private yieldedRecording;
+    /** This task received the raw DevTools endpoint (tab control states that it cannot be held back). */
+    private rawEndpoint;
     constructor(browser: ProjectBrowser, 
     /** The task scope (one per active task run). */
     scope: string, project: Project, recordingEnabled: () => boolean, env: NodeJS.ProcessEnv);
@@ -281,7 +353,28 @@ export declare class TaskBrowser {
     reset(_reason: string): void;
     /** A target session was detached (its tab closed). */
     detached(sessionId: string | undefined): void;
-    /** Ensures the connection and this task's working tab, with recording following that tab. */
+    /**
+     * Gives up the tab a user took over: the agent never acts on, inspects or records it again until it is handed back
+     * (the user-controlled interval is a labelled gap of the recording).
+     */
+    private yieldTab;
+    /**
+     * Gives up a tab a user now controls between actions: the one it works in (unless an operation of it is still in
+     * flight there and `now` is not set) or another of its own tabs.
+     */
+    giveUp(connection: CdpConnection, reserved: ReadonlySet<string>, now?: boolean): Promise<void>;
+    /** Tabs this task gave up to a user (returned ones may be selected again). */
+    private readonly yielded;
+    /** The DevTools session this task has on a tab (when it currently works in it). */
+    currentSession(targetId: string): string | undefined;
+    /** A tab this task gave up was handed back by the user: the agent revalidates it before acting on it. */
+    returned(targetId: string, url: string | undefined): void;
+    /** The note for the agent's next page result (given once). */
+    private takeNotice;
+    /**
+     * Ensures the connection and this task's working tab, with recording following that tab. A tab a user controls
+     * is never used: the current one is given up (with a note for the agent), and only tabs no user controls are chosen.
+     */
     private active;
     /** Opens a new tab of this task. */
     private newTab;
@@ -291,7 +384,7 @@ export declare class TaskBrowser {
     private attachPage;
     /** Resolves a tab id or a unique prefix of it. */
     private resolveTab;
-    /** Refuses to take over or close a tab another active task works in. */
+    /** Refuses to take over or close a tab another active task works in or a user controls. */
     private guard;
     /** Waits (bounded) until the current page finished loading. */
     private settle;

package/dist/browser/browser.js

@@ -11,6 +11,7 @@ import { createRedactor } from '../common/redact.js';
 import { promptbookAppData } from '../common/app-data.js';
 import { BrowserRecorder } from './recording.js';
 import { BrowserPools, profileOwnerPid } from './pool.js';
+import { TabReservations } from './tab-reservations.js';
 import { parseKeyPress } from './input.js';
 import { progressiveDelay, WAITING_POLICIES } from '../engine/progressive-waiting.js';
 import { MAX_PAGE_TEXT, clearLoginFieldsScript, elementObjectScript, elementPointScript, entryContentScript, entryTargetScript, focusForEntryScript, focusLoginFieldScript, followSignInLinkScript, isFileInputScript, loginFormScript, programmaticClickScript, readPageScript, setValueScript, staySignedInScript, submitFormScript, submitLoginScript, viewportScript, newPasswordFormScript, } from './page-scripts.js';
@@ -230,7 +231,7 @@ class CdpConnection {
     send(method, params = {}, sessionId) {
         const id = this.nextId++;
         return new Promise((resolve, reject) => {
-            this.pending.set(id, { resolve, reject });
+            this.pending.set(id, { resolve, reject, ...(sessionId ? { sessionId } : {}) });
             this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
         });
     }
@@ -257,9 +258,18 @@ class CdpConnection {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
     }
-    /** Notifies when the connection closes (browser exit or crash). */
+    /** Notifies when the connection closes (browser exit or crash); returns the unsubscribe function. */
     onClose(listener) {
         this.closeListeners.add(listener);
+        return () => this.closeListeners.delete(listener);
+    }
+    /** Commands of one session still waiting for their result (an operation in flight on that tab). */
+    pendingFor(sessionId) {
+        let count = 0;
+        for (const entry of this.pending.values())
+            if (entry.sessionId === sessionId)
+                count++;
+        return count;
     }
     /** Closes the socket (an intentional close does not notify close listeners). */
     close() {
@@ -267,6 +277,17 @@ class CdpConnection {
         this.socket.close();
     }
 }
+/**
+ * How long the set of user-controlled tabs of a profile is reused before it is read again (every engine sharing the
+ * profile notices a new reservation within this bound; control starts only after it).
+ *
+ * @private project browser
+ */
+export const RESERVATION_CACHE_MS = 300;
+/**
+ * How often a connected engine checks the profile's tab reservations between its tasks' actions.
+ */
+const RESERVATION_WATCH_MS = 1_000;
 /**
  * One named browser tool of this engine: its connection to the shared browser process of the tool's actual profile
  * (a [browser pool](pool.ts) that other project engines may use too) and the tabs of this engine's active tasks. The
@@ -299,6 +320,14 @@ export class ProjectBrowser {
     health = { state: 'not-started', ownership: { state: 'unknown' }, recovery: { attempts: 0, state: 'idle' } };
     /** Tabs of this engine's active tasks, by task scope. */
     sessions = new Map();
+    /** The shared browser-control boundary of the profile (user-controlled tabs of every connected engine). */
+    reservations;
+    /** The user-controlled tabs as last read (briefly reused). */
+    reservedCache;
+    /** Called before this engine disconnects (user-controlled tabs are closed rather than left to another engine). */
+    beforeDisconnect;
+    /** Checks the shared reservations while connected. */
+    reservationWatch;
     constructor(project, 
     /** Name of the browser tool this instance serves. */
     name, target, env, 
@@ -314,6 +343,63 @@ export class ProjectBrowser {
         this.recordingEnabled = recordingEnabled;
         this.pools = pools;
         this.instanceId = instanceId;
+        this.reservations = new TabReservations(env);
+    }
+    /** The project directory of this engine. */
+    get projectRoot() {
+        return this.project.root;
+    }
+    /** The actual profile directory of the current connection. */
+    get profile() {
+        return this.connectedProfile;
+    }
+    /**
+     * Tabs of this profile a user controls now, across every engine connected to it (reused for a short bound, so
+     * every engine notices a new reservation before the user's control starts).
+     */
+    async reservedTabs() {
+        const profile = this.connectedProfile;
+        if (!profile)
+            return new Set();
+        const cached = this.reservedCache;
+        if (cached && cached.profile === profile && Date.now() - cached.at < RESERVATION_CACHE_MS)
+            return cached.tabs;
+        const tabs = new Set((await this.reservations.list(profile).catch(() => [])).map((entry) => entry.targetId));
+        this.reservedCache = { at: Date.now(), profile, tabs };
+        return tabs;
+    }
+    /** Forgets the cached reservations (this engine just changed one). */
+    invalidateReservations() {
+        this.reservedCache = undefined;
+    }
+    /** The open tabs of the shared browser with the task of this engine working in each (for choosing a tab to control). */
+    async pages() {
+        const connection = await this.connect();
+        const reserved = await this.reservedTabs();
+        return (await listPages(connection)).map((page) => ({ ...page, ...(this.ownerOf(page.targetId) ? { task: this.ownerOf(page.targetId).scope } : {}), reserved: reserved.has(page.targetId) }));
+    }
+    /** The task of this engine working in a tab. */
+    ownerOf(targetId) {
+        return [...this.sessions.values()].find((session) => session.ownTabs.has(targetId));
+    }
+    /** The connection the tab-control session uses. */
+    async link() {
+        return await this.connect();
+    }
+    /** A user handed a tab back: tasks that gave it up are told to revalidate it before acting on it. */
+    handedBack(targetId, url) {
+        this.invalidateReservations();
+        for (const session of this.sessions.values())
+            session.returned(targetId, url);
+    }
+    /**
+     * The agent operation in flight on a tab, if any: its task's session still waits for DevTools results there (the
+     * user's control starts at the next safe boundary).
+     */
+    busyOn(targetId) {
+        const owner = this.ownerOf(targetId);
+        const sessionId = owner?.currentSession(targetId);
+        return Boolean(sessionId && this.connection?.pendingFor(sessionId));
     }
     /** Configuration of the next use: the retained one while tasks use the connection, otherwise the saved one. */
     config() {
@@ -478,6 +564,9 @@ export class ProjectBrowser {
         const tool = this.config();
         if (!tool)
             return this.acted('restart', 'failed', `The browser tool "${this.name}" is no longer configured.`);
+        const controlled = await this.controlledElsewhere('restart');
+        if (controlled)
+            return controlled;
         const profile = browserProfileDirectory(this.project, tool, this.env);
         const tabs = this.sessions.size;
         try {
@@ -505,6 +594,9 @@ export class ProjectBrowser {
         const tool = this.config();
         if (!tool)
             return this.acted('kill', 'failed', `The browser tool "${this.name}" is no longer configured.`);
+        const controlled = await this.controlledElsewhere('kill');
+        if (controlled)
+            return controlled;
         const profile = browserProfileDirectory(this.project, tool, this.env);
         const killed = await this.pools.kill(profile);
         this.dropConnection('The browser was killed.');
@@ -514,6 +606,17 @@ export class ProjectBrowser {
             return this.acted('kill', 'succeeded', `No Promptbook-started browser process was running for "${this.name}".`);
         return this.acted('kill', 'succeeded', `Killed the browser "${this.name}" (its profile is kept)${others.length ? `; also affected: ${others.join(', ')}` : ''}. The next use starts it again.`);
     }
+    /**
+     * A profile-wide operation conflicts with a tab a user controls: it is deferred (not applied) until that tab is
+     * handed back or its use ended, so the user's session is never cut off by automation.
+     */
+    async controlledElsewhere(action) {
+        this.invalidateReservations();
+        const reserved = await this.reservedTabs();
+        if (!reserved.size)
+            return undefined;
+        return this.acted(action, 'deferred', `Deferred: you control ${reserved.size === 1 ? 'a tab' : `${reserved.size} tabs`} of the browser "${this.name}". Return control to the agent or end your use of the tab first; nothing was ${action === 'kill' ? 'killed' : 'restarted'}.`);
+    }
     /** Opens https://github.com/ in the actual shared browser to show that it works (a visible window keeps the tab). */
     async testTab() {
         try {
@@ -622,13 +725,38 @@ export class ProjectBrowser {
         this.record = record;
         this.connectedProfile = profile;
         this.connectedWith = tool;
+        // A user may take a tab from any engine of the profile: its tasks here give it up promptly, also between actions.
+        clearInterval(this.reservationWatch);
+        this.reservationWatch = setInterval(() => void this.enforceReservations(), RESERVATION_WATCH_MS);
+        this.reservationWatch.unref();
         this.health = { ...this.health, actualMode: record.headless ? 'headless' : 'headful' };
         if (launched)
             this.note ??= undefined;
         return connection;
     }
+    /** Tasks working in a tab a user now controls give it up (once no operation of theirs is in flight on it). */
+    async enforceReservations() {
+        const connection = this.connection;
+        if (!connection || !this.sessions.size)
+            return;
+        const reserved = await this.reservedTabs();
+        if (!reserved.size)
+            return;
+        for (const session of this.sessions.values())
+            await session.giveUp(connection, reserved).catch(() => undefined);
+    }
+    /** A user takes control of a tab from this engine: the task working in it gives it up now. */
+    async yieldToUser(targetId) {
+        const connection = this.connection;
+        if (!connection)
+            return;
+        for (const session of this.sessions.values())
+            await session.giveUp(connection, new Set([targetId]), true).catch(() => undefined);
+    }
     /** Forgets the connection and every task tab of it (the shared process itself is not touched). */
     dropConnection(reason) {
+        clearInterval(this.reservationWatch);
+        this.reservationWatch = undefined;
         this.connection?.close();
         this.connection = undefined;
         this.record = undefined;
@@ -637,6 +765,8 @@ export class ProjectBrowser {
     }
     /** Handles a lost connection: task tabs end, the next use reconnects (relaunching the process if needed). */
     connectionLost(reason) {
+        clearInterval(this.reservationWatch);
+        this.reservationWatch = undefined;
         this.connection = undefined;
         this.record = undefined;
         for (const session of this.sessions.values())
@@ -679,6 +809,7 @@ export class ProjectBrowser {
     }
     /** Disconnects this engine from the shared browser; the process closes when it was the last managed connection. */
     async disconnect() {
+        await this.beforeDisconnect?.().catch(() => undefined);
         const profile = this.connectedProfile;
         const lastKnown = this.record;
         const wasConnected = Boolean(this.connection);
@@ -691,6 +822,18 @@ export class ProjectBrowser {
             this.setHealth({ state: 'stopped', ownership: { state: 'free' } });
     }
 }
+/**
+ * The address an address-bar entry opens: an entry without a scheme is a website (plain HTTP for local addresses).
+ *
+ * @private project browser
+ */
+export function browserAddress(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        throw new PtbkError('Name the URL to open.', { kind: 'usage' });
+    const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) || /^(about|blob|data|javascript|mailto|tel|view-source):/i.test(trimmed);
+    return hasScheme ? trimmed : `${/^(localhost|127\.|0\.0\.0\.0|\[::1\])/i.test(trimmed) ? 'http' : 'https'}://${trimmed}`;
+}
 /**
  * The open pages (tabs) of a browser connection.
  */
@@ -721,6 +864,12 @@ export class TaskBrowser {
     recorder;
     /** URL the task works on (diagnostics). */
     url;
+    /** What the agent learns with its next page result (a tab the user took or returned). */
+    notice;
+    /** The recording is paused because the user took the tab this task worked in. */
+    yieldedRecording = false;
+    /** This task received the raw DevTools endpoint (tab control states that it cannot be held back). */
+    rawEndpoint = false;
     constructor(browser, 
     /** The task scope (one per active task run). */
     scope, project, recordingEnabled, env) {
@@ -750,14 +899,77 @@ export class TaskBrowser {
         this.sessionId = undefined;
         this.targetId = undefined;
     }
-    /** Ensures the connection and this task's working tab, with recording following that tab. */
+    /**
+     * Gives up the tab a user took over: the agent never acts on, inspects or records it again until it is handed back
+     * (the user-controlled interval is a labelled gap of the recording).
+     */
+    async yieldTab(connection, targetId) {
+        if (!this.yieldedRecording) {
+            await this.recorder.pause('The user took control of this tab; the user-controlled interval is not recorded.');
+            this.yieldedRecording = true;
+        }
+        const previous = this.sessionId;
+        this.navigationListener?.();
+        this.navigationListener = undefined;
+        this.sessionId = undefined;
+        this.targetId = undefined;
+        this.ownTabs.delete(targetId);
+        this.yielded.add(targetId);
+        if (previous)
+            await connection.send('Target.detachFromTarget', { sessionId: previous }).catch(() => undefined);
+        this.notice = `Note: the user took control of the tab ${targetId} you worked in. Do not act on it or wait for it here; it is handed back only when they choose. You now work in another tab of your own.`;
+    }
+    /**
+     * Gives up a tab a user now controls between actions: the one it works in (unless an operation of it is still in
+     * flight there and `now` is not set) or another of its own tabs.
+     */
+    async giveUp(connection, reserved, now = false) {
+        if (this.targetId && reserved.has(this.targetId) && (now || !this.sessionId || !connection.pendingFor(this.sessionId)))
+            await this.yieldTab(connection, this.targetId);
+        for (const targetId of [...this.ownTabs]) {
+            if (!reserved.has(targetId) || targetId === this.targetId)
+                continue;
+            this.ownTabs.delete(targetId);
+            this.yielded.add(targetId);
+            this.notice ??= `Note: the user took control of your tab ${targetId}. Do not act on it or wait for it here; it is handed back only when they choose.`;
+        }
+    }
+    /** Tabs this task gave up to a user (returned ones may be selected again). */
+    yielded = new Set();
+    /** The DevTools session this task has on a tab (when it currently works in it). */
+    currentSession(targetId) {
+        return this.targetId === targetId ? this.sessionId : undefined;
+    }
+    /** A tab this task gave up was handed back by the user: the agent revalidates it before acting on it. */
+    returned(targetId, url) {
+        if (!this.yielded.delete(targetId))
+            return;
+        this.notice = `Note: the user handed back the tab ${targetId}${url ? ` (now at ${url})` : ''}. It may have changed while they used it: select it with browser_tabs and read it again before acting on it, and recheck the latest instructions.`;
+    }
+    /** The note for the agent's next page result (given once). */
+    takeNotice() {
+        const notice = this.notice;
+        this.notice = undefined;
+        return notice ? `${notice}\n\n` : '';
+    }
+    /**
+     * Ensures the connection and this task's working tab, with recording following that tab. A tab a user controls
+     * is never used: the current one is given up (with a note for the agent), and only tabs no user controls are chosen.
+     */
     async active() {
         const connection = await this.browser.connect();
+        const reserved = await this.browser.reservedTabs();
+        if (this.targetId && reserved.has(this.targetId))
+            await this.yieldTab(connection, this.targetId);
         if (!this.sessionId) {
-            // Another of this task's tabs, else a new tab of its own (never another task's).
-            const own = (await listPages(connection)).find((page) => this.ownTabs.has(page.targetId));
+            // Another of this task's tabs, else a new tab of its own (never another task's or a user-controlled one).
+            const own = (await listPages(connection)).find((page) => this.ownTabs.has(page.targetId) && !reserved.has(page.targetId));
             await this.attachPage(connection, own?.targetId ?? (await this.newTab(connection)));
         }
+        if (this.yieldedRecording) {
+            this.yieldedRecording = false;
+            await this.recorder.resume();
+        }
         this.navigationListener ??= connection.on((message) => {
             if (message.method !== 'Page.frameNavigated' || message.sessionId !== this.sessionId)
                 return;
@@ -820,8 +1032,10 @@ export class TaskBrowser {
             throw new PtbkError(matches.length ? `The tab id "${id}" matches several tabs; give more of it.` : `No open tab has the id "${id}"; browser_tabs lists them.`, { kind: 'usage' });
         return matches[0].targetId;
     }
-    /** Refuses to take over or close a tab another active task works in. */
-    guard(targetId) {
+    /** Refuses to take over or close a tab another active task works in or a user controls. */
+    async guard(targetId) {
+        if ((await this.browser.reservedTabs()).has(targetId))
+            throw new PtbkError(`The tab ${targetId} is controlled by the user now; it is not yours to use until they hand it back. Work in your own tabs (open one with browser_tabs action new).`, { kind: 'conflict' });
         if (this.browser.tabsOfOthers(this.scope).has(targetId))
             throw new PtbkError(`The tab ${targetId} belongs to another task working in this browser now; work in your own tabs (open one with browser_tabs action new).`, { kind: 'usage' });
     }
@@ -833,7 +1047,8 @@ export class TaskBrowser {
     }
     /** After an action: continues in a tab the action opened (a link to a new window, `window.open`), as a person would. */
     async followNewTab(connection, before) {
-        const opened = (await listPages(connection)).filter((page) => !before.has(page.targetId));
+        const reserved = await this.browser.reservedTabs();
+        const opened = (await listPages(connection)).filter((page) => !before.has(page.targetId) && !reserved.has(page.targetId));
         const tab = opened[opened.length - 1];
         if (!tab)
             return '';
@@ -853,16 +1068,11 @@ export class TaskBrowser {
         const tabs = (await listPages(connection)).filter((candidate) => this.ownTabs.has(candidate.targetId)).length;
         const omitted = page.omitted ? `\n… ${page.omitted} more elements are not listed (scroll to them, or use browser_evaluate).` : '';
         const note = this.browser.modeNote;
-        return `${page.title}\n${page.url}${tabs > 1 ? `\n(${tabs} of your tabs are open; browser_tabs lists and switches them)` : ''}\n\n${page.text}\n\nInteractive elements (their numbers are the ref of other browser tools):\n${page.elements.join('\n') || '(none)'}${omitted}${note ? `\n\nNote: ${note}` : ''}`;
+        return `${this.takeNotice()}${page.title}\n${page.url}${tabs > 1 ? `\n(${tabs} of your tabs are open; browser_tabs lists and switches them)` : ''}\n\n${page.text}\n\nInteractive elements (their numbers are the ref of other browser tools):\n${page.elements.join('\n') || '(none)'}${omitted}${note ? `\n\nNote: ${note}` : ''}`;
     }
     /** Navigates the current tab (or a new one) to any URL and waits for it to load (bounded). */
     async open(url, newTab = false) {
-        const trimmed = url.trim();
-        if (!trimmed)
-            throw new PtbkError('Name the URL to open.', { kind: 'usage' });
-        // An address without a scheme is a website, as in the address bar (plain HTTP for local addresses).
-        const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) || /^(about|blob|data|javascript|mailto|tel|view-source):/i.test(trimmed);
-        const address = hasScheme ? trimmed : `${/^(localhost|127\.|0\.0\.0\.0|\[::1\])/i.test(trimmed) ? 'http' : 'https'}://${trimmed}`;
+        const address = browserAddress(url);
         const { connection } = await this.active();
         if (newTab)
             await this.attachPage(connection, await this.newTab(connection));
@@ -903,8 +1113,10 @@ export class TaskBrowser {
         const { connection } = await this.active();
         const pages = await listPages(connection);
         const others = this.browser.tabsOfOthers(this.scope);
-        const mark = (page) => (page.targetId === this.targetId ? '*' : this.ownTabs.has(page.targetId) ? '-' : others.has(page.targetId) ? 'x' : 'o');
-        return `Open tabs (* = the tab you work in, - = your other tabs, x = another task's tab (not yours to use), o = other tabs; a unique prefix of an id is enough):\n${pages.map((page) => `${mark(page)} ${page.targetId}  ${page.title || '(untitled)'}  ${page.url}`).join('\n')}`;
+        const reserved = await this.browser.reservedTabs();
+        const mark = (page) => (reserved.has(page.targetId) ? 'u' : page.targetId === this.targetId ? '*' : this.ownTabs.has(page.targetId) ? '-' : others.has(page.targetId) ? 'x' : 'o');
+        // A user-controlled tab is listed without its address or title: it is not observed while the user has it.
+        return `${this.takeNotice()}Open tabs (* = the tab you work in, - = your other tabs, x = another task's tab (not yours to use), u = controlled by the user (not yours to use), o = other tabs; a unique prefix of an id is enough):\n${pages.map((page) => (reserved.has(page.targetId) ? `u ${page.targetId}  (controlled by the user)` : `${mark(page)} ${page.targetId}  ${page.title || '(untitled)'}  ${page.url}`)).join('\n')}`;
     }
     /** Opens a new tab (optionally at a URL), switches to a tab or closes one (never another task's). */
     async tab(action, id, url) {
@@ -918,7 +1130,7 @@ export class TaskBrowser {
         const targetId = id?.trim() ? await this.resolveTab(connection, id) : this.targetId;
         if (!targetId)
             throw new PtbkError('Name the tab id (browser_tabs lists them).', { kind: 'usage' });
-        this.guard(targetId);
+        await this.guard(targetId);
         if (action === 'select') {
             await this.attachPage(connection, targetId);
             return await this.read();
@@ -1145,15 +1357,33 @@ export class TaskBrowser {
         if (!/^[A-Z][A-Za-z]*\.[a-z][A-Za-z]*$/.test(method.trim()))
             throw new PtbkError('Name a DevTools protocol method such as Page.printToPDF or Emulation.setGeolocationOverride.', { kind: 'usage' });
         const { connection, sessionId } = await this.active();
+        if (scope === 'browser') {
+            // While a user controls a tab of this browser, browser-wide commands cannot reach it: none naming it, none
+            // attaching to every target and none ending the browser under the user.
+            const reserved = await this.browser.reservedTabs();
+            const text = JSON.stringify(params);
+            const reaching = [...reserved].find((targetId) => text.includes(targetId));
+            const sweeping = reserved.size > 0 && /^(Target\.(setAutoAttach|attachToBrowserTarget|exposeDevToolsProtocol|setDiscoverTargets|getTargets)|Browser\.(close|crash|crashGpuProcess)|Storage\.clear)/.test(method.trim());
+            if (reaching || sweeping)
+                throw new PtbkError(`${method.trim()} would reach a tab the user controls now; it is not available until they hand it back. Use your own tabs.`, { kind: 'conflict' });
+        }
         const result = await withTimeout(connection.send(method.trim(), { ...params }, scope === 'browser' ? undefined : sessionId), SCRIPT_TIMEOUT_MS, method);
         return truncate(JSON.stringify(result, null, 2), MAX_PAGE_TEXT);
     }
     /** The local DevTools endpoint of the shared browser for the agent's own automation scripts. */
     async devtoolsEndpoint() {
         await this.active();
+        // A raw endpoint bypasses the tab boundary, so it is not handed out while a user controls a tab here.
+        if ((await this.browser.reservedTabs()).size)
+            throw new PtbkError(`The raw DevTools endpoint of "${this.name}" is unavailable while the user controls one of its tabs; use the browser tools (they keep to your own tabs).`, { kind: 'conflict' });
         const devtools = this.browser.devtools;
         if (!devtools)
             throw new PtbkError(`The browser "${this.name}" exposes no DevTools endpoint right now; try again.`, { kind: 'technical' });
+        const profile = this.browser.profile;
+        if (profile && !this.rawEndpoint) {
+            this.rawEndpoint = true;
+            await this.browser.reservations.grantRawEndpoint(profile, `${this.browser.instanceId}/${this.scope}`, this.browser.projectRoot).catch(() => undefined);
+        }
         const http = `http://127.0.0.1:${devtools.port}`;
         return [
             `HTTP endpoint: ${http}`,
@@ -1448,7 +1678,13 @@ export class TaskBrowser {
     async release() {
         this.navigationListener?.();
         this.navigationListener = undefined;
-        const tabs = [...this.ownTabs];
+        const profile = this.browser.profile;
+        if (this.rawEndpoint && profile)
+            await this.browser.reservations.revokeRawEndpoint(profile, `${this.browser.instanceId}/${this.scope}`);
+        this.rawEndpoint = false;
+        // A tab the user controls stays open and theirs; it is never closed with the task.
+        const reserved = await this.browser.reservedTabs().catch(() => new Set());
+        const tabs = [...this.ownTabs].filter((targetId) => !reserved.has(targetId));
         this.ownTabs.clear();
         this.sessionId = undefined;
         this.targetId = undefined;