@reticlehq/server 2.3.0 → 2.4.0

package/dist/bridge.js

@@ -1,9 +1,27 @@
 import * as http from 'node:http';
 import { WebSocketServer } from 'ws';
-import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOOPBACK_HOST, MessageKind, ReticleEnv, RETICLE_PROTOCOL_VERSION, TRANSPORT_LIMITS, isLoopbackHostname, isOpaqueOrigin, OPAQUE_ORIGIN, isHighValueEvent, RATE_CAP_HIGH_VALUE_RESERVE_RATIO, } from '@reticlehq/core';
+import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOOPBACK_HOST, MessageKind, ReticleEnv, RETICLE_PROTOCOL_VERSION, TRANSPORT_LIMITS, isLocalPage, isLoopbackHostname, isOpaqueOrigin, OPAQUE_ORIGIN, isHighValueEvent, RATE_CAP_HIGH_VALUE_RESERVE_RATIO, } from '@reticlehq/core';
 import { Session, SessionManager } from './session/session.js';
 import { tokensMatch } from './token-auth.js';
 import { log } from './log.js';
+/**
+ * Take the mutable half of a session's identity from a repeat HELLO.
+ *
+ * Lives here rather than on Session because this is where the protocol decision is made — the caller
+ * has already established that the hello belongs to this same session — and because these fields are
+ * the session's public surface, read by the tools on every listing.
+ *
+ * `hasCapabilities` is the one that matters: it is announced in the hello, which the SDK sends at
+ * connect(), while capabilities are registered AFTER connect by design (registerStore needs a live
+ * SDK to subscribe through). Without this refresh, an app that declared its entire testable surface
+ * reported `hasCapabilities: false` forever.
+ */
+function refreshIdentity(session, hello) {
+    session.url = hello.url;
+    session.title = hello.title;
+    session.adapters = hello.adapters;
+    session.hasCapabilities = hello.hasCapabilities ?? false;
+}
 /** WS close codes + reasons the bridge sends to the SDK (1008 = policy violation, 1013 = try again later). */
 const WS_CLOSE = {
     TOO_MANY_HANDSHAKES: [1013, 'too many pending handshakes'],
@@ -266,7 +284,16 @@ export class Bridge {
             }
             if (parsed.kind === MessageKind.HELLO) {
                 if (session !== undefined) {
-                    socket.close(...WS_CLOSE.HELLO_DUPLICATE);
+                    // A repeat hello on the SAME socket for the SAME session is an identity refresh, not a
+                    // violation: the SDK re-announces when the app registers capabilities, which happens after
+                    // connect by design. Closing the socket on it made `hasCapabilities` permanently false for
+                    // every app that declared anything. A hello bearing a DIFFERENT session id is still a
+                    // protocol violation — that is the case this guard exists for.
+                    if (parsed.sessionId !== session.id) {
+                        socket.close(...WS_CLOSE.HELLO_DUPLICATE);
+                        return;
+                    }
+                    refreshIdentity(session, parsed);
                     return;
                 }
                 if (this.#token !== undefined && !tokensMatch(this.#token, parsed.token)) {
@@ -339,7 +366,20 @@ export class Bridge {
         // Without this branch `new URL` throws INSIDE the WS upgrade handler, crashing the process.
         if (isOpaqueOrigin(normalized))
             return this.#token !== undefined;
-        return isLoopbackHostname(new URL(normalized).hostname);
+        // `isLocalPage`, not `isLoopbackHostname` — the SAME rule the SDK applies on the page side.
+        //
+        // They had drifted, and the drift made a whole platform unreachable. Tauri v2 uses an opaque
+        // `tauri://localhost` on macOS/Linux, but on WINDOWS the webview needs a real http origin and
+        // Tauri serves `http://tauri.localhost`. `isLocalPage` was taught that hostname; this check was
+        // not. So a Windows Tauri app passed its own gate, dialed the bridge, and every handshake came
+        // back 403 — Reticle could not connect to a Tauri app on Windows at all, which is precisely the
+        // platform the release notes admitted had never been executed.
+        //
+        // No weaker than before: `.localhost` is reserved for loopback by RFC 6761, so the name cannot
+        // resolve to a remote host, and this is the argument core already made when it accepted the same
+        // hostname for the page.
+        const url = new URL(normalized);
+        return isLocalPage(url.protocol, url.hostname);
     }
     #parse(text) {
         let json;

package/dist/bridge.test-harness.d.ts

@@ -37,6 +37,11 @@ export declare class FakeBrowser {
     }[];
     constructor(port: number, sessionId: string, hasCapabilities?: boolean);
     open(): Promise<void>;
+    /** Re-send the HELLO on the live socket, the way the SDK does when capabilities register late. */
+    reannounce(overrides?: {
+        sessionId?: string;
+        hasCapabilities?: boolean;
+    }): void;
     emit(type: string, data: Record<string, unknown>, ref?: string): void;
     close(): void;
 }

package/dist/bridge.test-harness.js

@@ -59,6 +59,18 @@ export class FakeBrowser {
             });
         });
     }
+    /** Re-send the HELLO on the live socket, the way the SDK does when capabilities register late. */
+    reannounce(overrides = {}) {
+        this.#send({
+            kind: MessageKind.HELLO,
+            protocolVersion: 1,
+            sessionId: overrides.sessionId ?? this.sessionId,
+            url: 'http://localhost:3000/checkout',
+            title: 'Checkout',
+            adapters: [],
+            hasCapabilities: overrides.hasCapabilities ?? this.hasCapabilities,
+        });
+    }
     emit(type, data, ref) {
         this.#send({
             kind: MessageKind.EVENT,

package/dist/cli-parse.d.ts

@@ -4,7 +4,7 @@
  * file-size cap and keep the parser pure + unit-testable. Re-exported from cli.ts so existing
  * imports are unchanged.
  */
-export declare const CLI_USAGE = "usage:\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)\n  reticle serve [--port N] [--drive <url>] [--headed] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]\n  reticle status [--port N]\n  reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port \u2014 one command)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=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> [--headed]                       (foreground mode \u2014 for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headed]  (MCP stdio proxy \u2014 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 \u2014 status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't \u2014 prints exactly what it sends)\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 Cloud \u2014 runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\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                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)";
+export declare const CLI_USAGE = "usage:\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]\n  reticle status [--port N]\n  reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port \u2014 one command)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=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 \u2014 for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy \u2014 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 \u2014 status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't \u2014 prints exactly what it sends)\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 Cloud \u2014 runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\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                                          (send local run artifacts to the dashboard)\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 \u2014 batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
 export declare const COMPANY_FLAG = "--company";
 export declare const EMAIL_FLAG = "--email";
 export declare const CONTEXT_FLAG = "--context";
@@ -33,6 +33,12 @@ export declare const UNKNOWN_COMMAND = "unknown";
 /** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
 export declare function knownCommand(arg: string | undefined): string;
 export declare const HEADED_FLAG = "--headed";
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+export declare const HEADLESS_FLAG = "--headless";
 export declare const PORT_FLAG = "--port";
 export declare const DRIVE_FLAG = "--drive";
 export declare const HTTP_FLAG = "--http";
@@ -137,4 +143,10 @@ export type CliResult = {
     kind: 'error';
     message: string;
 };
-export declare function parseCliArgs(argv: string[], defaultPort: number): CliResult;
+/**
+ * @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 —
+ *   `cli.ts` decides it from `CI`. The product default is FALSE: showing the run is what makes it
+ *   trustworthy, and asking people to opt into seeing their own app was backwards.
+ */
+export declare function parseCliArgs(argv: string[], defaultPort: number, defaultHeadless?: boolean): CliResult;

package/dist/cli-parse.js

@@ -6,7 +6,7 @@
  */
 export const CLI_USAGE = `usage:
   reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)
-  reticle serve [--port N] [--drive <url>] [--headed] [--http] [--http-port N] [--http-token T]
+  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]
   reticle stop  [--port N] [--quiet]
   reticle status [--port N]
   reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port — one command)
@@ -15,8 +15,8 @@ export const CLI_USAGE = `usage:
   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 watch [url]                                  (on save, report which saved flows must re-verify)
-  reticle drive <url> [--headed]                       (foreground mode — for debugging)
-  reticle mcp   [--port N] [--drive <url>] [--headed]  (MCP stdio proxy — auto-starts daemon if needed)
+  reticle drive <url> [--headless]                     (foreground mode — for debugging)
+  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy — auto-starts daemon if needed)
   reticle update                                       (install the latest server version and restart)
   reticle rollback                                     (restore the previous server version and restart)
   reticle license                                      (show enterprise license status: active | eval | missing)
@@ -32,7 +32,10 @@ Cloud (link this project to Reticle Cloud — runs/flows recorded on the dashboa
   reticle project <ls|create <name>>                   (list or create cloud projects)
   reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
   reticle push                                          (send local run artifacts to the dashboard)
-  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)`;
+  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)
+
+'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay
+and the spec runner — batch work). --headed opts any of them in, --headless hides drive, CI hides it.`;
 const INIT_COMMAND = 'init';
 const SERVE_COMMAND = 'serve';
 const STOP_COMMAND = 'stop';
@@ -120,6 +123,12 @@ export function knownCommand(arg) {
     return KNOWN_COMMANDS.has(arg) ? arg : UNKNOWN_COMMAND;
 }
 export const HEADED_FLAG = '--headed';
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+export const HEADLESS_FLAG = '--headless';
 export const PORT_FLAG = '--port';
 export const DRIVE_FLAG = '--drive';
 const QUIET_FLAG = '--quiet';
@@ -132,7 +141,13 @@ export const HTTP_PORT_FLAG = '--http-port';
 export const HTTP_TOKEN_FLAG = '--http-token';
 const TIMEOUT_FLAG = '--timeout';
 const STORAGE_STATE_FLAG = '--storage-state';
-function parseServeFlags(args, defaultPort) {
+/**
+ * `serve` / `mcp` / `_daemon` own the browser POOL, which backs automated work — leased contexts for
+ * parallel agents, flow replay, the spec runner. Those are batch: nobody is watching, and launching
+ * them headed changed timing enough to break four e2e specs. The headed default belongs to the
+ * INTERACTIVE command (`drive`), where a human asked to see the run. `--headed` still opts in here.
+ */
+function parseServeFlags(args, defaultPort, _defaultHeadless) {
     let port = defaultPort;
     let driveUrl;
     let headless = true;
@@ -161,6 +176,9 @@ function parseServeFlags(args, defaultPort) {
         else if (arg === HEADED_FLAG) {
             headless = false;
         }
+        else if (arg === HEADLESS_FLAG) {
+            headless = true;
+        }
         else if (arg === HTTP_FLAG) {
             http = true;
         }
@@ -205,13 +223,16 @@ function parsePortFlag(args, defaultPort) {
     const parsed = parseInt(n, 10);
     return isNaN(parsed) ? defaultPort : parsed;
 }
-function parseDriveSuffix(args, port) {
-    let headless = true;
+function parseDriveSuffix(args, port, defaultHeadless) {
+    let headless = defaultHeadless;
     let driveUrl;
     for (const arg of args) {
         if (arg === HEADED_FLAG) {
             headless = false;
         }
+        else if (arg === HEADLESS_FLAG) {
+            headless = true;
+        }
         else if (arg.startsWith('--')) {
             return { kind: 'error', message: CLI_USAGE };
         }
@@ -336,7 +357,14 @@ function parseTargetArgs(rest) {
     }
     return since === undefined ? { files } : { files, since };
 }
-export function parseCliArgs(argv, defaultPort) {
+/**
+ * @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 —
+ *   `cli.ts` decides it from `CI`. The product default is FALSE: showing the run is what makes it
+ *   trustworthy, and asking people to opt into seeing their own app was backwards.
+ */
+export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
+    // Bare `reticle` is `serve` — a pool-owning command, so headless like the rest of that family.
     if (argv.length === 0)
         return { kind: 'serve', port: defaultPort, headless: true, http: false };
     const [cmd, ...rest] = argv;
@@ -356,7 +384,7 @@ export function parseCliArgs(argv, defaultPort) {
             return { kind: 'init', port: r.port, mcp: r.mcp, dryRun: r.dryRun, install: r.install };
         }
         case SERVE_COMMAND: {
-            const r = parseServeFlags(rest, defaultPort);
+            const r = parseServeFlags(rest, defaultPort, defaultHeadless);
             if (r.kind === 'error')
                 return r;
             return {
@@ -436,13 +464,13 @@ export function parseCliArgs(argv, defaultPort) {
             return url !== undefined ? { kind: 'open', port, url } : { kind: 'open', port };
         }
         case DRIVE_COMMAND: {
-            const r = parseDriveSuffix(rest, defaultPort);
+            const r = parseDriveSuffix(rest, defaultPort, defaultHeadless);
             if (r.kind === 'error')
                 return r;
             return { kind: 'drive', port: r.port, driveUrl: r.driveUrl, headless: r.headless };
         }
         case DAEMON_INNER_COMMAND: {
-            const r = parseServeFlags(rest, defaultPort);
+            const r = parseServeFlags(rest, defaultPort, defaultHeadless);
             if (r.kind === 'error')
                 return r;
             return {
@@ -503,7 +531,7 @@ export function parseCliArgs(argv, defaultPort) {
         case ROLLBACK_COMMAND:
             return { kind: 'rollback' };
         case MCP_COMMAND: {
-            const r = parseServeFlags(rest, defaultPort);
+            const r = parseServeFlags(rest, defaultPort, defaultHeadless);
             if (r.kind === 'error')
                 return r;
             return {

package/dist/cli-port.d.ts

@@ -7,6 +7,9 @@
  * 3..reticle.json "port" field in the cwd ← per-project isolation
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
+export declare function isLikelyDevServerPort(port: number): boolean;
+/** The warning printed when a project pins the bridge to something that looks like its dev server. */
+export declare function devServerPortWarning(port: number): string;
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.

package/dist/cli-port.js

@@ -8,6 +8,27 @@
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
 import { readFileSync } from 'node:fs';
+/**
+ * Ports that belong to a DEV SERVER, not to Reticle's bridge. Next defaults to 3000, Vite to 5173,
+ * Astro to 4321, and so on.
+ *
+ * `.reticle.json`'s `port` is the bridge — the daemon ↔ SDK channel, default 4400 — and it has
+ * nothing to do with the port the app is served on. Setting it to the dev-server port makes the
+ * daemon try to bind the port the app already holds; what the user sees is either a bind failure or
+ * a daemon that never connects, neither of which mentions the actual mistake. The old setup skill
+ * asked "what port does your dev server run on?" a few lines before showing this field, which is how
+ * the confusion got manufactured in the first place.
+ */
+const DEV_SERVER_PORTS = new Set([
+    3000, 3001, 4200, 4321, 5000, 5173, 5174, 8000, 8080, 8100, 9000,
+]);
+export function isLikelyDevServerPort(port) {
+    return DEV_SERVER_PORTS.has(port);
+}
+/** The warning printed when a project pins the bridge to something that looks like its dev server. */
+export function devServerPortWarning(port) {
+    return `[reticle] .reticle.json sets "port": ${port}, which is a common DEV-SERVER port. That field is the Reticle BRIDGE port (default 4400), not the port your app is served on — they must be different, or the daemon fights your dev server for it. Remove "port" unless you are running several apps at once.`;
+}
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.

package/dist/cli.js

@@ -24,7 +24,7 @@ import { runInit } from './init/run.js';
 import { handleDoctor } from './cli-doctor.js';
 import { buildNodeIo } from './init/node-io.js';
 import { describeLicense } from './license/license.js';
-import { readProjectPort, readProjectId } from './cli-port.js';
+import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId } from './cli-port.js';
 import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, parseCliArgs, CLI_USAGE, } from './cli-parse.js';
 import { handleFeedback, handleIdentify, handleTelemetry } from './telemetry/feedback-cli.js';
 import { installDaemonTelemetry } from './telemetry/daemon-telemetry.js';
@@ -413,8 +413,15 @@ function main() {
     const portEnv = process.env[ReticleEnv.PORT];
     const envPort = portEnv !== undefined ? parseInt(portEnv, 10) : undefined;
     const projectPort = readProjectPort(process.cwd());
+    // Say so rather than letting the daemon fight the dev server for the port and fail with an
+    // EADDRINUSE that mentions neither file nor cause.
+    if (projectPort !== undefined && isLikelyDevServerPort(projectPort)) {
+        process.stderr.write(`${devServerPortWarning(projectPort)}\n`);
+    }
     const defaultPort = envPort ?? projectPort ?? RETICLE_DEFAULT_PORT;
-    const parsed = parseCliArgs(argv, defaultPort);
+    // Headed by default; hidden only where there is no display to be headed on. A run nobody can see
+    // is a run nobody trusts, and every "did it actually do anything?" cost a human round-trip.
+    const parsed = parseCliArgs(argv, defaultPort, process.env['CI'] !== undefined);
     switch (parsed.kind) {
         case 'error':
             log('reticle_usage_error', { message: parsed.message });

package/dist/flows/decision.d.ts

@@ -1,11 +1,5 @@
 import { type FlowFile, type FlowReplayResult, type ReplayDecision, type SuiteVerdict } from '@reticlehq/core';
 export declare function buildDecision(result: FlowReplayResult, flow?: FlowFile): ReplayDecision;
-/**
- * Aggregate per-flow replays into one suite verdict — the autonomous loop's consolidated answer
- * after a build: did anything break, and what's the prioritized fix list. Pure: pass the already
- * decision-annotated replay results + their flows. Passing flows are counted; only failures carry
- * detail (token-cheap), each with the actionable decision so the agent fixes without re-querying.
- */
 export declare function buildSuiteVerdict(runs: ReadonlyArray<{
     replay: FlowReplayResult;
     flow?: FlowFile;

package/dist/flows/decision.js

@@ -1,5 +1,5 @@
 import { AnchorKind, ReplayStatus, } from '@reticlehq/core';
-import { classifyFlowAssertions } from './flow-classify.js';
+import { classifyFlowAssertions, FlowAssertionGrade } from './flow-classify.js';
 import { SUCCESS_STEP_TOOL } from './flow-success.js';
 /**
  * Turn a replay result into the autonomy DECISION envelope — the judgement a human reviewer used to
@@ -92,12 +92,39 @@ function suiteVerdictOf(status) {
  * decision-annotated replay results + their flows. Passing flows are counted; only failures carry
  * detail (token-cheap), each with the actionable decision so the agent fixes without re-querying.
  */
+/**
+ * Why a green replay still verified nothing, or undefined when it genuinely did.
+ *
+ * A flow with no steps, or one that asserts no observable consequence, replays green no matter what
+ * the app does — the grader already knows this at save time and says so. Counting it as `passed`
+ * turned that warning into "all 1 flow pass", which is a false green in the exact feature sold as
+ * the regression suite. Classified only when the flow file is available; never guessed.
+ */
+function unverifiableReason(flow) {
+    if (flow === undefined)
+        return undefined;
+    if (flow.steps.length === 0) {
+        return 'the flow has no steps — it replays green whatever the app does. Record it again, or add steps with reticle_annotate.';
+    }
+    const c = classifyFlowAssertions(flow);
+    if (c.grade !== FlowAssertionGrade.ASSERTION_FREE)
+        return undefined;
+    return (c.warning ??
+        'the flow asserts no observable consequence, so it passes even when the feature is broken.');
+}
 export function buildSuiteVerdict(runs) {
     const failures = [];
+    const unverifiable = [];
     let passed = 0;
     for (const { replay, flow } of runs) {
         if (replay.status === ReplayStatus.OK) {
-            passed += 1;
+            const reason = unverifiableReason(flow);
+            // A green that cannot go red is not a pass. Counted apart, so `passed` stays a count of things
+            // actually verified rather than of replays that merely completed.
+            if (reason !== undefined)
+                unverifiable.push({ flow: replay.name, reason });
+            else
+                passed += 1;
             continue;
         }
         const decision = replay.decision ?? buildDecision(replay, flow);
@@ -111,9 +138,23 @@ export function buildSuiteVerdict(runs) {
     }
     const total = runs.length;
     const failed = failures.length;
-    const status = failed === 0 ? 'pass' : 'fail';
+    // A real failure outranks an unverifiable flow: a broken flow is worse news than an empty one.
+    const status = failed > 0 ? 'fail' : unverifiable.length > 0 ? 'unverifiable' : 'pass';
+    const cannotFail = unverifiable.length === 0
+        ? ''
+        : ` — ${String(unverifiable.length)} verified nothing (${unverifiable.map((u) => u.flow).join(', ')})`;
     const summary = failed === 0
-        ? `all ${total} flow${total === 1 ? '' : 's'} pass`
-        : `${passed}/${total} flows pass — ${failed} need attention: ${failures.map((f) => f.flow).join(', ')}`;
-    return { status, total, passed, failed, summary, failures };
+        ? unverifiable.length === 0
+            ? `all ${total} flow${total === 1 ? '' : 's'} pass`
+            : `${String(passed)}/${String(total)} flows verified${cannotFail}`
+        : `${passed}/${total} flows pass — ${failed} need attention: ${failures.map((f) => f.flow).join(', ')}${cannotFail}`;
+    return {
+        status,
+        total,
+        passed,
+        failed,
+        summary,
+        failures,
+        ...(unverifiable.length > 0 ? { unverifiable } : {}),
+    };
 }

package/dist/flows/flow-tools.js

@@ -345,12 +345,18 @@ export const FLOW_TOOLS = [
                         await lease.release().catch(() => undefined);
                     }
                 });
-                return buildSuiteVerdict(outcomes.map((o, i) => ({
-                    replay: o.ok && o.value !== undefined
-                        ? o.value
-                        : leaseFailureReplay(requested[i] ?? '', o.error),
-                })));
+                const parallelRuns = await Promise.all(outcomes.map(async (o, i) => {
+                    const name = requested[i] ?? '';
+                    const replay = o.ok && o.value !== undefined ? o.value : leaseFailureReplay(name, o.error);
+                    const loaded = await deps.flows.load(name, projectId).catch(() => null);
+                    const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
+                    return flow === undefined ? { replay } : { replay, flow };
+                }));
+                return buildSuiteVerdict(parallelRuns);
             }
+            // The flow FILE travels with each replay so the verdict can tell a green that verified
+            // something from a green that could never have gone red. Without it the suite reported "all 1
+            // flow pass" for a flow with no steps at all.
             const runs = [];
             const timed = [];
             // The flake ledger the CLI gate already keeps — see FlakeStore. It was only ever written by
@@ -362,7 +368,9 @@ export const FLOW_TOOLS = [
             for (const flowName of requested) {
                 const start = deps.now();
                 const replay = await replayNamedFlow(deps, { flowName, sessionId });
-                runs.push({ replay });
+                const loaded = await deps.flows.load(flowName, projectId).catch(() => null);
+                const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
+                runs.push(flow === undefined ? { replay } : { replay, flow });
                 timed.push({ replay, durationMs: deps.now() - start });
             }
             // Accrue this run's outcomes, then report what the ledger knows. Best-effort on both halves: a

package/dist/init/capabilities.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What the app can be driven by: its `data-testid` values, and which state library holds its truth.
+ *
+ * `init` wired none of this, so every app came up with `hasCapabilities: false`, empty capabilities,
+ * and a `reticle_state` holding nothing but `__reticle_renders` — the state-truth read that SKILL.md
+ * calls the highest-value line was unavailable on every app out of the box. Measured across six.
+ *
+ * Testids are scanned rather than asked for. Stores are NAMED but not wired: detecting that an app
+ * depends on zustand is easy, knowing which module exports the store instance is not, and generating
+ * a wrong import would break the dev module that everything else now hangs off.
+ */
+/** Cap the generated list. A capabilities block is a hint for an agent, not an inventory. */
+export declare const MAX_TESTIDS = 60;
+/** Every distinct `data-testid` literal in the given sources, in first-seen order. */
+export declare function scanTestids(sources: readonly string[]): string[];
+/** The store libraries this app depends on, as ready-to-uncomment registration lines. */
+export declare function storeHints(deps: ReadonlySet<string>): string[];

package/dist/init/capabilities.js

@@ -0,0 +1,51 @@
+/**
+ * What the app can be driven by: its `data-testid` values, and which state library holds its truth.
+ *
+ * `init` wired none of this, so every app came up with `hasCapabilities: false`, empty capabilities,
+ * and a `reticle_state` holding nothing but `__reticle_renders` — the state-truth read that SKILL.md
+ * calls the highest-value line was unavailable on every app out of the box. Measured across six.
+ *
+ * Testids are scanned rather than asked for. Stores are NAMED but not wired: detecting that an app
+ * depends on zustand is easy, knowing which module exports the store instance is not, and generating
+ * a wrong import would break the dev module that everything else now hangs off.
+ */
+/** `data-testid="foo"` / `data-testid='foo'` / `data-testid={"foo"}` — the forms people actually write. */
+const TESTID_ATTR = /data-testid\s*=\s*[{]?\s*["'`]([^"'`]+)["'`]/g;
+/** Cap the generated list. A capabilities block is a hint for an agent, not an inventory. */
+export const MAX_TESTIDS = 60;
+/** Every distinct `data-testid` literal in the given sources, in first-seen order. */
+export function scanTestids(sources) {
+    const found = new Set();
+    for (const src of sources) {
+        for (const m of src.matchAll(TESTID_ATTR)) {
+            const id = m[1];
+            if (id !== undefined && id.length > 0)
+                found.add(id);
+            if (found.size >= MAX_TESTIDS)
+                return [...found];
+        }
+    }
+    return [...found];
+}
+/**
+ * State libraries the browser SDK has an adapter for, in the order we would recommend registering
+ * them. TanStack Query is first on purpose: a stale cache served as fresh fires NO network request,
+ * so the network log shows silence and the DOM shows a plausible number — the cache is the only
+ * witness, which makes it the highest-value store in the list and the least obvious one to add.
+ */
+const STORE_LIBRARIES = [
+    ['@tanstack/react-query', "registerStore('queries', tanstackQueryStore(queryClient))"],
+    ['zustand', "registerStore('app', useStore) // pass the store itself, not () => store.getState()"],
+    ['@reduxjs/toolkit', "registerStore('app', store)"],
+    ['redux', "registerStore('app', store)"],
+    ['jotai', "registerStore('app', jotaiStore(getDefaultStore(), { cart, user }))"],
+    ['valtio', "registerStore('app', valtioStore(state))"],
+    ['mobx', "registerStore('app', mobxStore(state))"],
+    ['xstate', "registerStore('machine', xstateStore(actor))"],
+    ['pinia', "registerStore('cart', piniaStore(useCartStore()))"],
+    ['svelte', "registerStore('cart', svelteStore(cartStore))"],
+];
+/** The store libraries this app depends on, as ready-to-uncomment registration lines. */
+export function storeHints(deps) {
+    return STORE_LIBRARIES.filter(([dep]) => deps.has(dep)).map(([, hint]) => hint);
+}

package/dist/init/detect.d.ts

@@ -6,6 +6,7 @@ export declare const Framework: {
     readonly NEXT: "next";
     readonly VITE: "vite";
     readonly SVELTEKIT: "sveltekit";
+    readonly ASTRO: "astro";
     readonly HTML: "html";
 };
 export type Framework = (typeof Framework)[keyof typeof Framework];
@@ -27,9 +28,31 @@ export interface DetectInput {
     configFiles: ReadonlySet<string>;
     /** Lockfile basenames present in the project root. */
     lockfiles: ReadonlySet<string>;
+    /** Marker basenames inside `node_modules` (`.modules.yaml`, `.yarn-state.yml`, …), if installed. */
+    nodeModulesMarkers?: ReadonlySet<string>;
 }
+/**
+ * The UI library the app renders with. Detection used to key on "vite is in package.json" and stop
+ * there, so a Vue or Preact app got `@reticlehq/react` installed and an all-green report with no
+ * mention that the React adapter has nothing to attach to.
+ */
+export declare const UiLibrary: {
+    readonly REACT: "react";
+    readonly PREACT: "preact";
+    readonly VUE: "vue";
+    readonly SVELTE: "svelte";
+    readonly UNKNOWN: "unknown";
+};
+export type UiLibrary = (typeof UiLibrary)[keyof typeof UiLibrary];
 export interface Detection {
     framework: Framework;
+    uiLibrary: UiLibrary;
+    /**
+     * Whether the project is TypeScript. Not cosmetic: generating a `.tsx` file into a JavaScript
+     * project makes Next auto-install TypeScript on the next `next dev`, which on Next 13 takes its
+     * require-hook down with it and the dev server never starts.
+     */
+    typescript: boolean;
     reactMajor: number | undefined;
     /** React 19 dropped _debugSource, so it needs the build-time source-map stamp. */
     needsSourceMapping: boolean;
@@ -37,6 +60,8 @@ export interface Detection {
 }
 /** Extract the leading major version from a semver range like "^19.0.0" or "19.1.1". */
 export declare function parseMajor(range: string | undefined): number | undefined;
+/** Marker basenames present inside the project's `node_modules`, if it has one. */
+export declare function packageManagerFromNodeModules(markers: ReadonlySet<string>): PackageManager | undefined;
 export declare function detect(input: DetectInput): Detection;
 interface InstallCommand {
     command: string;