@reticlehq/server 3.1.0 → 3.2.0

package/dist/command/daemon/lifetime/log-cap.d.ts

@@ -0,0 +1,68 @@
+/**
+ * How big the daemon's log may get, and the three things that keep it there.
+ *
+ * `rotateDaemonLog` runs at spawn. `guardDaemonLog` runs while the daemon lives, because a detached
+ * daemon writes for days — a beat every thirty seconds plus every session, tool call and reconnect —
+ * and a size checked once at start is a size nothing will ever check again. A log measured at 98% of
+ * the cap and still climbing had no remaining mechanism that would trim it, and the tracker carries
+ * the same failure with a bigger number: the daemon log filling a disk, and a user who left over it.
+ * `pruneOldDaemonLogs` is the other half of the disk — one file per port ever bound, forever.
+ *
+ * Here rather than in daemon.ts because the size check has to be called from the heartbeat, and
+ * `lifetime` is a sink: nothing in it may reach back into its parent. Same reason nothing here
+ * logs — the caller that has a logger emits `DAEMON_LOG_TRUNCATED_EVENT`.
+ */
+/**
+ * How large a daemon log may get before it is rolled over to `<name>.1`.
+ *
+ * It was unbounded. A real dev machine reached **24MB** on one port, which is not merely untidy: it
+ * is the difference between a log somebody opens and a log somebody gives up on, and it is disk that
+ * nothing ever reclaims. One previous generation is kept, because the question people bring to this
+ * file ("what happened just now?") is answered by the current one and the question they bring next
+ * ("and just before that?") is answered by the other.
+ */
+export declare const MAX_DAEMON_LOG_BYTES: number;
+/**
+ * Reclaim a log that has already run past `max`, by TRUNCATING IT IN PLACE. Returns bytes reclaimed.
+ *
+ * The one definition behind both logs Reticle writes: the daemon log, and the MCP proxy log in
+ * surface/mcp/proxy/proxy-log.ts, which delegates to this. An uncapped proxy log has filled a disk
+ * and broken unrelated builds, Docker and ordinary shell commands with ENOSPC; the daemon log is
+ * larger, longer-lived and had the same hole, so it gets the same answer rather than a second one.
+ *
+ * In place, never renamed or unlinked: a rename moves the bytes without reclaiming a byte, and a
+ * file a running process still holds open keeps its blocks allocated after an unlink until that
+ * handle closes. `: > ~/.reticle/daemon-4400.log` is the operation being copied here.
+ *
+ * Best-effort, in the same spirit as `rotateDaemonLog`: dying over housekeeping is strictly worse
+ * than a large file.
+ */
+export declare function recoverOversizedLog(deps: {
+    size(): number;
+    truncate(): void;
+}, max?: number): number;
+/** Emitted into the fresh log immediately after a truncation, so the gap explains itself. */
+export declare const DAEMON_LOG_TRUNCATED_EVENT = "reticle_daemon_log_truncated";
+/** Keep a RUNNING daemon's log under the cap. Returns the bytes reclaimed, 0 when it was fine. */
+export declare function guardDaemonLog(deps?: {
+    size(): number;
+    truncate(): void;
+}): number;
+/**
+ * How long a daemon log outlives its daemon.
+ *
+ * Every port ever bound leaves a `daemon-<port>.log` behind and nothing removed any of them — one
+ * machine held 128 files in `~/.reticle`, logs the large majority. Nothing enumerates them either:
+ * every reader (`doctor`, the startup-cause reader, the lifecycle messages) opens the log of the
+ * port it is asking about right now, so a log for a port that will never be bound again is read by
+ * nobody. A week is long enough to still have last Tuesday's crash when somebody asks about it.
+ */
+export declare const DAEMON_LOG_RETENTION_MS: number;
+/**
+ * Delete daemon logs nothing has written to in the retention window. Returns the names removed.
+ *
+ * Age is the whole test, and it doubles as the liveness probe: a live daemon beats into its log
+ * every thirty seconds, so a log older than a week has no daemon behind it by construction.
+ * Best-effort throughout — a log that will not delete is not a reason to fail a daemon start.
+ */
+export declare function pruneOldDaemonLogs(home: string, nowMs: number): string[];

package/dist/command/daemon/lifetime/log-cap.js

@@ -0,0 +1,115 @@
+/**
+ * How big the daemon's log may get, and the three things that keep it there.
+ *
+ * `rotateDaemonLog` runs at spawn. `guardDaemonLog` runs while the daemon lives, because a detached
+ * daemon writes for days — a beat every thirty seconds plus every session, tool call and reconnect —
+ * and a size checked once at start is a size nothing will ever check again. A log measured at 98% of
+ * the cap and still climbing had no remaining mechanism that would trim it, and the tracker carries
+ * the same failure with a bigger number: the daemon log filling a disk, and a user who left over it.
+ * `pruneOldDaemonLogs` is the other half of the disk — one file per port ever bound, forever.
+ *
+ * Here rather than in daemon.ts because the size check has to be called from the heartbeat, and
+ * `lifetime` is a sink: nothing in it may reach back into its parent. Same reason nothing here
+ * logs — the caller that has a logger emits `DAEMON_LOG_TRUNCATED_EVENT`.
+ */
+import { fstatSync, ftruncateSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * How large a daemon log may get before it is rolled over to `<name>.1`.
+ *
+ * It was unbounded. A real dev machine reached **24MB** on one port, which is not merely untidy: it
+ * is the difference between a log somebody opens and a log somebody gives up on, and it is disk that
+ * nothing ever reclaims. One previous generation is kept, because the question people bring to this
+ * file ("what happened just now?") is answered by the current one and the question they bring next
+ * ("and just before that?") is answered by the other.
+ */
+export const MAX_DAEMON_LOG_BYTES = 8 * 1024 * 1024;
+/**
+ * Reclaim a log that has already run past `max`, by TRUNCATING IT IN PLACE. Returns bytes reclaimed.
+ *
+ * The one definition behind both logs Reticle writes: the daemon log, and the MCP proxy log in
+ * surface/mcp/proxy/proxy-log.ts, which delegates to this. An uncapped proxy log has filled a disk
+ * and broken unrelated builds, Docker and ordinary shell commands with ENOSPC; the daemon log is
+ * larger, longer-lived and had the same hole, so it gets the same answer rather than a second one.
+ *
+ * In place, never renamed or unlinked: a rename moves the bytes without reclaiming a byte, and a
+ * file a running process still holds open keeps its blocks allocated after an unlink until that
+ * handle closes. `: > ~/.reticle/daemon-4400.log` is the operation being copied here.
+ *
+ * Best-effort, in the same spirit as `rotateDaemonLog`: dying over housekeeping is strictly worse
+ * than a large file.
+ */
+export function recoverOversizedLog(deps, max = MAX_DAEMON_LOG_BYTES) {
+    try {
+        const size = deps.size();
+        if (max >= size)
+            return 0;
+        deps.truncate();
+        return size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * The daemon's log, as the daemon itself can address it: its own stderr.
+ *
+ * `spawnDaemon` hands the child `stdio: ['ignore', logFd, logFd]`, so inside a running daemon fd 2
+ * IS `daemon-<port>.log`, opened with O_APPEND — which is what makes truncating it safe: an
+ * appending write always lands at the new end of file, so there is no sparse hole and no lost
+ * handle. No path, no port and no second open are needed to reach it. When the daemon runs in the
+ * foreground fd 2 is a terminal, whose reported size is 0, so this is a no-op there.
+ */
+const DAEMON_LOG_FD = 2;
+/** Emitted into the fresh log immediately after a truncation, so the gap explains itself. */
+export const DAEMON_LOG_TRUNCATED_EVENT = 'reticle_daemon_log_truncated';
+const daemonLogFdOps = {
+    size: () => fstatSync(DAEMON_LOG_FD).size,
+    truncate: () => ftruncateSync(DAEMON_LOG_FD, 0),
+};
+/** Keep a RUNNING daemon's log under the cap. Returns the bytes reclaimed, 0 when it was fine. */
+export function guardDaemonLog(deps = daemonLogFdOps) {
+    return recoverOversizedLog(deps);
+}
+/**
+ * How long a daemon log outlives its daemon.
+ *
+ * Every port ever bound leaves a `daemon-<port>.log` behind and nothing removed any of them — one
+ * machine held 128 files in `~/.reticle`, logs the large majority. Nothing enumerates them either:
+ * every reader (`doctor`, the startup-cause reader, the lifecycle messages) opens the log of the
+ * port it is asking about right now, so a log for a port that will never be bound again is read by
+ * nobody. A week is long enough to still have last Tuesday's crash when somebody asks about it.
+ */
+export const DAEMON_LOG_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Delete daemon logs nothing has written to in the retention window. Returns the names removed.
+ *
+ * Age is the whole test, and it doubles as the liveness probe: a live daemon beats into its log
+ * every thirty seconds, so a log older than a week has no daemon behind it by construction.
+ * Best-effort throughout — a log that will not delete is not a reason to fail a daemon start.
+ */
+export function pruneOldDaemonLogs(home, nowMs) {
+    const pruned = [];
+    let files;
+    try {
+        files = readdirSync(home);
+    }
+    catch {
+        return pruned; // no ~/.reticle yet → nothing to prune
+    }
+    for (const file of files) {
+        if (null === /^daemon-\d+\.log(\.1)?$/.exec(file))
+            continue;
+        const path = join(home, file);
+        try {
+            if (DAEMON_LOG_RETENTION_MS > nowMs - statSync(path).mtimeMs)
+                continue;
+            unlinkSync(path);
+            pruned.push(file);
+        }
+        catch {
+            // unreadable or already gone — either way it is not this process's problem
+        }
+    }
+    return pruned;
+}

package/dist/command/setup/agent-notice-memory.d.ts

@@ -0,0 +1,16 @@
+/** One client we could not write to, and why. */
+export interface ManualNotice {
+    readonly name: string;
+    readonly file: string;
+    readonly why: string;
+}
+/** Where the stamp lives, under the state home the caller resolves. */
+export declare const NOTICE_MEMORY_BASENAME = "agent-notices.json";
+/** Identity of a notice: the same client, the same file, for the same reason. */
+export declare function noticeKey(n: ManualNotice): string;
+/** Pure. The notices `said` has not already recorded, in order, without repeats. */
+export declare function unsaidNotices(said: readonly string[], notices: readonly ManualNotice[]): ManualNotice[];
+/** Every key recorded before. An unreadable or malformed stamp reads as "nothing was said". */
+export declare function readSaid(stateHome: string): string[];
+/** Record these keys beside whatever was there. A failed write costs a repeated line, nothing more. */
+export declare function rememberSaid(stateHome: string, keys: readonly string[]): void;

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