@zaip-ai/cli 2.2.0 → 3.0.0

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

@@ -1,11 +1,44 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { type SqliteReadModelFileSystem, sqliteReadModelPath } from "./sqlite-read-model.js";
 import {
-  type SqliteReadModelFileSystem,
-  sqliteReadModelPath,
-  validateSqliteReadModelSchema,
-} from "./sqlite-read-model.js";
+  readModelSchemaVersion,
+  requiredIndexes,
+  requiredPersistedTables,
+  requiredViews,
+} from "./sqlite-read-model-schema.js";
+
+/** The worker validates integrity and schema before emitting this receipt. */
+export function validateSnapshotWorkerReceipt(stdout: string, destination: string): void {
+  const result = JSON.parse(stdout) as {
+    storage_mode?: unknown;
+    path?: unknown;
+    schema?: {
+      schemaVersion?: unknown;
+      tableCount?: unknown;
+      viewCount?: unknown;
+      indexCount?: unknown;
+    };
+  } | null;
+  const schema = result?.schema;
+  if (
+    result?.storage_mode !== "sqlite_read_model" ||
+    typeof result.path !== "string" ||
+    resolve(result.path) !== resolve(destination) ||
+    schema?.schemaVersion !== readModelSchemaVersion ||
+    schema.tableCount !== requiredPersistedTables.length ||
+    typeof schema.viewCount !== "number" ||
+    !Number.isSafeInteger(schema.viewCount) ||
+    schema.viewCount < requiredViews.length ||
+    typeof schema.indexCount !== "number" ||
+    !Number.isSafeInteger(schema.indexCount) ||
+    schema.indexCount < requiredIndexes.length
+  )
+    throw new Error(
+      "SQLite refresh worker did not return a valid schema receipt for this destination",
+    );
+}
 
 async function rebuildPersistentDatabaseInWorker(workspaceRoot: string, destination: string) {
   const scriptCandidates = [
@@ -24,6 +57,8 @@ async function rebuildPersistentDatabaseInWorker(workspaceRoot: string, destinat
     throw new Error("SQLite refresh worker script is unavailable from this runtime checkout");
   await new Promise<void>((resolveWorker, rejectWorker) => {
     let stderr = "";
+    let stdout = "";
+    let oversizedReceipt = false;
     const worker = spawn(process.execPath, [script], {
       cwd: workspaceRoot,
       env: {
@@ -33,13 +68,18 @@ async function rebuildPersistentDatabaseInWorker(workspaceRoot: string, destinat
         ZAIP_SQLITE_PREFER_LAST_VALID_SEED: "0",
         ZAIP_DASHBOARD_LAUNCH_PROGRESS: "0",
       },
-      stdio: ["ignore", "ignore", "pipe"],
+      stdio: ["ignore", "pipe", "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.stdout?.setEncoding("utf8");
+    worker.stdout?.on("data", (chunk: string) => {
+      if (stdout.length + chunk.length > 64_000) oversizedReceipt = true;
+      if (!oversizedReceipt) stdout += chunk;
+    });
     worker.stderr?.setEncoding("utf8");
     worker.stderr?.on("data", (chunk: string) => {
       stderr = `${stderr}${chunk}`.slice(-8_000);
@@ -48,13 +88,22 @@ async function rebuildPersistentDatabaseInWorker(workspaceRoot: string, destinat
       cleanupWorker();
       rejectWorker(error);
     });
-    worker.once("exit", (code) => {
+    // close follows stdout drain; exit alone may precede the receipt bytes.
+    worker.once("close", (code) => {
       cleanupWorker();
-      return code === 0
-        ? resolveWorker()
-        : rejectWorker(
-            new Error(`SQLite refresh worker failed (${code}): ${stderr.trim() || "no stderr"}`),
-          );
+      if (code !== 0) {
+        rejectWorker(
+          new Error(`SQLite refresh worker failed (${code}): ${stderr.trim() || "no stderr"}`),
+        );
+        return;
+      }
+      try {
+        if (oversizedReceipt) throw new Error("SQLite refresh worker receipt exceeds size limit");
+        validateSnapshotWorkerReceipt(stdout, destination);
+        resolveWorker();
+      } catch (error) {
+        rejectWorker(error);
+      }
     });
   });
 }
@@ -88,6 +137,7 @@ export async function refreshSqliteSnapshotInWorker(
 ) {
   const destination = sqliteReadModelPath(workspaceRoot);
   await rebuildPersistentDatabaseInWorker(workspaceRoot, destination);
-  validateSqliteReadModelSchema(destination);
+  // Integrity/schema checking belongs to the worker, not the HTTP event loop.
+  // Zero exit alone is insufficient: its exact-destination receipt is mandatory.
   filesystem.refresh();
 }

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

@@ -19,6 +19,32 @@ afterEach(() => {
 });
 
 describe("snapshot source synchronization", () => {
+  it("reports capture failure separately while refreshing canonical data", async () => {
+    vi.useFakeTimers();
+    const error = new Error("capture timed out");
+    const onCaptureFailure = vi.fn();
+    const onRefreshFailure = vi.fn();
+    const onCaptureSuccess = vi.fn();
+    const capture = vi.fn().mockRejectedValueOnce(error).mockResolvedValue(undefined);
+    const refresh = vi.fn(async () => undefined);
+    startSnapshotSynchronization({
+      workspaceRoot: "C:/workspace",
+      staleSeed: false,
+      watchSources: true,
+      refresh,
+      captureActiveTelemetry: capture,
+      onCaptureFailure,
+      onCaptureSuccess,
+      onRefreshFailure,
+    });
+    await vi.advanceTimersByTimeAsync(301);
+    expect(onCaptureFailure).toHaveBeenCalledWith(error);
+    expect(onRefreshFailure).not.toHaveBeenCalled();
+    expect(refresh).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(onCaptureSuccess).toHaveBeenCalledTimes(1);
+    expect(refresh).toHaveBeenCalledTimes(2);
+  });
   it("watches current data for both creation and alteration refreshes", async () => {
     vi.useFakeTimers();
     const refresh = vi.fn(async () => undefined);
@@ -38,4 +64,22 @@ describe("snapshot source synchronization", () => {
     await vi.advanceTimersByTimeAsync(300);
     expect(refresh).toHaveBeenCalledTimes(2);
   });
+
+  it("reports failed refreshes with their observable trigger", async () => {
+    vi.useFakeTimers();
+    const onRefreshFailure = vi.fn();
+    startSnapshotSynchronization({
+      workspaceRoot: "C:/workspace",
+      staleSeed: true,
+      watchSources: false,
+      refresh: async () => {
+        throw new Error("read model unavailable");
+      },
+      onRefreshFailure,
+    });
+    await vi.runAllTimersAsync();
+    expect(onRefreshFailure).toHaveBeenCalledWith(
+      expect.objectContaining({ trigger: "stale_seed", error: expect.any(Error) }),
+    );
+  });
 });

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

@@ -6,15 +6,23 @@ export function startSnapshotSynchronization(input: {
   staleSeed: boolean;
   watchSources: boolean;
   refresh: () => Promise<void>;
+  /** Exact active-Codex collection, separate from projection and lifecycle repair. */
+  captureActiveTelemetry?: () => Promise<void>;
+  onCaptureFailure?: (error: unknown) => void;
+  onCaptureSuccess?: () => void;
+  /** Report failed asynchronous refreshes; a stale snapshot must never look healthy. */
+  onRefreshFailure?: (input: { trigger: "stale_seed" | "source_change"; error: unknown }) => void;
 }): void {
-  if (input.staleSeed) void input.refresh().catch(() => undefined);
+  const refresh = (trigger: "stale_seed" | "source_change") =>
+    void input.refresh().catch((error: unknown) => input.onRefreshFailure?.({ trigger, error }));
+  if (input.staleSeed) refresh("stale_seed");
   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);
+      refresh("source_change");
     }, 300);
     pendingRefresh.unref();
   };
@@ -30,6 +38,17 @@ export function startSnapshotSynchronization(input: {
       // Reuse-triggered refresh remains the portable fallback.
     }
   }
-  const freshnessTimer = setInterval(scheduleRefresh, 60_000);
+  const captureAndRefresh = () => {
+    if (input.captureActiveTelemetry === undefined) return scheduleRefresh();
+    void input
+      .captureActiveTelemetry()
+      .then(() => input.onCaptureSuccess?.())
+      .catch((error: unknown) => input.onCaptureFailure?.(error))
+      .finally(scheduleRefresh);
+  };
+  // Run at most once a minute. File watchers only project canonical changes;
+  // they never launch telemetry or lifecycle work.
+  captureAndRefresh();
+  const freshnessTimer = setInterval(captureAndRefresh, 60_000);
   freshnessTimer.unref();
 }

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

@@ -45,7 +45,7 @@ describe("dashboard backend snapshot", () => {
       [
         "lock_version: 1",
         "framework:",
-        "  version: 2.2.0",
+        "  version: 2.5.0",
         "  distribution_sha256: null",
         "layout:",
         "  version: 3",
@@ -357,7 +357,9 @@ describe("dashboard backend snapshot", () => {
     );
 
     try {
-      const app = createDashboardApp(fixtureRoot, "test-session");
+      const app = createDashboardApp(fixtureRoot, "test-session", undefined, {
+        reconcileOpenWork: async () => ({ reconciled_ids: [], blocked: [], not_reconciled: [] }),
+      });
       const allCosts = await app.request("/api/v2/cost-monitor?currency=BRL", {
         headers: { "x-zaip-session": "test-session" },
       });
@@ -448,7 +450,9 @@ describe("dashboard backend snapshot", () => {
           };
         };
       };
-      const julyOperationsPayload = (await julyOperations.json()) as { runs: OperationRunMetric[] };
+      const _julyOperationsPayload = (await julyOperations.json()) as {
+        runs: OperationRunMetric[];
+      };
       const allCostsPayload = (await allCosts.json()) as CostSummaryPayload;
       const julyCostsPayload = (await monthlyCosts.json()) as CostSummaryPayload;
       expect(allCostsPayload).toMatchObject({ readonly: true, aggregate_only: true });
@@ -456,7 +460,7 @@ describe("dashboard backend snapshot", () => {
       const portableAllCostsPayload = (await portableAllCosts.json()) as CostSummaryPayload;
       const portableJulyCostsPayload = (await portableJulyCosts.json()) as CostSummaryPayload;
       const quickOperationsPayload = (await quickOperations.json()) as QuickOperationsPayload;
-      const runIds = (rows: readonly { id: string }[] | readonly { run_id: string }[]) =>
+      const _runIds = (rows: readonly { id: string }[] | readonly { run_id: string }[]) =>
         rows.map((row) => ("id" in row ? row.id : row.run_id)).sort();
       // scope=summary is intentionally aggregate-only: no Run/Sub-Run payload
       // is loaded or returned.  Detail parity remains covered by Operations.
@@ -480,13 +484,13 @@ describe("dashboard backend snapshot", () => {
         expect(cost, `missing Cost bucket ${day}`).toBeDefined();
         expect(period.usage.cost.known_sum, `Operations cost ${day}`).toBeGreaterThan(0);
         expect(period.duration?.known_sum, `Operations duration ${day}`).toBeGreaterThan(0);
-        expect(cost!.estimated_brl, `Cost cost ${day}`).toBeGreaterThan(0);
-        expect(cost!.duration_ms, `Cost duration ${day}`).toBeGreaterThan(0);
-        expect(period.usage.total_tokens.known_sum).toBe(cost!.total_tokens);
-        expect(period.usage.cost.known_sum).toBe(cost!.estimated_brl);
-        expect(period.duration?.known_sum).toBe(cost!.duration_ms);
+        expect(cost?.estimated_brl, `Cost cost ${day}`).toBeGreaterThan(0);
+        expect(cost?.duration_ms, `Cost duration ${day}`).toBeGreaterThan(0);
+        expect(period.usage.total_tokens.known_sum).toBe(cost?.total_tokens);
+        expect(period.usage.cost.known_sum).toBe(cost?.estimated_brl);
+        expect(period.duration?.known_sum).toBe(cost?.duration_ms);
       }
-      const rootOperations = allOperationsPayload.runs.find(
+      const _rootOperations = allOperationsPayload.runs.find(
         (run) => run.id === "RUN-2026-07-14-00-00-DASHBOARD-FIXTURE-A1B2",
       );
       expect(
@@ -520,6 +524,8 @@ describe("dashboard backend snapshot", () => {
         },
         projection: {
           source_latest_at: "2026-07-14T00:00:05.000Z",
+          updated_at: null,
+          latest_token_collected_at: null,
           served_at: expect.any(String),
         },
       });
@@ -567,7 +573,7 @@ describe("dashboard backend snapshot", () => {
 
 describe("Cost Monitor daily summary route", () => {
   it("does not route summary requests through summary.json, snapshots, or Run transport", () => {
-    const source = readFileSync(new URL("./server.ts", import.meta.url), "utf8");
+    const source = readFileSync(new URL("./server-costs-routes.ts", import.meta.url), "utf8");
     const start = source.indexOf('if (scope === "summary")');
     const end = source.indexOf('if (scope === "runs")', start);
     const summaryRoute = source.slice(start, end);
@@ -580,9 +586,9 @@ describe("Cost Monitor daily summary route", () => {
   });
 
   it("uses only the bounded SQL aggregate for the Cost first fold", () => {
-    const source = readFileSync(new URL("./server.ts", import.meta.url), "utf8");
+    const source = readFileSync(new URL("./server-read-projections.ts", import.meta.url), "utf8");
     const start = source.indexOf("async function firstFoldCostSource(");
-    const end = source.indexOf("export function createDashboardApp(", start);
+    const end = source.indexOf("export async function dashboardSnapshot(", start);
     expect(start).toBeGreaterThanOrEqual(0);
     expect(end).toBeGreaterThan(start);
     const firstFoldCostSource = source.slice(start, end);
@@ -593,14 +599,9 @@ describe("Cost Monitor daily summary route", () => {
   });
 
   it("keeps the Daily first-fold response to its displayed-column allowlist", () => {
-    const source = readFileSync(new URL("./sqlite-read-model.ts", import.meta.url), "utf8");
-    const dailyBranch = source.slice(
-      source.indexOf(
-        "if (filteredCostGroup !== undefined && temporalCostGroup && !hasDimensionalCostFilter)",
-      ),
-      source.indexOf(
-        "if (filteredCostGroup !== undefined && (!temporalCostGroup || hasDimensionalCostFilter))",
-      ),
+    const dailyBranch = readFileSync(
+      new URL("./sqlite-query-temporal-dimension.ts", import.meta.url),
+      "utf8",
     );
     expect(dailyBranch).not.toContain("costMonitorFactualDurationByDay(");
     expect(dailyBranch).toContain("Daily first fold is an allowlisted table contract");

package/templates/.agents/dashboard/packages/local-runtime/src/server-sqlite-task-trace.test.ts

@@ -0,0 +1,97 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { createV2WorkspaceLayout } from "@zaip-ai/core";
+import { afterEach, expect, it, vi } from "vitest";
+import { buildSqliteTaskTrace } from "./server-sqlite-task-trace.js";
+import { rebuildSqliteReadModel, SqliteReadModelFileSystem } from "./sqlite-read-model.js";
+import { prepareMultiProviderFixture } from "./sqlite-read-model-multi-provider-fixture.js";
+
+const roots: string[] = [];
+const readers: SqliteReadModelFileSystem[] = [];
+afterEach(async () => {
+  vi.restoreAllMocks();
+  for (const reader of readers.splice(0)) reader.close();
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+const taskId = "TASK-2026-09-10-12-00-TRACE-AAAA";
+const layout = createV2WorkspaceLayout(
+  {
+    schema_version: 1,
+    project: { id: "trace", name: "Trace", timezone: "America/Sao_Paulo" },
+    stack: { id: "zaip-aios-stack", overrides: {} },
+    clients: { codex: true, claude: false },
+    tracking: { enabled: true, currency: "BRL", storage_mode: "tracked_sanitized" },
+  },
+  {
+    lock_version: 2,
+    framework: { version: "3.0.0", distribution_sha256: null },
+    layout: { version: 3 },
+    resolved_profile: { id: null, sha256: null },
+    managed_files: {},
+  },
+);
+const taskContent = (id: string, title: string) =>
+  `---\nid: ${id}\ntitle: ${title}\nstatus: completed\nrisk: standard\ncreated_at: 2026-09-10T15:00:00.000Z\n---\n# ${title}\n`;
+async function fixture(files: Record<string, string>) {
+  const root = await mkdtemp(join(tmpdir(), "zaip-trace-bounded-"));
+  roots.push(root);
+  await prepareMultiProviderFixture(root);
+  for (const [path, content] of Object.entries(files)) {
+    const target = join(root, path);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, content);
+  }
+  await rebuildSqliteReadModel(root);
+  const filesystem = new SqliteReadModelFileSystem(root);
+  readers.push(filesystem);
+  return filesystem;
+}
+
+it("resolves the exact Task and filters oversized history before transport without losing documents", async () => {
+  const path = layout.activePath("task", taskId);
+  const small = ".agents/records/changes/trace/artifacts/tests/notes.md";
+  const large = ".agents/records/changes/trace/artifacts/tests/oversized.md";
+  const astral = ".agents/records/changes/trace/artifacts/tests/astral.md";
+  const shadowId = "TASK-2026-09-10-11-00-SHADOW-AAAA";
+  const filesystem = await fixture({
+    [path]: taskContent(taskId, "Requested Task"),
+    [layout.activePath("task", shadowId)]: taskContent(shadowId, `References ${taskId}`),
+    [small]: `# ${taskId}\n${"x".repeat(250_000 - taskId.length - 3)}`,
+    [large]: `${taskId}\n${"x".repeat(250_001)}`,
+    [astral]: `${taskId}\n${"😀".repeat(130_000)}`,
+  });
+  const expected = filesystem
+    .canonicalTraceFiles([taskId])
+    .filter((row) => row.content.length <= 250_000)
+    .map((row) => row.path);
+  expect(expected).toContain(small);
+  expect(expected).not.toContain(large);
+  expect(expected).not.toContain(astral);
+  const scan = vi.spyOn(filesystem, "canonicalTraceFiles");
+  const trace = await buildSqliteTaskTrace(filesystem, layout, taskId);
+  expect(trace.task_title).toBe("Requested Task");
+  expect(trace.task_id).toBe(taskId);
+  expect(trace.documents.map((row) => row.path)).toEqual(expected);
+  expect(scan).toHaveBeenCalledOnce();
+  expect(scan.mock.calls[0]?.[1]).toBe(250_000);
+  expect(scan.mock.results[0]?.value.map((row: { path: string }) => row.path)).not.toContain(large);
+});
+
+it("rejects a mismatched Task identity instead of tracing a document that mentions it", async () => {
+  const filesystem = await fixture({
+    [layout.activePath("task", taskId)]: taskContent("TASK-2026-09-10-11-00-WRONG-AAAA", taskId),
+  });
+  await expect(buildSqliteTaskTrace(filesystem, layout, taskId)).rejects.toThrow(
+    /identity mismatch/,
+  );
+});
+
+it("retains the canonical divergent-layout guard and rejects invalid bounds", async () => {
+  const filesystem = await fixture({
+    [layout.activePath("task", taskId)]: taskContent(taskId, "Active"),
+    [`.agents/data/tasks/2026/09/10/${taskId}.md`]: taskContent(taskId, "Divergent"),
+  });
+  await expect(buildSqliteTaskTrace(filesystem, layout, taskId)).rejects.toThrow(/Divergent/);
+  expect(() => filesystem.canonicalTraceFiles([taskId], -1)).toThrow(/Invalid trace content bound/);
+});

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

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import type { WorkspaceLayout } from "@zaip-ai/core";
+import { resolveArtifactReadPath, type WorkspaceLayout } from "@zaip-ai/core";
 import type { TaskTrace, TraceDocument } from "@zaip-ai/dashboard-traceability/contracts";
 import {
   buildTraceStageRecords,
@@ -8,26 +8,23 @@ import {
 } from "@zaip-ai/dashboard-traceability/server";
 import type { SqliteReadModelFileSystem } from "./sqlite-read-model.js";
 
-export function buildSqliteTaskTrace(
+export async function buildSqliteTaskTrace(
   filesystem: SqliteReadModelFileSystem,
   layout: WorkspaceLayout,
   taskId: string,
-): TaskTrace {
-  const initial = filesystem.canonicalTraceFiles([taskId]);
-  const taskFile = initial.find(
-    (row) =>
-      row.path.includes("/.agents/data/tasks/") ||
-      row.path.includes(".agents/data/tasks/") ||
-      row.path.includes("/.agents/records/tasks/") ||
-      row.path.includes(".agents/records/tasks/"),
-  );
-  if (taskFile === undefined) throw new Error(`Canonical Task ${taskId} was not found`);
+): Promise<TaskTrace> {
+  // Resolve the exact canonical identity, not the first Task mentioning it.
+  // This also avoids scanning all historical contents just to locate one Task.
+  const taskPath = await resolveArtifactReadPath(filesystem, layout, "task", taskId);
+  if (taskPath === null) throw new Error(`Canonical Task ${taskId} was not found`);
+  const taskFile = { path: taskPath, content: await filesystem.readText(taskPath) };
   const scalar = (key: string): string | null => {
     const frontMatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(taskFile.content)?.[1] ?? "";
     const value = new RegExp(`^${key}:\\s*(.+?)\\s*$`, "m").exec(frontMatter)?.[1]?.trim();
     if (value === undefined || value === "null") return null;
     return value.replace(/^['"]|['"]$/g, "");
   };
+  if (scalar("id") !== taskId) throw new Error(`Canonical Task identity mismatch: ${taskId}`);
   const relatedId = (key: string, prefix: string): string | null =>
     scalar(key) ?? new RegExp(`\\b${prefix}[A-Z0-9-]+`).exec(taskFile.content)?.[0] ?? null;
   const changeId = relatedId("change_id", "CHG-") ?? taskId;
@@ -37,7 +34,7 @@ export function buildSqliteTaskTrace(
     (value): value is string => value !== null,
   );
   const documents = filesystem
-    .canonicalTraceFiles(markers)
+    .canonicalTraceFiles(markers, 250_000)
     .filter(
       (row) => /\.(?:md|json|jsonl|txt|log)$/i.test(row.path) && row.content.length <= 250_000,
     )

package/templates/.agents/dashboard/packages/local-runtime/src/server-sqlite-view-allowlist.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it, vi } from "vitest";
+import { createDashboardApp } from "./server.js";
+import { withSqliteReadModelFixture } from "./server.test-fixtures.js";
+
+describe("SQLite view HTTP allowlist", () => {
+  it("rejects inherited object names before invoking SQLite and accepts an owned view", async () => {
+    await withSqliteReadModelFixture("view-allowlist", async ({ root, filesystem }) => {
+      const viewPage = vi.spyOn(filesystem, "viewPage");
+      const app = createDashboardApp(root, "test-session", undefined, { filesystem });
+      for (const view of ["constructor", "toString", "__proto__"]) {
+        const response = await app.request(`/api/v2/sqlite-views?view=${view}`, {
+          headers: { "x-zaip-session": "test-session" },
+        });
+        expect(response.status).toBe(400);
+        await expect(response.json()).resolves.toEqual({ error: "Unsupported SQLite view" });
+      }
+      expect(viewPage).not.toHaveBeenCalled();
+      const response = await app.request("/api/v2/sqlite-views?view=first_fold_top_tasks", {
+        headers: { "x-zaip-session": "test-session" },
+      });
+      expect(response.status, await response.clone().text()).toBe(200);
+      expect(viewPage).toHaveBeenCalledWith("first_fold_top_tasks", expect.any(Object));
+    });
+  });
+});

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

@@ -0,0 +1,56 @@
+import {
+  readPrdDetail,
+  readSpecDetail,
+  readTaskDetail,
+} from "@zaip-ai/dashboard-operations/server";
+import { buildTaskTrace } from "@zaip-ai/dashboard-traceability/server";
+import type { Hono } from "hono";
+import { API_PREFIX, headOrJson, V2WorkspaceRequiredError } from "./server-http-contracts.js";
+import type { DashboardRouteContext } from "./server-route-context.js";
+import { buildSqliteTaskTrace } from "./server-sqlite-task-trace.js";
+import { SqliteReadModelFileSystem } from "./sqlite-read-model.js";
+export function registerTraceRoutes(app: Hono, dependencies: DashboardRouteContext) {
+  const { filesystem, readLayout } = dependencies;
+  app.on(["GET", "HEAD"], `${API_PREFIX}/tasks/:id`, async (context) => {
+    try {
+      const layout = await readLayout();
+      return headOrJson(context, await readTaskDetail(filesystem, layout, context.req.param("id")));
+    } catch (error) {
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      return headOrJson(context, { error: "Task not found" }, 404);
+    }
+  });
+  app.on(["GET", "HEAD"], `${API_PREFIX}/prds/:id`, async (context) => {
+    try {
+      const layout = await readLayout();
+      return headOrJson(context, await readPrdDetail(filesystem, layout, context.req.param("id")));
+    } catch (error) {
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      return headOrJson(context, { error: "PRD not found" }, 404);
+    }
+  });
+  app.on(["GET", "HEAD"], `${API_PREFIX}/specs/:id`, async (context) => {
+    try {
+      const layout = await readLayout();
+      return headOrJson(context, await readSpecDetail(filesystem, layout, context.req.param("id")));
+    } catch (error) {
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      return headOrJson(context, { error: "SPEC not found" }, 404);
+    }
+  });
+  app.on(["GET", "HEAD"], `${API_PREFIX}/tasks/:id/trace`, async (context) => {
+    try {
+      const layout = await readLayout();
+      const taskId = context.req.param("id");
+      return headOrJson(
+        context,
+        filesystem instanceof SqliteReadModelFileSystem
+          ? await buildSqliteTaskTrace(filesystem, layout, taskId)
+          : await buildTaskTrace(filesystem, layout, taskId),
+      );
+    } catch (error) {
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      return headOrJson(context, { error: "Task trace not found" }, 404);
+    }
+  });
+}

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

@@ -0,0 +1,84 @@
+import { serializeMarkdown, WorkspaceFileSystem } from "@zaip-ai/core";
+import { expect, it } from "vitest";
+import { createDashboardApp } from "./server.js";
+import { withSqliteReadModelFixture } from "./server.test-fixtures.js";
+import { rebuildSqliteReadModel, SqliteReadModelFileSystem } from "./sqlite-read-model.js";
+
+it("indexes draft and terminal Tasks in SQLite without adding drafts to Kanban", async () => {
+  await withSqliteReadModelFixture("trace-index", async ({ root }) => {
+    const at = "2026-09-11T10:00:00.000Z";
+    const canonical = new WorkspaceFileSystem(root);
+    for (const [i, status] of ["draft", "cancelled", "blocked"].entries()) {
+      await canonical.writeTextAtomic(
+        `.agents/records/tasks/2026/09/task-${i}.md`,
+        serializeMarkdown({
+          metadata: {
+            schema_version: 2,
+            id: `TASK-INDEX-${i}`,
+            title: `Task ${status}`,
+            status,
+            revision: 1,
+            change_id: `CHG-INDEX-${i}`,
+            short_name: `index-${i}`,
+            objective: "Identity fixture",
+            risk: "standard",
+            priority: "medium",
+            owner: null,
+            requirement_ids: ["REQ-WORK-001"],
+            acceptance_ids: ["AC-WORK-001-09"],
+            depends_on: [],
+            write_scopes: ["proof"],
+            plan_revision: null,
+            plan_hash: null,
+            created_at: at,
+            updated_at: at,
+            started_at: null,
+            finished_at: null,
+            result: null,
+          },
+          body: "# Identity fixture\n",
+        }),
+      );
+    }
+    await rebuildSqliteReadModel(root);
+    const sqlite = new SqliteReadModelFileSystem(root);
+    try {
+      const app = createDashboardApp(root, "fixture", undefined, { filesystem: sqlite });
+      const request = async (query: string) => {
+        const response = await app.request(`/api/v2/operations?${query}`, {
+          headers: { "x-zaip-session": "fixture" },
+        });
+        expect(response.status).toBe(200);
+        return response.json() as Promise<{
+          total: number;
+          tasks: { id: string; status: string }[];
+        }>;
+      };
+      const first = await request("scope=traceability&offset=0&limit=2");
+      const second = await request("scope=traceability&offset=2&limit=2");
+      expect(first.total).toBe(3);
+      expect(first.tasks).toHaveLength(2);
+      expect(second.tasks).toHaveLength(1);
+      expect([...first.tasks, ...second.tasks].map((task) => task.id)).toEqual([
+        "TASK-INDEX-2",
+        "TASK-INDEX-1",
+        "TASK-INDEX-0",
+      ]);
+      expect(second.tasks[0]?.status).toBe("draft");
+      for (const stage of [
+        "definition",
+        "planning",
+        "ready",
+        "executing",
+        "completed",
+        "blocked",
+      ]) {
+        const board = await request(`scope=board&stage=${stage}&kind=all-tasks`);
+        expect(board.tasks.map((task: { id: string }) => task.id)).not.toContain("TASK-INDEX-0");
+      }
+      expect((await request("scope=traceability&offset=3&limit=2")).tasks).toEqual([]);
+    } finally {
+      sqlite.close();
+    }
+  });
+});