@reticlehq/server 3.8.1 → 3.9.0

package/dist/command/cli/ci-hint.d.ts

@@ -0,0 +1,44 @@
+/**
+ * One line at the end of `reticle gate`, `reticle verify` and `reticle affected` when they run in a
+ * CI runner or a container. It names the pull request check and the page that tells more about it.
+ *
+ * Rules: one line; never in an interactive terminal; never in a machine output mode; off with
+ * `RETICLE_NO_CI_HINT`. It goes to stderr. The stdout of `verify` carries the verdict lines that a
+ * pipeline reads, and stderr already carries the human notes of these commands.
+ *
+ * No network call. The latest version comes from the update manifest that the update check already
+ * caches on disk. When there is no cache, the line does not compare versions.
+ *
+ * The caller gives the automation hint (`currentAutomationHint`): `telemetry` already reaches this
+ * directory, so this directory does not reach back.
+ */
+import { AutomationHint } from '@reticlehq/core/telemetry';
+/** Set to `1` to stop the line. */
+export declare const CI_HINT_SILENCE_ENV = "RETICLE_NO_CI_HINT";
+/** The page that tells about the pull request check. */
+export declare const CI_HINT_URL = "https://reticle.sh/ci";
+export interface CiHintInput {
+    env: NodeJS.ProcessEnv;
+    automation: AutomationHint | undefined;
+    /** A person watches the output in a terminal. */
+    interactive: boolean;
+    /** The command writes output for a program to read (JSON, an agent hook). */
+    machineOutput: boolean;
+    currentVersion: string;
+    /** The latest version from the cached update check, if there is one. */
+    latestVersion: string | undefined;
+}
+/** The line, or undefined when it must not print. Pure. */
+export declare function ciHintLine(input: CiHintInput): string | undefined;
+export interface CiHintPorts {
+    env: NodeJS.ProcessEnv;
+    interactive: () => boolean;
+    latestVersion: () => string | undefined;
+    write: (text: string) => void;
+}
+/** Write the line to stderr when it applies. Call it last, after the command's own output. */
+export declare function writeCiHint(args: {
+    automation: AutomationHint | undefined;
+    machineOutput: boolean;
+    ports?: CiHintPorts;
+}): void;

package/dist/command/cli/ci-hint.js

@@ -0,0 +1,72 @@
+/**
+ * One line at the end of `reticle gate`, `reticle verify` and `reticle affected` when they run in a
+ * CI runner or a container. It names the pull request check and the page that tells more about it.
+ *
+ * Rules: one line; never in an interactive terminal; never in a machine output mode; off with
+ * `RETICLE_NO_CI_HINT`. It goes to stderr. The stdout of `verify` carries the verdict lines that a
+ * pipeline reads, and stderr already carries the human notes of these commands.
+ *
+ * No network call. The latest version comes from the update manifest that the update check already
+ * caches on disk. When there is no cache, the line does not compare versions.
+ *
+ * The caller gives the automation hint (`currentAutomationHint`): `telemetry` already reaches this
+ * directory, so this directory does not reach back.
+ */
+import { AutomationHint } from '@reticlehq/core/telemetry';
+import { parseMajor } from '@reticlehq/init';
+import { loadManifest } from '../update/update-checker.js';
+import { SERVER_VERSION } from '../version/identity/server-version.js';
+/** Set to `1` to stop the line. */
+export const CI_HINT_SILENCE_ENV = 'RETICLE_NO_CI_HINT';
+/** The page that tells about the pull request check. */
+export const CI_HINT_URL = 'https://reticle.sh/ci';
+/** The env values that do not turn the line off. */
+const NOT_SILENCED = new Set(['', '0', 'false']);
+/** The automation hints that get the line. A hosted workspace or an agent sandbox is a person. */
+const CI_HINT_AUTOMATION = new Set([
+    AutomationHint.CI_RUNNER,
+    AutomationHint.CONTAINER,
+]);
+const CiHintCopy = {
+    CHECK: `Reticle: a pull request check shows each replay, the run history and a merge block. Read ${CI_HINT_URL}`,
+    BEHIND: (current, latest) => `Reticle: this engine (${current}) is a major version behind ${latest}. Update it, then read ${CI_HINT_URL}`,
+};
+/** The line, or undefined when it must not print. Pure. */
+export function ciHintLine(input) {
+    if (!NOT_SILENCED.has(input.env[CI_HINT_SILENCE_ENV] ?? '')) {
+        return undefined;
+    }
+    if (input.interactive || input.machineOutput) {
+        return undefined;
+    }
+    if (input.automation === undefined || !CI_HINT_AUTOMATION.has(input.automation)) {
+        return undefined;
+    }
+    const current = parseMajor(input.currentVersion);
+    const latest = parseMajor(input.latestVersion);
+    if (current !== undefined && latest !== undefined && latest > current) {
+        return CiHintCopy.BEHIND(input.currentVersion, input.latestVersion ?? '');
+    }
+    return CiHintCopy.CHECK;
+}
+const realPorts = () => ({
+    env: process.env,
+    interactive: () => true === process.stdout.isTTY || true === process.stderr.isTTY,
+    latestVersion: () => loadManifest()?.latestVersion,
+    write: (text) => process.stderr.write(text),
+});
+/** Write the line to stderr when it applies. Call it last, after the command's own output. */
+export function writeCiHint(args) {
+    const ports = args.ports ?? realPorts();
+    const line = ciHintLine({
+        env: ports.env,
+        automation: args.automation,
+        interactive: ports.interactive(),
+        machineOutput: args.machineOutput,
+        currentVersion: SERVER_VERSION,
+        latestVersion: ports.latestVersion(),
+    });
+    if (line !== undefined) {
+        ports.write(`${line}\n`);
+    }
+}

package/dist/command/cli/cli-doctor.d.ts

@@ -1 +1,6 @@
-export declare function handleDoctor(port: number): Promise<void>;
+import type { StepReporter } from './setup-mcp-cli.js';
+/**
+ * `reticle doctor`, and with `fix`, `reticle doctor --fix`. Without `fix` it changes nothing and
+ * ends with how many rows `--fix` can repair. With `fix` the exit code is 1 while any row fails.
+ */
+export declare function handleDoctor(port: number, fix?: boolean, reportStep?: StepReporter): Promise<void>;

package/dist/command/cli/cli-doctor.js

@@ -11,7 +11,8 @@ import { daemonLine } from './doctor/doctor-daemon-line.js';
 import { projectWiringLine } from './doctor/doctor-project-line.js';
 import { hasProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
 import { sessionsLine } from './doctor/doctor-sessions-line.js';
-import { captureLookup, describeForeignHolder, findPortHolder } from './ports/port-holder.js';
+import { captureLookup, describeForeignHolder } from './ports/port-holder.js';
+import { identifyPortHolder } from '../daemon/port-state.js';
 import { chromiumHint } from './doctor/browser/chromium-hint.js';
 import { probeChromiumWithFallback } from '../../launch-chromium.js';
 import { SERVER_VERSION } from '../version/identity/server-version.js';
@@ -32,6 +33,8 @@ import { describeUnsynced } from '../../memory/cloud/unsynced-roots.js';
 import { machineUnsyncedRoots } from '../../memory/project/sync-status.js';
 import { attachState, describeAttachState } from '../../surface/mcp/attach-memory.js';
 import { agentLinkText } from './doctor/doctor-agent-link.js';
+import { countNeeded, fixFooter, runDoctorFix } from './doctor/doctor-fix.js';
+import { machineRepairs, mcpRegistrationRow, readLauncherLine, readMcpRegistration, } from './doctor-repairs.js';
 import { findOccupiedSiblings, siblingListenerNote } from './ports/sibling-ports.js';
 import { daemonsServingProjectElsewhere, resolveDaemonForProject, splitBrainNote, wrongDaemonNote, } from '../daemon/daemon-resolve.js';
 import { isAlive } from '../daemon/daemon.js';
@@ -73,9 +76,41 @@ function splitBrainLine(port, projectId) {
     const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)));
     return elsewhere ?? wrongDaemonNote(port, resolveDaemonForProject(projectId, home, isAlive));
 }
-export async function handleDoctor(port) {
+const writeLine = (s) => {
+    process.stdout.write(`${s}\n`);
+};
+/**
+ * `reticle doctor`, and with `fix`, `reticle doctor --fix`. Without `fix` it changes nothing and
+ * ends with how many rows `--fix` can repair. With `fix` the exit code is 1 while any row fails.
+ */
+export async function handleDoctor(port, fix = false, reportStep = () => { }) {
+    const repairs = machineRepairs(port, reportStep);
+    if (fix) {
+        const green = await runDoctorFix({
+            doctor: (show) => doctorLines(port, show),
+            repairs,
+            print: writeLine,
+        });
+        if (!green) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    await doctorLines(port, true);
+    const footer = fixFooter(await countNeeded(repairs));
+    if (footer !== undefined) {
+        writeLine('');
+        writeLine(footer);
+    }
+}
+/** Every doctor row, in order. Each row is printed as it is found when `show` is true. */
+async function doctorLines(port, show) {
+    const lines = [];
     const line = (s) => {
-        process.stdout.write(`${s}\n`);
+        lines.push(s);
+        if (show) {
+            writeLine(s);
+        }
     };
     line('reticle doctor');
     line(doctorRow(DoctorRow.NODE, process.version));
@@ -84,6 +119,7 @@ export async function handleDoctor(port) {
     let sessions;
     let daemonStatus;
     line(doctorRow(DoctorRow.CHROMIUM, chromiumHint(await probeChromiumWithFallback())));
+    line(mcpRegistrationRow(readMcpRegistration()));
     // 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.
@@ -126,7 +162,7 @@ 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(doctorRow(DoctorRow.DAEMON, `✗ ${describeForeignHolder(port, findPortHolder(port, captureLookup), pid)}`));
+        line(doctorRow(DoctorRow.DAEMON, `✗ ${describeForeignHolder(port, identifyPortHolder(port, captureLookup), pid)}`));
     }
     else {
         line(doctorRow(DoctorRow.DAEMON, `✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`));
@@ -167,6 +203,10 @@ export async function handleDoctor(port) {
     // would flip agent presence on a daemon with no agents attached.
     const foreign = presence === PortPresence.FOREIGN;
     line(doctorRow(DoctorRow.AGENT_LINK, agentLinkText({ split, attachAction, foreign })));
+    const launcher = readLauncherLine(process.cwd());
+    if (launcher !== undefined) {
+        line(doctorRow(DoctorRow.LAUNCHER, launcher));
+    }
     // Remaining half of #261. The SDK dialling a port we are not on is invisible as a refused inbound,
     // but a listener on a well-known Reticle port is visible. Report the observation; do not conclude
     // it is the daemon this app wants — somebody else's daemon looks the same from here.
@@ -263,6 +303,7 @@ export async function handleDoctor(port) {
     if (keychain !== undefined) {
         line(doctorRow(DoctorRow.DESKTOP, `⚠ ${keychain}`));
     }
+    return lines;
 }
 /**
  * Two rows: does each agent hand its prompts to Reticle, and does the daemon send this

package/dist/command/cli/cli-flow-commands.d.ts

@@ -9,6 +9,7 @@ import { type ChangedFiles } from '../../language/flows/change/git-changed.js';
 import { type ProjectId } from '@reticlehq/core';
 import { type FileSystemPort } from '../../memory/project/fs/fs-port.js';
 import { type NamedFlow } from '../../language/flows/change/flow-sources.js';
+import { type GateCompleted } from '@reticlehq/core/telemetry';
 /** Load the {name, steps} of every saved flow for the active project. */
 /** Explicit files plus, when --since is given, the git-changed files since that ref. */
 /**
@@ -30,4 +31,9 @@ export declare function handleGate(files: string[], since: string | undefined,
 /** Hook mode: prose for a human, and silence when there was simply nothing to check. */
 hook?: boolean, 
 /** Accept today's coverage levels as the best before judging, for a drop that was intended. */
-acceptCoverage?: boolean): Promise<void>;
+acceptCoverage?: boolean, 
+/**
+ * Called once with how the gate ended, on every path. `cli.ts` passes the `gate_completed`
+ * sender: telemetry already reaches this directory, so this directory does not reach back.
+ */
+reportGateCompleted?: (gate: GateCompleted) => void): Promise<void>;

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

@@ -5,7 +5,7 @@
  * opens first. These five functions form one cohesive group: they all read the flow store and report on
  * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
  */
-import { GateExit, MSG_GATE_NO_FLOWS, msgGateRegression, msgGateRefused, gateExitWith, } from './answers/gate-exit.js';
+import { GATE_OUTCOME, GateExit, MSG_GATE_NO_FLOWS, msgGateRegression, msgGateRefused, gateExitWith, } from './answers/gate-exit.js';
 import { knownRegression } from './known-regression.js';
 import { gateHookMessage, GATE_SKIP_ENV } from './answers/gate-hook-message.js';
 import { readProjectId } from './ports/resolve/cli-port.js';
@@ -25,6 +25,7 @@ import { detectDowngrades } from '../../judgement/outcome/assertion-integrity.js
 import { computeCoverage, flowCoverageReport } from '../../language/flows/suite/coverage.js';
 import { readFileSync, statSync } from 'node:fs';
 import { log } from '../../log.js';
+import { GateOutcome } from '@reticlehq/core/telemetry';
 /** Load the {name, steps} of every saved flow for the active project. */
 /** Explicit files plus, when --since is given, the git-changed files since that ref. */
 /**
@@ -34,8 +35,9 @@ import { log } from '../../log.js';
  */
 export async function resolveChangedFiles(files, since, cwd) {
     // No ref means no question was asked of git, which is not a failure to answer one.
-    if (since === undefined)
+    if (since === undefined) {
         return { files, failed: false };
+    }
     const changed = await changedFilesSince(since, cwd);
     return {
         files: [...new Set([...files, ...changed.files])],
@@ -56,8 +58,9 @@ export async function loadNamedFlows(fs, reticleRoot, projectId) {
     const flows = [];
     for (const name of await store.list(projectId)) {
         const loaded = await store.load(name, projectId);
-        if (loaded.ok)
+        if (loaded.ok) {
             flows.push({ name: loaded.value.name, steps: loaded.value.steps });
+        }
     }
     return flows;
 }
@@ -81,8 +84,9 @@ function atChangedPath(cwd, file, read) {
             return undefined;
         }
     };
-    if (isAbsolute(file))
+    if (isAbsolute(file)) {
         return attempt(file);
+    }
     const parts = file.split('/');
     const cwdParts = cwd.split(sep);
     for (let i = 0; i < parts.length; i += 1) {
@@ -91,8 +95,9 @@ function atChangedPath(cwd, file, read) {
             continue;
         }
         const found = attempt(join(cwd, ...parts.slice(i)));
-        if (found !== undefined)
+        if (found !== undefined) {
             return found;
+        }
     }
     return undefined;
 }
@@ -122,8 +127,9 @@ async function currentPassing(fs, root, flows, affected, changed) {
         const own = 0 === sources.length ? changed : changed.filter((f) => sourceMatchesChange(f, sources));
         const stale = affected.includes(name) &&
             own.some((f) => !((changedFileModifiedAt(cwd, f) ?? Infinity) < at));
-        if (!stale)
+        if (!stale) {
             passing.push(name);
+        }
     }
     return passing;
 }
@@ -131,7 +137,12 @@ export async function handleGate(files, since,
 /** Hook mode: prose for a human, and silence when there was simply nothing to check. */
 hook = false, 
 /** Accept today's coverage levels as the best before judging, for a drop that was intended. */
-acceptCoverage = false) {
+acceptCoverage = false, 
+/**
+ * Called once with how the gate ended, on every path. `cli.ts` passes the `gate_completed`
+ * sender: telemetry already reaches this directory, so this directory does not reach back.
+ */
+reportGateCompleted = () => undefined) {
     try {
         const fs = createNodeFileSystem();
         const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
@@ -207,13 +218,17 @@ acceptCoverage = false) {
         // once the exit code is: it said "pass": true over an exit of 1 or 3.
         const known = await knownRegression(reticleRoot);
         const regressed = known.broken;
-        const local = pass
-            ? GateExit.PASS
-            : result.pass && flowCoverage.outcome !== undefined
-                ? GateExit.NOTHING_TO_CHECK
-                : GateExit.FAIL;
+        let local = GateExit.FAIL;
+        if (pass) {
+            local = GateExit.PASS;
+        }
+        else if (result.pass && flowCoverage.outcome !== undefined) {
+            local = GateExit.NOTHING_TO_CHECK;
+        }
         // Fails closed in CI, not in an agent's stop hook, where it would block over a key, not a change.
         const code = gateExitWith(local, regressed?.length, !hook && known.refused !== undefined);
+        // What the gate judged, sent before a hook's skip can turn the exit code into a pass.
+        reportGateCompleted({ outcome: GATE_OUTCOME[code], flowsChecked: affected.length });
         log('reticle_gate', {
             pass: GateExit.PASS === code,
             uncovered: result.uncovered,
@@ -237,14 +252,18 @@ acceptCoverage = false) {
         // A regression the platform already knows fails the build here too, with `reticle runs
         // regression`'s code, so the gate is the one command CI needs. Best-effort: unlinked or offline
         // changes nothing.
-        if (regressed !== undefined && 0 < regressed.length)
+        if (regressed !== undefined && 0 < regressed.length) {
             log('reticle_gate_regression', { broken: regressed });
-        if (known.refused !== undefined)
+        }
+        if (known.refused !== undefined) {
             process.stderr.write(`${msgGateRefused(known.refused)}\n`);
-        if (GateExit.NOTHING_TO_CHECK === code && !hook)
+        }
+        if (GateExit.NOTHING_TO_CHECK === code && !hook) {
             process.stderr.write(`${MSG_GATE_NO_FLOWS}\n`);
-        if (GateExit.REGRESSION === code && !hook && regressed !== undefined)
+        }
+        if (GateExit.REGRESSION === code && !hook && regressed !== undefined) {
             process.stderr.write(`${msgGateRegression(regressed)}\n`);
+        }
         if (GateExit.PASS !== code) {
             process.exitCode = code;
             if (hook) {
@@ -267,13 +286,16 @@ acceptCoverage = false) {
                     unexecuted: result.unexecuted,
                     regressed: regressed?.length ?? 0,
                 });
-                if (message !== undefined)
+                if (message !== undefined) {
                     process.stderr.write(`${message}\n`);
+                }
             }
         }
     }
     catch (error) {
         log('reticle_gate_failed', { error: error instanceof Error ? error.message : String(error) });
+        // No flow count: the gate broke before it judged, so a count would describe nothing.
+        reportGateCompleted({ outcome: GateOutcome.ERROR });
         process.exitCode = GateExit.FAIL;
     }
 }

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

@@ -17,6 +17,7 @@
  * 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 } from '../daemon/binding/port-presence.js';
 import { type PortHolder } from './ports/port-holder.js';
 /** What the plan says to do with the port. */
 export declare const KillAction: {
@@ -62,6 +63,26 @@ export declare function planKill(input: {
  * wrong token, or no answer: the caller then sends the signal as before.
  */
 export declare function requestShutdown(port: number, token?: string | undefined): Promise<boolean>;
+/**
+ * How long the second look waits for `/status`. The usual probe gives up after 1 second, and on a
+ * busy machine a healthy daemon took longer than that. A daemon that answers slowly is busy, not
+ * stuck, and other agents can use it.
+ */
+export declare const WEDGED_STATUS_TIMEOUT_MS = 10000;
+/**
+ * Stop a Reticle daemon that holds `port` and does not answer. True when it stopped one (#1937).
+ *
+ * The MCP proxy used to move to another port when it found one. The app's SDK dials the old port,
+ * so the new daemon got no page. Stopping the stuck daemon keeps the port the app dials. The holder
+ * must have a Reticle daemon's command line, so a stranger and the proxy itself are never signalled.
+ */
+export declare function stopWedgedDaemon(port: number, deps?: {
+    /** `statusTimeoutMs`: how long to wait for `/status`. Absent: the usual short probe. */
+    presence: (statusTimeoutMs?: number) => Promise<PortPresence>;
+    holder: () => PortHolder | null;
+    kill: () => Promise<boolean>;
+    wait: (ms: number) => Promise<void>;
+}): Promise<boolean>;
 /** `reticle kill` — free the port. Resolves to whether the port is now free. */
 export declare function runKill(port: number, force: boolean): Promise<boolean>;
 export {};

package/dist/command/cli/cli-kill.js

@@ -22,7 +22,8 @@ import { isAlive, readPid, removePid } from '../daemon/daemon.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
 import { log } from '../../log.js';
 import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
-import { captureLookup, findPortHolder } from './ports/port-holder.js';
+import { captureLookup } from './ports/port-holder.js';
+import { identifyPortHolder } from '../daemon/port-state.js';
 import * as http from 'node:http';
 import { LOOPBACK_HOST, SHUTDOWN_PATH } from '@reticlehq/core';
 import { storedPairingToken } from '../../portal/bridge/pairing-token.js';
@@ -50,7 +51,8 @@ export function planKill(input) {
             return { action: KillAction.NOTHING, forced: false, identifiedListener: false };
         return { action: KillAction.KILL, pid: recordedPid, forced: false, identifiedListener: false };
     }
-    const ours = answersStatus || listener.pid === recordedPid;
+    // `reticleDaemon`: its command line says so, though it answers nothing and no pid file names it.
+    const ours = answersStatus || listener.pid === recordedPid || true === listener.reticleDaemon;
     if (ours || force) {
         return {
             action: KillAction.KILL,
@@ -156,12 +158,53 @@ async function terminate(pid, asked = false) {
  */
 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.';
+/**
+ * How long a daemon that holds the port gets to answer before it counts as stuck. A daemon that has
+ * just bound answers in far less, so a second look after this does not stop one that is starting.
+ */
+const WEDGED_GRACE_MS = 2_000;
+/**
+ * How long the second look waits for `/status`. The usual probe gives up after 1 second, and on a
+ * busy machine a healthy daemon took longer than that. A daemon that answers slowly is busy, not
+ * stuck, and other agents can use it.
+ */
+export const WEDGED_STATUS_TIMEOUT_MS = 10_000;
+/**
+ * Stop a Reticle daemon that holds `port` and does not answer. True when it stopped one (#1937).
+ *
+ * The MCP proxy used to move to another port when it found one. The app's SDK dials the old port,
+ * so the new daemon got no page. Stopping the stuck daemon keeps the port the app dials. The holder
+ * must have a Reticle daemon's command line, so a stranger and the proxy itself are never signalled.
+ */
+export async function stopWedgedDaemon(port, deps = {
+    presence: (statusTimeoutMs) => probePresence(port, {
+        tcpOpen: probeDaemon,
+        status: (p) => fetchStatus(p, LOOPBACK_HOST, false, statusTimeoutMs),
+    }),
+    holder: () => identifyPortHolder(port, captureLookup),
+    kill: () => runKill(port, false),
+    wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}) {
+    if (PortPresence.FOREIGN !== (await deps.presence())) {
+        return false;
+    }
+    const holder = deps.holder();
+    if (true !== holder?.reticleDaemon) {
+        return false;
+    }
+    await deps.wait(WEDGED_GRACE_MS);
+    if (PortPresence.FOREIGN !== (await deps.presence(WEDGED_STATUS_TIMEOUT_MS))) {
+        return false;
+    }
+    log('reticle_wedged_daemon_stopping', { port, pid: holder.pid });
+    return deps.kill();
+}
 /** `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),
+        listener: identifyPortHolder(port, captureLookup),
         recordedPid: null !== recorded && isAlive(recorded) ? recorded : null,
         answersStatus: presence === PortPresence.DAEMON,
         force,

package/dist/command/cli/cli-parse.d.ts

@@ -4,8 +4,9 @@
  * and re-exports this surface.
  */
 import { type ParsedFeedback } from './cli-parse-feedback.js';
+import { DAEMON_INNER_COMMAND } from '../daemon/daemon-argv.js';
 import { HEADED_FLAG, PORT_FLAG } from './cli-parse-grammar.js';
-export { HEADED_FLAG, PORT_FLAG };
+export { DAEMON_INNER_COMMAND, HEADED_FLAG, PORT_FLAG };
 export { DRIVE_FLAG, HEADLESS_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, } from './cli-parse-serve.js';
 export { AGENT_FLAG, BUG_FLAG, CONTACT_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from './cli-parse-feedback.js';
 import { CLI_USAGE } from './cli-usage.js';
@@ -19,7 +20,6 @@ export declare const TelemetryAction: {
     readonly DISABLE: "disable";
 };
 export type TelemetryAction = (typeof TelemetryAction)[keyof typeof TelemetryAction];
-export declare const DAEMON_INNER_COMMAND = "_daemon";
 /**
  * Every subcommand a person can type, as one closed vocabulary. Telemetry reports which one ran, and
  * this is what keeps that property low-cardinality and non-identifying: an argument we do not
@@ -110,8 +110,11 @@ export type CliResult = {
 } | {
     kind: 'doctor';
     port: number;
+    fix: boolean;
 } | {
     kind: 'setup-mcp';
+} | {
+    kind: 'setup-wait-agents';
 } | {
     kind: 'setup-install';
     runtimeSecs: number;

package/dist/command/cli/cli-parse.js

@@ -6,10 +6,11 @@
 import { parseFeedbackArgs } from './cli-parse-feedback.js';
 import { HEADLESS_FLAG, parseServeFlags } from './cli-parse-serve.js';
 import { parseVerifySuffix } from './cli-parse-verify.js';
+import { DAEMON_INNER_COMMAND } from '../daemon/daemon-argv.js';
 import { HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, retiredFlag, unknownArgument, CLOUD_COMMANDS, REMOVED_COMMANDS, removedNote, } from './cli-parse-grammar.js';
 // Re-exported because the daemon's own argv builder reaches for these through this module, which is
 // where the grammar has always lived as far as every caller is concerned.
-export { HEADED_FLAG, PORT_FLAG };
+export { DAEMON_INNER_COMMAND, HEADED_FLAG, PORT_FLAG };
 export { DRIVE_FLAG, HEADLESS_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, } from './cli-parse-serve.js';
 import { FORCE_FLAG } from './cli-kill.js';
 // Re-exported so every existing importer of these flags is unaffected by the file split.
@@ -44,6 +45,7 @@ const TELEMETRY_COMMAND = 'telemetry';
 const FEEDBACK_COMMAND = 'feedback';
 const DOCTOR_COMMAND = 'doctor';
 const SETUP_COMMAND = 'setup';
+const SETUP_WAIT_AGENTS = 'wait-agents';
 /** `reticle hook`: the agent prompt hook. `cli.ts` runs it before this parser, and before telemetry. */
 export const HOOK_COMMAND = 'hook';
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
@@ -52,7 +54,6 @@ export const TelemetryAction = {
     ENABLE: 'enable',
     DISABLE: 'disable',
 };
-export const DAEMON_INNER_COMMAND = '_daemon';
 /**
  * Every subcommand a person can type, as one closed vocabulary. Telemetry reports which one ran, and
  * this is what keeps that property low-cardinality and non-identifying: an argument we do not
@@ -138,6 +139,7 @@ export function knownCommand(arg) {
     return KNOWN_COMMANDS.has(arg) ? arg : (COMMAND_FLAG_ALIASES.get(arg) ?? UNKNOWN_COMMAND);
 }
 const QUIET_FLAG = '--quiet';
+const FIX_FLAG = '--fix';
 const DRY_RUN_FLAG = '--dry-run';
 const YES_FLAG = '--yes';
 const NO_MCP_FLAG = '--no-mcp';
@@ -589,7 +591,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case DOCTOR_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
-            return { kind: 'doctor', port };
+            return { kind: 'doctor', port, fix: rest.includes(FIX_FLAG) };
         }
         /*
          * `setup mcp` — register the MCP server with the coding agents on this machine.
@@ -621,8 +623,11 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                     mcp: !rest.includes('--no-mcp'),
                 };
             }
-            // Only `mcp` today. A bare `reticle setup` falls to help rather than guessing, because the
-            // next subcommand here will not be a synonym for this one.
+            // `setup wait-agents` — the installer's last step: wait for the agents to connect.
+            if (SETUP_WAIT_AGENTS === what) {
+                return { kind: 'setup-wait-agents' };
+            }
+            // A bare `reticle setup` falls to help rather than guessing.
             if (what !== 'mcp') {
                 return { kind: 'help', topic: SETUP_COMMAND };
             }

package/dist/command/cli/cli-usage.js

@@ -92,7 +92,7 @@ const COMMANDS = [
     {
         name: 'verify',
         synopsis: 'verify <url> [--explore] [--expect <json>]',
-        summary: 'Check the saved flows against the running app; exit 0 means pass',
+        summary: 'Check saved flows, or one claim with --expect, against the running app; exit 0 = pass',
         group: HelpGroup.CHECK,
         detail: VERIFY_DETAIL,
     },
@@ -110,8 +110,9 @@ const COMMANDS = [
     },
     {
         name: 'doctor',
-        synopsis: 'doctor [--port N]',
+        synopsis: 'doctor [--fix] [--port N]',
         summary: 'Find what is wrong with the setup, and what is missing from coverage',
+        detail: '--fix repairs what Reticle can repair safely, and names the step for the rest.',
         group: HelpGroup.MACHINE,
     },
     {

package/dist/command/cli/cli-verify.d.ts

@@ -230,5 +230,10 @@ export declare function handleVerify(parsed: {
     resultsJson?: string;
     /** Acknowledge the replay guard's destructive steps ("Place order") for this run only. */
     confirmDangerous?: boolean;
-}): void;
+}, 
+/**
+ * Called once, after the last verdict line and before the exit. `cli.ts` passes the CI line:
+ * `telemetry` already reaches this directory, so this directory does not reach back.
+ */
+beforeExit?: () => void): void;
 export {};