@reticlehq/server 3.1.0 → 3.3.0

package/dist/command/setup/agent-notice-memory.js

@@ -0,0 +1,65 @@
+/**
+ * Which "add the reticle entry by hand" lines have already been said on this machine.
+ *
+ * Two commands register agents, deliberately: the installer does it because it once reached fewer
+ * clients than `init` and sent people to a project directory to finish a half-done job, and `init`
+ * does it because that is where the project gets wired. Both then narrate the clients whose config
+ * we refuse to rewrite -- a Zed settings file with comments in it, a Continue YAML somebody
+ * formatted -- so a `curl | sh` followed by `reticle init` prints the same two paragraphs twice in
+ * one sitting, and prints them again on every re-run after that, forever.
+ *
+ * The REGISTRATION stays in both places. The sentence is the thing that repeats, and it is a
+ * sentence about a MACHINE rather than about a run: a config we will not rewrite stays un-rewritten
+ * until somebody edits it, at which point the notice's own text changes and it is said again.
+ *
+ * Stamped by content, not by run. If the stamp cannot be read or written the notice simply prints,
+ * which is the failure that costs a duplicate line rather than a missed instruction.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Where the stamp lives, under the state home the caller resolves. */
+export const NOTICE_MEMORY_BASENAME = 'agent-notices.json';
+/** Identity of a notice: the same client, the same file, for the same reason. */
+export function noticeKey(n) {
+    return JSON.stringify([n.name, n.file, n.why]);
+}
+/** Pure. The notices `said` has not already recorded, in order, without repeats. */
+export function unsaidNotices(said, notices) {
+    const seen = new Set(said);
+    const out = [];
+    for (const n of notices) {
+        const key = noticeKey(n);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(n);
+    }
+    return out;
+}
+/** Every key recorded before. An unreadable or malformed stamp reads as "nothing was said". */
+export function readSaid(stateHome) {
+    try {
+        const raw = readFileSync(join(stateHome, NOTICE_MEMORY_BASENAME), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((k) => 'string' === typeof k);
+    }
+    catch {
+        return [];
+    }
+}
+/** Record these keys beside whatever was there. A failed write costs a repeated line, nothing more. */
+export function rememberSaid(stateHome, keys) {
+    if (0 === keys.length)
+        return;
+    const merged = [...new Set([...readSaid(stateHome), ...keys])];
+    try {
+        mkdirSync(stateHome, { recursive: true });
+        writeFileSync(join(stateHome, NOTICE_MEMORY_BASENAME), JSON.stringify(merged, null, 2));
+    }
+    catch {
+        // Said once too often is the cost. Silence here is deliberate: a stamp that cannot be written
+        // must not fail an install.
+    }
+}

package/dist/command/setup/bringup/dev-server-wait.d.ts

@@ -56,6 +56,7 @@ export declare const WAIT_CEILING_MS: number;
  * that is a live server whatever its parent did.
  */
 export declare function judgeWait(facts: WaitFacts): WaitVerdict;
+export declare function portBusyMessage(output: string): string | undefined;
 export declare function announcedUrl(output: string): string | undefined;
 /**
  * The url to watch: whatever the tool announced, else one composed from a port we OBSERVED our own

package/dist/command/setup/bringup/dev-server-wait.js

@@ -45,6 +45,22 @@ export function judgeWait(facts) {
         ? WaitVerdict.HUNG
         : WaitVerdict.WAITING;
 }
+/**
+ * CRA (and webpack) print a prompt rather than a URL when their default port is taken, then exit
+ * or hang waiting for a tty. Setup used to report only "exited without serving anything", which
+ * hid the port that was actually busy (#802).
+ */
+const CRA_PORT_BUSY = /Something is already running on port (\d+)/i;
+const NAMED_PORT_BUSY = /Port (\d+) is (?:already )?in use/i;
+const EADDRINUSE_PORT = /(?:EADDRINUSE|address already in use)[^\d]*(\d+)/i;
+export function portBusyMessage(output) {
+    const match = CRA_PORT_BUSY.exec(output) ?? NAMED_PORT_BUSY.exec(output) ?? EADDRINUSE_PORT.exec(output);
+    const port = match?.[1];
+    if (undefined === port)
+        return undefined;
+    return (`port ${port} is already in use — something else is serving there, so this launcher did not ` +
+        `bind. Pass --url http://localhost:${port} if that process is this app, or free the port and re-run.`);
+}
 /** A url the dev server announced, if it has announced one. Never composed, only read. */
 const URL_IN_OUTPUT = /https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d+/;
 export function announcedUrl(output) {

package/dist/command/setup/bringup/ensure-daemon.js

@@ -16,7 +16,7 @@ import { spawnDaemon } from '../../daemon/daemon.js';
 import { probePresence, presenceIsUsable } from '../../daemon/binding/port-presence.js';
 import { waitForDaemon, probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
 import { daemonSpawnArgs } from '../../cli/daemon-start-options.js';
-import { fetchStatus } from '../../cli/launch/cli-launch.js';
+import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 export const EnsureDaemon = {
     /** Something usable was already there. */
     ADOPTED: 'adopted',

package/dist/command/setup/init/init-host.js

@@ -3,6 +3,9 @@ import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
 import { reportOnboardingStep } from '../../../telemetry/onboarding-funnel.js';
 import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../../portal/bridge/pairing-token.js';
 import { declaredInstallSource } from '../../../telemetry/install-source.js';
+/** The variable Claude Code sets on every process it spawns, and the value it sets it to. */
+const CLAUDE_CODE_MARKER_ENV = 'CLAUDECODE';
+const CLAUDE_CODE_MARKER_VALUE = '1';
 export function serverInitHost() {
     return {
         span(name, fields, fn) {
@@ -33,5 +36,10 @@ export function serverInitHost() {
         installSource() {
             return declaredInstallSource();
         },
+        // Claude Code marks every process it spawns. If the marker ever changes, init falls back to the
+        // notice it printed before, which is the safe direction.
+        insideClaudeCode() {
+            return CLAUDE_CODE_MARKER_VALUE === process.env[CLAUDE_CODE_MARKER_ENV];
+        },
     };
 }

package/dist/command/setup/init/init-runtime.js

@@ -15,7 +15,7 @@ import { relaunchDecision } from '../bringup/relaunch.js';
 import { claudeTranscriptExists, codexSessionFor } from '../terminal/transcripts.js';
 import { probePresence } from '../../daemon/binding/port-presence.js';
 import { probeDaemon } from '../../../surface/mcp/proxy/proxy-daemon-probe.js';
-import { fetchStatus } from '../../cli/launch/cli-launch.js';
+import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { collectEnv, DEFAULT_PHASE_TIMEOUT_MS } from '../setup-options.js';
 /** How often the runtime phases look again: fast enough not to be the wait, slow enough to be free. */
 const POLL_MS = 250;
@@ -129,6 +129,18 @@ export async function continueAfterInit(parsed, result, io, cwd) {
             return;
         }
         io.print('');
+        // The precondition for everything the closing asks for, printed on the path that could not say
+        // it. An agent client reads its MCP server list when it STARTS and never re-reads it, so on the
+        // run that first registers Reticle the `reticle_*` tools are not in the session that just asked
+        // for them -- and this path closes by telling that session to call `reticle_act_and_wait`.
+        // `restartHint` has said this for a long time and is printed only when init stops at the files.
+        if (true === result.mcpNewlyRegistered) {
+            io.print('Reticle was registered with your agent by this run, and an agent reads its tool list only ' +
+                'when it starts: the `reticle_*` tools are NOT in this session yet. Restart it first — ' +
+                '`npx @reticlehq/server init --relaunch` prints the exact resume command for Claude Code ' +
+                'and Codex. Once per machine.');
+            io.print('');
+        }
         if (outcome.ok && !outcome.flowSaved) {
             // Success, and no flow. Saying "a flow was driven" here would replace a wrong exit code with
             // a wrong sentence, which is the worse of the two: the exit code is read by CI and the

package/dist/command/setup/node-effects.js

@@ -15,7 +15,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { Socket } from 'node:net';
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { fetchStatus } from '../cli/launch/cli-launch.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
 import { descendants, parseLsofPorts, parseNetstatListeners, parseWmicProcesses, } from './terminal/listeners.js';
 import { loopbackProbeUrls } from './probe/loopback-probe-urls.js';
 const WINDOWS = 'win32' === process.platform;

package/dist/command/setup/probe/page-probe.js

@@ -43,8 +43,15 @@ export function describePage(finding, url) {
             return (`${url} is served, and the SDK is NOT in the page. That is almost always a dev server still ` +
                 'serving the bundle it built before the build config was edited: restart it and hard-reload.');
         case PageFinding.SDK_PRESENT:
-            return (`The SDK IS in the page at ${url} and never dialled the bridge, so it loaded and returned ` +
-                'early: a localhost guard, a production-only check, or a bridge port that differs on the two sides.');
+            // This used to end "so it loaded and returned early", which is a claim about a code path this
+            // check cannot see — and at least one real occurrence was the opposite. On a Windows install
+            // gate cell the page console read "could not open a websocket to ws://localhost:<port>, 3
+            // attempts, all failed": the SDK dialled three times and the socket failed, having returned
+            // early from nothing. What is knowable here is that the SDK is present and no session arrived.
+            return (`The SDK IS in the page at ${url} and never dialled the bridge: a localhost guard, a ` +
+                'production-only check, a bridge port that differs on the two sides, or `localhost` ' +
+                'resolving to IPv6 where the daemon is only on IPv4 — `npx @reticlehq/server doctor` names ' +
+                'that last one, and the page console names the first three.');
     }
 }
 /**

package/dist/command/setup/run-setup.d.ts

@@ -39,6 +39,18 @@ export interface SetupOutcome {
     readonly notes: string[];
 }
 /** Everything the sequence needs from the world, so none of it is reached for directly. */
+/**
+ * The daemon's reason for "no session", in the two lengths its two readers need.
+ *
+ * Same fact, not two facts: `full` is the lead plus the differential behind it, so a reader given
+ * only one of them is never given something the other contradicts.
+ */
+export interface DaemonReason {
+    /** One line, printed to the person watching the install. */
+    readonly lead: string;
+    /** The whole differential, recorded for the agent reading `--json`. Defaults to the lead. */
+    readonly full?: string;
+}
 export interface SetupEffects {
     /** Start the dev server. Resolves once started; the caller owns stopping it. */
     readonly startDevServer: (command: string, cwd: string) => Promise<void>;
@@ -70,6 +82,19 @@ export interface SetupEffects {
      */
     readonly openBrowser: (url: string) => Promise<void>;
     readonly listSessions: () => Promise<CandidateSession[]>;
+    /**
+     * The daemon's own account of why nothing connected, if it can be asked.
+     *
+     * The daemon is the only party that can see a hello it REFUSED, and a refusal is the one piece of
+     * positive evidence in the whole failure -- only an SDK dials the bridge, so a turned-away page
+     * proves the app is running, instrumented and pointed here. `page-probe.ts` has said since it was
+     * written that this sentence is the one to lead with and that the page finding merely adds the
+     * page-side fact; only the second half was wired.
+     *
+     * Optional, and allowed to fail: setup must still report what it saw when the daemon cannot be
+     * reached, which is itself one of the states this runs in.
+     */
+    readonly daemonWhy?: () => Promise<DaemonReason | undefined>;
     readonly now: () => number;
     readonly sleep: (ms: number) => Promise<void>;
     readonly note: (line: string) => void;
@@ -95,11 +120,4 @@ export interface SetupInput {
     readonly phaseTimeoutMs: number;
     readonly pollMs: number;
 }
-/**
- * Run the phases. Stops at the first one that cannot continue, and always says what is left.
- *
- * A phase that fails is not an error to throw: the caller is usually an agent, and a thrown
- * exception loses the four things it needs — how far this got, the url, the session, and what to do
- * about it.
- */
 export declare function runSetupPhases(input: SetupInput, fx: SetupEffects): Promise<SetupOutcome>;

package/dist/command/setup/run-setup.js

@@ -13,7 +13,7 @@
  * way of going wrong, and the alternative to injecting them is a test that boots a real dev server
  * and a real browser to find out what happens when neither works.
  */
-import { judgeWait, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
+import { judgeWait, portBusyMessage, QUIET_MEANS_HUNG_MS, urlToWatch, WaitVerdict, } from './bringup/dev-server-wait.js';
 import { waitProgressLine } from './terminal/wait-progress.js';
 /**
  * Windows gets longer to say something before silence counts as a wedge.
@@ -69,6 +69,23 @@ const stop = (input, phase, partial, notes) => ({
  * exception loses the four things it needs — how far this got, the url, the session, and what to do
  * about it.
  */
+/**
+ * Ask the daemon why, and treat every failure as "it did not say".
+ *
+ * A daemon that cannot be reached is one of the states this runs in, so an error here is data, not
+ * an exception: the page finding below still prints and the run still ends with its own verdict.
+ */
+async function daemonWhy(fx) {
+    if (undefined === fx.daemonWhy)
+        return undefined;
+    try {
+        const why = await fx.daemonWhy();
+        return undefined === why || 0 === why.lead.length ? undefined : why;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function runSetupPhases(input, fx) {
     const notes = [];
     const note = (line) => {
@@ -139,7 +156,8 @@ export async function runSetupPhases(input, fx) {
                     break;
                 }
                 if (WaitVerdict.DEAD === verdict) {
-                    note('The dev server exited without serving anything.');
+                    note(portBusyMessage(fx.devServerOutput()) ??
+                        'The dev server exited without serving anything.');
                     return stop(input, SetupPhase.DEV_SERVER, {}, notes);
                 }
                 if (WaitVerdict.HUNG === verdict) {
@@ -238,7 +256,25 @@ export async function runSetupPhases(input, fx) {
                 'the capture helper not installed, or a CSP that blocks the bridge: run `npx @reticlehq/server doctor`.');
         }
         else {
-            // What the page contains is the one thing the daemon cannot know, so it is worth one fetch.
+            // The daemon first, when it has something to say: it is the only party that can see a hello it
+            // refused, and that outranks anything inferred from an absence. Then the page, which is the
+            // one thing the daemon cannot know, and worth one fetch.
+            const why = await daemonWhy(fx);
+            if (undefined !== why) {
+                // Two readers, two lengths, one fetch.
+                //
+                // The person watching an install gets the LEAD — that is what trimming this diagnosis was
+                // for. The agent reads `notes` out of `--json`, and what it acts on is the differential:
+                // which ports were actually scanned (so an empty result is not proof), why a missing
+                // `.reticle.json` is expected in a monorepo, and the lease that opens a URL on a box with
+                // no browser at all.
+                //
+                // Printing only the lead put BOTH readers on the lead, which silently emptied the agent
+                // surface: `init --json` stopped mentioning the lease, and `break/break-matrix.mjs`
+                // (`no-browser-to-open`) went red for exactly that reason.
+                fx.note(why.lead);
+                notes.push(why.full ?? why.lead);
+            }
             note(describePage(readPage(await fx.probePage(url)), url));
         }
         return stop(input, SetupPhase.CONNECT, { url }, notes);
@@ -256,12 +292,18 @@ export async function runSetupPhases(input, fx) {
     // Both routes, because `explore` needs a model: without ANTHROPIC_API_KEY it answers "No model
     // configured to drive the app". Naming only that one hands the reader a dead end on any machine
     // without a key, which is the same defect this release spent its time removing everywhere else.
-    note(`Connected, and the app at ${url} is instrumented. Onboarding is done. Nothing is PROVED ` +
-        'yet: that is the first run, and it is yours to start. Drive one flow yourself with the ' +
-        '`reticle_*` tools, ending in `reticle_act_and_wait` or `reticle_assert` — those two are ' +
-        'what produce a verdict. Or hand the whole drive to Reticle with `reticle_verify { action: ' +
-        '"explore", persona: "<who does what>" }`, which records what it drove so later runs replay ' +
-        'with no model in the loop; that route needs ANTHROPIC_API_KEY.');
+    // Three short lines rather than one paragraph, and each says who it is for.
+    //
+    // This was a single 524-character note, measured on a real first run: eighty-three words, no
+    // break, naming `reticle_*` tools at a reader who had just typed `reticle init` in a terminal and
+    // has no such tools to call. The facts were right and the shape made them unreadable, which on
+    // the last line of onboarding is the same as not saying them.
+    note(`Connected. ${url} is instrumented. Onboarding is done; nothing is verified yet.`);
+    note('Agent: drive one flow and end it with `reticle_act_and_wait` or `reticle_assert`. Those two ' +
+        'produce a verdict; nothing else does.');
+    note('Or hand over the whole drive: `reticle_verify { action: "explore", persona: "<who does ' +
+        'what>" }` records what it drove, so later runs replay with no model in the loop. Needs ' +
+        'ANTHROPIC_API_KEY.');
     return {
         ok: true,
         reachedPhase: SetupPhase.CONNECT,

package/dist/command/setup/setup-command.js

@@ -22,7 +22,10 @@ import { reticleStateHome } from '../daemon/daemon.js';
 import { readDevServers } from '../daemon/dev-servers.js';
 import { urlOfExistingApp } from './probe/existing-app.js';
 import { listSessions, OwnedDevServer, probePage } from './node-effects.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { summarizeStatus } from '../cli/launch/cli-launch.js';
 import { runSetupPhases, } from './run-setup.js';
+import { noticeKey, readSaid, rememberSaid, unsaidNotices } from './agent-notice-memory.js';
 /**
  * The dev server a crash should take with it, if one is running right now.
  *
@@ -89,10 +92,20 @@ export function registerOtherAgents(print) {
     if (0 < wrote.length) {
         print(`registered the MCP server with ${wrote.length} more agent(s): ${wrote.map((r) => r.name).join(', ')}`);
     }
-    // A format we will not rewrite is somebody's to edit, so it has to be said rather than skipped.
-    for (const manual of results.filter((r) => 'manual' === r.action)) {
-        print(`${manual.name}: ${manual.why} — add the reticle entry to ${manual.file} by hand.`);
+    // A format we will not rewrite is somebody's to edit, so it has to be said rather than skipped --
+    // but said ONCE. Two commands call this function by design, so a `curl | sh` followed by
+    // `reticle init` printed the same two paragraphs twice in one sitting, and again on every re-run
+    // after that. See agent-notice-memory.ts: the stamp is keyed on the notice's own text, so a
+    // config that changes is reported again.
+    const stateHome = reticleStateHome();
+    const manual = results
+        .filter((r) => 'manual' === r.action)
+        .map((r) => ({ name: r.name, file: r.file, why: r.why }));
+    const fresh = unsaidNotices(readSaid(stateHome), manual);
+    for (const notice of fresh) {
+        print(`${notice.name}: ${notice.why} — add the reticle entry to ${notice.file} by hand.`);
     }
+    rememberSaid(stateHome, fresh.map((n) => noticeKey(n)));
     const skills = applyAgentSkills(agentIo, { home, platform });
     if (0 < skills.length)
         print(`wrote the /reticle skill for ${skills.length} agent(s)`);
@@ -166,6 +179,21 @@ export async function runSetupCommand(input, print) {
             }
         },
         listSessions: () => listSessions(input.bridgePort),
+        // `summarizeStatus` already narrows this payload for `reticle status`; reusing it here keeps one
+        // reader of the wire shape rather than two that can disagree about which key carries the reason.
+        // Both lengths, from the one read: the lead is printed to the person watching the install, the
+        // full differential is recorded for the agent reading `--json`. Returning only the lead here is
+        // what emptied the agent surface — see the note at the call site in `run-setup.ts`.
+        daemonWhy: async () => {
+            const status = summarizeStatus(await fetchStatus(input.bridgePort));
+            const full = status.why;
+            // A daemon too old to report the short one falls back to the long one, because saying the
+            // right thing at length beats saying nothing.
+            const lead = status.whyLead ?? full;
+            if (undefined === lead)
+                return undefined;
+            return undefined === full ? { lead } : { lead, full };
+        },
         now: () => Date.now(),
         sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
         note: print,

package/dist/command/setup/terminal/confirm.js

@@ -29,7 +29,8 @@
  *    it worked.
  */
 import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
-import { fetchStatus, summarizeStatus } from '../../cli/launch/cli-launch.js';
+import { summarizeStatus } from '../../cli/launch/cli-launch.js';
+import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 import { readDevServers } from '../../daemon/dev-servers.js';
 import { devServersForProject } from '@reticlehq/core/artifacts';
 import { readProjectId } from '../../cli/ports/resolve/cli-port.js';

package/dist/command/update/updater.d.ts

@@ -29,6 +29,33 @@ type ExecutionKind = (typeof ExecutionKind)[keyof typeof ExecutionKind];
  * `apply_update` npm-installs into the user's own project (polluting their package.json).
  */
 export declare function classifyExecutionKind(script: string): ExecutionKind;
+/**
+ * Spawn npm, through a shell on Windows because `npm.cmd` cannot be spawned without one.
+ *
+ * Since the CVE-2024-27980 fix -- in every supported Node -- spawning a `.cmd` with no shell throws
+ * EINVAL. This repo has already paid for that lesson once, at `init/src/node-io.ts`: `reticle setup
+ * mcp` probed for the Claude CLI with a bare `execFileSync`, the probe threw, and the installer
+ * told the user their machine had no Claude Code on it. The same shape sat here, in the SELF-UPDATE
+ * path -- the channel every other fix reaches a user through, and the one place a silent failure
+ * strands somebody on an old version indefinitely.
+ *
+ * Arguments are quoted with init's own rule rather than a second copy of it. They are internal
+ * today (`install`, `-g`, and a package spec whose version comes from the registry), but a shell
+ * turns "internal" into "whatever the registry said", and the quoting is one import.
+ */
+export declare function npmSpawn(args: string[], 
+/**
+ * Injected so the Windows branch is testable on every platform.
+ *
+ * The bug this fixes could only be OBSERVED on Windows, and a check that can only fail on a
+ * machine nobody here runs is a check that fails in CI at the earliest and in the field at the
+ * latest. The rule is a pure function of the platform string, so it is one.
+ */
+on?: string): {
+    file: string;
+    argv: string[];
+    shell: boolean;
+};
 interface NpmInstall {
     args: string[];
     cwd?: string;

package/dist/command/update/updater.js

@@ -6,6 +6,7 @@ import { dirname, join } from 'node:path';
 import { loadManifest, saveManifest } from './update-checker.js';
 import { RETICLE_NPM_PACKAGE, SERVER_VERSION } from '../version/identity/server-version.js';
 import { log } from '../../log.js';
+import { windowsShellArg } from '@reticlehq/init';
 import { TelemetryEventKind } from '@reticlehq/core/telemetry';
 import { getTelemetry } from '../../telemetry/telemetry.js';
 import { wasNudged } from './nudge-credit.js';
@@ -34,7 +35,6 @@ export async function reportVersionChange(from, to, direction) {
         /* best-effort, like every other send */
     }
 }
-const NPM_BIN = NodePlatform.WINDOWS === platform() ? 'npm.cmd' : 'npm';
 const NPM_TIMEOUT_MS = 120_000;
 /** How this reticle process was launched — determines which npm strategy to use for updates. */
 const ExecutionKind = {
@@ -91,9 +91,42 @@ function findLocalProjectRoot() {
         dir = parent;
     }
 }
+/**
+ * Spawn npm, through a shell on Windows because `npm.cmd` cannot be spawned without one.
+ *
+ * Since the CVE-2024-27980 fix -- in every supported Node -- spawning a `.cmd` with no shell throws
+ * EINVAL. This repo has already paid for that lesson once, at `init/src/node-io.ts`: `reticle setup
+ * mcp` probed for the Claude CLI with a bare `execFileSync`, the probe threw, and the installer
+ * told the user their machine had no Claude Code on it. The same shape sat here, in the SELF-UPDATE
+ * path -- the channel every other fix reaches a user through, and the one place a silent failure
+ * strands somebody on an old version indefinitely.
+ *
+ * Arguments are quoted with init's own rule rather than a second copy of it. They are internal
+ * today (`install`, `-g`, and a package spec whose version comes from the registry), but a shell
+ * turns "internal" into "whatever the registry said", and the quoting is one import.
+ */
+export function npmSpawn(args, 
+/**
+ * Injected so the Windows branch is testable on every platform.
+ *
+ * The bug this fixes could only be OBSERVED on Windows, and a check that can only fail on a
+ * machine nobody here runs is a check that fails in CI at the earliest and in the field at the
+ * latest. The rule is a pure function of the platform string, so it is one.
+ */
+on = platform()) {
+    const bin = NodePlatform.WINDOWS === on ? 'npm.cmd' : 'npm';
+    if (NodePlatform.WINDOWS !== on)
+        return { file: bin, argv: args, shell: false };
+    return { file: [bin, ...args.map(windowsShellArg)].join(' '), argv: [], shell: true };
+}
 function runNpm(args, opts = {}) {
+    const spawn = npmSpawn(args);
     return new Promise((resolve, reject) => {
-        execFile(NPM_BIN, args, { timeout: NPM_TIMEOUT_MS, ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}) }, (err, _stdout, stderr) => {
+        execFile(spawn.file, spawn.argv, {
+            timeout: NPM_TIMEOUT_MS,
+            ...(spawn.shell ? { shell: true } : {}),
+            ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        }, (err, _stdout, stderr) => {
             if (err !== null) {
                 reject(new Error(`npm ${args.join(' ')} failed: ${stderr !== '' ? stderr : err.message}`));
             }

package/dist/features/crawl/crawl-tools.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { projectForRoot } from '../../memory/project/project-for-root.js';
 import { ReticleTool } from '@reticlehq/core';
 import { asNumber, asString } from '@reticlehq/core';
 import { stepCountSchema, timeoutMsSchema } from '../../surface/tools/args/numeric-bounds.js';
@@ -80,7 +82,7 @@ export const CRAWL_TOOLS = [
                 ...routesFromEvents(session.eventsSince(since)),
             ];
             if (routes.length > 0)
-                await deps.project.recordRoutes(routes);
+                await projectForRoot(deps, sessionRoot(deps, session.id)).recordRoutes(routes);
             return report;
         },
     },

package/dist/features/crawl/crawl.d.ts

@@ -16,6 +16,8 @@ export interface CrawlSession {
     /** The page under test, so a third-party beacon cannot be reported against a control. Optional
      *  for the same reason `currentDocumentId` is. */
     readonly url?: string | undefined;
+    /** Same-origin endpoints the project declared as background. Optional like `url`. */
+    readonly background?: readonly string[] | undefined;
     /**
      * Is the page BACKGROUNDED? A hidden tab has its rAF clamped and the DOM observer flushes on rAF,
      * so real renders emit nothing and every absence-derived contradiction reads that silence as a

package/dist/features/crawl/crawl.js

@@ -8,7 +8,8 @@ import { span } from '../../trace.js';
 import { ActionType, CRAWL_DEFAULTS, CrawlAnomalyKind, DANGEROUS_ACTION_CONFIRM_ARG, EventType, ReticleCommand, } from '@reticlehq/core';
 import { crawlEmptyNote } from './crawl-empty.js';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
-import { parseInteractive, sourceOf } from '../../surface/tools/tools-helpers.js';
+import { parseInteractive } from '@reticlehq/core';
+import { sourceOf } from '../../surface/tools/tools-helpers.js';
 import { isSessionReplacedError } from '../../portal/session/facts/session-replaced.js';
 import { ReticleTool } from '@reticlehq/core';
 import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
@@ -346,6 +347,7 @@ export async function crawl(session, opts, sleep) {
             currentDocumentId: session.currentDocumentId,
             currentEditEpoch: session.currentEditEpoch,
             appOrigin: session.url,
+            background: session.background,
             // A hidden tab cannot be observed, so its silence is not evidence. Stated from the session
             // rather than left to a heartbeat landing inside a 300ms window.
             pageHidden: session.throttled?.(),

package/dist/features/harness/drive-report.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What a drive did, written from the evidence rather than narrated by the model that drove.
+ *
+ * `HarnessResult.summary` is the driver's own account, and it has always carried a warning that
+ * nothing downstream grades it. That was a caveat when the driver was a language model. It became a
+ * hole the moment a System One model could drive: Jev answers typed questions and cannot produce a
+ * sentence, so `summary` came back EMPTY, and an agent calling `explore` got a result with no
+ * account of what had happened in it at all.
+ *
+ * Restoring prose would have been the obvious fix and the wrong one. The drive already records
+ * every call it made, with the arguments it used and the verdict the engine returned — so the
+ * account can be DERIVED. That is strictly better than a narration: a model summarising its own
+ * drive is the one witness with a reason to round "unknown" up to "worked", and this cannot, because
+ * it is not writing about the drive, it is reading it.
+ *
+ * Written for the agent on the other end of the MCP call. It leads with what was proved, because
+ * that is what a coding agent has to gate on, and it says "not proved" in those words rather than
+ * leaving a verdict of `unknown` to be read as a pass.
+ */
+import type { ToolOutcome } from './harness.js';
+/** One driven action, reduced to what a reader needs: what was done, and what it proved. */
+export interface DrivenStep {
+    /** The action verb, e.g. `click`. */
+    action: string;
+    /** The element, named the way a person would say it, falling back to the ref. */
+    target: string;
+    /** The engine's verdict for this step, when the step declared anything. */
+    verified: string | undefined;
+    /** The one sentence naming the deciding evidence. */
+    because: string | undefined;
+    /**
+     * What the drive CLAIMED would happen, in the words it declared before acting.
+     *
+     * Carried because "3 action(s) FAILED" is not triageable without it. A failure is either a defect
+     * in the app or a wrong guess by the driver, those need opposite responses, and the declared
+     * consequence is the only thing that tells them apart. Shown on failures only: on a pass it is
+     * noise, and the report is read every drive.
+     */
+    claimed: string | undefined;
+}
+/**
+ * Replays this drive ran, and what each came back with.
+ *
+ * The verdict is `status`, not `passed`. Reading the wrong key reported ten replays as "undecided"
+ * on a run where every one of them had answered — which is the same false-nothing this report was
+ * written to stop, made by the report itself.
+ *
+ * Three outcomes, kept apart because they mean different things to whoever reads this. `ok` is the
+ * journey still holding. `error` is it failing. `drift` is the flow's own anchors no longer
+ * resolving — the app moved under a recording, which is a finding about the RECORDING rather than
+ * proof the feature broke, and collapsing it into "failed" would send somebody to fix working code.
+ */
+export declare const ReplayOutcome: {
+    readonly OK: "ok";
+    readonly DRIFT: "drift";
+    readonly ERROR: "error";
+};
+export declare function replayedFlows(toolCalls: readonly ToolOutcome[]): {
+    name: string;
+    status: string | undefined;
+}[];
+/** Reduce the raw call log to the actions that actually drove the app. */
+export declare function drivenSteps(toolCalls: readonly ToolOutcome[]): DrivenStep[];
+/**
+ * The account, as lines.
+ *
+ * Proved and not-proved are counted separately and both are stated, because the failure mode this
+ * whole product exists to prevent is a reader taking "we did twelve things" for "twelve things
+ * work". `unknown` is deliberately grouped under NOT proved and labelled as undecided evidence
+ * rather than as a failure — it calls for a better check, not a code change, and collapsing the two
+ * would send an agent to rewrite working code.
+ */
+export declare function describeDrive(toolCalls: readonly ToolOutcome[], savedFlows: readonly string[]): string;