@reticlehq/server 2.8.0 → 2.10.0

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

@@ -0,0 +1,99 @@
+/**
+ * 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 { PortPresence } from '../daemon/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. */
+export 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;
+}
+export type DriveAttachResult = {
+    ok: true;
+    session: DriveSession;
+} | {
+    ok: false;
+    reason: string;
+};
+/** POST the drive request. Injected so the decision logic is tested without a socket. */
+export 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;
+/**
+ * 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;

package/dist/cli/drive-attach.js

@@ -0,0 +1,203 @@
+/**
+ * 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}`);
+}
+/**
+ * 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.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export declare function handleDrive(parsed: {
+    port: number;
+    driveUrl: string;
+    headless: boolean;
+}): void;

package/dist/cli/drive-command.js

@@ -0,0 +1,103 @@
+/**
+ * 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, 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);
+        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) {
+    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`);
+    // 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/open-note.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What `reticle open` says when it launched a URL and no session appeared.
+ *
+ * `open` resolves the port leniently on purpose: if nothing is on the port you asked for, it finds a
+ * running daemon instead, so nobody has to hunt for the port. That is the right default and it has
+ * one sharp edge — when it substitutes, the command is now talking to a DIFFERENT daemon than the
+ * caller named, and every subsequent sentence is about that other daemon.
+ *
+ * Observed driving this repo's own fixture: `open --port 4470` found nothing there, silently used a
+ * daemon on 4400, and reported that the app "carries no Reticle SDK, or dials a port other than
+ * 4400". The app was wired and was dialling 4470 exactly as asked. Reticle knew both numbers and
+ * reported neither, so the one actionable fact — you are pointed at the wrong daemon — was the only
+ * thing missing, and the advice given instead was to re-run `init` on a correctly installed app.
+ *
+ * That is the same shape as the field reports where a daemon in the wrong repo produced a diagnosis
+ * blaming the app: an absence explained by a cause the daemon had already ruled out.
+ *
+ * So the substitution is stated FIRST, with both numbers, before any cause that assumes they match.
+ */
+export declare function openFailureNote(port: number, requestedPort: number): string;

package/dist/cli/open-note.js

@@ -0,0 +1,37 @@
+/**
+ * What `reticle open` says when it launched a URL and no session appeared.
+ *
+ * `open` resolves the port leniently on purpose: if nothing is on the port you asked for, it finds a
+ * running daemon instead, so nobody has to hunt for the port. That is the right default and it has
+ * one sharp edge — when it substitutes, the command is now talking to a DIFFERENT daemon than the
+ * caller named, and every subsequent sentence is about that other daemon.
+ *
+ * Observed driving this repo's own fixture: `open --port 4470` found nothing there, silently used a
+ * daemon on 4400, and reported that the app "carries no Reticle SDK, or dials a port other than
+ * 4400". The app was wired and was dialling 4470 exactly as asked. Reticle knew both numbers and
+ * reported neither, so the one actionable fact — you are pointed at the wrong daemon — was the only
+ * thing missing, and the advice given instead was to re-run `init` on a correctly installed app.
+ *
+ * That is the same shape as the field reports where a daemon in the wrong repo produced a diagnosis
+ * blaming the app: an absence explained by a cause the daemon had already ruled out.
+ *
+ * So the substitution is stated FIRST, with both numbers, before any cause that assumes they match.
+ */
+export function openFailureNote(port, requestedPort) {
+    const substituted = port === requestedPort
+        ? ''
+        : `NOTE FIRST: you asked for port ${String(requestedPort)} and nothing was listening there, ` +
+            `so this used a daemon already running on ${String(port)}. If your app dials ` +
+            `${String(requestedPort)}, that is the whole problem — nothing below applies. Start a daemon ` +
+            `on ${String(requestedPort)} (\`npx @reticlehq/server serve --port ${String(requestedPort)}\`) ` +
+            `or point the app at ${String(port)}. `;
+    return (`${substituted}the URL was handed to the system default browser (this command does not use ` +
+        `Reticle's own Chromium, so a chromium warning from \`reticle doctor\` is unrelated ` +
+        `to this). No Reticle session appeared. By far the likeliest cause is that the app ` +
+        `carries no Reticle SDK, or dials a port other than ${String(port)} — run ` +
+        `\`npx @reticlehq/server init\` in the app's directory and restart its dev server. If the app IS ` +
+        `wired, give the page a moment and check the browser console: the SDK announces its ` +
+        `own connect failures there, including the one it refuses to make from a ` +
+        `non-localhost host, which needs BOTH allowNonLocalhost: true AND a pairing token ` +
+        `(~/.reticle/pairing-token) — the flag alone is not sufficient.`);
+}

package/dist/cli/status-next-action.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The sentence `status` owes the user, because `init` promised it.
+ *
+ * `init` closes with "run `npx @reticlehq/server status` — it confirms the app connected, or says
+ * exactly why it has not". On a real install, following that instruction printed `running: false,
+ * presence: "free"` and nothing else: no reason, no next step, no mention of the app. This is the last
+ * checkpoint in the setup path, so a user who arrives here and learns nothing has nowhere left to go.
+ *
+ * Deliberately thin. The differential already exists in `nextActionFor`, which ranks these causes from
+ * what the daemon knows and was rewritten this week to stop leading with a port mismatch; a second
+ * differential here could disagree with the first, and two confident answers pointing different ways
+ * is worse than one. This only supplies the facts the CLI has and renders the answer.
+ */
+export interface StatusFacts {
+    /** Is a usable daemon answering on this port? */
+    running: boolean;
+    /** Live browser sessions the daemon reports. */
+    sessionCount: number;
+    /** Has an app for this project ever connected on this port? Durable, survives a daemon restart. */
+    previouslyConnected: boolean;
+    /**
+     * Has `init` run in this project — i.e. is there a `.reticle.json` with a projectId?
+     *
+     * Was hardcoded `true` at the call below, which made the one branch that can say "run init"
+     * unreachable from `status` however unwired the project was. That is the commonest reason this
+     * command has nothing to report: registering the MCP server does not wire the app, and several
+     * paths do the first without the second.
+     */
+    initialized: boolean;
+}
+/**
+ * What to do next, or `undefined` when a session is connected and there is nothing to fix.
+ *
+ * The success case has to stay silent: advice printed beside a working session reads as though
+ * something is still wrong, which is its own kind of lie.
+ */
+export declare function statusNextAction(facts: StatusFacts): string | undefined;

package/dist/cli/status-next-action.js

@@ -0,0 +1,61 @@
+/**
+ * The sentence `status` owes the user, because `init` promised it.
+ *
+ * `init` closes with "run `npx @reticlehq/server status` — it confirms the app connected, or says
+ * exactly why it has not". On a real install, following that instruction printed `running: false,
+ * presence: "free"` and nothing else: no reason, no next step, no mention of the app. This is the last
+ * checkpoint in the setup path, so a user who arrives here and learns nothing has nowhere left to go.
+ *
+ * Deliberately thin. The differential already exists in `nextActionFor`, which ranks these causes from
+ * what the daemon knows and was rewritten this week to stop leading with a port mismatch; a second
+ * differential here could disagree with the first, and two confident answers pointing different ways
+ * is worse than one. This only supplies the facts the CLI has and renders the answer.
+ */
+import { nextActionFor } from '../session/no-session-next-action.js';
+/**
+ * What to do next, or `undefined` when a session is connected and there is nothing to fix.
+ *
+ * The success case has to stay silent: advice printed beside a working session reads as though
+ * something is still wrong, which is its own kind of lie.
+ */
+export function statusNextAction(facts) {
+    if (facts.sessionCount > 0)
+        return undefined;
+    // Ahead of everything else, because it dominates: an app that was never wired cannot connect, and
+    // no advice about dev servers or ports applies until it is. `previouslyConnected` overrides it —
+    // an app CAN be wired by the Vite or Babel plugin with no `.reticle.json` at all, so a project
+    // that has connected here before is wired whatever this file says, and sending it back to `init`
+    // would be the same wrong answer in the other direction.
+    if (!facts.initialized && !facts.previouslyConnected) {
+        return ('no app has ever connected for this project, and there is no Reticle config here — so the ' +
+            'tools are registered and the app itself is not instrumented. Those are two different halves ' +
+            'of the install. Run `npx @reticlehq/server init` in the app directory, then start the dev ' +
+            'server and load the page.');
+    }
+    if (!facts.running) {
+        // `running: false` reads as "Reticle is broken", and it usually means the opposite: the daemon is
+        // started by an agent, on demand, and idles out when nobody is driving. A user who has not
+        // attached an agent yet is exactly on track, and saying so is the whole job of this branch.
+        const wiring = facts.previouslyConnected
+            ? 'This project has connected before, so the wiring is correct.'
+            : '';
+        return (`no daemon is running on this port, which is normal — an agent starts it when it first calls a ` +
+            `Reticle tool, and it exits again when idle. ${wiring} Ask your agent to verify something, then ` +
+            `run status again.`).replace(/\s+/g, ' ');
+    }
+    // The daemon is up and no page has connected. `nextActionFor` owns the ranking; the CLI cannot see
+    // listening ports or a dev command from here, so it passes what it has and lets that function say
+    // what is missing rather than guessing at it.
+    const next = nextActionFor({
+        // The durable bit IS this side's `everConnected`. In-process the flag means "this daemon has served
+        // a session", which a daemon seconds old cannot know; from the CLI the honest equivalent is "an app
+        // for this project has connected on this port", which is the fact that decides whether the wiring
+        // is in question at all.
+        everConnected: facts.previouslyConnected,
+        initialized: facts.initialized,
+        listening: [],
+        dev: undefined,
+        previouslyConnected: facts.previouslyConnected,
+    });
+    return next.reason;
+}