Open-source AI browser agent for Chrome and Firefox (monorepo) ðŸ§
JavaScript ai-agentai-agentsai-toolsbrowser-aibrowser-automationbrowser-extensionchrome-aichrome-devtoolschrome-extensionchrome-extensionsfirefox-addonfirefox-addonsfirefox-extensionfirefox-extensionsgemmagemma4minimaxoffline-aioffline-llmqwen
Preserve browser handoff ownership through reload and cancellation
Barack Sokullu5f239661f053
diff --git a/docs/cloud-browser-handoff.md b/docs/cloud-browser-handoff.mdnew file mode 100644index 000000000..d8dbc9a0d--- /dev/null+++ b/docs/cloud-browser-handoff.md@@ -0,0 +1,24 @@+# Cloud browser handoff++Cloud runtimes advertise browser handoff through `run_handoff_v1`.++`cloud_pause` requests manual browser control for the existing run. The run stays+reserved while it is `pausing`; a writable `paused` acknowledgement follows only+after the current model/tool boundary settles and the handoff guard is saved.+Pausing a run does not suspend or power off its browser session.++`cloud_resume` returns control with an optional note. WebBrain reads the current+page before further work. The note reports state and grants no new task authority.+An existing clarification remains pending and requires its original explicit answer.++The durable `webbrainCloudHandoffGuards` record contains only run ID, tab ID, and+timestamps. Provider credentials, task content, notes, memory, and results are not+stored in this guard. A service worker restart, extension reload/update, or browser+restart restores manual ownership as interrupted and nonresumable. It never replays+the old task. Inspect the browser and explicitly abort the interrupted run before+starting further work. Other agents, scheduled runs, and Cloud tasks remain blocked+on that profile until reconciliation completes.++The guard clears only after a fresh handback observation is saved or explicit+cancellation confirms the native handler has settled, including recording cleanup.+Storage failures keep the browser read-only and preserve its reservation.diff --git a/src/chrome/src/agent/cloud-handoff.js b/src/chrome/src/agent/cloud-handoff.jsindex 0442021db..89a777bb6 100644--- a/src/chrome/src/agent/cloud-handoff.js+++ b/src/chrome/src/agent/cloud-handoff.js@@ -19,10 +19,12 @@ export class CloudHandoffGate {async acknowledge() {if (this.closed || this.state !== 'pausing') return;- this.state = 'paused';// A durable acknowledgement is required before the viewer becomes writable.await this.onState('paused');- if (!this.closed) this.stopKeepAlive = this.keepAlive();+ if (!this.closed && this.state === 'pausing') {+ this.state = 'paused';+ this.stopKeepAlive = this.keepAlive();+ }}async boundary() {diff --git a/src/chrome/src/cloud-runs.js b/src/chrome/src/cloud-runs.jsindex 5a72f0729..768cc974a 100644--- a/src/chrome/src/cloud-runs.js+++ b/src/chrome/src/cloud-runs.js@@ -12,6 +12,7 @@ const PRIVATE_RESULT_PLACEHOLDER = '[Private final answer encrypted for this worconst DEFAULT_CLOUD_BRIDGE_URL = 'ws://127.0.0.1:17374/extension';const CLOUD_RUN_STORAGE_KEY = 'webbrainCloudRunSnapshots';+const CLOUD_HANDOFF_GUARD_KEY = 'webbrainCloudHandoffGuards';const CLOUD_UPDATE_LIMIT = 200;const CLOUD_RUN_LIMIT = 50;const CLOUD_STRING_LIMIT = 16 * 1024;@@ -713,6 +714,21 @@ export function buildCloudPersistenceRows(runs) {return rows;}+// Session snapshots disappear on extension reload and browser restart. Keep+// only the identity needed to reserve manual ownership in durable storage.+function normalizeCloudHandoffGuard(row) {+ const timestamp = value => typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value)+ && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;+ // Cloud callers may supply correlation IDs containing punctuation or+ // Unicode. Match the existing start API rather than changing that contract.+ if (!row || typeof row.runId !== 'string' || !row.runId.trim() || row.runId.length > CLOUD_STRING_LIMIT+ || !Number.isSafeInteger(row.tabId) || row.tabId < 0 || row.tabId > 2147483647+ || !timestamp(row.createdAt) || !timestamp(row.updatedAt)+ || row.pausedAt != null && !timestamp(row.pausedAt)) throw new Error('Browser handoff guard could not be reconciled.');+ return { runId: row.runId, tabId: row.tabId, createdAt: row.createdAt,+ updatedAt: row.updatedAt, pausedAt: row.pausedAt || null };+}+function cloudSnapshot(run, { includeUpdates = true } = {}) {if (!run) return null;return {@@ -770,6 +786,7 @@ export function createCloudRunController({const startingRunIds = new Set();let pendingStarts = 0;const handoffGates = new Map();+ const activeExecutions = new Set();const startingConversations = new Set();const runAbortControllers = new Map();// Private envelopes live only for the active handle, outside snapshots and@@ -778,9 +795,24 @@ export function createCloudRunController({let hydratePromise = null;let persistQueue = Promise.resolve();let persistTimer = null;+ const durableHandoffGuards = new Map();+ let storedHandoffGuard = false;const isoNow = () => now().toISOString();+ function snapshot(run, options) {+ const result = cloudSnapshot(run, options);+ // Handler errors and cancellation can assign a terminal status before+ // asynchronous cleanup finishes. A retained guard remains authoritative+ // for pollers and streamers until confirmed removal releases ownership.+ if (result && durableHandoffGuards.has(run.runId) && TERMINAL_STATUSES.has(result.status)) {+ result.status = run.handoff ? 'paused' : 'aborting';+ result.handoff = run.handoff ? { ...run.handoff, state: 'paused', resumable: false, interrupted: true } : null;+ result.completedAt = null;+ }+ return result;+ }+// MV3 service workers suspend after ~30s idle; a bare setTimeout does not// reset that timer. Ping getPlatformInfo on a 20s interval for the duration// of an in-handle resume wait so Chrome keeps the worker alive. Best-effort:@@ -804,12 +836,39 @@ export function createCloudRunController({}}- async function persist() {- if (!api.storage?.session?.set) return;- const rows = buildCloudPersistenceRows(runs);+ async function persist({ clearHandoffRunId = null } = {}) {persistQueue = persistQueue.catch(() => {})- .then(() => api.storage.session.set({ [CLOUD_RUN_STORAGE_KEY]: rows }));+ .then(async () => {+ // Build inside the queue so an older ordinary checkpoint cannot put+ // back a reservation already cleared by confirmed reconciliation.+ const cancellationPending = id => activeExecutions.has(id) && runAbortControllers.get(id)?.signal.aborted;+ const clearing = [...durableHandoffGuards.entries()].filter(([id]) => {+ const run = runs.get(id);+ return !cancellationPending(id) && (id === clearHandoffRunId+ || (run && TERMINAL_STATUSES.has(run.status) && !activeExecutions.has(id)));+ });+ const clearedIds = new Set(clearing.map(([id]) => id));+ const guards = [...durableHandoffGuards.values()].filter(row => !clearedIds.has(row.runId));+ // A failed session write must not remove the durable reservation.+ await api.storage?.session?.set?.({ [CLOUD_RUN_STORAGE_KEY]: buildCloudPersistenceRows(runs) });+ if (guards.length || storedHandoffGuard || clearing.length) {+ if (!api.storage?.local?.set) throw new Error('Durable browser handoff storage is unavailable.');+ await api.storage.local.set({ [CLOUD_HANDOFF_GUARD_KEY]: guards });+ // Cancellation can arrive during an awaited handback clear. Keep+ // the in-memory reservation and restore its durable row before this+ // checkpoint can acknowledge anything or allow another actor in.+ const retained = clearing.filter(([id]) => cancellationPending(id));+ if (retained.length) {+ await api.storage.local.set({ [CLOUD_HANDOFF_GUARD_KEY]: [+ ...guards, ...retained.map(([id, row]) => durableHandoffGuards.get(id) || row),+ ] });+ }+ storedHandoffGuard = guards.length > 0 || retained.length > 0;+ const retainedIds = new Set(retained.map(([id]) => id));+ for (const [id, row] of clearing) if (!retainedIds.has(id) && durableHandoffGuards.get(id) === row) durableHandoffGuards.delete(id);+ }+ });await persistQueue;}@@ -824,9 +883,26 @@ export function createCloudRunController({async function hydrate() {if (hydratePromise) return hydratePromise;hydratePromise = (async () => {- if (!api.storage?.session?.get) return;- const stored = await api.storage.session.get(CLOUD_RUN_STORAGE_KEY);+ const local = await api.storage?.local?.get?.(CLOUD_HANDOFF_GUARD_KEY) || {};+ const guardRows = local[CLOUD_HANDOFF_GUARD_KEY] === undefined ? [] : local[CLOUD_HANDOFF_GUARD_KEY];+ if (!Array.isArray(guardRows) || guardRows.length > CLOUD_RUN_LIMIT) throw new Error('Browser handoff guard could not be reconciled.');+ for (const row of guardRows) {+ const guard = normalizeCloudHandoffGuard(row);+ if (durableHandoffGuards.has(guard.runId)) throw new Error('Browser handoff guard could not be reconciled.');+ durableHandoffGuards.set(guard.runId, guard);+ }+ storedHandoffGuard = durableHandoffGuards.size > 0;+ // Preserve main's fail-closed session read. Read failures are not proof+ // that no run owns this profile.+ const stored = await api.storage?.session?.get?.(CLOUD_RUN_STORAGE_KEY) || {};const rows = Array.isArray(stored?.[CLOUD_RUN_STORAGE_KEY]) ? stored[CLOUD_RUN_STORAGE_KEY] : [];+ for (const guard of durableHandoffGuards.values()) {+ const old = rows.findIndex(row => row?.runId === guard.runId);+ const restored = { ...(old < 0 ? { updates: [] } : rows[old]), ...guard, status: 'paused',+ handoff: { state: 'paused', resumable: false, interrupted: true,+ ...(guard.pausedAt ? { pausedAt: guard.pausedAt } : {}) }, completedAt: null };+ if (old < 0) rows.push(restored); else rows[old] = restored;+ }let changed = false;for (const row of rows) {if (!row?.runId) continue;@@ -847,6 +923,11 @@ export function createCloudRunController({// Keep the browser reserved for its owner; never replay this run.restored.status = 'paused';restored.handoff = { ...restored.handoff, state: 'paused', resumable: false, interrupted: true };+ durableHandoffGuards.set(restored.runId, normalizeCloudHandoffGuard({+ runId: restored.runId, tabId: restored.tabId,+ createdAt: durableHandoffGuards.get(restored.runId)?.createdAt || isoNow(),+ updatedAt: isoNow(), pausedAt: restored.handoff.pausedAt || null,+ }));restored.error = 'WebBrain restarted during browser handoff. Inspect the page and explicitly stop this interrupted run before starting further work.';startingTabs.add(restored.tabId);pushUpdate(restored, 'handoff', restored.handoff);@@ -1142,7 +1223,7 @@ export function createCloudRunController({}function assertNoHandoff() {- if (activeHandoff()) {+ if (durableHandoffGuards.size || activeHandoff()) {throw cloudRunError('Browser control belongs to an active handoff. Return control or explicitly reconcile the interrupted run before starting another task.', 409);}}@@ -1192,6 +1273,7 @@ export function createCloudRunController({? null : await importPrivateResultRecipient(msg.private_result_public_key);const suppliedRunId = msg.runId ?? msg.run_id;const requestedRunId = suppliedRunId == null ? '' : String(suppliedRunId).trim();+ if (requestedRunId.length > CLOUD_STRING_LIMIT) throw cloudRunError('Cloud run ID exceeds the supported length.', 400);const parentRunId = String(msg.parentRunId || msg.parent_run_id || '').trim() || null;const savedParent = parentRunId ? runs.get(parentRunId) : null;if (parentRunId) assertMemoryContinuation(savedParent, memoryOwner);@@ -1330,17 +1412,41 @@ export function createCloudRunController({};const handoffGate = new CloudHandoffGate({async onState(state) {+ const checkpoint = async options => {+ try { await persist(options); } catch (error) {+ // An abort may close the gate while this write is pending. Keep+ // cancellation pending until cleanup; never resurrect its pause.+ if (!handoffGate.closed && !cancelled()) {+ run.status = 'paused';+ run.handoff = { state: 'paused', resumable: false, interrupted: true };+ run.error = 'Browser handoff could not be saved safely. Keep the browser read-only and explicitly stop this run.';+ pushUpdate(run, 'handoff', run.handoff);+ }+ throw error;+ }+ };if (state === 'running') {+ await checkpoint({ clearHandoffRunId: run.runId });+ if (handoffGate.closed || cancelled()) return;run.handoff = null;run.status = run.pendingInput ? 'needs_user_input' : 'running';} else {+ if (handoffGate.closed || cancelled()) return;+ // Guard ownership from the pause request onwards. Neither polling+ // nor streaming may see writable paused state before this write.+ durableHandoffGuards.set(run.runId, normalizeCloudHandoffGuard({+ runId: run.runId, tabId: run.tabId, createdAt: run.createdAt, updatedAt: isoNow(),+ pausedAt: state === 'paused' ? isoNow() : run.handoff?.pausedAt || null,+ }));+ await checkpoint();+ if (handoffGate.closed || cancelled()) return;run.status = state;run.handoff = { state, resumable: true, interrupted: false,...(state === 'paused' ? { pausedAt: isoNow() } : run.handoff?.pausedAt ? { pausedAt: run.handoff.pausedAt } : {}) };}run.updatedAt = isoNow();pushUpdate(run, 'handoff', run.handoff || { state: null });- await persist();+ await checkpoint();},keepAlive() {const ping = () => { try { const p = api.runtime?.getPlatformInfo?.(() => { void api.runtime.lastError; }); p?.catch?.(() => {}); } catch {} };@@ -1378,6 +1484,7 @@ export function createCloudRunController({throw error;}+ activeExecutions.add(run.runId);(async () => {let recordingId = null;const strictSecretMode = !!recipient || agent.strictSecretMode === true;@@ -1658,6 +1765,23 @@ export function createCloudRunController({strictSecretOverflowRuns.delete(run.runId);strictTraceOverflowRuns.delete(run.runId);memoryConfigurations.delete(run.runId);+ activeExecutions.delete(run.runId);+ if (run.status === 'aborted' && durableHandoffGuards.has(run.runId)) {+ // The handler and recording cleanup have settled. Clear the durable+ // reservation before publicly acknowledging terminal cancellation.+ run.status = 'aborting';+ run.completedAt = null;+ try {+ await persist({ clearHandoffRunId: run.runId });+ run.status = 'aborted';+ run.completedAt = isoNow();+ } catch {+ run.status = 'paused';+ run.handoff = { state: 'paused', resumable: false, interrupted: true };+ run.error = 'Browser handoff cancellation could not be saved. Keep the browser read-only and explicitly stop this run again.';+ pushUpdate(run, 'handoff', run.handoff);+ }+ }sendIndicator(tabId, 'WB_HIDE_AGENT_INDICATORS');// Recording flush is still owned by this run. Keep the tab reserved// through all cleanup so aborting a nonterminal capture cannot cancel@@ -1667,7 +1791,7 @@ export function createCloudRunController({}})();- return cloudSnapshot(run, { includeUpdates: false });+ return snapshot(run, { includeUpdates: false });}async function startWorkflowRun(msg = {}) {@@ -1744,17 +1868,18 @@ export function createCloudRunController({// has finished writing; a poll cannot race a pending storage write.await persistQueue;const runId = msg.runId || msg.run_id;- if (!runId) return { runs: [...runs.values()].map(run => cloudSnapshot(run, { includeUpdates: false })) };+ if (!runId) return { runs: [...runs.values()].map(run => snapshot(run, { includeUpdates: false })) };const run = runs.get(runId);if (!run) throw new Error('Unknown cloud run.');- return cloudSnapshot(run);+ return snapshot(run);}async function abort(msg = {}) {await hydrate();const run = runs.get(msg.runId || msg.run_id);if (!run) throw new Error('Unknown cloud run.');- if (run.handoff?.interrupted) {+ if (run.handoff?.interrupted && !activeExecutions.has(run.runId)) {+ await persist({ clearHandoffRunId: run.runId });run.status = 'aborted';run.handoff = null;pushUpdate(run, 'handoff', { state: null });@@ -1774,19 +1899,20 @@ export function createCloudRunController({runAbortControllers.get(run.runId)?.abort();agent.abort(run.tabId);await persist();- }- return cloudSnapshot(run);+ } else if (run.status === 'aborted') await persist();+ return snapshot(run);}async function pause(msg = {}) {await hydrate();+ await persistQueue;const run = runs.get(msg.runId || msg.run_id);if (!run) throw cloudRunError('Unknown cloud run.', 404);if (run.workflowId) throw cloudRunError('Saved workflow replay does not support browser handoff.', 409);if (run.handoff) {// A duplicate pause must not expose a checkpoint still being written.await persistQueue;- return cloudSnapshot(run);+ return snapshot(run);}if (!['running', 'needs_user_input'].includes(run.status)) throw cloudRunError('Only a running browser task can be paused.', 409);if (pendingStarts || [...runs.values()].some(other => other !== run && !TERMINAL_STATUSES.has(other.status))@@ -1811,21 +1937,22 @@ export function createCloudRunController({}await gate.acknowledge();}- return cloudSnapshot(run);+ return snapshot(run);}async function resume(msg = {}) {await hydrate();+ await persistQueue;const run = runs.get(msg.runId || msg.run_id);if (!run) throw cloudRunError('Unknown cloud run.', 404);- if (!run.handoff?.resumable || run.handoff.interrupted) {+ if (run.status !== 'paused' || run.handoff?.state !== 'paused' || !run.handoff.resumable || run.handoff.interrupted) {throw cloudRunError('This handoff was interrupted. Inspect the browser and explicitly stop the interrupted run; it cannot safely resume.', 409);}if (typeof (msg.note ?? '') !== 'string' || (msg.note || '').length > 2000) throw cloudRunError('The handoff note must be text of at most 2000 characters.', 400);const gate = handoffGates.get(run.runId);if (!gate) throw cloudRunError('The browser handoff is no longer resumable.', 409);await gate.resume((msg.note || '').trim());- return cloudSnapshot(run);+ return snapshot(run);}async function respond(msg = {}) {@@ -1851,7 +1978,7 @@ export function createCloudRunController({run.error = '';pushUpdate(run, 'clarify_response', { clarifyId, source: 'cloud_api' });await persist();- return cloudSnapshot(run);+ return snapshot(run);}// Persistent bridge identity (chrome.storage.local). The token is the Cloud@@ -1921,11 +2048,11 @@ export function createCloudRunController({const owner = activeHandoff();const settlingOwner = kind === 'cloud' && owner?.tabId === tabId&& owner.handoff?.state === 'pausing' && !owner.handoff.interrupted;- if (owner && !settlingOwner) {+ if ((durableHandoffGuards.size || owner) && !settlingOwner) {throw cloudRunError('The browser is reserved for manual control. Return control or reconcile the interrupted handoff before starting an agent.', 409);}},- isRunning: (tabId) => startingTabs.has(tabId),+ isRunning: (tabId) => startingTabs.has(tabId) || [...durableHandoffGuards.values()].some(row => row.tabId === tabId),startRun,startWorkflowRun,compileWorkflow,diff --git a/src/firefox/src/agent/cloud-handoff.js b/src/firefox/src/agent/cloud-handoff.jsindex 0442021db..89a777bb6 100644--- a/src/firefox/src/agent/cloud-handoff.js+++ b/src/firefox/src/agent/cloud-handoff.js@@ -19,10 +19,12 @@ export class CloudHandoffGate {async acknowledge() {if (this.closed || this.state !== 'pausing') return;- this.state = 'paused';// A durable acknowledgement is required before the viewer becomes writable.await this.onState('paused');- if (!this.closed) this.stopKeepAlive = this.keepAlive();+ if (!this.closed && this.state === 'pausing') {+ this.state = 'paused';+ this.stopKeepAlive = this.keepAlive();+ }}async boundary() {diff --git a/src/firefox/src/cloud-runs.js b/src/firefox/src/cloud-runs.jsindex c2716079d..b57873589 100644--- a/src/firefox/src/cloud-runs.js+++ b/src/firefox/src/cloud-runs.js@@ -12,6 +12,7 @@ const PRIVATE_RESULT_PLACEHOLDER = '[Private final answer encrypted for this worconst DEFAULT_CLOUD_BRIDGE_URL = 'ws://127.0.0.1:17374/extension';const CLOUD_RUN_STORAGE_KEY = 'webbrainCloudRunSnapshots';+const CLOUD_HANDOFF_GUARD_KEY = 'webbrainCloudHandoffGuards';const CLOUD_UPDATE_LIMIT = 200;const CLOUD_RUN_LIMIT = 50;const CLOUD_STRING_LIMIT = 16 * 1024;@@ -713,6 +714,21 @@ export function buildCloudPersistenceRows(runs) {return rows;}+// Session snapshots disappear on extension reload and browser restart. Keep+// only the identity needed to reserve manual ownership in durable storage.+function normalizeCloudHandoffGuard(row) {+ const timestamp = value => typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value)+ && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;+ // Cloud callers may supply correlation IDs containing punctuation or+ // Unicode. Match the existing start API rather than changing that contract.+ if (!row || typeof row.runId !== 'string' || !row.runId.trim() || row.runId.length > CLOUD_STRING_LIMIT+ || !Number.isSafeInteger(row.tabId) || row.tabId < 0 || row.tabId > 2147483647+ || !timestamp(row.createdAt) || !timestamp(row.updatedAt)+ || row.pausedAt != null && !timestamp(row.pausedAt)) throw new Error('Browser handoff guard could not be reconciled.');+ return { runId: row.runId, tabId: row.tabId, createdAt: row.createdAt,+ updatedAt: row.updatedAt, pausedAt: row.pausedAt || null };+}+function cloudSnapshot(run, { includeUpdates = true } = {}) {if (!run) return null;return {@@ -772,6 +788,7 @@ export function createCloudRunController({const startingRunIds = new Set();let pendingStarts = 0;const handoffGates = new Map();+ const activeExecutions = new Set();const startingConversations = new Set();const runAbortControllers = new Map();// Private envelopes live only for the active handle, outside snapshots and@@ -780,9 +797,24 @@ export function createCloudRunController({let hydratePromise = null;let persistQueue = Promise.resolve();let persistTimer = null;+ const durableHandoffGuards = new Map();+ let storedHandoffGuard = false;const isoNow = () => now().toISOString();+ function snapshot(run, options) {+ const result = cloudSnapshot(run, options);+ // Handler errors and cancellation can assign a terminal status before+ // asynchronous cleanup finishes. A retained guard remains authoritative+ // for pollers and streamers until confirmed removal releases ownership.+ if (result && durableHandoffGuards.has(run.runId) && TERMINAL_STATUSES.has(result.status)) {+ result.status = run.handoff ? 'paused' : 'aborting';+ result.handoff = run.handoff ? { ...run.handoff, state: 'paused', resumable: false, interrupted: true } : null;+ result.completedAt = null;+ }+ return result;+ }+// Firefox uses a persistent background page, but the same ping is harmless// and keeps the Chrome MV3 service worker alive during resume waits. A bare// setTimeout does not reset the MV3 idle timer.@@ -805,12 +837,39 @@ export function createCloudRunController({}}- async function persist() {- if (!api.storage?.session?.set) return;- const rows = buildCloudPersistenceRows(runs);+ async function persist({ clearHandoffRunId = null } = {}) {persistQueue = persistQueue.catch(() => {})- .then(() => api.storage.session.set({ [CLOUD_RUN_STORAGE_KEY]: rows }));+ .then(async () => {+ // Build inside the queue so an older ordinary checkpoint cannot put+ // back a reservation already cleared by confirmed reconciliation.+ const cancellationPending = id => activeExecutions.has(id) && runAbortControllers.get(id)?.signal.aborted;+ const clearing = [...durableHandoffGuards.entries()].filter(([id]) => {+ const run = runs.get(id);+ return !cancellationPending(id) && (id === clearHandoffRunId+ || (run && TERMINAL_STATUSES.has(run.status) && !activeExecutions.has(id)));+ });+ const clearedIds = new Set(clearing.map(([id]) => id));+ const guards = [...durableHandoffGuards.values()].filter(row => !clearedIds.has(row.runId));+ // A failed session write must not remove the durable reservation.+ await api.storage?.session?.set?.({ [CLOUD_RUN_STORAGE_KEY]: buildCloudPersistenceRows(runs) });+ if (guards.length || storedHandoffGuard || clearing.length) {+ if (!api.storage?.local?.set) throw new Error('Durable browser handoff storage is unavailable.');+ await api.storage.local.set({ [CLOUD_HANDOFF_GUARD_KEY]: guards });+ // Cancellation can arrive during an awaited handback clear. Keep+ // the in-memory reservation and restore its durable row before this+ // checkpoint can acknowledge anything or allow another actor in.+ const retained = clearing.filter(([id]) => cancellationPending(id));+ if (retained.length) {+ await api.storage.local.set({ [CLOUD_HANDOFF_GUARD_KEY]: [+ ...guards, ...retained.map(([id, row]) => durableHandoffGuards.get(id) || row),+ ] });+ }+ storedHandoffGuard = guards.length > 0 || retained.length > 0;+ const retainedIds = new Set(retained.map(([id]) => id));+ for (const [id, row] of clearing) if (!retainedIds.has(id) && durableHandoffGuards.get(id) === row) durableHandoffGuards.delete(id);+ }+ });await persistQueue;}@@ -825,9 +884,26 @@ export function createCloudRunController({async function hydrate() {if (hydratePromise) return hydratePromise;hydratePromise = (async () => {- if (!api.storage?.session?.get) return;- const stored = await api.storage.session.get(CLOUD_RUN_STORAGE_KEY);+ const local = await api.storage?.local?.get?.(CLOUD_HANDOFF_GUARD_KEY) || {};+ const guardRows = local[CLOUD_HANDOFF_GUARD_KEY] === undefined ? [] : local[CLOUD_HANDOFF_GUARD_KEY];+ if (!Array.isArray(guardRows) || guardRows.length > CLOUD_RUN_LIMIT) throw new Error('Browser handoff guard could not be reconciled.');+ for (const row of guardRows) {+ const guard = normalizeCloudHandoffGuard(row);+ if (durableHandoffGuards.has(guard.runId)) throw new Error('Browser handoff guard could not be reconciled.');+ durableHandoffGuards.set(guard.runId, guard);+ }+ storedHandoffGuard = durableHandoffGuards.size > 0;+ // Preserve main's fail-closed session read. Read failures are not proof+ // that no run owns this profile.+ const stored = await api.storage?.session?.get?.(CLOUD_RUN_STORAGE_KEY) || {};const rows = Array.isArray(stored?.[CLOUD_RUN_STORAGE_KEY]) ? stored[CLOUD_RUN_STORAGE_KEY] : [];+ for (const guard of durableHandoffGuards.values()) {+ const old = rows.findIndex(row => row?.runId === guard.runId);+ const restored = { ...(old < 0 ? { updates: [] } : rows[old]), ...guard, status: 'paused',+ handoff: { state: 'paused', resumable: false, interrupted: true,+ ...(guard.pausedAt ? { pausedAt: guard.pausedAt } : {}) }, completedAt: null };+ if (old < 0) rows.push(restored); else rows[old] = restored;+ }let changed = false;for (const row of rows) {if (!row?.runId) continue;@@ -848,6 +924,11 @@ export function createCloudRunController({// Keep the browser reserved for its owner; never replay this run.restored.status = 'paused';restored.handoff = { ...restored.handoff, state: 'paused', resumable: false, interrupted: true };+ durableHandoffGuards.set(restored.runId, normalizeCloudHandoffGuard({+ runId: restored.runId, tabId: restored.tabId,+ createdAt: durableHandoffGuards.get(restored.runId)?.createdAt || isoNow(),+ updatedAt: isoNow(), pausedAt: restored.handoff.pausedAt || null,+ }));restored.error = 'WebBrain restarted during browser handoff. Inspect the page and explicitly stop this interrupted run before starting further work.';startingTabs.add(restored.tabId);pushUpdate(restored, 'handoff', restored.handoff);@@ -1143,7 +1224,7 @@ export function createCloudRunController({}function assertNoHandoff() {- if (activeHandoff()) {+ if (durableHandoffGuards.size || activeHandoff()) {throw cloudRunError('Browser control belongs to an active handoff. Return control or explicitly reconcile the interrupted run before starting another task.', 409);}}@@ -1193,6 +1274,7 @@ export function createCloudRunController({? null : await importPrivateResultRecipient(msg.private_result_public_key);const suppliedRunId = msg.runId ?? msg.run_id;const requestedRunId = suppliedRunId == null ? '' : String(suppliedRunId).trim();+ if (requestedRunId.length > CLOUD_STRING_LIMIT) throw cloudRunError('Cloud run ID exceeds the supported length.', 400);const parentRunId = String(msg.parentRunId || msg.parent_run_id || '').trim() || null;const savedParent = parentRunId ? runs.get(parentRunId) : null;if (parentRunId) assertMemoryContinuation(savedParent, memoryOwner);@@ -1331,17 +1413,41 @@ export function createCloudRunController({};const handoffGate = new CloudHandoffGate({async onState(state) {+ const checkpoint = async options => {+ try { await persist(options); } catch (error) {+ // An abort may close the gate while this write is pending. Keep+ // cancellation pending until cleanup; never resurrect its pause.+ if (!handoffGate.closed && !cancelled()) {+ run.status = 'paused';+ run.handoff = { state: 'paused', resumable: false, interrupted: true };+ run.error = 'Browser handoff could not be saved safely. Keep the browser read-only and explicitly stop this run.';+ pushUpdate(run, 'handoff', run.handoff);+ }+ throw error;+ }+ };if (state === 'running') {+ await checkpoint({ clearHandoffRunId: run.runId });+ if (handoffGate.closed || cancelled()) return;run.handoff = null;run.status = run.pendingInput ? 'needs_user_input' : 'running';} else {+ if (handoffGate.closed || cancelled()) return;+ // Guard ownership from the pause request onwards. Neither polling+ // nor streaming may see writable paused state before this write.+ durableHandoffGuards.set(run.runId, normalizeCloudHandoffGuard({+ runId: run.runId, tabId: run.tabId, createdAt: run.createdAt, updatedAt: isoNow(),+ pausedAt: state === 'paused' ? isoNow() : run.handoff?.pausedAt || null,+ }));+ await checkpoint();+ if (handoffGate.closed || cancelled()) return;run.status = state;run.handoff = { state, resumable: true, interrupted: false,...(state === 'paused' ? { pausedAt: isoNow() } : run.handoff?.pausedAt ? { pausedAt: run.handoff.pausedAt } : {}) };}run.updatedAt = isoNow();pushUpdate(run, 'handoff', run.handoff || { state: null });- await persist();+ await checkpoint();},keepAlive() {const ping = () => { try { const p = api.runtime?.getPlatformInfo?.(() => { void api.runtime.lastError; }); p?.catch?.(() => {}); } catch {} };@@ -1379,6 +1485,7 @@ export function createCloudRunController({throw error;}+ activeExecutions.add(run.runId);(async () => {let recordingId = null;const strictSecretMode = !!recipient || agent.strictSecretMode === true;@@ -1659,6 +1766,23 @@ export function createCloudRunController({strictSecretOverflowRuns.delete(run.runId);strictTraceOverflowRuns.delete(run.runId);memoryConfigurations.delete(run.runId);+ activeExecutions.delete(run.runId);+ if (run.status === 'aborted' && durableHandoffGuards.has(run.runId)) {+ // The handler and recording cleanup have settled. Clear the durable+ // reservation before publicly acknowledging terminal cancellation.+ run.status = 'aborting';+ run.completedAt = null;+ try {+ await persist({ clearHandoffRunId: run.runId });+ run.status = 'aborted';+ run.completedAt = isoNow();+ } catch {+ run.status = 'paused';+ run.handoff = { state: 'paused', resumable: false, interrupted: true };+ run.error = 'Browser handoff cancellation could not be saved. Keep the browser read-only and explicitly stop this run again.';+ pushUpdate(run, 'handoff', run.handoff);+ }+ }sendIndicator(tabId, 'WB_HIDE_AGENT_INDICATORS');// Recording flush is still owned by this run. Keep the tab reserved// through all cleanup so aborting a nonterminal capture cannot cancel@@ -1668,7 +1792,7 @@ export function createCloudRunController({}})();- return cloudSnapshot(run, { includeUpdates: false });+ return snapshot(run, { includeUpdates: false });}async function startWorkflowRun(msg = {}) {@@ -1745,17 +1869,18 @@ export function createCloudRunController({// has finished writing; a poll cannot race a pending storage write.await persistQueue;const runId = msg.runId || msg.run_id;- if (!runId) return { runs: [...runs.values()].map(run => cloudSnapshot(run, { includeUpdates: false })) };+ if (!runId) return { runs: [...runs.values()].map(run => snapshot(run, { includeUpdates: false })) };const run = runs.get(runId);if (!run) throw new Error('Unknown cloud run.');- return cloudSnapshot(run);+ return snapshot(run);}async function abort(msg = {}) {await hydrate();const run = runs.get(msg.runId || msg.run_id);if (!run) throw new Error('Unknown cloud run.');- if (run.handoff?.interrupted) {+ if (run.handoff?.interrupted && !activeExecutions.has(run.runId)) {+ await persist({ clearHandoffRunId: run.runId });run.status = 'aborted';run.handoff = null;pushUpdate(run, 'handoff', { state: null });@@ -1775,19 +1900,20 @@ export function createCloudRunController({runAbortControllers.get(run.runId)?.abort();agent.abort(run.tabId);await persist();- }- return cloudSnapshot(run);+ } else if (run.status === 'aborted') await persist();+ return snapshot(run);}async function pause(msg = {}) {await hydrate();+ await persistQueue;const run = runs.get(msg.runId || msg.run_id);if (!run) throw cloudRunError('Unknown cloud run.', 404);if (run.workflowId) throw cloudRunError('Saved workflow replay does not support browser handoff.', 409);if (run.handoff) {// A duplicate pause must not expose a checkpoint still being written.await persistQueue;- return cloudSnapshot(run);+ return snapshot(run);}if (!['running', 'needs_user_input'].includes(run.status)) throw cloudRunError('Only a running browser task can be paused.', 409);if (pendingStarts || [...runs.values()].some(other => other !== run && !TERMINAL_STATUSES.has(other.status))@@ -1812,21 +1938,22 @@ export function createCloudRunController({}await gate.acknowledge();}- return cloudSnapshot(run);+ return snapshot(run);}async function resume(msg = {}) {await hydrate();+ await persistQueue;const run = runs.get(msg.runId || msg.run_id);if (!run) throw cloudRunError('Unknown cloud run.', 404);- if (!run.handoff?.resumable || run.handoff.interrupted) {+ if (run.status !== 'paused' || run.handoff?.state !== 'paused' || !run.handoff.resumable || run.handoff.interrupted) {throw cloudRunError('This handoff was interrupted. Inspect the browser and explicitly stop the interrupted run; it cannot safely resume.', 409);}if (typeof (msg.note ?? '') !== 'string' || (msg.note || '').length > 2000) throw cloudRunError('The handoff note must be text of at most 2000 characters.', 400);const gate = handoffGates.get(run.runId);if (!gate) throw cloudRunError('The browser handoff is no longer resumable.', 409);await gate.resume((msg.note || '').trim());- return cloudSnapshot(run);+ return snapshot(run);}async function respond(msg = {}) {@@ -1852,7 +1979,7 @@ export function createCloudRunController({run.error = '';pushUpdate(run, 'clarify_response', { clarifyId, source: 'cloud_api' });await persist();- return cloudSnapshot(run);+ return snapshot(run);}// Persistent bridge identity (chrome.storage.local). The token is the Cloud@@ -1919,11 +2046,11 @@ export function createCloudRunController({const owner = activeHandoff();const settlingOwner = kind === 'cloud' && owner?.tabId === tabId&& owner.handoff?.state === 'pausing' && !owner.handoff.interrupted;- if (owner && !settlingOwner) {+ if ((durableHandoffGuards.size || owner) && !settlingOwner) {throw cloudRunError('The browser is reserved for manual control. Return control or reconcile the interrupted handoff before starting an agent.', 409);}},- isRunning: (tabId) => startingTabs.has(tabId),+ isRunning: (tabId) => startingTabs.has(tabId) || [...durableHandoffGuards.values()].some(row => row.tabId === tabId),startRun,startWorkflowRun,compileWorkflow,diff --git a/test/cloud-handoff.mjs b/test/cloud-handoff.mjsindex a68c49fe2..c6eaf0bf0 100644--- a/test/cloud-handoff.mjs+++ b/test/cloud-handoff.mjs@@ -19,17 +19,18 @@ for (const browser of ['chrome', 'firefox']) {const { createCloudRunController, buildCloudPersistenceRows } = await import(`../src/${browser}/src/cloud-runs.js`);const { Agent } = await import(`../src/${browser}/src/agent/agent.js`);- function harness(processMessage) {+ function harness(processMessage, options = {}) {const stored = {};- const api = { storage: { session: { get: async key => ({ [key]: structuredClone(stored[key]) }), set: async data => Object.assign(stored, structuredClone(data)) } },+ const local = {};+ const api = { storage: { local: { get: async key => ({ [key]: structuredClone(local[key]) }), set: async data => Object.assign(local, structuredClone(data)) }, session: { get: async key => ({ [key]: structuredClone(stored[key]) }), set: async data => Object.assign(stored, structuredClone(data)) } },tabs: { get: async id => ({ id, url: 'https://example.com/' }), query: async () => [{ id: 7, url: 'https://example.com/' }], update: async () => {} } };let clarificationResolve;const agent = { isRunning: () => false, hasOtherRunningTabs: () => false, canPauseAtClarification: () => true,strictSecretMode: true, processMessage, abort() {}, _persistNow: async () => ({ ok: true }),submitClarifyResponse(_tab, _id, answer) { clarificationResolve?.(answer); return true; } };let seq = 0;- const controller = createCloudRunController({ chromeApi: api, agent, makeRunId: () => `run_handoff_${++seq}`, ensureOffscreen: async () => {} });- return { controller, stored, agent, api, setClarificationResolver(value) { clarificationResolve = value; } };+ const controller = createCloudRunController({ chromeApi: api, agent, makeRunId: () => `run_handoff_${++seq}`, ensureOffscreen: async () => {}, ...options });+ return { controller, stored, local, agent, api, setClarificationResolver(value) { clarificationResolve = value; } };}test(`${browser}: pausing acknowledges only a settled boundary and keeps its tab reservation`, async () => {@@ -313,4 +314,305 @@ for (const browser of ['chrome', 'firefox']) {assert.equal(agent.hasOtherRunningTabs(7), true);assert.equal(agent.hasOtherRunningTabs(8), false);});+ for (const restart of ['extension reload', 'browser startup without session storage']) {+ test(`${browser}: ${restart} restores only a durable manual guard and never replays`, async () => {+ const ready = deferred(); let calls = 0;+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { calls++; await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });+ const run = await h.controller.startRun({ task: 'Private task with secret-provider-token' });+ await h.controller.pause({ runId: run.runId }); ready.resolve();+ await until(() => h.controller.runs.get(run.runId).status === 'paused');+ await h.controller.status({ runId: run.runId });+ const guard = h.local.webbrainCloudHandoffGuards[0];+ assert.deepEqual(Object.keys(guard).sort(), ['createdAt', 'pausedAt', 'runId', 'tabId', 'updatedAt']);+ assert.equal(JSON.stringify(h.local).includes('secret-provider-token'), false);+ delete h.stored.webbrainCloudRunSnapshots;+ if (restart.includes('without')) delete h.api.storage.session;+ const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent, ensureOffscreen: async () => {} });+ const restored = await restarted.status({ runId: run.runId });+ assert.equal(restored.status, 'paused'); assert.equal(restored.handoff.interrupted, true); assert.equal(restored.handoff.resumable, false);+ assert.equal(restored.task, undefined); assert.equal(restored.result, undefined); assert.equal(calls, 1);+ await assert.rejects(restarted.resume({ runId: run.runId }), error => error.status === 409);+ await assert.rejects(restarted.startRun({ task: 'Other bot', tabId: 8 }), error => error.status === 409);+ await assert.rejects(restarted.guardRunStart(8, { kind: 'scheduled' }), error => error.status === 409);+ assert.equal((await restarted.abort({ runId: run.runId })).status, 'aborted');+ assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);+ await restarted.guardRunStart(8, { kind: 'interactive' });+ await h.controller.abort({ runId: run.runId });+ });+ }++ test(`${browser}: a durable guard overrides a matching stale terminal snapshot`, async () => {+ const ready = deferred();+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });+ const run = await h.controller.startRun({ task: 'Read' });+ await h.controller.pause({ runId: run.runId }); ready.resolve();+ await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });+ h.stored.webbrainCloudRunSnapshots[0].status = 'aborted'; h.stored.webbrainCloudRunSnapshots[0].handoff = null;+ const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent, ensureOffscreen: async () => {} });+ const restored = await restarted.status({ runId: run.runId });+ assert.equal(restored.status, 'paused'); assert.equal(restored.handoff.interrupted, true);+ await restarted.abort({ runId: run.runId }); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);+ await h.controller.abort({ runId: run.runId });+ });++ test(`${browser}: durable local acknowledgement blocks publication and direct resume while writing`, async () => {+ const ready = deferred(), writing = deferred(), written = deferred();+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });+ const write = h.api.storage.local.set;+ h.api.storage.local.set = async data => { if (data.webbrainCloudHandoffGuards?.[0]?.pausedAt) { writing.resolve(); await written.promise; } return write(data); };+ const run = await h.controller.startRun({ task: 'Read' });+ await h.controller.pause({ runId: run.runId }); ready.resolve(); await writing.promise;+ assert.equal(h.controller.runs.get(run.runId).status, 'pausing');+ let exposed = false, resumed = false;+ const status = h.controller.status({ runId: run.runId }).then(value => { exposed = true; return value; });+ const returning = h.controller.resume({ runId: run.runId }).then(() => { resumed = true; }, error => { assert.equal(error.status, 409); });+ await tick(); assert.equal(exposed, false); assert.equal(resumed, false);+ written.resolve(); await status; await returning;+ await h.controller.abort({ runId: run.runId });+ });++ test(`${browser}: failed guard writes retain read-only ownership and abort waits for native quiescence`, async () => {+ const ready = deferred(), finished = deferred();+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); await finished.promise; options.onRunFinished('done'); return 'Read'; });+ const run = await h.controller.startRun({ task: 'Read' });+ const write = h.api.storage.local.set;+ h.api.storage.local.set = async () => { throw Error('Fixture guard write failure'); };+ await assert.rejects(h.controller.pause({ runId: run.runId }), /guard write failure/);+ assert.equal(h.controller.runs.get(run.runId).handoff.resumable, false);+ await assert.rejects(h.controller.guardRunStart(8, { kind: 'scheduled' }), error => error.status === 409);+ h.api.storage.local.set = write;+ const aborting = await h.controller.abort({ runId: run.runId }); assert.equal(aborting.status, 'aborting');+ assert.equal(h.local.webbrainCloudHandoffGuards.length, 1, 'a cancellation request must retain the durable guard');+ ready.resolve(); await tick(); assert.equal(h.local.webbrainCloudHandoffGuards.length, 1);+ finished.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'aborted');+ await h.controller.status({ runId: run.runId }); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);+ });++ test(`${browser}: guard removal failures preserve the lock until explicit cancellation retries`, async () => {+ const ready = deferred();+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });+ const run = await h.controller.startRun({ task: 'Read' });+ await h.controller.pause({ runId: run.runId }); ready.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });+ const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent, ensureOffscreen: async () => {} });+ await restarted.status({ runId: run.runId });+ const write = h.api.storage.local.set;+ h.api.storage.local.set = async data => { if (!data.webbrainCloudHandoffGuards.length) throw Error('Fixture clear failure'); return write(data); };+ await assert.rejects(restarted.abort({ runId: run.runId }), /clear failure/);+ assert.equal(restarted.runs.get(run.runId).status, 'paused');+ assert.equal(restarted.runs.get(run.runId).handoff.interrupted, true);+ assert.equal(restarted.runs.get(run.runId).updates.at(-1).data.state, 'paused', 'failed cancellation cannot publish a null handoff');+ assert.equal(restarted.isRunning(7), true);+ await assert.rejects(restarted.guardRunStart(8, { kind: 'interactive' }), error => error.status === 409);+ h.api.storage.local.set = write;+ assert.equal((await restarted.abort({ runId: run.runId })).status, 'aborted'); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);+ await h.controller.abort({ runId: run.runId });+ });++ test(`${browser}: handback guard-clear failure stops before any further action`, async () => {+ const ready = deferred(); let observations = 0, actions = 0;+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {+ await ready.promise; await options.handoffBoundary(); observations++;+ await options.handoffObserved(); actions++; options.onRunFinished('done'); return 'Read';+ });+ const run = await h.controller.startRun({ task: 'Read only' });+ await h.controller.pause({ runId: run.runId }); ready.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });+ const write = h.api.storage.local.set;+ h.api.storage.local.set = async data => { if (!data.webbrainCloudHandoffGuards.length) throw Error('Fixture observed-clear failure'); return write(data); };+ await h.controller.resume({ runId: run.runId }); await until(() => h.controller.runs.get(run.runId).handoff?.interrupted);+ const stopped = await h.controller.status({ runId: run.runId });+ assert.equal(stopped.status, 'paused'); assert.equal(stopped.handoff.resumable, false); assert.equal(observations, 1); assert.equal(actions, 0);+ assert.equal(h.local.webbrainCloudHandoffGuards.length, 1);+ await assert.rejects(h.controller.startRun({ task: 'Another bot', tabId: 8 }), error => error.status === 409);+ h.api.storage.local.set = write; await h.controller.abort({ runId: run.runId }); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);+ });++ test(`${browser}: queued persistence cannot resurrect a confirmed cleared guard`, async () => {+ const ready = deferred(), clearing = deferred(), cleared = deferred();+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read'; });+ const run = await h.controller.startRun({ task: 'Read' });+ await h.controller.pause({ runId: run.runId }); ready.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });+ const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent, ensureOffscreen: async () => {} }); await restarted.status({ runId: run.runId });+ const write = h.api.storage.local.set;+ h.api.storage.local.set = async data => { if (!data.webbrainCloudHandoffGuards.length) { clearing.resolve(); await cleared.promise; } return write(data); };+ const first = restarted.abort({ runId: run.runId }); await clearing.promise;+ const queued = restarted.abort({ runId: run.runId }); await tick(); cleared.resolve();+ await first; await queued; await restarted.status({ runId: run.runId }); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);+ await h.controller.abort({ runId: run.runId });+ });++ test(`${browser}: failed or malformed durable guard reads prevent run startup`, async () => {+ const valid = { runId: 'owned_1', tabId: 7, createdAt: '2026-10-12T23:00:00.000Z', updatedAt: '2026-10-12T23:00:00.000Z', pausedAt: null };+ const readFailure = Symbol('read failure');+ for (const value of [readFailure, null, false, 0, '', [{ runId: '', tabId: 7 }], [{ ...valid, runId: 123 }], [{ ...valid, runId: ' ' }],+ [valid, valid], [{ ...valid, tabId: '7' }], [{ ...valid, createdAt: 'yesterday' }]]) {+ let calls = 0;+ const h = harness(async () => { calls++; });+ h.api.storage.local.get = async () => { if (value === readFailure) throw Error('Fixture read failure'); return { webbrainCloudHandoffGuards: value }; };+ await assert.rejects(h.controller.startRun({ task: 'Read' })); assert.equal(calls, 0);+ }+ });++ test(`${browser}: failed live cancellation clear stays interrupted until owner retries`, async () => {+ const ready = deferred();+ const h = harness(async (_tab, _task, update, _mode, _attachments, options) => { await ready.promise; await options.handoffBoundary(); update('clarify', { clarifyId: 'late', question: 'Late question' }); options.onRunFinished('done'); return 'Read'; });+ const run = await h.controller.startRun({ task: 'Read' });+ await h.controller.pause({ runId: run.runId }); ready.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });+ const write = h.api.storage.local.set;+ h.api.storage.local.set = async data => { if (!data.webbrainCloudHandoffGuards.length) throw Error('Fixture live clear failure'); return write(data); };+ assert.equal((await h.controller.abort({ runId: run.runId })).status, 'aborting');+ await until(() => h.controller.runs.get(run.runId).handoff?.interrupted);+ const stopped = await h.controller.status({ runId: run.runId });+ assert.equal(stopped.status, 'paused'); assert.equal(stopped.handoff.resumable, false); assert.equal(stopped.pendingInput, null); assert.equal(stopped.completedAt, null);+ assert.equal(h.local.webbrainCloudHandoffGuards.length, 1);+ await assert.rejects(h.controller.guardRunStart(8, { kind: 'scheduled' }), error => error.status === 409);+ h.api.storage.local.set = write; assert.equal((await h.controller.abort({ runId: run.runId })).status, 'aborted'); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);+ });++ test(`${browser}: valid caller correlation IDs remain usable for handoff and reload`, async () => {+ for (const runId of ['request:17', 'tenant/run/1', 'browser-ü-任务']) {+ const ready = deferred();+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {+ await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read';+ });+ await h.controller.startRun({ task: 'Read only', runId });+ await h.controller.pause({ runId }); ready.resolve();+ await until(() => h.controller.runs.get(runId).status === 'paused'); await h.controller.status({ runId });+ delete h.stored.webbrainCloudRunSnapshots;+ const restarted = createCloudRunController({ chromeApi: h.api, agent: h.agent });+ assert.equal((await restarted.status({ runId })).handoff.interrupted, true);+ await restarted.abort({ runId }); await h.controller.abort({ runId });+ }+ const h = harness(async () => assert.fail('Oversized ID must not dispatch'));+ await assert.rejects(h.controller.startRun({ task: 'Read', runId: 'x'.repeat(16 * 1024 + 1) }), error => error.status === 400);+ assert.equal(h.controller.runs.size, 0);+ });++ test(`${browser}: cancellation during a pending pause guard write cannot resurrect manual control`, async () => {+ for (const fail of [false, true]) {+ const ready = deferred(), writing = deferred(), written = deferred(), finished = deferred();+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {+ await ready.promise; await options.handoffBoundary(); await finished.promise; options.onRunFinished('done'); return 'Read';+ });+ const run = await h.controller.startRun({ task: 'Read' });+ await h.controller.pause({ runId: run.runId });+ const set = h.api.storage.local.set;+ let failed = false;+ h.api.storage.local.set = async data => {+ if (data.webbrainCloudHandoffGuards?.[0]?.pausedAt) {+ writing.resolve(); await written.promise;+ if (fail && !failed) { failed = true; throw Error('Fixture pending pause write failure'); }+ }+ return set(data);+ };+ ready.resolve(); await writing.promise;+ const aborting = h.controller.abort({ runId: run.runId });+ await tick(); assert.equal(h.controller.runs.get(run.runId).status, 'aborting');+ await assert.rejects(h.controller.guardRunStart(8, { kind: 'scheduled' }), error => error.status === 409);+ written.resolve(); await aborting;+ assert.equal(h.controller.runs.get(run.runId).handoff, null, 'a delayed pause callback cannot restore writable state');+ finished.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'aborted');+ assert.equal((await h.controller.status({ runId: run.runId })).status, 'aborted');+ assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);+ }+ });++ test(`${browser}: cancellation stays nonterminal through native and recording cleanup`, async () => {+ const ready = deferred(), settled = deferred(), flushing = deferred(), flushed = deferred();+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {+ await ready.promise; await options.handoffBoundary(); await settled.promise; options.onRunFinished('done'); return 'Read';+ }, {+ startRecording: async () => ({ ok: true, state: { recordingId: 'capture-1' } }),+ stopRecording: async () => { flushing.resolve(); await flushed.promise; return { ok: true }; },+ });+ const run = await h.controller.startRun({ task: 'Read', capture: 'video' });+ await h.controller.pause({ runId: run.runId }); ready.resolve();+ await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });+ assert.equal((await h.controller.abort({ runId: run.runId })).status, 'aborting');+ for (const kind of ['cloud', 'scheduled', 'interactive']) await assert.rejects(h.controller.guardRunStart(8, { kind }), error => error.status === 409);+ await assert.rejects(h.controller.startRun({ task: 'Another bot', tabId: 8 }), error => error.status === 409);+ settled.resolve(); await flushing.promise;+ const pending = await h.controller.status({ runId: run.runId });+ assert.equal(pending.completedAt, null); assert.notEqual(pending.status, 'aborted');+ assert.equal(h.local.webbrainCloudHandoffGuards.length, 1, 'recording still owns the profile');+ flushed.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'aborted');+ await h.controller.status({ runId: run.runId }); assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);+ await h.controller.guardRunStart(8, { kind: 'interactive' });+ });++ test(`${browser}: a failed public paused checkpoint becomes nonresumable`, async () => {+ const ready = deferred();+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {+ await ready.promise; await options.handoffBoundary(); options.onRunFinished('done'); return 'Read';+ });+ const run = await h.controller.startRun({ task: 'Read' });+ await h.controller.pause({ runId: run.runId });+ const set = h.api.storage.session.set;+ h.api.storage.session.set = async data => {+ if (data.webbrainCloudRunSnapshots?.[0]?.handoff?.resumable && data.webbrainCloudRunSnapshots[0].status === 'paused') throw Error('Fixture public checkpoint failure');+ return set(data);+ };+ ready.resolve(); await until(() => h.controller.runs.get(run.runId).handoff?.interrupted);+ assert.equal(h.controller.runs.get(run.runId).handoff.resumable, false);+ assert.equal(h.local.webbrainCloudHandoffGuards.length, 1);+ await assert.rejects(h.controller.resume({ runId: run.runId }));+ h.api.storage.session.set = set;+ await until(() => !h.controller.runs.get(run.runId).pendingInput);+ await h.controller.abort({ runId: run.runId }); await until(() => h.controller.runs.get(run.runId).status === 'aborted');+ });++ test(`${browser}: abort racing a fresh-observation guard clear retains ownership through recording cleanup`, async () => {+ const ready = deferred(), clearing = deferred(), cleared = deferred(), continued = deferred(), flushing = deferred(), flushed = deferred();+ const h = harness(async (_tab, _task, _update, _mode, _attachments, options) => {+ await ready.promise; await options.handoffBoundary(); await options.handoffObserved();+ await continued.promise; options.onRunFinished('done'); return 'Read';+ }, {+ startRecording: async () => ({ ok: true, state: { recordingId: 'capture-2' } }),+ stopRecording: async () => { flushing.resolve(); await flushed.promise; return { ok: true }; },+ });+ const run = await h.controller.startRun({ task: 'Read', capture: 'video' });+ await h.controller.pause({ runId: run.runId }); ready.resolve();+ await until(() => h.controller.runs.get(run.runId).status === 'paused'); await h.controller.status({ runId: run.runId });+ const set = h.api.storage.local.set;+ let held = false;+ h.api.storage.local.set = async data => {+ if (!held && !data.webbrainCloudHandoffGuards.length) {+ held = true; clearing.resolve(); await cleared.promise;+ }+ return set(data);+ };+ await h.controller.resume({ runId: run.runId }); await clearing.promise;+ const aborting = h.controller.abort({ runId: run.runId });+ await tick();+ await assert.rejects(h.controller.guardRunStart(8, { kind: 'scheduled' }), error => error.status === 409);+ cleared.resolve();+ assert.equal((await aborting).status, 'aborting');+ assert.equal(h.local.webbrainCloudHandoffGuards.length, 1, 'cancellation during clear restores the durable reservation');+ continued.resolve(); await flushing.promise;+ for (const kind of ['cloud', 'scheduled', 'interactive']) await assert.rejects(h.controller.guardRunStart(8, { kind }), error => error.status === 409);+ await assert.rejects(h.controller.startRun({ task: 'Another bot', tabId: 8 }), error => error.status === 409);+ const pending = await h.controller.status({ runId: run.runId });+ assert.equal(pending.completedAt, null); assert.notEqual(pending.status, 'aborted');+ assert.equal(h.local.webbrainCloudHandoffGuards.length, 1);+ flushed.resolve(); await until(() => h.controller.runs.get(run.runId).status === 'aborted');+ assert.equal((await h.controller.status({ runId: run.runId })).status, 'aborted');+ assert.deepEqual(h.local.webbrainCloudHandoffGuards, []);+ await h.controller.guardRunStart(8, { kind: 'interactive' });+ });++ if (browser === 'firefox') test('Firefox keeps its in-process Cloud bridge transport', async () => {+ const calls = [];+ const h = harness(async () => assert.fail('Bridge controls must not start browser work'), {+ bridge: {+ start: async options => { calls.push(['start', options.url]); return { connected: true }; },+ stop: async () => { calls.push(['stop']); return { connected: false }; },+ status: async () => { calls.push(['status']); return { connected: true }; },+ },+ ensureOffscreen: () => assert.fail('Firefox has no offscreen document'),+ });+ h.api.runtime = { sendMessage: () => assert.fail('Firefox uses its injected background bridge') };+ assert.equal((await h.controller.startBridge('ws://127.0.0.1:17374/extension')).connected, true);+ assert.equal((await h.controller.bridgeStatus()).connected, true);+ assert.equal((await h.controller.stopBridge()).connected, false);+ assert.deepEqual(calls, [['start', 'ws://127.0.0.1:17374/extension'], ['status'], ['stop']]);+ });}