@jobshimo/browser-link 0.26.0 → 0.27.1

package/dist/extension/background.js

@@ -2,7 +2,7 @@ import { buildSnapshotJs, buildFindJs, buildClickResolveJs, buildTypeResolveJs,
 import { buildKeyEventSequence, resolveKey, modifiersToBitmask, MODIFIER_BITS, } from './keymap.js';
 import { resolveSettleParams, settleSafely } from './settle.js';
 import { runFlow, } from './flow.js';
-import { appendFlowHistory, createFlowRegistry, flowHistoryKey, parseFlowHistory, toHistoryEntry, } from './flow-registry.js';
+import { MAX_DETACHED_FLOW_MS, appendFlowHistory, createFlowRegistry, detachedFlowKey, detachedFlowRecordsToEvict, finishedDetachedFlowRecord, flowHistoryKey, flowIdFromDetachedFlowKey, minimalDetachedFlowRecord, parseDetachedFlowRecord, parseFlowHistory, startedDetachedFlowRecord, terminatedDetachedFlowRecord, terminatedFlowHistoryEntry, toFlowStatus, toHistoryEntry, } from './flow-registry.js';
 import { DEFAULT_IDLE_TTL_MINUTES, IDLE_TTL_STORAGE_KEY, IDLE_TTL_UPDATED_AT_STORAGE_KEY, clampIdleTtlMinutes, parseIncomingSettings, shouldAcceptIncomingSettings, shouldDisconnectForIdle, shouldScheduleIdleSweep, } from './idle-policy.js';
 import { DEFAULT_FLOW_RECORDING_ENABLED, FLOW_RECORDING_STORAGE_KEY, FLOW_RECORDING_UPDATED_AT_STORAGE_KEY, normalizeFlowRecordingEnabled, parseIncomingFlowRecordingSettings, } from './flow-recording-policy.js';
 import { buildRecorderJs, buildStopRecorderJs } from './inpage/recorder.js';
@@ -173,6 +173,12 @@ const tabStates = new Map();
  * the worker mid-flow the flow dies with it, the entry goes with it, and
  * the popup shows nothing running — which is the truth. A registry that
  * survived the worker would have to describe flows that no longer exist.
+ *
+ * A DETACHED flow additionally leaves a `detached-flow:<id>` record in
+ * `chrome.storage.session` (see `flow-registry.ts`), which is a different
+ * thing entirely: not a live registry, but the paper trail that lets
+ * `recoverDetachedFlows` below notice a worker termination and report it
+ * as `failed` / `worker-terminated` instead of leaving a phantom.
  */
 const flowRegistry = createFlowRegistry();
 /** Fallback id for a `browser.flow` that arrived without one (a server
@@ -1298,6 +1304,9 @@ async function handleFlow(tabId, state, msg, p) {
     // be the worst possible failure of this flag, so only the exact
     // boolean opts into it.
     const dryRun = p.dry_run === true;
+    // Strict `=== true` for the same reason: a flow that silently detached
+    // would keep acting after the caller believed it had returned.
+    const detach = p.detach === true;
     // The server mints the id (see `browser-dispatch.ts`) so the agent gets
     // it back even when the extension never answers. The local fallback
     // covers a server too old to send one: the popup's Stop button must work
@@ -1306,39 +1315,113 @@ async function handleFlow(tabId, state, msg, p) {
     // A dry run dispatches nothing and finishes in milliseconds, so it is
     // deliberately NOT registered: there is nothing to stop, and listing it
     // would push real runs out of a 20-entry history with entries that never
-    // touched the page.
+    // touched the page. It also ignores `detach` — projecting a flow is
+    // fast and synchronous whichever way the real run would go.
     if (dryRun) {
         const projection = await runFlow(rawSteps, buildFlowDeps(tabId, state), {
             dryRun: true,
         });
         return { kind: 'tool.response', id: msg.id, ok: true, result: projection };
     }
-    flowRegistry.register({ flowId, tabId, steps: rawSteps.length });
+    if (detach) {
+        // ONE detached flow per tab, enforced HERE because the registry is the
+        // only place that knows. Two loops clicking through the same page have
+        // no use case and every failure mode: they interleave on the same DOM,
+        // race each other's `while_found` probes, and leave a human with two
+        // Stop buttons and no way to tell which is which. The error names the
+        // running id so the caller can inspect or stop it.
+        const running = flowRegistry.detachedForTab(tabId);
+        if (running) {
+            return {
+                kind: 'tool.response',
+                id: msg.id,
+                ok: false,
+                error: `flow: a detached flow is already running on this tab (${running.flowId}). ` +
+                    `Wait for it, or stop it with browser.flow_cancel, before detaching another.`,
+            };
+        }
+    }
+    const entry = flowRegistry.register({
+        flowId,
+        tabId,
+        steps: rawSteps.length,
+        detached: detach,
+        ...(detach ? { expiresAt: Date.now() + MAX_DETACHED_FLOW_MS } : {}),
+    });
     // Best effort and deliberately not awaited: the title is only there so
     // the popup can tell two concurrent flows apart, and no flow should pay
     // a round trip to chrome.tabs before its first step.
     void chrome.tabs
         .get(tabId)
         .then((tab) => {
-        const entry = flowRegistry.get(flowId);
-        if (entry && typeof tab.title === 'string')
+        if (typeof tab.title === 'string')
             entry.title = tab.title;
     })
         .catch(() => {
         // Tab gone or title unavailable — the panel falls back to the id.
     });
-    const shouldCancel = () => flowRegistry.get(flowId)?.cancelled === true;
+    // Also covers the detached ceiling: `shouldStop` flips the entry to
+    // `expired` the first time the deadline has passed, so the outcome
+    // distinguishes "ran out of time" from "someone pressed Stop".
+    const shouldCancel = () => flowRegistry.shouldStop(flowId, Date.now());
+    const run = () => runFlow(rawSteps, {
+        ...buildFlowDeps(tabId, state, shouldCancel),
+        shouldCancel,
+        onProgress: (progress) => {
+            entry.progress = progress;
+        },
+    });
+    if (detach) {
+        // The record lands BEFORE the first step is dispatched: it is the only
+        // evidence a worker termination leaves behind, and a flow that acted
+        // before it was recorded would be exactly the invisible run this whole
+        // slice exists to make impossible. A record that will not store is
+        // therefore a refusal, not a warning: nothing has run yet, and that is
+        // the only moment refusing is still free.
+        if (!(await persistLaunchRecord(entry))) {
+            flowRegistry.finish(flowId);
+            return {
+                kind: 'tool.response',
+                id: msg.id,
+                ok: false,
+                error: 'flow: could not persist the detached-flow launch record ' +
+                    '(chrome.storage.session write failed). NOTHING was executed: a ' +
+                    'detached flow with no record acts irreversibly with no evidence.',
+            };
+        }
+        // Deliberately floating. This is the entire point of `detach`: the
+        // tool.response below goes out now, the loop keeps running, and the
+        // agent's turn is free. `recordFinishedFlow` in the `finally` is what
+        // eventually retires it.
+        void (async () => {
+            let flowResult = null;
+            try {
+                flowResult = await run();
+            }
+            catch {
+                // A throw (detached debugger, closed tab) is a `failed` outcome —
+                // recorded below from a null result. Nothing to rethrow to: there
+                // is no caller left.
+            }
+            finally {
+                recordFinishedFlow(flowId, flowResult);
+            }
+        })();
+        return {
+            kind: 'tool.response',
+            id: msg.id,
+            ok: true,
+            result: {
+                detached: true,
+                started_at: entry.startedAt,
+                steps: rawSteps.length,
+                expires_at: entry.expiresAt,
+            },
+        };
+    }
     let flowResult = null;
     try {
-        flowResult = await runFlow(rawSteps, {
-            ...buildFlowDeps(tabId, state, shouldCancel),
-            shouldCancel,
-            onProgress: (progress) => {
-                const entry = flowRegistry.get(flowId);
-                if (entry)
-                    entry.progress = progress;
-            },
-        });
+        flowResult = await run();
         // The wire-level response is ok:true whenever the flow RAN (even a
         // failed step, and even a cancellation, is a legitimate business
         // outcome — same pattern as wait_for's matched:false) — flowResult
@@ -1353,6 +1436,20 @@ async function handleFlow(tabId, state, msg, p) {
         recordFinishedFlow(flowId, flowResult);
     }
 }
+/** Answer the `flow_status` wire tool (behind `browser.flow_status`).
+ * Reads the live registry first and falls back to the persisted detached
+ * record; an id neither knows comes back as `state: 'unknown'`, never as an
+ * error — see `FlowState`. */
+async function handleFlowStatus(msg, p) {
+    const flowId = typeof p.flow_id === 'string' ? p.flow_id : '';
+    if (flowId.length === 0) {
+        return { kind: 'tool.response', id: msg.id, ok: false, error: 'flow_status: flow_id required' };
+    }
+    const entry = flowRegistry.get(flowId);
+    const record = entry ? undefined : await readDetachedFlowRecord(flowId);
+    const status = toFlowStatus(flowId, entry, record);
+    return { kind: 'tool.response', id: msg.id, ok: true, result: status };
+}
 /** The perform* bindings `runFlow` needs, in one place so the real run and
  * the dry-run projection cannot drift apart. `shouldCancel` is threaded
  * into `performWaitFor` alone: it is the only perform* with a loop of its
@@ -1368,35 +1465,270 @@ function buildFlowDeps(tabId, state, shouldCancel) {
         buildRecoverySnapshot: () => evaluateInTab(tabId, buildSnapshotJs({ only_interactive: true, max_interactive: 40 })),
     };
 }
-/** Serializes history writes. Appending is a read-modify-write over an
- * async store, so two flows on the same tab finishing microseconds apart
- * would otherwise both read the same list and the second `set` would drop
- * the first's entry. One global chain (rather than one per tab) is enough:
- * these writes happen once per finished flow, never in a hot path. */
-let flowHistoryWrites = Promise.resolve();
-/** Retire a finished flow: drop it from the in-flight registry and prepend
- * its outcome to the tab's session-scoped history. Never throws — a
- * storage failure must not turn a completed flow into a failed tool call. */
+/** Serializes EVERY flow-related `chrome.storage.session` mutation —
+ * history appends, detached-record writes, and the history drop when a tab
+ * closes. Appending is a read-modify-write over an async store, so two
+ * flows on the same tab finishing microseconds apart would otherwise both
+ * read the same list and the second `set` would drop the first's entry;
+ * and a tab-removal delete OUTSIDE the chain could be overtaken by a
+ * still-running flow's late append, resurrecting the key it just dropped.
+ * One global chain (rather than one per tab or one per concern) is enough:
+ * these writes happen a handful of times per flow, never in a hot path. */
+let flowStorageWrites = Promise.resolve();
+/** Append one unit of work to the serialized chain. Swallows failures so a
+ * single storage error cannot poison every later write — the session store
+ * dies with the browser anyway, so a lost entry is not worth surfacing. */
+function queueFlowStorageWrite(work) {
+    flowStorageWrites = flowStorageWrites.then(work).catch(() => {
+        // Best effort, and the chain must survive.
+    });
+    return flowStorageWrites;
+}
+/** Same chain, but the caller learns whether the write landed. A lost
+ * detached-flow record is not a lost entry: the launch record is a flow's
+ * only evidence, and a lost terminal write leaves a stale `running` record
+ * the next worker start reads as an orphan. The rejection is converted to
+ * `false`, never rethrown, so the chain survives as it does above. */
+function queueTrackedFlowStorageWrite(work) {
+    const tracked = flowStorageWrites.then(work).then(() => true, () => false);
+    flowStorageWrites = tracked.then(() => undefined);
+    return tracked;
+}
+/** Chrome tab ids whose flow history has been dropped because the tab
+ * closed, and WHEN. Chrome reuses tab ids within a session, so the
+ * timestamp matters: a flow that started before the removal belongs to the
+ * tab that is gone and must not be written back (that is the resurrection
+ * the serialized chain alone cannot prevent, since the late write is
+ * queued after the delete); a flow that started after it belongs to
+ * whatever tab holds the id now. Cleared when a tab connects under the id
+ * again, so this never grows past live-plus-recently-closed tabs. */
+const flowHistoryDroppedAt = new Map();
+/** Retire a finished flow: drop it from the in-flight registry, prepend its
+ * outcome to the tab's session-scoped history, and — for a detached flow —
+ * finalize its record and emit the one-per-flow audit event. Never throws:
+ * a storage failure must not turn a completed flow into a failed tool call,
+ * and for a detached flow there is no caller left to fail anyway. */
 function recordFinishedFlow(flowId, result) {
     const entry = flowRegistry.finish(flowId);
     if (!entry)
         return;
-    const historyEntry = toHistoryEntry(entry, result, Date.now());
-    const key = flowHistoryKey(entry.tabId);
-    flowHistoryWrites = flowHistoryWrites
-        .then(async () => {
+    const endedAt = Date.now();
+    const droppedAt = flowHistoryDroppedAt.get(entry.tabId);
+    // Skip the append entirely for a tab that has already been removed — see
+    // `flowHistoryDroppedAt`. Ordering on the chain is not enough on its own,
+    // because this write is queued AFTER the delete was.
+    if (droppedAt === undefined || droppedAt <= entry.startedAt) {
+        appendFlowHistoryEntry(entry.tabId, toHistoryEntry(entry, result, endedAt));
+    }
+    if (!entry.detached)
+        return;
+    const record = finishedDetachedFlowRecord(entry, result, endedAt);
+    // Exactly ONE summary event per detached flow, pushed here and nowhere
+    // else — never per iteration. `BridgeEventLog` holds 200 entries, so a
+    // single 200-iteration run emitting per-iteration events would silently
+    // evict every other event in the log, which is the opposite of an audit
+    // trail. If the socket is already gone the event is deferred onto the
+    // record and flushed when the tab next registers.
+    if (!publishFlowFinished(entry.tabId, record))
+        record.eventPending = true;
+    void persistTerminalRecord(record);
+}
+/** Prepend one entry to a tab's session-scoped flow history, on the
+ * serialized chain (the append is a read-modify-write, so two flows
+ * finishing microseconds apart would otherwise lose one). */
+function appendFlowHistoryEntry(tabId, historyEntry) {
+    const key = flowHistoryKey(tabId);
+    void queueFlowStorageWrite(async () => {
         const data = await chrome.storage.session.get(key);
         await chrome.storage.session.set({
             [key]: appendFlowHistory(parseFlowHistory(data[key]), historyEntry),
         });
-    })
-        .catch(() => {
-        // Best effort, and the chain must survive: the history is an
-        // operator convenience that dies with the browser session anyway, so
-        // one lost entry is not worth surfacing — but swallowing here is
-        // also what keeps a single failure from poisoning every later write.
     });
 }
+/** Push the one-per-flow summary `bridge.event`. Returns whether it
+ * actually went out — the caller defers it onto the record when it did
+ * not, so an audit trail is never quietly dropped just because the tab's
+ * socket happened to be closed. Counts and enums only: the manifest itself
+ * is addressable by `flow_id` through `browser.flow_status` and has no
+ * business in a 200-entry ring buffer. */
+function publishFlowFinished(tabId, record) {
+    const state = tabStates.get(tabId);
+    if (!state?.ws || state.ws.readyState !== WebSocket.OPEN)
+        return false;
+    send(state.ws, {
+        kind: 'bridge.event',
+        eventKind: 'flow-finished',
+        ...(state.serverTabId === undefined ? {} : { tabId: state.serverTabId }),
+        data: {
+            flow_id: record.flowId,
+            state: record.state,
+            detached: true,
+            steps: record.steps,
+            steps_completed: record.stepsCompleted,
+            ...(record.iterationsCompleted === undefined
+                ? {}
+                : { iterations_completed: record.iterationsCompleted }),
+            duration_ms: Math.max(0, (record.endedAt ?? record.startedAt) - record.startedAt),
+            ...(record.stoppedBy === undefined ? {} : { stopped_by: record.stoppedBy }),
+            manifest_available: record.manifest !== undefined,
+        },
+    });
+    return true;
+}
+/** Persist one detached-flow record and enforce the record cap. Runs on the
+ * serialized chain so a launch write and the matching terminal write can
+ * never land out of order. Reports whether THE RECORD landed; the cap sweep
+ * that follows is best effort and must not make a stored record look lost. */
+function writeDetachedFlowRecord(record) {
+    return queueTrackedFlowStorageWrite(async () => {
+        await chrome.storage.session.set({ [detachedFlowKey(record.flowId)]: record });
+        try {
+            const evict = detachedFlowRecordsToEvict(await readAllDetachedFlowRecords());
+            if (evict.length === 0)
+                return;
+            await chrome.storage.session.remove(evict.map((r) => detachedFlowKey(r.flowId)));
+        }
+        catch {
+            // Over the cap until the next write sweeps again.
+        }
+    });
+}
+/** Free session-storage quota by dropping every terminal record not still
+ * owing its summary event. Only after a rejected write: at that point old
+ * manifests are worth less than the launch record of a flow about to act.
+ *
+ * The sweep is deliberately GLOBAL, not scoped to the launching tab: it can
+ * discard a finished flow's manifest that another tab's agent had not read
+ * yet. That is the accepted trade. The alternative is refusing the launch,
+ * which leaves a flow about to do irreversible work with no record proving
+ * it started — and an unread manifest is recoverable by looking at the
+ * page, while a missing launch record makes a killed worker undetectable. */
+function pruneDetachedFlowRecords() {
+    return queueTrackedFlowStorageWrite(async () => {
+        const stale = (await readAllDetachedFlowRecords()).filter((r) => r.state !== 'running' && r.eventPending !== true);
+        if (stale.length === 0)
+            return;
+        await chrome.storage.session.remove(stale.map((r) => detachedFlowKey(r.flowId)));
+    });
+}
+/** Write the launch record and prove it landed, pruning old manifests and
+ * retrying ONCE when storage refuses (the plausible refusal is a quota one:
+ * ten records of up to 128 KB against pre-112 Chrome's 1 MB session cap).
+ * False means genuinely unstored — the caller must not start the flow. */
+async function persistLaunchRecord(entry) {
+    const record = startedDetachedFlowRecord(entry);
+    if (await writeDetachedFlowRecord(record))
+        return true;
+    await pruneDetachedFlowRecords();
+    return writeDetachedFlowRecord(record);
+}
+/** Write the terminal record and prove it landed. The retry STRIPS the
+ * manifest instead of repeating the same write: a failed terminal write
+ * does not lose an outcome, it invents a wrong one, because the stale
+ * `running` record left behind is read as `worker-terminated` next start.
+ * If the minimal record is refused too there is nothing left to try. */
+async function persistTerminalRecord(record) {
+    if (await writeDetachedFlowRecord(record))
+        return;
+    if (await writeDetachedFlowRecord(minimalDetachedFlowRecord(record)))
+        return;
+    console.warn('browser-link: detached-flow terminal record not persisted', record.flowId);
+}
+/** Read one detached-flow record. Drains the write chain first so a status
+ * poll landing microseconds after a flow ended never reports the stale
+ * `running` record the launch write left behind. */
+async function readDetachedFlowRecord(flowId) {
+    try {
+        await flowStorageWrites;
+        const key = detachedFlowKey(flowId);
+        const data = await chrome.storage.session.get(key);
+        return parseDetachedFlowRecord(data[key]) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Every detached-flow record currently in session storage. One
+ * `get(null)` rather than N keyed reads — the same sweep
+ * `resumePendingReconnects` does, and the record set is capped at
+ * `MAX_DETACHED_FLOW_RECORDS`. */
+async function readAllDetachedFlowRecords() {
+    let stored;
+    try {
+        stored = await chrome.storage.session.get(null);
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const [key, value] of Object.entries(stored)) {
+        if (flowIdFromDetachedFlowKey(key) === null)
+            continue;
+        const record = parseDetachedFlowRecord(value);
+        if (record)
+            records.push(record);
+    }
+    return records;
+}
+/**
+ * Reconcile detached-flow records left behind by a service worker Chrome
+ * terminated. Runs ONCE per worker start, before anything can register a
+ * flow, so every `running` record it finds is by definition orphaned: the
+ * loop that owned it lived in the dead worker's memory.
+ *
+ * The settled rule (see `terminatedDetachedFlowRecord`, and `DECISIONS.md`
+ * §13): mark it `failed` / `worker-terminated`, write the history entry,
+ * and NEVER resume. A detached flow does irreversible bulk work; resuming
+ * one whose real progress died with the worker would double-act on some
+ * unknowable prefix of it. Failing loudly is the only honest option, and a
+ * flow that looks `running` while nothing executes it is worse than either.
+ */
+async function recoverDetachedFlows() {
+    const now = Date.now();
+    for (const record of await readAllDetachedFlowRecords()) {
+        const terminated = terminatedDetachedFlowRecord(record, now);
+        if (!terminated)
+            continue;
+        void writeDetachedFlowRecord(terminated);
+        appendFlowHistoryEntry(terminated.tabId, terminatedFlowHistoryEntry(terminated));
+    }
+}
+/** Flows whose summary event is being flushed right now. `eventPending` is
+ * only cleared by a write queued AFTER the event goes out, so two fast
+ * reconnects of the same tab can both read the same still-pending record
+ * and publish its event twice — an audit trail that double-counts a flow is
+ * as wrong as one that drops it. Membership holds from the send until the
+ * clearing write settles; a write that failed leaves the flag set, and the
+ * next flush legitimately retries. */
+const flushingFlowEvents = new Set();
+/** Flush the summary events of any detached flow that ended while this
+ * tab's socket was down — including every flow the worker was killed
+ * under, whose event could not possibly have been sent at the time (no
+ * worker, no socket). Called from the `tab.registered` handler, which is
+ * the first moment there is somewhere to send them. */
+async function flushPendingFlowEvents(tabId) {
+    // Drain the chain first, as `readDetachedFlowRecord` does: a terminal
+    // record still queued reads as stale `running`, with no event to flush.
+    await flowStorageWrites;
+    for (const record of await readAllDetachedFlowRecords()) {
+        if (record.tabId !== tabId || record.eventPending !== true)
+            continue;
+        if (flushingFlowEvents.has(record.flowId))
+            continue;
+        flushingFlowEvents.add(record.flowId);
+        if (!publishFlowFinished(tabId, record)) {
+            flushingFlowEvents.delete(record.flowId);
+            return;
+        }
+        const { eventPending: _sent, ...flushed } = record;
+        void writeDetachedFlowRecord(flushed).then((stored) => {
+            // A refused clearing write must keep the flag: storage still says
+            // eventPending, so releasing it here would republish a sent event.
+            if (stored)
+                flushingFlowEvents.delete(record.flowId);
+        });
+    }
+}
 async function handleDrag(tabId, msg, p, optStr) {
     // Thin wire wrapper over performDrag — the same pattern the standalone
     // click/type/press/wait_for cases use over their perform* functions.
@@ -1571,6 +1903,13 @@ async function handleTool(state, msg) {
             }
             case 'flow':
                 return await handleFlow(tabId, state, msg, p);
+            case 'flow_status':
+                // Deliberately NOT scoped to `tabId`: the registry and the
+                // detached records are worker-global, keyed by flow_id. The tab
+                // this request arrived on is a transport route, not a filter — so
+                // an agent can still read a finished flow's manifest through any
+                // connected tab after the flow's own tab has closed.
+                return await handleFlowStatus(msg, p);
             case 'drag':
                 return await handleDrag(tabId, msg, p, optStr);
             case 'evaluate': {
@@ -1805,6 +2144,10 @@ async function resumePendingReconnects() {
     }
 }
 void resumePendingReconnects();
+// Same worker-start slot, same rationale: `chrome.storage.session` outlives
+// the service worker but not the browser, which is exactly the lifetime a
+// detached flow's record should have. See `recoverDetachedFlows`.
+void recoverDetachedFlows();
 /** Tabs with a `connectTab` currently in flight. The `tabStates.has` check
  * inside `doConnectTab` alone cannot prevent two concurrent connects — the
  * state lands only after three awaited chrome.* calls — so this SYNCHRONOUS
@@ -1833,6 +2176,11 @@ async function doConnectTab(tabId) {
     if (tabStates.has(tabId)) {
         return { ok: false, error: 'This tab is already connected' };
     }
+    // Whatever tab holds this Chrome id now, it is not the closed one whose
+    // history was dropped — so its own flows are free to write history
+    // again. Also what keeps `flowHistoryDroppedAt` from growing past
+    // live-plus-recently-closed tabs.
+    flowHistoryDroppedAt.delete(tabId);
     const tab = await chrome.tabs.get(tabId);
     if (!tab.url || !tab.title) {
         return { ok: false, error: 'Tab has no URL or title' };
@@ -1920,6 +2268,11 @@ async function doConnectTab(tabId) {
                         // asks the new primary to honour it. The primary emits
                         // `tab-renamed` in the bridge event log if it can't.
                         void storeTabId(tabId, msg.payload.tabId);
+                        // First moment there is a socket to send them on: deliver the
+                        // summary events of any detached flow that ended while this
+                        // tab was disconnected, including everything the worker was
+                        // killed under.
+                        void flushPendingFlowEvents(tabId);
                         settle({ ok: true, serverTabId: msg.payload.tabId });
                         return;
                     }
@@ -2481,9 +2834,15 @@ chrome.tabs.onRemoved.addListener((tabId) => {
     void forgetTabId(tabId);
     // …and its flow history. Chrome reuses tab ids within a session, so a
     // stale key would eventually show one tab's flows under another's.
-    void chrome.storage.session.remove(flowHistoryKey(tabId)).catch(() => {
-        // Best effort — session storage dies with the browser anyway.
-    });
+    //
+    // Two guards, because the delete alone is not enough. Routing it through
+    // the SAME serialized chain as the appends keeps it ordered against
+    // every write already queued; the `flowHistoryDroppedAt` stamp handles
+    // the other half — `cleanup` above only ASKS the tab's flows to stop, so
+    // one of them can still finish (and try to append) after this delete has
+    // run, resurrecting the key for a tab that no longer exists.
+    flowHistoryDroppedAt.set(tabId, Date.now());
+    void queueFlowStorageWrite(() => chrome.storage.session.remove(flowHistoryKey(tabId)));
 });
 /* Auto-connect tabs spawned by a connected tab.
  *