@reticlehq/server 3.7.0 → 3.8.1

package/dist/portal/session/session.js

@@ -1,3 +1,4 @@
+import { noteOwnReload, notePageLoaded } from '../../features/harness/drive-runs.js';
 import { asProjectId } from '@reticlehq/core';
 import { narrationArgs } from './narration-args.js';
 import { refusedResult } from './page-commands/undeclared-command.js';
@@ -15,7 +16,7 @@ const IMPACT_PUSH_DEBOUNCE_MS = 700;
 import { PendingCommands, CommandTimeoutError } from './page-commands/pending-commands.js';
 import { span } from '../../trace.js';
 import { keepCallerContextInDaemon, noteToDaemonLog } from './daemon-answers.js';
-import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, HudUseDataSchema, ReticleCommand, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LEASE, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
+import { isKnownRealm, EventType, HumanControlDataSchema, HumanControlKind, HumanMarkDataSchema, HudUseDataSchema, ReticleCommand, parseEventPayload, PresenterTone, SESSION_HEALTH, SESSION_LIFECYCLE, SessionState, } from '@reticlehq/core';
 import { RingBuffer } from '@reticlehq/engine/window/ring-buffer.js';
 import { readJournalWriteLoss, readQueryEvents, windowLost, } from '../../memory/journal/journal-query.js';
 import {} from '@reticlehq/engine/window/ambient.js';
@@ -28,6 +29,7 @@ import { ReviewStore } from './human/review-store.js';
 import { buildSessionRecommendation } from './presence/session-recommendation.js';
 import { buildPresenterArgs } from './human/presenter-args.js';
 import { buildSessionLease } from './presence/session-lease.js';
+import { sessionAgeWarning } from './presence/session-lease.js';
 import { buildSessionInfo } from './session-info.js';
 import { notedAct, probeMarkers, withInstrumentation } from './recorded-gaps.js';
 import { MAX_SUCCESSOR_HOPS, REBINDABLE_COMMANDS } from './rebind.js';
@@ -56,31 +58,36 @@ export class Session {
      * MINTED HERE. This is one of the two places a projectId enters the daemon with its provenance
      * intact: the field is `projectId` on a zod-parsed HELLO, so the page said what it is. Every
      * downstream reader takes the brand from this property rather than re-blessing a string.
+     * Set once more, by `adoptProject`, when a page that said nothing names its project later.
      */
     projectId;
+    /** Take a later HELLO's project id when the first carried none. A set project is kept. */
+    adoptProject(projectId) {
+        if (this.projectId !== undefined)
+            return false;
+        this.projectId = asProjectId(projectId);
+        return true;
+    }
     /**
      * The `.reticle` directory this session's evidence belongs in — impact counters AND capsules.
      * Stamped once, from the project it declared in HELLO, so every counter agrees where it goes.
      * Undefined when nothing could name a project: callers fall back to the daemon's own root.
      */
     artifactRoot;
-    /**
-     * Same-origin endpoints this session's project declared as background (`.reticle.json`
-     * `background`). Stamped with `artifactRoot`, from the same project. Empty excludes nothing.
-     */
+    /** Same-origin `background` endpoints of this session's project, stamped with `artifactRoot`. */
     background = [];
     url;
     title;
     adapters;
     hasCapabilities;
-    // What the page said about itself at HELLO. `HandshakeFacts` holds the reasoning, including
-    // the rule that `undefined` means "too old to say" and never "no".
+    // What the page said at HELLO. `HandshakeFacts` holds the reasoning (`undefined` is never "no").
     versionSkew;
     sdkVersion;
     captureBodies;
     channels;
     commands;
     sourceMapping;
+    instrumentation;
     redactKeys;
     #socket;
     #clock;
@@ -134,6 +141,8 @@ export class Session {
      */
     #editEpoch;
     #departureNote = new DepartureNote();
+    /** Set when a production nonce opened this session: every act then passes the production policy. */
+    production;
     constructor(hello, socket, clock) {
         this.id = hello.sessionId;
         this.projectId = hello.projectId === undefined ? undefined : asProjectId(hello.projectId);
@@ -142,6 +151,7 @@ export class Session {
         this.adapters = hello.adapters;
         this.hasCapabilities = hello.hasCapabilities ?? false;
         this.sourceMapping = hello.sourceMapping;
+        this.instrumentation = hello.instrumentation;
         this.redactKeys = hello.redactKeys ?? [];
         this.#socket = socket;
         this.#clock = clock;
@@ -233,6 +243,7 @@ export class Session {
             hasCapabilities: this.hasCapabilities,
             runtime: this.#runtime,
             versionSkew: this.versionSkew,
+            sdkVersion: this.sdkVersion,
             hidden: this.#hidden,
             page: this.page,
             health: () => this.health(),
@@ -288,6 +299,7 @@ export class Session {
         }
         if (event.documentId !== undefined)
             this.#documentId = event.documentId;
+        notePageLoaded(this.id, event, this.#clock());
         if (event.editEpoch !== undefined)
             this.#editEpoch = event.editEpoch;
         if (event.type === EventType.PAGE_HEALTH) {
@@ -555,15 +567,19 @@ export class Session {
     }
     /** Send a command to the browser and await its reply (or time out). */
     command(name, args = {}, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
-        // Recorded HERE rather than at the tool call sites: this is the one place every driven action
-        // passes through, so act_sequence and flow replay count too. Doing it per-tool missed both, and
-        // an under-counted "exercised" reports worse coverage than reality — the safe direction, but
-        // still wrong, and it made the number depend on which tool the agent happened to use.
-        if (name === ReticleCommand.ACT) {
-            const ref = args['ref'];
-            if ('string' === typeof ref)
-                this.recordActedRef(ref);
-        }
+        // The production policy decides here, where every driven action passes, and never in the page.
+        if (this.production === undefined)
+            return this.#dispatch(name, args, timeoutMs);
+        return this.production.gate(name, args, (n, a) => this.#dispatch(n, a, timeoutMs));
+    }
+    #dispatch(name, args, ms) {
+        // Recorded here, where every driven action passes (act_sequence and flow replay too). A reload
+        // sent from here is ours, so the page coming back is not a person reloading mid-drive.
+        const ref = args['ref'];
+        if (name === ReticleCommand.ACT && 'string' === typeof ref)
+            this.recordActedRef(ref);
+        if (name === ReticleCommand.REFRESH)
+            noteOwnReload(this.id, this.#clock());
         // Refused before it is sent, when the page said it does not serve this. The rule, and why
         // an absent declaration is not an empty list, live in `undeclared-command.ts`.
         const refused = refusedResult(name, this.commands, `${COMMAND_ID_PREFIX}refused`);
@@ -574,12 +590,12 @@ export class Session {
         // have made itself after a `reticle_sessions` round trip, minus the round trip.
         const successor = this.#liveSuccessor();
         if (successor !== undefined)
-            return successor.command(name, args, timeoutMs);
+            return successor.command(name, args, ms);
         const id = this.#pending.nextId(COMMAND_ID_PREFIX);
         const payload = commandPayload(id, this.id, name, args);
         // The timeout message is built LAZILY: health can change while a command is in flight, and the
         // diagnosis should describe the page as it was when the command actually gave up.
-        const awaited = this.#pending.track(id, timeoutMs, () => commandTimeoutMessage(name, timeoutMs, {
+        const awaited = this.#pending.track(id, ms, () => commandTimeoutMessage(name, ms, {
             url: this.url,
             hidden: this.#hidden,
             lastSeenMs: this.lastSeenMs(),
@@ -617,7 +633,7 @@ export class Session {
             // timeout means a caller who granted 8s can wait 16, and across a chain of replacements the
             // total is unbounded — a wait nobody asked for, on the path that exists to save a round trip.
             // A budget already spent means there is nothing left to retry into, so the error stands.
-            const remaining = timeoutMs - (Date.now() - sentAt);
+            const remaining = ms - (Date.now() - sentAt);
             if (remaining <= 0)
                 throw error;
             return next.command(name, args, remaining);
@@ -806,17 +822,9 @@ export class Session {
         this.#firstCommandDone = true;
         return buildSessionLease(this.id, this.#startedAt);
     }
-    /**
-     * Returns a human-readable age warning after SESSION_LEASE.WARN_AFTER_MS (10 min), else undefined.
-     * Spliced onto every session-bound tool result so the agent is passively reminded to clean up
-     * without needing an explicit polling loop.
-     */
+    /** The age reminder spliced onto session-bound results, so the agent cleans up without polling. */
     ageWarning() {
-        const ageMs = this.#clock() - this.#startedAt;
-        if (ageMs < SESSION_LEASE.WARN_AFTER_MS)
-            return undefined;
-        const minutes = Math.floor(ageMs / 60_000);
-        return `Session ${this.id} has been open for ${String(minutes)} minutes. If your task is complete, call reticle_session{action:"end"} now.`;
+        return sessionAgeWarning(this.id, this.#clock() - this.#startedAt);
     }
     /**
      * The tabs that should SEE what this session is told, supplied by the SessionManager.

package/dist/portal/session/zero-install-first-call.d.ts

@@ -16,16 +16,21 @@ export interface FirstCallOpened {
     /** One line for the agent: what was opened, what it cannot see, and how to wire it for good. */
     notice: string;
 }
+/** Compared both as written and with links resolved: either spelling may be the one lsof used. */
+export declare function within(child: string | undefined, parent: string): boolean;
+/** The caller's running app, for a lease that names no url. */
+export declare function projectAppUrlFinder(io: Pick<FirstCallIo, 'project' | 'serving' | 'servingDirectory'>): () => Promise<string | undefined>;
 /** One lease per project for the daemon's life: a failure is reported once, never retried. */
 export declare function firstCallOpener(io: FirstCallIo): () => Promise<FirstCallOpened | undefined>;
 /**
  * The daemon's two answers to an app nobody wired, built together because both ask the same
- * question first — which unwired web app is this caller in. `firstRun` wires it when the agent
+ * question first — which unwired web app is this caller in. `firstRun` names it when the agent
  * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call.
  */
-export declare function agentWiring(port: number, sessions: {
+export declare function agentWiring(sessions: {
     list(): readonly unknown[];
 }, lease: (url: string) => Promise<unknown>): {
     firstRun: FirstRunWiring;
     openUnwiredApp: () => Promise<FirstCallOpened | undefined>;
+    projectAppUrl: () => Promise<string | undefined>;
 };

package/dist/portal/session/zero-install-first-call.js

@@ -11,8 +11,9 @@
  * browser opened on another repo's app produces a confident verdict about code nobody touched. It
  * changes nothing in the repo — wiring it for good stays the agent's call, named in the notice.
  *
- * Where the serving process cannot be observed (no `lsof`, so Windows) nothing is opened and the
- * no-session answer names the lease and the init command instead.
+ * Where the serving process cannot be observed nothing is opened, and the no-session answer names
+ * the lease and the init command instead. On Windows the lookup reads the listener's command line
+ * (see `findListenerCwd`), so a dev server run from the project's `node_modules` counts.
  */
 import { realpathSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
@@ -21,6 +22,7 @@ import { callingClientDirectory } from '../../hooks/client-directory.js';
 import { detectDevCommandInProject, initCommandIn } from './dev-server/dev-command.js';
 import { probeDevServerStates } from './dev-server/dev-server-probe.js';
 import { firstRunWiring } from './first-run-wiring.js';
+import { wiringConsent } from './no-session-next-action.js';
 import { servingDirectoryOf } from './serving-directory.js';
 const LOCALHOST = 'http://localhost';
 /** The path with symlinks resolved when it exists (lsof reports `/private/tmp`, callers `/tmp`). */
@@ -34,7 +36,7 @@ function real(path) {
 }
 const inside = (c, p) => c === p || c.startsWith(`${p}${sep}`);
 /** Compared both as written and with links resolved: either spelling may be the one lsof used. */
-function within(child, parent) {
+export function within(child, parent) {
     if (child === undefined)
         return false;
     return inside(resolve(child), resolve(parent)) || inside(real(child), real(parent));
@@ -42,8 +44,30 @@ function within(child, parent) {
 function openedNotice(url, init) {
     return (`This app is not wired for Reticle, so Reticle opened ${url} in its own browser and supplied ` +
         'the SDK (zero-install: DOM, network, console and routes; no component state and no source ' +
-        `file:line). To wire it for good, run \`${init}\`, then ` +
-        'restart the dev server and reload the page.');
+        `file:line). To wire it for good: ${wiringConsent(init)} Then restart the dev server and ` +
+        'reload the page.');
+}
+/**
+ * The one dev server that runs in this project's folder, or undefined when there is none or more
+ * than one. Two servers in one project is a choice the caller makes, not one Reticle guesses.
+ */
+async function projectAppUrlIn(io, dir) {
+    const pinned = detectDevCommandInProject(dir)?.port;
+    const candidates = new Set(DEV_SERVER_PORTS);
+    if (pinned !== undefined) {
+        candidates.add(pinned);
+    }
+    const own = (await io.serving([...candidates]))
+        .map((port) => `${LOCALHOST}:${String(port)}`)
+        .filter((url) => within(io.servingDirectory(url), dir));
+    return 1 === own.length ? own[0] : undefined;
+}
+/** The caller's running app, for a lease that names no url. */
+export function projectAppUrlFinder(io) {
+    return async () => {
+        const dir = io.project();
+        return dir === undefined ? undefined : projectAppUrlIn(io, dir);
+    };
 }
 /** One lease per project for the daemon's life: a failure is reported once, never retried. */
 export function firstCallOpener(io) {
@@ -52,16 +76,9 @@ export function firstCallOpener(io) {
         const dir = io.project();
         if (dir === undefined || tried.has(dir))
             return undefined;
-        const pinned = detectDevCommandInProject(dir)?.port;
-        const candidates = new Set(DEV_SERVER_PORTS);
-        if (pinned !== undefined)
-            candidates.add(pinned);
-        const own = (await io.serving([...candidates]))
-            .map((port) => `${LOCALHOST}:${String(port)}`)
-            .filter((url) => within(io.servingDirectory(url), dir));
-        const [url] = own;
+        const url = await projectAppUrlIn(io, dir);
         // ponytail: nothing serving yet is not an attempt, so a later call looks again.
-        if (url === undefined || 1 !== own.length)
+        if (url === undefined)
             return undefined;
         tried.add(dir);
         await io.lease(url).catch(() => undefined);
@@ -72,17 +89,23 @@ export function firstCallOpener(io) {
 }
 /**
  * The daemon's two answers to an app nobody wired, built together because both ask the same
- * question first — which unwired web app is this caller in. `firstRun` wires it when the agent
+ * question first — which unwired web app is this caller in. `firstRun` names it when the agent
  * lists sessions; `openUnwiredApp` opens it zero-install on a page-needing call.
  */
-export function agentWiring(port, sessions, lease) {
-    const firstRun = firstRunWiring({ port, cliPath: process.argv[1] ?? '' });
-    const openUnwiredApp = firstCallOpener({
+export function agentWiring(sessions, lease) {
+    const firstRun = firstRunWiring();
+    const io = {
         project: () => firstRun.projectDirectory(callingClientDirectory() ?? process.cwd()),
         serving: async (ports) => (await probeDevServerStates(ports)).serving,
         servingDirectory: (url) => servingDirectoryOf(url),
         lease,
         connected: () => 0 < sessions.list().length,
-    });
-    return { firstRun, openUnwiredApp };
+    };
+    // Wired or not: a lease that names no url wants the app this caller works in either way.
+    const callerFolder = () => callingClientDirectory() ?? process.cwd();
+    return {
+        firstRun,
+        openUnwiredApp: firstCallOpener(io),
+        projectAppUrl: projectAppUrlFinder({ ...io, project: callerFolder }),
+    };
 }

package/dist/start-wiring.d.ts

@@ -47,8 +47,8 @@ export declare function sdkFixForProject(projectId?: string): string;
  * from before the project the agent is now driving existed.
  */
 /**
- * Every `.reticle` root on this machine that sync should consider, from the same two sources the
- * artifact resolver uses.
+ * Every `.reticle` root on this machine that sync should consider: the sources the artifact resolver
+ * uses, plus every root a lease claimed in this process.
  *
  * Read on every call rather than snapshotted, for the same reason: `reticle link` can run in
  * another terminal while this daemon is up, and a startup snapshot would keep that repo silent

package/dist/start-wiring.js

@@ -6,13 +6,16 @@
  * router, and the per-project lookups the daemon closes over. `daemon-parity.test.ts` checks both
  * entry points still call them.
  */
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { worktreeTwins } from './command/cli/config/checkout.js';
 import { cpus, homedir } from 'node:os';
 import { bridgeWsUrl, EventType, ReticleDir, ReticleEnv } from '@reticlehq/core';
 import { fetchPlatformConfig } from './features/harness/platform-config.js';
 import { platformEnvPort } from './memory/cloud/cloud-config.js';
 import { knownProjectCandidates, projectDirectoryFor, } from './memory/project/artifact-root-resolver.js';
 import { createNodeFileSystem } from './memory/project/fs/fs-port.js';
+import { claimedArtifactRoots } from './memory/project/root-claims.js';
 import { originOf } from './portal/session/session-manager.js';
 import { setBrowserMode, BrowserMode } from './telemetry/browser-mode.js';
 import { sdkFixForDirectory } from './command/version/sdk-fix.js';
@@ -151,8 +154,8 @@ export function sdkFixForProject(projectId) {
  * from before the project the agent is now driving existed.
  */
 /**
- * Every `.reticle` root on this machine that sync should consider, from the same two sources the
- * artifact resolver uses.
+ * Every `.reticle` root on this machine that sync should consider: the sources the artifact resolver
+ * uses, plus every root a lease claimed in this process.
  *
  * Read on every call rather than snapshotted, for the same reason: `reticle link` can run in
  * another terminal while this daemon is up, and a startup snapshot would keep that repo silent
@@ -162,7 +165,18 @@ export function sdkFixForProject(projectId) {
  * not. Deciding that here would mean reading every cloud.json on every tick.
  */
 export function knownProjectRoots() {
-    return [...new Set(knownProjectCandidates().map((c) => join(c.directory, ReticleDir.ROOT)))];
+    const directories = knownProjectCandidates().map((c) => c.directory);
+    // A page served from a git worktree writes its runs into that worktree's copy of the project.
+    const twins = directories
+        .flatMap(worktreeTwins)
+        .filter((d) => existsSync(join(d, ReticleDir.ROOT)));
+    return [
+        ...new Set([
+            ...[...directories, ...twins].map((d) => join(d, ReticleDir.ROOT)),
+            // A lease opened with `root` writes there; without this, that work is never sent.
+            ...claimedArtifactRoots(),
+        ]),
+    ];
 }
 /** This project's platform credential (stored, else the env key), as the env the platform readers take. */
 export const platformEnvFor = (root) => platformEnvPort(createNodeFileSystem(), root ?? join(process.cwd(), ReticleDir.ROOT), homedir(), process.env);

package/dist/status-payload.d.ts

@@ -36,6 +36,11 @@ interface StatusPayload {
      * a coding agent — what `reticle doctor` prints as its coverage line.
      */
     coverage?: TabCoverage[];
+    /**
+     * SDK version of each connected page, same order as the live tabs.
+     * `null` means the page did not report a version. Absent when nothing is connected.
+     */
+    pageSdkVersions?: readonly (string | null)[];
 }
 type TabCoverage = {
     sessionId: string;
@@ -47,7 +52,12 @@ why?: string, verifyPort?: number,
 /** The short rendering of the same diagnosis. Absent on a daemon that has no provider wired. */
 whyLead?: string, 
 /** The live tabs, for their coverage. */
-tabs?: readonly InstrumentedTab[]): StatusPayload;
+tabs?: readonly InstrumentedTab[], 
+/**
+ * SDK version of each connected page. `null` is a page that did not report one.
+ * Absent when nothing is connected. A newer CLI reads this to choose skew advice (#1709).
+ */
+pageSdkVersions?: readonly (string | null)[]): StatusPayload;
 /**
  * Why `serve --http` cannot claim success against an already-running daemon — or undefined when
  * that daemon already serves the verify HTTP endpoint on the wanted port.

package/dist/status-payload.js

@@ -7,7 +7,12 @@ why, verifyPort,
 /** The short rendering of the same diagnosis. Absent on a daemon that has no provider wired. */
 whyLead, 
 /** The live tabs, for their coverage. */
-tabs = []) {
+tabs = [], 
+/**
+ * SDK version of each connected page. `null` is a page that did not report one.
+ * Absent when nothing is connected. A newer CLI reads this to choose skew advice (#1709).
+ */
+pageSdkVersions = []) {
     return {
         running: true,
         version: SERVER_VERSION,
@@ -28,6 +33,7 @@ tabs = []) {
                     ...instrumentationOf(tab),
                 })),
             }),
+        ...(0 === pageSdkVersions.length ? {} : { pageSdkVersions }),
     };
 }
 /**

package/dist/surface/agent-presence-grace.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Hold back "the last agent detached" for a short grace.
+ *
+ * The daemon ends every browser session when the last agent detaches. A proxy that reconnects
+ * closes its stream and opens a new one, so a single drop of the link ended the user's session, and
+ * the agent's next call found "no connected session". With the grace, an agent that comes back
+ * inside it never detached, as far as the sessions can tell.
+ */
+/** Run `fn` after `ms`; the return value cancels it. Injected so a test needs no clock. */
+export type Schedule = (fn: () => void, ms: number) => () => void;
+export declare function withDetachGrace(onPresence: (connected: boolean) => void, graceMs: number, schedule?: Schedule): (connected: boolean) => void;

package/dist/surface/agent-presence-grace.js

@@ -0,0 +1,34 @@
+/**
+ * Hold back "the last agent detached" for a short grace.
+ *
+ * The daemon ends every browser session when the last agent detaches. A proxy that reconnects
+ * closes its stream and opens a new one, so a single drop of the link ended the user's session, and
+ * the agent's next call found "no connected session". With the grace, an agent that comes back
+ * inside it never detached, as far as the sessions can tell.
+ */
+const realSchedule = (fn, ms) => {
+    const timer = setTimeout(fn, ms);
+    // The grace must never keep a daemon alive that is shutting down.
+    timer.unref();
+    return () => clearTimeout(timer);
+};
+export function withDetachGrace(onPresence, graceMs, schedule = realSchedule) {
+    let cancelDetach;
+    return (connected) => {
+        if (!connected) {
+            cancelDetach?.();
+            cancelDetach = schedule(() => {
+                cancelDetach = undefined;
+                onPresence(false);
+            }, graceMs);
+            return;
+        }
+        if (cancelDetach !== undefined) {
+            // Back inside the grace: the detach was never reported, so there is no attach to report.
+            cancelDetach();
+            cancelDetach = undefined;
+            return;
+        }
+        onPresence(true);
+    };
+}

package/dist/surface/http-server.d.ts

@@ -8,7 +8,12 @@ export interface SharedServer {
      * so each concurrent Claude Code client needs its own McpServer.
      * Must be called before listen.
      */
-    attachMcp(factory: (peerSkew?: string) => McpServer): void;
+    attachMcp(factory: (peerSkew?: string, proxyId?: string, agentSession?: string) => McpServer): void;
+    /**
+     * SDK version of each page connected when an agent attaches.
+     * The daemon skew advice reads this so it does not tell the agent to restart over matching pages.
+     */
+    attachPageSdkVersions(provider: () => readonly (string | undefined)[]): void;
     /** Register the JSON the daemon returns from GET /status (live sessions + health for `reticle status`). */
     /** `held`: the request carried STATUS_HOLD_QUERY — a setup run is waiting on this daemon. */
     attachStatus(provider: (held: boolean) => unknown): void;
@@ -21,6 +26,12 @@ export interface SharedServer {
      * unattached, the route 404s, which is exactly what a newer CLI needs to hear from an older daemon.
      */
     attachDrive(provider: (url: string) => Promise<unknown>): void;
+    /**
+     * Register the handler behind POST /shutdown: the daemon's normal shutdown path. Only a loopback
+     * caller with the pairing token reaches it. Left unattached, the route 404s, and the caller falls
+     * back to a signal.
+     */
+    attachShutdown(handler: () => void): void;
     /**
      * Register a callback fired when the AGENT presence changes — true when the first MCP client (any
      * agent: Codex/OpenCode/Claude/Hermes) connects, false when the last one disconnects. Agent-