@reticlehq/server 2.4.0 → 2.6.0

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;

package/dist/version/peer-announce.d.ts

@@ -0,0 +1,4 @@
+export declare const PEER_VERSION_PARAM = "peerVersion";
+export declare const PEER_CONTRACT_PARAM = "peerContract";
+/** Compare an attaching agent process against this daemon, and queue the nudge when they disagree. */
+export declare function noteAgentPeer(version: string | null, contract: string | null): void;

package/dist/version/peer-announce.js

@@ -0,0 +1,30 @@
+/**
+ * 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 './server-version.js';
+import { describeSkew, DAEMON_FIX, 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,
+        fix: DAEMON_FIX,
+    }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
+    if (skew !== undefined)
+        noteVersionSkew(SkewPair.DAEMON, skew);
+}

package/dist/{server-version.js → version/server-version.js}

@@ -1,5 +1,9 @@
 import { createRequire } from 'node:module';
-const _pkg = createRequire(import.meta.url)('../package.json');
+// NOTE: a RUNTIME path, not an import — `tsc` does not check it and a file move will not rewrite
+// it. Two levels up because this file sits in `version/`: from `src/version/` and from
+// `dist/version/` alike, `../../package.json` is the package manifest. Moving this file again means
+// changing this line by hand; nothing else will tell you.
+const _pkg = createRequire(import.meta.url)('../../package.json');
 /** The Reticle server version, read from package.json at startup. */
 export const SERVER_VERSION = _pkg.version;
 /**

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

@@ -0,0 +1,28 @@
+/**
+ * Getting skew in front of the AGENT, on whatever tool it happens to be calling.
+ *
+ * Every check built before this reported into a place nobody looks: SDK skew landed in
+ * `reticle_sessions.versionSkew`, which an agent driving a flow never calls, and daemon skew went to
+ * a CLI log line no agent reads. So an agent could work an entire session against a mismatched pair,
+ * watch tools behave oddly, and never be told the one fact that explains it.
+ *
+ * This is the delivery channel — the same one the update nudge uses, for the same reason: an
+ * out-of-date install is worth mentioning whatever the agent is doing. It rides out on the next tool
+ * result, then goes quiet until the skew CHANGES. Told, not nagged: a banner on every call is one an
+ * agent learns to skip, and it would cost those tokens on every call for the rest of the session.
+ */
+import type { SkewPair } from './version-skew.js';
+interface VersionSkewNudge {
+    pair: SkewPair;
+    action: string;
+}
+/**
+ * Record a skew for delivery. Re-arms only when the message DIFFERS from the one already delivered:
+ * a second tab on a third version is news; the same tab reconnecting is not.
+ */
+export declare function noteVersionSkew(pair: SkewPair, action: string): void;
+/** The next undelivered skew, once. */
+export declare function takeVersionSkew(): VersionSkewNudge | undefined;
+/** Tests only — drop the module state so each case starts clean. */
+export declare function resetVersionSkew(): void;
+export {};

package/dist/version/version-nudge.js

@@ -0,0 +1,40 @@
+/**
+ * Getting skew in front of the AGENT, on whatever tool it happens to be calling.
+ *
+ * Every check built before this reported into a place nobody looks: SDK skew landed in
+ * `reticle_sessions.versionSkew`, which an agent driving a flow never calls, and daemon skew went to
+ * a CLI log line no agent reads. So an agent could work an entire session against a mismatched pair,
+ * watch tools behave oddly, and never be told the one fact that explains it.
+ *
+ * This is the delivery channel — the same one the update nudge uses, for the same reason: an
+ * out-of-date install is worth mentioning whatever the agent is doing. It rides out on the next tool
+ * result, then goes quiet until the skew CHANGES. Told, not nagged: a banner on every call is one an
+ * agent learns to skip, and it would cost those tokens on every call for the rest of the session.
+ */
+/** Pending per pair — the SDK and the daemon are different upgrades and each is worth saying once. */
+const pending = new Map();
+/** The last message delivered for each pair, so the same skew is never repeated. */
+const delivered = new Map();
+/**
+ * Record a skew for delivery. Re-arms only when the message DIFFERS from the one already delivered:
+ * a second tab on a third version is news; the same tab reconnecting is not.
+ */
+export function noteVersionSkew(pair, action) {
+    if (delivered.get(pair) === action)
+        return;
+    pending.set(pair, action);
+}
+/** The next undelivered skew, once. */
+export function takeVersionSkew() {
+    for (const [pair, action] of pending) {
+        pending.delete(pair);
+        delivered.set(pair, action);
+        return { pair, action };
+    }
+    return undefined;
+}
+/** Tests only — drop the module state so each case starts clean. */
+export function resetVersionSkew() {
+    pending.clear();
+    delivered.clear();
+}

package/dist/version/version-skew.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Does this peer speak our contract? The daemon is the only thing that asks.
+ *
+ * Reticle is three separately-installed pieces — the SDK in the page, this daemon, and the MCP
+ * server the agent spawns — upgraded independently and therefore drifting constantly. Each pair
+ * fails the same silent way: `protocolVersion` still matches, the connection succeeds, and only
+ * BEHAVIOUR disagrees. A user hit exactly that with a 2.2.1 SDK against a 2.3.0 daemon and saw a
+ * bare `-32000` with nothing on either side naming a version.
+ *
+ * Two decisions shape this file.
+ *
+ * The daemon is the SINGLE judge. Every piece announces itself at a connect it already makes — the
+ * SDK in HELLO, the CLI and the MCP server over /status — and comparing happens here, once. Three
+ * independent pairwise checks would be three copies to keep in step and three separate complaints
+ * about one upgrade; a table in one place can say what is actually true: which pieces disagree, and
+ * which one is behind.
+ *
+ * The signal is the CONTRACT FINGERPRINT, not the version. Version equality is wrong in both
+ * directions: it fires on 2.4.0-vs-2.4.1 where nothing changed — so every patch release makes every
+ * un-upgraded app cry wolf, and the warning becomes noise — and it cannot fire at all for two
+ * different BUILDS of one version number, which is exactly what a stale daemon and a cached npx
+ * install are. The fingerprint is derived from core's wire vocabulary, so it moves when a name on
+ * the wire changes and stays put when internals do. Versions still ride along, because they are what
+ * a human acts on.
+ */
+/** Which pair disagreed. Named so the nudge can report each independently. */
+export declare const SkewPair: {
+    /** The SDK in the page vs this daemon. */
+    readonly SDK: "sdk";
+    /** Another Reticle process — a CLI, or the MCP server an agent spawned — vs this daemon. */
+    readonly DAEMON: "daemon";
+};
+export type SkewPair = (typeof SkewPair)[keyof typeof SkewPair];
+/** What a piece says about itself when it connects. */
+export interface PeerIdentity {
+    /** Human-readable subject for the message: "the page", "the daemon on this port". */
+    what: string;
+    /** Package version, when the peer supplied one. Undefined on a hand-wired connect. */
+    version: string | undefined;
+    /** Contract fingerprint. Undefined means the peer predates the field — itself evidence of age. */
+    contract: string | undefined;
+    /** What the human runs to bring this piece into line. */
+    fix: string;
+}
+/** Everything a build knows about itself. */
+interface SelfIdentity {
+    version: string;
+    contract: string;
+}
+/**
+ * The one sentence to tell the agent, or undefined when the pair agrees.
+ *
+ * Silent when the fingerprints MATCH, whatever the versions say — that is the point: a patch bump
+ * that changed no wire name is not skew, and warning about it is how a real warning gets ignored.
+ *
+ * A peer with no fingerprint is treated as skewed ONLY when its version also differs from ours: the
+ * field is absent exactly on builds that predate it, so "no fingerprint AND a different version" is
+ * a build provably older than this daemon. With neither signal there is nothing to go on, and
+ * inventing a warning would be as dishonest as staying silent about a real one.
+ */
+export declare function describeSkew(peer: PeerIdentity, self: SelfIdentity): string | undefined;
+/** The fix line for a page whose SDK disagrees with this daemon. */
+export declare function sdkFix(daemonVersion: string): string;
+/** The fix line for another Reticle process that disagrees with the daemon it attached to. */
+export declare const DAEMON_FIX: string;
+export {};

package/dist/version/version-skew.js

@@ -0,0 +1,71 @@
+/**
+ * Does this peer speak our contract? The daemon is the only thing that asks.
+ *
+ * Reticle is three separately-installed pieces — the SDK in the page, this daemon, and the MCP
+ * server the agent spawns — upgraded independently and therefore drifting constantly. Each pair
+ * fails the same silent way: `protocolVersion` still matches, the connection succeeds, and only
+ * BEHAVIOUR disagrees. A user hit exactly that with a 2.2.1 SDK against a 2.3.0 daemon and saw a
+ * bare `-32000` with nothing on either side naming a version.
+ *
+ * Two decisions shape this file.
+ *
+ * The daemon is the SINGLE judge. Every piece announces itself at a connect it already makes — the
+ * SDK in HELLO, the CLI and the MCP server over /status — and comparing happens here, once. Three
+ * independent pairwise checks would be three copies to keep in step and three separate complaints
+ * about one upgrade; a table in one place can say what is actually true: which pieces disagree, and
+ * which one is behind.
+ *
+ * The signal is the CONTRACT FINGERPRINT, not the version. Version equality is wrong in both
+ * directions: it fires on 2.4.0-vs-2.4.1 where nothing changed — so every patch release makes every
+ * un-upgraded app cry wolf, and the warning becomes noise — and it cannot fire at all for two
+ * different BUILDS of one version number, which is exactly what a stale daemon and a cached npx
+ * install are. The fingerprint is derived from core's wire vocabulary, so it moves when a name on
+ * the wire changes and stays put when internals do. Versions still ride along, because they are what
+ * a human acts on.
+ */
+/** Which pair disagreed. Named so the nudge can report each independently. */
+export const SkewPair = {
+    /** The SDK in the page vs this daemon. */
+    SDK: 'sdk',
+    /** Another Reticle process — a CLI, or the MCP server an agent spawned — vs this daemon. */
+    DAEMON: 'daemon',
+};
+function versionPhrase(peer, self) {
+    return peer.version === undefined
+        ? `${peer.what} is on an unknown version; this daemon is ${self.version}`
+        : `${peer.what} is ${peer.version}; this daemon is ${self.version}`;
+}
+/**
+ * The one sentence to tell the agent, or undefined when the pair agrees.
+ *
+ * Silent when the fingerprints MATCH, whatever the versions say — that is the point: a patch bump
+ * that changed no wire name is not skew, and warning about it is how a real warning gets ignored.
+ *
+ * A peer with no fingerprint is treated as skewed ONLY when its version also differs from ours: the
+ * field is absent exactly on builds that predate it, so "no fingerprint AND a different version" is
+ * a build provably older than this daemon. With neither signal there is nothing to go on, and
+ * inventing a warning would be as dishonest as staying silent about a real one.
+ */
+export function describeSkew(peer, self) {
+    if (peer.contract !== undefined && peer.contract === self.contract)
+        return undefined;
+    if (peer.contract === undefined) {
+        if (peer.version === undefined || peer.version === self.version)
+            return undefined;
+        return (`version skew: ${versionPhrase(peer, self)}, and it is too old to report which wire contract ` +
+            `it speaks. They connect anyway and then disagree about behaviour, which usually surfaces as ` +
+            `a bare -32000 with nothing naming a version. ${peer.fix}`);
+    }
+    return (`version skew: ${versionPhrase(peer, self)}, and they speak DIFFERENT wire contracts ` +
+        `(${peer.contract} vs ${self.contract}) — so this is a real mismatch, not a harmless patch ` +
+        `difference. Tools will behave in ways neither side reports. ${peer.fix}`);
+}
+/** The fix line for a page whose SDK disagrees with this daemon. */
+export function sdkFix(daemonVersion) {
+    return (`Tell the human to install the matching SDK (\`npm i -D @reticlehq/react@${daemonVersion}\`) ` +
+        'or run `reticle update`, then restart their dev server so the page reloads with it.');
+}
+/** The fix line for another Reticle process that disagrees with the daemon it attached to. */
+export const DAEMON_FIX = 'A daemon outlives the agents attached to it, so it keeps serving its OWN code until it restarts ' +
+    '— anything fixed in the newer package is simply absent. Run `reticle stop` and retry to replace ' +
+    'it (other agents on that daemon will need to reconnect).';

package/dist/visual/visual-diff.js

@@ -32,7 +32,7 @@ function changedRegion(out, width, height) {
         for (let x = 0; x < width; x += 1) {
             const i = (y * width + x) * RGBA;
             // pixelmatch marks a changed pixel solid red (default diffColor) at full alpha.
-            if (out[i] === 255 && out[i + 1] === 0 && out[i + 2] === 0 && out[i + 3] === 255) {
+            if (255 === out[i] && 0 === out[i + 1] && 0 === out[i + 2] && 255 === out[i + 3]) {
                 if (x < minX)
                     minX = x;
                 if (y < minY)
@@ -80,7 +80,7 @@ export async function diffPng(baselineBytes, currentBytes, opts = {}) {
     const threshold = opts.threshold ?? VISUAL_PIXEL_THRESHOLD;
     const changedPixels = pixelmatch(a.data, b.data, out.data, width, height, { threshold });
     const totalPixels = width * height;
-    const ratio = totalPixels === 0 ? 0 : changedPixels / totalPixels;
+    const ratio = 0 === totalPixels ? 0 : changedPixels / totalPixels;
     const maxRatio = opts.maxRatio ?? 0;
     const region = changedPixels > 0 ? changedRegion(out.data, width, height) : undefined;
     const result = {

package/dist/visual/visual-tools.js

@@ -16,7 +16,7 @@ const rectShape = z.object({
 });
 function screenshotProvider(deps) {
     const p = deps.realInput;
-    return p !== undefined && typeof p.screenshot === 'function'
+    return p !== undefined && 'function' === typeof p.screenshot
         ? p
         : undefined;
 }
@@ -55,7 +55,7 @@ async function buildOpts(deps, sessionId, args) {
         if (box !== undefined)
             return { clip: box };
     }
-    return args['fullPage'] === true ? { fullPage: true } : {};
+    return true === args['fullPage'] ? { fullPage: true } : {};
 }
 /**
  * Ask the desktop shell to photograph its own window.
@@ -110,7 +110,7 @@ function isCapturePath(path) {
 function isCompletePng(bytes) {
     if (bytes.byteLength < 12)
         return false;
-    return bytes.subarray(bytes.byteLength - 8, bytes.byteLength - 4).toString('ascii') === 'IEND';
+    return 'IEND' === bytes.subarray(bytes.byteLength - 8, bytes.byteLength - 4).toString('ascii');
 }
 /**
  * Get pixels for a session, by whichever route exists.
@@ -137,7 +137,7 @@ async function capture(deps, sessionId, args) {
         if (png !== undefined)
             return { png };
     }
-    const desktop = await desktopCapture(deps, sessionId, args['fullPage'] === true);
+    const desktop = await desktopCapture(deps, sessionId, true === args['fullPage']);
     if (desktop.png !== undefined)
         return { png: desktop.png };
     if (desktop.reason !== undefined)

package/docs/README.md

@@ -0,0 +1,55 @@
+# Docs index
+
+Two audiences share this directory, which is why it looked like twenty-five unsorted files. Every page states its own audience in the first blockquote; this index is the shortcut.
+
+**User docs are published** to [reticle.sh](https://reticle.sh) via `mint.json`. **Contributor docs are not** — they are for people working _on_ Reticle, and they live here because they belong next to what they describe.
+
+---
+
+## For people using Reticle
+
+**Start:** [getting-started.md](getting-started.md) → [usage.md](usage.md) (the full tool reference).
+
+| Page | What it answers |
+| --- | --- |
+| [getting-started.md](getting-started.md) | install it, connect an agent, verify something |
+| [usage.md](usage.md) | every tool, every argument — the reference |
+| [agent-cheatsheet.md](agent-cheatsheet.md) | the condensed version an agent keeps in context |
+| [architecture.md](architecture.md) | how it works, and why it is built this way |
+| [platform-integration.md](platform-integration.md) | Vite, Next, Remix, Astro, plain HTML |
+| [desktop-apps.md](desktop-apps.md) | Electron and Tauri |
+| [integration-patterns.md](integration-patterns.md) | wiring it into a real codebase |
+| [flows.md](flows.md) | record → save → replay → heal |
+| [testing.md](testing.md) | `@reticlehq/test` — turning a session into a CI suite |
+| [multi-agent-testing.md](multi-agent-testing.md) | more than one agent on one app |
+| [human-control.md](human-control.md) | taking the wheel back from the agent |
+| [deploy-checks.md](deploy-checks.md) | running Reticle against a deployed build |
+| [token-efficiency.md](token-efficiency.md) | why it costs less than a screenshot loop |
+| [benchmarks.md](benchmarks.md) | how the numbers were measured, including where Reticle loses |
+| [telemetry.md](telemetry.md) | what is collected, and how to turn it off |
+| [local-registry.md](local-registry.md) | installing an unpublished build |
+| [enterprise.md](enterprise.md) | the licensed surface |
+
+## For people working on Reticle
+
+**Start:** [`CONTRIBUTING.md`](../CONTRIBUTING.md) → [gates.md](gates.md).
+
+| Page | What it answers |
+| --- | --- |
+| [gates.md](gates.md) | **I changed some files — which gate do I run?** |
+| [gate-plan.md](gate-plan.md) | why the gates are shaped this way, and what is still unbuilt |
+| [system-map.md](system-map.md) | how a tool call reaches the app, and which failures are silent |
+| [telemetry-contract.md](telemetry-contract.md) | required reading before touching anything that emits |
+| [debugging.md](debugging.md) | debugging Reticle itself — the four signals and what each answers |
+| [fixtures.md](fixtures.md) | the sibling `reticle-fixtures` repo: install complexity, not regressions |
+| [matrix/README.md](matrix/README.md) | submitting an MCP-client compatibility record — the best first contribution |
+| [matrix/MATRIX.md](matrix/MATRIX.md) | which clients are known to work (generated; do not hand-edit) |
+| [`../apps/README.md`](../apps/README.md) | what belongs in `apps/`, and what does not |
+| [`../apps/e2e/harness-rules.md`](../apps/e2e/harness-rules.md) | the four rules every gate obeys, and the incident behind each |
+| [`../bench/README.md`](../bench/README.md) | what in `bench/` is live and what is a kept one-off study |
+
+`fixtures-dispatch-receiver.yml` is not a doc — it is the workflow template `reticle-fixtures` needs, kept in this repo so the two ends of the contract cannot drift apart.
+
+---
+
+**Adding a page?** Put it in the right table above. If it is user-facing, add it to `mint.json` too — a page that is published but unlisted is a page nobody finds, and a page listed here but absent from `mint.json` is one users cannot reach at all.