@reticlehq/server 3.1.0 → 3.3.0

package/dist/surface/tools/args/numeric-bounds.js

@@ -38,8 +38,8 @@ export const MAX_TIMEOUT_MS = 120_000;
  *
  * This does not make long waits possible, and is not meant to — it makes the ADVERTISED bound one
  * that can actually be honoured. A caller that genuinely needs to outlast this polls: several short
- * waits, each of which returns a verdict. See #601 for the bounded-wait cursor that would let one
- * call do it properly.
+ * waits, each of which returns a verdict. `reticle_wait_for` does that for the caller: see
+ * `waitForTimeoutMsSchema` and `resumeAfter`.
  */
 const MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 export const MAX_BLOCKING_WAIT_MS = MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS - 5_000;
@@ -54,7 +54,7 @@ export const MAX_STATE_DEPTH = 256;
 /** A crawl that clicks forever is not a bound. */
 const MAX_CRAWL_STEPS = 500;
 /** Scroll-to-find steps. Default is 20; hundreds is searching, thousands is a hang. */
-export const MAX_SCROLLS = 200;
+const MAX_SCROLLS = 200;
 /** Fake-clock jump. One day of timers is a test; a billion ms is not. */
 const MAX_ADVANCE_MS = 86_400_000;
 /** Presenter idle window. One hour is a slow app; larger values never fire. */
@@ -71,6 +71,33 @@ export const cursorSchema = z.number().finite().int().nonnegative();
  * A wait budget in ms. 0 means evaluate now (documented on assert). Negative cannot be honoured.
  */
 export const timeoutMsSchema = z.number().finite().int().nonnegative().max(MAX_BLOCKING_WAIT_MS);
+/**
+ * The longest `reticle_wait_for` accepts, across as many calls as it takes. Ten minutes is a slow
+ * build or a queued job; an hour is a hang somebody forgot about.
+ */
+const MAX_RESUMABLE_WAIT_MS = 600_000;
+/**
+ * `reticle_wait_for`'s budget, which may exceed one call: it waits at most MAX_BLOCKING_WAIT_MS per
+ * call and hands back `resume_ms` for the rest (#601, from #635).
+ */
+export const waitForTimeoutMsSchema = z
+    .number()
+    .finite()
+    .int()
+    .nonnegative()
+    .max(MAX_RESUMABLE_WAIT_MS);
+/**
+ * What is left of a wait that stopped at the per-call limit, or undefined when there is nothing to
+ * resume: the predicate held, the whole budget fit in this call, or the wait ended for a reason
+ * waiting longer cannot change (the page went away, or the read could not be made).
+ */
+export function resumeAfter(requestedMs, perCallMs, verdict) {
+    if (verdict.pass || true === verdict.observationLost || verdict.inconclusive !== undefined) {
+        return undefined;
+    }
+    const left = requestedMs - perCallMs;
+    return left > 0 ? left : undefined;
+}
 /**
  * A count / cap. 0 means "return none", which is a real request. Negative is not.
  * Capped at the ring-buffer size so a `limit: 1e9` cannot pretend the buffer is larger than it is.

package/dist/surface/tools/assert/assert-grade.js

@@ -115,11 +115,23 @@ export function gradeOfPredicate(predicate) {
             return HonestyGrade.PRESENCE;
     }
 }
-/** Fold a combinator's branches on the ladder. No branches proves nothing, so it stays at the floor. */
+/**
+ * Fold a combinator's branches on the ladder. No branches proves nothing, so it stays at the floor.
+ *
+ * The floor is `NONE`, not `PRESENCE`. This sentence has been here since the function was written
+ * and the code returned one rung above it, which is the entire defect: `VACUOUS_GRADE`
+ * (`engine/src/evidence/verified.ts`) fires on `NONE`, so an empty combinator graded `PRESENCE`
+ * walked past the one guard whose job is refusing a green that rests on nothing — and reported
+ * `verified: "yes"` for a drive that asserted nothing at all.
+ *
+ * The schema refuses an empty combinator now, so this is the second defence rather than the only
+ * one. It is kept because the two stop different things: the schema stops it ENTERING through the
+ * documented door, and this stops it COUNTING if it is ever constructed rather than parsed.
+ */
 function combine(branches, pick) {
     const grades = branches.map(gradeOfPredicate);
     const first = grades[0];
     if (first === undefined)
-        return HonestyGrade.PRESENCE;
+        return HonestyGrade.NONE;
     return grades.reduce(pick, first);
 }

package/dist/surface/tools/assert/assert-verdict.js

@@ -1,4 +1,5 @@
 import { CaptureLoss, channelsRead, PredicateKind } from '@reticlehq/core';
+import { sessionVerdictFacts } from '../../../portal/session/session-verdict-facts.js';
 import { gapsForAction } from '@reticlehq/engine/evidence/instrumentation-gaps.js';
 import { noteSessionGaps } from '@reticlehq/engine/evidence/gap-ledger.js';
 import { declaresState } from '@reticlehq/engine/question/predicate/predicate-asks.js';
@@ -15,6 +16,7 @@ import { describeWaitTarget, namedNetIsInFlight } from '@reticlehq/engine/eviden
 import { inFlightRequestLabels, repeatedRequestLabels, } from '../act/settle-in-flight.js';
 import { gradeOfPredicate } from './assert-grade.js';
 import { assertSource } from './assert-source.js';
+import { VerdictAttribution, verdictAttributionOf } from '@reticlehq/core';
 /**
  * The honesty verdict for a plain `reticle_assert`.
  *
@@ -85,6 +87,7 @@ changeUndeclared) {
         currentDocumentId: session.currentDocumentId,
         currentEditEpoch: session.currentEditEpoch,
         appOrigin: session.url,
+        background: session.background,
         expectedFailures: declared.netFailures,
         namedNetUrls: declared.netUrls,
         renderProved: pass && declared.rendersContent,
@@ -97,13 +100,48 @@ changeUndeclared) {
     // rule — part of what happened was not seen — so both belong in `blindSpots`, which is the only
     // input `decideVerified` reads for that.
     const gap = transportGapNote(windowEvents);
+    /**
+     * The DURABLE half of the same question. `queryEvents` above falls through to the journal once the
+     * ring buffer has evicted, and that ledger refuses writes at its byte ceiling — so a window read
+     * from it after the ceiling was reached is missing whatever the cap turned away. The in-band
+     * marker cannot carry this: it is stamped with a `t`, and any `since` later than that filters it
+     * straight back out, leaving a partial answer that looks exactly like a complete one.
+     *
+     * Called optionally because `Session` is stubbed by cast in a great many suites, and a method
+     * added to it therefore arrives as a runtime `undefined` in files that have nothing to do with
+     * this change — the cost recorded at the top of `fake-session.ts`, four times over.
+     */
+    const ledgerClosed = undefined !== (await session.journalWriteLoss?.());
     // A consumer rule that crashed belongs here too: the engine ran with fewer rules than it claims,
     // so part of what happened may simply not have been looked for.
     const impeachingNotes = [impeaching.note, gap, ...crashedRuleNotes()].filter((n) => n !== undefined);
     const outcomePending = acceptedWriteLabels(windowEvents);
     const outcomeUnread = unreadWriteLabels(windowEvents);
-    const stillInFlight = inFlightRequestLabels(windowEvents);
+    const stillInFlight = inFlightRequestLabels(windowEvents, session.url, session.background);
     const effectiveInconclusive = inconclusive ?? (!pass ? session.preconditionFailure?.() : undefined);
+    /**
+     * Does a green here rest on the window having been COMPLETE?
+     *
+     * Not a refinement of the two losses below — it is what keeps either of them usable. Scarce loss
+     * is recorded for AGE eviction too, so `lostSince(0)` is true on any session past the 60s cutoff,
+     * and assert takes a caller-chosen `since` that is often 0. Impeaching every verdict over a wide
+     * window would make `unknown` the answer to everything, which is the failure this repo has already
+     * paid for once, when `unclean_capture` became the dominant cause of `unknown` in the field. A
+     * POSITIVE assertion that passed FOUND its evidence; things lost elsewhere do not unmake it.
+     */
+    const restsOnComplete = restsOnCompleteWindow(predicate);
+    /**
+     * The buffer evicted scarce evidence from this window.
+     *
+     * assert never consulted the buffer at all, on the reasoning that it "observes an already-open
+     * window" — but eviction happens on push regardless of who opened the window, so
+     * `{ console, absent: true }` returned `yes` over a window whose evidence was gone, which is
+     * absence of evidence read as evidence of absence. The act path needs no `restsOnComplete` guard:
+     * its cursor is the action's own.
+     */
+    const bufferLost = session.lostSince(since) && restsOnComplete;
+    /** The durable ledger refused writes, on a query path that read from it. Same rule, other store. */
+    const ledgerLost = ledgerClosed && restsOnComplete;
     const decision = decideVerified({
         pass,
         // What this claim needs to read, against what the page said it can see -- the protocol's
@@ -112,9 +150,8 @@ changeUndeclared) {
         // treating that silence as an empty set would refuse every claim from every older page.
         channelsRead: channelsRead(predicate.kind),
         ...(session.channels === undefined ? {} : { channelsObservable: session.channels }),
-        // So the unread-body remedy can check it applies to THIS page. Threaded rather than
-        // looked up inside decideVerified, which is pure and has no session.
-        ...(session.sdkVersion === undefined ? {} : { sdkVersion: session.sdkVersion }),
+        // Threaded rather than looked up: decideVerified is pure and has no session.
+        ...sessionVerdictFacts(session),
         // Same rule as the act path: the caller named a consequence, so a settlement-only finding must
         // not override it. A fix that lived on one half of the verdict surface would leave the other
         // half broken, and this is the tool agents call most.
@@ -127,27 +164,19 @@ changeUndeclared) {
         honesty: buildHonestyBlock({
             grade: gradeOfPredicate(predicate),
             attribution: 'window',
-            // Did the buffer evict SCARCE evidence belonging to this window, AND does a green here rest on
-            // the window being complete. assert never consulted the buffer at all, on the reasoning that it
-            // "observes an already-open window" — but eviction happens on push regardless of who opened the
-            // window, so `{ console, absent: true }` returned `yes` over a window whose evidence was gone,
-            // which is absence of evidence read as evidence of absence.
-            //
-            // The second half of the condition is not a refinement, it is what keeps this usable. Scarce
-            // loss is recorded for AGE eviction too, so `lostSince(0)` is true on any session past the 60s
-            // cutoff, and assert takes a caller-chosen `since` that is often 0. Impeaching every verdict
-            // over a wide window would make `unknown` the answer to everything — the failure this repo has
-            // already paid for once, when `unclean_capture` became the dominant cause of `unknown` in the
-            // field. The act path needs no such guard: its cursor is the action's own.
-            truncated: session.lostSince(since) && restsOnCompleteWindow(predicate),
+            truncated: bufferLost,
+            // The durable ledger stopped, and the SAME absence rule applies: a positive assertion that
+            // passed found its evidence, and events missing from the end of a file do not unmake it.
+            ledgerClosed: ledgerLost,
             coveragePartial: Coverage.PARTIAL === statement.coverage,
             ...(statement.note === undefined ? {} : { coverageNote: statement.note }),
             ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
-            // Which loss, as an enum, beside the prose.
+            // Which loss, as an enum, beside the prose. Ours before the page's, and the memory one before
+            // the disk one: `verification.uncleanLoss` takes the first, and a window that lost both is
+            // more usefully reported as the eviction, which is the one a caller can still drive around.
             losses: [
-                ...(session.lostSince(since) && restsOnCompleteWindow(predicate)
-                    ? [CaptureLoss.BUFFER_LOSS]
-                    : []),
+                ...(bufferLost ? [CaptureLoss.BUFFER_LOSS] : []),
+                ...(ledgerLost ? [CaptureLoss.JOURNAL_LOSS] : []),
                 ...(gap === undefined ? [] : [CaptureLoss.TRANSPORT_GAP]),
                 ...(impeaching.note === undefined ? [] : [CaptureLoss.BLIND_SPOT]),
             ],
@@ -190,6 +219,8 @@ changeUndeclared) {
         pass,
         lastActSource: session.lastAct.source(),
     });
+    // Who can act on this verdict, derived from the clause that decided it — see `attributedTo` below.
+    const attributedTo = verdictAttributionOf(decision.verifiedReason);
     return {
         decision: decision,
         contradictions,
@@ -199,6 +230,9 @@ changeUndeclared) {
             claim: describeWaitTarget(predicate),
             verified: decision.verified,
             ...(source === undefined ? {} : { source }),
+            // What answering this claim READ. Known here and nowhere later: a run folded from the journal
+            // has only what the journal kept, and without this it stamped `element` on every check.
+            kind: predicate.kind,
             // The three facts that make a verdict something other than a pass/fail line. All three were
             // known right here and none of them survived into the durable record, so nothing downstream
             // could report them however well this moment understood them.
@@ -213,6 +247,25 @@ changeUndeclared) {
             // arrived from a capture that could not be read, and only the first is worth asking about
             // again -- which is what makes a later answer a CORRECTION rather than a second opinion.
             reason: decision.verifiedReason,
+            /*
+             * WHOSE problem it is, in four values, finishing the sentence above.
+             *
+             * The reason names the deciding clause; this names who can act on it, which for an `unknown`
+             * is the only question the reader has. `environment` resolves by waiting, `could-not-see` by
+             * looking again with better coverage, `harness` by fixing Reticle or the call, and `code` is
+             * the only one that means go and change the app. Omitted on a proof, which has no owner.
+             *
+             * Derived here rather than inside the verdict: it is a pure function of a reason the engine
+             * already returns, and `core-coupling-only-shrinks` caps what the engine may borrow from core.
+             *
+             * Named `attributedTo`, not `attribution`, because two other things already carry that word:
+             * `honesty.attribution` a few lines up ("what the grade is attributed to" — the window), and
+             * `BugAttribution` in telemetry ("we found a defect, whose defect is it?"). Three meanings on
+             * one noun is how a reader ends up acting on the wrong one.
+             */
+            ...(attributedTo === undefined || VerdictAttribution.NONE === attributedTo
+                ? {}
+                : { attributedTo }),
             grade: gradeOfPredicate(predicate),
             couldNotSee: spots.map((spot) => spot.kind),
         },

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

@@ -1,7 +1,7 @@
 import { carryReticleIdentity } from './lease-tools.js';
 import { z } from 'zod';
 import { navigateResult } from './act/navigation/navigate-result.js';
-import { awaitArrival, idsAtTarget, ARRIVAL_TIMEOUT_MS, } from './act/navigation/navigate-arrival.js';
+import { absoluteTarget, awaitArrival, idsAtTarget, ARRIVAL_TIMEOUT_MS, } from './act/navigation/navigate-arrival.js';
 import { reloadResult } from './act/navigation/reload-result.js';
 import { waitForReconnect, RELOAD_RECONNECT_TIMEOUT_MS, } from '../../portal/session/session-reconnect.js';
 import { ReticleCommand } from '@reticlehq/core';
@@ -89,7 +89,8 @@ export const BROWSER_TOOLS = [
             // Sampled BEFORE dispatch, because that is the only moment it can be known. A session already
             // sitting on the target is not evidence that THIS navigation arrived — and the arrival scan,
             // which reads whatever is at the target afterwards, cannot tell the two apart on its own.
-            const priorIds = idsAtTarget(deps.sessions, url);
+            const target = absoluteTarget(url, session.url);
+            const priorIds = idsAtTarget(deps.sessions, target);
             session.beginAction(ReticleTool.NAVIGATE, { url });
             // Same floor as the reload path above, for the same reason: going to a new URL replaces the
             // document just as thoroughly. `beginAction` attributes events to this action; it does not move
@@ -103,7 +104,7 @@ export const BROWSER_TOOLS = [
                 // reticle_sessions itself. A refusal skips the wait: there is nothing to wait FOR.
                 const timeoutMs = asNumber(args['timeout_ms']) ?? ARRIVAL_TIMEOUT_MS;
                 const arrival = true === result.ok
-                    ? await awaitArrival(deps.sessions, url, { navigatedId: session.id, priorIds }, timeoutMs)
+                    ? await awaitArrival(deps.sessions, target, { navigatedId: session.id, priorIds }, timeoutMs)
                     : null;
                 return navigateResult(result, arrival, timeoutMs);
             }

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

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { projectForRoot } from '../../memory/project/project-for-root.js';
 import { coverageRegressed, observabilityOf } from '@reticlehq/engine/evidence/observability.js';
 import { foldFeatureCapture } from './feature-capture.js';
 import { foldToolHitRate } from './tool-hit-rate.js';
@@ -153,10 +155,11 @@ export function buildCoverageTools(toolNames) {
                 // The number, and the floor under it, together. A coverage figure that can only ever be
                 // reported and never contradicted is one an agent learns to satisfy rather than to earn.
                 const observability = observabilityOf(session.actedRefs(), gaps);
-                const best = await deps.project.bestObservability();
+                const project = projectForRoot(deps, sessionRoot(deps, sessionId));
+                const best = await project.bestObservability();
                 const regressed = coverageRegressed(best, observability);
                 if (observability.percent !== undefined) {
-                    await deps.project.raiseObservability(observability.percent);
+                    await project.raiseObservability(observability.percent);
                 }
                 return {
                     total: parseControls(tree).length,

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

@@ -2,36 +2,12 @@ import { z } from 'zod';
 import { runTool } from './invoke-tool.js';
 import { buildErrorPayload } from './error-recovery.js';
 import { mergedNameRedirect, mergedNameMessage, retiredToolNames } from './merged-name-redirect.js';
+import { CATALOGUE_SUMMARY_LENGTH, firstSentence } from './first-sentence.js';
 import { takeVersionSkewOnto } from '../../command/version/version-nudge.js';
 import { ReticleTool } from '@reticlehq/core';
 import { ADVERTISE_ALL_ENV } from './tool-surface.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
 import { isPredicateParam, predicateGrammar, } from '@reticlehq/engine/question/predicate/predicate-eval.js';
-/**
- * On-demand tool loading for MCP — the answer to the per-turn tool-definition tax.
- *
- * A normal MCP server advertises every tool's full description + schema, and the client re-sends
- * all of them to the model on EVERY turn. Measured here: Reticle at ~5.6k–14.6k tokens/turn just for
- * definitions, which dominates a real agent loop and only grows as the tool surface grows.
- *
- * The `dynamic` profile advertises just TWO meta-tools (~hundreds of tokens, fixed regardless of
- * how many real tools exist):
- * reticle_tools — discover. No args ⇒ a compact catalog (name + one-line summary) of every tool.
- * names:[...] ⇒ full description + params for just those tools, loaded on demand.
- * reticle_run — invoke any tool by name. On a bad/unknown call it returns that tool's params as a
- * hint, so the model self-corrects without ever needing the schema up front.
- *
- * The model lists once, loads the 2–3 tools it actually needs, and calls them — paying for tool
- * detail only when used, not every turn. Works with any MCP client (no client-side support needed).
- */
-/** First sentence (purpose) of a description — keeps the catalog one line per tool. */
-function firstSentence(description) {
-    const nl = description.indexOf('\n');
-    const base = nl >= 0 ? description.slice(0, nl) : description;
-    const dot = base.search(/\.\s/);
-    const sentence = dot >= 0 ? base.slice(0, dot + 1) : base;
-    return sentence.length > 140 ? `${sentence.slice(0, 139)}…` : sentence;
-}
 /** Compact param list from a tool's zod shape — name/required/description (the description already
  * carries the type and any enum hints, so no JSON-Schema machinery is needed). */
 function paramInfo(shape) {
@@ -49,6 +25,8 @@ function paramInfo(shape) {
 function unknownParamsError(toolName, unknown) {
     return `unknown ${1 === unknown.length ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')} — NOT applied, so any result would be an answer to a different question`;
 }
+/** The one `action` reticle_tools takes: every other tool on the surface is action-dispatched. */
+const TOOLS_LIST_ACTION = 'list';
 /** What to write instead — the one parameter reticle_tools declares, and the no-argument form. */
 const TOOLS_ARG_HINT = 'name the tools you want in `names`: reticle_tools { names: ["reticle_act_and_wait"] } — or call it with no arguments for the full catalog';
 /** The keys not declared by `shape`, in call order. */
@@ -73,6 +51,33 @@ export function buildDynamicTools(allTools, profile,
 callable) {
     const reachable = callable === undefined ? allTools : allTools.filter((tool) => callable.has(tool.name));
     const byName = new Map(reachable.map((t) => [t.name, t]));
+    const registered = new Map(allTools.map((tool) => [tool.name, tool]));
+    /**
+     * A name the catalogue cannot hand back as a callable tool.
+     *
+     * A redirect wins, because the capability moved and the old name is how an older instruction
+     * still asks for it. A name that is a real tool on a surface that cannot call it is the other
+     * case: `unknown tool` is what a typo gets, and a headline capability must not get the same
+     * sentence (#977). A name in neither set is a typo.
+     */
+    const explainAbsent = (name) => {
+        const moved = mergedNameRedirect(name);
+        if (moved !== undefined) {
+            return {
+                error: mergedNameMessage(name, moved),
+                tool: moved.tool,
+                ...(moved.action === undefined ? {} : { action: moved.action }),
+            };
+        }
+        if (callable !== undefined && registered.has(name)) {
+            return {
+                error: `${name} is a Reticle tool and this surface cannot call it. Restart the daemon with ` +
+                    `${ADVERTISE_ALL_ENV}=1, then call reticle_run { tool: "${name}", args }.`,
+                tool: name,
+            };
+        }
+        return { error: 'unknown tool' };
+    };
     // The profile is a DAEMON-startup decision, so an agent that exported RETICLE_TOOL_PROFILE into its
     // own environment sees no change and has, until now, no way to tell. Reported with the catalog.
     const profileBlock = profile === undefined
@@ -89,6 +94,10 @@ callable) {
             },
         };
     const toolsShape = {
+        action: z
+            .literal(TOOLS_LIST_ACTION)
+            .optional()
+            .describe('"list": the catalogue, same as no arguments.'),
         names: z
             .array(z.string())
             .optional()
@@ -135,7 +144,7 @@ callable) {
                 // turns "these are the tools" into "these are the tools I was shown".
                 const catalog = reachable.map((t) => ({
                     name: t.name,
-                    summary: firstSentence(t.description),
+                    summary: firstSentence(t.description, CATALOGUE_SUMMARY_LENGTH),
                 }));
                 // Names that USED to be tools, against the call that replaces each. Instructions written
                 // against an earlier release are a permanent fact of the product — `reticle_crawl` is still
@@ -171,15 +180,7 @@ callable) {
                     // `reticle_run` has answered a merged name with its replacement for a while; the tool
                     // asked to DISCOVER tools still said "unknown tool", which is the wrong answer in the one
                     // place an agent goes to resolve a name it is unsure of. Same redirect, same derivation.
-                    const moved = mergedNameRedirect(n);
-                    return moved === undefined
-                        ? { name: n, error: 'unknown tool' }
-                        : {
-                            name: n,
-                            error: mergedNameMessage(n, moved),
-                            tool: moved.tool,
-                            ...(moved.action === undefined ? {} : { action: moved.action }),
-                        };
+                    return { name: n, ...explainAbsent(n) };
                 }),
                 ...(carriesPredicate ? { predicateGrammar: predicateGrammar() } : {}),
             });
@@ -190,9 +191,10 @@ callable) {
         args: z.record(z.unknown()).optional().describe('Arguments object for that tool.'),
         // Accepted AND FORWARDED, not merely tolerated. reticle_run is the only way to reach an
         // unadvertised tool, so on a machine running several projects it has to be aimable — and
-        // `sessionId` is the shape an agent already uses on every other tool. Reported across 6 of 6
-        // apps: it took this key, dropped it, resolved by the daemon's cwd project, and failed with
-        // "no browser session for project X" while naming the very session it had been given.
+        // `sessionId` is the shape an agent already uses on every other tool. Reported from the field
+        // against every app it was tried on: it took this key, dropped it, resolved by the daemon's cwd
+        // project, and failed with "no browser session for project X" while naming the very session it
+        // had been given.
         sessionId: z
             .string()
             .optional()
@@ -232,14 +234,9 @@ callable) {
                 getSessionMetrics().recordUnknownTool(name);
                 // ...and for 22 of those names the capability DOES exist, it just moved when tools merged.
                 // Answering "unknown tool" there is simply wrong; see merged-name-redirect.
-                const moved = mergedNameRedirect(name);
-                if (moved !== undefined) {
-                    return {
-                        error: mergedNameMessage(name, moved),
-                        tool: moved.tool,
-                        ...(moved.action === undefined ? {} : { action: moved.action }),
-                    };
-                }
+                const absent = explainAbsent(name);
+                if ('unknown tool' !== absent.error)
+                    return absent;
                 return { error: `unknown tool '${name}'`, available: reachable.map((t) => t.name) };
             }
             // The outer aim, forwarded ONLY to a tool that declares a session — injecting it into one that

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

@@ -66,6 +66,12 @@ export declare const RECOVERY: {
     readonly COMMAND_TIMEOUT: string;
     readonly FLOW_STEP_MISSING: string;
     readonly NO_POOL: string;
+    /**
+     * The two ways a platform answer can refuse a drive. Neither is a fault, and both were telling the
+     * agent that a perfectly understood refusal might be a defect in Reticle — which is how a person
+     * who deliberately switched the harness off gets a bug report filed about their own decision.
+     */
+    readonly HARNESS_OFF: string;
 };
 /**
  * The actionable next move for a known error message, or undefined when none is recognized.

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

@@ -199,6 +199,15 @@ export const RECOVERY = {
         chromiumInstallCommand(bundledPlaywrightVersion()) +
         '` if that is what is missing. Meanwhile drive ' +
         'a tab the human already has open — reticle_sessions lists them.',
+    /**
+     * The two ways a platform answer can refuse a drive. Neither is a fault, and both were telling the
+     * agent that a perfectly understood refusal might be a defect in Reticle — which is how a person
+     * who deliberately switched the harness off gets a bug report filed about their own decision.
+     */
+    HARNESS_OFF: 'A human turned autonomous driving off for this project, or has not claimed the free harness ' +
+        'months. This is a deliberate refusal and there is nothing to report: drive the app yourself ' +
+        'through the MCP tools — reticle_navigate, then reticle_act_and_wait with an `until` — which is ' +
+        'the same verification without a model driving it.',
 };
 /**
  * Which OWNER each recovery belongs to, for `tool_refused`.
@@ -236,6 +245,8 @@ const REASON_OF = {
     WRONG_TARGET: RefusalReason.UNSUPPORTED,
     BAD_ARGUMENTS: RefusalReason.BAD_ARGS,
     INVALID_NAME: RefusalReason.BAD_ARGS,
+    // Nothing about the app or the call is wrong; the feature is switched off or unpaid for.
+    HARNESS_OFF: RefusalReason.UNSUPPORTED,
 };
 /** 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]]));
@@ -248,6 +259,10 @@ const RULES = [
     { match: /no baseline named/i, hint: RECOVERY.MISSING_BASELINE },
     { match: /no (?:active|compiled) recording named/i, hint: RECOVERY.MISSING_RECORDING },
     { match: /pairing token is required/i, hint: RECOVERY.TOKEN_REQUIRED },
+    {
+        match: /Autonomous driving is turned OFF|no harness entitlement/i,
+        hint: RECOVERY.HARNESS_OFF,
+    },
     // Three conditions the daemon understands perfectly and still asked for a bug report about. Each
     // needs its own rule: none of them contains "no browser session connected" (the scope miss is
     // "no browser session FOR project 'x'", which is the opposite claim — sessions exist).

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

@@ -11,9 +11,11 @@
  * them deterministically with no model in the loop at all.
  */
 import { z } from 'zod';
-import { ReticleTool } from '@reticlehq/core';
+import { ReticleTool, asRecord } from '@reticlehq/core';
 import { stepCountSchema } from './args/numeric-bounds.js';
-import { exploreApp, harnessAvailable, MSG_NO_HARNESS_KEY } from './harness-explore.js';
+import { exploreApp, harnessAvailable, withLinkedCredential, MSG_NO_HARNESS_KEY, } from './harness-explore.js';
+import { DRIVER_NAMES } from '../../features/harness/drivers.js';
+import { describeDrive, replayedFlows } from '../../features/harness/drive-report.js';
 import { StopReason } from '../../features/harness/harness.js';
 export const EXPLORE_TOOLS = [
     {
@@ -27,6 +29,10 @@ export const EXPLORE_TOOLS = [
             maxSteps: stepCountSchema
                 .optional()
                 .describe('Ceiling on model turns. Bounds cost, not value — the drive is graded however it ends.'),
+            driver: z
+                .enum(DRIVER_NAMES)
+                .optional()
+                .describe('Which model drives. An unconfigured one is an error, never a substitution, so an A/B cannot measure the same driver twice. Omit for the default.'),
             sessionId: z
                 .string()
                 .optional()
@@ -35,9 +41,24 @@ export const EXPLORE_TOOLS = [
         // Everything the handler returns has to be declared, or a schema-aware client never sees it.
         outputSchema: {
             stopReason: z.string(),
+            /** Which driver actually drove, so a comparison can never misattribute its own result. */
+            driver: z.string(),
             steps: z.number(),
             savedFlows: z.array(z.string()),
-            /** The model's own account of what it drove. NOT a verdict — the flows are the evidence. */
+            /** Flows that already existed and were driven and written again. A second run's ordinary result. */
+            rewroteFlows: z.array(z.string()),
+            /**
+             * What the drive set out to do, read from `.reticle` BEFORE it started — every recorded
+             * journey with the consequence that must still hold, and the declared intent nobody has
+             * tested. Returned so the caller can see the drive was aimed rather than wandering.
+             */
+            plan: z.object({ summary: z.string(), steps: z.array(z.unknown()) }),
+            /**
+             * What the drive did, derived from the calls it made and the verdicts the engine returned.
+             *
+             * Not the driver's narration. A driver that cannot write a sentence used to leave this empty,
+             * and a driver that can is the one witness with a reason to round "unknown" up to "worked".
+             */
             summary: z.string(),
             /** Present when the drive broke: a model that would not answer, a wedged browser. */
             error: z.string().optional(),
@@ -52,28 +73,80 @@ export const EXPLORE_TOOLS = [
             note: z.string().optional(),
         },
         handler: async (deps, args) => {
-            if (!harnessAvailable(process.env))
+            // The credential `reticle link` already filed counts as configured, so somebody who has
+            // signed in and linked does not also have to export a key by hand.
+            const env = await withLinkedCredential(deps, process.env);
+            if (!harnessAvailable(env))
                 throw new Error(MSG_NO_HARNESS_KEY);
             const persona = args['persona'];
             const maxSteps = args['maxSteps'];
             const sessionId = args['sessionId'];
-            const { drive, savedFlows } = await exploreApp(deps, process.env, {
+            const driver = args['driver'];
+            const { drive, savedFlows, rewroteFlows, driverName, plan } = await exploreApp(deps, env, {
                 ...('string' === typeof persona ? { focus: persona } : {}),
                 ...('number' === typeof maxSteps ? { maxSteps } : {}),
                 ...('string' === typeof sessionId ? { sessionId } : {}),
+                ...('string' === typeof driver ? { driverName: driver } : {}),
             });
             return {
                 stopReason: drive.stopReason,
+                driver: driverName,
                 steps: drive.steps,
                 savedFlows: [...savedFlows],
-                summary: drive.summary,
+                rewroteFlows: [...rewroteFlows],
+                plan: { summary: plan.summary, steps: [...plan.steps] },
+                // Derived, not narrated. The driver's own `summary` is appended only when it said
+                // something — it is the one part of this a model authored, so it goes last and is labelled.
+                summary: [
+                    describeDrive(drive.toolCalls, [...savedFlows, ...rewroteFlows]),
+                    ...(0 === drive.summary.length ? [] : [`The driver's own account: ${drive.summary}`]),
+                ].join('\n'),
                 ...(drive.error === undefined ? {} : { error: drive.error }),
                 usage: drive.usage,
-                ...(0 === savedFlows.length ? { note: NOTHING_RECORDED[drive.stopReason] } : {}),
+                // The note only fires when the drive left NOTHING behind. A rewritten flow is a flow: it
+                // replays, it proves what it asserts, and telling its author that "nothing will replay" is
+                // a lie this tool used to tell on every second run.
+                /*
+                 * The note fires only when the run left NOTHING behind — and a run that REPLAYED left
+                 * plenty. Sixteen recorded journeys re-proved for zero model tokens is the cheap half of
+                 * the plan doing its job, and telling its author to "raise maxSteps" reads as a failure.
+                 */
+                ...(0 === savedFlows.length &&
+                    0 === rewroteFlows.length &&
+                    0 === replayedFlows(drive.toolCalls).length
+                    ? { note: `${NOTHING_RECORDED[drive.stopReason]}${failureDetail(drive)}` }
+                    : {}),
             };
         },
     },
 ];
+/**
+ * The tool failure behind an empty drive, when there was one.
+ *
+ * "The drive ran out of steps before saving a flow" is true of a drive that explored happily and ran
+ * long, and ALSO of one that reached its save and was refused — and those need opposite responses.
+ * Without this the two are indistinguishable from outside the daemon, which cost a full debugging
+ * session: a driver whose `reticle_record{stop}` was rejected for a missing argument retried until
+ * the budget ended, and the only thing the caller ever saw was the advice to raise `maxSteps`.
+ */
+function failureDetail(drive) {
+    const failed = drive.toolCalls.filter((call) => call.isError);
+    const last = failed[failed.length - 1];
+    if (last !== undefined) {
+        const message = asRecord(last.result)['error'];
+        return ` ${String(failed.length)} tool call(s) failed during the drive; the last was ${last.name}: ${'string' === typeof message ? message : 'no message'}`;
+    }
+    // Nothing threw, so the interesting case left is a save that was ACCEPTED and wrote nothing —
+    // an empty recording reports success, and from outside the daemon that is indistinguishable from
+    // a drive that never reached its save at all.
+    const saves = drive.toolCalls.filter((call) => ReticleTool.FLOW_SAVE === call.name);
+    const save = saves[saves.length - 1];
+    if (save !== undefined) {
+        const result = asRecord(save.result);
+        return ` The flow save was accepted but kept nothing: ${JSON.stringify({ stepCount: result['stepCount'], empty: result['empty'], warning: result['warning'] })}.`;
+    }
+    return ` The drive never reached a flow save (${String(drive.toolCalls.length)} tool calls made).`;
+}
 /**
  * What an empty drive means, said rather than left for the caller to infer.
  *