@reticlehq/server 3.8.2 → 3.10.0

package/dist/command/cli/daemon-link/daemon-client.js

@@ -0,0 +1,205 @@
+/**
+ * The CLI's link to a running daemon: an MCP client over the daemon's HTTP/SSE transport, the lease
+ * calls that open and close a tab, and the readers of a tool result.
+ *
+ * Split out of `adhoc-verdict.ts` so a caller that needs only the link (`reticle compare`, and the
+ * `reticle_verify { action: "compare" }` tool that runs the same compare) does not reach the
+ * browser launcher, and through it the installer.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { LOOPBACK_HOST, MCP_SSE_PATH, ReticleTool, asString as asText } from '@reticlehq/core';
+import { CLI_CLIENT_NAME } from '../../../judgement/runs/verification-sync.js';
+import { TOKEN_QUERY_PARAM } from '../../../portal/bridge/token-auth.js';
+import { LEASE_KEPT_SENTENCE, LEASE_RELEASED_SENTENCE } from '../../../surface/tools/lease-hint.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;
+export const leaseFailedLine = (url) => `could not open ${url} in a Reticle browser, so nothing was checked:`;
+/**
+ * Why a lease's tab is not ready: its `notReadyReason`, then its `hint`, when it gave them. The CLI
+ * released the lease, so the hint's kept-lease sentence becomes the released-lease sentence.
+ */
+function notReadyLine(report) {
+    const reason = asText(report?.['notReadyReason']);
+    const hint = asText(report?.['hint'])?.replace(LEASE_KEPT_SENTENCE, LEASE_RELEASED_SENTENCE);
+    const head = reason === undefined ? 'the tab did not connect.' : `the tab did not connect (${reason}).`;
+    return hint === undefined ? head : `${head} ${hint}`;
+}
+/**
+ * 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 ask = (withRoot) => caller.call(ReticleTool.RUN, {
+        tool: ReticleTool.LEASE,
+        args: {
+            action: LeaseAction.ACQUIRE,
+            url,
+            ...(true === headed ? { headed } : {}),
+            ...(withRoot && root !== undefined ? { root } : {}),
+        },
+    }, LEASE_TIMEOUT_MS);
+    let acquired = await ask(true);
+    // A daemon from an older release does not know `root` and refuses the whole call, so the page
+    // was never opened. Ask once more without it: the lease works, only its runs land where that
+    // daemon puts them.
+    if (root !== undefined && REFUSES_ROOT.test(refusalOf(acquired) ?? '')) {
+        acquired = await ask(false);
+    }
+    const report = verdictOf(acquired, 'sessionId');
+    const sessionId = report?.['sessionId'];
+    // `ready: false` still carries a sessionId, but no session is registered under it. Driving it
+    // answered "names no session" and hid the cause the lease gave. Only an explicit false counts.
+    if ('string' === typeof sessionId && false === report?.['ready']) {
+        await releaseLease(caller, sessionId);
+        return { failed: [leaseFailedLine(url), notReadyLine(report)] };
+    }
+    // `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'] };
+    }
+    return {
+        failed: [leaseFailedLine(url), refusalOf(acquired) ?? JSON.stringify(acquired)],
+    };
+}
+/** The lease refusal an older daemon answers when it does not know the `root` argument. */
+const REFUSES_ROOT = /unknown parameter[^\n]*\broot\b/i;
+/** What the lease said no with: the `error` of its payload, else the refusal text. */
+function refusalOf(acquired) {
+    const why = verdictOf(acquired, 'error')?.['error'];
+    return 'string' === typeof why ? why : refusalText(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);
+}
+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;
+    }
+}
+/** The payload of a tool result: its structured content, or the JSON object in its text. */
+export function payloadOf(result) {
+    const structured = result?.structuredContent;
+    if ('object' === typeof structured && null !== structured) {
+        return structured;
+    }
+    const content = result?.content;
+    for (const part of Array.isArray(content) ? content : []) {
+        const text = part.text;
+        if ('string' !== typeof text) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            if ('object' === typeof parsed && null !== parsed) {
+                return parsed;
+            }
+        }
+        catch {
+            // Not JSON; the next part may be.
+        }
+    }
+    return {};
+}

package/dist/command/cli/doctor/browser/chromium-hint.d.ts

@@ -48,6 +48,11 @@ export interface ChromiumProbe {
      * `Microsoft Edge`) — see launch-chromium. Present only when `exists` is false and one was found.
      */
     fallback?: string | undefined;
+    /**
+     * Where Reticle looked for an installed Chrome or Edge when neither Playwright's build nor a
+     * fallback browser was found.
+     */
+    fallbackPaths?: readonly string[] | undefined;
     /** `executablePath` came from RETICLE_CHROMIUM_PATH, so the bundled build is not in play at all. */
     configured?: boolean | undefined;
     /** Why that configured executable cannot be launched. Present only when `exists` is false. */
@@ -118,7 +123,7 @@ export declare function parseChromiumRevision(executablePath: string): {
  * `executablePath()` resolves the revision the daemon will actually launch AND the root it will look
  * in, which is why the probe never reads `PLAYWRIGHT_BROWSERS_PATH` itself.
  */
-export declare function probeChromium(): Promise<ChromiumProbe>;
+export declare function probeChromium(exists?: (path: string) => boolean): Promise<ChromiumProbe>;
 /** The bundled playwright's version, or undefined if it cannot be read (the hint then goes unpinned). */
 export declare function bundledPlaywrightVersion(): string | undefined;
 /**

package/dist/command/cli/doctor/browser/chromium-hint.js

@@ -173,7 +173,7 @@ function installedRevisions(root) {
  * `executablePath()` resolves the revision the daemon will actually launch AND the root it will look
  * in, which is why the probe never reads `PLAYWRIGHT_BROWSERS_PATH` itself.
  */
-export async function probeChromium() {
+export async function probeChromium(exists = existsSync) {
     const searched = playwrightResolutionRoots();
     try {
         const { chromium } = await import('playwright');
@@ -181,14 +181,14 @@ export async function probeChromium() {
         const parsed = parseChromiumRevision(executablePath);
         return {
             executablePath,
-            exists: existsSync(executablePath),
+            exists: exists(executablePath),
             playwrightVersion: bundledPlaywrightVersion(),
             ...(null === parsed
                 ? {}
                 : {
                     wantedRevision: parsed.revision,
                     browsersRoot: parsed.root,
-                    installedRevisions: installedRevisions(parsed.root),
+                    installedRevisions: exists === existsSync ? installedRevisions(parsed.root) : [],
                 }),
         };
     }
@@ -248,6 +248,9 @@ export function bundledPlaywrightVersion() {
 export function chromiumPreflightRefusal(probe) {
     if (probe.exists)
         return undefined;
+    if (undefined !== probe.fallback) {
+        return undefined;
+    }
     if (true === probe.configured && probe.executablePath !== undefined) {
         return configuredChromiumRefusal(probe.executablePath, probe.problem ?? ChromiumPathProblem.MISSING);
     }
@@ -281,16 +284,19 @@ export function chromiumHint(probe) {
         const where = 0 === searched.length ? '' : ` — looked in ${searched.join(', ')}`;
         return `✗ the playwright package is not installed${where}; run: ${command}`;
     }
+    const fallbackPaths = probe.fallbackPaths ?? [];
     const present = probe.installedRevisions ?? [];
     if (present.length > 0 && probe.wantedRevision !== undefined) {
         // The reported machine. Every fact here is one the reader could not otherwise get: what is
         // wanted, what is there, and where "there" is. `npx playwright install chromium` unpinned adds
         // a build to this list and changes nothing, which is what happened.
+        const fallbackWhere = 0 === fallbackPaths.length ? '' : `; also looked for ${fallbackPaths.join(', ')}`;
         return (`✗ wrong revision — the bundled playwright wants ${probe.wantedRevision}; ` +
-            `${probe.browsersRoot ?? ''} holds ${present.join(', ')}. run: ${command}`);
+            `${probe.browsersRoot ?? ''} holds ${present.join(', ')}${fallbackWhere}. run: ${command}`);
     }
     // Naming the path is what turns "missing" from a verdict into evidence: a reader with browsers on
     // disk can see immediately whether this is a missing install or a lookup pointed somewhere else
     // (PLAYWRIGHT_BROWSERS_PATH, a different browsers root, a revision bump).
-    return `✗ missing — looked for ${probe.executablePath}; run: ${command}`;
+    const lookedFor = [probe.executablePath, ...fallbackPaths].join(', ');
+    return `✗ missing — looked for ${lookedFor}; run: ${command}`;
 }

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

@@ -14,6 +14,7 @@
  * at the call site.
  */
 import { describeSkew } from '../../version/version-skew.js';
+import { mcpConnectionHint } from '../answers/mcp-connection-hint.js';
 import { DoctorRow, doctorRow } from './doctor-rows.js';
 /**
  * `reticle stop`, not `reticle kill`.
@@ -34,14 +35,16 @@ const FIX = 'Restart it so both ends are the same build: `reticle stop`, then le
  */
 export function daemonLine(port, pid, peer, self) {
     const parts = [];
-    if (null !== pid)
+    if (null !== pid) {
         parts.push(`pid ${String(pid)}`);
-    if (peer.version !== undefined)
+    }
+    if (peer.version !== undefined) {
         parts.push(`v${peer.version}`);
+    }
     const detail = 0 === parts.length ? '' : ` (${parts.join(', ')})`;
     const skew = describeSkew({ what: 'the daemon on this port', version: peer.version, contract: peer.contract, fix: FIX }, self);
     const line = {
-        text: doctorRow(DoctorRow.DAEMON, `✓ running on :${String(port)}${detail}`),
+        text: doctorRow(DoctorRow.DAEMON, `✓ running on :${String(port)}${detail}. ${mcpConnectionHint(port)}`),
     };
     return skew === undefined ? line : { ...line, skew };
 }

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

@@ -0,0 +1,44 @@
+/**
+ * `reticle doctor --fix`: repair a half-done install, then say what still needs a person.
+ *
+ * A repair changes only Reticle's own state: its pid file, its own stuck daemon, its own Chromium,
+ * and its entry in an agent's MCP config. A row that needs a change to the user's app, a process
+ * that Reticle cannot prove is its daemon, or an action only the user can do, is never changed
+ * here. Its row already names the step, and this prints that step.
+ *
+ * Each repair checks again before it acts, so a second run finds nothing to do and changes nothing.
+ */
+import { DoctorRow } from './doctor-rows.js';
+type DoctorRowLabel = (typeof DoctorRow)[keyof typeof DoctorRow];
+/** One safe repair. `needed` reads the machine; `apply` changes only Reticle's own state. */
+export interface DoctorRepair {
+    /** The doctor row this repair makes green. */
+    readonly row: DoctorRowLabel;
+    /** What the repair is about, in a few words, so two repairs on one row read apart. */
+    readonly what: string;
+    /** The manual step, printed when the repair is not possible or does not take. */
+    readonly step: string;
+    needed(): Promise<boolean>;
+    apply(): Promise<void>;
+}
+/** What `--fix` says about each repair. */
+export declare const FixOutcome: {
+    readonly FIXED: "fixed";
+    readonly NOTHING: "nothing to do";
+    readonly STILL_NEEDS: "still needs";
+};
+/** The last line of a plain `doctor` run, when `--fix` can repair `count` rows. */
+export declare function fixFooter(count: number): string | undefined;
+/** How many repairs have work to do now. */
+export declare function countNeeded(repairs: readonly DoctorRepair[]): Promise<number>;
+/**
+ * Run doctor, apply the needed repairs in the given order, run doctor again, and print one line for
+ * each repair and one for each row that still fails. True when no row fails after the repairs.
+ */
+export declare function runDoctorFix(deps: {
+    /** Runs doctor and returns its rows. Prints them only when `show` is true. */
+    doctor: (show: boolean) => Promise<string[]>;
+    repairs: readonly DoctorRepair[];
+    print: (line: string) => void;
+}): Promise<boolean>;
+export {};

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

@@ -0,0 +1,89 @@
+/**
+ * `reticle doctor --fix`: repair a half-done install, then say what still needs a person.
+ *
+ * A repair changes only Reticle's own state: its pid file, its own stuck daemon, its own Chromium,
+ * and its entry in an agent's MCP config. A row that needs a change to the user's app, a process
+ * that Reticle cannot prove is its daemon, or an action only the user can do, is never changed
+ * here. Its row already names the step, and this prints that step.
+ *
+ * Each repair checks again before it acts, so a second run finds nothing to do and changes nothing.
+ */
+import { DoctorRow, doctorRow, LABEL_COLUMN } from './doctor-rows.js';
+/** What `--fix` says about each repair. */
+export const FixOutcome = {
+    FIXED: 'fixed',
+    NOTHING: 'nothing to do',
+    STILL_NEEDS: 'still needs',
+};
+/** The mark doctor puts on a row that fails. */
+const FAIL_MARK = '✗';
+const FIX_HEADING = 'reticle doctor --fix';
+/** The last line of a plain `doctor` run, when `--fix` can repair `count` rows. */
+export function fixFooter(count) {
+    if (0 === count) {
+        return undefined;
+    }
+    return `Run \`reticle doctor --fix\` to repair ${String(count)} of these.`;
+}
+/** How many repairs have work to do now. */
+export async function countNeeded(repairs) {
+    let count = 0;
+    for (const repair of repairs) {
+        if (await repair.needed()) {
+            count++;
+        }
+    }
+    return count;
+}
+/** The row label at the head of a doctor line, or undefined for a line that is not a row. */
+function rowLabelOf(line) {
+    const label = line.slice(0, LABEL_COLUMN + 2).trim();
+    return 0 === label.length ? undefined : label;
+}
+async function applyOne(repair) {
+    if (!(await repair.needed())) {
+        return FixOutcome.NOTHING;
+    }
+    try {
+        await repair.apply();
+    }
+    catch {
+        // The check below decides. A repair that threw and a repair that did nothing say the same thing.
+    }
+    if (await repair.needed()) {
+        return `${FixOutcome.STILL_NEEDS}: ${repair.step}`;
+    }
+    return FixOutcome.FIXED;
+}
+/**
+ * Run doctor, apply the needed repairs in the given order, run doctor again, and print one line for
+ * each repair and one for each row that still fails. True when no row fails after the repairs.
+ */
+export async function runDoctorFix(deps) {
+    await deps.doctor(true);
+    const results = [];
+    const stillFailing = new Set();
+    for (const repair of deps.repairs) {
+        const outcome = await applyOne(repair);
+        if (outcome.startsWith(FixOutcome.STILL_NEEDS)) {
+            stillFailing.add(repair.row);
+        }
+        results.push(doctorRow(repair.row, `${repair.what}: ${outcome}`));
+    }
+    const after = await deps.doctor(false);
+    const failures = after.filter((line) => line.includes(FAIL_MARK));
+    deps.print('');
+    deps.print(FIX_HEADING);
+    for (const line of results) {
+        deps.print(line);
+    }
+    for (const line of failures) {
+        // A repair that did not take already printed its step for this row.
+        const label = rowLabelOf(line);
+        if (label !== undefined && stillFailing.has(label)) {
+            continue;
+        }
+        deps.print(`  ${FixOutcome.STILL_NEEDS}: ${line.trim()}`);
+    }
+    return 0 === failures.length;
+}

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

@@ -0,0 +1,23 @@
+/** One agent's `reticle` entry, as its config holds it. */
+export interface RegisteredEntry {
+    readonly client: string;
+    readonly entry: unknown;
+}
+interface ConfigIo {
+    readFile(path: string): string | null;
+    exists(path: string): boolean;
+    homeDir(): string;
+}
+/**
+ * The `reticle` entry of each agent config here: Claude Code's user, local and project scopes, and
+ * every file-backed client that `init` registers with.
+ */
+export declare function registeredEntries(io: ConfigIo, cwd: string): RegisteredEntry[];
+/**
+ * The row text, or undefined when every registered launcher exists and no entry is stale.
+ *
+ * @param floatingNote `claudeStaleEntryNote`, when Claude Code's user-scope entry is the floating
+ *   npx form. `setup mcp` keeps that entry, so the row names the remove-then-add step.
+ */
+export declare function launcherLine(entries: readonly RegisteredEntry[], exists: (path: string) => boolean, floatingNote?: string): string | undefined;
+export {};

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

@@ -0,0 +1,60 @@
+/**
+ * The `launcher` row of `reticle doctor`: an agent config starts Reticle from an installed copy
+ * (`node <path> mcp`), and that file is gone.
+ *
+ * `init` registers the installed bin when there is one, so a sandbox boot does not download the
+ * package again. When the package is removed later, the agent shows the server as failed and says
+ * no more. This row names the path and the command that writes a working entry. It prints only
+ * when a launcher is missing, like `version`.
+ */
+import { McpClient, RETICLE_NPM_PACKAGE, claudeReticleEntries, clientSpec, detectMcpClients, isReticleLauncher, } from '@reticlehq/init';
+import { MCP_SERVER_NAME } from '@reticlehq/core';
+const SETUP_MCP = `npx ${RETICLE_NPM_PACKAGE} setup mcp`;
+/** `setup mcp` keeps an existing Claude Code entry, so that entry goes first. */
+const CLAUDE_REMOVE = `claude mcp remove ${MCP_SERVER_NAME} -s user`;
+const record = (value) => 'object' === typeof value && null !== value ? value : {};
+/** Every string in `command` and `args`, in both the `{ command, args }` and the array shape. */
+function strings(entry) {
+    const { command, args } = record(entry);
+    return [command, args].flat().filter((v) => 'string' === typeof v);
+}
+function parsed(text) {
+    try {
+        return JSON.parse(text ?? '');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The `reticle` entry of each agent config here: Claude Code's user, local and project scopes, and
+ * every file-backed client that `init` registers with.
+ */
+export function registeredEntries(io, cwd) {
+    const claude = claudeReticleEntries(io, cwd).map((entry) => ({
+        client: McpClient.CLAUDE_CODE,
+        entry,
+    }));
+    const others = detectMcpClients(io).map((c) => ({
+        client: c.id,
+        entry: record(record(parsed(c.existing))[clientSpec(c.id).serversKey])[MCP_SERVER_NAME],
+    }));
+    return [...claude, ...others].filter((e) => e.entry !== undefined);
+}
+/**
+ * The row text, or undefined when every registered launcher exists and no entry is stale.
+ *
+ * @param floatingNote `claudeStaleEntryNote`, when Claude Code's user-scope entry is the floating
+ *   npx form. `setup mcp` keeps that entry, so the row names the remove-then-add step.
+ */
+export function launcherLine(entries, exists, floatingNote) {
+    for (const { client, entry } of entries) {
+        const missing = strings(entry).find((s) => isReticleLauncher(s) && !exists(s));
+        if (missing === undefined) {
+            continue;
+        }
+        const fix = McpClient.CLAUDE_CODE === client ? `${CLAUDE_REMOVE}, then ${SETUP_MCP}` : SETUP_MCP;
+        return `✗ ${client} starts Reticle from ${missing}, and that file does not exist. Run: ${fix}`;
+    }
+    return floatingNote === undefined ? undefined : `✗ ${McpClient.CLAUDE_CODE}: ${floatingNote}`;
+}

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

@@ -40,6 +40,8 @@ export declare const DoctorRow: {
      * verification." Every row in this list checks a COMPONENT; none checked a LINK.
      */
     readonly AGENT_LINK: "agent link";
+    /** An agent config starts Reticle from an installed copy that is gone. Only then. */
+    readonly LAUNCHER: "launcher";
     /** Is the APP in this folder wired, not just the tools. Printed by `doctor-project-line.ts`. */
     readonly PROJECT: "project";
     /**
@@ -68,6 +70,8 @@ export declare const DoctorRow: {
     readonly PROMPTS: "prompts";
     /** The daemon's background sync for this project: on or off, why, and the last push. */
     readonly SYNC: "sync";
+    /** Which coding agents found on this machine have Reticle's MCP server registered. */
+    readonly MCP: "mcp";
 };
 type DoctorRowLabel = (typeof DoctorRow)[keyof typeof DoctorRow];
 export declare const DOCTOR_ROW_LABELS: readonly DoctorRowLabel[];

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

@@ -40,6 +40,8 @@ export const DoctorRow = {
      * verification." Every row in this list checks a COMPONENT; none checked a LINK.
      */
     AGENT_LINK: 'agent link',
+    /** An agent config starts Reticle from an installed copy that is gone. Only then. */
+    LAUNCHER: 'launcher',
     /** Is the APP in this folder wired, not just the tools. Printed by `doctor-project-line.ts`. */
     PROJECT: 'project',
     /**
@@ -68,6 +70,8 @@ export const DoctorRow = {
     PROMPTS: 'prompts',
     /** The daemon's background sync for this project: on or off, why, and the last push. */
     SYNC: 'sync',
+    /** Which coding agents found on this machine have Reticle's MCP server registered. */
+    MCP: 'mcp',
 };
 export const DOCTOR_ROW_LABELS = Object.values(DoctorRow);
 /** Indent every row carries, before the label. */

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

@@ -0,0 +1,64 @@
+import { PortPresence } from '../daemon/binding/port-presence.js';
+import { type StepReporter } from './setup-mcp-cli.js';
+import { type PortHolder } from './ports/port-holder.js';
+import { type ChromiumProbe } from './doctor/browser/chromium-hint.js';
+import type { DoctorRepair } from './doctor/doctor-fix.js';
+/** A pid file whose process is gone. `removePid` itself never removes the file of a live process. */
+export declare function stalePidRepair(deps: {
+    readPid: () => number | null;
+    isAlive: (pid: number) => boolean;
+    removePid: () => void;
+}): DoctorRepair;
+/**
+ * A Reticle daemon that holds the port and does not answer. Only a holder whose command line is a
+ * Reticle daemon's qualifies; `stopWedgedDaemon` checks that again, after a grace period, before it
+ * sends a signal. A stranger and the agent's own `reticle mcp` proxy are never stopped.
+ */
+export declare function wedgedDaemonRepair(port: number, deps: {
+    presence: () => Promise<PortPresence>;
+    holder: () => PortHolder | null;
+    stop: () => Promise<boolean>;
+}): DoctorRepair;
+/**
+ * No browser that a launch can use. Only when Playwright's own build is missing or at the wrong
+ * revision and no installed Chrome or Edge stands in. A RETICLE_CHROMIUM_PATH the user set is never
+ * replaced, and an absent playwright package is not a download this can fix.
+ */
+export declare function chromiumRepair(deps: {
+    probe: () => Promise<ChromiumProbe>;
+    install: () => Promise<unknown>;
+    /** The bundled playwright's version, which pins the manual install command. */
+    playwrightVersion: string | undefined;
+}): DoctorRepair;
+/** Agents found on this machine that do not have Reticle's MCP server registered. */
+export declare function mcpRepair(deps: {
+    gaps: () => readonly string[];
+    register: () => void;
+}): DoctorRepair;
+/**
+ * An agent config starts Reticle from an installed copy that no longer exists. `setup mcp`
+ * replaces Reticle's own entry in the JSON clients. It keeps an existing Claude Code entry, so for
+ * Claude Code the row still fails after the repair, and the step is the row's remove-then-add.
+ */
+export declare function launcherRepair(deps: {
+    /** The launcher row, or undefined when every registered launcher exists. */
+    line: () => string | undefined;
+    register: () => void;
+}): DoctorRepair;
+/** The launcher row for the agent configs of this machine and folder. */
+export declare function readLauncherLine(cwd: string): string | undefined;
+/** Which agents found here have Reticle, and which do not. */
+export interface McpRegistration {
+    readonly missing: readonly string[];
+    readonly present: readonly string[];
+}
+/** The `mcp` doctor row. */
+export declare function mcpRegistrationRow(registration: McpRegistration): string;
+/**
+ * Ask `setupMcp` what it would do, and do none of it. Config writes and registration commands are
+ * recorded, not run; only the two `--version` probes run, because they say whether an agent is here.
+ * No telemetry: this is a check, not a registration.
+ */
+export declare function readMcpRegistration(): McpRegistration;
+/** The repairs for this machine and port, in the order `--fix` applies them. */
+export declare function machineRepairs(port: number, reportStep: StepReporter): DoctorRepair[];