@reticlehq/server 2.11.0 → 2.12.0

package/dist/tools/invoke-tool.js

@@ -1,4 +1,5 @@
 import { healthEnvelope } from '../session/session-health.js';
+import { verifyNextBaton, SUPPRESS_VERIFY_NEXT_ENV } from './verify-next-baton.js';
 import { TelemetryActor, TelemetryEventKind, TRANSPORT_LIMITS, fingerprintFinding, } from '@reticlehq/core';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { getTelemetry } from '../telemetry/telemetry.js';
@@ -16,6 +17,7 @@ import { ReticleTool } from './tool-names.js';
 import { takeFeedbackPrompt } from './feedback-tools.js';
 import { takeFeedbackUndelivered } from '../telemetry/feedback-delivery.js';
 import { noteRefsMinted, wrongTabRefusal } from '../session/ref-provenance.js';
+import { CAPTURED_TOOLS, noteCapturedCall, noteToolDispatched, } from '../honesty/feature-capture.js';
 import { span } from '../trace.js';
 import { deltaForToolResult, impactSnapshot, initImpact, recordImpact, } from '../impact/impact-recorder.js';
 import { frictionOf, inviteFor } from './feedback-invite.js';
@@ -98,6 +100,8 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     ReticleTool.FLOW_REPLAY, // returns its own FlowReplayResult contract (+ auto-records a run)
     ReticleTool.FLOW_SAVE_RECORDED, // reads the recording buffer, writes disk
     ReticleTool.FLOW_HEAL, // returns its own FlowHealResult contract
+    ReticleTool.INTENT, // reads/writes .reticle/intent.json; sessionId only picks the project
+    ReticleTool.CONTEXT, // folds the journal + intent ledger; must still answer when nothing is connected
     ReticleTool.PROJECT, // reads .reticle/project.json
     ReticleTool.RUN_EXPORT, // reads .reticle/runs/<id>.json (verification-run artifact)
     ReticleTool.SESSION, // merged lifecycle/human-channel family (tune/yield/end/resume/messages/review/narrate)
@@ -300,6 +304,43 @@ export async function runTool(tool, deps, args) {
             session = undefined;
         }
     }
+    // The read-only calls the journal never keeps, recorded HERE because this is the one dispatch
+    // point every call routes through — a second recording site is a second thing to forget, and this
+    // instrument exists precisely because nothing was recorded before. Recorded before the handler
+    // runs: a read dispatches no action, so the counter reads the same either side.
+    //
+    // `reticle_context` is session-EXEMPT, so `session` above is undefined for it and it needs its own
+    // lenient resolve. Failing that resolve is silent by design: a call made with nothing connected
+    // has no per-session ledger to land in, and an instrument must never be why a tool call fails.
+    //
+    // EVERY tool is counted here, not just the read set: which of the 70-odd names in the table an
+    // agent actually reaches for is the question a decision about cutting or consolidating the surface
+    // turns on, and it had no answer. `reticle_run` is the one exclusion, for the same reason
+    // `reportRefusal` and `bugsInResult` exclude it — its handler calls `runTool` on the real tool, so
+    // the inner call is already counted under the name that RAN, and counting the wrapper too would
+    // both double the total and hide the run-only tier behind a single wrapper name. That tier is
+    // precisely the one the decision hinges on. See honesty/tool-hit-rate.ts.
+    if (ReticleTool.RUN !== tool.name) {
+        let target = session;
+        if (target === undefined) {
+            try {
+                target = deps.sessions.resolve(rawSessionId);
+            }
+            catch {
+                target = undefined;
+            }
+        }
+        if (target !== undefined) {
+            noteToolDispatched(target, tool.name);
+            if (CAPTURED_TOOLS.has(tool.name)) {
+                const subject = asString(args['ref']) ?? asString(args['target']);
+                noteCapturedCall(target, {
+                    tool: tool.name,
+                    ...(subject === undefined ? {} : { subject }),
+                });
+            }
+        }
+    }
     // A ref that was handed out by a DIFFERENT tab, on a call that named no session. Refused here, at
     // the one point that knows both the ref and the tab resolution picked — the handler only learns
     // that the ref missed, and answers that with "the DOM re-rendered", which is a confident diagnosis
@@ -450,8 +491,27 @@ export async function runTool(tool, deps, args) {
     // verdict-less session in the field never called a verdict-producing tool ONCE;
     // the counter behind this already existed and was reported only to us. One-shot per abandoned
     // run, same discipline as the pool lease — a hint on every call is noise that gets tuned out.
+    // The A/B control, and the reason it exists as an env flag rather than a code edit.
+    //
+    // `verify_next` is described in this repo's own changelog as "the largest known lever on whether a
+    // session produces a verdict at all", and it has never been measured — it was once built, fired
+    // and silently dropped by schema-strict clients for a whole release, which is exactly what an
+    // unmeasured lever looks like from the inside. "The payload now arrives" and "the agent acts on
+    // it" are different claims and only the first was ever verified.
+    //
+    // Suppressing it for a control arm has to leave the ONLY difference being the baton: same build,
+    // same surface, same counters. So the nudge is still TAKEN (the counter still resets, so the
+    // one-shot cadence is identical) and only the envelope key is withheld.
+    const suppressBaton = '1' === process.env[SUPPRESS_VERIFY_NEXT_ENV];
     const unverified = getSessionMetrics().takeUnverifiedNudge();
-    if (unverified !== undefined)
-        envelope[EnvelopeKey.VERIFY_NEXT] = unverified;
+    // Carry the CALL, not just the sentence. The prose has to be translated back into arguments, and
+    // that translation is where agents were already going wrong — `until` omitted, action arguments
+    // flat instead of nested under `args`. `ref` and `action` come from the act that actually
+    // dispatched, so the suggestion is about the element the agent touched. See verify-next-baton.
+    if (unverified !== undefined && !suppressBaton)
+        // `lastAct` read defensively: this envelope is built on EVERY tool call, so a session shape
+        // without it would turn a missing field into a crash on the whole surface rather than a missing
+        // suggestion. The baton degrades to prose, which is what it carried before.
+        envelope[EnvelopeKey.VERIFY_NEXT] = verifyNextBaton(unverified, resolved.lastAct?.effect() ?? {});
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }

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

@@ -35,5 +35,15 @@ export interface LeaseEvidence {
      * reported as a marker that was not found.
      */
     sdkMarker?: boolean;
+    /**
+     * The websocket URL the leased page actually tried, read from its own console.
+     *
+     * The only per-page proof there is about where the dial WENT. `refusal` proves a dial arrived
+     * HERE; this proves where one was aimed, which is the strictly more useful fact when it was aimed
+     * somewhere else — the case in which no refusal exists to be recorded, because nothing arrived.
+     *
+     * Absent means the page said nothing, never that it dialled correctly.
+     */
+    dialledUrl?: string;
 }
 export declare function leaseNotConnectedHint(url: string, port: number, evidence?: LeaseEvidence): string;

package/dist/tools/lease-hint.js

@@ -45,9 +45,45 @@ function markerClause(sdkMarker) {
             'document, so a lazily-imported SDK can still be missed — but combined with the rest it ' +
             'points at a bundle that carries no Reticle at all, i.e. wiring that never took effect.';
 }
+/**
+ * The port a websocket URL names, or undefined when it names none we can read.
+ *
+ * `ws://host/path` with no explicit port is deliberately undefined rather than defaulted to 80: a
+ * guessed port compared against the daemon's would manufacture a mismatch out of nothing, and this
+ * branch outranks every other cause. No answer is correct here; a plausible one is not.
+ */
+function dialledPort(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        const port = new URL(url).port;
+        return '' === port ? undefined : Number(port);
+    }
+    catch {
+        return undefined;
+    }
+}
 export function leaseNotConnectedHint(url, port, evidence = {}) {
     const opening = `the leased tab loaded ${url} but never dialled this daemon (port ${String(port)}).`;
     const marker = markerClause(evidence.sdkMarker);
+    // 0. The page told us where it dialled, and it was not here. Proof, and it outranks the refusal
+    //    branch below: a refusal proves a dial reached THIS daemon, which is a fact about some page;
+    //    this is a fact about the page in hand. When they disagree, the specific one wins.
+    //
+    //    Neither side can reach this conclusion alone, which is why it went unsaid for so long. The
+    //    page's own warning deliberately refuses to diagnose the daemon — from inside a browser a
+    //    daemon that is absent and one that is unreachable are the same observation. The daemon cannot
+    //    see a dial that never arrived. Put the address the page names beside the port the daemon is
+    //    bound to and the ambiguity disappears.
+    const dialled = dialledPort(evidence.dialledUrl);
+    if (dialled !== undefined && dialled !== port) {
+        return (`${opening} The page dialled ${String(evidence.dialledUrl)} (port ${String(dialled)}) and ` +
+            `this daemon is on ${String(port)}, so the dial never reached it. Nothing about the app's ` +
+            `wiring is in question. Either start the daemon on ${String(dialled)}, or point the app at ` +
+            `${String(port)} — the app's port comes from its build config (\`.reticle.json\`, ` +
+            `RETICLE_PORT, or the build plugin's \`port\`), and \`VITE_RETICLE_WS_URL\` overrides it ` +
+            `outright.${marker} ${RELEASE}`);
+    }
     // 1. A recorded refusal. The only cause with proof behind it, so nothing outranks it.
     if (evidence.refusal !== undefined) {
         return `${opening} A dial DID arrive and was refused: ${evidence.refusal}${marker} ${RELEASE}`;
@@ -55,11 +91,24 @@ export function leaseNotConnectedHint(url, port, evidence = {}) {
     // 2. Nuxt, whose most likely cause differs from every other framework's and which `init` warns
     //    about at install time — while this hint never mentioned it.
     const nuxt = evidence.framework?.toLowerCase() === NUXT ? ` ${NUXT_FIRST}` : '';
-    // 3. Proven wiring. Blaming the port here is the self-contradiction this rewrite exists to end.
+    // 3. Proven PORT. Blaming the port here is the self-contradiction this rewrite exists to end —
+    //    but "the wiring is correct" was a second claim, and it was not proven at all.
+    //
+    //    `previouslyConnected` is scoped to project + port, never to the app. In a monorepo, or for
+    //    anyone adding a second app, the thing that connected yesterday is a DIFFERENT app. Measured:
+    //    an uninstrumented app driven in exactly that situation was told its wiring was correct, and
+    //    handed four causes — a dev-mode guard, a stale dev server, a missing peer dependency, a
+    //    non-localhost page — every one of which presupposes the SDK is already installed. It was
+    //    not. That is the commonest failure there is, and `reticle init` appeared nowhere in the
+    //    answer, because the only branch that mentions it is the one reached when nothing is known.
     if (true === evidence.previouslyConnected) {
-        return (`${opening} An app for this project HAS connected on this port before, so the port and the ` +
-            `wiring are both correct — what is failing is the SDK reaching initialise on the page.${nuxt}` +
-            `${marker} ${REAL_CAUSES} ${RELEASE}`);
+        const notThisApp = true === evidence.sdkMarker
+            ? ''
+            : ' That may have been a DIFFERENT app, though: this one may carry no Reticle SDK at all, ' +
+                'in which case run `reticle init` in ITS directory first — every cause below assumes the ' +
+                'SDK is already installed.';
+        return (`${opening} An app for this project HAS connected on this port before, so the port is ` +
+            `proven.${notThisApp}${nuxt}${marker} ${REAL_CAUSES} ${RELEASE}`);
     }
     // 4. Wired, but never seen connect. Rank the real causes; keep the port differential last, where
     //    the evidence for it actually sits.

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

@@ -58,6 +58,11 @@ export declare function acquireLeasedSession(pool: {
         sessionId: string;
         release: () => Promise<void>;
     }>;
+    /**
+     * The address this lease's page said it could not reach. Optional so a test double need not
+     * implement it; the real pool always does.
+     */
+    dialFailureUrl?: (sessionId: string) => string | undefined;
     /** Optional so a test double need not implement it; the real pool always does. */
     alias?: (registeredId: string, leaseId: string) => void;
 }, sessions: {
@@ -81,5 +86,4 @@ export declare function waitForLeasedSession(isConnected: () => boolean, sleeper
  * any other call instead of being a second, invisible dispatch path.
  */
 export declare const LEASE_ACQUIRE_TOOL: ToolDef;
-export declare const LEASE_RELEASE_TOOL: ToolDef;
 export declare const LEASE_TOOLS: ToolDef[];

package/dist/tools/lease-tools.js

@@ -10,6 +10,7 @@
  */
 import { z } from 'zod';
 import { leaseNotConnectedHint } from './lease-hint.js';
+import { probeSdkMarker } from './sdk-marker-probe.js';
 import { readProjectFramework, readProjectId } from '../cli/cli-port.js';
 import { hasConnectedBefore } from '../session/connection-memory.js';
 import { reticleStateHome } from '../daemon/daemon.js';
@@ -24,14 +25,23 @@ import { chromiumHint } from '../cli/chromium-hint.js';
  * printed a static differential over the top of it — telling one agent in `reticle_sessions` that
  * the wiring was proven correct and telling it seconds later that the port was probably wrong.
  */
-function leaseEvidence(deps, port) {
+/**
+ * Async only for the marker probe, which is the piece that decides whether this app ships an SDK at
+ * all — the difference between the diagnosis a new user needs and four causes that all assume the
+ * install already happened. It is one localhost GET on a path that has already failed and is about
+ * to print a paragraph, and it can only ever add a sentence: the probe returns `undefined` on any
+ * doubt and the hint then says nothing about markers.
+ */
+async function leaseEvidence(deps, port, url) {
     const cwd = process.cwd();
     const projectId = readProjectId(cwd);
     const refusal = deps.sessions.lastClosure()?.reason;
     const framework = readProjectFramework(cwd);
+    const sdkMarker = await probeSdkMarker(url);
     return {
         ...(refusal === undefined ? {} : { refusal }),
         ...(framework === undefined ? {} : { framework }),
+        ...(sdkMarker === undefined ? {} : { sdkMarker }),
         previouslyConnected: hasConnectedBefore(reticleStateHome(), port, projectId),
         initialized: projectId !== undefined,
     };
@@ -239,16 +249,20 @@ export const LEASE_ACQUIRE_TOOL = {
             queued: pool.queuedCount(),
             ...(ready
                 ? {}
-                : (() => {
-                    const bridgePort = deps.bridgePort ?? RETICLE_DEFAULT_PORT;
-                    return {
-                        hint: leaseNotConnectedHint(url, bridgePort, leaseEvidence(deps, bridgePort)),
-                    };
-                })()),
+                : { hint: await notConnectedHint(deps, url, pool.dialFailureUrl?.(lease.sessionId)) }),
         };
     },
 };
-export const LEASE_RELEASE_TOOL = {
+/** The whole not-connected diagnosis, gathered and worded. Split out so the acquire path stays flat. */
+async function notConnectedHint(deps, url, dialledUrl) {
+    const bridgePort = deps.bridgePort ?? RETICLE_DEFAULT_PORT;
+    const evidence = await leaseEvidence(deps, bridgePort, url);
+    return leaseNotConnectedHint(url, bridgePort, {
+        ...evidence,
+        ...(dialledUrl === undefined ? {} : { dialledUrl }),
+    });
+}
+const LEASE_RELEASE_TOOL = {
     name: ReticleTool.LEASE_RELEASE,
     description: 'Release a leased browser context by sessionId, closing it and freeing the pool slot for a queued acquire. Call this when a flow finishes so the pool stays within its concurrency cap.',
     inputSchema: {

package/dist/tools/navigate-arrival.d.ts

@@ -13,8 +13,6 @@
  */
 import type { SessionManager } from '../session/session-manager.js';
 import type { NavigateArrival } from './navigate-result.js';
-/** Long enough for a dev server to serve a page and the SDK to dial back; short enough to not hang. */
-export declare const ARRIVAL_TIMEOUT_MS = 5000;
 export interface ArrivalClock {
     now: () => number;
     sleep: (ms: number) => Promise<void>;

package/dist/tools/navigate-arrival.js

@@ -12,7 +12,7 @@
  * the sleep are injected so this is testable without waiting on a real one.
  */
 /** Long enough for a dev server to serve a page and the SDK to dial back; short enough to not hang. */
-export const ARRIVAL_TIMEOUT_MS = 5_000;
+const ARRIVAL_TIMEOUT_MS = 5_000;
 const POLL_MS = 100;
 /**
  * Compare only origin + pathname.

package/dist/tools/observe-tools.js

@@ -5,7 +5,7 @@
 import { noteEmptyRead } from './observed-nothing.js';
 import { z } from 'zod';
 import { aliasParam } from './alias-args.js';
-import { CONSOLE_LEVELS, ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind, } from '@reticlehq/core';
+import { CONSOLE_LEVELS, ReticleCommand, DEFAULT_ASSERT_TIMEOUT_MS, PredicateKind, Verified, } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { buildReactionReport } from '../events/reaction.js';
 import { findContradictions } from '../events/contradictions.js';
@@ -13,13 +13,18 @@ import { evaluatePredicate, waitForPredicate, PredicateSchema } from '../events/
 import { parsePredicate } from '../events/predicate-parse.js';
 import { matchNet, matchConsole, isConsoleEvent, eventMatchesFilters, netEmptyHint, consoleEmptyHint, reconcileNet, projectNetCall, projectConsoleLog, } from '../events/event-filters.js';
 import { applyEventBudget, costHint, withSizeCost, DEFAULT_QUERY_LIMIT, } from '../session/output-budget.js';
-import { healthEnvelope, bufferEnvelope } from '../session/session-health.js';
+import { annotateStarvedFailure, healthEnvelope, bufferEnvelope, } from '../session/session-health.js';
 import { assertsDerivedIpcStatus, DERIVED_IPC_STATUS_ADVICE, isPresenceOnlyAssertion, PRESENCE_ONLY_ADVICE, } from './assert-grade.js';
 import { assertVerdict } from './assert-verdict.js';
+import { assertSource } from './assert-source.js';
+import { isChangeUndeclared } from '../honesty/undeclared-change.js';
+import { openSessionIntents } from '../intent/open-intents.js';
+import { dischargeInlineIntent, inlineVerdictId, linkInlineIntent, } from '../intent/inline-intent.js';
 import { bodiesNotCaptured } from '../honesty/uncaptured-bodies.js';
 import { withControl } from '../session/control-envelope.js';
-import { asString, asNumber } from './tools-helpers.js';
-import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+import { asString, asNumber, asRecord } from './tools-helpers.js';
+import { intentArg, sessionIdShape, commandOrThrow } from './tool-kit.js';
+import { gradeOfPredicate } from './assert-grade.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).
@@ -31,20 +36,20 @@ const bufferOutputShape = {
         .describe('Present only when the event buffer evicted events — a negative result may then be a false negative.'),
 };
 /**
- * Where to look when a failure has no element.
+ * The file:line an assertion may report — see `assertSource`.
  *
- * "the signal never fired", "the request was never made", "the store did not change" have no DOM node
- * to map to a component, so the file:line that covers element failures leaves exactly the failures
- * that most need explaining with nowhere to send the agent. The handler that should have fired the
- * signal lives with the control that was clicked, and the act path captured that control's source —
- * so a failing assertion can point there instead of at nothing.
- *
- * RED only: on a pass this is noise on the path the agent walks most.
+ * Neither `reticle_assert` nor `reticle_wait_for` drives anything, so the last act's source is about
+ * some earlier action and not about this verdict. The pointer comes from the assertion's own matched
+ * evidence; the last driven control is borrowed only for a RED whose predicate has no DOM clause at
+ * all, which is the failure that genuinely has no element to point at.
  */
-function lastActSourceOnFailure(session, pass) {
-    if (pass)
-        return {};
-    const source = session.lastAct.source();
+function assertionSource(session, predicate, verdict) {
+    const source = assertSource({
+        predicate,
+        evidence: verdict.evidence,
+        pass: verdict.pass,
+        lastActSource: session.lastAct.source(),
+    });
     return source === undefined ? {} : { source };
 }
 /**
@@ -179,7 +184,11 @@ export const OBSERVE_TOOLS = [
             // never asked about.
             const actCursor = session.lastAct.cursor();
             const judgingTheAct = actCursor !== undefined && actCursor >= since;
-            const contradictions = findContradictions(filtered, judgingTheAct ? { ...session.lastAct.effect(), actionSince: actCursor } : {});
+            const contradictions = findContradictions(filtered, {
+                currentDocumentId: session.currentDocumentId,
+                currentEditEpoch: session.currentEditEpoch,
+                ...(judgingTheAct ? { ...session.lastAct.effect(), actionSince: actCursor } : {}),
+            });
             // carry session health — a throttled tab means the observed timeline may be incomplete.
             return withControl(session, {
                 ...report,
@@ -233,7 +242,7 @@ export const OBSERVE_TOOLS = [
             source: z
                 .string()
                 .optional()
-                .describe('On a FAILING assertion, the `file:line` of the control last acted on — where the code that should have produced the missing signal/request/state change lives. Present only when an act preceded this assertion.'),
+                .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 session = deps.sessions.resolve(asString(args['sessionId']));
@@ -245,8 +254,11 @@ export const OBSERVE_TOOLS = [
             // match reticle_assert — wrap with control + session health (throttle matters most while blocking)
             // and the buffer envelope, so a verdict reached over an evicted window says so.
             return withControl(session, {
-                ...verdict,
-                ...lastActSourceOnFailure(session, verdict.pass),
+                // #537's starved-wait note wraps the verdict (it RETURNS the verdict), so it stands where
+                // `...verdict` did. The source line is #533's `assertionSource`, which superseded
+                // `lastActSourceOnFailure` — an assert used to be blamed on the previous act's file:line.
+                ...annotateStarvedFailure(session, verdict),
+                ...assertionSource(session, predicate, verdict),
                 ...healthEnvelope(session),
                 ...bufferEnvelope(session),
             });
@@ -255,14 +267,15 @@ export const OBSERVE_TOOLS = [
     {
         name: ReticleTool.ASSERT,
         example: { predicate: { kind: PredicateKind.SIGNAL, name: 'todos:loaded' } },
-        description: 'Evaluate a predicate (optionally waiting up to timeout_ms). Returns { pass, evidence, failureReason? }. The end of every verify loop. Prefer a { signal } or { net } consequence over { element }/{ text } presence — a passing presence-only assertion returns `advice` because a wrong/healed element can fake it. By default it only counts events since your last act, so a stale buffered signal can never fake a pass; pass `since` (an observe/act cursor) to set the window explicitly.',
+        description: 'Evaluate a predicate (optionally waiting up to timeout_ms). Returns { pass, evidence, failureReason? }. The end of every verify loop. CHECKING SEVERAL THINGS? Put them in ONE call with { kind: "allOf", predicates: [...] } — it returns one verdict naming whichever member failed, and one call costs one round trip where N calls cost N. Prefer a { signal } or { net } consequence over { element }/{ text } presence — a passing presence-only assertion returns `advice` because a wrong/healed element can fake it. By default it only counts events since your last act, so a stale buffered signal can never fake a pass; pass `since` (an observe/act cursor) to set the window explicitly.',
         inputSchema: {
             predicate: PredicateSchema.optional().describe(
             // Every kind, each with the field that carries its argument. Five of the nine were
             // undocumented here, including `route` — and "did submitting the login form navigate away"
             // is the most common thing an agent wants to assert. A field report reached us from an agent
             // that guessed `urlContains` on route (net's spelling) and got unrecognized_keys.
-            'Predicate to evaluate. Kinds: { signal, name } { net, urlContains|method|status|count|bodyContains } ' +
+            'Predicate to evaluate. Kinds: { signal, name|dataMatches|count } ' +
+                '{ net, urlContains|method|status|count|bodyContains } ' +
                 '{ 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 ' +
@@ -276,6 +289,7 @@ export const OBSERVE_TOOLS = [
                 .number()
                 .optional()
                 .describe('Cursor from a prior reticle_act — scopes the assertion to events after that act.'),
+            intent: intentArg,
             ...sessionIdShape,
         },
         outputSchema: {
@@ -309,7 +323,7 @@ export const OBSERVE_TOOLS = [
             source: z
                 .string()
                 .optional()
-                .describe('On a FAILING assertion, the `file:line` of the control last acted on — where the code that should have produced the missing signal/request/state change lives. Present only when an act preceded this assertion.'),
+                .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.'),
             coverage: z
                 .string()
                 .optional()
@@ -330,6 +344,9 @@ export const OBSERVE_TOOLS = [
             const timeout = asNumber(args['timeout_ms']) ?? 0;
             // Honesty: explicit since wins; else default to the last act's cursor; else the whole buffer.
             const since = asNumber(args['since']) ?? session.lastAct.cursor() ?? 0;
+            // Declared BEFORE the verdict, so the undeclared-change read below finds it open and stays
+            // quiet on THIS verdict rather than on the next one. Discharged after that read.
+            const intentId = await linkInlineIntent(deps, asString(args['sessionId']), asString(args['intent']), PredicateKind.SETTLED === predicate.kind ? undefined : predicate);
             const verdict = timeout > 0
                 ? await waitForPredicate(session, predicate, timeout, since)
                 : await evaluatePredicate(session, predicate, since);
@@ -345,16 +362,36 @@ export const OBSERVE_TOOLS = [
                     : assertsDerivedIpcStatus(predicate)
                         ? { advice: DERIVED_IPC_STATUS_ADVICE }
                         : {};
-            const { decision, contradictions, coverage, gaps } = await assertVerdict(session, predicate, verdict.pass, since, verdict.inconclusive, verdict.observationLost);
+            // Asked of every verdict drawn after an observed edit, not once per edit — see
+            // isChangeUndeclared for why repeating it is disclosure rather than nagging.
+            const changeUndeclared = await isChangeUndeclared(session.currentEditEpoch, () => openSessionIntents(deps, asString(args['sessionId'])));
+            const { decision, contradictions, coverage, gaps, verdictEffect } = await assertVerdict(session, predicate, verdict.pass, verdict.evidence, since, verdict.inconclusive, verdict.observationLost, changeUndeclared);
+            // The assertion IS the proof attempt, so a green one discharges the intent it was drawn for. A
+            // red proved nothing, and an unbound intent refuses discharge anyway — see inline-intent.ts.
+            // The id is checked HERE rather than only inside the helper so a caller that declared no intent
+            // touches nothing at all, not even the clock.
+            if (intentId !== undefined && Verified.YES === decision['verified']) {
+                await dischargeInlineIntent(deps, asString(args['sessionId']), intentId, {
+                    verdictId: inlineVerdictId(ReticleTool.ASSERT, deps.now()),
+                    grade: gradeOfPredicate(predicate),
+                    at: deps.now(),
+                });
+            }
+            // Journal the verdict so a LATER turn can read what this one proved. A verdict that lives only
+            // in the response lives only in the agent's context window, which is the copy a compaction
+            // 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);
             return withControl(session, {
                 ...decision,
-                ...verdict,
+                ...annotateStarvedFailure(session, verdict),
                 ...(contradictions.length > 0 ? { contradictions } : {}),
                 // What the app did not tell Reticle, on the same rule the act path uses.
                 ...(gaps.length > 0 ? { instrumentationGaps: gaps } : {}),
                 ...advice,
                 ...coverage,
-                ...lastActSourceOnFailure(session, verdict.pass),
+                // The SAME pointer the journal keeps, not a second lookup — one verdict, one file:line.
+                ...(verdictEffect.source === undefined ? {} : { source: verdictEffect.source }),
                 ...healthEnvelope(session),
                 ...bufferEnvelope(session),
             });

package/dist/tools/read-tools.js

@@ -4,7 +4,7 @@
  */
 import { resolveAnnotateTarget } from '../flows/annotate-target.js';
 import { z } from 'zod';
-import { EventType, ReticleCommand, REPLAY_PROGRAM_VERSION, SnapshotMode } from '@reticlehq/core';
+import { EventType, ReticleCommand, REPLAY_PROGRAM_VERSION, SnapshotMode, StorageArea, } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
 import { proposeConsequences } from '../oracles/propose-consequences.js';
 import { replayProgram } from '../flows/replay.js';
@@ -320,8 +320,10 @@ export const READ_TOOLS = [
                 .describe("Dot-path into the store (e.g. 'captionCache.v3'). Numeric array indices are supported."),
             depth: z
                 .number()
+                .int()
+                .positive()
                 .optional()
-                .describe('Collapse anything deeper than N levels to a size marker — avoids huge outputs for large stores.'),
+                .describe('Collapse anything deeper than N levels to a size marker — avoids huge outputs for large stores. A whole number of levels, 1 or more.'),
             ...sessionIdShape,
         },
         outputSchema: {
@@ -513,7 +515,7 @@ export const READ_TOOLS = [
             'diagnosable.',
         inputSchema: {
             area: z
-                .enum(['local', 'session', 'cookies'])
+                .nativeEnum(StorageArea)
                 .optional()
                 .describe('Scope to one storage area. Omit to read all three.'),
             key: z

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

@@ -5,10 +5,32 @@
  * Split out of act-tools.ts along its natural seam: the act tools care only about the outcome
  * (`result` defined = it went native), never about provider availability, box resolution,
  * drag-target inspection or the reason taxonomy.
+ *
+ * Also hosts `rewriteUploadArgs` — the daemon-side path that lets an agent name a file on disk
+ * and have its REAL bytes reach the browser's `<input type="file">`. The browser SDK cannot read
+ * the filesystem; the daemon can. The rewrite happens here, before the ACT command crosses the
+ * bridge, so the browser side sees a normal `{ content, name, type }` call and `assertUploadArgs`
+ * keeps its invariant (no fabricated bytes, no silently-dropped keys).
+ *
+ * Trust boundary: scoped to the project root (one level above `deps.reticleRoot`), resolved
+ * through `realpath` so symlinks cannot escape it. Sensitive files (.env*, .git/, *.pem, id_*,
+ * .npmrc) are denied with a message that says why. The cap is derived from the bridge's own
+ * MAX_MESSAGE_BYTES with the base64 4/3 inflation factor applied, so the encoded payload always
+ * fits in one WebSocket frame.
  */
 import { ActionType, InputModeReason } from '@reticlehq/core';
 import type { Session } from '../session/session.js';
 import { type ToolDeps } from './tool-kit.js';
+/**
+ * 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.
+ *
+ * Returns the (possibly rewritten) args object. All other actions are returned unchanged.
+ *
+ * This is the SINGLE interception point — called from session.command() so flow replay, crawl,
+ * and every other ACT dispatch site are covered without per-site wiring.
+ */
+export declare function rewriteUploadArgs(deps: Pick<ToolDeps, 'fs' | 'reticleRoot'>, action: string, innerArgs: Record<string, unknown>): Promise<Record<string, unknown>>;
 interface RealActResult {
     /** Defined only on a successful native action; `undefined` means the synthetic path runs. */
     result: unknown;