Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat(daemon): add diagnostic collector core

Gus621cc2ee5312
diff --git a/src/daemon/src/diagnostics/bundle.test.ts b/src/daemon/src/diagnostics/bundle.test.ts
new file mode 100644
index 000000000..2bd000e74
--- /dev/null
+++ b/src/daemon/src/diagnostics/bundle.test.ts
@@ -0,0 +1,321 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+interface DiagnosticEventRow {
+ recordType: "daemon_log" | "fsm";
+ timeMs: number;
+ [key: string]: unknown;
+}
+
+interface BundleArtifact {
+ path: string;
+ sizeBytes: number;
+ sha256: string;
+ uncompressedBytes: number;
+}
+
+interface BundleModule {
+ DIAGNOSTIC_NDJSON_MAX_BYTES: number;
+ DIAGNOSTIC_GZIP_MAX_BYTES: number;
+ buildDiagnosticBundle(args: {
+ outputPath: string;
+ header: Record<string, unknown>;
+ status: Record<string, unknown> | null;
+ events: AsyncIterable<DiagnosticEventRow> | Iterable<DiagnosticEventRow>;
+ sourceWarnings?: readonly string[];
+ sourceDroppedRows?: Readonly<Record<string, number>>;
+ maxUncompressedBytes?: number;
+ maxCompressedBytes?: number;
+ }): Promise<BundleArtifact>;
+}
+
+async function loadSubject(): Promise<BundleModule> {
+ return vi.importActual<BundleModule>("./bundle.js");
+}
+
+const dirs = new Set<string>();
+
+function tempDir(): string {
+ const dir = mkdtempSync(join(tmpdir(), "diagnostics-bundle-"));
+ dirs.add(dir);
+ return dir;
+}
+
+afterEach(() => {
+ for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+ dirs.clear();
+});
+
+function decode(path: string): { bytes: Buffer; rows: Array<Record<string, unknown>> } {
+ const compressed = readFileSync(path);
+ const bytes = gunzipSync(compressed);
+ return {
+ bytes,
+ rows: bytes.toString("utf8").trimEnd().split("\n").map((line) => JSON.parse(line) as Record<string, unknown>),
+ };
+}
+
+function header(extra: Record<string, unknown> = {}): Record<string, unknown> {
+ return {
+ recordType: "bundle_header",
+ schemaVersion: 1,
+ reportId: "dbr_report_1",
+ agentId: "target-agent",
+ machineId: "machine-1",
+ capturedAt: 2000,
+ fromMs: 1000,
+ deadlineAt: 3000,
+ ...extra,
+ };
+}
+
+function event(source: "daemon_log" | "fsm", id: string, timeMs: number, payload = "x"): DiagnosticEventRow {
+ return { recordType: source, id, timeMs, payload };
+}
+
+describe("B2c bounded gzip NDJSON bundle", () => {
+ it("writes the exact header/status/events/footer order and a recomputable footer", async () => {
+ const api = await loadSubject();
+ const outputPath = join(tempDir(), "report.ndjson.gz");
+ const artifact = await api.buildDiagnosticBundle({
+ outputPath,
+ header: header(),
+ status: { recordType: "status", timeMs: 1500, agentId: "target-agent", status: "running" },
+ events: [event("daemon_log", "log-1", 1600), event("fsm", "fsm-1", 1700)],
+ sourceWarnings: ["malformed_json", "incomplete_tail"],
+ sourceDroppedRows: { daemon_log: 2, fsm: 1 },
+ });
+ const decoded = decode(outputPath);
+
+ expect(decoded.rows.map((row) => row.recordType)).toEqual([
+ "bundle_header",
+ "status",
+ "daemon_log",
+ "fsm",
+ "bundle_footer",
+ ]);
+ expect(decoded.rows[0]).toEqual({
+ recordType: "bundle_header",
+ schemaVersion: 1,
+ reportId: "dbr_report_1",
+ agentId: "target-agent",
+ machineId: "machine-1",
+ capturedAt: 2000,
+ fromMs: 1000,
+ deadlineAt: 3000,
+ });
+ expect(decoded.rows.at(-1)).toEqual({
+ recordType: "bundle_footer",
+ earliestAt: 1500,
+ latestAt: 1700,
+ counts: { status: 1, daemon_log: 1, fsm: 1 },
+ missingSources: [],
+ warnings: ["malformed_json", "incomplete_tail"],
+ droppedRows: { daemon_log: 2, fsm: 1 },
+ truncated: false,
+ uncompressedBytes: decoded.bytes.byteLength,
+ });
+ expect(decoded.bytes.at(-1)).toBe(0x0a);
+ expect(artifact).toEqual({
+ path: outputPath,
+ sizeBytes: statSync(outputPath).size,
+ sha256: createHash("sha256").update(readFileSync(outputPath)).digest("hex"),
+ uncompressedBytes: decoded.bytes.byteLength,
+ });
+ });
+
+ it("accounts for missing sources with fixed codes and never serializes source paths or exception text", async () => {
+ const api = await loadSubject();
+ const outputPath = join(tempDir(), "missing.ndjson.gz");
+ await api.buildDiagnosticBundle({
+ outputPath,
+ header: header(),
+ status: null,
+ events: [],
+ sourceWarnings: ["daemon_log_missing", "fsm_trace_missing", "status_missing"],
+ });
+ const encoded = decode(outputPath).bytes.toString("utf8");
+ const footer = JSON.parse(encoded.trimEnd().split("\n").at(-1)!) as Record<string, unknown>;
+ expect(footer).toMatchObject({
+ missingSources: ["daemon_log", "fsm_trace", "status"],
+ warnings: ["daemon_log_missing", "fsm_trace_missing", "status_missing"],
+ });
+ expect(encoded).not.toMatch(/\/Users\/|\/home\/|daemon\.log|fsm-trace\.jsonl|Error:|stack/);
+ });
+
+ it("evicts globally oldest complete rows so newer FSM beats older daemon rows", async () => {
+ const api = await loadSubject();
+ const outputPath = join(tempDir(), "fsm-wins.ndjson.gz");
+ await api.buildDiagnosticBundle({
+ outputPath,
+ header: header(),
+ status: null,
+ events: [
+ event("daemon_log", "old-log-1", 100, "a".repeat(240)),
+ event("daemon_log", "old-log-2", 200, "b".repeat(240)),
+ event("fsm", "new-fsm", 300, "c".repeat(240)),
+ ],
+ maxUncompressedBytes: 850,
+ });
+ const { bytes, rows } = decode(outputPath);
+ const encoded = bytes.toString("utf8");
+ expect(bytes.byteLength).toBeLessThanOrEqual(850);
+ expect(encoded).toContain("new-fsm");
+ expect(encoded).not.toContain("old-log-1");
+ expect(rows.at(-1)).toMatchObject({ truncated: true });
+ });
+
+ it("evicts globally oldest complete rows so newer daemon rows beat older FSM rows", async () => {
+ const api = await loadSubject();
+ const outputPath = join(tempDir(), "log-wins.ndjson.gz");
+ await api.buildDiagnosticBundle({
+ outputPath,
+ header: header(),
+ status: null,
+ events: [
+ event("fsm", "old-fsm-1", 100, "a".repeat(240)),
+ event("fsm", "old-fsm-2", 200, "b".repeat(240)),
+ event("daemon_log", "new-log", 300, "c".repeat(240)),
+ ],
+ maxUncompressedBytes: 850,
+ });
+ const { bytes, rows } = decode(outputPath);
+ const encoded = bytes.toString("utf8");
+ expect(bytes.byteLength).toBeLessThanOrEqual(850);
+ expect(encoded).toContain("new-log");
+ expect(encoded).not.toContain("old-fsm-1");
+ expect(rows.at(-1)).toMatchObject({ truncated: true });
+ });
+
+ it("keeps complete UTF-8 JSON lines and resolves equal timestamps deterministically", async () => {
+ const api = await loadSubject();
+ const outputPath = join(tempDir(), "utf8.ndjson.gz");
+ await api.buildDiagnosticBundle({
+ outputPath,
+ header: header(),
+ status: null,
+ events: [
+ event("daemon_log", "log-tie", 100, "错误".repeat(10)),
+ event("fsm", "fsm-tie", 100, "诊断".repeat(10)),
+ event("fsm", "newest", 200, "完整".repeat(10)),
+ ],
+ maxUncompressedBytes: 900,
+ });
+ const { bytes, rows } = decode(outputPath);
+ expect(bytes.byteLength).toBeLessThanOrEqual(900);
+ expect(() => new TextDecoder("utf-8", { fatal: true }).decode(bytes)).not.toThrow();
+ expect(rows.every((row) => typeof row === "object" && row !== null)).toBe(true);
+ const times = rows.filter((row) => row.recordType === "fsm" || row.recordType === "daemon_log").map((row) => row.timeMs);
+ expect(times).toEqual([...times].sort((a, b) => Number(a) - Number(b)));
+ expect(rows.filter((row) => "id" in row).map((row) => [row.recordType, row.id])).toEqual([
+ ["daemon_log", "log-tie"],
+ ["fsm", "fsm-tie"],
+ ["fsm", "newest"],
+ ]);
+ });
+
+ it("uses strict header projection and excludes hostname, username, paths, env, and credentials", async () => {
+ const api = await loadSubject();
+ const outputPath = join(tempDir(), "header.ndjson.gz");
+ await api.buildDiagnosticBundle({
+ outputPath,
+ header: header({
+ hostname: "HOSTNAME_LEAK",
+ username: "USERNAME_LEAK",
+ home: "/Users/alice",
+ workdir: "/Users/alice/project",
+ env: { TOKEN: "ENV_LEAK" },
+ machineKey: "cmk_SECRET",
+ reconnectToken: "cmt_SECRET",
+ }),
+ status: null,
+ events: [],
+ });
+ const encoded = decode(outputPath).bytes.toString("utf8");
+ expect(encoded).not.toMatch(/HOSTNAME_LEAK|USERNAME_LEAK|\/Users\/alice|ENV_LEAK|cmk_SECRET|cmt_SECRET/);
+ expect(Object.keys(decode(outputPath).rows[0]!).sort()).toEqual([
+ "agentId",
+ "capturedAt",
+ "deadlineAt",
+ "fromMs",
+ "machineId",
+ "recordType",
+ "reportId",
+ "schemaVersion",
+ ]);
+ });
+
+ it("consumes a lazy AsyncIterable event source", async () => {
+ const api = await loadSubject();
+ const outputPath = join(tempDir(), "async.ndjson.gz");
+ const pulled: string[] = [];
+ async function* events(): AsyncGenerator<DiagnosticEventRow> {
+ for (const row of [event("daemon_log", "async-log", 100), event("fsm", "async-fsm", 200)]) {
+ pulled.push(String(row.id));
+ await Promise.resolve();
+ yield row;
+ }
+ }
+ const source = events();
+ expect(pulled).toEqual([]);
+ await api.buildDiagnosticBundle({ outputPath, header: header(), status: null, events: source });
+ expect(pulled).toEqual(["async-log", "async-fsm"]);
+ expect(decode(outputPath).rows.filter((row) => "id" in row).map((row) => row.id)).toEqual([
+ "async-log",
+ "async-fsm",
+ ]);
+ });
+
+ it("produces deterministic gzip bytes and lowercase SHA for identical canonical input", async () => {
+ const api = await loadSubject();
+ const dir = tempDir();
+ const args = {
+ header: header(),
+ status: { recordType: "status", timeMs: 1500, agentId: "target-agent", status: "idle" },
+ events: [event("fsm", "one", 1600), event("daemon_log", "two", 1700)],
+ };
+ const one = await api.buildDiagnosticBundle({ ...args, outputPath: join(dir, "one.gz") });
+ const two = await api.buildDiagnosticBundle({ ...args, outputPath: join(dir, "two.gz") });
+ expect(readFileSync(one.path)).toEqual(readFileSync(two.path));
+ expect(one.sha256).toMatch(/^[a-f0-9]{64}$/);
+ expect(two.sha256).toBe(one.sha256);
+ });
+
+ it("enforces the production 9 MiB complete-envelope and 10 MiB gzip limits", async () => {
+ const api = await loadSubject();
+ expect(api.DIAGNOSTIC_NDJSON_MAX_BYTES).toBe(9 * 1024 * 1024);
+ expect(api.DIAGNOSTIC_GZIP_MAX_BYTES).toBe(10 * 1024 * 1024);
+
+ const outputPath = join(tempDir(), "max.ndjson.gz");
+ const noisy = randomBytes(700_000).toString("base64");
+ const events = Array.from({ length: 12 }, (_, index) => event(
+ index % 2 === 0 ? "daemon_log" : "fsm",
+ `row-${index}`,
+ 1000 + index,
+ noisy,
+ ));
+ const artifact = await api.buildDiagnosticBundle({ outputPath, header: header(), status: null, events });
+ const decoded = decode(outputPath);
+ expect(decoded.bytes.byteLength).toBeLessThanOrEqual(api.DIAGNOSTIC_NDJSON_MAX_BYTES);
+ expect(artifact.uncompressedBytes).toBe(decoded.bytes.byteLength);
+ expect(artifact.sizeBytes).toBeLessThanOrEqual(api.DIAGNOSTIC_GZIP_MAX_BYTES);
+ expect(decoded.rows.at(-1)).toMatchObject({ recordType: "bundle_footer", truncated: true });
+ });
+
+ it("fails closed and removes the output when an injected compressed limit is exceeded", async () => {
+ const api = await loadSubject();
+ const outputPath = join(tempDir(), "too-large.ndjson.gz");
+ await expect(api.buildDiagnosticBundle({
+ outputPath,
+ header: header(),
+ status: null,
+ events: [event("fsm", "noise", 100, randomBytes(4096).toString("base64"))],
+ maxCompressedBytes: 64,
+ })).rejects.toMatchObject({ code: "bundle_too_large" });
+ expect(() => readFileSync(outputPath)).toThrow();
+ });
+});
diff --git a/src/daemon/src/diagnostics/bundle.ts b/src/daemon/src/diagnostics/bundle.ts
new file mode 100644
index 000000000..fda6a05f8
--- /dev/null
+++ b/src/daemon/src/diagnostics/bundle.ts
@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { createWriteStream, unlinkSync } from "node:fs";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
+import type { BundleArtifact, DiagnosticEventRow } from "./types.js";
+
+export const DIAGNOSTIC_NDJSON_MAX_BYTES = 9 * 1024 * 1024;
+export const DIAGNOSTIC_GZIP_MAX_BYTES = 10 * 1024 * 1024;
+
+class BundleTooLargeError extends Error {
+ readonly code = "bundle_too_large";
+ constructor() { super("diagnostic bundle exceeds its compressed byte limit"); }
+}
+
+function line(value: Record<string, unknown>): Buffer {
+ return Buffer.from(`${JSON.stringify(value)}\n`, "utf8");
+}
+
+function projectHeader(header: Record<string, unknown>): Record<string, unknown> {
+ return {
+ recordType: header.recordType,
+ schemaVersion: header.schemaVersion,
+ reportId: header.reportId,
+ agentId: header.agentId,
+ machineId: header.machineId,
+ capturedAt: header.capturedAt,
+ fromMs: header.fromMs,
+ deadlineAt: header.deadlineAt,
+ };
+}
+
+async function* asAsync<T>(input: AsyncIterable<T> | Iterable<T>): AsyncGenerator<T> {
+ if (Symbol.asyncIterator in input) {
+ for await (const value of input as AsyncIterable<T>) yield value;
+ } else {
+ for (const value of input as Iterable<T>) yield value;
+ }
+}
+
+function missingSources(warnings: readonly string[]): string[] {
+ const missing: string[] = [];
+ if (warnings.includes("daemon_log_missing")) missing.push("daemon_log");
+ if (warnings.includes("fsm_trace_missing")) missing.push("fsm_trace");
+ if (warnings.includes("status_missing")) missing.push("status");
+ return missing;
+}
+
+const WARNING_CODES = new Set([
+ "daemon_log_missing",
+ "fsm_trace_missing",
+ "status_missing",
+ "source_unavailable",
+ "malformed_json",
+ "line_too_long",
+ "incomplete_tail",
+ "invalid_timestamp",
+]);
+
+function fixedFooter(args: {
+ status: Record<string, unknown> | null;
+ earliestAt: number | null;
+ latestAt: number | null;
+ counts: { status: number; daemon_log: number; fsm: number };
+ warnings: readonly string[];
+ missing: readonly string[];
+ droppedRows: Readonly<Record<string, number>>;
+ truncated: boolean;
+ prefixBytes: number;
+}): { value: Record<string, unknown>; bytes: Buffer } {
+ let uncompressedBytes = 0;
+ let value: Record<string, unknown>;
+ let bytes: Buffer;
+ do {
+ value = {
+ recordType: "bundle_footer",
+ earliestAt: args.earliestAt,
+ latestAt: args.latestAt,
+ counts: args.counts,
+ missingSources: [...args.missing],
+ warnings: [...args.warnings],
+ droppedRows: { ...args.droppedRows },
+ truncated: args.truncated,
+ uncompressedBytes,
+ };
+ bytes = line(value);
+ const next = args.prefixBytes + bytes.byteLength;
+ if (next === uncompressedBytes) break;
+ uncompressedBytes = next;
+ } while (true);
+ return { value: value!, bytes: bytes! };
+}
+
+export async function buildDiagnosticBundle(args: {
+ outputPath: string;
+ header: Record<string, unknown>;
+ status: Record<string, unknown> | null;
+ events: AsyncIterable<DiagnosticEventRow> | Iterable<DiagnosticEventRow>;
+ sourceWarnings?: readonly string[];
+ sourceDroppedRows?: Readonly<Record<string, number>>;
+ maxUncompressedBytes?: number;
+ maxCompressedBytes?: number;
+}): Promise<BundleArtifact> {
+ const maxUncompressed = args.maxUncompressedBytes ?? DIAGNOSTIC_NDJSON_MAX_BYTES;
+ const maxCompressed = args.maxCompressedBytes ?? DIAGNOSTIC_GZIP_MAX_BYTES;
+ const headerBytes = line(projectHeader(args.header));
+ const statusBytes = args.status ? line(args.status) : null;
+ const warnings = [...new Set((args.sourceWarnings ?? []).filter((warning) => WARNING_CODES.has(warning)))];
+ const missing = missingSources(warnings);
+ const droppedRows: Record<string, number> = {};
+ for (const key of ["daemon_log", "fsm", "status"] as const) {
+ const value = args.sourceDroppedRows?.[key];
+ if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) droppedRows[key] = value;
+ }
+ const retained: Array<{ row: DiagnosticEventRow; bytes: Buffer }> = [];
+ let head = 0;
+ let retainedBytes = 0;
+ let truncated = false;
+ const counts = { status: args.status ? 1 : 0, daemon_log: 0, fsm: 0 };
+ const statusTime = typeof args.status?.timeMs === "number" ? args.status.timeMs : null;
+
+ const envelope = (): { footer: Buffer; total: number } => {
+ const firstEvent = retained[head]?.row.timeMs ?? null;
+ const lastEvent = retained.at(-1)?.row.timeMs ?? null;
+ const earliestAt = statusTime === null ? firstEvent : firstEvent === null ? statusTime : Math.min(statusTime, firstEvent);
+ const latestAt = statusTime === null ? lastEvent : lastEvent === null ? statusTime : Math.max(statusTime, lastEvent);
+ const footer = fixedFooter({
+ status: args.status,
+ earliestAt,
+ latestAt,
+ counts,
+ warnings,
+ missing,
+ droppedRows,
+ truncated,
+ prefixBytes: headerBytes.byteLength + (statusBytes?.byteLength ?? 0) + retainedBytes,
+ }).bytes;
+ return { footer, total: headerBytes.byteLength + (statusBytes?.byteLength ?? 0) + retainedBytes + footer.byteLength };
+ };
+
+ for await (const row of asAsync(args.events)) {
+ if ((row.recordType !== "daemon_log" && row.recordType !== "fsm") || !Number.isSafeInteger(row.timeMs)) continue;
+ const serialized = line(row);
+ retained.push({ row, bytes: serialized });
+ retainedBytes += serialized.byteLength;
+ counts[row.recordType] += 1;
+ while (envelope().total > maxUncompressed && head < retained.length) {
+ const removed = retained[head]!;
+ delete retained[head];
+ head += 1;
+ retainedBytes -= removed.bytes.byteLength;
+ counts[removed.row.recordType] -= 1;
+ droppedRows[removed.row.recordType] = (droppedRows[removed.row.recordType] ?? 0) + 1;
+ truncated = true;
+ }
+ if (head > 4_096 && head * 2 > retained.length) {
+ retained.splice(0, head);
+ head = 0;
+ }
+ }
+
+ const { footer, total } = envelope();
+ if (total > maxUncompressed) throw new BundleTooLargeError();
+ const hash = createHash("sha256");
+ let compressedBytes = 0;
+ const meter = new Transform({
+ transform(chunk: Buffer, _encoding, callback) {
+ compressedBytes += chunk.byteLength;
+ if (compressedBytes > maxCompressed) { callback(new BundleTooLargeError()); return; }
+ hash.update(chunk);
+ callback(null, chunk);
+ },
+ });
+ let created = false;
+ const destination = createWriteStream(args.outputPath, { flags: "wx", mode: 0o600 });
+ destination.once("open", () => { created = true; });
+ try {
+ await pipeline(
+ Readable.from([
+ headerBytes,
+ ...(statusBytes ? [statusBytes] : []),
+ ...retained.slice(head).map((entry) => entry.bytes),
+ footer,
+ ]),
+ createGzip({ level: 9 }),
+ meter,
+ destination,
+ );
+ } catch (error) {
+ if (created) { try { unlinkSync(args.outputPath); } catch { /* best effort */ } }
+ throw error;
+ }
+ return {
+ path: args.outputPath,
+ sizeBytes: compressedBytes,
+ sha256: hash.digest("hex"),
+ uncompressedBytes: total,
+ };
+}
diff --git a/src/daemon/src/diagnostics/coordinator.test.ts b/src/daemon/src/diagnostics/coordinator.test.ts
new file mode 100644
index 000000000..4ed1580d8
--- /dev/null
+++ b/src/daemon/src/diagnostics/coordinator.test.ts
@@ -0,0 +1,784 @@
+import { createHash } from "node:crypto";
+import {
+ closeSync,
+ existsSync,
+ fsyncSync,
+ lstatSync,
+ mkdtempSync,
+ mkdirSync,
+ openSync,
+ readFileSync,
+ renameSync,
+ rmSync,
+ statSync,
+ symlinkSync,
+ writeFileSync,
+ writeSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Readable } from "node:stream";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DiagnosticCollectCommand, DiagnosticReportFailureCode } from "@alook/shared";
+
+type TransportResult =
+ | { kind: "terminal"; status: "uploaded" | "failed" }
+ | { kind: "retryable" };
+
+interface DiagnosticTransport {
+ upload(
+ meta: { reportId: string; sizeBytes: number; sha256: string },
+ body: Readable,
+ ): Promise<TransportResult>;
+ fail(reportId: string, failureCode: DiagnosticReportFailureCode): Promise<TransportResult>;
+}
+
+type CrashPoint =
+ | "collecting_temp_written"
+ | "collecting_temp_fsynced"
+ | "collecting_renamed"
+ | "collecting_dir_fsynced"
+ | "archive_temp_written"
+ | "archive_temp_fsynced"
+ | "archive_renamed"
+ | "archive_dir_fsynced"
+ | "ready_temp_written"
+ | "ready_temp_fsynced"
+ | "ready_renamed"
+ | "ready_dir_fsynced"
+ | "before_upload"
+ | "after_upload";
+
+interface CoordinatorResult {
+ status: "uploaded" | "failed" | "pending" | "expired";
+ failureCode?: DiagnosticReportFailureCode;
+}
+
+interface CoordinatorModule {
+ DIAGNOSTIC_COORDINATOR_CRASH_POINTS: readonly CrashPoint[];
+ createDiagnosticReportCoordinator(args: {
+ machineDir: string;
+ buildBundle: (args: { command: DiagnosticCollectCommand; outputPath: string }) => Promise<{
+ path: string;
+ sizeBytes: number;
+ sha256: string;
+ }>;
+ transport: DiagnosticTransport;
+ now: () => number;
+ sleep: (delayMs: number) => Promise<void>;
+ scheduleRetry: (delayMs: number, task: () => Promise<void>) => () => void;
+ retry: { maxAttemptsPerRound: number; baseDelayMs: number; maxDelayMs: number };
+ checkpoint?: (point: CrashPoint) => void;
+ fsOps?: {
+ randomSuffix(): string;
+ open(path: string, flags: "wx" | "r", mode?: number): number;
+ write(fd: number, bytes: Uint8Array): void;
+ fsync(fd: number): void;
+ close(fd: number): void;
+ rename(from: string, to: string): void;
+ fsyncDirectory(path: string): void;
+ };
+ logger?: { warn(message: string, fields: Record<string, unknown>): void };
+ }): {
+ collect(command: DiagnosticCollectCommand): Promise<CoordinatorResult>;
+ recover(): Promise<void>;
+ shutdown(): Promise<void>;
+ };
+}
+
+async function loadSubject(): Promise<CoordinatorModule> {
+ return vi.importActual<CoordinatorModule>("./coordinator.js");
+}
+
+const dirs = new Set<string>();
+
+function tempDir(): string {
+ const dir = mkdtempSync(join(tmpdir(), "diagnostics-coordinator-"));
+ dirs.add(dir);
+ return dir;
+}
+
+afterEach(() => {
+ for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+ dirs.clear();
+});
+
+function command(overrides: Partial<DiagnosticCollectCommand> = {}): DiagnosticCollectCommand {
+ return {
+ type: "diagnostics:collect",
+ reportId: "dbr_report_1",
+ agentId: "agent-1",
+ fromMs: 1_000,
+ deadlineAt: 86_401_000,
+ ...overrides,
+ };
+}
+
+async function streamBytes(stream: Readable): Promise<Buffer> {
+ const chunks: Buffer[] = [];
+ for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+ return Buffer.concat(chunks);
+}
+
+function coordinatorHarness(
+ api: CoordinatorModule,
+ overrides: Partial<Parameters<CoordinatorModule["createDiagnosticReportCoordinator"]>[0]> & { archiveBytes?: Buffer } = {},
+) {
+ const machineDir = overrides.machineDir ?? tempDir();
+ const archiveBytes = overrides.archiveBytes ?? Buffer.from("fixed-gzip-archive-bytes");
+ const buildBundle = overrides.buildBundle ?? vi.fn(async ({ outputPath }: { command: DiagnosticCollectCommand; outputPath: string }) => {
+ writeFileSync(outputPath, archiveBytes, { flag: "wx", mode: 0o600 });
+ return {
+ path: outputPath,
+ sizeBytes: archiveBytes.byteLength,
+ sha256: createHash("sha256").update(archiveBytes).digest("hex"),
+ };
+ });
+ const uploaded: Array<{ meta: { reportId: string; sizeBytes: number; sha256: string }; bytes: Buffer }> = [];
+ const transport: DiagnosticTransport = overrides.transport ?? {
+ upload: vi.fn(async (meta, body) => {
+ uploaded.push({ meta, bytes: await streamBytes(body) });
+ return { kind: "terminal", status: "uploaded" } as const;
+ }),
+ fail: vi.fn(async () => ({ kind: "terminal", status: "failed" }) as const),
+ };
+ const scheduled: Array<{ delayMs: number; task: () => Promise<void>; cancelled: boolean }> = [];
+ const instance = api.createDiagnosticReportCoordinator({
+ machineDir,
+ buildBundle,
+ transport,
+ now: overrides.now ?? (() => 2_000),
+ sleep: overrides.sleep ?? (async () => {}),
+ scheduleRetry: overrides.scheduleRetry ?? ((delayMs, task) => {
+ const entry = { delayMs, task, cancelled: false };
+ scheduled.push(entry);
+ return () => { entry.cancelled = true; };
+ }),
+ retry: overrides.retry ?? { maxAttemptsPerRound: 3, baseDelayMs: 10, maxDelayMs: 40 },
+ checkpoint: overrides.checkpoint,
+ fsOps: overrides.fsOps,
+ logger: overrides.logger,
+ });
+ return { instance, machineDir, archiveBytes, buildBundle, transport, uploaded, scheduled };
+}
+
+function diagnosticsDir(machineDir: string): string {
+ return join(machineDir, "diagnostics");
+}
+
+function archivePath(machineDir: string, reportId = "dbr_report_1"): string {
+ return join(diagnosticsDir(machineDir), `report-${reportId}.ndjson.gz`);
+}
+
+function sidecarPath(machineDir: string, reportId = "dbr_report_1"): string {
+ return join(diagnosticsDir(machineDir), `report-${reportId}.json`);
+}
+
+describe("B2c durable diagnostic coordinator", () => {
+ it("commits an exact collecting sidecar before bundle creation and a ready sidecar before first upload", async () => {
+ const api = await loadSubject();
+ let harness!: ReturnType<typeof coordinatorHarness>;
+ const archiveBytes = Buffer.from("fixed-gzip-archive-bytes");
+ const sha256 = createHash("sha256").update(archiveBytes).digest("hex");
+ const buildBundle = vi.fn(async ({ command: request, outputPath }: { command: DiagnosticCollectCommand; outputPath: string }) => {
+ const collecting = JSON.parse(readFileSync(sidecarPath(harness.machineDir), "utf8")) as Record<string, unknown>;
+ expect(collecting).toEqual({
+ schemaVersion: 1,
+ phase: "collecting",
+ reportId: request.reportId,
+ agentId: request.agentId,
+ fromMs: request.fromMs,
+ deadlineAt: request.deadlineAt,
+ });
+ expect(JSON.stringify(collecting)).not.toMatch(/archiveBasename|absolute|path|cmk_|credential/);
+ writeFileSync(outputPath, archiveBytes, { flag: "wx", mode: 0o600 });
+ return { path: outputPath, sizeBytes: archiveBytes.length, sha256 };
+ });
+ let inspectedBeforeFirstByte = false;
+ const transport: DiagnosticTransport = {
+ upload: vi.fn(async (meta, body) => {
+ const ready = JSON.parse(readFileSync(sidecarPath(harness.machineDir), "utf8")) as Record<string, unknown>;
+ expect(ready).toEqual({
+ schemaVersion: 1,
+ phase: "ready",
+ reportId: "dbr_report_1",
+ agentId: "agent-1",
+ fromMs: 1_000,
+ deadlineAt: 86_401_000,
+ sizeBytes: archiveBytes.length,
+ sha256,
+ });
+ const archiveStat = lstatSync(archivePath(harness.machineDir));
+ expect(archiveStat.isFile()).toBe(true);
+ expect(archiveStat.isSymbolicLink()).toBe(false);
+ expect(archiveStat.mode & 0o777).toBe(0o600);
+ expect(readFileSync(archivePath(harness.machineDir))).toEqual(archiveBytes);
+ expect(meta).toEqual({ reportId: "dbr_report_1", sizeBytes: archiveBytes.length, sha256 });
+ inspectedBeforeFirstByte = true;
+
+ const uploadedBytes = await streamBytes(body);
+ expect(uploadedBytes).toEqual(archiveBytes);
+ expect(uploadedBytes.byteLength).toBe(ready.sizeBytes);
+ expect(createHash("sha256").update(uploadedBytes).digest("hex")).toBe(ready.sha256);
+ return { kind: "terminal", status: "uploaded" } as const;
+ }),
+ fail: vi.fn(async () => ({ kind: "terminal", status: "failed" }) as const),
+ };
+ harness = coordinatorHarness(api, { archiveBytes, buildBundle, transport });
+
+ await expect(harness.instance.collect(command())).resolves.toEqual({ status: "uploaded" });
+ expect(buildBundle).toHaveBeenCalledTimes(1);
+ expect(inspectedBeforeFirstByte).toBe(true);
+ expect(transport.upload).toHaveBeenCalledTimes(1);
+ expect(transport.fail).not.toHaveBeenCalled();
+ expect(existsSync(archivePath(harness.machineDir))).toBe(false);
+ expect(existsSync(sidecarPath(harness.machineDir))).toBe(false);
+ });
+
+ it("singleflights identical duplicates and rejects metadata conflicts without recollecting", async () => {
+ const api = await loadSubject();
+ let release!: () => void;
+ const gate = new Promise<void>((resolve) => { release = resolve; });
+ const base = coordinatorHarness(api);
+ const buildBundle = vi.fn(async ({ outputPath }: { command: DiagnosticCollectCommand; outputPath: string }) => {
+ await gate;
+ writeFileSync(outputPath, base.archiveBytes, { flag: "wx", mode: 0o600 });
+ return { path: outputPath, sizeBytes: base.archiveBytes.length, sha256: createHash("sha256").update(base.archiveBytes).digest("hex") };
+ });
+ const harness = coordinatorHarness(api, { machineDir: base.machineDir, buildBundle, transport: base.transport });
+
+ const first = harness.instance.collect(command());
+ const duplicate = harness.instance.collect(command());
+ const conflict = harness.instance.collect(command({ agentId: "agent-2" }));
+ release();
+
+ await expect(first).resolves.toEqual({ status: "uploaded" });
+ await expect(duplicate).resolves.toEqual({ status: "uploaded" });
+ await expect(conflict).resolves.toEqual({ status: "failed", failureCode: "local_artifact_invalid" });
+ expect(buildBundle).toHaveBeenCalledTimes(1);
+ expect(base.transport.upload).toHaveBeenCalledTimes(1);
+ expect(base.transport.fail).not.toHaveBeenCalled();
+ });
+
+ it("fails a different concurrent report as collector_busy without disturbing the active report", async () => {
+ const api = await loadSubject();
+ let release!: () => void;
+ const gate = new Promise<void>((resolve) => { release = resolve; });
+ const base = coordinatorHarness(api);
+ const buildBundle = vi.fn(async ({ outputPath }: { command: DiagnosticCollectCommand; outputPath: string }) => {
+ await gate;
+ writeFileSync(outputPath, base.archiveBytes, { flag: "wx", mode: 0o600 });
+ return { path: outputPath, sizeBytes: base.archiveBytes.length, sha256: createHash("sha256").update(base.archiveBytes).digest("hex") };
+ });
+ const harness = coordinatorHarness(api, { machineDir: base.machineDir, buildBundle, transport: base.transport });
+
+ const active = harness.instance.collect(command());
+ await expect(harness.instance.collect(command({ reportId: "dbr_report_2" }))).resolves.toEqual({
+ status: "failed",
+ failureCode: "collector_busy",
+ });
+ release();
+ await expect(active).resolves.toEqual({ status: "uploaded" });
+ expect(buildBundle).toHaveBeenCalledTimes(1);
+ expect(base.transport.fail).toHaveBeenCalledWith("dbr_report_2", "collector_busy");
+ });
+
+ it("durably writes sidecars with random same-directory wx/0600 temp files before rename and directory fsync", async () => {
+ const api = await loadSubject();
+ const operations: Array<{ op: string; path?: string; flags?: string; mode?: number }> = [];
+ let suffix = 0;
+ const fsOps = {
+ randomSuffix: vi.fn(() => `nonce-${++suffix}`),
+ open: vi.fn((path: string, flags: "wx" | "r", mode?: number) => {
+ operations.push({ op: "open", path, flags, mode });
+ return openSync(path, flags, mode);
+ }),
+ write: vi.fn((fd: number, bytes: Uint8Array) => {
+ operations.push({ op: "write" });
+ writeSync(fd, bytes);
+ }),
+ fsync: vi.fn((fd: number) => {
+ operations.push({ op: "fsync" });
+ fsyncSync(fd);
+ }),
+ close: vi.fn((fd: number) => {
+ operations.push({ op: "close" });
+ closeSync(fd);
+ }),
+ rename: vi.fn((from: string, to: string) => {
+ operations.push({ op: "rename", path: `${from}->${to}` });
+ renameSync(from, to);
+ }),
+ fsyncDirectory: vi.fn((path: string) => {
+ operations.push({ op: "fsyncDirectory", path });
+ if (process.platform === "win32") return;
+ const fd = openSync(path, "r");
+ try { fsyncSync(fd); } finally { closeSync(fd); }
+ }),
+ };
+ const bundleTemps: string[] = [];
+ const bytes = Buffer.from("durable-bytes");
+ const harness = coordinatorHarness(api, {
+ fsOps,
+ buildBundle: vi.fn(async ({ outputPath }) => {
+ bundleTemps.push(outputPath);
+ writeFileSync(outputPath, bytes, { flag: "wx", mode: 0o600 });
+ return { path: outputPath, sizeBytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
+ }),
+ });
+ await harness.instance.collect(command());
+
+ const exclusiveOpens = operations.filter((operation) => operation.op === "open" && operation.flags === "wx");
+ expect(exclusiveOpens).toHaveLength(2);
+ expect(exclusiveOpens.every((operation) => operation.mode === 0o600)).toBe(true);
+ const tempPaths = [...exclusiveOpens.map((operation) => operation.path!), ...bundleTemps];
+ expect(new Set(tempPaths).size).toBe(tempPaths.length);
+ expect(tempPaths.every((path) => join(path, "..") !== path && path.startsWith(`${diagnosticsDir(harness.machineDir)}/`))).toBe(true);
+
+ const names = operations.map((operation) => operation.op);
+ let cursor = 0;
+ for (let writeIndex = 0; writeIndex < 2; writeIndex += 1) {
+ const expected = ["open", "write", "fsync", "close", "rename", "fsyncDirectory"];
+ const actual: string[] = [];
+ for (; cursor < names.length && actual.length < expected.length; cursor += 1) {
+ if (names[cursor] === expected[actual.length]) actual.push(names[cursor]!);
+ }
+ expect(actual).toEqual(expected);
+ }
+ });
+
+ it("never reuses a colliding fixed temp or follows its symlink target", async () => {
+ const api = await loadSubject();
+ const machineDir = tempDir();
+ const outside = join(machineDir, "outside-target");
+ writeFileSync(outside, "must-survive");
+ const suffixes = ["collision", "fresh-1", "fresh-2", "fresh-3"];
+ let firstExclusivePath: string | null = null;
+ const fsOps = {
+ randomSuffix: vi.fn(() => suffixes.shift() ?? `fresh-${Date.now()}`),
+ open: vi.fn((path: string, flags: "wx" | "r", mode?: number) => {
+ if (flags === "wx" && firstExclusivePath === null) {
+ firstExclusivePath = path;
+ symlinkSync(outside, path);
+ }
+ return openSync(path, flags, mode);
+ }),
+ write: (fd: number, bytes: Uint8Array) => { writeSync(fd, bytes); },
+ fsync: (fd: number) => { fsyncSync(fd); },
+ close: (fd: number) => { closeSync(fd); },
+ rename: (from: string, to: string) => { renameSync(from, to); },
+ fsyncDirectory: (path: string) => {
+ if (process.platform === "win32") return;
+ const fd = openSync(path, "r");
+ try { fsyncSync(fd); } finally { closeSync(fd); }
+ },
+ };
+ const harness = coordinatorHarness(api, { machineDir, fsOps });
+ await expect(harness.instance.collect(command())).resolves.toEqual({ status: "uploaded" });
+ expect(fsOps.randomSuffix.mock.calls.length).toBeGreaterThanOrEqual(3);
+ expect(readFileSync(outside, "utf8")).toBe("must-survive");
+ expect(firstExclusivePath).not.toBeNull();
+ expect(lstatSync(firstExclusivePath!).isSymbolicLink()).toBe(true);
+ });
+
+ it("freezes every filesystem and upload crash checkpoint", async () => {
+ const api = await loadSubject();
+ expect(api.DIAGNOSTIC_COORDINATOR_CRASH_POINTS).toEqual([
+ "collecting_temp_written",
+ "collecting_temp_fsynced",
+ "collecting_renamed",
+ "collecting_dir_fsynced",
+ "archive_temp_written",
+ "archive_temp_fsynced",
+ "archive_renamed",
+ "archive_dir_fsynced",
+ "ready_temp_written",
+ "ready_temp_fsynced",
+ "ready_renamed",
+ "ready_dir_fsynced",
+ "before_upload",
+ "after_upload",
+ ]);
+
+ for (const point of api.DIAGNOSTIC_COORDINATOR_CRASH_POINTS) {
+ const machineDir = tempDir();
+ const firstBytes = Buffer.from(`first-archive-${point}`);
+ const resumedBytes = Buffer.from(`resumed-archive-${point}`);
+ const first = coordinatorHarness(api, {
+ machineDir,
+ archiveBytes: firstBytes,
+ checkpoint: (seen) => {
+ if (seen === point) throw new Error(`simulated crash at ${point}`);
+ },
+ });
+ await expect(first.instance.collect(command())).rejects.toThrow(`simulated crash at ${point}`);
+
+ const resumed = coordinatorHarness(api, { machineDir, archiveBytes: resumedBytes });
+ await resumed.instance.recover();
+ if (point === "collecting_temp_written" || point === "collecting_temp_fsynced") {
+ expect(resumed.buildBundle).not.toHaveBeenCalled();
+ expect(resumed.uploaded).toHaveLength(0);
+ await resumed.instance.collect(command());
+ }
+ const committedArchiveBoundary = [
+ "archive_renamed",
+ "archive_dir_fsynced",
+ "ready_temp_written",
+ "ready_temp_fsynced",
+ "ready_renamed",
+ "ready_dir_fsynced",
+ "before_upload",
+ "after_upload",
+ ].includes(point);
+ expect(resumed.buildBundle).toHaveBeenCalledTimes(committedArchiveBoundary ? 0 : 1);
+ expect(resumed.uploaded).toHaveLength(1);
+ expect(resumed.uploaded[0]?.bytes).toEqual(committedArchiveBoundary ? firstBytes : resumedBytes);
+ }
+ });
+
+ it("promotes archive-renamed plus collecting-sidecar recovery and reuses exact size/SHA/bytes", async () => {
+ const api = await loadSubject();
+ const machineDir = tempDir();
+ const first = coordinatorHarness(api, {
+ machineDir,
+ checkpoint: (point) => {
+ if (point === "archive_renamed") throw new Error("crash after archive rename");
+ },
+ });
+ await expect(first.instance.collect(command())).rejects.toThrow("crash after archive rename");
+ const committed = readFileSync(archivePath(machineDir));
+ const collecting = JSON.parse(readFileSync(sidecarPath(machineDir), "utf8")) as Record<string, unknown>;
+ expect(collecting.phase).toBe("collecting");
+
+ const resumed = coordinatorHarness(api, { machineDir });
+ await resumed.instance.recover();
+ expect(resumed.buildBundle).not.toHaveBeenCalled();
+ expect(resumed.uploaded[0]).toEqual({
+ meta: {
+ reportId: "dbr_report_1",
+ sizeBytes: committed.length,
+ sha256: createHash("sha256").update(committed).digest("hex"),
+ },
+ bytes: committed,
+ });
+ });
+
+ it("promotes archive-renamed state on an exact duplicate command and rejects persisted metadata mismatch", async () => {
+ const api = await loadSubject();
+ const exactDir = tempDir();
+ const first = coordinatorHarness(api, {
+ machineDir: exactDir,
+ archiveBytes: Buffer.from("committed-once"),
+ checkpoint: (point) => {
+ if (point === "archive_renamed") throw new Error("crash at same-byte boundary");
+ },
+ });
+ await expect(first.instance.collect(command())).rejects.toThrow("crash at same-byte boundary");
+ const committed = readFileSync(archivePath(exactDir));
+
+ const duplicate = coordinatorHarness(api, { machineDir: exactDir, archiveBytes: Buffer.from("must-not-build") });
+ await expect(duplicate.instance.collect(command())).resolves.toEqual({ status: "uploaded" });
+ expect(duplicate.buildBundle).not.toHaveBeenCalled();
+ expect(duplicate.uploaded[0]?.bytes).toEqual(committed);
+
+ const mismatchDir = tempDir();
+ const mismatchFirst = coordinatorHarness(api, {
+ machineDir: mismatchDir,
+ checkpoint: (point) => {
+ if (point === "archive_renamed") throw new Error("crash before mismatch");
+ },
+ });
+ await expect(mismatchFirst.instance.collect(command())).rejects.toThrow("crash before mismatch");
+ const mismatch = coordinatorHarness(api, { machineDir: mismatchDir });
+ await expect(mismatch.instance.collect(command({ fromMs: 999 }))).resolves.toEqual({
+ status: "failed",
+ failureCode: "local_artifact_invalid",
+ });
+ expect(mismatch.buildBundle).not.toHaveBeenCalled();
+ expect(mismatch.transport.upload).not.toHaveBeenCalled();
+ expect(mismatch.transport.fail).toHaveBeenCalledWith("dbr_report_1", "local_artifact_invalid");
+ });
+
+ it("retains one exact artifact across exponential retry exhaustion and the next scheduled round", async () => {
+ const api = await loadSubject();
+ const bodies: Buffer[] = [];
+ const transport: DiagnosticTransport = {
+ upload: vi.fn(async (_meta, body): Promise<TransportResult> => {
+ bodies.push(await streamBytes(body));
+ return bodies.length <= 3 ? { kind: "retryable" } : { kind: "terminal", status: "uploaded" };
+ }),
+ fail: vi.fn(async (): Promise<TransportResult> => ({ kind: "terminal", status: "failed" })),
+ };
+ const sleep = vi.fn(async (_delayMs: number) => {});
+ const harness = coordinatorHarness(api, { transport, sleep });
+
+ await expect(harness.instance.collect(command())).resolves.toEqual({ status: "pending" });
+ expect(harness.buildBundle).toHaveBeenCalledTimes(1);
+ expect(bodies).toHaveLength(3);
+ expect(bodies.every((bytes) => bytes.equals(harness.archiveBytes))).toBe(true);
+ expect(sleep.mock.calls.map(([delay]) => delay)).toEqual([10, 20]);
+ expect(harness.scheduled.map(({ delayMs }) => delayMs)).toEqual([40]);
+ expect(existsSync(archivePath(harness.machineDir))).toBe(true);
+ expect(existsSync(sidecarPath(harness.machineDir))).toBe(true);
+
+ await harness.scheduled[0]!.task();
+ expect(harness.buildBundle).toHaveBeenCalledTimes(1);
+ expect(bodies).toHaveLength(4);
+ expect(bodies[3]).toEqual(harness.archiveBytes);
+ expect(existsSync(archivePath(harness.machineDir))).toBe(false);
+ expect(existsSync(sidecarPath(harness.machineDir))).toBe(false);
+ });
+
+ it("fails missing, wrong-size, and same-size wrong-SHA ready artifacts independently without recollecting", async () => {
+ const api = await loadSubject();
+ const original = Buffer.from("archive-original");
+ for (const branch of ["missing", "wrong-size", "wrong-sha"] as const) {
+ const machineDir = tempDir();
+ const dir = diagnosticsDir(machineDir);
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
+ writeFileSync(sidecarPath(machineDir), JSON.stringify({
+ schemaVersion: 1,
+ phase: "ready",
+ reportId: "dbr_report_1",
+ agentId: "agent-1",
+ fromMs: 1000,
+ deadlineAt: 86_401_000,
+ sizeBytes: original.length,
+ sha256: createHash("sha256").update(original).digest("hex"),
+ }), { mode: 0o600 });
+ if (branch === "wrong-size") writeFileSync(archivePath(machineDir), "different-size");
+ if (branch === "wrong-sha") writeFileSync(archivePath(machineDir), Buffer.from("archive-originaL"));
+ const harness = coordinatorHarness(api, { machineDir });
+
+ await harness.instance.recover();
+ expect(harness.buildBundle, branch).not.toHaveBeenCalled();
+ expect(harness.transport.upload, branch).not.toHaveBeenCalled();
+ expect(harness.transport.fail, branch).toHaveBeenCalledWith("dbr_report_1", "local_artifact_invalid");
+ expect(existsSync(archivePath(machineDir)), branch).toBe(false);
+ expect(existsSync(sidecarPath(machineDir)), branch).toBe(false);
+ }
+ });
+
+ it("retains invalid artifacts across retryable failure PATCH and resumes the durable fail intent", async () => {
+ const api = await loadSubject();
+ for (const resumeKind of ["scheduled", "restart"] as const) {
+ const machineDir = tempDir();
+ const dir = diagnosticsDir(machineDir);
+ const original = Buffer.from("archive-original");
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
+ writeFileSync(sidecarPath(machineDir), JSON.stringify({
+ schemaVersion: 1,
+ phase: "ready",
+ reportId: "dbr_report_1",
+ agentId: "agent-1",
+ fromMs: 1000,
+ deadlineAt: 86_401_000,
+ sizeBytes: original.length,
+ sha256: createHash("sha256").update(original).digest("hex"),
+ }), { mode: 0o600 });
+ writeFileSync(archivePath(machineDir), Buffer.from("archive-originaL"), { mode: 0o600 });
+ let calls = 0;
+ const first = coordinatorHarness(api, {
+ machineDir,
+ retry: { maxAttemptsPerRound: 1, baseDelayMs: 10, maxDelayMs: 10 },
+ transport: {
+ upload: vi.fn(async (): Promise<TransportResult> => ({ kind: "retryable" })),
+ fail: vi.fn(async (): Promise<TransportResult> => {
+ calls += 1;
+ return resumeKind === "scheduled" && calls > 1
+ ? { kind: "terminal", status: "failed" }
+ : { kind: "retryable" };
+ }),
+ },
+ });
+ await first.instance.recover();
+ expect(existsSync(sidecarPath(machineDir)), resumeKind).toBe(true);
+ expect(existsSync(archivePath(machineDir)), resumeKind).toBe(true);
+
+ if (resumeKind === "scheduled") {
+ expect(first.scheduled).toHaveLength(1);
+ await first.scheduled[0]!.task();
+ } else {
+ await first.instance.shutdown();
+ const resumed = coordinatorHarness(api, { machineDir });
+ await resumed.instance.recover();
+ expect(resumed.transport.fail).toHaveBeenCalledWith("dbr_report_1", "local_artifact_invalid");
+ }
+ expect(existsSync(sidecarPath(machineDir)), resumeKind).toBe(false);
+ expect(existsSync(archivePath(machineDir)), resumeKind).toBe(false);
+ }
+ });
+
+ it("treats attributable corrupt sidecars as invalid, ignores embedded paths, and leaves unknown files untouched", async () => {
+ const api = await loadSubject();
+ const machineDir = tempDir();
+ const dir = diagnosticsDir(machineDir);
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
+ const outside = join(machineDir, "outside-secret");
+ writeFileSync(outside, "must-survive");
+ writeFileSync(sidecarPath(machineDir), JSON.stringify({
+ schemaVersion: 1,
+ phase: "ready",
+ reportId: "dbr_report_1",
+ archivePath: outside,
+ credential: "cmk_SECRET",
+ }), { mode: 0o600 });
+ writeFileSync(join(dir, "unknown-user-file"), "untouched");
+ const warn = vi.fn();
+ const harness = coordinatorHarness(api, { machineDir, logger: { warn } });
+
+ await harness.instance.recover();
+ expect(harness.buildBundle).not.toHaveBeenCalled();
+ expect(harness.transport.fail).toHaveBeenCalledWith("dbr_report_1", "local_artifact_invalid");
+ expect(warn).toHaveBeenCalledTimes(1);
+ expect(warn).toHaveBeenCalledWith("diagnostic local artifact invalid", {
+ reportId: "dbr_report_1",
+ code: "local_artifact_invalid",
+ });
+ expect(JSON.stringify(warn.mock.calls)).not.toMatch(/outside-secret|cmk_SECRET|archivePath|credential/);
+ expect(existsSync(sidecarPath(machineDir))).toBe(false);
+ expect(readFileSync(outside, "utf8")).toBe("must-survive");
+ expect(readFileSync(join(dir, "unknown-user-file"), "utf8")).toBe("untouched");
+ });
+
+ it("never overwrites an attributable committed archive that has no sidecar", async () => {
+ const api = await loadSubject();
+ const machineDir = tempDir();
+ mkdirSync(diagnosticsDir(machineDir), { recursive: true, mode: 0o700 });
+ writeFileSync(archivePath(machineDir), "already-committed-exact-bytes", { mode: 0o600 });
+ const harness = coordinatorHarness(api, { machineDir });
+
+ await harness.instance.recover();
+ expect(harness.buildBundle).not.toHaveBeenCalled();
+ expect(harness.transport.upload).not.toHaveBeenCalled();
+ expect(harness.transport.fail).toHaveBeenCalledWith("dbr_report_1", "local_artifact_invalid");
+ expect(existsSync(archivePath(machineDir))).toBe(false);
+ });
+
+ it("rejects symlinked artifacts without touching their targets", async () => {
+ const api = await loadSubject();
+ const machineDir = tempDir();
+ const dir = diagnosticsDir(machineDir);
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
+ const outside = join(machineDir, "outside-archive");
+ writeFileSync(outside, "outside-bytes");
+ symlinkSync(outside, archivePath(machineDir));
+ writeFileSync(sidecarPath(machineDir), JSON.stringify({
+ schemaVersion: 1,
+ phase: "ready",
+ reportId: "dbr_report_1",
+ agentId: "agent-1",
+ fromMs: 1000,
+ deadlineAt: 86_401_000,
+ sizeBytes: 13,
+ sha256: createHash("sha256").update("outside-bytes").digest("hex"),
+ }), { mode: 0o600 });
+ const harness = coordinatorHarness(api, { machineDir });
+
+ await harness.instance.recover();
+ expect(harness.transport.upload).not.toHaveBeenCalled();
+ expect(harness.transport.fail).toHaveBeenCalledWith("dbr_report_1", "local_artifact_invalid");
+ expect(readFileSync(outside, "utf8")).toBe("outside-bytes");
+ });
+
+ it("uses private modes and deletes only exact regular artifacts after confirmed terminal", async () => {
+ const api = await loadSubject();
+ const machineDir = tempDir();
+ let archiveMode = 0;
+ let sidecarMode = 0;
+ const harness = coordinatorHarness(api, {
+ machineDir,
+ checkpoint: (point) => {
+ if (point === "ready_dir_fsynced") {
+ archiveMode = statSync(archivePath(machineDir)).mode & 0o777;
+ sidecarMode = statSync(sidecarPath(machineDir)).mode & 0o777;
+ writeFileSync(join(diagnosticsDir(machineDir), "unknown-user-file"), "keep");
+ }
+ },
+ });
+ await harness.instance.collect(command());
+ if (process.platform !== "win32") {
+ expect(lstatSync(diagnosticsDir(machineDir)).mode & 0o777).toBe(0o700);
+ expect(archiveMode).toBe(0o600);
+ expect(sidecarMode).toBe(0o600);
+ }
+ expect(readFileSync(join(diagnosticsDir(machineDir), "unknown-user-file"), "utf8")).toBe("keep");
+ expect(existsSync(archivePath(machineDir))).toBe(false);
+ expect(existsSync(sidecarPath(machineDir))).toBe(false);
+ });
+
+ it("cleans attributable artifacts at the deadline without upload, failure PATCH, or recollection", async () => {
+ const api = await loadSubject();
+ const machineDir = tempDir();
+ const first = coordinatorHarness(api, {
+ machineDir,
+ transport: {
+ upload: vi.fn(async (_meta, body): Promise<TransportResult> => {
+ await streamBytes(body);
+ return { kind: "retryable" };
+ }),
+ fail: vi.fn(async (): Promise<TransportResult> => ({ kind: "terminal", status: "failed" })),
+ },
+ retry: { maxAttemptsPerRound: 1, baseDelayMs: 10, maxDelayMs: 10 },
+ });
+ await expect(first.instance.collect(command({ deadlineAt: 3000 }))).resolves.toEqual({ status: "pending" });
+ expect(existsSync(archivePath(machineDir))).toBe(true);
+
+ const expired = coordinatorHarness(api, { machineDir, now: () => 3000 });
+ await expired.instance.recover();
+ expect(expired.buildBundle).not.toHaveBeenCalled();
+ expect(expired.transport.upload).not.toHaveBeenCalled();
+ expect(expired.transport.fail).not.toHaveBeenCalled();
+ expect(existsSync(archivePath(machineDir))).toBe(false);
+ expect(existsSync(sidecarPath(machineDir))).toBe(false);
+ });
+
+ it("shutdown cancels scheduled retry and prevents its task from uploading or deleting ambiguous artifacts", async () => {
+ const api = await loadSubject();
+ const transport: DiagnosticTransport = {
+ upload: vi.fn(async (_meta, body): Promise<TransportResult> => {
+ await streamBytes(body);
+ return { kind: "retryable" };
+ }),
+ fail: vi.fn(async (): Promise<TransportResult> => ({ kind: "retryable" })),
+ };
+ const harness = coordinatorHarness(api, {
+ transport,
+ retry: { maxAttemptsPerRound: 1, baseDelayMs: 10, maxDelayMs: 10 },
+ });
+ await expect(harness.instance.collect(command())).resolves.toEqual({ status: "pending" });
+ expect(harness.scheduled).toHaveLength(1);
+ expect(transport.upload).toHaveBeenCalledTimes(1);
+
+ await harness.instance.shutdown();
+ expect(harness.scheduled[0]?.cancelled).toBe(true);
+ const buildCountAtShutdown = vi.mocked(harness.buildBundle).mock.calls.length;
+ await harness.scheduled[0]!.task();
+ expect(transport.upload).toHaveBeenCalledTimes(1);
+ expect(transport.fail).not.toHaveBeenCalled();
+ expect(harness.buildBundle).toHaveBeenCalledTimes(buildCountAtShutdown);
+ await expect(harness.instance.collect(command({ reportId: "dbr_report_2" }))).rejects.toMatchObject({
+ code: "coordinator_shutdown",
+ });
+ await expect(harness.instance.recover()).rejects.toMatchObject({ code: "coordinator_shutdown" });
+ expect(transport.upload).toHaveBeenCalledTimes(1);
+ expect(transport.fail).not.toHaveBeenCalled();
+ expect(harness.buildBundle).toHaveBeenCalledTimes(buildCountAtShutdown);
+ expect(existsSync(archivePath(harness.machineDir))).toBe(true);
+ expect(existsSync(sidecarPath(harness.machineDir))).toBe(true);
+ });
+
+ it("never follows an unsafe diagnostics directory and never scans outside the machine directory", async () => {
+ const api = await loadSubject();
+ const machineDir = tempDir();
+ const outside = tempDir();
+ writeFileSync(join(outside, "report-dbr_report_1.json"), "outside-sidecar");
+ symlinkSync(outside, diagnosticsDir(machineDir));
+ const harness = coordinatorHarness(api, { machineDir });
+
+ await expect(harness.instance.recover()).rejects.toMatchObject({ code: "local_artifact_invalid" });
+ expect(readFileSync(join(outside, "report-dbr_report_1.json"), "utf8")).toBe("outside-sidecar");
+ expect(harness.transport.upload).not.toHaveBeenCalled();
+ expect(harness.transport.fail).not.toHaveBeenCalled();
+ });
+});
diff --git a/src/daemon/src/diagnostics/coordinator.ts b/src/daemon/src/diagnostics/coordinator.ts
new file mode 100644
index 000000000..4662b2bff
--- /dev/null
+++ b/src/daemon/src/diagnostics/coordinator.ts
@@ -0,0 +1,407 @@
+import { createHash, randomBytes } from "node:crypto";
+import {
+ chmodSync,
+ closeSync,
+ createReadStream,
+ existsSync,
+ fsyncSync,
+ lstatSync,
+ mkdirSync,
+ openSync,
+ readFileSync,
+ readdirSync,
+ renameSync,
+ unlinkSync,
+ writeSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { DiagnosticCollectCommand, DiagnosticReportFailureCode } from "@alook/shared";
+import type {
+ DiagnosticBundleBuilder,
+ DiagnosticCoordinatorResult,
+ DiagnosticTransport,
+} from "./types.js";
+
+export const DIAGNOSTIC_COORDINATOR_CRASH_POINTS = [
+ "collecting_temp_written",
+ "collecting_temp_fsynced",
+ "collecting_renamed",
+ "collecting_dir_fsynced",
+ "archive_temp_written",
+ "archive_temp_fsynced",
+ "archive_renamed",
+ "archive_dir_fsynced",
+ "ready_temp_written",
+ "ready_temp_fsynced",
+ "ready_renamed",
+ "ready_dir_fsynced",
+ "before_upload",
+ "after_upload",
+] as const;
+
+export type DiagnosticCoordinatorCrashPoint = typeof DIAGNOSTIC_COORDINATOR_CRASH_POINTS[number];
+
+interface CollectingSidecar {
+ schemaVersion: 1;
+ phase: "collecting";
+ reportId: string;
+ agentId: string;
+ fromMs: number;
+ deadlineAt: number;
+}
+
+interface ReadySidecar extends Omit<CollectingSidecar, "phase"> {
+ phase: "ready";
+ sizeBytes: number;
+ sha256: string;
+}
+
+type Sidecar = CollectingSidecar | ReadySidecar;
+
+interface FsOps {
+ randomSuffix(): string;
+ open(path: string, flags: "wx" | "r", mode?: number): number;
+ write(fd: number, bytes: Uint8Array): void;
+ fsync(fd: number): void;
+ close(fd: number): void;
+ rename(from: string, to: string): void;
+ fsyncDirectory(path: string): void;
+}
+
+class CoordinatorError extends Error {
+ constructor(readonly code: "coordinator_shutdown" | "local_artifact_invalid") { super(code); }
+}
+
+function defaultFsOps(): FsOps {
+ return {
+ randomSuffix: () => randomBytes(12).toString("hex"),
+ open: (path, flags, mode) => openSync(path, flags, mode),
+ write: (fd, bytes) => { writeSync(fd, bytes); },
+ fsync: (fd) => { fsyncSync(fd); },
+ close: (fd) => { closeSync(fd); },
+ rename: (from, to) => { renameSync(from, to); },
+ fsyncDirectory: (path) => {
+ if (process.platform === "win32") return;
+ const fd = openSync(path, "r");
+ try { fsyncSync(fd); } finally { closeSync(fd); }
+ },
+ };
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+ return Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
+}
+
+function safeEpoch(value: unknown): value is number {
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function parseSidecar(value: unknown): Sidecar | null {
+ if (!isObject(value) || value.schemaVersion !== 1 || (value.phase !== "collecting" && value.phase !== "ready")) return null;
+ const baseKeys = ["schemaVersion", "phase", "reportId", "agentId", "fromMs", "deadlineAt"];
+ const keys = value.phase === "ready" ? [...baseKeys, "sizeBytes", "sha256"] : baseKeys;
+ if (!exactKeys(value, keys)
+ || typeof value.reportId !== "string" || !/^dbr_[A-Za-z0-9_-]+$/.test(value.reportId)
+ || typeof value.agentId !== "string" || !/^[A-Za-z0-9_-]+$/.test(value.agentId)
+ || !safeEpoch(value.fromMs) || !safeEpoch(value.deadlineAt)) return null;
+ if (value.phase === "ready") {
+ if (!safeEpoch(value.sizeBytes) || typeof value.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.sha256)) return null;
+ return value as unknown as ReadySidecar;
+ }
+ return value as unknown as CollectingSidecar;
+}
+
+function sameCommand(sidecar: Sidecar, command: DiagnosticCollectCommand): boolean {
+ return sidecar.reportId === command.reportId
+ && sidecar.agentId === command.agentId
+ && sidecar.fromMs === command.fromMs
+ && sidecar.deadlineAt === command.deadlineAt;
+}
+
+function commandFrom(sidecar: Sidecar): DiagnosticCollectCommand {
+ return { type: "diagnostics:collect", reportId: sidecar.reportId, agentId: sidecar.agentId, fromMs: sidecar.fromMs, deadlineAt: sidecar.deadlineAt };
+}
+
+export function createDiagnosticReportCoordinator(args: {
+ machineDir: string;
+ buildBundle: DiagnosticBundleBuilder;
+ transport: DiagnosticTransport;
+ now: () => number;
+ sleep: (delayMs: number) => Promise<void>;
+ scheduleRetry: (delayMs: number, task: () => Promise<void>) => () => void;
+ retry: { maxAttemptsPerRound: number; baseDelayMs: number; maxDelayMs: number };
+ checkpoint?: (point: DiagnosticCoordinatorCrashPoint) => void;
+ fsOps?: FsOps;
+ logger?: { warn(message: string, fields: Record<string, unknown>): void };
+}): {
+ collect(command: DiagnosticCollectCommand): Promise<DiagnosticCoordinatorResult>;
+ recover(): Promise<void>;
+ shutdown(): Promise<void>;
+} {
+ const fsOps = args.fsOps ?? defaultFsOps();
+ const dir = join(args.machineDir, "diagnostics");
+ let stopped = false;
+ let active: { command: DiagnosticCollectCommand; promise: Promise<DiagnosticCoordinatorResult> } | null = null;
+ const retryCancels = new Set<() => void>();
+
+ const checkpoint = (point: DiagnosticCoordinatorCrashPoint): void => { args.checkpoint?.(point); };
+ const archivePath = (reportId: string): string => join(dir, `report-${reportId}.ndjson.gz`);
+ const sidecarPath = (reportId: string): string => join(dir, `report-${reportId}.json`);
+
+ const ensureDir = (): void => {
+ if (existsSync(dir)) {
+ const stat = lstatSync(dir);
+ if (!stat.isDirectory() || stat.isSymbolicLink()) throw new CoordinatorError("local_artifact_invalid");
+ if (process.platform !== "win32") chmodSync(dir, 0o700);
+ return;
+ }
+ mkdirSync(dir, { mode: 0o700 });
+ };
+
+ const safeWarn = (reportId: string): void => {
+ try { args.logger?.warn("diagnostic local artifact invalid", { reportId, code: "local_artifact_invalid" }); } catch { /* diagnostic logging is fail-safe */ }
+ };
+
+ const removeExact = (path: string): void => {
+ try {
+ const stat = lstatSync(path);
+ if (stat.isFile() && !stat.isSymbolicLink()) unlinkSync(path);
+ } catch { /* missing/unsafe artifacts are left untouched */ }
+ };
+
+ const cleanup = (reportId: string): void => {
+ removeExact(archivePath(reportId));
+ removeExact(sidecarPath(reportId));
+ };
+
+ const durableSidecar = (sidecar: Sidecar): void => {
+ const destination = sidecarPath(sidecar.reportId);
+ const bytes = Buffer.from(JSON.stringify(sidecar), "utf8");
+ let temp = "";
+ let fd: number | null = null;
+ for (let attempt = 0; attempt < 32; attempt += 1) {
+ temp = join(dir, `.${sidecar.reportId}.${sidecar.phase}.${fsOps.randomSuffix()}.tmp`);
+ try {
+ fd = fsOps.open(temp, "wx", 0o600);
+ break;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+ }
+ }
+ if (fd === null) throw new Error("unable to reserve diagnostic sidecar temp");
+ try {
+ fsOps.write(fd, bytes);
+ checkpoint(sidecar.phase === "collecting" ? "collecting_temp_written" : "ready_temp_written");
+ fsOps.fsync(fd);
+ checkpoint(sidecar.phase === "collecting" ? "collecting_temp_fsynced" : "ready_temp_fsynced");
+ } finally {
+ fsOps.close(fd);
+ }
+ fsOps.rename(temp, destination);
+ checkpoint(sidecar.phase === "collecting" ? "collecting_renamed" : "ready_renamed");
+ fsOps.fsyncDirectory(dir);
+ checkpoint(sidecar.phase === "collecting" ? "collecting_dir_fsynced" : "ready_dir_fsynced");
+ };
+
+ const committedArchive = (reportId: string): { sizeBytes: number; sha256: string } | null => {
+ const path = archivePath(reportId);
+ try {
+ const stat = lstatSync(path);
+ if (!stat.isFile() || stat.isSymbolicLink()) return null;
+ const bytes = readFileSync(path);
+ return { sizeBytes: bytes.byteLength, sha256: createHash("sha256").update(bytes).digest("hex") };
+ } catch {
+ return null;
+ }
+ };
+
+ const scheduleTask = (delayMs: number, taskBody: () => Promise<void>): void => {
+ let cancel = () => {};
+ const task = async (): Promise<void> => {
+ retryCancels.delete(cancel);
+ if (stopped) return;
+ await taskBody();
+ };
+ cancel = args.scheduleRetry(delayMs, task);
+ retryCancels.add(cancel);
+ };
+
+ const retryFailure = async (
+ reportId: string,
+ failureCode: DiagnosticReportFailureCode,
+ options: { cleanupArtifacts: boolean; deadlineAt?: number },
+ ): Promise<DiagnosticCoordinatorResult> => {
+ if (options.deadlineAt !== undefined && args.now() >= options.deadlineAt) {
+ if (options.cleanupArtifacts) cleanup(reportId);
+ return { status: "expired" };
+ }
+ for (let attempt = 0; attempt < args.retry.maxAttemptsPerRound; attempt += 1) {
+ if (stopped) throw new CoordinatorError("coordinator_shutdown");
+ const result = await args.transport.fail(reportId, failureCode);
+ if (result.kind === "terminal") {
+ if (options.cleanupArtifacts) cleanup(reportId);
+ return { status: "failed", failureCode };
+ }
+ if (attempt + 1 < args.retry.maxAttemptsPerRound) {
+ await args.sleep(Math.min(args.retry.maxDelayMs, args.retry.baseDelayMs * 2 ** attempt));
+ }
+ }
+ const delay = Math.min(args.retry.maxDelayMs, args.retry.baseDelayMs * 2 ** Math.max(0, args.retry.maxAttemptsPerRound - 1));
+ scheduleTask(delay, async () => { await retryFailure(reportId, failureCode, options); });
+ return { status: "pending" };
+ };
+
+ const invalid = async (reportId: string, deadlineAt?: number): Promise<DiagnosticCoordinatorResult> => {
+ safeWarn(reportId);
+ return retryFailure(reportId, "local_artifact_invalid", { cleanupArtifacts: true, deadlineAt });
+ };
+
+ const uploadReady = async (sidecar: ReadySidecar): Promise<DiagnosticCoordinatorResult> => {
+ if (stopped) throw new CoordinatorError("coordinator_shutdown");
+ if (args.now() >= sidecar.deadlineAt) {
+ cleanup(sidecar.reportId);
+ return { status: "expired" };
+ }
+ const actual = committedArchive(sidecar.reportId);
+ if (!actual || actual.sizeBytes !== sidecar.sizeBytes || actual.sha256 !== sidecar.sha256) {
+ return invalid(sidecar.reportId, sidecar.deadlineAt);
+ }
+ for (let attempt = 0; attempt < args.retry.maxAttemptsPerRound; attempt += 1) {
+ if (stopped) throw new CoordinatorError("coordinator_shutdown");
+ checkpoint("before_upload");
+ const result = await args.transport.upload(
+ { reportId: sidecar.reportId, sizeBytes: sidecar.sizeBytes, sha256: sidecar.sha256 },
+ createReadStream(archivePath(sidecar.reportId)),
+ );
+ checkpoint("after_upload");
+ if (result.kind === "terminal") {
+ cleanup(sidecar.reportId);
+ return { status: result.status };
+ }
+ if (attempt + 1 < args.retry.maxAttemptsPerRound) {
+ const delay = Math.min(args.retry.maxDelayMs, args.retry.baseDelayMs * 2 ** attempt);
+ await args.sleep(delay);
+ }
+ }
+ const delay = Math.min(args.retry.maxDelayMs, args.retry.baseDelayMs * 2 ** Math.max(0, args.retry.maxAttemptsPerRound - 1));
+ scheduleTask(delay, async () => { await uploadReady(sidecar); });
+ return { status: "pending" };
+ };
+
+ const promoteArchive = (collecting: CollectingSidecar): ReadySidecar | null => {
+ const actual = committedArchive(collecting.reportId);
+ if (!actual) return null;
+ const ready: ReadySidecar = { ...collecting, phase: "ready", ...actual };
+ durableSidecar(ready);
+ return ready;
+ };
+
+ const buildAndCommit = async (command: DiagnosticCollectCommand, collecting: CollectingSidecar): Promise<ReadySidecar> => {
+ const temp = join(dir, `.${command.reportId}.archive.${fsOps.randomSuffix()}.tmp`);
+ const artifact = await args.buildBundle({ command, outputPath: temp });
+ checkpoint("archive_temp_written");
+ const fd = fsOps.open(artifact.path, "r");
+ try { fsOps.fsync(fd); checkpoint("archive_temp_fsynced"); } finally { fsOps.close(fd); }
+ fsOps.rename(artifact.path, archivePath(command.reportId));
+ if (process.platform !== "win32") chmodSync(archivePath(command.reportId), 0o600);
+ checkpoint("archive_renamed");
+ fsOps.fsyncDirectory(dir);
+ checkpoint("archive_dir_fsynced");
+ const actual = committedArchive(command.reportId);
+ if (!actual || actual.sizeBytes !== artifact.sizeBytes || actual.sha256 !== artifact.sha256) throw new CoordinatorError("local_artifact_invalid");
+ const ready: ReadySidecar = { ...collecting, phase: "ready", ...actual };
+ durableSidecar(ready);
+ return ready;
+ };
+
+ const processNew = async (command: DiagnosticCollectCommand): Promise<DiagnosticCoordinatorResult> => {
+ ensureDir();
+ const collecting: CollectingSidecar = {
+ schemaVersion: 1,
+ phase: "collecting",
+ reportId: command.reportId,
+ agentId: command.agentId,
+ fromMs: command.fromMs,
+ deadlineAt: command.deadlineAt,
+ };
+ durableSidecar(collecting);
+ const ready = await buildAndCommit(command, collecting);
+ return uploadReady(ready);
+ };
+
+ const readSidecar = (reportId: string): Sidecar | null => {
+ const path = sidecarPath(reportId);
+ try {
+ const stat = lstatSync(path);
+ if (!stat.isFile() || stat.isSymbolicLink()) return null;
+ return parseSidecar(JSON.parse(readFileSync(path, "utf8")));
+ } catch {
+ return null;
+ }
+ };
+
+ const resume = async (sidecar: Sidecar): Promise<DiagnosticCoordinatorResult> => {
+ if (args.now() >= sidecar.deadlineAt) { cleanup(sidecar.reportId); return { status: "expired" }; }
+ if (sidecar.phase === "ready") return uploadReady(sidecar);
+ const promoted = promoteArchive(sidecar);
+ if (promoted) return uploadReady(promoted);
+ const ready = await buildAndCommit(commandFrom(sidecar), sidecar);
+ return uploadReady(ready);
+ };
+
+ const collect = async (command: DiagnosticCollectCommand): Promise<DiagnosticCoordinatorResult> => {
+ if (stopped) throw new CoordinatorError("coordinator_shutdown");
+ if (active) {
+ if (active.command.reportId === command.reportId) {
+ return sameCommand({ schemaVersion: 1, phase: "collecting", ...active.command }, command)
+ ? active.promise
+ : { status: "failed", failureCode: "local_artifact_invalid" };
+ }
+ return retryFailure(command.reportId, "collector_busy", { cleanupArtifacts: false, deadlineAt: command.deadlineAt });
+ }
+ ensureDir();
+ let task: Promise<DiagnosticCoordinatorResult>;
+ const persistedPath = sidecarPath(command.reportId);
+ if (existsSync(persistedPath) || existsSync(archivePath(command.reportId))) {
+ const persisted = readSidecar(command.reportId);
+ task = !persisted || !sameCommand(persisted, command) ? invalid(command.reportId, persisted?.deadlineAt) : resume(persisted);
+ } else {
+ task = processNew(command);
+ }
+ active = { command, promise: task };
+ try { return await task; } finally { if (active?.promise === task) active = null; }
+ };
+
+ const recover = async (): Promise<void> => {
+ if (stopped) throw new CoordinatorError("coordinator_shutdown");
+ ensureDir();
+ const names = readdirSync(dir);
+ const ids = new Set<string>();
+ for (const name of names) {
+ const match = /^report-(dbr_[A-Za-z0-9_-]+)(?:\.json|\.ndjson\.gz)$/.exec(name);
+ if (match?.[1]) ids.add(match[1]);
+ }
+ for (const reportId of ids) {
+ if (stopped) throw new CoordinatorError("coordinator_shutdown");
+ const hasSidecar = existsSync(sidecarPath(reportId));
+ const hasArchive = existsSync(archivePath(reportId));
+ if (!hasSidecar) { if (hasArchive) await invalid(reportId); continue; }
+ const sidecar = readSidecar(reportId);
+ if (!sidecar || sidecar.reportId !== reportId) { await invalid(reportId, sidecar?.deadlineAt); continue; }
+ await resume(sidecar);
+ }
+ };
+
+ const shutdown = async (): Promise<void> => {
+ if (stopped) return;
+ stopped = true;
+ for (const cancel of retryCancels) { try { cancel(); } catch { /* best effort */ } }
+ retryCancels.clear();
+ };
+
+ return { collect, recover, shutdown };
+}
diff --git a/src/daemon/src/diagnostics/index.ts b/src/daemon/src/diagnostics/index.ts
new file mode 100644
index 000000000..93e758922
--- /dev/null
+++ b/src/daemon/src/diagnostics/index.ts
@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./snapshotReader.js";
+export * from "./privacyPolicy.js";
+export * from "./bundle.js";
+export * from "./coordinator.js";
diff --git a/src/daemon/src/diagnostics/privacyPolicy.test.ts b/src/daemon/src/diagnostics/privacyPolicy.test.ts
new file mode 100644
index 000000000..0d3ab333c
--- /dev/null
+++ b/src/daemon/src/diagnostics/privacyPolicy.test.ts
@@ -0,0 +1,1005 @@
+import { describe, expect, it, vi } from "vitest";
+
+type FieldRule =
+ | { type: "string"; maxChars: number; values?: readonly string[]; scrub?: true; nullable?: true }
+ | { type: "number"; integer: true; min: number; max: number }
+ | { type: "boolean" }
+ | { type: "string_array"; maxItems: number; maxChars: number; values?: readonly string[] };
+
+interface DaemonLogPolicyEntry {
+ header: string;
+ message: string;
+ scope: "machine" | "target";
+ fields: Readonly<Record<string, FieldRule>>;
+}
+
+interface PrivacyPolicyModule {
+ DAEMON_LOG_DIAGNOSTIC_POLICY: readonly DaemonLogPolicyEntry[];
+ projectFsmTraceRow(value: unknown, targetAgentId: string): Record<string, unknown> | null;
+ projectDaemonLogRow(value: unknown, targetAgentId: string): Record<string, unknown> | null;
+ projectStatusRow(value: unknown, targetAgentId: string): Record<string, unknown> | null;
+ scrubDiagnosticText(value: string): string;
+}
+
+async function loadSubject(): Promise<PrivacyPolicyModule> {
+ return vi.importActual<PrivacyPolicyModule>("./privacyPolicy.js");
+}
+
+const EXPECTED_APM_PHASES = [
+ "idle",
+ "tool_wait",
+ "tool_boundary",
+ "assistant_continuation",
+ "compacting",
+ "reviewing",
+ "error",
+] as const;
+
+const EXPECTED_MANAGER_EVENTS = [
+ "register",
+ "wake",
+ "spawned",
+ "session",
+ "progress",
+ "turn_end",
+ "exit",
+ "tick",
+ "reset_session",
+ "begin_reset",
+ "rewake_after_reset",
+ "runtime_signal",
+] as const;
+
+const EXPECTED_MANAGER_EFFECTS = ["spawn", "send", "stop", "terminate_stalled", "force_exit", "gated_hold"] as const;
+const EXPECTED_AGENT_STATUSES = ["idle", "starting", "running", "stopping"] as const;
+const EXPECTED_DERIVED_ACTIVITIES = ["idle", "starting", "running", "stopping"] as const;
+const EXPECTED_TURN_OUTCOMES = ["clean", "errored"] as const;
+const EXPECTED_TURN_SPAN_EVENTS = ["turn_begin", "turn_end", "turn_abort"] as const;
+const EXPECTED_TERMINATION_CAUSES = ["runtime_error", "killed_stalled", "other"] as const;
+const EXPECTED_SPAWN_FAILURE_REASONS = ["ENOENT", "handshake_timeout", "pre_handshake_exit", "spawn_threw", "other"] as const;
+const EXPECTED_TERMINATION_SEMANTICS = ["killed_stalled", "idle_stop", "force_exit", "other"] as const;
+const EXPECTED_ABORT_CAUSES = [
+ "start_threw",
+ "start_rejected",
+ "send_threw",
+ "spawn_failure",
+ "handshake_timeout",
+ "reset",
+ "nap",
+ "model_switch",
+ "requested_stop",
+ "shutdown",
+ "physical_exit",
+ "terminate_stalled",
+ "force_exit",
+ "other",
+] as const;
+const EXPECTED_LOG_LEVELS = ["debug", "info", "warn", "error"] as const;
+const EXPECTED_EXIT_SIGNALS = [
+ "SIGABRT",
+ "SIGALRM",
+ "SIGBREAK",
+ "SIGBUS",
+ "SIGCHLD",
+ "SIGCONT",
+ "SIGFPE",
+ "SIGHUP",
+ "SIGILL",
+ "SIGINFO",
+ "SIGINT",
+ "SIGIO",
+ "SIGIOT",
+ "SIGKILL",
+ "SIGLOST",
+ "SIGPIPE",
+ "SIGPOLL",
+ "SIGPROF",
+ "SIGPWR",
+ "SIGQUIT",
+ "SIGSEGV",
+ "SIGSTKFLT",
+ "SIGSTOP",
+ "SIGSYS",
+ "SIGTERM",
+ "SIGTRAP",
+ "SIGTSTP",
+ "SIGTTIN",
+ "SIGTTOU",
+ "SIGURG",
+ "SIGUSR1",
+ "SIGUSR2",
+ "SIGVTALRM",
+ "SIGWINCH",
+ "SIGXCPU",
+ "SIGXFSZ",
+ "other",
+] as const;
+
+type ProjectionFieldRule = (
+ | { type: "string"; maxChars: number; nullable?: true }
+ | { type: "integer"; min: number; max: number; nullable?: true }
+ | { type: "boolean" }
+ | { type: "timestamp" }
+ | { type: "enum"; values: readonly string[]; maxChars?: number; nullable?: true; unknownBucket?: "other" }
+ | { type: "enum_array"; values: readonly string[]; maxItems: number; dropUnknown: true }
+) & { optional?: true };
+
+const FSM_FIELD_RULES: Readonly<Record<string, ProjectionFieldRule>> = {
+ recordKind: { type: "enum", values: ["fsm"] },
+ agentId: { type: "string", maxChars: 128 },
+ event: { type: "enum", values: EXPECTED_MANAGER_EVENTS },
+ status: { type: "enum", values: EXPECTED_AGENT_STATUSES },
+ turnActive: { type: "boolean" },
+ inbox: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER },
+ lastDeliverAt: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, nullable: true },
+ lastProgressAt: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER },
+ idleSince: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, nullable: true },
+ resetting: { type: "boolean" },
+ resettingSince: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, nullable: true },
+ stoppingSince: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, nullable: true },
+ apmPhase: { type: "enum", values: EXPECTED_APM_PHASES },
+ effects: { type: "enum_array", values: EXPECTED_MANAGER_EFFECTS, maxItems: 32, dropUnknown: true },
+ nowMs: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER },
+ timeIso: { type: "timestamp" },
+ sinceProgressMs: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER },
+ sinceDeliverMs: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, nullable: true },
+ sinceStoppingMs: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, nullable: true },
+ traceTurnId: { type: "string", maxChars: 1_024, optional: true },
+ daemonTurnOrdinal: { type: "integer", min: 1, max: Number.MAX_SAFE_INTEGER, optional: true },
+ spawnOrdinal: { type: "integer", min: 1, max: Number.MAX_SAFE_INTEGER, optional: true },
+ turnOrdinal: { type: "integer", min: 1, max: Number.MAX_SAFE_INTEGER, optional: true },
+ launchIdSnapshot: { type: "string", maxChars: 1_024, nullable: true, optional: true },
+ endReason: { type: "enum", values: ["errored"], optional: true },
+ terminationCause: { type: "enum", values: EXPECTED_TERMINATION_CAUSES, maxChars: 64, unknownBucket: "other", optional: true },
+ exitCode: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, nullable: true, optional: true },
+ exitSignal: { type: "enum", values: EXPECTED_EXIT_SIGNALS, maxChars: 64, nullable: true, unknownBucket: "other", optional: true },
+ abnormal: { type: "boolean", optional: true },
+ spawnFailureReason: { type: "enum", values: EXPECTED_SPAWN_FAILURE_REASONS, maxChars: 64, unknownBucket: "other", optional: true },
+ terminationSemantics: { type: "enum", values: EXPECTED_TERMINATION_SEMANTICS, maxChars: 64, unknownBucket: "other", optional: true },
+};
+
+const TURN_SPAN_FIELD_RULES: Readonly<Record<string, ProjectionFieldRule>> = {
+ recordKind: { type: "enum", values: ["turn_span"] },
+ agentId: { type: "string", maxChars: 128 },
+ event: { type: "enum", values: EXPECTED_TURN_SPAN_EVENTS },
+ effects: { type: "enum_array", values: EXPECTED_MANAGER_EFFECTS, maxItems: 32, dropUnknown: true },
+ nowMs: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER },
+ timeIso: { type: "timestamp" },
+ traceTurnId: { type: "string", maxChars: 1_024 },
+ daemonTurnOrdinal: { type: "integer", min: 1, max: Number.MAX_SAFE_INTEGER },
+ spawnOrdinal: { type: "integer", min: 1, max: Number.MAX_SAFE_INTEGER },
+ turnOrdinal: { type: "integer", min: 1, max: Number.MAX_SAFE_INTEGER },
+ launchIdSnapshot: { type: "string", maxChars: 1_024, nullable: true },
+ outcome: { type: "enum", values: EXPECTED_TURN_OUTCOMES, optional: true },
+ terminationCause: { type: "enum", values: EXPECTED_TERMINATION_CAUSES, maxChars: 64, unknownBucket: "other", optional: true },
+ abortCause: { type: "enum", values: EXPECTED_ABORT_CAUSES, maxChars: 64, unknownBucket: "other", optional: true },
+};
+
+const STATUS_FIELD_RULES: Readonly<Record<string, ProjectionFieldRule>> = {
+ writtenAt: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER },
+ agentId: { type: "string", maxChars: 128 },
+ status: { type: "enum", values: EXPECTED_AGENT_STATUSES },
+ derivedActivity: { type: "enum", values: EXPECTED_DERIVED_ACTIVITIES },
+ turnActive: { type: "boolean" },
+ inbox: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER },
+ sinceProgressMs: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER },
+ stoppingSince: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, nullable: true },
+};
+
+const EXPECTED_POLICY: ReadonlyArray<{
+ header: string;
+ message: string;
+ scope: "machine" | "target";
+ fields: Readonly<Record<string, FieldRule>>;
+}> = [
+ {
+ header: "@alook/daemon",
+ message: "daemon startup",
+ scope: "machine",
+ fields: {
+ machineId: { type: "string", maxChars: 128 },
+ version: { type: "string", maxChars: 128 },
+ healthyRuntimeIds: { type: "string_array", maxItems: 128, maxChars: 64 },
+ unhealthyRuntimeIds: { type: "string_array", maxItems: 128, maxChars: 64 },
+ },
+ },
+ {
+ header: "@alook/daemon",
+ message: "daemon up",
+ scope: "machine",
+ fields: {
+ proxyProtocol: { type: "string", maxChars: 16, values: ["http", "https", "unknown"] },
+ controlProtocol: { type: "string", maxChars: 16, values: ["ws", "wss", "unknown"] },
+ },
+ },
+ { header: "@alook/daemon", message: "control plane OPEN", scope: "machine", fields: {} },
+ { header: "@alook/daemon", message: "shutting down…", scope: "machine", fields: {} },
+ { header: "@alook/daemon", message: "daemon teardown failed", scope: "machine", fields: { errorClass: { type: "string", maxChars: 64 } } },
+ { header: "@alook/daemon", message: "daemon ownership release failed", scope: "machine", fields: { errorClass: { type: "string", maxChars: 64 } } },
+ { header: "@alook/daemon", message: "uncaught exception", scope: "machine", fields: { errorClass: { type: "string", maxChars: 64 } } },
+ { header: "@alook/daemon", message: "unhandled rejection", scope: "machine", fields: { errorClass: { type: "string", maxChars: 64 } } },
+ { header: "@alook/daemon", message: "daemon runner initialization failed", scope: "machine", fields: { errorClass: { type: "string", maxChars: 64 } } },
+ { header: "@alook/daemon:ws", message: "control channel open", scope: "machine", fields: { attempt: { type: "number", integer: true, min: 0, max: 1_000_000 } } },
+ {
+ header: "@alook/daemon:ws",
+ message: "resync sent",
+ scope: "machine",
+ fields: {
+ ready: { type: "number", integer: true, min: 0, max: 1_000_000 },
+ sessions: { type: "number", integer: true, min: 0, max: 1_000_000 },
+ activities: { type: "number", integer: true, min: 0, max: 1_000_000 },
+ },
+ },
+ { header: "@alook/daemon:ws", message: "control channel closed", scope: "machine", fields: { code: { type: "number", integer: true, min: 0, max: 65_535 } } },
+ {
+ header: "@alook/daemon:ws",
+ message: "reconnecting",
+ scope: "machine",
+ fields: {
+ attempt: { type: "number", integer: true, min: 0, max: 1_000_000 },
+ delayMs: { type: "number", integer: true, min: 0, max: 3_600_000 },
+ },
+ },
+ { header: "@alook/daemon:ws", message: "heartbeat pong timeout — forcing reconnect", scope: "machine", fields: {} },
+ {
+ header: "@alook/daemon:manager",
+ message: "spawning agent",
+ scope: "target",
+ fields: {
+ agentId: { type: "string", maxChars: 128 },
+ runtime: { type: "string", maxChars: 64 },
+ model: { type: "string", maxChars: 256, scrub: true },
+ },
+ },
+ {
+ header: "@alook/daemon:manager",
+ message: "spawn failed",
+ scope: "target",
+ fields: {
+ agentId: { type: "string", maxChars: 128 },
+ runtime: { type: "string", maxChars: 64 },
+ reason: { type: "string", maxChars: 64, scrub: true },
+ },
+ },
+ {
+ header: "@alook/daemon:manager",
+ message: "runtime stderr",
+ scope: "target",
+ fields: {
+ agentId: { type: "string", maxChars: 128 },
+ runtime: { type: "string", maxChars: 64 },
+ text: { type: "string", maxChars: 65_536, scrub: true },
+ },
+ },
+ {
+ header: "@alook/daemon:manager",
+ message: "agent session established",
+ scope: "target",
+ fields: {
+ agentId: { type: "string", maxChars: 128 },
+ runtime: { type: "string", maxChars: 64 },
+ sessionId: { type: "string", maxChars: 256, scrub: true },
+ },
+ },
+ {
+ header: "@alook/daemon:manager",
+ message: "agent session ended",
+ scope: "target",
+ fields: {
+ agentId: { type: "string", maxChars: 128 },
+ reason: { type: "string", maxChars: 32, values: ["turn_end", "stopped", "terminate_stalled", "exit"] },
+ sessionId: { type: "string", maxChars: 256, scrub: true },
+ },
+ },
+ {
+ header: "@alook/daemon:manager",
+ message: "steering message sent to running agent",
+ scope: "target",
+ fields: {
+ agentId: { type: "string", maxChars: 128 },
+ mode: { type: "string", maxChars: 8, values: ["busy", "idle"] },
+ },
+ },
+ {
+ header: "@alook/daemon:manager",
+ message: "gated busy message held",
+ scope: "target",
+ fields: {
+ agentId: { type: "string", maxChars: 128 },
+ reason: { type: "string", maxChars: 32, values: ["mid_turn_wake", "tool_batch_complete", "compaction_finished", "review_finished"] },
+ blockedReason: {
+ type: "string",
+ maxChars: 32,
+ nullable: true,
+ values: [
+ "idle",
+ "tool_wait",
+ "tool_boundary",
+ "assistant_continuation",
+ "compacting",
+ "reviewing",
+ "error",
+ "non_gated",
+ "missing_session",
+ "empty_inbox",
+ "tool_boundary_flush_disabled",
+ "outstanding_tool_uses",
+ ],
+ },
+ },
+ },
+ { header: "@alook/daemon:router", message: "agent:wake received", scope: "target", fields: { agentId: { type: "string", maxChars: 128 } } },
+ {
+ header: "@alook/daemon:router",
+ message: "agent:wake ack",
+ scope: "target",
+ fields: {
+ agentId: { type: "string", maxChars: 128 },
+ status: { type: "string", maxChars: 8, values: ["ok", "error"] },
+ "error.code": { type: "string", maxChars: 32, values: ["bot_unknown", "bot_enroll_failed", "bot_runtime_missing", "internal_error"] },
+ },
+ },
+ { header: "@alook/daemon:router", message: "agent:stop received", scope: "target", fields: { agentId: { type: "string", maxChars: 128 } } },
+ {
+ header: "@alook/daemon:router",
+ message: "agent:stop ack",
+ scope: "target",
+ fields: {
+ agentId: { type: "string", maxChars: 128 },
+ status: { type: "string", maxChars: 8, values: ["ok", "error"] },
+ "error.code": { type: "string", maxChars: 32, values: ["bot_unknown", "bot_enroll_failed", "bot_runtime_missing", "internal_error"] },
+ },
+ },
+];
+
+function baseFsm(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+ return {
+ recordKind: "fsm",
+ agentId: "target-agent",
+ event: "wake",
+ status: "running",
+ turnActive: true,
+ inbox: 2,
+ lastDeliverAt: 100,
+ lastProgressAt: 110,
+ idleSince: null,
+ resetting: false,
+ resettingSince: null,
+ stoppingSince: null,
+ apmPhase: "idle",
+ effects: ["spawn", "send", "unknown-effect"],
+ nowMs: 120,
+ timeIso: "1970-01-01T00:00:00.120Z",
+ sinceProgressMs: 10,
+ sinceDeliverMs: 20,
+ sinceStoppingMs: null,
+ traceTurnId: "launch_1:1",
+ daemonTurnOrdinal: 1,
+ spawnOrdinal: 2,
+ turnOrdinal: 3,
+ launchIdSnapshot: "launch_1",
+ ...overrides,
+ };
+}
+
+function baseTurnSpan(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+ return {
+ recordKind: "turn_span",
+ event: "turn_begin",
+ agentId: "target-agent",
+ effects: [],
+ nowMs: 100,
+ timeIso: "1970-01-01T00:00:00.100Z",
+ traceTurnId: "launch:1",
+ daemonTurnOrdinal: 1,
+ spawnOrdinal: 1,
+ turnOrdinal: 1,
+ launchIdSnapshot: "launch",
+ ...overrides,
+ };
+}
+
+function fsmWithField(field: string, value: unknown): Record<string, unknown> {
+ const context = ["endReason", "terminationCause"].includes(field)
+ ? { event: "turn_end", endReason: "errored", terminationCause: "runtime_error" }
+ : ["exitCode", "exitSignal", "abnormal", "spawnFailureReason", "terminationSemantics"].includes(field)
+ ? { event: "exit", exitCode: null, exitSignal: null, abnormal: false }
+ : {};
+ return baseFsm({ ...context, [field]: value });
+}
+
+function turnSpanWithField(field: string, value: unknown): Record<string, unknown> {
+ const context = ["outcome", "terminationCause"].includes(field)
+ ? { event: "turn_end", outcome: "errored", terminationCause: "runtime_error" }
+ : field === "abortCause"
+ ? { event: "turn_abort", abortCause: "reset" }
+ : {};
+ return baseTurnSpan({ ...context, [field]: value });
+}
+
+function invalidProjectionValues(rule: ProjectionFieldRule): unknown[] {
+ switch (rule.type) {
+ case "string":
+ return [1, "x".repeat(rule.maxChars + 1)];
+ case "integer":
+ return ["1", rule.min - 1, rule.max + 1, rule.min + 0.5, Number.POSITIVE_INFINITY];
+ case "boolean":
+ return ["true", 1];
+ case "timestamp":
+ return [0, "1970-01-01", "1970-01-01T00:00:00.000Z trailing", "not-a-time"];
+ case "enum":
+ return [
+ 1,
+ ...(rule.unknownBucket ? [] : ["HOSTILE_ENUM_VALUE"]),
+ ...(rule.maxChars ? ["x".repeat(rule.maxChars + 1)] : []),
+ ];
+ case "enum_array":
+ return ["not-an-array", Array.from({ length: rule.maxItems + 1 }, () => rule.values[0])];
+ }
+}
+
+function statusInput(
+ agentOverrides: Record<string, unknown> = {},
+ writtenAt: unknown = 500,
+): Record<string, unknown> {
+ return {
+ writtenAt,
+ agents: [{
+ agentId: "target-agent",
+ status: "idle",
+ derivedActivity: "idle",
+ turnActive: false,
+ inbox: 0,
+ sinceProgressMs: 20,
+ stoppingSince: null,
+ ...agentOverrides,
+ }],
+ };
+}
+
+describe("B2c privacy policy", () => {
+ it("freezes the exact daemon-log tuples and complete field rules", async () => {
+ const api = await loadSubject();
+ expect(api.DAEMON_LOG_DIAGNOSTIC_POLICY).toEqual(EXPECTED_POLICY);
+ });
+
+ it("rebuilds FSM rows from a second allowlist and never spreads hostile fields", async () => {
+ const api = await loadSubject();
+ const projected = api.projectFsmTraceRow(baseFsm({
+ prompt: "PROMPT_LEAK_SENTINEL",
+ text: "SEND_LEAK_SENTINEL",
+ response: "RESPONSE_LEAK_SENTINEL",
+ thinking: "THINKING_LEAK_SENTINEL",
+ toolInput: "TOOL_LEAK_SENTINEL",
+ errorDetail: "ERROR_LEAK_SENTINEL",
+ recentEvents: ["RECENT_LEAK_SENTINEL"],
+ unknown: { nested: "UNKNOWN_LEAK_SENTINEL" },
+ }), "target-agent");
+
+ expect(projected).toEqual({
+ recordType: "fsm",
+ recordKind: "fsm",
+ agentId: "target-agent",
+ event: "wake",
+ status: "running",
+ turnActive: true,
+ inbox: 2,
+ lastDeliverAt: 100,
+ lastProgressAt: 110,
+ idleSince: null,
+ resetting: false,
+ resettingSince: null,
+ stoppingSince: null,
+ apmPhase: "idle",
+ effects: ["spawn", "send"],
+ nowMs: 120,
+ timeIso: "1970-01-01T00:00:00.120Z",
+ sinceProgressMs: 10,
+ sinceDeliverMs: 20,
+ sinceStoppingMs: null,
+ traceTurnId: "launch_1:1",
+ daemonTurnOrdinal: 1,
+ spawnOrdinal: 2,
+ turnOrdinal: 3,
+ launchIdSnapshot: "launch_1",
+ });
+ expect(JSON.stringify(projected)).not.toMatch(/PROMPT_LEAK|SEND_LEAK|RESPONSE_LEAK|THINKING_LEAK|TOOL_LEAK|ERROR_LEAK|RECENT_LEAK|UNKNOWN_LEAK/);
+
+ for (const apmPhase of EXPECTED_APM_PHASES) {
+ expect(api.projectFsmTraceRow(baseFsm({ apmPhase }), "target-agent"), apmPhase).toMatchObject({ apmPhase });
+ }
+ for (const event of EXPECTED_MANAGER_EVENTS) {
+ expect(api.projectFsmTraceRow(baseFsm({ event }), "target-agent"), event).toMatchObject({ event });
+ }
+ for (const effect of EXPECTED_MANAGER_EFFECTS) {
+ expect(api.projectFsmTraceRow(baseFsm({ effects: [effect] }), "target-agent"), effect).toMatchObject({ effects: [effect] });
+ }
+ for (const status of EXPECTED_AGENT_STATUSES) {
+ expect(api.projectFsmTraceRow(baseFsm({ status }), "target-agent"), status).toMatchObject({ status });
+ }
+ expect(api.projectFsmTraceRow(baseFsm({ effects: ["HOSTILE_EFFECT"] }), "target-agent")).toMatchObject({ effects: [] });
+
+ const minimalFsm = baseFsm({ event: "register", effects: [] });
+ for (const field of ["traceTurnId", "daemonTurnOrdinal", "spawnOrdinal", "turnOrdinal", "launchIdSnapshot"]) {
+ delete minimalFsm[field];
+ }
+ const projectedMinimal = api.projectFsmTraceRow(minimalFsm, "target-agent");
+ expect(projectedMinimal).toMatchObject({ recordType: "fsm", recordKind: "fsm", event: "register", effects: [] });
+ for (const field of ["traceTurnId", "daemonTurnOrdinal", "spawnOrdinal", "turnOrdinal", "launchIdSnapshot"]) {
+ expect(projectedMinimal).not.toHaveProperty(field);
+ }
+
+ const ordinaryExit = api.projectFsmTraceRow(baseFsm({ event: "exit", exitCode: 0, exitSignal: null, abnormal: false }), "target-agent");
+ expect(ordinaryExit).toMatchObject({ event: "exit", exitCode: 0, exitSignal: null, abnormal: false });
+ expect(ordinaryExit).not.toHaveProperty("spawnFailureReason");
+ expect(ordinaryExit).not.toHaveProperty("terminationSemantics");
+ });
+
+ it("freezes FSM/span outcome and cause enums plus bounded physical-exit metadata", async () => {
+ const api = await loadSubject();
+ const begin = api.projectFsmTraceRow(baseTurnSpan(), "target-agent");
+ expect(begin).toMatchObject({ recordType: "fsm", recordKind: "turn_span", event: "turn_begin" });
+
+ for (const outcome of EXPECTED_TURN_OUTCOMES) {
+ expect(api.projectFsmTraceRow(baseTurnSpan({
+ event: "turn_end",
+ outcome,
+ ...(outcome === "errored" ? { terminationCause: "runtime_error" } : {}),
+ }), "target-agent"), outcome).toMatchObject({ event: "turn_end", outcome });
+ }
+ for (const terminationCause of EXPECTED_TERMINATION_CAUSES) {
+ expect(api.projectFsmTraceRow(baseTurnSpan({ event: "turn_end", outcome: "errored", terminationCause }), "target-agent"), terminationCause)
+ .toMatchObject({ event: "turn_end", outcome: "errored", terminationCause });
+ expect(api.projectFsmTraceRow(baseFsm({ event: "turn_end", endReason: "errored", terminationCause }), "target-agent"), terminationCause)
+ .toMatchObject({ event: "turn_end", endReason: "errored", terminationCause });
+ }
+ for (const abortCause of EXPECTED_ABORT_CAUSES) {
+ expect(api.projectFsmTraceRow(baseTurnSpan({ event: "turn_abort", abortCause }), "target-agent"), abortCause)
+ .toMatchObject({ event: "turn_abort", abortCause });
+ }
+ for (const spawnFailureReason of EXPECTED_SPAWN_FAILURE_REASONS) {
+ expect(api.projectFsmTraceRow(baseFsm({ event: "exit", spawnFailureReason }), "target-agent"), spawnFailureReason)
+ .toMatchObject({ event: "exit", spawnFailureReason });
+ }
+ for (const terminationSemantics of EXPECTED_TERMINATION_SEMANTICS) {
+ expect(api.projectFsmTraceRow(baseFsm({ event: "exit", terminationSemantics }), "target-agent"), terminationSemantics)
+ .toMatchObject({ event: "exit", terminationSemantics });
+ }
+ for (const exitCode of [null, 0, 137] as const) {
+ expect(api.projectFsmTraceRow(baseFsm({ event: "exit", exitCode }), "target-agent"), `exitCode=${String(exitCode)}`)
+ .toMatchObject({ event: "exit", exitCode });
+ }
+ for (const exitSignal of [null, ...EXPECTED_EXIT_SIGNALS] as const) {
+ expect(api.projectFsmTraceRow(baseFsm({ event: "exit", exitSignal }), "target-agent"), `exitSignal=${String(exitSignal)}`)
+ .toMatchObject({ event: "exit", exitSignal });
+ }
+ for (const abnormal of [false, true] as const) {
+ expect(api.projectFsmTraceRow(baseFsm({ event: "exit", abnormal }), "target-agent"), `abnormal=${String(abnormal)}`)
+ .toMatchObject({ event: "exit", abnormal });
+ }
+
+ expect(api.projectFsmTraceRow(baseTurnSpan({
+ event: "turn_end",
+ outcome: "errored",
+ terminationCause: "HOSTILE_CAUSE_TEXT",
+ errorDetail: "HOSTILE_ERROR_TEXT",
+ }), "target-agent")).toMatchObject({ terminationCause: "other" });
+ expect(api.projectFsmTraceRow(baseTurnSpan({ event: "turn_abort", abortCause: "HOSTILE_ABORT_TEXT" }), "target-agent"))
+ .toMatchObject({ abortCause: "other" });
+ expect(api.projectFsmTraceRow(baseFsm({ event: "exit", spawnFailureReason: "HOSTILE_SPAWN_REASON" }), "target-agent"))
+ .toMatchObject({ spawnFailureReason: "other" });
+ expect(api.projectFsmTraceRow(baseFsm({ event: "exit", terminationSemantics: "HOSTILE_EXIT_SEMANTIC" }), "target-agent"))
+ .toMatchObject({ terminationSemantics: "other" });
+ expect(api.projectFsmTraceRow(baseFsm({ event: "exit", exitSignal: "HOSTILE_SIGNAL" }), "target-agent"))
+ .toMatchObject({ exitSignal: "other" });
+ expect(JSON.stringify([
+ api.projectFsmTraceRow(baseTurnSpan({ event: "turn_end", outcome: "errored", terminationCause: "HOSTILE_CAUSE_TEXT" }), "target-agent"),
+ api.projectFsmTraceRow(baseTurnSpan({ event: "turn_abort", abortCause: "HOSTILE_ABORT_TEXT" }), "target-agent"),
+ api.projectFsmTraceRow(baseFsm({ event: "exit", spawnFailureReason: "HOSTILE_SPAWN_REASON", terminationSemantics: "HOSTILE_EXIT_SEMANTIC" }), "target-agent"),
+ ])).not.toContain("HOSTILE");
+
+ for (const [field, rule] of Object.entries(TURN_SPAN_FIELD_RULES)) {
+ if (rule.type === "enum_array") {
+ for (const invalid of invalidProjectionValues(rule)) {
+ expect(api.projectFsmTraceRow(turnSpanWithField(field, invalid), "target-agent"), `span.${field}=${JSON.stringify(invalid)}`)
+ .toBeNull();
+ }
+ expect(api.projectFsmTraceRow(turnSpanWithField(field, ["HOSTILE_EFFECT"]), "target-agent"))
+ .toMatchObject({ [field]: [] });
+ continue;
+ }
+ for (const invalid of invalidProjectionValues(rule)) {
+ expect(api.projectFsmTraceRow(turnSpanWithField(field, invalid), "target-agent"), `span.${field}=${JSON.stringify(invalid)}`)
+ .toBeNull();
+ }
+ if (rule.type === "integer") {
+ expect(api.projectFsmTraceRow(turnSpanWithField(field, rule.min), "target-agent"), `span.${field}=min`)
+ .toMatchObject({ [field]: rule.min });
+ }
+ if (rule.type === "string" && field !== "agentId") {
+ const bounded = "x".repeat(rule.maxChars);
+ expect(api.projectFsmTraceRow(turnSpanWithField(field, bounded), "target-agent"), `span.${field}=maxChars`)
+ .toMatchObject({ [field]: bounded });
+ }
+ if ("nullable" in rule && rule.nullable) {
+ expect(api.projectFsmTraceRow(turnSpanWithField(field, null), "target-agent"), `span.${field}=null`)
+ .toMatchObject({ [field]: null });
+ }
+ if (rule.type === "enum" && rule.unknownBucket) {
+ expect(api.projectFsmTraceRow(turnSpanWithField(field, "HOSTILE_ENUM_VALUE"), "target-agent"), `span.${field}=bucket`)
+ .toMatchObject({ [field]: "other" });
+ }
+ }
+ });
+
+ it("enforces the test-owned FSM field-rule table and fails closed on every invalid shape", async () => {
+ const api = await loadSubject();
+ expect(api.projectFsmTraceRow(baseFsm({ agentId: "second-agent" }), "target-agent")).toBeNull();
+ expect(api.projectFsmTraceRow(baseFsm({ recordKind: "unknown" }), "target-agent")).toBeNull();
+ expect(api.projectFsmTraceRow(baseFsm({ event: "HOSTILE_EVENT" }), "target-agent")).toBeNull();
+ expect(api.projectFsmTraceRow(baseFsm({ status: "HOSTILE_STATUS" }), "target-agent")).toBeNull();
+ expect(api.projectFsmTraceRow(baseFsm({ apmPhase: "working" }), "target-agent")).toBeNull();
+ expect(api.projectFsmTraceRow(baseFsm({ apmPhase: "HOSTILE_APM_PHASE" }), "target-agent")).toBeNull();
+ expect(api.projectFsmTraceRow(baseFsm({ nowMs: Number.POSITIVE_INFINITY }), "target-agent")).toBeNull();
+ expect(api.projectFsmTraceRow(baseFsm({ traceTurnId: "x".repeat(1025) }), "target-agent")).toBeNull();
+ const boundedAgentId = "a".repeat(128);
+ expect(api.projectFsmTraceRow(baseFsm({ agentId: boundedAgentId }), boundedAgentId)).toMatchObject({ agentId: boundedAgentId });
+ const oversizedAgentId = "a".repeat(129);
+ expect(api.projectFsmTraceRow(baseFsm({ agentId: oversizedAgentId }), oversizedAgentId)).toBeNull();
+
+ for (const [field, rule] of Object.entries(FSM_FIELD_RULES)) {
+ if (rule.type === "enum_array") {
+ for (const invalid of invalidProjectionValues(rule)) {
+ expect(api.projectFsmTraceRow(fsmWithField(field, invalid), "target-agent"), `${field}=${JSON.stringify(invalid)}`).toBeNull();
+ }
+ expect(api.projectFsmTraceRow(fsmWithField(field, ["HOSTILE_EFFECT"]), "target-agent"), `${field}=unknown`)
+ .toMatchObject({ [field]: [] });
+ continue;
+ }
+ for (const invalid of invalidProjectionValues(rule)) {
+ expect(api.projectFsmTraceRow(fsmWithField(field, invalid), "target-agent"), `${field}=${JSON.stringify(invalid)}`).toBeNull();
+ }
+ if (rule.type === "integer") {
+ expect(api.projectFsmTraceRow(fsmWithField(field, rule.min), "target-agent"), `${field}=min`)
+ .toMatchObject({ [field]: rule.min });
+ }
+ if (rule.type === "string" && field !== "agentId") {
+ const bounded = "x".repeat(rule.maxChars);
+ expect(api.projectFsmTraceRow(fsmWithField(field, bounded), "target-agent"), `${field}=maxChars`)
+ .toMatchObject({ [field]: bounded });
+ }
+ if (rule.type === "boolean") {
+ for (const value of [false, true]) {
+ expect(api.projectFsmTraceRow(fsmWithField(field, value), "target-agent"), `${field}=${String(value)}`)
+ .toMatchObject({ [field]: value });
+ }
+ }
+ if ("nullable" in rule && rule.nullable) {
+ expect(api.projectFsmTraceRow(fsmWithField(field, null), "target-agent"), `${field}=null`)
+ .toMatchObject({ [field]: null });
+ }
+ if (rule.type === "enum" && rule.unknownBucket) {
+ expect(api.projectFsmTraceRow(fsmWithField(field, "HOSTILE_ENUM_VALUE"), "target-agent"), `${field}=bucket`)
+ .toMatchObject({ [field]: "other" });
+ }
+ if (rule.optional) {
+ const withoutOptional = fsmWithField(field, rule.type === "enum" ? rule.values[0] : undefined);
+ delete withoutOptional[field];
+ expect(api.projectFsmTraceRow(withoutOptional, "target-agent"), `${field}=omitted`).not.toBeNull();
+ }
+ }
+
+ expect(api.projectFsmTraceRow(baseTurnSpan({ event: "turn_end", outcome: "HOSTILE_OUTCOME" }), "target-agent")).toBeNull();
+ expect(api.projectFsmTraceRow(baseTurnSpan({ event: "turn_end", outcome: "errored", terminationCause: 1 }), "target-agent")).toBeNull();
+ expect(api.projectFsmTraceRow(baseTurnSpan({ event: "turn_abort", abortCause: 1 }), "target-agent")).toBeNull();
+ });
+
+ it("requires an exact daemon-log tuple before agentId can grant admission", async () => {
+ const api = await loadSubject();
+ const unknown = {
+ time: "2026-08-12T12:00:00.000Z",
+ header: "@alook/daemon:manager",
+ level: "warn",
+ message: "user controlled event",
+ fields: { agentId: "target-agent", text: "UNKNOWN_TUPLE_LEAK" },
+ };
+ expect(api.projectDaemonLogRow(unknown, "target-agent")).toBeNull();
+ expect(api.projectDaemonLogRow({ ...unknown, header: "@alook/daemon:evil", message: "runtime stderr" }, "target-agent")).toBeNull();
+ });
+
+ it("drops other-bot stderr even when its text forges a target agent field", async () => {
+ const api = await loadSubject();
+ const row = {
+ time: "2026-08-12T12:00:00.000Z",
+ header: "@alook/daemon:manager",
+ level: "warn",
+ message: "runtime stderr",
+ fields: {
+ agentId: "second-agent",
+ runtime: "claude",
+ text: "SECOND_BOT_SECRET\n{\"agentId\":\"target-agent\"} cmk_secret Bearer token /Users/private",
+ },
+ };
+ expect(api.projectDaemonLogRow(row, "target-agent")).toBeNull();
+ });
+
+ it("keeps disclosed target stderr but scrubs credentials, authorization, vouchers, and absolute paths", async () => {
+ const api = await loadSubject();
+ const row = {
+ time: "2026-08-12T12:00:00.000Z",
+ header: "@alook/daemon:manager",
+ level: "warn",
+ message: "runtime stderr",
+ fields: {
+ agentId: "target-agent",
+ runtime: "claude",
+ text: "provider failed cmk_ABC123 cmt_XYZ crk_RECONNECT Authorization: Bearer topsecret voucher=/tmp/voucher-token /Users/alice/project /home/bob/work C:\\Users\\alice\\secret \\\\server\\share\\private",
+ prompt: "PROMPT_EXTRA_LEAK",
+ authorization: "AUTH_EXTRA_LEAK",
+ otherBotId: "second-agent",
+ },
+ };
+ const projected = api.projectDaemonLogRow(row, "target-agent");
+ const encoded = JSON.stringify(projected);
+
+ expect(projected).toMatchObject({
+ recordType: "daemon_log",
+ header: "@alook/daemon:manager",
+ message: "runtime stderr",
+ fields: { agentId: "target-agent", runtime: "claude" },
+ });
+ expect(encoded).toContain("provider failed");
+ expect(encoded).not.toMatch(/cmk_|cmt_|crk_|topsecret|voucher-token|\/Users\/alice|\/home\/bob|C:\\\\Users\\\\alice|server\\\\share|PROMPT_EXTRA|AUTH_EXTRA|second-agent/);
+ });
+
+ it("drops every non-allowlisted field from every admitted daemon tuple", async () => {
+ const api = await loadSubject();
+ for (const entry of EXPECTED_POLICY) {
+ const fields: Record<string, unknown> = Object.fromEntries(Object.entries(entry.fields).map(([field, rule]) => {
+ if (field === "agentId") return [field, "target-agent"];
+ if (rule.type === "number") return [field, rule.min];
+ if (rule.type === "boolean") return [field, true];
+ if (rule.type === "string_array") return [field, [rule.values?.[0] ?? "safe"]];
+ return [field, rule.values?.[0] ?? "safe"];
+ }));
+ Object.assign(fields, {
+ prompt: "PROMPT_EXTRA_LEAK",
+ authorization: "AUTH_EXTRA_LEAK",
+ recentEvents: ["RECENT_EXTRA_LEAK"],
+ arbitrary: "ARBITRARY_EXTRA_LEAK",
+ });
+ const projected = api.projectDaemonLogRow({
+ time: "2026-08-12T12:00:00.000Z",
+ header: entry.header,
+ level: "info",
+ message: entry.message,
+ fields,
+ }, "target-agent");
+ expect(projected, `${entry.header} ${entry.message}`).not.toBeNull();
+ const encoded = JSON.stringify(projected);
+ expect(encoded).not.toMatch(/PROMPT_EXTRA|AUTH_EXTRA|RECENT_EXTRA|ARBITRARY_EXTRA/);
+ expect(Object.keys((projected?.fields ?? {}) as object).sort()).toEqual(Object.keys(entry.fields).sort());
+ }
+ });
+
+ it("fails closed for every daemon-log field-rule type, enum, and length violation", async () => {
+ const api = await loadSubject();
+ const validValue = (key: string, rule: FieldRule): unknown => {
+ if (key === "agentId") return "target-agent";
+ if (rule.type === "number") return rule.min;
+ if (rule.type === "boolean") return true;
+ if (rule.type === "string_array") return [rule.values?.[0] ?? "safe"];
+ return rule.values?.[0] ?? "safe";
+ };
+ const invalidValues = (rule: FieldRule): unknown[] => {
+ switch (rule.type) {
+ case "number":
+ return ["1", rule.min - 1, rule.max + 1, rule.min + 0.5, Number.POSITIVE_INFINITY, Number.MAX_SAFE_INTEGER + 1];
+ case "boolean":
+ return ["true", 1];
+ case "string":
+ return [
+ 1,
+ "x".repeat(rule.maxChars + 1),
+ ...(rule.values ? ["NOT_AN_ALLOWLISTED_ENUM"] : []),
+ ];
+ case "string_array":
+ return [
+ "not-an-array",
+ Array.from({ length: rule.maxItems + 1 }, () => rule.values?.[0] ?? "safe"),
+ ["x".repeat(rule.maxChars + 1)],
+ ...(rule.values ? [["NOT_AN_ALLOWLISTED_ENUM"]] : []),
+ ];
+ }
+ };
+
+ for (const entry of EXPECTED_POLICY) {
+ const validFields = Object.fromEntries(Object.entries(entry.fields).map(([key, rule]) => [key, validValue(key, rule)]));
+ for (const [key, rule] of Object.entries(entry.fields)) {
+ for (const invalid of invalidValues(rule)) {
+ const row = {
+ time: "2026-08-12T12:00:00.000Z",
+ header: entry.header,
+ level: "info",
+ message: entry.message,
+ fields: { ...validFields, [key]: invalid },
+ };
+ expect(
+ api.projectDaemonLogRow(row, "target-agent"),
+ `${entry.header} ${entry.message} ${key}=${JSON.stringify(invalid)}`,
+ ).toBeNull();
+ }
+ }
+ }
+ });
+
+ it("accepts only canonical timestamps and fixed log levels", async () => {
+ const api = await loadSubject();
+ const valid = {
+ time: "2026-08-12T12:00:00.000Z",
+ header: "@alook/daemon:manager",
+ level: "warn",
+ message: "runtime stderr",
+ fields: { agentId: "target-agent", runtime: "claude", text: "safe" },
+ };
+ for (const level of EXPECTED_LOG_LEVELS) {
+ expect(api.projectDaemonLogRow({ ...valid, level }, "target-agent"), level).toMatchObject({
+ time: valid.time,
+ level,
+ });
+ }
+ expect(api.projectDaemonLogRow({
+ time: valid.time,
+ header: "@alook/daemon:router",
+ level: "info",
+ message: "agent:wake ack",
+ fields: { agentId: "target-agent", status: "ok" },
+ }, "target-agent")).toMatchObject({ fields: { agentId: "target-agent", status: "ok" } });
+ expect(api.projectDaemonLogRow({
+ time: valid.time,
+ header: "@alook/daemon:ws",
+ level: "warn",
+ message: "control channel closed",
+ fields: {},
+ }, "target-agent")).toMatchObject({ fields: {} });
+ for (const time of [
+ 0,
+ "2026-08-12",
+ "2026-08-12T12:00:00Z trailing",
+ "not-a-time",
+ "99999-01-01T00:00:00.000Z",
+ ]) {
+ expect(api.projectDaemonLogRow({ ...valid, time }, "target-agent"), `time=${String(time)}`).toBeNull();
+ }
+ for (const level of ["trace", "fatal", "INFO", 1, null]) {
+ expect(api.projectDaemonLogRow({ ...valid, level }, "target-agent"), `level=${String(level)}`).toBeNull();
+ }
+ });
+
+ it("keeps target mismatch as an independent fail-closed gate", async () => {
+ const api = await loadSubject();
+ expect(api.projectDaemonLogRow({
+ time: "2026-08-12T12:00:00.000Z",
+ header: "@alook/daemon:manager",
+ level: "warn",
+ message: "runtime stderr",
+ fields: { agentId: "second-agent", runtime: "claude", text: "otherwise-valid" },
+ }, "target-agent")).toBeNull();
+ });
+
+ it("projects only the target status with an exact bounded field set", async () => {
+ const api = await loadSubject();
+ const projected = api.projectStatusRow({
+ writtenAt: 500,
+ agents: [
+ {
+ agentId: "second-agent",
+ status: "running",
+ derivedActivity: "running",
+ turnActive: true,
+ inbox: 99,
+ sinceProgressMs: 1,
+ stoppingSince: null,
+ secret: "SECOND_STATUS_SECRET",
+ },
+ {
+ agentId: "target-agent",
+ status: "idle",
+ derivedActivity: "idle",
+ turnActive: false,
+ inbox: 0,
+ sinceProgressMs: 20,
+ stoppingSince: null,
+ prompt: "TARGET_STATUS_EXTRA",
+ },
+ ],
+ hostname: "HOSTNAME_LEAK",
+ env: { TOKEN: "ENV_LEAK" },
+ workdir: "/Users/alice/project",
+ }, "target-agent");
+
+ expect(projected).toEqual({
+ recordType: "status",
+ timeMs: 500,
+ agentId: "target-agent",
+ status: "idle",
+ derivedActivity: "idle",
+ turnActive: false,
+ inbox: 0,
+ sinceProgressMs: 20,
+ stoppingSince: null,
+ });
+ expect(JSON.stringify(projected)).not.toMatch(/second-agent|SECOND_STATUS|TARGET_STATUS|HOSTNAME|ENV_LEAK|\/Users\/alice/);
+
+ for (const status of EXPECTED_AGENT_STATUSES) {
+ expect(api.projectStatusRow(statusInput({ status }), "target-agent"), status).toMatchObject({ status });
+ }
+ for (const derivedActivity of EXPECTED_DERIVED_ACTIVITIES) {
+ expect(api.projectStatusRow(statusInput({ derivedActivity }), "target-agent"), derivedActivity)
+ .toMatchObject({ derivedActivity });
+ }
+ });
+
+ it("enforces the test-owned status field-rule table", async () => {
+ const api = await loadSubject();
+ const boundedAgentId = "a".repeat(128);
+ expect(api.projectStatusRow({
+ writtenAt: 500,
+ agents: [{
+ agentId: boundedAgentId,
+ status: "idle",
+ derivedActivity: "idle",
+ turnActive: false,
+ inbox: 0,
+ sinceProgressMs: 20,
+ stoppingSince: null,
+ }],
+ }, boundedAgentId)).toMatchObject({ agentId: boundedAgentId });
+ const oversizedAgentId = "a".repeat(129);
+ expect(api.projectStatusRow({
+ writtenAt: 500,
+ agents: [{
+ agentId: oversizedAgentId,
+ status: "idle",
+ derivedActivity: "idle",
+ turnActive: false,
+ inbox: 0,
+ sinceProgressMs: 20,
+ stoppingSince: null,
+ }],
+ }, oversizedAgentId)).toBeNull();
+
+ for (const [field, rule] of Object.entries(STATUS_FIELD_RULES)) {
+ for (const invalid of invalidProjectionValues(rule)) {
+ const input = field === "writtenAt" ? statusInput({}, invalid) : statusInput({ [field]: invalid });
+ expect(api.projectStatusRow(input, "target-agent"), `${field}=${JSON.stringify(invalid)}`).toBeNull();
+ }
+ if (rule.type === "integer") {
+ const input = field === "writtenAt" ? statusInput({}, rule.min) : statusInput({ [field]: rule.min });
+ expect(api.projectStatusRow(input, "target-agent"), `${field}=min`).toMatchObject({
+ [field === "writtenAt" ? "timeMs" : field]: rule.min,
+ });
+ }
+ if (rule.type === "boolean") {
+ for (const value of [false, true]) {
+ expect(api.projectStatusRow(statusInput({ [field]: value }), "target-agent"), `${field}=${String(value)}`)
+ .toMatchObject({ [field]: value });
+ }
+ }
+ if ("nullable" in rule && rule.nullable) {
+ expect(api.projectStatusRow(statusInput({ [field]: null }), "target-agent"), `${field}=null`)
+ .toMatchObject({ [field]: null });
+ }
+ }
+ });
+
+ it("scrubber is deterministic, bounded, and never emits the original secret/path", async () => {
+ const api = await loadSubject();
+ const hostile = `${"x".repeat(70_000)} cmk_TOP Authorization: Bearer SECRET /Users/alice/private C:\\Users\\alice\\secret \\\\server\\share\\private`;
+ const first = api.scrubDiagnosticText(hostile);
+ const second = api.scrubDiagnosticText(hostile);
+ expect(first).toBe(second);
+ expect(Buffer.byteLength(first, "utf8")).toBeLessThanOrEqual(64 * 1024);
+ expect(first).not.toMatch(/cmk_TOP|SECRET|\/Users\/alice|C:\\Users\\alice|\\\\server\\share/);
+ });
+});
diff --git a/src/daemon/src/diagnostics/privacyPolicy.ts b/src/daemon/src/diagnostics/privacyPolicy.ts
new file mode 100644
index 000000000..c8d436d6b
--- /dev/null
+++ b/src/daemon/src/diagnostics/privacyPolicy.ts
@@ -0,0 +1,331 @@
+import type { LogLevel } from "../logger.js";
+
+type FieldRule =
+ | { type: "string"; maxChars: number; values?: readonly string[]; scrub?: true; nullable?: true }
+ | { type: "number"; integer: true; min: number; max: number }
+ | { type: "boolean" }
+ | { type: "string_array"; maxItems: number; maxChars: number; values?: readonly string[] };
+
+export interface DaemonLogPolicyEntry {
+ header: string;
+ message: string;
+ scope: "machine" | "target";
+ fields: Readonly<Record<string, FieldRule>>;
+}
+
+const string = (maxChars: number, options: Omit<Extract<FieldRule, { type: "string" }>, "type" | "maxChars"> = {}): FieldRule =>
+ ({ type: "string", maxChars, ...options });
+const integer = (min: number, max: number): FieldRule => ({ type: "number", integer: true, min, max });
+const stringArray = (maxItems: number, maxChars: number): FieldRule => ({ type: "string_array", maxItems, maxChars });
+const AGENT = string(128);
+const RUNTIME = string(64);
+const ACK_CODES = ["bot_unknown", "bot_enroll_failed", "bot_runtime_missing", "internal_error"] as const;
+
+export const DAEMON_LOG_DIAGNOSTIC_POLICY: readonly DaemonLogPolicyEntry[] = [
+ { header: "@alook/daemon", message: "daemon startup", scope: "machine", fields: {
+ machineId: string(128), version: string(128), healthyRuntimeIds: stringArray(128, 64), unhealthyRuntimeIds: stringArray(128, 64),
+ } },
+ { header: "@alook/daemon", message: "daemon up", scope: "machine", fields: {
+ proxyProtocol: string(16, { values: ["http", "https", "unknown"] }),
+ controlProtocol: string(16, { values: ["ws", "wss", "unknown"] }),
+ } },
+ { header: "@alook/daemon", message: "control plane OPEN", scope: "machine", fields: {} },
+ { header: "@alook/daemon", message: "shutting down…", scope: "machine", fields: {} },
+ { header: "@alook/daemon", message: "daemon teardown failed", scope: "machine", fields: { errorClass: string(64) } },
+ { header: "@alook/daemon", message: "daemon ownership release failed", scope: "machine", fields: { errorClass: string(64) } },
+ { header: "@alook/daemon", message: "uncaught exception", scope: "machine", fields: { errorClass: string(64) } },
+ { header: "@alook/daemon", message: "unhandled rejection", scope: "machine", fields: { errorClass: string(64) } },
+ { header: "@alook/daemon", message: "daemon runner initialization failed", scope: "machine", fields: { errorClass: string(64) } },
+ { header: "@alook/daemon:ws", message: "control channel open", scope: "machine", fields: { attempt: integer(0, 1_000_000) } },
+ { header: "@alook/daemon:ws", message: "resync sent", scope: "machine", fields: {
+ ready: integer(0, 1_000_000), sessions: integer(0, 1_000_000), activities: integer(0, 1_000_000),
+ } },
+ { header: "@alook/daemon:ws", message: "control channel closed", scope: "machine", fields: { code: integer(0, 65_535) } },
+ { header: "@alook/daemon:ws", message: "reconnecting", scope: "machine", fields: {
+ attempt: integer(0, 1_000_000), delayMs: integer(0, 3_600_000),
+ } },
+ { header: "@alook/daemon:ws", message: "heartbeat pong timeout — forcing reconnect", scope: "machine", fields: {} },
+ { header: "@alook/daemon:manager", message: "spawning agent", scope: "target", fields: {
+ agentId: AGENT, runtime: RUNTIME, model: string(256, { scrub: true }),
+ } },
+ { header: "@alook/daemon:manager", message: "spawn failed", scope: "target", fields: {
+ agentId: AGENT, runtime: RUNTIME, reason: string(64, { scrub: true }),
+ } },
+ { header: "@alook/daemon:manager", message: "runtime stderr", scope: "target", fields: {
+ agentId: AGENT, runtime: RUNTIME, text: string(65_536, { scrub: true }),
+ } },
+ { header: "@alook/daemon:manager", message: "agent session established", scope: "target", fields: {
+ agentId: AGENT, runtime: RUNTIME, sessionId: string(256, { scrub: true }),
+ } },
+ { header: "@alook/daemon:manager", message: "agent session ended", scope: "target", fields: {
+ agentId: AGENT,
+ reason: string(32, { values: ["turn_end", "stopped", "terminate_stalled", "exit"] }),
+ sessionId: string(256, { scrub: true }),
+ } },
+ { header: "@alook/daemon:manager", message: "steering message sent to running agent", scope: "target", fields: {
+ agentId: AGENT, mode: string(8, { values: ["busy", "idle"] }),
+ } },
+ { header: "@alook/daemon:manager", message: "gated busy message held", scope: "target", fields: {
+ agentId: AGENT,
+ reason: string(32, { values: ["mid_turn_wake", "tool_batch_complete", "compaction_finished", "review_finished"] }),
+ blockedReason: string(32, { nullable: true, values: [
+ "idle", "tool_wait", "tool_boundary", "assistant_continuation", "compacting", "reviewing", "error",
+ "non_gated", "missing_session", "empty_inbox", "tool_boundary_flush_disabled", "outstanding_tool_uses",
+ ] }),
+ } },
+ { header: "@alook/daemon:router", message: "agent:wake received", scope: "target", fields: { agentId: AGENT } },
+ { header: "@alook/daemon:router", message: "agent:wake ack", scope: "target", fields: {
+ agentId: AGENT, status: string(8, { values: ["ok", "error"] }), "error.code": string(32, { values: ACK_CODES }),
+ } },
+ { header: "@alook/daemon:router", message: "agent:stop received", scope: "target", fields: { agentId: AGENT } },
+ { header: "@alook/daemon:router", message: "agent:stop ack", scope: "target", fields: {
+ agentId: AGENT, status: string(8, { values: ["ok", "error"] }), "error.code": string(32, { values: ACK_CODES }),
+ } },
+];
+
+function object(value: unknown): Record<string, unknown> | null {
+ return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function canonicalTime(value: unknown): value is string {
+ if (typeof value !== "string") return false;
+ const time = Date.parse(value);
+ return Number.isFinite(time) && new Date(time).toISOString() === value;
+}
+
+function safeInteger(value: unknown, min = 0): value is number {
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= min;
+}
+
+function boundedString(value: unknown, maxChars: number): value is string {
+ return typeof value === "string" && value.length <= maxChars;
+}
+
+export function scrubDiagnosticText(value: string): string {
+ let scrubbed = value
+ .replace(/\b(?:cmk|cmt|crk)_[A-Za-z0-9_-]+\b/g, "[redacted-token]")
+ .replace(/Authorization\s*:\s*Bearer\s+[^\s]+/gi, "Authorization: Bearer [redacted]")
+ .replace(/\bvoucher\s*=\s*[^\s]+/gi, "voucher=[redacted]")
+ .replace(/\\\\[^\\\s]+\\[^\s]+/g, "[redacted-path]")
+ .replace(/\b[A-Za-z]:\\(?:[^\\\s]+\\)*[^\s]*/g, "[redacted-path]")
+ .replace(/(?<![A-Za-z0-9:/])\/(?:Users|home|tmp|var|etc|opt|private|usr|Library|Volumes|Applications|root|run|srv|mnt)(?:\/[^\s]*)?/g, "[redacted-path]");
+ const encoded = Buffer.from(scrubbed, "utf8");
+ if (encoded.byteLength > 65_536) {
+ let bytes = 0;
+ const bounded: string[] = [];
+ for (const codePoint of scrubbed) {
+ const width = Buffer.byteLength(codePoint, "utf8");
+ if (bytes + width > 65_536) break;
+ bounded.push(codePoint);
+ bytes += width;
+ }
+ scrubbed = bounded.join("");
+ }
+ return scrubbed;
+}
+
+function projectRule(value: unknown, rule: FieldRule): { ok: true; value: unknown } | { ok: false } {
+ if (value === null && rule.type === "string" && rule.nullable) return { ok: true, value: null };
+ switch (rule.type) {
+ case "string":
+ if (!boundedString(value, rule.maxChars) || (rule.values && !rule.values.includes(value))) return { ok: false };
+ return { ok: true, value: rule.scrub ? scrubDiagnosticText(value) : value };
+ case "number":
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= rule.min && value <= rule.max
+ ? { ok: true, value }
+ : { ok: false };
+ case "boolean":
+ return typeof value === "boolean" ? { ok: true, value } : { ok: false };
+ case "string_array":
+ if (!Array.isArray(value) || value.length > rule.maxItems) return { ok: false };
+ if (!value.every((entry) => boundedString(entry, rule.maxChars) && (!rule.values || rule.values.includes(entry)))) return { ok: false };
+ return { ok: true, value: [...value] };
+ }
+}
+
+export function projectDaemonLogRow(value: unknown, targetAgentId: string): Record<string, unknown> | null {
+ const row = object(value);
+ if (!row || !canonicalTime(row.time) || !["debug", "info", "warn", "error"].includes(row.level as LogLevel)) return null;
+ if (typeof row.header !== "string" || typeof row.message !== "string") return null;
+ const policy = DAEMON_LOG_DIAGNOSTIC_POLICY.find((entry) => entry.header === row.header && entry.message === row.message);
+ const fields = object(row.fields);
+ if (!policy || !fields) return null;
+ if (policy.scope === "target" && fields.agentId !== targetAgentId) return null;
+ const projectedFields: Record<string, unknown> = {};
+ for (const [key, rule] of Object.entries(policy.fields)) {
+ if (!(key in fields) || fields[key] === undefined) continue;
+ const projected = projectRule(fields[key], rule);
+ if (!projected.ok) return null;
+ projectedFields[key] = projected.value;
+ }
+ return {
+ recordType: "daemon_log",
+ timeMs: Date.parse(row.time),
+ time: row.time,
+ header: row.header,
+ level: row.level,
+ message: row.message,
+ fields: projectedFields,
+ };
+}
+
+const MANAGER_EVENTS = ["register", "wake", "spawned", "session", "progress", "turn_end", "exit", "tick", "reset_session", "begin_reset", "rewake_after_reset", "runtime_signal"] as const;
+const MANAGER_EFFECTS = ["spawn", "send", "stop", "terminate_stalled", "force_exit", "gated_hold"] as const;
+const AGENT_STATUSES = ["idle", "starting", "running", "stopping"] as const;
+const APM_PHASES = ["idle", "tool_wait", "tool_boundary", "assistant_continuation", "compacting", "reviewing", "error"] as const;
+const TERMINATION_CAUSES = ["runtime_error", "killed_stalled", "other"] as const;
+const SPAWN_FAILURE_REASONS = ["ENOENT", "handshake_timeout", "pre_handshake_exit", "spawn_threw", "other"] as const;
+const TERMINATION_SEMANTICS = ["killed_stalled", "idle_stop", "force_exit", "other"] as const;
+const ABORT_CAUSES = ["start_threw", "start_rejected", "send_threw", "spawn_failure", "handshake_timeout", "reset", "nap", "model_switch", "requested_stop", "shutdown", "physical_exit", "terminate_stalled", "force_exit", "other"] as const;
+const EXIT_SIGNALS = new Set(["SIGABRT", "SIGALRM", "SIGBREAK", "SIGBUS", "SIGCHLD", "SIGCONT", "SIGFPE", "SIGHUP", "SIGILL", "SIGINFO", "SIGINT", "SIGIO", "SIGIOT", "SIGKILL", "SIGLOST", "SIGPIPE", "SIGPOLL", "SIGPROF", "SIGPWR", "SIGQUIT", "SIGSEGV", "SIGSTKFLT", "SIGSTOP", "SIGSYS", "SIGTERM", "SIGTRAP", "SIGTSTP", "SIGTTIN", "SIGTTOU", "SIGURG", "SIGUSR1", "SIGUSR2", "SIGVTALRM", "SIGWINCH", "SIGXCPU", "SIGXFSZ", "other"]);
+
+function enumValue(value: unknown, values: readonly string[], bucket = false, maxChars = 64): string | null {
+ if (!boundedString(value, maxChars)) return null;
+ return values.includes(value) ? value : bucket ? "other" : null;
+}
+
+function copyInteger(row: Record<string, unknown>, output: Record<string, unknown>, key: string, options: { optional?: boolean; nullable?: boolean; min?: number } = {}): boolean {
+ if (!(key in row) || row[key] === undefined) return options.optional === true;
+ if (row[key] === null && options.nullable) { output[key] = null; return true; }
+ if (!safeInteger(row[key], options.min ?? 0)) return false;
+ output[key] = row[key];
+ return true;
+}
+
+function copyString(row: Record<string, unknown>, output: Record<string, unknown>, key: string, maxChars: number, optional = false, nullable = false): boolean {
+ if (!(key in row) || row[key] === undefined) return optional;
+ if (row[key] === null && nullable) { output[key] = null; return true; }
+ if (!boundedString(row[key], maxChars)) return false;
+ output[key] = row[key];
+ return true;
+}
+
+function projectTraceBase(row: Record<string, unknown>, targetAgentId: string): Record<string, unknown> | null {
+ if (row.agentId !== targetAgentId || !boundedString(row.agentId, 128) || !canonicalTime(row.timeIso)) return null;
+ const output: Record<string, unknown> = { recordType: "fsm", recordKind: row.recordKind, agentId: row.agentId };
+ if (!Array.isArray(row.effects) || row.effects.length > 32 || !row.effects.every((effect) => typeof effect === "string")) return null;
+ output.effects = row.effects.filter((effect) => MANAGER_EFFECTS.includes(effect as typeof MANAGER_EFFECTS[number]));
+ if (!copyInteger(row, output, "nowMs") || !copyString(row, output, "timeIso", 32)) return null;
+ return output;
+}
+
+function projectOptionalSpanMetadata(row: Record<string, unknown>, output: Record<string, unknown>): boolean {
+ return copyString(row, output, "traceTurnId", 1_024, true)
+ && copyInteger(row, output, "daemonTurnOrdinal", { optional: true, min: 1 })
+ && copyInteger(row, output, "spawnOrdinal", { optional: true, min: 1 })
+ && copyInteger(row, output, "turnOrdinal", { optional: true, min: 1 })
+ && copyString(row, output, "launchIdSnapshot", 1_024, true, true);
+}
+
+function projectFsm(row: Record<string, unknown>, targetAgentId: string): Record<string, unknown> | null {
+ const output = projectTraceBase(row, targetAgentId);
+ if (!output) return null;
+ const event = enumValue(row.event, MANAGER_EVENTS);
+ const status = enumValue(row.status, AGENT_STATUSES);
+ const apmPhase = enumValue(row.apmPhase, APM_PHASES);
+ if (!event || !status || !apmPhase || typeof row.turnActive !== "boolean" || typeof row.resetting !== "boolean") return null;
+ Object.assign(output, { event, status, turnActive: row.turnActive });
+ if (!copyInteger(row, output, "inbox")
+ || !copyInteger(row, output, "lastDeliverAt", { nullable: true })
+ || !copyInteger(row, output, "lastProgressAt")
+ || !copyInteger(row, output, "idleSince", { nullable: true })) return null;
+ output.resetting = row.resetting;
+ if (!copyInteger(row, output, "resettingSince", { nullable: true })
+ || !copyInteger(row, output, "stoppingSince", { nullable: true })) return null;
+ output.apmPhase = apmPhase;
+ if (!copyInteger(row, output, "sinceProgressMs")
+ || !copyInteger(row, output, "sinceDeliverMs", { nullable: true })
+ || !copyInteger(row, output, "sinceStoppingMs", { nullable: true })
+ || !projectOptionalSpanMetadata(row, output)) return null;
+
+ if ("endReason" in row && row.endReason !== undefined) {
+ if (event !== "turn_end" || row.endReason !== "errored") return null;
+ output.endReason = "errored";
+ }
+ if ("terminationCause" in row && row.terminationCause !== undefined) {
+ if (event !== "turn_end") return null;
+ const cause = enumValue(row.terminationCause, TERMINATION_CAUSES, true);
+ if (!cause) return null;
+ output.terminationCause = cause;
+ }
+ if ("exitCode" in row && row.exitCode !== undefined) {
+ if (event !== "exit" || !copyInteger(row, output, "exitCode", { nullable: true, optional: true })) return null;
+ }
+ if ("exitSignal" in row && row.exitSignal !== undefined) {
+ if (event !== "exit") return null;
+ if (row.exitSignal === null) output.exitSignal = null;
+ else if (!boundedString(row.exitSignal, 64)) return null;
+ else output.exitSignal = EXIT_SIGNALS.has(row.exitSignal) ? row.exitSignal : "other";
+ }
+ if ("abnormal" in row && row.abnormal !== undefined) {
+ if (event !== "exit") return null;
+ if (typeof row.abnormal !== "boolean") return null;
+ output.abnormal = row.abnormal;
+ }
+ for (const [key, values] of [["spawnFailureReason", SPAWN_FAILURE_REASONS], ["terminationSemantics", TERMINATION_SEMANTICS]] as const) {
+ if (!(key in row) || row[key] === undefined) continue;
+ if (event !== "exit") return null;
+ const projected = enumValue(row[key], values, true);
+ if (!projected) return null;
+ output[key] = projected;
+ }
+ return output;
+}
+
+function projectTurnSpan(row: Record<string, unknown>, targetAgentId: string): Record<string, unknown> | null {
+ const output = projectTraceBase(row, targetAgentId);
+ if (!output) return null;
+ const event = enumValue(row.event, ["turn_begin", "turn_end", "turn_abort"]);
+ if (!event || !copyString(row, output, "traceTurnId", 1_024)
+ || !copyInteger(row, output, "daemonTurnOrdinal", { min: 1 })
+ || !copyInteger(row, output, "spawnOrdinal", { min: 1 })
+ || !copyInteger(row, output, "turnOrdinal", { min: 1 })
+ || !copyString(row, output, "launchIdSnapshot", 1_024, false, true)) return null;
+ output.event = event;
+ if (event === "turn_end") {
+ const outcome = enumValue(row.outcome, ["clean", "errored"]);
+ if (!outcome) return null;
+ output.outcome = outcome;
+ if ("terminationCause" in row && row.terminationCause !== undefined) {
+ if (outcome !== "errored") return null;
+ const cause = enumValue(row.terminationCause, TERMINATION_CAUSES, true);
+ if (!cause) return null;
+ output.terminationCause = cause;
+ }
+ } else if (event === "turn_abort") {
+ const cause = enumValue(row.abortCause, ABORT_CAUSES, true);
+ if (!cause) return null;
+ output.abortCause = cause;
+ }
+ return output;
+}
+
+export function projectFsmTraceRow(value: unknown, targetAgentId: string): Record<string, unknown> | null {
+ const row = object(value);
+ if (!row) return null;
+ if (row.recordKind === "fsm") return projectFsm(row, targetAgentId);
+ if (row.recordKind === "turn_span") return projectTurnSpan(row, targetAgentId);
+ return null;
+}
+
+export function projectStatusRow(value: unknown, targetAgentId: string): Record<string, unknown> | null {
+ const row = object(value);
+ if (!row || !safeInteger(row.writtenAt) || !Array.isArray(row.agents)) return null;
+ const agent = row.agents.map(object).find((entry) => entry?.agentId === targetAgentId);
+ if (!agent || !boundedString(agent.agentId, 128)) return null;
+ const status = enumValue(agent.status, AGENT_STATUSES);
+ const derivedActivity = enumValue(agent.derivedActivity, AGENT_STATUSES);
+ if (!status || !derivedActivity || typeof agent.turnActive !== "boolean") return null;
+ const output: Record<string, unknown> = {
+ recordType: "status",
+ timeMs: row.writtenAt,
+ agentId: agent.agentId,
+ status,
+ derivedActivity,
+ turnActive: agent.turnActive,
+ };
+ if (!copyInteger(agent, output, "inbox")
+ || !copyInteger(agent, output, "sinceProgressMs")
+ || !copyInteger(agent, output, "stoppingSince", { nullable: true })) return null;
+ return output;
+}
diff --git a/src/daemon/src/diagnostics/snapshotReader.test.ts b/src/daemon/src/diagnostics/snapshotReader.test.ts
new file mode 100644
index 000000000..65b94c9a4
--- /dev/null
+++ b/src/daemon/src/diagnostics/snapshotReader.test.ts
@@ -0,0 +1,318 @@
+import { execFileSync } from "node:child_process";
+import {
+ appendFileSync,
+ closeSync,
+ existsSync,
+ mkdtempSync,
+ openSync,
+ readFileSync,
+ rmSync,
+ statSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+ createRotatingFileSink,
+ type RotatingFileSink,
+} from "../util/rotatingFileSink.js";
+
+type SnapshotSourceName = "daemon_log" | "fsm_trace";
+type SnapshotWarningCode =
+ | "source_unavailable"
+ | "malformed_json"
+ | "line_too_long"
+ | "incomplete_tail"
+ | "invalid_timestamp";
+
+interface SnapshotRow {
+ source: SnapshotSourceName;
+ timeMs: number;
+ ordinal: number;
+ value: Record<string, unknown>;
+}
+
+interface SnapshotReadResult {
+ rows: SnapshotRow[];
+ warnings: SnapshotWarningCode[];
+ droppedRows: number;
+}
+
+interface SnapshotReaderModule {
+ readSnapshotJsonLines(args: {
+ source: Pick<RotatingFileSink, "openSnapshot">;
+ sourceName: SnapshotSourceName;
+ fromMs: number;
+ maxLineBytes: number;
+ timestampOf: (value: Record<string, unknown>) => number | null;
+ }): Promise<SnapshotReadResult>;
+ mergeChronologicalSnapshotRows(inputs: readonly SnapshotRow[][]): SnapshotRow[];
+ readPinnedJsonFile(args: {
+ path: string;
+ maxBytes: number;
+ }): Promise<{ value: unknown | null; warnings: SnapshotWarningCode[] }>;
+}
+
+async function loadSubject(): Promise<SnapshotReaderModule> {
+ return vi.importActual<SnapshotReaderModule>("./snapshotReader.js");
+}
+
+function line(id: string, timeMs: number): string {
+ return JSON.stringify({ id, timeMs });
+}
+
+function timestampOf(value: Record<string, unknown>): number | null {
+ return typeof value.timeMs === "number" ? value.timeMs : null;
+}
+
+const dirs = new Set<string>();
+
+function tempDir(): string {
+ const dir = mkdtempSync(join(tmpdir(), "diagnostics-snapshot-"));
+ dirs.add(dir);
+ return dir;
+}
+
+afterEach(() => {
+ for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+ dirs.clear();
+});
+
+describe("B2c snapshot reader", () => {
+ it("opens the existing rotating sink snapshot synchronously and survives A/B/C rotation", async () => {
+ const api = await loadSubject();
+ const path = join(tempDir(), "daemon.log");
+ const sink = createRotatingFileSink(path, 30, { mode: 0o600, hardMaxBytes: true });
+ sink.write(line("A", 100));
+ sink.write(line("B", 200));
+ expect(readFileSync(`${path}.1`, "utf8")).toBe(`${line("A", 100)}\n`);
+ expect(readFileSync(path, "utf8")).toBe(`${line("B", 200)}\n`);
+ const openSnapshot = vi.spyOn(sink, "openSnapshot");
+
+ const pending = api.readSnapshotJsonLines({
+ source: sink,
+ sourceName: "daemon_log",
+ fromMs: 0,
+ maxLineBytes: 1024,
+ timestampOf,
+ });
+
+ expect(openSnapshot).toHaveBeenCalledTimes(1);
+ sink.write(line("C", 300));
+ const result = await pending;
+ const ids = result.rows.map((row) => row.value.id);
+
+ expect(ids).toEqual(["A", "B"]);
+ expect(ids).not.toEqual(["A", "C"]);
+ });
+
+ it("closes every pinned fd in finally on success and timestamp failure", async () => {
+ const api = await loadSubject();
+ const path = join(tempDir(), "source.jsonl");
+ writeFileSync(path, `${line("one", 100)}\n`);
+
+ const makeSource = () => {
+ const fd = openSync(path, "r");
+ const close = vi.fn(() => closeSync(fd));
+ return {
+ source: {
+ openSnapshot: () => ({
+ files: [{ path, fd, size: statSync(path).size }],
+ close,
+ }),
+ },
+ close,
+ };
+ };
+
+ const successful = makeSource();
+ await api.readSnapshotJsonLines({
+ source: successful.source,
+ sourceName: "daemon_log",
+ fromMs: 0,
+ maxLineBytes: 1024,
+ timestampOf,
+ });
+ expect(successful.close).toHaveBeenCalledTimes(1);
+
+ const failed = makeSource();
+ const result = await api.readSnapshotJsonLines({
+ source: failed.source,
+ sourceName: "daemon_log",
+ fromMs: 0,
+ maxLineBytes: 1024,
+ timestampOf: () => {
+ throw new Error("HOSTILE_TIMESTAMP_DETAIL");
+ },
+ });
+ expect(failed.close).toHaveBeenCalledTimes(1);
+ expect(result).toEqual({ rows: [], warnings: ["invalid_timestamp"], droppedRows: 1 });
+ expect(JSON.stringify(result)).not.toContain("HOSTILE_TIMESTAMP_DETAIL");
+ });
+
+ it("reports a missing rotating source without inventing rows", async () => {
+ const api = await loadSubject();
+ const path = join(tempDir(), "missing.log");
+ expect(existsSync(path)).toBe(false);
+ const source = createRotatingFileSink(path, 4096, { mode: 0o600, hardMaxBytes: true });
+ await expect(api.readSnapshotJsonLines({
+ source,
+ sourceName: "daemon_log",
+ fromMs: 0,
+ maxLineBytes: 1024,
+ timestampOf,
+ })).resolves.toEqual({ rows: [], warnings: ["source_unavailable"], droppedRows: 0 });
+ });
+
+ it("pins active size so appends after openSnapshot are never read", async () => {
+ const api = await loadSubject();
+ const path = join(tempDir(), "fsm-trace.jsonl");
+ const sink = createRotatingFileSink(path, 1024 * 1024, { mode: 0o600, hardMaxBytes: true });
+ sink.write(line("before", 100));
+
+ const pending = api.readSnapshotJsonLines({
+ source: sink,
+ sourceName: "fsm_trace",
+ fromMs: 0,
+ maxLineBytes: 1024,
+ timestampOf,
+ });
+ sink.write(line("after", 200));
+
+ await expect(pending).resolves.toMatchObject({
+ rows: [expect.objectContaining({ value: expect.objectContaining({ id: "before" }) })],
+ });
+ });
+
+ it("drops malformed and oversize lines and reports an incomplete pinned tail", async () => {
+ const api = await loadSubject();
+ const path = join(tempDir(), "daemon.log");
+ writeFileSync(path, [
+ line("valid", 100),
+ "{broken",
+ JSON.stringify({ id: "oversize", timeMs: 200, text: "x".repeat(200) }),
+ JSON.stringify({ id: "partial", timeMs: 300 }),
+ ].join("\n"));
+ const source = createRotatingFileSink(path, 4096, { mode: 0o600, hardMaxBytes: true });
+
+ const result = await api.readSnapshotJsonLines({
+ source,
+ sourceName: "daemon_log",
+ fromMs: 0,
+ maxLineBytes: 80,
+ timestampOf,
+ });
+
+ expect(result.rows.map((row) => row.value.id)).toEqual(["valid"]);
+ expect(result.warnings).toEqual(["malformed_json", "line_too_long", "incomplete_tail"]);
+ expect(result.droppedRows).toBe(3);
+ });
+
+ it("rejects symlink and FIFO generations without following or blocking", async () => {
+ const api = await loadSubject();
+ const dir = tempDir();
+ const outside = join(dir, "outside.log");
+ writeFileSync(outside, `${line("secret", 100)}\n`);
+ const link = join(dir, "daemon.log");
+ symlinkSync(outside, link);
+ const linked = createRotatingFileSink(link, 4096, { mode: 0o600, hardMaxBytes: true });
+
+ const linkedResult = await api.readSnapshotJsonLines({
+ source: linked,
+ sourceName: "daemon_log",
+ fromMs: 0,
+ maxLineBytes: 1024,
+ timestampOf,
+ });
+ expect(linkedResult.rows).toEqual([]);
+ expect(linkedResult.warnings).toEqual(["source_unavailable"]);
+
+ if (process.platform === "win32") return;
+ const fifoPath = join(dir, "fsm-trace.jsonl");
+ execFileSync("mkfifo", [fifoPath]);
+ const fifo = createRotatingFileSink(fifoPath, 4096, { mode: 0o600, hardMaxBytes: true });
+ const fifoResult = await api.readSnapshotJsonLines({
+ source: fifo,
+ sourceName: "fsm_trace",
+ fromMs: 0,
+ maxLineBytes: 1024,
+ timestampOf,
+ });
+ expect(fifoResult.rows).toEqual([]);
+ expect(fifoResult.warnings).toEqual(["source_unavailable"]);
+ });
+
+ it("uses an inclusive 24-hour cutoff and drops rows without a finite safe timestamp", async () => {
+ const api = await loadSubject();
+ const path = join(tempDir(), "fsm-trace.jsonl");
+ const sink = createRotatingFileSink(path, 4096, { mode: 0o600, hardMaxBytes: true });
+ sink.write(line("old", 999));
+ sink.write(line("boundary", 1000));
+ sink.write(line("new", 1001));
+ sink.write(JSON.stringify({ id: "nan", timeMs: "1002" }));
+ sink.write(JSON.stringify({ id: "unsafe", timeMs: Number.MAX_SAFE_INTEGER + 1 }));
+
+ const result = await api.readSnapshotJsonLines({
+ source: sink,
+ sourceName: "fsm_trace",
+ fromMs: 1000,
+ maxLineBytes: 1024,
+ timestampOf,
+ });
+
+ expect(result.rows.map((row) => row.value.id)).toEqual(["boundary", "new"]);
+ expect(result.droppedRows).toBe(3);
+ });
+
+ it("k-way merges rotated sources chronologically with deterministic source and ordinal ties", async () => {
+ const api = await loadSubject();
+ const dir = tempDir();
+ const log = createRotatingFileSink(join(dir, "daemon.log"), 4096, { mode: 0o600, hardMaxBytes: true });
+ const fsm = createRotatingFileSink(join(dir, "fsm-trace.jsonl"), 4096, { mode: 0o600, hardMaxBytes: true });
+ log.write(line("log-100", 100));
+ log.write(line("log-300-a", 300));
+ log.write(line("log-300-b", 300));
+ fsm.write(line("fsm-200", 200));
+ fsm.write(line("fsm-300", 300));
+
+ const [logRows, fsmRows] = await Promise.all([
+ api.readSnapshotJsonLines({ source: log, sourceName: "daemon_log", fromMs: 0, maxLineBytes: 1024, timestampOf }),
+ api.readSnapshotJsonLines({ source: fsm, sourceName: "fsm_trace", fromMs: 0, maxLineBytes: 1024, timestampOf }),
+ ]);
+ const merged = api.mergeChronologicalSnapshotRows([logRows.rows, fsmRows.rows]);
+
+ expect(merged.map((row) => row.value.id)).toEqual([
+ "log-100",
+ "fsm-200",
+ "log-300-a",
+ "log-300-b",
+ "fsm-300",
+ ]);
+ });
+
+ it("pins status.json with no-follow, a fixed size, and a strict byte cap", async () => {
+ const api = await loadSubject();
+ const dir = tempDir();
+ const statusPath = join(dir, "status.json");
+ writeFileSync(statusPath, JSON.stringify({ writtenAt: 100, agents: [] }));
+ const pending = api.readPinnedJsonFile({ path: statusPath, maxBytes: 1024 });
+ appendFileSync(statusPath, "HOSTILE_TRAILING_BYTES");
+ await expect(pending).resolves.toEqual({
+ value: { writtenAt: 100, agents: [] },
+ warnings: [],
+ });
+
+ const linkPath = join(dir, "status-link.json");
+ symlinkSync(statusPath, linkPath);
+ await expect(api.readPinnedJsonFile({ path: linkPath, maxBytes: 1024 })).resolves.toEqual({
+ value: null,
+ warnings: ["source_unavailable"],
+ });
+ await expect(api.readPinnedJsonFile({ path: statusPath, maxBytes: 4 })).resolves.toEqual({
+ value: null,
+ warnings: ["line_too_long"],
+ });
+ });
+});
diff --git a/src/daemon/src/diagnostics/snapshotReader.ts b/src/daemon/src/diagnostics/snapshotReader.ts
new file mode 100644
index 000000000..5371a37ed
--- /dev/null
+++ b/src/daemon/src/diagnostics/snapshotReader.ts
@@ -0,0 +1,205 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import type { RotatingFileSink } from "../util/rotatingFileSink.js";
+import type {
+ SnapshotReadResult,
+ SnapshotRow,
+ SnapshotSourceName,
+ SnapshotWarningCode,
+} from "./types.js";
+
+function pushWarning(warnings: SnapshotWarningCode[], warning: SnapshotWarningCode): void {
+ warnings.push(warning);
+}
+
+function readPinnedBytes(fd: number, size: number): Buffer {
+ const bytes = Buffer.alloc(size);
+ let offset = 0;
+ while (offset < size) {
+ const read = readSync(fd, bytes, offset, size - offset, offset);
+ if (read === 0) break;
+ offset += read;
+ }
+ return offset === size ? bytes : bytes.subarray(0, offset);
+}
+
+export async function readSnapshotJsonLines(args: {
+ source: Pick<RotatingFileSink, "openSnapshot">;
+ sourceName: SnapshotSourceName;
+ fromMs: number;
+ maxLineBytes: number;
+ timestampOf: (value: Record<string, unknown>) => number | null;
+}): Promise<SnapshotReadResult> {
+ const stream = openSnapshotJsonLineStream(args);
+ const rows: SnapshotRow[] = [];
+ for await (const row of stream.rows) rows.push(row);
+ return { rows, warnings: stream.warnings, droppedRows: stream.stats.droppedRows };
+}
+
+export function openSnapshotJsonLineStream(args: {
+ source: Pick<RotatingFileSink, "openSnapshot">;
+ sourceName: SnapshotSourceName;
+ fromMs: number;
+ maxLineBytes: number;
+ timestampOf: (value: Record<string, unknown>) => number | null;
+}): { rows: AsyncIterable<SnapshotRow>; warnings: SnapshotWarningCode[]; stats: { droppedRows: number }; close(): void } {
+ let snapshot: ReturnType<RotatingFileSink["openSnapshot"]>;
+ const warnings: SnapshotWarningCode[] = [];
+ const stats = { droppedRows: 0 };
+ try {
+ snapshot = args.source.openSnapshot();
+ } catch {
+ warnings.push("source_unavailable");
+ return { rows: { async *[Symbol.asyncIterator]() { /* empty */ } }, warnings, stats, close: () => {} };
+ }
+ let closed = false;
+ const close = (): void => {
+ if (closed) return;
+ closed = true;
+ try { snapshot.close(); } catch { /* best effort */ }
+ };
+ if (snapshot.files.length === 0) {
+ warnings.push("source_unavailable");
+ }
+ const rows = (async function* (): AsyncGenerator<SnapshotRow> {
+ let ordinal = 0;
+ const acceptLine = (line: Buffer): SnapshotRow | null => {
+ let value: unknown;
+ try { value = JSON.parse(line.toString("utf8")); } catch {
+ pushWarning(warnings, "malformed_json"); stats.droppedRows += 1; ordinal += 1; return null;
+ }
+ if (value === null || typeof value !== "object" || Array.isArray(value)) {
+ pushWarning(warnings, "malformed_json"); stats.droppedRows += 1; ordinal += 1; return null;
+ }
+ let timeMs: number | null = null;
+ try { timeMs = args.timestampOf(value as Record<string, unknown>); } catch {
+ pushWarning(warnings, "invalid_timestamp");
+ }
+ if (timeMs === null || !Number.isSafeInteger(timeMs) || timeMs < args.fromMs) {
+ if (timeMs !== null && (!Number.isSafeInteger(timeMs) || timeMs < 0)) pushWarning(warnings, "invalid_timestamp");
+ stats.droppedRows += 1; ordinal += 1; return null;
+ }
+ const row = { source: args.sourceName, timeMs, ordinal, value: value as Record<string, unknown> };
+ ordinal += 1;
+ return row;
+ };
+ try {
+ for (const file of snapshot.files) {
+ let position = 0;
+ let parts: Buffer[] = [];
+ let lineBytes = 0;
+ let oversize = false;
+ try {
+ while (position < file.size) {
+ const chunk = Buffer.alloc(Math.min(64 * 1024, file.size - position));
+ const count = readSync(file.fd, chunk, 0, chunk.length, position);
+ if (count === 0) break;
+ position += count;
+ let start = 0;
+ for (let index = 0; index < count; index += 1) {
+ if (chunk[index] !== 0x0a) continue;
+ const segment = chunk.subarray(start, index);
+ if (!oversize && lineBytes + segment.length <= args.maxLineBytes) {
+ parts.push(segment);
+ lineBytes += segment.length;
+ } else {
+ oversize = true;
+ }
+ if (oversize) {
+ pushWarning(warnings, "line_too_long"); stats.droppedRows += 1; ordinal += 1;
+ } else {
+ const row = acceptLine(Buffer.concat(parts, lineBytes));
+ if (row) yield row;
+ }
+ parts = [];
+ lineBytes = 0;
+ oversize = false;
+ start = index + 1;
+ }
+ const remainder = chunk.subarray(start, count);
+ if (!oversize && lineBytes + remainder.length <= args.maxLineBytes) {
+ parts.push(remainder);
+ lineBytes += remainder.length;
+ } else if (remainder.length > 0) {
+ oversize = true;
+ parts = [];
+ lineBytes = 0;
+ }
+ }
+ if (lineBytes > 0 || oversize) {
+ pushWarning(warnings, "incomplete_tail"); stats.droppedRows += 1; ordinal += 1;
+ }
+ } catch {
+ pushWarning(warnings, "source_unavailable");
+ }
+ }
+ } finally {
+ close();
+ }
+ })();
+ return { rows, warnings, stats, close };
+}
+
+const SOURCE_ORDER: Record<SnapshotSourceName, number> = { daemon_log: 0, fsm_trace: 1 };
+
+export function mergeChronologicalSnapshotRows(inputs: readonly SnapshotRow[][]): SnapshotRow[] {
+ return inputs.flat().sort((a, b) =>
+ a.timeMs - b.timeMs || SOURCE_ORDER[a.source] - SOURCE_ORDER[b.source] || a.ordinal - b.ordinal,
+ );
+}
+
+export async function* mergeChronologicalSnapshotStreams(
+ inputs: readonly AsyncIterable<SnapshotRow>[],
+): AsyncGenerator<SnapshotRow> {
+ const iterators = inputs.map((input) => input[Symbol.asyncIterator]());
+ const heads = await Promise.all(iterators.map((iterator) => iterator.next()));
+ try {
+ while (true) {
+ let selected = -1;
+ for (let index = 0; index < heads.length; index += 1) {
+ const candidate = heads[index];
+ if (!candidate || candidate.done) continue;
+ if (selected < 0) { selected = index; continue; }
+ const current = heads[selected]!;
+ if (current.done) { selected = index; continue; }
+ const a = candidate.value;
+ const b = current.value;
+ if (a.timeMs < b.timeMs
+ || (a.timeMs === b.timeMs && SOURCE_ORDER[a.source] < SOURCE_ORDER[b.source])
+ || (a.timeMs === b.timeMs && a.source === b.source && a.ordinal < b.ordinal)) selected = index;
+ }
+ if (selected < 0) break;
+ const head = heads[selected]!;
+ if (head.done) break;
+ yield head.value;
+ heads[selected] = await iterators[selected]!.next();
+ }
+ } finally {
+ await Promise.all(iterators.map(async (iterator) => { try { await iterator.return?.(); } catch { /* best effort */ } }));
+ }
+}
+
+export async function readPinnedJsonFile(args: {
+ path: string;
+ maxBytes: number;
+}): Promise<{ value: unknown | null; warnings: SnapshotWarningCode[] }> {
+ let fd: number | null = null;
+ try {
+ const noFollow = "O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0;
+ fd = openSync(args.path, constants.O_RDONLY | noFollow);
+ const stat = fstatSync(fd);
+ if (!stat.isFile()) return { value: null, warnings: ["source_unavailable"] };
+ if (stat.size > args.maxBytes) return { value: null, warnings: ["line_too_long"] };
+ const bytes = readPinnedBytes(fd, stat.size);
+ try {
+ return { value: JSON.parse(bytes.toString("utf8")), warnings: [] };
+ } catch {
+ return { value: null, warnings: ["malformed_json"] };
+ }
+ } catch {
+ return { value: null, warnings: ["source_unavailable"] };
+ } finally {
+ if (fd !== null) {
+ try { closeSync(fd); } catch { /* best effort */ }
+ }
+ }
+}
diff --git a/src/daemon/src/diagnostics/types.ts b/src/daemon/src/diagnostics/types.ts
new file mode 100644
index 000000000..e25a953b0
--- /dev/null
+++ b/src/daemon/src/diagnostics/types.ts
@@ -0,0 +1,62 @@
+import type { Readable } from "node:stream";
+import type { DiagnosticCollectCommand, DiagnosticReportFailureCode } from "@alook/shared";
+
+export type SnapshotSourceName = "daemon_log" | "fsm_trace";
+export type SnapshotWarningCode =
+ | "source_unavailable"
+ | "malformed_json"
+ | "line_too_long"
+ | "incomplete_tail"
+ | "invalid_timestamp";
+
+export interface SnapshotRow {
+ source: SnapshotSourceName;
+ timeMs: number;
+ ordinal: number;
+ value: Record<string, unknown>;
+}
+
+export interface SnapshotReadResult {
+ rows: SnapshotRow[];
+ warnings: SnapshotWarningCode[];
+ droppedRows: number;
+}
+
+export interface DiagnosticEventRow extends Record<string, unknown> {
+ recordType: "daemon_log" | "fsm";
+ timeMs: number;
+}
+
+export interface BundleArtifact {
+ path: string;
+ sizeBytes: number;
+ sha256: string;
+ uncompressedBytes: number;
+}
+
+export interface DiagnosticTransportResult {
+ kind: "terminal";
+ status: "uploaded" | "failed";
+}
+
+export interface DiagnosticRetryResult {
+ kind: "retryable";
+}
+
+export interface DiagnosticTransport {
+ upload(meta: { reportId: string; sizeBytes: number; sha256: string }, body: Readable): Promise<DiagnosticTransportResult | DiagnosticRetryResult>;
+ fail(reportId: string, failureCode: DiagnosticReportFailureCode): Promise<DiagnosticTransportResult | DiagnosticRetryResult>;
+}
+
+export interface DiagnosticCoordinatorResult {
+ status: "uploaded" | "failed" | "pending" | "expired";
+ failureCode?: DiagnosticReportFailureCode;
+}
+
+export interface DiagnosticBundleBuilder {
+ (args: { command: DiagnosticCollectCommand; outputPath: string }): Promise<{
+ path: string;
+ sizeBytes: number;
+ sha256: string;
+ }>;
+}