@reticlehq/server 2.11.0 → 2.13.0

package/dist/cli/daemon-start-options.js

@@ -0,0 +1,38 @@
+import { DAEMON_INNER_COMMAND, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, PORT_FLAG, } from './cli-parse.js';
+export function daemonStartOptions(parsed) {
+    return {
+        port: parsed.port,
+        headless: parsed.headless,
+        ...(parsed.driveUrl !== undefined ? { driveUrl: parsed.driveUrl } : {}),
+        ...(parsed.http
+            ? {
+                httpVerify: true,
+                ...(parsed.httpPort !== undefined ? { httpVerifyPort: parsed.httpPort } : {}),
+                ...(parsed.httpToken !== undefined ? { httpVerifyToken: parsed.httpToken } : {}),
+            }
+            : {}),
+    };
+}
+/**
+ * The argv a parent hands its detached `_daemon` child.
+ *
+ * `serve` and `mcp` each built this list by hand and each made the SAME mistake as the options
+ * builder above — pushing `--headed` only inside the `driveUrl` branch — so the flag survived
+ * parsing, was dropped at the spawn, and the child launched a hidden pool. Three sites, one wrong
+ * idea: that headless belongs to the drive URL. It belongs to the pool, which exists either way.
+ */
+export function daemonSpawnArgs(parsed) {
+    const args = [DAEMON_INNER_COMMAND, PORT_FLAG, String(parsed.port)];
+    if (parsed.driveUrl !== undefined)
+        args.push(DRIVE_FLAG, parsed.driveUrl);
+    if (!parsed.headless)
+        args.push(HEADED_FLAG);
+    if (parsed.http) {
+        args.push(HTTP_FLAG);
+        if (parsed.httpPort !== undefined)
+            args.push(HTTP_PORT_FLAG, String(parsed.httpPort));
+        if (parsed.httpToken !== undefined)
+            args.push(HTTP_TOKEN_FLAG, parsed.httpToken);
+    }
+    return args;
+}

package/dist/cli/device-flow.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The browser device flow's wire shapes and its hand-off to a real browser.
+ *
+ * `reticle login` works like `gh auth login`: the CLI asks the cloud for a device code, opens the
+ * approval page, and polls until a human confirms it in a session that is already signed in. That
+ * confirmation is the whole security of the flow — only somebody already authenticated in the
+ * dashboard can turn a device code into a token for their org.
+ *
+ * Split from `cloud-cli` because it is self-contained: the schemas describe two endpoints and the
+ * opener knows only about platforms. Nothing here reads a session, a credential, or a project.
+ */
+import { z } from 'zod';
+/** What `/v1/auth/device/start` answers: the codes, where to approve, and how fast to poll. */
+export declare const DeviceStartSchema: z.ZodObject<{
+    deviceCode: z.ZodString;
+    userCode: z.ZodString;
+    verificationUri: z.ZodString;
+    verificationUriComplete: z.ZodString;
+    interval: z.ZodNumber;
+    expiresAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    interval: number;
+    expiresAt: number;
+}, {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    interval: number;
+    expiresAt: number;
+}>;
+/**
+ * What `/v1/auth/device/token` answers while polling. Everything past `status` is optional because
+ * only an APPROVED poll carries a token, and `org.id` is absent on a cloud older than org-scoped
+ * credentials.
+ */
+export declare const DevicePollSchema: z.ZodObject<{
+    status: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+    org: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        id?: string | undefined;
+    }, {
+        name: string;
+        id?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    status: string;
+    org?: {
+        name: string;
+        id?: string | undefined;
+    } | undefined;
+    token?: string | undefined;
+}, {
+    status: string;
+    org?: {
+        name: string;
+        id?: string | undefined;
+    } | undefined;
+    token?: string | undefined;
+}>;
+/**
+ * Best-effort open the approval page in the default browser.
+ *
+ * Every failure is swallowed on purpose: the URL is printed either way, and a headless box, a
+ * container, or an SSH session has no opener at all. Refusing to log in because a convenience did
+ * not work would break the one environment that most needs the printed fallback.
+ */
+export declare const openBrowser: (target: string) => void;

package/dist/cli/device-flow.js

@@ -0,0 +1,56 @@
+/**
+ * The browser device flow's wire shapes and its hand-off to a real browser.
+ *
+ * `reticle login` works like `gh auth login`: the CLI asks the cloud for a device code, opens the
+ * approval page, and polls until a human confirms it in a session that is already signed in. That
+ * confirmation is the whole security of the flow — only somebody already authenticated in the
+ * dashboard can turn a device code into a token for their org.
+ *
+ * Split from `cloud-cli` because it is self-contained: the schemas describe two endpoints and the
+ * opener knows only about platforms. Nothing here reads a session, a credential, or a project.
+ */
+import { z } from 'zod';
+import { spawn } from 'node:child_process';
+import { NodePlatform } from '../platform.js';
+/** What `/v1/auth/device/start` answers: the codes, where to approve, and how fast to poll. */
+export const DeviceStartSchema = z.object({
+    deviceCode: z.string(),
+    userCode: z.string(),
+    verificationUri: z.string(),
+    verificationUriComplete: z.string(),
+    interval: z.number(),
+    expiresAt: z.number(),
+});
+/**
+ * What `/v1/auth/device/token` answers while polling. Everything past `status` is optional because
+ * only an APPROVED poll carries a token, and `org.id` is absent on a cloud older than org-scoped
+ * credentials.
+ */
+export const DevicePollSchema = z.object({
+    status: z.string(),
+    token: z.string().optional(),
+    org: z.object({ id: z.string().optional(), name: z.string() }).optional(),
+});
+/**
+ * Best-effort open the approval page in the default browser.
+ *
+ * Every failure is swallowed on purpose: the URL is printed either way, and a headless box, a
+ * container, or an SSH session has no opener at all. Refusing to log in because a convenience did
+ * not work would break the one environment that most needs the printed fallback.
+ */
+export const openBrowser = (target) => {
+    const cmd = NodePlatform.MACOS === process.platform
+        ? 'open'
+        : NodePlatform.WINDOWS === process.platform
+            ? 'cmd'
+            : 'xdg-open';
+    const args = NodePlatform.WINDOWS === process.platform ? ['/c', 'start', '', target] : [target];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        /* no opener available — the user opens the printed URL manually */
+    }
+};

package/dist/cli/doctor-rows.d.ts

@@ -18,7 +18,8 @@
  * row added and never documented.
  *
  * NOT every row prints on every run. `version` prints only on skew, `port check` only on a
- * mismatch, `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
+ * mismatch, `sibling` only when a well-known Reticle port other than ours has a listener,
+ * `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
  * vocabulary is therefore "what this command can print", not "what one run printed" — a guard built
  * by scraping a single invocation would silently stop covering the conditional rows, which are
  * exactly the ones a reader is least likely to have seen before.
@@ -30,8 +31,18 @@ export declare const DoctorRow: {
     readonly DAEMON: "daemon";
     readonly VERSION: "version";
     readonly SESSIONS: "sessions";
+    /**
+     * The agent-to-daemon hop, which every other row here is blind to.
+     *
+     * Reported from the field: a user with the SDK injected, the overlay visible, a live session on
+     * the daemon and every tool listed in their client was still told by three separate agents that
+     * Reticle was not present. Their words: "four green checkmarks that don't add up to a working
+     * verification." Every row in this list checks a COMPONENT; none checked a LINK.
+     */
+    readonly AGENT_LINK: "agent link";
     readonly BRIDGE_PORT: "bridge port";
     readonly PORT_CHECK: "port check";
+    readonly SIBLING: "sibling";
     readonly DAEMON_LOG: "daemon log";
     readonly TRACING: "tracing";
     readonly DESKTOP: "desktop";

package/dist/cli/doctor-rows.js

@@ -18,7 +18,8 @@
  * row added and never documented.
  *
  * NOT every row prints on every run. `version` prints only on skew, `port check` only on a
- * mismatch, `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
+ * mismatch, `sibling` only when a well-known Reticle port other than ours has a listener,
+ * `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
  * vocabulary is therefore "what this command can print", not "what one run printed" — a guard built
  * by scraping a single invocation would silently stop covering the conditional rows, which are
  * exactly the ones a reader is least likely to have seen before.
@@ -30,8 +31,18 @@ export const DoctorRow = {
     DAEMON: 'daemon',
     VERSION: 'version',
     SESSIONS: 'sessions',
+    /**
+     * The agent-to-daemon hop, which every other row here is blind to.
+     *
+     * Reported from the field: a user with the SDK injected, the overlay visible, a live session on
+     * the daemon and every tool listed in their client was still told by three separate agents that
+     * Reticle was not present. Their words: "four green checkmarks that don't add up to a working
+     * verification." Every row in this list checks a COMPONENT; none checked a LINK.
+     */
+    AGENT_LINK: 'agent link',
     BRIDGE_PORT: 'bridge port',
     PORT_CHECK: 'port check',
+    SIBLING: 'sibling',
     DAEMON_LOG: 'daemon log',
     TRACING: 'tracing',
     DESKTOP: 'desktop',

package/dist/cli/drive-attach.d.ts

@@ -78,6 +78,19 @@ export declare function readAttachResponse(port: number, url: string, res: {
 export declare function requestDriveSession(port: number, url: string, post?: DrivePost): Promise<DriveAttachResult>;
 /** The success line. Names the session, because that is the handle everything downstream needs. */
 export declare function describeAttached(port: number, url: string, session: DriveSession): string;
+/**
+ * What an attach cannot honour: the window.
+ *
+ * `drive` documents a HEADED browser and parses `--headless` as the opt-out, but the attach path
+ * POSTs a url and nothing else — the daemon answers from a pool it launched headless at boot, and no
+ * per-request flag can change a browser that is already running. So the run is invisible, which is
+ * the half of the field report that reads "the app starts to run headlessly".
+ *
+ * Saying so is the honest half. The other half is that the run is no longer unwatchable: the HUD
+ * feed is mirrored to every other tab of the same app (see Session.setViewers), so a tab the human
+ * already has open shows the narration and the counters as the leased context is driven.
+ */
+export declare function driveHeadlessOnAttach(port: number, url: string): string;
 /**
  * A stranger holds the port, in words `drive` can honour.
  *

package/dist/cli/drive-attach.js

@@ -147,6 +147,24 @@ export function describeAttached(port, url, session) {
     return (`attached to the Reticle daemon on :${String(port)} — it is driving ${url} as session ` +
         `${session.sessionId}, which every Reticle tool can address.${life}`);
 }
+/**
+ * What an attach cannot honour: the window.
+ *
+ * `drive` documents a HEADED browser and parses `--headless` as the opt-out, but the attach path
+ * POSTs a url and nothing else — the daemon answers from a pool it launched headless at boot, and no
+ * per-request flag can change a browser that is already running. So the run is invisible, which is
+ * the half of the field report that reads "the app starts to run headlessly".
+ *
+ * Saying so is the honest half. The other half is that the run is no longer unwatchable: the HUD
+ * feed is mirrored to every other tab of the same app (see Session.setViewers), so a tab the human
+ * already has open shows the narration and the counters as the leased context is driven.
+ */
+export function driveHeadlessOnAttach(port, url) {
+    return (`note: this session runs inside the daemon on :${String(port)}, whose browser was launched ` +
+        'headless — there is no window to show, and `--headless` is not a per-drive choice. Open ' +
+        `${url} in your own browser to watch: any tab of that app mirrors this session's HUD. To get a ` +
+        'window instead, stop the daemon and run `reticle drive` again with the port free.');
+}
 /**
  * A stranger holds the port, in words `drive` can honour.
  *

package/dist/cli/drive-command.js

@@ -13,7 +13,7 @@ import { probeDaemon } from '../mcp/mcp-proxy.js';
 import { readPid } from '../daemon/daemon.js';
 import { fetchStatus } from './cli-launch.js';
 import { captureLookup, findPortHolder } from './port-holder.js';
-import { DriveMode, decideDriveMode, describeAttached, driveForeignHolder, driveRaceLost, requestDriveSession, } from './drive-attach.js';
+import { DriveMode, decideDriveMode, describeAttached, driveForeignHolder, driveHeadlessOnAttach, driveRaceLost, requestDriveSession, } from './drive-attach.js';
 export function handleDrive(parsed) {
     void driveWithHonestConflict(parsed);
 }
@@ -43,7 +43,7 @@ async function driveWithHonestConflict(parsed) {
         return;
     }
     if (DriveMode.ATTACH === mode) {
-        await attachToRunningDaemon(parsed.port, parsed.driveUrl);
+        await attachToRunningDaemon(parsed.port, parsed.driveUrl, parsed.headless);
         return;
     }
     // The probe cannot close the race: something can take the port between here and the bind, and the
@@ -81,7 +81,7 @@ async function driveWithHonestConflict(parsed) {
  * against it renews its lease), and a foreground hold here could only keep it alive by faking tool
  * calls at it.
  */
-async function attachToRunningDaemon(port, url) {
+async function attachToRunningDaemon(port, url, headless) {
     const result = await requestDriveSession(port, url);
     if (!result.ok) {
         log('reticle_drive_attach_failed', { port, url, reason: result.reason });
@@ -96,6 +96,10 @@ async function attachToRunningDaemon(port, url) {
         ready: result.session.ready,
     });
     process.stderr.write(`${describeAttached(port, url, result.session)}\n`);
+    // The command's own default is headed, and this path cannot deliver that. Said out loud rather
+    // than left for the user to discover by watching a window that never opens.
+    if (!headless)
+        process.stderr.write(`${driveHeadlessOnAttach(port, url)}\n`);
     // A tab that never connected is not a drive session, and reporting one is the false green this
     // command exists to avoid.
     if (!result.session.ready)

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,174 @@
+/**
+ * `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 { resolveMcpPort, daemonProjectAt } from '../daemon/daemon-resolve.js';
+import { daemonSpawnArgs } from './daemon-start-options.js';
+import { WakeAction, decideWake } from '../daemon/wake-decision.js';
+import { pickDaemonPortToBind } from '../daemon/free-port.js';
+import { fetchStatus } from './cli-launch.js';
+import { migrateApprovals } from '../setup/approval-migration.js';
+import { ReticleEnv } from '@reticlehq/core';
+import { agentIo } from '../setup/agent-io.js';
+import { SERVER_VERSION } from '../version/server-version.js';
+import { homedir } from 'node:os';
+/**
+ * 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".
+    // Read once and reused by the wake path below: the boot resolution and every later wake must be
+    // defending the SAME identity, and computing it twice is how they drift apart.
+    // Before the port work, because it is the only moment we are guaranteed to get on a machine that
+    // installed Reticle before the pre-approval rules existed. Once per version, never a create that
+    // supersedes an allowlist we cannot read, and it cannot throw: see approval-migration.
+    // A sandboxed state dir means a test, a gate or a fixture, none of which are asking us to rewrite
+    // the real user's editor configuration.
+    if (undefined === process.env[ReticleEnv.STATE_DIR]) {
+        migrateApprovals({
+            io: agentIo,
+            home: homedir(),
+            platform: process.platform,
+            stateHome: reticleStateHome(),
+            version: SERVER_VERSION,
+            log,
+        });
+    }
+    const projectId = readProjectId(process.cwd());
+    const port = await resolveMcpPort(opts.port, projectId, 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 });
+        // Identity, not just presence. `resolveMcpPort` above already refuses to adopt a stranger's
+        // daemon at boot; this is the same question asked on every WAKE, which is where it was missing.
+        //
+        // Reachable by ordinary use, with no error anywhere: a daemon retires on its idle timer and
+        // frees the port, another project's daemon binds it, and this project's dormant proxy wakes
+        // straight onto it. The agent then drives, asserts and reports a verdict about a DIFFERENT
+        // APPLICATION. That is worse than the disconnect it was reintroduced under the cover of, because
+        // a disconnect is visible and this is a false green wearing a valid session.
+        const wake = decideWake(presence, daemonProjectAt(port, reticleStateHome()), projectId);
+        if (WakeAction.USE === wake)
+            return;
+        if (WakeAction.REFUSE === wake) {
+            throw new Error(PortPresence.DAEMON === presence
+                ? `the daemon on port ${String(port)} belongs to a different project, so this one will ` +
+                    'not adopt it. Stop it, or start this project on its own port.'
+                : describePresence(presence, port));
+        }
+        const scriptPath = process.argv[1];
+        if (scriptPath === undefined) {
+            log('reticle_mcp_no_script', {});
+            process.exit(1);
+        }
+        const daemonArgs = daemonSpawnArgs({
+            port,
+            headless,
+            http,
+            ...(driveUrl !== undefined ? { driveUrl } : {}),
+            ...(httpPort !== undefined ? { httpPort } : {}),
+            ...(httpToken !== undefined ? { 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',
+            });
+        });
+    });
+}