@reticlehq/server 3.2.0 → 3.4.0

package/dist/command/cli/answers/gate-hook-message.d.ts

@@ -21,6 +21,12 @@ interface GateHookInput {
     downgraded: readonly string[];
     /** Flows whose coverage was deleted while their files changed. */
     deleted: readonly string[];
+    /** Changed interactive components no saved flow has ever driven. */
+    unflowed?: readonly string[];
+    /** Coverage levels below their best, already worded (`branched 100% -> 50%`). */
+    coverageRegressed?: readonly string[];
+    /** Changed files the browser loaded and never ran a function of. */
+    unexecuted?: readonly string[];
 }
 /**
  * The message, or undefined when there is nothing to say.

package/dist/command/cli/answers/gate-hook-message.js

@@ -37,6 +37,12 @@ export function gateHookMessage(exit, input) {
         lines.push(`  assertions weakened to something fakeable: ${name(input.downgraded)} — a check that cannot fail is not a check`);
     if (input.deleted.length > 0)
         lines.push(`  coverage deleted while its files changed: ${name(input.deleted)}`);
+    if (input.unflowed !== undefined && input.unflowed.length > 0)
+        lines.push(`  changed, and no saved flow drives it: ${name(input.unflowed)} — drive it with reticle_act_and_wait and a declared \`until\``);
+    if (input.coverageRegressed !== undefined && input.coverageRegressed.length > 0)
+        lines.push(`  coverage fell: ${name(input.coverageRegressed)} — something new is uncovered; reticle_verify { action: "crawl", exhaustive: true } names it. If the drop was intended, \`reticle gate --accept-coverage\` records it`);
+    if (input.unexecuted !== undefined && input.unexecuted.length > 0)
+        lines.push(`  changed, and no drive ever ran it: ${name(input.unexecuted)}`);
     if (input.quarantined.length > 0)
         lines.push(`  held back as flaky, so proving nothing: ${name(input.quarantined)}`);
     lines.push('');

package/dist/command/cli/auth/cloud-keystore.d.ts

@@ -33,6 +33,4 @@ interface CredentialWrite {
  * re-link, and refusing it would strand the repo.
  */
 export declare const applyCredential: (store: Record<string, unknown>, write: CredentialWrite) => Record<string, unknown>;
-/** Where the store lives, given the reticle home directory. */
-export declare const credentialsPath: (homeDir: string, file: string) => string;
 export {};

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

@@ -14,7 +14,6 @@
  * two are kept readable (a repo linked by an older CLI must not lose its key) and written only when
  * doing so cannot mislead somebody else.
  */
-import { join } from 'node:path';
 import { credentialSlot } from '../../../memory/cloud/cloud-config.js';
 /** Trailing slashes are not identity: `https://x/` and `https://x` are one cloud. */
 const normalizeUrl = (url) => url.replace(/\/+$/, '');
@@ -93,5 +92,3 @@ export const applyCredential = (store, write) => {
         store[projectId] = { key, url };
     return store;
 };
-/** Where the store lives, given the reticle home directory. */
-export const credentialsPath = (homeDir, file) => join(homeDir, file);

package/dist/command/cli/auth/cloud-session.d.ts

@@ -18,15 +18,19 @@ declare const SessionSchema: z.ZodObject<{
      * is ours" and mints, which is the safe direction.
      */
     orgId: z.ZodOptional<z.ZodString>;
+    /** Who signed in. Absent in sessions written before it was recorded. */
+    email: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     url: string;
     token: string;
     orgName: string;
+    email?: string | undefined;
     orgId?: string | undefined;
 }, {
     url: string;
     token: string;
     orgName: string;
+    email?: string | undefined;
     orgId?: string | undefined;
 }>;
 export type Session = z.infer<typeof SessionSchema>;

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

@@ -19,6 +19,8 @@ const SessionSchema = z.object({
      * is ours" and mints, which is the safe direction.
      */
     orgId: z.string().optional(),
+    /** Who signed in. Absent in sessions written before it was recorded. */
+    email: z.string().optional(),
 });
 /** Trailing slashes are not identity: `https://x/` and `https://x` are one host. */
 export const normalizeUrl = (url) => url.replace(/\/+$/, '');

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

@@ -1,26 +1,29 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { ReticleEnv } from '@reticlehq/core';
+import { devServersForProject, ReticleEnv } from '@reticlehq/core';
 import { readPid, reticleStateHome } from '../daemon/daemon.js';
 import { PortPresence, probePresence } from '../daemon/binding/port-presence.js';
 import { isLocalhostSplit, probeLoopbackReach } from '../daemon/binding/loopback-reach.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
-import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
+import { fetchStatus, summarizeStatus } from '../daemon/binding/daemon-status-probe.js';
 import { daemonLine } from './doctor/doctor-daemon-line.js';
 import { projectWiringLine } from './doctor/doctor-project-line.js';
 import { hasProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
 import { sessionsLine } from './doctor/doctor-sessions-line.js';
 import { captureLookup, describeForeignHolder, findPortHolder } from './ports/port-holder.js';
-import { chromiumHint, probeChromium } from './doctor/browser/chromium-hint.js';
+import { chromiumHint } from './doctor/browser/chromium-hint.js';
+import { probeChromiumWithFallback } from '../../launch-chromium.js';
 import { SERVER_VERSION } from '../version/identity/server-version.js';
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
-import { diagnoseDesktop, isDesktopProject, diagnoseWebCsp } from '@reticlehq/init';
-import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectId, readProjectPort, } from './ports/resolve/cli-port.js';
+import { CspBasis, diagnoseDesktop, diagnoseObservedWebCsp, diagnoseWebCsp, isDesktopProject, resolveWebCspFindings, webCspOptionsFor, } from '@reticlehq/init';
+import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectFramework, readProjectId, readProjectPort, } from './ports/resolve/cli-port.js';
 import { DoctorRow, doctorRow } from './doctor/doctor-rows.js';
 import { attachState, describeAttachState } from '../../surface/mcp/attach-memory.js';
 import { findOccupiedSiblings, siblingListenerNote } from './ports/sibling-ports.js';
 import { daemonsServingProjectElsewhere, resolveDaemonForProject, splitBrainNote, wrongDaemonNote, } from '../daemon/daemon-resolve.js';
 import { isAlive } from '../daemon/daemon.js';
+import { readDevServers } from '../daemon/dev-servers.js';
+import { hasConnectedDocument, observeWebDocument, } from '../../portal/session/dev-server/served-document.js';
 /**
  * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
  * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
@@ -65,7 +68,8 @@ export async function handleDoctor(port) {
     // Filled in only on the daemon branch — there is nothing to ask when no daemon is answering, and
     // the branches below already say so in their own terms.
     let sessions;
-    line(doctorRow(DoctorRow.CHROMIUM, chromiumHint(await probeChromium())));
+    let daemonStatus;
+    line(doctorRow(DoctorRow.CHROMIUM, chromiumHint(await probeChromiumWithFallback())));
     // Ask the PORT, not just the pid file. "not running on :4400" has been printed about a port that
     // was demonstrably occupied, which sends the reader to start a daemon that cannot bind. The three
     // states are genuinely different problems with different fixes, so doctor names which one it is.
@@ -76,6 +80,7 @@ export async function handleDoctor(port) {
         // throwing both away — while skew is invisible everywhere else, reaching the agent as a bare
         // -32000 naming no version. This is the command a human runs at exactly that moment.
         const payload = await fetchStatus(port);
+        daemonStatus = payload;
         const status = asIdentity(payload);
         const built = daemonLine(port, pid, status, {
             version: SERVER_VERSION,
@@ -187,10 +192,27 @@ export async function handleDoctor(port) {
     // The web sibling of the desktop findings below: a `connect-src` that excludes the bridge makes
     // the browser refuse the WebSocket and report it in ITS console only, so every check above passes
     // at an app that can never connect. Named, with the exact text to paste.
-    const csp = diagnoseWebCsp(readProjectFile, port);
+    const devServers = devServersForProject(readDevServers(reticleStateHome()), {
+        projectId,
+        root: process.cwd(),
+    });
+    const observedDocuments = (await Promise.all(devServers.map((server) => observeWebDocument(server.url)))).filter((document) => document !== undefined);
+    const observedCsp = 0 === observedDocuments.length
+        ? undefined
+        : observedDocuments.flatMap((document) => diagnoseObservedWebCsp(document, port));
+    const connected = hasConnectedDocument(summarizeStatus(daemonStatus).sessions, devServers.map((server) => server.url), projectId);
+    const csp = resolveWebCspFindings({
+        // With the wiring `init` recorded, so the two commands name the same rule for one policy.
+        predicted: diagnoseWebCsp(readProjectFile, port, [], webCspOptionsFor(readProjectFramework(process.cwd()))),
+        ...(observedCsp === undefined ? {} : { observed: observedCsp }),
+        connected,
+    });
     if (csp.length > 0) {
         line('');
-        line(`  csp          ✗ a Content-Security-Policy is blocking the Reticle bridge:`);
+        const observed = csp.some((finding) => finding.basis === CspBasis.OBSERVED);
+        line(observed
+            ? `  csp          ✗ a Content-Security-Policy is blocking the Reticle bridge:`
+            : `  csp          ? a configuration may block the Reticle bridge (predicted, not observed):`);
         for (const finding of csp) {
             line(`                 ${finding.file}`);
             line(`                   ${finding.problem}`);

package/dist/command/cli/cli-flow-commands.d.ts

@@ -37,11 +37,8 @@ export declare function handleWatch(): void;
  * failing reproduction plus the consequence that should have held; replay one with reticle_flow_replay.
  */
 export declare function handleCapsules(): Promise<void>;
-/**
- * `reticle gate <file...>` — exit non-zero unless passing artifacts cover the flows affected by the
- * changed files. Flaky flows are quarantined (surfaced, not blocking). The environment-side enforcement
- * that makes verification unavoidable. Never throws; a fault fails closed (exit 1).
- */
 export declare function handleGate(files: string[], since: string | undefined, 
 /** Hook mode: prose for a human, and silence when there was simply nothing to check. */
-hook?: boolean): Promise<void>;
+hook?: boolean, 
+/** Accept today's coverage levels as the best before judging, for a drop that was intended. */
+acceptCoverage?: boolean): Promise<void>;

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

@@ -14,7 +14,9 @@ import { ReticleDir, RunFlowStatus } from '@reticlehq/core';
 import { FlowStore } from '../../language/flows/flows.js';
 import { RunStore } from '../../judgement/runs/artifact/run-store.js';
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
-import { affectedSavedFlows } from '../../language/flows/change/flow-sources.js';
+import { affectedSavedFlows, toFlowSources, } from '../../language/flows/change/flow-sources.js';
+import { isInteractiveSource, unflowedFiles } from '../../language/flows/change/affected.js';
+import { LedgerStore, regressions, staleChanged, unexecutedChanged, } from '../../features/exhaust/ledger.js';
 import { gateDecision } from '../../language/flows/change/gate.js';
 import { FlakeStore } from '../../language/flows/stores/flake-store.js';
 import { formatBuddyStatus } from '../../language/flows/buddy-status.js';
@@ -23,7 +25,7 @@ import { AssertionTiersStore } from '../../language/flows/stores/assertion-tiers
 import { detectDowngrades } from '../../judgement/outcome/assertion-integrity.js';
 import { computeCoverage, flowCoverageReport } from '../../language/flows/suite/coverage.js';
 import { createWatchBatcher } from '../../language/flows/change/watch-batcher.js';
-import { watch } from 'node:fs';
+import { readFileSync, statSync, watch } from 'node:fs';
 import { log } from '../../log.js';
 /** Load the {name, steps} of every saved flow for the active project. */
 /** Explicit files plus, when --since is given, the git-changed files since that ref. */
@@ -163,9 +165,35 @@ export async function handleCapsules() {
  * changed files. Flaky flows are quarantined (surfaced, not blocking). The environment-side enforcement
  * that makes verification unavoidable. Never throws; a fault fails closed (exit 1).
  */
+/**
+ * A changed file's text, or '' when it is gone. `git diff --name-only` answers from the repository
+ * root while the gate may run in a package below it, so leading segments are dropped until the path
+ * resolves from `cwd`.
+ */
+function atChangedPath(cwd, file, read) {
+    const parts = file.split('/');
+    for (let i = 0; i < parts.length; i += 1) {
+        try {
+            return read(join(cwd, ...parts.slice(i)));
+        }
+        catch {
+            // not at this depth; try the path one segment shorter
+        }
+    }
+    return undefined;
+}
+function readChangedFile(cwd, file) {
+    return atChangedPath(cwd, file, (path) => readFileSync(path, 'utf8')) ?? '';
+}
+/** When a changed file was last modified, or undefined when it is gone. Same lookup as its text. */
+function changedFileModifiedAt(cwd, file) {
+    return atChangedPath(cwd, file, (path) => statSync(path).mtimeMs);
+}
 export async function handleGate(files, since, 
 /** Hook mode: prose for a human, and silence when there was simply nothing to check. */
-hook = false) {
+hook = false, 
+/** Accept today's coverage levels as the best before judging, for a drop that was intended. */
+acceptCoverage = false) {
     try {
         const fs = createNodeFileSystem();
         const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
@@ -204,7 +232,32 @@ hook = false) {
         const deleted = Object.entries(baseline)
             .filter(([name, entry]) => !byName.has(name) && entry.sources.some((f) => changedSet.has(f)))
             .map(([name]) => name);
-        const result = gateDecision({ affected, passing, flaky, downgraded, deleted });
+        // Only against a suite that exists: a project with no flows yet is NOTHING_TO_CHECK, and
+        // demanding a flow per edited component on its first day would block every stop.
+        const unflowed = 0 === allFlows.length
+            ? []
+            : unflowedFiles(toFlowSources(allFlows), changed, (file) => isInteractiveSource(readChangedFile(process.cwd(), file)));
+        // The coverage ledger, when one exists: a level that fell below its best, and changed code the
+        // browser loaded and never ran. A project that never folded coverage has an empty ledger and
+        // neither can fire.
+        const ledgerStore = new LedgerStore(fs, reticleRoot);
+        const coverageAccepted = acceptCoverage ? await ledgerStore.acceptCurrent() : [];
+        const ledger = await ledgerStore.load();
+        const unexecuted = unexecutedChanged(ledger.code, changed);
+        // Changed files whose coverage predates the edit: their counts describe the old code, so
+        // `unexecuted` cannot judge them either way. Named rather than silently read as covered; not
+        // blocking, because a destructive exhaustive crawl after every edit is not a price a gate may set.
+        const coverageStale = staleChanged(ledger, changed, (file) => changedFileModifiedAt(process.cwd(), file)).filter((file) => !unexecuted.includes(file));
+        const result = gateDecision({
+            affected,
+            passing,
+            flaky,
+            downgraded,
+            deleted,
+            unflowed,
+            coverageRegressed: regressions(ledger),
+            unexecuted,
+        });
         // Verified-surface coverage over flows: how much of the saved suite this run actually exercised.
         const coverage = computeCoverage({ testids: [], signals: [], flows: allFlows.map((f) => f.name) }, { testids: [], signals: [], flows: passing });
         // A gate over an empty suite has not passed — it had nothing to check. Same rule the suite
@@ -217,6 +270,13 @@ hook = false) {
             quarantined: result.quarantined,
             ...(result.downgraded.length > 0 ? { downgraded: result.downgraded } : {}),
             ...(result.deleted.length > 0 ? { deletedCoverage: result.deleted } : {}),
+            ...(result.unflowed.length > 0 ? { unflowed: result.unflowed } : {}),
+            ...(result.coverageRegressed.length > 0
+                ? { coverageRegressed: result.coverageRegressed }
+                : {}),
+            ...(result.unexecuted.length > 0 ? { unexecuted: result.unexecuted } : {}),
+            ...(coverageStale.length > 0 ? { coverageStale } : {}),
+            ...(coverageAccepted.length > 0 ? { coverageAccepted } : {}),
             coverage: flowCoverage,
         });
         // Two non-zero codes, because two callers want opposite things from the same run. CI wants any
@@ -242,6 +302,9 @@ hook = false) {
                     // A downgrade is reported per flow with its step indices; the hook names the flow.
                     downgraded: result.downgraded.map((d) => d.flow),
                     deleted: result.deleted,
+                    unflowed: result.unflowed,
+                    coverageRegressed: result.coverageRegressed.map((r) => `${r.level} ${String(r.was)}% -> ${String(r.now)}%`),
+                    unexecuted: result.unexecuted,
                 });
                 if (message !== undefined)
                     process.stderr.write(`${message}\n`);

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

@@ -27,3 +27,10 @@ export declare const missingOperand: (command: string, what: string) => ParseErr
 export declare const HEADED_FLAG = "--headed";
 export declare const PORT_FLAG = "--port";
 export declare const VERIFY_COMMAND = "verify";
+/**
+ * The predicate flag, shared for the same reason the rest of this file is: two places have to name
+ * it. The grammar reads it, and `verify` itself has to say IN PROSE which flag it could not honour
+ * when the port is not serving a daemon — a refusal that never names the flag is how this one was
+ * missed for a release.
+ */
+export declare const EXPECT_FLAG = "--expect";

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

@@ -37,3 +37,10 @@ export const missingOperand = (command, what) => ({
 export const HEADED_FLAG = '--headed';
 export const PORT_FLAG = '--port';
 export const VERIFY_COMMAND = 'verify';
+/**
+ * The predicate flag, shared for the same reason the rest of this file is: two places have to name
+ * it. The grammar reads it, and `verify` itself has to say IN PROSE which flag it could not honour
+ * when the port is not serving a daemon — a refusal that never names the flag is how this one was
+ * missed for a release.
+ */
+export const EXPECT_FLAG = '--expect';

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

@@ -7,6 +7,8 @@ export type VerifySuffix = {
     storageState?: string;
     sessionId?: string;
     expect?: unknown;
+    /** A path to read the predicate from, when `--expect-file` was used instead of `--expect`. */
+    expectFile?: string;
     explore?: boolean;
     persona?: string;
     select?: string[];
@@ -14,9 +16,4 @@ export type VerifySuffix = {
     kind: 'error';
     message: string;
 };
-/**
- * Parse `verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>]
- * [--session-id <id>]`. The first non-flag token is the preview URL. `defaultPort` is already
- * env + `.reticle.json` + 4400.
- */
 export declare function parseVerifySuffix(args: string[], defaultPort: number): VerifySuffix;

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] [--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>']            (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>] [--accept-coverage] [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 setup mcp                                    (register the MCP server with your agents; the installer's registration half)\n  reticle capsules                                     (list the saved fail-to-pass bug capsules in .reticle/capsules)\n  reticle hunt <dir>                                   (aggregate a directory of crawl reports into one false-green rate)\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;
@@ -148,6 +149,7 @@ export type CliResult = {
     storageState?: string;
     sessionId?: string;
     expect?: unknown;
+    expectFile?: string;
     explore?: boolean;
     persona?: string;
     select?: string[];
@@ -165,6 +167,11 @@ export type CliResult = {
     files: string[];
     since?: string;
     hook?: boolean;
+    acceptCoverage?: boolean;
+} | {
+    kind: 'report';
+    session?: string;
+    hook: boolean;
 } | {
     kind: 'watch';
     url?: string;
@@ -184,6 +191,12 @@ export type CliResult = {
     kind: 'error';
     message: string;
 };
+/**
+ * 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 declare function dialsTheDaemon(parsed: CliResult): boolean;
 /**
  * @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 —