@reticlehq/server 3.9.0 → 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/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-repairs.js

@@ -50,7 +50,7 @@ export function wedgedDaemonRepair(port, deps) {
     return {
         row: DoctorRow.DAEMON,
         what: 'a Reticle daemon that does not answer',
-        step: `reticle restart --port ${String(port)}`,
+        step: `reticle serve --restart --port ${String(port)}`,
         needed: async () => PortPresence.FOREIGN === (await deps.presence()) && true === deps.holder()?.reticleDaemon,
         apply: async () => {
             await deps.stop();

package/dist/command/cli/ensure-daemon.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `reticle open` and every other flow that needs a daemon on `port`.
+ *
+ * The retry: a FOREIGN reading seconds after `reticle restart` is usually OUR OWN daemon still
+ * answering its first `/status` — the 1 s `/status` window and the 500 ms TCP window do not
+ * survive a cold Windows start, and the refusal then names a holder it could not identify, while
+ * `reticle status` run moments later shows the daemon fine. The pid file names what `restart`
+ * started; while that process is alive the port is probed once more before refusing. A stranger's
+ * pid is never in the file, so the refusal keeps its teeth for the stranger case it was written
+ * for.
+ *
+ * Probes, the pid file and the spawn are injected so the rule is testable without a socket — the
+ * same shape `probePresence`'s own callers use.
+ */
+import { PortPresence } from '../daemon/binding/port-presence.js';
+export interface EnsureDaemonDeps {
+    /** The classified presence probe. Defaults to the shared TCP + `/status` pair. */
+    probe?: (port: number) => Promise<PortPresence>;
+    readPid?: (port: number) => number | null;
+    isAlive?: (pid: number) => boolean;
+    /** How long to wait before the second probe. */
+    retryDelayMs?: number;
+    spawnDaemon?: (port: number) => Promise<void>;
+    onUsable?: (port: number) => Promise<void> | void;
+}
+export declare function ensureDaemon(port: number, deps?: EnsureDaemonDeps): Promise<void>;

package/dist/command/cli/ensure-daemon.js

@@ -0,0 +1,57 @@
+/**
+ * `reticle open` and every other flow that needs a daemon on `port`.
+ *
+ * The retry: a FOREIGN reading seconds after `reticle restart` is usually OUR OWN daemon still
+ * answering its first `/status` — the 1 s `/status` window and the 500 ms TCP window do not
+ * survive a cold Windows start, and the refusal then names a holder it could not identify, while
+ * `reticle status` run moments later shows the daemon fine. The pid file names what `restart`
+ * started; while that process is alive the port is probed once more before refusing. A stranger's
+ * pid is never in the file, so the refusal keeps its teeth for the stranger case it was written
+ * for.
+ *
+ * Probes, the pid file and the spawn are injected so the rule is testable without a socket — the
+ * same shape `probePresence`'s own callers use.
+ */
+import { PortPresence, probePresence, presenceIsUsable, } from '../daemon/binding/port-presence.js';
+import { describePortState } from '../daemon/port-state.js';
+import { probeDaemon, waitForDaemon } from '../../surface/mcp/mcp-proxy.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { isAlive, readPid, spawnDaemon } from '../daemon/daemon.js';
+import { warnOnDaemonSkew } from './launch/cli-launch.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG } from './cli-parse.js';
+/** The probe pair every daemon-touching command shares. */
+const REAL_PROBES = {
+    tcpOpen: (port) => probeDaemon(port),
+    status: (port) => fetchStatus(port),
+};
+export async function ensureDaemon(port, deps = {}) {
+    const probe = deps.probe ?? (() => probePresence(port, REAL_PROBES));
+    const readRecordedPid = deps.readPid ?? readPid;
+    const pidIsAlive = deps.isAlive ?? isAlive;
+    const spawn = deps.spawnDaemon ?? spawnRealDaemon;
+    const onUsable = deps.onUsable ?? warnOnDaemonSkew;
+    const retryDelayMs = deps.retryDelayMs ?? 1_500;
+    let presence = await probe(port);
+    if (PortPresence.FOREIGN === presence) {
+        const recorded = readRecordedPid(port);
+        if (recorded !== null && pidIsAlive(recorded)) {
+            await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+            presence = await probe(port);
+        }
+    }
+    if (presenceIsUsable(presence)) {
+        return void (await onUsable(port));
+    }
+    if (PortPresence.FREE !== presence) {
+        throw new Error(describePortState(presence, port));
+    }
+    await spawn(port);
+}
+async function spawnRealDaemon(port) {
+    const scriptPath = process.argv[1];
+    if (scriptPath === undefined) {
+        throw new Error('cannot locate the reticle daemon script');
+    }
+    spawnDaemon(process.execPath, scriptPath, [DAEMON_INNER_COMMAND, PORT_FLAG, String(port)], port);
+    await waitForDaemon(port);
+}

package/dist/command/cli/finished-run/grade-command.d.ts

@@ -0,0 +1,23 @@
+import { type StateIo } from '../../../features/compare/outside/state-sources.js';
+import { type GradeArgs } from '../cli-parse-grade.js';
+export declare const GradeExit: {
+    readonly PASS: 0;
+    readonly FAIL: 1;
+    readonly UNVERIFIED: 2;
+};
+/** The most difference lines printed as text. `--json` gives every line. */
+export declare const MAX_TEXT_LINES = 10;
+type Ok = Extract<GradeArgs, {
+    kind: 'ok';
+}>;
+export interface GradeOut {
+    line: (text: string) => void;
+    exit: (code: number) => void;
+}
+export interface GradeIo {
+    state: StateIo;
+    readText: (path: string) => Promise<string>;
+    writeText: (path: string, text: string) => void;
+}
+export declare function handleGrade(args: Ok, out: GradeOut, io?: GradeIo): Promise<void>;
+export {};

package/dist/command/cli/finished-run/grade-command.js

@@ -0,0 +1,180 @@
+/**
+ * `reticle grade`: grade a finished run of an app from snapshots of its stored data.
+ *
+ * - `snapshot` reads the declared state sources (and the page the run ended on) into a file.
+ * - `judge` compares a candidate snapshot with two reference snapshots, and checks the final answer
+ *   against a source read at grade time.
+ * - `tables` writes a state declaration with one source for each table of a database.
+ * - `suggest` removes the sources that change between two runs of the same correct steps.
+ *
+ * It needs no daemon and no browser. The rules are in `@/features/grade/`.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { MSG_READ_FAILED, readStateSources, sourceRows, StateDeclarationSchema, } from '../../../features/compare/outside/state-sources.js';
+import { checkAnswer, ExpectSchema } from '../../../features/grade/grade-answer.js';
+import { GradeVerdict, gradeState, SnapshotSchema, urlLine, } from '../../../features/grade/grade-state.js';
+import { quietSources, tableSources } from '../../../features/grade/grade-suggest.js';
+import { GradeStep } from '../cli-parse-grade.js';
+import { hostStateIo } from '../two-builds/compare-command.js';
+export const GradeExit = { PASS: 0, FAIL: 1, UNVERIFIED: 2 };
+const EXIT = {
+    [GradeVerdict.PASS]: GradeExit.PASS,
+    [GradeVerdict.FAIL]: GradeExit.FAIL,
+    [GradeVerdict.UNVERIFIED]: GradeExit.UNVERIFIED,
+};
+/** The most difference lines printed as text. `--json` gives every line. */
+export const MAX_TEXT_LINES = 10;
+const UTF8 = 'utf8';
+const COLUMN = '\t';
+const LINE_BREAK = /\r?\n/;
+const SKIP_SEPARATOR = ',';
+const reasonOf = (error) => error instanceof Error ? error.message : String(error);
+function writeFile(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+}
+const defaultIo = {
+    state: hostStateIo,
+    readText: (path) => readFile(path, UTF8),
+    writeText: writeFile,
+};
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+async function readSnapshot(io, path) {
+    const parsed = SnapshotSchema.safeParse(JSON.parse(await io.readText(path)));
+    if (!parsed.success) {
+        throw new Error(`${path} is not a grade snapshot: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+/** The sources of a state declaration file, or why they could not be read. */
+async function declarationOf(io, path) {
+    try {
+        const parsed = StateDeclarationSchema.safeParse(JSON.parse(await io.readText(path)));
+        return parsed.success ? parsed.data.sources : { error: parsed.error.message };
+    }
+    catch (error) {
+        return { error: reasonOf(error) };
+    }
+}
+/** At most `MAX_TEXT_LINES` lines, then a line that says how many were left out. */
+function capped(sign, lines) {
+    const shown = lines.slice(0, MAX_TEXT_LINES).map((line) => `  ${sign} ${line}`);
+    const rest = lines.length - shown.length;
+    return rest > 0 ? [...shown, `  ... and ${String(rest)} more (--json lists every line)`] : shown;
+}
+async function snapshot(args, io, out) {
+    const sources = await declarationOf(io, args.state ?? '');
+    if ('error' in sources) {
+        out.line(`Could not read the state sources in ${args.state ?? ''}: ${sources.error}`);
+        out.exit(GradeExit.UNVERIFIED);
+        return;
+    }
+    // No row cap: the grade diff is linear, and a cut row would not name its record.
+    const lines = await readStateSources(sources, io.state, Number.POSITIVE_INFINITY);
+    if (args.url !== undefined) {
+        lines.push(urlLine(args.url));
+    }
+    io.writeText(args.out ?? '', json({ lines }));
+    const failed = lines.filter((line) => line.startsWith(MSG_READ_FAILED));
+    out.line(`Snapshot: ${args.out ?? ''}: ${String(lines.length)} lines`);
+    failed.forEach((line) => out.line(`  ${line}`));
+    out.exit(failed.length > 0 ? GradeExit.UNVERIFIED : GradeExit.PASS);
+}
+async function answerOf(args, io) {
+    if (args.expect === undefined) {
+        return {};
+    }
+    const parsed = ExpectSchema.safeParse(JSON.parse(await io.readText(args.expect)));
+    if (!parsed.success) {
+        return { unread: `${args.expect}: ${parsed.error.message}` };
+    }
+    const spec = parsed.data.answer;
+    let rows;
+    try {
+        rows = await sourceRows(spec.source, io.state);
+    }
+    catch (error) {
+        return { unread: `answer source ${spec.source.label}: ${reasonOf(error)}` };
+    }
+    return { check: checkAnswer(rows, args.answer, spec) };
+}
+async function judge(args, io, out) {
+    const [reference, again, candidate] = await Promise.all([args.reference, args.again, args.candidate].map((p) => readSnapshot(io, p ?? '')));
+    if (reference === undefined || again === undefined || candidate === undefined) {
+        throw new Error('a snapshot is missing');
+    }
+    const state = gradeState(reference, again, candidate);
+    const answer = await answerOf(args, io);
+    const unread = [...state.unread, ...(answer.unread === undefined ? [] : [answer.unread])];
+    let verdict = GradeVerdict.PASS;
+    if (unread.length > 0) {
+        verdict = GradeVerdict.UNVERIFIED;
+    }
+    else if (state.verdict === GradeVerdict.FAIL || false === answer.check?.ok) {
+        verdict = GradeVerdict.FAIL;
+    }
+    const result = {
+        verdict,
+        state: { removed: state.removed, added: state.added, ignored: state.ignored },
+        ...(answer.check === undefined ? {} : { answer: answer.check }),
+        unread,
+    };
+    if (args.json) {
+        out.line(JSON.stringify(result));
+    }
+    else {
+        out.line(verdict.toUpperCase());
+        unread.forEach((line) => out.line(`  unread: ${line}`));
+        if (answer.check !== undefined) {
+            out.line(answer.check.ok
+                ? `  answer: correct (${answer.check.expected})`
+                : `  answer: wrong: ${answer.check.reason ?? ''}`);
+        }
+        out.line(`  state: ${String(state.removed.length + state.added.length)} lines differ, ${String(state.ignored)} ignored as noise`);
+        capped('-', state.removed).forEach(out.line);
+        capped('+', state.added).forEach(out.line);
+    }
+    out.exit(EXIT[verdict]);
+}
+async function tables(args, io, out) {
+    const listed = await io.state.run(args.list ?? '', args.container);
+    const names = listed.split(LINE_BREAK).map((line) => line.split(COLUMN)[0] ?? '');
+    const skip = (args.skip ?? '').split(SKIP_SEPARATOR).filter((prefix) => '' !== prefix);
+    const result = tableSources(names, args.rows ?? '', args.container, skip);
+    io.writeText(args.out ?? '', json({ sources: result.sources }));
+    out.line(`Declaration: ${args.out ?? ''}: ${String(result.sources.length)} sources`);
+    result.skipped.forEach((s) => out.line(`  skipped ${s.label}: ${s.reason}`));
+    out.exit(GradeExit.PASS);
+}
+async function suggest(args, io, out) {
+    const sources = await declarationOf(io, args.state ?? '');
+    if ('error' in sources) {
+        out.line(`Could not read the state sources in ${args.state ?? ''}: ${sources.error}`);
+        out.exit(GradeExit.UNVERIFIED);
+        return;
+    }
+    const reference = await readSnapshot(io, args.reference ?? '');
+    const again = await readSnapshot(io, args.again ?? '');
+    const result = quietSources(sources, reference.lines, again.lines);
+    io.writeText(args.out ?? '', json({ sources: result.sources }));
+    out.line(`Declaration: ${args.out ?? ''}: kept ${String(result.sources.length)} of ${String(sources.length)} sources`);
+    result.dropped.forEach((d) => out.line(`  dropped ${d.label}: ${d.reason}`));
+    out.exit(GradeExit.PASS);
+}
+const STEPS = {
+    [GradeStep.SNAPSHOT]: snapshot,
+    [GradeStep.JUDGE]: judge,
+    [GradeStep.TABLES]: tables,
+    [GradeStep.SUGGEST]: suggest,
+};
+export async function handleGrade(args, out, io = defaultIo) {
+    try {
+        await STEPS[args.step](args, io, out);
+    }
+    catch (error) {
+        out.line(`UNVERIFIED\n  ${reasonOf(error)}`);
+        out.exit(GradeExit.UNVERIFIED);
+    }
+}

package/dist/command/cli/lifecycle/daemon-lifecycle.d.ts

@@ -24,7 +24,7 @@ export declare function handleServe(parsed: {
 }): void;
 export declare function handleStop(port: number, quiet: boolean): void;
 /**
- * `reticle restart` — free the port, then put a daemon back on it and prove it bound.
+ * `reticle serve --restart` — free the port, then put a daemon back on it and prove it bound.
  *
  * The two halves are reported separately on purpose. A restart that killed the old daemon and then
  * could not start a new one leaves the user in a different place from one that could not kill

package/dist/command/cli/lifecycle/daemon-lifecycle.js

@@ -197,7 +197,7 @@ function waitForStop(port, pid, quiet) {
     }, 100);
 }
 /**
- * `reticle restart` — free the port, then put a daemon back on it and prove it bound.
+ * `reticle serve --restart` — free the port, then put a daemon back on it and prove it bound.
  *
  * The two halves are reported separately on purpose. A restart that killed the old daemon and then
  * could not start a new one leaves the user in a different place from one that could not kill

package/dist/command/cli/ports/port-holder.d.ts

@@ -55,6 +55,15 @@ ourPid?: number | null): string;
 export declare function findPortHolder(port: number, exec: (command: string, args: readonly string[]) => string | null): PortHolder | null;
 /** The path in `lsof -a -p <pid> -d cwd -Fn` output, or null when it printed none. */
 export declare function parseProcessCwd(stdout: string): string | null;
+/** Each port in `lsof -nP -iTCP -sTCP:LISTEN -Fn` output, once. A dual-stack bind prints two lines. */
+export declare function parseListeningPorts(stdout: string): number[];
+/**
+ * Every TCP port on this machine with a listener, or nothing when the lookup cannot run.
+ *
+ * Off on Windows. A process there shows no working directory, so `findListenerCwd` starts PowerShell
+ * for each port, and the daemon blocks for each start.
+ */
+export declare function findListeningPorts(exec: (command: string, args: readonly string[]) => string | null, platform?: NodeJS.Platform): number[];
 /**
  * The folder that holds the `node_modules` a command line runs from, or null.
  *

package/dist/command/cli/ports/port-holder.js

@@ -93,7 +93,7 @@ ourPid) {
     // Naming the command matters more than naming the process. "Stop that process" describes an
     // outcome and leaves the reader to invent a route to it, and the route they invent is the `-ti`
     // pipeline that takes their agent's proxy down with the holder.
-    const tail = 'a daemon cannot bind it. Free it with `reticle restart --force` (it signals the listener only, ' +
+    const tail = 'a daemon cannot bind it. Free it with `reticle serve --restart --force` (it signals the listener only, ' +
         "never the agent's mcp proxy), or run Reticle on a different port (`--port`), then retry.";
     if (null === holder) {
         /**
@@ -117,11 +117,11 @@ ourPid) {
         return `port ${String(port)} is held by a process Reticle could not identify — ${tail}${ours}`;
     }
     if (true === holder.reticleDaemon && ourPid !== holder.pid) {
-        // Not the pid we recorded, so `reticle stop` cannot find it. `restart` finds the listener.
+        // Not the pid we recorded, so `reticle stop` cannot find it. `serve --restart` finds the listener.
         // It did not answer a short probe. A busy daemon does that too, and other agents can use it.
         return (`port ${String(port)} is held by a Reticle daemon (pid ${String(holder.pid)}) that did not ` +
             'answer in time. It may be busy. Run `reticle status` again in a few seconds. If it stays ' +
-            'silent, run `reticle restart`: it stops that process and starts a new daemon on this port.');
+            'silent, run `reticle serve --restart`: it stops that process and starts a new daemon on this port.');
     }
     if (ourPid !== null && ourPid !== undefined && ourPid === holder.pid) {
         return (`port ${String(port)} is held by YOUR Reticle daemon (pid ${String(holder.pid)}), and it is ` +
@@ -150,6 +150,30 @@ export function parseProcessCwd(stdout) {
     }
     return null;
 }
+/** Each port in `lsof -nP -iTCP -sTCP:LISTEN -Fn` output, once. A dual-stack bind prints two lines. */
+export function parseListeningPorts(stdout) {
+    const ports = new Set();
+    for (const line of stdout.split('\n')) {
+        const port = line.startsWith(NAME_FIELD) ? /:(\d+)$/.exec(line)?.[1] : undefined;
+        if (port !== undefined) {
+            ports.add(Number(port));
+        }
+    }
+    return [...ports];
+}
+/**
+ * Every TCP port on this machine with a listener, or nothing when the lookup cannot run.
+ *
+ * Off on Windows. A process there shows no working directory, so `findListenerCwd` starts PowerShell
+ * for each port, and the daemon blocks for each start.
+ */
+export function findListeningPorts(exec, platform = process.platform) {
+    if ('win32' === platform) {
+        return [];
+    }
+    const out = exec('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-Fn']);
+    return null === out ? [] : parseListeningPorts(out);
+}
 /** A Windows PowerShell cold start alone can take more than the lsof bound. */
 const WINDOWS_LOOKUP_TIMEOUT_MS = 8_000;
 /** The listener's command line: Windows does not show another process's working directory. */

package/dist/command/cli/status/status-lines.d.ts

@@ -24,6 +24,7 @@ export declare const StatusLabel: {
     readonly NEXT: "next";
     readonly SPLIT_BRAIN: "split brain";
     readonly UPDATE: "update";
+    readonly LICENSE: "license";
 };
 export type StatusLabel = (typeof StatusLabel)[keyof typeof StatusLabel];
 /** The block to print on stdout, one string per line, heading first. */