@zaip-ai/cli 4.8.0 → 5.0.0

package/templates/.agents/dashboard/packages/local-runtime/src/active-capture-failure.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { activeCaptureFailure } from "./active-capture-failure.js";
+
+describe("public active capture diagnostics", () => {
+  it.each([
+    [{ code: "ETIMEDOUT" }, "timeout"],
+    [{ code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" }, "output_limit"],
+    [{ killed: true, signal: "SIGTERM" }, "process_terminated"],
+    [{ code: 1 }, "process_exit"],
+    [{ code: "ENOENT" }, "spawn_failure"],
+  ])("classifies process failures without guessing their cause", (fields, kind) => {
+    expect(activeCaptureFailure(Object.assign(new Error("private"), fields))).toMatchObject({
+      code: "active_telemetry_capture_failed",
+      failure_kind: kind,
+      exit_code: "code" in fields && typeof fields.code === "number" ? fields.code : null,
+    });
+  });
+
+  it("never exposes child output, command, paths or arbitrary error properties", () => {
+    const error = Object.assign(new Error("Bearer sensitive-value"), {
+      name: "sensitive-value",
+      stdout: "sensitive-value",
+      stderr: "sensitive-value",
+      cmd: "sensitive-value",
+      code: "sensitive-value",
+      signal: "sensitive-value",
+    });
+    const result = activeCaptureFailure(error);
+    expect(JSON.stringify(result)).not.toContain("sensitive-value");
+    expect(result).toMatchObject({
+      failure_kind: "capture_error",
+      process_code: null,
+      exit_code: null,
+      signal: null,
+    });
+    expect(activeCaptureFailure(null).cause).toBe("unknown_error");
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/active-capture-failure.ts

@@ -0,0 +1,35 @@
+/** Public health diagnostics never include command lines, environment or process output. */
+export function activeCaptureFailure(error: unknown) {
+  const failure = error instanceof Error ? error : null;
+  const fields = failure as (Error & { code?: unknown; signal?: unknown; killed?: unknown }) | null;
+  const code = fields?.code;
+  const signal = fields?.signal;
+  const exitCode = Number.isSafeInteger(code) ? (code as number) : null;
+  const processCode =
+    typeof code === "string" &&
+    ["ENOENT", "EACCES", "EPERM", "ETIMEDOUT", "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"].includes(code)
+      ? code
+      : null;
+  const processSignal =
+    typeof signal === "string" && /^SIG[A-Z0-9]{1,12}$/.test(signal) ? signal : null;
+  return {
+    code: "active_telemetry_capture_failed",
+    occurred_at: new Date().toISOString(),
+    cause: failure === null ? "unknown_error" : "Error",
+    failure_kind:
+      processCode === "ETIMEDOUT"
+        ? "timeout"
+        : processCode === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+          ? "output_limit"
+          : fields?.killed === true || processSignal !== null
+            ? "process_terminated"
+            : exitCode !== null
+              ? "process_exit"
+              : processCode !== null
+                ? "spawn_failure"
+                : "capture_error",
+    process_code: processCode,
+    exit_code: exitCode,
+    signal: processSignal,
+  };
+}

package/templates/.agents/dashboard/packages/local-runtime/src/active-codex-telemetry.test.ts

@@ -2,10 +2,11 @@ import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
-
+import { activeCaptureFailure } from "./active-capture-failure.js";
 import {
   captureActiveCodexTelemetry,
   captureRepositoryActiveCodexTelemetry,
+  ObservedCodexCaptureDeadlineError,
 } from "./active-codex-telemetry.js";
 import * as sources from "./sqlite-read-model-source-fingerprint.js";
 
@@ -17,7 +18,7 @@ afterEach(async () => {
 });
 
 describe("active Codex telemetry capture", () => {
-  it("allows the measured catch-up budget and still rejects incomplete output", async () => {
+  it("bounds one automatic pass and rejects a partial receipt without progress", async () => {
     const root = await runtimeFixture("");
     const execute = vi.fn(async (_file: string, _args: string[], _options: unknown) => ({
       stdout: JSON.stringify({
@@ -26,14 +27,64 @@ describe("active Codex telemetry capture", () => {
       stderr: "",
     }));
     await expect(captureActiveCodexTelemetry(root, root, execute as never)).rejects.toThrow(
-      "incomplete",
+      "bounded pending progress",
     );
     expect(execute.mock.calls[0]?.[2]).toMatchObject({
-      timeout: 600_000,
+      timeout: 125_000,
+      signal: expect.any(AbortSignal),
       windowsHide: true,
       cwd: root,
     });
   });
+  it("marks timeout only when its own child deadline aborts the project process", async () => {
+    const root = await runtimeFixture("");
+    const deadline = new AbortController();
+    const execute = vi.fn(
+      async (_file: string, _args: string[], options: { signal: AbortSignal }) =>
+        new Promise<never>((_resolve, reject) => {
+          options.signal.addEventListener(
+            "abort",
+            () =>
+              reject(
+                Object.assign(new Error("private child output"), {
+                  name: "AbortError",
+                  code: "ABORT_ERR",
+                }),
+              ),
+            { once: true },
+          );
+          deadline.abort();
+        }),
+    );
+    await expect(
+      captureActiveCodexTelemetry(root, root, execute as never, deadline.signal),
+    ).rejects.toBeInstanceOf(ObservedCodexCaptureDeadlineError);
+    const failure = activeCaptureFailure(new ObservedCodexCaptureDeadlineError());
+    expect(failure).toMatchObject({ failure_kind: "timeout", process_code: "ETIMEDOUT" });
+    expect(JSON.stringify(failure)).not.toContain("private child output");
+    expect(
+      activeCaptureFailure(
+        Object.assign(new Error("external termination"), {
+          killed: true,
+          signal: "SIGTERM",
+        }),
+      ).failure_kind,
+    ).toBe("process_terminated");
+    const externalAbort = Object.assign(new Error("external cancellation"), {
+      name: "AbortError",
+      code: "ABORT_ERR",
+    });
+    await expect(
+      captureActiveCodexTelemetry(
+        root,
+        root,
+        (async () => {
+          throw externalAbort;
+        }) as never,
+        new AbortController().signal,
+      ),
+    ).rejects.toBe(externalAbort);
+  });
   it("uses the primary CLI for registered worktrees while preserving each target workspace and cwd", async () => {
     const primary = await runtimeFixture(`import {writeFileSync} from 'node:fs';
       import {resolve} from 'node:path';
@@ -77,7 +128,7 @@ describe("active Codex telemetry capture", () => {
 
   it("does not let an empty or stale active index suppress terminal usage capture", async () => {
     const root = await runtimeFixture(
-      "if(!process.argv.includes('--recent') || !process.argv.includes('--drain') || process.argv.includes('--active') || process.argv[process.argv.indexOf('--limit')+1]!=='32') process.exit(8); process.stdout.write(JSON.stringify({telemetry:{mode:'recent_exact_session',complete:true,captured:[{captured:true}]}}));\n",
+      "if(!process.argv.includes('--recent') || process.argv.includes('--drain') || process.argv.includes('--active') || process.argv[process.argv.indexOf('--limit')+1]!=='32') process.exit(8); process.stdout.write(JSON.stringify({telemetry:{mode:'recent_exact_session',complete:true,captured:[{captured:true}]}}));\n",
     );
     await writeFile(
       join(root, ".agents/records/lifecycle/active-work.json"),
@@ -150,7 +201,19 @@ describe("active Codex telemetry capture", () => {
     const root = await runtimeFixture(
       "process.stdout.write(JSON.stringify({telemetry:{mode:'recent_exact_session',complete:false,captured:[]}}));",
     );
-    await expect(captureActiveCodexTelemetry(root)).rejects.toThrow("incomplete");
+    await expect(captureActiveCodexTelemetry(root)).rejects.toThrow("bounded pending progress");
+  });
+  it("reports an examined partial window as pending without inventing missing usage", async () => {
+    const root = await runtimeFixture(
+      "process.stdout.write(JSON.stringify({telemetry:{mode:'recent_exact_session',complete:false,candidate_count:70,processed_count:32,pending_count:38,captured:[{captured:false}]}}));",
+    );
+    await expect(captureActiveCodexTelemetry(root)).resolves.toMatchObject({
+      captured_runs: 0,
+      captured_segments: 0,
+      catch_up_complete: false,
+      pending_runs: 38,
+      skipped_reason: "catch_up_pending",
+    });
   });
   it.each([
     "active_exact_session",

package/templates/.agents/dashboard/packages/local-runtime/src/active-codex-telemetry.ts

@@ -6,13 +6,21 @@ import { lifecycleManifestState } from "./server-lifecycle-diagnostics.js";
 import { dashboardCanonicalSourceRoots } from "./sqlite-read-model-source-fingerprint.js";
 
 const execFileAsync = promisify(execFile);
-// Measured complete catch-up of a 98-Run / 30k-envelope backlog exceeded the
-// old 55s deadline. Keep the UI updating while this finite selection commits;
-// expiry remains a failure and can never promote a partial capture to current.
-export const RECENT_CODEX_CAPTURE_TIMEOUT_MS = 600_000;
+// One automatic pass examines at most 32 Runs. Manual --drain remains separate.
+export const RECENT_CODEX_CAPTURE_TIMEOUT_MS = 120_000;
+
+export class ObservedCodexCaptureDeadlineError extends Error {
+  readonly code = "ETIMEDOUT";
+  readonly deadline_observed = true;
+  constructor() {
+    super("Recent Codex capture exceeded its observed process deadline");
+  }
+}
 
 export type ActiveCodexTelemetryCapture = {
   captured_runs: number;
+  catch_up_complete?: boolean;
+  pending_runs?: number;
   /** The active CLI reports whether a Run changed, not its segment cardinality. */
   captured_segments: number | null;
   manifest_state: "initialized" | "missing" | "invalid";
@@ -23,6 +31,7 @@ export type ActiveCodexTelemetryCapture = {
     | "no_recent_active_runs"
     | "no_recent_runs"
     | "no_new_segments"
+    | "catch_up_pending"
     | null;
   last_capture_at: string;
 };
@@ -36,6 +45,7 @@ export async function captureActiveCodexTelemetry(
   workspaceRoot: string,
   runtimeRoot = workspaceRoot,
   execute = execFileAsync,
+  deadline = AbortSignal.timeout(RECENT_CODEX_CAPTURE_TIMEOUT_MS),
 ): Promise<ActiveCodexTelemetryCapture> {
   // The CLI intentionally treats an absent active-work index as an empty pass.
   // Validate the canonical manifest first so that exit 0 cannot mask missing lifecycle.
@@ -61,7 +71,6 @@ export async function captureActiveCodexTelemetry(
         "--recent",
         "--limit",
         "32",
-        "--drain",
         "--disable-codex-raw",
         "--json",
       ],
@@ -69,24 +78,40 @@ export async function captureActiveCodexTelemetry(
         cwd: workspaceRoot,
         encoding: "utf8",
         windowsHide: true,
-        timeout: RECENT_CODEX_CAPTURE_TIMEOUT_MS,
+        signal: deadline,
+        // A secondary child-process guard covers a broken abort delivery.
+        timeout: RECENT_CODEX_CAPTURE_TIMEOUT_MS + 5_000,
         maxBuffer: 1_024 * 1_024,
       },
     );
     const payload = parseJsonResult(outcome.stdout);
-    const captured = readCaptured(payload);
+    const receipt = readCaptured(payload);
+    const captured = receipt.captured;
     const capturedRuns = captured.filter((item) => item.captured).length;
     return {
       captured_runs: capturedRuns,
+      catch_up_complete: receipt.complete,
+      pending_runs: receipt.pending,
       // Zero is factual for an idle pass. A non-idle pass has no segment count
       // in the CLI contract, so retain unavailable rather than inventing one.
       captured_segments: capturedRuns === 0 ? 0 : null,
       manifest_state: "initialized",
-      skipped_reason:
-        captured.length === 0 ? "no_recent_runs" : capturedRuns === 0 ? "no_new_segments" : null,
+      skipped_reason: !receipt.complete
+        ? "catch_up_pending"
+        : captured.length === 0
+          ? "no_recent_runs"
+          : capturedRuns === 0
+            ? "no_new_segments"
+            : null,
       last_capture_at: new Date().toISOString(),
     };
   } catch (error) {
+    if (
+      deadline.aborted &&
+      error instanceof Error &&
+      (error.name === "AbortError" || ("code" in error && error.code === "ABORT_ERR"))
+    )
+      throw new ObservedCodexCaptureDeadlineError();
     if (isManifestUninitialized(error)) {
       return {
         captured_runs: 0,
@@ -117,10 +142,13 @@ export async function captureRepositoryActiveCodexTelemetry(
   const capturedRuns = results.reduce((count, result) => count + result.captured_runs, 0);
   return {
     captured_runs: capturedRuns,
+    catch_up_complete: results.every((result) => result.catch_up_complete !== false),
+    pending_runs: results.reduce((count, result) => count + (result.pending_runs ?? 0), 0),
     captured_segments: capturedRuns === 0 ? 0 : null,
     manifest_state: primary.manifest_state,
-    skipped_reason:
-      capturedRuns > 0
+    skipped_reason: results.some((result) => result.catch_up_complete === false)
+      ? "catch_up_pending"
+      : capturedRuns > 0
         ? null
         : results.some((result) => result.skipped_reason === "no_new_segments")
           ? "no_new_segments"
@@ -138,17 +166,26 @@ function parseJsonResult(stdout: string): unknown {
   }
 }
 
-function readCaptured(payload: unknown): Array<{ captured: boolean }> {
+function readCaptured(payload: unknown): {
+  captured: Array<{ captured: boolean }>;
+  complete: boolean;
+  pending: number;
+} {
   if (typeof payload !== "object" || payload === null) throw new Error("Invalid capture payload");
   const telemetry = (payload as { telemetry?: unknown }).telemetry;
   if (typeof telemetry !== "object" || telemetry === null)
     throw new Error("Invalid capture telemetry");
-  const receipt = telemetry as { mode?: unknown; complete?: unknown };
-  if (receipt.mode !== "recent_exact_session" || receipt.complete !== true)
+  const receipt = telemetry as {
+    mode?: unknown;
+    complete?: unknown;
+    candidate_count?: unknown;
+    pending_count?: unknown;
+  };
+  if (receipt.mode !== "recent_exact_session" || typeof receipt.complete !== "boolean")
     throw new Error("Recent telemetry capture is incomplete");
   const captured = (telemetry as { captured?: unknown }).captured;
   if (!Array.isArray(captured)) throw new Error("Invalid capture entries");
-  return captured.map((item) => {
+  const items = captured.map((item) => {
     if (
       typeof item !== "object" ||
       item === null ||
@@ -157,6 +194,16 @@ function readCaptured(payload: unknown): Array<{ captured: boolean }> {
       throw new Error("Invalid capture entry");
     return { captured: (item as { captured: boolean }).captured };
   });
+  const pending = receipt.complete ? 0 : receipt.pending_count;
+  if (
+    !receipt.complete &&
+    (!Number.isSafeInteger(pending) ||
+      (pending as number) < 1 ||
+      !Number.isSafeInteger(receipt.candidate_count) ||
+      (receipt.candidate_count as number) < items.length + (pending as number))
+  )
+    throw new Error("Recent telemetry capture lacks bounded pending progress");
+  return { captured: items, complete: receipt.complete, pending: pending as number };
 }
 
 function isManifestUninitialized(error: unknown): boolean {

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

@@ -160,7 +160,12 @@ export function manifestRun(
     artifact_path: `.agents/records/runs/${summary.run_id}`,
     status: summary.status ?? "completed",
     phase: summary.phase ?? "execution",
-    entrypoint: summary.task_id === null ? "conversation" : "task",
+    entrypoint:
+      summary.purpose === "observation"
+        ? "observation"
+        : summary.task_id === null
+          ? "conversation"
+          : "task",
     work_type: "new",
     run_role: delegated ? ("subagent" as const) : ("orchestrator" as const),
     run_kind: delegated ? ("subrun" as const) : ("run" as const),
@@ -187,7 +192,7 @@ export function manifestRun(
     terminal_call_count: summary.llm_call_count,
     failed_call_count: summary.status === "failed" ? summary.llm_call_count : 0,
     cancelled_call_count: summary.status === "cancelled" ? summary.llm_call_count : 0,
-    conversation_id: summary.agent_invocation_id,
+    conversation_id: summary.purpose === "observation" ? null : summary.agent_invocation_id,
     execution_id: summary.execution_id,
     task_id: summary.task_id,
     spec_id: summary.spec_id,
@@ -226,6 +231,7 @@ function manifestRunPurpose(
   delegated: boolean,
 ): RunProjection["run_purpose"] {
   if (
+    value === "observation" ||
     value === "intake" ||
     value === "orchestration" ||
     value === "execution" ||

package/templates/.agents/dashboard/packages/local-runtime/src/server-capture-projection-order.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./server-snapshot-synchronization.js", () => ({
+  startSnapshotSynchronization: vi.fn(),
+}));
+
+import { createDashboardApp } from "./server.js";
+import { withSqliteReadModelFixture } from "./server.test-fixtures.js";
+import { startSnapshotSynchronization } from "./server-snapshot-synchronization.js";
+
+afterEach(() => vi.clearAllMocks());
+
+describe("source changes during active telemetry", () => {
+  it.each([
+    false,
+    true,
+  ])("waits for an earlier projection before capture (failure=%s)", async (fail) => {
+    await withSqliteReadModelFixture("projection-first", async ({ root, filesystem }) => {
+      let settle!: () => void;
+      const refresh = vi
+        .fn(async () => undefined)
+        .mockImplementationOnce(async () => {
+          await new Promise<void>((resolve) => {
+            settle = resolve;
+          });
+          if (fail) throw new Error("projection failed");
+        });
+      const capture = vi.fn(async () => ({
+        captured_runs: 0,
+        captured_segments: null,
+        manifest_state: "initialized" as const,
+        skipped_reason: null,
+        last_capture_at: new Date().toISOString(),
+      }));
+      const app = createDashboardApp(root, "session", undefined, {
+        filesystem,
+        refreshReadModel: refresh,
+        captureTelemetry: capture,
+      });
+      const synchronization = vi.mocked(startSnapshotSynchronization).mock.calls.at(-1)?.[0];
+      if (!synchronization?.synchronizeTelemetry) throw new Error("Synchronization was not wired");
+      const source = synchronization.refresh().catch(() => undefined);
+      const capturing = synchronization.synchronizeTelemetry();
+      const joined = synchronization.refresh();
+      try {
+        await Promise.resolve();
+        expect(capture).not.toHaveBeenCalled();
+        expect(refresh).toHaveBeenCalledOnce();
+      } finally {
+        settle();
+        await Promise.all([source, capturing, joined]);
+      }
+      expect(capture).toHaveBeenCalledOnce();
+      expect(refresh).toHaveBeenCalledTimes(2);
+      expect(await (await app.request("/api/v2/health")).json()).toEqual(
+        expect.objectContaining({
+          active_capture_failure: null,
+          projection_refresh_failure: null,
+        }),
+      );
+    });
+  });
+  it.each([
+    false,
+    true,
+  ])("defers source projection until capture settles (failure=%s)", async (fail) => {
+    await withSqliteReadModelFixture("capture-order", async ({ root, filesystem }) => {
+      let settle!: () => void;
+      const refresh = vi.fn(async () => undefined);
+      const capture = vi.fn(async () => {
+        await new Promise<void>((resolve) => {
+          settle = resolve;
+        });
+        if (fail) throw Object.assign(new Error("capture failed"), { code: 1 });
+        return {
+          captured_runs: 1,
+          captured_segments: null,
+          manifest_state: "initialized" as const,
+          skipped_reason: null,
+          last_capture_at: new Date().toISOString(),
+        };
+      });
+      const app = createDashboardApp(root, "session", undefined, {
+        filesystem,
+        refreshReadModel: refresh,
+        captureTelemetry: capture,
+      });
+      const synchronization = vi.mocked(startSnapshotSynchronization).mock.calls.at(-1)?.[0];
+      if (!synchronization?.synchronizeTelemetry) throw new Error("Synchronization was not wired");
+      const capturing = synchronization.synchronizeTelemetry();
+      const sourceChange = synchronization.refresh();
+      const secondChange = synchronization.refresh();
+      try {
+        await Promise.resolve();
+        expect(refresh).not.toHaveBeenCalled();
+      } finally {
+        settle();
+        await Promise.all([capturing, sourceChange, secondChange]);
+      }
+      expect(capture).toHaveBeenCalledOnce();
+      expect(refresh).toHaveBeenCalledOnce();
+      const health = await (await app.request("/api/v2/health")).json();
+      expect(health).toEqual(
+        expect.objectContaining({
+          active_capture_failure: fail
+            ? expect.objectContaining({
+                failure_kind: "process_exit",
+                exit_code: 1,
+              })
+            : null,
+        }),
+      );
+      await synchronization.refresh();
+      expect(refresh).toHaveBeenCalledTimes(2);
+      expect(capture).toHaveBeenCalledOnce();
+    });
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/server-cost-run-search.test.ts

@@ -0,0 +1,90 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { WorkspaceFileSystem, type WorkspaceLayout } from "@zaip-ai/core";
+import { LifecycleManifestStore } from "@zaip-ai/lifecycle-manifests";
+import { Hono } from "hono";
+import { expect, it } from "vitest";
+import { buildManifestCostRunPage, type CompactRunMetric } from "./server-projections.js";
+
+it("searches Task titles through the real compact projection before Run pagination", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-cost-title-"));
+  try {
+    const filesystem = new WorkspaceFileSystem(root);
+    await new LifecycleManifestStore(filesystem).replace([
+      {
+        schema_version: 1,
+        event_id: "task-title",
+        operation: "upsert",
+        occurred_at: "2026-08-09T12:00:00.000Z",
+        entity: {
+          kind: "task",
+          id: "TASK-1",
+          title: "Needle title",
+          status: "completed",
+          risk: "lite",
+          priority: null,
+          updated_at: "2026-08-09T12:00:00.000Z",
+          relations: [],
+          usage: null,
+          data: { created_at: "2026-08-09T12:00:00.000Z", finished_at: "2026-08-09T12:00:00.000Z" },
+        },
+      },
+    ]);
+    const metric = (id: string, task_id: string | null, hour: number): CompactRunMetric => ({
+      id,
+      task_id,
+      started_at: `2026-08-09T${hour}:00:00.000Z`,
+      finished_at: null,
+      execution_id: null,
+      conversation_id: null,
+      agent: null,
+      agent_name: null,
+      provider: null,
+      model: null,
+      spec_id: null,
+      prd_id: null,
+      change_id: null,
+      phase: "execution",
+      parent_run_id: null,
+      status: "completed",
+      duration_ms: null,
+      total_tokens: null,
+      cost: null,
+      currency: null,
+      events: null,
+    });
+    const summaryPath = ".agents/records/lifecycle/summary.json";
+    const summary = JSON.parse(await filesystem.readText(summaryPath));
+    summary.run_metrics = [
+      metric("RUN-UNRELATED", null, 15),
+      metric("RUN-SECOND", "TASK-1", 14),
+      metric("RUN-FIRST", "TASK-1", 13),
+    ];
+    await filesystem.writeTextAtomic(summaryPath, JSON.stringify(summary));
+    const app = new Hono();
+    app.get("/", async (context) =>
+      context.json(
+        await buildManifestCostRunPage(
+          filesystem,
+          { version: 2 } as WorkspaceLayout,
+          context,
+          { from: "2026-08-09", to: "2026-08-09" },
+          1,
+          1,
+        ),
+      ),
+    );
+    const response = await app.request("/?query=needle%20title&currency=USD");
+    expect(response.status).toBe(200);
+    expect(await response.json()).toMatchObject({
+      page_only: true,
+      run_page: { total: 2, offset: 1, limit: 1, has_more: false },
+      runs: [
+        { run_id: "RUN-FIRST", task_title: "Needle title", input_tokens: null, total_tokens: null },
+      ],
+    });
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,86 @@
+import type { CostMonitorProjection } from "@zaip-ai/dashboard-cost-monitor/contracts";
+import type { CompactRunMetric } from "./server-projections.js";
+
+/** Match the complete compact population before either lifecycle or manifest pagination. */
+export function filterCompactCostRuns(
+  runs: readonly CompactRunMetric[],
+  query: string,
+  tasks: readonly { id: string; title: string }[],
+): CompactRunMetric[] {
+  const needle = query.trim().toLowerCase();
+  if (!needle) return [...runs];
+  const titles = new Map(tasks.map((task) => [task.id, task.title]));
+  return runs.filter((run) =>
+    [
+      run.id,
+      run.task_id,
+      run.task_id === null ? null : titles.get(run.task_id),
+      run.provider,
+      run.agent,
+      run.agent_name,
+      run.model,
+      run.phase,
+      run.spec_id,
+      run.prd_id,
+      run.execution_id,
+      run.conversation_id,
+    ].some((value) => value?.toLowerCase().includes(needle)),
+  );
+}
+
+/** Keeps Cost Run transport incremental without changing aggregate semantics. */
+export function pageCostRunRows(
+  projection: CostMonitorProjection,
+  offset: number,
+  limit: number,
+): CostMonitorProjection {
+  const safeOffset = Math.max(0, offset);
+  const safeLimit = Math.min(500, Math.max(1, limit));
+  return {
+    ...projection,
+    runs: projection.runs.slice(safeOffset, safeOffset + safeLimit),
+    run_page: {
+      offset: safeOffset,
+      limit: safeLimit,
+      total: projection.runs.length,
+      has_more: safeOffset + safeLimit < projection.runs.length,
+    },
+  };
+}
+
+/**
+ * The Runs endpoint advertises these dimensions as server-side filters. Apply
+ * them before offset pagination so the reported total and every page have the
+ * same population. Aggregate fields intentionally retain their full filtered
+ * projection semantics and are not derived from the transport page.
+ */
+export function filterCostRunRows(
+  projection: CostMonitorProjection,
+  filters: {
+    provider: readonly string[];
+    model: readonly string[];
+    agent: readonly string[];
+    phase: readonly string[];
+    status: readonly string[];
+  },
+): CostMonitorProjection {
+  const includes = (values: readonly string[], value: string) =>
+    values.length === 0 || values.includes(value);
+  const provider = (value: string | null) => {
+    const normalized = value?.trim().toLowerCase();
+    return !normalized || normalized === "unknown" || normalized === "codex"
+      ? "openai"
+      : normalized;
+  };
+  return {
+    ...projection,
+    runs: projection.runs.filter(
+      (run) =>
+        includes(filters.provider, provider(run.provider)) &&
+        includes(filters.model, run.model) &&
+        includes(filters.agent, run.agent_name) &&
+        includes(filters.phase, run.phase) &&
+        includes(filters.status, run.task_status),
+    ),
+  };
+}