@reticlehq/server 2.10.0 → 2.12.0

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";

package/dist/cloud/cloud-sync.js

@@ -30,6 +30,38 @@ export function resolveCloudConfig(env) {
         return null;
     return { url: url.replace(/\/+$/, ''), apiKey };
 }
+/**
+ * Budget for a cloud call. Node's `fetch` has NO default timeout, so a connection that opens and then
+ * stalls never settles — and the caller `await`s it forever. In `reticle_flow_verify` that is an MCP
+ * tool call that never returns, and in `reticle cloud …` a terminal that prints nothing.
+ *
+ * One shared budget covers every call here: they are all small JSON request/response pairs against the
+ * same API, so there is nothing to tune per site. The ONE exception is the hosted verification submit,
+ * which blocks while a real browser runs the suite server-side — a normal response there is minutes,
+ * not seconds, so it gets its own (still bounded) budget rather than dragging the common one up.
+ */
+const CLOUD_FETCH_TIMEOUT_MS = 30_000;
+export const CLOUD_VERIFY_TIMEOUT_MS = 120_000;
+/** Names Node gives an abort: `AbortSignal.timeout` raises TimeoutError, an explicit abort AbortError. */
+const TIMEOUT_ERROR_NAMES = new Set(['TimeoutError', 'AbortError']);
+/**
+ * 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 async function cloudFetch(url, init, timeoutMs = CLOUD_FETCH_TIMEOUT_MS) {
+    try {
+        return await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (err) {
+        if (err instanceof Error && TIMEOUT_ERROR_NAMES.has(err.name)) {
+            throw new Error(`Reticle Cloud request timed out after ${Math.round(timeoutMs / 1000)}s: ${init.method} ${url}. ` +
+                `The server accepted the connection but never answered. Check the network and ${CloudEnv.URL}, then retry — ` +
+                `verification works locally without cloud.`);
+        }
+        throw err;
+    }
+}
 export const SyncOutcome = {
     SYNCED: 'synced',
     SKIPPED: 'skipped',

package/dist/crawl/crawl.d.ts

@@ -4,6 +4,15 @@ export interface CrawlSession {
     command(name: string, args?: Record<string, unknown>): Promise<CommandResult>;
     elapsed(): number;
     eventsSince(cursor: number): ReticleEvent[];
+    /**
+     * Which document is on screen now, so a finding is never drawn from a page the crawl has already
+     * navigated away from. Optional for the same reason `beginAction` is: a test fake supplies a
+     * minimal session, and its absence leaves the scoping inert rather than broken.
+     */
+    readonly currentDocumentId?: string | undefined;
+    /** Which round of source edits is in force, so a finding drawn entirely from pre-edit evidence
+     *  says so. Optional for the same reason `currentDocumentId` is. */
+    readonly currentEditEpoch?: number | undefined;
     /**
      * Attribution window around each click. Optional so a caller can supply a minimal session, but a real
      * session MUST provide it: without a window the click's own effects carry no actionId, and an
@@ -44,19 +53,6 @@ export interface CrawlAnomaly {
 }
 /** Said out loud when the page was larger than one snapshot, so a clean sweep cannot mean "all clear". */
 export declare const CAPPED_SNAPSHOT_NOTE = "the page exceeded one snapshot, so controls past the cap were never seen \u2014 interactiveFound is a floor, not a total; re-run with a narrower `scope` to cover the rest";
-/**
- * Said out loud when the crawl's OWN clicks put controls on the page that it then never visited.
- *
- * The enumeration happens once, before the first click, so a control that only exists after a login,
- * a modal or a tab switch is invisible to this run. Measured on the bench app: a crawl of the login
- * screen visited three controls, its click on "Sign in" produced seven more, and it returned
- * `truncated: false` with an empty anomaly list and nine of twelve steps unused. Read as a sweep,
- * that is a clean bill of health for an app the crawl never entered.
- *
- * The same words as the capped-snapshot case on purpose — it is the same idea (interactiveFound is a
- * floor) reached by a different route, and a second vocabulary for it would just be more to learn.
- */
-export declare function revealedControlsNote(count: number): string;
 export interface CrawlReport {
     interactiveFound: number;
     stepsRun: number;

package/dist/crawl/crawl.js

@@ -18,7 +18,7 @@ export const CAPPED_SNAPSHOT_NOTE = 'the page exceeded one snapshot, so controls
  * The same words as the capped-snapshot case on purpose — it is the same idea (interactiveFound is a
  * floor) reached by a different route, and a second vocabulary for it would just be more to learn.
  */
-export function revealedControlsNote(count) {
+function revealedControlsNote(count) {
     return (`the page changed as you clicked: ${String(count)} control(s) that did not exist when this crawl ` +
         'started were never visited — interactiveFound is a floor, not a total; re-run the crawl from ' +
         'the state you are now in to cover them');
@@ -65,7 +65,19 @@ export function legitimatelyInert(desc) {
         return true;
     if (desc.includes('[checked]'))
         return true;
-    return /\b(textbox|searchbox|combobox|spinbutton)\b/.test(desc);
+    // Inputs, and the ARIA LIVE-REGION roles.
+    //
+    // `alert`, `status`, `log`, `timer` and `marquee` exist to be READ — a screen reader announces
+    // them and nothing is meant to happen when one is clicked. Clicking twice and seeing nothing is
+    // therefore correct behaviour, and reporting it as `dead-control` accuses a working app.
+    //
+    // Found by driving a real app: the demo reported `dead-control — alert "Invalid email or
+    // password"`, which is a login form correctly telling somebody their password was wrong. That is
+    // the most expensive kind of false positive there is — the strongest claim the crawler makes,
+    // about an app that was working, and on the path a new user meets first.
+    //
+    // `alertdialog` is deliberately NOT here: it is interactive, and a word boundary keeps it out.
+    return /\b(textbox|searchbox|combobox|spinbutton|alert|status|log|timer|marquee)\b/.test(desc);
 }
 /**
  * How many interactive controls exist now that did not exist when the crawl enumerated.
@@ -199,7 +211,12 @@ export async function crawl(session, opts, sleep) {
         }
         // CONTRADICTIONS: the channels disagree about what this click did. Reported per control, so a
         // crawl of an unknown app surfaces its false greens without anyone knowing where to look.
-        for (const c of findContradictions(events)) {
+        // A crawl clicks controls that navigate, so its windows are the ones most likely to straddle a
+        // document boundary — and a finding here is reported against a specific control by name.
+        for (const c of findContradictions(events, {
+            currentDocumentId: session.currentDocumentId,
+            currentEditEpoch: session.currentEditEpoch,
+        })) {
             counts.contradictions += 1;
             anomalies.push({
                 kind: c.kind,

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

@@ -0,0 +1,79 @@
+/**
+ * Which daemon does THIS project belong to?
+ *
+ * The system answered that two incompatible ways. Build plugins asked the registry by projectId, the
+ * way `pickDaemonPort` was designed to be asked. The CLI and the MCP proxy asked a NUMBER —
+ * `envPort ?? projectPort ?? 4400` — and then attached to whatever owned it, whoever it belonged to.
+ *
+ * So every project on a machine funnelled into one daemon. Its recorded identity was whichever
+ * project won the race to the port, which made the registry entry wrong the moment a second project
+ * attached, and made one `kill` on one well-known port a machine-wide outage for every agent at once.
+ *
+ * It worked anyway, by luck: everyone defaulted to the same number, so everyone found each other.
+ * The luck ends the moment a daemon is anywhere but the default — which is exactly when discovery was
+ * supposed to help, and exactly when it returned nothing.
+ *
+ * This module is the one answer both sides now use. It is pure and injectable: no process spawning,
+ * no port binding, nothing that needs a real `~/.reticle` to test.
+ */
+import { type DaemonRegistryEntry } from '@reticlehq/core';
+/**
+ * Every well-formed registry entry in `home`.
+ *
+ * A corrupt or half-written entry is skipped rather than thrown on: the registry is written by other
+ * processes that can be killed mid-write, and one bad file must not make a machine's daemons
+ * undiscoverable. Validated through core's schema so a shape change cannot silently pass here.
+ */
+export declare function readDaemonRegistry(home: string): DaemonRegistryEntry[];
+/**
+ * The port of the live daemon serving `projectId`, or undefined when this project has none.
+ *
+ * Undefined means "start one", never "use the default and hope". That distinction is the fix: the old
+ * path had no way to express "no daemon of mine exists", so it fell through to a number and attached
+ * to a stranger.
+ *
+ * The selection rule is core's `pickDaemonPort`, shared with every build plugin, so the daemon side
+ * and the app side cannot disagree about which daemon is ours.
+ */
+export declare function resolveDaemonForProject(projectId: string | undefined, home: string, alive: (pid: number) => boolean): number | undefined;
+/**
+ * May `caller` take over a daemon already sitting on the port it wanted?
+ *
+ * Two deliberate escape hatches, both of which keep an existing install working:
+ *
+ * A daemon that claims NO project was started somewhere without a `.reticle.json` — the global MCP
+ * registration in a directory that is not an app, which is the majority of daemons in the field. It
+ * belongs to nobody, so it belongs to whoever asks; refusing would break every user running Reticle
+ * globally, which is how it is documented to be installed.
+ *
+ * A caller with no project of its own has no identity to defend and nothing to be confused about, so
+ * it keeps the old permissive behaviour rather than being locked out of a daemon it can use.
+ *
+ * Everything else — a named daemon and a differently-named caller — is the cross-project bleed, and
+ * is the one case this refuses.
+ */
+export declare function adoptable(daemonProjectId: string | undefined, callerProjectId: string | undefined): boolean;
+/** The project a daemon on `port` claims, or undefined when it claims none / is not registered. */
+export declare function daemonProjectAt(port: number, home: string): string | undefined;
+/**
+ * The port this agent's MCP proxy should serve, decided BEFORE the proxy starts.
+ *
+ * Resolved once rather than per reconnect because the proxy's transport is built around a fixed
+ * number, and making it chase a moving port would mean reworking the reconnect path — the one piece
+ * of this system whose failure mode is "the MCP server disappeared mid-session". The port it settles
+ * on is this project's own, so the thing it would be chasing is a daemon it alone is responsible for.
+ *
+ * The order is the whole fix:
+ *   1. our project's live daemon, wherever it is listening — a daemon that moved is still ours;
+ *   2. the preferred port, but only if free or holding a daemon we may adopt;
+ *   3. a port the OS gives us, when the preferred one belongs to somebody else.
+ *
+ * Step 3 is what stops a second project from attaching to the first project's daemon. That single
+ * silent adoption is what made every agent on a machine share one process, one identity and one
+ * blast radius.
+ */
+export declare function resolveMcpPort(preferred: number, projectId: string | undefined, home: string, deps: {
+    alive: (pid: number) => boolean;
+    daemonPresent: (port: number) => Promise<boolean>;
+    pickPort: (preferred: number) => Promise<number>;
+}): Promise<number>;

package/dist/daemon/daemon-resolve.js

@@ -0,0 +1,118 @@
+/**
+ * Which daemon does THIS project belong to?
+ *
+ * The system answered that two incompatible ways. Build plugins asked the registry by projectId, the
+ * way `pickDaemonPort` was designed to be asked. The CLI and the MCP proxy asked a NUMBER —
+ * `envPort ?? projectPort ?? 4400` — and then attached to whatever owned it, whoever it belonged to.
+ *
+ * So every project on a machine funnelled into one daemon. Its recorded identity was whichever
+ * project won the race to the port, which made the registry entry wrong the moment a second project
+ * attached, and made one `kill` on one well-known port a machine-wide outage for every agent at once.
+ *
+ * It worked anyway, by luck: everyone defaulted to the same number, so everyone found each other.
+ * The luck ends the moment a daemon is anywhere but the default — which is exactly when discovery was
+ * supposed to help, and exactly when it returned nothing.
+ *
+ * This module is the one answer both sides now use. It is pure and injectable: no process spawning,
+ * no port binding, nothing that needs a real `~/.reticle` to test.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DaemonRegistryEntrySchema, daemonRegistryPort, pickDaemonPort, } from '@reticlehq/core';
+/**
+ * Every well-formed registry entry in `home`.
+ *
+ * A corrupt or half-written entry is skipped rather than thrown on: the registry is written by other
+ * processes that can be killed mid-write, and one bad file must not make a machine's daemons
+ * undiscoverable. Validated through core's schema so a shape change cannot silently pass here.
+ */
+export function readDaemonRegistry(home) {
+    let files;
+    try {
+        files = readdirSync(home);
+    }
+    catch {
+        return []; // no ~/.reticle yet: no daemon has ever run here
+    }
+    const entries = [];
+    for (const file of files) {
+        if (null === daemonRegistryPort(file))
+            continue;
+        try {
+            const parsed = DaemonRegistryEntrySchema.safeParse(JSON.parse(readFileSync(join(home, file), 'utf8')));
+            if (parsed.success)
+                entries.push(parsed.data);
+        }
+        catch {
+            continue;
+        }
+    }
+    return entries;
+}
+/**
+ * The port of the live daemon serving `projectId`, or undefined when this project has none.
+ *
+ * Undefined means "start one", never "use the default and hope". That distinction is the fix: the old
+ * path had no way to express "no daemon of mine exists", so it fell through to a number and attached
+ * to a stranger.
+ *
+ * The selection rule is core's `pickDaemonPort`, shared with every build plugin, so the daemon side
+ * and the app side cannot disagree about which daemon is ours.
+ */
+export function resolveDaemonForProject(projectId, home, alive) {
+    return pickDaemonPort(readDaemonRegistry(home), projectId, alive) ?? undefined;
+}
+/**
+ * May `caller` take over a daemon already sitting on the port it wanted?
+ *
+ * Two deliberate escape hatches, both of which keep an existing install working:
+ *
+ * A daemon that claims NO project was started somewhere without a `.reticle.json` — the global MCP
+ * registration in a directory that is not an app, which is the majority of daemons in the field. It
+ * belongs to nobody, so it belongs to whoever asks; refusing would break every user running Reticle
+ * globally, which is how it is documented to be installed.
+ *
+ * A caller with no project of its own has no identity to defend and nothing to be confused about, so
+ * it keeps the old permissive behaviour rather than being locked out of a daemon it can use.
+ *
+ * Everything else — a named daemon and a differently-named caller — is the cross-project bleed, and
+ * is the one case this refuses.
+ */
+export function adoptable(daemonProjectId, callerProjectId) {
+    if (daemonProjectId === undefined || 0 === daemonProjectId.length)
+        return true;
+    if (callerProjectId === undefined || 0 === callerProjectId.length)
+        return true;
+    return daemonProjectId === callerProjectId;
+}
+/** The project a daemon on `port` claims, or undefined when it claims none / is not registered. */
+export function daemonProjectAt(port, home) {
+    return readDaemonRegistry(home).find((e) => e.port === port)?.projectId;
+}
+/**
+ * The port this agent's MCP proxy should serve, decided BEFORE the proxy starts.
+ *
+ * Resolved once rather than per reconnect because the proxy's transport is built around a fixed
+ * number, and making it chase a moving port would mean reworking the reconnect path — the one piece
+ * of this system whose failure mode is "the MCP server disappeared mid-session". The port it settles
+ * on is this project's own, so the thing it would be chasing is a daemon it alone is responsible for.
+ *
+ * The order is the whole fix:
+ *   1. our project's live daemon, wherever it is listening — a daemon that moved is still ours;
+ *   2. the preferred port, but only if free or holding a daemon we may adopt;
+ *   3. a port the OS gives us, when the preferred one belongs to somebody else.
+ *
+ * Step 3 is what stops a second project from attaching to the first project's daemon. That single
+ * silent adoption is what made every agent on a machine share one process, one identity and one
+ * blast radius.
+ */
+export async function resolveMcpPort(preferred, projectId, home, deps) {
+    const mine = resolveDaemonForProject(projectId, home, deps.alive);
+    if (mine !== undefined)
+        return mine;
+    if (!(await deps.daemonPresent(preferred)))
+        return preferred;
+    return adoptable(daemonProjectAt(preferred, home), projectId)
+        ? preferred
+        : deps.pickPort(preferred);
+}

package/dist/daemon/free-port.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A port this machine will actually let us bind.
+ *
+ * Once daemons are per-project, "which port" stops being a constant and becomes a question. The
+ * answer must not be "the next number up": probing 4401, 4402, 4403 races every other agent doing
+ * the same arithmetic at the same moment, and the loser finds out at bind time, which is after it has
+ * already told the caller which port to use.
+ *
+ * So the OS assigns it. Binding port 0 asks the kernel for a free one and hands back the number it
+ * chose, and nothing else can be holding it at that instant. There is still a window between closing
+ * the probe socket and the daemon binding for real — unavoidable without passing the listener itself
+ * to the child — but it is microseconds wide and loses to a retry, where a guessed number loses every
+ * time on a busy machine.
+ *
+ * The preferred port is tried first so the ordinary single-project install keeps landing on the
+ * documented default, and every doc, log line and troubleshooting page that says 4400 stays true.
+ */
+/** Can we bind `port` on the loopback interface right now? */
+export declare function portIsFree(port: number, host?: string): Promise<boolean>;
+/** Ask the kernel for a free port. Rejects only if the machine cannot bind loopback at all. */
+export declare function osAssignedPort(host?: string): Promise<number>;
+/**
+ * `preferred` when it is free, otherwise whatever the OS gives us.
+ *
+ * Injectable so the decision is unit-testable without binding anything: the interesting case is the
+ * one where the preferred port is taken, and a test must be able to say so without racing a real
+ * socket.
+ */
+export declare function pickDaemonPortToBind(preferred: number, isFree?: (port: number) => Promise<boolean>, assign?: () => Promise<number>): Promise<number>;