@zaip-ai/cli 4.5.0 → 4.7.0

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-schema-base-views.ts

@@ -1,4 +1,5 @@
 import { costInvocationProjectionSelect } from "./sqlite-cost-invocation-projection.js";
+import { specRootElapsedViewSql } from "./sqlite-spec-root-elapsed-view.js";
 export const baseViewSql = `
         CREATE INDEX zaip_activities_agent_run ON zaip_aios_activities(activity_source_kind, agent_run_id, occurred_day_sp, occurred_at DESC);
         CREATE INDEX zaip_activities_relationships ON zaip_aios_activities(task_id, spec_id, prd_id, execution_id, conversation_id);
@@ -55,6 +56,7 @@ export const baseViewSql = `
               WHERE allocation.spec_id=a.spec_id AND allocation.run_id=a.run_id
             )
           UNION ALL SELECT * FROM shared_creation_allocations;
+        ${specRootElapsedViewSql}
         CREATE VIEW attributed_token_active AS
           SELECT f.activity_row_id, f.occurred_day_sp, f.attributed_token_active_ms,
             a.run_id, a.execution_id, a.task_id, a.spec_id, a.prd_id, a.conversation_id,
@@ -214,11 +216,11 @@ export const baseViewSql = `
             SELECT day, interval_group, MIN(start_ms) AS start_ms, MAX(end_ms) AS end_ms
             FROM cost_monitor_grouped_intervals GROUP BY day, interval_group
           ), cost_monitor_daily_duration AS (
-            -- Tempo is the shared attributed activity fact. Financial
-            -- coverage is reported independently below; an incomplete price
-            -- record must never erase an observed temporal fact.
-            SELECT occurred_day_sp AS day, SUM(attributed_token_active_ms) AS total_duration
-            FROM attributed_token_active_facts GROUP BY occurred_day_sp
+            -- Cost daily duration is factual elapsed time from source intervals.
+            -- The union removes root/subrun overlap; token-active allocation
+            -- remains a distinct Operations and attribution measure.
+            SELECT day, ROUND(SUM(end_ms - start_ms)) AS total_duration
+            FROM cost_monitor_merged_intervals GROUP BY day
           ), cost_monitor_duration_coverage AS (
             SELECT day, COUNT(DISTINCT activity_id) AS eligible_runs,
               COUNT(DISTINCT activity_id) AS known_runs
@@ -267,7 +269,7 @@ export const baseViewSql = `
             i.total_root_run_duration,
             i.total_sub_run_duration,
             o.total_duration AS operations_total_duration,
-            COALESCE(dcm.total_duration, o.total_duration) AS cost_monitor_total_duration,
+            dcm.total_duration AS cost_monitor_total_duration,
             coverage.eligible_runs AS cost_monitor_duration_eligible_runs,
             coverage.known_runs AS cost_monitor_duration_known_runs,
             o.total_duration AS total_duration,
@@ -305,7 +307,7 @@ export const baseViewSql = `
         -- population rather than Operations' broader Run/activity totals.
         CREATE VIEW cost_monitor_overview AS SELECT period_kind, period_key, cost_monitor_invocation_count AS total_run_count, cost_monitor_invocation_count AS invocation_count, llm_call_count, source_event_count, cost_monitor_total_duration, total_tokens, total_cost_usd, total_cost_brl FROM overview;
         CREATE VIEW task_summary AS SELECT t.id, t.title, t.status, t.risk, t.occurred_at, t.occurred_day_sp, COUNT(i.run_id) AS invocation_count, SUM(i.llm_call_count) AS llm_call_count, SUM(i.duration_ms) AS total_duration, SUM(i.total_tokens) AS total_tokens, SUM(i.cost_usd) AS total_cost_usd, SUM(i.cost_brl) AS total_cost_brl FROM tasks t LEFT JOIN activities i ON i.task_id = t.id GROUP BY t.id, t.title, t.status, t.risk, t.occurred_at, t.occurred_day_sp;
-        CREATE VIEW spec_summary AS SELECT s.id, s.title, s.status, s.risk, s.occurred_at, s.occurred_day_sp, COUNT(i.run_id) AS invocation_count, SUM(i.llm_call_count) AS llm_call_count, SUM(i.duration_ms) AS total_duration, SUM(i.total_tokens) AS total_tokens, SUM(i.cost_usd) AS total_cost_usd, SUM(i.cost_brl) AS total_cost_brl FROM specs s LEFT JOIN macro_spec_activities i ON i.spec_id = s.id GROUP BY s.id, s.title, s.status, s.risk, s.occurred_at, s.occurred_day_sp;
+        CREATE VIEW spec_summary AS SELECT s.id, s.title, s.status, s.risk, s.occurred_at, s.occurred_day_sp, COUNT(i.run_id) AS invocation_count, SUM(i.llm_call_count) AS llm_call_count, elapsed.total_duration_ms AS total_duration, SUM(i.total_tokens) AS total_tokens, SUM(i.cost_usd) AS total_cost_usd, SUM(i.cost_brl) AS total_cost_brl FROM specs s LEFT JOIN macro_spec_activities i ON i.spec_id = s.id LEFT JOIN spec_root_elapsed elapsed ON elapsed.spec_id=s.id GROUP BY s.id, s.title, s.status, s.risk, s.occurred_at, s.occurred_day_sp;
         CREATE VIEW prd_summary AS SELECT p.id, p.title, p.status, p.risk, p.occurred_at, p.occurred_day_sp, COUNT(i.run_id) AS invocation_count, SUM(i.llm_call_count) AS llm_call_count, SUM(i.duration_ms) AS total_duration, SUM(i.total_tokens) AS total_tokens, SUM(i.cost_usd) AS total_cost_usd, SUM(i.cost_brl) AS total_cost_brl FROM prds p LEFT JOIN activities i ON i.prd_id = p.id GROUP BY p.id, p.title, p.status, p.risk, p.occurred_at, p.occurred_day_sp;
         CREATE VIEW cost_monitor_group_daily AS SELECT * FROM cost_monitor_group_daily_cache;
         CREATE VIEW vw_overview AS SELECT * FROM overview;

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-schema-dashboard-views.ts

@@ -51,7 +51,9 @@ export const dashboardViewSql = `        CREATE VIEW vw_operations_work_list AS
             FROM entity_activity GROUP BY entity_kind, entity_id
           ), durations AS (
             SELECT entity_kind, entity_id, ROUND(SUM(duration_ms)) AS total_duration
-            FROM entity_activity GROUP BY entity_kind, entity_id
+            FROM entity_activity WHERE entity_kind <> 'spec' GROUP BY entity_kind, entity_id
+            UNION ALL
+            SELECT 'spec', spec_id, total_duration_ms FROM spec_root_elapsed
           )
           SELECT w.entity_kind, w.id, w.title, w.status, w.risk, w.occurred_at, w.occurred_day_sp,
             f.invocation_count, f.llm_call_count, d.total_duration,
@@ -231,7 +233,6 @@ export const dashboardViewSql = `        CREATE VIEW vw_operations_work_list AS
           WITH usage AS (
             SELECT spec_id,
               COUNT(*) AS total_run_count,
-              ROUND(SUM(duration_ms)) AS total_duration_ms,
               SUM(total_tokens) AS total_tokens,
               SUM(cost_usd) AS total_cost_usd,
               SUM(cost_brl) AS total_cost_brl
@@ -239,16 +240,17 @@ export const dashboardViewSql = `        CREATE VIEW vw_operations_work_list AS
           )
           SELECT COUNT(*) AS entity_count,
             SUM(usage.total_run_count) AS total_run_count,
-            SUM(usage.total_duration_ms) AS total_duration_ms,
+            SUM(elapsed.total_duration_ms) AS total_duration_ms,
             SUM(usage.total_tokens) AS total_tokens,
             SUM(usage.total_cost_usd) AS total_cost_usd,
             SUM(usage.total_cost_brl) AS total_cost_brl,
-            CASE WHEN COUNT(*)=0 THEN NULL ELSE SUM(usage.total_duration_ms)/COUNT(*) END AS average_duration_ms,
+            CASE WHEN COUNT(*)=0 THEN NULL ELSE SUM(elapsed.total_duration_ms)/COUNT(*) END AS average_duration_ms,
             CASE WHEN COUNT(*)=0 THEN NULL ELSE SUM(usage.total_tokens)/COUNT(*) END AS average_tokens,
             CASE WHEN COUNT(*)=0 THEN NULL ELSE SUM(usage.total_cost_usd)/COUNT(*) END AS average_cost_usd,
             CASE WHEN COUNT(*)=0 THEN NULL ELSE SUM(usage.total_cost_brl)/COUNT(*) END AS average_cost_brl,
             MAX(s.occurred_at) AS latest_created_at
-          FROM spec_summary s LEFT JOIN usage ON usage.spec_id=s.id;
+          FROM spec_summary s LEFT JOIN usage ON usage.spec_id=s.id
+            LEFT JOIN spec_root_elapsed elapsed ON elapsed.spec_id=s.id;
         CREATE VIEW vw_first_fold_prd_metrics_all_time AS
           WITH usage AS (
             SELECT prd_id,
@@ -276,16 +278,16 @@ export const dashboardViewSql = `        CREATE VIEW vw_operations_work_list AS
             SELECT spec_id,
               COUNT(*) AS total_run_count,
               SUM(llm_call_count) AS llm_call_count,
-              ROUND(SUM(duration_ms)) AS total_duration_ms,
               SUM(total_tokens) AS total_tokens,
               SUM(cost_usd) AS total_cost_usd,
               SUM(cost_brl) AS total_cost_brl
             FROM macro_spec_activities GROUP BY spec_id
           ), ranked AS (
             SELECT s.id AS entity_id, s.title, s.status, usage.total_run_count, usage.llm_call_count,
-              usage.total_duration_ms, usage.total_tokens, usage.total_cost_usd, usage.total_cost_brl,
-              ROW_NUMBER() OVER (ORDER BY usage.total_duration_ms IS NOT NULL DESC, usage.total_duration_ms DESC, usage.total_run_count DESC, s.id) AS rank
+              elapsed.total_duration_ms, usage.total_tokens, usage.total_cost_usd, usage.total_cost_brl,
+              ROW_NUMBER() OVER (ORDER BY elapsed.total_duration_ms IS NOT NULL DESC, elapsed.total_duration_ms DESC, usage.total_run_count DESC, s.id) AS rank
             FROM spec_summary s LEFT JOIN usage ON usage.spec_id=s.id
+              LEFT JOIN spec_root_elapsed elapsed ON elapsed.spec_id=s.id
           ), total AS (SELECT SUM(total_duration_ms) AS total_duration_ms FROM ranked)
           SELECT ranked.rank, ranked.entity_id, ranked.title, ranked.status,
             COALESCE(ranked.total_run_count,0) AS total_run_count, ranked.llm_call_count,

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-spec-root-elapsed-view.ts

@@ -0,0 +1,61 @@
+/**
+ * SPEC elapsed time is the union of factual root Run intervals within each
+ * SPEC. A root and its children must not both contribute elapsed time. A Run
+ * linked to two SPECs remains visible in each; the cross-SPEC sum is therefore
+ * a sum of entity durations, not a global wall-clock total.
+ */
+export const specRootElapsedViewSql = `
+        CREATE VIEW spec_root_elapsed AS
+          WITH roots AS (
+            SELECT spec_id, run_id,
+              MAX(source_duration_ms) AS source_duration_ms,
+              MIN(source_started_at) AS source_started_at,
+              MAX(source_finished_at) AS source_finished_at
+            FROM macro_spec_activities
+            WHERE spec_id IS NOT NULL AND run_role='root'
+            GROUP BY spec_id, run_id
+          ), source_intervals AS (
+            SELECT spec_id,
+              (julianday(source_started_at) - 2440587.5) * 86400000.0 AS start_ms,
+              (julianday(source_finished_at) - 2440587.5) * 86400000.0 AS end_ms
+            FROM roots
+            WHERE source_started_at IS NOT NULL AND source_finished_at IS NOT NULL
+              AND julianday(source_finished_at) > julianday(source_started_at)
+          ), ordered AS (
+            SELECT spec_id, start_ms, end_ms,
+              MAX(end_ms) OVER (
+                PARTITION BY spec_id ORDER BY start_ms, end_ms
+                ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING
+              ) AS prior_end_ms
+            FROM source_intervals
+          ), grouped AS (
+            SELECT spec_id, start_ms, end_ms,
+              SUM(CASE WHEN prior_end_ms IS NULL OR start_ms > prior_end_ms THEN 1 ELSE 0 END)
+                OVER (PARTITION BY spec_id ORDER BY start_ms, end_ms) AS interval_group
+            FROM ordered
+          ), merged AS (
+            SELECT spec_id, interval_group, MIN(start_ms) AS start_ms, MAX(end_ms) AS end_ms
+            FROM grouped GROUP BY spec_id, interval_group
+          ), source_totals AS (
+            SELECT spec_id, SUM(end_ms - start_ms) AS duration_ms
+            FROM merged GROUP BY spec_id
+          ), fallback_totals AS (
+            -- A terminal factual duration without source boundaries remains
+            -- available, but cannot be unioned against another Run interval.
+            SELECT spec_id, SUM(source_duration_ms) AS duration_ms
+            FROM roots
+            WHERE source_duration_ms IS NOT NULL
+              AND NOT (
+                source_started_at IS NOT NULL AND source_finished_at IS NOT NULL
+                AND julianday(source_finished_at) > julianday(source_started_at)
+              )
+            GROUP BY spec_id
+          ), known_specs AS (
+            SELECT spec_id FROM source_totals UNION SELECT spec_id FROM fallback_totals
+          )
+          SELECT known_specs.spec_id,
+            ROUND(COALESCE(source_totals.duration_ms, 0) + COALESCE(fallback_totals.duration_ms, 0)) AS total_duration_ms
+          FROM known_specs
+          LEFT JOIN source_totals USING(spec_id)
+          LEFT JOIN fallback_totals USING(spec_id);
+`;

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-spec-root-elapsed.test.ts

@@ -0,0 +1,210 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, expect, it } from "vitest";
+import { rebuildSqliteReadModel, SqliteReadModelFileSystem } from "./sqlite-read-model.js";
+
+const roots: string[] = [];
+afterEach(async () => {
+  await Promise.all(
+    roots
+      .splice(0)
+      .map((root) =>
+        import("node:fs/promises").then(({ rm }) => rm(root, { recursive: true, force: true })),
+      ),
+  );
+});
+
+it("shows a 21-hour source-observed SPEC root and splits Cost elapsed without child double counting", async () => {
+  const temp = resolve(import.meta.dirname, "../../../../../..", ".tmp", "sqlite-read-model-tests");
+  await mkdir(temp, { recursive: true });
+  const root = await mkdtemp(join(temp, "spec-elapsed-"));
+  roots.push(root);
+  const records = join(root, ".agents", "records");
+  await mkdir(join(records, "runs", "2026", "09"), { recursive: true });
+  await mkdir(join(records, "specs", "2026", "09"), { recursive: true });
+  await mkdir(join(root, ".agents", "config"), { recursive: true });
+  await writeFile(join(root, ".agents", "config", "project.yaml"), "zaip:\n  enabled: true\n");
+  for (const id of ["SPEC-ROOT", "SPEC-CHILD"])
+    await writeFile(
+      join(records, "specs", "2026", "09", `${id}.md`),
+      `---\nid: ${id}\ntitle: ${id}\nstatus: active\nrisk: standard\ncreated_at: 2026-09-30T22:00:00.000Z\n---\n# ${id}\n`,
+    );
+
+  const sourceStart = "2026-09-30T22:41:41.072Z";
+  const sourceEnd = "2026-10-01T19:55:46.569Z";
+  const run = (id: string, specId: string, start: string, end: string, parent: string | null) => {
+    const invocation = `AINV-${id}`;
+    return [
+      {
+        schema_version: 2,
+        event_id: `${id}:1`,
+        run_id: id,
+        sequence: 1,
+        occurred_at: start,
+        type: "run.started",
+        attribution_status: "attributed",
+        phase: "execution",
+        run_role: parent === null ? "orchestrator" : "subagent",
+        run_purpose: "execution",
+        requires_finalizer: false,
+        execution_kind: "delivery",
+        execution_eligibility: ["delivery"],
+        entrypoint: "spec",
+        work_type: "new",
+        storage_mode: "tracked_sanitized",
+        client: "codex",
+        agent: "agent",
+        agent_name: "agent",
+        provider: "openai",
+        model: "gpt-6-sol",
+        reasoning_effort: null,
+        client_thread_id: `thread-${id}`,
+        client_turn_id: `turn-${id}`,
+        conversation_id: "CONV-SPEC",
+        execution_id: "EXEC-SPEC",
+        task_id: null,
+        spec_id: specId,
+        prd_id: null,
+        change_id: null,
+        parent_run_id: parent,
+        continuation_of_run_id: null,
+        retry_of_run_id: null,
+        agent_invocation_id: invocation,
+        root_agent_invocation_id: parent === null ? invocation : "AINV-RUN-ROOT",
+        parent_agent_invocation_id: parent === null ? null : "AINV-RUN-ROOT",
+        invocation_kind: parent === null ? "orchestrator" : "delegated",
+        delegation_depth: parent === null ? 0 : 1,
+      },
+      {
+        schema_version: 2,
+        event_id: `${id}:2`,
+        run_id: id,
+        sequence: 2,
+        occurred_at: end,
+        type: "usage.recorded",
+        phase: "execution",
+        activity_kind: "model_usage",
+        classification_source: "explicit",
+        tokens: {
+          input: 100,
+          cached_input: 0,
+          output: 20,
+          reasoning: 0,
+          total: 120,
+          source: "provider_reported",
+        },
+        cost: { usd: 1, brl: 5, fx_rate: 5 },
+        provider: "openai",
+        model: "gpt-6-sol",
+        source_segment_key: id,
+        model_call_id: `MCALL-${id}`,
+        runtime: { reasoning_effort: null, service_tier: null },
+        supersedes_event_id: null,
+        source_occurred_at: end,
+        source_started_at: start,
+        source_finished_at: end,
+        duration_ms: null,
+        duration_provenance: null,
+      },
+    ];
+  };
+  for (const [id, specId, start, end, parent] of [
+    ["RUN-ROOT", "SPEC-ROOT", sourceStart, sourceEnd, null],
+    ["RUN-OVERLAP", "SPEC-ROOT", "2026-10-01T04:30:00.000Z", "2026-10-01T05:30:00.000Z", null],
+    ["RUN-CHILD", "SPEC-CHILD", "2026-10-01T04:00:00.000Z", "2026-10-01T05:00:00.000Z", "RUN-ROOT"],
+    ["RUN-UNKNOWN", "SPEC-CHILD", "2026-10-02T12:00:00.000Z", "2026-10-02T12:00:00.000Z", null],
+  ] as const)
+    await writeFile(
+      join(records, "runs", "2026", "09", `${id}.jsonl`),
+      `${run(id, specId, start, end, parent)
+        .map((event) => JSON.stringify(event))
+        .join("\n")}\n`,
+    );
+
+  await rebuildSqliteReadModel(root);
+  const db = new DatabaseSync(resolve(root, ".local/sqlite/zaip-aios-dashboard.sqlite"), {
+    readOnly: true,
+  });
+  const observed = Date.parse(sourceEnd) - Date.parse(sourceStart);
+  expect(observed).toBe(76_445_497);
+  expect(
+    db.prepare("SELECT source_duration_ms FROM zaip_aios_activities WHERE run_id='RUN-ROOT'").get(),
+  ).toEqual({ source_duration_ms: observed });
+  expect(
+    db
+      .prepare("SELECT spec_id, total_duration_ms FROM zaip_vw_spec_root_elapsed ORDER BY spec_id")
+      .all(),
+  ).toEqual([{ spec_id: "SPEC-ROOT", total_duration_ms: observed }]);
+  expect(
+    db
+      .prepare(
+        "SELECT entity_id, total_duration_ms FROM zaip_vw_first_fold_top_specs_all_time ORDER BY rank LIMIT 1",
+      )
+      .get(),
+  ).toEqual({ entity_id: "SPEC-ROOT", total_duration_ms: observed });
+  expect(
+    db.prepare("SELECT total_duration_ms FROM zaip_vw_first_fold_spec_metrics_all_time").get(),
+  ).toEqual({ total_duration_ms: observed });
+  expect(
+    db
+      .prepare("SELECT period_key, total_duration FROM zaip_vw_cost_daily ORDER BY period_key")
+      .all(),
+  ).toEqual([
+    { period_key: "2026-09-30", total_duration: 15_498_928 },
+    { period_key: "2026-10-01", total_duration: 60_946_569 },
+    { period_key: "2026-10-02", total_duration: null },
+  ]);
+  db.close();
+  const filesystem = new SqliteReadModelFileSystem(root);
+  const allTimeCost = filesystem.costMonitorSummaryAggregate({ from: null, to: null });
+  expect(allTimeCost.cost_monitor_daily_duration).toMatchObject({
+    "2026-09-30": { known_sum: 15_498_928 },
+    "2026-10-01": { known_sum: 60_946_569 },
+    "2026-10-02": { known_sum: 0, known_runs: 0, eligible_runs: 1 },
+  });
+  expect(allTimeCost.daily_rows).toContainEqual(
+    expect.objectContaining({ key: "2026-10-02", total_duration: null }),
+  );
+  const unknownFiltered = filesystem.costMonitorSummaryAggregate({
+    from: "2026-10-02",
+    to: "2026-10-02",
+    specs: ["SPEC-CHILD"],
+  });
+  expect(unknownFiltered.cost_monitor_daily_duration).toMatchObject({
+    "2026-10-02": { known_sum: 0, known_runs: 0, eligible_runs: 1 },
+  });
+  expect(unknownFiltered.daily_rows).toContainEqual(
+    expect.objectContaining({ key: "2026-10-02", total_duration: null }),
+  );
+  const secondDayCost = filesystem.costMonitorSummaryAggregate({
+    from: "2026-10-01",
+    to: "2026-10-01",
+  });
+  expect(secondDayCost.cost_monitor_daily_duration).toMatchObject({
+    "2026-10-01": { known_sum: 60_946_569 },
+  });
+  expect(secondDayCost.cost_monitor_daily_duration).not.toHaveProperty("2026-09-30");
+  const filteredCost = filesystem.costMonitorSummaryAggregate({
+    from: "2026-10-01",
+    to: "2026-10-01",
+    specs: ["SPEC-ROOT"],
+  });
+  expect(filteredCost.cost_monitor_daily_duration).toMatchObject({
+    "2026-10-01": { known_sum: 60_946_569 },
+  });
+  const unknownDay = { from: "2026-10-02", to: "2026-10-02" };
+  expect(
+    filesystem.costMonitorSummaryAggregate(unknownDay).cost_monitor_daily_duration,
+  ).toMatchObject({
+    "2026-10-02": { known_sum: 0, eligible_runs: 1, known_runs: 0 },
+  });
+  expect(
+    filesystem.costMonitorSummaryAggregate({ ...unknownDay, specs: ["SPEC-CHILD"] })
+      .cost_monitor_daily_duration,
+  ).toMatchObject({ "2026-10-02": { known_sum: 0, eligible_runs: 1, known_runs: 0 } });
+  expect(filesystem.summaryPage("spec", { from: null, to: null }, 0, 10).rows).toContainEqual(
+    expect.objectContaining({ id: "SPEC-ROOT", total_duration: observed }),
+  );
+  filesystem.close();
+});

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

@@ -0,0 +1,87 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SqliteReadModelFileSystem } from "./sqlite-read-model-filesystem.js";
+import { rebuildSqliteReadModel } from "./sqlite-read-model-rebuild.js";
+import { validateSqliteReadModelSchema } from "./sqlite-read-model-schema.js";
+import * as fingerprints from "./sqlite-read-model-source-fingerprint.js";
+
+const roots: string[] = [];
+const source = ".agents/records/tasks/TASK-STARTUP.md";
+const record = (title: string) =>
+  `---\nid: TASK-STARTUP\ntitle: ${title}\nstatus: executing\ncreated_at: 2026-09-29T12:00:00Z\n---\n`;
+async function fixture() {
+  const parent = resolve(import.meta.dirname, "../../../../..", ".local/sqlite/tests");
+  await mkdir(parent, { recursive: true });
+  const root = await mkdtemp(join(parent, "startup-seed-"));
+  roots.push(root);
+  await mkdir(join(root, ".agents/records/tasks"), { recursive: true });
+  await writeFile(join(root, source), record("Before"));
+  return root;
+}
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+describe("validated startup generation", () => {
+  it("serves a seed without traversing sources, then canonical refresh observes the changed record", async () => {
+    const root = await fixture();
+    await rebuildSqliteReadModel(root);
+    await writeFile(join(root, source), record("After"));
+    const fingerprint = vi.spyOn(fingerprints, "sourceFingerprint");
+    const sql = vi.spyOn(DatabaseSync.prototype, "prepare");
+    const result = await rebuildSqliteReadModel(root, {
+      preferExisting: true,
+      sourceRoots: ["invalid-startup-root"],
+    });
+    expect(result).toMatchObject({ cache: "stale_seed", fingerprint_ms: 0, materialize_ms: 0 });
+    expect(fingerprint).not.toHaveBeenCalled();
+    expect(sql).toHaveBeenCalledWith("PRAGMA quick_check");
+    expect(sql).not.toHaveBeenCalledWith("PRAGMA integrity_check");
+    const reader = new SqliteReadModelFileSystem(root);
+    try {
+      expect(await reader.readText(source)).toContain("title: Before");
+      await rebuildSqliteReadModel(root);
+      expect(sql).toHaveBeenCalledWith("PRAGMA integrity_check");
+      reader.refresh();
+      expect(await reader.readText(source)).toContain("title: After");
+    } finally {
+      reader.close();
+    }
+  });
+
+  it.each([
+    "old-schema",
+    "missing-index",
+    "missing-payload",
+  ])("rebuilds %s rather than serving incomplete seed", async (damage) => {
+    const root = await fixture();
+    const first = await rebuildSqliteReadModel(root);
+    const database = new DatabaseSync(first.path);
+    try {
+      if (damage === "old-schema")
+        database.exec(
+          "UPDATE zaip_aios_activities SET payload_json=json_set(payload_json,'$.value','0') WHERE payload_type='metadata' AND json_extract(payload_json,'$.key')='schema_version'",
+        );
+      else if (damage === "missing-index")
+        database.exec("DROP INDEX zaip_activities_work_item_identity");
+      else
+        database.exec(
+          "DELETE FROM zaip_aios_activities WHERE payload_type='first_fold_all_time_board_cache'",
+        );
+    } finally {
+      database.close();
+    }
+    expect((await rebuildSqliteReadModel(root, { preferExisting: true })).cache).toBe("rebuilt");
+    expect(() => validateSqliteReadModelSchema(first.path)).not.toThrow();
+  });
+
+  it("rejects corrupt bytes and never serves them as a validated seed", async () => {
+    const root = await fixture();
+    const first = await rebuildSqliteReadModel(root);
+    await writeFile(first.path, "corrupt SQLite bytes");
+    expect(() => validateSqliteReadModelSchema(first.path, { integrity: "quick" })).toThrow();
+    await expect(rebuildSqliteReadModel(root, { preferExisting: true })).rejects.toThrow();
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/start-dashboard-logging.mjs

@@ -1,11 +1,15 @@
 import { appendFileSync, mkdirSync } from "node:fs";
-import { launcherLogPath, sessionDirectory } from "./start-dashboard-paths.mjs";
+import { createDashboardDiagnostics, sanitizeDiagnostic } from "./dashboard-diagnostics.mjs";
+import { launcherLogPath, sessionDirectory, workspaceRoot } from "./start-dashboard-paths.mjs";
+export const launcherDiagnostics = createDashboardDiagnostics(workspaceRoot, "launcher");
+process.env.ZAIP_DASHBOARD_LAUNCH_ID = launcherDiagnostics.correlationId;
 export function appendLauncherLog(message) {
+  launcherDiagnostics.log("launcher_message", { message });
   try {
     mkdirSync(sessionDirectory, { recursive: true });
     appendFileSync(
       launcherLogPath,
-      `[${new Date().toISOString()}] ${stripTerminalControlCodes(message)}\n`,
+      `[${new Date().toISOString()}] ${stripTerminalControlCodes(sanitizeDiagnostic(message))}\n`,
       "utf8",
     );
   } catch {

package/templates/.agents/dashboard/packages/local-runtime/start-dashboard-server.mjs

@@ -55,12 +55,18 @@ export async function startDashboardServer({
         ZAIP_SQLITE_PREFER_LAST_VALID_SEED: "0",
         ZAIP_SQLITE_DB_PATH: dbPath,
       },
-      stdio: ["ignore", "ignore", "pipe"],
+      stdio: ["ignore", "pipe", "pipe"],
       windowsHide: true,
     });
     onChildStarted(child);
+    appendLog(`Runtime spawned: pid=${child.pid} port=${port} attempt=${attempt}`);
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) =>
+      appendLog(`runtime stdout: ${String(chunk).slice(0, 16000)}`),
+    );
     child.stderr?.setEncoding("utf8");
     child.stderr?.on("data", (chunk) => {
+      appendLog(`runtime stderr: ${String(chunk).slice(0, 16000)}`);
       stderr = `${stderr}${chunk}`.slice(-4_000);
       startupTelemetryBuffer = `${startupTelemetryBuffer}${String(chunk)}`;
       const lines = startupTelemetryBuffer.split("\n");

package/templates/.agents/dashboard/packages/local-runtime/start-dashboard.mjs

@@ -3,7 +3,6 @@ import {
   dashboardUrl,
   findAvailablePortWithFallback,
   openBrowser,
-  preferredPort,
 } from "./start-dashboard-navigation.mjs";
 
 export {
@@ -23,6 +22,7 @@ import {
 import {
   appendLauncherLog,
   formatLauncherError,
+  launcherDiagnostics,
   stripTerminalControlCodes,
 } from "./start-dashboard-logging.mjs";
 import {
@@ -36,7 +36,6 @@ import {
   lockHeartbeatFloorMs,
   lockPath,
   lockTimeoutMs,
-  maxPortAttempts,
   maxPortHistory,
   maxServerStartAttempts,
   nodeCompileCacheDirectory,
@@ -494,6 +493,7 @@ async function startDashboardServer(
   });
 }
 async function main() {
+  launcherDiagnostics.log("launcher_entered");
   let ownedChild = null;
   let currentSession = null;
   let launchPage = null;
@@ -741,9 +741,8 @@ async function waitForDashboard(port, child) {
     await delay(100);
   }
 }
-function delay(milliseconds) {
-  return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
-}
+const delay = (milliseconds) =>
+  new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
 const isMain = process.argv[1]
   ? resolve(process.argv[1]) === fileURLToPath(import.meta.url)
   : false;

package/templates/.agents/dashboard/packages/ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-ui",
-  "version": "4.5.0",
+  "version": "4.7.0",
   "private": true,
   "type": "module",
   "exports": {

package/templates/.agents/dashboard/packages/ui/src/DashboardHeader.test.mjs

@@ -1,8 +1,10 @@
 import { readFileSync } from "node:fs";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it } from "vitest";
+import { DashboardHeader } from "./DashboardHeader.tsx";
 
 const styles = readFileSync(new URL("ui.css", import.meta.url), "utf8");
-const headerSource = readFileSync(new URL("DashboardHeader.tsx", import.meta.url), "utf8");
 
 describe("DashboardHeader", () => {
   it("optically balances the repository badge horizontal spacing", () => {
@@ -10,12 +12,39 @@ describe("DashboardHeader", () => {
     expect(rule).toContain("padding-block: 0.3rem");
     expect(rule).toContain("padding-inline: 0.6rem 0.72rem");
   });
-  it("labels the timestamp as telemetry rather than overall snapshot freshness", () => {
-    expect(headerSource).toContain('updated: "Última telemetria"');
-    expect(headerSource).toContain('waiting: "Sem telemetria medida"');
+  it.each(["pt-BR", "en-US"])("shows only snapshot freshness in %s", (locale) => {
+    const telemetry = "2026-09-29T11:32:27Z";
+    const snapshot = "2026-09-29T12:59:35Z";
+    const markup = renderHeader({ locale, lastUpdatedAt: telemetry, snapshotUpdatedAt: snapshot });
+    const formatted = new Intl.DateTimeFormat(locale, { dateStyle: "short", timeStyle: "medium" });
+    expect(markup.match(/<small>/g)).toHaveLength(1);
+    expect(markup).toContain(locale === "pt-BR" ? "Última Atualização" : "Last Updated");
+    expect(markup).toContain(formatted.format(new Date(snapshot)));
+    expect(markup).not.toContain(formatted.format(new Date(telemetry)));
+  });
+  it("keeps an unavailable snapshot explicit even when telemetry exists", () => {
+    const markup = renderHeader({ lastUpdatedAt: "2026-09-29T11:32:27Z" });
+    expect(markup.match(/<small>/g)).toHaveLength(1);
+    expect(markup).toContain("Atualização indisponível");
+    expect(markup).not.toContain("11:32:27");
   });
 });
 
+function renderHeader(props) {
+  return renderToStaticMarkup(
+    createElement(DashboardHeader, {
+      filters: null,
+      lastUpdatedAt: null,
+      loading: false,
+      locale: "pt-BR",
+      onLocaleChange() {},
+      onRefresh() {},
+      title: "Dashboard ZAIP AIOS",
+      ...props,
+    }),
+  );
+}
+
 function cssRule(source, selector) {
   const match = [...source.matchAll(/([^{}]+)\{([^}]*)\}/g)].find((candidate) =>
     candidate[1]?.split(",").some((item) => item.trim() === selector),

package/templates/.agents/dashboard/packages/ui/src/DashboardHeader.tsx

@@ -7,7 +7,7 @@ const zaipLogoUrl = new URL("../../../../config/src/logo_novo_azul.png", import.
 export function DashboardHeader({
   filters,
   filtersActive = false,
-  lastUpdatedAt,
+  snapshotUpdatedAt = null,
   loading,
   locale,
   onLocaleChange,
@@ -19,6 +19,7 @@ export function DashboardHeader({
   filters: ReactNode;
   filtersActive?: boolean;
   lastUpdatedAt: string | null;
+  snapshotUpdatedAt?: string | null;
   loading: boolean;
   locale: DashboardHeaderLocale;
   onLocaleChange: (locale: DashboardHeaderLocale) => void;
@@ -38,8 +39,8 @@ export function DashboardHeader({
           refresh: "Atualizar",
           refreshing: "Atualizando…",
           settings: "Configurações",
-          updated: "Última telemetria",
-          waiting: "Sem telemetria medida",
+          updated: "Última Atualização",
+          waiting: "Atualização indisponível",
         }
       : {
           filters: "Filters",
@@ -47,13 +48,13 @@ export function DashboardHeader({
           refresh: "Refresh",
           refreshing: "Refreshing…",
           settings: "Settings",
-          updated: "Last telemetry",
-          waiting: "No measured telemetry",
+          updated: "Last Updated",
+          waiting: "Update unavailable",
         };
   const updatedLabel =
-    lastUpdatedAt === null
+    snapshotUpdatedAt === null
       ? copy.waiting
-      : `${copy.updated} ${new Intl.DateTimeFormat(locale, { dateStyle: "short", timeStyle: "medium" }).format(new Date(lastUpdatedAt))}`;
+      : `${copy.updated} ${new Intl.DateTimeFormat(locale, { dateStyle: "short", timeStyle: "medium" }).format(new Date(snapshotUpdatedAt))}`;
   const changeLocale = (next: DashboardHeaderLocale) => {
     onLocaleChange(next);
     setLocaleOpen(false);