@ryanfw/prompt-orchestration-pipeline 1.3.3 → 1.3.5

package/docs/http-api.md

@@ -81,7 +81,10 @@ or on error:
 | `forbidden_origin` | 403 | Cross-origin mutation rejected |
 | `status_unavailable` | 500 | Job status file unreadable |
 | `no_pending_gate` | 409 | Job has no pending gate decision |
+| `INVALID_JSON` | 409 | Job status JSON is invalid |
+| `STATUS_CORRUPT` | 409 | Job status file is corrupt |
 | `FS_ERROR` | 500 | Filesystem operation failed |
+| `BAD_PATH` | 400 | Task analysis path is invalid |
 | `BAD_REQUEST` | 400 | Malformed request body |
 | `NOT_FOUND` | 404 | Route or resource not found |
 
@@ -203,11 +206,21 @@ Clients should treat a gap longer than the keep-alive interval as a potential di
 
 | Event | Data Shape | Description |
 |-------|-----------|-------------|
-| `state:change` | `{ jobId, changeType, ... }` | A job's state has changed |
-| `state:summary` | `{ changeCount }` | Summary of accumulated state changes |
-| `job:created` | `JobSummary` | A new job was detected |
-| `job:updated` | `JobSummary` | An existing job was updated |
+| `state:change` | `{ jobId, path }` | A job's state file changed; the `jobId` is derived from the changed path |
+| `state:summary` | `{ changeCount }` | Summary of accumulated state changes when no per-job change is prioritized |
+| `job:created` | `JobSummary` | A new job was detected (summary granularity; see Caveat below) |
+| `job:updated` | `JobSummary` | An existing job was updated (summary granularity; see Caveat below) |
+| `job:removed` | `{ jobId }` | A job was removed from a watched location |
 | `heartbeat` | `{ ok, timestamp }` | Application-level heartbeat (distinct from the keep-alive comment) |
+| `seed:uploaded` | `{}` | A seed was uploaded; clients should refetch the job list |
+
+The keep-alive comment (`: keep-alive`) sent on a fixed interval is **not** an application event;
+clients must not treat it as one. Unknown event types and unknown fields within a known event
+are tolerated by the contract; clients should ignore them. `task:updated`, `status:changed`,
+bare `state`, and `message` are **not** part of the browser-facing contract and are not
+emitted on `/api/events`. `job:created` and `job:updated` carry summary-granularity
+`JobSummary` data; deep per-task detail (costs, files, per-stage state) continues to arrive
+via the existing `state:change` → refetch path.
 
 ### Job Filtering
 

package/docs/pop-task-guide.md

@@ -209,6 +209,7 @@ export const inference = async ({ runAgent, io, data, flags }) => {
     // timeoutMs?: number     // optional wall-clock cap
     // idleTimeoutMs?: number // optional no-output cap
     // captureDiff?: boolean  // capture a git diff as 'agent.patch'
+    // onEvent?: (event) => {} // observe adapter harness events during the run
   });
 
   if (!result.ok) {
@@ -226,6 +227,13 @@ By default (`io` is `true`) the agent shares the task's file I/O: it can call th
 task sees, and its `agent-result.md` is written automatically. Token usage and
 cost flow into the job status like any other LLM call.
 
+Use `onEvent` when a task needs to observe live harness activity, such as
+assistant messages, tool calls, usage events, or run completion. POP invokes the
+callback after it has buffered the event and appended the redacted debug log, so
+omitting the callback leaves behavior unchanged. The `event.raw` payload comes
+directly from the underlying CLI adapter; treat it as unstable and avoid
+persisting it unless you have considered sensitive values in the raw stream.
+
 **`runAgent` vs `llm`**: use `llm.<provider>.chat()` for a single request/response
 LLM call; use `runAgent()` when you need a tool-using CLI agent that reads and
 writes files over multiple turns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanfw/prompt-orchestration-pipeline",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "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",
@@ -32,7 +32,10 @@
     "ui": "NODE_ENV=development bun --watch src/ui/server/index.ts",
     "ui:dev": "vite",
     "ui:build": "vite build && bun run generate:embedded-assets",
-    "prepack": "bun run ui:build",
+    "verify:package": "bun scripts/verify-package-assets.js",
+    "smoke:packed-consumer": "bun scripts/smoke-packed-consumer.js",
+    "release:check": "bun run ui:build && bun run verify:package && bun run smoke:packed-consumer",
+    "prepack": "bun run ui:build && bun run verify:package",
     "ui:prod": "bun src/ui/server/index.ts",
     "demo:ui": "NODE_ENV=production PO_ROOT=demo bun src/ui/server/index.ts",
     "demo:orchestrator": "PO_ROOT=demo NODE_ENV=production bun -e \"import('./src/core/orchestrator.ts').then(m => m.startOrchestrator({ dataDir: process.env.PO_ROOT || 'demo' })).catch(err => { console.error(err); process.exit(1) })\"",
@@ -42,9 +45,6 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@babel/parser": "^7.28.5",
-    "@babel/traverse": "^7.28.5",
-    "@babel/types": "^7.28.5",
     "@radix-ui/react-progress": "^1.1.7",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-toast": "^1.2.15",

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

@@ -29,8 +29,11 @@ async function scaffoldWorkspace(tmpDir: string): Promise<void> {
   await Bun.write(
     join(tmpDir, "pipeline-config", "registry.json"),
     JSON.stringify({
+      version: 1,
       pipelines: {
         "test-pipeline": {
+          name: "Test Pipeline",
+          description: "test pipeline",
           configDir: join(tmpDir, "pipeline-config", "test-pipeline"),
           tasksDir: join(tmpDir, "pipeline-config", "test-pipeline", "tasks"),
         },
@@ -60,7 +63,7 @@ describe("submitJobWithValidation", () => {
 
   it("writes seed file to pending and returns success", async () => {
     const result = await submitJobWithValidation({
-      dataDir: tmpDir,
+      root: tmpDir,
       seedObject: { pipeline: "test-pipeline" },
     });
 
@@ -79,7 +82,7 @@ describe("submitJobWithValidation", () => {
 
   it("returns seed name as jobName when provided", async () => {
     const result = await submitJobWithValidation({
-      dataDir: tmpDir,
+      root: tmpDir,
       seedObject: { pipeline: "test-pipeline", name: "my-job" },
     });
 
@@ -87,74 +90,88 @@ describe("submitJobWithValidation", () => {
     expect((result as SubmitSuccessResult).jobName).toBe("my-job");
   });
 
-  it("rejects non-object seed with message containing 'JSON object'", async () => {
+  it("rejects non-object seed with exact message", async () => {
     const result = await submitJobWithValidation({
-      dataDir: tmpDir,
+      root: tmpDir,
       seedObject: "not an object",
     });
 
     expect(result.success).toBe(false);
-    expect((result as SubmitFailureResult).message).toContain("JSON object");
+    expect((result as SubmitFailureResult).message).toBe("seed must be a JSON object");
   });
 
-  it("rejects array seed with message containing 'JSON object'", async () => {
+  it("rejects array seed with exact message", async () => {
     const result = await submitJobWithValidation({
-      dataDir: tmpDir,
+      root: tmpDir,
       seedObject: [1, 2, 3],
     });
 
     expect(result.success).toBe(false);
-    expect((result as SubmitFailureResult).message).toContain("JSON object");
+    expect((result as SubmitFailureResult).message).toBe("seed must be a JSON object");
   });
 
-  it("rejects null seed with message containing 'JSON object'", async () => {
+  it("rejects null seed with exact message", async () => {
     const result = await submitJobWithValidation({
-      dataDir: tmpDir,
+      root: tmpDir,
       seedObject: null,
     });
 
     expect(result.success).toBe(false);
-    expect((result as SubmitFailureResult).message).toContain("JSON object");
+    expect((result as SubmitFailureResult).message).toBe("seed must be a JSON object");
   });
 
-  it("rejects seed missing pipeline field with message containing 'pipeline'", async () => {
+  it("rejects seed missing pipeline field with exact message", async () => {
     const result = await submitJobWithValidation({
-      dataDir: tmpDir,
+      root: tmpDir,
       seedObject: { name: "my-job" },
     });
 
     expect(result.success).toBe(false);
-    expect((result as SubmitFailureResult).message).toContain("pipeline");
+    expect((result as SubmitFailureResult).message).toBe("seed.pipeline must be a non-empty string");
   });
 
   it("rejects seed with empty pipeline string", async () => {
     const result = await submitJobWithValidation({
-      dataDir: tmpDir,
+      root: tmpDir,
       seedObject: { pipeline: "" },
     });
 
     expect(result.success).toBe(false);
-    expect((result as SubmitFailureResult).message).toContain("pipeline");
+    expect((result as SubmitFailureResult).message).toBe("seed.pipeline must be a non-empty string");
   });
 
-  it("rejects non-existent pipeline slug with message containing 'not found'", async () => {
+  it("rejects non-string pipeline value", async () => {
     const result = await submitJobWithValidation({
-      dataDir: tmpDir,
+      root: tmpDir,
+      seedObject: { pipeline: 123 },
+    });
+
+    expect(result.success).toBe(false);
+    expect((result as SubmitFailureResult).message).toBe("seed.pipeline must be a non-empty string");
+  });
+
+  it("rejects non-existent pipeline slug with exact message", async () => {
+    const result = await submitJobWithValidation({
+      root: tmpDir,
       seedObject: { pipeline: "does-not-exist" },
     });
 
     expect(result.success).toBe(false);
-    expect((result as SubmitFailureResult).message).toContain("not found");
+    expect((result as SubmitFailureResult).message).toBe(
+      "Pipeline 'does-not-exist' not found in registry",
+    );
   });
 
   it("rejects seed with empty name string", async () => {
     const result = await submitJobWithValidation({
-      dataDir: tmpDir,
+      root: tmpDir,
       seedObject: { pipeline: "test-pipeline", name: "" },
     });
 
     expect(result.success).toBe(false);
-    expect((result as SubmitFailureResult).message).toContain("name");
+    expect((result as SubmitFailureResult).message).toBe(
+      "seed.name must be a non-empty string if provided",
+    );
   });
 });
 
@@ -196,7 +213,7 @@ describe("PipelineOrchestrator.getStatus", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const record = await orch.getStatus(jobId);
 
     expect(record.jobId).toBe(jobId);
@@ -220,7 +237,7 @@ describe("PipelineOrchestrator.getStatus", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const record = await orch.getStatus(jobId);
 
     expect(record.jobId).toBe(jobId);
@@ -244,7 +261,7 @@ describe("PipelineOrchestrator.getStatus", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const record = await orch.getStatus("named-job");
 
     expect(record.jobId).toBe(jobId);
@@ -258,7 +275,7 @@ describe("PipelineOrchestrator.getStatus", () => {
       JSON.stringify({ pipeline: "test-pipeline", name: "pending-job" }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const record = await orch.getStatus(jobId);
 
     expect(record.jobId).toBe(jobId);
@@ -268,8 +285,24 @@ describe("PipelineOrchestrator.getStatus", () => {
     expect(record.createdAt).toBeTruthy();
   });
 
+  it("returns pending record for non-UUID seed filename parsed by parseSeedFilename", async () => {
+    const jobId = "my-job";
+    await Bun.write(
+      join(tmpDir, "pipeline-data", "pending", `${jobId}-seed.json`),
+      JSON.stringify({ pipeline: "test-pipeline", name: "my-job" }),
+    );
+
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
+    const record = await orch.getStatus(jobId);
+
+    expect(record.jobId).toBe(jobId);
+    expect(record.jobName).toBe("my-job");
+    expect(record.state).toBe("pending");
+    expect(record.pipeline).toBe("test-pipeline");
+  });
+
   it("throws for nonexistent job with message containing 'not found'", async () => {
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
 
     await expect(orch.getStatus("nonexistent-id")).rejects.toThrow("not found");
   });
@@ -280,7 +313,7 @@ describe("PipelineOrchestrator.getStatus", () => {
     await mkdir(jobDir, { recursive: true });
     await Bun.write(join(jobDir, "tasks-status.json"), "{{{not valid json");
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const record = await orch.getStatus(jobId);
 
     expect(record.jobId).toBe(jobId);
@@ -315,7 +348,7 @@ describe("PipelineOrchestrator.getStatus", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const record = await orch.getStatus(jobId);
 
     expect(record.jobId).toBe(jobId);
@@ -388,7 +421,7 @@ describe("PipelineOrchestrator.listJobs", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const jobs = await orch.listJobs();
 
     expect(jobs.length).toBe(3);
@@ -406,7 +439,7 @@ describe("PipelineOrchestrator.listJobs", () => {
   });
 
   it("returns empty array when all directories are empty", async () => {
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const jobs = await orch.listJobs();
 
     expect(jobs).toEqual([]);
@@ -416,7 +449,7 @@ describe("PipelineOrchestrator.listJobs", () => {
     // Remove all pipeline-data directories
     await rm(join(tmpDir, "pipeline-data"), { recursive: true, force: true });
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const jobs = await orch.listJobs();
 
     expect(jobs).toEqual([]);
@@ -464,7 +497,7 @@ describe("PipelineOrchestrator.listJobs", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const jobs = await orch.listJobs();
 
     expect(jobs.length).toBe(4);
@@ -514,7 +547,7 @@ describe("PipelineOrchestrator.listJobs", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const jobs = await orch.listJobs();
 
     const ids = jobs.map((j) => j.jobId);
@@ -544,7 +577,7 @@ describe("PipelineOrchestrator.listJobs", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const jobs = await orch.listJobs();
 
     const ids = jobs.map((j) => j.jobId);
@@ -573,7 +606,7 @@ describe("PipelineOrchestrator.listJobs", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const getStatusRecord = await orch.getStatus(jobId);
     const listJobsRecords = await orch.listJobs();
     const listJobsRecord = listJobsRecords.find((j) => j.jobId === jobId)!;
@@ -599,7 +632,7 @@ describe("PipelineOrchestrator.listJobs", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const record = await orch.getStatus(jobId);
 
     expect(record.state).toBe("complete");
@@ -621,7 +654,7 @@ describe("PipelineOrchestrator.listJobs", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const jobs = await orch.listJobs();
     const record = jobs.find((j) => j.jobId === jobId)!;
 
@@ -645,13 +678,13 @@ describe("PipelineOrchestrator.listJobs", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     const record = await orch.getStatus(jobId);
 
     expect(record.state).toBe("failed");
   });
 
-  it("listJobs preserves JobView extras (progress, costs)", async () => {
+  it("listJobs preserves JobView extras (costs)", async () => {
     const jobId = "cccc-5555-6666-7777-0005";
     const jobDir = join(tmpDir, "pipeline-data", "current", jobId);
     await mkdir(jobDir, { recursive: true });
@@ -669,12 +702,82 @@ describe("PipelineOrchestrator.listJobs", () => {
       }),
     );
 
-    const orch = new PipelineOrchestrator({ autoStart: false });
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
     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.progress).toBe(0);
     expect(record.costs).toEqual({ usd: 1.23 });
   });
 });
+
+// ─── AC-4: API strict root resolution ─────────────────────────────────────────
+
+describe("API strict root resolution (AC-4)", () => {
+  let tmpDir: string;
+  let savedPoRoot: string | undefined;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "pop-api-strict-test-"));
+    await scaffoldWorkspace(tmpDir);
+    savedPoRoot = process.env["PO_ROOT"];
+    delete process.env["PO_ROOT"];
+  });
+
+  afterEach(async () => {
+    if (savedPoRoot === undefined) {
+      delete process.env["PO_ROOT"];
+    } else {
+      process.env["PO_ROOT"] = savedPoRoot;
+    }
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("PipelineOrchestrator throws when neither root nor PO_ROOT is set", () => {
+    expect(() => new PipelineOrchestrator({ autoStart: false })).toThrow(
+      "Workspace root is required",
+    );
+  });
+
+  it("PipelineOrchestrator succeeds when root is set explicitly", async () => {
+    const orch = new PipelineOrchestrator({ autoStart: false, root: tmpDir });
+    const jobs = await orch.listJobs();
+    expect(jobs).toEqual([]);
+  });
+
+  it("PipelineOrchestrator succeeds when PO_ROOT is set and root is absent", async () => {
+    process.env["PO_ROOT"] = tmpDir;
+    const orch = new PipelineOrchestrator({ autoStart: false });
+    const jobs = await orch.listJobs();
+    expect(jobs).toEqual([]);
+  });
+
+  it("submitJobWithValidation throws when neither root nor PO_ROOT is set", async () => {
+    await expect(
+      submitJobWithValidation({ seedObject: { pipeline: "test-pipeline" } }),
+    ).rejects.toThrow("Workspace root is required");
+  });
+
+  it("submitJobWithValidation succeeds when root is set explicitly", async () => {
+    const result = await submitJobWithValidation({
+      root: tmpDir,
+      seedObject: { pipeline: "test-pipeline" },
+    });
+    expect(result.success).toBe(true);
+    const pendingFiles = await readdir(join(tmpDir, "pipeline-data", "pending"));
+    const seedFile = pendingFiles.find((f) => f.endsWith("-seed.json"));
+    expect(seedFile).toBeDefined();
+  });
+
+  it("submitJobWithValidation succeeds when PO_ROOT is set and root is absent", async () => {
+    process.env["PO_ROOT"] = tmpDir;
+    const result = await submitJobWithValidation({
+      seedObject: { pipeline: "test-pipeline" },
+    });
+    expect(result.success).toBe(true);
+    const pendingFiles = await readdir(join(tmpDir, "pipeline-data", "pending"));
+    const seedFile = pendingFiles.find((f) => f.endsWith("-seed.json"));
+    expect(seedFile).toBeDefined();
+  });
+});

package/src/api/index.ts

@@ -1,31 +1,19 @@
 import path from "node:path";
-import { mkdir, readdir, rename, stat } from "node:fs/promises";
-import { resolvePipelinePaths, getPendingSeedPath } from "../config/paths";
+import { readdir, stat } from "node:fs/promises";
+import { resolvePipelinePaths, resolveWorkspaceRoot } from "../config/paths";
 import type { PipelinePaths } from "../config/paths";
-import { getPipelineConfig } from "../core/config";
+import { submitSeed } from "../core/job-submission.ts";
+import type { SubmitResult } from "../core/job-submission.ts";
 import { normalizeJobView } from "../core/job-view";
 import type { JobView } from "../core/job-view";
-import { SEED_PATTERN } from "../core/orchestrator";
+import { parseSeedFilename } from "../core/seed-naming.ts";
 import { readJobStatusResult, STATUS_FILENAME, type StatusReadResult } from "../core/status-writer";
 
-/** Result of a successful job submission. */
-export interface SubmitSuccessResult {
-  success: true;
-  jobId: string;
-  jobName: string;
-}
-
-/** Result of a failed job submission. */
-export interface SubmitFailureResult {
-  success: false;
-  message: string;
-}
-
-export type SubmitResult = SubmitSuccessResult | SubmitFailureResult;
+export type { SubmitResult, SubmitSuccessResult, SubmitFailureResult } from "../core/job-submission.ts";
 
 /** Options for submitJobWithValidation. */
 export interface SubmitJobOptions {
-  dataDir: string;
+  root?: string;
   seedObject: unknown;
 }
 
@@ -47,28 +35,11 @@ export interface JobStatusRecord {
 /** Orchestrator construction options. */
 export interface OrchestratorOptions {
   autoStart: boolean;
+  root?: string;
 }
 
 // ─── Private Helpers ──────────────────────────────────────────────────────────
 
-async function atomicWriteJson(filePath: string, data: unknown): Promise<void> {
-  const tmp = `${filePath}.${Date.now()}.tmp`;
-  await Bun.write(tmp, JSON.stringify(data, null, 2));
-  await rename(tmp, filePath);
-}
-
-function assertSeedObject(value: unknown): asserts value is Record<string, unknown> {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error("seed must be a JSON object");
-  }
-}
-
-function assertPipelineSlug(value: unknown): asserts value is string {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new Error("seed.pipeline must be a non-empty string");
-  }
-}
-
 async function safeReaddir(dirPath: string): Promise<string[]> {
   try {
     return await readdir(dirPath);
@@ -147,44 +118,8 @@ async function readStatusForApi(jobDir: string, label: string): Promise<StatusRe
 export async function submitJobWithValidation(
   opts: SubmitJobOptions,
 ): Promise<SubmitResult> {
-  const rootDir = path.resolve(opts.dataDir);
-
-  try {
-    assertSeedObject(opts.seedObject);
-    assertPipelineSlug(opts.seedObject["pipeline"]);
-  } catch (err) {
-    return { success: false, message: (err as Error).message };
-  }
-
-  const seed = opts.seedObject as Record<string, unknown>;
-
-  if (seed["name"] !== undefined) {
-    if (typeof seed["name"] !== "string" || seed["name"].length === 0) {
-      return { success: false, message: "seed.name must be a non-empty string if provided" };
-    }
-  }
-
-  try {
-    getPipelineConfig(seed["pipeline"] as string, rootDir);
-  } catch (err) {
-    return { success: false, message: (err as Error).message };
-  }
-
-  const jobId = crypto.randomUUID();
-  const jobName = (typeof seed["name"] === "string" && seed["name"].length > 0)
-    ? seed["name"]
-    : jobId;
-  const pendingPath = getPendingSeedPath(rootDir, jobId);
-
-  await mkdir(path.dirname(pendingPath), { recursive: true });
-
-  try {
-    await atomicWriteJson(pendingPath, opts.seedObject);
-  } catch (err) {
-    throw new Error(`failed to write seed file for job ${jobId}: ${(err as Error).message}`);
-  }
-
-  return { success: true, jobId, jobName };
+  const rootDir = resolveWorkspaceRoot(opts.root);
+  return submitSeed({ root: rootDir, seedObject: opts.seedObject });
 }
 
 export class PipelineOrchestrator {
@@ -194,7 +129,7 @@ export class PipelineOrchestrator {
 
   constructor(opts: OrchestratorOptions) {
     this.autoStart = opts.autoStart;
-    this.root = path.resolve(process.env["PO_ROOT"] ?? process.cwd());
+    this.root = resolveWorkspaceRoot(opts.root);
     this.paths = resolvePipelinePaths(this.root);
   }
 
@@ -232,10 +167,8 @@ export class PipelineOrchestrator {
     // 3. Pending fallback
     const pendingFiles = await safeReaddir(this.paths.pending);
     for (const file of pendingFiles) {
-      const match = file.match(SEED_PATTERN);
-      if (!match) continue;
-      const id = match[1]!;
-      if (id !== jobName) continue;
+      const id = parseSeedFilename(file);
+      if (id === null || id !== jobName) continue;
 
       const filePath = path.join(this.paths.pending, file);
       const seed = await readJsonFile<Record<string, unknown>>(filePath);
@@ -258,9 +191,8 @@ export class PipelineOrchestrator {
     // Pending jobs
     const pendingFiles = await safeReaddir(this.paths.pending);
     for (const file of pendingFiles) {
-      const match = file.match(SEED_PATTERN);
-      if (!match) continue;
-      const id = match[1]!;
+      const id = parseSeedFilename(file);
+      if (id === null) continue;
       const filePath = path.join(this.paths.pending, file);
       try {
         const seed = await readJsonFile<Record<string, unknown>>(filePath);