@reticlehq/server 3.8.2 → 3.9.0

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

@@ -0,0 +1,214 @@
+/**
+ * The safe repairs `reticle doctor --fix` can apply, in the order it applies them.
+ *
+ * Each one changes only Reticle's own state, and each reuses the code that already owns that state:
+ * `removePid` for the pid file, `stopWedgedDaemon` for a stuck daemon, the launch path's pinned
+ * install for Chromium, and `reticle setup mcp` for the agent registrations. The facts each one
+ * reads are injected, so the decision is tested without a home directory or a port.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { claudeAvailableProbe, claudeStaleEntryNote, claudeUserEntryIsFloating, codexAvailableProbe, probeCli, } from '@reticlehq/init';
+import { mcpLauncher } from '../setup/mcp-launcher.js';
+import { isAlive, readPid, removePid } from '../daemon/daemon.js';
+import { PortPresence, probePresence } from '../daemon/binding/port-presence.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { identifyPortHolder } from '../daemon/port-state.js';
+import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
+import { probeChromiumWithFallback, probeLaunchableChromium } from '../../launch-chromium.js';
+import { setupMcp } from '../setup/setup-mcp.js';
+import { handleSetupMcp } from './setup-mcp-cli.js';
+import { stopWedgedDaemon } from './cli-kill.js';
+import { captureLookup } from './ports/port-holder.js';
+import { bundledPlaywrightVersion, chromiumInstallCommand, } from './doctor/browser/chromium-hint.js';
+import { DoctorRow, doctorRow } from './doctor/doctor-rows.js';
+import { launcherLine, registeredEntries } from './doctor/doctor-launcher-line.js';
+const SETUP_MCP_COMMAND = 'reticle setup mcp';
+/** A pid file whose process is gone. `removePid` itself never removes the file of a live process. */
+export function stalePidRepair(deps) {
+    const needed = () => {
+        const pid = deps.readPid();
+        return pid !== null && !deps.isAlive(pid);
+    };
+    return {
+        row: DoctorRow.DAEMON,
+        what: 'pid file of a stopped daemon',
+        step: 'delete the pid file of the stopped daemon in ~/.reticle',
+        needed: () => Promise.resolve(needed()),
+        apply: () => {
+            deps.removePid();
+            return Promise.resolve();
+        },
+    };
+}
+/**
+ * A Reticle daemon that holds the port and does not answer. Only a holder whose command line is a
+ * Reticle daemon's qualifies; `stopWedgedDaemon` checks that again, after a grace period, before it
+ * sends a signal. A stranger and the agent's own `reticle mcp` proxy are never stopped.
+ */
+export function wedgedDaemonRepair(port, deps) {
+    return {
+        row: DoctorRow.DAEMON,
+        what: 'a Reticle daemon that does not answer',
+        step: `reticle restart --port ${String(port)}`,
+        needed: async () => PortPresence.FOREIGN === (await deps.presence()) && true === deps.holder()?.reticleDaemon,
+        apply: async () => {
+            await deps.stop();
+        },
+    };
+}
+/**
+ * No browser that a launch can use. Only when Playwright's own build is missing or at the wrong
+ * revision and no installed Chrome or Edge stands in. A RETICLE_CHROMIUM_PATH the user set is never
+ * replaced, and an absent playwright package is not a download this can fix.
+ */
+export function chromiumRepair(deps) {
+    return {
+        row: DoctorRow.CHROMIUM,
+        what: "Playwright's own Chromium",
+        step: chromiumInstallCommand(deps.playwrightVersion),
+        needed: async () => {
+            const probe = await deps.probe();
+            return (!probe.exists &&
+                probe.fallback === undefined &&
+                true !== probe.configured &&
+                probe.executablePath !== undefined);
+        },
+        apply: async () => {
+            await deps.install();
+        },
+    };
+}
+/** Agents found on this machine that do not have Reticle's MCP server registered. */
+export function mcpRepair(deps) {
+    return {
+        row: DoctorRow.MCP,
+        what: 'agent registrations',
+        step: SETUP_MCP_COMMAND,
+        needed: () => Promise.resolve(deps.gaps().length > 0),
+        apply: () => {
+            deps.register();
+            return Promise.resolve();
+        },
+    };
+}
+/** How the launcher row starts its command, as `doctor-launcher-line.ts` writes it. */
+const LAUNCHER_RUN = 'Run: ';
+/**
+ * An agent config starts Reticle from an installed copy that no longer exists. `setup mcp`
+ * replaces Reticle's own entry in the JSON clients. It keeps an existing Claude Code entry, so for
+ * Claude Code the row still fails after the repair, and the step is the row's remove-then-add.
+ */
+export function launcherRepair(deps) {
+    let step = SETUP_MCP_COMMAND;
+    return {
+        row: DoctorRow.LAUNCHER,
+        what: 'a registered launcher that does not exist or has no version',
+        // The step is read after `needed`, which reads the row again.
+        get step() {
+            return step;
+        },
+        needed: () => {
+            const line = deps.line();
+            if (line === undefined) {
+                return Promise.resolve(false);
+            }
+            const at = line.indexOf(LAUNCHER_RUN);
+            step = at < 0 ? SETUP_MCP_COMMAND : line.slice(at + LAUNCHER_RUN.length);
+            return Promise.resolve(true);
+        },
+        apply: () => {
+            deps.register();
+            return Promise.resolve();
+        },
+    };
+}
+/** The launcher row for the agent configs of this machine and folder. */
+export function readLauncherLine(cwd) {
+    const io = {
+        exists: existsSync,
+        homeDir: homedir,
+        readFile: (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+    return launcherLine(registeredEntries(io, cwd), existsSync, claudeUserEntryIsFloating(io) ? claudeStaleEntryNote(mcpLauncher()) : undefined);
+}
+/** The `mcp` doctor row. */
+export function mcpRegistrationRow(registration) {
+    const { missing, present } = registration;
+    if (missing.length > 0) {
+        const also = 0 === present.length ? '' : ` (registered with ${present.join(', ')})`;
+        return doctorRow(DoctorRow.MCP, `✗ not registered with ${missing.join(', ')}; run \`${SETUP_MCP_COMMAND}\`${also}`);
+    }
+    if (0 === present.length) {
+        return doctorRow(DoctorRow.MCP, `no agent that this check knows was found; \`${SETUP_MCP_COMMAND}\` names the agents it knows`);
+    }
+    return doctorRow(DoctorRow.MCP, `✓ registered with ${present.join(', ')}`);
+}
+/**
+ * Ask `setupMcp` what it would do, and do none of it. Config writes and registration commands are
+ * recorded, not run; only the two `--version` probes run, because they say whether an agent is here.
+ * No telemetry: this is a check, not a registration.
+ */
+export function readMcpRegistration() {
+    const probes = [claudeAvailableProbe(), codexAvailableProbe()];
+    const isProbe = (command, args) => probes.some((p) => p.command === command && p.args.join(' ') === args.join(' '));
+    const result = setupMcp({
+        exists: (p) => existsSync(p),
+        readFile: (p) => {
+            try {
+                return readFileSync(p, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        writeFile: () => { },
+        homeDir: () => homedir(),
+        print: () => { },
+        runCli: (command, args) => (isProbe(command, args) ? probeCli(command, args) : true),
+        reportStep: () => { },
+    });
+    return { missing: result.registered, present: result.alreadyThere };
+}
+/** The repairs for this machine and port, in the order `--fix` applies them. */
+export function machineRepairs(port, reportStep) {
+    return [
+        stalePidRepair({
+            readPid: () => readPid(port),
+            isAlive,
+            removePid: () => {
+                removePid(port);
+            },
+        }),
+        wedgedDaemonRepair(port, {
+            presence: () => probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }),
+            holder: () => identifyPortHolder(port, captureLookup),
+            stop: () => stopWedgedDaemon(port),
+        }),
+        chromiumRepair({
+            probe: () => probeChromiumWithFallback(),
+            install: () => probeLaunchableChromium(),
+            playwrightVersion: bundledPlaywrightVersion(),
+        }),
+        // Before `mcp`: its `setup mcp` also replaces a stale launcher, and this one says so.
+        launcherRepair({
+            line: () => readLauncherLine(process.cwd()),
+            register: () => {
+                handleSetupMcp(reportStep, false);
+            },
+        }),
+        mcpRepair({
+            gaps: () => readMcpRegistration().missing,
+            register: () => {
+                handleSetupMcp(reportStep, false);
+            },
+        }),
+    ];
+}

package/dist/command/cli/drive/drive-command.js

@@ -8,11 +8,10 @@
  */
 import { start } from '../../../index.js';
 import { log } from '../../../log.js';
-import { probePresence, describePresence } from '../../daemon/binding/port-presence.js';
+import { probePresence } from '../../daemon/binding/port-presence.js';
 import { probeDaemon } from '../../../surface/mcp/mcp-proxy.js';
-import { readPid } from '../../daemon/daemon.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
-import { captureLookup, findPortHolder } from '../ports/port-holder.js';
+import { describePortState } from '../../daemon/port-state.js';
 import { DriveMode, NO_ATTACHED_APP, attachedApp, decideDriveMode, describeAttached, driveForeignHolder, driveHeadlessOnAttach, driveRaceLost, requestDriveSession, } from './drive-attach.js';
 /** `projectId` is the one in this directory's `.reticle.json`, read by the caller. */
 export function handleDrive(parsed, projectId) {
@@ -34,10 +33,7 @@ async function driveWithHonestConflict(parsed, projectId) {
     const presence = await probePresence(parsed.port, { tcpOpen: probeDaemon, status: fetchStatus });
     const mode = decideDriveMode(presence);
     if (DriveMode.REFUSE === mode) {
-        const reason = driveForeignHolder(describePresence(presence, parsed.port, {
-            ourPid: readPid(parsed.port),
-            holderPid: findPortHolder(parsed.port, captureLookup)?.pid,
-        }));
+        const reason = driveForeignHolder(describePortState(presence, parsed.port));
         log('reticle_drive_port_conflict', { port: parsed.port, presence, reason });
         process.stderr.write(`${reason}\n`);
         process.exit(1);

package/dist/command/cli/first-use-checks.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Four checks for the first seconds of `init`, `connect`, `setup` and `verify`: the Node.js version,
+ * a browser to drive, `npx.cmd` on the Windows PATH, and the bridge port.
+ *
+ * Each failed check prints one line: the cause and its one fix. A passed check prints nothing. All
+ * are warnings: the command goes on, so a check that is wrong can never block a path that works.
+ * The paths that cannot go on still refuse later, in their own words (the lease preflight, the
+ * init runtime phase).
+ *
+ * `reticle doctor --fix` would repair the two that a program can repair: install the Chromium, and
+ * move init to a free port. That is a separate change.
+ */
+import { PortPresence } from '../daemon/binding/port-presence.js';
+import { type ChromiumProbe } from './doctor/browser/chromium-hint.js';
+/** What the checks read, injected so each one runs against a fake machine in tests. */
+export interface FirstUseFacts {
+    /** `process.versions.node`. */
+    nodeVersion: string;
+    /** The `engines.node` range of this package. */
+    nodeRange: string | undefined;
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    /** The folder of the running `node` executable. */
+    nodeDir: string;
+    exists: (path: string) => boolean;
+    chromium: () => Promise<ChromiumProbe>;
+    /** The bridge port to check. No port: no port check. */
+    port?: number;
+    portPresence?: () => Promise<PortPresence>;
+    describePort?: (presence: PortPresence, port: number) => string;
+}
+/** The line for a Node.js older than the `engines` floor, or undefined. */
+export declare function nodeTooOldLine(version: string, range: string | undefined): string | undefined;
+/** The line for a machine with no browser Reticle can launch, or undefined. */
+export declare function chromiumMissingLine(probe: ChromiumProbe): string | undefined;
+/** The line for a Windows PATH with no `npx.cmd` on it, or undefined. */
+export declare function windowsNpxLine(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, nodeDir: string, exists: (path: string) => boolean): string | undefined;
+/** The warning lines, in a fixed order. Empty when every check passes. */
+export declare function firstUseWarnings(facts: FirstUseFacts): Promise<string[]>;
+/** Write the warnings for this machine to stderr. `port` adds the bridge port check. */
+export declare function writeFirstUseWarnings(port?: number): Promise<void>;

package/dist/command/cli/first-use-checks.js

@@ -0,0 +1,127 @@
+/**
+ * Four checks for the first seconds of `init`, `connect`, `setup` and `verify`: the Node.js version,
+ * a browser to drive, `npx.cmd` on the Windows PATH, and the bridge port.
+ *
+ * Each failed check prints one line: the cause and its one fix. A passed check prints nothing. All
+ * are warnings: the command goes on, so a check that is wrong can never block a path that works.
+ * The paths that cannot go on still refuse later, in their own words (the lease preflight, the
+ * init runtime phase).
+ *
+ * `reticle doctor --fix` would repair the two that a program can repair: install the Chromium, and
+ * move init to a free port. That is a separate change.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, win32 } from 'node:path';
+import { ReticleEnv } from '@reticlehq/core';
+import { PortPresence, probePresence } from '../daemon/binding/port-presence.js';
+import { describePortState } from '../daemon/port-state.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
+import { probeChromiumWithFallback } from '../../launch-chromium.js';
+import { compareVersions } from '../version/version-skew.js';
+import { SERVER_NODE_RANGE } from '../version/identity/server-version.js';
+import { ChromiumPathProblem, configuredChromiumRefusal, } from './doctor/browser/chromium-hint.js';
+const WARNING_PREFIX = '⚠ ';
+const NODE_DOWNLOAD_URL = 'https://nodejs.org';
+/** Only a plain floor (`>=20.11`) is read. Any other range is not checked. */
+const NODE_FLOOR = /^>=\s*(\d+(?:\.\d+)*)$/;
+const NPX_WINDOWS = 'npx.cmd';
+const PATH_KEY = 'path';
+const WINDOWS_PATH_SEPARATOR = ';';
+const WINDOWS = 'win32';
+/** The line for a Node.js older than the `engines` floor, or undefined. */
+export function nodeTooOldLine(version, range) {
+    const floor = range === undefined ? undefined : NODE_FLOOR.exec(range.trim())?.[1];
+    if (floor === undefined) {
+        return undefined;
+    }
+    const order = compareVersions(version, floor);
+    if (order === undefined || order >= 0) {
+        return undefined;
+    }
+    return (`Reticle needs Node.js ${floor} or later, and this is Node.js ${version}. ` +
+        `Install the current Node.js LTS from ${NODE_DOWNLOAD_URL}, then run the command again.`);
+}
+/** The line for a machine with no browser Reticle can launch, or undefined. */
+export function chromiumMissingLine(probe) {
+    if (probe.exists || probe.fallback !== undefined) {
+        return undefined;
+    }
+    if (true === probe.configured && probe.executablePath !== undefined) {
+        return configuredChromiumRefusal(probe.executablePath, probe.problem ?? ChromiumPathProblem.MISSING);
+    }
+    // No playwright at all is a broken install, not a blocked download. `reticle doctor` names it.
+    if (probe.executablePath === undefined) {
+        return undefined;
+    }
+    return ('No Chromium, Chrome or Edge is on this machine, so the first browser session downloads ' +
+        'Chromium (about 150 MiB). If your network blocks that download, install Google Chrome, or set ' +
+        `${ReticleEnv.CHROMIUM_PATH} to a Chromium executable.`);
+}
+/** The line for a Windows PATH with no `npx.cmd` on it, or undefined. */
+export function windowsNpxLine(platform, env, nodeDir, exists) {
+    if (WINDOWS !== platform) {
+        return undefined;
+    }
+    // Windows reads environment names without letter case: `Path` and `PATH` are one variable.
+    const key = Object.keys(env).find((name) => PATH_KEY === name.toLowerCase());
+    const path = key === undefined ? '' : (env[key] ?? '');
+    const onPath = path
+        .split(WINDOWS_PATH_SEPARATOR)
+        .map((dir) => dir.trim().replace(/^"|"$/g, ''))
+        .some((dir) => dir.length > 0 && exists(win32.join(dir, NPX_WINDOWS)));
+    if (onPath) {
+        return undefined;
+    }
+    return (`${NPX_WINDOWS} is not on PATH, so your agent cannot start the Reticle MCP server with npx. ` +
+        `Add ${nodeDir} to PATH, then open a new terminal.`);
+}
+/** Run a probe; a probe that fails gives no line. */
+async function quietly(probe) {
+    try {
+        return await probe();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The warning lines, in a fixed order. Empty when every check passes. */
+export async function firstUseWarnings(facts) {
+    const lines = [
+        nodeTooOldLine(facts.nodeVersion, facts.nodeRange),
+        windowsNpxLine(facts.platform, facts.env, facts.nodeDir, facts.exists),
+    ];
+    const probe = await quietly(facts.chromium);
+    lines.push(probe === undefined ? undefined : chromiumMissingLine(probe));
+    const { port, portPresence, describePort } = facts;
+    if (port !== undefined && portPresence !== undefined && describePort !== undefined) {
+        const presence = await quietly(portPresence);
+        lines.push(PortPresence.FOREIGN === presence ? describePort(presence, port) : undefined);
+    }
+    return lines.flatMap((line) => (line === undefined ? [] : [`${WARNING_PREFIX}${line}`]));
+}
+/** This machine's facts. */
+function thisMachine(port) {
+    return {
+        nodeVersion: process.versions.node,
+        nodeRange: SERVER_NODE_RANGE,
+        platform: process.platform,
+        env: process.env,
+        nodeDir: dirname(process.execPath),
+        exists: existsSync,
+        chromium: () => probeChromiumWithFallback(),
+        ...(port === undefined
+            ? {}
+            : {
+                port,
+                portPresence: () => probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus }),
+                describePort: describePortState,
+            }),
+    };
+}
+/** Write the warnings for this machine to stderr. `port` adds the bridge port check. */
+export async function writeFirstUseWarnings(port) {
+    for (const line of await firstUseWarnings(thisMachine(port))) {
+        process.stderr.write(`${line}\n`);
+    }
+}

package/dist/command/cli/first-verdict-node.d.ts

@@ -0,0 +1,3 @@
+import { type FirstVerdictPorts } from './first-verdict.js';
+/** Bare `reticle` in an unwired folder. Returns the exit code. `stop` records an onboarding stop. */
+export declare function cmdFirstVerdict(port: number, headed: boolean, stop: FirstVerdictPorts['stop']): Promise<number>;

package/dist/command/cli/first-verdict-node.js

@@ -0,0 +1,189 @@
+/**
+ * The first verdict, wired to this machine: the dev server, the daemon and the Reticle browser.
+ * Every decision is in `first-verdict.ts`; this file only gathers facts and runs effects.
+ */
+import { join } from 'node:path';
+import { EventType, PredicateKind, QueryBy, ReticleTool, SnapshotMode, asRecord, } from '@reticlehq/core';
+import { OnboardingStop } from '@reticlehq/core/telemetry';
+import { RETICLE_VERIFY_DEFAULT_PORT } from '../../index.js';
+import { DEV_SERVER_PORTS } from './ports/resolve/cli-port.js';
+import { WELL_KNOWN_RETICLE_PORTS } from './ports/sibling-ports.js';
+import { probeDevServerStates } from '../../portal/session/dev-server/dev-server-probe.js';
+import { detectDevCommandInProject, } from '../../portal/session/dev-server/dev-command.js';
+import { probePage } from '../setup/node-effects.js';
+import { startDevServerAndWait } from '../setup/start-dev-server.js';
+import { defaultPairingTokenDir, readOrCreatePairingTokenSync, } from '../../portal/bridge/pairing-token.js';
+import { acquireLease, connectOverSse, endpointFor, releaseLease, verdictOf, } from './adhoc-verdict.js';
+import { ensureTryDaemon } from './try-command.js';
+import { writeFirstUseWarnings } from './first-use-checks.js';
+import { AppChoice, MSG_NO_APP, chooseApp, linksToOpen, pageFactsOf, runFirstVerdict, } from './first-verdict.js';
+/** How long a dev server this command started gets to serve its first page. */
+const DEV_START_BUDGET_MS = 120_000;
+/** How long a page gets to come back after a navigation, and to go quiet after it. */
+const PAGE_ARRIVAL_MS = 15_000;
+const PAGE_SETTLE_MS = 5_000;
+const CALL_SLACK_MS = 5_000;
+/** The most events read for one page, and the most links read off the start page. */
+const EVENTS_READ = 500;
+const LINKS_READ = 100;
+const HREF = 'href';
+/** The tool-call fields that carry each answer, for `verdictOf`. */
+const NAV_FIELD = 'ok';
+const EVENTS_FIELD = 'events';
+const ELEMENTS_FIELD = 'elements';
+const STATUS_FIELD = 'status';
+/** `reticle_look` answers the find and the page read that the merged surface no longer names alone. */
+const LOOK_FIND = 'find';
+const LOOK_PAGE = 'page';
+/** The bridge, the bench daemon and the verify endpoint. None of them is an app. */
+const RETICLE_PORTS = new Set([
+    ...WELL_KNOWN_RETICLE_PORTS,
+    RETICLE_VERIFY_DEFAULT_PORT,
+]);
+/** Only these events decide the smoke check. */
+const SMOKE_EVENTS = [EventType.NET_REQUEST, EventType.CONSOLE_ERROR, EventType.ERROR_UNCAUGHT];
+/** Start the folder's dev command and wait until it serves a page, or say why it did not. */
+async function startDevServer(command, cwd) {
+    const dir = command.directory === undefined ? cwd : join(cwd, command.directory);
+    process.stdout.write(`Starting your dev server: ${command.command}\n`);
+    const started = await startDevServerAndWait(command.command, dir, DEV_START_BUDGET_MS);
+    return 'failed' in started
+        ? { lines: [started.failed], stop: OnboardingStop.DEV_SERVER_FAILED }
+        : { url: started.url, release: started.stop };
+}
+/** The app in `cwd`, or the one dev server that runs, started when it has to be. */
+async function findApp(cwd) {
+    const devCommand = detectDevCommandInProject(cwd);
+    const pinned = devCommand?.port;
+    const pinnedServing = pinned !== undefined && (await probePage(`http://localhost:${String(pinned)}`)).served;
+    // Only outside an app folder: in one, another server is never the app to check.
+    const running = devCommand === undefined
+        ? (await probeDevServerStates([...DEV_SERVER_PORTS].filter((p) => !RETICLE_PORTS.has(p))))
+            .serving
+        : [];
+    const choice = chooseApp({
+        ...(devCommand === undefined ? {} : { devCommand }),
+        pinnedServing,
+        running,
+    });
+    if (AppChoice.USE === choice.action) {
+        return { url: choice.url };
+    }
+    if (AppChoice.NONE === choice.action) {
+        return choice;
+    }
+    // `chooseApp` starts a server only for a folder with a dev command.
+    return devCommand === undefined
+        ? { lines: MSG_NO_APP, stop: OnboardingStop.NO_WEB_APP }
+        : startDevServer(devCommand, cwd);
+}
+/** One call through `reticle_run`, the route every tool profile has. */
+function run(caller, tool, args, timeoutMs) {
+    return caller.call(ReticleTool.RUN, { tool, args }, timeoutMs);
+}
+/** Wait for the page to go quiet, then read what its document did. */
+async function readPage(caller, sessionId, url, nav) {
+    // A page that never goes quiet is still judged on what it did: the wait only bounds the read.
+    await run(caller, ReticleTool.WAIT_FOR, { predicate: { kind: PredicateKind.SETTLED }, timeout_ms: PAGE_SETTLE_MS, sessionId }, PAGE_SETTLE_MS + CALL_SLACK_MS).catch(() => undefined);
+    const observed = verdictOf(await run(caller, ReticleTool.OBSERVE, {
+        sessionId,
+        since: 0,
+        filters: SMOKE_EVENTS,
+        max_events: EVENTS_READ,
+    }), EVENTS_FIELD);
+    const events = observed?.[EVENTS_FIELD];
+    return pageFactsOf(url, Array.isArray(events) ? events : [], nav);
+}
+/** Go to `url` (or reload), and say whether the page came back and where. */
+async function go(caller, sessionId, url) {
+    const args = url === undefined
+        ? { reload: true, timeout_ms: PAGE_ARRIVAL_MS, sessionId }
+        : { url, timeout_ms: PAGE_ARRIVAL_MS, sessionId };
+    const result = asRecord(verdictOf(await caller.call(ReticleTool.NAVIGATE, args, PAGE_ARRIVAL_MS + CALL_SLACK_MS), NAV_FIELD));
+    const landedOn = result['landedOn'];
+    const next = result['sessionId'];
+    return {
+        arrived: true === result['confirmed'],
+        ...('string' === typeof landedOn ? { landedOn } : {}),
+        sessionId: 'string' === typeof next ? next : sessionId,
+    };
+}
+/** The path of the page on screen, from the page's own status. */
+async function currentPath(caller, sessionId) {
+    const answer = verdictOf(await run(caller, ReticleTool.LOOK, {
+        action: LOOK_PAGE,
+        mode: SnapshotMode.STATUS,
+        sessionId,
+    }).catch(() => undefined), STATUS_FIELD);
+    const route = asRecord(answer?.[STATUS_FIELD])['route'];
+    return 'string' === typeof route ? route : undefined;
+}
+/** The smoke check, through the daemon on `port`, in a Reticle browser with the zero-install reader. */
+async function smokeThroughDaemon(port, url, headed) {
+    const unavailable = await ensureTryDaemon(port);
+    if (unavailable !== undefined) {
+        return { failed: [unavailable] };
+    }
+    const caller = await connectOverSse(endpointFor(port, readOrCreatePairingTokenSync(defaultPairingTokenDir())));
+    try {
+        const opened = await acquireLease(caller, url, headed);
+        if ('failed' in opened) {
+            return opened;
+        }
+        try {
+            // Reload once: the reader then runs from the start of the document, so it sees what the
+            // first load did (a console error during start-up) and not only what came after.
+            const back = await go(caller, opened.leased, undefined);
+            const path = await currentPath(caller, back.sessionId);
+            // The path only: the lease puts its own parameters on the url, and the page is not a link to open.
+            const here = path === undefined ? url : new URL(new URL(path, url).pathname, url).href;
+            const startNav = {
+                arrived: back.arrived,
+                ...(new URL(here).pathname === new URL(url).pathname ? {} : { landedOn: here }),
+            };
+            const start = await readPage(caller, back.sessionId, url, startNav);
+            const found = verdictOf(await run(caller, ReticleTool.LOOK, {
+                action: LOOK_FIND,
+                by: QueryBy.ROLE,
+                value: 'link',
+                attrs: [HREF],
+                limit: LINKS_READ,
+                sessionId: back.sessionId,
+            }), ELEMENTS_FIELD);
+            const elements = Array.isArray(found?.[ELEMENTS_FIELD]) ? found[ELEMENTS_FIELD] : [];
+            const links = elements.flatMap((item) => {
+                const element = asRecord(item);
+                const href = asRecord(element['attrs'])[HREF];
+                const name = element['name'];
+                return 'string' === typeof href
+                    ? [{ name: 'string' === typeof name ? name : '', href }]
+                    : [];
+            });
+            const picked = linksToOpen(here, links);
+            const visited = [];
+            let sessionId = back.sessionId;
+            for (const target of picked.open) {
+                const nav = await go(caller, sessionId, target);
+                sessionId = nav.sessionId;
+                visited.push(await readPage(caller, sessionId, target, nav));
+            }
+            return { start, links: visited, linksFound: picked.found };
+        }
+        finally {
+            await releaseLease(caller, opened.leased);
+        }
+    }
+    finally {
+        await caller.close().catch(() => undefined);
+    }
+}
+/** Bare `reticle` in an unwired folder. Returns the exit code. `stop` records an onboarding stop. */
+export async function cmdFirstVerdict(port, headed, stop) {
+    await writeFirstUseWarnings();
+    return runFirstVerdict({
+        findApp: () => findApp(process.cwd()),
+        smoke: (url) => smokeThroughDaemon(port, url, headed),
+        out: (line) => process.stdout.write(`${line}\n`),
+        stop,
+    });
+}