@vostride/agent-qa-runner 0.0.1 → 0.2.1

package/dist/index.d.cts

@@ -0,0 +1,3903 @@
+import { StepEvidence, RecordingEntry, Action as Action$1, RecordingAnnotationWitness, Platform, ActionsFor as ActionsFor$1, LiveStreamKind, LiveFrame, ScreenState, RecordingContentType, ScopeKey, BriefBlock, ServedRetrievalTraceV1, SearchOptions, IndexEntry, RecordId, ReadOptions, RecordBody, Anchor, CautionBlock, ProcedureBindingAvailability, ProcedureMatch, CanaryOutcome, ElementState, ElementLabels, Ref, ElementInfo, ScreenStateMetadata, CacheKey, ClipboardEvidence, SubmitOutcome, SubmitReason, FillVerdict, InputPath, DownloadEvidence, IdempotentNoopMeta, AssertValueOp, ConditionFileCheck, OperationEvidence, GroundingAttempt, WorkingMemoryEntry, ConditionVerdict, ConditionNeed, CitationSource, InterpolatedVariable, ToolExchangeEvidence, ModelCallRecord, RunEventEnvelope, CompletedRunHandoff, HookStartedPayload, HookFinishedPayload, TestRetryScheduledPayload, DeclaredModelProfile, ModelIdentity, RunId, PostProcessingDisposition, RunStatus, RunArtifactStageInput, RunArtifactFinalizeInput, ExecutionContext, QuarantineAppliedEntry, PlannerLimitsRecord, ServingRecordMetadata, ServingAdmissionDecision, ServedAdmissionSurface, ServedAdmissionEvent, ArtifactRef, EvidenceDocument, RecordingRef, StepFinalizedPayload, ModelUsageObservations, SubActionEvidence, SubActionRecordedPayload, RecordedRetrievalRung, ProcedureBodyPayload, ReadTrace, Surface, SamplingParams, BriefLine, ServedBrief, ServedPromptTurn, ActionResult as ActionResult$1, CautionLine, PlanningFailureEvidence, ReportedValueEvidence, TerminationEvidence, LimitStopEvidence, ConditionVerdictsEvidence, OperationCaptureAvailability, StepLimitUsage, AiJudgmentEvidence, AssertValueEvidence, VerdictSource, StepPlanSource, CacheMissReason, Decision, VerifierVerdict, Viewport, ActionAnnotation, MaskFn, RedactedEnvVar, CacheableStepInput, NonCacheableStepInput, RunEventType, RunEventPayload, LiveFrameEndReason, LiveFrameSubscription, LiveStreamDeclaration, RunSession, PerTestOutcome, MemberTestOutcome, Verdict, RiskActionDescriptor } from '@vostride/agent-qa-schema';
+export { IdempotentNoopMeta, Ref, asRef, readIdempotentNoopMeta } from '@vostride/agent-qa-schema';
+import { LanguageModel, ModelMessage, LanguageModelUsage, ToolSet, SystemModelMessage, Tool } from 'ai';
+import { z } from 'zod';
+
+type StepStatus = 'passed' | 'failed' | 'healed' | 'skipped' | 'cancelled';
+type TestStatus = 'passed' | 'failed' | 'skipped' | 'cancelled';
+interface StepAnnotation {
+    clickPoint?: {
+        x: number;
+        y: number;
+    };
+    boundingBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    failureHighlight?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    type: 'click' | 'fill' | 'tap' | 'hover' | 'scroll' | 'swipe' | 'pinch' | 'navigate' | 'other';
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    startPoint?: {
+        x: number;
+        y: number;
+    };
+    endPoint?: {
+        x: number;
+        y: number;
+    };
+    direction?: 'up' | 'down' | 'left' | 'right';
+    pinchScale?: 'in' | 'out';
+}
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+interface SubActionTrace {
+    index: number;
+    observation: string;
+    reasoning: string;
+    plannedAction: Action;
+    result: 'success' | 'failure' | 'no-input';
+    error?: string;
+    noInputSent?: {
+        currentState: string;
+    };
+    screenStateBefore: string;
+    screenStateAfter?: string;
+    screenContextBefore?: string;
+    screenContextAfter?: string;
+    confidence?: number;
+    verifierReasoning?: string;
+    cached: boolean;
+    tokenUsage?: TokenUsage;
+    phaseDurations?: {
+        observe?: number;
+        plan?: number;
+        execute?: number;
+        verify?: number;
+    };
+    screenshotBefore?: Buffer;
+    screenshotAfter?: Buffer;
+    annotation?: StepAnnotation;
+    data?: unknown;
+}
+interface StepTrace {
+    observation: string;
+    reasoning: string;
+    plannedAction: Action;
+    result: 'success' | 'failure';
+    error?: string;
+    screenStateBefore: string;
+    screenStateAfter?: string;
+    screenContextBefore?: string;
+    screenContextAfter?: string;
+    confidence?: number;
+    verifierReasoning?: string;
+    tokenUsage?: TokenUsage;
+    phaseDurations?: {
+        observe?: number;
+        plan?: number;
+        execute?: number;
+        verify?: number;
+    };
+    subActions?: SubActionTrace[];
+}
+interface StepPhaseEvent {
+    phase: 'observe' | 'plan' | 'execute' | 'verify';
+    subActionIndex?: number;
+    phaseOrdinal?: number;
+    text?: string;
+    confidence?: number;
+    action?: unknown;
+    success?: boolean;
+    duration?: number;
+}
+interface AccessibilityViolation {
+    ruleId: string;
+    impact: 'minor' | 'moderate' | 'serious' | 'critical';
+    description: string;
+    help: string;
+    helpUrl: string;
+    nodes: Array<{
+        html: string;
+        target: string[];
+    }>;
+}
+interface ConsoleLogEntry {
+    level: string;
+    text: string;
+    location?: {
+        url: string;
+        lineNumber: number;
+        columnNumber: number;
+    };
+    timestamp: number;
+}
+interface NetworkLogEntry {
+    url: string;
+    method: string;
+    status: number;
+    requestHeaders: Record<string, string>;
+    responseHeaders: Record<string, string>;
+    body?: string;
+    requestBody?: string;
+    startTime: number;
+    endTime: number;
+    timing?: Record<string, number>;
+}
+interface StepResult {
+    id?: string;
+    name: string;
+    status: StepStatus;
+    duration: number;
+    action?: Action;
+    observation?: string;
+    error?: string;
+    screenshot?: Buffer;
+    screenshotBefore?: Buffer;
+    trace?: StepTrace;
+    /**
+     * The §A8 evidence accumulated by the runner loop, produced by construction (D-14).
+     * ADDITIVE (Phase 353): the legacy `trace` is projected FROM this, never the reverse
+     * (Open Q5). Core's transitional orchestration persists it via the run-artifact path
+     * (D-16) until Phase 361 lifts the accumulator into RunSession/CompletedRunHandoff.
+     */
+    evidence?: StepEvidence;
+    retryCount?: number;
+    capturedVariables?: Record<string, string>;
+    annotation?: StepAnnotation;
+    accessibilityViolations?: AccessibilityViolation[];
+    consoleLogs?: ConsoleLogEntry[];
+    networkLogs?: NetworkLogEntry[];
+    variableSnapshot?: Record<string, {
+        value: string;
+        source: string;
+    }>;
+    originalStepName?: string;
+}
+interface TestResult {
+    runId?: string;
+    name: string;
+    filePath: string;
+    status: TestStatus;
+    steps: StepResult[];
+    duration: number;
+    metadata?: Record<string, unknown>;
+    retryCount?: number;
+    recording?: RecordingEntry;
+    failureSummary?: string;
+    /** One detached actual failure, retained only when a subsequent attempt runs. */
+    firstFailedAttempt?: {
+        /** Zero-based member attempt index, independently of the final retryCount. */
+        attempt: number;
+        result: Omit<TestResult, 'firstFailedAttempt'>;
+    };
+}
+
+interface ObserveOptions {
+    extractDom?: boolean;
+}
+type Action = Action$1;
+type ActionsFor<P extends Platform = Platform> = ActionsFor$1<P>;
+/**
+ * An adapter's LIVE STREAM capability (403 D-05). The adapter owns the producer (a CDP screencast,
+ * an MJPEG broadcaster, a WebRTC track, or a snapshot producer over a capture that is safe to run
+ * beside a step); the runner owns nothing but this object, so no `Page` and no session handle ever
+ * leaves the adapter. Lifecycle is lazy and refcounted by the run's {@link LiveStreamHub}: `start`
+ * on the first viewer, `ack` per consumed frame (the producer's flow control), `stop` on the
+ * last — idempotent, so a double stop is a no-op rather than a throw.
+ *
+ * The labelled 1s snapshot producer (`createSnapshotLiveStream`) sits behind this same contract
+ * (428 D-11): the composition registers it as the whole preview when an adapter has no continuous
+ * stream, and as the fallback the hub starts when a continuous stream fails to start (D-12).
+ */
+interface LiveStreamCapability {
+    readonly kind: LiveStreamKind;
+    start(onFrame: (frame: LiveFrame) => void): Promise<void>;
+    ack(frameId: number): Promise<void>;
+    stop(): Promise<void>;
+}
+interface RecordingStart {
+    zeroMs?: number;
+}
+interface RecordingStop {
+    stagingPath: string;
+    contentType: RecordingContentType;
+}
+interface RecordingCapability {
+    start(): Promise<RecordingStart>;
+    stop(): Promise<RecordingStop | undefined>;
+    /** Bracket one actual execution; completion withholds unsupported or changed scenes. */
+    beginAnnotation?(): (() => RecordingAnnotationWitness | undefined) | undefined;
+}
+interface OperationCaptureSupport {
+    download: boolean;
+    clipboard: boolean;
+    /** Why a capture is unsupported, e.g. the browser name. */
+    reason?: string;
+}
+/**
+ * 2026-10-08 (436-15, D-19): what the loop hands one dispatch. `remainingStepMs` is set only when
+ * a step deadline is armed; adapters that run no post-action wait ignore both.
+ */
+interface ExecuteOptions {
+    remainingStepMs?: number;
+    abortSignal?: AbortSignal;
+}
+interface PlatformAdapter<P extends Platform = Platform> {
+    readonly platform: P;
+    setup(config: PlatformConfig): Promise<void>;
+    cleanup(): Promise<void>;
+    observe(options?: ObserveOptions): Promise<ScreenState>;
+    execute(action: ActionsFor<P>, options?: ExecuteOptions): Promise<ActionResult>;
+    screenshot?(): Promise<Buffer | undefined>;
+    /**
+     * 403 D-05: the optional live-stream producer for this adapter's current target. ABSENT means
+     * "no continuous stream" (non-Chromium, remote farm), not "no preview": the composition's
+     * `liveStreamFor` wraps `screenshot()` in the labelled 1s snapshot producer instead, and uses
+     * that producer as the fallback when a continuous stream fails to start (428 D-11/D-12). Only an
+     * adapter with neither reads `{ kind: 'none' }`. An adapter whose `screenshot()` mutates shared
+     * state (the mobile adapters switch the Appium context) must expose its own snapshot
+     * `liveStream` over a side-effect-free capture instead, so `screenshot()` is never wrapped.
+     */
+    readonly liveStream?: LiveStreamCapability;
+    readonly recording?: RecordingCapability;
+    /**
+     * 436 D-23: which operation-specific captures this adapter runs. ABSENT means none; the loop
+     * then records both as unavailable, with `reason` or else 'platform'.
+     */
+    readonly operationCaptureSupport?: OperationCaptureSupport;
+    drainConsoleLogs?(level?: string): ConsoleLogEntry[];
+    drainNetworkLogs?(urlPattern?: string): NetworkLogEntry[];
+    /** 439 D-14: the undrained network log, read without consuming it; the step-end drain still sees it. */
+    peekNetworkLogs?(urlPattern?: string): NetworkLogEntry[];
+    /**
+     * 439 D-04: the bytes of a completed download with this sha256, held in memory and bounded by
+     * the adapter; undefined when the adapter holds none (over its cap, evicted, or disposed).
+     */
+    readDownloadBytes?(sha256: string): Uint8Array | undefined;
+}
+declare function assertNever(value: never): never;
+interface ActionResult {
+    recordingAnnotation?: RecordingAnnotationWitness;
+    success: boolean;
+    error?: string;
+    screenshot?: Buffer;
+    metadata?: Record<string, unknown>;
+    coordinates?: {
+        x: number;
+        y: number;
+    };
+    boundingBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    startCoordinates?: {
+        x: number;
+        y: number;
+    };
+    endCoordinates?: {
+        x: number;
+        y: number;
+    };
+    data?: unknown;
+}
+interface RuntimeAuthStateConfig {
+    version: number;
+    kind: 'web';
+    targetName: string;
+    stateName: string;
+    capturedAt: string;
+    storageStatePath: string;
+}
+interface PlatformConfig {
+    platform: 'web' | 'android' | 'ios';
+    browser?: BrowserConfig;
+    device?: DeviceConfig;
+    bundleId?: string;
+    appPackage?: string;
+    appActivity?: string;
+    deepLinkAppId?: string;
+    appState?: 'preserve' | 'reset';
+    appPath?: string;
+    browserstackApp?: string;
+    appiumUrl?: string;
+    timeouts?: TimeoutConfig;
+    recording?: {
+        enabled: boolean;
+        videoDir: string;
+        videoSize?: {
+            width: number;
+            height: number;
+        };
+    };
+    verbose?: boolean;
+    farmSession?: {
+        hostname: string;
+        port: number;
+        path: string;
+        capabilities: Record<string, unknown>;
+    };
+    logCapture?: {
+        console?: boolean;
+        network?: boolean;
+    };
+    authState?: RuntimeAuthStateConfig;
+}
+interface BrowserConfig {
+    name: 'chromium' | 'firefox' | 'webkit';
+    headless?: boolean;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+interface DeviceConfig {
+    name: string;
+    platform: 'android' | 'ios';
+    transport: 'local' | 'browserstack';
+    match: Record<string, unknown>;
+}
+interface TimeoutConfig {
+    step?: number;
+    test?: number;
+    navigation?: number;
+}
+
+/**
+ * The Channel-1 brief and the serve-time trace that explains it, as ONE value (KREV-02 · D-16).
+ *
+ * The pairing is the guarantee, not a convenience. A reader implementation cannot satisfy this
+ * port while producing a brief and no trace, and a consumer cannot receive a brief without also
+ * being handed how it was chosen — which is what makes 387-06's why-verb able to answer about the
+ * moment of serving rather than about a re-query of today's index.
+ */
+interface ServedRunBrief {
+    brief: BriefBlock;
+    trace: ServedRetrievalTraceV1;
+}
+/** The Channel-3 caution block with its own serve-time trace, on the same one-value contract. */
+interface ServedCautions {
+    block: CautionBlock;
+    trace: ServedRetrievalTraceV1;
+}
+interface KnowledgeHintReader {
+    getRunBrief(scope: ScopeKey, budget: number): ServedRunBrief;
+    search(query: string, options: SearchOptions): IndexEntry[];
+    read(id: RecordId, options?: ReadOptions): RecordBody | undefined;
+    getCautions(anchors: Anchor[], budget: number): ServedCautions;
+    /**
+     * D-08 port evolution: source-tagged binding NAMES cross here (variables, memory, secrets) so
+     * matcher fillability mirrors loop binding; no value ever crosses the reader port in any form.
+     * Value binding stays loop-side at replay time. Absent availability is treated as empty, so a
+     * referenced-parameter procedure downranks to hint (fail-conservative).
+     */
+    getProcedure(intent: string, screenState: ScreenState, availability?: ProcedureBindingAvailability): ProcedureMatch | undefined;
+    emitCanaryOutcome(payload: CanaryOutcome): void;
+}
+
+/**
+ * Adapter -> builder input for a single observed node.
+ *
+ * Structural links are carried as INDICES because refs do not exist yet — the
+ * builder mints them in document order (RESEARCH Pitfall #7).
+ */
+interface InterimNode {
+    /** Schema role vocabulary — adapters map native roles BEFORE the builder. */
+    role: string;
+    /** Raw accessible name; the builder normalizes it (ElementInfo.name = name ?? ''). */
+    name?: string;
+    value?: string;
+    /** Index of the nearest INCLUDED ancestor in the same nodes array. */
+    parentIndex?: number;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Optional; the builder derives the geometric center from bounds when absent. */
+    center?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * ONLY real platform signals (D-08 — never fabricated). The builder derives the
+     * required booleans from documented defaults when a signal is absent:
+     *   enabled  = state.enabled  ?? true  (absence of a disabled signal means enabled)
+     *   focused  = state.focused  ?? false
+     *   visible  = state.visible  ?? true  (present in the a11y tree means exposed;
+     *                                       adapters set false explicitly for offscreen)
+     * Optional bits (selected/checked/editable/clickable) pass through only when the
+     * platform supplied them — typed-absent otherwise.
+     */
+    state?: Partial<ElementState>;
+    labels?: ElementLabels;
+    /** Raw platform bag, passed through to ElementInfo.attributes (default {}). */
+    attributes?: Record<string, string>;
+    /** Static text folded in from children that are not nodes; copied to ElementInfo.text. */
+    text?: string;
+    /** Adapter-private hint (e.g. android class / XCUI type); the builder ignores it. */
+    nativeType?: string;
+    /** D-10; the builder maps containerIndex -> the minted container Ref. */
+    scrollContext?: {
+        containerIndex?: number;
+        offsetX: number;
+        offsetY: number;
+    };
+}
+interface BuildScreenStateInput {
+    platform: Platform;
+    /** Document order — this is the ref-minting order. */
+    nodes: InterimNode[];
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /**
+     * EXACT on web; BEST-EFFORT on mobile (D-10) — mobile callers pass a best-effort
+     * scroll derived from scrollable-node bounds. The field is precise only on web.
+     */
+    scroll: {
+        offsetX: number;
+        offsetY: number;
+        contentWidth: number;
+        contentHeight: number;
+    };
+    coordSpace: 'viewport' | 'content' | 'screen';
+    /** Caller-supplied — keeps the builder pure and deterministic. */
+    timestamp: number;
+    url?: string;
+    /** Web-only (D-04); lands in metadata.domContext. */
+    domContext?: string;
+}
+/**
+ * Execute-time resolution stays adapter-private: `index` is the live node's place in the
+ * input nodes array. No same-screen position is minted for anything to pick by (438 D-13).
+ */
+interface RefBinding {
+    index: number;
+}
+interface BuildScreenStateResult {
+    /** Schema type — never redefined. */
+    state: ScreenState;
+    /** Execute-time ref -> live-node resolution; stays adapter-private. */
+    binding: Record<Ref, RefBinding>;
+}
+/**
+ * The capture stamp the loop applies after compression (D-11). `full` carries the
+ * real image dimensions; `textOnly` attaches no image.
+ */
+type CaptureStamp = {
+    mode: 'full';
+    imageWidth: number;
+    imageHeight: number;
+} | {
+    mode: 'textOnly';
+};
+/**
+ * Assemble a schema v2 ScreenState plus an adapter-private ref->node binding from a
+ * platform-neutral interim node list. Pure and deterministic: identical input always
+ * yields byte-identical output.
+ */
+declare function buildScreenState(input: BuildScreenStateInput): BuildScreenStateResult;
+/**
+ * Deterministic LLM-facing tree text, derived from the structured elements (D-02) —
+ * one grammar for all platforms. Exported so Phase 357's slim/rich dual-projection is
+ * a renderer-only change with zero adapter edits.
+ *
+ * Grammar (pinned; RESEARCH Pitfall #10):
+ *   [Viewport: {viewportWidth}x{viewportHeight}] [{elements.length} elements]
+ *   {2 spaces × depth}- {role}{ "name"?} [ref={ref}]{ @(x,y wxh)?}{ [disabled]?}{ [offscreen]?}{ [checked]?}{ [selected]?}{ [editable]?}{ text: <row text as a JSON string>?}
+ * depth = length of the parentRef chain (root elements depth 0).
+ * A rendered name collapses each line break, with the whitespace around it, to one space, so
+ * every element stays on one line; element.name and value keep the raw text.
+ * ` text: "…"` appears only on a row container (ROW_CONTAINER_ROLES) whose element.text is
+ * non-empty (438 D-02: the planner must see a row to state it); line breaks collapse the same
+ * way and the rendered text is capped at 120 characters plus `…`. The row text is a JSON string
+ * (JSON.stringify, as quoted() renders names in the refusal line), so a quote or backslash in app
+ * text cannot end the string or forge a ref, flag or line (438 gap round, WR-02, T-438-04).
+ * element.text keeps the full text the judge and replay compare against.
+ */
+declare function renderScreenTree(elements: ElementInfo[], metadata: ScreenStateMetadata): string;
+/**
+ * Pure re-stamp of the discriminated captureMode metadata member (D-11). Constructs a
+ * fresh metadata object from the base fields and returns a NEW ScreenState — zero `as`
+ * casts, zero mutation of the input.
+ */
+declare function stampCaptureMode(state: ScreenState, capture: CaptureStamp): ScreenState;
+
+/** The element the planner meant beside its ref (D-01); `row` names a repeated label's row. */
+interface StatedTarget {
+    role?: string;
+    name: string;
+    row?: string;
+}
+/** The element lanes an action can carry a stated target on. */
+type StatedTargetLane = 'ref' | 'fromRef' | 'toRef';
+/** The stated target per element lane, kept by the gate for the pre-dispatch check (D-01, D-04). */
+type StatedTargets = Partial<Record<StatedTargetLane, StatedTarget>>;
+type TargetMismatchReason = 'role-kind' | 'name-no-shared-word' | 'name-number' | 'row';
+type StatedTargetJudgement = {
+    verdict: 'agrees';
+    rowStated: boolean;
+    rowKnown: boolean;
+    observedRow?: string;
+} | {
+    verdict: 'contradicts';
+    reasons: TargetMismatchReason[];
+    rowStated: boolean;
+    observedRow?: string;
+};
+/**
+ * Judge a stated target against the element its ref names (D-03). `elements` is the observation
+ * the element belongs to; the element's row is read from it (D-02).
+ */
+declare function judgeStatedTarget(stated: StatedTarget, element: ElementInfo, elements: readonly ElementInfo[]): StatedTargetJudgement;
+
+/**
+ * The subset of the action union that may be persisted in a cached plan (D-08). The
+ * non-deterministic AI-assertion verbs — `assertAI` (judge lane) and `extractAI`
+ * (extraction lane) — are `Exclude`d from the composed `Action` union so a plan carrying
+ * one CANNOT typecheck into a cache write. Plan 10's runtime guard at the write site is the
+ * narrowing proof; this static boundary is the belt-and-suspenders (the 356
+ * `NonCacheableStepInput` type-level idiom, mirrored at the value shape).
+ */
+type CacheablePlannedAction = Exclude<Action, {
+    type: 'assertAI';
+} | {
+    type: 'extractAI';
+}>;
+/**
+ * Descriptor-only locator (D-12, 438 D-10/D-11). Identity is the observed role, the exact
+ * observed name with spacing tidied (numbers and badges kept) and, when the planner stated a
+ * row the element's row holds, those row words. Never a position, a ref, a selector or
+ * coordinates: replay re-finds the one element with this identity in a fresh observation.
+ */
+interface GroundedLocator {
+    role: string;
+    name: string;
+    row?: string;
+}
+/**
+ * The cached plan value. `plannedActions` are stored in sanitized (locator-free,
+ * data-free) form AND statically exclude the AI-assertion verbs (D-08); grounding is carried
+ * only by `groundedLocator` descriptors so no run-specific ref/selector/coordinate or step
+ * `data` value ever persists (D-12).
+ */
+interface CachedPlanValue {
+    plannedActions: CacheablePlannedAction[];
+    groundedLocator: GroundedLocator[];
+    verificationOutcome: 'passed' | 'failed';
+}
+/**
+ * Redesigned per-key cache port (D-11). Get/set/invalidate over a branded CacheKey
+ * — the v1 prefix/index sub-action model is dropped. A storage implementation (Plan
+ * 05's FsActionCache) implements this interface; runner stays storage-neutral.
+ */
+interface ActionPlanCache {
+    get(key: CacheKey): Promise<CachedPlanValue | null>;
+    set(key: CacheKey, value: CachedPlanValue): Promise<void>;
+    invalidate(key: CacheKey): Promise<void>;
+}
+
+/**
+ * Project a planned action's target element to a descriptor-only locator: its role, its exact
+ * name, and the stated row when the element's known row holds it. Returns null when the action
+ * targets no element (e.g. navigate) or the ref no longer resolves.
+ */
+declare function toGroundedLocator(action: Action, elements: readonly ElementInfo[], stated?: StatedTarget): GroundedLocator | null;
+interface BuildCachedPlanValueInput {
+    plannedActions: readonly Action[];
+    elements: readonly ElementInfo[];
+    verificationOutcome: 'passed' | 'failed';
+    /** The completing decision's stated target per lane; supplies a locator's row words. */
+    statedTargets?: StatedTargets;
+}
+/**
+ * Assemble a descriptor-only CachedPlanValue. Planned actions are sanitized of every
+ * locator binding and step `data` value; grounding is carried solely by the
+ * descriptor locators so nothing run-specific is ever persisted (D-12 overfit guard).
+ */
+declare function buildCachedPlanValue(input: BuildCachedPlanValueInput): CachedPlanValue;
+
+declare const ROW_CONTAINER_ROLES: readonly string[];
+/**
+ * Word tokens of a text: digit groups joined, NFKC, lowercased, split on every run that is not a
+ * letter or digit.
+ */
+declare function wordTokens(text: string | undefined): string[];
+/**
+ * The row text of an element in its observation, or undefined when the element has no row
+ * container or the container's text is empty (D-02: the row is unknown).
+ */
+declare function rowTextOf(element: ElementInfo, elements: readonly ElementInfo[]): string | undefined;
+/** Whether every stated row word is in the row text (equal, or a prefix of a non-number word). */
+declare function rowContains(rowText: string, statedRow: string): boolean;
+
+type StrictMatchResult = {
+    kind: 'resolved';
+    ref: Ref;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'not-unique';
+    count: number;
+};
+
+/** The values a readable fill compared: requested and read back (sentinels for a secure field). */
+interface FillRereadMeta {
+    expected: string;
+    actual: string;
+}
+/** What ended a scroll: the target appeared, the swipe budget ran out, or a boundary signal. */
+type ScrollEndedBy = 'target-visible' | 'max-swipes' | 'boundary';
+/** Outcomes new runs write (436-02, D-24). */
+declare const SCROLL_OUTCOMES_WRITTEN: readonly ["found", "not-found", "unresolved"];
+/** Outcomes only pre-436 runs wrote; still read so persisted metadata stays parseable (D-17). */
+declare const SCROLL_OUTCOMES_READ_ONLY: readonly ["no-change", "cap"];
+/** EXEC-02 scroll outcome block. `endedBy` is absent on pre-436 metadata. */
+interface ScrollUntilVisibleMeta {
+    swipes: number;
+    reversedOnce: boolean;
+    outcome: (typeof SCROLL_OUTCOMES_WRITTEN)[number] | (typeof SCROLL_OUTCOMES_READ_ONLY)[number];
+    endedBy?: ScrollEndedBy;
+}
+/** EXEC-03 openApp resolution block. */
+interface OpenAppMeta {
+    resolvedId: string;
+    matchKind: 'exact' | 'fuzzy' | 'explicit';
+}
+
+declare function readFillRereadMeta(actionResult?: ActionResult): FillRereadMeta | undefined;
+declare function readScrollUntilVisibleMeta(actionResult?: MetadataCarrier): ScrollUntilVisibleMeta | undefined;
+declare function readOpenAppMeta(actionResult?: ActionResult): OpenAppMeta | undefined;
+/** EXEC-05 reportValue answer block (D-01/D-03). Keyed `reportedValue`. */
+interface ReportedValueMeta {
+    value: string;
+}
+/** EXEC-06 uniqueValue mint block (D-16). Keyed `uniqueValue`. */
+interface UniqueValueMeta {
+    value: string;
+    prefix: string;
+}
+/** EXEC-07 AI-judgment block (D-05/D-06/D-07/D-09). Keyed `aiJudgment`. */
+interface AiJudgmentMeta {
+    verb: 'assertAI' | 'extractAI';
+    verdict?: boolean;
+}
+/** EXEC-07 assertValue outcome block (D-10/D-11). Keyed `assertValueOutcome`. */
+interface AssertValueOutcomeMeta {
+    source: string;
+    op: string;
+    passed: boolean;
+    expected?: string;
+    actual?: string | null;
+}
+/**
+ * The minimal structural input the 360 metadata readers narrow: any ActionResult-like carrier of a
+ * metadata bag. Broader than `ActionResult` so the seam's loosely-typed sub-action result surfaces
+ * (which only guarantee an optional `metadata`) narrow cleanly — the defensive idiom returns
+ * undefined on any shape miss regardless.
+ */
+type MetadataCarrier = {
+    metadata?: Record<string, unknown>;
+};
+declare function readReportedValueMeta(actionResult?: MetadataCarrier): ReportedValueMeta | undefined;
+declare function readUniqueValueMeta(actionResult?: MetadataCarrier): UniqueValueMeta | undefined;
+declare function readAiJudgmentMeta(actionResult?: MetadataCarrier): AiJudgmentMeta | undefined;
+declare function readAssertValueOutcomeMeta(actionResult?: MetadataCarrier): AssertValueOutcomeMeta | undefined;
+/** Typed refusal of a fill/clearText before any text was typed. Keyed `fillRefusal`. */
+interface FillRefusalMeta {
+    verb: 'fill' | 'clearText';
+    cause: 'not-editable' | 'target-not-found' | 'single-line-field';
+    evidence: 'no-editable-signal' | 'no-keyboard-focus' | 'focus-elsewhere' | 'stale-target' | 'text-has-line-breaks';
+}
+/**
+ * What happened to a requested submit after a fill (437 D-17). Keyed `fillSubmit`. Pre-437 blocks
+ * carry `sent` alone or `{ sent: false, reason: 'multi-line-field' }` and still read.
+ */
+interface FillSubmitMeta {
+    sent: boolean;
+    outcome?: SubmitOutcome;
+    reason?: SubmitReason;
+    detail?: string;
+}
+/** A shell-routed action refused or failed by the driver (437 D-18). Keyed `shellAction`. */
+interface ShellActionMeta {
+    verb: 'keyevent' | 'openQuickSettings';
+    outcome: 'unavailable' | 'failed';
+    reason?: 'adb-shell-disabled';
+    detail?: string;
+}
+declare function readFillRefusalMeta(actionResult?: MetadataCarrier): FillRefusalMeta | undefined;
+/** How a fill or clear's read-back compared with the requested text (437 D-06). Keyed `fillVerdict`. */
+interface FillVerdictMeta {
+    verb: 'fill' | 'clearText';
+    verdict: FillVerdict;
+    path?: InputPath;
+    secure?: true;
+}
+declare function readFillVerdictMeta(actionResult?: MetadataCarrier): FillVerdictMeta | undefined;
+declare function readFillSubmitMeta(actionResult?: MetadataCarrier): FillSubmitMeta | undefined;
+declare function readShellActionMeta(actionResult?: MetadataCarrier): ShellActionMeta | undefined;
+declare function readDownloadMeta(actionResult?: MetadataCarrier): DownloadEvidence[] | undefined;
+/** The most masked clipboard text one write keeps; longer text is cut and marked. */
+declare const CLIPBOARD_TEXT_LIMIT = 2000;
+declare const CLIPBOARD_TRUNCATION_MARKER = "\u2026[truncated]";
+type ClipboardWriteMeta = Pick<ClipboardEvidence, 'source' | 'text' | 'readBack'>;
+declare function readClipboardMeta(actionResult?: MetadataCarrier): ClipboardWriteMeta[] | undefined;
+
+interface FillVerifyInput {
+    expected: string;
+    actual: string | undefined;
+    secure: boolean;
+    verb?: 'fill' | 'clearText';
+}
+interface FillVerifyResult {
+    verdict: FillVerdict;
+    ok: boolean;
+    secure?: true;
+    meta?: FillRereadMeta;
+    selfCorrectingError?: string;
+}
+declare const FILL_SEPARATORS: ReadonlySet<string>;
+declare function compareFillReread(input: FillVerifyInput): FillVerifyResult;
+
+type DesiredState = 'checked' | 'unchecked' | 'selected' | 'unselected';
+interface DesiredStateAction {
+    type: string;
+    ref?: string;
+    desiredState?: DesiredState;
+    value?: string;
+}
+declare function desiredStateSatisfied(action: DesiredStateAction, screenState: ScreenState): IdempotentNoopMeta | undefined;
+
+type Direction = 'up' | 'down' | 'left' | 'right';
+/** What one swipe proved: the container moved, it is at its extent, or nothing is known. */
+type SwipeSignal = 'moved' | 'at-boundary' | 'unknown';
+/** The target is on screen, definitively not on screen, or cannot be judged. */
+type TargetVisibility = 'visible' | 'hidden' | 'unknown';
+interface ScrollPrimitives {
+    /** One platform swipe in `direction`, optionally inside container `ref`. */
+    swipeOnce(direction: Direction, ref?: Ref): Promise<SwipeSignal>;
+    /** Native search-scroll toward `target`; its `true` is confirmed by the visibility probe. */
+    nativeSearchScroll?(target: string, ref?: Ref, direction?: Direction): Promise<boolean>;
+    /** Light probe: interim nodes only, NO refMap mint, NO screenshot. Read for visibility only. */
+    readInterimTree(): Promise<InterimNode[]>;
+    /**
+     * Is `target` visible, definitively not on screen, or impossible to judge? When supplied it
+     * replaces the interim-tree name match; any other answer counts as unknown.
+     */
+    probeTargetVisible?(target: string, ref?: Ref): Promise<TargetVisibility>;
+}
+interface UntilVisibleParams {
+    target: string;
+    direction: Direction;
+    maxSwipes: number;
+    retryOpposite: boolean;
+    ref?: Ref;
+}
+interface ScrollLoopResult {
+    meta: ScrollUntilVisibleMeta;
+    found: boolean;
+}
+interface ScrollOffsets {
+    before: number;
+    after: number;
+    /** Largest offset the container can reach on the swiped axis. */
+    max: number;
+}
+/**
+ * The offset rule shared by every surface that can read real scroll offsets (web containers,
+ * Android WebView): a changed offset is movement; an unchanged offset at the container's extent
+ * in the swiped direction is the boundary; anything else is unknown.
+ */
+declare function swipeSignalFromOffsets(direction: Direction, offsets: ScrollOffsets | undefined): SwipeSignal;
+/** A page's scrolling element, read before and after a gesture that is not bound to a container. */
+interface DocumentScrollOffsets {
+    x: number;
+    y: number;
+    maxX: number;
+    maxY: number;
+}
+/**
+ * The offset rule for a gesture that lands on whatever is under the pointer (web wheel, WebView
+ * touch swipe), over every scroller the gesture may have acted on, as aligned before/after arrays
+ * (436-18 · D-25). Any member that moved is movement. A boundary needs at least one member with
+ * range on the swiped axis and every member with range at its extent; a member short of its
+ * extent, no member with range, or missing, empty or misaligned arrays prove nothing.
+ */
+declare function scrollerSetSwipeSignal(direction: Direction, before: readonly DocumentScrollOffsets[] | undefined, after: readonly DocumentScrollOffsets[] | undefined): SwipeSignal;
+/**
+ * The scroller-set rule over the document scroller alone: a document with no scroll range on the
+ * swiped axis proves nothing, because the gesture may have moved a nested scroller.
+ */
+declare function documentSwipeSignal(direction: Direction, before: DocumentScrollOffsets | undefined, after: DocumentScrollOffsets | undefined): SwipeSignal;
+declare function runUntilVisibleLoop(p: ScrollPrimitives, params: UntilVisibleParams): Promise<ScrollLoopResult>;
+interface DirectionScrollParams {
+    direction: Direction;
+    ref?: Ref;
+}
+/** Direction mode is one gesture: no opposite retry, whatever the signal says. */
+declare function runDirectionScroll(p: ScrollPrimitives, params: DirectionScrollParams): Promise<ScrollLoopResult>;
+declare const MAX_TO_END_SWIPES = 20;
+/**
+ * toEnd: swipe until a boundary signal or the cap. Reaching the boundary is the goal, so it
+ * reports 'found'; the cap without a boundary signal reports 'unresolved'.
+ */
+declare function runToEndScroll(p: ScrollPrimitives, direction: Direction, ref?: Ref, cap?: number): Promise<ScrollLoopResult>;
+
+interface AppRegistryEntry {
+    id: string;
+    label?: string;
+}
+interface ScorerOptions {
+    fuzzyThreshold?: number;
+    fuzzyMargin?: number;
+    editDistanceBound?: number;
+    candidateCount?: number;
+}
+type AppResolution = {
+    kind: 'exact' | 'fuzzy';
+    id: string;
+} | {
+    kind: 'ambiguous' | 'unknown';
+    candidates: {
+        id: string;
+        label?: string;
+    }[];
+};
+/**
+ * Minimum score a fuzzy top candidate must clear to be launchable. Internal runner constant;
+ * injectable via ScorerOptions for tests only. Do NOT promote to user-facing config or thread
+ * through LoopPorts / any config schema (353 K=2 precedent).
+ */
+declare const DEFAULT_FUZZY_THRESHOLD = 0.5;
+/**
+ * Minimum lead the top fuzzy candidate must hold over the runner-up to launch (else ambiguous).
+ * Internal runner constant; injectable for tests only. Do NOT promote to user-facing config.
+ */
+declare const DEFAULT_FUZZY_MARGIN = 0.15;
+/**
+ * Levenshtein cap: matches beyond this edit distance do not count as edit-rung candidates.
+ * Internal runner constant; injectable for tests only. Do NOT promote to user-facing config.
+ */
+declare const DEFAULT_EDIT_DISTANCE_BOUND = 3;
+/**
+ * How many candidates an ambiguous/unknown resolution surfaces. Internal runner constant;
+ * injectable for tests only. Do NOT promote to user-facing config.
+ */
+declare const DEFAULT_CANDIDATE_COUNT = 3;
+declare function resolveAppName(name: string, registry: AppRegistryEntry[], opts?: ScorerOptions): AppResolution;
+
+/** The closed set of runner-minted (platform-less) verb names dispatched without adapter.execute. */
+declare const MINT_VERBS: readonly ["reportValue", "uniqueValue"];
+type MintVerb = (typeof MINT_VERBS)[number];
+/** Emission params for a `reportValue` mint (mirrors reportValueSchema). */
+interface ReportValueInput {
+    value: string;
+}
+/**
+ * Mint the D-01/D-03 `reportValue` success result. The answer rides `metadata.reportedValue`
+ * (readReportedValueMeta narrows it). NOTE: `value` here is the emission value — the Plan 10 seam
+ * masks before recording into StepEvidence.reportedValue (masked-before-record, T-360-01).
+ */
+declare function mintReportedValue(input: ReportValueInput): ActionResult;
+/** Emission params for a `uniqueValue` mint (mirrors uniqueValueSchema). */
+interface UniqueValueInput {
+    prefix: string;
+}
+/**
+ * The injectable suffix generator (353 K=2 determinism, D-16): a pure `() => string` overridden in
+ * tests for deterministic output, defaulting to {@link defaultUniqueValueGenerator}.
+ */
+type UniqueValueGenerator = () => string;
+/**
+ * Mint the D-16 `uniqueValue` success result: `prefix` + a generated suffix, carried on
+ * `metadata.uniqueValue` ({ value, prefix }). The generator is injectable for deterministic tests;
+ * uniqueness is the semantic, so cache replay re-mints fresh. The Plan 10 seam auto-writes the
+ * minted value into run-scoped working memory keyed by the prefix.
+ */
+declare function mintUniqueValue(input: UniqueValueInput, generator?: UniqueValueGenerator): ActionResult;
+/**
+ * Default suffix source (D-16): timestamp + entropy, base36-encoded, non-empty and distinct across
+ * calls. Injectable so deterministic tests pass a fixed generator instead. Randomness/time IS the
+ * semantic here (uniqueness), unlike the deterministic app-resolution ladder.
+ */
+declare function defaultUniqueValueGenerator(): string;
+
+/** Comparator input: the source label, the closed op, the (optional) expected, and the raw actual. */
+interface AssertValueInput {
+    source: string;
+    op: AssertValueOp;
+    /** Absent for the no-expected ops (isNull/isDefined). */
+    expected?: string;
+    /** The raw value the adapter read. `null` is a read; `undefined` is unread and fails every op. */
+    actual?: string | null;
+    /** Each network log entry's JSON, for `source: 'network'`. Absent or empty is unread. */
+    entries?: string[];
+}
+/** Comparator outcome — projects onto the schema AssertValueEvidence block. */
+interface AssertValueResult {
+    source: string;
+    op: AssertValueOp;
+    expected?: string;
+    actual?: string | null;
+    passed: boolean;
+}
+/**
+ * Apply the closed assertValue op deterministically. Type-aware per the Block A pins: gt/lt coerce
+ * numeric; equals/notEquals/contains compare as strings; isNull passes only on a null read. An
+ * unread value fails every op (439 D-14). A network read passes only on a matching entry.
+ */
+declare function compareAssertValue(input: AssertValueInput): AssertValueResult;
+
+/** The most characters of each side `firstDifference` shows. */
+declare const FILE_DIFFERENCE_WINDOW = 80;
+interface SavedFileExpectation {
+    name: string;
+    /** 'none': the name only; 'exact': the whole text; 'lines': each line whole, in order. */
+    match: 'none' | 'exact' | 'lines';
+    text: string;
+}
+interface SavedFileComparison extends ConditionFileCheck {
+    /** The 1-based file line of the first difference, when the content differs. */
+    line?: number;
+}
+/**
+ * Compare a held download with the verifier's expectation. The name is exact (case and extension);
+ * 'exact' needs the whole text, 'lines' each expected line as a whole file line in order, and an
+ * empty expected text matches only a zero-byte file. `bytes` undefined, or bytes that are not valid
+ * UTF-8, leave the content 'unverified'.
+ */
+declare function compareSavedFile(input: {
+    expected: SavedFileExpectation;
+    name: string;
+    bytes: Uint8Array | undefined;
+    mask: (value: string) => string;
+}): SavedFileComparison;
+
+/**
+ * A complete, valid v2 `ScreenState` with `captureMode: 'textOnly'`. Callers override
+ * individual fields; the base is deterministic (fixed refs/bounds/timestamp/scroll).
+ */
+declare function makeScreenState(overrides?: Partial<ScreenState>): ScreenState;
+/** The platform-neutral node list + the builder input (minus nodes/platform). */
+interface InterimFixture {
+    nodes: InterimNode[];
+    buildInput: Omit<BuildScreenStateInput, 'nodes' | 'platform'>;
+}
+type InterimFixtureKind = 'login-screen' | 'mixed-geometry' | 'nested';
+/**
+ * Platform-neutral interim nodes plus the matching builder input for a scenario. The
+ * conformance cases feed these through `buildScreenState` (per platform) to assert the
+ * shared contract holds identically across all three adapters.
+ */
+declare function makeInterimNodes(kind: InterimFixtureKind): InterimFixture;
+
+type RecordedActionOutcome = 'success' | 'failure' | 'no-input' | 'refused';
+interface RecordedAction {
+    /** 1-based position of the action in the step. */
+    index: number;
+    action: Action;
+    /** The element the action's ref named on the screen it acted on. */
+    element?: {
+        role: string;
+        name: string;
+    };
+    outcome: RecordedActionOutcome;
+    error?: string;
+    operationEvidence?: OperationEvidence;
+}
+type RecordedReadKind = 'assertValue' | 'assertAI' | 'extractAI' | 'reportValue';
+interface RecordedRead {
+    /** The 1-based index of the action that read the value. */
+    index: number;
+    kind: RecordedReadKind;
+    text: string;
+    assert?: {
+        source: string;
+        op: string;
+        expected?: string;
+        passed: boolean;
+    };
+    claim?: string;
+    /** An assertAI read's verdict on its claim. */
+    judged?: boolean;
+    mode?: string;
+}
+interface CarriedLine {
+    stepNumber: number;
+    actionIndex: number;
+    text: string;
+}
+interface VerifierStepRecord {
+    startScreen: ScreenState;
+    actions: RecordedAction[];
+    reads: RecordedRead[];
+    carried: CarriedLine[];
+}
+interface RenderedStepRecord {
+    actions: string;
+    operationEvidence: string;
+    reads: string;
+    carried: string;
+}
+declare const RECORD_ACTION_LINE_CAP = 40;
+declare const RECORD_LINE_CHAR_CAP = 300;
+declare const RECORD_LIST_CAP = 50;
+declare class StepRecordAccumulator {
+    private startScreen;
+    private readonly actions;
+    private readonly reads;
+    private readonly carried;
+    /** Keeps the first settled observation of the step; later calls are ignored. */
+    start(screen: ScreenState): void;
+    addAction(entry: Omit<RecordedAction, 'index'>): number;
+    /** A read belongs to the action about to be recorded. */
+    addRead(entry: Omit<RecordedRead, 'index'>): void;
+    addCarried(line: CarriedLine): void;
+    /** The actions recorded so far; unlike `snapshot` it needs no start screen. */
+    recordedActions(): RecordedAction[];
+    snapshot(): VerifierStepRecord;
+}
+/** The record as the verifier turn shows it, one string per part. */
+declare function renderStepRecord(record: VerifierStepRecord): RenderedStepRecord;
+
+/**
+ * A planned action plus the frozen v45 plan envelope (D-09). Structural mirror of
+ * core's ActionPlanSchema output; the v45 tool registry (this plan, task 3) produces it.
+ */
+interface ActionPlan {
+    reasoning: string;
+    action: {
+        type: string;
+        [key: string]: unknown;
+    };
+    confidence: number;
+    stepComplete: boolean;
+    stepFailed?: boolean;
+    /**
+     * D-09/GROUND-01 grounding-attempts carriage. When the planning turn grounds the
+     * action in-turn (via the injected groundability callback), the gate's §A8
+     * GroundingAttempt trail rides here so the resolved-descriptor evidence reaches
+     * executeStep (threaded onto StepEvidence in Plan 07). Absent when no grounding
+     * callback is injected or the gate recorded no attempts.
+     */
+    groundingAttempts?: GroundingAttempt[];
+    /** D-01: the element the planner meant per element lane, judged before dispatch. */
+    statedTargets?: StatedTargets;
+    /**
+     * WM-01 write channel (spec §12.15, ratified 2026-07-05). Verbatim facts the planner captured
+     * this turn via the `remember[]` plan-field; the loop hands them to the run-scoped
+     * `WorkingMemoryStore` (Plan 08 wiring). Absent when the planner captured nothing this turn.
+     */
+    remember?: WorkingMemoryEntry[];
+    /**
+     * D-09 bulk-loop completion predicate. On a "do X to all" step the planner declares the positive
+     * completion predicate here and re-states it each turn; the verifier backstops. Absent for
+     * non-bulk steps.
+     */
+    bulkCompletionPredicate?: string;
+    /**
+     * D-04 infeasible terminal outcome (EXEC-05, spec §12.10). The additive plan-field envelope
+     * (358 remember[] precedent) by which a turn declares the step terminally infeasible — the
+     * requested capability/screen does not exist in this build. Closed literal union ('infeasible'
+     * today, extensible later); machine-distinguishable from a plain `stepFailed`. When set, the
+     * loop routes it into a typed StepEvidence.termination block and a distinct verdict outcome
+     * (Plan 10 seam). Absent for an ordinary failure.
+     */
+    failureKind?: 'infeasible';
+    /**
+     * D-04 infeasible reason — required whenever `failureKind` is set (enforced at the
+     * toolCallToActionPlan parse boundary). The human-readable why, recorded verbatim in the
+     * termination evidence block. Absent unless `failureKind` is present.
+     */
+    failureReason?: string;
+}
+/** 436 D-08: debits one planner model call before it is made; false refuses the call. */
+interface PlanningCallGate {
+    tryDebitPlanningCall(): boolean;
+}
+interface PlannerConfig {
+    maxActions: number;
+    maxPlanningTurns: number;
+    previousStepCount: number;
+}
+interface PlanResult {
+    plan: ActionPlan;
+    tokenUsage?: TokenUsage;
+    /**
+     * Ordered non-action exchanges from this live planning decision (D-01).
+     * Absent for cache-replay-produced results, which have no live planning turn.
+     */
+    exchanges?: ToolExchangeEvidence[];
+    /**
+     * Observed final-response metadata for this live planning decision (D-05/D-08).
+     * Absent when the provider exposes no call record or no live model call occurred.
+     */
+    callRecord?: ModelCallRecord;
+}
+/** One condition as the verifier judged it (439 D-02, D-10); the runner decides what it counts for. */
+interface ConditionJudgment {
+    quote: string;
+    verdict: ConditionVerdict;
+    needs: 'none' | ConditionNeed;
+    controlRef: string;
+    file: {
+        name: string;
+        match: 'none' | 'exact' | 'lines';
+        text: string;
+    };
+    citations: {
+        source: CitationSource;
+        quote: string;
+    }[];
+    reasoning: string;
+}
+/** An open dialog as the verifier accounted for it (439 D-16). */
+interface DialogAccount {
+    name: string;
+    account: 'bears-on-condition' | 'requested' | 'unrelated';
+    reasoning: string;
+}
+/**
+ * The verifier's per-condition output. There is no overall success: the runner computes the pass
+ * (439 D-10). `verifierError` is set only by the fallback when the model call failed.
+ */
+interface VerificationResult {
+    conditions: ConditionJudgment[];
+    dialogs: DialogAccount[];
+    isAppError: boolean;
+    reasoning: string;
+    verifierError?: string;
+}
+interface VerifyResult {
+    verification: VerificationResult;
+    tokenUsage?: TokenUsage;
+}
+interface StepContext {
+    stepInstruction: string;
+    testName: string;
+    testContext?: string;
+    suiteContext?: string;
+    stepNumber?: number;
+    stepCount?: number;
+    previousSteps: {
+        instruction: string;
+        outcome: string;
+        reasoning?: string;
+        plannedAction?: string;
+        verifierResponse?: string;
+    }[];
+    contextWindow?: number;
+    plannerModel: LanguageModel;
+    verifierModel: LanguageModel;
+    modelId?: string;
+    variables?: Record<string, string>;
+    /**
+     * The `{{env:NAME}}` bindings that interpolated into `stepInstruction` before this step
+     * was planned (PROC-01 · 381 D-03/D-08). DESTINATION: stamped verbatim onto
+     * `StepEvidence.interpolatedVariables` at finalize, where the procedure-extraction emit
+     * fold reads it to classify a trajectory value slot back to its source binding NAME.
+     *
+     * Carried VERBATIM end to end — never masked (unlike `variables` above, which is
+     * secret-redacted for the planner). See the masking prohibition documented on
+     * `StepEvidence.interpolatedVariables`: masking would break the consumer's exact-match
+     * classification for email-valued and credential-named bindings.
+     *
+     * Absent/empty when the step's text interpolated nothing — finalize then stamps nothing.
+     */
+    interpolatedVariables?: readonly InterpolatedVariable[];
+    /**
+     * D-12/D-13 compatibility slot for a directly supplied learned brief. Reader-backed runs use
+     * the structured L1/L2/truncation fields below; buildVolatileTier applies the same hypotheses
+     * frame to either source. Empty/undefined omits the learned section entirely.
+     */
+    knowledgeBrief?: string;
+    /**
+     * BRIF-01 human-authored/sovereign L0 policy material. It is isolated from learned spans so
+     * buildContextTier can keep only this byte-stable material in the cached-prefix region.
+     */
+    knowledgePolicyL0?: string;
+    /** BRIF-01 learned caution summaries rendered under the volatile hypotheses frame. */
+    knowledgeBriefL1?: string;
+    /** BRIF-01 learned procedure/high-trust-fact summaries rendered in the volatile tier. */
+    knowledgeBriefL2?: string;
+    /** BRIF-01 reader-provided clipping signal; empty/undefined means no signal is rendered. */
+    knowledgeBriefTruncation?: string;
+    /**
+     * CR-08 immutable UTC date for planner prompt evidence, captured once per step as
+     * `YYYY-MM-DD`. When absent, direct legacy prompt-builder callers retain the current
+     * UTC-date fallback. Bound values cross this type unchanged; the production capture
+     * boundary validates the closed date form before persistence.
+     */
+    promptDate?: string;
+    /**
+     * D-12/D-13 working-memory channel (structured turn content). The run-scoped
+     * `WorkingMemoryStore` set, injected verbatim as its own turn message by `composeTurnMessages`
+     * — the second v2 channel replacing the retired single memory-context string. Phase 358
+     * SANCTIONED BREAK (D-12/D-13): this was a plain `string` slot; it is now `WorkingMemoryEntry[]`
+     * (no shim, no string overload) so the planner receives the structured verbatim set. Empty
+     * array/undefined ⇒ omitted from the turn entirely (empty-slot omission).
+     */
+    workingMemory?: WorkingMemoryEntry[];
+    /**
+     * D-09 active bulk-completion predicate (per-turn VOLATILE turn content). While a bulk
+     * "do X to all" loop is running, the planner's declared positive predicate is re-stated each
+     * turn with the re-evaluate/cite-positive-evidence instruction. Absent for non-bulk steps.
+     */
+    bulkCompletionPredicate?: string;
+    failureContext?: string;
+    /**
+     * Sub-actions already attempted in this step (multi-action mode), with each outcome and any
+     * returned data. Screen change is not recorded here: outcomes decide (HARN-01).
+     */
+    subActionHistory?: {
+        action: string;
+        reasoning?: string;
+        result: 'success' | 'failure' | 'no-input';
+        error?: string;
+        verifierRejection?: string;
+        data?: string;
+        evidence?: string;
+    }[];
+    plannerConfig?: PlannerConfig;
+    /** 436 D-08: the step's planning-call meter, bound by the loop before each plan() call. */
+    planningCallGate?: PlanningCallGate;
+    screenshot?: Buffer;
+    /**
+     * Vision-gate prompt note for this run (D-11). Non-empty only for text-only
+     * models; injected into the planner prompt when present.
+     */
+    promptNote?: string;
+    /**
+     * D-13 re-run-after-failure context (LOOP-03). A re-run carries everything (full
+     * memory/context, no ablation) plus an explicit run-level flag and the prior
+     * attempt's failure summary, surfaced to the planner as prompt context.
+     */
+    isRerun?: boolean;
+    rerunAttempt?: number;
+    previousFailureSummary?: string;
+}
+interface Planner {
+    plan(step: string, screenState: ScreenState, context: StepContext, abortSignal?: AbortSignal): Promise<PlanResult>;
+}
+interface VerifierAuthorContext {
+    suiteContext?: string;
+    testContext?: string;
+    stepNumber?: number;
+    stepCount?: number;
+}
+interface Verifier {
+    verify(step: string, before: ScreenState, after: ScreenState, action: Action, screenshot?: Buffer, abortSignal?: AbortSignal, promptNote?: string, bulkCompletionPredicate?: string, authorContext?: VerifierAuthorContext, operationEvidence?: OperationEvidence, record?: VerifierStepRecord): Promise<VerifyResult>;
+    /**
+     * D-05 AI judge lane (EXEC-07, spec §9.6/§12.2) — OPTIONAL so every existing Verifier
+     * implementor keeps compiling (D-05: no new port). Plan 09 implements this on LLMVerifier
+     * against the injected model handle; the loop (Plan 10 seam) routes `assertAI` through it
+     * exactly once per attempt (single-model law). A single-shot judgment over the current
+     * observation returning the verdict + rationale. `opts` carries the requested-but-deferred
+     * M3/M4 knobs (consensus/video/effort) so demand is recorded (D-09).
+     */
+    judgeClaim?(claim: string, screen: ScreenState, opts?: Record<string, unknown>): Promise<{
+        verdict: boolean;
+        rationale: string;
+    }>;
+    /**
+     * D-07 AI extraction lane (EXEC-07, spec §9.6) — OPTIONAL, same no-new-port rationale as
+     * `judgeClaim`. Plan 09 implements it on LLMVerifier; the loop routes `extractAI` through it,
+     * writes the extracted fields into run-scoped working memory (`scope:'run'`), and degrades
+     * `scope:'global'` to the same run-scoped write (D-07). Returns the extracted field map.
+     */
+    extractData?(query: string, screen: ScreenState, opts?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+type AssertionType = 'text-presence' | 'element-visibility' | 'url-match' | 'element-count' | 'ai';
+interface AssertionInput {
+    type: AssertionType;
+    value: string;
+    expected?: string;
+}
+interface AssertionResult {
+    passed: boolean;
+    assertionType: AssertionType;
+    expected: string;
+    actual: string;
+    reasoning: string;
+}
+interface Asserter {
+    evaluate(assertion: AssertionInput, screenState: ScreenState): Promise<AssertionResult>;
+}
+type ExtractionMethod = 'regex' | 'selector' | 'ai';
+interface ExtractorInput {
+    method: ExtractionMethod;
+    variableName: string;
+    pattern?: string;
+    selector?: string;
+    description?: string;
+}
+interface CaptureResult {
+    success: boolean;
+    variableName: string;
+    value?: string;
+    reasoning: string;
+}
+interface VariableExtractor {
+    extract(input: ExtractorInput, screenState: ScreenState): Promise<CaptureResult>;
+}
+
+/** A legacy `{ success }` verdict a double may still be written with, or the full result. */
+type ScriptedVerdict = {
+    success: boolean;
+    reasoning: string;
+    isAppError?: boolean;
+} | VerificationResult;
+/** One met condition quoting the whole step, citing the first line of the final screen. */
+declare function metVerification(options: {
+    step: string;
+    after?: ScreenState;
+    action?: Action;
+    reasoning?: string;
+}): VerificationResult;
+/** One not-met condition quoting the whole step, with no citations. */
+declare function notMetVerification(options: {
+    step: string;
+    reasoning: string;
+}): VerificationResult;
+/** A passing or failing scripted verdict in the per-condition shape, with `isAppError` carried. */
+declare function scriptedVerification(options: {
+    step: string;
+    after?: ScreenState;
+    action?: Action;
+    pass: boolean;
+    reasoning: string;
+    isAppError?: boolean;
+}): VerificationResult;
+/** Convert a scripted verdict to the per-condition shape against what `verify` received. */
+declare function toVerificationResult(verdict: ScriptedVerdict, received: {
+    step: string;
+    after?: ScreenState;
+    action?: Action;
+}): VerificationResult;
+
+/**
+ * A single platform's observed input for the shared spec. `buildInput` is the builder
+ * input minus the parts the case controls (`nodes` and `platform`).
+ */
+interface ConformanceInput {
+    platform: Platform;
+    nodes: InterimNode[];
+    buildInput: Omit<BuildScreenStateInput, 'nodes' | 'platform'>;
+}
+/**
+ * One executable contract assertion. `run` receives a factory so cases that need
+ * independent builds (e.g. the determinism check) can materialize the input twice.
+ * Violations throw a plain Error — no assertion library.
+ */
+interface ScreenConformanceCase {
+    name: string;
+    run(make: () => ConformanceInput): void;
+}
+declare const screenConformanceCases: ScreenConformanceCase[];
+
+type HookRuntime = 'node' | 'bun' | 'python' | 'bash';
+interface HookDefinition {
+    id: string;
+    name: string;
+    runtime: HookRuntime;
+    file: string;
+    deps: string[];
+    packageFile?: string;
+    timeout: number;
+    network: boolean;
+}
+interface HookResult {
+    success: boolean;
+    variables: Record<string, string>;
+    output: string;
+    stdout: string;
+    stderr: string;
+    duration: number;
+    error?: string;
+}
+declare const RUNTIME_IMAGE_MAP: Record<HookRuntime, string>;
+
+/** Structurally compatible with model-owner reports; no provider implementation dependency. */
+interface StepModelCallReport {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    respondingModelId?: string;
+}
+type StepModelCallEvent = {
+    kind: 'start';
+} | {
+    kind: 'success';
+    report: StepModelCallReport;
+} | {
+    kind: 'failure';
+};
+interface StepModelObservation {
+    onCall(event: StepModelCallEvent): void;
+}
+interface StepModelScopeKey {
+    runId: RunId;
+    testIndex: number;
+    stepIndex: number;
+}
+interface StepModelRoleFacts {
+    declared?: ModelIdentity;
+    respondingModelIds: string[];
+}
+interface StepModelAttempt {
+    invocation: number;
+    role: 'planner' | 'verifier';
+    kind: StepModelCallEvent['kind'];
+    report?: StepModelCallReport;
+}
+interface StepModelSnapshot extends StepModelScopeKey {
+    attempts: StepModelAttempt[];
+    started: number;
+    succeeded: number;
+    failed: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    roles: {
+        planner: StepModelRoleFacts;
+        verifier: StepModelRoleFacts;
+    };
+}
+interface StepModelConsumers {
+    planner: Planner;
+    verifier?: Verifier;
+    plannerModel: LanguageModel;
+    verifierModel: LanguageModel;
+}
+interface StepModelScope extends StepModelConsumers {
+    readonly key: StepModelScopeKey;
+    snapshot(): StepModelSnapshot;
+    /** Freeze after extraction, before terminal publication. Pending attempts remain uncovered. */
+    finish(): StepModelSnapshot;
+    /** Called only after the final event; retained callbacks cannot affect another step. */
+    dispose(): void;
+}
+type StepModelScopeFactory = (key: StepModelScopeKey) => StepModelScope;
+interface StepModelBinding {
+    /** Resolved handle supplies metadata; it is never mutated or double-wrapped. */
+    model: Exclude<LanguageModel, string>;
+    /**
+     * Bind a fresh observer for ONE SDK invocation. Reuse host conversation/accounting state,
+     * but never a model bound to another observer. Model-owner middleware emits every actual
+     * retry start/terminal; the runner must not synthesize dispatches around generateText.
+     */
+    bind(observation: StepModelObservation): LanguageModel;
+}
+interface StepModelScopeOptions {
+    key: StepModelScopeKey;
+    models: {
+        planner: StepModelBinding;
+        verifier: StepModelBinding;
+    };
+    profiles?: {
+        planner: ModelIdentity;
+        verifier?: ModelIdentity;
+    };
+    mask(text: string): string;
+    createConsumers(models: Pick<StepModelConsumers, 'plannerModel' | 'verifierModel'>): Pick<StepModelConsumers, 'planner' | 'verifier'>;
+}
+/**
+ * The two 356 A5 config digests the run actually keyed on, computed once at the CLI
+ * composition root and passed in the resolved {@link RunConfig} (D-20). Carried verbatim
+ * into `runStarted`/the handoff so run identity and handoff identity cannot fork.
+ */
+interface ConfigDigests {
+    suiteConfigDigest: string;
+    testConfigDigest: string;
+}
+/**
+ * The run-start baseline health-probe outcome (D-04, RCC-02): ONE GET against the web
+ * target's base URL, executed at the CLI composition root (the runner bans node:* — only
+ * the RESULT crosses this seam). ALL probe failures arrive as values on `error`; a probe
+ * never aborts the run. Consumed by the deterministic root-cause classifier's environment
+ * branch (run/root-cause.ts).
+ */
+interface BaselineProbeResult {
+    status?: number;
+    elapsedMs: number;
+    error?: string;
+}
+/**
+ * The JSONL event-log seam (D-05/D-06). BOTH legs are SYNC and fire-and-forget — the bus
+ * NEVER awaits telemetry (a synchronous one-line append; D-06/D-07). `append` persists one
+ * envelope per emitted event; a throw degrades the bus to memory-only with a single
+ * `runWarning` (D-07). `read(fromSeq)` supplies older-than-window envelopes for deep replay.
+ * The runner-local `FsEventLog` (Plan 07) implements this against `events.jsonl`.
+ */
+interface EventLogPort {
+    append(envelope: RunEventEnvelope): void;
+    read(fromSeq: number): RunEventEnvelope[];
+}
+/**
+ * The per-hook execution options the orchestration threads into the {@link HookExecutorPort}
+ * (D-06). `env` is the accumulated-variables + user-env map the orchestrator merges per hook;
+ * `secretEnv` is the ALREADY-RESOLVED secret name→value map for container injection — the CLI
+ * composition root resolves the SecretStore and the runner never touches the store itself. The
+ * secret VALUES double as the output-variable filter (a hook-emitted variable equal to a secret
+ * value is dropped). `secretRedactor` redacts stdout/stderr/error; `authState` mounts + injects
+ * the active auth state (container-local paths only). Pitfall 3: all sandbox-side
+ * redaction/filtering stays inside the impl — the sink mask is additive.
+ */
+interface HookExecuteOptions {
+    env: Record<string, string>;
+    secretEnv: Record<string, string>;
+    secretRedactor?: SecretRedactorPort;
+    authState?: RuntimeAuthStateConfig;
+}
+/**
+ * The D-06 hook-execution seam: a runner-owned port whose only implementation is the
+ * runner-local `DockerHookExecutor` (the 356/361 port-in-runner/impl-in-runner-local
+ * precedent). `execute` runs ONE hook in the sandboxed container and resolves a
+ * {@link HookResult} — a per-hook timeout resolves a FAILED result with an exit-124-style
+ * error, NEVER a throw (the orchestration relies on a resolved result to synthesize
+ * fail-fast skips). node:child_process / node:fs live behind this port in runner-local;
+ * the runner stays storageNeutral (validate:arch is the arbiter).
+ */
+interface HookExecutorPort {
+    execute(hook: HookDefinition, opts: HookExecuteOptions): Promise<HookResult>;
+}
+/**
+ * The durable handoff seam (D-05/D-17). SYNC single-document persist of the one
+ * `CompletedRunHandoff` at run end; the runner-local `FsHandoffStore` (Plan 07) writes
+ * `handoff.json` beside `events.jsonl`. Failure degrades with a `runWarning`, never gates
+ * the verdict (D-07).
+ */
+interface HandoffStorePort {
+    save(handoff: CompletedRunHandoff): void;
+}
+/**
+ * What the post-verdict step is told about the run whose posture it is deciding (404 D-10).
+ *
+ * The two markers are read off the ASSEMBLED `RunConfig` — the same values `startRun` was handed
+ * — never off ambient state, so a gate-run skip (D-08) is decided from the run's own record.
+ * Absent means absent: `?: true` carriers are conditionally spread, never written as `undefined`.
+ */
+interface PostVerdictStepInput {
+    readonly runId: RunId;
+    readonly verdict: RunStatus;
+    readonly gateRun?: true;
+    readonly excludedFromOutcomes?: true;
+}
+/**
+ * The step's answer: the posture, and — when the consult could not decide — the reason, by name.
+ *
+ * A warning rather than a fourth union arm (D-11). `detached` is the honest "nothing will be
+ * drained from here", and the cause travels on the `runWarning` channel a surface already reads.
+ */
+interface PostVerdictOutcome {
+    readonly disposition: PostProcessingDisposition;
+    readonly warning?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/**
+ * The post-verdict step (404 D-10) — the `HandoffStorePort` idiom applied to the ONE decision the
+ * shell delays `runFinished` for.
+ *
+ * WHAT IT MAY DO: the durable enqueue and ONE writer-lease consult. Milliseconds. The runner
+ * names no queue, no sqlite and no lease vocabulary (validate:arch storageNeutral) — the HOST
+ * supplies the implementation, and the shell only awaits it.
+ *
+ * WHAT IT MAY NOT DO: gate `done`. A throw, a resolution past
+ * {@link POST_VERDICT_STEP_BUDGET_MS}, or an absent port all yield `detached` plus a named
+ * `runWarning`, and `runFinished` still publishes last with `bus.close()` behind it (403-03 D-3).
+ * The step returns a VALUE and never touches the bus: the shell keeps sole ownership of the
+ * terminal sequence.
+ *
+ * THE SHELL HOLDS NO LEASE. Whatever the step acquired stays with the host, which hands it to its
+ * own pump — acquire → pump → release is ONE lease, never re-acquired (RESEARCH Pitfall 3).
+ */
+interface PostVerdictPort {
+    run(input: PostVerdictStepInput): Promise<PostVerdictOutcome>;
+}
+/**
+ * The hard bound the shell races the step against (404 D-10, RESEARCH Pitfall 1).
+ *
+ * `acquireWriterLease` has contention/deadline semantics of its own, and a busy sqlite enqueue can
+ * stall; without a bound here `runFinished`, `done`, the SSE close and the dashboard finalize all
+ * slide behind it. Five seconds is generous for "enqueue + one consult" and still far below any
+ * drain budget — reaching it means the consult is not going to answer, which is `detached`.
+ */
+declare const POST_VERDICT_STEP_BUDGET_MS = 5000;
+/**
+ * The D-08 run-artifact persistence seam: a runner-owned port whose only implementation is the
+ * runner-local `FsRunArtifactStore` (the 356/361 port-in-runner/impl-in-runner-local precedent).
+ * BOTH legs are SYNC and fire-and-forget — the shell NEVER awaits artifact persistence, and a
+ * throw degrades with a `runWarning`, never gates the verdict (the event-log/handoff
+ * discipline; D-07). The store writes ONE `artifact.json` into the SAME
+ * `<root>/runs/<slug(runId)>/` family as `events.jsonl`/`handoff.json` (one self-contained run
+ * directory). `stage(document)` persists the config + source snapshot once after `runStarted`;
+ * `finalize(patch)` merges terminal errors + the end timestamp before `runFinished` — matching
+ * the dashboard DB staged/finalize idiom so a crashed run still leaves a staged artifact. Per the
+ * RESEARCH Q5 keep/drop table the FILE artifact keeps config/source/errors only; the top-level
+ * `runtime` section is dropped (derived from events/handoff). An absent port is a silent no-op.
+ */
+interface RunArtifactStorePort {
+    stage(document: RunArtifactStageInput): void;
+    finalize(patch: RunArtifactFinalizeInput): void;
+}
+/**
+ * Injectable timer seam for the heartbeat + run-budget clocks (spec §2.2 liveness / D-03).
+ * `schedule(delayMs, fn)` arms a one-shot and returns a cancel handle; `now()` supplies the
+ * envelope `ts`. The default impl wraps global setTimeout/clearTimeout (unref'd so it never
+ * keeps the process alive); unit pins inject a deterministic fake — no real timers, no watch
+ * mode.
+ */
+interface RunTimerPort {
+    schedule(delayMs: number, fn: () => void): () => void;
+    now(): number;
+}
+/**
+ * One ordered member of the run (D-04). `failFastGroup` scopes today's suite fail-fast: a
+ * failed/timed-out member skips the remaining SAME-group members; ungrouped members never
+ * fail-fast, preserving the single-test path's run-all behavior.
+ *
+ * `testIndex` is optional: the shell owns iteration and derives the authoritative index
+ * from array position (a caller-supplied value is a hint at most). `name` is REQUIRED so
+ * the compiler enforces every descriptor construction site supplies the parsed test name;
+ * handoff assembly copies it verbatim onto `PerTestOutcome.testName`.
+ */
+interface RunMemberDescriptor {
+    testId: string;
+    testIndex?: number;
+    name: string;
+    failFastGroup?: string;
+    /**
+     * The member test file's WORKSPACE-RELATIVE path — rooted at the config directory,
+     * forward-slashed, no leading `./`. REQUIRED since 381-01 (ABRF-02): stable test identity =
+     * filePath + testName, copied verbatim onto `PerTestOutcome.filePath` by the handoff assembly —
+     * the required field makes the compiler enforce that every descriptor construction site supplies
+     * it.
+     *
+     * 390-08 (CR-02 / D-01): this is IDENTITY, not a file handle. It is deliberately checkout-
+     * independent — the same bytes on every machine — because the committed `quarantine.jsonl` keys
+     * entries on it and matches with `===`, so an absolute path here would produce a ledger that
+     * could only ever apply on the machine that wrote it. Nothing in the run reads bytes off disk
+     * through this field; the CLI mints it via core's `workspaceRelativeIdentityPath` and keeps the
+     * absolute path on the side for every read.
+     */
+    filePath: string;
+    /**
+     * 363 D-01 parity fields (RESEARCH Q1). All OPTIONAL and additive — the shell rides them onto
+     * the widened `testStarted` payload so reporters can render the full v1 console/JUnit/wire
+     * surface from the bus alone. Suite grouping (`suiteId`/`suiteName`/`suiteIndex`/`suiteTotal`)
+     * rides testStarted rather than a suite lifecycle event — the shell stays suite-agnostic and
+     * reporters derive suite boundaries by watching the grouping change. `totalSteps` is the
+     * per-member parsed step count. The CLI populates these at both startRun sites; absent
+     * ⇒ omitted from the payload (no undefined-hole survives JSON round-trip).
+     */
+    suiteId?: string;
+    suiteName?: string;
+    suiteIndex?: number;
+    suiteTotal?: number;
+    totalSteps?: number;
+    /**
+     * G-428-2 (2026-09-26): the raw authored text of each step, in order. It is the same string
+     * member-runner announces at `stepStarted` (`memberStepText`). The shell masks it onto
+     * `testStarted.stepTexts`; callers never pre-mask. Absent ⇒ omitted from the payload.
+     */
+    stepTexts?: readonly string[];
+    /**
+     * THIS MEMBER'S OWN TARGET's run-start health baseline (D-04, 401-19 WR-04).
+     *
+     * PER MEMBER, NOT PER RUN, because a run's members may name different targets and a reading taken
+     * against one of them says nothing about another. It lived on `RunConfig` and was handed to the
+     * classifier for EVERY member, so a 503 observed against member B's target was recorded as member
+     * A's environment failure. The CLI composition root fills this in behind the verdict, probing each
+     * DISTINCT member URL once; absent means no probe applies to this member — the mobile posture,
+     * where the device-session-create failure is the equivalent environment signal, and equally the
+     * posture of a member whose target could not be resolved.
+     */
+    baselineProbe?: BaselineProbeResult;
+    /**
+     * 402-02 (D-09): members declaring the SAME lane share a mutable execution resource and MUST NOT
+     * run concurrently — the bounded member pool runs them strictly one at a time, in index order.
+     * Absent means "this member owns everything it touches" and the pool may schedule it freely.
+     *
+     * This is a PRECONDITION the producer states, never something the shell infers. D-09 requires
+     * each concurrent member its own browser/CDP handle; today's suite path does not satisfy that
+     * (every member of a suite drives the ONE adapter its suite set up, and `createSuiteLifecycle`
+     * admits one active suite at a time), while the direct path does (each direct test constructs
+     * its own adapter). A producer that starts handing each member its own session drops the lane
+     * and gets concurrency; nothing in the shell has to be re-argued for that to be safe.
+     */
+    exclusiveLane?: string;
+}
+/**
+ * The run-scoped event sink handed to the executor per member test (D-02). The shell binds
+ * `runId`/`testIndex`/masking; core curries `stepIndex` via `loopEmitFor`. `stepStarted`
+ * fires as a step opens; `loopEmitFor(stepIndex)` yields the {@link LoopEventEmitPort} the
+ * loop emits `stepFinalized`/`subActionRecorded` through.
+ */
+interface MemberEventSink {
+    stepStarted(input: {
+        stepIndex: number;
+        stepText: string;
+    }): void;
+    loopEmitFor(stepIndex: number): LoopEventEmitPort;
+    /**
+     * 363 D-01 parity legs, each routed through its Plan 01 projection + the sink mask (never a raw
+     * `bus.publish` from the caller — T-363-06). `hookStarted`/`hookFinished` are emitted by the
+     * runner hook orchestration (Plan 04 populates them; `hookFinished` stdout/stderr/error and every
+     * `variables` value are masked at the sink, T-363-05). `testRetryScheduled` is emitted by the
+     * member-runner retry loop (Plan 10) and marks a per-test accumulation reset for subscribers.
+     */
+    hookStarted(input: HookStartedPayload): void;
+    hookFinished(input: HookFinishedPayload): void;
+    testRetryScheduled(input: TestRetryScheduledPayload): void;
+}
+/** Immutable member-start decision context used when the shell must synthesize step evidence. */
+interface MemberEvidenceContext {
+    modelProfile?: DeclaredModelProfile;
+    verifierIdentity?: ModelIdentity;
+    toolSchemaDigest?: string;
+}
+/** The per-member execution context threaded into the injected {@link MemberTestExecutor}. */
+interface MemberTestRunContext {
+    /** Canonical shell identity. Legacy executors without a shell cannot certify scoped usage. */
+    runId?: RunId;
+    abortSignal: AbortSignal;
+    testIndex: number;
+    events: MemberEventSink;
+    setEvidenceContext(context: MemberEvidenceContext): void;
+    /**
+     * CASS-02 run-scoped decision-screenshot byte store (the same instance the shell holds on
+     * {@link RunPorts}). The member threads it onto `LoopPorts.evidenceArtifacts`; absent ⇒ a
+     * memory-only run with no screenshot persistence.
+     */
+    evidenceArtifacts?: EvidenceArtifactStorePort;
+    /**
+     * 403 D-05: declare (or withdraw) this member's live-stream producer. Optional on the SAME
+     * `setEvidenceContext` precedent above — the executor pushes a capability the shell knows
+     * nothing about, and the shell owns the per-run hub that refcounts it. Passing `undefined`
+     * withdraws the declaration (the handle then reads `{ kind: 'none' }`). Absent on the context
+     * ⇒ a composition that predates live view; the executor's optional call is a no-op.
+     * `fallback` is the labelled snapshot producer the hub switches to when the primary fails to
+     * start (428 D-12).
+     */
+    registerLiveStream?(capability: LiveStreamCapability | undefined, fallback?: LiveStreamCapability): void;
+}
+/**
+ * The injected per-test execution port (D-01). The CLI composition root wraps core's
+ * `runTest` behind this seam (core depends on runner, so runner can never import core);
+ * Phase 363 dissolves the core side of the port when it migrates hooks/variables/reporters.
+ * A staged migration, not a workaround — this is the exact seam 363 needs.
+ */
+type MemberTestExecutor = (member: RunMemberDescriptor, ctx: MemberTestRunContext) => Promise<TestResult>;
+/**
+ * The durable/telemetry/clock seams the run wires behind ports (D-04/D-05). All optional —
+ * an absent leg degrades gracefully (no persistence, memory-only telemetry, default clock).
+ * Grouped under `ports` so the resolved config keeps the run identity fields flat and the
+ * injectable I/O seams together (the Wave-0 `run-shell.test.ts` pins this nesting).
+ */
+interface RunPorts {
+    handoffStore?: HandoffStorePort;
+    eventLog?: EventLogPort;
+    /**
+     * The D-08 run-artifact store. Staged after `runStarted`, finalized before `runFinished`;
+     * absent ⇒ no artifact.json is written (memory-only run, byte-identical pre-363-06 behavior).
+     */
+    runArtifactStore?: RunArtifactStorePort;
+    /**
+     * The run-budget clock (D-03). The shell arms `runBudgetMs` on this timer; it is NOT
+     * routed into the bus heartbeat (the two clocks stay distinct so firing the injected
+     * budget timer is unambiguous — see the shell's timer note).
+     */
+    timer?: RunTimerPort;
+    /**
+     * The CASS-02 run-scoped decision-screenshot artifact store (Plan 11). The runner-local
+     * `FsEvidenceArtifactStore` is constructed run-scoped at the CLI composition root and injected
+     * here; the shell hands the same instance to every member. Absent ⇒ no screenshot bytes are
+     * persisted (memory-only run, byte-identical pre-Plan-11 behavior).
+     */
+    evidenceArtifacts?: EvidenceArtifactStorePort;
+    /**
+     * Where a VIEWER's fault is reported (403 WR-06): a live-frame subscriber that throws during
+     * delivery is detached by the hub and the fact lands here. NEVER the bus — the run's permanent
+     * transcript must not depend on who happened to be watching (LIVE-03). Same signature as the
+     * hub's own option, so the shell forwards rather than adapts; absent ⇒ reported nowhere.
+     */
+    onSubscriberFault?: (code: string, message: string) => void;
+    /**
+     * The 404 D-10 post-verdict step, awaited between `runArtifactStore.finalize` and
+     * `runFinished`. Absent ⇒ `disposition: 'detached'` with NO warning — a host that composed no
+     * step is not an error, it is a host from which nothing will be drained, and the wire says so.
+     */
+    postVerdict?: PostVerdictPort;
+}
+/**
+ * The fully-resolved run configuration `startRun` receives (D-04). The CLI keeps pattern
+ * discovery, parsing, config merge, and target/device/model resolution; `startRun` never
+ * touches fs or providers (validate:arch stays clean) — hence NO fs/provider/discovery-shaped
+ * members here. A future cloud RPC surface reuses this same resolved-config contract.
+ *
+ * `members`/`ports` shapes are pinned by the Wave-0 `run-shell.test.ts` scaffold.
+ */
+interface RunConfig {
+    runId: RunId;
+    scope: ScopeKey;
+    executionContext: ExecutionContext;
+    configDigests: ConfigDigests;
+    buildOrdinal: number;
+    /**
+     * D-14 §6 gate-run exclusion copied into the durable completed-run handoff. Only literal
+     * true excludes; absence denotes an ordinary counted run and remains absent in JSON.
+     */
+    excludedFromOutcomes?: true;
+    /**
+     * D-10 verify-before-present gate-run marker (Phase 384, 2026-07-28) copied into the
+     * durable completed-run handoff. A DISTINCT axis from `excludedFromOutcomes` above:
+     * C8-ratified, gate runs still feed curation. Only literal true marks a gate run;
+     * absence denotes an ordinary run and remains absent in JSON. 384 threads the carrier
+     * only — the exclusion semantics land in 388/393.
+     *
+     * ═══ 2026-08-26 — Phase 404 D-08 amends "gate runs still feed curation" ═══
+     *
+     * They still feed the FOLD — a gate run's handoff, folded, still emits curation candidates, and
+     * the outcome-side exclusion still keys on `excludedFromOutcomes` alone. What changed is the
+     * QUEUE: the post-verdict step enqueues NOTHING for a run carrying either marker, so no
+     * `analyze-run` row exists for a `write_test` keep-filter probe. The reasons are all about the
+     * gate loop rather than about correctness — no strong-model analysis cost per keep-gate
+     * iteration, no draft evidence reaching curation through the chain, and no post-processing chips
+     * about a run nobody will ever open. The marker still rides the handoff and the payload schema
+     * still carries it, because the exclusion is a decision the enqueue takes and not a fact the
+     * record forgets.
+     */
+    gateRun?: true;
+    members: readonly RunMemberDescriptor[];
+    executor: MemberTestExecutor;
+    /**
+     * The run's redactor over the secrets its producer read at the run's start (441-12, D-06/D-11).
+     * Every bus event, and so `events.jsonl` and the dashboard rows, is masked with it and nothing
+     * else. Absent ⇒ the run's events are published as written.
+     */
+    secretRedactor?: SecretRedactorPort;
+    runBudgetMs?: number;
+    ports?: RunPorts;
+    /**
+     * The D-08 config + source artifact snapshot the CLI composition root assembles (the
+     * `buildRunArtifactContext` document). Staged verbatim into `artifact.json` after `runStarted`
+     * via `ports.runArtifactStore`. Optional — absent ⇒ an empty stage (schema-version-only doc),
+     * so the store leg stays a no-op-shaped write and the memory-only path is unchanged.
+     */
+    runArtifact?: RunArtifactStageInput;
+    /**
+     * Phase 390 D-16: the quarantined-test set, resolved ONCE at run start by the composition layer
+     * (the CLI folds the committed ledger before the first member executes) and threaded in as PLAIN
+     * DATA. This is deliberately NOT a port: the runner gains zero new I/O seams and stays
+     * storageNeutral, and the disposition is deterministic for the whole run, so a mid-run ledger
+     * edit can never retroactively change a running build. Mirrors how `executionContext` is
+     * resolved once at run start.
+     *
+     * Members are matched on `(filePath, name)` — the stable test identity — never `testId`. A match
+     * makes the member's failure skippable in the aggregate rule (`deriveAggregateVerdict`) and
+     * stamps the disposition beside its truthful outcome in the handoff. Absent or empty ⇒
+     * byte-identical pre-390 behavior.
+     */
+    quarantined?: readonly QuarantineAppliedEntry[];
+    /**
+     * 436 D-06: the planner limits the producer resolved for this run and the members whose own
+     * limits differ, as plain data. Copied verbatim onto the handoff; absent stays absent.
+     */
+    plannerLimits?: PlannerLimitsRecord;
+    /**
+     * 402-02 (D-09/D-12): how many members may execute CONCURRENTLY in this run's process. Defaults
+     * to 1 — one worker is a plain sequential loop, byte-identical to the pre-402 shell, so nothing
+     * changes until a config resolves a higher value. Effective concurrency is
+     * `min(members.length, workers)`; values below 1 and non-finite values resolve to 1.
+     *
+     * CONFIG-RESOLVED, NEVER REQUEST-SUPPLIED (D-12). It arrives on the already-resolved RunConfig
+     * the composition root builds, exactly like `runBudgetMs` — `RunsStartInput` carries no
+     * concurrency field, so a remote token-holder cannot raise the concurrency of a target whose
+     * owner tuned it down (the refused-request-fields posture), and unbounded concurrency
+     * (T-402-08) has no reachable input.
+     */
+    workers?: number;
+}
+
+/**
+ * The raw storage-state blob (adapter-produced; e.g. a Playwright storageState object). Opaque
+ * to the runner — persisted and returned verbatim, never inspected or masked here (D-14).
+ */
+type StorageStateBlob = unknown;
+/**
+ * The evidence-safe reference to a persisted storage state (D-14). This — and ONLY this — is
+ * what may transit into `StepEvidence`/the handoff: the name plus a one-way fingerprint of the
+ * stored blob. The blob itself never leaves the store.
+ */
+interface StorageStateReference {
+    /** The caller-supplied slot name (as authored; the store slugs it before it becomes a path). */
+    name: string;
+    /** One-way fingerprint of the stored blob (the 343 `fingerprint()` idiom — identity, not the data). */
+    fingerprint: string;
+}
+/**
+ * The runner-facing storage-state persistence seam (D-14). A runner-local implementation owns
+ * the `.agent-qa/storage-states/` filesystem writes; the loop injects it beside `cache` and
+ * records only the returned reference.
+ */
+interface StorageStatePort {
+    /**
+     * Persist the raw storage-state blob under `name` and return the evidence-safe reference.
+     * The name is slugged traversal-safe before it becomes a filename (T-360-03).
+     */
+    save(name: string, state: StorageStateBlob): Promise<StorageStateReference>;
+    /**
+     * Load the raw blob previously saved under `name`, or `undefined` when no such slot exists
+     * (a missing name is never an error).
+     */
+    load(name: string): Promise<StorageStateBlob | undefined>;
+}
+
+type RecordAdmission = ServingAdmissionDecision;
+type ServingExposureSurface = ServedAdmissionSurface;
+interface ServingExposure {
+    readonly surface: ServingExposureSurface;
+    readonly turnOrdinal: number;
+}
+interface RecordLedger {
+    /** Preview without mutation so channel-local and combined-turn checks can commit atomically. */
+    inspect(record: ServingRecordMetadata): RecordAdmission;
+    admit(record: ServingRecordMetadata, exposure?: ServingExposure): RecordAdmission;
+    resetTurn(seedRecords: readonly ServingRecordMetadata[], exposure?: ServingExposure): void;
+    /** Optional-compatible evidence seam; production ledgers provide both methods. */
+    beginStepEvidence?(): void;
+    drainEvidenceEvents?(): ServedAdmissionEvent[];
+    size(): number;
+    spent(): number;
+}
+interface ProductionRecordLedger extends RecordLedger {
+    beginStepEvidence(): void;
+    drainEvidenceEvents(): ServedAdmissionEvent[];
+}
+/**
+ * One turn-time authority for the global distinct-record and combined dominance walls. Channel 1
+ * seeds exact rendered material; Channel 3 and Channel 2 then charge every exposure against the
+ * same source/cluster maps. Re-emphasizing an id remains free only for the DISTINCT slot — its
+ * repeated bytes still count toward budget and dominance.
+ */
+declare function createRecordLedger(input: {
+    cap: number;
+    budget: number;
+    seedRecords: readonly ServingRecordMetadata[];
+}): ProductionRecordLedger;
+
+/** Compression output — v1's CompressResult shape (Pitfall 9). */
+interface CompressedScreenshot {
+    buffer: Buffer;
+    imageWidth: number;
+    imageHeight: number;
+}
+/**
+ * Screenshot compression + dimension port. The core-side implementation owns
+ * `sharp` (storageNeutral forbids it in runner, Pitfall 9). `compress` covers the
+ * LLM-planner compression call site; `dimensions` covers the action-space-width
+ * metadata fallback done inline via `sharp(screenshot).metadata()` at v1
+ * loop.ts:199-201. The loop applies `stampCaptureMode` itself (runner-owned since 352).
+ */
+interface ScreenshotCompressor {
+    compress(screenshot: Buffer, options: {
+        effectiveResolution: number;
+        maxBytes?: number;
+        actionSpaceWidth: number;
+    }): Promise<CompressedScreenshot>;
+    dimensions(screenshot: Buffer): Promise<{
+        width: number;
+        height: number;
+    }>;
+}
+/**
+ * Structural secret-lookup port. The concrete `SecretStore` (moved into runner in
+ * this plan, task 2) satisfies it by construction; `resolveSecretTemplatesInValue`
+ * consumes it. Named distinctly from the concrete class to avoid a barrel collision.
+ */
+interface SecretResolver {
+    get(name: string): string | undefined;
+    require(name: string): string;
+    has(name: string): boolean;
+    /**
+     * OPTIONAL name enumeration (PROC-02 · 381 D-08). The loop assembles the procedure
+     * consult's binding-NAME set from the ports already in scope; secret template names are
+     * part of that set so secret-parameterized procedures stay replay-eligible. Names only —
+     * the callback receives the value because the concrete `SecretStore.forEachSecret`
+     * already carries it, but the loop only ever collects the name; no value crosses the
+     * reader port in any form. Absent implementations simply contribute no names.
+     */
+    forEachSecret?(callback: (name: string, value: string) => void): void;
+}
+/** Structural secret-redactor port — the concrete `SecretRedactor` satisfies it. */
+interface SecretRedactorPort {
+    redactString(value: string): string;
+}
+/**
+ * Structural run-scoped working-memory port (WM-01 · D-11/D-12). The concrete
+ * `WorkingMemoryStore` (working-memory/store.ts) satisfies it by construction; declared
+ * structurally here (the SecretResolver naming precedent) so the ports module never imports the
+ * concrete class. `capture` writes verbatim entries (registered secrets redacted at capture);
+ * `entries` returns the whole set in capture order; `dispose` empties it at run end.
+ */
+interface WorkingMemoryPort {
+    capture(entries: readonly WorkingMemoryEntry[], ctx?: {
+        test?: number;
+        step?: number;
+    }): void;
+    entries(): WorkingMemoryEntry[];
+    dispose(): void;
+}
+/** Minimal scoped-logger surface the loop uses; core's LogManager satisfies it. */
+interface LoopScopedLogger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error?(message: string, meta?: Record<string, unknown>): void;
+}
+interface LoopLogger {
+    createScopedLogger(scope: string): LoopScopedLogger | undefined;
+}
+/**
+ * Runner-local structural copy of model's DegradeOptions (D-05/D-07). Runner cannot
+ * import the model package, so the shape is duplicated here; Plan 05's cli conformance
+ * proof asserts model's `DegradeOptions` structurally matches this. Policy-free: the
+ * caller (Phase 355) supplies the concrete budget + pin predicate.
+ */
+interface RunnerDegradeOptions {
+    budget: number;
+    pin?: (message: ModelMessage, index: number) => boolean;
+}
+/**
+ * Runner-local structural copy of model's DegradeOutcome (D-09). `ok:true` carries the
+ * fitted messages; `ok:false` is the structured cannot-fit outcome (system + final +
+ * pinned content alone exceed the budget) — degrade never throws and never violates a pin.
+ */
+type RunnerDegradeOutcome = {
+    ok: true;
+    messages: ModelMessage[];
+} | {
+    ok: false;
+    reason: 'pinned-content-exceeds-budget';
+    messages: ModelMessage[];
+};
+/**
+ * Provider-neutral token-accounting port (D-05/D-07) — the 354↔355 seam. A types-only
+ * structural duplicate of model's `TokenAccounting` (accounting/types.ts): runner cannot
+ * import model, so the shape is mirrored here and message types are imported from `'ai'`
+ * only (never `@ai-sdk/*`, PROVIDER_ORCHESTRATION_ALLOWED). Policy-free — prompt tokens
+ * only. This plan declares the seam; Phase 355 wires estimate/degrade consumption.
+ */
+interface TokenAccounting {
+    estimate(messages: ModelMessage[]): number;
+    recordUsage(usage: LanguageModelUsage, messages: ModelMessage[]): void;
+    getCeilings(): {
+        contextWindow: number;
+        maxOutput: number;
+    };
+    degrade(messages: ModelMessage[], options: RunnerDegradeOptions): RunnerDegradeOutcome;
+}
+/**
+ * D-02 run-scoped event-emit seam. The loop emits `stepFinalized`/`subActionRecorded` at the
+ * moment they occur (live semantics from day one) — the bus assigns `seq` centrally. Both legs
+ * are fire-and-forget SYNCHRONOUS void: the loop must NEVER await telemetry (D-02/D-07). Follows
+ * the optional-port idiom (masking/workingMemory): structural, optional on {@link LoopPorts},
+ * optional-chained at the emit site, never throw-on-absent (D-05 degrade-when-absent). The
+ * concrete curry lands at the run shell (`MemberEventSink.loopEmitFor`); the port survives 363's
+ * migration unchanged.
+ */
+interface LoopEventEmitPort {
+    /**
+     * 363 D-01: the additive-optional `extra` carries the StepResult-derived
+     * `{status, durationMs, error}` the reporters need (RESEARCH Q1 parity). Sourced from the
+     * runner `StepResult` at the loop's single terminal `finish()` funnel — NOT fields on the §A8
+     * `StepEvidence` DTO (Pitfall 2). `error` is masked at the sink chokepoint (T-363-05). Absent
+     * ⇒ the base evidence-only payload, source-compatible with pre-363 callers.
+     */
+    stepFinalized(evidence: StepEvidence, extra?: {
+        status?: StepFinalizedPayload['status'];
+        durationMs?: number;
+        error?: string;
+        /**
+         * 405 D-05: the step's measured usage, from the loop's own planner + verifier tally.
+         * Absent when nothing was measured — the loop's `tokenUsage()` already answers
+         * `undefined` in that case, so absence is produced, never fabricated here.
+         */
+        tokenUsage?: StepFinalizedPayload['tokenUsage'];
+        /** Finished member scope, including late extraction; overrides the legacy loop tally. */
+        modelObservations?: ModelUsageObservations;
+        evidence?: StepFinalizedPayload['evidence'];
+        variableSnapshot?: StepFinalizedPayload['variableSnapshot'];
+    }): void;
+    subActionRecorded(evidence: SubActionEvidence, subActionIndex: number, 
+    /** Capture-time ARIA state; the projector appends its ref beside the decision screenshot. */
+    extra?: {
+        ariaEvidence?: SubActionRecordedPayload['ariaEvidence'];
+        recordingOffsetMs?: number;
+    }): void;
+}
+/**
+ * Run-scoped content-addressed evidence artifact store (CASS-02). Storage-neutral: a
+ * runner-local `FsEvidenceArtifactStore` owns the sha-keyed blob persistence; the runner
+ * declares only the shape. `persistDecisionScreenshot` returns the identity for the exact
+ * byte payload so a decision screenshot becomes addressable by `ArtifactRef.sha`; `getBlob`
+ * serves those bytes back, letting a host adapter satisfy eval's structurally identical
+ * `ArtifactSource` without a runner-to-eval dependency. Both legs are synchronous.
+ */
+interface PersistedRecording {
+    ref: RecordingRef;
+    byteLength: number;
+}
+interface EvidenceArtifactStorePort {
+    persistDecisionScreenshot(bytes: Uint8Array): ArtifactRef;
+    /** Already live-masked JSON only. Optional for existing screenshot-only hosts. */
+    persistEvidenceDocument?(document: Exclude<EvidenceDocument, {
+        kind: 'variables';
+    }>): ArtifactRef;
+    hasBlob?(sha: string): boolean;
+    getBlob(sha: string): Uint8Array | undefined;
+    persistRecording?(stagingPath: string): PersistedRecording;
+    blobSize?(sha: string): number | undefined;
+    readBlobRange?(sha: string, start: number, end: number): Uint8Array | undefined;
+    discardRecording?(stagingPath: string): void;
+}
+/**
+ * The member-scoped procedure-flow carry (F-381-51-1 · 381 D-09): the replay position a
+ * completed test step hands to the NEXT test step so a committed multi-step flow replays
+ * exactly one body step per test step. Transports ONLY the consult match, the parsed body
+ * payload, and the cursor — never a pre-resolved ref, never a screen: every carried body
+ * step re-earns dispatch through the full fresh-screen descriptor/guard/page-anchor/
+ * grounding-gate ladder at its own test step (D-10 — a stored action can never dispatch
+ * against a screen its guards did not pass on at that step).
+ */
+interface ProcedureFlowCarry {
+    match: ProcedureMatch;
+    payload: ProcedureBodyPayload;
+    nextIndex: number;
+}
+/** 439 D-04: a completed download from an earlier step of this test, labelled by its producer. */
+interface CarriedDownload {
+    stepNumber: number;
+    /** 1-based position of the producing action in its step. */
+    actionIndex: number;
+    evidence: DownloadEvidence;
+}
+/** 439 D-04: the latest app clipboard write from an earlier step of this test. */
+interface CarriedClipboard {
+    stepNumber: number;
+    actionIndex: number;
+    evidence: ClipboardEvidence;
+}
+interface CarriedArtifacts {
+    downloads: CarriedDownload[];
+    clipboard?: CarriedClipboard;
+}
+/**
+ * The runner-owned port bundle the loop executes against — successor to v1's
+ * AgentLoopConfig (core types.ts:66-104), minus the D-10 healing/attempt-limit
+ * fields and minus the v1 cache-key inputs (those move behind the cache port).
+ */
+interface LoopPorts {
+    recordingZeroMs?: number;
+    adapter: PlatformAdapter;
+    planner: Planner;
+    verifier?: Verifier;
+    /**
+     * Redesigned per-key cache port (D-11): get/set/invalidate over a branded CacheKey,
+     * descriptor-only value. Plan 05's FsActionCache implements it; injected at the Plan 06
+     * CLI composition root. Absent ⇒ every step misses (no cache), never throws (D-05).
+     */
+    cache?: ActionPlanCache;
+    /**
+     * D-05 declared decision context for both model roles. Composition roots pass the
+     * same profile objects to the planner/verifier constructors and this recording lane;
+     * the loop never derives model facts from a model handle. Absent preserves the
+     * provider-neutral degrade-when-absent contract.
+     */
+    modelProfiles?: {
+        planner: DeclaredModelProfile;
+        verifier?: DeclaredModelProfile;
+    };
+    /**
+     * D-16 once-per-member digest of the complete bound tool surface. It remains a
+     * separate optional port because tool attribution is distinct from model identity;
+     * absent callers continue without evidence stamping and never throw.
+     */
+    toolSchemaDigest?: string;
+    compressor?: ScreenshotCompressor;
+    /** D-05 optional read-only knowledge reader — the loop degrades gracefully when absent. */
+    knowledgeReader?: KnowledgeHintReader;
+    /**
+     * 407 D-13/D-17 (2026-08-29) — the HOST's retrieval rung, resolved ONCE at the composition
+     * root by knowledge-local's single `resolveRetrievalRung`, never re-probed per step. It
+     * crosses as the schema type because the runner never imports knowledge-local (validate:arch
+     * enforces that); a promise because the resolver's embedder probe can cost a model load and
+     * overlapping it with run start keeps the probe off the critical path.
+     *
+     * It describes the ladder the machine was on when this run was served — NOT how this brief was
+     * ranked. Absent ⇒ no rung is stamped (D-05 degrade-when-absent); a rejection stamps nothing
+     * and never fails a step; and a rung is never stamped onto a step no reader served (D-16 —
+     * "no knowledge reader bound is not a rung").
+     */
+    knowledgeRetrievalRung?: Promise<RecordedRetrievalRung>;
+    /**
+     * F-381-51-1 · D-09 member-scoped carry cell (the recordLedger shared-mutable-object
+     * precedent): the caller owns ONE cell per test member and threads the SAME object into
+     * every per-step ports literal. The loop TAKES the carry at step start (reading and
+     * immediately emptying the cell) and re-arms it only after the step's verifier accepts a
+     * successful replayed step with body steps remaining — take-then-rearm, the D-11 one-shot
+     * law extended across the step boundary: every other exit (guard miss, execution failure,
+     * verifier rejection, policy denial, step failure, abort, exhaustion) leaves the cell
+     * empty. Loop-side state only: never serialized, never recorded into evidence or the
+     * handoff, never crosses a test boundary. Absent ⇒ no cursor crosses steps (D-05
+     * degrade-when-absent).
+     */
+    procedureFlow?: {
+        carry?: ProcedureFlowCarry;
+    };
+    /**
+     * 439 D-04 member-scoped carry cell, the `procedureFlow` precedent: the caller owns ONE cell per
+     * test member and threads the SAME object into every per-step ports literal. The loop renders its
+     * items into the step record's carried lines at step start, and at the step's end appends the
+     * step's completed downloads and replaces the clipboard with its latest write. Loop-side state
+     * only: never serialized, never recorded into evidence or the handoff, never crosses a test
+     * boundary. Absent ⇒ nothing carries (the live editor).
+     */
+    carriedArtifacts?: CarriedArtifacts;
+    /**
+     * D-02/D-15/D-17 knowledge budgets are computed beside model token accounting at the
+     * composition root and arrive here as plain numbers. The provider-neutral loop never derives
+     * model ceilings or imports token-accounting policy; absent bindings use provisional floors.
+     */
+    knowledgeBudgets?: {
+        brief: number;
+        searchResults: number;
+        caution: number;
+        readBody: number;
+        recordCap: number;
+    };
+    /** D-21 run-fixed build ordinal copied into ServedBrief attribution when a reader is bound. */
+    knowledgeAsOfBuild?: number;
+    /**
+     * D-17 loop-controlled turn ledger. A composition root that registers Channel-2 tools binds
+     * the same object into their closures; the loop owns reset timing and Channel 3 consults it
+     * directly. Absent is legal and creates a step-local ledger for Channel-1 accounting only.
+     */
+    recordLedger?: RecordLedger;
+    /**
+     * D-11 Channel-2 turn reset owned by the memory-tool wrapper. The loop invokes it only after
+     * reseeding the shared distinct-record ledger from the frozen brief, so both ledgers begin the
+     * live planning turn from the same boundary.
+     */
+    beginMemoryTurn?: (scope?: ScopeKey, exposedIds?: readonly RecordId[]) => void;
+    /** Consume the successful direct reads served during the current live planning turn. */
+    drainMemoryReadTraces?: () => ReadTrace[];
+    plannerConfig?: PlannerConfig;
+    /** Wall-clock timeout for a single step (ms). 0 or undefined = no timeout. */
+    stepTimeout?: number;
+    logger?: LoopLogger;
+    logCapture?: {
+        console?: boolean;
+        network?: boolean;
+    };
+    vision?: {
+        screenshotSize?: number;
+        effectiveResolution?: number;
+    };
+    visionGate?: {
+        attachImage: boolean;
+        captureMode: 'full' | 'textOnly';
+        promptNote: string;
+    };
+    /** Pitfall 8 — setVariable executes via this callback, NOT the adapter. */
+    onSetVariable?: (name: string, value: string) => void;
+    /** Pitfall 1 — path resolution stays core-side, injected pre-resolved into the loop. */
+    resolveUploadPath?: (rawPath: string) => string;
+    abortSignal?: AbortSignal;
+    secretStore?: SecretResolver;
+    secretRedactor?: SecretRedactorPort;
+    /**
+     * WM-01 run-scoped working-memory seam (D-11/D-12). The concrete `WorkingMemoryStore` is
+     * created at the CLI composition root and injected here; Phase 361 rebinds this exact seam onto
+     * `RunSession` (the knowledgeReader idiom). Unbound ⇒ the loop runs memory-less: no capture, an
+     * empty served set — it never throws (D-05 degrade-when-absent).
+     */
+    workingMemory?: WorkingMemoryPort;
+    /**
+     * D-14 storage-state persistence seam (Phase 360). The runner-local `FsStorageStateStore` is
+     * constructed run-scoped at the CLI/dashboard composition roots and injected here; the seam
+     * strips the raw blob from the recorded result and records only `{ name, fingerprint }`. Unbound
+     * ⇒ a `storageState` action degrades to a §7.1 persistence-unavailable error (never throws, D-05).
+     */
+    storageState?: StorageStatePort;
+    /**
+     * D-16 injectable unique-value suffix generator (353 K=2 determinism). Absent ⇒ the seam uses
+     * `defaultUniqueValueGenerator` (timestamp + entropy). Tests inject a fixed generator for
+     * deterministic minted values; production leaves it unbound.
+     */
+    uniqueValueGenerator?: UniqueValueGenerator;
+    /**
+     * D-06 optional pre-prompt blob-guard — bounds a single one-shot structured tool-output
+     * value before it lands in the sub-action history / next planning turn. A pure signature
+     * (no `ai`/model types, zero arch risk). Composition roots that depend on model may inject
+     * model's canonical `guardBlob`; the loop degrades to a runner-local fallback when absent.
+     */
+    guardBlob?: (value: unknown) => string | undefined;
+    /**
+     * D-02 run-scoped event-emit seam. Bound by the run shell (per-step curry via
+     * `MemberEventSink.loopEmitFor`) so the loop emits `stepFinalized`/`subActionRecorded` live;
+     * absent ⇒ the loop runs telemetry-less (no emit), never throws (D-05 degrade-when-absent).
+     */
+    events?: LoopEventEmitPort;
+    /**
+     * D-20 real config digests, so the loop can key the cache on what the run actually keyed on
+     * (consumed in Plan 08). Type-imported from the run layer; absent ⇒ the existing key material
+     * is used unchanged.
+     */
+    configDigests?: ConfigDigests;
+    /**
+     * CASS-02 run-scoped decision-screenshot byte store. The shell hands one store instance to
+     * every member; the loop mints an `ArtifactRef` for captured screenshot bytes through it.
+     * Absent ⇒ a legal memory-only / test-harness state (no persistence), never throws (D-05).
+     */
+    evidenceArtifacts?: EvidenceArtifactStorePort;
+}
+
+declare function executeStep(stepInstruction: string, ports: LoopPorts, context: StepContext): Promise<StepResult>;
+
+/**
+ * Capture-location context stamped onto each entry (D-11): the whole run set is served every
+ * turn, so the planner weighs relevance itself — these mark where the entry was captured, they
+ * are not a filter rule.
+ */
+interface WorkingMemoryProvenanceContext {
+    test?: number;
+    step?: number;
+}
+/**
+ * Run-scoped verbatim working memory: a plain Map keyed by entry key, latest-wins on
+ * re-capture (D-12 — one key ⇒ one current value, the OTP-resend reality), whole-set recall in
+ * capture order (D-11 — no filtering, no search). Registered secrets are redacted at capture
+ * (Pitfall 7 boundary 1); every other value stays verbatim.
+ */
+declare class WorkingMemoryStore {
+    private readonly redactor?;
+    private readonly store;
+    constructor(redactor?: SecretRedactorPort | undefined);
+    /**
+     * Capture verbatim entries. Each item is validated against workingMemoryEntrySchema (closed
+     * enums reject unknown kind/provenance at the boundary, V5), its value redacted for registered
+     * secrets only, and stamped with the capture location. Re-capturing an existing key overwrites
+     * its value (D-12 latest-wins); the key's original capture position is preserved.
+     */
+    capture(entries: readonly WorkingMemoryEntry[], ctx?: WorkingMemoryProvenanceContext): void;
+    /** The whole run-scoped set in capture order (D-11 — no filtering, no search). */
+    entries(): WorkingMemoryEntry[];
+    /** Empty the store at run end (WM-02 disposal; the redacted flush is composed elsewhere). */
+    dispose(): void;
+}
+
+type AgentAbortScope = 'test' | 'step';
+interface AgentTimeoutAbortReason {
+    type: 'agent-qa-timeout';
+    scope: AgentAbortScope;
+    timeoutMs: number;
+    message: string;
+}
+declare function createTimeoutAbortReason(scope: AgentAbortScope, timeoutMs: number): AgentTimeoutAbortReason;
+/**
+ * True iff `message` is the message createTimeoutAbortReason('test', ms) mints for
+ * some ms — the D-16 member-timeout signal. Rejects the 'step'-scope variant (a step
+ * timeout is an ordinary failure) and any arbitrary text.
+ *
+ * WHY match on the message string: the AgentTimeoutAbortReason object does NOT survive
+ * onto TestResult — the only trace that reaches verdict derivation is a failed step
+ * whose `error` equals this minted message (RESEARCH Q3). This matcher is the one place
+ * that knowledge lives, exported beside the sole mint site so the format stays
+ * single-sourced.
+ */
+declare function isTestTimeoutMessage(message: string): boolean;
+declare function getTimeoutAbortReason(signal: AbortSignal | undefined): AgentTimeoutAbortReason | undefined;
+declare function withAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+
+type ToolCategory = 'action' | 'file' | 'network';
+interface ToolDefinition<T extends z.ZodType = z.ZodType> {
+    id: string;
+    type: string;
+    surface: Surface;
+    exposed?: boolean;
+    description: string;
+    category: ToolCategory;
+    schema: T;
+    /** Advisory audit/confirmation hint only; must not gate platform slices. */
+    destructive?: boolean;
+    /** Advisory audit/trace hint only; must not gate platform slices. */
+    readOnly?: boolean;
+}
+
+declare const EXPOSURE: Record<Platform, ReadonlySet<Surface>>;
+declare class ToolRegistry {
+    private tools;
+    register<T extends z.ZodType>(def: ToolDefinition<T>): this;
+    get(id: string): ToolDefinition | undefined;
+    getAll(): ToolDefinition[];
+    getForPlatform(platform: Platform): ToolDefinition[];
+    getSchema(id: string): z.ZodType;
+    generateDocs(platform?: Platform): string;
+}
+declare const defaultRegistry: ToolRegistry;
+
+/**
+ * K — the per-turn non-action tool-call budget (D-06/D-10). Channel 2's designed
+ * search→read sequence needs two calls, and one retry pair must fit in the same turn.
+ * This remains an internal provisional constant, injectable via
+ * ExecutePlanningTurnOptions.budget for tests only. Do NOT promote it to user-facing
+ * config or thread it through LoopPorts / any config schema.
+ */
+declare const DEFAULT_NON_ACTION_TOOL_BUDGET = 4;
+/**
+ * A caller-registered non-action tool. `tool` is the `ai` definition merged into the
+ * always-send-all slice; `execute` runs the call and returns a JSON-serializable
+ * result appended to the conversation as a tool message. Zero of these ship in 353;
+ * tests register fakes to exercise the machinery (D-07).
+ */
+interface NonActionToolHandler {
+    tool: Tool;
+    execute(args: Record<string, unknown>): Promise<unknown> | unknown;
+}
+type NonActionToolMap = Record<string, NonActionToolHandler>;
+/**
+ * An ordered record of one executed non-action tool call within a planning turn
+ * (§B1). Exchanges persist on SubActionEvidence for successful decisions (INST-01,
+ * D-01) and PlanningFailureEvidence for failed turns (D-03).
+ */
+type ToolExchange = ToolExchangeEvidence;
+type PlanningTurnFailureReason = 'no_action_tool_called' | 'non_action_tool_budget_exhausted' | 'ungroundable_action' | 'planning_limit_reached';
+/**
+ * The in-turn groundability verdict for a parsed action (D-09). Returned by the
+ * injected `groundability` callback the caller (LLMPlanner) builds from the Plan-04
+ * grounding gate + the in-scope screenState — the tool-loop stays gate-agnostic and
+ * NEVER imports `grounding/` itself.
+ *
+ * `ok: true` may optionally carry the gate's fully-grounded execution-shape `action`
+ * (ref, never a descriptor) and its §A8 `attempts` trail; when present the turn swaps
+ * them onto the returned plan so the resolved action + evidence ride to executeStep.
+ * When omitted (e.g. a test seam that only signals groundability) the parsed plan is
+ * returned unchanged. `ok: false` carries the §7.1 error text injected back into the
+ * SAME conversation as an error-text tool result for the model's one-shot correction.
+ */
+type GroundabilityResult = {
+    ok: true;
+    action?: Record<string, unknown>;
+    attempts?: GroundingAttempt[];
+    statedTargets?: StatedTargets;
+} | {
+    ok: false;
+    message: string;
+};
+/** The injected groundability callback: parsed action → groundability verdict (D-09). */
+type GroundabilityCallback = (plan: ActionPlan) => GroundabilityResult;
+interface PlanningTurnSuccess {
+    ok: true;
+    plan: ActionPlan;
+    exchanges: ToolExchange[];
+    tokenUsage?: TokenUsage;
+    callRecord?: ModelCallRecord;
+}
+interface PlanningTurnFailure {
+    ok: false;
+    reason: PlanningTurnFailureReason;
+    message: string;
+    exchanges: ToolExchange[];
+    tokenUsage?: TokenUsage;
+    callRecord?: ModelCallRecord;
+}
+type PlanningTurnResult = PlanningTurnSuccess | PlanningTurnFailure;
+interface ExecutePlanningTurnOptions {
+    model: LanguageModel;
+    /** Registry backing toolCallToActionPlan (the turn's termination projection). */
+    registry: ToolRegistry;
+    /** The full v45 action slice (buildTools output) — always sent (always-send-all). */
+    actionTools: ToolSet;
+    /**
+     * System prompt — a single string, or the Phase 355 [stable, context, volatile]
+     * tier array the caller assembles (D-15). Passed through to generateText untouched;
+     * the tool-loop applies no clamp/degrade policy of its own.
+     */
+    system: string | Array<SystemModelMessage>;
+    /** The initial user message(s): text and optional image, built by the caller. */
+    messages: ModelMessage[];
+    /** Caller-registered non-action tools. Empty in production (D-07). */
+    nonActionTools?: NonActionToolMap;
+    /** K override for tests (D-06). Defaults to DEFAULT_NON_ACTION_TOOL_BUDGET. */
+    budget?: number;
+    /**
+     * D-09 in-turn grounding feedback. When present, a parsed action call is grounded by
+     * this injected callback after `toolCallToActionPlan` succeeds. A failure appends the
+     * §7.1 error text as an error-text tool result in the SAME conversation with EXACTLY
+     * ONE retry (a turn-local one-shot flag, never a counter — LOOP-02); a second
+     * consecutive grounding failure returns a structured `'ungroundable_action'` failure.
+     * The retry neither consumes nor bypasses the ≤K non-action budget (Pitfall 8). When
+     * absent the turn behaves exactly as the 353 bounded loop (back-compat within phase).
+     */
+    groundability?: GroundabilityCallback;
+    /**
+     * Dynamic output cap (CTXB-04) computed by the caller's clamp helper and passed
+     * through to generateText. `undefined` is a valid no-op passthrough — the tool-loop
+     * computes no clamp of its own (D-15/Pitfall 5).
+     */
+    maxOutputTokens?: number;
+    /**
+     * Optional sampling parameters applied at the model call site (D-10/D-11). Every
+     * field is optional and absence preserves the provider default. `maxOutputTokens`
+     * is deliberately excluded because the output ceiling remains clamp-owned.
+     */
+    sampling?: SamplingParams;
+    /**
+     * 436 D-08: when bound, every model call of the turn is debited before it is made; a refused
+     * debit ends the turn with `planning_limit_reached` and no model call.
+     */
+    planningCallGate?: PlanningCallGate;
+    abortSignal?: AbortSignal;
+    logger?: LoopScopedLogger;
+}
+declare function executePlanningTurn(options: ExecutePlanningTurnOptions): Promise<PlanningTurnResult>;
+
+/**
+ * Structured planning-turn failure used to preserve failed-turn evidence across
+ * the planner's throw-based public contract (D-03).
+ */
+declare class PlanningTurnError extends Error {
+    readonly reason: PlanningTurnFailureReason;
+    readonly exchanges: ToolExchangeEvidence[];
+    readonly callRecord?: ModelCallRecord;
+    constructor(reason: PlanningTurnFailureReason, message: string, exchanges: ToolExchangeEvidence[], callRecord?: ModelCallRecord);
+}
+/**
+ * 436 D-08/D-12: the step's planning-turn limit refused a planner model call. Never a planning
+ * failure; the loop ends the step with its typed limit stop.
+ */
+declare class PlanningLimitReachedError extends Error {
+    readonly exchanges: ToolExchangeEvidence[];
+    readonly callRecord?: ModelCallRecord;
+    constructor(exchanges: ToolExchangeEvidence[], callRecord?: ModelCallRecord);
+}
+declare class LLMPlanner implements Planner {
+    private model;
+    private platform;
+    private logger?;
+    private capabilityNotes?;
+    private accounting;
+    private profile?;
+    private nonActionTools?;
+    constructor(model: LanguageModel, platform: Platform | undefined, logger: LoopScopedLogger | undefined, capabilityNotes: string | undefined, accounting: TokenAccounting, profile?: DeclaredModelProfile, nonActionTools?: NonActionToolMap);
+    private buildSystemTiers;
+    plan(step: string, screenState: ScreenState, context: StepContext, abortSignal?: AbortSignal): Promise<PlanResult>;
+}
+
+declare const VerificationResultSchema: z.ZodObject<{
+    conditions: z.ZodArray<z.ZodObject<{
+        quote: z.ZodString;
+        verdict: z.ZodEnum<{
+            unverified: "unverified";
+            met: "met";
+            "not-met": "not-met";
+            inconclusive: "inconclusive";
+        }>;
+        needs: z.ZodEnum<{
+            visual: "visual";
+            none: "none";
+            file: "file";
+            persistence: "persistence";
+            "limit-max": "limit-max";
+            "limit-min": "limit-min";
+        }>;
+        controlRef: z.ZodString;
+        file: z.ZodObject<{
+            name: z.ZodString;
+            match: z.ZodEnum<{
+                exact: "exact";
+                none: "none";
+                lines: "lines";
+            }>;
+            text: z.ZodString;
+        }, z.core.$strip>;
+        citations: z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<{
+                action: "action";
+                "start-screen": "start-screen";
+                "final-screen": "final-screen";
+                read: "read";
+                carried: "carried";
+                screenshot: "screenshot";
+            }>;
+            quote: z.ZodString;
+        }, z.core.$strip>>;
+        reasoning: z.ZodString;
+    }, z.core.$strip>>;
+    dialogs: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        account: z.ZodEnum<{
+            "bears-on-condition": "bears-on-condition";
+            requested: "requested";
+            unrelated: "unrelated";
+        }>;
+        reasoning: z.ZodString;
+    }, z.core.$strip>>;
+    isAppError: z.ZodBoolean;
+    reasoning: z.ZodString;
+}, z.core.$strip>;
+/** Closed judgment schema — a boolean verdict + rationale, never free text (D-06). */
+declare const AiJudgmentResultSchema: z.ZodObject<{
+    verdict: z.ZodBoolean;
+    rationale: z.ZodString;
+}, z.core.$strip>;
+declare class LLMVerifier implements Verifier {
+    private model;
+    private accounting;
+    private profile?;
+    constructor(model: LanguageModel, accounting: TokenAccounting, profile?: DeclaredModelProfile);
+    verify(step: string, before: ScreenState, after: ScreenState, action: Action, screenshot?: Buffer, abortSignal?: AbortSignal, promptNote?: string, bulkCompletionPredicate?: string, authorContext?: VerifierAuthorContext, operationEvidence?: OperationEvidence, record?: VerifierStepRecord): Promise<VerifyResult>;
+    private runVerification;
+    /**
+     * D-05/D-06/D-09 AI judge lane. A SINGLE structured call over the current observation that
+     * returns the verdict + rationale. `opts` carries the requested-but-deferred M3/M4 knobs
+     * (consensus/video/effort) so demand is visible (D-09) — accepted, never honored, never an
+     * error; the loop records them into the AiJudgment evidence block. Empty/overflow model output
+     * degrades to a structured `verdict:false` failure (the verify() never-crash posture) — abort
+     * is the only rethrow.
+     */
+    judgeClaim(claim: string, screen: ScreenState, opts?: Record<string, unknown>): Promise<{
+        verdict: boolean;
+        rationale: string;
+    }>;
+    /**
+     * D-07 AI extraction lane. A SINGLE structured call whose output schema is derived from the
+     * extractAI request's declared field list (each field a string). Returns the extracted field
+     * map; the loop writes it into run-scoped working memory and degrades a `scope:'global'`
+     * request to the same run-scoped write (D-07 — no durable-memory port in M1). Empty/overflow
+     * output degrades to an empty extraction (never a throw) — abort is the only rethrow.
+     */
+    extractData(query: string, screen: ScreenState, opts?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private runStructured;
+}
+
+declare class AssertionEvaluator implements Asserter {
+    evaluate(assertion: AssertionInput, screenState: ScreenState): Promise<AssertionResult>;
+    private evaluateTextPresence;
+    private evaluateElementVisibility;
+    private evaluateUrlMatch;
+    private evaluateElementCount;
+}
+declare class LLMAssertionEvaluator implements Asserter {
+    private model;
+    constructor(model: LanguageModel);
+    evaluate(assertion: AssertionInput, screenState: ScreenState): Promise<AssertionResult>;
+}
+declare function createAsserter(model?: LanguageModel): Asserter;
+
+type VariableSource = 'env' | 'inline' | 'suite' | 'cli' | 'capture' | 'hook' | 'step';
+interface VariableStoreOptions {
+    onWarn?: (message: string) => void;
+}
+declare class VariableStore {
+    private storage;
+    private onWarn?;
+    constructor(options?: VariableStoreOptions);
+    set(name: string, value: string, source?: VariableSource): void;
+    get(name: string): string | undefined;
+    has(name: string): boolean;
+    getSource(name: string): VariableSource | undefined;
+    getAll(): Map<string, string>;
+    setAll(vars: Record<string, string>, source?: VariableSource): void;
+    snapshot(): Record<string, {
+        value: string;
+        source: VariableSource;
+    }>;
+}
+
+interface InterpolationWithProvenance {
+    text: string;
+    /**
+     * The bindings that actually resolved, one entry per DISTINCT name in first-occurrence
+     * order. Unresolved patterns and the skipped `{{secret:...}}` template contribute
+     * nothing. Values are recorded VERBATIM — see the masking prohibition on
+     * `StepEvidence.interpolatedVariables` (masking here would break the emit fold's
+     * exact-match classification and reintroduce G-381-3).
+     */
+    substitutions: InterpolatedVariable[];
+}
+/**
+ * The single replacement implementation (PROC-01 · 381 D-03/D-08). Produces byte-identical
+ * text to the historical `interpolateVariables` while reporting WHICH binding names
+ * produced it, so the name survives the pre-planning interpolation seam into StepEvidence.
+ */
+declare function interpolateVariablesWithProvenance(template: string, store: VariableStore): InterpolationWithProvenance;
+declare function interpolateVariables(template: string, store: VariableStore): string;
+interface UnresolvedTemplate {
+    pattern: string;
+    message: string;
+}
+declare function findUnresolvedTemplates(text: string): UnresolvedTemplate[];
+declare function findBareVariables(text: string): string[];
+
+declare class ExplicitExtractor implements VariableExtractor {
+    extract(input: ExtractorInput, screenState: ScreenState): Promise<CaptureResult>;
+    private extractByRegex;
+    private extractBySelector;
+}
+declare function createExtractor(model?: LanguageModel, method?: string): VariableExtractor;
+
+declare const ExtractionResultSchema: z.ZodObject<{
+    value: z.ZodString;
+    reasoning: z.ZodString;
+}, z.core.$strip>;
+declare class LLMVariableExtractor implements VariableExtractor {
+    private model;
+    constructor(model: LanguageModel);
+    extract(input: ExtractorInput, screenState: ScreenState): Promise<CaptureResult>;
+}
+
+type PromptPlatform = 'web' | 'android' | 'ios';
+/**
+ * v1 token estimate (chars/4). No semantic change (D-04); the TokenAccounting port
+ * lands in Phase 355. Exported here because the prompts module is the token estimate's
+ * sole runner-side consumer.
+ */
+declare function estimateTokens(text: string): number;
+declare function buildSystemPrompt(platform?: PromptPlatform): string;
+/**
+ * CONTEXT tier (D-04): the app-under-test / suite / test framing. Byte-stable per run,
+ * so it sits inside the cached prefix and carries the single Anthropic `cache_control`
+ * ephemeral breakpoint (D-05) — everything at or above this message (stable + context)
+ * is cached once per run at zero incremental cost. A non-Anthropic provider never parses
+ * the `anthropic` namespace, so `providerOptions` is a transparent no-op there.
+ */
+declare function buildContextTier(context: StepContext): SystemModelMessage;
+/**
+ * Render the knowledge brief (the volatile-tier ingredient, D-12) framed as hypotheses
+ * to weigh against the live observation — never as commands (spec §5, L3). Returns ''
+ * when the brief slot is unbound/empty so the volatile tier omits the section entirely
+ * (no 'Knowledge brief' header, no dangling blank line).
+ */
+declare function renderBriefAsHypotheses(brief?: string): string;
+/**
+ * VOLATILE tier (D-04/D-07): the knowledge brief (empty until M2 binds a
+ * KnowledgeHintReader impl, D-12) plus a DATE-GRANULARITY timestamp. Date precision only
+ * — minute/second precision would bust the KV cache (D-07). Carries NO cache breakpoint;
+ * it sits after the breakpoint that lives on the context tier.
+ */
+declare function buildVolatileTier(context: StepContext): SystemModelMessage;
+/**
+ * Per-turn content composer (CTXB-01/CTXB-02 — D-08/D-09/D-12). Decomposes the
+ * per-turn state into a small ordered set of turn messages so 354's degrade() can pin
+ * and proportionally truncate at message granularity rather than shredding one blob.
+ * Order: re-run context → previous steps → sub-action history → failure context →
+ * working memory → latest observation → current instruction (FINAL). Empty slots are
+ * omitted entirely — no blank/degenerate message is pushed (D-12).
+ *
+ * PIN CONTRACT (D-08): the last two messages are the pinned pair — the latest
+ * OBSERVATION (second-to-last) and the CURRENT INSTRUCTION (last, verbatim). The caller
+ * (Plan 05) protects exactly these two via degrade's `pin`; every earlier message is
+ * trim-eligible. All per-turn state lives here and NEVER in the cached system tiers.
+ */
+declare function composeTurnMessages(context: StepContext, screenState: ScreenState): ModelMessage[];
+declare function formatAction(action: Action): string;
+/**
+ * VERIFIER stable tier (CTXB-01 / D-11): the byte-stable verdict-identity block, the verifier's own
+ * cached prefix, identical on every verification call. 439 (D-01, D-05, D-06, D-11, D-18) states
+ * the per-condition contract here: split the step into quoted conditions, judge each from cited
+ * current evidence, and leave the pass to the runner. Arg-less: no per-call inputs; the
+ * screenshot-analysis paragraph rides only a per-call turn that has an image (D-19).
+ */
+declare function buildVerifierStableTier(): string;
+/**
+ * VERIFIER per-call turn content (D-11). Only the per-verification-call bytes: the step
+ * goal, the enriched action description, and the before/after screen states (+ the
+ * optional screenshot note and prompt note). The byte-stable verdict-identity/approach
+ * prose now lives in `buildVerifierStableTier()` (the verifier's own cached prefix), so
+ * it is no longer re-emitted per call.
+ */
+declare function buildVerificationPrompt(step: string, beforeState: ScreenState, afterState: ScreenState, action: Action, hasScreenshot?: boolean, promptNote?: string, bulkCompletionPredicate?: string, authorContext?: VerifierAuthorContext, operationEvidence?: OperationEvidence, record?: VerifierStepRecord): string;
+declare function buildAssertionPrompt(assertion: AssertionInput, screenState: ScreenState): string;
+declare function buildExtractionPrompt(input: ExtractorInput, screenState: ScreenState): string;
+
+declare const CHARS_PER_TOKEN_ESTIMATE = 4;
+declare const OBSERVATION_LINE_PREFIX = "Observation: ";
+type OriginStampedEntry = IndexEntry & {
+    origin?: 'app-observed' | 'user';
+    originClass?: 'agent-observed' | 'agent-verified' | 'import' | 'user';
+};
+/**
+ * Cap learned summaries using JavaScript String.length (UTF-16 code units), the
+ * BRIF-01 length contract. The ellipsis is part of the 140-code-unit maximum.
+ */
+declare function renderCautionSummary(summary: string): string;
+declare function tierForEntry(entry: OriginStampedEntry): string;
+/** Deterministic provisional cost of the exact text handed to the planner. */
+declare function estimateRenderedServingCost(text: string): number;
+interface RenderedCautionLine {
+    summary: string;
+    cost: number;
+}
+/** Render and cost Channel 3 through one projection so framing can never be undercharged. */
+declare function renderCautionLine(entry: IndexEntry): RenderedCautionLine;
+declare function renderBriefLine(entry: IndexEntry): {
+    line: string;
+    briefLine: BriefLine;
+    cost: number;
+};
+declare function renderObservationLine(line: BriefLine): string;
+declare function assembleBriefTiers(policyText: string, userFactSummaries: readonly string[], renderedLines: readonly {
+    line: string;
+    tier: string;
+}[]): {
+    L0: string;
+    L1: string;
+    L2: string;
+};
+
+declare function makeEmptyServedBrief(scope: ScopeKey, asOfBuild: number): ServedBrief;
+declare function foldCacheStatus(subActionCacheFlags: boolean[]): StepEvidence['cacheStatus'];
+declare function collapseAnnotation(action: Action, execResult: ActionResult, viewport: Viewport): ActionAnnotation;
+interface RecordSubActionInput {
+    /** The planner's reasoning/plan string for this sub-action. */
+    plan: string;
+    plannedAction: Action$1;
+    /**
+     * The FULL observed ScreenState the sub-action was planned against (D-15). Pitfall 3:
+     * v1 stored only the tree string — the forbidden shape. elements + refMap ride along.
+     */
+    stateBefore: ScreenState;
+    stateAfter?: ScreenState;
+    /**
+     * The execution result as the schema ActionResult (screenshot may be present here as
+     * bytes; it is structurally excluded by toRecordedActionResult before storage — the
+     * type-level screenshot-never guarantee, T-353-06). annotation is produced via
+     * collapseAnnotation.
+     */
+    result: ActionResult$1;
+    /** v1 per-sub-action cache flag; folded per step by foldCacheStatus at finalize. */
+    cached?: boolean;
+    /**
+     * The §A8 grounding evidence for this sub-action (GROUND-02): the resolved descriptor
+     * plus the per-rung attempt trail (turn gate on the live path, replay resolution on the
+     * cache path, re-ground heal entries on the D-10 path). Present only when the action
+     * carried an element field; the loop redacts the descriptor BEFORE passing it here so a
+     * pre-redaction descriptor never reaches evidence (T-357-02a, the redact-before-record
+     * ordering). Typed via the schema DTO — no runner-local mirror (353 evidence-by-construction).
+     */
+    grounding?: SubActionEvidence['grounding'];
+    /**
+     * The §A8 decision-screenshot ArtifactRef (CASS-02): the identity of the exact final image
+     * bytes the planner saw for this live decision, minted by the run-scoped artifact store.
+     * Absent on cache-served, text-only, unbound-store, or failed-store paths — never fabricated.
+     */
+    decisionScreenshotRef?: SubActionEvidence['decisionScreenshotRef'];
+    /**
+     * Auxiliary §A8 ArtifactRefs already reserved by the schema DTO. Copied verbatim (order and
+     * identity preserved) so the recorder never drops artifact references present on the input.
+     */
+    artifactRefs?: SubActionEvidence['artifactRefs'];
+    /**
+     * Ordered exchanges from this live planning decision (D-01). The loop masks every
+     * string leaf BEFORE passing them here (T-360-01); the recorder never sees raw values.
+     * Present, possibly empty, for live turns and absent for cache replay.
+     */
+    exchanges?: ToolExchangeEvidence[];
+    /**
+     * Final-response enrichment for this live decision (D-05/D-08). The loop passes it
+     * conditionally; structural absence means no live call record was available.
+     */
+    callRecord?: ModelCallRecord;
+    /** 436 D-22: what the action produced outside the page, already masked by the loop. */
+    operationEvidence?: SubActionEvidence['operationEvidence'];
+    healedDispatch?: SubActionEvidence['healedDispatch'];
+}
+declare class EvidenceRecorder {
+    private readonly subActions;
+    private readonly cacheFlags;
+    private servedBrief;
+    /**
+     * KREV-02 · D-13: the serve-time retrieval trace, recorded BESIDE `servedBrief` and never
+     * inside it. `ServedBrief` feeds `computeBriefDigest`, so a trace channel within it would have
+     * rewritten every cassette and acceptance digest in the tree; a sibling field leaves those
+     * bytes untouched, which `evidence-trace.test.ts` proves by digest equality rather than by
+     * asserting that nobody edited the brief.
+     *
+     * Channel 1 is REPLACED on each record (a step replans against the SAME frozen brief, so
+     * appending would duplicate its attributions), while Channel 3 APPENDS — exactly mirroring how
+     * `servedBrief.channel1` and `servedBrief.channel3` themselves behave.
+     */
+    private channel1Trace?;
+    private readonly channel3TraceLines;
+    private readonly channel3Truncated;
+    private selfHeal?;
+    private workingMemory?;
+    private planningFailure?;
+    private reportedValue?;
+    private termination?;
+    private limitStop?;
+    private conditionVerdicts?;
+    private limitUsage?;
+    private operationCapture?;
+    private aiJudgment?;
+    private assertOutcome?;
+    private verdictSource?;
+    private planSource?;
+    private cacheMiss?;
+    /** D-06 run-declared planner context, copied onto every finalized step when bound. */
+    private readonly modelProfile?;
+    /** D-07 verifier identity copied beside every finalized verdict when bound. */
+    private readonly verifierIdentity?;
+    /** D-16 once-per-member bound-surface digest copied onto every finalized step. */
+    private readonly toolSchemaDigest?;
+    /**
+     * 407 D-13: the HOST's retrieval rung at serve time, handed in by the composition root and
+     * copied onto every finalized step. It sits BESIDE `servedBrief` for the same reason
+     * `retrievalTrace` does — `computeBriefDigest` keys cassettes and acceptance evidence on the
+     * brief's bytes, so a rung channel inside the brief would invalidate every brief ever served.
+     * The recorder never resolves it: a run's rung is a fact about serve time, not a live probe.
+     */
+    private readonly retrievalRung?;
+    /**
+     * D-02 single sub-action chokepoint (Plan 361-08). When bound, invoked at the END of
+     * every {@link recordSubAction} append with the recorded evidence and its index — so all
+     * five loop call sites emit `subActionRecorded` through ONE seam, never per-call-site.
+     * Optional-chained: unbound ⇒ the recorder is byte-identical to today (never throws, D-05).
+     */
+    private readonly onSubActionRecorded?;
+    constructor(options?: {
+        servedBrief?: ServedBrief;
+        scope?: ScopeKey;
+        asOfBuild?: number;
+        onSubActionRecorded?: (evidence: SubActionEvidence, index: number) => void;
+        modelProfile?: DeclaredModelProfile;
+        verifierIdentity?: ModelIdentity;
+        toolSchemaDigest?: string;
+        retrievalRung?: RecordedRetrievalRung;
+    });
+    private replaceServedBrief;
+    private losslessProof;
+    /**
+     * Upgrade this production recorder from the proof-less historical shape to a live lossless
+     * proof. The model-visible channel bytes stay unchanged; only the actual serving caps and
+     * empty chronological journals are introduced.
+     */
+    beginLosslessServedBrief(input: {
+        recordCap: number;
+        combinedBudget: number;
+    }): void;
+    /**
+     * Append observations drained from the production admission authority. Ordinals must remain
+     * contiguous across batches; validation occurs before mutation so a bad batch appends nothing.
+     */
+    recordServedAdmissionEvents(events: readonly ServedAdmissionEvent[]): void;
+    /** Append one exact production prompt snapshot and re-address the complete served proof. */
+    recordServedPromptTurn(turn: ServedPromptTurn): void;
+    /** The number of sub-actions recorded so far; the next recordSubAction returns this index. */
+    get subActionCount(): number;
+    /** Append a §A8 SubActionEvidence. Returns its index (for attachStateAfter). */
+    recordSubAction(input: RecordSubActionInput): number;
+    /**
+     * Snapshot the run-scoped working-memory set served to this step's planning turns
+     * (WM-01, §12.15). The loop passes the values ALREADY masked (the loop's `recordMask`, Pitfall
+     * 7 boundary 3) — recorded BESIDE the brief, never inside `servedBrief`.
+     */
+    recordWorkingMemory(entries: WorkingMemoryEntry[]): void;
+    /**
+     * Record the real deterministic Channel-1 brief served to this step. The recording type is the
+     * schema-owned ServedBrief; the digest is always recomputed over the populated channels.
+     * makeEmptyServedBrief remains exclusively the no-reader constructor fallback.
+     */
+    recordServedBrief(input: {
+        scope: ScopeKey;
+        asOfBuild: number;
+        budget: number;
+        block: BriefBlock;
+        /**
+         * D-16's last hop, made structural. The trace is a REQUIRED parameter, so the only way to
+         * persist a served brief without one is to change this signature — which is a compile error
+         * at every call site rather than a silently trace-less run. `makeEmptyServedBrief` stays the
+         * one no-reader constructor fallback and records nothing here, so an absent trace on evidence
+         * means "no reader was bound", never "a reader served and the trace was dropped" (D-15).
+         */
+        trace: ServedRetrievalTraceV1;
+    }): void;
+    /**
+     * Append the exact Channel-3 CautionLines injected into a live replan turn. Refused records
+     * never enter this method; the reserved reader overflow line does because its summary was
+     * actually rendered. Digest recomputation keeps ServedBrief content-addressed after mutation.
+     *
+     * WR-10 (387-13): the LEDGER accumulates on every call, including the zero-injection one. A
+     * turn that injected nothing is not a turn with nothing to explain — it is exactly the turn
+     * "why didn't it mention X" is asked about, and {@link foldRetrievalTrace} carries a dedicated
+     * arm for "no served lines, non-empty truncation ledger" that this method previously made
+     * unreachable by returning before accumulating.
+     *
+     * The surviving `cautions.length === 0` return is a COST guard, not a correctness one, and the
+     * distinction is measured rather than asserted: deleting it outright reddens nothing, because
+     * appending an empty array and recomputing a content-addressed digest reproduces the same
+     * bytes. It stays only to skip a whole-brief rehash on every all-cut turn. D-13's byte-stability
+     * on this path is protected by what is NOT written here — cut candidates are never spoofed into
+     * `channel3` as served lines — and the regression cases pin that outcome, not this branch.
+     */
+    recordServedCautions(cautions: readonly CautionLine[], trace: ServedRetrievalTraceV1): void;
+    /** Append successful Channel-2 direct reads and re-address the complete served brief. */
+    recordServedReadTraces(traces: readonly ReadTrace[]): void;
+    /**
+     * Record the structurally failed planning turn (D-03). Exchanges and message arrive
+     * ALREADY masked by the loop; the recorder remains mask-agnostic.
+     */
+    recordPlanningFailure(evidence: PlanningFailureEvidence): void;
+    /**
+     * Record the D-03 `common_reportValue` answer block. `value` arrives already masked. Surfaced
+     * on StepEvidence.reportedValue so the verdict layer (and Phase 361's handoff) carries the
+     * retrieved answer first-class. reportValue is non-terminal (D-02) — this only records.
+     */
+    recordReportedValue(evidence: ReportedValueEvidence): void;
+    /**
+     * Record the D-04 infeasible termination block — present only when a turn declared the step
+     * infeasible via the `failureKind`/`failureReason` envelope (machine-distinguishable from a
+     * plain `stepFailed`). Sorted keys `["kind","reason"]` are fixed by the DTO.
+     */
+    recordTermination(evidence: TerminationEvidence): void;
+    /**
+     * Record the typed limit stop (436 D-12/D-13). Its text fields arrive already masked; it is
+     * never a planning failure, a termination or a verdict source.
+     */
+    recordLimitStop(evidence: LimitStopEvidence): void;
+    /**
+     * Record the per-condition verdicts (439 D-07). Text fields arrive masked and bounded; a later
+     * judgment of the same step replaces an earlier one.
+     */
+    recordConditionVerdicts(evidence: ConditionVerdictsEvidence): void;
+    /** Record whether the step's platform could capture each operation (436 D-23). */
+    recordOperationCapture(availability: OperationCaptureAvailability): void;
+    /** Record the step's configured limits and usage (436 D-11); finish() calls it on every path. */
+    recordLimitUsage(usage: StepLimitUsage): void;
+    /**
+     * Record the D-05/D-06/D-07/D-09 AI judge block (`assertAI`/`extractAI`): verdict, rationale
+     * (masked), the requested-but-deferred M3/M4 knobs, and the extractAI global-scope degradation
+     * marker. One judgment per attempt (single-model law).
+     */
+    recordAiJudgment(evidence: AiJudgmentEvidence): void;
+    /**
+     * Record the D-10/D-11 structured `common_assertValue` outcome block: the comparator's
+     * deterministic result with `expected`/`actual` already masked. A passing outcome drives the
+     * verifier short-circuit (Plan 10 seam), recorded via {@link recordVerdictSource}.
+     */
+    recordAssertOutcome(evidence: AssertValueEvidence): void;
+    /**
+     * Record which path produced this step's final verification verdict (D-11): the deterministic
+     * assertValue comparator (`'assert-value'`) or the verifier's own model call
+     * (`'verifier-model'`), which also decides every AI-judged conclusion (assertAI or extractAI;
+     * quick 261004-lsa). Set with the final verdict, so a verifier rejection records nothing.
+     */
+    recordVerdictSource(source: VerdictSource): void;
+    /**
+     * Record the typed step plan source (PROC-02 · 381 D-12). `procedure-replay` carries the
+     * guard fold (checksPassed/total + the first miss when the fold broke off); `procedure-hint`
+     * marks a served-without-replay exposure. Recorded BESIDE `cacheStatus` — structurally
+     * distinct from the cached flag so eval/cassette consumers reading cached semantics are
+     * never polluted (Pitfall 4). Last write wins: the loop updates the fold as guard checks
+     * accumulate, and the final state is what finalize emits.
+     */
+    recordPlanSource(source: StepPlanSource): void;
+    /**
+     * Record why a cache key hit did not replay (438 D-11), before the loop invalidates the entry.
+     * The first reason in the step is kept.
+     */
+    recordCacheMiss(miss: {
+        reason: CacheMissReason;
+    }): void;
+    /**
+     * Attach the D-15 stateAfter at the spec-locked boundaries (assert sub-actions, the
+     * verifier boundary, the self-heal boundary) by reuse of an observation the loop
+     * already takes — no extra capture.
+     */
+    attachStateAfter(index: number, state: ScreenState): void;
+    /** Record the §A8 contrastive self-heal pair (D-12): the failed decision and the
+     * recovering decision at the replan-with-failure-context boundary. */
+    recordSelfHeal(failedDecision: Decision, recoveringDecision: Decision): void;
+    /**
+     * Fold the per-channel serve-time attributions into the one persisted trace (D-13/D-14).
+     *
+     * Every value here was computed by the reader at the moment of serving and is copied through
+     * unchanged — no score is re-derived and no rank is recomputed at persistence time. The runner
+     * writes; the reader computed.
+     *
+     * Absent when nothing was served through a bound reader, which is D-15's honest no-trace arm:
+     * an absent trace says "no reader served this step", not "a trace was lost".
+     */
+    private foldRetrievalTrace;
+    /** Finalize the accumulated evidence into a §A8 StepEvidence. cacheStatus is the
+     * per-step fold; servedBrief is always present (empty when no reader bound).
+     *
+     * `options.nonCacheable` threads the D-08 bypass signal (Pitfall 7): when a step was
+     * classified NonCacheableStepInput the loop never touched the cache, so cacheStatus is
+     * `'bypass'` DIRECTLY — orthogonal to the boolean hit/miss fold (a cached sub-action's
+     * flag must not fold to `'hit'` for a bypassed step). */
+    finalize(verdict: VerifierVerdict, stepIndex: number, stepText: string, options?: {
+        nonCacheable?: boolean;
+        /**
+         * The step's `{{env:NAME}}` provenance pairs (PROC-01 · 381 D-03/D-08), stamped only
+         * when non-empty so the absent-by-default shape is preserved. The recorder is
+         * MASK-AGNOSTIC by contract: it records exactly what its caller passes and masks
+         * nothing itself. These pairs in particular must NOT be masked anywhere — see the
+         * masking prohibition on `StepEvidence.interpolatedVariables`.
+         */
+        interpolatedVariables?: readonly InterpolatedVariable[];
+    }): StepEvidence;
+}
+declare function projectLegacyTrace(evidence: StepEvidence): SubActionTrace[];
+
+interface GroundingStrategy {
+    reground(locator: GroundedLocator, elements: readonly ElementInfo[]): StrictMatchResult;
+}
+declare const deterministicDescriptorMatcher: GroundingStrategy;
+
+/**
+ * Stable, non-secret, project-level env-digest salt (Open Question 2 resolution).
+ * It MUST be a fixed versioned constant — a per-run salt would silently change the
+ * env digest every run and disable ALL env-dependent cache hits. Never derive this
+ * per-run and never fold a secret into it.
+ */
+declare const CACHE_ENV_DIGEST_SALT = "agent-qa/cache/env-digest/v1";
+interface BuildCacheableStepInputArgs {
+    /** The declared-secret mask (441 D-06); the identity when unbound. */
+    mask?: MaskFn;
+    platform: Platform;
+    suiteConfigDigest: string;
+    testConfigDigest: string;
+    stepText: string;
+    stepIndex: number;
+    testIndex: number;
+    /** Value-free redacted env shapes only — raw env values never reach the digest. */
+    envVars: readonly RedactedEnvVar[];
+    /** Stable project salt; defaults to CACHE_ENV_DIGEST_SALT. Never per-run. */
+    envSalt?: string;
+    screenIdentityHash: string;
+    /** Accepted for caller ergonomics but intentionally never a key component (D-14). */
+    branch?: string;
+}
+/**
+ * Assemble the schema kernel's 8-field CacheableStepInput. `mask()` is applied to
+ * stepText BEFORE it enters the tuple (the MASK-FUT-01 floor, D-05); the env digest
+ * folds only the value-free redacted shapes under the stable salt. The caller passes
+ * the result to computeCacheKey to obtain the 16-hex CacheKey / filename (D-06).
+ */
+declare function buildCacheableStepInput(args: BuildCacheableStepInputArgs): CacheableStepInput;
+
+interface CacheableClassification {
+    cacheable: true;
+    /** Value-free config-env shapes this step depends on (folded into the digest). */
+    envVars: RedactedEnvVar[];
+}
+interface ClassifyStepInput {
+    stepText: string;
+    /** Variable names this step sets — the onSetVariable / setVariable provenance. */
+    envSets?: readonly string[];
+    /** Config-env values this cacheable step reads (value-free shapes). */
+    configEnv?: readonly RedactedEnvVar[];
+}
+/**
+ * Classify a step by resolution provenance (D-07). Env/secret read-or-set steps
+ * return NonCacheableStepInput; a config-env-dependent step returns a
+ * CacheableClassification carrying the value-free RedactedEnvVar shapes.
+ */
+declare function classifyStep(input: ClassifyStepInput): CacheableClassification | NonCacheableStepInput;
+
+/**
+ * Thrown by `subscribe(fromSeq, …)` when the requested range is neither in the in-memory
+ * window nor recoverable from the (possibly degraded) event log (D-07 — report incomplete,
+ * never silently serve a truncated stream). `earliestAvailableSeq` is the lowest seq the bus
+ * can still replay (the SSE `Last-Event-ID` re-subscribe floor in M5).
+ */
+declare class ReplayIncompleteError extends Error {
+    readonly earliestAvailableSeq: number;
+    constructor(requestedSeq: number, earliestAvailableSeq: number);
+}
+/** A live/replay subscriber. Synchronous — replay-then-live per-subscriber order is total. */
+type RunEventHandler = (event: RunEventEnvelope) => void;
+/**
+ * The bus surface. `publish` stamps `seq`/`ts` and returns the sealed envelope (the shell reads
+ * `.seq` for `runFinished.finalSeq`); `subscribe` replays then goes live; `close` stops the
+ * heartbeat (publish-after-close is a programming error).
+ */
+interface RunEventBus {
+    publish(type: RunEventType, payload: RunEventPayload | Record<string, unknown>): RunEventEnvelope;
+    subscribe(fromSeq: number | undefined, handler: RunEventHandler): () => void;
+    readonly currentSeq: number;
+    close(): void;
+}
+interface CreateRunEventBusOptions {
+    runId: string;
+    eventLog?: EventLogPort;
+    timer?: RunTimerPort;
+    heartbeatMs?: number;
+    windowMaxEvents?: number;
+    windowMaxBytes?: number;
+}
+declare function createRunEventBus(opts: CreateRunEventBusOptions): RunEventBus;
+
+/** How long a handle's stream keeps running after its LAST viewer detaches (403 D-07). */
+declare const LIVE_STREAM_STOP_GRACE_MS = 2000;
+/** How long the hub waits for every subscriber to ack a frame before acking on their behalf. */
+declare const LIVE_STREAM_ACK_BOUND_MS = 250;
+/**
+ * Default timer: the `bus.ts` idiom — unref'd so a pending grace never holds the process open.
+ * Exported so the snapshot producer shares it rather than copying it (428 D-11).
+ */
+declare function defaultLiveStreamTimer(): RunTimerPort;
+interface CreateLiveStreamHubOptions {
+    timer?: RunTimerPort;
+    graceMs?: number;
+    ackBoundMs?: number;
+    /**
+     * Facts about the RUN's producer. The shell wires this to the run's durable event log, so what
+     * lands here is replayed to every later reader of the run.
+     */
+    onWarning?: (code: string, message: string) => void;
+    /**
+     * Where a SUBSCRIBER's fault is reported (403 WR-06). Deliberately a DIFFERENT sink than
+     * `onWarning`, and the difference is the whole fix: a viewer that throws — or whose socket died
+     * between a `readyState` check and the write — is a fact about THAT VIEWER, and the run's
+     * permanent record must not depend on who happened to be watching (LIVE-03). Absent by default,
+     * so a host that does not care reports nothing anywhere.
+     */
+    onSubscriberFault?: (code: string, message: string) => void;
+}
+/**
+ * The run's frame fan-out. `register` is the PRODUCER side (the member executor hands its adapter's
+ * capability in, and hands `undefined` in when the member finishes); `subscribe`/`capabilityOf` are
+ * the CONSUMER side the `RunSession` exposes.
+ */
+interface LiveStreamHub {
+    /**
+     * `fallback` is the labelled snapshot producer this handle switches to when `capability` fails
+     * to start (428 D-12). The failure is still recorded; `capabilityOf` keeps the declared kind.
+     */
+    register(handle: number, capability: LiveStreamCapability | undefined, fallback?: LiveStreamCapability): void;
+    subscribe(handle: number, onFrame: (frame: LiveFrame) => void, onEnd?: (reason: LiveFrameEndReason) => void): LiveFrameSubscription | undefined;
+    capabilityOf(handle: number): LiveStreamDeclaration;
+    close(): Promise<void>;
+}
+declare function createLiveStreamHub(opts?: CreateLiveStreamHubOptions): LiveStreamHub;
+
+/**
+ * The three live-preview cadences, side by side: a snapshot every second (this producer), a
+ * keepalive frame after two quiet seconds on a static page (the web adapter's screencast, 428-06),
+ * and the viewer's ~5s freshness window (428-14) that both of them stay inside.
+ */
+declare const LIVE_SNAPSHOT_INTERVAL_MS = 1000;
+declare const LIVE_KEEPALIVE_QUIET_MS = 2000;
+declare function createSnapshotLiveStream(input: {
+    capture: () => Promise<Uint8Array | undefined>;
+    timer?: RunTimerPort;
+    intervalMs?: number;
+}): LiveStreamCapability;
+/** What a run or an editor session registers with its hub: a stream, and what replaces it on a failed start. */
+type LiveStreamRegistration = {
+    capability: LiveStreamCapability;
+    fallback?: LiveStreamCapability;
+};
+/**
+ * THE ONE SELECTION RULE (428 D-11/D-12), used by both run paths and the editor.
+ *
+ * The adapter's own `liveStream` always wins. `screenshot()` is wrapped in the snapshot producer
+ * only when the adapter's own capability is not already a snapshot: as the fallback behind a
+ * continuous stream that may fail to start, or as the whole preview when there is no continuous
+ * stream. An adapter whose own stream IS a snapshot (mobile) gets no fallback, which is what keeps
+ * a mobile run off its context-switching `screenshot()`.
+ */
+declare function liveStreamFor(adapter: Pick<PlatformAdapter, 'liveStream' | 'screenshot'> | undefined, options?: {
+    timer?: RunTimerPort;
+}): LiveStreamRegistration | undefined;
+/**
+ * Width and height from a PNG IHDR or a JPEG SOF header, so a snapshot frame has a size before
+ * the viewer decodes it. Anything it cannot read — another format, a truncated header — answers
+ * 0 by 0, and every read is bounded by the byte length.
+ */
+declare function imageSizeOf(bytes: Uint8Array): {
+    width: number;
+    height: number;
+};
+
+/** The explicit handle carries its own capability; no ambient current-step registry exists. */
+declare function withStepModelCall<T>(model: LanguageModel, call: (model: LanguageModel) => Promise<T>): Promise<{
+    result: T;
+    scoped: boolean;
+    respondingModelId?: string;
+}>;
+declare function createStepModelScope(options: StepModelScopeOptions): StepModelScope;
+
+declare function parseEnvFile(content: string): Record<string, string>;
+declare function serializeEnvFile(vars: Record<string, string>): string;
+
+declare const AUTH_STATE_HOOK_JSON_ENV = "AGENT_QA_AUTH_STATE_JSON";
+declare const AUTH_STATE_HOOK_STORAGE_STATE_PATH_ENV = "AGENT_QA_AUTH_STATE_STORAGE_STATE_PATH";
+declare const AUTH_STATE_HOOK_WORKSPACE_DIR = ".agent-qa-auth-state";
+declare const AUTH_STATE_HOOK_STORAGE_STATE_FILENAME = "storage-state.json";
+declare const AUTH_STATE_HOOK_CONTAINER_STORAGE_STATE_PATH = "/workspace/.agent-qa-auth-state/storage-state.json";
+declare function isReservedAuthStateHookEnvKey(key: string): boolean;
+declare function stripReservedAuthStateHookEnv(variables: Record<string, string>): Record<string, string>;
+declare function buildAuthStateHookEnv(authState: RuntimeAuthStateConfig | undefined, storageStatePath?: string): Record<string, string>;
+
+interface SecretTemplate {
+    pattern: string;
+    name: string;
+}
+interface SecretFileMetadata {
+    count: number;
+}
+declare class SecretConfigError extends Error {
+    constructor(message: string);
+}
+declare class MissingSecretError extends Error {
+    constructor(name: string);
+}
+declare class SecretStore implements SecretResolver {
+    private storage;
+    constructor(secrets?: Record<string, string> | ReadonlyArray<readonly [string, string]>);
+    static empty(): SecretStore;
+    static fromEnvContent(content: string): SecretStore;
+    private set;
+    get(name: string): string | undefined;
+    require(name: string): string;
+    has(name: string): boolean;
+    count(): number;
+    metadata(): SecretFileMetadata;
+    forEachSecret(callback: (name: string, value: string) => void): void;
+}
+declare function findSecretTemplates(text: string): SecretTemplate[];
+declare function interpolateSecretTemplates(template: string, store: SecretStore): string;
+declare function resolveSecretTemplatesInValue<T>(value: T, store?: SecretResolver): T;
+declare function redactSecretValue<T>(value: T, redactor?: SecretRedactorPort): T;
+/**
+ * The cached-plan invalidation predicate (loop cache-poisoning guard): returns true
+ * when a value contains a redacted `[secret:*]` marker. Moved from core loop.ts.
+ */
+declare function containsRedactedSecretMarker(value: unknown): boolean;
+declare function literalSecretMarkerRefusal(value: unknown): string | undefined;
+declare class SecretRedactor implements SecretRedactorPort {
+    private readonly store;
+    private readonly pattern;
+    private readonly valuePattern;
+    private readonly nameByValue;
+    constructor(store: SecretStore);
+    redactString(value: string): string;
+    private maskValues;
+    redactValue(value: unknown): unknown;
+}
+
+/** Structural secret source (SecretStore satisfies it) — used to resolve container secretEnv. */
+interface SecretEnvSource {
+    forEachSecret(callback: (name: string, value: string) => void): void;
+}
+/**
+ * Resolve the already-materialized secret name→value map the container is injected with
+ * (D-06). The runner-owned {@link SecretStore} satisfies the structural source; the port only
+ * ever sees the resolved map, never the store itself.
+ */
+declare function resolveSecretEnv(store?: SecretEnvSource): Record<string, string>;
+/**
+ * The threaded hook-execution carrier (Phase 363 D-06) — successor to core's
+ * `SandboxRunnerOptions`. Threaded through the run/suite config as `sandboxOptions` and
+ * spread into {@link RunHooksOptions} at each hook site. Carries the injected
+ * {@link HookExecutorPort} (constructed once at the composition root) plus the secret
+ * store / redactor / active auth-state the hook body needs. `dockerBin`/`pullPolicy` are
+ * retained for source-compat with the old carrier (the executor owns those now).
+ */
+interface SandboxRunnerOptions {
+    executor: HookExecutorPort;
+    dockerBin?: string;
+    pullPolicy?: 'always' | 'if-not-present' | 'never';
+    envVars?: Record<string, string>;
+    secretStore?: SecretStore;
+    secretRedactor?: SecretRedactorPort;
+    authState?: RuntimeAuthStateConfig;
+}
+interface HookOrchestrationResult {
+    results: Map<string, HookResult>;
+    variables: Record<string, string>;
+    allPassed: boolean;
+    duration: number;
+}
+/**
+ * The narrow lifecycle-emit seam `runHooks` fires through — the Plan 03 sink legs
+ * (`MemberEventSink.hookStarted`/`hookFinished`) satisfy it structurally. Both legs are
+ * fire-and-forget; the orchestration NEVER awaits telemetry. Output detail is emitted
+ * as-is (already sandbox-redacted by the impl); the sink applies the additive run-mask
+ * (T-363-05) — the orchestration does not mask.
+ */
+interface HookEmitSeam {
+    hookStarted(payload: HookStartedPayload): void;
+    hookFinished(payload: HookFinishedPayload): void;
+}
+/** Identity fields locating this hook batch in the run tree (payload provenance). */
+interface HookRunIdentity {
+    phase: HookStartedPayload['phase'];
+    scope?: HookStartedPayload['scope'];
+    testIndex?: number;
+    stepIndex?: number;
+}
+interface RunHooksOptions {
+    /** The injected D-06 executor (runner-local `DockerHookExecutor`). */
+    executor: HookExecutorPort;
+    /** User env + CLI/suite variables the first hook starts from. */
+    env?: Record<string, string>;
+    /** Carrier-compat alias for {@link env} (the old `SandboxRunnerOptions.envVars` field). */
+    envVars?: Record<string, string>;
+    /** Already-resolved secret name→value pairs for container injection (D-06). */
+    secretEnv?: Record<string, string>;
+    /** Runner-owned secret store; the orchestrator resolves {@link secretEnv} from it. */
+    secretStore?: SecretEnvSource;
+    /** Structural secret redactor for stdout/stderr/error redaction. */
+    secretRedactor?: SecretRedactorPort;
+    /** Active auth-state mounted + injected per hook. */
+    authState?: RuntimeAuthStateConfig;
+    /** Tolerated carrier fields (the executor owns docker config now; ignored by orchestration). */
+    dockerBin?: string;
+    pullPolicy?: 'always' | 'if-not-present' | 'never';
+    /** Optional lifecycle emit seam; requires {@link identity} to emit. */
+    emit?: HookEmitSeam;
+    /** Payload provenance; when present alongside {@link emit}, every executed hook emits. */
+    identity?: HookRunIdentity;
+}
+declare function runHooks(hooks: HookDefinition[], options: RunHooksOptions): Promise<HookOrchestrationResult>;
+
+/**
+ * Start a run (D-01). Constructs the session SYNCHRONOUSLY — the bus, `runStarted` at seq 1, the
+ * run-budget arm, the run-level AbortController — then kicks the async member pool whose settled
+ * result feeds `done`. Returns the addressable {@link RunSession} immediately.
+ *
+ * 402-02 (D-09): members execute through a BOUNDED CONCURRENT POOL rather than a `for` loop, but
+ * everything after it is unchanged — the terminal sequence is still ONE code path, run once, after
+ * the pool settles. Concurrency changes which member is in flight when; it does not change who
+ * publishes the verdict, or when `runFinished` is last.
+ */
+declare function startRun(config: RunConfig): RunSession;
+
+/**
+ * Build the per-member {@link MemberEventSink} the shell hands to the executor context (D-02).
+ * `testIndex` is bound here; `stepIndex` is curried by `loopEmitFor`. `mask` is the run's mask
+ * (441-12, D-06). All three payload kinds go through the schema projections + mask.
+ */
+declare function createMemberEventSink(deps: {
+    bus: RunEventBus;
+    mask: MaskFn;
+    testIndex: number;
+}): MemberEventSink;
+
+/** A single member-test step — a bare instruction or an object carrying per-step knobs. */
+interface MemberStepSpec {
+    step: string;
+    timeout?: number;
+    capture?: {
+        variable: string;
+        method?: ExtractionMethod;
+        pattern?: string;
+        selector?: string;
+        description?: string;
+    };
+}
+/**
+ * The one derivation of the text a step is announced with at `stepStarted` (G-428-2). Every
+ * producer that states a step's text before it starts (the CLI's `stepTexts` on each member
+ * descriptor) derives it here, so the pending text and the announced text cannot drift.
+ */
+declare function memberStepText(step: string | MemberStepSpec): string;
+/** The runner-owned member-test shape (a core-independent subset of TestDefinition). */
+interface MemberTest {
+    testId: string;
+    name: string;
+    filePath: string;
+    url?: string;
+    context?: string;
+    steps: Array<string | MemberStepSpec>;
+    meta?: {
+        timeout?: number;
+        retries?: number;
+        [key: string]: unknown;
+    };
+}
+/** The injected runJS execution handler (Q-2). The CLI owns page.evaluate + platform checks. */
+type RunJsHandler = (code: string, ctx: {
+    abortSignal: AbortSignal;
+}) => Promise<{
+    value: string;
+    error?: string;
+}>;
+/** The injected appium execution handler (Q-2). The CLI resolves secrets + calls the adapter. */
+type AppiumScriptHandler = (action: Action, ctx: {
+    abortSignal: AbortSignal;
+}) => Promise<ActionResult>;
+/** The injected accessibility-check handler (Q-4). The CLI owns page acquisition + the web module. */
+type AccessibilityCheckHandler = (opts: {
+    standard?: 'wcag2a' | 'wcag2aa' | 'wcag2aaa';
+    disableRules?: string[];
+    exclude?: string[];
+}, ctx: {
+    abortSignal: AbortSignal;
+}) => Promise<AccessibilityViolation[]>;
+/** The injected failure-screenshot writer. The CLI owns the adapter screenshot capture. */
+type FailureScreenshotWriter = (ctx: {
+    abortSignal: AbortSignal;
+}) => Promise<Buffer | undefined>;
+/**
+ * Everything runMemberTest needs, all injected at the CLI composition root. The sink,
+ * abortSignal, and testIndex are the per-member context the shell binds (so runMemberTest
+ * slots cleanly behind {@link MemberTestExecutor}); the rest are the run-scoped host impls
+ * the CLI already builds for the loop.
+ */
+interface MemberRunConfig {
+    adapter: PlatformAdapter;
+    planner: Planner;
+    verifier?: Verifier;
+    cache?: ActionPlanCache;
+    modelProfiles?: {
+        planner: DeclaredModelProfile;
+        verifier?: DeclaredModelProfile;
+    };
+    onEvidenceContext?: (context: MemberEvidenceContext) => void;
+    workingMemory?: WorkingMemoryPort;
+    storageState?: StorageStatePort;
+    compressor?: ScreenshotCompressor;
+    knowledgeReader?: KnowledgeHintReader;
+    knowledgeBudgets?: {
+        brief: number;
+        searchResults: number;
+        caution: number;
+        readBody: number;
+        recordCap: number;
+    };
+    knowledgeAsOfBuild?: number;
+    /**
+     * 407 D-13 — the host's retrieval rung, resolved once at the composition root and threaded
+     * verbatim onto every step's LoopPorts. Typed off LoopPorts so there is ONE spelling of the
+     * contract between the run shell and the loop.
+     */
+    knowledgeRetrievalRung?: LoopPorts['knowledgeRetrievalRung'];
+    recordLedger?: LoopPorts['recordLedger'];
+    beginMemoryTurn?: LoopPorts['beginMemoryTurn'];
+    drainMemoryReadTraces?: LoopPorts['drainMemoryReadTraces'];
+    uniqueValueGenerator?: UniqueValueGenerator;
+    guardBlob?: (value: unknown) => string | undefined;
+    configDigests?: ConfigDigests;
+    evidenceArtifacts?: EvidenceArtifactStorePort;
+    plannerModel: LanguageModel;
+    verifierModel: LanguageModel;
+    /** The host closes over resolved model/accounting configuration, never a current-step pointer. */
+    stepModelScope?: {
+        runId: StepModelScopeKey['runId'];
+        create: StepModelScopeFactory;
+    };
+    envFileVars?: Record<string, string>;
+    inlineVars?: Record<string, string>;
+    suiteVars?: Record<string, string>;
+    cliVars?: Record<string, string>;
+    hookSetupVars?: Record<string, string>;
+    hookExecutor?: HookExecutorPort;
+    inlineHookDefs?: Map<string, HookDefinition>;
+    hookEnvVars?: Record<string, string>;
+    hookSecretEnv?: Record<string, string>;
+    hookAuthState?: RuntimeAuthStateConfig;
+    runJs?: RunJsHandler;
+    appiumScript?: AppiumScriptHandler;
+    accessibilityCheck?: AccessibilityCheckHandler;
+    persistFailureScreenshot?: FailureScreenshotWriter;
+    resolveSecrets?: (text: string) => string;
+    secretStore?: SecretResolver;
+    secretRedactor?: SecretRedactorPort;
+    sink: MemberEventSink;
+    testIndex: number;
+    abortSignal: AbortSignal;
+    captureScreenshots?: boolean;
+    recording?: {
+        enabled: boolean;
+        keepFailuresOnly?: boolean;
+    };
+    accessibility?: {
+        enabled: boolean;
+        standard?: 'wcag2a' | 'wcag2aa' | 'wcag2aaa';
+        runAfter?: 'every-step' | 'navigation' | 'test-end';
+        failOnViolation?: boolean;
+        disableRules?: string[];
+        exclude?: string[];
+    };
+    timeouts?: {
+        step?: number;
+        test?: number;
+        navigation?: number;
+    };
+    plannerConfig?: PlannerConfig;
+    logger?: LoopLogger;
+    logCapture?: {
+        console?: boolean;
+        network?: boolean;
+    };
+    vision?: {
+        screenshotSize?: number;
+        effectiveResolution?: number;
+    };
+    visionGate?: {
+        attachImage: boolean;
+        captureMode: 'full' | 'textOnly';
+        promptNote: string;
+    };
+    contextWindow?: number;
+    suiteContext?: string;
+    resolveUploadPath?: (rawPath: string) => string;
+    onWarn?: (message: string) => void;
+    executeStep?: typeof executeStep;
+    extractorFactory?: (model: LanguageModel | undefined, method: string) => VariableExtractor;
+}
+/**
+ * Run a member test with the retry loop (D-13). The trigger stays `meta.retries`
+ * (user-config surface unchanged). Attempts run INSIDE the member; `testRetryScheduled`
+ * fires between attempts (a per-test accumulation reset for subscribers); only the FINAL
+ * attempt's TestResult leaves the member carrying `retryCount` (Pitfall 9 — the shell
+ * emits the single authoritative testStarted/testFinished pair per member).
+ */
+declare function runMemberTest(member: MemberTest, config: MemberRunConfig): Promise<TestResult>;
+
+declare function isCanonicalHookIdShape(value: string): boolean;
+interface InlineHookCall {
+    hookId: string;
+    fullMatch: string;
+}
+declare function parseHookInline(text: string): InlineHookCall[];
+declare function stripHookInline(text: string): string;
+interface RunJSMatch {
+    fullMatch: string;
+    code: string;
+}
+declare function parseRunJSInline(text: string): RunJSMatch[];
+declare function coerceRunJSResult(value: unknown): string;
+declare function parseAppiumInline(text: string): Action | null;
+
+declare function generateFailureSummary(steps: StepResult[]): string;
+
+/**
+ * Fold one completed member {@link TestResult} + its derived {@link MemberTestOutcome} into a
+ * {@link PerTestOutcome}. Steps are built from `result.steps`: a step with §A8 evidence carries it
+ * (with `stepIndex` OVERRIDDEN to its array position); an evidence-less step gets a synthesized
+ * minimal StepEvidence. `testIndex` is the shell-owned array position.
+ *
+ * `rootCause` is the shell-classified §A9 verdict (373-07): attached ONLY when defined so clean
+ * passes/skipped/cancelled members stay rootCause-free in the persisted JSON (the D-01 presence
+ * rule — the key is absent, never undefined-valued).
+ *
+ * `deps.quarantined` is the 390 D-14 disposition, stamped BESIDE `outcome` under the same
+ * presence rule. It never alters `outcome`: a quarantined failing member reads `'failed'` here, and
+ * the licence to ignore that failure lives entirely in the aggregate rule and in this marker.
+ */
+declare function assemblePerTestOutcome(member: RunMemberDescriptor, result: TestResult, outcome: MemberTestOutcome, deps: {
+    testIndex: number;
+    scope: ScopeKey;
+    buildOrdinal: number;
+    mask: MaskFn;
+    modelProfile?: DeclaredModelProfile;
+    verifierIdentity?: ModelIdentity;
+    toolSchemaDigest?: string;
+    quarantined?: true;
+}, rootCause?: Verdict, origin?: {
+    runId: string;
+    outcome: 'failed' | 'timeout';
+    rootCause?: Verdict;
+}): PerTestOutcome;
+/**
+ * The shell-produced skip outcome (D-15): a member the shell never invoked (run aborted, or a
+ * poisoned same-group member). `outcome: 'skipped'`, no steps — neutral in the aggregate fold.
+ *
+ * `quarantined` is still stamped when the ledger licensed this member (390 D-14): the disposition
+ * describes the TEST's standing, not the outcome it happened to reach, so a reader of the handoff
+ * sees the same truth whether the member ran or was skipped past.
+ */
+declare function skippedPerTestOutcome(member: RunMemberDescriptor, testIndex: number, quarantined?: true): PerTestOutcome;
+/**
+ * Assemble the one {@link CompletedRunHandoff} a run persists (D-17). Every header field is copied
+ * verbatim FROM the resolved {@link RunConfig} (D-04/D-20 — never re-derived); `aggregateVerdict`
+ * is the execution verdict; `tests` are the assembled per-member outcomes in run order.
+ *
+ * 390 D-16: `quarantineApplied` records the ledger entries this run was operating under, copied
+ * from the same resolved config the disposition markers were matched against — so the run's own
+ * receipt answers "which suppressions were licensed here, and until when" without re-reading a
+ * ledger that may since have changed. An empty set stays ABSENT, keeping every unquarantined run's
+ * handoff bytes identical to pre-390.
+ */
+declare function assembleHandoff(config: RunConfig, outcomes: PerTestOutcome[], aggregateVerdict: RunStatus, timing: {
+    startedAt: number;
+    endedAt: number;
+}): CompletedRunHandoff;
+
+/**
+ * Derive the member-level outcome for one completed test (D-16). Pure total function.
+ *
+ * - status `skipped` ⇒ `'skipped'` (member-neutral; passed through)
+ * - status `cancelled` ⇒ `'cancelled'`
+ * - status `passed` ⇒ `'healed'` when ANY step carries selfHeal evidence, else `'passed'`.
+ *   The live heal signal is StepEvidence.selfHeal *presence* — a step-status read would
+ *   never fire (RESEARCH Pitfall 5), so we never inspect a step status string here.
+ * - status `failed` ⇒ `'timeout'` when ANY failed step's `error` is the test-deadline
+ *   message (isTestTimeoutMessage), else `'failed'`.
+ *
+ * Core's TestStatus and the executor port stay untouched by this derivation (D-16).
+ */
+declare function deriveMemberOutcome(result: TestResult): MemberTestOutcome;
+/**
+ * Fold member outcomes into the aggregate run verdict — the ratified spec §2.1 ordered
+ * rule with the D-15 neutral-skipped clause. EVALUATED IN ORDER:
+ *
+ *  1. `runCancelled` ⇒ `'cancelled'` (a whole-run cancel wins over everything)
+ *  2. `runBudgetExpired` ⇒ `'timeout'` (reserved for the whole-run wall-clock budget;
+ *     a member 'timeout' is NOT this — it falls to the failed branch below)
+ *  3. any member `'failed'` or `'timeout'` ⇒ `'failed'`
+ *  4. any member `'cancelled'` (none failed) ⇒ `'cancelled'`
+ *  5. any member `'healed'` (none failed) ⇒ `'healed'`
+ *  6. else ⇒ `'passed'`
+ *
+ * `'skipped'` members are neutral throughout — an all-skipped (or empty) run is
+ * vacuously `'passed'` (D-15, the reconciled clause; matches every test runner).
+ *
+ * PHASE 390 D-14 — the quarantine skip is EXPLICIT IN THE RULE, right here in step 3 and nowhere
+ * else. `quarantined[i] === true` marks a member whose failure the committed ledger has licensed:
+ * step 3 passes over it, so a run whose only failures are quarantined aggregates `'passed'` and
+ * exits 0 through the untouched {@link mapVerdictToExitCode}. Three things this deliberately does
+ * NOT do: it does not rewrite the member outcome (`'failed'` stays `'failed'` — the projection
+ * window and the auto-exit keep seeing reality), it does not touch any other branch (a sibling
+ * `'cancelled'`/`'healed'` still governs, and the two run-level branches still win outright), and
+ * it does not widen either closed union. `quarantined` absent — or shorter than `outcomes` — is
+ * byte-identical pre-390 behavior, which is why every existing call site compiles unchanged.
+ *
+ * The skip covers `'timeout'` members as well as `'failed'` ones: a quarantined flaky test that
+ * times out is the same A3 phenomenon, and a rule that suppressed one but not the other would make
+ * relief depend on how the flake happened to manifest that build.
+ */
+declare function deriveAggregateVerdict(input: {
+    runCancelled: boolean;
+    runBudgetExpired: boolean;
+    outcomes: readonly MemberTestOutcome[];
+    quarantined?: readonly boolean[];
+}): RunStatus;
+/**
+ * Map an aggregate verdict to a process exit code (D-14). Pure and pinned:
+ * passed/healed ⇒ 0 (healed is ratified as a pass — the annotation lives in output and
+ * the handoff, never the exit code), failed/timeout ⇒ 1, cancelled ⇒ 130 (existing SIGINT
+ * convention). Exit 2 stays reserved for config/setup errors and is NOT produced here.
+ */
+declare function mapVerdictToExitCode(verdict: RunStatus): number;
+
+/** The four classes the deterministic classifier can mint (RCC-02). */
+type DeterministicRootCauseClass = 'timeout' | 'environment' | 'flake' | 'unknown';
+/** The fixed unknown-class rationale template (D-02). */
+declare const UNKNOWN_SIGNAL_RATIONALE = "no deterministic signal matched";
+interface RootCauseInput {
+    /** The member's final-attempt TestResult (carries retryCount — the flake signal source). */
+    result: TestResult;
+    /** The derived member outcome (deriveMemberOutcome) — the timeout + presence-rule signal. */
+    outcome: MemberTestOutcome;
+    /** Shell-derived member index; becomes Verdict.perTest. */
+    testIndex: number;
+    /** Run-start baseline probe outcome (D-04, web targets; threaded by Plan 07). */
+    baselineProbe?: {
+        status?: number;
+        elapsedMs: number;
+        error?: string;
+    };
+    /**
+     * The run's mask (439 D-08). An unproven step's reason carries the planner's own words, which
+     * the step error holds unmasked, so its rationale passes through this before it is recorded.
+     */
+    mask?: (text: string) => string;
+}
+/**
+ * The D-02 faithful VerdictBase constructor. Pure and total: every field of the LLM-shaped
+ * base is filled deterministically — confidence keys on the class ('unknown' ⇒ 0, else 1),
+ * the unknown rationale is always the fixed template regardless of the signal argument.
+ */
+declare function deterministicVerdict(cls: DeterministicRootCauseClass, signal: string, citedSteps: number[], perTest: number): Verdict;
+/**
+ * Classify one member's root cause from deterministic signals only (RCC-02). Returns
+ * undefined when the presence rule says no rootCause (skipped/cancelled/clean pass).
+ * See the module header for the documented, pinned branch order.
+ */
+declare function classifyRootCause(input: RootCauseInput): Verdict | undefined;
+
+declare function createMemoryTools(deps: {
+    reader: KnowledgeHintReader;
+    scope: ScopeKey;
+    asOfBuild: number;
+    searchResultBudget: number;
+    readBodyBudget: number;
+    recordLedger: RecordLedger;
+    estimateTokens: (text: string) => number;
+    onReadTrace?: (trace: ReadTrace) => void;
+}): {
+    tools: NonActionToolMap;
+    beginTurn(scope?: ScopeKey, exposedIds?: readonly RecordId[], turnOrdinal?: number): void;
+    drainReadTraces(): ReadTrace[];
+};
+
+declare function buildTools(registry: ToolRegistry, options: {
+    platform: Platform;
+    categories?: ToolCategory[];
+}): Record<string, Tool<any, any>>;
+declare function toolCallToActionPlan(toolId: string, args: Record<string, unknown>, registry: ToolRegistry): {
+    action: {
+        type: string;
+    };
+    failureReason?: string | undefined;
+    failureKind?: "infeasible" | undefined;
+    bulkCompletionPredicate?: string | undefined;
+    remember?: {
+        key: string;
+        value: string;
+        kind: "code" | "filename" | "extracted-value" | "progress-marker";
+        provenance: "observation" | "toolResult" | "plannerInference";
+        testIndex?: number | undefined;
+        stepIndex?: number | undefined;
+    }[] | undefined;
+    reasoning: string;
+    confidence: number;
+    stepComplete: boolean;
+    stepFailed: boolean;
+    doesActionAdvanceUsTowardsGoal: boolean;
+};
+
+/**
+ * Project a resolved Action onto the schema-owned {@link RiskActionDescriptor} (D-08). An
+ * unrecognized verb projects `recognized: false` — the classifier's fail-safe floor maps it to
+ * `restricted` → deny. `command`/`declaredTier` are deliberately omitted: no shell-wrapper actions
+ * exist in-test and `declaredTier` stays the registry's future channel.
+ */
+declare function projectRiskAction(action: {
+    type: string;
+}): RiskActionDescriptor;
+
+declare function normalizePointerActionForStep(action: Action, stepInstruction: string): Action;
+
+/**
+ * Converts "Meta" tokens in keyboard combo strings to "Control" on non-Mac platforms.
+ *
+ * Users write combos like "Meta+k" and we route them to Cmd+K on Mac, Ctrl+K on
+ * Windows/Linux. Uses split/join (not regex) to avoid edge-case bugs with adjacent
+ * tokens like "Shift+Meta+Meta+T".
+ *
+ * @param keys - Array of key/combo strings (e.g., ["Meta+k", "Enter"])
+ * @param options.enabled - When false, keys are returned unchanged
+ * @param options.isMac - When true, keys are returned unchanged (Meta is native)
+ * @returns New array with Meta tokens replaced by Control (when applicable)
+ */
+declare function convertKeysForPlatform(keys: string[], options: {
+    enabled: boolean;
+    isMac: boolean;
+}): string[];
+/**
+ * Returns true when running on macOS. Reads process.platform at call time so
+ * tests can override it via Object.defineProperty(process, 'platform', ...).
+ */
+declare function isMacPlatform(): boolean;
+
+export { AUTH_STATE_HOOK_CONTAINER_STORAGE_STATE_PATH, AUTH_STATE_HOOK_JSON_ENV, AUTH_STATE_HOOK_STORAGE_STATE_FILENAME, AUTH_STATE_HOOK_STORAGE_STATE_PATH_ENV, AUTH_STATE_HOOK_WORKSPACE_DIR, type AccessibilityCheckHandler, type AccessibilityViolation, type Action, type ActionPlan, type ActionPlanCache, type ActionResult, type ActionsFor, type AgentAbortScope, type AgentTimeoutAbortReason, type AiJudgmentMeta, AiJudgmentResultSchema, type AppRegistryEntry, type AppResolution, type AppiumScriptHandler, type AssertValueInput, type AssertValueOutcomeMeta, type AssertValueResult, type Asserter, AssertionEvaluator, type AssertionInput, type AssertionResult, type AssertionType, type BaselineProbeResult, type BrowserConfig, type BuildCacheableStepInputArgs, type BuildCachedPlanValueInput, type BuildScreenStateInput, type BuildScreenStateResult, CACHE_ENV_DIGEST_SALT, CHARS_PER_TOKEN_ESTIMATE, CLIPBOARD_TEXT_LIMIT, CLIPBOARD_TRUNCATION_MARKER, type CacheableClassification, type CacheablePlannedAction, type CachedPlanValue, type CaptureResult, type CaptureStamp, type CarriedArtifacts, type CarriedClipboard, type CarriedDownload, type CarriedLine, type ClassifyStepInput, type ClipboardWriteMeta, type CompressedScreenshot, type ConditionJudgment, type ConfigDigests, type ConformanceInput, type ConsoleLogEntry, type CreateLiveStreamHubOptions, type CreateRunEventBusOptions, DEFAULT_CANDIDATE_COUNT, DEFAULT_EDIT_DISTANCE_BOUND, DEFAULT_FUZZY_MARGIN, DEFAULT_FUZZY_THRESHOLD, DEFAULT_NON_ACTION_TOOL_BUDGET, type DesiredState, type DesiredStateAction, type DeterministicRootCauseClass, type DeviceConfig, type DialogAccount, type Direction, type DirectionScrollParams, type DocumentScrollOffsets, EXPOSURE, type EventLogPort, type EvidenceArtifactStorePort, EvidenceRecorder, type ExecuteOptions, type ExecutePlanningTurnOptions, ExplicitExtractor, type ExtractionMethod, ExtractionResultSchema, type ExtractorInput, FILE_DIFFERENCE_WINDOW, FILL_SEPARATORS, type FailureScreenshotWriter, type FillRefusalMeta, type FillRereadMeta, type FillSubmitMeta, type FillVerdictMeta, type FillVerifyInput, type FillVerifyResult, type GroundedLocator, type GroundingStrategy, type HandoffStorePort, type HookDefinition, type HookEmitSeam, type HookExecuteOptions, type HookExecutorPort, type HookOrchestrationResult, type HookResult, type HookRunIdentity, type HookRuntime, type InlineHookCall, type InterimFixture, type InterimFixtureKind, type InterimNode, type InterpolationWithProvenance, type KnowledgeHintReader, LIVE_KEEPALIVE_QUIET_MS, LIVE_SNAPSHOT_INTERVAL_MS, LIVE_STREAM_ACK_BOUND_MS, LIVE_STREAM_STOP_GRACE_MS, LLMAssertionEvaluator, LLMPlanner, LLMVariableExtractor, LLMVerifier, type LiveStreamCapability, type LiveStreamHub, type LiveStreamRegistration, type LoopEventEmitPort, type LoopLogger, type LoopPorts, type LoopScopedLogger, MAX_TO_END_SWIPES, MINT_VERBS, type MemberEventSink, type MemberEvidenceContext, type MemberRunConfig, type MemberStepSpec, type MemberTest, type MemberTestExecutor, type MemberTestRunContext, type MintVerb, MissingSecretError, type NetworkLogEntry, type NonActionToolHandler, type NonActionToolMap, OBSERVATION_LINE_PREFIX, type ObserveOptions, type OpenAppMeta, type OperationCaptureSupport, POST_VERDICT_STEP_BUDGET_MS, type PersistedRecording, type PlanResult, type Planner, type PlannerConfig, type PlanningCallGate, PlanningLimitReachedError, PlanningTurnError, type PlanningTurnFailure, type PlanningTurnFailureReason, type PlanningTurnResult, type PlanningTurnSuccess, type PlatformAdapter, type PlatformConfig, type PostVerdictOutcome, type PostVerdictPort, type PostVerdictStepInput, RECORD_ACTION_LINE_CAP, RECORD_LINE_CHAR_CAP, RECORD_LIST_CAP, ROW_CONTAINER_ROLES, RUNTIME_IMAGE_MAP, type RecordAdmission, type RecordLedger, type RecordSubActionInput, type RecordedAction, type RecordedActionOutcome, type RecordedRead, type RecordedReadKind, type RecordingCapability, type RecordingStart, type RecordingStop, type RefBinding, type RenderedCautionLine, type RenderedStepRecord, ReplayIncompleteError, type ReportValueInput, type ReportedValueMeta, type RootCauseInput, type RunArtifactStorePort, type RunConfig, type RunEventBus, type RunHooksOptions, type RunJSMatch, type RunJsHandler, type RunMemberDescriptor, type RunPorts, type RunTimerPort, type RunnerDegradeOptions, type RunnerDegradeOutcome, type RuntimeAuthStateConfig, SCROLL_OUTCOMES_READ_ONLY, SCROLL_OUTCOMES_WRITTEN, type SandboxRunnerOptions, type SavedFileComparison, type SavedFileExpectation, type ScorerOptions, type ScreenConformanceCase, type ScreenshotCompressor, type ScriptedVerdict, type ScrollEndedBy, type ScrollLoopResult, type ScrollOffsets, type ScrollPrimitives, type ScrollUntilVisibleMeta, SecretConfigError, type SecretFileMetadata, SecretRedactor, type SecretRedactorPort, type SecretResolver, SecretStore, type SecretTemplate, type ServedCautions, type ServedRunBrief, type ShellActionMeta, type StatedTarget, type StatedTargets, type StepAnnotation, type StepContext, type StepModelAttempt, type StepModelBinding, type StepModelCallEvent, type StepModelCallReport, type StepModelConsumers, type StepModelObservation, type StepModelRoleFacts, type StepModelScope, type StepModelScopeFactory, type StepModelScopeKey, type StepModelScopeOptions, type StepModelSnapshot, type StepPhaseEvent, StepRecordAccumulator, type StepResult, type StepStatus, type StepTrace, type StorageStateBlob, type StorageStatePort, type StorageStateReference, type SubActionTrace, type SwipeSignal, type TargetVisibility, type TestResult, type TestStatus, type TimeoutConfig, type TokenAccounting, type TokenUsage, type ToolCategory, type ToolDefinition, type ToolExchange, ToolRegistry, UNKNOWN_SIGNAL_RATIONALE, type UniqueValueGenerator, type UniqueValueInput, type UniqueValueMeta, type UntilVisibleParams, type VariableExtractor, type VariableSource, VariableStore, type VariableStoreOptions, type VerificationResult, VerificationResultSchema, type Verifier, type VerifierStepRecord, type VerifyResult, type WorkingMemoryPort, type WorkingMemoryProvenanceContext, WorkingMemoryStore, assembleBriefTiers, assembleHandoff, assemblePerTestOutcome, assertNever, buildAssertionPrompt, buildAuthStateHookEnv, buildCacheableStepInput, buildCachedPlanValue, buildContextTier, buildExtractionPrompt, buildScreenState, buildSystemPrompt, buildTools, buildVerificationPrompt, buildVerifierStableTier, buildVolatileTier, classifyRootCause, classifyStep, coerceRunJSResult, collapseAnnotation, compareAssertValue, compareFillReread, compareSavedFile, composeTurnMessages, containsRedactedSecretMarker, convertKeysForPlatform, createAsserter, createExtractor, createLiveStreamHub, createMemberEventSink, createMemoryTools, createRecordLedger, createRunEventBus, createSnapshotLiveStream, createStepModelScope, createTimeoutAbortReason, defaultLiveStreamTimer, defaultRegistry, defaultUniqueValueGenerator, deriveAggregateVerdict, deriveMemberOutcome, desiredStateSatisfied, deterministicDescriptorMatcher, deterministicVerdict, documentSwipeSignal, estimateRenderedServingCost, estimateTokens, executePlanningTurn, executeStep, findBareVariables, findSecretTemplates, findUnresolvedTemplates, foldCacheStatus, formatAction, generateFailureSummary, getTimeoutAbortReason, imageSizeOf, interpolateSecretTemplates, interpolateVariables, interpolateVariablesWithProvenance, isCanonicalHookIdShape, isMacPlatform, isReservedAuthStateHookEnvKey, isTestTimeoutMessage, judgeStatedTarget, literalSecretMarkerRefusal, liveStreamFor, makeEmptyServedBrief, makeInterimNodes, makeScreenState, mapVerdictToExitCode, memberStepText, metVerification, mintReportedValue, mintUniqueValue, normalizePointerActionForStep, notMetVerification, parseAppiumInline, parseEnvFile, parseHookInline, parseRunJSInline, projectLegacyTrace, projectRiskAction, readAiJudgmentMeta, readAssertValueOutcomeMeta, readClipboardMeta, readDownloadMeta, readFillRefusalMeta, readFillRereadMeta, readFillSubmitMeta, readFillVerdictMeta, readOpenAppMeta, readReportedValueMeta, readScrollUntilVisibleMeta, readShellActionMeta, readUniqueValueMeta, redactSecretValue, renderBriefAsHypotheses, renderBriefLine, renderCautionLine, renderCautionSummary, renderObservationLine, renderScreenTree, renderStepRecord, resolveAppName, resolveSecretEnv, resolveSecretTemplatesInValue, rowContains, rowTextOf, runDirectionScroll, runHooks, runMemberTest, runToEndScroll, runUntilVisibleLoop, screenConformanceCases, scriptedVerification, scrollerSetSwipeSignal, serializeEnvFile, skippedPerTestOutcome, stampCaptureMode, startRun, stripHookInline, stripReservedAuthStateHookEnv, swipeSignalFromOffsets, tierForEntry, toGroundedLocator, toVerificationResult, toolCallToActionPlan, withAbort, withStepModelCall, wordTokens };