Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
feat(daemon): add diagnostic collector core
Gus621cc2ee5312
diff --git a/src/daemon/src/diagnostics/bundle.test.ts b/src/daemon/src/diagnostics/bundle.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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;+ }>;+}