@zaip-ai/cli 1.0.8 → 1.3.1

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

@@ -45,7 +45,7 @@ describe("dashboard backend snapshot", () => {
       [
         "lock_version: 1",
         "framework:",
-        "  version: 1.0.8",
+        "  version: 1.3.0",
         "  distribution_sha256: null",
         "layout:",
         "  version: 3",
@@ -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(");
@@ -593,12 +595,27 @@ 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))'),
+      source.indexOf(
+        "if (filteredCostGroup !== undefined && temporalCostGroup && !hasDimensionalCostFilter)",
+      ),
+      source.indexOf(
+        "if (filteredCostGroup !== undefined && (!temporalCostGroup || hasDimensionalCostFilter))",
+      ),
     );
     expect(dailyBranch).not.toContain("costMonitorFactualDurationByDay(");
     expect(dailyBranch).toContain("Daily first fold is an allowlisted table contract");
-    for (const field of ["prd_count", "spec_count", "task_count", "total_run_count", "validation_count", "evidence_count", "total_duration", "duration_known", "total_tokens", "total_cost_brl"])
+    for (const field of [
+      "prd_count",
+      "spec_count",
+      "task_count",
+      "total_run_count",
+      "validation_count",
+      "evidence_count",
+      "total_duration",
+      "duration_known",
+      "total_tokens",
+      "total_cost_brl",
+    ])
       expect(dailyBranch).toContain(`${field}:`);
     expect(dailyBranch).not.toContain("...row,");
   });

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

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import type { WorkspaceLayout } from "@zaip-ai/core";
+import {
+  buildTraceStageRecords,
+  classifyTraceDocument,
+  timestampsFromContent,
+} from "@zaip-ai/dashboard-traceability/server";
+import type { TaskTrace, TraceDocument } from "../../../modules/traceability/src/contracts.js";
+import type { SqliteReadModelFileSystem } from "./sqlite-read-model.js";
+
+export function buildSqliteTaskTrace(
+  filesystem: SqliteReadModelFileSystem,
+  layout: WorkspaceLayout,
+  taskId: string,
+): TaskTrace {
+  const initial = filesystem.canonicalTraceFiles([taskId]);
+  const taskFile = initial.find(
+    (row) =>
+      row.path.includes("/.agents/records/tasks/") || row.path.includes(".agents/records/tasks/"),
+  );
+  if (taskFile === undefined) throw new Error(`Canonical Task ${taskId} was not found`);
+  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, "");
+  };
+  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;
+  const specId = relatedId("spec_id", "SPEC-");
+  const prdId = relatedId("prd_id", "PRD-");
+  const markers = [taskId, changeId, specId, prdId].filter(
+    (value): value is string => value !== null,
+  );
+  const documents = filesystem
+    .canonicalTraceFiles(markers)
+    .filter(
+      (row) => /\.(?:md|json|jsonl|txt|log)$/i.test(row.path) && row.content.length <= 250_000,
+    )
+    .map((row) => {
+      const classification = classifyTraceDocument(row.path);
+      const timestamps = timestampsFromContent(row.content);
+      return {
+        id: createHash("sha256").update(row.path).digest("hex").slice(0, 16),
+        path: row.path,
+        title:
+          row.content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? row.path.split("/").at(-1) ?? row.path,
+        ...classification,
+        content: row.content,
+        ...timestamps,
+      } satisfies TraceDocument;
+    });
+  const stages = buildTraceStageRecords(documents);
+  const coveredStages = new Set(documents.map((document) => document.stage));
+  const risk = scalar("risk");
+  const status = scalar("status");
+  return {
+    schema_version: 2,
+    layout_version: layout.version as 2 | 3,
+    readonly: true,
+    source: ".agents/records",
+    task_id: taskId,
+    task_title: scalar("title") ?? taskFile.content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? taskId,
+    task_risk: risk === "lite" || risk === "standard" || risk === "critical" ? risk : null,
+    task_created_at: scalar("created_at"),
+    task_progress:
+      status === "completed"
+        ? 100
+        : status === "verifying"
+          ? 80
+          : status === "executing"
+            ? 50
+            : status === "blocked" || status === "failed" || status === "cancelled"
+              ? 0
+              : 10,
+    spec_id: specId,
+    prd_id: prdId,
+    change_id: changeId,
+    usage: filesystem.taskTraceUsage(taskId),
+    documents,
+    stages,
+    coverage: {
+      stages_with_documents: coveredStages.size,
+      stages_with_timestamps: stages.filter((stage) => stage.status === "recorded").length,
+      total_stages: 6,
+      evidence_count: documents.filter((document) => document.kind === "evidence").length,
+      test_count: documents.filter((document) => document.kind === "test").length,
+    },
+  };
+}

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

@@ -51,7 +51,10 @@ export function githubRepositoryFromRemote(remote: string): string | null {
 }
 
 export function dashboardWorkspaceKey(workspaceRoot: string): string {
-  return createHash("sha256").update(`${resolve(workspaceRoot)}:dashboard-sqlite`).digest("hex").slice(0, 16);
+  return createHash("sha256")
+    .update(`${resolve(workspaceRoot)}:dashboard-sqlite`)
+    .digest("hex")
+    .slice(0, 16);
 }
 
 export interface ReconciliationItem {
@@ -104,11 +107,12 @@ export function reconciliationResult(value: unknown): ReconciliationResult {
       const record = entity as Record<string, unknown>;
       if (
         item.status === "closed" &&
-        record.status === "completed" &&
+        ["completed", "blocked", "cancelled", "failed"].includes(record.status as string) &&
         typeof record.id === "string"
       ) {
         reconciled.add(record.id);
-      } else if (record.status === "blocked") {
+      }
+      if (record.status === "blocked") {
         remember(blocked, record.id, record.status_reason ?? reason);
       } else if (item.status === "deferred") {
         remember(notReconciled, record.id, reason);

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

@@ -1,4 +1,37 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { InvocationSummaryV1 } from "@zaip-ai/costs";
+import { rebuildSqliteReadModel, SqliteReadModelFileSystem } from "./sqlite-read-model.js";
+
+export async function withSqliteReadModelFixture<T>(
+  name: string,
+  run: (fixture: { root: string; filesystem: SqliteReadModelFileSystem }) => Promise<T>,
+): Promise<T> {
+  const root = await mkdtemp(join(tmpdir(), `zaip-dashboard-${name}-`));
+  const previousDbPath = process.env.ZAIP_SQLITE_DB_PATH;
+  process.env.ZAIP_SQLITE_DB_PATH = join(root, "read-model.sqlite");
+  let filesystem: SqliteReadModelFileSystem | undefined;
+  try {
+    await mkdir(join(root, ".agents", "config"), { recursive: true });
+    await writeFile(
+      join(root, ".agents", "config", "project.yaml"),
+      `schema_version: 1\nproject:\n  id: ${name}\n  name: ${name}\n  timezone: UTC\nstack:\n  id: zaip-aios-stack\n  overrides: {}\nclients:\n  codex: true\n  claude: true\ntracking:\n  enabled: true\n  currency: BRL\n  storage_mode: tracked_sanitized\n`,
+    );
+    await writeFile(
+      join(root, ".agents", "config", "framework.lock.yaml"),
+      "lock_version: 1\nframework:\n  version: 1.3.0\n  distribution_sha256: null\nlayout:\n  version: 3\nresolved_profile:\n  id: null\n  sha256: null\nmanaged_files: {}\n",
+    );
+    await rebuildSqliteReadModel(root);
+    filesystem = new SqliteReadModelFileSystem(root);
+    return await run({ root, filesystem });
+  } finally {
+    filesystem?.close();
+    if (previousDbPath === undefined) delete process.env.ZAIP_SQLITE_DB_PATH;
+    else process.env.ZAIP_SQLITE_DB_PATH = previousDbPath;
+    await rm(root, { recursive: true, force: true });
+  }
+}
 
 export function pricingCatalog(inputRate: number) {
   return {
@@ -76,6 +109,9 @@ export function invocationSummary(
     zaip_agent: "zaip-agent-orchestrator",
     phase: "execution",
     purpose: "orchestration",
+    // Legacy fixtures remain valid while current invocation contracts carry a
+    // nullable developer identity.
+    developer_identity: null,
     occurred_at: "2026-07-26T12:00:00.000Z",
     status: "completed",
     coverage: "complete",