@ryanfw/prompt-orchestration-pipeline 1.3.2 → 1.3.4

package/src/core/pipeline-runner.ts

@@ -6,8 +6,8 @@ import { getConfig, getPipelineConfig } from "./config";
 import { validatePipelineOrThrow } from "./validation";
 import { loadFreshModule } from "./module-loader";
 import { atomicWrite, writeJobStatus, flushJobStatus, StatusCorruptError, type GateInfo } from "./status-writer";
-import { decideTransition } from "./lifecycle-policy";
-import { runPipeline } from "./task-runner";
+import { areDependenciesSatisfied, decideTransition } from "./lifecycle-policy";
+import { runPipeline, recordAgentUsage } from "./task-runner";
 import type { AuditLogEntry, PipelineResult } from "./task-runner";
 import type { TaskStateValue } from "../config/statuses";
 import { ensureTaskSymlinkBridge } from "./symlink-bridge";
@@ -19,6 +19,8 @@ import { TaskState, normalizeTaskState } from "../config/statuses";
 import { releaseJobSlot } from "./job-concurrency";
 import { ControlValidationError, parseControlFile, validateControlDirectives, type ControlDirectives } from "./control";
 import { appendRunEvent } from "./run-events";
+import { resolveWorkspaceRoot } from "../config/paths";
+import { resolveTaskRegistryPath } from "../config/pipeline-registry";
 import {
   getTaskName,
   normalizePipelineTasks,
@@ -136,7 +138,7 @@ export interface ResolvedJobConfig {
   pipelineSlug: string;
   pipelineJsonPath: string;
   tasksDir: string;
-  taskRegistryPath: string; // Fully resolved module path: PO_TASK_REGISTRY or join(tasksDir, "index.js")
+  taskRegistryPath: string; // PO_TASK_REGISTRY or resolveTaskRegistryPath(tasksDir): prefers index.js, falls back to index.ts
   workDir: string;
   statusPath: string;
   startFromTask: string | null;
@@ -301,6 +303,7 @@ async function applyControlStatus(args: {
     if (args.directives !== null) {
       taskEntry.controlApplied = true;
     }
+    delete taskEntry.controlError;
     delete taskEntry.retrying;
     delete taskEntry.nextRetryAt;
     delete taskEntry.lastRetryError;
@@ -393,40 +396,54 @@ async function applyControlFileIfPresent(args: {
   return { gate };
 }
 
-async function failControlValidation(args: {
+async function haltForInvalidControl(args: {
   workDir: string;
   dataDir: string;
   jobId: string;
   taskName: string;
+  executionTimeMs: number;
+  refinementAttempts: number;
+  endedAt?: string;
   error: ControlValidationError;
-}): Promise<never> {
-  const normalized = normalizeError(args.error);
+}): Promise<void> {
   await appendRunEvent(args.workDir, {
     type: "control_invalid",
     task: args.taskName,
-    message: normalized.message,
+    message: args.error.message,
     at: new Date().toISOString(),
   });
 
   await writeJobStatus(args.workDir, (snapshot) => {
-    snapshot.state = "failed";
+    snapshot.state = "waiting";
     snapshot.current = args.taskName;
     snapshot.currentStage = null;
-    const raw = (snapshot.tasks[args.taskName] ?? {}) as Record<string, unknown>;
-    raw["state"] = TaskState.FAILED;
-    raw["endedAt"] = new Date().toISOString();
-    raw["error"] = { name: normalized.name, message: normalized.message, stack: normalized.stack };
-    raw["failedStage"] = "control";
-    delete raw["stageLogPath"];
-    delete raw["errorContext"];
-    delete raw["retrying"];
-    delete raw["nextRetryAt"];
-    delete raw["lastRetryError"];
-    snapshot.tasks[args.taskName] = raw as typeof snapshot.tasks[string];
+    const taskEntry = (snapshot.tasks[args.taskName] ?? {}) as Record<string, unknown>;
+    taskEntry["state"] = TaskState.DONE;
+    taskEntry["endedAt"] = args.endedAt ?? new Date().toISOString();
+    taskEntry["executionTimeMs"] = args.executionTimeMs;
+    taskEntry["refinementAttempts"] = args.refinementAttempts;
+    taskEntry["controlApplied"] = false;
+    taskEntry["controlError"] = {
+      message: args.error.message,
+      violations: args.error.violations.length > 0 ? args.error.violations : undefined,
+    };
+    delete taskEntry["error"];
+    delete taskEntry["failedStage"];
+    delete taskEntry["stageLogPath"];
+    delete taskEntry["errorContext"];
+    delete taskEntry["retrying"];
+    delete taskEntry["nextRetryAt"];
+    delete taskEntry["lastRetryError"];
+    snapshot.tasks[args.taskName] = taskEntry as typeof snapshot.tasks[string];
+    snapshot.gate = {
+      afterTask: args.taskName,
+      kind: "control_invalid",
+      message: `Control file invalid for ${args.taskName}: ${args.error.message}. Repair tasks/${args.taskName}/control.json and approve to retry.`,
+      requestedAt: new Date().toISOString(),
+    };
   });
 
   await releaseJobSlotBestEffort(args.dataDir, args.jobId);
-  process.exit(1);
 }
 
 async function markControlRecoveryChecked(workDir: string, taskName: string): Promise<void> {
@@ -434,6 +451,7 @@ async function markControlRecoveryChecked(workDir: string, taskName: string): Pr
     const taskEntry = snapshot.tasks[taskName];
     if (!taskEntry || taskEntry.state !== TaskState.DONE || taskEntry.controlApplied === true) return;
     taskEntry.controlApplied = true;
+    delete taskEntry.controlError;
   });
 }
 
@@ -447,6 +465,7 @@ function buildGateInfo(
   if (directivePause) {
     return {
       afterTask: taskName,
+      kind: "approval",
       message: directivePause.message,
       artifacts: directivePause.artifacts,
       requestedAt,
@@ -459,6 +478,7 @@ function buildGateInfo(
   if (selectedEntry.gate === true) {
     return {
       afterTask: taskName,
+      kind: "approval",
       message: defaultMessage,
       requestedAt,
     };
@@ -466,6 +486,7 @@ function buildGateInfo(
 
   return {
     afterTask: taskName,
+    kind: "approval",
     message: selectedEntry.gate.message ?? defaultMessage,
     artifacts: selectedEntry.gate.artifacts,
     requestedAt,
@@ -497,9 +518,8 @@ export function normalizeError(e: unknown): NormalizedError {
   return { message: String(e) };
 }
 
-/** Resolves all runtime configuration for a pipeline job from environment variables and seed.json. */
-export async function resolveJobConfig(jobId: string): Promise<ResolvedJobConfig> {
-  const poRoot = resolve(process.env["PO_ROOT"] ?? process.cwd());
+/** Builds runtime configuration for a pipeline job from a resolved root, environment variables, and seed.json. */
+export async function resolveJobConfig(jobId: string, poRoot: string): Promise<ResolvedJobConfig> {
   const dataDir = process.env["PO_DATA_DIR"] ?? "pipeline-data";
   const currentDir = process.env["PO_CURRENT_DIR"] ?? join(poRoot, dataDir, "current");
   const completeDir = process.env["PO_COMPLETE_DIR"] ?? join(poRoot, dataDir, "complete");
@@ -531,7 +551,7 @@ export async function resolveJobConfig(jobId: string): Promise<ResolvedJobConfig
     pipelineJsonPath = runScopedPipelineJsonPath;
   }
 
-  const taskRegistryPath = process.env["PO_TASK_REGISTRY"] ?? join(tasksDir, "index.js");
+  const taskRegistryPath = process.env["PO_TASK_REGISTRY"] ?? resolveTaskRegistryPath(tasksDir);
   const startFromTask = process.env["PO_START_FROM_TASK"] ?? null;
   const runSingleTask = process.env["PO_RUN_SINGLE_TASK"] === "true";
 
@@ -635,12 +655,13 @@ const RETRY_BACKOFF_MULTIPLIER = 2;
 
 /** Runs a pipeline job end-to-end for the given job ID. */
 export async function runPipelineJob(jobId: string): Promise<void> {
+  getConfig();
   let workDir: string | undefined;
   let activeTaskName: string | null = null;
-  const poRoot = resolve(process.env["PO_ROOT"] ?? process.cwd());
+  const poRoot = resolveWorkspaceRoot();
   let dataDir: string | undefined = resolve(poRoot, process.env["PO_DATA_DIR"] ?? "pipeline-data");
   try {
-  const config = await resolveJobConfig(jobId);
+  const config = await resolveJobConfig(jobId, poRoot);
   workDir = config.workDir;
   dataDir = resolve(config.poRoot, config.dataDir);
   await writePidFile(config.workDir);
@@ -727,13 +748,17 @@ export async function runPipelineJob(jobId: string): Promise<void> {
           } catch (error) {
             if (!(error instanceof ControlValidationError)) throw error;
             activeTaskName = null;
-            await failControlValidation({
+            await haltForInvalidControl({
               workDir: config.workDir,
               dataDir,
               jobId,
               taskName,
+              executionTimeMs: typeof taskStatus?.executionTimeMs === "number" ? taskStatus.executionTimeMs : 0,
+              refinementAttempts: typeof taskStatus?.refinementAttempts === "number" ? taskStatus.refinementAttempts : 0,
+              endedAt: typeof taskStatus?.endedAt === "string" ? taskStatus.endedAt : undefined,
               error,
             });
+            return;
           }
         }
         await loadDoneArtifact(config.workDir, taskName, pipelineArtifacts);
@@ -764,25 +789,21 @@ export async function runPipelineJob(jobId: string): Promise<void> {
     const taskName = selectedEntry.name;
     const taskState = selectedTaskState;
 
-    let predecessorsReady = true;
-    for (const entry of pipelineTasks) {
-      if (entry.name === taskName) break;
-      const state = normalizeTaskState(status.tasks[entry.name]?.state ?? TaskState.PENDING);
-      if (state !== TaskState.DONE && state !== TaskState.SKIPPED) {
-        predecessorsReady = false;
-        break;
-      }
-    }
+    const predecessorStates = pipelineTasks
+      .slice(0, pipelineTasks.findIndex((entry) => entry.name === taskName))
+      .map((entry) => normalizeTaskState(status.tasks[entry.name]?.state ?? TaskState.PENDING));
+    const dependenciesReady = areDependenciesSatisfied(predecessorStates);
 
-    // Check lifecycle policy (bypassed when startFromTask is set)
-    if (!startFromTask) {
-      const decision = decideTransition({ op: "start", taskState, dependenciesReady: predecessorsReady });
-      if (!decision.ok) {
-        throw Object.assign(
-          new Error(`Lifecycle policy blocked task start: ${taskName} (reason: ${decision.reason})`),
-          { httpStatus: 409, error: "unsupported_lifecycle" }
-        );
-      }
+    const decision = decideTransition({
+      op: startFromTask ? "restart" : "start",
+      taskState,
+      dependenciesReady,
+    });
+    if (!decision.ok) {
+      throw Object.assign(
+        new Error(`Lifecycle policy blocked task start: ${taskName} (reason: ${decision.reason})`),
+        { httpStatus: 409, error: "unsupported_lifecycle" }
+      );
     }
 
     // Update status to RUNNING
@@ -823,12 +844,6 @@ export async function runPipelineJob(jobId: string): Promise<void> {
         const agentExecutionTimeMs = Date.now() - agentStartTime;
 
         if (agentResult.ok) {
-          const usageKey = `${agentEntry.harness}:${agentEntry.model ?? "default"}`;
-          const inputTokens = agentResult.usage?.inputTokens ?? 0;
-          const outputTokens = agentResult.usage?.outputTokens ?? 0;
-          const costUsd = agentResult.costUsd ?? 0;
-          const usageTuple = [usageKey, inputTokens, outputTokens, costUsd];
-
           await writeJobStatus(config.workDir, (snapshot) => {
             snapshot.state = "done";
             snapshot.current = null;
@@ -838,7 +853,11 @@ export async function runPipelineJob(jobId: string): Promise<void> {
             taskEntry.endedAt = new Date().toISOString();
             taskEntry.executionTimeMs = agentExecutionTimeMs;
             const usage = (taskEntry.tokenUsage ?? []) as unknown[];
-            usage.push(usageTuple);
+            recordAgentUsage(
+              { harness: agentEntry.harness, model: agentEntry.model },
+              agentResult,
+              (t) => usage.push(t),
+            );
             taskEntry.tokenUsage = usage;
             snapshot.tasks[taskName] = taskEntry;
           });
@@ -850,6 +869,16 @@ export async function runPipelineJob(jobId: string): Promise<void> {
             taskEntry.state = "failed";
             taskEntry.endedAt = new Date().toISOString();
             taskEntry.error = agentResult.error ?? "Agent step failed";
+            recordAgentUsage(
+              { harness: agentEntry.harness, model: agentEntry.model },
+              agentResult,
+              (t) => {
+                const usage = (taskEntry.tokenUsage ?? []) as unknown[];
+                usage.push(t);
+                taskEntry.tokenUsage = usage;
+              },
+              { failed: true },
+            );
             snapshot.tasks[taskName] = taskEntry;
           });
           activeTaskName = null;
@@ -1005,13 +1034,16 @@ export async function runPipelineJob(jobId: string): Promise<void> {
       } catch (error) {
         if (!(error instanceof ControlValidationError)) throw error;
         activeTaskName = null;
-        await failControlValidation({
+        await haltForInvalidControl({
           workDir: config.workDir,
           dataDir,
           jobId,
           taskName,
+          executionTimeMs,
+          refinementAttempts,
           error,
         });
+        return;
       }
 
       if (appliedControl === null) {

package/src/core/redact.ts

@@ -0,0 +1,40 @@
+export const REDACTED = "[REDACTED]";
+
+const SECRET_KEY_PATTERN = /^(authorization|bearer|token|api[-_]?key|apikey|secret|password|x-api-key)$/i;
+
+export interface RedactOptions {
+  secrets?: string[];
+}
+
+export function redactSecrets(value: unknown, options?: RedactOptions): unknown {
+  const secrets = options?.secrets ?? [];
+  const seen = new WeakSet<object>();
+  return redactValue(value, secrets, seen);
+}
+
+function redactString(s: string, secrets: string[]): string {
+  let out = s;
+  for (const secret of secrets) {
+    if (secret === "") continue;
+    out = out.split(secret).join(REDACTED);
+  }
+  return out;
+}
+
+function redactValue(value: unknown, secrets: string[], seen: WeakSet<object>): unknown {
+  if (typeof value === "function") return value;
+  if (value === null) return null;
+  if (typeof value === "string") return redactString(value, secrets);
+  if (typeof value !== "object") return value;
+  if (seen.has(value as object)) return "[Circular]";
+  seen.add(value as object);
+  if (Array.isArray(value)) {
+    return value.map((el) => redactValue(el, secrets, seen));
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([k, v]) => [
+      k,
+      SECRET_KEY_PATTERN.test(k) ? REDACTED : redactValue(v, secrets, seen),
+    ]),
+  );
+}

package/src/core/runner-liveness.ts

@@ -0,0 +1,280 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+
+import { deriveJobStatusFromTasks } from "../config/statuses";
+import { createLogger } from "./logger";
+import { readJobStatusResult, writeJobStatus } from "./status-writer";
+import type { StatusSnapshot } from "./status-writer";
+import { readJobSlotLease, withRuntimeLock } from "./job-concurrency";
+import type { JobSlotLease } from "./job-concurrency";
+
+export const STALE_RUNNING_GRACE_MS = 30_000;
+
+export interface StaleRunningInput {
+  status: StatusSnapshot;
+  pid: number | null;
+  pidAlive: boolean;
+  nowMs: number;
+  staleAfterMs: number;
+}
+
+export type StaleRunningDecision =
+  | { stale: false; reason: "not_running" | "live_pid" | "fresh_status" }
+  | { stale: true; runningTaskId: string | null; ageMs: number };
+
+export type ReconcileSource = "child-exit" | "boot-sweep";
+
+export type ReconcileReason =
+  | "marked-failed"
+  | "not-running"
+  | "no-running-task"
+  | "live-pid"
+  | "live-lease"
+  | "fresh-status"
+  | "unreadable";
+
+export interface ReconcileResult {
+  reconciled: boolean;
+  taskId?: string;
+  reason: ReconcileReason;
+}
+
+export interface ReconcileOptions {
+  dataDir: string;
+  jobId: string;
+  jobDir: string;
+  source: ReconcileSource;
+  lockTimeoutMs: number;
+  staleLeaseTimeoutMs?: number;
+  code?: number | null;
+  signal?: string | null;
+  requireStaleStatus?: boolean;
+  staleAfterMs?: number;
+  now?: () => number;
+  isAlive?: (pid: number) => boolean;
+}
+
+export interface SweepOptions {
+  dataDir: string;
+  currentDir: string;
+  lockTimeoutMs: number;
+  staleLeaseTimeoutMs?: number;
+  staleAfterMs?: number;
+  now?: () => number;
+  isAlive?: (pid: number) => boolean;
+}
+
+export interface SweepResult {
+  scanned: number;
+  reconciled: string[];
+}
+
+export async function readRunnerPid(jobDir: string): Promise<number | null> {
+  try {
+    const content = await Bun.file(path.join(jobDir, "runner.pid")).text();
+    const pid = parseInt(content.trim(), 10);
+    return Number.isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+
+export function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function getTaskDerivedStatus(snapshot: StatusSnapshot): string {
+  return deriveJobStatusFromTasks(
+    Object.values(snapshot.tasks).map((task) => ({ state: task.state })),
+  );
+}
+
+export function findRunningTaskId(snapshot: StatusSnapshot): string | null {
+  if (snapshot.current && snapshot.tasks[snapshot.current]?.state === "running") {
+    return snapshot.current;
+  }
+  return Object.keys(snapshot.tasks).find((taskId) => snapshot.tasks[taskId]?.state === "running") ?? null;
+}
+
+export function classifyStaleRunningStatus(input: StaleRunningInput): StaleRunningDecision {
+  if (getTaskDerivedStatus(input.status) !== "running") {
+    return { stale: false, reason: "not_running" };
+  }
+  if (input.pid !== null && input.pidAlive) {
+    return { stale: false, reason: "live_pid" };
+  }
+  const updatedMs = Date.parse(input.status.lastUpdated);
+  if (!Number.isFinite(updatedMs)) {
+    return { stale: true, runningTaskId: findRunningTaskId(input.status), ageMs: 0 };
+  }
+  const ageMs = input.nowMs - updatedMs;
+  if (ageMs < input.staleAfterMs) {
+    return { stale: false, reason: "fresh_status" };
+  }
+  return { stale: true, runningTaskId: findRunningTaskId(input.status), ageMs };
+}
+
+const reconcileLogger = createLogger("runner-liveness");
+
+function isLeaseLiveOrInFlight(
+  lease: JobSlotLease,
+  nowMs: number,
+  staleLeaseTimeoutMs: number,
+  isAlive: (pid: number) => boolean,
+): boolean {
+  if (typeof lease.pid === "number" && lease.pid > 0) {
+    return isAlive(lease.pid);
+  }
+  const acquiredMs = Date.parse(lease.acquiredAt);
+  if (!Number.isFinite(acquiredMs)) return false;
+  return nowMs - acquiredMs < staleLeaseTimeoutMs;
+}
+
+function isFreshStatus(snapshot: StatusSnapshot, nowMs: number, staleAfterMs: number): boolean {
+  const updatedMs = Date.parse(snapshot.lastUpdated);
+  return Number.isFinite(updatedMs) && nowMs - updatedMs < staleAfterMs;
+}
+
+export async function reconcileInterruptedJob(opts: ReconcileOptions): Promise<ReconcileResult> {
+  const {
+    dataDir,
+    jobId,
+    jobDir,
+    source,
+    lockTimeoutMs,
+    code,
+    signal,
+    requireStaleStatus = false,
+    staleAfterMs = STALE_RUNNING_GRACE_MS,
+    now = Date.now,
+    isAlive = isProcessAlive,
+  } = opts;
+  const staleLeaseTimeoutMs = opts.staleLeaseTimeoutMs ?? lockTimeoutMs;
+
+  return withRuntimeLock(dataDir, lockTimeoutMs, async () => {
+    const statusResult = await readJobStatusResult(jobDir);
+    if (!statusResult.ok) {
+      return { reconciled: false, reason: "unreadable" } satisfies ReconcileResult;
+    }
+    const snapshot = statusResult.value;
+
+    const derived = getTaskDerivedStatus(snapshot);
+    if (derived !== "running" && snapshot.state !== "running") {
+      return { reconciled: false, reason: "not-running" } satisfies ReconcileResult;
+    }
+
+    const pid = await readRunnerPid(jobDir);
+    if (pid !== null && isAlive(pid)) {
+      return { reconciled: false, reason: "live-pid" } satisfies ReconcileResult;
+    }
+
+    const lease = await readJobSlotLease(dataDir, jobId);
+    if (lease && isLeaseLiveOrInFlight(lease, now(), staleLeaseTimeoutMs, isAlive)) {
+      return { reconciled: false, reason: "live-lease" } satisfies ReconcileResult;
+    }
+
+    if (requireStaleStatus && derived === "running") {
+      const decision = classifyStaleRunningStatus({
+        status: snapshot,
+        pid,
+        pidAlive: false,
+        nowMs: now(),
+        staleAfterMs,
+      });
+      if (!decision.stale) {
+        return {
+          reconciled: false,
+          reason: decision.reason === "not_running" ? "not-running" : "fresh-status",
+        } satisfies ReconcileResult;
+      }
+    } else if (requireStaleStatus && snapshot.state === "running") {
+      if (isFreshStatus(snapshot, now(), staleAfterMs)) {
+        return { reconciled: false, reason: "fresh-status" } satisfies ReconcileResult;
+      }
+    }
+
+    const taskId = findRunningTaskId(snapshot);
+    const nowMs = now();
+    await writeJobStatus(jobDir, (s) => {
+      if (taskId !== null) {
+        const task = s.tasks[taskId];
+        if (task) {
+          task.state = "failed";
+          task.endedAt = new Date(nowMs).toISOString();
+          task.error = "runner exited without completing this task";
+          task.errorContext = { kind: "runner-interrupted", code, signal, source };
+        }
+      } else {
+        s.current = null;
+        s.currentStage = null;
+        s.error = {
+          name: "RunnerInterrupted",
+          message: "runner exited while the job was still marked running",
+        };
+        s.errorContext = { kind: "runner-interrupted", code, signal, source };
+      }
+      s.state = "failed";
+    });
+
+    reconcileLogger.log("reconciled interrupted job", { jobId, taskId, pid, code, signal, path: source });
+
+    return taskId === null
+      ? { reconciled: true, reason: "marked-failed" } satisfies ReconcileResult
+      : { reconciled: true, taskId, reason: "marked-failed" } satisfies ReconcileResult;
+  });
+}
+
+function isErrnoException(value: unknown): value is NodeJS.ErrnoException {
+  return value instanceof Error && typeof (value as NodeJS.ErrnoException).code === "string";
+}
+
+export async function reconcileOrphanedCurrentJobs(opts: SweepOptions): Promise<SweepResult> {
+  const { dataDir, currentDir, lockTimeoutMs, staleLeaseTimeoutMs, staleAfterMs, now, isAlive } = opts;
+
+  let entries: string[];
+  try {
+    const dirents = await readdir(currentDir, { withFileTypes: true });
+    entries = dirents.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch (err) {
+    if (isErrnoException(err) && err.code === "ENOENT") {
+      return { scanned: 0, reconciled: [] };
+    }
+    throw err;
+  }
+
+  const reconciled: string[] = [];
+  for (const entry of entries) {
+    const jobId = entry;
+    const jobDir = path.join(currentDir, entry);
+    const result = await reconcileInterruptedJob({
+      dataDir,
+      jobId,
+      jobDir,
+      source: "boot-sweep",
+      requireStaleStatus: true,
+      staleAfterMs,
+      lockTimeoutMs,
+      staleLeaseTimeoutMs,
+      now,
+      isAlive,
+    });
+    if (result.reconciled) {
+      reconciled.push(jobId);
+    }
+  }
+
+  if (entries.length > 0) {
+    reconcileLogger.log("reconciled orphaned current jobs", {
+      scanned: entries.length,
+      reconciled: reconciled.length,
+    });
+  }
+
+  return { scanned: entries.length, reconciled };
+}

package/src/core/seed-naming.ts

@@ -0,0 +1,9 @@
+export const SEED_FILENAME_PATTERN = /^([A-Za-z0-9][A-Za-z0-9-_]*)-seed\.json$/;
+
+export function seedFilename(jobId: string): string {
+  return `${jobId}-seed.json`;
+}
+
+export function parseSeedFilename(name: string): string | null {
+  return SEED_FILENAME_PATTERN.exec(name)?.[1] ?? null;
+}