@reticlehq/server 3.1.0 → 3.2.0

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

@@ -97,6 +97,18 @@ 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);
@@ -104,6 +116,29 @@ changeUndeclared) {
     const outcomeUnread = unreadWriteLabels(windowEvents);
     const stillInFlight = inFlightRequestLabels(windowEvents);
     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
@@ -127,27 +162,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]),
             ],

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) {
@@ -73,6 +49,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
@@ -135,7 +138,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 +174,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 +185,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 +228,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.
  *

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

@@ -55,6 +55,15 @@ function sessionFacts(deps, sessionId) {
         return { driven };
     }
 }
+/** Said when a report arrives with no body at all. Names both accepted fields so the retry can work. */
+const NO_BODY_REASON = 'the report has no body — send it as `text` (or `summary`, which is the same field). Nothing was filed.';
+/** `text`, or the `summary` alias, whichever arrived. Empty when neither did — the handler refuses. */
+function feedbackBody(args) {
+    const text = asString(args['text'])?.trim();
+    if (text !== undefined && '' !== text)
+        return text;
+    return asString(args['summary'])?.trim() ?? '';
+}
 export const FEEDBACK_TOOLS = [
     {
         name: ReticleTool.FEEDBACK,
@@ -72,8 +81,22 @@ export const FEEDBACK_TOOLS = [
                 .describe('bug = a Reticle tool returned a wrong or broken result; gap = Reticle could not observe something you needed at all; ambiguity = the verification ran but you could not tell pass from fail; feature_request = something that does not exist and would have helped; improvement = something that exists but is awkward or inefficient; experience = something worked notably well and is worth keeping (pair it with `rating`).'),
             text: z
                 .string()
-                .min(1)
+                .optional()
                 .describe('For a failure: the root-cause analysis — the call you made, what you expected, what you got, and why Reticle is at fault. For a request: what you want, in your own words.'),
+            /**
+             * `text` under the name agents reach for unprompted.
+             *
+             * Incident: field reports of a call carrying a summary and a trace coming back
+             * "String must contain at least 1 character(s)" and being lost. The body had been put in
+             * `summary` — a field this tool never had. The MCP SDK validates input BEFORE the handler, so
+             * a required `text` made those calls unreachable and unanswerable: no handler ran, nothing
+             * could explain the rejection, and the report was dropped.
+             *
+             * So `text` is optional and this is its alias; the handler takes whichever arrived and refuses
+             * — with both names in the reason — only when neither did. Widening the schema is what buys
+             * the chance to say anything at all.
+             */
+            summary: z.string().optional().describe('Alias for `text`; send either.'),
             need: z
                 .string()
                 .optional()
@@ -124,10 +147,26 @@ export const FEEDBACK_TOOLS = [
             model: 'claude-opus-4',
         },
         handler: async (deps, args) => {
+            // Refuse here rather than in core's schema: core validates a REPORT, which has one body field
+            // and knows nothing about the `summary` alias, so its rejection reads "String must contain at
+            // least 1 character(s)" and names neither field. That sentence is what agents were given when
+            // their report was dropped, and it is unactionable — the agent cannot tell which of eight
+            // arguments was wrong.
+            const body = feedbackBody(args);
+            if ('' === body) {
+                return {
+                    sent: false,
+                    accepted: false,
+                    reason: NO_BODY_REASON,
+                    redacted: [],
+                    context: undefined,
+                    note: 'NOT accepted (see reason). Tell the human what you found so it is not lost.',
+                };
+            }
             const receipt = await submitFeedback({
                 source: FeedbackSource.AGENT,
                 kind: asString(args['kind']),
-                text: asString(args['text']) ?? '',
+                text: body,
                 ...optionalText(args, 'trace'),
                 ...optionalText(args, 'need'),
                 ...optionalText(args, 'impact'),
@@ -187,6 +226,14 @@ export const VERDICT_TOOLS = new Set([
     // inflate the count.
     ReticleTool.VERIFY,
     ReticleTool.RECONCILE,
+    // Replaying ONE saved flow proves a journey still works, which is a verification by any reading a
+    // user would give the word — and it was in neither the numerator nor the denominator. It matched
+    // no name tripwire (`/assert|verify/`), it declares no `verified` field for the shape guard to
+    // catch, and its own status vocabulary spells itself `ok | drift | error`, so the three
+    // independent things that could have noticed all said nothing. `verificationOf` maps that
+    // vocabulary; `error` stays UNKNOWN, because a flow that could not load is not a verdict about
+    // anybody's app.
+    ReticleTool.FLOW_REPLAY,
 ]);
 /**
  * Verifications between re-offers of the prompt, and how many times we will ever offer it.

package/dist/surface/tools/first-sentence.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The opening sentence of a tool description, for the two surfaces that show a summary.
+ *
+ * There were two copies of this, and only one of them knew about abbreviations. The MCP surface's
+ * copy masks `e.g.` and friends before looking for a sentence end; the tool catalogue's private
+ * copy did not, so `reticle_session` reached every agent as
+ *
+ *   Drive or inspect the SESSION itself, chosen by action: "tune" adjusts the presenter session (e.g.
+ *
+ * and stopped there. Everything after the abbreviation was cut, including `"yield" hands the tab
+ * back to the human and is MANDATORY before you stop driving`. The catalogue is the surface an
+ * agent reads to find out what exists, so the one instruction the product calls mandatory was
+ * missing from the only place it would have been discovered.
+ *
+ * This is the same defect the MCP copy already carried a long comment about, reappearing in a
+ * second copy written without the fix. So there is one implementation now, and the thing the two
+ * callers genuinely disagree about -- how much room a line gets -- is a parameter rather than a
+ * reason to fork the logic again.
+ */
+/** What the MCP surface allows a one-line description. */
+export declare const MCP_SUMMARY_LENGTH = 160;
+/** What the catalogue allows, which is tighter: it prints one line per tool, for every tool. */
+export declare const CATALOGUE_SUMMARY_LENGTH = 140;
+export declare function firstSentence(description: string, maxLength?: number): string;