@reticlehq/server 2.6.0 → 2.8.0

package/dist/capsule/causal-summary.js

@@ -1,4 +1,23 @@
 import { EventType, PerfMetric, isDevToolingUrl } from '@reticlehq/core';
+/**
+ * THE INVARIANT: every field of this summary has a bounded size that does not depend on how much the
+ * app did. A verdict travels in the same payload as its evidence, so an unbounded evidence field is
+ * an unbounded chance that the verdict is the part a client truncates — and an agent that cannot read
+ * the verdict has run the verification and got nothing, which is indistinguishable from not running
+ * it. Measured: one click on a page with a registered TanStack Query store returned ~363KB, because
+ * `capValue` bounded each diff and nothing bounded the COUNT of them.
+ *
+ * 20 keeps the signal that is actually read — the first paths to move, and the settle window over all
+ * of them — while the full names of everything that changed stay one `reticle_state` call away.
+ */
+export const MAX_SUMMARY_ENTRIES = 20;
+/** Trim one list to the cap and report the loss. Order is arrival order, so the head is the earliest. */
+function cap(list, name, elided) {
+    if (list.length <= MAX_SUMMARY_ENTRIES)
+        return list;
+    elided[name] = list.length - MAX_SUMMARY_ENTRIES;
+    return list.slice(0, MAX_SUMMARY_ENTRIES);
+}
 function pushUnique(list, value) {
     if ('string' === typeof value && value.length > 0 && !list.includes(value))
         list.push(value);
@@ -118,6 +137,11 @@ export function causalSummary(events) {
                 break;
         }
     }
+    const elided = {};
+    // `stateSettleMs` is computed over EVERY diff, before the cap: the interval is a fact about the
+    // store, and shrinking it because the evidence was trimmed would make the transient window read as
+    // narrower than it was — the one number here that must survive the trim intact.
+    const settle = stateSettle(stateDiffs);
     return {
         net: {
             total: netTotal,
@@ -126,13 +150,14 @@ export function causalSummary(events) {
             ...(headline === undefined ? {} : { headline }),
         },
         consoleErrors,
-        statePathsChanged,
-        storageKeysChanged,
-        stateDiffs,
-        ...stateSettle(stateDiffs),
-        storageDiffs,
+        statePathsChanged: cap(statePathsChanged, 'statePathsChanged', elided),
+        storageKeysChanged: cap(storageKeysChanged, 'storageKeysChanged', elided),
+        stateDiffs: cap(stateDiffs, 'stateDiffs', elided),
+        ...settle,
+        storageDiffs: cap(storageDiffs, 'storageDiffs', elided),
         ...(route === undefined ? {} : { route }),
-        signals,
+        signals: cap(signals, 'signals', elided),
+        ...(0 === Object.keys(elided).length ? {} : { elided }),
         ...(layoutShift === undefined ? {} : { layoutShift }),
         longTasks,
     };

package/dist/capsule/divergence.js

@@ -7,7 +7,13 @@ function satisfies(link, events) {
         case ConsequenceKind.SIGNAL:
             return events.some((e) => e.type === EventType.SIGNAL && e.data['name'] === link.name);
         case ConsequenceKind.STATE:
-            return events.some((e) => e.type === EventType.STATE_CHANGE && e.data['name'] === link.name);
+            // Matched against the store name OR the changed path, because the link carries whichever half
+            // the predicate gave: `store` when it named one, and `path` otherwise (predicateToExpectedLinks).
+            // The event carries both. Comparing only the store meant every assertion written by path
+            // reported "never changed" however the app behaved — a false claim printed beside a `stateDiffs`
+            // entry showing that exact path changing.
+            return events.some((e) => e.type === EventType.STATE_CHANGE &&
+                (e.data['name'] === link.name || e.data['path'] === link.name));
         case ConsequenceKind.NET:
             return net(events).some((e) => 'string' === typeof e.data['url'] &&
                 e.data['url'].includes(link.urlContains) &&

package/dist/cli/chromium-hint.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A Chromium hint you can satisfy by following it.
+ *
+ * `npx playwright install chromium` looks obviously right and is quietly wrong. `npx` resolves the
+ * LATEST playwright, which pins a different browser revision than the playwright the daemon actually
+ * bundles — so the command downloads ~90 MiB of a build the daemon will not use, and the check still
+ * says missing afterwards. Reported from the field by an agent whose machine already had five
+ * chromium builds, none of them the wanted one, with no way to learn which one was wanted.
+ *
+ * The same reporter came back, because pinning the command fixes only half of it. Their five builds
+ * sat in the standard Windows browsers root and the line still read a flat `missing`, which leaves
+ * two readings — "the check is broken" and "none of these count" — and no way to choose. Present at
+ * the wrong revision and absent entirely are different problems: one is a single pinned download,
+ * the other means the lookup is aimed at a root nothing was ever installed into. Collapsing them is
+ * what made the loop unbreakable.
+ *
+ * Three things fix it, and they are what any unsatisfiable check needs: pin the command to the
+ * version doing the asking, say what was probed, and separate the verdicts that have different
+ * fixes. The wanted revision and the browsers root are both read back off the path Playwright itself
+ * resolves, so `PLAYWRIGHT_BROWSERS_PATH` and every platform default are honoured by construction
+ * rather than by a table of roots this file would have to keep in step with Playwright's.
+ */
+/** What the check found, gathered by the caller so this stays pure and testable. */
+export interface ChromiumProbe {
+    /** Executable path the daemon's own playwright resolves to; undefined when playwright is absent. */
+    executablePath?: string | undefined;
+    /** Whether that path exists on disk. */
+    exists: boolean;
+    /** Version of the playwright the DAEMON bundles — not whatever `npx` would fetch. */
+    playwrightVersion?: string | undefined;
+    /** The revision that path names, e.g. `chromium-1223`. Undefined if the path has no revision in it. */
+    wantedRevision?: string | undefined;
+    /** The browsers root the lookup used, wherever `PLAYWRIGHT_BROWSERS_PATH` and the platform put it. */
+    browsersRoot?: string | undefined;
+    /** Chromium revisions actually sitting in that root, wanted or not. */
+    installedRevisions?: readonly string[] | undefined;
+}
+/**
+ * The install command, pinned when we know what to pin to.
+ *
+ * Unpinned is still the right fallback: a wrong-revision download is a bad outcome, but no command
+ * at all is a worse one.
+ */
+export declare function chromiumInstallCommand(playwrightVersion?: string): string;
+/**
+ * Split a resolved executable path into the browsers root and the revision under it, or null.
+ *
+ * Reading them back off Playwright's own answer is the point. The alternative is reconstructing the
+ * root from `PLAYWRIGHT_BROWSERS_PATH` plus a per-platform default, which is a copy of Playwright's
+ * resolution rules that drifts the first time they change one — and getting it wrong here means
+ * telling a user their browsers are missing while looking in the wrong directory, which is the exact
+ * failure this file exists to stop.
+ */
+export declare function parseChromiumRevision(executablePath: string): {
+    revision: string;
+    root: string;
+} | null;
+/**
+ * Ask the playwright THIS process would use, not the one `npx` would fetch.
+ *
+ * `executablePath()` resolves the revision the daemon will actually launch AND the root it will look
+ * in, which is why the probe never reads `PLAYWRIGHT_BROWSERS_PATH` itself.
+ */
+export declare function probeChromium(): Promise<ChromiumProbe>;
+/** The bundled playwright's version, or undefined if it cannot be read (the hint then goes unpinned). */
+export declare function bundledPlaywrightVersion(): string | undefined;
+/** The doctor line for the Chromium check — verdict, what was probed, and how to satisfy it. */
+export declare function chromiumHint(probe: ChromiumProbe): string;

package/dist/cli/chromium-hint.js

@@ -0,0 +1,145 @@
+/**
+ * A Chromium hint you can satisfy by following it.
+ *
+ * `npx playwright install chromium` looks obviously right and is quietly wrong. `npx` resolves the
+ * LATEST playwright, which pins a different browser revision than the playwright the daemon actually
+ * bundles — so the command downloads ~90 MiB of a build the daemon will not use, and the check still
+ * says missing afterwards. Reported from the field by an agent whose machine already had five
+ * chromium builds, none of them the wanted one, with no way to learn which one was wanted.
+ *
+ * The same reporter came back, because pinning the command fixes only half of it. Their five builds
+ * sat in the standard Windows browsers root and the line still read a flat `missing`, which leaves
+ * two readings — "the check is broken" and "none of these count" — and no way to choose. Present at
+ * the wrong revision and absent entirely are different problems: one is a single pinned download,
+ * the other means the lookup is aimed at a root nothing was ever installed into. Collapsing them is
+ * what made the loop unbreakable.
+ *
+ * Three things fix it, and they are what any unsatisfiable check needs: pin the command to the
+ * version doing the asking, say what was probed, and separate the verdicts that have different
+ * fixes. The wanted revision and the browsers root are both read back off the path Playwright itself
+ * resolves, so `PLAYWRIGHT_BROWSERS_PATH` and every platform default are honoured by construction
+ * rather than by a table of roots this file would have to keep in step with Playwright's.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+/**
+ * A browsers-root entry that is a chromium build.
+ *
+ * Deliberately not matching `chromium_headless_shell-*`: it lives beside the full build and is a
+ * different artifact, so counting it would let a root holding only headless shells report the full
+ * browser as present-but-mismatched.
+ */
+const CHROMIUM_DIR = /^chromium-\d+$/;
+/** The same directory name as a path segment, on either separator, so Windows paths split too. */
+const CHROMIUM_SEGMENT = /[\\/](chromium-\d+)[\\/]/;
+/**
+ * The install command, pinned when we know what to pin to.
+ *
+ * Unpinned is still the right fallback: a wrong-revision download is a bad outcome, but no command
+ * at all is a worse one.
+ */
+export function chromiumInstallCommand(playwrightVersion) {
+    const pin = playwrightVersion === undefined ? 'playwright' : `playwright@${playwrightVersion}`;
+    return `npx ${pin} install chromium`;
+}
+/**
+ * Split a resolved executable path into the browsers root and the revision under it, or null.
+ *
+ * Reading them back off Playwright's own answer is the point. The alternative is reconstructing the
+ * root from `PLAYWRIGHT_BROWSERS_PATH` plus a per-platform default, which is a copy of Playwright's
+ * resolution rules that drifts the first time they change one — and getting it wrong here means
+ * telling a user their browsers are missing while looking in the wrong directory, which is the exact
+ * failure this file exists to stop.
+ */
+export function parseChromiumRevision(executablePath) {
+    const match = CHROMIUM_SEGMENT.exec(executablePath);
+    if (null === match)
+        return null;
+    const revision = match[1];
+    if (revision === undefined)
+        return null;
+    return { revision, root: executablePath.slice(0, match.index) };
+}
+/** Chromium revisions present in a browsers root. Empty on an unreadable or absent root. */
+function installedRevisions(root) {
+    try {
+        return readdirSync(root)
+            .filter((entry) => CHROMIUM_DIR.test(entry))
+            .sort();
+    }
+    catch {
+        // No root at all is the commonest case here and is not an error: it means nothing was installed.
+        return [];
+    }
+}
+/**
+ * Ask the playwright THIS process would use, not the one `npx` would fetch.
+ *
+ * `executablePath()` resolves the revision the daemon will actually launch AND the root it will look
+ * in, which is why the probe never reads `PLAYWRIGHT_BROWSERS_PATH` itself.
+ */
+export async function probeChromium() {
+    try {
+        const { chromium } = await import('playwright');
+        const executablePath = chromium.executablePath();
+        const parsed = parseChromiumRevision(executablePath);
+        return {
+            executablePath,
+            exists: existsSync(executablePath),
+            playwrightVersion: bundledPlaywrightVersion(),
+            ...(null === parsed
+                ? {}
+                : {
+                    wantedRevision: parsed.revision,
+                    browsersRoot: parsed.root,
+                    installedRevisions: installedRevisions(parsed.root),
+                }),
+        };
+    }
+    catch {
+        // Playwright itself is absent — a different problem from a missing browser, and the hint says so.
+        return { exists: false };
+    }
+}
+/** The bundled playwright's version, or undefined if it cannot be read (the hint then goes unpinned). */
+export function bundledPlaywrightVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require('playwright/package.json');
+        if ('object' === typeof pkg && null !== pkg && 'version' in pkg) {
+            const { version } = pkg;
+            if ('string' === typeof version)
+                return version;
+        }
+    }
+    catch {
+        /* an unreadable package.json is not worth failing a diagnostic over */
+    }
+    return undefined;
+}
+/** The doctor line for the Chromium check — verdict, what was probed, and how to satisfy it. */
+export function chromiumHint(probe) {
+    if (probe.exists) {
+        // Naming the revision on the happy line too: it is the number the mismatch line talks about, and
+        // a reader comparing two machines has nothing to compare without it.
+        return probe.wantedRevision === undefined
+            ? '✓ installed'
+            : `✓ installed (${probe.wantedRevision})`;
+    }
+    const command = chromiumInstallCommand(probe.playwrightVersion);
+    if (probe.executablePath === undefined) {
+        return `✗ the playwright package is not installed; run: ${command}`;
+    }
+    const present = probe.installedRevisions ?? [];
+    if (present.length > 0 && probe.wantedRevision !== undefined) {
+        // The reported machine. Every fact here is one the reader could not otherwise get: what is
+        // wanted, what is there, and where "there" is. `npx playwright install chromium` unpinned adds
+        // a build to this list and changes nothing, which is what happened.
+        return (`✗ wrong revision — the bundled playwright wants ${probe.wantedRevision}; ` +
+            `${probe.browsersRoot ?? ''} holds ${present.join(', ')}. run: ${command}`);
+    }
+    // Naming the path is what turns "missing" from a verdict into evidence: a reader with browsers on
+    // disk can see immediately whether this is a missing install or a lookup pointed somewhere else
+    // (PLAYWRIGHT_BROWSERS_PATH, a different browsers root, a revision bump).
+    return `✗ missing — looked for ${probe.executablePath}; run: ${command}`;
+}

package/dist/cli/cli-doctor.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ReticleEnv } from '@reticlehq/core';
 import { readPid, reticleStateHome } from '../daemon/daemon.js';
@@ -6,36 +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 { spawnSync } from 'node:child_process';
+import { sessionsLine } from './doctor-sessions-line.js';
+import { captureLookup, describeForeignHolder, findPortHolder } from './port-holder.js';
+import { chromiumHint, probeChromium } from './chromium-hint.js';
 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)
@@ -60,16 +42,10 @@ export async function handleDoctor(port) {
     };
     line('reticle doctor');
     line(`  node         ${process.version}`);
-    try {
-        const { chromium } = await import('playwright');
-        const path = chromium.executablePath();
-        line(existsSync(path)
-            ? '  chromium     ✓ installed'
-            : '  chromium     ✗ missing — run: npx playwright install chromium');
-    }
-    catch {
-        line('  chromium     ✗ missing — run: npx playwright install chromium');
-    }
+    // 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
     // states are genuinely different problems with different fixes, so doctor names which one it is.
@@ -79,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,
@@ -87,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"
@@ -94,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;
+}