@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,211 @@
+/**
+ * Telling the agent that a newer Reticle exists.
+ *
+ * Until now nothing did. `checkForUpdate` had exactly one caller — the `reticle update` command — so
+ * a published release was invisible to every install until a human happened to type that command,
+ * which in practice meant never. A fix could ship and sit unused for months on the machines that hit
+ * the bug it fixed.
+ *
+ * The nudge rides the tool-result envelope rather than being a tool of its own, for the same reason
+ * the session-health and pool-lease reminders do: the agent is mid-task, and something it has to go
+ * and ASK for is something it will not ask for. Delivered ONCE per daemon process — a repeated
+ * "please update" during someone's work is noise, and noise is what gets filtered out.
+ *
+ * It deliberately does NOT update anything by itself. A silent self-install would swap the binary
+ * under a running session, restart the daemon, and drop every agent attached to it — during work the
+ * 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, loadManifest } from './update-checker.js';
+import { SERVER_VERSION } from '../version/identity/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. Numeric per segment, so a 10 patch correctly
+ * beats a 9 (string order does not), and a bare release beats its own prerelease.
+ */
+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';
+let pending;
+let delivered = false;
+/**
+ * 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.
+ */
+/** 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.
+ *
+ * `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 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 upgrades the packages, ` +
+            "refreshes the Reticle rules in this project's CLAUDE.md / AGENTS.md, and 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;
+            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,
+            });
+        })
+            .catch(() => {
+            /* a version check must never surface to a user */
+        });
+    }, 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;
+}
+/**
+ * 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 function updateNudgeState() {
+    return {
+        shown: delivered,
+        ...(pending === undefined ? {} : { offered: pending.latestVersion }),
+    };
+}
+/** Tests only — drop the module state so each case starts clean. */
+export function resetUpdateNudge() {
+    pending = undefined;
+    delivered = false;
+}

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

@@ -0,0 +1,81 @@
+/** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */
+declare const VersionChangeDirection: {
+    readonly UPDATE: "update";
+    readonly ROLLBACK: "rollback";
+};
+type VersionChangeDirection = (typeof VersionChangeDirection)[keyof typeof VersionChangeDirection];
+/**
+ * Report a completed version move. Never throws — an install that worked must still be reported done.
+ *
+ * Exported so the emit path can be exercised directly: `applyUpdate`/`rollback` both run a real npm
+ * install and then `process.exit`, so there is no way to reach this through them in a test without
+ * mocking the package manager and the process itself.
+ */
+export declare function reportVersionChange(from: string, to: string, direction: VersionChangeDirection): Promise<void>;
+/** How this reticle process was launched — determines which npm strategy to use for updates. */
+declare const ExecutionKind: {
+    /** Launched via `npx @reticlehq/server` — npm re-resolves the package on restart. */
+    readonly NPX: "npx";
+    /** Installed globally via `npm install -g`. */
+    readonly GLOBAL: "global";
+    /** Installed as a local project dependency. */
+    readonly LOCAL: "local";
+};
+type ExecutionKind = (typeof ExecutionKind)[keyof typeof 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,
+ * nvm) or AppData\npm (Windows). Match those FIRST, otherwise a global install is misread as local and
+ * `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;
+}
+/**
+ * The npm argv (and optional cwd) that installs `version` for the given launch kind, or null for
+ * npx (which re-resolves the package on the next restart — no install needed). Installs
+ * `@reticlehq/server` — the package that actually carries the `reticle` bin — never
+ * `@reticlehq/core`, which is schema-only and has no executable.
+ */
+export declare function installArgs(version: string, kind: ExecutionKind, localRoot: string | null): NpmInstall | null;
+/**
+ * Install targetVersion using the appropriate strategy for the detected execution kind,
+ * then exit so Claude Code restarts with the new binary. Saves the current version
+ * first so rollback can restore it.
+ */
+export declare function applyUpdate(targetVersion: string): Promise<void>;
+/**
+ * Reinstall the previousVersion saved in the update manifest using the appropriate
+ * strategy, then exit so Claude Code restarts with the restored binary.
+ */
+export declare function rollback(): Promise<void>;
+export {};

package/dist/command/update/updater.js

@@ -0,0 +1,223 @@
+import { execFile } from 'node:child_process';
+import { NodePlatform } from '../../machine/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 '../version/identity/server-version.js';
+import { log } from '../../log.js';
+import { windowsShellArg } from '@reticlehq/init';
+import { TelemetryEventKind } from '@reticlehq/core/telemetry';
+import { getTelemetry } from '../../telemetry/telemetry.js';
+import { wasNudged } from './nudge-credit.js';
+/** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */
+const VersionChangeDirection = {
+    UPDATE: 'update',
+    ROLLBACK: 'rollback',
+};
+/**
+ * Report a completed version move. Never throws — an install that worked must still be reported done.
+ *
+ * Exported so the emit path can be exercised directly: `applyUpdate`/`rollback` both run a real npm
+ * install and then `process.exit`, so there is no way to reach this through them in a test without
+ * mocking the package manager and the process itself.
+ */
+export async function reportVersionChange(from, to, direction) {
+    try {
+        const nudged = wasNudged(to);
+        await getTelemetry().emit(TelemetryEventKind.VERSION_CHANGED, {
+            // 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_TIMEOUT_MS = 120_000;
+/** How this reticle process was launched — determines which npm strategy to use for updates. */
+const ExecutionKind = {
+    /** Launched via `npx @reticlehq/server` — npm re-resolves the package on restart. */
+    NPX: 'npx',
+    /** Installed globally via `npm install -g`. */
+    GLOBAL: 'global',
+    /** Installed as a local project dependency. */
+    LOCAL: 'local',
+};
+/**
+ * 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.
+ */
+function detectExecutionKind() {
+    return classifyExecutionKind(process.argv[1] ?? '');
+}
+/**
+ * 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,
+ * nvm) or AppData\npm (Windows). Match those FIRST, otherwise a global install is misread as local and
+ * `apply_update` npm-installs into the user's own project (polluting their package.json).
+ */
+export function classifyExecutionKind(script) {
+    if (script.includes('/_npx/') || script.includes('\\_npx\\'))
+        return ExecutionKind.NPX;
+    const globalSignals = [
+        '/lib/node_modules/',
+        '\\npm\\node_modules\\',
+        '/.nvm/',
+        '/homebrew/',
+        '/usr/local/',
+        '/usr/lib/',
+    ];
+    if (globalSignals.some((s) => script.includes(s)))
+        return ExecutionKind.GLOBAL;
+    if (script.includes('/node_modules/') || script.includes('\\node_modules\\')) {
+        return ExecutionKind.LOCAL;
+    }
+    return ExecutionKind.GLOBAL;
+}
+/** Walk up from cwd until a directory containing package.json is found. */
+function findLocalProjectRoot() {
+    let dir = process.cwd();
+    for (;;) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null; // reached filesystem root
+        dir = parent;
+    }
+}
+/**
+ * Spawn npm, through a shell on Windows because `npm.cmd` cannot be spawned without one.
+ *
+ * Since the CVE-2024-27980 fix -- in every supported Node -- spawning a `.cmd` with no shell throws
+ * EINVAL. This repo has already paid for that lesson once, at `init/src/node-io.ts`: `reticle setup
+ * mcp` probed for the Claude CLI with a bare `execFileSync`, the probe threw, and the installer
+ * told the user their machine had no Claude Code on it. The same shape sat here, in the SELF-UPDATE
+ * path -- the channel every other fix reaches a user through, and the one place a silent failure
+ * strands somebody on an old version indefinitely.
+ *
+ * Arguments are quoted with init's own rule rather than a second copy of it. They are internal
+ * today (`install`, `-g`, and a package spec whose version comes from the registry), but a shell
+ * turns "internal" into "whatever the registry said", and the quoting is one import.
+ */
+export function npmSpawn(args, 
+/**
+ * Injected so the Windows branch is testable on every platform.
+ *
+ * The bug this fixes could only be OBSERVED on Windows, and a check that can only fail on a
+ * machine nobody here runs is a check that fails in CI at the earliest and in the field at the
+ * latest. The rule is a pure function of the platform string, so it is one.
+ */
+on = platform()) {
+    const bin = NodePlatform.WINDOWS === on ? 'npm.cmd' : 'npm';
+    if (NodePlatform.WINDOWS !== on)
+        return { file: bin, argv: args, shell: false };
+    return { file: [bin, ...args.map(windowsShellArg)].join(' '), argv: [], shell: true };
+}
+function runNpm(args, opts = {}) {
+    const spawn = npmSpawn(args);
+    return new Promise((resolve, reject) => {
+        execFile(spawn.file, spawn.argv, {
+            timeout: NPM_TIMEOUT_MS,
+            ...(spawn.shell ? { shell: true } : {}),
+            ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        }, (err, _stdout, stderr) => {
+            if (err !== null) {
+                reject(new Error(`npm ${args.join(' ')} failed: ${stderr !== '' ? stderr : err.message}`));
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}
+/**
+ * The npm argv (and optional cwd) that installs `version` for the given launch kind, or null for
+ * npx (which re-resolves the package on the next restart — no install needed). Installs
+ * `@reticlehq/server` — the package that actually carries the `reticle` bin — never
+ * `@reticlehq/core`, which is schema-only and has no executable.
+ */
+export function installArgs(version, kind, localRoot) {
+    if (kind === ExecutionKind.NPX)
+        return null;
+    const pkg = `${RETICLE_NPM_PACKAGE}@${version}`;
+    if (kind === ExecutionKind.LOCAL && localRoot !== null) {
+        return { args: ['install', pkg], cwd: localRoot };
+    }
+    return { args: ['install', '-g', pkg] };
+}
+async function installVersion(version, kind) {
+    const localRoot = kind === ExecutionKind.LOCAL ? findLocalProjectRoot() : null;
+    const plan = installArgs(version, kind, localRoot);
+    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', {
+            note: 'Running via npx — exiting so Claude Code restarts and npx fetches the new version',
+        });
+        return;
+    }
+    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' });
+    }
+    await runNpm(plan.args, plan.cwd !== undefined ? { cwd: plan.cwd } : {});
+}
+async function installVersionRollback(version, kind) {
+    if (kind === ExecutionKind.NPX) {
+        log('reticle_rollback_npx_strategy', {
+            note: 'Running via npx — update your .mcp.json args to pin the version you want to restore',
+        });
+        return;
+    }
+    await installVersion(version, kind);
+}
+/**
+ * Install targetVersion using the appropriate strategy for the detected execution kind,
+ * then exit so Claude Code restarts with the new binary. Saves the current version
+ * first so rollback can restore it.
+ */
+export async function applyUpdate(targetVersion) {
+    const manifest = loadManifest();
+    if (manifest !== null) {
+        saveManifest({ ...manifest, previousVersion: manifest.currentVersion });
+    }
+    const kind = detectExecutionKind();
+    log('reticle_update_applying', { version: targetVersion, executionKind: kind });
+    await installVersion(targetVersion, kind);
+    log('reticle_update_applied', { version: targetVersion, executionKind: kind });
+    // Emitted AFTER the install succeeded, so the metric counts versions that actually landed rather
+    // than attempts. Awaited, unlike every other send in the product: `process.exit(0)` on the next
+    // line would kill an in-flight fire-and-forget POST, and this event is rare enough that the wait
+    // costs nothing. A failed send still cannot block the exit — `emit` swallows its own errors.
+    await reportVersionChange(SERVER_VERSION, targetVersion, VersionChangeDirection.UPDATE);
+    process.exit(0);
+}
+/**
+ * Reinstall the previousVersion saved in the update manifest using the appropriate
+ * strategy, then exit so Claude Code restarts with the restored binary.
+ */
+export async function rollback() {
+    const manifest = loadManifest();
+    if (null === manifest || manifest.previousVersion === undefined) {
+        throw new Error('No previous version available for rollback');
+    }
+    const prev = manifest.previousVersion;
+    const kind = detectExecutionKind();
+    log('reticle_rollback_applying', { version: prev, executionKind: kind });
+    await installVersionRollback(prev, kind);
+    log('reticle_rollback_applied', { version: prev, executionKind: kind });
+    // A rollback is a release-quality alarm — someone shipped something that broke a real user badly
+    // enough for them to go backwards. Worth knowing about within the hour, not at the next retro.
+    await reportVersionChange(SERVER_VERSION, prev, VersionChangeDirection.ROLLBACK);
+    // For npx, exiting would let the next restart re-resolve @latest — rolling FORWARD, the opposite
+    // of rollback. installVersionRollback already told the user to pin the version in.mcp.json, so
+    // stay running rather than trigger that. Other kinds installed the old version and must restart.
+    if (kind !== ExecutionKind.NPX)
+        process.exit(0);
+}

package/dist/command/version/identity/server-version.js

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * This package's own manifest, found by looking upwards rather than by counting directories.
+ *
+ * It used to say `../../package.json`, with a note explaining that two levels up was right from both
+ * `src/version/` and `dist/version/`, and warning that moving the file meant editing the line by
+ * hand because nothing would tell you. The file moved. Nothing told us: it is a runtime path, so the
+ * compiler cannot see it, every test passed, and the failure appeared only when an app that embeds
+ * the server tried to start.
+ *
+ * Walking up removes the question. The manifest is the first `package.json` above this file, which
+ * is true from `src/`, from `dist/`, and from wherever either ends up next.
+ */
+function ownManifest() {
+    /*
+     * `fileURLToPath`, NOT `new URL(...).pathname`.
+     *
+     * On Windows the pathname of `file:///D:/a/reticle/...` is `/D:/a/reticle/...` — a leading slash
+     * in front of the drive letter, which is not a path that exists. Every `existsSync` below then
+     * answers false, the walk runs all the way to the root, and this throws "cannot find the server
+     * package.json" on a machine where the file is sitting right there.
+     *
+     * It broke the Windows build and nothing else, because that is the only place a POSIX-shaped
+     * assumption about a file URL gets a different answer.
+     */
+    let dir = dirname(fileURLToPath(import.meta.url));
+    const { root } = parse(dir);
+    for (;;) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            return JSON.parse(readFileSync(candidate, 'utf8'));
+        }
+        if (dir === root)
+            break;
+        dir = dirname(dir);
+    }
+    // Loud rather than quiet. A missing manifest used to surface as an undefined version reported to
+    // the agent and to telemetry, which reads as "this build has no version" rather than as a bug.
+    throw new Error('cannot find the server package.json above ' + import.meta.url);
+}
+const _pkg = ownManifest();
+/** The Reticle server version, read from package.json at startup. */
+export const SERVER_VERSION = _pkg.version;
+/**
+ * The published npm package that carries the `reticle` bin — read from package.json so it can never
+ * drift. Self-update installs THIS (never `@reticlehq/core`, which is schema-only and has no bin).
+ */
+export const RETICLE_NPM_PACKAGE = _pkg.name;

package/dist/command/version/peer-announce.js

@@ -0,0 +1,32 @@
+/**
+ * How another Reticle PROCESS announces itself to the daemon.
+ *
+ * The SDK announces in HELLO and the CLI reads /status, but the MCP server an agent spawns had no
+ * announcement at all — and it is the piece the user actually hits: `npx @reticlehq/server mcp`
+ * resolves from a cache, so an agent can be running a months-old MCP package against a current
+ * daemon with nothing anywhere saying so.
+ *
+ * It rides the SSE connect the proxy already makes, as two query params. Query params rather than a
+ * new message because the connection happens before any protocol exchange, and because an older
+ * proxy that sends neither is handled correctly by describeSkew (absent contract + differing version
+ * = a build that predates the field).
+ */
+import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
+import { SERVER_VERSION } from './identity/server-version.js';
+import { daemonFix, describeSkew, SkewPair } from './version-skew.js';
+import { noteVersionSkew } from './version-nudge.js';
+export const PEER_VERSION_PARAM = 'peerVersion';
+export const PEER_CONTRACT_PARAM = 'peerContract';
+/** Compare an attaching agent process against this daemon, and queue the nudge when they disagree. */
+export function noteAgentPeer(version, contract) {
+    const skew = describeSkew({
+        what: "the agent's MCP server",
+        version: version ?? undefined,
+        contract: contract ?? undefined,
+        // Inverted from cli-launch: here THIS process is the daemon and the peer is the agent's
+        // MCP server, so the daemon is the newer half whenever the announcing agent is behind.
+        fix: daemonFix(SERVER_VERSION, version ?? undefined),
+    }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
+    if (skew !== undefined)
+        noteVersionSkew(SkewPair.DAEMON, skew);
+}