@osolmaz/pi-workflows 0.2.0 → 0.3.0

package/dist/workflows/store.js

@@ -20,6 +20,28 @@ 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) {
+    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 = os.homedir()) {
     const override = process.env.PI_WORKFLOWS_RUNS_DIR;
@@ -40,39 +62,75 @@ export function createRunId(workflowName, now = new Date()) {
         .slice(0, 40);
     return `${stamp}-${slug || "workflow"}-${randomUUID().slice(0, 8)}`;
 }
-/**
- * Persists run bundles (see docs/run-bundles.md). `trace.ndjson` is the
- * append-only source of truth; every transition appends the trace event
- * first, then atomically replaces `state.json` (carrying `traceSeq`) and
- * `manifest.json`. Large string leaves in persisted values are externalized
- * into content-addressed `artifacts/`. Bundles are private: directories are
- * 0700 and files 0600.
- */
 export class WorkflowRunStore {
     outputRoot;
+    fenceProvider;
     contexts = new Map();
-    constructor(outputRoot = workflowRunsBaseDir()) {
+    constructor(outputRoot = workflowRunsBaseDir(), options = {}) {
         this.outputRoot = outputRoot;
+        this.fenceProvider = options.fenceProvider;
     }
     runDirFor(runId) {
+        assertValidRunId(runId);
         return path.join(this.outputRoot, runId);
     }
+    async quarantineIncompleteRun(runId) {
+        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;
+    }
     contextFor(runDir) {
         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;
+    }
+    streamFor(runDir, attemptId) {
+        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;
     }
     /**
      * Run `task` exclusively for this bundle. Sequence numbers are assigned
@@ -80,27 +138,181 @@ export class WorkflowRunStore {
      */
     withRunLock(runDir, task) {
         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);
         return result;
     }
-    withSessionEventLock(runDir, task) {
-        const context = this.contextFor(runDir);
-        const result = context.sessionEventLock.then(task);
-        context.sessionEventLock = result.then(() => undefined, () => undefined);
+    withSessionEventLock(runDir, attemptId, task) {
+        const stream = this.streamFor(runDir, attemptId);
+        const result = stream.lock.then(async () => {
+            this.fenceProvider?.(runDir)?.();
+            return await task();
+        });
+        stream.lock = result.then(() => undefined, () => undefined);
         return result;
     }
     async initializeRunBundle(workflow, state) {
         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));
             await appendLine(path.join(runDir, TRACE_PATH), null);
             await this.writeProjections(runDir, state);
             return runDir;
         });
     }
+    /**
+     * 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) {
+        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.
+     */
+    async finalizeRecordingCaptures(runDir, reason, options = {}) {
+        if (options.skipFlat !== true) {
+            const flatCapture = await readJsonFile(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(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, reason = "Workflow host stopped before the run finished") {
+        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.
@@ -119,48 +331,77 @@ export class WorkflowRunStore {
      * append a `session_bound` trace event. Projections catch up on the next
      * snapshot.
      */
-    async writeSessionBinding(runDir, binding) {
+    /** True when a session binding already exists for this bundle. */
+    async hasSessionBinding(runDir) {
+        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) {
+        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, binding, attemptId) {
         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, entry) {
+    async appendSessionEntry(runDir, entry, attemptId) {
         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 = {
-                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;
         });
     }
     /** Append a fully stamped ordered batch to `session/events.ndjson`. */
-    async appendSessionEventBatch(runDir, records) {
+    async appendSessionEventBatch(runDir, records, attemptId) {
         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) {
@@ -173,7 +414,7 @@ export class WorkflowRunStore {
                     payload: 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))
+                        ? (await encodeValue(record.payload, this.contextFor(runDir).artifacts))
                         : record.payload,
                 })));
                 for (const record of encoded) {
@@ -181,30 +422,31 @@ 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, capture) {
+    async writeSessionCapture(runDir, capture, attemptId) {
         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) {
-        const events = await readCompleteNdjson(path.join(runDir, SESSION_EVENTS_PATH));
-        const entries = await readCompleteNdjson(path.join(runDir, SESSION_ENTRIES_PATH));
+    async sessionCounts(runDir, attemptId) {
+        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,
@@ -229,10 +471,118 @@ export class WorkflowRunStore {
         const encoded = await encodeRunState(state, context.artifacts);
         await writeJsonAtomic(path.join(runDir, STATE_PATH), encoded);
         await writeJsonAtomic(path.join(runDir, MANIFEST_PATH), createManifest(state, {
-            session: context.sessionBound,
+            session: [...context.streams.values()].some((stream) => stream.sessionBound),
+        }));
+    }
+    async writeLoadedProjections(runDir, state) {
+        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, keepSeq, beforeWrite) {
+    let raw;
+    try {
+        raw = await fs.readFile(tracePath, "utf8");
+    }
+    catch {
+        return;
+    }
+    const lines = raw.split("\n");
+    if (lines.at(-1) === "") {
+        lines.pop();
+    }
+    const good = [];
+    let expectedSeq = 1;
+    for (const line of lines) {
+        if (line.trim().length === 0) {
+            break;
+        }
+        try {
+            const event = JSON.parse(line);
+            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) {
+    return new Map([["", { ...flat, lock: Promise.resolve() }]]);
+}
+function recoverTerminalProjection(state, event) {
+    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) {
+    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) {
+    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) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
 async function appendLine(filePath, value) {
     await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
     await fs.appendFile(filePath, value === null ? "" : `${JSON.stringify(value)}\n`, {
@@ -426,6 +776,11 @@ async function encodeRunState(state, artifacts) {
             : {}),
     };
 }
+/** Read the final trace record without loading the rest of a run bundle. */
+export async function readLastTraceEvent(runDir, tracePath) {
+    const events = await readNdjsonFile(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) {
     const manifest = await readJsonFile(path.join(runDir, MANIFEST_PATH));
@@ -445,13 +800,52 @@ export async function readRunBundle(runDir) {
     const entries = await readNdjsonFile(path.join(sessionDir, "entries.ndjson"));
     const events = await readNdjsonFile(path.join(sessionDir, "events.ndjson"));
     const sessionCapture = await readJsonFile(path.join(sessionDir, "capture.json"));
-    const sessionIntegrity = assessSessionIntegrity({
+    const flatIntegrity = assessSessionIntegrity({
         binding: sessionBinding,
         entries,
         events,
         capture: sessionCapture,
         runTerminal: state.status !== "running",
     });
+    const sessionSegments = [];
+    let segmentIds = [];
+    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(path.join(segmentDir, "binding.json"));
+        const segmentEntries = await readNdjsonFile(path.join(segmentDir, "entries.ndjson"));
+        const segmentEvents = await readNdjsonFile(path.join(segmentDir, "events.ndjson"));
+        const capture = await readJsonFile(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,
@@ -462,6 +856,7 @@ export async function readRunBundle(runDir) {
         sessionEvents: events.records,
         sessionCapture,
         sessionIntegrity,
+        sessionSegments,
     };
 }
 /**