taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/dist/application/generation/generation-step-executor.js

@@ -1,20 +1,31 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { appProcessPids, primaryAppPid } from "../../domain/app-process.js";
-import { GenerationSessionSchema, GenerationInFlightSchema, expandProposedStepVariables, hashGenerationConfirmationEvidence } from "../../domain/generation.js";
+import { GenerationSessionSchema, GenerationInFlightSchema, expandProposedStepVariables, hashGenerationConfirmationEvidence, isGenerationConfirmationExpired } from "../../domain/generation.js";
 import { JourneyStepSchema } from "../../domain/journey.js";
+import { uiBackendIdAsSelection } from "../../domain/ui-backend.js";
+import { assessWindowHierarchy } from "../../domain/window-hierarchy.js";
 import { ProposedStepSchema, hashProposedStep } from "../../domain/proposed-step.js";
 import { RuntimeSnapshotSchema, hashRuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+import { isKnownSystemPackage, isSystemScenario } from "../../domain/system-app-profiles.js";
 import { ExpectationEvaluator } from "../assertion/expectation-evaluator.js";
+import { GuardedExpectationObservations, settledExpectationForeground } from "../assertion/guarded-expectation.js";
 import { LogcatCollector } from "../collector/logcat-collector.js";
+import { logcatStopFailed } from "../collector/logcat-stop.js";
+import { resolveActionTarget } from "../interaction/action-target.js";
 import { ActionExecutor } from "../interaction/action-executor.js";
 import { ScrollToExecutor } from "../interaction/scroll-to-executor.js";
+import { BridgeRunner, ExternalStepRunner, idleTimeoutDetails } from "../interaction/external-step-runner.js";
 import { resolveLocator } from "../locator/locator-resolver.js";
 import { IdleWaiter } from "../wait/idle-waiter.js";
+import { deviceIdentityResolver } from "../wait/idle-profiles.js";
+import { withIdleAdvice } from "../wait/idle-advice.js";
 import { summarizeProposedStep } from "./generation-confirmation-service.js";
 import { GenerationOperationError } from "./generation-starter.js";
 import { RiskEvaluator } from "./risk-evaluator.js";
 import { hasExactlyOneEnabledFocusedElement } from "./focused-input.js";
+import { closeUiSnapshotProvider } from "../ui/ui-snapshot-lifecycle.js";
+import { uiStabilityProbe } from "../ui/ui-stability-probe.js";
 class StepCancelledError extends Error {
     name = "StepCancelledError";
 }
@@ -64,7 +75,8 @@ function asFailure(error) {
         && typeof error.code === "string") {
         return {
             code: error.code,
-            message: error instanceof Error ? error.message : error.code
+            message: error instanceof Error ? error.message : error.code,
+            ...("details" in error ? { details: error.details } : {})
         };
     }
     return {
@@ -72,8 +84,8 @@ function asFailure(error) {
         message: error instanceof Error ? error.message : "Unknown step failure"
     };
 }
-function fail(code, message) {
-    throw Object.assign(new Error(message), { code });
+function fail(code, message, details) {
+    throw Object.assign(new Error(message), { code, ...(details === undefined ? {} : { details }) });
 }
 function sameSession(left, right) {
     return JSON.stringify(left) === JSON.stringify(right);
@@ -94,7 +106,7 @@ function exactApprovedChallenge(session, proposal, snapshot, source, now) {
             source
         })
         || challenge.actionSummary !== summarizeProposedStep(proposal)
-        || now.getTime() >= new Date(challenge.expiresAt).getTime()) {
+        || isGenerationConfirmationExpired(challenge, now)) {
         throw new GenerationOperationError("RISK_CONFIRMATION_REQUIRED", "An exact non-expired approved confirmation is required");
     }
     return challenge;
@@ -125,38 +137,41 @@ function assertBaseAuthorization(session, proposal, snapshot) {
         throw new GenerationOperationError("SNAPSHOT_STALE", "Proposal is not bound to the authoritative generation snapshot");
     }
 }
-function executableStep(proposal, variables, after) {
+function executableStep(proposal, variables, after, extra) {
     const expanded = expandProposedStepVariables(proposal, variables);
-    const action = Object.fromEntries(Object.entries(expanded).filter(([key]) => key !== "binding" && key !== "activity"));
+    const action = Object.fromEntries(Object.entries(expanded).filter(([key]) => key !== "binding" && key !== "activity" && key !== "flow"));
     return JourneyStepSchema.parse({
         ...action,
+        ...(extra === undefined ? {} : extra),
         activity: {
             before: expanded.activity.before,
             after
         }
     });
 }
-function requireTarget(layout, step) {
-    if (step.action !== "click"
+function requireTarget(layout, step, viewport) {
+    if ((step.action !== "click"
         && step.action !== "longClick"
-        && step.action !== "swipe") {
+        && step.action !== "swipe")
+        || step.locator === undefined) {
         return undefined;
     }
-    const resolution = resolveLocator(layout, step.locator);
+    const resolution = resolveActionTarget(layout, step.action, step.locator, viewport);
     if (resolution.status !== "found") {
         fail(resolution.code, resolution.message);
     }
-    if (step.action === "click" && resolution.element.clickable !== true) {
-        fail("ACTION_FAILED", "click target is not clickable");
-    }
-    if (step.action === "longClick"
-        && resolution.element.longClickable !== true) {
-        fail("ACTION_FAILED", "longClick target is not longClickable");
+    return resolution.target;
+}
+function requireBridgeTrigger(layout, step, viewport) {
+    const resolution = resolveLocator(layout, step.triggerLocator, {
+        requiredCapability: "clickable",
+        viewport
+    });
+    if (resolution.status !== "found") {
+        fail(resolution.code, resolution.message);
     }
-    if (step.action === "swipe"
-        && (resolution.element.scrollable !== true
-            || resolution.element.bounds === undefined)) {
-        fail("ACTION_FAILED", "swipe target lacks scrollable bounds");
+    if (resolution.element.clickable !== true) {
+        fail("ACTION_FAILED", "bridge trigger target is not clickable");
     }
     return {
         point: resolution.point,
@@ -168,16 +183,127 @@ function requireTarget(layout, step) {
 export class GenerationStepExecutor {
     dependencies;
     riskEvaluator = new RiskEvaluator();
+    currentViewport;
+    currentUiSnapshot;
     constructor(dependencies) {
         this.dependencies = dependencies;
     }
+    boundUiSnapshotProvider() {
+        const uiSnapshotProvider = this.dependencies.uiSnapshotProvider;
+        if (uiSnapshotProvider === undefined) {
+            throw new Error("Generation UI snapshot provider is not bound");
+        }
+        return uiSnapshotProvider;
+    }
+    boundViews() {
+        const views = this.dependencies.views;
+        if (views === undefined) {
+            throw new Error("Generation runtime session views are not bound");
+        }
+        return views;
+    }
+    requireCurrentViewport() {
+        if (this.currentViewport === undefined) {
+            throw new Error("Generation UI snapshot viewport is unavailable");
+        }
+        return this.currentViewport;
+    }
+    requireCurrentUiSnapshot() {
+        if (this.currentUiSnapshot === undefined) {
+            throw new Error("Generation UI snapshot metadata is unavailable");
+        }
+        return this.currentUiSnapshot;
+    }
+    async captureLayout(reason, timeoutMs, signal) {
+        const uiSnapshotProvider = this.boundUiSnapshotProvider();
+        const snapshot = await uiSnapshotProvider.capture({
+            reason,
+            freshness: "sameMutationEpoch",
+            timeoutMs,
+            ...(signal === undefined ? {} : { signal })
+        });
+        this.currentViewport = snapshot.viewport;
+        this.currentUiSnapshot = {
+            observationId: snapshot.observationId,
+            capturedAt: snapshot.capturedAt,
+            durationMs: snapshot.durationMs,
+            backend: snapshot.backend,
+            viewport: snapshot.viewport
+        };
+        return snapshot.roots;
+    }
     execute = async (input) => {
+        if (this.dependencies.uiSnapshotProvider === undefined) {
+            if (this.dependencies.sessions === undefined
+                || this.dependencies.sessionPorts === undefined
+                || this.dependencies.createFreshnessGuard === undefined) {
+                throw new Error("Generation UI snapshot provider factory is unavailable");
+            }
+            const session = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+            const idle = session.idlePolicy === undefined
+                ? this.dependencies.idle
+                : session.idlePolicy;
+            const deviceSession = await this.dependencies.sessions.openSession({
+                deviceSerial: session.target.deviceSerial,
+                ...(input.signal === undefined ? {} : { signal: input.signal })
+            });
+            try {
+                const views = this.dependencies.sessionPorts(deviceSession);
+                const boundBackendSelection = uiBackendIdAsSelection(session.bindings.uiBackend.id);
+                const uiSnapshotProvider = await deviceSession.openUiSnapshots({
+                    timeoutMs: idle.timeoutMs,
+                    ...(boundBackendSelection === undefined
+                        ? {}
+                        : { backend: boundBackendSelection }),
+                    ...(this.dependencies.uiCacheEnabled === undefined
+                        ? {}
+                        : { cacheEnabled: this.dependencies.uiCacheEnabled }),
+                    ...(input.signal === undefined ? {} : { signal: input.signal })
+                });
+                try {
+                    return await new GenerationStepExecutor({
+                        ...this.dependencies,
+                        idle,
+                        freshnessGuard: this.dependencies.createFreshnessGuard(uiSnapshotProvider, views),
+                        views,
+                        uiSnapshotProvider
+                    }).execute(input);
+                }
+                finally {
+                    await closeUiSnapshotProvider(uiSnapshotProvider);
+                }
+            }
+            finally {
+                await deviceSession.close();
+            }
+        }
+        const freshnessGuard = this.dependencies.freshnessGuard;
+        if (freshnessGuard === undefined) {
+            throw new Error("Generation freshness guard is unavailable");
+        }
+        const executionStartedAt = this.dependencies.clock.now();
+        const timing = {
+            freshnessCheckMs: 0,
+            evidenceSetupMs: 0,
+            logcatStartMs: 0,
+            preActionObservationMs: 0,
+            actionExecutionMs: 0,
+            idleWaitMs: 0,
+            postActionObservationMs: 0,
+            expectationMs: 0,
+            logcatStopMs: 0,
+            totalMs: 0
+        };
         const proposal = ProposedStepSchema.parse(input.proposal);
         const snapshot = RuntimeSnapshotSchema.parse(input.snapshot);
         const source = z.enum(["planner", "manualOverride"]).parse(input.source);
         const session = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        if (JSON.stringify(session.bindings.uiBackend)
+            !== JSON.stringify(this.boundUiSnapshotProvider().descriptor)) {
+            throw new GenerationOperationError("CONFIG_INVALID", "Generation UI backend does not match the authoritative session");
+        }
         assertBaseAuthorization(session, proposal, snapshot);
-        const risk = this.riskEvaluator.evaluate(proposal.action, session.target.interactionPolicy);
+        const risk = this.riskEvaluator.evaluate(proposal, session.target.interactionPolicy, snapshot);
         if (risk.effectiveRisk === "forbidden") {
             throw new GenerationOperationError("ACTION_FORBIDDEN", `${proposal.action} is forbidden by the Core interaction policy`);
         }
@@ -208,7 +334,15 @@ export class GenerationStepExecutor {
         }
         let fresh;
         try {
-            fresh = await this.dependencies.freshnessGuard.assertFresh(proposal.binding, input.signal, approved);
+            const freshnessStartedAt = this.dependencies.clock.now();
+            fresh = await freshnessGuard.assertFresh(proposal.binding, input.signal, approved, 
+            // A wait proposal has no Locator target; a pure Layout change (a
+            // loading indicator that settled between bind and execute) is not
+            // a reason to force a re-observe round trip.
+            proposal.action === "wait"
+                ? { layoutChangeFrom: snapshot }
+                : undefined);
+            timing.freshnessCheckMs = (this.dependencies.clock.now() - freshnessStartedAt);
         }
         catch (error) {
             await clearApproved();
@@ -240,7 +374,15 @@ export class GenerationStepExecutor {
                 stepIndex: session.candidateSteps.length,
                 snapshotHash: proposal.binding.snapshotHash,
                 proposalHash: hashProposedStep(proposal),
-                attemptId: this.dependencies.generateAttemptId()
+                attemptId: this.dependencies.generateAttemptId(),
+                ...(approved === undefined
+                    ? {}
+                    : {
+                        confirmation: {
+                            challengeId: approved.challengeId,
+                            approvalMode: approved.approvalMode ?? "localTty"
+                        }
+                    })
             });
         }
         catch (error) {
@@ -274,10 +416,12 @@ export class GenerationStepExecutor {
         let proposalEvidenceSha256;
         let snapshotEvidenceSha256;
         try {
+            const evidenceStartedAt = this.dependencies.clock.now();
             await this.dependencies.store.writeEvidence(session.id, proposalEvidencePath, proposal);
             proposalEvidenceSha256 = sha256(canonicalEvidenceBytes(proposal));
             await this.dependencies.store.writeEvidence(session.id, snapshotEvidencePath, snapshot);
             snapshotEvidenceSha256 = sha256(canonicalEvidenceBytes(snapshot));
+            timing.evidenceSetupMs = (this.dependencies.clock.now() - evidenceStartedAt);
         }
         catch (error) {
             await this.markRecovery(session.id, inFlight);
@@ -287,31 +431,52 @@ export class GenerationStepExecutor {
             await this.markRecovery(session.id, inFlight);
             return cancellation();
         }
-        const logcat = new LogcatCollector(this.dependencies.adb, this.dependencies.clock);
+        const logcat = new LogcatCollector(this.boundViews().adb, this.dependencies.clock);
         let logcatStarted = false;
         let finalStep;
         let outcome;
+        let stableLayout;
+        let postActionRuntime;
+        let bridgeEscapedPackageName;
+        let bridgeExternalSteps;
         const stepStartedAt = this.dependencies.clock.now();
         try {
+            const preActionStartedAt = this.dependencies.clock.now();
+            const preAction = await this.observeLive(session, authoritativePid, proposal.activity.before, input.signal, 
+            // The freshness guard already tolerated a pure Layout change for
+            // wait proposals, so the pre-action hash gate must not re-impose
+            // it; package, process, and Activity checks above still apply.
+            proposal.action === "wait" ? undefined : fresh, this.dependencies.idle.timeoutMs, this.adoptFreshSnapshotUi(fresh));
+            timing.preActionObservationMs = (this.dependencies.clock.now() - preActionStartedAt);
+            throwIfCancelled(input.signal);
+            const logcatStartedAt = this.dependencies.clock.now();
             await logcat.start({
                 deviceSerial: session.target.deviceSerial,
+                pids: preAction.pids,
                 ...(input.signal === undefined ? {} : { signal: input.signal })
             });
+            timing.logcatStartMs = (this.dependencies.clock.now() - logcatStartedAt);
             logcatStarted = true;
             throwIfCancelled(input.signal);
-            const preAction = await this.observeLive(session, authoritativePid, proposal.activity.before, input.signal, fresh);
-            logcat.scopeToPids(preAction.pids);
-            throwIfCancelled(input.signal);
+            const proposedFlow = proposal.action === "bridge"
+                ? proposal.flow
+                : undefined;
             const provisional = executableStep(proposal, session.variables, proposal.activity.before);
-            const actionExecutor = new ActionExecutor(this.dependencies.adb, session.target.deviceSerial);
-            const idleWaiter = new IdleWaiter(this.dependencies.androidCli, this.dependencies.clock, session.target.deviceSerial);
+            const actionExecutor = new ActionExecutor(this.boundViews().adb, session.target.deviceSerial, () => this.boundUiSnapshotProvider().invalidate?.("beforeAction"));
+            const idleWaiter = new IdleWaiter(uiStabilityProbe(this.boundUiSnapshotProvider(), this.boundViews().uiStability), this.dependencies.clock, session.target.deviceSerial, session.target.packageName, deviceIdentityResolver(this.boundViews().adb, {
+                packageName: session.target.packageName,
+                deviceSerial: session.target.deviceSerial,
+                timeoutMs: this.dependencies.idle.timeoutMs
+            }));
             if (provisional.action === "scrollTo") {
+                const actionStartedAt = this.dependencies.clock.now();
                 const scroll = await new ScrollToExecutor({
-                    androidCli: this.dependencies.androidCli,
+                    uiSnapshotProvider: this.boundUiSnapshotProvider(),
                     actionExecutor,
                     idleWaiter,
                     deviceSerial: session.target.deviceSerial,
                     idle: this.dependencies.idle,
+                    viewport: () => this.currentViewport,
                     beforeSwipe: async () => {
                         const guarded = await this.observeLive(session, authoritativePid, proposal.activity.before, input.signal);
                         return guarded.layout;
@@ -321,6 +486,9 @@ export class GenerationStepExecutor {
                     },
                     requireLiveContainerCapability: true
                 }).execute(provisional, input.signal, preAction.layout);
+                const scrollDurationMs = (this.dependencies.clock.now() - actionStartedAt);
+                timing.idleWaitMs = scroll.idleDurationMs;
+                timing.actionExecutionMs = Math.max(0, scrollDurationMs - timing.idleWaitMs);
                 throwIfCancelled(input.signal);
                 if (scroll.status === "cancelled") {
                     outcome = {
@@ -329,11 +497,77 @@ export class GenerationStepExecutor {
                     };
                 }
                 else if (scroll.status === "failed") {
-                    fail(scroll.code, scroll.message);
+                    fail(scroll.code, scroll.message, scroll.idle === undefined
+                        ? undefined
+                        : { idle: scroll.idle });
+                }
+            }
+            else if (provisional.action === "bridge") {
+                throwIfCancelled(input.signal);
+                await this.assertForegroundIdentity(session, authoritativePid, proposal.activity.before, input.signal);
+                throwIfCancelled(input.signal);
+                const triggerTarget = requireBridgeTrigger(preAction.layout, provisional, preAction.viewport);
+                const scenario = provisional.scenario;
+                const bridge = await new BridgeRunner({
+                    adb: this.boundViews().adb,
+                    clock: this.dependencies.clock,
+                    actionExecutor,
+                    externalSteps: this.externalStepRunner(session),
+                    idleWaiter,
+                    idle: this.dependencies.idle,
+                    packageName: session.target.packageName,
+                    deviceSerial: session.target.deviceSerial
+                }).run({
+                    trigger: {
+                        step: JourneyStepSchema.parse({
+                            action: "click",
+                            locator: provisional.triggerLocator,
+                            activity: {
+                                before: provisional.activity.before,
+                                after: provisional.activity.before
+                            }
+                        }),
+                        target: triggerTarget
+                    },
+                    escapeTimeoutMs: provisional.escapeTimeoutMs ?? 3000,
+                    returnTimeoutMs: provisional.returnTimeoutMs,
+                    acceptEscape: (escapedPackageName) => {
+                        if (isSystemScenario(scenario)
+                            && !isKnownSystemPackage(scenario, escapedPackageName)) {
+                            fail("SCENARIO_PACKAGE_MISMATCH", `Escaped package "${escapedPackageName}" is not a known ${scenario} package`);
+                        }
+                        return undefined;
+                    },
+                    external: {
+                        kind: "steps",
+                        steps: (escapedPackageName) => (proposedFlow === undefined
+                            ? Promise.resolve(undefined)
+                            : this.resolveExternalFlow(session, proposedFlow, escapedPackageName, input.signal))
+                    },
+                    signal: input.signal
+                });
+                timing.actionExecutionMs = bridge.timing.actionMs;
+                timing.idleWaitMs = bridge.timing.waitMs;
+                if (bridge.status === "cancelled") {
+                    outcome = {
+                        status: "cancelled",
+                        failure: {
+                            code: "RECOVERY_REQUIRED",
+                            message: "Step was cancelled"
+                        }
+                    };
+                }
+                else if (bridge.status === "failed") {
+                    fail(bridge.code, bridge.message, bridge.details);
+                }
+                else {
+                    bridgeEscapedPackageName = bridge.escapedPackageName;
+                    bridgeExternalSteps = bridge.externalSteps;
+                    stableLayout = bridge.idle.layout;
                 }
             }
             else {
-                const target = requireTarget(preAction.layout, provisional);
+                const target = requireTarget(preAction.layout, provisional, preAction.viewport);
                 if (provisional.action === "inputText") {
                     if (!hasExactlyOneEnabledFocusedElement(preAction.layout)) {
                         fail("ACTION_FAILED", "inputText requires exactly one enabled focused Layout element");
@@ -343,7 +577,9 @@ export class GenerationStepExecutor {
                     throwIfCancelled(input.signal);
                     await this.assertForegroundIdentity(session, authoritativePid, proposal.activity.before, input.signal);
                     throwIfCancelled(input.signal);
+                    const actionStartedAt = this.dependencies.clock.now();
                     const action = await actionExecutor.execute(provisional, target, input.signal);
+                    timing.actionExecutionMs = (this.dependencies.clock.now() - actionStartedAt);
                     if (isCancelled(input.signal)) {
                         outcome = {
                             status: "cancelled",
@@ -358,7 +594,9 @@ export class GenerationStepExecutor {
                     }
                 }
                 if (outcome === undefined) {
+                    const idleStartedAt = this.dependencies.clock.now();
                     const idle = await idleWaiter.waitUntilIdle(this.dependencies.idle, input.signal);
+                    timing.idleWaitMs = (this.dependencies.clock.now() - idleStartedAt);
                     if (idle.status === "cancelled") {
                         outcome = {
                             status: "cancelled",
@@ -369,55 +607,42 @@ export class GenerationStepExecutor {
                         };
                     }
                     else if (idle.status === "timeout") {
-                        fail(idle.code, "Layout did not become stable before timeout");
+                        fail(idle.code, withIdleAdvice("Layout did not become stable before timeout", idle), idleTimeoutDetails(idle));
+                    }
+                    else {
+                        stableLayout = idle.layout;
                     }
                     throwIfCancelled(input.signal);
                 }
             }
             if (outcome === undefined) {
                 throwIfCancelled(input.signal);
-                const after = await this.observeLive(session, authoritativePid, undefined, input.signal);
+                const postActionStartedAt = this.dependencies.clock.now();
+                const after = await this.observeLive(session, authoritativePid, undefined, input.signal, undefined, this.dependencies.idle.timeoutMs, stableLayout);
+                timing.postActionObservationMs = (this.dependencies.clock.now() - postActionStartedAt);
+                postActionRuntime = after;
                 logcat.scopeToPids(after.pids);
-                finalStep = executableStep(proposal, session.variables, after.activity);
+                const bridgeExtra = {};
+                if (bridgeEscapedPackageName !== undefined) {
+                    bridgeExtra.escapedPackageName = bridgeEscapedPackageName;
+                }
+                if (bridgeExternalSteps !== undefined) {
+                    bridgeExtra.externalSteps = bridgeExternalSteps;
+                    bridgeExtra.replayMode = "auto";
+                }
+                finalStep = executableStep(proposal, session.variables, after.activity, Object.keys(bridgeExtra).length === 0 ? undefined : bridgeExtra);
                 if (finalStep.expect !== undefined) {
-                    const expectation = await new ExpectationEvaluator(this.dependencies.adb, this.dependencies.androidCli, logcat, this.dependencies.clock).evaluate(finalStep.expect, {
+                    const expectationStartedAt = this.dependencies.clock.now();
+                    const observations = new GuardedExpectationObservations({
+                        activity: (observation) => this.assertForegroundIdentity(session, authoritativePid, undefined, observation.signal, observation.timeoutMs),
+                        layout: (observation) => this.observeLive(session, authoritativePid, after.activity, observation.signal, undefined, observation.timeoutMs),
+                        rethrow: (error) => error instanceof StepCancelledError
+                    }, after);
+                    const expectation = await new ExpectationEvaluator(this.boundViews().adb, this.boundUiSnapshotProvider(), logcat, this.dependencies.clock).evaluate(finalStep.expect, {
                         packageName: session.target.packageName,
                         deviceSerial: session.target.deviceSerial,
                         stepStartedAt
-                    }, input.signal, {
-                        activity: async (observation) => {
-                            try {
-                                const activity = await this.assertForegroundIdentity(session, authoritativePid, undefined, observation.signal, observation.timeoutMs);
-                                return { status: "observed", activity };
-                            }
-                            catch (error) {
-                                if (error instanceof StepCancelledError)
-                                    throw error;
-                                return {
-                                    status: "failed",
-                                    message: error instanceof Error
-                                        ? error.message
-                                        : "Generated Expect Activity observation failed"
-                                };
-                            }
-                        },
-                        layout: async (observation) => {
-                            try {
-                                const guarded = await this.observeLive(session, authoritativePid, after.activity, observation.signal, undefined, observation.timeoutMs);
-                                return { status: "observed", layout: guarded.layout };
-                            }
-                            catch (error) {
-                                if (error instanceof StepCancelledError)
-                                    throw error;
-                                return {
-                                    status: "failed",
-                                    message: error instanceof Error
-                                        ? error.message
-                                        : "Generated Expect Layout observation failed"
-                                };
-                            }
-                        }
-                    });
+                    }, input.signal, observations.boundary());
                     if (expectation.status === "cancelled") {
                         outcome = {
                             status: "cancelled",
@@ -432,11 +657,10 @@ export class GenerationStepExecutor {
                     }
                     else {
                         throwIfCancelled(input.signal);
-                        await this.observeLive(session, authoritativePid, finalStep.expect.type === "activity"
-                            ? finalStep.expect.value
-                            : after.activity, input.signal);
+                        postActionRuntime = await this.settledExpectationRuntime(session, authoritativePid, finalStep.expect, after, observations.lastLayoutObservation(), input.signal);
                         throwIfCancelled(input.signal);
                     }
+                    timing.expectationMs = (this.dependencies.clock.now() - expectationStartedAt);
                 }
             }
         }
@@ -447,15 +671,13 @@ export class GenerationStepExecutor {
         }
         let stopFailure;
         if (logcatStarted) {
+            const logcatStopStartedAt = this.dependencies.clock.now();
             try {
                 const stopped = await logcat.stop();
                 if (isCancelled(input.signal)) {
                     outcome = cancellation();
                 }
-                if (stopped.exitCode !== 0
-                    || stopped.timedOut
-                    || stopped.cancelled
-                    || stopped.spawnError !== undefined) {
+                if (logcatStopFailed(stopped)) {
                     stopFailure = {
                         code: "COLLECTION_FAILED",
                         message: stopped.stderr.trim()
@@ -472,12 +694,15 @@ export class GenerationStepExecutor {
                         : "Logcat collector failed to stop"
                 };
             }
+            timing.logcatStopMs = (this.dependencies.clock.now() - logcatStopStartedAt);
         }
         outcome ??= stopFailure === undefined
             ? { status: "succeeded", step: finalStep }
             : { status: "failed", failure: stopFailure };
+        timing.totalMs = this.dependencies.clock.now() - executionStartedAt;
+        outcome = { ...outcome, timing };
         const log = logcatStarted
-            ? logcat.lines().map((line) => line.raw).join("\n")
+            ? logcat.rawLines().map((line) => line.raw).join("\n")
             : "";
         try {
             await this.dependencies.store.writeTextEvidence(session.id, executionPath(inFlight, "logcat.txt"), log.length === 0 ? "" : `${log}\n`);
@@ -506,6 +731,9 @@ export class GenerationStepExecutor {
                     path: snapshotEvidencePath,
                     sha256: snapshotEvidenceSha256
                 },
+                ...(inFlight.confirmation === undefined
+                    ? {}
+                    : { confirmation: inFlight.confirmation }),
                 outcome,
                 ...(stopFailure === undefined
                     ? {}
@@ -553,25 +781,95 @@ export class GenerationStepExecutor {
                 }
                 throw new GenerationOperationError("RECOVERY_REQUIRED", "Step completion state is ambiguous and requires recovery");
             }
-            return outcome;
+            if (this.dependencies.observeNext === undefined
+                || postActionRuntime === undefined) {
+                return outcome;
+            }
+            const nextObservationStartedAt = this.dependencies.clock.now();
+            try {
+                const nextObservation = await this.dependencies.observeNext({
+                    generationId: session.id,
+                    runtime: {
+                        foregroundPackageName: postActionRuntime.foregroundPackageName,
+                        activity: postActionRuntime.activity,
+                        pid: postActionRuntime.pid,
+                        layout: postActionRuntime.layout,
+                        windowHierarchy: postActionRuntime.windowHierarchy,
+                        uiSnapshot: postActionRuntime.uiSnapshot
+                    },
+                    ...(input.signal === undefined ? {} : { signal: input.signal })
+                });
+                return {
+                    ...outcome,
+                    timing: {
+                        ...timing,
+                        nextObservationMs: (this.dependencies.clock.now() - nextObservationStartedAt)
+                    },
+                    nextObservation
+                };
+            }
+            catch (error) {
+                return {
+                    ...outcome,
+                    timing: {
+                        ...timing,
+                        nextObservationMs: (this.dependencies.clock.now() - nextObservationStartedAt)
+                    },
+                    nextObservationFailure: asFailure(error)
+                };
+            }
         }
         await this.markRecovery(session.id, inFlight);
         return outcome;
     };
-    async observeLive(session, expectedPid, expectedActivity, signal, authoritativeSnapshot, timeoutMs = this.dependencies.idle.timeoutMs) {
-        const deadline = this.dependencies.clock.now() + timeoutMs;
+    /**
+     * The freshness guard captured this Layout and proved it equals the
+     * authoritative binding hash, and nothing mutates the device between that
+     * capture and the pre-action observation, so re-capturing it would only
+     * repeat the most expensive device call of the step.
+     */
+    adoptFreshSnapshotUi(fresh) {
+        this.currentViewport = fresh.viewport;
+        this.currentUiSnapshot = {
+            observationId: fresh.uiObservationId,
+            capturedAt: fresh.capturedAt,
+            durationMs: fresh.uiCaptureDurationMs,
+            backend: fresh.uiBackend,
+            viewport: fresh.viewport
+        };
+        return fresh.layout;
+    }
+    /**
+     * The post-action runtime after a passing expectation: an `element`
+     * expectation already observed it, and a proven `activity` expectation on
+     * the post-action Activity adds nothing to re-observe. Otherwise the
+     * settled foreground is observed again.
+     */
+    async settledExpectationRuntime(session, expectedPid, expectation, after, lastLayoutObservation, signal) {
+        const settled = settledExpectationForeground(expectation, after.activity);
+        if (expectation.type === "element") {
+            return lastLayoutObservation ?? after;
+        }
+        if (settled.proven && settled.activity === after.activity) {
+            return after;
+        }
+        return this.observeLive(session, expectedPid, settled.activity, signal);
+    }
+    async observeLive(session, expectedPid, expectedActivity, signal, authoritativeSnapshot, timeoutMs = this.dependencies.idle.timeoutMs, stableLayout) {
+        const deadline = this.dependencies.clock.now()
+            + Math.max(timeoutMs, this.dependencies.idle.timeoutMs);
         const identity = () => ({
             packageName: session.target.packageName,
             deviceSerial: session.target.deviceSerial,
             ...(signal === undefined ? {} : { signal }),
             timeoutMs: Math.max(1, deadline - this.dependencies.clock.now())
         });
-        const foreground = await this.dependencies.adb.foregroundComponent(identity());
+        const foreground = await this.boundViews().adb.foregroundComponent(identity());
         throwIfCancelled(signal);
         if (foreground.packageName !== session.target.packageName) {
             fail("PACKAGE_ESCAPE", "Foreground package escaped generation target");
         }
-        const processes = await this.dependencies.adb.appProcesses(identity());
+        const processes = await this.boundViews().adb.appProcesses(identity());
         const pid = primaryAppPid(processes, session.target.packageName);
         throwIfCancelled(signal);
         if (pid === null || pid !== expectedPid) {
@@ -581,26 +879,33 @@ export class GenerationStepExecutor {
             && foreground.activity !== expectedActivity) {
             fail("SNAPSHOT_STALE", "Generation Activity changed unexpectedly");
         }
-        const layout = await this.dependencies.androidCli.layout({
-            deviceSerial: session.target.deviceSerial,
-            ...(signal === undefined ? {} : { signal }),
-            timeoutMs: Math.max(1, deadline - this.dependencies.clock.now())
-        });
-        throwIfCancelled(signal);
-        const confirmedForeground = await this.dependencies.adb
-            .foregroundComponent(identity());
+        const [layout, topology] = await Promise.all([
+            stableLayout === undefined
+                ? this.captureLayout("locate", Math.max(1, deadline - this.dependencies.clock.now()), signal)
+                : Promise.resolve(stableLayout),
+            this.boundViews().adb.windowTopology(identity())
+        ]);
+        const windowHierarchy = assessWindowHierarchy(topology, layout);
         throwIfCancelled(signal);
-        if (confirmedForeground.packageName !== session.target.packageName) {
-            fail("PACKAGE_ESCAPE", "Foreground package escaped generation target");
-        }
-        const confirmedPid = primaryAppPid(await this.dependencies.adb.appProcesses(identity()), session.target.packageName);
-        throwIfCancelled(signal);
-        if (confirmedPid === null || confirmedPid !== expectedPid) {
-            fail("APP_CRASHED", "Generation process identity changed");
-        }
-        if (confirmedForeground.activity
-            !== (expectedActivity ?? foreground.activity)) {
-            fail("SNAPSHOT_STALE", "Generation Activity changed unexpectedly");
+        // A Layout captured here must be bracketed by a second identity check.
+        // A settled Layout passed in was captured before the checks above, so
+        // they already confirm it and a second pair would observe nothing new.
+        if (stableLayout === undefined) {
+            const confirmedForeground = await this.boundViews().adb
+                .foregroundComponent(identity());
+            throwIfCancelled(signal);
+            if (confirmedForeground.packageName !== session.target.packageName) {
+                fail("PACKAGE_ESCAPE", "Foreground package escaped generation target");
+            }
+            const confirmedPid = primaryAppPid(await this.boundViews().adb.appProcesses(identity()), session.target.packageName);
+            throwIfCancelled(signal);
+            if (confirmedPid === null || confirmedPid !== expectedPid) {
+                fail("APP_CRASHED", "Generation process identity changed");
+            }
+            if (confirmedForeground.activity
+                !== (expectedActivity ?? foreground.activity)) {
+                fail("SNAPSHOT_STALE", "Generation Activity changed unexpectedly");
+            }
         }
         if (authoritativeSnapshot !== undefined) {
             const liveHash = hashRuntimeSnapshot({
@@ -608,7 +913,10 @@ export class GenerationStepExecutor {
                 foregroundPackageName: foreground.packageName,
                 activity: foreground.activity,
                 pid,
-                layout
+                layout,
+                ...(authoritativeSnapshot.windowHierarchy === undefined
+                    ? {}
+                    : { windowHierarchy })
             });
             const authoritativeHash = hashRuntimeSnapshot(authoritativeSnapshot);
             if (liveHash !== authoritativeHash) {
@@ -620,18 +928,22 @@ export class GenerationStepExecutor {
             activity: foreground.activity,
             pid,
             pids: appProcessPids(processes),
-            layout
+            layout,
+            viewport: this.requireCurrentViewport(),
+            uiSnapshot: this.requireCurrentUiSnapshot(),
+            windowHierarchy
         };
     }
     async assertForegroundIdentity(session, expectedPid, expectedActivity, signal, timeoutMs = this.dependencies.idle.timeoutMs) {
-        const deadline = this.dependencies.clock.now() + timeoutMs;
+        const deadline = this.dependencies.clock.now()
+            + Math.max(timeoutMs, this.dependencies.idle.timeoutMs);
         const identity = () => ({
             packageName: session.target.packageName,
             deviceSerial: session.target.deviceSerial,
             ...(signal === undefined ? {} : { signal }),
             timeoutMs: Math.max(1, deadline - this.dependencies.clock.now())
         });
-        const foreground = await this.dependencies.adb.foregroundComponent(identity());
+        const foreground = await this.boundViews().adb.foregroundComponent(identity());
         throwIfCancelled(signal);
         if (foreground.packageName !== session.target.packageName) {
             fail("PACKAGE_ESCAPE", "Foreground package escaped generation target");
@@ -640,7 +952,7 @@ export class GenerationStepExecutor {
             && foreground.activity !== expectedActivity) {
             fail("SNAPSHOT_STALE", "Generation Activity changed before mutation");
         }
-        const pid = primaryAppPid(await this.dependencies.adb.appProcesses(identity()), session.target.packageName);
+        const pid = primaryAppPid(await this.boundViews().adb.appProcesses(identity()), session.target.packageName);
         throwIfCancelled(signal);
         if (pid === null || pid !== expectedPid) {
             fail("APP_CRASHED", "Generation process identity changed");
@@ -665,4 +977,55 @@ export class GenerationStepExecutor {
         });
         await this.dependencies.store.update(generationId, latest.revision, recovery);
     }
+    /** Resolves and validates the bound External Flow for the escaped app. */
+    async resolveExternalFlow(session, flowName, escapedPackageName, signal) {
+        if (this.dependencies.externalFlowResolver === undefined) {
+            fail("EXTERNAL_FLOW_NOT_FOUND", "External Flow resolver is unavailable in this runtime");
+        }
+        const binding = session.externalFlows.find((entry) => entry.name === flowName);
+        if (binding === undefined) {
+            fail("EXTERNAL_FLOW_NOT_FOUND", `External Flow "${flowName}" is not bound to generation session ${session.id}`);
+        }
+        const resolution = await this.dependencies.externalFlowResolver.resolve({
+            projectRoot: this.dependencies.projectRoot,
+            name: flowName
+        });
+        if (resolution.flowSha256 !== binding.flowSha256) {
+            fail("EXTERNAL_FLOW_STALE", `External Flow "${flowName}" has changed since session start`);
+        }
+        if (resolution.flow.escapedPackageName !== binding.escapedPackageName) {
+            fail("EXTERNAL_PACKAGE_MISMATCH", `External Flow "${flowName}" escaped package does not match session binding`);
+        }
+        if (resolution.flow.escapedPackageName !== escapedPackageName) {
+            fail("EXTERNAL_PACKAGE_MISMATCH", `Escaped package "${escapedPackageName}" does not match Flow package "${resolution.flow.escapedPackageName}"`);
+        }
+        if (resolution.flow.expectedEscapeActivity !== undefined) {
+            const foreground = await this.boundViews().adb.foregroundComponent({
+                packageName: escapedPackageName,
+                deviceSerial: session.target.deviceSerial,
+                ...(signal === undefined ? {} : { signal }),
+                timeoutMs: 5000
+            });
+            if (foreground.activity !== resolution.flow.expectedEscapeActivity) {
+                fail("EXTERNAL_ACTIVITY_MISMATCH", `External escape Activity "${foreground.activity}" does not match expected "${resolution.flow.expectedEscapeActivity}"`);
+            }
+        }
+        return resolution.flow.steps;
+    }
+    externalStepRunner(session) {
+        return new ExternalStepRunner({
+            adb: this.boundViews().adb,
+            actionExecutor: new ActionExecutor(this.boundViews().adb, session.target.deviceSerial, () => this.boundUiSnapshotProvider().invalidate?.("beforeAction")),
+            uiSnapshotProvider: this.boundUiSnapshotProvider(),
+            captureLayout: (reason, timeoutMs, signal) => this.captureLayout(reason, timeoutMs, signal),
+            createIdleWaiter: (packageName) => new IdleWaiter(uiStabilityProbe(this.boundUiSnapshotProvider(), this.boundViews().uiStability), this.dependencies.clock, session.target.deviceSerial, packageName, deviceIdentityResolver(this.boundViews().adb, {
+                packageName,
+                deviceSerial: session.target.deviceSerial,
+                timeoutMs: this.dependencies.idle.timeoutMs
+            })),
+            idle: this.dependencies.idle,
+            viewport: () => this.currentViewport,
+            deviceSerial: session.target.deviceSerial
+        });
+    }
 }