@reticlehq/server 3.8.2 → 3.10.0

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] …';
@@ -32,8 +33,9 @@ const ELISION = '… [elided] …';
  */
 function capMessage(message) {
     const max = TRANSPORT_LIMITS.MAX_ERROR_LENGTH;
-    if (max >= message.length)
+    if (max >= message.length) {
         return message;
+    }
     const keep = Math.floor((max - ELISION.length) / 2);
     return `${message.slice(0, keep)}${ELISION}${message.slice(message.length - keep)}`;
 }
@@ -70,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
@@ -83,8 +90,9 @@ function isUnissuedRefRefusal(message) {
 }
 /** A message that already carries its own concrete next action, so nothing should be appended. */
 function isSelfRecovering(message) {
-    if (message.includes(SELF_RECOVERING_MARKER))
+    if (message.includes(SELF_RECOVERING_MARKER)) {
         return true;
+    }
     return SELF_RECOVERING.some((rule) => rule.match.test(message));
 }
 /** The recovery hints, named so they are not free strings and can be asserted in tests. */
@@ -142,8 +150,9 @@ export const RECOVERY = {
      * carry: which of them to reach for, and that nothing was acted on.
      */
     TARGET_MISSED: 'The call was valid — the selector matched nothing on the page RIGHT NOW, and nothing was ' +
-        'acted on. Take a reticle_snapshot to see what is actually there (a view may still be ' +
-        'rendering, or the control may be named differently), then retry with what it shows. This is ' +
+        'acted on. If the message lists the nearest targets and one is the element you meant, retry ' +
+        'with its ref. If not, take a reticle_snapshot to see what is actually there (a view may still ' +
+        'be rendering, or the control may be named differently), then retry with what it shows. This is ' +
         'a miss, not a Reticle defect: there is nothing to report.',
     /**
      * The selector was underspecified, which is the caller's to fix and the same class as a miss.
@@ -201,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 ' +
@@ -256,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
@@ -322,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. */
@@ -372,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 is shut down/i,
+        hint: RECOVERY.NO_POOL,
+        detail: RefusalDetail.POOL_SHUT_DOWN,
+    },
     {
-        match: /browser pool (?:unavailable|is shut down)|Chromium is not installed/i,
+        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.
@@ -389,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.
@@ -464,15 +525,17 @@ const RULES = [
  * saying a server is running and the recovery saying to go start one.
  */
 export function recoveryFor(message) {
-    if (isUnissuedRefRefusal(message))
+    if (isUnissuedRefRefusal(message)) {
         return RECOVERY.UNISSUED_REF;
-    if (isSelfRecovering(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`.
@@ -483,27 +546,46 @@ export function recoveryFor(message) {
  * this table rather than about anybody's app.
  */
 export function refusalReasonFor(rawMessage, coded) {
-    if (coded !== undefined)
-        return REASON_OF_CODE[coded.code];
+    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: REASON_OF_CODE[coded.code] };
+    }
     const message = zodArrayAsSentence(rawMessage);
-    if (isUnissuedRefRefusal(message))
-        return RefusalReason.BAD_ARGS;
+    if (isUnissuedRefRefusal(message)) {
+        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;
+    if (message.includes(SELF_RECOVERING_MARKER)) {
+        return { reason: RefusalReason.NO_SESSION };
+    }
     for (const rule of SELF_RECOVERING) {
-        if (rule.match.test(message))
-            return rule.reason;
+        if (rule.match.test(message)) {
+            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;
-    if (INVALID_NAME_REJECTION.test(message))
-        return RefusalReason.BAD_ARGS;
-    const hint = recoveryFor(message);
-    return (hint === undefined ? undefined : REASON_BY_HINT.get(hint)) ?? RefusalReason.OTHER;
+    if (ARGUMENT_REJECTION.test(message)) {
+        return { reason: RefusalReason.BAD_ARGS };
+    }
+    if (INVALID_NAME_REJECTION.test(message)) {
+        return { reason: RefusalReason.BAD_ARGS, detail: RefusalDetail.INVALID_NAME };
+    }
+    const rule = firstRule(message);
+    if (rule === undefined) {
+        return { reason: 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.
@@ -520,8 +602,9 @@ export function refusalReasonFor(rawMessage, coded) {
 /** Max issues rendered — a union rejection can emit one per member, which is how the array became unreadable. */
 const MAX_RENDERED_ISSUES = 3;
 function isZodIssue(value) {
-    if (typeof value !== 'object' || null === value)
+    if (typeof value !== 'object' || null === value) {
         return false;
+    }
     const v = value;
     return 'string' === typeof v['code'] && 'string' === typeof v['message'];
 }
@@ -548,8 +631,9 @@ function issueClause(issue) {
  */
 function zodArrayAsSentence(message) {
     const text = message.trim();
-    if (!text.startsWith('['))
+    if (!text.startsWith('[')) {
         return message;
+    }
     let parsed;
     try {
         parsed = JSON.parse(text);
@@ -557,8 +641,9 @@ function zodArrayAsSentence(message) {
     catch {
         return message; // not JSON at all — e.g. prose that happens to open with a bracket
     }
-    if (!Array.isArray(parsed) || 0 === parsed.length || !parsed.every(isZodIssue))
+    if (!Array.isArray(parsed) || 0 === parsed.length || !parsed.every(isZodIssue)) {
         return message;
+    }
     const shown = parsed.slice(0, MAX_RENDERED_ISSUES).map(issueClause).join('; ');
     const rest = parsed.length - MAX_RENDERED_ISSUES;
     return rest > 0 ? `${shown} (and ${String(rest)} more)` : shown;
@@ -613,8 +698,9 @@ const REASON_OF_CODE = {
  * its sentence: the not-linked refusal was matched by its prose, and the prose was rewritten.
  */
 export function codedRefusalOf(error) {
-    if (!(error instanceof Error))
+    if (!(error instanceof Error)) {
         return undefined;
+    }
     const parsed = CodedRefusalSchema.safeParse({
         code: 'code' in error ? error.code : undefined,
         next: 'next' in error ? error.next : undefined,
@@ -631,24 +717,29 @@ export function buildErrorPayload(rawMessage, coded) {
     // leave an unparseable fragment as the agent's error text — the worst of both shapes.
     const message = capMessage(zodArrayAsSentence(rawMessage));
     // A coded refusal says who does what next itself: no hint beside it, and no bug-report ask.
-    if (coded !== undefined)
+    if (coded !== undefined) {
         return { error: message, code: coded.code, next: coded.next };
-    if (isUnissuedRefRefusal(message))
+    }
+    if (isUnissuedRefRefusal(message)) {
         return { error: message, recovery: RECOVERY.UNISSUED_REF };
+    }
     // A self-diagnosing message gets NEITHER a generic recovery nor the feedback ask. It already
     // inspected the machine and named the cause; a second, contradictory hint is noise, and inviting a
     // bug report about a condition Reticle diagnosed itself is exactly backwards.
-    if (isSelfRecovering(message))
+    if (isSelfRecovering(message)) {
         return { error: message };
+    }
     // An argument rejection is the agent's to fix, not a Reticle defect. Reported from the field: a
     // clean `unrecognized_keys: ["value"]` came back wrapped in "may be a defect in Reticle", which
     // spends the agent's turn and fills the feedback channel with reports about malformed calls.
-    if (ARGUMENT_REJECTION.test(message))
+    if (ARGUMENT_REJECTION.test(message)) {
         return { error: message, recovery: ARGUMENT_RECOVERY };
+    }
     // Reticle's own name validators rejecting a caller's value: an argument rejection that the schema
     // cannot express (the shape is a runtime pattern, not a type), so it needs its own arm.
-    if (INVALID_NAME_REJECTION.test(message))
+    if (INVALID_NAME_REJECTION.test(message)) {
         return { error: message, recovery: RECOVERY.INVALID_NAME };
+    }
     const recovery = recoveryFor(message);
     return recovery !== undefined
         ? { error: message, recovery }

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

@@ -17,6 +17,7 @@ import { endsRun, noteToolResult, runReportField } from './run-report.js';
 import { runLedger } from '../../judgement/runs/run-ledger.js';
 import { readAppNotes } from './agent/app-notes.js';
 import { forTheAgent } from './agent/for-the-agent.js';
+import { inRepeatStreak, withHintOn } from './repeat-hint.js';
 import { feedbackAlreadyAsked, noteFeedbackAsked } from './agent/notices.js';
 import { SKEW_SHORT_WARNING, SKEW_VERDICT_WARNING } from '../../portal/session/session-health.js';
 import { verifyNextBaton, SUPPRESS_VERIFY_NEXT_ENV } from './verify-next-baton.js';
@@ -29,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';
@@ -46,6 +47,7 @@ import { takeStepShot } from '../../features/visual/step-shots.js';
 import { defectForToolResult, deltaForToolResult, impactSnapshot, initImpact, recordImpact, } from '../../memory/impact/impact-recorder.js';
 import { FrictionKind, frictionOf, inviteFor } from './feedback-invite.js';
 import { VACUOUS_BECAUSE } from '@reticlehq/engine/evidence/verified.js';
+import { NEXT_STEP_FIELD } from './empty-session-list.js';
 /**
  * Emit `verification_completed` when a verification tool produced a verdict.
  *
@@ -134,11 +136,12 @@ function reportBugsFound(toolName, result, sessionId) {
  * tool's name, and then hands the same failure back out to be reported a second time as
  * `reticle_run`. A count that doubles because of HOW a tool was reached is not a measurement.
  */
-function reportRefusal(toolName, message, error) {
+function reportRefusal(toolName, args, message, error) {
     if (toolName === ReticleTool.RUN) {
         return;
     }
-    reportToolRefused(toolName, refusalReasonFor(message, codedRefusalOf(error)));
+    const { reason, detail } = classifyRefusal(message, codedRefusalOf(error));
+    reportToolRefused(toolName, reason, args, detail);
 }
 /**
  * Which friction this result represents, counting the invitation if there is one.
@@ -256,25 +259,20 @@ export async function runTool(tool, deps, given, call) {
         // The project of the session a call ends, read while the session still exists: releasing a
         // tab removes it, and an unreadable project lost an unlinked user's cloud line.
         const endedIn = agentCall && ends ? safeRoot(() => sessionRoot(deps, sessionIdFromArgs(args))) : undefined;
-        const raw = await loggedTool(tool, deps, args, call);
+        // `reticle_run` is counted once, as the tool it reached; never another agent's call (rule 8).
+        const owner = currentDrivenBy() === undefined && ReticleTool.RUN !== tool.name;
+        const { raw, hint } = await inRepeatStreak(owner ? deps.attachId : undefined, tool.name, args, () => loggedTool(tool, deps, args, call));
         const attach = currentDrivenBy() === undefined ? deps.attachId : undefined;
         const root = attach === undefined
             ? undefined
             : safeRoot(() => sessionRoot(deps, sessionIdFromArgs(args)));
         // The app notes before this call, so a note it learns counts as memory written.
         const notesBefore = agentCall && root !== undefined ? readAppNotes(root) : [];
-        const answer = forTheAgent({
-            name: tool.name,
-            args,
-            result: raw,
-            attach,
-            root,
-            fold: NOTICE_FOLD,
-        });
+        const answer = withHintOn(forTheAgent({ name: tool.name, args, result: raw, attach, root, fold: NOTICE_FOLD }), hint);
         if (!agentCall) {
             return answer;
         }
-        runLedger.after(deps.now());
+        runLedger.after(deps.now(), deps.attachId);
         noteToolResult(runLedger, tool.name, args, raw);
         const notesAfter = root === undefined ? [] : readAppNotes(root);
         runLedger.memoryWritten(notesAfter.filter((note) => !notesBefore.includes(note)).length);
@@ -282,7 +280,10 @@ export async function runTool(tool, deps, given, call) {
         if (!ends || null === answer || 'object' !== typeof answer) {
             return answer;
         }
-        return { ...answer, ...runReportField(runLedger, endedIn ?? root, process.env, deps.now()) };
+        return {
+            ...answer,
+            ...runReportField(runLedger, endedIn ?? root, process.env, deps.now(), deps.attachId),
+        };
     }));
 }
 /** Advisories that become once-per-session notice lines. See agent/notices.ts. */
@@ -391,7 +392,7 @@ async function dispatchTool(tool, deps, args, call, seen = {}) {
             'value — a selector or an id rather than a document, or a slice of the text you need.';
         // Refused before the handler was ever entered, and still a refusal the agent has to recover
         // from. Reported here rather than at the return below, which this branch never reaches.
-        reportRefusal(tool.name, error);
+        reportRefusal(tool.name, args, error);
         return { error };
     }
     // One driver per tab. The Harness clicking through a page while the agent clicks too is two hands
@@ -399,7 +400,7 @@ async function dispatchTool(tool, deps, args, call, seen = {}) {
     const busy = ACTION_TOOLS.has(tool.name) ? harnessDriving(deps, args) : undefined;
     if (busy !== undefined) {
         const error = msgHarnessHasTheTab(busy);
-        reportRefusal(tool.name, error);
+        reportRefusal(tool.name, args, error);
         return { error };
     }
     // An ACTION is what gets abandoned. Counted here, against verifications, so "the agent drove the
@@ -448,7 +449,7 @@ async function dispatchTool(tool, deps, args, call, seen = {}) {
     // before Playwright invents a closed page. ready:true leases still hit this path.
     if (session?.versionSkew !== undefined && CDP_TOOLS.has(tool.name)) {
         const message = session.versionSkew;
-        reportRefusal(tool.name, message);
+        reportRefusal(tool.name, args, message);
         throw new Error(message);
     }
     // A ref that was handed out by a DIFFERENT tab, on a call that named no session. Refused here, at
@@ -466,7 +467,7 @@ async function dispatchTool(tool, deps, args, call, seen = {}) {
         if (wrongTab !== undefined) {
             // Refused before the handler was entered, so it is reported here — the same shape as the
             // oversized-argument refusal above.
-            reportRefusal(tool.name, wrongTab);
+            reportRefusal(tool.name, args, wrongTab);
             return { error: wrongTab };
         }
     }
@@ -516,7 +517,7 @@ async function dispatchTool(tool, deps, args, call, seen = {}) {
         const rewritten = rewriteClosedAsSkew(error, skewText);
         const toThrow = rewritten ?? error;
         const message = toThrow instanceof Error ? toThrow.message : String(toThrow);
-        reportRefusal(tool.name, message, toThrow);
+        reportRefusal(tool.name, args, message, toThrow);
         // The invitation on THIS path is the one `buildErrorPayload` attaches when it does not recognise
         // the error, and it was never counted — so the denominator excluded the commonest friction there
         // is. Gated on the payload actually carrying the ask, because a recognised error gets a recovery
@@ -580,7 +581,7 @@ async function dispatchTool(tool, deps, args, call, seen = {}) {
     // project the daemon was started in.
     session?.pushImpact?.(() => impactSnapshot(artifactRoot));
     if (resultIsError(raw)) {
-        reportRefusal(tool.name, raw.error);
+        reportRefusal(tool.name, args, raw.error);
     }
     else {
         noteToolServed();
@@ -660,6 +661,11 @@ async function dispatchTool(tool, deps, args, call, seen = {}) {
         })
         : undefined;
     const platformLine = platform === undefined ? nudge : nudge === undefined ? platform : `${platform}\n${nudge}`;
+    // The first call of this connection, in an unwired app with nothing attached: the offer the
+    // plugin's SessionStart hook makes, which `/reload-plugins` never fires. Always taken, so a call
+    // that already said it (the opened tab's notice, an empty list's `next_step`) still uses the once.
+    const firstOffer = agentCall && deps.attachId !== undefined ? deps.firstSessionOffer?.(deps.attachId) : undefined;
+    const offer = opened === undefined && !(NEXT_STEP_FIELD in (answer ?? {})) ? firstOffer : undefined;
     const drives = agentCall
         ? takeDriveNotes('string' === typeof answer?.['runId'] ? answer['runId'] : undefined)
         : [];
@@ -675,7 +681,8 @@ async function dispatchTool(tool, deps, args, call, seen = {}) {
         undelivered === undefined &&
         friction === undefined &&
         platformLine === undefined &&
-        next === undefined
+        next === undefined &&
+        offer === undefined
         ? raw
         : {
             // First, so a model that truncates a long result still reads it.
@@ -696,6 +703,7 @@ async function dispatchTool(tool, deps, args, call, seen = {}) {
             ...(update !== undefined ? { [EnvelopeKey.UPDATE_AVAILABLE]: update } : {}),
             ...(skew !== undefined ? { [EnvelopeKey.VERSION_SKEW]: skew } : {}),
             ...(platformLine !== undefined ? { [EnvelopeKey.PLATFORM]: platformLine } : {}),
+            ...(offer === undefined ? {} : { [EnvelopeKey.FIRST_SESSION_OFFER]: offer }),
             ...(0 === drives.length ? {} : { [EnvelopeKey.HARNESS]: drives.join('\n') }),
             ...(notes === undefined ? {} : { [EnvelopeKey.CONTROL]: notes }),
             ...(undelivered !== undefined

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 {};