@osolmaz/pi-workflows 0.1.0 → 0.3.0

package/dist/workflows/store.js

@@ -2,13 +2,46 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { ArtifactWriter, encodeValue } from "./artifacts.js";
 export const RUN_BUNDLE_SCHEMA = "pi-workflows.run-bundle.v1";
+export const RUN_STATE_SCHEMA = "pi-workflows.run-state.v1";
 export const TRACE_EVENT_SCHEMA = "pi-workflows.trace-event.v1";
 export const DEFINITION_SNAPSHOT_SCHEMA = "pi-workflows.definition-snapshot.v1";
+export const SESSION_BINDING_SCHEMA = "pi-workflows.session-binding.v1";
+export const SESSION_EVENT_SCHEMA = "pi-workflows.session-event.v1";
+export const SESSION_CAPTURE_SCHEMA = "pi-workflows.session-capture.v1";
+export const SESSION_EVENT_MAX_BYTES = 1024 * 1024;
 const MANIFEST_PATH = "manifest.json";
 const WORKFLOW_SNAPSHOT_PATH = "workflow.json";
 const STATE_PATH = "state.json";
 const TRACE_PATH = "trace.ndjson";
+const SESSION_DIR = "session";
+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;
@@ -29,76 +62,815 @@ export function createRunId(workflowName, now = new Date()) {
         .slice(0, 40);
     return `${stamp}-${slug || "workflow"}-${randomUUID().slice(0, 8)}`;
 }
-/**
- * Persists run bundles. A bundle directory contains `manifest.json`,
- * `workflow.json` (definition snapshot), `state.json` (full run projection,
- * atomically replaced), and `trace.ndjson` (append-only event log).
- */
 export class WorkflowRunStore {
     outputRoot;
-    traceSeqByRun = new Map();
-    appendChainByPath = new Map();
-    constructor(outputRoot = workflowRunsBaseDir()) {
+    fenceProvider;
+    contexts = new Map();
+    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,
+                lock: Promise.resolve(),
+            };
+            context.streams.set(key, stream);
+        }
+        return stream;
+    }
+    /**
+     * Run `task` exclusively for this bundle. Sequence numbers are assigned
+     * inside the lock, so physical file order always matches logical order.
+     */
+    withRunLock(runDir, task) {
+        const context = this.contextFor(runDir);
+        const result = context.lock.then(async () => {
+            this.fenceProvider?.(runDir)?.();
+            return await task();
+        });
+        context.lock = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    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);
-        await fs.mkdir(runDir, { recursive: true });
-        this.traceSeqByRun.set(runDir, 0);
-        await writeJsonAtomic(path.join(runDir, WORKFLOW_SNAPSHOT_PATH), createDefinitionSnapshot(workflow));
-        await writeJsonAtomic(path.join(runDir, MANIFEST_PATH), createManifest(state));
-        await writeJsonAtomic(path.join(runDir, STATE_PATH), state);
-        await this.appendJsonLine(path.join(runDir, TRACE_PATH), null);
-        return runDir;
+        return await this.withRunLock(runDir, async () => {
+            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.
+     */
     async writeSnapshot(runDir, state, event) {
-        state.updatedAt = new Date().toISOString();
-        await writeJsonAtomic(path.join(runDir, STATE_PATH), state);
-        await writeJsonAtomic(path.join(runDir, MANIFEST_PATH), createManifest(state));
-        return await this.appendTrace(runDir, state, event);
+        return await this.withRunLock(runDir, async () => {
+            const traceEvent = await this.appendTraceEvent(runDir, state.runId, event);
+            state.traceSeq = traceEvent.seq;
+            state.updatedAt = new Date().toISOString();
+            await this.writeProjections(runDir, state);
+            return traceEvent;
+        });
     }
-    async appendTrace(runDir, state, event) {
+    /**
+     * Bind the run to a Pi conversation: write `session/binding.json` once and
+     * append a `session_bound` trace event. Projections catch up on the next
+     * snapshot.
+     */
+    /** 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 stream = this.streamFor(runDir, attemptId);
+            if (stream.sessionBound) {
+                return;
+            }
+            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,
+                    ...(attemptId !== undefined ? { captureAttemptId: attemptId } : {}),
+                },
+            });
+        });
+    }
+    /** Append one verbatim Pi session entry to `session/entries.ndjson`. */
+    async appendSessionEntry(runDir, entry, attemptId) {
+        return await this.withRunLock(runDir, async () => {
+            const stream = this.streamFor(runDir, attemptId);
+            stream.sessionSeq += 1;
+            const record = {
+                seq: stream.sessionSeq,
+                at: new Date().toISOString(),
+                entry,
+            };
+            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, attemptId) {
+        if (records.length === 0) {
+            return;
+        }
+        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 = stream.sessionEventSeq + 1;
+                for (const record of records) {
+                    validateSessionEventRecord(record);
+                    if (record.seq !== expected) {
+                        throw new Error(`Expected session event seq ${expected}, got ${record.seq}`);
+                    }
+                    expected += 1;
+                }
+                const encoded = await Promise.all(records.map(async (record) => ({
+                    ...record,
+                    payload: record.type === "tool_execution_started" ||
+                        record.type === "tool_execution_finished" ||
+                        (record.type === "assistant_event" && record.payload.type === "toolcall_end")
+                        ? (await encodeValue(record.payload, this.contextFor(runDir).artifacts))
+                        : record.payload,
+                })));
+                for (const record of encoded) {
+                    if (Buffer.byteLength(JSON.stringify(record), "utf8") + 1 > SESSION_EVENT_MAX_BYTES) {
+                        throw new Error(`session event exceeded ${SESSION_EVENT_MAX_BYTES} bytes`);
+                    }
+                }
+                await appendLines(path.join(runDir, sessionStreamPaths(attemptId).events), encoded);
+                stream.sessionEventSeq = records.at(-1)?.seq ?? stream.sessionEventSeq;
+            }
+            catch (error) {
+                stream.sessionEventsStopped = true;
+                throw error;
+            }
+        });
+    }
+    /** Atomically replace the temporal capture integrity projection. */
+    async writeSessionCapture(runDir, capture, attemptId) {
+        validateSessionCapture(capture);
+        await this.withSessionEventLock(runDir, attemptId, async () => {
+            const stream = this.streamFor(runDir, attemptId);
+            if (capture.status !== "recording") {
+                stream.sessionEventsStopped = true;
+            }
+            await writeJsonAtomic(path.join(runDir, sessionStreamPaths(attemptId).capture), capture);
+        });
+    }
+    /** Count complete durable session records after both writers have drained. */
+    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,
+            lastEventSeq: events.at(-1)?.seq ?? 0,
+        };
+    }
+    async appendTraceEvent(runDir, runId, event) {
+        const context = this.contextFor(runDir);
         const traceEvent = {
-            seq: this.nextTraceSeq(runDir),
+            seq: context.traceSeq + 1,
             at: new Date().toISOString(),
-            runId: state.runId,
+            runId,
             ...event,
+            payload: (await encodeValue(event.payload, context.artifacts)),
         };
-        await this.appendJsonLine(path.join(runDir, TRACE_PATH), traceEvent);
+        await appendLine(path.join(runDir, TRACE_PATH), traceEvent);
+        context.traceSeq = traceEvent.seq;
         return traceEvent;
     }
-    nextTraceSeq(runDir) {
-        const next = (this.traceSeqByRun.get(runDir) ?? 0) + 1;
-        this.traceSeqByRun.set(runDir, next);
-        return next;
+    async writeProjections(runDir, state) {
+        const context = this.contextFor(runDir);
+        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.streams.values()].some((stream) => stream.sessionBound),
+        }));
     }
-    async appendJsonLine(filePath, value) {
-        const prior = this.appendChainByPath.get(filePath) ?? Promise.resolve();
-        const nextWrite = prior.then(async () => {
-            await fs.mkdir(path.dirname(filePath), { recursive: true });
-            await fs.appendFile(filePath, value === null ? "" : `${JSON.stringify(value)}\n`, "utf8");
-        });
-        const tracked = nextWrite.finally(() => {
-            if (this.appendChainByPath.get(filePath) === tracked) {
-                this.appendChainByPath.delete(filePath);
+    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;
             }
-        });
-        this.appendChainByPath.set(filePath, tracked);
-        await tracked;
+            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`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+async function appendLines(filePath, values) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const text = values.map((value) => `${JSON.stringify(value)}\n`).join("");
+    await fs.appendFile(filePath, text, { encoding: "utf8", mode: 0o600 });
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function validateSessionEventRecord(record) {
+    if (!Number.isSafeInteger(record.seq) || record.seq < 1) {
+        throw new Error("Session event seq must be a positive safe integer");
+    }
+    if (!isNonEmptyString(record.at) ||
+        !isNonEmptyString(record.nodeId) ||
+        !isNonEmptyString(record.attemptId) ||
+        !isNonEmptyString(record.type) ||
+        typeof record.payload !== "object" ||
+        record.payload === null ||
+        Array.isArray(record.payload)) {
+        throw new Error("Session event is missing required envelope fields");
+    }
+    const knownType = [
+        "turn_started",
+        "turn_finished",
+        "message_started",
+        "assistant_event",
+        "message_finished",
+        "tool_execution_started",
+        "tool_execution_updated",
+        "tool_execution_finished",
+    ].includes(record.type);
+    if (!knownType) {
+        return;
+    }
+    if (!isNonEmptyString(record.turnId)) {
+        throw new Error(`${record.type} requires turnId`);
+    }
+    if (!["turn_started", "turn_finished"].includes(record.type) &&
+        !isNonEmptyString(record.messageId)) {
+        throw new Error(`${record.type} requires messageId`);
+    }
+    if (record.type.startsWith("tool_execution_") && !isNonEmptyString(record.toolCallId)) {
+        throw new Error(`${record.type} requires toolCallId`);
+    }
+}
+function sessionRelationshipDiagnostics(entries, events) {
+    const entryIds = new Set(entries.flatMap((record) => (isNonEmptyString(record.entry.id) ? [record.entry.id] : [])));
+    const turns = new Set();
+    const messages = new Set();
+    const tools = new Set();
+    const diagnostics = [];
+    for (const event of events) {
+        switch (event.type) {
+            case "turn_started":
+                if (event.turnId)
+                    turns.add(event.turnId);
+                break;
+            case "turn_finished":
+                if (!event.turnId || !turns.has(event.turnId)) {
+                    diagnostics.push(`turn_finished ${event.seq} precedes turn_started`);
+                }
+                break;
+            case "message_started":
+                if (!event.turnId || !turns.has(event.turnId)) {
+                    diagnostics.push(`message_started ${event.seq} precedes turn_started`);
+                }
+                if (event.messageId)
+                    messages.add(event.messageId);
+                break;
+            case "assistant_event":
+                if (!event.messageId || !messages.has(event.messageId)) {
+                    diagnostics.push(`assistant_event ${event.seq} precedes message_started`);
+                }
+                break;
+            case "message_finished": {
+                if (!event.messageId || !messages.has(event.messageId)) {
+                    diagnostics.push(`message_finished ${event.seq} precedes message_started`);
+                }
+                const settled = event.payload.settled;
+                const entryId = event.payload.entryId;
+                if (settled === true && (!isNonEmptyString(entryId) || !entryIds.has(entryId))) {
+                    diagnostics.push(`message_finished ${event.seq} references a missing entry`);
+                }
+                else if (settled !== true && entryId !== undefined) {
+                    diagnostics.push(`message_finished ${event.seq} has entryId while unsettled`);
+                }
+                break;
+            }
+            case "tool_execution_started":
+                if (!event.messageId || !messages.has(event.messageId)) {
+                    diagnostics.push(`tool_execution_started ${event.seq} precedes message_started`);
+                }
+                if (event.toolCallId)
+                    tools.add(event.toolCallId);
+                break;
+            case "tool_execution_updated":
+            case "tool_execution_finished":
+                if (!event.toolCallId || !tools.has(event.toolCallId)) {
+                    diagnostics.push(`${event.type} ${event.seq} precedes tool_execution_started`);
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    return diagnostics;
+}
+function validateSessionCapture(capture) {
+    if (capture.schema !== SESSION_CAPTURE_SCHEMA ||
+        capture.eventSchema !== SESSION_EVENT_SCHEMA ||
+        !["recording", "complete", "failed"].includes(capture.status) ||
+        !Number.isSafeInteger(capture.eventCount) ||
+        capture.eventCount < 0 ||
+        !Number.isSafeInteger(capture.entryCount) ||
+        capture.entryCount < 0 ||
+        !Number.isSafeInteger(capture.lastEventSeq) ||
+        capture.lastEventSeq < 0) {
+        throw new Error("Invalid session capture projection");
+    }
+    if (capture.status === "failed" && capture.failure === undefined) {
+        throw new Error("Failed session capture requires failure details");
+    }
+    if (capture.status !== "failed" && capture.failure !== undefined) {
+        throw new Error("Only failed session capture may contain failure details");
+    }
+}
+async function readCompleteNdjson(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const lines = raw.split("\n");
+    if (!raw.endsWith("\n")) {
+        lines.pop();
+    }
+    const records = [];
+    for (const line of lines) {
+        if (line.trim().length === 0) {
+            continue;
+        }
+        try {
+            const value = JSON.parse(line);
+            if (!Number.isSafeInteger(value.seq) || value.seq < 1) {
+                break;
+            }
+            records.push({ seq: value.seq });
+        }
+        catch {
+            break;
+        }
+    }
+    return records;
+}
+/**
+ * Encode the externalizable value positions of the state document. The
+ * in-memory state always holds raw values; the persisted copy may carry
+ * `$artifact` references instead of large strings.
+ */
+async function encodeRunState(state, artifacts) {
+    const results = Object.fromEntries(await Promise.all(Object.entries(state.results).map(async ([nodeId, result]) => [
+        nodeId,
+        "output" in result
+            ? { ...result, output: await encodeValue(result.output, artifacts) }
+            : result,
+    ])));
+    return {
+        ...state,
+        input: await encodeValue(state.input, artifacts),
+        outputs: Object.fromEntries(await Promise.all(Object.entries(state.outputs).map(async ([nodeId, output]) => [
+            nodeId,
+            await encodeValue(output, artifacts),
+        ]))),
+        results,
+        steps: await Promise.all(state.steps.map(async (step) => ({
+            ...step,
+            prompt: (await encodeValue(step.prompt, artifacts)),
+            output: await encodeValue(step.output, artifacts),
+        }))),
+        ...(state.finalOutput !== undefined
+            ? { finalOutput: await encodeValue(state.finalOutput, 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));
-    const state = await readJsonFile(path.join(runDir, STATE_PATH));
-    if (!manifest || !state || manifest.schema !== RUN_BUNDLE_SCHEMA) {
+    if (!manifest || manifest.schema !== RUN_BUNDLE_SCHEMA) {
+        return null;
+    }
+    // A schema-tagged manifest may still be malformed (e.g. hand-edited);
+    // treat anything unexpected as an unreadable bundle rather than throwing.
+    const paths = typeof manifest.paths === "object" && manifest.paths !== null ? manifest.paths : {};
+    const state = await readJsonFile(resolveBundlePath(runDir, paths.state, STATE_PATH));
+    if (!state || state.schema !== RUN_STATE_SCHEMA) {
         return null;
     }
-    const snapshot = await readJsonFile(path.join(runDir, WORKFLOW_SNAPSHOT_PATH));
-    return { runDir, manifest, state, snapshot };
+    const snapshot = await readJsonFile(resolveBundlePath(runDir, paths.workflow, WORKFLOW_SNAPSHOT_PATH));
+    const sessionDir = resolveBundlePath(runDir, paths.session, SESSION_DIR);
+    const sessionBinding = await readJsonFile(path.join(sessionDir, "binding.json"));
+    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 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,
+        state,
+        snapshot,
+        sessionBinding,
+        sessionEntries: entries.records,
+        sessionEvents: events.records,
+        sessionCapture,
+        sessionIntegrity,
+        sessionSegments,
+    };
+}
+/**
+ * Resolve a manifest-relative path, rejecting anything that is not a string
+ * or escapes the bundle directory. Malformed manifests must degrade to an
+ * unreadable bundle, never to a thrown error that aborts a listing.
+ */
+function resolveBundlePath(runDir, relative, fallback) {
+    const candidate = path.resolve(runDir, typeof relative === "string" && relative ? relative : fallback);
+    if (candidate !== path.resolve(runDir) &&
+        !candidate.startsWith(path.resolve(runDir) + path.sep)) {
+        return path.join(runDir, fallback);
+    }
+    return candidate;
 }
 /** List run bundles under `outputRoot`, most recently started first. */
 export async function listRunBundles(outputRoot) {
@@ -128,7 +900,102 @@ async function readJsonFile(filePath) {
         return null;
     }
 }
-function createManifest(state) {
+async function readNdjsonFile(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return { records: [], exists: false, tornTail: false, malformed: false };
+    }
+    const tornTail = raw.length > 0 && !raw.endsWith("\n");
+    const lines = raw.split("\n");
+    if (tornTail) {
+        lines.pop();
+    }
+    const records = [];
+    let malformed = false;
+    for (const line of lines) {
+        if (line.trim().length === 0) {
+            continue;
+        }
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch {
+            malformed = true;
+        }
+    }
+    return { records, exists: true, tornTail, malformed };
+}
+function assessSessionIntegrity(input) {
+    const anySessionFile = input.binding !== null || input.entries.exists || input.events.exists || input.capture !== null;
+    if (!anySessionFile) {
+        return { status: "unavailable", diagnostics: [] };
+    }
+    const diagnostics = [];
+    if (!input.binding || input.binding.schema !== SESSION_BINDING_SCHEMA) {
+        diagnostics.push("missing or invalid session binding");
+    }
+    if (!input.capture) {
+        diagnostics.push("missing session capture status");
+        return { status: "invalid", diagnostics };
+    }
+    try {
+        validateSessionCapture(input.capture);
+    }
+    catch (error) {
+        diagnostics.push(failureMessageForDiagnostic(error));
+        return { status: "invalid", diagnostics };
+    }
+    if (input.entries.malformed || input.events.malformed) {
+        diagnostics.push("malformed NDJSON line before the journal tail");
+    }
+    if (input.events.tornTail && input.capture.status !== "recording") {
+        diagnostics.push("terminal session event journal has a torn tail");
+    }
+    if (input.runTerminal && input.capture.status === "recording") {
+        diagnostics.push("terminal run still reports recording capture");
+    }
+    let expected = 1;
+    for (const event of input.events.records) {
+        try {
+            validateSessionEventRecord(event);
+        }
+        catch (error) {
+            diagnostics.push(failureMessageForDiagnostic(error));
+            break;
+        }
+        if (event.seq !== expected) {
+            diagnostics.push(`session event sequence gap at ${expected}`);
+            break;
+        }
+        expected += 1;
+    }
+    diagnostics.push(...sessionRelationshipDiagnostics(input.entries.records, input.events.records));
+    if (input.capture.status !== "recording") {
+        const lastEventSeq = input.events.records.at(-1)?.seq ?? 0;
+        if (input.capture.eventCount !== input.events.records.length ||
+            input.capture.entryCount !== input.entries.records.length ||
+            input.capture.lastEventSeq !== lastEventSeq) {
+            diagnostics.push("session capture counts do not match durable files");
+        }
+    }
+    if (diagnostics.length > 0) {
+        return { status: "invalid", diagnostics };
+    }
+    if (input.capture.status === "failed") {
+        return {
+            status: "failed",
+            diagnostics: [input.capture.failure?.message ?? "session capture failed"],
+        };
+    }
+    return { status: input.capture.status, diagnostics: [] };
+}
+function failureMessageForDiagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function createManifest(state, present) {
     return {
         schema: RUN_BUNDLE_SCHEMA,
         runId: state.runId,
@@ -143,6 +1010,11 @@ function createManifest(state) {
             workflow: WORKFLOW_SNAPSHOT_PATH,
             state: STATE_PATH,
             trace: TRACE_PATH,
+            ...(present.session ? { session: SESSION_DIR } : {}),
+            // Declare this before any payload can externalize a string. Live
+            // session-event patches may reference a newly written artifact before
+            // the next workflow state projection refreshes the manifest.
+            artifacts: "artifacts",
         },
     };
 }
@@ -174,8 +1046,11 @@ function snapshotNode(node) {
 }
 async function writeJsonAtomic(filePath, value) {
     const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
     await fs.rename(tempPath, filePath);
 }
 //# sourceMappingURL=store.js.map