Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

Fix workflow recovery receipts and actor evidence ownership

Codex release-state test9750b3450c07
diff --git a/website-tests/README.md b/website-tests/README.md
index b568bfd4b..e985968bb 100644
--- a/website-tests/README.md
+++ b/website-tests/README.md
@@ -181,16 +181,16 @@ build. Configure `manualActorIdentityVerified:true` only after checking A's
actual login in the chosen browser; the string `"false"` is not confirmation.
Cloud REST has no documented DOM/control endpoint. A separate logged-in local
-B can independently prove public posts, incoming mail/messages and shared access,
-but cannot observe A's private unsent draft or pre-share folder. Full workflows
-therefore require explicit actor-tab manual evidence for those phases. Without
-it, preflight reports unsupported before dispatching a private-phase task.
+B can independently prove incoming mail/messages and shared access in the
+separate receiver stages. Every A stage requires explicit actor-tab manual
+evidence, including sends, replies and cleanup, so captured message/thread IDs
+belong to A's account. Without it, preflight reports unsupported before dispatch.
Automated active steering/checkpoints are also unsupported on REST alone.
Finished-run `/messages` continuation is not active-run steering.
For manual verification set `manualEvidenceFile` to an ignored private JSON
file and run in an interactive terminal. A noninteractive CLI with no manual
-observer callback is blocked before any private-phase task. Each checkpoint writes a private
+observer callback is blocked before any actor task. Each checkpoint writes a private
requirement file with the exact run marker, stage, expected body/account/resource.
Observe the actual browser and append evidence to `{ "observations": [...] }`.
Rows use the same `webbrain-authenticated-evidence/1` schema as DOM observations,
@@ -290,6 +290,12 @@ select the matching dashboard run explicitly:
npm run reconcile -- --report RUN_DIRECTORY --request-id RECORDED_REQUEST_ID --run-id CONFIRMED_RUN_ID
```
+Local shutdown saves exact terminal extension receipts in the private ledger
+before closing actor tabs. Recovery can use those receipts after the live tab
+journal has been deleted, and still requires independent effect evidence. If a
+receipt cannot be saved or the run is still active, shutdown retains the browser
+and its tabs for reconciliation.
+
Reconciliation reads existing runs/effects and never resends. An ambiguous Cloud
upload can be reconciled by its recorded byte hash and exact server filename;
use `--remote-name CONFIRMED_SERVER_FILENAME` if its upload response was lost. Cleanup operates
diff --git a/website-tests/backends/local.mjs b/website-tests/backends/local.mjs
index fef3ae8e5..5698d6aba 100644
--- a/website-tests/backends/local.mjs
+++ b/website-tests/backends/local.mjs
@@ -630,9 +630,20 @@ export function createLocalBackend(role, options = {}) {
if (!mime) throw new Error('Only WebBrain-supported text, image and PDF chat attachments are accepted.');
return { name, kind: extension === '.pdf' ? 'document' : 'image', mimeType: mime, dataUrl: `data:${mime};base64,${bytes.toString('base64')}` };
},
- async close() {
+ async close({ pendingEntries = [], saveReceipt } = {}) {
for (const entry of [...activeRuns.values()]) await backend.stop(entry.handle).catch(() => {});
- for (const page of ownedPages) await page.close().catch(() => {});
+ // Closing a tab deletes the extension journal. Persist exact terminal
+ // receipts first; otherwise retain the browser for live reconciliation.
+ let preserveBrowser = false;
+ for (const entry of pendingEntries) {
+ try {
+ const receipt = await backend.inspectSavedRun(entry);
+ if (!saveReceipt || receipt.active || !terminalStatuses.has(receipt.status)) throw new Error('Journal is not durably terminal.');
+ await saveReceipt(entry, receipt);
+ } catch { preserveBrowser = true; }
+ }
+ if (preserveBrowser && !attached) return { preserved: true };
+ if (!preserveBrowser) for (const page of ownedPages) await page.close().catch(() => {});
ownedPages.clear(); handles.clear(); checkpoints.clear();
await transport?.close?.().catch(() => {});
transport = null;
diff --git a/website-tests/core.test.mjs b/website-tests/core.test.mjs
index 539bd7767..8adad7814 100644
--- a/website-tests/core.test.mjs
+++ b/website-tests/core.test.mjs
@@ -215,3 +215,36 @@ test('copied placeholder configuration defaults to exactly one owned fixture and
const live = await loadConfig({ cwd, env: {}, overrides: { target: 'live' } }); assert.equal(selectScenarios(live).length, 8);
await assert.rejects(main(['run', '--target', 'live'], { cwd, env: {} }), { code: 'live_scenario_selection_required' });
});
+
+test('paired Cloud stages use actor evidence and reserve B for receipts', async t => {
+ const cfg = await config(t, { actors: { A: { backend: 'cloud', name: 'actor' }, B: { backend: 'local', name: 'observer' } }, manualEvidenceFile: 'unused' });
+ Object.assign(cfg.sites.x, { manualActorIdentityVerified: true, observerIdentity: 'receiver', recipientIdentity: 'receiver', recipient: 'receiver' });
+ cfg.allowedRecipients = ['receiver'];
+ const { runner } = injectedRunner(cfg, path.join(cfg.artifacts, 'one'));
+ runner.manualCheckpoint = async () => {};
+ await runner.backend('A');
+ runner.backends.A.capabilities.domObservation = false;
+ const roles = [];
+ runner.observe = async role => { roles.push(role); return { actualEffect: true }; };
+ await runner.initialize();
+ const result = await runner.runScenario({ ...simpleScenario, requiresObserver: true,
+ steps: [{ id: 'publish', actor: 'A', action: 'post' }, { id: 'receipt', actor: 'B', action: 'navigation' }] });
+ await runner.close();
+ assert.equal(result.status, 'passed', JSON.stringify(result));
+ assert.deepEqual(roles, ['A', 'B']);
+});
+
+test('runner shutdown durably saves pending local receipts', async t => {
+ const cfg = await config(t), { runner } = injectedRunner(cfg, path.join(cfg.artifacts, 'one'), { observed: false });
+ await runner.initialize(); await runner.runScenario(simpleScenario);
+ runner.backends.A.close = async ({ pendingEntries, saveReceipt }) => {
+ assert.equal(pendingEntries.length, 1);
+ const entry = pendingEntries[0];
+ await saveReceipt(entry, { backend: 'local', source: 'installed-extension-run-journal', tabId: entry.tabId,
+ requestId: entry.requestId, runId: entry.runId, status: 'completed', active: false, content: 'private' });
+ };
+ await runner.close();
+ const ledger = await MutationLedger.load(runner.ledger.filename, cfg);
+ assert.equal(ledger.pendingEntries()[0].localReceipt.status, 'completed');
+ assert.equal(JSON.stringify(ledger.data).includes('private'), false);
+});
diff --git a/website-tests/ledger.mjs b/website-tests/ledger.mjs
index 914efa84f..9c9ab5c60 100644
--- a/website-tests/ledger.mjs
+++ b/website-tests/ledger.mjs
@@ -38,6 +38,13 @@ export class MutationLedger {
for (const key of ['status', 'runId', 'sessionId', 'tabId', 'completedAt', 'code', 'verifiedAt', 'remoteName', 'sha256']) if (patch[key] !== undefined) entry[key] = patch[key];
await this.save(); return entry;
}
+ async saveLocalReceipt(requestId, receipt) {
+ const entry = this.data.entries.find(item => item.requestId === requestId);
+ if (!validLocalReceipt(entry, receipt)) throw new HarnessError('local_saved_run_identity_mismatch');
+ entry.localReceipt = { backend: 'local', source: receipt.source, tabId: receipt.tabId,
+ requestId, runId: receipt.runId, status: receipt.status, active: false };
+ await this.save();
+ }
async recordResource(entry, resource, identity) {
if (!resource?.id || !resource?.url || !identity) throw new HarnessError('resource_ownership_unproven');
const item = { id: resource.id, url: resource.url, kind: resource.kind, conversationId: resource.conversationId,
@@ -59,3 +66,10 @@ export class MutationLedger {
pendingEntries() { return this.data.entries.filter(e => ['attempted', 'accepted', 'ambiguous', 'running', 'needs_user_input'].includes(e.status)); }
pendingResources() { return this.data.resources.filter(r => r.cleanup !== 'verified'); }
}
+
+export function validLocalReceipt(entry, receipt) {
+ return !!entry && receipt?.backend === 'local' && receipt.source === 'installed-extension-run-journal'
+ && Number.isSafeInteger(entry.tabId) && entry.tabId > 0 && receipt.tabId === entry.tabId && receipt.requestId === entry.requestId && !!receipt.runId
+ && (!entry.runId || receipt.runId === entry.runId) && receipt.active === false
+ && ['completed', 'failed', 'aborted', 'stopped', 'cancelled'].includes(receipt.status);
+}
diff --git a/website-tests/local.test.mjs b/website-tests/local.test.mjs
index e26a118e7..ab213cb7d 100644
--- a/website-tests/local.test.mjs
+++ b/website-tests/local.test.mjs
@@ -621,3 +621,22 @@ test('installed MV3 extension reports real source and attached-browser detach pr
const stillAlive = await fetch(`${cdpUrl}/json/version`);
assert.equal(stillAlive.status, 200, 'CDP detachment leaves the Chrome process alive.');
});
+
+test('shutdown saves an exact terminal receipt before destroying its tab journal', async t => {
+ const { backend, calls } = await rig(t, { prior: { requestId: 'saved-request', runId: 'saved-run', status: 'failed', events: [] } });
+ await backend.connect(); await backend.open('https://x.com/');
+ await backend.close({ pendingEntries: [{ tabId: 31, runId: 'saved-run', requestId: 'saved-request' }],
+ saveReceipt: async (entry, receipt) => {
+ assert.equal(calls.some(call => call[0] === 'page.close'), false);
+ assert.equal(receipt.requestId, entry.requestId); assert.equal(receipt.status, 'failed');
+ calls.push(['receipt.saved']);
+ } });
+ assert.ok(calls.findIndex(call => call[0] === 'receipt.saved') < calls.findIndex(call => call[0] === 'page.close'));
+});
+
+test('shutdown preserves a dedicated browser if its pending receipt cannot be saved', async t => {
+ const { backend, calls } = await rig(t);
+ await backend.connect(); await backend.open('https://x.com/');
+ assert.deepEqual(await backend.close({ pendingEntries: [{ tabId: 31, requestId: 'unknown' }], saveReceipt: async () => {} }), { preserved: true });
+ assert.equal(calls.some(call => ['page.close', 'context.close', 'transport.close'].includes(call[0])), false);
+});
diff --git a/website-tests/recovery.mjs b/website-tests/recovery.mjs
index b68556d99..4ef12180b 100644
--- a/website-tests/recovery.mjs
+++ b/website-tests/recovery.mjs
@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
import path from 'node:path';
import { createHash, randomUUID } from 'node:crypto';
import { authorize, HarnessError, lockFiles, placeholder, redact, safeError } from './config.mjs';
-import { MutationLedger } from './ledger.mjs';
+import { MutationLedger, validLocalReceipt } from './ledger.mjs';
import { WorkflowRunner, createBackend, publicDoctor } from './runner.mjs';
import { sites, normalizeIdentity } from './sites.mjs';
import { scenarios, planTask, verifyEvidence } from './scenarios.mjs';
@@ -261,7 +261,8 @@ export async function recover(config, directory, args = {}, cleanup = false, { b
if (!runId && !entry.tabId) fail('explicit_dispatch_receipt_required');
const value = await backend(role, entry);
const runtime = config.actors[role].backend === 'cloud' ? await value.getRun(runId)
- : value.inspectSavedRun ? await value.inspectSavedRun(entry) : null;
+ : validLocalReceipt(entry, entry.localReceipt) ? entry.localReceipt
+ : value.inspectSavedRun ? await value.inspectSavedRun(entry) : null;
if (!runtime) fail('runtime_terminal_receipt_required');
const terminal = runtime.active !== true && TERMINAL.has(runtime.status);
receipts.set(entry.requestId, { terminal, runtime });
diff --git a/website-tests/recovery.test.mjs b/website-tests/recovery.test.mjs
index 083240123..625fbdee6 100644
--- a/website-tests/recovery.test.mjs
+++ b/website-tests/recovery.test.mjs
@@ -436,3 +436,25 @@ test('unknown upload hash or mismatched remote bytes remain pending without any
assert.equal((await loaded(mismatch)).pendingEntries().length, 1);
assert.ok(mismatch.calls.every(call => call.method === 'GET' || call.method === 'POST' && call.url.endsWith('/downloads-access')));
});
+
+test('recovery uses a durable exact local receipt after shutdown deletes the live journal', async t => {
+ const ctx = await setup(t);
+ await capture(ctx, 'publish', { id: '123', url: ctx.binding.url, kind: 'post' });
+ const entry = await ctx.ledger.attempt({ scenario: ctx.scenario.id, stage: 'cleanup', actor: 'A', action: 'delete', marker });
+ await ctx.ledger.update(entry.requestId, { status: 'ambiguous', tabId: 7, runId: 'cleanup-run' });
+ await ctx.ledger.saveLocalReceipt(entry.requestId, { backend: 'local', source: 'installed-extension-run-journal',
+ tabId: 7, requestId: entry.requestId, runId: 'cleanup-run', active: false, status: 'stopped' });
+ await assert.rejects(ctx.ledger.saveLocalReceipt(entry.requestId, { ...entry.localReceipt, runId: 'other' }), { code: 'local_saved_run_identity_mismatch' });
+ const mock = injected(ctx, { removed: ['123'] });
+ const original = mock.backendFactory;
+ mock.backendFactory = async (...args) => {
+ const backend = await original(...args);
+ backend.inspectSavedRun = async () => { throw new Error('Tab was closed'); };
+ return backend;
+ };
+ const report = await recover(ctx.config, ctx.directory, {}, false, mock);
+ assert.equal(report.counts.blocked, 0, JSON.stringify(report));
+ assert.equal((await loaded(ctx)).pendingEntries().length, 0);
+ assert.equal((await loaded(ctx)).pendingResources().length, 0);
+ assert.equal(mock.calls.run.length, 0);
+});
diff --git a/website-tests/runner.mjs b/website-tests/runner.mjs
index b6d8135b4..9a9cb7abd 100644
--- a/website-tests/runner.mjs
+++ b/website-tests/runner.mjs
@@ -189,10 +189,9 @@ export class WorkflowRunner {
if (!site.originAllowed(url, binding)) throw new HarnessError('site_origin_mismatch');
if (this.config.actors.A.backend === 'cloud' && binding.manualActorIdentityVerified !== true)
throw new HarnessError('cloud_actor_identity_confirmation_required');
- const cloudPrivatePhases = this.config.actors.A.backend === 'cloud' && scenario.steps.some(stage =>
- stage.expectation === 'composer' || scenario.kind === 'files');
- if (cloudPrivatePhases && (!this.config.manualEvidenceFile || !this.manualCheckpoint))
- throw new HarnessError('cloud_private_phase_requires_manual_evidence', 'A receiver cannot observe the actor’s private draft/folder.', 'unsupported');
+ const cloudActorEvidence = this.config.actors.A.backend === 'cloud' && scenario.steps.some(stage => stage.actor !== 'B');
+ if (cloudActorEvidence && (!this.config.manualEvidenceFile || !this.manualCheckpoint))
+ throw new HarnessError('cloud_private_phase_requires_manual_evidence', 'Actor stages require evidence from the actor’s selected browser.', 'unsupported');
const actor = await this.backend('A');
// Establish independent observation before allowing any remote mutation.
const observerRole = scenario.requiresObserver || actor.capabilities?.domObservation === false && this.config.actors.B.backend ? 'B' : 'A';
@@ -241,8 +240,7 @@ export class WorkflowRunner {
const plan = this.taskPlanner({ scenario, stage, context });
const task = typeof plan === 'string' ? plan : plan.task;
const phase = plan.observation?.phase || stage.phase || stage.expectation || 'resource';
- const actorPrivatePhase = phase === 'composer' || scenario.kind === 'files' && stage.actor !== 'B';
- const viewRole = stage.actor === 'B' ? 'B' : actor.capabilities?.domObservation === false && !actorPrivatePhase ? observerRole : 'A';
+ const viewRole = stage.actor === 'B' ? 'B' : 'A';
let observedContext = { ...context, ...plan.observation, observedAfter: new Date(stageStart).toISOString(), expectedIdentity: viewRole === 'B' ? binding.observerIdentity || binding.recipientIdentity : binding.expectedIdentity };
if (stage.actor === 'B' && stage.action === 'navigation') {
const evidence = await this.observe('B', scenario.site, observedContext, phase);
@@ -350,7 +348,10 @@ export class WorkflowRunner {
}
async close() {
if (this.events.length) await fs.writeFile(path.join(this.directory, 'events.json'), JSON.stringify(this.events, null, 2), { mode: 0o600 });
- for (const backend of Object.values(this.backends)) await backend.close().catch(() => {});
+ for (const [role, backend] of Object.entries(this.backends)) await backend.close({
+ pendingEntries: this.ledger?.pendingEntries().filter(entry => entry.actor === role) || [],
+ saveReceipt: (entry, receipt) => this.ledger.saveLocalReceipt(entry.requestId, receipt),
+ }).catch(() => {});
for (const lockPath of this.lockPaths || []) {
if (!this.ledger) continue;
const lock = JSON.parse(await fs.readFile(lockPath, 'utf8'));