@reticlehq/server 3.3.0 → 3.5.0

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

@@ -37,17 +37,36 @@ 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, autoLink = true) => {
     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.
     await writeFile(sessionPath(home(), url), body);
     await writeFile(join(home(), SESSION_FILE), body);
     emit({ loggedIn: orgName, session: join(home(), SESSION_FILE) });
-    await linkAfterLogin(url, project, link);
+    if (autoLink)
+        await linkAfterLogin(url, project, link);
 };
 /**
  * Finish the job when the shell is already standing in an unlinked Reticle project.
@@ -106,7 +125,7 @@ const linkAfterLogin = async (url, project, link) => {
  * Browser device flow — the DEFAULT `reticle login` (like `gh auth login`): fetch a device + user code,
  * open the browser to approve, then poll until the user confirms. No email to type, no code to copy back.
  */
-const cmdLoginDevice = async (explicitUrl, project, link) => {
+const cmdLoginDevice = async (explicitUrl, project, link, autoLink) => {
     const url = baseUrl(null, explicitUrl);
     const started = DeviceStartSchema.parse(await api('POST', `${url}/v1/auth/device/start`, null, {}));
     hint(`Opening ${started.verificationUri} — confirm this code in the browser: ${started.userCode}`);
@@ -116,7 +135,7 @@ const cmdLoginDevice = async (explicitUrl, project, link) => {
         await sleep(intervalMs);
         const poll = DevicePollSchema.parse(await api('POST', `${url}/v1/auth/device/token`, null, { deviceCode: started.deviceCode }));
         if ('approved' === poll.status && poll.token !== undefined && poll.org !== undefined) {
-            await writeSession(url, poll.token, poll.org.name, poll.org.id, project, link);
+            await writeSession(url, poll.token, poll.org.name, poll.org.id, project, link, undefined, autoLink);
             return 0;
         }
         if ('pending' === poll.status) {
@@ -136,12 +155,12 @@ const cmdLoginDevice = async (explicitUrl, project, link) => {
  * `reticle login` — browser device flow by default; `--email <e>` (or a positional email) keeps the
  * headless two-step code path for CI/servers where opening a browser makes no sense.
  */
-export const cmdLogin = async (argv, link) => {
+export const cmdLogin = async (argv, link, autoLink = true) => {
     const f = flags(argv);
     const positional = argv[0] !== undefined && !argv[0].startsWith('--') ? argv[0] : undefined;
     const email = f['email'] ?? positional;
     if (email === undefined)
-        return cmdLoginDevice(f['url'], f['project'], link);
+        return cmdLoginDevice(f['url'], f['project'], link, autoLink);
     const org = f['org'];
     const url = baseUrl(null, f['url']);
     let code = f['code'];
@@ -159,7 +178,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, autoLink);
     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/launch/cli-launch.d.ts

@@ -12,6 +12,13 @@ export { summarizeStatus } from '../../daemon/binding/daemon-status-probe.js';
  * 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';
@@ -48,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): {

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

@@ -1,6 +1,6 @@
 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';
@@ -29,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 {
@@ -82,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)) {

package/dist/command/cli/ports/resolve/cli-port.d.ts

@@ -23,6 +23,13 @@ export declare const RETICLE_CONFIG_BASENAME = ".reticle.json";
  * Returns undefined when nothing is found, which keeps every caller's existing default intact.
  */
 export declare function findProjectConfig(cwd: string): Record<string, unknown> | undefined;
+/**
+ * The directory of the project this invocation serves: where its `.reticle.json` is, else the one
+ * wired workspace app below a monorepo root, else `cwd` itself. What the CLI reads the installed SDK
+ * from, so it answers for the app the port above belongs to rather than for the directory it was
+ * started in.
+ */
+export declare function projectDirOf(cwd: string): string;
 /**
  * The dev-server port heuristics live in `@reticlehq/init` — `existing-config.ts` is what diagnoses
  * a `.reticle.json` whose `port` is the app's own dev-server port, and the scaffolder may not import
@@ -33,8 +40,20 @@ export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
+ *
+ * With no config at or above `cwd`, it looks DOWN, the same way `projectIdsAt` does. Running from a
+ * monorepo root whose app was wired in `apps/web` used to find nothing and fall back to the default
+ * port, so `status`, `mcp` and `verify` quietly talked to another project's daemon. One wired app
+ * below, or several that agree, give their port; several that disagree give none, and
+ * `workspacePortConflict` is what says so rather than letting the default win in silence.
  */
 export declare function readProjectPort(cwd: string): number | undefined;
+/**
+ * The sentence for a monorepo root whose wired apps name different ports, or undefined when there is
+ * nothing to choose between. `readProjectPort` refuses to pick one; this is what tells the person
+ * which ports exist and how to name the one they meant.
+ */
+export declare function workspacePortConflict(cwd: string): string | undefined;
 /**
  * Read the stable projectId stored in the project's .reticle.json (written by `reticle init`). The daemon
  * uses it as the default resolve scope so auto-selection stays within the active app. Returns
@@ -63,6 +82,12 @@ export declare function projectIdsAt(cwd: string): ProjectId[];
  * time and the hint the agent reads hours later never mentioned it.
  */
 export declare function readProjectFramework(cwd: string): string | undefined;
+/**
+ * Whether the project this directory serves is a desktop shell (Electron, Tauri) — the same question
+ * `doctor` asks, answered from the same files. Read so the no-session guidance stops sending a
+ * desktop user to a browser URL.
+ */
+export declare function readProjectIsDesktop(cwd: string): boolean;
 /**
  * Whether the durable causal journal is enabled. On by default (the journal IS the loop); off only via
  * explicit opt-out — `.reticle.json` `"journal": false`, or `RETICLE_JOURNAL` set to `0`/`false`. The env