@reticlehq/server 2.7.0 → 2.8.0

package/dist/cli/cli-doctor.js

@@ -6,37 +6,18 @@ 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 { sessionsLine } from './doctor-sessions-line.js';
+import { captureLookup, 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';
+import { diagnosePortMismatch, readProjectPort } from './cli-port.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)
@@ -61,6 +42,9 @@ export async function handleDoctor(port) {
     };
     line('reticle doctor');
     line(`  node         ${process.version}`);
+    // Filled in only on the daemon branch — there is nothing to ask when no daemon is answering, and
+    // the branches below already say so in their own terms.
+    let sessions;
     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
@@ -71,7 +55,8 @@ export async function handleDoctor(port) {
         // 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 payload = await fetchStatus(port);
+        const status = asIdentity(payload);
         const built = daemonLine(port, pid, status, {
             version: SERVER_VERSION,
             contract: CONTRACT_FINGERPRINT,
@@ -79,6 +64,10 @@ export async function handleDoctor(port) {
         line(built.text);
         if (built.skew !== undefined)
             line(`  version      ✗ ${built.skew}`);
+        // The same payload already carries whether anything has CONNECTED, and doctor was reading
+        // `version` off it and dropping the rest. Without this the command is silent on the one step the
+        // funnel stalls on: wired correctly, daemon up, and no page has ever dialled in.
+        sessions = sessionsLine('object' === typeof payload && null !== payload ? payload : {});
     }
     else if (presence === PortPresence.FOREIGN) {
         // Name the holder when we can. `doctor` exists for exactly this moment, and "another process"
@@ -86,18 +75,32 @@ export async function handleDoctor(port) {
         // 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)}`);
+        line(`  daemon       ✗ ${describeForeignHolder(port, findPortHolder(port, captureLookup), pid)}`);
     }
     else {
         line(`  daemon       ✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`);
     }
-    line(`  bridge port  ${port}  (your app must dial THIS port — not your dev-server port)`);
+    if (sessions !== undefined)
+        line(sessions.text);
+    line(`  bridge port  ${port}  (your app must dial THIS port, not your dev-server port)`);
+    const projectPort = readProjectPort(process.cwd());
+    const mismatch = diagnosePortMismatch(port, projectPort);
+    if (mismatch !== undefined)
+        line(`  port check   ✗ ${mismatch}`);
     // Where to LOOK when something is wrong. The daemon has always written a structured log here and
     // nothing ever said so, so the first move in every investigation was reading source instead of
     // reading the log. `RETICLE_TRACE=1` turns the same stream into a per-stage trace — see
     // docs/debugging.md.
     line(`  daemon log   ${join(reticleStateHome(), `daemon-${String(port)}.log`)}`);
     line(`  tracing      ${ReticleEnv.TRACE}=1 on the daemon for per-stage timings in that log`);
+    // Below the checklist rather than inline: it is a paragraph, and a paragraph in the middle of a
+    // column of one-line checks buries the checks under it. This is the daemon's own no-session
+    // diagnosis, the same one an agent gets from an empty reticle_sessions.
+    if (sessions?.why !== undefined) {
+        line('');
+        line('  nothing has connected. What the daemon can tell from here:');
+        line(`    ${sessions.why}`);
+    }
     // Desktop setup RCA. Every one of these fails SILENTLY — a Tauri app with the default CSP runs
     // perfectly and never connects; an Electron app without the preload line reports zero network
     // activity forever, which reads as "makes no backend calls" rather than "you are blind to them".

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

@@ -0,0 +1,58 @@
+/**
+ * `reticle kill` — free the bridge port without taking the agent's transport with it.
+ *
+ * The obvious incantation, `lsof -ti tcp:4400 | xargs kill -9`, also kills `reticle mcp`: the proxy
+ * holds a CLIENT socket on that port, `-ti` does not filter to listeners, and so the one command
+ * people reach for when the bridge is stuck destroys the channel they were trying to fix. What
+ * follows is worse than an error — the client gets no reply at all, and nothing reaches the proxy log
+ * because the process that writes it is the one that died. That is the mechanism behind most
+ * "my MCP disconnected" reports (#114, #110).
+ *
+ * The safe form was written down, and a documented incantation is a worse answer than a command: it
+ * has to be found, remembered, and typed correctly at the moment someone is already stuck. So this is
+ * the command, and it signals exactly one pid — the LISTENER.
+ *
+ * It is not a rename of `stop`. `stop` reads the pid file, which is the right source when the daemon
+ * we started is the daemon that is wedged, and no source at all when the pid file is stale, was never
+ * written, or belongs to a daemon from another checkout. `kill` asks the PORT, which is the thing the
+ * user actually wants freed, and falls back to the pid file only where the lookup cannot run.
+ */
+import { type PortHolder } from './port-holder.js';
+/** What the plan says to do with the port. */
+export declare const KillAction: {
+    readonly NOTHING: "nothing";
+    readonly KILL: "kill";
+    readonly REFUSE: "refuse";
+};
+export type KillAction = (typeof KillAction)[keyof typeof KillAction];
+export interface KillPlan {
+    action: KillAction;
+    /** The single pid to signal. Present only for `kill`. */
+    pid?: number;
+    /** True when the target was not identifiable as Reticle's and `--force` overrode the refusal. */
+    forced: boolean;
+    /** False when the listener lookup could not run, so the pid came from our own records instead. */
+    identifiedListener: boolean;
+    /** Why we will not act, for `refuse`. */
+    reason?: string;
+    holder?: PortHolder;
+}
+export declare const FORCE_FLAG = "--force";
+/**
+ * Decide what to signal. Pure.
+ *
+ * `answersStatus` is the strongest evidence available and deliberately outranks the pid file: a
+ * daemon started from another checkout owns the port, is a Reticle daemon, and appears nowhere in our
+ * records. Refusing it would leave the port held by exactly the process this command exists to clear.
+ */
+export declare function planKill(input: {
+    /** The listener on the port, from a `-sTCP:LISTEN` lookup. Null when there is none, or no `lsof`. */
+    listener: PortHolder | null;
+    /** The pid our records hold for this port, or null when there is none or it is dead. */
+    recordedPid: number | null;
+    /** Whether the port answers `/status`, i.e. whatever holds it is a Reticle daemon. */
+    answersStatus: boolean;
+    force: boolean;
+}): KillPlan;
+/** `reticle kill` — free the port. Resolves to whether the port is now free. */
+export declare function runKill(port: number, force: boolean): Promise<boolean>;

package/dist/cli/cli-kill.js

@@ -0,0 +1,162 @@
+/**
+ * `reticle kill` — free the bridge port without taking the agent's transport with it.
+ *
+ * The obvious incantation, `lsof -ti tcp:4400 | xargs kill -9`, also kills `reticle mcp`: the proxy
+ * holds a CLIENT socket on that port, `-ti` does not filter to listeners, and so the one command
+ * people reach for when the bridge is stuck destroys the channel they were trying to fix. What
+ * follows is worse than an error — the client gets no reply at all, and nothing reaches the proxy log
+ * because the process that writes it is the one that died. That is the mechanism behind most
+ * "my MCP disconnected" reports (#114, #110).
+ *
+ * The safe form was written down, and a documented incantation is a worse answer than a command: it
+ * has to be found, remembered, and typed correctly at the moment someone is already stuck. So this is
+ * the command, and it signals exactly one pid — the LISTENER.
+ *
+ * It is not a rename of `stop`. `stop` reads the pid file, which is the right source when the daemon
+ * we started is the daemon that is wedged, and no source at all when the pid file is stale, was never
+ * written, or belongs to a daemon from another checkout. `kill` asks the PORT, which is the thing the
+ * user actually wants freed, and falls back to the pid file only where the lookup cannot run.
+ */
+import { PortPresence, probePresence } from '../daemon/port-presence.js';
+import { isAlive, readPid, removePid } from '../daemon/daemon.js';
+import { probeDaemon } from '../mcp/mcp-proxy.js';
+import { log } from '../log.js';
+import { fetchStatus } from './cli-launch.js';
+import { captureLookup, findPortHolder } from './port-holder.js';
+/** What the plan says to do with the port. */
+export const KillAction = {
+    NOTHING: 'nothing',
+    KILL: 'kill',
+    REFUSE: 'refuse',
+};
+export const FORCE_FLAG = '--force';
+/**
+ * Decide what to signal. Pure.
+ *
+ * `answersStatus` is the strongest evidence available and deliberately outranks the pid file: a
+ * daemon started from another checkout owns the port, is a Reticle daemon, and appears nowhere in our
+ * records. Refusing it would leave the port held by exactly the process this command exists to clear.
+ */
+export function planKill(input) {
+    const { listener, recordedPid, answersStatus, force } = input;
+    if (null === listener) {
+        // No listener identified. On Windows and in slim containers that means the lookup could not run
+        // rather than that the port is free, so the recorded pid is the best target we have — and the
+        // report says which of the two it is rather than implying a lookup we never made.
+        if (null === recordedPid)
+            return { action: KillAction.NOTHING, forced: false, identifiedListener: false };
+        return { action: KillAction.KILL, pid: recordedPid, forced: false, identifiedListener: false };
+    }
+    const ours = answersStatus || listener.pid === recordedPid;
+    if (ours || force) {
+        return {
+            action: KillAction.KILL,
+            pid: listener.pid,
+            forced: !ours,
+            identifiedListener: true,
+            holder: listener,
+        };
+    }
+    return {
+        action: KillAction.REFUSE,
+        forced: false,
+        identifiedListener: true,
+        holder: listener,
+        reason: `pid ${String(listener.pid)} ("${listener.command}") is listening, and it is not a Reticle ` +
+            `daemon — it never answered /status and it is not the pid Reticle recorded. Killing it would ` +
+            `be killing someone else's process. Run it again with ${FORCE_FLAG} if that is what you ` +
+            `meant, or start Reticle on another port.`,
+    };
+}
+/** How long the target gets to exit on SIGTERM before we stop asking politely. */
+const GRACEFUL_KILL_MS = 5_000;
+/** How long after SIGKILL before we accept the process is not ours to kill and say so. */
+const FORCED_KILL_MS = 2_000;
+const KILL_POLL_MS = 100;
+/**
+ * Signal ONE pid and wait for it to go: SIGTERM, then SIGKILL, then give up and say it survived.
+ *
+ * The escalation is the reason this exists rather than a bare SIGTERM — there is a field report of a
+ * daemon that ignored SIGTERM until a human ran `kill -9` by hand, which is the moment the `lsof -ti`
+ * pipeline gets typed and the agent's proxy dies with the daemon.
+ */
+async function terminate(pid) {
+    const signal = (name) => {
+        try {
+            process.kill(pid, name);
+        }
+        catch {
+            // Gone between the liveness check and here. The next poll reports it as gone.
+        }
+    };
+    signal('SIGTERM');
+    const started = Date.now();
+    let escalated = false;
+    for (;;) {
+        await new Promise((resolve) => setTimeout(resolve, KILL_POLL_MS));
+        if (!isAlive(pid))
+            return { gone: true, escalated };
+        const waited = Date.now() - started;
+        if (!escalated && waited > GRACEFUL_KILL_MS) {
+            escalated = true;
+            signal('SIGKILL');
+            continue;
+        }
+        if (waited > GRACEFUL_KILL_MS + FORCED_KILL_MS)
+            return { gone: false, escalated };
+    }
+}
+/**
+ * What was NOT touched, said out loud on every kill.
+ *
+ * The command exists because of a pipeline that killed more than the reader intended and never told
+ * them, so a report that lists only the casualty repeats half the mistake. An `reticle mcp` proxy on
+ * this port survives, and its own recovery from a dead daemon is good: it goes dormant and restarts
+ * one on the next request.
+ */
+const PROXY_SPARED_NOTE = 'only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, ' +
+    'not the port, and was left alone — it goes dormant and starts a fresh daemon on the next tool call.';
+/** `reticle kill` — free the port. Resolves to whether the port is now free. */
+export async function runKill(port, force) {
+    const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+    const recorded = readPid(port);
+    const plan = planKill({
+        listener: findPortHolder(port, captureLookup),
+        recordedPid: null !== recorded && isAlive(recorded) ? recorded : null,
+        answersStatus: presence === PortPresence.DAEMON,
+        force,
+    });
+    if (KillAction.NOTHING === plan.action) {
+        removePid(port);
+        log('reticle_kill_nothing_to_do', { port, presence });
+        return true;
+    }
+    if (KillAction.REFUSE === plan.action) {
+        log('reticle_kill_refused', { port, reason: plan.reason, holder: plan.holder?.command });
+        return false;
+    }
+    const pid = plan.pid;
+    if (pid === undefined) {
+        // Unreachable by construction (planKill never returns KILL without a pid, and a test pins that),
+        // but the alternative to this branch is a non-null assertion, which this codebase does not use.
+        log('reticle_kill_nothing_to_do', { port, presence });
+        return true;
+    }
+    const { gone, escalated } = await terminate(pid);
+    if (gone)
+        removePid(port);
+    log(gone ? 'reticle_killed' : 'reticle_kill_survived', {
+        port,
+        pid,
+        escalated,
+        ...(plan.forced ? { forced: true } : {}),
+        // Say where the pid came from. Without `lsof` this is the pid we recorded, not the pid we
+        // observed listening, and those are different claims.
+        listenerIdentified: plan.identifiedListener,
+        note: gone
+            ? PROXY_SPARED_NOTE
+            : `pid ${String(pid)} survived SIGKILL, so it is not yours to kill (permissions) or is an ` +
+                `unkillable zombie. The port is still held. ${PROXY_SPARED_NOTE}`,
+    });
+    return gone;
+}

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.
@@ -29,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
@@ -64,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

@@ -120,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-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;