@reticlehq/server 2.14.0 → 3.2.0

package/dist/cli/drive-attach.js

@@ -1,221 +0,0 @@
-/**
- * Who gets the bridge port when `reticle drive <url>` runs — and what happens when the answer is
- * "not you".
- *
- * `drive` used to bind :4400 unconditionally. A daemon on that port is the NORMAL state the moment
- * any MCP client has started one, so the bind died with a raw `node:net` EADDRINUSE stack — in the
- * exact situation the product tells people to run `drive` in, since `reticle_sessions` recommends it
- * for a throttled tab and a throttled tab nearly always coexists with the daemon that makes the bind
- * impossible. Two independent field reports hit it; the second lost half an hour to the workaround,
- * because `reticle stop` frees the port and the MCP proxy respawns a daemon into the gap before
- * `drive` can bind, so the "escape hatch" is a race the user cannot win.
- *
- * The fix is arbitration, not a better race:
- *
- * - **A healthy daemon owns the port → ATTACH.** Driving is a REQUEST to the process that already
- *   owns the browser plane, not a competing process. The daemon hands out a pooled, isolated,
- *   never-throttled context (the same one `reticle_lease` returns) and the caller gets back a
- *   sessionId every Reticle tool — including the ones the agent already has open on that daemon —
- *   can address. Nothing is bound, so there is nothing to race for and no reason to run `stop`.
- * - **Nothing on the port → BIND.** Unchanged: `drive` is still a self-contained foreground engine
- *   with its own browser when it can have the port.
- * - **A stranger owns the port → REFUSE**, naming the holder. Neither binding nor attaching can
- *   work, and pretending otherwise is the lie this module exists to remove.
- *
- * Making `stop` block until the port is genuinely free (and muzzling the proxy meanwhile) was the
- * alternative. It is strictly more machinery — a cross-process handoff, a suppression window, a new
- * way for the proxy to be wrong — to earn the same browser the daemon can already open, and it would
- * still leave `drive` unable to run while an agent is working. Attaching deletes the race instead of
- * refereeing it.
- */
-import * as http from 'node:http';
-import { DRIVE_PATH, LOOPBACK_HOST } from '@reticlehq/core';
-import { PortPresence } from '../daemon/port-presence.js';
-/** What `drive` should do about the port, given what is on it. */
-export const DriveMode = {
-    /** Nothing is listening: bind it and run the foreground engine. */
-    BIND: 'bind',
-    /** Our daemon is serving it: ask that daemon for a driveable session. */
-    ATTACH: 'attach',
-    /** Someone else holds it: neither is possible. */
-    REFUSE: 'refuse',
-};
-/** Pure. Exhaustive by switch, so a fourth presence has to decide what driving means for it. */
-export function decideDriveMode(presence) {
-    switch (presence) {
-        case PortPresence.DAEMON:
-            return DriveMode.ATTACH;
-        case PortPresence.FOREIGN:
-            return DriveMode.REFUSE;
-        case PortPresence.FREE:
-            return DriveMode.BIND;
-    }
-}
-/** The daemon answers a tool refusal (app down, pool unavailable) as a 200 with this field. */
-const ERROR_FIELD = 'error';
-/**
- * Turn the daemon's answer into a session or a sentence. Pure.
- *
- * Every failure branch has to end in something the reader can DO, because this is the path that
- * replaces the EADDRINUSE stack — an answer that is merely accurate ("404") repeats the original
- * mistake in a politer font.
- */
-export function readAttachResponse(port, url, res) {
-    if (404 === res.status) {
-        return {
-            ok: false,
-            reason: `the Reticle daemon on :${String(port)} is older than this CLI and cannot open a drive ` +
-                'session — stop it with `reticle stop` and retry (the next tool call starts a current one).',
-        };
-    }
-    if (200 !== res.status) {
-        return {
-            ok: false,
-            reason: `the Reticle daemon on :${String(port)} refused to open a drive session ` +
-                `(HTTP ${String(res.status)}: ${res.body.slice(0, 200)}).`,
-        };
-    }
-    const notASession = {
-        ok: false,
-        reason: `the Reticle daemon on :${String(port)} answered the drive request with something that is ` +
-            'not a session. Stop it with `reticle stop` and retry.',
-    };
-    const parsed = parseJson(res.body);
-    if (typeof parsed !== 'object' || null === parsed)
-        return notASession;
-    const record = parsed;
-    const error = record[ERROR_FIELD];
-    if ('string' === typeof error) {
-        return { ok: false, reason: `could not drive ${url} — ${error}` };
-    }
-    const sessionId = record['sessionId'];
-    if ('string' !== typeof sessionId || 0 === sessionId.length) {
-        return {
-            ok: false,
-            reason: `the Reticle daemon on :${String(port)} answered the drive request with something that is ` +
-                'not a session. Stop it with `reticle stop` and retry.',
-        };
-    }
-    const expiresInMs = record['expiresInMs'];
-    const hint = record['hint'];
-    return {
-        ok: true,
-        session: {
-            sessionId,
-            ready: true === record['ready'],
-            ...('number' === typeof expiresInMs ? { expiresInMs } : {}),
-            ...('string' === typeof hint ? { hint } : {}),
-        },
-    };
-}
-function parseJson(body) {
-    try {
-        return JSON.parse(body);
-    }
-    catch {
-        return undefined;
-    }
-}
-/** Ask the daemon on `port` to open a driveable browser at `url`. */
-export async function requestDriveSession(port, url, post = postJson) {
-    let res;
-    try {
-        res = await post(port, DRIVE_PATH, JSON.stringify({ url }));
-    }
-    catch (error) {
-        // The daemon answered /status a moment ago and is gone now — a shutdown, a crash, a `stop` from
-        // another terminal. Retrying is the whole answer, and it is the one thing an errno never says.
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-            ok: false,
-            reason: `could not reach the Reticle daemon on :${String(port)} (${message}) — it answered a ` +
-                'moment ago, so it is shutting down or has just been stopped. Retry the command.',
-        };
-    }
-    return readAttachResponse(port, url, res);
-}
-/** The success line. Names the session, because that is the handle everything downstream needs. */
-export function describeAttached(port, url, session) {
-    const life = session.expiresInMs === undefined
-        ? ''
-        : ` It is released after ${String(Math.round(session.expiresInMs / 1000))}s untouched; any ` +
-            'tool call against it resets that.';
-    if (!session.ready) {
-        return (`the Reticle daemon on :${String(port)} opened ${url} as session ${session.sessionId}, but ` +
-            `the page did not connect to the bridge. ${session.hint ?? 'Check that the app embeds @reticlehq/core.'}`);
-    }
-    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.
- *
- * The shared sentence for a foreign holder offers `--port`, which is true of `serve`, `status` and
- * `doctor` and false here: `drive` rejects that flag outright and reads the port from the
- * environment. Sending someone to a flag that does not exist is a second dead end at the moment they
- * have already hit one, so the route that works is named instead. The shared sentence is passed in
- * rather than rebuilt, so the description of the holder stays in one place.
- */
-export function driveForeignHolder(description) {
-    return `${description} \`drive\` takes the port from RETICLE_PORT or .reticle.json, not a flag.`;
-}
-/**
- * The port went from free to taken between the probe and the bind.
- *
- * The probe cannot close that window, and the loser of the race learns about it as an EADDRINUSE on
- * the server object, outside every promise `drive` holds. It is a DISTINCT state from a foreign
- * holder — the likeliest winner is a daemon the proxy just spawned — so it gets its own sentence,
- * and that sentence is "run it again", because the second run attaches instead of binding.
- */
-export function driveRaceLost(port, url) {
-    return (`:${String(port)} was taken while \`drive\` was starting — a daemon (probably one the agent's ` +
-        `MCP proxy just spawned) now owns it. Run \`reticle drive ${url}\` again: it will attach to ` +
-        'that daemon instead of binding the port.');
-}
-/** How long the drive request waits. A pooled context has to launch a browser on a cold daemon. */
-const DRIVE_REQUEST_TIMEOUT_MS = 60_000;
-/** The real POST. Loopback-only: the daemon is always local, and the drive plane never leaves the host. */
-function postJson(port, path, body) {
-    return new Promise((resolve, reject) => {
-        const req = http.request({
-            host: LOOPBACK_HOST,
-            port,
-            path,
-            method: 'POST',
-            timeout: DRIVE_REQUEST_TIMEOUT_MS,
-            headers: {
-                'Content-Type': 'application/json',
-                'Content-Length': Buffer.byteLength(body),
-            },
-        }, (res) => {
-            let received = '';
-            res.setEncoding('utf8');
-            res.on('data', (chunk) => (received += chunk));
-            res.on('end', () => resolve({ status: res.statusCode ?? 0, body: received }));
-        });
-        req.on('error', reject);
-        req.on('timeout', () => {
-            req.destroy();
-            reject(new Error(`no answer within ${String(DRIVE_REQUEST_TIMEOUT_MS)}ms`));
-        });
-        req.end(body);
-    });
-}

package/dist/cli/drive-command.js

@@ -1,107 +0,0 @@
-/**
- * The `reticle drive <url>` command: decide who gets the bridge port, then do the right thing.
- *
- * Lifted out of cli.ts as one unit — the decision, the attach, and the bind are three answers to a
- * single question and reading one without the others is how the port fight got shipped in the first
- * place. The pure parts (which mode, and every sentence a user reads) live next door in
- * drive-attach.ts, which is where the reasoning for attaching is written down.
- */
-import { start } from '../index.js';
-import { log } from '../log.js';
-import { probePresence, describePresence } from '../daemon/port-presence.js';
-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, driveHeadlessOnAttach, driveRaceLost, requestDriveSession, } from './drive-attach.js';
-export function handleDrive(parsed) {
-    void driveWithHonestConflict(parsed);
-}
-/**
- * Decide who gets the port BEFORE binding it — and when the answer is "the daemon", ask it instead.
- *
- * `drive` went straight to `start`, which binds. The listen error surfaces asynchronously on the
- * server object long after `start` has resolved, so the `.catch` on that promise could never see it
- * and the process died with the raw `node:net` EADDRINUSE stack — in the one situation this command
- * is most often run in, since `reticle_sessions` recommends `reticle drive` for a throttled tab and
- * a throttled tab nearly always coexists with the daemon holding the port. Refusing politely was
- * only half a fix: the way out it named (`reticle stop`, then retry) is a race the user loses,
- * because the MCP proxy respawns a daemon into the gap. So a healthy daemon is now ATTACHED to —
- * see cli/drive-attach.ts.
- */
-async function driveWithHonestConflict(parsed) {
-    const presence = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
-    const mode = decideDriveMode(presence);
-    if (DriveMode.REFUSE === mode) {
-        const reason = driveForeignHolder(describePresence(presence, parsed.port, {
-            ourPid: readPid(parsed.port),
-            holderPid: findPortHolder(parsed.port, captureLookup)?.pid,
-        }));
-        log('reticle_drive_port_conflict', { port: parsed.port, presence, reason });
-        process.stderr.write(`${reason}\n`);
-        process.exit(1);
-        return;
-    }
-    if (DriveMode.ATTACH === mode) {
-        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
-    // bind reports it on the server, outside every promise this function holds. Catching it at the
-    // process is the only place that sees it at all — and only EADDRINUSE, so a genuine crash still
-    // crashes rather than being dressed up as a port conflict.
-    process.on('uncaughtException', (error) => {
-        const code = error?.code;
-        if ('EADDRINUSE' !== code)
-            throw error;
-        const reason = driveRaceLost(parsed.port, parsed.driveUrl);
-        log('reticle_drive_port_race_lost', { port: parsed.port, reason });
-        process.stderr.write(`${reason}\n`);
-        process.exit(1);
-    });
-    const options = {
-        port: parsed.port,
-        driveUrl: parsed.driveUrl,
-        headless: parsed.headless,
-    };
-    try {
-        await start(options);
-        log('reticle_started', { port: parsed.port });
-    }
-    catch (error) {
-        log('reticle_start_failed', { error: error instanceof Error ? error.message : String(error) });
-        process.exit(1);
-    }
-}
-/**
- * Drive through the daemon that already owns the port.
- *
- * Exits once the session exists rather than holding the foreground: the thing the caller needs is
- * the sessionId, the session belongs to the daemon (it outlives this process, and any tool call
- * 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, headless) {
-    const result = await requestDriveSession(port, url);
-    if (!result.ok) {
-        log('reticle_drive_attach_failed', { port, url, reason: result.reason });
-        process.stderr.write(`${result.reason}\n`);
-        process.exit(1);
-        return;
-    }
-    log('reticle_drive_attached', {
-        port,
-        url,
-        sessionId: result.session.sessionId,
-        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)
-        process.exit(1);
-}

package/dist/cli/mcp-command.js

@@ -1,174 +0,0 @@
-/**
- * `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',
-            });
-        });
-    });
-}

package/dist/cli/port-holder.js

@@ -1,123 +0,0 @@
-/**
- * Who is holding the bridge port.
- *
- * `doctor` is what a user runs when the agent cannot reach the bridge, and the commonest real cause
- * is that something else is on 4400. It already stopped saying "nothing is listening" for that case,
- * but it did not say WHICH process — so the reader's next move was a shell command they had to know.
- *
- * Naming the holder is also the safe answer to a trap this project has hit for real: the obvious
- * lookup, `lsof -ti tcp:4400 | xargs kill -9`, ALSO kills the agent's own `reticle mcp` proxy,
- * because that proxy holds a client connection to the same port and `-ti` does not filter to
- * listeners. Every invocation here is `-sTCP:LISTEN`, and the message never suggests `-ti`.
- *
- * The parser is pure and the lookup takes an injected exec, so the rule is tested on every platform
- * while the shelling out stays at the call site.
- */
-import { spawnSync } from 'node:child_process';
-/** Bound on the holder lookup. A hung `lsof` must not hang the commands that diagnose hangs. */
-const LOOKUP_TIMEOUT_MS = 2_000;
-/**
- * Run a lookup and return its stdout, or null if it could not run.
- *
- * Null on ANY failure — no lsof (every Windows user, a slim container), a non-zero exit, a throw.
- * This is a diagnostic nicety inside the commands people run when things are already broken; it must
- * never be the reason one of them fails. Every caller handles the null by saying it could not
- * identify the holder, rather than asserting the holder is not ours — a claim it has no evidence
- * for, and one that was wrong for every Windows user.
- */
-export function captureLookup(command, args) {
-    try {
-        const result = spawnSync(command, [...args], { encoding: 'utf8', timeout: LOOKUP_TIMEOUT_MS });
-        return 0 === result.status && 'string' === typeof result.stdout ? result.stdout : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** `lsof -F pc` emits one field per line, prefixed by its selector: `p<pid>`, `c<command>`. */
-const PID_FIELD = 'p';
-const COMMAND_FIELD = 'c';
-/**
- * The FIRST listener in `lsof -nP -iTCP:<port> -sTCP:LISTEN -F pc` output, or null.
- *
- * First, not "the only one": a dual-stack listener (IPv4 + IPv6) is reported twice, and on a port
- * conflict the answer the reader needs is "something is there, here is what" rather than an
- * exhaustive list. A second `p` record ends the first.
- *
- * Null on anything incomplete. Half an answer — a pid with no command — prints worse than the
- * un-named message it would replace, which is the same mistake as the port lie this command fixed.
- */
-export function parsePortHolder(stdout) {
-    let pid;
-    let command;
-    for (const raw of stdout.split('\n')) {
-        const line = raw.trim();
-        if (0 === line.length)
-            continue;
-        const value = line.slice(1);
-        if (line.startsWith(PID_FIELD)) {
-            if (pid !== undefined)
-                break; // a second record: the first one is the answer
-            const parsed = Number(value);
-            if (!Number.isInteger(parsed) || parsed <= 0)
-                return null;
-            pid = parsed;
-            continue;
-        }
-        if (line.startsWith(COMMAND_FIELD) && command === undefined)
-            command = value;
-    }
-    return pid === undefined || command === undefined ? null : { pid, command };
-}
-/** What `doctor` prints for a port held by something that is not a Reticle daemon. */
-export function describeForeignHolder(port, holder, 
-/**
- * The pid we recorded for this port, from the daemon pid file.
- *
- * When it matches the process actually holding the port, the port is held by OUR daemon — one
- * that accepts TCP and never answers `/status`, i.e. wedged. That classifies as FOREIGN, which is
- * right for "can anything bind this?" and wrong to say out loud: the reader goes hunting a
- * stranger, and the fix that works (`reticle stop`, it respawns on the next call) is never named.
- */
-ourPid) {
-    // Naming the command matters more than naming the process. "Stop that process" describes an
-    // outcome and leaves the reader to invent a route to it, and the route they invent is the `-ti`
-    // pipeline that takes their agent's proxy down with the holder.
-    const tail = 'a daemon cannot bind it. Free it with `reticle kill --force` (it signals the listener only, ' +
-        "never the agent's mcp proxy), or run Reticle on a different port (`--port`), then retry.";
-    if (null === holder) {
-        /**
-         * We could not identify the holder — no `lsof` (every Windows user, and 35% of them by the
-         * 2026-08 telemetry; also a slim container), or the lookup timed out.
-         *
-         * This used to assert the port was held by "another process that is not a Reticle daemon",
-         * which is a claim the null case has NO evidence for. It is also the likeliest thing to be
-         * wrong: reaching here at all means presence is FOREIGN — the port accepts TCP and never
-         * answers `/status` — and the commonest cause of that is OUR OWN daemon, wedged. So on the one
-         * platform where the lookup cannot run, `doctor` sent the reader hunting a stranger and never
-         * named `reticle stop`, the fix that actually works.
-         *
-         * Say what is known, and name the recorded pid when there is one.
-         */
-        const ours = ourPid !== null && ourPid !== undefined
-            ? ` Reticle's own records show pid ${String(ourPid)} for this port — if that process is ` +
-                'still around it is a wedged Reticle daemon, and `reticle stop` clears it.'
-            : '';
-        return `port ${String(port)} is held by a process Reticle could not identify — ${tail}${ours}`;
-    }
-    if (ourPid !== null && ourPid !== undefined && ourPid === holder.pid) {
-        return (`port ${String(port)} is held by YOUR Reticle daemon (pid ${String(holder.pid)}), and it is ` +
-            'not responding — running but wedged, so nothing can use it and nothing else can bind the ' +
-            'port. Stop it with `reticle stop`; the next tool call starts a fresh one.');
-    }
-    return (`port ${String(port)} is held by pid ${String(holder.pid)} ("${holder.command}"), which is not ` +
-        `a Reticle daemon — ${tail}`);
-}
-/** The lookup itself. `exec` is injected so the shelling out never runs in a unit test. */
-export function findPortHolder(port, exec) {
-    // -n/-P skip DNS and service-name lookups (slow, and irrelevant here). -sTCP:LISTEN is the part
-    // that matters: without it this also reports the agent's own MCP proxy, which is a client of the
-    // port, not its owner.
-    const out = exec('lsof', ['-nP', `-iTCP:${String(port)}`, '-sTCP:LISTEN', '-F', 'pc']);
-    return null === out ? null : parsePortHolder(out);
-}