@zaip-ai/cli 2.6.0 → 3.1.0

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

@@ -7,9 +7,26 @@ import {
   parseAgentCatalog,
   parseProjectConfig,
   parseYaml,
+  resolveAutonomy,
   serializeYaml,
   type WorkspaceFileSystem,
 } from "@zaip-ai/core";
+import {
+  installationProfile,
+  type PROJECT_INSTALLATION_TOTAL,
+  type ProjectStatusSummary,
+  readDocumentAvailability,
+  summarizeProjectInstallation,
+  summarizeProjectStatus,
+} from "./project-installation-summary.js";
+
+export {
+  PROJECT_INSTALLATION_AREA_REQUIREMENTS,
+  PROJECT_INSTALLATION_STACK_REQUIREMENTS,
+  PROJECT_INSTALLATION_TOTAL,
+  summarizeProjectInstallation,
+  summarizeProjectStatus,
+} from "./project-installation-summary.js";
 
 const AGENT_CATALOG_PATH = ".agents/config/agents/catalog.yaml";
 const CODEX_CONFIG_PATH = ".codex/config.toml";
@@ -17,30 +34,7 @@ const FRAMEWORK_LOCK_PATH = ".agents/config/framework.lock.yaml";
 const DASHBOARD_STACK_DEPENDENCIES_PATH = ".agents/dashboard/stack-dependencies.json";
 const exec = promisify(execFile);
 export const SOFTWARE_ARCHITECTURE_PATH = ".agents/architecture/software-architecture.md";
-export const PROJECT_INSTALLATION_STACK_REQUIREMENTS = [
-  "Node.js",
-  "TypeScript",
-  "Vite",
-  "Astro",
-  "Redis",
-  "BullMQ",
-  "Hono",
-  "React",
-  "Git",
-  "Terraform",
-] as const;
-export const PROJECT_INSTALLATION_AREA_REQUIREMENTS = [
-  "software_architecture",
-  "design_system",
-  "brandbook",
-  "marketing_strategy",
-  "sales_playbook",
-  "growth_strategy",
-] as const;
-export const PROJECT_INSTALLATION_TOTAL =
-  PROJECT_INSTALLATION_STACK_REQUIREMENTS.length + PROJECT_INSTALLATION_AREA_REQUIREMENTS.length;
-
-export type ProjectOverview = {
+export type ProjectOverview = ProjectStatusSummary & {
   framework_version: string | null;
   installation: {
     completed: number;
@@ -60,6 +54,7 @@ export type ProjectOverview = {
     source: string | null;
     verification: "exact" | "constraint" | "unavailable";
     installation: "runtime" | "installed" | "missing" | "bundled";
+    probe?: "verified" | "missing" | "unknown";
   }>;
   areas: Array<{
     id:
@@ -71,7 +66,7 @@ export type ProjectOverview = {
       | "sales_playbook";
     label: string;
     artifact: string;
-    available: boolean;
+    available: boolean | null;
   }>;
 };
 
@@ -107,19 +102,27 @@ export async function readProjectOverview(
       countDirectMarkdownFiles(filesystem, ".agents/rules"),
       countCodexHookEvents(filesystem),
     ]);
-  const [stack_components, areas] = await Promise.all([
+  const [project, stack_components, areas] = await Promise.all([
+    readProjectSettings(filesystem),
     readVerifiedStackComponents(filesystem),
     Promise.all(
       projectOverviewArtifacts.map(async (area) => ({
         ...area,
-        available: await hasNonEmptyFile(filesystem, area.artifact),
+        available: await readDocumentAvailability(filesystem, area.artifact),
       })),
     ),
   ]);
   const installation = summarizeProjectInstallation(stack_components, areas);
+  const status = summarizeProjectStatus(
+    installationProfile(project),
+    stack_components,
+    areas,
+    "healthy",
+  );
   return {
     framework_version: frameworkVersion,
     installation,
+    ...status,
     metrics: [
       { id: "agents", label: "Agentes", value: catalog.agents.length },
       { id: "squads", label: "Squads", value: catalog.squads.length },
@@ -132,36 +135,6 @@ export async function readProjectOverview(
   };
 }
 
-export function summarizeProjectInstallation(
-  stackComponents: ProjectOverview["stack_components"],
-  areas: ProjectOverview["areas"],
-): ProjectOverview["installation"] {
-  const completed =
-    PROJECT_INSTALLATION_STACK_REQUIREMENTS.filter((name) =>
-      stackComponents.some(
-        (component) => component.name === name && isInstalledLocalRequirement(component),
-      ),
-    ).length +
-    PROJECT_INSTALLATION_AREA_REQUIREMENTS.filter((id) =>
-      areas.some((area) => area.id === id && area.available),
-    ).length;
-  return {
-    completed,
-    total: PROJECT_INSTALLATION_TOTAL,
-    percent: (completed / PROJECT_INSTALLATION_TOTAL) * 100,
-    state: completed === PROJECT_INSTALLATION_TOTAL ? "complete" : "incomplete",
-  };
-}
-
-function isInstalledLocalRequirement(
-  component: ProjectOverview["stack_components"][number],
-): boolean {
-  return (
-    component.verification === "exact" &&
-    (component.installation === "runtime" || component.installation === "installed")
-  );
-}
-
 async function readFrameworkVersion(filesystem: WorkspaceFileSystem): Promise<string | null> {
   try {
     const lock = recordValue(parseYaml(await filesystem.readText(FRAMEWORK_LOCK_PATH)));
@@ -246,13 +219,19 @@ async function readVerifiedStackComponents(
   ];
 }
 
-type InstalledPackage = { name: string; version: string | null; source: string | null };
+type InstalledPackage = {
+  name: string;
+  version: string | null;
+  source: string | null;
+  probe: "verified" | "missing" | "unknown";
+};
 type DashboardStackDependencies = { node: string | null; packages: Map<string, string> };
 
 async function readInstalledPackageVersion(
   filesystem: WorkspaceFileSystem,
   name: string,
 ): Promise<InstalledPackage> {
+  let uncertain = false;
   const roots = ["node_modules"];
   if (name === "hono") roots.push(".agents/dashboard/packages/local-runtime/node_modules");
   if (name === "react") roots.push(".agents/dashboard/apps/frontend/node_modules");
@@ -267,15 +246,18 @@ async function readInstalledPackageVersion(
         version === null ||
         !/^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(version) ||
         entrypoint === null
-      )
+      ) {
+        uncertain = true;
         continue;
+      }
       await filesystem.readText(`${root}/${name}/${entrypoint}`);
-      return { name, version, source };
-    } catch {
-      // A pnpm workspace can install dependencies in the owning package only.
+      return { name, version, source, probe: "verified" };
+    } catch (error) {
+      // Absence is known only for ENOENT; invalid JSON and denied reads are unknown.
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") uncertain = true;
     }
   }
-  return { name, version: null, source: null };
+  return { name, version: null, source: null, probe: uncertain ? "unknown" : "missing" };
 }
 
 async function readDashboardStackDependencies(
@@ -374,6 +356,7 @@ async function executableComponent(
       source: executable === command ? `Comando do workspace: ${command}` : local,
       verification: "exact",
       installation: executable === command ? "runtime" : "installed",
+      probe: "verified",
     };
   } catch {
     return {
@@ -383,6 +366,7 @@ async function executableComponent(
       source: null,
       verification: "unavailable",
       installation: "missing",
+      probe: "unknown",
     };
   }
 }
@@ -399,6 +383,7 @@ function runtimeComponent(
     source: `Runtime do Dashboard: ${process.execPath}`,
     verification: "exact",
     installation: "runtime",
+    probe: "verified",
   };
 }
 
@@ -418,6 +403,7 @@ function packageComponent(
       source: installed.get(packageName)?.source ?? null,
       verification: "exact",
       installation: "installed",
+      probe: "verified",
     };
   if (bundled)
     return {
@@ -430,6 +416,7 @@ function packageComponent(
           : ".agents/dashboard/apps/frontend/dist",
       verification: "unavailable",
       installation: "bundled",
+      probe: "unknown",
     };
   return {
     name,
@@ -438,6 +425,7 @@ function packageComponent(
     source: null,
     verification: "unavailable",
     installation: "missing",
+    probe: installed.get(packageName)?.probe ?? "missing",
   };
 }
 
@@ -535,6 +523,7 @@ const architectureLabels: Record<string, string> = {
 };
 
 export function renderSoftwareArchitecture(config: ProjectConfig): string {
+  const autonomy = resolveAutonomy(config.autonomy);
   const overrides = recordValue(config.stack.overrides);
   const components = recordValue(overrides.components);
   const languages = recordValue(overrides.languages);
@@ -556,14 +545,14 @@ export function renderSoftwareArchitecture(config: ProjectConfig): string {
     "",
   ]);
   const executionDetails =
-    config.execution?.runtime === "autonomous"
+    config.execution && config.execution.runtime !== "manual"
       ? [
-          "- **Runtime:** autonomous",
+          `- **Runtime:** ${config.execution.runtime}`,
           `- **Provider:** ${markdownCell(config.execution.autonomous.provider)}`,
           `- **Modelo-base:** ${markdownCell(config.execution.autonomous.model)}`,
           `- **Paralelismo máximo:** ${config.execution.autonomous.max_parallelism}`,
           `- **Lease configurado:** ${config.execution.autonomous.lease_ms} ms`,
-          `- **Limite total de invocações:** ${config.execution.autonomous.max_total_invocations ?? "Não definido"}`,
+          `- **Limite total de invocações:** ${config.autonomy ? "Por Task; sem teto agregado de SPEC/PRD" : (config.execution.autonomous.max_total_invocations ?? "Não definido")}`,
         ]
       : [`- **Runtime:** ${config.execution?.runtime ?? "manual (padrão implícito)"}`];
   const assuranceDetails =
@@ -602,6 +591,18 @@ export function renderSoftwareArchitecture(config: ProjectConfig): string {
     "## Execução",
     "",
     ...executionDetails,
+    ...(config.autonomy
+      ? [
+          "",
+          "### Autonomia",
+          "",
+          `- **Perfil:** ${autonomy.label}`,
+          `- **Execuções por Task:** ${autonomy.attempts ?? "Ilimitadas"}`,
+          `- **Replanejamentos por Task:** ${autonomy.replans ?? "Ilimitados"}`,
+          "- Sem abandono por tempo. Tasks iniciadas preservam o perfil e os contadores.",
+          "- Subagentes podem ter modelo/esforço diferentes do principal, com aviso explícito.",
+        ]
+      : []),
     "",
     "## Assurance",
     "",

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

@@ -0,0 +1,91 @@
+import { Hono } from "hono";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { registerBrowserLeaseRoute } from "./server-browser-lease.js";
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+async function openLease(app: Hono) {
+  const response = await app.request("/api/v2/browser-lease");
+  if (response.body === null) throw new Error("Missing SSE body");
+  const reader = response.body.getReader();
+  const chunks: string[] = [];
+  const drained = (async () => {
+    for (;;) {
+      const chunk = await reader.read();
+      if (chunk.done) return;
+      chunks.push(new TextDecoder().decode(chunk.value));
+    }
+  })();
+  await vi.advanceTimersByTimeAsync(0);
+  expect(response.headers.get("content-type")).toContain("text/event-stream");
+  expect(chunks[0]).toContain("event: lease\ndata: active");
+  return {
+    chunks,
+    close: async () => {
+      await reader.cancel();
+      await drained;
+    },
+  };
+}
+
+describe("browser lease lifecycle", () => {
+  it("keeps the real SSE body active past a five-minute idle timeout", async () => {
+    vi.useFakeTimers();
+    const exit = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+    const app = new Hono();
+    registerBrowserLeaseRoute(app, "/api/v2", true);
+    const lease = await openLease(app);
+    try {
+      for (let interval = 0; interval < 31; interval++) {
+        const before = lease.chunks.length;
+        await vi.advanceTimersByTimeAsync(10_000);
+        expect(lease.chunks.length).toBeGreaterThan(before);
+        expect(lease.chunks.at(-1)).toContain(": keep-alive\n\n");
+        expect(exit).not.toHaveBeenCalled();
+      }
+    } finally {
+      await lease.close();
+    }
+    expect(vi.getTimerCount()).toBe(1);
+    await vi.advanceTimersByTimeAsync(11_999);
+    expect(exit).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+  });
+
+  it("expires only after the last client closes and a replacement cancels expiry", async () => {
+    vi.useFakeTimers();
+    const exit = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+    const app = new Hono();
+    registerBrowserLeaseRoute(app, "/api/v2", true);
+    const first = await openLease(app);
+    const second = await openLease(app);
+    await first.close();
+    await vi.advanceTimersByTimeAsync(13_000);
+    expect(exit).not.toHaveBeenCalled();
+    await second.close();
+    await vi.advanceTimersByTimeAsync(11_000);
+    const replacement = await openLease(app);
+    await vi.advanceTimersByTimeAsync(13_000);
+    expect(exit).not.toHaveBeenCalled();
+    await replacement.close();
+    await vi.advanceTimersByTimeAsync(12_000);
+    expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("does not terminate an unmanaged server or retain a heartbeat after cancellation", async () => {
+    vi.useFakeTimers();
+    const exit = vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+    const app = new Hono();
+    registerBrowserLeaseRoute(app, "/api/v2");
+    const lease = await openLease(app);
+    await lease.close();
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(exit).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

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

@@ -13,7 +13,7 @@ export function registerBrowserLeaseRoute(
     browserLeaseDeadline.unref();
   }
   const releaseBrowserLease = (lease: object) => {
-    browserLeases.delete(lease);
+    if (!browserLeases.delete(lease)) return;
     if (!launcherOwned || browserLeases.size !== 0) return;
     if (browserLeaseDeadline !== undefined) clearTimeout(browserLeaseDeadline);
     browserLeaseDeadline = setTimeout(() => process.exit(0), 12_000);
@@ -25,9 +25,29 @@ export function registerBrowserLeaseRoute(
     browserLeaseDeadline = undefined;
     browserLeases.add(lease);
     return streamSSE(context, async (stream) => {
-      stream.onAbort(() => releaseBrowserLease(lease));
-      await stream.writeSSE({ event: "lease", data: "active" });
-      await new Promise(() => {});
+      let heartbeat: NodeJS.Timeout | undefined;
+      let wake: (() => void) | undefined;
+      stream.onAbort(() => {
+        if (heartbeat !== undefined) clearTimeout(heartbeat);
+        wake?.();
+        releaseBrowserLease(lease);
+      });
+      try {
+        await stream.writeSSE({ event: "lease", data: "active" });
+        while (!stream.aborted) {
+          await new Promise<void>((resolve) => {
+            wake = resolve;
+            heartbeat = setTimeout(resolve, 10_000);
+            heartbeat.unref();
+          });
+          // SSE comments keep idle HTTP clients alive without changing the
+          // browser's lease event contract or accumulating overlapping writes.
+          if (!stream.aborted) await stream.write(": keep-alive\n\n");
+        }
+      } finally {
+        if (heartbeat !== undefined) clearTimeout(heartbeat);
+        releaseBrowserLease(lease);
+      }
     });
   });
 }

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

@@ -0,0 +1,17 @@
+import { Hono } from "hono";
+import { describe, expect, it } from "vitest";
+
+describe("Dashboard HTTP query security", () => {
+  const app = new Hono().get("/", (context) => context.json(context.req.query()));
+
+  it("does not interpret a question mark inside a URL fragment as a query", async () => {
+    const response = await app.request("http://localhost/#?admin=true");
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({});
+  });
+
+  it("preserves real query parameters but excludes fragment parameters", async () => {
+    const response = await app.request("http://localhost/?currency=BRL#?admin=true");
+    expect(await response.json()).toEqual({ currency: "BRL" });
+  });
+});

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

@@ -52,14 +52,14 @@ export function registerOperationsRoutes(app: Hono, dependencies: DashboardRoute
         scope !== "quick" &&
         scope !== "detail" &&
         scope !== "board" &&
+        scope !== "traceability" &&
         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"));
+      if (scope === "board" || scope === "traceability") {
         const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
         const limit = Math.min(
           50,
@@ -80,6 +80,25 @@ export function registerOperationsRoutes(app: Hono, dependencies: DashboardRoute
             };
           },
         );
+        // Traceability is an identity index, not an executable Kanban column.
+        // Drafts remain discoverable without changing their canonical state.
+        if (scope === "traceability") {
+          const tasks = board.projection.tasks.toSorted(
+            (a, b) => b.created_at.localeCompare(a.created_at) || b.id.localeCompare(a.id),
+          );
+          return headOrJson(
+            context,
+            {
+              tasks: tasks.slice(offset, offset + limit),
+              total: tasks.length,
+              offset,
+              limit,
+            },
+            200,
+            true,
+          );
+        }
+        const stage = boardStage(context.req.query("stage"));
         const filters = boardFilters(context);
         const pageKey = JSON.stringify({ from, to, stage, offset, limit, ...filters });
         const page = await readAggregate(`operations:board-page:${pageKey}`, async () =>

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

@@ -1,6 +1,21 @@
 import { EventEmitter } from "node:events";
-import { describe, expect, it } from "vitest";
-import { attachRefreshWorkerCleanup } from "./server-snapshot-refresh.js";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { describe, expect, it, vi } from "vitest";
+import {
+  attachRefreshWorkerCleanup,
+  refreshSqliteSnapshotInWorker,
+  validateSnapshotWorkerReceipt,
+} from "./server-snapshot-refresh.js";
+import { SqliteReadModelFileSystem } from "./sqlite-read-model-filesystem.js";
+import {
+  readModelSchemaVersion,
+  requiredIndexes,
+  requiredPersistedTables,
+  requiredViews,
+} from "./sqlite-read-model-schema.js";
 
 describe("snapshot refresh shutdown", () => {
   it("terminates an active refresh worker on runtime shutdown and removes its listener on completion", () => {
@@ -17,3 +32,80 @@ describe("snapshot refresh shutdown", () => {
     expect(calls).toEqual(["SIGTERM"]);
   });
 });
+
+describe("snapshot worker process boundary", () => {
+  it.each([
+    "valid",
+    "empty",
+    "wrong-path",
+    "nonzero",
+    "oversized",
+  ] as const)("reopens only after valid receipt and successful process close: %s", async (mode) => {
+    const root = await mkdtemp(join(tmpdir(), "zaip-refresh-receipt-"));
+    const db = new DatabaseSync(":memory:");
+    const filesystem = new SqliteReadModelFileSystem(root, db);
+    const refresh = vi.spyOn(filesystem, "refresh").mockImplementation(() => undefined);
+    try {
+      const scripts = join(root, ".agents/dashboard/packages/local-runtime/scripts");
+      await mkdir(scripts, { recursive: true });
+      // This fixture tests native transport/failure handling, not DB integrity.
+      // The shipped rebuild script performs the real schema/integrity validation.
+      await writeFile(
+        join(scripts, "rebuild-sqlite-read-model.mjs"),
+        `
+          const receipt = {storage_mode:'sqlite_read_model',
+            path: ${JSON.stringify(mode)} === 'wrong-path' ? 'other.sqlite' : process.env.ZAIP_SQLITE_DB_PATH,
+            schema: ${JSON.stringify({ schemaVersion: readModelSchemaVersion, tableCount: requiredPersistedTables.length, viewCount: requiredViews.length, indexCount: requiredIndexes.length })}};
+          if (${JSON.stringify(mode)} !== 'empty') {
+            if (${JSON.stringify(mode)} === 'oversized') process.stdout.write(' '.repeat(64001));
+            const output = JSON.stringify(receipt);
+            process.stdout.write(output.slice(0, 20));
+            setTimeout(() => process.stdout.write(output.slice(20)), 5);
+          }
+          process.exitCode = ${mode === "nonzero" ? 1 : 0};
+        `,
+      );
+      if (mode === "valid") {
+        await expect(refreshSqliteSnapshotInWorker(root, filesystem)).resolves.toBeUndefined();
+        expect(refresh).toHaveBeenCalledTimes(1);
+      } else {
+        await expect(refreshSqliteSnapshotInWorker(root, filesystem)).rejects.toThrow();
+        expect(refresh).not.toHaveBeenCalled();
+      }
+    } finally {
+      refresh.mockRestore();
+      db.close();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("validated worker receipt", () => {
+  const destination = "snapshot.sqlite";
+  const receipt = {
+    storage_mode: "sqlite_read_model",
+    path: destination,
+    schema: {
+      schemaVersion: readModelSchemaVersion,
+      tableCount: requiredPersistedTables.length,
+      viewCount: requiredViews.length,
+      indexCount: requiredIndexes.length,
+    },
+  };
+  it("accepts the exact schema-validated destination without scanning it on the HTTP thread", () => {
+    // The path need not exist in this process: only the worker does the heavy check.
+    expect(() => validateSnapshotWorkerReceipt(JSON.stringify(receipt), destination)).not.toThrow();
+  });
+  it.each([
+    "",
+    "null",
+    "{}",
+    JSON.stringify({ ...receipt, path: "other.sqlite" }),
+    JSON.stringify({ ...receipt, schema: { ...receipt.schema, schemaVersion: "old" } }),
+    JSON.stringify({ ...receipt, schema: { ...receipt.schema, indexCount: 0 } }),
+    JSON.stringify({ ...receipt, schema: { ...receipt.schema, tableCount: 0 } }),
+    JSON.stringify({ ...receipt, schema: { ...receipt.schema, viewCount: null } }),
+  ])("rejects absent, stale or unrelated validation: %s", (value) => {
+    expect(() => validateSnapshotWorkerReceipt(value, destination)).toThrow();
+  });
+});