@reticlehq/server 2.12.0 → 2.13.1

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

@@ -31,21 +31,21 @@ 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;
 }>;

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/cli/cli-doctor.js

@@ -17,7 +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
@@ -41,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`);
@@ -92,6 +107,22 @@ 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.
@@ -102,7 +133,6 @@ export async function handleDoctor(port) {
     // 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-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> [--port N] [--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;
@@ -114,6 +127,7 @@ export type CliResult = {
     port: number;
     timeoutMs?: number;
     storageState?: string;
+    sessionId?: string;
 } | {
     kind: 'affected';
     files: string[];

package/dist/cli/cli-parse.js

@@ -17,8 +17,21 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
  */
 export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticle <command>\` once the bin is on your PATH)
 
-  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]  (wire Reticle into the project in this directory)
+  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+                [--flow "<what to drive>"] [--env KEY=VALUE]... [--files-only]  (wire Reticle into the project in this directory)
                 --app picks WHICH app in a monorepo, when several are found
+                --flow names the journey worth proving, in your own words. Only you know
+                which one matters, and naming it is the difference between a drive that
+                finishes and one that spends its budget looking for something to do
+                --env is what the app needs to reach a usable state: the key from
+                .env.example, the mock backend, the variable that skips an auth wall.
+                Repeatable, and a value may contain spaces and equals signs
+                --files-only writes the files and stops, which is what init did before it
+                learned to boot the app and prove the install works
+                --license writes the key to .env and keeps .env out of git
+                --json puts the result on stdout, so an agent reads one object
+                --no-drive / --no-open / --no-agents / --url / --timeout / --drive-model
+                are the runtime dials: CI, a headless box, or an app you already run
                 --no-mcp skips MORE than the server registration: also the agent rule files
                 (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
                 only make sense once the tools are reachable.
@@ -29,7 +42,7 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle status [--port N]
   reticle doctor [--port N]                            (one command to diagnose setup: Chromium, daemon, port)
   reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)
-  reticle verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)
+  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)
   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)
@@ -45,13 +58,15 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
   reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]
                                                        (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
 
-Cloud (link this project to Reticle Cloud; runs/flows recorded on the dashboard):
-  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)
+Cloud (link this project to Reticle; runs/flows recorded on the dashboard):
+  reticle login [--url <u>] [--email <e>] [--code <c>] [--org <n>]
+                                                       (browser device flow by default; --email mails a code)
+  reticle logout [--url <u>]                           (sign out of ONE host; others stay signed in)
   reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)
   reticle whoami                                        (who am I signed in as, and is this repo attached?)
   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 push | sync [--watch]                        (one sync cycle: send the difference, collect decisions)
   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
@@ -134,6 +149,8 @@ const KNOWN_COMMANDS = new Set([
     'config',
     'push',
     'runs',
+    'issues',
+    'memory',
     'regression',
     'share',
     'doctor',
@@ -159,12 +176,64 @@ const DRY_RUN_FLAG = '--dry-run';
 const YES_FLAG = '--yes';
 const NO_MCP_FLAG = '--no-mcp';
 const APP_FLAG = '--app';
+/**
+ * What only the caller can know, and what it may switch off.
+ *
+ * `--flow`, `--env` and `--app` are an AGENT's answers: which journey proves the thing the user
+ * cares about, what the app needs to reach a usable state, and which app in a monorepo. None is
+ * inferable from the repository alone, and a run without them either guesses or stops.
+ *
+ * `--files-only` is the escape hatch for a caller that wants what init used to do and nothing more.
+ */
+const FLOW_FLAG = '--flow';
+const ENV_FLAG = '--env';
+const FILES_ONLY_FLAG = '--files-only';
+/**
+ * Write `captureNetworkBodies: true` into the app's config. OFF unless asked (#705).
+ *
+ * Body capture is what makes a 2xx write's OUTCOME readable rather than just its transport, so it
+ * is worth having — but a body is the one part of a request that routinely carries personal data,
+ * and `init` runs unattended. Whoever passes this has decided; nothing decides it for them.
+ */
+const CAPTURE_BODIES_FLAG = '--capture-bodies';
+/**
+ * The rest of the runtime surface.
+ *
+ * `--json` is not a convenience: SKILL.md tells an agent to read the result and act on `agentTodo`,
+ * and reading one object is one turn where interpreting a report is several. The three opt-outs are
+ * what a machine without a browser, or a caller already running their app, actually needs.
+ */
+const JSON_FLAG = '--json';
+const NO_DRIVE_FLAG = '--no-drive';
+const NO_OPEN_FLAG = '--no-open';
+const NO_AGENTS_FLAG = '--no-agents';
+/**
+ * Restart the calling client so IT gets the tools.
+ *
+ * The flag was accepted by the prototype and not by `init`, so passing it printed the whole usage
+ * text. `init` decides what a restart should do — including refusing an id with no transcript, which
+ * is the case that looks exactly like success — and prints it; performing the restart is the
+ * caller's, because opening a terminal is not something a one-shot command should do behind a flag.
+ */
+const RELAUNCH_FLAG = '--relaunch';
+const URL_FLAG = '--url';
+const TIMEOUT_FLAG_INIT = '--timeout';
+const DRIVE_MODEL_FLAG = '--drive-model';
+/**
+ * The key, written to .env by the command rather than by hand.
+ *
+ * The instructions used to ask an agent for three steps: append to .env, check .gitignore, confirm.
+ * All three are deterministic, and the second is the one that costs something when skipped, because
+ * a key committed to git is leaked and stays leaked after the file is removed.
+ */
+const LICENSE_FLAG = '--license';
 const NO_INSTALL_FLAG = '--no-install';
 export const HTTP_FLAG = '--http';
 export const HTTP_PORT_FLAG = '--http-port';
 export const HTTP_TOKEN_FLAG = '--http-token';
 const TIMEOUT_FLAG = '--timeout';
 const STORAGE_STATE_FLAG = '--storage-state';
+const SESSION_ID_FLAG = '--session-id';
 const unknownArgument = (arg) => ({
     kind: 'error',
     message: `unknown argument '${arg}'`,
@@ -181,6 +250,10 @@ const missingOperand = (command, what) => ({
     kind: 'error',
     message: `${command} needs ${what}`,
 });
+const requiresHttp = (flag) => ({
+    kind: 'error',
+    message: `${flag} requires ${HTTP_FLAG} — it configures the verify endpoint ${HTTP_FLAG} starts`,
+});
 const unknownCommand = (command) => ({
     kind: 'error',
     message: `unknown command '${command}'`,
@@ -245,6 +318,13 @@ function parseServeFlags(args, defaultPort, _defaultHeadless) {
         }
         i++;
     }
+    // Without `--http` these flags configure an endpoint nothing starts, and they were accepted and
+    // silently ignored — worse than being rejected, because the whole reason to pass them is to be
+    // honoured (#687).
+    if (!http && httpPort !== undefined)
+        return requiresHttp(HTTP_PORT_FLAG);
+    if (!http && httpToken !== undefined)
+        return requiresHttp(HTTP_TOKEN_FLAG);
     return {
         kind: 'ok',
         port,
@@ -290,14 +370,16 @@ function parseDriveSuffix(args, port, defaultHeadless) {
     return { kind: 'ok', port, driveUrl, headless };
 }
 /**
- * Parse `verify <url> [--port N] [--headed] [--timeout N] [--storage-state <file>]`. The first
- * non-flag token is the preview URL. `defaultPort` is already env + `.reticle.json` + 4400.
+ * 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.
  */
 function parseVerifySuffix(args, defaultPort) {
     let headless = true;
     let url;
     let timeoutMs;
     let storageState;
+    let sessionId;
     let port = defaultPort;
     let i = 0;
     while (i < args.length) {
@@ -334,6 +416,13 @@ function parseVerifySuffix(args, defaultPort) {
                 return missingValue(STORAGE_STATE_FLAG);
             storageState = v;
         }
+        else if (arg === SESSION_ID_FLAG) {
+            i++;
+            const v = args[i];
+            if (v === undefined)
+                return missingValue(SESSION_ID_FLAG);
+            sessionId = v;
+        }
         else if (arg.startsWith('--')) {
             return unknownArgument(arg);
         }
@@ -354,6 +443,7 @@ function parseVerifySuffix(args, defaultPort) {
         port,
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
         ...(storageState !== undefined ? { storageState } : {}),
+        ...(sessionId !== undefined ? { sessionId } : {}),
     };
 }
 function parseInitFlags(args) {
@@ -362,6 +452,20 @@ function parseInitFlags(args) {
     let dryRun = false;
     let install = true;
     let app;
+    let flow;
+    // Repeatable: one variable per flag, so a value containing spaces or `=` needs no quoting rules.
+    const env = [];
+    let filesOnly = false;
+    let captureBodies = false;
+    let json = false;
+    let drive = true;
+    let open = true;
+    let relaunch = false;
+    let agents = true;
+    let url;
+    let timeoutSeconds;
+    let driveModel;
+    let licenseKey;
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
@@ -386,6 +490,72 @@ function parseInitFlags(args) {
                 return missingValue(APP_FLAG);
             app = value;
         }
+        else if (arg === FLOW_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(FLOW_FLAG);
+            flow = value;
+        }
+        else if (arg === ENV_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(ENV_FLAG);
+            env.push(value);
+        }
+        else if (arg === FILES_ONLY_FLAG) {
+            filesOnly = true;
+        }
+        else if (arg === CAPTURE_BODIES_FLAG) {
+            captureBodies = true;
+        }
+        else if (arg === JSON_FLAG) {
+            json = true;
+        }
+        else if (arg === NO_DRIVE_FLAG) {
+            drive = false;
+        }
+        else if (arg === NO_OPEN_FLAG) {
+            open = false;
+        }
+        else if (arg === RELAUNCH_FLAG) {
+            relaunch = true;
+        }
+        else if (arg === NO_AGENTS_FLAG) {
+            agents = false;
+        }
+        else if (arg === URL_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(URL_FLAG);
+            url = value;
+        }
+        else if (arg === LICENSE_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(LICENSE_FLAG);
+            licenseKey = value;
+        }
+        else if (arg === DRIVE_MODEL_FLAG) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(DRIVE_MODEL_FLAG);
+            driveModel = value;
+        }
+        else if (arg === TIMEOUT_FLAG_INIT) {
+            i++;
+            const value = args[i];
+            if (value === undefined)
+                return missingValue(TIMEOUT_FLAG_INIT);
+            const seconds = parseInt(value, 10);
+            if (isNaN(seconds))
+                return notANumber(TIMEOUT_FLAG_INIT, value);
+            timeoutSeconds = seconds;
+        }
         else if (arg === NO_MCP_FLAG) {
             mcp = false;
         }
@@ -403,7 +573,27 @@ function parseInitFlags(args) {
         }
         i++;
     }
-    return { kind: 'ok', port, mcp, dryRun, install, app };
+    return {
+        kind: 'ok',
+        port,
+        mcp,
+        dryRun,
+        install,
+        app,
+        flow,
+        env,
+        filesOnly,
+        captureBodies,
+        json,
+        drive,
+        open,
+        relaunch,
+        agents,
+        url,
+        timeoutSeconds,
+        driveModel,
+        licenseKey,
+    };
 }
 /** Pure CLI arg parser — exported for unit tests. argv = process.argv.slice(2). */
 const SINCE_FLAG = '--since';
@@ -471,6 +661,19 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 dryRun: r.dryRun,
                 install: r.install,
                 app: r.app,
+                flow: r.flow,
+                env: r.env,
+                filesOnly: r.filesOnly,
+                captureBodies: r.captureBodies,
+                json: r.json,
+                drive: r.drive,
+                open: r.open,
+                relaunch: r.relaunch,
+                agents: r.agents,
+                url: r.url,
+                timeoutSeconds: r.timeoutSeconds,
+                driveModel: r.driveModel,
+                licenseKey: r.licenseKey,
             };
         }
         case SERVE_COMMAND: {
@@ -574,6 +777,7 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
                 port: r.port,
                 ...(r.timeoutMs !== undefined ? { timeoutMs: r.timeoutMs } : {}),
                 ...(r.storageState !== undefined ? { storageState: r.storageState } : {}),
+                ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
             };
         }
         case CAPSULES_COMMAND:

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

@@ -62,6 +62,7 @@ export declare function handleVerify(parsed: {
     headless: boolean;
     timeoutMs?: number;
     storageState?: string;
+    sessionId?: string;
     /** Bridge port — parseCliArgs already resolves --port / RETICLE_PORT / .reticle.json into this. */
     port: number;
 }): void;