@reticlehq/server 2.4.0 → 2.5.0

package/dist/trace.js

@@ -0,0 +1,150 @@
+/**
+ * Verbose internal flow tracing, for people working ON Reticle.
+ *
+ * The gap it fills: the journal records what the AGENT did to the app, and telemetry records
+ * aggregates. Neither says which of OUR code a tool call went through, in what order, or where the
+ * time went — so every "why is this flow slow" and "which path produced this verdict" was
+ * reconstructed by hand from reading source. One line per stage answers both.
+ *
+ * Design, in order of what it cost to get wrong elsewhere in this repo:
+ *
+ *  - OFF by default, and ~126ns per site when off (measured) — `span` calls the function and
+ *    returns. A trace on every tool call is a real cost on the hot path, and the hot path is a
+ *    verification loop of 50–200 calls.
+ *  - ONE line per stage, emitted when it ENDS, carrying its own duration. A start line as well
+ *    would double the volume to say something the end line already implies.
+ *  - Correlated by a call id and a depth, carried in AsyncLocalStorage rather than threaded through
+ *    every signature. Several agents are inside `runTool` at once — interleaving is the normal case
+ *    — so without an id the output is a pile of unrelated lines, and instrumenting anything would
+ *    mean changing its parameters, which is how instrumentation stops being added.
+ *  - Through the existing `log()`, so it lands in the same stderr stream the daemon already
+ *    redirects to `~/.reticle/daemon-<port>.log`. No new sink, no new file, nothing else to tail.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ReticleEnv } from '@reticlehq/core';
+import { log } from './log.js';
+/** The `event` field every trace line carries, so one `grep` separates it from milestone logs. */
+const TRACE_EVENT = 'trace';
+const ON_VALUES = new Set(['1', 'true', 'on', 'yes']);
+const context = new AsyncLocalStorage();
+/**
+ * Monotonic within a process, and PID-qualified so it stays unique across them.
+ *
+ * A bare counter was not enough: the e2e battery runs many daemons, and a restarted daemon starts
+ * over at 1, so `c7` named a different call in every process. Aggregating that trace silently
+ * merged unrelated calls into one — measured on the first real trace collected, before it had a
+ * chance to mislead anything.
+ */
+let nextCallId = 0;
+const CALL_ID_PREFIX = `p${String(process.pid)}-c`;
+/**
+ * Whether tracing is on.
+ *
+ * Read per call, not cached at import, and the reason is `loadDotEnv`: the CLI populates
+ * `process.env` from the project's .env AFTER every module has been imported, so a value captured at
+ * import time would miss a `RETICLE_TRACE` set there — silently, which is the worst way for a
+ * diagnostic switch to fail. (The reason originally given here — "so it can be turned on while the
+ * daemon runs" — was wrong: nothing outside a process can change its environment.)
+ *
+ * Measured cost of reading it per call: 126ns per traced site when tracing is OFF, against a ~9ns
+ * bare call. With a handful of spans per tool call that is under a microsecond on a call that takes
+ * milliseconds — cheap enough to be worth the correctness, and not the literal zero this comment
+ * used to imply.
+ */
+export function traceEnabled() {
+    const raw = process.env[ReticleEnv.TRACE];
+    return raw !== undefined && ON_VALUES.has(raw.trim().toLowerCase());
+}
+/** The scope a stage runs in, plus how to report it. Shared by the async and sync forms. */
+function openSpan(name, fields) {
+    const parent = context.getStore();
+    const scope = parent === undefined
+        ? { callId: `${CALL_ID_PREFIX}${String((nextCallId += 1))}`, depth: 0 }
+        : parent;
+    const depth = parent === undefined ? 0 : parent.depth;
+    const startedAt = Date.now();
+    return {
+        // The child scope is what nested spans see: same call, one level deeper.
+        child: { callId: scope.callId, depth: depth + 1 },
+        emit: (ok, extra) => {
+            log(TRACE_EVENT, {
+                span: name,
+                ms: Date.now() - startedAt,
+                depth,
+                callId: scope.callId,
+                ok,
+                ...fields,
+                ...extra,
+            });
+        },
+    };
+}
+/**
+ * Bind a callback to the call that is running NOW, so it reports inside that call when it fires later.
+ *
+ * `waitForPredicate` re-checks its predicate from a WebSocket event listener and an interval. Neither
+ * is in the awaited chain, so AsyncLocalStorage does not reach them and every re-check used to open a
+ * brand new call at depth 0. Measured on one healthy run: 165 spans across 60 callIds, 25 of them a
+ * `browser.command` with no matching `tool.handler`.
+ *
+ * That is not cosmetic. The documented signature of a HUNG tool call is exactly "a browser.command
+ * with no tool.handler for that callId, ever" — the invariant that located a real hang. A clean run
+ * emitting 23 of them makes the invariant unusable and hides the next hang in its own noise.
+ *
+ * Returns `fn` unchanged when there is no call to bind to, so a caller outside a span is not given a
+ * fabricated parent.
+ */
+export function bindSpanContext(fn) {
+    const captured = context.getStore();
+    if (captured === undefined)
+        return fn;
+    return (...args) => {
+        context.run(captured, () => fn(...args));
+    };
+}
+/** How much of a thrown value to keep. Enough to identify it, not enough to paste a stack into a log. */
+const ERROR_CHARS = 300;
+/**
+ * Run `fn` as a named stage, recording how long it took and how it sat inside the call around it.
+ *
+ * Wrap a stage worth a line in a bottleneck hunt — a session resolve, a browser round-trip, a
+ * predicate evaluation — not every function. The value of the trace is that reading it is faster
+ * than reading the code, and that stops being true somewhere around one line per statement.
+ */
+export async function span(name, fields, fn) {
+    if (!traceEnabled())
+        return fn();
+    const { child, emit } = openSpan(name, fields);
+    try {
+        const value = await context.run(child, async () => fn());
+        emit(true, {});
+        return value;
+    }
+    catch (err) {
+        // A stage that THREW is the one most worth having in the trace: without this line the trace
+        // shows a call that entered a stage and never left it, which reads as a hang.
+        emit(false, { error: String(err).slice(0, ERROR_CHARS) });
+        throw err;
+    }
+}
+/**
+ * The synchronous form. Same line, same tree, same cost when off.
+ *
+ * It exists because `reticle init` — the flow every user hits before anything else, and the one
+ * whose slowness they experience personally — is synchronous end to end. An async-only span left
+ * exactly that flow untraceable.
+ */
+export function spanSync(name, fields, fn) {
+    if (!traceEnabled())
+        return fn();
+    const { child, emit } = openSpan(name, fields);
+    try {
+        const value = context.run(child, fn);
+        emit(true, {});
+        return value;
+    }
+    catch (err) {
+        emit(false, { error: String(err).slice(0, ERROR_CHARS) });
+        throw err;
+    }
+}

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

@@ -0,0 +1,4 @@
+/** Record that an agent was told about `version`. Called when the nudge is actually delivered. */
+export declare function creditNudge(version: string, dir?: string, now?: number): void;
+/** True when this exact version was offered to an agent recently enough to have caused the update. */
+export declare function wasNudged(version: string, dir?: string, now?: number): boolean;

package/dist/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: 2.4.0 carried a fix for a connect defect affecting every Vite
+ * app and reached zero users, 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/update/sdk-sync.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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. Measured once as pnpm taking 2.2.1 while
+ * npm took 2.3.0 in the next project over.
+ */
+import { type PackageManager } from '../init/detect.js';
+/** The Reticle packages this project declares, from either dependency section. */
+export declare function reticleDepsOf(pkgJson: unknown): string[];
+/** 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/update/sdk-sync.js

@@ -0,0 +1,42 @@
+/**
+ * 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. Measured once as pnpm taking 2.2.1 while
+ * npm took 2.3.0 in the next project over.
+ */
+import { installCommandParts } from '../init/detect.js';
+/** Everything we publish is scoped here. */
+const RETICLE_SCOPE = '@reticlehq/';
+/**
+ * The CLI. Never an app dependency: it carries the Node MCP server and `ws`, and putting it in a
+ * browser app's tree is what the retired `@reticlehq/core` umbrella got wrong. The other half of
+ * `reticle update` owns this one.
+ */
+const SERVER_PACKAGE = '@reticlehq/server';
+function namesIn(section) {
+    if ('object' !== typeof section || null === section)
+        return [];
+    return Object.keys(section);
+}
+/** The Reticle packages this project declares, from either dependency section. */
+export function reticleDepsOf(pkgJson) {
+    if ('object' !== typeof pkgJson || null === pkgJson)
+        return [];
+    const manifest = pkgJson;
+    const declared = [...namesIn(manifest['dependencies']), ...namesIn(manifest['devDependencies'])];
+    return [...new Set(declared)].filter((name) => name.startsWith(RETICLE_SCOPE) && name !== SERVER_PACKAGE);
+}
+/** 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/update/update-checker.js

@@ -3,7 +3,7 @@ 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 '../server-version.js';
+import { RETICLE_NPM_PACKAGE } from '../version/server-version.js';
 import { log } from '../log.js';
 const RETICLE_HOME = join(homedir(), '.reticle');
 const MANIFEST_PATH = join(RETICLE_HOME, 'update-manifest.json');
@@ -20,12 +20,12 @@ function validateNpmInfo(info) {
     if (typeof info.version !== 'string' || !VERSION_RE.test(info.version)) {
         throw new Error('npm registry returned an implausible version');
     }
-    const changelog = typeof info.reticle?.changelog === 'string'
+    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) => typeof x === 'string')
+            .filter((x) => 'string' === typeof x)
             .slice(0, 100)
             .map((s) => s.slice(0, MAX_MANIFEST_TEXT))
         : undefined;

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

@@ -1,4 +1,14 @@
-export interface UpdateNudge {
+/**
+ * Is `candidate` a strictly NEWER release than `current`?
+ *
+ * Replaces a plain `!==`, which told anyone on a version newer than the published one — a
+ * prerelease, a local build, a rollback in progress — to "update" to something older. A nudge that
+ * prompts a downgrade is one people learn to ignore, and this is the mechanism the entire adoption
+ * story rests on. Numeric per segment, so 2.10.0 correctly beats 2.9.0 (string order does not), and
+ * a bare release beats its own prerelease.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+interface UpdateNudge {
     /** The version available, so the agent can tell the human what they would be moving to. */
     latestVersion: string;
     currentVersion: string;
@@ -7,14 +17,61 @@ export interface UpdateNudge {
     action: string;
 }
 /**
- * Kick off a background check. Non-blocking and best-effort: `checkForUpdate` never throws, caches
- * for 24h on disk, and falls back to the cached manifest when the registry is unreachable — so this
- * costs one npm registry request per day per machine, and nothing at all when offline.
+ * Describe the release, not just its number.
+ *
+ * `packages/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
+ * "2.4.1 → 2.5.0" 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.
  */
+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;
 /** Tests only — drop the module state so each case starts clean. */
 export declare function resetUpdateNudge(): void;
-/** Tests only — seed a pending nudge without going near the network. */
-export declare function setPendingUpdate(nudge: UpdateNudge | undefined): void;
+export {};

package/dist/update/update-nudge.js

@@ -16,9 +16,35 @@
  * human never agreed to interrupt. So the envelope carries the fact and the exact command, and the
  * decision stays with the people whose machine it is.
  */
-import { checkForUpdate } from './update-checker.js';
-import { SERVER_VERSION } from '../server-version.js';
+import { checkForUpdate, loadManifest } from './update-checker.js';
+import { SERVER_VERSION } from '../version/server-version.js';
 import { log } from '../log.js';
+import { creditNudge } from './nudge-credit.js';
+/**
+ * Is `candidate` a strictly NEWER release than `current`?
+ *
+ * Replaces a plain `!==`, which told anyone on a version newer than the published one — a
+ * prerelease, a local build, a rollback in progress — to "update" to something older. A nudge that
+ * prompts a downgrade is one people learn to ignore, and this is the mechanism the entire adoption
+ * story rests on. Numeric per segment, so 2.10.0 correctly beats 2.9.0 (string order does not), and
+ * a bare release beats its own prerelease.
+ */
+export function isNewerVersion(candidate, current) {
+    const parse = (v) => {
+        const [core = '', ...rest] = v.split(/[-+]/);
+        return { parts: core.split('.').map((n) => Number.parseInt(n, 10) || 0), pre: rest.length > 0 };
+    };
+    const a = parse(candidate);
+    const b = parse(current);
+    for (let i = 0; i < 3; i++) {
+        const left = a.parts[i] ?? 0;
+        const right = b.parts[i] ?? 0;
+        if (left !== right)
+            return left > right;
+    }
+    // Same numbers: a final release is newer than its own prerelease, and nothing else counts.
+    return !a.pre && b.pre;
+}
 /** Let the daemon finish coming up before touching the network. */
 const CHECK_DELAY_MS = 8_000;
 const UPDATE_COMMAND = 'reticle update';
@@ -29,20 +55,63 @@ let delivered = false;
  * for 24h on disk, and falls back to the cached manifest when the registry is unreachable — so this
  * costs one npm registry request per day per machine, and nothing at all when offline.
  */
+/** How much of the release description may ride on a tool result. See buildNudge. */
+const MAX_CHANGELOG_CHARS = 240;
+const MAX_LISTED_BREAKING = 4;
+/**
+ * Describe the release, not just its number.
+ *
+ * `packages/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
+ * "2.4.1 → 2.5.0" 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.
+ */
+export function buildNudge(latestVersion, currentVersion, release) {
+    const changelog = (release?.changelog ?? '').trim();
+    const breaking = (release?.breakingChanges ?? []).filter((line) => 0 < line.trim().length);
+    const listed = breaking.slice(0, MAX_LISTED_BREAKING);
+    const rest = breaking.length - listed.length;
+    return {
+        currentVersion,
+        latestVersion,
+        command: UPDATE_COMMAND,
+        action: `A newer Reticle is available (${currentVersion} → ${latestVersion}). ` +
+            ('' === changelog ? '' : `${changelog.slice(0, MAX_CHANGELOG_CHARS)} `) +
+            (0 === breaking.length
+                ? ''
+                : `This release has BREAKING changes: ${listed.join('; ')}` +
+                    (0 < rest ? ` (+${String(rest)} more — see the changelog)` : '') +
+                    '. Read them before updating. ') +
+            `Tell the human, and run \`${UPDATE_COMMAND}\` if they agree — it restarts the daemon, ` +
+            'so do it between tasks rather than mid-verification. Continue your current task first.',
+    };
+}
 export function startUpdateCheck(now = () => Date.now()) {
+    // The cached answer first, so the very first tool call can carry it — see armUpdateNudgeFrom.
+    armUpdateNudgeFrom(loadManifest());
     setTimeout(() => {
         void checkForUpdate(SERVER_VERSION, now)
             .then((manifest) => {
             if (!manifest.updateAvailable || manifest.latestVersion === undefined)
                 return;
-            pending = {
-                currentVersion: SERVER_VERSION,
-                latestVersion: manifest.latestVersion,
-                command: UPDATE_COMMAND,
-                action: `A newer Reticle is available (${SERVER_VERSION} → ${manifest.latestVersion}). ` +
-                    `Tell the human, and run \`${UPDATE_COMMAND}\` if they agree — it restarts the daemon, ` +
-                    'so do it between tasks rather than mid-verification. Continue your current task first.',
-            };
+            if (!isNewerVersion(manifest.latestVersion, SERVER_VERSION))
+                return;
+            // WITH the release description. The manifest has carried `changelog` and `breakingChanges`
+            // all along; nothing read them.
+            pending = buildNudge(manifest.latestVersion, SERVER_VERSION, {
+                ...(manifest.changelog === undefined ? {} : { changelog: manifest.changelog }),
+                ...(manifest.breakingChanges === undefined
+                    ? {}
+                    : { breakingChanges: manifest.breakingChanges }),
+            });
+            delivered = false;
             log('reticle_update_available', {
                 from: SERVER_VERSION,
                 to: manifest.latestVersion,
@@ -53,20 +122,64 @@ export function startUpdateCheck(now = () => Date.now()) {
         });
     }, CHECK_DELAY_MS).unref();
 }
+/**
+ * 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 function updateTarget(manifest, currentVersion = SERVER_VERSION) {
+    const latest = manifest.latestVersion;
+    if (latest === undefined || !isNewerVersion(latest, currentVersion))
+        return undefined;
+    return latest;
+}
+/**
+ * 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 function armUpdateNudgeFrom(cached, currentVersion = SERVER_VERSION) {
+    const latest = cached?.latestVersion;
+    if (latest === undefined || !isNewerVersion(latest, currentVersion))
+        return;
+    // The CACHED path matters more than the live one: it is what the very first tool call carries, and
+    // it is the only nudge an offline machine ever sees. Dropping the release description here would
+    // have left the fields unread on the commonest path while looking fixed.
+    pending = buildNudge(latest, currentVersion, {
+        ...(cached?.changelog === undefined ? {} : { changelog: cached.changelog }),
+        ...(cached?.breakingChanges === undefined ? {} : { breakingChanges: cached.breakingChanges }),
+    });
+    delivered = false;
+}
 /** The nudge, once. Returns undefined afterwards so a long session is told exactly one time. */
 export function takeUpdateNudge() {
     if (delivered || pending === undefined)
         return undefined;
     delivered = true;
+    // Leave a mark an `reticle update` in another process can read, so version_changed can say whether
+    // this nudge is what caused the upgrade. Best-effort by construction — see nudge-credit.
+    creditNudge(pending.latestVersion);
     return pending;
 }
+/**
+ * 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 function availableUpdate(currentVersion = SERVER_VERSION) {
+    const latest = loadManifest()?.latestVersion;
+    return latest !== undefined && isNewerVersion(latest, currentVersion) ? latest : undefined;
+}
 /** Tests only — drop the module state so each case starts clean. */
 export function resetUpdateNudge() {
     pending = undefined;
     delivered = false;
 }
-/** Tests only — seed a pending nudge without going near the network. */
-export function setPendingUpdate(nudge) {
-    pending = nudge;
-    delivered = false;
-}

package/dist/update/updater.d.ts

@@ -1,5 +1,5 @@
 /** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */
-export declare const VersionChangeDirection: {
+declare const VersionChangeDirection: {
     readonly UPDATE: "update";
     readonly ROLLBACK: "rollback";
 };
@@ -22,14 +22,6 @@ declare const ExecutionKind: {
     readonly LOCAL: "local";
 };
 type ExecutionKind = (typeof ExecutionKind)[keyof typeof ExecutionKind];
-/**
- * Infer how reticle was launched from process.argv[1].
- *
- * npm's npx cache stores packages under a path containing `_npx`, which is the
- * most reliable cross-platform signal. Local installs always live inside a
- * `node_modules` directory. Everything else is treated as a global install.
- */
-export declare function detectExecutionKind(): ExecutionKind;
 /**
  * Classify a launch from the entry script path. Pure so it's testable. Global installs ALSO live under
  * a `node_modules`, but under the npm global prefix — a `lib/node_modules` (unix: /usr/local, Homebrew,

package/dist/update/updater.js

@@ -1,14 +1,16 @@
 import { execFile } from 'node:child_process';
+import { NodePlatform } from '../platform.js';
 import { existsSync } from 'node:fs';
 import { platform } from 'node:os';
 import { dirname, join } from 'node:path';
 import { loadManifest, saveManifest } from './update-checker.js';
-import { RETICLE_NPM_PACKAGE, SERVER_VERSION } from '../server-version.js';
+import { RETICLE_NPM_PACKAGE, SERVER_VERSION } from '../version/server-version.js';
 import { log } from '../log.js';
 import { TelemetryEventKind } from '@reticlehq/core';
 import { getTelemetry } from '../telemetry/telemetry.js';
+import { wasNudged } from './nudge-credit.js';
 /** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */
-export const VersionChangeDirection = {
+const VersionChangeDirection = {
     UPDATE: 'update',
     ROLLBACK: 'rollback',
 };
@@ -21,15 +23,18 @@ export const VersionChangeDirection = {
  */
 export async function reportVersionChange(from, to, direction) {
     try {
+        const nudged = wasNudged(to);
         await getTelemetry().emit(TelemetryEventKind.VERSION_CHANGED, {
-            versionChange: { from, to, direction },
+            // Only when true: an absent flag reads as "we do not know", which is honest for a machine that
+            // updated from a shell script or a package bump with no agent involved at all.
+            versionChange: { from, to, direction, ...(nudged ? { nudged } : {}) },
         });
     }
     catch {
         /* best-effort, like every other send */
     }
 }
-const NPM_BIN = platform() === 'win32' ? 'npm.cmd' : 'npm';
+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 = {
@@ -47,7 +52,7 @@ const ExecutionKind = {
  * most reliable cross-platform signal. Local installs always live inside a
  * `node_modules` directory. Everything else is treated as a global install.
  */
-export function detectExecutionKind() {
+function detectExecutionKind() {
     return classifyExecutionKind(process.argv[1] ?? '');
 }
 /**
@@ -116,7 +121,7 @@ export function installArgs(version, kind, localRoot) {
 async function installVersion(version, kind) {
     const localRoot = kind === ExecutionKind.LOCAL ? findLocalProjectRoot() : null;
     const plan = installArgs(version, kind, localRoot);
-    if (plan === null) {
+    if (null === plan) {
         // npx re-resolves the package from npm on the next Claude Code restart — no npm
         // install needed. The restart itself is what triggers the update.
         log('reticle_update_npx_strategy', {
@@ -124,7 +129,7 @@ async function installVersion(version, kind) {
         });
         return;
     }
-    if (kind === ExecutionKind.LOCAL && localRoot === null) {
+    if (kind === ExecutionKind.LOCAL && null === localRoot) {
         // Could not find a project root — fell back to a global install as a safe default.
         log('reticle_update_local_no_root', { fallback: 'global' });
     }
@@ -166,7 +171,7 @@ export async function applyUpdate(targetVersion) {
  */
 export async function rollback() {
     const manifest = loadManifest();
-    if (manifest === null || manifest.previousVersion === undefined) {
+    if (null === manifest || manifest.previousVersion === undefined) {
         throw new Error('No previous version available for rollback');
     }
     const prev = manifest.previousVersion;