@zaip-ai/cli 1.3.2 → 1.3.5

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

@@ -28,6 +28,7 @@ import {
   readDateOnlyCostDimensionPage,
 } from "./sqlite-cost-agent-page.js";
 import { buildCostDimensionAggregates } from "./sqlite-cost-aggregates.js";
+import { rebuildCostInvocationDimensionFactsSql } from "./sqlite-cost-dimension-facts.js";
 import { type CostGroupKind, readCostGroupPage } from "./sqlite-cost-group-page.js";
 import { materializeCostGroupDailyProjection } from "./sqlite-cost-group-projection.js";
 import { filterCostInvocationProjection } from "./sqlite-cost-invocation-page.js";
@@ -54,7 +55,6 @@ import {
 import {
   installLegacyViewAliases,
   materializeSnapshot,
-  mostRecentCompatibleSnapshot,
   pruneSnapshotCache,
   readSnapshotFileCount,
 } from "./sqlite-snapshot-cache.js";
@@ -64,15 +64,14 @@ export {
   sourceFingerprint,
 } from "./sqlite-read-model-source-fingerprint.js";
 
+import { reportSqliteReadModelLaunchProgress } from "./sqlite-read-model-launch-progress.js";
 import { sourceFingerprint } from "./sqlite-read-model-source-fingerprint.js";
+import { materializePreferredStaleSeed } from "./sqlite-read-model-stale-seed.js";
 
 const dbRelativePath = ".local/dashboard-sqlite/read-model.sqlite";
-// Schema 58 aligns Operations invocation/day facts with the same factual
-// source day used by tokens, Cost Monitor and attributed Tempo. Seed reuse is
-// safe only when both source and this schema version match.
-// Allocation rows are materialized after attributed-time reconciliation; a
-// prior seed contains the pre-reconciliation payload and is incompatible.
-const readModelSchemaVersion = "70";
+// Schema 71 requires the canonical work-item identity index. Older seeds must
+// rebuild rather than silently retaining the unindexed correlated lookups.
+const readModelSchemaVersion = "71";
 const requiredPersistedTables = [
   "zaip_aios_activities",
   "zaip_dim_llm_model",
@@ -97,6 +96,7 @@ const requiredIndexes = [
   "zaip_activities_period_invocation",
   "zaip_activities_status",
   "zaip_activities_payload",
+  "zaip_activities_work_item_identity",
   "cost_dimension_facts_day_model",
   "cost_dimension_facts_day_provider",
   "cost_dimension_facts_invocation",
@@ -993,6 +993,16 @@ export function validateSqliteReadModelSchema(path: string): {
   }
 }
 
+function hasReusableSnapshotPayloads(database: DatabaseSync): boolean {
+  const indexes = database
+    .prepare("SELECT name FROM sqlite_master WHERE type='index'")
+    .all() as Array<{
+    name: string;
+  }>;
+  const names = new Set(indexes.map((index) => index.name));
+  return requiredIndexes.every((name) => names.has(name)) && hasRequiredFirstFoldPayloads(database);
+}
+
 /** Recreates the disposable comparison read model from ZAIP records and configuration. */
 export async function rebuildSqliteReadModel(
   workspaceRoot: string,
@@ -1005,21 +1015,28 @@ export async function rebuildSqliteReadModel(
   materialize_ms: number;
 }> {
   const path = sqliteReadModelPath(workspaceRoot);
+  const reportLaunchProgress = reportSqliteReadModelLaunchProgress;
+  const cacheDirectory = process.env.ZAIP_SQLITE_CACHE_DIR ?? join(dirname(path), "cache");
+  const preferredSeed = await materializePreferredStaleSeed({
+    destination: path,
+    enabled: !options.forceCanonical && process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED === "1",
+    fingerprintMs: 0,
+    hasRequiredPayloads: hasReusableSnapshotPayloads,
+    reportProgress: true,
+    schemaVersion: readModelSchemaVersion,
+  });
+  if (preferredSeed !== null) return preferredSeed;
   const fingerprintStartedAt = performance.now();
+  reportLaunchProgress("source_fingerprint_started", 8, "Inventariando fontes canônicas.");
   const sourceSnapshot = await sourceFingerprint(workspaceRoot);
-  const reportLaunchProgress = (phase: string, percent: number, detail: string) => {
-    if (process.env.ZAIP_DASHBOARD_LAUNCH_PROGRESS !== "1") return;
-    process.stderr.write(
-      `${JSON.stringify({ event: "dashboard_sqlite_rebuild_progress", phase, percent, detail })}\n`,
-    );
-  };
+  reportLaunchProgress("source_fingerprint_ready", 20, "Inventário canônico concluído.");
   const { fingerprint } = sourceSnapshot;
   const fingerprintMs = Math.round(performance.now() - fingerprintStartedAt);
   const existingFiles = readSnapshotFileCount(
     path,
     fingerprint,
     readModelSchemaVersion,
-    hasRequiredFirstFoldPayloads,
+    hasReusableSnapshotPayloads,
   );
   if (existingFiles !== null) {
     validateSqliteReadModelSchema(path);
@@ -1037,7 +1054,7 @@ export async function rebuildSqliteReadModel(
   // source fingerprint, then atomically materialize that cache into the
   // generation path.  A normal fresh-port handoff can therefore be warm.
   const cachePath = join(
-    process.env.ZAIP_SQLITE_CACHE_DIR ?? join(dirname(path), "cache"),
+    cacheDirectory,
     // The cache payload is part of the immutable generation contract.  Keep
     // a separate namespace when that payload changes, so a schema-compatible
     // older seed cannot bypass the new all-time precomputation.
@@ -1049,7 +1066,7 @@ export async function rebuildSqliteReadModel(
     cachePath,
     fingerprint,
     readModelSchemaVersion,
-    hasRequiredFirstFoldPayloads,
+    hasReusableSnapshotPayloads,
   );
   if (cachedFiles !== null) {
     const materializeStartedAt = performance.now();
@@ -1068,24 +1085,14 @@ export async function rebuildSqliteReadModel(
   // reconstruction merely because a record changed since the last snapshot.
   // The launcher labels this state as updating and starts an isolated refresh;
   // this process still serves only a schema-validated immutable seed.
-  if (!options.forceCanonical && process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED === "1") {
-    const fallback = await mostRecentCompatibleSnapshot(
-      dirname(cachePath),
-      readModelSchemaVersion,
-      hasRequiredFirstFoldPayloads,
-    );
-    if (fallback !== null) {
-      const materializeStartedAt = performance.now();
-      await materializeSnapshot(fallback.path, path);
-      return {
-        files: fallback.files,
-        path,
-        cache: "stale_seed",
-        fingerprint_ms: fingerprintMs,
-        materialize_ms: Math.round(performance.now() - materializeStartedAt),
-      };
-    }
-  }
+  const fallback = await materializePreferredStaleSeed({
+    destination: path,
+    enabled: !options.forceCanonical && process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED === "1",
+    fingerprintMs,
+    hasRequiredPayloads: hasReusableSnapshotPayloads,
+    schemaVersion: readModelSchemaVersion,
+  });
+  if (fallback !== null) return fallback;
 
   reportLaunchProgress(
     "source_inventory",
@@ -2123,6 +2130,8 @@ export async function rebuildSqliteReadModel(
           }),
         );
       }
+      // Keep canonical TEMP references outside the public-view name rewriter.
+      database.exec(rebuildCostInvocationDimensionFactsSql);
       const viewSql = `
         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);
@@ -2140,6 +2149,7 @@ export async function rebuildSqliteReadModel(
           WHERE agent_invocation_id IS NOT NULL;
         CREATE INDEX zaip_activities_status ON zaip_aios_activities(activity_source_kind, status, phase);
         CREATE INDEX zaip_activities_payload ON zaip_aios_activities(payload_type, activity_key);
+        CREATE INDEX zaip_activities_work_item_identity ON zaip_aios_activities(json_extract(payload_json, '$.entity_kind'), json_extract(payload_json, '$.id')) WHERE payload_type='work_item';
         CREATE VIEW files AS SELECT json_extract(payload_json, '$.path') AS path, json_extract(payload_json, '$.content') AS content, json_extract(payload_json, '$.mtime_ms') AS mtime_ms, json_extract(payload_json, '$.size_bytes') AS size_bytes, json_extract(payload_json, '$.content_sha256') AS content_sha256, json_extract(payload_json, '$.artifact_kind') AS artifact_kind, json_extract(payload_json, '$.artifact_id') AS artifact_id, json_extract(payload_json, '$.artifact_occurred_at') AS artifact_occurred_at, json_extract(payload_json, '$.artifact_occurred_day_sp') AS artifact_occurred_day_sp, json_extract(payload_json, '$.artifact_task_id') AS artifact_task_id, json_extract(payload_json, '$.artifact_change_id') AS artifact_change_id, json_extract(payload_json, '$.artifact_run_id') AS artifact_run_id FROM zaip_aios_activities WHERE payload_type='file';
         CREATE VIEW read_model_source_state AS SELECT json_extract(payload_json, '$.source_path') AS source_path, json_extract(payload_json, '$.source_hash') AS source_hash, json_extract(payload_json, '$.mtime_ms') AS mtime_ms, json_extract(payload_json, '$.size_bytes') AS size_bytes, json_extract(payload_json, '$.source_kind') AS source_kind, json_extract(payload_json, '$.last_processed_at') AS last_processed_at FROM zaip_aios_activities WHERE payload_type='source_state';
         CREATE VIEW read_model_metadata AS SELECT json_extract(payload_json, '$.key') AS key, json_extract(payload_json, '$.value') AS value FROM zaip_aios_activities WHERE payload_type='metadata';
@@ -2182,44 +2192,6 @@ export async function rebuildSqliteReadModel(
         CREATE VIEW sub_runs AS SELECT * FROM activities WHERE run_role = 'subrun';
         CREATE VIEW invocations AS SELECT activity_row_id, activity_key, version_activity_id, source_occurred_at, root_agent_run_id AS root_agent_invocation_id, parent_agent_run_id AS parent_agent_invocation_id, execution_id, task_id, spec_id, prd_id, change_id, conversation_id, run_id, occurred_at, occurred_day_sp, invocation_kind, delegation_depth, zaip_agent, zaip_agent_persona, zaip_agent_job, zaip_agent_role, client, provider, model, phase, purpose, status, source_started_at, source_finished_at, attributed_token_active_ms, attributed_token_active_ms AS duration_ms, CASE WHEN attributed_token_active_ms IS NOT NULL THEN 'observed' ELSE 'unavailable' END AS duration_provenance, CASE WHEN attributed_token_active_ms IS NOT NULL THEN 'attributed_token_active' ELSE NULL END AS duration_fact_provenance, input_tokens, cached_input_tokens, output_tokens, reasoning_tokens, total_tokens, token_source, cost_usd, cost_brl, cost_method, pricing_model, pricing_source, fx_rate, service_tier, reasoning_effort, source_event_count, usage_event_count, llm_call_count, agent_run_id AS agent_invocation_id FROM agent_runs;
         CREATE VIEW invocation_usage AS SELECT agent_invocation_id, agent_invocation_id AS usage_index, provider, model, service_tier, reasoning_effort, input_tokens, cached_input_tokens, uncached_input_tokens, output_tokens, reasoning_tokens, visible_output_tokens, total_tokens, input_rate_usd_per_million, cached_input_rate_usd_per_million, output_rate_usd_per_million, reasoning_rate_usd_per_million, context_input_multiplier, context_output_multiplier, speed_cost_multiplier, pricing_scenario, standard_cost_usd, speed_uplift_usd, input_cost_usd, cached_input_cost_usd, output_cost_usd, reasoning_cost_usd, calculated_cost_usd, recorded_cost_usd, cost_variance_usd, cost_usd, cost_brl, cost_method, pricing_model, pricing_source, fx_rate FROM invocation_usage_segments;
-        -- Flatten the small financial dimension fact once during rebuild.
-        -- Models/Providers must never execute JSON extraction for each paint.
-        CREATE TABLE cost_invocation_dimension_facts AS
-          SELECT i.agent_invocation_id, date(COALESCE(i.source_started_at, i.source_occurred_at, i.occurred_at), '-3 hours') AS occurred_day_sp,
-            CASE WHEN u.model IS NULL OR trim(u.model)='' OR u.model='unavailable' THEN 'unavailable' ELSE u.model END AS model,
-            CASE WHEN u.provider IS NULL OR trim(u.provider)='' OR u.provider='unavailable' THEN 'unavailable' ELSE u.provider END AS provider,
-            u.input_tokens, u.cached_input_tokens, u.output_tokens, u.reasoning_tokens,
-            u.total_tokens, u.cost_usd, u.cost_brl, i.attributed_token_active_ms AS duration_ms, 0 AS residual
-          FROM invocations i JOIN invocation_usage u USING(agent_invocation_id)
-          WHERE u.total_tokens IS NOT NULL OR u.cost_usd IS NOT NULL OR u.cost_brl IS NOT NULL;
-        CREATE INDEX cost_dimension_facts_day_model ON cost_invocation_dimension_facts(occurred_day_sp, model);
-        CREATE INDEX cost_dimension_facts_day_provider ON cost_invocation_dimension_facts(occurred_day_sp, provider);
-        CREATE INDEX cost_dimension_facts_invocation ON cost_invocation_dimension_facts(agent_invocation_id);
-        INSERT INTO cost_invocation_dimension_facts
-          SELECT i.agent_invocation_id, date(COALESCE(i.source_started_at, i.source_occurred_at, i.occurred_at), '-3 hours') AS occurred_day_sp, 'unavailable', 'unavailable',
-            i.input_tokens-COALESCE(s.input_tokens,0), i.cached_input_tokens-COALESCE(s.cached_input_tokens,0),
-            i.output_tokens-COALESCE(s.output_tokens,0), i.reasoning_tokens-COALESCE(s.reasoning_tokens,0),
-            i.total_tokens-COALESCE(s.total_tokens,0), i.cost_usd-COALESCE(s.cost_usd,0),
-            i.cost_brl-COALESCE(s.cost_brl,0), i.attributed_token_active_ms, 1
-          FROM invocations i LEFT JOIN (
-            SELECT agent_invocation_id, SUM(input_tokens) input_tokens, SUM(cached_input_tokens) cached_input_tokens,
-              SUM(output_tokens) output_tokens, SUM(reasoning_tokens) reasoning_tokens, SUM(total_tokens) total_tokens,
-              SUM(cost_usd) cost_usd, SUM(cost_brl) cost_brl
-            FROM cost_invocation_dimension_facts GROUP BY agent_invocation_id
-          ) s USING(agent_invocation_id)
-          WHERE i.total_tokens<>COALESCE(s.total_tokens,0) OR i.cost_usd<>COALESCE(s.cost_usd,0) OR i.cost_brl<>COALESCE(s.cost_brl,0);
-        -- Financial activities outside Agent Invocation telemetry are still
-        -- factual Cost Monitor facts. Give them a stable synthetic key and
-        -- retain them as the explicit no-dimension population.
-        INSERT INTO cost_invocation_dimension_facts
-          SELECT 'activity:' || a.activity_row_id, a.occurred_day_sp, 'unavailable', 'unavailable',
-            a.input_tokens, a.cached_input_tokens, a.output_tokens, a.reasoning_tokens,
-            a.total_tokens, a.cost_usd, a.cost_brl, f.attributed_token_active_ms, 1
-          FROM zaip_aios_activities a
-          LEFT JOIN attributed_token_active_facts f USING(activity_row_id)
-          WHERE a.payload_type IS NULL AND a.activity_source_kind <> 'agent_run'
-            AND (a.total_tokens IS NOT NULL OR a.cost_usd IS NOT NULL OR a.cost_brl IS NOT NULL)
-            AND NOT EXISTS (SELECT 1 FROM cost_invocation_dimension_facts d WHERE d.agent_invocation_id='activity:' || a.activity_row_id);
         CREATE VIEW work_items AS SELECT entity_kind, id, title, status, risk, occurred_at, occurred_day_sp FROM canonical_work_items UNION ALL SELECT 'task', task_id, COALESCE(MAX(title), task_id), MAX(work_item_status), MAX(risk), MIN(occurred_at), MIN(occurred_day_sp) FROM activities WHERE task_id IS NOT NULL AND NOT EXISTS (SELECT 1 FROM canonical_work_items c WHERE c.entity_kind='task' AND c.id=activities.task_id) GROUP BY task_id UNION ALL SELECT 'spec', spec_id, COALESCE(MAX(title), spec_id), MAX(work_item_status), MAX(risk), MIN(occurred_at), MIN(occurred_day_sp) FROM activities WHERE spec_id IS NOT NULL AND NOT EXISTS (SELECT 1 FROM canonical_work_items c WHERE c.entity_kind='spec' AND c.id=activities.spec_id) GROUP BY spec_id UNION ALL SELECT 'prd', prd_id, COALESCE(MAX(title), prd_id), MAX(work_item_status), MAX(risk), MIN(occurred_at), MIN(occurred_day_sp) FROM activities WHERE prd_id IS NOT NULL AND NOT EXISTS (SELECT 1 FROM canonical_work_items c WHERE c.entity_kind='prd' AND c.id=activities.prd_id) GROUP BY prd_id;
         CREATE VIEW tasks AS SELECT id, title, status, risk, occurred_at, occurred_day_sp FROM work_items WHERE entity_kind = 'task';
         CREATE VIEW specs AS SELECT id, title, status, risk, occurred_at, occurred_day_sp FROM work_items WHERE entity_kind = 'spec';
@@ -3167,7 +3139,7 @@ export async function rebuildSqliteReadModel(
         cachePath,
         fingerprint,
         readModelSchemaVersion,
-        hasRequiredFirstFoldPayloads,
+        hasReusableSnapshotPayloads,
       ) === null
     ) {
       await rm(temporaryPath, { force: true });

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

@@ -2,9 +2,13 @@ import { copyFile, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promis
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { hasRequiredFirstFoldPayloads } from "./sqlite-first-fold-persistence.js";
-import { rebuildSqliteReadModel, SqliteReadModelFileSystem } from "./sqlite-read-model.js";
+import {
+  rebuildSqliteReadModel,
+  SqliteReadModelFileSystem,
+  validateSqliteReadModelSchema,
+} from "./sqlite-read-model.js";
 
 const roots: string[] = [];
 
@@ -13,6 +17,45 @@ afterEach(async () => {
 });
 
 describe("SQLite snapshot seed publication", () => {
+  it.each([
+    "old-schema",
+    "missing-index",
+  ])("rebuilds incompatible %s generations and stale seeds", async (damage) => {
+    const root = await mkdtemp(join(tmpdir(), "zaip-snapshot-index-upgrade-"));
+    roots.push(root);
+    await mkdir(join(root, ".agents", "config"), { recursive: true });
+    await writeFile(join(root, ".agents", "config", "project.yaml"), "zaip:\n  enabled: true\n");
+    const destination = join(root, ".local", "dashboard-sqlite", "read-model.sqlite");
+    const cacheDirectory = join(root, ".local", "dashboard-sqlite", "cache");
+    vi.stubEnv("ZAIP_SQLITE_DB_PATH", destination);
+    vi.stubEnv("ZAIP_SQLITE_CACHE_DIR", cacheDirectory);
+    vi.stubEnv("ZAIP_SQLITE_PREFER_LAST_VALID_SEED", "1");
+    try {
+      await expect(rebuildSqliteReadModel(root)).resolves.toMatchObject({ cache: "rebuilt" });
+      const seedName = (await readdir(cacheDirectory)).find((name) => name.endsWith(".sqlite"));
+      if (seedName === undefined) throw new Error("Expected the rebuilt seed");
+      for (const path of [destination, join(cacheDirectory, seedName)]) {
+        const database = new DatabaseSync(path);
+        try {
+          if (damage === "missing-index")
+            database.exec("DROP INDEX zaip_activities_work_item_identity");
+          else
+            database.exec(
+              "UPDATE zaip_aios_activities SET payload_json=json_set(payload_json, '$.value', '70') WHERE payload_type='metadata' AND json_extract(payload_json, '$.key')='schema_version'",
+            );
+        } finally {
+          database.close();
+        }
+      }
+      await expect(rebuildSqliteReadModel(root)).resolves.toMatchObject({ cache: "rebuilt" });
+      expect(() => validateSqliteReadModelSchema(destination)).not.toThrow();
+      await expect(rebuildSqliteReadModel(root)).resolves.toMatchObject({ cache: "stale_seed" });
+      expect(() => validateSqliteReadModelSchema(destination)).not.toThrow();
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
   it("skips a newer incomplete seed and materializes the prior complete cache", async () => {
     const root = await mkdtemp(join(tmpdir(), "zaip-snapshot-seed-"));
     roots.push(root);
@@ -58,6 +101,40 @@ describe("SQLite snapshot seed publication", () => {
     }
   });
 
+  it("uses a compatible stale seed before source inventory when launcher policy requests it", async () => {
+    const root = await mkdtemp(join(tmpdir(), "zaip-snapshot-seed-early-"));
+    roots.push(root);
+    await mkdir(join(root, ".agents", "records", "tasks"), { recursive: true });
+    await mkdir(join(root, ".agents", "config"), { recursive: true });
+    await writeFile(join(root, ".agents", "config", "project.yaml"), "zaip:\n  enabled: true\n");
+    await writeFile(join(root, ".agents", "records", "tasks", "task.md"), "# initial\n");
+    await rebuildSqliteReadModel(root);
+    await writeFile(join(root, ".agents", "records", "tasks", "task.md"), "# changed\n");
+    const previousPath = process.env.ZAIP_SQLITE_DB_PATH;
+    const previousSeed = process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED;
+    const previousProgress = process.env.ZAIP_DASHBOARD_LAUNCH_PROGRESS;
+    const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    try {
+      process.env.ZAIP_SQLITE_DB_PATH = join(root, ".local", "dashboard-sqlite", "served.sqlite");
+      process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED = "1";
+      process.env.ZAIP_DASHBOARD_LAUNCH_PROGRESS = "1";
+      await expect(rebuildSqliteReadModel(root)).resolves.toMatchObject({
+        cache: "stale_seed",
+        fingerprint_ms: 0,
+      });
+      expect(stderr.mock.calls.join("\n")).toContain('"phase":"stale_seed_ready"');
+      expect(stderr.mock.calls.join("\n")).not.toContain('"phase":"source_fingerprint_started"');
+    } finally {
+      stderr.mockRestore();
+      if (previousPath === undefined) delete process.env.ZAIP_SQLITE_DB_PATH;
+      else process.env.ZAIP_SQLITE_DB_PATH = previousPath;
+      if (previousSeed === undefined) delete process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED;
+      else process.env.ZAIP_SQLITE_PREFER_LAST_VALID_SEED = previousSeed;
+      if (previousProgress === undefined) delete process.env.ZAIP_DASHBOARD_LAUNCH_PROGRESS;
+      else process.env.ZAIP_DASHBOARD_LAUNCH_PROGRESS = previousProgress;
+    }
+  });
+
   it("rejects a seed whose board payload is truncated below canonical work", async () => {
     const root = await mkdtemp(join(tmpdir(), "zaip-snapshot-truncated-"));
     roots.push(root);

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-work-item-index.test.ts

@@ -0,0 +1,56 @@
+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 { afterEach, describe, 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) => rm(root, { recursive: true, force: true })));
+});
+
+describe("SQLite work-item identity index", () => {
+  it("uses the partial JSON identity index without changing canonical work-list IDs", async () => {
+    const root = await mkdtemp(join(tmpdir(), "zaip-work-item-index-"));
+    roots.push(root);
+    await mkdir(join(root, ".agents", "config"), { recursive: true });
+    await mkdir(join(root, ".agents", "records", "tasks"), { recursive: true });
+    await writeFile(join(root, ".agents", "config", "project.yaml"), "zaip:\n  enabled: true\n");
+    await writeFile(
+      join(root, ".agents", "records", "tasks", "TASK-INDEXED.md"),
+      "---\nid: TASK-INDEXED\ntitle: Indexed canonical task\nstatus: ready\nrisk: standard\ncreated_at: 2026-08-31T12:00:00.000Z\n---\n# Indexed canonical task\n",
+    );
+    const previousDbPath = process.env.ZAIP_SQLITE_DB_PATH;
+    process.env.ZAIP_SQLITE_DB_PATH = join(root, ".local", "dashboard-sqlite", "read-model.sqlite");
+    let filesystem: SqliteReadModelFileSystem | undefined;
+    try {
+      await rebuildSqliteReadModel(root);
+      filesystem = new SqliteReadModelFileSystem(root);
+      expect(
+        filesystem
+          .viewPage("operations_work_list", { limit: 10, offset: 0 })
+          .rows.map((row) => row.id),
+      ).toContain("TASK-INDEXED");
+      const database = new DatabaseSync(process.env.ZAIP_SQLITE_DB_PATH, { readOnly: true });
+      try {
+        const plan = database
+          .prepare(`EXPLAIN QUERY PLAN
+          SELECT a.task_id FROM zaip_vw_activities a WHERE a.task_id IS NOT NULL
+          AND NOT EXISTS (SELECT 1 FROM zaip_vw_canonical_work_items c WHERE c.entity_kind='task' AND c.id=a.task_id)
+          GROUP BY a.task_id`)
+          .all() as Array<{ detail: string }>;
+        expect(plan.map((row) => row.detail).join("\n")).toContain(
+          "zaip_activities_work_item_identity",
+        );
+      } finally {
+        database.close();
+      }
+    } finally {
+      filesystem?.close();
+      if (previousDbPath === undefined) delete process.env.ZAIP_SQLITE_DB_PATH;
+      else process.env.ZAIP_SQLITE_DB_PATH = previousDbPath;
+    }
+  });
+});

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

@@ -8,6 +8,8 @@ export async function createDashboardLaunchPage({ port, host, runtimeKind, healt
     phase: "Iniciando o launcher local",
     detail: "Abrindo a página de preparação.",
   };
+  let progressSteps = [{ phase: progress.phase, detail: progress.detail }];
+  progress = { ...progress, steps: progressSteps };
   const connections = new Set();
   let resolveRedirectObserved;
   const redirectObserved = new Promise((resolveObserved) => {
@@ -49,18 +51,26 @@ export async function createDashboardLaunchPage({ port, host, runtimeKind, healt
   <style>
     :root{color-scheme:dark;font-family:Inter,system-ui,sans-serif;background:#010610;color:#f1f5f9}
     *{box-sizing:border-box}body{margin:0;background:#010610}.launch-overlay{position:fixed;inset:0;width:100vw;height:100vh;display:grid;place-items:center;padding:clamp(18px,5vw,72px);background:radial-gradient(circle at 50% 35%,rgba(0,176,240,.11),transparent 42%),#010610}
-    .progress{width:min(100%,760px);padding:clamp(24px,4vw,42px);border:1px solid rgba(125,211,252,.2);border-radius:20px;background:rgba(3,9,22,.94);box-shadow:0 24px 80px rgba(0,0,0,.45);backdrop-filter:blur(10px)}.progress strong,.progress span:not(.handoff):not(.failure){display:block}.progress strong{font-size:clamp(1.05rem,2vw,1.35rem)}.progress span{color:#b6c6db;font-size:clamp(.88rem,1.5vw,1rem);margin-top:7px}.track{position:relative;height:9px;margin-top:20px;border-radius:999px;background:#172033;overflow:hidden}.track::after{content:"";position:absolute;inset:0;background:linear-gradient(90deg,transparent 0%,rgba(224,242,254,.14) 35%,rgba(224,242,254,.8) 50%,rgba(224,242,254,.14) 65%,transparent 100%);transform:translateX(-100%);animation:launch-activity 1.35s ease-in-out infinite;pointer-events:none}.progress.terminal-failure .track::after{animation:none;transform:none;background:rgba(254,202,202,.2)}.bar{position:relative;z-index:1;height:100%;width:4%;border-radius:inherit;background:linear-gradient(90deg,#38bdf8,#818cf8);transition:width .35s ease}@keyframes launch-activity{to{transform:translateX(100%)}}@media (prefers-reduced-motion:reduce){.track::after{animation:none;transform:none;background:linear-gradient(90deg,transparent 0%,rgba(224,242,254,.2) 50%,transparent 100%)}}.handoff,.failure{display:none;margin-top:16px;color:#dbeafe}.failure{color:#fecaca}
+    .progress{width:min(100%,760px);padding:clamp(24px,4vw,42px);border:1px solid rgba(125,211,252,.2);border-radius:20px;background:rgba(3,9,22,.94);box-shadow:0 24px 80px rgba(0,0,0,.45);backdrop-filter:blur(10px)}.progress strong,.progress span:not(.handoff):not(.failure){display:block}.progress strong{font-size:clamp(1.05rem,2vw,1.35rem)}.progress span{color:#b6c6db;font-size:clamp(.88rem,1.5vw,1rem);margin-top:7px}.track{position:relative;height:9px;margin-top:20px;border-radius:999px;background:#172033;overflow:hidden}.track::after{content:"";position:absolute;z-index:2;inset:0;background:linear-gradient(90deg,transparent 0%,rgba(224,242,254,.14) 35%,rgba(224,242,254,.8) 50%,rgba(224,242,254,.14) 65%,transparent 100%);transform:translateX(-100%);animation:launch-activity 1.35s ease-in-out infinite;pointer-events:none}.progress.terminal-failure .track::after{animation:none;transform:none;background:rgba(254,202,202,.2)}.progress.terminal-failure .bar{background:#f87171}.bar{position:relative;z-index:1;height:100%;width:4%;border-radius:inherit;background:linear-gradient(90deg,#38bdf8,#818cf8);transition:width .35s ease}@keyframes launch-activity{to{transform:translateX(100%)}}@media (prefers-reduced-motion:reduce){.track::after{animation:none;transform:none;background:linear-gradient(90deg,transparent 0%,rgba(224,242,254,.2) 50%,transparent 100%)}}.handoff,.failure{display:none;margin-top:16px;color:#dbeafe}.failure{color:#fecaca}
+    .activity{min-height:1.3em}.steps{display:grid;gap:7px;max-height:12.5rem;overflow:auto;margin:18px 0 0;padding:0;list-style:none}.steps li{position:relative;padding-left:20px;color:#94a3b8;font-size:.82rem}.steps li::before{content:"";position:absolute;left:1px;top:.4em;width:8px;height:8px;border-radius:50%;background:#475569}.steps li[data-state="active"]{color:#dbeafe}.steps li[data-state="active"]::before{background:#38bdf8;box-shadow:0 0 0 4px rgba(56,189,248,.16)}.progress.terminal-failure .steps li[data-state="active"]::before{background:#f87171}@media (prefers-reduced-motion:reduce){.bar{transition:none}}
   </style>
 </head>
 <body>
-  <main class="launch-overlay" aria-label="Preparando dashboard">
-    <section class="progress" aria-live="polite" role="status"><strong id="phase">Iniciando o launcher local</strong><span id="detail">Abrindo a página de preparação.</span><div class="track" id="track" aria-label="Preparação em andamento"><div class="bar" id="bar"></div></div><span class="handoff" id="handoff">O dashboard está pronto. Abrindo a tela principal automaticamente…</span><span class="failure" id="failure" role="alert"></span></section>
+  <main class="launch-overlay" aria-label="Preparando dashboard" aria-busy="true">
+    <section class="progress" aria-live="polite" role="status"><strong id="phase">Iniciando o launcher local</strong><span id="detail">Abrindo a página de preparação.</span><span class="activity" id="activity" aria-hidden="true">Atividade em andamento.</span><div class="track" id="track" role="progressbar" aria-label="Preparação em andamento" aria-valuemin="0" aria-valuemax="100" aria-valuenow="4" aria-valuetext="Iniciando o launcher local"><div class="bar" id="bar"></div></div><ol class="steps" id="steps" aria-label="Etapas de preparação"><li data-state="active">Iniciando o launcher local</li></ol><span class="handoff" id="handoff">O dashboard está pronto. Abrindo a tela principal automaticamente…</span><span class="failure" id="failure" role="alert"></span></section>
   </main>
   <script>
-    let handoffTarget=null,progressRequestInFlight=false,terminalFailure=false;
-    function showHandoff(target){handoffTarget=target;document.getElementById("handoff").style.display="block";document.getElementById("phase").textContent="Dashboard pronto";document.getElementById("detail").textContent="Concluindo a abertura da tela principal."}
-    function showFailure(next){terminalFailure=true;clearInterval(progressPoll);document.getElementById("phase").textContent=next.phase;document.getElementById("detail").textContent="A preparação não foi concluída. Consulte a mensagem abaixo para agir.";document.getElementById("bar").style.width="100%";document.getElementById("handoff").style.display="none";document.getElementById("failure").textContent=next.detail;document.getElementById("failure").style.display="block";document.querySelector(".progress").classList.add("terminal-failure")}
-    async function updateProgress(){if(progressRequestInFlight||terminalFailure)return terminalFailure;progressRequestInFlight=true;try{const r=await fetch("/api/v2/progress",{cache:"no-store",signal:AbortSignal.timeout(1000)});const p=await r.json();if(terminalFailure)return true;if(p.failure){showFailure(p.failure);return true}if(!handoffTarget){document.getElementById("phase").textContent=p.phase;document.getElementById("detail").textContent=p.detail};if(!terminalFailure)document.getElementById("bar").style.width=Math.max(4,Math.min(100,Number(p.percent)||4))+"%"}catch{}finally{progressRequestInFlight=false}return terminalFailure}
+    let handoffTarget=null,progressRequestInFlight=false,terminalFailure=false,lastProgressPercent=4,compilationStartedAt=null,compilationDetail="",compilationTicker=null,activeStepKey="",activeStepStartedAt=Date.now();
+    const reducedMotion=window.matchMedia?.("(prefers-reduced-motion: reduce)").matches===true;
+    const recordedStepKeys=new Set(["Iniciando o launcher local\\u0000Abrindo a página de preparação."]);
+    function stopCompilationTicker(){if(compilationTicker!==null){clearInterval(compilationTicker);compilationTicker=null}compilationStartedAt=null}
+    function renderCompilationElapsed(){if(compilationStartedAt===null||handoffTarget||terminalFailure)return;const seconds=Math.floor((Date.now()-compilationStartedAt)/1000);document.getElementById("detail").textContent=compilationDetail+" · Compilação em andamento · "+seconds+"s"}
+    function renderActivityElapsed(){if(handoffTarget||terminalFailure)return;const seconds=Math.floor((Date.now()-activeStepStartedAt)/1000);document.getElementById("activity").textContent="Etapa atual em andamento · "+seconds+"s"}
+    function recordStep(step){if(!step||typeof step.phase!=="string")return;const detail=typeof step.detail==="string"?step.detail:"";const key=step.phase+"\\u0000"+detail;if(recordedStepKeys.has(key))return;recordedStepKeys.add(key);const list=document.getElementById("steps");for(const item of list.querySelectorAll("li[data-state=active]"))item.dataset.state="complete";const item=document.createElement("li");item.dataset.state="active";item.textContent=detail?step.phase+" — "+detail:step.phase;list.append(item);while(list.children.length>10)list.removeChild(list.firstElementChild);list.scrollTop=list.scrollHeight}
+    function setProgressBar(percent,phase){lastProgressPercent=percent;document.getElementById("bar").style.width=percent+"%";document.getElementById("track").setAttribute("aria-valuenow",String(percent));document.getElementById("track").setAttribute("aria-valuetext",phase)}
+    function showHandoff(target){handoffTarget=target;stopCompilationTicker();setProgressBar(100,"Dashboard pronto");document.querySelector(".launch-overlay").setAttribute("aria-busy","false");document.getElementById("handoff").style.display="block";document.getElementById("phase").textContent="Dashboard pronto";document.getElementById("detail").textContent="Concluindo a abertura da tela principal.";document.getElementById("activity").textContent="Preparação concluída."}
+    function showFailure(next,percent=lastProgressPercent){terminalFailure=true;clearInterval(progressPoll);stopCompilationTicker();document.querySelector(".launch-overlay").setAttribute("aria-busy","false");document.getElementById("phase").textContent=next.phase;document.getElementById("detail").textContent="A preparação não foi concluída. Consulte a mensagem abaixo para agir.";setProgressBar(percent,next.phase);document.getElementById("handoff").style.display="none";document.getElementById("failure").textContent=next.detail;document.getElementById("failure").style.display="block";document.querySelector(".progress").classList.add("terminal-failure")}
+    async function updateProgress(){if(progressRequestInFlight||terminalFailure)return terminalFailure;progressRequestInFlight=true;try{const r=await fetch("/api/v2/progress",{cache:"no-store",signal:AbortSignal.timeout(1000)});const p=await r.json();if(terminalFailure)return true;const percent=Math.max(4,Math.min(100,Number(p.percent)||4));if(p.failure){showFailure(p.failure,percent);return true}if(!handoffTarget){for(const step of Array.isArray(p.steps)?p.steps:[p])recordStep(step);const nextStepKey=p.phase+"\\u0000"+(p.detail??"");if(nextStepKey!==activeStepKey){activeStepKey=nextStepKey;activeStepStartedAt=Date.now()}document.getElementById("phase").textContent=p.phase;const compiling=p.phase.startsWith("Atualizando ");if(compiling){if(compilationStartedAt===null){compilationStartedAt=Date.now();compilationDetail=p.detail;if(!reducedMotion)compilationTicker=setInterval(renderCompilationElapsed,1000)}renderCompilationElapsed()}else{stopCompilationTicker();document.getElementById("detail").textContent=p.detail}renderActivityElapsed()}if(!terminalFailure&&!handoffTarget)setProgressBar(percent,p.phase)}catch{}finally{progressRequestInFlight=false}return terminalFailure}
     const progressPoll=setInterval(updateProgress,250);
     async function waitForDashboard(){try{if(await updateProgress())return;const ready=await fetch("/api/v2/ready",{cache:"no-store",signal:AbortSignal.timeout(1000)});const next=await ready.json();if(next.failure){showFailure(next.failure);return}if(next.target){showHandoff(next.target);clearInterval(progressPoll);setTimeout(()=>location.replace(next.target),0);return}const response=await fetch("${healthPath}",{cache:"no-store",signal:AbortSignal.timeout(1000)});const payload=await response.json();if(response.ok&&payload.kind==="${runtimeKind}"){clearInterval(progressPoll);location.reload();return}}catch{}setTimeout(waitForDashboard,250)}
     updateProgress();setTimeout(waitForDashboard,100)
@@ -86,10 +96,18 @@ export async function createDashboardLaunchPage({ port, host, runtimeKind, healt
       redirectUrl = target;
     },
     setProgress: (next) => {
+      const nextStep = {
+        phase: next.phase ?? progress.phase,
+        detail: next.detail ?? progress.detail,
+      };
+      const previousStep = progressSteps.at(-1);
+      if (previousStep?.phase !== nextStep.phase || previousStep.detail !== nextStep.detail)
+        progressSteps = [...progressSteps, nextStep].slice(-10);
       progress = {
         ...progress,
         ...next,
         percent: Math.max(progress.percent, next.percent ?? progress.percent),
+        steps: progressSteps,
       };
     },
     setFailure: (next) => {
@@ -97,7 +115,7 @@ export async function createDashboardLaunchPage({ port, host, runtimeKind, healt
       progress = {
         ...progress,
         ...next,
-        percent: Math.max(progress.percent, next.percent ?? progress.percent),
+        percent: progress.percent,
       };
     },
     waitForRedirect: async (timeoutMs = 1_500) =>

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

@@ -16,7 +16,14 @@ describe("dashboard launch page", () => {
       expect(html).toContain("position:fixed;inset:0;width:100vw;height:100vh");
       expect(html).toContain("display:grid;place-items:center");
       expect(html).toContain('aria-live="polite" role="status"');
-      expect(html).toContain('aria-label="Preparação em andamento"');
+      expect(html).toContain('role="progressbar" aria-label="Preparação em andamento"');
+      expect(html).toContain('aria-valuemin="0" aria-valuemax="100" aria-valuenow="4"');
+      expect(html).toContain('aria-busy="true"');
+      expect(html).toContain("z-index:2");
+      expect(html).toContain("Compilação em andamento");
+      expect(html).toContain('id="steps" aria-label="Etapas de preparação"');
+      expect(html).toContain('id="activity" aria-hidden="true"');
+      expect(html).toContain("function recordStep(step)");
       expect(html).toContain("animation:launch-activity 1.35s ease-in-out infinite");
       expect(html).toContain("@media (prefers-reduced-motion:reduce)");
       expect(html).toContain("O dashboard está pronto. Abrindo a tela principal automaticamente…");
@@ -27,6 +34,12 @@ describe("dashboard launch page", () => {
       await expect(progress.json()).resolves.toMatchObject({
         phase: "Iniciando o launcher local",
         percent: expect.any(Number),
+        steps: [
+          {
+            phase: "Iniciando o launcher local",
+            detail: "Abrindo a página de preparação.",
+          },
+        ],
       });
       expect(health.status).toBe(503);
       await expect(health.json()).resolves.toEqual({
@@ -62,10 +75,26 @@ describe("dashboard launch page", () => {
           page.locator("#handoff").evaluate((element) => getComputedStyle(element).display),
         )
         .toBe("none");
-      launchPage.setProgress({ percent: 64, phase: "Atualizando progresso independente" });
+      launchPage.setProgress({
+        percent: 64,
+        phase: "Atualizando a interface",
+        detail: "Uma dependência deste artefato foi modificada.",
+      });
+      await expect.poll(() => page.locator("#phase").textContent()).toBe("Atualizando a interface");
+      await expect.poll(() => page.locator("#track").getAttribute("aria-valuenow")).toBe("64");
       await expect
-        .poll(() => page.locator("#phase").textContent())
-        .toBe("Atualizando progresso independente");
+        .poll(() => page.locator("#track").getAttribute("aria-valuetext"))
+        .toBe("Atualizando a interface");
+      await expect
+        .poll(() => page.locator("#detail").textContent())
+        .toContain("Compilação em andamento · 0s");
+      await expect.poll(() => page.locator("#steps li").count()).toBe(2);
+      await expect
+        .poll(() => page.locator("#steps li[data-state=active]").textContent())
+        .toContain("Atualizando a interface");
+      await expect
+        .poll(() => page.locator("#activity").textContent())
+        .toContain("Etapa atual em andamento");
 
       await page.evaluate(() => window.showHandoff("http://127.0.0.1:4417/?token=ready"));
       await expect
@@ -73,6 +102,9 @@ describe("dashboard launch page", () => {
           page.locator("#handoff").evaluate((element) => getComputedStyle(element).display),
         )
         .toBe("block");
+      await expect
+        .poll(() => page.locator(".launch-overlay").getAttribute("aria-busy"))
+        .toBe("false");
     } finally {
       await browser.close();
       await launchPage.close();
@@ -83,6 +115,11 @@ describe("dashboard launch page", () => {
     const launchPage = await startDashboardLaunchPage(0);
     const browser = await chromium.launch();
     try {
+      launchPage.setProgress({
+        percent: 64,
+        phase: "Atualizando o runtime local",
+        detail: "Uma dependência deste artefato foi modificada.",
+      });
       launchPage.setFailure({
         percent: 100,
         phase: "Não foi possível preparar o dashboard",
@@ -136,6 +173,10 @@ describe("dashboard launch page", () => {
       await expect
         .poll(() => page.locator("#bar").evaluate((element) => getComputedStyle(element).width))
         .not.toBe("4px");
+      await expect.poll(() => page.locator("#track").getAttribute("aria-valuenow")).toBe("64");
+      await expect
+        .poll(() => page.locator(".launch-overlay").getAttribute("aria-busy"))
+        .toBe("false");
 
       await launchPage.closeAfterFailureObservation(0);
       await expect

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

@@ -0,0 +1,58 @@
+import { rename, writeFile } from "node:fs/promises";
+import process from "node:process";
+
+export function presentLaunchFailure(launchPage, error, formatError) {
+  if (launchPage === null) return null;
+  launchPage.setFailure({
+    percent: 100,
+    phase: "Não foi possível preparar o dashboard",
+    detail: formatError(error instanceof Error ? error.message : String(error), 900),
+  });
+  launchPage.closeAfterFailureObservation();
+  return null;
+}
+
+export function createPhaseTimer(appendLauncherLog, launcherPid) {
+  return (phase, startedAt, details = {}) => {
+    appendLauncherLog(
+      JSON.stringify({
+        event: "dashboard_sqlite_phase",
+        phase,
+        elapsed_ms: Date.now() - startedAt,
+        launcher_pid: launcherPid,
+        ...details,
+      }),
+    );
+  };
+}
+
+export async function writeLauncherStatus(status, message = "") {
+  const path = process.env.ZAIP_LAUNCH_STATUS;
+  if (!path) return;
+  const temporaryPath = `${path}.${process.pid}.tmp`;
+  await writeFile(temporaryPath, `${status}\n${message}`.trimEnd(), "utf8");
+  await rename(temporaryPath, path);
+}
+
+export async function awaitOwnedDashboardExit({
+  child,
+  currentSession,
+  clearOwnedDashboardSession,
+  recordPortStatus,
+  removeGeneratedReadModel,
+  processRef = process,
+}) {
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    processRef.once(signal, () => child.kill(signal));
+  }
+  const exitCode = await new Promise((resolveExit, rejectExit) => {
+    child.once("error", rejectExit);
+    child.once("exit", (code) => resolveExit(code ?? 0));
+  });
+  await clearOwnedDashboardSession();
+  if (currentSession !== null) {
+    await recordPortStatus(currentSession, "closed");
+    await removeGeneratedReadModel(currentSession.dbPath);
+  }
+  return exitCode;
+}