@e2edev/e2e 0.7.0 → 0.9.0

package/README.md

@@ -23,7 +23,7 @@ import type { E2EConfig } from '@e2edev/e2e';
 import { playwright } from '@e2edev/playwright';
 
 export default {
-  targets: [{ name: 'web', platform: 'web', engine: playwright({ url: process.env.APP_URL ?? 'http://localhost:3000' }) }],
+  targets: [{ name: 'web', engine: playwright({ url: process.env.APP_URL ?? 'http://localhost:3000' }) }],
 } satisfies E2EConfig;
 ```
 
@@ -37,7 +37,6 @@ export default {
   targets: [
     {
       name: 'web',
-      platform: 'web',
       engine: playwright({
         url: 'http://127.0.0.1:3000',
         services: [
@@ -147,6 +146,12 @@ agent step, in the AI SDK devtools database shape. Open it with
 [unbox-ai](https://github.com/tester-army/unbox-ai):
 `npx unbox-ai .e2e/ai-trace.json`.
 
+`e2e run --video` records every attempt: a WebM screencast of the page under
+the attempt's artifact directory, named in the failure recap.
+`artifacts: ['screenshot', 'trace', 'video']` turns it on for every run, and
+`artifacts: { kinds: ['screenshot', 'trace', 'video'], video: { retain:
+'on-failure' } }` keeps only the recordings of attempts that did not pass.
+
 ## Coding agents
 
 `e2e init` installs a skill, `SKILL.md` plus one file per topic, into
@@ -163,7 +168,7 @@ npx --no-install e2e guide writing-tests  # one topic
 
 ## Current limitations
 
-- The HTML reporter and video artifacts are not available.
+- The HTML reporter is not available.
 - Reported steps carry no source locations.
 
 ## Contributing

package/dist/agent/act-validation.d.ts

@@ -3,15 +3,18 @@
  * functions with no dispatch state: everything a step's arguments and an
  * executor's verdict must satisfy before the harness trusts them.
  */
-import type { AgentOptions, AgentParams, JsonValue, Secret } from '../types.ts';
+import type { ActOptions, AgentParams, JsonValue, Secret } from '../types.ts';
 import { type StepVerdict } from './executor.ts';
 /** Normalizes and bounds the instruction per spec 02. */
 export declare function validateInstruction(instruction: string, api: string): string;
 /**
- * The `act` type has no `schema` or `vision`; a caller outside the type
- * checker who passes one still fails loudly instead of being silently ignored.
+ * The `act` type has no `schema` or `vision`, and no key outside
+ * `ActOptions`; a caller outside the type checker who passes one still fails
+ * loudly instead of being silently ignored. The pre-0.8 shapes land here too:
+ * `act(instruction, params)` arrives as an options bag of the caller's own
+ * keys, and `act(instruction, params, options)` as a third argument.
  */
-export declare function rejectUnsupportedActOptions(options: AgentOptions | undefined): void;
+export declare function validateActOptions(options: ActOptions | undefined, extraArguments: number): void;
 /**
  * Validates parameters and returns an inert, secret-free snapshot plus the
  * declared secrets. A `Secret` value is projected to

package/dist/agent/act-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act-validation.d.ts","sourceRoot":"","sources":["../../src/agent/act-validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAkB,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEhG,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAWlE,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAa5E;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,CAWnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG;IAC/D,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;IAC3D,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,CAoBA;AAqBD,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,WAAW,CAqCnF"}
+{"version":3,"file":"act-validation.d.ts","sourceRoot":"","sources":["../../src/agent/act-validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAkB,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE9F,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAWlE,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAa5E;AAID;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CA4BhG;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG;IAC/D,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;IAC3D,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,CAoBA;AAqBD,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,WAAW,CAqCnF"}

package/dist/agent/act-validation.js

@@ -26,13 +26,23 @@ export function validateInstruction(instruction, api) {
     }
     return normalized;
 }
+const ACT_OPTION_KEYS = new Set(['params', 'timeout', 'maxSteps', 'maxModelCalls']);
 /**
- * The `act` type has no `schema` or `vision`; a caller outside the type
- * checker who passes one still fails loudly instead of being silently ignored.
+ * The `act` type has no `schema` or `vision`, and no key outside
+ * `ActOptions`; a caller outside the type checker who passes one still fails
+ * loudly instead of being silently ignored. The pre-0.8 shapes land here too:
+ * `act(instruction, params)` arrives as an options bag of the caller's own
+ * keys, and `act(instruction, params, options)` as a third argument.
  */
-export function rejectUnsupportedActOptions(options) {
+export function validateActOptions(options, extraArguments) {
+    if (extraArguments > 0) {
+        throw new TestError('INVALID_ARGUMENT', 'agent.act takes two arguments: act(instruction, { params, timeout, maxSteps, maxModelCalls })');
+    }
     if (options === undefined)
         return;
+    if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+        throw new TestError('INVALID_ARGUMENT', 'agent.act options must be a plain object');
+    }
     const loose = options;
     const unsupported = (name) => {
         throw new ConfigurationError('UNSUPPORTED_CAPABILITY', `agent.act ${name} is not part of this milestone`);
@@ -41,6 +51,11 @@ export function rejectUnsupportedActOptions(options) {
         unsupported('structured output (options.schema)');
     if (loose.vision !== undefined)
         unsupported('vision evidence (options.vision)');
+    const unknown = Object.keys(options).filter((key) => !ACT_OPTION_KEYS.has(key));
+    if (unknown.length > 0) {
+        const listed = unknown.map((key) => JSON.stringify(key)).join(', ');
+        throw new TestError('INVALID_ARGUMENT', `agent.act options has no ${unknown.length === 1 ? 'key' : 'keys'} ${listed}; the values an instruction refers to go under params: act(instruction, { params: { ${unknown.join(', ')} } })`);
+    }
 }
 /**
  * Validates parameters and returns an inert, secret-free snapshot plus the

package/dist/agent/act-validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"act-validation.js","sourceRoot":"","sources":["../../src/agent/act-validation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"act-validation.js","sourceRoot":"","sources":["../../src/agent/act-validation.ts"],"names":[],"mappings":"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"}

package/dist/agent/act.d.ts

@@ -9,10 +9,10 @@
  * locate/judgment tier runs on. Trace-cache participation — replay, live
  * recording, staging — lives beside the dispatch in `StepTraceSession`.
  */
-import type { AgentOptions, AgentParams, AgentResult } from '../types.ts';
+import type { ActOptions, ActResult } from '../types.ts';
 import type { AgentContext } from './invocation.ts';
 /** Runs one `agent.act()` call as a harness-dispatched executor step. */
-export declare function runActStep(runtime: AgentContext, instruction: string, params: AgentParams | undefined, options: AgentOptions | undefined): Promise<AgentResult>;
+export declare function runActStep(runtime: AgentContext, instruction: string, options: ActOptions | undefined, extraArguments?: number): Promise<ActResult>;
 /**
  * Runs one `agent.assert()` call through the executor socket. Used when a
  * custom executor is configured: the brain that plans flows also judges

package/dist/agent/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/agent/act.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,OAAO,KAAK,EAEV,YAAY,EACZ,WAAW,EACX,WAAW,EAKZ,MAAM,aAAa,CAAC;AAmBrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAkCpD,yEAAyE;AACzE,wBAAsB,UAAU,CAC9B,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,OAAO,EAAE,YAAY,GAAG,SAAS,GAChC,OAAO,CAAC,WAAW,CAAC,CAgBtB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GAChF,OAAO,CAAC,IAAI,CAAC,CAqBf"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/agent/act.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EAOV,MAAM,aAAa,CAAC;AAmBrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAkFpD,yEAAyE;AACzE,wBAAsB,UAAU,CAC9B,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,cAAc,SAAI,GACjB,OAAO,CAAC,SAAS,CAAC,CAepB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GAChF,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/agent/act.js

@@ -11,30 +11,71 @@
  */
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { EngineError } from '../engine/surface.js';
-import { ConfigurationError, TestError } from '../internal/errors.js';
+import { asEngineError, ConfigurationError, TestError } from '../internal/errors.js';
 import { timestamp } from '../internal/ids.js';
 import { resolveNavigationUrl } from '../internal/urls.js';
 import { AgentError, CATEGORY_BY_CODE, isAgentError, toAgentError } from './error.js';
-import { rejectUnsupportedActOptions, validateInstruction, validateParams, validateVerdict, } from './act-validation.js';
+import { validateActOptions, validateInstruction, validateParams, validateVerdict, } from './act-validation.js';
 import { resolveBoundedBudget, resolveTimeout } from './call-options.js';
 import { RUNTIME_CODES, } from './executor.js';
 import { isDerivedValue } from './derived.js';
 import { projectPriorSteps, serializeLedger } from './ledger.js';
 import { instantiateLanguageModel } from './model/sdk.js';
-import { observationShape, pixelsForModel, prepareObservation, projectTree, settleObservation, } from './observation.js';
+import { isTransitionalObservation, observationShape, pixelsForModel, prepareObservation, projectTree, settleObservation, } from './observation.js';
+import { observationByteBudget } from './observation-budget.js';
 import { boundedOperation, checkStepClock, instrumentPhase, recordPolicyEvent, retryingObserve } from './phases.js';
-import { containerKey, describeAction } from './actions.js';
-import { describePosition } from '../cache/relocate.js';
+import { containerKey, describeAction, describeTarget } from './actions.js';
+import { describePosition, relocateDescriptor } from '../cache/relocate.js';
 import { authorizeSecretFill } from './secrets.js';
 import { ModelUsage, tokenFields } from './usage.js';
 import { StepTraceSession } from './step-cache.js';
+/**
+ * Ceiling on one targeted grammar action: the time the engine may wait for a
+ * node to become actionable before the failure goes back to the model.
+ * `actionTimeout` bounds every engine operation and doubles as the judgment
+ * tier's clock, so projects raise it for slow models; a tap under a consent
+ * overlay then sits in the engine's actionability retry for the whole budget
+ * (90 s in the testbed) before the model learns anything, when the useful
+ * answer — what is in the way — is known within seconds. Navigation keeps the
+ * full budget: a slow page really can take that long to load.
+ */
+const MAX_TARGETED_ACTION_MS = 15_000;
+/**
+ * How many times a targeted action re-finds its node after the engine reports
+ * it stale. One relocation covers a re-render between the observation and the
+ * action; the second covers a render tick landing between the fresh look and
+ * the action itself. A control that keeps vanishing faster than that is
+ * reported to the model as gone.
+ */
+const MAX_STALE_RELOCATIONS = 2;
+/**
+ * The change wait after a scroll or a mutating project tool. A scroll moves
+ * nothing the tree records and a tool usually changes state the screen shows
+ * only after a reload, so most of these change no shape at all and a long
+ * wait is pure cost; a windowed list rendering its next rows, or a tool the
+ * page reacts to, does so within a few hundred milliseconds.
+ */
+const BRIEF_CHANGE_WAIT_MS = 500;
+/**
+ * Observations kept for resolving an id the newest one no longer carries.
+ * A turn that batches actions addresses the screen it saw, while every
+ * action's own look re-observes; on an engine that mints ids per observation
+ * (a device), each look renumbers the tree. A few looks back is as far as one
+ * turn can reach.
+ */
+const MAX_RECENT_OBSERVATIONS = 8;
+/**
+ * How far one grammar scroll moves. The engine's default flick is half the
+ * scrolled box; a deliberate scroll of three quarters keeps every row on
+ * screen at least once while covering a long feed in fewer actions.
+ */
+const SCROLL_MOMENTUM = 'slow';
 /** Runs one `agent.act()` call as a harness-dispatched executor step. */
-export async function runActStep(runtime, instruction, params, options) {
+export async function runActStep(runtime, instruction, options, extraArguments = 0) {
     const normalized = validateInstruction(instruction, 'agent.act');
-    rejectUnsupportedActOptions(options);
-    const { projected, secrets } = validateParams(params);
-    await dispatchAgentStep(runtime, {
+    validateActOptions(options, extraArguments);
+    const { projected, secrets } = validateParams(options?.params);
+    return dispatchAgentStep(runtime, {
         api: 'agent.act',
         kind: 'act',
         instruction: normalized,
@@ -45,7 +86,6 @@ export async function runActStep(runtime, instruction, params, options) {
         maxSteps: options?.maxSteps,
         maxModelCalls: options?.maxModelCalls,
     });
-    return { ok: true };
 }
 /**
  * Runs one `agent.assert()` call through the executor socket. Used when a
@@ -83,7 +123,7 @@ export async function runAssertStep(runtime, assertion, options) {
  * (cache/context.ts).
  */
 async function dispatchAgentStep(runtime, spec) {
-    await runtime.steps.run('agent', spec.api, spec.instruction, async () => {
+    return runtime.steps.run('agent', spec.api, spec.instruction, async () => {
         const dispatch = new ActDispatch(runtime, spec);
         try {
             let verdict;
@@ -95,6 +135,7 @@ async function dispatchAgentStep(runtime, spec) {
             }
             dispatch.settle(validateVerdict(verdict, runtime.executor.name));
             await dispatch.conclude('passed');
+            return dispatch.result();
         }
         catch (cause) {
             await dispatch.conclude(isAgentError(cause) && cause.code === 'CANCELLED' ? 'cancelled' : 'failed');
@@ -124,6 +165,8 @@ class ActDispatch {
         ledgerBytes: 0,
     };
     latest;
+    /** The newest observations of the step, oldest first; see MAX_RECENT_OBSERVATIONS. */
+    recent = [];
     explanation;
     /** First budget/timeout/cancel failure; runtime truth outranks the verdict. */
     hardStop;
@@ -165,6 +208,17 @@ class ActDispatch {
     stepIndex;
     /** The last pixel decision recorded on this step: `allowed`, or the withheld reason. */
     pixelsDecided;
+    /**
+     * The screen shape the newest committed action was resolved against, kept
+     * until the next settled observation has waited for the screen to leave it.
+     * Armed by actions whose effect shows in the tree; a secret fill leaves no
+     * visible trace and a scroll moves nothing the tree records, so neither
+     * arms it. Without this, the observation after a tap on a link reads the
+     * old page, stable and wrong, and the model repairs what already worked.
+     */
+    pendingChange;
+    /** The change wait the pending action asked for; undefined takes the default. */
+    pendingChangeWaitMs;
     constructor(runtime, spec) {
         this.runtime = runtime;
         this.spec = spec;
@@ -264,7 +318,7 @@ class ActDispatch {
     buildActions() {
         return {
             tap: (target) => this.commitTargeted('tap', target, async (node) => {
-                await this.session.perform(node.ref, { kind: 'tap' }, this.operation());
+                await this.session.perform(node.ref, { kind: 'tap' }, this.actionOperation());
                 return { name: 'tap', node };
             }),
             type: (target, value) => {
@@ -272,7 +326,7 @@ class ActDispatch {
                     throw new TestError('INVALID_ARGUMENT', 'type value must be a string');
                 }
                 return this.commitTargeted('type', target, async (node) => {
-                    await this.session.perform(node.ref, { kind: 'fill', value, sensitive: false }, this.operation());
+                    await this.session.perform(node.ref, { kind: 'fill', value, sensitive: false }, this.actionOperation());
                     return { name: 'type', node, value };
                 });
             },
@@ -282,7 +336,7 @@ class ActDispatch {
                     throw new TestError('INVALID_ARGUMENT', 'press key must be a short non-empty string');
                 }
                 return this.commitTargeted('press', target, async (node) => {
-                    await this.session.perform(node.ref, { kind: 'press', key }, this.operation());
+                    await this.session.perform(node.ref, { kind: 'press', key }, this.actionOperation());
                     return { name: 'press', node, key };
                 });
             },
@@ -291,7 +345,7 @@ class ActDispatch {
                     throw new TestError('INVALID_ARGUMENT', 'select value must be a non-empty option label');
                 }
                 return this.commitTargeted('selectOption', target, async (node) => {
-                    await this.session.perform(node.ref, { kind: 'selectOption', value }, this.operation());
+                    await this.session.perform(node.ref, { kind: 'selectOption', value }, this.actionOperation());
                     return { name: 'select', node, value };
                 });
             },
@@ -344,6 +398,7 @@ class ActDispatch {
             redact: this.redact,
             testIdAttribute: this.runtime.config.testIdAttribute,
             currentPath: (nodes) => this.currentPath(nodes !== undefined && nodes === this.latest?.nodes ? this.latest : undefined),
+            replaying: (active) => this.runtime.steps.replaying(active),
         };
     }
     /** Best-effort current location path + query, for trace preconditions. */
@@ -468,7 +523,7 @@ class ActDispatch {
             this.modelId = usage.modelId;
         this.runtime.steps.recordEvent({
             kind: 'model',
-            startedAt: timestamp(),
+            startedAt: usage?.startedAt ?? timestamp(),
             durationMs: Math.max(0, Math.round(usage?.durationMs ?? 0)),
             status: 'passed',
             name: 'executor',
@@ -501,10 +556,25 @@ class ActDispatch {
                 this.reserveAction();
                 this.stepCache?.recordGap(call.name);
             }
-            return instrumentPhase(this.runtime, { api: this.spec.api, kind: 'engine', phase: 'agent.action', name: `tool:${call.name}` }, body);
+            const value = await instrumentPhase(this.runtime, { api: this.spec.api, kind: 'engine', phase: 'agent.action', name: `tool:${call.name}` }, body);
+            // A tool the page reacts to at once is read after the reaction; one
+            // whose effect shows only after a reload costs the brief wait, not two seconds.
+            if (call.mutates)
+                this.armChange(BRIEF_CHANGE_WAIT_MS);
+            return value;
         };
         return call.mutates ? this.serialized(run) : run();
     }
+    /** What the settled step did, for the caller of `agent.act()`. */
+    result() {
+        const cache = this.stepCache?.cacheInfo;
+        return {
+            summary: this.explanation ?? '',
+            ...(cache === undefined ? {} : { cache }),
+            modelCalls: this.metrics.modelCalls,
+            actions: this.metrics.actionSteps,
+        };
+    }
     /** Attaches metrics, model provenance, and the verdict explanation to the step. */
     finish() {
         this.closed = true;
@@ -556,6 +626,10 @@ class ActDispatch {
     operation() {
         return boundedOperation(this.runtime.engine, this.runtime.config.actionTimeout, this.deadline);
     }
+    /** The operation context of one targeted action; see MAX_TARGETED_ACTION_MS. */
+    actionOperation() {
+        return boundedOperation(this.runtime.engine, Math.min(this.runtime.config.actionTimeout, MAX_TARGETED_ACTION_MS), this.deadline);
+    }
     /** Resolves the configured model once; executors that never read it never pay. */
     resolveModel() {
         if (!this.sdkModelResolved) {
@@ -652,6 +726,14 @@ class ActDispatch {
         // A tainted viewport never captures pixels: the engine would mask what it
         // knows about, and the secret may be anywhere on screen by now.
         const capturePixels = pixels && !this.runtime.taint.value;
+        // A settled look consumes the pending change: it waits for the screen to
+        // leave the pre-action shape once, and later looks read the screen as is.
+        const changedFrom = settle ? this.pendingChange : undefined;
+        const changeWaitMs = settle ? this.pendingChangeWaitMs : undefined;
+        if (settle) {
+            this.pendingChange = undefined;
+            this.pendingChangeWaitMs = undefined;
+        }
         const observation = await instrumentPhase(this.runtime, { api: this.spec.api, kind: 'observation', phase: 'agent.observe' }, () => settle
             ? settleObservation(() => this.captureObservation(capturePixels), observationShape, {
                 remainingMs: () => this.deadline.remaining(),
@@ -659,12 +741,30 @@ class ActDispatch {
                 // the attempt signal alone would let settling outlive the step
                 // by one poll interval.
                 signal: this.stepSignal,
-            })
+            }, { changedFrom, changeWaitMs, transitional: isTransitionalObservation })
             : this.captureObservation(capturePixels), (prepared) => ({ count: prepared.nodes.size, bytes: prepared.bytes }));
-        this.latest = observation;
+        this.publish(observation);
         this.metrics.observationBytes = Math.max(this.metrics.observationBytes, observation.bytes);
         return observation;
     }
+    /** Makes an observation the newest and remembers it among the recent ones. */
+    publish(observation) {
+        this.latest = observation;
+        this.recent.push(observation);
+        if (this.recent.length > MAX_RECENT_OBSERVATIONS)
+            this.recent.shift();
+    }
+    /**
+     * Arms the change wait: the next settled observation waits for the screen
+     * to leave the newest observation's shape, for the default two seconds or
+     * the given brief window.
+     */
+    armChange(waitMs) {
+        if (this.latest === undefined)
+            return;
+        this.pendingChange = observationShape(this.latest);
+        this.pendingChangeWaitMs = waitMs;
+    }
     /** One raw observation capture: retried at the engine, then redacted and bounded. */
     async captureObservation(pixels) {
         const raw = await retryingObserve({
@@ -676,11 +776,31 @@ class ActDispatch {
         });
         return prepareObservation(raw, {
             redact: this.runtime.redact,
-            maxBytes: this.runtime.config.agent.maxObservationBytes,
+            maxBytes: this.observationByteBudget(pixels),
             testIdAttribute: this.runtime.config.testIdAttribute,
         });
     }
-    /** Resolves an executor target against the newest observation. */
+    /**
+     * Bytes one act observation may contribute to a model turn, clamped like a
+     * judgment's. The loop's history grows past what any one observation costs,
+     * so the fixed part counted here is what every turn resends: the project
+     * context and the prior-step ledger.
+     */
+    observationByteBudget(pixels) {
+        const { config } = this.runtime;
+        return observationByteBudget({
+            maxObservationBytes: config.agent.maxObservationBytes,
+            maxModelTokensPerCall: config.limits.maxModelTokensPerCall,
+        }, { fixedBytes: this.metrics.contextBytes + this.metrics.ledgerBytes, pixels });
+    }
+    /**
+     * Resolves an executor target against the newest observation. An id the
+     * newest observation no longer carries, but a recent one did, is re-found
+     * in the newest one by its descriptor: a turn that batches actions keeps
+     * addressing the screen it saw while each action's own look re-observes,
+     * and an engine that mints ids per observation renumbers the tree between
+     * them. Exactly one match, or the id counts as gone.
+     */
     resolveTarget(target) {
         if (typeof target?.id !== 'string' || target.id === '') {
             throw new TestError('INVALID_ARGUMENT', 'action target must be { id: string }');
@@ -690,12 +810,29 @@ class ActDispatch {
         if (latest === undefined) {
             throw new AgentError('LOCATOR_NOT_FOUND', 'no observation has been captured yet; observe before acting');
         }
-        const node = latest.nodes.get(id);
+        const node = latest.nodes.get(id) ?? this.refound(id, latest);
         if (node === undefined) {
-            throw new AgentError('LOCATOR_NOT_FOUND', `node #${id} is not part of observation ${latest.revision}; re-observe and use a current id`);
+            throw new AgentError('LOCATOR_NOT_FOUND', `node #${id} is not on the current screen (observation ${latest.revision}); it was removed or never existed`);
         }
         return node;
     }
+    /** The newest node matching the descriptor of what `id` named in a recent observation, if exactly one. */
+    refound(id, latest) {
+        let earlier;
+        for (let index = this.recent.length - 1; index >= 0 && earlier === undefined; index -= 1) {
+            earlier = this.recent[index].nodes.get(id);
+        }
+        if (earlier === undefined)
+            return undefined;
+        const descriptor = describeTarget(earlier, this.redact, this.runtime.config.testIdAttribute);
+        if (descriptor === undefined)
+            return undefined;
+        const relocated = relocateDescriptor(descriptor, latest.nodes, {
+            redact: this.redact,
+            testIdAttribute: this.runtime.config.testIdAttribute,
+        });
+        return relocated.kind === 'found' ? latest.nodes.get(relocated.id) : undefined;
+    }
     /**
      * Runs one grammar action against the action budget, recorded as an engine
      * event. The body performs the engine call and returns the committed
@@ -718,6 +855,12 @@ class ActDispatch {
             this.checkpoint(cause);
             throw cause;
         }
+        // The effect may still be arriving: the next settled observation waits for
+        // the screen to leave the shape this action was resolved against. A secret
+        // fill leaves no visible trace and arms nothing; a scroll waits briefly for
+        // rows a windowed or lazy list renders.
+        if (name !== 'typeSecret')
+            this.armChange(name === 'scroll' ? BRIEF_CHANGE_WAIT_MS : undefined);
         if (this.stepCache === undefined)
             return;
         // A typed value the step derived at run time is this run's data, not the
@@ -729,51 +872,85 @@ class ActDispatch {
         }
         this.stepCache.record(action);
     }
-    /** One action against a resolved node; a stale ref asks for a re-observe. */
+    /**
+     * One action against a resolved node. A node the engine reports stale is
+     * re-found by its descriptor against a fresh capture and the action retried
+     * (`MAX_STALE_RELOCATIONS` times): a list that remounts its rows between
+     * the observation and the action keeps the control on screen under a dead
+     * handle, and the control, not the handle, is what the model asked for. A
+     * descriptor that matches nothing or several nodes fails the action instead.
+     */
     commitTargeted(name, target, perform) {
         return this.runAction(name, async () => {
-            const node = this.resolveTarget(target);
-            // The container the node sits in is captured with it: that is what
-            // tells this row's "Delete" from the next row's when the flow replays.
-            const latest = this.latest;
-            const within = latest === undefined ? undefined : containerKey(node.ref.id, latest.nodes, latest.parents, this.redact);
-            // When the description still matches several controls, the position among
-            // them is recorded too; a replay that finds the same number picks the same one.
-            const position = latest === undefined
-                ? undefined
-                : describePosition(node, within, latest.nodes, {
+            let node = this.resolveTarget(target);
+            // resolveTarget guarantees an observation; it is the one the node came from.
+            let observation = this.latest;
+            for (let relocations = 0;; relocations += 1) {
+                // The container the node sits in is captured with it: that is what
+                // tells this row's "Delete" from the next row's when the flow replays.
+                const within = containerKey(node.ref.id, observation.nodes, observation.parents, this.redact);
+                // When the description still matches several controls, the position among
+                // them is recorded too; a replay that finds the same number picks the same one.
+                const position = describePosition(node, within, observation.nodes, {
                     redact: this.redact,
                     testIdAttribute: this.runtime.config.testIdAttribute,
                 });
-            try {
-                const action = await perform(node);
-                return {
-                    ...action,
-                    ...(within === undefined ? {} : { within }),
-                    ...(position === undefined ? {} : { position }),
-                };
-            }
-            catch (cause) {
-                if (cause instanceof EngineError && cause.code === 'NODE_STALE') {
-                    throw new AgentError('LOCATOR_NOT_FOUND', 'the target node is stale; re-observe and use a current id', { cause });
+                try {
+                    const action = await perform(node);
+                    return {
+                        ...action,
+                        ...(within === undefined ? {} : { within }),
+                        ...(position === undefined ? {} : { position }),
+                    };
+                }
+                catch (cause) {
+                    if (asEngineError(cause)?.code !== 'NODE_STALE')
+                        throw cause;
+                    const relocated = relocations < MAX_STALE_RELOCATIONS ? await this.relocateStale(node) : undefined;
+                    if (relocated === undefined) {
+                        throw new AgentError('LOCATOR_NOT_FOUND', 'the target node left the screen before the action reached it', { cause });
+                    }
+                    node = relocated.node;
+                    observation = relocated.observation;
                 }
-                throw cause;
             }
         });
     }
+    /**
+     * Re-finds a node that went stale: one fresh capture, then the trace
+     * recorder's own descriptor matching (`cache/relocate.ts`) against it,
+     * exactly one match or nothing. The capture is taken directly rather than
+     * through the serialized observe: this runs inside a serialized action
+     * body, and a queued observation would wait on its own caller.
+     */
+    async relocateStale(stale) {
+        const options = { redact: this.redact, testIdAttribute: this.runtime.config.testIdAttribute };
+        const descriptor = describeTarget(stale, this.redact, this.runtime.config.testIdAttribute);
+        if (descriptor === undefined)
+            return undefined;
+        this.checkpoint();
+        const observation = await instrumentPhase(this.runtime, { api: this.spec.api, kind: 'observation', phase: 'agent.observe', name: 'relocate' }, () => this.captureObservation(false), (prepared) => ({ count: prepared.nodes.size, bytes: prepared.bytes }));
+        this.publish(observation);
+        this.metrics.observationBytes = Math.max(this.metrics.observationBytes, observation.bytes);
+        const relocated = relocateDescriptor(descriptor, observation.nodes, options);
+        if (relocated.kind !== 'found')
+            return undefined;
+        const node = observation.nodes.get(relocated.id);
+        return node === undefined ? undefined : { node, observation };
+    }
     async scroll(direction, target) {
         if (!['up', 'down', 'left', 'right'].includes(direction)) {
             throw new TestError('INVALID_ARGUMENT', `invalid scroll direction "${String(direction)}"`);
         }
         if (target === undefined) {
             await this.runAction('scroll', async () => {
-                await this.session.swipe(direction, undefined, this.operation());
+                await this.session.swipe(direction, SCROLL_MOMENTUM, this.actionOperation());
                 return { name: 'scroll', direction };
             });
             return;
         }
         await this.commitTargeted('scroll', target, async (node) => {
-            await this.session.perform(node.ref, { kind: 'swipe', direction }, this.operation());
+            await this.session.perform(node.ref, { kind: 'swipe', direction, momentum: SCROLL_MOMENTUM }, this.actionOperation());
             return { name: 'scroll', direction, node };
         });
     }
@@ -791,10 +968,10 @@ class ActDispatch {
         await this.commitTargeted('typeSecret', target, async (node) => {
             const plaintext = await authorizeSecretFill({
                 session: this.session,
-                operation: () => this.operation(),
+                operation: () => this.actionOperation(),
                 recordPolicy: (policy, decision, code) => this.recordPolicy(policy, decision, code),
             }, this.runtime, secret, node);
-            await this.session.perform(node.ref, { kind: 'fill', value: plaintext, sensitive: true }, this.operation());
+            await this.session.perform(node.ref, { kind: 'fill', value: plaintext, sensitive: true }, this.actionOperation());
             this.runtime.taint.value = true;
             // Recorded by stable name only; replay re-runs the full authorization.
             return { name: 'typeSecret', node, secret: name };