@zaip-ai/cli 3.0.0 → 3.2.0

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

@@ -0,0 +1,17 @@
+// Intl's immutable formatter is reusable; timestamps and results are never cached.
+const dateFormatter = new Intl.DateTimeFormat("en", {
+  timeZone: "America/Sao_Paulo",
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+});
+
+export function saoPauloDay(timestamp: string): string {
+  const values = Object.fromEntries(
+    dateFormatter
+      .formatToParts(new Date(timestamp))
+      .filter((part) => part.type !== "literal")
+      .map((part) => [part.type, part.value]),
+  ) as { year: string; month: string; day: string };
+  return `${values.year}-${values.month}-${values.day}`;
+}

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-cold-parse.test.ts

@@ -0,0 +1,78 @@
+import { expect, it, vi } from "vitest";
+import { saoPauloDay } from "./sqlite-calendar.js";
+import { readCanonicalLifecycleRecords } from "./sqlite-read-model-canonical.js";
+import { isCanonicalLifecyclePath } from "./sqlite-read-model-canonical-parsing.js";
+
+it("reuses only the immutable formatter and preserves calendar, DST and invalid input behavior", () => {
+  const cases = [
+    ["2024-03-01T02:59:59Z", "2024-02-29"],
+    ["2026-01-01T02:59:59Z", "2025-12-31"],
+    ["2026-01-01T03:00:00Z", "2026-01-01"],
+    ["2018-11-04T02:59:59Z", "2018-11-03"],
+    ["2018-11-04T03:00:00Z", "2018-11-04"],
+    ["2019-02-17T02:00:00Z", "2019-02-16"],
+  ] as const;
+  const formatterConstructor = vi.spyOn(Intl, "DateTimeFormat");
+  try {
+    for (let index = 0; index < 100; index++)
+      for (const [timestamp, expected] of cases) expect(saoPauloDay(timestamp)).toBe(expected);
+    expect(() => saoPauloDay("invalid")).toThrow(RangeError);
+    expect(formatterConstructor).not.toHaveBeenCalled();
+  } finally {
+    formatterConstructor.mockRestore();
+  }
+});
+
+it("ignores irrelevant source content before YAML parsing and keeps both lifecycle layouts", () => {
+  const ignored = [
+    ".agents/records/tasks/2026/09/task.md",
+    ".agents/records/changes/2026/09/C/artifacts/tests/test.md",
+    ".agents/records/runs/run.jsonl",
+    ".agents/records/executions/E/other.md",
+    ".agents/records/changes/C/decisions/other.txt",
+    "elsewhere/executions/E/execution.md",
+  ].map((path) => ({
+    path,
+    get content(): string {
+      throw new Error("Irrelevant content must never be inspected");
+    },
+  }));
+  expect(readCanonicalLifecycleRecords(ignored)).toEqual({
+    executions: [],
+    changes: [],
+    decisions: [],
+  });
+  for (const layout of ["data", "records"]) {
+    const rows = [
+      {
+        path: `.agents/${layout}/executions/2026/09/E/execution.md`,
+        content:
+          "---\nid: E\ncreated_at: 2026-09-15T00:00:00Z\nstatus: blocked\norigin:\n  type: interaction\n  conversation_id: C\n---\n",
+      },
+      {
+        path: `.agents/${layout}/changes/2026/09/H/change.md`,
+        content:
+          "---\nid: H\ncreated_at: 2026-09-15T00:00:00Z\nsource:\n  type: task\n  task_id: T\n---\n",
+      },
+      ...["changes", "executions"].map((kind) => ({
+        path: `.agents/${layout}/${kind}/E/artifacts/decisions/D.md`,
+        content: `---\nid: D-${kind}\ncreated_at: 2026-09-15T00:00:00Z\norigin: human\nscope_type: execution\nscope_id: E\n---\n`,
+      })),
+    ];
+    expect(rows.every((row) => isCanonicalLifecyclePath(row.path))).toBe(true);
+    const result = readCanonicalLifecycleRecords([...ignored, ...rows]);
+    expect(result.executions).toHaveLength(1);
+    expect(result.executions[0]).toMatchObject({ id: "E", originId: "C", status: "blocked" });
+    expect(result.changes).toHaveLength(1);
+    expect(result.changes[0]).toMatchObject({ id: "H", sourceId: "T" });
+    expect(result.decisions).toHaveLength(2);
+    expect(
+      readCanonicalLifecycleRecords([
+        {
+          path: `.agents/${layout}/executions/E/execution.md`,
+          content: "---\nid: [invalid\n---\n",
+        },
+      ]).executions,
+    ).toEqual([]);
+  }
+});

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-cost-group-projection.test.ts

@@ -0,0 +1,94 @@
+import { DatabaseSync } from "node:sqlite";
+import { expect, it } from "vitest";
+import { materializeCostGroupDailyProjection } from "./sqlite-cost-group-projection.js";
+import { baseViewSql } from "./sqlite-schema-base-views.js";
+
+it("evaluates the invocation population once across all eight daily groups with legacy parity", () => {
+  const database = new DatabaseSync(":memory:");
+  let costReads = 0;
+  database.function("observed_cost", (id) => {
+    costReads++;
+    return id === 1 ? 0 : null;
+  });
+  try {
+    database.exec(`CREATE TABLE inputs(id INTEGER); INSERT INTO inputs VALUES (1),(2);
+      CREATE VIEW invocations AS SELECT '2026-09-15' AS occurred_day_sp,
+      'e' AS execution_id, 'a' AS zaip_agent, 'p' AS provider, 'm' AS model,
+      't' AS task_id, 's' AS spec_id, 'r' AS prd_id, 'c' AS conversation_id,
+      1 AS llm_call_count, NULL AS duration_ms, 2 AS input_tokens,
+      NULL AS cached_input_tokens, 3 AS output_tokens, NULL AS reasoning_tokens,
+      5 AS total_tokens, observed_cost(id) AS cost_usd, NULL AS cost_brl FROM inputs;`);
+    const definition = /CREATE VIEW cost_monitor_group_daily_cache AS ([^;]+);/.exec(
+      baseViewSql,
+    )?.[1];
+    if (!definition) throw new Error("Canonical daily group SQL absent");
+    database.exec(`CREATE VIEW measured AS ${definition};`);
+    const actual = database.prepare("SELECT * FROM measured ORDER BY group_kind").all();
+    expect(actual).toHaveLength(8);
+    expect(costReads).toBe(2);
+    const reference = definition
+      .replace(/WITH group_invocations AS MATERIALIZED \([^)]*\) /, "")
+      .replaceAll("FROM group_invocations", "FROM invocations");
+    costReads = 0;
+    const expected = database.prepare(`SELECT * FROM (${reference}) ORDER BY group_kind`).all();
+    expect(costReads).toBe(16);
+    expect(actual).toEqual(expected);
+    for (const row of actual) {
+      expect(row.invocation_count).toBe(2);
+      expect(row.total_cost_usd).toBe(0);
+      expect(row.total_cost_brl).toBeNull();
+      expect(row.total_duration).toBeNull();
+    }
+  } finally {
+    database.close();
+  }
+});
+
+it("materializes exact labels without evaluating unrelated entity metrics", () => {
+  const database = new DatabaseSync(":memory:");
+  let irrelevantReads = 0;
+  database.function("unrelated_metric", () => {
+    irrelevantReads++;
+    throw new Error("Label projection must not evaluate unrelated metrics");
+  });
+  try {
+    database.exec(
+      `CREATE TABLE zaip_vw_cost_monitor_group_daily_cache(group_kind TEXT, day TEXT, group_value TEXT, cost REAL);`,
+    );
+    const insert = database.prepare(
+      "INSERT INTO zaip_vw_cost_monitor_group_daily_cache VALUES (?, '2026-09-15', ?, 2)",
+    );
+    for (const kind of ["task", "spec", "prd", "execution", "conversation"]) {
+      insert.run(kind, kind);
+      insert.run(kind, "missing");
+      insert.run(kind, null);
+      database.exec(
+        `CREATE VIEW zaip_vw_${kind}s AS SELECT '${kind}' AS id, 'Title' AS title, 'blocked' AS status, 'standard' AS risk, unrelated_metric() AS expensive_unused;`,
+      );
+    }
+    materializeCostGroupDailyProjection(database);
+    const rows = database
+      .prepare("SELECT * FROM cost_group_entity_projection ORDER BY group_kind, group_value")
+      .all();
+    expect(rows).toHaveLength(10);
+    for (const row of rows) {
+      expect(row.status).toBe(row.group_value === "missing" ? null : "blocked");
+      const titled =
+        row.group_value !== "missing" && ["task", "spec", "prd"].includes(String(row.group_kind));
+      expect(row.title).toBe(titled ? "Title" : null);
+      expect(row.risk).toBe(titled ? "standard" : null);
+    }
+    expect(irrelevantReads).toBe(0);
+    materializeCostGroupDailyProjection(database);
+    expect(
+      database
+        .prepare("SELECT * FROM cost_group_entity_projection ORDER BY group_kind, group_value")
+        .all(),
+    ).toEqual(rows);
+    expect(database.prepare("SELECT COUNT(*) AS n FROM cost_group_daily_projection").get()?.n).toBe(
+      15,
+    );
+  } finally {
+    database.close();
+  }
+});

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-cost-group-projection.ts

@@ -15,11 +15,11 @@ export function materializeCostGroupDailyProjection(database: DatabaseSync): voi
     CREATE TABLE IF NOT EXISTS cost_group_entity_projection(group_kind TEXT, group_value TEXT, title TEXT, status TEXT, risk TEXT);
     DELETE FROM cost_group_entity_projection;
     INSERT INTO cost_group_entity_projection
-      WITH tasks AS MATERIALIZED (SELECT * FROM zaip_vw_tasks),
-        specs AS MATERIALIZED (SELECT * FROM zaip_vw_specs),
-        prds AS MATERIALIZED (SELECT * FROM zaip_vw_prds),
-        executions AS MATERIALIZED (SELECT * FROM zaip_vw_executions),
-        conversations AS MATERIALIZED (SELECT * FROM zaip_vw_conversations)
+      WITH tasks AS MATERIALIZED (SELECT id, title, status, risk FROM zaip_vw_tasks),
+        specs AS MATERIALIZED (SELECT id, title, status, risk FROM zaip_vw_specs),
+        prds AS MATERIALIZED (SELECT id, title, status, risk FROM zaip_vw_prds),
+        executions AS MATERIALIZED (SELECT id, status FROM zaip_vw_executions),
+        conversations AS MATERIALIZED (SELECT id, status FROM zaip_vw_conversations)
       SELECT 'task' AS group_kind, groups.group_value, entity.title, entity.status, entity.risk
         FROM (SELECT DISTINCT group_value FROM cost_group_daily_projection
               WHERE group_kind = 'task' AND group_value IS NOT NULL) groups

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-duration-lookup.test.ts

@@ -0,0 +1,59 @@
+import { DatabaseSync } from "node:sqlite";
+import { expect, it } from "vitest";
+import { baseViewSql } from "./sqlite-schema-base-views.js";
+
+it("uses indexed duration lookup with exact legacy sums and nulls and no duplicate Run rows", () => {
+  const db = new DatabaseSync(":memory:");
+  try {
+    db.exec(
+      "CREATE TABLE zaip_aios_activities(activity_row_id TEXT, payload_type TEXT, payload_json TEXT);",
+    );
+    const insert = db.prepare("INSERT INTO zaip_aios_activities VALUES(?,?,?)");
+    for (const id of ["known", "zero", "unknown", "missing"]) insert.run(id, null, null);
+    for (const [id, values] of [
+      ["known", [3, 5, null]],
+      ["zero", [0]],
+      ["unknown", [null]],
+      ["unrelated", [900]],
+    ] as const)
+      for (const duration of values)
+        insert.run(
+          `fact-${id}`,
+          "duration_allocation",
+          JSON.stringify({ activity_row_id: id, attributed_token_active_ms: duration }),
+        );
+    insert.run(
+      "technical",
+      "other",
+      JSON.stringify({ activity_row_id: "known", attributed_token_active_ms: 999 }),
+    );
+    const index = /CREATE INDEX zaip_activities_duration_activity[^;]+;/.exec(baseViewSql)?.[0];
+    const view = /CREATE VIEW activities AS\s+([^;]+);/.exec(baseViewSql)?.[1];
+    if (!index || !view) throw new Error("Canonical indexed duration SQL missing");
+    db.exec(`${index} CREATE VIEW activities AS ${view};`);
+    const query =
+      "SELECT activity_row_id,attributed_token_active_ms FROM activities ORDER BY activity_row_id";
+    const actual = db.prepare(query).all();
+    const expected = db
+      .prepare(`SELECT a.activity_row_id,f.duration AS attributed_token_active_ms
+      FROM zaip_aios_activities a LEFT JOIN (
+        SELECT json_extract(payload_json,'$.activity_row_id') AS activity_row_id,
+        SUM(json_extract(payload_json,'$.attributed_token_active_ms')) AS duration
+        FROM zaip_aios_activities WHERE payload_type='duration_allocation' GROUP BY activity_row_id
+      ) f USING(activity_row_id) WHERE a.payload_type IS NULL ORDER BY a.activity_row_id`)
+      .all();
+    expect(actual).toEqual(expected);
+    expect(actual).toHaveLength(4);
+    expect(actual.map((row) => row.attributed_token_active_ms)).toEqual([8, null, null, 0]);
+    const plan = db.prepare(`EXPLAIN QUERY PLAN ${query}`).all();
+    expect(
+      plan.some((row) =>
+        String(row.detail).includes("zaip_activities_duration_activity (<expr>=?)"),
+      ),
+    ).toBe(true);
+    const labelPlan = db.prepare("EXPLAIN QUERY PLAN SELECT activity_row_id FROM activities").all();
+    expect(labelPlan.some((row) => String(row.detail).includes("CORRELATED"))).toBe(false);
+  } finally {
+    db.close();
+  }
+});

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-entity-label-views.test.ts

@@ -0,0 +1,72 @@
+import { DatabaseSync } from "node:sqlite";
+import { expect, it } from "vitest";
+import { baseViewSql } from "./sqlite-schema-base-views.js";
+
+it("preserves canonical precedence and legacy labels without repeated payload or metric expansion", () => {
+  const db = new DatabaseSync(":memory:");
+  let payloadReads = 0;
+  let metricReads = 0;
+  db.function("payload_origin", (value) => {
+    payloadReads++;
+    return value;
+  });
+  db.function("unused_metric", () => {
+    metricReads++;
+    return 42;
+  });
+  try {
+    db.exec(`
+      CREATE TABLE inputs(id TEXT, status TEXT, created_at TEXT, occurred_day_sp TEXT, origin_type TEXT, origin_id TEXT);
+      INSERT INTO inputs VALUES
+        ('e1','blocked','2026-09-01','2026-09-01','interaction','c1'),
+        ('e2','completed','2026-09-02','2026-09-02','interaction','c1'),
+        ('e3',NULL,'2026-09-03','2026-09-03','task','not-conversation'),
+        ('e4','failed','2026-09-04','2026-09-04','interaction',NULL);
+      CREATE VIEW canonical_executions AS SELECT id,status,created_at,occurred_day_sp,origin_type,
+        payload_origin(origin_id) AS origin_id FROM inputs;
+      CREATE TABLE zaip_aios_activities(payload_type TEXT, execution_id TEXT, conversation_id TEXT,
+        status TEXT, occurred_at TEXT, occurred_day_sp TEXT);
+      INSERT INTO zaip_aios_activities VALUES
+        (NULL,'e1','c1','failed','2026-08-01','2026-08-01'),
+        (NULL,'legacy','legacy-c','blocked','2026-09-05','2026-09-05'),
+        (NULL,'legacy','legacy-c','completed','2026-09-06','2026-09-06'),
+        (NULL,'unknown','unknown-c',NULL,NULL,NULL),
+        ('technical','fake','fake-c','completed','2026-01-01','2026-01-01'),
+        (NULL,NULL,NULL,'completed','2026-01-01','2026-01-01');
+      CREATE VIEW activities AS SELECT a.*, f.metric FROM zaip_aios_activities a
+        LEFT JOIN (SELECT execution_id, SUM(unused_metric()) AS metric FROM zaip_aios_activities GROUP BY execution_id) f
+        USING(execution_id) WHERE a.payload_type IS NULL;
+    `);
+    const reference = {
+      executions: `SELECT id,status,created_at AS occurred_at,occurred_day_sp FROM canonical_executions
+        UNION ALL SELECT execution_id,MAX(status),MIN(occurred_at),MIN(occurred_day_sp)
+        FROM activities WHERE execution_id IS NOT NULL AND NOT EXISTS
+        (SELECT 1 FROM canonical_executions c WHERE c.id=activities.execution_id) GROUP BY execution_id`,
+      conversations: `SELECT origin_id AS id,MAX(status) AS status,MIN(created_at) AS occurred_at,MIN(occurred_day_sp) AS occurred_day_sp
+        FROM canonical_executions WHERE origin_type='interaction' AND origin_id IS NOT NULL GROUP BY origin_id
+        UNION ALL SELECT conversation_id,MAX(status),MIN(occurred_at),MIN(occurred_day_sp)
+        FROM activities WHERE conversation_id IS NOT NULL AND NOT EXISTS
+        (SELECT 1 FROM canonical_executions c WHERE c.origin_type='interaction' AND c.origin_id=activities.conversation_id) GROUP BY conversation_id`,
+    };
+    for (const name of ["executions", "conversations"] as const) {
+      const expected = db.prepare(`SELECT * FROM (${reference[name]}) ORDER BY id`).all();
+      const repeatedReads = payloadReads;
+      payloadReads = 0;
+      metricReads = 0;
+      const definition = new RegExp(`CREATE VIEW ${name} AS\\s+([^;]+);`).exec(baseViewSql)?.[1];
+      if (!definition) throw new Error(`Missing canonical view ${name}`);
+      const actual = db.prepare(`SELECT * FROM (${definition}) ORDER BY id`).all();
+      expect(actual).toEqual(expected);
+      expect(actual.some((row) => String(row.id).startsWith("fake"))).toBe(false);
+      expect(metricReads).toBe(0);
+      if (name === "conversations") {
+        expect(payloadReads).toBe(4);
+        expect(repeatedReads).toBeGreaterThan(payloadReads);
+        expect(actual.find((row) => row.id === "c1")?.status).toBe("completed");
+        expect(actual.find((row) => row.id === "unknown-c")?.status).toBeNull();
+      }
+    }
+  } finally {
+    db.close();
+  }
+});

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-materialize-runs.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import type { DatabaseSync } from "node:sqlite";
-import { pricingCatalogSchema, resolveHistoricalDeveloperAttribution } from "@zaip-ai/costs";
+import { prepareHistoricalDeveloperAttribution, pricingCatalogSchema } from "@zaip-ai/costs";
 import {
   foldRunV2Records,
   parseRunV2JsonLines,
@@ -97,7 +97,7 @@ export function materializeCanonicalRuns(input: RunMaterializationInput) {
       .all() as Array<{ content: string }>
   ).flatMap((row) => {
     try {
-      return [JSON.parse(row.content)];
+      return [prepareHistoricalDeveloperAttribution(JSON.parse(row.content))];
     } catch {
       return [];
     }
@@ -117,8 +117,7 @@ export function materializeCanonicalRuns(input: RunMaterializationInput) {
       };
     for (const candidate of historicalDeveloperManifests) {
       try {
-        const resolved = resolveHistoricalDeveloperAttribution({
-          manifest: candidate,
+        const resolved = candidate({
           run_id: String(JSON.parse(row.content.split(/\r?\n/u)[0] ?? "{}").run_id ?? ""),
           path: row.path,
           content: row.content,

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-query-entity-group.test.ts

@@ -0,0 +1,171 @@
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { SqliteViewInput } from "./sqlite-query-context.js";
+import { readEntityGroup } from "./sqlite-query-entity-group.js";
+
+const databases: DatabaseSync[] = [];
+afterEach(() => {
+  vi.restoreAllMocks();
+  for (const database of databases.splice(0)) database.close();
+});
+
+function fixture(kind: "spec" | "prd") {
+  const database = new DatabaseSync(":memory:");
+  databases.push(database);
+  database.exec(`
+    CREATE TABLE ${kind}s (id TEXT PRIMARY KEY, title TEXT, status TEXT, risk TEXT,
+      occurred_at TEXT, occurred_day_sp TEXT);
+    CREATE TABLE invocations (agent_invocation_id TEXT PRIMARY KEY, ${kind}_id TEXT,
+      occurred_at TEXT, occurred_day_sp TEXT, llm_call_count INTEGER, duration_ms REAL,
+      input_tokens REAL, cached_input_tokens REAL, output_tokens REAL, reasoning_tokens REAL,
+      total_tokens REAL, cost_usd REAL, cost_brl REAL);
+  `);
+  const entity = (id: string, day = "2026-09-10", status = "completed", risk = "standard") =>
+    database
+      .prepare(`INSERT INTO ${kind}s VALUES (?, ?, ?, ?, ?, ?)`)
+      .run(id, `Title ${id}`, status, risk, `${day}T12:00:00Z`, day);
+  const invocation = (id: string, parent: string, day: string, cost: number | null) =>
+    database
+      .prepare("INSERT INTO invocations VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+      .run(
+        id,
+        parent,
+        `${day}T13:00:00Z`,
+        day,
+        cost === null ? null : 1,
+        cost,
+        cost,
+        cost,
+        cost,
+        cost,
+        cost,
+        cost,
+        cost,
+      );
+  const read = (input: SqliteViewInput = {}) =>
+    readEntityGroup(
+      { database },
+      kind === "spec" ? "cost_monitor_specs" : "cost_monitor_prds",
+      input,
+      kind,
+    );
+  return { database, entity, invocation, read };
+}
+
+describe.each(["spec", "prd"] as const)("canonical %s single grouped query", (kind) => {
+  it("computes full totals and deterministic pages with one SQL statement", () => {
+    const { database, entity, invocation, read } = fixture(kind);
+    for (let i = 0; i < 12; i++) {
+      const id = `E${String(i).padStart(2, "0")}`;
+      entity(id);
+      invocation(`I${i}`, id, "2026-09-10", 0.12345678901234566);
+    }
+    const prepare = vi.spyOn(database, "prepare");
+    const first = read({ limit: 10 });
+    expect(prepare).toHaveBeenCalledTimes(1);
+    prepare.mockClear();
+    const second = read({ limit: 10, offset: 10 });
+    expect(prepare).toHaveBeenCalledTimes(1);
+    expect(first.total_count).toBe(12);
+    expect(first.has_more).toBe(true);
+    expect(second.has_more).toBe(false);
+    expect(second.rows.map((row) => row.id)).toEqual(["E10", "E11"]);
+    expect(first.totals).toEqual(second.totals);
+    expect(first.totals).toMatchObject({
+      entity_count: 12,
+      invocation_count: 12,
+      total_duration: 1,
+    });
+    expect(first.rows[0]).toMatchObject({
+      id: "E00",
+      key: "E00",
+      total_cost_brl: 0.12345678901234566,
+    });
+    expect(Object.keys(first.rows[0] ?? {}).some((key) => key.startsWith("__"))).toBe(false);
+    const beyond = read({ limit: 10, offset: 99 });
+    expect(beyond).toMatchObject({
+      total_count: 12,
+      rows: [],
+      totals: first.totals,
+      has_more: false,
+    });
+  });
+
+  it("retains canonical entity dates, no-run unknowns and observed zero with filters", () => {
+    const { entity, invocation, read } = fixture(kind);
+    entity("CURRENT");
+    invocation("old-run", "CURRENT", "2026-08-01", 100);
+    entity("ZERO");
+    invocation("zero", "ZERO", "2026-09-10", 0);
+    entity("UNKNOWN");
+    invocation("unknown", "UNKNOWN", "2026-09-10", null);
+    entity("NO-RUN");
+    entity("OLD", "2026-08-01");
+    invocation("new-run", "OLD", "2026-09-10", 999);
+    entity("BLOCKED", "2026-09-10", "blocked", "critical");
+    const page = read({
+      from: "2026-09-01",
+      to: "2026-09-30",
+      status: "completed",
+      risk: "standard",
+    });
+    expect(page.total_count).toBe(4);
+    expect(page.totals).toEqual({
+      entity_count: 4,
+      invocation_count: 2,
+      total_duration: 0,
+      total_tokens: 0,
+      total_cost_usd: 0,
+      total_cost_brl: 0,
+    });
+    expect(page.rows.find((row) => row.id === "CURRENT")).toMatchObject({
+      invocation_count: 0,
+      total_cost_brl: null,
+      first_day: "2026-09-10",
+      occurred_at: "2026-09-10T12:00:00Z",
+    });
+    expect(page.rows.find((row) => row.id === "ZERO")).toMatchObject({
+      total_cost_brl: 0,
+      invocation_count: 1,
+    });
+    expect(page.rows.find((row) => row.id === "UNKNOWN")).toMatchObject({
+      total_cost_brl: null,
+      invocation_count: 1,
+    });
+    expect(page.rows.find((row) => row.id === "NO-RUN")).toMatchObject({
+      total_cost_brl: null,
+      invocation_count: 0,
+    });
+    expect(read({ query: "Title BLOCKED", risk: "critical" }).rows.map((row) => row.id)).toEqual([
+      "BLOCKED",
+    ]);
+    expect(read({ query: "CURRENT" }).totals.total_cost_brl).toBe(100);
+  });
+
+  it("returns nullable empty totals and clamps page boundaries without losing counts", () => {
+    const { entity, read } = fixture(kind);
+    expect(read({ limit: 0, offset: -2 })).toMatchObject({
+      rows: [],
+      total_count: 0,
+      limit: 1,
+      offset: 0,
+      has_more: false,
+      totals: {
+        entity_count: 0,
+        invocation_count: 0,
+        total_duration: null,
+        total_tokens: null,
+        total_cost_usd: null,
+        total_cost_brl: null,
+      },
+    });
+    entity("ONLY");
+    expect(read({ limit: 1000, offset: 1 })).toMatchObject({
+      rows: [],
+      total_count: 1,
+      limit: 200,
+      has_more: false,
+      totals: { entity_count: 1, invocation_count: 0, total_cost_brl: null },
+    });
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-query-entity-group.ts

@@ -2,7 +2,7 @@ import { type CostGroupKind, readCostGroupPage } from "./sqlite-cost-group-page.
 import type { SqliteQueryContext, SqliteViewInput } from "./sqlite-query-context.js";
 import type { SqliteViewName } from "./sqlite-read-model-types.js";
 export function readEntityGroup(
-  context: SqliteQueryContext,
+  context: Pick<SqliteQueryContext, "database">,
   view: SqliteViewName,
   input: SqliteViewInput,
   groupKind: string,
@@ -55,7 +55,7 @@ export function readEntityGroup(
     const entityWhere = entityClauses.length === 0 ? "1" : entityClauses.join(" AND ");
     const invocationJoin =
       invocationClauses.length === 0 ? "" : ` AND ${invocationClauses.join(" AND ")}`;
-    const ctes = `WITH grouped AS (
+    const ctes = `WITH grouped AS MATERIALIZED (
           SELECT entity.id AS group_value, entity.title, entity.status, entity.risk,
             COALESCE(MIN(i.occurred_day_sp), entity.occurred_day_sp) AS first_day,
             COALESCE(MAX(i.occurred_day_sp), entity.occurred_day_sp) AS last_day,
@@ -76,23 +76,43 @@ export function readEntityGroup(
     const limit = Math.min(200, Math.max(1, input.limit ?? 50));
     const offset = Math.max(0, input.offset ?? 0);
     const values = [...invocationValues, ...entityValues];
-    const total_count = Number(
-      (
-        context.database
-          .prepare(`${ctes} SELECT COUNT(*) AS count FROM grouped`)
-          .get(...values) as { count: number }
-      ).count,
-    );
-    const totals = context.database
+    // Materialize this population once for count, totals and the requested page.
+    // A totals-first LEFT JOIN retains totals even for an empty/out-of-range page.
+    const result = context.database
       .prepare(
-        `${ctes} SELECT COUNT(*) AS entity_count, COALESCE(SUM(invocation_count), 0) AS invocation_count, ROUND(SUM(total_duration)) AS total_duration, SUM(total_tokens) AS total_tokens, SUM(total_cost_usd) AS total_cost_usd, SUM(total_cost_brl) AS total_cost_brl FROM grouped`,
-      )
-      .get(...values) as Record<string, unknown>;
-    const rows = context.database
-      .prepare(
-        `${ctes} SELECT group_value AS id, group_value AS key, title, status, risk, first_day, last_day, occurred_at, invocation_count, llm_call_count, total_duration, total_input_tokens, total_cached_input_tokens, total_output_tokens, total_reasoning_tokens, total_tokens, total_cost_usd, total_cost_brl FROM grouped ORDER BY total_cost_brl DESC, group_value LIMIT ? OFFSET ?`,
+        `${ctes}, totals AS (
+          SELECT COUNT(*) AS __entity_count,
+            COALESCE(SUM(invocation_count), 0) AS __invocation_count,
+            ROUND(SUM(total_duration)) AS __total_duration,
+            SUM(total_tokens) AS __total_tokens,
+            SUM(total_cost_usd) AS __total_cost_usd,
+            SUM(total_cost_brl) AS __total_cost_brl FROM grouped
+        ), paged AS (
+          SELECT 1 AS __row_present, group_value AS id, group_value AS key,
+            title, status, risk, first_day, last_day, occurred_at, invocation_count,
+            llm_call_count, total_duration, total_input_tokens, total_cached_input_tokens,
+            total_output_tokens, total_reasoning_tokens, total_tokens, total_cost_usd,
+            total_cost_brl FROM grouped ORDER BY total_cost_brl DESC, group_value LIMIT ? OFFSET ?
+        ) SELECT totals.*, paged.* FROM totals LEFT JOIN paged ON 1
+          ORDER BY paged.total_cost_brl DESC, paged.id`,
       )
       .all(...values, limit, offset) as Array<Record<string, unknown>>;
+    const aggregate = result[0];
+    if (!aggregate) throw new Error("Canonical macro query did not return its aggregate row.");
+    const total_count = Number(aggregate.__entity_count);
+    const totals = {
+      entity_count: aggregate.__entity_count,
+      invocation_count: aggregate.__invocation_count,
+      total_duration: aggregate.__total_duration,
+      total_tokens: aggregate.__total_tokens,
+      total_cost_usd: aggregate.__total_cost_usd,
+      total_cost_brl: aggregate.__total_cost_brl,
+    };
+    const rows = result
+      .filter((row) => row.__row_present === 1)
+      .map((row) =>
+        Object.fromEntries(Object.entries(row).filter(([key]) => !key.startsWith("__"))),
+      );
     return {
       data_source: "sqlite_read_model" as const,
       view,

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-read-model-canonical-parsing.ts

@@ -1,5 +1,12 @@
 import { parseYaml } from "@zaip-ai/core";
 
+/** Same accepted lifecycle paths as the parser, before any YAML or cache work. */
+export function isCanonicalLifecyclePath(path: string): boolean {
+  return /^\.agents\/(?:data|records)\/(?:executions\/.*\/execution\.md|changes\/.*\/change\.md|(?:changes|executions)\/.*\/decisions\/.*\.md)$/.test(
+    path,
+  );
+}
+
 export function frontMatterRecord(content: string): Record<string, unknown> | null {
   const source = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content)?.[1];
   if (source === undefined) return null;