e2e 0.16.0 → 0.18.0

package/dist/agent/observation.d.ts

@@ -1,14 +1,15 @@
 /** Observation capture, redaction, and model serialization. */
 import type { Observation, SemanticNode, ViewportSize } from '../engine/surface.ts';
+import type { SecretLedger } from '../internal/redact.ts';
 import type { VisionDegradation } from '../run/steps.ts';
 import type { ExecutorNode, ExecutorObservation, ExecutorPixels } from './executor.ts';
 /** Why pixels the caller asked for are not part of this observation. */
 type PixelsWithheld = 'MASKING_UNPROVEN';
 export type AgentObservation = AgentObservationMetadata & ({
     readonly kind: 'semantic';
-    readonly nodes: ReadonlyMap<string, SemanticNode>;
+    readonly nodes: ReadonlyMap<string, RedactedNode>;
     readonly parents: ReadonlyMap<string, string>;
-    readonly tree: SemanticNode;
+    readonly tree: RedactedNode;
     readonly truncated: boolean;
     readonly pixels?: ExecutorPixels | undefined;
     readonly pixelsWithheld?: PixelsWithheld | undefined;
@@ -37,10 +38,11 @@ interface AgentObservationMetadata {
  *
  * Pixels whose masking the engine cannot prove (fewer masked regions than
  * secure nodes) are withheld before they reach a model or disk; the semantic
- * tree never carries secure values. Registered secret values are additionally
- * replaced by their stable secret name, and so is the leading part of one a
- * field the engine cut at its limit ends with. A field holding one keeps no
- * selection, as a secure field keeps none.
+ * tree never carries secure values. Every string of every node is redacted
+ * once, here (`redactNode`): registered secret values are replaced by their
+ * stable secret name, and so is the leading part of one a field the engine
+ * cut at its limit ends with. A field holding one keeps no selection, as a
+ * secure field keeps none.
  */
 export declare function prepareObservation(observation: Observation, options: {
     redact: (text: string) => string;
@@ -52,6 +54,34 @@ export declare function prepareObservation(observation: Observation, options: {
     /** The app base URL's origin: link targets on it render as paths, which navigation resolves against it. */
     appOrigin?: string | undefined;
 }): AgentObservation;
+/** What redacts a node: whole values, and the leading part of one a cut field ends with. */
+export type NodeRedaction = Pick<SecretLedger, 'redact' | 'redactCut'>;
+declare const REDACTED: unique symbol;
+/**
+ * A semantic node every string of which has passed the attempt's secret
+ * ledger (`redactNode`). Model-facing text and executor trees render only
+ * from this shape, so a node no redaction touched cannot reach them.
+ */
+export interface RedactedNode extends Omit<SemanticNode, 'children'> {
+    readonly [REDACTED]: true;
+    readonly children?: readonly RedactedNode[];
+}
+/**
+ * The node and its subtree with every secret taken out of every field
+ * (`NODE_FIELDS`), before any consumer reads it: the model's text, the
+ * executor's tree, cache descriptors and anchors, failure evidence.
+ */
+export declare function redactNode(node: SemanticNode, redaction: NodeRedaction): RedactedNode;
+/**
+ * An earlier capture's nodes redacted again through the ledger as it is now,
+ * each on its own fields, then linked to its redacted-again children, so the
+ * tree keeps its shape (which nodes are leaves) without a subtree redacted
+ * once per ancestor. A secret a provider resolved after the capture masks
+ * text the capture still shows, so the two captures read alike wherever the
+ * screen did not change. Redacting redacted text changes nothing else: a
+ * marker is never read again.
+ */
+export declare function redactNodesAgain(nodes: ReadonlyMap<string, RedactedNode>, redaction: NodeRedaction): ReadonlyMap<string, RedactedNode>;
 /** Phase metrics describe a node count only when the capture actually read nodes. */
 export declare function observationDetail(observation: AgentObservation): {
     count?: number;
@@ -82,21 +112,20 @@ export declare const INTERACTIVE_ROLES: ReadonlySet<string>;
  */
 export declare function interactiveNodeCount(observation: Pick<ExecutorObservation, 'text'>): number;
 /**
- * Projects the raw tree onto the executor-facing node shape: the same
- * redaction the text serialization applies, field by field, and no value or
- * selection at all for a secure node, and a link target bounded as a line
+ * Projects a redacted tree onto the executor-facing node shape, the fields
+ * the text serialization renders, with a link target bounded as a line
  * bounds it: a target on `appOrigin` keeps that origin and loses no more of
  * its path than the line does. Selectors stay behind — they are relocation
  * material for the trace cache, not something a brain reasons about.
  */
-export declare function projectTree(node: SemanticNode, redact: (text: string) => string, appOrigin?: string): ExecutorNode;
+export declare function projectTree(node: RedactedNode, appOrigin?: string): ExecutorNode;
 /**
  * Renders one node as `#id role "name" text="..." value="..." selection="..." [states]`. Role-less text
  * holders omit the role token entirely: on a large screen they are half the
  * lines, and the model needs their text, not a filler word. A link target on
  * `appOrigin`, the app base URL's, renders as its path.
  */
-export declare function formatNode(node: SemanticNode, depth: number, redact: (text: string) => string, appOrigin?: string): string;
+export declare function formatNode(node: RedactedNode, depth: number, appOrigin?: string): string;
 /**
  * What the screen looks like, independent of which observation looked at it.
  *

package/dist/agent/observation.js

@@ -15,10 +15,11 @@ const UNAVAILABLE_TREE_MARKER = '[semantic capture unavailable: no nodes were re
  *
  * Pixels whose masking the engine cannot prove (fewer masked regions than
  * secure nodes) are withheld before they reach a model or disk; the semantic
- * tree never carries secure values. Registered secret values are additionally
- * replaced by their stable secret name, and so is the leading part of one a
- * field the engine cut at its limit ends with. A field holding one keeps no
- * selection, as a secure field keeps none.
+ * tree never carries secure values. Every string of every node is redacted
+ * once, here (`redactNode`): registered secret values are replaced by their
+ * stable secret name, and so is the leading part of one a field the engine
+ * cut at its limit ends with. A field holding one keeps no selection, as a
+ * secure field keeps none.
  */
 export function prepareObservation(observation, options) {
     const location = observation.location === undefined ? undefined : options.redact(observation.location);
@@ -42,11 +43,10 @@ export function prepareObservation(observation, options) {
             pixels: pixels.cleared,
         };
     }
-    const tree = protectSecrets(observation.tree, options);
+    const tree = redactNode(observation.tree, options);
     const nodes = new Map();
     const parents = new Map();
     indexNodes(tree, nodes, parents);
-    const redact = options.redact;
     const lines = [];
     const encoder = new TextEncoder();
     // The marker is reserved up front so a truncated observation still fits the
@@ -63,7 +63,7 @@ export function prepareObservation(observation, options) {
     const emit = (node, depth) => {
         if (cutByBudget)
             return;
-        const line = formatNode(node, depth, redact, options.appOrigin);
+        const line = formatNode(node, depth, options.appOrigin);
         const size = encoder.encode(`${line}\n`).byteLength;
         if (lines.length > 0 && bytes + size > budget) {
             cutByBudget = true;
@@ -97,40 +97,94 @@ export function prepareObservation(observation, options) {
         ...(pixels.withheld === undefined ? {} : { pixelsWithheld: pixels.withheld }),
     };
 }
-/** The fields an engine may cut, each at its observed limit. */
-const CUT_FIELDS = [
-    ['name', OBSERVED_NAME_LIMIT],
-    ['text', OBSERVED_TEXT_LIMIT],
-    ['value', OBSERVED_TEXT_LIMIT],
-    ['selection', OBSERVED_TEXT_LIMIT],
-];
+/** Leaves a field the engine fills from a closed set (an enum, booleans, numbers) or mints itself as it is. */
+const keep = (value) => value;
 /**
- * The tree with what whole-value redaction misses taken out, before any
- * consumer reads it. Every field exactly as long as its observed limit, and
- * so possibly cut there, passes through `redactCut`: a secret the cut stopped
- * partway through leaves a leading part at the end that no whole value
- * matches. A shorter field is whole, and so is a longer one (a native input's
- * value, which no engine cuts); both are left to `redact`. A selection that
- * may show part of a secret is dropped, as a secure field's is. A subtree
- * with nothing changed is returned as it is.
+ * How each field of a node is redacted, one entry per field of
+ * `SemanticNode`: a field added to the contract does not compile until it
+ * says how its text is redacted, and a key an engine sends that the
+ * contract does not name is dropped. Every string passes through
+ * `redactText`. A secure node keeps no value or selection, and a selection
+ * that may show part of a secret is dropped, as a secure field's is. The ref
+ * is the engine's own handle, sent back to it to act, never page text.
  */
-function protectSecrets(node, redaction) {
-    const withhold = node.selection !== undefined && selectionMayHoldSecret(node, node.selection, redaction);
-    const changed = {};
-    for (const [field, limit] of CUT_FIELDS) {
-        const text = node[field];
-        if (text?.length !== limit || (withhold && field === 'selection'))
+const NODE_FIELDS = {
+    ref: keep,
+    role: (role, _node, redaction) => redactText(role, redaction),
+    name: (name, _node, redaction) => redactText(name, redaction, OBSERVED_NAME_LIMIT),
+    text: (text, _node, redaction) => redactText(text, redaction, OBSERVED_TEXT_LIMIT),
+    value: (value, node, redaction) => (node.states?.secure === true ? undefined : redactText(value, redaction, OBSERVED_TEXT_LIMIT)),
+    selection: (selection, node, redaction) => node.states?.secure === true || selectionMayHoldSecret(node, selection, redaction)
+        ? undefined
+        : redactText(selection, redaction, OBSERVED_TEXT_LIMIT),
+    testId: (testId, _node, redaction) => redactText(testId, redaction),
+    inputPurpose: keep,
+    states: keep,
+    level: keep,
+    attributes: (attributes, _node, redaction) => Object.fromEntries(Object.entries(attributes).map(([key, value]) => [redactText(key, redaction), redactText(value, redaction)])),
+    rect: keep,
+    selector: (selector, _node, redaction) => redactText(selector, redaction),
+    framePath: (framePath, _node, redaction) => framePath.map((selector) => redactText(selector, redaction)),
+};
+/**
+ * The node and its subtree with every secret taken out of every field
+ * (`NODE_FIELDS`), before any consumer reads it: the model's text, the
+ * executor's tree, cache descriptors and anchors, failure evidence.
+ */
+export function redactNode(node, redaction) {
+    const redacted = {};
+    for (const [field, value] of Object.entries(node)) {
+        if (field === 'children' || value === undefined || !Object.hasOwn(NODE_FIELDS, field))
             continue;
-        const redacted = redaction.redactCut(text);
-        if (redacted !== text)
-            changed[field] = redacted;
+        const redactValue = NODE_FIELDS[field];
+        const result = redactValue(value, node, redaction);
+        if (result !== undefined)
+            redacted[field] = result;
     }
-    const children = node.children?.map((child) => protectSecrets(child, redaction));
-    const sameChildren = (children ?? []).every((child, index) => child === node.children?.[index]);
-    if (!withhold && Object.keys(changed).length === 0 && sameChildren)
-        return node;
-    const { selection: _selection, ...withoutSelection } = node;
-    return { ...(withhold ? withoutSelection : node), ...changed, ...(children === undefined ? {} : { children }) };
+    if (node.children !== undefined)
+        redacted['children'] = node.children.map((child) => redactNode(child, redaction));
+    return redacted;
+}
+/**
+ * An earlier capture's nodes redacted again through the ledger as it is now,
+ * each on its own fields, then linked to its redacted-again children, so the
+ * tree keeps its shape (which nodes are leaves) without a subtree redacted
+ * once per ancestor. A secret a provider resolved after the capture masks
+ * text the capture still shows, so the two captures read alike wherever the
+ * screen did not change. Redacting redacted text changes nothing else: a
+ * marker is never read again.
+ */
+export function redactNodesAgain(nodes, redaction) {
+    const again = new Map();
+    for (const [id, { children: _children, ...fields }] of nodes)
+        again.set(id, redactNode(fields, redaction));
+    for (const [id, { children }] of nodes) {
+        const node = again.get(id);
+        if (node === undefined || children === undefined)
+            continue;
+        node.children = children.map((child) => again.get(child.ref.id)).filter((child) => child !== undefined);
+    }
+    return again;
+}
+/**
+ * One observed string with every secret taken out, in the form it is written
+ * and in the one-line form a line, a descriptor, or an anchor shows it
+ * (`collapseText`). A field exactly as long as `limit`, and so possibly cut
+ * there, passes through `redactCut`: a secret the cut stopped partway through
+ * leaves a leading part at the end that no whole value matches. A shorter
+ * field is whole, and so is a longer one (a native input's value, which no
+ * engine cuts); both pass through `redact`. A field whose collapsed form
+ * still holds a secret (the whitespace inside a value widened) is kept
+ * collapsed and redacted, so no later collapse brings the value back.
+ */
+function redactText(text, redaction, limit) {
+    const pass = text.length === limit ? redaction.redactCut : redaction.redact;
+    const redacted = pass(text);
+    const collapsed = collapseText(redacted);
+    if (collapsed === redacted)
+        return redacted;
+    const read = pass(collapsed);
+    return read === collapsed ? redacted : read;
 }
 /**
  * Whether a node's selection may show part of a secret, which no whole-value
@@ -142,7 +196,7 @@ function protectSecrets(node, redaction) {
 function selectionMayHoldSecret(node, selection, redaction) {
     const fields = [node.value, node.text].filter((text) => text !== undefined);
     const cut = (text) => text.length === OBSERVED_TEXT_LIMIT;
-    if (fields.some((text) => (cut(text) ? redaction.redactCut(text) : redaction.redact(text)) !== text))
+    if (fields.some((text) => redactText(text, redaction, OBSERVED_TEXT_LIMIT) !== text))
         return true;
     return fields.some(cut) && !fields.some((text) => text.includes(selection));
 }
@@ -234,33 +288,29 @@ export function interactiveNodeCount(observation) {
     return count;
 }
 /**
- * Projects the raw tree onto the executor-facing node shape: the same
- * redaction the text serialization applies, field by field, and no value or
- * selection at all for a secure node, and a link target bounded as a line
+ * Projects a redacted tree onto the executor-facing node shape, the fields
+ * the text serialization renders, with a link target bounded as a line
  * bounds it: a target on `appOrigin` keeps that origin and loses no more of
  * its path than the line does. Selectors stay behind — they are relocation
  * material for the trace cache, not something a brain reasons about.
  */
-export function projectTree(node, redact, appOrigin) {
-    const secure = node.states?.secure === true;
+export function projectTree(node, appOrigin) {
     const attributes = node.attributes === undefined
         ? undefined
-        : Object.fromEntries(Object.entries(node.attributes).map(([key, value]) => [key, key === 'href' ? treeHref(redact(value), appOrigin) : redact(value)]));
+        : Object.fromEntries(Object.entries(node.attributes).map(([key, value]) => [key, key === 'href' ? treeHref(value, appOrigin) : value]));
     return {
         id: node.ref.id,
         ...(node.role === undefined ? {} : { role: node.role }),
-        ...(node.name === undefined ? {} : { name: redact(node.name) }),
-        ...(node.text === undefined ? {} : { text: redact(node.text) }),
-        ...(node.value === undefined || secure ? {} : { value: redact(node.value) }),
-        ...(node.selection === undefined || secure ? {} : { selection: redact(node.selection) }),
+        ...(node.name === undefined ? {} : { name: node.name }),
+        ...(node.text === undefined ? {} : { text: node.text }),
+        ...(node.value === undefined ? {} : { value: node.value }),
+        ...(node.selection === undefined ? {} : { selection: node.selection }),
         ...(node.inputPurpose === undefined ? {} : { inputPurpose: node.inputPurpose }),
         ...(node.states === undefined ? {} : { states: node.states }),
         ...(attributes === undefined ? {} : { attributes }),
         ...(node.rect === undefined ? {} : { rect: node.rect }),
         ...(node.framePath === undefined ? {} : { framePath: node.framePath }),
-        ...(node.children === undefined
-            ? {}
-            : { children: node.children.map((child) => projectTree(child, redact, appOrigin)) }),
+        ...(node.children === undefined ? {} : { children: node.children.map((child) => projectTree(child, appOrigin)) }),
     };
 }
 /** Depth beyond this renders flat; deep chrome must not buy tokens with spaces. */
@@ -273,37 +323,37 @@ const MAX_HREF_LENGTH = 256;
  * lines, and the model needs their text, not a filler word. A link target on
  * `appOrigin`, the app base URL's, renders as its path.
  */
-export function formatNode(node, depth, redact, appOrigin) {
+export function formatNode(node, depth, appOrigin) {
     const parts = [`#${node.ref.id}`];
     if (node.role !== undefined && node.role !== '')
         parts.push(node.role);
     if (node.name !== undefined && node.name !== '')
-        parts.push(JSON.stringify(redact(node.name)));
+        parts.push(JSON.stringify(node.name));
     const text = node.text === undefined ? '' : collapseText(node.text);
     if (text !== '' && text !== node.name)
-        parts.push(`text=${JSON.stringify(redact(text))}`);
+        parts.push(`text=${JSON.stringify(text)}`);
     // Disambiguators the model needs when role and name repeat. The engine has
     // already reduced href to origin and path.
     if (node.testId !== undefined && node.testId !== '')
         parts.push(`testid=${JSON.stringify(node.testId)}`);
     const href = node.attributes?.['href'];
     if (href !== undefined && href !== '')
-        parts.push(`href=${JSON.stringify(renderHref(redact(href), appOrigin))}`);
+        parts.push(`href=${JSON.stringify(renderHref(href, appOrigin))}`);
     const placeholder = node.attributes?.['placeholder'];
     if (placeholder !== undefined && placeholder !== '' && (node.name ?? '') === '') {
-        parts.push(`placeholder=${JSON.stringify(redact(placeholder))}`);
+        parts.push(`placeholder=${JSON.stringify(placeholder)}`);
     }
     if (node.states?.secure === true) {
         parts.push('value=<secure>');
     }
     else if (node.value !== undefined && node.value !== '') {
-        parts.push(`value=${JSON.stringify(redact(node.value))}`);
+        parts.push(`value=${JSON.stringify(node.value)}`);
     }
     // What a Shift+Arrow press selected: without it the model extends a
     // selection blind and cannot tell one word from its neighbour. Rendered
     // verbatim (escaped), since a selected space or newline is a selection too.
-    if (node.selection !== undefined && node.selection !== '' && node.states?.secure !== true) {
-        parts.push(`selection=${JSON.stringify(redact(node.selection))}`);
+    if (node.selection !== undefined && node.selection !== '') {
+        parts.push(`selection=${JSON.stringify(node.selection)}`);
     }
     if (node.inputPurpose !== undefined && node.inputPurpose !== 'none') {
         parts.push(`purpose=${node.inputPurpose}`);

package/dist/agent/phases.d.ts

@@ -67,11 +67,17 @@ export declare function checkStepClock(options: {
  * re-read rather than surfaced as a failed call. `guard` is the caller's
  * clock check, so a capture that outlives the deadline reports the step's own
  * timeout rather than whichever transport error the truncated budget produced.
+ * `fallback` asks the engine for fallback pixels, which a secret fill
+ * (`tainted`, read per capture) withholds; a capture that then times out
+ * before the step clock does is the policy denial it is, not an engine
+ * timeout, since only those pixels could have answered.
  */
 export declare function retryingObserve(options: {
-    readonly observe: (operation: OperationContext) => Promise<Observation>;
+    readonly observe: (operation: OperationContext, pixelFallback: boolean) => Promise<Observation>;
     readonly operation: () => OperationContext;
     readonly guard: (cause?: unknown) => void;
     readonly signal: AbortSignal;
     readonly api: string;
+    readonly fallback: boolean;
+    readonly tainted: () => boolean;
 }): Promise<Observation>;

package/dist/agent/phases.js

@@ -4,7 +4,7 @@
  * these, so event recording, `--debug` buckets, tracing, deadline semantics,
  * and observation race-hardening cannot drift between the two paths.
  */
-import { asEngineError, E2EError } from '../internal/errors.js';
+import { asEngineError, isE2EError } from '../internal/errors.js';
 import { timestamp } from '../internal/ids.js';
 import { POLL_INTERVAL_MS, sleep } from '../internal/time.js';
 import { AgentError, toAgentError } from './error.js';
@@ -112,14 +112,23 @@ function timedOutAtDeadline(cause, deadline) {
  * re-read rather than surfaced as a failed call. `guard` is the caller's
  * clock check, so a capture that outlives the deadline reports the step's own
  * timeout rather than whichever transport error the truncated budget produced.
+ * `fallback` asks the engine for fallback pixels, which a secret fill
+ * (`tainted`, read per capture) withholds; a capture that then times out
+ * before the step clock does is the policy denial it is, not an engine
+ * timeout, since only those pixels could have answered.
  */
 export async function retryingObserve(options) {
     for (;;) {
+        const withheld = options.fallback && options.tainted();
         try {
-            return await options.observe(options.operation());
+            return await options.observe(options.operation(), options.fallback && !withheld);
         }
         catch (cause) {
             options.guard(cause);
+            if (withheld && asEngineError(cause)?.code === 'OPERATION_TIMEOUT') {
+                throw new AgentError('POLICY_DENIED', `${options.api} could not read the semantic tree, and its screenshot fallback is denied: ` +
+                    'a secret was filled in this attempt, so no pixels leave the runner until it ends (PIXEL_TAINTED)', { cause });
+            }
             // Structural, not instanceof: an engine a config file imported lives in
             // another module registry, and its retryable race would otherwise fail
             // the observation the moment a page navigates under it.
@@ -133,7 +142,7 @@ export async function retryingObserve(options) {
 }
 /** Event code for a failed phase: the runner or engine code, or the error's name. */
 function phaseErrorCode(cause) {
-    if (cause instanceof E2EError)
+    if (isE2EError(cause))
         return cause.code;
     const engineError = asEngineError(cause);
     if (engineError !== undefined)

package/dist/agent/point-tap.d.ts

@@ -7,9 +7,9 @@
  * screenshot are scaled into the observation's CSS pixels first.
  */
 import type { PointActionName } from '../cache/trace.ts';
-import type { SemanticNode, ViewportPoint, ViewportSize } from '../engine/surface.ts';
+import type { ViewportPoint, ViewportSize } from '../engine/surface.ts';
 import type { ExecutorPixels } from './executor.ts';
-import { type AgentObservation } from './observation.ts';
+import { type AgentObservation, type RedactedNode } from './observation.ts';
 /**
  * Scales a point read off a screenshot into the observation's CSS pixels and
  * clamps it to the viewport. `pixels.scale` is image pixels per CSS pixel
@@ -23,9 +23,9 @@ export declare function imagePointToViewport(point: {
 }, pixels: Pick<ExecutorPixels, 'width' | 'height' | 'scale'>, viewport: ViewportSize): ViewportPoint;
 export interface HitTest {
     /** The innermost enabled control whose box contains the point, if any. */
-    readonly control: SemanticNode | undefined;
+    readonly control: RedactedNode | undefined;
     /** The innermost listed node of any role whose box contains the point, if any. */
-    readonly under: SemanticNode | undefined;
+    readonly under: RedactedNode | undefined;
 }
 /**
  * Finds what the newest observation lists at a viewport point. Only an
@@ -54,12 +54,12 @@ export declare const POINT_VERBS: Readonly<Record<PointActionName, {
 export declare function describePointAction(input: PointProse & {
     readonly verb: PointActionName;
     readonly point: ViewportPoint;
-    readonly control: SemanticNode | undefined;
-    readonly under: SemanticNode | undefined;
+    readonly control: RedactedNode | undefined;
+    readonly under: RedactedNode | undefined;
 }): string;
 /** What one hit test found, for the model that named the point. */
 export declare function describePointHit(input: PointProse & {
     readonly point: ViewportPoint;
-    readonly control: SemanticNode | undefined;
-    readonly under: SemanticNode | undefined;
+    readonly control: RedactedNode | undefined;
+    readonly under: RedactedNode | undefined;
 }): string;

package/dist/agent/point-tap.js

@@ -41,7 +41,7 @@ export function hitTest(observation, point) {
  * The innermost listed node whose box contains the point, among those
  * `accept` admits: deepest in the tree, then the smallest box. Hidden nodes
  * and nodes without a box are skipped. Every box is in the top-level
- * viewport's CSS pixels, nested documents included (`SemanticNode.rect`), so
+ * viewport's CSS pixels, nested documents included (`RedactedNode.rect`), so
  * a node inside an iframe is found like any other.
  */
 function innermostAt(observation, point, accept = () => true) {

package/dist/agent/prompts.js

@@ -95,6 +95,9 @@ export const JUDGMENT_REQUEST = [
     'Decide whether the instruction is true for the observation right now.',
     'Answer "holds" only when the observation shows it is true, and "fails" only when the observation shows it is false.',
     'Answer "inconclusive" when the observation does not contain enough evidence to decide either way: the relevant part is not on screen, is still loading, or cannot be read. Never guess.',
+    'When the same value or state is shown in more than one place, such as an order total in a summary and again as the amount on a pay button, the instruction holds only when every place agrees with it; one place that contradicts it is a "fails", even if another agrees.',
+    'This applies only when the instruction does not say where to look: an instruction that names the place, such as "the order summary total", is judged on that place alone.',
+    'It is about one value shown twice, not about different items: a claim about some item, such as "a todo is marked done", holds when one item matches.',
     'Quotation marks in the instruction delimit the words to look for; the marks themselves, their style (straight or curly), and the punctuation around them are not part of those words, so text that reads the same holds.',
     'Write the explanation first and let the verdict follow from it: the two must agree.',
     'Respond with { "protocolVersion": "agent-judgment-2", "explanation": <short reason grounded in the observation>, "verdict": "holds" | "fails" | "inconclusive" }.',

package/dist/agent/replay.d.ts

@@ -11,15 +11,20 @@
  * timeout, cancellation) rethrow untouched; they are the step's truth, not a
  * divergence.
  */
-import { type ActionTrace, type DerivedReason, type TraceTargetDescriptor, type TraceViewport } from '../cache/trace.ts';
-import type { SemanticNode } from '../engine/surface.ts';
+import { type ActionTrace, type DerivedReason, type TraceViewport } from '../cache/trace.ts';
+import type { RedactedNode } from './observation.ts';
 import { type ExecutorActions, type ReplayHandOffReason } from './executor.ts';
 import { type SettleMode } from './settle-policy.ts';
 /** The nodes of one observation, keyed by their per-observation ids. */
-export type ObservedNodes = ReadonlyMap<string, SemanticNode>;
+export type ObservedNodes = ReadonlyMap<string, RedactedNode>;
 /** One capture's location and viewport, with nodes only when semantic evidence is available. */
 export type ObservedScreen = {
     readonly viewport: TraceViewport;
+    /**
+     * Where the capture was, as the cache compares it (`appLocation`): on the
+     * app's own origin its path, query, and fragment; elsewhere the whole
+     * location; a device's screen title as it is.
+     */
     readonly path?: string;
 } & ({
     readonly kind: 'semantic';
@@ -45,7 +50,6 @@ export interface ReplayHost {
     readonly actions: ExecutorActions;
     readonly signal: AbortSignal;
     remainingMs(): number;
-    readonly redact: (text: string) => string;
 }
 export interface ReplayOutcome {
     /** True when every recorded action executed; the step self-finalizes. */
@@ -67,20 +71,27 @@ export interface ReplayOptions {
      * instead of capturing again: nothing has happened since it was taken.
      */
     readonly initial?: SemanticScreen;
+    /**
+     * Asked before a free action (a navigate, typed text, a key) that follows
+     * another action; true takes the look a targeted action would have taken.
+     * A free action reads no screen, so without it the screen the previous
+     * action left goes unseen.
+     */
+    readonly looksBeforeFree?: () => boolean;
 }
 /** Replays one trace until it completes or diverges. */
 export declare function replayTrace(host: ReplayHost, trace: ActionTrace, options?: ReplayOptions): Promise<ReplayOutcome>;
 /**
- * Verifies a trace's recorded end anchors against the live screen: every
- * anchor must be present again (`anchors.ts`, every recorded field equal) or
- * the replay must not pass on its own. Waits on the same settling backoff
+ * Waits for a trace's recorded end state on the live screen: `holds` (the
+ * recorded delta, `cache/anchors.ts`) must be true of one look, or the
+ * replay must not pass on its own. Waits on the same settling backoff
  * relocation uses, because the recording run's final look came seconds of
  * model latency after its last action and a replay's comes right away: a
  * save still in flight is a wait, not a divergence. A surface that cannot be
  * observed at all is a mismatch too — the executor gets the step and judges
  * the live state; only runtime hard stops propagate.
  */
-export declare function verifyAnchors(host: ReplayHost, anchors: readonly TraceTargetDescriptor[], options?: {
+export declare function verifyEndState(host: ReplayHost, holds: (screen: SemanticScreen) => boolean, options?: {
     readonly waitMs?: number;
     readonly initial?: SemanticScreen;
 }): Promise<boolean>;