@reticlehq/server 3.4.0 → 3.6.0

package/README.md

@@ -27,4 +27,4 @@ See the [main README](https://github.com/reticlehq/reticle).
 
 ## License
 
-[FSL-1.1-ALv2](./LICENSE) (source-available: free for any use except reselling Reticle itself; converts to Apache-2.0 after two years). Files under `dist/ee/` are enterprise features covered by the [Reticle Enterprise License](./LICENSE-ENTERPRISE) — free for development, testing, and evaluation; a license key activates them in production.
+[FSL-1.1-ALv2](./LICENSE) (source-available: free for any use except reselling Reticle itself; converts to Apache-2.0 after two years). Files under `dist/features/ee/` are enterprise features covered by the [Reticle Enterprise License](./LICENSE-ENTERPRISE) — free for development, testing, and evaluation; a license key activates them in production.

package/SKILL.md

@@ -8,7 +8,13 @@ This file is the whole critical path and nothing else. Everything it leaves out
 
 Do not spend a turn working out which path you are on.
 
-**`reticle_*` tools visible?** The machine is set up. Go straight to the project:
+**`reticle_*` tools visible?** The machine is set up; installing changed no app. In the project, call:
+
+```
+reticle_session { action: "list" }
+```
+
+On a never-connected project that call runs `init` itself and lists the files it changed under `wired`; tell the user. If it answers `run_init`, the daemon was started outside the project: run this in the app's directory:
 
 ```bash
 RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init
@@ -23,7 +29,7 @@ irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1
 
 It registers the MCP server with the coding agents it finds and, where an agent has a per-server approval rule (Claude Code, for one), pre-approves Reticle's own tools. They reopen this client and the tools are there. If they want to choose each step instead, the manual install is `https://docs.reticle.sh/install-manual.md`. Do not register it yourself and then work around your client not having reloaded: that is the sequence that breaks.
 
-`init` is ONBOARDING, and where it stops: wire, boot, wait for a session. Idempotent, reporting `·` for what is already there. Two things it cannot do for you, in this order:
+`init`, whether the first session call runs it or you do, is ONBOARDING, and where it stops: wire, boot, wait for a session. Idempotent, reporting `·` for what is already there. Two things it cannot do for you, in this order:
 
 1. **Restart the dev server if one was already running when `init` ran.** It read the build config at boot; `init` edited that file afterwards, so the process keeps serving a bundle with no SDK in it. Restart, then hard-reload the tab. A 100% failure, not an intermittent one, and the largest single cause of a correct install that finds nothing connected.
 2. **Confirm rather than assume:** `reticle_session { action: "list" }`. One session listed is the proof the SDK reached the page. An empty list carries a `why` that names which cause this is; read it before changing anything.
@@ -31,10 +37,10 @@ It registers the MCP server with the coding agents it finds and, where an agent
 Then the FIRST RUN, which proves anything at all:
 
 ```
-reticle_verify { action: "explore", persona: "<the journey worth proving>" }
+reticle_act_and_wait { ref, action, until }
 ```
 
-Name the journey: Reticle can list the buttons, not which one matters. `explore` SAVES what it drove, so later runs replay with no model.
+Drive the journey that matters; `until` on its LAST step names the end state. It is saved as a flow that replays with no model. On a linked project (Free includes monthly Harness credits), `reticle_verify { action: "explore", persona }` drives it for you on the Reticle platform. Either way, name the journey: Reticle lists buttons, not which one matters.
 
 Everything between here and there is a rule the steps assume. Read it as you go, not before you act.
 
@@ -42,7 +48,7 @@ Everything between here and there is a rule the steps assume. Read it as you go,
 
 **Setup is not complete until you have driven one real flow in the user's app and produced a verdict.** Writing config files is not installed. Every earlier point looks like success and is not:
 
-- `init` exited 0. Wired, and connected. Nothing is PROVED: that is the first run.
+- `init` exited 0, or the first session call came back `wired`. Wired, and connected. Nothing is PROVED: that is the first run.
 - The `reticle_*` tools appeared. Your client can reach a daemon. The app is very likely still uninstrumented.
 - A session is listed. The app dialled in. The user has still seen nothing happen.
 
@@ -59,7 +65,7 @@ Two places always need the user:
 1. **No recognisable dev script in `package.json`.** Say so; do not invent one.
 2. **Your host asks the human to approve a command.** That prompt belongs to the host. Never bypass or suppress it, and take a refusal as the answer. `init` writing a pre-approval rule for the `reticle` server is not that: it is a scoped, announced config change the human asked for by running the command, and it covers only Reticle's own tools.
 
-**A client restart is not one of them, and that is the point.** Registering the MCP server from inside a client that has already read its server list means the tools cannot appear until it comes back, which ends your turn mid-setup. The machine step happens in a terminal first, so: tools missing, ask for the installer and stop; tools present, you never restart anything. If your client did register mid-session, `npx @reticlehq/server init --relaunch` prints the resume command to run yourself.
+**A client restart is not one of them.** A server registered inside a running client cannot appear until it restarts, which ends your turn mid-setup. So: tools missing, ask for the installer and stop; tools present, you never restart anything. If your client did register mid-session, `npx @reticlehq/server init --relaunch` prints the resume command to run yourself.
 
 ## Feedback is first-class
 
@@ -96,7 +102,7 @@ Every page arrives with the rules that matter prepended, so one fetch orients yo
 
 You do not have to decide. `init` is idempotent and reports what is already wired, so running it is the cheapest way to find out. It never drives; the first run is yours to start.
 
-Read **VERIFY** below when the question is "does this still work?" rather than "is this set up?". If `reticle_session` returns an empty list on a project that is already wired, read `docs/troubleshooting.mdx` beside this file (no network call, which matters when something is already not working), or fetch `https://docs.reticle.sh/troubleshooting.md`; do not restart setup.
+Read **VERIFY** below when the question is "does this still work?" rather than "is this set up?". If `reticle_session` returns an empty list on a project that is already wired, read `docs/troubleshooting.mdx` beside this file (no network call), or fetch `https://docs.reticle.sh/troubleshooting.md`; do not restart setup.
 
 ---
 
@@ -112,7 +118,7 @@ You need it once, while setting a project up. If `reticle_session` already lists
 
 **Verdicts come from `reticle_act_and_wait`, `reticle_assert`, and `reticle_act { steps }` when a step declares `expect`** (plus `reticle_verify` replays). Everything else (a bare `act`, `look`, `navigate`, `observe`) moves or reads the app and proves nothing. A drive that ends without a verdict has no result, however many tools it used.
 
-A verdict of `verified: "unknown"` is not a pass. It means Reticle drove the app and could not tell what happened. Report it as unknown. `verified: "no-fault"` is not a pass either. It means the page settled and no channel reported a problem, but nothing was declared to prove, so assert a consequence the action CHANGES. **Never weaken a check to make it pass.**
+`verified: "unknown"` is not a pass: Reticle drove the app and could not tell what happened; report it as unknown. Nor is `"no-fault"`: the page settled with nothing wrong, but nothing was declared to prove, so assert a consequence the action CHANGES. **Never weaken a check to make it pass.**
 
 ## Take the cheapest path that answers the question
 
@@ -180,4 +186,6 @@ The advertised surface is deliberately small (`default` 10, `all` 30, the wider
 
 Report what you drove, what it produced, and the `file:line` for anything broken.
 
+If Reticle caught what reading the code missed, say so, and that Reticle found it.
+
 Beyond change verification (security behaviour, accessibility, performance, SEO basics, personas), what each checks and the call to make: `https://docs.reticle.sh/use-cases.md`.

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

@@ -22,9 +22,11 @@ export interface ChromiumLaunchOptions {
     args: string[];
     /** An installed Chrome/Edge to drive instead of Playwright's own build; absent = the bundled one. */
     channel?: string;
+    /** A Chromium executable to launch directly, from RETICLE_CHROMIUM_PATH. */
+    executablePath?: string;
 }
 /**
  * Build the launch options for a headless or headed Chromium. Pure; returns a fresh mutable array
  * each call so no caller can mutate the constant behind everyone else's back.
  */
-export declare function chromiumLaunchOptions(headless: boolean, channel?: string): ChromiumLaunchOptions;
+export declare function chromiumLaunchOptions(headless: boolean, channel?: string, executablePath?: string): ChromiumLaunchOptions;

package/dist/chromium-launch-options.js

@@ -24,10 +24,11 @@ export const CHROMIUM_ANTI_THROTTLING_ARGS = [
  * Build the launch options for a headless or headed Chromium. Pure; returns a fresh mutable array
  * each call so no caller can mutate the constant behind everyone else's back.
  */
-export function chromiumLaunchOptions(headless, channel) {
+export function chromiumLaunchOptions(headless, channel, executablePath) {
     return {
         headless,
         args: [...CHROMIUM_ANTI_THROTTLING_ARGS],
         ...(channel === undefined ? {} : { channel }),
+        ...(executablePath === undefined ? {} : { executablePath }),
     };
 }

package/dist/command/cli/adhoc-verdict.d.ts

@@ -79,6 +79,7 @@ export declare function leaseIfNoTab(caller: ToolCaller, url: string, sessions:
  */
 export declare function acquireLease(caller: ToolCaller, url: string): Promise<{
     leased: string;
+    zeroInstall: boolean;
 } | {
     failed: string[];
 }>;

package/dist/command/cli/adhoc-verdict.js

@@ -52,9 +52,12 @@ function sameDocument(a, b) {
  */
 export async function acquireLease(caller, url) {
     const acquired = await caller.call(ReticleTool.RUN, { tool: ReticleTool.LEASE, args: { action: LeaseAction.ACQUIRE, url } }, LEASE_TIMEOUT_MS);
-    const sessionId = verdictOf(acquired, 'sessionId')?.['sessionId'];
-    if ('string' === typeof sessionId)
-        return { leased: sessionId };
+    const report = verdictOf(acquired, 'sessionId');
+    const sessionId = report?.['sessionId'];
+    // `zeroInstall`: the page never dialled in, so the lease supplied Reticle's own reader.
+    if ('string' === typeof sessionId) {
+        return { leased: sessionId, zeroInstall: true === report?.['zeroInstall'] };
+    }
     const why = verdictOf(acquired, 'error')?.['error'];
     return {
         failed: [

package/dist/command/cli/answers/open-note.d.ts

@@ -18,3 +18,5 @@
  * So the substitution is stated FIRST, with both numbers, before any cause that assumes they match.
  */
 export declare function openFailureNote(port: number, requestedPort: number): string;
+/** Recovery when the OS could not open a URL: agents can use Reticle's browser lease instead. */
+export declare function openLaunchFailureNote(url: string, launcher: string): string;

package/dist/command/cli/answers/open-note.js

@@ -1,3 +1,18 @@
+import { ReticleTool } from '@reticlehq/core';
+const LeaseAction = { ACQUIRE: 'acquire' };
+const LeaseArgument = {
+    TOOL: 'tool',
+    ARGS: 'args',
+    ACTION: 'action',
+    URL: 'url',
+};
+const OpenLaunchFailureCopy = {
+    NOTHING_OPENED: 'Nothing was opened.',
+    OS_BROWSER: 'This command asks the OS to open a url in your default browser',
+    LAUNCH_FAILED: (launcher) => `(\`${launcher}\` on this platform) and that failed,`,
+    OPEN_MANUALLY: 'so open the url yourself or set a default browser.',
+    RETICLE_BROWSER: 'If you are using Reticle tools, open it in a Reticle-owned browser with',
+};
 /**
  * What `reticle open` says when it launched a URL and no session appeared.
  *
@@ -35,3 +50,10 @@ export function openFailureNote(port, requestedPort) {
         `non-localhost host, which needs BOTH allowNonLocalhost: true AND a pairing token ` +
         `(~/.reticle/pairing-token) — the flag alone is not sufficient.`);
 }
+/** Recovery when the OS could not open a URL: agents can use Reticle's browser lease instead. */
+export function openLaunchFailureNote(url, launcher) {
+    return (`${OpenLaunchFailureCopy.NOTHING_OPENED} ${OpenLaunchFailureCopy.OS_BROWSER} ` +
+        `${OpenLaunchFailureCopy.LAUNCH_FAILED(launcher)} ${OpenLaunchFailureCopy.OPEN_MANUALLY} ` +
+        `${OpenLaunchFailureCopy.RETICLE_BROWSER} ` +
+        `\`${ReticleTool.RUN} { ${LeaseArgument.TOOL}: "${ReticleTool.LEASE}", ${LeaseArgument.ARGS}: { ${LeaseArgument.ACTION}: "${LeaseAction.ACQUIRE}", ${LeaseArgument.URL}: ${JSON.stringify(url)} } }\`.`);
+}

package/dist/command/cli/auth/cloud-session.d.ts

@@ -21,17 +21,17 @@ declare const SessionSchema: z.ZodObject<{
     /** Who signed in. Absent in sessions written before it was recorded. */
     email: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    url: string;
     token: string;
+    url: string;
     orgName: string;
-    email?: string | undefined;
     orgId?: string | undefined;
+    email?: string | undefined;
 }, {
-    url: string;
     token: string;
+    url: string;
     orgName: string;
-    email?: string | undefined;
     orgId?: string | undefined;
+    email?: string | undefined;
 }>;
 export type Session = z.infer<typeof SessionSchema>;
 /** Trailing slashes are not identity: `https://x/` and `https://x` are one host. */

package/dist/command/cli/auth/device-flow.d.ts

@@ -53,18 +53,18 @@ export declare const DevicePollSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     status: string;
+    token?: string | undefined;
     org?: {
         name: string;
         id?: string | undefined;
     } | undefined;
-    token?: string | undefined;
 }, {
     status: string;
+    token?: string | undefined;
     org?: {
         name: string;
         id?: string | undefined;
     } | undefined;
-    token?: string | undefined;
 }>;
 /**
  * Best-effort open the approval page in the default browser.

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

@@ -10,14 +10,14 @@ import { gateHookMessage, GATE_SKIP_ENV } from './answers/gate-hook-message.js';
 import { readProjectId } from './ports/resolve/cli-port.js';
 import { changedFilesSince } from '../../language/flows/change/git-changed.js';
 import { join } from 'node:path';
-import { ReticleDir, RunFlowStatus } from '@reticlehq/core';
+import { ReticleDir } 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, 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 { gateDecision, passingFlowNames } from '../../language/flows/change/gate.js';
 import { FlakeStore } from '../../language/flows/stores/flake-store.js';
 import { formatBuddyStatus } from '../../language/flows/buddy-status.js';
 import { CapsuleStore } from '../../judgement/capsule/capsule-store.js';
@@ -72,9 +72,7 @@ export async function loadNamedFlows(fs, reticleRoot, projectId) {
 async function emitBuddyStatus(fs, reticleRoot, flows, affected) {
     try {
         const latest = await new RunStore(fs, reticleRoot).latest();
-        const passingNames = new Set((latest?.flows ?? [])
-            .filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED)
-            .map((f) => f.name));
+        const passingNames = new Set(passingFlowNames(latest?.flows ?? []));
         const quarantined = await new FlakeStore(fs, reticleRoot).flakyFlows();
         const flaky = new Set(quarantined);
         // A deviation is an at-risk flow with no passing artifact — and a quarantined flake is not a deviation.
@@ -202,9 +200,7 @@ acceptCoverage = false) {
         const allFlows = await loadNamedFlows(fs, reticleRoot, readProjectId(process.cwd()));
         const affected = affectedSavedFlows(allFlows, changed).affected;
         const latest = await new RunStore(fs, reticleRoot).latest();
-        const passing = (latest?.flows ?? [])
-            .filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED)
-            .map((f) => f.name);
+        const passing = passingFlowNames(latest?.flows ?? []);
         const flaky = await new FlakeStore(fs, reticleRoot).flakyFlows();
         // Anti-reward-hacking: diff each flow's CURRENT assertions against what it asserted the last
         // time it passed. A mustHold that dropped from a real consequence to a fakeable presence check is a

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>] [--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 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 tutorial [--run] [--headless] [--port N]   (watch Reticle verify a demo app, in seconds)\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                an agent drives one journey with reticle_act_and_wait and an `until` on its last\n                step; with a linked project, reticle_verify { action: \"explore\", persona: \"\u2026\" }\n                (or reticle verify <url> --explore --persona \"\u2026\") drives it instead\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 avoids cmd.exe and PowerShell quote mangling. It\n                asks an existing daemon, never binds or stops one; with none, it refuses.\n                Cannot combine with --storage-state. Use when the client lacks reticle_*\n                tools. exit 0 ONLY on verified:\"yes\" \u2014 \"unknown\" is not a pass. For an\n                action --expect cannot do, drive the daemon's HTTP MCP transport instead \u2014 see\n                https://docs.reticle.sh/http-transport.md)\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";

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

@@ -22,12 +22,14 @@ export { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
  */
 export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticle <command>\` once the bin is on your PATH)
 
+  reticle tutorial [--run] [--headless] [--port N]   (watch Reticle verify a demo app, in seconds)
   reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
                 [--env KEY=VALUE]... [--files-only] [--hooks]  (wire Reticle into the project in this directory)
                 init is ONBOARDING: it wires the project, boots the app and proves a session
                 connected. It does not drive. The FIRST RUN is the stage that proves a flow:
-                reticle verify <url> --explore --persona "<who does what>", or the same thing
-                from an agent as reticle_verify { action: "explore", persona: "…" }
+                an agent drives one journey with reticle_act_and_wait and an \`until\` on its last
+                step; with a linked project, reticle_verify { action: "explore", persona: "…" }
+                (or reticle verify <url> --explore --persona "…") drives it instead
                 --app picks WHICH app in a monorepo, when several are found
                 --env is what the app needs to reach a usable state: the key from
                 .env.example, the mock backend, the variable that skips an auth wall.
@@ -57,14 +59,12 @@ export const CLI_USAGE = `usage:  npx @reticlehq/server <command>   (or \`reticl
                        [--explore] [--persona <who>]   (no saved flows? let Reticle drive the app itself and record them)
                        [--select <label>]              (repeatable: verify only flows carrying these labels — no model, exit 0=pass)
                 [--expect '<json predicate>' | --expect-file <path>]   (one verdict, no saved
-                flows needed. --expect-file is the form no shell can mangle: cmd.exe keeps the
-                single quotes the docs show, and PowerShell strips the inner double quotes, and
-                a predicate that does not parse produces no verdict at all — asks the daemon that
-                is already running, so nothing is bound and nothing is stopped. It NEEDS that
-                daemon: with none on the port it refuses and names the flag, rather than reporting
-                on your saved flows instead. Cannot be combined with --storage-state, which this
-                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)
+                flows needed. --expect-file avoids cmd.exe and PowerShell quote mangling. It
+                asks an existing daemon, never binds or stops one; with none, it refuses.
+                Cannot combine with --storage-state. Use when the client lacks reticle_*
+                tools. exit 0 ONLY on verified:"yes" — "unknown" is not a pass. For an
+                action --expect cannot do, drive the daemon's HTTP MCP transport instead — see
+                https://docs.reticle.sh/http-transport.md)
   reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)
   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)
@@ -85,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)
@@ -170,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',

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

@@ -125,7 +125,7 @@ export declare function portBusyMessage(port: number): string;
  */
 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
+ * The platform key is set here but not in the daemon, which is what asks the platform. 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;

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

@@ -13,18 +13,20 @@ import { join, basename } from 'node:path';
 import { readFileSync } from 'node:fs';
 import { runAdhocVerdict } from './adhoc-verdict.js';
 import { runAdhocExplore, runAdhocSuite } from './adhoc-suite.js';
-import { exploreApp, harnessAvailable, MSG_NO_HARNESS_KEY, } from '../../surface/tools/harness-explore.js';
+import { exploreApp, harnessAvailable, MSG_NO_HARNESS_KEY, withLinkedCredential, } from '../../surface/tools/harness-explore.js';
+import { linkedCloudPort } from '../../memory/cloud/cloud-config.js';
 import { resolveSuiteSelection } from '../../language/flows/suite-selection.js';
-import { readOrCreatePairingTokenSync, defaultPairingTokenDir, } from '../../portal/bridge/pairing-token.js';
+import { projectOnly } from '../../memory/project/session-root.js';
+import { configuredPairingToken, nodePairingTokenDeps, readOrCreatePairingTokenSync, defaultPairingTokenDir, } from '../../portal/bridge/pairing-token.js';
 import { randomUUID } from 'node:crypto';
-import { RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, VerifyPhase, } from '@reticlehq/core';
+import { MCP_SSE_PATH, MCP_MESSAGE_PATH, RETICLE_DEFAULT_PORT, ReticleEnv, bridgeWsUrl, isLoopbackHostname, ReticleDir, RunAgentKind, RunFramework, RunProfile, RunTrigger, VerdictStatus, VerifyPhase, } from '@reticlehq/core';
 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, 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 { linkedRunsCloudPort } 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';
@@ -233,6 +235,9 @@ export function buildVerifyDeps(running, reticleRoot, now) {
         fs,
         reticleRoot,
         now,
+        // The key `reticle connect` filed. Without it a connected machine that never exported
+        // RETICLE_API_KEY was told to run `reticle connect` when asking the Harness to drive.
+        linkedCloud: linkedCloudPort(fs, reticleRoot, homedir(), process.env),
     };
     if (running.realInput !== undefined)
         deps.realInput = running.realInput;
@@ -259,17 +264,18 @@ async function openLiveConnection(opts) {
     const envPort = Number(process.env[ReticleEnv.PORT]);
     const port = Number.isFinite(envPort) && envPort > 0 ? envPort : opts.port;
     const { origin, loopback } = urlParts(opts.url);
-    const pairing = loopback
+    // The configured token when there is one: an app in a container presents the one in the shared
+    // token directory, and a fresh one-shot token refused it (#1251).
+    const token = loopback
+        ? undefined
+        : ((await configuredPairingToken(process.env, nodePairingTokenDeps())) ?? randomUUID());
+    const pairing = token === undefined
         ? {}
-        : (() => {
-            const token = randomUUID();
-            const bridgeUrl = bridgeWsUrl(port);
-            return {
-                token,
-                injectConnect: { token, url: bridgeUrl },
-                ...(origin !== undefined ? { allowedOrigins: [origin] } : {}),
-            };
-        })();
+        : {
+            token,
+            injectConnect: { token, url: bridgeWsUrl(port) },
+            ...(origin !== undefined ? { allowedOrigins: [origin] } : {}),
+        };
     const running = await start({
         port,
         driveUrl: opts.url,
@@ -281,18 +287,19 @@ async function openLiveConnection(opts) {
         ...(opts.storageState !== undefined ? { storageState: opts.storageState } : {}),
     });
     const deps = buildVerifyDeps(running, opts.reticleRoot, opts.now);
+    const harnessEnv = await withLinkedCredential(deps, process.env);
     const runner = new ReticleRunner(createRunnerPort(deps, opts.sessionId));
     return {
         sessionReady: (timeoutMs) => waitForSession(deps.sessions, timeoutMs, opts.now),
         listFlows: async (select) => select === undefined || 0 === select.length
             ? deps.flows.list()
-            : (await resolveSuiteSelection(deps, undefined, { labels: [...select] })).run,
+            : (await resolveSuiteSelection(deps, projectOnly(undefined), { labels: [...select] })).run,
         // Absent, not throwing, when no model is configured: the CLI reads its absence as "unavailable"
         // and prints the one sentence that makes it available.
-        ...(harnessAvailable(process.env)
+        ...(harnessAvailable(harnessEnv)
             ? {
                 explore: async (focus) => {
-                    const result = await exploreApp(deps, process.env, {
+                    const result = await exploreApp(deps, harnessEnv, {
                         ...(focus === undefined ? {} : { focus }),
                         ...(opts.sessionId === undefined ? {} : { sessionId: opts.sessionId }),
                     });
@@ -389,16 +396,19 @@ export function expectNeedsDaemonMessage(port, presence) {
         '  • Start a daemon on that port, pointed at the app, then re-run this command: ' +
         `npx @reticlehq/server serve --port ${String(port)} --drive <url>\n` +
         `  • 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.');
+        'a different question, and it proves nothing about your predicate.\n\n' +
+        `  • Once that daemon is running, you can also drive its HTTP MCP transport for anything ` +
+        `${EXPECT_FLAG} cannot do — click, fill, press (${MCP_SSE_PATH}, then ${MCP_MESSAGE_PATH}). ` +
+        'See https://docs.reticle.sh/http-transport.md.');
 }
 /**
- * The model key is set here but not in the daemon, which is where the drive runs. The daemon is
+ * The platform key is set here but not in the daemon, which is what asks the platform. 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)}`);
+    return (`${ReticleEnv.API_KEY} is set in this shell, but the daemon on port ${String(port)} was ` +
+        'started without it, and the daemon is what asks the platform to drive. 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 = {
@@ -485,7 +495,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),
+        cloud: linkedRunsCloudPort(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
@@ -557,8 +567,8 @@ export function handleVerify(parsed) {
                 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.
+                // exported it in this shell and was told to link 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)