@zaip-ai/cli 1.0.4 → 1.0.7

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

@@ -0,0 +1,799 @@
+import { execFile } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { loadWorkspaceLayout, WorkspaceFileSystem, type WorkspaceLayout } from "@zaip-ai/core";
+import { fxRateSchema, PricingRepository, pricingCatalogSchema } from "@zaip-ai/costs";
+import { buildCostMonitorProjection } from "@zaip-ai/dashboard-cost-monitor/server";
+import {
+  buildOperationsProjection,
+  projectExecutionDurations,
+  readPrdDetail,
+  readSpecDetail,
+  readTaskDetail,
+  recalculateOperationsRunSummary,
+} from "@zaip-ai/dashboard-operations/server";
+import { buildTaskTrace } from "@zaip-ai/dashboard-traceability/server";
+import { type Context, Hono } from "hono";
+import { getCookie, setCookie } from "hono/cookie";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import {
+  type AgentAdapterSyncResult,
+  AgentCatalogUpdateError,
+  persistAgentCatalogUpdate,
+  readAgentCatalogSettings,
+} from "./agent-catalog-settings.js";
+import { mergeManifestRuns } from "./manifest-runs.js";
+import { persistProjectSettings, readProjectSettings } from "./project-settings.js";
+import {
+  configuredAgentNames,
+  invocationSummariesForPeriod,
+  queryValues,
+  selectedCurrency,
+} from "./server-summary-helpers.js";
+
+export { manifestRun, mergeManifestRuns } from "./manifest-runs.js";
+
+const API_PREFIX = "/api/v2";
+const HOST = "127.0.0.1";
+const RUNTIME_KIND = "zaip-dashboard-local-runtime";
+const SESSION_COOKIE = "zaip-dashboard-session";
+const DASHBOARD_CONFIG_PATH = ".agents/dashboard/dashboard.config.json";
+const execFileAsync = promisify(execFile);
+const agentPortraitFiles: Record<string, string> = {
+  "agent-orchestrator": "1 - Dave - Product Owner.png",
+  "agent-builder": "2 - Rafa - Tech Lead.png",
+  "agent-task-executor": "3 - Leo - Software Engineer.png",
+  "agent-analyst": "4 - Bia - Product Manager.png",
+  "agent-finalizer": "5 - Gui - Quality Assurance Lead.png",
+  "agent-reviewer": "6 - Nanda - Principal Engineer.png",
+  "agent-integrator": "7 - Dani - Integration Engineer.png",
+  "agent-auditor": "8 - Ana - Quality Auditor.png",
+  "agent-text-summarizer": "9 - Lia - Technical Writer.png",
+  "agent-data-analyst": "10 - Gabi - Data Analyst.png",
+  "agent-refactoring-specialist": "11 - Tati - Refactoring Specialist.png",
+  "agent-frontend": "12 - Doug - Frontend Developer.png",
+  "agent-backend": "13 - Will - Backend Developer.png",
+  "agent-website-developer": "14 - Jonny - Website Developer.png",
+  "agent-designer": "15 - Manu - Product Designer.png",
+  "agent-cloud-engineer": "16 - Dan - Cloud Engineer.png",
+  "agent-security-auditor": "17 - Luis - Security Auditor.png",
+  "agent-marketing-analyst": "18 - Lucia - Marketing Analyst.png",
+};
+
+interface ActiveWorkItem {
+  kind: string;
+  id: string;
+  status: string | null;
+}
+
+/** Pure lifecycle helper retained for callers; it never reads a runtime projection. */
+export function openWorkIds(items: readonly ActiveWorkItem[]): string[] {
+  const kinds = new Set(["prd", "spec", "change", "task", "execution"]);
+  const statuses = new Set(["active", "executing", "verifying", "running", "paused"]);
+  return items
+    .filter(
+      (item) =>
+        kinds.has(item.kind) &&
+        (statuses.has(item.status ?? "") || (item.kind === "task" && item.status === "planned")),
+    )
+    .map((item) => item.id)
+    .sort();
+}
+
+interface DashboardAppOptions {
+  syncAgentAdapters?: () => Promise<AgentAdapterSyncResult>;
+}
+
+class V2WorkspaceRequiredError extends Error {
+  override readonly name = "V2WorkspaceRequiredError";
+}
+
+function isAllowedOrigin(origin: string): boolean {
+  try {
+    const parsed = new URL(origin);
+    return (
+      parsed.protocol === "http:" && (parsed.hostname === HOST || parsed.hostname === "localhost")
+    );
+  } catch {
+    return false;
+  }
+}
+
+function isSafeUiPath(pathname: string): boolean {
+  try {
+    const decoded = decodeURIComponent(pathname).replaceAll("\\", "/");
+    return !decoded.includes("\0") && !decoded.split("/").some((segment) => segment === "..");
+  } catch {
+    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 dashboardIdentity(
+  filesystem: WorkspaceFileSystem,
+  workspaceRoot: string,
+): Promise<{ title: string; repository_name: string }> {
+  let title = process.env.ZAIP_DASHBOARD_TITLE?.trim() || "Dashboard Zaip AIOS";
+  let repositorySetting = "auto";
+  try {
+    if (await filesystem.exists(DASHBOARD_CONFIG_PATH)) {
+      const config = JSON.parse(await filesystem.readText(DASHBOARD_CONFIG_PATH)) as {
+        github_repository?: unknown;
+        title?: unknown;
+      };
+      if (typeof config.title === "string" && config.title.trim()) title = config.title.trim();
+      if (typeof config.github_repository === "string") {
+        repositorySetting = config.github_repository.trim();
+      }
+    }
+  } catch {
+    // A configuração visual nunca deve impedir a inicialização do dashboard.
+  }
+  if (repositorySetting.toLowerCase() !== "auto") {
+    return {
+      title,
+      repository_name: githubRepositoryFromRemote(repositorySetting) ?? "",
+    };
+  }
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["-C", workspaceRoot, "remote", "get-url", "origin"],
+      { encoding: "utf8", windowsHide: true },
+    );
+    return { title, repository_name: githubRepositoryFromRemote(stdout) ?? "" };
+  } catch {
+    // Falha de detecção mantém o badge ausente sem impedir o dashboard.
+  }
+  return { title, repository_name: "" };
+}
+
+export function githubRepositoryFromRemote(remote: string): string | null {
+  const trimmed = remote.trim();
+  const match =
+    trimmed.match(/github\.com(?::|\/)([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i) ??
+    trimmed.match(/^([^/:\s]+)\/([^/\s]+?)(?:\.git)?$/);
+  return match ? `${match[1]}/${match[2]}` : null;
+}
+
+export function dashboardWorkspaceKey(workspaceRoot: string): string {
+  return createHash("sha256").update(resolve(workspaceRoot)).digest("hex").slice(0, 16);
+}
+
+export interface ReconciliationItem {
+  id: string;
+  reason: string | null;
+}
+
+export interface ReconciliationResult {
+  reconciled_ids: string[];
+  blocked: ReconciliationItem[];
+  not_reconciled: ReconciliationItem[];
+}
+
+async function reconcileOpenWork(
+  filesystem: WorkspaceFileSystem,
+  workspaceRoot: string,
+): Promise<ReconciliationResult> {
+  if (!(await filesystem.exists(".agents/runtime/bin/zaip.mjs"))) {
+    return { reconciled_ids: [], blocked: [], not_reconciled: [] };
+  }
+  const cliPath = resolve(workspaceRoot, ".agents", "runtime", "bin", "zaip.mjs");
+  const { stdout } = await execFileAsync(
+    process.execPath,
+    [cliPath, "run", "reconcile", "--open", "--json"],
+    { cwd: workspaceRoot, windowsHide: true, timeout: 120_000, maxBuffer: 10 * 1_024 * 1_024 },
+  );
+  return reconciliationResult(JSON.parse(stdout) as unknown);
+}
+
+export function reconciliationResult(value: unknown): ReconciliationResult {
+  const reconciled = new Set<string>();
+  const blocked = new Map<string, string | null>();
+  const notReconciled = new Map<string, string | null>();
+  const remember = (target: Map<string, string | null>, id: unknown, reason: unknown): void => {
+    if (typeof id !== "string") return;
+    target.set(id, typeof reason === "string" && reason.trim() ? reason : null);
+  };
+  const records =
+    typeof value === "object" && value !== null ? (value as Record<string, unknown>) : {};
+  const reconciliations = Array.isArray(records.reconciliations) ? records.reconciliations : [];
+  for (const candidate of reconciliations) {
+    if (typeof candidate !== "object" || candidate === null) continue;
+    const item = candidate as Record<string, unknown>;
+    const reason = item.error;
+    const entities = ["tasks", "changes", "executions", "specs", "prds"].flatMap((key) =>
+      Array.isArray(item[key]) ? item[key] : [],
+    );
+    for (const entity of entities) {
+      if (typeof entity !== "object" || entity === null) continue;
+      const record = entity as Record<string, unknown>;
+      if (
+        item.status === "closed" &&
+        record.status === "completed" &&
+        typeof record.id === "string"
+      ) {
+        reconciled.add(record.id);
+      } else if (record.status === "blocked") {
+        remember(blocked, record.id, record.status_reason ?? reason);
+      } else if (item.status === "deferred") {
+        remember(notReconciled, record.id, reason);
+      }
+    }
+  }
+  const orphanedExecutions = Array.isArray(records.orphaned_executions)
+    ? records.orphaned_executions
+    : [];
+  orphanedExecutions.forEach((id) => {
+    remember(blocked, id, "Execution orphaned after the reconciliation grace period.");
+  });
+  const errors = Array.isArray(records.reconciliation_errors) ? records.reconciliation_errors : [];
+  errors.forEach((candidate) => {
+    if (typeof candidate !== "object" || candidate === null) return;
+    const item = candidate as Record<string, unknown>;
+    remember(notReconciled, item.run_id, item.error);
+  });
+  const unresolved = Array.isArray(records.unresolved_running_run_ids)
+    ? records.unresolved_running_run_ids
+    : [];
+  unresolved.forEach((id) => {
+    remember(notReconciled, id, "Invocation is still running.");
+  });
+  const entries = (items: Map<string, string | null>): ReconciliationItem[] =>
+    [...items.entries()]
+      .map(([id, reason]) => ({ id, reason }))
+      .sort((left, right) => left.id.localeCompare(right.id));
+  return {
+    reconciled_ids: [...reconciled].sort(),
+    blocked: entries(blocked),
+    not_reconciled: entries(notReconciled),
+  };
+}
+
+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,
+): Response {
+  if (context.req.method === "HEAD") return context.body(null, status);
+  return context.json(payload, status);
+}
+
+export function createDashboardApp(
+  workspaceRoot = process.env.ZAIP_WORKSPACE ?? process.cwd(),
+  sessionToken = defaultSessionToken(),
+  uiRoot = resolve(process.env.ZAIP_UI_ROOT ?? "./dist"),
+  options: DashboardAppOptions = {},
+): Hono {
+  const app = new Hono();
+  const filesystem = new WorkspaceFileSystem(workspaceRoot);
+  const workspaceKey = dashboardWorkspaceKey(workspaceRoot);
+  const syncAgentAdapters = options.syncAgentAdapters ?? (() => runAgentAdapterSync(workspaceRoot));
+  let catalogWriteTail = Promise.resolve();
+  let snapshotInFlight: Promise<Awaited<ReturnType<typeof dashboardSnapshot>>> | null = null;
+  let cachedSnapshot: Awaited<ReturnType<typeof dashboardSnapshot>> | null = null;
+  let cachedSnapshotAt = 0;
+  let cachedSnapshotKey: string | null = null;
+  const readSnapshot = (context: Context) => {
+    const key = `${selectedCurrency(context)}:${context.req.query("from") ?? ""}:${context.req.query("to") ?? ""}`;
+    if (
+      cachedSnapshot !== null &&
+      cachedSnapshotKey === key &&
+      Date.now() - cachedSnapshotAt < 2_000
+    )
+      return Promise.resolve(cachedSnapshot);
+    if (snapshotInFlight !== null) return snapshotInFlight;
+    snapshotInFlight = dashboardSnapshot(filesystem, workspaceRoot, context)
+      .then((snapshot) => {
+        cachedSnapshot = snapshot;
+        cachedSnapshotKey = key;
+        cachedSnapshotAt = Date.now();
+        return snapshot;
+      })
+      .finally(() => {
+        snapshotInFlight = null;
+      });
+    return snapshotInFlight;
+  };
+
+  app.use("*", async (context, next) => {
+    context.header("Cache-Control", "no-store");
+    context.header("X-Content-Type-Options", "nosniff");
+    context.header("Referrer-Policy", "no-referrer");
+    context.header(
+      "Content-Security-Policy",
+      "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; object-src 'none'; frame-ancestors 'none'",
+    );
+    if (shouldBootstrapBrowserSession(context)) {
+      setCookie(context, SESSION_COOKIE, sessionToken, {
+        httpOnly: true,
+        path: "/",
+        sameSite: "Strict",
+      });
+    }
+    return next();
+  });
+
+  app.use(`${API_PREFIX}/*`, async (context, next) => {
+    const settingsWrite =
+      context.req.method === "PUT" &&
+      (context.req.path === `${API_PREFIX}/pricing` ||
+        context.req.path === `${API_PREFIX}/fx-rate` ||
+        context.req.path === `${API_PREFIX}/agent-catalog` ||
+        context.req.path === `${API_PREFIX}/project-settings`);
+    const reconcileWrite =
+      context.req.method === "POST" && context.req.path === `${API_PREFIX}/reconcile-open-work`;
+    if (
+      context.req.method !== "GET" &&
+      context.req.method !== "HEAD" &&
+      !settingsWrite &&
+      !reconcileWrite
+    ) {
+      context.header(
+        "Allow",
+        context.req.path === `${API_PREFIX}/pricing` ||
+          context.req.path === `${API_PREFIX}/fx-rate` ||
+          context.req.path === `${API_PREFIX}/agent-catalog` ||
+          context.req.path === `${API_PREFIX}/project-settings`
+          ? "GET, HEAD, PUT"
+          : context.req.path === `${API_PREFIX}/reconcile-open-work`
+            ? "POST"
+            : "GET, HEAD",
+      );
+      return context.json({ error: "Dashboard API is read-only" }, 405);
+    }
+    if (context.req.path === `${API_PREFIX}/health`) return next();
+
+    const origin = context.req.header("origin");
+    if (origin !== undefined && !isAllowedOrigin(origin)) {
+      return context.json({ error: "Origin rejected" }, 403);
+    }
+    const headerSession = context.req.header("x-zaip-session");
+    const cookieSession = getCookie(context, SESSION_COOKIE);
+    const portraitToken =
+      context.req.method === "GET" &&
+      context.req.path.startsWith(`${API_PREFIX}/agent-catalog-assets/`)
+        ? context.req.query("token")
+        : undefined;
+    if (
+      headerSession !== sessionToken &&
+      cookieSession !== sessionToken &&
+      portraitToken !== sessionToken
+    ) {
+      return context.json({ error: "Invalid local session" }, 401);
+    }
+    return next();
+  });
+
+  app.on(["GET", "HEAD"], `${API_PREFIX}/health`, async (context) => {
+    try {
+      const layout = await requireV2Layout(filesystem);
+      return headOrJson(context, {
+        kind: RUNTIME_KIND,
+        workspaceKey,
+        service: "zaip-aios-dashboard",
+        status: "ok",
+        api_version: 2,
+        workspace_layout: layout.version,
+        read_only: true,
+      });
+    } catch (error) {
+      return headOrJson(
+        context,
+        {
+          kind: RUNTIME_KIND,
+          workspaceKey,
+          service: "zaip-aios-dashboard",
+          status: "unavailable",
+          api_version: 2,
+          read_only: true,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        503,
+      );
+    }
+  });
+
+  app.on(["GET", "HEAD"], `${API_PREFIX}/operations`, async (context) => {
+    try {
+      const layout = await requireV2Layout(filesystem);
+      const { from, to } = projectionPeriodFilter(context);
+      const projection = await buildCanonicalOperationsProjection(
+        filesystem,
+        layout,
+        { from, to },
+        context.req.query("scope") === "overview",
+      );
+      return headOrJson(context, projection);
+    } catch (error) {
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      return headOrJson(
+        context,
+        { error: error instanceof Error ? error.message : String(error) },
+        400,
+      );
+    }
+  });
+
+  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 requireV2Layout(filesystem);
+      const reconciledIds = await reconcileOpenWork(filesystem, workspaceRoot);
+      return context.json({
+        ...(await dashboardSnapshot(filesystem, workspaceRoot, context)),
+        reconciliation: reconciledIds,
+      });
+    } catch (error) {
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      return context.json({ error: error instanceof Error ? error.message : String(error) }, 400);
+    }
+  });
+
+  app.on(["GET", "HEAD"], `${API_PREFIX}/cost-monitor`, async (context) => {
+    try {
+      const layout = await requireV2Layout(filesystem);
+      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,
+      );
+    }
+  });
+
+  app.on(["GET", "HEAD"], `${API_PREFIX}/pricing`, async (context) =>
+    headOrJson(
+      context,
+      pricingCatalogSchema.parse(
+        JSON.parse(await filesystem.readText(".agents/config/pricing/models.json")),
+      ),
+    ),
+  );
+
+  app.put(`${API_PREFIX}/pricing`, async (context) => {
+    const catalog = pricingCatalogSchema.parse({
+      ...(await context.req.json()),
+      updated_at: new Date().toISOString(),
+    });
+    await filesystem.writeTextAtomic(
+      ".agents/config/pricing/models.json",
+      `${JSON.stringify(catalog, null, 2)}\n`,
+    );
+    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);
+    return context.json(rate);
+  });
+
+  app.on(["GET", "HEAD"], `${API_PREFIX}/agent-catalog`, async (context) => {
+    try {
+      return headOrJson(context, await readAgentCatalogSettings(filesystem));
+    } catch (error) {
+      return headOrJson(
+        context,
+        { error: error instanceof Error ? error.message : String(error) },
+        400,
+      );
+    }
+  });
+
+  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);
+    try {
+      return context.body(
+        await readFile(resolve(workspaceRoot, ".agents/config/src", portrait)),
+        200,
+        { "cache-control": "no-store", "content-type": "image/png" },
+      );
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return context.json({ error: "Agent portrait not found" }, 404);
+      }
+      return context.json({ error: "Agent portrait could not be read" }, 500);
+    }
+  });
+
+  app.put(`${API_PREFIX}/agent-catalog`, async (context) => {
+    const update = async () => {
+      try {
+        return context.json(
+          await persistAgentCatalogUpdate(filesystem, await context.req.json(), syncAgentAdapters),
+        );
+      } catch (error) {
+        if (error instanceof AgentCatalogUpdateError) {
+          return context.json({ error: error.message }, error.status);
+        }
+        return context.json({ error: "Agent catalog update failed" }, 500);
+      }
+    };
+    const result = catalogWriteTail.then(update, update);
+    catalogWriteTail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  });
+
+  app.on(["GET", "HEAD"], `${API_PREFIX}/project-settings`, async (context) => {
+    try {
+      return headOrJson(context, await readProjectSettings(filesystem));
+    } catch (error) {
+      return headOrJson(
+        context,
+        { error: error instanceof Error ? error.message : String(error) },
+        400,
+      );
+    }
+  });
+
+  app.put(`${API_PREFIX}/project-settings`, async (context) => {
+    try {
+      return context.json(await persistProjectSettings(filesystem, await context.req.json()));
+    } catch (error) {
+      return context.json(
+        { error: error instanceof Error ? error.message : "Project settings update failed" },
+        400,
+      );
+    }
+  });
+
+  app.on(["GET", "HEAD"], `${API_PREFIX}/tasks/:id`, async (context) => {
+    try {
+      const layout = await requireV2Layout(filesystem);
+      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 requireV2Layout(filesystem);
+      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 requireV2Layout(filesystem);
+      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 requireV2Layout(filesystem);
+      return headOrJson(context, await buildTaskTrace(filesystem, layout, context.req.param("id")));
+    } catch (error) {
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      return headOrJson(context, { error: "Task trace not found" }, 404);
+    }
+  });
+
+  app.onError((error, context) => {
+    const status = error instanceof V2WorkspaceRequiredError ? 409 : 500;
+    return headOrJson(
+      context,
+      { error: status === 409 ? error.message : "Dashboard projection failed" },
+      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)) {
+      return context.json({ error: "Invalid dashboard asset path" }, 400);
+    }
+    return next();
+  });
+  app.use("/*", serveStatic({ root: uiRoot }));
+  app.on(["GET", "HEAD"], "/*", serveStatic({ path: `${uiRoot}/index.html` }));
+  return app;
+}
+
+async function runAgentAdapterSync(workspaceRoot: string): Promise<AgentAdapterSyncResult> {
+  const cliPath = resolve(workspaceRoot, ".agents", "runtime", "bin", "zaip.mjs");
+  const commandOptions = {
+    cwd: workspaceRoot,
+    encoding: "utf8" as const,
+    windowsHide: true,
+    timeout: 120_000,
+    maxBuffer: 10 * 1_024 * 1_024,
+  };
+  await execFileAsync(process.execPath, [cliPath, "adapters", "build", "--json"], commandOptions);
+  const { stdout } = await execFileAsync(
+    process.execPath,
+    [cliPath, "adapters", "check", "--json"],
+    commandOptions,
+  );
+  const result = JSON.parse(stdout) as { valid?: unknown; drifted?: unknown };
+  return {
+    valid: result.valid === true,
+    drifted: Array.isArray(result.drifted)
+      ? result.drifted.filter((value): value is string => typeof value === "string")
+      : [],
+  };
+}
+
+/** Date-only filters in the dashboard represent complete calendar days. */
+export function projectionPeriodFilter(context: Pick<Context, "req">): {
+  from: string | null;
+  to: string | null;
+} {
+  const from = context.req.query("from") ?? null;
+  const to = context.req.query("to") ?? null;
+  return {
+    from: dateOnlyBoundary(from, "start"),
+    to: dateOnlyBoundary(to, "end"),
+  };
+}
+
+function dateOnlyBoundary(value: string | null, boundary: "start" | "end"): string | null {
+  if (value === null || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return value;
+  return boundary === "start" ? `${value}T00:00:00.000Z` : `${value}T23:59:59.999Z`;
+}
+
+async function dashboardSnapshot(
+  filesystem: WorkspaceFileSystem,
+  workspaceRoot: string,
+  context: Context,
+) {
+  const layout = await requireV2Layout(filesystem);
+  const { from, to } = projectionPeriodFilter(context);
+  const operations = await buildCanonicalOperationsProjection(filesystem, layout, { from, to });
+  const costs = await buildCurrentCostProjection(filesystem, operations, selectedCurrency(context));
+  return {
+    operations,
+    costs,
+    dashboard: await dashboardIdentity(filesystem, workspaceRoot),
+    projection: {
+      source_latest_at: operations.summary.source_latest_at,
+      served_at: new Date().toISOString(),
+    },
+  };
+}
+
+/**
+ * Assemble Operations from the tracked lifecycle records and, when a bounded
+ * period was requested, the signed InvocationSummary manifests for that same
+ * period.  Runtime projections are deliberately not read or cached here.
+ */
+async function buildCanonicalOperationsProjection(
+  filesystem: WorkspaceFileSystem,
+  layout: WorkspaceLayout,
+  filter: { from: string | null; to: string | null },
+  overviewOnly = false,
+) {
+  const operations = await buildOperationsProjection(filesystem, layout, filter, { overviewOnly });
+  if (overviewOnly || filter.from === null || filter.to === null) return operations;
+  const summaries = await invocationSummariesForPeriod(filesystem, {
+    from: filter.from,
+    to: filter.to,
+  });
+  return summaries.length === 0
+    ? operations
+    : recalculateOperationsRunSummary({
+        ...operations,
+        runs: projectExecutionDurations(mergeManifestRuns(operations.runs, summaries)),
+      });
+}
+
+async function buildCurrentCostProjection(
+  filesystem: WorkspaceFileSystem,
+  operations: Awaited<ReturnType<typeof buildCanonicalOperationsProjection>>,
+  currency: "BRL" | "USD",
+) {
+  const pricing = new PricingRepository(filesystem);
+  const [catalog, fxRate] = await Promise.all([
+    pricing.readCatalog(),
+    currency === "BRL" ? pricing.readLatestFxRate() : Promise.resolve(null),
+  ]);
+  const agentNames = await configuredAgentNames(filesystem);
+  return buildCostMonitorProjection(operations, { catalog, fxRate, currency }, agentNames);
+}
+
+async function buildManifestFirstCostProjection(
+  filesystem: WorkspaceFileSystem,
+  operations: Awaited<ReturnType<typeof buildCanonicalOperationsProjection>>,
+  context: Context,
+) {
+  const from = context.req.query("from") ?? null;
+  const to = context.req.query("to") ?? null;
+  if (from === null || to === null) {
+    return buildCurrentCostProjection(filesystem, operations, selectedCurrency(context));
+  }
+  const filters = {
+    providers: queryValues(context, "provider"),
+    models: queryValues(context, "model"),
+    zaip_agents: queryValues(context, "agent"),
+    phases: queryValues(context, "phase"),
+    statuses: queryValues(context, "status"),
+  };
+  const summaries = await invocationSummariesForPeriod(filesystem, { from, to, filters });
+  if (summaries.length === 0)
+    return buildCurrentCostProjection(filesystem, operations, selectedCurrency(context));
+  const runs = projectExecutionDurations(mergeManifestRuns(operations.runs, summaries));
+  return buildCurrentCostProjection(filesystem, { ...operations, runs }, selectedCurrency(context));
+}
+
+const sessionToken = defaultSessionToken();
+export const app = createDashboardApp(process.env.ZAIP_WORKSPACE ?? process.cwd(), sessionToken);
+
+const isMain = process.argv[1]
+  ? resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+  : false;
+
+if (isMain) {
+  const port = Number.parseInt(process.env.ZAIP_SERVER_PORT ?? "4317", 10);
+  serve({ fetch: app.fetch, hostname: HOST, port }, ({ port: boundPort }) => {
+    process.stdout.write(
+      `ZAIP-AIOS dashboard API: http://${HOST}:${boundPort}${API_PREFIX}/health\n`,
+    );
+  });
+}