@reticlehq/server 2.14.0 → 3.2.0

package/dist/command/cli/cli-update-commands.js

@@ -0,0 +1,112 @@
+/**
+ * The self-update command pair — `reticle update` and `reticle rollback`.
+ *
+ * Split out of cli.ts, which sits at the 600-line cap: these two are one cohesive unit (swap the
+ * installed version, restart) and the file they came from is the CLI's dispatch table, which grows
+ * for entirely different reasons.
+ */
+import { checkForUpdate } from '../update/update-checker.js';
+import { updateTarget } from '../update/update-nudge.js';
+import { applyUpdate, rollback } from '../update/updater.js';
+import { refreshAgentRules, detectPackageManager, buildNodeIo, SILENT_HOST } from '@reticlehq/init';
+import { SERVER_VERSION } from '../version/identity/server-version.js';
+import { log } from '../../log.js';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { reticleDepsOf, sdkSyncCommand } from '../update/sdk-sync.js';
+/**
+ * Bring the SDK in the CURRENT project to the version being installed.
+ *
+ * Best-effort and non-fatal on purpose: `reticle update` is run from wherever the human happens to
+ * be, which is often not an app at all. A directory with no manifest, or one that has none of our
+ * packages, simply has nothing to sync — that is a normal outcome, not a failure, and it must never
+ * stop the CLI half from happening.
+ */
+function syncProjectSdk(target) {
+    const cwd = process.cwd();
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return; // not an app directory
+    }
+    const packages = reticleDepsOf(manifest);
+    // Nothing to trace and nothing to report: this reads the manifest and runs one package-manager
+    // command. It never enters `runInit`, so there is no init outcome for a host to carry.
+    const io = buildNodeIo(cwd, SILENT_HOST);
+    const pm = detectPackageManager(new Set(io.rootFiles()), new Set(io.listDirs('node_modules')));
+    const cmd = sdkSyncCommand(pm, packages, target);
+    if (null === cmd) {
+        log('reticle_update_sdk', { synced: false, reason: 'no @reticlehq packages in this project' });
+        return;
+    }
+    const ok = io.exec(cmd.command, cmd.args);
+    log('reticle_update_sdk', { synced: ok, packages, to: target, packageManager: pm });
+    if (!ok) {
+        log('reticle_update_sdk_failed', {
+            hint: `run \`${cmd.command} ${cmd.args.join(' ')}\` by hand, then restart the dev server`,
+        });
+    }
+}
+/** `reticle update` — install the latest server version, sync the app's SDK, and restart. */
+export async function handleUpdate() {
+    try {
+        const manifest = await checkForUpdate(SERVER_VERSION, () => Date.now());
+        // Direction, not inequality: the registry being DIFFERENT is not the registry being newer, and
+        // the old gate happily installed a downgrade — reported by a user. See updateTarget.
+        const target = updateTarget(manifest);
+        if (target === undefined) {
+            log('reticle_update', {
+                ok: false,
+                message: 'already on the latest version',
+                version: SERVER_VERSION,
+            });
+            return;
+        }
+        log('reticle_update', { ok: true, from: SERVER_VERSION, to: target });
+        // Bring this project's agent rules up with the version.
+        //
+        // The managed block has always been updatable — marker-delimited, idempotent by comparing
+        // content — and nothing called it after the first install. `mergeMarkedInstruction` is reachable
+        // from `buildPlan` alone, so a project set up on an older release kept that release's
+        // instructions forever and every improvement to them reached new projects only.
+        //
+        // That is backwards: the people who most need better instructions are the ones already
+        // installed and not getting value, and this is the moment they are touching the install anyway.
+        // Only files that ALREADY carry the block are touched, and only inside the markers.
+        const refreshed = refreshAgentRules(process.cwd(), {
+            read: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : null),
+            write: (path, content) => {
+                writeFileSync(path, content, 'utf8');
+            },
+        });
+        if (0 !== refreshed.updated.length)
+            log('reticle_rules_refreshed', { files: refreshed.updated, to: target });
+        // The app's SDK FIRST, then the CLI. `reticle update` used to swap only the CLI, so the command
+        // whose job is keeping an install current was itself a way to produce a version-skewed pair —
+        // and the skew message told people to run it to fix an outdated SDK, which it could not do.
+        //
+        // Before the CLI swap because `applyUpdate` never returns (it execs and exits). If this half
+        // fails the daemon is still the older one, which is the direction the HELLO check names clearly
+        // and a re-run fixes; the reverse would leave a new daemon talking to an old page.
+        syncProjectSdk(target);
+        await applyUpdate(target); // calls process.exit; Claude Code restarts
+    }
+    catch (error) {
+        log('reticle_update_failed', { error: error instanceof Error ? error.message : String(error) });
+        process.exitCode = 1;
+    }
+}
+/** `reticle rollback` — restore the previous server version and restart. */
+export async function handleRollback() {
+    try {
+        await rollback(); // calls process.exit
+    }
+    catch (error) {
+        log('reticle_rollback_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        process.exitCode = 1;
+    }
+}

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

@@ -0,0 +1,124 @@
+/**
+ * `reticle verify <url>` — one-shot, non-MCP verification. It boots the engine in drive mode (Reticle owns
+ * a browser pointed at the preview URL), waits for the in-page SDK to dial back, replays every saved
+ * flow, renders the verdict, and exits 0 on pass / 1 otherwise. The same ReticleRunner + verdict the MCP
+ * and HTTP paths use — so a platform/CI agent that can only run a shell command (Lovable, Emergent,
+ * GitHub Actions) gets a byte-identical artifact without speaking MCP.
+ *
+ * The orchestration (runVerify) is split from the live wiring (openLiveConnection) behind VerifyPorts,
+ * so the decision logic — including the two honesty guards (no session, no flows ⇒ never a green pass)
+ * — is unit-tested without launching a real browser.
+ */
+import { type ReticleVerificationRun } from '@reticlehq/core';
+import { type RunningServer } from '../../index.js';
+import { type VerifyProgressListener } from '../../judgement/runs/reticle-runner.js';
+import type { ToolDeps } from '../../surface/tools/tool-kit.js';
+/** The live capabilities runVerify needs — faked in tests so the logic runs without a browser. */
+export interface VerifyConnection {
+    /** Resolve true once a browser session has connected, or false at timeout. */
+    sessionReady(timeoutMs: number): Promise<boolean>;
+    /**
+     * Flow names to verify, after selection. `select` narrows to flows carrying ANY of those labels.
+     *
+     * The connection applies it rather than the caller, because a label lives inside the flow file and
+     * only the connection can read one.
+     */
+    listFlows(select?: readonly string[]): Promise<string[]>;
+    /**
+     * Drive the app with a model and save what it drove. Present only when a model is configured.
+     *
+     * Optional on the interface on purpose: the harness is unavailable on a machine with no key, and
+     * every other path through this command has to keep working exactly as it did.
+     */
+    explore?: (focus?: string) => Promise<{
+        savedFlows: readonly string[];
+        steps: number;
+    }>;
+    /**
+     * `onProgress` is narration for a run in flight — see `verify-progress.ts` in core. Optional at
+     * every layer: a connection that ignores it behaves exactly as it did before.
+     */
+    verify(onProgress?: VerifyProgressListener): Promise<ReticleVerificationRun>;
+    close(): Promise<void>;
+}
+export interface VerifyPorts {
+    connect: () => Promise<VerifyConnection>;
+    out: (line: string) => void;
+    fail: (line: string) => void;
+    exit: (code: number) => void;
+}
+interface VerifyArgs {
+    url: string;
+    timeoutMs: number;
+    /** Drive the app with a model first, saving flows, when there is nothing saved yet. */
+    explore?: boolean;
+    /** Who to be, or what to accomplish, while exploring. Implies `explore`. */
+    persona?: string;
+    /** Verify only flows carrying ANY of these labels. */
+    select?: string[];
+}
+/** Orchestration: boot → wait for a session → replay flows → verdict → exit code. Browser-free. */
+export declare function runVerify(args: VerifyArgs, ports: VerifyPorts): Promise<void>;
+/**
+ * Reconstruct the disk-backed ToolDeps over the live bridge + driven browser the daemon owns.
+ *
+ * Exported because the demo tour needs the same thing, and a second copy of this constructor is a
+ * second place to forget a field when `ToolDeps` grows one — the failure being a tool that refuses
+ * at runtime for want of a store nobody noticed was missing.
+ */
+export declare function buildVerifyDeps(running: RunningServer, reticleRoot: string, now: () => number): ToolDeps;
+/** Split a drive URL into its origin + whether it's loopback — decides token/injection pairing. */
+export declare function urlParts(url: string): {
+    origin?: 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.
+ *
+ * The message says every way out rather than picking one, and it says FIRST that a busy port is the
+ * normal state rather than a fault — an install that worked leaves a daemon on it, so a reader who
+ * arrives here has done nothing wrong and should not go looking for what they broke (#689).
+ *
+ * `reticle drive` leads, because it is the only option that works in the state most people are in
+ * when they reach this message: the client exposes no `reticle_*` tools (Codex, Cursor Cloud,
+ * Antigravity, a session whose MCP link dropped), which is exactly when the CLI is reached for. It
+ * ATTACHES to the running daemon rather than binding — see cli/drive/drive-attach.ts — so there is nothing
+ * to stop, nothing to race, and it hands back a sessionId the daemon owns. The advice that used to
+ * lead, "ask the daemon through the tools", is the one thing that reader by construction cannot do.
+ *
+ * Stopping the daemon stays on the list and stays LAST of the working options, with the reason: the
+ * MCP proxy respawns one into the gap, so `stop` is a race the caller usually loses, and it kills
+ * the agent's own link on the way past.
+ *
+ * `verify` itself attaching, rather than needing the port at all, is the real fix and is #689's
+ * first bullet — not this change.
+ */
+export declare function portBusyMessage(port: number): string;
+export declare function handleVerify(parsed: {
+    url: string;
+    /** A parsed predicate for a flow-free, one-shot verdict against the running daemon. */
+    expect?: unknown;
+    headless: boolean;
+    timeoutMs?: number;
+    storageState?: string;
+    sessionId?: string;
+    /** Verify only flows carrying ANY of these labels. */
+    select?: string[];
+    /** Drive the app with a model and record flows, when there are none saved yet. */
+    explore?: boolean;
+    /** Who to be, or what to accomplish, while exploring. Implies `explore`. */
+    persona?: string;
+    /** Bridge port — parseCliArgs already resolves --port / RETICLE_PORT / .reticle.json into this. */
+    port: number;
+}): void;
+export {};

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

@@ -0,0 +1,426 @@
+/**
+ * `reticle verify <url>` — one-shot, non-MCP verification. It boots the engine in drive mode (Reticle owns
+ * a browser pointed at the preview URL), waits for the in-page SDK to dial back, replays every saved
+ * flow, renders the verdict, and exits 0 on pass / 1 otherwise. The same ReticleRunner + verdict the MCP
+ * and HTTP paths use — so a platform/CI agent that can only run a shell command (Lovable, Emergent,
+ * GitHub Actions) gets a byte-identical artifact without speaking MCP.
+ *
+ * The orchestration (runVerify) is split from the live wiring (openLiveConnection) behind VerifyPorts,
+ * so the decision logic — including the two honesty guards (no session, no flows ⇒ never a green pass)
+ * — is unit-tested without launching a real browser.
+ */
+import { join, basename } from 'node:path';
+import { runAdhocVerdict } from './adhoc-verdict.js';
+import { exploreApp, harnessAvailable, MSG_NO_HARNESS_KEY, } from '../../surface/tools/harness-explore.js';
+import { resolveSuiteSelection } from '../../language/flows/suite-selection.js';
+import { readOrCreatePairingTokenSync, defaultPairingTokenDir, } from '../../portal/bridge/pairing-token.js';
+import { randomUUID } from 'node:crypto';
+import { RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, VerifyPhase, } from '@reticlehq/core';
+import { start } from '../../index.js';
+import { probePresence, PortPresence } from '../daemon/binding/port-presence.js';
+import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
+import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { cloudFetch, createProgressReporter, resolveCloudConfig, syncProgressToCloud, syncRunToCloud, SyncOutcome, } from '../../memory/cloud/cloud-sync.js';
+import { ReticleRunner } from '../../judgement/runs/reticle-runner.js';
+import { createRunnerPort } from '../../judgement/runs/runner-port.js';
+import { RunStore } from '../../judgement/runs/artifact/run-store.js';
+import { renderRunReport } from '../../judgement/runs/artifact/render-report.js';
+import { BaselineStore } from '../../memory/project/baselines.js';
+import { RecordingStore } from '../../language/flows/recording/tape/recordings.js';
+import { FlowStore } from '../../language/flows/flows.js';
+import { ProjectStore } from '../../memory/project/project-store.js';
+import { AnnotationStore } from '../../language/flows/stores/annotation-store.js';
+import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
+const EXIT_PASS = 0;
+const EXIT_FAIL = 1;
+const DEFAULT_SESSION_TIMEOUT_MS = 15_000;
+const SESSION_POLL_MS = 250;
+const DEFAULT_PROJECT_NAME = 'app';
+const VERIFY_AGENT_ID = 'reticle-cli';
+const MSG_NO_SESSION = 'No app connected: Reticle drove the URL but no @reticlehq/browser session dialed back.\n' +
+    '  Make sure the SDK is in the build and reticle.connect() runs on the preview page' +
+    ' (for a non-localhost preview: allowNonLocalhost + a pairing token).';
+const MSG_NO_FLOWS = 'No saved flows to verify (.reticle/flows is empty), so refusing to report a pass for verifying nothing.\n' +
+    '  Flows are recorded interactively by an agent (reticle_record{action:"start"} → act → reticle_flow_save via the\n' +
+    '  MCP tools), then committed to .reticle/flows/. In CI, check those files in and re-run `reticle verify`.\n' +
+    '  Or let Reticle record them for you: `reticle verify <url> --explore` drives the app itself and saves what it\n' +
+    '  drove, so every run after the first one replays with no model in the loop.';
+/** What a drive that produced nothing is allowed to be reported as. Never a pass — see runVerify. */
+const MSG_EXPLORED_NOTHING = 'The drive saved no flows, so there is still nothing to verify. Nothing was proved.';
+const MSG_VERIFY_PREFIX = 'verify failed: ';
+function errMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function openConnection(ports) {
+    try {
+        return await ports.connect();
+    }
+    catch (error) {
+        ports.fail(MSG_VERIFY_PREFIX + errMessage(error));
+        ports.exit(EXIT_FAIL);
+        return undefined;
+    }
+}
+/** Orchestration: boot → wait for a session → replay flows → verdict → exit code. Browser-free. */
+export async function runVerify(args, ports) {
+    const conn = await openConnection(ports);
+    if (conn === undefined)
+        return;
+    try {
+        const ready = await conn.sessionReady(args.timeoutMs);
+        if (!ready) {
+            ports.fail(MSG_NO_SESSION);
+            ports.exit(EXIT_FAIL);
+            return;
+        }
+        let names = await conn.listFlows(args.select);
+        /*
+         * A selection that matched nothing is NOT "no flows to verify".
+         *
+         * The generic refusal below would send somebody to record a flow they already have, while the
+         * real fault is a label that does not exist. And treating it as an empty suite is how a typo
+         * becomes a green pass over zero flows -- exactly the shape this command's exit code exists to
+         * prevent.
+         */
+        if (0 === names.length && args.select !== undefined && args.select.length > 0) {
+            ports.fail(`No flow carries ${args.select.map((label) => `"${label}"`).join(' or ')}, so nothing ran ` +
+                `and nothing was proved. Check the label, or run without --select to verify every flow.`);
+            ports.exit(EXIT_FAIL);
+            return;
+        }
+        /*
+         * Drive the app ourselves, but only when asked and only when there is nothing to replay.
+         *
+         * Never automatic. A drive spends somebody's model budget and really clicks things in their app,
+         * and neither is a decision this command gets to make on their behalf. And never INSTEAD of
+         * replaying: saved flows are the cheap, deterministic path, so a project that already has them
+         * pays nothing here.
+         */
+        if (0 === names.length && (true === args.explore || args.persona !== undefined)) {
+            const explored = await explore(conn, args, ports);
+            if (!explored)
+                return;
+            names = await conn.listFlows();
+        }
+        if (0 === names.length) {
+            ports.fail(MSG_NO_FLOWS);
+            ports.exit(EXIT_FAIL);
+            return;
+        }
+        /*
+         * Narrate the run while it happens.
+         *
+         * Everything else the CLI reports is a finished artifact, which is the right shape for evidence
+         * and the wrong shape for the minutes a verification actually takes. Without this the dashboard
+         * has nothing to show between "linked" and "done", and a run that is working looks exactly like
+         * one that has died — the ambiguity somebody spent fifteen minutes inside.
+         *
+         * Opt-in and best-effort: no cloud credentials means nothing is buffered and nothing is sent.
+         */
+        /*
+         * A correlation id for the STREAM, minted before the run exists.
+         *
+         * The artifact's own `runId` is only assigned once verification finishes, and these events have
+         * to be attributable from the first one — so the stream gets its own id, and the dashboard keys
+         * live progress by it until the finished run replaces the whole picture.
+         */
+        const streamId = randomUUID();
+        const cloud = resolveCloudConfig(process.env);
+        const progress = createProgressReporter(streamId, cloud, cloudFetch);
+        let run;
+        try {
+            run = await conn.verify(progress.onProgress);
+        }
+        finally {
+            // Stopped before the last flush so the timer cannot fire mid-send, and flushed after it so the
+            // events from the final flow are not thrown away with the interval that would have sent them.
+            progress.stop();
+            await progress.flush().catch(() => undefined);
+        }
+        await pushRunToCloud(run, ports); // best-effort; opt-in; never changes the verdict or exit code
+        /*
+         * The last event anybody watching is waiting for, sent after the artifact has actually landed —
+         * so "pushed" on a dashboard means the run is really there, not that we were about to try.
+         */
+        await syncProgressToCloud(streamId, 
+        // The run's OWN injected timestamp — no wall clock is read in this path (rule 7).
+        [{ phase: VerifyPhase.PUSHED, at: run.createdAt }], cloud, cloudFetch).catch(() => undefined);
+        ports.out(renderRunReport(run));
+        ports.exit(run.verdict.status === VerdictStatus.PASS ? EXIT_PASS : EXIT_FAIL);
+    }
+    catch (error) {
+        ports.fail(MSG_VERIFY_PREFIX + errMessage(error));
+        ports.exit(EXIT_FAIL);
+    }
+    finally {
+        await conn.close().catch(() => undefined);
+    }
+}
+/**
+ * Drive the app with a model, and say plainly what came of it.
+ *
+ * Returns false when the run should stop. A drive that saved nothing is NOT a pass: the honest
+ * refusal below it is the whole reason this command exists, and reaching it through an expensive
+ * drive rather than an empty directory changes nothing about what was proved.
+ */
+async function explore(conn, args, ports) {
+    if (conn.explore === undefined) {
+        ports.fail(MSG_NO_HARNESS_KEY);
+        ports.exit(EXIT_FAIL);
+        return false;
+    }
+    ports.out('No saved flows yet — driving the app to record some.');
+    const drive = await conn.explore(args.persona);
+    if (0 === drive.savedFlows.length) {
+        ports.fail(MSG_EXPLORED_NOTHING);
+        ports.exit(EXIT_FAIL);
+        return false;
+    }
+    ports.out(`Recorded ${String(drive.savedFlows.length)} flow(s) in ${String(drive.steps)} step(s): ` +
+        `${drive.savedFlows.join(', ')} — every future run replays these with no model in the loop.`);
+    return true;
+}
+/**
+ * Best-effort push of a finished run to the cloud dashboard. Opt-in: only fires when the user has set
+ * RETICLE_CLOUD_URL + RETICLE_API_KEY (the "shifted to server" step). Absent → no-op, nothing leaves the
+ * machine (the no-phone-home default). A push failure NEVER changes the verdict or exit code — the run is
+ * already reported locally; the cloud copy is an enhancement.
+ */
+async function pushRunToCloud(run, ports) {
+    const config = resolveCloudConfig(process.env);
+    if (null === config)
+        return;
+    const result = await syncRunToCloud(run, config, cloudFetch);
+    if (result.outcome === SyncOutcome.SYNCED) {
+        ports.out(`↑ run ${run.runId} recorded on the Reticle dashboard`);
+    }
+    else {
+        ports.fail(`cloud run sync failed (${result.status ?? result.error ?? 'error'}); run kept locally`);
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForSession(sessions, timeoutMs, now) {
+    const deadline = now() + timeoutMs;
+    while (now() < deadline) {
+        if (sessions.count() > 0)
+            return true;
+        await delay(SESSION_POLL_MS);
+    }
+    return sessions.count() > 0;
+}
+/**
+ * Reconstruct the disk-backed ToolDeps over the live bridge + driven browser the daemon owns.
+ *
+ * Exported because the demo tour needs the same thing, and a second copy of this constructor is a
+ * second place to forget a field when `ToolDeps` grows one — the failure being a tool that refuses
+ * at runtime for want of a store nobody noticed was missing.
+ */
+export function buildVerifyDeps(running, reticleRoot, now) {
+    const fs = createNodeFileSystem();
+    const deps = {
+        sessions: running.bridge.sessions,
+        baselines: new BaselineStore(),
+        recordings: new RecordingStore(),
+        flows: new FlowStore(fs, reticleRoot, { now }),
+        annotations: new AnnotationStore(),
+        project: new ProjectStore(fs, reticleRoot, { now }),
+        fs,
+        reticleRoot,
+        now,
+    };
+    if (running.realInput !== undefined)
+        deps.realInput = running.realInput;
+    return deps;
+}
+/** Split a drive URL into its origin + whether it's loopback — decides token/injection pairing. */
+export function urlParts(url) {
+    try {
+        const u = new URL(url);
+        return { origin: u.origin, loopback: isLoopbackHostname(u.hostname) };
+    }
+    catch {
+        return { loopback: false };
+    }
+}
+async function openLiveConnection(opts) {
+    // A localhost preview connects natively (the app's own reticle.connect is allowed on loopback), so the
+    // bridge stays token-free. A HOSTED (non-localhost) preview is blocked by the SDK's connection policy
+    // and rejected as a foreign origin — so there we pair via a one-shot token both the bridge and the
+    // injected reticle.connect share, plus the preview's origin on the allow-list. That split is what makes
+    // both "verify my dev server" and "verify a live Lovable URL" work from the same command.
+    // `reticle verify` boots its OWN daemon. Hardcoding the default port meant it crashed with EADDRINUSE
+    // on any machine already running a daemon — i.e. every developer machine — so honour RETICLE_PORT.
+    const envPort = Number(process.env[ReticleEnv.PORT]);
+    const port = Number.isFinite(envPort) && envPort > 0 ? envPort : opts.port;
+    const { origin, loopback } = urlParts(opts.url);
+    const pairing = loopback
+        ? {}
+        : (() => {
+            const token = randomUUID();
+            const bridgeUrl = bridgeWsUrl(port);
+            return {
+                token,
+                injectConnect: { token, url: bridgeUrl },
+                ...(origin !== undefined ? { allowedOrigins: [origin] } : {}),
+            };
+        })();
+    const running = await start({
+        port,
+        driveUrl: opts.url,
+        headless: opts.headless,
+        mcp: false,
+        reticleRoot: opts.reticleRoot,
+        now: opts.now,
+        ...pairing,
+        ...(opts.storageState !== undefined ? { storageState: opts.storageState } : {}),
+    });
+    const deps = buildVerifyDeps(running, opts.reticleRoot, opts.now);
+    const runner = new ReticleRunner(createRunnerPort(deps, opts.sessionId));
+    return {
+        sessionReady: (timeoutMs) => waitForSession(deps.sessions, timeoutMs, opts.now),
+        listFlows: async (select) => select === undefined || 0 === select.length
+            ? deps.flows.list()
+            : (await resolveSuiteSelection(deps, undefined, { labels: [...select] })).run,
+        // Absent, not throwing, when no model is configured: the CLI reads its absence as "unavailable"
+        // and prints the one sentence that makes it available.
+        ...(harnessAvailable(process.env)
+            ? {
+                explore: async (focus) => {
+                    const result = await exploreApp(deps, process.env, {
+                        ...(focus === undefined ? {} : { focus }),
+                        ...(opts.sessionId === undefined ? {} : { sessionId: opts.sessionId }),
+                    });
+                    return { savedFlows: result.savedFlows, steps: result.drive.steps };
+                },
+            }
+            : {}),
+        verify: async (onProgress) => {
+            const run = await runner.verify({
+                project: { name: opts.projectName, framework: RunFramework.OTHER, previewUrl: opts.url },
+                agent: { id: VERIFY_AGENT_ID, kind: RunAgentKind.OEM_PIPELINE },
+                trigger: { kind: RunTrigger.OEM },
+                profile: RunProfile.PROD_PREVIEW,
+                ...(onProgress === undefined ? {} : { onProgress }),
+            });
+            // Persist the artifact. `reticle gate` decides from RunStore.latest, so without this the
+            // documented CI loop is broken end to end: `reticle verify` could pass and the gate would still
+            // block, because it never sees a passing run. (Only the optional `serve --http` endpoint used to
+            // persist.) Best-effort — a disk failure must not turn a passing verification into a failure.
+            try {
+                await new RunStore(deps.fs, opts.reticleRoot).write(run);
+            }
+            catch {
+                // artifact persistence is not the verdict
+            }
+            return run;
+        },
+        close: () => running.close(),
+    };
+}
+/** 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.
+ *
+ * The message says every way out rather than picking one, and it says FIRST that a busy port is the
+ * normal state rather than a fault — an install that worked leaves a daemon on it, so a reader who
+ * arrives here has done nothing wrong and should not go looking for what they broke (#689).
+ *
+ * `reticle drive` leads, because it is the only option that works in the state most people are in
+ * when they reach this message: the client exposes no `reticle_*` tools (Codex, Cursor Cloud,
+ * Antigravity, a session whose MCP link dropped), which is exactly when the CLI is reached for. It
+ * ATTACHES to the running daemon rather than binding — see cli/drive/drive-attach.ts — so there is nothing
+ * to stop, nothing to race, and it hands back a sessionId the daemon owns. The advice that used to
+ * lead, "ask the daemon through the tools", is the one thing that reader by construction cannot do.
+ *
+ * Stopping the daemon stays on the list and stays LAST of the working options, with the reason: the
+ * MCP proxy respawns one into the gap, so `stop` is a race the caller usually loses, and it kills
+ * the agent's own link on the way past.
+ *
+ * `verify` itself attaching, rather than needing the port at all, is the real fix and is #689's
+ * first bullet — not this change.
+ */
+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' +
+        '  This is the NORMAL state after a working install, not a fault: the daemon your MCP client ' +
+        'started owns that port.\n\n' +
+        `  • Drive the app through the daemon that is already there — this needs no tools and stops ` +
+        `nothing: npx @reticlehq/server drive <url>\n` +
+        '  • If your client HAS the Reticle tools, ask that daemon directly: ' +
+        'reticle_run { tool: "reticle_verify", args: { action: "change", files: ["..."] } }\n' +
+        `  • Or run both on another port, if your app is configured for it: RETICLE_PORT=<port> ` +
+        'npx @reticlehq/server verify <url>\n' +
+        `  • Stopping the daemon (npx @reticlehq/server stop --port ${String(port)}) works, but it cuts ` +
+        "your agent's MCP link and the proxy usually respawns a daemon into the gap before verify can " +
+        'bind — prefer one of the above.');
+}
+export function handleVerify(parsed) {
+    const now = () => Date.now();
+    const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
+    const projectName = basename(process.cwd()) || DEFAULT_PROJECT_NAME;
+    const ports = {
+        connect: () => openLiveConnection({
+            url: parsed.url,
+            headless: parsed.headless,
+            reticleRoot,
+            projectName,
+            now,
+            port: parsed.port ?? RETICLE_DEFAULT_PORT,
+            ...(parsed.storageState !== undefined ? { storageState: parsed.storageState } : {}),
+            ...(parsed.sessionId !== undefined ? { sessionId: parsed.sessionId } : {}),
+        }),
+        out: (line) => process.stdout.write(`${line}\n`),
+        fail: (line) => process.stderr.write(`${line}\n`),
+        exit: (code) => process.exit(code),
+    };
+    // 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) {
+            // A daemon owning the port is the NORMAL state after a working install, and it used to be the
+            // end of the road: `verify` refused, the other verdict paths need saved flows a first-install
+            // project does not have, and stopping the daemon cuts the agent's own MCP link. An agent could
+            // hold a live, correctly-wired app and have no way to reach a verdict at all.
+            //
+            // With `--expect` there is now a way, and it does not need the port: ask the daemon that
+            // already owns it. See runAdhocVerdict.
+            if (parsed.expect !== undefined) {
+                const verdict = await runAdhocVerdict({
+                    port,
+                    ...(parsed.url !== undefined && '' !== parsed.url ? { url: parsed.url } : {}),
+                    predicate: parsed.expect,
+                    ...(parsed.sessionId === undefined ? {} : { sessionId: parsed.sessionId }),
+                    ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
+                });
+                for (const line of verdict.lines)
+                    ports.out(line);
+                ports.exit(verdict.code);
+                return;
+            }
+            ports.fail(portBusyMessage(port));
+            ports.exit(1);
+            return;
+        }
+        await runVerify({
+            url: parsed.url,
+            timeoutMs: parsed.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS,
+            ...(true === parsed.explore ? { explore: true } : {}),
+            ...(parsed.persona === undefined ? {} : { persona: parsed.persona }),
+            ...(parsed.select === undefined ? {} : { select: parsed.select }),
+        }, ports);
+    })();
+}