taphound 0.2.0-dev.11 → 0.2.0-dev.12

package/README.md

@@ -90,7 +90,7 @@ taphound init --agent claude,codex,cursor,droid
 - [Principles](https://github.com/caikaidev/TapHound/blob/main/docs/principles.md) · [Workflow Skills and development scenarios](https://github.com/caikaidev/TapHound/blob/main/docs/workflow-skills.md) · [Agent integration](https://github.com/caikaidev/TapHound/blob/main/docs/agent-integration.md) · [Journey Generator guide](https://github.com/caikaidev/TapHound/blob/main/docs/journey-generator-guide.md)
 - [Acceptance Contracts](https://github.com/caikaidev/TapHound/blob/main/docs/contract-schema.md) · [Baselines & regression](https://github.com/caikaidev/TapHound/blob/main/docs/checkpoint-regression.md) · [Failure classification](https://github.com/caikaidev/TapHound/blob/main/docs/failure-classification.md)
 - [Semantic Anchors](https://github.com/caikaidev/TapHound/blob/main/docs/semantic-anchor.md) · [Capability matrix](https://github.com/caikaidev/TapHound/blob/main/docs/capability-matrix.md) · [`observe`](https://github.com/caikaidev/TapHound/blob/main/docs/observe.md)
-- [Runtime backends](https://github.com/caikaidev/TapHound/blob/main/docs/architecture/runtime-backend.md) · [Local development & testing](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) · [Releasing](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md)
+- [Runtime backends](https://github.com/caikaidev/TapHound/blob/main/docs/architecture/runtime-backend.md) · [Local development & testing](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) · [Releasing](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md) · [Diagnostics and feedback](https://github.com/caikaidev/TapHound/blob/main/docs/diagnostics.md)
 
 ## Current Limitations
 

package/README.zh-CN.md

@@ -90,7 +90,7 @@ taphound init --agent claude,codex,cursor,droid
 - [设计原则](https://github.com/caikaidev/TapHound/blob/main/docs/principles.md) · [Workflow Skill 与开发场景](https://github.com/caikaidev/TapHound/blob/main/docs/workflow-skills.md) · [Agent 集成](https://github.com/caikaidev/TapHound/blob/main/docs/agent-integration.md) · [Journey Generator 指南](https://github.com/caikaidev/TapHound/blob/main/docs/journey-generator-guide.md)
 - [Acceptance Contract](https://github.com/caikaidev/TapHound/blob/main/docs/contract-schema.md) · [Baseline 与回归对比](https://github.com/caikaidev/TapHound/blob/main/docs/checkpoint-regression.md) · [失败分类](https://github.com/caikaidev/TapHound/blob/main/docs/failure-classification.md)
 - [Semantic Anchor](https://github.com/caikaidev/TapHound/blob/main/docs/semantic-anchor.md) · [能力矩阵](https://github.com/caikaidev/TapHound/blob/main/docs/capability-matrix.md) · [`observe`](https://github.com/caikaidev/TapHound/blob/main/docs/observe.md)
-- [运行时后端](https://github.com/caikaidev/TapHound/blob/main/docs/architecture/runtime-backend.md) · [本地开发与测试](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) · [发布](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md)
+- [运行时后端](https://github.com/caikaidev/TapHound/blob/main/docs/architecture/runtime-backend.md) · [本地开发与测试](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) · [发布](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md) · [诊断与反馈](https://github.com/caikaidev/TapHound/blob/main/docs/diagnostics.md)
 
 ## 当前限制
 

package/assets/skills/taphound-journey-generator/SKILL.md

@@ -488,6 +488,13 @@ the index with `taphound knowledge rehash --project <project> --json` and
   session's selected module shards, stop and report a Context coverage gap.
   Do not add modules after start because `contextSelection` is bound to the
   authoritative session.
+- When TapHound itself misbehaves (a crash, a result that contradicts the
+  device, or unexplained slowness), run
+  `taphound diagnose export --project <project>` and give the user the printed
+  bundle path to attach to their report. The bundle is redacted; do not add
+  paths, screenshots, or log excerpts to the report yourself.
+- `UI_SNAPSHOT_FAILED` exits `3`: it is an environment failure, not
+  evidence about the app. Rerun before diagnosing the Journey.
 - Repeated `UI_SNAPSHOT_FAILED` ("UIAutomator dump failed") on a slow or
   busy device usually means the dump deadline is too tight, not that the
   device is broken. Raise `ui.snapshotTimeoutMs` in `.taphound/config.json`

package/assets/skills/taphound-journey-generator/scripts/envelope.mjs

@@ -370,6 +370,14 @@ function validateEnvelope(envelope) {
 
 // A bind source is one observe output, one step output, or a raw binding
 // object. The binding fields are copied verbatim; nothing is invented.
+const BIND_SOURCE_HINT = "bind --from expects the unmodified stdout of "
+  + "`taphound generation observe --json` (status \"observed\" with "
+  + "generationId, baseRevision, snapshotHash, snapshotRef) or of a succeeded "
+  + "`taphound generation step --json` (status \"succeeded\" with nextBinding "
+  + "and nextSnapshotRef); save it with `> file` instead of assembling a "
+  + "subset. A bare binding {generationId, baseRevision, snapshotHash} is also "
+  + "accepted";
+
 function readBindingFromSource(source) {
   if (!isPlainObject(source)) {
     fail("ENVELOPE_INVALID", "bind source must be a JSON object");
@@ -460,7 +468,16 @@ async function bind(inputPath, fromPath, outPath) {
     fail("ENVELOPE_INVALID", "envelope.version must be 1");
   }
   const source = await readJsonFile(fromPath, "bind source");
-  const { binding, snapshotRef } = readBindingFromSource(source);
+  let bindingSource;
+  try {
+    bindingSource = readBindingFromSource(source);
+  } catch (error) {
+    if (error?.code === "ENVELOPE_INVALID") {
+      fail("ENVELOPE_INVALID", `${error.message}. ${BIND_SOURCE_HINT}`);
+    }
+    throw error;
+  }
+  const { binding, snapshotRef } = bindingSource;
   const proposal = isPlainObject(envelope.proposal)
     ? { ...envelope.proposal, binding }
     : undefined;

package/assets/skills/taphound-verify-change/references/preserve.md

@@ -256,13 +256,16 @@ supported semantic element or structured event. Such a Case stays `PAUSED`,
 never silently weaker.
 
 The helper also requires a machine-generated process receipt because a report
-file alone cannot establish an independent CLI invocation:
+file alone cannot establish an independent CLI invocation. `taphound verify
+--journey` writes it as `receipt.json` beside the published `report.json` and
+prints its path as `receiptPath` in the `--json` output:
 
 ```json
 {
   "version": 1,
   "argv": [
     "verify", "--project", "/absolute/project",
+    "--config", "/absolute/project/.taphound/config.json",
     "--journey", "/absolute/project/.taphound/journeys/forward.json",
     "--device", "emulator-5554", "--policy-from-meta", "--json"
   ],
@@ -273,9 +276,13 @@ file alone cannot establish an independent CLI invocation:
 }
 ```
 
-The workflow runner must capture actual argv, exit status, and resulting
-digests. An agent must not write a success receipt merely because a report
-exists.
+`argv` is the normalized invocation TapHound ran: absolute project, config,
+and Journey paths plus the selected device serial. Pass the `receiptPath`
+that `verify` printed; never write or edit a receipt by hand. A missing
+`receiptPath` (the receipt could not be written, reported on stderr) means the
+evidence is unavailable, so rerun `verify`. Pass absolute, symlink-free
+`--project` and `--journey` paths so the recorded paths match the helper's
+checks.
 
 **A, historical worktree:**
 
@@ -288,7 +295,8 @@ exists.
      --device <serial> --policy-from-meta --json
    ```
 
-2. Record its process receipt. Prepare with a private input:
+2. Take `reportPath` and `receiptPath` from that `verify --json` output.
+   Prepare with a private input:
 
    ```json
    {
@@ -306,7 +314,7 @@ exists.
        "journeyPath": "/absolute/old-project/.taphound/journeys/forward.json",
        "metaPath": "/absolute/old-project/.taphound/journeys/forward.meta.json",
        "reportPath": "/absolute/old-project/.taphound/build/runs/<run>/report.json",
-       "receiptPath": "/absolute/old-project/.taphound/build/workflows/<case>/receipt.json"
+       "receiptPath": "/absolute/old-project/.taphound/build/runs/<run>/receipt.json"
      }
    }
    ```
@@ -332,7 +340,7 @@ exists.
    goal/scenario against B's current Project Context and UI, but copy every
    observable exactly into its deterministic expectations. Finalize it, then
    launch a separate strict `verify` process on the installed refactored APK
-   and record the same receipt shape.
+   and keep the `reportPath` and `receiptPath` it prints.
 3. Compare only after that independent Replay:
 
    ```

package/assets/skills/taphound-verify-change/scripts/ui-refactor.mjs

@@ -449,7 +449,7 @@ async function compare(handoff, projectPath, journeyPath, reportPath, receiptPat
   await checkReceipt(receiptFile, project, journeyFile, reportFile,
     data.manifest.base.device, {
       journey: journeyHash(journey), report: await fileHash(reportFile)
-    }, report.status === "failed" ? 4 : 0);
+    }, report.status === "failed" ? 1 : 0);
   const covered = checkReplay(project, data.manifest.base.device,
     data.caseData, journey, meta, report, reportFile);
   if (report.runId === data.manifest.base.runId) {

package/dist/adapters/appium/appium-ui-snapshot-provider.d.ts

@@ -15,6 +15,12 @@ export interface AppiumHttpClient {
 export interface AppiumProviderOptions {
     endpoint?: string | undefined;
     mapTestTagToResourceId?: boolean | undefined;
+    /** Called after each attempt to recreate a degraded session. */
+    onSessionRecovery?: ((succeeded: boolean) => void) | undefined;
+}
+export declare class AppiumHttpError extends Error {
+    readonly status: number;
+    constructor(status: number);
 }
 export declare class FetchAppiumHttpClient implements AppiumHttpClient {
     private readonly endpoint;
@@ -28,7 +34,9 @@ export declare class AppiumUiSnapshotProviderFactory implements UiSnapshotProvid
     private readonly endpoint;
     private readonly http;
     private readonly settings;
+    private readonly onSessionRecovery;
     constructor(runner: ProcessRunner, http?: AppiumHttpClient, options?: AppiumProviderOptions);
     probe(timeoutMs?: number): Promise<boolean>;
     open(options: OpenUiSnapshotProviderOptions): Promise<UiSnapshotProvider>;
+    private createSession;
 }

package/dist/adapters/appium/appium-ui-snapshot-provider.js

@@ -14,6 +14,14 @@ function loopbackEndpoint(value) {
     }
     return endpoint;
 }
+export class AppiumHttpError extends Error {
+    status;
+    constructor(status) {
+        super(`Appium HTTP ${String(status)}`);
+        this.status = status;
+        this.name = "AppiumHttpError";
+    }
+}
 export class FetchAppiumHttpClient {
     endpoint;
     constructor(endpoint) {
@@ -36,7 +44,7 @@ export class FetchAppiumHttpClient {
         });
         const payload = await response.json();
         if (!response.ok) {
-            throw new Error(`Appium HTTP ${String(response.status)}`);
+            throw new AppiumHttpError(response.status);
         }
         return { value: payload.value };
     }
@@ -47,18 +55,33 @@ function objectValue(value) {
     }
     return value;
 }
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * A page source request that timed out or hit a session Appium no longer
+ * knows (HTTP 404) points at a degraded UiAutomator2 session, not at the app.
+ */
+function degradedSession(error) {
+    return (error instanceof DOMException && error.name === "TimeoutError")
+        || (error instanceof AppiumHttpError && error.status === 404);
+}
 class AppiumUiSnapshotProvider {
     http;
     sessionId;
+    createSession;
     environment;
     descriptor;
+    onSessionRecovery;
     closePromise;
     lastSourceSignature;
-    constructor(http, sessionId, environment, descriptor) {
+    constructor(http, sessionId, createSession, environment, descriptor, onSessionRecovery) {
         this.http = http;
         this.sessionId = sessionId;
+        this.createSession = createSession;
         this.environment = environment;
         this.descriptor = descriptor;
+        this.onSessionRecovery = onSessionRecovery;
     }
     reset() {
         this.lastSourceSignature = undefined;
@@ -90,15 +113,24 @@ class AppiumUiSnapshotProvider {
         const startedAt = performance.now();
         let source;
         try {
-            source = (await this.http.request({
-                method: "GET",
-                path: `/session/${this.sessionId}/source`,
-                timeoutMs: options.timeoutMs,
-                ...(options.signal === undefined ? {} : { signal: options.signal })
-            })).value;
+            source = await this.pageSource(options);
         }
         catch (error) {
-            throw new UiSnapshotError("UI_SNAPSHOT_FAILED", this.descriptor.id, `Appium page source capture failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error, terminal: true });
+            if (options.signal?.aborted === true || !degradedSession(error)) {
+                throw this.captureFailure(errorText(error), error);
+            }
+            // Capture is read-only, so one retry on a fresh session cannot change
+            // what Replay observes; it only stops a degraded session from turning
+            // into a false verification failure.
+            try {
+                await this.recreateSession(options.signal);
+                source = await this.pageSource(options);
+                this.onSessionRecovery?.(true);
+            }
+            catch (retryError) {
+                this.onSessionRecovery?.(false);
+                throw this.captureFailure(`${errorText(error)}; retry on a recreated session failed: ${errorText(retryError)}`, retryError);
+            }
         }
         if (typeof source !== "string") {
             throw new UiSnapshotError("UI_SNAPSHOT_INVALID", this.descriptor.id, "Appium returned a non-string page source");
@@ -121,6 +153,34 @@ class AppiumUiSnapshotProvider {
             timing: {}
         });
     }
+    async pageSource(options) {
+        return (await this.http.request({
+            method: "GET",
+            path: `/session/${this.sessionId}/source`,
+            timeoutMs: options.timeoutMs,
+            ...(options.signal === undefined ? {} : { signal: options.signal })
+        })).value;
+    }
+    captureFailure(detail, cause) {
+        return new UiSnapshotError("UI_SNAPSHOT_FAILED", this.descriptor.id, `Appium page source capture failed: ${detail}`, { cause, terminal: true });
+    }
+    async recreateSession(signal) {
+        await this.http.request({
+            method: "DELETE",
+            path: `/session/${this.sessionId}`,
+            timeoutMs: 2000
+        }).catch(() => undefined);
+        const sessionId = await this.createSession(signal);
+        if (this.closePromise !== undefined) {
+            await this.http.request({
+                method: "DELETE",
+                path: `/session/${sessionId}`,
+                timeoutMs: 5000
+            }).catch(() => undefined);
+            throw new Error("Appium UI snapshot provider is closed");
+        }
+        this.sessionId = sessionId;
+    }
     close() {
         this.closePromise ??= this.http.request({
             method: "DELETE",
@@ -135,6 +195,7 @@ export class AppiumUiSnapshotProviderFactory {
     endpoint;
     http;
     settings;
+    onSessionRecovery;
     constructor(runner, http, options = {}) {
         this.runner = runner;
         this.endpoint = loopbackEndpoint(options.endpoint ?? "http://127.0.0.1:4723/");
@@ -142,6 +203,7 @@ export class AppiumUiSnapshotProviderFactory {
         this.settings = {
             mapTestTagToResourceId: options.mapTestTagToResourceId ?? false
         };
+        this.onSessionRecovery = options.onSessionRecovery;
     }
     async probe(timeoutMs = 2000) {
         try {
@@ -158,7 +220,7 @@ export class AppiumUiSnapshotProviderFactory {
     }
     async open(options) {
         const environment = await readDeviceUiEnvironment(this.runner, "appium-uiautomator2", options);
-        let provisionalSessionId;
+        let provider;
         try {
             const status = objectValue((await this.http.request({
                 method: "GET",
@@ -170,41 +232,8 @@ export class AppiumUiSnapshotProviderFactory {
             const engineVersion = typeof build.version === "string"
                 ? build.version
                 : "unknown";
-            const created = objectValue((await this.http.request({
-                method: "POST",
-                path: "/session",
-                timeoutMs: options.timeoutMs,
-                body: {
-                    capabilities: {
-                        alwaysMatch: {
-                            platformName: "Android",
-                            "appium:automationName": "UiAutomator2",
-                            "appium:udid": options.deviceSerial,
-                            "appium:noReset": true,
-                            "appium:autoLaunch": false,
-                            "appium:autoGrantPermissions": false,
-                            "appium:fullReset": false,
-                            "appium:shouldTerminateApp": false
-                        },
-                        firstMatch: [{}]
-                    }
-                },
-                ...(options.signal === undefined ? {} : { signal: options.signal })
-            })).value);
-            const sessionId = typeof created.sessionId === "string"
-                ? created.sessionId
-                : undefined;
-            if (sessionId === undefined) {
-                throw new Error("Appium did not return a session id");
-            }
-            provisionalSessionId = sessionId;
-            await this.http.request({
-                method: "POST",
-                path: `/session/${sessionId}/appium/settings`,
-                timeoutMs: options.timeoutMs,
-                body: { settings: this.settings },
-                ...(options.signal === undefined ? {} : { signal: options.signal })
-            });
+            const createSession = (signal) => this.createSession(options.deviceSerial, options.timeoutMs, signal);
+            const sessionId = await createSession(options.signal);
             const descriptor = {
                 id: "appium-uiautomator2",
                 adapterVersion: "appium-uiautomator2-v1",
@@ -215,26 +244,66 @@ export class AppiumUiSnapshotProviderFactory {
                     capabilitiesVersion: 1
                 })).digest("hex")
             };
-            const provider = new AppiumUiSnapshotProvider(this.http, sessionId, environment, descriptor);
+            provider = new AppiumUiSnapshotProvider(this.http, sessionId, createSession, environment, descriptor, this.onSessionRecovery);
             await provider.capture({
                 reason: "evidence",
                 timeoutMs: options.timeoutMs,
                 ...(options.signal === undefined ? {} : { signal: options.signal })
             });
-            provisionalSessionId = undefined;
             return provider;
         }
         catch (error) {
-            if (provisionalSessionId !== undefined) {
-                await this.http.request({
-                    method: "DELETE",
-                    path: `/session/${provisionalSessionId}`,
-                    timeoutMs: 5000
-                }).catch(() => undefined);
-            }
+            await provider?.close().catch(() => undefined);
             if (error instanceof UiSnapshotError)
                 throw error;
             throw new UiSnapshotError("UI_BACKEND_UNAVAILABLE", "appium-uiautomator2", "Appium UiAutomator2 session could not be opened", { cause: error });
         }
     }
+    async createSession(deviceSerial, timeoutMs, signal) {
+        const created = objectValue((await this.http.request({
+            method: "POST",
+            path: "/session",
+            timeoutMs,
+            body: {
+                capabilities: {
+                    alwaysMatch: {
+                        platformName: "Android",
+                        "appium:automationName": "UiAutomator2",
+                        "appium:udid": deviceSerial,
+                        "appium:noReset": true,
+                        "appium:autoLaunch": false,
+                        "appium:autoGrantPermissions": false,
+                        "appium:fullReset": false,
+                        "appium:shouldTerminateApp": false
+                    },
+                    firstMatch: [{}]
+                }
+            },
+            ...(signal === undefined ? {} : { signal })
+        })).value);
+        const sessionId = typeof created.sessionId === "string"
+            ? created.sessionId
+            : undefined;
+        if (sessionId === undefined) {
+            throw new Error("Appium did not return a session id");
+        }
+        try {
+            await this.http.request({
+                method: "POST",
+                path: `/session/${sessionId}/appium/settings`,
+                timeoutMs,
+                body: { settings: this.settings },
+                ...(signal === undefined ? {} : { signal })
+            });
+        }
+        catch (error) {
+            await this.http.request({
+                method: "DELETE",
+                path: `/session/${sessionId}`,
+                timeoutMs: 5000
+            }).catch(() => undefined);
+            throw error;
+        }
+        return sessionId;
+    }
 }

package/dist/adapters/filesystem/diagnostics-journal.d.ts

@@ -0,0 +1,17 @@
+import { type CommandEvent } from "../../domain/diagnostics.js";
+import type { DiagnosticsJournal } from "../../ports/diagnostics.js";
+/**
+ * Appends one JSON line per invocation under `.taphound/build/log/`. It only
+ * writes where a command already initialized the ignored build layout (the
+ * build directory and `.taphound/.gitignore`), so read-only commands never
+ * create project files, and keeps the current file under `maxBytes` with one
+ * rotated predecessor.
+ */
+export declare class FileSystemDiagnosticsJournal implements DiagnosticsJournal {
+    private readonly maxBytes;
+    constructor(maxBytes?: number);
+    append(projectRoot: string, event: CommandEvent): Promise<void>;
+    readLines(projectRoot: string): Promise<readonly string[]>;
+    salt(projectRoot: string): Promise<Buffer>;
+    private ensureLogDirectory;
+}

package/dist/adapters/filesystem/diagnostics-journal.js

@@ -0,0 +1,130 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { CommandEventSchema, DIAGNOSTICS_EVENTS_FILE, DIAGNOSTICS_EVENTS_ROTATED_FILE, DIAGNOSTICS_SALT_FILE } from "../../domain/diagnostics.js";
+import { BUILD_DIR, BUILD_IGNORE_FILE, DIAGNOSTICS_LOG_DIR, TAPHOUND_DIR } from "../../domain/workspace.js";
+import { ensureBuildLayout } from "./workspace-layout.js";
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+function isMissing(error) {
+    return error?.code === "ENOENT";
+}
+async function isDirectory(path) {
+    try {
+        const stats = await lstat(path);
+        return stats.isDirectory() && !stats.isSymbolicLink();
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
+async function sizeOf(path) {
+    try {
+        return (await lstat(path)).size;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return 0;
+        throw error;
+    }
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissing(error))
+            return "";
+        throw error;
+    }
+}
+async function isFile(path) {
+    try {
+        const stats = await lstat(path);
+        return stats.isFile();
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
+/**
+ * Appends one JSON line per invocation under `.taphound/build/log/`. It only
+ * writes where a command already initialized the ignored build layout (the
+ * build directory and `.taphound/.gitignore`), so read-only commands never
+ * create project files, and keeps the current file under `maxBytes` with one
+ * rotated predecessor.
+ */
+export class FileSystemDiagnosticsJournal {
+    maxBytes;
+    constructor(maxBytes = DEFAULT_MAX_BYTES) {
+        this.maxBytes = maxBytes;
+    }
+    async append(projectRoot, event) {
+        if (!await isDirectory(join(projectRoot, BUILD_DIR))
+            || !await isFile(join(projectRoot, BUILD_IGNORE_FILE))) {
+            return;
+        }
+        const line = `${JSON.stringify(CommandEventSchema.parse(event))}\n`;
+        const directory = await this.ensureLogDirectory(projectRoot);
+        const current = join(directory, DIAGNOSTICS_EVENTS_FILE);
+        if (await sizeOf(current) + Buffer.byteLength(line) > this.maxBytes) {
+            await rename(current, join(directory, DIAGNOSTICS_EVENTS_ROTATED_FILE))
+                .catch((error) => {
+                if (!isMissing(error))
+                    throw error;
+            });
+        }
+        const handle = await open(current, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW, 0o600);
+        try {
+            await handle.writeFile(line, "utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async readLines(projectRoot) {
+        const directory = join(projectRoot, DIAGNOSTICS_LOG_DIR);
+        const text = await readOptional(join(directory, DIAGNOSTICS_EVENTS_ROTATED_FILE))
+            + await readOptional(join(directory, DIAGNOSTICS_EVENTS_FILE));
+        return text.split("\n").filter((line) => line.trim().length > 0);
+    }
+    async salt(projectRoot) {
+        if (!await isDirectory(join(projectRoot, TAPHOUND_DIR))) {
+            throw Object.assign(new Error(`Not a TapHound project (no ${TAPHOUND_DIR}/ directory): ${projectRoot}`), { code: "CONFIG_INVALID" });
+        }
+        await ensureBuildLayout(projectRoot);
+        const path = join(await this.ensureLogDirectory(projectRoot), DIAGNOSTICS_SALT_FILE);
+        try {
+            const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            const salt = randomBytes(32);
+            try {
+                await handle.writeFile(salt);
+            }
+            finally {
+                await handle.close();
+            }
+            return salt;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const salt = await readFile(path);
+        if (salt.length < 16) {
+            throw new Error(`Diagnostics salt is unreadable: ${DIAGNOSTICS_LOG_DIR}/${DIAGNOSTICS_SALT_FILE}`);
+        }
+        return salt;
+    }
+    async ensureLogDirectory(projectRoot) {
+        const directory = join(projectRoot, DIAGNOSTICS_LOG_DIR);
+        await mkdir(directory, { recursive: true });
+        if (!await isDirectory(directory)) {
+            throw new Error(`${DIAGNOSTICS_LOG_DIR} is not a directory`);
+        }
+        return directory;
+    }
+}

package/dist/application/diagnostics/diagnostics-exporter.d.ts

@@ -0,0 +1,29 @@
+import { type DiagnosticsBundle } from "../../domain/diagnostics.js";
+import type { DiagnosticsJournal } from "../../ports/diagnostics.js";
+export interface DiagnosticsExporterDependencies {
+    journal: DiagnosticsJournal;
+    readJson: (path: string) => Promise<unknown>;
+    now: () => Date;
+    taphoundVersion: string;
+    host: DiagnosticsBundle["host"];
+}
+export interface DiagnosticsExportInput {
+    projectRoot: string;
+    /** Most recent journal events to include. */
+    eventLimit: number;
+    /** Most recent referenced runs to summarize. */
+    runLimit: number;
+}
+/**
+ * Builds a feedback bundle from the local journal and the reports it
+ * references. Only allowlisted structural facts survive: identifying strings
+ * become ordinal aliases or salted digests, and everything else is dropped.
+ * The result is validated against the strict bundle schema before return.
+ */
+export declare class DiagnosticsExporter {
+    private readonly dependencies;
+    constructor(dependencies: DiagnosticsExporterDependencies);
+    export(input: DiagnosticsExportInput): Promise<DiagnosticsBundle>;
+    private readConfig;
+    private readReport;
+}