@reticlehq/server 3.2.0 → 3.4.0

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

@@ -23,7 +23,7 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
 export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticle <command>\` once the bin is on your PATH)
 
   reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
-                [--env KEY=VALUE]... [--files-only]  (wire Reticle into the project in this directory)
+                [--env KEY=VALUE]... [--files-only] [--hooks]  (wire Reticle into the project in this directory)
                 init is ONBOARDING: it wires the project, boots the app and proves a session
                 connected. It does not drive. The FIRST RUN is the stage that proves a flow:
                 reticle verify <url> --explore --persona "<who does what>", or the same thing
@@ -56,12 +56,21 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>] [--session-id <id>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
                        [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)
                        [--select <label>]              (repeatable: verify only flows carrying these labels — no model, exit 0=pass)
-                [--expect '<json predicate>']            (one verdict, no saved flows needed — asks
-                the daemon that is already running, so nothing is bound and nothing is stopped. This
-                is the path when your client never loaded the reticle_* tools. exit 0 ONLY on
-                verified:"yes" — "unknown" is not a pass)
+                [--expect '<json predicate>' | --expect-file <path>]   (one verdict, no saved
+                flows needed. --expect-file is the form no shell can mangle: cmd.exe keeps the
+                single quotes the docs show, and PowerShell strips the inner double quotes, and
+                a predicate that does not parse produces no verdict at all — asks the daemon that
+                is already running, so nothing is bound and nothing is stopped. It NEEDS that
+                daemon: with none on the port it refuses and names the flag, rather than reporting
+                on your saved flows instead. Cannot be combined with --storage-state, which this
+                path has nowhere to load. This is the path when your client never loaded the
+                reticle_* tools. exit 0 ONLY on verified:"yes" — "unknown" is not a pass)
   reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
-  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)
+  reticle gate [--since <ref>] [--accept-coverage] [file...]  (exit non-zero unless passing artifacts cover the affected flows)
+  reticle report [--session <id>] [--hook]             (what the latest session claimed, and what held)
+  reticle setup mcp                                    (register the MCP server with your agents; the installer's registration half)
+  reticle capsules                                     (list the saved fail-to-pass bug capsules in .reticle/capsules)
+  reticle hunt <dir>                                   (aggregate a directory of crawl reports into one false-green rate)
   reticle watch [url]                                  (on save, report which saved flows must re-verify)
   reticle drive <url> [--headless]                     (foreground mode, for debugging)
   reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)
@@ -102,6 +111,10 @@ const CAPSULES_COMMAND = 'capsules';
 const GATE_COMMAND = 'gate';
 /** Hook mode: prose a human can read, and silence when there was simply nothing to check. */
 const HOOK_FLAG = '--hook';
+const ACCEPT_COVERAGE_FLAG = '--accept-coverage';
+/** `reticle report [--session <id>] [--hook]` — what the latest session claimed, and what held. */
+const REPORT_COMMAND = 'report';
+const SESSION_FLAG = '--session';
 const WATCH_COMMAND = 'watch';
 const UPDATE_COMMAND = 'update';
 const ROLLBACK_COMMAND = 'rollback';
@@ -146,6 +159,7 @@ const KNOWN_COMMANDS = new Set([
     HUNT_COMMAND,
     CAPSULES_COMMAND,
     GATE_COMMAND,
+    REPORT_COMMAND,
     WATCH_COMMAND,
     UPDATE_COMMAND,
     ROLLBACK_COMMAND,
@@ -228,6 +242,8 @@ const FILES_ONLY_FLAG = '--files-only';
  * and `init` runs unattended. Whoever passes this has decided; nothing decides it for them.
  */
 const CAPTURE_BODIES_FLAG = '--capture-bodies';
+/** `--hooks`: also install the print-only Claude Code Stop hook (`reticle report --hook`). */
+const HOOKS_FLAG = '--hooks';
 /**
  * The rest of the runtime surface.
  *
@@ -410,6 +426,7 @@ function parseInitFlags(args) {
     const env = [];
     let filesOnly = false;
     let captureBodies = false;
+    let hooks = false;
     let json = false;
     let open = true;
     let relaunch = false;
@@ -457,6 +474,9 @@ function parseInitFlags(args) {
         else if (arg === CAPTURE_BODIES_FLAG) {
             captureBodies = true;
         }
+        else if (arg === HOOKS_FLAG) {
+            hooks = true;
+        }
         else if (arg === JSON_FLAG) {
             json = true;
         }
@@ -520,6 +540,7 @@ function parseInitFlags(args) {
         env,
         filesOnly,
         captureBodies,
+        hooks,
         json,
         open,
         relaunch,
@@ -561,6 +582,18 @@ function parseTargetArgs(rest) {
     }
     return since === undefined ? { files } : { files, since };
 }
+/**
+ * Whether this command talks to a daemon on the resolved port, and so must not run when
+ * the workspace port conflict (cli-port) has said the port is a guess. `init` carries a port but resolves the
+ * workspace itself, and a tutorial only dials one when asked to run.
+ */
+export function dialsTheDaemon(parsed) {
+    if ('init' === parsed.kind)
+        return false;
+    if ('tutorial' === parsed.kind)
+        return parsed.run;
+    return 'port' in parsed;
+}
 /**
  * @param defaultHeadless Whether a browser Reticle launches should be hidden when no flag says
  *   otherwise. Injected rather than read from the environment here, because this module is pure —
@@ -606,6 +639,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 env: r.env,
                 filesOnly: r.filesOnly,
                 captureBodies: r.captureBodies,
+                hooks: r.hooks,
                 json: r.json,
                 open: r.open,
                 relaunch: r.relaunch,
@@ -772,6 +806,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 ...(r.storageState !== undefined ? { storageState: r.storageState } : {}),
                 ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
                 ...(r.expect !== undefined ? { expect: r.expect } : {}),
+                ...(r.expectFile !== undefined ? { expectFile: r.expectFile } : {}),
                 ...(true === r.explore ? { explore: true } : {}),
                 ...(r.persona !== undefined ? { persona: r.persona } : {}),
                 ...(r.select !== undefined ? { select: r.select } : {}),
@@ -791,15 +826,26 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             return { kind: 'affected', files: t.files, ...(since === undefined ? {} : { since }) };
         }
         case GATE_COMMAND: {
-            // `--hook` is stripped before target parsing, which would reject it as an unknown flag.
+            // Flags are stripped before target parsing, which would reject them as unknown.
             const hook = rest.includes(HOOK_FLAG);
-            const t = parseTargetArgs(rest.filter((a) => a !== HOOK_FLAG));
+            const acceptCoverage = rest.includes(ACCEPT_COVERAGE_FLAG);
+            const t = parseTargetArgs(rest.filter((a) => a !== HOOK_FLAG && a !== ACCEPT_COVERAGE_FLAG));
             const since = t.since ?? implicitSince(t.files);
             return {
                 kind: 'gate',
                 files: t.files,
                 ...(since === undefined ? {} : { since }),
                 ...(hook ? { hook: true } : {}),
+                ...(acceptCoverage ? { acceptCoverage: true } : {}),
+            };
+        }
+        case REPORT_COMMAND: {
+            const at = rest.indexOf(SESSION_FLAG);
+            const session = -1 === at ? undefined : rest[at + 1];
+            return {
+                kind: 'report',
+                hook: rest.includes(HOOK_FLAG),
+                ...(session === undefined ? {} : { session }),
             };
         }
         case WATCH_COMMAND: {

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

@@ -14,6 +14,7 @@ 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';
+const WINDOWS_MANUAL_UPDATE = 'irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex';
 /**
  * Bring the SDK in the CURRENT project to the version being installed.
  *
@@ -94,7 +95,13 @@ export async function handleUpdate() {
         await applyUpdate(target); // calls process.exit; Claude Code restarts
     }
     catch (error) {
-        log('reticle_update_failed', { error: error instanceof Error ? error.message : String(error) });
+        const message = error instanceof Error ? error.message : String(error);
+        log('reticle_update_failed', {
+            error: message,
+            ...('win32' === process.platform && message.includes('spawn EINVAL')
+                ? { hint: `run \`${WINDOWS_MANUAL_UPDATE}\` in PowerShell to update manually` }
+                : {}),
+        });
         process.exitCode = 1;
     }
 }

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

@@ -11,6 +11,8 @@
  */
 import { type ReticleVerificationRun } from '@reticlehq/core';
 import { type RunningServer } from '../../index.js';
+import { PortPresence } from '../daemon/binding/port-presence.js';
+import { type CloudConfig } from '../../memory/cloud/cloud-sync.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. */
@@ -46,6 +48,11 @@ export interface VerifyPorts {
     out: (line: string) => void;
     fail: (line: string) => void;
     exit: (code: number) => void;
+    /**
+     * The platform credential for this repo: the stored key for a linked repo, else the exported
+     * one. A port so the push is testable, and so this reads what every other caller reads.
+     */
+    cloud: () => Promise<CloudConfig | null>;
 }
 interface VerifyArgs {
     url: string;
@@ -104,10 +111,83 @@ export declare function urlParts(url: string): {
  * first bullet — not this change.
  */
 export declare function portBusyMessage(port: number): string;
+/**
+ * What `--expect` is answered with when the port is not serving a daemon.
+ *
+ * It used to be answered with nothing at all. The predicate was read only inside the daemon branch,
+ * so on a free or foreign port the flag was dropped without a word and the command carried on into
+ * the saved-flows path — where it reported, accurately and about something else entirely, that there
+ * were no saved flows to verify. Byte-identical output to the same command with no `--expect` on it.
+ *
+ * That is the documented recovery for a client that never loaded the `reticle_*` tools, so it failed
+ * for the people with no other route to a verdict, and it failed in the one way they could not
+ * diagnose: the refusal they got was true.
+ */
+export declare function expectNeedsDaemonMessage(port: number, presence: PortPresence): string;
+/**
+ * The model key is set here but not in the daemon, which is where the drive runs. The daemon is
+ * usually the one `init` or the agent's MCP client started, from an environment without the key.
+ */
+export declare function daemonLacksKeyMessage(port: number): string;
+/** What `verify` does next, once the options and the state of the port are both known. */
+export declare const VerifyRoute: {
+    /** Ask the daemon that already owns the port for a one-shot verdict on the predicate. */
+    readonly ADHOC: "adhoc";
+    /** Ask the daemon that already owns the port to replay the saved flows. See runAdhocSuite. */
+    readonly ADHOC_SUITE: "adhoc-suite";
+    /** Ask the daemon that already owns the port to explore the url and record flows. */
+    readonly ADHOC_EXPLORE: "adhoc-explore";
+    /** Boot our own daemon, drive the url, replay the flows saved on disk. */
+    readonly FLOWS: "flows";
+    /** Answer the caller, and run nothing. */
+    readonly REFUSE: "refuse";
+};
+export type VerifyRoute = (typeof VerifyRoute)[keyof typeof VerifyRoute];
+export type VerifyPlan = {
+    route: typeof VerifyRoute.ADHOC;
+} | {
+    route: typeof VerifyRoute.ADHOC_SUITE;
+} | {
+    route: typeof VerifyRoute.ADHOC_EXPLORE;
+} | {
+    route: typeof VerifyRoute.FLOWS;
+} | {
+    route: typeof VerifyRoute.REFUSE;
+    message: string;
+};
+/**
+ * All four routes this command has, in one pure function.
+ *
+ * They used to be a pair of nested `if`s that consulted `--expect` only after the port had already
+ * answered as a daemon, which is how one of the four went missing: a predicate on any other port
+ * state fell through to a path that cannot see it. Stating the cases together is what makes an
+ * unhandled one visible, and it lets every one of them be driven with no port, no daemon and no
+ * browser — which is where an argument-level decision belongs.
+ */
+export declare function routeVerify(args: {
+    /** True when the caller supplied a predicate, by `--expect` or `--expect-file`. */
+    hasPredicate: boolean;
+    /**
+     * True when the caller asked for something only a browser of OUR OWN can do: `--headed` or
+     * `--storage-state`. The running daemon's tab can honour neither, so replaying there would
+     * silently ignore the request.
+     */
+    wantsOwnBrowser?: boolean;
+    /**
+     * `--explore`: a model drives the url and records flows. The daemon on the port runs the same
+     * drive (`reticle_verify { action: "explore" }`), so this is NOT a reason to need our own browser —
+     * it used to be, and `init` leaves exactly that daemon behind before recommending this command.
+     */
+    explore?: boolean;
+    presence: PortPresence;
+    port: number;
+}): VerifyPlan;
 export declare function handleVerify(parsed: {
     url: string;
     /** A parsed predicate for a flow-free, one-shot verdict against the running daemon. */
     expect?: unknown;
+    /** The same predicate in a file, which is the form no shell can mangle. Resolved below. */
+    expectFile?: string;
     headless: boolean;
     timeoutMs?: number;
     storageState?: string;

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

@@ -10,17 +10,22 @@
  * — is unit-tested without launching a real browser.
  */
 import { join, basename } from 'node:path';
+import { readFileSync } from 'node:fs';
 import { runAdhocVerdict } from './adhoc-verdict.js';
+import { runAdhocExplore, runAdhocSuite } from './adhoc-suite.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 { probePresence, describePresence, PortPresence, } from '../daemon/binding/port-presence.js';
+import { EXPECT_FLAG } from './cli-parse-grammar.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 { fetchStatus, summarizeStatus } from '../daemon/binding/daemon-status-probe.js';
+import { cloudFetch, createProgressReporter, syncProgressToCloud, syncRunToCloud, SyncOutcome, } from '../../memory/cloud/cloud-sync.js';
+import { linkedCloudPort } from '../../memory/cloud/cloud-config.js';
+import { homedir } from 'node:os';
 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';
@@ -125,7 +130,7 @@ export async function runVerify(args, ports) {
          * live progress by it until the finished run replaces the whole picture.
          */
         const streamId = randomUUID();
-        const cloud = resolveCloudConfig(process.env);
+        const cloud = await ports.cloud().catch(() => null);
         const progress = createProgressReporter(streamId, cloud, cloudFetch);
         let run;
         try {
@@ -137,7 +142,7 @@ export async function runVerify(args, ports) {
             progress.stop();
             await progress.flush().catch(() => undefined);
         }
-        await pushRunToCloud(run, ports); // best-effort; opt-in; never changes the verdict or exit code
+        await pushRunToCloud(run, cloud, 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.
@@ -181,13 +186,12 @@ async function explore(conn, args, ports) {
     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
+ * Best-effort push of a finished run to the cloud dashboard. Opt-in: only fires when this repo is
+ * linked or RETICLE_API_KEY is set. 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);
+async function pushRunToCloud(run, config, ports) {
     if (null === config)
         return;
     const result = await syncRunToCloud(run, config, cloudFetch);
@@ -365,8 +369,106 @@ export function portBusyMessage(port) {
         "your agent's MCP link and the proxy usually respawns a daemon into the gap before verify can " +
         'bind — prefer one of the above.');
 }
+/**
+ * What `--expect` is answered with when the port is not serving a daemon.
+ *
+ * It used to be answered with nothing at all. The predicate was read only inside the daemon branch,
+ * so on a free or foreign port the flag was dropped without a word and the command carried on into
+ * the saved-flows path — where it reported, accurately and about something else entirely, that there
+ * were no saved flows to verify. Byte-identical output to the same command with no `--expect` on it.
+ *
+ * That is the documented recovery for a client that never loaded the `reticle_*` tools, so it failed
+ * for the people with no other route to a verdict, and it failed in the one way they could not
+ * diagnose: the refusal they got was true.
+ */
+export function expectNeedsDaemonMessage(port, presence) {
+    return (`${EXPECT_FLAG} asks the Reticle daemon that already owns port ${String(port)} for the ` +
+        'verdict — it binds nothing and launches nothing, which is what lets it answer while the port ' +
+        `is busy. Right now ${describePresence(presence, port)}.\n\n` +
+        '  The predicate did not run, and nothing was proved.\n\n' +
+        '  • Start a daemon on that port, pointed at the app, then re-run this command: ' +
+        `npx @reticlehq/server serve --port ${String(port)} --drive <url>\n` +
+        `  • Or drop ${EXPECT_FLAG}, and verify drives the url itself and replays your saved flows — ` +
+        'a different question, and it proves nothing about your predicate.');
+}
+/**
+ * The model key is set here but not in the daemon, which is where the drive runs. The daemon is
+ * usually the one `init` or the agent's MCP client started, from an environment without the key.
+ */
+export function daemonLacksKeyMessage(port) {
+    return (`${ReticleEnv.HARNESS_KEY} is set in this shell, but the daemon on port ${String(port)} was ` +
+        'started without it, and the drive runs inside the daemon. Restart it from this shell so it ' +
+        `inherits the key: npx @reticlehq/server restart --port ${String(port)}`);
+}
+/** What `verify` does next, once the options and the state of the port are both known. */
+export const VerifyRoute = {
+    /** Ask the daemon that already owns the port for a one-shot verdict on the predicate. */
+    ADHOC: 'adhoc',
+    /** Ask the daemon that already owns the port to replay the saved flows. See runAdhocSuite. */
+    ADHOC_SUITE: 'adhoc-suite',
+    /** Ask the daemon that already owns the port to explore the url and record flows. */
+    ADHOC_EXPLORE: 'adhoc-explore',
+    /** Boot our own daemon, drive the url, replay the flows saved on disk. */
+    FLOWS: 'flows',
+    /** Answer the caller, and run nothing. */
+    REFUSE: 'refuse',
+};
+/**
+ * All four routes this command has, in one pure function.
+ *
+ * They used to be a pair of nested `if`s that consulted `--expect` only after the port had already
+ * answered as a daemon, which is how one of the four went missing: a predicate on any other port
+ * state fell through to a path that cannot see it. Stating the cases together is what makes an
+ * unhandled one visible, and it lets every one of them be driven with no port, no daemon and no
+ * browser — which is where an argument-level decision belongs.
+ */
+export function routeVerify(args) {
+    if (args.hasPredicate) {
+        return args.presence === PortPresence.DAEMON
+            ? { route: VerifyRoute.ADHOC }
+            : { route: VerifyRoute.REFUSE, message: expectNeedsDaemonMessage(args.port, args.presence) };
+    }
+    if (args.presence !== PortPresence.DAEMON)
+        return { route: VerifyRoute.FLOWS };
+    if (true === args.explore && true !== args.wantsOwnBrowser) {
+        return { route: VerifyRoute.ADHOC_EXPLORE };
+    }
+    // No predicate, but there may be SAVED FLOWS, and a daemon already owns the port: replay them
+    // there rather than refusing, unless the request needs a browser that path never opens.
+    return true === args.wantsOwnBrowser
+        ? { route: VerifyRoute.REFUSE, message: portBusyMessage(args.port) }
+        : { route: VerifyRoute.ADHOC_SUITE };
+}
 export function handleVerify(parsed) {
     const now = () => Date.now();
+    /*
+     * `--expect-file` is `--expect` with the shell taken out of the loop.
+     *
+     * Resolved here rather than in the parser because the parser is pure and reads no disk, and
+     * because the two failures a reader can hit — the file is not there, and what is in it is not
+     * JSON — are worth saying apart. Either one ends the run before anything binds: a predicate that
+     * could not be read produces NO verdict, and exiting 1 with the reason is the only honest answer.
+     */
+    let expectation = parsed.expect;
+    if (parsed.expectFile !== undefined) {
+        let text;
+        try {
+            text = readFileSync(parsed.expectFile, 'utf8');
+        }
+        catch {
+            process.stderr.write(`--expect-file: cannot read ${parsed.expectFile}\n`);
+            process.exit(1);
+            return;
+        }
+        try {
+            expectation = JSON.parse(text);
+        }
+        catch {
+            process.stderr.write(`--expect-file: ${parsed.expectFile} is not valid JSON, so no predicate was read\n`);
+            process.exit(1);
+            return;
+        }
+    }
     const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
     const projectName = basename(process.cwd()) || DEFAULT_PROJECT_NAME;
     const ports = {
@@ -383,26 +485,43 @@ export function handleVerify(parsed) {
         out: (line) => process.stdout.write(`${line}\n`),
         fail: (line) => process.stderr.write(`${line}\n`),
         exit: (code) => process.exit(code),
+        cloud: linkedCloudPort(createNodeFileSystem(), reticleRoot, homedir(), process.env),
     };
     // 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) {
+        const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
+        const plan = routeVerify({
+            hasPredicate: expectation !== undefined,
+            wantsOwnBrowser: !parsed.headless || parsed.storageState !== undefined,
+            explore: true === parsed.explore || parsed.persona !== undefined,
+            presence,
+            port,
+        });
+        switch (plan.route) {
+            // Either the busy port, or a predicate this state cannot answer. Both are refusals that name
+            // what was asked for — never a report about a check nobody requested.
+            case VerifyRoute.REFUSE:
+                ports.fail(plan.message);
+                ports.exit(EXIT_FAIL);
+                return;
             // 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) {
+            // With `--expect` there is a way, and it does not need the port: ask the daemon that already
+            // owns it. See runAdhocVerdict.
+            case VerifyRoute.ADHOC: {
                 const verdict = await runAdhocVerdict({
                     port,
                     ...(parsed.url !== undefined && '' !== parsed.url ? { url: parsed.url } : {}),
-                    predicate: parsed.expect,
+                    predicate: expectation,
+                    // Read fresh, not from `presence`: that probe asks whether a daemon is on the port, and
+                    // this asks whether a TAB is — the difference between asserting and opening the url first.
+                    sessions: async () => summarizeStatus(await fetchStatus(port)).sessions,
                     ...(parsed.sessionId === undefined ? {} : { sessionId: parsed.sessionId }),
                     ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
                 });
@@ -411,16 +530,52 @@ export function handleVerify(parsed) {
                 ports.exit(verdict.code);
                 return;
             }
-            ports.fail(portBusyMessage(port));
-            ports.exit(1);
-            return;
+            // No predicate, a daemon on the port, and saved flows to run: the other half of the same
+            // dead end. The whole promise of a saved suite is that it runs again without an agent.
+            case VerifyRoute.ADHOC_SUITE: {
+                const suite = await runAdhocSuite({
+                    port,
+                    ...(parsed.select === undefined ? {} : { select: parsed.select }),
+                    ...(parsed.sessionId === undefined ? {} : { sessionId: parsed.sessionId }),
+                    ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
+                });
+                for (const line of suite.lines)
+                    ports.out(line);
+                ports.exit(suite.code);
+                return;
+            }
+            // `--explore` with a daemon on the port — the state `init` leaves behind right before it names
+            // this command as the first run. The daemon drives and records; this process only asks.
+            case VerifyRoute.ADHOC_EXPLORE: {
+                const explored = await runAdhocExplore({
+                    port,
+                    url: parsed.url,
+                    ...(parsed.persona === undefined ? {} : { persona: parsed.persona }),
+                    sessions: async () => summarizeStatus(await fetchStatus(port)).sessions,
+                    ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
+                });
+                for (const line of explored.lines)
+                    ports.out(line);
+                // The drive runs INSIDE the daemon, so the key has to be in ITS environment. A reader who
+                // exported it in this shell and got "set ANTHROPIC_API_KEY" back has been told to do the
+                // thing they just did; say where the key is actually missing.
+                if (0 !== explored.code && harnessAvailable(process.env)) {
+                    const refusedForKey = explored.lines.some((line) => line.includes(MSG_NO_HARNESS_KEY));
+                    if (refusedForKey)
+                        ports.fail(daemonLacksKeyMessage(port));
+                }
+                ports.exit(explored.code);
+                return;
+            }
+            case VerifyRoute.FLOWS:
+                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);
+                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);
     })();
 }

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

@@ -489,7 +489,7 @@ const cmdSync = async (argv) => {
     const reticleRoot = join(process.cwd(), RETICLE_DIR);
     const cloud = await resolveProjectCloud(fs, reticleRoot, homedir(), process.env);
     if (null === cloud.config) {
-        err('cloud not attached here — run `reticle link` (or set RETICLE_CLOUD_URL/KEY)');
+        err(cloud.reason ?? 'cloud not attached here: run `reticle link`, or set RETICLE_API_KEY');
         return 1;
     }
     const config = cloud.config;
@@ -521,7 +521,10 @@ const cmdSync = async (argv) => {
                 flows: report.flowsSent,
                 records: report.derivedSent,
                 ...(report.runsRejected.length > 0 ? { rejected: report.runsRejected } : {}),
+                ...(report.refused.length > 0 ? { refused: report.refused } : {}),
             },
+            ...(report.held.length > 0 ? { notSent: report.held } : {}),
+            ...(report.notRetried.length > 0 ? { notRetried: report.notRetried } : {}),
             pulled: report.pulled,
             ...(report.morePending ? { morePending: true } : {}),
             ...(report.error === undefined ? {} : { error: report.error }),
@@ -546,7 +549,7 @@ const repoCloud = async () => {
     const fs = createNodeFileSystem();
     const cloud = await resolveProjectCloud(fs, join(process.cwd(), RETICLE_DIR), homedir(), process.env);
     if (null === cloud.config)
-        throw new Error('cloud not attached here — run `reticle link` (or set RETICLE_CLOUD_URL/KEY)');
+        throw new Error(cloud.reason ?? 'cloud not attached here: run `reticle link`, or set RETICLE_API_KEY');
     return cloud.config;
 };
 /** `reticle runs` — the linked project's recent run artifacts (the key scopes it server-side). */

package/dist/command/cli/cloud-kit.d.ts

@@ -1,6 +1,4 @@
 import { type Session } from './auth/cloud-session.js';
-/** Where `reticle login` dials when nothing says otherwise: the hosted service. */
-export declare const DEFAULT_URL = "https://app.reticle.sh";
 export declare const RETICLE_DIR = ".reticle";
 export declare const SESSION_FILE = "session.json";
 export declare const CREDENTIALS_FILE = "credentials.json";

package/dist/command/cli/cloud-kit.js

@@ -8,15 +8,13 @@
  * `cloud-login` is the first to move — and it is a real seam rather than a file-size dodge: nothing
  * here knows what a project, a credential or a link is.
  */
-import { apiKeyFrom } from '@reticlehq/core';
+import { DEFAULT_PLATFORM_URL, apiKeyFrom, cloudUrlFrom } from '@reticlehq/core';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { z } from 'zod';
 import { cloudFetch } from '../../memory/cloud/cloud-sync.js';
 import { normalizeUrl, readSessionFrom, resolveSessionFor, sessionPath, } from './auth/cloud-session.js';
-/** Where `reticle login` dials when nothing says otherwise: the hosted service. */
-export const DEFAULT_URL = 'https://app.reticle.sh';
 export const RETICLE_DIR = '.reticle';
 export const SESSION_FILE = 'session.json';
 export const CREDENTIALS_FILE = 'credentials.json';
@@ -72,7 +70,7 @@ export const baseUrl = (session, explicit) => {
     // and it cannot leak into a sibling process the way an exported variable does.
     if (explicit !== undefined && explicit.length > 0)
         return normalizeUrl(explicit);
-    const env = process.env['RETICLE_CLOUD_URL'];
+    const env = cloudUrlFrom(process.env);
     if (env !== undefined && env.length > 0)
         return env.replace(/\/+$/, '');
     if (null !== session && session.url.length > 0)
@@ -81,7 +79,7 @@ export const baseUrl = (session, explicit) => {
     // saying because that default was wrong for everyone except us. The default is now the hosted
     // service, so the fallback IS the intended path — and a warning printed on the correct path is
     // how people learn to ignore stderr, which is where the real problems are written.
-    return DEFAULT_URL;
+    return DEFAULT_PLATFORM_URL;
 };
 /** Bearer for a command: an explicit api key (agent) wins, else the human login token. */
 export const bearer = (session) => apiKeyFrom(process.env) ?? session?.token ?? null;