@zaip-ai/cli 2.2.0 → 2.6.0

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

@@ -1,27 +1,13 @@
-import { createHash, randomBytes } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
-import { loadWorkspaceLayout, WorkspaceFileSystem, type WorkspaceLayout } from "@zaip-ai/core";
+import { WorkspaceFileSystem, type WorkspaceLayout } from "@zaip-ai/core";
 import { fxRateSchema, PricingRepository, pricingCatalogSchema } from "@zaip-ai/costs";
-import {
-  buildCostSummaryProjection,
-  type CostSummarySource,
-} from "@zaip-ai/dashboard-cost-monitor/server";
-import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
-import {
-  buildOperationsProjection,
-  buildQuickOperationsProjection,
-  readPrdDetail,
-  readSpecDetail,
-  readTaskDetail,
-} from "@zaip-ai/dashboard-operations/server";
-import { buildTaskTrace } from "@zaip-ai/dashboard-traceability/server";
-import { LifecycleManifestStore } from "@zaip-ai/lifecycle-manifests";
 import { type Context, Hono } from "hono";
 import { getCookie, setCookie } from "hono/cookie";
-import type { ContentfulStatusCode } from "hono/utils/http-status";
+import { captureActiveCodexTelemetry } from "./active-codex-telemetry.js";
 import { runAgentAdapterSync } from "./agent-adapter-sync.js";
 import {
   type AgentAdapterSyncResult,
@@ -34,47 +20,28 @@ import {
   readProjectOverview,
   readProjectSettings,
 } from "./project-settings.js";
-import { agentPortraitFiles, openWorkIds } from "./server-agent-assets.js";
-import {
-  type BoardClassification,
-  boardFilters,
-  boardPage,
-  boardStage,
-  classificationPage,
-} from "./server-board.js";
+import { createProjectionRefreshDiagnostics } from "./projection-refresh-diagnostics.js";
+import { agentPortraitFiles } from "./server-agent-assets.js";
 import { registerBrowserLeaseRoute } from "./server-browser-lease.js";
-import { registerDailyReadModelRoute } from "./server-daily-read-models-route.js";
+import { registerCostsRoutes } from "./server-costs-routes.js";
 import {
-  changeEntityPageRows,
-  decisionEntityPageRows,
-  filterLifecyclePageRows,
-  operationsPageFilters,
-} from "./server-operations-pages.js";
-import { registerOperationsRunsRoute } from "./server-operations-runs-route.js";
+  API_PREFIX,
+  headOrJson,
+  requireV2Layout,
+  V2WorkspaceRequiredError,
+} from "./server-http-contracts.js";
+import { registerOperationsRoutes } from "./server-operations-routes.js";
 import { projectionPeriodFilter } from "./server-period.js";
-import { periodMacroMetric, projectAllTimeTopTasks } from "./server-period-macro-metric.js";
-import {
-  buildCanonicalOperationsProjection,
-  buildCurrentCostProjection,
-  buildManifestCostRunPage,
-  buildManifestFirstCostProjection,
-  isUnfilteredCostRequest,
-  knownWorkIds,
-  normalizeWorkPriority,
-  readCurrentFxRate,
-  readWorkPriority,
-} from "./server-projections.js";
+import { buildFirstFoldQuickProjection, dashboardSnapshot } from "./server-read-projections.js";
 import { isAllowedDashboardAuthority } from "./server-request-authority.js";
 import { refreshSqliteSnapshotInWorker } from "./server-snapshot-refresh.js";
 import { readCommittedSnapshotRevision } from "./server-snapshot-revision.js";
 import { startSnapshotSynchronization } from "./server-snapshot-synchronization.js";
-import { buildSqliteTaskTrace } from "./server-sqlite-task-trace.js";
 import { writeReadModelStartup, writeStartupPhase } from "./server-startup.js";
-import { queryValues, selectedCurrency } from "./server-summary-helpers.js";
+import { selectedCurrency } from "./server-summary-helpers.js";
+import { registerTraceRoutes } from "./server-trace-routes.js";
 import {
   createWorkReconciliation,
-  reconciliationNeedsRefresh,
-  startHostTerminalReconciliation,
   waitForWorkReconciliation,
 } from "./server-work-reconciliation.js";
 
@@ -84,14 +51,9 @@ import {
   dashboardIdentity,
   dashboardWorkspaceKey,
   ReconciliationCommandTimeoutError,
-  type ReconciliationResult,
   reconcileOpenWork,
 } from "./server-workspace.js";
-import {
-  rebuildSqliteReadModel,
-  SqliteReadModelFileSystem,
-  sqliteViewMetadata,
-} from "./sqlite-read-model.js";
+import { rebuildSqliteReadModel, SqliteReadModelFileSystem } from "./sqlite-read-model.js";
 
 export { manifestRun, mergeManifestRuns } from "./manifest-runs.js";
 export { openWorkIds } from "./server-agent-assets.js";
@@ -110,15 +72,10 @@ export {
   validateSqliteReadModelSchema,
 } from "./sqlite-read-model.js";
 
-type OverviewMacroMetrics = NonNullable<
-  NonNullable<OperationsProjection["summary"]["overview_metrics"]>["macro_metrics"]
->;
-
-const API_PREFIX = "/api/v2";
 const HOST = "127.0.0.1";
 const RUNTIME_KIND = "zaip-dashboard-sqlite-runtime";
 const SESSION_COOKIE = "zaip-dashboard-sqlite-session";
-const WORK_PRIORITY_PATH = ".agents/dashboard/work-priority.json";
+
 const SNAPSHOT_CACHE_TTL_MS = 5_000;
 interface DashboardAppOptions {
   syncAgentAdapters?: () => Promise<AgentAdapterSyncResult>;
@@ -137,10 +94,6 @@ interface DashboardAppOptions {
   launcherOwned?: boolean;
 }
 
-class V2WorkspaceRequiredError extends Error {
-  override readonly name = "V2WorkspaceRequiredError";
-}
-
 function isAllowedOrigin(origin: string): boolean {
   try {
     const parsed = new URL(origin);
@@ -151,7 +104,6 @@ function isAllowedOrigin(origin: string): boolean {
     return false;
   }
 }
-
 function isSafeUiPath(pathname: string): boolean {
   try {
     const decoded = decodeURIComponent(pathname).replaceAll("\\", "/");
@@ -160,462 +112,29 @@ function isSafeUiPath(pathname: string): boolean {
     return false;
   }
 }
-
 function defaultSessionToken(): string {
   return process.env.ZAIP_UI_TOKEN ?? randomBytes(24).toString("base64url");
 }
-
 function shouldBootstrapBrowserSession(context: Context): boolean {
   if (context.req.method !== "GET" && context.req.method !== "HEAD") return false;
   if (context.req.path !== "/" && context.req.path !== "/index.html") return false;
-
   const origin = context.req.header("origin");
   if (origin !== undefined && !isAllowedOrigin(origin)) return false;
   return context.req.header("sec-fetch-site") !== "cross-site";
 }
 
-async function requireV2Layout(filesystem: WorkspaceFileSystem): Promise<WorkspaceLayout> {
-  const layout = await loadWorkspaceLayout(filesystem);
-  if (layout.version === 1) {
-    throw new V2WorkspaceRequiredError("Dashboard API requires a modern ZAIP-AIOS workspace");
-  }
-  return layout;
-}
-
-function headOrJson(
-  context: Context,
-  payload: unknown,
-  status: ContentfulStatusCode = 200,
-  cacheable = false,
-): Response {
-  if (cacheable) {
-    const etag = `"${createHash("sha256").update(JSON.stringify(payload)).digest("base64url")}"`;
-    context.header("ETag", etag);
-    context.header("Cache-Control", "private, no-cache");
-    if (context.req.header("if-none-match") === etag) return context.body(null, 304);
-  }
-  if (context.req.method === "HEAD") return context.body(null, status);
-  return context.json(payload, status);
-}
 /**
  * Keep the entity/macro details on the snapshot filesystem, while making the
  * first-fold counters and token/cost facts come from SQL.
  * Duration intentionally retains the shared hybrid legacy policy in the
  * Operations module; its underlying daily rows are still SQLite-backed.
  */
-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,
-      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",
-      },
-    },
-  };
-}
 
 /**
  * SQLite's files snapshot intentionally excludes derived lifecycle manifests.
  * Build the Operations first fold from its canonical SQL views instead of
  * treating a missing manifest as a broken workspace.
  */
-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: [],
-  };
-}
-
-function nullableMetric(value: unknown): number | null {
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
-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";
-}
-
-function normalizeRisk(value: unknown): "lite" | "standard" | "critical" {
-  return ["lite", "standard", "critical"].includes(String(value))
-    ? (String(value) as "lite" | "standard" | "critical")
-    : "standard";
-}
-
-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";
-}
-
-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 function createDashboardApp(
   workspaceRoot = process.env.ZAIP_WORKSPACE ?? process.cwd(),
@@ -692,6 +211,7 @@ export function createDashboardApp(
     aggregateInFlight.clear();
   };
   let observedSnapshotRevision: string | null = null;
+  const projectionRefreshDiagnostics = createProjectionRefreshDiagnostics();
   let projectionRefreshInFlight: Promise<void> | null = null;
   let projectionRefreshRequested = false;
   const rebuildProjection = async () => {
@@ -701,15 +221,35 @@ export function createDashboardApp(
     }
     snapshotState = "updating";
     projectionRefreshInFlight = (async () => {
+      let passes = 0;
       do {
         projectionRefreshRequested = false;
         await refreshReadModel();
         if (isSqliteSnapshot) sqliteLayout = requireV2Layout(filesystem);
         clearSnapshotCache();
-      } while (projectionRefreshRequested);
+        passes += 1;
+        // Publish a committed generation after a bounded catch-up pass. A
+        // busy watcher must not hold `/ready` in `updating` indefinitely.
+      } while (projectionRefreshRequested && passes < 2);
       snapshotState = "current";
+      projectionRefreshDiagnostics.clear();
     })().finally(() => {
       projectionRefreshInFlight = null;
+      // Preserve a source change that arrived during the bounded catch-up.
+      // It starts after the committed generation becomes observable, rather
+      // than extending the current `updating` state without bound.
+      if (projectionRefreshRequested) {
+        projectionRefreshRequested = false;
+        // Yield a real event-loop turn with `current` exposed before starting
+        // another rebuild. `/ready` can then advertise the committed SQLite
+        // generation and open tabs can read it coherently.
+        const followUp = setTimeout(() => {
+          void rebuildProjection().catch((error: unknown) =>
+            projectionRefreshDiagnostics.record({ trigger: "source_change", error }),
+          );
+        }, 250);
+        followUp.unref();
+      }
     });
     return projectionRefreshInFlight;
   };
@@ -718,6 +258,10 @@ export function createDashboardApp(
     staleSeed: isSqliteSnapshot && snapshotState === "updating",
     watchSources: isSqliteSnapshot && options.watchSources === true,
     refresh: rebuildProjection,
+    ...(isSqliteSnapshot && options.watchSources === true
+      ? { captureActiveTelemetry: () => captureActiveCodexTelemetry(workspaceRoot) }
+      : {}),
+    onRefreshFailure: projectionRefreshDiagnostics.record,
   });
   const reconcileWork = createWorkReconciliation({
     reconcile: (mode) =>
@@ -726,13 +270,9 @@ export function createDashboardApp(
       }),
     refresh: rebuildProjection,
   });
-  if (
-    isSqliteSnapshot &&
-    options.watchSources === true &&
-    process.env.ZAIP_DASHBOARD_WATCH_SOURCES !== "0"
-  ) {
-    startHostTerminalReconciliation(() => reconcileWork("host-terminal"));
-  }
+  // Terminal usage is persisted by the host/CLI lifecycle boundary. The
+  // source synchronizer above projects those records, but the Dashboard must
+  // never run lifecycle reconciliation automatically on startup or a timer.
   const readSnapshot = (context: Context) => {
     const key = snapshotKey(context);
     const cached = cachedSnapshots.get(key);
@@ -758,7 +298,6 @@ export function createDashboardApp(
     snapshotInFlight.set(key, inFlight);
     return inFlight;
   };
-
   app.use("*", async (context, next) => {
     if (!isAllowedDashboardAuthority(context.req.url, context.req.header("host"))) {
       return context.json({ error: "Host rejected" }, 403);
@@ -779,7 +318,6 @@ export function createDashboardApp(
     }
     return next();
   });
-
   app.use(`${API_PREFIX}/*`, async (context, next) => {
     const settingsWrite =
       context.req.method === "PUT" &&
@@ -824,7 +362,6 @@ export function createDashboardApp(
     }
     if (context.req.path === `${API_PREFIX}/health` || context.req.path === `${API_PREFIX}/ready`)
       return next();
-
     const origin = context.req.header("origin");
     if (origin !== undefined && !isAllowedOrigin(origin)) {
       return context.json({ error: "Origin rejected" }, 403);
@@ -853,7 +390,6 @@ export function createDashboardApp(
     return next();
   });
   registerBrowserLeaseRoute(app, API_PREFIX, options.launcherOwned === true);
-
   app.on(["GET", "HEAD"], `${API_PREFIX}/health`, async (context) => {
     try {
       const layout = await readLayout();
@@ -861,12 +397,13 @@ export function createDashboardApp(
         kind: RUNTIME_KIND,
         workspaceKey,
         service: "zaip-aios-dashboard",
-        status: "ok",
+        status: projectionRefreshDiagnostics.healthStatus,
         api_version: 2,
         workspace_layout: layout.version,
         read_only: true,
         storage: isSqliteSnapshot ? filesystem.metadata() : { storage_mode: "filesystem" },
         snapshot_state: snapshotState,
+        projection_refresh_failure: projectionRefreshDiagnostics.failure,
       });
     } catch (error) {
       return headOrJson(
@@ -884,7 +421,6 @@ export function createDashboardApp(
       );
     }
   });
-
   // Launcher readiness proves a canonical projection can be read; health alone
   // intentionally remains a lightweight process/layout probe.
   app.on(["GET", "HEAD"], `${API_PREFIX}/ready`, async (context) => {
@@ -913,6 +449,7 @@ export function createDashboardApp(
           // /ready must never start a competing projection in the background.
           day_count: metadata.daily_aggregate_count,
           snapshot_state: snapshotState,
+          projection_refresh_failure: projectionRefreshDiagnostics.failure,
           snapshot_revision: revision,
         });
       }
@@ -939,321 +476,21 @@ export function createDashboardApp(
       );
     }
   });
-
   // Header identity is intentionally separate from Operations projections.
   // The quick first fold omits it, and resolving this small configuration/git
   // value must not read, refresh, or otherwise materialize a snapshot.
   app.on(["GET", "HEAD"], `${API_PREFIX}/dashboard-identity`, async (context) =>
     headOrJson(context, await dashboardIdentity(filesystem, workspaceRoot)),
   );
-
-  app.on(["GET", "HEAD"], `${API_PREFIX}/operations`, async (context) => {
-    try {
-      const requestStartedAt = performance.now();
-      const scope = context.req.query("scope");
-      if (
-        scope !== "overview" &&
-        scope !== "quick" &&
-        scope !== "detail" &&
-        scope !== "board" &&
-        scope !== "classification"
-      )
-        return headOrJson(context, (await readSnapshot(context)).operations);
-      const layout = await readLayout();
-      const layoutMs = performance.now() - requestStartedAt;
-      const { from, to } = projectionPeriodFilter(context);
-      if (scope === "board") {
-        const stage = boardStage(context.req.query("stage"));
-        const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
-        const limit = Math.min(
-          50,
-          Math.max(1, Number.parseInt(context.req.query("limit") ?? "10", 10) || 10),
-        );
-        const board = await readAggregate(
-          `operations:board:${from ?? ""}:${to ?? ""}`,
-          async () => {
-            const projection = await buildFirstFoldQuickProjection(
-              filesystem,
-              layout,
-              { from, to },
-              { includeBoardTasks: true },
-            );
-            return {
-              projection,
-              priority: await readWorkPriority(canonicalFilesystem, knownWorkIds(projection)),
-            };
-          },
-        );
-        const filters = boardFilters(context);
-        const pageKey = JSON.stringify({ from, to, stage, offset, limit, ...filters });
-        const page = await readAggregate(`operations:board-page:${pageKey}`, async () =>
-          boardPage(board.projection, stage, offset, limit, board.priority.item_ids, filters),
-        );
-        return headOrJson(context, page, 200, true);
-      }
-      if (scope === "classification") {
-        const kind = context.req.query("kind");
-        const classification = context.req.query("classification");
-        if (kind !== "task" && kind !== "spec" && kind !== "prd")
-          return headOrJson(context, { error: "A valid work kind is required" }, 400);
-        if (
-          !["lite", "standard", "critical", "empty", "structured", "rework"].includes(
-            classification ?? "",
-          )
-        )
-          return headOrJson(context, { error: "A valid classification is required" }, 400);
-        const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
-        const limit = Math.min(
-          50,
-          Math.max(1, Number.parseInt(context.req.query("limit") ?? "50", 10) || 50),
-        );
-        const projection = await readAggregate(
-          `operations:classification:${from ?? ""}:${to ?? ""}`,
-          () =>
-            buildFirstFoldQuickProjection(
-              filesystem,
-              layout,
-              { from, to },
-              { includeBoardTasks: true },
-            ),
-        );
-        return headOrJson(
-          context,
-          classificationPage(
-            projection,
-            kind,
-            classification as BoardClassification,
-            offset,
-            limit,
-          ),
-          200,
-          true,
-        );
-      }
-      if (scope === "quick") {
-        const projectionStartedAt = performance.now();
-        const quick = await readAggregate(
-          `operations:quick:${from ?? ""}:${to ?? ""}`,
-          () =>
-            buildFirstFoldQuickProjection(
-              filesystem,
-              layout,
-              { from, to },
-              {
-                includeTopTasks: from === null && to === null,
-                includeExtended: from === null && to === null,
-              },
-            ),
-          context.req.query("fresh") === "1",
-        );
-        if (
-          process.env.ZAIP_DASHBOARD_PROFILE_FIRST_FOLD === "1" &&
-          filesystem instanceof SqliteReadModelFileSystem
-        ) {
-          const timings = filesystem.firstFoldViewportProfile();
-          context.header(
-            "Server-Timing",
-            [
-              `layout;dur=${Math.round(layoutMs * 10) / 10}`,
-              `projection;dur=${Math.round((performance.now() - projectionStartedAt) * 10) / 10}`,
-              ...Object.entries(timings).map(([name, duration]) => `${name};dur=${duration}`),
-            ].join(", "),
-          );
-        }
-        return headOrJson(context, quick, 200, true);
-      }
-      const projection =
-        filesystem instanceof SqliteReadModelFileSystem
-          ? await buildFirstFoldQuickProjection(
-              filesystem,
-              layout,
-              { from, to },
-              {
-                includeBoardTasks: scope === "detail",
-                includeExtended: scope === "detail" || scope === "overview",
-                includePeriods: scope === "detail" || scope === "overview",
-              },
-            )
-          : await buildCanonicalOperationsProjection(
-              filesystem,
-              layout,
-              { from, to },
-              scope === "overview",
-            );
-      return headOrJson(context, projection, 200, scope === "overview");
-    } catch (error) {
-      if (error instanceof V2WorkspaceRequiredError) throw error;
-      return headOrJson(
-        context,
-        { error: error instanceof Error ? error.message : String(error) },
-        400,
-      );
-    }
+  registerOperationsRoutes(app, {
+    filesystem,
+    canonicalFilesystem,
+    isSqliteSnapshot,
+    readLayout,
+    readSnapshot,
+    readAggregate,
+    clearSnapshotCache,
   });
-
-  registerOperationsRunsRoute(app, filesystem, readAggregate, headOrJson);
-
-  // Explicit SQL read-model API for the comparison dashboard. It never falls
-  // back to filesystem pagination, making first-fold/entity query plans
-  // inspectable while preserving the established Operations contracts.
-  app.on(["GET", "HEAD"], `${API_PREFIX}/sqlite-read-models`, async (context) => {
-    if (!(filesystem instanceof SqliteReadModelFileSystem))
-      return headOrJson(context, { error: "SQLite read model is not active" }, 409);
-    const kind = context.req.query("kind");
-    const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
-    const limit = Math.min(
-      200,
-      Math.max(1, Number.parseInt(context.req.query("limit") ?? "20", 10) || 20),
-    );
-    if (kind === "overview") {
-      const period = context.req.query("period");
-      if (period !== "day" && period !== "month" && period !== "year")
-        return headOrJson(context, { error: "Unsupported SQLite overview period" }, 400);
-      return headOrJson(context, filesystem.overviewPage(period, offset, limit), 200, true);
-    }
-    if (kind !== "task" && kind !== "spec" && kind !== "prd")
-      return headOrJson(context, { error: "Unsupported SQLite read model" }, 400);
-    const { from, to } = projectionPeriodFilter(context);
-    const filters = operationsPageFilters(context);
-    return headOrJson(
-      context,
-      filesystem.summaryPage(
-        kind,
-        { from, to, ...filters },
-        offset,
-        limit,
-        context.req.query("cursor") ?? null,
-      ),
-      200,
-      true,
-    );
-  });
-
-  app.on(["GET", "HEAD"], `${API_PREFIX}/sqlite-views`, async (context) => {
-    if (!(filesystem instanceof SqliteReadModelFileSystem))
-      return headOrJson(context, { error: "SQLite read model is not active" }, 409);
-    const view = context.req.query("view");
-    if (view === undefined || !(view in sqliteViewMetadata))
-      return headOrJson(context, { error: "Unsupported SQLite view" }, 400);
-    const parsed = Number.parseInt(context.req.query("limit") ?? "", 10);
-    const defaultLimit = view.includes("agent_invocations")
-      ? 100
-      : view === "first_fold_top_tasks"
-        ? 5
-        : 50;
-    const limit = Math.min(200, Math.max(1, Number.isFinite(parsed) ? parsed : defaultLimit));
-    const { from, to } = projectionPeriodFilter(context);
-    const optional = (name: string) => {
-      const value = context.req.query(name);
-      return value === undefined ? {} : { [name]: value };
-    };
-    const workListKind = context.req.query("kind");
-    if (
-      view === "operations_work_list" &&
-      workListKind !== undefined &&
-      !["all", "task", "standalone-task", "prd", "spec"].includes(workListKind)
-    )
-      return headOrJson(context, { error: "Unsupported Operations work-list kind" }, 400);
-    return headOrJson(
-      context,
-      filesystem.viewPage(view as keyof typeof sqliteViewMetadata, {
-        from,
-        to,
-        ...optional("query"),
-        ...optional("status"),
-        ...optional("risk"),
-        ...optional("provider"),
-        ...optional("model"),
-        ...optional("agent"),
-        ...optional("phase"),
-        ...optional("origin"),
-        ...optional("workType"),
-        ...optional("priority"),
-        ...(workListKind === undefined
-          ? {}
-          : { kind: workListKind as "all" | "task" | "standalone-task" | "prd" | "spec" }),
-        offset: Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0),
-        limit,
-      }),
-      200,
-      true,
-    );
-  });
-
-  app.on(["GET", "HEAD"], `${API_PREFIX}/work-priority`, async (context) => {
-    const layout = await requireV2Layout(canonicalFilesystem);
-    const operations = await buildOperationsProjection(canonicalFilesystem, layout, {
-      from: null,
-      to: null,
-    });
-    return headOrJson(
-      context,
-      await readWorkPriority(canonicalFilesystem, knownWorkIds(operations)),
-    );
-  });
-
-  app.on(["GET", "HEAD"], `${API_PREFIX}/operations/entities`, async (context) => {
-    const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
-    const limit = Math.min(
-      500,
-      Math.max(1, Number.parseInt(context.req.query("limit") ?? "100", 10) || 100),
-    );
-    const kind = context.req.query("kind");
-    if (kind !== "changes" && kind !== "decisions")
-      return headOrJson(context, { error: "Unsupported Operations entity page" }, 400);
-    const { from, to } = projectionPeriodFilter(context);
-    const pageFilters = operationsPageFilters(context);
-    const payload = await readAggregate(
-      `operations:entities:${kind}:${from ?? ""}:${to ?? ""}:${offset}:${limit}:${pageFilters.query}:${pageFilters.status}:${pageFilters.risk}`,
-      async () => {
-        const layout = await readLayout();
-        const entities = await new LifecycleManifestStore(filesystem).readEntities(
-          kind === "changes" ? "change" : "decision",
-        );
-        const entityRows =
-          kind === "changes"
-            ? changeEntityPageRows(entities, layout, from, to)
-            : decisionEntityPageRows(entities, layout, from, to);
-        const rows = filterLifecyclePageRows(entityRows, pageFilters);
-        return {
-          data_source: "lifecycle_manifest_shards",
-          kind,
-          offset,
-          limit,
-          total: rows.length,
-          rows: rows.slice(offset, offset + limit),
-        };
-      },
-    );
-    return headOrJson(context, payload, 200, true);
-  });
-
-  registerDailyReadModelRoute(app, filesystem, readAggregate, headOrJson);
-  app.put(`${API_PREFIX}/work-priority`, async (context) => {
-    const candidate = normalizeWorkPriority(await context.req.json());
-    // Priority is canonical queue configuration, never snapshot content.
-    // Keep every other settings mutation blocked in snapshot-serving mode.
-    await canonicalFilesystem.writeTextAtomic(
-      WORK_PRIORITY_PATH,
-      `${JSON.stringify(candidate, null, 2)}\n`,
-    );
-    clearSnapshotCache();
-    return context.json(candidate);
-  });
-
-  app.on(["GET", "HEAD"], `${API_PREFIX}/snapshot`, async (context) => {
-    try {
-      return headOrJson(context, await readSnapshot(context));
-    } catch (error) {
-      if (error instanceof V2WorkspaceRequiredError) throw error;
-      return headOrJson(
-        context,
-        { error: error instanceof Error ? error.message : String(error) },
-        400,
-      );
-    }
-  });
-
   app.post(`${API_PREFIX}/reconcile-open-work`, async (context) => {
     try {
       await readLayout();
@@ -1286,7 +523,6 @@ export function createDashboardApp(
       return context.json({ error: error instanceof Error ? error.message : String(error) }, 400);
     }
   });
-
   app.post(`${API_PREFIX}/refresh-projection`, async (context) => {
     try {
       await readLayout();
@@ -1297,151 +533,15 @@ export function createDashboardApp(
       return context.json({ error: error instanceof Error ? error.message : String(error) }, 400);
     }
   });
-
-  app.on(["GET", "HEAD"], `${API_PREFIX}/cost-monitor`, async (context) => {
-    try {
-      const scope = context.req.query("scope") ?? "summary";
-      if (scope === "summary") {
-        const layout = await readLayout();
-        const { from, to } = projectionPeriodFilter(context);
-        const currency = selectedCurrency(context);
-        const aggregateStartedAt = performance.now();
-        const [source, rate] = await Promise.all([
-          firstFoldCostSource(filesystem, {
-            from,
-            to,
-            providers: queryValues(context, "provider"),
-            models: queryValues(context, "model"),
-            agents: queryValues(context, "agent"),
-            phases: queryValues(context, "phase"),
-            statuses: queryValues(context, "status"),
-            tasks: queryValues(context, "task"),
-            specs: queryValues(context, "spec"),
-            prds: queryValues(context, "prd"),
-            executions: queryValues(context, "execution"),
-            changes: queryValues(context, "change"),
-          }),
-          currency === "BRL" ? readCurrentFxRate(filesystem) : Promise.resolve(null),
-        ]);
-        // First fold receives only aggregate facts. Detailed Runs and entity
-        // arrays remain on their explicit paginated endpoints.
-        const aggregateMs = performance.now() - aggregateStartedAt;
-        const costOperations = {
-          schema_version: 1,
-          layout_version: layout.version,
-          readonly: true,
-          source: ".agents/records",
-          filters: { from, to },
-          summary: { task_count: source.task_count ?? 0 },
-          prds: [],
-          specs: [],
-          runs: [],
-        } as unknown as OperationsProjection;
-        const projectionStartedAt = performance.now();
-        const payload = buildCostSummaryProjection(
-          source,
-          costOperations,
-          currency,
-          rate?.rate ?? null,
-        );
-        context.header(
-          "Server-Timing",
-          `cost_sql;dur=${aggregateMs.toFixed(1)},cost_projection;dur=${(performance.now() - projectionStartedAt).toFixed(1)}`,
-        );
-        return headOrJson(context, payload, 200, true);
-      }
-      if (scope === "runs") {
-        const layout = await readLayout();
-        const { from, to } = projectionPeriodFilter(context);
-        const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
-        const limit = Math.min(
-          500,
-          Math.max(1, Number.parseInt(context.req.query("limit") ?? "100", 10) || 100),
-        );
-        return headOrJson(
-          context,
-          // The paged Cost adapter reads the lifecycle summary. That canonical
-          // artifact is intentionally not copied into SQLite; use its current
-          // filesystem alongside the immutable SQL facts rather than failing
-          // a filtered page with a synthetic missing-file error.
-          await buildManifestCostRunPage(
-            isSqliteSnapshot ? canonicalFilesystem : filesystem,
-            layout,
-            context,
-            { from, to },
-            offset,
-            limit,
-          ),
-          200,
-          true,
-        );
-      }
-      if (isUnfilteredCostRequest(context))
-        return headOrJson(context, (await readSnapshot(context)).costs);
-      const layout = await readLayout();
-      const { from, to } = projectionPeriodFilter(context);
-      // Cost and Operations must start from the same manifest-corrected Run
-      // population; financial availability is represented on each row, never
-      // by dropping lifecycle Runs before the Cost projection.
-      const operations = await buildCanonicalOperationsProjection(filesystem, layout, { from, to });
-      return headOrJson(
-        context,
-        await buildManifestFirstCostProjection(filesystem, operations, context),
-      );
-    } catch (error) {
-      if (error instanceof V2WorkspaceRequiredError) throw error;
-      return headOrJson(
-        context,
-        { error: error instanceof Error ? error.message : String(error) },
-        400,
-      );
-    }
-  });
-
-  /** Compact factual attribution view used by both Cost Monitor and Operations.
-   * It is intentionally read-only and is available only from a coherent SQLite
-   * generation, never by reopening mutable JSONL streams on a request. */
-  app.on(["GET", "HEAD"], `${API_PREFIX}/developers`, async (context) => {
-    if (!(filesystem instanceof SqliteReadModelFileSystem))
-      return headOrJson(
-        context,
-        { error: "Developer attribution requires the SQLite read model" },
-        409,
-      );
-    const { from, to } = projectionPeriodFilter(context);
-    return headOrJson(
-      context,
-      filesystem.developerCostAggregate({
-        from,
-        to,
-        accountIds: queryValues(context, "account_id"),
-      }),
-      200,
-      true,
-    );
+  registerCostsRoutes(app, {
+    filesystem,
+    canonicalFilesystem,
+    isSqliteSnapshot,
+    readLayout,
+    readSnapshot,
+    readAggregate,
+    clearSnapshotCache,
   });
-
-  /** Operations keeps its developer facts separate from Cost Monitor columns. */
-  app.on(["GET", "HEAD"], `${API_PREFIX}/operations/developers`, async (context) => {
-    if (!(filesystem instanceof SqliteReadModelFileSystem))
-      return headOrJson(
-        context,
-        { error: "Developer attribution requires the SQLite read model" },
-        409,
-      );
-    const { from, to } = projectionPeriodFilter(context);
-    return headOrJson(
-      context,
-      filesystem.operationsDeveloperAggregate({
-        from,
-        to,
-        accountIds: queryValues(context, "account_id"),
-      }),
-      200,
-      true,
-    );
-  });
-
   app.on(["GET", "HEAD"], `${API_PREFIX}/pricing`, async (context) =>
     headOrJson(
       context,
@@ -1450,7 +550,6 @@ export function createDashboardApp(
       ),
     ),
   );
-
   app.put(`${API_PREFIX}/pricing`, async (context) => {
     const catalog = pricingCatalogSchema.parse({
       ...(await context.req.json()),
@@ -1463,19 +562,16 @@ export function createDashboardApp(
     clearSnapshotCache();
     return context.json(catalog);
   });
-
   app.on(["GET", "HEAD"], `${API_PREFIX}/fx-rate`, async (context) => {
     const rate = await new PricingRepository(filesystem).readLatestFxRate();
     return headOrJson(context, rate);
   });
-
   app.put(`${API_PREFIX}/fx-rate`, async (context) => {
     const input = fxRateSchema.pick({ rate: true }).parse(await context.req.json());
     const rate = await new PricingRepository(filesystem).writeCurrentFxRate(input.rate);
     clearSnapshotCache();
     return context.json(rate);
   });
-
   app.on(["GET", "HEAD"], `${API_PREFIX}/agent-catalog`, async (context) => {
     try {
       return headOrJson(context, await readAgentCatalogSettings(filesystem));
@@ -1487,7 +583,6 @@ export function createDashboardApp(
       );
     }
   });
-
   app.get(`${API_PREFIX}/agent-catalog-assets/:agentId`, async (context) => {
     const portrait = agentPortraitFiles[context.req.param("agentId")];
     if (portrait === undefined) return context.json({ error: "Agent portrait not found" }, 404);
@@ -1504,7 +599,6 @@ export function createDashboardApp(
       return context.json({ error: "Agent portrait could not be read" }, 500);
     }
   });
-
   app.put(`${API_PREFIX}/agent-catalog`, async (context) => {
     const update = async () => {
       try {
@@ -1529,7 +623,6 @@ export function createDashboardApp(
     );
     return result;
   });
-
   app.on(["GET", "HEAD"], `${API_PREFIX}/project-settings`, async (context) => {
     try {
       return headOrJson(context, await readProjectSettings(canonicalFilesystem));
@@ -1541,11 +634,9 @@ export function createDashboardApp(
       );
     }
   });
-
   app.on(["GET", "HEAD"], `${API_PREFIX}/project-settings/overview`, async (context) => {
     return headOrJson(context, await readProjectOverview(canonicalFilesystem));
   });
-
   app.put(`${API_PREFIX}/project-settings`, async (context) => {
     try {
       const persisted = await persistProjectSettings(canonicalFilesystem, await context.req.json());
@@ -1558,53 +649,15 @@ export function createDashboardApp(
       );
     }
   });
-
-  app.on(["GET", "HEAD"], `${API_PREFIX}/tasks/:id`, async (context) => {
-    try {
-      const layout = await readLayout();
-      return headOrJson(context, await readTaskDetail(filesystem, layout, context.req.param("id")));
-    } catch (error) {
-      if (error instanceof V2WorkspaceRequiredError) throw error;
-      return headOrJson(context, { error: "Task not found" }, 404);
-    }
-  });
-
-  app.on(["GET", "HEAD"], `${API_PREFIX}/prds/:id`, async (context) => {
-    try {
-      const layout = await readLayout();
-      return headOrJson(context, await readPrdDetail(filesystem, layout, context.req.param("id")));
-    } catch (error) {
-      if (error instanceof V2WorkspaceRequiredError) throw error;
-      return headOrJson(context, { error: "PRD not found" }, 404);
-    }
-  });
-
-  app.on(["GET", "HEAD"], `${API_PREFIX}/specs/:id`, async (context) => {
-    try {
-      const layout = await readLayout();
-      return headOrJson(context, await readSpecDetail(filesystem, layout, context.req.param("id")));
-    } catch (error) {
-      if (error instanceof V2WorkspaceRequiredError) throw error;
-      return headOrJson(context, { error: "SPEC not found" }, 404);
-    }
-  });
-
-  app.on(["GET", "HEAD"], `${API_PREFIX}/tasks/:id/trace`, async (context) => {
-    try {
-      const layout = await readLayout();
-      const taskId = context.req.param("id");
-      return headOrJson(
-        context,
-        filesystem instanceof SqliteReadModelFileSystem
-          ? buildSqliteTaskTrace(filesystem, layout, taskId)
-          : await buildTaskTrace(filesystem, layout, taskId),
-      );
-    } catch (error) {
-      if (error instanceof V2WorkspaceRequiredError) throw error;
-      return headOrJson(context, { error: "Task trace not found" }, 404);
-    }
+  registerTraceRoutes(app, {
+    filesystem,
+    canonicalFilesystem,
+    isSqliteSnapshot,
+    readLayout,
+    readSnapshot,
+    readAggregate,
+    clearSnapshotCache,
   });
-
   app.onError((error, context) => {
     const status = error instanceof V2WorkspaceRequiredError ? 409 : 500;
     return headOrJson(
@@ -1613,9 +666,7 @@ export function createDashboardApp(
       status,
     );
   });
-
   app.all(`${API_PREFIX}/*`, (context) => headOrJson(context, { error: "Not found" }, 404));
-
   app.on(["GET", "HEAD"], "/", serveStatic({ path: `${uiRoot}/index.html` }));
   app.use("/*", async (context, next) => {
     if (!isSafeUiPath(context.req.path)) {
@@ -1628,45 +679,10 @@ export function createDashboardApp(
   return app;
 }
 
-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,
-      served_at: new Date().toISOString(),
-    },
-  };
-}
-
 const moduleStartedAt = performance.now();
 const sessionToken = defaultSessionToken();
 const runtimeWorkspaceRoot = process.env.ZAIP_WORKSPACE ?? process.cwd();
-
 let defaultApp: Hono | undefined;
-
 /**
  * Compatibility export for direct module consumers. The executable must not
  * construct this filesystem-backed app: `main` creates the SQLite app after
@@ -1676,14 +692,12 @@ export function defaultDashboardApp(): Hono {
   defaultApp ??= createDashboardApp(runtimeWorkspaceRoot, sessionToken);
   return defaultApp;
 }
-
 export const app = new Proxy({} as Hono, {
   get(_target, property) {
     const value = Reflect.get(defaultDashboardApp(), property);
     return typeof value === "function" ? value.bind(defaultDashboardApp()) : value;
   },
 });
-
 async function main(): Promise<void> {
   const port = Number.parseInt(process.env.ZAIP_SERVER_PORT ?? "4317", 10);
   writeStartupPhase(moduleStartedAt, "main_entered");
@@ -1706,7 +720,6 @@ async function main(): Promise<void> {
     );
   });
 }
-
 if (
   process.argv[1]?.endsWith("server.cjs") ||
   process.argv[1]?.endsWith("server.js") ||