taphound 0.2.0-dev.11 → 0.2.0-dev.13

package/dist/application/ui/ui-stability-probe.js

@@ -1,8 +1,24 @@
+/**
+ * A snapshot provider that samples stability itself (Appium) answers every
+ * structural sample, but frame-stat samples still go to the runtime probe:
+ * the provider only knows page sources, so it would answer a cheap
+ * `dumpsys gfxinfo` request with a full hierarchy capture.
+ */
 export function uiStabilityProbe(provider, fallback) {
     const withCapability = provider;
-    return withCapability.supportsStability !== false
-        && typeof withCapability.sample === "function"
-        && typeof withCapability.reset === "function"
-        ? withCapability
-        : fallback;
+    if (withCapability.supportsStability === false
+        || typeof withCapability.sample !== "function"
+        || typeof withCapability.reset !== "function") {
+        return fallback;
+    }
+    const structural = withCapability;
+    return {
+        reset: () => {
+            structural.reset();
+            fallback.reset();
+        },
+        sample: (options) => (options.stabilityBackend === "frameStats"
+            ? fallback.sample(options)
+            : structural.sample(options))
+    };
 }

package/dist/application/wait/idle-waiter.js

@@ -1,6 +1,14 @@
 import { resolveIdlePolicy } from "./idle-profiles.js";
 const EARLY_BAIL_FRAME_CHANGES = 2;
 const POST_FALLBACK_MIN_STABLE = 2;
+/**
+ * Once frame stats showed no rendering for `stablePolls` polls, the
+ * structural phase only has to confirm the hierarchy did not change between
+ * two captures taken during this wait: one empty diff after at least two
+ * structural samples. Each capture costs a full hierarchy dump.
+ */
+const POST_FRAME_STABLE_CONFIRMATIONS = 1;
+const POST_FRAME_STABLE_MIN_SAMPLES = 2;
 function isEditableWidgetChange(change) {
     if (typeof change !== "object" || change === null) {
         return false;
@@ -92,6 +100,8 @@ export class IdleWaiter {
         let lastLayout;
         let backend;
         let fallbackUsed = false;
+        let frameStable = false;
+        let structuralSamples = 0;
         let frameActivityDetected = false;
         let samplingDurationMs = 0;
         let useStructuralBackend = strategy === "layoutDiff"
@@ -105,7 +115,8 @@ export class IdleWaiter {
                     durationMs: this.clock.now() - startedAt
                 };
             }
-            const elapsedBeforePoll = this.clock.now() - startedAt;
+            const pollStartedAt = this.clock.now();
+            const elapsedBeforePoll = pollStartedAt - startedAt;
             polls += 1;
             let observation;
             try {
@@ -159,6 +170,7 @@ export class IdleWaiter {
                 consecutiveEmpty = 0;
             }
             else if (useStructuralBackend) {
+                structuralSamples += 1;
                 let visibleChanges = meaningfulChanges(diff, config.ignoreCursorBlink === true);
                 if (config.ignoreLayoutDrift === true && visibleChanges.length > 0) {
                     const keys = visibleChanges.map(semanticKeys);
@@ -190,13 +202,17 @@ export class IdleWaiter {
             }
             const isPostFallback = fallbackUsed && strategy === "hybrid";
             const requiredStableObservations = useStructuralBackend
-                ? (isPostFallback
-                    ? Math.max(POST_FALLBACK_MIN_STABLE, config.stablePolls - 1)
-                    : Math.max(2, config.stablePolls))
+                ? (frameStable
+                    ? POST_FRAME_STABLE_CONFIRMATIONS
+                    : isPostFallback
+                        ? Math.max(POST_FALLBACK_MIN_STABLE, config.stablePolls - 1)
+                        : Math.max(2, config.stablePolls))
                 : config.stablePolls;
-            if (consecutiveEmpty >= requiredStableObservations) {
+            if (consecutiveEmpty >= requiredStableObservations
+                && (!frameStable || structuralSamples >= POST_FRAME_STABLE_MIN_SAMPLES)) {
                 if (strategy === "hybrid" && !useStructuralBackend) {
                     useStructuralBackend = true;
+                    frameStable = true;
                     consecutiveEmpty = 0;
                 }
                 else {
@@ -231,8 +247,15 @@ export class IdleWaiter {
                     ...telemetry(strategy, backend, fallbackUsed, frameActivityDetected, samplingDurationMs)
                 };
             }
+            // The interval runs from the start of one poll to the start of the
+            // next: a slow sample (a full hierarchy dump) eats into the wait
+            // instead of being added on top of it.
+            const sleepMs = Math.min(config.pollIntervalMs - (this.clock.now() - pollStartedAt), remainingMs);
+            if (sleepMs <= 0) {
+                continue;
+            }
             try {
-                await this.clock.sleep(Math.min(config.pollIntervalMs, remainingMs), signal);
+                await this.clock.sleep(sleepMs, signal);
             }
             catch (error) {
                 if (isAborted(signal)) {

package/dist/cli/commands/diagnose.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { CliDependencies } from "../dependencies.js";
+export declare function createDiagnoseCommand(dependencies: CliDependencies): Command;

package/dist/cli/commands/diagnose.js

@@ -0,0 +1,84 @@
+import { resolve } from "node:path";
+import { Command, InvalidArgumentError } from "commander";
+import { exitCodeForFailure, failureCodeFromUnknown } from "../../domain/failure.js";
+import { DIAGNOSTICS_EXPORT_DIR } from "../../domain/workspace.js";
+import { errorMessage, failureOutput, writeJson, writeLine } from "../output.js";
+const REVIEW_NOTE = "Review the file before sharing it. It holds command outcomes, "
+    + "timings, and failure codes; project paths, package, Activity and Journey "
+    + "names, locator values, device serials, screenshots, UI hierarchies, and "
+    + "log text are left out or replaced by aliases.";
+function positiveInteger(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 1000) {
+        throw new InvalidArgumentError("must be an integer from 1 to 1000");
+    }
+    return parsed;
+}
+function exportFileName(at) {
+    return `taphound-diagnostics-${at.toISOString().replaceAll(":", "-")}.json`;
+}
+export function createDiagnoseCommand(dependencies) {
+    return new Command("diagnose")
+        .description("Collect redacted diagnostics to attach to TapHound feedback")
+        .addCommand(new Command("export")
+        .description("Write a redacted diagnostics bundle from the local journal and recent reports")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--out <path>", `Bundle path (default ${DIAGNOSTICS_EXPORT_DIR}/<timestamp>.json)`)
+        .option("--events <count>", "Most recent journal events to include", positiveInteger, 50)
+        .option("--runs <count>", "Most recent referenced runs to summarize", positiveInteger, 10)
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        const json = options.json === true;
+        const diagnostics = dependencies.diagnosticsExport;
+        if (diagnostics === undefined) {
+            const output = failureOutput(2, "CONFIG_INVALID", "TapHound diagnostics export is not configured");
+            if (json) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stderr, output.failure.message);
+            }
+            dependencies.setExitCode(2);
+            return;
+        }
+        try {
+            const projectRoot = resolve(dependencies.cwd(), options.project);
+            const bundle = await diagnostics.export({
+                projectRoot,
+                eventLimit: options.events,
+                runLimit: options.runs
+            });
+            const path = options.out === undefined
+                ? resolve(projectRoot, DIAGNOSTICS_EXPORT_DIR, exportFileName(new Date(bundle.generatedAt)))
+                : resolve(dependencies.cwd(), options.out);
+            await diagnostics.write(path, `${JSON.stringify(bundle, null, 2)}\n`);
+            if (json) {
+                writeJson(dependencies.stdout, {
+                    status: "exported",
+                    exitCode: 0,
+                    path,
+                    events: bundle.journal.events.length,
+                    runs: bundle.runs.length
+                });
+            }
+            else {
+                writeLine(dependencies.stdout, `TapHound diagnostics: ${path}\n${String(bundle.journal.events.length)} event(s), `
+                    + `${String(bundle.runs.length)} run summary(ies)`);
+            }
+            writeLine(dependencies.stderr, REVIEW_NOTE);
+            dependencies.setExitCode(0);
+        }
+        catch (error) {
+            const code = failureCodeFromUnknown(error) ?? "INTERNAL_ERROR";
+            const exitCode = exitCodeForFailure(code);
+            const output = failureOutput(exitCode, code, errorMessage(error));
+            if (json) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stderr, output.failure.message);
+            }
+            dependencies.setExitCode(exitCode);
+        }
+    }));
+}

package/dist/cli/commands/generation/session-commands.js

@@ -7,7 +7,7 @@ import { GenerationOperationError, flowReplayFailureDetails } from "../../../app
 import { GenerationSessionIdSchema, verificationPhaseLabel } from "../../../domain/generation.js";
 import { DEFAULT_DEVICE_ROLE } from "../../../domain/journey.js";
 import { ProjectRelativePathSchema } from "../../../domain/project-context.js";
-import { CONFIG_PATH, CONTEXT_INDEX_PATH } from "../../../domain/workspace.js";
+import { CONFIG_PATH, CONTEXT_INDEX_PATH, isJourneyBriefPath, JOURNEY_BRIEF_ROOTS } from "../../../domain/workspace.js";
 import { GenerationSessionStoreError } from "../../../ports/generation-session-store.js";
 import { errorMessage, writeJson, writeLine } from "../../output.js";
 import { canonicalProjectRoot } from "../../project-root.js";
@@ -52,6 +52,9 @@ export function createStartCommand(dependencies) {
                     catch (error) {
                         throw new GenerationOperationError("BRIEF_INVALID", `Journey Brief path must stay within the project: ${briefRequest} (${error instanceof Error ? error.message : String(error)})`);
                     }
+                    if (!isJourneyBriefPath(briefPath)) {
+                        throw new GenerationOperationError("BRIEF_INVALID", `Journey Brief must live under ${JOURNEY_BRIEF_ROOTS.join("/ or ")}/: ${briefPath}`);
+                    }
                     let bytes;
                     try {
                         bytes = await dependencies.readFile(resolve(projectRoot, briefPath));

package/dist/cli/commands/journey.js

@@ -213,6 +213,7 @@ function createCheckCommand(dependencies) {
         .option("--project <path>", "Android project root", dependencies.cwd())
         .option("--config <path>", "TapHound config path", CONFIG_PATH)
         .option("--context <path>", "Project Context index path")
+        .option("--journey <path-or-name...>", "Check only these Journeys (project-relative path or Journey name)")
         .option("--json", "Emit one machine-readable JSON value")
         .option("--strict", "Exit non-zero when any Journey is not fresh")
         .action(async (options) => {
@@ -245,7 +246,8 @@ function createCheckCommand(dependencies) {
                 projectRoot,
                 config,
                 project,
-                bundle: index.bundle
+                bundle: index.bundle,
+                journeys: options.journey
             });
             const notFresh = result.summary.total - result.summary.fresh;
             const exitCode = options.strict === true && notFresh > 0 ? 1 : 0;

package/dist/cli/commands/verify.js

@@ -1,12 +1,15 @@
-import { resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
 import { Command } from "commander";
 import { readCliVersion } from "../version.js";
 import { runDiffVerification } from "../diff-verification.js";
 import { loadPublishedReplayPolicy } from "../../application/generation/replay-policy-loader.js";
+import { logcatEvidenceWarning } from "../../application/report/report-writer.js";
 import { TapHoundConfigSchema } from "../../domain/config.js";
 import { DEFAULT_DEVICE_ROLE, JourneySchema } from "../../domain/journey.js";
 import { assertArtifactDirectory, CONFIG_PATH } from "../../domain/workspace.js";
 import { exitCodeForFailure } from "../../domain/failure.js";
+import { VERIFY_RECEIPT_FILE, VerifyReceiptSchema } from "../../domain/verify-receipt.js";
 import { errorMessage, failureOutput, writeJson, writeLine } from "../output.js";
 import { prepareWorkspace } from "../workspace-guard.js";
 function toolVersions(checks) {
@@ -26,6 +29,50 @@ function writeFailure(dependencies, json, code, message) {
     }
     dependencies.setExitCode(exitCode);
 }
+/** The normalized invocation TapHound ran, recorded in the process receipt. */
+function receiptArgv(options, projectRoot, deviceSerial) {
+    const root = resolve(projectRoot);
+    return [
+        "verify",
+        "--project", root,
+        "--config", resolve(root, options.config),
+        "--journey", resolve(root, options.journey),
+        "--device", deviceSerial,
+        ...(options.package === undefined ? [] : ["--package", options.package]),
+        ...(options.activity === undefined ? [] : ["--activity", options.activity]),
+        ...(options.reports === undefined ? [] : ["--reports", options.reports]),
+        ...(options.policyFromMeta === true ? ["--policy-from-meta"] : []),
+        ...(options.json === true ? ["--json"] : [])
+    ];
+}
+/**
+ * Publishes the process receipt beside the report. The report is already
+ * published, so a receipt failure is reported on stderr and leaves the
+ * verify result intact; a Workflow checker then pauses on the missing receipt.
+ */
+async function writeReceipt(dependencies, argv, result) {
+    if (dependencies.writeVerifyReceipt === undefined)
+        return undefined;
+    const receiptPath = join(dirname(result.reportPath), VERIFY_RECEIPT_FILE);
+    try {
+        const receipt = VerifyReceiptSchema.parse({
+            version: 1,
+            argv,
+            exitCode: result.exitCode,
+            journeySha256: result.report.journey.sha256,
+            reportPath: result.reportPath,
+            reportSha256: createHash("sha256")
+                .update(await dependencies.readFile(result.reportPath))
+                .digest("hex")
+        });
+        await dependencies.writeVerifyReceipt(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`);
+        return receiptPath;
+    }
+    catch (error) {
+        writeLine(dependencies.stderr, `TapHound: verify receipt was not written: ${errorMessage(error)}`);
+        return undefined;
+    }
+}
 async function runDoctorAndVerify(dependencies, options, config, journey, projectRoot) {
     const json = options.json === true;
     let replayPolicy;
@@ -103,11 +150,16 @@ async function runDoctorAndVerify(dependencies, options, config, journey, projec
                 ? {}
                 : { signal: dependencies.signal })
         });
+        const receiptPath = await writeReceipt(dependencies, receiptArgv(options, projectRoot, deviceSerial), result);
         if (json) {
-            writeJson(dependencies.stdout, result);
+            writeJson(dependencies.stdout, receiptPath === undefined ? result : { ...result, receiptPath });
         }
         else {
-            writeLine(dependencies.stdout, `TapHound verify: ${result.status.toUpperCase()}\nReport: ${result.reportPath}`);
+            writeLine(dependencies.stdout, `TapHound verify: ${result.status.toUpperCase()}\nReport: ${result.reportPath}${receiptPath === undefined ? "" : `\nReceipt: ${receiptPath}`}`);
+        }
+        const logcatWarning = logcatEvidenceWarning(result.report);
+        if (logcatWarning !== undefined) {
+            writeLine(dependencies.stderr, logcatWarning);
         }
         dependencies.setExitCode(result.exitCode);
     }

package/dist/cli/dependencies.d.ts

@@ -1,3 +1,6 @@
+import { type DiagnosticsExportInput } from "../application/diagnostics/diagnostics-exporter.js";
+import type { DiagnosticsBundle } from "../domain/diagnostics.js";
+import { type CliDiagnostics } from "./diagnostics-recorder.js";
 import type { MobileMcpTools } from "../adapters/runtime/mobile-mcp/mobile-mcp-tools.js";
 import type { Clock } from "../ports/clock.js";
 import { type AlignCameraResult } from "../application/align/align-service.js";
@@ -160,11 +163,19 @@ export interface CliDependencies {
     } | undefined;
     readJson: (path: string) => Promise<unknown>;
     readFile: (path: string) => Promise<Buffer>;
+    /** Atomically publishes a verify process receipt beside its report. */
+    writeVerifyReceipt?: ((path: string, content: string) => Promise<void>) | undefined;
     cwd: () => string;
     stdout: TextOutput;
     stderr: TextOutput;
     setExitCode: (code: number) => void;
     close?: (() => Promise<void>) | undefined;
+    /** Local diagnostics journal; absent in tests and when disabled. */
+    diagnostics?: CliDiagnostics | undefined;
+    diagnosticsExport?: {
+        export: (input: DiagnosticsExportInput) => Promise<DiagnosticsBundle>;
+        write: (path: string, content: string) => Promise<void>;
+    } | undefined;
 }
 export interface ProductionDependencyOptions {
     generationStoreFactory?: (projectRoot: string) => GenerationSessionStore;

package/dist/cli/dependencies.js

@@ -1,5 +1,5 @@
 import { randomBytes, randomUUID } from "node:crypto";
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -8,6 +8,12 @@ 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 { FileSystemDiagnosticsJournal } from "../adapters/filesystem/diagnostics-journal.js";
+import { UiCaptureTelemetry } from "../application/diagnostics/ui-capture-telemetry.js";
+import { ObservedUiSnapshotProviderFactory } from "../application/ui/observed-ui-snapshot-provider.js";
+import { DiagnosticsExporter } from "../application/diagnostics/diagnostics-exporter.js";
+import { readCliVersion } from "./version.js";
+import { diagnosticsEnabled, diagnosticsHost } from "./diagnostics-recorder.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";
@@ -117,6 +123,9 @@ export function createProductionDependencies(signal, options = {}) {
     const clock = options.clock ?? new SystemClock();
     const now = () => clock.now();
     const permissionCaptureTimeoutMs = 10_000;
+    const uiTelemetry = new UiCaptureTelemetry();
+    const diagnosticsJournal = new FileSystemDiagnosticsJournal();
+    const observed = (source) => (new ObservedUiSnapshotProviderFactory(source, uiTelemetry, now));
     let backend;
     let screenshots;
     let uiSnapshots;
@@ -124,7 +133,7 @@ export function createProductionDependencies(signal, options = {}) {
     if (options.runtimeBackend !== undefined) {
         backend = options.runtimeBackend;
         screenshots = new SessionBackedScreenshotAdapter(backend);
-        uiSnapshots = new CachedUiSnapshotProviderFactory(new SessionBackedUiSnapshotProviderFactory(backend), now);
+        uiSnapshots = new CachedUiSnapshotProviderFactory(observed(new SessionBackedUiSnapshotProviderFactory(backend)), now);
     }
     else if (backendId === "mobile-mcp") {
         const shared = new SharedSessionRuntimeBackend(new MobileMcpRuntimeBackend({
@@ -134,12 +143,16 @@ export function createProductionDependencies(signal, options = {}) {
         sharedBackend = shared;
         backend = shared;
         screenshots = new SessionBackedScreenshotAdapter(backend);
-        uiSnapshots = new CachedUiSnapshotProviderFactory(new SessionBackedUiSnapshotProviderFactory(backend), now);
+        uiSnapshots = new CachedUiSnapshotProviderFactory(observed(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 autoSnapshots = new CachedUiSnapshotProviderFactory(observed(new AutoUiSnapshotProviderFactory(new SystemUiAutomatorSnapshotProviderFactory(runner), new AndroidCliSnapshotProviderFactory(runner), new AppiumUiSnapshotProviderFactory(runner, undefined, {
+            onSessionRecovery: (succeeded) => {
+                uiTelemetry.sessionRecovered("appium-uiautomator2", succeeded);
+            }
+        }))), now);
         const adbBackend = new AdbRuntimeBackend({
             adb: adbAdapter,
             screenshots: androidCli,
@@ -585,6 +598,17 @@ export function createProductionDependencies(signal, options = {}) {
             : { cliEntryPath: process.argv[1] }),
         readJson: async (path) => JSON.parse(await readFile(path, "utf8")),
         readFile: async (path) => readFile(path),
+        writeVerifyReceipt: async (path, content) => {
+            const temporaryPath = `${path}.${randomUUID()}.tmp`;
+            try {
+                await writeFile(temporaryPath, content, { encoding: "utf8", flag: "wx" });
+                await rename(temporaryPath, path);
+            }
+            catch (error) {
+                await rm(temporaryPath, { force: true });
+                throw error;
+            }
+        },
         cwd: () => process.cwd(),
         stdout: {
             write: (content) => {
@@ -598,6 +622,35 @@ export function createProductionDependencies(signal, options = {}) {
         },
         setExitCode: (code) => {
             process.exitCode = code;
-        }
+        },
+        diagnosticsExport: {
+            export: (input) => new DiagnosticsExporter({
+                journal: diagnosticsJournal,
+                readJson: async (path) => JSON.parse(await readFile(path, "utf8")),
+                now: () => new Date(),
+                taphoundVersion: readCliVersion(),
+                host: diagnosticsHost()
+            }).export(input),
+            write: async (path, content) => {
+                await mkdir(dirname(path), { recursive: true });
+                const temporaryPath = `${path}.${randomUUID()}.tmp`;
+                try {
+                    await writeFile(temporaryPath, content, { encoding: "utf8", flag: "wx", mode: 0o600 });
+                    await rename(temporaryPath, path);
+                }
+                catch (error) {
+                    await rm(temporaryPath, { force: true });
+                    throw error;
+                }
+            }
+        },
+        ...(diagnosticsEnabled(process.env)
+            ? {
+                diagnostics: {
+                    journal: diagnosticsJournal,
+                    telemetry: uiTelemetry
+                }
+            }
+            : {})
     };
 }

package/dist/cli/diagnostics-recorder.d.ts

@@ -0,0 +1,31 @@
+import type { Command } from "commander";
+import { type CommandEvent, type DiagnosticsHostSchema } from "../domain/diagnostics.js";
+import type { UiCaptureTelemetry } from "../application/diagnostics/ui-capture-telemetry.js";
+import type { DiagnosticsJournal } from "../ports/diagnostics.js";
+import type { z } from "zod";
+export interface CliDiagnostics {
+    journal: DiagnosticsJournal;
+    telemetry: UiCaptureTelemetry;
+}
+export declare function diagnosticsEnabled(env: Record<string, string | undefined>): boolean;
+export declare function diagnosticsHost(): z.infer<typeof DiagnosticsHostSchema>;
+/** What the invoked command is, captured before its action runs. */
+export interface InvokedCommand {
+    command: string;
+    flags: string[];
+    projectRoot: string;
+}
+export declare function describeInvocation(action: Command, cwd: string): InvokedCommand;
+/**
+ * Reads only the structured outcome of one machine-readable output: status,
+ * failure code, and run id. Messages and every other field are ignored.
+ */
+export declare function outcomeFromJsonOutput(stdout: string): Pick<CommandEvent, "status" | "failureCode" | "runId">;
+export declare function commandEvent(input: {
+    invocation: InvokedCommand;
+    startedAt: Date;
+    durationMs: number;
+    exitCode: number;
+    stdout: string | undefined;
+    telemetry: UiCaptureTelemetry;
+}): CommandEvent;

package/dist/cli/diagnostics-recorder.js

@@ -0,0 +1,82 @@
+import { arch, platform, version as nodeVersion } from "node:process";
+import { resolve } from "node:path";
+import { CommandEventSchema, DIAGNOSTICS_DISABLE_ENV_VAR } from "../domain/diagnostics.js";
+import { FAILURE_CODES } from "../domain/failure.js";
+import { readCliVersion } from "./version.js";
+export function diagnosticsEnabled(env) {
+    const value = env[DIAGNOSTICS_DISABLE_ENV_VAR]?.trim().toLowerCase();
+    return !["0", "off", "false", "no"].includes(value ?? "");
+}
+export function diagnosticsHost() {
+    return {
+        platform,
+        arch,
+        node: nodeVersion.replace(/^v/, "")
+    };
+}
+export function describeInvocation(action, cwd) {
+    const names = [];
+    let command = action;
+    while (command.parent !== null) {
+        names.unshift(command.name());
+        command = command.parent;
+    }
+    const flags = action.options
+        .map((option) => option.attributeName())
+        .filter((name) => action.getOptionValueSource(name) === "cli");
+    const project = action.opts().project;
+    return {
+        command: names.join(" "),
+        flags,
+        projectRoot: typeof project === "string" ? resolve(cwd, project) : cwd
+    };
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function failureCode(value) {
+    return FAILURE_CODES.find((code) => code === value);
+}
+/**
+ * Reads only the structured outcome of one machine-readable output: status,
+ * failure code, and run id. Messages and every other field are ignored.
+ */
+export function outcomeFromJsonOutput(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout.trim());
+    }
+    catch {
+        return {};
+    }
+    const output = record(parsed);
+    if (output === undefined)
+        return {};
+    const report = record(output.report);
+    const status = [output.status, output.verdict].find((value) => (typeof value === "string" && /^[a-zA-Z][a-zA-Z\d]{0,31}$/.test(value)));
+    const code = failureCode(record(output.failure)?.code)
+        ?? failureCode(record(report?.primaryFailure)?.code);
+    const runId = [report?.runId, output.runId].find((value) => (typeof value === "string" && /^[\w.-]{1,128}$/.test(value)));
+    return {
+        ...(typeof status === "string" ? { status } : {}),
+        ...(code === undefined ? {} : { failureCode: code }),
+        ...(typeof runId === "string" ? { runId } : {})
+    };
+}
+export function commandEvent(input) {
+    return CommandEventSchema.parse({
+        version: 1,
+        kind: "command",
+        at: input.startedAt.toISOString(),
+        taphoundVersion: readCliVersion(),
+        host: diagnosticsHost(),
+        command: input.invocation.command,
+        flags: input.invocation.flags,
+        durationMs: Math.max(0, Math.round(input.durationMs)),
+        exitCode: input.exitCode,
+        ...(input.stdout === undefined ? {} : outcomeFromJsonOutput(input.stdout)),
+        ui: input.telemetry.summary()
+    });
+}

package/dist/cli/main.d.ts

@@ -5,4 +5,4 @@ export interface TerminationSignalSource {
     off: (event: "SIGINT" | "SIGTERM", listener: () => void) => unknown;
 }
 export declare function withTerminationSignal<T>(operation: (signal: AbortSignal) => Promise<T>, source?: TerminationSignalSource): Promise<T>;
-export declare function runMain(argv: readonly string[], dependencies?: CliDependencies): Promise<void>;
+export declare function runMain(argv: readonly string[], baseDependencies?: CliDependencies): Promise<void>;