@reticlehq/server 3.3.0 → 3.5.0

package/LICENSE-ENTERPRISE

@@ -34,4 +34,4 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-For an Reticle Enterprise subscription: hey@reticle.ai
+For a Reticle Enterprise subscription: hey@reticle.sh

package/README.md

@@ -15,13 +15,13 @@ Point your agent at it. On Claude Code, register it at user scope:
 claude mcp add reticle -s user -- npx @reticlehq/server mcp
 ```
 
-Default tools (18):
+Default tools (10):
 
-`reticle_sessions`, `reticle_snapshot`, `reticle_query`, `reticle_inspect`, `reticle_navigate`, `reticle_act`, `reticle_act_sequence`, `reticle_act_and_wait`, `reticle_observe`, `reticle_wait_for`, `reticle_assert`, `reticle_network`, `reticle_console`, `reticle_state`, `reticle_feedback`, `reticle_session`, `reticle_tools`, `reticle_run`.
+`reticle_navigate`, `reticle_look`, `reticle_act`, `reticle_act_and_wait`, `reticle_observe`, `reticle_assert`, `reticle_session`, `reticle_tools`, `reticle_run`, `reticle_verify`.
 
 Only `reticle_act_and_wait` and `reticle_assert` return a verdict; everything else moves or reads the app.
 
-Another 30 tools ship but are not advertised, to keep the per-turn tool payload small: screenshots and visual diff, saved flows, recording, baselines, clock control, viewport, crawl, coverage, network mocking, leases and more. Reach any of them by name with `reticle_run`, list them with `reticle_tools`, or advertise the whole surface with `RETICLE_ADVERTISE_ALL_TOOLS=1` (this roughly doubles the per-turn tool payload).
+More tools ship but are not advertised, to keep the per-turn tool payload small: screenshots and visual diff, saved flows, recording, baselines, clock control, viewport, crawl, coverage, network mocking, leases and more. Reach any of them by name with `reticle_run`, list them with `reticle_tools`, or advertise the whole surface with `RETICLE_ADVERTISE_ALL_TOOLS=1` (this roughly doubles the per-turn tool payload).
 
 See the [main README](https://github.com/reticlehq/reticle).
 

package/SKILL.md

@@ -21,7 +21,7 @@ curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/inst
 irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex   # Windows
 ```
 
-It registers the MCP server with every agent it can reach; they reopen this client and the tools are there. Do not instead register it yourself and then work around your client not having reloaded: that is the sequence that breaks.
+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:
 
@@ -48,13 +48,13 @@ Everything between here and there is a rule the steps assume. Read it as you go,
 
 **Do not tell the user Reticle is set up until a verdict exists.** The common failure is an agent that writes the config, reports success, and leaves an uninstrumented page. The command then exits non-zero: believe the exit code.
 
-## Setup runs to the end without you
+## Finish the setup steps
 
-**Do not stop, and do not ask the user anything, until their app is running with Reticle inside it and a session is connected.** Everything between here and that point is yours to do: run `init`, fix the wiring it could not, start the dev server, open the browser. None needs a human, and each has been where an onboarding turn died.
+**Finish the setup steps; ask the user only when a step needs their decision.** Running `init`, fixing wiring it could not, starting the dev server and opening the browser are setup steps, not decisions.
 
-Questions the repo already answers, so never ask them: which framework, package manager, port, editor or MCP client, whether to start the dev server, open the browser, or carry on. Decide, act, and say what you did in one line.
+The repo already answers which framework, package manager, port, editor or MCP client, so work those out rather than asking. Say what you did in one line.
 
-There are exactly two places you may stop, and neither is a question about a preference:
+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.
@@ -79,8 +79,6 @@ npx @reticlehq/server feedback --agent --kind <kind> "what happened"
 
 Nothing is too minor. Report defects in **Reticle**; a bug in the app under test is Reticle working, and belongs in your answer. Never put app source, secrets, or user data in a report.
 
-When the person you work with is stuck, offer them a call with the founder (https://calendar.app.google/h9NRDbBBQetyTzWM6) or `npx @reticlehq/server identify --context company --email <theirs>`. Offer it; never book or submit for them.
-
 ## Do not re-read this file to look something up
 
 Fetch the one page that answers the question instead. **Appending `.md` to any docs URL returns its source with no site chrome.**
@@ -112,7 +110,7 @@ You need it once, while setting a project up. If `reticle_session` already lists
 
 # VERIFY
 
-**Only `reticle_act_and_wait` and `reticle_assert` produce a verdict.** Everything else (`act`, `snapshot`, `query`, `navigate`, `observe`, `network`, `console`) moves or reads the app and proves nothing. A drive that ends without one of those two has no result, however many tools it used.
+**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.**
 
@@ -124,10 +122,10 @@ Work down this list and stop at the first row that fits. Do not hand-drive a flo
 | --- | --- | --- |
 | "Did my edit break anything?" | `reticle_verify({ action: "change", files: ["src/App.tsx"] })` | 1 |
 | "Does every saved journey still work?" | `reticle_verify({ action: "flows" })` | 1 |
-| "Does this new behaviour work?" | ONE `reticle_act_and_wait` with `until` | 1 |
+| "Does this new behaviour work?" | `reticle_act_and_wait` on the step that ENDS the journey | 1+ |
 | No MCP available at all | `npx @reticlehq/server verify <url>`, then `gate --since HEAD~1` (below); `verify` has no `--since` | 2, no MCP |
 
-Replay before you drive. A covered journey re-verifies for a few hundred tokens; driving it costs tens of thousands, because driving spends turns and replay spends none.
+Replay before you drive: a covered journey re-verifies for a few hundred tokens, and driving it costs tens of thousands.
 
 `{action:"change"}` answers `unknown` when no saved flow covers your files. Nothing ran, so nothing was proved: drive it yourself, and never read it as a pass. `"no"` names the step that broke and what it found instead, so a regression arrives located. If a locator was RENAMED rather than broken, `{action:"heal"}` rebinds it, re-asserting the saved consequence first and refusing if that stops firing, so it repairs a locator and never an intent.
 
@@ -159,7 +157,7 @@ Whether that flow is worth anything depends on how you drove it. A step keeps a
 
 ## When you do have to drive by hand
 
-Three calls, and the last one is the only one that counts:
+Done means the journey's END is proved. Drive every step your change touches and put the verdict on the step that ends it:
 
 ```
 reticle_session()                                    // connected? if empty, read `why` — it names the fix
@@ -171,7 +169,7 @@ reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "allOf",
 ]}})                                                 // ← the verdict
 ```
 
-Prefer `reticle_act_and_wait({ ref, action, until })`. It names the expected consequence **before** the action, which is the difference between a check and a rationalisation.
+`until` names the consequence **before** the action, which makes it a check. Add `durable: true` when the change should survive a reload.
 
 The advertised surface is deliberately small (`default` 10, `all` 30, the wider one behind `RETICLE_ADVERTISE_ALL_TOOLS=1`), and is not all there is. `reticle_tools` lists EVERY registered tool, `{ names: [...] }` loads full argument grammar, and `reticle_run { tool, args }` calls any of them, advertised or not. A retired name answers with where it went, not "not found".
 
@@ -180,6 +178,6 @@ The advertised surface is deliberately small (`default` 10, `all` 30, the wider
 
 ## When the verdict lands
 
-Report what you drove, what it produced, and the `file:line` for anything broken. Then, once per project and only after a verdict that is not `unknown`, tell the user in one line that Reticle is open source at `https://github.com/reticlehq/reticle` and that a star helps other people find it.
+Report what you drove, what it produced, and the `file:line` for anything broken.
 
-Once, never on a failed or unknown verdict, and never in place of reporting the result.
+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

@@ -17,13 +17,14 @@
  */
 export declare const CHROMIUM_ANTI_THROTTLING_ARGS: readonly ["--disable-background-timer-throttling", "--disable-backgrounding-occluded-windows", "--disable-renderer-backgrounding"];
 /** The options object handed to `chromium.launch` at both launch sites. */
-interface ChromiumLaunchOptions {
+export interface ChromiumLaunchOptions {
     headless: boolean;
     args: string[];
+    /** An installed Chrome/Edge to drive instead of Playwright's own build; absent = the bundled one. */
+    channel?: 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): ChromiumLaunchOptions;
-export {};
+export declare function chromiumLaunchOptions(headless: boolean, channel?: string): ChromiumLaunchOptions;

package/dist/chromium-launch-options.js

@@ -24,6 +24,10 @@ 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) {
-    return { headless, args: [...CHROMIUM_ANTI_THROTTLING_ARGS] };
+export function chromiumLaunchOptions(headless, channel) {
+    return {
+        headless,
+        args: [...CHROMIUM_ANTI_THROTTLING_ARGS],
+        ...(channel === undefined ? {} : { channel }),
+    };
 }

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

@@ -17,3 +17,25 @@ export interface AdhocSuiteOptions {
  * this product exists to prevent.
  */
 export declare function runAdhocSuite(options: AdhocSuiteOptions): Promise<AdhocVerdict>;
+export interface AdhocExploreOptions {
+    port: number;
+    /** The app to explore; opened in a Reticle browser when the daemon has no tab on its origin. */
+    url: string;
+    /** Who to be, or what to accomplish. */
+    persona?: string;
+    token?: string;
+    connect?: (endpoint: URL) => Promise<ToolCaller>;
+    /** The tabs the daemon has connected. See runAdhocVerdict. */
+    sessions: () => Promise<readonly {
+        url: string;
+    }[]>;
+}
+/**
+ * `verify <url> --explore` against the daemon that already owns the port: open the url, let the
+ * daemon's model drive it and record flows, then replay them — the same three steps the path that
+ * boots its own daemon takes, so the exit code means the same thing on both.
+ *
+ * It used to refuse here, and that refusal was the first thing a new user met: `init` leaves its
+ * daemon on the port and then recommends exactly this command as the first run.
+ */
+export declare function runAdhocExplore(options: AdhocExploreOptions): Promise<AdhocVerdict>;

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

@@ -15,9 +15,11 @@
  * is stopped, the agent keeps its link.
  */
 import { ReticleTool } from '@reticlehq/core';
-import { connectOverSse, endpointFor, refusalText, verdictOf, } from './adhoc-verdict.js';
+import { connectOverSse, endpointFor, leaseIfNoTab, releaseLease, refusalText, verdictOf, } from './adhoc-verdict.js';
 /** The only status that is a pass. `unverifiable` means nothing was checked, which is not one. */
 const PASSED = 'pass';
+/** The `reticle_verify` actions this file asks for. */
+const EXPLORE_ACTION = 'explore';
 /**
  * How long a SUITE may take, against the SDK's 60s default for one request.
  *
@@ -52,37 +54,106 @@ export async function runAdhocSuite(options) {
         };
     }
     try {
-        // Spread rather than set: an explicit `undefined` is a key the tools reject as an unknown
-        // parameter, which would turn "no tab named" into a refusal. Same rule as the one-shot path.
-        const result = await caller.call(ReticleTool.VERIFY, {
-            action: 'flows',
-            ...(options.select === undefined ? {} : { select: options.select }),
-            ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }),
-        }, SUITE_TIMEOUT_MS);
-        const refusal = refusalText(result);
-        if (refusal !== undefined)
-            return { code: 1, lines: ['status: unverifiable', refusal] };
-        const report = verdictOf(result, 'status');
-        const status = 'string' === typeof report?.['status'] ? report['status'] : 'unverifiable';
-        const summary = 'string' === typeof report?.['summary'] ? report['summary'] : undefined;
+        return await replaySuite(caller, options);
+    }
+    catch (error) {
+        return {
+            code: 1,
+            lines: [
+                `the suite could not be run: ${error instanceof Error ? error.message : String(error)}`,
+            ],
+        };
+    }
+    finally {
+        await caller.close().catch(() => undefined);
+    }
+}
+/** The saved suite through an open connection, as a verdict. Shared by the suite and explore paths. */
+async function replaySuite(caller, options) {
+    // Spread rather than set: an explicit `undefined` is a key the tools reject as an unknown
+    // parameter, which would turn "no tab named" into a refusal. Same rule as the one-shot path.
+    const result = await caller.call(ReticleTool.VERIFY, {
+        action: 'flows',
+        ...(options.select === undefined ? {} : { select: options.select }),
+        ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }),
+    }, SUITE_TIMEOUT_MS);
+    const refusal = refusalText(result);
+    if (refusal !== undefined)
+        return { code: 1, lines: ['status: unverifiable', refusal] };
+    const report = verdictOf(result, 'status');
+    const status = 'string' === typeof report?.['status'] ? report['status'] : 'unverifiable';
+    const summary = 'string' === typeof report?.['summary'] ? report['summary'] : undefined;
+    return {
+        code: PASSED === status ? 0 : 1,
+        lines: [
+            `status: ${status}`,
+            ...(summary === undefined ? [] : [summary]),
+            JSON.stringify(report ?? result, null, 2),
+        ],
+    };
+}
+/**
+ * `verify <url> --explore` against the daemon that already owns the port: open the url, let the
+ * daemon's model drive it and record flows, then replay them — the same three steps the path that
+ * boots its own daemon takes, so the exit code means the same thing on both.
+ *
+ * It used to refuse here, and that refusal was the first thing a new user met: `init` leaves its
+ * daemon on the port and then recommends exactly this command as the first run.
+ */
+export async function runAdhocExplore(options) {
+    const connect = options.connect ?? connectOverSse;
+    let caller;
+    try {
+        caller = await connect(endpointFor(options.port, options.token));
+    }
+    catch (error) {
         return {
-            code: PASSED === status ? 0 : 1,
+            code: 1,
             lines: [
-                `status: ${status}`,
-                ...(summary === undefined ? [] : [summary]),
-                JSON.stringify(report ?? result, null, 2),
+                `could not reach the daemon on port ${String(options.port)}: ${error instanceof Error ? error.message : String(error)}`,
             ],
         };
     }
+    let leased;
+    try {
+        const opened = await leaseIfNoTab(caller, options.url, options.sessions);
+        if ('failed' in opened)
+            return { code: 1, lines: ['status: unverifiable', ...opened.failed] };
+        leased = opened.leased;
+        const pin = leased === undefined ? {} : { sessionId: leased };
+        const drove = await caller.call(ReticleTool.VERIFY, {
+            action: EXPLORE_ACTION,
+            ...(options.persona === undefined ? {} : { persona: options.persona }),
+            ...pin,
+        }, SUITE_TIMEOUT_MS);
+        const refusal = refusalText(drove);
+        if (refusal !== undefined)
+            return { code: 1, lines: ['status: unverifiable', refusal] };
+        const report = verdictOf(drove, 'savedFlows');
+        const recorded = [report?.['savedFlows'], report?.['rewroteFlows']].flatMap((list) => Array.isArray(list) ? list.filter((name) => 'string' === typeof name) : []);
+        const summary = 'string' === typeof report?.['summary'] ? report['summary'] : undefined;
+        const note = 'string' === typeof report?.['note'] ? report['note'] : undefined;
+        const drive = [
+            ...(summary === undefined ? [] : [summary]),
+            ...(note === undefined ? [] : [note]),
+        ];
+        // A drive that left nothing to replay proved nothing, however long it ran.
+        if (0 === recorded.length)
+            return { code: 1, lines: ['status: unverifiable', ...drive] };
+        const suite = await replaySuite(caller, pin);
+        return { code: suite.code, lines: [...drive, ...suite.lines] };
+    }
     catch (error) {
         return {
             code: 1,
             lines: [
-                `the suite could not be run: ${error instanceof Error ? error.message : String(error)}`,
+                `the explore could not be run: ${error instanceof Error ? error.message : String(error)}`,
             ],
         };
     }
     finally {
+        if (leased !== undefined)
+            await releaseLease(caller, leased);
         await caller.close().catch(() => undefined);
     }
 }

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

@@ -48,7 +48,42 @@ interface AdhocVerdictOptions {
     token?: string;
     /** Injected so a test does not need a live daemon. */
     connect?: (endpoint: URL) => Promise<ToolCaller>;
+    /**
+     * The tabs the daemon has connected, so a url with none on its origin can be opened here rather
+     * than refused. Absent = never lease, which is the old behaviour and what the unit tests that do
+     * not care get.
+     */
+    sessions?: () => Promise<readonly {
+        url: string;
+    }[]>;
 }
+/**
+ * Open `url` in a Reticle-leased browser when the daemon has no tab on its origin.
+ *
+ * `{}` means a tab is already there (drive it); `{ leased }` names the lease this call opened, which
+ * the caller must hand to `releaseLease`; `{ failed }` is the lease's own refusal, as lines to print —
+ * a missing browser, an app that is not up — so nothing is asserted against a page that never opened.
+ */
+export declare function leaseIfNoTab(caller: ToolCaller, url: string, sessions: () => Promise<readonly {
+    url: string;
+}[]>): Promise<{
+    leased?: string;
+    alreadyAt?: boolean;
+} | {
+    failed: string[];
+}>;
+/**
+ * Open `url` in a Reticle-leased browser unconditionally: `{ leased }` names the lease, which the
+ * caller hands to `releaseLease`; `{ failed }` is the lease's own refusal, as lines to print.
+ * `init`'s connect proof on a machine with no system browser takes this path directly.
+ */
+export declare function acquireLease(caller: ToolCaller, url: string): Promise<{
+    leased: string;
+} | {
+    failed: string[];
+}>;
+/** Hand back a lease `leaseIfNoTab` opened. Best-effort: an expired lease is already gone. */
+export declare function releaseLease(caller: ToolCaller, sessionId: string): Promise<void>;
 /** The narrow slice of an MCP client this needs — one call, then close. */
 export interface ToolCaller {
     call(name: string, args: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;

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

@@ -3,6 +3,75 @@ import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { LOOPBACK_HOST, MCP_SSE_PATH } from '@reticlehq/core';
 import { TOKEN_QUERY_PARAM } from '../../portal/bridge/token-auth.js';
 import { ReticleTool } from '@reticlehq/core';
+import { decideOpen } from './launch/cli-launch.js';
+/** The lease tool is reached through `reticle_run`, the route that works on every tool profile. */
+const LeaseAction = { ACQUIRE: 'acquire', RELEASE: 'release' };
+/**
+ * Generous on purpose: on a machine with no Chrome, Edge or Playwright Chromium the FIRST lease
+ * downloads Chromium before it can open anything (see launch-chromium), which outlives the MCP
+ * client's 60s default and would report a timeout for a lease that was about to succeed.
+ */
+const LEASE_TIMEOUT_MS = 300_000;
+const leaseFailedLine = (url) => `could not open ${url} in a Reticle browser, so nothing was checked:`;
+/**
+ * Open `url` in a Reticle-leased browser when the daemon has no tab on its origin.
+ *
+ * `{}` means a tab is already there (drive it); `{ leased }` names the lease this call opened, which
+ * the caller must hand to `releaseLease`; `{ failed }` is the lease's own refusal, as lines to print —
+ * a missing browser, an app that is not up — so nothing is asserted against a page that never opened.
+ */
+export async function leaseIfNoTab(caller, url, sessions) {
+    const open = [...(await sessions())];
+    if ('open' !== decideOpen(open, url).action) {
+        return open.some((s) => sameDocument(s.url, url)) ? { alreadyAt: true } : {};
+    }
+    return acquireLease(caller, url);
+}
+/**
+ * Whether two urls name the same document, ignoring a trailing slash and the hash.
+ *
+ * `verify <url>` navigated a tab already showing that url, which reloads it. In a desktop window
+ * that reload is a disconnect: the assert ran against a session that was gone ~20ms later and
+ * answered `unknown — session disconnected`.
+ */
+function sameDocument(a, b) {
+    try {
+        const x = new URL(a);
+        const y = new URL(b);
+        const path = (u) => u.pathname.replace(/\/+$/, '');
+        return x.origin === y.origin && path(x) === path(y) && x.search === y.search;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Open `url` in a Reticle-leased browser unconditionally: `{ leased }` names the lease, which the
+ * caller hands to `releaseLease`; `{ failed }` is the lease's own refusal, as lines to print.
+ * `init`'s connect proof on a machine with no system browser takes this path directly.
+ */
+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 why = verdictOf(acquired, 'error')?.['error'];
+    return {
+        failed: [
+            leaseFailedLine(url),
+            'string' === typeof why ? why : (refusalText(acquired) ?? JSON.stringify(acquired)),
+        ],
+    };
+}
+/** Hand back a lease `leaseIfNoTab` opened. Best-effort: an expired lease is already gone. */
+export async function releaseLease(caller, sessionId) {
+    await caller
+        .call(ReticleTool.RUN, {
+        tool: ReticleTool.LEASE,
+        args: { action: LeaseAction.RELEASE, sessionId },
+    })
+        .catch(() => undefined);
+}
 /** `verified` is the only field that decides the exit code. Everything else is for the reader. */
 const PROVED = 'yes';
 export function endpointFor(port, token) {
@@ -112,12 +181,28 @@ export async function runAdhocVerdict(options) {
             ],
         };
     }
+    let leased;
     try {
         // Spread rather than set: an explicit `sessionId: undefined` is a key the tools reject as an
         // unknown parameter, which would turn "no tab named" into a refusal.
-        const pin = options.sessionId === undefined ? {} : { sessionId: options.sessionId };
-        if (options.url !== undefined && options.url.length > 0) {
-            await caller.call(ReticleTool.NAVIGATE, { url: options.url, ...pin });
+        const url = options.url !== undefined && options.url.length > 0 ? options.url : undefined;
+        // A url and no tab on its origin: this used to refuse with "open the app first" and name some
+        // OTHER listening port as the one to open. The caller already said which url; open it here, in
+        // a Reticle browser, and hand the lease back when the verdict is in.
+        let alreadyAt = false;
+        if (url !== undefined && options.sessionId === undefined && options.sessions !== undefined) {
+            const opened = await leaseIfNoTab(caller, url, options.sessions);
+            if ('failed' in opened)
+                return { code: 1, lines: ['verified: unknown', ...opened.failed] };
+            leased = opened.leased;
+            alreadyAt = true === opened.alreadyAt;
+        }
+        const aimed = options.sessionId ?? leased;
+        const pin = aimed === undefined ? {} : { sessionId: aimed };
+        // A fresh lease, or a tab already showing this url, is already AT it; navigating again would
+        // only reload the page — and reload a desktop window out from under the assert.
+        if (url !== undefined && leased === undefined && !alreadyAt) {
+            await caller.call(ReticleTool.NAVIGATE, { url, ...pin });
         }
         const result = await caller.call(ReticleTool.ASSERT, { predicate: options.predicate, ...pin });
         const refusal = refusalText(result);
@@ -147,6 +232,8 @@ export async function runAdhocVerdict(options) {
         };
     }
     finally {
+        if (leased !== undefined)
+            await releaseLease(caller, leased);
         await caller.close().catch(() => undefined);
     }
 }

package/dist/command/cli/answers/gate-hook-message.d.ts

@@ -21,6 +21,12 @@ interface GateHookInput {
     downgraded: readonly string[];
     /** Flows whose coverage was deleted while their files changed. */
     deleted: readonly string[];
+    /** Changed interactive components no saved flow has ever driven. */
+    unflowed?: readonly string[];
+    /** Coverage levels below their best, already worded (`branched 100% -> 50%`). */
+    coverageRegressed?: readonly string[];
+    /** Changed files the browser loaded and never ran a function of. */
+    unexecuted?: readonly string[];
 }
 /**
  * The message, or undefined when there is nothing to say.

package/dist/command/cli/answers/gate-hook-message.js

@@ -37,6 +37,12 @@ export function gateHookMessage(exit, input) {
         lines.push(`  assertions weakened to something fakeable: ${name(input.downgraded)} — a check that cannot fail is not a check`);
     if (input.deleted.length > 0)
         lines.push(`  coverage deleted while its files changed: ${name(input.deleted)}`);
+    if (input.unflowed !== undefined && input.unflowed.length > 0)
+        lines.push(`  changed, and no saved flow drives it: ${name(input.unflowed)} — drive it with reticle_act_and_wait and a declared \`until\``);
+    if (input.coverageRegressed !== undefined && input.coverageRegressed.length > 0)
+        lines.push(`  coverage fell: ${name(input.coverageRegressed)} — something new is uncovered; reticle_verify { action: "crawl", exhaustive: true } names it. If the drop was intended, \`reticle gate --accept-coverage\` records it`);
+    if (input.unexecuted !== undefined && input.unexecuted.length > 0)
+        lines.push(`  changed, and no drive ever ran it: ${name(input.unexecuted)}`);
     if (input.quarantined.length > 0)
         lines.push(`  held back as flaky, so proving nothing: ${name(input.quarantined)}`);
     lines.push('');

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

@@ -33,6 +33,4 @@ interface CredentialWrite {
  * re-link, and refusing it would strand the repo.
  */
 export declare const applyCredential: (store: Record<string, unknown>, write: CredentialWrite) => Record<string, unknown>;
-/** Where the store lives, given the reticle home directory. */
-export declare const credentialsPath: (homeDir: string, file: string) => string;
 export {};

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

@@ -14,7 +14,6 @@
  * two are kept readable (a repo linked by an older CLI must not lose its key) and written only when
  * doing so cannot mislead somebody else.
  */
-import { join } from 'node:path';
 import { credentialSlot } from '../../../memory/cloud/cloud-config.js';
 /** Trailing slashes are not identity: `https://x/` and `https://x` are one cloud. */
 const normalizeUrl = (url) => url.replace(/\/+$/, '');
@@ -93,5 +92,3 @@ export const applyCredential = (store, write) => {
         store[projectId] = { key, url };
     return store;
 };
-/** Where the store lives, given the reticle home directory. */
-export const credentialsPath = (homeDir, file) => join(homeDir, file);

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

@@ -18,16 +18,20 @@ declare const SessionSchema: z.ZodObject<{
      * is ours" and mints, which is the safe direction.
      */
     orgId: z.ZodOptional<z.ZodString>;
+    /** 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;
     orgId?: string | undefined;
+    email?: string | undefined;
 }, {
-    url: string;
     token: string;
+    url: string;
     orgName: string;
     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/cloud-session.js

@@ -19,6 +19,8 @@ const SessionSchema = z.object({
      * is ours" and mints, which is the safe direction.
      */
     orgId: z.string().optional(),
+    /** Who signed in. Absent in sessions written before it was recorded. */
+    email: z.string().optional(),
 });
 /** Trailing slashes are not identity: `https://x/` and `https://x` are one host. */
 export const normalizeUrl = (url) => url.replace(/\/+$/, '');

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

@@ -11,11 +11,12 @@ import { projectWiringLine } from './doctor/doctor-project-line.js';
 import { hasProjectConnectedBefore } from '../../memory/recall/prior/connection-memory.js';
 import { sessionsLine } from './doctor/doctor-sessions-line.js';
 import { captureLookup, describeForeignHolder, findPortHolder } from './ports/port-holder.js';
-import { chromiumHint, probeChromium } from './doctor/browser/chromium-hint.js';
+import { chromiumHint } from './doctor/browser/chromium-hint.js';
+import { probeChromiumWithFallback } from '../../launch-chromium.js';
 import { SERVER_VERSION } from '../version/identity/server-version.js';
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
-import { CspBasis, diagnoseDesktop, diagnoseObservedWebCsp, diagnoseWebCsp, isDesktopProject, resolveWebCspFindings, } from '@reticlehq/init';
-import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectId, readProjectPort, } from './ports/resolve/cli-port.js';
+import { CspBasis, diagnoseDesktop, diagnoseObservedWebCsp, diagnoseWebCsp, isDesktopProject, resolveWebCspFindings, webCspOptionsFor, } from '@reticlehq/init';
+import { RETICLE_CONFIG_BASENAME, diagnosePortMismatch, readProjectFramework, readProjectId, readProjectPort, } from './ports/resolve/cli-port.js';
 import { DoctorRow, doctorRow } from './doctor/doctor-rows.js';
 import { attachState, describeAttachState } from '../../surface/mcp/attach-memory.js';
 import { findOccupiedSiblings, siblingListenerNote } from './ports/sibling-ports.js';
@@ -68,7 +69,7 @@ export async function handleDoctor(port) {
     // the branches below already say so in their own terms.
     let sessions;
     let daemonStatus;
-    line(doctorRow(DoctorRow.CHROMIUM, chromiumHint(await probeChromium())));
+    line(doctorRow(DoctorRow.CHROMIUM, chromiumHint(await probeChromiumWithFallback())));
     // Ask the PORT, not just the pid file. "not running on :4400" has been printed about a port that
     // was demonstrably occupied, which sends the reader to start a daemon that cannot bind. The three
     // states are genuinely different problems with different fixes, so doctor names which one it is.
@@ -201,7 +202,8 @@ export async function handleDoctor(port) {
         : observedDocuments.flatMap((document) => diagnoseObservedWebCsp(document, port));
     const connected = hasConnectedDocument(summarizeStatus(daemonStatus).sessions, devServers.map((server) => server.url), projectId);
     const csp = resolveWebCspFindings({
-        predicted: diagnoseWebCsp(readProjectFile, port),
+        // With the wiring `init` recorded, so the two commands name the same rule for one policy.
+        predicted: diagnoseWebCsp(readProjectFile, port, [], webCspOptionsFor(readProjectFramework(process.cwd()))),
         ...(observedCsp === undefined ? {} : { observed: observedCsp }),
         connected,
     });

package/dist/command/cli/cli-flow-commands.d.ts

@@ -37,11 +37,8 @@ export declare function handleWatch(): void;
  * failing reproduction plus the consequence that should have held; replay one with reticle_flow_replay.
  */
 export declare function handleCapsules(): Promise<void>;
-/**
- * `reticle gate <file...>` — exit non-zero unless passing artifacts cover the flows affected by the
- * 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).
- */
 export declare function handleGate(files: string[], since: string | undefined, 
 /** Hook mode: prose for a human, and silence when there was simply nothing to check. */
-hook?: boolean): Promise<void>;
+hook?: boolean, 
+/** Accept today's coverage levels as the best before judging, for a drop that was intended. */
+acceptCoverage?: boolean): Promise<void>;