@zaip-ai/cli 2.2.0 → 3.0.0

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

@@ -0,0 +1,461 @@
+import type { WorkspaceFileSystem, WorkspaceLayout } from "@zaip-ai/core";
+import {
+  buildCostSummaryProjection,
+  type CostSummarySource,
+} from "@zaip-ai/dashboard-cost-monitor/server";
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+import { buildQuickOperationsProjection } from "@zaip-ai/dashboard-operations/server";
+import { LifecycleManifestStore } from "@zaip-ai/lifecycle-manifests";
+import type { Context } from "hono";
+import { requireV2Layout } from "./server-http-contracts.js";
+import { projectionPeriodFilter } from "./server-period.js";
+import { periodMacroMetric, projectAllTimeTopTasks } from "./server-period-macro-metric.js";
+import {
+  buildCanonicalOperationsProjection,
+  buildCurrentCostProjection,
+  readCurrentFxRate,
+} from "./server-projections.js";
+import { selectedCurrency } from "./server-summary-helpers.js";
+import { dashboardIdentity } from "./server-workspace.js";
+import { SqliteReadModelFileSystem } from "./sqlite-read-model.js";
+export type OverviewMacroMetrics = NonNullable<
+  NonNullable<OperationsProjection["summary"]["overview_metrics"]>["macro_metrics"]
+>;
+export async function buildFirstFoldQuickProjection(
+  filesystem: WorkspaceFileSystem,
+  layout: WorkspaceLayout,
+  filter: { from: string | null; to: string | null },
+  options: {
+    includeBoardTasks?: boolean;
+    includeExtended?: boolean;
+    includePeriods?: boolean;
+    includeTopTasks?: boolean;
+  } = {},
+): Promise<OperationsProjection> {
+  // The comparison runtime deliberately has no lifecycle daily aggregates in
+  // its snapshot.  Its immutable filesystem contains only canonical records,
+  // while the SQL views supply the first-fold facts.  Never enter the legacy
+  // quick projection here: it requires lifecycle daily read models and would
+  // make an otherwise valid SQLite dashboard fail on first paint.
+  const projection =
+    filesystem instanceof SqliteReadModelFileSystem
+      ? buildSqliteOperationsProjection(filesystem, layout, filter, options)
+      : await buildQuickOperationsProjection(filesystem, layout, filter, options);
+  if (!(filesystem instanceof SqliteReadModelFileSystem)) return projection;
+  const cachedMonthlyQuick = filesystem.firstFoldMonthlyQuick(filter);
+  const aggregate =
+    filter.from === null && filter.to === null
+      ? filesystem.firstFoldViewportAllTime().aggregate
+      : (cachedMonthlyQuick?.aggregate ?? filesystem.firstFoldAggregate(filter));
+  return {
+    ...projection,
+    summary: {
+      ...projection.summary,
+      projection_updated_at: filesystem.projectionUpdatedAt(),
+      latest_token_collected_at: filesystem.latestTokenCollectedAt(),
+      run_count: aggregate.total_run_count,
+      overview_metrics: {
+        ...projection.summary.overview_metrics,
+        duration_ms: aggregate.duration_ms,
+        tokens: aggregate.total_tokens,
+        cost_brl: aggregate.cost_brl,
+        execution_day_count: aggregate.execution_day_count,
+        data_source: "run_records",
+      },
+    },
+  };
+}
+export function buildSqliteOperationsProjection(
+  filesystem: SqliteReadModelFileSystem,
+  layout: WorkspaceLayout,
+  filter: { from: string | null; to: string | null },
+  options: {
+    includeBoardTasks?: boolean;
+    includeExtended?: boolean;
+    includePeriods?: boolean;
+    includeTopTasks?: boolean;
+  },
+): OperationsProjection {
+  const cachedMonthlyQuick = filesystem.firstFoldMonthlyQuick(filter);
+  const fullAllTime =
+    filter.from === null && filter.to === null
+      ? options.includeExtended === true
+        ? filesystem.firstFoldAllTime()
+        : null
+      : null;
+  const allTime =
+    fullAllTime ??
+    (filter.from === null && filter.to === null ? filesystem.firstFoldViewportAllTime() : null);
+  const allTimeBoard =
+    filter.from === null && filter.to === null && options.includeBoardTasks === true
+      ? filesystem.firstFoldBoardAllTime()
+      : null;
+  const page = <T extends "task" | "spec" | "prd">(kind: T) =>
+    cachedMonthlyQuick?.pages[kind] ??
+    allTimeBoard?.pages[kind] ??
+    filesystem.canonicalWorkPage(kind, filter, 0, 10_000).rows;
+  const includeEntities = allTime === null || options.includeBoardTasks === true;
+  const tasks = includeEntities ? page("task") : [];
+  const specs = includeEntities ? page("spec") : [];
+  const prds = includeEntities ? page("prd") : [];
+  const aggregate =
+    allTime?.aggregate ?? cachedMonthlyQuick?.aggregate ?? filesystem.firstFoldAggregate(filter);
+  const legacyDraftCount = allTime?.task_status_counts.draft ?? 0;
+  const taskCount =
+    allTime === null ? tasks.length : Math.max(0, allTime.aggregate.task_count - legacyDraftCount);
+  const allTimeTopTasks =
+    filter.from === null &&
+    filter.to === null &&
+    (fullAllTime !== null || options.includeTopTasks === true)
+      ? (fullAllTime?.top_tasks ?? filesystem.firstFoldTopTasksAllTime())
+      : null;
+  const topTasks =
+    allTimeTopTasks === null
+      ? (cachedMonthlyQuick?.top_tasks ?? filesystem.topTasks(filter)).map((task) => ({
+          task_id: task.task_id,
+          duration_ms: task.duration_ms,
+          total_tokens: task.total_tokens,
+          cost_brl: task.cost_brl,
+          run_count: task.run_count,
+        }))
+      : projectAllTimeTopTasks(allTimeTopTasks);
+  const macroMetrics =
+    fullAllTime === null
+      ? ({
+          specs: periodMacroMetric(specs, "spec"),
+          prds: periodMacroMetric(prds, "prd"),
+        } satisfies OverviewMacroMetrics)
+      : (Object.fromEntries(
+          (["specs", "prds"] as const).map((kind) => {
+            const metric = fullAllTime.macro_metrics[kind];
+            return [
+              kind,
+              {
+                status_counts: metric.status_counts,
+                classification_counts: metric.classification_counts,
+                entity_count: metric.entity_count,
+                total_run_count: metric.total_run_count,
+                total_duration_ms: metric.total_duration_ms,
+                total_tokens: metric.total_tokens,
+                total_cost_usd: metric.total_cost_usd,
+                total_cost_brl: metric.total_cost_brl,
+                average_duration_ms: metric.average_duration_ms,
+                average_tokens: metric.average_tokens,
+                average_cost_usd: metric.average_cost_usd,
+                average_cost_brl: metric.average_cost_brl,
+                latest_created_at: metric.latest_created_at,
+                top_entities: metric.top_entities.map((entity) => ({
+                  entity_id: entity.entity_id,
+                  title: entity.title,
+                  duration_ms: entity.total_duration_ms,
+                  total_tokens: entity.total_tokens,
+                  total_cost_usd: entity.total_cost_usd,
+                  cost_brl: entity.total_cost_brl,
+                  run_count: entity.total_run_count,
+                  duration_share: entity.duration_share,
+                })),
+              },
+            ];
+          }),
+        ) as NonNullable<
+          NonNullable<OperationsProjection["summary"]["overview_metrics"]>["macro_metrics"]
+        >);
+  const statuses: Record<string, number> = Object.fromEntries(
+    Object.entries(allTime?.task_status_counts ?? {}).filter(([status]) => status !== "draft"),
+  );
+  const risks: Record<string, number> = allTime?.task_risk_counts ?? {};
+  if (allTime === null) {
+    for (const task of tasks) {
+      const status = typeof task.status === "string" ? task.status : "draft";
+      const risk = typeof task.risk === "string" ? task.risk : "standard";
+      statuses[status] = (statuses[status] ?? 0) + 1;
+      risks[risk] = (risks[risk] ?? 0) + 1;
+    }
+  }
+  const latest =
+    allTime?.aggregate.latest_task_created_at ??
+    [...tasks, ...specs, ...prds]
+      .map((row) => (typeof row.occurred_at === "string" ? row.occurred_at : null))
+      .filter((value): value is string => value !== null)
+      .sort()
+      .at(-1) ??
+    null;
+  const unavailableUsage = {
+    events: 0,
+    tokens: { input: null, cached_input: null, output: null, reasoning: null, total: null },
+    cost: { usd: null, brl: null },
+    coverage: { events: 0, tokens: 0, usd: 0, brl: 0 },
+  };
+  const totalUsage = {
+    ...unavailableUsage,
+    tokens: { ...unavailableUsage.tokens, total: aggregate.total_tokens },
+    cost: { ...unavailableUsage.cost, brl: aggregate.cost_brl },
+  };
+  const usage = {
+    conversation: unavailableUsage,
+    planning: unavailableUsage,
+    execution: unavailableUsage,
+    total: totalUsage,
+    new_work: unavailableUsage,
+    rework: unavailableUsage,
+  };
+  const dailyPeriods = options.includePeriods === true ? filesystem.dailyPeriods(filter) : {};
+  const hasUnknownUsage = Object.values(dailyPeriods).some(
+    (period) => period.usage.total_tokens.unknown > 0 || period.usage.cost.unknown > 0,
+  );
+  const canonicalSource = filesystem.canonicalSource();
+  const taskProjection = (row: Record<string, unknown>) => ({
+    schema_version: 2 as const,
+    id: String(row.id),
+    revision: 1,
+    change_id: typeof row.change_id === "string" ? row.change_id : "",
+    title: String(row.title ?? row.id),
+    short_name: String(row.title ?? row.id),
+    objective: "",
+    status: normalizeTaskStatus(row.status),
+    attempt_count: null,
+    risk: normalizeRisk(row.risk),
+    priority: "medium" as const,
+    owner: null,
+    requirement_ids: [],
+    acceptance_ids: [],
+    depends_on: [],
+    write_scopes: [],
+    created_at: String(row.occurred_at),
+    updated_at: String(row.occurred_at),
+    started_at: null,
+    finished_at: null,
+    result: null,
+    artifact_path: canonicalSource,
+    progress: 0,
+    spec_id: typeof row.spec_id === "string" ? row.spec_id : null,
+    origin: typeof row.origin === "string" ? row.origin : null,
+    execution_started: false,
+    telemetry: {
+      duration_ms: nullableMetric(row.total_duration),
+      tokens: nullableMetric(row.total_tokens),
+      cost_brl: nullableMetric(row.total_cost_brl),
+    },
+  });
+  const macroProjection = (row: Record<string, unknown>, kind: "prd" | "spec") => {
+    const entityUsage = {
+      ...unavailableUsage,
+      tokens: { ...unavailableUsage.tokens, total: nullableMetric(row.total_tokens) },
+      cost: { ...unavailableUsage.cost, brl: nullableMetric(row.total_cost_brl) },
+    };
+    return {
+      id: String(row.id),
+      title: String(row.title ?? row.id),
+      created_at: String(row.occurred_at),
+      updated_at: String(row.occurred_at),
+      kind,
+      parent_id: null,
+      artifact_path: canonicalSource,
+      lifecycle_status: String(row.status ?? "draft"),
+      work_status: normalizeMacroStatus(row.status),
+      execution_ids: [],
+      task_ids: [],
+      planned_tasks: [],
+      canonical_run_ids: [],
+      run_ids: [],
+      root_execution_run_ids: [],
+      execution_count: 0,
+      task_count: 0,
+      run_count: nullableMetric(row.invocation_count) ?? 0,
+      duration_ms: nullableMetric(row.total_duration),
+      decisions: { human: 0, agent: 0 },
+      rework_run_count: 0,
+      quality: {
+        completed_tasks: 0,
+        task_completion_rate: 0,
+        terminal_runs: 0,
+        successful_runs: 0,
+        terminal_success_rate: 0,
+        rework_rate: 0,
+      },
+      usage: {
+        conversation: unavailableUsage,
+        planning: unavailableUsage,
+        execution: unavailableUsage,
+        total: entityUsage,
+        new_work: unavailableUsage,
+        rework: unavailableUsage,
+      },
+    };
+  };
+  return {
+    schema_version: 2,
+    layout_version: layout.version as 2 | 3,
+    readonly: true,
+    source: canonicalSource,
+    filters: filter,
+    summary: {
+      prd_count: allTime?.aggregate.prd_count ?? prds.length,
+      spec_count: allTime?.aggregate.spec_count ?? specs.length,
+      execution_count: 0,
+      task_count: taskCount,
+      run_count: aggregate.total_run_count,
+      overview_metrics: {
+        duration_ms: aggregate.duration_ms,
+        execution_day_count: aggregate.execution_day_count,
+        tokens: aggregate.total_tokens,
+        cost_brl: aggregate.cost_brl,
+        prd_count: allTime?.aggregate.prd_count ?? prds.length,
+        spec_count: allTime?.aggregate.spec_count ?? specs.length,
+        selected_counts: {
+          prds: allTime?.aggregate.prd_count ?? prds.length,
+          specs: allTime?.aggregate.spec_count ?? specs.length,
+        },
+        task_count: taskCount,
+        completed_prd_count:
+          allTime?.aggregate.completed_prd_count ??
+          prds.filter((row) => row.status === "completed").length,
+        completed_spec_count:
+          allTime?.aggregate.completed_spec_count ??
+          specs.filter((row) => row.status === "completed").length,
+        completed_task_count: allTime?.aggregate.completed_task_count ?? statuses.completed ?? 0,
+        task_status_counts: statuses,
+        task_risk_counts: risks,
+        top_tasks: topTasks,
+        ...(macroMetrics === undefined ? {} : { macro_metrics: macroMetrics }),
+        latest_task_created_at: latest,
+        coverage: { duration: 1, tokens: hasUnknownUsage ? 0 : 1, cost: hasUnknownUsage ? 0 : 1 },
+        data_source: "run_records",
+        partial: true,
+      },
+      decisions: { human: 0, agent: 0 },
+      source_latest_at: latest,
+      quality: {
+        completed_tasks: statuses.completed ?? 0,
+        task_completion_rate:
+          taskCount === 0
+            ? 0
+            : (allTime?.aggregate.completed_task_count ?? statuses.completed ?? 0) / taskCount,
+        terminal_runs: 0,
+        successful_runs: 0,
+        terminal_success_rate: 0,
+        rework_rate: 0,
+      },
+      reconciliation: {
+        phase_tokens_match_total: true,
+        phase_usd_match_total: true,
+        phase_brl_match_total: true,
+        origin_tokens_match_total: true,
+      },
+      usage,
+      periods: { daily: options.includePeriods === true ? dailyPeriods : {} },
+    },
+    origins: { conversation: usage, task: usage, spec: usage, prd: usage },
+    prds: prds.map((row) => macroProjection(row, "prd")),
+    specs: specs.map((row) => macroProjection(row, "spec")),
+    tasks: options.includeBoardTasks ? tasks.map(taskProjection) : [],
+    changes: [],
+    executions: [],
+    runs: [],
+    decisions: [],
+    evidences: [],
+    validations: [],
+  };
+}
+export function nullableMetric(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+export function normalizeTaskStatus(
+  value: unknown,
+):
+  | "draft"
+  | "planned"
+  | "executing"
+  | "verifying"
+  | "completed"
+  | "failed"
+  | "blocked"
+  | "cancelled" {
+  return [
+    "draft",
+    "planned",
+    "executing",
+    "verifying",
+    "completed",
+    "failed",
+    "blocked",
+    "cancelled",
+  ].includes(String(value))
+    ? (String(value) as
+        | "draft"
+        | "planned"
+        | "executing"
+        | "verifying"
+        | "completed"
+        | "failed"
+        | "blocked"
+        | "cancelled")
+    : "draft";
+}
+export function normalizeRisk(value: unknown): "lite" | "standard" | "critical" {
+  return ["lite", "standard", "critical"].includes(String(value))
+    ? (String(value) as "lite" | "standard" | "critical")
+    : "standard";
+}
+export function normalizeMacroStatus(
+  value: unknown,
+): "planning" | "executing" | "verifying" | "completed" | "blocked" | "failed" | "cancelled" {
+  const status = String(value);
+  if (["executing", "verifying", "completed", "blocked", "failed", "cancelled"].includes(status))
+    return status as "executing" | "verifying" | "completed" | "blocked" | "failed" | "cancelled";
+  return "planning";
+}
+export async function firstFoldCostSource(
+  filesystem: WorkspaceFileSystem,
+  filters: Parameters<SqliteReadModelFileSystem["invocationCostRows"]>[0] = {
+    from: null,
+    to: null,
+  },
+): Promise<CostSummarySource> {
+  if (filesystem instanceof SqliteReadModelFileSystem) {
+    return filesystem.costMonitorSummaryAggregate(filters) as CostSummarySource;
+  }
+  const daily = await new LifecycleManifestStore(filesystem).readDailyReadModels("overview");
+  if (daily === null) throw new Error("Lifecycle daily overview is not initialized");
+  return {
+    periods: {
+      daily: Object.fromEntries(
+        Object.entries(daily.days).map(([day, model]) => [day, model.overview]),
+      ),
+    },
+  } satisfies CostSummarySource;
+}
+export async function dashboardSnapshot(
+  filesystem: WorkspaceFileSystem,
+  workspaceRoot: string,
+  context: Context,
+  cachedLayout?: WorkspaceLayout,
+) {
+  const layout = cachedLayout ?? (await requireV2Layout(filesystem));
+  const { from, to } = projectionPeriodFilter(context);
+  const currency = selectedCurrency(context);
+  const operations =
+    filesystem instanceof SqliteReadModelFileSystem
+      ? await buildFirstFoldQuickProjection(filesystem, layout, { from, to })
+      : await buildCanonicalOperationsProjection(filesystem, layout, { from, to });
+  const costs =
+    filesystem instanceof SqliteReadModelFileSystem
+      ? buildCostSummaryProjection(
+          await firstFoldCostSource(filesystem, { from, to }),
+          operations,
+          currency,
+          currency === "BRL" ? ((await readCurrentFxRate(filesystem))?.rate ?? null) : null,
+        )
+      : await buildCurrentCostProjection(filesystem, operations, currency);
+  return {
+    operations,
+    costs,
+    dashboard: await dashboardIdentity(filesystem, workspaceRoot),
+    projection: {
+      source_latest_at: operations.summary.source_latest_at,
+      updated_at: operations.summary.projection_updated_at ?? null,
+      latest_token_collected_at: operations.summary.latest_token_collected_at ?? null,
+      served_at: new Date().toISOString(),
+    },
+  };
+}

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

@@ -177,6 +177,84 @@ created_at: 2026-09-05T10:00:00.000Z
     filesystem.close();
   });
 
+  it("publishes current between bounded rebuild batches before scheduling a follow-up", async () => {
+    const fixtureRoot = await createSqliteFixture();
+    const filesystem = new SqliteReadModelFileSystem(fixtureRoot);
+    let releaseFirst!: () => void;
+    let releaseSecond!: () => void;
+    const refresh = vi
+      .fn()
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            releaseFirst = resolve;
+          }),
+      )
+      .mockImplementationOnce(
+        () =>
+          new Promise<void>((resolve) => {
+            releaseSecond = resolve;
+          }),
+      )
+      .mockResolvedValue(undefined);
+    const app = createDashboardApp(fixtureRoot, "test-session", undefined, {
+      snapshotReadOnly: true,
+      filesystem,
+      refreshReadModel: refresh,
+      layout: v2Layout,
+    });
+    try {
+      const first = app.request("/api/v2/refresh-projection", {
+        method: "POST",
+        headers: { "x-zaip-session": "test-session" },
+      });
+      await vi.waitFor(() => expect(refresh).toHaveBeenCalledTimes(1));
+      void app.request("/api/v2/refresh-projection", {
+        method: "POST",
+        headers: { "x-zaip-session": "test-session" },
+      });
+      releaseFirst();
+      await vi.waitFor(() => expect(refresh).toHaveBeenCalledTimes(2));
+      // A third source request arrives during the bounded second pass.
+      void app.request("/api/v2/refresh-projection", {
+        method: "POST",
+        headers: { "x-zaip-session": "test-session" },
+      });
+      releaseSecond();
+      await expect(first).resolves.toMatchObject({ status: 200 });
+      const ready = await app.request("/api/v2/ready", {
+        headers: { "x-zaip-session": "test-session" },
+      });
+      await expect(ready.json()).resolves.toMatchObject({ snapshot_state: "current" });
+      await vi.waitFor(() => expect(refresh).toHaveBeenCalledTimes(3));
+    } finally {
+      filesystem.close();
+    }
+  });
+
+  it("does not start lifecycle reconciliation when the Dashboard runtime starts", async () => {
+    const fixtureRoot = await createSqliteFixture();
+    const filesystem = new SqliteReadModelFileSystem(fixtureRoot);
+    const reconcile = vi.fn(async () => ({ reconciled_ids: [], blocked: [], not_reconciled: [] }));
+    const app = createDashboardApp(fixtureRoot, "test-session", undefined, {
+      snapshotReadOnly: true,
+      filesystem,
+      canonicalFilesystem: new WorkspaceFileSystem(fixtureRoot),
+      reconcileOpenWork: reconcile,
+      refreshReadModel: async () => undefined,
+      layout: v2Layout,
+      watchSources: true,
+    });
+    try {
+      await new Promise((resolve) => setTimeout(resolve, 1_100));
+      expect(reconcile).not.toHaveBeenCalled();
+      await app.request("/api/v2/ready", { headers: { "x-zaip-session": "test-session" } });
+      expect(reconcile).not.toHaveBeenCalled();
+    } finally {
+      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, {

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

@@ -0,0 +1,13 @@
+import type { WorkspaceFileSystem } from "@zaip-ai/core";
+import type { Context } from "hono";
+import type { requireV2Layout } from "./server-http-contracts.js";
+import type { dashboardSnapshot } from "./server-read-projections.js";
+export interface DashboardRouteContext {
+  filesystem: WorkspaceFileSystem;
+  canonicalFilesystem: WorkspaceFileSystem;
+  isSqliteSnapshot: boolean;
+  readLayout: () => ReturnType<typeof requireV2Layout>;
+  readSnapshot: (context: Context) => ReturnType<typeof dashboardSnapshot>;
+  readAggregate: <T>(key: string, build: () => Promise<T>, fresh?: boolean) => Promise<T>;
+  clearSnapshotCache: () => void;
+}

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

@@ -1,6 +1,21 @@
 import { EventEmitter } from "node:events";
-import { describe, expect, it } from "vitest";
-import { attachRefreshWorkerCleanup } from "./server-snapshot-refresh.js";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { describe, expect, it, vi } from "vitest";
+import {
+  attachRefreshWorkerCleanup,
+  refreshSqliteSnapshotInWorker,
+  validateSnapshotWorkerReceipt,
+} from "./server-snapshot-refresh.js";
+import { SqliteReadModelFileSystem } from "./sqlite-read-model-filesystem.js";
+import {
+  readModelSchemaVersion,
+  requiredIndexes,
+  requiredPersistedTables,
+  requiredViews,
+} from "./sqlite-read-model-schema.js";
 
 describe("snapshot refresh shutdown", () => {
   it("terminates an active refresh worker on runtime shutdown and removes its listener on completion", () => {
@@ -17,3 +32,80 @@ describe("snapshot refresh shutdown", () => {
     expect(calls).toEqual(["SIGTERM"]);
   });
 });
+
+describe("snapshot worker process boundary", () => {
+  it.each([
+    "valid",
+    "empty",
+    "wrong-path",
+    "nonzero",
+    "oversized",
+  ] as const)("reopens only after valid receipt and successful process close: %s", async (mode) => {
+    const root = await mkdtemp(join(tmpdir(), "zaip-refresh-receipt-"));
+    const db = new DatabaseSync(":memory:");
+    const filesystem = new SqliteReadModelFileSystem(root, db);
+    const refresh = vi.spyOn(filesystem, "refresh").mockImplementation(() => undefined);
+    try {
+      const scripts = join(root, ".agents/dashboard/packages/local-runtime/scripts");
+      await mkdir(scripts, { recursive: true });
+      // This fixture tests native transport/failure handling, not DB integrity.
+      // The shipped rebuild script performs the real schema/integrity validation.
+      await writeFile(
+        join(scripts, "rebuild-sqlite-read-model.mjs"),
+        `
+          const receipt = {storage_mode:'sqlite_read_model',
+            path: ${JSON.stringify(mode)} === 'wrong-path' ? 'other.sqlite' : process.env.ZAIP_SQLITE_DB_PATH,
+            schema: ${JSON.stringify({ schemaVersion: readModelSchemaVersion, tableCount: requiredPersistedTables.length, viewCount: requiredViews.length, indexCount: requiredIndexes.length })}};
+          if (${JSON.stringify(mode)} !== 'empty') {
+            if (${JSON.stringify(mode)} === 'oversized') process.stdout.write(' '.repeat(64001));
+            const output = JSON.stringify(receipt);
+            process.stdout.write(output.slice(0, 20));
+            setTimeout(() => process.stdout.write(output.slice(20)), 5);
+          }
+          process.exitCode = ${mode === "nonzero" ? 1 : 0};
+        `,
+      );
+      if (mode === "valid") {
+        await expect(refreshSqliteSnapshotInWorker(root, filesystem)).resolves.toBeUndefined();
+        expect(refresh).toHaveBeenCalledTimes(1);
+      } else {
+        await expect(refreshSqliteSnapshotInWorker(root, filesystem)).rejects.toThrow();
+        expect(refresh).not.toHaveBeenCalled();
+      }
+    } finally {
+      refresh.mockRestore();
+      db.close();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("validated worker receipt", () => {
+  const destination = "snapshot.sqlite";
+  const receipt = {
+    storage_mode: "sqlite_read_model",
+    path: destination,
+    schema: {
+      schemaVersion: readModelSchemaVersion,
+      tableCount: requiredPersistedTables.length,
+      viewCount: requiredViews.length,
+      indexCount: requiredIndexes.length,
+    },
+  };
+  it("accepts the exact schema-validated destination without scanning it on the HTTP thread", () => {
+    // The path need not exist in this process: only the worker does the heavy check.
+    expect(() => validateSnapshotWorkerReceipt(JSON.stringify(receipt), destination)).not.toThrow();
+  });
+  it.each([
+    "",
+    "null",
+    "{}",
+    JSON.stringify({ ...receipt, path: "other.sqlite" }),
+    JSON.stringify({ ...receipt, schema: { ...receipt.schema, schemaVersion: "old" } }),
+    JSON.stringify({ ...receipt, schema: { ...receipt.schema, indexCount: 0 } }),
+    JSON.stringify({ ...receipt, schema: { ...receipt.schema, tableCount: 0 } }),
+    JSON.stringify({ ...receipt, schema: { ...receipt.schema, viewCount: null } }),
+  ])("rejects absent, stale or unrelated validation: %s", (value) => {
+    expect(() => validateSnapshotWorkerReceipt(value, destination)).toThrow();
+  });
+});