@reticlehq/server 3.3.0 → 3.4.0

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

package/dist/command/cli/ports/resolve/cli-port.js

@@ -9,7 +9,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { SILENT_HOST, buildNodeIo, deriveProjectId, findWorkspaceApps, packageName, } from '@reticlehq/init';
+import { SILENT_HOST, buildNodeIo, deriveProjectId, findWorkspaceApps, isDesktopProject, packageName, } from '@reticlehq/init';
 import { asProjectId } from '@reticlehq/core';
 /** The project config `reticle init` writes. */
 export const RETICLE_CONFIG_BASENAME = '.reticle.json';
@@ -35,18 +35,15 @@ const MAX_CONFIG_SEARCH_DEPTH = 6;
  * Returns undefined when nothing is found, which keeps every caller's existing default intact.
  */
 export function findProjectConfig(cwd) {
+    const dir = findProjectConfigDir(cwd);
+    return dir === undefined ? undefined : readConfigAt(dir);
+}
+/** The directory holding the nearest `.reticle.json` at or above `cwd`, by the same walk. */
+function findProjectConfigDir(cwd) {
     let dir = resolve(cwd);
     for (let depth = 0; depth <= MAX_CONFIG_SEARCH_DEPTH; depth += 1) {
-        try {
-            const raw = readFileSync(`${dir}/${RETICLE_CONFIG_BASENAME}`, 'utf8');
-            const config = JSON.parse(raw);
-            if ('object' === typeof config && config !== null && !Array.isArray(config)) {
-                return config;
-            }
-        }
-        catch {
-            // Absent, unreadable, or not JSON at this level — keep walking.
-        }
+        if (readConfigAt(dir) !== undefined)
+            return dir;
         const parent = dirname(dir);
         if (parent === dir)
             break;
@@ -54,6 +51,48 @@ export function findProjectConfig(cwd) {
     }
     return 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 function projectDirOf(cwd) {
+    const configDir = findProjectConfigDir(cwd);
+    if (configDir !== undefined)
+        return appPointedAtBy(configDir) ?? configDir;
+    const apps = workspaceAppPorts(cwd);
+    const only = 1 === apps.length ? apps[0] : undefined;
+    return only === undefined ? resolve(cwd) : join(resolve(cwd), only.app);
+}
+/**
+ * The one workspace app below `dir` whose own config names the project `dir`'s does, or undefined.
+ *
+ * `init` writes a copy of the app's `.reticle.json` at the root the agent runs from, so the root's
+ * config is a pointer to that app rather than a project of its own. The projectId is the link — no
+ * path is stored — and a root whose id no app shares, or several do, is its own project.
+ */
+function appPointedAtBy(dir) {
+    const id = readConfigAt(dir)?.['projectId'];
+    if ('string' !== typeof id || 0 === id.length)
+        return undefined;
+    const named = workspaceApps(dir).filter((app) => id === readConfigAt(join(dir, app))?.['projectId']);
+    const only = 1 === named.length ? named[0] : undefined;
+    return only === undefined ? undefined : join(dir, only);
+}
+/** The `.reticle.json` in exactly `dir` — no walk — or undefined when absent or not an object. */
+function readConfigAt(dir) {
+    try {
+        const config = JSON.parse(readFileSync(join(dir, RETICLE_CONFIG_BASENAME), 'utf8'));
+        if ('object' === typeof config && config !== null && !Array.isArray(config)) {
+            return config;
+        }
+    }
+    catch {
+        // Absent, unreadable, or not JSON at this level.
+    }
+    return undefined;
+}
 /**
  * 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
@@ -61,15 +100,70 @@ export function findProjectConfig(cwd) {
  * diagnosis, and `cli.ts`) are unchanged.
  */
 export { DEV_SERVER_PORTS, isLikelyDevServerPort, devServerPortWarning } from '@reticlehq/init';
+/** A config's `port`, when it is a usable TCP port. */
+function configPort(config) {
+    const p = config?.['port'];
+    if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
+        return p;
+    return undefined;
+}
 /**
  * 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 function readProjectPort(cwd) {
-    const p = findProjectConfig(cwd)?.['port'];
-    if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
-        return p;
-    return undefined;
+    const config = findProjectConfig(cwd);
+    if (config !== undefined)
+        return configPort(config);
+    const ports = new Set(workspaceAppPorts(cwd).map((a) => a.port));
+    return 1 === ports.size ? [...ports][0] : undefined;
+}
+/** Each workspace app under `cwd` whose own `.reticle.json` records a port. */
+function workspaceAppPorts(cwd) {
+    const found = [];
+    for (const app of workspaceApps(cwd)) {
+        // The app's OWN file only — walking up from an unwired sibling would reach the root, or past it.
+        const port = configPort(readConfigAt(join(cwd, app)));
+        if (port !== undefined)
+            found.push({ app, port });
+    }
+    return found;
+}
+/** init's workspace discovery under `cwd`, relative app directories; empty when `cwd` is no package. */
+function workspaceApps(cwd) {
+    // Only from a directory that is itself a package: a root with no package.json is not a workspace,
+    // and scanning, say, a home directory would adopt the port of whichever checkout happened to sit
+    // there.
+    if (packageNameAt(cwd) === undefined)
+        return [];
+    try {
+        return findWorkspaceApps(buildNodeIo(cwd, SILENT_HOST));
+    }
+    catch {
+        // Discovery touches the filesystem; an unreadable tree is simply no further evidence.
+        return [];
+    }
+}
+/**
+ * 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 function workspacePortConflict(cwd) {
+    if (findProjectConfig(cwd) !== undefined)
+        return undefined;
+    const apps = workspaceAppPorts(cwd);
+    if (new Set(apps.map((a) => a.port)).size < 2)
+        return undefined;
+    const listed = apps.map((a) => `${a.app} (:${String(a.port)})`).join(', ');
+    return (`This workspace has more than one app wired for Reticle, on different ports: ${listed}. ` +
+        'Not guessing which one you meant — run the command from inside that app, or pass --port.');
 }
 /**
  * Read the stable projectId stored in the project's .reticle.json (written by `reticle init`). The daemon
@@ -142,6 +236,22 @@ export function readProjectFramework(cwd) {
         return framework;
     return 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 function readProjectIsDesktop(cwd) {
+    const dir = projectDirOf(cwd);
+    return isDesktopProject((relative) => {
+        try {
+            return readFileSync(join(dir, relative), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
 /**
  * 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