@reticlehq/server 2.12.0 → 2.13.1

package/dist/tools/reconcile-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { EventType, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { EventType, ReticleCommand, SnapshotMode, urlForMatch } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
+import { cursorSchema } from './numeric-bounds.js';
 import { reconcile } from '../events/reconcile.js';
 import { salvageJson } from '../events/json-salvage.js';
 import { withControl } from '../session/control-envelope.js';
@@ -29,7 +30,7 @@ async function capturedBodies(session, since, urlContains) {
     for (const event of events) {
         if (event.type !== EventType.NET_REQUEST)
             continue;
-        const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
+        const url = urlForMatch(event.data);
         if (urlContains !== undefined && !url.includes(urlContains))
             continue;
         total += 1;
@@ -55,8 +56,7 @@ export const RECONCILE_TOOLS = [
         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()
+            since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior act — scopes to responses received after it. Default: 0.'),
             urlContains: z

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

@@ -56,6 +56,18 @@ export interface ToolDeps<Ext = unknown> {
      * exactly today's behaviour.
      */
     artifactRootFor?: (projectId: string | undefined) => ArtifactRoot;
+    /**
+     * A verification run just landed — wake cloud sync instead of waiting for its next tick.
+     *
+     * The run itself is pushed immediately on this path, but everything AROUND it — the impact
+     * counters, the flows it exercised, flake and intent — moves only on the timer. That is what
+     * produced a dashboard showing a fresh run beside stale numbers, which reads as a sync bug and is
+     * really just two different clocks. Waking the loop here makes the run and its context arrive
+     * together.
+     *
+     * Optional: absent ⇒ the timer alone, which is exactly today's behaviour.
+     */
+    onRunPersisted?: () => void;
     /**
      * This daemon's OWN project id, derived from the directory it was started in.
      *

package/dist/tools/tool-kit.js

@@ -21,7 +21,12 @@ import { normalizeLines } from '../project/baselines.js';
 export const intentArg = z
     .string()
     .optional()
-    .describe('What this change is meant to make true, in your own words, or the id of an intent you already declared. ' +
+    .describe('What this change is meant to make true — as a durable statement ABOUT THE PRODUCT, or the id of an intent you already declared. ' +
+    'Write it so a teammate who was not here understands it in six months: name the behaviour, not this run. ' +
+    'GOOD: "a filtered issue queue is a shareable link — the filter is in the URL". ' +
+    'BAD: "P1 step 5", "drive 2 of 2", "same as before the fix", "the board renders cleanly" — these name a session, ' +
+    'a step number or nothing checkable, and the person reading them later has none of that context. ' +
+    'This is shared memory: it is pooled per project and later agents read it back to avoid re-deriving what you just established. ' +
     'Recorded in .reticle/intent.json, the same ledger reticle_intent writes, and marked proved by this verdict if it passes.');
 export const sessionIdShape = {
     sessionId: z

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

@@ -53,6 +53,8 @@ export declare const ReticleTool: {
     readonly VERIFY: "reticle_verify";
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     readonly PROJECT: "reticle_project";
+    /** The team's shared memory, read on demand — see memory/memory-tools.ts. */
+    readonly MEMORY: "reticle_memory";
     /** explicitly record a run outcome (the manual companion to auto-recording). */
     readonly RUN_RECORD: "reticle_run_record";
     /** capture a pixel screenshot (CDP/driven browser) →.reticle/visual/<name>.png. */

package/dist/tools/tool-names.js

@@ -54,6 +54,8 @@ export const ReticleTool = {
     VERIFY: 'reticle_verify',
     /** read cross-run history (.reticle/project.json) + diff-vs-last for a name. */
     PROJECT: 'reticle_project',
+    /** The team's shared memory, read on demand — see memory/memory-tools.ts. */
+    MEMORY: 'reticle_memory',
     /** explicitly record a run outcome (the manual companion to auto-recording). */
     RUN_RECORD: 'reticle_run_record',
     /** capture a pixel screenshot (CDP/driven browser) →.reticle/visual/<name>.png. */

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

@@ -8,6 +8,25 @@ export declare function parseInteractive(tree: string): InteractiveItem[];
 export declare function asString(value: unknown): string | undefined;
 export declare function asNumber(value: unknown): number | undefined;
 export declare function asRecord(value: unknown): Record<string, unknown>;
+/**
+ * The session this call is aimed at: a top-level `sessionId`, or the same key on sequence steps.
+ *
+ * `reticle_act_sequence` describes each step as equivalent to one `reticle_act`, so an agent that
+ * learned the escape hatch on the single-action tool puts `sessionId` on the step. Reading only the
+ * top-level key then auto-selects a different tab, the step refs miss, and the refusal reads as a
+ * stale ref — a confident diagnosis of the wrong thing. Top-level still wins when both are given.
+ *
+ * Mixed step ids refuse rather than pick: two named tabs is a guess we will not make.
+ */
+export declare function sessionIdFromArgs(args: Record<string, unknown>): string | undefined;
+/**
+ * The ref this call is about to spend: a top-level `ref`, or the first sequence step's.
+ *
+ * Wrong-tab refusal keys off this. A sequence that only carries refs inside `steps` used to look
+ * like a call with no ref, so auto-selection could pick a different tab and the miss was blamed
+ * on the DOM.
+ */
+export declare function spentRefFromArgs(args: Record<string, unknown>): string | undefined;
 /**
  * A `{ file, line }` source location off an untrusted result payload, or undefined.
  *

package/dist/tools/tools-helpers.js

@@ -19,6 +19,52 @@ export function asNumber(value) {
 export function asRecord(value) {
     return 'object' === typeof value && value !== null ? value : {};
 }
+/**
+ * The session this call is aimed at: a top-level `sessionId`, or the same key on sequence steps.
+ *
+ * `reticle_act_sequence` describes each step as equivalent to one `reticle_act`, so an agent that
+ * learned the escape hatch on the single-action tool puts `sessionId` on the step. Reading only the
+ * top-level key then auto-selects a different tab, the step refs miss, and the refusal reads as a
+ * stale ref — a confident diagnosis of the wrong thing. Top-level still wins when both are given.
+ *
+ * Mixed step ids refuse rather than pick: two named tabs is a guess we will not make.
+ */
+export function sessionIdFromArgs(args) {
+    const top = asString(args['sessionId']);
+    if (top !== undefined)
+        return top;
+    const steps = args['steps'];
+    if (!Array.isArray(steps))
+        return undefined;
+    let found;
+    for (const raw of steps) {
+        const id = asString(asRecord(raw)['sessionId']);
+        if (id === undefined)
+            continue;
+        if (found !== undefined && found !== id) {
+            throw new Error(`reticle_act_sequence steps name different sessionIds ('${found}' and '${id}'). ` +
+                'Pass one sessionId at the top level to target a tab. Nothing was acted on.');
+        }
+        found = id;
+    }
+    return found;
+}
+/**
+ * The ref this call is about to spend: a top-level `ref`, or the first sequence step's.
+ *
+ * Wrong-tab refusal keys off this. A sequence that only carries refs inside `steps` used to look
+ * like a call with no ref, so auto-selection could pick a different tab and the miss was blamed
+ * on the DOM.
+ */
+export function spentRefFromArgs(args) {
+    const top = asString(args['ref']);
+    if (top !== undefined)
+        return top;
+    const steps = args['steps'];
+    if (!Array.isArray(steps) || 0 === steps.length)
+        return undefined;
+    return asString(asRecord(steps[0])['ref']);
+}
 /**
  * A `{ file, line }` source location off an untrusted result payload, or undefined.
  *

package/dist/tools/tools.d.ts

@@ -1,6 +1,8 @@
 import { type ToolDef } from './tool-kit.js';
 import { type MergePlan } from './merge-tools.js';
 export type { ToolDef, ToolDeps } from './tool-kit.js';
+/** Every handler, including tools retired from the advertised MCP surface. */
+export declare const RAW_TOOLS: ToolDef[];
 /**
  * surface consolidation. Tool defs are re-sent EVERY turn, so the advertised count is a per-turn
  * tax multiplied by loop length. Sibling families collapse into one action-dispatched tool; the member

package/dist/tools/tools.js

@@ -3,7 +3,8 @@ import { NoSessionAction, QueryBy, ReticleCommand, SnapshotMode } from '@reticle
 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 { asRecord, asString, asNumber } from './tools-helpers.js';
+import { countSchema } from './numeric-bounds.js';
 import { normalizeQueryArgs } from './query-shape.js';
 import { paginateQueryResult } from './query-paginate.js';
 /**
@@ -24,6 +25,7 @@ import { FLOW_TOOLS } from '../flows/flow-tools.js';
 import { INTENT_TOOLS } from '../intent/intent-tools.js';
 import { CONTEXT_TOOLS } from '../runs/context-tools.js';
 import { PROJECT_TOOLS } from '../project/project-tools.js';
+import { MEMORY_TOOLS } from '../memory/memory-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';
@@ -46,7 +48,8 @@ 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 = [
+/** Every handler, including tools retired from the advertised MCP surface. */
+export const RAW_TOOLS = [
     {
         name: ReticleTool.SESSIONS,
         description: 'List connected browser sessions (tab url/title, sessionId, last-seen, health: hidden/focused/throttled, and `realInputAvailable` — true when native CDP/launched real input is driving this tab), plus a `recommendation` naming the in-protocol escape hatch (`reticle_run { tool: "reticle_lease" }`, with `reticle drive` as the human-side equivalent) when a tab is hidden/throttled and may be un-scriptable from here.',
@@ -63,6 +66,10 @@ const RAW_TOOLS = [
                 title: z.string().optional(),
                 adapters: z.array(z.string()),
                 hasCapabilities: z.boolean(),
+                runtime: z
+                    .string()
+                    .optional()
+                    .describe("Which shell answered: web, electron or tauri. Absent on an SDK too old to report one — never defaulted, because a browser tab and a desktop window on the same url are otherwise indistinguishable and only one of them has the app's IPC."),
                 versionSkew: z
                     .string()
                     .optional()
@@ -75,6 +82,11 @@ const RAW_TOOLS = [
                 leased: z.boolean().optional(),
                 stale: z.boolean().optional(),
                 cleanup_suggestion: z.string().optional(),
+                unresponsive: z
+                    .literal(true)
+                    .optional()
+                    .describe('Present only when this tab is attached but has stopped answering commands: every call against it will time out. The other health fields still look fine, which is what makes this state invisible without the flag.'),
+                unresponsive_suggestion: z.string().optional(),
                 pendingMarks: z.number().optional(),
                 review_suggestion: z.string().optional(),
                 recommendation: z.string().optional(),
@@ -104,7 +116,7 @@ const RAW_TOOLS = [
                 reason: z.string(),
             })
                 .optional()
-                .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of start_dev_server | run_init | open_app | reopen_app."),
+                .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of daemon_split | start_dev_server | run_init | open_app | reopen_app. `daemon_split` outranks the rest and means the app IS running and instrumented, on a DIFFERENT daemon than the one you are attached to — do not start or re-init anything, read `reason`."),
         },
         handler: async (deps) => {
             const provider = deps.realInput;
@@ -221,12 +233,12 @@ const RAW_TOOLS = [
             return commandOrThrow(deps, resolved.id, ReticleCommand.SNAPSHOT, {
                 scope: args['scope'],
                 mode,
-            }).then((raw) => withSizeCost(applySnapshotDelta(raw, {
+            }).then((raw) => withSizeCost(noteEmptyLeanTree(applySnapshotDelta(raw, {
                 sessionId: resolved.id,
                 scope: asString(args['scope']) ?? '',
                 mode,
                 diff: true === args['diff'],
-            }, SNAPSHOT_CACHE)));
+            }, SNAPSHOT_CACHE), mode)));
         },
     },
     {
@@ -259,9 +271,7 @@ const RAW_TOOLS = [
                 .array(z.string())
                 .optional()
                 .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()
+            limit: countSchema
                 .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
@@ -336,6 +346,15 @@ const RAW_TOOLS = [
                     .describe('Structural clusters on the page — what IS here, to diagnose the miss.'),
                 presentTestids: z.array(z.string()).optional(),
                 knownEmptyState: z.boolean(),
+                splitText: z
+                    .object({
+                    ref: z.string().optional(),
+                    role: z.string().optional(),
+                    name: z.string().optional(),
+                })
+                    .passthrough()
+                    .optional()
+                    .describe("Present when a TEXT search missed but the string IS on the page, split across this container's children. Retry as { scope: <ref>, self: true } — no text query can match a string no single element owns."),
             })
                 .optional()
                 .describe('Present only on zero matches — tells you what IS on the page so you can diagnose the miss.'),
@@ -467,6 +486,7 @@ const RAW_TOOLS = [
     ...FLOW_TOOLS,
     // reticle_project (read history + diff-vs-last) / reticle_run_record. See project-tools.ts.
     ...PROJECT_TOOLS,
+    ...MEMORY_TOOLS,
     // reticle_run_export — export the verification-run verdict artifact (.reticle/runs/). See run-tools.ts.
     ...RUN_TOOLS,
     // reticle_screenshot / reticle_visual_diff — opt-in, CDP-driven. See visual-tools.ts.
@@ -579,4 +599,32 @@ export const RETIRED_FROM_SURFACE = [
     ReticleTool.REFRESH, // absorbed into reticle_navigate { reload: true }
     ReticleTool.WAIT_READY, // server-internal: the first live call already blocks for the session
 ];
+/**
+ * An empty `interactive` tree is a claim, and it is usually the wrong one.
+ *
+ * `mode:"interactive"` filters on ARIA role, and a large share of production UI carries none. On
+ * MarkText — a shipped Electron editor — it returns NOTHING while `mode:"full"` returns 47 nodes,
+ * because its whole block picker is `<div>`s with no role, no testid and no pointer cursor. This
+ * tool's own description recommends the lean mode, so an agent takes the cheap look, is handed `""`,
+ * and reads it as an empty page. It is the one shape of answer this product must never invent.
+ *
+ * The browser counts what leanness passed over, so the tool can say which of the two it is.
+ */
+function noteEmptyLeanTree(result, mode) {
+    if (SnapshotMode.INTERACTIVE !== mode)
+        return result;
+    const row = asRecord(result);
+    if (0 !== asNumber(row['nodes']))
+        return result;
+    const skipped = asNumber(row['leanSkipped']) ?? 0;
+    if (0 === skipped)
+        return result;
+    return {
+        ...row,
+        note: `no element on this page carries an interactive ARIA role, so this mode found nothing — ` +
+            `${String(skipped)} element(s) were passed over for leanness and this is NOT an empty page. ` +
+            `Take reticle_snapshot { mode: "full" } instead; the controls here are addressed by text or ` +
+            `by testid rather than by role.`,
+    };
+}
 export const TOOLS = applyMerges(RAW_TOOLS, MERGE_PLANS, RETIRED_FROM_SURFACE);

package/dist/update/reticle-deps.d.ts

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

package/dist/update/reticle-deps.js

@@ -0,0 +1,27 @@
+/**
+ * The `@reticlehq/*` packages a project actually declares.
+ *
+ * Shared by `reticle update` (which syncs them) and the version-skew remedy (which names them).
+ * Lives here, not in `init/`, so the daemon library path can read a package.json without pulling
+ * the installer in behind it.
+ */
+/** Everything we publish is scoped here. */
+const RETICLE_SCOPE = '@reticlehq/';
+/**
+ * The CLI. Never an app dependency: it carries the Node MCP server and `ws`, and putting it in a
+ * browser app's tree is what the retired `@reticlehq/core` umbrella got wrong.
+ */
+const SERVER_PACKAGE = '@reticlehq/server';
+function namesIn(section) {
+    if ('object' !== typeof section || null === section)
+        return [];
+    return Object.keys(section);
+}
+/** The Reticle packages this project declares, from either dependency section. */
+export function reticleDepsOf(pkgJson) {
+    if ('object' !== typeof pkgJson || null === pkgJson)
+        return [];
+    const manifest = pkgJson;
+    const declared = [...namesIn(manifest['dependencies']), ...namesIn(manifest['devDependencies'])];
+    return [...new Set(declared)].filter((name) => name.startsWith(RETICLE_SCOPE) && name !== SERVER_PACKAGE);
+}

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

@@ -12,8 +12,7 @@
  * 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[];
+export { reticleDepsOf } from './reticle-deps.js';
 /** The install to run, or null when this project has nothing of ours to sync. */
 export declare function sdkSyncCommand(pm: PackageManager, packages: readonly string[], version: string): {
     command: string;

package/dist/update/sdk-sync.js

@@ -12,27 +12,7 @@
  * 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);
-}
+export { reticleDepsOf } from './reticle-deps.js';
 /** The install to run, or null when this project has nothing of ours to sync. */
 export function sdkSyncCommand(pm, packages, version) {
     if (0 === packages.length)

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

@@ -69,6 +69,24 @@ export declare function takeUpdateNudge(): UpdateNudge | undefined;
  * audiences and must not steal each other's message.
  */
 export declare function availableUpdate(currentVersion?: string): string | undefined;
+/**
+ * What the nudge did this daemon run, for the session summary.
+ *
+ * The nudge has shipped for several releases and emitted nothing, so "did the agent get told about
+ * a release, and did anything happen" was unanswerable — and it is the whole adoption mechanism for
+ * a published fix. `versionChange.nudged` is the half that only ever arrives from machines that DID
+ * update; the pinned cohort never fires `version_changed` at all.
+ *
+ * Reads the same module state the delivery path uses rather than adding a counter beside it, so the
+ * two cannot disagree. `shown` is the one-shot delivery flag: it means "an agent was told", never
+ * how often. `offered` is present whenever a newer release was known, whether or not it was
+ * delivered — without it, `shown: false` would mean "nothing was available" and "something was and
+ * the nudge did not fire" at the same time, and only one of those is a defect.
+ */
+export declare function updateNudgeState(): {
+    shown: boolean;
+    offered?: string;
+};
 /** Tests only — drop the module state so each case starts clean. */
 export declare function resetUpdateNudge(): void;
 export {};

package/dist/update/update-nudge.js

@@ -187,6 +187,26 @@ export function availableUpdate(currentVersion = SERVER_VERSION) {
     const latest = loadManifest()?.latestVersion;
     return latest !== undefined && isNewerVersion(latest, currentVersion) ? latest : undefined;
 }
+/**
+ * What the nudge did this daemon run, for the session summary.
+ *
+ * The nudge has shipped for several releases and emitted nothing, so "did the agent get told about
+ * a release, and did anything happen" was unanswerable — and it is the whole adoption mechanism for
+ * a published fix. `versionChange.nudged` is the half that only ever arrives from machines that DID
+ * update; the pinned cohort never fires `version_changed` at all.
+ *
+ * Reads the same module state the delivery path uses rather than adding a counter beside it, so the
+ * two cannot disagree. `shown` is the one-shot delivery flag: it means "an agent was told", never
+ * how often. `offered` is present whenever a newer release was known, whether or not it was
+ * delivered — without it, `shown: false` would mean "nothing was available" and "something was and
+ * the nudge did not fire" at the same time, and only one of those is a defect.
+ */
+export function updateNudgeState() {
+    return {
+        shown: delivered,
+        ...(pending === undefined ? {} : { offered: pending.latestVersion }),
+    };
+}
 /** Tests only — drop the module state so each case starts clean. */
 export function resetUpdateNudge() {
     pending = undefined;

package/dist/version/peer-announce.js

@@ -13,7 +13,7 @@
  */
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from './server-version.js';
-import { describeSkew, DAEMON_FIX, SkewPair } from './version-skew.js';
+import { daemonFix, describeSkew, SkewPair } from './version-skew.js';
 import { noteVersionSkew } from './version-nudge.js';
 export const PEER_VERSION_PARAM = 'peerVersion';
 export const PEER_CONTRACT_PARAM = 'peerContract';
@@ -23,7 +23,9 @@ export function noteAgentPeer(version, contract) {
         what: "the agent's MCP server",
         version: version ?? undefined,
         contract: contract ?? undefined,
-        fix: DAEMON_FIX,
+        // Inverted from cli-launch: here THIS process is the daemon and the peer is the agent's
+        // MCP server, so the daemon is the newer half whenever the announcing agent is behind.
+        fix: daemonFix(SERVER_VERSION, version ?? undefined),
     }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
     if (skew !== undefined)
         noteVersionSkew(SkewPair.DAEMON, skew);

package/dist/version/sdk-fix.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The project-aware SDK remedy for version skew (#618).
+ *
+ * `sdkFix` in version-skew.ts is the no-project fallback: it names `@reticlehq/browser` and npm,
+ * because those answers are never actively wrong. When a project directory IS in hand, name the
+ * packages actually in package.json and the manager the lockfile implies.
+ *
+ * Does not import `init/`. The library path must never reach the installer
+ * (`library-path-boundary.test.ts`); `reticleDepsOf` lives in `update/` for that reason, and the
+ * lockfile → manager map is the same evidence `detectPackageManager` reads, kept here so a HELLO
+ * does not load the install plan.
+ */
+/** What a project contributes to the remedy, when we were able to read one. */
+export interface SdkFixContext {
+    /** `@reticlehq/*` packages declared in package.json. Empty / omitted means none yet. */
+    packages?: readonly string[];
+    packageManager: PackageManagerName;
+}
+/** Lockfile / marker → manager, same evidence `init/detect.ts` uses. */
+export declare const PackageManagerName: {
+    readonly PNPM: "pnpm";
+    readonly YARN: "yarn";
+    readonly BUN: "bun";
+    readonly NPM: "npm";
+};
+export type PackageManagerName = (typeof PackageManagerName)[keyof typeof PackageManagerName];
+/**
+ * The one sentence telling the human how to bring the page's SDK in line with this daemon.
+ *
+ * No context → the framework-neutral sensor and npm, never the React kit. Packages from
+ * package.json win when present. When the project has none of ours yet, the sensor is named
+ * rather than `@reticlehq/react` — that is the Vue/Nuxt failure.
+ */
+export declare function resolveSdkFix(daemonVersion: string, ctx?: Partial<SdkFixContext>): string;
+/**
+ * Read the context `resolveSdkFix` needs off a parsed manifest and the lockfiles/markers present.
+ *
+ * Undefined when there is no manifest to interpret — the caller then uses the no-project fallback.
+ * Pure: no filesystem.
+ */
+export declare function sdkFixContextOf(pkgJson: unknown, lockfiles: ReadonlySet<string>, nodeModulesMarkers?: ReadonlySet<string>): SdkFixContext | undefined;
+/**
+ * The remedy for the project in `directory`, or the no-project fallback when it cannot be read.
+ *
+ * `read` is injected so the decision is testable without a filesystem; the daemon uses the default.
+ */
+export declare function sdkFixForDirectory(daemonVersion: string, directory: string, read?: (path: string) => string | undefined): string;

package/dist/version/sdk-fix.js

@@ -0,0 +1,127 @@
+/**
+ * The project-aware SDK remedy for version skew (#618).
+ *
+ * `sdkFix` in version-skew.ts is the no-project fallback: it names `@reticlehq/browser` and npm,
+ * because those answers are never actively wrong. When a project directory IS in hand, name the
+ * packages actually in package.json and the manager the lockfile implies.
+ *
+ * Does not import `init/`. The library path must never reach the installer
+ * (`library-path-boundary.test.ts`); `reticleDepsOf` lives in `update/` for that reason, and the
+ * lockfile → manager map is the same evidence `detectPackageManager` reads, kept here so a HELLO
+ * does not load the install plan.
+ */
+import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { reticleDepsOf } from '../update/reticle-deps.js';
+/** Lockfile / marker → manager, same evidence `init/detect.ts` uses. */
+export const PackageManagerName = {
+    PNPM: 'pnpm',
+    YARN: 'yarn',
+    BUN: 'bun',
+    NPM: 'npm',
+};
+/** Same package a Vue/Nuxt install gets — never the React kit. */
+const FRAMEWORK_NEUTRAL_SDK = '@reticlehq/browser';
+const PACKAGE_JSON = 'package.json';
+const NODE_MODULES = 'node_modules';
+const LOCKFILE_NAMES = ['pnpm-lock.yaml', 'yarn.lock', 'bun.lockb', 'bun.lock'];
+/** Markers each manager leaves inside `node_modules` — stronger than an uncommitted lockfile. */
+const NODE_MODULES_MARKERS = [
+    ['.modules.yaml', PackageManagerName.PNPM],
+    ['.yarn-state.yml', PackageManagerName.YARN],
+    ['.package-lock.json', PackageManagerName.NPM],
+];
+const INSTALL_FLAGS = {
+    [PackageManagerName.PNPM]: ['add', '-D'],
+    [PackageManagerName.YARN]: ['add', '-D'],
+    [PackageManagerName.BUN]: ['add', '-d'],
+    [PackageManagerName.NPM]: ['i', '-D'],
+};
+function packagesFor(ctx) {
+    if (ctx?.packages !== undefined && 0 !== ctx.packages.length)
+        return ctx.packages;
+    return [FRAMEWORK_NEUTRAL_SDK];
+}
+function managerOf(lockfiles, nodeModulesMarkers) {
+    if (lockfiles.has('pnpm-lock.yaml'))
+        return PackageManagerName.PNPM;
+    if (lockfiles.has('yarn.lock'))
+        return PackageManagerName.YARN;
+    if (lockfiles.has('bun.lockb') || lockfiles.has('bun.lock'))
+        return PackageManagerName.BUN;
+    for (const [name, pm] of NODE_MODULES_MARKERS) {
+        if (nodeModulesMarkers.has(name))
+            return pm;
+    }
+    return PackageManagerName.NPM;
+}
+function installLine(pm, pkgs) {
+    return `${pm} ${[...INSTALL_FLAGS[pm], ...pkgs].join(' ')}`;
+}
+function restartClause() {
+    return ('or run `reticle update`, then restart their dev server so the page reloads with it. The ' +
+        'restart is not optional: a bundler keeps serving the pre-bundled copy it already has, so an ' +
+        'upgrade can look applied — matching versions in `npm ls` — while the page runs the old module.');
+}
+/**
+ * The one sentence telling the human how to bring the page's SDK in line with this daemon.
+ *
+ * No context → the framework-neutral sensor and npm, never the React kit. Packages from
+ * package.json win when present. When the project has none of ours yet, the sensor is named
+ * rather than `@reticlehq/react` — that is the Vue/Nuxt failure.
+ */
+export function resolveSdkFix(daemonVersion, ctx) {
+    const pm = ctx?.packageManager ?? PackageManagerName.NPM;
+    const pinned = packagesFor(ctx).map((name) => `${name}@${daemonVersion}`);
+    return `Tell the human to install the matching SDK (\`${installLine(pm, pinned)}\`) ${restartClause()}`;
+}
+/**
+ * Read the context `resolveSdkFix` needs off a parsed manifest and the lockfiles/markers present.
+ *
+ * Undefined when there is no manifest to interpret — the caller then uses the no-project fallback.
+ * Pure: no filesystem.
+ */
+export function sdkFixContextOf(pkgJson, lockfiles, nodeModulesMarkers = new Set()) {
+    if ('object' !== typeof pkgJson || null === pkgJson)
+        return undefined;
+    return {
+        packages: reticleDepsOf(pkgJson),
+        packageManager: managerOf(lockfiles, nodeModulesMarkers),
+    };
+}
+/** Reads a file, or undefined if it is not there / not readable. */
+function readTextFile(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseJson(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function present(directory, names, read, extra = '') {
+    const found = new Set();
+    for (const name of names) {
+        if (read(join(directory, extra, name)) !== undefined)
+            found.add(name);
+    }
+    return found;
+}
+/**
+ * The remedy for the project in `directory`, or the no-project fallback when it cannot be read.
+ *
+ * `read` is injected so the decision is testable without a filesystem; the daemon uses the default.
+ */
+export function sdkFixForDirectory(daemonVersion, directory, read = readTextFile) {
+    const ctx = sdkFixContextOf(parseJson(read(join(directory, PACKAGE_JSON))), present(directory, LOCKFILE_NAMES, read), present(directory, NODE_MODULES_MARKERS.map(([name]) => name), read, NODE_MODULES));
+    return resolveSdkFix(daemonVersion, ctx);
+}