@reticlehq/server 2.14.0 → 3.2.0

package/dist/tools/unadvertised-help.js

@@ -1,42 +0,0 @@
-/**
- * What to say when an agent calls a real Reticle tool that this profile does not advertise.
- *
- * The default surface is the verify loop plus the two meta-tools; the extended one is larger but
- * still capped. Counts live in `surface-sizes.test.ts` — restating them here is how they drift.
- * Everything omitted stays fully callable through `reticle_run`, which `surface-reachability.test.ts`
- * guards.
- *
- * The gap was in the ERROR. The MCP SDK answers `Tool <name> not found`, which is indistinguishable
- * from "this tool does not exist", so an agent that trusts it stops trying. Reported from a real
- * sweep of a Next app-router project: the first pass scored 25 failures that were nothing of the
- * kind — every one of those tools worked through `reticle_run` seconds later.
- *
- * So: a name Reticle owns never comes back as "not found". It comes back with the call that works
- * and the switch that makes it stop being necessary.
- */
-import { ReticleTool } from './tool-names.js';
-import { ADVERTISE_ALL_ENV } from './tool-surface.js';
-import { mergedNameRedirect, mergedNameMessage } from './merged-name-redirect.js';
-/**
- * Guidance for `name`, or undefined when there is nothing useful to add — the tool IS advertised (so
- * any error belongs to the call itself), or the name is not ours to explain.
- */
-export function unadvertisedToolHelp(name, advertised, known) {
-    if (advertised.has(name))
-        return undefined;
-    // A name that MOVED gets the move, not a profile lecture — it is not un-advertised, it is gone.
-    const moved = mergedNameRedirect(name);
-    if (moved !== undefined)
-        return mergedNameMessage(name, moved);
-    if (!known.has(name))
-        return undefined;
-    return (`${name} exists and works, but is not advertised under this tool profile — the schemas for all ` +
-        `tools are re-sent every turn, so the default advertises a subset and keeps the rest one call ` +
-        `away. It is NOT missing: invoke it with ` +
-        `${ReticleTool.RUN} { tool: "${name}", args: { ... } }. ` +
-        `Call ${ReticleTool.TOOLS} { names: ["${name}"] } for its parameters. ` +
-        `If you need it repeatedly, start the daemon with ${ADVERTISE_ALL_ENV}=1 for the extended ` +
-        `surface. That is read by the DAEMON at startup, so it takes effect on the next daemon, and it ` +
-        `advertises MORE tools rather than all of them — editors budget MCP tools as a shared count, so ` +
-        `${ReticleTool.RUN} stays the way to reach the rest.`);
-}

package/dist/tools/verify-next-baton.js

@@ -1,52 +0,0 @@
-/**
- * The verdict nudge, as a call the agent can make rather than a sentence it has to translate.
- *
- * `verify_next` already fires when an agent has driven the page several times and asked for no
- * verdict, which is the commonest shape of a wasted session: almost every verdict-less session in
- * the field never called a verdict-producing tool once. What it carried was prose. Prose has to be
- * turned back into a call, and the translation is exactly where the agent was already going wrong —
- * `until` omitted, arguments flat instead of nested under `args`, a predicate written as a bare
- * array.
- *
- * So it carries the call. `ref` and `action` come from the act that actually dispatched, so the
- * suggestion is about the element the agent really touched rather than a worked example from a
- * document. `until` is deliberately left as a placeholder the agent must replace: naming the
- * consequence is the one part nothing but the agent can know, and filling it in with a guess would
- * be Reticle inventing the assertion — the failure `no-fault` exists to prevent.
- *
- * Emitted only when there is a real call to suggest. A baton with nothing behind it is the router
- * failure in miniature: an agent that follows a fabricated next step follows it confidently.
- */
-import { ReticleTool } from './tool-names.js';
-/**
- * Set to `1` to withhold the baton from tool results — the control arm of its A/B, and nothing else.
- *
- * A measurement flag, not a product setting: it is read at one call site, documented here, and named
- * loudly enough that nobody sets it by accident. It exists because this feature has shipped, been
- * declared the largest lever on whether a session verifies at all, and never been measured — and a
- * control arm is the only way to tell "agents that see it verify" from "agents that were going to
- * verify anyway also saw it".
- */
-export const SUPPRESS_VERIFY_NEXT_ENV = 'RETICLE_SUPPRESS_VERIFY_NEXT';
-/** What the agent must supply itself. Phrased as an instruction so it cannot be sent verbatim. */
-export const UNTIL_PLACEHOLDER = '<name the consequence this action causes>';
-/**
- * Build the baton from what the session actually did.
- *
- * `ref` absent means no act dispatched under a ref this session — a navigation, or a run that only
- * read. There is then no honest call to name, so the prose stands alone rather than pointing at an
- * element nobody touched.
- */
-export function verifyNextBaton(prose, lastAct) {
-    const { ref, action } = lastAct;
-    if (ref === undefined || action === undefined)
-        return { why: prose };
-    return {
-        why: prose,
-        call: {
-            tool: ReticleTool.ACT_AND_WAIT,
-            args: { ref, action, until: { kind: 'text', value: UNTIL_PLACEHOLDER } },
-        },
-        docs: `reticle_tools { names: ["${ReticleTool.ACT_AND_WAIT}"] }`,
-    };
-}

package/dist/update/nudge-credit.js

@@ -1,53 +0,0 @@
-/**
- * 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/reticle-deps.d.ts

@@ -1,9 +0,0 @@
-/**
- * The `@reticlehq/*` packages a project actually declares.
- *
- * Shared by `reticle update` (which syncs them) and the version-skew remedy (which names them).
- * Lives here, not in `init/`, so the daemon library path can read a package.json without pulling
- * the installer in behind it.
- */
-/** The Reticle packages this project declares, from either dependency section. */
-export declare function reticleDepsOf(pkgJson: unknown): string[];

package/dist/update/reticle-deps.js

@@ -1,27 +0,0 @@
-/**
- * The `@reticlehq/*` packages a project actually declares.
- *
- * Shared by `reticle update` (which syncs them) and the version-skew remedy (which names them).
- * Lives here, not in `init/`, so the daemon library path can read a package.json without pulling
- * the installer in behind it.
- */
-/** 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.
- */
-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);
-}

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

@@ -1,20 +0,0 @@
-/**
- * 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 '@reticlehq/init';
-export { reticleDepsOf } from './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/update/sdk-sync.js

@@ -1,22 +0,0 @@
-/**
- * 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 '@reticlehq/init';
-export { reticleDepsOf } from './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/update/update-checker.js

@@ -1,122 +0,0 @@
-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/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/update/update-nudge.d.ts

@@ -1,92 +0,0 @@
-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.
- *
- * `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.
- *
- * 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.
- *
- * The nudge has shipped for several releases and emitted nothing, so "did the agent get told about
- * a release, and did anything happen" was unanswerable — and it is the whole adoption mechanism for
- * a published fix. `versionChange.nudged` is the half that only ever arrives from machines that DID
- * update; the pinned cohort never fires `version_changed` at all.
- *
- * 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 {};

package/dist/update/update-nudge.js

@@ -1,214 +0,0 @@
-/**
- * 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/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.
- */
-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.
- *
- * `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.
- *
- * 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.
- *
- * The nudge has shipped for several releases and emitted nothing, so "did the agent get told about
- * a release, and did anything happen" was unanswerable — and it is the whole adoption mechanism for
- * a published fix. `versionChange.nudged` is the half that only ever arrives from machines that DID
- * update; the pinned cohort never fires `version_changed` at all.
- *
- * 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;
-}