@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.4

package/src/core/__tests__/job-view.test.ts

@@ -0,0 +1,1341 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { __resetWarnedFallbackKeys, deriveProgress, normalizeJobView } from "../job-view";
+import type { JobView } from "../job-view";
+
+const JOB_ID = "job-abc-123";
+const LOCATION = "current";
+
+let warnSpy: ReturnType<typeof spyOn<Console, "warn">> | null = null;
+
+function captureWarn(): ReturnType<typeof spyOn<Console, "warn">> {
+  warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  return warnSpy;
+}
+
+function restoreWarn(): void {
+  warnSpy?.mockRestore();
+  warnSpy = null;
+}
+
+function callsContaining(spy: ReturnType<typeof spyOn<Console, "warn">>, fragment: string): number {
+  return spy.mock.calls.filter((call) => typeof call[0] === "string" && call[0].includes(fragment)).length;
+}
+
+function warnCallsContaining(fragment: string): number {
+  return warnSpy ? callsContaining(warnSpy, fragment) : 0;
+}
+
+beforeEach(() => {
+  __resetWarnedFallbackKeys();
+  captureWarn();
+});
+
+afterEach(() => {
+  restoreWarn();
+});
+
+describe("normalizeJobView", () => {
+  describe("canonical output (AC-1)", () => {
+    test("never emits 'error' as a job status (persisted 'failed' maps to 'failed')", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "failed", tasks: { a: { state: "failed" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("never emits 'done' as a job status (persisted 'done' maps to 'complete')", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { a: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("always sets id, jobId, location, and a title", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { name: "My Job", state: "pending" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.id).toBe(JOB_ID);
+      expect(view.jobId).toBe(JOB_ID);
+      expect(view.location).toBe(LOCATION);
+      expect(view.name).toBe("My Job");
+      expect(view.title).toBe("My Job");
+    });
+
+    test("falls back to jobId for the title when name/title are missing", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "pending" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.name).toBe(JOB_ID);
+      expect(view.title).toBe(JOB_ID);
+    });
+  });
+
+  describe("persisted state authoritative (AC-2 precedence 1)", () => {
+    test("state:'pending' returns 'pending' even when raw.status says 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "pending", status: "failed" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("pending");
+    });
+
+    test("state:'running' wins over a 'failed' raw.status", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", status: "failed" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("running");
+    });
+
+    test("state:'done' (persisted JobState) maps to 'complete'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "done" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("state:'done' in current with pending tasks derives from tasks instead of hiding pending work", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { a: { state: "done" }, b: { state: "pending" } } },
+        JOB_ID,
+        "current",
+      );
+
+      // Assert
+      expect(view.status).toBe("pending");
+    });
+
+    test("state:'done' in current with running tasks derives running status", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { a: { state: "done" }, b: { state: "running" } } },
+        JOB_ID,
+        "current",
+      );
+
+      // Assert
+      expect(view.status).toBe("running");
+    });
+
+    test("state:'done' in complete location remains complete even when archived tasks disagree", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { a: { state: "done" }, b: { state: "pending" } } },
+        JOB_ID,
+        "complete",
+      );
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("state is case-insensitive: 'FAILED' → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "FAILED" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+  });
+
+  describe("reconciled interrupted job regression (#315, AC-2)", () => {
+    test("state:'failed' + task failed with errorContext.kind='runner-interrupted' → status:'failed' and errorContext preserved", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "failed",
+          tasks: {
+            research: {
+              state: "failed",
+              error: "runner exited without completing this task",
+              errorContext: {
+                kind: "runner-interrupted",
+                code: 1,
+                signal: null,
+                source: "child-exit",
+              },
+            },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("failed");
+      expect(view.tasks.research?.errorContext).toEqual({
+        kind: "runner-interrupted",
+        code: 1,
+        signal: null,
+        source: "child-exit",
+      });
+      expect(view.tasks.research?.error).toEqual({ message: "runner exited without completing this task" });
+    });
+
+    test("state:'failed' + job-level runner interruption preserves root errorContext", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "failed",
+          error: {
+            name: "RunnerInterrupted",
+            message: "runner exited while the job was still marked running",
+          },
+          errorContext: {
+            kind: "runner-interrupted",
+            code: 1,
+            signal: null,
+            source: "boot-sweep",
+          },
+          tasks: {
+            research: { state: "done", currentStage: null },
+            analysis: { state: "pending", currentStage: null },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("failed");
+      expect(view.error).toEqual({
+        code: "RunnerInterrupted",
+        name: "RunnerInterrupted",
+        message: "runner exited while the job was still marked running",
+      });
+      expect(view.errorContext).toEqual({
+        kind: "runner-interrupted",
+        code: 1,
+        signal: null,
+        source: "boot-sweep",
+      });
+    });
+  });
+
+  describe("waiting is never lost (AC-3)", () => {
+    test("state:'waiting' + all tasks done → 'waiting' (persisted state authoritative)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "waiting", tasks: { a: { state: "done" }, b: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("waiting");
+    });
+
+    test("state:'waiting' wins over a 'failed' raw.status", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "waiting", status: "failed" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("waiting");
+    });
+  });
+
+  describe("raw.status fallback (AC-2 precedence 2)", () => {
+    test("state absent + status:'running' (no tasks) → 'running'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "running" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("running");
+    });
+
+    test("state absent + status:'complete' (no tasks) → 'complete'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "complete" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("state absent + status:'failed' (no tasks) → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "failed" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("state absent + status:'error' (legacy synonym) → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "error" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("state absent + status:'done' (legacy synonym) → 'complete'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "done" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("status case-insensitive: 'ERROR' → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "ERROR" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("state unrecognized + status:'error' → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "bogus-state", status: "error" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+  });
+
+  describe("task-derived fallback (AC-2 precedence 3)", () => {
+    test("state absent + no status + all tasks done → 'complete' and warns once", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "done" }, b: { state: "done" } } };
+
+      // Act
+      const view: JobView = normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("state absent + no status + tasks failed + done → 'failed' (failed priority) and warns", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "failed" }, b: { state: "done" } } };
+
+      // Act
+      const view: JobView = normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("state absent + no status + tasks running + done → 'running' and warns", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "running" }, b: { state: "done" } } };
+
+      // Act
+      const view: JobView = normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("running");
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("state absent + no status + unrecognized status falls through to derivation", () => {
+      // Arrange
+      const raw = { status: "mystery-status", tasks: { a: { state: "done" } } };
+
+      // Act
+      const view: JobView = normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("task-derived fallback warns once across multiple calls for the same location:jobId", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "done" } } };
+
+      // Act
+      normalizeJobView(raw, JOB_ID, LOCATION);
+      normalizeJobView(raw, JOB_ID, LOCATION);
+      normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("task-derived fallback warns separately for different location:jobId keys", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "done" } } };
+
+      // Act
+      normalizeJobView(raw, "job-A", "current");
+      normalizeJobView(raw, "job-B", "current");
+      normalizeJobView(raw, "job-A", "complete");
+
+      // Assert
+      expect(warnCallsContaining("current:job-A")).toBe(1);
+      expect(warnCallsContaining("current:job-B")).toBe(1);
+      expect(warnCallsContaining("complete:job-A")).toBe(1);
+    });
+  });
+
+  describe("disagreement cases (AC-4)", () => {
+    test("state:'failed' + tasks all done → 'failed' (persisted state authoritative)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "failed", tasks: { a: { state: "done" }, b: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("state:'running' + tasks all done → 'running' (persisted state authoritative)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", tasks: { a: { state: "done" }, b: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("running");
+    });
+
+    test("state absent + tasks all done → 'complete'", () => {
+      // Arrange
+      const raw = { tasks: { a: { state: "done" }, b: { state: "done" } } };
+
+      // Act
+      const view: JobView = normalizeJobView(raw, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+      expect(warnCallsContaining(`${LOCATION}:${JOB_ID}`)).toBe(1);
+    });
+
+    test("state:'done' + tasks all done → 'complete' (agreement)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { a: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+  });
+
+  describe("liberal input, canonical output (AC-5)", () => {
+    test("status:'error' (legacy) with no valid state → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "error" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+
+    test("state:'done' (persisted) → 'complete' and never 'done'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "done" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+      expect(view.status).not.toBe("done");
+    });
+
+    test("status:'done' (legacy) → 'complete' and never 'done'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ status: "done" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+      expect(view.status).not.toBe("done");
+    });
+
+    test("case-insensitive: state:'DONE' → 'complete'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "DONE" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("complete");
+    });
+
+    test("case-insensitive: state:'  failed  ' → 'failed'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "  failed  " }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.status).toBe("failed");
+    });
+  });
+
+  describe("field preservation", () => {
+    test("ignores persisted progress and derives via deriveProgress (AC-7)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", progress: 42, tasks: { a: { state: "done" }, b: { state: "running" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.progress).toBe(50);
+    });
+
+    test("derives progress with pipelineConfig task count when present", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "running",
+          progress: 99,
+          pipelineConfig: { tasks: ["a", "b", "c", "d"] },
+          tasks: {
+            a: { state: "done" },
+            b: { state: "running" },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.progress).toBe(25);
+      expect(view.pipelineConfig).toEqual({ tasks: ["a", "b", "c", "d"] });
+    });
+
+    test("derives progress from completed tasks when persisted progress is missing", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", tasks: { a: { state: "done" }, b: { state: "skipped" }, c: { state: "pending" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.progress).toBe(66);
+    });
+
+    test("derives progress when persisted progress is not finite", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", progress: Number.NaN, tasks: { a: { state: "done" }, b: { state: "pending" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.progress).toBe(50);
+    });
+
+    test("maps live snapshot lastUpdated to updatedAt", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "running", lastUpdated: "2026-06-19T12:00:00.000Z" },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.updatedAt).toBe("2026-06-19T12:00:00.000Z");
+      expect(view.lastUpdated).toBe("2026-06-19T12:00:00.000Z");
+    });
+
+    test("prefers explicit updatedAt over lastUpdated", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "running",
+          updatedAt: "2026-06-19T12:05:00.000Z",
+          lastUpdated: "2026-06-19T12:00:00.000Z",
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.updatedAt).toBe("2026-06-19T12:05:00.000Z");
+      expect(view.lastUpdated).toBe("2026-06-19T12:00:00.000Z");
+    });
+
+    test("preserves explicit top-level costs when present", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", costs: { totalCost: 7, totalTokens: 12 } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toEqual({ totalCost: 7, totalTokens: 12 });
+    });
+
+    test("aggregates costs from task tokenUsage when top-level costs are absent", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "done",
+          tasks: {
+            alpha: { state: "done", tokenUsage: [["openai:gpt-4o", 10, 5, 0.25]] },
+            beta: { state: "done", tokenUsage: [["anthropic:claude", 7, 3, 0.5], ["bad"]] },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toEqual({
+        totalCost: 0.75,
+        totalTokens: 25,
+        totalInputTokens: 17,
+        totalOutputTokens: 8,
+        estimatedCost: 0,
+        unavailableCost: 0,
+        hasEstimated: false,
+        alpha: {
+          inputTokens: 10,
+          outputTokens: 5,
+          inputCost: 0,
+          outputCost: 0,
+          totalCost: 0.25,
+          source: "reported",
+        },
+        beta: {
+          inputTokens: 7,
+          outputTokens: 3,
+          inputCost: 0,
+          outputCost: 0,
+          totalCost: 0.5,
+          source: "reported",
+        },
+      });
+      expect(view.tasks.alpha?.tokenUsage).toEqual([["openai:gpt-4o", 10, 5, 0.25]]);
+      expect(view.tasks.beta?.tokenUsage).toEqual([
+        ["anthropic:claude", 7, 3, 0.5],
+        ["bad"],
+      ]);
+    });
+
+    test("normalizes persisted string task errors to message objects", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "failed",
+          tasks: {
+            agent: { state: "failed", error: "Agent step failed" },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.tasks.agent?.error).toEqual({ message: "Agent step failed" });
+    });
+
+    test("preserves readable:false when present", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "failed", readable: false },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.readable).toBe(false);
+    });
+
+    test("preserves readable:true when present", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", readable: true },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.readable).toBe(true);
+    });
+
+    test("readable is undefined when absent (defaults to readable per #313)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView({ state: "done" }, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.readable).toBeUndefined();
+    });
+
+    test("preserves error: { code, message, path } when well-formed", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { readable: false, error: { code: "STATUS_CORRUPT", message: "bad json", path: "/tmp/x" } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toEqual({ code: "STATUS_CORRUPT", message: "bad json", path: "/tmp/x" });
+    });
+
+    test("preserves error without path", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { readable: false, error: { code: "STATUS_CORRUPT", message: "bad json" } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toEqual({ code: "STATUS_CORRUPT", message: "bad json" });
+    });
+
+    test("normalizes gate rejection errors from name/message", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { error: { name: "GateRejected", message: "needs another pass" } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toEqual({
+        code: "GateRejected",
+        message: "needs another pass",
+        name: "GateRejected",
+      });
+    });
+
+    test("normalizes runner failures from name/message/stack", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { error: { name: "Error", message: "boom", stack: "trace" } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toEqual({
+        code: "Error",
+        message: "boom",
+        name: "Error",
+        stack: "trace",
+      });
+    });
+
+    test("uses a fallback code for message-only errors", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { error: { code: 42, message: "bad" } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toEqual({ code: "JOB_ERROR", message: "bad" });
+    });
+
+    test("drops error when message is not a string", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { error: { code: "STATUS_CORRUPT", message: 42 } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.error).toBeUndefined();
+    });
+  });
+
+  describe("task id synthesis (AC-8 server side)", () => {
+    test("array tasks with explicit name fields are keyed by name", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: [{ name: "alpha" }, { name: "beta" }] },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["alpha", "beta"]);
+    });
+
+    test("array tasks with no name fall back to zero-based 'task-0', 'task-1'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: [{}, {}] },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["task-0", "task-1"]);
+    });
+
+    test("array tasks with no name preserve order in the fallback", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: [{ state: "done" }, { state: "done" }, { state: "done" }] },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["task-0", "task-1", "task-2"]);
+    });
+
+    test("mixed array (named + unnamed) uses name where present, 'task-N' otherwise", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: [{ name: "alpha" }, {}] },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["alpha", "task-1"]);
+    });
+
+    test("empty-string name falls back to 'task-${index}'", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: [{ name: "" }] },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["task-0"]);
+    });
+
+    test("object tasks are keyed by their existing keys (pipeline order preserved)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        { state: "done", tasks: { plan: { state: "done" }, review: { state: "done" } } },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(Object.keys(view.tasks)).toEqual(["plan", "review"]);
+    });
+  });
+
+  describe("robustness", () => {
+    test("non-object raw returns a JobView with empty tasks and pending status (no throw)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView("not an object", JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.tasks).toEqual({});
+      expect(view.status).toBe("pending");
+    });
+
+    test("null raw returns a JobView with empty tasks and pending status (no throw)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(null, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.tasks).toEqual({});
+      expect(view.status).toBe("pending");
+    });
+
+    test("undefined raw returns a JobView with empty tasks and pending status (no throw)", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(undefined, JOB_ID, LOCATION);
+
+      // Assert
+      expect(view.tasks).toEqual({});
+      expect(view.status).toBe("pending");
+    });
+  });
+
+  describe("gate kind preservation (AC-11)", () => {
+    test("preserves gate.kind === 'control_invalid' through normalizeJobView", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "waiting",
+          gate: {
+            afterTask: "review",
+            message: "Control file invalid for review: bad directive.",
+            requestedAt: "2026-06-19T12:00:00.000Z",
+            kind: "control_invalid",
+          },
+          tasks: { review: { state: "done" } },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.gate?.kind).toBe("control_invalid");
+    });
+
+    test("omits gate.kind when value is not one of the allowed strings", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "waiting",
+          gate: {
+            afterTask: "review",
+            message: "Control file invalid.",
+            requestedAt: "2026-06-19T12:00:00.000Z",
+            kind: 42,
+          },
+          tasks: { review: { state: "done" } },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.gate).toBeDefined();
+      expect(Object.hasOwn(view.gate!, "kind")).toBe(false);
+    });
+  });
+
+  describe("getCosts source propagation (AC-10)", () => {
+    test("mixed reported+estimated tuples separate measured from estimated totals", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "done",
+          tasks: {
+            alpha: { state: "done", tokenUsage: [["openai:gpt-4o", 10, 5, 0.25, "reported"]] },
+            beta: { state: "done", tokenUsage: [["anthropic:claude", 7, 3, 0.5, "estimated"]] },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toMatchObject({
+        totalCost: 0.25,
+        estimatedCost: 0.5,
+        unavailableCost: 0,
+        hasEstimated: true,
+        totalTokens: 25,
+        totalInputTokens: 17,
+        totalOutputTokens: 8,
+      });
+      expect(view.costs).toMatchObject({
+        alpha: { source: "reported", totalCost: 0.25, inputTokens: 10, outputTokens: 5 },
+        beta: { source: "estimated", totalCost: 0.5, inputTokens: 7, outputTokens: 3 },
+      });
+    });
+
+    test("all-reported tuples do not set an estimate marker", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "done",
+          tasks: {
+            alpha: { state: "done", tokenUsage: [["openai:gpt-4o", 10, 5, 0.25, "reported"]] },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toMatchObject({
+        totalCost: 0.25,
+        estimatedCost: 0,
+        unavailableCost: 0,
+        hasEstimated: false,
+      });
+      expect(view.costs).toMatchObject({ alpha: { source: "reported", totalCost: 0.25 } });
+      expect(Object.hasOwn(view.costs.alpha as object, "failed")).toBe(false);
+    });
+
+    test("reported usage with estimated cost stays out of measured totals", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "done",
+          tasks: {
+            alpha: {
+              state: "done",
+              tokenUsage: [["openai:unknown-model", 10, 5, 0, "reported", false, true]],
+            },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toMatchObject({
+        totalCost: 0,
+        estimatedCost: 0,
+        unavailableCost: 0,
+        hasEstimated: true,
+        totalTokens: 15,
+        alpha: {
+          source: "reported",
+          totalCost: 0,
+          costEstimated: true,
+        },
+      });
+    });
+
+    test("legacy 4-element tuples are treated as reported", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "done",
+          tasks: {
+            alpha: { state: "done", tokenUsage: [["openai:gpt-4o", 10, 5, 0.25]] },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toMatchObject({
+        totalCost: 0.25,
+        estimatedCost: 0,
+        unavailableCost: 0,
+        hasEstimated: false,
+      });
+      expect(view.costs).toMatchObject({ alpha: { source: "reported", totalCost: 0.25 } });
+    });
+
+    test("unavailable source contributes to unavailableCost and sets hasEstimated", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "done",
+          tasks: {
+            alpha: {
+              state: "done",
+              tokenUsage: [["claudecode:default", 0, 0, 0.1, "unavailable"]],
+            },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toMatchObject({
+        totalCost: 0,
+        estimatedCost: 0,
+        unavailableCost: 0.1,
+        hasEstimated: true,
+      });
+      expect(view.costs).toMatchObject({ alpha: { source: "unavailable", totalCost: 0.1 } });
+    });
+
+    test("cost-only agent tuple surfaces unavailable cost, not a measured total (AC-6)", () => {
+      // Arrange — the exact 7-element tuple the stage runAgent / pipeline agent
+      // path emits for a token-less (costUsd-only) harness via recordAgentUsage.
+      const view: JobView = normalizeJobView(
+        {
+          state: "done",
+          tasks: {
+            "agent-cost-task": {
+              state: "done",
+              tokenUsage: [["opencode:gpt-4o", 0, 0, 0.12, "unavailable", false, true]],
+            },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert — cost lands in unavailableCost (estimated), never the measured totalCost.
+      expect(view.costs).toMatchObject({
+        totalCost: 0,
+        totalTokens: 0,
+        estimatedCost: 0,
+        unavailableCost: 0.12,
+        hasEstimated: true,
+      });
+      expect(view.costs).toMatchObject({
+        "agent-cost-task": { source: "unavailable", totalCost: 0.12, costEstimated: true },
+      });
+    });
+
+    test("zero source contributes no cost and does not set hasEstimated", () => {
+      // Arrange / Act — mix zero with reported so the job has a non-empty costs
+      // object and we can verify zero does not add to estimated/unavailable.
+      const view: JobView = normalizeJobView(
+        {
+          state: "done",
+          tasks: {
+            alpha: {
+              state: "done",
+              tokenUsage: [
+                ["mock:mock", 0, 0, 0, "zero"],
+                ["openai:gpt-4o", 10, 5, 0.25, "reported"],
+              ],
+            },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert — zero source is legitimate reported-zero; no estimate marker.
+      expect(view.costs).toMatchObject({
+        totalCost: 0.25,
+        estimatedCost: 0,
+        unavailableCost: 0,
+        hasEstimated: false,
+      });
+    });
+
+    test("6-element failed tuple marks the task breakdown as failed", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "failed",
+          tasks: {
+            alpha: {
+              state: "failed",
+              tokenUsage: [["openai:gpt-4o", 10, 5, 0.25, "estimated", true]],
+            },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toMatchObject({
+        estimatedCost: 0.25,
+        hasEstimated: true,
+        alpha: { source: "estimated", failed: true, totalCost: 0.25 },
+      });
+    });
+
+    test("legacy 6-element failed tuple is not mistaken for a costEstimated slot", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "failed",
+          tasks: {
+            alpha: {
+              state: "failed",
+              tokenUsage: [["openai:gpt-4o", 10, 5, 0.25, "reported", true]],
+            },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toMatchObject({
+        totalCost: 0.25,
+        estimatedCost: 0,
+        hasEstimated: false,
+        alpha: { source: "reported", failed: true, totalCost: 0.25 },
+      });
+      expect(Object.hasOwn(view.costs.alpha as object, "costEstimated")).toBe(false);
+    });
+
+    test("a task with mixed sources takes the worst (most uncertain) source", () => {
+      // Arrange / Act
+      const view: JobView = normalizeJobView(
+        {
+          state: "done",
+          tasks: {
+            alpha: {
+              state: "done",
+              tokenUsage: [
+                ["openai:gpt-4o", 10, 5, 0.25, "reported"],
+                ["anthropic:claude", 7, 3, 0.5, "estimated"],
+              ],
+            },
+          },
+        },
+        JOB_ID,
+        LOCATION,
+      );
+
+      // Assert
+      expect(view.costs).toMatchObject({
+        totalCost: 0.25,
+        estimatedCost: 0.5,
+        hasEstimated: true,
+        alpha: { source: "estimated", totalCost: 0.75 },
+      });
+    });
+  });
+});
+
+describe("deriveProgress (AC-6)", () => {
+  test("taskCount = configured when configured > actual", () => {
+    // Arrange
+    const tasks = [{ state: "done" }, { state: "pending" }];
+
+    // Act
+    const result = deriveProgress(tasks, 5);
+
+    // Assert
+    expect(result.taskCount).toBe(5);
+    expect(result.doneCount).toBe(1);
+    expect(result.completedCount).toBe(1);
+    expect(result.progress).toBe(Math.floor((1 / 5) * 100));
+  });
+
+  test("taskCount = actual when actual > configured", () => {
+    // Arrange
+    const tasks = [{ state: "done" }, { state: "done" }, { state: "skipped" }, { state: "pending" }];
+
+    // Act
+    const result = deriveProgress(tasks, 1);
+
+    // Assert
+    expect(result.taskCount).toBe(4);
+    expect(result.doneCount).toBe(2);
+    expect(result.completedCount).toBe(3);
+    expect(result.progress).toBe(Math.floor((3 / 4) * 100));
+  });
+
+  test("taskCount = actual when configuredCount is null", () => {
+    // Arrange
+    const tasks = [{ state: "done" }, { state: "skipped" }, { state: "pending" }];
+
+    // Act
+    const result = deriveProgress(tasks, null);
+
+    // Assert
+    expect(result.taskCount).toBe(3);
+    expect(result.progress).toBe(Math.floor((2 / 3) * 100));
+  });
+
+  test("zero tasks returns taskCount 0 and progress 0", () => {
+    // Arrange / Act
+    const result = deriveProgress([], null);
+
+    // Assert
+    expect(result.taskCount).toBe(0);
+    expect(result.doneCount).toBe(0);
+    expect(result.completedCount).toBe(0);
+    expect(result.progress).toBe(0);
+  });
+
+  test("zero tasks + configuredCount 0 returns taskCount 0 and progress 0", () => {
+    // Arrange / Act
+    const result = deriveProgress([], 0);
+
+    // Assert
+    expect(result.taskCount).toBe(0);
+    expect(result.progress).toBe(0);
+  });
+
+  test("progress clamps at 100 when configured < actual and all tasks are completed", () => {
+    // Arrange
+    const tasks = [{ state: "done" }, { state: "done" }];
+
+    // Act
+    const result = deriveProgress(tasks, 1);
+
+    // Assert
+    expect(result.taskCount).toBe(2);
+    expect(result.completedCount).toBe(2);
+    expect(result.progress).toBe(100);
+  });
+
+  test("doneCount counts only 'done', not 'skipped'", () => {
+    // Arrange
+    const tasks = [{ state: "done" }, { state: "skipped" }, { state: "skipped" }];
+
+    // Act
+    const result = deriveProgress(tasks, null);
+
+    // Assert
+    expect(result.doneCount).toBe(1);
+    expect(result.completedCount).toBe(3);
+  });
+
+  test("completedCount counts both 'done' and 'skipped'", () => {
+    // Arrange
+    const tasks = [{ state: "done" }, { state: "skipped" }, { state: "skipped" }];
+
+    // Act
+    const result = deriveProgress(tasks, null);
+
+    // Assert
+    expect(result.completedCount).toBe(3);
+  });
+
+  test("tasks with undefined state are not counted as completed", () => {
+    // Arrange
+    const tasks = [{}, { state: "done" }];
+
+    // Act
+    const result = deriveProgress(tasks, null);
+
+    // Assert
+    expect(result.doneCount).toBe(1);
+    expect(result.completedCount).toBe(1);
+    expect(result.progress).toBe(50);
+  });
+
+  test("tasks with non-completion state ('running') are not counted", () => {
+    // Arrange
+    const tasks = [{ state: "running" }, { state: "done" }];
+
+    // Act
+    const result = deriveProgress(tasks, null);
+
+    // Assert
+    expect(result.doneCount).toBe(1);
+    expect(result.completedCount).toBe(1);
+    expect(result.progress).toBe(50);
+  });
+});
+
+describe("__resetWarnedFallbackKeys", () => {
+  test("clears the warn cache so a subsequent call warns again", () => {
+    // Arrange
+    const raw = { tasks: { a: { state: "done" } } };
+
+    // Act
+    normalizeJobView(raw, JOB_ID, LOCATION);
+    const firstCalls = warnCallsContaining(`${LOCATION}:${JOB_ID}`);
+    __resetWarnedFallbackKeys();
+    normalizeJobView(raw, JOB_ID, LOCATION);
+    const secondCalls = warnCallsContaining(`${LOCATION}:${JOB_ID}`);
+
+    // Assert
+    expect(firstCalls).toBe(1);
+    expect(secondCalls).toBe(2);
+  });
+});