@reticlehq/server 2.11.0 → 2.13.0

package/dist/tools/observe-tools.js

@@ -5,21 +5,29 @@
 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 { countSchema, cursorSchema, httpStatusSchema, timeoutMsSchema, windowMsSchema, } from './numeric-bounds.js';
 import { buildReactionReport } from '../events/reaction.js';
 import { findContradictions } from '../events/contradictions.js';
 import { evaluatePredicate, waitForPredicate, PredicateSchema } from '../events/predicate.js';
+import { resolveSessionWithin } from '../session/resolve-within.js';
+import { WALL_CLOCK } from '../session/wall-clock.js';
 import { parsePredicate } from '../events/predicate-parse.js';
-import { matchNet, matchConsole, isConsoleEvent, eventMatchesFilters, netEmptyHint, consoleEmptyHint, reconcileNet, projectNetCall, projectConsoleLog, } from '../events/event-filters.js';
+import { matchNet, matchConsole, isConsoleEvent, eventMatchesFilters, netEmptyHint, consoleEmptyHint, reconcileNet, projectNetCall, projectConsoleLog, withoutUrlRaw, } 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 +39,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 };
 }
 /**
@@ -78,21 +86,17 @@ export const OBSERVE_TOOLS = [
         example: { since: 0 },
         description: 'Return the timeline of everything the app did in a window (DOM/network/route/console/animation/signal), with a summary. Use after an action. Pass `max_events` to cap the timeline to the most recent N (older events are dropped and counted in cost.droppedOldest). Every result carries a `cost:{events,bytes}` hint so you can self-budget your next call.',
         inputSchema: {
-            window_ms: z
-                .number()
-                .positive()
+            window_ms: windowMsSchema
                 // A non-positive window silently produced a FUTURE cursor, so the tool returned zero events
                 // and echoed the nonsense value back — indistinguishable from a genuinely quiet page. An
                 // agent that fumbles this argument gets a clean "nothing happened" instead of being told the
                 // question was malformed, which is the exact confusion this layer exists to refuse.
                 .optional()
                 .describe('Time window to look back, in ms (must be > 0). Default: 2000. Ignored when `since` is provided.'),
-            since: z
-                .number()
+            since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior reticle_act or reticle_observe call. Scopes the event window to exactly that span.'),
-            until: z
-                .number()
+            until: cursorSchema
                 .optional()
                 .describe('Upper cursor bound. With `since`, returns the span "between action A and B".'),
             actionId: z
@@ -105,9 +109,7 @@ export const OBSERVE_TOOLS = [
                 .describe('Event type allowlist — the cheapest way to shrink a large timeline. Use a bucket name — ' +
                 'dom | net | route | console | animation | signal | perf | state | storage — or a raw ' +
                 'type (e.g. "net.request"). Omit to return all types.'),
-            max_events: z
-                .number()
-                .nonnegative()
+            max_events: countSchema
                 .optional()
                 .describe('Cap the timeline to the most recent N events. Older events are counted in cost.droppedOldest.'),
             ...sessionIdShape,
@@ -179,11 +181,16 @@ 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,
+                appOrigin: session.url,
+                ...(judgingTheAct ? { ...session.lastAct.effect(), actionSince: actCursor } : {}),
+            });
             // carry session health — a throttled tab means the observed timeline may be incomplete.
             return withControl(session, {
                 ...report,
-                events: report.events.map(withoutConstantSessionId),
+                events: report.events.map((e) => withoutUrlRaw(withoutConstantSessionId(e))),
                 ...(contradictions.length > 0 ? { contradictions } : {}),
                 cost: costHint(report, budgeted.length, droppedOldest),
                 ...healthEnvelope(session),
@@ -199,9 +206,10 @@ 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: z.number().optional().describe('Maximum wait in milliseconds. Default: 4000.'),
-            since: z
-                .number()
+            timeout_ms: timeoutMsSchema
+                .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.'),
+            since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior reticle_act — scopes the wait to events after that act.'),
             ...sessionIdShape,
@@ -214,6 +222,10 @@ export const OBSERVE_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('The tab disconnected mid-wait, so this was never observed — the verdict is UNKNOWN, not a failure of the app.'),
+            inconclusive: z
+                .string()
+                .optional()
+                .describe('The wait could not be graded as a product failure — e.g. the tab is throttled and may never have rendered. The verdict is UNKNOWN, not "the UI is absent".'),
             session: z
                 .object({ lastSeenMs: z.number(), throttled: z.boolean(), focused: z.boolean() })
                 .optional(),
@@ -233,20 +245,25 @@ 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']));
+            const waitBudget = asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS;
+            // Spend the budget waiting for the APP as well as for the predicate. See resolve-within.
+            const session = await resolveSessionWithin(deps.sessions, asString(args['sessionId']), waitBudget, WALL_CLOCK);
             // `until` is act_and_wait's name for this — see alias-args.ts.
             const predicate = parsePredicate(aliasParam(args, 'predicate', ['until'])['predicate']);
             // 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;
-            const verdict = await waitForPredicate(session, predicate, asNumber(args['timeout_ms']) ?? DEFAULT_ASSERT_TIMEOUT_MS, since);
+            const verdict = await waitForPredicate(session, predicate, waitBudget, since);
             // 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,27 +272,27 @@ 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 ' +
                 'over element/text presence.'),
             until: PredicateSchema.optional().describe("Alias for `predicate` (act_and_wait's name)."),
-            timeout_ms: z
-                .number()
+            timeout_ms: timeoutMsSchema
                 .optional()
-                .describe('If > 0, wait up to this many milliseconds before failing. Default: 0 (evaluate once).'),
-            since: z
-                .number()
+                .describe('If > 0, wait up to this many milliseconds before failing. Default: 0 (evaluate once). 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.'),
+            since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior reticle_act — scopes the assertion to events after that act.'),
+            intent: intentArg,
             ...sessionIdShape,
         },
         outputSchema: {
@@ -286,6 +303,10 @@ export const OBSERVE_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('The tab disconnected mid-wait, so this was never observed — the verdict is UNKNOWN, not a failure of the app.'),
+            inconclusive: z
+                .string()
+                .optional()
+                .describe('The assertion could not be graded as a product failure — e.g. the tab is throttled and may never have rendered. The verdict is UNKNOWN, not "the UI is absent".'),
             advice: z
                 .string()
                 .optional()
@@ -309,7 +330,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()
@@ -324,12 +345,16 @@ export const OBSERVE_TOOLS = [
                 .describe('What the APP did not tell Reticle, and the one change that would fix it — each entry is { kind, missing, cost, fix, source?, ref? }. Reported ONLY where an absence made THIS verdict weaker: a failing assertion with no source to point at, or a state assertion against an app that registers no store. Never a survey of the page, so an entry is always work worth doing now. OMITTED when the app told Reticle everything it needed.'),
         },
         handler: async (deps, args) => {
-            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const timeout = asNumber(args['timeout_ms']) ?? 0;
+            // Spend the budget waiting for the APP as well as for the predicate. See resolve-within.
+            const session = await resolveSessionWithin(deps.sessions, asString(args['sessionId']), timeout, WALL_CLOCK);
             // `until` is act_and_wait's name for this — see alias-args.ts.
             const predicate = parsePredicate(aliasParam(args, 'predicate', ['until'])['predicate']);
-            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 +370,43 @@ 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(),
+                }, 
+                /*
+                 * An assertion has no element of its own — it observes, it does not act. The file it names
+                 * is the one the LAST action touched, which is the code path that produced the state being
+                 * asserted about. Already remembered on the session for exactly this reason: an assertion
+                 * whose failure has nothing to point at still needs to name a file.
+                 */
+                session.lastAct.source());
+            }
+            // 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),
             });
@@ -365,12 +417,10 @@ export const OBSERVE_TOOLS = [
         example: { urlContains: '/api/todos', method: 'POST' },
         description: 'Filtered list of network calls. Fast path for "did POST /x return 200?". A zero-match filter returns a `hint` { totalInWindow, present[] } of the calls that DID fire, so a miss is diagnosable. Desktop IPC (`ipc://`) has no status code — the 200/500 there is derived, so filter on `ok` for those.',
         inputSchema: {
-            since: z
-                .number()
+            since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior reticle_act — scopes the query to requests fired after that act.'),
-            until: z
-                .number()
+            until: cursorSchema
                 .optional()
                 .describe('Upper cursor bound — with `since`, the span between two acts.'),
             actionId: z
@@ -382,14 +432,12 @@ export const OBSERVE_TOOLS = [
                 .optional()
                 .describe('HTTP method filter: GET | POST | PUT | DELETE | PATCH etc.'),
             urlContains: z.string().optional().describe('Substring that the request URL must contain.'),
-            status: z.number().optional().describe('HTTP status code filter (e.g. 200, 404, 500).'),
+            status: httpStatusSchema.optional().describe('HTTP status code filter (e.g. 200, 404, 500).'),
             ok: z
                 .boolean()
                 .optional()
                 .describe('Outcome filter: false keeps only calls that FAILED, true only those that succeeded. The filter to use for desktop IPC (`ipc://`), whose status code is derived. A still-pending call matches neither.'),
-            limit: z
-                .number()
-                .nonnegative()
+            limit: countSchema
                 .optional()
                 .describe('Keep only the most recent N matching calls (older are dropped and counted in droppedOldest) — cuts tokens on a wide window. Defaults to 200 when omitted; pass a higher number for more, or scope with since/until.'),
             bodies: z
@@ -457,21 +505,17 @@ export const OBSERVE_TOOLS = [
             level: consoleLevelEnum
                 .optional()
                 .describe(`Log level filter: ${CONSOLE_LEVEL_LIST}. Omit to return all levels.`),
-            since: z
-                .number()
+            since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior reticle_act — scopes the query to log entries after that act.'),
-            until: z
-                .number()
+            until: cursorSchema
                 .optional()
                 .describe('Upper cursor bound — with `since`, the span between two acts.'),
             actionId: z
                 .string()
                 .optional()
                 .describe('Keep only log entries attributed to this action — "what did action N log".'),
-            limit: z
-                .number()
-                .nonnegative()
+            limit: countSchema
                 .optional()
                 .describe('Keep only the most recent N matching entries (older are dropped and counted in droppedOldest) — cuts tokens when a page spams the console. Defaults to 200 when omitted; pass a higher number for more, or scope with since/until.'),
             ...sessionIdShape,

package/dist/tools/read-tools.js

@@ -4,8 +4,9 @@
  */
 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 { advanceMsSchema, depthSchema } from './numeric-bounds.js';
 import { proposeConsequences } from '../oracles/propose-consequences.js';
 import { replayProgram } from '../flows/replay.js';
 import { diffLines } from '../project/baselines.js';
@@ -15,6 +16,26 @@ import { buildReactionReport, summarizeReaction } from '../events/reaction.js';
 import { asString, asNumber, parseInteractive } from './tools-helpers.js';
 import { sessionIdShape, commandOrThrow, snapshotTree } from './tool-kit.js';
 import { bufferEnvelope } from '../session/session-health.js';
+/** The route part of a session URL. A host belongs to the machine, not to the journey. */
+/**
+ * The page a recording started on, as a NAVIGABLE path: pathname + hash.
+ *
+ * The hash matters and the pathname alone is not enough. Under a hash router every page has the
+ * document pathname `/`, so a recording made on `#/posts/12` stored `/`, the replay's start-path
+ * comparison saw `/` on both sides and never warned about drift, and the navigate it suggests
+ * pointed at the default route rather than the recorded one.
+ */
+function pathnameOf(url) {
+    if (url === undefined)
+        return undefined;
+    try {
+        const parsed = new URL(url);
+        return `${parsed.pathname}${parsed.hash}`;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * What record-stop says about a step that compiled to no anchor at all.
  *
@@ -141,7 +162,10 @@ export const READ_TOOLS = [
             const session = deps.sessions.resolve(asString(args['sessionId']));
             const name = asString(args['recordingName']) ?? 'default';
             const cursor = session.elapsed();
-            deps.recordings.start(name, cursor);
+            // Where the journey begins, so a saved flow can navigate here before step 1 instead of
+            // replaying from wherever the page happens to be. Pathname only: a host or port belongs to
+            // the machine that recorded it, not to the journey.
+            deps.recordings.start(name, cursor, pathnameOf(session.url));
             return Promise.resolve({ recordingName: name, since: cursor });
         },
     },
@@ -181,6 +205,7 @@ export const READ_TOOLS = [
                 name,
                 version: REPLAY_PROGRAM_VERSION,
                 steps: rec.steps,
+                ...(rec.startPath === undefined ? {} : { startPath: rec.startPath }),
             };
             deps.recordings.saveCompiled(program);
             const unstable = rec.steps.filter((s) => !s.stable).length;
@@ -282,8 +307,7 @@ export const READ_TOOLS = [
                 .boolean()
                 .optional()
                 .describe('Freeze the fake clock. Time stops advancing until advanceMs or reset.'),
-            advanceMs: z
-                .number()
+            advanceMs: advanceMsSchema
                 .optional()
                 .describe('Fast-forward time by this many milliseconds — triggers debounces, toasts, auto-dismiss timers.'),
             reset: z.boolean().optional().describe('Restore the real clock.'),
@@ -318,10 +342,9 @@ export const READ_TOOLS = [
                 .string()
                 .optional()
                 .describe("Dot-path into the store (e.g. 'captionCache.v3'). Numeric array indices are supported."),
-            depth: z
-                .number()
+            depth: depthSchema
                 .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 +536,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;
@@ -18,11 +40,21 @@ interface RealActResult {
     /** Why we went synthetic despite a configured provider (field bug #2: never a silent fallback). */
     reason?: InputModeReason;
 }
+/**
+ * Hover without a native pointer is a false success: synthetic mouseover reports dispatched and
+ * settled while CSS `:hover` never applies. Same refusal shape as contenteditable — name the gap
+ * rather than pretend the action ran.
+ */
+export declare const HOVER_NEEDS_POINTER_MSG = "cannot hover without a real pointer \u2014 CSS :hover only applies to a native mouse move, never to a synthetic mouseover";
 /**
  * Attempt to drive a pointer action via native input. Returns a synthetic outcome (with a
  * `reason` when a provider is configured) whenever the synthetic path should run — no matching
  * page, unresolvable box, declined, etc. A throw inside the provider becomes a synthetic fallback
  * flagged with `fellBack`. `result` is defined only on a real success.
+ *
+ * Hover is the exception: it never returns synthetic. CSS `:hover` is not applied by
+ * `dispatchEvent`, so a synthetic success is the defect. The call either drives a real pointer
+ * or throws.
  */
 export declare function tryRealInput(deps: ToolDeps, session: Session, ref: string, action: ActionType, args: Record<string, unknown>): Promise<RealActResult>;
 export {};