@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.4

package/src/ui/server/endpoints/task-analysis-endpoint.ts

@@ -1,12 +1,28 @@
 import path from "node:path";
 
+import { TaskAnalysisRepository } from "../../../task-analysis/repository";
+import { resolveUnderRoot } from "../../../utils/path-containment";
 import { sendJson } from "../utils/http-utils";
 
-export async function handleTaskAnalysis(_req: Request, slug: string, taskId: string): Promise<Response> {
-  const root = process.env["PO_ROOT"] ?? process.cwd();
-  const filePath = path.join(root, "pipeline-config", slug, "tasks", `${taskId}.analysis.json`);
-  if (!(await Bun.file(filePath).exists())) {
+export async function handleTaskAnalysis(
+  _req: Request,
+  slug: string,
+  taskId: string,
+  root: string,
+): Promise<Response> {
+  const validatedPath = resolveUnderRoot(
+    path.join(root, "pipeline-config"),
+    slug,
+    "tasks",
+    `${taskId}.analysis.json`,
+  );
+  if (validatedPath === null) {
+    return sendJson(400, { ok: false, code: "BAD_PATH", message: "invalid task-analysis path" });
+  }
+
+  const analysis = await TaskAnalysisRepository.readFromPath(validatedPath);
+  if (analysis === null) {
     return sendJson(404, { ok: false, code: "NOT_FOUND", message: "analysis file not found" });
   }
-  return sendJson(200, { ok: true, data: JSON.parse(await Bun.file(filePath).text()) });
+  return sendJson(200, { ok: true, data: analysis });
 }

package/src/ui/server/endpoints/task-save-endpoint.ts

@@ -3,12 +3,11 @@ import path from "node:path";
 
 import { sendJson } from "../utils/http-utils";
 
-export async function handleTaskSave(req: Request): Promise<Response> {
+export async function handleTaskSave(req: Request, root: string): Promise<Response> {
   const body = (await req.json()) as Record<string, unknown>;
   const slug = typeof body["slug"] === "string" ? body["slug"] : "";
   const taskId = typeof body["taskId"] === "string" ? body["taskId"] : "";
   const content = typeof body["content"] === "string" ? body["content"] : "";
-  const root = process.env["PO_ROOT"] ?? process.cwd();
   const taskPath = path.join(root, "pipeline-config", slug, "tasks", `${taskId}.md`);
   await mkdir(path.dirname(taskPath), { recursive: true });
   await Bun.write(taskPath, content);

package/src/ui/server/endpoints/upload-endpoints.ts

@@ -1,21 +1,14 @@
-import { mkdir } from "node:fs/promises";
-import path from "node:path";
-
 import { parseMultipartFormData, sendJson } from "../utils/http-utils";
 import { extractSeedZip } from "../zip-utils";
 import { createErrorResponse } from "../config-bridge";
 import { Constants } from "../config-bridge-node";
-import { resolveWithin } from "../utils/path-containment";
+import { submitUploadedSeed } from "../../../core/job-submission.ts";
 
 export interface SeedUploadResult {
   seedObject: Record<string, unknown>;
   artifacts?: Array<{ filename: string; content: Uint8Array }>;
 }
 
-function nextJobId(): string {
-  return `job-${Date.now()}`;
-}
-
 export async function normalizeSeedUpload(req: Request): Promise<SeedUploadResult> {
   const contentType = req.headers.get("content-type") ?? "";
   if (contentType.includes("application/json")) {
@@ -34,39 +27,11 @@ export async function handleSeedUploadDirect(
   dataDir: string,
   artifacts: Array<{ filename: string; content: Uint8Array }> = [],
 ): Promise<Response> {
-  const jobId = nextJobId();
-  const pipelineData = path.join(dataDir, "pipeline-data");
-  const pendingDir = path.join(pipelineData, "pending");
-
-  // Stage artifacts under staging/{jobId}/ (before the trigger file).
-  // The orchestrator owns current/{jobId}/ and moves staged artifacts into
-  // current/{jobId}/files/artifacts/ during promotion.
-  if (artifacts.length > 0) {
-    const stagingJobDir = path.join(pipelineData, "staging", jobId);
-
-    for (const artifact of artifacts) {
-      if (resolveWithin(stagingJobDir, artifact.filename) === null) {
-        return sendJson(400, createErrorResponse(Constants.ERROR_CODES.BAD_REQUEST, `unsafe artifact path: ${artifact.filename}`));
-      }
-    }
-
-    for (const artifact of artifacts) {
-      const resolved = resolveWithin(stagingJobDir, artifact.filename)!;
-      await mkdir(path.dirname(resolved), { recursive: true });
-      await Bun.write(resolved, artifact.content);
-    }
+  const result = await submitUploadedSeed({ root: dataDir, seedObject, artifacts });
+  if (!result.success) {
+    return sendJson(400, createErrorResponse(Constants.ERROR_CODES.BAD_REQUEST, result.message));
   }
-
-  // Write the seed to pending/ as the trigger file for the orchestrator.
-  // The orchestrator watches pending/*.json and handles the full lifecycle:
-  // move to current/, write tasks-status.json, and spawn the pipeline runner.
-  await mkdir(pendingDir, { recursive: true });
-  await Bun.write(
-    path.join(pendingDir, `${jobId}-seed.json`),
-    JSON.stringify(seedObject, null, 2),
-  );
-
-  return sendJson(201, { ok: true, data: { jobId } });
+  return sendJson(201, { ok: true, data: { jobId: result.jobId } });
 }
 
 export async function handleSeedUpload(req: Request, dataDir: string): Promise<Response> {

package/src/ui/server/index.ts

@@ -1,7 +1,8 @@
 import path from "node:path";
 
-import { getPipelineDataDir } from "../../config/paths";
-import { getOrchestratorConfig } from "../../core/config";
+import { emitSseEvent, type SseEvent } from "../../config/sse-events.ts";
+import { getPipelineDataDir, resolveWorkspaceRoot } from "../../config/paths";
+import { getConfig, getOrchestratorConfig } from "../../core/config";
 import { loadEnvironment } from "../../core/environment";
 import { getConcurrencyRuntimePaths } from "../../core/job-concurrency";
 import { createLogger } from "../../core/logger";
@@ -19,7 +20,8 @@ import { sseRegistry } from "./sse-registry";
 const logger = createLogger("ui-server");
 
 export interface ServerOptions {
-  dataDir: string;
+  /** Workspace root (not the `pipeline-data` subdir); omitted values fall back to `PO_ROOT` at boot. */
+  dataDir?: string;
   port?: number;
 }
 
@@ -62,8 +64,8 @@ export async function initializeWatcher(dataDir: string): Promise<void> {
   );
 }
 
-export function createServer(dataDir?: string): { fetch: (req: Request) => Promise<Response> } {
-  const resolvedDataDir = dataDir ?? process.env["PO_ROOT"] ?? process.cwd();
+export function createServer(dataDir: string): { fetch: (req: Request) => Promise<Response> } {
+  const resolvedDataDir = dataDir;
   const rawOrigins = process.env["PO_CORS_ORIGINS"];
   const allowNull = process.env["PO_CORS_ALLOW_NULL_ORIGIN"];
   const cors = parseCorsConfig(rawOrigins, allowNull === "1" || allowNull === "true");
@@ -72,18 +74,21 @@ export function createServer(dataDir?: string): { fetch: (req: Request) => Promi
 }
 
 export async function startServer(options: ServerOptions): Promise<ServerHandle> {
-  if (process.env["NODE_ENV"] !== "test" && !process.env["PO_ROOT"]) {
-    throw new Error("PO_ROOT is required in non-test environments");
-  }
+  const root = resolveWorkspaceRoot(options.dataDir);
 
-  await loadEnvironment({ rootDir: options.dataDir });
-  initPATHS(options.dataDir);
+  await loadEnvironment({ rootDir: root });
+  getConfig();
+  initPATHS(root);
 
   const port = options.port ?? 4000;
-  const app = createServer(options.dataDir);
+  const app = createServer(root);
 
   let heartbeat: ReturnType<typeof setInterval> | null = setInterval(() => {
-    sseRegistry.broadcast("heartbeat", { ok: true, timestamp: new Date().toISOString() });
+    const event: SseEvent = {
+      type: "heartbeat",
+      data: { ok: true, timestamp: new Date().toISOString() },
+    };
+    emitSseEvent(sseRegistry, event);
   }, 30_000);
 
   let server: Bun.Server<undefined> | null = null;
@@ -112,7 +117,7 @@ export async function startServer(options: ServerOptions): Promise<ServerHandle>
   ]);
   await startup;
   try {
-    await initializeWatcher(options.dataDir);
+    await initializeWatcher(root);
   } catch (error) {
     if (heartbeat) clearInterval(heartbeat);
     heartbeat = null;
@@ -164,7 +169,7 @@ if (
   process.argv[1] !== process.execPath &&
   import.meta.url === Bun.pathToFileURL(process.argv[1]).href
 ) {
-  const dataDir = process.env["PO_ROOT"] ?? process.cwd();
+  const dataDir = process.env["PO_ROOT"];
   startServer({ dataDir }).catch((err) => {
     console.error("Failed to start server:", err);
     process.exit(1);

package/src/ui/server/job-reader.ts

@@ -1,9 +1,12 @@
+import { join } from "node:path";
+
 import type { ErrorEnvelope } from "./config-bridge";
 import {
   Constants,
   createErrorResponse,
   getTasksStatusPath,
   isLocked,
+  resolvePipelinePaths,
   validateJobId,
 } from "./config-bridge-node";
 import { getFileReadingStats, readFileWithRetry } from "./file-reader";
@@ -30,13 +33,22 @@ export interface JobReadingStats {
 
 const READ_LOCATIONS = ["current", "complete"] as const;
 
-export async function readJob(jobId: string): Promise<JobReadResult> {
+function getTasksStatusPathForRoot(
+  jobId: string,
+  location: (typeof READ_LOCATIONS)[number],
+  root?: string,
+): string {
+  if (root === undefined) return getTasksStatusPath(jobId, location);
+  return join(resolvePipelinePaths(root)[location], jobId, "tasks-status.json");
+}
+
+export async function readJob(jobId: string, root?: string): Promise<JobReadResult> {
   if (!validateJobId(jobId)) {
     return { ...createErrorResponse(Constants.ERROR_CODES.BAD_REQUEST, "invalid job id"), jobId, location: "" };
   }
 
   for (const location of READ_LOCATIONS) {
-    const path = getTasksStatusPath(jobId, location);
+    const path = getTasksStatusPathForRoot(jobId, location, root);
     const result = await readFileWithRetry(path);
     if (!result.ok) {
       if (result.code === Constants.ERROR_CODES.NOT_FOUND) continue;

package/src/ui/server/router.ts

@@ -1,6 +1,8 @@
 import path from "node:path";
 
+import { resolveUnderRoot } from "../../utils/path-containment";
 import { embeddedAssets } from "./embedded-assets";
+import type { EmbeddedAssetEntry } from "./embedded-assets";
 import { handleConcurrencyStatus } from "./endpoints/concurrency-endpoint";
 import { handleCreatePipeline } from "./endpoints/create-pipeline-endpoint";
 import { handleTaskFile, handleTaskFileList } from "./endpoints/file-endpoints";
@@ -38,6 +40,7 @@ interface Route {
 }
 
 interface RouterOptions {
+  /** Workspace root (not the `pipeline-data` subdir). The CLI transport ensures this is set; the boot function asserts. */
   dataDir: string;
   distDir?: string;
   cors?: CorsConfig;
@@ -49,6 +52,12 @@ function normalizeParams(groups: Record<string, string | undefined>): Record<str
   );
 }
 
+function responseFromEmbedded(entry: EmbeddedAssetEntry): Response {
+  return new Response(Bun.file(entry.path), {
+    headers: { "Content-Type": entry.mime },
+  });
+}
+
 export function createRouter(options: RouterOptions): {
   addRoute(method: string, path: string, handler: RouteHandler): void;
   handle(req: Request): Promise<Response>;
@@ -64,11 +73,14 @@ export function createRouter(options: RouterOptions): {
   const serveAsset = async (pathname: string): Promise<Response | null> => {
     const embedded = embeddedAssets[pathname];
     if (embedded) {
-      return new Response(Bun.file(embedded.path), { headers: { "Content-Type": embedded.mime } });
+      return responseFromEmbedded(embedded);
     }
 
-    const diskPath = pathname === "/" ? path.join(distDir, "index.html") : path.join(distDir, pathname);
-    if (await Bun.file(diskPath).exists()) {
+    const diskPath = resolveUnderRoot(
+      distDir,
+      pathname === "/" ? "index.html" : pathname.replace(/^\/+/, ""),
+    );
+    if (diskPath !== null && (await Bun.file(diskPath).exists())) {
       return new Response(Bun.file(diskPath), { headers: { "Content-Type": getMimeType(diskPath) } });
     }
 
@@ -77,6 +89,11 @@ export function createRouter(options: RouterOptions): {
       return new Response(Bun.file(indexPath), { headers: { "Content-Type": "text/html" } });
     }
 
+    const shell = embeddedAssets["/"];
+    if (shell) {
+      return responseFromEmbedded(shell);
+    }
+
     return null;
   };
 
@@ -87,17 +104,17 @@ export function createRouter(options: RouterOptions): {
   addRoute("POST", "/api/jobs/:jobId/stop", (req, params) => handleJobStop(req, params["jobId"]!, options.dataDir));
   addRoute("POST", "/api/jobs/:jobId/rescan", (req, params) => handleJobRescan(req, params["jobId"]!, options.dataDir));
   addRoute("POST", "/api/jobs/:jobId/tasks/:taskId/start", (req, params) => handleTaskStart(req, params["jobId"]!, params["taskId"]!, options.dataDir));
-  addRoute("GET", "/api/jobs/:jobId/tasks/:taskId/files", (req, params) => handleTaskFileList(req, params["jobId"]!, params["taskId"]!));
-  addRoute("GET", "/api/jobs/:jobId/tasks/:taskId/file", (req, params) => handleTaskFile(req, params["jobId"]!, params["taskId"]!));
+  addRoute("GET", "/api/jobs/:jobId/tasks/:taskId/files", (req, params) => handleTaskFileList(req, params["jobId"]!, params["taskId"]!, options.dataDir));
+  addRoute("GET", "/api/jobs/:jobId/tasks/:taskId/file", (req, params) => handleTaskFile(req, params["jobId"]!, params["taskId"]!, options.dataDir));
   addRoute("GET", "/api/pipelines", () => handlePipelinesList());
   addRoute("GET", "/api/pipelines/:slug", (_req, params) => handlePipelineTypeDetail(params["slug"]!));
-  addRoute("POST", "/api/pipelines", (req) => handleCreatePipeline(req));
-  addRoute("POST", "/api/pipelines/:slug/analyze", (req, params) => handlePipelineAnalysis(req, params["slug"]!));
+  addRoute("POST", "/api/pipelines", (req) => handleCreatePipeline(req, options.dataDir));
+  addRoute("POST", "/api/pipelines/:slug/analyze", (req, params) => handlePipelineAnalysis(req, params["slug"]!, options.dataDir));
   addRoute("GET", "/api/pipelines/:slug/artifacts", (req, params) => handlePipelineArtifacts(req, params["slug"]!));
-  addRoute("GET", "/api/pipelines/:slug/tasks/:taskId/analysis", (req, params) => handleTaskAnalysis(req, params["slug"]!, params["taskId"]!));
-  addRoute("GET", "/api/pipelines/:slug/schemas/:filename", (req, params) => handleSchemaFile(req, params["slug"]!, params["filename"]!));
+  addRoute("GET", "/api/pipelines/:slug/tasks/:taskId/analysis", (req, params) => handleTaskAnalysis(req, params["slug"]!, params["taskId"]!, options.dataDir));
+  addRoute("GET", "/api/pipelines/:slug/schemas/:filename", (req, params) => handleSchemaFile(req, params["slug"]!, params["filename"]!, options.dataDir));
   addRoute("POST", "/api/ai/task-plan", (req) => handleTaskPlan(req));
-  addRoute("POST", "/api/tasks/create", (req) => handleTaskSave(req));
+  addRoute("POST", "/api/tasks/create", (req) => handleTaskSave(req, options.dataDir));
   addRoute("GET", "/api/state", () => handleApiState());
   addRoute("GET", "/api/meta", () => handleMeta());
   addRoute("GET", "/api/concurrency", () => handleConcurrencyStatus(options.dataDir));
@@ -150,6 +167,12 @@ export function createRouter(options: RouterOptions): {
         return extraHeaders ? decorateHeaders(response, extraHeaders) : response;
       }
 
+      if (url.pathname.startsWith("/api/")) {
+        const notFound = sendJson(404, { ok: false, code: "NOT_FOUND", message: "route not found" });
+        const extraHeaders = corsHeadersFor(origin, host, cors);
+        return extraHeaders ? decorateHeaders(notFound, extraHeaders) : notFound;
+      }
+
       const asset = await serveAsset(url.pathname);
       if (asset) {
         const extraHeaders = corsHeadersFor(origin, host, cors);

package/src/ui/server/sse-broadcast.ts

@@ -1,3 +1,4 @@
+import { emitSseEvent, type SseEvent } from "../../config/sse-events.ts";
 import { createLogger } from "../../core/logger";
 import { sseRegistry } from "./sse-registry";
 
@@ -20,6 +21,8 @@ function parseChange(change: ChangeLike): ChangeLike & { jobId?: string; lifecyc
   return { ...change, lifecycle: match[1], jobId: match[2] };
 }
 
+type StateChangeData = Extract<SseEvent, { type: "state:change" }>["data"];
+
 export function broadcastStateUpdate(currentState: StateLike): void {
   try {
     const prioritized = currentState.recentChanges.find((change) =>
@@ -27,11 +30,19 @@ export function broadcastStateUpdate(currentState: StateLike): void {
     );
 
     if (prioritized) {
-      sseRegistry.broadcast("state:change", parseChange(prioritized));
-      return;
+      const parsed = parseChange(prioritized);
+      if (typeof parsed.jobId === "string") {
+        const data: StateChangeData = { ...parsed, jobId: parsed.jobId };
+        emitSseEvent(sseRegistry, { type: "state:change", data });
+        return;
+      }
     }
 
-    sseRegistry.broadcast("state:summary", { changeCount: currentState.changeCount });
+    const event: SseEvent = {
+      type: "state:summary",
+      data: { changeCount: currentState.changeCount },
+    };
+    emitSseEvent(sseRegistry, event);
   } catch (error) {
     try {
       logger.error("failed to broadcast state update", error);

package/src/ui/server/sse-enhancer.ts

@@ -1,8 +1,12 @@
+import { emitSseEvent, type JobWire, type SseEvent } from "../../config/sse-events.ts";
 import { transformJobListForAPI } from "../state/transformers/list-transformer";
 import { transformJobStatus } from "../state/transformers/status-transformer";
 import { Constants } from "./config-bridge-node";
 import { readJob, type JobReadResult } from "./job-reader";
 import { sseRegistry, type SSERegistry } from "./sse-registry";
+import { createLogger } from "../../core/logger";
+
+const logger = createLogger("ui-server-sse-enhancer");
 
 export interface SSEEnhancerOptions {
   readJobFn: (jobId: string) => Promise<JobReadResult>;
@@ -29,8 +33,14 @@ export function createSSEEnhancer(options: SSEEnhancerOptions): SSEEnhancer {
     const transformed = transformJobStatus(result.data, jobId, result.location);
     if (!transformed) return;
     const [apiJob] = transformJobListForAPI([transformed], { includePipelineMetadata: true });
-    options.sseRegistry.broadcast(seen.has(jobId) ? "job:updated" : "job:created", apiJob);
-    seen.add(jobId);
+    if (!apiJob) return;
+    const type: SseEvent["type"] = seen.has(jobId) ? "job:updated" : "job:created";
+    try {
+      emitSseEvent(options.sseRegistry, { type, data: apiJob as JobWire });
+      seen.add(jobId);
+    } catch (error) {
+      logger.error(`failed to emit ${type} for job ${jobId}`, error);
+    }
   };
 
   return {

package/src/ui/state/__tests__/schema-loader.test.ts

@@ -19,7 +19,17 @@ describe("schema-loader", () => {
     resetConfig();
     await Bun.write(
       registryPath,
-      JSON.stringify({ pipelines: { demo: { configDir: "pipeline-config/demo", tasksDir: "tasks/demo" } } }),
+      JSON.stringify({
+        version: 1,
+        pipelines: {
+          demo: {
+            name: "Demo",
+            description: "demo pipeline",
+            configDir: "pipeline-config/demo",
+            tasksDir: "tasks/demo",
+          },
+        },
+      }),
     );
     await Bun.write(path.join(pipelineDir, "pipeline.json"), JSON.stringify({ slug: "demo" }));
   });

package/src/ui/state/__tests__/snapshot.test.ts

@@ -1,6 +1,26 @@
-import { describe, expect, it, vi } from "vitest";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { initPATHS, resetPATHS } from "../../server/config-bridge-node";
 import { buildSnapshotFromFilesystem, composeStateSnapshot } from "../snapshot";
+import type { CanonicalJob, JobReadResult } from "../types";
+
+const tempRoots: string[] = [];
+
+async function makeTempRoot(): Promise<string> {
+  const root = await Bun.$`mktemp -d ${join(tmpdir(), "snapshot-XXXXXX")}`.text();
+  const trimmed = root.trim();
+  tempRoots.push(trimmed);
+  return trimmed;
+}
+
+afterEach(async () => {
+  resetPATHS();
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
 
 describe("snapshot", () => {
   it("composes default snapshots and extracts ids from variant fields", () => {
@@ -17,17 +37,22 @@ describe("snapshot", () => {
   });
 
   it("builds a sorted deduplicated filesystem snapshot from injected deps", async () => {
-    const readJob = vi.fn(async (jobId: string, location: string) => ({
-      ok: true,
-      jobId,
-      location,
-      data: {
-        title: `${jobId}-${location}`,
-        createdAt: "2024-01-01T00:00:00.000Z",
-        updatedAt: location === "current" ? "2024-02-01T00:00:00.000Z" : "2024-01-15T00:00:00.000Z",
-        tasks: { a: { state: location === "current" ? "running" : "done" } },
-      },
-    }));
+    const readLocations = ["current", "current", "complete"] as const;
+    let readIndex = 0;
+    const readJob = vi.fn(async (jobId: string) => {
+      const location = readLocations[readIndex++] ?? "current";
+      return {
+        ok: true,
+        jobId,
+        location,
+        data: {
+          title: `${jobId}-${location}`,
+          createdAt: "2024-01-01T00:00:00.000Z",
+          updatedAt: location === "current" ? "2024-02-01T00:00:00.000Z" : "2024-01-15T00:00:00.000Z",
+          tasks: { a: { state: location === "current" ? "running" : "done" } },
+        },
+      };
+    });
 
     const snapshot = await buildSnapshotFromFilesystem({
       listAllJobs: () => ({ current: ["job-1", "job-2"], complete: ["job-1"] }),
@@ -45,14 +70,45 @@ describe("snapshot", () => {
     });
   });
 
+  it("builds the default filesystem snapshot with the real job reader", async () => {
+    const root = await makeTempRoot();
+    initPATHS(root);
+
+    const jobDir = join(root, "pipeline-data", "current", "job-1");
+    await mkdir(jobDir, { recursive: true });
+    await writeFile(
+      join(jobDir, "tasks-status.json"),
+      JSON.stringify({
+        jobId: "job-1",
+        name: "Job 1",
+        tasks: { research: { state: "done" } },
+        createdAt: "2024-01-01T00:00:00.000Z",
+        updatedAt: "2024-02-01T00:00:00.000Z",
+      }),
+    );
+
+    const snapshot = await buildSnapshotFromFilesystem({
+      now: () => new Date("2024-03-01T00:00:00.000Z"),
+    });
+
+    expect(snapshot.jobs).toEqual([
+      expect.objectContaining({
+        jobId: "job-1",
+        title: "Job 1",
+        location: "current",
+      }),
+    ]);
+    expect(snapshot.meta.lastUpdated).toBe("2024-03-01T00:00:00.000Z");
+  });
+
   it("catches individual job read failures and continues with successful reads", async () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const readJob = vi.fn(async (jobId: string, location: string) => {
+    const readJob = vi.fn(async (jobId: string) => {
       if (jobId === "bad-job") throw new Error("disk read failed");
       return {
         ok: true,
         jobId,
-        location,
+        location: "current",
         data: { title: jobId, tasks: { a: { state: "done" } }, createdAt: "2024-01-01T00:00:00.000Z" },
       };
     });
@@ -81,4 +137,54 @@ describe("snapshot", () => {
       }),
     ).rejects.toThrow(/unavailable/);
   });
+
+  it("sorts snapshot jobs with failed (former error) priority first", async () => {
+    const statusByJobId: Record<string, CanonicalJob["status"]> = {
+      "job-failed": "failed",
+      "job-running": "running",
+      "job-complete": "complete",
+      "job-pending": "pending",
+    };
+    const transformMultipleJobs = vi.fn((results: JobReadResult[]): CanonicalJob[] =>
+      results.map((result) => ({
+        id: result.jobId,
+        jobId: result.jobId,
+        name: result.jobId,
+        title: result.jobId,
+        status: statusByJobId[result.jobId] ?? "pending",
+        progress: 0,
+        createdAt: "2024-01-01T00:00:00.000Z",
+        updatedAt: "2024-01-01T00:00:00.000Z",
+        location: result.location,
+        tasks: {},
+        files: {},
+        costs: {},
+      })),
+    );
+
+    const snapshot = await buildSnapshotFromFilesystem({
+      listAllJobs: () => ({
+        current: ["job-pending", "job-running", "job-failed", "job-complete"],
+        complete: [],
+      }),
+      readJob: async (jobId) => ({ ok: true, jobId, location: "current", data: {} }),
+      transformMultipleJobs,
+      now: () => new Date("2024-03-01T00:00:00.000Z"),
+    });
+
+    expect(transformMultipleJobs).toHaveBeenCalledTimes(1);
+    expect(snapshot.jobs.map((job) => job.jobId)).toEqual([
+      "job-failed",
+      "job-running",
+      "job-complete",
+      "job-pending",
+    ]);
+    expect(snapshot.jobs.map((job) => job.status)).toEqual([
+      "failed",
+      "running",
+      "complete",
+      "pending",
+    ]);
+    expect(snapshot.jobs[0]?.jobId).toBe("job-failed");
+  });
 });