@reticlehq/server 3.8.1 → 3.9.0

package/dist/language/flows/replay.js

@@ -1,5 +1,5 @@
 import { SECRET_FIELD_ARG, SECRET_NAME_ARG, secretKeyForFill, secretValue, } from './fields/flow-secret-field.js';
-import { EventType, FlowPredicateSchema, MUTATING_METHODS, Verified, isDevToolingUrl, pathOf, } from '@reticlehq/core';
+import { EventType, FlowPredicateSchema, MUTATING_METHODS, isDevToolingUrl, pathOf, } from '@reticlehq/core';
 import { DANGEROUS_ACTION_CONFIRM_ARG, DOCUMENT_ANCHOR_ROLE, ReticleCommand, QueryBy, isGlobalPressCall, } from '@reticlehq/core';
 import { ReticleTool, invokedFlowMissing } from '@reticlehq/core';
 import { formatStepAddress } from 'open-verification';
@@ -22,8 +22,9 @@ function ambiguousRoleNote(role, name) {
  * resolution — can't drift between them.
  */
 export function queryRefs(result) {
-    if (!result.ok)
+    if (!result.ok) {
         return [];
+    }
     const payload = asRecord(result.result);
     const elements = Array.isArray(payload['elements']) ? payload['elements'] : [];
     return elements.map((e) => asString(asRecord(e)['ref']) ?? '').filter((r) => r.length > 0);
@@ -47,12 +48,14 @@ export function replayActionArgs(value, confirmDangerous = false, field) {
     const key = field === undefined ? undefined : secretKeyForFill(args, field);
     delete args[SECRET_NAME_ARG];
     delete args[SECRET_FIELD_ARG];
-    if (confirmDangerous)
+    if (confirmDangerous) {
         args[DANGEROUS_ACTION_CONFIRM_ARG] = true;
+    }
     if (key !== undefined) {
         const supplied = secretValue(key, process.env);
-        if (supplied !== undefined && supplied.length > 0)
+        if (supplied !== undefined && supplied.length > 0) {
             args['value'] = supplied;
+        }
     }
     return args;
 }
@@ -62,20 +65,24 @@ export function replayActionArgs(value, confirmDangerous = false, field) {
  */
 function recordedFieldName(step) {
     const by = asString(step['by']);
-    if (QueryBy.TESTID === by)
+    if (QueryBy.TESTID === by) {
         return asString(step['value']);
-    if (QueryBy.ROLE === by)
+    }
+    if (QueryBy.ROLE === by) {
         return asString(step['name']);
+    }
     return undefined;
 }
 /** The element's source location from an action result, when the framework stamped one. */
 function sourceFromResult(res) {
     const source = asRecord(res['source']);
-    if (typeof source['file'] !== 'string' || typeof source['line'] !== 'number')
+    if (typeof source['file'] !== 'string' || typeof source['line'] !== 'number') {
         return undefined;
+    }
     const out = { file: source['file'], line: source['line'] };
-    if ('number' === typeof source['column'])
+    if ('number' === typeof source['column']) {
         out['column'] = source['column'];
+    }
     return out;
 }
 /**
@@ -91,8 +98,9 @@ export { pathOf };
  */
 export function wroteIn(events) {
     return events.some((event) => {
-        if (EventType.NET_REQUEST !== event.type)
+        if (EventType.NET_REQUEST !== event.type) {
             return false;
+        }
         const method = asString(event.data['method'])?.toUpperCase() ?? '';
         return MUTATING_METHODS.includes(method) && !isDevToolingUrl(asString(event.data['url']));
     });
@@ -122,7 +130,9 @@ route,
 /** The session that acted: only recordings it started take the step. */
 session, 
 /** The act's window sent a write request; see `wroteIn`. */
-wrote = false) {
+wrote = false, 
+/** The act as the ambient tape keeps it, when that differs. See RecordingStore.capture. */
+ambientArgs) {
     // NO `active()` gate. `RecordingStore.capture` opens the AMBIENT tape on its first step, and that
     // branch was unreachable from here: this returned early whenever nothing was open, and the only
     // thing that opened anything was `reticle_record { action: "start" }`. So the comment on `capture`
@@ -134,8 +144,15 @@ wrote = false) {
     // recorded cannot contribute to either.
     // A click on Reticle's own panel (the HUD exposed) is not a step of the app's journey: saved, the
     // app's flow pressed Run Harness on replay, a paid drive, under an intent that never named it.
-    if (true === asRecord(res)['reticleUi'])
+    if (true === asRecord(res)['reticleUi']) {
         return;
+    }
+    const step = capturedStep(args, res, route, wrote);
+    const ambient = ambientArgs === undefined ? undefined : capturedStep(ambientArgs, res, route, wrote);
+    recordings.capture(step, route, session, ambient);
+}
+/** One act as a recorded step, with the claim the agent declared on it. */
+function capturedStep(args, res, route, wrote) {
     const step = compileActStep(args, res);
     // Keep the assertion the agent actually made. `act_and_wait { until }` IS the agent saying what
     // success means — the large majority of calls carry one — and dropping it produced a flow graded
@@ -143,36 +160,50 @@ wrote = false) {
     // story failing at its last step. See enforceableExpect below.
     const declared = args['until'] ?? args['predicate'];
     const expect = enforceableExpect(declared);
-    if (expect !== undefined)
+    if (expect !== undefined) {
         step.expect = expect;
-    else if (declared !== undefined)
+    }
+    else if (declared !== undefined) {
         step.unkeptExpect = UNKEPT_EXPECT;
-    if (route !== undefined)
+    }
+    if (route !== undefined) {
         step.page = route;
+    }
     const intent = asString(args['intent'])?.trim();
-    if (intent !== undefined && intent.length > 0)
+    if (intent !== undefined && intent.length > 0) {
         step.intent = intent;
-    if (wrote)
+    }
+    if (wrote) {
         step.writes = true;
-    recordings.capture(step, route, session);
+    }
+    return step;
 }
 /**
- * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
- * on a yes. Recorded before the verdict, a step kept an `until` that came back `no` or `no-fault` —
- * a regression test asserting something never once observed to hold because of the action. The
- * action itself is always recorded: it happened, and replay needs it to reach the next step.
+ * Capture an act_and_wait once its verdict is known.
+ *
+ * The rule act_sequence keeps (#988). A recording somebody opened keeps every claim the agent
+ * declared, held or not: dropping a refuted one saved a flow that replayed green on the defect it
+ * had caught. The ambient tape keeps a claim only if the action made it hold (`held`), so a flow cut
+ * from it never replays a claim that was never once true because of the action. The action is
+ * always recorded: replay needs it to reach the next step.
+ *
+ * Keyed on `held`, not on `verified: yes`. A claim the action made hold under an `unknown` or a
+ * contradicted verdict is still what the agent proved about the page, and dropping it left the
+ * replay with no check at all. One function decides both tapes: a second rule that took the claim off the tape
+ * after the fact ran before this capture, so it took the PREVIOUS step's claim, which had passed.
  */
-export function captureVerdictedAct(recordings, args, res, route, verified, session, 
+export function captureVerdictedAct(recordings, args, res, route, held, session, 
 /** The act's window sent a write request; see `wroteIn`. */
 wrote = false) {
     const { until: _until, predicate: _predicate, ...unproved } = args;
-    captureAct(recordings, Verified.YES === verified ? args : unproved, res, route, session, wrote);
+    captureAct(recordings, args, res, route, session, wrote, held ? undefined : unproved);
 }
 /** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
 export function captureAssertion(recordings, raw, session) {
     const expect = enforceableExpect(raw);
-    if (expect !== undefined)
+    if (expect !== undefined) {
         recordings.attachExpect(expect, session);
+    }
 }
 /**
  * A declared predicate, as a recorded expectation — or nothing.
@@ -186,8 +217,9 @@ export function captureAssertion(recordings, raw, session) {
  * Every one of those was a claim the agent made and the file did not keep.
  */
 function enforceableExpect(raw) {
-    if (raw === undefined)
+    if (raw === undefined) {
         return undefined;
+    }
     // The flow file's own schema, so capture keeps exactly what a load would accept — a predicate
     // holding a session ref is refused by both, rather than recorded here and rejected on read.
     const parsed = FlowPredicateSchema.safeParse(raw);
@@ -232,8 +264,9 @@ function compileAnchorArgs(r, ref, action, actArgs) {
     const compiled = anchorArgs(r, ref, action, actArgs);
     // The SDK says the target holds a secret (a password input, whatever its label). Carried beside
     // the anchor so the saved flow redacts the fill by what the field IS, not by what it is called.
-    if (true === r['secret'])
+    if (true === r['secret']) {
         compiled.args[SECRET_FIELD_ARG] = true;
+    }
     return compiled;
 }
 function anchorArgs(r, ref, action, actArgs) {
@@ -262,10 +295,12 @@ function anchorArgs(r, ref, action, actArgs) {
             action,
             args: actArgs,
         };
-        if (source !== undefined)
+        if (source !== undefined) {
             testidArgs['source'] = source;
-        if (testidOf !== undefined)
+        }
+        if (testidOf !== undefined) {
             testidArgs['of'] = testidOf;
+        }
         return { args: testidArgs, stable: true };
     }
     // Role + NAME before component: a component/source anchor names the JSX site, so every row's copy
@@ -282,8 +317,9 @@ function anchorArgs(r, ref, action, actArgs) {
             action,
             args: actArgs,
         };
-        if (source !== undefined)
+        if (source !== undefined) {
             roleArgs['source'] = source;
+        }
         if ('number' === typeof r['nth'] && 'number' === typeof r['of']) {
             roleArgs['nth'] = r['nth'];
             roleArgs['of'] = r['of'];
@@ -293,10 +329,12 @@ function anchorArgs(r, ref, action, actArgs) {
     const component = asString(r['component']);
     if (component !== undefined || source !== undefined) {
         const componentArgs = { by: QueryBy.COMPONENT, action, args: actArgs };
-        if (component !== undefined)
+        if (component !== undefined) {
             componentArgs['component'] = component;
-        if (source !== undefined)
+        }
+        if (source !== undefined) {
             componentArgs['source'] = source;
+        }
         return { args: componentArgs, stable: true };
     }
     return { args: { ref, action, args: actArgs }, stable: false };
@@ -314,12 +352,14 @@ export function compileSequenceStep(args, res) {
     let stable = inputSteps.length > 0;
     const subSteps = inputSteps.flatMap((raw, i) => {
         // A step on Reticle's own panel is not a step of the app's journey, as for a single act.
-        if (true === asRecord(resolved[i])['reticleUi'])
+        if (true === asRecord(resolved[i])['reticleUi']) {
             return [];
+        }
         const step = asRecord(raw);
         const compiled = compileAnchorArgs(asRecord(resolved[i]), asString(step['ref']) ?? '', asString(step['action']) ?? '', replayActionArgs(step['args']));
-        if (!compiled.stable)
+        if (!compiled.stable) {
             stable = false;
+        }
         // Each sub-step keeps its OWN declared consequence. A sequence records one step and replays as
         // one batch, but what each step CLAIMED is per step -- folding them together would let one
         // signal answer for every click in the journey.
@@ -346,18 +386,21 @@ export function compileSequenceStep(args, res) {
  */
 async function resolveRef(session, step) {
     // Dispatched the way it ran live: at the document, with no ref. See compileAnchorArgs.
-    if (isDocumentPress(step))
+    if (isDocumentPress(step)) {
         return { ref: '' };
+    }
     const by = asString(step.by);
     const value = asString(step.value);
     if (by === QueryBy.TESTID && value !== undefined) {
         const result = await session.command(ReticleCommand.QUERY, { by, value });
-        if (!result.ok)
+        if (!result.ok) {
             throw new Error(result.error ?? 'query failed');
+        }
         const refs = queryRefs(result);
         const ref = refs[0];
-        if (ref === undefined)
+        if (ref === undefined) {
             throw new Error(`testid '${value}' did not resolve in current page`);
+        }
         return refs.length > 1 ? { ref, note: ambiguousTestidNote(value) } : { ref };
     }
     // Role + accessible NAME: the anchor that distinguishes one row's control from another's, which
@@ -366,8 +409,9 @@ async function resolveRef(session, step) {
         const name = asString(step.name);
         const query = { by, value, ...(name === undefined ? {} : { name }) };
         const result = await session.command(ReticleCommand.QUERY, query);
-        if (!result.ok)
+        if (!result.ok) {
             throw new Error(result.error ?? 'query failed');
+        }
         const refs = queryRefs(result);
         const meant = refFor(step, refs);
         const ref = meant ?? refs[0];
@@ -385,8 +429,9 @@ async function resolveRef(session, step) {
             ...(source === undefined ? {} : { source }),
         };
         const result = await session.command(ReticleCommand.QUERY, query);
-        if (!result.ok)
+        if (!result.ok) {
             throw new Error(result.error ?? 'query failed');
+        }
         const refs = queryRefs(result);
         const ref = refs[0];
         if (ref === undefined) {
@@ -468,8 +513,9 @@ via = []) {
                 ...via,
             ]);
             results.push(...nested);
-            if (nested.some((r) => !r.ok))
+            if (nested.some((r) => !r.ok)) {
                 break;
+            }
             continue;
         }
         try {
@@ -480,8 +526,9 @@ via = []) {
                 for (const raw of subs) {
                     const sub = asRecord(raw);
                     const { ref, note } = await resolveRef(session, sub);
-                    if (note !== undefined)
+                    if (note !== undefined) {
                         notes.push(note);
+                    }
                     liveSteps.push({
                         ref,
                         action: asString(sub['action']) ?? '',
@@ -502,8 +549,9 @@ via = []) {
                     session.finishAction();
                 }
                 results.push(buildResult(step.tool, r.ok, r.error, notes));
-                if (!r.ok)
+                if (!r.ok) {
                     break;
+                }
             }
             else {
                 const { ref, note } = await resolveRef(session, step.args);
@@ -520,8 +568,9 @@ via = []) {
                     session.finishAction();
                 }
                 results.push(buildResult(step.tool, r.ok, r.error, note !== undefined ? [note] : []));
-                if (!r.ok)
+                if (!r.ok) {
                     break;
+                }
             }
         }
         catch (e) {
@@ -537,9 +586,11 @@ via = []) {
 }
 function buildResult(tool, ok, error, notes) {
     const base = { tool, ok };
-    if (!ok)
+    if (!ok) {
         base.error = error ?? 'command failed';
-    if (notes.length > 0)
+    }
+    if (notes.length > 0) {
         base.note = notes.join('; ');
+    }
     return base;
 }

package/dist/launch-chromium.d.ts

@@ -87,6 +87,7 @@ interface ProbeMachine {
     env: NodeJS.ProcessEnv;
     exists: (path: string) => boolean;
     pathProblem: (path: string) => ChromiumPathProblem | undefined;
+    platform?: NodeJS.Platform;
 }
 /**
  * The lease preflight's probe: "can a launch succeed?", which now includes the Chrome/Edge fallback

package/dist/launch-chromium.js

@@ -48,11 +48,15 @@ const CHANNEL_PATHS = {
     },
 };
 const WINDOWS_INSTALL_ROOTS = ['LOCALAPPDATA', 'PROGRAMFILES', 'PROGRAMFILES(X86)'];
+function darwinChannelCandidates(appPath, env) {
+    const home = env['HOME']?.replace(/\/+$/, '');
+    return undefined === home || 0 === home.length ? [appPath] : [appPath, `${home}${appPath}`];
+}
 /** Candidate executable paths for a channel on this platform; empty where it is not installable. */
 export function channelExecutableCandidates(channel, platform, env) {
     const paths = CHANNEL_PATHS[channel];
     if ('darwin' === platform)
-        return [paths.darwin];
+        return darwinChannelCandidates(paths.darwin, env);
     if ('linux' === platform)
         return [paths.linux];
     if ('win32' === platform) {
@@ -63,9 +67,21 @@ export function channelExecutableCandidates(channel, platform, env) {
     }
     return [];
 }
+function findInstalledBrowser(deps) {
+    for (const channel of CHANNEL_ORDER) {
+        const found = channelExecutableCandidates(channel, deps.platform, deps.env).find((p) => deps.exists(p));
+        if (undefined !== found) {
+            // Playwright resolves a channel from its own registry (/Applications on macOS). A browser in
+            // ~/Applications is not in that registry, so launch it by executablePath instead.
+            const outsideRegistry = 'darwin' === deps.platform && found !== CHANNEL_PATHS[channel].darwin;
+            return outsideRegistry ? { channel, executablePath: found } : { channel };
+        }
+    }
+    return undefined;
+}
 /** The first installed Chrome/Edge on this machine, or undefined. Looks only; installs nothing. */
 export function findInstalledChannel(deps) {
-    return CHANNEL_ORDER.find((channel) => channelExecutableCandidates(channel, deps.platform, deps.env).some((p) => deps.exists(p)));
+    return findInstalledBrowser(deps)?.channel;
 }
 const usingChannelLine = (channel) => `[reticle] Playwright's Chromium is not installed; using the installed ${CHANNEL_LABEL[channel]} instead.\n`;
 const installingLine = (command) => `[reticle] No Chromium, Chrome or Edge found; installing Playwright's Chromium (${command}) — a one-time download…\n`;
@@ -98,10 +114,12 @@ export async function resolveChromiumTarget(deps) {
     }
     if (deps.exists(bundled))
         return { found: true };
-    const channel = findInstalledChannel(deps);
-    if (channel !== undefined) {
-        deps.announce(usingChannelLine(channel));
-        return { found: true, channel };
+    const installed = findInstalledBrowser(deps);
+    if (undefined !== installed) {
+        deps.announce(usingChannelLine(installed.channel));
+        return undefined === installed.executablePath
+            ? { found: true, channel: installed.channel }
+            : { found: true, executablePath: installed.executablePath };
     }
     deps.announce(installingLine(chromiumInstallCommand(bundledPlaywrightVersion())));
     const ok = await deps.install();
@@ -207,6 +225,7 @@ const THIS_MACHINE = {
     env: process.env,
     exists: existsSync,
     pathProblem: (path) => chromiumPathProblem(path, process.platform),
+    platform: process.platform,
 };
 /**
  * The lease preflight's probe: "can a launch succeed?", which now includes the Chrome/Edge fallback
@@ -217,16 +236,29 @@ export async function probeLaunchableChromium(machine = THIS_MACHINE) {
     const configured = configuredChromiumProbe(machine.env, machine.pathProblem);
     if (configured !== undefined)
         return configured;
+    const platform = machine.platform ?? process.platform;
     try {
         const { chromium } = await import('playwright');
-        const target = await resolveChromiumTarget(defaultDeps(chromium));
+        const target = await resolveChromiumTarget({
+            ...defaultDeps(chromium),
+            exists: machine.exists,
+            pathProblem: machine.pathProblem,
+            platform,
+            env: machine.env,
+            ...(machine === THIS_MACHINE
+                ? {}
+                : {
+                    install: () => Promise.resolve(false),
+                    announce: () => { },
+                }),
+        });
         if (target.found)
             return { exists: true };
     }
     catch {
-        // No playwright at all — probeChromium below says so, with where it looked.
+        // No playwright at all — probeChromiumWithFallback below says so, with where it looked.
     }
-    return probeChromium();
+    return probeChromiumWithFallback(machine);
 }
 /**
  * `doctor`'s probe: the plain Chromium probe, plus the installed browser that stands in when the
@@ -236,13 +268,18 @@ export async function probeChromiumWithFallback(machine = THIS_MACHINE) {
     const configured = configuredChromiumProbe(machine.env, machine.pathProblem);
     if (configured !== undefined)
         return configured;
-    const probe = await probeChromium();
+    const probe = await probeChromium(machine.exists);
     if (probe.exists)
         return probe;
+    const platform = machine.platform ?? process.platform;
     const channel = findInstalledChannel({
         exists: machine.exists,
-        platform: process.platform,
+        platform,
         env: machine.env,
     });
-    return channel === undefined ? probe : { ...probe, fallback: CHANNEL_LABEL[channel] };
+    if (undefined !== channel) {
+        return { ...probe, fallback: CHANNEL_LABEL[channel] };
+    }
+    const fallbackPaths = CHANNEL_ORDER.flatMap((ch) => channelExecutableCandidates(ch, platform, machine.env));
+    return 0 === fallbackPaths.length ? probe : { ...probe, fallbackPaths };
 }

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/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/drive-error.d.ts

@@ -0,0 +1,6 @@
+import type { DriveErrorCode } from '@reticlehq/core';
+/** Structured, code-tagged failure so callers branch on cause, not message text. */
+export declare class DriveError extends Error {
+    readonly code: DriveErrorCode;
+    constructor(code: DriveErrorCode, message: string);
+}

package/dist/portal/input/drive-error.js

@@ -0,0 +1,9 @@
+/** Structured, code-tagged failure so callers branch on cause, not message text. */
+export class DriveError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DriveError';
+    }
+}

package/dist/portal/input/network-mock.js

@@ -47,10 +47,11 @@ export function matchMock(rules, req) {
 export async function applyOutcome(route, outcome, sleep) {
     if ('continue' === outcome.kind) {
         // Sleep FIRST, then let it through: the delay is the whole perturbation, and the response that
-        // comes back is the server's own.
+        // comes back is the server's own. Fallback, not continue: a lease's context route (the CSP
+        // widening, #2016) must still see the request.
         if (outcome.delayMs !== undefined && outcome.delayMs > 0)
             await sleep(outcome.delayMs);
-        await route.continue();
+        await route.fallback();
         return;
     }
     if ('abort' === outcome.kind) {

package/dist/portal/input/real-input-press.d.ts

@@ -0,0 +1,34 @@
+import type { Page } from 'playwright';
+import { InputModeReason } from '@reticlehq/core';
+import type { RealInputArgs } from './real-input.js';
+type SleepFn = (ms: number) => Promise<void>;
+/**
+ * Drive a `press` with a real keyboard — coordinate-free; the key goes to whatever holds focus.
+ * Key and modifiers come from the same core helpers the synthetic dispatcher uses, so the two paths
+ * cannot read the same args differently.
+ *
+ * A `holdMs` splits the chord into down / wait / up, the same shape the page uses for a held key.
+ * `keyboard.press` would send it instantly instead, reporting a hold-to-confirm that never held.
+ * The one thing this cannot reproduce is the auto-repeat a held key emits: the driver sends a single
+ * keydown, where the in-page path sends the repeats a browser would. Named rather than papered over
+ * — an app that counts repeats needs the synthetic path, and a caller that sees a held key do
+ * nothing now has a reason to try it.
+ */
+export declare function pressViaKeyboard(page: Page, args: RealInputArgs, sleep: SleepFn, now: () => number): Promise<number>;
+/**
+ * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
+ *
+ * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
+ * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
+ * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
+ * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
+ * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
+ * routed to the synthetic path by the caller, which reports the reason rather than pretending a
+ * different gesture happened.
+ *
+ * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
+ * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
+ * should name that, not the generic "you passed a ref".
+ */
+export declare function unspellablePressReason(ref: string, args: Record<string, unknown>): InputModeReason | undefined;
+export {};