@reticlehq/server 3.5.0 → 3.7.0

package/dist/surface/tools/tool-hit-rate.d.ts

@@ -1,87 +0,0 @@
-/**
- * Which tools this session called, and how reachable each one was.
- *
- * The generalisation of the capture ledger: it recorded a short list of read tools to answer one
- * feature's disproof, and the question that followed is the same question asked of the whole table —
- * most of the surface has never been observed being called at all, and a decision about what to cut
- * or consolidate is about to be made. This is the instrument for that decision, and nothing else.
- *
- * ## Why the count alone is not enough
- *
- * A tool that goes uncalled because nobody was told it exists and a tool that goes uncalled because
- * nobody wants it look identical in a call count. They are opposite conclusions. So every count is
- * reported beside the tool's REACHABILITY — advertised on the default surface, advertised only on
- * the extended one, or reachable solely by naming it to `reticle_run` — and the interesting cell is
- * the one where an agent found a run-only tool anyway.
- *
- * ## The tiers are derived, never restated
- *
- * `tierOfTool` reads `CORE_TOOL_NAMES` and `EXTENDED_TOOL_NAMES` directly. A tool promoted or
- * demoted between surfaces changes tier here with nothing edited. A local copy of either list would
- * go stale on the first move and would then be wrong about the exact axis this exists to measure —
- * and it would be wrong silently, in a report used to justify deleting things.
- *
- * ## What these numbers do NOT establish
- *
- *  - **One session is not a hit rate.** This is evidence about ONE run by ONE agent against ONE app.
- *    A hit rate is a distribution over many sessions; a single session quoted as one is an anecdote
- *    with a denominator drawn on it.
- *  - **Never-called is not useless.** A tool one team reaches for once a month in an emergency and a
- *    tool nobody has ever called are the same zero here. Frequency alone cannot separate them, so a
- *    cut decided on frequency alone will delete the wrong things.
- *  - **Absent is not zero.** A session with no ledger reports `observed: false`. It has not
- *    established that no tools were called; it has established that nothing was watching.
- *  - The tools that ran BEFORE this instrument existed in the process, or against a session this
- *    daemon adopted after the fact, are simply missing rather than counted low.
- */
-/** How an agent could have reached a tool. Derived from the surface sets — see above. */
-export declare const ToolTier: {
-    /** Advertised directly on the surface every user gets. */
-    readonly DEFAULT: "default";
-    /** Advertised only when the full schema-carrying surface is switched on. */
-    readonly EXTENDED: "extended";
-    /** Advertised nowhere: reachable only by naming it to `reticle_run`. */
-    readonly RUN_ONLY: "run-only";
-};
-export type ToolTier = (typeof ToolTier)[keyof typeof ToolTier];
-/** Which surface would have put this tool in front of an agent, read off that surface's own set. */
-export declare function tierOfTool(tool: string): ToolTier;
-/** How many tools fell in each tier on one side of the called/never-called split. */
-interface TierCounts {
-    default: number;
-    extended: number;
-    runOnly: number;
-}
-interface ToolHitRate {
-    /** False when this session carries no ledger — "not watched", never "nothing was called". */
-    observed: boolean;
-    /** The four-plus-two cells: every tier, called and never-called. Omitted when not observed. */
-    cells?: {
-        called: TierCounts;
-        neverCalled: TierCounts;
-    };
-    /** Each tool called this session, most-called first. */
-    called?: readonly {
-        tool: string;
-        tier: ToolTier;
-        calls: number;
-    }[];
-    /** Each tool in the table this session never called, by name. */
-    neverCalled?: readonly {
-        tool: string;
-        tier: ToolTier;
-    }[];
-}
-/**
- * Cross one session's per-tool counts with the tool table.
- *
- * `allTools` is the DISPATCHABLE table — the names `reticle_run` will accept — passed in rather than
- * imported, because the table is assembled in the module that owns this tool and importing it back
- * would close a cycle. A tool counted but absent from the table still appears, so a name the table
- * lost is visible rather than dropped.
- */
-export declare function foldToolHitRate(input: {
-    calls: ReadonlyMap<string, number> | undefined;
-    allTools: readonly string[];
-}): ToolHitRate;
-export {};

package/dist/surface/tools/tool-hit-rate.js

@@ -1,90 +0,0 @@
-import { CORE_TOOL_NAMES, EXTENDED_TOOL_NAMES } from './tool-surface.js';
-/**
- * Which tools this session called, and how reachable each one was.
- *
- * The generalisation of the capture ledger: it recorded a short list of read tools to answer one
- * feature's disproof, and the question that followed is the same question asked of the whole table —
- * most of the surface has never been observed being called at all, and a decision about what to cut
- * or consolidate is about to be made. This is the instrument for that decision, and nothing else.
- *
- * ## Why the count alone is not enough
- *
- * A tool that goes uncalled because nobody was told it exists and a tool that goes uncalled because
- * nobody wants it look identical in a call count. They are opposite conclusions. So every count is
- * reported beside the tool's REACHABILITY — advertised on the default surface, advertised only on
- * the extended one, or reachable solely by naming it to `reticle_run` — and the interesting cell is
- * the one where an agent found a run-only tool anyway.
- *
- * ## The tiers are derived, never restated
- *
- * `tierOfTool` reads `CORE_TOOL_NAMES` and `EXTENDED_TOOL_NAMES` directly. A tool promoted or
- * demoted between surfaces changes tier here with nothing edited. A local copy of either list would
- * go stale on the first move and would then be wrong about the exact axis this exists to measure —
- * and it would be wrong silently, in a report used to justify deleting things.
- *
- * ## What these numbers do NOT establish
- *
- *  - **One session is not a hit rate.** This is evidence about ONE run by ONE agent against ONE app.
- *    A hit rate is a distribution over many sessions; a single session quoted as one is an anecdote
- *    with a denominator drawn on it.
- *  - **Never-called is not useless.** A tool one team reaches for once a month in an emergency and a
- *    tool nobody has ever called are the same zero here. Frequency alone cannot separate them, so a
- *    cut decided on frequency alone will delete the wrong things.
- *  - **Absent is not zero.** A session with no ledger reports `observed: false`. It has not
- *    established that no tools were called; it has established that nothing was watching.
- *  - The tools that ran BEFORE this instrument existed in the process, or against a session this
- *    daemon adopted after the fact, are simply missing rather than counted low.
- */
-/** How an agent could have reached a tool. Derived from the surface sets — see above. */
-export const ToolTier = {
-    /** Advertised directly on the surface every user gets. */
-    DEFAULT: 'default',
-    /** Advertised only when the full schema-carrying surface is switched on. */
-    EXTENDED: 'extended',
-    /** Advertised nowhere: reachable only by naming it to `reticle_run`. */
-    RUN_ONLY: 'run-only',
-};
-/** Which surface would have put this tool in front of an agent, read off that surface's own set. */
-export function tierOfTool(tool) {
-    if (CORE_TOOL_NAMES.has(tool))
-        return ToolTier.DEFAULT;
-    if (EXTENDED_TOOL_NAMES.has(tool))
-        return ToolTier.EXTENDED;
-    return ToolTier.RUN_ONLY;
-}
-function tally(tools) {
-    return {
-        default: tools.filter((tier) => ToolTier.DEFAULT === tier).length,
-        extended: tools.filter((tier) => ToolTier.EXTENDED === tier).length,
-        runOnly: tools.filter((tier) => ToolTier.RUN_ONLY === tier).length,
-    };
-}
-/**
- * Cross one session's per-tool counts with the tool table.
- *
- * `allTools` is the DISPATCHABLE table — the names `reticle_run` will accept — passed in rather than
- * imported, because the table is assembled in the module that owns this tool and importing it back
- * would close a cycle. A tool counted but absent from the table still appears, so a name the table
- * lost is visible rather than dropped.
- */
-export function foldToolHitRate(input) {
-    const { calls } = input;
-    if (calls === undefined)
-        return { observed: false };
-    const called = [...calls]
-        .map(([tool, count]) => ({ tool, tier: tierOfTool(tool), calls: count }))
-        .sort((a, b) => b.calls - a.calls || a.tool.localeCompare(b.tool));
-    const neverCalled = input.allTools
-        .filter((tool) => !calls.has(tool))
-        .map((tool) => ({ tool, tier: tierOfTool(tool) }))
-        .sort((a, b) => a.tool.localeCompare(b.tool));
-    return {
-        observed: true,
-        cells: {
-            called: tally(called.map((entry) => entry.tier)),
-            neverCalled: tally(neverCalled.map((entry) => entry.tier)),
-        },
-        called,
-        neverCalled,
-    };
-}

package/dist/telemetry/harness-drive.d.ts

@@ -1,4 +0,0 @@
-/** Run `drive` with every verdict underneath it attributed to the harness. */
-export declare function withHarnessDrive<T>(drive: () => Promise<T>): Promise<T>;
-/** True while a harness drive is in progress. */
-export declare function harnessDriving(): boolean;

package/dist/telemetry/harness-drive.js

@@ -1,35 +0,0 @@
-/**
- * Whether the tool call running right now belongs to one of OUR drives.
- *
- * `reticle_verify { action: "explore" }` hands the app to a model inside the daemon, which drives
- * through the same dispatch chokepoint every agent uses. That is the right design — the inner
- * `act_and_wait` and `assert` calls are real verifications and must be counted — but it left every
- * verdict a drive produced indistinguishable from one the user's own agent earned, under the same
- * session and the same `actor: agent`. So "did this install ever verify anything by itself" had no
- * answer, and any per-session rate read high by however much we drove.
- *
- * Module state, one flag, set for the span of the drive. The same one-hop pattern `tool-refused.ts`
- * already uses for its pending reason, and for the same reason: the fact is produced in one place
- * and needed in another, with a chokepoint in between that has no business taking an extra argument
- * for a metric.
- *
- * A COUNTER rather than a boolean, so a drive nested inside a drive cannot clear the flag on its way
- * out and leave the outer one unmarked.
- */
-let depth = 0;
-/** Run `drive` with every verdict underneath it attributed to the harness. */
-export async function withHarnessDrive(drive) {
-    depth += 1;
-    try {
-        return await drive();
-    }
-    finally {
-        // In a `finally` because a drive that THREW still drove: leaving the flag raised would attribute
-        // the user's own next verdict to a harness that is no longer running.
-        depth -= 1;
-    }
-}
-/** True while a harness drive is in progress. */
-export function harnessDriving() {
-    return depth > 0;
-}

package/dist/telemetry/identify.d.ts

@@ -1,22 +0,0 @@
-import { UsageContextKind, type Identity } from '@reticlehq/core/telemetry';
-/** Re-exported so the CLI has one import for the whole feature; the shape itself lives in core. */
-export { UsageContextKind };
-export type { Identity };
-export declare function readIdentity(file?: string): Identity | undefined;
-export declare function saveIdentity(identity: Identity, file?: string): void;
-export declare function clearIdentity(file?: string): void;
-/**
- * What identifying yourself actually does, in plain words, shown BEFORE anything is sent.
- *
- * The second sentence is the one that matters and the one a consent notice usually omits: the
- * identity is keyed to the same anonymous id the previous events carried, so opting in links the
- * usage history that was already collected. That is exactly what makes it useful to us, which is
- * exactly why the user has to be told before they choose, not after.
- */
-export declare const IDENTIFY_NOTICE: string;
-/**
- * Report an identity. Emitted as its own event so it is trivially separable from the anonymous
- * stream — a distinct name is what lets the analytics side hold it under a different retention rule,
- * or drop it entirely, without touching the adoption metrics.
- */
-export declare function submitIdentity(identity: Identity): Promise<boolean>;

package/dist/telemetry/identify.js

@@ -1,73 +0,0 @@
-/**
- * `reticle identify` — the ONLY way Reticle ever learns who you are, and it is a thing you type.
- *
- * The product question behind this is real: which of these anonymous ids are companies who would pay
- * for support, an enterprise licence, or a design-partner slot? The tempting answer is to infer it —
- * match a git remote against a company domain, sniff an email out of `git config`, resolve an npm org.
- * Reticle does none of that, and the refusal is deliberate rather than squeamish:
- *
- *   - it would contradict a promise made in four places (README, usage, enterprise FAQ, telemetry
- *     policy) that project names, git remotes and account identifiers are never sent;
- *   - covert identification of a data subject is not "anonymous usage metrics", so it would also
- *     break the legal basis the policy states — legitimate interest, minimized to the listed fields;
- *   - and it is worse at the actual job. A scraped lead is a cold email from a tool the recipient
- *     trusted, which is the fastest way to turn an advocate into someone who runs
- *     `reticle telemetry disable` and tells their team to do the same. A self-identified one already
- *     wants to talk to you.
- *
- * So this is opt-in, explicit, reversible, and it tells the user exactly what it links before it
- * sends anything.
- */
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { TelemetryEventKind, UsageContextKind } from '@reticlehq/core/telemetry';
-import { getTelemetry } from './telemetry.js';
-const RETICLE_DIR = join(homedir(), '.reticle');
-/** Persisted so the identity survives shells and is attached to later sessions — and so it can be shown back. */
-const IDENTITY_FILE = join(RETICLE_DIR, 'identity.json');
-/** Re-exported so the CLI has one import for the whole feature; the shape itself lives in core. */
-export { UsageContextKind };
-export function readIdentity(file = IDENTITY_FILE) {
-    try {
-        return JSON.parse(readFileSync(file, 'utf8'));
-    }
-    catch {
-        return undefined;
-    }
-}
-export function saveIdentity(identity, file = IDENTITY_FILE) {
-    mkdirSync(RETICLE_DIR, { recursive: true });
-    writeFileSync(file, JSON.stringify(identity, null, 2), 'utf8');
-}
-export function clearIdentity(file = IDENTITY_FILE) {
-    rmSync(file, { force: true });
-}
-/**
- * What identifying yourself actually does, in plain words, shown BEFORE anything is sent.
- *
- * The second sentence is the one that matters and the one a consent notice usually omits: the
- * identity is keyed to the same anonymous id the previous events carried, so opting in links the
- * usage history that was already collected. That is exactly what makes it useful to us, which is
- * exactly why the user has to be told before they choose, not after.
- */
-export const IDENTIFY_NOTICE = [
-    'This sends the details you type here to the Reticle maintainers, so we can contact you and',
-    "understand how teams use Reticle. It is linked to this machine's anonymous id, which means it",
-    'also connects the anonymous usage already recorded from this machine to what you enter now.',
-    'Nothing about your app, your code, or your repository is included, and nothing else changes.',
-    'Undo it any time with `reticle identify --forget` (that stops future sends and deletes the local file;',
-    'email support@reticlehq.com to have what was already sent removed).',
-].join('\n');
-/**
- * Report an identity. Emitted as its own event so it is trivially separable from the anonymous
- * stream — a distinct name is what lets the analytics side hold it under a different retention rule,
- * or drop it entirely, without touching the adoption metrics.
- */
-export async function submitIdentity(identity) {
-    const telemetry = getTelemetry();
-    if (!telemetry.enabled)
-        return false;
-    await telemetry.emit(TelemetryEventKind.IDENTIFIED, { identity });
-    return true;
-}

package/docs/cli/capsules.mdx

@@ -1,70 +0,0 @@
----
-title: reticle capsules
-description: List the saved fail-to-pass bug capsules recorded from failed assertions.
-icon: capsules
----
-
-`reticle capsules` lists what is in `.reticle/capsules`. A capsule is a minimal failing reproduction plus the consequence that should have held. Replay one with the `reticle_flow_replay` tool.
-
-```bash
-npx @reticlehq/server capsules
-```
-
-No flags.
-
-## What it prints
-
-One `reticle_capsules` line: a `count` and an array. Real capture from this repository, trimmed to three of the seventy-nine entries and pretty-printed (the CLI prints it as a single line):
-
-```json
-{
-  "t": "2026-08-15T18:42:48.790Z",
-  "event": "reticle_capsules",
-  "count": 79,
-  "capsules": [
-    {
-      "id": "1786793143459-e5",
-      "origin": "failed-assert",
-      "expected": "signal auth:granted",
-      "observed": "signal \"auth:granted\" never fired",
-      "steps": 1
-    },
-    {
-      "id": "1786791565180-e12",
-      "origin": "failed-assert",
-      "expected": "declared consequence",
-      "observed": "route is '/actions', expected '/server-actions'",
-      "steps": 1
-    },
-    {
-      "id": "1785653101906-e3",
-      "origin": "failed-assert",
-      "expected": "declared consequence",
-      "observed": "not settled: 236 request(s) still in flight",
-      "steps": 1
-    }
-  ]
-}
-```
-
-| Field      | Meaning                                          |
-| ---------- | ------------------------------------------------ |
-| `id`       | Capsule id, timestamp plus a cursor              |
-| `flow`     | Present when the capsule came from a named flow  |
-| `origin`   | How it was captured, for example `failed-assert` |
-| `expected` | The consequence that was declared                |
-| `observed` | What actually happened                           |
-| `steps`    | How many steps the reproduction is               |
-
-## Exit codes
-
-| Code | Meaning                                                                  |
-| ---- | ------------------------------------------------------------------------ |
-| `0`  | Listed, even when the count is zero                                      |
-| `1`  | The capsule store could not be read. Logged as `reticle_capsules_failed` |
-
-## Worked example
-
-```bash
-npx @reticlehq/server capsules | jq '.capsules[] | select(.origin == "failed-assert") | .observed'
-```

package/docs/cli/hunt.mdx

@@ -1,73 +0,0 @@
----
-title: reticle hunt
-description: Aggregate many crawl reports into one false-green rate across already-merged changes.
-icon: crosshairs
----
-
-`reticle hunt` is arithmetic, not driving. You point it at a directory of crawl reports (one JSON file per checkout, each produced by `reticle_verify {action:"crawl"}`) and it turns the pile into the one number the core claim needs: across N already-merged, already-green changes, how many carried a candidate false green?
-
-```bash
-npx @reticlehq/server hunt <dir-of-crawl-reports>
-```
-
-No control arm is needed. Those changes shipped, so the counterfactual is already established.
-
-## Arguments
-
-| Argument | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `<dir>` | string, positional, **required** | none | Directory of `*.json` crawl reports. Each file is one crawl over one checkout |
-
-Each input file is read for `label` (falling back to the filename), `anomalies[]`, and `stepsRun`.
-
-## What it prints
-
-One `reticle_hunt` line with the summary. Real capture over a directory of two reports, one of them carrying a contradiction and a console error, with the `headline` sentence trimmed at the ellipsis:
-
-```json
-{
-  "t": "2026-08-15T18:43:18.333Z",
-  "event": "reticle_hunt",
-  "runs": 2,
-  "runsWithCoverage": 2,
-  "runsWithContradictions": 1,
-  "contradictions": 1,
-  "singleChannelFaults": 1,
-  "byKind": { "ui-advanced-request-failed": 1, "console-error": 1 },
-  "flagged": ["abc123"],
-  "headline": "1 of 2 merged, already-green changes carried a candidate false green (1 contradictions) ..."
-}
-```
-
-| Field | Meaning |
-| --- | --- |
-| `runs` | Report files read |
-| `runsWithCoverage` | Runs that drove at least one control. The only honest denominator: a run that drove nothing is not evidence of cleanliness |
-| `runsWithContradictions` | Runs with at least one cross-channel contradiction |
-| `contradictions` | Total contradictions. The kinds are `ui-advanced-request-failed`, `signal-contradicted`, `response-ignored`, `duplicate-request`, `request-never-settled`, `failure-misattributed` |
-| `singleChannelFaults` | Everything else: console errors, failed requests, dead controls. Context, not the claim |
-| `byKind` | Counts per anomaly kind |
-| `flagged` | The labels with contradictions, so each can be confirmed by hand |
-| `headline` | A sentence phrased so it cannot overstate itself. It says "candidate", because every flag still needs manual confirmation |
-
-## Exit codes
-
-Always `0`. A read failure is logged as `reticle_hunt_failed`. Omitting the directory is a usage error:
-
-```
-{"t":"2026-08-15T18:43:06.525Z","event":"reticle_usage_error","message":"usage: reticle hunt <dir-of-crawl-reports>"}
-usage: reticle hunt <dir-of-crawl-reports>
-```
-
-That path exits `1`.
-
-## Worked example
-
-```bash
-for sha in $(git log --format=%H -n 30 main); do
-  git checkout "$sha" && npm run dev &
-  # drive reticle_verify {action:"crawl"} over the app, write the JSON:
-  # .../reports/$sha.json
-done
-npx @reticlehq/server hunt ./reports
-```

package/docs/cli/identify.mdx

@@ -1,76 +0,0 @@
----
-title: reticle identify
-description: Opt in to telling the Reticle maintainers who you are, and undo it at any time.
-icon: id-card
----
-
-`reticle identify` attaches a name, a company, an email and a usage context to this machine's Reticle install and sends them to the maintainers, so support or an enterprise trial has someone to talk to. It is off unless you run it, and `reticle identify --forget` undoes it.
-
-It is opt-in and deliberately not interactive. A prompt in the middle of someone's work is pressure, and this is the one command where the choice has to be free. You type what you want to share, or you never run it at all.
-
-```bash
-npx @reticlehq/server identify --context <company|side_project|open_source|learning> [--company "Acme"] [--email you@acme.com] [--forget]
-```
-
-## Flags
-
-| Flag | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `--context K` | one of `company`, `side_project`, `open_source`, `learning` | none. Required unless `--forget` | What Reticle is being used for |
-| `--company N` | string | unset | Your company name. Optional |
-| `--email E` | string | unset | An address to reach you on. Optional |
-| `--forget` | boolean | `false` | Delete the local identity file and stop sending it |
-
-Every field except the context is optional, so you can say "this is a company" without saying which, or name the company without leaving an address.
-
-## What it prints
-
-The consent notice, then the exact payload, then the result:
-
-```
-sending      {"context":"company","company":"Acme","email":"you@acme.com"}
-thanks       saved and sent. we may reach out; `reticle identify --forget` undoes this.
-```
-
-`not sent` replaces the last line when telemetry is disabled on the machine, in which case the identity is saved locally only.
-
-With `--forget`:
-
-```
-forgotten    the local identity file is deleted; nothing further is sent.
-             to have what was already sent removed, email support@reticlehq.com
-```
-
-Run with no valid `--context`, it prints the current identity (if any), the usage, and the full consent notice, and exits `1`. Real capture on a machine with no identity on file:
-
-```
-usage: reticle identify --context <company|side_project|open_source|learning>
-       [--company "Acme"] [--email you@acme.com] [--forget]
-
-This sends the details you type here to the Reticle maintainers, so we can contact you and
-understand how teams use Reticle. It is linked to this machine's anonymous id, which means it
-also connects the anonymous usage already recorded from this machine to what you enter now.
-Nothing about your app, your code, or your repository is included, and nothing else changes.
-Undo it any time with `reticle identify --forget` (that stops future sends and deletes the local file;
-email support@reticlehq.com to have what was already sent removed).
-```
-
-<Warning>
-  Identifying links this machine's anonymous id to what you type, which also connects the anonymous
-  usage already recorded from this machine to that identity. The command says so before it sends
-  anything. Nothing about your app, your code, or your repository is ever included.
-</Warning>
-
-## Exit codes
-
-| Code | Meaning                                                                        |
-| ---- | ------------------------------------------------------------------------------ |
-| `0`  | Identity saved, or forgotten, or usage printed when an identity already exists |
-| `1`  | No valid `--context` and no identity on file                                   |
-
-## Worked example
-
-```bash
-npx @reticlehq/server identify --context open_source --email maintainer@example.com
-npx @reticlehq/server identify --forget
-```

package/docs/cli/kill.mdx

@@ -1,91 +0,0 @@
----
-title: reticle kill
-description: Free the bridge port by killing its listener, without touching the agent's own MCP proxy.
-icon: skull
----
-
-`reticle kill` frees the bridge port. It asks **who is listening** on the port and signals that one process, which is the whole difference between this command and the shell pipeline everybody reaches for.
-
-```bash
-npx @reticlehq/server kill [--port N] [--force]
-```
-
-<Warning>
-  Never free the port with `lsof -ti tcp:4400 | xargs kill -9`. `reticle mcp` holds a **client**
-  socket on that port, so `-ti` lists the proxy right beside the daemon and the pipeline kills both.
-  When the proxy dies, the agent's next tool calls get no reply at all: not an error, not a timeout.
-  Nothing is written to the proxy log either, because the process that writes it is the one that
-  died. That is the mechanism behind most "my MCP disconnected" reports.
-</Warning>
-
-## Flags
-
-| Flag | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `--port N` | number | `4400` (or `RETICLE_PORT`, or the port in `.reticle.json`) | Which port to free |
-| `--force` | boolean | `false` | Kill the listener even when it is not a Reticle daemon |
-
-## kill or stop?
-
-They target different things, and the distinction matters exactly when you are stuck.
-
-|  | `reticle stop` | `reticle kill` |
-| --- | --- | --- |
-| Finds the process by | the pid recorded in Reticle's own state | the **listener** on the port |
-| Works when the pid file is stale or was never written | no | yes |
-| Works on a daemon from another checkout | no | yes |
-| Works without `lsof` (Windows, slim containers) | yes | yes, falling back to the recorded pid and saying so |
-
-Reach for `stop` in a script that shuts down a daemon it started. Reach for `kill` when the port is held and you want it back.
-
-## How it decides
-
-1. Look up the listener with `lsof -nP -iTCP:<port> -sTCP:LISTEN`. Client sockets are excluded by construction, so the proxy is never a candidate.
-2. It is Reticle's if it answers `/status`, **or** if it is the pid Reticle recorded for the port. `/status` outranks the pid file, so a daemon started from another checkout is still recognised as ours.
-3. Anything else is refused, by name, unless `--force`.
-4. `SIGTERM`, then `SIGKILL` after 5 seconds, then report that it survived and exit `1`.
-
-## What it prints
-
-Real captures, taken against a daemon started on a scratch port. The long `note` and `reason` strings are trimmed at the ellipsis. Measured exit codes: `0` for killed and nothing-to-do, `1` for refused.
-
-Killed:
-
-```
-{"t":"2026-08-15T18:43:43.590Z","event":"reticle_killed","port":4499,"pid":78621,"escalated":false,"listenerIdentified":true,"note":"only the listener was signalled. Any `reticle mcp` proxy on this port holds a client connection, not the port, and was left alone ..."}
-```
-
-Refused, because the listener is not ours. This one was captured with `python3 -m http.server 4498` holding the port:
-
-```
-{"t":"2026-08-15T18:43:57.128Z","event":"reticle_kill_refused","port":4498,"reason":"pid 78795 (\"Python\") 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 if that is what you meant, or start Reticle on another port.","holder":"Python"}
-```
-
-Nothing to free:
-
-```
-{"t":"2026-08-15T18:43:43.784Z","event":"reticle_kill_nothing_to_do","port":4499,"presence":"free"}
-```
-
-| Event | When |
-| --- | --- |
-| `reticle_killed` | The listener is gone. `escalated: true` means it took a `SIGKILL`; `forced: true` means `--force` overrode a refusal |
-| `reticle_kill_refused` | The listener is not a Reticle daemon and `--force` was not given. Exits `1` |
-| `reticle_kill_survived` | It survived `SIGKILL`. The port is still held. Exits `1` |
-| `reticle_kill_nothing_to_do` | No listener, and no live recorded pid |
-
-`listenerIdentified: false` means `lsof` could not run and the pid came from Reticle's records rather than from an observed listener. Those are different claims, so the field says which one you got.
-
-## Exit codes
-
-| Code | Meaning                                                            |
-| ---- | ------------------------------------------------------------------ |
-| `0`  | The port is free                                                   |
-| `1`  | The port is still held: refused, or the process survived `SIGKILL` |
-
-## Worked example
-
-```bash
-npx @reticlehq/server kill            # free 4400
-npx @reticlehq/server status          # confirm
-```