@reticlehq/server 3.8.2 → 3.10.0

package/dist/memory/cloud/sync-daemon.js

@@ -41,7 +41,7 @@ import { describeSync } from './sync-describe.js';
 import { diskSink, diskSource, policyScreenshots, readCloudState } from './sync-disk.js';
 import { resolveProjectCloud } from './cloud-config.js';
 import { watch } from 'node:fs';
-import { BackgroundSyncState, backgroundSyncGate, } from './background-sync.js';
+import { BackgroundSyncState, backgroundSyncGate, closeCycleGate, } from './background-sync.js';
 import { unmatchedRoots, unsyncedRoots } from './unsynced-roots.js';
 /**
  * The backstop: how often the daemon cycles when nothing under `.reticle` has changed. Long, because
@@ -186,38 +186,39 @@ export function startSyncDaemon(deps) {
     let wasLinked;
     /** The project the last cycle synced to: a re-link to another one is announced too. */
     let wasProject;
-    /** The last count logged per root: a root is announced when its count changes, never per tick. */
-    const announced = new Map();
+    /** The aggregate last logged: unlinked roots are announced as one line per change, never per tick. */
+    let announcedUnsynced;
     let unsynced = [];
     /** Which roots pushed this cycle, and whether each is linked by its own link file. */
     let rootsLinked = new Map();
     /** The linked roots that send flows: a link with `sync.flows` off keeps every flow local. */
     let rootsSendFlows = new Set();
-    /**
-     * Count what every root still owes, and say once per change where runs sit that nothing sends.
-     * Linked roots are listed too (the platform report and `doctor` read them), but only an unlinked
-     * one earns a log line: a linked root's pending runs are the next cycle's job.
-     */
+    /** Count what every root owes; unlinked roots are one aggregate line per change, never per tick. */
     const refreshUnsynced = async () => {
         const linked = rootsLinked;
         const sendsFlows = rootsSendFlows;
         unsynced = await unsyncedRoots(
         // With what no project claimed, which no cycle pushes: the dashboard's unsent list left it out.
         [...linked.keys(), ...unmatchedRoots(homedir())], (r) => Promise.resolve(true === linked.get(r)), (r) => Promise.resolve(sendsFlows.has(r)));
-        for (const entry of unsynced) {
-            const held = entry.runs + entry.flows;
-            if (entry.linked || announced.get(entry.root) === held) {
-                continue;
-            }
-            announced.set(entry.root, held);
-            log('reticle_cloud_unsynced_root', {
-                root: entry.root,
-                runs: entry.runs,
-                flows: entry.flows,
-                linked: entry.linked,
-                fix: "run `reticle connect` in that folder's project: this work is on this machine only",
-            });
+        const unlinked = unsynced.filter((entry) => !entry.linked);
+        const runs = unlinked.reduce((total, entry) => total + entry.runs, 0);
+        const flows = unlinked.reduce((total, entry) => total + entry.flows, 0);
+        const signature = JSON.stringify([unlinked.map((e) => [e.root, e.runs, e.flows]), runs, flows]);
+        if (0 === unlinked.length) {
+            announcedUnsynced = undefined;
+            return;
+        }
+        if (announcedUnsynced === signature) {
+            return;
         }
+        announcedUnsynced = signature;
+        log('reticle_cloud_unsynced_root', {
+            count: unlinked.length,
+            runs,
+            flows,
+            examples: unlinked.slice(0, 3).map((entry) => entry.root),
+            fix: 'run `reticle connect` in each project that owns these folders: this work is on this machine only',
+        });
     };
     /**
      * The cloud as this tick may use it: unchanged when the gate lets the root send, else with no
@@ -778,12 +779,10 @@ export function attachCloudSync(deps) {
         // and on the backstop timer.
         // Watching them too means one recursive watcher per linked repo — add it if siblings lag.
         watch: (onChange) => watchReticleRoot(deps.reticleRoot, onChange),
-        // Sent only while somebody is signed in, to a linked project that did not switch it off.
-        ...(signedIn === undefined
-            ? {}
-            : {
-                gate: (root, cloud) => backgroundSyncGate({ reticleRoot: root, cloud, env: deps.env, signedIn }),
-            }),
+        // Sent only to a linked project that did not switch it off; see `closeCycleGate` for no sign-in.
+        gate: (root, cloud) => signedIn === undefined
+            ? closeCycleGate(root, deps.env)
+            : backgroundSyncGate({ reticleRoot: root, cloud, env: deps.env, signedIn }),
         ...(deps.request === undefined ? {} : { request: deps.request }),
         ...(deps.intervalMs === undefined ? {} : { intervalMs: deps.intervalMs }),
     });

package/dist/memory/cloud/sync-screenshots.js

@@ -20,6 +20,11 @@ const HTTP_OK = 200;
 const NOT_THERE = new Set([404, 405]);
 /** Refused for good: too large (413), too many for one run (409). Retrying cannot change it. */
 const REFUSED_FOR_GOOD = new Set([409, 413]);
+/**
+ * The platform takes only JPEG and answers 400 to anything else, which stops the cycle. A desktop
+ * capture from a page SDK before 3.7 is a PNG, so it stays on this machine.
+ */
+const isJpeg = (image) => 0xff === image[0] && 0xd8 === image[1];
 /** The screenshots a run artifact lists, read defensively: a malformed entry is skipped. */
 function listed(payload) {
     const raw = 'object' === typeof payload && null !== payload
@@ -78,7 +83,7 @@ export async function syncScreenshots(deps) {
                     done.add(keyOf(shot));
                     sent[run.runId] = [...done];
                 };
-                if (image.byteLength > STEP_SCREENSHOT.MAX_BYTES) {
+                if (image.byteLength > STEP_SCREENSHOT.MAX_BYTES || !isJpeg(image)) {
                     markDone();
                     continue;
                 }

package/dist/memory/journal/attach-journal.js

@@ -19,7 +19,8 @@ export function makeJournalAttach(deps) {
             log('journal_skipped_unsafe_session_id', { sessionId: session.id });
             return;
         }
-        const journal = new SessionJournal(deps.fs, session.artifactRoot ?? deps.reticleRoot, session.id);
+        // The session's clock stamps each record's `t`, so it also bounds a cut that left nothing to parse.
+        const journal = new SessionJournal(deps.fs, session.artifactRoot ?? deps.reticleRoot, session.id, { now: () => session.elapsed() });
         // Same SessionJournal is both the write sink and the read fall-through for queries after eviction.
         session.setJournal(new JournalRecorder(journal, { now: () => session.elapsed() }), journal);
     };

package/dist/memory/journal/drive-flow.d.ts

@@ -44,6 +44,13 @@ export interface DriveProgram {
  *
  * So it is not a tool and not a rule. It runs at teardown, in code, on every session.
  */
+/**
+ * The claims one tape step carries: its own `expect`, and the `expect` of each of its sub-steps.
+ *
+ * A `reticle_act { steps }` journey is one tape step, and each claim is on its sub-step. When only
+ * the step's own `expect` was read, a journey with four held claims was "unproven" and was not saved.
+ */
+export declare function claimsOf(step: TapeStep): Predicate[];
 /** The one condition on saving, and the reason the whole thing is safe. */
 export declare function carriesAnAssertion(steps: readonly TapeStep[]): boolean;
 /** Every auto-saved flow's name starts here, which is what lets a merge tell them from hand-named ones. */

package/dist/memory/journal/drive-flow.js

@@ -1,4 +1,4 @@
-import { ActionType, QueryBy, REPLAY_PROGRAM_VERSION, asFlowName, defaultIsSensitiveKey, } from '@reticlehq/core';
+import { ActionType, FlowPredicateSchema, QueryBy, REPLAY_PROGRAM_VERSION, asFlowName, asRecord, isCredentialFieldName, } from '@reticlehq/core';
 import { journeySentence } from '@reticlehq/core';
 /**
  * What a session drove, saved as a replayable flow — without anybody asking for it.
@@ -11,9 +11,23 @@ import { journeySentence } from '@reticlehq/core';
  *
  * So it is not a tool and not a rule. It runs at teardown, in code, on every session.
  */
+/**
+ * The claims one tape step carries: its own `expect`, and the `expect` of each of its sub-steps.
+ *
+ * A `reticle_act { steps }` journey is one tape step, and each claim is on its sub-step. When only
+ * the step's own `expect` was read, a journey with four held claims was "unproven" and was not saved.
+ */
+export function claimsOf(step) {
+    const subs = Array.isArray(step.args['steps']) ? step.args['steps'] : [];
+    const subClaims = subs.flatMap((sub) => {
+        const parsed = FlowPredicateSchema.safeParse(asRecord(sub)['expect']);
+        return parsed.success ? [parsed.data] : [];
+    });
+    return step.expect === undefined ? subClaims : [step.expect, ...subClaims];
+}
 /** The one condition on saving, and the reason the whole thing is safe. */
 export function carriesAnAssertion(steps) {
-    return steps.some((step) => step.expect !== undefined);
+    return steps.some((step) => 0 < claimsOf(step).length);
 }
 /** Squeeze any string into one safe, lower-case filename segment. */
 const segment = (value, max) => value
@@ -28,10 +42,12 @@ const segment = (value, max) => value
  * said nothing about what it was for.
  */
 function provedSentence(steps) {
-    return journeySentence(steps.flatMap((step) => (step.expect === undefined ? [] : [step.expect])));
+    return journeySentence(steps.flatMap(claimsOf));
 }
 /** Every auto-saved flow's name starts here, which is what lets a merge tell them from hand-named ones. */
 export const DRIVE_FLOW_PREFIX = 'drive-';
+/** The most characters one segment of core's FLOW_NAME_PATTERN holds. */
+const FLOW_NAME_MAX_LENGTH = 64;
 /**
  * A readable name for a journey, led by WHY it was driven.
  *
@@ -52,7 +68,10 @@ export function driveFlowName(route, steps = []) {
     // Minted here: every character has just been forced through `segment`, so this IS the validated
     // boundary the brand is meant to be created at.
     const parts = [lead, ...('' !== why || 0 === leg.length ? [] : [leg])].filter((p) => '' !== p);
-    return asFlowName(`${DRIVE_FLOW_PREFIX}${0 === parts.length ? 'journey' : parts.join('-')}`);
+    // Cut to the flow-name limit: a sentence and a route together went over it, the save refused
+    // the name, and session end dropped the flow with nothing said.
+    const body = segment(parts.join('-'), FLOW_NAME_MAX_LENGTH - DRIVE_FLOW_PREFIX.length);
+    return asFlowName(`${DRIVE_FLOW_PREFIX}${'' === body ? 'journey' : body}`);
 }
 /** Why session end saved no flow, as reported on the `flow_recorded` step. */
 export const DriveFlowSkipReason = {
@@ -106,16 +125,25 @@ function segmentsByRoute(steps) {
     return out;
 }
 /**
- * A fill into a field the network channel would redact — the sign-in a journey must not carry.
+ * A fill into a field whose name says it holds a credential — the sign-in a journey must not carry.
  * Read off the recorder's anchor args: a testid names the field by `value`, a role by `name`.
  */
 function typesASecret(step) {
-    const action = step.args['action'];
-    if (ActionType.FILL !== action && ActionType.TYPE !== action)
+    // A sign-in sent as one reticle_act sequence carries its fills as sub-steps.
+    const subs = step.args['steps'];
+    if (Array.isArray(subs)) {
+        return subs.some((sub) => fillsASecret(asRecord(sub)));
+    }
+    return fillsASecret(step.args);
+}
+function fillsASecret(args) {
+    const action = args['action'];
+    if (ActionType.FILL !== action && ActionType.TYPE !== action) {
         return false;
-    const by = step.args['by'];
-    const field = QueryBy.TESTID === by ? step.args['value'] : step.args['name'];
-    return 'string' === typeof field && defaultIsSensitiveKey(field);
+    }
+    const by = args['by'];
+    const field = QueryBy.TESTID === by ? args['value'] : args['name'];
+    return 'string' === typeof field && isCredentialFieldName(field);
 }
 /**
  * The tape without the attempts an agent made again. An action that declared nothing, followed at
@@ -126,11 +154,13 @@ function typesASecret(step) {
 function withoutRetries(steps) {
     return steps.filter((step, i) => {
         const next = steps[i + 1];
-        if (next === undefined || step.expect !== undefined || next.expect === undefined)
+        if (next === undefined || step.expect !== undefined || next.expect === undefined) {
             return true;
+        }
         // Tried again where it was tried: a page later it is a step of the journey, not a retry.
-        if (step.route !== next.route || step.page !== next.page || step.mocked !== next.mocked)
+        if (step.route !== next.route || step.page !== next.page || step.mocked !== next.mocked) {
             return true;
+        }
         const { expect: _declared, ...again } = next.args;
         const { expect: _none, ...first } = step.args;
         return step.tool !== next.tool || JSON.stringify(first) !== JSON.stringify(again);
@@ -138,8 +168,9 @@ function withoutRetries(steps) {
 }
 /** A flow per journey, so two journeys in one session are two regression tests rather than one. */
 export function driveFlowsFrom(tape) {
-    if (tape === undefined || 0 === tape.steps.length)
+    if (tape === undefined || 0 === tape.steps.length) {
         return { programs: [], outcome: {} };
+    }
     const programs = [];
     let unproven = 0;
     let mocked = 0;

package/dist/memory/journal/journal-recorder.d.ts

@@ -30,8 +30,10 @@ export interface JournalReadLoss {
     /** Parsed records evicted from the retained set. Exact, unlike `droppedBytes`. */
     droppedEvents: number;
     /**
-     * Latest timestamp of parsed cache evictions, inclusive. Omitted after a byte cut skips
-     * unparsed records: their time range is unknown even when newer bytes survive.
+     * Latest `t` the loss can reach, inclusive: a parsed record that was evicted, or the bound of a
+     * byte cut. Omitted while a cut has no bound, which means every window is lost. A cut has no
+     * bound until a record after it is parsed, and none at all when the clock can have started
+     * again across it.
      */
     lostThroughT?: number;
     /** Human-and-agent readable summary. Present so a consumer never has to compose one. */

package/dist/memory/journal/session-journal.d.ts

@@ -42,6 +42,13 @@ export interface SessionJournalOptions {
     maxReadBytes?: number;
     maxRetainedBytes?: number;
     maxRetainedEvents?: number;
+    /**
+     * The session's elapsed-ms clock, the same clock that stamps each record's `t`. It bounds a cut
+     * that left no readable record: every skipped byte was on disk at the read, so its `t` is at or
+     * before the time of the read. Without it, such a cut stays unbounded until a later read parses
+     * a record.
+     */
+    now?: () => number;
 }
 /**
  * Default byte budget for one serialized writer's event ledger (#986).

package/dist/memory/journal/session-journal.js

@@ -146,11 +146,13 @@ export class SessionJournal {
     #droppedBytes = 0;
     /** Parsed records evicted from the retained set. Exact — these were counted, not estimated. */
     #droppedEvents = 0;
-    /**
-     * Latest parsed eviction timestamp, or +Infinity after unparsed bytes were skipped.
-     * -Infinity means no loss. Later intact reads cannot narrow an unknown discarded time range.
-     */
+    /** Latest `t` that a cut or an eviction can reach, inclusive. -Infinity means no loss. */
     #lostThroughT = Number.NEGATIVE_INFINITY;
+    /** A cut skipped bytes and no record after it has been parsed yet, so its bound is unknown. */
+    #cutPending = false;
+    /** The last record parsed, so a cut can tell whether the clock started again across it. */
+    #lastParsed;
+    #now;
     constructor(fs, root, sessionId, options = {}) {
         if (!isValidSessionId(sessionId)) {
             throw new Error(`refusing to journal an unsafe session id: ${sessionId}`);
@@ -171,6 +173,7 @@ export class SessionJournal {
         this.#maxRetainedBytes = boundedOption(options.maxRetainedBytes, JOURNAL_READ_LIMITS.MAX_RETAINED_BYTES, 'maxRetainedBytes');
         this.#maxRetainedEvents = boundedOption(options.maxRetainedEvents, JOURNAL_READ_LIMITS.MAX_RETAINED_EVENTS, 'maxRetainedEvents');
         this.#eventBytesCap = cap;
+        this.#now = options.now;
     }
     /**
      * Append a batch, or refuse it at the byte cap and say so.
@@ -416,10 +419,15 @@ export class SessionJournal {
             // never skips, so its start IS the offset we asked for.
             const from = chunk.from ?? this.#eventBytesConsumed;
             const skipped = Math.max(0, from - this.#eventBytesConsumed);
-            this.#ingestTail(chunk.text);
+            // Before the ingest, so the first record parsed after the cut bounds it.
             if (skipped > 0) {
                 this.#noteCut(skipped);
             }
+            this.#ingestTail(chunk.text);
+            const now = this.#now;
+            if (this.#cutPending && now !== undefined) {
+                this.#boundCut({ t: now() });
+            }
             // Resume at the end of the last COMPLETE line, counted forward over the bytes that actually
             // ARRIVED. Not from `chunk.size`: that is the file's end as `fstat` reported it, and a read
             // truncated or cut short returns less — a cursor there would skip every unread byte, silently
@@ -494,6 +502,10 @@ export class SessionJournal {
             }
             const result = ReticleEventSchema.safeParse(parsed);
             if (result.success) {
+                if (this.#cutPending) {
+                    this.#boundCut(result.data);
+                }
+                this.#lastParsed = result.data;
                 this.#eventCache.push(result.data);
                 // Its cost in the file, newline included — so the retained bound is in the same unit the
                 // read ceiling and the loss report are.
@@ -543,13 +555,37 @@ export class SessionJournal {
         }
     }
     /**
-     * Skipped bytes have unknown timestamps: page clocks can reset while the journal id survives.
-     * A surviving tail cannot bound records that were never parsed. Later intact reads cannot
-     * reconstruct that history; finite bounds apply only to parsed cache evictions.
+     * Skipped bytes are not parsed, so their `t` is not known at the cut. The first record parsed
+     * after the cut, or the time of the read, can bound them (see `#boundCut`). Until then, the cut
+     * reaches every window.
      */
     #noteCut(skippedBytes) {
         this.#droppedBytes += skippedBytes;
-        this.#lostThroughT = Number.POSITIVE_INFINITY;
+        this.#cutPending = true;
+    }
+    /**
+     * Bound the pending cut at `next`: the first record parsed after it, or the time of the read.
+     *
+     * The file is append-only, and one connection stamps `t` from one monotonic clock
+     * (`Session.elapsed`). So when the clock did not start again across the cut, each skipped record
+     * has a `t` at or before `next.t`.
+     *
+     * A reload or a reconnect keeps the session id and starts the clock again, and one window can
+     * span it: a window opened at t=150 on the old connection can hold skipped old records at t=200
+     * while the new connection's records start at t=10. A bound from the new clock then clears a
+     * window that lost evidence. So the cut stays unbounded, for good, when the reset cannot be
+     * ruled out: no record was parsed before the cut, or `t` or `seq` went down, or the document
+     * changed. This check is conservative but not complete. A reconnect in the same document whose
+     * new clock already passed the old `t` shows none of the three signs.
+     */
+    #boundCut(next) {
+        const last = this.#lastParsed;
+        this.#cutPending = false;
+        if (last === undefined || clockStartedAgain(last, next)) {
+            this.#lostThroughT = Number.POSITIVE_INFINITY;
+            return;
+        }
+        this.#lostThroughT = Math.max(this.#lostThroughT, next.t);
     }
     /**
      * What these reads could not produce, or `undefined` when nothing was lost.
@@ -562,7 +598,7 @@ export class SessionJournal {
         if (0 === this.#droppedBytes && 0 === this.#droppedEvents) {
             return undefined;
         }
-        const bounded = Number.isFinite(this.#lostThroughT);
+        const bounded = !this.#cutPending && Number.isFinite(this.#lostThroughT);
         return {
             droppedBytes: this.#droppedBytes,
             droppedEvents: this.#droppedEvents,
@@ -621,6 +657,18 @@ export class SessionJournal {
         return out;
     }
 }
+/** Did the clock start again between `last` and `next`? A field one record lacks proves nothing. */
+function clockStartedAgain(last, next) {
+    if (next.t < last.t) {
+        return true;
+    }
+    if (last.seq !== undefined && next.seq !== undefined && next.seq < last.seq) {
+        return true;
+    }
+    return (last.documentId !== undefined &&
+        next.documentId !== undefined &&
+        next.documentId !== last.documentId);
+}
 /**
  * The closure report a session's sidecar holds — details when it can be read, the bare fact when not.
  *

package/dist/memory/project/root-claims.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The `.reticle` folder a caller meant by `root`. Agents pass the project folder, the one they work
+ * in, so a folder that holds a `.reticle` stands for it — and so does any existing directory, since
+ * a fresh worktree has none until the first run writes one, the same way a `.reticle` path is
+ * accepted before it exists. A path nowhere on disk is the caller's to fix, and the refusals name
+ * the path to pass. Openings exported so error-recovery classifies both as the caller's mistake.
+ */
+export declare const ARTIFACT_ROOT_ABSOLUTE_REFUSAL: string;
+export declare const ARTIFACT_ROOT_MISSING_REFUSAL: string;
 /** Claim `root` for the session a lease registers. Takes a `.reticle` folder or the project folder holding one. */
 export declare function claimArtifactRoot(leaseId: string, root: string): void;
 /** Every root a lease claimed in this process, released or not. Sync reads it to find the work. */

package/dist/memory/project/root-claims.js

@@ -17,20 +17,25 @@ const claims = new Map();
 const everClaimed = new Set();
 /**
  * The `.reticle` folder a caller meant by `root`. Agents pass the project folder, the one they work
- * in, so a folder that holds a `.reticle` stands for it. Anything else is refused with the path to pass.
+ * in, so a folder that holds a `.reticle` stands for it — and so does any existing directory, since
+ * a fresh worktree has none until the first run writes one, the same way a `.reticle` path is
+ * accepted before it exists. A path nowhere on disk is the caller's to fix, and the refusals name
+ * the path to pass. Openings exported so error-recovery classifies both as the caller's mistake.
  */
+export const ARTIFACT_ROOT_ABSOLUTE_REFUSAL = `root must be an absolute path to a ${ReticleDir.ROOT} folder`;
+export const ARTIFACT_ROOT_MISSING_REFUSAL = `root must be an existing directory, or the ${ReticleDir.ROOT} folder inside one`;
 function resolveArtifactRoot(root) {
     if (!isAbsolute(root)) {
-        throw new Error(`root must be an absolute path to a ${ReticleDir.ROOT} folder, got ${root}`);
+        throw new Error(`${ARTIFACT_ROOT_ABSOLUTE_REFUSAL}, got ${root}`);
     }
     if (ReticleDir.ROOT === basename(root)) {
         return root;
     }
     const inside = join(root, ReticleDir.ROOT);
-    if (isDirectory(inside)) {
+    if (isDirectory(inside) || isDirectory(root)) {
         return inside;
     }
-    throw new Error(`root must be the ${ReticleDir.ROOT} folder, or a project folder that contains one, got ${root}. Pass ${inside}`);
+    throw new Error(`${ARTIFACT_ROOT_MISSING_REFUSAL}, got ${root}. Pass ${inside}`);
 }
 function isDirectory(path) {
     try {

package/dist/portal/bridge/bridge.d.ts

@@ -57,6 +57,18 @@ export declare const WS_CLOSE_REASON: {
      */
     readonly INVALID_HELLO_CLOSE: "invalid hello: version skew. Put SDK, build plugin and server on one release.";
 };
+/** WS close codes + reasons the bridge sends to the SDK (1008 = policy violation, 1013 = try again later). */
+export declare const WS_CLOSE: {
+    readonly TOO_MANY_HANDSHAKES: readonly [1013, "too many pending handshakes"];
+    readonly HELLO_TIMEOUT: readonly [1008, "hello timeout"];
+    readonly INVALID_MESSAGE: readonly [1008, "invalid message"];
+    readonly INVALID_HELLO: readonly [1008, "invalid hello: version skew. Put SDK, build plugin and server on one release."];
+    readonly HELLO_DUPLICATE: readonly [1008, "hello already received"];
+    readonly AUTH_FAILED: readonly [1008, "authentication failed — restart the dev server; a reload keeps the old pairing token"];
+    readonly SESSION_LIMIT: readonly [1013, "session limit reached"];
+    readonly PROTOCOL_MISMATCH: readonly [1008, "protocol version mismatch — @reticlehq/browser and server disagree"];
+    readonly HANDLER_FAILED: readonly [1011, "the Reticle daemon failed handling a message — reload the page to reconnect"];
+};
 interface BridgeOptions {
     port: number;
     host?: string;
@@ -107,10 +119,7 @@ export declare class Bridge {
      */
     attachSessionReady(handler: SessionReadyHandler): void;
     /** Register a callback fired the instant a session is created — used to attach the durable journal. */
-    /**
-     * Teardown handler fired when a session is removed (tab closed/disconnected). Without it the journal's
-     * batched tail (< one flush batch) never reaches disk and the learned ambient map is discarded.
-     */
+    /** Teardown when a session is removed (tab closed/disconnected). Additive — every handler runs. */
     attachSessionEnd(handler: (session: Session) => Promise<void>): void;
     /**
      * Register what to do when the panel's sync button is pressed.

package/dist/portal/bridge/bridge.js

@@ -101,7 +101,7 @@ export const WS_CLOSE_REASON = {
     INVALID_HELLO_CLOSE: 'invalid hello: version skew. Put SDK, build plugin and server on one release.',
 };
 /** WS close codes + reasons the bridge sends to the SDK (1008 = policy violation, 1013 = try again later). */
-const WS_CLOSE = {
+export const WS_CLOSE = {
     TOO_MANY_HANDSHAKES: [1013, 'too many pending handshakes'],
     HELLO_TIMEOUT: [1008, 'hello timeout'],
     INVALID_MESSAGE: [1008, 'invalid message'],
@@ -190,8 +190,10 @@ export class Bridge {
      */
     #onSessionCreate = [];
     #onProjectAdopted = [];
-    /** Fired when a session is removed — flushes its journal tail + persists what it learned. */
-    #onSessionEnd;
+    // Fired when a session is removed. ADDITIVE: a single slot meant one teardown silently displaced
+    // the other — the same trap the create-side note describes. The durable journal flushes its tail;
+    // the page-error journal drops the session's dedupe memory.
+    #onSessionEnd = [];
     /** Wired by the daemon: push to the dashboard now, because somebody asked in the panel. */
     #onSyncRequest;
     #onHarnessRequest;
@@ -737,7 +739,9 @@ export class Bridge {
                     log('session_disconnected', { sessionId: ended.id });
                     // Best-effort teardown: flush the journal tail + persist ambient learning. Never awaited here
                     // (the socket is already closing) and never allowed to reject into the close handler.
-                    void this.#onSessionEnd?.(ended).catch(() => undefined);
+                    for (const handler of this.#onSessionEnd) {
+                        void handler(ended).catch(() => undefined);
+                    }
                     // AFTER teardown is started, and deliberately not awaited on it. The payload says a
                     // session ended, which is already true here; making it wait for the journal flush would
                     // put a hook in the path of a socket close for no gain to the consumer.
@@ -835,12 +839,9 @@ export class Bridge {
         this.#onSessionReady.push(handler);
     }
     /** Register a callback fired the instant a session is created — used to attach the durable journal. */
-    /**
-     * Teardown handler fired when a session is removed (tab closed/disconnected). Without it the journal's
-     * batched tail (< one flush batch) never reaches disk and the learned ambient map is discarded.
-     */
+    /** Teardown when a session is removed (tab closed/disconnected). Additive — every handler runs. */
     attachSessionEnd(handler) {
-        this.#onSessionEnd = handler;
+        this.#onSessionEnd.push(handler);
     }
     /**
      * Register what to do when the panel's sync button is pressed.

package/dist/portal/input/download-capture.d.ts

@@ -0,0 +1,7 @@
+import { type NetworkDetail } from './network-detail.js';
+/** The part of a CDP session this needs, kept structural so it can be tested with a fake. */
+export interface CdpLike {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    on(event: string, handler: (event: unknown) => void): void;
+}
+export declare function attachDownloadCapture(cdp: CdpLike, emit: (detail: NetworkDetail) => void, pageUrl: () => string): Promise<void>;

package/dist/portal/input/download-capture.js

@@ -0,0 +1,92 @@
+import { buildNetworkDetail } from './network-detail.js';
+import { drivenRedactionPolicy } from './driven-redaction.js';
+/**
+ * Capture a file the server sends as a download, on a page Reticle drives.
+ *
+ * A click that becomes a download leaves the page as a navigation the browser turns into a file.
+ * Measured on Chromium, nothing the page can see records it: no page `request`/`response` event, no
+ * CDP `Network.responseReceived` on the page target, and a Playwright route does not intercept it.
+ * So a `net` check on a working export missed. CDP request interception at the response stage does
+ * see it, with the status and headers, so this listens there.
+ *
+ * Document responses only, and every paused response is let through at once: the capture must never
+ * change or delay what the page receives. Chromium only; a browser without the Fetch domain gets no
+ * capture rather than an error.
+ */
+const DOCUMENT_RESPONSES = { patterns: [{ resourceType: 'Document', requestStage: 'Response' }] };
+/**
+ * The body is read only for a text attachment of known, small size. Reading it holds the whole file
+ * in memory, so a large or binary download keeps its status and headers and gets no body: a body
+ * check on it stays undecidable rather than costing the run its memory.
+ */
+const MAX_BODY_READ_BYTES = 1024 * 1024;
+const TEXTUAL = /text\/|json|csv|xml/i;
+function readableBodySize(headers) {
+    const length = Number(headers['content-length']);
+    return (Number.isFinite(length) &&
+        length <= MAX_BODY_READ_BYTES &&
+        TEXTUAL.test(headers['content-type'] ?? ''));
+}
+async function readBody(cdp, requestId) {
+    try {
+        const got = (await cdp.send('Fetch.getResponseBody', { requestId }));
+        if ('string' !== typeof got.body) {
+            return undefined;
+        }
+        return true === got.base64Encoded ? Buffer.from(got.body, 'base64').toString('utf8') : got.body;
+    }
+    catch {
+        return undefined;
+    }
+}
+function headersOf(raw) {
+    const headers = {};
+    if (!Array.isArray(raw)) {
+        return headers;
+    }
+    for (const entry of raw) {
+        const { name, value } = (entry ?? {});
+        if ('string' === typeof name && 'string' === typeof value) {
+            headers[name.toLowerCase()] = value;
+        }
+    }
+    return headers;
+}
+function isAttachment(headers) {
+    return /^\s*attachment\b/i.test(headers['content-disposition'] ?? '');
+}
+async function onPaused(cdp, paused, emit, pageUrl) {
+    const requestId = 'string' === typeof paused.requestId ? paused.requestId : undefined;
+    try {
+        const headers = headersOf(paused.responseHeaders);
+        const url = paused.request?.url;
+        const status = paused.responseStatusCode;
+        if (isAttachment(headers) && 'string' === typeof url && 'number' === typeof status) {
+            const method = paused.request?.method;
+            const responseBody = requestId !== undefined && readableBodySize(headers)
+                ? await readBody(cdp, requestId)
+                : undefined;
+            emit(buildNetworkDetail({
+                url,
+                ...('string' === typeof method ? { method } : {}),
+                status,
+                headers,
+                resourceType: 'document',
+                ...(responseBody === undefined ? {} : { responseBody }),
+                pageUrl: pageUrl(),
+            }, drivenRedactionPolicy()));
+        }
+    }
+    catch {
+        // Recording is best-effort; letting the response through below is not.
+    }
+    if (requestId !== undefined) {
+        await cdp.send('Fetch.continueRequest', { requestId }).catch(() => undefined);
+    }
+}
+export async function attachDownloadCapture(cdp, emit, pageUrl) {
+    cdp.on('Fetch.requestPaused', (event) => {
+        void onPaused(cdp, event ?? {}, emit, pageUrl);
+    });
+    await cdp.send('Fetch.enable', DOCUMENT_RESPONSES);
+}