@reticlehq/server 3.9.0 → 3.10.0

package/dist/surface/tools/compare-tools.d.ts

@@ -0,0 +1,11 @@
+import { type CompareCommandOptions } from '../../command/cli/two-builds/compare-command.js';
+import type { ToolDef } from './tool-kit.js';
+type RunCompare = (options: CompareCommandOptions) => Promise<{
+    code: number;
+    lines: string[];
+}>;
+type Sleep = (ms: number) => Promise<void>;
+/** The compare tool. `run` and `sleep` are injected so a test needs no daemon. */
+export declare function compareTool(run?: RunCompare, sleep?: Sleep): ToolDef;
+export declare const COMPARE_TOOLS: ToolDef[];
+export {};

package/dist/surface/tools/compare-tools.js

@@ -0,0 +1,94 @@
+/**
+ * `reticle_verify { action: "compare" }`: `reticle compare` for an agent whose tools are loaded.
+ *
+ * It runs the CLI's own compare (`runCompareCommand`) against this daemon, over the same loopback
+ * transport the CLI uses, so the answer is the `--json` object of `reticle compare` and nothing
+ * else. The leased tabs resolve their own project from the page, as every lease does. A compare takes minutes, longer than one tool call may wait, so within `wait` seconds it
+ * answers the result, or `{ status: "running", runId }` to poll with `runId`, as `explore` does.
+ */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { RETICLE_DEFAULT_PORT, ReticleTool } from '@reticlehq/core';
+import { pairingToken, runCompareCommand, } from '../../command/cli/two-builds/compare-command.js';
+const RUN_PREFIX = 'compare-';
+const COMPARE_ACTION = 'compare';
+const RUNNING = 'running';
+/** Seconds one call waits for the result before it answers with a run id. */
+const DEFAULT_WAIT_S = 50;
+const MAX_WAIT_S = 240;
+const MS_PER_S = 1000;
+/** The most finished runs kept for polling. A run is read back once or twice, not for ever. */
+const KEPT_RUNS = 8;
+const MSG_NEEDS_URLS = 'compare needs `reference` and `candidate`, the urls of two running builds';
+const MSG_UNKNOWN_RUN = 'no compare run has the id';
+const asText = (value) => 'string' === typeof value && value.length > 0 ? value : undefined;
+/** The JSON object the CLI printed, or the line itself when it is not one. */
+function parsed(lines) {
+    const line = lines[0] ?? '';
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return { error: line };
+    }
+}
+/** The compare tool. `run` and `sleep` are injected so a test needs no daemon. */
+export function compareTool(run = runCompareCommand, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+    const runs = new Map();
+    const answer = async (runId, result, waitS) => {
+        const timedOut = Symbol(RUNNING);
+        const first = await Promise.race([result, sleep(waitS * MS_PER_S).then(() => timedOut)]);
+        if (first !== timedOut) {
+            return first;
+        }
+        return { status: RUNNING, runId, next: { action: COMPARE_ACTION, runId } };
+    };
+    return {
+        name: ReticleTool.VERIFY_COMPARE,
+        description: 'Drive two running builds of one app the same way (for example main and a pull request preview) and list each difference in what users see and in the requests and console errors the app made. Nothing is installed in the app. One opinionated recipe: plan every action on the reference, drive it on the reference two times and the candidate one time, and ignore what changes between the two reference runs. With `base`, each difference is tagged regression, target-missed or changed, with a score. Answers the JSON of `reticle compare --json`: `verified` yes (same), no (different) or unknown (the run proves nothing). Within `wait` seconds the result, or { status: "running", runId } to poll with `runId`. DESTRUCTIVE: it presses every button it finds.',
+        inputSchema: {
+            reference: z.string().optional().describe('URL of the build that is right, e.g. main.'),
+            candidate: z.string().optional().describe('URL of the build to check.'),
+            base: z.string().optional().describe('URL of the build before the change.'),
+            runId: z
+                .string()
+                .optional()
+                .describe('The run id a compare call answered with; pass it to poll that run.'),
+            wait: z.number().min(0).max(MAX_WAIT_S).optional().describe('Seconds; default 50.'),
+        },
+        handler: async (deps, args) => {
+            const waitS = 'number' === typeof args['wait'] ? args['wait'] : DEFAULT_WAIT_S;
+            const polled = asText(args['runId']);
+            if (polled !== undefined) {
+                const result = runs.get(polled);
+                if (result === undefined) {
+                    return { error: `${MSG_UNKNOWN_RUN} ${polled}` };
+                }
+                return answer(polled, result, waitS);
+            }
+            const reference = asText(args['reference']);
+            const candidate = asText(args['candidate']);
+            if (reference === undefined || candidate === undefined) {
+                return { error: MSG_NEEDS_URLS };
+            }
+            const base = asText(args['base']);
+            const token = pairingToken();
+            const runId = `${RUN_PREFIX}${randomUUID()}`;
+            const result = run({
+                reference,
+                candidate,
+                ...(base === undefined ? {} : { base }),
+                json: true,
+                port: deps.bridgePort ?? RETICLE_DEFAULT_PORT,
+                ...(token === undefined ? {} : { token }),
+            }).then((out) => parsed(out.lines));
+            runs.set(runId, result);
+            // ponytail: the oldest runs are dropped by count. Drop by age if a session polls very late.
+            for (const old of [...runs.keys()].slice(0, Math.max(0, runs.size - KEPT_RUNS))) {
+                runs.delete(old);
+            }
+            return answer(runId, result, waitS);
+        },
+    };
+}
+export const COMPARE_TOOLS = [compareTool()];

package/dist/surface/tools/coverage-tools.js

@@ -63,7 +63,7 @@ export function buildCoverageTools() {
                 app: z
                     .boolean()
                     .optional()
-                    .describe('Also fold into the app-wide ledger; returns `app.levels`.'),
+                    .describe('Also fold into the app-wide ledger; returns `app.levels`, `app.holes` and `app.findings`.'),
                 ...sessionIdShape,
             },
             outputSchema: {

package/dist/surface/tools/dynamic-tools.js

@@ -310,10 +310,17 @@ callable) {
                     hint: `pass them inside args: reticle_run { tool, args: { ${strayTop.join(', ')}: … } } if the target tool declares them`,
                 };
             }
-            const name = 'string' === typeof args['tool'] ? args['tool'] : '';
-            const given = 'object' === typeof args['args'] && args['args'] !== null
+            const asked = 'string' === typeof args['tool'] ? args['tool'] : '';
+            const passed = 'object' === typeof args['args'] && args['args'] !== null
                 ? args['args']
                 : {};
+            // A merged name is CALLED, as the MCP layer does (mcp.ts). Explaining it here left
+            // `reticle verify --expect` unable to wait, so it could never give a verdict. The old name is
+            // the action, so it wins over an `action` in the arguments.
+            const moved = byName.has(asked) ? undefined : mergedNameRedirect(asked);
+            const routed = moved?.action !== undefined && byName.has(moved.tool);
+            const name = routed ? moved.tool : asked;
+            const given = routed ? { ...passed, action: moved.action } : passed;
             const aimed = args['sessionId'];
             const target = byName.get(name);
             if (target === undefined) {

package/dist/surface/tools/error-recovery.d.ts

@@ -8,7 +8,7 @@
  * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
  * baseline stores). No clock, no IO — unit-testable in isolation.
  */
-import { RefusalReason, type CodedRefusal } from '@reticlehq/core';
+import { RefusalDetail, RefusalReason, type CodedRefusal } from '@reticlehq/core';
 /** The recovery hints, named so they are not free strings and can be asserted in tests. */
 export declare const RECOVERY: {
     readonly NO_SESSION: string;
@@ -97,6 +97,11 @@ export declare const RECOVERY: {
  * saying a server is running and the recovery saying to go start one.
  */
 export declare function recoveryFor(message: string): string | undefined;
+/** A refusal's bucket, and the cause inside it when the recovery table can tell. */
+export interface RefusalClass {
+    readonly reason: RefusalReason;
+    readonly detail?: RefusalDetail;
+}
 /**
  * WHY a tool refused, as one of the six buckets in core's `RefusalReason`.
  *
@@ -106,6 +111,12 @@ export declare function recoveryFor(message: string): string | undefined;
  * this table rather than about anybody's app.
  */
 export declare function refusalReasonFor(rawMessage: string, coded?: CodedRefusal): RefusalReason;
+/**
+ * The bucket and, when the recovery table names one, the cause inside it. The cause comes from the
+ * same rule that chose the agent's advice, so the two cannot disagree. No detail means no rule
+ * matched, or the message diagnosed itself (`noSessionReason` carries that cause).
+ */
+export declare function classifyRefusal(rawMessage: string, coded?: CodedRefusal): RefusalClass;
 /**
  * The ask attached to errors we do NOT recognize. An unrecognized error is, by definition, the case
  * where Reticle failed in a way nobody anticipated — the single highest-value moment to hear from the

package/dist/surface/tools/error-recovery.js

@@ -8,12 +8,13 @@
  * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
  * baseline stores). No clock, no IO — unit-testable in isolation.
  */
-import { CodedRefusalSchema, PRODUCTION_REFUSAL_PREFIX, RefusalCode, RefusalReason, ReticleEnv, TRANSPORT_LIMITS, UNISSUED_REF_REFUSAL, } from '@reticlehq/core';
+import { CodedRefusalSchema, PRODUCTION_REFUSAL_PREFIX, RefusalCode, RefusalDetail, RefusalReason, ReticleEnv, TRANSPORT_LIMITS, UNISSUED_REF_REFUSAL, } from '@reticlehq/core';
 import { SELF_RECOVERING_MARKER } from '../../portal/session/no-session-diagnosis.js';
 import { MSG_HARNESS_DISABLED, MSG_HARNESS_UNCLAIMED, MSG_HARNESS_UNCONFIRMED, PlatformRefusalCode, RefusalLead, } from '../../features/harness/platform/refusal.js';
 import { BODY_CLAUSE_REFUSAL_OPENING } from '@reticlehq/engine/evidence/body-capture-remedy.js';
 import { EMPTY_FIND_OPENING } from './read/query-shape.js';
 import { UNKNOWN_FLOW_OPENING } from '../../language/flows/suite-selection.js';
+import { ARTIFACT_ROOT_ABSOLUTE_REFUSAL, ARTIFACT_ROOT_MISSING_REFUSAL, } from '../../memory/project/root-claims.js';
 import { CHROMIUM_PATH_REFUSAL_PREFIX, chromiumInstallCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
 /** Marks where an over-long message had its middle removed. Named so tests assert it by value. */
 const ELISION = '… [elided] …';
@@ -71,6 +72,11 @@ const SELF_RECOVERING = [
     // Both are the caller's to fix, and the defect ask on top told an agent to file a bug about them.
     { match: literally(EMPTY_FIND_OPENING), reason: RefusalReason.BAD_ARGS },
     { match: literally(UNKNOWN_FLOW_OPENING), reason: RefusalReason.NO_MATCH },
+    // A lease `root` naming no directory on disk — relative, or absent — is the caller's to fix, and
+    // the message carries the exact path to pass instead. Both sat under the feedback ask, which
+    // invited a bug report about a mistyped path (#2085).
+    { match: literally(ARTIFACT_ROOT_ABSOLUTE_REFUSAL), reason: RefusalReason.BAD_ARGS },
+    { match: literally(ARTIFACT_ROOT_MISSING_REFUSAL), reason: RefusalReason.BAD_ARGS },
 ];
 /**
  * The refusal for a `ref` Reticle never minted — decided BEFORE every other rule, not by one inside
@@ -204,10 +210,12 @@ export const RECOVERY = {
         'on purpose. If you mean it, send the SAME call again with ' +
         '`args: { confirmDangerous: true }` — it goes inside the `args` object, not beside it. This is ' +
         'a deliberate refusal, not a defect: there is nothing to report.',
-    UNSUPPORTED_SURFACE: 'That surface is not supported yet, and Reticle refuses rather than pretending — a rich-text ' +
-        'editor keeps its own document model, so writing to the DOM would look right and submit the old ' +
-        'content. Drive the same outcome another way (a plain input, a command, a keyboard action) or ' +
-        'assert on the result instead of typing it. Known gap, already reported: no need to file it.',
+    UNSUPPORTED_SURFACE: 'That surface is a rich-text editor: it keeps its own document model, so `fill` and `type` ' +
+        'refuse it rather than write the DOM and submit the old content. A contenteditable editor ' +
+        '(Tiptap, ProseMirror) takes `insertText` with `{ text }`: it goes through the browser editing ' +
+        'pipeline, so the editor model updates. An EditContext editor (Monaco, CodeMirror 6) cannot be ' +
+        'typed into yet, because a scripted update fires no textupdate for its model: use `press` for ' +
+        'a key. If the ref points at a wrapper, act on the editor inside it instead.',
     HOVER_NEEDS_POINTER: 'Hover needs a real pointer: a synthetic mouseover does not apply CSS :hover, and Reticle ' +
         'refuses rather than reporting the styles as applied. Acquire a tab with ' +
         'reticle_run { tool: "reticle_lease", args: { action: "acquire", url } } — reticle_lease is not ' +
@@ -259,7 +267,7 @@ export const RECOVERY = {
         'what is wrong with the path). The call itself was fine, so retrying it will not help, and ' +
         'neither will installing Chromium. Ask the human to fix that path, or unset it to use ' +
         "Playwright's own Chromium, in the environment the daemon starts from, then run " +
-        '`npx @reticlehq/server restart`. Meanwhile drive a tab the human already has open, which ' +
+        '`npx @reticlehq/server serve --restart`. Meanwhile drive a tab the human already has open, which ' +
         'reticle_sessions lists. This is configuration, not a Reticle defect: there is nothing to report.',
     /**
      * The two ways a platform answer can refuse a drive. Neither is a fault, and both were telling the
@@ -325,6 +333,44 @@ const REASON_OF = {
     // The call is valid; the app is not instrumented enough for the Harness yet.
     HARNESS_LOCKED: RefusalReason.UNSUPPORTED,
 };
+/**
+ * Which CAUSE each recovery names, for `tool_refused`. A `Record` for the same reason as `REASON_OF`:
+ * a recovery added without a detail does not compile. A rule can name a narrower detail than its
+ * recovery (`NO_POOL` covers three causes with one hint).
+ */
+const DETAIL_OF = {
+    NO_SESSION: RefusalDetail.NO_SESSION,
+    MULTIPLE_SESSIONS: RefusalDetail.MULTIPLE_SESSIONS,
+    UNKNOWN_SESSION: RefusalDetail.UNKNOWN_SESSION,
+    SCOPE_MISMATCH: RefusalDetail.SCOPE_MISMATCH,
+    SESSION_GONE: RefusalDetail.SESSION_GONE,
+    THROTTLED: RefusalDetail.THROTTLED,
+    COMMAND_TIMEOUT: RefusalDetail.COMMAND_TIMEOUT,
+    NO_POOL: RefusalDetail.POOL_UNAVAILABLE,
+    CHROMIUM_PATH: RefusalDetail.CHROMIUM_PATH,
+    TOKEN_REQUIRED: RefusalDetail.TOKEN_REQUIRED,
+    MISSING_BASELINE: RefusalDetail.MISSING_BASELINE,
+    MISSING_RECORDING: RefusalDetail.MISSING_RECORDING,
+    STALE_REF: RefusalDetail.STALE_REF,
+    STALE_REF_AFTER_EDIT: RefusalDetail.STALE_REF_AFTER_EDIT,
+    UNISSUED_REF: RefusalDetail.UNISSUED_REF,
+    NO_SUCH_OPTION: RefusalDetail.NO_SUCH_OPTION,
+    TARGET_MISSED: RefusalDetail.TARGET_MISSED,
+    AMBIGUOUS_TARGET: RefusalDetail.AMBIGUOUS_TARGET,
+    FLOW_STEP_MISSING: RefusalDetail.FLOW_STEP_MISSING,
+    UNSUPPORTED_SURFACE: RefusalDetail.UNSUPPORTED_SURFACE,
+    HOVER_NEEDS_POINTER: RefusalDetail.HOVER_NEEDS_POINTER,
+    NOT_EDITABLE: RefusalDetail.NOT_EDITABLE,
+    CONFIRM_DANGEROUS: RefusalDetail.CONFIRM_DANGEROUS,
+    WRONG_TARGET: RefusalDetail.WRONG_TARGET,
+    PRODUCTION_POLICY: RefusalDetail.PRODUCTION_POLICY,
+    BAD_ARGUMENTS: RefusalDetail.BAD_ARGUMENTS,
+    INVALID_NAME: RefusalDetail.INVALID_NAME,
+    HARNESS_OFF: RefusalDetail.HARNESS_OFF,
+    HARNESS_LOCKED: RefusalDetail.HARNESS_LOCKED,
+};
+/** Hint text back to its detail, as `REASON_BY_HINT` does for the reason. */
+const DETAIL_BY_HINT = new Map(Object.entries(RECOVERY).map(([key, hint]) => [hint, DETAIL_OF[key]]));
 /** Hint text back to its reason. The hints are distinct strings, so this inverts cleanly. */
 const REASON_BY_HINT = new Map(Object.entries(RECOVERY).map(([key, hint]) => [hint, REASON_OF[key]]));
 /** Ordered match rules; the first hit wins. Substrings track the thrown messages they recover. */
@@ -375,9 +421,17 @@ const RULES = [
     { match: /^command '[^']*' timed out after/i, hint: RECOVERY.COMMAND_TIMEOUT },
     // Flow replay: the recorded anchor is gone. Ordinary drift, and the tool that fixes it exists.
     { match: /did not resolve in current page/i, hint: RECOVERY.FLOW_STEP_MISSING },
+    // One hint for three causes: the agent's next step is the same, the fix for the user is not.
+    { match: /browser pool unavailable/i, hint: RECOVERY.NO_POOL },
     {
-        match: /browser pool (?:unavailable|is shut down)|Chromium is not installed/i,
+        match: /browser pool is shut down/i,
         hint: RECOVERY.NO_POOL,
+        detail: RefusalDetail.POOL_SHUT_DOWN,
+    },
+    {
+        match: /Chromium is not installed/i,
+        hint: RECOVERY.NO_POOL,
+        detail: RefusalDetail.CHROMIUM_MISSING,
     },
     // The commonest post-action condition there is. Unmatched, it fell through to FEEDBACK_ASK and
     // told the agent a successful click's aftermath might be a bug in Reticle.
@@ -392,6 +446,10 @@ const RULES = [
     // broken. Order matters: contenteditable and disabled/readonly are `cannot <verb> …` messages too,
     // so they must be tested before the general wrong-target rule.
     { match: /contenteditable/i, hint: RECOVERY.UNSUPPORTED_SURFACE },
+    // The EditContext refusal from insertText. Its message names no `contenteditable`, so it used to
+    // fall through to the feedback ask — a deliberate refusal of a surface we cannot type into yet
+    // read as "Reticle may be broken".
+    { match: /EditContext/i, hint: RECOVERY.UNSUPPORTED_SURFACE },
     { match: /cannot hover without a real pointer/i, hint: RECOVERY.HOVER_NEEDS_POINTER },
     { match: /cannot \w+ a (disabled|readonly) </i, hint: RECOVERY.NOT_EDITABLE },
     // Both "action" and "native action" refusals need the same confirmation guidance.
@@ -473,12 +531,11 @@ export function recoveryFor(message) {
     if (isSelfRecovering(message)) {
         return undefined;
     }
-    for (const rule of RULES) {
-        if (rule.match.test(message)) {
-            return rule.hint;
-        }
-    }
-    return undefined;
+    return firstRule(message)?.hint;
+}
+/** The first rule that matches the message. The order of `RULES` decides. */
+function firstRule(message) {
+    return RULES.find((rule) => rule.match.test(message));
 }
 /**
  * WHY a tool refused, as one of the six buckets in core's `RefusalReason`.
@@ -489,33 +546,46 @@ export function recoveryFor(message) {
  * this table rather than about anybody's app.
  */
 export function refusalReasonFor(rawMessage, coded) {
+    return classifyRefusal(rawMessage, coded).reason;
+}
+/**
+ * The bucket and, when the recovery table names one, the cause inside it. The cause comes from the
+ * same rule that chose the agent's advice, so the two cannot disagree. No detail means no rule
+ * matched, or the message diagnosed itself (`noSessionReason` carries that cause).
+ */
+export function classifyRefusal(rawMessage, coded) {
     if (coded !== undefined) {
-        return REASON_OF_CODE[coded.code];
+        return { reason: REASON_OF_CODE[coded.code] };
     }
     const message = zodArrayAsSentence(rawMessage);
     if (isUnissuedRefRefusal(message)) {
-        return RefusalReason.BAD_ARGS;
+        return { reason: RefusalReason.BAD_ARGS, detail: RefusalDetail.UNISSUED_REF };
     }
     // The no-session diagnosis inspected the machine and named the cause itself, so it never reaches
     // the recovery table. It is the single largest refusal there is; missing it would gut the metric.
     if (message.includes(SELF_RECOVERING_MARKER)) {
-        return RefusalReason.NO_SESSION;
+        return { reason: RefusalReason.NO_SESSION };
     }
     for (const rule of SELF_RECOVERING) {
         if (rule.match.test(message)) {
-            return rule.reason;
+            return { reason: rule.reason };
         }
     }
     // Same order as buildErrorPayload: a schema rejection is the agent's own call, whatever else in
     // the message might also match.
     if (ARGUMENT_REJECTION.test(message)) {
-        return RefusalReason.BAD_ARGS;
+        return { reason: RefusalReason.BAD_ARGS };
     }
     if (INVALID_NAME_REJECTION.test(message)) {
-        return RefusalReason.BAD_ARGS;
+        return { reason: RefusalReason.BAD_ARGS, detail: RefusalDetail.INVALID_NAME };
+    }
+    const rule = firstRule(message);
+    if (rule === undefined) {
+        return { reason: RefusalReason.OTHER };
     }
-    const hint = recoveryFor(message);
-    return (hint === undefined ? undefined : REASON_BY_HINT.get(hint)) ?? RefusalReason.OTHER;
+    const reason = REASON_BY_HINT.get(rule.hint) ?? RefusalReason.OTHER;
+    const detail = rule.detail ?? DETAIL_BY_HINT.get(rule.hint);
+    return detail === undefined ? { reason } : { reason, detail };
 }
 /**
  * A schema rejection: the call named a parameter that does not exist, or gave one the wrong type.

package/dist/surface/tools/explore-tools.js

@@ -60,7 +60,7 @@ export const EXPLORE_TOOLS = [
             runId: z
                 .string()
                 .optional()
-                .describe('The run id an explore call answered with; pass it to poll that run.'),
+                .describe('The run id a call answered with; pass it to poll that run.'),
             planId: z.string().optional().describe('Run a plan saved on the dashboard, as it stands.'),
             stop: z.boolean().optional().describe('With runId: stop that Harness run.'),
             say: z.string().optional().describe('With runId: a note to the running Harness.'),

package/dist/surface/tools/invoke-tool.js

@@ -30,7 +30,7 @@ import { rewriteClosedAsSkew } from '../../command/version/version-skew.js';
 import { noteToolCall } from '../../command/daemon/lifetime/daemon-usefulness.js';
 import { bugsInResult, routeOf } from '../../telemetry/bug-found.js';
 import { noteToolServed, reportToolRefused } from '../../telemetry/tool-refused.js';
-import { buildErrorPayload, codedRefusalOf, refusalReasonFor } from './error-recovery.js';
+import { buildErrorPayload, classifyRefusal, codedRefusalOf } from './error-recovery.js';
 import { resultIsError } from '../mcp/faults/mcp-is-error.js';
 import { verificationOf } from '../../telemetry/verification-of.js';
 import { emitBugFoundHook, emitVerdictHook } from '../../hooks/hook-emit.js';
@@ -140,7 +140,8 @@ function reportRefusal(toolName, args, message, error) {
     if (toolName === ReticleTool.RUN) {
         return;
     }
-    reportToolRefused(toolName, refusalReasonFor(message, codedRefusalOf(error)), args);
+    const { reason, detail } = classifyRefusal(message, codedRefusalOf(error));
+    reportToolRefused(toolName, reason, args, detail);
 }
 /**
  * Which friction this result represents, counting the invitation if there is one.

package/dist/surface/tools/lease-coverage-tools.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `reticle_lease { action: "coverage" }` — which code of a leased page ran, as the JS engine counted it.
+ *
+ * A caller outside the app cannot see which branches a drive reached. The JS engine can: each script's block
+ * ranges carry a count. This reads them from the lease's own Playwright page, the way
+ * `reticle_network_mock` reaches it, so it needs no change to the app.
+ *
+ * A take returns what ran since the previous take, and coverage keeps running across a reload.
+ * Start it on acquire (`jsCoverage: true`) to see the code that runs while the page loads; a start
+ * after the load misses it.
+ */
+import { z } from 'zod';
+import type { ScriptCoverage } from '../../portal/input/js-coverage.js';
+import { type ToolDef } from './tool-kit.js';
+export declare const LeaseCoverageMode: {
+    readonly START: "start";
+    readonly TAKE: "take";
+};
+/** Ranges one take returns when the caller sets no cap. */
+export declare const DEFAULT_MAX_COVERAGE_RANGES = 20000;
+interface Range {
+    startOffset: number;
+    endOffset: number;
+    count: number;
+}
+/** What a take returns: each kept script with its ranges, and what the cap and filter left out. */
+export interface CoverageTake {
+    scripts: {
+        url: string;
+        ranges: Range[];
+    }[];
+    scriptCount: number;
+    rangeCount: number;
+    filteredOut?: number;
+    truncated?: {
+        scripts: number;
+        ranges: number;
+        maxRanges: number;
+    };
+}
+/**
+ * Flatten each script's functions into one range list, keep the scripts `urlContains` names, and
+ * stop at `maxRanges`. What the cap drops is counted in `truncated`, beside the value.
+ */
+export declare function flattenCoverage(entries: readonly ScriptCoverage[], maxRanges: number, urlContains?: string): CoverageTake;
+/** The acquire argument that starts coverage before the page's first script. */
+export declare const LEASE_JS_COVERAGE_ARG: z.ZodOptional<z.ZodBoolean>;
+export declare const LEASE_COVERAGE_TOOL: ToolDef;
+export {};

package/dist/surface/tools/lease-coverage-tools.js

@@ -0,0 +1,128 @@
+/**
+ * `reticle_lease { action: "coverage" }` — which code of a leased page ran, as the JS engine counted it.
+ *
+ * A caller outside the app cannot see which branches a drive reached. The JS engine can: each script's block
+ * ranges carry a count. This reads them from the lease's own Playwright page, the way
+ * `reticle_network_mock` reaches it, so it needs no change to the app.
+ *
+ * A take returns what ran since the previous take, and coverage keeps running across a reload.
+ * Start it on acquire (`jsCoverage: true`) to see the code that runs while the page loads; a start
+ * after the load misses it.
+ */
+import { z } from 'zod';
+import { ReticleTool, asNumber, asString } from '@reticlehq/core';
+import { sessionIdShape } from './tool-kit.js';
+export const LeaseCoverageMode = { START: 'start', TAKE: 'take' };
+/** Ranges one take returns when the caller sets no cap. */
+export const DEFAULT_MAX_COVERAGE_RANGES = 20_000;
+const MAX_COVERAGE_RANGES = 200_000;
+const NOT_A_LEASE = 'reticle_lease { action: "coverage" } reads a leased tab only. Acquire one with reticle_lease { action: "acquire", url, jsCoverage: true }, then pass its sessionId.';
+const CANNOT_MEASURE = 'This leased page cannot measure JS coverage. Coverage needs Chromium, and a page that is still open.';
+const WAS_NOT_RUNNING = 'Coverage was not running, so this take holds nothing. It runs now: do the work, then take again. To see the code that runs while the page loads, acquire with jsCoverage: true.';
+/**
+ * Flatten each script's functions into one range list, keep the scripts `urlContains` names, and
+ * stop at `maxRanges`. What the cap drops is counted in `truncated`, beside the value.
+ */
+export function flattenCoverage(entries, maxRanges, urlContains) {
+    const kept = entries.filter((e) => urlContains === undefined || e.url.includes(urlContains));
+    const scripts = [];
+    let rangeCount = 0;
+    let droppedRanges = 0;
+    let droppedScripts = 0;
+    for (const entry of kept) {
+        const ranges = entry.functions.flatMap((f) => f.ranges);
+        const room = maxRanges - rangeCount;
+        if (room <= 0 && 0 < ranges.length) {
+            droppedScripts += 1;
+            droppedRanges += ranges.length;
+            continue;
+        }
+        const taken = ranges
+            .slice(0, Math.max(0, room))
+            .map(({ startOffset, endOffset, count }) => ({ startOffset, endOffset, count }));
+        droppedRanges += ranges.length - taken.length;
+        rangeCount += taken.length;
+        scripts.push({ url: entry.url, ranges: taken });
+    }
+    const filteredOut = entries.length - kept.length;
+    return {
+        scripts,
+        scriptCount: scripts.length,
+        rangeCount,
+        ...(0 < filteredOut ? { filteredOut } : {}),
+        ...(0 < droppedRanges
+            ? { truncated: { scripts: droppedScripts, ranges: droppedRanges, maxRanges } }
+            : {}),
+    };
+}
+/** The acquire argument that starts coverage before the page's first script. */
+export const LEASE_JS_COVERAGE_ARG = z
+    .boolean()
+    .optional()
+    .describe('Start JS coverage before the page runs its first script, so reticle_lease { action: "coverage" } also counts the code that runs while the page loads.');
+export const LEASE_COVERAGE_TOOL = {
+    name: ReticleTool.LEASE_COVERAGE,
+    description: 'JS coverage of a leased tab: which code ran. { mode: "start" } starts it; { mode: "take" } (the default) returns, for each script, its url and block ranges { startOffset, endOffset, count } since the previous take. A count of 0 is code that did not run. Acquire with jsCoverage: true to include the code that runs while the page loads. Use urlContains to keep only your own scripts; a take that hits maxRanges says what it dropped in `truncated`.',
+    example: { mode: 'take', urlContains: '/src/' },
+    inputSchema: {
+        mode: z
+            .enum([LeaseCoverageMode.START, LeaseCoverageMode.TAKE])
+            .optional()
+            .describe('"start" starts coverage; "take" (default) returns what ran since the previous take.'),
+        urlContains: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('Keep only the scripts whose url contains this text, for example "/src/".'),
+        maxRanges: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_COVERAGE_RANGES)
+            .optional()
+            .describe(`The most ranges one take returns. Default ${String(DEFAULT_MAX_COVERAGE_RANGES)}.`),
+        ...sessionIdShape,
+    },
+    outputSchema: {
+        running: z.boolean().describe('Whether coverage runs on the page after this call.'),
+        scripts: z
+            .array(z.object({
+            url: z.string(),
+            ranges: z.array(z.object({ startOffset: z.number(), endOffset: z.number(), count: z.number() })),
+        }))
+            .optional(),
+        scriptCount: z.number().optional(),
+        rangeCount: z.number().optional(),
+        filteredOut: z
+            .number()
+            .optional()
+            .describe('Scripts left out because their url did not contain urlContains.'),
+        truncated: z
+            .object({ scripts: z.number(), ranges: z.number(), maxRanges: z.number() })
+            .optional()
+            .describe('Present when the take hit maxRanges: the scripts and ranges it dropped. Absent means nothing was dropped.'),
+        hint: z.string().optional(),
+    },
+    handler: async (deps, args) => {
+        const session = deps.sessions.resolve(asString(args['sessionId']));
+        const coverage = deps.pool?.coverageOf(session.id);
+        if (coverage === undefined) {
+            throw new Error(NOT_A_LEASE);
+        }
+        if (LeaseCoverageMode.START === args['mode']) {
+            if (!(await coverage.start())) {
+                throw new Error(CANNOT_MEASURE);
+            }
+            return { running: true };
+        }
+        const entries = await coverage.take();
+        if (entries === undefined) {
+            if (!(await coverage.start())) {
+                throw new Error(CANNOT_MEASURE);
+            }
+            return { running: true, scripts: [], scriptCount: 0, rangeCount: 0, hint: WAS_NOT_RUNNING };
+        }
+        const maxRanges = asNumber(args['maxRanges']) ?? DEFAULT_MAX_COVERAGE_RANGES;
+        return { running: true, ...flattenCoverage(entries, maxRanges, asString(args['urlContains'])) };
+    },
+};

package/dist/surface/tools/lease-hint.d.ts

@@ -17,7 +17,8 @@
  * So: rank by what the daemon actually knows, and fall back to the differential only when it knows
  * nothing. A cause we hold positive evidence against is not printed at all.
  */
-import type { LeaseReaderFailure } from './lease-readiness.js';
+import { LeaseNotReadyReason } from '@reticlehq/core';
+import { HeldLeaseReload, type LeaseReaderFailure } from './lease-readiness.js';
 /** What the daemon can say for certain at the moment a lease comes back unconnected. */
 export interface LeaseEvidence {
     /** A dial WAS made and turned away, with the reason. The only certain cause there is. */
@@ -72,3 +73,36 @@ export declare function leaseNotConnectedHint(url: string, port: number, evidenc
 export declare function leaseStillLoadingHint(url: string, waitedMs: number): string;
 /** The hint for a lease whose zero-install reader did not run (#1701). The lease is already released. */
 export declare function leaseReaderFailedHint(url: string, failure: LeaseReaderFailure): string;
+/** What `reticle_lease` answers for a held lease that it loaded again and that did not connect. */
+export interface KeptLeaseAnswer {
+    sessionId: string;
+    url: string;
+    ready: false;
+    notReadyReason: LeaseNotReadyReason;
+    reused: true;
+    expiresInMs: number;
+    leased: number;
+    queued: number;
+    hint: string;
+}
+/**
+ * The answer for a held lease that is kept although its page did not connect (#1924). The tab is
+ * kept, because its context holds the cookies: a new context starts signed out. `reload` says
+ * whether its page loaded again; `cause` is why it did not connect, or why it did not load.
+ */
+export declare function keptLeaseAnswer(lease: {
+    sessionId: string;
+    origin: string;
+    url: string;
+    reload: HeldLeaseReload;
+}, pool: {
+    leaseTtlMs(): number;
+    activeCount(): number;
+    queuedCount(): number;
+}, cause: string): KeptLeaseAnswer;
+/**
+ * Why a held lease's page did not load again, said from what the daemon can check: whether
+ * anything accepts a connection on the page's port. Only asked of a loopback URL, where the probe
+ * reaches the same server the browser does.
+ */
+export declare function notLoadedCause(url: string, portAccepts: ((port: number) => Promise<boolean>) | undefined): Promise<string>;