@reticlehq/server 2.6.0 → 2.8.0

package/dist/cli/cli-launch.d.ts

@@ -1,3 +1,4 @@
+import { PortPresence } from '../daemon/port-presence.js';
 /**
  * CLI launch + status helpers — the daemon-introspection (`reticle status`) and the one-command
  * "show me the app" flow (`reticle open`). Split out of cli.ts so that file stays under the size cap.
@@ -19,6 +20,7 @@ interface StatusSession {
 export declare function summarizeStatus(payload: unknown): {
     sessionCount: number;
     sessions: StatusSession[];
+    why?: string;
 };
 /**
  * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
@@ -28,6 +30,22 @@ export declare function summarizeStatus(payload: unknown): {
  * another agent's session on a version bump, which is worse than a loud line.
  */
 export declare function warnOnDaemonSkew(port: number): Promise<void>;
+/**
+ * Why `reticle drive` cannot have the port, or undefined when it can. Pure.
+ *
+ * `drive` bound the port unconditionally, and a daemon already listening on it is the NORMAL state
+ * once any MCP client has started one. The bind died with a raw `node:net` stack trace: the one
+ * failure in this CLI that answered a user with a Node core dump rather than a structured Reticle
+ * line naming the port. It is also the command Reticle itself recommends — `reticle_sessions`
+ * returns "run `reticle drive <url>`" whenever a tab is throttled, and a throttled tab nearly always
+ * coexists with the running daemon that makes the bind impossible.
+ *
+ * The `reticle_lease` suggestion is deliberately first: it needs no free port, it is what the
+ * daemon's own no-session diagnostic already points at, and it works while the collision stands.
+ */
+export declare function drivePortConflict(presence: PortPresence, port: number, holder?: {
+    ourPid: number | null;
+}): string | undefined;
 /** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
 export declare function fetchStatus(port: number): Promise<unknown>;
 /** What `reticle open` should do: reuse an already-connected tab, open a new one, or ask for a url. */

package/dist/cli/cli-launch.js

@@ -6,6 +6,7 @@ import { describeSkew, DAEMON_FIX } from '../version/version-skew.js';
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { log } from '../log.js';
+import { PortPresence, describePresence } from '../daemon/port-presence.js';
 /**
  * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
  * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
@@ -15,6 +16,9 @@ export function summarizeStatus(payload) {
     if (typeof payload !== 'object' || null === payload)
         return { sessionCount: 0, sessions: [] };
     const obj = payload;
+    // Carried through to the printed line: with no sessions this is the whole answer, and dropping it
+    // here would silently undo the reason it is on the wire.
+    const why = 'string' === typeof obj['why'] ? obj['why'] : undefined;
     const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
     const sessions = raw
         .map((s) => {
@@ -34,7 +38,7 @@ export function summarizeStatus(payload) {
     })
         .filter((s) => s !== null);
     const sessionCount = 'number' === typeof obj['sessionCount'] ? obj['sessionCount'] : sessions.length;
-    return { sessionCount, sessions };
+    return { sessionCount, sessions, ...(why === undefined ? {} : { why }) };
 }
 /** A string field off the /status body, or undefined on a daemon too old to report it. */
 function statusField(payload, key) {
@@ -61,6 +65,33 @@ export async function warnOnDaemonSkew(port) {
     if (skew !== undefined)
         log('reticle_daemon_skew', { port, warning: skew });
 }
+/**
+ * Why `reticle drive` cannot have the port, or undefined when it can. Pure.
+ *
+ * `drive` bound the port unconditionally, and a daemon already listening on it is the NORMAL state
+ * once any MCP client has started one. The bind died with a raw `node:net` stack trace: the one
+ * failure in this CLI that answered a user with a Node core dump rather than a structured Reticle
+ * line naming the port. It is also the command Reticle itself recommends — `reticle_sessions`
+ * returns "run `reticle drive <url>`" whenever a tab is throttled, and a throttled tab nearly always
+ * coexists with the running daemon that makes the bind impossible.
+ *
+ * The `reticle_lease` suggestion is deliberately first: it needs no free port, it is what the
+ * daemon's own no-session diagnostic already points at, and it works while the collision stands.
+ */
+export function drivePortConflict(presence, port, holder) {
+    if (presence !== PortPresence.DAEMON && presence !== PortPresence.FOREIGN)
+        return undefined;
+    if (PortPresence.FOREIGN === presence)
+        return describePresence(presence, port);
+    const pid = holder?.ourPid;
+    const who = pid !== null && pid !== undefined
+        ? `a Reticle daemon (pid ${String(pid)}) is already serving :${String(port)}`
+        : `a Reticle daemon is already serving :${String(port)}`;
+    return (`${who}, so \`drive\` cannot bind that port. Use the daemon that is already there — its ` +
+        '`reticle_lease` tool opens a browser Reticle drives itself and needs no free port — or stop ' +
+        'it with `reticle stop` and retry, or drive on another port with `RETICLE_PORT=N` (`drive` ' +
+        'takes the port from the environment or .reticle.json, not from a flag).');
+}
 /** How long the daemon /status probe waits before giving up — a local loopback call is near-instant. */
 const STATUS_PROBE_TIMEOUT_MS = 1000;
 /** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */

package/dist/cli/cli-parse.d.ts

@@ -6,7 +6,14 @@
  */
 import { type ParsedFeedback } from './cli-parse-feedback.js';
 export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
-export declare const CLI_USAGE = "usage:\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]\n  reticle status [--port N]\n  reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port \u2014 one command)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode \u2014 for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy \u2014 auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics \u2014 status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't \u2014 prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle Cloud \u2014 runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner \u2014 batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
+/**
+ * The lines below say `reticle <command>`, which is the bin this package installs and is correct
+ * once it is on PATH. Copied into `npx`, it is not: `npx reticle` resolves the PACKAGE named
+ * `reticle`, which belongs to somebody else, and npx will happily fetch and run it. The docs were
+ * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
+ * the usage block rather than being a footnote somewhere else.
+ */
+export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";
@@ -52,6 +59,14 @@ export type CliResult = {
     kind: 'stop';
     port: number;
     quiet: boolean;
+} | {
+    kind: 'kill';
+    port: number;
+    force: boolean;
+} | {
+    kind: 'restart';
+    port: number;
+    force: boolean;
 } | {
     kind: 'status';
     port: number;

package/dist/cli/cli-parse.js

@@ -5,36 +5,47 @@
  * imports are unchanged.
  */
 import { parseFeedbackArgs } from './cli-parse-feedback.js';
+import { FORCE_FLAG } from './cli-kill.js';
 // Re-exported so every existing importer of these flags is unaffected by the file split.
 export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
-export const CLI_USAGE = `usage:
+/**
+ * The lines below say `reticle <command>`, which is the bin this package installs and is correct
+ * once it is on PATH. Copied into `npx`, it is not: `npx reticle` resolves the PACKAGE named
+ * `reticle`, which belongs to somebody else, and npx will happily fetch and run it. The docs were
+ * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
+ * the usage block rather than being a footnote somewhere else.
+ */
+export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticle <command>\` once the bin is on your PATH)
+
   reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)
                 --app picks WHICH app in a monorepo, when several are found
                 --no-mcp skips MORE than the server registration: also the agent rule files
                 (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
                 only make sense once the tools are reachable.
   reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]
-  reticle stop  [--port N] [--quiet]
+  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)
+  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)
+  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)
   reticle status [--port N]
-  reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port — one command)
+  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
   reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
   reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
   reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
   reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)
   reticle watch [url]                                  (on save, report which saved flows must re-verify)
-  reticle drive <url> [--headless]                     (foreground mode — for debugging)
-  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy — auto-starts daemon if needed)
+  reticle drive <url> [--headless]                     (foreground mode, for debugging)
+  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)
   reticle update                                       (install the latest server version and restart)
   reticle rollback                                     (restore the previous server version and restart)
   reticle license                                      (show enterprise license status: active | eval | missing)
-  reticle telemetry [status|enable|disable]            (anonymous usage metrics — status shows what's sent + the policy)
-  reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't — prints exactly what it sends)
+  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)
+  reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't; prints exactly what it sends)
   reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "message"
                                                        (agents: file from anywhere, including a setup that never finished)
   reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
                                                        (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
 
-Cloud (link this project to Reticle Cloud — runs/flows recorded on the dashboard):
+Cloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):
   reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)
   reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)
   reticle whoami                                        (who am I signed in as, and is this repo attached?)
@@ -44,10 +55,12 @@ Cloud (link this project to Reticle Cloud — runs/flows recorded on the dashboa
   reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)
 
 'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay
-and the spec runner — batch work). --headed opts any of them in, --headless hides drive, CI hides it.`;
+and the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.`;
 const INIT_COMMAND = 'init';
 const SERVE_COMMAND = 'serve';
 const STOP_COMMAND = 'stop';
+const KILL_COMMAND = 'kill';
+const RESTART_COMMAND = 'restart';
 const STATUS_COMMAND = 'status';
 const OPEN_COMMAND = 'open';
 const DRIVE_COMMAND = 'drive';
@@ -90,6 +103,8 @@ const KNOWN_COMMANDS = new Set([
     INIT_COMMAND,
     SERVE_COMMAND,
     STOP_COMMAND,
+    KILL_COMMAND,
+    RESTART_COMMAND,
     STATUS_COMMAND,
     OPEN_COMMAND,
     DRIVE_COMMAND,
@@ -463,6 +478,14 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             const quiet = rest.includes(QUIET_FLAG);
             return { kind: 'stop', port, quiet };
         }
+        case KILL_COMMAND: {
+            const port = parsePortFlag(rest, defaultPort);
+            return { kind: 'kill', port, force: rest.includes(FORCE_FLAG) };
+        }
+        case RESTART_COMMAND: {
+            const port = parsePortFlag(rest, defaultPort);
+            return { kind: 'restart', port, force: rest.includes(FORCE_FLAG) };
+        }
         case STATUS_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
             return { kind: 'status', port };

package/dist/cli/cli-port.d.ts

@@ -44,3 +44,11 @@ export declare function readJournalEnabled(cwd: string, env: string | undefined)
  * Pass `portFlag` when the user explicitly supplied --port; pass `undefined` to fall through.
  */
 export declare function resolvePort(portFlag: number | undefined, envPort: number | undefined, projectPort: number | undefined, defaultPort: number): number;
+/**
+ * Detect a port mismatch between the daemon and the project's SDK configuration.
+ *
+ * Returns a diagnostic string when the daemon port differs from what `.reticle.json` declares.
+ * The SDK reads `.reticle.json` at build/connect time, so a mismatch means the app will dial a
+ * port nothing is listening on — the silent no-connect that #261 documents.
+ */
+export declare function diagnosePortMismatch(daemonPort: number, projectPort: number | undefined): string | undefined;

package/dist/cli/cli-port.js

@@ -20,7 +20,26 @@ import { readFileSync } from 'node:fs';
  * the confusion got manufactured in the first place.
  */
 export const DEV_SERVER_PORTS = new Set([
-    3000, 3001, 4200, 4321, 5000, 5173, 5174, 8000, 8080, 8100, 9000,
+    3000,
+    3001,
+    4200,
+    4321,
+    5000,
+    5173,
+    5174,
+    8000,
+    8080,
+    8100,
+    9000,
+    // Added after the scan reported "nothing is listening" at people whose app was plainly running.
+    // A narrow list is not just unhelpful, it is CONFIDENTLY wrong — the message states absence as a
+    // fact — so the defaults of the frameworks agents actually meet belong in it.
+    1420, // Tauri
+    3100, // Next, second instance
+    4173, // vite preview
+    5175, // Vite, third instance
+    7860, // Gradio
+    8501, // Streamlit
 ]);
 export function isLikelyDevServerPort(port) {
     return DEV_SERVER_PORTS.has(port);
@@ -101,3 +120,19 @@ export function readJournalEnabled(cwd, env) {
 export function resolvePort(portFlag, envPort, projectPort, defaultPort) {
     return portFlag ?? envPort ?? projectPort ?? defaultPort;
 }
+/**
+ * Detect a port mismatch between the daemon and the project's SDK configuration.
+ *
+ * Returns a diagnostic string when the daemon port differs from what `.reticle.json` declares.
+ * The SDK reads `.reticle.json` at build/connect time, so a mismatch means the app will dial a
+ * port nothing is listening on — the silent no-connect that #261 documents.
+ */
+export function diagnosePortMismatch(daemonPort, projectPort) {
+    if (projectPort === undefined)
+        return undefined;
+    if (projectPort === daemonPort)
+        return undefined;
+    return (`.reticle.json says "port": ${String(projectPort)} but this daemon is on :${String(daemonPort)}` +
+        ` — the SDK will dial :${String(projectPort)} and never connect. ` +
+        `Either start the daemon with --port ${String(projectPort)}, or update .reticle.json to match.`);
+}

package/dist/cli/cli-verify.js

@@ -30,10 +30,10 @@ const DEFAULT_SESSION_TIMEOUT_MS = 15_000;
 const SESSION_POLL_MS = 250;
 const DEFAULT_PROJECT_NAME = 'app';
 const VERIFY_AGENT_ID = 'reticle-cli';
-const MSG_NO_SESSION = 'No app connected — Reticle drove the URL but no @reticlehq/browser session dialed back.\n' +
+const MSG_NO_SESSION = 'No app connected: Reticle drove the URL but no @reticlehq/browser session dialed back.\n' +
     '  Make sure the SDK is in the build and reticle.connect() runs on the preview page' +
     ' (for a non-localhost preview: allowNonLocalhost + a pairing token).';
-const MSG_NO_FLOWS = 'No saved flows to verify (.reticle/flows is empty) — refusing to report a pass for verifying nothing.\n' +
+const MSG_NO_FLOWS = 'No saved flows to verify (.reticle/flows is empty), so refusing to report a pass for verifying nothing.\n' +
     '  Flows are recorded interactively by an agent (reticle_record{action:"start"} → act → reticle_flow_save via the\n' +
     '  MCP tools), then committed to .reticle/flows/. In CI, check those files in and re-run `reticle verify`.';
 const MSG_VERIFY_PREFIX = 'verify failed: ';

package/dist/cli/doctor-daemon-line.js

@@ -14,7 +14,16 @@
  * at the call site.
  */
 import { describeSkew } from '../version/version-skew.js';
-const FIX = 'Restart it so both ends are the same build: `reticle stop`, then let your agent reconnect.';
+/**
+ * `reticle stop`, not `reticle kill`.
+ *
+ * The first version of this said `reticle kill`, which this CLI does not dispatch — it is a proposal
+ * (#114), described as a gap in docs/system-map.md, and I read it there as if it shipped. A remedy
+ * naming a command that errors is a second dead end handed to someone already stuck, on the one
+ * command they run when they are confused.
+ */
+const FIX = 'Restart it so both ends are the same build: `reticle stop`, then let your agent reconnect (it ' +
+    'spawns a fresh daemon on the next tool call).';
 /**
  * Build the daemon line for a port that answered `/status`.
  *

package/dist/cli/doctor-sessions-line.d.ts

@@ -0,0 +1,12 @@
+/** What this reads off `/status`. Everything is optional — an older daemon may send none of it. */
+export interface SessionFacts {
+    sessionCount?: unknown;
+    why?: unknown;
+}
+export interface SessionsLine {
+    /** The `sessions` row itself. */
+    text: string;
+    /** The diagnosis to print underneath, when there is one and it is not contradicted by a session. */
+    why?: string;
+}
+export declare function sessionsLine(facts: SessionFacts): SessionsLine;

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

@@ -0,0 +1,66 @@
+import { SELF_RECOVERING_MARKER } from '../session/no-session-diagnosis.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: '  sessions     ? this daemon did not report connected pages (older build)' };
+    }
+    if (count > 0) {
+        const plural = 1 === count ? 'page' : 'pages';
+        return { text: `  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: '  sessions     ✗ no page has connected to this daemon',
+        ...(why === undefined ? {} : { why }),
+    };
+}

package/dist/cli/port-holder.d.ts

@@ -17,6 +17,16 @@ export interface PortHolder {
     pid: number;
     command: string;
 }
+/**
+ * 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 declare function captureLookup(command: string, args: readonly string[]): string | null;
 /**
  * The FIRST listener in `lsof -nP -iTCP:<port> -sTCP:LISTEN -F pc` output, or null.
  *

package/dist/cli/port-holder.js

@@ -13,6 +13,27 @@
  * 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';
@@ -59,8 +80,11 @@ export function describeForeignHolder(port, holder,
  * stranger, and the fix that works (`reticle stop`, it respawns on the next call) is never named.
  */
 ourPid) {
-    const tail = 'a daemon cannot bind it. Stop that process, or run Reticle on a different port ' +
-        '(`--port`), then retry.';
+    // 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