@reticlehq/server 3.6.0 → 3.7.0

package/dist/command/setup/run-setup.js

@@ -2,12 +2,8 @@
  * The half of setup that happens after the files are written.
  *
  * `init` wires a project; this gets the app running with the SDK inside it and proves a session
- * connected. That is where ONBOARDING ends — the first run, which proves a flow, is a separate
- * stage and a separate command.
- *
- * It does NOT drive a flow. `reticle_verify { action: "explore" }` does that, with a model inside
- * the daemon that already holds the tools — so no client restart is needed and no second CLI has to
- * exist on the machine.
+ * connected. That is where ONBOARDING ends. Then init says what Reticle sees and hands the first
+ * flow to the coding agent (`try-command.ts`'s `initFirstFlow`); nothing in init drives.
  *
  * Every effect is injected. That is not ceremony: the sequence has five phases, each with its own
  * way of going wrong, and the alternative to injecting them is a test that boots a real dev server
@@ -47,6 +43,21 @@ const NO_BROWSER_GRACE_MS = 3_000;
  * as opened, and init then waited out its whole connect budget over a correct install.
  */
 const SYSTEM_BROWSER_GRACE_MS = 15_000;
+/**
+ * Said before Reticle starts its own static server for a plain page, while it can still be acted
+ * on: the page may already be served by something with an API behind it, and only the person
+ * running init knows that (#1426).
+ */
+export const STATIC_PAGE_URL_HINT = 'This page has no dev server of its own, so Reticle is starting a static one. ' +
+    'If the page is already served (python -m http.server, php -S, a Node server with an API), ' +
+    're-run with `reticle init --url <app>` to attach to that server instead.';
+/** Whose server the success line names, so a session on Reticle's own is never mistaken for the app. */
+export const ServerStartedBy = {
+    CALLER: 'you passed its url',
+    ALREADY_RUNNING: 'it was already running',
+    RETICLE_STATIC: 'Reticle started this static server',
+    SETUP: 'setup started the dev server',
+};
 export const SetupPhase = {
     DEV_SERVER: 'dev-server',
     CONNECT: 'connect',
@@ -129,12 +140,14 @@ export async function runSetupPhases(input, fx) {
             note(
             // "stop here rather than invent one" is the SKILL.md rule, and the words are the contract —
             // inventing a dev command is how a setup script runs the wrong thing and reports success.
-            'No dev command: the project names no dev, start or serve script, and there is no --url. ' +
+            'No dev command: the project names no dev, start or serve script, and no app url was given (`reticle init --url <app>`). ' +
                 'Stopping here rather than invent one — start the app yourself and pass --url to say ' +
                 'where it is serving, or add a dev/start/serve script to package.json and re-run.');
             return stop(input, SetupPhase.DEV_SERVER, {}, notes);
         }
         else {
+            if (true === input.devCommandIsStaticPage)
+                note(STATIC_PAGE_URL_HINT);
             await fx.startDevServer(input.devCommand, input.appDir);
             const startedAt = fx.now();
             // This loop used to poll in complete silence. Reported as thirty minutes of nothing ending in a
@@ -372,40 +385,33 @@ export async function runSetupPhases(input, fx) {
     // Getting started is three stages — installation puts the CLI on the machine, onboarding wires
     // the project, the first run proves a flow — and this command owns the middle one. A connected
     // session is the whole proof that onboarding worked: the SDK is in the page, the bridge paired,
-    // and the tools now have something to talk to.
-    //
-    // `<url>` stays a placeholder in this string on purpose: `guidance-commands-run` feeds every
-    // command we print to the real parser, and an interpolated value reads there as a missing operand.
-    // The live url is named in the sentence instead, where a reader needs it anyway.
-    // Both routes, because `explore` runs on the platform: without a linked project it refuses.
-    // Naming only that one hands the reader a dead end on any machine without one.
-    // A heading and a numbered list rather than one paragraph: a reader scans for what to do next.
+    // and the tools now have something to talk to. What to do next is the first flow's to say.
     //
-    // This was a single 524-character note, measured on a real first run: eighty-three words, no
-    // break, naming `reticle_*` tools at a reader who had just typed `reticle init` in a terminal and
-    // has no such tools to call. The facts were right and the shape made them unreadable, which on
-    // the last line of onboarding is the same as not saying them.
-    note(`✓ Connected. ${url} is instrumented. Onboarding is done; nothing is verified yet.`);
+    // It names whose server that is, because a session on Reticle's static server is not the app a
+    // real server was serving, and "connected" alone let an agent verify the wrong one (#1426).
+    const startedBy = undefined !== input.suppliedUrl
+        ? ServerStartedBy.CALLER
+        : attachedToExisting
+            ? ServerStartedBy.ALREADY_RUNNING
+            : true === input.devCommandIsStaticPage
+                ? ServerStartedBy.RETICLE_STATIC
+                : ServerStartedBy.SETUP;
+    note(`✓ Connected to ${new URL(url).origin} (${startedBy}). Onboarding is done; nothing is verified yet.`);
     // Said, because "connected" otherwise reads as "your browser connected": the page that dialled
     // was a headless one Reticle launched and has now closed, and nothing is open on this screen.
-    if (undefined !== lease && session.sessionId === lease.sessionId) {
+    const leased = undefined !== lease && session.sessionId === lease.sessionId;
+    if (leased) {
         note('The proof came from a Reticle-owned headless browser (now closed), not a window of yours — ' +
             `open ${url} in your own browser to use the app.`);
     }
     await releaseLease(lease);
-    note('');
-    note('Next, prove one flow. Your agent does this:');
-    note('  1. Drive one flow and end it with `reticle_act_and_wait` or `reticle_assert`. Those two ' +
-        'produce a verdict; nothing else does.');
-    note('  2. Or hand over the whole drive: `reticle_verify { action: "explore", persona: "<who does ' +
-        'what>" }` records what it drove, so later runs replay with no model in the loop. Runs on ' +
-        'the Reticle platform: needs a linked project (`reticle connect`); Free includes monthly Harness credits.');
     return {
         ok: true,
         reachedPhase: SetupPhase.CONNECT,
         url,
         sessionId: session.sessionId,
         flowSaved: false,
+        leased,
         notes,
         fallback: [],
     };

package/dist/command/setup/setup-command.d.ts

@@ -29,7 +29,30 @@ interface SetupCommandInput extends Omit<SetupInput, 'shape'> {
     readonly registerAgents: boolean;
     /** The bridge's pairing token, for the MCP transport a connect-proof lease is opened over. */
     readonly pairingToken?: string | undefined;
+    /** False for `--no-first-run`: connect, and say nothing more. */
+    readonly firstRun: boolean;
+    /** `--json`: an agent is reading, so nothing is driven on its behalf. */
+    readonly json: boolean;
+    /**
+     * What happens once the connection is proved: the coverage summary and the agent prompt. A port,
+     * because it reads the daemon's status and the link, which this directory does not reach for.
+     */
+    readonly firstFlow?: FirstFlowPort | undefined;
 }
+/** init's ending, as `command/cli/try-command.ts` says it. Structural, so setup imports nothing. */
+export type FirstFlowPort = (ctx: {
+    appDir: string;
+    bridgePort: number;
+    pairingToken?: string | undefined;
+    url: string;
+    sessionId: string;
+    leased: boolean;
+    openBrowser: boolean;
+    firstRun: boolean;
+    json: boolean;
+}, say: (line: string) => void) => Promise<{
+    flowSaved: boolean;
+}>;
 /** Returns how many agents it wrote a config for, so a caller does not then say "none found". */
 export declare function registerOtherAgents(print: (line: string) => void): number;
 type SetupCommandResult = SetupOutcome;

package/dist/command/setup/setup-command.js

@@ -5,11 +5,12 @@
  * three lines it was. The only decision here is which effects to hand over; the sequencing lives in
  * run-setup.ts and the pieces it calls.
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { planAgentConfigs } from './agent-configs.js';
 import { AppShape, describeShape, readShape } from './desktop-shape.js';
+import { SigningEnv, tauriSigningEnv } from './tauri-signing.js';
 import { stopOnInterrupt } from './terminal/interrupt.js';
 import { stopOnCrash, crashSentence } from './terminal/crash.js';
 import { applyAgentPlan, applyAgentSkills } from './agent-writer.js';
@@ -22,7 +23,7 @@ import { readProjectId } from '../cli/ports/resolve/cli-port.js';
 import { spawnSync } from 'node:child_process';
 import { isAlive, reticleStateHome } from '../daemon/daemon.js';
 import { readDevServers } from '../daemon/dev-servers.js';
-import { urlOfExistingApp } from './probe/existing-app.js';
+import { connectedAppUrl, urlOfExistingApp } from './probe/existing-app.js';
 import { handedOverUrl, stopHandedOver } from './bringup/dev-server-files.js';
 import { listSessions, OwnedDevServer, probePage } from './node-effects.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
@@ -164,6 +165,31 @@ async function restartHandedOverServer(appDir) {
     }
     return stopped;
 }
+/**
+ * init's ending, inside the dev server's lifetime: coverage is read off the open tab, and the `finally`
+ * in `runSetupCommand` only stops a server that was not handed over. Its lines join the notes, so
+ * `--json` carries the next step too.
+ */
+async function afterConnect(input, url, sessionId, outcome, print) {
+    const notes = [...outcome.notes];
+    if (input.firstFlow === undefined)
+        return { flowSaved: false, notes };
+    const { flowSaved } = await input.firstFlow({
+        appDir: input.appDir,
+        bridgePort: input.bridgePort,
+        pairingToken: input.pairingToken,
+        url,
+        sessionId,
+        leased: true === outcome.leased,
+        openBrowser: input.openBrowser,
+        firstRun: input.firstRun,
+        json: input.json,
+    }, (line) => {
+        notes.push(line);
+        print(line);
+    });
+    return { flowSaved, notes };
+}
 export async function runSetupCommand(input, print) {
     if (input.registerAgents)
         registerOtherAgents(print);
@@ -214,7 +240,29 @@ export async function runSetupCommand(input, print) {
     const effects = {
         startDevServer: (command, cwd) => {
             print(`starting: ${command}`);
-            server.start(command, cwd, input.env);
+            const signing = AppShape.TAURI === shape
+                ? tauriSigningEnv({
+                    platform: process.platform,
+                    env: { ...process.env, ...input.env },
+                    read: (path) => {
+                        try {
+                            return readFileSync(join(cwd, path), 'utf8');
+                        }
+                        catch {
+                            return undefined;
+                        }
+                    },
+                    writeRunner: (name, script) => {
+                        const path = join(reticleStateHome(), name);
+                        writeFileSync(path, script);
+                        chmodSync(path, 0o755);
+                        return path;
+                    },
+                })
+                : {};
+            if (SigningEnv.IDENTITY in signing)
+                print(`signing the dev build as ${String(signing[SigningEnv.IDENTITY])}, so macOS does not ask for the keychain password`);
+            server.start(command, cwd, { ...input.env, ...signing });
             return Promise.resolve();
         },
         // The server the plugin announced (Vite), or failing that the one a previous init handed over
@@ -226,7 +274,9 @@ export async function runSetupCommand(input, print) {
             (await handedOverUrl(reticleStateHome(), input.appDir, {
                 alive: isAlive,
                 answers: async (url) => (await probePage(url)).served,
-            })),
+            })) ??
+            // A desktop window of this project already connected: its renderer announces no server.
+            connectedAppUrl(await listSessions(input.bridgePort), readProjectId(input.appDir)),
         devServerOutput: () => server.output(),
         devServerExited: () => server.exited(),
         devServerQuietForMs: () => server.quietForMs(),
@@ -287,8 +337,11 @@ export async function runSetupCommand(input, print) {
             if (undefined !== log)
                 print(`The dev server keeps running; its output goes to ${log}`);
         }
+        if (!outcome.ok || undefined === outcome.url || undefined === outcome.sessionId)
+            return outcome;
         return {
             ...outcome,
+            ...(await afterConnect(input, outcome.url, outcome.sessionId, outcome, print)),
         };
     }
     finally {

package/dist/command/setup/setup-mcp.js

@@ -1,5 +1,22 @@
-import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeHasReticle, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
+import { McpClient, MCP_CLIENTS, claudeAddCommand, claudeAvailableProbe, claudeHasReticle, codexAddCommand, codexAvailableProbe, codexNamesOurServer, detectMcpClients, mergeClientConfig, clientSpec, ClientMergeStatus, } from '@reticlehq/init';
 import { OnboardingPhase, OnboardingStepStatus, } from '@reticlehq/core/telemetry';
+/**
+ * Codex registers through `codex mcp add`, which does the TOML editing we refuse to do (#1238).
+ * `undefined` when that does not apply, and the caller reports a hand edit exactly as before: not
+ * Codex, the `codex` binary is not here, or the config already names a `reticle` server. That last
+ * one matters: `codex mcp add` REPLACES an entry of the same name and still exits 0, so an entry
+ * somebody wrote themselves, in any shape, must never reach it. Otherwise: did the command take.
+ */
+function registerWithCodexCli(io, client, serversKey) {
+    if (McpClient.CODEX !== client.id || codexNamesOurServer(client.existing, serversKey)) {
+        return undefined;
+    }
+    const probe = codexAvailableProbe();
+    if (!io.runCli(probe.command, probe.args))
+        return undefined;
+    const cmd = codexAddCommand();
+    return io.runCli(cmd.command, cmd.args);
+}
 export function setupMcp(io) {
     const detected = [];
     const registered = [];
@@ -47,7 +64,13 @@ export function setupMcp(io) {
         // on an existing file and would CREATE an empty one otherwise, and either way claiming success
         // sends somebody to an agent that has no Reticle tools in it.
         if (ClientMergeStatus.MANUAL === merged.status) {
-            manual.push({ id: client.id, configPath: client.configPath, docs: spec.docs });
+            const viaCli = registerWithCodexCli(io, client, spec.serversKey);
+            if (true === viaCli)
+                registered.push(client.id);
+            else if (false === viaCli)
+                failed.push(client.id);
+            else
+                manual.push({ id: client.id, configPath: client.configPath, docs: spec.docs });
             continue;
         }
         try {

package/dist/command/setup/tauri-signing.d.ts

@@ -0,0 +1,19 @@
+/** The env the runner reads its arguments from: the script stays a fixed file. */
+export declare const SigningEnv: {
+    readonly IDENTITY: "RETICLE_SIGNING_IDENTITY";
+    readonly IDENTIFIER: "RETICLE_SIGNING_IDENTIFIER";
+    readonly APPLE: "APPLE_SIGNING_IDENTITY";
+};
+export declare const RUNNER_FILE = "tauri-sign-runner.sh";
+/** The runner: sign the binary Cargo built, then run it exactly as Cargo would have. */
+export declare const RUNNER_SCRIPT: string;
+export interface SigningDeps {
+    readonly platform: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** A file's text relative to the app directory, or undefined when it is absent. */
+    readonly read: (path: string) => string | undefined;
+    /** Writes the runner and makes it executable; returns its absolute path. */
+    readonly writeRunner: (name: string, script: string) => string;
+}
+/** The extra env for starting a Tauri dev build signed, or `{}` when there is nothing to sign with. */
+export declare function tauriSigningEnv(deps: SigningDeps): Record<string, string>;

package/dist/command/setup/tauri-signing.js

@@ -0,0 +1,79 @@
+/**
+ * Sign the Tauri dev build Reticle starts with the project's own signing identity, so macOS stops
+ * asking for the keychain password.
+ *
+ * macOS ties a keychain item to the designated requirement of the app that saved it: its code
+ * identifier and its signing team. `tauri dev` produces an ad-hoc signed binary named after the
+ * crate, so every keychain read from it is a different app asking, and macOS prompts each time.
+ * `reticle doctor` explained that; this removes it when the project has said who signs it.
+ *
+ * `APPLE_SIGNING_IDENTITY` cannot simply be passed through: Tauri reads it only when it bundles
+ * (`tauri build`), never in `tauri dev`. What `tauri dev` does run is `cargo run`, and Cargo hands
+ * the freshly built binary to a per-target RUNNER before executing it. The runner written here signs
+ * that binary — with the identity, and with the app's bundle identifier so the requirement matches
+ * the release app's — and then executes it unchanged. A signing failure is said on stderr and never
+ * stops the app.
+ *
+ * Nothing happens off macOS, outside a Tauri project, with no identity, with the ad-hoc identity
+ * `-` (which matches nothing), or when the project already sets a Cargo runner of its own.
+ */
+import { join } from 'node:path';
+/** The env the runner reads its arguments from: the script stays a fixed file. */
+export const SigningEnv = {
+    IDENTITY: 'RETICLE_SIGNING_IDENTITY',
+    IDENTIFIER: 'RETICLE_SIGNING_IDENTIFIER',
+    APPLE: 'APPLE_SIGNING_IDENTITY',
+};
+/** Cargo's runner variable for each Mac target `tauri dev` builds. */
+const RUNNER_VARS = [
+    'CARGO_TARGET_AARCH64_APPLE_DARWIN_RUNNER',
+    'CARGO_TARGET_X86_64_APPLE_DARWIN_RUNNER',
+];
+const DARWIN = 'darwin';
+const AD_HOC = '-';
+const TAURI_CONF = join('src-tauri', 'tauri.conf.json');
+export const RUNNER_FILE = 'tauri-sign-runner.sh';
+/** The runner: sign the binary Cargo built, then run it exactly as Cargo would have. */
+export const RUNNER_SCRIPT = `#!/bin/sh
+# Written by Reticle. Signs the Tauri dev build with this project's signing identity before it
+# starts, so macOS treats it as the app that owns your keychain items and stops asking for the
+# password. Remove RETICLE_SIGNING_IDENTITY from the environment to turn it off.
+codesign --force --sign "$${SigningEnv.IDENTITY}" --identifier "$${SigningEnv.IDENTIFIER}" "$1" >/dev/null 2>&1 ||
+  echo "reticle: could not sign $1 with $${SigningEnv.IDENTITY}; macOS may ask for the keychain password" >&2
+exec "$@"
+`;
+const asRecord = (value) => 'object' === typeof value && null !== value ? value : {};
+const asText = (value) => 'string' === typeof value && 0 < value.trim().length ? value.trim() : undefined;
+/** The extra env for starting a Tauri dev build signed, or `{}` when there is nothing to sign with. */
+export function tauriSigningEnv(deps) {
+    if (DARWIN !== deps.platform)
+        return {};
+    const raw = deps.read(TAURI_CONF);
+    if (raw === undefined)
+        return {};
+    let conf;
+    try {
+        conf = asRecord(JSON.parse(raw));
+    }
+    catch {
+        return {};
+    }
+    const macOS = asRecord(asRecord(conf['bundle'])['macOS']);
+    const identity = asText(deps.env[SigningEnv.APPLE]) ?? asText(macOS['signingIdentity']);
+    const identifier = asText(conf['identifier']);
+    if (identity === undefined || AD_HOC === identity || identifier === undefined)
+        return {};
+    // A project that runs its builds through a runner of its own keeps it.
+    if (RUNNER_VARS.some((name) => deps.env[name] !== undefined))
+        return {};
+    const runner = deps.writeRunner(RUNNER_FILE, RUNNER_SCRIPT);
+    // Cargo splits a runner given in the environment on whitespace, so a path with a space in it
+    // would run the wrong program. ponytail: skip it; doctor still explains the prompt.
+    if (/\s/.test(runner))
+        return {};
+    return {
+        [SigningEnv.IDENTITY]: identity,
+        [SigningEnv.IDENTIFIER]: identifier,
+        ...Object.fromEntries(RUNNER_VARS.map((name) => [name, runner])),
+    };
+}

package/dist/command/setup/terminal/listeners.d.ts

@@ -21,11 +21,20 @@ export declare function parseLsofPorts(out: string): number[];
  * and taking index 1 reads every IPv6 row as port 0 and silently drops half the table.
  */
 export declare function parseNetstatListeners(out: string): Listener[];
-/** One (pid, parent) pair, as `wmic process get ParentProcessId,ProcessId` prints them. */
+/**
+ * One (pid, parent) pair, as `wmic process get CreationDate,ParentProcessId,ProcessId` prints them.
+ *
+ * `startedAtMs` is the process's own creation time, when the source gave one. It is what tells a
+ * real child from a stale link: Windows never clears ParentProcessId when a parent exits, and it
+ * reuses pids, so "ppid matches" alone can adopt an unrelated, older process. See `descendants`.
+ */
 export interface ProcessPair {
     readonly pid: number;
     readonly ppid: number;
+    readonly startedAtMs?: number;
 }
+/** Epoch milliseconds of a WMI datetime, or undefined when it is not one. */
+export declare function parseWmiDatetime(text: string): number | undefined;
 export declare function parseWmicProcesses(out: string): ProcessPair[];
 /**
  * `root` and everything descended from it.

package/dist/command/setup/terminal/listeners.js

@@ -39,16 +39,37 @@ export function parseNetstatListeners(out) {
     }
     return rows;
 }
+/** A WMI datetime: `yyyymmddHHMMSS.ffffff` then the offset from UTC in minutes, `+000` / `-300`. */
+const WMI_DATETIME = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d{6})([+-])(\d{3})$/;
+const MICROS_PER_MS = 1000;
+const MS_PER_MINUTE = 60_000;
+/** Epoch milliseconds of a WMI datetime, or undefined when it is not one. */
+export function parseWmiDatetime(text) {
+    const m = WMI_DATETIME.exec(text);
+    if (null === m)
+        return undefined;
+    const n = (index) => Number(m[index]);
+    const local = Date.UTC(n(1), n(2) - 1, n(3), n(4), n(5), n(6), Math.floor(n(7) / MICROS_PER_MS));
+    const minutesEast = '-' === m[8] ? -n(9) : n(9);
+    return local - minutesEast * MS_PER_MINUTE;
+}
 export function parseWmicProcesses(out) {
     const pairs = [];
     for (const line of String(out).split(/\r?\n/)) {
         const f = line.trim().split(/\s+/);
-        if (f.length !== 2)
+        // Two columns (ppid pid), or three with the creation time first: wmic prints its columns in
+        // alphabetical order, and the PowerShell fallback prints the same shape on purpose.
+        const timed = 3 === f.length;
+        if (!timed && 2 !== f.length)
+            continue;
+        const startedAtMs = timed ? parseWmiDatetime(f[0] ?? '') : undefined;
+        if (timed && undefined === startedAtMs)
+            continue;
+        const ppid = Number(f[timed ? 1 : 0]);
+        const pid = Number(f[timed ? 2 : 1]);
+        if (!Number.isInteger(pid) || !Number.isInteger(ppid))
             continue;
-        const ppid = Number(f[0]);
-        const pid = Number(f[1]);
-        if (Number.isInteger(pid) && Number.isInteger(ppid))
-            pairs.push({ pid, ppid });
+        pairs.push(undefined === startedAtMs ? { pid, ppid } : { pid, ppid, startedAtMs });
     }
     return pairs;
 }
@@ -60,8 +81,18 @@ export function parseWmicProcesses(out) {
  * indistinguishable from "no server".
  */
 export function descendants(pairs, root) {
+    const startedAt = new Map();
+    for (const { pid, startedAtMs } of pairs) {
+        if (undefined !== startedAtMs)
+            startedAt.set(pid, startedAtMs);
+    }
     const byParent = new Map();
-    for (const { pid, ppid } of pairs) {
+    for (const { pid, ppid, startedAtMs } of pairs) {
+        // A child created before the parent it names is a stale link left by pid reuse, not a child.
+        const parentStarted = startedAt.get(ppid);
+        if (undefined !== startedAtMs && undefined !== parentStarted && startedAtMs < parentStarted) {
+            continue;
+        }
         const kids = byParent.get(ppid);
         if (kids === undefined)
             byParent.set(ppid, [pid]);

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

@@ -1,3 +1,12 @@
+/**
+ * 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. Numeric per segment, so a 10 patch correctly
+ * beats a 9 (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;

package/dist/command/update/update-nudge.js

@@ -28,7 +28,7 @@ import { creditNudge } from './nudge-credit.js';
  * prompts a downgrade is one people learn to ignore. Numeric per segment, so a 10 patch correctly
  * beats a 9 (string order does not), and a bare release beats its own prerelease.
  */
-function isNewerVersion(candidate, current) {
+export function isNewerVersion(candidate, current) {
     const parse = (v) => {
         const [core = '', ...rest] = v.split(/[-+]/);
         return { parts: core.split('.').map((n) => Number.parseInt(n, 10) || 0), pre: rest.length > 0 };

package/dist/command/update/updater.js

@@ -168,15 +168,6 @@ async function installVersion(version, kind) {
     }
     await runNpm(plan.args, plan.cwd !== undefined ? { cwd: plan.cwd } : {});
 }
-async function installVersionRollback(version, kind) {
-    if (kind === ExecutionKind.NPX) {
-        log('reticle_rollback_npx_strategy', {
-            note: 'Running via npx — update your .mcp.json args to pin the version you want to restore',
-        });
-        return;
-    }
-    await installVersion(version, kind);
-}
 /**
  * Install targetVersion using the appropriate strategy for the detected execution kind,
  * then exit so Claude Code restarts with the new binary. Saves the current version
@@ -209,15 +200,20 @@ export async function rollback() {
     }
     const prev = manifest.previousVersion;
     const kind = detectExecutionKind();
+    // Under npx there is nothing to reinstall: the next start re-resolves the package. Say how to pin
+    // the old version and stop, rather than logging and reporting a rollback that never landed.
+    if (kind === ExecutionKind.NPX) {
+        log('reticle_rollback_npx_strategy', {
+            version: prev,
+            note: 'Running via npx — update your .mcp.json args to pin the version you want to restore',
+        });
+        return;
+    }
     log('reticle_rollback_applying', { version: prev, executionKind: kind });
-    await installVersionRollback(prev, kind);
+    await installVersion(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);
+    process.exit(0);
 }

package/dist/command/version/version-nudge.js

@@ -68,6 +68,9 @@ export function takeVersionSkewOnto(payload, connection) {
     const skew = takeVersionSkew(connection);
     if (skew === undefined)
         return payload;
+    // Compatible, so it did not cause this error: ride along, and leave the advice and the ask alone.
+    if (SkewPair.SDK_BEHIND === skew.pair)
+        return { ...payload, [EnvelopeKey.VERSION_SKEW]: skew };
     const { feedback, ...rest } = payload;
     return {
         ...rest,

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

@@ -28,6 +28,12 @@ export declare const SkewPair: {
     readonly SDK: "sdk";
     /** Another Reticle process — a CLI, or the MCP server an agent spawned — vs this daemon. */
     readonly DAEMON: "daemon";
+    /**
+     * The SDK in the page is a minor or more behind, on the same contract: compatible, so it is news
+     * and not a cause. Its own pair so it never displaces an untold real skew, and never stands in for
+     * the advice on an error it did not cause (see takeVersionSkewOnto).
+     */
+    readonly SDK_BEHIND: "sdk_behind";
 };
 export type SkewPair = (typeof SkewPair)[keyof typeof SkewPair];
 /** What a piece says about itself when it connects. */
@@ -78,7 +84,7 @@ interface SelfIdentity {
  * a build provably older than this daemon. With neither signal there is nothing to go on, and
  * inventing a warning would be as dishonest as staying silent about a real one.
  */
-export declare function describeSkew(peer: PeerIdentity, self: SelfIdentity): string | undefined;
+export declare function describeSkew(given: PeerIdentity, self: SelfIdentity): string | undefined;
 /**
  * The fix line for a page whose SDK disagrees with this daemon, with no project to read.
  *
@@ -88,6 +94,19 @@ export declare function describeSkew(peer: PeerIdentity, self: SelfIdentity): st
  * `@reticlehq/react` and told Vue projects to install a React package (#618).
  */
 export declare function sdkFix(daemonVersion: string): string;
+/** The same fact for the person looking at the page, on its overlay. */
+export declare const SDK_BEHIND_NARRATION: (sdk: string, daemon: string) => string;
+/**
+ * A page whose SDK is a minor release or more behind this daemon.
+ *
+ * `describeSkew` is silent here on purpose: the contract matches, so the page connects and every
+ * verdict is sound. But whatever shipped since is not in the page, the overlay included, and from
+ * the field that looked exactly like a broken release: the CLI reported the new version while the
+ * page showed an overlay without the newer controls, and nothing anywhere said which SDK it was
+ * running. Patch releases stay silent for the cry-wolf reason in the header. `fix` is a thunk
+ * because reading the project's manifest is only worth it when the page IS behind.
+ */
+export declare function describeSdkBehind(sdk: string | undefined, daemon: string, fix: () => string): string | undefined;
 /**
  * The fix line for another Reticle process that disagrees with the daemon it attached to.
  *