@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/cli/demo/demo-page.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The page the tutorial drives when the user has no app of their own yet.
+ *
+ * `reticle tutorial` used to print four steps and stop. Printing is not teaching: the reader is told
+ * that a verdict is the point, and then watches nothing produce one. So the tour now RUNS — against a
+ * page served from here, because the alternative (drive whatever is in front of the user) is how a
+ * first run ends on a login wall, and a tutorial that fails on step one teaches that Reticle does not
+ * work.
+ *
+ * It carries the real SDK, not a stub. A demo instrumented by something other than the thing being
+ * demonstrated proves nothing about the thing being demonstrated.
+ *
+ * WHY THERE IS NO IMPORT MAP WRITTEN DOWN HERE. The SDK is ESM with bare specifiers, the shipped
+ * server has no bundler, and the obvious fix — a hand-written map of specifier to path — is the exact
+ * defect this repository keeps paying for: two lists that must agree, where the one nobody updated is
+ * the one that breaks. A dependency added to the SDK would leave this map short by one, the page
+ * would fail to load a module, and the tour would report that the user's setup is broken.
+ *
+ * So the map is DISCOVERED. Start at the SDK entry, scan the files beside it for bare specifiers,
+ * resolve each one, and repeat. It cannot be short by one, because nothing here knows the names.
+ *
+ * The walk follows imports out of OUR packages only; a third-party one is mounted whole and not
+ * read. That is a deliberate line, not an oversight. Reading zod means walking several thousand
+ * files to learn something that has not changed in this repository's lifetime, and it measurably
+ * cost about a minute — on the one command whose whole job is a good first impression. The drift
+ * this guards against is our own SDK gaining a dependency, which is the thing that actually moves;
+ * a third-party leaf that grows a bare runtime import would fail loudly on the page instead, which
+ * is a worse message but not a silent one.
+ */
+/** The signal the demo app fires when it saves — the consequence the tour declares in advance. */
+export declare const DEMO_SIGNAL = "demo:saved";
+/** Controls the tour points at. Named here so the page and the run cannot disagree about them. */
+export declare const DemoTestId: {
+    readonly SAVE: "demo-save";
+    readonly NAME: "demo-name";
+    readonly STATUS: "demo-status";
+};
+export interface SdkMount {
+    /** URL prefix the page fetches under. */
+    prefix: string;
+    /** Directory on disk it serves from. */
+    dir: string;
+}
+export interface SdkGraph {
+    /** Bare specifier to the URL the page should load it from. */
+    imports: Record<string, string>;
+    mounts: SdkMount[];
+    /** URL of the SDK entry module itself. */
+    entry: string;
+}
+/**
+ * Resolve the SDK and everything it reaches, as URLs a page can fetch.
+ *
+ * `resolve` is injected so a test can describe a dependency graph without one existing on disk —
+ * and because the real one is `import.meta.resolve`, which answers against THIS module's location
+ * and so cannot be pointed at a fixture.
+ */
+export declare function sdkGraph(resolve?: (spec: string) => string): SdkGraph;
+/**
+ * The demo app, and the one line that makes it verifiable.
+ *
+ * Saving fires a SIGNAL as well as changing the text. Both are here on purpose: the text is what a
+ * person sees, the signal is what the app itself says happened, and the tour waits on the signal
+ * because that is the difference it exists to teach — a rendered word can be a coincidence, and an
+ * app declaring its own state cannot.
+ */
+export declare function demoPageHtml(graph: SdkGraph, token: string, bridgeUrl: string): string;
+/**
+ * Serve the demo on a port the OS picks.
+ *
+ * Port 0 rather than a chosen number: this starts while a daemon, a dev server and possibly another
+ * copy of this tour are already running, and a tutorial whose first act is a port collision has
+ * taught the wrong lesson about the product.
+ */
+export declare function serveDemoPage(html: string, graph: SdkGraph): Promise<{
+    url: string;
+    close: () => Promise<void>;
+}>;

package/dist/command/cli/demo/demo-page.js

@@ -0,0 +1,238 @@
+/**
+ * The page the tutorial drives when the user has no app of their own yet.
+ *
+ * `reticle tutorial` used to print four steps and stop. Printing is not teaching: the reader is told
+ * that a verdict is the point, and then watches nothing produce one. So the tour now RUNS — against a
+ * page served from here, because the alternative (drive whatever is in front of the user) is how a
+ * first run ends on a login wall, and a tutorial that fails on step one teaches that Reticle does not
+ * work.
+ *
+ * It carries the real SDK, not a stub. A demo instrumented by something other than the thing being
+ * demonstrated proves nothing about the thing being demonstrated.
+ *
+ * WHY THERE IS NO IMPORT MAP WRITTEN DOWN HERE. The SDK is ESM with bare specifiers, the shipped
+ * server has no bundler, and the obvious fix — a hand-written map of specifier to path — is the exact
+ * defect this repository keeps paying for: two lists that must agree, where the one nobody updated is
+ * the one that breaks. A dependency added to the SDK would leave this map short by one, the page
+ * would fail to load a module, and the tour would report that the user's setup is broken.
+ *
+ * So the map is DISCOVERED. Start at the SDK entry, scan the files beside it for bare specifiers,
+ * resolve each one, and repeat. It cannot be short by one, because nothing here knows the names.
+ *
+ * The walk follows imports out of OUR packages only; a third-party one is mounted whole and not
+ * read. That is a deliberate line, not an oversight. Reading zod means walking several thousand
+ * files to learn something that has not changed in this repository's lifetime, and it measurably
+ * cost about a minute — on the one command whose whole job is a good first impression. The drift
+ * this guards against is our own SDK gaining a dependency, which is the thing that actually moves;
+ * a third-party leaf that grows a bare runtime import would fail loudly on the page instead, which
+ * is a worse message but not a silent one.
+ */
+import { fileURLToPath } from 'node:url';
+import { createServer } from 'node:http';
+import { dirname, join, relative, extname, sep } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+/** Where the tour starts. Everything else on the page is reached from here. */
+const SDK_ENTRY = '@reticlehq/browser';
+/** The signal the demo app fires when it saves — the consequence the tour declares in advance. */
+export const DEMO_SIGNAL = 'demo:saved';
+/** Controls the tour points at. Named here so the page and the run cannot disagree about them. */
+export const DemoTestId = {
+    SAVE: 'demo-save',
+    NAME: 'demo-name',
+    STATUS: 'demo-status',
+};
+/** What the status line says before anything has been proved. */
+const STATUS_BEFORE = 'nothing saved yet';
+/** Bare specifiers this cannot serve and must not try to: the page is a browser. */
+const NOT_SERVABLE = /^node:/;
+/**
+ * The packages whose imports are followed. See the note at the top for why the walk stops here.
+ *
+ * `open-verification` is listed by NAME because it is ours without being in the scope: it left the
+ * org to stand on its own as the specification, and matching on `@reticlehq/` alone would silently
+ * demote it to an unscanned third-party leaf. Today its only dependency is zod, which core already
+ * pulls in, so nothing would have broken yet — which is exactly the kind of gap that is cheap now
+ * and expensive on the day the spec grows a second dependency.
+ */
+const OURS = /^(@reticlehq\/|open-verification$)/;
+const JS_CONTENT_TYPE = 'text/javascript; charset=utf-8';
+const HTML_CONTENT_TYPE = 'text/html; charset=utf-8';
+/**
+ * A compiled package's own imports, read off disk.
+ *
+ * Test files are skipped: `dist` carries compiled specs, and those import `vitest` and `node:fs`,
+ * which are not part of what a page loads and would send the walk looking for packages that only
+ * exist in this repository.
+ */
+function bareSpecifiersIn(dir) {
+    const found = new Set();
+    const walk = (at) => {
+        for (const name of readdirSync(at)) {
+            const path = join(at, name);
+            if (statSync(path).isDirectory()) {
+                if ('node_modules' !== name)
+                    walk(path);
+                continue;
+            }
+            if (!name.endsWith('.js') || name.endsWith('.test.js'))
+                continue;
+            for (const match of readFileSync(path, 'utf8').matchAll(/from\s*'([^.'][^']*)'/g)) {
+                const spec = match[1];
+                if (spec !== undefined && !NOT_SERVABLE.test(spec))
+                    found.add(spec);
+            }
+        }
+    };
+    walk(dir);
+    return found;
+}
+/** The directory holding a resolved entry's `package.json` — what has to be mounted whole. */
+function packageRootOf(entryPath) {
+    let at = dirname(entryPath);
+    for (;;) {
+        if (existsSync(join(at, 'package.json')))
+            return at;
+        const up = dirname(at);
+        if (up === at)
+            return undefined;
+        at = up;
+    }
+}
+/**
+ * Resolve the SDK and everything it reaches, as URLs a page can fetch.
+ *
+ * `resolve` is injected so a test can describe a dependency graph without one existing on disk —
+ * and because the real one is `import.meta.resolve`, which answers against THIS module's location
+ * and so cannot be pointed at a fixture.
+ */
+export function sdkGraph(resolve = defaultResolve) {
+    const imports = {};
+    const mounts = [];
+    const roots = new Map();
+    const queue = [SDK_ENTRY];
+    const seen = new Set();
+    let entry = '';
+    while (queue.length > 0) {
+        const spec = queue.shift();
+        if (spec === undefined || seen.has(spec))
+            continue;
+        seen.add(spec);
+        const entryPath = resolve(spec);
+        const root = packageRootOf(entryPath);
+        if (root === undefined) {
+            throw new Error(`the demo page cannot serve ${spec}: it resolves outside any package`);
+        }
+        let prefix = roots.get(root);
+        if (prefix === undefined) {
+            prefix = `/sdk/${String(mounts.length)}/`;
+            roots.set(root, prefix);
+            mounts.push({ prefix, dir: root });
+        }
+        const url = prefix + relative(root, entryPath).split(sep).join('/');
+        if (SDK_ENTRY === spec)
+            entry = url;
+        else
+            imports[spec] = url;
+        if (OURS.test(spec)) {
+            for (const next of bareSpecifiersIn(dirname(entryPath)))
+                queue.push(next);
+        }
+    }
+    return { imports, mounts, entry };
+}
+function defaultResolve(spec) {
+    return fileURLToPath(import.meta.resolve(spec));
+}
+/**
+ * The demo app, and the one line that makes it verifiable.
+ *
+ * Saving fires a SIGNAL as well as changing the text. Both are here on purpose: the text is what a
+ * person sees, the signal is what the app itself says happened, and the tour waits on the signal
+ * because that is the difference it exists to teach — a rendered word can be a coincidence, and an
+ * app declaring its own state cannot.
+ */
+export function demoPageHtml(graph, token, bridgeUrl) {
+    const importMap = JSON.stringify({ imports: graph.imports });
+    const connect = JSON.stringify({ session: 'demo', url: bridgeUrl, token });
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>Reticle demo</title>
+<script type="importmap">${importMap}</script>
+<style>
+ body{font:16px/1.5 system-ui,sans-serif;margin:0;padding:2.5rem 1.5rem;max-width:34rem}
+ h1{font-size:1.3rem;margin:0 0 .25rem}
+ p.lede{color:#555;margin:0 0 2rem}
+ label{display:block;font-weight:600;margin:0 0 .4rem}
+ input{font:inherit;padding:.5rem .6rem;width:100%;box-sizing:border-box;border:1px solid #bbb;border-radius:6px}
+ button{font:inherit;margin-top:1rem;padding:.55rem 1.1rem;border:0;border-radius:6px;background:#111;color:#fff;cursor:pointer}
+ p.status{margin-top:1.5rem;padding:.75rem;background:#f4f4f5;border-radius:6px}
+</style></head>
+<body>
+ <h1>Reticle demo</h1>
+ <p class="lede">A tiny app, instrumented with the real SDK. The tutorial is about to drive it.</p>
+ <label for="${DemoTestId.NAME}">Display name</label>
+ <input id="${DemoTestId.NAME}" data-testid="${DemoTestId.NAME}" value="Ada">
+ <button data-testid="${DemoTestId.SAVE}">Save</button>
+ <p class="status" data-testid="${DemoTestId.STATUS}">${STATUS_BEFORE}</p>
+<script type="module">
+ import { reticle } from ${JSON.stringify(graph.entry)};
+ reticle.connect(${connect});
+ const status = document.querySelector('[data-testid="${DemoTestId.STATUS}"]');
+ document.querySelector('[data-testid="${DemoTestId.SAVE}"]').addEventListener('click', () => {
+   const name = document.querySelector('[data-testid="${DemoTestId.NAME}"]').value;
+   status.textContent = 'saved ' + name;
+   reticle.signal(${JSON.stringify(DEMO_SIGNAL)}, { name });
+ });
+</script>
+</body></html>`;
+}
+/**
+ * Serve the demo on a port the OS picks.
+ *
+ * Port 0 rather than a chosen number: this starts while a daemon, a dev server and possibly another
+ * copy of this tour are already running, and a tutorial whose first act is a port collision has
+ * taught the wrong lesson about the product.
+ */
+export function serveDemoPage(html, graph) {
+    const server = createServer((req, res) => {
+        const path = (req.url ?? '/').split('?')[0] ?? '/';
+        if ('/' === path) {
+            res.writeHead(200, { 'content-type': HTML_CONTENT_TYPE });
+            res.end(html);
+            return;
+        }
+        for (const mount of graph.mounts) {
+            if (!path.startsWith(mount.prefix))
+                continue;
+            const file = join(mount.dir, path.slice(mount.prefix.length));
+            // A request that climbed out of the mount is not served, whatever it points at.
+            if (!file.startsWith(mount.dir + sep) || !existsSync(file) || statSync(file).isDirectory()) {
+                break;
+            }
+            res.writeHead(200, {
+                'content-type': '.js' === extname(file) ? JS_CONTENT_TYPE : 'application/octet-stream',
+            });
+            res.end(readFileSync(file));
+            return;
+        }
+        res.writeHead(404);
+        res.end('not found');
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (null === address || 'string' === typeof address) {
+                reject(new Error('the demo page could not be served: no port was assigned'));
+                return;
+            }
+            resolve({
+                url: `http://127.0.0.1:${String(address.port)}/`,
+                close: () => new Promise((done) => {
+                    server.close(() => {
+                        done();
+                    });
+                }),
+            });
+        });
+    });
+}

package/dist/command/cli/demo/demo-run.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The tutorial, run rather than printed.
+ *
+ * `reticle tutorial` described four steps and produced nothing. The last of those steps says that a
+ * drive without a verdict has no result — and the tour itself ended without one, which is the lesson
+ * taught by counter-example. So the same four steps now execute, against the demo page, and every
+ * line the reader sees is a thing that actually happened.
+ *
+ * The steps are NOT re-listed here. They come from `tutorialScript`, the same source the printed tour
+ * reads, because two descriptions of one sequence drift and the one nobody updated is the one
+ * somebody follows.
+ *
+ * Tools are called in-process rather than over the daemon's MCP transport. This command starts the
+ * daemon it drives, so it already holds the session; going back out over a socket to reach a server
+ * inside this process would add a transport that can fail to a tour whose job is to not fail. The
+ * funnel telemetry is unaffected either way — `runTool` is the chokepoint that reports it, and both
+ * routes pass through it.
+ */
+export interface DemoTourOptions {
+    port: number;
+    headless: boolean;
+    /** Every line the reader sees, in order. Injected so a test reads the tour instead of a terminal. */
+    say: (line: string) => void;
+    now?: () => number;
+}
+/** A tour either reached a verdict or it did not; the exit code says which. */
+export interface DemoTourResult {
+    code: number;
+    verified: string | undefined;
+}
+/**
+ * Run the tour, and report whether it ended at a proof.
+ *
+ * A step that cannot be taken stops the tour and says which one. Carrying on past a failed step
+ * would end at a verdict taken against a page the earlier steps never reached — which is precisely
+ * the false green the fourth step is there to warn about.
+ */
+export declare function runDemoTour(options: DemoTourOptions): Promise<DemoTourResult>;

package/dist/command/cli/demo/demo-run.js

@@ -0,0 +1,138 @@
+/**
+ * The tutorial, run rather than printed.
+ *
+ * `reticle tutorial` described four steps and produced nothing. The last of those steps says that a
+ * drive without a verdict has no result — and the tour itself ended without one, which is the lesson
+ * taught by counter-example. So the same four steps now execute, against the demo page, and every
+ * line the reader sees is a thing that actually happened.
+ *
+ * The steps are NOT re-listed here. They come from `tutorialScript`, the same source the printed tour
+ * reads, because two descriptions of one sequence drift and the one nobody updated is the one
+ * somebody follows.
+ *
+ * Tools are called in-process rather than over the daemon's MCP transport. This command starts the
+ * daemon it drives, so it already holds the session; going back out over a socket to reach a server
+ * inside this process would add a transport that can fail to a tour whose job is to not fail. The
+ * funnel telemetry is unaffected either way — `runTool` is the chokepoint that reports it, and both
+ * routes pass through it.
+ */
+import { ReticleTool } from '@reticlehq/core';
+// TOOLS comes through the package barrel rather than from `surface/tools/tools.js` directly. That
+// aggregator composes the tool arrays out of five directories, and anything importing it back is how
+// this package accumulated cycles; the barrel sits above both it and this file, which is the
+// direction that does not close a loop.
+import { start, TOOLS } from '../../../index.js';
+import { runTool } from '../../../surface/tools/invoke-tool.js';
+import { buildVerifyDeps } from '../cli-verify.js';
+import { readOrCreatePairingTokenSync, defaultPairingTokenDir, } from '../../../portal/bridge/pairing-token.js';
+import { tutorialScript, TutorialAudience, demoPlan } from '../tutorial.js';
+import { sdkGraph, demoPageHtml, serveDemoPage, DEMO_SIGNAL } from './demo-page.js';
+/** How long to wait for the demo page to dial the bridge before giving up on it. */
+const SESSION_TIMEOUT_MS = 30_000;
+const SESSION_POLL_MS = 250;
+/** Only `verified: "yes"` is a pass — see the contract every verdict tool here is held to. */
+const PROVED = 'yes';
+function toolNamed(name) {
+    const found = TOOLS.find((t) => t.name === name);
+    if (found === undefined) {
+        throw new Error(`the tutorial cannot run: ${name} is not in the tool registry`);
+    }
+    return found;
+}
+function asRecord(value) {
+    return 'object' === typeof value && null !== value ? value : {};
+}
+function asText(value) {
+    return 'string' === typeof value ? value : undefined;
+}
+/** The controls `reticle_query` found, in the shape the safety rule reads them. */
+function controlsIn(result) {
+    const raw = asRecord(result)['elements'];
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        const el = asRecord(item);
+        const ref = asText(el['ref']);
+        const name = asText(el['name']);
+        if (ref === undefined || name === undefined)
+            continue;
+        const role = asText(el['role']);
+        out.push(role === undefined ? { ref, name } : { ref, name, role });
+    }
+    return out;
+}
+async function waitForSession(running, now) {
+    const deadline = now() + SESSION_TIMEOUT_MS;
+    while (now() < deadline) {
+        if (running.bridge.sessions.count() > 0)
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, SESSION_POLL_MS));
+    }
+    return running.bridge.sessions.count() > 0;
+}
+/**
+ * Run the tour, and report whether it ended at a proof.
+ *
+ * A step that cannot be taken stops the tour and says which one. Carrying on past a failed step
+ * would end at a verdict taken against a page the earlier steps never reached — which is precisely
+ * the false green the fourth step is there to warn about.
+ */
+export async function runDemoTour(options) {
+    const now = options.now ?? (() => Date.now());
+    const steps = new Map(tutorialScript(TutorialAudience.HUMAN).map((s) => [s.id, s]));
+    const announce = (id) => {
+        const step = steps.get(id);
+        if (step === undefined)
+            return;
+        options.say('');
+        options.say(step.say);
+        options.say(`  why: ${step.why}`);
+    };
+    const graph = sdkGraph();
+    const token = readOrCreatePairingTokenSync(defaultPairingTokenDir()) ?? '';
+    const bridgeUrl = `ws://localhost:${String(options.port)}/reticle`;
+    const page = await serveDemoPage(demoPageHtml(graph, token, bridgeUrl), graph);
+    let running;
+    try {
+        running = await start({ port: options.port, driveUrl: page.url, headless: options.headless });
+        const deps = buildVerifyDeps(running, process.cwd(), now);
+        const call = async (name, args) => await runTool(toolNamed(name), deps, args);
+        announce('connect');
+        if (!(await waitForSession(running, now))) {
+            options.say('  the demo page never dialled the bridge, so there is nothing to show.');
+            return { code: 1, verified: undefined };
+        }
+        options.say(`  one session connected: the demo app at ${page.url}`);
+        announce('look');
+        const snapshot = asRecord(await call(ReticleTool.SNAPSHOT, { mode: 'interactive' }));
+        for (const line of (asText(snapshot['tree']) ?? '').split('\n'))
+            options.say(`  ${line}`);
+        announce('declare');
+        const found = controlsIn(await call(ReticleTool.QUERY, { role: 'button' }));
+        const plan = demoPlan(found);
+        if (!plan.ok) {
+            options.say(`  ${plan.because}`);
+            return { code: 1, verified: undefined };
+        }
+        options.say(`  "${plan.name}" is safe to press. Saving should make the app say so itself:`);
+        options.say(`  reticle_act_and_wait { ref: "${plan.ref}", action: "click", until: {`);
+        options.say(`    kind: "signal", name: "${DEMO_SIGNAL}" } }`);
+        announce('verdict');
+        const verdict = asRecord(await call(ReticleTool.ACT_AND_WAIT, {
+            ref: plan.ref,
+            action: 'click',
+            until: { kind: 'signal', name: DEMO_SIGNAL },
+        }));
+        const verified = asText(verdict['verified']);
+        const because = asText(verdict['verifiedReason']) ?? asText(verdict['failureReason']);
+        options.say(`  verified: ${verified ?? 'unknown'}`);
+        if (because !== undefined)
+            options.say(`  because: ${because}`);
+        return { code: PROVED === verified ? 0 : 1, verified };
+    }
+    finally {
+        await page.close();
+        await running?.close?.();
+    }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * What `doctor` says about the daemon it found — pure, so it can be tested without a socket.
+ *
+ * Doctor already stopped lying about the PORT: `probePresence` separates "a daemon is here" from "a
+ * stranger holds it" from "nothing is listening", which was the load-bearing half of the report. It
+ * still did not say WHICH daemon, though the `/status` payload it already fetches carries `version`
+ * and `contract` and it discarded both.
+ *
+ * That is the gap worth closing, because skew is invisible everywhere else: a CLI and a daemon on
+ * different contracts connect anyway and then disagree about behaviour, which reaches the agent as a
+ * bare `-32000` naming no version at all. Doctor is the command a human runs at exactly that moment.
+ *
+ * Same split as `classifyPort`/`probePresence`: the rule lives here and is tested; the fetching stays
+ * at the call site.
+ */
+import { describeSkew } from '../../version/version-skew.js';
+import { DoctorRow, doctorRow } from './doctor-rows.js';
+/**
+ * `reticle stop`, not `reticle kill`.
+ *
+ * The first version of this said `reticle kill`, which this CLI does not dispatch — it is a proposal
+ * (#114), described as a gap in docs/system-map.md, and I read it there as if it shipped. A remedy
+ * naming a command that errors is a second dead end handed to someone already stuck, on the one
+ * command they run when they are confused.
+ */
+const FIX = 'Restart it so both ends are the same build: `reticle stop`, then let your agent reconnect (it ' +
+    'spawns a fresh daemon on the next tool call).';
+/**
+ * Build the daemon line for a port that answered `/status`.
+ *
+ * `pid` comes from the pid file and is genuinely optional — a daemon started by another user, or one
+ * whose pid file was cleaned up, still answers. Printing `(pid null)` would be worse than printing
+ * nothing, which is the same class of mistake as the port lie this command already fixed.
+ */
+export function daemonLine(port, pid, peer, self) {
+    const parts = [];
+    if (null !== pid)
+        parts.push(`pid ${String(pid)}`);
+    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}`),
+    };
+    return skew === undefined ? line : { ...line, skew };
+}

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

@@ -0,0 +1,75 @@
+/**
+ * The row labels `reticle doctor` can print, and the one place that pads them into a column.
+ *
+ * These were free strings before, hand-padded at every call site across three modules
+ * (`cli-doctor.ts`, `doctor-daemon-line.ts`, `doctor-sessions-line.ts`). Two problems with that,
+ * and the second is the one that motivated #340:
+ *
+ * 1. The padding was maintained by eye. Every label happened to be padded to the same column, but
+ *    nothing enforced it, and a label longer than the column would have quietly broken the
+ *    alignment of one row in a checklist whose whole readability is the column.
+ * 2. Nothing connected the labels to the docs pages that reproduce doctor's output. A row could be
+ *    added, renamed or removed and the three pages showing sample output would go on describing the
+ *    old vocabulary, with no gate noticing. `doctor` is the command a stuck user runs, and the docs
+ *    are what they read when its output does not match what they were told to expect.
+ *
+ * The label set is exported so the docs guard can derive its expectation from the command rather
+ * than from a hand-kept list, which is the direction that catches the case that actually bites: a
+ * row added and never documented.
+ *
+ * NOT every row prints on every run. `version` prints only on skew, `port check` only on a
+ * mismatch, `sibling` only when a well-known Reticle port other than ours has a listener,
+ * `desktop` only on a desktop project, and `sessions` only when a daemon answered. The
+ * vocabulary is therefore "what this command can print", not "what one run printed" — a guard built
+ * by scraping a single invocation would silently stop covering the conditional rows, which are
+ * exactly the ones a reader is least likely to have seen before.
+ */
+/** Every row label `doctor` can emit. Values are the literal text at the head of the row. */
+export declare const DoctorRow: {
+    readonly NODE: "node";
+    readonly CHROMIUM: "chromium";
+    readonly DAEMON: "daemon";
+    readonly VERSION: "version";
+    readonly SESSIONS: "sessions";
+    /**
+     * The agent-to-daemon hop, which every other row here is blind to.
+     *
+     * Reported from the field: a user with the SDK injected, the overlay visible, a live session on
+     * the daemon and every tool listed in their client was still told by three separate agents that
+     * Reticle was not present. Their words: "four green checkmarks that don't add up to a working
+     * verification." Every row in this list checks a COMPONENT; none checked a LINK.
+     */
+    readonly AGENT_LINK: "agent link";
+    /**
+     * Which of `localhost`'s two answers reaches the bridge, printed only when they disagree.
+     *
+     * The daemon binds `127.0.0.1` and `loopback-alias.ts` forwards `[::1]` to it, best-effort —
+     * a machine with IPv6 off, or something already holding `[::1]:port`, leaves the daemon serving
+     * IPv4 alone and must not be fatal. But `localhost` is a NAME, and Windows Chrome tries the IPv6
+     * answer first, so on that combination the SDK's documented default URL cannot reach a daemon that
+     * is running perfectly. The only record of the alias failing was a field on one JSON log line.
+     *
+     * Conditional like `version`: a healthy machine answers on both and prints nothing.
+     */
+    readonly LOOPBACK: "loopback";
+    readonly BRIDGE_PORT: "bridge port";
+    readonly PORT_CHECK: "port check";
+    readonly SIBLING: "sibling";
+    readonly DAEMON_LOG: "daemon log";
+    readonly TRACING: "tracing";
+    readonly DESKTOP: "desktop";
+};
+type DoctorRowLabel = (typeof DoctorRow)[keyof typeof DoctorRow];
+export declare const DOCTOR_ROW_LABELS: readonly DoctorRowLabel[];
+/**
+ * Width the label column pads to.
+ *
+ * Derived from the longest label rather than hardcoded, so adding a longer row realigns the whole
+ * checklist instead of breaking one line of it. With the current set the longest is `bridge port`
+ * (11), so this is 13 — byte-identical to the hand-padding it replaces. A test pins that, so a
+ * change to the column is a deliberate, visible change rather than an invisible reflow.
+ */
+export declare const LABEL_COLUMN: number;
+/** Build one `doctor` row: the standard indent, the label padded to the column, then `rest`. */
+export declare function doctorRow(label: DoctorRowLabel, rest: string): string;
+export {};