@zaip-ai/cli 4.5.0 → 4.6.0

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

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { basename, resolve } from "node:path";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
@@ -6,24 +6,20 @@ import { WorkspaceFileSystem, type WorkspaceLayout } from "@zaip-ai/core";
 import { fxRateSchema, PricingRepository, pricingCatalogSchema } from "@zaip-ai/costs";
 import { type Context, Hono } from "hono";
 import { getCookie, setCookie } from "hono/cookie";
+import { createDashboardDiagnostics } from "../dashboard-diagnostics.mjs";
 import {
   type ActiveCodexTelemetryCapture,
   captureRepositoryActiveCodexTelemetry,
 } from "./active-codex-telemetry.js";
 import { runAgentAdapterSync } from "./agent-adapter-sync.js";
-import {
-  type AgentAdapterSyncResult,
-  AgentCatalogUpdateError,
-  persistAgentCatalogUpdate,
-  readAgentCatalogSettings,
-} from "./agent-catalog-settings.js";
+import type { AgentAdapterSyncResult } from "./agent-catalog-settings.js";
 import {
   persistProjectSettings,
   readProjectOverview,
   readProjectSettings,
 } from "./project-settings.js";
 import { createProjectionRefreshDiagnostics } from "./projection-refresh-diagnostics.js";
-import { agentPortraitFiles } from "./server-agent-assets.js";
+import { registerAgentCatalogRoutes } from "./server-agent-catalog-routes.js";
 import { registerBrowserLeaseRoute } from "./server-browser-lease.js";
 import { registerCostsRoutes } from "./server-costs-routes.js";
 import {
@@ -36,12 +32,17 @@ import { lifecycleManifestState } from "./server-lifecycle-diagnostics.js";
 import { registerOperationsRoutes } from "./server-operations-routes.js";
 import { projectionPeriodFilter } from "./server-period.js";
 import { buildFirstFoldQuickProjection, dashboardSnapshot } from "./server-read-projections.js";
+import {
+  createLoggedWorkReconciliation,
+  registerReconciliationRoute,
+} from "./server-reconciliation-route.js";
 import { isAllowedDashboardAuthority } from "./server-request-authority.js";
 import { refreshSqliteSnapshotInWorker } from "./server-snapshot-refresh.js";
 import { readCommittedSnapshotRevision } from "./server-snapshot-revision.js";
 import { startSnapshotSynchronization } from "./server-snapshot-synchronization.js";
 import { writeReadModelStartup, writeStartupPhase } from "./server-startup.js";
 import { selectedCurrency } from "./server-summary-helpers.js";
+import { createTelemetryProjectionRefresh } from "./server-telemetry-refresh.js";
 import { registerTraceRoutes } from "./server-trace-routes.js";
 import {
   defaultSessionToken,
@@ -50,20 +51,11 @@ import {
   isSafeUiPath,
   shouldBootstrapBrowserSession,
 } from "./server-ui-security.js";
-import {
-  createWorkReconciliation,
-  waitForWorkReconciliation,
-} from "./server-work-reconciliation.js";
 import { dashboardCanonicalSourceRoots } from "./sqlite-read-model-source-fingerprint.js";
 
 export { reconciliationNeedsRefresh } from "./server-work-reconciliation.js";
 
-import {
-  dashboardIdentity,
-  dashboardWorkspaceKey,
-  ReconciliationCommandTimeoutError,
-  reconcileOpenWork,
-} from "./server-workspace.js";
+import { dashboardIdentity, dashboardWorkspaceKey, reconcileOpenWork } from "./server-workspace.js";
 import { rebuildSqliteReadModel, SqliteReadModelFileSystem } from "./sqlite-read-model.js";
 
 export { manifestRun, mergeManifestRuns } from "./manifest-runs.js";
@@ -95,6 +87,7 @@ interface DashboardAppOptions {
   snapshotReadOnly?: boolean;
   reconcileOpenWork?: typeof reconcileOpenWork;
   refreshReadModel?: () => Promise<void>;
+  captureTelemetry?: () => Promise<ActiveCodexTelemetryCapture>;
   snapshotState?: "current" | "updating";
   /** Enable filesystem and day rollover synchronization for the serving process. */
   watchSources?: boolean;
@@ -123,6 +116,8 @@ export function createDashboardApp(
   options: DashboardAppOptions = {},
 ): Hono {
   const app = new Hono();
+  const diagnostics = createDashboardDiagnostics(workspaceRoot, "runtime");
+  diagnostics.log("runtime_app_started", { snapshot_read_only: options.snapshotReadOnly });
   const filesystem = options.filesystem ?? new WorkspaceFileSystem(workspaceRoot);
   const isSqliteSnapshot = filesystem instanceof SqliteReadModelFileSystem;
   // Cache layout within a committed revision and reload after synchronization.
@@ -145,7 +140,6 @@ export function createDashboardApp(
   const workspace = resolve(workspaceRoot);
   const workspaceName = basename(workspace);
   const syncAgentAdapters = options.syncAgentAdapters ?? (() => runAgentAdapterSync(workspaceRoot));
-  let catalogWriteTail = Promise.resolve();
   type DashboardSnapshot = Awaited<ReturnType<typeof dashboardSnapshot>>;
   const snapshotInFlight = new Map<string, Promise<DashboardSnapshot>>();
   const cachedSnapshots = new Map<string, { snapshot: DashboardSnapshot; cachedAt: number }>();
@@ -198,12 +192,17 @@ export function createDashboardApp(
   let activeCapture: ActiveCodexTelemetryCapture | null = null;
   let projectionRefreshInFlight: Promise<void> | null = null;
   let projectionRefreshRequested = false;
-  const rebuildProjection = async () => {
+  const associatedRefreshJobs = new Set<string>();
+  const rebuildProjection = async (associatedJobId: string | null = null) => {
+    if (associatedJobId !== null) associatedRefreshJobs.add(associatedJobId);
     if (projectionRefreshInFlight !== null) {
       projectionRefreshRequested = true;
       return projectionRefreshInFlight;
     }
     snapshotState = "updating";
+    const refresh_id = randomUUID();
+    const job_id = associatedJobId;
+    diagnostics.log("projection_refresh_started", { refresh_id, job_id });
     projectionRefreshInFlight = (async () => {
       let passes = 0;
       do {
@@ -217,36 +216,57 @@ export function createDashboardApp(
       } while (projectionRefreshRequested && passes < 2);
       snapshotState = "current";
       projectionRefreshDiagnostics.clear();
-    })().finally(() => {
-      projectionRefreshInFlight = null;
-      // Preserve a source change that arrived during the bounded catch-up.
-      // It starts after the committed generation becomes observable, rather
-      // than extending the current `updating` state without bound.
-      if (projectionRefreshRequested) {
-        projectionRefreshRequested = false;
-        // Yield a real event-loop turn with `current` exposed before starting
-        // another rebuild. `/ready` can then advertise the committed SQLite
-        // generation and open tabs can read it coherently.
-        const followUp = setTimeout(() => {
-          void rebuildProjection().catch((error: unknown) =>
-            projectionRefreshDiagnostics.record({ trigger: "source_change", error }),
-          );
-        }, 250);
-        followUp.unref();
-      }
-    });
+      diagnostics.log("projection_refresh_completed", {
+        refresh_id,
+        job_id: [...associatedRefreshJobs][0] ?? job_id,
+        job_ids: [...associatedRefreshJobs],
+        projection_updated_at: isSqliteSnapshot ? filesystem.projectionUpdatedAt() : null,
+        latest_token_collected_at: isSqliteSnapshot ? filesystem.latestTokenCollectedAt() : null,
+      });
+      if (!projectionRefreshRequested) associatedRefreshJobs.clear();
+    })()
+      .catch((error: unknown) => {
+        // A failed promotion is still an older snapshot; leave its readiness
+        // explicit and retain evidence instead of silently swallowing failure.
+        projectionRefreshDiagnostics.record({ trigger: "source_change", error });
+        diagnostics.log("projection_refresh_failed", {
+          refresh_id,
+          job_id: [...associatedRefreshJobs][0] ?? job_id,
+          job_ids: [...associatedRefreshJobs],
+          error,
+        });
+        associatedRefreshJobs.clear();
+        throw error;
+      })
+      .finally(() => {
+        projectionRefreshInFlight = null;
+        // Preserve a source change that arrived during the bounded catch-up.
+        // It starts after the committed generation becomes observable, rather
+        // than extending the current `updating` state without bound.
+        if (projectionRefreshRequested) {
+          projectionRefreshRequested = false;
+          // Yield a real event-loop turn with `current` exposed before starting
+          // another rebuild. `/ready` can then advertise the committed SQLite
+          // generation and open tabs can read it coherently.
+          const followUp = setTimeout(() => {
+            void rebuildProjection().catch((error: unknown) =>
+              projectionRefreshDiagnostics.record({ trigger: "source_change", error }),
+            );
+          }, 250);
+          followUp.unref();
+        }
+      });
     return projectionRefreshInFlight;
   };
-  startSnapshotSynchronization({
-    workspaceRoot,
-    discoverSourceRoots: () => dashboardCanonicalSourceRoots(workspaceRoot),
-    staleSeed: isSqliteSnapshot && snapshotState === "updating",
-    watchSources: isSqliteSnapshot && options.watchSources === true,
+  const telemetryRefresh = createTelemetryProjectionRefresh({
     refresh: rebuildProjection,
-    ...(isSqliteSnapshot && options.watchSources === true
-      ? { captureActiveTelemetry: () => captureRepositoryActiveCodexTelemetry(workspaceRoot) }
-      : {}),
-    onRefreshFailure: projectionRefreshDiagnostics.record,
+    ...(options.captureTelemetry !== undefined
+      ? { capture: options.captureTelemetry }
+      : isSqliteSnapshot &&
+          options.watchSources === true &&
+          process.env.ZAIP_DASHBOARD_WATCH_SOURCES !== "0"
+        ? { capture: () => captureRepositoryActiveCodexTelemetry(workspaceRoot) }
+        : {}),
     onCaptureSuccess: (result) => {
       activeCapture = result;
       activeCaptureFailure = null;
@@ -259,12 +279,29 @@ export function createDashboardApp(
       };
     },
   });
-  const reconcileWork = createWorkReconciliation({
-    reconcile: (mode) =>
+  const visibleSnapshotState = () =>
+    telemetryRefresh.pending || activeCaptureFailure !== null ? "updating" : snapshotState;
+  startSnapshotSynchronization({
+    workspaceRoot,
+    discoverSourceRoots: () => dashboardCanonicalSourceRoots(workspaceRoot),
+    staleSeed: isSqliteSnapshot && snapshotState === "updating",
+    watchSources: isSqliteSnapshot && options.watchSources === true,
+    refresh: rebuildProjection,
+    synchronizeTelemetry: telemetryRefresh.refresh,
+    onRefreshFailure: projectionRefreshDiagnostics.record,
+  });
+  const reconcileWork = createLoggedWorkReconciliation({
+    diagnostics,
+    reconcile: (mode, jobId) =>
       reconcileOpen(canonicalFilesystem, workspaceRoot, {
         hostTerminalOnly: mode === "host-terminal",
+        jobId,
       }),
-    refresh: rebuildProjection,
+    snapshotTimes: () => ({
+      projection_updated_at: isSqliteSnapshot ? filesystem.projectionUpdatedAt() : null,
+      latest_token_collected_at: isSqliteSnapshot ? filesystem.latestTokenCollectedAt() : null,
+    }),
+    refresh: (jobId) => rebuildProjection(jobId),
   });
   // Terminal usage is persisted by the host/CLI lifecycle boundary. The
   // source synchronizer above projects those records, but the Dashboard must
@@ -331,7 +368,9 @@ export function createDashboardApp(
     const browserLeaseWrite =
       context.req.method === "GET" && context.req.path === `${API_PREFIX}/browser-lease`;
     const projectionRefreshWrite =
-      context.req.method === "POST" && context.req.path === `${API_PREFIX}/refresh-projection`;
+      context.req.method === "POST" &&
+      (context.req.path === `${API_PREFIX}/refresh-projection` ||
+        context.req.path === `${API_PREFIX}/capture-telemetry`);
     if (
       context.req.method !== "GET" &&
       context.req.method !== "HEAD" &&
@@ -350,7 +389,8 @@ export function createDashboardApp(
           ? "GET, HEAD, PUT"
           : context.req.path === `${API_PREFIX}/reconcile-open-work`
             ? "POST"
-            : context.req.path === `${API_PREFIX}/refresh-projection`
+            : context.req.path === `${API_PREFIX}/refresh-projection` ||
+                context.req.path === `${API_PREFIX}/capture-telemetry`
               ? "POST"
               : "GET, HEAD",
       );
@@ -408,7 +448,7 @@ export function createDashboardApp(
         lifecycle_manifest_state: manifestState,
         read_only: true,
         storage: isSqliteSnapshot ? filesystem.metadata() : { storage_mode: "filesystem" },
-        snapshot_state: snapshotState,
+        snapshot_state: visibleSnapshotState(),
         projection_refresh_failure: projectionRefreshDiagnostics.failure,
         active_capture_failure: activeCaptureFailure,
         active_capture: activeCapture,
@@ -468,11 +508,13 @@ export function createDashboardApp(
           // monthly Operations projection was materialized during rebuild;
           // /ready must never start a competing projection in the background.
           day_count: metadata.daily_aggregate_count,
-          snapshot_state: snapshotState,
+          snapshot_state: visibleSnapshotState(),
           projection_refresh_failure: projectionRefreshDiagnostics.failure,
           active_capture_failure: activeCaptureFailure,
           active_capture: activeCapture,
           snapshot_revision: revision,
+          projection_updated_at: filesystem.projectionUpdatedAt(),
+          latest_token_collected_at: filesystem.latestTokenCollectedAt(),
         });
       }
       const projection = await buildFirstFoldQuickProjection(filesystem, layout, {
@@ -518,48 +560,43 @@ export function createDashboardApp(
     readAggregate,
     clearSnapshotCache,
   });
-  app.post(`${API_PREFIX}/reconcile-open-work`, async (context) => {
+  registerReconciliationRoute(app, {
+    readLayout,
+    diagnostics,
+    reconcileWork,
+    refresh: (jobId) => rebuildProjection(jobId),
+    snapshotState: visibleSnapshotState,
+    refreshCompleted: () =>
+      visibleSnapshotState() === "current" && projectionRefreshInFlight === null,
+  });
+  app.post(`${API_PREFIX}/refresh-projection`, async (context) => {
     try {
       await readLayout();
-      // Share the canonical mutation queue with missed host-stop recovery.
-      // Projection rebuilds run in the background and publish their revision.
-      const reconciledIds = await waitForWorkReconciliation(reconcileWork("manual"), () => {
-        void rebuildProjection().catch(() => undefined);
-      });
-      return context.json({
-        reconciliation: reconciledIds,
-        snapshot_state: snapshotState,
-        projection_refresh_completed:
-          snapshotState === "current" && projectionRefreshInFlight === null,
-      });
-    } catch (error) {
-      if (error instanceof V2WorkspaceRequiredError) throw error;
-      if (error instanceof ReconciliationCommandTimeoutError) {
-        // SIGTERM can occur after the CLI persisted some records. Start an
-        // atomic refresh without extending the request past the client's
-        // deadline, and make that uncertainty explicit to the caller.
+      await telemetryRefresh.refresh(true);
+      if (activeCaptureFailure !== null)
         return context.json(
           {
-            error: error.message,
-            reconciliation_may_be_partial: true,
-            projection_refresh_started: true,
+            error: "Telemetry capture is unavailable",
+            snapshot_state: visibleSnapshotState(),
+            active_capture_failure: activeCaptureFailure,
           },
-          408,
+          503,
         );
-      }
-      return context.json({ error: error instanceof Error ? error.message : String(error) }, 400);
-    }
-  });
-  app.post(`${API_PREFIX}/refresh-projection`, async (context) => {
-    try {
-      await readLayout();
-      await rebuildProjection();
       return context.json(await readSnapshot(context));
     } catch (error) {
       if (error instanceof V2WorkspaceRequiredError) throw error;
       return context.json({ error: error instanceof Error ? error.message : String(error) }, 400);
     }
   });
+  app.post(`${API_PREFIX}/capture-telemetry`, async (context) => {
+    await readLayout();
+    void telemetryRefresh
+      .refresh()
+      .catch((error: unknown) =>
+        projectionRefreshDiagnostics.record({ trigger: "source_change", error }),
+      );
+    return context.json({ snapshot_state: visibleSnapshotState() }, 202);
+  });
   registerCostsRoutes(app, {
     filesystem,
     canonicalFilesystem,
@@ -599,56 +636,11 @@ export function createDashboardApp(
     clearSnapshotCache();
     return context.json(rate);
   });
-  app.on(["GET", "HEAD"], `${API_PREFIX}/agent-catalog`, async (context) => {
-    try {
-      return headOrJson(context, await readAgentCatalogSettings(filesystem));
-    } catch (error) {
-      return headOrJson(
-        context,
-        { error: error instanceof Error ? error.message : String(error) },
-        400,
-      );
-    }
-  });
-  app.get(`${API_PREFIX}/agent-catalog-assets/:agentId`, async (context) => {
-    const portrait = agentPortraitFiles[context.req.param("agentId")];
-    if (portrait === undefined) return context.json({ error: "Agent portrait not found" }, 404);
-    try {
-      return context.body(
-        await readFile(resolve(workspaceRoot, ".agents/config/src", portrait)),
-        200,
-        { "cache-control": "no-store", "content-type": "image/png" },
-      );
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-        return context.json({ error: "Agent portrait not found" }, 404);
-      }
-      return context.json({ error: "Agent portrait could not be read" }, 500);
-    }
-  });
-  app.put(`${API_PREFIX}/agent-catalog`, async (context) => {
-    const update = async () => {
-      try {
-        const persisted = await persistAgentCatalogUpdate(
-          filesystem,
-          await context.req.json(),
-          syncAgentAdapters,
-        );
-        clearSnapshotCache();
-        return context.json(persisted);
-      } catch (error) {
-        if (error instanceof AgentCatalogUpdateError) {
-          return context.json({ error: error.message }, error.status);
-        }
-        return context.json({ error: "Agent catalog update failed" }, 500);
-      }
-    };
-    const result = catalogWriteTail.then(update, update);
-    catalogWriteTail = result.then(
-      () => undefined,
-      () => undefined,
-    );
-    return result;
+  registerAgentCatalogRoutes(app, {
+    filesystem,
+    workspaceRoot,
+    syncAgentAdapters,
+    clearSnapshotCache,
   });
   app.on(["GET", "HEAD"], `${API_PREFIX}/project-settings`, async (context) => {
     try {

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-cost-agent-page.ts

@@ -1,3 +1,5 @@
+import { providerVisibleMetricsSql } from "./sqlite-provider-visibility.js";
+
 /**
  * Date-only Cost pages can use immutable, indexed activity facts.  Any
  * additional filter deliberately falls back to the canonical SQL path, whose
@@ -181,8 +183,18 @@ export function readDateOnlyCostDimensionPage(
     dimension === "model"
       ? "COALESCE(task_population.task_count,0) AS task_count,0 AS prd_count,0 AS spec_count,0 AS validation_count,0 AS evidence_count"
       : "COALESCE(task_population.task_count,0) task_count";
+  const aggregatedRows = `${cte}, aggregated_rows AS (
+    SELECT keys.key,keys.key AS label,COALESCE(population.invocation_count,0) invocation_count,
+      ${rowProductivity},population.total_duration,population.source_event_count,
+      financial.total_tokens,financial.total_cost_usd,financial.total_cost_brl
+    FROM keys LEFT JOIN population USING(key) LEFT JOIN task_population USING(key)
+      LEFT JOIN financial USING(key)
+  ), visible_rows AS (SELECT * FROM aggregated_rows${
+    dimension === "provider" ? ` WHERE ${providerVisibleMetricsSql}` : ""
+  })`;
   const total_count = Number(
-    database.prepare(`${cte} SELECT COUNT(*) AS count FROM keys`).get(...args)?.count ?? 0,
+    database.prepare(`${aggregatedRows} SELECT COUNT(*) AS count FROM visible_rows`).get(...args)
+      ?.count ?? 0,
   );
   const totals =
     database
@@ -192,7 +204,7 @@ export function readDateOnlyCostDimensionPage(
       .get(...args) ?? {};
   const rows = database
     .prepare(
-      `${cte} SELECT keys.key,keys.key AS label,COALESCE(population.invocation_count,0) invocation_count,${rowProductivity},population.total_duration,population.source_event_count,financial.total_tokens,financial.total_cost_usd,financial.total_cost_brl FROM keys LEFT JOIN population USING(key) LEFT JOIN task_population USING(key) LEFT JOIN financial USING(key) ORDER BY financial.total_cost_brl DESC,keys.key LIMIT ? OFFSET ?`,
+      `${aggregatedRows} SELECT * FROM visible_rows ORDER BY total_cost_brl DESC,key LIMIT ? OFFSET ?`,
     )
     .all(...args, limit, offset);
   if (dimension === "model") {

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

@@ -0,0 +1,163 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { prepareDashboardSqliteStartup } from "./sqlite-dashboard-startup.js";
+import { rebuildSqliteReadModel } from "./sqlite-read-model-rebuild.js";
+import { sqliteReadModelPath, validateSqliteReadModelSchema } from "./sqlite-read-model-schema.js";
+import { sourceFingerprint } from "./sqlite-read-model-source-fingerprint.js";
+
+vi.mock("./sqlite-read-model-source-fingerprint.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./sqlite-read-model-source-fingerprint.js")>();
+  return { ...actual, sourceFingerprint: vi.fn(actual.sourceFingerprint) };
+});
+
+const roots: string[] = [];
+const taskContent = (title: string) =>
+  `---\nid: TASK-STARTUP\ntitle: ${title}\nstatus: ready\nrisk: standard\ncreated_at: 2026-08-01T12:00:00.000Z\n---\n`;
+
+async function fixture(seed = true) {
+  vi.stubEnv("ZAIP_SQLITE_DB_PATH", undefined);
+  const fixtures = resolve(import.meta.dirname, "../../../../../.local/sqlite/tests");
+  await mkdir(fixtures, { recursive: true });
+  const root = await mkdtemp(resolve(fixtures, "startup-"));
+  roots.push(root);
+  const task = resolve(root, ".agents/records/tasks/task.md");
+  await mkdir(dirname(task), { recursive: true });
+  await mkdir(resolve(root, ".agents/config"), { recursive: true });
+  await writeFile(resolve(root, ".agents/config/project.yaml"), "zaip:\n  enabled: true\n");
+  await writeFile(task, taskContent("Original seed"));
+  if (seed) await rebuildSqliteReadModel(root);
+  vi.mocked(sourceFingerprint).mockClear();
+  return { root, task, path: sqliteReadModelPath(root) };
+}
+
+function editDatabase(path: string, sql: string) {
+  const database = new DatabaseSync(path);
+  try {
+    database.exec(sql);
+  } finally {
+    database.close();
+  }
+}
+
+function persistedTask(path: string): string {
+  const database = new DatabaseSync(path, { readOnly: true });
+  try {
+    return (
+      database
+        .prepare("SELECT content FROM zaip_vw_files WHERE path=?")
+        .get(".agents/records/tasks/task.md") as { content: string }
+    ).content;
+  } finally {
+    database.close();
+  }
+}
+
+afterEach(async () => {
+  vi.unstubAllEnvs();
+  vi.mocked(sourceFingerprint).mockClear();
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("dashboard SQLite startup", () => {
+  it("serves a validated stale seed without source inventory even after canonical changes", async () => {
+    const { root, task, path } = await fixture();
+    await writeFile(task, taskContent("Changed canonically"));
+    const before = await readFile(path);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      await expect(prepareDashboardSqliteStartup(root)).resolves.toMatchObject({
+        path,
+        files: 2,
+        cache: "stale_seed",
+        fingerprint_ms: 0,
+        materialize_ms: 0,
+        refresh: { processed_sources: 0, reused_sources: 0, canonical_runs_refolded: 0 },
+      });
+    }
+    expect(sourceFingerprint).not.toHaveBeenCalled();
+    expect(await readFile(path)).toEqual(before);
+    expect(persistedTask(path)).toContain("Original seed");
+    // The normal refresh remains canonical and publishes the changed source.
+    await rebuildSqliteReadModel(root);
+    expect(sourceFingerprint).toHaveBeenCalled();
+    expect(persistedTask(path)).toContain("Changed canonically");
+  });
+
+  it.each([
+    [
+      "schema",
+      "UPDATE zaip_aios_activities SET payload_json=json_set(payload_json,'$.value','old') WHERE payload_type='metadata' AND json_extract(payload_json,'$.key')='schema_version'",
+    ],
+    ["index", "DROP INDEX zaip_activities_work_item_identity"],
+    [
+      "missing first fold",
+      "DELETE FROM zaip_aios_activities WHERE payload_type='first_fold_all_time_cache'",
+    ],
+    [
+      "truncated board",
+      "UPDATE zaip_aios_activities SET payload_json=json_set(payload_json,'$.pages.task',json('[]')) WHERE payload_type='first_fold_all_time_board_cache'",
+    ],
+    [
+      "malformed board",
+      "UPDATE zaip_aios_activities SET payload_json='invalid' WHERE payload_type='first_fold_all_time_board_cache'",
+    ],
+    [
+      "malformed cost summary",
+      "UPDATE zaip_aios_activities SET payload_json='invalid' WHERE payload_type='cost_monitor_summary_cache'",
+    ],
+    [
+      "invalid file count",
+      "UPDATE zaip_aios_activities SET payload_json=json_set(payload_json,'$.value','NaN') WHERE payload_type='metadata' AND json_extract(payload_json,'$.key')='source_file_count'",
+    ],
+  ])("rejects %s and rebuilds changed canonical sources", async (_damage, sql) => {
+    const { root, task, path } = await fixture();
+    editDatabase(path, sql);
+    await writeFile(task, taskContent("Recovered canonical source"));
+    await expect(prepareDashboardSqliteStartup(root)).resolves.toMatchObject({
+      path,
+      cache: "rebuilt",
+    });
+    expect(sourceFingerprint).toHaveBeenCalled();
+    expect(() => validateSqliteReadModelSchema(path)).not.toThrow();
+    expect(persistedTask(path)).toContain("Recovered canonical source");
+  });
+
+  it("builds canonical data when the seed is absent", async () => {
+    const { root, path } = await fixture(false);
+    await expect(prepareDashboardSqliteStartup(root)).resolves.toMatchObject({
+      path,
+      cache: "rebuilt",
+    });
+    expect(sourceFingerprint).toHaveBeenCalled();
+    expect(() => validateSqliteReadModelSchema(path)).not.toThrow();
+  });
+
+  it("accepts a genuinely empty committed model without fabricating source work", async () => {
+    const { root, task, path } = await fixture(false);
+    await rm(task);
+    await rm(resolve(root, ".agents/config/project.yaml"));
+    await expect(rebuildSqliteReadModel(root)).resolves.toMatchObject({ files: 0 });
+    vi.mocked(sourceFingerprint).mockClear();
+    await expect(prepareDashboardSqliteStartup(root)).resolves.toMatchObject({
+      path,
+      files: 0,
+      cache: "stale_seed",
+      fingerprint_ms: 0,
+    });
+    expect(sourceFingerprint).not.toHaveBeenCalled();
+  });
+
+  it("honors an explicit forced canonical rebuild", async () => {
+    const { root, task, path } = await fixture();
+    await writeFile(task, taskContent("Forced canonical source"));
+    await expect(
+      prepareDashboardSqliteStartup(root, { forceCanonical: true }),
+    ).resolves.toMatchObject({
+      path,
+      cache: "rebuilt",
+    });
+    expect(sourceFingerprint).toHaveBeenCalled();
+    expect(persistedTask(path)).toContain("Forced canonical source");
+  });
+});