@reticlehq/server 2.12.0 → 2.13.1

package/dist/tools/numeric-bounds.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Shared bounds for numeric TOOL INPUTS.
+ *
+ * An unknown parameter is refused with "They were NOT applied — a result computed without them
+ * would look like an answer." A known parameter carrying a value the code cannot honour is the
+ * same failure: `reticle_state { depth: -5 }` used to return the full unscoped store, because
+ * `capDepth` treats a negative budget as "no cap". The agent cannot tell a bound it asked for
+ * from a bound that was dropped.
+ *
+ * A single rule for every number would be wrong (`since: 0` is a real cursor; `timeout_ms: 0`
+ * on assert means evaluate now; `threshold` is a 0–1 ratio). Each helper below is one policy,
+ * with the sentence for why that bound and not another.
+ */
+import { z } from 'zod';
+/**
+ * Hard cap on "return the first N". The ring buffer holds this many events; asking for a billion
+ * cannot be honoured from memory we do not keep, and would look like a complete listing.
+ */
+export declare const MAX_RESULT_COUNT: 2000;
+/**
+ * Hard cap on a numeric millisecond argument that does NOT block the caller's request.
+ * `timeout_ms: 0` stays legal — it means evaluate once, do not wait.
+ */
+export declare const MAX_TIMEOUT_MS = 120000;
+export declare const MAX_BLOCKING_WAIT_MS: number;
+/**
+ * `capDepth` at this many levels is already past any store an agent can read.
+ *
+ * Not lower: `numeric-args-are-bounded.test.ts` pins depth 50 as legal, because a large depth is a
+ * SCOPE choice and not an error. A ceiling that refuses it would turn a working call into a refusal
+ * in the name of bounding one that never worked.
+ */
+export declare const MAX_STATE_DEPTH = 256;
+/** A crawl that clicks forever is not a bound. */
+export declare const MAX_CRAWL_STEPS = 500;
+/** Scroll-to-find steps. Default is 20; hundreds is searching, thousands is a hang. */
+export declare const MAX_SCROLLS = 200;
+/** Fake-clock jump. One day of timers is a test; a billion ms is not. */
+export declare const MAX_ADVANCE_MS = 86400000;
+/** Presenter idle window. One hour is a slow app; larger values never fire. */
+export declare const MAX_IDLE_MS = 3600000;
+/** Viewport CSS px — matches the clamp the handler already applied, now as a refusal. */
+export declare const MIN_VIEWPORT_PX = 64;
+export declare const MAX_VIEWPORT_PX = 10000;
+/**
+ * A page cursor. 0 is the start of the buffer, so `.positive()` would refuse a legitimate first
+ * page. Negative is not a cursor.
+ */
+export declare const cursorSchema: z.ZodNumber;
+/**
+ * A wait budget in ms. 0 means evaluate now (documented on assert). Negative cannot be honoured.
+ */
+export declare const timeoutMsSchema: z.ZodNumber;
+/**
+ * A count / cap. 0 means "return none", which is a real request. Negative is not.
+ * Capped at the ring-buffer size so a `limit: 1e9` cannot pretend the buffer is larger than it is.
+ */
+export declare const countSchema: z.ZodNumber;
+/**
+ * Store projection depth. Negative used to mean "no cap" inside `capDepth`, which is how
+ * `depth: -5` silently returned the full store — that is the defect this bound closes.
+ *
+ * 0 stays REFUSED, which is the policy already on the surface (a zero-level read is not a read).
+ * `capDepth(v, 0)` does return a size marker, so accepting it would be defensible — but that is a
+ * change to what the tool answers, not a bound on what it cannot honour, and it belongs in its own
+ * change with its own reason.
+ */
+export declare const depthSchema: z.ZodNumber;
+/**
+ * Pixel-diff ratios (`threshold`, `maxRatio`). pixelmatch's threshold and our pass ratio are both
+ * 0..1; `.int()` would refuse 0.01.
+ */
+export declare const ratioSchema: z.ZodNumber;
+/** HTTP status on a mock or a filter. */
+export declare const httpStatusSchema: z.ZodNumber;
+/** Viewport CSS px. `.int()` alone still accepted 5 and 999999, then the handler silently clamped. */
+export declare const viewportPxSchema: z.ZodNumber;
+/** Crawl / scroll step budgets. 0 is a documented no-op on crawl ("raise it to crawl at all"). */
+export declare const stepCountSchema: z.ZodNumber;
+export declare const scrollCountSchema: z.ZodNumber;
+export declare const advanceMsSchema: z.ZodNumber;
+export declare const idleMsSchema: z.ZodNumber;
+/** Delay before a mocked response. 0 is immediate. */
+export declare const delayMsSchema: z.ZodNumber;
+/**
+ * Observe lookback. Must be > 0 — a non-positive window used to mint a FUTURE cursor, so the
+ * tool returned zero events and looked like a quiet page. Capped so `window_ms: 1e12` cannot hang.
+ */
+export declare const windowMsSchema: z.ZodNumber;
+/**
+ * Parallelism for suite replay. 0 (and omit) means sequential. Capped at the session/pool ceiling;
+ * asking for a thousand workers cannot be honoured.
+ */
+export declare const workerCountSchema: z.ZodNumber;
+/**
+ * A row index / list length in a virtualized table. Those lists are large on purpose; the ring
+ * buffer's 2000 is the wrong ceiling. A billion-row claim is not a list, it is a hang.
+ */
+export declare const MAX_LIST_INDEX = 1000000;
+export declare const listIndexSchema: z.ZodNumber;

package/dist/tools/numeric-bounds.js

@@ -0,0 +1,125 @@
+/**
+ * Shared bounds for numeric TOOL INPUTS.
+ *
+ * An unknown parameter is refused with "They were NOT applied — a result computed without them
+ * would look like an answer." A known parameter carrying a value the code cannot honour is the
+ * same failure: `reticle_state { depth: -5 }` used to return the full unscoped store, because
+ * `capDepth` treats a negative budget as "no cap". The agent cannot tell a bound it asked for
+ * from a bound that was dropped.
+ *
+ * A single rule for every number would be wrong (`since: 0` is a real cursor; `timeout_ms: 0`
+ * on assert means evaluate now; `threshold` is a 0–1 ratio). Each helper below is one policy,
+ * with the sentence for why that bound and not another.
+ */
+import { z } from 'zod';
+import { RING_BUFFER_DEFAULTS, TRANSPORT_LIMITS } from '@reticlehq/core';
+/**
+ * Hard cap on "return the first N". The ring buffer holds this many events; asking for a billion
+ * cannot be honoured from memory we do not keep, and would look like a complete listing.
+ */
+export const MAX_RESULT_COUNT = RING_BUFFER_DEFAULTS.MAX_EVENTS;
+/**
+ * Hard cap on a numeric millisecond argument that does NOT block the caller's request.
+ * `timeout_ms: 0` stays legal — it means evaluate once, do not wait.
+ */
+export const MAX_TIMEOUT_MS = 120_000;
+/**
+ * Hard cap on a wait the CALLER BLOCKS ON, which is a different ceiling from the one above.
+ *
+ * A blocking wait is bounded by the client's patience, not by ours. The MCP SDK's default request
+ * timeout is 60s and clients configure it lower; we advertised 120s. A caller who believed the
+ * advertised bound and asked for 90s got a TRANSPORT error at 60s — not a Reticle verdict, not a
+ * near-miss diagnosis, nothing to act on. The wait was honoured right up to the point where the
+ * only thing that could report it had gone.
+ *
+ * So the ceiling is set below the SDK default rather than at it: the margin is what lets Reticle's
+ * own "timed out, here is the near miss" answer beat the client's abort. A refused argument is a
+ * bad ceiling costing one round trip; an accepted one that cannot be delivered costs the drive.
+ *
+ * This does not make long waits possible, and is not meant to — it makes the ADVERTISED bound one
+ * that can actually be honoured. A caller that genuinely needs to outlast this polls: several short
+ * waits, each of which returns a verdict. See #601 for the bounded-wait cursor that would let one
+ * call do it properly.
+ */
+const MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+export const MAX_BLOCKING_WAIT_MS = MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS - 5_000;
+/**
+ * `capDepth` at this many levels is already past any store an agent can read.
+ *
+ * Not lower: `numeric-args-are-bounded.test.ts` pins depth 50 as legal, because a large depth is a
+ * SCOPE choice and not an error. A ceiling that refuses it would turn a working call into a refusal
+ * in the name of bounding one that never worked.
+ */
+export const MAX_STATE_DEPTH = 256;
+/** A crawl that clicks forever is not a bound. */
+export const MAX_CRAWL_STEPS = 500;
+/** Scroll-to-find steps. Default is 20; hundreds is searching, thousands is a hang. */
+export const MAX_SCROLLS = 200;
+/** Fake-clock jump. One day of timers is a test; a billion ms is not. */
+export const MAX_ADVANCE_MS = 86_400_000;
+/** Presenter idle window. One hour is a slow app; larger values never fire. */
+export const MAX_IDLE_MS = 3_600_000;
+/** Viewport CSS px — matches the clamp the handler already applied, now as a refusal. */
+export const MIN_VIEWPORT_PX = 64;
+export const MAX_VIEWPORT_PX = 10_000;
+/**
+ * A page cursor. 0 is the start of the buffer, so `.positive()` would refuse a legitimate first
+ * page. Negative is not a cursor.
+ */
+export const cursorSchema = z.number().finite().int().nonnegative();
+/**
+ * A wait budget in ms. 0 means evaluate now (documented on assert). Negative cannot be honoured.
+ */
+export const timeoutMsSchema = z.number().finite().int().nonnegative().max(MAX_BLOCKING_WAIT_MS);
+/**
+ * A count / cap. 0 means "return none", which is a real request. Negative is not.
+ * Capped at the ring-buffer size so a `limit: 1e9` cannot pretend the buffer is larger than it is.
+ */
+export const countSchema = z.number().finite().int().nonnegative().max(MAX_RESULT_COUNT);
+/**
+ * Store projection depth. Negative used to mean "no cap" inside `capDepth`, which is how
+ * `depth: -5` silently returned the full store — that is the defect this bound closes.
+ *
+ * 0 stays REFUSED, which is the policy already on the surface (a zero-level read is not a read).
+ * `capDepth(v, 0)` does return a size marker, so accepting it would be defensible — but that is a
+ * change to what the tool answers, not a bound on what it cannot honour, and it belongs in its own
+ * change with its own reason.
+ */
+export const depthSchema = z.number().finite().int().positive().max(MAX_STATE_DEPTH);
+/**
+ * Pixel-diff ratios (`threshold`, `maxRatio`). pixelmatch's threshold and our pass ratio are both
+ * 0..1; `.int()` would refuse 0.01.
+ */
+export const ratioSchema = z.number().finite().min(0).max(1);
+/** HTTP status on a mock or a filter. */
+export const httpStatusSchema = z.number().finite().int().min(100).max(599);
+/** Viewport CSS px. `.int()` alone still accepted 5 and 999999, then the handler silently clamped. */
+export const viewportPxSchema = z.number().finite().int().min(MIN_VIEWPORT_PX).max(MAX_VIEWPORT_PX);
+/** Crawl / scroll step budgets. 0 is a documented no-op on crawl ("raise it to crawl at all"). */
+export const stepCountSchema = z.number().finite().int().nonnegative().max(MAX_CRAWL_STEPS);
+export const scrollCountSchema = z.number().finite().int().nonnegative().max(MAX_SCROLLS);
+export const advanceMsSchema = z.number().finite().int().nonnegative().max(MAX_ADVANCE_MS);
+export const idleMsSchema = z.number().finite().int().nonnegative().max(MAX_IDLE_MS);
+/** Delay before a mocked response. 0 is immediate. */
+export const delayMsSchema = z.number().finite().int().nonnegative().max(MAX_TIMEOUT_MS);
+/**
+ * Observe lookback. Must be > 0 — a non-positive window used to mint a FUTURE cursor, so the
+ * tool returned zero events and looked like a quiet page. Capped so `window_ms: 1e12` cannot hang.
+ */
+export const windowMsSchema = z.number().finite().int().positive().max(MAX_TIMEOUT_MS);
+/**
+ * Parallelism for suite replay. 0 (and omit) means sequential. Capped at the session/pool ceiling;
+ * asking for a thousand workers cannot be honoured.
+ */
+export const workerCountSchema = z
+    .number()
+    .finite()
+    .int()
+    .nonnegative()
+    .max(TRANSPORT_LIMITS.MAX_SESSIONS);
+/**
+ * A row index / list length in a virtualized table. Those lists are large on purpose; the ring
+ * buffer's 2000 is the wrong ceiling. A billion-row claim is not a list, it is a hang.
+ */
+export const MAX_LIST_INDEX = 1_000_000;
+export const listIndexSchema = z.number().finite().int().nonnegative().max(MAX_LIST_INDEX);

package/dist/tools/observe-tools.js

@@ -7,11 +7,14 @@ import { z } from 'zod';
 import { aliasParam } from './alias-args.js';
 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 { annotateStarvedFailure, healthEnvelope, bufferEnvelope, } from '../session/session-health.js';
 import { assertsDerivedIpcStatus, DERIVED_IPC_STATUS_ADVICE, isPresenceOnlyAssertion, PRESENCE_ONLY_ADVICE, } from './assert-grade.js';
@@ -83,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
@@ -110,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,
@@ -187,12 +184,13 @@ export const OBSERVE_TOOLS = [
             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),
@@ -208,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,
@@ -223,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(),
@@ -245,12 +248,14 @@ 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 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, {
@@ -281,12 +286,10 @@ export const OBSERVE_TOOLS = [
                 '{ 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,
@@ -300,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()
@@ -338,10 +345,11 @@ 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
@@ -375,7 +383,14 @@ export const OBSERVE_TOOLS = [
                     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
@@ -402,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
@@ -419,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
@@ -494,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

@@ -6,6 +6,7 @@ import { resolveAnnotateTarget } from '../flows/annotate-target.js';
 import { z } from 'zod';
 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,7 @@ export const READ_TOOLS = [
                 .string()
                 .optional()
                 .describe("Dot-path into the store (e.g. 'captionCache.v3'). Numeric array indices are supported."),
-            depth: z
-                .number()
-                .int()
-                .positive()
+            depth: depthSchema
                 .optional()
                 .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,

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

@@ -40,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 {};

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

@@ -19,7 +19,7 @@
  * fits in one WebSocket frame.
  */
 import { ActionType, InputModeReason, ReticleCommand, TRANSPORT_LIMITS } from '@reticlehq/core';
-import { isPointerAction } from '../input/real-input.js';
+import { boxCenter, isPointerAction } from '../input/real-input.js';
 import { assertDragNotDestructive, assertNotDestructive } from './act-danger.js';
 import { NATIVE_INPUT_ARG } from '@reticlehq/core';
 import { asString, asRecord } from './tools-helpers.js';
@@ -171,16 +171,66 @@ function synthetic(reason) {
         ? { result: undefined, settled: false }
         : { result: undefined, settled: false, reason };
 }
+/**
+ * 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 const HOVER_NEEDS_POINTER_MSG = 'cannot hover without a real pointer — CSS :hover only applies to a native mouse move, never to a synthetic mouseover';
+function hoverSucceeded(center) {
+    return { result: { performed: true, center, action: ActionType.HOVER }, settled: true };
+}
+/**
+ * Drive hover through a real pointer (CDP provider, then a leased Playwright page), or refuse.
+ *
+ * A leased tab already owns Chromium — the pool can move the mouse even when `reticle drive` /
+ * `RETICLE_CDP_URL` never configured a provider. Falling through to synthetic dispatch is the
+ * bug: the tool reports done and the styles never ran.
+ */
+async function hoverForReal(deps, session, ref, inner, provider) {
+    const providerReady = provider !== undefined && (await provider.isAvailableFor(session.url));
+    if (!providerReady && deps.pool === undefined) {
+        throw new Error(HOVER_NEEDS_POINTER_MSG);
+    }
+    const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
+    assertNotDestructive(ActionType.HOVER, inner, inspected);
+    const box = asBox(inspected);
+    if (box === undefined) {
+        throw new Error(HOVER_NEEDS_POINTER_MSG);
+    }
+    if (providerReady && provider !== undefined) {
+        try {
+            const performed = await provider.perform(session.url, ActionType.HOVER, box, {});
+            if (performed.performed)
+                return hoverSucceeded(performed.center);
+        }
+        catch {
+            // A provider error used to fall back to synthetic dispatch. For hover that is a lie.
+        }
+    }
+    const { cx, cy } = boxCenter(box);
+    if (true === (await deps.pool?.hoverLease(session.id, cx, cy))) {
+        return hoverSucceeded({ cx, cy });
+    }
+    throw new Error(HOVER_NEEDS_POINTER_MSG);
+}
 /**
  * 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 async function tryRealInput(deps, session, ref, action, args) {
     const provider = deps.realInput;
     const inner = asRecord(args['args']);
     const askedForNative = true === inner[NATIVE_INPUT_ARG];
+    if (action === ActionType.HOVER) {
+        return hoverForReal(deps, session, ref, inner, provider);
+    }
     if (provider === undefined) {
         // Silent by default: with no provider EVERY action is synthetic, and a reason on all of them is
         // noise on the most-used tool in the product. But an agent that passed native:true asked a
@@ -197,6 +247,12 @@ export async function tryRealInput(deps, session, ref, action, args) {
     if ((action === ActionType.CLICK || action === ActionType.DBLCLICK) && !askedForNative) {
         return synthetic(InputModeReason.SYNTHETIC_CLICK_PREFERRED);
     }
+    // Under version skew CDP is unusable while DOM tools still work (#688). Surface the skew sentence
+    // rather than "page not correlated" / a silent provider-error fallback — those send the agent
+    // hunting a dead context that is not dead.
+    if (session.versionSkew !== undefined) {
+        throw new Error(session.versionSkew);
+    }
     if (!(await provider.isAvailableFor(session.url)))
         return synthetic(InputModeReason.PAGE_NOT_CORRELATED);
     const inspected = await commandOrThrow(deps, session.id, ReticleCommand.INSPECT, { ref });
@@ -235,6 +291,8 @@ export async function tryRealInput(deps, session, ref, action, args) {
         return { result: { performed: true, center: performed.center, action }, settled: true };
     }
     catch {
+        if (session.versionSkew !== undefined)
+            throw new Error(session.versionSkew);
         return {
             result: undefined,
             settled: false,