@zaip-ai/cli 1.0.8 → 1.3.1

package/templates/.agents/dashboard/packages/local-runtime/src/project-settings.test.ts

@@ -2,9 +2,9 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
+  PROJECT_CONFIG_PATH,
   parseProjectConfig,
   parseYaml,
-  PROJECT_CONFIG_PATH,
   serializeYaml,
   WorkspaceFileSystem,
 } from "@zaip-ai/core";
@@ -123,6 +123,10 @@ async function fixtureProject() {
 }
 
 describe("project settings persistence", () => {
+  it("uses the canonical lowercase architecture artifact path", () => {
+    expect(SOFTWARE_ARCHITECTURE_PATH).toBe(".agents/architecture/software-architecture.md");
+  });
+
   it("reads, validates and atomically persists the complete project config", async () => {
     const { configPath, filesystem } = await fixtureProject();
     const current = await readProjectSettings(filesystem);
@@ -385,7 +389,7 @@ describe("project settings persistence", () => {
         }),
         expect.objectContaining({
           id: "brandbook",
-          artifact: ".agents/brand/brandbook.md",
+          artifact: ".agents/branding/brandbook.md",
           available: false,
         }),
       ]),

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

@@ -1,8 +1,8 @@
 import {
   PROJECT_CONFIG_PATH,
   type ProjectConfig,
-  parseProjectConfig,
   parseAgentCatalog,
+  parseProjectConfig,
   parseYaml,
   serializeYaml,
   type WorkspaceFileSystem,
@@ -12,7 +12,7 @@ const AGENT_CATALOG_PATH = ".agents/config/agents/catalog.yaml";
 const CODEX_CONFIG_PATH = ".codex/config.toml";
 const FRAMEWORK_LOCK_PATH = ".agents/config/framework.lock.yaml";
 const SQLITE_READ_MODEL_PATH = ".local/dashboard-sqlite/read-model.sqlite";
-export const SOFTWARE_ARCHITECTURE_PATH = "docs/SOFTWARE-ARCHITECTURE.md";
+export const SOFTWARE_ARCHITECTURE_PATH = ".agents/architecture/software-architecture.md";
 
 export type ProjectOverview = {
   framework_version: string | null;
@@ -48,7 +48,7 @@ const projectOverviewArtifacts: Array<Omit<ProjectOverview["areas"][number], "av
     artifact: SOFTWARE_ARCHITECTURE_PATH,
   },
   { id: "design_system", label: "Design system", artifact: ".agents/design/DESIGN.md" },
-  { id: "brandbook", label: "Brandbook", artifact: ".agents/brand/brandbook.md" },
+  { id: "brandbook", label: "Brandbook", artifact: ".agents/branding/brandbook.md" },
   {
     id: "marketing_strategy",
     label: "Estratégia de Marketing",

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

@@ -17,14 +17,13 @@ describe("boardPage", () => {
       prds: [prd],
       specs: [spec],
     } as unknown as Parameters<typeof boardPage>[0];
-    const page = boardPage(
-      projection,
-      "executing",
-      0,
-      10,
-      [],
-      { query: "", status: "", risk: "", origin: "", kind: "" },
-    );
+    const page = boardPage(projection, "executing", 0, 10, [], {
+      query: "",
+      status: "",
+      risk: "",
+      origin: "",
+      kind: "",
+    });
 
     expect(page.tasks[0]).toBe(task);
     expect(page.prds[0]).toBe(prd);
@@ -42,17 +41,91 @@ describe("boardPage", () => {
     const projection = { changes: [], tasks: [task], prds: [], specs: [] } as unknown as Parameters<
       typeof boardPage
     >[0];
-    const page = boardPage(
-      projection,
-      "executing",
-      0,
-      10,
-      [],
-      { query: "", status: "", risk: "", origin: "", kind: "" },
-    );
+    const page = boardPage(projection, "executing", 0, 10, [], {
+      query: "",
+      status: "",
+      risk: "",
+      origin: "",
+      kind: "",
+    });
     expect(page.tasks[0]).toBe(task);
   });
 
+  it("separates standalone Tasks from Tasks linked to a SPEC", () => {
+    const standalone = {
+      id: "TASK-STANDALONE",
+      title: "Standalone",
+      status: "executing",
+      spec_id: null,
+      updated_at: "2026-08-08T10:00:00Z",
+    };
+    const linked = {
+      id: "TASK-LINKED",
+      title: "Linked",
+      status: "executing",
+      spec_id: "SPEC-1",
+      updated_at: "2026-08-08T10:00:00Z",
+    };
+    const projection = {
+      changes: [],
+      tasks: [standalone, linked],
+      prds: [],
+      specs: [],
+    } as unknown as Parameters<typeof boardPage>[0];
+
+    const standalonePage = boardPage(projection, "executing", 0, 10, [], {
+      query: "",
+      status: "",
+      risk: "",
+      origin: "",
+      kind: "standalone-task",
+    });
+    const linkedPage = boardPage(projection, "executing", 0, 10, [], {
+      query: "",
+      status: "",
+      risk: "",
+      origin: "",
+      kind: "task",
+    });
+
+    expect(standalonePage.tasks).toEqual([standalone]);
+    expect(linkedPage.tasks).toEqual([linked]);
+    expect(standalonePage.totals_by_kind).toMatchObject({ task: 1, "standalone-task": 1 });
+  });
+
+  it("returns every Task for an Overview status dialog", () => {
+    const standalone = {
+      id: "TASK-STANDALONE",
+      title: "Standalone",
+      status: "executing",
+      spec_id: null,
+      updated_at: "2026-08-08T10:00:00Z",
+    };
+    const linked = {
+      id: "TASK-LINKED",
+      title: "Linked",
+      status: "executing",
+      spec_id: "SPEC-1",
+      updated_at: "2026-08-08T10:00:00Z",
+    };
+    const projection = {
+      changes: [],
+      tasks: [standalone, linked],
+      prds: [],
+      specs: [],
+    } as unknown as Parameters<typeof boardPage>[0];
+
+    const page = boardPage(projection, "executing", 0, 10, [], {
+      query: "",
+      status: "",
+      risk: "",
+      origin: "",
+      kind: "all-tasks",
+    });
+
+    expect(page.total).toBe(2);
+    expect(page.tasks.map((task) => task.id)).toEqual([linked.id, standalone.id]);
+  });
 });
 
 function macro(id: string, kind: "prd" | "spec", taskIds: string[]) {

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

@@ -7,7 +7,13 @@ import type { Context } from "hono";
 import type { buildCanonicalOperationsProjection } from "./server-projections.js";
 
 type BoardStage = WorkStage;
-export type BoardClassification = "lite" | "standard" | "critical" | "empty" | "structured" | "rework";
+export type BoardClassification =
+  | "lite"
+  | "standard"
+  | "critical"
+  | "empty"
+  | "structured"
+  | "rework";
 
 interface BoardFilters {
   query: string;
@@ -56,15 +62,20 @@ export function boardPage(
   const sourceByChange = new Map(
     projection.changes.map((change) => [change.id, change.source.type] as const),
   );
+  const taskOrigin = (task: (typeof projection.tasks)[number]) => {
+    const origin = (task as typeof task & { origin?: unknown }).origin;
+    return (
+      sourceByChange.get(task.change_id) ??
+      (typeof origin === "string" ? origin : task.spec_id === null ? "task" : "spec")
+    );
+  };
   const matchesQuery = (values: readonly (string | null | undefined)[]) =>
     filters.query === "" ||
     values.some((value) => value?.toLocaleLowerCase().includes(filters.query));
   const taskMatches = (task: (typeof projection.tasks)[number]) =>
     (filters.status === "" || taskWorkStage(task) === filters.status) &&
     (filters.risk === "" || task.risk === filters.risk) &&
-    (filters.origin === "" ||
-      (sourceByChange.get(task.change_id) ?? (task.spec_id === null ? "task" : "spec")) ===
-        filters.origin) &&
+    (filters.origin === "" || taskOrigin(task) === filters.origin) &&
     matchesQuery([
       task.id,
       task.title,
@@ -110,7 +121,13 @@ export function boardPage(
   const stageItems =
     filters.kind === ""
       ? allStageItems
-      : allStageItems.filter((item) => item.kind === filters.kind);
+      : filters.kind === "all-tasks"
+        ? allStageItems.filter((item) => item.kind === "task")
+        : filters.kind === "standalone-task"
+          ? allStageItems.filter((item) => item.kind === "task" && item.row.spec_id === null)
+          : filters.kind === "task"
+            ? allStageItems.filter((item) => item.kind === "task" && item.row.spec_id !== null)
+            : allStageItems.filter((item) => item.kind === filters.kind);
   const page = stageItems.slice(offset, offset + limit);
   const ids = new Set(page.map((item) => item.row.id));
   return {
@@ -119,19 +136,17 @@ export function boardPage(
     total: stageItems.length,
     totals_by_kind: {
       all: allStageItems.length,
-      task: allStageItems.filter((item) => item.kind === "task").length,
+      task: allStageItems.filter((item) => item.kind === "task" && item.row.spec_id !== null)
+        .length,
+      "standalone-task": allStageItems.filter(
+        (item) => item.kind === "task" && item.row.spec_id === null,
+      ).length,
       prd: allStageItems.filter((item) => item.kind === "prd").length,
       spec: allStageItems.filter((item) => item.kind === "spec").length,
     },
-    prds: page
-      .filter((item) => item.kind === "prd")
-      .map((item) => item.row),
-    specs: page
-      .filter((item) => item.kind === "spec")
-      .map((item) => item.row),
-    tasks: page
-      .filter((item) => item.kind === "task")
-      .map((item) => item.row),
+    prds: page.filter((item) => item.kind === "prd").map((item) => item.row),
+    specs: page.filter((item) => item.kind === "spec").map((item) => item.row),
+    tasks: page.filter((item) => item.kind === "task").map((item) => item.row),
     changes: projection.changes.filter((change) =>
       change.task_ids.some((taskId) => ids.has(taskId)),
     ),
@@ -173,7 +188,9 @@ export function classificationPage(
     tasks: kind === "task" ? page : [],
     changes:
       kind === "task"
-        ? projection.changes.filter((change) => page.some((task) => change.task_ids.includes(task.id)))
+        ? projection.changes.filter((change) =>
+            page.some((task) => change.task_ids.includes(task.id)),
+          )
         : [],
   };
 }

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

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { classificationPage } from "./server-board.js";
+
+describe("dashboard classification pages", () => {
+  it.each([
+    ["task", "lite", "TASK-LITE"],
+    ["task", "standard", "TASK-STANDARD"],
+    ["task", "critical", "TASK-CRITICAL"],
+    ["spec", "empty", "SPEC-EMPTY"],
+    ["spec", "structured", "SPEC-STRUCTURED"],
+    ["spec", "rework", "SPEC-REWORK"],
+    ["prd", "empty", "PRD-EMPTY"],
+    ["prd", "structured", "PRD-STRUCTURED"],
+    ["prd", "rework", "PRD-REWORK"],
+  ] as const)("returns only the canonical %s %s classification page", (kind, classification, expectedId) => {
+    const projection = {
+      tasks: [
+        { id: "TASK-LITE", risk: "lite", created_at: "2026-08-21T00:00:00.000Z", updated_at: null },
+        {
+          id: "TASK-STANDARD",
+          risk: "standard",
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+        {
+          id: "TASK-CRITICAL",
+          risk: "critical",
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+      ],
+      specs: [
+        {
+          id: "SPEC-EMPTY",
+          task_count: 0,
+          rework_run_count: 0,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+        {
+          id: "SPEC-STRUCTURED",
+          task_count: 1,
+          rework_run_count: 0,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+        {
+          id: "SPEC-REWORK",
+          task_count: 1,
+          rework_run_count: 1,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+      ],
+      prds: [
+        {
+          id: "PRD-EMPTY",
+          task_count: 0,
+          rework_run_count: 0,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+        {
+          id: "PRD-STRUCTURED",
+          task_count: 1,
+          rework_run_count: 0,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+        {
+          id: "PRD-REWORK",
+          task_count: 1,
+          rework_run_count: 1,
+          created_at: "2026-08-21T00:00:00.000Z",
+          updated_at: null,
+        },
+      ],
+      changes: [],
+    } as unknown as Parameters<typeof classificationPage>[0];
+    const page = classificationPage(projection, kind, classification, 0, 1);
+    const items = kind === "task" ? page.tasks : kind === "spec" ? page.specs : page.prds;
+    expect(page).toMatchObject({ offset: 0, total: 1 });
+    expect(items.map((item) => item.id)).toEqual([expectedId]);
+    expect(kind === "task" ? page.specs : page.tasks).toEqual([]);
+    expect(kind === "prd" ? page.specs : page.prds).toEqual([]);
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/server-period-macro-metric.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { boardPage } from "./server-board.js";
+import { periodMacroMetric } from "./server-period-macro-metric.js";
+
+const noBoardFilters = { query: "", status: "", risk: "", origin: "", kind: "prd" };
+
+describe("periodMacroMetric", () => {
+  it("keeps a draft PRD counter and its status-dialog board page in Definition", () => {
+    const prd = {
+      id: "PRD-DRAFT",
+      kind: "prd",
+      title: "Draft PRD",
+      status: "draft",
+      lifecycle_status: "draft",
+      work_status: "draft",
+      task_ids: [],
+      parent_id: null,
+      updated_at: "2026-08-29T16:00:00Z",
+    };
+    const projection = { changes: [], tasks: [], prds: [prd], specs: [] } as unknown as Parameters<
+      typeof boardPage
+    >[0];
+
+    expect(periodMacroMetric([prd], "prd").status_counts).toEqual({ definition: 1 });
+    expect(boardPage(projection, "definition", 0, 10, [], noBoardFilters)).toMatchObject({
+      total: 1,
+      prds: [{ id: "PRD-DRAFT" }],
+    });
+    expect(boardPage(projection, "planning", 0, 10, [], noBoardFilters).total).toBe(0);
+  });
+
+  it.each([
+    ["spec", "draft", "planning"],
+    ["prd", "ready", "ready"],
+    ["spec", "planned", "ready"],
+    ["prd", "active", "executing"],
+    ["spec", "delivered", "completed"],
+    ["prd", "cancelled", "cancelled"],
+  ] as const)("maps %s %s to %s", (kind, status, expectedStage) => {
+    expect(periodMacroMetric([{ id: `${kind}-${status}`, status }], kind).status_counts).toEqual({
+      [expectedStage]: 1,
+    });
+  });
+});

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

@@ -0,0 +1,125 @@
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+
+type AllTimeTopTaskFact = {
+  task_id: string;
+  total_duration_ms: number | null;
+  total_tokens: number | null;
+  total_cost_usd: number | null;
+  total_cost_brl: number | null;
+  total_run_count: number;
+};
+
+export function projectAllTimeTopTasks(
+  tasks: readonly AllTimeTopTaskFact[],
+): NonNullable<NonNullable<OperationsProjection["summary"]["overview_metrics"]>["top_tasks"]> {
+  return tasks.map((task) => ({
+    task_id: task.task_id,
+    duration_ms: task.total_duration_ms,
+    total_tokens: task.total_tokens,
+    total_cost_usd: task.total_cost_usd,
+    cost_brl: task.total_cost_brl,
+    run_count: task.total_run_count,
+  }));
+}
+
+type OverviewMacroMetric = NonNullable<
+  NonNullable<OperationsProjection["summary"]["overview_metrics"]>["macro_metrics"]
+>["specs"];
+
+const nullableMetric = (value: unknown): number | null =>
+  typeof value === "number" && Number.isFinite(value) ? value : null;
+
+type MacroKind = "spec" | "prd";
+
+/**
+ * Keeps narrowed-period Overview counters aligned with the stage used by the
+ * board endpoint that supplies the status dialog.
+ */
+export const periodMacroStage = (kind: MacroKind, value: unknown) => {
+  const status = String(value);
+  if (status === "draft") return kind === "prd" ? "definition" : "planning";
+  if (status === "ready" || status === "planned") return "ready";
+  if (status === "active") return "executing";
+  if (status === "delivered") return "completed";
+  return ["executing", "verifying", "completed", "blocked", "failed", "cancelled"].includes(status)
+    ? status
+    : "planning";
+};
+
+/** Projects narrowed-period SPEC/PRD rows without falling back to Task totals. */
+export function periodMacroMetric(
+  rows: readonly Record<string, unknown>[],
+  kind: MacroKind,
+): OverviewMacroMetric {
+  const knownSum = (field: string): number | null => {
+    const values = rows
+      .map((row) => row[field])
+      .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+    return values.length === 0 ? null : values.reduce((total, value) => total + value, 0);
+  };
+  const number = (row: Record<string, unknown>, field: string) => nullableMetric(row[field]) ?? 0;
+  const totalDuration = knownSum("total_duration");
+  const totalTokens = knownSum("total_tokens");
+  const totalCostUsd = knownSum("total_cost_usd");
+  const totalCostBrl = knownSum("total_cost_brl");
+  const statusCounts: Record<string, number> = {};
+  const classificationCounts: Record<string, number> = { empty: 0, structured: 0, rework: 0 };
+  for (const row of rows) {
+    const status = periodMacroStage(kind, row.status);
+    statusCounts[status] = (statusCounts[status] ?? 0) + 1;
+    const classification =
+      number(row, "rework_run_count") > 0
+        ? "rework"
+        : number(row, "task_count") > 0
+          ? "structured"
+          : "empty";
+    classificationCounts[classification] = (classificationCounts[classification] ?? 0) + 1;
+  }
+  const topEntities = rows
+    .map((row) => ({
+      entity_id: String(row.id),
+      title: String(row.title ?? row.id),
+      duration_ms: nullableMetric(row.total_duration),
+      total_tokens: nullableMetric(row.total_tokens),
+      total_cost_usd: nullableMetric(row.total_cost_usd),
+      cost_brl: nullableMetric(row.total_cost_brl),
+      run_count: number(row, "invocation_count"),
+    }))
+    .toSorted(
+      (left, right) =>
+        (right.duration_ms ?? -1) - (left.duration_ms ?? -1) ||
+        left.entity_id.localeCompare(right.entity_id),
+    )
+    .slice(0, 5)
+    .map((entity) => ({
+      ...entity,
+      duration_share:
+        totalDuration === null || totalDuration === 0 || entity.duration_ms === null
+          ? 0
+          : entity.duration_ms / totalDuration,
+    }));
+  const latest =
+    rows
+      .flatMap((row) => (typeof row.occurred_at === "string" ? [row.occurred_at] : []))
+      .toSorted()
+      .at(-1) ?? null;
+  return {
+    status_counts: statusCounts,
+    classification_counts: classificationCounts,
+    entity_count: rows.length,
+    total_run_count: rows.reduce((total, row) => total + number(row, "invocation_count"), 0),
+    total_duration_ms: totalDuration,
+    total_tokens: totalTokens,
+    total_cost_usd: totalCostUsd,
+    total_cost_brl: totalCostBrl,
+    average_duration_ms:
+      totalDuration === null || rows.length === 0 ? null : totalDuration / rows.length,
+    average_tokens: totalTokens === null || rows.length === 0 ? null : totalTokens / rows.length,
+    average_cost_usd:
+      totalCostUsd === null || rows.length === 0 ? null : totalCostUsd / rows.length,
+    average_cost_brl:
+      totalCostBrl === null || rows.length === 0 ? null : totalCostBrl / rows.length,
+    latest_created_at: latest,
+    top_entities: topEntities,
+  };
+}

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

@@ -0,0 +1,66 @@
+import { resolve } from "node:path";
+import { WorkspaceFileSystem, type WorkspaceLayout } from "@zaip-ai/core";
+import { describe, expect, it, vi } from "vitest";
+import { createDashboardApp, reconciliationNeedsRefresh } from "./server.js";
+
+const workspaceRoot = resolve(import.meta.dirname, "../../../../..");
+const v2Layout = { version: 3 } as WorkspaceLayout;
+
+describe("reconciliation snapshot refresh", () => {
+  it("refreshes only when reconciliation changed canonical work", () => {
+    expect(
+      reconciliationNeedsRefresh({ reconciled_ids: [], blocked: [], not_reconciled: [] }),
+    ).toBe(false);
+    expect(
+      reconciliationNeedsRefresh({
+        reconciled_ids: [],
+        blocked: [{ id: "TASK-BLOCKED", reason: "Finalization evidence is missing." }],
+        not_reconciled: [],
+      }),
+    ).toBe(true);
+    expect(
+      reconciliationNeedsRefresh({
+        reconciled_ids: ["TASK-CHANGED"],
+        blocked: [],
+        not_reconciled: [],
+      }),
+    ).toBe(true);
+  });
+
+  it("serves health while a changed reconciliation refreshes in a worker", async () => {
+    let rejectRefresh: ((error: Error) => void) | undefined;
+    const refresh = vi.fn(
+      () =>
+        new Promise<void>((_resolveRefresh, reject) => {
+          rejectRefresh = reject;
+        }),
+    );
+    const app = createDashboardApp(workspaceRoot, "test-session", undefined, {
+      snapshotReadOnly: true,
+      canonicalFilesystem: new WorkspaceFileSystem(workspaceRoot),
+      reconcileOpenWork: async () => ({
+        reconciled_ids: ["TASK-CHANGED"],
+        blocked: [],
+        not_reconciled: [],
+      }),
+      refreshReadModel: refresh,
+      layout: v2Layout,
+    });
+    const reconciliation = app.request("/api/v2/reconcile-open-work", {
+      method: "POST",
+      headers: { "x-zaip-session": "test-session" },
+    });
+    await vi.waitFor(() => expect(refresh).toHaveBeenCalledOnce());
+    await expect(
+      app.request("/api/v2/health", { headers: { "x-zaip-session": "test-session" } }),
+    ).resolves.toMatchObject({
+      status: 200,
+    });
+    rejectRefresh?.(new Error("simulated worker refresh failure"));
+    const response = await reconciliation;
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toMatchObject({
+      error: "simulated worker refresh failure",
+    });
+  });
+});

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

@@ -0,0 +1,61 @@
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { createDashboardApp } from "./server.js";
+import { isAllowedDashboardAuthority } from "./server-request-authority.js";
+
+const workspaceRoot = resolve(import.meta.dirname, "../../../../..");
+
+describe("dashboard loopback authority", () => {
+  it.each([
+    ["http://127.0.0.1:4317/", undefined],
+    ["http://localhost/", "localhost"],
+    ["http://localhost:4317/", "localhost:4317"],
+    ["http://127.0.0.1:4317/", "127.0.0.1:4317"],
+  ])("accepts a loopback authority %s / %s", (url, host) => {
+    expect(isAllowedDashboardAuthority(url, host)).toBe(true);
+  });
+
+  it.each([
+    ["http://untrusted.example:4317/", undefined],
+    ["http://localhost.evil.invalid/", undefined],
+    ["http://localhost/", "untrusted.example:4317"],
+    ["http://localhost/", "localhost:99999"],
+    ["http://localhost/", "localhost/evil"],
+    ["http://localhost/", "localhost@evil.invalid"],
+    ["http://localhost/", "localhost,evil.invalid"],
+    ["http://user:synthetic@localhost/", undefined],
+    ["https://localhost/", undefined],
+    ["not-a-url", undefined],
+  ])("rejects untrusted or malformed authority %s / %s", (url, host) => {
+    expect(isAllowedDashboardAuthority(url, host)).toBe(false);
+  });
+
+  it("rejects arbitrary hosts before bootstrap and API even with a valid session", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    for (const path of ["/", "/index.html", "/api/v2/fx-rate", "/api/v2/health"]) {
+      const response = await app.request(`http://untrusted.example:4317${path}`, {
+        headers: { "sec-fetch-site": "same-origin", "x-zaip-session": "test-session" },
+      });
+      expect(response.status).toBe(403);
+      expect(response.headers.get("set-cookie")).toBeNull();
+    }
+    const spoofed = await app.request("http://localhost/", {
+      headers: { host: "untrusted.example", "sec-fetch-site": "none" },
+    });
+    expect(spoofed.status).toBe(403);
+    expect(spoofed.headers.get("set-cookie")).toBeNull();
+  });
+
+  it("preserves normal local bootstrap and cross-site denial", async () => {
+    const app = createDashboardApp(workspaceRoot, "test-session");
+    const local = await app.request("http://127.0.0.1:4317/", {
+      headers: { "sec-fetch-site": "none" },
+    });
+    expect(local.status).not.toBe(403);
+    expect(local.headers.get("set-cookie")).toContain("HttpOnly");
+    const crossSite = await app.request("http://127.0.0.1:4317/", {
+      headers: { "sec-fetch-site": "cross-site", origin: "http://untrusted.example" },
+    });
+    expect(crossSite.headers.get("set-cookie")).toBeNull();
+  });
+});

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

@@ -0,0 +1,18 @@
+/** The dashboard is a loopback service, not a reverse-proxy/public host endpoint. */
+export function isAllowedDashboardAuthority(requestUrl: string, hostHeader?: string): boolean {
+  const allowedHost = /^(?:localhost|127\.0\.0\.1)(?::[0-9]{1,5})?$/i;
+  try {
+    const url = new URL(requestUrl);
+    if (url.protocol !== "http:" || url.username || url.password || !allowedHost.test(url.host)) {
+      return false;
+    }
+    if (hostHeader !== undefined) {
+      if (!allowedHost.test(hostHeader)) return false;
+      // Parse as well to reject invalid port numbers, not merely malformed syntax.
+      new URL(`http://${hostHeader}`);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}