@intx/hub-sessions 0.3.0 → 0.4.0

package/dist/workflow-run-kind.js

@@ -165,8 +165,7 @@ import fs from "node:fs";
 import git from "isomorphic-git";
 import { type } from "arktype";
 import { getLogger } from "@intx/log";
-import { glob, repoActionToGrantVerb } from "@intx/hub-common";
-import { UserPrincipal, } from "./repo-store/index.js";
+import { authorizeUserPrincipal, } from "./repo-store/index.js";
 import { WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, encodeCombinedEventLog, } from "./workflow-run-event-log.js";
 const logger = getLogger(["hub-sessions", "workflow-run-kind"]);
 export const WORKFLOW_RUN_GITIGNORE_PATH = ".gitignore";
@@ -179,6 +178,20 @@ export const WORKFLOW_RUN_CONTROL_PREFIX = "control";
 export const WORKFLOW_RUN_INBOX_DIR = "inbox";
 export const WORKFLOW_RUN_PROCESSING_DIR = "processing";
 export const WORKFLOW_RUN_CONSUMED_DIR = "consumed";
+/**
+ * Per-run inbound mail-part subtree. Non-text inbound mail content
+ * (image/audio/video/document mail parts) is committed here as real
+ * files rather than inlined into the JSON event log, whose serialization
+ * boundary would corrupt binary bytes. The layout is
+ * `runs/<runId>/parts/<urlEncoded(messageId)>/<index>-<name>`: one
+ * directory per inbound message (so a long-lived run's successive turns
+ * never collide), and one file per mail part carrying its verbatim
+ * bytes. The workflow-host ingest writes the bytes and records a
+ * lightweight `{ name, contentType, ref }` reference into the run's
+ * trigger / signal payload; the step invoker reads the bytes back at
+ * `agent.send` time. Files are immutable once written, like `blobs/`.
+ */
+export const WORKFLOW_RUN_PARTS_DIR = "parts";
 /**
  * Filename of the per-address retention watermark blob, a direct child
  * of `addresses/<urlEncoded>/` (a file, not a directory). Carries the
@@ -235,6 +248,38 @@ export const DEFAULT_CONSUMED_RETENTION_MS = 24 * 60 * 60 * 1000;
  * `<agentKey>` directory layer below the prefix).
  */
 export const WORKFLOW_RUN_AGENT_STATE_PREFIX = "agent-state";
+/**
+ * Conversational-mailbox subtree for the warm single-step agent. The
+ * substrate mailbox backing commits the agent's durable inbox under
+ * `mailbox/INBOX/` so the full message history replicates to the hub
+ * alongside the run state. The layout is:
+ *
+ *   - `mailbox/INBOX/index.json` — the mailbox index. MUTABLE: the
+ *     backing rewrites it on every flush, so it is exempt from the
+ *     retained-blob byte-equality walk the `<uid>.eml` blobs are subject
+ *     to. It must nonetheless PERSIST once it existed: dropping it drops
+ *     the whole mailbox and resets uidValidity/uidNext on the next open.
+ *   - `mailbox/INBOX/<uid>.eml` — one message per file, carrying the
+ *     raw signed message bytes. `<uid>` is a decimal integer >= 1. A
+ *     RETAINED `<uid>.eml` (present in both prior and prospective) is
+ *     opaque and IMMUTABLE: it must reappear byte-identically, exactly
+ *     like `runs/<runId>/blobs/`. A prior `<uid>.eml` may be ABSENT from
+ *     the prospective tree — that is the warm agent expunging a message.
+ *     The raw bytes are not lost: they stay reachable through the parent
+ *     commit, and a `workflow-run` repo's objects are never GC'd (its
+ *     kind is off the GC allow-list), so an expunged message survives in
+ *     history for the life of the run repo. The audit trail rests on
+ *     "these objects are never pruned", not on the live tree being
+ *     monotonic.
+ *
+ * The only entries permitted under `mailbox/` are the `INBOX/`
+ * directory; the only entries permitted under `mailbox/INBOX/` are
+ * `index.json` and `<uid>.eml` message files. Anything else fails the
+ * push.
+ */
+export const WORKFLOW_RUN_MAILBOX_PREFIX = "mailbox";
+export const WORKFLOW_RUN_MAILBOX_INBOX_DIR = "INBOX";
+export const WORKFLOW_RUN_MAILBOX_INDEX_FILE = "index.json";
 /**
  * Allowed top-level entries in the prospective tree. Anything else
  * fails the push. `control/` has no v1 use and stays absent.
@@ -243,8 +288,16 @@ const ALLOWED_TOP_LEVEL = new Set([
     WORKFLOW_RUN_RUNS_PREFIX,
     WORKFLOW_RUN_ADDRESSES_PREFIX,
     WORKFLOW_RUN_AGENT_STATE_PREFIX,
+    WORKFLOW_RUN_MAILBOX_PREFIX,
     WORKFLOW_RUN_GITIGNORE_PATH,
 ]);
+/**
+ * Per-message filename shape for the `mailbox/INBOX/` subtree:
+ * `<uid>.eml`, where `<uid>` is a decimal integer >= 1 (no leading zero,
+ * never `0`). Pins the shape so a malformed message name fails the push
+ * at the boundary rather than landing silently.
+ */
+const MAILBOX_EML_FILENAME_RE = /^[1-9][0-9]*\.eml$/;
 const CLAIM_CHECK_SUBDIRS = new Set([
     WORKFLOW_RUN_INBOX_DIR,
     WORKFLOW_RUN_PROCESSING_DIR,
@@ -297,6 +350,30 @@ export function requireEventSeq(filename, context) {
  * silently.
  */
 const BLOB_FILENAME_RE = /^[0-9a-f]{64}$/;
+/**
+ * Per-mail-part filename shape for the
+ * `runs/<runId>/parts/<urlEncoded(messageId)>/` subtree:
+ * `<index>-<name>`, where `index` is the decimal position of the
+ * mail part within its inbound message and `name` is a non-empty
+ * (possibly sanitized) filename. The workflow-host ingest owns the exact
+ * encoding and sanitizes untrusted names to satisfy this shape; this regex
+ * pins the shape so a malformed name fails the push rather than landing
+ * silently. The bytes themselves are opaque and immutable, exactly like
+ * `blobs/`.
+ */
+const PART_FILENAME_RE = /^(0|[1-9][0-9]*)-(.+)$/;
+/**
+ * Maximum byte length of a single mail part path component (the
+ * URL-encoded message segment, and each `<index>-<name>` filename).
+ * messageIds and mail part names arrive from untrusted inbound mail;
+ * an over-long RFC 5322 message-id URL-encodes past the filesystem's
+ * 255-byte component limit and would otherwise fail at disk-write time,
+ * downstream of validation. Reject it at the boundary instead.
+ */
+export const MAX_MAIL_PART_PATH_COMPONENT_BYTES = 255;
+function mailPartComponentByteLength(component) {
+    return new TextEncoder().encode(component).length;
+}
 /**
  * Entries the kind handler accepts under `runs/<runId>/`. The `events/`
  * subtree carries the append-only event log; the `blobs/` subtree carries
@@ -315,6 +392,10 @@ const RUN_DIR_ALLOWED_CHILDREN = new Set([
     // files into one combined file by a compaction commit.
     WORKFLOW_RUN_EVENTS_FILE,
     WORKFLOW_RUN_GRANTS_FILE,
+    // Inbound-mail mail part bytes committed as real files. See
+    // WORKFLOW_RUN_PARTS_DIR; validated by enumerateRunParts and
+    // held immutable by the same prior-tree byte-equality walk as blobs.
+    WORKFLOW_RUN_PARTS_DIR,
 ]);
 /**
  * Filename shape for inbox and processing entries:
@@ -390,22 +471,6 @@ const WatermarkEnvelope = type({
     watermark: "number >= 0",
     "+": "ignore",
 });
-/**
- * Terminal event discriminators mapped to the `workflow_run.status` value
- * each settles the run into. A run whose log contains an entry with one of
- * these `type` values must not receive any event with a strictly greater
- * seq.
- *
- * This map is a hand-rolled copy of the runtime's terminal-run vocabulary
- * (`isTerminalRunPhase` in `@intx/workflow` state-machine `state.ts`,
- * re-exported from the state-machine index and consumed by `transition.ts`),
- * duplicated here because `@intx/hub-sessions` must not depend on
- * `@intx/workflow`. It is the sole authority for that vocabulary and MUST
- * stay in sync with the canonical runtime definition:
- * if the runtime adds or removes a terminal run phase, update this map too.
- * Drift silently reopens the restore-time double-driver collision that
- * `readOwnedMessageIds` (below) exists to prevent.
- */
 const TERMINAL_EVENT_STATUS = new Map([
     ["RunCompleted", "completed"],
     ["RunFailed", "failed"],
@@ -417,6 +482,27 @@ const TERMINAL_EVENT_STATUS = new Map([
  * the two cannot drift apart.
  */
 const TERMINAL_EVENT_TYPES = new Set(TERMINAL_EVENT_STATUS.keys());
+/**
+ * Classify a workflow-run event type against the terminal-status vocabulary.
+ * `TERMINAL_EVENT_STATUS` is the sole authority (see above), so a type absent
+ * from it is by definition not terminal: no separate membership set is
+ * consulted and no "unmapped terminal type" case can arise.
+ */
+export function classifyTerminalEvent(eventType) {
+    const status = TERMINAL_EVENT_STATUS.get(eventType);
+    return status === undefined
+        ? { terminal: false }
+        : { terminal: true, status };
+}
+/**
+ * True when a blob is absent from the prior tree -- i.e. this commit is the
+ * one that authored it. Consumers act only on a newly-added blob; a blob
+ * already present in the prior tree was carried forward unchanged by a
+ * compaction commit and must not be re-acted upon.
+ */
+async function blobIsNewlyAdded(blobPath, priorReadBlob) {
+    return (await priorReadBlob(blobPath)) === null;
+}
 /**
  * Recognised CancelRequested origins. Mirrors the workflow package's
  * `CANCEL_ORIGINS` vocabulary; inlined here so the substrate does
@@ -550,7 +636,7 @@ async function enumerateEventBlobs(listDir, scopeRunIds) {
         if (offender !== undefined) {
             return {
                 ok: false,
-                reason: `run directory ${runDirPath} contains unexpected entry ${JSON.stringify(offender)}; only "${WORKFLOW_RUN_EVENTS_DIR}", "${WORKFLOW_RUN_BLOBS_DIR}", "${WORKFLOW_RUN_EVENTS_FILE}", and "${WORKFLOW_RUN_GRANTS_FILE}" are allowed`,
+                reason: `run directory ${runDirPath} contains unexpected entry ${JSON.stringify(offender)}; only "${WORKFLOW_RUN_EVENTS_DIR}", "${WORKFLOW_RUN_BLOBS_DIR}", "${WORKFLOW_RUN_EVENTS_FILE}", "${WORKFLOW_RUN_GRANTS_FILE}", and "${WORKFLOW_RUN_PARTS_DIR}" are allowed`,
             };
         }
         const hasCombined = runChildren.includes(WORKFLOW_RUN_EVENTS_FILE);
@@ -566,14 +652,16 @@ async function enumerateEventBlobs(listDir, scopeRunIds) {
         if (hasCombined)
             continue;
         if (!hasPerEvent) {
-            // A run dir whose only child is `grants.json` is the legitimate
-            // pre-first-event window: the hub's `run.grants` frame writes the
-            // grants ahead of the trigger, so the grants file lands before the
-            // child emits its first event. Carry it forward untouched -- there is
-            // no event log to enumerate yet. Any other events-less shape (e.g. a
-            // bare `blobs/` with no events) remains rejected below.
-            if (runChildren.length === 1 &&
-                runChildren[0] === WORKFLOW_RUN_GRANTS_FILE) {
+            // The pre-first-event window: `grants.json` (the hub's `run.grants`
+            // frame writes grants ahead of the trigger) and `parts/` (the
+            // supervisor commits inbound-mail mail part bytes before firing the
+            // trigger) may both land before the child emits its first event. Carry
+            // such a run forward untouched -- there is no event log to enumerate
+            // yet, and the mail parts subtree is validated by its own walk. Any
+            // other events-less shape (e.g. a bare `blobs/` with no events) remains
+            // rejected below.
+            const nonPreEvent = runChildren.filter((c) => c !== WORKFLOW_RUN_GRANTS_FILE && c !== WORKFLOW_RUN_PARTS_DIR);
+            if (nonPreEvent.length === 0) {
                 continue;
             }
             return {
@@ -814,6 +902,159 @@ async function enumerateRunBlobs(listDir, scopeRunIds) {
     }
     return { ok: true, blobs: out };
 }
+/**
+ * Walk every `runs/<runId>/parts/<messageSegment>/` directory and
+ * validate each entry: the `<messageSegment>` is a URL-encoded messageId
+ * that must round-trip cleanly (the same canonical-encoding discipline the
+ * claim-check `addresses/` subtree enforces) and stay within the path-
+ * component byte cap, must be a directory rather than a dangling blob, and
+ * each filename matches the `<index>-<name>` shape within the same cap. The
+ * `parts/` subdirectory is optional: a run that never received a
+ * non-text inbound message never produces one. Returns the flat entry list
+ * so the caller can apply immutability checks against the prior tree,
+ * exactly as it does for blobs.
+ */
+async function enumerateRunParts(listDir, scopeRunIds) {
+    const out = [];
+    // See enumerateRunBlobs: a defined `scopeRunIds` walks only the commit's
+    // touched runs; an untouched run's mail parts are carried forward
+    // byte-identical and were validated when written.
+    const runIds = scopeRunIds === undefined
+        ? await listDir(WORKFLOW_RUN_RUNS_PREFIX)
+        : Array.from(scopeRunIds);
+    for (const runId of runIds) {
+        const runDirPath = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}`;
+        const runChildren = await listDir(runDirPath);
+        if (!runChildren.includes(WORKFLOW_RUN_PARTS_DIR))
+            continue;
+        const partsDirPath = `${runDirPath}/${WORKFLOW_RUN_PARTS_DIR}`;
+        const messageSegments = await listDir(partsDirPath);
+        for (const messageSegment of messageSegments) {
+            const roundTrip = checkUrlSegmentRoundTrip(messageSegment);
+            if (!roundTrip.ok) {
+                return {
+                    ok: false,
+                    reason: `mail part message ${roundTrip.reason} under ${partsDirPath}`,
+                };
+            }
+            if (mailPartComponentByteLength(messageSegment) >
+                MAX_MAIL_PART_PATH_COMPONENT_BYTES) {
+                return {
+                    ok: false,
+                    reason: `mail part message segment ${JSON.stringify(messageSegment)} under ${partsDirPath} exceeds the ${String(MAX_MAIL_PART_PATH_COMPONENT_BYTES)}-byte path-component limit`,
+                };
+            }
+            const messageDirPath = `${partsDirPath}/${messageSegment}`;
+            const filenames = await listDir(messageDirPath);
+            // A message segment must be a directory carrying at least one
+            // mail part file. An empty listing means either a dangling blob
+            // committed directly at `parts/<segment>` (the substrate lists a
+            // blob path as empty, exactly as the agent-state walk detects) or an
+            // empty directory; both are rejected so untrusted inbound content has
+            // no silent-accept path.
+            if (filenames.length === 0) {
+                return {
+                    ok: false,
+                    reason: `mail part message segment ${JSON.stringify(messageSegment)} under ${partsDirPath} is not a directory carrying mail part files`,
+                };
+            }
+            for (const filename of filenames) {
+                if (!PART_FILENAME_RE.test(filename)) {
+                    return {
+                        ok: false,
+                        reason: `mail part filename ${messageDirPath}/${filename} does not match <index>-<name>`,
+                    };
+                }
+                if (mailPartComponentByteLength(filename) >
+                    MAX_MAIL_PART_PATH_COMPONENT_BYTES) {
+                    return {
+                        ok: false,
+                        reason: `mail part filename ${messageDirPath}/${filename} exceeds the ${String(MAX_MAIL_PART_PATH_COMPONENT_BYTES)}-byte path-component limit`,
+                    };
+                }
+                // Each mail part entry must be a leaf blob, not a nested directory.
+                // The `<index>-<name>` shape is permissive (`.+`), so a directory
+                // named e.g. `0-foo` would otherwise pass and admit an arbitrarily
+                // nested subtree, breaking the one-file-per-mail-part invariant and
+                // -- on a pack-receive validation with no `listDirOids` -- driving the
+                // immutability resolver to `readBlob` a tree path and throw. A blob
+                // lists as empty; a directory lists its children.
+                const filePath = `${messageDirPath}/${filename}`;
+                if ((await listDir(filePath)).length > 0) {
+                    return {
+                        ok: false,
+                        reason: `mail part ${filePath} is a directory; each mail part must be a single file`,
+                    };
+                }
+                out.push({
+                    runId,
+                    messageSegment,
+                    filename,
+                    blobPath: filePath,
+                });
+            }
+        }
+    }
+    return { ok: true, parts: out };
+}
+/**
+ * Validate the per-run `parts/` subtree's immutability against the
+ * prior tree, both directions, mirroring the blobs walk. Mail part files
+ * are write-once. A path present in the prior tree must carry the same git
+ * blob OID in the prospective tree: unlike `blobs/`, a mail part filename
+ * is `<index>-<name>` (not a content hash), so the same path can carry
+ * different bytes -- the OID compare is the load-bearing immutability guard,
+ * and comparing the OID git already computed avoids re-reading tens of MB of
+ * mail part bytes on every commit that merely touches the run. A prior path
+ * must reappear (no deletion): run reclaim drops the whole `runs/<runId>/`
+ * subtree outside `validatePush`, so a partial mail part deletion is always
+ * a violation. Structural shape is enforced by `enumerateRunParts`.
+ */
+async function validateRunPartsSubtree(args) {
+    const prospective = await enumerateRunParts(args.listDir, args.scopeRunIds);
+    if (!prospective.ok)
+        return prospective;
+    const prior = await enumerateRunParts(args.priorListDir, args.scopeRunIds);
+    if (!prior.ok) {
+        return {
+            ok: false,
+            reason: `prior tree's mail parts subtree is structurally invalid: ${prior.reason}`,
+        };
+    }
+    const prospectiveOid = makeListingOidResolver("prospective", args.listDirOids, async (p) => (await git.hashBlob({ object: await args.readBlob(p) })).oid);
+    const priorOid = makeListingOidResolver("prior", args.priorListDirOids, async (p) => {
+        const bytes = await args.priorReadBlob(p);
+        if (bytes === null) {
+            throw new Error(`mail parts: prior entry ${p} was enumerated but its bytes could not be read`);
+        }
+        return (await git.hashBlob({ object: bytes })).oid;
+    });
+    const prospectivePaths = new Set(prospective.parts.map((e) => e.blobPath));
+    const priorPaths = new Set(prior.parts.map((e) => e.blobPath));
+    for (const entry of prospective.parts) {
+        if (!priorPaths.has(entry.blobPath))
+            continue; // newly added
+        const [next, before] = await Promise.all([
+            prospectiveOid(entry.blobPath),
+            priorOid(entry.blobPath),
+        ]);
+        if (next !== before) {
+            return {
+                ok: false,
+                reason: `mail part ${entry.blobPath} bytes diverge from the prior tree (blob OID ${next} vs ${before}); mail part files are immutable once written`,
+            };
+        }
+    }
+    for (const entry of prior.parts) {
+        if (prospectivePaths.has(entry.blobPath))
+            continue;
+        return {
+            ok: false,
+            reason: `mail part ${entry.blobPath} present in the prior tree is missing from the prospective tree; mail part files are immutable once written`,
+        };
+    }
+    return { ok: true };
+}
 /**
  * Enforce blob immutability via prior-tree byte equality. The blob
  * value itself is opaque bytes (no JSON envelope, no arktype
@@ -925,13 +1166,16 @@ async function checkPriorByteEquality(blobPath, readBlob, priorReadBlob) {
     return { ok: true };
 }
 /**
- * Round-trip an `<urlEncoded(address)>` segment through decode then
- * encode. A divergence means the segment is not the canonical
- * encoding of any address, which would leave consumers guessing
- * which encoding to use when reading the subtree. Surface as a
- * concrete rejection at push time.
+ * Round-trip a URL-encoded path segment through decode then encode. A
+ * divergence means the segment is not the canonical encoding of any
+ * value, which would leave consumers guessing which encoding to use
+ * when reading the subtree. Surface as a concrete rejection at push
+ * time. Shared by every subtree that keys a directory by an
+ * `encodeURIComponent`-encoded identity (`addresses/`, `agent-state/`,
+ * and the per-run `parts/` message segment); callers prepend
+ * their own subtree context to the returned reason.
  */
-function checkAddressSegmentRoundTrip(segment) {
+function checkUrlSegmentRoundTrip(segment) {
     let decoded;
     try {
         decoded = decodeURIComponent(segment);
@@ -939,14 +1183,14 @@ function checkAddressSegmentRoundTrip(segment) {
     catch (cause) {
         return {
             ok: false,
-            reason: `address segment ${JSON.stringify(segment)} is not a valid URL-encoded string: ${cause instanceof Error ? cause.message : String(cause)}`,
+            reason: `segment ${JSON.stringify(segment)} is not a valid URL-encoded string: ${cause instanceof Error ? cause.message : String(cause)}`,
         };
     }
     const reencoded = encodeURIComponent(decoded);
     if (reencoded !== segment) {
         return {
             ok: false,
-            reason: `address segment ${JSON.stringify(segment)} does not round-trip URL-encoding (re-encoded as ${JSON.stringify(reencoded)})`,
+            reason: `segment ${JSON.stringify(segment)} does not round-trip URL-encoding (re-encoded as ${JSON.stringify(reencoded)})`,
         };
     }
     return { ok: true, decoded };
@@ -979,9 +1223,10 @@ async function enumerateClaimCheckBlobs(listDir, resolveConsumedOid) {
     const perAddress = new Map();
     const segments = await listDir(WORKFLOW_RUN_ADDRESSES_PREFIX);
     for (const segment of segments) {
-        const roundTrip = checkAddressSegmentRoundTrip(segment);
-        if (!roundTrip.ok)
-            return roundTrip;
+        const roundTrip = checkUrlSegmentRoundTrip(segment);
+        if (!roundTrip.ok) {
+            return { ok: false, reason: `address ${roundTrip.reason}` };
+        }
         const addrDir = `${WORKFLOW_RUN_ADDRESSES_PREFIX}/${segment}`;
         const children = await listDir(addrDir);
         for (const child of children) {
@@ -1695,11 +1940,11 @@ async function validateAgentStateSubtree(topLevelTreePaths, listDir) {
     }
     const segments = await listDir(WORKFLOW_RUN_AGENT_STATE_PREFIX);
     for (const segment of segments) {
-        const roundTrip = checkAddressSegmentRoundTrip(segment);
+        const roundTrip = checkUrlSegmentRoundTrip(segment);
         if (!roundTrip.ok) {
             return {
                 ok: false,
-                reason: `agent-state segment ${JSON.stringify(segment)} does not round-trip URL-encoding; ${roundTrip.reason}`,
+                reason: `agent-state ${roundTrip.reason}`,
             };
         }
         // Reject a blob dangling directly at `agent-state/<segment>`: every
@@ -1716,6 +1961,149 @@ async function validateAgentStateSubtree(topLevelTreePaths, listDir) {
     }
     return { ok: true };
 }
+/**
+ * Enforce mailbox `<uid>.eml` immutability via prior-tree byte equality.
+ * A message blob RETAINED from the prior tree (present in both) must carry
+ * byte-identical contents in the prospective tree. A prior blob absent
+ * from the prospective tree is a legal expunge and never reaches here
+ * (the caller only checks retained paths). Mirrors the blob-immutability
+ * discipline (`checkBlobPriorByteEquality`) with mailbox-specific wording.
+ */
+async function checkMailboxEmlPriorByteEquality(emlPath, readBlob, priorReadBlob) {
+    const prior = await priorReadBlob(emlPath);
+    if (prior === null)
+        return { ok: true };
+    const prospective = await readBlob(emlPath);
+    if (prior.byteLength !== prospective.byteLength) {
+        return {
+            ok: false,
+            reason: `mailbox message ${emlPath} bytes diverge from the prior tree (lengths ${String(prior.byteLength)} vs ${String(prospective.byteLength)}); a retained mailbox message is immutable`,
+        };
+    }
+    for (let i = 0; i < prior.byteLength; i++) {
+        if (prior[i] !== prospective[i]) {
+            return {
+                ok: false,
+                reason: `mailbox message ${emlPath} bytes diverge from the prior tree at offset ${String(i)}; a retained mailbox message is immutable`,
+            };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Walk the `mailbox/INBOX/` subtree and validate its shape. The only
+ * entry permitted directly under `mailbox/` is the `INBOX/` directory;
+ * the only entries permitted under `mailbox/INBOX/` are the mutable
+ * `index.json` file and `<uid>.eml` message files. Each entry must be a
+ * leaf blob rather than a nested directory (a blob lists as empty, a
+ * directory lists its children -- the same discrimination the agent-state
+ * and mail-parts walks use). Returns the flat set of `<uid>.eml` blob
+ * paths so the caller can hold retained messages immutable against the
+ * prior tree, plus `indexPresent` -- whether `index.json` exists under
+ * the INBOX -- so the caller can enforce index continuity. An absent
+ * `mailbox/` subtree lists as empty and contributes no message paths.
+ */
+async function enumerateMailboxInbox(listDir) {
+    const emlPaths = new Set();
+    let indexPresent = false;
+    const mailboxChildren = await listDir(WORKFLOW_RUN_MAILBOX_PREFIX);
+    if (mailboxChildren.length === 0)
+        return { ok: true, emlPaths, indexPresent };
+    for (const child of mailboxChildren) {
+        if (child !== WORKFLOW_RUN_MAILBOX_INBOX_DIR) {
+            return {
+                ok: false,
+                reason: `mailbox subtree contains unexpected entry ${JSON.stringify(child)} under ${WORKFLOW_RUN_MAILBOX_PREFIX}/; only "${WORKFLOW_RUN_MAILBOX_INBOX_DIR}" is allowed`,
+            };
+        }
+    }
+    const inboxPath = `${WORKFLOW_RUN_MAILBOX_PREFIX}/${WORKFLOW_RUN_MAILBOX_INBOX_DIR}`;
+    const inboxEntries = await listDir(inboxPath);
+    // A `mailbox/` top-level whose `INBOX` child carries no entries is a
+    // dangling blob committed directly at `mailbox/INBOX` (a blob lists as
+    // empty), not the required directory. Git never records an empty
+    // directory, so a present-but-empty listing is always the blob case.
+    if (inboxEntries.length === 0) {
+        return {
+            ok: false,
+            reason: `mailbox ${inboxPath} is a blob, not a directory carrying "${WORKFLOW_RUN_MAILBOX_INDEX_FILE}" and <uid>.eml message files`,
+        };
+    }
+    for (const entry of inboxEntries) {
+        const entryPath = `${inboxPath}/${entry}`;
+        if (entry === WORKFLOW_RUN_MAILBOX_INDEX_FILE) {
+            if ((await listDir(entryPath)).length > 0) {
+                return {
+                    ok: false,
+                    reason: `mailbox ${entryPath} is a directory; the mailbox index must be a single file`,
+                };
+            }
+            indexPresent = true;
+            continue;
+        }
+        if (!MAILBOX_EML_FILENAME_RE.test(entry)) {
+            return {
+                ok: false,
+                reason: `mailbox entry ${entryPath} does not match "${WORKFLOW_RUN_MAILBOX_INDEX_FILE}" or <uid>.eml (uid a decimal integer >= 1)`,
+            };
+        }
+        if ((await listDir(entryPath)).length > 0) {
+            return {
+                ok: false,
+                reason: `mailbox message ${entryPath} is a directory; each message must be a single .eml file`,
+            };
+        }
+        emlPaths.add(entryPath);
+    }
+    return { ok: true, emlPaths, indexPresent };
+}
+/**
+ * Validate the `mailbox/INBOX/` subtree (design conversational-mailbox).
+ * Enforces the subtree shape via `enumerateMailboxInbox`, then holds a
+ * RETAINED `<uid>.eml` message blob byte-identical against the prior tree.
+ * A prior `<uid>.eml` absent from the prospective tree is a legal expunge:
+ * the warm agent physically removes a message from the live INBOX. The raw
+ * bytes are not lost -- they stay reachable through the parent commit, and
+ * a `workflow-run` repo's objects are never GC'd (its kind is excluded
+ * from the GC allow-list; see `DEFAULT_GC_KINDS` in `agent-repo`), so the
+ * expunged message survives in history for the life of the run repo. The
+ * audit trail therefore rests on "these objects are never pruned", not on
+ * the live tree being monotonic.
+ *
+ * The `index.json` entry is mutable, but must PERSIST once it existed: if
+ * the prior tree carried an index and the prospective tree drops it, the
+ * whole mailbox has vanished, which would reset `uidValidity` / `uidNext`
+ * on the next open and force uid reuse from 1. That is rejected. A
+ * well-behaved backing always rewrites `index.json` on flush, so the guard
+ * fails no legitimate push. Mirrors the blob-immutability discipline the
+ * `runs/<runId>/blobs/` subtree uses, minus the deletion direction.
+ */
+async function validateMailboxSubtree(listDir, readBlob, priorListDir, priorReadBlob) {
+    const prospective = await enumerateMailboxInbox(listDir);
+    if (!prospective.ok)
+        return prospective;
+    const prior = await enumerateMailboxInbox(priorListDir);
+    if (!prior.ok) {
+        return {
+            ok: false,
+            reason: `prior tree's mailbox subtree is structurally invalid: ${prior.reason}`,
+        };
+    }
+    for (const emlPath of prospective.emlPaths) {
+        if (!prior.emlPaths.has(emlPath))
+            continue; // newly added
+        const immutable = await checkMailboxEmlPriorByteEquality(emlPath, readBlob, priorReadBlob);
+        if (!immutable.ok)
+            return immutable;
+    }
+    if (prior.indexPresent && !prospective.indexPresent) {
+        return {
+            ok: false,
+            reason: `mailbox ${WORKFLOW_RUN_MAILBOX_PREFIX}/${WORKFLOW_RUN_MAILBOX_INBOX_DIR}/${WORKFLOW_RUN_MAILBOX_INDEX_FILE} present in the prior tree is missing from the prospective tree; the mailbox index must persist so uidValidity/uidNext continuity holds across reopens`,
+        };
+    }
+    return { ok: true };
+}
 export const workflowRunKindHandler = {
     kind: "workflow-run",
     directoryPrefix: "workflow-runs",
@@ -1745,7 +2133,7 @@ export const workflowRunKindHandler = {
             if (!ALLOWED_TOP_LEVEL.has(entry)) {
                 return {
                     ok: false,
-                    reason: `unexpected top-level entry ${JSON.stringify(entry)}; allowed: "${WORKFLOW_RUN_RUNS_PREFIX}", "${WORKFLOW_RUN_ADDRESSES_PREFIX}", "${WORKFLOW_RUN_AGENT_STATE_PREFIX}", "${WORKFLOW_RUN_GITIGNORE_PATH}"`,
+                    reason: `unexpected top-level entry ${JSON.stringify(entry)}; allowed: "${WORKFLOW_RUN_RUNS_PREFIX}", "${WORKFLOW_RUN_ADDRESSES_PREFIX}", "${WORKFLOW_RUN_AGENT_STATE_PREFIX}", "${WORKFLOW_RUN_MAILBOX_PREFIX}", "${WORKFLOW_RUN_GITIGNORE_PATH}"`,
                 };
             }
         }
@@ -1774,6 +2162,21 @@ export const workflowRunKindHandler = {
                 return claimCheck;
             }
         }
+        const mailboxPresent = topLevelTreePaths.includes(WORKFLOW_RUN_MAILBOX_PREFIX) ||
+            priorTopLevels.includes(WORKFLOW_RUN_MAILBOX_PREFIX);
+        if (mailboxPresent) {
+            // Enter mailbox validation when the prospective OR prior tree
+            // carries a `mailbox/` subtree. A prospective tree that drops the
+            // subtree while the prior tree held one must still go through the
+            // walk so the index-continuity guard fires on the vanished
+            // `index.json` (a message-only expunge is legal; dropping the whole
+            // mailbox is not).
+            const mailboxCheck = await validateMailboxSubtree(listDir, readBlob, priorListDir, priorReadBlob);
+            if (!mailboxCheck.ok) {
+                logger.debug `workflow-run validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${mailboxCheck.reason}`;
+                return mailboxCheck;
+            }
+        }
         const runsPresent = topLevelTreePaths.includes(WORKFLOW_RUN_RUNS_PREFIX) ||
             priorTopLevels.includes(WORKFLOW_RUN_RUNS_PREFIX);
         if (!runsPresent) {
@@ -1858,7 +2261,7 @@ export const workflowRunKindHandler = {
                     // checkPriorByteEquality rejects it first. Mirrors the newly-terminal
                     // gate below, which likewise acts only on a blob absent from the
                     // prior tree.
-                    if ((await priorReadBlob(entry.blobPath)) === null) {
+                    if (await blobIsNewlyAdded(entry.blobPath, priorReadBlob)) {
                         const principalCheck = checkCancelOriginPrincipal(entry.blobPath, origin, principal);
                         if (!principalCheck.ok) {
                             logger.debug `workflow-run validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${principalCheck.reason}`;
@@ -1872,7 +2275,8 @@ export const workflowRunKindHandler = {
                         reason: `run ${runId} has event at seq ${String(entry.filenameSeq)} after terminal ${terminalType} at seq ${String(terminalSeq)}`,
                     };
                 }
-                if (TERMINAL_EVENT_TYPES.has(parsed.parsed.body.type)) {
+                const classified = classifyTerminalEvent(parsed.parsed.body.type);
+                if (classified.terminal) {
                     terminalSeq = entry.filenameSeq;
                     terminalType = parsed.parsed.body.type;
                     // Surface the run as newly terminal only when this commit is
@@ -1883,15 +2287,11 @@ export const workflowRunKindHandler = {
                     // terminal blob already present in the prior tree and emits no
                     // signal, so a downstream consumer keyed on the signal does
                     // not double-fire.
-                    if ((await priorReadBlob(entry.blobPath)) === null) {
-                        const status = TERMINAL_EVENT_STATUS.get(parsed.parsed.body.type);
-                        if (status === undefined) {
-                            throw new Error(`terminal event type ${parsed.parsed.body.type} has no workflow_run.status mapping`);
-                        }
+                    if (await blobIsNewlyAdded(entry.blobPath, priorReadBlob)) {
                         const terminalBytes = await readBlob(entry.blobPath);
                         newlyTerminalRuns.push({
                             runId,
-                            status,
+                            status: classified.status,
                             terminalEventJson: new TextDecoder().decode(terminalBytes),
                         });
                     }
@@ -1965,6 +2365,19 @@ export const workflowRunKindHandler = {
                 reason: `blob ${b.blobPath} present in the prior tree is missing from the prospective tree; blob entries are immutable once written`,
             };
         }
+        const partsCheck = await validateRunPartsSubtree({
+            listDir,
+            priorListDir,
+            readBlob,
+            priorReadBlob,
+            listDirOids,
+            priorListDirOids,
+            scopeRunIds,
+        });
+        if (!partsCheck.ok) {
+            logger.debug `workflow-run validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${partsCheck.reason}`;
+            return partsCheck;
+        }
         return { ok: true, newlyTerminalRuns };
     },
     onRefUpdated() {
@@ -2071,63 +2484,13 @@ export const workflowRunAuthorize = (principal, repoId, ref, action) => {
         }
     }
     if (principal.kind === "user") {
-        // The route layer has already pre-resolved the grant verdict and
-        // attached it as `authz`. The substrate does NOT re-query the
-        // grant store here; it (a) checks the bearer-token's claims
-        // bound the requested (ref, action) and have not expired, and
-        // (b) sanity-checks that the pre-resolved verdict targets this
-        // exact resource and grant verb. Both gates must pass before the
-        // verdict's `effect` is honoured.
-        const parsed = UserPrincipal(principal);
-        if (parsed instanceof type.errors) {
-            return {
-                allowed: false,
-                reason: `user principal is malformed: ${parsed.summary}`,
-            };
-        }
-        if (!parsed.tokenClaims.actions.includes(action)) {
-            return {
-                allowed: false,
-                reason: `token does not grant action ${action}`,
-            };
-        }
-        // `ref === "*"` is the substrate's sentinel for the bulk read
-        // performed by `listRefs`. Per-ref filtering is the advertise-refs
-        // layer's responsibility, so the bulk read is gated on action and
-        // expiry alone.
-        if (ref !== "*" && !glob.match(parsed.tokenClaims.refPattern, ref)) {
-            return {
-                allowed: false,
-                reason: `token refPattern ${parsed.tokenClaims.refPattern} does not match ${ref}`,
-            };
-        }
-        if (Date.now() >= parsed.tokenClaims.expiresAt) {
-            return {
-                allowed: false,
-                reason: `token expired at ${parsed.tokenClaims.expiresAt}`,
-            };
-        }
-        const expectedResource = `workflow-run:${repoId.id}`;
-        if (parsed.authz.resource !== expectedResource) {
-            return {
-                allowed: false,
-                reason: `authz verdict resource ${parsed.authz.resource} does not match ${expectedResource}`,
-            };
-        }
-        const expectedGrantVerb = repoActionToGrantVerb(action);
-        if (parsed.authz.grantVerb !== expectedGrantVerb) {
-            return {
-                allowed: false,
-                reason: `authz verdict grantVerb ${parsed.authz.grantVerb} does not match ${expectedGrantVerb}`,
-            };
-        }
-        if (parsed.authz.effect === "allow") {
-            return { allowed: true };
-        }
-        return {
-            allowed: false,
-            reason: `authz verdict denied for ${expectedResource} ${expectedGrantVerb}`,
-        };
+        return authorizeUserPrincipal({
+            principal,
+            repoId,
+            ref,
+            action,
+            resourcePrefix: "workflow-run",
+        });
     }
     // Fail closed on any kind not handled above. The tenant-level
     // `workflow` principal kind (`@intx/types` principalKinds) is a
@@ -2641,26 +3004,31 @@ export async function markConsumed(store, principal, repoId, args) {
     };
 }
 /**
- * Read the run event logs under `runs/` and return the set of
- * `consumedMessageId`s belonging to NON-terminal runs -- the messages a
- * live run still owns. The caller (the supervisor's spawn-time replay)
- * feeds this into `replayProcessingToInbox`'s `ownedMessageIds` so a
- * parked run's message is not re-admitted to inbox and dispatched a
- * second time while the run is recovered by re-driving its durable log.
- * Without this, the re-drive AND the re-triggered fresh run both re-park
- * the same awaitSignal gate on the same runId, and the two concurrent
- * runtime bodies race to a corrupt terminal.
+ * Walk `runs/` once and return the two boot-recovery inputs the supervisor's
+ * spawn needs, from a single traversal of the working tree via `getRepoDir`:
  *
- * Reads the substrate's working tree via `getRepoDir`, mirroring the
- * child's `discoverInFlightRuns`. The working tree tracks the run-event
- * ref (`refs/heads/main`); the claim-check ref (`refs/heads/events`)
- * cannot see it, which is why this lives at the caller rather than inside
- * `replayProcessingToInbox`'s single-ref delta. A run whose log is sealed
- * (combined `events.json`, only permitted for a terminated run) or
- * carries a terminal event is excluded; an absent `runs/` directory
- * yields an empty set.
+ * - `ownedMessageIds`: the `consumedMessageId`s of NON-terminal runs -- the
+ *   messages a live run still owns. Spawn feeds this into
+ *   `replayProcessingToInbox`'s `ownedMessageIds` so a parked run's message is
+ *   not re-admitted to inbox and dispatched a second time while the run is
+ *   recovered by re-driving its durable log. Without this, the re-drive AND the
+ *   re-triggered fresh run both re-park the same awaitSignal gate on the same
+ *   runId, and the two concurrent runtime bodies race to a corrupt terminal.
+ * - `pendingSealRunIds`: runs that are terminal but still in per-event form --
+ *   an interrupted fold left them unsealed. Spawn hands these to the recovery
+ *   sweep, which re-runs the idempotent fold. A terminal event is a *proposal*:
+ *   the authoritative decision is `compactRunEvents`, which independently
+ *   re-checks the run's max-seq event and no-ops a run that is not actually
+ *   terminal, so this scan may be loose.
+ *
+ * The working tree tracks the run-event ref (`refs/heads/main`); the
+ * claim-check ref (`refs/heads/events`) cannot see it, which is why this lives
+ * at the caller rather than inside `replayProcessingToInbox`'s single-ref
+ * delta. A run whose log is sealed (combined `events.jsonl`, only permitted for
+ * a terminated run) contributes to neither set; an absent `runs/` directory
+ * yields empty results.
  */
-export async function readOwnedMessageIds(store, repoId) {
+export async function scanRunsForBoot(store, repoId) {
     const fs = await import("node:fs/promises");
     const path = await import("node:path");
     const repoDir = store.getRepoDir(repoId);
@@ -2671,22 +3039,32 @@ export async function readOwnedMessageIds(store, repoId) {
     }
     catch (cause) {
         if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") {
-            return new Set();
+            return { ownedMessageIds: new Set(), pendingSealRunIds: [] };
         }
         throw cause;
     }
     const owned = new Set();
+    const pendingSealRunIds = [];
     for (const runId of runIds) {
         const runDir = path.join(runsDir, runId);
         // A sealed run (combined events file) is terminal by the handler's
         // own invariant -- only a terminated run is sealed -- so it owns
-        // nothing. Its presence also means the per-event directory is absent.
+        // nothing and is already folded. Its presence also means the per-event
+        // directory is absent.
         let sealed = false;
         try {
             await fs.access(path.join(runDir, WORKFLOW_RUN_EVENTS_FILE));
             sealed = true;
         }
-        catch {
+        catch (cause) {
+            // ENOENT is the normal "not sealed" case. Any other stat error leaves
+            // the run to fall through to the events-dir read below, which resolves
+            // it, so this catch is benign; warn so the anomaly is still visible.
+            if (!(cause instanceof Error) ||
+                !("code" in cause) ||
+                cause.code !== "ENOENT") {
+                logger.warn `scanRunsForBoot: stat of the sealed-log file for run ${runId} failed: ${cause instanceof Error ? cause.message : String(cause)}`;
+            }
             sealed = false;
         }
         if (sealed)
@@ -2696,7 +3074,19 @@ export async function readOwnedMessageIds(store, repoId) {
         try {
             files = await fs.readdir(eventsDir);
         }
-        catch {
+        catch (cause) {
+            // ENOENT means the run has neither a sealed log nor a per-event
+            // directory (grants may be staged before the first event); skip it.
+            // A non-ENOENT error drops the run from BOTH result sets, and a live
+            // run dropped from ownedMessageIds gets its message re-admitted and
+            // dispatched a second time on the same runId -- the double-driver
+            // corruption this scan exists to prevent. Surface it, but still skip:
+            // aborting the whole boot scan over one run is worse.
+            if (!(cause instanceof Error) ||
+                !("code" in cause) ||
+                cause.code !== "ENOENT") {
+                logger.error `scanRunsForBoot: reading events for run ${runId} failed; skipping it may re-admit its message and start a second run on the same runId: ${cause instanceof Error ? cause.message : String(cause)}`;
+            }
             continue;
         }
         let terminal = false;
@@ -2708,7 +3098,17 @@ export async function readOwnedMessageIds(store, repoId) {
             try {
                 parsed = JSON.parse(await fs.readFile(path.join(eventsDir, file), "utf8"));
             }
-            catch {
+            catch (cause) {
+                // A corrupt or unreadable event file drops this run's
+                // classification: a missed RunStarted re-admits its message (a
+                // second run on the same runId), a missed terminal event skips a
+                // needed seal. Surface it, but skip the file rather than abort the
+                // scan. ENOENT here is a benign race (the file vanished mid-scan).
+                if (!(cause instanceof Error) ||
+                    !("code" in cause) ||
+                    cause.code !== "ENOENT") {
+                    logger.error `scanRunsForBoot: reading event ${file} for run ${runId} failed; skipping it may re-admit its message and start a second run on the same runId: ${cause instanceof Error ? cause.message : String(cause)}`;
+                }
                 continue;
             }
             if (typeof parsed !== "object" ||
@@ -2729,44 +3129,31 @@ export async function readOwnedMessageIds(store, repoId) {
                     consumedMessageId = mid;
             }
         }
-        if (terminal)
+        if (terminal) {
+            pendingSealRunIds.push(runId);
             continue;
+        }
         if (consumedMessageId !== undefined)
             owned.add(consumedMessageId);
     }
-    return owned;
+    return { ownedMessageIds: owned, pendingSealRunIds };
 }
-/** Read one run's lifecycle from a committed workflow-run tree. */
-export async function readCommittedWorkflowRunLifecycle(reads, runId) {
-    if (reads === null)
-        return "absent";
-    const runPath = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}`;
-    const runChildren = await reads.listDir(runPath);
-    if (runChildren.some((entry) => entry.type === "blob" && entry.name === WORKFLOW_RUN_EVENTS_FILE)) {
+/**
+ * Classify a run's lifecycle from a read surface. The committed (git-object)
+ * and working-tree (node:fs) readers share this core: a sealed combined log is
+ * terminal; otherwise the latest per-event file decides terminal-vs-live, and a
+ * run with no events is absent. The surface owns every read detail -- the
+ * absent/ENOENT discrimination, the per-surface entry filter, and wrapping an
+ * unreadable latest event as `workflow_run_event_unreadable` -- so this core
+ * never sees a raw read error.
+ */
+async function classifyRunLifecycle(surface) {
+    if (await surface.sealedLogPresent())
         return "terminal";
-    }
-    const eventsPath = `${runPath}/${WORKFLOW_RUN_EVENTS_DIR}`;
-    const eventEntries = (await reads.listDir(eventsPath)).filter((entry) => entry.type === "blob" && parseEventSeq(entry.name) !== null);
-    const latest = eventEntries.reduce((candidate, entry) => {
-        if (candidate === undefined)
-            return entry;
-        const candidateSeq = parseEventSeq(candidate.name);
-        const entrySeq = parseEventSeq(entry.name);
-        return entrySeq !== null &&
-            candidateSeq !== null &&
-            entrySeq > candidateSeq
-            ? entry
-            : candidate;
-    }, undefined);
+    const entries = await surface.listEventEntries();
+    const latest = entries.reduce((candidate, entry) => candidate === undefined || entry.seq > candidate.seq ? entry : candidate, undefined);
     if (latest !== undefined) {
-        const eventPath = `${eventsPath}/${latest.name}`;
-        let parsed;
-        try {
-            parsed = JSON.parse(new TextDecoder().decode(await reads.readBlobByOid(latest.oid)));
-        }
-        catch (cause) {
-            throw new Error(`workflow_run_event_unreadable: ${eventPath}`, { cause });
-        }
+        const parsed = await surface.readEvent(latest);
         if (typeof parsed === "object" &&
             parsed !== null &&
             "type" in parsed &&
@@ -2775,7 +3162,40 @@ export async function readCommittedWorkflowRunLifecycle(reads, runId) {
             return "terminal";
         }
     }
-    return eventEntries.length === 0 ? "absent" : "live";
+    return entries.length === 0 ? "absent" : "live";
+}
+/** Read one run's lifecycle from a committed workflow-run tree. */
+export async function readCommittedWorkflowRunLifecycle(reads, runId) {
+    if (reads === null)
+        return "absent";
+    const runPath = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}`;
+    const eventsPath = `${runPath}/${WORKFLOW_RUN_EVENTS_DIR}`;
+    return classifyRunLifecycle({
+        async sealedLogPresent() {
+            const runChildren = await reads.listDir(runPath);
+            return runChildren.some((entry) => entry.type === "blob" && entry.name === WORKFLOW_RUN_EVENTS_FILE);
+        },
+        async listEventEntries() {
+            const eventEntries = await reads.listDir(eventsPath);
+            return eventEntries.flatMap((entry) => {
+                if (entry.type !== "blob")
+                    return [];
+                const seq = parseEventSeq(entry.name);
+                return seq === null ? [] : [{ seq, name: entry.name, oid: entry.oid }];
+            });
+        },
+        async readEvent(entry) {
+            const eventPath = `${eventsPath}/${entry.name}`;
+            try {
+                return JSON.parse(new TextDecoder().decode(await reads.readBlobByOid(entry.oid)));
+            }
+            catch (cause) {
+                throw new Error(`workflow_run_event_unreadable: ${eventPath}`, {
+                    cause,
+                });
+            }
+        },
+    });
 }
 /**
  * Read the durable lifecycle of one run from the workflow-run working tree.
@@ -2793,56 +3213,52 @@ export async function readWorkflowRunLifecycle(store, repoId, runId) {
     const fs = await import("node:fs/promises");
     const path = await import("node:path");
     const runDir = path.join(store.getRepoDir(repoId), WORKFLOW_RUN_RUNS_PREFIX, runId);
-    try {
-        await fs.access(path.join(runDir, WORKFLOW_RUN_EVENTS_FILE));
-        return "terminal";
-    }
-    catch (cause) {
-        if (!(cause instanceof Error) ||
-            !("code" in cause) ||
-            cause.code !== "ENOENT") {
-            throw cause;
-        }
-    }
     const eventsDir = path.join(runDir, WORKFLOW_RUN_EVENTS_DIR);
-    let files;
-    try {
-        files = await fs.readdir(eventsDir);
-    }
-    catch (cause) {
-        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") {
-            return "absent";
-        }
-        throw cause;
-    }
-    const eventFiles = files.filter((file) => parseEventSeq(file) !== null);
-    const latest = eventFiles.reduce((candidate, file) => {
-        if (candidate === undefined)
-            return file;
-        const candidateSeq = parseEventSeq(candidate);
-        const fileSeq = parseEventSeq(file);
-        return fileSeq !== null && candidateSeq !== null && fileSeq > candidateSeq
-            ? file
-            : candidate;
-    }, undefined);
-    if (latest !== undefined) {
-        const eventPath = path.join(eventsDir, latest);
-        let parsed;
-        try {
-            parsed = JSON.parse(await fs.readFile(eventPath, "utf8"));
-        }
-        catch (cause) {
-            throw new Error(`workflow_run_event_unreadable: ${eventPath}`, { cause });
-        }
-        if (typeof parsed === "object" &&
-            parsed !== null &&
-            "type" in parsed &&
-            typeof parsed.type === "string" &&
-            TERMINAL_EVENT_TYPES.has(parsed.type)) {
-            return "terminal";
-        }
-    }
-    return eventFiles.length === 0 ? "absent" : "live";
+    return classifyRunLifecycle({
+        async sealedLogPresent() {
+            try {
+                await fs.access(path.join(runDir, WORKFLOW_RUN_EVENTS_FILE));
+                return true;
+            }
+            catch (cause) {
+                if (!(cause instanceof Error) ||
+                    !("code" in cause) ||
+                    cause.code !== "ENOENT") {
+                    throw cause;
+                }
+                return false;
+            }
+        },
+        async listEventEntries() {
+            let files;
+            try {
+                files = await fs.readdir(eventsDir);
+            }
+            catch (cause) {
+                if (cause instanceof Error &&
+                    "code" in cause &&
+                    cause.code === "ENOENT") {
+                    return [];
+                }
+                throw cause;
+            }
+            return files.flatMap((file) => {
+                const seq = parseEventSeq(file);
+                return seq === null ? [] : [{ seq, name: file }];
+            });
+        },
+        async readEvent(entry) {
+            const eventPath = path.join(eventsDir, entry.name);
+            try {
+                return JSON.parse(await fs.readFile(eventPath, "utf8"));
+            }
+            catch (cause) {
+                throw new Error(`workflow_run_event_unreadable: ${eventPath}`, {
+                    cause,
+                });
+            }
+        },
+    });
 }
 /**
  * Recovery path: move every processing entry at `address` back to