@reticlehq/server 3.8.2 → 3.10.0

package/dist/command/cli/verify-results.js

@@ -6,26 +6,92 @@
  * never rounded up to `yes`, and the run is `yes` only when every journey is.
  */
 import { RunFlowStatus, VerdictStatus, Verified, } from '@reticlehq/core';
+/**
+ * The shape of the `--results-json` file. 1 had only `verdict` and `results`; 2 adds `steps` per
+ * journey and the gated `score`. A consumer checks this before it reads a field that 1 did not have.
+ */
+export const RESULTS_SCHEMA_VERSION = 2;
+/**
+ * One journey's steps. `planned` is the flow file's step count, when the caller could read it:
+ * without it, a replay that stopped at step 2 of 10 would look like a 2-step journey. Replay adds a
+ * `success` step for a flow with a success oracle, so the total is the larger of the two.
+ */
+function stepCounts(flow, planned) {
+    let passed = 0;
+    let failed = 0;
+    let judgedUnits = 0;
+    let swept;
+    for (const step of (flow.stepResults ?? [])) {
+        // A sequence counts its sub-steps; any other step counts once.
+        const units = step.subSteps?.total ?? 1;
+        judgedUnits += units;
+        const ok = step.ok && step.drift === undefined;
+        // Gated: once a step failed, later verdicts are reported apart and never paid.
+        if (swept !== undefined) {
+            if (ok) {
+                swept.passed += units;
+            }
+            else {
+                swept.passed += step.subSteps?.passed ?? 0;
+                swept.failed += 1;
+            }
+            continue;
+        }
+        if (ok) {
+            passed += units;
+        }
+        else {
+            passed += step.subSteps?.passed ?? 0;
+            failed += 1;
+            swept = { passed: 0, failed: 0 };
+        }
+    }
+    const total = Math.max(planned ?? flow.steps, judgedUnits);
+    const counts = { passed, failed, unknown: total - passed - failed };
+    if (swept !== undefined && swept.passed + swept.failed > 0) {
+        counts.swept = swept;
+    }
+    return counts;
+}
 function journeyVerdict(status) {
-    if (RunFlowStatus.FAIL === status)
+    if (RunFlowStatus.FAIL === status) {
         return Verified.NO;
+    }
     // A heal is consequence-verified before it is reported, so it proves as much as a pass.
-    if (RunFlowStatus.PASS === status || RunFlowStatus.HEALED === status)
+    if (RunFlowStatus.PASS === status || RunFlowStatus.HEALED === status) {
         return Verified.YES;
+    }
     return Verified.UNKNOWN;
 }
-/** `pushed`: the run reached the platform, so its id resolves there and the results name it. */
-export function verifyResults(run, pushed = false) {
+/**
+ * `pushed`: the run reached the platform, so its id resolves there and the results name it.
+ * `planned`: each flow file's step count, by journey name (see `stepCounts`).
+ */
+export function verifyResults(run, pushed = false, planned = new Map()) {
     const results = run.flows.map((flow) => ({
         journey: flow.name,
         verdict: journeyVerdict(flow.status),
         ...(flow.failureReason === undefined ? {} : { reason: flow.failureReason }),
         ...(pushed ? { runId: run.runId } : {}),
+        steps: stepCounts(flow, planned.get(flow.name)),
     }));
-    const verdict = results.some((r) => Verified.NO === r.verdict)
-        ? Verified.NO
-        : VerdictStatus.PASS === run.verdict.status && results.every((r) => Verified.YES === r.verdict)
-            ? Verified.YES
-            : Verified.UNKNOWN;
-    return { verdict, results };
+    const sum = (key) => results.reduce((n, r) => n + r.steps[key], 0);
+    const passed = sum('passed');
+    const total = passed + sum('failed') + sum('unknown');
+    const score = {
+        passed,
+        failed: sum('failed'),
+        unknown: sum('unknown'),
+        total,
+        ...(0 === total ? {} : { value: passed / total }),
+    };
+    let verdict = Verified.UNKNOWN;
+    if (results.some((r) => Verified.NO === r.verdict)) {
+        verdict = Verified.NO;
+    }
+    else if (VerdictStatus.PASS === run.verdict.status &&
+        results.every((r) => Verified.YES === r.verdict)) {
+        verdict = Verified.YES;
+    }
+    return { schemaVersion: RESULTS_SCHEMA_VERSION, verdict, results, score };
 }

package/dist/command/cli.js

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
-import { PlatformLinkVia } from '@reticlehq/core/telemetry';
+import { OnboardingPhase, PlatformLinkVia } from '@reticlehq/core/telemetry';
 import { hudSignIn } from './cli/cloud-login.js';
-import { handleSetupMcp, handleSetupInstall } from './cli/setup-mcp-cli.js';
+import { agentsBlock, handleSetupMcp, handleSetupInstall, handleSetupWaitAgents, readAgentRows, shouldWaitForAgents, } from './cli/setup-mcp-cli.js';
 import { reportStepFromCli } from './cli-onboarding.js';
 import { pathToFileURL } from 'node:url';
 import { openFailureNote, openLaunchFailureNote } from './cli/answers/open-note.js';
+import { writeCiHint } from './cli/ci-hint.js';
+import { currentAutomationHint, isCiEnv } from '../telemetry/automation-hint.js';
 import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { installCrashGuard } from './setup/setup-command.js';
 import { handleStatus } from './cli/status-fields.js';
 export { handleStatus, reportStatus } from './cli/status-fields.js';
 import { reticleStateHome } from './daemon/daemon.js';
+import { ensureDaemon } from './cli/ensure-daemon.js';
 import { handleMcp } from './cli/mcp-command.js';
 import { handleReport } from './cli/report-command.js';
 import { handleContext } from './cli/context-command.js';
@@ -18,10 +21,11 @@ import { handleHook } from './cli/hook/hook-command.js';
 import { HOOK_COMMAND } from './cli/cli-parse.js';
 import { daemonProjectAt, readDaemonRegistry, resolveDaemonForProject, } from './daemon/daemon-resolve.js';
 import { pickDaemonPortToBind } from './daemon/binding/free-port.js';
+import { exitAfterClose } from './daemon/lifetime/daemon-exit.js';
 import { isSameOrAbove, portForInit, portFromEnv } from './setup/init/init-port.js';
 import { daemonStartOptions } from './cli/daemon-start-options.js';
 import { handleGate, loadNamedFlows, resolveChangedFiles } from './cli/cli-flow-commands.js';
-import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
+import { DaemonStartupError, RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
 import { loadDotEnv } from '../telemetry/dev-repo.js';
 import { licenseKeyFromEnvFiles } from '../features/license/license-env.js';
 import { LICENSE_KEY_ENV } from '../features/license/license.js';
@@ -33,34 +37,41 @@ import { startDaemon } from '../index.js';
 import { cmdLink, connectInstalls, isCloudCommand, runCloudCommand } from './cli/cloud-cli.js';
 import { SERVER_VERSION } from './version/identity/server-version.js';
 import { log } from '../log.js';
-import { isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon/daemon.js';
-import { PortPresence, probePresence, presenceIsUsable, describePresence, } from './daemon/binding/port-presence.js';
-import { waitForDaemon, probeDaemon } from '../surface/mcp/mcp-proxy.js';
+import { isAlive, removePid, discoverDaemonPort, writeDaemonRegistry } from './daemon/daemon.js';
+import { probePresence, presenceIsUsable } from './daemon/binding/port-presence.js';
+import { probeDaemon } from '../surface/mcp/mcp-proxy.js';
 import { installDaemonResilience, recordExitReason, DaemonExitReason, } from './daemon/daemon-resilience.js';
 import { IdleShutdown, resolveIdleShutdownMs, resolveIdleCheckMs } from './daemon/idle-shutdown.js';
 import { DaemonHeartbeat, resolveHeartbeatMs } from './daemon/lifetime/heartbeat.js';
 import { everServedToolCall } from './daemon/lifetime/daemon-usefulness.js';
-import { DAEMON_START_FAILED_EVENT } from './daemon/lifetime/startup-failure.js';
-import { summarizeStatus, warnOnDaemonSkew, decideOpen, openInBrowser, openCommand, } from './cli/launch/cli-launch.js';
+import { installStartupTrap, recordStartupFailure } from './daemon/lifetime/startup-failure.js';
+import { summarizeStatus, decideOpen, openInBrowser, openCommand, } from './cli/launch/cli-launch.js';
 import { NAVIGATE_NO_SESSION_ID, navigateLeftTab, openCandidates } from './cli/open-navigate.js';
 import { fetchStatus } from './daemon/binding/daemon-status-probe.js';
 import { handleDrive } from './cli/drive/drive-command.js';
 import { handleVerify } from './cli/cli-verify.js';
+import { handleVerifyAgainst } from './cli/verify-against.js';
+import { handleCompare } from './cli/two-builds/compare-command.js';
+import { handleGrade } from './cli/finished-run/grade-command.js';
+import { FIRST_VERDICT_REASON, bareRunsFirstVerdict } from './cli/first-verdict.js';
+import { cmdFirstVerdict } from './cli/first-verdict-node.js';
+import { reportOnboardingStop } from '../telemetry/onboarding-funnel.js';
 import { runKill } from './cli/cli-kill.js';
 import { runInit, buildNodeIo, InitFailure } from '@reticlehq/init';
 import { continueAfterInit } from './setup/init/init-runtime.js';
 import { initFirstFlow } from './cli/try-command.js';
 import { handleDoctor } from './cli/cli-doctor.js';
+import { writeFirstUseWarnings } from './cli/first-use-checks.js';
 import { serverInitHost } from './setup/init/init-host.js';
 import { describeLicense } from '../features/license/license.js';
 import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId, workspacePortConflict, projectDirOf, } from './cli/ports/resolve/cli-port.js';
 import { helpRunsAt, helpVersionNote, nodeSpawner, readTextFile, reexecAtVersion, versionMatchNote, versionToMatch, } from './cli/launch/sdk-version-match.js';
-import { DAEMON_INNER_COMMAND, PORT_FLAG, parseCliArgs, CLI_USAGE, dialsTheDaemon, } from './cli/cli-parse.js';
+import { PORT_FLAG, parseCliArgs, CLI_USAGE, dialsTheDaemon } from './cli/cli-parse.js';
 import { renderHelp } from './cli/cli-usage.js';
 import { RENAMED_COMMANDS, renamedCommandFor, renamedNote } from './cli/cli-parse-grammar.js';
 import { handleFeedback, handleTelemetry } from '../telemetry/feedback-cli.js';
 import { installDaemonTelemetry } from '../telemetry/daemon-telemetry.js';
-import { reportCliRun } from '../telemetry/cli-telemetry.js';
+import { reportCliRun, reportGateCompleted } from '../telemetry/cli-telemetry.js';
 // Re-exported so existing imports (and the CLI tests) keep resolving from '@/cli.js'.
 export { parseCliArgs, CLI_USAGE };
 /** Said when `connect` carries on past an init whose setup did not finish. */
@@ -94,6 +105,11 @@ async function handleInit(parsed) {
     // RETICLE_PORT counts as explicit, as it does for every other command: resolved once here, so the
     // port written into the project and the port the runtime phase binds are the same number.
     const explicit = parsed.port ?? portFromEnv(process.env);
+    // The bridge port matters only when init goes on to start the app.
+    const bridgePort = true === parsed.filesOnly || parsed.dryRun
+        ? undefined
+        : (explicit ?? readProjectPort(cwd) ?? RETICLE_DEFAULT_PORT);
+    await writeFirstUseWarnings(bridgePort);
     const port = await portForInit(explicit, readProjectPort(cwd), readProjectId(cwd), {
         // The registry names a daemon's owner; an older daemon that never registered is known by the
         // projects its connected pages announced.
@@ -134,7 +150,7 @@ async function handleInit(parsed) {
         deferOutcome: true,
         continuesToRuntime: true !== parsed.filesOnly && true !== parsed.dryRun,
     }, io);
-    await continueAfterInit({ ...parsed, port }, result, io, cwd, initFirstFlow);
+    await continueAfterInit({ ...parsed, port }, result, io, cwd, initFirstFlow, (print, mayWait) => agentsBlock(readAgentRows(cwd), print, mayWait && shouldWaitForAgents(process.stdout.isTTY, isCiEnv(process.env))));
     return result;
 }
 // `serve`, `stop` and `restart` live in `cli/lifecycle/daemon-lifecycle.ts`: one idea, and the
@@ -149,12 +165,12 @@ import { handleServe, handleStop, handleRestart } from './cli/lifecycle/daemon-l
 function handleVersion() {
     process.stdout.write(`${SERVER_VERSION}\n`);
 }
-/** `reticle license` — show enterprise activation resolved from the environment (offline; nothing leaves). */
+/** `reticle license` (now `status`) — show enterprise activation resolved from the environment (offline; nothing leaves). */
 function handleLicense() {
     log('reticle_license', { ...describeLicense(Date.now()) });
 }
 /**
- * `reticle affected <file...>` — print which saved flows must re-verify for the given changed files.
+ * `reticle gate --list <file...>` (was `affected`) — print which saved flows must re-verify for the given changed files.
  * Environment-side (costs the agent nothing per turn); the foundation of watch/gate. Never throws:
  * a load error is logged, not fatal.
  */
@@ -178,32 +194,6 @@ async function handleAffected(files, since) {
         });
     }
 }
-/** Ensure a daemon is reachable on `port` (probe the real port; spawn + wait only if nothing's there). */
-function ensureDaemon(port) {
-    return probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }).then(async (presence) => {
-        // Attaching to whatever already owns the port is the whole point of a daemon — but it means an
-        // upgrade does NOT take effect until that daemon dies, and nothing used to say so. Say it here,
-        // where both versions are in hand, and keep attaching: killing another agent's daemon on a
-        // version bump is worse than a loud warning.
-        if (presenceIsUsable(presence)) {
-            return warnOnDaemonSkew(port);
-        }
-        // Not free, not a daemon: a stranger holds the port. Spawning here is guaranteed to fail —
-        // the child cannot bind — and `waitForDaemon` would then report READY anyway, because its
-        // probe is the same bare TCP connect and the stranger accepts. That is the "serve reports
-        // success for a daemon that never bound" shape. Refuse instead, with the sentence `doctor`
-        // says.
-        if (PortPresence.FREE !== presence) {
-            throw new Error(describePresence(presence, port));
-        }
-        const scriptPath = process.argv[1];
-        if (scriptPath === undefined) {
-            throw new Error('cannot locate the reticle daemon script');
-        }
-        spawnDaemon(process.execPath, scriptPath, [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)], port);
-        return waitForDaemon(port);
-    });
-}
 /**
  * `reticle open [url]` — the one-command "show me the app". Resolves the port (the requested one if a
  * daemon's there, else a running daemon it discovers — so the user never hunts for the port), ensures
@@ -212,6 +202,8 @@ function ensureDaemon(port) {
  */
 /** How long `reticle open` waits for the launched page to register before reporting on it. */
 const OPEN_SESSION_WAIT_MS = 8000;
+/** For the heartbeat's resident memory, in MB. */
+const BYTES_PER_MB = 1024 * 1024;
 /**
  * Poll until a NEW session shows up, or the wait runs out. Returns whether one did.
  *
@@ -342,8 +334,12 @@ function handleDaemonInner(parsed) {
         hudSignIn: (repaint, link) => hudSignIn(repaint, undefined, undefined, link),
         hudLink: (root) => cmdLink([], root, PlatformLinkVia.HUD),
     };
+    // Until the daemon is ready, a throw or a rejection is a failed start. Write it to the log with
+    // its code, so the next start can say why this one died (#2043).
+    const disposeStartupTrap = installStartupTrap(process, log);
     startDaemon(options)
         .then((server) => {
+        disposeStartupTrap();
         log('reticle_daemon_ready', { port: parsed.port, pid: process.pid });
         // Daemon lifecycle telemetry: started, a one-shot project profile, the periodic counter flush,
         // and the rich summary on shutdown. All of it lives in one module — see daemon-telemetry.ts.
@@ -375,24 +371,15 @@ function handleDaemonInner(parsed) {
             // to reach a socket that is still open.
             server.announceShutdown?.();
             // Awaited before the close/exit chain: `process.exit(0)` kills an in-flight POST, and this is
-            // the one event carrying the whole session. A failed send resolves anyway (emit swallows its
-            // own errors), so this can delay the exit by at most the send timeout, never prevent it.
-            void daemonTelemetry
-                // The reason rides out on the session summary, which is the only event that fires at this
-                // exact moment. The proxy emits the matching `mcp_connection_lost` and cannot know it —
-                // it sees a socket end and nothing more, which is how a scheduled idle exit came to make up
-                // the large majority of "outages". See SessionSummary.exit.
-                .shutdown(reason)
-                .then(() => server.close())
-                .then(() => {
-                removePid(parsed.port);
-                process.exit(0);
-            })
-                .catch((err) => {
-                const message = err instanceof Error ? err.message : String(err);
-                log('reticle_daemon_close_error', { error: message });
+            // the one event carrying the whole session. The reason rides out on the session summary;
+            // the proxy sees only a socket end. See SessionSummary.exit. The summary and the close share
+            // one bound, so a close that never settles cannot keep this process on its port (#1937).
+            void exitAfterClose({
+                summary: () => daemonTelemetry.shutdown(reason),
+                close: () => server.close(),
+            }).then((code) => {
                 removePid(parsed.port);
-                process.exit(1);
+                process.exit(code);
             });
         };
         // Wrapped rather than passed directly: a signal handler receives the signal name as its first
@@ -432,12 +419,13 @@ function handleDaemonInner(parsed) {
             facts: () => ({
                 sessions: server.bridge.sessions.count(),
                 served: everServedToolCall(),
+                rssMb: Math.round(process.memoryUsage().rss / BYTES_PER_MB),
             }),
         }).start();
     })
         .catch((error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        log(DAEMON_START_FAILED_EVENT, { error: message });
+        disposeStartupTrap();
+        recordStartupFailure(log, error, DaemonStartupError.START);
         removePid(parsed.port);
         process.exit(1);
     });
@@ -515,7 +503,7 @@ export function main() {
         const colour = true === process.stderr.isTTY && process.env['NO_COLOR'] === undefined;
         process.stderr.write(`${renamedNote(argv[0] ?? '', renamedTo, colour)}\n`);
     }
-    // Cloud subcommands (login/link/project/config/push) are a distinct family with their own async client;
+    // Cloud subcommands (connect/sync/runs/config) are a distinct family with their own async client;
     // handle them before the local typed parser so `reticle login` etc. work as one tool.
     if (isCloudCommand(argv[0])) {
         // Asking a command what it does is never a request to run it. These dispatch before the typed
@@ -617,6 +605,17 @@ export function main() {
             void handleInit(parsed);
             break;
         case 'serve':
+            // Bare `reticle` in a folder Reticle has not wired: the first verdict, with no agent and no
+            // `init`. A wired project, and `reticle serve` itself, keep serving.
+            if (bareRunsFirstVerdict(argv, myProjectId !== undefined || projectPort !== undefined || portConflict !== undefined)) {
+                void cmdFirstVerdict(parsed.port, !parsed.headless, (row) => reportOnboardingStop({ phase: OnboardingPhase.FIRST_RUN, reason: FIRST_VERDICT_REASON, ...row }, { detach: true }))
+                    .then((code) => process.exit(code))
+                    .catch((cause) => {
+                    process.stderr.write(`reticle: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+                    process.exit(1);
+                });
+                break;
+            }
             handleServe(parsed);
             break;
         case 'stop':
@@ -633,7 +632,8 @@ export function main() {
             void handleRestart(parsed.port, parsed.force);
             break;
         case 'status':
-            void handleStatus(parsed.port, parsed.json);
+            // Offline: the license key is read from the environment.
+            void handleStatus(parsed.port, parsed.json, { ...describeLicense(Date.now()) });
             break;
         case 'license':
             handleLicense();
@@ -655,17 +655,24 @@ export function main() {
             process.exit(1);
             break;
         case 'doctor':
-            void handleDoctor(parsed.port);
+            void handleDoctor(parsed.port, parsed.fix, reportStepFromCli);
             break;
         case 'setup-mcp':
-            handleSetupMcp(reportStepFromCli);
+            void writeFirstUseWarnings().then(() => {
+                handleSetupMcp(reportStepFromCli, true, shouldWaitForAgents(process.stdout.isTTY, isCiEnv(process.env)));
+            });
+            break;
+        case 'setup-wait-agents':
+            void handleSetupWaitAgents(shouldWaitForAgents(process.stdout.isTTY, isCiEnv(process.env)));
             break;
         case 'setup-install':
-            handleSetupInstall({
-                runtimeSecs: parsed.runtimeSecs,
-                installSecs: parsed.installSecs,
-                mcp: parsed.mcp,
-            }, reportStepFromCli);
+            void writeFirstUseWarnings().then(() => {
+                handleSetupInstall({
+                    runtimeSecs: parsed.runtimeSecs,
+                    installSecs: parsed.installSecs,
+                    mcp: parsed.mcp,
+                }, reportStepFromCli);
+            });
             break;
         case 'open':
             handleOpen(parsed.port, parsed.url, parsed.navigate);
@@ -674,13 +681,48 @@ export function main() {
             handleDrive(parsed, readProjectId(process.cwd()));
             break;
         case 'verify':
-            handleVerify(parsed);
+            void writeFirstUseWarnings().then(async () => {
+                // `--against` compares two builds through the daemon, and starts one when there is none.
+                if (parsed.against !== undefined) {
+                    await handleVerifyAgainst({ ...parsed, against: parsed.against }, ensureDaemon, {
+                        line: (text) => process.stdout.write(`${text}\n`),
+                        fail: (text) => process.stderr.write(`${text}\n`),
+                        exit: (code) => process.exit(code),
+                    });
+                    return;
+                }
+                handleVerify(parsed, () => {
+                    writeCiHint({ automation: currentAutomationHint(process.env), machineOutput: false });
+                });
+            });
+            break;
+        case 'compare':
+            // Two builds through the daemon, which it starts when there is none. Nothing to install.
+            void handleCompare(parsed, ensureDaemon, {
+                line: (text) => process.stdout.write(`${text}\n`),
+                exit: (code) => process.exit(code),
+            });
+            break;
+        case 'grade':
+            // Reads the declared state sources and snapshot files. No daemon and no browser.
+            void handleGrade(parsed.args, {
+                line: (text) => process.stdout.write(`${text}\n`),
+                exit: (code) => process.exit(code),
+            });
             break;
         case 'affected':
-            void handleAffected(parsed.files, parsed.since);
+            void handleAffected(parsed.files, parsed.since).then(() => {
+                writeCiHint({ automation: currentAutomationHint(process.env), machineOutput: false });
+            });
             break;
         case 'gate':
-            void handleGate(parsed.files, parsed.since, parsed.hook, parsed.acceptCoverage);
+            void handleGate(parsed.files, parsed.since, parsed.hook, parsed.acceptCoverage, reportGateCompleted).then(() => {
+                // A stop hook's output is read by the agent, so it is a machine output mode.
+                writeCiHint({
+                    automation: currentAutomationHint(process.env),
+                    machineOutput: true === parsed.hook,
+                });
+            });
             break;
         case 'report':
             void handleReport(parsed.session, parsed.hook);

package/dist/command/daemon/binding/daemon-status-probe.d.ts

@@ -9,7 +9,9 @@
  */
 export declare function fetchStatus(port: number, host?: string, 
 /** Also tell the daemon a setup run is waiting on it, so it does not idle out mid-wait. */
-hold?: boolean): Promise<unknown>;
+hold?: boolean, 
+/** A longer limit, for a caller that must not mistake a busy daemon for a stuck one. */
+timeoutMs?: number): Promise<unknown>;
 /** One connected tab as `reticle status` reports it — the at-a-glance health line. */
 interface StatusSession {
     sessionId: string;

package/dist/command/daemon/binding/daemon-status-probe.js

@@ -42,13 +42,15 @@ const ReticleStatusSchema = z
  */
 export function fetchStatus(port, host = LOOPBACK_HOST, 
 /** Also tell the daemon a setup run is waiting on it, so it does not idle out mid-wait. */
-hold = false) {
+hold = false, 
+/** A longer limit, for a caller that must not mistake a busy daemon for a stuck one. */
+timeoutMs = STATUS_PROBE_TIMEOUT_MS) {
     return new Promise((resolve) => {
         const req = http.get({
             host,
             port,
             path: hold ? `${STATUS_PATH}?${STATUS_HOLD_QUERY}=1` : STATUS_PATH,
-            timeout: STATUS_PROBE_TIMEOUT_MS,
+            timeout: timeoutMs,
             // Shares the proxy's keep-alive agent: the proxy calls this on every reconnect, and a socket
             // per probe is the same churn the POST leg was fixed for.
             agent: loopbackAgent,

package/dist/command/daemon/daemon-argv.d.ts

@@ -0,0 +1,9 @@
+/** The argv word that runs the daemon itself. `serve` and the MCP proxy spawn it; a person never types it. */
+export declare const DAEMON_INNER_COMMAND = "_daemon";
+/**
+ * True when `commandLine` runs a Reticle daemon (#1937).
+ *
+ * The MCP proxy (`reticle mcp`) and every other process fail this test, so nothing that relies on
+ * it can stop the agent's proxy or a stranger's process.
+ */
+export declare function isReticleDaemonCommand(commandLine: string): boolean;

package/dist/command/daemon/daemon-argv.js

@@ -0,0 +1,11 @@
+/** The argv word that runs the daemon itself. `serve` and the MCP proxy spawn it; a person never types it. */
+export const DAEMON_INNER_COMMAND = '_daemon';
+/**
+ * True when `commandLine` runs a Reticle daemon (#1937).
+ *
+ * The MCP proxy (`reticle mcp`) and every other process fail this test, so nothing that relies on
+ * it can stop the agent's proxy or a stranger's process.
+ */
+export function isReticleDaemonCommand(commandLine) {
+    return commandLine.trim().split(/\s+/).includes(DAEMON_INNER_COMMAND);
+}

package/dist/command/daemon/daemon-resolve.d.ts

@@ -98,7 +98,14 @@ export declare function projectlessNote(myPort: number, others: readonly {
  * record naming a daemon that is not the one being asked. The wording says which side is empty,
  * since the failure is invisible precisely because both sides look healthy from where they stand.
  */
-export declare function splitBrainNote(myPort: number, elsewhere: readonly number[]): string | undefined;
+export declare function splitBrainNote(myPort: number, elsewhere: readonly number[], 
+/** This project and the registry home, to tell whether the app's daemon belongs to another project. */
+owner?: {
+    projectId: string | undefined;
+    home: string;
+}, 
+/** Where `RETICLE_PORT` is read from; injectable so the note is testable. */
+env?: Readonly<Record<string, string | undefined>>): string | undefined;
 /**
  * The other stance on the same split, for a command standing on the port that HAS the app.
  *

package/dist/command/daemon/daemon-resolve.js

@@ -20,6 +20,7 @@ import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '@reticlehq/core/artifacts';
 import { ReticleEnv, RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+import { portFromEnv } from '../setup/init/init-port.js';
 const RETICLE_PORT_ENV = ReticleEnv.PORT;
 /**
  * Every well-formed registry entry in `home`.
@@ -151,11 +152,36 @@ export function projectlessNote(myPort, others) {
  * record naming a daemon that is not the one being asked. The wording says which side is empty,
  * since the failure is invisible precisely because both sides look healthy from where they stand.
  */
-export function splitBrainNote(myPort, elsewhere) {
+export function splitBrainNote(myPort, elsewhere, 
+/** This project and the registry home, to tell whether the app's daemon belongs to another project. */
+owner, 
+/** Where `RETICLE_PORT` is read from; injectable so the note is testable. */
+env = process.env) {
     if (0 === elsewhere.length)
         return undefined;
     const listed = elsewhere.map((port) => `:${String(port)}`).join(', ');
     const first = elsewhere[0] ?? myPort;
+    // The app landed on ANOTHER project's daemon (#1652): two projects share a port. `resolveMcpPort`
+    // never adopts a daemon registered to a different project, so RETICLE_PORT would only relocate the
+    // agent again. The step that works is giving this project its own port, so its app comes here.
+    // Owner by port alone is safe: `elsewhere` is already liveness-filtered (`daemonsServingProjectElsewhere`).
+    const holder = owner === undefined ? undefined : daemonProjectAt(first, owner.home);
+    if (owner !== undefined && holder !== undefined && !adoptable(holder, owner.projectId)) {
+        // Port resolution is env-first (`--port`, `RETICLE_PORT`, `.reticle.json`, 4400), so a
+        // `RETICLE_PORT` left in the agent's MCP config from the old advice outranks the new `port`.
+        const envFirst = portFromEnv(env) === undefined
+            ? 'Give this project its own port instead: set'
+            : `Give this project its own port instead: first remove ${RETICLE_PORT_ENV} from the agent's ` +
+                'MCP config, because it takes precedence over `.reticle.json`, then set';
+        return (`this project's app is connected to the Reticle daemon on :${String(first)}, which is ` +
+            `registered to another project, "${holder}", while this project's daemon is on ` +
+            `:${String(myPort)} — the two projects share a port, and the agent is attached to the empty ` +
+            `half. Pointing the agent at :${String(first)} will not help: an MCP server never attaches to ` +
+            `another project's daemon. ${envFirst} \`port\` in its ` +
+            `.reticle.json to one no other project uses (for example ${String(myPort)}), then restart the ` +
+            `dev server so the app connects to this project's daemon, and restart the agent session. ` +
+            `Leave :${String(first)} running; it serves "${holder}".`);
+    }
     // The agent moves, not the app (#1546). The daemon the app is on is a working session this agent
     // did not start, and it may be a person's, another agent's or another project's. Stopping it was
     // the first thing this used to say. It comes last now, with what it costs.

package/dist/command/daemon/daemon.d.ts

@@ -1,3 +1,4 @@
+import { type DeathCause } from './lifetime/death-cause.js';
 import { type EscapeRequest, type EscapeResult } from './win32-escape.js';
 export { MAX_DAEMON_LOG_BYTES, recoverOversizedLog } from './lifetime/log-cap.js';
 /** Env override for the whole state directory — see ReticleEnv.STATE_DIR. */
@@ -22,6 +23,11 @@ export declare function rotateDaemonLog(path: string, deps: {
     renameFile(from: string, to: string): void;
 }, max?: number): boolean;
 export declare function readPid(port: number, home?: string): number | null;
+/**
+ * Whether a process with this pid exists. `EPERM` means it exists and this process may not signal
+ * it, which a daemon that WMI started can answer on Windows; only `ESRCH` means it is gone. Reading
+ * every throw as "dead" reclaimed a live daemon and started a second one on its port.
+ */
 export declare function isAlive(pid: number): boolean;
 export declare function writePid(port: number): void;
 /**
@@ -49,13 +55,22 @@ export declare function isRunning(port: number): boolean;
  * (lowest port, deterministic), or null when none is running.
  */
 export declare function discoverDaemonPort(): number | null;
+/**
+ * Does this pidfile name a daemon that is still running?
+ *
+ * The pid must be alive AND the file must be newer than the last boot. A pid alone is not enough:
+ * the OS reuses pids, and after a reboot a pidfile named an unrelated Bluetooth service on Windows.
+ * The port was free, but serve skipped the start because that pid was alive, and the daemon never
+ * came up. A file whose age cannot be read is judged by its pid alone, as before.
+ */
+export declare function pidFileIsLive(path: string, pid: number, pidAlive: (pid: number) => boolean, bootMs?: () => number): boolean;
 /**
  * Sweep ~/.reticle for daemon-<port>.pid files whose process is no longer alive and delete them, so a
  * crashed daemon never leaves a stale pidfile that confuses discovery or makes a port look "taken".
  * Returns the ports reclaimed. `home` and `pidAlive` are injectable for testing (default to the real
  * ~/.reticle and the process.kill(pid,0) liveness probe).
  */
-export declare function reclaimStaleDaemons(home?: string, pidAlive?: (pid: number) => boolean): number[];
+export declare function reclaimStaleDaemons(home?: string, pidAlive?: (pid: number) => boolean, bootMs?: () => number): number[];
 /** The minimal shape of a spawned child that spawnDaemon uses. */
 export interface SpawnedChild {
     readonly pid?: number | undefined;
@@ -76,15 +91,18 @@ export interface SpawnDaemonDeps {
         env?: Record<string, string | undefined>;
     }): SpawnedChild;
     pidAlive(pid: number): boolean;
+    /** When the machine last booted, epoch ms. Optional: the default reads `os.uptime()`. */
+    readonly bootTimeMs?: () => number;
     /** `process.platform`. Optional so a test that does not care runs the detached start. */
     readonly platform?: string;
     /** Windows only: start the daemon outside the Job Object of this process. See win32-escape.ts. */
     readonly escapeJob?: (request: EscapeRequest) => EscapeResult;
     /**
-     * A predecessor died without a clean stop; `ageMs` is how long it had run. Optional so a test that
-     * does not care reports nothing. The default sends `daemon_died_unclean`.
+     * A predecessor died without a clean stop; `ageMs` is how long it had run, and `cause` is what its
+     * own log says about how it ended. Optional so a test that does not care reports nothing. The
+     * default sends `daemon_died_unclean`.
      */
-    onUncleanDeath?(ageMs: number): void;
+    onUncleanDeath?(ageMs: number, cause?: DeathCause): void;
 }
 /**
  * Spawn the reticle daemon as a detached background process, redirecting output to the log file.