@osolmaz/pi-workflows 0.2.0 → 0.3.0

package/src/workflows/store.ts

@@ -36,6 +36,35 @@ const SESSION_BINDING_PATH = `${SESSION_DIR}/binding.json`;
 const SESSION_ENTRIES_PATH = `${SESSION_DIR}/entries.ndjson`;
 const SESSION_EVENTS_PATH = `${SESSION_DIR}/events.ndjson`;
 const SESSION_CAPTURE_PATH = `${SESSION_DIR}/capture.json`;
+const SESSION_SEGMENTS_DIR = `${SESSION_DIR}/segments`;
+
+/** Capture file layout for one recorder attempt; "" is the legacy flat stream. */
+function sessionStreamPaths(attemptId?: string): {
+  dir: string;
+  binding: string;
+  entries: string;
+  events: string;
+  capture: string;
+} {
+  if (attemptId === undefined) {
+    return {
+      dir: SESSION_DIR,
+      binding: SESSION_BINDING_PATH,
+      entries: SESSION_ENTRIES_PATH,
+      events: SESSION_EVENTS_PATH,
+      capture: SESSION_CAPTURE_PATH,
+    };
+  }
+  assertValidRunId(attemptId);
+  const dir = `${SESSION_SEGMENTS_DIR}/${attemptId}`;
+  return {
+    dir,
+    binding: `${dir}/binding.json`,
+    entries: `${dir}/entries.ndjson`,
+    events: `${dir}/events.ndjson`,
+    capture: `${dir}/capture.json`,
+  };
+}
 
 /** Runs directory: `$PI_WORKFLOWS_RUNS_DIR` or `~/.pi/agent/workflows/runs`. */
 export function workflowRunsBaseDir(homeDir: string = os.homedir()): string {
@@ -59,12 +88,19 @@ export function createRunId(workflowName: string, now: Date = new Date()): strin
   return `${stamp}-${slug || "workflow"}-${randomUUID().slice(0, 8)}`;
 }
 
-type RunBundleContext = {
-  traceSeq: number;
+/** Per-attempt capture stream state; the "" key is the legacy flat stream. */
+type SessionStreamState = {
   sessionSeq: number;
   sessionEventSeq: number;
   sessionBound: boolean;
   sessionEventsStopped: boolean;
+  /** Session events have a separate append chain so token traffic cannot
+   * queue ahead of workflow transitions. */
+  lock: Promise<unknown>;
+};
+
+type RunBundleContext = {
+  traceSeq: number;
   artifacts: ArtifactWriter;
   /**
    * Serializes complete transitions (encode, trace append, projections) so
@@ -72,9 +108,7 @@ type RunBundleContext = {
    * append order.
    */
   lock: Promise<unknown>;
-  /** Session events have a separate append chain so token traffic cannot
-   * queue ahead of workflow transitions. */
-  sessionEventLock: Promise<unknown>;
+  streams: Map<string, SessionStreamState>;
 };
 
 /**
@@ -85,34 +119,92 @@ type RunBundleContext = {
  * into content-addressed `artifacts/`. Bundles are private: directories are
  * 0700 and files 0600.
  */
+/**
+ * A fence proves the writer still owns the run. It is checked before every
+ * locked write; it throws (ClaimLostError) when the queue claim was lost, so
+ * a stalled runner can never interleave writes with the new claim holder.
+ */
+export type RunFence = () => void;
+
+export type WorkflowRunStoreOptions = {
+  fenceProvider?: (runDir: string) => RunFence | undefined;
+};
+
 export class WorkflowRunStore {
   readonly outputRoot: string;
+  private readonly fenceProvider: ((runDir: string) => RunFence | undefined) | undefined;
   private readonly contexts = new Map<string, RunBundleContext>();
 
-  constructor(outputRoot: string = workflowRunsBaseDir()) {
+  constructor(outputRoot: string = workflowRunsBaseDir(), options: WorkflowRunStoreOptions = {}) {
     this.outputRoot = outputRoot;
+    this.fenceProvider = options.fenceProvider;
   }
 
   runDirFor(runId: string): string {
+    assertValidRunId(runId);
     return path.join(this.outputRoot, runId);
   }
 
+  async quarantineIncompleteRun(runId: string): Promise<string | undefined> {
+    const runDir = this.runDirFor(runId);
+    let runStat;
+    try {
+      runStat = await fs.lstat(runDir);
+    } catch (error) {
+      if (isMissingPath(error)) {
+        return undefined;
+      }
+      throw error;
+    }
+    if (!runStat.isDirectory() || runStat.isSymbolicLink()) {
+      throw new Error(`Reserved workflow run path is not a directory: ${runDir}`);
+    }
+    try {
+      await fs.lstat(path.join(runDir, MANIFEST_PATH));
+      throw new Error(`Reserved workflow run has an unreadable manifest: ${runId}`);
+    } catch (error) {
+      if (!isMissingPath(error)) {
+        throw error;
+      }
+    }
+    const quarantineDir = path.join(
+      this.outputRoot,
+      `.${runId}.incomplete-${randomUUID().slice(0, 8)}`,
+    );
+    await fs.rename(runDir, quarantineDir);
+    this.contexts.delete(runDir);
+    return quarantineDir;
+  }
+
   private contextFor(runDir: string): RunBundleContext {
     let context = this.contexts.get(runDir);
     if (!context) {
       context = {
         traceSeq: 0,
+        artifacts: new ArtifactWriter(runDir),
+        lock: Promise.resolve(),
+        streams: new Map(),
+      };
+      this.contexts.set(runDir, context);
+    }
+    return context;
+  }
+
+  private streamFor(runDir: string, attemptId?: string): SessionStreamState {
+    const context = this.contextFor(runDir);
+    const key = attemptId ?? "";
+    let stream = context.streams.get(key);
+    if (!stream) {
+      stream = {
         sessionSeq: 0,
         sessionEventSeq: 0,
         sessionBound: false,
         sessionEventsStopped: false,
-        artifacts: new ArtifactWriter(runDir),
         lock: Promise.resolve(),
-        sessionEventLock: Promise.resolve(),
       };
-      this.contexts.set(runDir, context);
+      context.streams.set(key, stream);
     }
-    return context;
+    return stream;
   }
 
   /**
@@ -121,7 +213,10 @@ export class WorkflowRunStore {
    */
   private withRunLock<T>(runDir: string, task: () => Promise<T>): Promise<T> {
     const context = this.contextFor(runDir);
-    const result = context.lock.then(task);
+    const result = context.lock.then(async () => {
+      this.fenceProvider?.(runDir)?.();
+      return await task();
+    });
     context.lock = result.then(
       () => undefined,
       () => undefined,
@@ -129,10 +224,17 @@ export class WorkflowRunStore {
     return result;
   }
 
-  private withSessionEventLock<T>(runDir: string, task: () => Promise<T>): Promise<T> {
-    const context = this.contextFor(runDir);
-    const result = context.sessionEventLock.then(task);
-    context.sessionEventLock = result.then(
+  private withSessionEventLock<T>(
+    runDir: string,
+    attemptId: string | undefined,
+    task: () => Promise<T>,
+  ): Promise<T> {
+    const stream = this.streamFor(runDir, attemptId);
+    const result = stream.lock.then(async () => {
+      this.fenceProvider?.(runDir)?.();
+      return await task();
+    });
+    stream.lock = result.then(
       () => undefined,
       () => undefined,
     );
@@ -144,9 +246,9 @@ export class WorkflowRunStore {
     state: WorkflowRunState,
   ): Promise<string> {
     const runDir = this.runDirFor(state.runId);
-    this.contexts.delete(runDir);
     return await this.withRunLock(runDir, async () => {
-      await fs.mkdir(runDir, { recursive: true, mode: 0o700 });
+      await fs.mkdir(this.outputRoot, { recursive: true, mode: 0o700 });
+      await fs.mkdir(runDir, { recursive: false, mode: 0o700 });
       await writeJsonAtomic(
         path.join(runDir, WORKFLOW_SNAPSHOT_PATH),
         createDefinitionSnapshot(workflow),
@@ -157,6 +259,176 @@ export class WorkflowRunStore {
     });
   }
 
+  /**
+   * Prepare an interrupted bundle for resume. Repairs a torn trace tail,
+   * drops trace events the state projection never recorded, and seeds the
+   * in-process context so new events continue the sequence. The caller must
+   * hold the run's queue claim; the fence is verified before any write.
+   */
+  async prepareRunResume(runId: string): Promise<LoadedRunBundle> {
+    const runDir = this.runDirFor(runId);
+    this.fenceProvider?.(runDir)?.();
+    const bundle = await readRunBundle(runDir);
+    if (bundle === null) {
+      throw new Error(`Cannot resume unreadable workflow run: ${runId}`);
+    }
+    if (bundle.state.status !== "running") {
+      throw new Error(`Cannot resume workflow run ${runId} with status ${bundle.state.status}`);
+    }
+    const tracePath = resolveBundlePath(runDir, bundle.manifest.paths.trace, TRACE_PATH);
+    await repairTraceFile(tracePath, bundle.state.traceSeq, () => {
+      // The repair rewrites the trace; re-verify ownership immediately
+      // before the rename so a stalled runner cannot truncate a new claim
+      // holder's appended events.
+      this.fenceProvider?.(runDir)?.();
+    });
+
+    // A crashed session never finalizes its capture, and resuming recorders
+    // always write new segments — so dangling "recording" captures end here
+    // instead of reporting the run capture-corrupt forever.
+    await this.finalizeRecordingCaptures(runDir, "Workflow host stopped before the run finished");
+
+    const counts = await this.sessionCounts(runDir);
+    const captureFinished =
+      bundle.sessionCapture?.status === "complete" || bundle.sessionCapture?.status === "failed";
+    this.contexts.set(runDir, {
+      traceSeq: bundle.state.traceSeq,
+      artifacts: new ArtifactWriter(runDir),
+      lock: Promise.resolve(),
+      streams: seededStreams({
+        sessionSeq: counts.entryCount,
+        sessionEventSeq: counts.lastEventSeq,
+        sessionBound: bundle.manifest.paths.session !== undefined,
+        sessionEventsStopped: captureFinished,
+      }),
+    });
+    const prepared = await readRunBundle(runDir);
+    if (prepared === null) {
+      throw new Error(`Workflow run ${runId} became unreadable during resume preparation`);
+    }
+    return prepared;
+  }
+
+  /**
+   * Finalize captures left "recording" by a session that is gone, so they
+   * report failed with the reason instead of dangling forever.
+   */
+  private async finalizeRecordingCaptures(
+    runDir: string,
+    reason: string,
+    options: { skipFlat?: boolean } = {},
+  ): Promise<void> {
+    if (options.skipFlat !== true) {
+      const flatCapture = await readJsonFile<WorkflowSessionCapture>(
+        path.join(runDir, SESSION_CAPTURE_PATH),
+      );
+      if (flatCapture?.status === "recording") {
+        const counts = await this.sessionCounts(runDir);
+        await this.writeSessionCapture(runDir, {
+          schema: SESSION_CAPTURE_SCHEMA,
+          eventSchema: SESSION_EVENT_SCHEMA,
+          status: "failed",
+          ...counts,
+          failure: {
+            failedAt: new Date().toISOString(),
+            code: "host_interrupted",
+            message: reason,
+          },
+        });
+      }
+    }
+    for (const segmentId of await this.listSessionSegments(runDir)) {
+      const segmentCapture = await readJsonFile<WorkflowSessionCapture>(
+        path.join(runDir, sessionStreamPaths(segmentId).capture),
+      );
+      if (segmentCapture?.status !== "recording") {
+        continue;
+      }
+      const segmentCounts = await this.sessionCounts(runDir, segmentId);
+      await this.writeSessionCapture(
+        runDir,
+        {
+          schema: SESSION_CAPTURE_SCHEMA,
+          eventSchema: SESSION_EVENT_SCHEMA,
+          status: "failed",
+          ...segmentCounts,
+          failure: {
+            failedAt: new Date().toISOString(),
+            code: "host_interrupted",
+            message: reason,
+          },
+        },
+        segmentId,
+      );
+    }
+  }
+
+  /** Mark a nonterminal bundle failed and append an interruption event. */
+  async markRunInterrupted(
+    runId: string,
+    reason = "Workflow host stopped before the run finished",
+  ): Promise<LoadedRunBundle | null> {
+    const runDir = this.runDirFor(runId);
+    const bundle = await readRunBundle(runDir);
+    if (bundle === null || bundle.state.status !== "running") {
+      return bundle;
+    }
+    const lastTraceEvent = await readLastTraceEvent(runDir, bundle.manifest.paths.trace);
+    const counts = await this.sessionCounts(runDir);
+    const sessionBound = bundle.manifest.paths.session !== undefined;
+    const captureFinished =
+      bundle.sessionCapture?.status === "complete" || bundle.sessionCapture?.status === "failed";
+    this.contexts.set(runDir, {
+      traceSeq: Math.max(bundle.state.traceSeq, lastTraceEvent?.seq ?? 0),
+      artifacts: new ArtifactWriter(runDir),
+      lock: Promise.resolve(),
+      streams: seededStreams({
+        sessionSeq: counts.entryCount,
+        sessionEventSeq: counts.lastEventSeq,
+        sessionBound,
+        sessionEventsStopped: captureFinished,
+      }),
+    });
+    const state = bundle.state;
+    if (lastTraceEvent !== null && recoverTerminalProjection(state, lastTraceEvent)) {
+      await this.writeLoadedProjections(runDir, state);
+      return await readRunBundle(runDir);
+    }
+    if (sessionBound && !captureFinished) {
+      await this.writeSessionCapture(runDir, {
+        schema: SESSION_CAPTURE_SCHEMA,
+        eventSchema: SESSION_EVENT_SCHEMA,
+        status: "failed",
+        ...counts,
+        failure: {
+          failedAt: new Date().toISOString(),
+          code: "host_interrupted",
+          message: reason,
+        },
+      });
+    }
+    await this.finalizeRecordingCaptures(runDir, reason, { skipFlat: true });
+    state.status = "failed";
+    state.finishedAt = new Date().toISOString();
+    state.error = reason;
+    delete state.currentNode;
+    delete state.currentAttemptId;
+    delete state.currentNodeStartedAt;
+    delete state.statusDetail;
+    delete state.paused;
+    await this.withRunLock(runDir, async () => {
+      const traceEvent = await this.appendTraceEvent(runDir, state.runId, {
+        scope: "run",
+        type: "run_interrupted",
+        payload: { error: reason },
+      });
+      state.traceSeq = traceEvent.seq;
+      state.updatedAt = traceEvent.at;
+      await this.writeLoadedProjections(runDir, state);
+    });
+    return await readRunBundle(runDir);
+  }
+
   /**
    * Persist one transition: append the trace event, then rewrite the
    * projections reflecting it.
@@ -180,34 +452,71 @@ export class WorkflowRunStore {
    * append a `session_bound` trace event. Projections catch up on the next
    * snapshot.
    */
-  async writeSessionBinding(runDir: string, binding: WorkflowSessionBinding): Promise<void> {
+  /** True when a session binding already exists for this bundle. */
+  async hasSessionBinding(runDir: string): Promise<boolean> {
+    try {
+      await fs.lstat(path.join(runDir, SESSION_BINDING_PATH));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** List capture segment attempt ids under `session/segments/`. */
+  async listSessionSegments(runDir: string): Promise<string[]> {
+    try {
+      const entries = await fs.readdir(path.join(runDir, SESSION_SEGMENTS_DIR), {
+        withFileTypes: true,
+      });
+      return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
+  async writeSessionBinding(
+    runDir: string,
+    binding: WorkflowSessionBinding,
+    attemptId?: string,
+  ): Promise<void> {
     await this.withRunLock(runDir, async () => {
-      const context = this.contextFor(runDir);
-      if (context.sessionBound) {
+      const stream = this.streamFor(runDir, attemptId);
+      if (stream.sessionBound) {
         return;
       }
-      context.sessionBound = true;
-      await fs.mkdir(path.join(runDir, SESSION_DIR), { recursive: true, mode: 0o700 });
-      await writeJsonAtomic(path.join(runDir, SESSION_BINDING_PATH), binding);
+      stream.sessionBound = true;
+      const paths = sessionStreamPaths(attemptId);
+      await fs.mkdir(path.join(runDir, paths.dir), { recursive: true, mode: 0o700 });
+      await writeJsonAtomic(path.join(runDir, paths.binding), binding);
       await this.appendTraceEvent(runDir, binding.runId, {
         scope: "session",
         type: "session_bound",
-        payload: { piSessionId: binding.piSessionId },
+        payload: {
+          piSessionId: binding.piSessionId,
+          ...(attemptId !== undefined ? { captureAttemptId: attemptId } : {}),
+        },
       });
     });
   }
 
   /** Append one verbatim Pi session entry to `session/entries.ndjson`. */
-  async appendSessionEntry(runDir: string, entry: Record<string, unknown>): Promise<number> {
+  async appendSessionEntry(
+    runDir: string,
+    entry: Record<string, unknown>,
+    attemptId?: string,
+  ): Promise<number> {
     return await this.withRunLock(runDir, async () => {
-      const context = this.contextFor(runDir);
-      context.sessionSeq += 1;
+      const stream = this.streamFor(runDir, attemptId);
+      stream.sessionSeq += 1;
       const record: WorkflowSessionEntryRecord = {
-        seq: context.sessionSeq,
+        seq: stream.sessionSeq,
         at: new Date().toISOString(),
         entry,
       };
-      await appendLine(path.join(runDir, SESSION_ENTRIES_PATH), record);
+      await appendLine(path.join(runDir, sessionStreamPaths(attemptId).entries), record);
       return record.seq;
     });
   }
@@ -216,17 +525,18 @@ export class WorkflowRunStore {
   async appendSessionEventBatch(
     runDir: string,
     records: WorkflowSessionEventRecord[],
+    attemptId?: string,
   ): Promise<void> {
     if (records.length === 0) {
       return;
     }
-    await this.withSessionEventLock(runDir, async () => {
-      const context = this.contextFor(runDir);
-      if (context.sessionEventsStopped) {
+    await this.withSessionEventLock(runDir, attemptId, async () => {
+      const stream = this.streamFor(runDir, attemptId);
+      if (stream.sessionEventsStopped) {
         throw new Error("Session event capture has stopped");
       }
       try {
-        let expected = context.sessionEventSeq + 1;
+        let expected = stream.sessionEventSeq + 1;
         for (const record of records) {
           validateSessionEventRecord(record);
           if (record.seq !== expected) {
@@ -241,7 +551,7 @@ export class WorkflowRunStore {
               record.type === "tool_execution_started" ||
               record.type === "tool_execution_finished" ||
               (record.type === "assistant_event" && record.payload.type === "toolcall_end")
-                ? ((await encodeValue(record.payload, context.artifacts)) as Record<
+                ? ((await encodeValue(record.payload, this.contextFor(runDir).artifacts)) as Record<
                     string,
                     unknown
                   >)
@@ -253,33 +563,39 @@ export class WorkflowRunStore {
             throw new Error(`session event exceeded ${SESSION_EVENT_MAX_BYTES} bytes`);
           }
         }
-        await appendLines(path.join(runDir, SESSION_EVENTS_PATH), encoded);
-        context.sessionEventSeq = records.at(-1)?.seq ?? context.sessionEventSeq;
+        await appendLines(path.join(runDir, sessionStreamPaths(attemptId).events), encoded);
+        stream.sessionEventSeq = records.at(-1)?.seq ?? stream.sessionEventSeq;
       } catch (error) {
-        context.sessionEventsStopped = true;
+        stream.sessionEventsStopped = true;
         throw error;
       }
     });
   }
 
   /** Atomically replace the temporal capture integrity projection. */
-  async writeSessionCapture(runDir: string, capture: WorkflowSessionCapture): Promise<void> {
+  async writeSessionCapture(
+    runDir: string,
+    capture: WorkflowSessionCapture,
+    attemptId?: string,
+  ): Promise<void> {
     validateSessionCapture(capture);
-    await this.withSessionEventLock(runDir, async () => {
-      const context = this.contextFor(runDir);
+    await this.withSessionEventLock(runDir, attemptId, async () => {
+      const stream = this.streamFor(runDir, attemptId);
       if (capture.status !== "recording") {
-        context.sessionEventsStopped = true;
+        stream.sessionEventsStopped = true;
       }
-      await writeJsonAtomic(path.join(runDir, SESSION_CAPTURE_PATH), capture);
+      await writeJsonAtomic(path.join(runDir, sessionStreamPaths(attemptId).capture), capture);
     });
   }
 
   /** Count complete durable session records after both writers have drained. */
   async sessionCounts(
     runDir: string,
+    attemptId?: string,
   ): Promise<{ eventCount: number; entryCount: number; lastEventSeq: number }> {
-    const events = await readCompleteNdjson(path.join(runDir, SESSION_EVENTS_PATH));
-    const entries = await readCompleteNdjson(path.join(runDir, SESSION_ENTRIES_PATH));
+    const paths = sessionStreamPaths(attemptId);
+    const events = await readCompleteNdjson(path.join(runDir, paths.events));
+    const entries = await readCompleteNdjson(path.join(runDir, paths.entries));
     return {
       eventCount: events.length,
       entryCount: entries.length,
@@ -312,12 +628,132 @@ export class WorkflowRunStore {
     await writeJsonAtomic(
       path.join(runDir, MANIFEST_PATH),
       createManifest(state, {
-        session: context.sessionBound,
+        session: [...context.streams.values()].some((stream) => stream.sessionBound),
+      }),
+    );
+  }
+
+  private async writeLoadedProjections(runDir: string, state: WorkflowRunState): Promise<void> {
+    const context = this.contextFor(runDir);
+    await writeJsonAtomic(path.join(runDir, STATE_PATH), state);
+    await writeJsonAtomic(
+      path.join(runDir, MANIFEST_PATH),
+      createManifest(state, {
+        session: [...context.streams.values()].some((stream) => stream.sessionBound),
       }),
     );
   }
 }
 
+/**
+ * Truncate a trace file to the longest contiguous valid prefix, then to the
+ * event count the state projection recorded. A crash can leave a partial
+ * final line or one event appended before its projection write; the repair
+ * keeps state and trace consistent so resume can continue the sequence. The
+ * rewrite is atomic: a stale writer appending to the old inode cannot
+ * interleave with the repaired file.
+ */
+async function repairTraceFile(
+  tracePath: string,
+  keepSeq: number,
+  beforeWrite?: () => void,
+): Promise<void> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(tracePath, "utf8");
+  } catch {
+    return;
+  }
+  const lines = raw.split("\n");
+  if (lines.at(-1) === "") {
+    lines.pop();
+  }
+  const good: string[] = [];
+  let expectedSeq = 1;
+  for (const line of lines) {
+    if (line.trim().length === 0) {
+      break;
+    }
+    try {
+      const event = JSON.parse(line) as { seq?: unknown };
+      if (event.seq !== expectedSeq) {
+        break;
+      }
+      good.push(line);
+      expectedSeq += 1;
+    } catch {
+      break;
+    }
+  }
+  const kept = good.slice(0, keepSeq);
+  if (kept.length === lines.length) {
+    return;
+  }
+  beforeWrite?.();
+  const tempPath = `${tracePath}.${process.pid}.${randomUUID()}.tmp`;
+  await fs.writeFile(tempPath, kept.length === 0 ? "" : `${kept.join("\n")}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await fs.rename(tempPath, tracePath);
+}
+
+function seededStreams(flat: Omit<SessionStreamState, "lock">): Map<string, SessionStreamState> {
+  return new Map([["", { ...flat, lock: Promise.resolve() }]]);
+}
+
+function recoverTerminalProjection(state: WorkflowRunState, event: WorkflowTraceEvent): boolean {
+  const status = terminalStatusForEvent(event.type);
+  if (status === undefined) {
+    return false;
+  }
+  state.traceSeq = event.seq;
+  state.status = status;
+  state.updatedAt = event.at;
+  state.finishedAt = event.at;
+  if (typeof event.payload.error === "string") {
+    state.error = event.payload.error;
+  }
+  if (typeof event.payload.waitingOn === "string") {
+    state.waitingOn = event.payload.waitingOn;
+  }
+  if (Object.hasOwn(event.payload, "finalOutput")) {
+    state.finalOutput = event.payload.finalOutput;
+  }
+  delete state.currentNode;
+  delete state.currentAttemptId;
+  delete state.currentNodeStartedAt;
+  return true;
+}
+
+function terminalStatusForEvent(type: string): WorkflowRunState["status"] | undefined {
+  switch (type) {
+    case "run_waiting":
+      return "waiting";
+    case "run_completed":
+      return "completed";
+    case "run_failed":
+    case "run_interrupted":
+      return "failed";
+    case "run_timed_out":
+      return "timed_out";
+    case "run_cancelled":
+      return "cancelled";
+    default:
+      return undefined;
+  }
+}
+
+function assertValidRunId(runId: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(runId)) {
+    throw new Error(`Invalid workflow run id: ${JSON.stringify(runId)}`);
+  }
+}
+
+function isMissingPath(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
 async function appendLine(filePath: string, value: unknown): Promise<void> {
   await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
   await fs.appendFile(filePath, value === null ? "" : `${JSON.stringify(value)}\n`, {
@@ -545,6 +981,16 @@ export type SessionCaptureIntegrity = {
   diagnostics: string[];
 };
 
+/** One capture attempt: the session data a single recorder wrote. */
+export type SessionCaptureSegment = {
+  attemptId: string;
+  binding: WorkflowSessionBinding | null;
+  entries: WorkflowSessionEntryRecord[];
+  events: WorkflowSessionEventRecord[];
+  capture: WorkflowSessionCapture | null;
+  integrity: SessionCaptureIntegrity;
+};
+
 export type LoadedRunBundle = {
   runDir: string;
   manifest: WorkflowRunManifest;
@@ -555,8 +1001,21 @@ export type LoadedRunBundle = {
   sessionEvents: WorkflowSessionEventRecord[];
   sessionCapture: WorkflowSessionCapture | null;
   sessionIntegrity: SessionCaptureIntegrity;
+  /** Per-attempt captures written after a handoff or resume. */
+  sessionSegments: SessionCaptureSegment[];
 };
 
+/** Read the final trace record without loading the rest of a run bundle. */
+export async function readLastTraceEvent(
+  runDir: string,
+  tracePath?: string,
+): Promise<WorkflowTraceEvent | null> {
+  const events = await readNdjsonFile<WorkflowTraceEvent>(
+    resolveBundlePath(runDir, tracePath, TRACE_PATH),
+  );
+  return events.records.at(-1) ?? null;
+}
+
 /** Read a run bundle from disk. Returns null when the bundle is unreadable. */
 export async function readRunBundle(runDir: string): Promise<LoadedRunBundle | null> {
   const manifest = await readJsonFile<WorkflowRunManifest>(path.join(runDir, MANIFEST_PATH));
@@ -589,13 +1048,62 @@ export async function readRunBundle(runDir: string): Promise<LoadedRunBundle | n
   const sessionCapture = await readJsonFile<WorkflowSessionCapture>(
     path.join(sessionDir, "capture.json"),
   );
-  const sessionIntegrity = assessSessionIntegrity({
+  const flatIntegrity = assessSessionIntegrity({
     binding: sessionBinding,
     entries,
     events,
     capture: sessionCapture,
     runTerminal: state.status !== "running",
   });
+  const sessionSegments: SessionCaptureSegment[] = [];
+  let segmentIds: string[] = [];
+  try {
+    segmentIds = (await fs.readdir(path.join(sessionDir, "segments"), { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch {
+    // No segments directory means only the flat stream can exist.
+  }
+  for (const attemptId of segmentIds) {
+    const segmentDir = path.join(sessionDir, "segments", attemptId);
+    const binding = await readJsonFile<WorkflowSessionBinding>(
+      path.join(segmentDir, "binding.json"),
+    );
+    const segmentEntries = await readNdjsonFile<WorkflowSessionEntryRecord>(
+      path.join(segmentDir, "entries.ndjson"),
+    );
+    const segmentEvents = await readNdjsonFile<WorkflowSessionEventRecord>(
+      path.join(segmentDir, "events.ndjson"),
+    );
+    const capture = await readJsonFile<WorkflowSessionCapture>(
+      path.join(segmentDir, "capture.json"),
+    );
+    sessionSegments.push({
+      attemptId,
+      binding,
+      entries: segmentEntries.records,
+      events: segmentEvents.records,
+      capture,
+      integrity: assessSessionIntegrity({
+        binding,
+        entries: segmentEntries,
+        events: segmentEvents,
+        capture,
+        runTerminal: state.status !== "running",
+      }),
+    });
+  }
+  // The headline integrity is the flat stream's when present; otherwise the
+  // chronologically latest capture segment speaks for the run (segment ids
+  // are random, so directory order says nothing about time).
+  sessionSegments.sort((a, b) =>
+    (a.binding?.boundAt ?? "").localeCompare(b.binding?.boundAt ?? ""),
+  );
+  const sessionIntegrity =
+    flatIntegrity.status !== "unavailable" || sessionSegments.length === 0
+      ? flatIntegrity
+      : (sessionSegments.at(-1)?.integrity ?? flatIntegrity);
   return {
     runDir,
     manifest,
@@ -606,6 +1114,7 @@ export async function readRunBundle(runDir: string): Promise<LoadedRunBundle | n
     sessionEvents: events.records,
     sessionCapture,
     sessionIntegrity,
+    sessionSegments,
   };
 }