@zaip-ai/cli 4.5.0 → 4.7.0

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

@@ -0,0 +1,76 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { WorkspaceFileSystem } from "@zaip-ai/core";
+import type { Hono } from "hono";
+import {
+  type AgentAdapterSyncResult,
+  AgentCatalogUpdateError,
+  persistAgentCatalogUpdate,
+  readAgentCatalogSettings,
+} from "./agent-catalog-settings.js";
+import { agentPortraitFiles } from "./server-agent-assets.js";
+import { API_PREFIX, headOrJson } from "./server-http-contracts.js";
+
+export function registerAgentCatalogRoutes(
+  app: Hono,
+  options: {
+    filesystem: WorkspaceFileSystem;
+    workspaceRoot: string;
+    syncAgentAdapters: () => Promise<AgentAdapterSyncResult>;
+    clearSnapshotCache: () => void;
+  },
+): void {
+  const { filesystem, workspaceRoot, syncAgentAdapters, clearSnapshotCache } = options;
+  let catalogWriteTail = Promise.resolve();
+  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 {
+        const persisted = await persistAgentCatalogUpdate(
+          filesystem,
+          await context.req.json(),
+          syncAgentAdapters,
+        );
+        clearSnapshotCache();
+        return context.json(persisted);
+      } 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;
+  });
+}

package/templates/.agents/dashboard/packages/local-runtime/src/server-dual-reads-manifest-summaries-without-losing.test.ts

@@ -207,6 +207,11 @@ describe("dashboard backend", () => {
         { id: "RUN-FAILED", reason: "Could not read Run." },
         { id: "TASK-DEFERRED", reason: "Canonical gates are incomplete." },
       ],
+      outcomes: [
+        { id: "CHG-COMPLETED", status: "completed", reason: null },
+        { id: "TASK-BLOCKED", status: "blocked", reason: "Missing finalizer." },
+        { id: "TASK-COMPLETED", status: "completed", reason: null },
+      ],
     });
   });
   it("requires the local session for projections", async () => {

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

@@ -0,0 +1,118 @@
+import { mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import type { WorkspaceLayout } from "@zaip-ai/core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createDashboardApp } from "./server.js";
+import { ReconciliationCommandTimeoutError } from "./server-workspace.js";
+
+const roots: string[] = [];
+async function fixture() {
+  const base = resolve(import.meta.dirname, "../../../../../../.tmp/dashboard-server-diagnostics");
+  await mkdir(base, { recursive: true });
+  const root = await mkdtemp(join(base, "fixture-"));
+  roots.push(root);
+  return root;
+}
+async function events(root: string) {
+  const directory = join(root, ".local/dashboard-logs");
+  const content = (
+    await Promise.all(
+      (await readdir(directory)).map((name) => readFile(join(directory, name), "utf8")),
+    )
+  ).join("");
+  return content
+    .trim()
+    .split("\n")
+    .map((line) => JSON.parse(line));
+}
+const layout = { version: 3 } as WorkspaceLayout;
+const headers = { "x-zaip-session": "test-session" };
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+describe("manual reconciliation observable boundaries", () => {
+  it("keeps later unrelated refreshes separate from the completed reconciliation job", async () => {
+    const root = await fixture();
+    const app = createDashboardApp(root, "test-session", undefined, {
+      layout,
+      snapshotReadOnly: true,
+      reconcileOpenWork: async () => ({
+        reconciled_ids: ["RUN-X"],
+        blocked: [],
+        not_reconciled: [],
+      }),
+      refreshReadModel: async () => undefined,
+    });
+    await app.request("/api/v2/reconcile-open-work", { method: "POST", headers });
+    await vi.waitFor(async () =>
+      expect(
+        (await events(root)).some((item) => item.event === "projection_refresh_completed"),
+      ).toBe(true),
+    );
+    await app.request("/api/v2/refresh-projection", { method: "POST", headers });
+    const completed = (await events(root)).filter(
+      (item) => item.event === "projection_refresh_completed",
+    );
+    expect(completed[0].job_id).toEqual(expect.any(String));
+    expect(completed.at(-1).job_id).toBe(null);
+    expect(completed.at(-1).job_ids).toEqual([]);
+  });
+  it("logs request, job completion and asynchronous refresh failure without false promotion", async () => {
+    const root = await fixture();
+    const app = createDashboardApp(root, "test-session", undefined, {
+      layout,
+      snapshotReadOnly: true,
+      reconcileOpenWork: async () => ({
+        reconciled_ids: ["RUN-X"],
+        blocked: [],
+        not_reconciled: [],
+      }),
+      refreshReadModel: async () => {
+        throw new Error("simulated refresh failure");
+      },
+    });
+    const response = await app.request("/api/v2/reconcile-open-work", { method: "POST", headers });
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as { reconciliation: { diagnostics: { job_id: string } } };
+    expect(body.reconciliation.diagnostics).toMatchObject({
+      job_id: expect.any(String),
+      completed_at: expect.any(String),
+      latest_token_collected_at: null,
+      projection_updated_at: null,
+    });
+    await vi.waitFor(async () => {
+      const records = await events(root);
+      expect(records.map((item) => item.event)).toContain("projection_refresh_failed");
+    });
+    const records = await events(root);
+    const job = body.reconciliation.diagnostics.job_id;
+    expect(records.find((item) => item.event === "projection_refresh_failed").job_id).toBe(job);
+    expect(records.some((item) => item.event === "projection_refresh_completed")).toBe(false);
+    expect(records.some((item) => item.event === "reconciliation_button_received")).toBe(true);
+  });
+  it("logs timeout/partial failure and attempts snapshot refresh with a correlated finite response", async () => {
+    const root = await fixture();
+    const refresh = vi.fn(async () => undefined);
+    const app = createDashboardApp(root, "test-session", undefined, {
+      layout,
+      snapshotReadOnly: true,
+      reconcileOpenWork: async () => {
+        throw new ReconciliationCommandTimeoutError();
+      },
+      refreshReadModel: refresh,
+    });
+    const response = await app.request("/api/v2/reconcile-open-work", { method: "POST", headers });
+    expect(response.status).toBe(408);
+    expect(await response.json()).toMatchObject({
+      reconciliation_may_be_partial: true,
+      projection_refresh_started: true,
+      request_id: expect.any(String),
+      job_id: expect.any(String),
+      log_directory: ".local/dashboard-logs",
+    });
+    await vi.waitFor(() => expect(refresh).toHaveBeenCalledOnce());
+    expect((await events(root)).map((item) => item.event)).toEqual(
+      expect.arrayContaining(["reconciliation_failed", "reconciliation_response_error"]),
+    );
+  });
+});

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

@@ -1,3 +1,5 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import type { WorkspaceFileSystem } from "@zaip-ai/core";
 import { describe, expect, it, vi } from "vitest";
 import { reconcileOpenWork, reconciliationResult } from "./server-workspace.js";
@@ -14,7 +16,7 @@ describe("manual reconciliation report", () => {
           },
         ],
       }),
-    ).toEqual({ reconciled_ids: ["PRD-DONE", "SPEC-DONE"], blocked: [], not_reconciled: [] });
+    ).toMatchObject({ reconciled_ids: ["PRD-DONE", "SPEC-DONE"], blocked: [], not_reconciled: [] });
   });
 
   it("reports the canonical owners of an orphan with their persisted blocking reasons", () => {
@@ -35,7 +37,7 @@ describe("manual reconciliation report", () => {
         ],
         unresolved_running_run_ids: ["RUN-LIVE"],
       }),
-    ).toEqual({
+    ).toMatchObject({
       reconciled_ids: ["EXEC-ORPHAN", "PRD-ORPHAN", "SPEC-ORPHAN", "TASK-ORPHAN"],
       blocked: [
         { id: "EXEC-ORPHAN", reason: "Host terminated without delivery evidence." },
@@ -56,13 +58,40 @@ describe("manual reconciliation report", () => {
           { id: "TASK-LIVE", status: "executing" },
         ],
       }),
-    ).toEqual({ reconciled_ids: [], blocked: [], not_reconciled: [] });
+    ).toMatchObject({ reconciled_ids: [], blocked: [], not_reconciled: [], outcomes: [] });
+  });
+  it("preserves failed Run and owner blocking outcomes from manual orphan closure", () => {
+    const result = reconciliationResult({
+      runs: [
+        {
+          run: { run_id: "RUN-ORPHAN" },
+          status: "failed",
+          finished: { status: "failed", summary: "orphaned" },
+        },
+      ],
+      reconciliations: [
+        {
+          status: "closed",
+          tasks: [{ id: "TASK-X", status: "blocked", status_reason: "repair required" }],
+        },
+      ],
+    });
+    expect(result.outcomes).toEqual([
+      { id: "RUN-ORPHAN", status: "failed", reason: "orphaned" },
+      { id: "TASK-X", status: "blocked", reason: "repair required" },
+    ]);
+    expect(result.reconciled_ids).toEqual(["RUN-ORPHAN", "TASK-X"]);
   });
 
   it("reports unavailable reconciliation instead of returning a successful empty result", async () => {
     const filesystem = { exists: vi.fn(async () => false) } as unknown as WorkspaceFileSystem;
-    await expect(reconcileOpenWork(filesystem, "test-workspace")).rejects.toThrow(
-      "could not be reconciled",
-    );
+    const base = resolve(import.meta.dirname, "../../../../../../.tmp/reconciliation-unavailable");
+    await mkdir(base, { recursive: true });
+    const root = await mkdtemp(join(base, "fixture-"));
+    try {
+      await expect(reconcileOpenWork(filesystem, root)).rejects.toThrow("could not be reconciled");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
   });
 });

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

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import type { Hono } from "hono";
+import { type createDashboardDiagnostics, sanitizeDiagnostic } from "../dashboard-diagnostics.mjs";
+import { API_PREFIX, V2WorkspaceRequiredError } from "./server-http-contracts.js";
+import {
+  createWorkReconciliation,
+  type ReconciliationMode,
+  waitForWorkReconciliation,
+} from "./server-work-reconciliation.js";
+import {
+  ReconciliationCommandTimeoutError,
+  type ReconciliationResult,
+} from "./server-workspace.js";
+
+type Diagnostics = ReturnType<typeof createDashboardDiagnostics>;
+export function createLoggedWorkReconciliation(input: {
+  diagnostics: Diagnostics;
+  reconcile: (mode: ReconciliationMode, jobId: string) => Promise<ReconciliationResult>;
+  snapshotTimes: () => {
+    projection_updated_at: string | null;
+    latest_token_collected_at: string | null;
+  };
+  refresh: (jobId: string | null) => Promise<void>;
+}) {
+  return createWorkReconciliation({
+    reconcile: async (mode, requestedJobId) => {
+      const job_id = requestedJobId ?? randomUUID();
+      const started_at = new Date().toISOString();
+      input.diagnostics.log("reconciliation_started", { job_id, mode });
+      try {
+        const result = await input.reconcile(mode, job_id);
+        const receipt = {
+          ...result,
+          diagnostics: {
+            job_id,
+            started_at,
+            completed_at: new Date().toISOString(),
+            log_directory: ".local/dashboard-logs",
+            ...input.snapshotTimes(),
+          },
+        };
+        input.diagnostics.log("reconciliation_completed", { job_id, result: receipt });
+        return receipt;
+      } catch (error) {
+        input.diagnostics.log("reconciliation_failed", { job_id, error });
+        throw error;
+      }
+    },
+    refresh: (jobId) => input.refresh(jobId ?? null),
+  });
+}
+
+export function registerReconciliationRoute(
+  app: Hono,
+  input: {
+    diagnostics: Diagnostics;
+    readLayout: () => Promise<unknown>;
+    reconcileWork: ReturnType<typeof createLoggedWorkReconciliation>;
+    refresh: (jobId: string | null) => Promise<void>;
+    snapshotState: () => "current" | "updating";
+    refreshCompleted: () => boolean;
+  },
+) {
+  app.post(`${API_PREFIX}/reconcile-open-work`, async (context) => {
+    const request_id = randomUUID();
+    let job_id: string | null = null;
+    context.header("X-ZAIP-Request-Id", request_id);
+    input.diagnostics.log("reconciliation_button_received", { request_id });
+    try {
+      await input.readLayout();
+      const pending = input.reconcileWork("manual", request_id);
+      job_id = input.reconcileWork.jobIdFor(pending);
+      input.diagnostics.log("reconciliation_queued", { request_id, job_id });
+      const result = await waitForWorkReconciliation(pending, () => {
+        input.diagnostics.log("reconciliation_http_deadline", { request_id, job_id });
+        void input.refresh(job_id).catch(() => undefined);
+      });
+      input.diagnostics.log("reconciliation_response", {
+        request_id,
+        job_id: result.diagnostics?.job_id,
+        snapshot_state: input.snapshotState(),
+      });
+      return context.json({
+        reconciliation: result,
+        snapshot_state: input.snapshotState(),
+        projection_refresh_completed: input.refreshCompleted(),
+      });
+    } catch (error) {
+      input.diagnostics.log("reconciliation_response_error", { request_id, job_id, error });
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      const failure = {
+        error: sanitizeDiagnostic(error instanceof Error ? error.message : String(error)),
+        request_id,
+        job_id,
+        log_directory: ".local/dashboard-logs",
+      };
+      if (error instanceof ReconciliationCommandTimeoutError)
+        return context.json(
+          { ...failure, reconciliation_may_be_partial: true, projection_refresh_started: true },
+          408,
+        );
+      return context.json(failure, 400);
+    }
+  });
+}

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

@@ -12,6 +12,7 @@ vi.mock("node:fs", () => ({
 }));
 
 import { startSnapshotSynchronization } from "./server-snapshot-synchronization.js";
+import { createTelemetryProjectionRefresh } from "./server-telemetry-refresh.js";
 
 afterEach(() => {
   watchers.splice(0);
@@ -20,24 +21,73 @@ afterEach(() => {
 });
 
 describe("snapshot source synchronization", () => {
+  it("orders stale-seed startup capture before the initial projection commit", async () => {
+    vi.useFakeTimers();
+    let release!: () => void;
+    const refresh = vi.fn(async () => undefined);
+    const capture = vi.fn(async () => {
+      await new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      return {
+        captured_runs: 0,
+        captured_segments: 0,
+        manifest_state: "initialized" as const,
+        skipped_reason: "no_recent_runs" as const,
+        last_capture_at: new Date().toISOString(),
+      };
+    });
+    startSnapshotSynchronization({
+      workspaceRoot: "C:/workspace",
+      staleSeed: true,
+      watchSources: true,
+      refresh,
+      synchronizeTelemetry: createTelemetryProjectionRefresh({ capture, refresh }).refresh,
+    });
+    expect(capture).toHaveBeenCalledOnce();
+    await vi.advanceTimersByTimeAsync(300);
+    expect(refresh).not.toHaveBeenCalled();
+    release();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(refresh).toHaveBeenCalledOnce();
+  });
+
+  it("keeps controlled snapshots stable when source watching is explicitly disabled", async () => {
+    vi.useFakeTimers();
+    vi.stubEnv("ZAIP_DASHBOARD_WATCH_SOURCES", "0");
+    const refresh = vi.fn(async () => undefined);
+    const synchronizeTelemetry = vi.fn(async () => undefined);
+    startSnapshotSynchronization({
+      workspaceRoot: "C:/workspace",
+      staleSeed: false,
+      watchSources: true,
+      refresh,
+      synchronizeTelemetry,
+    });
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(refresh).not.toHaveBeenCalled();
+    expect(synchronizeTelemetry).not.toHaveBeenCalled();
+  });
   it("observes newly registered checkout records and stops observing removed checkouts", async () => {
     vi.useFakeTimers();
-    let roots = ["C:/main", "C:/codex/worktree"];
+    const primaryRoot = "C:/main";
+    const siblingRoot = "C:/codex/worktree";
+    let roots = [primaryRoot, siblingRoot];
     const refresh = vi.fn(async () => undefined);
     startSnapshotSynchronization({
-      workspaceRoot: roots[0]!,
+      workspaceRoot: primaryRoot,
       discoverSourceRoots: async () => roots,
       staleSeed: false,
       watchSources: true,
       refresh,
     });
     await vi.advanceTimersByTimeAsync(1);
-    const sibling = watchers.find(({ path }) => path === join(roots[1]!, ".agents", "records"));
+    const sibling = watchers.find(({ path }) => path === join(siblingRoot, ".agents", "records"));
     expect(sibling).toBeDefined();
     sibling?.listener();
     await vi.advanceTimersByTimeAsync(300);
     expect(refresh).toHaveBeenCalled();
-    roots = [roots[0]!];
+    roots = [primaryRoot];
     await vi.advanceTimersByTimeAsync(60_000);
     expect(sibling?.close).toHaveBeenCalledOnce();
   });
@@ -51,7 +101,7 @@ describe("snapshot source synchronization", () => {
       captured_runs: 0,
       captured_segments: 0,
       manifest_state: "initialized",
-      skipped_reason: "no_active_runs",
+      skipped_reason: "no_recent_runs",
       last_capture_at: "2026-09-16T00:00:00.000Z",
     });
     const refresh = vi.fn(async () => undefined);
@@ -60,9 +110,12 @@ describe("snapshot source synchronization", () => {
       staleSeed: false,
       watchSources: true,
       refresh,
-      captureActiveTelemetry: capture,
-      onCaptureFailure,
-      onCaptureSuccess,
+      synchronizeTelemetry: createTelemetryProjectionRefresh({
+        capture,
+        refresh,
+        onCaptureFailure,
+        onCaptureSuccess,
+      }).refresh,
       onRefreshFailure,
     });
     await vi.advanceTimersByTimeAsync(301);
@@ -71,7 +124,7 @@ describe("snapshot source synchronization", () => {
     expect(refresh).toHaveBeenCalledTimes(1);
     await vi.advanceTimersByTimeAsync(60_000);
     expect(onCaptureSuccess).toHaveBeenCalledWith(
-      expect.objectContaining({ skipped_reason: "no_active_runs" }),
+      expect.objectContaining({ skipped_reason: "no_recent_runs" }),
     );
     expect(refresh).toHaveBeenCalledTimes(2);
   });
@@ -81,6 +134,8 @@ describe("snapshot source synchronization", () => {
     const workspaceRoot = "C:/workspace";
 
     startSnapshotSynchronization({ workspaceRoot, staleSeed: false, watchSources: true, refresh });
+    await vi.advanceTimersByTimeAsync(0);
+    refresh.mockClear();
 
     const currentData = watchers.find(
       ({ path }) => path === join(workspaceRoot, ".agents", "data"),

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

@@ -1,6 +1,5 @@
 import { watch } from "node:fs";
 import { join } from "node:path";
-import type { ActiveCodexTelemetryCapture } from "./active-codex-telemetry.js";
 
 export function startSnapshotSynchronization(input: {
   workspaceRoot: string;
@@ -9,17 +8,26 @@ export function startSnapshotSynchronization(input: {
   staleSeed: boolean;
   watchSources: boolean;
   refresh: () => Promise<void>;
-  /** Exact active-Codex collection, separate from projection and lifecycle repair. */
-  captureActiveTelemetry?: () => Promise<ActiveCodexTelemetryCapture>;
-  onCaptureFailure?: (error: unknown) => void;
-  onCaptureSuccess?: (result: ActiveCodexTelemetryCapture) => void;
+  /** Capture exact recent usage before rebuilding, without lifecycle repair. */
+  synchronizeTelemetry?: () => Promise<void>;
   /** Report failed asynchronous refreshes; a stale snapshot must never look healthy. */
   onRefreshFailure?: (input: { trigger: "stale_seed" | "source_change"; error: unknown }) => void;
 }): void {
   const refresh = (trigger: "stale_seed" | "source_change") =>
     void input.refresh().catch((error: unknown) => input.onRefreshFailure?.({ trigger, error }));
-  if (input.staleSeed) refresh("stale_seed");
-  if (!input.watchSources || process.env.ZAIP_DASHBOARD_WATCH_SOURCES === "0") return;
+  const watching = input.watchSources && process.env.ZAIP_DASHBOARD_WATCH_SOURCES !== "0";
+  const captureAndRefresh = () =>
+    void (input.synchronizeTelemetry?.() ?? input.refresh()).catch((error: unknown) =>
+      input.onRefreshFailure?.({
+        trigger: input.staleSeed ? "stale_seed" : "source_change",
+        error,
+      }),
+    );
+  // Startup is one ordered pass. Never publish a stale-seed rebuild before
+  // the initial telemetry command has completed.
+  if (watching) captureAndRefresh();
+  else if (input.staleSeed) refresh("stale_seed");
+  if (!watching) return;
   let pendingRefresh: NodeJS.Timeout | undefined;
   const scheduleRefresh = () => {
     if (pendingRefresh !== undefined) clearTimeout(pendingRefresh);
@@ -64,27 +72,11 @@ export function startSnapshotSynchronization(input: {
     }
   };
   void discover();
-  let captureInFlight = false;
-  const captureAndRefresh = () => {
-    if (captureInFlight) return;
-    captureInFlight = true;
-    void (async () => {
-      try {
-        await discover();
-        if (input.captureActiveTelemetry !== undefined) {
-          input.onCaptureSuccess?.(await input.captureActiveTelemetry());
-        }
-      } catch (error) {
-        input.onCaptureFailure?.(error);
-      } finally {
-        scheduleRefresh();
-        captureInFlight = false;
-      }
-    })();
-  };
   // Run at most once a minute. File watchers only project canonical changes;
   // they never launch telemetry or lifecycle work.
-  captureAndRefresh();
-  const freshnessTimer = setInterval(captureAndRefresh, 60_000);
+  const freshnessTimer = setInterval(() => {
+    void discover();
+    captureAndRefresh();
+  }, 60_000);
   freshnessTimer.unref();
 }