@reticlehq/server 2.11.0 → 2.13.0

package/dist/bridge/protocol-skew.js

@@ -0,0 +1,45 @@
+/**
+ * Which side of a protocol mismatch is the stale one, and therefore what to tell the user to do.
+ *
+ * The close reason was a single fixed string — "upgrade @reticlehq/browser" — sent whichever way the
+ * versions disagreed. That is correct only when the page is BEHIND the daemon, and the common real
+ * skew runs the other way: the app's package.json pulls a current `@reticlehq/browser` while the
+ * daemon is an older `@reticlehq/server` that npx resolved from cache. Observed in this repo's own
+ * logs as `got: 2, expected: 1` — a browser two steps ahead, told to upgrade itself.
+ *
+ * Advice that names the wrong component is worse than none: the user upgrades the thing that was
+ * already current, sees no change, and concludes the tool is broken.
+ *
+ * Kept short on purpose — a WebSocket close reason is capped at 123 BYTES, and a reason that
+ * overflows is dropped by the socket layer, which would take the diagnosis with it.
+ *
+ * NOT a duplicate of `version/version-skew.ts`, and the two should not be merged. That module
+ * describes peers which connected SUCCESSFULLY and then disagree about behaviour, so it has both
+ * versions and a wire-contract fingerprint to reason from and a whole sentence to say it in. This
+ * one runs where the hello was rejected outright: the connection never forms, a single integer is
+ * all that is known, and the answer has to fit in a close frame. The remedies are worded to match
+ * that module's, because a user who hits both should not be told two different things.
+ */
+/** The page is older than the daemon: its SDK cannot speak the protocol the daemon expects. */
+export const BROWSER_IS_OLDER = 'protocol mismatch — upgrade @reticlehq/browser in this app';
+/** The daemon is older than the page. Usually an npx cache serving a stale @reticlehq/server. */
+export const DAEMON_IS_OLDER = 'protocol mismatch — the daemon is older; run `reticle stop`, then retry';
+/** The versions disagree but not in a direction we can read. */
+export const SKEW_UNKNOWN = 'protocol version mismatch — @reticlehq/browser and server disagree';
+/** The cap a WebSocket close reason must fit inside, in bytes. */
+export const CLOSE_REASON_MAX_BYTES = 123;
+/**
+ * Name the stale component, given what the page announced and what this daemon speaks.
+ *
+ * `got` is the page's protocol version, `expected` is the daemon's. A `got` we could not read at
+ * all falls back to naming both, which is vague but never actively misleading.
+ */
+export const protocolSkewReason = (got, expected) => {
+    if (null === got || !Number.isFinite(got))
+        return SKEW_UNKNOWN;
+    if (got < expected)
+        return BROWSER_IS_OLDER;
+    if (got > expected)
+        return DAEMON_IS_OLDER;
+    return SKEW_UNKNOWN;
+};

package/dist/capsule/capsule-store.d.ts

@@ -16,7 +16,7 @@ import type { FileSystemPort } from '../project/fs-port.js';
  * in the schema literal, and in act-capsule's writer — with the named one used by nobody.
  */
 export declare const CAPSULE_VERSION = 1;
-export declare const CapsuleSchema: z.ZodObject<{
+declare const CapsuleSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     id: z.ZodString;
     /** The flow the failure happened in, when it came from one (a bare assert has no flow). */
@@ -31,21 +31,21 @@ export declare const CapsuleSchema: z.ZodObject<{
     /** Minimal steps to reproduce (prefix-trimmed). */
     steps: z.ZodArray<z.ZodType<FlowStep, z.ZodTypeDef, FlowStep>, "many">;
 }, "strip", z.ZodTypeAny, {
+    id: string;
+    version: 1;
     expected: string;
     origin: string;
-    version: 1;
-    id: string;
-    observed: string;
     steps: FlowStep[];
+    observed: string;
     createdAt: number;
     flow?: string | undefined;
 }, {
+    id: string;
+    version: 1;
     expected: string;
     origin: string;
-    version: 1;
-    id: string;
-    observed: string;
     steps: FlowStep[];
+    observed: string;
     createdAt: number;
     flow?: string | undefined;
 }>;
@@ -68,3 +68,4 @@ export declare class CapsuleStore {
 export declare function capsuleId(now: number, label: string): string;
 /** The minimal reproduction: the steps up to and including the one that failed (prefix trim). */
 export declare function minimalSteps(steps: readonly FlowStep[], failedIndex: number): FlowStep[];
+export {};

package/dist/capsule/capsule-store.js

@@ -17,7 +17,7 @@ import { reticleDirPaths } from '../project/reticle-dir.js';
  * in the schema literal, and in act-capsule's writer — with the named one used by nobody.
  */
 export const CAPSULE_VERSION = 1;
-export const CapsuleSchema = z.object({
+const CapsuleSchema = z.object({
     version: z.literal(CAPSULE_VERSION),
     id: z.string(),
     /** The flow the failure happened in, when it came from one (a bare assert has no flow). */

package/dist/capsule/causal-summary.d.ts

@@ -4,7 +4,7 @@ import { type ReticleEvent } from '@reticlehq/core';
  * app did in the act's window, as counts + a headline, not a raw event dump. Diffs come from the
  * storage/state events; attribution from. Pure composition over the attributed event window.
  */
-export interface StateDiff {
+interface StateDiff {
     path: string;
     from: unknown;
     to: unknown;
@@ -20,7 +20,7 @@ export interface StateDiff {
      */
     atMs: number;
 }
-export interface StorageDiff {
+interface StorageDiff {
     key: string;
     from?: unknown;
     to?: unknown;

package/dist/capsule/causal-summary.js

@@ -1,4 +1,5 @@
 import { EventType, PerfMetric, isDevToolingUrl } from '@reticlehq/core';
+import { routePathOf } from '../events/predicate-route.js';
 /**
  * THE INVARIANT: every field of this summary has a bounded size that does not depend on how much the
  * app did. A verdict travels in the same payload as its evidence, so an unbounded evidence field is
@@ -119,8 +120,12 @@ export function causalSummary(events, context = {}) {
                 break;
             }
             case EventType.ROUTE_CHANGE:
-                if ('string' === typeof data['pathname'])
-                    route = data['pathname'];
+                // The ROUTER's path. Reporting the document pathname left `route: "/"` on every action of a
+                // hash-routed app — the same reading that made a route predicate unsatisfiable there, and an
+                // agent reasoning off this field would conclude the route never changed. See routePathOf.
+                if ('string' === typeof data['pathname']) {
+                    route = routePathOf(data['pathname'], 'string' === typeof data['hash'] ? data['hash'] : '');
+                }
                 break;
             case EventType.SIGNAL:
                 pushUnique(signals, data['name']);

package/dist/chromium-launch-options.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The launch options every Reticle-driven Chromium gets, in one place.
+ *
+ * A pooled browser serves several lease contexts while only one page is ever the visible one, and a
+ * driven page can sit in a window the host does not treat as visible. For everyone else Chromium
+ * throttles timers, suspends rAF, and deprioritizes the renderer, which is exactly the state a
+ * session reports as `throttled: true`: WebSocket- and timer-driven DOM updates land seconds late,
+ * asserts time out on content that appears right after the timeout, with no refetch, because the
+ * app was fine and the browser was parked. The three switches below are the documented opt-outs,
+ * shared by both launch sites so the pooled path (`playwright-launcher`) and the drive path
+ * (`real-input`) cannot drift apart.
+ */
+/**
+ * Chromium switches that keep background pages running at full speed. Named individually rather
+ * than as one free string per call site, so a typo is a test failure instead of a silently ignored
+ * argument.
+ */
+export declare const CHROMIUM_ANTI_THROTTLING_ARGS: readonly ["--disable-background-timer-throttling", "--disable-backgrounding-occluded-windows", "--disable-renderer-backgrounding"];
+/** The options object handed to `chromium.launch` at both launch sites. */
+export interface ChromiumLaunchOptions {
+    headless: boolean;
+    args: string[];
+}
+/**
+ * Build the launch options for a headless or headed Chromium. Pure; returns a fresh mutable array
+ * each call so no caller can mutate the constant behind everyone else's back.
+ */
+export declare function chromiumLaunchOptions(headless: boolean): ChromiumLaunchOptions;

package/dist/chromium-launch-options.js

@@ -0,0 +1,29 @@
+/**
+ * The launch options every Reticle-driven Chromium gets, in one place.
+ *
+ * A pooled browser serves several lease contexts while only one page is ever the visible one, and a
+ * driven page can sit in a window the host does not treat as visible. For everyone else Chromium
+ * throttles timers, suspends rAF, and deprioritizes the renderer, which is exactly the state a
+ * session reports as `throttled: true`: WebSocket- and timer-driven DOM updates land seconds late,
+ * asserts time out on content that appears right after the timeout, with no refetch, because the
+ * app was fine and the browser was parked. The three switches below are the documented opt-outs,
+ * shared by both launch sites so the pooled path (`playwright-launcher`) and the drive path
+ * (`real-input`) cannot drift apart.
+ */
+/**
+ * Chromium switches that keep background pages running at full speed. Named individually rather
+ * than as one free string per call site, so a typo is a test failure instead of a silently ignored
+ * argument.
+ */
+export const CHROMIUM_ANTI_THROTTLING_ARGS = [
+    '--disable-background-timer-throttling',
+    '--disable-backgrounding-occluded-windows',
+    '--disable-renderer-backgrounding',
+];
+/**
+ * Build the launch options for a headless or headed Chromium. Pure; returns a fresh mutable array
+ * each call so no caller can mutate the constant behind everyone else's back.
+ */
+export function chromiumLaunchOptions(headless) {
+    return { headless, args: [...CHROMIUM_ANTI_THROTTLING_ARGS] };
+}

package/dist/cli/cli-doctor.js

@@ -17,6 +17,10 @@ import { diagnoseDesktop, isDesktopProject } from '../init/desktop-doctor.js';
 import { diagnoseWebCsp } from '../init/csp-doctor.js';
 import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectId, readProjectPort, } from './cli-port.js';
 import { DoctorRow, doctorRow } from './doctor-rows.js';
+import { attachState, describeAttachState } from '../mcp/attach-memory.js';
+import { findOccupiedSiblings, siblingListenerNote } from './sibling-ports.js';
+import { daemonsServingProjectElsewhere, resolveDaemonForProject, splitBrainNote, wrongDaemonNote, } from '../daemon/daemon-resolve.js';
+import { isAlive } from '../daemon/daemon.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
@@ -40,6 +44,18 @@ function asIdentity(payload) {
         ...(contract === undefined ? {} : { contract }),
     };
 }
+/**
+ * One project, two daemons — asked from whichever end this command is standing on.
+ *
+ * Shares the rule with `reticle status` rather than restating it: the empty daemon can see that the
+ * app connected somewhere else, the daemon holding the app can only see that this project owns
+ * another one, and a second copy of either half would be a second opinion waiting to disagree.
+ */
+function splitBrainLine(port, projectId) {
+    const home = reticleStateHome();
+    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)));
+    return elsewhere ?? wrongDaemonNote(port, resolveDaemonForProject(projectId, home, isAlive));
+}
 export async function handleDoctor(port) {
     const line = (s) => {
         process.stdout.write(`${s}\n`);
@@ -91,10 +107,32 @@ export async function handleDoctor(port) {
     const mismatch = diagnosePortMismatch(port, projectPort);
     if (mismatch !== undefined)
         line(doctorRow(DoctorRow.PORT_CHECK, `✗ ${mismatch}`));
+    const projectId = readProjectId(process.cwd());
+    // The hop between the agent and this daemon, stated as its own row rather than inferred from the
+    // ones above it. `sessions` says the BROWSER reached the daemon; nothing said whether the AGENT
+    // did, and those two are exactly the pair a user cannot tell apart when one of them is broken.
+    const attach = attachState(reticleStateHome(), port);
+    const attachAction = describeAttachState(attach);
+    // A SPLIT outranks the attach record, and this is the one place it can. Both records are per PORT,
+    // so on a machine whose daemons have split in two the attach row reports "nothing has ever
+    // attached here" and sends the reader to re-register a server that is registered and running —
+    // the confident wrong answer for a link that is not missing but misaimed.
+    const split = splitBrainLine(port, projectId);
+    line(doctorRow(DoctorRow.AGENT_LINK, split !== undefined
+        ? `✗ ${split}`
+        : attachAction === undefined
+            ? "✓ an MCP client has listed and called Reticle's tools on this port"
+            : `✗ ${attachAction}`));
+    // Remaining half of #261. The SDK dialling a port we are not on is invisible as a refused inbound,
+    // but a listener on a well-known Reticle port is visible. Report the observation; do not conclude
+    // it is the daemon this app wants — somebody else's daemon looks the same from here.
+    const occupiedSiblings = await findOccupiedSiblings(port, probeDaemon);
+    const siblingNote = siblingListenerNote(port, occupiedSiblings);
+    if (siblingNote !== undefined)
+        line(doctorRow(DoctorRow.SIBLING, siblingNote));
     // The check this checklist was missing: is the APP wired, not just the tools. Everything above can
     // be green in a project that has never been through `init`, and that combination is precisely the
     // one `doctor` gets run to explain.
-    const projectId = readProjectId(process.cwd());
     line(projectWiringLine({
         projectId,
         previouslyConnected: hasProjectConnectedBefore(reticleStateHome(), port, projectId),

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

@@ -27,4 +27,6 @@ export declare function handleCapsules(): Promise<void>;
  * 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): Promise<void>;
+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>;

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

@@ -5,6 +5,8 @@
  * opens first. These five functions form one cohesive group: they all read the flow store and report on
  * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
  */
+import { GateExit } from './gate-exit.js';
+import { gateHookMessage, GATE_SKIP_ENV } from './gate-hook-message.js';
 import { readProjectId } from './cli-port.js';
 import { changedFilesSince } from '../flows/git-changed.js';
 import { join } from 'node:path';
@@ -143,7 +145,9 @@ 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).
  */
-export async function handleGate(files, since) {
+export async function handleGate(files, since, 
+/** Hook mode: prose for a human, and silence when there was simply nothing to check. */
+hook = false) {
     try {
         const fs = createNodeFileSystem();
         const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
@@ -196,11 +200,37 @@ export async function handleGate(files, since) {
             ...(result.deleted.length > 0 ? { deletedCoverage: result.deleted } : {}),
             coverage: flowCoverage,
         });
-        if (!pass)
-            process.exitCode = 1;
+        // Two non-zero codes, because two callers want opposite things from the same run. CI wants any
+        // problem to fail. A Stop hook wants to block a real regression and NOT block a project that
+        // has simply not recorded a flow yet — which is every project on its first day, and measured
+        // before this change as an exit 1 that would have blocked every stop. See GateExit.
+        if (!pass) {
+            const code = result.pass && flowCoverage.outcome !== undefined
+                ? GateExit.NOTHING_TO_CHECK
+                : GateExit.FAIL;
+            process.exitCode = code;
+            if (hook) {
+                // An honest escape hatch, because the alternative to one is not compliance — it is somebody
+                // deleting the hook, and a deleted gate protects nothing. Recorded either way.
+                if (process.env[GATE_SKIP_ENV] !== undefined) {
+                    process.stderr.write(`Reticle: gate skipped via ${GATE_SKIP_ENV}. This change is unverified.\n`);
+                    process.exitCode = GateExit.PASS;
+                    return;
+                }
+                const message = gateHookMessage(code, {
+                    uncovered: result.uncovered,
+                    quarantined: result.quarantined,
+                    // 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,
+                });
+                if (message !== undefined)
+                    process.stderr.write(`${message}\n`);
+            }
+        }
     }
     catch (error) {
         log('reticle_gate_failed', { error: error instanceof Error ? error.message : String(error) });
-        process.exitCode = 1;
+        process.exitCode = GateExit.FAIL;
     }
 }

package/dist/cli/cli-kill.d.ts

@@ -25,7 +25,7 @@ export declare const KillAction: {
     readonly REFUSE: "refuse";
 };
 export type KillAction = (typeof KillAction)[keyof typeof KillAction];
-export interface KillPlan {
+interface KillPlan {
     action: KillAction;
     /** The single pid to signal. Present only for `kill`. */
     pid?: number;
@@ -56,3 +56,4 @@ export declare function planKill(input: {
 }): KillPlan;
 /** `reticle kill` — free the port. Resolves to whether the port is now free. */
 export declare function runKill(port: number, force: boolean): Promise<boolean>;
+export {};

package/dist/cli/cli-launch.d.ts

@@ -10,6 +10,8 @@ interface StatusSession {
     throttled: boolean;
     stale: boolean;
     pendingMarks: number;
+    /** The tab is attached and answering nothing — see Session.unresponsive. Absent on an older daemon. */
+    unresponsive?: true;
 }
 /**
  * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
@@ -62,8 +64,9 @@ type OpenDecision = {
  * is run by a human whose browser this is, and yanking the page they are looking at to somewhere else
  * is a bigger surprise than being told where the tab actually is.
  */
-export declare function decideOpen(sessions: {
+export declare function decideOpen(all: {
     url: string;
+    unresponsive?: boolean;
 }[], url: string | undefined): OpenDecision;
 /** The OS command that opens a URL in the default browser, per platform. Pure — unit-tested. */
 export declare function openCommand(url: string, platform: NodeJS.Platform): {
@@ -79,4 +82,11 @@ export declare function openCommand(url: string, platform: NodeJS.Platform): {
  * port problem while nothing had ever opened.
  */
 export declare function openInBrowser(url: string, platform?: NodeJS.Platform, run?: (cmd: string, args: string[]) => Promise<string | null>): Promise<string | null>;
+/**
+ * What a finished launcher means, or null when nothing is wrong.
+ *
+ * Exported for its own tests: the headless case is the one that matters and it cannot be produced
+ * by spawning a real launcher on a developer machine.
+ */
+export declare function launcherFailure(code: number | null, signal: NodeJS.Signals | null): string | null;
 export {};

package/dist/cli/cli-launch.js

@@ -2,10 +2,11 @@ import * as http from 'node:http';
 import { NodePlatform } from '../platform.js';
 import { spawn } from 'node:child_process';
 import { isOpaqueOrigin, LOOPBACK_HOST, STATUS_PATH } from '@reticlehq/core';
-import { describeSkew, DAEMON_FIX } from '../version/version-skew.js';
+import { daemonFix, describeSkew } from '../version/version-skew.js';
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { log } from '../log.js';
+import { loopbackAgent } from '../loopback-agent.js';
 /**
  * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
  * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
@@ -33,6 +34,7 @@ export function summarizeStatus(payload) {
             throttled: true === r['throttled'],
             stale: true === r['stale'],
             pendingMarks: 'number' === typeof r['pendingMarks'] ? r['pendingMarks'] : 0,
+            ...(true === r['unresponsive'] ? { unresponsive: true } : {}),
         };
     })
         .filter((s) => s !== null);
@@ -55,11 +57,13 @@ function statusField(payload, key) {
  */
 export async function warnOnDaemonSkew(port) {
     const status = await fetchStatus(port);
+    const daemonVersion = statusField(status, 'version');
     const skew = describeSkew({
         what: 'the daemon already running on this port',
-        version: statusField(status, 'version'),
+        version: daemonVersion,
         contract: statusField(status, 'contract'),
-        fix: DAEMON_FIX,
+        // The daemon is the peer here and this process is the agent side.
+        fix: daemonFix(daemonVersion, SERVER_VERSION),
     }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
     if (skew !== undefined)
         log('reticle_daemon_skew', { port, warning: skew });
@@ -69,7 +73,15 @@ const STATUS_PROBE_TIMEOUT_MS = 1000;
 /** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
 export function fetchStatus(port) {
     return new Promise((resolve) => {
-        const req = http.get({ host: LOOPBACK_HOST, port, path: STATUS_PATH, timeout: STATUS_PROBE_TIMEOUT_MS }, (res) => {
+        const req = http.get({
+            host: LOOPBACK_HOST,
+            port,
+            path: STATUS_PATH,
+            timeout: STATUS_PROBE_TIMEOUT_MS,
+            // Shares the proxy's keep-alive agent: the proxy calls this on every reconnect, and a socket
+            // per probe is the same churn the POST leg was fixed for.
+            agent: loopbackAgent,
+        }, (res) => {
             let body = '';
             res.setEncoding('utf8');
             res.on('data', (chunk) => (body += chunk));
@@ -117,7 +129,11 @@ function sameOrigin(a, b) {
  * is run by a human whose browser this is, and yanking the page they are looking at to somewhere else
  * is a bigger surprise than being told where the tab actually is.
  */
-export function decideOpen(sessions, url) {
+export function decideOpen(all, url) {
+    // A tab that has stopped answering is not a tab you can be handed. `open` is the command a caller
+    // reaches for to RECOVER, and reusing the wedged one left no way out short of killing the daemon:
+    // ending the session only flips a flag on the record, it does not make the page answer.
+    const sessions = all.filter((s) => true !== s.unresponsive);
     if (url === undefined) {
         const first = sessions[0];
         return first !== undefined ? { action: 'reuse', url: first.url } : { action: 'need-url' };
@@ -159,16 +175,49 @@ export async function openInBrowser(url, platform = process.platform, run = defa
     const { cmd, args } = openCommand(url, platform);
     return run(cmd, args);
 }
-/** null when the launcher started; the failure message when it could not be run at all. */
+/**
+ * What a finished launcher means, or null when nothing is wrong.
+ *
+ * Exported for its own tests: the headless case is the one that matters and it cannot be produced
+ * by spawning a real launcher on a developer machine.
+ */
+export function launcherFailure(code, signal) {
+    if (null !== signal)
+        return `the browser launcher was killed by ${signal}`;
+    // null code with no signal: it never reported an outcome in the window we waited. Some desktop
+    // launchers stay attached rather than handing off, and inventing a failure there would be worse
+    // than the silence — it would send someone to fix a browser that opened.
+    if (null === code || 0 === code)
+        return null;
+    return (`the browser launcher exited ${String(code)} — on a machine with no browser (CI, a container, ` +
+        'an SSH session, WSL with no host browser) it starts fine and then has nothing to open');
+}
+/** How long to wait for the launcher to hand off before assuming it did. */
+const LAUNCHER_EXIT_MS = 2_000;
+/** null when the launcher opened something; the failure message when it did not. */
 function defaultRun(cmd, args) {
     return new Promise((resolve) => {
         const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
         // An unhandled 'error' on a ChildProcess throws — and ENOENT on the launcher is exactly the case
         // this function exists to report, so it must be listened for either way.
-        child.on('error', (err) => resolve(err.message));
-        child.on('spawn', () => {
+        child.on('error', (err) => finish(err.message));
+        // The EXIT, not the spawn. Answering "did the command begin" reported success on every headless
+        // box, where the launcher begins perfectly well and then finds nothing to open — see
+        // launcherFailure. Every launcher we use hands off and exits immediately, so this costs nothing
+        // on the path where it works.
+        child.on('exit', (code, signal) => finish(launcherFailure(code, signal)));
+        // ...and a launcher that stays attached must not hold up the install.
+        const timer = setTimeout(() => {
             child.unref();
-            resolve(null);
-        });
+            finish(null);
+        }, LAUNCHER_EXIT_MS);
+        timer.unref?.();
     });
 }

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

@@ -13,7 +13,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>]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\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> [--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, 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 Cloud; 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: 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                [--flow \"<what to drive>\"] [--env KEY=VALUE]... [--files-only]  (wire Reticle into the project in this directory)\n                --app picks WHICH app in a monorepo, when several are found\n                --flow names the journey worth proving, in your own words. Only you know\n                which one matters, and naming it is the difference between a drive that\n                finishes and one that spends its budget looking for something to do\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                --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-drive / --no-open / --no-agents / --url / --timeout / --drive-model\n                are the runtime dials: CI, a 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  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.";
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";
@@ -47,6 +47,19 @@ export type CliResult = {
     dryRun: boolean;
     install: boolean;
     app: string | undefined;
+    flow: string | undefined;
+    env: string[];
+    filesOnly: boolean;
+    captureBodies: boolean;
+    json: boolean;
+    drive: boolean;
+    relaunch: boolean;
+    open: boolean;
+    agents: boolean;
+    url: string | undefined;
+    timeoutSeconds: number | undefined;
+    driveModel: string | undefined;
+    licenseKey: string | undefined;
 } | {
     kind: 'serve';
     port: number;
@@ -111,8 +124,10 @@ export type CliResult = {
     kind: 'verify';
     url: string;
     headless: boolean;
+    port: number;
     timeoutMs?: number;
     storageState?: string;
+    sessionId?: string;
 } | {
     kind: 'affected';
     files: string[];
@@ -126,6 +141,7 @@ export type CliResult = {
     kind: 'gate';
     files: string[];
     since?: string;
+    hook?: boolean;
 } | {
     kind: 'watch';
     url?: string;