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

package/dist/application/recorder/recorder-service.js

@@ -1,22 +1,23 @@
 import { parse } from "node:path";
 import { normalizeActivity } from "../../domain/activity.js";
 import { primaryAppPid } from "../../domain/app-process.js";
-import { JourneySchema, JourneyStepSchema } from "../../domain/journey.js";
+import { DEFAULT_DEVICE_ROLE, ExternalStepSchema, JourneySchema, JourneyStepSchema } from "../../domain/journey.js";
 import { ActionExecutor } from "../interaction/action-executor.js";
+import { BridgeRunner, ExternalStepRunner } from "../interaction/external-step-runner.js";
 import { resolveLocator } from "../locator/locator-resolver.js";
-import { launchFailure } from "../runtime/launch-failure.js";
-import { ProcessWaiter } from "../runtime/process-waiter.js";
+import { coldLaunchApp } from "../runtime/cold-launch.js";
 import { IdleWaiter } from "../wait/idle-waiter.js";
+import { deviceIdentityResolver } from "../wait/idle-profiles.js";
 import { listLocatableTargets, listRecorderTargets } from "./locator-selector.js";
+import { closeUiSnapshotProvider } from "../ui/ui-snapshot-lifecycle.js";
+/** How long the Recorder waits for a bridge trigger to leave the app. */
+const BRIDGE_ESCAPE_TIMEOUT_MS = 3000;
 function failedCommand(result) {
     return result.exitCode !== 0
         || result.timedOut
         || result.cancelled
         || result.spawnError !== undefined;
 }
-function commandMessage(result, fallback) {
-    return result.stderr.trim() || result.spawnError || fallback;
-}
 function annotatedPath(outputPath) {
     const output = parse(outputPath);
     return `${output.dir}/${output.name}.annotated.png`;
@@ -53,139 +54,163 @@ export class RecorderService {
             ...(input.signal === undefined ? {} : { signal: input.signal }),
             timeoutMs: input.config.idle.timeoutMs
         };
-        if (!await this.dependencies.adb.isInstalled(identity)) {
-            return {
-                status: "failed",
-                stepsRecorded: 0,
-                message: `Package ${input.config.run.packageName} is not installed on ${input.deviceSerial}`
-            };
-        }
-        const stopped = await this.dependencies.adb.forceStop(identity);
-        if (failedCommand(stopped)) {
-            return {
-                status: "failed",
-                stepsRecorded: 0,
-                message: commandMessage(stopped, "App reset failed")
-            };
-        }
-        const launchError = launchFailure(await this.dependencies.adb.launchActivity({
-            packageName: input.config.run.packageName,
-            activity: launchActivity,
-            deviceSerial: input.deviceSerial,
-            ...(input.signal === undefined ? {} : { signal: input.signal }),
-            timeoutMs: input.config.idle.timeoutMs
-        }));
-        if (launchError !== undefined) {
-            return {
-                status: "failed",
-                stepsRecorded: 0,
-                message: launchError
-            };
-        }
-        const processReadiness = await new ProcessWaiter(this.dependencies.adb, this.dependencies.clock).wait({
-            packageName: input.config.run.packageName,
+        const session = await this.dependencies.sessions.openSession({
             deviceSerial: input.deviceSerial,
-            pollIntervalMs: input.config.idle.pollIntervalMs,
-            timeoutMs: input.config.idle.timeoutMs,
             ...(input.signal === undefined ? {} : { signal: input.signal })
         });
-        if (processReadiness.status === "cancelled") {
-            return { status: "cancelled", stepsRecorded: 0 };
-        }
-        if (processReadiness.status === "timeout") {
-            return {
-                status: "failed",
-                stepsRecorded: 0,
-                message: "App process was not found after launch"
-            };
-        }
-        const idleWaiter = new IdleWaiter(this.dependencies.androidCli, this.dependencies.clock, input.deviceSerial);
-        await this.dependencies.androidCli.layout({
-            deviceSerial: input.deviceSerial,
-            ...(input.signal === undefined ? {} : { signal: input.signal }),
-            timeoutMs: input.config.idle.timeoutMs
-        });
-        const startupIdle = await idleWaiter.waitUntilIdle(input.config.idle, input.signal);
-        if (startupIdle.status === "cancelled") {
-            return { status: "cancelled", stepsRecorded: 0 };
-        }
-        if (startupIdle.status === "timeout") {
-            return {
-                status: "failed",
-                stepsRecorded: 0,
-                message: "Layout did not become stable before timeout"
-            };
-        }
-        const steps = [];
-        const executor = new ActionExecutor(this.dependencies.adb, input.deviceSerial);
-        for (;;) {
-            const layout = await this.dependencies.androidCli.layout({
+        try {
+            const views = this.dependencies.sessionPorts(session);
+            if (!await views.adb.isInstalled(identity)) {
+                return {
+                    status: "failed",
+                    stepsRecorded: 0,
+                    message: `Package ${input.config.run.packageName} is not installed on ${input.deviceSerial}`
+                };
+            }
+            const launched = await coldLaunchApp(views.adb, this.dependencies.clock, {
+                packageName: input.config.run.packageName,
+                activity: launchActivity,
                 deviceSerial: input.deviceSerial,
-                ...(input.signal === undefined ? {} : { signal: input.signal }),
-                timeoutMs: input.config.idle.timeoutMs
+                pollIntervalMs: input.config.idle.pollIntervalMs,
+                timeoutMs: input.config.idle.timeoutMs,
+                signal: input.signal
             });
-            const action = await this.dependencies.prompt.selectAction();
-            if (action === "cancel") {
-                return { status: "cancelled", stepsRecorded: steps.length };
+            if (launched.status === "cancelled") {
+                return { status: "cancelled", stepsRecorded: 0 };
+            }
+            if (launched.status === "failed") {
+                return {
+                    status: "failed",
+                    stepsRecorded: 0,
+                    message: launched.message
+                };
             }
-            if (action === "finish") {
-                if (steps.length === 0) {
+            const uiSnapshotProvider = await session.openUiSnapshots({
+                timeoutMs: input.config.ui?.snapshotTimeoutMs
+                    ?? input.config.idle.timeoutMs,
+                backend: input.config.ui?.backend ?? "auto",
+                cacheEnabled: input.config.ui?.cacheEnabled ?? true,
+                ...(input.signal === undefined ? {} : { signal: input.signal })
+            });
+            try {
+                const idleWaiter = new IdleWaiter(views.uiStability, this.dependencies.clock, input.deviceSerial, input.config.run.packageName, deviceIdentityResolver(views.adb, {
+                    packageName: input.config.run.packageName,
+                    deviceSerial: input.deviceSerial,
+                    timeoutMs: input.config.idle.timeoutMs
+                }));
+                await uiSnapshotProvider.capture({
+                    reason: "locate",
+                    ...(input.signal === undefined ? {} : { signal: input.signal }),
+                    timeoutMs: input.config.idle.timeoutMs
+                });
+                const startupIdle = await idleWaiter.waitUntilIdle(input.config.idle, input.signal);
+                if (startupIdle.status === "cancelled") {
+                    return { status: "cancelled", stepsRecorded: 0 };
+                }
+                if (startupIdle.status === "timeout") {
                     return {
                         status: "failed",
                         stepsRecorded: 0,
-                        message: "Journey requires at least one successful step"
+                        message: "Layout did not become stable before timeout"
                     };
                 }
-                const journey = JourneySchema.parse({
-                    version: 1,
-                    name: input.journeyName,
-                    steps
-                });
-                await this.dependencies.journeyWriter.write(input.outputPath, journey);
-                return { status: "completed", stepsRecorded: steps.length, journey };
-            }
-            const prepared = await this.prepareAction(action, layout, input);
-            if (prepared === undefined) {
-                continue;
-            }
-            // scrollTo captures `before` post-scroll by design: it does not navigate, so before==after in practice (replay checks `before` pre-scroll but the Activity is unchanged).
-            const before = normalizeActivity(input.config.run.packageName, await this.dependencies.adb.currentActivity(identity));
-            if (prepared.draft.action !== "scrollTo") {
-                const execution = await executor.execute(prepared.draft, actionTarget(prepared.target), input.signal);
-                if (execution.status === "failed") {
-                    await this.dependencies.prompt.notifyFailure(execution.message);
-                    continue;
-                }
-                const idle = await idleWaiter.waitUntilIdle(input.config.idle, input.signal);
-                if (idle.status !== "stable") {
-                    if (idle.status === "cancelled") {
+                const steps = [];
+                const executor = new ActionExecutor(views.adb, input.deviceSerial, () => uiSnapshotProvider.invalidate?.("beforeAction"));
+                for (;;) {
+                    const layout = (await uiSnapshotProvider.capture({
+                        reason: "locate",
+                        freshness: "sameMutationEpoch",
+                        ...(input.signal === undefined ? {} : { signal: input.signal }),
+                        timeoutMs: input.config.idle.timeoutMs
+                    })).roots;
+                    const action = await this.dependencies.prompt.selectAction();
+                    if (action === "cancel") {
                         return { status: "cancelled", stepsRecorded: steps.length };
                     }
-                    return {
-                        status: "failed",
-                        stepsRecorded: steps.length,
-                        message: "Layout did not become stable before timeout"
-                    };
+                    if (action === "finish") {
+                        if (steps.length === 0) {
+                            return {
+                                status: "failed",
+                                stepsRecorded: 0,
+                                message: "Journey requires at least one successful step"
+                            };
+                        }
+                        const journey = JourneySchema.parse({
+                            version: 2,
+                            name: input.journeyName,
+                            devices: [{ role: DEFAULT_DEVICE_ROLE }],
+                            steps
+                        });
+                        await this.dependencies.journeyWriter.write(input.outputPath, journey);
+                        return { status: "completed", stepsRecorded: steps.length, journey };
+                    }
+                    if (action === "bridgeTrigger") {
+                        const result = await this.recordBridgeStep(layout, input, identity, uiSnapshotProvider, views);
+                        if (result.status === "cancelled") {
+                            return { status: "cancelled", stepsRecorded: steps.length };
+                        }
+                        if (result.status === "failed") {
+                            return {
+                                status: "failed",
+                                stepsRecorded: steps.length,
+                                message: result.message
+                            };
+                        }
+                        if (result.status === "recorded") {
+                            steps.push(result.step);
+                        }
+                        continue;
+                    }
+                    const prepared = await this.prepareAction(action, layout, input, uiSnapshotProvider, views);
+                    if (prepared === undefined) {
+                        continue;
+                    }
+                    // scrollTo captures `before` post-scroll by design: it does not navigate, so before==after in practice (replay checks `before` pre-scroll but the Activity is unchanged).
+                    const before = normalizeActivity(input.config.run.packageName, await views.adb.currentActivity(identity));
+                    if (prepared.draft.action !== "scrollTo") {
+                        const execution = await executor.execute(prepared.draft, actionTarget(prepared.target), input.signal);
+                        if (execution.status === "failed") {
+                            await this.dependencies.prompt.notifyFailure(execution.message);
+                            continue;
+                        }
+                        const idle = await idleWaiter.waitUntilIdle(input.config.idle, input.signal);
+                        if (idle.status !== "stable") {
+                            if (idle.status === "cancelled") {
+                                return { status: "cancelled", stepsRecorded: steps.length };
+                            }
+                            return {
+                                status: "failed",
+                                stepsRecorded: steps.length,
+                                message: "Layout did not become stable before timeout"
+                            };
+                        }
+                    }
+                    const processes = await views.adb.appProcesses(identity);
+                    if (primaryAppPid(processes, input.config.run.packageName) === null) {
+                        return {
+                            status: "failed",
+                            stepsRecorded: steps.length,
+                            message: "App process crashed after the recorded Action"
+                        };
+                    }
+                    const after = normalizeActivity(input.config.run.packageName, await views.adb.currentActivity(identity));
+                    steps.push(JourneyStepSchema.parse({
+                        ...prepared.draft,
+                        activity: { before, after }
+                    }));
                 }
             }
-            const processes = await this.dependencies.adb.appProcesses(identity);
-            if (primaryAppPid(processes, input.config.run.packageName) === null) {
-                return {
-                    status: "failed",
-                    stepsRecorded: steps.length,
-                    message: "App process crashed after the recorded Action"
-                };
+            finally {
+                await closeUiSnapshotProvider(uiSnapshotProvider);
             }
-            const after = normalizeActivity(input.config.run.packageName, await this.dependencies.adb.currentActivity(identity));
-            steps.push(JourneyStepSchema.parse({
-                ...prepared.draft,
-                activity: { before, after }
-            }));
+        }
+        finally {
+            await session.close();
         }
     }
-    async prepareAction(action, layout, input) {
+    async prepareAction(action, layout, input, uiSnapshotProvider, views) {
         if (action === "scrollTo") {
-            return this.prepareScrollTo(layout, input);
+            return this.prepareScrollTo(layout, input, uiSnapshotProvider, views);
         }
         if (action === "inputText") {
             return {
@@ -223,7 +248,7 @@ export class RecorderService {
         }
         let fallback;
         const screenshotPath = annotatedPath(input.outputPath);
-        const capture = await this.dependencies.androidCli.captureScreen({
+        const capture = await views.screenshots.capture({
             outputPath: screenshotPath,
             annotate: true,
             deviceSerial: input.deviceSerial,
@@ -256,8 +281,8 @@ export class RecorderService {
             }
         };
     }
-    async prepareScrollTo(layout, input) {
-        const containers = listRecorderTargets(layout, "swipe");
+    async prepareScrollTo(layout, input, uiSnapshotProvider, views, packageName = input.config.run.packageName, resourceIdOnly = false) {
+        const containers = listRecorderTargets(layout, "swipe").filter((target) => !resourceIdOnly || target.locator.resourceId !== undefined);
         if (containers.length === 0) {
             await this.dependencies.prompt.notifyFailure("No scrollable element has a unique deterministic Locator");
             return undefined;
@@ -270,12 +295,16 @@ export class RecorderService {
         }
         const direction = await this.dependencies.prompt.selectSwipeDirection();
         const options = await this.dependencies.prompt.swipeOptions();
-        const executor = new ActionExecutor(this.dependencies.adb, input.deviceSerial);
-        const idleWaiter = new IdleWaiter(this.dependencies.androidCli, this.dependencies.clock, input.deviceSerial);
+        const executor = new ActionExecutor(views.adb, input.deviceSerial, () => uiSnapshotProvider.invalidate?.("beforeAction"));
+        const idleWaiter = new IdleWaiter(views.uiStability, this.dependencies.clock, input.deviceSerial, packageName, deviceIdentityResolver(views.adb, {
+            packageName,
+            deviceSerial: input.deviceSerial,
+            timeoutMs: input.config.idle.timeoutMs
+        }));
         let currentLayout = layout;
         let swipesUsed = 0;
         for (;;) {
-            const targets = listLocatableTargets(currentLayout);
+            const targets = listLocatableTargets(currentLayout).filter((target) => !resourceIdOnly || target.locator.resourceId !== undefined);
             const decision = await this.dependencies.prompt.scrollTargetDecision(targets.map((t) => ({ id: t.element.id, label: t.label })));
             if (decision.kind === "cancel") {
                 return undefined;
@@ -321,11 +350,274 @@ export class RecorderService {
                 return undefined;
             }
             swipesUsed += 1;
-            currentLayout = await this.dependencies.androidCli.layout({
-                deviceSerial: input.deviceSerial,
+            currentLayout = (await uiSnapshotProvider.capture({
+                reason: "locate",
+                freshness: "sameMutationEpoch",
                 ...(input.signal === undefined ? {} : { signal: input.signal }),
                 timeoutMs: input.config.idle.timeoutMs
+            })).roots;
+        }
+    }
+    async recordBridgeStep(layout, input, identity, uiSnapshotProvider, views) {
+        try {
+            const scenario = await this.dependencies.prompt.selectBridgeScenario();
+            const description = await this.dependencies.prompt.inputBridgeDescription(scenario);
+            const returnTimeoutMs = await this.dependencies.prompt.inputBridgeReturnTimeoutMs();
+            const targets = listRecorderTargets(layout, "click");
+            if (targets.length === 0) {
+                await this.dependencies.prompt.notifyFailure("No clickable element has a unique deterministic Locator for the bridge trigger");
+                return { status: "skipped" };
+            }
+            const selectedId = await this.dependencies.prompt.selectTarget(targets.map((target) => ({
+                id: target.element.id,
+                label: target.label
+            })));
+            const triggerTarget = targets.find((candidate) => candidate.element.id === selectedId);
+            if (triggerTarget === undefined) {
+                await this.dependencies.prompt.notifyFailure("Selected trigger element is unavailable");
+                return { status: "skipped" };
+            }
+            const trigger = actionTarget(triggerTarget);
+            if (trigger === undefined) {
+                await this.dependencies.prompt.notifyFailure("Selected trigger element has no executable geometry");
+                return { status: "skipped" };
+            }
+            const before = normalizeActivity(input.config.run.packageName, await views.adb.currentActivity(identity));
+            const executor = new ActionExecutor(views.adb, input.deviceSerial, () => uiSnapshotProvider.invalidate?.("beforeAction"));
+            const externalSteps = this.externalStepRunner(input, uiSnapshotProvider, views, executor);
+            // Set once the trigger escaped: a failure before that left the app
+            // where it was, so the person can simply choose again.
+            const progress = { escaped: false };
+            const bridge = await new BridgeRunner({
+                adb: views.adb,
+                clock: this.dependencies.clock,
+                actionExecutor: executor,
+                externalSteps,
+                idleWaiter: this.idleWaiter(input, views, input.config.run.packageName),
+                idle: input.config.idle,
+                packageName: input.config.run.packageName,
+                deviceSerial: input.deviceSerial
+            }).run({
+                trigger: {
+                    step: {
+                        action: "click",
+                        locator: triggerTarget.locator,
+                        activity: { before, after: before }
+                    },
+                    target: trigger
+                },
+                escapeTimeoutMs: BRIDGE_ESCAPE_TIMEOUT_MS,
+                returnTimeoutMs,
+                // The Recorder records whichever app the trigger opened.
+                acceptEscape: () => {
+                    progress.escaped = true;
+                    return undefined;
+                },
+                external: {
+                    kind: "drive",
+                    drive: async (escapedPackageName) => {
+                        await this.dependencies.prompt.notifyExternalEscape(escapedPackageName);
+                        return this.recordExternalSteps(input, escapedPackageName, uiSnapshotProvider, views, externalSteps);
+                    }
+                },
+                signal: input.signal
             });
+            if (bridge.status === "cancelled") {
+                return { status: "cancelled" };
+            }
+            if (bridge.status === "failed") {
+                if (progress.escaped) {
+                    return { status: "failed", message: bridge.message };
+                }
+                if (bridge.code === "BRIDGE_NO_ESCAPE") {
+                    await this.dependencies.prompt.notifyBridgeNoEscape();
+                }
+                else {
+                    await this.dependencies.prompt.notifyFailure(bridge.message);
+                }
+                return { status: "skipped" };
+            }
+            await this.dependencies.prompt.notifyExternalReturn();
+            const processes = await views.adb.appProcesses(identity);
+            if (primaryAppPid(processes, input.config.run.packageName) === null) {
+                return {
+                    status: "failed",
+                    message: "App process crashed after the recorded Action"
+                };
+            }
+            const after = normalizeActivity(input.config.run.packageName, await views.adb.currentActivity(identity));
+            const bridgeStep = JourneyStepSchema.parse({
+                action: "bridge",
+                scenario,
+                description,
+                triggerLocator: triggerTarget.locator,
+                escapedPackageName: bridge.escapedPackageName,
+                returnTimeoutMs,
+                externalSteps: bridge.externalSteps ?? [],
+                replayMode: "auto",
+                activity: { before, after }
+            });
+            return { status: "recorded", step: bridgeStep };
+        }
+        catch (error) {
+            if (input.signal?.aborted === true) {
+                return { status: "cancelled" };
+            }
+            throw error;
+        }
+    }
+    /**
+     * Records External Steps one chosen step at a time. Each step (except
+     * `scrollTo`, which the person already scrolled while choosing it) runs
+     * through the same ExternalStepRunner Replay uses, so only a step that
+     * replays is recorded. Leaving the escaped app ends the list.
+     */
+    async recordExternalSteps(input, escapedPackageName, uiSnapshotProvider, views, runner) {
+        const externalSteps = [];
+        const externalIdentity = {
+            packageName: escapedPackageName,
+            deviceSerial: input.deviceSerial,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            timeoutMs: input.config.idle.timeoutMs
+        };
+        for (;;) {
+            const action = await this.dependencies.prompt.selectExternalStepAction();
+            if (action === "finishExternal") {
+                break;
+            }
+            const foreground = await views.adb.foregroundComponent(externalIdentity);
+            if (foreground.packageName !== escapedPackageName) {
+                break;
+            }
+            const layout = (await uiSnapshotProvider.capture({
+                reason: "locate",
+                freshness: "sameMutationEpoch",
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+                timeoutMs: input.config.idle.timeoutMs
+            })).roots;
+            const prepared = await this.prepareExternalStep(action, layout, input, escapedPackageName, uiSnapshotProvider, views);
+            if (prepared === undefined) {
+                continue;
+            }
+            const step = this.buildExternalStep(prepared.draft, foreground.activity);
+            if (step.action === "scrollTo") {
+                externalSteps.push(step);
+                continue;
+            }
+            const outcome = await runner.run([step], escapedPackageName, input.signal);
+            if (outcome.status === "cancelled") {
+                return { status: "cancelled" };
+            }
+            if (outcome.status === "failed") {
+                // The action ran but the app never settled: the device is no longer
+                // in a state the recorded steps describe.
+                if (outcome.code === "IDLE_TIMEOUT") {
+                    return {
+                        status: "failed",
+                        code: outcome.code,
+                        message: outcome.message
+                    };
+                }
+                await this.dependencies.prompt.notifyFailure(outcome.message);
+                continue;
+            }
+            externalSteps.push(step);
+            const after = await views.adb.foregroundComponent(externalIdentity);
+            if (after.packageName !== escapedPackageName) {
+                break;
+            }
+        }
+        return { status: "driven", steps: externalSteps };
+    }
+    externalStepRunner(input, uiSnapshotProvider, views, actionExecutor) {
+        let viewport;
+        return new ExternalStepRunner({
+            adb: views.adb,
+            actionExecutor,
+            uiSnapshotProvider,
+            captureLayout: async (reason, timeoutMs, signal) => {
+                const snapshot = await uiSnapshotProvider.capture({
+                    reason,
+                    freshness: "sameMutationEpoch",
+                    timeoutMs,
+                    ...(signal === undefined ? {} : { signal })
+                });
+                viewport = snapshot.viewport;
+                return snapshot.roots;
+            },
+            createIdleWaiter: (packageName) => (this.idleWaiter(input, views, packageName)),
+            idle: input.config.idle,
+            viewport: () => viewport,
+            deviceSerial: input.deviceSerial
+        });
+    }
+    idleWaiter(input, views, packageName) {
+        return new IdleWaiter(views.uiStability, this.dependencies.clock, input.deviceSerial, packageName, deviceIdentityResolver(views.adb, {
+            packageName,
+            deviceSerial: input.deviceSerial,
+            timeoutMs: input.config.idle.timeoutMs
+        }));
+    }
+    async prepareExternalStep(action, layout, input, packageName, uiSnapshotProvider, views) {
+        if (action === "scrollTo") {
+            return this.prepareScrollTo(layout, input, uiSnapshotProvider, views, packageName, true);
+        }
+        if (action === "inputText") {
+            return {
+                draft: { action, text: await this.dependencies.prompt.inputText() }
+            };
         }
+        if (action === "back" || action === "wait") {
+            return { draft: { action } };
+        }
+        const targets = listRecorderTargets(layout, action).filter((target) => target.locator.resourceId !== undefined);
+        if (targets.length === 0) {
+            await this.dependencies.prompt.notifyFailure("No enabled element has a unique resourceId Locator in the external app");
+            return undefined;
+        }
+        const selectedId = await this.dependencies.prompt.selectTarget(targets.map((target) => ({
+            id: target.element.id,
+            label: target.label
+        })));
+        const target = targets.find((candidate) => candidate.element.id === selectedId);
+        if (target === undefined) {
+            await this.dependencies.prompt.notifyFailure("Selected external element is unavailable");
+            return undefined;
+        }
+        if (action === "swipe") {
+            const options = await this.dependencies.prompt.swipeOptions();
+            return {
+                target,
+                draft: {
+                    action,
+                    locator: target.locator,
+                    direction: await this.dependencies.prompt.selectSwipeDirection(),
+                    ...options
+                }
+            };
+        }
+        if (action === "click") {
+            return {
+                target,
+                draft: {
+                    action,
+                    locator: target.locator
+                }
+            };
+        }
+        return {
+            target,
+            draft: {
+                action,
+                locator: target.locator,
+                durationMs: await this.dependencies.prompt.longClickDuration()
+            }
+        };
+    }
+    buildExternalStep(draft, expectedActivity) {
+        return ExternalStepSchema.parse({
+            ...draft,
+            expectedActivity
+        });
     }
 }

package/dist/application/report/report-writer.js

@@ -5,7 +5,7 @@ function renderSummary(report) {
         `TapHound run ${report.runId}: ${report.status.toUpperCase()}`,
         `Journey: ${report.journey.name}`,
         `Package: ${report.project.packageName}`,
-        `Device: ${report.environment.deviceSerial}`,
+        ...report.environment.devices.map((device) => `Device[${device.role}]: ${device.deviceSerial}`),
         "",
         "Layers:",
         ...Object.entries(report.layers).map(([layer, status]) => `- ${layer}: ${status}`)

package/dist/application/runtime/cold-launch.d.ts

@@ -0,0 +1,28 @@
+import type { AdbPort } from "../../ports/adb.js";
+import type { Clock } from "../../ports/clock.js";
+export interface ColdLaunchInput {
+    packageName: string;
+    /** Fully qualified launch Activity. */
+    activity: string;
+    deviceSerial: string;
+    pollIntervalMs: number;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+export type ColdLaunchOutcome = {
+    status: "ready";
+    pids: readonly number[];
+    /** Time spent waiting for the process after the launch returned. */
+    processWaitMs: number;
+} | {
+    status: "failed";
+    stage: "reset" | "launch" | "process";
+    message: string;
+} | {
+    status: "cancelled";
+};
+/**
+ * The one cold launch Replay, the Recorder, and Generation share: force-stop
+ * the app, start its launch Activity, and wait until its process exists.
+ */
+export declare function coldLaunchApp(adb: AdbPort, clock: Clock, input: ColdLaunchInput): Promise<ColdLaunchOutcome>;