@reticlehq/server 3.1.0 → 3.3.0

package/dist/memory/project/learned-routes.js

@@ -26,20 +26,35 @@ export function routesFromEvents(events) {
         return route === undefined ? [] : [route];
     });
 }
-/** Persist initial and subsequent routes for existing and future browser sessions. */
-export function attachRouteLearning(bridge, project) {
+/**
+ * Persist initial and subsequent routes for existing and future browser sessions.
+ *
+ * `storeFor` resolves the store for ONE session's artifact root, rather than the daemon being handed
+ * a single store bound to its own `process.cwd()`. That binding was right only when the daemon
+ * happened to be started inside the app it was driving — and a user-scoped MCP registration, the
+ * common case, starts it wherever the editor's cwd is. The routes of every app then landed in that
+ * directory, which is how a `.reticle/` kept reappearing in a backend nobody had instrumented,
+ * while the driven project's own memory never filled.
+ */
+export function attachRouteLearning(bridge, storeFor) {
     const attached = new WeakSet();
-    const pending = new Set();
+    // Keyed by STORE rather than by root path: `storeFor` already answers one store per root, so this
+    // cannot disagree with it about which roots are distinct.
+    const pending = new Map();
     let flushTimer;
     const flush = () => {
         flushTimer = undefined;
-        const routes = [...pending];
+        const batches = [...pending];
         pending.clear();
-        if (routes.length > 0)
-            void project.recordRoutes(routes).catch(() => undefined);
+        for (const [store, routes] of batches) {
+            if (routes.size > 0)
+                void store.recordRoutes([...routes]).catch(() => undefined);
+        }
     };
-    const queue = (route) => {
-        pending.add(route);
+    const queue = (store, route) => {
+        const routes = pending.get(store) ?? new Set();
+        routes.add(route);
+        pending.set(store, routes);
         if (flushTimer !== undefined)
             clearTimeout(flushTimer);
         flushTimer = setTimeout(flush, ROUTE_PERSIST_DEBOUNCE_MS);
@@ -48,13 +63,14 @@ export function attachRouteLearning(bridge, project) {
         if (attached.has(session))
             return;
         attached.add(session);
+        const store = storeFor(session.artifactRoot);
         const initial = routeFromUrl(session.url);
         if (initial !== undefined)
-            queue(initial);
+            queue(store, initial);
         session.onEvent((event) => {
             const route = routeFromEvent(event);
             if (route !== undefined)
-                queue(route);
+                queue(store, route);
         });
     };
     for (const session of bridge.sessions.all())

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

@@ -0,0 +1,30 @@
+/**
+ * The project memory store for ONE artifact root.
+ *
+ * `deps.project` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started inside the app it is driving — and a user-scoped MCP
+ * registration, the common case, starts it wherever the editor's cwd is. So every run record, every
+ * learned route and every observability high-water mark was written into that directory: a
+ * `.reticle/` appearing in a backend nobody instrumented, and a driven project whose own memory
+ * stayed empty. The cloud half of `recordReplayRun` had already been moved onto the session's root
+ * and its local half left behind, which is how a replay outcome could reach the dashboard and not
+ * the project it belonged to.
+ *
+ * Reads and writes both go through here, deliberately: a write that resolves to the app while a
+ * read still answers from the daemon's directory is worse than either alone — the record lands and
+ * is then invisible to the tool that exists to report it.
+ *
+ * Rebinding is cheap (a filesystem port, a root and a clock) and the single-project case allocates
+ * nothing: when the resolved root IS the daemon's, `deps.project` comes back unchanged.
+ */
+import { ProjectStore } from './project-store.js';
+import type { FileSystemPort } from './fs/fs-port.js';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+export declare function projectForRoot(deps: ToolDeps, root: string): ProjectStore;
+/**
+ * The same question asked by the daemon rather than by a tool: one store per artifact root, so a
+ * session's learned routes land in the app that was driven and not in whatever directory the daemon
+ * was launched from. The daemon's own store is seeded in, so the single-project case allocates
+ * nothing and keeps the instance every other caller already holds.
+ */
+export declare function projectStoreResolver(fs: FileSystemPort, daemonStore: ProjectStore, daemonRoot: string, now: () => number): (root: string | undefined) => ProjectStore;

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

@@ -0,0 +1,43 @@
+/**
+ * The project memory store for ONE artifact root.
+ *
+ * `deps.project` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started inside the app it is driving — and a user-scoped MCP
+ * registration, the common case, starts it wherever the editor's cwd is. So every run record, every
+ * learned route and every observability high-water mark was written into that directory: a
+ * `.reticle/` appearing in a backend nobody instrumented, and a driven project whose own memory
+ * stayed empty. The cloud half of `recordReplayRun` had already been moved onto the session's root
+ * and its local half left behind, which is how a replay outcome could reach the dashboard and not
+ * the project it belonged to.
+ *
+ * Reads and writes both go through here, deliberately: a write that resolves to the app while a
+ * read still answers from the daemon's directory is worse than either alone — the record lands and
+ * is then invisible to the tool that exists to report it.
+ *
+ * Rebinding is cheap (a filesystem port, a root and a clock) and the single-project case allocates
+ * nothing: when the resolved root IS the daemon's, `deps.project` comes back unchanged.
+ */
+import { ProjectStore } from './project-store.js';
+export function projectForRoot(deps, root) {
+    if (root === deps.reticleRoot)
+        return deps.project;
+    return new ProjectStore(deps.fs, root, { now: deps.now });
+}
+/**
+ * The same question asked by the daemon rather than by a tool: one store per artifact root, so a
+ * session's learned routes land in the app that was driven and not in whatever directory the daemon
+ * was launched from. The daemon's own store is seeded in, so the single-project case allocates
+ * nothing and keeps the instance every other caller already holds.
+ */
+export function projectStoreResolver(fs, daemonStore, daemonRoot, now) {
+    const byRoot = new Map([[daemonRoot, daemonStore]]);
+    return (root) => {
+        const key = root ?? daemonRoot;
+        let found = byRoot.get(key);
+        if (found === undefined) {
+            found = new ProjectStore(fs, key, { now });
+            byRoot.set(key, found);
+        }
+        return found;
+    };
+}

package/dist/memory/project/project-tools.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { sessionRoot } from './session-root.js';
+import { projectForRoot } from './project-for-root.js';
 import { ProjectReadError, RunStatus } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { countSchema } from '../../surface/tools/args/numeric-bounds.js';
@@ -67,9 +69,11 @@ function lastTwoFor(runs, name) {
  * The per-flow diff between the two most-recent verification ARTIFACTS (.reticle/runs), or undefined when
  * fewer than two exist. Never throws — a missing/unreadable artifact must not break reading run history.
  */
-async function lastTwoRunArtifacts(deps) {
+async function lastTwoRunArtifacts(deps, 
+/** The session's root — the same address `persistAndSyncVerificationRun` wrote the pair to. */
+root) {
     try {
-        const pair = await new RunStore(deps.fs, deps.reticleRoot).latestTwo();
+        const pair = await new RunStore(deps.fs, root).latestTwo();
         return pair === undefined ? undefined : diffVerificationRuns(pair[0], pair[1]);
     }
     catch {
@@ -106,7 +110,8 @@ export const PROJECT_TOOLS = [
         handler: async (deps, args) => {
             const cloud = await cloudRegression(deps, asString(args['sessionId']));
             const withCloud = (obj) => cloud === undefined ? obj : { ...obj, cloud };
-            const read = await deps.project.read();
+            const project = projectForRoot(deps, sessionRoot(deps, asString(args['sessionId'])));
+            const read = await project.read();
             if (!read.ok) {
                 return withCloud({
                     error: read.reason === ProjectReadError.MISSING
@@ -133,14 +138,14 @@ export const PROJECT_TOOLS = [
                     learned: read.file.learned,
                 });
             }
-            const lastRun = await deps.project.lastRun(name);
+            const lastRun = await project.lastRun(name);
             const pair = lastTwoFor(read.file.runs, name);
             //: the RICH run diff (per-flow duration deltas past a noise floor, status changes, new/removed
             // flows, verdict change) over the last two verification ARTIFACTS. That lives alongside — not
             // instead of — the lightweight RunRecord diff above: `diff` answers "did this named run behave like
             // last time?" from project.json, while `runDiff` answers "what changed between the last two full
             // verification runs?" from .reticle/runs. Best-effort: no artifacts simply means no runDiff.
-            const runDiff = await lastTwoRunArtifacts(deps);
+            const runDiff = await lastTwoRunArtifacts(deps, sessionRoot(deps, asString(args['sessionId'])));
             const forName = read.file.runs.filter((r) => r.name === name);
             return withCloud({
                 runs: recent(forName),

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

@@ -1,3 +1,4 @@
+import type { ProjectId } from '@reticlehq/core';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 /**
  * The `.reticle` directory a tool call's artifacts belong in.
@@ -9,15 +10,43 @@ import type { ToolDeps } from '../../surface/tools/tool-kit.js';
  * fixed — the flow would save successfully and then be invisible to the tool that exists to replay
  * it, which reads as "no flows covered this change" rather than as an error.
  *
- * Falls back to `deps.reticleRoot` whenever resolution cannot name a project, which is exactly the
- * behaviour every call site had before the resolver existed.
+ * Falls back to `deps.reticleRoot` whenever resolution cannot name a project — EXCEPT when the
+ * caller named a session that resolves to nothing, which is the one case where the fallback is a
+ * wrong answer rather than a cautious one. See `sessionProjectId`.
  */
 export declare function sessionRoot(deps: ToolDeps, sessionId: string | undefined): string;
+/**
+ * The same answer for a caller that already holds the projectId rather than a sessionId.
+ *
+ * The suite paths resolve the project ONCE and thread it down -- the run artifact, the cloud link,
+ * the flake ledger and the flows all belong to that one project -- so asking them to go back to the
+ * session manager for an id they already have is how a caller ends up taking the root from one
+ * place and the id from another. `sessionRoot` is now this function plus a lookup, so the two
+ * cannot disagree about what a resolved root is.
+ */
+export declare function rootForProjectId(deps: ToolDeps, projectId: ProjectId | undefined): string;
+/**
+ * The PROJECT directory -- one level above `.reticle` -- for a caller that runs a tool in a tree
+ * rather than writing a file into one. `git diff` is the case: it was being run in the daemon's
+ * `.reticle` subdirectory, which answers about the wrong repository (or, from a globally-registered
+ * daemon at `/` or `$HOME`, about none) while reporting a clean "nothing changed".
+ */
+export declare function projectDirFor(deps: ToolDeps, sessionId: string | undefined): string;
 /**
  * The connected session's projectId, or undefined when there is no session to ask.
  *
- * `sessions.resolve` throws when nothing is connected, when the id names no session, and when
- * several are connected and none was named. All three mean the same thing here — we cannot tell
- * which project this call is about — and none of them is a reason to fail the caller's tool.
+ * `sessions.resolve` throws for three reasons, and they do not all mean the same thing. Nothing
+ * connected, and several connected with none named, both mean "we cannot tell which project this
+ * call is about" — on a call that named no session that is not a reason to fail the caller's tool,
+ * which may not need a session at all, so it degrades to the daemon's own root.
+ *
+ * A sessionId that names NO session is the third, and it is a different fact. An agent that passes
+ * an id has named the project too, so swallowing that throw does not degrade to a cautious answer:
+ * it silently retargets the call at whichever checkout the daemon was started in (#994).
+ * The same fallback can expose another project's ledger on reads as well as misdirect writes.
+ *
+ * So the ambiguous case still declines (the resolver has its own `AMBIGUOUS` branch for the same
+ * reason) and the mis-addressed case refuses. There is no root that is right for a dead id, so
+ * there is no answer either.
  */
-export declare function sessionProjectId(deps: ToolDeps, sessionId: string | undefined): string | undefined;
+export declare function sessionProjectId(deps: ToolDeps, sessionId: string | undefined): ProjectId | undefined;

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

@@ -1,3 +1,4 @@
+import { dirname } from 'node:path';
 /**
  * The `.reticle` directory a tool call's artifacts belong in.
  *
@@ -8,18 +9,62 @@
  * fixed — the flow would save successfully and then be invisible to the tool that exists to replay
  * it, which reads as "no flows covered this change" rather than as an error.
  *
- * Falls back to `deps.reticleRoot` whenever resolution cannot name a project, which is exactly the
- * behaviour every call site had before the resolver existed.
+ * Falls back to `deps.reticleRoot` whenever resolution cannot name a project — EXCEPT when the
+ * caller named a session that resolves to nothing, which is the one case where the fallback is a
+ * wrong answer rather than a cautious one. See `sessionProjectId`.
  */
 export function sessionRoot(deps, sessionId) {
-    return deps.artifactRootFor?.(sessionProjectId(deps, sessionId)).root ?? deps.reticleRoot;
+    // Skip the LOOKUP, never the refusal.
+    //
+    // `artifactRootFor?.(…)` short-circuits its own argument, so an unwired caller used to skip
+    // resolution entirely and hand a named-but-dead session the daemon's own directory without ever
+    // checking the id -- which is how one app's intents, flows and runs land in another app's
+    // checkout. Resolving as an ARGUMENT fixes that, because arguments are evaluated first.
+    //
+    // But `resolve(undefined)` is not free: it builds the ranked no-session diagnosis and records
+    // which branch it took. With no resolver wired AND no id named there is nothing to refuse and
+    // nothing its answer could change, so that one case skips the lookup and costs what it always
+    // did. Every embedder of this engine, and every older construction of ToolDeps, is on it.
+    const nothingToRefuse = deps.artifactRootFor === undefined && sessionId === undefined;
+    return rootForProjectId(deps, nothingToRefuse ? undefined : sessionProjectId(deps, sessionId));
+}
+/**
+ * The same answer for a caller that already holds the projectId rather than a sessionId.
+ *
+ * The suite paths resolve the project ONCE and thread it down -- the run artifact, the cloud link,
+ * the flake ledger and the flows all belong to that one project -- so asking them to go back to the
+ * session manager for an id they already have is how a caller ends up taking the root from one
+ * place and the id from another. `sessionRoot` is now this function plus a lookup, so the two
+ * cannot disagree about what a resolved root is.
+ */
+export function rootForProjectId(deps, projectId) {
+    return deps.artifactRootFor?.(projectId).root ?? deps.reticleRoot;
+}
+/**
+ * The PROJECT directory -- one level above `.reticle` -- for a caller that runs a tool in a tree
+ * rather than writing a file into one. `git diff` is the case: it was being run in the daemon's
+ * `.reticle` subdirectory, which answers about the wrong repository (or, from a globally-registered
+ * daemon at `/` or `$HOME`, about none) while reporting a clean "nothing changed".
+ */
+export function projectDirFor(deps, sessionId) {
+    return dirname(sessionRoot(deps, sessionId));
 }
 /**
  * The connected session's projectId, or undefined when there is no session to ask.
  *
- * `sessions.resolve` throws when nothing is connected, when the id names no session, and when
- * several are connected and none was named. All three mean the same thing here — we cannot tell
- * which project this call is about — and none of them is a reason to fail the caller's tool.
+ * `sessions.resolve` throws for three reasons, and they do not all mean the same thing. Nothing
+ * connected, and several connected with none named, both mean "we cannot tell which project this
+ * call is about" — on a call that named no session that is not a reason to fail the caller's tool,
+ * which may not need a session at all, so it degrades to the daemon's own root.
+ *
+ * A sessionId that names NO session is the third, and it is a different fact. An agent that passes
+ * an id has named the project too, so swallowing that throw does not degrade to a cautious answer:
+ * it silently retargets the call at whichever checkout the daemon was started in (#994).
+ * The same fallback can expose another project's ledger on reads as well as misdirect writes.
+ *
+ * So the ambiguous case still declines (the resolver has its own `AMBIGUOUS` branch for the same
+ * reason) and the mis-addressed case refuses. There is no root that is right for a dead id, so
+ * there is no answer either.
  */
 /*
  * Exported alongside `sessionRoot`, and that is the point rather than a convenience. A caller that
@@ -32,7 +77,24 @@ export function sessionProjectId(deps, sessionId) {
     try {
         return deps.sessions.resolve(sessionId).projectId;
     }
-    catch {
-        return undefined;
+    catch (cause) {
+        if (sessionId === undefined)
+            return undefined;
+        throw unresolvedTargetRefusal(sessionId, cause);
     }
 }
+/**
+ * Why a named-but-dead session gets no directory, and what to do instead.
+ *
+ * The manager's own message is carried verbatim at the end because it is the actionable half — it
+ * names the sessions that ARE connected, with their ids and urls, or says that none are. Rebuilding
+ * a worse version of that here is how the two no-session paths drifted apart the last time.
+ */
+function unresolvedTargetRefusal(sessionId, cause) {
+    const because = cause instanceof Error ? cause.message : String(cause);
+    return new Error(`sessionId '${sessionId}' names no session, so there is no project to resolve this call's ` +
+        '.reticle directory against, and nothing was read or written. Reticle refuses rather than ' +
+        "falling back to the daemon's own directory, which belongs to whatever project the daemon " +
+        "was started in — that is how one app's intents, flows and runs land in another app's " +
+        `checkout. Omit sessionId to use the connected app, or name one that is live. ${because}`);
+}

package/dist/memory/recall/prior/connection-memory.d.ts

@@ -63,3 +63,9 @@ export declare function hasAnyAppConnectedBefore(stateDir: string, port: number,
  * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
  */
 export declare function hasProjectConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;
+/**
+ * Has any of these projects connected before: the first-move question for a directory that speaks
+ * for more than one app (a monorepo root), or for none by name (an app wired by the plugin alone).
+ * The ids come from `projectIdsAt`; each is still asked the narrow question.
+ */
+export declare function hasAnyProjectConnectedBefore(stateDir: string, port: number, projectIds: readonly string[]): boolean;

package/dist/memory/recall/prior/connection-memory.js

@@ -112,3 +112,11 @@ export function hasProjectConnectedBefore(stateDir, port, projectId) {
         return false;
     return hasAnyAppConnectedBefore(stateDir, port, projectId);
 }
+/**
+ * Has any of these projects connected before: the first-move question for a directory that speaks
+ * for more than one app (a monorepo root), or for none by name (an app wired by the plugin alone).
+ * The ids come from `projectIdsAt`; each is still asked the narrow question.
+ */
+export function hasAnyProjectConnectedBefore(stateDir, port, projectIds) {
+    return projectIds.some((id) => hasProjectConnectedBefore(stateDir, port, id));
+}

package/dist/memory/recall/registered-projects.d.ts

@@ -1,5 +1,5 @@
 /** One project this machine has paired before, in the shape the no-session facts already carry. */
-export interface RegisteredProject {
+interface RegisteredProject {
     directory: string;
     projectId?: string;
 }
@@ -52,3 +52,4 @@ export declare function isUnscopedRoot(directory: string, home: string): boolean
  * reporting it as such would tell a correctly-scoped daemon to go and look somewhere else.
  */
 export declare function registeredElsewhere(home: string, directory: string): RegisteredProject[];
+export {};

package/dist/portal/bridge/auth-failure-reason.d.ts

@@ -20,4 +20,13 @@
  * With no evidence — a fresh daemon, or a HELLO naming no project — nothing is inferred and the
  * plain reason stands, unless the page sent no token.
  */
+/**
+ * Whether a recorded close is a pairing-token refusal.
+ *
+ * The bridge records the specific sentence it sent on the socket, not one fixed string, so a
+ * comparison with a single constant misses a wrong token, a missing token, and a daemon that
+ * belongs to another project. All three are refusals. A later good session is a separate question
+ * the caller answers with `connectedSinceLastClosure`.
+ */
+export declare function isAuthRefusalReason(reason: string | undefined): boolean;
 export declare function authFailureReason(servedProjects: ReadonlySet<string>, helloProject: string | undefined, helloToken?: string): string;

package/dist/portal/bridge/auth-failure-reason.js

@@ -28,10 +28,27 @@ const PLAIN = 'authentication failed';
  * before `~/.reticle` was replaced. Both need the same first move: ask `status`, which can say which.
  */
 const WRONG_TOKEN = 'authentication failed: wrong pairing token — run `reticle status` for the cause';
-/** A paste-in snippet or a Next config that never saw a token. Reload cannot mint one. */
-const NO_TOKEN = 'authentication failed: no pairing token on the page';
+/**
+ * A paste-in snippet or a Next config that never saw a token. Reload cannot mint one; restarting the
+ * dev server re-runs the substitution that should have put it there (#1047).
+ */
+const NO_TOKEN = 'authentication failed: no pairing token on the page; the build did not substitute it, so restart the dev server';
 /** WebSocket close reasons are capped at 123 bytes; a longer one throws and closes with nothing. */
 const MAX_REASON_BYTES = 123;
+const DIFFERENT_PROJECT_PREFIX = 'this daemon serves a different project';
+/**
+ * Whether a recorded close is a pairing-token refusal.
+ *
+ * The bridge records the specific sentence it sent on the socket, not one fixed string, so a
+ * comparison with a single constant misses a wrong token, a missing token, and a daemon that
+ * belongs to another project. All three are refusals. A later good session is a separate question
+ * the caller answers with `connectedSinceLastClosure`.
+ */
+export function isAuthRefusalReason(reason) {
+    if (reason === undefined)
+        return false;
+    return reason.startsWith('authentication failed') || reason.startsWith(DIFFERENT_PROJECT_PREFIX);
+}
 export function authFailureReason(servedProjects, helloProject, helloToken) {
     // ONE served project, not merely some. A daemon that has accepted sessions from SEVERAL projects
     // is demonstrably not owned by any one of them, so "that daemon is not yours, stop it" is the
@@ -45,7 +62,7 @@ export function authFailureReason(servedProjects, helloProject, helloToken) {
     if (helloProject !== undefined &&
         1 === servedProjects.size &&
         !servedProjects.has(helloProject)) {
-        const reason = `this daemon serves a different project — run \`reticle stop\` and retry`;
+        const reason = `${DIFFERENT_PROJECT_PREFIX} — run \`reticle stop\` and retry`;
         return Buffer.byteLength(reason, 'utf8') <= MAX_REASON_BYTES ? reason : PLAIN;
     }
     if (helloToken === undefined || 0 === helloToken.length)

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

@@ -20,7 +20,7 @@ export declare const WS_CLOSE_REASON: {
      * this stays as the close-code table's label and as the fallback when the skew cannot be read.
      */
     readonly PROTOCOL_MISMATCH: "protocol version mismatch — @reticlehq/browser and server disagree";
-    readonly AUTH_FAILED: "authentication failed — reload the page to pick up the current pairing token";
+    readonly AUTH_FAILED: "authentication failed — restart the dev server; a reload keeps the old pairing token";
     /**
      * The daemon threw while handling a message. Closing is deliberate: an exception leaves the
      * session in a state neither side can describe, and a socket left OPEN and unresponsive is the
@@ -97,6 +97,11 @@ export declare class Bridge {
      * is to make something happen sooner than it already would.
      */
     attachSyncRequest(handler: () => void): void;
+    /**
+     * Register a handler for the panel's harness switch. Optional for the same reason as the above: a
+     * bridge built without one ignores the request rather than refusing it.
+     */
+    attachHarnessRequest(handler: (enabled: boolean) => void): void;
     /** Register a handler to run when a session connects. Additive — every handler runs. */
     attachSessionCreate(handler: (session: Session) => void): void;
     close(): Promise<void>;

package/dist/portal/bridge/bridge.js

@@ -48,7 +48,7 @@ export const WS_CLOSE_REASON = {
      * this stays as the close-code table's label and as the fallback when the skew cannot be read.
      */
     PROTOCOL_MISMATCH: 'protocol version mismatch — @reticlehq/browser and server disagree',
-    AUTH_FAILED: 'authentication failed — reload the page to pick up the current pairing token',
+    AUTH_FAILED: 'authentication failed — restart the dev server; a reload keeps the old pairing token',
     /**
      * The daemon threw while handling a message. Closing is deliberate: an exception leaves the
      * session in a state neither side can describe, and a socket left OPEN and unresponsive is the
@@ -119,6 +119,24 @@ function replayRequest(event) {
     const name = event.data['text'];
     return 'string' === typeof name && name.length > 0 ? name : undefined;
 }
+/**
+ * The desired harness state if this event is the panel's switch, else undefined.
+ *
+ * Carries `on`/`off` rather than meaning "toggle": a double-click on a flaky connection sends two,
+ * and two toggles land back where they started while two `on`s are the same as one.
+ */
+function harnessRequest(event) {
+    if (event.type !== EventType.HUMAN_CONTROL)
+        return undefined;
+    if (event.data['kind'] !== HumanControlKind.HARNESS)
+        return undefined;
+    const want = event.data['text'];
+    if ('on' === want)
+        return true;
+    if ('off' === want)
+        return false;
+    return undefined;
+}
 /** True when this event is the panel's "sync now" button. Pure boundary narrowing, like the above. */
 function isSyncRequest(event) {
     return event.type === EventType.HUMAN_CONTROL && event.data['kind'] === HumanControlKind.SYNC;
@@ -225,6 +243,7 @@ export class Bridge {
     #onSessionEnd;
     /** Wired by the daemon: push to the dashboard now, because somebody asked in the panel. */
     #onSyncRequest;
+    #onHarnessRequest;
     constructor(options) {
         const host = options.host ?? LOOPBACK_HOST;
         if ((options.token?.length ?? 0) > TRANSPORT_LIMITS.MAX_TOKEN_LENGTH) {
@@ -479,7 +498,7 @@ export class Bridge {
                             presented: parsed.token !== undefined && 0 < parsed.token.length,
                             tokenSource: this.#tokenSource,
                         });
-                        this.sessions.noteClosure(WS_CLOSE_REASON.AUTH_FAILED, this.#clock());
+                        this.sessions.noteClosure(reason, this.#clock());
                         socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
                         return;
                     }
@@ -616,6 +635,10 @@ export class Bridge {
                     // A panel ▶ replay needs the daemon's flow store, which the Session can't reach — route it to
                     // the daemon-wired handler instead of the in-session control path. Everything else is normal.
                     const replay = replayRequest(parsed.event);
+                    // Narrowed before the chain, not inside it: the result is needed by the branch AND by the
+                    // test that decides whether this is a panel control at all, and calling it twice would
+                    // invite the two calls to disagree.
+                    const harness = harnessRequest(parsed.event);
                     if (replay !== undefined)
                         this.#onReplay?.(session.id, replay);
                     // Same shape as ▶ replay, and routed the same way: what to push lives in the daemon's
@@ -623,6 +646,10 @@ export class Bridge {
                     // us to hurry, not asking for a result.
                     else if (isSyncRequest(parsed.event))
                         this.#onSyncRequest?.();
+                    // The switch is written through to the platform by the daemon, for the same reason: the
+                    // Session has no cloud credential and should not grow one.
+                    else if (harness !== undefined)
+                        this.#onHarnessRequest?.(harness);
                     // Pass the raw frame's byte length so the buffer doesn't re-serialize every event for accounting.
                     else
                         session.pushEvent(parsed.event, Buffer.byteLength(text, 'utf8'));
@@ -758,6 +785,13 @@ export class Bridge {
     attachSyncRequest(handler) {
         this.#onSyncRequest = handler;
     }
+    /**
+     * Register a handler for the panel's harness switch. Optional for the same reason as the above: a
+     * bridge built without one ignores the request rather than refusing it.
+     */
+    attachHarnessRequest(handler) {
+        this.#onHarnessRequest = handler;
+    }
     /** Register a handler to run when a session connects. Additive — every handler runs. */
     attachSessionCreate(handler) {
         this.#onSessionCreate.push(handler);

package/dist/portal/input/real-input.js

@@ -7,6 +7,7 @@ import { classifyConnectFailure } from '../../telemetry/connect-failure.js';
 import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG } from '@reticlehq/core';
 import { installNetworkMocks } from './network-mock.js';
 import { attachNetworkDetail } from './network-detail.js';
+import { injectedConnectArgs } from '../pool/zero-install.js';
 /** Structured, code-tagged failure so callers branch on cause, not message text. */
 export class DriveError extends Error {
     code;
@@ -338,7 +339,7 @@ export class LaunchedRealInputProvider {
             await page.waitForFunction('!!globalThis.__reticleInstance', {
                 timeout: INJECT_CONNECT_WAIT_MS,
             });
-            const arg = JSON.stringify({ allowNonLocalhost: true, token: opts.token, url: opts.url });
+            const arg = JSON.stringify(injectedConnectArgs(opts));
             await page.evaluate(`globalThis.__reticleInstance.connect(${arg})`);
         }
         catch {

package/dist/portal/pool/browser-pool.d.ts

@@ -18,6 +18,11 @@ export interface Lease {
     readonly url: string;
     readonly navStatus?: number;
     release(): Promise<void>;
+    /**
+     * Hand the page the zero-install reader: evaluated in the live document, and added ahead of every
+     * document this lease loads next. False when there is no reader, or the page cannot run one.
+     */
+    injectReader?(): Promise<boolean>;
 }
 /** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
 export declare const DEFAULT_LEASE_TTL_MS: number;
@@ -32,6 +37,11 @@ interface BrowserPoolOptions {
     leaseTtlMs?: number;
     /** Per-lease navigation timeout — a page that won't load fails its own lease, never blocks a slot. */
     navTimeoutMs?: number;
+    /**
+     * The zero-install reader, built where the daemon knows its own port and pairing token. A thunk so
+     * the ~450KB build is only read if some page ever needs it; undefined when there is none to give.
+     */
+    zeroInstallScript?: () => string | undefined;
 }
 /**
  * Owns a single browser and leases isolated contexts out of it, capped at `maxContexts`.

package/dist/portal/pool/browser-pool.js

@@ -30,6 +30,7 @@ export class BrowserPool {
     #genId;
     #now;
     #ttl;
+    #zeroInstall;
     #navTimeout;
     #browser;
     #launching;
@@ -70,6 +71,7 @@ export class BrowserPool {
         this.#now = opts.now ?? (() => Date.now());
         this.#ttl = opts.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
         this.#navTimeout = opts.navTimeoutMs ?? DEFAULT_NAV_TIMEOUT_MS;
+        this.#zeroInstall = opts.zeroInstallScript;
     }
     /** The TTL configured for leases — how long an untouched lease lives before the reaper reclaims it. */
     leaseTtlMs() {
@@ -405,6 +407,14 @@ export class BrowserPool {
                 url,
                 ...(navStatus !== undefined ? { navStatus } : {}),
                 release: () => this.#release(sessionId),
+                injectReader: async () => {
+                    const script = this.#zeroInstall?.();
+                    if (script === undefined || page.evaluate === undefined)
+                        return false;
+                    await page.addInitScript?.(script);
+                    await page.evaluate(script);
+                    return true;
+                },
             };
         }
         catch (err) {

package/dist/portal/pool/playwright-launcher.js

@@ -41,6 +41,7 @@ function wrapBrowser(browser) {
                     return {
                         goto: (url, opts) => page.goto(url, gotoOptions(opts?.timeoutMs)),
                         close: () => page.close(),
+                        evaluate: (script) => page.evaluate(script),
                         // Playwright returns a Buffer; Uint8Array is what the visual store and differ take.
                         screenshot: async (opts) => new Uint8Array(await page.screenshot({ fullPage: true === opts?.fullPage })),
                         // Three moves, same as performGesture: a single move to the center can be a no-op if

package/dist/portal/pool/pool-contract.d.ts

@@ -34,6 +34,8 @@ export interface PooledPage {
      * reports dispatched/settled while the styles never ran.
      */
     hover?(x: number, y: number): Promise<void>;
+    /** Evaluate a script in the page's current document. OPTIONAL: without it no reader is injected. */
+    evaluate?(script: string): Promise<unknown>;
     /** Add an init script to run after document creation but before any page scripts run. */
     addInitScript?<Arg>(script: ((arg: Arg) => void) | string, arg?: Arg): Promise<InitScriptHandle | void>;
     /**