@reticlehq/server 2.11.0 → 2.13.0

package/dist/telemetry/session-metrics.js

@@ -123,6 +123,12 @@ export class SessionMetrics {
      * call a tool, and of the sessions that made exactly one call, most bounced on this.
      */
     #noSessionErrors = 0;
+    /** Connection-level MCP POST failures the SSE stream cannot see. See SessionSummary. */
+    #postSocketFailures = 0;
+    #lifetimePostSocketFailures = 0;
+    /** Retries of those POSTs that then delivered. */
+    #postRetriesSaved = 0;
+    #lifetimePostRetriesSaved = 0;
     /** Longest back-to-back run per tool — a retry loop, which `toolCounts` cannot distinguish. */
     #repeatRuns = new Map();
     #lastTool;
@@ -325,6 +331,24 @@ export class SessionMetrics {
             tool: site,
         });
     }
+    /**
+     * The MCP proxy could not POST a tool call because the TCP socket itself failed (`ENOBUFS`,
+     * `EMFILE`, `ECONNREFUSED` before any bytes left). The SSE stream is still up, so this is
+     * invisible to `mcp_connection_lost`, and the handler never ran, so it is invisible to
+     * `tool_refused`. Counted so a dashboard can see it without a new event kind.
+     */
+    recordPostSocketFailure() {
+        this.#postSocketFailures += 1;
+        this.#lifetimePostSocketFailures += 1;
+    }
+    /**
+     * A bounded retry of an unsent POST then delivered. The pair against `recordPostSocketFailure`:
+     * the retry that quietly saved a call is a different fact from the one that never ran.
+     */
+    recordPostRetrySaved() {
+        this.#postRetriesSaved += 1;
+        this.#lifetimePostRetriesSaved += 1;
+    }
     /** The agent's recent approach run + the call in flight — context for a crash report. */
     get trail() {
         return { breadcrumb: [...this.#breadcrumb], inFlight: this.#inFlight };
@@ -469,12 +493,16 @@ export class SessionMetrics {
                 toolErrors: this.#lifetimeToolErrors,
                 verifications: this.#lifetimeVerifications,
                 bugsFound: this.#lifetimeBugsFound,
+                postSocketFailures: this.#lifetimePostSocketFailures,
+                postRetriesSaved: this.#lifetimePostRetriesSaved,
             }
             : {
                 toolCalls: this.#toolCalls,
                 toolErrors: this.#toolErrors,
                 verifications: this.#verifications,
                 bugsFound: this.#bugsFound,
+                postSocketFailures: this.#postSocketFailures,
+                postRetriesSaved: this.#postRetriesSaved,
             };
         return {
             durationMs: Math.max(0, this.#now() - this.#startedAt),
@@ -488,6 +516,8 @@ export class SessionMetrics {
             bugsFound: scalars.bugsFound,
             ...(this.#bugKinds.size > 0 ? { bugKinds: Object.fromEntries(this.#bugKinds) } : {}),
             ...(this.#noSessionErrors > 0 ? { noSessionErrors: this.#noSessionErrors } : {}),
+            ...(scalars.postSocketFailures > 0 ? { postSocketFailures: scalars.postSocketFailures } : {}),
+            ...(scalars.postRetriesSaved > 0 ? { postRetriesSaved: scalars.postRetriesSaved } : {}),
             ...(this.#repeatRuns.size > 0
                 ? { consecutiveRepeats: Object.fromEntries(this.#repeatRuns) }
                 : {}),
@@ -588,7 +618,9 @@ export class SessionMetrics {
             0 === this.#verifications &&
             0 === this.#toolErrors &&
             0 === this.#bugsFound &&
-            0 === this.#sdkFailures);
+            0 === this.#sdkFailures &&
+            0 === this.#postSocketFailures &&
+            0 === this.#postRetriesSaved);
     }
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */
     reset() {
@@ -596,6 +628,8 @@ export class SessionMetrics {
         this.#toolErrors = 0;
         this.#verifications = 0;
         this.#noSessionErrors = 0;
+        this.#postSocketFailures = 0;
+        this.#postRetriesSaved = 0;
         this.#repeatRuns.clear();
         this.#lastTool = undefined;
         this.#currentRun = 0;

package/dist/telemetry/telemetry.js

@@ -9,7 +9,7 @@
  *   - it is best-effort and non-blocking: a send failure NEVER changes what the tool does.
  *
  * Events are `@reticlehq/core`'s `TelemetryEventSchema`, mapped at the wire into PostHog's capture
- * format (https://posthog.com/docs/api/capture) — PostHog is the analytics backend until Reticle Cloud
+ * format (https://posthog.com/docs/api/capture) — PostHog is the analytics backend until the hosted service
  * grows its own; a project API key is WRITE-ONLY by design, so embedding it in an OSS client is safe.
  * Everything here is wrapped so a telemetry bug can never surface to a user — a broken metric must not
  * break a verification.
@@ -76,8 +76,23 @@ export const FEEDBACK_RETRY_BACKOFF_MS = 750;
  * (`reticle version`/`gate`) ~800ms. Long-lived daemon events still send in-process: a spawn per tool
  * call would be far heavier than a fetch inside an already-running server.
  */
+/**
+ * The budget the DISOWNED child gets, and why it is not `SEND_TIMEOUT_MS`.
+ *
+ * 2s is right for an in-process send: the daemon is waiting on it, so the budget is a latency cost
+ * somebody pays. A detached child pays nobody — the parent has already exited — so the only thing a
+ * short budget there buys is a lost event.
+ *
+ * And it loses the worst ones. Every detached send comes from a SHORT-LIVED CLI process, which pays
+ * cold DNS and a cold TLS route by definition; measured on the feedback path with a WARM cache it
+ * was already 0.694s before any payload moved. `reticle_installed` is the extreme case: it fires
+ * once per machine, on the first Reticle command that machine ever runs, which is the single coldest
+ * network call it will ever make to the collector — so the top of the funnel is the event most
+ * likely to be dropped, and it fails silently like everything else here.
+ */
+const DETACHED_SEND_TIMEOUT_MS = 15_000;
 const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'content-type':'application/json'}," +
-    `body:process.argv[2],signal:AbortSignal.timeout(${SEND_TIMEOUT_MS})})` +
+    `body:process.argv[2],signal:AbortSignal.timeout(${DETACHED_SEND_TIMEOUT_MS})})` +
     '.catch(()=>{}).finally(()=>process.exit(0))';
 /** Env var names — mirror cloud-sync's `RETICLE_*` convention. */
 import { isReticleSourceCheckout } from './dev-repo.js';

package/dist/telemetry/tool-refused.d.ts

@@ -10,7 +10,9 @@
  * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
  * covered without anybody remembering to cover it.
  */
-import { type RefusalReason } from '@reticlehq/core';
+import { RefusalReason, type NoSessionReason } from '@reticlehq/core';
+/** Record the branch code for the no-session error being thrown right now. */
+export declare function notePendingNoSessionReason(reason: NoSessionReason | undefined): void;
 /** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */
 export declare function noteToolServed(): void;
 /** One refused call, reported with its cause and whether it was itself a retry. */

package/dist/telemetry/tool-refused.js

@@ -10,7 +10,7 @@
  * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
  * covered without anybody remembering to cover it.
  */
-import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { RefusalReason, TelemetryActor, TelemetryEventKind, } from '@reticlehq/core';
 import { getTelemetry } from './telemetry.js';
 /**
  * Refusal events one daemon run will send.
@@ -32,6 +32,24 @@ let sent = 0;
  * describe — so the flag lands on the RETRY instead of on the first refusal.
  */
 let lastRefusedTool;
+/**
+ * The no-session branch code for the refusal about to be reported, set by whoever threw it.
+ *
+ * `no_session` is the largest refusal cohort and on its own it is a set difference: nothing
+ * connected, and no word on which of several opposite situations that was. The diagnosis that CAN
+ * say is computed where the error is thrown, and the refusal is classified downstream from the
+ * message, so the two never met (#615).
+ *
+ * Module-level and consumed once, like `lastRefusedTool` above and for the same reason: the
+ * producer and the consumer are one hop apart on the same call, and threading a field through every
+ * refusal path to carry it would touch a dozen call sites that have nothing to do with sessions.
+ * Cleared on read so a later refusal cannot inherit a stale reason.
+ */
+let pendingNoSessionReason;
+/** Record the branch code for the no-session error being thrown right now. */
+export function notePendingNoSessionReason(reason) {
+    pendingNoSessionReason = reason;
+}
 /** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */
 export function noteToolServed() {
     lastRefusedTool = undefined;
@@ -40,16 +58,30 @@ export function noteToolServed() {
 export function reportToolRefused(tool, reason) {
     const retried = lastRefusedTool === tool;
     lastRefusedTool = tool;
+    // Read and clear whatever the throw left, whether or not this refusal can use it: a reason left
+    // sitting would attach itself to an unrelated refusal later in the session.
+    const noSessionReason = pendingNoSessionReason;
+    pendingNoSessionReason = undefined;
     if (sent >= MAX_REFUSALS_PER_SESSION)
         return;
     sent += 1;
     void getTelemetry().emit(TelemetryEventKind.TOOL_REFUSED, {
         actor: TelemetryActor.AGENT,
-        refusal: { tool, reason, retried },
+        refusal: {
+            tool,
+            reason,
+            retried,
+            // Only where it means something. On any other refusal reason this field would be answering
+            // a question nobody asked of it.
+            ...(RefusalReason.NO_SESSION === reason && noSessionReason !== undefined
+                ? { noSessionReason }
+                : {}),
+        },
     });
 }
 /** Tests only — the counters are process-lifetime, so each case has to start from zero. */
 export function resetToolRefusals() {
     sent = 0;
     lastRefusedTool = undefined;
+    pendingNoSessionReason = undefined;
 }

package/dist/telemetry/verification-of.js

@@ -13,7 +13,7 @@
  * be readable and testable on its own rather than inferred from a ternary inside a dispatcher.
  */
 import { CaptureLoss, VerifiedReason } from '@reticlehq/core';
-import { VERIFICATION_TOOLS } from '../tools/feedback-tools.js';
+import { VERDICT_TOOLS } from '../tools/feedback-tools.js';
 import { getBrowserMode } from './browser-mode.js';
 /**
  * The deciding clause, read off the result `decideVerified` wrote it onto.
@@ -92,7 +92,7 @@ function passedOf(result, status) {
  * it verified. That is the product's thesis reduced to a boolean.
  */
 export function verificationOf(toolName, result, durationMs, brand) {
-    if (!VERIFICATION_TOOLS.has(toolName))
+    if (!VERDICT_TOOLS.has(toolName))
         return undefined;
     // A paused session REFUSES the call — nothing driven, nothing asserted. The refusal carries a
     // verdict field so the agent never reads undefined off it, and that field must not be mistaken

package/dist/tools/act-capsule.d.ts

@@ -17,6 +17,16 @@ interface CapsuleSaveInputs {
         file: string;
         line: number;
     };
+    /**
+     * The `.reticle` this capsule belongs in, from the session the act ACTUALLY drove.
+     *
+     * Passed in rather than re-resolved here, because re-resolving loses twice: `args.sessionId` is
+     * frequently absent, and `sessions.resolve(undefined)` throws whenever more than one tab is
+     * connected — which is precisely the multi-project case this routing exists for, so it failed in
+     * exactly the situation it was written to fix. The caller also knows about a session the act
+     * FOLLOWED through a navigation; this file cannot.
+     */
+    root?: string | undefined;
 }
 /** Returns the capsule id when one was written, or undefined when there was nothing to save. */
 export declare function saveFailedAssertCapsule(inputs: CapsuleSaveInputs): Promise<string | undefined>;

package/dist/tools/act-capsule.js

@@ -13,16 +13,22 @@ import { ActionType, AnchorKind } from '@reticlehq/core';
 import { CapsuleStore, capsuleId, CAPSULE_VERSION } from '../capsule/capsule-store.js';
 import { ReticleTool } from './tool-names.js';
 import { asRecord, asString } from './tools-helpers.js';
+import { sessionRoot } from '../project/session-root.js';
 /** Returns the capsule id when one was written, or undefined when there was nothing to save. */
 export async function saveFailedAssertCapsule(inputs) {
-    const { deps, verdict, capsule, links, args, actResult, actedSource } = inputs;
+    const { deps, verdict, capsule, links, args, actResult, actedSource, root: given } = inputs;
     if (verdict.pass || capsule === undefined)
         return undefined;
     const id = capsuleId(deps.now(), asString(args['ref']) ?? 'assert');
     const expectedText = links
         .map((l) => ('name' in l ? `${l.kind} ${String(l.name)}` : l.kind))
         .join(' AND ');
-    const saved = await new CapsuleStore(deps.fs, deps.reticleRoot).save({
+    // The capsule belongs to the project whose app just failed, not to wherever the daemon stands.
+    // Same rule and same resolver as every other artifact: a capsule written into a sibling repo is
+    // evidence filed against a codebase that did not produce it, and it outlives the turn.
+    // The caller's answer wins; the resolver is the fallback for callers that have no session.
+    const root = given ?? sessionRoot(deps, asString(args['sessionId']));
+    const saved = await new CapsuleStore(deps.fs, root).save({
         version: CAPSULE_VERSION,
         id,
         createdAt: deps.now(),

package/dist/tools/act-danger.d.ts

@@ -2,7 +2,8 @@ import { ActionType } from '@reticlehq/core';
 export declare function assertNotDestructive(action: ActionType, innerArgs: Record<string, unknown>, inspected: unknown): void;
 /**
  * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
- * source alone never says so.
+ * source alone never says so. Each end is classified on its own text and role, so a Payment
+ * option dragged onto Save is not a payment.
  */
 export declare function assertDragNotDestructive(innerArgs: Record<string, unknown>, from: unknown, to: unknown): void;
 /**

package/dist/tools/act-danger.js

@@ -22,23 +22,31 @@ function descriptorText(value) {
         asString(descriptor['formText']) ?? '',
     ].join(' ');
 }
+function descriptorRole(value) {
+    const role = asString(asRecord(value)['role']);
+    return role !== undefined && role.length > 0 ? role : undefined;
+}
+function isDestructiveDescriptor(value) {
+    return isDangerousActionText(descriptorText(value), descriptorRole(value));
+}
 export function assertNotDestructive(action, innerArgs, inspected) {
     if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
         return;
     if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
-    if (!isDangerousActionText(descriptorText(inspected)))
+    if (!isDestructiveDescriptor(inspected))
         return;
     throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
 }
 /**
  * A drag is judged on BOTH ends. Dropping a harmless row onto "Delete" is destructive, and the
- * source alone never says so.
+ * source alone never says so. Each end is classified on its own text and role, so a Payment
+ * option dragged onto Save is not a payment.
  */
 export function assertDragNotDestructive(innerArgs, from, to) {
     if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
-    if (!isDangerousActionText(`${descriptorText(from)} ${descriptorText(to)}`))
+    if (!isDestructiveDescriptor(from) && !isDestructiveDescriptor(to))
         return;
     throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
 }

package/dist/tools/act-observation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What to do when the observer left in the middle of an act.
+ *
+ * A full-document navigation — often the very thing the act CAUSED — tears the SDK down. The page
+ * re-announces, and whatever this call still had in flight is gone. That is a fact about the
+ * observer, never about the application, and the difference matters: every honest verdict this
+ * engine can give depends on not converting "I stopped watching" into "your app is broken".
+ *
+ * Extracted from act-tools.ts, which had reached the file-size cap. It earns its own module because
+ * it is one idea — follow the document that took over, and re-ask there — used from the two points
+ * where observation can be lost: a write rejected at dispatch, and a wait cut off mid-predicate.
+ */
+import type { Session } from '../session/session.js';
+import { type SuccessorRegistry } from '../session/session-successor.js';
+import type { EvalResult } from '../events/predicate-eval.js';
+export interface FollowSuccessor {
+    sessions: SuccessorRegistry;
+    session: Session;
+    verdict: EvalResult;
+    /** Total budget the CALLER granted, in ms. */
+    timeout: number;
+    /** `session.elapsed()` at the moment the predicate started. */
+    predicateStarted: number;
+    /** Re-ask the declared consequence on `next`, with whatever budget is left. */
+    reevaluate: (next: Session, budgetMs: number) => Promise<EvalResult>;
+}
+export interface FollowedOutcome {
+    session: Session;
+    verdict: EvalResult;
+    /** True when the wait moved to a new document, so the caller must reset its event cursor. */
+    followed: boolean;
+}
+/**
+ * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
+ *
+ * `navigate` already waits for the HELLO and returns the new id; this path used to grade
+ * `observation_lost` and leave the agent holding a DEAD id, so the next assert failed even though
+ * the new page had loaded perfectly. Two live tabs at that origin is still a guess, and
+ * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
+ */
+export declare function followLostObservation(input: FollowSuccessor): Promise<FollowedOutcome>;

package/dist/tools/act-observation.js

@@ -0,0 +1,36 @@
+/**
+ * What to do when the observer left in the middle of an act.
+ *
+ * A full-document navigation — often the very thing the act CAUSED — tears the SDK down. The page
+ * re-announces, and whatever this call still had in flight is gone. That is a fact about the
+ * observer, never about the application, and the difference matters: every honest verdict this
+ * engine can give depends on not converting "I stopped watching" into "your app is broken".
+ *
+ * Extracted from act-tools.ts, which had reached the file-size cap. It earns its own module because
+ * it is one idea — follow the document that took over, and re-ask there — used from the two points
+ * where observation can be lost: a write rejected at dispatch, and a wait cut off mid-predicate.
+ */
+import { awaitDocumentSuccessor } from '../session/session-successor.js';
+/**
+ * Follow the unique same-origin successor and re-ask there, or leave the verdict untouched.
+ *
+ * `navigate` already waits for the HELLO and returns the new id; this path used to grade
+ * `observation_lost` and leave the agent holding a DEAD id, so the next assert failed even though
+ * the new page had loaded perfectly. Two live tabs at that origin is still a guess, and
+ * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
+ */
+export async function followLostObservation(input) {
+    const { sessions, session, verdict, timeout, predicateStarted, reevaluate } = input;
+    if (true !== verdict.observationLost || 0 >= timeout)
+        return { session, verdict, followed: false };
+    const remaining = timeout - (session.elapsed() - predicateStarted);
+    const next = remaining > 0 ? await awaitDocumentSuccessor(sessions, session, remaining) : null;
+    if (null === next)
+        return { session, verdict, followed: false };
+    // Computed on the DEPARTED session, before the caller points at the successor: the new session's
+    // elapsed() starts at 0 and would silently refund the whole budget the caller had already spent.
+    const leftover = timeout - (session.elapsed() - predicateStarted);
+    if (leftover <= 0)
+        return { session: next, verdict, followed: true };
+    return { session: next, verdict: await reevaluate(next, leftover), followed: true };
+}

package/dist/tools/act-preflight.d.ts

@@ -0,0 +1,20 @@
+export declare function assertSequenceSteps(steps: readonly unknown[]): void;
+/**
+ * Throws if this call cannot honestly be driven. Call it after the args are parsed and before the
+ * first dispatch — anything that depends on what is actually rendered belongs after the action.
+ */
+export declare function preflightAct(actArgs: Record<string, unknown>, until: unknown): void;
+/**
+ * Dispatch a write, or report that its outcome went unobserved.
+ *
+ * Returns null — never throws — when the transport was displaced by a newer connection claiming the
+ * same id. That happens on any full-document navigation the act itself causes: the page unloads,
+ * re-announces, and the write in flight is rejected by the handle that just died.
+ *
+ * The write is deliberately NOT re-sent. Re-asking a READ on the successor is free; re-sending a
+ * WRITE is not, because nothing can prove the first one did not reach the page — and a duplicated
+ * click on a button that charges a card is a far worse outcome than a verdict of "I could not see".
+ * Every other failure propagates unchanged: only a replacement is an observation problem, and
+ * treating a timeout or a refusal as one would launder a real failure into a shrug.
+ */
+export declare function dispatchAct<T>(send: () => Promise<T>): Promise<T | null>;

package/dist/tools/act-preflight.js

@@ -0,0 +1,98 @@
+/**
+ * Everything refused BEFORE the action window opens.
+ *
+ * Both checks here share one property, and it is the reason they belong together: each is decidable
+ * without touching the page, and each would otherwise be discovered only after the click had landed
+ * — when the action is spent, the page has moved, and the honest answer has already been lost.
+ *
+ * Refusing early is not a convenience. `reticle_act_and_wait` promises a verdict, and a verdict that
+ * blames the app for the caller's own mistake is the most damaging thing a verification tool can
+ * produce: it sends somebody to fix code that is not broken. "Nothing was acted on" is a far better
+ * outcome than "unknown".
+ */
+import { SessionReplacedError } from '../session/pending-commands.js';
+import { assertNativeInputSupported } from './act-danger.js';
+import { unevaluablePredicateReason } from '../events/predicate-precheck.js';
+/**
+ * Refuse a sequence whose steps cannot be addressed.
+ *
+ * `steps` is a bare array of objects, so a step with neither `ref` nor `target` used to travel on
+ * and dispatch as `ref: ''`. The browser then threw `ref '' no longer resolves to an element` —
+ * a stale-ref diagnosis for a missing locator — and the caller went looking for a re-render.
+ *
+ * `target` is the same locator `reticle_act` / `reticle_act_and_wait` take; the handler resolves it
+ * with `resolveActTarget` before dispatch. This check only asks that every step names one of the
+ * two, and it runs before the first step, so a typo in step three cannot leave one and two applied.
+ */
+/**
+ * Keys an agent reaches for when it means "and prove this happened".
+ *
+ * A sub-step reads `ref`/`target`/`action`/`args` and nothing else, and the schema is a permissive
+ * record, so any of these was accepted and dropped. `until` is the likeliest of them by a distance:
+ * it is what act_and_wait — the tool immediately next to this one — calls its assertion.
+ *
+ * Silently ignoring one manufactures a false green. A sequence carrying an impossible `until` came
+ * back `completed: 1` with no error and nothing said about the predicate, which reads as the
+ * consequence having held. act_sequence cannot grade one; refusing and naming the tool that can is
+ * the same answer given to an unsupported native click, and for the same reason.
+ */
+const CONSEQUENCE_KEYS = ['until', 'expect', 'assert', 'waitFor'];
+export function assertSequenceSteps(steps) {
+    if (0 === steps.length) {
+        throw new Error('reticle_act_sequence was given no steps. Pass steps: [{ ref, action, args? }] or [{ target, action, args? }] — nothing was acted on.');
+    }
+    steps.forEach((raw, i) => {
+        const step = 'object' === typeof raw && null !== raw ? raw : {};
+        const claimed = CONSEQUENCE_KEYS.find((k) => step[k] !== undefined);
+        if (claimed !== undefined) {
+            throw new Error(`step ${String(i)} carries \`${claimed}\`, and reticle_act_sequence cannot grade it. ` +
+                'Sub-steps are dispatched, never asserted — the key would be dropped and the sequence ' +
+                'would report success having checked nothing. Drive the steps here, then prove the ' +
+                'consequence with reticle_act_and_wait on the LAST action (its `until` is graded), or ' +
+                'with reticle_assert after this call. Nothing was acted on.');
+        }
+        if ('string' === typeof step['ref'] && step['ref'].length > 0)
+            return;
+        if (step['target'] !== undefined)
+            return;
+        throw new Error(`step ${String(i)} has no \`ref\` or \`target\`. ` +
+            'Sequence steps take `ref` (from reticle_query/reticle_snapshot) or `target` ' +
+            '(e.g. { testid } or { label }), the same locator reticle_act accepts. ' +
+            'Nothing was acted on — the whole sequence is refused so a bad step cannot leave the earlier ones half-applied.');
+    });
+}
+/**
+ * Throws if this call cannot honestly be driven. Call it after the args are parsed and before the
+ * first dispatch — anything that depends on what is actually rendered belongs after the action.
+ */
+export function preflightAct(actArgs, until) {
+    // This path cannot honour a native-input request, and taking the argument and ignoring it told
+    // the agent its trusted click had happened. See act-danger.
+    assertNativeInputSupported(actArgs);
+    const unevaluable = unevaluablePredicateReason(until);
+    if (unevaluable !== undefined)
+        throw new Error(unevaluable);
+}
+/**
+ * Dispatch a write, or report that its outcome went unobserved.
+ *
+ * Returns null — never throws — when the transport was displaced by a newer connection claiming the
+ * same id. That happens on any full-document navigation the act itself causes: the page unloads,
+ * re-announces, and the write in flight is rejected by the handle that just died.
+ *
+ * The write is deliberately NOT re-sent. Re-asking a READ on the successor is free; re-sending a
+ * WRITE is not, because nothing can prove the first one did not reach the page — and a duplicated
+ * click on a button that charges a card is a far worse outcome than a verdict of "I could not see".
+ * Every other failure propagates unchanged: only a replacement is an observation problem, and
+ * treating a timeout or a refusal as one would launder a real failure into a shrug.
+ */
+export async function dispatchAct(send) {
+    try {
+        return await send();
+    }
+    catch (error) {
+        if (error instanceof SessionReplacedError)
+            return null;
+        throw error;
+    }
+}

package/dist/tools/act-sequence-retry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The two things a sequence step needs beyond a plain act: a retry when the ref goes stale under a
+ * re-render, and a result shaped for the per-step report.
+ *
+ * ── THE RETRY ─────────────────────────────────────────────────────────────────────────────────
+ *
+ * Refs are invalidated by a re-render, and `reticle_act_sequence` exists precisely because the
+ * caller cannot re-snapshot between steps. So `fill -> fill -> submit` fails on step two the moment
+ * step one causes React to re-render — and the SAME refs then work when the caller retries the whole
+ * sequence by hand, which is the tell: this is a race with the render, not a dead element. Losing
+ * the sequence to it makes the tool unusable for the exact shape it was built for.
+ *
+ * The fix is one retry, after the app has been given the grace period it already gets elsewhere, and
+ * ONLY for staleness. A genuinely gone element fails again immediately, and a step that failed for
+ * any other reason is never retried — a tool that quietly re-runs actions would turn one click into
+ * two, which is worse than the failure it was papering over.
+ */
+import { waitForReaction } from './react-grace.js';
+export declare const isStaleRefError: (error: string | undefined) => boolean;
+/** The shape a step attempt returns. Structural so this file needs nothing from the tool layer. */
+export interface StepOutcome {
+    ok: boolean;
+    error?: string | undefined;
+    result?: unknown;
+}
+/** Just enough of a session for the grace period. Same structural contract react-grace.ts uses. */
+type ReactionSource = Parameters<typeof waitForReaction>[0];
+/**
+ * Run one step, and retry it once if — and only if — its ref went stale under a re-render.
+ *
+ * `attempt` is called at most twice with identical arguments, so it must be the same idempotent
+ * dispatch the caller would have made itself.
+ */
+export declare function runStepWithStaleRetry(attempt: () => Promise<StepOutcome>, session: ReactionSource, since: number, budgetMs: number, opts?: {
+    sleep(ms: number): Promise<void>;
+}): Promise<StepOutcome>;
+/**
+ * One step's entry in the per-step report.
+ *
+ * Only the fields the underlying act actually produced. Copying them conditionally keeps a clean step
+ * from carrying a row of nulls that read as "we looked and found nothing" rather than "there was
+ * nothing to look for".
+ */
+export declare function describeStepResult(step: Record<string, unknown>, result: Record<string, unknown>): Record<string, unknown>;
+export {};

package/dist/tools/act-sequence-retry.js

@@ -0,0 +1,58 @@
+/**
+ * The two things a sequence step needs beyond a plain act: a retry when the ref goes stale under a
+ * re-render, and a result shaped for the per-step report.
+ *
+ * ── THE RETRY ─────────────────────────────────────────────────────────────────────────────────
+ *
+ * Refs are invalidated by a re-render, and `reticle_act_sequence` exists precisely because the
+ * caller cannot re-snapshot between steps. So `fill -> fill -> submit` fails on step two the moment
+ * step one causes React to re-render — and the SAME refs then work when the caller retries the whole
+ * sequence by hand, which is the tell: this is a race with the render, not a dead element. Losing
+ * the sequence to it makes the tool unusable for the exact shape it was built for.
+ *
+ * The fix is one retry, after the app has been given the grace period it already gets elsewhere, and
+ * ONLY for staleness. A genuinely gone element fails again immediately, and a step that failed for
+ * any other reason is never retried — a tool that quietly re-runs actions would turn one click into
+ * two, which is worse than the failure it was papering over.
+ */
+import { waitForReaction } from './react-grace.js';
+/** Matches the daemon's own wording, which error-recovery.ts also keys its STALE_REF hint off. */
+const STALE_REF = /no longer resolves to an element/i;
+export const isStaleRefError = (error) => error !== undefined && STALE_REF.test(error);
+const realSleep = {
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+/**
+ * Run one step, and retry it once if — and only if — its ref went stale under a re-render.
+ *
+ * `attempt` is called at most twice with identical arguments, so it must be the same idempotent
+ * dispatch the caller would have made itself.
+ */
+export async function runStepWithStaleRetry(attempt, session, since, budgetMs, opts = realSleep) {
+    const first = await attempt();
+    if (first.ok || !isStaleRefError(first.error))
+        return first;
+    await waitForReaction(session, since, budgetMs, opts);
+    return attempt();
+}
+/**
+ * One step's entry in the per-step report.
+ *
+ * Only the fields the underlying act actually produced. Copying them conditionally keeps a clean step
+ * from carrying a row of nulls that read as "we looked and found nothing" rather than "there was
+ * nothing to look for".
+ */
+export function describeStepResult(step, result) {
+    const out = {
+        ref: result['ref'] ?? step['ref'],
+        action: result['action'] ?? step['action'],
+        dispatched: result['dispatched'] ?? true,
+        settled: result['settled'] ?? null,
+        settleReason: result['settleReason'] ?? null,
+    };
+    for (const key of ['testid', 'component', 'role', 'name', 'source', 'warning']) {
+        if (result[key] !== undefined)
+            out[key] = result[key];
+    }
+    return out;
+}

package/dist/tools/act-sequence-tool.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `reticle_act_sequence` — several actions compiled into one round trip.
+ *
+ * Split out of `act-tools.ts` when that file passed the 1000-line backstop. A tool seam rather than
+ * an arbitrary one: its two neighbours drive ONE action and grade its consequence, while this one
+ * compiles a list of steps and runs them inside a single action window, reporting per step.
+ *
+ * It keeps its own `beginAction` — the dispatch and the attribution window that must wrap it stay in
+ * the same file, which is the property `dispatch-attribution.test.ts` enforces. An earlier attempt
+ * split the shared `actCommand` helper out instead, which separated the two and that guard caught it.
+ */
+import { type ToolDef } from './tool-kit.js';
+export declare const ACT_SEQUENCE_TOOL: ToolDef;