@zaip-ai/cli 2.2.0 → 2.6.0

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

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

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

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

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

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

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

@@ -38,4 +38,22 @@ describe("snapshot source synchronization", () => {
     await vi.advanceTimersByTimeAsync(300);
     expect(refresh).toHaveBeenCalledTimes(2);
   });
+
+  it("reports failed refreshes with their observable trigger", async () => {
+    vi.useFakeTimers();
+    const onRefreshFailure = vi.fn();
+    startSnapshotSynchronization({
+      workspaceRoot: "C:/workspace",
+      staleSeed: true,
+      watchSources: false,
+      refresh: async () => {
+        throw new Error("read model unavailable");
+      },
+      onRefreshFailure,
+    });
+    await vi.runAllTimersAsync();
+    expect(onRefreshFailure).toHaveBeenCalledWith(
+      expect.objectContaining({ trigger: "stale_seed", error: expect.any(Error) }),
+    );
+  });
 });

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

@@ -6,15 +6,21 @@ export function startSnapshotSynchronization(input: {
   staleSeed: boolean;
   watchSources: boolean;
   refresh: () => Promise<void>;
+  /** Exact active-Codex collection, separate from projection and lifecycle repair. */
+  captureActiveTelemetry?: () => Promise<void>;
+  /** Report failed asynchronous refreshes; a stale snapshot must never look healthy. */
+  onRefreshFailure?: (input: { trigger: "stale_seed" | "source_change"; error: unknown }) => void;
 }): void {
-  if (input.staleSeed) void input.refresh().catch(() => undefined);
+  const refresh = (trigger: "stale_seed" | "source_change") =>
+    void input.refresh().catch((error: unknown) => input.onRefreshFailure?.({ trigger, error }));
+  if (input.staleSeed) refresh("stale_seed");
   if (!input.watchSources || process.env.ZAIP_DASHBOARD_WATCH_SOURCES === "0") return;
   let pendingRefresh: NodeJS.Timeout | undefined;
   const scheduleRefresh = () => {
     if (pendingRefresh !== undefined) clearTimeout(pendingRefresh);
     pendingRefresh = setTimeout(() => {
       pendingRefresh = undefined;
-      void input.refresh().catch(() => undefined);
+      refresh("source_change");
     }, 300);
     pendingRefresh.unref();
   };
@@ -30,6 +36,16 @@ export function startSnapshotSynchronization(input: {
       // Reuse-triggered refresh remains the portable fallback.
     }
   }
-  const freshnessTimer = setInterval(scheduleRefresh, 60_000);
+  const captureAndRefresh = () => {
+    if (input.captureActiveTelemetry === undefined) return scheduleRefresh();
+    void input
+      .captureActiveTelemetry()
+      .catch((error: unknown) => input.onRefreshFailure?.({ trigger: "source_change", error }))
+      .finally(scheduleRefresh);
+  };
+  // Run at most once a minute. File watchers only project canonical changes;
+  // they never launch telemetry or lifecycle work.
+  captureAndRefresh();
+  const freshnessTimer = setInterval(captureAndRefresh, 60_000);
   freshnessTimer.unref();
 }