@reticlehq/server 2.2.1 → 2.3.0

package/dist/tools/reconcile-tools.js

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { EventType, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { ReticleTool } from './tool-names.js';
+import { reconcile } from '../events/reconcile.js';
+import { salvageJson } from '../events/json-salvage.js';
+import { withControl } from '../session/control-envelope.js';
+import { asNumber, asString } from './tools-helpers.js';
+import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+/**
+ * Does the screen agree with the data the app was given?
+ *
+ * A separate tool rather than a passive contradiction rule, because it needs the rendered page as
+ * well as the events — a comparison, not an observation. Passive rules stay pure and run on every
+ * window; this one costs a snapshot, so the agent asks for it.
+ *
+ * It exists because the misses that mattered on a real payments dashboard were all this shape: a USD
+ * amount rendered with a rupee sign, a settlement the API calls `on_hold` rendered as "pending". No
+ * request fails, no assertion fails, and the numbers on screen match the numbers in the payload. The
+ * only thing that disagrees is the meaning.
+ */
+/** Response bodies captured in the window, newest last. Only JSON is worth comparing. */
+async function capturedBodies(session, since, urlContains) {
+    const events = (await session.queryEvents({ since }));
+    const bodies = [];
+    let withBody = 0;
+    let total = 0;
+    let truncated = 0;
+    for (const event of events) {
+        if (event.type !== EventType.NET_REQUEST)
+            continue;
+        const url = typeof event.data['url'] === 'string' ? event.data['url'] : '';
+        if (urlContains !== undefined && !url.includes(urlContains))
+            continue;
+        total += 1;
+        const raw = event.data['responseBody'];
+        if (typeof raw !== 'string' || raw.length === 0)
+            continue;
+        // A capped body is not an absent one. Recover the records that closed before the cut rather than
+        // reporting nothing about the page with the most data on it.
+        const salvaged = salvageJson(raw);
+        if (salvaged.values.length === 0)
+            continue;
+        bodies.push(...salvaged.values);
+        withBody += 1;
+        if (salvaged.partial)
+            truncated += 1;
+    }
+    return { bodies, withBody, total, truncated };
+}
+export const RECONCILE_TOOLS = [
+    {
+        name: ReticleTool.RECONCILE,
+        example: { urlContains: '/api/v1/settlements' },
+        description: 'Compare what the API returned against what the page RENDERS. Catches the class no status code and no assertion can: a USD amount shown with a ₹ sign, a record the API calls `on_hold` displayed as "pending". Needs response bodies — enable `captureNetworkBodies` — and says so when they are missing rather than reporting a clean result over data it never read.',
+        inputSchema: {
+            ...sessionIdShape,
+            since: z
+                .number()
+                .optional()
+                .describe('Cursor from a prior act — scopes to responses received after it. Default: 0.'),
+            urlContains: z
+                .string()
+                .optional()
+                .describe('Only compare responses from URLs containing this, e.g. "/api/v1/settlements".'),
+        },
+        outputSchema: {
+            mismatches: z
+                .array(z.object({ entity: z.string(), field: z.string(), api: z.string() }).passthrough())
+                .describe('Fields whose rendering disagrees with the data the app was given.'),
+            compared: z.number().describe('How many responses carried a body that could be compared.'),
+            note: z
+                .string()
+                .optional()
+                .describe('Present when nothing could be compared — never silent about an empty check.'),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const since = asNumber(args['since']) ?? 0;
+            const { bodies, withBody, total, truncated } = await capturedBodies(session, since, asString(args['urlContains']));
+            // An empty result over data that was never read is the exact false green this tool exists to
+            // prevent, so the two cases are reported differently and neither is silent.
+            if (bodies.length === 0) {
+                return withControl(session, {
+                    mismatches: [],
+                    compared: 0,
+                    note: total === 0
+                        ? 'no responses in this window matched — nothing was compared'
+                        : `${String(total)} response(s) matched but NONE carried a recorded body, so nothing was compared. Enable it where your app calls connect(): \`reticle.connect({ captureNetworkBodies: true })\`, then re-run`,
+                });
+            }
+            const snapshot = await commandOrThrow(deps, session.id, ReticleCommand.SNAPSHOT, {
+                mode: SnapshotMode.FULL,
+            });
+            const tree = snapshot.tree;
+            const mismatches = reconcile(bodies, typeof tree === 'string' ? tree : '');
+            // A truncated body is declared whether or not anything was found in it: "no mismatches" over a
+            // partially-read payload is a weaker statement than over a whole one, and the difference is
+            // exactly the kind of omission this layer exists to refuse.
+            const partial = truncated > 0
+                ? {
+                    note: `${String(truncated)} of ${String(withBody)} response(s) exceeded the body cap and were read only up to the cut — records after it were not compared`,
+                }
+                : mismatches.length === 0
+                    ? {
+                        note: `compared ${String(withBody)} response(s); nothing on screen contradicts them`,
+                    }
+                    : {};
+            return withControl(session, { mismatches, compared: withBody, ...partial });
+        },
+    },
+];

package/dist/tools/snapshot-delta.d.ts

@@ -58,4 +58,3 @@ export interface SnapshotDeltaOpts {
  * the pure `snapshotDelta`.
  */
 export declare function applySnapshotDelta(raw: unknown, opts: SnapshotDeltaOpts, cache: SnapshotCache): unknown;
-//# sourceMappingURL=snapshot-delta.d.ts.map

package/dist/tools/tool-invoker.d.ts

@@ -12,4 +12,3 @@ export type ToolInvoker = (toolName: string, args: Record<string, unknown>) => P
  * (the MCP `{ isError, content }` envelope is a transport concern this layer deliberately skips).
  */
 export declare function createToolInvoker(deps: ToolDeps): ToolInvoker;
-//# sourceMappingURL=tool-invoker.d.ts.map

package/dist/tools/tool-invoker.js

@@ -17,4 +17,3 @@ export function createToolInvoker(deps) {
         return runTool(tool, deps, args);
     };
 }
-//# sourceMappingURL=tool-invoker.js.map

package/dist/tools/tool-kit.d.ts

@@ -46,6 +46,22 @@ export interface ToolDef {
      * compose tool calls safely. Also drives TOON encoding for snapshot/query results.
      */
     outputSchema?: z.ZodRawShape;
+    /**
+     * One concrete, valid call — the shape, not the prose.
+     *
+     * A schema tells an agent the FIELD NAMES; it does not tell it how they compose, and under a lean
+     * profile only the first sentence of the description survives. So an agent reads "execute one
+     * action against a ref", sees `ref` / `action` / `args`, and guesses `{ action, testid }`. The
+     * guess fails inside the MCP SDK's own validation — BEFORE this package's error handling runs — so
+     * what comes back is a raw zod dump: the validator's internal state, naming no field and showing
+     * no correct shape. Two of those round trips cost more than the lean snapshot saves, which means
+     * arg-guessing quietly refunds the entire token advantage.
+     *
+     * Rendered into the advertised description, so it survives the terse profiles where it matters
+     * most. `tool-examples.test.ts` parses every one of these against its OWN inputSchema, because an
+     * example that does not validate is worse than none at all.
+     */
+    example?: Record<string, unknown>;
     handler: (deps: ToolDeps, args: Record<string, unknown>) => Promise<unknown>;
 }
 export declare const sessionIdShape: {
@@ -66,4 +82,3 @@ export declare function snapshotTree(deps: ToolDeps, sessionId: string | undefin
     lines: string[];
     route: string;
 }>;
-//# sourceMappingURL=tool-kit.d.ts.map

package/dist/tools/tool-kit.js

@@ -11,7 +11,7 @@ export const sessionIdShape = {
     sessionId: z
         .string()
         .optional()
-        .describe('Active session ID from reticle_sessions. Omit when only one browser session is open — Reticle resolves it automatically.'),
+        .describe('OMIT THIS unless you mean a specific tab — Reticle scopes to your project, prefers the active one, and refuses rather than guesses when ambiguous. Pass an id from reticle_sessions only to target a particular tab. The previous wording ("omit when only ONE session is open") was wrong and cost real turns: with three sessions connected — an app plus two pool leases — resolution is still unambiguous, but that sentence sent the agent off to list and filter sessions by hand before every single call.'),
 };
 /**
  * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime
@@ -32,6 +32,13 @@ export const sessionEnvelopeShape = {
     // That is exactly what invoke-tool.ts's health splice exists to prevent, so it belongs in the shared
     // envelope, not per-tool.
     warning: z.string().optional(),
+    // The one-shot "ask the human how this went" envelope. Undeclared, a validating profile would strip
+    // it — and a feedback prompt that never reaches the agent is a feedback prompt that never reaches
+    // the person, which is the entire failure mode this channel exists to fix.
+    feedback_prompt: z.unknown().optional(),
+    // One-shot "a newer Reticle exists" notice. Undeclared, a validating profile would strip it and the
+    // agent would never learn an update was waiting.
+    update_available: z.unknown().optional(),
 };
 /** Unwrap a browser command result or throw its error so the agent sees a clean failure. */
 export async function commandOrThrow(deps, sessionId, 
@@ -53,4 +60,3 @@ export async function snapshotTree(deps, sessionId) {
     const snap = (result.result ?? {});
     return { lines: normalizeLines(snap.tree ?? ''), route: snap.status?.route ?? '' };
 }
-//# sourceMappingURL=tool-kit.js.map

package/dist/tools/tool-names.d.ts

@@ -15,6 +15,7 @@ export declare const ReticleTool: {
     readonly CONSOLE: "reticle_console";
     readonly ANIMATIONS: "reticle_animations";
     readonly ASSERT: "reticle_assert";
+    readonly RECONCILE: "reticle_reconcile";
     readonly BASELINE_SAVE: "reticle_baseline_save";
     readonly BASELINE_LIST: "reticle_baseline_list";
     readonly DIFF: "reticle_diff";
@@ -42,6 +43,9 @@ export declare const ReticleTool: {
     readonly FLOW_HEAL: "reticle_flow_heal";
     /** structured annotation → compiles into the recording's expect/dynamic/success. */
     readonly ANNOTATE: "reticle_annotate";
+    readonly AFFECTED: "reticle_affected";
+    readonly COVERAGE: "reticle_coverage";
+    readonly VERIFY_CHANGE: "reticle_verify_change";
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     readonly PROJECT: "reticle_project";
     /** explicitly record a run outcome (the manual companion to auto-recording). */
@@ -94,6 +98,7 @@ export declare const ReticleTool: {
     readonly TOOLS: "reticle_tools";
     /** Meta: invoke any tool by name — the escape hatch that keeps a trimmed profile a trim, not a removal. */
     readonly RUN: "reticle_run";
+    /** Report that Reticle itself failed — the agent's only way to tell us what to fix. */
+    readonly FEEDBACK: "reticle_feedback";
 };
 export type ReticleTool = (typeof ReticleTool)[keyof typeof ReticleTool];
-//# sourceMappingURL=tool-names.d.ts.map

package/dist/tools/tool-names.js

@@ -16,6 +16,7 @@ export const ReticleTool = {
     CONSOLE: 'reticle_console',
     ANIMATIONS: 'reticle_animations',
     ASSERT: 'reticle_assert',
+    RECONCILE: 'reticle_reconcile',
     BASELINE_SAVE: 'reticle_baseline_save',
     BASELINE_LIST: 'reticle_baseline_list',
     DIFF: 'reticle_diff',
@@ -43,6 +44,9 @@ export const ReticleTool = {
     FLOW_HEAL: 'reticle_flow_heal',
     /** structured annotation → compiles into the recording's expect/dynamic/success. */
     ANNOTATE: 'reticle_annotate',
+    AFFECTED: 'reticle_affected',
+    COVERAGE: 'reticle_coverage',
+    VERIFY_CHANGE: 'reticle_verify_change',
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     PROJECT: 'reticle_project',
     /** explicitly record a run outcome (the manual companion to auto-recording). */
@@ -95,5 +99,6 @@ export const ReticleTool = {
     TOOLS: 'reticle_tools',
     /** Meta: invoke any tool by name — the escape hatch that keeps a trimmed profile a trim, not a removal. */
     RUN: 'reticle_run',
+    /** Report that Reticle itself failed — the agent's only way to tell us what to fix. */
+    FEEDBACK: 'reticle_feedback',
 };
-//# sourceMappingURL=tool-names.js.map

package/dist/tools/tools-helpers.d.ts

@@ -21,4 +21,3 @@ export declare function sourceOf(value: unknown): {
     column?: number;
 } | undefined;
 export {};
-//# sourceMappingURL=tools-helpers.d.ts.map

package/dist/tools/tools-helpers.js

@@ -39,4 +39,3 @@ export function sourceOf(value) {
         out.column = record['column'];
     return out;
 }
-//# sourceMappingURL=tools-helpers.js.map

package/dist/tools/tools.d.ts

@@ -1,4 +1,3 @@
 import { type ToolDef } from './tool-kit.js';
 export type { ToolDef, ToolDeps } from './tool-kit.js';
 export declare const TOOLS: ToolDef[];
-//# sourceMappingURL=tools.d.ts.map

package/dist/tools/tools.js

@@ -12,6 +12,9 @@ import { FLOW_TOOLS } from '../flows/flow-tools.js';
 import { PROJECT_TOOLS } from '../project/project-tools.js';
 import { RUN_TOOLS } from '../runs/run-tools.js';
 import { VISUAL_TOOLS } from '../visual/visual-tools.js';
+import { AFFECTED_TOOLS } from '../flows/affected-tools.js';
+import { COVERAGE_TOOLS } from './coverage-tools.js';
+import { VERIFY_CHANGE_TOOLS } from '../flows/verify-change-tools.js';
 import { CRAWL_TOOLS } from '../crawl/crawl-tools.js';
 import { SCROLL_TOOLS } from '../input/scroll-tools.js';
 import { NETWORK_MOCK_TOOLS } from '../input/network-mock-tools.js';
@@ -23,8 +26,10 @@ import { sessionIdShape, commandOrThrow } from './tool-kit.js';
 import { applyMerges } from './merge-tools.js';
 import { ACT_TOOLS } from './act-tools.js';
 import { OBSERVE_TOOLS } from './observe-tools.js';
+import { RECONCILE_TOOLS } from './reconcile-tools.js';
 import { READ_TOOLS } from './read-tools.js';
 import { LEASE_TOOLS } from './lease-tools.js';
+import { FEEDBACK_TOOLS } from './feedback-tools.js';
 /** Per-server last-snapshot cache backing reticle_snapshot's diff:true delta mode (route-invalidated). */
 const SNAPSHOT_CACHE = new SnapshotCache();
 const RAW_TOOLS = [
@@ -71,7 +76,8 @@ const RAW_TOOLS = [
     },
     {
         name: ReticleTool.SNAPSHOT,
-        description: 'Semantic accessibility snapshot of the page or a subtree. mode: full|interactive|status. Use to see what is on screen right now. The result carries cost:{ bytes, tokens } (estimated) — if it is large, re-scope (pass `scope`) or use mode:interactive/status instead of reading the whole tree. Pass diff:true after your first snapshot to get back ONLY what changed since your last look (mode:delta with added/removed, or mode:unchanged) — far fewer tokens and no stale tree to mis-read; a route change resets it to a full snapshot automatically.',
+        example: { diff: true },
+        description: 'Semantic accessibility snapshot of the page or a subtree — `mode:"interactive"` returns only the controls, ~3x smaller. Refs (`e42`) are stable: the same element keeps its ref across snapshots and only stops resolving once it leaves the DOM — re-snapshot after a navigation or if a ref fails to resolve, not between ordinary actions. mode: full|interactive|status. Use to see what is on screen right now. The result carries cost:{ bytes, tokens } (estimated) — if it is large, re-scope (pass `scope`) or use mode:interactive/status instead of reading the whole tree. Pass diff:true after your first snapshot to get back ONLY what changed since your last look (mode:delta with added/removed, or mode:unchanged) — far fewer tokens and no stale tree to mis-read; a route change resets it to a full snapshot automatically.',
         inputSchema: {
             scope: z
                 .string()
@@ -151,7 +157,8 @@ const RAW_TOOLS = [
     },
     {
         name: ReticleTool.QUERY,
-        description: 'Find elements by Testing-Library semantics, INCLUDING inside open shadow roots. 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.',
+        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.',
         inputSchema: {
             by: z.string().describe('Query strategy: role | text | label | placeholder | testid | alt'),
             value: z
@@ -171,6 +178,7 @@ const RAW_TOOLS = [
                 .describe("Attribute names to return per match, e.g. ['href'] to inventory links or ['src'] for images. Absent attributes are omitted; credential-bearing names are redacted."),
             limit: z
                 .number()
+                .nonnegative()
                 .optional()
                 .describe('Cap the returned descriptors to the first N (cuts tokens on broad queries). If more matched, the result carries total + truncated:true so the trim is never silent — narrow with name/scope.'),
             count_only: z
@@ -262,9 +270,12 @@ const RAW_TOOLS = [
     },
     {
         name: ReticleTool.INSPECT,
+        example: { ref: 'e42' },
         description: 'Deep info on one element by ref: full a11y props, visibility, box, and (with @reticlehq/react) component stack + source file.',
         inputSchema: {
-            ref: z.string().describe("Element ref from reticle_snapshot or reticle_query (e.g. 'e42')."),
+            ref: z
+                .string()
+                .describe(`Element ref (e.g. 'e42') from reticle_snapshot/reticle_query — stable until the element leaves the DOM, so no re-snapshot between actions.`),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -325,6 +336,7 @@ const RAW_TOOLS = [
         }),
     },
     // reticle_capabilities (live | fromDisk) + reticle_contract_save. See contract-tools.ts.
+    ...RECONCILE_TOOLS,
     ...CONTRACT_TOOLS,
     ...DOMAIN_TOOLS,
     // reticle_flow_save / reticle_flow_list / reticle_flow_load. See flow-tools.ts.
@@ -345,6 +357,13 @@ const RAW_TOOLS = [
     ...SESSION_TOOLS,
     // reticle_annotate (structured annotation → expect/dynamic/success). See annotate-tools.ts.
     ...ANNOTATE_TOOLS,
+    // reticle_affected — which saved flows a diff invalidates. Unadvertised (zero per-turn cost),
+    // reachable through reticle_run. See affected-tools.ts.
+    ...AFFECTED_TOOLS,
+    // reticle_coverage — which controls were driven vs never touched. Unadvertised; via reticle_run.
+    ...COVERAGE_TOOLS,
+    // reticle_verify_change — "did my change break anything" in one call. See verify-change-tools.ts.
+    ...VERIFY_CHANGE_TOOLS,
     // Live-control: reticle_end_session / reticle_resume / reticle_messages. See live-control-tools.ts.
     ...LIVE_CONTROL_TOOLS,
     // reticle_navigate / reticle_refresh — browser navigation tools. See browser-tools.ts.
@@ -353,6 +372,8 @@ const RAW_TOOLS = [
     ...OBSERVE_TOOLS,
     ...READ_TOOLS,
     ...LEASE_TOOLS,
+    // reticle_feedback — the agent reports that RETICLE failed (not that the app did). See feedback-tools.ts.
+    ...FEEDBACK_TOOLS,
 ];
 /**
  * surface consolidation. Tool defs are re-sent EVERY turn, so the advertised count is a per-turn
@@ -415,4 +436,3 @@ const RETIRED_FROM_SURFACE = [
     ReticleTool.WAIT_READY, // server-internal: the first live call already blocks for the session
 ];
 export const TOOLS = applyMerges(RAW_TOOLS, MERGE_PLANS, RETIRED_FROM_SURFACE);
-//# sourceMappingURL=tools.js.map

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

@@ -30,4 +30,3 @@ export interface UpdateCheckPorts {
  */
 export declare function checkForUpdate(currentVersion: string, now: () => number, ports?: UpdateCheckPorts): Promise<UpdateManifest>;
 export {};
-//# sourceMappingURL=update-checker.d.ts.map

package/dist/update/update-checker.js

@@ -120,4 +120,3 @@ export async function checkForUpdate(currentVersion, now, ports = defaultPorts)
         };
     }
 }
-//# sourceMappingURL=update-checker.js.map

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

@@ -0,0 +1,20 @@
+export 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;
+}
+/**
+ * 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.
+ */
+export declare function startUpdateCheck(now?: () => number): void;
+/** The nudge, once. Returns undefined afterwards so a long session is told exactly one time. */
+export declare function takeUpdateNudge(): UpdateNudge | 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;

package/dist/update/update-nudge.js

@@ -0,0 +1,72 @@
+/**
+ * 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 } from './update-checker.js';
+import { SERVER_VERSION } from '../server-version.js';
+import { log } from '../log.js';
+/** 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.
+ */
+export function startUpdateCheck(now = () => Date.now()) {
+    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.',
+            };
+            log('reticle_update_available', {
+                from: SERVER_VERSION,
+                to: manifest.latestVersion,
+            });
+        })
+            .catch(() => {
+            /* a version check must never surface to a user */
+        });
+    }, CHECK_DELAY_MS).unref();
+}
+/** 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;
+    return pending;
+}
+/** 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,3 +1,17 @@
+/** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */
+export declare const VersionChangeDirection: {
+    readonly UPDATE: "update";
+    readonly ROLLBACK: "rollback";
+};
+export type VersionChangeDirection = (typeof VersionChangeDirection)[keyof typeof VersionChangeDirection];
+/**
+ * Report a completed version move. Never throws — an install that worked must still be reported done.
+ *
+ * Exported so the emit path can be exercised directly: `applyUpdate`/`rollback` both run a real npm
+ * install and then `process.exit`, so there is no way to reach this through them in a test without
+ * mocking the package manager and the process itself.
+ */
+export declare function reportVersionChange(from: string, to: string, direction: VersionChangeDirection): Promise<void>;
 /** How this reticle process was launched — determines which npm strategy to use for updates. */
 declare const ExecutionKind: {
     /** Launched via `npx @reticlehq/server` — npm re-resolves the package on restart. */
@@ -46,4 +60,3 @@ export declare function applyUpdate(targetVersion: string): Promise<void>;
  */
 export declare function rollback(): Promise<void>;
 export {};
-//# sourceMappingURL=updater.d.ts.map

package/dist/update/updater.js

@@ -3,8 +3,32 @@ 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 } from '../server-version.js';
+import { RETICLE_NPM_PACKAGE, SERVER_VERSION } from '../server-version.js';
 import { log } from '../log.js';
+import { TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from '../telemetry/telemetry.js';
+/** Which way the installed version moved. A rollback means a release hurt someone enough to retreat. */
+export const VersionChangeDirection = {
+    UPDATE: 'update',
+    ROLLBACK: 'rollback',
+};
+/**
+ * Report a completed version move. Never throws — an install that worked must still be reported done.
+ *
+ * Exported so the emit path can be exercised directly: `applyUpdate`/`rollback` both run a real npm
+ * install and then `process.exit`, so there is no way to reach this through them in a test without
+ * mocking the package manager and the process itself.
+ */
+export async function reportVersionChange(from, to, direction) {
+    try {
+        await getTelemetry().emit(TelemetryEventKind.VERSION_CHANGED, {
+            versionChange: { from, to, direction },
+        });
+    }
+    catch {
+        /* best-effort, like every other send */
+    }
+}
 const NPM_BIN = platform() === 'win32' ? 'npm.cmd' : 'npm';
 const NPM_TIMEOUT_MS = 120_000;
 /** How this reticle process was launched — determines which npm strategy to use for updates. */
@@ -129,6 +153,11 @@ export async function applyUpdate(targetVersion) {
     log('reticle_update_applying', { version: targetVersion, executionKind: kind });
     await installVersion(targetVersion, kind);
     log('reticle_update_applied', { version: targetVersion, executionKind: kind });
+    // Emitted AFTER the install succeeded, so the metric counts versions that actually landed rather
+    // than attempts. Awaited, unlike every other send in the product: `process.exit(0)` on the next
+    // line would kill an in-flight fire-and-forget POST, and this event is rare enough that the wait
+    // costs nothing. A failed send still cannot block the exit — `emit` swallows its own errors.
+    await reportVersionChange(SERVER_VERSION, targetVersion, VersionChangeDirection.UPDATE);
     process.exit(0);
 }
 /**
@@ -145,10 +174,12 @@ export async function rollback() {
     log('reticle_rollback_applying', { version: prev, executionKind: kind });
     await installVersionRollback(prev, kind);
     log('reticle_rollback_applied', { version: prev, executionKind: kind });
+    // A rollback is a release-quality alarm — someone shipped something that broke a real user badly
+    // enough for them to go backwards. Worth knowing about within the hour, not at the next retro.
+    await reportVersionChange(SERVER_VERSION, prev, VersionChangeDirection.ROLLBACK);
     // For npx, exiting would let the next restart re-resolve @latest — rolling FORWARD, the opposite
     // of rollback. installVersionRollback already told the user to pin the version in.mcp.json, so
     // stay running rather than trigger that. Other kinds installed the old version and must restart.
     if (kind !== ExecutionKind.NPX)
         process.exit(0);
 }
-//# sourceMappingURL=updater.js.map

package/dist/visual/visual-diff.d.ts

@@ -43,4 +43,3 @@ export interface VisualDiffResult {
  * mismatch is a hard fail (can't pixel-diff) reported as `dimensionMismatch`, never a throw.
  */
 export declare function diffPng(baselineBytes: Uint8Array, currentBytes: Uint8Array, opts?: DiffOptions): Promise<VisualDiffResult>;
-//# sourceMappingURL=visual-diff.d.ts.map

package/dist/visual/visual-diff.js

@@ -97,4 +97,3 @@ export async function diffPng(baselineBytes, currentBytes, opts = {}) {
     };
     return region === undefined ? result : { ...result, region };
 }
-//# sourceMappingURL=visual-diff.js.map

package/dist/visual/visual-store.d.ts

@@ -20,4 +20,3 @@ export declare class VisualStore {
     /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
     saveDiff(name: string, png: Uint8Array): Promise<string>;
 }
-//# sourceMappingURL=visual-store.d.ts.map

package/dist/visual/visual-store.js

@@ -62,4 +62,3 @@ export class VisualStore {
         return path;
     }
 }
-//# sourceMappingURL=visual-store.js.map

package/dist/visual/visual-tools.d.ts

@@ -6,4 +6,3 @@ import type { ToolDef } from '../tools/tools.js';
  * stay the default; this is the complementary "does it look right" surface, never bundled in.
  */
 export declare const VISUAL_TOOLS: ToolDef[];
-//# sourceMappingURL=visual-tools.d.ts.map