@zaip-ai/cli 1.3.0 → 1.3.1

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

@@ -92,6 +92,40 @@ describe("boardPage", () => {
     expect(linkedPage.tasks).toEqual([linked]);
     expect(standalonePage.totals_by_kind).toMatchObject({ task: 1, "standalone-task": 1 });
   });
+
+  it("returns every Task for an Overview status dialog", () => {
+    const standalone = {
+      id: "TASK-STANDALONE",
+      title: "Standalone",
+      status: "executing",
+      spec_id: null,
+      updated_at: "2026-08-08T10:00:00Z",
+    };
+    const linked = {
+      id: "TASK-LINKED",
+      title: "Linked",
+      status: "executing",
+      spec_id: "SPEC-1",
+      updated_at: "2026-08-08T10:00:00Z",
+    };
+    const projection = {
+      changes: [],
+      tasks: [standalone, linked],
+      prds: [],
+      specs: [],
+    } as unknown as Parameters<typeof boardPage>[0];
+
+    const page = boardPage(projection, "executing", 0, 10, [], {
+      query: "",
+      status: "",
+      risk: "",
+      origin: "",
+      kind: "all-tasks",
+    });
+
+    expect(page.total).toBe(2);
+    expect(page.tasks.map((task) => task.id)).toEqual([linked.id, standalone.id]);
+  });
 });
 
 function macro(id: string, kind: "prd" | "spec", taskIds: string[]) {

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

@@ -62,15 +62,20 @@ export function boardPage(
   const sourceByChange = new Map(
     projection.changes.map((change) => [change.id, change.source.type] as const),
   );
+  const taskOrigin = (task: (typeof projection.tasks)[number]) => {
+    const origin = (task as typeof task & { origin?: unknown }).origin;
+    return (
+      sourceByChange.get(task.change_id) ??
+      (typeof origin === "string" ? origin : task.spec_id === null ? "task" : "spec")
+    );
+  };
   const matchesQuery = (values: readonly (string | null | undefined)[]) =>
     filters.query === "" ||
     values.some((value) => value?.toLocaleLowerCase().includes(filters.query));
   const taskMatches = (task: (typeof projection.tasks)[number]) =>
     (filters.status === "" || taskWorkStage(task) === filters.status) &&
     (filters.risk === "" || task.risk === filters.risk) &&
-    (filters.origin === "" ||
-      (sourceByChange.get(task.change_id) ?? (task.spec_id === null ? "task" : "spec")) ===
-        filters.origin) &&
+    (filters.origin === "" || taskOrigin(task) === filters.origin) &&
     matchesQuery([
       task.id,
       task.title,
@@ -116,11 +121,13 @@ export function boardPage(
   const stageItems =
     filters.kind === ""
       ? allStageItems
-      : filters.kind === "standalone-task"
-        ? allStageItems.filter((item) => item.kind === "task" && item.row.spec_id === null)
-        : filters.kind === "task"
-          ? allStageItems.filter((item) => item.kind === "task" && item.row.spec_id !== null)
-          : allStageItems.filter((item) => item.kind === filters.kind);
+      : filters.kind === "all-tasks"
+        ? allStageItems.filter((item) => item.kind === "task")
+        : filters.kind === "standalone-task"
+          ? allStageItems.filter((item) => item.kind === "task" && item.row.spec_id === null)
+          : filters.kind === "task"
+            ? allStageItems.filter((item) => item.kind === "task" && item.row.spec_id !== null)
+            : allStageItems.filter((item) => item.kind === filters.kind);
   const page = stageItems.slice(offset, offset + limit);
   const ids = new Set(page.map((item) => item.row.id));
   return {

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

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { classificationPage } from "./server-board.js";
+
+describe("dashboard classification pages", () => {
+  it.each([
+    ["task", "lite", "TASK-LITE"],
+    ["task", "standard", "TASK-STANDARD"],
+    ["task", "critical", "TASK-CRITICAL"],
+    ["spec", "empty", "SPEC-EMPTY"],
+    ["spec", "structured", "SPEC-STRUCTURED"],
+    ["spec", "rework", "SPEC-REWORK"],
+    ["prd", "empty", "PRD-EMPTY"],
+    ["prd", "structured", "PRD-STRUCTURED"],
+    ["prd", "rework", "PRD-REWORK"],
+  ] as const)("returns only the canonical %s %s classification page", (kind, classification, expectedId) => {
+    const projection = {
+      tasks: [
+        { id: "TASK-LITE", risk: "lite", created_at: "2026-08-21T00:00:00.000Z", updated_at: null },
+        {
+          id: "TASK-STANDARD",
+          risk: "standard",
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+        {
+          id: "TASK-CRITICAL",
+          risk: "critical",
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+      ],
+      specs: [
+        {
+          id: "SPEC-EMPTY",
+          task_count: 0,
+          rework_run_count: 0,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+        {
+          id: "SPEC-STRUCTURED",
+          task_count: 1,
+          rework_run_count: 0,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+        {
+          id: "SPEC-REWORK",
+          task_count: 1,
+          rework_run_count: 1,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+      ],
+      prds: [
+        {
+          id: "PRD-EMPTY",
+          task_count: 0,
+          rework_run_count: 0,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+        {
+          id: "PRD-STRUCTURED",
+          task_count: 1,
+          rework_run_count: 0,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+        {
+          id: "PRD-REWORK",
+          task_count: 1,
+          rework_run_count: 1,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+      ],
+      changes: [],
+    } as unknown as Parameters<typeof classificationPage>[0];
+    const page = classificationPage(projection, kind, classification, 0, 1);
+    const items = kind === "task" ? page.tasks : kind === "spec" ? page.specs : page.prds;
+    expect(page).toMatchObject({ offset: 0, total: 1 });
+    expect(items.map((item) => item.id)).toEqual([expectedId]);
+    expect(kind === "task" ? page.specs : page.tasks).toEqual([]);
+    expect(kind === "prd" ? page.specs : page.prds).toEqual([]);
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/server-period-macro-metric.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { boardPage } from "./server-board.js";
+import { periodMacroMetric } from "./server-period-macro-metric.js";
+
+const noBoardFilters = { query: "", status: "", risk: "", origin: "", kind: "prd" };
+
+describe("periodMacroMetric", () => {
+  it("keeps a draft PRD counter and its status-dialog board page in Definition", () => {
+    const prd = {
+      id: "PRD-DRAFT",
+      kind: "prd",
+      title: "Draft PRD",
+      status: "draft",
+      lifecycle_status: "draft",
+      work_status: "draft",
+      task_ids: [],
+      parent_id: null,
+      updated_at: "2026-08-29T16:00:00Z",
+    };
+    const projection = { changes: [], tasks: [], prds: [prd], specs: [] } as unknown as Parameters<
+      typeof boardPage
+    >[0];
+
+    expect(periodMacroMetric([prd], "prd").status_counts).toEqual({ definition: 1 });
+    expect(boardPage(projection, "definition", 0, 10, [], noBoardFilters)).toMatchObject({
+      total: 1,
+      prds: [{ id: "PRD-DRAFT" }],
+    });
+    expect(boardPage(projection, "planning", 0, 10, [], noBoardFilters).total).toBe(0);
+  });
+
+  it.each([
+    ["spec", "draft", "planning"],
+    ["prd", "ready", "ready"],
+    ["spec", "planned", "ready"],
+    ["prd", "active", "executing"],
+    ["spec", "delivered", "completed"],
+    ["prd", "cancelled", "cancelled"],
+  ] as const)("maps %s %s to %s", (kind, status, expectedStage) => {
+    expect(periodMacroMetric([{ id: `${kind}-${status}`, status }], kind).status_counts).toEqual({
+      [expectedStage]: 1,
+    });
+  });
+});

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

@@ -0,0 +1,125 @@
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+
+type AllTimeTopTaskFact = {
+  task_id: string;
+  total_duration_ms: number | null;
+  total_tokens: number | null;
+  total_cost_usd: number | null;
+  total_cost_brl: number | null;
+  total_run_count: number;
+};
+
+export function projectAllTimeTopTasks(
+  tasks: readonly AllTimeTopTaskFact[],
+): NonNullable<NonNullable<OperationsProjection["summary"]["overview_metrics"]>["top_tasks"]> {
+  return tasks.map((task) => ({
+    task_id: task.task_id,
+    duration_ms: task.total_duration_ms,
+    total_tokens: task.total_tokens,
+    total_cost_usd: task.total_cost_usd,
+    cost_brl: task.total_cost_brl,
+    run_count: task.total_run_count,
+  }));
+}
+
+type OverviewMacroMetric = NonNullable<
+  NonNullable<OperationsProjection["summary"]["overview_metrics"]>["macro_metrics"]
+>["specs"];
+
+const nullableMetric = (value: unknown): number | null =>
+  typeof value === "number" && Number.isFinite(value) ? value : null;
+
+type MacroKind = "spec" | "prd";
+
+/**
+ * Keeps narrowed-period Overview counters aligned with the stage used by the
+ * board endpoint that supplies the status dialog.
+ */
+export const periodMacroStage = (kind: MacroKind, value: unknown) => {
+  const status = String(value);
+  if (status === "draft") return kind === "prd" ? "definition" : "planning";
+  if (status === "ready" || status === "planned") return "ready";
+  if (status === "active") return "executing";
+  if (status === "delivered") return "completed";
+  return ["executing", "verifying", "completed", "blocked", "failed", "cancelled"].includes(status)
+    ? status
+    : "planning";
+};
+
+/** Projects narrowed-period SPEC/PRD rows without falling back to Task totals. */
+export function periodMacroMetric(
+  rows: readonly Record<string, unknown>[],
+  kind: MacroKind,
+): OverviewMacroMetric {
+  const knownSum = (field: string): number | null => {
+    const values = rows
+      .map((row) => row[field])
+      .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+    return values.length === 0 ? null : values.reduce((total, value) => total + value, 0);
+  };
+  const number = (row: Record<string, unknown>, field: string) => nullableMetric(row[field]) ?? 0;
+  const totalDuration = knownSum("total_duration");
+  const totalTokens = knownSum("total_tokens");
+  const totalCostUsd = knownSum("total_cost_usd");
+  const totalCostBrl = knownSum("total_cost_brl");
+  const statusCounts: Record<string, number> = {};
+  const classificationCounts: Record<string, number> = { empty: 0, structured: 0, rework: 0 };
+  for (const row of rows) {
+    const status = periodMacroStage(kind, row.status);
+    statusCounts[status] = (statusCounts[status] ?? 0) + 1;
+    const classification =
+      number(row, "rework_run_count") > 0
+        ? "rework"
+        : number(row, "task_count") > 0
+          ? "structured"
+          : "empty";
+    classificationCounts[classification] = (classificationCounts[classification] ?? 0) + 1;
+  }
+  const topEntities = rows
+    .map((row) => ({
+      entity_id: String(row.id),
+      title: String(row.title ?? row.id),
+      duration_ms: nullableMetric(row.total_duration),
+      total_tokens: nullableMetric(row.total_tokens),
+      total_cost_usd: nullableMetric(row.total_cost_usd),
+      cost_brl: nullableMetric(row.total_cost_brl),
+      run_count: number(row, "invocation_count"),
+    }))
+    .toSorted(
+      (left, right) =>
+        (right.duration_ms ?? -1) - (left.duration_ms ?? -1) ||
+        left.entity_id.localeCompare(right.entity_id),
+    )
+    .slice(0, 5)
+    .map((entity) => ({
+      ...entity,
+      duration_share:
+        totalDuration === null || totalDuration === 0 || entity.duration_ms === null
+          ? 0
+          : entity.duration_ms / totalDuration,
+    }));
+  const latest =
+    rows
+      .flatMap((row) => (typeof row.occurred_at === "string" ? [row.occurred_at] : []))
+      .toSorted()
+      .at(-1) ?? null;
+  return {
+    status_counts: statusCounts,
+    classification_counts: classificationCounts,
+    entity_count: rows.length,
+    total_run_count: rows.reduce((total, row) => total + number(row, "invocation_count"), 0),
+    total_duration_ms: totalDuration,
+    total_tokens: totalTokens,
+    total_cost_usd: totalCostUsd,
+    total_cost_brl: totalCostBrl,
+    average_duration_ms:
+      totalDuration === null || rows.length === 0 ? null : totalDuration / rows.length,
+    average_tokens: totalTokens === null || rows.length === 0 ? null : totalTokens / rows.length,
+    average_cost_usd:
+      totalCostUsd === null || rows.length === 0 ? null : totalCostUsd / rows.length,
+    average_cost_brl:
+      totalCostBrl === null || rows.length === 0 ? null : totalCostBrl / rows.length,
+    latest_created_at: latest,
+    top_entities: topEntities,
+  };
+}

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

@@ -0,0 +1,66 @@
+import { resolve } from "node:path";
+import { WorkspaceFileSystem, type WorkspaceLayout } from "@zaip-ai/core";
+import { describe, expect, it, vi } from "vitest";
+import { createDashboardApp, reconciliationNeedsRefresh } from "./server.js";
+
+const workspaceRoot = resolve(import.meta.dirname, "../../../../..");
+const v2Layout = { version: 3 } as WorkspaceLayout;
+
+describe("reconciliation snapshot refresh", () => {
+  it("refreshes only when reconciliation changed canonical work", () => {
+    expect(
+      reconciliationNeedsRefresh({ reconciled_ids: [], blocked: [], not_reconciled: [] }),
+    ).toBe(false);
+    expect(
+      reconciliationNeedsRefresh({
+        reconciled_ids: [],
+        blocked: [{ id: "TASK-BLOCKED", reason: "Finalization evidence is missing." }],
+        not_reconciled: [],
+      }),
+    ).toBe(true);
+    expect(
+      reconciliationNeedsRefresh({
+        reconciled_ids: ["TASK-CHANGED"],
+        blocked: [],
+        not_reconciled: [],
+      }),
+    ).toBe(true);
+  });
+
+  it("serves health while a changed reconciliation refreshes in a worker", async () => {
+    let rejectRefresh: ((error: Error) => void) | undefined;
+    const refresh = vi.fn(
+      () =>
+        new Promise<void>((_resolveRefresh, reject) => {
+          rejectRefresh = reject;
+        }),
+    );
+    const app = createDashboardApp(workspaceRoot, "test-session", undefined, {
+      snapshotReadOnly: true,
+      canonicalFilesystem: new WorkspaceFileSystem(workspaceRoot),
+      reconcileOpenWork: async () => ({
+        reconciled_ids: ["TASK-CHANGED"],
+        blocked: [],
+        not_reconciled: [],
+      }),
+      refreshReadModel: refresh,
+      layout: v2Layout,
+    });
+    const reconciliation = app.request("/api/v2/reconcile-open-work", {
+      method: "POST",
+      headers: { "x-zaip-session": "test-session" },
+    });
+    await vi.waitFor(() => expect(refresh).toHaveBeenCalledOnce());
+    await expect(
+      app.request("/api/v2/health", { headers: { "x-zaip-session": "test-session" } }),
+    ).resolves.toMatchObject({
+      status: 200,
+    });
+    rejectRefresh?.(new Error("simulated worker refresh failure"));
+    const response = await reconciliation;
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toMatchObject({
+      error: "simulated worker refresh failure",
+    });
+  });
+});

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

@@ -0,0 +1,61 @@
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { createDashboardApp } from "./server.js";
+import { isAllowedDashboardAuthority } from "./server-request-authority.js";
+
+const workspaceRoot = resolve(import.meta.dirname, "../../../../..");
+
+describe("dashboard loopback authority", () => {
+  it.each([
+    ["http://127.0.0.1:4317/", undefined],
+    ["http://localhost/", "localhost"],
+    ["http://localhost:4317/", "localhost:4317"],
+    ["http://127.0.0.1:4317/", "127.0.0.1:4317"],
+  ])("accepts a loopback authority %s / %s", (url, host) => {
+    expect(isAllowedDashboardAuthority(url, host)).toBe(true);
+  });
+
+  it.each([
+    ["http://untrusted.example:4317/", undefined],
+    ["http://localhost.evil.invalid/", undefined],
+    ["http://localhost/", "untrusted.example:4317"],
+    ["http://localhost/", "localhost:99999"],
+    ["http://localhost/", "localhost/evil"],
+    ["http://localhost/", "localhost@evil.invalid"],
+    ["http://localhost/", "localhost,evil.invalid"],
+    ["http://user:synthetic@localhost/", undefined],
+    ["https://localhost/", undefined],
+    ["not-a-url", undefined],
+  ])("rejects untrusted or malformed authority %s / %s", (url, host) => {
+    expect(isAllowedDashboardAuthority(url, host)).toBe(false);
+  });
+
+  it("rejects arbitrary hosts before bootstrap and API even with a valid session", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    for (const path of ["/", "/index.html", "/api/v2/fx-rate", "/api/v2/health"]) {
+      const response = await app.request(`http://untrusted.example:4317${path}`, {
+        headers: { "sec-fetch-site": "same-origin", "x-zaip-session": "test-session" },
+      });
+      expect(response.status).toBe(403);
+      expect(response.headers.get("set-cookie")).toBeNull();
+    }
+    const spoofed = await app.request("http://localhost/", {
+      headers: { host: "untrusted.example", "sec-fetch-site": "none" },
+    });
+    expect(spoofed.status).toBe(403);
+    expect(spoofed.headers.get("set-cookie")).toBeNull();
+  });
+
+  it("preserves normal local bootstrap and cross-site denial", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    const local = await app.request("http://127.0.0.1:4317/", {
+      headers: { "sec-fetch-site": "none" },
+    });
+    expect(local.status).not.toBe(403);
+    expect(local.headers.get("set-cookie")).toContain("HttpOnly");
+    const crossSite = await app.request("http://127.0.0.1:4317/", {
+      headers: { "sec-fetch-site": "cross-site", origin: "http://untrusted.example" },
+    });
+    expect(crossSite.headers.get("set-cookie")).toBeNull();
+  });
+});

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

@@ -0,0 +1,18 @@
+/** The dashboard is a loopback service, not a reverse-proxy/public host endpoint. */
+export function isAllowedDashboardAuthority(requestUrl: string, hostHeader?: string): boolean {
+  const allowedHost = /^(?:localhost|127\.0\.0\.1)(?::[0-9]{1,5})?$/i;
+  try {
+    const url = new URL(requestUrl);
+    if (url.protocol !== "http:" || url.username || url.password || !allowedHost.test(url.host)) {
+      return false;
+    }
+    if (hostHeader !== undefined) {
+      if (!allowedHost.test(hostHeader)) return false;
+      // Parse as well to reject invalid port numbers, not merely malformed syntax.
+      new URL(`http://${hostHeader}`);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { compactRunProjection, runTimestampInRange } from "./server-projections.js";
+
+describe("dashboard run projections", () => {
+  it("keeps Runs on the final all-time summary day inside the page-first range", () => {
+    expect(runTimestampInRange("2026-08-07T23:59:59.000Z", "2026-08-01", "2026-08-07")).toBe(true);
+    expect(runTimestampInRange("2026-08-08T00:00:00.000Z", "2026-08-01", "2026-08-07")).toBe(false);
+  });
+
+  it("keeps a lifecycle Run with no InvocationSummary as a null-telemetry page row", () => {
+    const run = compactRunProjection({
+      id: "RUN-NO-SUMMARY",
+      started_at: "2026-08-07T02:59:59.999Z",
+      finished_at: null,
+      task_id: null,
+      execution_id: null,
+      conversation_id: null,
+      agent: null,
+      agent_name: null,
+      provider: null,
+      model: null,
+      spec_id: null,
+      prd_id: null,
+      change_id: null,
+      phase: "execution",
+      parent_run_id: null,
+      status: "completed",
+      duration_ms: null,
+      total_tokens: null,
+      cost: null,
+      currency: null,
+      events: null,
+    });
+    expect(run).toMatchObject({
+      id: "RUN-NO-SUMMARY",
+      duration_ms: null,
+      source_duration_ms: null,
+    });
+    expect(run.usage.total.tokens.total).toBeNull();
+    expect(run.usage.total.cost.brl).toBeNull();
+  });
+});

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

@@ -0,0 +1,97 @@
+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 {
+  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.
+  const scriptCandidates = [
+    resolve(
+      workspaceRoot,
+      ".agents/dashboard/packages/local-runtime/scripts/rebuild-sqlite-read-model.mjs",
+    ),
+    resolve(process.cwd(), "scripts/rebuild-sqlite-read-model.mjs"),
+    resolve(
+      process.cwd(),
+      ".agents/dashboard/packages/local-runtime/scripts/rebuild-sqlite-read-model.mjs",
+    ),
+  ];
+  const script = scriptCandidates.find((candidate) => existsSync(candidate));
+  if (script === undefined)
+    throw new Error("SQLite refresh worker script is unavailable from this runtime checkout");
+  await new Promise<void>((resolveWorker, rejectWorker) => {
+    let stderr = "";
+    const worker = spawn(process.execPath, [script], {
+      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_PREFER_LAST_VALID_SEED: "0",
+        ZAIP_DASHBOARD_LAUNCH_PROGRESS: "0",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      windowsHide: true,
+    });
+    worker.stderr?.setEncoding("utf8");
+    worker.stderr?.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    worker.once("error", rejectWorker);
+    worker.once("exit", (code) =>
+      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(() => {});
+}
+
+/**
+ * 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.
+ */
+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);
+  }
+}

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

@@ -582,7 +582,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 start = source.indexOf("async function firstFoldCostSource(");
-    const end = source.indexOf("function buildSqliteTaskTrace(", start);
+    const end = source.indexOf("export function createDashboardApp(", start);
+    expect(start).toBeGreaterThanOrEqual(0);
+    expect(end).toBeGreaterThan(start);
     const firstFoldCostSource = source.slice(start, end);
     expect(firstFoldCostSource).toContain("costMonitorSummaryAggregate(filters)");
     expect(firstFoldCostSource).not.toContain("costMonitorFinancialActivityRows(");