@reticlehq/server 3.9.0 → 3.10.0

package/SKILL.md

@@ -2,30 +2,31 @@
 
 Reticle is the proof layer for AI coding agents. A dev-only SDK inside the user's running app gives you `reticle_*` MCP tools that read the DOM, network, routing, console and framework state. You act on the real app and get a verdict: `yes`, `no`, or `unknown` (could not tell), with evidence and the `file:line` to open. No screenshots: it drives the tab the user already has open.
 
-**Your first goal: one real verdict in the user's app.** Do the three steps in order. Do not stop to explain Reticle first.
+**Your first goal: one real verdict in the user's app.** Do the steps in order. Do not stop to explain Reticle first.
 
-## 1. Install (once per machine)
+## 1. Check the app, with nothing installed
 
-**`reticle_*` tools visible?** Go to step 2.
+**`reticle_*` tools visible?** Call `reticle_session { action: "list" }`. It changes no file. On a wired project, go to step 3. On a project that is not wired, its `next_step` names the zero-install lease and asks the consent question for `init`.
 
-**Not visible?** Hand the user one line for a terminal, outside this client, and stop:
+**No tools, or an app with no `.reticle.json`?** Run this in the app's folder. It changes no file:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.sh | sh
-irm https://raw.githubusercontent.com/reticlehq/reticle/main/install/install.ps1 | iex   # Windows
+npx @reticlehq/server@latest
 ```
 
-It registers Reticle with every coding agent it finds and prints the next steps: restart the agent (a client loads MCP servers only at start, so a prompt cannot replace this command), then paste the prompt it printed. Do not register the server yourself and work around your client not having reloaded. If your client did register mid-session, `npx @reticlehq/server init --relaunch` prints the command that resumes this conversation with the tools.
+It starts the dev server if the app does not run, opens the app in a Reticle browser and checks it: the page loads, no console error, no failed request, and each same-origin link opens. It prints `verified: yes` or `verified: no` with each fault. Show the user that verdict, then offer `init`.
 
 ## 2. Wire this app (once per project)
 
-In the project, call `reticle_session { action: "list" }`. It changes no file. On a project that is not wired, its `next_step` asks the consent question for `init`. When an app is running, it also names the zero-install lease, which checks that app now with nothing installed. `init` changes files, so run it only when the user agrees. A request to set up Reticle is that agreement. Run it in the app's folder:
+`init` changes files, so run it only when the user agrees. A request to set up Reticle is that agreement. Run it in the app's folder:
 
 ```bash
 RETICLE_INSTALL_SOURCE=skill_file npx @reticlehq/server@latest init
 ```
 
-A dev server that was running when `init` ran must be restarted once. If `init` cannot finish alone, read SETUP below.
+It registers Reticle with every coding agent it finds. A dev server that was running when `init` ran must be restarted once. If `init` cannot finish alone, read SETUP below.
+
+**Still no `reticle_*` tools?** A client loads MCP servers only at start, so a prompt cannot add them. `npx @reticlehq/server init --relaunch` prints the command that resumes this conversation with the tools. Else ask the user to restart the agent. Do not register the server yourself and work around your client not having reloaded.
 
 ## 3. Prove one flow
 
@@ -76,7 +77,7 @@ The advertised surface is deliberately small (`default` 10, `all` 30). `RETICLE_
 | `reticle_verify` | replay, coverage, Harness | `action`: `change` `flows` `affected` `coverage` `crawl` `explore` `mutate` `heal` |
 | `reticle_tools` / `reticle_run` | everything else (below) | `names`; `tool`, `args` |
 
-Actions: `click` `dblclick` `hover` `focus` `blur` `fill` `type` `clear` `select` `check` `uncheck` `submit` `press` `upload` `scrollIntoView` `scroll` `drag` `tap` `zoom`. `args`: `{ value }` for fill/select, `{ text: "Enter" }` for press, `{ toRef }` for drag, `{ path }` for upload, `{ native: true }` for a trusted click. A control whose label reads as destructive is refused until you pass `args.confirmDangerous: true`, and only do that when the user asked for it.
+Actions: `click` `dblclick` `hover` `focus` `blur` `fill` `type` `clear` `select` `check` `uncheck` `submit` `press` `upload` `scrollIntoView` `scroll` `drag` `tap` `zoom` `insertText`. `args`: `{ value }` for fill/select, `{ text: "Enter" }` for press, `{ toRef }` for drag, `{ path }` for upload, `{ native: true }` for a trusted click. `insertText` takes `{ text }` and types into a contenteditable/Tiptap/ProseMirror editor, where `fill` and `type` are refused. A control whose label reads as destructive is refused until you pass `args.confirmDangerous: true`, and only do that when the user asked for it.
 
 Beyond the advertised set, one hop each:
 
@@ -94,7 +95,7 @@ Every `until`, `predicate` and `expect` is `{ kind, ...fields }`; unknown fields
 
 | kind | fields |
 | --- | --- |
-| `element` | `query: { testid \| role+name \| text \| label \| placeholder \| alt \| component, scope? }`, `state?`: `visible` `hidden` `enabled` `disabled` `checked` `expanded` `pressed` `focused` `present` `inViewport`, `absent?` |
+| `element` | `query: { testid \| role+name \| text \| label \| placeholder \| alt \| component, scope? }`, `state?`: `visible` `hidden` `enabled` `disabled` `checked` `expanded` `pressed` `focused` `present` `inViewport` `receivesPointer`, `absent?` |
 | `text` | `contains`, `scope?`, `visible?`, `absent?`, `ignoreCase?`, `satisfies?` |
 | `net` | `method`, `urlContains`, `status`, `ok`, `count` (exact; omit = ≥1; 0 = never), `bodyContains`, `bodyMatches`, `requestBodyMatches`, `repeatable` |
 | `route` | `pathname` or `contains` |
@@ -104,7 +105,7 @@ Every `until`, `predicate` and `expect` is `{ kind, ...fields }`; unknown fields
 | `settled` / `animation` / `compare` | `quietMs`, `channel?` / `name`, `completed` / `left`, `right`, `as` |
 | `allOf` / `anyOf` / `not` | `predicates: [...]` / `predicates: [...]` / `predicate` |
 
-`satisfies` asserts a property when the exact value varies: `nonEmpty`, `oneOf`, `withinTolerance`, `matchesPattern`, `type`, `changed`, `unchanged`, `increased`, `decreased`. Composites hold only predicates: `absent` belongs inside a child, and an `element` takes a `query`, never a `ref`. A bare `route` or `state` is already true before the action and proves nothing; pair it with what the action causes.
+`satisfies` asserts a property when the exact value varies: `nonEmpty`, `oneOf`, `withinTolerance`, `matchesPattern`, `type`, `changed`, `unchanged`, `increased`, `decreased`. Composites hold only predicates: `absent` belongs inside a child, and an `element` takes a `query`, never a `ref`. A bare `route` or `state` is already true before the action and proves nothing; pair it with what the action causes. `absent` means not in the DOM; to say a thing is not shown, add `visible: true`. Assert what the requirement names, not a label you saw: another correct build can name it differently.
 
 ## Feedback is first-class
 

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

@@ -101,6 +101,8 @@ async function replaySuite(caller, options) {
         ...(options.select === undefined ? {} : { labels: options.select }),
         ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }),
         ...(true === options.confirmDangerous ? { confirmDangerous: true } : {}),
+        // The CLI waits as long as its own timeout, not the MCP default of 240 s, which is there for clients that give up at about 300 s.
+        budgetMs: SUITE_TIMEOUT_MS,
         // The running daemon's environment is not this command's: the secrets a CI step set for
         // `reticle verify` go with the call, for this call only.
         ...secretsArg(process.env),

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

@@ -1,3 +1,5 @@
+import { type ToolCaller } from './daemon-link/daemon-client.js';
+export { acquireLease, connectOverSse, endpointFor, refusalText, releaseLease, verdictOf, type ToolCaller, } from './daemon-link/daemon-client.js';
 /**
  * A verdict from the CLI, against the daemon that is already running.
  *
@@ -83,54 +85,12 @@ root?: string): Promise<{
 } | {
     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, 
-/** Open it in a window somebody can watch, whatever the daemon was started as. */
-headed?: boolean, 
-/** The `.reticle` the lease's runs belong in: the caller's project, not wherever the page resolves. */
-root?: string): Promise<{
-    leased: string;
-    zeroInstall: boolean;
-} | {
-    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 longest one `reticle_assert` call waits: its `timeout_ms` cap, one MCP request less slack.
  * Named here rather than imported, because this directory does not reach the tool layer; pinned
  * equal to `MAX_BLOCKING_WAIT_MS` by adhoc-verdict.test.ts so the two cannot drift apart.
  */
 export declare const ASSERT_MAX_WAIT_MS = 55000;
-/** 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>;
-    close(): Promise<void>;
-}
-export declare function endpointFor(port: number, token: string | undefined): URL;
-export declare function connectOverSse(endpoint: URL): Promise<ToolCaller>;
-/**
- * The report object an MCP tool result carries, or undefined when the shape is not one.
- *
- * `field` is the key that makes a payload the report this caller wants: `verified` for a one-shot
- * verdict, `status` for a suite. It is a parameter rather than a fixed name because the suite path
- * reproduced this function's own incident the moment it reused it — the headline printed
- * `unverifiable` while the JSON under it said `"status":"fail"` with 74 failing flows, because a
- * suite report has no `verified` key and the text reader would only accept one that did.
- */
-export declare function verdictOf(result: unknown, field?: string): Record<string, unknown> | undefined;
-/**
- * The tool's own words when it refused, rather than the envelope carrying them.
- *
- * A refusal from these tools is the most useful text they produce — it names the cause and the next
- * action — and printing the MCP result object around it buries that in JSON escaping. The reader is
- * at a terminal; give them the sentence.
- */
-export declare function refusalText(result: unknown): string | undefined;
 /**
  * Navigate (optionally) and assert, against the daemon already on this port.
  *
@@ -146,4 +106,3 @@ export declare function runAdhocVerdict(options: AdhocVerdictOptions): Promise<A
  * caller that wants the finished report asks again by `runId` rather than starting a second drive.
  */
 export declare function exploreToEnd(caller: ToolCaller, args: Record<string, unknown>, budgetMs: number, now?: () => number): Promise<unknown>;
-export {};

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

@@ -1,30 +1,8 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { CLI_CLIENT_NAME } from '../../judgement/runs/verification-sync.js';
-import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
-import { DEFAULT_ASSERT_TIMEOUT_MS, LOOPBACK_HOST, MCP_SSE_PATH } from '@reticlehq/core';
-import { TOKEN_QUERY_PARAM } from '../../portal/bridge/token-auth.js';
-import { ReticleTool, asString as asText } from '@reticlehq/core';
+import { DEFAULT_ASSERT_TIMEOUT_MS, ReticleTool, asString as asText } from '@reticlehq/core';
 import { decideOpen } from './launch/cli-launch.js';
-import { LEASE_KEPT_SENTENCE, LEASE_RELEASED_SENTENCE } from '../../surface/tools/lease-hint.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:`;
-/**
- * Why a lease's tab is not ready: its `notReadyReason`, then its `hint`, when it gave them. The CLI
- * released the lease, so the hint's kept-lease sentence becomes the released-lease sentence.
- */
-function notReadyLine(report) {
-    const reason = asText(report?.['notReadyReason']);
-    const hint = asText(report?.['hint'])?.replace(LEASE_KEPT_SENTENCE, LEASE_RELEASED_SENTENCE);
-    const head = reason === undefined ? 'the tab did not connect.' : `the tab did not connect (${reason}).`;
-    return hint === undefined ? head : `${head} ${hint}`;
-}
+import { acquireLease, connectOverSse, endpointFor, refusalText, releaseLease, verdictOf, } from './daemon-link/daemon-client.js';
+// Re-exported so every existing importer of the daemon link through this file is unaffected.
+export { acquireLease, connectOverSse, endpointFor, refusalText, releaseLease, verdictOf, } from './daemon-link/daemon-client.js';
 /**
  * Open `url` in a Reticle-leased browser when the daemon has no tab on its origin.
  *
@@ -75,64 +53,6 @@ function sameDocument(a, b) {
         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, 
-/** Open it in a window somebody can watch, whatever the daemon was started as. */
-headed, 
-/** The `.reticle` the lease's runs belong in: the caller's project, not wherever the page resolves. */
-root) {
-    const ask = (withRoot) => caller.call(ReticleTool.RUN, {
-        tool: ReticleTool.LEASE,
-        args: {
-            action: LeaseAction.ACQUIRE,
-            url,
-            ...(true === headed ? { headed } : {}),
-            ...(withRoot && root !== undefined ? { root } : {}),
-        },
-    }, LEASE_TIMEOUT_MS);
-    let acquired = await ask(true);
-    // A daemon from an older release does not know `root` and refuses the whole call, so the page
-    // was never opened. Ask once more without it: the lease works, only its runs land where that
-    // daemon puts them.
-    if (root !== undefined && REFUSES_ROOT.test(refusalOf(acquired) ?? '')) {
-        acquired = await ask(false);
-    }
-    const report = verdictOf(acquired, 'sessionId');
-    const sessionId = report?.['sessionId'];
-    // `ready: false` still carries a sessionId, but no session is registered under it. Driving it
-    // answered "names no session" and hid the cause the lease gave. Only an explicit false counts.
-    if ('string' === typeof sessionId && false === report?.['ready']) {
-        await releaseLease(caller, sessionId);
-        return { failed: [leaseFailedLine(url), notReadyLine(report)] };
-    }
-    // `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'] };
-    }
-    return {
-        failed: [leaseFailedLine(url), refusalOf(acquired) ?? JSON.stringify(acquired)],
-    };
-}
-/** The lease refusal an older daemon answers when it does not know the `root` argument. */
-const REFUSES_ROOT = /unknown parameter[^\n]*\broot\b/i;
-/** What the lease said no with: the `error` of its payload, else the refusal text. */
-function refusalOf(acquired) {
-    const why = verdictOf(acquired, 'error')?.['error'];
-    return 'string' === typeof why ? why : refusalText(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);
-}
 /** How long `--expect` waits without a `--timeout`: the wait form's own default. */
 const DEFAULT_EXPECT_WAIT_MS = DEFAULT_ASSERT_TIMEOUT_MS;
 /** Room for the daemon to answer after the wait it was given has run out. */
@@ -152,31 +72,55 @@ function runRefusal(result) {
     const said = verdictOf(result, 'error')?.['error'];
     return refusalText(result) ?? ('string' === typeof said ? said : undefined);
 }
+/** The `reticle_assert` action that waits for a predicate within a budget. */
+const ASSERT_WAIT_ACTION = 'wait';
+/**
+ * The refusal of a daemon whose `reticle_assert` takes no `action`: every surface but the merged
+ * one, where `reticle_wait_for` is still a tool of its own.
+ */
+const REFUSES_ACTION = /unknown parameter[^\n]*\baction\b/i;
+/**
+ * One wait for the predicate, through `reticle_assert { action: "wait" }` (#2144).
+ *
+ * It went through `reticle_run { tool: "reticle_wait_for" }`. That name was merged into
+ * `reticle_assert`, and a 3.9.0 daemon answered it with "reticle_wait_for was merged into
+ * reticle_assert", so every `--expect` with a long `--timeout` printed `verified: unknown`. A daemon
+ * whose `reticle_assert` takes no action still has `reticle_wait_for` as a tool, so that is the
+ * one place the name is still used.
+ */
+async function waitOnce(caller, args, timeoutMs) {
+    const waited = await caller.call(ReticleTool.ASSERT, { action: ASSERT_WAIT_ACTION, ...args }, timeoutMs);
+    const refused = runRefusal(waited);
+    if (refused === undefined || !REFUSES_ACTION.test(refused)) {
+        return waited;
+    }
+    return caller.call(ReticleTool.RUN, { tool: ReticleTool.WAIT_FOR, args }, timeoutMs);
+}
 /**
  * Wait for the expectation, then grade it with ONE `reticle_assert` (#1533).
  *
- * The grade is `reticle_assert`'s, never the wait's: it journals, captures the assertion, and
- * carries `verifiedReason`, contradictions and coverage, which `reticle_wait_for` does not.
- * `reticle_assert` already waits when `timeout_ms > 0`, up to one request. A longer budget spends
- * the part one assert cannot hold in `reticle_wait_for` first, through `reticle_run` (the route
- * every tool profile has), following `resume_ms`, and then asserts. No `since` is passed by
- * either: both default to the same last-act cursor, and nothing here acts in between.
+ * The grade is the final `reticle_assert`'s: it journals, captures the assertion, and carries
+ * `verifiedReason`, contradictions and coverage. `reticle_assert` already waits when
+ * `timeout_ms > 0`, up to one request. A longer budget spends the part one assert cannot hold in
+ * `reticle_assert { action: "wait" }` first, following `resume_ms`, and then asserts. No `since` is
+ * passed by either: both default to the same last-act cursor, and nothing here acts in between.
  */
 async function waitForExpectation(caller, predicate, pin, timeoutMs) {
     const budget = Math.max(0, timeoutMs ?? DEFAULT_EXPECT_WAIT_MS);
     let settle = budget - ASSERT_MAX_WAIT_MS;
     while (0 < settle) {
-        const waited = await caller.call(ReticleTool.RUN, { tool: ReticleTool.WAIT_FOR, args: { predicate, timeout_ms: settle, ...pin } }, 
-        // The daemon blocks no longer than one request allows and answers resume_ms past that, so
-        // the budget plus slack always outlasts the call.
-        settle + WAIT_CALL_SLACK_MS);
+        // The daemon blocks no longer than one request allows and answers resume_ms past that, so the
+        // budget plus slack always outlasts the call.
+        const waited = await waitOnce(caller, { predicate, timeout_ms: settle, ...pin }, settle + WAIT_CALL_SLACK_MS);
         const refused = runRefusal(waited);
-        if (refused !== undefined)
+        if (refused !== undefined) {
             return { refused };
-        // By `pass`, which every wait answers with: a "not yet" carries no `verified`.
-        const report = verdictOf(waited, 'pass');
+        }
+        // In the shape `reticle_assert` answers: a final answer carries `verified`, and only a wait
+        // that the per-call cap stopped carries `resume_ms` without one.
+        const report = verdictOf(waited, 'resume_ms');
         const resume = report?.['resume_ms'];
-        if (true === report?.['pass'] ||
+        if (report?.['verified'] !== undefined ||
             'number' !== typeof resume ||
             resume <= 0 ||
             resume >= settle) {
@@ -191,91 +135,6 @@ async function waitForExpectation(caller, predicate, pin, timeoutMs) {
 }
 /** `verified` is the only field that decides the exit code. Everything else is for the reader. */
 const PROVED = 'yes';
-export function endpointFor(port, token) {
-    const url = new URL(`http://${LOOPBACK_HOST}:${String(port)}${MCP_SSE_PATH}`);
-    if (token !== undefined && token.length > 0)
-        url.searchParams.set(TOKEN_QUERY_PARAM, token);
-    return url;
-}
-export async function connectOverSse(endpoint) {
-    const client = new Client({ name: CLI_CLIENT_NAME, version: '1' }, { capabilities: {} });
-    await client.connect(new SSEClientTransport(endpoint));
-    return {
-        call: async (name, args, timeoutMs) => await client.callTool({ name, arguments: args }, undefined, timeoutMs === undefined ? undefined : { timeout: timeoutMs }),
-        close: async () => {
-            await client.close();
-        },
-    };
-}
-/**
- * The report object an MCP tool result carries, or undefined when the shape is not one.
- *
- * `field` is the key that makes a payload the report this caller wants: `verified` for a one-shot
- * verdict, `status` for a suite. It is a parameter rather than a fixed name because the suite path
- * reproduced this function's own incident the moment it reused it — the headline printed
- * `unverifiable` while the JSON under it said `"status":"fail"` with 74 failing flows, because a
- * suite report has no `verified` key and the text reader would only accept one that did.
- */
-export function verdictOf(result, field = 'verified') {
-    const structured = result?.structuredContent;
-    if ('object' === typeof structured && null !== structured) {
-        return structured;
-    }
-    // A daemon that answers with the verdict as TEXT left this undefined, so the headline read
-    // `verified: unknown` while the JSON printed underneath it said `"verified":"no"` — one response
-    // giving two answers to the same question. The text is the same object, so read it.
-    return verdictFromText(result, field);
-}
-/** The report object inside an MCP text part, when the result carried it there instead. */
-function verdictFromText(result, field) {
-    const content = result?.content;
-    if (!Array.isArray(content))
-        return undefined;
-    for (const part of content) {
-        const text = part.text;
-        if ('string' !== typeof text)
-            continue;
-        try {
-            const parsed = JSON.parse(text);
-            // Only a shape that actually carries a verdict — anything else stays `unknown`, which is the
-            // honest answer for a result this function could not read.
-            if ('object' === typeof parsed && null !== parsed && field in parsed) {
-                return parsed;
-            }
-        }
-        catch {
-            /* Not JSON; the next part may still be. */
-        }
-    }
-    return undefined;
-}
-/**
- * The tool's own words when it refused, rather than the envelope carrying them.
- *
- * A refusal from these tools is the most useful text they produce — it names the cause and the next
- * action — and printing the MCP result object around it buries that in JSON escaping. The reader is
- * at a terminal; give them the sentence.
- */
-export function refusalText(result) {
-    const r = result;
-    if (true !== r?.isError || !Array.isArray(r.content))
-        return undefined;
-    const text = r.content
-        .map((part) => part.text)
-        .filter((t) => 'string' === typeof t)
-        .join('\n');
-    if (0 === text.length)
-        return undefined;
-    // The tools answer with a JSON envelope whose `error` is the sentence; unwrap when it is one.
-    try {
-        const parsed = JSON.parse(text);
-        const inner = parsed?.error;
-        return 'string' === typeof inner ? inner : text;
-    }
-    catch {
-        return text;
-    }
-}
 /**
  * Navigate (optionally) and assert, against the daemon already on this port.
  *
@@ -315,8 +174,9 @@ export async function runAdhocVerdict(options) {
         }
         if (url !== undefined && options.sessionId === undefined && options.sessions !== undefined) {
             const opened = await leaseIfNoTab(caller, url, options.sessions, options.root);
-            if ('failed' in opened)
+            if ('failed' in opened) {
                 return { code: 1, lines: ['verified: unknown', ...opened.failed] };
+            }
             leased = opened.leased;
             alreadyAt = true === opened.alreadyAt;
         }
@@ -328,8 +188,9 @@ export async function runAdhocVerdict(options) {
             await caller.call(ReticleTool.NAVIGATE, { url, ...pin });
         }
         const waited = await waitForExpectation(caller, options.predicate, pin, options.timeoutMs);
-        if ('refused' in waited)
+        if ('refused' in waited) {
             return { code: 1, lines: ['verified: unknown', waited.refused] };
+        }
         const result = waited.result;
         const refusal = refusalText(result);
         if (refusal !== undefined) {
@@ -357,8 +218,9 @@ export async function runAdhocVerdict(options) {
         };
     }
     finally {
-        if (leased !== undefined)
+        if (leased !== undefined) {
             await releaseLease(caller, leased);
+        }
         await caller.close().catch(() => undefined);
     }
 }
@@ -384,8 +246,9 @@ export async function exploreToEnd(caller, args, budgetMs, now = Date.now) {
     for (;;) {
         const report = verdictOf(result, 'status');
         const runId = report?.['runId'];
-        if (DRIVE_RUNNING !== report?.['status'] || 'string' !== typeof runId || now() >= deadline)
+        if (DRIVE_RUNNING !== report?.['status'] || 'string' !== typeof runId || now() >= deadline) {
             return result;
+        }
         result = await ask({ runId });
     }
 }

package/dist/command/cli/answers/mcp-connection-hint.d.ts

@@ -0,0 +1,2 @@
+/** The same connection hint for a running daemon in `status` and `doctor`. */
+export declare function mcpConnectionHint(port: number): string;

package/dist/command/cli/answers/mcp-connection-hint.js

@@ -0,0 +1,6 @@
+import { LOOPBACK_HOST, MCP_SSE_PATH } from '@reticlehq/core';
+const MCP_CONNECTION_HINT = 'If your agent has no reticle_* tools, connect over HTTP/SSE at';
+/** The same connection hint for a running daemon in `status` and `doctor`. */
+export function mcpConnectionHint(port) {
+    return `${MCP_CONNECTION_HINT} http://${LOOPBACK_HOST}:${String(port)}${MCP_SSE_PATH}`;
+}

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

@@ -73,7 +73,7 @@ function asIdentity(payload) {
  */
 function splitBrainLine(port, projectId) {
     const home = reticleStateHome();
-    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)));
+    const elsewhere = splitBrainNote(port, daemonsServingProjectElsewhere(projectId, port, home, isAlive, (other) => hasProjectConnectedBefore(home, other, projectId)), { projectId, home });
     return elsewhere ?? wrongDaemonNote(port, resolveDaemonForProject(projectId, home, isAlive));
 }
 const writeLine = (s) => {

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

@@ -13,6 +13,7 @@ import { changedFilesSince } from '../../language/flows/change/git-changed.js';
 import { isAbsolute, join, sep } from 'node:path';
 import { ReticleDir } from '@reticlehq/core';
 import { FlowStore } from '../../language/flows/flows.js';
+import { namedFlowsIn } from '../../language/flows/flow-store-for-session.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';
@@ -54,15 +55,7 @@ export async function resolveChangedFiles(files, since, cwd) {
  * confident negative about somebody else's project, which is worse than an error.
  */
 export async function loadNamedFlows(fs, reticleRoot, projectId) {
-    const store = new FlowStore(fs, reticleRoot, { now: () => Date.now() });
-    const flows = [];
-    for (const name of await store.list(projectId)) {
-        const loaded = await store.load(name, projectId);
-        if (loaded.ok) {
-            flows.push({ name: loaded.value.name, steps: loaded.value.steps });
-        }
-    }
-    return flows;
+    return await namedFlowsIn(new FlowStore(fs, reticleRoot, { now: () => Date.now() }), projectId);
 }
 /**
  * `reticle gate <file...>` — exit non-zero unless passing artifacts cover the flows affected by the

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

@@ -69,7 +69,7 @@ export function planKill(input) {
         holder: listener,
         reason: `pid ${String(listener.pid)} ("${listener.command}") is listening, and it is not a Reticle ` +
             `daemon — it never answered /status and it is not the pid Reticle recorded. Killing it would ` +
-            `be killing someone else's process. If that is what you meant, \`reticle restart ${FORCE_FLAG}\` ` +
+            `be killing someone else's process. If that is what you meant, \`reticle serve --restart ${FORCE_FLAG}\` ` +
             `stops it and starts Reticle there (\`stop ${FORCE_FLAG}\` never does); or start Reticle on ` +
             `another port.`,
     };

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

@@ -0,0 +1,22 @@
+/**
+ * `reticle compare <reference-url> <candidate-url> [--base <url>] [--state <file>] [--json] [--report <file>]`. The
+ * command has one recipe. `--state` names the app's stored data to read, and `--port` names the
+ * daemon, as on every command that uses one.
+ *
+ * Split out of `cli-parse.ts` when that file came near the 1000-line cap.
+ */
+import { type ParseError } from './cli-parse-grammar.js';
+export declare const COMPARE_COMMAND = "compare";
+export type CompareArgs = {
+    kind: 'ok';
+    reference: string;
+    candidate: string;
+    base?: string;
+    /** The path of the state sources file. */
+    state?: string;
+    /** Where to write the HTML report. */
+    report?: string;
+    json: boolean;
+    port: number;
+} | ParseError;
+export declare function parseCompareArgs(args: readonly string[], defaultPort: number): CompareArgs;

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

@@ -0,0 +1,75 @@
+/**
+ * `reticle compare <reference-url> <candidate-url> [--base <url>] [--state <file>] [--json] [--report <file>]`. The
+ * command has one recipe. `--state` names the app's stored data to read, and `--port` names the
+ * daemon, as on every command that uses one.
+ *
+ * Split out of `cli-parse.ts` when that file came near the 1000-line cap.
+ */
+import { JSON_FLAG, PORT_FLAG, missingOperand, missingValue, notANumber, unknownArgument, } from './cli-parse-grammar.js';
+export const COMPARE_COMMAND = 'compare';
+/** `compare --base <url>`: the build before the change. */
+const BASE_FLAG = '--base';
+/** `compare --state <file.json>`: the declared state sources to read after each sequence. */
+const STATE_FLAG = '--state';
+/** `compare --report <file>`: also write the result as one HTML page. */
+const REPORT_FLAG = '--report';
+/** `compare` takes exactly a reference url and a candidate url. */
+const COMPARE_URLS = 2;
+export function parseCompareArgs(args, defaultPort) {
+    const urls = [];
+    let base;
+    let state;
+    let report;
+    let json = false;
+    let port = defaultPort;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (JSON_FLAG === arg) {
+            json = true;
+            continue;
+        }
+        if (BASE_FLAG === arg || STATE_FLAG === arg || REPORT_FLAG === arg || PORT_FLAG === arg) {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                return missingValue(arg);
+            }
+            i += 1;
+            if (BASE_FLAG === arg) {
+                base = value;
+                continue;
+            }
+            if (STATE_FLAG === arg) {
+                state = value;
+                continue;
+            }
+            if (REPORT_FLAG === arg) {
+                report = value;
+                continue;
+            }
+            const n = Number(value);
+            if (!Number.isInteger(n)) {
+                return notANumber(arg, value);
+            }
+            port = n;
+            continue;
+        }
+        if (arg.startsWith('--') || COMPARE_URLS === urls.length) {
+            return unknownArgument(arg);
+        }
+        urls.push(arg);
+    }
+    const [reference, candidate] = urls;
+    if (reference === undefined || candidate === undefined) {
+        return missingOperand(COMPARE_COMMAND, 'a reference url and a candidate url');
+    }
+    return {
+        kind: 'ok',
+        reference,
+        candidate,
+        ...(base === undefined ? {} : { base }),
+        ...(state === undefined ? {} : { state }),
+        ...(report === undefined ? {} : { report }),
+        json,
+        port,
+    };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * `reticle grade <snapshot|judge|tables|suggest> [flags]`: grade a finished run of an app from
+ * snapshots of its stored data. The rules are in `@/features/grade/`.
+ */
+import { type ParseError } from './cli-parse-grammar.js';
+export declare const GRADE_COMMAND = "grade";
+export declare const GradeStep: {
+    readonly SNAPSHOT: "snapshot";
+    readonly JUDGE: "judge";
+    readonly TABLES: "tables";
+    readonly SUGGEST: "suggest";
+};
+export type GradeStep = (typeof GradeStep)[keyof typeof GradeStep];
+/** Each flag that takes a value, and the field it fills. */
+declare const VALUE_FLAGS: {
+    readonly '--state': "state";
+    readonly '--out': "out";
+    readonly '--url': "url";
+    readonly '--reference': "reference";
+    readonly '--again': "again";
+    readonly '--candidate': "candidate";
+    readonly '--expect': "expect";
+    readonly '--answer': "answer";
+    readonly '--list': "list";
+    readonly '--rows': "rows";
+    readonly '--container': "container";
+    readonly '--skip': "skip";
+};
+type GradeField = (typeof VALUE_FLAGS)[keyof typeof VALUE_FLAGS];
+export type GradeArgs = ({
+    kind: 'ok';
+    step: GradeStep;
+    json: boolean;
+} & Partial<Record<GradeField, string>>) | ParseError;
+export declare function parseGradeArgs(args: readonly string[]): GradeArgs;
+export {};