@reticlehq/server 2.7.0 → 2.9.0

package/dist/cli/cli-doctor.js

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ReticleEnv } from '@reticlehq/core';
 import { readPid, reticleStateHome } from '../daemon/daemon.js';
@@ -6,37 +6,22 @@ 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 { projectWiringLine } from './doctor-project-line.js';
+import { hasProjectConnectedBefore } from '../session/connection-memory.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 { diagnoseWebCsp } from '../init/csp-doctor.js';
+import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectId, readProjectPort, } from './cli-port.js';
+import { DoctorRow, doctorRow } from './doctor-rows.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)
@@ -60,8 +45,11 @@ export async function handleDoctor(port) {
         process.stdout.write(`${s}\n`);
     };
     line('reticle doctor');
-    line(`  node         ${process.version}`);
-    line(`  chromium     ${chromiumHint(await probeChromium())}`);
+    line(doctorRow(DoctorRow.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(doctorRow(DoctorRow.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.
@@ -71,14 +59,19 @@ 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,
         });
         line(built.text);
         if (built.skew !== undefined)
-            line(`  version      ✗ ${built.skew}`);
+            line(doctorRow(DoctorRow.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 +79,43 @@ 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(doctorRow(DoctorRow.DAEMON, `✗ ${describeForeignHolder(port, findPortHolder(port, captureLookup), pid)}`));
     }
     else {
-        line(`  daemon       ✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`);
+        line(doctorRow(DoctorRow.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(doctorRow(DoctorRow.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(doctorRow(DoctorRow.PORT_CHECK, `✗ ${mismatch}`));
+    // The check this checklist was missing: is the APP wired, not just the tools. Everything above can
+    // be green in a project that has never been through `init`, and that combination is precisely the
+    // one `doctor` gets run to explain.
+    const projectId = readProjectId(process.cwd());
+    line(projectWiringLine({
+        projectId,
+        previouslyConnected: hasProjectConnectedBefore(reticleStateHome(), port, projectId),
+        // An absent config and a corrupt one both read back as "no id"; only this tells them apart,
+        // and telling somebody a file is missing while it sits in front of them is its own dead end.
+        configPresent: existsSync(join(process.cwd(), RETICLE_CONFIG_BASENAME)),
+    }));
     // 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`);
+    line(doctorRow(DoctorRow.DAEMON_LOG, join(reticleStateHome(), `daemon-${String(port)}.log`)));
+    line(doctorRow(DoctorRow.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".
@@ -109,10 +127,23 @@ export async function handleDoctor(port) {
             return undefined;
         }
     };
+    // The web sibling of the desktop findings below: a `connect-src` that excludes the bridge makes
+    // the browser refuse the WebSocket and report it in ITS console only, so every check above passes
+    // at an app that can never connect. Named, with the exact text to paste.
+    const csp = diagnoseWebCsp(readProjectFile, port);
+    if (csp.length > 0) {
+        line('');
+        line(`  csp          ✗ a Content-Security-Policy is blocking the Reticle bridge:`);
+        for (const finding of csp) {
+            line(`                 ${finding.file}`);
+            line(`                   ${finding.problem}`);
+            line(`                   fix: ${finding.fix}`);
+        }
+    }
     const desktop = diagnoseDesktop(readProjectFile, port);
     if (desktop.length > 0) {
         line('');
-        line(`  desktop      ✗ ${String(desktop.length)} issue(s) — the app will look fine and not work:`);
+        line(doctorRow(DoctorRow.DESKTOP, `✗ ${String(desktop.length)} issue(s) — the app will look fine and not work:`));
         for (const finding of desktop) {
             line(`                 ${finding.file}`);
             line(`                   ${finding.problem}`);
@@ -122,6 +153,6 @@ export async function handleDoctor(port) {
     else if (isDesktopProject(readProjectFile)) {
         // Say so explicitly. Silence would read as "not checked", which is the same ambiguity the
         // findings above exist to remove.
-        line('  desktop      ✓ desktop wiring looks right');
+        line(doctorRow(DoctorRow.DESKTOP, '✓ desktop wiring looks right'));
     }
 }

package/dist/cli/cli-flow-commands.js

@@ -19,7 +19,7 @@ import { formatBuddyStatus } from '../flows/buddy-status.js';
 import { CapsuleStore } from '../capsule/capsule-store.js';
 import { AssertionTiersStore } from '../flows/assertion-tiers-store.js';
 import { detectDowngrades } from '../flows/assertion-integrity.js';
-import { computeCoverage } from '../flows/coverage.js';
+import { computeCoverage, flowCoverageReport } from '../flows/coverage.js';
 import { createWatchBatcher } from '../flows/watch-batcher.js';
 import { watch } from 'node:fs';
 import { log } from '../log.js';
@@ -184,19 +184,19 @@ export async function handleGate(files, since) {
         const result = gateDecision({ affected, passing, flaky, downgraded, deleted });
         // Verified-surface coverage over flows: how much of the saved suite this run actually exercised.
         const coverage = computeCoverage({ testids: [], signals: [], flows: allFlows.map((f) => f.name) }, { testids: [], signals: [], flows: passing });
+        // A gate over an empty suite has not passed — it had nothing to check. Same rule the suite
+        // verdict already applies to `reticle verify`; see flowCoverageReport.
+        const flowCoverage = flowCoverageReport(coverage.flows);
+        const pass = result.pass && flowCoverage.outcome === undefined;
         log('reticle_gate', {
-            pass: result.pass,
+            pass,
             uncovered: result.uncovered,
             quarantined: result.quarantined,
             ...(result.downgraded.length > 0 ? { downgraded: result.downgraded } : {}),
             ...(result.deleted.length > 0 ? { deletedCoverage: result.deleted } : {}),
-            coverage: {
-                pct: coverage.flows.pct,
-                covered: coverage.flows.covered,
-                total: coverage.flows.total,
-            },
+            coverage: flowCoverage,
         });
-        if (!result.pass)
+        if (!pass)
             process.exitCode = 1;
     }
     catch (error) {

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

@@ -7,6 +7,21 @@
  * 3..reticle.json "port" field in the cwd ← per-project isolation
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
+/** The project config `reticle init` writes. */
+export declare const RETICLE_CONFIG_BASENAME = ".reticle.json";
+/**
+ * Find the nearest `.reticle.json` at or above `cwd`, and return its parsed contents.
+ *
+ * Every reader below used to join the basename onto `cwd` and stop there, so a process whose
+ * working directory was one level away from the config behaved exactly like a project that had
+ * never been through `init`: no port, no projectId, no journal setting, and a diagnostic that told
+ * the user to run an install they had already run. That is the shape of several field reports at
+ * once — an app wired in a subdirectory, an agent running from a repo root, a worktree beside its
+ * main checkout — and they are all the same missing walk.
+ *
+ * Returns undefined when nothing is found, which keeps every caller's existing default intact.
+ */
+export declare function findProjectConfig(cwd: string): Record<string, unknown> | undefined;
 /**
  * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
  * Astro to 4321, and so on.
@@ -33,6 +48,15 @@ export declare function readProjectPort(cwd: string): number | undefined;
  * undefined if the file is absent/unreadable or has no non-empty string projectId.
  */
 export declare function readProjectId(cwd: string): string | undefined;
+/**
+ * The framework `reticle init` stamped into `.reticle.json`, when there is one.
+ *
+ * Read so the no-session diagnosis can RANK its causes instead of printing one static differential.
+ * Nuxt is the case that pays for this: it does not register a newly added plugin on HMR, so a dev
+ * server older than the wiring is its single most likely cause — `init` warns about it at install
+ * time and the hint the agent reads hours later never mentioned it.
+ */
+export declare function readProjectFramework(cwd: string): string | undefined;
 /**
  * Whether the durable causal journal is enabled. On by default (the journal IS the loop); off only via
  * explicit opt-out — `.reticle.json` `"journal": false`, or `RETICLE_JOURNAL` set to `0`/`false`. The env
@@ -44,3 +68,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;