@reticlehq/server 3.1.0 → 3.3.0

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

@@ -6,11 +6,28 @@
  * pin, a predicate to assert AND a persona to drive as — so it carries more grammar than the rest of
  * the CLI put together.
  */
-import { HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, unknownArgument, } from './cli-parse-grammar.js';
+import { EXPECT_FLAG, HEADED_FLAG, PORT_FLAG, VERIFY_COMMAND, missingOperand, missingValue, notANumber, unknownArgument, } from './cli-parse-grammar.js';
 const TIMEOUT_FLAG = '--timeout';
 const STORAGE_STATE_FLAG = '--storage-state';
-const EXPECT_FLAG = '--expect';
+/** The same predicate, read from a file, which no shell can mangle. See `parseExpect`. */
+const EXPECT_FILE_FLAG = '--expect-file';
 const SESSION_ID_FLAG = '--session-id';
+/**
+ * `--expect` and `--storage-state` cannot both be honoured, so the pair is refused rather than
+ * half-applied.
+ *
+ * `--expect` takes its verdict from the tab a running daemon already owns — it binds nothing and
+ * launches nothing, which is exactly what makes it work while the port is busy. There is nowhere in
+ * that path to load a storage state, and the flag was not refused, it was dropped: a restricted-user
+ * absence assertion was graded against a logged-in admin tab and PASSED. A false green is worse than
+ * a missing answer, and the only honest reply to a question this command cannot ask is to say so.
+ */
+const MSG_EXPECT_WITH_STORAGE_STATE = `${EXPECT_FLAG} cannot be combined with ${STORAGE_STATE_FLAG}: the predicate is graded against ` +
+    'the tab the running daemon already owns, so the storage state would never be loaded and the ' +
+    'verdict would be about whoever is signed in there.\n' +
+    `  Use one of them: ${EXPECT_FLAG} on its own asserts against the session you have, and ` +
+    `${STORAGE_STATE_FLAG} without ${EXPECT_FLAG} makes Reticle drive the url with that state and ` +
+    'replay the saved flows.';
 /** Let Reticle drive the app itself and record what it drove, when nothing is saved yet. */
 const EXPLORE_FLAG = '--explore';
 /** Who to be while exploring — a persona, or the business outcome to reach. Implies --explore. */
@@ -22,6 +39,46 @@ const SELECT_FLAG = '--select';
  * [--session-id <id>]`. The first non-flag token is the preview URL. `defaultPort` is already
  * env + `.reticle.json` + 4400.
  */
+/**
+ * Read a predicate off the command line, allowing for what a Windows shell did to it on the way.
+ *
+ * `cmd.exe` does not treat `'` as a quote character, so the command every doc and README shows
+ * arrives with LITERAL single quotes around the JSON. That is unambiguous, so it is undone: a
+ * matching pair, and only when what is inside then parses.
+ *
+ * PowerShell calling a native executable strips the INNER double quotes instead, and `{kind:signal}`
+ * is not JSON and cannot be repaired without guessing which bare words were keys and which were
+ * string values. Guessing there would assert something the caller did not write, so it is named
+ * instead — with the two forms that do work, because a predicate that does not parse produces NO
+ * verdict at all, which is the worst of the three possible outcomes.
+ */
+function parseExpect(raw) {
+    const unwrapped = raw.length > 1 && raw.startsWith("'") && raw.endsWith("'") ? raw.slice(1, -1) : raw;
+    try {
+        return { kind: 'ok', value: JSON.parse(unwrapped) };
+    }
+    catch {
+        if (looksQuoteStripped(unwrapped)) {
+            return {
+                kind: 'error',
+                message: `${EXPECT_FLAG} received ${unwrapped}, which has had its double quotes removed — that is ` +
+                    'PowerShell passing an argument to a native program, not a problem with the predicate. ' +
+                    `Use ${EXPECT_FILE_FLAG} <path> (no quoting at all), or escape them: ` +
+                    `${EXPECT_FLAG} "{\\"kind\\":\\"signal\\",\\"name\\":\\"order:placed\\"}"`,
+            };
+        }
+        // Named as a JSON problem rather than an unknown argument: the value IS the predicate, and
+        // "unknown argument" would send the reader looking at the flag instead of at their quoting.
+        return {
+            kind: 'error',
+            message: `${EXPECT_FLAG} needs a JSON predicate; could not parse: ${unwrapped}`,
+        };
+    }
+}
+/** A JSON object with every double quote gone: braces, a colon, and not one `"` anywhere. */
+function looksQuoteStripped(value) {
+    return (value.startsWith('{') && value.endsWith('}') && value.includes(':') && !value.includes('"'));
+}
 export function parseVerifySuffix(args, defaultPort) {
     let headless = true;
     let url;
@@ -29,6 +86,7 @@ export function parseVerifySuffix(args, defaultPort) {
     let storageState;
     let sessionId;
     let expect;
+    let expectFile;
     let explore = false;
     let persona;
     const select = [];
@@ -102,17 +160,17 @@ export function parseVerifySuffix(args, defaultPort) {
             const v = args[i];
             if (v === undefined)
                 return missingValue(EXPECT_FLAG);
-            try {
-                expect = JSON.parse(v);
-            }
-            catch {
-                // Named as a JSON problem rather than an unknown argument: the value IS the predicate, and
-                // "unknown argument" would send the reader looking at the flag instead of at their quoting.
-                return {
-                    kind: 'error',
-                    message: `${EXPECT_FLAG} needs a JSON predicate; could not parse: ${v}`,
-                };
-            }
+            const read = parseExpect(v);
+            if ('error' === read.kind)
+                return read;
+            expect = read.value;
+        }
+        else if (arg === EXPECT_FILE_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined)
+                return missingValue(EXPECT_FILE_FLAG);
+            expectFile = v;
         }
         else if (arg.startsWith('--')) {
             return unknownArgument(arg);
@@ -127,12 +185,27 @@ export function parseVerifySuffix(args, defaultPort) {
     }
     if (url === undefined)
         return missingOperand(VERIFY_COMMAND, 'a url');
+    // Two ways to say the same thing, and no way to say two different things. Preferring one
+    // silently is how a run asserts something the person did not write.
+    if (expect !== undefined && expectFile !== undefined) {
+        return {
+            kind: 'error',
+            message: `${EXPECT_FLAG} and ${EXPECT_FILE_FLAG} both name the predicate; pass one`,
+        };
+    }
+    // Refused here, where nothing has been bound and no browser exists yet, because the damage this
+    // pair does is a verdict taken against the wrong user. A predicate from a file is the same
+    // predicate, so it is refused the same way.
+    if ((expect !== undefined || expectFile !== undefined) && storageState !== undefined) {
+        return { kind: 'error', message: MSG_EXPECT_WITH_STORAGE_STATE };
+    }
     return {
         kind: 'ok',
         url,
         headless,
         port,
         ...(expect !== undefined ? { expect } : {}),
+        ...(expectFile !== undefined ? { expectFile } : {}),
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         ...(storageState !== undefined ? { storageState } : {}),
         ...(sessionId !== undefined ? { sessionId } : {}),

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

@@ -15,7 +15,7 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
  * telling readers to do exactly that on 110 lines before it was caught, so the invocation now leads
  * the usage block rather than being a footnote somewhere else.
  */
-export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]\n                [--env KEY=VALUE]... [--files-only]  (wire Reticle into the project in this directory)\n                init is ONBOARDING: it wires the project, boots the app and proves a session\n                connected. It does not drive. The FIRST RUN is the stage that proves a flow:\n                reticle verify <url> --explore --persona \"<who does what>\", or the same thing\n                from an agent as reticle_verify { action: \"explore\", persona: \"\u2026\" }\n                --app picks WHICH app in a monorepo, when several are found\n                --env is what the app needs to reach a usable state: the key from\n                .env.example, the mock backend, the variable that skips an auth wall.\n                Repeatable, and a value may contain spaces and equals signs\n                --files-only writes the files and stops, which is what init did before it\n                learned to boot the app and prove the install works\n                --relaunch prints the exact command that restarts THIS conversation with\n                the tools loaded, so the restart is not a chore handed to a human. It\n                refuses when the session id has no transcript behind it, because\n                --resume on an empty id opens a blank conversation that looks like\n                success. Works with --files-only\n                --license writes the key to .env and keeps .env out of git\n                --json puts the result on stdout, so an agent reads one object\n                --no-open / --no-agents / --url / --timeout are the runtime dials: CI, a\n                headless box, or an app you already run\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N]\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  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)\n                       [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)\n                       [--select <label>]              (repeatable: verify only flows carrying these labels \u2014 no model, exit 0=pass)\n                [--expect '<json predicate>']            (one verdict, no saved flows needed \u2014 asks\n                the daemon that is already running, so nothing is bound and nothing is stopped. This\n                is the path when your client never loaded the reticle_* tools. exit 0 ONLY on\n                verified:\"yes\" \u2014 \"unknown\" is not a pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle; runs/flows recorded on the dashboard):\n  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]\n                                                       (browser device flow by default; --email mails a code)\n  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
+export declare const CLI_USAGE = "usage:  npx @reticlehq/server <command>   (or `reticle <command>` once the bin is on your PATH)\n\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]\n                [--env KEY=VALUE]... [--files-only] [--hooks]  (wire Reticle into the project in this directory)\n                init is ONBOARDING: it wires the project, boots the app and proves a session\n                connected. It does not drive. The FIRST RUN is the stage that proves a flow:\n                reticle verify <url> --explore --persona \"<who does what>\", or the same thing\n                from an agent as reticle_verify { action: \"explore\", persona: \"\u2026\" }\n                --app picks WHICH app in a monorepo, when several are found\n                --env is what the app needs to reach a usable state: the key from\n                .env.example, the mock backend, the variable that skips an auth wall.\n                Repeatable, and a value may contain spaces and equals signs\n                --files-only writes the files and stops, which is what init did before it\n                learned to boot the app and prove the install works\n                --relaunch prints the exact command that restarts THIS conversation with\n                the tools loaded, so the restart is not a chore handed to a human. It\n                refuses when the session id has no transcript behind it, because\n                --resume on an empty id opens a blank conversation that looks like\n                success. Works with --files-only\n                --license writes the key to .env and keeps .env out of git\n                --json puts the result on stdout, so an agent reads one object\n                --no-open / --no-agents / --url / --timeout are the runtime dials: CI, a\n                headless box, or an app you already run\n                --no-mcp skips MORE than the server registration: also the agent rule files\n                (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three\n                only make sense once the tools are reachable.\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)\n  reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)\n  reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)\n  reticle status [--port N] [--json]                   (a readable block; --json for the event)\n  reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  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)\n                       [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)\n                       [--select <label>]              (repeatable: verify only flows carrying these labels \u2014 no model, exit 0=pass)\n                [--expect '<json predicate>' | --expect-file <path>]   (one verdict, no saved\n                flows needed. --expect-file is the form no shell can mangle: cmd.exe keeps the\n                single quotes the docs show, and PowerShell strips the inner double quotes, and\n                a predicate that does not parse produces no verdict at all \u2014 asks the daemon that\n                is already running, so nothing is bound and nothing is stopped. It NEEDS that\n                daemon: with none on the port it refuses and names the flag, rather than reporting\n                on your saved flows instead. Cannot be combined with --storage-state, which this\n                path has nowhere to load. This is the path when your client never loaded the\n                reticle_* tools. exit 0 ONLY on verified:\"yes\" \u2014 \"unknown\" is not a pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle report [--session <id>] [--hook]             (what the latest session claimed, and what held)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode, for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics; status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't; prints exactly what it sends)\n  reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement|experience> \"message\"\n                                                       (agents: file from anywhere, including a setup that never finished)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle; runs/flows recorded on the dashboard):\n  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]\n                                                       (browser device flow by default; --email mails a code)\n  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner: batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";
@@ -58,6 +58,7 @@ export type CliResult = {
     env: string[];
     filesOnly: boolean;
     captureBodies: boolean;
+    hooks: boolean;
     json: boolean;
     relaunch: boolean;
     open: boolean;
@@ -88,6 +89,7 @@ export type CliResult = {
 } | {
     kind: 'status';
     port: number;
+    json: boolean;
 } | {
     kind: 'license';
 } | {
@@ -147,6 +149,7 @@ export type CliResult = {
     storageState?: string;
     sessionId?: string;
     expect?: unknown;
+    expectFile?: string;
     explore?: boolean;
     persona?: string;
     select?: string[];
@@ -164,6 +167,10 @@ export type CliResult = {
     files: string[];
     since?: string;
     hook?: boolean;
+} | {
+    kind: 'report';
+    session?: string;
+    hook: boolean;
 } | {
     kind: 'watch';
     url?: string;

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
@@ -50,18 +50,24 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle stop  [--port N] [--quiet]                    (stop the daemon we started, by its recorded pid)
   reticle kill  [--port N] [--force]                   (free the port by its LISTENER, never the agent's mcp proxy)
   reticle restart [--port N] [--force]                 (kill, then start a daemon and wait for a real bind)
-  reticle status [--port N]
+  reticle status [--port N] [--json]                   (a readable block; --json for the event)
   reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
   reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
   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 report [--session <id>] [--hook]             (what the latest session claimed, and what held)
   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 +108,9 @@ 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';
+/** `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 +155,7 @@ const KNOWN_COMMANDS = new Set([
     HUNT_COMMAND,
     CAPSULES_COMMAND,
     GATE_COMMAND,
+    REPORT_COMMAND,
     WATCH_COMMAND,
     UPDATE_COMMAND,
     ROLLBACK_COMMAND,
@@ -228,6 +238,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 +422,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 +470,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 +536,7 @@ function parseInitFlags(args) {
         env,
         filesOnly,
         captureBodies,
+        hooks,
         json,
         open,
         relaunch,
@@ -606,6 +623,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,
@@ -644,7 +662,10 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
         }
         case STATUS_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
-            return { kind: 'status', port };
+            // The block is the default and the JSON is the opt-in, which is the way round `tutorial`
+            // already settled on: a person typing this should not have to ask for prose, and a caller
+            // parsing it knows to ask for the object.
+            return { kind: 'status', port, json: rest.includes(JSON_FLAG) };
         }
         case 'tutorial': {
             // `--agent` is the opt-in, because a person typing this is the common case and should not have
@@ -769,6 +790,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 } : {}),
@@ -799,6 +821,15 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 ...(hook ? { hook: 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: {
             // `reticle watch [url]` — on file save, report which saved flows must re-verify.
             const url = rest.find((arg) => !arg.startsWith('-'));

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

@@ -11,6 +11,7 @@
  */
 import { type ReticleVerificationRun } from '@reticlehq/core';
 import { type RunningServer } from '../../index.js';
+import { PortPresence } from '../daemon/binding/port-presence.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. */
@@ -104,10 +105,68 @@ 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;
+/** 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";
+    /** 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.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: `--explore` (a model
+     * driving a fresh page), `--headed`, or `--storage-state`. The running daemon's tab can honour
+     * none of them, so replaying there would silently ignore the request.
+     */
+    wantsOwnBrowser?: 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,16 +10,19 @@
  * — 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 { 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 './launch/cli-launch.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';
@@ -182,7 +185,7 @@ async function explore(conn, args, ports) {
 }
 /**
  * Best-effort push of a finished run to the cloud dashboard. Opt-in: only fires when the user has set
- * RETICLE_CLOUD_URL + RETICLE_CLOUD_KEY (the "shifted to server" step). Absent → no-op, nothing leaves the
+ * 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.
  */
@@ -365,8 +368,92 @@ 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.');
+}
+/** 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',
+    /** 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 };
+    // 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 = {
@@ -389,20 +476,32 @@ export function handleVerify(parsed) {
     // 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: true === parsed.explore || !parsed.headless || parsed.storageState !== 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,
                     ...(parsed.sessionId === undefined ? {} : { sessionId: parsed.sessionId }),
                     ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
                 });
@@ -411,16 +510,29 @@ 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;
+            }
+            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);
     })();
 }