@reticlehq/server 2.11.0 → 2.12.0

package/dist/cli/gate-exit.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What `reticle gate` means by its exit code.
+ *
+ * Split out of the handler because two different readers depend on it and they want opposite
+ * things. CI wants any problem to be a failure. A Stop hook — the layer that makes verification
+ * unskippable — wants to block a real regression and NOT block a project that has simply not
+ * recorded a flow yet, which is every project on its first day.
+ *
+ * `NOTHING_TO_CHECK` stays non-zero deliberately. The gate exits non-zero over an empty suite
+ * because "nothing was checked" and "everything passed" are indistinguishable from the outside,
+ * and that reasoning does not stop being true just because a second caller appeared.
+ */
+export declare const GateExit: {
+    /** Affected flows were checked and hold. */
+    readonly PASS: 0;
+    /** Something is actually wrong: an affected flow with no passing artifact, a downgraded
+     * assertion, deleted coverage. A caller should stop here. */
+    readonly FAIL: 1;
+    /** The gate ran and had nothing to judge — no flows recorded. Non-zero, but not a regression. */
+    readonly NOTHING_TO_CHECK: 2;
+};

package/dist/cli/gate-exit.js

@@ -0,0 +1,21 @@
+/**
+ * What `reticle gate` means by its exit code.
+ *
+ * Split out of the handler because two different readers depend on it and they want opposite
+ * things. CI wants any problem to be a failure. A Stop hook — the layer that makes verification
+ * unskippable — wants to block a real regression and NOT block a project that has simply not
+ * recorded a flow yet, which is every project on its first day.
+ *
+ * `NOTHING_TO_CHECK` stays non-zero deliberately. The gate exits non-zero over an empty suite
+ * because "nothing was checked" and "everything passed" are indistinguishable from the outside,
+ * and that reasoning does not stop being true just because a second caller appeared.
+ */
+export const GateExit = {
+    /** Affected flows were checked and hold. */
+    PASS: 0,
+    /** Something is actually wrong: an affected flow with no passing artifact, a downgraded
+     * assertion, deleted coverage. A caller should stop here. */
+    FAIL: 1,
+    /** The gate ran and had nothing to judge — no flows recorded. Non-zero, but not a regression. */
+    NOTHING_TO_CHECK: 2,
+};

package/dist/cli/gate-hook-message.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a Stop hook shows the human when the gate blocks.
+ *
+ * A hook runs at the moment an agent says it is finished, and whatever it prints is the last thing
+ * anybody reads. The gate's normal output is one long JSON line built for CI to parse; pasted into
+ * a terminal at the end of a session it is a wall of names with no instruction attached.
+ *
+ * So the hook path gets prose. It has to answer three things in the order a person asks them: what
+ * is not verified, why that matters right now, and what to do about it — including how to proceed
+ * anyway, because a gate with no honest escape hatch gets disabled entirely and then protects
+ * nothing.
+ */
+/** Named so a reader of the hook output knows the flag is real and not a suggestion. */
+export declare const GATE_SKIP_ENV = "RETICLE_SKIP_GATE";
+export interface GateHookInput {
+    /** Flows the changed files touch that have no passing artifact. */
+    uncovered: readonly string[];
+    /** Flows held back as flaky — reported, never counted as a pass. */
+    quarantined: readonly string[];
+    /** Assertions that dropped from a real consequence to a fakeable one. */
+    downgraded: readonly string[];
+    /** Flows whose coverage was deleted while their files changed. */
+    deleted: readonly string[];
+}
+/**
+ * The message, or undefined when there is nothing to say.
+ *
+ * `NOTHING_TO_CHECK` returns undefined on purpose: a project that has not recorded a flow yet is
+ * every project on its first day, and blocking there would make the first experience of Reticle an
+ * agent that cannot stop. The gate still reports it — this decides only whether a HUMAN is
+ * interrupted.
+ */
+export declare function gateHookMessage(exit: number, input: GateHookInput): string | undefined;

package/dist/cli/gate-hook-message.js

@@ -0,0 +1,46 @@
+/**
+ * What a Stop hook shows the human when the gate blocks.
+ *
+ * A hook runs at the moment an agent says it is finished, and whatever it prints is the last thing
+ * anybody reads. The gate's normal output is one long JSON line built for CI to parse; pasted into
+ * a terminal at the end of a session it is a wall of names with no instruction attached.
+ *
+ * So the hook path gets prose. It has to answer three things in the order a person asks them: what
+ * is not verified, why that matters right now, and what to do about it — including how to proceed
+ * anyway, because a gate with no honest escape hatch gets disabled entirely and then protects
+ * nothing.
+ */
+import { GateExit } from './gate-exit.js';
+/** Named so a reader of the hook output knows the flag is real and not a suggestion. */
+export const GATE_SKIP_ENV = 'RETICLE_SKIP_GATE';
+const MAX_NAMED = 5;
+/** A short list, then a count — a hook that prints forty names is a hook people turn off. */
+function name(list) {
+    const shown = list.slice(0, MAX_NAMED).join(', ');
+    return list.length > MAX_NAMED ? `${shown} (+${String(list.length - MAX_NAMED)} more)` : shown;
+}
+/**
+ * The message, or undefined when there is nothing to say.
+ *
+ * `NOTHING_TO_CHECK` returns undefined on purpose: a project that has not recorded a flow yet is
+ * every project on its first day, and blocking there would make the first experience of Reticle an
+ * agent that cannot stop. The gate still reports it — this decides only whether a HUMAN is
+ * interrupted.
+ */
+export function gateHookMessage(exit, input) {
+    if (GateExit.FAIL !== exit)
+        return undefined;
+    const lines = ['Reticle: this change is not verified.'];
+    if (input.uncovered.length > 0)
+        lines.push(`  no passing run covers: ${name(input.uncovered)}`);
+    if (input.downgraded.length > 0)
+        lines.push(`  assertions weakened to something fakeable: ${name(input.downgraded)} — a check that cannot fail is not a check`);
+    if (input.deleted.length > 0)
+        lines.push(`  coverage deleted while its files changed: ${name(input.deleted)}`);
+    if (input.quarantined.length > 0)
+        lines.push(`  held back as flaky, so proving nothing: ${name(input.quarantined)}`);
+    lines.push('');
+    lines.push('  Replay them: npx @reticlehq/server verify <your app url>');
+    lines.push(`  Or proceed anyway: ${GATE_SKIP_ENV}=1 — it is recorded, not silent.`);
+    return lines.join('\n');
+}

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

@@ -0,0 +1,25 @@
+/**
+ * `reticle mcp` — the process an editor launches, and the one whose failure a user experiences as
+ * "the MCP server disconnected".
+ *
+ * Split out of `cli.ts` when that file passed the 1000-line backstop. It earns its own module rather
+ * than being an arbitrary slice: everything here is about ONE decision — which daemon this agent
+ * talks to for the rest of its life — and the port resolution at the top is the fix for agents on
+ * different projects silently sharing one daemon, one identity and one blast radius.
+ */
+/**
+ * MCP proxy mode: ensures the daemon is running, then bridges Claude Code's
+ * stdin/stdout to the daemon's SSE endpoint. This is the recommended way to
+ * configure Reticle in.mcp.json — users never need to manage the daemon manually.
+ *
+ * Pass --drive <url> to have the daemon launch its own Playwright browser at that
+ * URL. The agent then has full autonomous control without relying on the user's browser.
+ */
+export declare function handleMcp(opts: {
+    port: number;
+    driveUrl?: string;
+    headless: boolean;
+    http: boolean;
+    httpPort?: number;
+    httpToken?: string;
+}): Promise<void>;

package/dist/cli/mcp-command.js

@@ -0,0 +1,143 @@
+/**
+ * `reticle mcp` — the process an editor launches, and the one whose failure a user experiences as
+ * "the MCP server disconnected".
+ *
+ * Split out of `cli.ts` when that file passed the 1000-line backstop. It earns its own module rather
+ * than being an arbitrary slice: everything here is about ONE decision — which daemon this agent
+ * talks to for the rest of its life — and the port resolution at the top is the fix for agents on
+ * different projects silently sharing one daemon, one identity and one blast radius.
+ */
+import { log } from '../log.js';
+import { isAlive, spawnDaemon, reticleStateHome } from '../daemon/daemon.js';
+import { PortPresence, probePresence, presenceIsUsable, describePresence, } from '../daemon/port-presence.js';
+import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, } from '../mcp/mcp-proxy.js';
+import { installProxyResilience } from '../daemon/daemon-resilience.js';
+import { readProjectId } from './cli-port.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, } from './cli-parse.js';
+import { resolveMcpPort } from '../daemon/daemon-resolve.js';
+import { pickDaemonPortToBind } from '../daemon/free-port.js';
+import { fetchStatus } from './cli-launch.js';
+/**
+ * MCP proxy mode: ensures the daemon is running, then bridges Claude Code's
+ * stdin/stdout to the daemon's SSE endpoint. This is the recommended way to
+ * configure Reticle in.mcp.json — users never need to manage the daemon manually.
+ *
+ * Pass --drive <url> to have the daemon launch its own Playwright browser at that
+ * URL. The agent then has full autonomous control without relying on the user's browser.
+ */
+export async function handleMcp(opts) {
+    const { driveUrl, headless, http, httpPort, httpToken } = opts;
+    // Decided before anything else, because every line below is about ONE port and the wrong one means
+    // serving another project's daemon. `resolveMcpPort` prefers our own daemon wherever it moved to,
+    // takes the requested port when it is free or unclaimed, and relocates to an OS-assigned port
+    // rather than adopting a daemon that belongs to somebody else.
+    //
+    // Synchronous-looking on purpose: a probe is one loopback connect, and doing it here keeps the
+    // proxy's transport built around a single fixed number. Making the proxy chase a moving port would
+    // mean reworking the reconnect path, which is the one piece whose failure reads to a user as
+    // "the MCP server disappeared mid-session".
+    const port = await resolveMcpPort(opts.port, readProjectId(process.cwd()), reticleStateHome(), {
+        alive: isAlive,
+        daemonPresent: async (p) => presenceIsUsable(await probePresence(p, { tcpOpen: probeDaemon, status: fetchStatus })),
+        pickPort: (p) => pickDaemonPortToBind(p),
+    });
+    if (port !== opts.port) {
+        log('reticle_mcp_port_relocated', {
+            requested: opts.port,
+            port,
+            reason: 'the requested port serves a different project',
+        });
+    }
+    // The proxy IS the MCP server the editor launched. Nothing respawns it, so an uncaught throw here
+    // is what a user experiences as "the MCP server disconnected — open /mcp and reconnect". Log it,
+    // report it, keep serving: the reconnect and dormant paths already know how to rebuild the only
+    // state this process has. See installProxyResilience for why its rule inverts the daemon's.
+    // The proxy's crash handlers must write to the proxy's LOG FILE, not just stderr. The editor
+    // swallows stderr, so wiring these to `log` meant a crash was handled and then unrecorded — the
+    // failure a user reports as "it disconnected" left nothing behind to read.
+    setProxyLogPort(port);
+    installProxyResilience(process, proxyLog);
+    /**
+     * Make sure a daemon is on the port, spawning one if not.
+     *
+     * Called on first start AND on every reconnect. The proxy used to only retry the socket, so a
+     * daemon that exited — crashed, `reticle stop`, or self-shut-down as idle — meant the retries hit
+     * a dead port until the budget ran out and the agent's MCP server exited with it. Reticle simply
+     * disappeared mid-session with nothing said. Respawning here makes the reconnect self-healing.
+     */
+    const ensure = async () => {
+        // The same question every other surface asks. It used to be a bare TCP connect, so a stranger on
+        // the bridge port answered "a daemon is here" — the proxy connected, the stream ended, and each
+        // client request woke into the identical non-answer. Rejecting here is what puts the proxy
+        // dormant with a reason, instead of pretending the wake succeeded.
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        if (presenceIsUsable(presence))
+            return;
+        if (PortPresence.FREE !== presence)
+            throw new Error(describePresence(presence, port));
+        const scriptPath = process.argv[1];
+        if (scriptPath === undefined) {
+            log('reticle_mcp_no_script', {});
+            process.exit(1);
+        }
+        const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)];
+        if (driveUrl !== undefined) {
+            daemonArgs.push(DRIVE_FLAG, driveUrl);
+            if (!headless)
+                daemonArgs.push(HEADED_FLAG);
+        }
+        // Forward the HTTP-verify flags too (previously silently dropped for `reticle mcp`).
+        if (http) {
+            daemonArgs.push(HTTP_FLAG);
+            if (httpPort !== undefined)
+                daemonArgs.push(HTTP_PORT_FLAG, String(httpPort));
+            if (httpToken !== undefined)
+                daemonArgs.push(HTTP_TOKEN_FLAG, httpToken);
+        }
+        spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
+        // Announce the daemon only once the PORT ACCEPTS. This line used to be written the instant the
+        // child was spawned, which on a Windows first bootstrap meant `reticle_mcp_daemon_started`
+        // followed about ten seconds later by `reticle_mcp_daemon_unavailable` and a first
+        // `reticle_sessions` that expired. A readiness signal that precedes readiness is worse than
+        // none: a client that believes it stops waiting for the thing that has not happened.
+        await waitForDaemon(port);
+        log('reticle_mcp_daemon_started', { port, ...(driveUrl !== undefined ? { driveUrl } : {}) });
+    };
+    // Start the proxy WHATEVER happened to the daemon.
+    //
+    // This used to exit(1) when `ensure` failed, which is the third way an MCP server disappears on a
+    // user: something else is holding the bridge port — a foreign daemon from another project, a
+    // half-dead process, a port a colleague's tool grabbed — the spawned daemon cannot bind, and the
+    // editor shows a server that failed to start. Nothing about that is unrecoverable: the proxy
+    // answers `initialize` itself, serves the cached catalog, and its wake path retries a daemon on
+    // every client request. Present-and-complaining beats absent, because absent needs a human.
+    // `void`: the chain handles its own failure and the process must not wait on it — the proxy is
+    // started from `finally` either way.
+    void ensure()
+        .catch((err) => {
+        log('reticle_mcp_daemon_unavailable', {
+            error: err instanceof Error ? err.message : String(err),
+            note: 'serving anyway — the next tool call will try to start a daemon again',
+        });
+    })
+        .finally(() => {
+        // Also `void`: the proxy runs for the life of the process and is never awaited by anyone.
+        //
+        // The `.catch` is load-bearing despite that. `startMcpProxy` rejects when its FIRST connect
+        // fails — which is precisely the case this block exists to tolerate, a daemon that is not
+        // there yet — and with nothing attached that reject became an unhandledRejection. Reported
+        // from a win32 user as a crash reading `connect ECONNREFUSED` with an EMPTY frame list,
+        // because the stack of a refused socket is entirely node internals and the privacy filter
+        // keeps only Reticle frames. So the one path we most want diagnosable arrived as an anonymous
+        // crash. The proxy itself is unaffected — it has already installed its stdin reader and goes
+        // on serving from cache, waking a daemon on the next request — which is exactly why this
+        // must be logged as the expected condition it is rather than reported as a defect.
+        void startMcpProxy(port, ensure).catch((err) => {
+            log('reticle_mcp_proxy_first_connect_failed', {
+                port,
+                error: err instanceof Error ? err.message : String(err),
+                note: 'serving from cache; the next client request will try to start a daemon',
+            });
+        });
+    });
+}

package/dist/cli/sibling-ports.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Well-known Reticle ports other than the one this daemon bound.
+ *
+ * The remaining half of #261: when the SDK dials 4460 and we listen on 4400, we cannot see the
+ * refused inbound — but we CAN notice that a well-known Reticle port other than ours has a
+ * listener. That is an observation, not a diagnosis. A neighbour's daemon, another project, or an
+ * unrelated process on 4460 all look identical from here, so the sentence that reports it must not
+ * conclude that it is the daemon this app wants. Maintainer constraint on the issue: report the
+ * observation without the conclusion.
+ */
+/**
+ * The port the bench fixture's SDK dials.
+ *
+ * Deliberate, and must not be "fixed" onto the default: `bench/harness/ports.mjs` documents a past
+ * incident caused by having more than one source of truth for it. It exists so a default daemon on
+ * 4400 and a bench run never collide. Doctor and the no-session diagnosis probe it as a sibling
+ * of 4400 for that reason — it is the port the original silent no-connect was on.
+ */
+export declare const RETICLE_BENCH_PORT = 4460;
+/** Ports a Reticle daemon is known to occupy. Probe every one except the port we ourselves bound. */
+export declare const WELL_KNOWN_RETICLE_PORTS: readonly number[];
+/** Well-known Reticle ports other than `boundPort`. Empty when we are the only well-known occupant. */
+export declare function siblingPorts(boundPort: number, known?: readonly number[]): readonly number[];
+/**
+ * One sentence for a listener on a sibling Reticle port. `undefined` when there is nothing to say.
+ *
+ * Wording is load-bearing: it names the observation and refuses the conclusion. A test pins that it
+ * does not claim the listener is the daemon this app wants, or that the SDK is dialling it.
+ */
+export declare function siblingListenerNote(boundPort: number, occupiedSiblings: readonly number[]): string | undefined;
+/**
+ * Which well-known siblings currently accept a TCP connection.
+ *
+ * Pure in the rule, impure at the edge: `isListening` is injected so this can be tested without a
+ * socket, and so a lying probe is a separate failure from a lying sentence.
+ */
+export declare function findOccupiedSiblings(boundPort: number, isListening: (port: number) => Promise<boolean>): Promise<readonly number[]>;

package/dist/cli/sibling-ports.js

@@ -0,0 +1,56 @@
+/**
+ * Well-known Reticle ports other than the one this daemon bound.
+ *
+ * The remaining half of #261: when the SDK dials 4460 and we listen on 4400, we cannot see the
+ * refused inbound — but we CAN notice that a well-known Reticle port other than ours has a
+ * listener. That is an observation, not a diagnosis. A neighbour's daemon, another project, or an
+ * unrelated process on 4460 all look identical from here, so the sentence that reports it must not
+ * conclude that it is the daemon this app wants. Maintainer constraint on the issue: report the
+ * observation without the conclusion.
+ */
+import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
+/**
+ * The port the bench fixture's SDK dials.
+ *
+ * Deliberate, and must not be "fixed" onto the default: `bench/harness/ports.mjs` documents a past
+ * incident caused by having more than one source of truth for it. It exists so a default daemon on
+ * 4400 and a bench run never collide. Doctor and the no-session diagnosis probe it as a sibling
+ * of 4400 for that reason — it is the port the original silent no-connect was on.
+ */
+export const RETICLE_BENCH_PORT = 4460;
+/** Ports a Reticle daemon is known to occupy. Probe every one except the port we ourselves bound. */
+export const WELL_KNOWN_RETICLE_PORTS = [
+    RETICLE_DEFAULT_PORT,
+    RETICLE_BENCH_PORT,
+];
+/** Well-known Reticle ports other than `boundPort`. Empty when we are the only well-known occupant. */
+export function siblingPorts(boundPort, known = WELL_KNOWN_RETICLE_PORTS) {
+    return known.filter((port) => port !== boundPort);
+}
+/**
+ * One sentence for a listener on a sibling Reticle port. `undefined` when there is nothing to say.
+ *
+ * Wording is load-bearing: it names the observation and refuses the conclusion. A test pins that it
+ * does not claim the listener is the daemon this app wants, or that the SDK is dialling it.
+ */
+export function siblingListenerNote(boundPort, occupiedSiblings) {
+    if (0 === occupiedSiblings.length)
+        return undefined;
+    const listed = occupiedSiblings.map((port) => `:${String(port)}`).join(', ');
+    return (`something is listening on ${listed}, which this daemon is not` +
+        ` (this daemon is on :${String(boundPort)}); that may or may not be related.`);
+}
+/**
+ * Which well-known siblings currently accept a TCP connection.
+ *
+ * Pure in the rule, impure at the edge: `isListening` is injected so this can be tested without a
+ * socket, and so a lying probe is a separate failure from a lying sentence.
+ */
+export async function findOccupiedSiblings(boundPort, isListening) {
+    const occupied = [];
+    for (const port of siblingPorts(boundPort)) {
+        if (await isListening(port))
+            occupied.push(port);
+    }
+    return occupied;
+}

package/dist/cli.js

@@ -6,7 +6,10 @@ import { join } from 'node:path';
 import { stateDirProblem } from './daemon/state-dir.js';
 import { statusNextAction } from './cli/status-next-action.js';
 import { hasConnectedBefore } from './session/connection-memory.js';
+import { attachStatusFields } from './mcp/attach-memory.js';
 import { reticleStateHome } from './daemon/daemon.js';
+import { handleMcp } from './cli/mcp-command.js';
+import { resolveDaemonForProject } from './daemon/daemon-resolve.js';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli/cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
 import { loadDotEnv } from './telemetry/dev-repo.js';
@@ -20,8 +23,8 @@ import { SERVER_VERSION } from './version/server-version.js';
 import { log } from './log.js';
 import { readPid, isAlive, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, logPath, } from './daemon/daemon.js';
 import { PortPresence, probePresence, presenceIsUsable, describePresence, } from './daemon/port-presence.js';
-import { waitForDaemon, startMcpProxy, probeDaemon, proxyLog, setProxyLogPort, } from './mcp/mcp-proxy.js';
-import { installDaemonResilience, installProxyResilience, recordExitReason, DaemonExitReason, } from './daemon/daemon-resilience.js';
+import { waitForDaemon, probeDaemon } from './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/heartbeat.js';
 import { everServedToolCall } from './daemon/daemon-usefulness.js';
@@ -238,6 +241,10 @@ function handleStatus(port) {
     // path does the first without the second — so this is the commonest reason `status` has nothing to
     // report, and it was not among the facts this command could state.
     const initialized = projectId !== undefined;
+    // The OTHER half of the install, and the half this command could not see. A host that registers
+    // Reticle and never lists its tools looks exactly like an abandoned install from here — same idle
+    // daemon, same zero sessions — and the user sees a tool that does nothing. See attach-memory.ts.
+    const client = attachStatusFields(reticleStateHome(), port);
     if (null === pid || !isAlive(pid)) {
         // `running: false` on its own has been reported about a port that was demonstrably occupied,
         // because the pid file is not the port. Ask the port before answering.
@@ -252,6 +259,7 @@ function handleStatus(port) {
                 // `running: false` and nothing else, which reads as "Reticle is broken" for what is usually
                 // just a daemon that has not been asked to do anything yet.
                 ...withNextAction({ running, sessionCount: 0, previouslyConnected, initialized }),
+                ...client,
             });
         });
         return;
@@ -270,6 +278,7 @@ function handleStatus(port) {
                 pid,
                 ...nudge,
                 ...withNextAction({ running: true, sessionCount: 0, previouslyConnected, initialized }),
+                ...client,
             });
             return;
         }
@@ -280,7 +289,7 @@ function handleStatus(port) {
         const next = summary.why === undefined
             ? withNextAction({ running: true, ...summary, previouslyConnected, initialized })
             : {};
-        log('reticle_status', { port, running: true, pid, ...summary, ...next, ...nudge });
+        log('reticle_status', { port, running: true, pid, ...summary, ...next, ...client, ...nudge });
     });
 }
 /** Print the running package version (resolved once in server-version.ts). */
@@ -398,8 +407,17 @@ async function waitForNewSession(port, before) {
     return false;
 }
 function handleOpen(requestedPort, url) {
+    // Our project's daemon first: `discoverDaemonPort` returns the LOWEST live daemon on the machine,
+    // whoever it belongs to, so on a machine running two projects `reticle open` could drive the other
+    // one's browser. It stays as the last resort for a caller with no project id, where any daemon is
+    // better than none and there is no identity to confuse.
+    const myProject = readProjectId(process.cwd());
     probeDaemon(requestedPort)
-        .then((here) => (here ? requestedPort : (discoverDaemonPort() ?? requestedPort)))
+        .then((here) => here
+        ? requestedPort
+        : (resolveDaemonForProject(myProject, reticleStateHome(), isAlive) ??
+            discoverDaemonPort() ??
+            requestedPort))
         .then(async (port) => {
         await ensureDaemon(port);
         const { sessions } = summarizeStatus(await fetchStatus(port));
@@ -585,109 +603,6 @@ function handleDaemonInner(parsed) {
         process.exit(1);
     });
 }
-/**
- * MCP proxy mode: ensures the daemon is running, then bridges Claude Code's
- * stdin/stdout to the daemon's SSE endpoint. This is the recommended way to
- * configure Reticle in.mcp.json — users never need to manage the daemon manually.
- *
- * Pass --drive <url> to have the daemon launch its own Playwright browser at that
- * URL. The agent then has full autonomous control without relying on the user's browser.
- */
-function handleMcp(opts) {
-    const { port, driveUrl, headless, http, httpPort, httpToken } = opts;
-    // The proxy IS the MCP server the editor launched. Nothing respawns it, so an uncaught throw here
-    // is what a user experiences as "the MCP server disconnected — open /mcp and reconnect". Log it,
-    // report it, keep serving: the reconnect and dormant paths already know how to rebuild the only
-    // state this process has. See installProxyResilience for why its rule inverts the daemon's.
-    // The proxy's crash handlers must write to the proxy's LOG FILE, not just stderr. The editor
-    // swallows stderr, so wiring these to `log` meant a crash was handled and then unrecorded — the
-    // failure a user reports as "it disconnected" left nothing behind to read.
-    setProxyLogPort(port);
-    installProxyResilience(process, proxyLog);
-    /**
-     * Make sure a daemon is on the port, spawning one if not.
-     *
-     * Called on first start AND on every reconnect. The proxy used to only retry the socket, so a
-     * daemon that exited — crashed, `reticle stop`, or self-shut-down as idle — meant the retries hit
-     * a dead port until the budget ran out and the agent's MCP server exited with it. Reticle simply
-     * disappeared mid-session with nothing said. Respawning here makes the reconnect self-healing.
-     */
-    const ensure = async () => {
-        // The same question every other surface asks. It used to be a bare TCP connect, so a stranger on
-        // the bridge port answered "a daemon is here" — the proxy connected, the stream ended, and each
-        // client request woke into the identical non-answer. Rejecting here is what puts the proxy
-        // dormant with a reason, instead of pretending the wake succeeded.
-        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
-        if (presenceIsUsable(presence))
-            return;
-        if (PortPresence.FREE !== presence)
-            throw new Error(describePresence(presence, port));
-        const scriptPath = process.argv[1];
-        if (scriptPath === undefined) {
-            log('reticle_mcp_no_script', {});
-            process.exit(1);
-        }
-        const daemonArgs = [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)];
-        if (driveUrl !== undefined) {
-            daemonArgs.push(DRIVE_FLAG, driveUrl);
-            if (!headless)
-                daemonArgs.push(HEADED_FLAG);
-        }
-        // Forward the HTTP-verify flags too (previously silently dropped for `reticle mcp`).
-        if (http) {
-            daemonArgs.push(HTTP_FLAG);
-            if (httpPort !== undefined)
-                daemonArgs.push(HTTP_PORT_FLAG, String(httpPort));
-            if (httpToken !== undefined)
-                daemonArgs.push(HTTP_TOKEN_FLAG, httpToken);
-        }
-        spawnDaemon(process.execPath, scriptPath, daemonArgs, port);
-        // Announce the daemon only once the PORT ACCEPTS. This line used to be written the instant the
-        // child was spawned, which on a Windows first bootstrap meant `reticle_mcp_daemon_started`
-        // followed about ten seconds later by `reticle_mcp_daemon_unavailable` and a first
-        // `reticle_sessions` that expired. A readiness signal that precedes readiness is worse than
-        // none: a client that believes it stops waiting for the thing that has not happened.
-        await waitForDaemon(port);
-        log('reticle_mcp_daemon_started', { port, ...(driveUrl !== undefined ? { driveUrl } : {}) });
-    };
-    // Start the proxy WHATEVER happened to the daemon.
-    //
-    // This used to exit(1) when `ensure` failed, which is the third way an MCP server disappears on a
-    // user: something else is holding the bridge port — a foreign daemon from another project, a
-    // half-dead process, a port a colleague's tool grabbed — the spawned daemon cannot bind, and the
-    // editor shows a server that failed to start. Nothing about that is unrecoverable: the proxy
-    // answers `initialize` itself, serves the cached catalog, and its wake path retries a daemon on
-    // every client request. Present-and-complaining beats absent, because absent needs a human.
-    // `void`: the chain handles its own failure and the process must not wait on it — the proxy is
-    // started from `finally` either way.
-    void ensure()
-        .catch((err) => {
-        log('reticle_mcp_daemon_unavailable', {
-            error: err instanceof Error ? err.message : String(err),
-            note: 'serving anyway — the next tool call will try to start a daemon again',
-        });
-    })
-        .finally(() => {
-        // Also `void`: the proxy runs for the life of the process and is never awaited by anyone.
-        //
-        // The `.catch` is load-bearing despite that. `startMcpProxy` rejects when its FIRST connect
-        // fails — which is precisely the case this block exists to tolerate, a daemon that is not
-        // there yet — and with nothing attached that reject became an unhandledRejection. Reported
-        // from a win32 user as a crash reading `connect ECONNREFUSED` with an EMPTY frame list,
-        // because the stack of a refused socket is entirely node internals and the privacy filter
-        // keeps only Reticle frames. So the one path we most want diagnosable arrived as an anonymous
-        // crash. The proxy itself is unaffected — it has already installed its stdin reader and goes
-        // on serving from cache, waking a daemon on the next request — which is exactly why this
-        // must be logged as the expected condition it is rather than reported as a defect.
-        void startMcpProxy(port, ensure).catch((err) => {
-            log('reticle_mcp_proxy_first_connect_failed', {
-                port,
-                error: err instanceof Error ? err.message : String(err),
-                note: 'serving from cache; the next client request will try to start a daemon',
-            });
-        });
-    });
-}
 function main() {
     // Before anything reads process.env — notably the telemetry gate and the bridge's security
     // options — fold in a project-local `.env`. Values already in the environment always win.
@@ -718,7 +633,19 @@ function main() {
     if (projectPort !== undefined && isLikelyDevServerPort(projectPort)) {
         process.stderr.write(`${devServerPortWarning(projectPort)}\n`);
     }
-    const defaultPort = envPort ?? projectPort ?? RETICLE_DEFAULT_PORT;
+    // Registry BEFORE the default, and after both explicit sources.
+    //
+    // This is the line that ends the split brain. Build plugins have always asked the registry which
+    // daemon serves this project; the CLI asked a number and then attached to whoever owned it. So
+    // every project on the machine funnelled into one daemon whose identity was whichever project won
+    // the race, and one kill on one well-known port was a machine-wide outage.
+    //
+    // An explicit port still wins, because a person who typed one is answering this question
+    // themselves. Below that, our OWN daemon wherever it is listening. Only then the default, which is
+    // now a starting preference rather than an assumption.
+    const myProjectId = readProjectId(process.cwd());
+    const myDaemonPort = resolveDaemonForProject(myProjectId, reticleStateHome(), isAlive);
+    const defaultPort = envPort ?? projectPort ?? myDaemonPort ?? RETICLE_DEFAULT_PORT;
     // Headed by default; hidden only where there is no display to be headed on. A run nobody can see
     // is a run nobody trusts, and every "did it actually do anything?" cost a human round-trip.
     const parsed = parseCliArgs(argv, defaultPort, process.env['CI'] !== undefined);
@@ -792,7 +719,7 @@ function main() {
             void handleHunt(parsed.dir);
             break;
         case 'gate':
-            void handleGate(parsed.files, parsed.since);
+            void handleGate(parsed.files, parsed.since, parsed.hook);
             break;
         case 'watch':
             handleWatch();
@@ -804,7 +731,7 @@ function main() {
             void handleRollback();
             break;
         case 'mcp':
-            handleMcp(parsed);
+            void handleMcp(parsed);
             break;
         case '_daemon':
             handleDaemonInner(parsed);

package/dist/cloud/cloud-config.d.ts

@@ -5,7 +5,7 @@ export declare const CLOUD_LINK_FILE = "cloud.json";
 /** `~/.reticle/credentials.json` — the user's per-cloud-project API keys (the only secret). */
 export declare const CREDENTIALS_FILE = "credentials.json";
 /** What the daemon mirrors to the cloud for a project. Each surface is independently toggleable. */
-export interface SyncPolicy {
+interface SyncPolicy {
     /** Push verification-run artifacts to the dashboard Runs tab. */
     runs: boolean;
     /** Push per-flow project-memory outcomes (the regression history). */
@@ -33,3 +33,4 @@ export interface ProjectCloud {
  * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
  */
 export declare function resolveProjectCloud(fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv): Promise<ProjectCloud>;
+export {};

package/dist/cloud/cloud-sync.d.ts

@@ -21,6 +21,17 @@ export interface CloudConfig {
 }
 /** Resolve cloud credentials from the environment, or null when not logged in (sync disabled). */
 export declare function resolveCloudConfig(env: NodeJS.ProcessEnv): CloudConfig | null;
+export declare const CLOUD_VERIFY_TIMEOUT_MS = 120000;
+/**
+ * The fetch every cloud call goes through. Adds the abort signal, and turns the abort into a message
+ * that says what happened and what to do — a bare `AbortError` reaching a user or an agent is a riddle,
+ * and the agent-facing half of this product is judged on whether its errors are actionable.
+ */
+export declare function cloudFetch(url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}, timeoutMs?: number): Promise<Response>;
 export declare const SyncOutcome: {
     readonly SYNCED: "synced";
     readonly SKIPPED: "skipped";