@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,206 @@
+/**
+ * The step `init` never took: stay and watch for an app to connect.
+ *
+ * The install has two halves. Registering the MCP server gives the agent the tools; getting the SDK
+ * into a running page gives it something to look at. Almost everyone finishes the first, and nothing
+ * joined "init finished" to "an app connected" — so `init` exited 0 having written files, and the
+ * person left with a config file and no instrumented page was never told (#269).
+ *
+ * The capability existed in three places and was used together by none of them: the poll behind
+ * `reticle open`, the install gate (which calls this exact check "the only step that proves the
+ * install works"), and the event that measures whether it ever happened.
+ *
+ * WHY NO FLAG, and no dev-server management:
+ *
+ *  - No flag, because the people this is for are the ones who do not know to ask. `--verify` would
+ *    be typed by the users who already run `status` afterwards, which is exactly the cohort that is
+ *    not being lost. The gate instead is whether a HUMAN IS AT THE TERMINAL: `init` waits when
+ *    stdout is a TTY and skips the wait entirely otherwise, so a scripted or agent-driven `init`
+ *    keeps today's cost and today's exit behaviour, and blocking never happens where blocking is
+ *    wrong. The signal is the standard "am I being piped" one and needs no argument parsing, which
+ *    also keeps `init`'s documented flag surface where it is.
+ *  - The DAEMON never starts anything. A dev server started by a long-lived daemon is invisible to
+ *    the person whose machine it runs on and orphans when the daemon exits, so the daemon stays out
+ *    of it. Note what that reasoning is actually about: attributability, not abstinence. A
+ *    foreground `init` somebody ran satisfies it — the command is in their transcript, and it stops
+ *    what it started if setup fails or is interrupted — which is why the runtime phase is allowed
+ *    to boot one where the daemon is not. This function keeps its own shape either way: confirm the
+ *    app if it connects, otherwise name the ONE command that is outstanding and the one that proves
+ *    it worked.
+ */
+import { InitConfirmation, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+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';
+import { reticleStateHome } from '../../daemon/daemon.js';
+import { reportInitOutcome } from '../../../telemetry/init-telemetry.js';
+/**
+ * How long a human is asked to wait.
+ *
+ * Long enough for a page that is already loading to finish dialling, short enough that somebody who
+ * has not restarted their dev server yet is not held hostage by a wait that cannot succeed — they
+ * have not typed the command that would make it succeed, and the message tells them which one.
+ */
+const CONFIRM_WINDOW_MS = 12_000;
+const CONFIRM_POLL_MS = 500;
+/**
+ * Poll until an app connects or the window runs out.
+ *
+ * A session that was ALREADY there when the wait began does not count, and this is the whole reason
+ * the check reads ids rather than a count. A daemon is shared across every project on the machine,
+ * so "a session exists" is satisfied by another app, by a stray tab, by yesterday's work — and
+ * confirming this install on somebody else's session is a false green in the one message a user
+ * reads to decide whether they are done. `reticle open` refuses the same way, for the same reason.
+ *
+ * The conservative direction is deliberate: an app that reconnects under an id it already held is
+ * reported as not-yet-connected, and the message it gets sends them to `status`, which shows it. A
+ * missed confirmation costs one command; a false one costs the whole point of confirming.
+ */
+export async function confirmAppConnected(deps) {
+    const deadline = deps.now() + (deps.windowMs ?? CONFIRM_WINDOW_MS);
+    let before;
+    for (;;) {
+        const ids = await deps.listSessionIds();
+        // A port nobody is listening on cannot receive a session, and no amount of waiting changes that.
+        // One look settles it; polling on would spend the whole window to re-learn the first answer.
+        if (null === ids)
+            return InitConfirmation.NO_DAEMON;
+        const baseline = before;
+        if (baseline === undefined)
+            before = new Set(ids);
+        else if (ids.some((id) => !baseline.has(id)))
+            return InitConfirmation.CONNECTED;
+        if (deadline <= deps.now())
+            return InitConfirmation.NO_SESSION;
+        await deps.sleep(deps.pollMs ?? CONFIRM_POLL_MS);
+    }
+}
+const PROVE_COMMAND = '`npx @reticlehq/server status`';
+/**
+ * What the user reads, in the marks the rest of the report already uses: `⚠` means work left to do
+ * and nothing else, `ℹ` is worth reading but is not work, `✓` happened.
+ *
+ * Only NO_SESSION earns a `⚠`, and it earns it honestly: the app is wired and has not connected, so
+ * there is a command outstanding. A missing daemon is not a defect in the install — the daemon comes
+ * up when the agent loads the tools — so it is a notice.
+ */
+/**
+ * Narrow "no app connected" using what the dev servers themselves announced.
+ *
+ * `confirmAppConnected` can only observe the bridge, so its NO_SESSION covers two situations with
+ * OPPOSITE fixes: the dev server is not running Reticle at all, or it is and no page has been
+ * opened. An announced entry is proof the plugin is loaded in the process that is actually running
+ * — which means the config is right and it has already been restarted.
+ *
+ * Only the unexplained answer is sharpened. CONNECTED is the finished state and NO_DAEMON is a
+ * different fact; neither becomes more true because a dev server is up.
+ */
+export function sharpenWithDevServers(confirmation, running) {
+    if (confirmation !== InitConfirmation.NO_SESSION)
+        return confirmation;
+    return 0 === running.length ? InitConfirmation.NO_SESSION : InitConfirmation.NO_PAGE;
+}
+export function confirmationMessage(confirmation, port, running = []) {
+    if (confirmation === InitConfirmation.CONNECTED) {
+        return ('  [✓] an app is connected — that is the install finished, not just written.\n' +
+            '      Ask your agent to drive a flow.');
+    }
+    if (confirmation === InitConfirmation.NO_DAEMON) {
+        return (`  [ℹ] nothing is listening on port ${String(port)} yet, so no app could have connected and ` +
+            'this run did not wait for one.\n' +
+            '      The daemon starts on its own when your agent loads the Reticle tools. After that, ' +
+            `${PROVE_COMMAND} confirms the app.`);
+    }
+    if (confirmation === InitConfirmation.NO_PAGE) {
+        // Deliberately never says "restart". The announcement is proof they already did — telling them
+        // again is how a correct instruction reads as the tool not knowing what is going on.
+        const where = running.map((s) => `        ${s.url}`).join('\n');
+        return ('  [⚠] your dev server has Reticle loaded, and no page has connected yet — so the only step ' +
+            'left is opening the app.\n' +
+            `      Open it in a browser:\n${where}\n` +
+            `      ${PROVE_COMMAND} then confirms it.`);
+    }
+    return ('  [⚠] no app has connected yet — the files are written, the page half of the install is not ' +
+        'done.\n' +
+        '      Restart your dev server and load the app in a browser — or ask your agent to, which it is ' +
+        'now told to do for you, in the background and with the command from your own scripts.\n' +
+        `      ${PROVE_COMMAND} then confirms it, or says exactly why it has not connected.`);
+}
+/**
+ * What a non-TTY run says instead of waiting.
+ *
+ * `init` deliberately does not block when nobody is at the terminal — a 12-second wait in a script
+ * is wrong, and an agent driving `init` through a shell is never a TTY. But silence was the wrong
+ * other half of that decision: the agent path IS the prescribed path (every skill and every README
+ * block tells an agent to run exactly this command), so the one message joining "init finished" to
+ * "an app connected" was withheld from most of the people who run it. They were left with files on
+ * disk, an exit code of 0, and nothing saying the page half had not happened.
+ *
+ * It claims nothing it did not check. It did not look for a session, so it does not say whether one
+ * exists — a one-shot look would be worse than none, because a daemon is shared across every project
+ * on the machine and "a session exists" is satisfied by somebody else's app, which is the false
+ * green `confirmAppConnected` refuses by design.
+ */
+function unwatchedMessage(port) {
+    return ('  [ℹ] the files are written. An app CONNECTING is what finishes the install, and this run did ' +
+        'not wait to see one.\n' +
+        '      Start the dev server, load the app in a browser, then ' +
+        `${PROVE_COMMAND} — it confirms the app, or says exactly why it has not connected.\n` +
+        `      Bridge port ${String(port)}.`);
+}
+const WATCHING = (windowMs) => `  watching for an app to connect (up to ${String(Math.round(windowMs / 1000))}s) — Ctrl-C is safe, ` +
+    'everything above is already written.';
+/**
+ * Finish `init` on evidence rather than on a write.
+ *
+ * The telemetry report happens HERE rather than inside `runInit`, so the one `init_completed` event
+ * carries what was seen. Emitting inside `runInit` and again after the wait would double-count the
+ * funnel it exists to measure, and a second event kind for the same command would need joining back
+ * to the first before anybody could read either.
+ */
+export async function confirmInstall(result, io, deps, report = reportInitOutcome) {
+    const outcome = result.outcome;
+    // No outcome means a dry run or an exit that already reported for itself (no package.json). A
+    // preview is not an install and must not land in the funnel as either a success or a failure.
+    if (outcome === undefined)
+        return;
+    if (!deps.interactive) {
+        // Still no waiting — see unwatchedMessage for why it speaks anyway.
+        io.print('');
+        io.print(unwatchedMessage(deps.port));
+        report(outcome);
+        return;
+    }
+    io.print('');
+    io.print(WATCHING(deps.windowMs ?? CONFIRM_WINDOW_MS));
+    const observed = await confirmAppConnected(deps);
+    const running = deps.listDevServers?.() ?? [];
+    const confirmation = sharpenWithDevServers(observed, running);
+    io.print(confirmationMessage(confirmation, deps.port, running));
+    report({ ...outcome, confirmation });
+}
+/** The real deps: the daemon's own status endpoint, and whether a human is watching. */
+export function nodeConfirmDeps(port = RETICLE_DEFAULT_PORT) {
+    return {
+        // Scoped to the project being set up. The registry is machine-wide, so unscoped it reported a
+        // sibling app's dev server as this one's — see devServersForProject.
+        listDevServers: () => devServersForProject(readDevServers(reticleStateHome()), {
+            projectId: readProjectId(process.cwd()),
+            root: process.cwd(),
+        }),
+        listSessionIds: async () => {
+            const payload = await fetchStatus(port);
+            // `fetchStatus` resolves undefined when nothing answered, which is precisely the "no daemon"
+            // case — a zero-session daemon and an absent one need opposite messages.
+            if (payload === undefined)
+                return null;
+            return summarizeStatus(payload).sessions.map((s) => s.sessionId);
+        },
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        interactive: true === process.stdout.isTTY,
+        port,
+    };
+}

package/dist/command/setup/terminal/crash.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Take the dev server with us when setup crashes, and hand the user one sentence.
+ *
+ * The sibling of `interrupt.ts`, and for a related reason: a `finally` does not run when the
+ * process dies on an uncaught throw either, so a bug of ours left the detached dev server holding a
+ * port nobody could account for — and printed a raw Node stack trace on the way out.
+ *
+ * The prototype this phase was ported from had exactly this handler. It was not ported, and nothing
+ * noticed for one specific reason: the break-matrix scenario written to catch it
+ * (`a-bug-of-our-own-is-not-a-stack-trace`) was still aimed at the prototype, so it went on passing
+ * while the shipped CLI did the thing it forbids. A gate pointed at code nobody runs is not a gate.
+ *
+ * A bug of ours is still our bug — but it should arrive as one sentence, with the machine left
+ * tidy, and with whatever the caller is parsing still well formed.
+ */
+/** The parts of `process` this needs, so the behaviour is testable without throwing anything. */
+export interface CrashTarget {
+    on(event: 'uncaughtException' | 'unhandledRejection', handler: (err: unknown) => void): void;
+    off(event: 'uncaughtException' | 'unhandledRejection', handler: (err: unknown) => void): void;
+    exit(code: number): void;
+}
+/**
+ * Report a crash: `message` is one line safe to show, `stack` is for a file and never for a stream.
+ *
+ * Injected rather than written here, because where the trace lands is the caller's business — and
+ * because a handler that writes files is a handler nothing can test.
+ */
+export type CrashReporter = (message: string, stack: string) => void;
+/**
+ * How to report the crash, in the only form that works while the process is dying.
+ *
+ * The shell command, never `reticle_session { action: "feedback" }`: this handler runs BECAUSE
+ * Reticle is going down, so there is no daemon to accept a tool call and no session to file
+ * through. `feedback --agent` needs neither.
+ *
+ * The sentence used to end "Please report it." -- a wish with no call in it, which an agent cannot
+ * act on and a human has to go and look up. This is the moment a report is worth most: a defect in
+ * OUR code, in somebody else's project, held by an agent whose context is about to end.
+ */
+export declare const CRASH_REPORT_ASK: string;
+/**
+ * The one line a crash is allowed to print. Exported so it can be asserted without throwing.
+ *
+ * `hit a bug of its own` is load-bearing: the break-matrix scenario
+ * `a-bug-of-our-own-is-not-a-stack-trace` greps for exactly that, and it is what tells a reader
+ * this is not their fault before they start debugging their own project.
+ */
+export declare function crashSentence(message: string, crashLog: string): string;
+/**
+ * Run `stop`, report once, and leave with a failure code if this process dies of its own bug.
+ *
+ * Returns a disposer, and callers must use it: `init` keeps running after setup, and a handler left
+ * behind would tear down a server it no longer owns.
+ */
+export declare function stopOnCrash(stop: () => void, target: CrashTarget, report: CrashReporter): () => void;

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

@@ -0,0 +1,74 @@
+/**
+ * Take the dev server with us when setup crashes, and hand the user one sentence.
+ *
+ * The sibling of `interrupt.ts`, and for a related reason: a `finally` does not run when the
+ * process dies on an uncaught throw either, so a bug of ours left the detached dev server holding a
+ * port nobody could account for — and printed a raw Node stack trace on the way out.
+ *
+ * The prototype this phase was ported from had exactly this handler. It was not ported, and nothing
+ * noticed for one specific reason: the break-matrix scenario written to catch it
+ * (`a-bug-of-our-own-is-not-a-stack-trace`) was still aimed at the prototype, so it went on passing
+ * while the shipped CLI did the thing it forbids. A gate pointed at code nobody runs is not a gate.
+ *
+ * A bug of ours is still our bug — but it should arrive as one sentence, with the machine left
+ * tidy, and with whatever the caller is parsing still well formed.
+ */
+/**
+ * How to report the crash, in the only form that works while the process is dying.
+ *
+ * The shell command, never `reticle_session { action: "feedback" }`: this handler runs BECAUSE
+ * Reticle is going down, so there is no daemon to accept a tool call and no session to file
+ * through. `feedback --agent` needs neither.
+ *
+ * The sentence used to end "Please report it." -- a wish with no call in it, which an agent cannot
+ * act on and a human has to go and look up. This is the moment a report is worth most: a defect in
+ * OUR code, in somebody else's project, held by an agent whose context is about to end.
+ */
+export const CRASH_REPORT_ASK = 'Please report it — a crash is always our bug, and this is the one we most want to hear about: ' +
+    'npx @reticlehq/server feedback --agent --kind bug "what you ran, and the message above"';
+/**
+ * The one line a crash is allowed to print. Exported so it can be asserted without throwing.
+ *
+ * `hit a bug of its own` is load-bearing: the break-matrix scenario
+ * `a-bug-of-our-own-is-not-a-stack-trace` greps for exactly that, and it is what tells a reader
+ * this is not their fault before they start debugging their own project.
+ */
+export function crashSentence(message, crashLog) {
+    return (`reticle hit a bug of its own and stopped: ${message}. Anything it had already done is done, ` +
+        `and re-running is safe. The trace is in ${crashLog}. ${CRASH_REPORT_ASK}`);
+}
+/** Long enough to identify the fault, short enough that it cannot become the output. */
+const MESSAGE_MAX = 300;
+const FATAL = ['uncaughtException', 'unhandledRejection'];
+/** Anything can be thrown, so this takes `unknown` and never assumes a shape. */
+function oneLine(err) {
+    const raw = err instanceof Error ? err.message : String(err);
+    return (raw.split('\n')[0] ?? '').slice(0, MESSAGE_MAX);
+}
+/**
+ * Run `stop`, report once, and leave with a failure code if this process dies of its own bug.
+ *
+ * Returns a disposer, and callers must use it: `init` keeps running after setup, and a handler left
+ * behind would tear down a server it no longer owns.
+ */
+export function stopOnCrash(stop, target, report) {
+    // Once only, for the reason `stopOnInterrupt` states: `stop` kills a process GROUP, and on a
+    // recycled pid a second kill is somebody else's process. Both fatals can fire for one fault.
+    let done = false;
+    const handlers = FATAL.map((event) => {
+        const handler = (err) => {
+            if (!done) {
+                done = true;
+                stop();
+                report(oneLine(err), String(err instanceof Error ? (err.stack ?? err.message) : err));
+            }
+            target.exit(1);
+        };
+        target.on(event, handler);
+        return { event, handler };
+    });
+    return () => {
+        for (const { event, handler } of handlers)
+            target.off(event, handler);
+    };
+}

package/dist/command/update/nudge-credit.js

@@ -0,0 +1,53 @@
+/**
+ * Did the update nudge cause the update?
+ *
+ * `version_changed` says a version moved. It has never said why, so the only question worth asking
+ * about the nudge — does telling agents about a release make releases get installed — was
+ * unanswerable. That is not academic: a release once carried a fix for a connect defect affecting
+ * every Vite app and went essentially unadopted, and nothing in the data could distinguish "the
+ * nudge never fired" from "the nudge fired and nobody acted on it". Those need opposite responses.
+ *
+ * The nudge is delivered by a DAEMON; `reticle update` runs in a different process. They cannot see
+ * each other in memory, so a marker file is the join. It holds the version that was offered and
+ * when — no identity, nothing about the machine, and it is overwritten rather than appended.
+ *
+ * Every function here swallows its own errors. This runs inside `reticle update`, which must finish
+ * whatever the telemetry believes.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const DEFAULT_DIR = join(homedir(), '.reticle');
+const FILE = 'update-nudge.json';
+/**
+ * How long a nudge can plausibly have caused an update. A week is generous for "the agent mentioned
+ * it and the human got round to it"; beyond that the two are unrelated events that happen to share a
+ * version number.
+ */
+const CREDIT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/** Record that an agent was told about `version`. Called when the nudge is actually delivered. */
+export function creditNudge(version, dir = DEFAULT_DIR, now = Date.now()) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const record = { offered: version, at: now };
+        writeFileSync(join(dir, FILE), JSON.stringify(record), 'utf8');
+    }
+    catch {
+        /* a metric must never break the nudge */
+    }
+}
+/** True when this exact version was offered to an agent recently enough to have caused the update. */
+export function wasNudged(version, dir = DEFAULT_DIR, now = Date.now()) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, FILE), 'utf8'));
+        if (typeof parsed !== 'object' || null === parsed)
+            return false;
+        const record = parsed;
+        if (record.offered !== version || typeof record.at !== 'number')
+            return false;
+        return now - record.at <= CREDIT_WINDOW_MS;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/command/update/sdk-sync.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The half of `reticle update` that was missing: bringing the APP's SDK to the same version as the
+ * daemon being installed.
+ *
+ * `reticle update` swapped the CLI and stopped. The app kept whatever `@reticlehq/react` it had, so
+ * the command whose job is to keep an install current was itself a way to create a version-skewed
+ * pair — the failure the HELLO skew check, the nudge and the pin all exist to prevent. The skew
+ * message even told people to run `reticle update` to fix an outdated SDK, which could not work.
+ *
+ * Pinned to an exact version for the same reason `init` pins: an unpinned `add` can resolve out of a
+ * stale registry cache and reinstall the skew being fixed — two package managers on one machine can
+ * resolve the same unpinned range to different releases.
+ */
+import { type PackageManager } from '@reticlehq/init';
+export { reticleDepsOf } from '../../memory/project/reticle-deps.js';
+/** The install to run, or null when this project has nothing of ours to sync. */
+export declare function sdkSyncCommand(pm: PackageManager, packages: readonly string[], version: string): {
+    command: string;
+    args: string[];
+} | null;

package/dist/command/update/sdk-sync.js

@@ -0,0 +1,22 @@
+/**
+ * The half of `reticle update` that was missing: bringing the APP's SDK to the same version as the
+ * daemon being installed.
+ *
+ * `reticle update` swapped the CLI and stopped. The app kept whatever `@reticlehq/react` it had, so
+ * the command whose job is to keep an install current was itself a way to create a version-skewed
+ * pair — the failure the HELLO skew check, the nudge and the pin all exist to prevent. The skew
+ * message even told people to run `reticle update` to fix an outdated SDK, which could not work.
+ *
+ * Pinned to an exact version for the same reason `init` pins: an unpinned `add` can resolve out of a
+ * stale registry cache and reinstall the skew being fixed — two package managers on one machine can
+ * resolve the same unpinned range to different releases.
+ */
+import { installCommandParts } from '@reticlehq/init';
+export { reticleDepsOf } from '../../memory/project/reticle-deps.js';
+/** The install to run, or null when this project has nothing of ours to sync. */
+export function sdkSyncCommand(pm, packages, version) {
+    if (0 === packages.length)
+        return null;
+    const { command, args } = installCommandParts(pm, packages.map((p) => `${p}@${version}`));
+    return { command, args: [...args] };
+}

package/dist/command/update/update-checker.js

@@ -0,0 +1,122 @@
+import * as fs from 'node:fs';
+import * as https from 'node:https';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { UpdateCheckIntervalMs } from '@reticlehq/core';
+import { RETICLE_NPM_PACKAGE } from '../version/identity/server-version.js';
+import { log } from '../../log.js';
+const RETICLE_HOME = join(homedir(), '.reticle');
+const MANIFEST_PATH = join(RETICLE_HOME, 'update-manifest.json');
+// Poll the package that carries the bin (@reticlehq/server), so the version we compare against and
+// the version we install are the same package — not @reticlehq/core, which only tracks it by luck.
+const NPM_REGISTRY = `https://registry.npmjs.org/${RETICLE_NPM_PACKAGE}/latest`;
+// npm's registry is trusted, but this response is persisted to disk AND echoed into the agent's
+// context, so validate its shape before it flows anywhere: a plausible semver, bounded free-text.
+const VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/;
+const MAX_MANIFEST_TEXT = 20_000;
+/** Reject an implausible version (throws → caller falls back to cache) and bound the free-text
+ * fields, so a malformed or oversized registry response can neither corrupt nor bloat the manifest. */
+function validateNpmInfo(info) {
+    if (typeof info.version !== 'string' || !VERSION_RE.test(info.version)) {
+        throw new Error('npm registry returned an implausible version');
+    }
+    const changelog = 'string' === typeof info.reticle?.changelog
+        ? info.reticle.changelog.slice(0, MAX_MANIFEST_TEXT)
+        : undefined;
+    const breakingChanges = Array.isArray(info.reticle?.breakingChanges)
+        ? info.reticle.breakingChanges
+            .filter((x) => 'string' === typeof x)
+            .slice(0, 100)
+            .map((s) => s.slice(0, MAX_MANIFEST_TEXT))
+        : undefined;
+    const reticle = {
+        ...(changelog !== undefined ? { changelog } : {}),
+        ...(breakingChanges !== undefined ? { breakingChanges } : {}),
+    };
+    return { version: info.version, reticle };
+}
+export function loadManifest() {
+    if (!fs.existsSync(MANIFEST_PATH))
+        return null;
+    try {
+        const raw = fs.readFileSync(MANIFEST_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveManifest(manifest) {
+    fs.mkdirSync(RETICLE_HOME, { recursive: true });
+    fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2), 'utf8');
+}
+function isCacheFresh(manifest, now) {
+    const checked = new Date(manifest.lastChecked).getTime();
+    return now() - checked < UpdateCheckIntervalMs;
+}
+function fetchNpmInfo() {
+    return new Promise((resolve, reject) => {
+        const req = https.get(NPM_REGISTRY, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => {
+                body += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch (err) {
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+            res.on('error', reject);
+        });
+        req.setTimeout(5000, () => {
+            req.destroy();
+            reject(new Error('npm registry request timed out'));
+        });
+        req.on('error', reject);
+    });
+}
+const defaultPorts = { fetchInfo: fetchNpmInfo, loadManifest, saveManifest };
+/**
+ * Returns the current update manifest, refreshing from the npm registry when the cache
+ * is older than UpdateCheckIntervalMs. Never throws — falls back to the cached manifest
+ * (or a safe "no update" default) when the registry is unreachable.
+ */
+export async function checkForUpdate(currentVersion, now, ports = defaultPorts) {
+    const cached = ports.loadManifest();
+    if (cached !== null && cached.currentVersion === currentVersion && isCacheFresh(cached, now)) {
+        return cached;
+    }
+    try {
+        const info = validateNpmInfo(await ports.fetchInfo());
+        const updateAvailable = info.version !== currentVersion;
+        const manifest = {
+            currentVersion,
+            latestVersion: info.version,
+            updateAvailable,
+            lastChecked: new Date(now()).toISOString(),
+            ...(info.reticle?.changelog !== undefined ? { changelog: info.reticle.changelog } : {}),
+            ...(info.reticle?.breakingChanges !== undefined
+                ? { breakingChanges: info.reticle.breakingChanges }
+                : {}),
+            ...(cached?.previousVersion !== undefined ? { previousVersion: cached.previousVersion } : {}),
+        };
+        ports.saveManifest(manifest);
+        return manifest;
+    }
+    catch (err) {
+        log('reticle_update_check_failed', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        if (cached !== null)
+            return { ...cached, currentVersion };
+        return {
+            currentVersion,
+            updateAvailable: false,
+            lastChecked: new Date(now()).toISOString(),
+        };
+    }
+}

package/dist/command/update/update-nudge.d.ts

@@ -0,0 +1,90 @@
+interface UpdateNudge {
+    /** The version available, so the agent can tell the human what they would be moving to. */
+    latestVersion: string;
+    currentVersion: string;
+    /** The exact command. Spelled out so the agent never has to guess or invent one. */
+    command: string;
+    action: string;
+}
+/**
+ * Describe the release, not just its number.
+ *
+ * `server/package.json` carries `reticle.changelog` and `reticle.breakingChanges`, and
+ * `update-checker` parses both into the manifest — where they stopped. This function named two
+ * versions and nothing else, so both fields were written, shipped, parsed and discarded. Latent
+ * metadata nobody ever printed.
+ *
+ * Survivable while releases are additive; actively harmful for one that is not. An agent told only
+ * the two version numbers runs `reticle update` mid-task and discovers a retired environment variable and
+ * six newly-strict parameters by breaking on them.
+ *
+ * Bounded on purpose: this rides on a tool result every turn until it is delivered, so a long
+ * changelog is a per-turn tax. The count of anything elided is stated rather than silently dropped.
+ *
+ * It also names what `update` does to the RULE FILES, which is the half nobody would guess. A new
+ * release changes what the always-loaded instructions should say — that is the whole reason
+ * `refreshAgentRules` exists — and an agent that reads "it restarts the daemon" has no reason to
+ * think its CLAUDE.md is now a release behind. Saying so costs one clause on a message that is
+ * delivered once per daemon, and it is the difference between a fleet that upgrades its rules and
+ * one that upgrades its binary and keeps last release's instructions forever.
+ */
+export declare function buildNudge(latestVersion: string, currentVersion: string, release?: {
+    changelog?: string;
+    breakingChanges?: string[];
+}): UpdateNudge;
+export declare function startUpdateCheck(now?: () => number): void;
+/**
+ * What `reticle update` should install, or undefined when it should do nothing.
+ *
+ * `handleUpdate` gated on `manifest.updateAvailable`, a plain `latest !== current`, so whenever the
+ * registry's latest was OLDER than the running build — a prerelease, a local build, a rollback in
+ * progress, a stale npx cache — it announced the move and then installed the downgrade. Reported by
+ * a real user on 2026-08-06: "both the `update_available` banner and `reticle update` report the
+ * current and target versions swapped, so an upgrade is described as a downgrade."
+ */
+export declare function updateTarget(manifest: {
+    updateAvailable?: boolean;
+    latestVersion?: string;
+}, currentVersion?: string): string | undefined;
+/**
+ * Arm from an already-cached answer, synchronously, at daemon boot.
+ *
+ * The network check fires 8s after boot and the nudge is delivered by riding a tool result — but
+ * half the sessions that use Reticle at all make exactly ONE tool call, usually in the first
+ * seconds. The check had not finished, so the single chance to tell them was gone, and the
+ * population most in need of the update is precisely the one that never heard about it. Yesterday's
+ * answer is already on disk; use it now and let the network refresh behind it.
+ */
+export declare function armUpdateNudgeFrom(cached: {
+    latestVersion?: string;
+    updateAvailable?: boolean;
+    changelog?: string;
+    breakingChanges?: string[];
+} | null, currentVersion?: string): void;
+/** The nudge, once. Returns undefined afterwards so a long session is told exactly one time. */
+export declare function takeUpdateNudge(): UpdateNudge | undefined;
+/**
+ * The newer version, if the cached answer says there is one — WITHOUT consuming the agent's
+ * one-shot nudge. `reticle status` is a human reading a terminal; the two channels are separate
+ * audiences and must not steal each other's message.
+ */
+export declare function availableUpdate(currentVersion?: string): string | undefined;
+/**
+ * What the nudge did this daemon run, for the session summary.
+ *
+ * Without this, "did the agent get told about a release, and did anything happen" is unanswerable:
+ * `versionChange.nudged` is the half that only ever arrives from machines that DID update.
+ *
+ * Reads the same module state the delivery path uses rather than adding a counter beside it, so the
+ * two cannot disagree. `shown` is the one-shot delivery flag: it means "an agent was told", never
+ * how often. `offered` is present whenever a newer release was known, whether or not it was
+ * delivered — without it, `shown: false` would mean "nothing was available" and "something was and
+ * the nudge did not fire" at the same time, and only one of those is a defect.
+ */
+export declare function updateNudgeState(): {
+    shown: boolean;
+    offered?: string;
+};
+/** Tests only — drop the module state so each case starts clean. */
+export declare function resetUpdateNudge(): void;
+export {};