@reticlehq/server 2.4.0 → 2.6.0

package/dist/tools/tools.js

@@ -1,10 +1,22 @@
 import { z } from 'zod';
-import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { withSizeCost } from '../session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './snapshot-delta.js';
 import { asString, asNumber } from './tools-helpers.js';
+import { normalizeQueryArgs } from './query-shape.js';
 import { paginateQueryResult } from './query-paginate.js';
+/**
+ * The query strategies, derived from the enum in core — never retyped.
+ *
+ * The description used to hand-list them and had already drifted: it named six and omitted
+ * `component`, which is real and works. Deriving both the schema and the prose from one source is
+ * the repo's own rule, and here it is also the difference between refusing `by:'css'` and silently
+ * answering "0 matches" to it.
+ */
+const QUERY_BY_VALUES = Object.values(QueryBy);
+const QUERY_BY_LIST = QUERY_BY_VALUES.join(' | ');
+const queryByEnum = z.enum(QUERY_BY_VALUES);
 import { CONTRACT_TOOLS } from './contract-tools.js';
 import { DOMAIN_TOOLS } from '../domain/domain-tools.js';
 import { BROWSER_TOOLS } from './browser-tools.js';
@@ -49,6 +61,10 @@ const RAW_TOOLS = [
                 title: z.string().optional(),
                 adapters: z.array(z.string()),
                 hasCapabilities: z.boolean(),
+                versionSkew: z
+                    .string()
+                    .optional()
+                    .describe("Present only when this page's SDK version differs from the daemon's. A skewed pair connects and then disagrees about tool behaviour — usually surfacing as a bare -32000. Fix it before trusting any verdict from this session."),
                 lastSeenMs: z.number(),
                 throttled: z.boolean(),
                 focused: z.boolean(),
@@ -151,19 +167,24 @@ const RAW_TOOLS = [
                 sessionId: resolved.id,
                 scope: asString(args['scope']) ?? '',
                 mode,
-                diff: args['diff'] === true,
+                diff: true === args['diff'],
             }, SNAPSHOT_CACHE)));
         },
     },
     {
         name: ReticleTool.QUERY,
         example: { by: 'testid', value: 'todo-list' },
-        description: 'Find elements by Testing-Library semantics, INCLUDING open shadow roots — `count_only:true` gives just the count (~30x smaller); `limit` caps descriptors. Pass `by` (role|text|label|placeholder|testid|alt) and `value` (the query string). Returns matching refs + descriptors + visibility. Pass `attrs:["href"]` to project attributes (link/image URLs) onto each match. Pass `limit` to cap descriptors (broad role queries can be large) or `count_only:true` for just the match count — both cut tokens. On zero matches, also returns hint:{ route, presentRegions[], knownEmptyState } so you can distinguish an empty state from a missing element WITHOUT taking a snapshot.',
+        description: `Find elements by Testing-Library semantics, INCLUDING open shadow roots — \`count_only:true\` gives just the count (~30x smaller); \`limit\` caps descriptors. Pass \`by\` (${QUERY_BY_LIST}) and \`value\` (the query string). Returns matching refs + descriptors + visibility. Pass \`attrs:["href"]\` to project attributes (link/image URLs) onto each match. Pass \`limit\` to cap descriptors (broad role queries can be large) or \`count_only:true\` for just the match count — both cut tokens. On zero matches, also returns hint:{ route, presentRegions[], knownEmptyState } so you can distinguish an empty state from a missing element WITHOUT taking a snapshot.`,
         inputSchema: {
-            by: z.string().describe('Query strategy: role | text | label | placeholder | testid | alt'),
+            // Constrained to the enum, NOT z.string(). A free string let `by:'css'` through to the
+            // browser's `default: return []`, so an unsupported strategy answered "0 matches" — which
+            // reads as "the element is not on the page". Measured on a live page: by:'css' value:'body'
+            // returned count 0. A false negative is the one answer this product must never invent.
+            by: queryByEnum.optional().describe(`Query strategy: ${QUERY_BY_LIST}`),
             value: z
                 .string()
-                .describe('Query value for the selected strategy (e.g. by=role value=button, or by=testid value=submit-btn).'),
+                .optional()
+                .describe('Query value for the selected strategy (e.g. by=role value=button, or by=testid value=submit-btn). Or use the predicate spelling directly: { testid: "submit" }, { text: "Deploy" }.'),
             name: z
                 .string()
                 .optional()
@@ -185,6 +206,14 @@ const RAW_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('Return just { count } (no element descriptors) — use when you only need "how many match?" and not their refs.'),
+            // The predicate's spelling, accepted as an alias for by/value so the shape an agent learns from
+            // act_and_wait/assert also works here. See query-shape.ts.
+            testid: z.string().optional().describe('Alias for by="testid" value=… (predicate spelling).'),
+            text: z.string().optional().describe('Alias for by="text" value=… (predicate spelling).'),
+            role: z.string().optional().describe('Alias for by="role" value=… (predicate spelling).'),
+            label: z.string().optional().describe('Alias for by="label" value=… (predicate spelling).'),
+            placeholder: z.string().optional().describe('Alias for by="placeholder" value=… .'),
+            alt: z.string().optional().describe('Alias for by="alt" value=… (predicate spelling).'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -257,16 +286,20 @@ const RAW_TOOLS = [
                 .optional()
                 .describe('True when a `scope` was given but resolved to nothing — zero matches then means the scope is gone, NOT that the element is absent. The search did not widen to the whole page. Re-check the scope before concluding anything.'),
         },
-        handler: (deps, args) => commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.QUERY, {
-            by: args['by'],
-            value: args['value'],
-            name: args['name'],
-            scope: args['scope'],
-            // The handler forwards an explicit allowlist, so a new input is silently dropped unless it is
-            // added here — the browser saw no `attrs` and returned undefined while the unit tests, which
-            // call matchQuery directly, passed. Schema plus implementation is not the whole wire.
-            attrs: args['attrs'],
-        }).then((result) => withSizeCost(paginateQueryResult(result, asNumber(args['limit']), args['count_only'] === true))),
+        handler: (deps, rawArgs) => {
+            // Accept the predicate's named-field spelling too — see query-shape.ts.
+            const args = normalizeQueryArgs(rawArgs);
+            return commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.QUERY, {
+                by: args['by'],
+                value: args['value'],
+                name: args['name'],
+                scope: args['scope'],
+                // The handler forwards an explicit allowlist, so a new input is silently dropped unless it is
+                // added here — the browser saw no `attrs` and returned undefined while the unit tests, which
+                // call matchQuery directly, passed. Schema plus implementation is not the whole wire.
+                attrs: args['attrs'],
+            }).then((result) => withSizeCost(paginateQueryResult(result, asNumber(args['limit']), true === args['count_only'])));
+        },
     },
     {
         name: ReticleTool.INSPECT,
@@ -383,7 +416,7 @@ const RAW_TOOLS = [
  * Guardrail (from the plan): the 12-tool core hot-set keeps its EXACT names and shapes and is never
  * merged — sessions/navigate/snapshot/query/act/act_and_wait/observe/network/console/wait_for/assert/state.
  */
-const MERGE_PLANS = [
+export const MERGE_PLANS = [
     {
         name: ReticleTool.BASELINE,
         description: 'Semantic-state baselines: { action: "save" } snapshots the current state under a name, "list" returns saved names, "diff" compares the live page against a saved baseline (REMOVED/ADDED elements + console-error count).',
@@ -419,6 +452,9 @@ const MERGE_PLANS = [
             review: ReticleTool.REVIEW,
             narrate: ReticleTool.NARRATE,
         },
+        // The handback the lease block orders on every session — the one call an agent MUST make, so it
+        // is the one that must not need a schema lookup first.
+        example: { action: 'yield', mode: 'waiting' },
     },
     {
         name: ReticleTool.LEASE,
@@ -430,7 +466,7 @@ const MERGE_PLANS = [
  * Retired from the MCP surface entirely (capability preserved elsewhere, per the plan):
  * - run_record: auto-recording on flow_replay already persists run outcomes.
  */
-const RETIRED_FROM_SURFACE = [
+export const RETIRED_FROM_SURFACE = [
     ReticleTool.RUN_RECORD, // auto-recording on flow_replay already persists run outcomes
     ReticleTool.REFRESH, // absorbed into reticle_navigate { reload: true }
     ReticleTool.WAIT_READY, // server-internal: the first live call already blocks for the session

package/dist/tools/unadvertised-help.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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 declare function unadvertisedToolHelp(name: string, advertised: ReadonlySet<string>, known: ReadonlySet<string>): string | undefined;

package/dist/tools/unadvertised-help.js

@@ -0,0 +1,39 @@
+/**
+ * What to say when an agent calls a real Reticle tool that this profile does not advertise.
+ *
+ * The default profile advertises 16 of 46 tools. That is deliberate — every advertised tool's schema
+ * is re-sent on every turn, and the trim is most of why `hybrid` is cheap — and the other 30 stay
+ * fully callable through `reticle_run`, which `profile-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 { TOOL_SURFACE, TOOL_PROFILE_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, set ${TOOL_PROFILE_ENV}=${TOOL_SURFACE.ALL} to advertise ` +
+        `every tool directly.`);
+}

package/dist/trace.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Verbose internal flow tracing, for people working ON Reticle.
+ *
+ * The gap it fills: the journal records what the AGENT did to the app, and telemetry records
+ * aggregates. Neither says which of OUR code a tool call went through, in what order, or where the
+ * time went — so every "why is this flow slow" and "which path produced this verdict" was
+ * reconstructed by hand from reading source. One line per stage answers both.
+ *
+ * Design, in order of what it cost to get wrong elsewhere in this repo:
+ *
+ *  - OFF by default, and ~126ns per site when off (measured) — `span` calls the function and
+ *    returns. A trace on every tool call is a real cost on the hot path, and the hot path is a
+ *    verification loop of 50–200 calls.
+ *  - ONE line per stage, emitted when it ENDS, carrying its own duration. A start line as well
+ *    would double the volume to say something the end line already implies.
+ *  - Correlated by a call id and a depth, carried in AsyncLocalStorage rather than threaded through
+ *    every signature. Several agents are inside `runTool` at once — interleaving is the normal case
+ *    — so without an id the output is a pile of unrelated lines, and instrumenting anything would
+ *    mean changing its parameters, which is how instrumentation stops being added.
+ *  - Through the existing `log()`, so it lands in the same stderr stream the daemon already
+ *    redirects to `~/.reticle/daemon-<port>.log`. No new sink, no new file, nothing else to tail.
+ */
+/**
+ * Whether tracing is on.
+ *
+ * Read per call, not cached at import, and the reason is `loadDotEnv`: the CLI populates
+ * `process.env` from the project's .env AFTER every module has been imported, so a value captured at
+ * import time would miss a `RETICLE_TRACE` set there — silently, which is the worst way for a
+ * diagnostic switch to fail. (The reason originally given here — "so it can be turned on while the
+ * daemon runs" — was wrong: nothing outside a process can change its environment.)
+ *
+ * Measured cost of reading it per call: 126ns per traced site when tracing is OFF, against a ~9ns
+ * bare call. With a handful of spans per tool call that is under a microsecond on a call that takes
+ * milliseconds — cheap enough to be worth the correctness, and not the literal zero this comment
+ * used to imply.
+ */
+export declare function traceEnabled(): boolean;
+/**
+ * Bind a callback to the call that is running NOW, so it reports inside that call when it fires later.
+ *
+ * `waitForPredicate` re-checks its predicate from a WebSocket event listener and an interval. Neither
+ * is in the awaited chain, so AsyncLocalStorage does not reach them and every re-check used to open a
+ * brand new call at depth 0. Measured on one healthy run: 165 spans across 60 callIds, 25 of them a
+ * `browser.command` with no matching `tool.handler`.
+ *
+ * That is not cosmetic. The documented signature of a HUNG tool call is exactly "a browser.command
+ * with no tool.handler for that callId, ever" — the invariant that located a real hang. A clean run
+ * emitting 23 of them makes the invariant unusable and hides the next hang in its own noise.
+ *
+ * Returns `fn` unchanged when there is no call to bind to, so a caller outside a span is not given a
+ * fabricated parent.
+ */
+export declare function bindSpanContext<A extends unknown[]>(fn: (...args: A) => void): (...args: A) => void;
+/**
+ * Run `fn` as a named stage, recording how long it took and how it sat inside the call around it.
+ *
+ * Wrap a stage worth a line in a bottleneck hunt — a session resolve, a browser round-trip, a
+ * predicate evaluation — not every function. The value of the trace is that reading it is faster
+ * than reading the code, and that stops being true somewhere around one line per statement.
+ */
+export declare function span<T>(name: string, fields: Record<string, unknown>, fn: () => Promise<T> | T): Promise<T>;
+/**
+ * The synchronous form. Same line, same tree, same cost when off.
+ *
+ * It exists because `reticle init` — the flow every user hits before anything else, and the one
+ * whose slowness they experience personally — is synchronous end to end. An async-only span left
+ * exactly that flow untraceable.
+ */
+export declare function spanSync<T>(name: string, fields: Record<string, unknown>, fn: () => T): T;

package/dist/trace.js

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

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

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

package/dist/update/nudge-credit.js

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

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

@@ -0,0 +1,21 @@
+/**
+ * The half of `reticle update` that was missing: bringing the APP's SDK to the same version as the
+ * daemon being installed.
+ *
+ * `reticle update` swapped the CLI and stopped. The app kept whatever `@reticlehq/react` it had, so
+ * the command whose job is to keep an install current was itself a way to create a version-skewed
+ * pair — the failure the HELLO skew check, the nudge and the pin all exist to prevent. The skew
+ * message even told people to run `reticle update` to fix an outdated SDK, which could not work.
+ *
+ * Pinned to an exact version for the same reason `init` pins: an unpinned `add` can resolve out of a
+ * stale registry cache and reinstall the skew being fixed. Measured once as pnpm taking 2.2.1 while
+ * npm took 2.3.0 in the next project over.
+ */
+import { type PackageManager } from '../init/detect.js';
+/** The Reticle packages this project declares, from either dependency section. */
+export declare function reticleDepsOf(pkgJson: unknown): string[];
+/** The install to run, or null when this project has nothing of ours to sync. */
+export declare function sdkSyncCommand(pm: PackageManager, packages: readonly string[], version: string): {
+    command: string;
+    args: string[];
+} | null;

package/dist/update/sdk-sync.js

@@ -0,0 +1,42 @@
+/**
+ * The half of `reticle update` that was missing: bringing the APP's SDK to the same version as the
+ * daemon being installed.
+ *
+ * `reticle update` swapped the CLI and stopped. The app kept whatever `@reticlehq/react` it had, so
+ * the command whose job is to keep an install current was itself a way to create a version-skewed
+ * pair — the failure the HELLO skew check, the nudge and the pin all exist to prevent. The skew
+ * message even told people to run `reticle update` to fix an outdated SDK, which could not work.
+ *
+ * Pinned to an exact version for the same reason `init` pins: an unpinned `add` can resolve out of a
+ * stale registry cache and reinstall the skew being fixed. Measured once as pnpm taking 2.2.1 while
+ * npm took 2.3.0 in the next project over.
+ */
+import { installCommandParts } from '../init/detect.js';
+/** Everything we publish is scoped here. */
+const RETICLE_SCOPE = '@reticlehq/';
+/**
+ * The CLI. Never an app dependency: it carries the Node MCP server and `ws`, and putting it in a
+ * browser app's tree is what the retired `@reticlehq/core` umbrella got wrong. The other half of
+ * `reticle update` owns this one.
+ */
+const SERVER_PACKAGE = '@reticlehq/server';
+function namesIn(section) {
+    if ('object' !== typeof section || null === section)
+        return [];
+    return Object.keys(section);
+}
+/** The Reticle packages this project declares, from either dependency section. */
+export function reticleDepsOf(pkgJson) {
+    if ('object' !== typeof pkgJson || null === pkgJson)
+        return [];
+    const manifest = pkgJson;
+    const declared = [...namesIn(manifest['dependencies']), ...namesIn(manifest['devDependencies'])];
+    return [...new Set(declared)].filter((name) => name.startsWith(RETICLE_SCOPE) && name !== SERVER_PACKAGE);
+}
+/** The install to run, or null when this project has nothing of ours to sync. */
+export function sdkSyncCommand(pm, packages, version) {
+    if (0 === packages.length)
+        return null;
+    const { command, args } = installCommandParts(pm, packages.map((p) => `${p}@${version}`));
+    return { command, args: [...args] };
+}

package/dist/update/update-checker.js

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

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

@@ -1,4 +1,14 @@
-export interface UpdateNudge {
+/**
+ * Is `candidate` a strictly NEWER release than `current`?
+ *
+ * Replaces a plain `!==`, which told anyone on a version newer than the published one — a
+ * prerelease, a local build, a rollback in progress — to "update" to something older. A nudge that
+ * prompts a downgrade is one people learn to ignore, and this is the mechanism the entire adoption
+ * story rests on. Numeric per segment, so 2.10.0 correctly beats 2.9.0 (string order does not), and
+ * a bare release beats its own prerelease.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+interface UpdateNudge {
     /** The version available, so the agent can tell the human what they would be moving to. */
     latestVersion: string;
     currentVersion: string;
@@ -7,14 +17,61 @@ export interface UpdateNudge {
     action: string;
 }
 /**
- * Kick off a background check. Non-blocking and best-effort: `checkForUpdate` never throws, caches
- * for 24h on disk, and falls back to the cached manifest when the registry is unreachable — so this
- * costs one npm registry request per day per machine, and nothing at all when offline.
+ * Describe the release, not just its number.
+ *
+ * `packages/server/package.json` carries `reticle.changelog` and `reticle.breakingChanges`, and
+ * `update-checker` parses both into the manifest — where they stopped. This function named two
+ * versions and nothing else, so both fields were written, shipped, parsed and discarded. Latent
+ * metadata nobody ever printed.
+ *
+ * Survivable while releases are additive; actively harmful for one that is not. An agent told only
+ * "2.4.1 → 2.5.0" runs `reticle update` mid-task and discovers a retired environment variable and
+ * six newly-strict parameters by breaking on them.
+ *
+ * Bounded on purpose: this rides on a tool result every turn until it is delivered, so a long
+ * changelog is a per-turn tax. The count of anything elided is stated rather than silently dropped.
  */
+export declare function buildNudge(latestVersion: string, currentVersion: string, release?: {
+    changelog?: string;
+    breakingChanges?: string[];
+}): UpdateNudge;
 export declare function startUpdateCheck(now?: () => number): void;
+/**
+ * What `reticle update` should install, or undefined when it should do nothing.
+ *
+ * `handleUpdate` gated on `manifest.updateAvailable`, a plain `latest !== current`, so whenever the
+ * registry's latest was OLDER than the running build — a prerelease, a local build, a rollback in
+ * progress, a stale npx cache — it announced the move and then installed the downgrade. Reported by
+ * a real user on 2026-08-06: "both the `update_available` banner and `reticle update` report the
+ * current and target versions swapped, so an upgrade is described as a downgrade."
+ */
+export declare function updateTarget(manifest: {
+    updateAvailable?: boolean;
+    latestVersion?: string;
+}, currentVersion?: string): string | undefined;
+/**
+ * Arm from an already-cached answer, synchronously, at daemon boot.
+ *
+ * The network check fires 8s after boot and the nudge is delivered by riding a tool result — but
+ * half the sessions that use Reticle at all make exactly ONE tool call, usually in the first
+ * seconds. The check had not finished, so the single chance to tell them was gone, and the
+ * population most in need of the update is precisely the one that never heard about it. Yesterday's
+ * answer is already on disk; use it now and let the network refresh behind it.
+ */
+export declare function armUpdateNudgeFrom(cached: {
+    latestVersion?: string;
+    updateAvailable?: boolean;
+    changelog?: string;
+    breakingChanges?: string[];
+} | null, currentVersion?: string): void;
 /** The nudge, once. Returns undefined afterwards so a long session is told exactly one time. */
 export declare function takeUpdateNudge(): UpdateNudge | undefined;
+/**
+ * The newer version, if the cached answer says there is one — WITHOUT consuming the agent's
+ * one-shot nudge. `reticle status` is a human reading a terminal; the two channels are separate
+ * audiences and must not steal each other's message.
+ */
+export declare function availableUpdate(currentVersion?: string): string | undefined;
 /** Tests only — drop the module state so each case starts clean. */
 export declare function resetUpdateNudge(): void;
-/** Tests only — seed a pending nudge without going near the network. */
-export declare function setPendingUpdate(nudge: UpdateNudge | undefined): void;
+export {};