@zaip-ai/cli 4.5.0 → 4.7.0

package/templates/.agents/dashboard/packages/local-runtime/src/active-codex-telemetry.test.ts

@@ -1,33 +1,84 @@
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { captureActiveCodexTelemetry } from "./active-codex-telemetry.js";
+import {
+  captureActiveCodexTelemetry,
+  captureRepositoryActiveCodexTelemetry,
+} from "./active-codex-telemetry.js";
+import * as sources from "./sqlite-read-model-source-fingerprint.js";
 
 const roots: string[] = [];
 
 afterEach(async () => {
+  vi.restoreAllMocks();
   await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
 });
 
 describe("active Codex telemetry capture", () => {
+  it("allows the measured catch-up budget and still rejects incomplete output", async () => {
+    const root = await runtimeFixture("");
+    const execute = vi.fn(async (_file: string, _args: string[], _options: unknown) => ({
+      stdout: JSON.stringify({
+        telemetry: { mode: "recent_exact_session", complete: false, captured: [] },
+      }),
+      stderr: "",
+    }));
+    await expect(captureActiveCodexTelemetry(root, root, execute as never)).rejects.toThrow(
+      "incomplete",
+    );
+    expect(execute.mock.calls[0]?.[2]).toMatchObject({
+      timeout: 600_000,
+      windowsHide: true,
+      cwd: root,
+    });
+  });
+  it("uses the primary CLI for registered worktrees while preserving each target workspace and cwd", async () => {
+    const primary = await runtimeFixture(`import {writeFileSync} from 'node:fs';
+      import {resolve} from 'node:path';
+      const target=process.argv[process.argv.indexOf('--workspace')+1];
+      if(target!==resolve(process.cwd()))throw new Error('Target workspace mismatch');
+      writeFileSync('capture-target.json',JSON.stringify({target,cwd:process.cwd(),cli:process.argv[1]}));
+      process.stdout.write(JSON.stringify({telemetry:{mode:'recent_exact_session',complete:true,captured:[{captured:true}]}}));`);
+    const secondary = await runtimeFixture(`import {writeFileSync} from 'node:fs';
+      writeFileSync('outdated-cli-executed','incorrect runtime');process.exitCode=9;`);
+    vi.spyOn(sources, "dashboardCanonicalSourceRoots").mockResolvedValue([primary, secondary]);
+    await expect(captureRepositoryActiveCodexTelemetry(primary)).resolves.toMatchObject({
+      captured_runs: 2,
+      captured_segments: null,
+      skipped_reason: null,
+    });
+    for (const target of [primary, secondary]) {
+      const captured = JSON.parse(await readFile(join(target, "capture-target.json"), "utf8"));
+      expect(captured).toEqual({
+        target,
+        cwd: target,
+        cli: join(primary, ".agents/runtime/bin/zaip.mjs"),
+      });
+    }
+    await expect(stat(join(secondary, "outdated-cli-executed"))).rejects.toMatchObject({
+      code: "ENOENT",
+    });
+  });
   it("reports an idle capture explicitly instead of treating it as an opaque success", async () => {
     const root = await runtimeFixture(
-      "process.stdout.write(JSON.stringify({ telemetry: { mode: 'active_exact_session', captured: [] } }, null, 2));\n",
+      "process.stdout.write(JSON.stringify({ telemetry: { mode: 'recent_exact_session', complete:true, captured: [] } }, null, 2));\n",
     );
 
     await expect(captureActiveCodexTelemetry(root)).resolves.toMatchObject({
       captured_runs: 0,
       captured_segments: 0,
       manifest_state: "initialized",
-      skipped_reason: "no_active_runs",
+      skipped_reason: "no_recent_runs",
       last_capture_at: expect.any(String),
     });
   });
 
-  it("does not execute a CLI against historical running entries in a stale worktree", async () => {
-    const root = await runtimeFixture("process.exitCode = 8;\n");
+  it("does not let an empty or stale active index suppress terminal usage capture", async () => {
+    const root = await runtimeFixture(
+      "if(!process.argv.includes('--recent') || !process.argv.includes('--drain') || process.argv.includes('--active') || process.argv[process.argv.indexOf('--limit')+1]!=='32') process.exit(8); process.stdout.write(JSON.stringify({telemetry:{mode:'recent_exact_session',complete:true,captured:[{captured:true}]}}));\n",
+    );
     await writeFile(
       join(root, ".agents/records/lifecycle/active-work.json"),
       JSON.stringify({
@@ -36,13 +87,13 @@ describe("active Codex telemetry capture", () => {
       }),
     );
     await expect(captureActiveCodexTelemetry(root)).resolves.toMatchObject({
-      skipped_reason: "no_recent_active_runs",
-      captured_runs: 0,
+      skipped_reason: null,
+      captured_runs: 1,
     });
   });
   it("still captures a recently active worktree Run", async () => {
     const root = await runtimeFixture(
-      "process.stdout.write(JSON.stringify({telemetry:{captured:[{captured:true}]}}));\n",
+      "process.stdout.write(JSON.stringify({telemetry:{mode:'recent_exact_session',complete:true,captured:[{captured:true}]}}));\n",
     );
     await writeFile(
       join(root, ".agents/records/lifecycle/active-work.json"),
@@ -71,7 +122,7 @@ describe("active Codex telemetry capture", () => {
   });
   it("does not accept CLI idle success as proof of initialized lifecycle", async () => {
     const root = await runtimeFixture(
-      "process.stdout.write(JSON.stringify({ telemetry: { captured: [] } }));",
+      "process.stdout.write(JSON.stringify({ telemetry: { mode:'recent_exact_session', complete:true, captured: [] } }));",
     );
     await rm(join(root, ".agents/records/lifecycle"), { recursive: true });
     await expect(captureActiveCodexTelemetry(root)).resolves.toMatchObject({
@@ -81,7 +132,7 @@ describe("active Codex telemetry capture", () => {
   });
   it("preserves unavailable segment cardinality for a captured Run", async () => {
     const root = await runtimeFixture(
-      "process.stdout.write(JSON.stringify({ telemetry: { captured: [{captured:true}] } }, null, 2));",
+      "process.stdout.write(JSON.stringify({ telemetry: { mode:'recent_exact_session', complete:true, captured: [{captured:true}] } }, null, 2));",
     );
     await expect(captureActiveCodexTelemetry(root)).resolves.toMatchObject({
       captured_runs: 1,
@@ -95,6 +146,21 @@ describe("active Codex telemetry capture", () => {
     );
     await expect(captureActiveCodexTelemetry(root)).rejects.toThrow("Invalid capture telemetry");
   });
+  it("rejects an incomplete bounded pass rather than calling partial collection current", async () => {
+    const root = await runtimeFixture(
+      "process.stdout.write(JSON.stringify({telemetry:{mode:'recent_exact_session',complete:false,captured:[]}}));",
+    );
+    await expect(captureActiveCodexTelemetry(root)).rejects.toThrow("incomplete");
+  });
+  it.each([
+    "active_exact_session",
+    null,
+  ])("rejects incompatible capture receipt mode %s", async (mode) => {
+    const root = await runtimeFixture(
+      `process.stdout.write(JSON.stringify({telemetry:{mode:${JSON.stringify(mode)},complete:true,captured:[]}}));`,
+    );
+    await expect(captureActiveCodexTelemetry(root)).rejects.toThrow("incomplete");
+  });
 });
 
 async function runtimeFixture(script: string): Promise<string> {

package/templates/.agents/dashboard/packages/local-runtime/src/active-codex-telemetry.ts

@@ -1,12 +1,15 @@
 import { execFile } from "node:child_process";
-import { readFile, stat } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { promisify } from "node:util";
 import { WorkspaceFileSystem } from "@zaip-ai/core";
 import { lifecycleManifestState } from "./server-lifecycle-diagnostics.js";
 import { dashboardCanonicalSourceRoots } from "./sqlite-read-model-source-fingerprint.js";
 
 const execFileAsync = promisify(execFile);
+// Measured complete catch-up of a 98-Run / 30k-envelope backlog exceeded the
+// old 55s deadline. Keep the UI updating while this finite selection commits;
+// expiry remains a failure and can never promote a partial capture to current.
+export const RECENT_CODEX_CAPTURE_TIMEOUT_MS = 600_000;
 
 export type ActiveCodexTelemetryCapture = {
   captured_runs: number;
@@ -18,18 +21,21 @@ export type ActiveCodexTelemetryCapture = {
     | "manifest_invalid"
     | "no_active_runs"
     | "no_recent_active_runs"
+    | "no_recent_runs"
     | "no_new_segments"
     | null;
   last_capture_at: string;
 };
 
 /**
- * Captures only active Runs whose persisted Codex correlation names a concrete
+ * Captures recent active and terminal Runs whose persisted Codex correlation names a concrete
  * turn. The CLI reuses source segment and loop keys as its durable cursor;
  * this never reconciles or changes a Run lifecycle.
  */
 export async function captureActiveCodexTelemetry(
   workspaceRoot: string,
+  runtimeRoot = workspaceRoot,
+  execute = execFileAsync,
 ): Promise<ActiveCodexTelemetryCapture> {
   // The CLI intentionally treats an absent active-work index as an empty pass.
   // Validate the canonical manifest first so that exit 0 cannot mask missing lifecycle.
@@ -42,26 +48,28 @@ export async function captureActiveCodexTelemetry(
       skipped_reason: manifestState === "missing" ? "manifest_uninitialized" : "manifest_invalid",
       last_capture_at: new Date().toISOString(),
     };
-  const activeRuns = await recentActiveRuns(workspaceRoot);
-  if (activeRuns !== null && activeRuns.recent === 0) {
-    return {
-      captured_runs: 0,
-      captured_segments: 0,
-      manifest_state: "initialized",
-      skipped_reason: activeRuns.stale > 0 ? "no_recent_active_runs" : "no_active_runs",
-      last_capture_at: new Date().toISOString(),
-    };
-  }
-  const cliPath = resolve(workspaceRoot, ".agents", "runtime", "bin", "zaip.mjs");
+  const cliPath = resolve(runtimeRoot, ".agents", "runtime", "bin", "zaip.mjs");
   try {
-    const outcome = await execFileAsync(
+    const outcome = await execute(
       process.execPath,
-      [cliPath, "run", "usage", "--active", "--limit", "1", "--disable-codex-raw", "--json"],
+      [
+        cliPath,
+        "--workspace",
+        resolve(workspaceRoot),
+        "run",
+        "usage",
+        "--recent",
+        "--limit",
+        "32",
+        "--drain",
+        "--disable-codex-raw",
+        "--json",
+      ],
       {
         cwd: workspaceRoot,
         encoding: "utf8",
         windowsHide: true,
-        timeout: 55_000,
+        timeout: RECENT_CODEX_CAPTURE_TIMEOUT_MS,
         maxBuffer: 1_024 * 1_024,
       },
     );
@@ -75,7 +83,7 @@ export async function captureActiveCodexTelemetry(
       captured_segments: capturedRuns === 0 ? 0 : null,
       manifest_state: "initialized",
       skipped_reason:
-        captured.length === 0 ? "no_active_runs" : capturedRuns === 0 ? "no_new_segments" : null,
+        captured.length === 0 ? "no_recent_runs" : capturedRuns === 0 ? "no_new_segments" : null,
       last_capture_at: new Date().toISOString(),
     };
   } catch (error) {
@@ -92,49 +100,18 @@ export async function captureActiveCodexTelemetry(
   }
 }
 
-/** A stale lifecycle index is not proof of a live Codex invocation. */
-async function recentActiveRuns(
-  workspaceRoot: string,
-): Promise<{ recent: number; stale: number } | null> {
-  const path = join(workspaceRoot, ".agents", "records", "lifecycle", "active-work.json");
-  const metadata = await stat(path).catch((error: NodeJS.ErrnoException) => {
-    if (error.code === "ENOENT") return null;
-    throw error;
-  });
-  if (metadata === null) return null;
-  if (metadata.size > 8 * 1024 * 1024) throw new Error("Active-work index exceeds capture limit");
-  const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
-  if (
-    typeof parsed !== "object" ||
-    parsed === null ||
-    !Array.isArray((parsed as { items?: unknown }).items)
-  )
-    throw new Error("Invalid active-work index for telemetry capture");
-  const cutoff = Date.now() - 72 * 60 * 60 * 1_000;
-  const runs = (parsed as { items: unknown[] }).items.filter(
-    (item) =>
-      typeof item === "object" &&
-      item !== null &&
-      (item as { kind?: unknown }).kind === "run" &&
-      (item as { status?: unknown }).status === "running",
-  );
-  const recent = runs.filter((item) => {
-    const updated = (item as { updated_at?: unknown }).updated_at;
-    return (
-      typeof updated === "string" &&
-      Number.isFinite(Date.parse(updated)) &&
-      Date.parse(updated) >= cutoff
-    );
-  }).length;
-  return { recent, stale: runs.length - recent };
-}
-
 /** Capture each canonical checkout before refreshing the combined SQLite view. */
 export async function captureRepositoryActiveCodexTelemetry(
   workspaceRoot: string,
+  runtimeRoot = workspaceRoot,
 ): Promise<ActiveCodexTelemetryCapture> {
   const roots = await dashboardCanonicalSourceRoots(workspaceRoot);
-  const results = await Promise.all(roots.map((root) => captureActiveCodexTelemetry(root)));
+  // Registered checkouts contribute records, not executable runtime versions.
+  // One current CLI serves every target; --workspace pins its storage and
+  // exact source correlation even when the cwd belongs to another checkout.
+  const results = await Promise.all(
+    roots.map((root) => captureActiveCodexTelemetry(root, runtimeRoot)),
+  );
   const primary = results[0];
   if (primary === undefined) throw new Error("No dashboard workspace was discovered");
   const capturedRuns = results.reduce((count, result) => count + result.captured_runs, 0);
@@ -166,6 +143,9 @@ function readCaptured(payload: unknown): Array<{ captured: boolean }> {
   const telemetry = (payload as { telemetry?: unknown }).telemetry;
   if (typeof telemetry !== "object" || telemetry === null)
     throw new Error("Invalid capture telemetry");
+  const receipt = telemetry as { mode?: unknown; complete?: unknown };
+  if (receipt.mode !== "recent_exact_session" || receipt.complete !== true)
+    throw new Error("Recent telemetry capture is incomplete");
   const captured = (telemetry as { captured?: unknown }).captured;
   if (!Array.isArray(captured)) throw new Error("Invalid capture entries");
   return captured.map((item) => {

package/templates/.agents/dashboard/packages/local-runtime/src/canonical-source-revision-cache.test.ts

@@ -0,0 +1,125 @@
+import * as fs from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { CanonicalSourceRevisionCache } from "./canonical-source-revision-cache.js";
+import { sourceFingerprint } from "./sqlite-read-model-source-fingerprint.js";
+
+vi.mock("node:fs/promises", async (original) => {
+  const actual = await original<typeof import("node:fs/promises")>();
+  return { ...actual, readFile: vi.fn(actual.readFile) };
+});
+
+const roots: string[] = [];
+const source = ".agents/records/tasks/TASK-CACHE.md";
+const record = (revision: number) =>
+  `---\nid: TASK-CACHE\nupdated_at: 2026-09-29T12:00:00Z\nrevision: ${revision}\n---\n`;
+async function fixture() {
+  const parent = resolve(import.meta.dirname, "../../../../..", ".local/sqlite/tests");
+  await fs.mkdir(parent, { recursive: true });
+  const root = await fs.mkdtemp(join(parent, "revision-cache-"));
+  roots.push(root);
+  await fs.mkdir(join(root, ".agents/records/tasks"), { recursive: true });
+  await fs.writeFile(join(root, source), record(1));
+  return root;
+}
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
+});
+
+describe("physical canonical revision cache", () => {
+  it("persists peer revisions across workers, selects revision despite older mtime, and bypasses on force", async () => {
+    const root = await fixture();
+    const peer = await fixture();
+    await fs.writeFile(join(peer, source), record(2));
+    await fs.utimes(join(peer, source), new Date("2025-01-01"), new Date("2025-01-01"));
+    vi.spyOn(Date, "now").mockReturnValue(Date.now() + 10_000);
+    const options = { sourceRoots: [root, peer] };
+    const initial = await sourceFingerprint(root, options);
+    expect(initial.candidates[0]?.path).toBe(join(peer, source));
+    expect(initial.duplicateReads).toBe(2);
+    const previous = new Map(initial.candidates.map((item) => [item.source, item]));
+    const next = await sourceFingerprint(root, { ...options, previous });
+    expect(next).toMatchObject({ duplicateReads: 0, duplicateReused: 2, hashedFiles: 0 });
+    expect(next.fingerprint).toBe(initial.fingerprint);
+    const forced = await sourceFingerprint(root, { ...options, previous, verifyContent: true });
+    expect(forced).toMatchObject({ duplicateReads: 2, duplicateReused: 0, hashedFiles: 1 });
+    expect(forced.fingerprint).toBe(initial.fingerprint);
+    expect(await fs.stat(join(peer, ".local")).catch(() => null)).toBeNull();
+  });
+
+  it("invalidates edits, replacements, additions and removals; keeps ties deterministic", async () => {
+    const root = await fixture();
+    const peer = await fixture();
+    vi.spyOn(Date, "now").mockReturnValue(Date.now() + 10_000);
+    const options = { sourceRoots: [root, peer] };
+    expect((await sourceFingerprint(root, options)).candidates[0]?.path).toBe(join(root, source));
+    const metadata = await fs.stat(join(peer, source));
+    await fs.writeFile(join(peer, source), record(2));
+    await fs.utimes(join(peer, source), metadata.atime, metadata.mtime);
+    expect((await sourceFingerprint(root, options)).candidates[0]?.path).toBe(join(peer, source));
+    await fs.writeFile(join(root, "replacement"), record(3));
+    await fs.utimes(join(root, "replacement"), metadata.atime, metadata.mtime);
+    await fs.rename(join(root, "replacement"), join(root, source));
+    expect((await sourceFingerprint(root, options)).candidates[0]?.path).toBe(join(root, source));
+    await fs.writeFile(join(peer, ".agents/records/tasks/NEW.md"), record(1));
+    expect((await sourceFingerprint(root, options)).candidates).toHaveLength(2);
+    await fs.rm(join(root, source));
+    expect(
+      (await sourceFingerprint(root, options)).candidates.find((item) => item.source === source)
+        ?.path,
+    ).toBe(join(peer, source));
+  });
+
+  it("does not trust rapid writes or their first settled cache entry", async () => {
+    const root = await fixture();
+    const peer = await fixture();
+    const metadata = await fs.stat(join(root, source));
+    const clock = vi.spyOn(Date, "now").mockReturnValue(metadata.ctimeMs);
+    const options = { sourceRoots: [root, peer] };
+    await sourceFingerprint(root, options);
+    for (let value = 2; value < 8; value++) {
+      await fs.writeFile(join(peer, source), record(value));
+      const result = await sourceFingerprint(root, options);
+      expect(result.duplicateReads).toBe(2);
+      expect(result.candidates[0]?.path).toBe(join(peer, source));
+    }
+    clock.mockReturnValue(Date.now() + 20_000);
+    expect((await sourceFingerprint(root, options)).duplicateReads).toBe(2);
+    expect((await sourceFingerprint(root, options)).duplicateReads).toBe(0);
+  });
+
+  it("retries when file metadata changes while reading its revision", async () => {
+    const root = await fixture();
+    const cache = await CanonicalSourceRevisionCache.open(root);
+    const actualRead = (
+      await vi.importActual<typeof import("node:fs/promises")>("node:fs/promises")
+    ).readFile;
+    let changed = false;
+    vi.spyOn(fs, "readFile").mockImplementation(async (...args: Parameters<typeof fs.readFile>) => {
+      const bytes = await actualRead(...args);
+      if (!changed && String(args[0]) === join(root, source)) {
+        changed = true;
+        await fs.writeFile(join(root, source), record(3) + "changed length\n");
+      }
+      return bytes;
+    });
+    const result = await cache.read(join(root, source), source);
+    expect(cache.reads).toBe(2);
+    expect(result?.entry.revision[1]).toBe(3);
+  });
+
+  it("treats malformed cache as disposable and prunes origins no longer duplicated", async () => {
+    const root = await fixture();
+    const peer = await fixture();
+    vi.spyOn(Date, "now").mockReturnValue(Date.now() + 10_000);
+    const options = { sourceRoots: [root, peer] };
+    await sourceFingerprint(root, options);
+    const path = join(root, ".local/cache/dashboard-canonical-revisions-v1.json");
+    await fs.writeFile(path, "not JSON");
+    expect((await sourceFingerprint(root, options)).duplicateReads).toBe(2);
+    await fs.rm(join(peer, source));
+    await sourceFingerprint(root, options);
+    expect(JSON.parse(await fs.readFile(path, "utf8")).entries).toEqual([]);
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/canonical-source-revision-cache.ts

@@ -0,0 +1,168 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { BigIntStats } from "node:fs";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+type Revision = [string, number, number];
+type Entry = { metadata: string; revision: Revision; contentHash: string; settled: boolean };
+// Covers the observed 12,712 logical sources across ten registered roots.
+const maxEntries = 200_000;
+const maxBytes = 128 * 1024 * 1024;
+
+function identity(value: BigIntStats): string {
+  return [value.dev, value.ino, value.birthtimeNs, value.mtimeNs, value.ctimeNs, value.size].join(
+    ":",
+  );
+}
+
+function revision(content: string, source: string): Revision {
+  if (source.endsWith(".jsonl")) {
+    const dates = [...content.matchAll(/"occurred_at"\s*:\s*"([^"]+)"/gu)];
+    return [
+      dates.reduce((last, match) => ((match[1] ?? "") > last ? match[1]! : last), ""),
+      dates.length,
+      content.length,
+    ];
+  }
+  const updated = /^updated_at:\s*([^\r\n]+)/mu.exec(content)?.[1]?.trim() ?? "";
+  const created = /^created_at:\s*([^\r\n]+)/mu.exec(content)?.[1]?.trim() ?? "";
+  return [
+    updated || created,
+    Number(/^revision:\s*(\d+)/mu.exec(content)?.[1] ?? 0),
+    content.length,
+  ];
+}
+
+function validEntry(value: unknown): value is Entry {
+  if (!value || typeof value !== "object") return false;
+  const item = value as Entry;
+  return (
+    typeof item.metadata === "string" &&
+    /^\d+(?::\d+){5}$/u.test(item.metadata) &&
+    typeof item.contentHash === "string" &&
+    /^[a-f0-9]{64}$/u.test(item.contentHash) &&
+    typeof item.settled === "boolean" &&
+    Array.isArray(item.revision) &&
+    item.revision.length === 3 &&
+    typeof item.revision[0] === "string" &&
+    item.revision[0].length <= 256 &&
+    Number.isSafeInteger(item.revision[1]) &&
+    item.revision[1] >= 0 &&
+    Number.isSafeInteger(item.revision[2]) &&
+    item.revision[2] >= 0
+  );
+}
+
+/** Disposable local optimization, never a canonical record or a replacement for inventory. */
+export class CanonicalSourceRevisionCache {
+  private readonly entries = new Map<string, Entry>();
+  private readonly seen = new Set<string>();
+  private dirty = false;
+  reads = 0;
+  reused = 0;
+  private constructor(
+    private readonly path: string,
+    private readonly verify: boolean,
+  ) {}
+
+  static async open(workspaceRoot: string, verify = false): Promise<CanonicalSourceRevisionCache> {
+    const cache = new CanonicalSourceRevisionCache(
+      resolve(workspaceRoot, ".local/cache/dashboard-canonical-revisions-v1.json"),
+      verify,
+    );
+    if (verify) return cache;
+    try {
+      if ((await stat(cache.path)).size > maxBytes) return cache;
+      const data = JSON.parse(await readFile(cache.path, "utf8")) as {
+        version?: unknown;
+        entries?: unknown;
+      };
+      if (data.version !== 1 || !Array.isArray(data.entries) || data.entries.length > maxEntries)
+        return cache;
+      for (const row of data.entries) {
+        if (
+          !Array.isArray(row) ||
+          row.length !== 2 ||
+          typeof row[0] !== "string" ||
+          row[0].length > 4096 ||
+          !validEntry(row[1])
+        )
+          continue;
+        cache.entries.set(row[0], row[1]);
+      }
+    } catch {
+      /* Missing or invalid cache means reread, never failed freshness. */
+    }
+    return cache;
+  }
+
+  async read(
+    path: string,
+    source: string,
+  ): Promise<{ entry: Entry; metadata: BigIntStats; reused: boolean } | null> {
+    const origin = resolve(path);
+    if (this.seen.size < maxEntries) this.seen.add(origin);
+    try {
+      for (let attempt = 0; attempt < 3; attempt += 1) {
+        const before = await stat(origin, { bigint: true });
+        const key = identity(before);
+        const settled = Date.now() - Number(before.ctimeMs) > 2_000;
+        const previous = this.entries.get(origin);
+        if (!this.verify && settled && previous?.settled && previous.metadata === key) {
+          this.reused += 1;
+          return { entry: previous, metadata: before, reused: true };
+        }
+        const bytes = await readFile(origin);
+        this.reads += 1;
+        if (identity(await stat(origin, { bigint: true })) !== key) continue;
+        const entry: Entry = {
+          metadata: key,
+          settled,
+          revision: revision(bytes.toString("utf8"), source),
+          contentHash: createHash("sha256").update(bytes).digest("hex"),
+        };
+        if (
+          !this.verify &&
+          this.seen.has(origin) &&
+          (this.entries.has(origin) || this.entries.size < maxEntries)
+        ) {
+          this.entries.set(origin, entry);
+          this.dirty = true;
+        }
+        return { entry, metadata: before, reused: false };
+      }
+      throw new Error(`Canonical source changed repeatedly during revision selection: ${source}`);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        this.entries.delete(origin);
+        this.dirty = true;
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async persist(): Promise<void> {
+    if (this.verify) return;
+    for (const origin of this.entries.keys()) {
+      if (!this.seen.has(origin)) {
+        this.entries.delete(origin);
+        this.dirty = true;
+      }
+    }
+    if (!this.dirty) return;
+    const retained = [...this.entries].slice(-maxEntries);
+    const data = JSON.stringify({ version: 1, entries: retained });
+    if (Buffer.byteLength(data) > maxBytes) return;
+    const temporary = `${this.path}.${randomUUID()}.tmp`;
+    try {
+      await mkdir(dirname(this.path), { recursive: true });
+      await writeFile(temporary, data, { flag: "wx" });
+      await rename(temporary, this.path);
+    } catch {
+      /* Cache persistence must never prevent canonical verification. */
+    } finally {
+      await rm(temporary, { force: true }).catch(() => undefined);
+    }
+  }
+}

package/templates/.agents/dashboard/packages/local-runtime/src/dashboard-diagnostics.test.ts

@@ -0,0 +1,57 @@
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { WorkspaceFileSystem } from "@zaip-ai/core";
+import { afterEach, describe, expect, it } from "vitest";
+import { reconcileOpenWork } from "./server-workspace.js";
+
+const roots: string[] = [];
+async function fixture(script: string) {
+  const base = resolve(import.meta.dirname, "../../../../../../.tmp/dashboard-cli-diagnostics");
+  await mkdir(base, { recursive: true });
+  const root = await mkdtemp(join(base, "fixture-"));
+  roots.push(root);
+  await mkdir(join(root, ".agents/runtime/bin"), { recursive: true });
+  await writeFile(join(root, ".agents/runtime/bin/zaip.mjs"), script);
+  return root;
+}
+async function logs(root: string) {
+  const directory = join(root, ".local/dashboard-logs");
+  return (
+    await Promise.all(
+      (await readdir(directory)).map((name) => readFile(join(directory, name), "utf8")),
+    )
+  ).join("");
+}
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+describe("reconciliation CLI diagnostics", () => {
+  it("persists real CLI stdout and stderr plus structured outcomes with job correlation", async () => {
+    const root = await fixture(
+      'process.stderr.write("diagnostic warning\\n"); process.stdout.write(JSON.stringify({ runs: [{run:{run_id:"RUN-X"},status:"failed",finished:{status:"failed"}}] }));',
+    );
+    const result = await reconcileOpenWork(new WorkspaceFileSystem(root), root, {
+      jobId: "JOB-REAL",
+    });
+    expect(result.outcomes).toEqual([{ id: "RUN-X", status: "failed", reason: null }]);
+    const content = await logs(root);
+    expect(content).toContain('"job_id":"JOB-REAL"');
+    expect(content).toContain("diagnostic warning");
+    expect(content).toContain("cli_completed");
+  });
+  it("retains failed CLI diagnostics and redacts secrets from stderr", async () => {
+    const root = await fixture(
+      'process.stderr.write("Bearer sensitive password=private\\n"); process.exit(2);',
+    );
+    await expect(reconcileOpenWork(new WorkspaceFileSystem(root), root)).rejects.toThrow();
+    const content = await logs(root);
+    expect(content).toContain("cli_error");
+    expect(content).not.toMatch(/sensitive|private/);
+    expect(content).toContain("[redacted]");
+  });
+  it("reports invalid CLI JSON as failure with retained output", async () => {
+    const root = await fixture('process.stdout.write("invalid-json");');
+    await expect(reconcileOpenWork(new WorkspaceFileSystem(root), root)).rejects.toThrow();
+    expect(await logs(root)).toContain("cli_invalid_result");
+  });
+});