@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.3

package/docs/http-api.md

@@ -12,6 +12,41 @@ This document is the authoritative reference for the Prompt Orchestration Pipeli
 - **CORS**: Opt-in via `--cors-origins <comma-separated-origins>` and `--cors-allow-null-origin`. When no origins are configured, no `Access-Control-*` headers are emitted. Cross-origin mutating requests (`POST`, `PUT`, `PATCH`, `DELETE`) to `/api/*` are rejected before dispatch when the origin is not allowed.
 - **Content type**: All JSON responses use `Content-Type: application/json`. SSE streams use `Content-Type: text/event-stream`.
 
+## Canonical Job Status
+
+Job `status` values returned by `/api/jobs` and `/api/jobs/:id` are drawn
+from the canonical `JobStatus` enum:
+
+| Value | Meaning |
+|-------|---------|
+| `pending` | Queued, not yet started |
+| `running` | One or more tasks are executing |
+| `waiting` | Paused on a human gate (approve/reject) |
+| `complete` | All terminal tasks finished successfully (persisted `state: "done"` is mapped to this value on read) |
+| `failed` | A task or gate failed (persisted `state: "failed"` and legacy `status: "error"` both surface as this value) |
+
+The canonical vocabulary is the only vocabulary the server emits. The
+reader tolerates legacy spellings (`done`, `error`, `completed`) on
+input, but the wire `status` is always one of the five values above.
+
+### Interrupted runners
+
+When a pipeline runner process dies before its job reaches a terminal
+state (crash, OOM, `SIGKILL`, or the orchestrator dying alongside it),
+the orchestrator marks the orphaned `running` task and the job `failed`
+durably — on runner exit when the orchestrator observed the child, and
+on the next orchestrator startup via a single boot sweep over
+`current/` for jobs orphaned while the orchestrator was down (including
+detached resume runners from `/restart` and `/tasks/:taskId/start`).
+The persisted states stay the existing `failed`; the distinction from a
+task-logic failure is carried by `tasks[taskId].errorContext.kind =
+"runner-interrupted"` when a running task is attributable, or by root
+`errorContext.kind = "runner-interrupted"` when only the job-level
+status remained `running` (with `code`, `signal`, `source`). Recovery stays
+a client action via `POST /api/jobs/:jobId/restart` or
+`POST /api/jobs/:jobId/tasks/:taskId/start`; the orchestrator does not
+auto-respawn.
+
 ## Response Envelope
 
 Every JSON response uses the shape:
@@ -230,6 +265,37 @@ Capability negotiation is not built into this protocol. Clients discover compati
 - **Adding a new event type** is a **minor** change (given the robustness rule above).
 - **Changing an existing event's payload shape** (removing or renaming a field, changing a field's type) is a **breaking** change.
 
+## Breaking Changes
+
+The changes below are observable to external HTTP/API consumers. They
+are documented here because the spec does not yet ship a real
+schema/version discriminator (deferred to #32). A dated entry is
+added for every change so consumers can grep for the cutover.
+
+### 2026-06-19 — Canonical job status and name-keyed task ids
+
+The persisted `JobState` vocabulary (`done`) and the legacy HTTP
+`status` field (`error`) are both mapped to the canonical `JobStatus`
+enum on read. Task ids are now name-keyed on the server and the
+browser; an unnamed array entry falls back to a zero-based
+`task-${index}` (e.g. `task-0`, `task-1`) so server and browser agree.
+
+| Surface | Before | After |
+|---------|--------|-------|
+| `GET /api/jobs`, `GET /api/jobs/:id` → `status` | `"error"` | `"failed"` |
+| `GET /api/jobs`, `GET /api/jobs/:id` → `status` | `"done"` | `"complete"` |
+| `PipelineOrchestrator.getStatus(...)` → `state` | `"done"` | `"complete"` |
+| `PipelineOrchestrator.listJobs()` → `state` (per job) | mixed (`done` vs `complete`) | always `"complete"` |
+| `tasks` keys (server and browser) | mixed (`task-0`/`task-1` split) | name-keyed; `task-${index}` only for unnamed array entries |
+
+Legacy spellings (`done`, `error`, `completed`) are still **accepted**
+on input by `normalizeJobStatus` / `normalizeJobView` so a mixed
+deploy or stale on-disk file does not mis-render. The server **never
+emits** `done` / `error` as a job status.
+
+This is the only external break signal shipped with this change.
+A durable schema/version discriminator is tracked in #32.
+
 ## Protocol Versioning
 
 The `protocolVersion` integer returned by `GET /api/meta` is the protocol's semver indicator:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanfw/prompt-orchestration-pipeline",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "A Prompt-orchestration pipeline (POP) is a framework for building, running, and experimenting with complex chains of LLM tasks.",
   "type": "module",
   "main": "src/ui/server/index.ts",

package/src/api/__tests__/index.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import { mkdtemp, rm, mkdir, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -214,7 +214,7 @@ describe("PipelineOrchestrator.getStatus", () => {
         id: jobId,
         name: "done-job",
         pipeline: "test-pipeline",
-        state: "complete",
+        state: "done",
         createdAt: "2026-01-01T00:00:00.000Z",
         tasks: {},
       }),
@@ -225,6 +225,7 @@ describe("PipelineOrchestrator.getStatus", () => {
 
     expect(record.jobId).toBe(jobId);
     expect(record.jobName).toBe("done-job");
+    expect(record.state).toBe("complete");
   });
 
   it("finds job by name scan fallback", async () => {
@@ -272,6 +273,57 @@ describe("PipelineOrchestrator.getStatus", () => {
 
     await expect(orch.getStatus("nonexistent-id")).rejects.toThrow("not found");
   });
+
+  it("returns unreadable placeholder for corrupt current job instead of throwing", async () => {
+    const jobId = "33333333-4444-5555-6666-777777777777";
+    const jobDir = join(tmpDir, "pipeline-data", "current", jobId);
+    await mkdir(jobDir, { recursive: true });
+    await Bun.write(join(jobDir, "tasks-status.json"), "{{{not valid json");
+
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const record = await orch.getStatus(jobId);
+
+    expect(record.jobId).toBe(jobId);
+    expect(record.state).toBe("failed");
+    expect(record.readable).toBe(false);
+    expect(record.error).toBeDefined();
+    const error = record.error as { code: string; message: string; path: string };
+    expect(error.code).toBe("STATUS_CORRUPT");
+    expect(error.path).toBe(join(jobDir, "tasks-status.json"));
+    expect(error.message).toContain("Repair or delete");
+    expect(error.message).toContain(jobId);
+  });
+
+  it("skips unexpected current read errors and falls back to complete lookup", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const jobId = "33333333-4444-5555-6666-888888888888";
+    const currentDir = join(tmpDir, "pipeline-data", "current", jobId);
+    await mkdir(currentDir, { recursive: true });
+    await mkdir(join(currentDir, "tasks-status.json"));
+
+    const completeDir = join(tmpDir, "pipeline-data", "complete", jobId);
+    await mkdir(completeDir, { recursive: true });
+    await Bun.write(
+      join(completeDir, "tasks-status.json"),
+      JSON.stringify({
+        id: jobId,
+        name: "complete-fallback",
+        pipeline: "test-pipeline",
+        state: "done",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        tasks: {},
+      }),
+    );
+
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const record = await orch.getStatus(jobId);
+
+    expect(record.jobId).toBe(jobId);
+    expect(record.jobName).toBe("complete-fallback");
+    expect(record.state).toBe("complete");
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(jobId));
+    warn.mockRestore();
+  });
 });
 
 // ─── PipelineOrchestrator.listJobs ───────────────────────────────────────────
@@ -330,7 +382,7 @@ describe("PipelineOrchestrator.listJobs", () => {
         id: completeId,
         name: "complete-one",
         pipeline: "test-pipeline",
-        state: "complete",
+        state: "done",
         createdAt: "2026-01-01T00:00:00.000Z",
         tasks: {},
       }),
@@ -369,4 +421,260 @@ describe("PipelineOrchestrator.listJobs", () => {
 
     expect(jobs).toEqual([]);
   });
+
+  it("surfaces corrupt current job as unreadable placeholder alongside valid and pending jobs", async () => {
+    const pendingId = "bbbb-1111-2222-3333-0001";
+    await Bun.write(
+      join(tmpDir, "pipeline-data", "pending", `${pendingId}-seed.json`),
+      JSON.stringify({ pipeline: "test-pipeline", name: "pending-one" }),
+    );
+
+    const validCurrentId = "bbbb-1111-2222-3333-0002";
+    const validCurrentDir = join(tmpDir, "pipeline-data", "current", validCurrentId);
+    await mkdir(validCurrentDir, { recursive: true });
+    await Bun.write(
+      join(validCurrentDir, "tasks-status.json"),
+      JSON.stringify({
+        id: validCurrentId,
+        name: "valid-current",
+        pipeline: "test-pipeline",
+        state: "running",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        tasks: {},
+      }),
+    );
+
+    const corruptCurrentId = "bbbb-1111-2222-3333-0003";
+    const corruptCurrentDir = join(tmpDir, "pipeline-data", "current", corruptCurrentId);
+    await mkdir(corruptCurrentDir, { recursive: true });
+    await Bun.write(join(corruptCurrentDir, "tasks-status.json"), "{{{not valid json");
+
+    const completeId = "bbbb-1111-2222-3333-0004";
+    const completeDir = join(tmpDir, "pipeline-data", "complete", completeId);
+    await mkdir(completeDir, { recursive: true });
+    await Bun.write(
+      join(completeDir, "tasks-status.json"),
+      JSON.stringify({
+        id: completeId,
+        name: "complete-one",
+        pipeline: "test-pipeline",
+        state: "done",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        tasks: {},
+      }),
+    );
+
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const jobs = await orch.listJobs();
+
+    expect(jobs.length).toBe(4);
+
+    const ids = jobs.map((j) => j.jobId);
+    expect(ids).toContain(pendingId);
+    expect(ids).toContain(validCurrentId);
+    expect(ids).toContain(corruptCurrentId);
+    expect(ids).toContain(completeId);
+
+    const corrupt = jobs.find((j) => j.jobId === corruptCurrentId)!;
+    expect(corrupt.state).toBe("failed");
+    expect(corrupt.readable).toBe(false);
+    const corruptError = corrupt.error as { code: string; message: string; path: string };
+    expect(corruptError.code).toBe("STATUS_CORRUPT");
+    expect(corruptError.path).toBe(join(corruptCurrentDir, "tasks-status.json"));
+    expect(corruptError.message).toContain("Repair or delete");
+    expect(corruptError.message).toContain(corruptCurrentId);
+
+    const valid = jobs.find((j) => j.jobId === validCurrentId)!;
+    expect(valid.readable).toBeUndefined();
+    expect(valid.error).toBeUndefined();
+    expect(valid.jobName).toBe("valid-current");
+
+    const pending = jobs.find((j) => j.jobId === pendingId)!;
+    expect(pending.state).toBe("pending");
+    expect(pending.readable).toBeUndefined();
+  });
+
+  it("skips current job whose status file is missing", async () => {
+    const missingId = "cccc-1111-2222-3333-0001";
+    const missingDir = join(tmpDir, "pipeline-data", "current", missingId);
+    await mkdir(missingDir, { recursive: true });
+
+    const validId = "cccc-1111-2222-3333-0002";
+    const validDir = join(tmpDir, "pipeline-data", "current", validId);
+    await mkdir(validDir, { recursive: true });
+    await Bun.write(
+      join(validDir, "tasks-status.json"),
+      JSON.stringify({
+        id: validId,
+        name: "valid-current",
+        pipeline: "test-pipeline",
+        state: "running",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        tasks: {},
+      }),
+    );
+
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const jobs = await orch.listJobs();
+
+    const ids = jobs.map((j) => j.jobId);
+    expect(ids).toContain(validId);
+    expect(ids).not.toContain(missingId);
+  });
+
+  it("skips current job with unexpected status read error without throwing", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const unreadableId = "dddd-1111-2222-3333-0001";
+    const unreadableDir = join(tmpDir, "pipeline-data", "current", unreadableId);
+    await mkdir(unreadableDir, { recursive: true });
+    await mkdir(join(unreadableDir, "tasks-status.json"));
+
+    const validId = "dddd-1111-2222-3333-0002";
+    const validDir = join(tmpDir, "pipeline-data", "current", validId);
+    await mkdir(validDir, { recursive: true });
+    await Bun.write(
+      join(validDir, "tasks-status.json"),
+      JSON.stringify({
+        id: validId,
+        name: "valid-current",
+        pipeline: "test-pipeline",
+        state: "running",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        tasks: {},
+      }),
+    );
+
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const jobs = await orch.listJobs();
+
+    const ids = jobs.map((j) => j.jobId);
+    expect(ids).toContain(validId);
+    expect(ids).not.toContain(unreadableId);
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(unreadableId));
+    warn.mockRestore();
+  });
+
+  it("getStatus and listJobs return identical state for the same fixture", async () => {
+    const jobId = "cccc-5555-6666-7777-0001";
+    const jobDir = join(tmpDir, "pipeline-data", "current", jobId);
+    await mkdir(jobDir, { recursive: true });
+    await Bun.write(
+      join(jobDir, "tasks-status.json"),
+      JSON.stringify({
+        id: jobId,
+        name: "cross-surface",
+        pipeline: "test-pipeline",
+        state: "running",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        tasks: {
+          a: { state: "running" },
+          b: { state: "pending" },
+        },
+      }),
+    );
+
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const getStatusRecord = await orch.getStatus(jobId);
+    const listJobsRecords = await orch.listJobs();
+    const listJobsRecord = listJobsRecords.find((j) => j.jobId === jobId)!;
+
+    expect(getStatusRecord.state).toBe("running");
+    expect(listJobsRecord.state).toBe("running");
+    expect(getStatusRecord.state).toBe(listJobsRecord.state);
+  });
+
+  it("getStatus returns canonical 'complete' for persisted 'done' state", async () => {
+    const jobId = "cccc-5555-6666-7777-0002";
+    const jobDir = join(tmpDir, "pipeline-data", "complete", jobId);
+    await mkdir(jobDir, { recursive: true });
+    await Bun.write(
+      join(jobDir, "tasks-status.json"),
+      JSON.stringify({
+        id: jobId,
+        name: "done-canonical",
+        pipeline: "test-pipeline",
+        state: "done",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        tasks: { a: { state: "done" } },
+      }),
+    );
+
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const record = await orch.getStatus(jobId);
+
+    expect(record.state).toBe("complete");
+  });
+
+  it("listJobs returns canonical 'complete' for persisted 'done' state without force", async () => {
+    const jobId = "cccc-5555-6666-7777-0003";
+    const jobDir = join(tmpDir, "pipeline-data", "complete", jobId);
+    await mkdir(jobDir, { recursive: true });
+    await Bun.write(
+      join(jobDir, "tasks-status.json"),
+      JSON.stringify({
+        id: jobId,
+        name: "done-list",
+        pipeline: "test-pipeline",
+        state: "done",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        tasks: { a: { state: "done" } },
+      }),
+    );
+
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const jobs = await orch.listJobs();
+    const record = jobs.find((j) => j.jobId === jobId)!;
+
+    expect(record.state).toBe("complete");
+  });
+
+  it("getStatus maps persisted 'error' legacy status to canonical 'failed'", async () => {
+    const jobId = "cccc-5555-6666-7777-0004";
+    const jobDir = join(tmpDir, "pipeline-data", "current", jobId);
+    await mkdir(jobDir, { recursive: true });
+    await Bun.write(
+      join(jobDir, "tasks-status.json"),
+      JSON.stringify({
+        id: jobId,
+        name: "legacy-error",
+        pipeline: "test-pipeline",
+        state: "unknown-state",
+        status: "error",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        tasks: { a: { state: "failed" } },
+      }),
+    );
+
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const record = await orch.getStatus(jobId);
+
+    expect(record.state).toBe("failed");
+  });
+
+  it("listJobs preserves JobView extras (progress, costs)", async () => {
+    const jobId = "cccc-5555-6666-7777-0005";
+    const jobDir = join(tmpDir, "pipeline-data", "current", jobId);
+    await mkdir(jobDir, { recursive: true });
+    await Bun.write(
+      join(jobDir, "tasks-status.json"),
+      JSON.stringify({
+        id: jobId,
+        name: "with-extras",
+        pipeline: "test-pipeline",
+        state: "running",
+        progress: 42,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        costs: { usd: 1.23 },
+        tasks: { a: { state: "running" } },
+      }),
+    );
+
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const jobs = await orch.listJobs();
+    const record = jobs.find((j) => j.jobId === jobId)!;
+
+    expect(record.state).toBe("running");
+    expect(record.progress).toBe(42);
+    expect(record.costs).toEqual({ usd: 1.23 });
+  });
 });

package/src/api/index.ts

@@ -3,8 +3,10 @@ import { mkdir, readdir, rename, stat } from "node:fs/promises";
 import { resolvePipelinePaths, getPendingSeedPath } from "../config/paths";
 import type { PipelinePaths } from "../config/paths";
 import { getPipelineConfig } from "../core/config";
-import { deriveJobStatusFromTasks } from "../config/statuses";
+import { normalizeJobView } from "../core/job-view";
+import type { JobView } from "../core/job-view";
 import { SEED_PATTERN } from "../core/orchestrator";
+import { readJobStatusResult, STATUS_FILENAME, type StatusReadResult } from "../core/status-writer";
 
 /** Result of a successful job submission. */
 export interface SubmitSuccessResult {
@@ -27,7 +29,12 @@ export interface SubmitJobOptions {
   seedObject: unknown;
 }
 
-/** Job status record returned by getStatus. */
+/**
+ * Job status record returned by getStatus.
+ *
+ * Additive optional fields (present only when the on-disk status is unreadable):
+ * `readable: false` and `error: { code, message, path }`. Absent ⇒ normal/readable.
+ */
 export interface JobStatusRecord {
   jobId: string;
   jobName: string;
@@ -71,21 +78,68 @@ async function safeReaddir(dirPath: string): Promise<string[]> {
   }
 }
 
+function locationForPath(paths: PipelinePaths, jobDir: string): "current" | "complete" {
+  if (jobDir.startsWith(paths.current + path.sep) || jobDir === paths.current) return "current";
+  return "complete";
+}
+
 async function readJsonFile<T = unknown>(filePath: string): Promise<T> {
   const text = await Bun.file(filePath).text();
   return JSON.parse(text) as T;
 }
 
-function mapStatusToRecord(data: Record<string, unknown>): JobStatusRecord {
-  const { id, name, pipeline, state, createdAt, ...rest } = data;
-  return {
-    jobId: String(id ?? ""),
-    jobName: String(name ?? id ?? ""),
-    pipeline: String(pipeline ?? ""),
-    state: String(state ?? ""),
-    createdAt: String(createdAt ?? ""),
+function toJobStatusRecord(view: JobView): JobStatusRecord {
+  const {
+    id: _id,
+    jobId: _jobId,
+    name,
+    title: _title,
+    status,
+    pipeline,
+    createdAt,
+    readable,
+    error,
+    ...rest
+  } = view;
+  const record: JobStatusRecord = {
+    jobId: view.jobId,
+    jobName: name,
+    pipeline: pipeline ?? "",
+    state: status,
+    createdAt: createdAt ?? "",
     ...rest,
   };
+  if (readable !== undefined) record["readable"] = readable;
+  if (error !== undefined) record["error"] = error;
+  return record;
+}
+
+function buildCorruptPlaceholder(jobDir: string, jobId: string): JobStatusRecord {
+  const statusPath = path.join(jobDir, STATUS_FILENAME);
+  return {
+    jobId,
+    jobName: jobId,
+    pipeline: "",
+    state: "failed",
+    createdAt: "",
+    readable: false,
+    error: {
+      code: "STATUS_CORRUPT",
+      message:
+        `Status file is unreadable (corrupt). ` +
+        `Repair or delete ${statusPath} for job "${jobId}" to recover.`,
+      path: statusPath,
+    },
+  };
+}
+
+async function readStatusForApi(jobDir: string, label: string): Promise<StatusReadResult | null> {
+  try {
+    return await readJobStatusResult(jobDir);
+  } catch (err) {
+    console.warn(`[api] skipping unreadable status ${label}: ${(err as Error).message}`);
+    return null;
+  }
 }
 
 // ─── Public API ───────────────────────────────────────────────────────────────
@@ -147,13 +201,15 @@ export class PipelineOrchestrator {
   async getStatus(jobName: string): Promise<JobStatusRecord> {
     // 1. Direct jobId lookup in current, then complete
     for (const dir of [this.paths.current, this.paths.complete]) {
-      const statusPath = path.join(dir, jobName, "tasks-status.json");
-      try {
-        const data = await readJsonFile<Record<string, unknown>>(statusPath);
-        return mapStatusToRecord(data);
-      } catch {
-        // not found here, continue
+      const jobDir = path.join(dir, jobName);
+      const result = await readStatusForApi(jobDir, jobName);
+      if (!result) continue;
+      if (result.ok) {
+        return toJobStatusRecord(
+          normalizeJobView(result.value, jobName, locationForPath(this.paths, jobDir)),
+        );
       }
+      if (result.reason === "corrupt") return buildCorruptPlaceholder(jobDir, jobName);
     }
 
     // 2. Name scan fallback
@@ -161,14 +217,14 @@ export class PipelineOrchestrator {
       const entries = await safeReaddir(dir);
       for (const entry of entries) {
         if (entry === ".gitkeep") continue;
-        const statusPath = path.join(dir, entry, "tasks-status.json");
-        try {
-          const data = await readJsonFile<Record<string, unknown>>(statusPath);
-          if (data["name"] === jobName) {
-            return mapStatusToRecord(data);
-          }
-        } catch {
-          // skip unreadable entries
+        const jobDir = path.join(dir, entry);
+        const result = await readStatusForApi(jobDir, entry);
+        if (!result) continue;
+        if (!result.ok) continue;
+        if (result.value["name"] === jobName) {
+          return toJobStatusRecord(
+            normalizeJobView(result.value, entry, locationForPath(this.paths, jobDir)),
+          );
         }
       }
     }
@@ -225,35 +281,28 @@ export class PipelineOrchestrator {
     const currentEntries = await safeReaddir(this.paths.current);
     for (const entry of currentEntries) {
       if (entry === ".gitkeep") continue;
-      const statusPath = path.join(this.paths.current, entry, "tasks-status.json");
-      try {
-        const data = await readJsonFile<Record<string, unknown>>(statusPath);
-        const tasks = data["tasks"];
-        const taskArray = tasks && typeof tasks === "object" && !Array.isArray(tasks)
-          ? Object.values(tasks as Record<string, { state: unknown }>)
-          : [];
-        const state = deriveJobStatusFromTasks(taskArray);
-        const record = mapStatusToRecord(data);
-        record.state = state;
-        results.push(record);
-      } catch (err) {
-        console.warn(`[api] skipping unreadable current job ${entry}: ${(err as Error).message}`);
+      const jobDir = path.join(this.paths.current, entry);
+      const result = await readStatusForApi(jobDir, entry);
+      if (!result) continue;
+      if (!result.ok) {
+        if (result.reason === "corrupt") results.push(buildCorruptPlaceholder(jobDir, entry));
+        continue;
       }
+      results.push(toJobStatusRecord(normalizeJobView(result.value, entry, "current")));
     }
 
     // Complete jobs
     const completeEntries = await safeReaddir(this.paths.complete);
     for (const entry of completeEntries) {
       if (entry === ".gitkeep") continue;
-      const statusPath = path.join(this.paths.complete, entry, "tasks-status.json");
-      try {
-        const data = await readJsonFile<Record<string, unknown>>(statusPath);
-        const record = mapStatusToRecord(data);
-        record.state = "complete";
-        results.push(record);
-      } catch (err) {
-        console.warn(`[api] skipping unreadable complete job ${entry}: ${(err as Error).message}`);
+      const jobDir = path.join(this.paths.complete, entry);
+      const result = await readStatusForApi(jobDir, entry);
+      if (!result) continue;
+      if (!result.ok) {
+        if (result.reason === "corrupt") results.push(buildCorruptPlaceholder(jobDir, entry));
+        continue;
       }
+      results.push(toJobStatusRecord(normalizeJobView(result.value, entry, "complete")));
     }
 
     return results;