@reticlehq/server 2.2.1 → 2.4.0

package/dist/cli-parse.js

@@ -6,7 +6,7 @@
  */
 export const CLI_USAGE = `usage:
   reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)
-  reticle serve [--port N] [--drive <url>] [--headed] [--http] [--http-port N] [--http-token T]
+  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]
   reticle stop  [--port N] [--quiet]
   reticle status [--port N]
   reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port — one command)
@@ -15,12 +15,15 @@ export const CLI_USAGE = `usage:
   reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
   reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)
   reticle watch [url]                                  (on save, report which saved flows must re-verify)
-  reticle drive <url> [--headed]                       (foreground mode — for debugging)
-  reticle mcp   [--port N] [--drive <url>] [--headed]  (MCP stdio proxy — auto-starts daemon if needed)
+  reticle drive <url> [--headless]                     (foreground mode — for debugging)
+  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy — auto-starts daemon if needed)
   reticle update                                       (install the latest server version and restart)
   reticle rollback                                     (restore the previous server version and restart)
   reticle license                                      (show enterprise license status: active | eval | missing)
   reticle telemetry [status|enable|disable]            (anonymous usage metrics — status shows what's sent + the policy)
+  reticle feedback [--rating 1-5] [--bug] "message"    (tell us what worked and what didn't — prints exactly what it sends)
+  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)
@@ -29,7 +32,10 @@ Cloud (link this project to Reticle Cloud — runs/flows recorded on the dashboa
   reticle project <ls|create <name>>                   (list or create cloud projects)
   reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]
   reticle push                                          (send local run artifacts to the dashboard)
-  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)`;
+  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)
+
+'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay
+and the spec runner — batch work). --headed opts any of them in, --headless hides drive, CI hides it.`;
 const INIT_COMMAND = 'init';
 const SERVE_COMMAND = 'serve';
 const STOP_COMMAND = 'stop';
@@ -38,6 +44,7 @@ const OPEN_COMMAND = 'open';
 const DRIVE_COMMAND = 'drive';
 const VERIFY_COMMAND = 'verify';
 const AFFECTED_COMMAND = 'affected';
+const HUNT_COMMAND = 'hunt';
 const CAPSULES_COMMAND = 'capsules';
 const GATE_COMMAND = 'gate';
 const WATCH_COMMAND = 'watch';
@@ -47,6 +54,15 @@ const MCP_COMMAND = 'mcp';
 const LICENSE_COMMAND = 'license';
 const VERSION_COMMAND = 'version';
 const TELEMETRY_COMMAND = 'telemetry';
+const FEEDBACK_COMMAND = 'feedback';
+const IDENTIFY_COMMAND = 'identify';
+export const COMPANY_FLAG = '--company';
+export const EMAIL_FLAG = '--email';
+export const CONTEXT_FLAG = '--context';
+export const FORGET_FLAG = '--forget';
+/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
+export const RATING_FLAG = '--rating';
+export const BUG_FLAG = '--bug';
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export const TelemetryAction = {
     STATUS: 'status',
@@ -54,7 +70,65 @@ export const TelemetryAction = {
     DISABLE: 'disable',
 };
 export 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 const UNKNOWN_COMMAND = 'unknown';
+const KNOWN_COMMANDS = new Set([
+    INIT_COMMAND,
+    SERVE_COMMAND,
+    STOP_COMMAND,
+    STATUS_COMMAND,
+    OPEN_COMMAND,
+    DRIVE_COMMAND,
+    VERIFY_COMMAND,
+    AFFECTED_COMMAND,
+    HUNT_COMMAND,
+    CAPSULES_COMMAND,
+    GATE_COMMAND,
+    WATCH_COMMAND,
+    UPDATE_COMMAND,
+    ROLLBACK_COMMAND,
+    MCP_COMMAND,
+    LICENSE_COMMAND,
+    VERSION_COMMAND,
+    TELEMETRY_COMMAND,
+    FEEDBACK_COMMAND,
+    IDENTIFY_COMMAND,
+    DAEMON_INNER_COMMAND,
+    // Cloud subcommands dispatch before the local parser but are still commands a human ran.
+    'login',
+    'logout',
+    'whoami',
+    'link',
+    'project',
+    'config',
+    'push',
+    'runs',
+    'regression',
+    'share',
+    'doctor',
+    'help',
+]);
+/** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
+export function knownCommand(arg) {
+    if (arg === undefined || arg === '')
+        return 'help';
+    return KNOWN_COMMANDS.has(arg) ? arg : UNKNOWN_COMMAND;
+}
 export const HEADED_FLAG = '--headed';
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+export const HEADLESS_FLAG = '--headless';
 export const PORT_FLAG = '--port';
 export const DRIVE_FLAG = '--drive';
 const QUIET_FLAG = '--quiet';
@@ -67,7 +141,13 @@ export const HTTP_PORT_FLAG = '--http-port';
 export const HTTP_TOKEN_FLAG = '--http-token';
 const TIMEOUT_FLAG = '--timeout';
 const STORAGE_STATE_FLAG = '--storage-state';
-function parseServeFlags(args, defaultPort) {
+/**
+ * `serve` / `mcp` / `_daemon` own the browser POOL, which backs automated work — leased contexts for
+ * parallel agents, flow replay, the spec runner. Those are batch: nobody is watching, and launching
+ * them headed changed timing enough to break four e2e specs. The headed default belongs to the
+ * INTERACTIVE command (`drive`), where a human asked to see the run. `--headed` still opts in here.
+ */
+function parseServeFlags(args, defaultPort, _defaultHeadless) {
     let port = defaultPort;
     let driveUrl;
     let headless = true;
@@ -96,6 +176,9 @@ function parseServeFlags(args, defaultPort) {
         else if (arg === HEADED_FLAG) {
             headless = false;
         }
+        else if (arg === HEADLESS_FLAG) {
+            headless = true;
+        }
         else if (arg === HTTP_FLAG) {
             http = true;
         }
@@ -140,13 +223,16 @@ function parsePortFlag(args, defaultPort) {
     const parsed = parseInt(n, 10);
     return isNaN(parsed) ? defaultPort : parsed;
 }
-function parseDriveSuffix(args, port) {
-    let headless = true;
+function parseDriveSuffix(args, port, defaultHeadless) {
+    let headless = defaultHeadless;
     let driveUrl;
     for (const arg of args) {
         if (arg === HEADED_FLAG) {
             headless = false;
         }
+        else if (arg === HEADLESS_FLAG) {
+            headless = true;
+        }
         else if (arg.startsWith('--')) {
             return { kind: 'error', message: CLI_USAGE };
         }
@@ -271,7 +357,14 @@ function parseTargetArgs(rest) {
     }
     return since === undefined ? { files } : { files, since };
 }
-export function parseCliArgs(argv, defaultPort) {
+/**
+ * @param defaultHeadless Whether a browser Reticle launches should be hidden when no flag says
+ *   otherwise. Injected rather than read from the environment here, because this module is pure —
+ *   `cli.ts` decides it from `CI`. The product default is FALSE: showing the run is what makes it
+ *   trustworthy, and asking people to opt into seeing their own app was backwards.
+ */
+export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
+    // Bare `reticle` is `serve` — a pool-owning command, so headless like the rest of that family.
     if (argv.length === 0)
         return { kind: 'serve', port: defaultPort, headless: true, http: false };
     const [cmd, ...rest] = argv;
@@ -291,7 +384,7 @@ export function parseCliArgs(argv, defaultPort) {
             return { kind: 'init', port: r.port, mcp: r.mcp, dryRun: r.dryRun, install: r.install };
         }
         case SERVE_COMMAND: {
-            const r = parseServeFlags(rest, defaultPort);
+            const r = parseServeFlags(rest, defaultPort, defaultHeadless);
             if (r.kind === 'error')
                 return r;
             return {
@@ -328,6 +421,42 @@ export function parseCliArgs(argv, defaultPort) {
             }
             return { kind: 'telemetry', action };
         }
+        case IDENTIFY_COMMAND: {
+            const flag = (name) => {
+                const at = rest.indexOf(name);
+                return at === -1 ? undefined : rest[at + 1];
+            };
+            const context = flag(CONTEXT_FLAG);
+            const company = flag(COMPANY_FLAG);
+            const email = flag(EMAIL_FLAG);
+            return {
+                kind: 'identify',
+                ...(context !== undefined ? { context } : {}),
+                ...(company !== undefined ? { company } : {}),
+                ...(email !== undefined ? { email } : {}),
+                forget: rest.includes(FORGET_FLAG),
+            };
+        }
+        case FEEDBACK_COMMAND: {
+            const ratingAt = rest.indexOf(RATING_FLAG);
+            const rating = ratingAt === -1 ? undefined : Number(rest[ratingAt + 1]);
+            if (rating !== undefined && (!Number.isInteger(rating) || rating < 1 || rating > 5)) {
+                return { kind: 'error', message: `${RATING_FLAG} takes a whole number from 1 to 5` };
+            }
+            // Everything that is not a flag or the rating's value is the message. Quoting is the user's
+            // job for shell reasons, but joining the remainder means an unquoted sentence still works.
+            const consumed = new Set(ratingAt === -1 ? [] : [ratingAt, ratingAt + 1]);
+            const text = rest
+                .filter((arg, i) => !consumed.has(i) && !arg.startsWith('--'))
+                .join(' ')
+                .trim();
+            return {
+                kind: 'feedback',
+                text,
+                ...(rating !== undefined ? { rating } : {}),
+                bug: rest.includes(BUG_FLAG),
+            };
+        }
         case OPEN_COMMAND: {
             const port = parsePortFlag(rest, defaultPort);
             // The first non-flag arg is the url (optional — omitting reuses a connected tab).
@@ -335,13 +464,13 @@ export function parseCliArgs(argv, defaultPort) {
             return url !== undefined ? { kind: 'open', port, url } : { kind: 'open', port };
         }
         case DRIVE_COMMAND: {
-            const r = parseDriveSuffix(rest, defaultPort);
+            const r = parseDriveSuffix(rest, defaultPort, defaultHeadless);
             if (r.kind === 'error')
                 return r;
             return { kind: 'drive', port: r.port, driveUrl: r.driveUrl, headless: r.headless };
         }
         case DAEMON_INNER_COMMAND: {
-            const r = parseServeFlags(rest, defaultPort);
+            const r = parseServeFlags(rest, defaultPort, defaultHeadless);
             if (r.kind === 'error')
                 return r;
             return {
@@ -368,6 +497,12 @@ export function parseCliArgs(argv, defaultPort) {
         }
         case CAPSULES_COMMAND:
             return { kind: 'capsules' };
+        case HUNT_COMMAND: {
+            const dir = rest.find((a) => !a.startsWith('-'));
+            return dir === undefined
+                ? { kind: 'error', message: 'usage: reticle hunt <dir-of-crawl-reports>' }
+                : { kind: 'hunt', dir };
+        }
         case AFFECTED_COMMAND: {
             const t = parseTargetArgs(rest);
             if (t.files.length === 0 && t.since === undefined) {
@@ -396,7 +531,7 @@ export function parseCliArgs(argv, defaultPort) {
         case ROLLBACK_COMMAND:
             return { kind: 'rollback' };
         case MCP_COMMAND: {
-            const r = parseServeFlags(rest, defaultPort);
+            const r = parseServeFlags(rest, defaultPort, defaultHeadless);
             if (r.kind === 'error')
                 return r;
             return {
@@ -413,4 +548,3 @@ export function parseCliArgs(argv, defaultPort) {
             return { kind: 'error', message: CLI_USAGE };
     }
 }
-//# sourceMappingURL=cli-parse.js.map

package/dist/cli-port.d.ts

@@ -7,6 +7,9 @@
  * 3..reticle.json "port" field in the cwd ← per-project isolation
  * 4. RETICLE_DEFAULT_PORT (4400)
  */
+export declare function isLikelyDevServerPort(port: number): boolean;
+/** The warning printed when a project pins the bridge to something that looks like its dev server. */
+export declare function devServerPortWarning(port: number): string;
 /**
  * Read the port stored in the project's .reticle.json (written by `reticle init`).
  * Returns undefined if the file is absent, unreadable, or has no valid numeric port.
@@ -29,4 +32,3 @@ export declare function readJournalEnabled(cwd: string, env: string | undefined)
  * Pass `portFlag` when the user explicitly supplied --port; pass `undefined` to fall through.
  */
 export declare function resolvePort(portFlag: number | undefined, envPort: number | undefined, projectPort: number | undefined, defaultPort: number): number;
-//# sourceMappingURL=cli-port.d.ts.map

package/dist/cli-port.js

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

package/dist/cli-verify.d.ts

@@ -45,4 +45,3 @@ export declare function handleVerify(parsed: {
     port?: number;
 }): void;
 export {};
-//# sourceMappingURL=cli-verify.d.ts.map

package/dist/cli-verify.js

@@ -34,7 +34,7 @@ const MSG_NO_SESSION = 'No app connected — Reticle drove the URL but no @retic
     '  Make sure the SDK is in the build and reticle.connect() runs on the preview page' +
     ' (for a non-localhost preview: allowNonLocalhost + a pairing token).';
 const MSG_NO_FLOWS = 'No saved flows to verify (.reticle/flows is empty) — refusing to report a pass for verifying nothing.\n' +
-    '  Flows are recorded interactively by an agent (reticle_record_start → act → reticle_flow_save via the\n' +
+    '  Flows are recorded interactively by an agent (reticle_record{action:"start"} → act → reticle_flow_save via the\n' +
     '  MCP tools), then committed to .reticle/flows/. In CI, check those files in and re-run `reticle verify`.';
 const MSG_VERIFY_PREFIX = 'verify failed: ';
 function errMessage(error) {
@@ -219,4 +219,3 @@ export function handleVerify(parsed) {
     };
     void runVerify({ url: parsed.url, timeoutMs: parsed.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS }, ports);
 }
-//# sourceMappingURL=cli-verify.js.map

package/dist/cli.d.ts

@@ -2,4 +2,3 @@
 import { parseCliArgs, CLI_USAGE } from './cli-parse.js';
 export { parseCliArgs, CLI_USAGE };
 export type { CliResult } from './cli-parse.js';
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { pathToFileURL } from 'node:url';
-import { realpathSync, existsSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { handleWatch, handleCapsules, handleGate, loadNamedFlows, resolveChangedFiles, } from './cli-flow-commands.js';
 import { RETICLE_DEFAULT_PORT, ReticleDir, ReticleEnv } from '@reticlehq/core';
+import { loadDotEnv } from './telemetry/dev-repo.js';
 import { createNodeFileSystem } from './project/fs-port.js';
 import { affectedSavedFlows } from './flows/flow-sources.js';
 import { checkForUpdate } from './update/update-checker.js';
@@ -11,7 +12,6 @@ import { applyUpdate, rollback } from './update/updater.js';
 import { start, startDaemon } from './index.js';
 import { isCloudCommand, runCloudCommand } from './cloud-cli.js';
 import { SERVER_VERSION } from './server-version.js';
-import { getTelemetry, TelemetryEventKind, describeTelemetry, setTelemetryEnabled, } from './telemetry/telemetry.js';
 import { log } from './log.js';
 import { readPid, isAlive, isRunning, removePid, spawnDaemon, discoverDaemonPort, writeDaemonRegistry, } from './daemon.js';
 import { waitForDaemon, startMcpProxy, probeDaemon } from './mcp-proxy.js';
@@ -19,11 +19,16 @@ import { installDaemonResilience } from './daemon-resilience.js';
 import { IdleShutdown, resolveIdleShutdownMs } from './idle-shutdown.js';
 import { fetchStatus, summarizeStatus, decideOpen, openInBrowser } from './cli-launch.js';
 import { handleVerify } from './cli-verify.js';
+import { summarizeHunt } from './hunt/hunt-report.js';
 import { runInit } from './init/run.js';
+import { handleDoctor } from './cli-doctor.js';
 import { buildNodeIo } from './init/node-io.js';
 import { describeLicense } from './license/license.js';
-import { readProjectPort, readProjectId } from './cli-port.js';
-import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, parseCliArgs, CLI_USAGE, TelemetryAction, } from './cli-parse.js';
+import { isLikelyDevServerPort, devServerPortWarning, readProjectPort, readProjectId } from './cli-port.js';
+import { DAEMON_INNER_COMMAND, PORT_FLAG, DRIVE_FLAG, HEADED_FLAG, HTTP_FLAG, HTTP_PORT_FLAG, HTTP_TOKEN_FLAG, parseCliArgs, CLI_USAGE, } from './cli-parse.js';
+import { handleFeedback, handleIdentify, handleTelemetry } from './telemetry/feedback-cli.js';
+import { installDaemonTelemetry } from './telemetry/daemon-telemetry.js';
+import { reportCliRun } from './telemetry/cli-telemetry.js';
 // Re-exported so existing imports (and the CLI tests) keep resolving from './cli.js'.
 export { parseCliArgs, CLI_USAGE };
 function handleInit(parsed) {
@@ -100,36 +105,6 @@ function handleStatus(port) {
         log('reticle_status', { port, running: true, pid, ...summarizeStatus(payload) });
     });
 }
-/**
- * `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
- * reminds the user which port the app must dial. Human-readable to stdout (not the JSON log).
- */
-async function handleDoctor(port) {
-    const line = (s) => {
-        process.stdout.write(`${s}\n`);
-    };
-    line('reticle doctor');
-    line(`  node         ${process.version}`);
-    try {
-        const { chromium } = await import('playwright');
-        const path = chromium.executablePath();
-        line(existsSync(path)
-            ? '  chromium     ✓ installed'
-            : '  chromium     ✗ missing — run: npx playwright install chromium');
-    }
-    catch {
-        line('  chromium     ✗ missing — run: npx playwright install chromium');
-    }
-    const pid = readPid(port);
-    if (pid !== null && isAlive(pid)) {
-        line(`  daemon       ✓ running on :${port} (pid ${pid})`);
-    }
-    else {
-        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)`);
-}
 /** Print the running package version (resolved once in server-version.ts). */
 function handleVersion() {
     log('reticle_version', { version: SERVER_VERSION });
@@ -138,24 +113,6 @@ function handleVersion() {
 function handleLicense() {
     log('reticle_license', { ...describeLicense(Date.now()) });
 }
-/**
- * `reticle telemetry [status|enable|disable]` — the user-facing control for anonymous usage metrics.
- * `disable` persists a machine-wide opt-out (survives shells, unlike RETICLE_TELEMETRY=0); `status`
- * says what's on, why, and where the full policy lives. Human-readable to stdout, like `doctor`.
- */
-function handleTelemetry(action) {
-    const line = (s) => {
-        process.stdout.write(`${s}\n`);
-    };
-    if (action !== TelemetryAction.STATUS) {
-        setTelemetryEnabled(action === TelemetryAction.ENABLE);
-    }
-    const state = describeTelemetry();
-    line(`telemetry    ${state.enabled ? 'enabled' : 'disabled'}  (${state.reason})`);
-    line(`policy       ${state.policyUrl}`);
-    if (state.enabled)
-        line('opt out      reticle telemetry disable  (or RETICLE_TELEMETRY=0 / DO_NOT_TRACK=1)');
-}
 /**
  * `reticle affected <file...>` — print which saved flows must re-verify for the given changed files.
  * Environment-side (costs the agent nothing per turn); the foundation of watch/gate. Never throws:
@@ -179,6 +136,42 @@ async function handleAffected(files, since) {
         });
     }
 }
+/**
+ * `reticle hunt <dir>` — aggregate crawl reports from many checkouts into one number.
+ *
+ * Detection already exists (`reticle_crawl`). This is the arithmetic that turns a pile of runs into
+ * the claim worth making: over N already-merged, already-green changes, how many carried a candidate
+ * false green? No control arm is needed, because those changes SHIPPED — the counterfactual is
+ * already established, which is what makes this the cheapest credible evidence available.
+ *
+ * Each file in <dir> is one crawl result. Producing them is a shell loop over a commit range:
+ * check out, boot the app, `reticle_crawl`, write the JSON here.
+ */
+async function handleHunt(dir) {
+    try {
+        const fs = createNodeFileSystem();
+        const names = await fs.readdir(dir);
+        const runs = [];
+        for (const name of names.filter((n) => n.endsWith('.json'))) {
+            const raw = await fs.readFile(join(dir, name));
+            if (raw === undefined)
+                continue;
+            const parsed = JSON.parse(raw);
+            const report = parsed;
+            runs.push({
+                label: report.label ?? name.replace(/\.json$/, ''),
+                anomalies: report.anomalies ?? [],
+                ...(report.stepsRun === undefined ? {} : { stepsRun: report.stepsRun }),
+            });
+        }
+        log('reticle_hunt', { ...summarizeHunt(runs) });
+    }
+    catch (error) {
+        log('reticle_hunt_failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 /** `reticle update` — install the latest server version and restart (moved off the MCP surface). */
 async function handleUpdate() {
     try {
@@ -237,7 +230,11 @@ function handleOpen(requestedPort, url) {
         const { sessions } = summarizeStatus(await fetchStatus(port));
         const decision = decideOpen(sessions, url);
         if (decision.action === 'need-url') {
-            log('reticle_open', { port, error: 'no app connected — pass a url: reticle open <url>' });
+            log('reticle_open', {
+                port,
+                error: 'no app connected — pass a url: reticle open <url>. Desktop app (Electron/Tauri)? ' +
+                    'There is no url to open: start it as you normally would and it connects to this bridge itself.',
+            });
             return;
         }
         if (decision.action === 'reuse') {
@@ -269,10 +266,9 @@ function handleDaemonInner(parsed) {
     startDaemon(options)
         .then((server) => {
         log('reticle_daemon_ready', { port: parsed.port, pid: process.pid });
-        // A live daemon IS an active session (the numerator of "active sessions" + DAU/WAU/MAU). Pair the
-        // START here with an END (carrying duration) on any clean shutdown below — best-effort, non-blocking.
-        const sessionStartedAt = Date.now();
-        void getTelemetry().emit(TelemetryEventKind.SESSION_START);
+        // Daemon lifecycle telemetry: started, a one-shot project profile, the periodic counter flush,
+        // and the rich summary on shutdown. All of it lives in one module — see daemon-telemetry.ts.
+        const daemonTelemetry = installDaemonTelemetry(process.cwd());
         // Publish to the discovery registry so a build plugin can find this daemon by projectId — no
         // hand-reconciled port. Written from the child (only it knows its cwd); removePid drops it.
         const registryProjectId = readProjectId(process.cwd());
@@ -289,11 +285,12 @@ function handleDaemonInner(parsed) {
             process.exit(1);
         });
         const shutdown = () => {
-            void getTelemetry().emit(TelemetryEventKind.SESSION_END, {
-                sessionMs: Date.now() - sessionStartedAt,
-            });
-            server
-                .close()
+            // Awaited before the close/exit chain: `process.exit(0)` kills an in-flight POST, and this is
+            // the one event carrying the whole session. A failed send resolves anyway (emit swallows its
+            // own errors), so this can delay the exit by at most the send timeout, never prevent it.
+            void daemonTelemetry
+                .shutdown()
+                .then(() => server.close())
                 .then(() => {
                 removePid(parsed.port);
                 process.exit(0);
@@ -392,14 +389,21 @@ function handleLegacyDrive(parsed) {
     });
 }
 function main() {
+    // Before anything reads process.env — notably the telemetry gate and the bridge's security
+    // options — fold in a project-local `.env`. Values already in the environment always win.
+    loadDotEnv(process.cwd());
     const argv = process.argv.slice(2);
     // Every invocation passes through here — the single chokepoint for the "how often is it used / how
     // many distinct machines + projects" metrics. Fire-and-forget: a metric must never delay or fail a run.
-    const telemetry = getTelemetry();
-    // `detach` so a quick command (`version`/`gate`) exits immediately instead of waiting out the POST.
-    if (telemetry.firstRun)
-        void telemetry.emit(TelemetryEventKind.INSTALL, { detach: true });
-    void telemetry.emit(TelemetryEventKind.INVOKE, { detach: true });
+    //
+    // `_daemon` is EXCLUDED, and that exclusion is the whole point of this branch. `reticle mcp` and
+    // `reticle serve` start the daemon by re-running this very binary, so the child re-entered main()
+    // and emitted a second event for what a person experienced as one action. The old `invoke` metric
+    // was therefore inflated ~2x — and inflated worst on the agent-driven sessions that matter most,
+    // while one-shot commands like `version` counted once. That skewed the RATIO between commands, not
+    // just the scale, which is the kind of error you cannot correct for after the fact. The daemon's
+    // own lifecycle is already reported by `daemon_started` / `daemon_stopped`; it is not a CLI run.
+    reportCliRun(argv);
     // Cloud subcommands (login/link/project/config/push) are a distinct family with their own async client;
     // handle them before the local typed parser so `reticle login` etc. work as one tool.
     if (isCloudCommand(argv[0])) {
@@ -409,8 +413,15 @@ function main() {
     const portEnv = process.env[ReticleEnv.PORT];
     const envPort = portEnv !== undefined ? parseInt(portEnv, 10) : undefined;
     const projectPort = readProjectPort(process.cwd());
+    // Say so rather than letting the daemon fight the dev server for the port and fail with an
+    // EADDRINUSE that mentions neither file nor cause.
+    if (projectPort !== undefined && isLikelyDevServerPort(projectPort)) {
+        process.stderr.write(`${devServerPortWarning(projectPort)}\n`);
+    }
     const defaultPort = envPort ?? projectPort ?? RETICLE_DEFAULT_PORT;
-    const parsed = parseCliArgs(argv, defaultPort);
+    // Headed by default; hidden only where there is no display to be headed on. A run nobody can see
+    // is a run nobody trusts, and every "did it actually do anything?" cost a human round-trip.
+    const parsed = parseCliArgs(argv, defaultPort, process.env['CI'] !== undefined);
     switch (parsed.kind) {
         case 'error':
             log('reticle_usage_error', { message: parsed.message });
@@ -434,6 +445,12 @@ function main() {
         case 'telemetry':
             handleTelemetry(parsed.action);
             break;
+        case 'feedback':
+            void handleFeedback(parsed.text, parsed.rating, parsed.bug);
+            break;
+        case 'identify':
+            void handleIdentify(parsed);
+            break;
         case 'version':
             handleVersion();
             break;
@@ -458,6 +475,9 @@ function main() {
         case 'affected':
             void handleAffected(parsed.files, parsed.since);
             break;
+        case 'hunt':
+            void handleHunt(parsed.dir);
+            break;
         case 'gate':
             void handleGate(parsed.files, parsed.since);
             break;
@@ -500,4 +520,3 @@ function isEntryPoint() {
 if (isEntryPoint()) {
     main();
 }
-//# sourceMappingURL=cli.js.map

package/dist/cloud/cloud-config.d.ts

@@ -34,4 +34,3 @@ export interface ProjectCloud {
  * so the single-project / CI flow is unchanged. `homeDir` is injected (testable; `os.homedir()` at call).
  */
 export declare function resolveProjectCloud(fs: FileSystemPort, reticleRoot: string, homeDir: string, env: NodeJS.ProcessEnv): Promise<ProjectCloud>;
-//# sourceMappingURL=cloud-config.d.ts.map

package/dist/cloud/cloud-config.js

@@ -84,4 +84,3 @@ export async function resolveProjectCloud(fs, reticleRoot, homeDir, env) {
     const config = key !== null ? { url: link.url.replace(/\/+$/, ''), apiKey: key } : null;
     return { config, policy, verify: link.verify, projectId: link.projectId };
 }
-//# sourceMappingURL=cloud-config.js.map

package/dist/cloud/cloud-sync.d.ts

@@ -110,20 +110,20 @@ declare const ServerVerificationSchema: z.ZodObject<{
     }>, "many">;
     summary: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    verificationId: string;
-    verdict: string | null;
     flows: {
         status: string;
         name: string;
     }[];
-    summary: string;
-}, {
     verificationId: string;
     verdict: string | null;
+    summary: string;
+}, {
     flows: {
         status: string;
         name: string;
     }[];
+    verificationId: string;
+    verdict: string | null;
     summary: string;
 }>;
 export type ServerVerification = z.infer<typeof ServerVerificationSchema>;
@@ -140,4 +140,3 @@ export declare function submitServerVerification(body: {
     source: string;
 }, config: CloudConfig | null, fetchImpl: FetchPostJsonLike): Promise<ServerVerification | null>;
 export {};
-//# sourceMappingURL=cloud-sync.d.ts.map

package/dist/cloud/cloud-sync.js

@@ -173,4 +173,3 @@ export async function submitServerVerification(body, config, fetchImpl) {
         return null;
     }
 }
-//# sourceMappingURL=cloud-sync.js.map