@reticlehq/server 2.8.0 → 2.10.0

package/dist/cli/cli-port.js

@@ -8,6 +8,50 @@
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
 import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/** The project config `reticle init` writes. */
+export const RETICLE_CONFIG_BASENAME = '.reticle.json';
+/**
+ * How far up to look for the project config before giving up.
+ *
+ * A cap rather than "walk to the filesystem root" so a process started somewhere unrelated cannot
+ * silently adopt a config from a distant ancestor and dial a port that belongs to another project.
+ * Deep enough for the layouts that actually broke: an app in `frontend/` or `apps/web/`, a git
+ * worktree checked out beside its main repo, and an agent whose cwd is a package inside a monorepo.
+ */
+const MAX_CONFIG_SEARCH_DEPTH = 6;
+/**
+ * Find the nearest `.reticle.json` at or above `cwd`, and return its parsed contents.
+ *
+ * Every reader below used to join the basename onto `cwd` and stop there, so a process whose
+ * working directory was one level away from the config behaved exactly like a project that had
+ * never been through `init`: no port, no projectId, no journal setting, and a diagnostic that told
+ * the user to run an install they had already run. That is the shape of several field reports at
+ * once — an app wired in a subdirectory, an agent running from a repo root, a worktree beside its
+ * main checkout — and they are all the same missing walk.
+ *
+ * Returns undefined when nothing is found, which keeps every caller's existing default intact.
+ */
+export function findProjectConfig(cwd) {
+    let dir = resolve(cwd);
+    for (let depth = 0; depth <= MAX_CONFIG_SEARCH_DEPTH; depth += 1) {
+        try {
+            const raw = readFileSync(`${dir}/${RETICLE_CONFIG_BASENAME}`, 'utf8');
+            const config = JSON.parse(raw);
+            if ('object' === typeof config && config !== null && !Array.isArray(config)) {
+                return config;
+            }
+        }
+        catch {
+            // Absent, unreadable, or not JSON at this level — keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
 /**
  * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
  * Astro to 4321, and so on.
@@ -53,18 +97,9 @@ export function devServerPortWarning(port) {
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
  */
 export function readProjectPort(cwd) {
-    try {
-        const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
-        const config = JSON.parse(raw);
-        if ('object' === typeof config && config !== null) {
-            const p = config['port'];
-            if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
-                return p;
-        }
-    }
-    catch {
-        //.reticle.json absent or unreadable — fall through to default
-    }
+    const p = findProjectConfig(cwd)?.['port'];
+    if ('number' === typeof p && Number.isInteger(p) && p > 0 && p < 65536)
+        return p;
     return undefined;
 }
 /**
@@ -73,18 +108,23 @@ export function readProjectPort(cwd) {
  * undefined if the file is absent/unreadable or has no non-empty string projectId.
  */
 export function readProjectId(cwd) {
-    try {
-        const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
-        const config = JSON.parse(raw);
-        if ('object' === typeof config && config !== null) {
-            const id = config['projectId'];
-            if ('string' === typeof id && id.length > 0)
-                return id;
-        }
-    }
-    catch {
-        //.reticle.json absent or unreadable — no default scope
-    }
+    const id = findProjectConfig(cwd)?.['projectId'];
+    if ('string' === typeof id && id.length > 0)
+        return id;
+    return undefined;
+}
+/**
+ * The framework `reticle init` stamped into `.reticle.json`, when there is one.
+ *
+ * Read so the no-session diagnosis can RANK its causes instead of printing one static differential.
+ * Nuxt is the case that pays for this: it does not register a newly added plugin on HMR, so a dev
+ * server older than the wiring is its single most likely cause — `init` warns about it at install
+ * time and the hint the agent reads hours later never mentioned it.
+ */
+export function readProjectFramework(cwd) {
+    const framework = findProjectConfig(cwd)?.['framework'];
+    if ('string' === typeof framework && framework.length > 0)
+        return framework;
     return undefined;
 }
 /**
@@ -100,17 +140,8 @@ export function readJournalEnabled(cwd, env) {
         if ('1' === v || 'true' === v || 'on' === v)
             return true;
     }
-    try {
-        const raw = readFileSync(`${cwd}/.reticle.json`, 'utf8');
-        const config = JSON.parse(raw);
-        if ('object' === typeof config && config !== null) {
-            if (false === config['journal'])
-                return false;
-        }
-    }
-    catch {
-        //.reticle.json absent or unreadable — journaling stays on by default
-    }
+    if (false === findProjectConfig(cwd)?.['journal'])
+        return false;
     return true;
 }
 /**

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

@@ -36,6 +36,27 @@ export declare function urlParts(url: string): {
     loopback: boolean;
 };
 /** CLI entry — wires the live ports and runs the one-shot verification. Exits the process itself. */
+/**
+ * What a user reads when the bridge port is already taken by a daemon.
+ *
+ * `verify` boots its OWN daemon, and it has to do so on the port the APP dials — a loopback page
+ * connects natively to the port baked into its config, so verify cannot simply pick a free one and
+ * still be found. On any machine with Reticle set up, that port already belongs to a running daemon.
+ *
+ * It used to die there. The listen failure surfaces asynchronously on the server object, after
+ * `start` has resolved, so nothing caught it and the process printed a raw `node:net` stack — the
+ * worst answer available, and reached most often by the people with the fewest other options, since
+ * the skill offers this command as the way to a verdict with no MCP at all.
+ *
+ * Three ways out, in the order they are worth trying, and the message says all three rather than
+ * picking one: an agent that already has the tools should ask the daemon that is running instead of
+ * starting a second one; somebody who wants this command specifically can stop the daemon; and a
+ * second port works when the app is configured for it.
+ *
+ * Attaching to the running daemon the way `reticle drive` now does is the better answer and is not
+ * this change — see cli/drive-attach.ts for the shape it should take.
+ */
+export declare function portBusyMessage(port: number): string;
 export declare function handleVerify(parsed: {
     url: string;
     headless: boolean;

package/dist/cli/cli-verify.js

@@ -13,6 +13,9 @@ import { join, basename } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, } from '@reticlehq/core';
 import { start } from '../index.js';
+import { probePresence, PortPresence } from '../daemon/port-presence.js';
+import { probeDaemon } from '../mcp/mcp-proxy.js';
+import { fetchStatus } from './cli-launch.js';
 import { resolveCloudConfig, syncRunToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { ReticleRunner } from '../runs/reticle-runner.js';
 import { createRunnerPort } from '../runs/runner-port.js';
@@ -199,6 +202,35 @@ async function openLiveConnection(opts) {
     };
 }
 /** CLI entry — wires the live ports and runs the one-shot verification. Exits the process itself. */
+/**
+ * What a user reads when the bridge port is already taken by a daemon.
+ *
+ * `verify` boots its OWN daemon, and it has to do so on the port the APP dials — a loopback page
+ * connects natively to the port baked into its config, so verify cannot simply pick a free one and
+ * still be found. On any machine with Reticle set up, that port already belongs to a running daemon.
+ *
+ * It used to die there. The listen failure surfaces asynchronously on the server object, after
+ * `start` has resolved, so nothing caught it and the process printed a raw `node:net` stack — the
+ * worst answer available, and reached most often by the people with the fewest other options, since
+ * the skill offers this command as the way to a verdict with no MCP at all.
+ *
+ * Three ways out, in the order they are worth trying, and the message says all three rather than
+ * picking one: an agent that already has the tools should ask the daemon that is running instead of
+ * starting a second one; somebody who wants this command specifically can stop the daemon; and a
+ * second port works when the app is configured for it.
+ *
+ * Attaching to the running daemon the way `reticle drive` now does is the better answer and is not
+ * this change — see cli/drive-attach.ts for the shape it should take.
+ */
+export function portBusyMessage(port) {
+    return (`reticle verify needs port ${String(port)} — the port your app dials — and a Reticle daemon is ` +
+        'already listening on it. It did not start a second one.\n\n' +
+        '  • If you have the Reticle tools, ask the daemon that is already running instead: ' +
+        'reticle_run { tool: "reticle_verify", args: { action: "change", files: ["..."] } }\n' +
+        `  • Or stop it and re-run: npx @reticlehq/server stop --port ${String(port)}\n` +
+        `  • Or run both on another port, if your app is configured for it: RETICLE_PORT=<port> ` +
+        'npx @reticlehq/server verify <url>');
+}
 export function handleVerify(parsed) {
     const now = () => Date.now();
     const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
@@ -217,5 +249,17 @@ export function handleVerify(parsed) {
         fail: (line) => process.stderr.write(`${line}\n`),
         exit: (code) => process.exit(code),
     };
-    void runVerify({ url: parsed.url, timeoutMs: parsed.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS }, ports);
+    // Asked BEFORE anything binds. The listen failure arrives asynchronously on the server object,
+    // long after `start` has resolved, so no `.catch` on that promise can ever see it — which is why
+    // this used to reach the user as a raw node stack rather than as an answer.
+    void (async () => {
+        const port = parsed.port ?? RETICLE_DEFAULT_PORT;
+        if ((await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus })) ===
+            PortPresence.DAEMON) {
+            ports.fail(portBusyMessage(port));
+            ports.exit(1);
+            return;
+        }
+        await runVerify({ url: parsed.url, timeoutMs: parsed.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS }, ports);
+    })();
 }

package/dist/cli/config-discovery.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Where the project config actually is, and — when we cannot find it — where we looked.
+ *
+ * `findProjectConfig` walks UP from the daemon's working directory, which is right for a developer
+ * who ran `reticle` in their project and wrong for the way most daemons are actually started.
+ * Editors launch MCP servers from wherever they like, and in at least one popular one that is the
+ * user's home directory: the config then sits at `<repo>/apps/web/.reticle.json`, the up-walk from
+ * home never touches it, and Reticle confidently reports the project unwired. Reported twice, plus a
+ * git-worktree variant of the same shape.
+ *
+ * So: walk up, then — from the repo root, if there is one — look in the workspace directories the
+ * project's OWN manifest declares, falling back to the two conventions everybody uses.
+ *
+ * The second half is the `searched` list. "There is no `.reticle.json`" is unfalsifiable without it,
+ * and this file exists because that claim was made, confidently, about configs that were right
+ * there. Every result carries the places that were checked.
+ *
+ * Deliberately NOT a "pick one" function. Several configs means several projects, and choosing one
+ * silently is how an agent ends up with a confident verdict about an app it never touched. Callers
+ * are handed the list and must name it.
+ */
+export interface FoundConfig {
+    /** Absolute path to the `.reticle.json`. */
+    path: string;
+    /** The directory it configures — what a reader needs in order to act. */
+    directory: string;
+    /** Its projectId, when it declares a usable one. */
+    projectId?: string;
+}
+export interface ConfigDiscovery {
+    found: FoundConfig[];
+    /** Every directory checked, in the order checked. The answer to "are you sure?". */
+    searched: string[];
+}
+export declare function discoverProjectConfigs(cwd: string): ConfigDiscovery;

package/dist/cli/config-discovery.js

@@ -0,0 +1,163 @@
+/**
+ * Where the project config actually is, and — when we cannot find it — where we looked.
+ *
+ * `findProjectConfig` walks UP from the daemon's working directory, which is right for a developer
+ * who ran `reticle` in their project and wrong for the way most daemons are actually started.
+ * Editors launch MCP servers from wherever they like, and in at least one popular one that is the
+ * user's home directory: the config then sits at `<repo>/apps/web/.reticle.json`, the up-walk from
+ * home never touches it, and Reticle confidently reports the project unwired. Reported twice, plus a
+ * git-worktree variant of the same shape.
+ *
+ * So: walk up, then — from the repo root, if there is one — look in the workspace directories the
+ * project's OWN manifest declares, falling back to the two conventions everybody uses.
+ *
+ * The second half is the `searched` list. "There is no `.reticle.json`" is unfalsifiable without it,
+ * and this file exists because that claim was made, confidently, about configs that were right
+ * there. Every result carries the places that were checked.
+ *
+ * Deliberately NOT a "pick one" function. Several configs means several projects, and choosing one
+ * silently is how an agent ends up with a confident verdict about an app it never touched. Callers
+ * are handed the list and must name it.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { RETICLE_CONFIG_BASENAME } from './cli-port.js';
+/** How far up to walk. Matches the existing config search so the two cannot disagree. */
+const MAX_UP_LEVELS = 6;
+/**
+ * Workspace directories checked when the manifest declares none.
+ *
+ * Not a guess at where an app might be — these are the two layouts the JS ecosystem converged on,
+ * and both reported cases used one of them.
+ */
+const CONVENTIONAL_WORKSPACES = ['apps', 'packages'];
+/** How many entries of one workspace directory to stat. A backstop, not a policy. */
+const MAX_WORKSPACE_ENTRIES = 64;
+function readConfig(directory) {
+    const path = join(directory, RETICLE_CONFIG_BASENAME);
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+            return undefined;
+        const projectId = parsed['projectId'];
+        return {
+            path,
+            directory,
+            ...('string' === typeof projectId && projectId.length > 0 ? { projectId } : {}),
+        };
+    }
+    catch {
+        // Absent, unreadable, or not JSON. A malformed config is reported elsewhere; here it is simply
+        // not a config we can name a project from.
+        return undefined;
+    }
+}
+/** The nearest ancestor holding a `.git`, or undefined. The repo root is where workspaces hang off. */
+function repoRootOf(start) {
+    let dir = start;
+    for (let level = 0; level <= MAX_UP_LEVELS; level += 1) {
+        if (existsSync(join(dir, '.git')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * The workspace directories this repo declares, from its own manifest where it has one.
+ *
+ * Reading `pnpm-workspace.yaml` with a substring scan rather than a YAML parser is deliberate: the
+ * only thing wanted from it is the leading path segment of each glob, the file is machine-written in
+ * practice, and a parser dependency to read one list of strings does not pay for itself.
+ */
+function declaredWorkspaceDirs(repoRoot) {
+    const dirs = new Set();
+    try {
+        const pkg = JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8'));
+        if ('object' === typeof pkg && null !== pkg) {
+            const workspaces = pkg['workspaces'];
+            const globs = Array.isArray(workspaces)
+                ? workspaces
+                : 'object' === typeof workspaces && null !== workspaces
+                    ? (workspaces['packages'] ?? [])
+                    : [];
+            if (Array.isArray(globs)) {
+                for (const glob of globs)
+                    if ('string' === typeof glob)
+                        dirs.add(firstSegment(glob));
+            }
+        }
+    }
+    catch {
+        // No manifest, or one we cannot read. The conventions below still apply.
+    }
+    try {
+        const yaml = readFileSync(join(repoRoot, 'pnpm-workspace.yaml'), 'utf8');
+        for (const line of yaml.split('\n')) {
+            const match = /^\s*-\s*['"]?([^'"\s]+)/.exec(line);
+            const glob = match?.[1];
+            if (glob !== undefined)
+                dirs.add(firstSegment(glob));
+        }
+    }
+    catch {
+        // Not a pnpm workspace.
+    }
+    for (const conventional of CONVENTIONAL_WORKSPACES)
+        dirs.add(conventional);
+    return [...dirs].filter((dir) => dir.length > 0 && !dir.startsWith('.'));
+}
+/** `apps/*` -> `apps`. The glob machinery is not needed; the leading directory is all we scan. */
+function firstSegment(glob) {
+    const [first] = glob.split('/');
+    return first ?? '';
+}
+export function discoverProjectConfigs(cwd) {
+    const searched = [];
+    const found = [];
+    const seen = new Set();
+    const check = (directory) => {
+        if (seen.has(directory))
+            return;
+        seen.add(directory);
+        searched.push(directory);
+        const config = readConfig(directory);
+        if (config !== undefined)
+            found.push(config);
+    };
+    let dir = resolve(cwd);
+    for (let level = 0; level <= MAX_UP_LEVELS; level += 1) {
+        check(dir);
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const repoRoot = repoRootOf(resolve(cwd));
+    if (repoRoot === undefined)
+        return { found, searched };
+    for (const workspace of declaredWorkspaceDirs(repoRoot)) {
+        const base = join(repoRoot, workspace);
+        let entries = [];
+        try {
+            entries = readdirSync(base).slice(0, MAX_WORKSPACE_ENTRIES);
+        }
+        catch {
+            continue; // A declared workspace directory that does not exist is not an error here.
+        }
+        for (const entry of entries) {
+            const candidate = join(base, entry);
+            try {
+                if (!statSync(candidate).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            check(candidate);
+        }
+    }
+    return { found, searched };
+}

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

@@ -14,6 +14,7 @@
  * at the call site.
  */
 import { describeSkew } from '../version/version-skew.js';
+import { DoctorRow, doctorRow } from './doctor-rows.js';
 /**
  * `reticle stop`, not `reticle kill`.
  *
@@ -39,6 +40,8 @@ export function daemonLine(port, pid, peer, self) {
         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: `  daemon       ✓ running on :${String(port)}${detail}` };
+    const line = {
+        text: doctorRow(DoctorRow.DAEMON, `✓ running on :${String(port)}${detail}`),
+    };
     return skew === undefined ? line : { ...line, skew };
 }

package/dist/cli/doctor-project-line.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Whether `init` has wired THIS directory — the check `doctor` was missing.
+ *
+ * `doctor` already read `.reticle.json` for the port, so it knew whether the file existed and never
+ * said so. In a project where `init` has not run the checklist came out clean: node fine, chromium
+ * fine, a daemon that starts on demand, a bridge port. Every line true, and the app carrying no SDK
+ * went unremarked — which is exactly the state that produces "the tools are here and nothing ever
+ * verifies", and the state `doctor` is run to explain.
+ *
+ * Registering the MCP server and instrumenting the app are two different halves of the install, and
+ * more than one route does the first without the second.
+ */
+export interface ProjectWiringFacts {
+    /** The id from `.reticle.json`, or undefined when there is no config here. */
+    projectId: string | undefined;
+    /** Has an app for this project ever connected on this port? Durable across daemon restarts. */
+    previouslyConnected: boolean;
+    /**
+     * Is there a `.reticle.json` on disk here at all?
+     *
+     * Separate from `projectId` because the two failures are different facts with the same symptom: an
+     * absent config and a corrupt one both read back as "no id". Saying "no .reticle.json here" about a
+     * file that is sitting right there sends somebody hunting a missing file when what they have is a
+     * broken one — and a corrupt config is itself worth naming, since it is how a project ends up
+     * pointed at the wrong daemon.
+     */
+    configPresent?: boolean;
+}
+/**
+ * One line, in the same shape as the checks beside it.
+ *
+ * `previouslyConnected` outranks the missing file, and that ordering is the important part: the Vite
+ * and Babel plugins instrument an app without writing a config, so a project that has connected here
+ * is wired whatever the file says. Sending it to `init` would be the same wrong answer pointing the
+ * other way — and `init` is the one action that can overwrite a setup that already works.
+ */
+export declare function projectWiringLine(facts: ProjectWiringFacts): string;

package/dist/cli/doctor-project-line.js

@@ -0,0 +1,35 @@
+/**
+ * Whether `init` has wired THIS directory — the check `doctor` was missing.
+ *
+ * `doctor` already read `.reticle.json` for the port, so it knew whether the file existed and never
+ * said so. In a project where `init` has not run the checklist came out clean: node fine, chromium
+ * fine, a daemon that starts on demand, a bridge port. Every line true, and the app carrying no SDK
+ * went unremarked — which is exactly the state that produces "the tools are here and nothing ever
+ * verifies", and the state `doctor` is run to explain.
+ *
+ * Registering the MCP server and instrumenting the app are two different halves of the install, and
+ * more than one route does the first without the second.
+ */
+/**
+ * One line, in the same shape as the checks beside it.
+ *
+ * `previouslyConnected` outranks the missing file, and that ordering is the important part: the Vite
+ * and Babel plugins instrument an app without writing a config, so a project that has connected here
+ * is wired whatever the file says. Sending it to `init` would be the same wrong answer pointing the
+ * other way — and `init` is the one action that can overwrite a setup that already works.
+ */
+export function projectWiringLine(facts) {
+    if (facts.projectId !== undefined) {
+        return `  project      ✓ wired here (${facts.projectId})`;
+    }
+    if (facts.previouslyConnected) {
+        return '  project      ✓ an app has connected here before, so it is wired (no .reticle.json — a build plugin can wire an app without one)';
+    }
+    if (true === facts.configPresent) {
+        return ('  project      ✗ .reticle.json is here but carries no readable projectId — a corrupt or ' +
+            'hand-edited config reads the same as no config, and points this project at the default ' +
+            'daemon. Run `npx @reticlehq/server init` in the app directory to rewrite it');
+    }
+    return ('  project      ✗ no .reticle.json here and nothing has ever connected — the tools may be ' +
+        'registered, but this app is not instrumented. Run `npx @reticlehq/server init` in the app directory');
+}

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

@@ -0,0 +1,51 @@
+/**
+ * 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, `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";
+    readonly BRIDGE_PORT: "bridge port";
+    readonly PORT_CHECK: "port check";
+    readonly DAEMON_LOG: "daemon log";
+    readonly TRACING: "tracing";
+    readonly DESKTOP: "desktop";
+};
+export 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;

package/dist/cli/doctor-rows.js

@@ -0,0 +1,54 @@
+/**
+ * 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, `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 const DoctorRow = {
+    NODE: 'node',
+    CHROMIUM: 'chromium',
+    DAEMON: 'daemon',
+    VERSION: 'version',
+    SESSIONS: 'sessions',
+    BRIDGE_PORT: 'bridge port',
+    PORT_CHECK: 'port check',
+    DAEMON_LOG: 'daemon log',
+    TRACING: 'tracing',
+    DESKTOP: 'desktop',
+};
+export const DOCTOR_ROW_LABELS = Object.values(DoctorRow);
+/** Indent every row carries, before the label. */
+const INDENT = '  ';
+/**
+ * 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 const LABEL_COLUMN = DOCTOR_ROW_LABELS.reduce((widest, label) => Math.max(widest, label.length), 0) + 2;
+/** Build one `doctor` row: the standard indent, the label padded to the column, then `rest`. */
+export function doctorRow(label, rest) {
+    return `${INDENT}${label.padEnd(LABEL_COLUMN)}${rest}`;
+}

package/dist/cli/doctor-sessions-line.js

@@ -1,4 +1,5 @@
 import { SELF_RECOVERING_MARKER } from '../session/no-session-diagnosis.js';
+import { DoctorRow, doctorRow } from './doctor-rows.js';
 /**
  * The line `doctor` was missing: is anything actually CONNECTED?
  *
@@ -49,18 +50,20 @@ export function sessionsLine(facts) {
         // An older daemon that does not report it. Saying "0 connected" here would be a claim about the
         // app made from a payload that never mentioned the app — the exact kind of confident wrong
         // sentence the no-session diagnosis exists to avoid.
-        return { text: '  sessions     ? this daemon did not report connected pages (older build)' };
+        return {
+            text: doctorRow(DoctorRow.SESSIONS, '? this daemon did not report connected pages (older build)'),
+        };
     }
     if (count > 0) {
         const plural = 1 === count ? 'page' : 'pages';
-        return { text: `  sessions     ✓ ${String(count)} ${plural} connected` };
+        return { text: doctorRow(DoctorRow.SESSIONS, `✓ ${String(count)} ${plural} connected`) };
     }
     const why = 'string' === typeof facts.why && facts.why.length > 0 ? forAHuman(facts.why) : undefined;
     return {
         // Deliberately ✗ rather than a neutral note. Zero connected pages is why somebody is running
         // doctor, and a ✓-coloured checklist that hides the one failing thing is how the old output
         // convinced people their setup was fine.
-        text: '  sessions     ✗ no page has connected to this daemon',
+        text: doctorRow(DoctorRow.SESSIONS, '✗ no page has connected to this daemon'),
         ...(why === undefined ? {} : { why }),
     };
 }