@reticlehq/server 2.3.0 → 2.5.0

package/dist/capsule/predicate-to-links.js

@@ -1,3 +1,4 @@
+import { ConsequenceKind, PredicateKind } from '@reticlehq/core';
 /**
  * Convert a mustHold predicate into the ordered ExpectedLinks the divergence capsule walks. Only the
  * consequence kinds (signal/net/state) become links — a presence check (element/text) can't diverge in a
@@ -5,24 +6,26 @@
  */
 export function predicateToExpectedLinks(predicate) {
     switch (predicate.kind) {
-        case 'signal':
-            return predicate.name === undefined ? [] : [{ kind: 'signal', name: predicate.name }];
-        case 'net':
+        case PredicateKind.SIGNAL:
+            return predicate.name === undefined
+                ? []
+                : [{ kind: ConsequenceKind.SIGNAL, name: predicate.name }];
+        case PredicateKind.NET:
             return predicate.urlContains === undefined
                 ? []
                 : [
                     {
-                        kind: 'net',
+                        kind: ConsequenceKind.NET,
                         urlContains: predicate.urlContains,
                         ...(predicate.status === undefined ? {} : { status: predicate.status }),
                     },
                 ];
-        case 'state': {
+        case PredicateKind.STATE: {
             const name = predicate.store ?? predicate.path;
-            return [{ kind: 'state', name }];
+            return [{ kind: ConsequenceKind.STATE, name }];
         }
-        case 'allOf':
-        case 'anyOf':
+        case PredicateKind.ALL_OF:
+        case PredicateKind.ANY_OF:
             return predicate.predicates.flatMap(predicateToExpectedLinks);
         default:
             return [];

package/dist/{cli-doctor.js → cli/cli-doctor.js}

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { readPid, isAlive } from './daemon.js';
-import { diagnoseDesktop, isDesktopProject } from './init/desktop-doctor.js';
+import { ReticleEnv } from '@reticlehq/core';
+import { readPid, isAlive, reticleStateHome } from '../daemon/daemon.js';
+import { diagnoseDesktop, isDesktopProject } from '../init/desktop-doctor.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
@@ -31,6 +32,12 @@ export async function handleDoctor(port) {
         line(`  daemon       ✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`);
     }
     line(`  bridge port  ${port}  (your app must dial THIS port — not your dev-server port)`);
+    // Where to LOOK when something is wrong. The daemon has always written a structured log here and
+    // nothing ever said so, so the first move in every investigation was reading source instead of
+    // reading the log. `RETICLE_TRACE=1` turns the same stream into a per-stage trace — see
+    // docs/debugging.md.
+    line(`  daemon log   ${join(reticleStateHome(), `daemon-${String(port)}.log`)}`);
+    line(`  tracing      ${ReticleEnv.TRACE}=1 on the daemon for per-stage timings in that log`);
     // Desktop setup RCA. Every one of these fails SILENTLY — a Tauri app with the default CSP runs
     // perfectly and never connects; an Electron app without the preload line reports zero network
     // activity forever, which reads as "makes no backend calls" rather than "you are blind to them".

package/dist/{cli-flow-commands.d.ts → cli/cli-flow-commands.d.ts}

@@ -5,8 +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 { type FileSystemPort } from './project/fs-port.js';
-import { type NamedFlow } from './flows/flow-sources.js';
+import { type FileSystemPort } from '../project/fs-port.js';
+import { type NamedFlow } from '../flows/flow-sources.js';
 /** Load the {name, steps} of every saved flow for the active project. */
 /** Explicit files plus, when --since is given, the git-changed files since that ref. */
 export declare function resolveChangedFiles(files: string[], since: string | undefined): Promise<string[]>;

package/dist/{cli-flow-commands.js → cli/cli-flow-commands.js}

@@ -6,23 +6,23 @@
  * verification state, and none of them touch daemon lifecycle, which is what the rest of cli.ts does.
  */
 import { readProjectId } from './cli-port.js';
-import { changedFilesSince } from './flows/git-changed.js';
+import { changedFilesSince } from '../flows/git-changed.js';
 import { join } from 'node:path';
 import { ReticleDir, RunFlowStatus } from '@reticlehq/core';
-import { FlowStore } from './flows/flows.js';
-import { RunStore } from './runs/run-store.js';
-import { createNodeFileSystem } from './project/fs-port.js';
-import { affectedSavedFlows } from './flows/flow-sources.js';
-import { gateDecision } from './flows/gate.js';
-import { FlakeStore } from './flows/flake-store.js';
-import { formatBuddyStatus } from './flows/buddy-status.js';
-import { CapsuleStore } from './capsule/capsule-store.js';
-import { AssertionTiersStore } from './flows/assertion-tiers-store.js';
-import { detectDowngrades } from './flows/assertion-integrity.js';
-import { computeCoverage } from './flows/coverage.js';
-import { createWatchBatcher } from './flows/watch-batcher.js';
+import { FlowStore } from '../flows/flows.js';
+import { RunStore } from '../runs/run-store.js';
+import { createNodeFileSystem } from '../project/fs-port.js';
+import { affectedSavedFlows } from '../flows/flow-sources.js';
+import { gateDecision } from '../flows/gate.js';
+import { FlakeStore } from '../flows/flake-store.js';
+import { formatBuddyStatus } from '../flows/buddy-status.js';
+import { CapsuleStore } from '../capsule/capsule-store.js';
+import { AssertionTiersStore } from '../flows/assertion-tiers-store.js';
+import { detectDowngrades } from '../flows/assertion-integrity.js';
+import { computeCoverage } from '../flows/coverage.js';
+import { createWatchBatcher } from '../flows/watch-batcher.js';
 import { watch } from 'node:fs';
-import { log } from './log.js';
+import { log } from '../log.js';
 /** Load the {name, steps} of every saved flow for the active project. */
 /** Explicit files plus, when --since is given, the git-changed files since that ref. */
 export async function resolveChangedFiles(files, since) {
@@ -107,7 +107,7 @@ export function handleWatch() {
         .then((flows) => emitBuddyStatus(fs, reticleRoot, flows, []))
         .catch(() => undefined);
     watch(process.cwd(), { recursive: true }, (_event, filename) => {
-        if (typeof filename === 'string' && WATCHED_EXTENSIONS.test(filename))
+        if ('string' === typeof filename && WATCHED_EXTENSIONS.test(filename))
             batcher.onChange(filename);
     });
 }

package/dist/{cli-launch.d.ts → cli/cli-launch.d.ts}

@@ -20,12 +20,26 @@ export declare function summarizeStatus(payload: unknown): {
     sessionCount: number;
     sessions: StatusSession[];
 };
+/**
+ * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
+ *
+ * Attaching to whatever owns the port is the point of a daemon — but it means an upgrade does not
+ * take effect until that daemon dies, and nothing used to say so. Killing it here would take out
+ * another agent's session on a version bump, which is worse than a loud line.
+ */
+export declare function warnOnDaemonSkew(port: number): Promise<void>;
 /** GET the daemon's /status JSON. Resolves to the parsed body, or undefined on any failure. */
 export declare function fetchStatus(port: number): Promise<unknown>;
 /** What `reticle open` should do: reuse an already-connected tab, open a new one, or ask for a url. */
 type OpenDecision = {
     action: 'reuse';
     url: string;
+}
+/** A tab on that origin exists, but on another page — kept, and NOT reported as done. */
+ | {
+    action: 'left-as-is';
+    url: string;
+    requested: string;
 } | {
     action: 'open';
     url: string;
@@ -36,8 +50,16 @@ type OpenDecision = {
  * Decide what `reticle open [url]` does, given the currently-connected tabs. Pure.
  * - no url + a tab connected → reuse it (the app is already open; don't spawn a duplicate).
  * - no url + nothing connected → ask for one.
- * - url + a tab already on that origin → reuse it (idempotent — re-running never piles up tabs).
+ * - url + a tab already AT that url → reuse it (idempotent — re-running never piles up tabs).
+ * - url + a tab on that origin but another page → keep it, and say so (`left-as-is`).
  * - url + no matching tab → open it.
+ *
+ * The origin match is why re-running this never piles up tabs, and it stays. What changed is the
+ * REPORT: matching by origin meant `reticle open http://localhost:3000/settings` answered `reusing`
+ * for a tab sitting on `http://localhost:3000/` and exited 0, so the caller read a success for a page
+ * that was never opened. Navigating the tab instead was the other option and is worse: `reticle open`
+ * 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: {
     url: string;
@@ -47,6 +69,13 @@ export declare function openCommand(url: string, platform: NodeJS.Platform): {
     cmd: string;
     args: string[];
 };
-/** Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic. */
-export declare function openInBrowser(url: string, platform?: NodeJS.Platform, run?: (cmd: string, args: string[]) => void): void;
+/**
+ * Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic.
+ *
+ * Resolves to whether the launch COMMAND started — not to whether a page appeared. It used to return
+ * nothing at all and the caller printed `{"opened": url}` unconditionally, so a launcher that failed
+ * outright still reported success. Reported from the field as twenty minutes lost chasing a phantom
+ * 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>;
 export {};

package/dist/cli/cli-launch.js

@@ -0,0 +1,171 @@
+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 { CONTRACT_FINGERPRINT } from '@reticlehq/core';
+import { SERVER_VERSION } from '../version/server-version.js';
+import { log } from '../log.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
+ * degrades to "running, 0 sessions" instead of throwing.
+ */
+export function summarizeStatus(payload) {
+    if (typeof payload !== 'object' || null === payload)
+        return { sessionCount: 0, sessions: [] };
+    const obj = payload;
+    const raw = Array.isArray(obj['sessions']) ? obj['sessions'] : [];
+    const sessions = raw
+        .map((s) => {
+        if (typeof s !== 'object' || null === s)
+            return null;
+        const r = s;
+        const sessionId = 'string' === typeof r['sessionId'] ? r['sessionId'] : '';
+        if ('' === sessionId)
+            return null;
+        return {
+            sessionId,
+            url: 'string' === typeof r['url'] ? r['url'] : '',
+            throttled: true === r['throttled'],
+            stale: true === r['stale'],
+            pendingMarks: 'number' === typeof r['pendingMarks'] ? r['pendingMarks'] : 0,
+        };
+    })
+        .filter((s) => s !== null);
+    const sessionCount = 'number' === typeof obj['sessionCount'] ? obj['sessionCount'] : sessions.length;
+    return { sessionCount, sessions };
+}
+/** A string field off the /status body, or undefined on a daemon too old to report it. */
+function statusField(payload, key) {
+    if (typeof payload !== 'object' || null === payload)
+        return undefined;
+    const value = payload[key];
+    return 'string' === typeof value && value.length > 0 ? value : undefined;
+}
+/**
+ * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
+ *
+ * Attaching to whatever owns the port is the point of a daemon — but it means an upgrade does not
+ * take effect until that daemon dies, and nothing used to say so. Killing it here would take out
+ * another agent's session on a version bump, which is worse than a loud line.
+ */
+export async function warnOnDaemonSkew(port) {
+    const status = await fetchStatus(port);
+    const skew = describeSkew({
+        what: 'the daemon already running on this port',
+        version: statusField(status, 'version'),
+        contract: statusField(status, 'contract'),
+        fix: DAEMON_FIX,
+    }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
+    if (skew !== undefined)
+        log('reticle_daemon_skew', { port, warning: skew });
+}
+/** How long the daemon /status probe waits before giving up — a local loopback call is near-instant. */
+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) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => (body += chunk));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch {
+                    resolve(undefined);
+                }
+            });
+        });
+        req.on('error', () => resolve(undefined));
+        req.on('timeout', () => {
+            req.destroy();
+            resolve(undefined);
+        });
+    });
+}
+function sameOrigin(a, b) {
+    try {
+        const origin = new URL(a).origin;
+        // Two opaque origins (desktop webviews, file:// docs) BOTH stringify to "null", so comparing them
+        // would call every desktop app the same app and reuse the wrong session. Never match on opaque.
+        if (isOpaqueOrigin(origin))
+            return false;
+        return origin === new URL(b).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide what `reticle open [url]` does, given the currently-connected tabs. Pure.
+ * - no url + a tab connected → reuse it (the app is already open; don't spawn a duplicate).
+ * - no url + nothing connected → ask for one.
+ * - url + a tab already AT that url → reuse it (idempotent — re-running never piles up tabs).
+ * - url + a tab on that origin but another page → keep it, and say so (`left-as-is`).
+ * - url + no matching tab → open it.
+ *
+ * The origin match is why re-running this never piles up tabs, and it stays. What changed is the
+ * REPORT: matching by origin meant `reticle open http://localhost:3000/settings` answered `reusing`
+ * for a tab sitting on `http://localhost:3000/` and exited 0, so the caller read a success for a page
+ * that was never opened. Navigating the tab instead was the other option and is worse: `reticle open`
+ * 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) {
+    if (url === undefined) {
+        const first = sessions[0];
+        return first !== undefined ? { action: 'reuse', url: first.url } : { action: 'need-url' };
+    }
+    const exact = sessions.find((s) => s.url === url);
+    if (exact !== undefined)
+        return { action: 'reuse', url: exact.url };
+    const onOrigin = sessions.find((s) => sameOrigin(s.url, url));
+    return onOrigin !== undefined
+        ? { action: 'left-as-is', url: onOrigin.url, requested: url }
+        : { action: 'open', url };
+}
+/**
+ * Percent-encode the cmd.exe metacharacters that `start` re-parses so a URL can't break out into
+ * command execution on Windows (`?next=x&calc` → command chaining). `%` is left untouched so an
+ * already-encoded URL isn't double-encoded; the browser decodes the escapes back to the real URL.
+ */
+function encodeForWindowsStart(url) {
+    return url.replace(/[&^|<>()"'!]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/** The OS command that opens a URL in the default browser, per platform. Pure — unit-tested. */
+export function openCommand(url, platform) {
+    if (NodePlatform.MACOS === platform)
+        return { cmd: 'open', args: [url] };
+    if (NodePlatform.WINDOWS === platform) {
+        return { cmd: 'cmd', args: ['/c', 'start', '', encodeForWindowsStart(url)] };
+    }
+    return { cmd: 'xdg-open', args: [url] };
+}
+/**
+ * Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic.
+ *
+ * Resolves to whether the launch COMMAND started — not to whether a page appeared. It used to return
+ * nothing at all and the caller printed `{"opened": url}` unconditionally, so a launcher that failed
+ * outright still reported success. Reported from the field as twenty minutes lost chasing a phantom
+ * port problem while nothing had ever opened.
+ */
+export async function openInBrowser(url, platform = process.platform, run = defaultRun) {
+    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. */
+function defaultRun(cmd, args) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+        // 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.unref();
+            resolve(null);
+        });
+    });
+}

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

@@ -0,0 +1,143 @@
+/**
+ * Pure CLI argument parsing — the command/flag grammar, the CliResult union, and parseCliArgs.
+ * Split out of cli.ts (which keeps the side-effecting handlers + dispatch) to stay under the
+ * 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] [--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]\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.";
+/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
+export declare const RATING_FLAG = "--rating";
+export declare const BUG_FLAG = "--bug";
+/** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
+export declare const TelemetryAction: {
+    readonly STATUS: "status";
+    readonly ENABLE: "enable";
+    readonly DISABLE: "disable";
+};
+export type TelemetryAction = (typeof TelemetryAction)[keyof typeof TelemetryAction];
+export declare const DAEMON_INNER_COMMAND = "_daemon";
+/**
+ * Every subcommand a person can type, as one closed vocabulary. Telemetry reports which one ran, and
+ * this is what keeps that property low-cardinality and non-identifying: an argument we do not
+ * recognize reports as `unknown` rather than being echoed, so a typo — which may be a path, a URL, or
+ * a flow name — can never reach the wire just because someone misspelled `status`.
+ *
+ * Lives here rather than in the telemetry module because this is where the command names are already
+ * defined; a second list somewhere else would drift the first time a command is added.
+ */
+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";
+export declare const PORT_FLAG = "--port";
+export declare const DRIVE_FLAG = "--drive";
+export declare const HTTP_FLAG = "--http";
+export declare const HTTP_PORT_FLAG = "--http-port";
+export declare const HTTP_TOKEN_FLAG = "--http-token";
+export type CliResult = {
+    kind: 'init';
+    port: number | undefined;
+    mcp: boolean;
+    dryRun: boolean;
+    install: boolean;
+    app: string | undefined;
+} | {
+    kind: 'serve';
+    port: number;
+    driveUrl?: string;
+    headless: boolean;
+    http: boolean;
+    httpPort?: number;
+    httpToken?: string;
+} | {
+    kind: 'stop';
+    port: number;
+    quiet: boolean;
+} | {
+    kind: 'status';
+    port: number;
+} | {
+    kind: 'license';
+} | {
+    kind: 'telemetry';
+    action: TelemetryAction;
+} | {
+    kind: 'feedback';
+    text: string;
+    rating?: number;
+    bug: boolean;
+} | {
+    kind: 'identify';
+    context?: string;
+    company?: string;
+    email?: string;
+    forget: boolean;
+} | {
+    kind: 'version';
+} | {
+    kind: 'help';
+} | {
+    kind: 'doctor';
+    port: number;
+} | {
+    kind: 'open';
+    port: number;
+    url?: string;
+} | {
+    kind: '_daemon';
+    port: number;
+    driveUrl?: string;
+    headless: boolean;
+    http: boolean;
+    httpPort?: number;
+    httpToken?: string;
+} | {
+    kind: 'drive';
+    port: number;
+    driveUrl: string;
+    headless: boolean;
+} | {
+    kind: 'verify';
+    url: string;
+    headless: boolean;
+    timeoutMs?: number;
+    storageState?: string;
+} | {
+    kind: 'affected';
+    files: string[];
+    since?: string;
+} | {
+    kind: 'hunt';
+    dir: string;
+} | {
+    kind: 'capsules';
+} | {
+    kind: 'gate';
+    files: string[];
+    since?: string;
+} | {
+    kind: 'watch';
+    url?: string;
+} | {
+    kind: 'update';
+} | {
+    kind: 'rollback';
+} | {
+    kind: 'mcp';
+    port: number;
+    driveUrl?: string;
+    headless: boolean;
+    http: boolean;
+    httpPort?: number;
+    httpToken?: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * @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;