@reticlehq/server 3.9.0 → 3.10.0

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

@@ -0,0 +1,187 @@
+/**
+ * `reticle verify <candidate-url> --against <reference-url>`: did a change alter what users see?
+ *
+ * It drives both running builds with the same actions (the saved flows, and the explorer on the
+ * reference) and reports each difference in what a person can read and use. The rules are in
+ * `@/features/compare`. This file connects them to the running daemon: each run is a leased tab,
+ * and each read or action is a tool call on that tab, the same calls an agent makes.
+ */
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ReticleDir, ReticleTool, SnapshotMode, isConsequenceDrift, selectFlows, } from '@reticlehq/core';
+import { compareBuilds } from '../../features/compare/compare-run.js';
+import { compareExit, compareJson, compareLines } from '../../features/compare/compare-report.js';
+import { FlowStore } from '../../language/flows/flows.js';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+import { callerArtifactRoot } from '../../memory/project/link-directory.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../portal/bridge/pairing-token.js';
+import { acquireLease, connectOverSse, endpointFor, payloadOf, refusalText, releaseLease, } from './daemon-link/daemon-client.js';
+/** How long a navigation may take before the start page counts as not loaded. */
+const NAVIGATE_WAIT_MS = 15_000;
+/** One replayed flow step: a step can wait for its own consequence, so give it room. */
+const REPLAY_STEP_CALL_MS = 120_000;
+/** How long to wait after each action before the page is read, so a short timer can fire. */
+export const AGAINST_WAIT_MS = 300;
+/** The explorer's action budget on the reference. */
+export const AGAINST_MAX_ACTIONS = 150;
+/** The label of a replayed step that names no anchor. */
+const UNNAMED_STEP = 'step';
+const MSG_LEASE_FAILED = 'could not open a browser on';
+const MSG_NO_DAEMON = 'could not reach the daemon on port';
+const asText = (value) => 'string' === typeof value ? value : undefined;
+/** A step that ran: it passed, or its action ran and only its declared consequence did not hold. */
+function stepDone(step) {
+    if (step === undefined) {
+        return false;
+    }
+    if (true === step['ok']) {
+        return true;
+    }
+    const drift = step['drift'];
+    const reason = asText(drift?.reasonKind);
+    return reason !== undefined && isConsequenceDrift(reason);
+}
+/** One leased tab, as the compare driver. Every call goes through `reticle_run` on that tab. */
+export function daemonDriver(caller, tab) {
+    let sessionId = tab.sessionId;
+    const run = async (tool, args, timeoutMs) => {
+        const result = await caller.call(ReticleTool.RUN, { tool, args: { ...args, sessionId } }, timeoutMs);
+        return { payload: payloadOf(result), refused: refusalText(result) !== undefined };
+    };
+    const snapshot = async (mode) => (await run(ReticleTool.SNAPSHOT, { mode })).payload;
+    return {
+        async reset() {
+            const { payload, refused } = await run(ReticleTool.NAVIGATE, { url: tab.url, timeout_ms: NAVIGATE_WAIT_MS }, NAVIGATE_WAIT_MS * 2);
+            const next = asText(payload['sessionId']);
+            if (next !== undefined) {
+                sessionId = next;
+            }
+            return !refused && true === payload['ok'] && false !== payload['confirmed'];
+        },
+        async look() {
+            const body = await snapshot(SnapshotMode.INTERACTIVE);
+            const route = asText(body['status']?.route);
+            return { tree: asText(body['tree']) ?? '', ...(route === undefined ? {} : { route }) };
+        },
+        async read() {
+            return asText((await snapshot(SnapshotMode.FULL))['tree']) ?? '';
+        },
+        async act(ref, action, value) {
+            const { payload, refused } = await run(ReticleTool.ACT, {
+                ref,
+                action,
+                args: value === undefined ? {} : { value },
+            });
+            return { ok: !refused && false !== payload['dispatched'], events: [] };
+        },
+        async replayStep(flow, index) {
+            const { payload } = await run(ReticleTool.FLOW_REPLAY, {
+                flowName: flow,
+                to: index + 1,
+                ...(0 === index ? {} : { at: index }),
+                ...(true === tab.confirmDangerous ? { confirmDangerous: true } : {}),
+            }, REPLAY_STEP_CALL_MS);
+            const steps = Array.isArray(payload['steps']) ? payload['steps'] : [];
+            const step = steps.map((s) => s).find((s) => index === s['step']);
+            return { done: stepDone(step), label: asText(step?.['anchor']) ?? UNNAMED_STEP };
+        },
+        async close() {
+            if (tab.closeLease) {
+                await releaseLease(caller, sessionId);
+            }
+        },
+    };
+}
+/** The saved flows a run replays, with `--select` applied, and how many steps each has. */
+export async function flowsToReplay(fs, reticleRoot, select, now) {
+    const store = new FlowStore(fs, reticleRoot, { now });
+    const files = [];
+    for (const name of await store.list()) {
+        const loaded = await store.load(name);
+        if (loaded.ok) {
+            files.push(loaded.value);
+        }
+    }
+    const chosen = selectFlows(files, select === undefined ? {} : { labels: [...select] }).run;
+    return chosen.map((flow) => ({ name: flow.name, steps: flow.steps.length }));
+}
+/** Compare the two builds through the daemon on `port`. Returns the lines to print and the exit code. */
+export async function runVerifyAgainst(options) {
+    const connect = options.connect ?? connectOverSse;
+    let caller;
+    try {
+        caller = await connect(endpointFor(options.port, options.token));
+    }
+    catch (error) {
+        const why = error instanceof Error ? error.message : String(error);
+        return { code: 1, lines: [`${MSG_NO_DAEMON} ${String(options.port)}: ${why}`] };
+    }
+    const open = async (url) => {
+        const lease = await acquireLease(caller, url, false, options.root);
+        if ('failed' in lease) {
+            throw new Error([`${MSG_LEASE_FAILED} ${url}`, ...lease.failed].join('\n'));
+        }
+        return daemonDriver(caller, {
+            url,
+            sessionId: lease.leased,
+            closeLease: true,
+            ...(true === options.confirmDangerous ? { confirmDangerous: true } : {}),
+        });
+    };
+    try {
+        const result = await compareBuilds({
+            reference: options.reference,
+            candidate: options.candidate,
+            open,
+            flows: options.flows,
+            maxActions: AGAINST_MAX_ACTIONS,
+            wait: () => options.sleep(AGAINST_WAIT_MS),
+        });
+        const urls = { reference: options.reference, candidate: options.candidate };
+        if (options.resultsJson !== undefined) {
+            const write = options.write ?? ((path, text) => writeFile(path, text, 'utf8'));
+            await write(options.resultsJson, `${JSON.stringify(compareJson(urls, result), null, 2)}\n`);
+        }
+        return { code: compareExit(result), lines: compareLines(urls, result) };
+    }
+    catch (error) {
+        return { code: 1, lines: [error instanceof Error ? error.message : String(error)] };
+    }
+    finally {
+        await caller.close().catch(() => undefined);
+    }
+}
+/**
+ * The command. It needs a daemon, as an agent does: `ensureDaemon` attaches to the one on the port,
+ * or starts one. Nothing here stops a daemon, so an agent's MCP link stays up.
+ */
+export async function handleVerifyAgainst(parsed, ensureDaemon, out) {
+    try {
+        await ensureDaemon(parsed.port);
+    }
+    catch (error) {
+        out.fail(error instanceof Error ? error.message : String(error));
+        out.exit(1);
+        return;
+    }
+    const cwd = process.cwd();
+    const root = callerArtifactRoot(cwd);
+    const token = readOrCreatePairingTokenSync(defaultPairingTokenDir());
+    // The same `.reticle` the leased tabs replay from, so the list and the replay agree.
+    const flows = await flowsToReplay(createNodeFileSystem(), root ?? join(cwd, ReticleDir.ROOT), parsed.select, Date.now);
+    const result = await runVerifyAgainst({
+        port: parsed.port,
+        candidate: parsed.url,
+        reference: parsed.against,
+        flows,
+        ...(token === undefined || 0 === token.length ? {} : { token }),
+        ...(root === undefined ? {} : { root }),
+        ...(true === parsed.confirmDangerous ? { confirmDangerous: true } : {}),
+        ...(parsed.resultsJson === undefined ? {} : { resultsJson: parsed.resultsJson }),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    });
+    for (const line of result.lines) {
+        out.line(line);
+    }
+    out.exit(result.code);
+}

package/dist/command/cli/verify-no-session.d.ts

@@ -0,0 +1,2 @@
+/** Why no session connected. A short timeout also says that the unit is milliseconds. */
+export declare function noSessionMessage(timeoutMs: number): string;

package/dist/command/cli/verify-no-session.js

@@ -0,0 +1,13 @@
+const MSG_NO_SESSION = 'No app connected: Reticle drove the URL but no @reticlehq/browser session dialed back.\n' +
+    '  Make sure the SDK is in the build and reticle.connect() runs on the preview page' +
+    ' (for a non-localhost preview: allowNonLocalhost + a pairing token).';
+/** A `--timeout` under this is likely a count of seconds, so the message names the unit. */
+const SHORT_TIMEOUT_MS = 1000;
+/** Why no session connected. A short timeout also says that the unit is milliseconds. */
+export function noSessionMessage(timeoutMs) {
+    if (timeoutMs >= SHORT_TIMEOUT_MS) {
+        return MSG_NO_SESSION;
+    }
+    return (`${MSG_NO_SESSION}\n  The wait was ${String(timeoutMs)} ms: the timeout is in milliseconds. ` +
+        'Use --timeout 60000 to wait 60 seconds.');
+}

package/dist/command/cli/verify-results.d.ts

@@ -7,7 +7,31 @@
  */
 import { Verified, type ReticleVerificationRun } from '@reticlehq/core';
 type JourneyVerdict = typeof Verified.YES | typeof Verified.NO | typeof Verified.UNKNOWN;
+/**
+ * How many steps passed, failed, or were never judged. `unknown` is a step the replay never
+ * reached or could not decide; it stays in the total, so an undecided step never raises a score.
+ */
+export interface StepCounts {
+    passed: number;
+    failed: number;
+    unknown: number;
+    /**
+     * Verdicts reached AFTER the journey's first failed step (`--sweep` goes on past it). They are not
+     * in `passed` or `failed`, and they count as `unknown` in the score: a step is paid only when every
+     * step before it passed. Absent when no step ran after a failure.
+     */
+    swept?: {
+        passed: number;
+        failed: number;
+    };
+}
+/**
+ * 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 declare const RESULTS_SCHEMA_VERSION = 2;
 export interface VerifyResults {
+    schemaVersion: number;
     verdict: JourneyVerdict;
     /** `runId` is the run the journey came from, set only when that run reached the platform. */
     results: {
@@ -15,8 +39,17 @@ export interface VerifyResults {
         verdict: JourneyVerdict;
         reason?: string;
         runId?: string;
+        steps: StepCounts;
     }[];
+    /** All journeys together. `value` is passed / total, absent when there is no step at all. */
+    score: StepCounts & {
+        total: number;
+        value?: number;
+    };
 }
-/** `pushed`: the run reached the platform, so its id resolves there and the results name it. */
-export declare function verifyResults(run: ReticleVerificationRun, pushed?: boolean): VerifyResults;
+/**
+ * `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 declare function verifyResults(run: ReticleVerificationRun, pushed?: boolean, planned?: ReadonlyMap<string, number>): VerifyResults;
 export {};

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

@@ -13,6 +13,7 @@ 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';
@@ -24,7 +25,7 @@ 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';
@@ -36,20 +37,22 @@ 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 } from './daemon/binding/port-presence.js';
-import { describePortState } from './daemon/port-state.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';
@@ -63,7 +66,7 @@ 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';
@@ -162,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.
  */
@@ -191,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(describePortState(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
@@ -357,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.
@@ -443,8 +424,8 @@ function handleDaemonInner(parsed) {
         }).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);
     });
@@ -522,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
@@ -651,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();
@@ -699,12 +681,35 @@ export function main() {
             handleDrive(parsed, readProjectId(process.cwd()));
             break;
         case 'verify':
-            void writeFirstUseWarnings().then(() => {
+            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).then(() => {
                 writeCiHint({ automation: currentAutomationHint(process.env), machineOutput: false });

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

@@ -55,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;
@@ -82,6 +91,8 @@ 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. */