@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/cli/doctor/doctor-rows.js

@@ -0,0 +1,77 @@
+/**
+ * The row labels `reticle doctor` can print, and the one place that pads them into a column.
+ *
+ * These were free strings before, hand-padded at every call site across three modules
+ * (`cli-doctor.ts`, `doctor-daemon-line.ts`, `doctor-sessions-line.ts`). Two problems with that,
+ * and the second is the one that motivated #340:
+ *
+ * 1. The padding was maintained by eye. Every label happened to be padded to the same column, but
+ *    nothing enforced it, and a label longer than the column would have quietly broken the
+ *    alignment of one row in a checklist whose whole readability is the column.
+ * 2. Nothing connected the labels to the docs pages that reproduce doctor's output. A row could be
+ *    added, renamed or removed and the three pages showing sample output would go on describing the
+ *    old vocabulary, with no gate noticing. `doctor` is the command a stuck user runs, and the docs
+ *    are what they read when its output does not match what they were told to expect.
+ *
+ * The label set is exported so the docs guard can derive its expectation from the command rather
+ * than from a hand-kept list, which is the direction that catches the case that actually bites: a
+ * row added and never documented.
+ *
+ * NOT every row prints on every run. `version` prints only on skew, `port check` only on a
+ * 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.
+ */
+/** Every row label `doctor` can emit. Values are the literal text at the head of the row. */
+export const DoctorRow = {
+    NODE: 'node',
+    CHROMIUM: 'chromium',
+    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',
+    /**
+     * Which of `localhost`'s two answers reaches the bridge, printed only when they disagree.
+     *
+     * The daemon binds `127.0.0.1` and `loopback-alias.ts` forwards `[::1]` to it, best-effort —
+     * a machine with IPv6 off, or something already holding `[::1]:port`, leaves the daemon serving
+     * IPv4 alone and must not be fatal. But `localhost` is a NAME, and Windows Chrome tries the IPv6
+     * answer first, so on that combination the SDK's documented default URL cannot reach a daemon that
+     * is running perfectly. The only record of the alias failing was a field on one JSON log line.
+     *
+     * Conditional like `version`: a healthy machine answers on both and prints nothing.
+     */
+    LOOPBACK: 'loopback',
+    BRIDGE_PORT: 'bridge port',
+    PORT_CHECK: 'port check',
+    SIBLING: 'sibling',
+    DAEMON_LOG: 'daemon log',
+    TRACING: 'tracing',
+    DESKTOP: 'desktop',
+};
+export const DOCTOR_ROW_LABELS = Object.values(DoctorRow);
+/** Indent every row carries, before the label. */
+const INDENT = '  ';
+/**
+ * Width the label column pads to.
+ *
+ * Derived from the longest label rather than hardcoded, so adding a longer row realigns the whole
+ * checklist instead of breaking one line of it. With the current set the longest is `bridge port`
+ * (11), so this is 13 — byte-identical to the hand-padding it replaces. A test pins that, so a
+ * change to the column is a deliberate, visible change rather than an invisible reflow.
+ */
+export const LABEL_COLUMN = DOCTOR_ROW_LABELS.reduce((widest, label) => Math.max(widest, label.length), 0) + 2;
+/** Build one `doctor` row: the standard indent, the label padded to the column, then `rest`. */
+export function doctorRow(label, rest) {
+    return `${INDENT}${label.padEnd(LABEL_COLUMN)}${rest}`;
+}

package/dist/command/cli/doctor/doctor-sessions-line.js

@@ -0,0 +1,69 @@
+import { SELF_RECOVERING_MARKER } from '../../../portal/session/no-session-diagnosis.js';
+import { DoctorRow, doctorRow } from './doctor-rows.js';
+/**
+ * The line `doctor` was missing: is anything actually CONNECTED?
+ *
+ * `doctor` collapses the first-run failure modes into one command, and it checked every one of them
+ * except the one the funnel actually stalls on. A user who has installed the SDK, wired the plugin
+ * and started the daemon runs `doctor`, gets node, chromium, daemon, bridge port and desktop wiring
+ * all ✓, and is no better off — because the thing that is wrong is that no page has ever dialled in,
+ * and nothing on that screen mentions pages.
+ *
+ * The daemon has always known. `/status` carries `sessionCount`, the session list, and `why` — the
+ * same no-session diagnosis an agent gets from an empty `reticle_sessions`, which is careful about
+ * what it can and cannot prove. `reticle status` prints it. `doctor` fetched the identical payload
+ * to read `version` and `contract` off it and dropped the rest on the floor.
+ *
+ * So this invents no new diagnosis. It surfaces one that already exists, on the command a stuck human
+ * runs, which is the difference between a checklist that ends in "everything is fine" and one that
+ * ends in a next action.
+ *
+ * Pure and payload-shaped rather than reaching for the bridge: `doctor` runs in a separate process
+ * from the daemon and can only ever know what `/status` told it.
+ */
+/**
+ * The diagnosis is written for an AGENT, and `doctor` has a human in front of it.
+ *
+ * Every branch of it ends by telling the reader to call `reticle_sessions` again, which is right for
+ * the caller it was written for and useless to somebody in a shell: an MCP tool is not something you
+ * can type. Printing it unchanged would make `doctor` end on a recovery its reader cannot perform,
+ * which is the same defect as the aged-out lease message that told an agent to ask a human to reopen
+ * a tab that never existed.
+ *
+ * So the last sentence is swapped for the shell equivalent of itself. Only that sentence — the rest
+ * of the diagnosis is about the app and reads the same to either audience.
+ */
+const HUMAN_RETRY = 'Then run `reticle doctor` again — it will appear within a second of the page loading.';
+function forAHuman(why) {
+    // Imported, not re-typed: a copy of a sentence that has to match another file's byte-for-byte is a
+    // drift bug with a delay on it, and the failure is silent — the swap simply stops happening and
+    // doctor goes back to telling a human to call an MCP tool.
+    return why.replace(SELF_RECOVERING_MARKER, HUMAN_RETRY);
+}
+function countOf(facts) {
+    const raw = facts.sessionCount;
+    return 'number' === typeof raw && Number.isFinite(raw) && raw >= 0 ? raw : undefined;
+}
+export function sessionsLine(facts) {
+    const count = countOf(facts);
+    if (count === undefined) {
+        // An older daemon that does not report it. Saying "0 connected" here would be a claim about the
+        // app made from a payload that never mentioned the app — the exact kind of confident wrong
+        // sentence the no-session diagnosis exists to avoid.
+        return {
+            text: doctorRow(DoctorRow.SESSIONS, '? this daemon did not report connected pages (older build)'),
+        };
+    }
+    if (count > 0) {
+        const plural = 1 === count ? 'page' : 'pages';
+        return { text: doctorRow(DoctorRow.SESSIONS, `✓ ${String(count)} ${plural} connected`) };
+    }
+    const why = 'string' === typeof facts.why && facts.why.length > 0 ? forAHuman(facts.why) : undefined;
+    return {
+        // Deliberately ✗ rather than a neutral note. Zero connected pages is why somebody is running
+        // doctor, and a ✓-coloured checklist that hides the one failing thing is how the old output
+        // convinced people their setup was fine.
+        text: doctorRow(DoctorRow.SESSIONS, '✗ no page has connected to this daemon'),
+        ...(why === undefined ? {} : { why }),
+    };
+}

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

@@ -0,0 +1,113 @@
+/**
+ * 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. The documented workaround is worse than the bug, 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 { PortPresence } from '../../daemon/binding/port-presence.js';
+/** What `drive` should do about the port, given what is on it. */
+export declare const DriveMode: {
+    /** Nothing is listening: bind it and run the foreground engine. */
+    readonly BIND: "bind";
+    /** Our daemon is serving it: ask that daemon for a driveable session. */
+    readonly ATTACH: "attach";
+    /** Someone else holds it: neither is possible. */
+    readonly REFUSE: "refuse";
+};
+export type DriveMode = (typeof DriveMode)[keyof typeof DriveMode];
+/** Pure. Exhaustive by switch, so a fourth presence has to decide what driving means for it. */
+export declare function decideDriveMode(presence: PortPresence): DriveMode;
+/** A driveable session the daemon opened on our behalf. */
+interface DriveSession {
+    sessionId: string;
+    /** Whether the tab's SDK actually registered — false ⇒ the app may not embed @reticlehq/core. */
+    ready: boolean;
+    /** How long the session survives untouched. Absent from a daemon that does not report it. */
+    expiresInMs?: number;
+    /** The daemon's own diagnosis when the tab did not connect. */
+    hint?: string;
+}
+type DriveAttachResult = {
+    ok: true;
+    session: DriveSession;
+} | {
+    ok: false;
+    reason: string;
+};
+/** POST the drive request. Injected so the decision logic is tested without a socket. */
+type DrivePost = (port: number, path: string, body: string) => Promise<{
+    status: number;
+    body: string;
+}>;
+/**
+ * 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 declare function readAttachResponse(port: number, url: string, res: {
+    status: number;
+    body: string;
+}): DriveAttachResult;
+/** Ask the daemon on `port` to open a driveable browser at `url`. */
+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.
+ *
+ * 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 declare function driveForeignHolder(description: string): string;
+/**
+ * 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 declare function driveRaceLost(port: number, url: string): string;
+export {};

package/dist/command/cli/drive/drive-attach.js

@@ -0,0 +1,221 @@
+/**
+ * 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. The documented workaround is worse than the bug, 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/binding/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/command/cli/drive/drive-command.js

@@ -0,0 +1,107 @@
+/**
+ * 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/binding/port-presence.js';
+import { probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
+import { readPid } from '../../daemon/daemon.js';
+import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
+import { captureLookup, findPortHolder } from '../ports/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/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);
+}