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

package/dist/cli/dependencies.js

@@ -1,56 +1,294 @@
 import { randomBytes, randomUUID } from "node:crypto";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
 import { AdbAdapter } from "../adapters/adb/adb-adapter.js";
+import { AdbRuntimeBackend } from "../adapters/runtime/adb-runtime-backend.js";
+import { SharedSessionRuntimeBackend } from "../adapters/runtime/shared-session-runtime-backend.js";
+import { SessionBackedScreenshotAdapter, SessionBackedUiSnapshotProviderFactory } from "../adapters/runtime/session-backed-ports.js";
+import { runtimeSessionPortViews } from "../adapters/runtime/session-adb-view.js";
+import { MobileMcpRuntimeBackend } from "../adapters/runtime/mobile-mcp/mobile-mcp-runtime-backend.js";
+import { McpToolClient } from "../adapters/runtime/mobile-mcp/mcp-tool-client.js";
+import { isMobileMcpSpawnFailureDetail, mobileMcpServerUnavailableMessage } from "../adapters/runtime/mobile-mcp/mobile-mcp-errors.js";
+import { SystemUiAutomatorSnapshotProviderFactory } from "../adapters/adb/system-uiautomator-snapshot-provider.js";
 import { AndroidCliAdapter } from "../adapters/android-cli/android-cli-adapter.js";
+import { AndroidCliSnapshotProviderFactory } from "../adapters/android-cli/android-cli-snapshot-provider.js";
+import { AppiumUiSnapshotProviderFactory } from "../adapters/appium/appium-ui-snapshot-provider.js";
+import { checkAppiumUiAutomator2 } from "../adapters/appium/appium-doctor.js";
+import { AutoUiSnapshotProviderFactory } from "../adapters/ui/auto-ui-snapshot-provider.js";
+import { CachedUiSnapshotProviderFactory } from "../application/ui/cached-ui-snapshot-provider.js";
+import { CameraProbeAdapter } from "../adapters/camera/camera-probe-adapter.js";
 import { SystemClock } from "../adapters/clock/system-clock.js";
 import { FileSystemArtifactStore } from "../adapters/filesystem/artifact-store.js";
+import { FileSystemContextDocumentWriter } from "../adapters/filesystem/context-document-writer.js";
 import { FileSystemGenerationMetaWriter } from "../adapters/filesystem/generation-meta-writer.js";
 import { FileSystemGenerationSessionStore } from "../adapters/filesystem/generation-session-store.js";
 import { FileSystemJourneyWriter } from "../adapters/filesystem/journey-writer.js";
+import { FileSystemKnowledgeRegistry } from "../adapters/filesystem/knowledge-registry.js";
+import { FileSystemJourneyCompositionStore } from "../adapters/filesystem/journey-composition-store.js";
+import { FileSystemExternalFlowRegistry } from "../adapters/filesystem/external-flow-registry.js";
 import { NodeProjectFileInspector } from "../adapters/filesystem/project-file-inspector.js";
+import { NodeProjectInventoryInspector } from "../adapters/filesystem/project-inventory-inspector.js";
+import { GradleProjectModuleDiscoverer } from "../adapters/filesystem/project-module-discoverer.js";
+import { AndroidProjectIdentityInspector } from "../adapters/filesystem/project-identity-inspector.js";
 import { FileSystemSkillInstaller } from "../adapters/filesystem/skill-installer.js";
+import { FileSystemWorkspaceLayout } from "../adapters/filesystem/workspace-layout.js";
 import { NodeProcessRunner } from "../adapters/process/node-process-runner.js";
+import { NodeDetachedProcessLauncher } from "../adapters/process/node-detached-process-launcher.js";
 import { InquirerRecorderPrompt } from "../adapters/prompt/inquirer-recorder-prompt.js";
 import { InquirerGenerationPrompt } from "../adapters/prompt/inquirer-generation-prompt.js";
 import { InquirerInitPrompt } from "../adapters/prompt/inquirer-init-prompt.js";
+import { InquirerAlignPrompt } from "../adapters/prompt/inquirer-align-prompt.js";
+import { AlignService } from "../application/align/align-service.js";
+import { ObserveService } from "../application/observe/observe-service.js";
+import { ContextGenerator } from "../application/context/context-generator.js";
+import { ContextRehasher } from "../application/context/context-rehasher.js";
 import { ContextValidator } from "../application/context/context-validator.js";
+import { ContextLoader } from "../application/context/context-loader.js";
+import { ContextRefresher } from "../application/context/context-refresher.js";
 import { DoctorService } from "../application/doctor/doctor-service.js";
 import { GenerationConfirmationService } from "../application/generation/generation-confirmation-service.js";
+import { GenerationAppPreparer } from "../application/generation/generation-app-preparer.js";
 import { GenerationFinalizer } from "../application/generation/generation-finalizer.js";
 import { GenerationPublisher } from "../application/generation/generation-publisher.js";
+import { GenerationRecoveryService } from "../application/generation/generation-recovery-service.js";
+import { GenerationReopenService } from "../application/generation/generation-reopen-service.js";
+import { GenerationConfigService } from "../application/generation/generation-config-service.js";
+import { GenerationReplaceService } from "../application/generation/generation-replace-service.js";
 import { GenerationStarter, GenerationOperationError, hashGenerationBinding } from "../application/generation/generation-starter.js";
+import { readGenerationContextSnapshot } from "../application/generation/generation-context-snapshot.js";
 import { GenerationStepExecutor } from "../application/generation/generation-step-executor.js";
 import { RuntimeObserver, SnapshotReobservationGuard } from "../application/generation/runtime-observer.js";
 import { InitService } from "../application/init/init-service.js";
+import { JourneyResolver } from "../application/journey/journey-resolver.js";
+import { ExternalFlowResolver } from "../application/journey/external-flow-resolver.js";
+import { KnowledgeLoadError, KnowledgeLoader } from "../application/knowledge/knowledge-loader.js";
+import { KnowledgeAnchorResolver } from "../application/knowledge/anchor-resolver.js";
+import { ImpactResolver } from "../application/impact/impact-resolver.js";
+import { NodeGitDiff } from "../adapters/git/node-git-diff.js";
 import { ProjectDescriber } from "../application/project/project-describer.js";
 import { RecorderService } from "../application/recorder/recorder-service.js";
 import { ReportWriter } from "../application/report/report-writer.js";
+import { ContractVerifier } from "../application/contract/contract-verifier.js";
+import { ContractLoader } from "../application/contract/contract-loader.js";
+import { ContractReviewMerger } from "../application/contract/contract-review.js";
+import { BaselineService } from "../application/checkpoint/baseline-service.js";
+import { FailureClassifier } from "../application/diagnosis/failure-classifier.js";
+import { TapHoundReportV4Schema } from "../domain/report.js";
 import { VerifyRuntime } from "../application/runtime/verify-runtime.js";
+import { IdleWaiter } from "../application/wait/idle-waiter.js";
+import { deviceIdentityResolver } from "../application/wait/idle-profiles.js";
+import { resolveRuntimeBackendId } from "../domain/runtime.js";
+import { withRuntimeSession } from "../ports/runtime-backend.js";
+import { verificationPhaseLabel } from "../domain/generation.js";
+import { isErrnoException } from "../shared/errors.js";
+import { readRuntimeBackendChoice } from "./runtime-selection.js";
+import { CONTEXT_INDEX_PATH } from "../domain/workspace.js";
+import { JourneySchema } from "../domain/journey.js";
 function runId() {
     return `${new Date().toISOString().replaceAll(":", "-")}-${randomUUID()}`;
 }
+export function loadKnowledgeResilient(load, input) {
+    return load(input).catch((error) => {
+        if ((isErrnoException(error) && error.code === "ENOENT")
+            || (error instanceof KnowledgeLoadError
+                && error.code === "KNOWLEDGE_NOT_FOUND")) {
+            return {
+                index: {
+                    version: 1,
+                    packageName: input.packageName,
+                    revision: 0,
+                    anchors: [],
+                    screens: []
+                },
+                indexSha256: "0".repeat(64),
+                knowledgeHash: "0".repeat(64),
+                anchors: [],
+                screens: []
+            };
+        }
+        throw error;
+    });
+}
 export function createProductionDependencies(signal, options = {}) {
+    const backendId = resolveRuntimeBackendId(options.runtimeBackendChoice ?? readRuntimeBackendChoice(process.env));
     const runner = new NodeProcessRunner();
-    const adb = new AdbAdapter(runner);
-    const androidCli = new AndroidCliAdapter(runner);
-    const clock = new SystemClock();
+    const clock = options.clock ?? new SystemClock();
+    const now = () => clock.now();
+    const permissionCaptureTimeoutMs = 10_000;
+    let backend;
+    let screenshots;
+    let uiSnapshots;
+    let sharedBackend;
+    if (options.runtimeBackend !== undefined) {
+        backend = options.runtimeBackend;
+        screenshots = new SessionBackedScreenshotAdapter(backend);
+        uiSnapshots = new CachedUiSnapshotProviderFactory(new SessionBackedUiSnapshotProviderFactory(backend), now);
+    }
+    else if (backendId === "mobile-mcp") {
+        const shared = new SharedSessionRuntimeBackend(new MobileMcpRuntimeBackend({
+            createTools: options.mobileMcpToolsFactory
+                ?? (() => new McpToolClient())
+        }));
+        sharedBackend = shared;
+        backend = shared;
+        screenshots = new SessionBackedScreenshotAdapter(backend);
+        uiSnapshots = new CachedUiSnapshotProviderFactory(new SessionBackedUiSnapshotProviderFactory(backend), now);
+    }
+    else {
+        const adbAdapter = new AdbAdapter(runner);
+        const androidCli = new AndroidCliAdapter(runner);
+        const autoSnapshots = new CachedUiSnapshotProviderFactory(new AutoUiSnapshotProviderFactory(new SystemUiAutomatorSnapshotProviderFactory(runner), new AndroidCliSnapshotProviderFactory(runner), new AppiumUiSnapshotProviderFactory(runner)), now);
+        const adbBackend = new AdbRuntimeBackend({
+            adb: adbAdapter,
+            screenshots: androidCli,
+            annotatedScreens: androidCli,
+            uiStability: androidCli,
+            uiSnapshots: autoSnapshots
+        });
+        backend = adbBackend;
+        screenshots = androidCli;
+        uiSnapshots = autoSnapshots;
+    }
+    const sessions = backend;
+    // Device-wide probes (listing, install state) borrow a session per call.
+    const devices = {
+        devices: (signal) => backend.listDevices(signal),
+        isInstalled: (identity) => withRuntimeSession(backend, identity.deviceSerial, identity.signal, (session) => session.isInstalled({
+            packageName: identity.packageName,
+            ...(identity.signal === undefined ? {} : { signal: identity.signal }),
+            ...(identity.timeoutMs === undefined
+                ? {}
+                : { timeoutMs: identity.timeoutMs })
+        }))
+    };
+    const waitUntilIdle = (deviceSerial, config, signal, packageName, stability, device) => new IdleWaiter(stability, clock, deviceSerial, packageName, deviceIdentityResolver(device, {
+        packageName,
+        deviceSerial,
+        timeoutMs: config.timeoutMs
+    })).waitUntilIdle(config, signal);
     const generationStoreFactory = options.generationStoreFactory
         ?? ((projectRoot) => (new FileSystemGenerationSessionStore(projectRoot)));
-    const contextValidator = new ContextValidator(new NodeProjectFileInspector());
+    const projectFiles = new NodeProjectFileInspector();
+    const projectInventory = new NodeProjectInventoryInspector();
+    const moduleDiscoverer = new GradleProjectModuleDiscoverer();
+    const identityInspector = new AndroidProjectIdentityInspector();
+    const contextWriter = new FileSystemContextDocumentWriter();
+    const contextValidator = new ContextValidator(projectFiles, projectInventory);
+    const contextLoader = new ContextLoader({
+        files: projectFiles,
+        inventory: projectInventory,
+        readJson: async (path) => JSON.parse(await readFile(path, "utf8"))
+    });
+    const contextRefresher = new ContextRefresher({
+        files: projectFiles,
+        inventory: projectInventory,
+        loader: contextLoader,
+        writer: contextWriter
+    });
+    const contextGenerator = new ContextGenerator({
+        discoverer: moduleDiscoverer,
+        identity: identityInspector,
+        files: projectFiles,
+        inventory: projectInventory,
+        writer: contextWriter
+    });
+    const contextRehasher = new ContextRehasher({
+        files: projectFiles,
+        loader: contextLoader,
+        writer: contextWriter
+    });
+    const journeyCompositionStore = new FileSystemJourneyCompositionStore();
+    const journeyResolver = new JourneyResolver(journeyCompositionStore);
+    const builtinFlowsRoot = resolvePath(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "assets", "external-flows");
+    const externalFlowRegistry = new FileSystemExternalFlowRegistry(builtinFlowsRoot);
+    const externalFlowResolver = new ExternalFlowResolver({
+        registry: externalFlowRegistry
+    });
+    const knowledgeRegistry = new FileSystemKnowledgeRegistry();
+    const knowledgeLoader = new KnowledgeLoader(knowledgeRegistry);
+    const productionContractLoader = new ContractLoader({
+        readText: (path) => readFile(path, "utf8")
+    });
+    const productionContractReview = new ContractReviewMerger({
+        now: () => new Date()
+    });
+    const productionBaselineService = new BaselineService({
+        readText: (path) => readFile(path, "utf8"),
+        writeText: (path, content) => {
+            const directory = dirname(path);
+            return mkdir(directory, { recursive: true }).then(() => (writeFile(path, content, "utf8")));
+        },
+        now: () => new Date()
+    });
+    const productionFailureClassifier = new FailureClassifier({
+        now: () => new Date()
+    });
+    const productionContractVerifier = new ContractVerifier({
+        verify: (input) => productionVerifyRuntime.verify(input),
+        loadKnowledge: (input) => (knowledgeRegistry.load(input.projectRoot)),
+        readText: (path) => readFile(path, "utf8"),
+        writeVerdict: async ({ reportPath, verdict }) => {
+            const directory = dirname(reportPath);
+            await mkdir(directory, { recursive: true });
+            await writeFile(join(directory, "verdict.json"), `${JSON.stringify(verdict, null, 2)}\n`, "utf8");
+        },
+        now: () => new Date()
+    });
+    const productionVerifyRuntime = new VerifyRuntime({
+        sessions,
+        sessionPorts: runtimeSessionPortViews,
+        clock,
+        artifactStore: new FileSystemArtifactStore(),
+        reportWriter: new ReportWriter(),
+        now: () => new Date(),
+        createRunId: runId,
+        anchorResolverFor: (projectRoot) => (new KnowledgeAnchorResolver(knowledgeRegistry, projectRoot)),
+        loadKnowledge: (input) => (knowledgeRegistry.load(input.projectRoot))
+    });
+    const gitDiff = new NodeGitDiff(runner);
+    const impactResolver = new ImpactResolver({
+        loadContext: async (input) => {
+            const loaded = await contextLoader.load({
+                projectRoot: input.projectRoot,
+                contextPath: join(input.projectRoot, CONTEXT_INDEX_PATH),
+                allowIncomplete: true
+            });
+            return { context: loaded.context, modules: loaded.modules };
+        },
+        loadKnowledge: (input) => loadKnowledgeResilient(knowledgeLoader.load.bind(knowledgeLoader), input),
+        listJourneyPaths: (input) => (journeyCompositionStore.listJourneyPaths(input.projectRoot)),
+        readJourney: async (input) => {
+            const bytes = await journeyCompositionStore.read({
+                projectRoot: input.projectRoot,
+                relativePath: input.path
+            });
+            try {
+                return JourneySchema.parse(JSON.parse(bytes.toString("utf8")));
+            }
+            catch {
+                return null;
+            }
+        }
+    });
     return {
         ...(signal === undefined ? {} : { signal }),
+        ...(sharedBackend === undefined
+            ? {}
+            : { close: () => sharedBackend.close() }),
         doctor: new DoctorService({
             runner,
-            adb,
+            adb: devices,
             nodeVersion: process.version,
+            runtimeBackendId: backendId,
             checkAndroidPermissions: async (deviceSerial, signal) => {
                 const directory = await mkdtemp(join(tmpdir(), "taphound-doctor-"));
                 try {
-                    const result = await androidCli.captureScreen({
+                    const result = await screenshots.capture({
                         outputPath: join(directory, "screen.png"),
                         deviceSerial,
+                        timeoutMs: permissionCaptureTimeoutMs,
                         ...(signal === undefined ? {} : { signal })
                     });
                     if (result.exitCode !== 0
@@ -59,9 +297,11 @@ export function createProductionDependencies(signal, options = {}) {
                         || result.timedOut) {
                         return {
                             status: "failed",
-                            message: result.stderr.trim()
-                                || result.spawnError
-                                || "Android screen capture permission probe failed"
+                            message: result.timedOut
+                                ? "Android screen capture permission probe timed out after 10 seconds"
+                                : result.stderr.trim()
+                                    || result.spawnError
+                                    || "Android screen capture permission probe failed"
                         };
                     }
                     return { status: "passed" };
@@ -69,35 +309,121 @@ export function createProductionDependencies(signal, options = {}) {
                 finally {
                     await rm(directory, { recursive: true, force: true });
                 }
+            },
+            checkAppiumUiAutomator2: async (appiumSignal) => (checkAppiumUiAutomator2(runner, appiumSignal)),
+            checkMobileMcpServer: async (mcpSignal) => {
+                const result = await runner.run({
+                    executable: "mcp-server-mobile",
+                    args: ["--version"],
+                    ...(mcpSignal === undefined ? {} : { signal: mcpSignal })
+                });
+                if (result.exitCode !== 0
+                    || result.spawnError !== undefined
+                    || result.cancelled
+                    || result.timedOut) {
+                    const detail = result.stderr.trim()
+                        || result.spawnError
+                        || "mcp-server-mobile check failed";
+                    return {
+                        status: "failed",
+                        message: isMobileMcpSpawnFailureDetail(detail)
+                            ? mobileMcpServerUnavailableMessage("mcp-server-mobile", detail)
+                            : detail
+                    };
+                }
+                return {
+                    status: "passed",
+                    version: result.stdout.trim().split(/\r?\n/, 1)[0] ?? "unknown"
+                };
             }
         }),
         recorder: new RecorderService({
-            androidCli,
-            adb,
+            sessions,
+            sessionPorts: runtimeSessionPortViews,
             clock,
-            prompt: new InquirerRecorderPrompt(),
+            prompt: options.recorderPrompt ?? new InquirerRecorderPrompt(),
             journeyWriter: new FileSystemJourneyWriter()
         }),
-        verifier: new VerifyRuntime({
-            androidCli,
-            adb,
-            clock,
-            artifactStore: new FileSystemArtifactStore(),
-            reportWriter: new ReportWriter(),
-            now: () => new Date(),
-            createRunId: runId
+        verifier: productionVerifyRuntime,
+        contractLoader: productionContractLoader,
+        contractVerifier: productionContractVerifier,
+        baselineService: productionBaselineService,
+        failureClassifier: {
+            classify: async (reportPath) => {
+                const text = await readFile(reportPath, "utf8");
+                const report = TapHoundReportV4Schema.parse(JSON.parse(text));
+                return productionFailureClassifier.classify({ report });
+            }
+        },
+        contractReview: {
+            merge: productionContractReview.merge,
+            writeVerdict: async ({ verdictPath, view }) => {
+                const directory = dirname(verdictPath);
+                await mkdir(directory, { recursive: true });
+                await writeFile(verdictPath, `${JSON.stringify(view, null, 2)}\n`, "utf8");
+            }
+        },
+        projectDescriber: new ProjectDescriber({
+            discoverer: moduleDiscoverer,
+            identity: identityInspector
         }),
-        projectDescriber: new ProjectDescriber(),
         contextValidator,
+        contextLoader,
+        contextRefresher,
+        contextGenerator,
+        contextRehasher,
+        journeyResolver,
+        journeyCompositionStore,
+        externalFlowResolver,
         init: new InitService({
             installer: new FileSystemSkillInstaller(),
             cwd: process.cwd(),
             homedir: homedir()
         }),
         initPrompt: new InquirerInitPrompt(),
+        align: new AlignService({
+            adb: devices,
+            probe: new CameraProbeAdapter({
+                sessions,
+                sessionPorts: runtimeSessionPortViews,
+                uiSnapshots,
+                now: () => Date.now(),
+                sleep: async (ms) => {
+                    await new Promise((resolve) => setTimeout(resolve, ms));
+                }
+            }),
+            prompt: new InquirerAlignPrompt(),
+            registry: externalFlowRegistry
+        }),
+        observer: (layoutTimeoutMs, backend, cacheEnabled) => {
+            const service = new ObserveService({
+                sessions,
+                layoutTimeoutMs,
+                ...(backend === undefined ? {} : { backend }),
+                ...(cacheEnabled === undefined ? {} : { cacheEnabled })
+            });
+            return {
+                observe: (input) => service.observe(input)
+            };
+        },
+        workspaceLayout: new FileSystemWorkspaceLayout(),
+        impact: {
+            resolve: (input) => impactResolver.resolve(input)
+        },
+        gitDiff,
+        knowledge: {
+            load: (input) => knowledgeLoader.load(input),
+            rehash: (input) => (knowledgeRegistry.rehash(input.projectRoot, input.packageName))
+        },
         generationStarter: {
             start: async (input) => new GenerationStarter({
                 contextValidator,
+                appPreparer: new GenerationAppPreparer({
+                    sessions,
+                    sessionPorts: runtimeSessionPortViews,
+                    clock
+                }),
+                uiSnapshots,
                 store: generationStoreFactory(input.projectRoot),
                 now: () => new Date(),
                 generateId: randomUUID,
@@ -107,8 +433,9 @@ export function createProductionDependencies(signal, options = {}) {
         runtimeObserver: {
             observe: async ({ projectRoot, ...input }) => (new RuntimeObserver({
                 store: generationStoreFactory(projectRoot),
-                adb,
-                androidCli,
+                sessions,
+                sessionPorts: runtimeSessionPortViews,
+                waitUntilIdle,
                 now: () => new Date(),
                 createAttemptId: randomUUID
             }).observe(input))
@@ -118,16 +445,13 @@ export function createProductionDependencies(signal, options = {}) {
             const prompt = new InquirerGenerationPrompt();
             const observer = new RuntimeObserver({
                 store,
-                adb,
-                androidCli,
+                sessions,
+                sessionPorts: runtimeSessionPortViews,
+                waitUntilIdle,
                 now: () => new Date(),
-                createAttemptId: randomUUID
-            });
-            const freshnessGuard = new SnapshotReobservationGuard({
-                store,
-                adb,
-                androidCli,
-                now: () => new Date()
+                createAttemptId: randomUUID,
+                uiCacheEnabled: config.ui?.cacheEnabled ?? true,
+                uiSnapshotTimeoutMs: config.ui?.snapshotTimeoutMs
             });
             const confirmation = new GenerationConfirmationService({
                 store,
@@ -138,54 +462,129 @@ export function createProductionDependencies(signal, options = {}) {
             });
             const executor = new GenerationStepExecutor({
                 store,
-                freshnessGuard,
-                adb,
-                androidCli,
+                createFreshnessGuard: (uiSnapshotProvider, views) => (new SnapshotReobservationGuard({
+                    store,
+                    adb: views.adb,
+                    uiSnapshotProvider,
+                    now: () => new Date(),
+                    uiSnapshotTimeoutMs: config.ui?.snapshotTimeoutMs
+                })),
+                sessions,
+                sessionPorts: runtimeSessionPortViews,
+                uiCacheEnabled: config.ui?.cacheEnabled ?? true,
                 clock,
                 idle: config.idle,
                 now: () => new Date(),
                 generateAttemptId: randomUUID,
+                projectRoot,
+                externalFlowResolver,
                 clearApprovedConfirmation: async (generationId, challenge) => confirmation.clearApproved({
                     generationId,
                     challenge
-                })
+                }),
+                observeNext: (observation) => (observer.observeCollected({
+                    generationId: observation.generationId,
+                    runtime: observation.runtime,
+                    ...(observation.signal === undefined
+                        ? {}
+                        : { signal: observation.signal })
+                }))
             });
             const publisher = new GenerationPublisher({
                 store,
                 journeyWriter: new FileSystemJourneyWriter(),
                 metaWriter: new FileSystemGenerationMetaWriter()
             });
+            const verifyRuntime = new VerifyRuntime({
+                sessions,
+                sessionPorts: runtimeSessionPortViews,
+                clock,
+                artifactStore: new FileSystemArtifactStore(),
+                reportWriter: new ReportWriter(),
+                now: () => new Date(),
+                createRunId: runId,
+                anchorResolverFor: (projectRoot) => (new KnowledgeAnchorResolver(knowledgeRegistry, projectRoot))
+            });
             const finalizer = new GenerationFinalizer({
                 store,
-                contextValidator,
-                adb,
-                verifyRuntime: new VerifyRuntime({
-                    androidCli,
-                    adb,
-                    clock,
-                    artifactStore: new FileSystemArtifactStore(),
-                    reportWriter: new ReportWriter(),
-                    now: () => new Date(),
-                    createRunId: runId
-                }),
+                verifyRuntime,
                 publisher,
-                generateAttemptId: randomUUID
+                generateAttemptId: randomUUID,
+                owner: { pid: process.pid, now: () => new Date() },
+                progress: (stage) => {
+                    process.stderr.write(`TapHound finalize: ${stage}\n`);
+                },
+                replayProgress: (phase) => {
+                    process.stderr.write(`TapHound finalize: ${verificationPhaseLabel(phase)}\n`);
+                }
+            });
+            const recovery = new GenerationRecoveryService({
+                store,
+                now: () => new Date(),
+                ownerAlive: (pid) => {
+                    try {
+                        process.kill(pid, 0);
+                        return true;
+                    }
+                    catch (error) {
+                        return !isErrnoException(error) || error.code !== "ESRCH";
+                    }
+                }
+            });
+            const reopen = new GenerationReopenService({
+                store,
+                now: () => new Date()
             });
             return {
                 confirmation,
                 executor,
                 observer,
                 finalizer,
+                recovery,
+                reopen,
+                archive: async (id) => {
+                    const current = await store.read(id);
+                    const next = {
+                        ...current,
+                        revision: current.revision + 1,
+                        state: "archived"
+                    };
+                    await store.archive(id, current.revision, next);
+                    return next;
+                },
+                list: () => store.list(),
                 readSession: (id) => store.read(id),
+                readContextSnapshot: (id) => (readGenerationContextSnapshot({ store }, id)),
                 assertConfigIdentity: async (id) => {
                     const session = await store.read(id);
                     if (hashGenerationBinding(config) !== session.bindings.configHash) {
                         throw new GenerationOperationError("CONFIG_INVALID", "Generation configuration does not match the authoritative session");
                     }
-                }
+                },
+                updateIdlePolicy: async (id, patch) => (new GenerationConfigService({ store }).updateIdlePolicy({
+                    generationId: id,
+                    config,
+                    patch
+                })),
+                replace: (input) => (new GenerationReplaceService({
+                    store,
+                    observer,
+                    verifyRuntime,
+                    appPreparer: new GenerationAppPreparer({
+                        sessions,
+                        sessionPorts: runtimeSessionPortViews,
+                        clock
+                    })
+                }).replace(input))
             };
         },
+        detachedProcess: new NodeDetachedProcessLauncher(),
+        createDetachedJobId: randomUUID,
+        ...(process.argv[1] === undefined
+            ? {}
+            : { cliEntryPath: process.argv[1] }),
         readJson: async (path) => JSON.parse(await readFile(path, "utf8")),
+        readFile: async (path) => readFile(path),
         cwd: () => process.cwd(),
         stdout: {
             write: (content) => {

package/dist/cli/diff-verification.d.ts

@@ -0,0 +1,41 @@
+import type { ImpactSet } from "../domain/impact.js";
+import { CONFIG_PATH } from "../domain/workspace.js";
+import { type FailureCode } from "../domain/failure.js";
+import type { CliDependencies } from "./dependencies.js";
+export interface DiffVerificationOptions {
+    project: string;
+    config: string;
+    base: string;
+    head?: string | undefined;
+    device?: string | undefined;
+    scope?: string | undefined;
+    json?: boolean | undefined;
+}
+export interface JourneyVerdict {
+    path: string;
+    name: string;
+    selection: "p0" | "p1" | "p2";
+    status: string;
+    exitCode: 0 | 1 | 2 | 3 | 4;
+    reportPath: string;
+}
+export interface DiffVerificationResult {
+    base: string;
+    head: string;
+    impact: ImpactSet;
+    results: JourneyVerdict[];
+    overall: "passed" | "failed" | "error";
+    exitCode: 0 | 1 | 2 | 3 | 4;
+    note?: string | undefined;
+}
+declare function writeFailure(dependencies: CliDependencies, json: boolean, code: FailureCode, message: string): void;
+/**
+ * Diff-driven verification: compute the ImpactSet for a Git change, select
+ * the affected Journeys by tier (p0/p1/p2), and verify each one on the
+ * connected device.
+ *
+ * This is the Agent-facing entry behind `verify --diff`; it never parses the app's internals — the Coding Agent
+ * only sees Journey names + verdicts.
+ */
+export declare function runDiffVerification(dependencies: CliDependencies, options: DiffVerificationOptions): Promise<void>;
+export { CONFIG_PATH, writeFailure };