@reticlehq/server 3.2.0 → 3.4.0

package/dist/command/cli/cloud-login.js

@@ -37,10 +37,28 @@ const LoginSchema = z.object({
  * code out of a server log they may not even be tailing.
  */
 const RequestCodeSchema = z.object({ devCode: z.string().optional() });
+const MeSchema = z.object({ email: z.string().min(1).nullable().optional() });
+/** The signed-in address, asked of the cloud. Best-effort: a login never fails for want of it. */
+const signedInEmail = async (url, token) => {
+    try {
+        return MeSchema.parse(await api('GET', `${url}/v1/me`, token)).email ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
 /** Persist a session token under ~/.reticle and print the next step. Shared by both login paths. */
-const writeSession = async (url, token, orgName, orgId, project, link) => {
+const writeSession = async (url, token, orgName, orgId, project, link, email) => {
     await mkdir(join(home(), SESSIONS_DIR), { recursive: true });
-    const body = `${JSON.stringify({ url: normalizeUrl(url), token, orgName, ...(orgId === undefined ? {} : { orgId }) }, null, 2)}\n`;
+    // Who signed in, so a flow saved on this machine can say which person made it (FlowFile.author).
+    const who = email ?? (await signedInEmail(url, token));
+    const body = `${JSON.stringify({
+        url: normalizeUrl(url),
+        token,
+        orgName,
+        ...(orgId === undefined ? {} : { orgId }),
+        ...(who === undefined ? {} : { email: who }),
+    }, null, 2)}\n`;
     // Both, on purpose. The per-host file is what lets another environment stay logged in; the active
     // file is what a bare command with no override resolves through, and keeping it means nothing
     // about the single-environment workflow changes.
@@ -159,7 +177,7 @@ export const cmdLogin = async (argv, link) => {
         code = requested.devCode;
     }
     const parsed = LoginSchema.parse(await api('POST', `${url}/v1/auth/login`, null, { email, code }));
-    await writeSession(url, parsed.token, parsed.org.name, parsed.org.id, f['project'], link);
+    await writeSession(url, parsed.token, parsed.org.name, parsed.org.id, f['project'], link, email);
     return 0;
 };
 /** `reticle logout` — forget the cached session token (per-project keys under credentials.json stay). */

package/dist/command/cli/demo/demo-page.js

@@ -67,16 +67,19 @@ const HTML_CONTENT_TYPE = 'text/html; charset=utf-8';
 function bareSpecifiersIn(dir) {
     const found = new Set();
     const walk = (at) => {
-        for (const name of readdirSync(at)) {
+        for (const entry of readdirSync(at, { withFileTypes: true })) {
+            const name = entry.name;
             const path = join(at, name);
-            if (statSync(path).isDirectory()) {
+            if (entry.isDirectory()) {
                 if ('node_modules' !== name)
                     walk(path);
                 continue;
             }
             if (!name.endsWith('.js') || name.endsWith('.test.js'))
                 continue;
-            for (const match of readFileSync(path, 'utf8').matchAll(/from\s*'([^.'][^']*)'/g)) {
+            // `from` as a keyword, not the tail of a string: core's `z.discriminatedUnion('from', [...])`
+            // read as an import of everything up to the next quote. A specifier never holds whitespace.
+            for (const match of readFileSync(path, 'utf8').matchAll(/(?<![\w$.'"])from\s*'([^.'\s][^'\s]*)'/g)) {
                 const spec = match[1];
                 if (spec !== undefined && !NOT_SERVABLE.test(spec))
                     found.add(spec);

package/dist/command/cli/doctor/browser/chromium-hint.d.ts

@@ -43,6 +43,11 @@ export interface ChromiumProbe {
      * and kept reading "not installed", with no way to see that neither was ever searched.
      */
     searchedPaths?: readonly string[] | undefined;
+    /**
+     * The installed browser Reticle drives instead when its own build is absent (`Google Chrome`,
+     * `Microsoft Edge`) — see launch-chromium. Present only when `exists` is false and one was found.
+     */
+    fallback?: string | undefined;
 }
 /** The install command, pinned when we know what to pin to. */
 export declare function chromiumInstallCommand(playwrightVersion?: string): string;

package/dist/command/cli/doctor/browser/chromium-hint.js

@@ -170,6 +170,11 @@ export function chromiumHint(probe) {
             : `✓ installed (${probe.wantedRevision})`;
     }
     const command = chromiumInstallCommand(probe.playwrightVersion);
+    // Not a failure: every Reticle browser launches on this one. The install command stays on the
+    // line for a reader who wants the exact build the tests run against.
+    if (probe.fallback !== undefined && probe.executablePath !== undefined) {
+        return `✓ using the installed ${probe.fallback} (Playwright's own Chromium is not installed; ${command} adds it)`;
+    }
     if (probe.executablePath === undefined) {
         // Same rule as the missing-browser line below: a verdict with nowhere to check it against reads
         // as a broken check. The roots say whether this process even searched the directory the reader

package/dist/command/cli/doctor/doctor-sessions-line.d.ts

@@ -1,5 +1,5 @@
 /** What this reads off `/status`. Everything is optional — an older daemon may send none of it. */
-export interface SessionFacts {
+interface SessionFacts {
     sessionCount?: unknown;
     why?: unknown;
 }
@@ -10,3 +10,4 @@ export interface SessionsLine {
     why?: string;
 }
 export declare function sessionsLine(facts: SessionFacts): SessionsLine;
+export {};

package/dist/command/cli/launch/cli-launch.d.ts

@@ -3,34 +3,7 @@
  * "show me the app" flow (`reticle open`). Split out of cli.ts so that file stays under the size cap.
  * The decision logic is pure (unit-tested); the IO (fetch, OS browser launch) is injected/isolated.
  */
-/** One connected tab as `reticle status` reports it — the at-a-glance health line. */
-interface StatusSession {
-    sessionId: string;
-    url: string;
-    throttled: boolean;
-    /**
-     * The tab is backgrounded. Reported by the daemon on every session; `false` on one too old to say,
-     * which reads as visible — the conservative answer, since it keeps the reuse this command has
-     * always done rather than opening a tab on a guess.
-     */
-    hidden: boolean;
-    stale: boolean;
-    pendingMarks: number;
-    /** The tab is attached and answering nothing — see Session.unresponsive. Absent on an older daemon. */
-    unresponsive?: true;
-}
-/**
- * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
- * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
- * degrades to "running, 0 sessions" instead of throwing.
- */
-export declare function summarizeStatus(payload: unknown): {
-    sessionCount: number;
-    sessions: StatusSession[];
-    why?: string;
-    /** The same diagnosis without the differential, for a surface a person reads. */
-    whyLead?: string;
-};
+export { summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
 /**
  * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
  *
@@ -39,6 +12,13 @@ export declare function summarizeStatus(payload: unknown): {
  * another agent's session on a version bump, which is worse than a loud line.
  */
 export declare function warnOnDaemonSkew(port: number): Promise<void>;
+/**
+ * The skew sentence for a daemon's `/status` body, or undefined when it speaks our contract.
+ *
+ * Shared with `init`, which must not ADOPT a skewed daemon: an older one refuses every hello from
+ * the page init just instrumented.
+ */
+export declare function daemonSkew(status: unknown): string | undefined;
 /** What `reticle open` should do: reuse an already-connected tab, open a new one, or ask for a url. */
 type OpenDecision = {
     action: 'reuse';
@@ -75,6 +55,7 @@ export declare function decideOpen(all: {
     url: string;
     unresponsive?: boolean;
     hidden?: boolean;
+    lastSeenMs?: number;
 }[], url: string | undefined): OpenDecision;
 /** The OS command that opens a URL in the default browser, per platform. Pure — unit-tested. */
 export declare function openCommand(url: string, platform: NodeJS.Platform): {
@@ -97,4 +78,3 @@ export declare function openInBrowser(url: string, platform?: NodeJS.Platform, r
  * by spawning a real launcher on a developer machine.
  */
 export declare function launcherFailure(code: number | null, signal: NodeJS.Signals | null): string | null;
-export {};

package/dist/command/cli/launch/cli-launch.js

@@ -1,53 +1,19 @@
 import { NodePlatform } from '../../../machine/platform.js';
 import { spawn } from 'node:child_process';
-import { isOpaqueOrigin } from '@reticlehq/core';
+import { isOpaqueOrigin, SESSION_HEALTH } from '@reticlehq/core';
 import { daemonFix, describeSkew } from '../../version/version-skew.js';
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from '../../version/identity/server-version.js';
 import { log } from '../../../log.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
 /**
- * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
- * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
- * degrades to "running, 0 sessions" instead of throwing.
+ * CLI launch + status helpers — the daemon-introspection (`reticle status`) and the one-command
+ * "show me the app" flow (`reticle open`). Split out of cli.ts so that file stays under the size cap.
+ * The decision logic is pure (unit-tested); the IO (fetch, OS browser launch) is injected/isolated.
  */
-export function summarizeStatus(payload) {
-    if (typeof payload !== 'object' || null === payload)
-        return { sessionCount: 0, sessions: [] };
-    const obj = payload;
-    // Carried through to the printed line: with no sessions this is the whole answer, and dropping it
-    // here would silently undo the reason it is on the wire.
-    const why = 'string' === typeof obj['why'] ? obj['why'] : undefined;
-    // Absent on a daemon older than this field, which is why every reader falls back to `why`.
-    const whyLead = 'string' === typeof obj['whyLead'] ? obj['whyLead'] : undefined;
-    const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
-    const sessions = raw
-        .map((s) => {
-        if (typeof s !== 'object' || null === s)
-            return null;
-        const r = s;
-        const sessionId = 'string' === typeof r['sessionId'] ? r['sessionId'] : '';
-        if ('' === sessionId)
-            return null;
-        return {
-            sessionId,
-            url: 'string' === typeof r['url'] ? r['url'] : '',
-            throttled: true === r['throttled'],
-            hidden: true === r['hidden'],
-            stale: true === r['stale'],
-            pendingMarks: 'number' === typeof r['pendingMarks'] ? r['pendingMarks'] : 0,
-            ...(true === r['unresponsive'] ? { unresponsive: true } : {}),
-        };
-    })
-        .filter((s) => s !== null);
-    const sessionCount = 'number' === typeof obj['sessionCount'] ? obj['sessionCount'] : sessions.length;
-    return {
-        sessionCount,
-        sessions,
-        ...(why === undefined ? {} : { why }),
-        ...(whyLead === undefined ? {} : { whyLead }),
-    };
-}
+// Parsing the daemon's /status payload lives beside the probe that fetches it; re-exported here for
+// the callers that already import it from this module.
+export { summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
 /** A string field off the /status body, or undefined on a daemon too old to report it. */
 function statusField(payload, key) {
     if (typeof payload !== 'object' || null === payload)
@@ -63,17 +29,25 @@ function statusField(payload, key) {
  * another agent's session on a version bump, which is worse than a loud line.
  */
 export async function warnOnDaemonSkew(port) {
-    const status = await fetchStatus(port);
+    const skew = daemonSkew(await fetchStatus(port));
+    if (skew !== undefined)
+        log('reticle_daemon_skew', { port, warning: skew });
+}
+/**
+ * The skew sentence for a daemon's `/status` body, or undefined when it speaks our contract.
+ *
+ * Shared with `init`, which must not ADOPT a skewed daemon: an older one refuses every hello from
+ * the page init just instrumented.
+ */
+export function daemonSkew(status) {
     const daemonVersion = statusField(status, 'version');
-    const skew = describeSkew({
+    return describeSkew({
         what: 'the daemon already running on this port',
         version: daemonVersion,
         contract: statusField(status, 'contract'),
         // The daemon is the peer here and this process is the agent side.
         fix: daemonFix(daemonVersion, SERVER_VERSION),
     }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
-    if (skew !== undefined)
-        log('reticle_daemon_skew', { port, warning: skew });
 }
 function sameOrigin(a, b) {
     try {
@@ -116,10 +90,14 @@ export function decideOpen(all, url) {
     // three checks that could never resolve. Opening the url instead costs one foreground tab and the
     // hidden one is left exactly where it was — nothing is navigated out from under anybody.
     //
-    // HIDDEN, not `throttled`: throttled is `hidden || stale`, and a stale-but-visible tab is usually
-    // a quiet page that drives fine. Excluding those would pile up a duplicate tab per run, which is
-    // the thing the origin match below exists to prevent.
-    const sessions = all.filter((s) => true !== s.unresponsive && true !== s.hidden);
+    // And a tab the SDK has gone SILENT in. The page heartbeats on a native timer every few seconds
+    // whatever it is doing, so a quiet page is not a silent one: past the daemon's own staleness
+    // threshold the page is frozen (a discarded tab, a sleeping machine, a wedged main thread). This
+    // looked only at the url, and `verify --expect` drove a tab last heard from 105s earlier into
+    // "command 'match' timed out after 8000ms" instead of opening the url it had been given.
+    const sessions = all.filter((s) => true !== s.unresponsive &&
+        true !== s.hidden &&
+        (s.lastSeenMs ?? 0) <= SESSION_HEALTH.STALE_THRESHOLD_MS);
     if (url === undefined) {
         const first = sessions[0];
         if (first !== undefined)

package/dist/command/cli/launch/sdk-version-match.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Run the CLI whose major matches the SDK the project actually installed.
+ *
+ * The agent's MCP entry and every rule file `init` writes say `npx @reticlehq/server`, deliberately
+ * unpinned (see `npxServerArgs` in init), which resolves the LATEST server — while the project's SDK
+ * stays locked at whatever `init` installed. A project wired on the previous major therefore got a
+ * daemon from the next one, and every verdict came back `version_skew`; a global install from an
+ * older release shadows npx the same way in the other direction. Nothing the project could do fixed
+ * it short of upgrading, and the report named the skew without resolving it.
+ *
+ * So the one entry every command passes through asks, before doing anything: is the SDK in this
+ * project on my major? If not, it hands the same arguments to `npx @reticlehq/server@<that version>`
+ * and steps aside. Only across majors — a minor apart verifies fine, and re-running for it would
+ * cost an npx resolve on every command for nothing.
+ *
+ * Deliberately free of `@/` and relative imports: the stdio test runs this file in a bare Node child
+ * to see the real file descriptors, and that child has neither the alias nor the build.
+ */
+import { type ChildProcess } from 'node:child_process';
+/** The packages an instrumented project installs; they release in lockstep, so any one will do. */
+export declare const SDK_PACKAGES: readonly ["@reticlehq/react", "@reticlehq/browser", "@reticlehq/next", "@reticlehq/vite-plugin"];
+export declare const VersionMatchEnv: {
+    /** Set to anything to keep the CLI you ran, whatever the project installed. */
+    readonly OPT_OUT: "RETICLE_NO_VERSION_MATCH";
+    /** Set on the re-run child, so it can never re-run itself again. */
+    readonly REEXECUTED: "RETICLE_VERSION_MATCHED";
+    /** What npm puts here for `npx <spec>` — how a version typed on the npx line is recognised. */
+    readonly NPX_PACKAGE: "npm_config_package";
+};
+/**
+ * The SDK version installed for `projectDir`, found the way Node resolves it: the nearest
+ * `node_modules` at or above the directory, so a package hoisted to a workspace root counts.
+ */
+export declare function installedSdkVersion(projectDir: string, readFile: (path: string) => string | undefined): string | undefined;
+/** `readFile` for the real filesystem: the text, or undefined when there is nothing readable. */
+export declare function readTextFile(path: string): string | undefined;
+/** The one line a person sees on stderr when the CLI hands over — stdout belongs to the protocol. */
+export declare function versionMatchNote(sdkVersion: string, cliVersion: string): string;
+export interface VersionMatchInput {
+    argv: readonly string[];
+    cliVersion: string;
+    env: Readonly<Record<string, string | undefined>>;
+    projectDir: string;
+    readFile: (path: string) => string | undefined;
+}
+/**
+ * The version to re-run at, or undefined to carry on in this process. Pure: the filesystem and the
+ * environment are handed in.
+ */
+export declare function versionToMatch(input: VersionMatchInput): string | undefined;
+/** How to launch `npx --yes @reticlehq/server@<version> <args>` on this platform. */
+export declare function npxInvocation(version: string, args: readonly string[], on: string): {
+    file: string;
+    argv: string[];
+    shell: boolean;
+};
+/** The two things the re-run needs from its child: when it ends, and a way to pass a signal on. */
+export interface ReexecChild {
+    /** Called once, with the exit code — or undefined when the child never started or was killed. */
+    onEnd(listener: (code: number | undefined, error: Error | undefined) => void): void;
+    kill(signal: NodeJS.Signals): void;
+}
+export type ReexecSpawner = (file: string, argv: string[], options: {
+    stdio: 'inherit';
+    env: NodeJS.ProcessEnv;
+    shell: boolean;
+}) => ReexecChild;
+/** A ChildProcess, seen through `ReexecChild`. */
+export declare function asReexecChild(child: ChildProcess): ReexecChild;
+/** The real spawner. */
+export declare const nodeSpawner: ReexecSpawner;
+/**
+ * Hand this invocation to the matching version and exit with its code.
+ *
+ * `stdio: 'inherit'` gives the child this process's own file descriptors, so an MCP client's JSON-RPC
+ * stream reaches it without passing through a byte of JavaScript here — nothing to buffer, reframe or
+ * lose. For that to hold, this must run before anything writes to stdout.
+ */
+export declare function reexecAtVersion(version: string, args: readonly string[], env: NodeJS.ProcessEnv, deps: {
+    spawn: ReexecSpawner;
+    exit: (code: number) => void;
+    platform?: string;
+    warn?: (line: string) => void;
+}): void;

package/dist/command/cli/launch/sdk-version-match.js

@@ -0,0 +1,206 @@
+/**
+ * Run the CLI whose major matches the SDK the project actually installed.
+ *
+ * The agent's MCP entry and every rule file `init` writes say `npx @reticlehq/server`, deliberately
+ * unpinned (see `npxServerArgs` in init), which resolves the LATEST server — while the project's SDK
+ * stays locked at whatever `init` installed. A project wired on the previous major therefore got a
+ * daemon from the next one, and every verdict came back `version_skew`; a global install from an
+ * older release shadows npx the same way in the other direction. Nothing the project could do fixed
+ * it short of upgrading, and the report named the skew without resolving it.
+ *
+ * So the one entry every command passes through asks, before doing anything: is the SDK in this
+ * project on my major? If not, it hands the same arguments to `npx @reticlehq/server@<that version>`
+ * and steps aside. Only across majors — a minor apart verifies fine, and re-running for it would
+ * cost an npx resolve on every command for nothing.
+ *
+ * Deliberately free of `@/` and relative imports: the stdio test runs this file in a bare Node child
+ * to see the real file descriptors, and that child has neither the alias nor the build.
+ */
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { NodePlatform, windowsShellArg } from '@reticlehq/init';
+/** The packages an instrumented project installs; they release in lockstep, so any one will do. */
+export const SDK_PACKAGES = [
+    '@reticlehq/react',
+    '@reticlehq/browser',
+    '@reticlehq/next',
+    '@reticlehq/vite-plugin',
+];
+/** The package that carries the `reticle` bin — what the re-run asks npx for. */
+const SERVER_PACKAGE = '@reticlehq/server';
+const NPX = 'npx';
+const NPX_WINDOWS = 'npx.cmd';
+const NPX_YES = '--yes';
+const NODE_MODULES = 'node_modules';
+const PACKAGE_JSON = 'package.json';
+const LATEST_TAG = 'latest';
+const MARKED = '1';
+export const VersionMatchEnv = {
+    /** Set to anything to keep the CLI you ran, whatever the project installed. */
+    OPT_OUT: 'RETICLE_NO_VERSION_MATCH',
+    /** Set on the re-run child, so it can never re-run itself again. */
+    REEXECUTED: 'RETICLE_VERSION_MATCHED',
+    /** What npm puts here for `npx <spec>` — how a version typed on the npx line is recognised. */
+    NPX_PACKAGE: 'npm_config_package',
+};
+/**
+ * Commands whose job is to CHANGE the version, or to report on this binary. Re-running `init` or
+ * `update` at the project's old version would undo exactly what the person asked for; `version` and
+ * `help` describe the binary they ran. `_daemon` is spawned by a CLI that already decided.
+ */
+const KEEP_COMMANDS = new Set([
+    'init',
+    'update',
+    'rollback',
+    'version',
+    'help',
+    '_daemon',
+]);
+const KEEP_FLAGS = new Set(['--version', '-v', '--help', '-h']);
+const SETUP_COMMAND = 'setup';
+const SETUP_INSTALL = 'install';
+/** A published release — not `workspace:*`, a link, or a tag npx could not pin. */
+const RELEASE_VERSION = /^(\d+)\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+function majorOf(version) {
+    return RELEASE_VERSION.exec(version)?.[1];
+}
+/**
+ * The SDK version installed for `projectDir`, found the way Node resolves it: the nearest
+ * `node_modules` at or above the directory, so a package hoisted to a workspace root counts.
+ */
+export function installedSdkVersion(projectDir, readFile) {
+    let dir = projectDir;
+    for (;;) {
+        for (const pkg of SDK_PACKAGES) {
+            const raw = readFile(join(dir, NODE_MODULES, pkg, PACKAGE_JSON));
+            if (raw === undefined)
+                continue;
+            try {
+                const version = JSON.parse(raw).version;
+                if ('string' === typeof version)
+                    return version;
+            }
+            catch {
+                // A manifest that will not parse is no evidence; try the next package.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** `readFile` for the real filesystem: the text, or undefined when there is nothing readable. */
+export function readTextFile(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The one line a person sees on stderr when the CLI hands over — stdout belongs to the protocol. */
+export function versionMatchNote(sdkVersion, cliVersion) {
+    return (`This project's Reticle SDK is ${sdkVersion}; running ${SERVER_PACKAGE}@${sdkVersion} to match ` +
+        `(this CLI is ${cliVersion}, a different major). Set ${VersionMatchEnv.OPT_OUT}=1 to keep this one.`);
+}
+/** Did the person name a version on the npx line (`npx @reticlehq/server@<version> …`)? */
+function pinnedOnNpxLine(spec) {
+    if (spec === undefined || !spec.startsWith(`${SERVER_PACKAGE}@`))
+        return false;
+    return spec.slice(SERVER_PACKAGE.length + 1) !== LATEST_TAG;
+}
+function keepsThisBinary(argv) {
+    const [command, sub] = argv;
+    if (command !== undefined && KEEP_COMMANDS.has(command))
+        return true;
+    if (SETUP_COMMAND === command && SETUP_INSTALL === sub)
+        return true;
+    return argv.some((arg) => KEEP_FLAGS.has(arg));
+}
+/**
+ * The version to re-run at, or undefined to carry on in this process. Pure: the filesystem and the
+ * environment are handed in.
+ */
+export function versionToMatch(input) {
+    const { env } = input;
+    if (env[VersionMatchEnv.REEXECUTED] !== undefined)
+        return undefined;
+    if (env[VersionMatchEnv.OPT_OUT] !== undefined)
+        return undefined;
+    if (pinnedOnNpxLine(env[VersionMatchEnv.NPX_PACKAGE]))
+        return undefined;
+    if (keepsThisBinary(input.argv))
+        return undefined;
+    const sdk = installedSdkVersion(input.projectDir, input.readFile);
+    if (sdk === undefined)
+        return undefined;
+    const sdkMajor = majorOf(sdk);
+    if (sdkMajor === undefined)
+        return undefined;
+    return sdkMajor === majorOf(input.cliVersion) ? undefined : sdk;
+}
+/** How to launch `npx --yes @reticlehq/server@<version> <args>` on this platform. */
+export function npxInvocation(version, args, on) {
+    const argv = [NPX_YES, `${SERVER_PACKAGE}@${version}`, ...args];
+    // A `.cmd` cannot be spawned without a shell since the CVE-2024-27980 fix, and a shell needs every
+    // argument quoted — the same rule `npmSpawn` in the updater follows.
+    if (NodePlatform.WINDOWS !== on)
+        return { file: NPX, argv, shell: false };
+    return { file: [NPX_WINDOWS, ...argv.map(windowsShellArg)].join(' '), argv: [], shell: true };
+}
+/** A ChildProcess, seen through `ReexecChild`. */
+export function asReexecChild(child) {
+    return {
+        onEnd: (listener) => {
+            // Node can emit `error` AND `exit` for one child; the listener exits the process, so once.
+            let ended = false;
+            const end = (code, error) => {
+                if (ended)
+                    return;
+                ended = true;
+                listener(code, error);
+            };
+            child.once('error', (error) => end(undefined, error));
+            child.once('exit', (code) => end(code ?? undefined, undefined));
+        },
+        kill: (signal) => {
+            child.kill(signal);
+        },
+    };
+}
+/** The real spawner. */
+export const nodeSpawner = (file, argv, options) => asReexecChild(spawn(file, argv, options));
+const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+const SPAWN_FAILED_EXIT = 1;
+/**
+ * Hand this invocation to the matching version and exit with its code.
+ *
+ * `stdio: 'inherit'` gives the child this process's own file descriptors, so an MCP client's JSON-RPC
+ * stream reaches it without passing through a byte of JavaScript here — nothing to buffer, reframe or
+ * lose. For that to hold, this must run before anything writes to stdout.
+ */
+export function reexecAtVersion(version, args, env, deps) {
+    const inv = npxInvocation(version, args, deps.platform ?? process.platform);
+    const child = deps.spawn(inv.file, inv.argv, {
+        stdio: 'inherit',
+        env: { ...env, [VersionMatchEnv.REEXECUTED]: MARKED },
+        shell: inv.shell,
+    });
+    // A client that stops the proxy signals THIS pid; the real server is the child.
+    const forward = (signal) => {
+        child.kill(signal);
+    };
+    for (const signal of FORWARDED_SIGNALS)
+        process.on(signal, forward);
+    child.onEnd((code, error) => {
+        for (const signal of FORWARDED_SIGNALS)
+            process.off(signal, forward);
+        if (error !== undefined) {
+            deps.warn?.(`Could not start ${SERVER_PACKAGE}@${version} to match this project's SDK (${error.message}). ` +
+                `Set ${VersionMatchEnv.OPT_OUT}=1 to use the installed CLI instead.`);
+        }
+        deps.exit(code ?? SPAWN_FAILED_EXIT);
+    });
+}

package/dist/command/cli/lifecycle/daemon-lifecycle.js

@@ -17,7 +17,7 @@
 import { log } from '../../../log.js';
 import { RETICLE_VERIFY_DEFAULT_PORT } from '../../../index.js';
 import { verifyEndpointMismatch } from '../../../status-payload.js';
-import { probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
+import { probeDaemon, waitForDaemonBind } from '../../../surface/mcp/mcp-proxy.js';
 import { stateDirProblem } from '../../daemon/state-dir.js';
 import { readPid, isAlive, removePid, spawnDaemon, logPath, reticleStateHome, } from '../../daemon/daemon.js';
 import { readDaemonStartupCause } from '../../daemon/lifetime/startup-failure.js';
@@ -84,7 +84,7 @@ async function serveWithHonestExit(parsed) {
     // The child binds asynchronously and, when it cannot, exits 1 long after this process would have
     // reported success. Wait for it to ANSWER — `/status` responding is the only evidence a daemon
     // exists that does not come from the pid file the child may never have earned.
-    const bound = await waitForPresence(parsed.port, PortPresence.DAEMON, SERVE_BIND_TIMEOUT_MS);
+    const bound = await waitForDaemonBind(parsed.port);
     if (!bound) {
         const settled = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
         const startupCause = readDaemonStartupCause(logPath(parsed.port), startupStartedAt);
@@ -113,24 +113,10 @@ async function serveWithHonestExit(parsed) {
     }
     log('reticle_daemon_spawned', { port: parsed.port, ...(parsed.http ? { http: true } : {}) });
 }
-/** How long `serve` waits for the child to bind. Generous: a cold daemon start is seconds. */
-const SERVE_BIND_TIMEOUT_MS = 15_000;
-const PRESENCE_POLL_MS = 150;
 /** How long a daemon gets to shut down on its own before `stop` stops asking politely. */
 const GRACEFUL_STOP_MS = 5000;
 /** How long after SIGKILL before we accept the process is not ours to kill and say so. */
 const FORCED_STOP_MS = 2000;
-async function waitForPresence(port, want, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    for (;;) {
-        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
-        if (presence === want)
-            return true;
-        if (Date.now() >= deadline)
-            return false;
-        await new Promise((resolve) => setTimeout(resolve, PRESENCE_POLL_MS));
-    }
-}
 export function handleStop(port, quiet) {
     const pid = readPid(port);
     if (null === pid || !isAlive(pid)) {