@reticlehq/server 2.5.0 → 2.6.0

package/SKILL.md

@@ -1,5 +1,15 @@
 # Reticle
 
+> ## Before anything else: feedback is part of the job
+>
+> Reticle is built FOR agents, so you are its user and the only one who can report what it costs you. That applies **from this line onwards** — including everything that happens during setup, which is where Reticle is most likely to break and least likely to hear about it.
+>
+> **The moment something is wrong, missing, awkward, or slower than it should be, file it — one call, then carry on with the task.** A step in this document that did not match reality, an install that needed a manual fix, a tool that returned nonsense, something you wished existed, something that works but takes five calls where it should take one. Nothing is too minor; the minor things are exactly what never gets reported and therefore never gets fixed.
+>
+> - Tools available: `reticle_feedback { kind, text, need?, impact?, currentApproach?, model?, trace? }` where `kind` is `bug` | `gap` | `ambiguity` | `feature_request` | `improvement`.
+> - Not set up yet, or the daemon will not start (which is most of setup): `reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"` — it needs nothing running.
+> - Report defects in **Reticle**. A bug you find in the app under test is Reticle working; that one goes to the user. Never put app source, secrets, or user data in a report.
+
 Start by detecting which mode to run:
 
 ```bash
@@ -442,7 +452,7 @@ reticle_network({ sessionId, limit: 10 })
 reticle_console({ sessionId, limit: 20 })
 ```
 
-> **There is one tool surface, and nothing to pick.** The verify loop is advertised directly (navigate / snapshot / query / act / act_and_wait / observe / network / console / wait_for / assert / state / inspect / sessions / session / feedback). Everything else the skill names — `reticle_capabilities`, `reticle_act_sequence`, the flow and record tools — is one hop away through two meta-tools: `reticle_run({ tool, args })` invokes any tool by name, `reticle_tools` lists them (pass `names:[…]` for full params). `reticle_run` takes `sessionId` at the top level and forwards it, so you do not have to nest it in `args`. Advertised counts, checked by a gate (`surface-sizes.test.ts`): `default` 17, `all` 48.
+> **There is one tool surface, and nothing to pick.** The verify loop is advertised directly (navigate / snapshot / query / act / act_sequence / act_and_wait / observe / network / console / wait_for / assert / state / inspect / sessions / session / feedback). Everything else the skill names — `reticle_capabilities`, the flow and record tools — is one hop away through two meta-tools: `reticle_run({ tool, args })` invokes any tool by name, `reticle_tools` lists them (pass `names:[…]` for full params). `reticle_run` takes `sessionId` at the top level and forwards it, so you do not have to nest it in `args`. Advertised counts, checked by a gate (`surface-sizes.test.ts`): `default` 18, `all` 48.
 >
 > `all` is a verification switch, not a mode to drive agents in: `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises every tool **with its output schema**, at several times the per-turn cost. It is read by the DAEMON at startup, never by your client — exporting it while a daemon is already running changes nothing, so run `npx @reticlehq/server stop` first.
 
@@ -476,22 +486,28 @@ Then pick a mode:
 
 ### Targeted
 
+> **Only two tools produce a verdict: `reticle_act_and_wait` and `reticle_assert`.** Everything else — `act`, `snapshot`, `query`, `navigate`, `observe`, `network`, `console` — moves or reads the app and proves nothing. A drive that ends without one of those two is a drive with no result, however many tools it used. Measured across two days of real sessions: `reticle_act` was called 3.6× more often than `reticle_act_and_wait`, and **20 of the 28 agents that drove an app produced no verdict at all.** Reach for `act_and_wait` first; drop to bare `act` only for a step whose consequence you are deliberately asserting later.
+
 1. Navigate if needed: `reticle_navigate({ sessionId, url })`
 2. Snapshot to confirm correct state
-3. Act on controls using testids:
-   ```
-   reticle_act({ sessionId, ref, action: "click" })
+3. **Act and declare the consequence in the same hop** — this is the default:
    ```
-4. Assert — always use `since` from the act result:
-   ```
-   reticle_assert({ sessionId, since, timeout_ms: 5000, predicate: { kind: "allOf", predicates: [
+   reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "allOf", predicates: [
      { kind: "net",     method: "POST", urlContains: "/api/...", status: 200 },
      { kind: "element", query: { role: "...", name: "..." }, state: "visible" },
-     { kind: "signal",  name: "..." },
      { kind: "console", level: "error", absent: true }
    ]}})
    ```
-5. Record: ✅ pass / ❌ fail / ⚠️ partial
+   One call, one verdict, and the oracle is written _before_ the result exists — see **Declare before you act** below.
+4. Only when an action's consequence lands somewhere you cannot name up front, act bare and assert after — always with `since` from the act result, or the assertion silently reads the wrong window:
+   ```
+   reticle_act({ sessionId, ref, action: "click" })
+   reticle_assert({ sessionId, since, timeout_ms: 5000, predicate: { kind: "allOf", predicates: [
+     { kind: "net",    method: "POST", urlContains: "/api/...", status: 200 },
+     { kind: "signal", name: "..." }
+   ]}})
+   ```
+5. Record: ✅ pass / ❌ fail / ⚠️ partial. A verdict of `verified: "unknown"` is **not** a pass — it means Reticle drove the app and could not tell what happened (`unclean_capture`, `outcome_unread`, `unsettled`). Report it as unknown and say why; do not round it up.
 
 ### Plan then batch — do NOT ping-pong act-by-act
 
@@ -614,7 +630,8 @@ If something failed, call `reticle_inspect({ sessionId, ref })` on the failing e
 - Batch net + element + signal + console into one `allOf` — don't call `reticle_assert` four times.
 - Never assert on pixels — use predicates, not `reticle_screenshot` (screenshots are for genuinely visual checks only).
 - If the session disconnects mid-test (navigation creates a new session ID) — call `reticle_sessions()` again and continue.
-- **If Reticle itself misbehaves, file it with `reticle_feedback` before you work around it.** Three things are worth reporting: a tool that returned something wrong or impossible (`kind: "bug"`), something you needed to observe and Reticle simply could not see (`kind: "gap"`), and a verification that ran but left you unable to tell pass from fail (`kind: "ambiguity"`). Write `text` as a root-cause analysis — what you called, what you expected, what you got — and put the call trail in `trace`. Then continue the task; do not retry the failing call just to re-report it. Report defects in **Reticle**, not bugs you found in the app under test: finding those is Reticle working, and they belong in your report to the user.
+- **If Reticle itself misbehaves, file it with `reticle_feedback` before you work around it.** A tool that returned something wrong or impossible (`kind: "bug"`), something you needed to observe and Reticle simply could not see (`kind: "gap"`), a verification that ran but left you unable to tell pass from fail (`kind: "ambiguity"`). Write `text` as a root-cause analysis — what you called, what you expected, what you got — and put the call trail in `trace`. Then continue the task; do not retry the failing call just to re-report it. Report defects in **Reticle**, not bugs you found in the app under test: finding those is Reticle working, and they belong in your report to the user.
+- **File what you WISHED for too, in the same breath.** `kind: "feature_request"` for something that does not exist, `kind: "improvement"` for something that works but is awkward or costs too many calls. Put the goal in `need` (not your guess at the fix), what gets better in `impact`, and how you are working around it today in `currentApproach`. This is the half nobody files, and it is the half that decides the roadmap — you are the user Reticle is built for, and the thought is gone when your context is. Set `model` to the model you are running.
 
 ---
 

package/dist/bridge/bridge.d.ts

@@ -4,6 +4,18 @@ import { Session, SessionManager } from '../session/session.js';
 type ReplayRequestHandler = (sessionId: string, flowName: string) => void;
 /** Called once a browser session connects, so the daemon can push it the replayable-flow list. */
 type SessionReadyHandler = (session: Session) => void;
+/**
+ * The close reasons worth telling an AGENT about, not just the SDK.
+ *
+ * The SDK prints these and stops retrying. The agent then calls a tool and is told "no browser
+ * session connected" — which is indistinguishable from an app nobody started. An outdated SDK and a
+ * stale pairing token were both invisible for that reason; these two carry their own remedy, so
+ * surfacing them is strictly better than the generic answer.
+ */
+export declare const WS_CLOSE_REASON: {
+    readonly PROTOCOL_MISMATCH: "protocol version mismatch — upgrade @reticlehq/browser";
+    readonly AUTH_FAILED: "authentication failed — reload the page to pick up the current pairing token";
+};
 interface BridgeOptions {
     port: number;
     host?: string;

package/dist/bridge/bridge.js

@@ -5,6 +5,7 @@ import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOO
 import { Session, SessionManager } from '../session/session.js';
 import { tokensMatch } from './token-auth.js';
 import { log } from '../log.js';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { describeSkew, sdkFix, SkewPair } from '../version/version-skew.js';
 import { noteVersionSkew } from '../version/version-nudge.js';
 import { SERVER_VERSION } from '../version/server-version.js';
@@ -26,15 +27,31 @@ function refreshIdentity(session, hello) {
     session.adapters = hello.adapters;
     session.hasCapabilities = hello.hasCapabilities ?? false;
 }
+/**
+ * The close reasons worth telling an AGENT about, not just the SDK.
+ *
+ * The SDK prints these and stops retrying. The agent then calls a tool and is told "no browser
+ * session connected" — which is indistinguishable from an app nobody started. An outdated SDK and a
+ * stale pairing token were both invisible for that reason; these two carry their own remedy, so
+ * surfacing them is strictly better than the generic answer.
+ */
+export const WS_CLOSE_REASON = {
+    PROTOCOL_MISMATCH: 'protocol version mismatch — upgrade @reticlehq/browser',
+    AUTH_FAILED: 'authentication failed — reload the page to pick up the current pairing token',
+};
 /** WS close codes + reasons the bridge sends to the SDK (1008 = policy violation, 1013 = try again later). */
 const WS_CLOSE = {
     TOO_MANY_HANDSHAKES: [1013, 'too many pending handshakes'],
     HELLO_TIMEOUT: [1008, 'hello timeout'],
     INVALID_MESSAGE: [1008, 'invalid message'],
     HELLO_DUPLICATE: [1008, 'hello already received'],
-    AUTH_FAILED: [1008, 'authentication failed'],
+    // Names the recovery, because the SDK prints this reason and then stops retrying — so it is the
+    // last thing the developer sees. The common cause is a page served before the daemon existed,
+    // which carries no token; a reload re-fetches the connect module and picks the current one up.
+    // Kept under the 123-byte WebSocket close-reason limit.
+    AUTH_FAILED: [1008, WS_CLOSE_REASON.AUTH_FAILED],
     SESSION_LIMIT: [1013, 'session limit reached'],
-    PROTOCOL_MISMATCH: [1008, 'protocol version mismatch — upgrade @reticlehq/browser'],
+    PROTOCOL_MISMATCH: [1008, WS_CLOSE_REASON.PROTOCOL_MISMATCH],
 };
 /** Parse a positive integer env override; anything else (unset, zero, junk) falls through to the default. */
 function positiveIntFromEnv(raw) {
@@ -261,6 +278,10 @@ export class Bridge {
                 const got = helloProtocolMismatch(text);
                 if (got !== null) {
                     log('protocol_version_mismatch', { got, expected: RETICLE_PROTOCOL_VERSION });
+                    // Told to the AGENT too, not only to the SDK that is about to stop retrying. Without this
+                    // the next tool call answers "no browser session connected", which reads as "no app is
+                    // running" — so an SDK too old to connect is invisible.
+                    this.sessions.noteClosure(WS_CLOSE_REASON.PROTOCOL_MISMATCH, this.#clock());
                     socket.close(...WS_CLOSE.PROTOCOL_MISMATCH);
                     return;
                 }
@@ -315,6 +336,7 @@ export class Bridge {
                         served: [...this.#servedProjects],
                         ...(parsed.projectId === undefined ? {} : { helloProject: parsed.projectId }),
                     });
+                    this.sessions.noteClosure(WS_CLOSE_REASON.AUTH_FAILED, this.#clock());
                     socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
                     return;
                 }
@@ -363,6 +385,14 @@ export class Bridge {
                     noteVersionSkew(SkewPair.SDK, skew);
                 }
                 log('session_connected', { sessionId: session.id, url: session.url });
+                // The one fact that separates a broken install from an unused one. Best-effort and wrapped:
+                // a metric must never affect whether an app can connect. See SessionSummary.appConnects.
+                try {
+                    getSessionMetrics().recordAppConnected();
+                }
+                catch {
+                    /* never let a counter interfere with an app connecting */
+                }
                 this.#onSessionReady?.(session); // daemon pushes the replayable-flow list to the panel
                 return;
             }

package/dist/bridge/bridge.test-harness.d.ts

@@ -35,6 +35,14 @@ export declare class FakeBrowser {
     emit(type: string, data: Record<string, unknown>, ref?: string): void;
     close(): void;
 }
+/**
+ * Poll until `cond` holds.
+ *
+ * The default was 2000ms and the fifty-browser test blew it on the Windows runner at 5155ms — a
+ * statement about the machine, not about the bridge. Raising it is safe in a way that raising a
+ * fixed sleep would not be: this POLLS every 10ms and resolves the instant the condition holds, so
+ * a passing test is not slowed by one millisecond and only a genuinely failing one waits longer.
+ */
 export declare function waitUntil(cond: () => boolean, timeoutMs?: number): Promise<void>;
 export declare const callTool: (deps: ToolDeps, name: string, args?: Record<string, unknown>) => Promise<unknown>;
 /** Builds the ToolDeps wired to a running bridge, with a frozen clock for deterministic tests. */

package/dist/bridge/bridge.test-harness.js

@@ -170,7 +170,15 @@ export class FakeBrowser {
         this.#ws.send(JSON.stringify(obj));
     }
 }
-export function waitUntil(cond, timeoutMs = 2000) {
+/**
+ * Poll until `cond` holds.
+ *
+ * The default was 2000ms and the fifty-browser test blew it on the Windows runner at 5155ms — a
+ * statement about the machine, not about the bridge. Raising it is safe in a way that raising a
+ * fixed sleep would not be: this POLLS every 10ms and resolves the instant the condition holds, so
+ * a passing test is not slowed by one millisecond and only a genuinely failing one waits longer.
+ */
+export function waitUntil(cond, timeoutMs = 15_000) {
     return new Promise((resolve, reject) => {
         const start = Date.now();
         const tick = () => {

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,13 +1,59 @@
 import { existsSync, 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 { 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`);
@@ -24,9 +70,31 @@ export async function handleDoctor(port) {
     catch {
         line('  chromium     ✗ missing — run: npx playwright install chromium');
     }
+    // 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-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/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,35 @@
+/**
+ * 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';
+const FIX = 'Restart it so both ends are the same build: `reticle stop`, then let your agent reconnect.';
+/**
+ * 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;