@reticlehq/server 2.5.0 → 2.7.0

package/dist/cli/chromium-hint.js

@@ -0,0 +1,75 @@
+/**
+ * A Chromium hint you can satisfy by following it.
+ *
+ * `npx playwright install chromium` looks obviously right and is quietly wrong. `npx` resolves the
+ * LATEST playwright, which pins a different browser revision than the playwright the daemon actually
+ * bundles — so the command downloads ~90 MiB of a build the daemon will not use, and the check still
+ * says missing afterwards. Reported from the field by an agent whose machine already had five
+ * chromium builds, none of them the wanted one, with no way to learn which one was wanted.
+ *
+ * Two things fix it, and they are the same two things any unsatisfiable check needs: pin the command
+ * to the version doing the asking, and say what was probed. A check that reports only its verdict
+ * cannot be argued with — the reader has no way to tell a missing browser from a bad lookup.
+ */
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+/**
+ * The install command, pinned when we know what to pin to.
+ *
+ * Unpinned is still the right fallback: a wrong-revision download is a bad outcome, but no command
+ * at all is a worse one.
+ */
+export function chromiumInstallCommand(playwrightVersion) {
+    const pin = playwrightVersion === undefined ? 'playwright' : `playwright@${playwrightVersion}`;
+    return `npx ${pin} install chromium`;
+}
+/**
+ * Ask the playwright THIS process would use, not the one `npx` would fetch.
+ *
+ * Both halves matter: `executablePath()` resolves the revision the daemon will actually launch, and
+ * the bundled package version is what makes the suggested command install that same revision.
+ */
+export async function probeChromium() {
+    try {
+        const { chromium } = await import('playwright');
+        const executablePath = chromium.executablePath();
+        return {
+            executablePath,
+            exists: existsSync(executablePath),
+            playwrightVersion: bundledPlaywrightVersion(),
+        };
+    }
+    catch {
+        // Playwright itself is absent — a different problem from a missing browser, and the hint says so.
+        return { exists: false };
+    }
+}
+/** The bundled playwright's version, or undefined if it cannot be read (the hint then goes unpinned). */
+export function bundledPlaywrightVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require('playwright/package.json');
+        if ('object' === typeof pkg && null !== pkg && 'version' in pkg) {
+            const { version } = pkg;
+            if ('string' === typeof version)
+                return version;
+        }
+    }
+    catch {
+        /* an unreadable package.json is not worth failing a diagnostic over */
+    }
+    return undefined;
+}
+/** The doctor line for the Chromium check — verdict, what was probed, and how to satisfy it. */
+export function chromiumHint(probe) {
+    if (probe.exists)
+        return '✓ installed';
+    const command = chromiumInstallCommand(probe.playwrightVersion);
+    // Naming the path is what turns "missing" from a verdict into evidence: a reader with browsers on
+    // disk can see immediately whether this is a missing install or a lookup pointed somewhere else
+    // (PLAYWRIGHT_BROWSERS_PATH, a different browsers root, a revision bump).
+    const probed = probe.executablePath === undefined
+        ? 'the playwright package is not installed'
+        : `looked for ${probe.executablePath}`;
+    return `✗ missing — ${probed}; run: ${command}`;
+}

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

@@ -1,6 +1 @@
-/**
- * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
- * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
- * reminds the user which port the app must dial. Human-readable to stdout (not the JSON log).
- */
 export declare function handleDoctor(port: number): Promise<void>;

package/dist/cli/cli-doctor.js

@@ -1,32 +1,92 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ReticleEnv } from '@reticlehq/core';
-import { readPid, isAlive, reticleStateHome } from '../daemon/daemon.js';
+import { readPid, reticleStateHome } from '../daemon/daemon.js';
+import { PortPresence, probePresence } from '../daemon/port-presence.js';
+import { probeDaemon } from '../mcp/mcp-proxy.js';
+import { fetchStatus } from './cli-launch.js';
+import { daemonLine } from './doctor-daemon-line.js';
+import { describeForeignHolder, findPortHolder } from './port-holder.js';
+import { chromiumHint, probeChromium } from './chromium-hint.js';
+import { spawnSync } from 'node:child_process';
+import { SERVER_VERSION } from '../version/server-version.js';
+import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { diagnoseDesktop, isDesktopProject } from '../init/desktop-doctor.js';
 /**
  * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
  * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
  * reminds the user which port the app must dial. Human-readable to stdout (not the JSON log).
  */
+/**
+ * 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 command people run when things are already broken; it must
+ * never be the reason `doctor` fails. `describeForeignHolder` handles the null by saying it could
+ * not identify the holder and naming our recorded pid, rather than asserting the holder is not ours
+ * — a claim it has no evidence for, and one that was wrong for every Windows user.
+ */
+function runCapture(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;
+    }
+}
+/** Bound on the holder lookup. A hung `lsof` must not hang the command that diagnoses hangs. */
+const LOOKUP_TIMEOUT_MS = 2_000;
+/** Narrow the `/status` payload to the two fields the daemon line reads. */
+function asIdentity(payload) {
+    if (typeof payload !== 'object' || null === payload)
+        return {};
+    const record = payload;
+    const pick = (key) => {
+        const value = record[key];
+        return 'string' === typeof value && value.length > 0 ? value : undefined;
+    };
+    // Keys are OMITTED rather than set to undefined: `exactOptionalPropertyTypes` is on, and the
+    // distinction is the point — "this daemon did not say" is not the same as "this daemon said none".
+    const version = pick('version');
+    const contract = pick('contract');
+    return {
+        ...(version === undefined ? {} : { version }),
+        ...(contract === undefined ? {} : { contract }),
+    };
+}
 export async function handleDoctor(port) {
     const line = (s) => {
         process.stdout.write(`${s}\n`);
     };
     line('reticle doctor');
     line(`  node         ${process.version}`);
-    try {
-        const { chromium } = await import('playwright');
-        const path = chromium.executablePath();
-        line(existsSync(path)
-            ? '  chromium     ✓ installed'
-            : '  chromium     ✗ missing — run: npx playwright install chromium');
-    }
-    catch {
-        line('  chromium     ✗ missing — run: npx playwright install chromium');
-    }
+    line(`  chromium     ${chromiumHint(await probeChromium())}`);
+    // Ask the PORT, not just the pid file. "not running on :4400" has been printed about a port that
+    // was demonstrably occupied, which sends the reader to start a daemon that cannot bind. The three
+    // states are genuinely different problems with different fixes, so doctor names which one it is.
     const pid = readPid(port);
-    if (pid !== null && isAlive(pid)) {
-        line(`  daemon       ✓ running on :${port} (pid ${pid})`);
+    const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+    if (presence === PortPresence.DAEMON) {
+        // Name WHICH daemon. The /status payload already carries version + contract, and doctor was
+        // throwing both away — while skew is invisible everywhere else, reaching the agent as a bare
+        // -32000 naming no version. This is the command a human runs at exactly that moment.
+        const status = asIdentity(await fetchStatus(port));
+        const built = daemonLine(port, pid, status, {
+            version: SERVER_VERSION,
+            contract: CONTRACT_FINGERPRINT,
+        });
+        line(built.text);
+        if (built.skew !== undefined)
+            line(`  version      ✗ ${built.skew}`);
+    }
+    else if (presence === PortPresence.FOREIGN) {
+        // Name the holder when we can. `doctor` exists for exactly this moment, and "another process"
+        // leaves the reader to find a shell command themselves — the obvious one being the `lsof -ti`
+        // pipeline that also kills the agent's own MCP proxy.
+        // `pid` is what our pid file recorded for this port. When it matches the process actually
+        // holding it, this is our OWN daemon wedged, not a stranger — and the fix is different.
+        line(`  daemon       ✗ ${describeForeignHolder(port, findPortHolder(port, runCapture), pid)}`);
     }
     else {
         line(`  daemon       ✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`);

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

@@ -19,6 +19,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.

package/dist/cli/cli-launch.js

@@ -15,6 +15,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 +37,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) {

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

@@ -0,0 +1,31 @@
+/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
+export declare const RATING_FLAG = "--rating";
+export declare const BUG_FLAG = "--bug";
+/**
+ * The AGENT half of the same channel, for the phase where `reticle_feedback` does not exist yet.
+ *
+ * An agent that is still installing Reticle — or that just watched `init` fail, or a daemon refuse to
+ * start — has no MCP tools to file with, and that is exactly the report we most need: the failures
+ * that happen before the tool surface is reachable are invisible to every other path we have. This
+ * gives that agent the same shape the tool takes, over a command that needs nothing running.
+ */
+export declare const KIND_FLAG = "--kind";
+export declare const AGENT_FLAG = "--agent";
+/** Accepted `--kind` values, from core's enum — never a second hand-written list to drift from it. */
+export declare const FEEDBACK_KINDS: readonly string[];
+/** What `parseFeedbackArgs` yields: the parsed command, or a usage error to print. */
+export type ParsedFeedback = {
+    kind: 'feedback';
+    text: string;
+    rating?: number;
+    /** The FeedbackKind name from `--kind`; absent means the legacy bug/experience split. */
+    feedbackKind?: string;
+    bug: boolean;
+    /** `--agent`: file as the agent, so agent reports never dilute the human rating signal. */
+    agent: boolean;
+} | {
+    kind: 'error';
+    message: string;
+};
+/** Parse everything after `reticle feedback`. */
+export declare function parseFeedbackArgs(rest: string[]): ParsedFeedback;

package/dist/cli/cli-parse-feedback.js

@@ -0,0 +1,56 @@
+/**
+ * The `reticle feedback` grammar — flags, kind validation, and the message-vs-flag split.
+ *
+ * Split out of `cli-parse.ts` when that file crossed the line cap. Cohesive on its own terms: this
+ * is the one command whose arguments are free text, so it is the only place in the grammar where
+ * "everything that is not a flag" is a rule with edge cases rather than a one-liner.
+ */
+import { FeedbackKind } from '@reticlehq/core';
+/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
+export const RATING_FLAG = '--rating';
+export const BUG_FLAG = '--bug';
+/**
+ * The AGENT half of the same channel, for the phase where `reticle_feedback` does not exist yet.
+ *
+ * An agent that is still installing Reticle — or that just watched `init` fail, or a daemon refuse to
+ * start — has no MCP tools to file with, and that is exactly the report we most need: the failures
+ * that happen before the tool surface is reachable are invisible to every other path we have. This
+ * gives that agent the same shape the tool takes, over a command that needs nothing running.
+ */
+export const KIND_FLAG = '--kind';
+export const AGENT_FLAG = '--agent';
+/** Accepted `--kind` values, from core's enum — never a second hand-written list to drift from it. */
+export const FEEDBACK_KINDS = Object.values(FeedbackKind);
+/** Parse everything after `reticle feedback`. */
+export function parseFeedbackArgs(rest) {
+    const ratingAt = rest.indexOf(RATING_FLAG);
+    const rating = -1 === ratingAt ? undefined : Number(rest[ratingAt + 1]);
+    if (rating !== undefined && (!Number.isInteger(rating) || rating < 1 || rating > 5)) {
+        return { kind: 'error', message: `${RATING_FLAG} takes a whole number from 1 to 5` };
+    }
+    const kindAt = rest.indexOf(KIND_FLAG);
+    const feedbackKind = -1 === kindAt ? undefined : rest[kindAt + 1];
+    if (feedbackKind !== undefined && !FEEDBACK_KINDS.includes(feedbackKind)) {
+        return { kind: 'error', message: `${KIND_FLAG} takes one of: ${FEEDBACK_KINDS.join(', ')}` };
+    }
+    // Everything that is not a flag or a flag's VALUE is the message. Quoting is the user's job for
+    // shell reasons, but joining the remainder means an unquoted sentence still works. Both value
+    // positions have to be consumed: without that, `--kind bug "..."` filed a report whose text began
+    // with the word "bug".
+    const consumed = new Set([
+        ...(-1 === ratingAt ? [] : [ratingAt, ratingAt + 1]),
+        ...(-1 === kindAt ? [] : [kindAt, kindAt + 1]),
+    ]);
+    const text = rest
+        .filter((arg, i) => !consumed.has(i) && !arg.startsWith('--'))
+        .join(' ')
+        .trim();
+    return {
+        kind: 'feedback',
+        text,
+        ...(rating !== undefined ? { rating } : {}),
+        ...(feedbackKind !== undefined ? { feedbackKind } : {}),
+        bug: rest.includes(BUG_FLAG),
+        agent: rest.includes(AGENT_FLAG),
+    };
+}

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

@@ -4,10 +4,9 @@
  * file-size cap and keep the parser pure + unit-testable. Re-exported from cli.ts so existing
  * imports are unchanged.
  */
-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 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.";
-/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
-export declare const RATING_FLAG = "--rating";
-export declare const BUG_FLAG = "--bug";
+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 `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";
@@ -61,12 +60,9 @@ export type CliResult = {
 } | {
     kind: 'telemetry';
     action: TelemetryAction;
-} | {
+} | Extract<ParsedFeedback, {
     kind: 'feedback';
-    text: string;
-    rating?: number;
-    bug: boolean;
-} | {
+}> | {
     kind: 'identify';
     context?: string;
     company?: string;

package/dist/cli/cli-parse.js

@@ -4,6 +4,9 @@
  * file-size cap and keep the parser pure + unit-testable. Re-exported from cli.ts so existing
  * imports are unchanged.
  */
+import { parseFeedbackArgs } from './cli-parse-feedback.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:
   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
@@ -26,6 +29,8 @@ export const CLI_USAGE = `usage:
   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 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)
 
@@ -64,9 +69,6 @@ const COMPANY_FLAG = '--company';
 const EMAIL_FLAG = '--email';
 const CONTEXT_FLAG = '--context';
 const FORGET_FLAG = '--forget';
-/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
-export const RATING_FLAG = '--rating';
-export const BUG_FLAG = '--bug';
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export const TelemetryAction = {
     STATUS: 'status',
@@ -496,26 +498,8 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 forget: rest.includes(FORGET_FLAG),
             };
         }
-        case FEEDBACK_COMMAND: {
-            const ratingAt = rest.indexOf(RATING_FLAG);
-            const rating = -1 === ratingAt ? undefined : Number(rest[ratingAt + 1]);
-            if (rating !== undefined && (!Number.isInteger(rating) || rating < 1 || rating > 5)) {
-                return { kind: 'error', message: `${RATING_FLAG} takes a whole number from 1 to 5` };
-            }
-            // Everything that is not a flag or the rating's value is the message. Quoting is the user's
-            // job for shell reasons, but joining the remainder means an unquoted sentence still works.
-            const consumed = new Set(-1 === ratingAt ? [] : [ratingAt, ratingAt + 1]);
-            const text = rest
-                .filter((arg, i) => !consumed.has(i) && !arg.startsWith('--'))
-                .join(' ')
-                .trim();
-            return {
-                kind: 'feedback',
-                text,
-                ...(rating !== undefined ? { rating } : {}),
-                bug: rest.includes(BUG_FLAG),
-            };
-        }
+        case FEEDBACK_COMMAND:
+            return parseFeedbackArgs(rest);
         case OPEN_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
             // The first non-flag arg is the url (optional — omitting reuses a connected tab).

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);

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

@@ -0,0 +1,37 @@
+/**
+ * What `doctor` says about the daemon it found — pure, so it can be tested without a socket.
+ *
+ * Doctor already stopped lying about the PORT: `probePresence` separates "a daemon is here" from "a
+ * stranger holds it" from "nothing is listening", which was the load-bearing half of the report. It
+ * still did not say WHICH daemon, though the `/status` payload it already fetches carries `version`
+ * and `contract` and it discarded both.
+ *
+ * That is the gap worth closing, because skew is invisible everywhere else: a CLI and a daemon on
+ * different contracts connect anyway and then disagree about behaviour, which reaches the agent as a
+ * bare `-32000` naming no version at all. Doctor is the command a human runs at exactly that moment.
+ *
+ * Same split as `classifyPort`/`probePresence`: the rule lives here and is tested; the fetching stays
+ * at the call site.
+ */
+/** The fields of `/status` this line cares about. Both optional — an old daemon reports neither. */
+export interface DaemonIdentity {
+    version?: string;
+    contract?: string;
+}
+export interface DaemonLine {
+    /** The `daemon ✓ …` line itself. */
+    text: string;
+    /** A skew sentence to print underneath, when this CLI and that daemon disagree. */
+    skew?: string;
+}
+/**
+ * Build the daemon line for a port that answered `/status`.
+ *
+ * `pid` comes from the pid file and is genuinely optional — a daemon started by another user, or one
+ * whose pid file was cleaned up, still answers. Printing `(pid null)` would be worse than printing
+ * nothing, which is the same class of mistake as the port lie this command already fixed.
+ */
+export declare function daemonLine(port: number, pid: number | null, peer: DaemonIdentity, self: {
+    version: string;
+    contract: string;
+}): DaemonLine;

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

@@ -0,0 +1,44 @@
+/**
+ * What `doctor` says about the daemon it found — pure, so it can be tested without a socket.
+ *
+ * Doctor already stopped lying about the PORT: `probePresence` separates "a daemon is here" from "a
+ * stranger holds it" from "nothing is listening", which was the load-bearing half of the report. It
+ * still did not say WHICH daemon, though the `/status` payload it already fetches carries `version`
+ * and `contract` and it discarded both.
+ *
+ * That is the gap worth closing, because skew is invisible everywhere else: a CLI and a daemon on
+ * different contracts connect anyway and then disagree about behaviour, which reaches the agent as a
+ * bare `-32000` naming no version at all. Doctor is the command a human runs at exactly that moment.
+ *
+ * Same split as `classifyPort`/`probePresence`: the rule lives here and is tested; the fetching stays
+ * at the call site.
+ */
+import { describeSkew } from '../version/version-skew.js';
+/**
+ * `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`.
+ *
+ * `pid` comes from the pid file and is genuinely optional — a daemon started by another user, or one
+ * whose pid file was cleaned up, still answers. Printing `(pid null)` would be worse than printing
+ * nothing, which is the same class of mistake as the port lie this command already fixed.
+ */
+export function daemonLine(port, pid, peer, self) {
+    const parts = [];
+    if (null !== pid)
+        parts.push(`pid ${String(pid)}`);
+    if (peer.version !== undefined)
+        parts.push(`v${peer.version}`);
+    const detail = 0 === parts.length ? '' : ` (${parts.join(', ')})`;
+    const skew = describeSkew({ what: 'the daemon on this port', version: peer.version, contract: peer.contract, fix: FIX }, self);
+    const line = { text: `  daemon       ✓ running on :${String(port)}${detail}` };
+    return skew === undefined ? line : { ...line, skew };
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Who is holding the bridge port.
+ *
+ * `doctor` is what a user runs when the agent cannot reach the bridge, and the commonest real cause
+ * is that something else is on 4400. It already stopped saying "nothing is listening" for that case,
+ * but it did not say WHICH process — so the reader's next move was a shell command they had to know.
+ *
+ * Naming the holder is also the safe answer to a trap this project has hit for real: the obvious
+ * lookup, `lsof -ti tcp:4400 | xargs kill -9`, ALSO kills the agent's own `reticle mcp` proxy,
+ * because that proxy holds a client connection to the same port and `-ti` does not filter to
+ * listeners. Every invocation here is `-sTCP:LISTEN`, and the message never suggests `-ti`.
+ *
+ * The parser is pure and the lookup takes an injected exec, so the rule is tested on every platform
+ * while the shelling out stays at the call site.
+ */
+export interface PortHolder {
+    pid: number;
+    command: string;
+}
+/**
+ * The FIRST listener in `lsof -nP -iTCP:<port> -sTCP:LISTEN -F pc` output, or null.
+ *
+ * First, not "the only one": a dual-stack listener (IPv4 + IPv6) is reported twice, and on a port
+ * conflict the answer the reader needs is "something is there, here is what" rather than an
+ * exhaustive list. A second `p` record ends the first.
+ *
+ * Null on anything incomplete. Half an answer — a pid with no command — prints worse than the
+ * un-named message it would replace, which is the same mistake as the port lie this command fixed.
+ */
+export declare function parsePortHolder(stdout: string): PortHolder | null;
+/** What `doctor` prints for a port held by something that is not a Reticle daemon. */
+export declare function describeForeignHolder(port: number, holder: PortHolder | null, 
+/**
+ * The pid we recorded for this port, from the daemon pid file.
+ *
+ * When it matches the process actually holding the port, the port is held by OUR daemon — one
+ * that accepts TCP and never answers `/status`, i.e. wedged. That classifies as FOREIGN, which is
+ * right for "can anything bind this?" and wrong to say out loud: the reader goes hunting a
+ * stranger, and the fix that works (`reticle stop`, it respawns on the next call) is never named.
+ */
+ourPid?: number | null): string;
+/** The lookup itself. `exec` is injected so the shelling out never runs in a unit test. */
+export declare function findPortHolder(port: number, exec: (command: string, args: readonly string[]) => string | null): PortHolder | null;