@reticlehq/server 2.13.1 → 2.14.0

package/dist/tools/navigate-arrival.js

@@ -10,9 +10,18 @@
  * Bounded and best-effort by construction: a navigation to a page that is not instrumented, or not
  * there at all, must still return promptly with `confirmed:false` rather than hanging. The clock and
  * the sleep are injected so this is testable without waiting on a real one.
+ *
+ * The bound is the CALLER'S to set. It was a fixed 5s that `reticle_navigate` did not expose, and a
+ * Nuxt SPA reattaching under HMR was measured coming back in 30–60s — so every navigation to it
+ * answered `confirmed:false` while the app was still on its way, and nothing the agent could pass
+ * would make the daemon wait. `assert` / `wait_for` / `act_and_wait` all spend the caller's
+ * `timeout_ms` (resolve-within.ts); this is the same budget applied to the same wait.
+ */
+/**
+ * The default when the caller gives no `timeout_ms`: long enough for a dev server to serve a page
+ * and the SDK to dial back; short enough to not hang. A caller who knows the app is slower says so.
  */
-/** Long enough for a dev server to serve a page and the SDK to dial back; short enough to not hang. */
-const ARRIVAL_TIMEOUT_MS = 5_000;
+export const ARRIVAL_TIMEOUT_MS = 5_000;
 const POLL_MS = 100;
 /**
  * Compare only origin + pathname.
@@ -32,12 +41,36 @@ function samePage(a, b) {
         return false;
     }
 }
-function findArrival(sessions, target) {
+/**
+ * The sessions already on `target` — the set `ArrivalScope.priorIds` is built from, sampled before
+ * the navigation is dispatched.
+ *
+ * Shares `samePage` with the arrival scan on purpose: "was it already there" and "is it there now"
+ * are the same question asked at two moments, and two spellings of it would eventually disagree.
+ */
+export function idsAtTarget(sessions, target) {
+    const ids = new Set();
     for (const s of sessions.all()) {
         if (samePage(s.url, target))
+            ids.add(s.id);
+    }
+    return ids;
+}
+function findArrival(sessions, target, scope) {
+    let arrived = null;
+    for (const s of sessions.all()) {
+        if (!samePage(s.url, target))
+            continue;
+        // The tab we drove is the answer whenever it is there, not a tie broken by scan order.
+        if (s.id === scope.navigatedId)
             return { sessionId: s.id };
+        if (scope.priorIds.has(s.id))
+            continue;
+        // Keep looking rather than returning: the driven session may still be ahead of us.
+        if (null === arrived)
+            arrived = { sessionId: s.id };
     }
-    return null;
+    return arrived;
 }
 const REAL_CLOCK = {
     now: () => Date.now(),
@@ -47,10 +80,10 @@ const REAL_CLOCK = {
  * Poll until a session is present at `target`, or the budget runs out. Returns `null` on timeout —
  * never throws, because a failure to confirm is a legitimate answer, not an error.
  */
-export async function awaitArrival(sessions, target, timeoutMs = ARRIVAL_TIMEOUT_MS, clock = REAL_CLOCK) {
+export async function awaitArrival(sessions, target, scope, timeoutMs = ARRIVAL_TIMEOUT_MS, clock = REAL_CLOCK) {
     const deadline = clock.now() + timeoutMs;
     for (;;) {
-        const found = findArrival(sessions, target);
+        const found = findArrival(sessions, target, scope);
         if (found !== null)
             return found;
         if (clock.now() >= deadline)

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

@@ -28,4 +28,11 @@ export declare function navigateResult(result: {
  * one place that CAN answer this — the SDK reconnects to it — so making it answer removes a
  * `reticle_sessions` poll from every single navigation.
  */
-arrival?: NavigateArrival | null): Record<string, unknown>;
+arrival: NavigateArrival | null, 
+/**
+ * The budget the daemon spent waiting for arrival, in ms. Reported on `confirmed:false` so the
+ * agent can tell "Reticle stopped waiting" from "the page never came back": the first is fixed by
+ * asking for a longer `timeout_ms`, the second is not. Without it the two read identically, and a
+ * slow SPA (30–60s to reattach under HMR) looked like a failed navigation on every call.
+ */
+waitedMs: number): Record<string, unknown>;

package/dist/tools/navigate-result.js

@@ -8,7 +8,14 @@ export function navigateResult(result,
  * one place that CAN answer this — the SDK reconnects to it — so making it answer removes a
  * `reticle_sessions` poll from every single navigation.
  */
-arrival = null) {
+arrival, 
+/**
+ * The budget the daemon spent waiting for arrival, in ms. Reported on `confirmed:false` so the
+ * agent can tell "Reticle stopped waiting" from "the page never came back": the first is fixed by
+ * asking for a longer `timeout_ms`, the second is not. Without it the two read identically, and a
+ * slow SPA (30–60s to reattach under HMR) looked like a failed navigation on every call.
+ */
+waitedMs) {
     const ok = true === result.ok;
     const base = {
         ok,
@@ -30,9 +37,12 @@ arrival = null) {
     return {
         ...base,
         confirmed: false,
+        waitedMs,
         note: 'ok means the navigation was DISPATCHED, not that the page arrived. The SDK is torn down by ' +
-            'the navigation itself, so nothing here can see the new document. Call reticle_sessions to ' +
-            'confirm a session reconnected at the new URL before acting; if none appears, the page did ' +
-            'not load or is not instrumented.',
+            'the navigation itself, so nothing here can see the new document, and no session reconnected ' +
+            `at the new URL within ${waitedMs}ms. A slow app may still be on its way (an SPA reattaching ` +
+            'under HMR can take 30-60s): navigate again with a larger timeout_ms, or call reticle_sessions ' +
+            'to confirm a session reconnected before acting; if none appears, the page did not load or is ' +
+            'not instrumented.',
     };
 }

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

@@ -31,14 +31,8 @@ export declare const MAX_BLOCKING_WAIT_MS: number;
  * 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;
@@ -92,9 +86,4 @@ export declare const windowMsSchema: z.ZodNumber;
  * 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

@@ -52,13 +52,13 @@ export const MAX_BLOCKING_WAIT_MS = MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS - 5_000;
  */
 export const MAX_STATE_DEPTH = 256;
 /** A crawl that clicks forever is not a bound. */
-export const MAX_CRAWL_STEPS = 500;
+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;
+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;
+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;
@@ -121,5 +121,5 @@ export const workerCountSchema = z
  * 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;
+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

@@ -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, Verified, } from '@reticlehq/core';
+import { CONSOLE_ATTACH_NOTE, 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';
@@ -19,11 +19,12 @@ import { applyEventBudget, costHint, withSizeCost, DEFAULT_QUERY_LIMIT, } from '
 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 { assertionSource } 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 { bodyClauseRefusal } from '../honesty/body-capture-remedy.js';
 import { withControl } from '../session/control-envelope.js';
 import { asString, asNumber, asRecord } from './tools-helpers.js';
 import { intentArg, sessionIdShape, commandOrThrow } from './tool-kit.js';
@@ -38,23 +39,6 @@ const bufferOutputShape = {
         .optional()
         .describe('Present only when the event buffer evicted events — a negative result may then be a false negative.'),
 };
-/**
- * The file:line an assertion may report — see `assertSource`.
- *
- * 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 assertionSource(session, predicate, verdict) {
-    const source = assertSource({
-        predicate,
-        evidence: verdict.evidence,
-        pass: verdict.pass,
-        lastActSource: session.lastAct.source(),
-    });
-    return source === undefined ? {} : { source };
-}
 /**
  * Drop `sessionId` from an event in a response the caller scoped to ONE session.
  *
@@ -78,7 +62,6 @@ function withoutConstantSessionId(event) {
  * it (it reports which levels are present), but on a quiet page the answer is identical to a genuine
  * all-clear. Refusing the value outright is the only reading with no ambiguity.
  */
-const CONSOLE_LEVEL_LIST = CONSOLE_LEVELS.join(' | ');
 const consoleLevelEnum = z.enum(CONSOLE_LEVELS);
 export const OBSERVE_TOOLS = [
     {
@@ -253,6 +236,11 @@ export const OBSERVE_TOOLS = [
             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']);
+            // Refused up front rather than waited out: a body clause this session cannot answer would
+            // burn the whole timeout to report something knowable now. See #801(C).
+            const bodyRefusal = bodyClauseRefusal(predicate, session);
+            if (bodyRefusal !== undefined)
+                throw new Error(bodyRefusal);
             // 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, waitBudget, since);
@@ -280,7 +268,7 @@ export const OBSERVE_TOOLS = [
             // 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|dataMatches|count } ' +
-                '{ net, urlContains|method|status|count|bodyContains } ' +
+                '{ net, urlContains|method|status|count|bodyContains|requestBodyContains|requestBodyMatches } ' +
                 '{ state, path|equals } { route, pathname (exact) | contains (path+query+hash) } ' +
                 '{ element, testid|role|text } { text } { console, level|contains|absent } { animation, name } ' +
                 '{ settled } — combine with { allOf | anyOf | not }. Prefer a signal/net/state consequence ' +
@@ -350,6 +338,11 @@ export const OBSERVE_TOOLS = [
             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']);
+            // Refused up front rather than waited out: a body clause this session cannot answer would
+            // burn the whole timeout to report something knowable now. See #801(C).
+            const bodyRefusal = bodyClauseRefusal(predicate, session);
+            if (bodyRefusal !== undefined)
+                throw new Error(bodyRefusal);
             // 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
@@ -492,7 +485,7 @@ export const OBSERVE_TOOLS = [
             return withSizeCost(noteEmptyRead({
                 calls,
                 ...(droppedOldest > 0 ? { total: matched.length, droppedOldest } : {}),
-                ...(bodies ? bodiesNotCaptured(calls) : {}),
+                ...(bodies ? bodiesNotCaptured(calls, session.sdkVersion) : {}),
                 ...buffer,
             }, 'calls', { noun: 'network calls' }));
         },
@@ -502,9 +495,7 @@ export const OBSERVE_TOOLS = [
         example: { level: 'error' },
         description: 'Console/error log. Fast path for "were there any errors during this flow?". When a level filter matches nothing, returns a `hint` { totalInWindow, byLevel } so 0 errors is distinguishable from a silent page.',
         inputSchema: {
-            level: consoleLevelEnum
-                .optional()
-                .describe(`Log level filter: ${CONSOLE_LEVEL_LIST}. Omit to return all levels.`),
+            level: consoleLevelEnum.optional().describe('Log level filter. Omit to return all levels.'),
             since: cursorSchema
                 .optional()
                 .describe('Cursor from a prior reticle_act — scopes the query to log entries after that act.'),
@@ -556,7 +547,12 @@ export const OBSERVE_TOOLS = [
             // returning read here was already wired to.
             return withSizeCost(noteEmptyRead(droppedOldest > 0
                 ? { logs, total: matched.length, droppedOldest, ...buffer }
-                : { logs, ...buffer }, 'logs', { noun: 'console lines' }));
+                : { logs, ...buffer }, 'logs', 
+            // Same gate as the predicate path, for the same reason and at the same price: the blind
+            // stretch is between page load and attach, so only a window that starts at attach can
+            // contain it. A read since an action already began after the channel was live, and
+            // stapling 369 bytes onto every quiet read would be paying for a caveat that is not true.
+            { noun: 'console lines', ...(0 === since ? { caveat: CONSOLE_ATTACH_NOTE } : {}) }));
         },
     },
     {

package/dist/tools/observed-nothing.d.ts

@@ -15,6 +15,15 @@ interface EmptyReadContext {
     windowMs?: number;
     /** What was being counted, in the agent's words: "console lines", "network calls". */
     noun: string;
+    /**
+     * What this channel could NOT have seen, when it has a structural blind spot.
+     *
+     * "The observation ran and found none" is only the whole truth for a channel that was watching
+     * the entire window. The console is not one: it does not exist until the SDK patches it, so a
+     * clean read cannot speak for what the page logged before that. Saying so here is the difference
+     * between a result and a confident false green — omitted for every channel that has no such gap.
+     */
+    caveat?: string;
 }
 /**
  * Add `observed: true` and a note when `key` holds an EMPTY array. Returns the result untouched

package/dist/tools/observed-nothing.js

@@ -28,6 +28,7 @@ export function noteEmptyRead(result, key, context) {
         ...result,
         // The distinction the field sweep could not make: this is a RESULT, not a failure to look.
         observed: true,
-        note: `no ${context.noun}${window}; the observation ran and found none, which is a result, not a missing reading`,
+        note: `no ${context.noun}${window}; the observation ran and found none, which is a result, not a missing reading` +
+            (context.caveat === undefined ? '' : ` — ${context.caveat}`),
     };
 }

package/dist/tools/read-tools.js

@@ -8,6 +8,7 @@ import { EventType, ReticleCommand, REPLAY_PROGRAM_VERSION, SnapshotMode, Storag
 import { ReticleTool } from './tool-names.js';
 import { advanceMsSchema, depthSchema } from './numeric-bounds.js';
 import { proposeConsequences } from '../oracles/propose-consequences.js';
+import { recordingBacktrackWarning, routesFromRecording } from '../flows/recording-backtrack.js';
 import { replayProgram } from '../flows/replay.js';
 import { diffLines } from '../project/baselines.js';
 import { selectPath, capDepth, projectComponentState } from '../session/state-select.js';
@@ -16,6 +17,7 @@ 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';
+import { routeOfUrl } from '../events/predicate-route.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.
@@ -28,13 +30,8 @@ import { bufferEnvelope } from '../session/session-health.js';
 function pathnameOf(url) {
     if (url === undefined)
         return undefined;
-    try {
-        const parsed = new URL(url);
-        return `${parsed.pathname}${parsed.hash}`;
-    }
-    catch {
-        return undefined;
-    }
+    const parts = routeOfUrl(url);
+    return parts === undefined ? undefined : `${parts.docPath}${parts.hash}`;
 }
 /**
  * What record-stop says about a step that compiled to no anchor at all.
@@ -58,7 +55,6 @@ function unanchoredWarning(count) {
 }
 /** Severities the presenter HUD can render. */
 const HUD_LEVELS = ['info', 'warn', 'error'];
-const HUD_LEVEL_LIST = HUD_LEVELS.join(' | ');
 const hudLevelEnum = z.enum(HUD_LEVELS);
 /**
  * How deep an unscoped `reticle_state` read goes before collapsing to size markers.
@@ -171,7 +167,7 @@ export const READ_TOOLS = [
     },
     {
         name: ReticleTool.RECORD_STOP,
-        description: 'Stop the recording identified by `recordingName` and return both the reaction report for the span and a compiled, replayable { program: { version, steps:[{tool,args,stable}] } } of the agent acts captured during it.',
+        description: 'Stop the recording identified by `recordingName` and return both the reaction report for the span and a compiled, replayable { program: { version, steps:[{tool,args,stable}] } } of the agent acts captured during it. `warning` is present when the window left a page and returned to it — replay has no navigation steps, so the next click will look for a control on a page the tab is no longer on.',
         inputSchema: {
             recordingName: z
                 .string()
@@ -201,11 +197,13 @@ export const READ_TOOLS = [
                     : `no active recording named '${name}'; in progress: ${active.map((r) => `'${r}'`).join(', ')}`);
             }
             const events = session.eventsSince(rec.cursor);
+            const routes = routesFromRecording(rec.startPath, events);
             const program = {
                 name,
                 version: REPLAY_PROGRAM_VERSION,
                 steps: rec.steps,
                 ...(rec.startPath === undefined ? {} : { startPath: rec.startPath }),
+                ...(0 === routes.length ? {} : { routes }),
             };
             deps.recordings.saveCompiled(program);
             const unstable = rec.steps.filter((s) => !s.stable).length;
@@ -224,15 +222,14 @@ export const READ_TOOLS = [
                     timeline_omitted: `${String(events.length)} event(s) were recorded and are not included here. Call reticle_observe { since: ${String(rec.cursor)} } for the raw timeline.`,
                 }
                 : {};
+            const unanchored = 0 < unstable ? unanchoredWarning(unstable) : undefined;
+            const backtrack = recordingBacktrackWarning(routes);
+            const warning = [unanchored, backtrack].filter((part) => part !== undefined);
             const body = {
                 recordingName: name,
                 program,
                 ...timeline,
-                ...(unstable > 0
-                    ? {
-                        warning: unanchoredWarning(unstable),
-                    }
-                    : {}),
+                ...(0 === warning.length ? {} : { warning: warning.join(' ') }),
                 ...(proposedConsequences.length > 0 ? { proposedConsequences } : {}),
                 ...digest,
             };
@@ -285,9 +282,7 @@ export const READ_TOOLS = [
                 .describe('Short sentence describing your next action, shown on the presenter HUD for the developer watching.'),
             // Derived, like every other advertised vocabulary here: a free string let a typo through to
             // a HUD that then rendered an unknown severity.
-            level: hudLevelEnum
-                .optional()
-                .describe(`Display severity: ${HUD_LEVEL_LIST}. Default: info.`),
+            level: hudLevelEnum.optional().describe('Display severity. Default: info.'),
             ...sessionIdShape,
         },
         outputSchema: { ok: z.boolean() },

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

@@ -12,15 +12,21 @@
  * 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.
+ * Trust boundary: scoped to the project root (one level above `deps.reticleRoot`) plus any
+ * opt-in `uploadRoots` declared in `.reticle.json`, resolved through `realpath` so symlinks
+ * cannot escape an allowed root. 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';
+/**
+ * Expand a leading `~` against the caller's home directory. Absolute and relative paths pass
+ * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
+ */
+export declare function expandUserPath(rawPath: string, home: string): string;
 /**
  * If the action is `upload` AND the inner args carry `path`, read the file from disk and rewrite
  * the args to `{ content, name, type, __base64: true }` before the ACT command reaches the browser.
@@ -30,7 +36,9 @@ import { type ToolDeps } from './tool-kit.js';
  * 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>>;
+export declare function rewriteUploadArgs(deps: Pick<ToolDeps, 'fs' | 'reticleRoot'>, action: string, innerArgs: Record<string, unknown>, 
+/** Injected for tests; production uses the process home directory. */
+home?: string): Promise<Record<string, unknown>>;
 interface RealActResult {
     /** Defined only on a successful native action; `undefined` means the synthetic path runs. */
     result: unknown;

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

@@ -12,11 +12,12 @@
  * 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.
+ * Trust boundary: scoped to the project root (one level above `deps.reticleRoot`) plus any
+ * opt-in `uploadRoots` declared in `.reticle.json`, resolved through `realpath` so symlinks
+ * cannot escape an allowed root. 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, ReticleCommand, TRANSPORT_LIMITS } from '@reticlehq/core';
 import { boxCenter, isPointerAction } from '../input/real-input.js';
@@ -25,7 +26,9 @@ import { NATIVE_INPUT_ARG } from '@reticlehq/core';
 import { asString, asRecord } from './tools-helpers.js';
 import { commandOrThrow } from './tool-kit.js';
 import { asBox } from './act-helpers.js';
-import { isAbsolute, join, relative, extname, basename } from 'node:path';
+import { isAbsolute, join, relative, extname, basename, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { RETICLE_CONFIG_BASENAME } from '../cli/cli-port.js';
 /**
  * Minimal extension → MIME-type table for the file types agents most commonly upload.
  * Falls back to `application/octet-stream` for anything not listed here — the browser and
@@ -92,28 +95,79 @@ function isDeniedPath(resolvedPath) {
  * that configures the socket so they can never drift.
  */
 const UPLOAD_MAX_BYTES = Math.floor((TRANSPORT_LIMITS.MAX_MESSAGE_BYTES / (4 / 3)) * 0.75);
+/**
+ * Expand a leading `~` against the caller's home directory. Absolute and relative paths pass
+ * through unchanged. `home` is injected so unit tests do not depend on the machine's real home.
+ */
+export function expandUserPath(rawPath, home) {
+    if ('~' === rawPath)
+        return home;
+    if (rawPath.startsWith('~/') || rawPath.startsWith('~\\'))
+        return join(home, rawPath.slice(2));
+    return rawPath;
+}
+/** True when `real` is inside `root` after both have been realpath'd / resolved. */
+function isInsideRoot(real, root) {
+    const rel = relative(root, real);
+    return !rel.startsWith('..') && !isAbsolute(rel);
+}
+/**
+ * Opt-in extra upload directories from `.reticle.json` (`uploadRoots`). Absent, empty, or unreadable
+ * config means project-root only — the previous default, kept on purpose.
+ */
+async function readUploadRoots(projectRoot, fs, home) {
+    const configPath = join(projectRoot, RETICLE_CONFIG_BASENAME);
+    let raw;
+    try {
+        raw = await fs.readFile(configPath);
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if ('object' !== typeof parsed || null === parsed || Array.isArray(parsed))
+        return [];
+    const listed = parsed['uploadRoots'];
+    if (!Array.isArray(listed))
+        return [];
+    const roots = [];
+    for (const entry of listed) {
+        if ('string' !== typeof entry || 0 === entry.trim().length)
+            continue;
+        roots.push(resolve(expandUserPath(entry.trim(), home)));
+    }
+    return roots;
+}
 /**
  * Resolve and validate a caller-supplied upload path.
  *
- * 1. Resolve to absolute (join against project root for relative paths).
+ * 1. Expand a leading `~`, then resolve to absolute (join against project root for relative paths).
  * 2. Call `realpath` to follow symlinks — `relative()` is lexical and a symlink inside the tree
  *    can point outside it; realpath is the only reliable check.
- * 3. Confirm the real path is within the project root.
+ * 3. Confirm the real path is within the project root or an opt-in `uploadRoots` entry.
  * 4. Confirm the path does not match the sensitive-file deny-list.
  *
  * Returns the resolved real path on success. Throws with a user-readable message on any violation.
  */
-async function resolveUploadPath(rawPath, projectRoot, fs) {
-    const abs = isAbsolute(rawPath) ? rawPath : join(projectRoot, rawPath);
+async function resolveUploadPath(rawPath, projectRoot, fs, uploadRoots, home) {
+    const expanded = expandUserPath(rawPath, home);
+    const abs = isAbsolute(expanded) ? expanded : join(projectRoot, expanded);
     // realpath resolves symlinks; it also rejects ENOENT, so we get a clear missing-file error.
     const real = await fs.realpath(abs).catch(() => {
         throw new Error(`upload path '${rawPath}' could not be read: file not found or not accessible.`);
     });
-    const rel = relative(projectRoot, real);
-    if (rel.startsWith('..') || isAbsolute(rel)) {
-        throw new Error(`upload path '${rawPath}' resolves to '${real}', which is outside the project root ` +
-            `'${projectRoot}' — only files within the project directory may be uploaded. ` +
-            'Use a path relative to the project root, or an absolute path inside it.');
+    const allowed = [projectRoot, ...uploadRoots];
+    if (!allowed.some((root) => isInsideRoot(real, root))) {
+        const listed = allowed.map((r) => `'${r}'`).join(', ');
+        throw new Error(`upload path '${rawPath}' resolves to '${real}', which is outside every allowed upload root ` +
+            `(${listed}). Paths must sit under the project directory or an entry in ` +
+            `\`.reticle.json\`'s \`uploadRoots\` (e.g. ["~/Downloads"]).`);
     }
     if (isDeniedPath(real)) {
         throw new Error(`upload path '${rawPath}' matches a sensitive-file pattern and cannot be read by the daemon. ` +
@@ -130,16 +184,19 @@ async function resolveUploadPath(rawPath, projectRoot, fs) {
  * 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 async function rewriteUploadArgs(deps, action, innerArgs) {
+export async function rewriteUploadArgs(deps, action, innerArgs, 
+/** Injected for tests; production uses the process home directory. */
+home = homedir()) {
     if (action !== ActionType.UPLOAD)
         return innerArgs;
     const rawPath = asString(innerArgs['path']);
     if (rawPath === undefined)
         return innerArgs; // no path → browser handles as inline upload
     // Project root is one level above .reticle/
-    const projectRoot = join(deps.reticleRoot, '..');
+    const projectRoot = resolve(join(deps.reticleRoot, '..'));
+    const uploadRoots = await readUploadRoots(projectRoot, deps.fs, home);
     // Blocker 4 fix: stat FIRST, before allocating read buffer, so a huge file fails fast.
-    const realPath = await resolveUploadPath(rawPath, projectRoot, deps.fs);
+    const realPath = await resolveUploadPath(rawPath, projectRoot, deps.fs, uploadRoots, home);
     const fileStat = await deps.fs.stat(realPath).catch(() => {
         throw new Error(`upload path '${rawPath}' could not be read: file not found or not accessible.`);
     });

package/dist/tools/reconcile-tools.js

@@ -1,3 +1,4 @@
+import { bodyCaptureRemedy } from '../honesty/body-capture-remedy.js';
 import { z } from 'zod';
 import { EventType, ReticleCommand, SnapshotMode, urlForMatch } from '@reticlehq/core';
 import { ReticleTool } from './tool-names.js';
@@ -86,7 +87,7 @@ export const RECONCILE_TOOLS = [
                     compared: 0,
                     note: 0 === total
                         ? 'no responses in this window matched — nothing was compared'
-                        : `${String(total)} response(s) matched but NONE carried a recorded body, so nothing was compared. Enable it where your app calls connect(): \`reticle.connect({ captureNetworkBodies: true })\`, then re-run`,
+                        : `${String(total)} response(s) matched but NONE carried a recorded body, so nothing was compared. ${bodyCaptureRemedy(session.sdkVersion)}`,
                 });
             }
             // The whole page, INCLUDING whatever the snapshot's node cap cut off. A comparison against a

package/dist/tools/reload-result.d.ts

@@ -11,4 +11,9 @@
  * remembers the id in sessionStorage so a reload rejoins the SAME session instead of appearing as a
  * new one. This is the remaining half: saying that the page is not back yet.
  */
-export declare function reloadResult(reconnected?: boolean): Record<string, unknown>;
+/**
+ * `waitedMs` is the budget that expired, reported on `confirmed:false` for the same reason the URL
+ * branch reports it (navigate-result.ts): so "Reticle stopped waiting" is distinguishable from "the
+ * page never came back", and the fix — a larger `timeout_ms` — is visible in the result.
+ */
+export declare function reloadResult(reconnected: boolean, waitedMs: number): Record<string, unknown>;

package/dist/tools/reload-result.js

@@ -22,8 +22,13 @@ const RELOAD_NOTE = 'ok means the reload was DISPATCHED, not that the page came
  */
 const RELOAD_RECONNECTED_NOTE = 'the page came back and re-announced itself under the same session id, so this session is live ' +
     'again — no re-selection needed. Anything captured before the reload is gone with the old document.';
-export function reloadResult(reconnected = false) {
+/**
+ * `waitedMs` is the budget that expired, reported on `confirmed:false` for the same reason the URL
+ * branch reports it (navigate-result.ts): so "Reticle stopped waiting" is distinguishable from "the
+ * page never came back", and the fix — a larger `timeout_ms` — is visible in the result.
+ */
+export function reloadResult(reconnected, waitedMs) {
     return reconnected
         ? { ok: true, confirmed: true, note: RELOAD_RECONNECTED_NOTE }
-        : { ok: true, confirmed: false, note: RELOAD_NOTE };
+        : { ok: true, confirmed: false, waitedMs, note: RELOAD_NOTE };
 }