@reticlehq/server 3.2.0 → 3.4.0

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

@@ -7,7 +7,7 @@ import { z } from 'zod';
 import { aliasParam } from './args/alias-args.js';
 import { CONSOLE_ATTACH_NOTE, CONSOLE_LEVELS, ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind, Verified, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
-import { countSchema, cursorSchema, httpStatusSchema, timeoutMsSchema, windowMsSchema, } from './args/numeric-bounds.js';
+import { countSchema, cursorSchema, httpStatusSchema, timeoutMsSchema, waitForTimeoutMsSchema, resumeAfter, MAX_BLOCKING_WAIT_MS, windowMsSchema, } from './args/numeric-bounds.js';
 import { buildReactionReport } from '@reticlehq/engine/question/reaction.js';
 import { findContradictions } from '@reticlehq/engine/disagreement/contradictions.js';
 import { evaluatePredicate, waitForPredicate, PredicateSchema, } from '@reticlehq/engine/question/predicate/predicate.js';
@@ -16,7 +16,7 @@ import { WALL_CLOCK } from '../../portal/session/timing/wall-clock.js';
 import { parsePredicate } from '@reticlehq/engine/question/predicate/predicate-parse.js';
 import { matchNet, matchConsole, isConsoleEvent, eventMatchesFilters, netEmptyHint, consoleEmptyHint, reconcileNet, projectNetCall, projectConsoleLog, withoutUrlRaw, } from '@reticlehq/engine/window/event-filters.js';
 import { applyEventBudget, costHint, withSizeCost, DEFAULT_OBSERVE_EVENT_LIMIT, DEFAULT_QUERY_LIMIT, } from '../../portal/session/output-budget.js';
-import { annotateStarvedFailure, healthEnvelope, bufferEnvelope, } from '../../portal/session/session-health.js';
+import { annotateStarvedFailure, currentOf, healthEnvelope, bufferEnvelope, } from '../../portal/session/session-health.js';
 import { assertsDerivedIpcStatus, DERIVED_IPC_STATUS_ADVICE, isPresenceOnlyAssertion, PRESENCE_ONLY_ADVICE, } from './assert/assert-grade.js';
 import { assertVerdict } from './assert/assert-verdict.js';
 import { followLostObservation } from './act/act-observation.js';
@@ -33,6 +33,7 @@ import { withControl } from '../../portal/session/control-envelope.js';
 import { asNumber, asRecord, asString } from '@reticlehq/core';
 import { intentArg, sessionIdShape, commandOrThrow } from './tool-kit.js';
 import { gradeOfPredicate } from './assert/assert-grade.js';
+import { captureAssertion } from '../../language/flows/replay.js';
 /**
  * Evidence-completeness block: present on observe/network/console only when the ring buffer has
  * evicted events, so a "no such event" answer is distinguishable from "I dropped it" (issue #27).
@@ -172,6 +173,7 @@ export const OBSERVE_TOOLS = [
                 currentDocumentId: session.currentDocumentId,
                 currentEditEpoch: session.currentEditEpoch,
                 appOrigin: session.url,
+                background: session.background,
                 ...(judgingTheAct ? { ...session.lastAct.effect(), actionSince: actCursor } : {}),
             });
             // carry session health — a throttled tab means the observed timeline may be incomplete.
@@ -193,15 +195,19 @@ export const OBSERVE_TOOLS = [
             predicate: PredicateSchema.optional().describe('Predicate to wait for: { signal }, { net }, { element }, { kind: "net", ok: false } (assert on the OUTCOME — the honest field for IPC, which has no status code), { kind: "state", store, path, equals } (assert a registered store\'s value directly — the source of truth no DOM read can reach; equals takes a literal or { $gte | $contains | $length } pattern), { kind: "settled", quietMs } (deterministic network + DOM idle — prefer this over a fixed sleep), or a combination via allOf/anyOf.'),
             // Same concept, the neighbouring tool's name. See alias-args.ts.
             until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
-            timeout_ms: timeoutMsSchema
+            timeout_ms: waitForTimeoutMsSchema
                 .optional()
-                .describe('Maximum wait in milliseconds. Default: 4000. Capped at 55000: your MCP client aborts the request before a longer wait can return, so a bound above this would be advertised and not deliverable. To outlast it, poll — several short waits, each of which returns a verdict.'),
+                .describe(`Maximum wait in milliseconds. Default: 4000, up to 600000. One call waits at most ${String(MAX_BLOCKING_WAIT_MS)} ms, because your MCP client aborts a longer request; past that it returns resume_ms, and you call again with timeout_ms: resume_ms and the same since to keep waiting.`),
             since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior reticle_act — scopes the wait to events after that act.'),
             ...sessionIdShape,
         },
         outputSchema: {
+            resume_ms: z
+                .number()
+                .optional()
+                .describe('Present when this call stopped at the per-call limit before the predicate was seen. Call again with timeout_ms set to this, the same predicate and the same since, to keep waiting.'),
             pass: z.boolean(),
             evidence: z.unknown().optional(),
             failureReason: z.string().optional(),
@@ -239,7 +245,9 @@ export const OBSERVE_TOOLS = [
                 .describe('Where the code behind this verdict lives, as `file:line`. For an element/text assertion it is the matched element itself; for a FAILING signal/net/state assertion — which has no element to point at — it is the control last acted on, where the handler that should have fired lives. OMITTED when neither is known: this tool never borrows an unrelated location.'),
         },
         handler: async (deps, args) => {
-            const waitBudget = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
+            const requestedMs = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
+            // One call never blocks past what the client allows; the rest comes back as resume_ms.
+            const waitBudget = Math.min(requestedMs, MAX_BLOCKING_WAIT_MS);
             // Spend the budget waiting for the APP as well as for the predicate. See resolve-within.
             let session = await resolveSessionWithin(deps.sessions, asString(args['sessionId']), waitBudget, WALL_CLOCK);
             // `until` is act_and_wait's name for this — see alias-args.ts.
@@ -275,6 +283,7 @@ export const OBSERVE_TOOLS = [
                 ...annotateStarvedFailure(session, verdict),
                 ...assertionSource(session, predicate, verdict),
                 ...(followed.followed ? { sessionId: session.id } : {}),
+                ...((resume) => (resume === undefined ? {} : { resume_ms: resume }))(resumeAfter(requestedMs, waitBudget, verdict)),
                 ...healthEnvelope(session),
                 ...bufferEnvelope(session),
             });
@@ -294,7 +303,7 @@ export const OBSERVE_TOOLS = [
                 '{ net, urlContains|method|status|count|bodyMatches|bodyContains|requestBodyContains|requestBodyMatches } ' +
                 '{ state, path|equals } { route, pathname (exact) | contains (path+query+hash) } ' +
                 '{ element, testid|role|text } { text } { console, level|contains|absent } { animation, name } ' +
-                '{ settled } — combine with { allOf | anyOf | not }. Prefer a signal/net/state consequence ' +
+                '{ settled } { compare, left, right } — combine with { allOf | anyOf | not }. Prefer a signal/net/state consequence ' +
                 'over element/text presence.'),
             until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
             timeout_ms: timeoutMsSchema
@@ -438,6 +447,13 @@ export const OBSERVE_TOOLS = [
             // destroys — see runs/run-context.ts. Recorded WITHOUT an attribution window: this tool drives
             // nothing, so no event it observed was caused by it.
             session.recordAction(ReticleTool.ASSERT, asRecord(args), verdictEffect);
+            // A passing check over the default window (since the last act) is proof of that act, so it
+            // joins that step in the recording — otherwise "act, then assert" saves a bare click. An
+            // explicit `since` may reach back past the last step, where replay would not find it. The
+            // store itself refuses when a navigation came after that step: see RecordingStore.markNavigated.
+            if (Verified.YES === decision['verified'] && args['since'] === undefined) {
+                captureAssertion(deps.recordings, predicate);
+            }
             return withControl(session, {
                 ...decision,
                 ...annotateStarvedFailure(session, verdict),
@@ -454,7 +470,7 @@ export const OBSERVE_TOOLS = [
                 ...coverage,
                 // The SAME pointer the journal keeps, not a second lookup — one verdict, one file:line.
                 ...(verdictEffect.source === undefined ? {} : { source: verdictEffect.source }),
-                ...healthEnvelope(session),
+                ...healthEnvelope(currentOf(deps.sessions, session)),
                 ...bufferEnvelope(session),
             });
         },

package/dist/surface/tools/real-input-attempt.d.ts

@@ -22,11 +22,6 @@
 import { ActionType, InputModeReason } from '@reticlehq/core';
 import type { Session } from '../../portal/session/session.js';
 import { type ToolDeps } from './tool-kit.js';
-/**
- * Expand a leading `~` against the caller's home directory. Absolute and relative paths pass
- * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
- */
-export declare function expandUserPath(rawPath: string, home: string): string;
 /**
  * If the action is `upload` AND the inner args carry `path`, read the file from disk and rewrite
  * the args to `{ content, name, type, __base64: true }` before the ACT command reaches the browser.

package/dist/surface/tools/real-input-attempt.js

@@ -99,7 +99,7 @@ const UPLOAD_MAX_BYTES = Math.floor((TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / (4 / 3
  * Expand a leading `~` against the caller's home directory. Absolute and relative paths pass
  * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
  */
-export function expandUserPath(rawPath, home) {
+function expandUserPath(rawPath, home) {
     if ('~' === rawPath)
         return home;
     if (rawPath.startsWith('~/') || rawPath.startsWith('~\\'))

package/dist/surface/tools/tool-kit.d.ts

@@ -222,6 +222,11 @@ export declare const EnvelopeKey: {
     readonly VERIFY_NEXT: "verify_next";
     /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
     readonly FEEDBACK_INVITE: "feedback_invite";
+    /**
+     * The same moment, for the HUMAN: a call with the founder, or an email through `identify`. The
+     * agent is told to offer it and never to book or submit anything itself.
+     */
+    readonly TALK_TO_US: "talk_to_us";
     /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
     readonly VERSION_SKEW: "version_skew";
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */

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

@@ -28,7 +28,7 @@ export const intentArg = z
     'BAD: "P1 step 5", "drive 2 of 2", "same as before the fix", "the board renders cleanly" — these name a session, ' +
     'a step number or nothing checkable, and the person reading them later has none of that context. ' +
     'This is shared memory: it is pooled per project and later agents read it back to avoid re-deriving what you just established. ' +
-    'Recorded in .reticle/intent.json, the same ledger reticle_intent writes, and marked proved by this verdict if it passes.');
+    'Recorded in .reticle/intent/, the same ledger reticle_intent writes, and marked proved by this verdict if it passes.');
 export const sessionIdShape = {
     sessionId: z
         .string()
@@ -75,6 +75,11 @@ export const EnvelopeKey = {
     VERIFY_NEXT: 'verify_next',
     /** The contextual "tell us what just went wrong" invitation. Same story, same release. */
     FEEDBACK_INVITE: 'feedback_invite',
+    /**
+     * The same moment, for the HUMAN: a call with the founder, or an email through `identify`. The
+     * agent is told to offer it and never to book or submit anything itself.
+     */
+    TALK_TO_US: 'talk_to_us',
     /** SDK/daemon version skew — often the one fact that explains everything else in the session. */
     VERSION_SKEW: 'version_skew',
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */

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

@@ -395,11 +395,23 @@ export function describeToolSurface(active, requested) {
 export function defaultAdvertisedNames() {
     const surface = resolveToolSurface();
     const names = [...filterToolNames(surface)];
-    // `reticle_run` is real only where the surface keeps a dispatch hatch. The merged surface ships
-    // the catalogue without one, and naming a hatch that is not there is the same defect one level in.
-    return TOOL_SURFACE.MERGED === surface
-        ? [...names, ReticleTool.TOOLS]
-        : [...names, ReticleTool.TOOLS, ReticleTool.RUN];
+    /*
+     * Both meta tools, on every surface, because that is what the MCP actually advertises.
+     *
+     * This used to withhold `reticle_run` from the merged surface, reasoning that "naming a hatch
+     * that is not there is the same defect one level in". The reasoning is sound and the premise was
+     * false: `buildDynamicTools` returns `[reticle_tools, reticle_run]` unconditionally and
+     * `advertisedTools` appends both to every surface, so the hatch has always been there. Measured
+     * against a live daemon on the default surface: `reticle_run` is advertised, and
+     * `reticle_run { tool: "reticle_lease" }` reaches `reticle_lease`.
+     *
+     * Two functions answering one question, and this was the one the MCP never called. It is read by
+     * `server-instructions`, which gates "Everything else is one hop: reticle_tools lists it,
+     * reticle_run calls it" on this list - so agents were told the hatch was absent from a surface
+     * carrying it, and six recovery messages were later rewritten to match the lie.
+     * `advertised-names-are-real.test.ts` now pins this to `advertisedTools` itself.
+     */
+    return [...names, ReticleTool.TOOLS, ReticleTool.RUN];
 }
 /** The advertised NAME set for a surface, without needing the tool table. */
 function filterToolNames(surface) {

package/dist/surface/tools/tools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { NoSessionAction, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { DiscoveryInvite, AttrNamesSchema, EventType, NoSessionAction, QueryBy, ReticleCommand, SnapshotMode, } from '@reticlehq/core';
 import { ReticleTool } from '@reticlehq/core';
 import { withSizeCost } from '../../portal/session/output-budget.js';
 import { applySnapshotDelta, SnapshotCache } from './read/snapshot-delta.js';
@@ -109,7 +109,7 @@ export const RAW_TOOLS = [
                     lastOutage: z.object({ startedMs: z.number(), durationMs: z.number() }).optional(),
                 })
                     .optional()
-                    .describe('Present only when this tab has dropped and reconnected at least once: how long it has been attached in total, how many outages occurred, and when the last one started and how long it lasted. A verdict over this window spans a gap where nothing was observed.'),
+                    .describe('Continuity of the SDK-to-daemon LINK for this tab, present for any tab the daemon has a record of: how long this attachment has lasted, how many times it dropped and came back, and when the last gap started and how long it lasted. `outages > 0` means a verdict over this window spans a gap where nothing was observed. These are link counters, NOT app health: they say nothing about whether the page origin is still serving, so a tab whose dev server has died reports `outages: 0` with a growing `connectedSinceMs` and is not evidence the app is up.'),
             }))
                 .describe('Connected browser sessions with health state. `projectId` groups sessions by app (stable across port changes); `leased` marks a pool-managed headless context vs a human tab.'),
             why: z
@@ -125,6 +125,10 @@ export const RAW_TOOLS = [
             })
                 .optional()
                 .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of daemon_split | start_dev_server | run_init | open_app | reopen_app. `daemon_split` outranks the rest and means the app IS running and instrumented, on a DIFFERENT daemon than the one you are attached to — do not start or re-init anything, read `reason`."),
+            talk_to_us: z
+                .string()
+                .optional()
+                .describe('Present ONLY when `sessions` is empty: a call with the founder for the person you are working with. Offer it; never act on it.'),
             lastKnown: z
                 .object({
                 sessionId: z.string(),
@@ -158,6 +162,8 @@ export const RAW_TOOLS = [
                     ...(why === undefined ? {} : { why }),
                     ...(next === undefined ? {} : { next_action: next }),
                     ...(undefined === lastKnown ? {} : { lastKnown }),
+                    // Setup that never connects is where most people give up; it is the talk worth having.
+                    talk_to_us: DiscoveryInvite.AGENT,
                 };
             }
             return { sessions };
@@ -230,6 +236,10 @@ export const RAW_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('True when the page exceeded the snapshot cap. The tree is then a document-order PREFIX: an element being absent from it does NOT mean it is absent from the page.'),
+            // The refs a capped read never entered — re-read one with `scope`. Undeclared, a validating
+            // client stripped it, and a truncated tree arrived with no way to finish reading it.
+            unread: z.array(z.string()).optional(),
+            unreadOverflow: z.boolean().optional(),
             note: z
                 .string()
                 .optional()
@@ -261,7 +271,7 @@ export const RAW_TOOLS = [
                 scope: asString(args['scope']) ?? '',
                 mode,
                 diff: true === args['diff'],
-            }, deps.snapshots ?? SNAPSHOT_CACHE), mode), mode), mode)));
+            }, deps.snapshots ?? SNAPSHOT_CACHE), mode), mode), mode, resolved)));
         },
     },
     {
@@ -290,10 +300,7 @@ export const RAW_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('Return the `scope` element ITSELF instead of searching inside it. Use when the target is a plain layout container with no role, name, testid or text of its own — which is routinely the element that carries the handler, and is otherwise unreachable because every query excludes its own scope root. Requires `scope`.'),
-            attrs: z
-                .array(z.string())
-                .optional()
-                .describe("Attribute names to return per match, e.g. ['href'] to inventory links or ['src'] for images. Absent attributes are omitted; credential-bearing names are redacted."),
+            attrs: AttrNamesSchema.optional().describe("Attribute NAMES to return per match, e.g. ['href'] for links, ['src'] for images. Projects, never filters: 'name=value' is refused. Absent omitted; credentials redacted."),
             limit: countSchema
                 .optional()
                 .describe('Cap the returned descriptors to the first N (cuts tokens on broad queries). If more matched, the result carries total + truncated:true so the trim is never silent — narrow with name/scope.'),
@@ -371,6 +378,12 @@ export const RAW_TOOLS = [
                     .optional()
                     .describe('Structural clusters on the page — what IS here, to diagnose the miss.'),
                 presentTestids: z.array(z.string()).optional(),
+                // Declared for the same reason presentRegions had to be: undeclared here, it is stripped
+                // from structuredContent without a word — and this field exists precisely to say a word.
+                presentTestidsTotal: z
+                    .number()
+                    .optional()
+                    .describe('Present only when presentTestids was cut at its cap: how many there were. The list is document order, so a region low on the page is what got dropped — absence from the list proves nothing.'),
                 knownEmptyState: z.boolean(),
                 splitText: z
                     .object({
@@ -614,24 +627,31 @@ function noteEmptyLeanTree(result, mode) {
  * wrapper or two is ordinary, so this is deliberately not `=== 0`.
  */
 const UNMOUNTED_ROOT_MAX_ELEMENTS = 3;
-/**
- * The third cause of an empty tree, and the one the walk cannot see: the app is not mounted.
- *
- * Reported from the field with the react-three-fiber crash. The source-mapping stamp threw inside
- * R3F's commit phase, React unmounted the entire tree, and the page went white — and the snapshot
- * answered `{ tree: "", nodes: 0 }`, which is also what a page that has not rendered yet answers.
- * The reporter spent a diagnosis pass separating the two, and said that detecting a dead root would
- * have pointed straight at the cause.
- *
- * The other two notes here explain an empty tree by what the WALK passed over. This one cannot: a
- * walk that visited nothing has nothing to have skipped. It reads the DOM count instead, which is
- * why the browser now reports it, and it fires only when the skip counts are silent — a page whose
- * elements were all hidden has plenty of DOM and belongs to `noteHiddenPage`.
- *
- * Like both of its neighbours it names a fact and hands over the next read, and does not diagnose:
- * "not mounted" is certain from the count, WHY is not, and the console is where the answer is.
- */
-function noteUnmountedRoot(result, mode) {
+function crashEvidence(session) {
+    const since = asRecord(session)['eventsSince'];
+    if ('function' !== typeof since)
+        return undefined;
+    let events;
+    try {
+        events = since.call(session, 0);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(events))
+        return undefined;
+    const errors = events.filter((e) => {
+        const type = asString(asRecord(e)['type']);
+        return EventType.CONSOLE_ERROR === type || EventType.ERROR_UNCAUGHT === type;
+    });
+    if (0 === errors.length)
+        return undefined;
+    const first = errors
+        .map((e) => asString(asRecord(asRecord(e)['data'])['message']))
+        .find((m) => undefined !== m && '' !== m);
+    return { count: errors.length, first: first ?? '' };
+}
+function noteUnmountedRoot(result, mode, session) {
     if (SnapshotMode.STATUS === mode)
         return result;
     const row = asRecord(result);
@@ -642,12 +662,31 @@ function noteUnmountedRoot(result, mode) {
     const elements = asNumber(row['domElements']);
     if (elements === undefined || elements > UNMOUNTED_ROOT_MAX_ELEMENTS)
         return result;
+    const mount = `the tree is empty because there is almost nothing in the DOM: ${String(elements)} ` +
+        `element(s) under this scope. That is a mount container with nothing rendered into it, not a ` +
+        `page whose contents were skipped — so the app is UNMOUNTED rather than slow, and waiting ` +
+        `will not change it. `;
+    // An uncaught error beside an empty mount container is the difference between "has not started"
+    // and "started and died", which are the two readings of this count and want opposite next moves.
+    // Nothing here is framework-specific, and deliberately so: the condition is a known mount
+    // container that holds nothing with an uncaught error beside it, which is as true of a Vue or
+    // Svelte root as a React one.
+    const crash = crashEvidence(session);
+    if (crash !== undefined) {
+        return {
+            ...row,
+            note: mount +
+                `The app did not merely fail to start — it CRASHED: ${String(crash.count)} uncaught ` +
+                `error(s) were logged in this session` +
+                ('' === crash.first ? '' : `, the first: "${crash.first}"`) +
+                `. Read reticle_console for the rest, and check anything that runs inside a framework ` +
+                `commit phase. Loading the app again will reproduce it rather than fix it.`,
+        };
+    }
     return {
         ...row,
-        note: `the tree is empty because there is almost nothing in the DOM: ${String(elements)} ` +
-            `element(s) under this scope. That is a mount container with nothing rendered into it, not a ` +
-            `page whose contents were skipped — so the app is UNMOUNTED rather than slow, and waiting ` +
-            `will not change it. An app that was rendering and then stopped has usually thrown: read ` +
+        note: mount +
+            `An app that was rendering and then stopped has usually thrown: read ` +
             `reticle_console for an uncaught error, and check anything that runs inside a framework ` +
             `commit phase. If the app has genuinely not started yet, load it and snapshot again.`,
     };

package/dist/telemetry/argument-shape.d.ts

@@ -19,8 +19,6 @@
  * never quietly start forwarding free text.
  */
 export declare const OTHER_VALUE = "other";
-/** True for anything we are willing to report a value for. */
-export declare function isSafeEnumParam(name: string): boolean;
 /**
  * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
  * known enum. Never the raw value of anything else.

package/dist/telemetry/argument-shape.js

@@ -41,10 +41,6 @@ const SAFE_ENUM_PARAMS = new Map([
     ['level', new Set(['error', 'warn', 'info', 'log', 'debug'])],
 ]);
 export const OTHER_VALUE = 'other';
-/** True for anything we are willing to report a value for. */
-export function isSafeEnumParam(name) {
-    return SAFE_ENUM_PARAMS.has(name);
-}
 /**
  * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
  * known enum. Never the raw value of anything else.

package/dist/telemetry/error-class.d.ts

@@ -2,9 +2,8 @@
  * Whose defect was that tool error?
  *
  * `toolErrors` was one number covering three failures with three different fixes, so the top-line
- * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Measured over
- * 2026-08-10/11: 60 `state`, 22 `refusal`, 20 `schema` (serialized zod arrays) and 20 stale refs.
- * Read as "126 tool errors" that hides the sixth of them where OUR schema failed to explain itself —
+ * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Read as one
+ * number, it hides the share where OUR schema failed to explain itself (serialized zod arrays),
  * which is the only bucket we can fix by writing better descriptions.
  *
  * Classified from the message SHAPE, never stored raw: this returns a bucket, and the caller keeps

package/dist/telemetry/error-class.js

@@ -2,9 +2,8 @@
  * Whose defect was that tool error?
  *
  * `toolErrors` was one number covering three failures with three different fixes, so the top-line
- * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Measured over
- * 2026-08-10/11: 60 `state`, 22 `refusal`, 20 `schema` (serialized zod arrays) and 20 stale refs.
- * Read as "126 tool errors" that hides the sixth of them where OUR schema failed to explain itself —
+ * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Read as one
+ * number, it hides the share where OUR schema failed to explain itself (serialized zod arrays),
  * which is the only bucket we can fix by writing better descriptions.
  *
  * Classified from the message SHAPE, never stored raw: this returns a bucket, and the caller keeps

package/dist/telemetry/feedback-local.d.ts

@@ -1,4 +1,5 @@
 import type { Feedback } from '@reticlehq/core/telemetry';
+/** Reports live beside the rest of the workspace, not in a temp dir somebody has to be told about. */
 interface SavedFeedback {
     path: string;
     /** A ready-to-run command that turns the file into an issue. */

package/dist/telemetry/feedback-local.js

@@ -13,8 +13,6 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ReticleDir } from '@reticlehq/core';
-/** Reports live beside the rest of the workspace, not in a temp dir somebody has to be told about. */
-const FEEDBACK_SUBDIR = 'feedback';
 /** Filesystem-safe, sortable, and unique enough for one report per second per kind. */
 const stamp = (now) => new Date(now).toISOString().replace(/[:.]/g, '-').replace('Z', '');
 const asMarkdown = (input, text, context) => {
@@ -39,7 +37,7 @@ const asMarkdown = (input, text, context) => {
  */
 export function saveFeedbackLocally(cwd, input, text, context, now = Date.now()) {
     try {
-        const dir = join(cwd, ReticleDir.ROOT, FEEDBACK_SUBDIR);
+        const dir = join(cwd, ReticleDir.ROOT, ReticleDir.FEEDBACK_SUBDIR);
         mkdirSync(dir, { recursive: true });
         const path = join(dir, `${stamp(now)}-${input.kind ?? 'note'}.md`);
         writeFileSync(path, asMarkdown(input, text, context), 'utf8');

package/dist/telemetry/feedback.d.ts

@@ -27,7 +27,7 @@ import { type SessionFacts } from './feedback-context.js';
 export declare const FEEDBACK_ENV = "RETICLE_FEEDBACK";
 /** What replaces a redacted match. Visible on purpose: a reader must see that something was removed. */
 export declare const REDACTED = "[redacted]";
-export interface Redaction {
+interface Redaction {
     text: string;
     /** Which rules fired, deduped. Surfaced back to the author so a redaction is never silent. */
     removed: string[];

package/dist/telemetry/harness-drive.d.ts

@@ -2,5 +2,3 @@
 export declare function withHarnessDrive<T>(drive: () => Promise<T>): Promise<T>;
 /** True while a harness drive is in progress. */
 export declare function harnessDriving(): boolean;
-/** Tests only — a leaked span would mis-attribute every verdict after it. */
-export declare function resetHarnessDrive(): void;

package/dist/telemetry/harness-drive.js

@@ -33,7 +33,3 @@ export async function withHarnessDrive(drive) {
 export function harnessDriving() {
     return depth > 0;
 }
-/** Tests only — a leaked span would mis-attribute every verdict after it. */
-export function resetHarnessDrive() {
-    depth = 0;
-}

package/dist/telemetry/hud-metrics.d.ts

@@ -0,0 +1,32 @@
+import { HudPanel, HudView, type HudUseData } from '@reticlehq/core';
+/**
+ * How people use the in-page HUD, rolled into the session summary.
+ *
+ * Windowed like the tool histograms beside it: a periodic flush reports what happened since the
+ * last one, so a dashboard sums across a session's events. Names only — every key is a control id
+ * the wire schema already checked against core's closed list.
+ */
+/** How many steps of the journey one window keeps. A journey longer than this is cut, and says so. */
+export declare const HUD_JOURNEY_MAX = 60;
+export interface HudSummary {
+    /** Presses per control; a toggle counts under `id:on` / `id:off` so a switch reads both ways. */
+    hudControls?: Record<string, number>;
+    /** Milliseconds the HUD spent in each view during the window. */
+    hudViewMs?: Partial<Record<HudView, number>>;
+    /** Milliseconds each panel was showing during the window. */
+    hudPanelMs?: Partial<Record<HudPanel, number>>;
+    /** The window's presses and view changes, in order, cut at HUD_JOURNEY_MAX. */
+    hudJourney?: string[];
+    /** Present, and true, only when the journey was cut. */
+    hudJourneyCut?: true;
+}
+export declare class HudMetrics {
+    #private;
+    constructor(now: () => number);
+    record(use: HudUseData): void;
+    get empty(): boolean;
+    /** The window so far. Open view and panel are counted up to now, and keep running after. */
+    summarize(): HudSummary;
+    /** Start the next window. The current view and panel carry over, timed from now. */
+    reset(): void;
+}

package/dist/telemetry/hud-metrics.js

@@ -0,0 +1,95 @@
+import { isHudControl } from '@reticlehq/core/hud';
+import { HudPanel, HudView } from '@reticlehq/core';
+/**
+ * How people use the in-page HUD, rolled into the session summary.
+ *
+ * Windowed like the tool histograms beside it: a periodic flush reports what happened since the
+ * last one, so a dashboard sums across a session's events. Names only — every key is a control id
+ * the wire schema already checked against core's closed list.
+ */
+/** How many steps of the journey one window keeps. A journey longer than this is cut, and says so. */
+export const HUD_JOURNEY_MAX = 60;
+export class HudMetrics {
+    #now;
+    #controls = new Map();
+    #viewMs = new Map();
+    #panelMs = new Map();
+    #journey = [];
+    #cut = false;
+    /** Did anything happen this window. A HUD merely sitting open is not worth a flush of its own. */
+    #changed = false;
+    #view;
+    #panel;
+    constructor(now) {
+        this.#now = now;
+    }
+    record(use) {
+        // A control the HUD never rendered is dropped here, the one place HUD use is counted, so free
+        // text cannot ride in on the id.
+        const control = use.control !== undefined && isHudControl(use.control) ? use.control : undefined;
+        if (control === undefined && use.view === undefined && use.panel === undefined)
+            return;
+        this.#changed = true;
+        if (control !== undefined) {
+            const key = use.toggle === undefined ? control : `${control}:${use.toggle}`;
+            this.#controls.set(key, (this.#controls.get(key) ?? 0) + 1);
+            this.#step(key);
+        }
+        if (use.view !== undefined && use.view !== this.#view?.value) {
+            this.#close(this.#view, this.#viewMs);
+            this.#view = { value: use.view, since: this.#now() };
+            this.#step(`view:${use.view}`);
+        }
+        if (use.panel !== undefined && use.panel !== this.#panel?.value) {
+            this.#close(this.#panel, this.#panelMs);
+            this.#panel = { value: use.panel, since: this.#now() };
+            if (use.panel !== HudPanel.NONE)
+                this.#step(`panel:${use.panel}`);
+        }
+    }
+    get empty() {
+        return !this.#changed;
+    }
+    /** The window so far. Open view and panel are counted up to now, and keep running after. */
+    summarize() {
+        const viewMs = this.#withOpen(this.#view, this.#viewMs);
+        const panelMs = this.#withOpen(this.#panel, this.#panelMs);
+        return {
+            ...(this.#controls.size > 0 ? { hudControls: Object.fromEntries(this.#controls) } : {}),
+            ...(viewMs.size > 0 ? { hudViewMs: Object.fromEntries(viewMs) } : {}),
+            ...(panelMs.size > 0 ? { hudPanelMs: Object.fromEntries(panelMs) } : {}),
+            ...(this.#journey.length > 0 ? { hudJourney: [...this.#journey] } : {}),
+            ...(this.#cut ? { hudJourneyCut: true } : {}),
+        };
+    }
+    /** Start the next window. The current view and panel carry over, timed from now. */
+    reset() {
+        const at = this.#now();
+        this.#controls.clear();
+        this.#viewMs.clear();
+        this.#panelMs.clear();
+        this.#journey.length = 0;
+        this.#cut = false;
+        this.#changed = false;
+        if (this.#view !== undefined)
+            this.#view = { ...this.#view, since: at };
+        if (this.#panel !== undefined)
+            this.#panel = { ...this.#panel, since: at };
+    }
+    #step(entry) {
+        if (this.#journey.length < HUD_JOURNEY_MAX)
+            this.#journey.push(entry);
+        else
+            this.#cut = true;
+    }
+    #close(open, into) {
+        if (open === undefined)
+            return;
+        into.set(open.value, (into.get(open.value) ?? 0) + Math.max(0, this.#now() - open.since));
+    }
+    #withOpen(open, closed) {
+        const out = new Map(closed);
+        this.#close(open, out);
+        return out;
+    }
+}

package/dist/telemetry/session-metrics.d.ts

@@ -16,6 +16,7 @@
  * than a rule saying it shouldn't.
  */
 import { BrowserLaunchKind, type ConnectFailure, type SessionSummary } from '@reticlehq/core/telemetry';
+import type { HudUseData } from '@reticlehq/core';
 /**
  * Mutable counters for one daemon lifetime. A plain class, not a store: it is process-local, it never
  * persists, and it dies with the daemon.
@@ -24,6 +25,8 @@ export declare class SessionMetrics {
     #private;
     /** Clock injected — this file must stay testable without a real one, per the repo's clock rule. */
     constructor(now: () => number);
+    /** A person used the HUD. Names only; the wire schema has already narrowed it. */
+    recordHudUse(use: HudUseData): void;
     /**
      * Record a call starting. Returns a function to call when it finishes — that closure is what makes
      * timing correct under CONCURRENCY: several agents can be inside `runTool` at once, so a single
@@ -162,5 +165,7 @@ export declare const recordSdkFailure: (failure: {
     site: string;
     message: string;
 }) => void;
+/** Narrow-and-record one HUD use. Keeps the session hot path to a single call. */
+export declare const recordHudUse: (use: HudUseData) => void;
 /** Tests only — drop the singleton so each case starts from zero. */
 export declare const resetSessionMetrics: () => void;