@reticlehq/server 2.11.0 → 2.13.0

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

@@ -1,13 +1,3 @@
-/**
- * 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;
@@ -30,6 +20,13 @@ interface UpdateNudge {
  *
  * Bounded on purpose: this rides on a tool result every turn until it is delivered, so a long
  * changelog is a per-turn tax. The count of anything elided is stated rather than silently dropped.
+ *
+ * It also names what `update` does to the RULE FILES, which is the half nobody would guess. A new
+ * release changes what the always-loaded instructions should say — that is the whole reason
+ * `refreshAgentRules` exists — and an agent that reads "it restarts the daemon" has no reason to
+ * think its CLAUDE.md is now a release behind. Saying so costs one clause on a message that is
+ * delivered once per daemon, and it is the difference between a fleet that upgrades its rules and
+ * one that upgrades its binary and keeps last release's instructions forever.
  */
 export declare function buildNudge(latestVersion: string, currentVersion: string, release?: {
     changelog?: string;
@@ -72,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

@@ -29,7 +29,7 @@ import { creditNudge } from './nudge-credit.js';
  * story rests on. Numeric per segment, so 2.10.0 correctly beats 2.9.0 (string order does not), and
  * a bare release beats its own prerelease.
  */
-export function isNewerVersion(candidate, current) {
+function isNewerVersion(candidate, current) {
     const parse = (v) => {
         const [core = '', ...rest] = v.split(/[-+]/);
         return { parts: core.split('.').map((n) => Number.parseInt(n, 10) || 0), pre: rest.length > 0 };
@@ -72,6 +72,13 @@ const MAX_LISTED_BREAKING = 4;
  *
  * Bounded on purpose: this rides on a tool result every turn until it is delivered, so a long
  * changelog is a per-turn tax. The count of anything elided is stated rather than silently dropped.
+ *
+ * It also names what `update` does to the RULE FILES, which is the half nobody would guess. A new
+ * release changes what the always-loaded instructions should say — that is the whole reason
+ * `refreshAgentRules` exists — and an agent that reads "it restarts the daemon" has no reason to
+ * think its CLAUDE.md is now a release behind. Saying so costs one clause on a message that is
+ * delivered once per daemon, and it is the difference between a fleet that upgrades its rules and
+ * one that upgrades its binary and keeps last release's instructions forever.
  */
 export function buildNudge(latestVersion, currentVersion, release) {
     const changelog = (release?.changelog ?? '').trim();
@@ -89,8 +96,10 @@ export function buildNudge(latestVersion, currentVersion, release) {
                 : `This release has BREAKING changes: ${listed.join('; ')}` +
                     (0 < rest ? ` (+${String(rest)} more — see the changelog)` : '') +
                     '. Read them before updating. ') +
-            `Tell the human, and run \`${UPDATE_COMMAND}\` if they agree — it restarts the daemon, ` +
-            'so do it between tasks rather than mid-verification. Continue your current task first.',
+            `Tell the human, and run \`${UPDATE_COMMAND}\` if they agree — it upgrades the packages, ` +
+            "refreshes the Reticle rules in this project's CLAUDE.md / AGENTS.md, and restarts the " +
+            'daemon, so do it between tasks rather than mid-verification. Continue your current task ' +
+            'first.',
     };
 }
 export function startUpdateCheck(now = () => Date.now()) {
@@ -178,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/update/updater.d.ts

@@ -3,7 +3,7 @@ declare const VersionChangeDirection: {
     readonly UPDATE: "update";
     readonly ROLLBACK: "rollback";
 };
-export type VersionChangeDirection = (typeof VersionChangeDirection)[keyof typeof VersionChangeDirection];
+type VersionChangeDirection = (typeof VersionChangeDirection)[keyof typeof VersionChangeDirection];
 /**
  * Report a completed version move. Never throws — an install that worked must still be reported done.
  *

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);
+}

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

@@ -23,6 +23,20 @@ interface VersionSkewNudge {
 export declare function noteVersionSkew(pair: SkewPair, action: string): void;
 /** The next undelivered skew, once. */
 export declare function takeVersionSkew(): VersionSkewNudge | undefined;
+/**
+ * Splice pending skew onto a tool-error payload.
+ *
+ * Successful calls already carry `version_skew` via `runTool`. Thrown errors never reached that
+ * splice — they became a Playwright string plus `FEEDBACK_ASK`, so a caller debugs a CDP timeout
+ * instead of the mismatched pair that caused it (#618). When the error was unrecognized, the
+ * feedback ask is replaced: the skew IS the next move, and inviting a bug report about it is
+ * backwards. A recognized recovery is kept; the envelope still rides along.
+ */
+export declare function takeVersionSkewOnto(payload: {
+    error: string;
+    recovery?: string;
+    feedback?: string;
+}): Record<string, unknown>;
 /** Tests only — drop the module state so each case starts clean. */
 export declare function resetVersionSkew(): void;
 export {};

package/dist/version/version-nudge.js

@@ -11,6 +11,7 @@
  * result, then goes quiet until the skew CHANGES. Told, not nagged: a banner on every call is one an
  * agent learns to skip, and it would cost those tokens on every call for the rest of the session.
  */
+import { EnvelopeKey } from '../tools/tool-kit.js';
 /** Pending per pair — the SDK and the daemon are different upgrades and each is worth saying once. */
 const pending = new Map();
 /** The last message delivered for each pair, so the same skew is never repeated. */
@@ -33,6 +34,26 @@ export function takeVersionSkew() {
     }
     return undefined;
 }
+/**
+ * Splice pending skew onto a tool-error payload.
+ *
+ * Successful calls already carry `version_skew` via `runTool`. Thrown errors never reached that
+ * splice — they became a Playwright string plus `FEEDBACK_ASK`, so a caller debugs a CDP timeout
+ * instead of the mismatched pair that caused it (#618). When the error was unrecognized, the
+ * feedback ask is replaced: the skew IS the next move, and inviting a bug report about it is
+ * backwards. A recognized recovery is kept; the envelope still rides along.
+ */
+export function takeVersionSkewOnto(payload) {
+    const skew = takeVersionSkew();
+    if (skew === undefined)
+        return payload;
+    const { feedback, ...rest } = payload;
+    return {
+        ...rest,
+        ...(feedback !== undefined && rest.recovery === undefined ? { recovery: skew.action } : {}),
+        [EnvelopeKey.VERSION_SKEW]: skew,
+    };
+}
 /** Tests only — drop the module state so each case starts clean. */
 export function resetVersionSkew() {
     pending.clear();

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

@@ -59,8 +59,43 @@ interface SelfIdentity {
  * inventing a warning would be as dishonest as staying silent about a real one.
  */
 export declare function describeSkew(peer: PeerIdentity, self: SelfIdentity): string | undefined;
-/** The fix line for a page whose SDK disagrees with this daemon. */
+/**
+ * The fix line for a page whose SDK disagrees with this daemon, with no project to read.
+ *
+ * Names the framework-neutral sensor and plain npm, because those are the answers that are never
+ * actively wrong. When a project directory IS available, `resolveSdkFix` / `sdkFixForDirectory`
+ * in sdk-fix.ts read the real packages and package manager — this used to hardcode
+ * `@reticlehq/react` and told Vue projects to install a React package (#618).
+ */
 export declare function sdkFix(daemonVersion: string): string;
-/** The fix line for another Reticle process that disagrees with the daemon it attached to. */
-export declare const DAEMON_FIX: string;
+/**
+ * The fix line for another Reticle process that disagrees with the daemon it attached to.
+ *
+ * Branches on DIRECTION, which the old unconditional `reticle stop` did not (#618). Restarting the
+ * daemon converges the pair only when the daemon is the OLDER half. When the daemon is newer — the
+ * common case, because the MCP registration is deliberately unpinned and so resolves fresh while a
+ * long-lived daemon does not — `reticle stop` starts another newer daemon and leaves the same two
+ * contract hashes with the roles unchanged. Nothing the agent can do converges that, so say so and
+ * ask for the one thing that does, exactly as the SDK branch already does when the page is stale.
+ *
+ * Both versions are named by ROLE, not by which side is calling: this is read from both ends — a
+ * CLI judging the daemon it attached to, and the daemon judging an agent that announced itself —
+ * and the advice depends on which piece is behind, not on who noticed.
+ */
+export declare function daemonFix(daemonVersion: string | undefined, agentVersion: string | undefined): string;
+/**
+ * Playwright wording when a CDP call cannot bind to the page.
+ *
+ * Under SDK/daemon version skew this text is a LIE: the page is still connected (DOM tools work),
+ * and the agent spends turns re-acquiring leases and asking a human to sign into a fresh profile
+ * (#688). Matched only so we can replace it with the skew sentence already on the session.
+ */
+export declare const PLAYWRIGHT_CLOSED_ERROR: RegExp;
+/** True when `error` is Playwright's closed-target class — not proof the tab is gone. */
+export declare function isPlaywrightClosedError(error: unknown): boolean;
+/**
+ * Replace a closed-target throw with the session's skew sentence when we already know the pair is
+ * mismatched. Undefined when there is no skew to name, or the throw is something else.
+ */
+export declare function rewriteClosedAsSkew(error: unknown, skew: string | undefined): Error | undefined;
 export {};

package/dist/version/version-skew.js

@@ -23,6 +23,7 @@
  * the wire changes and stays put when internals do. Versions still ride along, because they are what
  * a human acts on.
  */
+import { resolveSdkFix } from './sdk-fix.js';
 /** Which pair disagreed. Named so the nudge can report each independently. */
 export const SkewPair = {
     /** The SDK in the page vs this daemon. */
@@ -60,12 +61,87 @@ export function describeSkew(peer, self) {
         `(${peer.contract} vs ${self.contract}) — so this is a real mismatch, not a harmless patch ` +
         `difference. Tools will behave in ways neither side reports. ${peer.fix}`);
 }
-/** The fix line for a page whose SDK disagrees with this daemon. */
+/**
+ * The fix line for a page whose SDK disagrees with this daemon, with no project to read.
+ *
+ * Names the framework-neutral sensor and plain npm, because those are the answers that are never
+ * actively wrong. When a project directory IS available, `resolveSdkFix` / `sdkFixForDirectory`
+ * in sdk-fix.ts read the real packages and package manager — this used to hardcode
+ * `@reticlehq/react` and told Vue projects to install a React package (#618).
+ */
 export function sdkFix(daemonVersion) {
-    return (`Tell the human to install the matching SDK (\`npm i -D @reticlehq/react@${daemonVersion}\`) ` +
-        'or run `reticle update`, then restart their dev server so the page reloads with it.');
+    return resolveSdkFix(daemonVersion);
+}
+/**
+ * Compare two of our own version strings. Numeric dotted compare, prerelease tags ignored: both
+ * sides are Reticle package versions, so this never sees a range or build metadata. Undefined when
+ * either side does not parse, so the caller can decline to guess a direction.
+ */
+function compareVersions(a, b) {
+    const parts = (v) => {
+        const head = v.split('-')[0];
+        if (head === undefined)
+            return undefined;
+        const nums = head.split('.').map((n) => parseInt(n, 10));
+        return nums.some(isNaN) ? undefined : nums;
+    };
+    if (a === undefined)
+        return undefined;
+    const left = parts(a);
+    const right = parts(b);
+    if (left === undefined || right === undefined)
+        return undefined;
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (0 !== diff)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * The fix line for another Reticle process that disagrees with the daemon it attached to.
+ *
+ * Branches on DIRECTION, which the old unconditional `reticle stop` did not (#618). Restarting the
+ * daemon converges the pair only when the daemon is the OLDER half. When the daemon is newer — the
+ * common case, because the MCP registration is deliberately unpinned and so resolves fresh while a
+ * long-lived daemon does not — `reticle stop` starts another newer daemon and leaves the same two
+ * contract hashes with the roles unchanged. Nothing the agent can do converges that, so say so and
+ * ask for the one thing that does, exactly as the SDK branch already does when the page is stale.
+ *
+ * Both versions are named by ROLE, not by which side is calling: this is read from both ends — a
+ * CLI judging the daemon it attached to, and the daemon judging an agent that announced itself —
+ * and the advice depends on which piece is behind, not on who noticed.
+ */
+export function daemonFix(daemonVersion, agentVersion) {
+    const order = agentVersion === undefined ? undefined : compareVersions(daemonVersion, agentVersion);
+    if (order !== undefined && order > 0) {
+        return ('The daemon is NEWER than this process, so `reticle stop` will not converge them — it would ' +
+            'replace it with another newer daemon and leave the same mismatch. Tell the human to restart ' +
+            'the agent so it spawns a current MCP server (or update the package it spawns), then retry.');
+    }
+    return ('A daemon outlives the agents attached to it, so it keeps serving its OWN code until it restarts ' +
+        '— anything fixed in the newer package is simply absent. Run `reticle stop` and retry to replace ' +
+        'it (other agents on that daemon will need to reconnect).');
+}
+/**
+ * Playwright wording when a CDP call cannot bind to the page.
+ *
+ * Under SDK/daemon version skew this text is a LIE: the page is still connected (DOM tools work),
+ * and the agent spends turns re-acquiring leases and asking a human to sign into a fresh profile
+ * (#688). Matched only so we can replace it with the skew sentence already on the session.
+ */
+export const PLAYWRIGHT_CLOSED_ERROR = /target (?:page|context|browser) has been closed|browser has been closed|browser has disconnected/i;
+/** True when `error` is Playwright's closed-target class — not proof the tab is gone. */
+export function isPlaywrightClosedError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return PLAYWRIGHT_CLOSED_ERROR.test(message);
+}
+/**
+ * Replace a closed-target throw with the session's skew sentence when we already know the pair is
+ * mismatched. Undefined when there is no skew to name, or the throw is something else.
+ */
+export function rewriteClosedAsSkew(error, skew) {
+    if (skew === undefined || !isPlaywrightClosedError(error))
+        return undefined;
+    return new Error(skew);
 }
-/** The fix line for another Reticle process that disagrees with the daemon it attached to. */
-export const DAEMON_FIX = 'A daemon outlives the agents attached to it, so it keeps serving its OWN code until it restarts ' +
-    '— anything fixed in the newer package is simply absent. Run `reticle stop` and retry to replace ' +
-    'it (other agents on that daemon will need to reconnect).';

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

@@ -8,15 +8,15 @@ export declare class VisualStore {
     constructor(fs: FileSystemPort, root: string);
     /** The absolute baseline path for `name` (for echoing back to the agent). Guards the name so a
      *  crafted value can never echo a path outside .reticle/visual/ to a future caller that does IO. */
-    baselinePath(name: string): string;
+    baselinePath(name: string, runtime?: string): string;
     /** The absolute overlay-diff path for `name`. Same name guard as baselinePath. */
-    diffPath(name: string): string;
+    diffPath(name: string, runtime?: string): string;
     /** True iff a valid name and a baseline PNG exists on disk. */
-    hasBaseline(name: string): Promise<boolean>;
+    hasBaseline(name: string, runtime?: string): Promise<boolean>;
     /** Write a PNG baseline (auto-creating .reticle/visual/). Returns its path; throws on a bad name. */
-    saveBaseline(name: string, png: Uint8Array): Promise<string>;
+    saveBaseline(name: string, png: Uint8Array, runtime?: string): Promise<string>;
     /** Read a PNG baseline, or undefined if absent / invalid name (never throws on missing). */
-    readBaseline(name: string): Promise<Uint8Array | undefined>;
+    readBaseline(name: string, runtime?: string): Promise<Uint8Array | undefined>;
     /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
-    saveDiff(name: string, png: Uint8Array): Promise<string>;
+    saveDiff(name: string, png: Uint8Array, runtime?: string): Promise<string>;
 }

package/dist/visual/visual-store.js

@@ -1,4 +1,4 @@
-import { reticleDirPaths, isValidFlowName, visualDiffPath, visualPath, } from '../project/reticle-dir.js';
+import { isValidFlowName, visualDiffPath, visualDir, visualPath } from '../project/reticle-dir.js';
 /**
  * On-disk PNG baselines + diffs under .reticle/visual/. Binary sibling of FlowStore — same
  * name guard (rejects path traversal before any join) and injected FileSystemPort, but bytes not text.
@@ -12,39 +12,40 @@ export class VisualStore {
     }
     /** The absolute baseline path for `name` (for echoing back to the agent). Guards the name so a
      *  crafted value can never echo a path outside .reticle/visual/ to a future caller that does IO. */
-    baselinePath(name) {
+    baselinePath(name, runtime) {
         if (!isValidFlowName(name))
             throw new Error(`invalid visual baseline name: ${name}`);
-        return visualPath(this.#root, name);
+        return visualPath(this.#root, name, runtime);
     }
     /** The absolute overlay-diff path for `name`. Same name guard as baselinePath. */
-    diffPath(name) {
+    diffPath(name, runtime) {
         if (!isValidFlowName(name))
             throw new Error(`invalid visual diff name: ${name}`);
-        return visualDiffPath(this.#root, name);
+        return visualDiffPath(this.#root, name, runtime);
     }
     /** True iff a valid name and a baseline PNG exists on disk. */
-    async hasBaseline(name) {
+    async hasBaseline(name, runtime) {
         if (!isValidFlowName(name))
             return false;
-        return this.#fs.exists(visualPath(this.#root, name));
+        return this.#fs.exists(visualPath(this.#root, name, runtime));
     }
     /** Write a PNG baseline (auto-creating .reticle/visual/). Returns its path; throws on a bad name. */
-    async saveBaseline(name, png) {
+    async saveBaseline(name, png, runtime) {
         if (!isValidFlowName(name))
             throw new Error(`invalid visual baseline name: ${name}`);
-        await this.#fs.mkdir(reticleDirPaths(this.#root).visual);
-        const path = visualPath(this.#root, name);
+        // The runtime's own directory, not the shared one — see visualDir.
+        await this.#fs.mkdir(visualDir(this.#root, runtime));
+        const path = visualPath(this.#root, name, runtime);
         await this.#fs.writeFileBytes(path, png);
         return path;
     }
     /** Read a PNG baseline, or undefined if absent / invalid name (never throws on missing). */
-    async readBaseline(name) {
-        if (!isValidFlowName(name) || !(await this.#fs.exists(visualPath(this.#root, name)))) {
+    async readBaseline(name, runtime) {
+        if (!isValidFlowName(name) || !(await this.#fs.exists(visualPath(this.#root, name, runtime)))) {
             return undefined;
         }
         try {
-            return await this.#fs.readFileBytes(visualPath(this.#root, name));
+            return await this.#fs.readFileBytes(visualPath(this.#root, name, runtime));
         }
         catch (error) {
             if (this.#fs.isNotFound(error))
@@ -53,11 +54,12 @@ export class VisualStore {
         }
     }
     /** Write the overlay diff PNG for `name` (auto-creating .reticle/visual/). Returns its path. */
-    async saveDiff(name, png) {
+    async saveDiff(name, png, runtime) {
         if (!isValidFlowName(name))
             throw new Error(`invalid visual baseline name: ${name}`);
-        await this.#fs.mkdir(reticleDirPaths(this.#root).visual);
-        const path = visualDiffPath(this.#root, name);
+        // Beside its baseline, or a diff lands in a directory the baseline is not in.
+        await this.#fs.mkdir(visualDir(this.#root, runtime));
+        const path = visualDiffPath(this.#root, name, runtime);
         await this.#fs.writeFileBytes(path, png);
         return path;
     }