@zaip-ai/cli 1.3.7 → 1.4.1

package/templates/.agents/dashboard/packages/local-runtime/src/server-browser-lease.ts

@@ -0,0 +1,33 @@
+import type { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+
+export function registerBrowserLeaseRoute(
+  app: Hono,
+  apiPrefix: string,
+  launcherOwned = false,
+): void {
+  const browserLeases = new Set<object>();
+  let browserLeaseDeadline: NodeJS.Timeout | undefined;
+  if (launcherOwned) {
+    browserLeaseDeadline = setTimeout(() => process.exit(0), 12_000);
+    browserLeaseDeadline.unref();
+  }
+  const releaseBrowserLease = (lease: object) => {
+    browserLeases.delete(lease);
+    if (!launcherOwned || browserLeases.size !== 0) return;
+    if (browserLeaseDeadline !== undefined) clearTimeout(browserLeaseDeadline);
+    browserLeaseDeadline = setTimeout(() => process.exit(0), 12_000);
+    browserLeaseDeadline.unref();
+  };
+  app.get(`${apiPrefix}/browser-lease`, (context) => {
+    const lease = {};
+    if (browserLeaseDeadline !== undefined) clearTimeout(browserLeaseDeadline);
+    browserLeaseDeadline = undefined;
+    browserLeases.add(lease);
+    return streamSSE(context, async (stream) => {
+      stream.onAbort(() => releaseBrowserLease(lease));
+      await stream.writeSSE({ event: "lease", data: "active" });
+      await new Promise(() => {});
+    });
+  });
+}

package/templates/.agents/dashboard/packages/local-runtime/src/server-reconciliation-refresh.test.ts

@@ -1,12 +1,96 @@
-import { resolve } from "node:path";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { WorkspaceFileSystem, type WorkspaceLayout } from "@zaip-ai/core";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { createDashboardApp, reconciliationNeedsRefresh } from "./server.js";
+import { ReconciliationCommandTimeoutError, reconciliationResult } from "./server-workspace.js";
+import { rebuildSqliteReadModel, SqliteReadModelFileSystem } from "./sqlite-read-model.js";
 
 const workspaceRoot = resolve(import.meta.dirname, "../../../../..");
 const v2Layout = { version: 3 } as WorkspaceLayout;
+const fixtureRoots: string[] = [];
+const fixtureBase = join(workspaceRoot, ".tmp", "server-reconciliation-refresh-tests");
+
+async function createSqliteFixture(): Promise<string> {
+  await mkdir(fixtureBase, { recursive: true });
+  const root = await mkdtemp(join(fixtureBase, "fixture-"));
+  fixtureRoots.push(root);
+  await mkdir(join(root, ".agents", "config"), { recursive: true });
+  await Promise.all([
+    readFile(join(workspaceRoot, ".agents", "config", "project.yaml"), "utf8").then((content) =>
+      writeFile(join(root, ".agents", "config", "project.yaml"), content),
+    ),
+    readFile(join(workspaceRoot, ".agents", "config", "framework.lock.yaml"), "utf8").then(
+      (content) => writeFile(join(root, ".agents", "config", "framework.lock.yaml"), content),
+    ),
+  ]);
+  await rebuildSqliteReadModel(root);
+  return root;
+}
+
+afterEach(async () => {
+  await Promise.all(
+    fixtureRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
+  );
+});
 
 describe("reconciliation snapshot refresh", () => {
+  it("publishes a stable readiness revision and changes it after a status-only snapshot commit", async () => {
+    const fixtureRoot = await createSqliteFixture();
+    const taskPath = join(fixtureRoot, ".agents/records/tasks/TASK-REVISION.md");
+    await mkdir(join(fixtureRoot, ".agents/records/tasks"), { recursive: true });
+    const task = (status: string) => `---
+schema_version: 2
+id: TASK-REVISION
+title: Snapshot status revision
+status: ${status}
+created_at: 2026-09-05T10:00:00.000Z
+---
+# Task
+`;
+    await writeFile(taskPath, task("executing"));
+    await rebuildSqliteReadModel(fixtureRoot);
+    const filesystem = new SqliteReadModelFileSystem(fixtureRoot);
+    const refresh = vi.fn(async () => undefined);
+    const app = createDashboardApp(fixtureRoot, "test-session", undefined, {
+      snapshotReadOnly: true,
+      filesystem,
+      refreshReadModel: refresh,
+      layout: v2Layout,
+    });
+    const ready = async () => {
+      const response = await app.request("/api/v2/ready", {
+        headers: { "x-zaip-session": "test-session" },
+      });
+      expect(response.status).toBe(200);
+      return response.json() as Promise<{
+        snapshot_revision: string;
+        activity_count: number;
+        day_count: number;
+      }>;
+    };
+    try {
+      const before = await ready();
+      expect(before.snapshot_revision).toMatch(/^[a-f0-9]{64}$/);
+      await expect(ready()).resolves.toEqual(before);
+      await writeFile(taskPath, task("completed"));
+      // Canonical edits do not pretend that the opened snapshot was promoted.
+      await expect(ready()).resolves.toEqual(before);
+      // Use the production refresh boundary, which releases Windows readers
+      // before replacing an older snapshot generation.
+      await filesystem.rebuildAndRefresh(() => rebuildSqliteReadModel(fixtureRoot));
+      const after = await ready();
+      expect(after.snapshot_revision).not.toBe(before.snapshot_revision);
+      expect(after.activity_count).toBe(before.activity_count);
+      expect(after.day_count).toBe(before.day_count);
+      await filesystem.rebuildAndRefresh(() => rebuildSqliteReadModel(fixtureRoot));
+      await expect(ready()).resolves.toEqual(after);
+      expect(refresh).not.toHaveBeenCalled();
+    } finally {
+      filesystem.close();
+    }
+  });
+
   it("refreshes only when reconciliation changed canonical work", () => {
     expect(
       reconciliationNeedsRefresh({ reconciled_ids: [], blocked: [], not_reconciled: [] }),
@@ -25,9 +109,35 @@ describe("reconciliation snapshot refresh", () => {
         not_reconciled: [],
       }),
     ).toBe(true);
+    expect(
+      reconciliationNeedsRefresh(
+        reconciliationResult({
+          reconciliations: [
+            {
+              status: "closed",
+              specs: [{ id: "SPEC-DELIVERED", status: "delivered" }],
+              prds: [{ id: "PRD-DELIVERED", status: "delivered" }],
+            },
+          ],
+        }),
+      ),
+    ).toBe(true);
   });
 
-  it("serves health while a changed reconciliation refreshes in a worker", async () => {
+  it("reports a closed Run as a snapshot-changing reconciliation without a Task graph", () => {
+    expect(
+      reconciliationNeedsRefresh(
+        reconciliationResult({
+          runs: [{ run: { run_id: "RUN-CONVERSATION-CLOSED" } }],
+          reconciliations: [],
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("returns a compact receipt while a changed reconciliation refreshes in a worker", async () => {
+    const fixtureRoot = await createSqliteFixture();
+    const filesystem = new SqliteReadModelFileSystem(fixtureRoot);
     let rejectRefresh: ((error: Error) => void) | undefined;
     const refresh = vi.fn(
       () =>
@@ -35,9 +145,10 @@ describe("reconciliation snapshot refresh", () => {
           rejectRefresh = reject;
         }),
     );
-    const app = createDashboardApp(workspaceRoot, "test-session", undefined, {
+    const app = createDashboardApp(fixtureRoot, "test-session", undefined, {
       snapshotReadOnly: true,
-      canonicalFilesystem: new WorkspaceFileSystem(workspaceRoot),
+      filesystem,
+      canonicalFilesystem: new WorkspaceFileSystem(fixtureRoot),
       reconcileOpenWork: async () => ({
         reconciled_ids: ["TASK-CHANGED"],
         blocked: [],
@@ -50,17 +161,43 @@ describe("reconciliation snapshot refresh", () => {
       method: "POST",
       headers: { "x-zaip-session": "test-session" },
     });
+    const response = await reconciliation;
+    expect(response.status, await response.clone().text()).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({
+      snapshot_state: "updating",
+      projection_refresh_completed: false,
+      reconciliation: { reconciled_ids: ["TASK-CHANGED"] },
+    });
     await vi.waitFor(() => expect(refresh).toHaveBeenCalledOnce());
     await expect(
       app.request("/api/v2/health", { headers: { "x-zaip-session": "test-session" } }),
-    ).resolves.toMatchObject({
-      status: 200,
-    });
+    ).resolves.toMatchObject({ status: 200 });
     rejectRefresh?.(new Error("simulated worker refresh failure"));
-    const response = await reconciliation;
-    expect(response.status).toBe(400);
+    await vi.waitFor(() => expect(refresh).toHaveBeenCalledOnce());
+    filesystem.close();
+  });
+
+  it("returns a finite partial-reconciliation error and refreshes the projection", async () => {
+    const refresh = vi.fn(async () => undefined);
+    const app = createDashboardApp(workspaceRoot, "test-session", undefined, {
+      snapshotReadOnly: true,
+      canonicalFilesystem: new WorkspaceFileSystem(workspaceRoot),
+      reconcileOpenWork: async () => {
+        throw new ReconciliationCommandTimeoutError();
+      },
+      refreshReadModel: refresh,
+      layout: v2Layout,
+    });
+
+    const response = await app.request("/api/v2/reconcile-open-work", {
+      method: "POST",
+      headers: { "x-zaip-session": "test-session" },
+    });
+    expect(response.status).toBe(408);
     await expect(response.json()).resolves.toMatchObject({
-      error: "simulated worker refresh failure",
+      reconciliation_may_be_partial: true,
+      projection_refresh_started: true,
     });
+    await vi.waitFor(() => expect(refresh).toHaveBeenCalledOnce());
   });
 });

package/templates/.agents/dashboard/packages/local-runtime/src/server-reconciliation-result.test.ts

@@ -0,0 +1,68 @@
+import type { WorkspaceFileSystem } from "@zaip-ai/core";
+import { describe, expect, it, vi } from "vitest";
+import { reconcileOpenWork, reconciliationResult } from "./server-workspace.js";
+
+describe("manual reconciliation report", () => {
+  it("reports delivered SPECs and PRDs even when no Task or Run changed", () => {
+    expect(
+      reconciliationResult({
+        reconciliations: [
+          {
+            status: "closed",
+            specs: [{ id: "SPEC-DONE", status: "delivered" }],
+            prds: [{ id: "PRD-DONE", status: "delivered" }],
+          },
+        ],
+      }),
+    ).toEqual({ reconciled_ids: ["PRD-DONE", "SPEC-DONE"], blocked: [], not_reconciled: [] });
+  });
+
+  it("reports the canonical owners of an orphan with their persisted blocking reasons", () => {
+    expect(
+      reconciliationResult({
+        orphaned_executions: ["EXEC-ORPHAN"],
+        orphaned_execution_entities: [
+          {
+            id: "EXEC-ORPHAN",
+            status: "blocked",
+            status_reason: "Host terminated without delivery evidence.",
+          },
+        ],
+        orphaned_owner_entities: [
+          { id: "TASK-ORPHAN", status: "blocked", status_reason: "Host interrupted." },
+          { id: "SPEC-ORPHAN", status: "blocked", status_reason: "Child attempt stopped." },
+          { id: "PRD-ORPHAN", status: "blocked", status_reason: "Child attempt stopped." },
+        ],
+        unresolved_running_run_ids: ["RUN-LIVE"],
+      }),
+    ).toEqual({
+      reconciled_ids: ["EXEC-ORPHAN", "PRD-ORPHAN", "SPEC-ORPHAN", "TASK-ORPHAN"],
+      blocked: [
+        { id: "EXEC-ORPHAN", reason: "Host terminated without delivery evidence." },
+        { id: "PRD-ORPHAN", reason: "Child attempt stopped." },
+        { id: "SPEC-ORPHAN", reason: "Child attempt stopped." },
+        { id: "TASK-ORPHAN", reason: "Host interrupted." },
+      ],
+      not_reconciled: [{ id: "RUN-LIVE", reason: "Invocation is still running." }],
+    });
+  });
+
+  it("does not advertise untouched draft, ready or active entities as reconciled", () => {
+    expect(
+      reconciliationResult({
+        orphaned_owner_entities: [
+          { id: "PRD-DRAFT", status: "draft" },
+          { id: "SPEC-READY", status: "ready" },
+          { id: "TASK-LIVE", status: "executing" },
+        ],
+      }),
+    ).toEqual({ reconciled_ids: [], blocked: [], not_reconciled: [] });
+  });
+
+  it("reports unavailable reconciliation instead of returning a successful empty result", async () => {
+    const filesystem = { exists: vi.fn(async () => false) } as unknown as WorkspaceFileSystem;
+    await expect(reconcileOpenWork(filesystem, "test-workspace")).rejects.toThrow(
+      "could not be reconciled",
+    );
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/server-snapshot-refresh.test.ts

@@ -0,0 +1,19 @@
+import { EventEmitter } from "node:events";
+import { describe, expect, it } from "vitest";
+import { attachRefreshWorkerCleanup } from "./server-snapshot-refresh.js";
+
+describe("snapshot refresh shutdown", () => {
+  it("terminates an active refresh worker on runtime shutdown and removes its listener on completion", () => {
+    const processRef = new EventEmitter();
+    const calls: string[] = [];
+    const cleanup = attachRefreshWorkerCleanup(
+      { kill: (signal) => (calls.push(String(signal)), true) },
+      processRef,
+    );
+    processRef.emit("exit");
+    expect(calls).toEqual(["SIGTERM"]);
+    cleanup();
+    processRef.emit("exit");
+    expect(calls).toEqual(["SIGTERM"]);
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/server-snapshot-refresh.ts

@@ -1,25 +1,13 @@
 import { spawn } from "node:child_process";
-import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
-import { rm } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { resolve } from "node:path";
 import {
   type SqliteReadModelFileSystem,
   sqliteReadModelPath,
   validateSqliteReadModelSchema,
 } from "./sqlite-read-model.js";
-import { activateStagedSqliteSnapshot, stageSqliteSnapshot } from "./sqlite-snapshot-install.js";
 
-/** Rebuilds an isolated SQLite generation so the serving event loop stays available. */
-export async function rebuildSnapshotInWorker(workspaceRoot: string, currentPath: string) {
-  const target = resolve(
-    dirname(currentPath),
-    `refresh-server-${process.pid}-${randomBytes(4).toString("hex")}.sqlite`,
-  );
-  // A temporary/canonical workspace contains data, not necessarily a second
-  // dashboard runtime checkout. The explicit candidates work for a launcher
-  // opened at the workspace root and for fixture tests launched from the
-  // runtime's source checkout, without relying on import.meta in the CJS build.
+async function rebuildPersistentDatabaseInWorker(workspaceRoot: string, destination: string) {
   const scriptCandidates = [
     resolve(
       workspaceRoot,
@@ -40,58 +28,66 @@ export async function rebuildSnapshotInWorker(workspaceRoot: string, currentPath
       cwd: workspaceRoot,
       env: {
         ...process.env,
-        // The script prioritizes ZAIP_WORKSPACE over cwd. Do not inherit a
-        // launcher's root when this refresh was requested for another
-        // canonical workspace (notably an isolated test fixture).
         ZAIP_WORKSPACE: workspaceRoot,
-        ZAIP_SQLITE_DB_PATH: target,
+        ZAIP_SQLITE_DB_PATH: destination,
         ZAIP_SQLITE_PREFER_LAST_VALID_SEED: "0",
         ZAIP_DASHBOARD_LAUNCH_PROGRESS: "0",
       },
       stdio: ["ignore", "ignore", "pipe"],
       windowsHide: true,
     });
+    // Lease shutdown may end the serving parent while a slow snapshot rebuild
+    // is still writing. Terminate the direct child synchronously during parent
+    // exit so the next launcher cannot overlap the persistent SQLite writer.
+    const cleanupWorker = attachRefreshWorkerCleanup(worker);
     worker.stderr?.setEncoding("utf8");
     worker.stderr?.on("data", (chunk: string) => {
-      stderr += chunk;
+      stderr = `${stderr}${chunk}`.slice(-8_000);
     });
-    worker.once("error", rejectWorker);
-    worker.once("exit", (code) =>
-      code === 0
+    worker.once("error", (error) => {
+      cleanupWorker();
+      rejectWorker(error);
+    });
+    worker.once("exit", (code) => {
+      cleanupWorker();
+      return code === 0
         ? resolveWorker()
         : rejectWorker(
             new Error(`SQLite refresh worker failed (${code}): ${stderr.trim() || "no stderr"}`),
-          ),
-    );
+          );
+    });
   });
-  return target;
 }
 
-export async function removeRefreshSnapshot(path: string) {
-  await rm(path, { force: true }).catch(() => {});
+export function attachRefreshWorkerCleanup(
+  worker: { kill(signal?: NodeJS.Signals): boolean },
+  processRef: {
+    once(event: string, listener: () => void): unknown;
+    removeListener(event: string, listener: () => void): unknown;
+  } = process,
+): () => void {
+  const stopWorkerOnParentExit = () => {
+    try {
+      worker.kill("SIGTERM");
+    } catch {
+      /* already terminal */
+    }
+  };
+  processRef.once("exit", stopWorkerOnParentExit);
+  return () => processRef.removeListener("exit", stopWorkerOnParentExit);
 }
 
 /**
- * Builds and validates a replacement outside the serving process, then asks
- * the read-model filesystem to perform only the short close/rename/reopen
- * handoff. The current immutable generation remains readable while staging.
+ * The child process writes the single persistent database in place. WAL keeps
+ * the server reader usable until the worker commits; no staged SQLite file is
+ * created. On an error the worker rolls back and this reader stays untouched.
  */
 export async function refreshSqliteSnapshotInWorker(
   workspaceRoot: string,
   filesystem: SqliteReadModelFileSystem,
 ) {
   const destination = sqliteReadModelPath(workspaceRoot);
-  const refreshedPath = await rebuildSnapshotInWorker(workspaceRoot, destination);
-  try {
-    const stagedPath = await stageSqliteSnapshot(
-      refreshedPath,
-      destination,
-      validateSqliteReadModelSchema,
-    );
-    await filesystem.rebuildAndRefresh(async () => {
-      activateStagedSqliteSnapshot(stagedPath, destination);
-    });
-  } finally {
-    await removeRefreshSnapshot(refreshedPath);
-  }
+  await rebuildPersistentDatabaseInWorker(workspaceRoot, destination);
+  validateSqliteReadModelSchema(destination);
+  filesystem.refresh();
 }

package/templates/.agents/dashboard/packages/local-runtime/src/server-snapshot-revision.test.ts

@@ -0,0 +1,42 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { expect, it } from "vitest";
+import { readCommittedSnapshotRevision } from "./server-snapshot-revision.js";
+import { sqliteReadModelPath } from "./sqlite-read-model.js";
+
+it("publishes only committed metadata, preserving the revision through a rolled-back write", async () => {
+  const base = resolve(tmpdir());
+  const root = await mkdtemp(join(base, "zaip-revision-"));
+  if (!resolve(root).startsWith(base + sep))
+    throw new Error("Fixture cleanup outside temporary directory");
+  const databasePath = sqliteReadModelPath(root);
+  await mkdir(dirname(databasePath), { recursive: true });
+  const writer = new DatabaseSync(databasePath);
+  try {
+    writer.exec(`
+      PRAGMA journal_mode=WAL;
+      CREATE TABLE read_model_metadata (key TEXT PRIMARY KEY, value TEXT);
+      CREATE VIEW zaip_vw_read_model_metadata AS SELECT * FROM read_model_metadata;
+      INSERT INTO read_model_metadata VALUES ('schema_version', '1'), ('source_fingerprint', 'first');
+    `);
+    const original = readCommittedSnapshotRevision(root);
+    expect(original).toMatch(/^[a-f0-9]{64}$/);
+    writer.exec(
+      "BEGIN IMMEDIATE; UPDATE read_model_metadata SET value='second' WHERE key='source_fingerprint';",
+    );
+    expect(readCommittedSnapshotRevision(root)).toBe(original);
+    writer.exec("ROLLBACK;");
+    expect(readCommittedSnapshotRevision(root)).toBe(original);
+    writer.exec(
+      "BEGIN IMMEDIATE; UPDATE read_model_metadata SET value='second' WHERE key='source_fingerprint'; COMMIT;",
+    );
+    const committed = readCommittedSnapshotRevision(root);
+    expect(committed).not.toBe(original);
+    expect(readCommittedSnapshotRevision(root)).toBe(committed);
+  } finally {
+    writer.close();
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/templates/.agents/dashboard/packages/local-runtime/src/server-snapshot-revision.ts

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { sqliteReadModelPath } from "./sqlite-read-model.js";
+
+/** Read committed inputs only. Canonical edits and rolled-back writes cannot advance the revision. */
+export function readCommittedSnapshotRevision(workspaceRoot: string): string {
+  const database = new DatabaseSync(sqliteReadModelPath(workspaceRoot), { readOnly: true });
+  try {
+    const rows = database
+      .prepare(
+        "SELECT key, value FROM zaip_vw_read_model_metadata WHERE key IN ('schema_version', 'source_fingerprint')",
+      )
+      .all() as Array<{ key: string; value: string }>;
+    const metadata = new Map(rows.map((row) => [row.key, row.value]));
+    if (!metadata.has("schema_version") || !metadata.has("source_fingerprint")) {
+      throw new Error("Committed SQLite snapshot metadata is incomplete");
+    }
+    return createHash("sha256")
+      .update(metadata.get("schema_version") as string)
+      .update(":")
+      .update(metadata.get("source_fingerprint") as string)
+      .digest("hex");
+  } finally {
+    database.close();
+  }
+}

package/templates/.agents/dashboard/packages/local-runtime/src/server-snapshot-synchronization.ts

@@ -0,0 +1,34 @@
+import { watch } from "node:fs";
+import { join } from "node:path";
+
+export function startSnapshotSynchronization(input: {
+  workspaceRoot: string;
+  staleSeed: boolean;
+  watchSources: boolean;
+  refresh: () => Promise<void>;
+}): void {
+  if (input.staleSeed) void input.refresh().catch(() => undefined);
+  if (!input.watchSources || process.env.ZAIP_DASHBOARD_WATCH_SOURCES === "0") return;
+  let pendingRefresh: NodeJS.Timeout | undefined;
+  const scheduleRefresh = () => {
+    if (pendingRefresh !== undefined) clearTimeout(pendingRefresh);
+    pendingRefresh = setTimeout(() => {
+      pendingRefresh = undefined;
+      void input.refresh().catch(() => undefined);
+    }, 300);
+    pendingRefresh.unref();
+  };
+  for (const sourceRoot of [
+    join(input.workspaceRoot, ".agents", "records"),
+    join(input.workspaceRoot, ".agents", "config"),
+  ]) {
+    try {
+      const watcher = watch(sourceRoot, { recursive: true }, scheduleRefresh);
+      watcher.unref();
+    } catch {
+      // Reuse-triggered refresh remains the portable fallback.
+    }
+  }
+  const freshnessTimer = setInterval(scheduleRefresh, 60_000);
+  freshnessTimer.unref();
+}

package/templates/.agents/dashboard/packages/local-runtime/src/server-startup.ts

@@ -0,0 +1,30 @@
+import type { rebuildSqliteReadModel } from "./sqlite-read-model.js";
+
+export function writeStartupPhase(startedAt: number, phase: string): void {
+  process.stderr.write(
+    `${JSON.stringify({
+      event: "dashboard_sqlite_startup_phase",
+      phase,
+      elapsed_ms: Math.round(performance.now() - startedAt),
+    })}\n`,
+  );
+}
+
+export function writeReadModelStartup(
+  startedAt: number,
+  readModel: Awaited<ReturnType<typeof rebuildSqliteReadModel>>,
+): void {
+  // The parent launcher captures stderr even when stdout is intentionally
+  // hidden. This makes seed hit/miss and private-copy cost observable without
+  // exposing a shared handle or workspace payload.
+  process.stderr.write(
+    `${JSON.stringify({
+      event: "dashboard_sqlite_read_model",
+      elapsed_ms: Math.round(performance.now() - startedAt),
+      cache: readModel.cache,
+      fingerprint_ms: readModel.fingerprint_ms,
+      materialize_ms: readModel.materialize_ms,
+      source_files: readModel.files,
+    })}\n`,
+  );
+}

package/templates/.agents/dashboard/packages/local-runtime/src/server-work-reconciliation.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createWorkReconciliation,
+  startHostTerminalReconciliation,
+  waitForWorkReconciliation,
+} from "./server-work-reconciliation.js";
+import { type ReconciliationResult, reconciliationCommandTimeoutMs } from "./server-workspace.js";
+
+const clean: ReconciliationResult = { reconciled_ids: [], blocked: [], not_reconciled: [] };
+const changed: ReconciliationResult = {
+  ...clean,
+  reconciled_ids: ["TASK-TERMINAL", "SPEC-DELIVERED", "PRD-DELIVERED"],
+};
+afterEach(() => vi.useRealTimers());
+
+describe("canonical host recovery", () => {
+  it("serializes manual recovery after host-only work and deduplicates concurrent clicks", async () => {
+    let release!: (value: ReconciliationResult) => void;
+    const first = new Promise<ReconciliationResult>((resolve) => {
+      release = resolve;
+    });
+    const reconcile = vi.fn().mockReturnValueOnce(first).mockResolvedValue(changed);
+    const refresh = vi.fn().mockResolvedValue(undefined);
+    const run = createWorkReconciliation({ reconcile, refresh });
+    const automatic = run("host-terminal");
+    await Promise.resolve();
+    const manual = run("manual");
+    expect(run("manual")).toBe(manual);
+    expect(run("host-terminal")).toBe(manual);
+    expect(reconcile.mock.calls).toEqual([["host-terminal"]]);
+    release(clean);
+    await automatic;
+    await expect(manual).resolves.toEqual(changed);
+    expect(reconcile.mock.calls).toEqual([["host-terminal"], ["manual"]]);
+    expect(refresh).toHaveBeenCalledOnce();
+  });
+
+  it("promotes partial changes after a failure and allows the next attempt", async () => {
+    const reconcile = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("writer interrupted"))
+      .mockResolvedValue(clean);
+    const refresh = vi.fn().mockResolvedValue(undefined);
+    const run = createWorkReconciliation({ reconcile, refresh });
+    await expect(run("manual")).rejects.toThrow("writer interrupted");
+    await expect(run("manual")).resolves.toEqual(clean);
+    expect(refresh).toHaveBeenCalledOnce();
+  });
+
+  it("recovers at startup and retries after failure without overlapping work", async () => {
+    vi.useFakeTimers();
+    let release!: () => void;
+    const reconcile = vi
+      .fn()
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            release = resolve;
+          }),
+      )
+      .mockRejectedValueOnce(new Error("busy"))
+      .mockResolvedValue(undefined);
+    const stop = startHostTerminalReconciliation(reconcile);
+    await vi.advanceTimersByTimeAsync(1_000);
+    await vi.advanceTimersByTimeAsync(90_000);
+    expect(reconcile).toHaveBeenCalledOnce();
+    release();
+    await vi.advanceTimersByTimeAsync(30_000);
+    expect(reconcile).toHaveBeenCalledTimes(2);
+    await vi.advanceTimersByTimeAsync(30_000);
+    expect(reconcile).toHaveBeenCalledTimes(3);
+    stop();
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(reconcile).toHaveBeenCalledTimes(3);
+  });
+
+  it("bounds total request time even while the canonical writer is queued", async () => {
+    vi.useFakeTimers();
+    let release!: (value: ReconciliationResult) => void;
+    const pending = new Promise<ReconciliationResult>((resolve) => {
+      release = resolve;
+    });
+    const bounded = expect(waitForWorkReconciliation(pending)).rejects.toThrow("exceeded");
+    await vi.advanceTimersByTimeAsync(reconciliationCommandTimeoutMs);
+    await bounded;
+    release(changed);
+    await expect(pending).resolves.toEqual(changed);
+  });
+});