@reticlehq/server 3.3.0 → 3.5.0

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

@@ -14,7 +14,9 @@ import { ReticleDir, RunFlowStatus } from '@reticlehq/core';
 import { FlowStore } from '../../language/flows/flows.js';
 import { RunStore } from '../../judgement/runs/artifact/run-store.js';
 import { createNodeFileSystem } from '../../memory/project/fs/fs-port.js';
-import { affectedSavedFlows } from '../../language/flows/change/flow-sources.js';
+import { affectedSavedFlows, toFlowSources, } from '../../language/flows/change/flow-sources.js';
+import { isInteractiveSource, unflowedFiles } from '../../language/flows/change/affected.js';
+import { LedgerStore, regressions, staleChanged, unexecutedChanged, } from '../../features/exhaust/ledger.js';
 import { gateDecision } from '../../language/flows/change/gate.js';
 import { FlakeStore } from '../../language/flows/stores/flake-store.js';
 import { formatBuddyStatus } from '../../language/flows/buddy-status.js';
@@ -23,7 +25,7 @@ import { AssertionTiersStore } from '../../language/flows/stores/assertion-tiers
 import { detectDowngrades } from '../../judgement/outcome/assertion-integrity.js';
 import { computeCoverage, flowCoverageReport } from '../../language/flows/suite/coverage.js';
 import { createWatchBatcher } from '../../language/flows/change/watch-batcher.js';
-import { watch } from 'node:fs';
+import { readFileSync, statSync, watch } from 'node:fs';
 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. */
@@ -163,9 +165,35 @@ export async function handleCapsules() {
  * changed files. Flaky flows are quarantined (surfaced, not blocking). The environment-side enforcement
  * that makes verification unavoidable. Never throws; a fault fails closed (exit 1).
  */
+/**
+ * A changed file's text, or '' when it is gone. `git diff --name-only` answers from the repository
+ * root while the gate may run in a package below it, so leading segments are dropped until the path
+ * resolves from `cwd`.
+ */
+function atChangedPath(cwd, file, read) {
+    const parts = file.split('/');
+    for (let i = 0; i < parts.length; i += 1) {
+        try {
+            return read(join(cwd, ...parts.slice(i)));
+        }
+        catch {
+            // not at this depth; try the path one segment shorter
+        }
+    }
+    return undefined;
+}
+function readChangedFile(cwd, file) {
+    return atChangedPath(cwd, file, (path) => readFileSync(path, 'utf8')) ?? '';
+}
+/** When a changed file was last modified, or undefined when it is gone. Same lookup as its text. */
+function changedFileModifiedAt(cwd, file) {
+    return atChangedPath(cwd, file, (path) => statSync(path).mtimeMs);
+}
 export async function handleGate(files, since, 
 /** Hook mode: prose for a human, and silence when there was simply nothing to check. */
-hook = false) {
+hook = false, 
+/** Accept today's coverage levels as the best before judging, for a drop that was intended. */
+acceptCoverage = false) {
     try {
         const fs = createNodeFileSystem();
         const reticleRoot = join(process.cwd(), ReticleDir.ROOT);
@@ -204,7 +232,32 @@ hook = false) {
         const deleted = Object.entries(baseline)
             .filter(([name, entry]) => !byName.has(name) && entry.sources.some((f) => changedSet.has(f)))
             .map(([name]) => name);
-        const result = gateDecision({ affected, passing, flaky, downgraded, deleted });
+        // Only against a suite that exists: a project with no flows yet is NOTHING_TO_CHECK, and
+        // demanding a flow per edited component on its first day would block every stop.
+        const unflowed = 0 === allFlows.length
+            ? []
+            : unflowedFiles(toFlowSources(allFlows), changed, (file) => isInteractiveSource(readChangedFile(process.cwd(), file)));
+        // The coverage ledger, when one exists: a level that fell below its best, and changed code the
+        // browser loaded and never ran. A project that never folded coverage has an empty ledger and
+        // neither can fire.
+        const ledgerStore = new LedgerStore(fs, reticleRoot);
+        const coverageAccepted = acceptCoverage ? await ledgerStore.acceptCurrent() : [];
+        const ledger = await ledgerStore.load();
+        const unexecuted = unexecutedChanged(ledger.code, changed);
+        // Changed files whose coverage predates the edit: their counts describe the old code, so
+        // `unexecuted` cannot judge them either way. Named rather than silently read as covered; not
+        // blocking, because a destructive exhaustive crawl after every edit is not a price a gate may set.
+        const coverageStale = staleChanged(ledger, changed, (file) => changedFileModifiedAt(process.cwd(), file)).filter((file) => !unexecuted.includes(file));
+        const result = gateDecision({
+            affected,
+            passing,
+            flaky,
+            downgraded,
+            deleted,
+            unflowed,
+            coverageRegressed: regressions(ledger),
+            unexecuted,
+        });
         // Verified-surface coverage over flows: how much of the saved suite this run actually exercised.
         const coverage = computeCoverage({ testids: [], signals: [], flows: allFlows.map((f) => f.name) }, { testids: [], signals: [], flows: passing });
         // A gate over an empty suite has not passed — it had nothing to check. Same rule the suite
@@ -217,6 +270,13 @@ hook = false) {
             quarantined: result.quarantined,
             ...(result.downgraded.length > 0 ? { downgraded: result.downgraded } : {}),
             ...(result.deleted.length > 0 ? { deletedCoverage: result.deleted } : {}),
+            ...(result.unflowed.length > 0 ? { unflowed: result.unflowed } : {}),
+            ...(result.coverageRegressed.length > 0
+                ? { coverageRegressed: result.coverageRegressed }
+                : {}),
+            ...(result.unexecuted.length > 0 ? { unexecuted: result.unexecuted } : {}),
+            ...(coverageStale.length > 0 ? { coverageStale } : {}),
+            ...(coverageAccepted.length > 0 ? { coverageAccepted } : {}),
             coverage: flowCoverage,
         });
         // Two non-zero codes, because two callers want opposite things from the same run. CI wants any
@@ -242,6 +302,9 @@ hook = false) {
                     // A downgrade is reported per flow with its step indices; the hook names the flow.
                     downgraded: result.downgraded.map((d) => d.flow),
                     deleted: result.deleted,
+                    unflowed: result.unflowed,
+                    coverageRegressed: result.coverageRegressed.map((r) => `${r.level} ${String(r.was)}% -> ${String(r.now)}%`),
+                    unexecuted: result.unexecuted,
                 });
                 if (message !== undefined)
                     process.stderr.write(`${message}\n`);

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

@@ -15,7 +15,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>]\n                [--env KEY=VALUE]... [--files-only] [--hooks]  (wire Reticle into the project in this directory)\n                init is ONBOARDING: it wires the project, boots the app and proves a session\n                connected. It does not drive. The FIRST RUN is the stage that proves a flow:\n                reticle verify <url> --explore --persona \"<who does what>\", or the same thing\n                from an agent as reticle_verify { action: \"explore\", persona: \"\u2026\" }\n                --app picks WHICH app in a monorepo, when several are found\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                --relaunch prints the exact command that restarts THIS conversation with\n                the tools loaded, so the restart is not a chore handed to a human. It\n                refuses when the session id has no transcript behind it, because\n                --resume on an empty id opens a blank conversation that looks like\n                success. Works with --files-only\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-open / --no-agents / --url / --timeout are the runtime dials: CI, a\n                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] [--json]                   (a readable block; --json for the event)\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                       [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)\n                       [--select <label>]              (repeatable: verify only flows carrying these labels \u2014 no model, exit 0=pass)\n                [--expect '<json predicate>' | --expect-file <path>]   (one verdict, no saved\n                flows needed. --expect-file is the form no shell can mangle: cmd.exe keeps the\n                single quotes the docs show, and PowerShell strips the inner double quotes, and\n                a predicate that does not parse produces no verdict at all \u2014 asks the daemon that\n                is already running, so nothing is bound and nothing is stopped. It NEEDS that\n                daemon: with none on the port it refuses and names the flag, rather than reporting\n                on your saved flows instead. Cannot be combined with --storage-state, which this\n                path has nowhere to load. This is the path when your client never loaded the\n                reticle_* tools. exit 0 ONLY on verified:\"yes\" \u2014 \"unknown\" is not a 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 report [--session <id>] [--hook]             (what the latest session claimed, and what held)\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.";
+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                [--env KEY=VALUE]... [--files-only] [--hooks]  (wire Reticle into the project in this directory)\n                init is ONBOARDING: it wires the project, boots the app and proves a session\n                connected. It does not drive. The FIRST RUN is the stage that proves a flow:\n                reticle verify <url> --explore --persona \"<who does what>\", or the same thing\n                from an agent as reticle_verify { action: \"explore\", persona: \"\u2026\" }\n                --app picks WHICH app in a monorepo, when several are found\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                --relaunch prints the exact command that restarts THIS conversation with\n                the tools loaded, so the restart is not a chore handed to a human. It\n                refuses when the session id has no transcript behind it, because\n                --resume on an empty id opens a blank conversation that looks like\n                success. Works with --files-only\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-open / --no-agents / --url / --timeout are the runtime dials: CI, a\n                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] [--json]                   (a readable block; --json for the event)\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                       [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)\n                       [--select <label>]              (repeatable: verify only flows carrying these labels \u2014 no model, exit 0=pass)\n                [--expect '<json predicate>' | --expect-file <path>]   (one verdict, no saved\n                flows needed. --expect-file is the form no shell can mangle: cmd.exe keeps the\n                single quotes the docs show, and PowerShell strips the inner double quotes, and\n                a predicate that does not parse produces no verdict at all \u2014 asks the daemon that\n                is already running, so nothing is bound and nothing is stopped. It NEEDS that\n                daemon: with none on the port it refuses and names the flag, rather than reporting\n                on your saved flows instead. Cannot be combined with --storage-state, which this\n                path has nowhere to load. This is the path when your client never loaded the\n                reticle_* tools. exit 0 ONLY on verified:\"yes\" \u2014 \"unknown\" is not a pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [--accept-coverage] [file...]  (exit non-zero unless passing artifacts cover the affected flows)\n  reticle report [--session <id>] [--hook]             (what the latest session claimed, and what held)\n  reticle setup mcp                                    (register the MCP server with your agents; the installer's registration half)\n  reticle capsules                                     (list the saved fail-to-pass bug capsules in .reticle/capsules)\n  reticle hunt <dir>                                   (aggregate a directory of crawl reports into one false-green rate)\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 connect [--project <name|id>] [--url <cloud origin>]\n                                                       (wire this app if needed, sign in, link, send local history)\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";
@@ -167,6 +167,7 @@ export type CliResult = {
     files: string[];
     since?: string;
     hook?: boolean;
+    acceptCoverage?: boolean;
 } | {
     kind: 'report';
     session?: string;
@@ -190,6 +191,12 @@ export type CliResult = {
     kind: 'error';
     message: string;
 };
+/**
+ * Whether this command talks to a daemon on the resolved port, and so must not run when
+ * the workspace port conflict (cli-port) has said the port is a guess. `init` carries a port but resolves the
+ * workspace itself, and a tutorial only dials one when asked to run.
+ */
+export declare function dialsTheDaemon(parsed: CliResult): boolean;
 /**
  * @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 —

package/dist/command/cli/cli-parse.js

@@ -66,8 +66,11 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
                 path has nowhere to load. This is the path when your client never loaded the
                 reticle_* tools. exit 0 ONLY on verified:"yes" — "unknown" is not a 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 gate [--since <ref>] [--accept-coverage] [file...]  (exit non-zero unless passing artifacts cover the affected flows)
   reticle report [--session <id>] [--hook]             (what the latest session claimed, and what held)
+  reticle setup mcp                                    (register the MCP server with your agents; the installer's registration half)
+  reticle capsules                                     (list the saved fail-to-pass bug capsules in .reticle/capsules)
+  reticle hunt <dir>                                   (aggregate a directory of crawl reports into one false-green rate)
   reticle watch [url]                                  (on save, report which saved flows must re-verify)
   reticle drive <url> [--headless]                     (foreground mode, for debugging)
   reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy; auto-starts daemon if needed)
@@ -82,6 +85,8 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
                                                        (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)
 
 Cloud (link this project to Reticle; runs/flows recorded on the dashboard):
+  reticle connect [--project <name|id>] [--url <cloud origin>]
+                                                       (wire this app if needed, sign in, link, send local history)
   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)
@@ -108,6 +113,7 @@ const CAPSULES_COMMAND = 'capsules';
 const GATE_COMMAND = 'gate';
 /** Hook mode: prose a human can read, and silence when there was simply nothing to check. */
 const HOOK_FLAG = '--hook';
+const ACCEPT_COVERAGE_FLAG = '--accept-coverage';
 /** `reticle report [--session <id>] [--hook]` — what the latest session claimed, and what held. */
 const REPORT_COMMAND = 'report';
 const SESSION_FLAG = '--session';
@@ -166,7 +172,7 @@ const KNOWN_COMMANDS = new Set([
     FEEDBACK_COMMAND,
     IDENTIFY_COMMAND,
     DAEMON_INNER_COMMAND,
-    // Cloud subcommands dispatch before the local parser but are still commands a human ran.
+    'connect',
     'login',
     'logout',
     'whoami',
@@ -578,6 +584,18 @@ function parseTargetArgs(rest) {
     }
     return since === undefined ? { files } : { files, since };
 }
+/**
+ * Whether this command talks to a daemon on the resolved port, and so must not run when
+ * the workspace port conflict (cli-port) has said the port is a guess. `init` carries a port but resolves the
+ * workspace itself, and a tutorial only dials one when asked to run.
+ */
+export function dialsTheDaemon(parsed) {
+    if ('init' === parsed.kind)
+        return false;
+    if ('tutorial' === parsed.kind)
+        return parsed.run;
+    return 'port' in parsed;
+}
 /**
  * @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 —
@@ -810,15 +828,17 @@ export function parseCliArgs(argv, defaultPort, defaultHeadless = false) {
             return { kind: 'affected', files: t.files, ...(since === undefined ? {} : { since }) };
         }
         case GATE_COMMAND: {
-            // `--hook` is stripped before target parsing, which would reject it as an unknown flag.
+            // Flags are stripped before target parsing, which would reject them as unknown.
             const hook = rest.includes(HOOK_FLAG);
-            const t = parseTargetArgs(rest.filter((a) => a !== HOOK_FLAG));
+            const acceptCoverage = rest.includes(ACCEPT_COVERAGE_FLAG);
+            const t = parseTargetArgs(rest.filter((a) => a !== HOOK_FLAG && a !== ACCEPT_COVERAGE_FLAG));
             const since = t.since ?? implicitSince(t.files);
             return {
                 kind: 'gate',
                 files: t.files,
                 ...(since === undefined ? {} : { since }),
                 ...(hook ? { hook: true } : {}),
+                ...(acceptCoverage ? { acceptCoverage: true } : {}),
             };
         }
         case REPORT_COMMAND: {

package/dist/command/cli/cli-update-commands.js

@@ -14,6 +14,7 @@ import { log } from '../../log.js';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { reticleDepsOf, sdkSyncCommand } from '../update/sdk-sync.js';
+const WINDOWS_MANUAL_UPDATE = 'irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex';
 /**
  * Bring the SDK in the CURRENT project to the version being installed.
  *
@@ -94,7 +95,13 @@ export async function handleUpdate() {
         await applyUpdate(target); // calls process.exit; Claude Code restarts
     }
     catch (error) {
-        log('reticle_update_failed', { error: error instanceof Error ? error.message : String(error) });
+        const message = error instanceof Error ? error.message : String(error);
+        log('reticle_update_failed', {
+            error: message,
+            ...('win32' === process.platform && message.includes('spawn EINVAL')
+                ? { hint: `run \`${WINDOWS_MANUAL_UPDATE}\` in PowerShell to update manually` }
+                : {}),
+        });
         process.exitCode = 1;
     }
 }

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

@@ -12,6 +12,7 @@
 import { type ReticleVerificationRun } from '@reticlehq/core';
 import { type RunningServer } from '../../index.js';
 import { PortPresence } from '../daemon/binding/port-presence.js';
+import { type CloudConfig } from '../../memory/cloud/cloud-sync.js';
 import { type VerifyProgressListener } from '../../judgement/runs/reticle-runner.js';
 import type { ToolDeps } from '../../surface/tools/tool-kit.js';
 /** The live capabilities runVerify needs — faked in tests so the logic runs without a browser. */
@@ -47,6 +48,11 @@ export interface VerifyPorts {
     out: (line: string) => void;
     fail: (line: string) => void;
     exit: (code: number) => void;
+    /**
+     * The platform credential for this repo: the stored key for a linked repo, else the exported
+     * one. A port so the push is testable, and so this reads what every other caller reads.
+     */
+    cloud: () => Promise<CloudConfig | null>;
 }
 interface VerifyArgs {
     url: string;
@@ -118,12 +124,19 @@ export declare function portBusyMessage(port: number): string;
  * diagnose: the refusal they got was true.
  */
 export declare function expectNeedsDaemonMessage(port: number, presence: PortPresence): string;
+/**
+ * The model key is set here but not in the daemon, which is where the drive runs. The daemon is
+ * usually the one `init` or the agent's MCP client started, from an environment without the key.
+ */
+export declare function daemonLacksKeyMessage(port: number): string;
 /** What `verify` does next, once the options and the state of the port are both known. */
 export declare const VerifyRoute: {
     /** Ask the daemon that already owns the port for a one-shot verdict on the predicate. */
     readonly ADHOC: "adhoc";
     /** Ask the daemon that already owns the port to replay the saved flows. See runAdhocSuite. */
     readonly ADHOC_SUITE: "adhoc-suite";
+    /** Ask the daemon that already owns the port to explore the url and record flows. */
+    readonly ADHOC_EXPLORE: "adhoc-explore";
     /** Boot our own daemon, drive the url, replay the flows saved on disk. */
     readonly FLOWS: "flows";
     /** Answer the caller, and run nothing. */
@@ -134,6 +147,8 @@ export type VerifyPlan = {
     route: typeof VerifyRoute.ADHOC;
 } | {
     route: typeof VerifyRoute.ADHOC_SUITE;
+} | {
+    route: typeof VerifyRoute.ADHOC_EXPLORE;
 } | {
     route: typeof VerifyRoute.FLOWS;
 } | {
@@ -153,11 +168,17 @@ export declare function routeVerify(args: {
     /** True when the caller supplied a predicate, by `--expect` or `--expect-file`. */
     hasPredicate: boolean;
     /**
-     * True when the caller asked for something only a browser of OUR OWN can do: `--explore` (a model
-     * driving a fresh page), `--headed`, or `--storage-state`. The running daemon's tab can honour
-     * none of them, so replaying there would silently ignore the request.
+     * True when the caller asked for something only a browser of OUR OWN can do: `--headed` or
+     * `--storage-state`. The running daemon's tab can honour neither, so replaying there would
+     * silently ignore the request.
      */
     wantsOwnBrowser?: boolean;
+    /**
+     * `--explore`: a model drives the url and records flows. The daemon on the port runs the same
+     * drive (`reticle_verify { action: "explore" }`), so this is NOT a reason to need our own browser —
+     * it used to be, and `init` leaves exactly that daemon behind before recommending this command.
+     */
+    explore?: boolean;
     presence: PortPresence;
     port: number;
 }): VerifyPlan;

package/dist/command/cli/cli-verify.js

@@ -12,7 +12,7 @@
 import { join, basename } from 'node:path';
 import { readFileSync } from 'node:fs';
 import { runAdhocVerdict } from './adhoc-verdict.js';
-import { runAdhocSuite } from './adhoc-suite.js';
+import { runAdhocExplore, runAdhocSuite } from './adhoc-suite.js';
 import { exploreApp, harnessAvailable, MSG_NO_HARNESS_KEY, } from '../../surface/tools/harness-explore.js';
 import { resolveSuiteSelection } from '../../language/flows/suite-selection.js';
 import { readOrCreatePairingTokenSync, defaultPairingTokenDir, } from '../../portal/bridge/pairing-token.js';
@@ -22,8 +22,10 @@ import { start } from '../../index.js';
 import { probePresence, describePresence, PortPresence, } from '../daemon/binding/port-presence.js';
 import { EXPECT_FLAG } from './cli-parse-grammar.js';
 import { probeDaemon } from '../../surface/mcp/mcp-proxy.js';
-import { fetchStatus } from '../daemon/binding/daemon-status-probe.js';
-import { cloudFetch, createProgressReporter, resolveCloudConfig, syncProgressToCloud, syncRunToCloud, SyncOutcome, } from '../../memory/cloud/cloud-sync.js';
+import { fetchStatus, summarizeStatus } from '../daemon/binding/daemon-status-probe.js';
+import { cloudFetch, createProgressReporter, syncProgressToCloud, syncRunToCloud, SyncOutcome, } from '../../memory/cloud/cloud-sync.js';
+import { linkedCloudPort } from '../../memory/cloud/cloud-config.js';
+import { homedir } from 'node:os';
 import { ReticleRunner } from '../../judgement/runs/reticle-runner.js';
 import { createRunnerPort } from '../../judgement/runs/runner-port.js';
 import { RunStore } from '../../judgement/runs/artifact/run-store.js';
@@ -128,7 +130,7 @@ export async function runVerify(args, ports) {
          * live progress by it until the finished run replaces the whole picture.
          */
         const streamId = randomUUID();
-        const cloud = resolveCloudConfig(process.env);
+        const cloud = await ports.cloud().catch(() => null);
         const progress = createProgressReporter(streamId, cloud, cloudFetch);
         let run;
         try {
@@ -140,7 +142,7 @@ export async function runVerify(args, ports) {
             progress.stop();
             await progress.flush().catch(() => undefined);
         }
-        await pushRunToCloud(run, ports); // best-effort; opt-in; never changes the verdict or exit code
+        await pushRunToCloud(run, cloud, ports); // best-effort; opt-in; never changes the verdict or exit code
         /*
          * The last event anybody watching is waiting for, sent after the artifact has actually landed —
          * so "pushed" on a dashboard means the run is really there, not that we were about to try.
@@ -184,13 +186,12 @@ async function explore(conn, args, ports) {
     return true;
 }
 /**
- * Best-effort push of a finished run to the cloud dashboard. Opt-in: only fires when the user has set
- * RETICLE_CLOUD_URL + RETICLE_API_KEY (the "shifted to server" step). Absent → no-op, nothing leaves the
- * machine (the no-phone-home default). A push failure NEVER changes the verdict or exit code — the run is
+ * Best-effort push of a finished run to the cloud dashboard. Opt-in: only fires when this repo is
+ * linked or RETICLE_API_KEY is set. Absent → no-op, nothing leaves the machine (the no-phone-home
+ * default). A push failure NEVER changes the verdict or exit code — the run is
  * already reported locally; the cloud copy is an enhancement.
  */
-async function pushRunToCloud(run, ports) {
-    const config = resolveCloudConfig(process.env);
+async function pushRunToCloud(run, config, ports) {
     if (null === config)
         return;
     const result = await syncRunToCloud(run, config, cloudFetch);
@@ -390,12 +391,23 @@ export function expectNeedsDaemonMessage(port, presence) {
         `  • Or drop ${EXPECT_FLAG}, and verify drives the url itself and replays your saved flows — ` +
         'a different question, and it proves nothing about your predicate.');
 }
+/**
+ * The model key is set here but not in the daemon, which is where the drive runs. The daemon is
+ * usually the one `init` or the agent's MCP client started, from an environment without the key.
+ */
+export function daemonLacksKeyMessage(port) {
+    return (`${ReticleEnv.HARNESS_KEY} is set in this shell, but the daemon on port ${String(port)} was ` +
+        'started without it, and the drive runs inside the daemon. Restart it from this shell so it ' +
+        `inherits the key: npx @reticlehq/server restart --port ${String(port)}`);
+}
 /** What `verify` does next, once the options and the state of the port are both known. */
 export const VerifyRoute = {
     /** Ask the daemon that already owns the port for a one-shot verdict on the predicate. */
     ADHOC: 'adhoc',
     /** Ask the daemon that already owns the port to replay the saved flows. See runAdhocSuite. */
     ADHOC_SUITE: 'adhoc-suite',
+    /** Ask the daemon that already owns the port to explore the url and record flows. */
+    ADHOC_EXPLORE: 'adhoc-explore',
     /** Boot our own daemon, drive the url, replay the flows saved on disk. */
     FLOWS: 'flows',
     /** Answer the caller, and run nothing. */
@@ -418,6 +430,9 @@ export function routeVerify(args) {
     }
     if (args.presence !== PortPresence.DAEMON)
         return { route: VerifyRoute.FLOWS };
+    if (true === args.explore && true !== args.wantsOwnBrowser) {
+        return { route: VerifyRoute.ADHOC_EXPLORE };
+    }
     // No predicate, but there may be SAVED FLOWS, and a daemon already owns the port: replay them
     // there rather than refusing, unless the request needs a browser that path never opens.
     return true === args.wantsOwnBrowser
@@ -470,6 +485,7 @@ export function handleVerify(parsed) {
         out: (line) => process.stdout.write(`${line}\n`),
         fail: (line) => process.stderr.write(`${line}\n`),
         exit: (code) => process.exit(code),
+        cloud: linkedCloudPort(createNodeFileSystem(), reticleRoot, homedir(), process.env),
     };
     // Asked BEFORE anything binds. The listen failure arrives asynchronously on the server object,
     // long after `start` has resolved, so no `.catch` on that promise can ever see it — which is why
@@ -479,7 +495,8 @@ export function handleVerify(parsed) {
         const presence = await probePresence(port, { tcpOpen: probeDaemon, status: fetchStatus });
         const plan = routeVerify({
             hasPredicate: expectation !== undefined,
-            wantsOwnBrowser: true === parsed.explore || !parsed.headless || parsed.storageState !== undefined,
+            wantsOwnBrowser: !parsed.headless || parsed.storageState !== undefined,
+            explore: true === parsed.explore || parsed.persona !== undefined,
             presence,
             port,
         });
@@ -502,6 +519,9 @@ export function handleVerify(parsed) {
                     port,
                     ...(parsed.url !== undefined && '' !== parsed.url ? { url: parsed.url } : {}),
                     predicate: expectation,
+                    // Read fresh, not from `presence`: that probe asks whether a daemon is on the port, and
+                    // this asks whether a TAB is — the difference between asserting and opening the url first.
+                    sessions: async () => summarizeStatus(await fetchStatus(port)).sessions,
                     ...(parsed.sessionId === undefined ? {} : { sessionId: parsed.sessionId }),
                     ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
                 });
@@ -524,6 +544,29 @@ export function handleVerify(parsed) {
                 ports.exit(suite.code);
                 return;
             }
+            // `--explore` with a daemon on the port — the state `init` leaves behind right before it names
+            // this command as the first run. The daemon drives and records; this process only asks.
+            case VerifyRoute.ADHOC_EXPLORE: {
+                const explored = await runAdhocExplore({
+                    port,
+                    url: parsed.url,
+                    ...(parsed.persona === undefined ? {} : { persona: parsed.persona }),
+                    sessions: async () => summarizeStatus(await fetchStatus(port)).sessions,
+                    ...((t) => (t === undefined || 0 === t.length ? {} : { token: t }))(readOrCreatePairingTokenSync(defaultPairingTokenDir())),
+                });
+                for (const line of explored.lines)
+                    ports.out(line);
+                // The drive runs INSIDE the daemon, so the key has to be in ITS environment. A reader who
+                // exported it in this shell and got "set ANTHROPIC_API_KEY" back has been told to do the
+                // thing they just did; say where the key is actually missing.
+                if (0 !== explored.code && harnessAvailable(process.env)) {
+                    const refusedForKey = explored.lines.some((line) => line.includes(MSG_NO_HARNESS_KEY));
+                    if (refusedForKey)
+                        ports.fail(daemonLacksKeyMessage(port));
+                }
+                ports.exit(explored.code);
+                return;
+            }
             case VerifyRoute.FLOWS:
                 await runVerify({
                     url: parsed.url,

package/dist/command/cli/cloud-cli.js

@@ -42,6 +42,7 @@ import { diskSink, diskSource, readCloudIssues, readCloudState } from '../../mem
  */
 const CLOUD_COMMANDS = new Set([
     'login',
+    'connect',
     'logout',
     'whoami',
     'link',
@@ -438,6 +439,62 @@ const cmdLink = async (argv) => {
     }
     return 0;
 };
+/**
+ * `reticle connect` finishes the cloud half of first-run setup in one invocation. The CLI entry
+ * initializes an unwired app before calling this verb. A saved login is checked against this exact
+ * host before reuse; an expired one opens the normal browser approval flow. Login does not auto-link
+ * here because this command links once, to the project the caller named, then sends local history.
+ */
+const cmdConnect = async (argv) => {
+    for (let i = 0; i < argv.length; i += 2) {
+        const flag = argv[i];
+        const value = argv[i + 1];
+        if ((flag !== '--project' && flag !== '--url') ||
+            value === undefined ||
+            0 === value.length ||
+            value.startsWith('--')) {
+            err('usage: reticle connect [--project <name|id>] [--url <cloud origin>]');
+            return 2;
+        }
+    }
+    if (!(await createNodeFileSystem().exists(join(process.cwd(), RETICLE_CONFIG_BASENAME)))) {
+        err('this app is not wired yet — run `reticle init` in its directory, then `reticle connect`');
+        return 2;
+    }
+    const f = flags(argv);
+    const url = baseUrl(null, f['url']);
+    if (undefined === apiKeyFrom(process.env)) {
+        const session = await readSessionFor(url);
+        let signedIn = false;
+        if (session !== null) {
+            try {
+                await api('GET', `${url}/v1/me`, session.token);
+                signedIn = true;
+            }
+            catch {
+                hint('saved sign-in needs renewal — opening browser approval');
+            }
+        }
+        if (!signedIn) {
+            const code = await cmdLogin(['--url', url], cmdLink, false);
+            if (code !== 0)
+                return code;
+        }
+    }
+    const linkArgs = [
+        '--url',
+        url,
+        ...(f['project'] === undefined ? [] : ['--project', f['project']]),
+    ];
+    const linked = await cmdLink(linkArgs);
+    if (linked !== 0)
+        return linked;
+    const pushed = await cmdPush();
+    if (pushed !== 0)
+        return pushed;
+    hint('Connected. Open your coding agent and ask it to verify one flow in your app.');
+    return 0;
+};
 /** `reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]`. */
 const cmdConfig = async (argv) => {
     const f = flags(argv);
@@ -489,7 +546,7 @@ const cmdSync = async (argv) => {
     const reticleRoot = join(process.cwd(), RETICLE_DIR);
     const cloud = await resolveProjectCloud(fs, reticleRoot, homedir(), process.env);
     if (null === cloud.config) {
-        err('cloud not attached here — run `reticle link` (or set RETICLE_CLOUD_URL/KEY)');
+        err(cloud.reason ?? 'cloud not attached here: run `reticle link`, or set RETICLE_API_KEY');
         return 1;
     }
     const config = cloud.config;
@@ -521,7 +578,10 @@ const cmdSync = async (argv) => {
                 flows: report.flowsSent,
                 records: report.derivedSent,
                 ...(report.runsRejected.length > 0 ? { rejected: report.runsRejected } : {}),
+                ...(report.refused.length > 0 ? { refused: report.refused } : {}),
             },
+            ...(report.held.length > 0 ? { notSent: report.held } : {}),
+            ...(report.notRetried.length > 0 ? { notRetried: report.notRetried } : {}),
             pulled: report.pulled,
             ...(report.morePending ? { morePending: true } : {}),
             ...(report.error === undefined ? {} : { error: report.error }),
@@ -546,7 +606,7 @@ const repoCloud = async () => {
     const fs = createNodeFileSystem();
     const cloud = await resolveProjectCloud(fs, join(process.cwd(), RETICLE_DIR), homedir(), process.env);
     if (null === cloud.config)
-        throw new Error('cloud not attached here — run `reticle link` (or set RETICLE_CLOUD_URL/KEY)');
+        throw new Error(cloud.reason ?? 'cloud not attached here: run `reticle link`, or set RETICLE_API_KEY');
     return cloud.config;
 };
 /** `reticle runs` — the linked project's recent run artifacts (the key scopes it server-side). */
@@ -658,6 +718,8 @@ export const runCloudCommand = async (argv) => {
                 // The linker is passed in rather than imported by cloud-login: login ends by linking and
                 // link needs a session, so the cycle is broken at this one call site.
                 return await cmdLogin(rest, cmdLink);
+            case 'connect':
+                return await cmdConnect(rest);
             case 'logout':
                 return await cmdLogout(rest);
             case 'whoami':

package/dist/command/cli/cloud-kit.js

@@ -8,15 +8,13 @@
  * `cloud-login` is the first to move — and it is a real seam rather than a file-size dodge: nothing
  * here knows what a project, a credential or a link is.
  */
-import { apiKeyFrom } from '@reticlehq/core';
+import { DEFAULT_PLATFORM_URL, apiKeyFrom, cloudUrlFrom } from '@reticlehq/core';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { z } from 'zod';
 import { cloudFetch } from '../../memory/cloud/cloud-sync.js';
 import { normalizeUrl, readSessionFrom, resolveSessionFor, sessionPath, } from './auth/cloud-session.js';
-/** Where `reticle login` dials when nothing says otherwise: the hosted service. */
-const DEFAULT_URL = 'https://app.reticle.sh';
 export const RETICLE_DIR = '.reticle';
 export const SESSION_FILE = 'session.json';
 export const CREDENTIALS_FILE = 'credentials.json';
@@ -72,7 +70,7 @@ export const baseUrl = (session, explicit) => {
     // and it cannot leak into a sibling process the way an exported variable does.
     if (explicit !== undefined && explicit.length > 0)
         return normalizeUrl(explicit);
-    const env = process.env['RETICLE_CLOUD_URL'];
+    const env = cloudUrlFrom(process.env);
     if (env !== undefined && env.length > 0)
         return env.replace(/\/+$/, '');
     if (null !== session && session.url.length > 0)
@@ -81,7 +79,7 @@ export const baseUrl = (session, explicit) => {
     // saying because that default was wrong for everyone except us. The default is now the hosted
     // service, so the fallback IS the intended path — and a warning printed on the correct path is
     // how people learn to ignore stderr, which is where the real problems are written.
-    return DEFAULT_URL;
+    return DEFAULT_PLATFORM_URL;
 };
 /** Bearer for a command: an explicit api key (agent) wins, else the human login token. */
 export const bearer = (session) => apiKeyFrom(process.env) ?? session?.token ?? null;

package/dist/command/cli/cloud-login.d.ts

@@ -4,7 +4,7 @@ type Linker = (argv: readonly string[]) => Promise<number>;
  * `reticle login` — browser device flow by default; `--email <e>` (or a positional email) keeps the
  * headless two-step code path for CI/servers where opening a browser makes no sense.
  */
-export declare const cmdLogin: (argv: readonly string[], link: Linker) => Promise<number>;
+export declare const cmdLogin: (argv: readonly string[], link: Linker, autoLink?: boolean) => Promise<number>;
 /** `reticle logout` — forget the cached session token (per-project keys under credentials.json stay). */
 /**
  * `reticle logout` — sign out of ONE host, not of everywhere.