@reticlehq/server 3.8.2 → 3.10.0

package/dist/command/cli/adhoc-verdict.d.ts

@@ -1,3 +1,5 @@
+import { type ToolCaller } from './daemon-link/daemon-client.js';
+export { acquireLease, connectOverSse, endpointFor, refusalText, releaseLease, verdictOf, type ToolCaller, } from './daemon-link/daemon-client.js';
 /**
  * A verdict from the CLI, against the daemon that is already running.
  *
@@ -83,54 +85,12 @@ root?: string): Promise<{
 } | {
     failed: string[];
 }>;
-/**
- * Open `url` in a Reticle-leased browser unconditionally: `{ leased }` names the lease, which the
- * caller hands to `releaseLease`; `{ failed }` is the lease's own refusal, as lines to print.
- * `init`'s connect proof on a machine with no system browser takes this path directly.
- */
-export declare function acquireLease(caller: ToolCaller, url: string, 
-/** Open it in a window somebody can watch, whatever the daemon was started as. */
-headed?: boolean, 
-/** The `.reticle` the lease's runs belong in: the caller's project, not wherever the page resolves. */
-root?: string): Promise<{
-    leased: string;
-    zeroInstall: boolean;
-} | {
-    failed: string[];
-}>;
-/** Hand back a lease `leaseIfNoTab` opened. Best-effort: an expired lease is already gone. */
-export declare function releaseLease(caller: ToolCaller, sessionId: string): Promise<void>;
 /**
  * The longest one `reticle_assert` call waits: its `timeout_ms` cap, one MCP request less slack.
  * Named here rather than imported, because this directory does not reach the tool layer; pinned
  * equal to `MAX_BLOCKING_WAIT_MS` by adhoc-verdict.test.ts so the two cannot drift apart.
  */
 export declare const ASSERT_MAX_WAIT_MS = 55000;
-/** The narrow slice of an MCP client this needs — one call, then close. */
-export interface ToolCaller {
-    call(name: string, args: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
-    close(): Promise<void>;
-}
-export declare function endpointFor(port: number, token: string | undefined): URL;
-export declare function connectOverSse(endpoint: URL): Promise<ToolCaller>;
-/**
- * The report object an MCP tool result carries, or undefined when the shape is not one.
- *
- * `field` is the key that makes a payload the report this caller wants: `verified` for a one-shot
- * verdict, `status` for a suite. It is a parameter rather than a fixed name because the suite path
- * reproduced this function's own incident the moment it reused it — the headline printed
- * `unverifiable` while the JSON under it said `"status":"fail"` with 74 failing flows, because a
- * suite report has no `verified` key and the text reader would only accept one that did.
- */
-export declare function verdictOf(result: unknown, field?: string): Record<string, unknown> | undefined;
-/**
- * The tool's own words when it refused, rather than the envelope carrying them.
- *
- * A refusal from these tools is the most useful text they produce — it names the cause and the next
- * action — and printing the MCP result object around it buries that in JSON escaping. The reader is
- * at a terminal; give them the sentence.
- */
-export declare function refusalText(result: unknown): string | undefined;
 /**
  * Navigate (optionally) and assert, against the daemon already on this port.
  *
@@ -146,4 +106,3 @@ export declare function runAdhocVerdict(options: AdhocVerdictOptions): Promise<A
  * caller that wants the finished report asks again by `runId` rather than starting a second drive.
  */
 export declare function exploreToEnd(caller: ToolCaller, args: Record<string, unknown>, budgetMs: number, now?: () => number): Promise<unknown>;
-export {};

package/dist/command/cli/adhoc-verdict.js

@@ -1,19 +1,8 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { CLI_CLIENT_NAME } from '../../judgement/runs/verification-sync.js';
-import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
-import { DEFAULT_ASSERT_TIMEOUT_MS, LOOPBACK_HOST, MCP_SSE_PATH } from '@reticlehq/core';
-import { TOKEN_QUERY_PARAM } from '../../portal/bridge/token-auth.js';
-import { ReticleTool, asString as asText } from '@reticlehq/core';
+import { DEFAULT_ASSERT_TIMEOUT_MS, ReticleTool, asString as asText } from '@reticlehq/core';
 import { decideOpen } from './launch/cli-launch.js';
-/** The lease tool is reached through `reticle_run`, the route that works on every tool profile. */
-const LeaseAction = { ACQUIRE: 'acquire', RELEASE: 'release' };
-/**
- * Generous on purpose: on a machine with no Chrome, Edge or Playwright Chromium the FIRST lease
- * downloads Chromium before it can open anything (see launch-chromium), which outlives the MCP
- * client's 60s default and would report a timeout for a lease that was about to succeed.
- */
-const LEASE_TIMEOUT_MS = 300_000;
-const leaseFailedLine = (url) => `could not open ${url} in a Reticle browser, so nothing was checked:`;
+import { acquireLease, connectOverSse, endpointFor, refusalText, releaseLease, verdictOf, } from './daemon-link/daemon-client.js';
+// Re-exported so every existing importer of the daemon link through this file is unaffected.
+export { acquireLease, connectOverSse, endpointFor, refusalText, releaseLease, verdictOf, } from './daemon-link/daemon-client.js';
 /**
  * Open `url` in a Reticle-leased browser when the daemon has no tab on its origin.
  *
@@ -64,48 +53,6 @@ function sameDocument(a, b) {
         return false;
     }
 }
-/**
- * Open `url` in a Reticle-leased browser unconditionally: `{ leased }` names the lease, which the
- * caller hands to `releaseLease`; `{ failed }` is the lease's own refusal, as lines to print.
- * `init`'s connect proof on a machine with no system browser takes this path directly.
- */
-export async function acquireLease(caller, url, 
-/** Open it in a window somebody can watch, whatever the daemon was started as. */
-headed, 
-/** The `.reticle` the lease's runs belong in: the caller's project, not wherever the page resolves. */
-root) {
-    const acquired = await caller.call(ReticleTool.RUN, {
-        tool: ReticleTool.LEASE,
-        args: {
-            action: LeaseAction.ACQUIRE,
-            url,
-            ...(true === headed ? { headed } : {}),
-            ...(root === undefined ? {} : { root }),
-        },
-    }, LEASE_TIMEOUT_MS);
-    const report = verdictOf(acquired, 'sessionId');
-    const sessionId = report?.['sessionId'];
-    // `zeroInstall`: the page never dialled in, so the lease supplied Reticle's own reader.
-    if ('string' === typeof sessionId) {
-        return { leased: sessionId, zeroInstall: true === report?.['zeroInstall'] };
-    }
-    const why = verdictOf(acquired, 'error')?.['error'];
-    return {
-        failed: [
-            leaseFailedLine(url),
-            'string' === typeof why ? why : (refusalText(acquired) ?? JSON.stringify(acquired)),
-        ],
-    };
-}
-/** Hand back a lease `leaseIfNoTab` opened. Best-effort: an expired lease is already gone. */
-export async function releaseLease(caller, sessionId) {
-    await caller
-        .call(ReticleTool.RUN, {
-        tool: ReticleTool.LEASE,
-        args: { action: LeaseAction.RELEASE, sessionId },
-    })
-        .catch(() => undefined);
-}
 /** How long `--expect` waits without a `--timeout`: the wait form's own default. */
 const DEFAULT_EXPECT_WAIT_MS = DEFAULT_ASSERT_TIMEOUT_MS;
 /** Room for the daemon to answer after the wait it was given has run out. */
@@ -125,31 +72,55 @@ function runRefusal(result) {
     const said = verdictOf(result, 'error')?.['error'];
     return refusalText(result) ?? ('string' === typeof said ? said : undefined);
 }
+/** The `reticle_assert` action that waits for a predicate within a budget. */
+const ASSERT_WAIT_ACTION = 'wait';
+/**
+ * The refusal of a daemon whose `reticle_assert` takes no `action`: every surface but the merged
+ * one, where `reticle_wait_for` is still a tool of its own.
+ */
+const REFUSES_ACTION = /unknown parameter[^\n]*\baction\b/i;
+/**
+ * One wait for the predicate, through `reticle_assert { action: "wait" }` (#2144).
+ *
+ * It went through `reticle_run { tool: "reticle_wait_for" }`. That name was merged into
+ * `reticle_assert`, and a 3.9.0 daemon answered it with "reticle_wait_for was merged into
+ * reticle_assert", so every `--expect` with a long `--timeout` printed `verified: unknown`. A daemon
+ * whose `reticle_assert` takes no action still has `reticle_wait_for` as a tool, so that is the
+ * one place the name is still used.
+ */
+async function waitOnce(caller, args, timeoutMs) {
+    const waited = await caller.call(ReticleTool.ASSERT, { action: ASSERT_WAIT_ACTION, ...args }, timeoutMs);
+    const refused = runRefusal(waited);
+    if (refused === undefined || !REFUSES_ACTION.test(refused)) {
+        return waited;
+    }
+    return caller.call(ReticleTool.RUN, { tool: ReticleTool.WAIT_FOR, args }, timeoutMs);
+}
 /**
  * Wait for the expectation, then grade it with ONE `reticle_assert` (#1533).
  *
- * The grade is `reticle_assert`'s, never the wait's: it journals, captures the assertion, and
- * carries `verifiedReason`, contradictions and coverage, which `reticle_wait_for` does not.
- * `reticle_assert` already waits when `timeout_ms > 0`, up to one request. A longer budget spends
- * the part one assert cannot hold in `reticle_wait_for` first, through `reticle_run` (the route
- * every tool profile has), following `resume_ms`, and then asserts. No `since` is passed by
- * either: both default to the same last-act cursor, and nothing here acts in between.
+ * The grade is the final `reticle_assert`'s: it journals, captures the assertion, and carries
+ * `verifiedReason`, contradictions and coverage. `reticle_assert` already waits when
+ * `timeout_ms > 0`, up to one request. A longer budget spends the part one assert cannot hold in
+ * `reticle_assert { action: "wait" }` first, following `resume_ms`, and then asserts. No `since` is
+ * passed by either: both default to the same last-act cursor, and nothing here acts in between.
  */
 async function waitForExpectation(caller, predicate, pin, timeoutMs) {
     const budget = Math.max(0, timeoutMs ?? DEFAULT_EXPECT_WAIT_MS);
     let settle = budget - ASSERT_MAX_WAIT_MS;
     while (0 < settle) {
-        const waited = await caller.call(ReticleTool.RUN, { tool: ReticleTool.WAIT_FOR, args: { predicate, timeout_ms: settle, ...pin } }, 
-        // The daemon blocks no longer than one request allows and answers resume_ms past that, so
-        // the budget plus slack always outlasts the call.
-        settle + WAIT_CALL_SLACK_MS);
+        // The daemon blocks no longer than one request allows and answers resume_ms past that, so the
+        // budget plus slack always outlasts the call.
+        const waited = await waitOnce(caller, { predicate, timeout_ms: settle, ...pin }, settle + WAIT_CALL_SLACK_MS);
         const refused = runRefusal(waited);
-        if (refused !== undefined)
+        if (refused !== undefined) {
             return { refused };
-        // By `pass`, which every wait answers with: a "not yet" carries no `verified`.
-        const report = verdictOf(waited, 'pass');
+        }
+        // In the shape `reticle_assert` answers: a final answer carries `verified`, and only a wait
+        // that the per-call cap stopped carries `resume_ms` without one.
+        const report = verdictOf(waited, 'resume_ms');
         const resume = report?.['resume_ms'];
-        if (true === report?.['pass'] ||
+        if (report?.['verified'] !== undefined ||
             'number' !== typeof resume ||
             resume <= 0 ||
             resume >= settle) {
@@ -164,91 +135,6 @@ async function waitForExpectation(caller, predicate, pin, timeoutMs) {
 }
 /** `verified` is the only field that decides the exit code. Everything else is for the reader. */
 const PROVED = 'yes';
-export function endpointFor(port, token) {
-    const url = new URL(`http://${LOOPBACK_HOST}:${String(port)}${MCP_SSE_PATH}`);
-    if (token !== undefined && token.length > 0)
-        url.searchParams.set(TOKEN_QUERY_PARAM, token);
-    return url;
-}
-export async function connectOverSse(endpoint) {
-    const client = new Client({ name: CLI_CLIENT_NAME, version: '1' }, { capabilities: {} });
-    await client.connect(new SSEClientTransport(endpoint));
-    return {
-        call: async (name, args, timeoutMs) => await client.callTool({ name, arguments: args }, undefined, timeoutMs === undefined ? undefined : { timeout: timeoutMs }),
-        close: async () => {
-            await client.close();
-        },
-    };
-}
-/**
- * The report object an MCP tool result carries, or undefined when the shape is not one.
- *
- * `field` is the key that makes a payload the report this caller wants: `verified` for a one-shot
- * verdict, `status` for a suite. It is a parameter rather than a fixed name because the suite path
- * reproduced this function's own incident the moment it reused it — the headline printed
- * `unverifiable` while the JSON under it said `"status":"fail"` with 74 failing flows, because a
- * suite report has no `verified` key and the text reader would only accept one that did.
- */
-export function verdictOf(result, field = 'verified') {
-    const structured = result?.structuredContent;
-    if ('object' === typeof structured && null !== structured) {
-        return structured;
-    }
-    // A daemon that answers with the verdict as TEXT left this undefined, so the headline read
-    // `verified: unknown` while the JSON printed underneath it said `"verified":"no"` — one response
-    // giving two answers to the same question. The text is the same object, so read it.
-    return verdictFromText(result, field);
-}
-/** The report object inside an MCP text part, when the result carried it there instead. */
-function verdictFromText(result, field) {
-    const content = result?.content;
-    if (!Array.isArray(content))
-        return undefined;
-    for (const part of content) {
-        const text = part.text;
-        if ('string' !== typeof text)
-            continue;
-        try {
-            const parsed = JSON.parse(text);
-            // Only a shape that actually carries a verdict — anything else stays `unknown`, which is the
-            // honest answer for a result this function could not read.
-            if ('object' === typeof parsed && null !== parsed && field in parsed) {
-                return parsed;
-            }
-        }
-        catch {
-            /* Not JSON; the next part may still be. */
-        }
-    }
-    return undefined;
-}
-/**
- * The tool's own words when it refused, rather than the envelope carrying them.
- *
- * A refusal from these tools is the most useful text they produce — it names the cause and the next
- * action — and printing the MCP result object around it buries that in JSON escaping. The reader is
- * at a terminal; give them the sentence.
- */
-export function refusalText(result) {
-    const r = result;
-    if (true !== r?.isError || !Array.isArray(r.content))
-        return undefined;
-    const text = r.content
-        .map((part) => part.text)
-        .filter((t) => 'string' === typeof t)
-        .join('\n');
-    if (0 === text.length)
-        return undefined;
-    // The tools answer with a JSON envelope whose `error` is the sentence; unwrap when it is one.
-    try {
-        const parsed = JSON.parse(text);
-        const inner = parsed?.error;
-        return 'string' === typeof inner ? inner : text;
-    }
-    catch {
-        return text;
-    }
-}
 /**
  * Navigate (optionally) and assert, against the daemon already on this port.
  *
@@ -288,8 +174,9 @@ export async function runAdhocVerdict(options) {
         }
         if (url !== undefined && options.sessionId === undefined && options.sessions !== undefined) {
             const opened = await leaseIfNoTab(caller, url, options.sessions, options.root);
-            if ('failed' in opened)
+            if ('failed' in opened) {
                 return { code: 1, lines: ['verified: unknown', ...opened.failed] };
+            }
             leased = opened.leased;
             alreadyAt = true === opened.alreadyAt;
         }
@@ -301,8 +188,9 @@ export async function runAdhocVerdict(options) {
             await caller.call(ReticleTool.NAVIGATE, { url, ...pin });
         }
         const waited = await waitForExpectation(caller, options.predicate, pin, options.timeoutMs);
-        if ('refused' in waited)
+        if ('refused' in waited) {
             return { code: 1, lines: ['verified: unknown', waited.refused] };
+        }
         const result = waited.result;
         const refusal = refusalText(result);
         if (refusal !== undefined) {
@@ -330,8 +218,9 @@ export async function runAdhocVerdict(options) {
         };
     }
     finally {
-        if (leased !== undefined)
+        if (leased !== undefined) {
             await releaseLease(caller, leased);
+        }
         await caller.close().catch(() => undefined);
     }
 }
@@ -357,8 +246,9 @@ export async function exploreToEnd(caller, args, budgetMs, now = Date.now) {
     for (;;) {
         const report = verdictOf(result, 'status');
         const runId = report?.['runId'];
-        if (DRIVE_RUNNING !== report?.['status'] || 'string' !== typeof runId || now() >= deadline)
+        if (DRIVE_RUNNING !== report?.['status'] || 'string' !== typeof runId || now() >= deadline) {
             return result;
+        }
         result = await ask({ runId });
     }
 }

package/dist/command/cli/answers/gate-exit.d.ts

@@ -1,3 +1,4 @@
+import { GateOutcome } from '@reticlehq/core/telemetry';
 /**
  * What `reticle gate` means by its exit code.
  *
@@ -21,14 +22,17 @@ export declare const GateExit: {
     /** The platform knows a flow that passed before and is broken now: `reticle runs regression`'s code. */
     readonly REGRESSION: 3;
 };
+export type GateExit = (typeof GateExit)[keyof typeof GateExit];
+/** The `gate_completed` outcome for each exit code. A gate that throws reports `error` instead. */
+export declare const GATE_OUTCOME: Readonly<Record<GateExit, GateOutcome>>;
 /**
  * The gate's code once the platform has been asked about regressions: a known one fails the build
  * with `reticle runs regression`'s code, whatever the local answer was, so the gate is the one
  * command CI needs. `undefined` (not linked, or the platform did not answer) changes nothing.
  */
-export declare function gateExitWith(local: number, regressed: number | undefined, 
+export declare function gateExitWith(local: GateExit, regressed: number | undefined, 
 /** The platform the project is linked to refused its credential: the gate fails closed. */
-refused?: boolean): number;
+refused?: boolean): GateExit;
 /**
  * Said when the linked platform refused the key. A CI pipeline whose key was revoked stayed green
  * and silent: the gate lost the platform's regression report and the only trace was a log line.

package/dist/command/cli/answers/gate-exit.js

@@ -1,3 +1,4 @@
+import { GateOutcome } from '@reticlehq/core/telemetry';
 /**
  * What `reticle gate` means by its exit code.
  *
@@ -21,6 +22,13 @@ export const GateExit = {
     /** The platform knows a flow that passed before and is broken now: `reticle runs regression`'s code. */
     REGRESSION: 3,
 };
+/** The `gate_completed` outcome for each exit code. A gate that throws reports `error` instead. */
+export const GATE_OUTCOME = {
+    [GateExit.PASS]: GateOutcome.PASS,
+    [GateExit.FAIL]: GateOutcome.FAIL,
+    [GateExit.NOTHING_TO_CHECK]: GateOutcome.NOTHING_TO_CHECK,
+    [GateExit.REGRESSION]: GateOutcome.REGRESSION,
+};
 /**
  * The gate's code once the platform has been asked about regressions: a known one fails the build
  * with `reticle runs regression`'s code, whatever the local answer was, so the gate is the one
@@ -29,8 +37,9 @@ export const GateExit = {
 export function gateExitWith(local, regressed, 
 /** The platform the project is linked to refused its credential: the gate fails closed. */
 refused = false) {
-    if (regressed !== undefined && 0 < regressed)
+    if (regressed !== undefined && 0 < regressed) {
         return GateExit.REGRESSION;
+    }
     return refused && GateExit.PASS === local ? GateExit.FAIL : local;
 }
 /**
@@ -52,8 +61,9 @@ export const MSG_GATE_NO_FLOWS = 'Reticle gate: no saved flows here, so there wa
  */
 export function msgGateRegression(broken) {
     const names = broken.map((entry) => {
-        if ('string' === typeof entry)
+        if ('string' === typeof entry) {
             return entry;
+        }
         const record = 'object' === typeof entry && null !== entry ? entry : {};
         const name = record['flowName'] ?? record['name'];
         const was = record['previousStatus'];

package/dist/command/cli/answers/mcp-connection-hint.d.ts

@@ -0,0 +1,2 @@
+/** The same connection hint for a running daemon in `status` and `doctor`. */
+export declare function mcpConnectionHint(port: number): string;

package/dist/command/cli/answers/mcp-connection-hint.js

@@ -0,0 +1,6 @@
+import { LOOPBACK_HOST, MCP_SSE_PATH } from '@reticlehq/core';
+const MCP_CONNECTION_HINT = 'If your agent has no reticle_* tools, connect over HTTP/SSE at';
+/** The same connection hint for a running daemon in `status` and `doctor`. */
+export function mcpConnectionHint(port) {
+    return `${MCP_CONNECTION_HINT} http://${LOOPBACK_HOST}:${String(port)}${MCP_SSE_PATH}`;
+}

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';
@@ -70,12 +73,44 @@ function asIdentity(payload) {
  */
 function splitBrainLine(port, projectId) {
     const home = reticleStateHome();
-    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)));
+    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)), { projectId, home });
     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