@reticlehq/server 3.1.0 → 3.2.0

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/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

@@ -32,6 +32,20 @@ const WRONG_TOKEN = 'authentication failed: wrong pairing token — run `reticle
 const NO_TOKEN = 'authentication failed: no pairing token on the page';
 /** 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 +59,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/session/facts/session-replaced.d.ts

@@ -22,3 +22,22 @@ export declare function sessionReplacedReason(id: string, url: string): string;
  * without each one re-deriving a message — an `Error`, a bare string, or something else entirely.
  */
 export declare function isSessionReplacedError(error: unknown): boolean;
+/**
+ * The reason every command still in flight is rejected with when the socket under it closes.
+ *
+ * A full-document navigation closes that socket, so on an MPA — or on any click that loads a new
+ * page — this arrives for the exact command that CAUSED it, and the successor is still connecting.
+ * `SessionManager.remove` cannot tell those two apart at the moment it runs: it is called from the
+ * socket's own close handler, the tombstone it writes is what a successor is later matched against,
+ * and nothing has arrived yet. So the rejection stays a plain transport failure, as
+ * `PendingCommands.rejectAll` documents, and a caller that CAN wait decides what it means.
+ */
+export declare const SESSION_DISCONNECTED_REASON = "session disconnected";
+/**
+ * Is this failure the page's transport going away, rather than an answer from the page?
+ *
+ * True for both shapes the same event takes: the reconnect that claimed the id back, and the close
+ * that landed before any successor did. A caller holding a budget can follow either; a caller that
+ * cannot must say it stopped watching, never that the app failed.
+ */
+export declare function isDocumentGoneError(error: unknown): boolean;

package/dist/portal/session/facts/session-replaced.js

@@ -27,3 +27,25 @@ export function isSessionReplacedError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.includes(SESSION_REPLACED_PREFIX);
 }
+/**
+ * The reason every command still in flight is rejected with when the socket under it closes.
+ *
+ * A full-document navigation closes that socket, so on an MPA — or on any click that loads a new
+ * page — this arrives for the exact command that CAUSED it, and the successor is still connecting.
+ * `SessionManager.remove` cannot tell those two apart at the moment it runs: it is called from the
+ * socket's own close handler, the tombstone it writes is what a successor is later matched against,
+ * and nothing has arrived yet. So the rejection stays a plain transport failure, as
+ * `PendingCommands.rejectAll` documents, and a caller that CAN wait decides what it means.
+ */
+export const SESSION_DISCONNECTED_REASON = 'session disconnected';
+/**
+ * Is this failure the page's transport going away, rather than an answer from the page?
+ *
+ * True for both shapes the same event takes: the reconnect that claimed the id back, and the close
+ * that landed before any successor did. A caller holding a budget can follow either; a caller that
+ * cannot must say it stopped watching, never that the app failed.
+ */
+export function isDocumentGoneError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return isSessionReplacedError(error) || message === SESSION_DISCONNECTED_REASON;
+}

package/dist/portal/session/no-session-diagnosis.d.ts

@@ -165,6 +165,7 @@ export declare const SELF_RECOVERING_MARKER = "Then call reticle_sessions again
 export declare function explainNoSession(facts: NoSessionFacts): {
     reason: NoSessionReason;
     message: string;
+    detail?: string;
 };
 /**
  * The message alone, for the callers that render it.