@intx/hub-sessions 0.2.2 → 0.4.0

package/dist/workflow-run-kind.js

@@ -151,11 +151,11 @@
 // Authz:
 //   - `hub` principal: full access.
 //   - `workflow-process` principal: read/write its own deployment's
-//     event log. The principal carries `{ deploymentId, runId? }`;
-//     this handler verifies `repoId.id === deploymentId`.
+//     event log. The principal carries `{ anchorRunId, runId? }`;
+//     this handler verifies `repoId.id === anchorRunId`.
 //   - `supervisor` principal: read/write its own deployment's event
-//     log. The principal carries `{ deploymentId }`; this handler
-//     verifies `repoId.id === deploymentId`.
+//     log. The principal carries `{ anchorRunId }`; this handler
+//     verifies `repoId.id === anchorRunId`.
 //   - `sidecar` principal: read-only (createPack, resolveRef) for
 //     resume.
 //   - `user` principal: gated by bearer-token claims and the route
@@ -165,19 +165,33 @@ 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";
 export const WORKFLOW_RUN_RUNS_PREFIX = "runs";
 export const WORKFLOW_RUN_EVENTS_DIR = "events";
 export const WORKFLOW_RUN_BLOBS_DIR = "blobs";
+export const WORKFLOW_RUN_GRANTS_FILE = "grants.json";
 export const WORKFLOW_RUN_ADDRESSES_PREFIX = "addresses";
 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
@@ -195,15 +209,28 @@ export const WORKFLOW_RUN_WATERMARK_FILE = "watermark.json";
  * deduped by a retained consumed entry, short enough that `consumed/`
  * reaches a bounded steady state of one day's message volume.
  *
- * INVARIANT (operator-owned): the horizon must be >= the longest
- * window in which the same `messageId` could legitimately be
- * re-submitted and still must be caught as a duplicate. There is no
- * automatic internal mail redelivery in the system today, so this is
- * the external re-submission window. If an at-least-once redelivery
- * source is ever added, the horizon must be >= its maximum redelivery
- * window or dedup breaks; a breach surfaces LOUDLY (a too-late
- * re-submission carrying an old `receivedAt` is refused at enqueue,
- * not silently reprocessed) rather than as silent double-processing.
+ * INVARIANT (operator-owned): the horizon must be >= the longest window in
+ * which the same `messageId` could legitimately be re-submitted and still must
+ * be caught as a duplicate. The hub now redelivers un-acked inbound mail
+ * (connected-window retry and reconnect-redelivery), so an at-least-once
+ * internal source DOES exist -- but the dedup guarantee against it does not
+ * rest on window arithmetic. It rests on a STRUCTURAL fact: `enqueueInbox` is
+ * only ever called with a freshly stamped `receivedAt` (a redelivery
+ * re-enters `onMailMessage` and re-stamps `Date.now()`, never carrying the
+ * original), and the watermark only ever advances to at most
+ * `consumedAt - retentionHorizonMs`, which is <= now, so a fresh `receivedAt`
+ * always sits a full horizon above the watermark and can never be stale-
+ * refused. A redelivery instead hits the `consumed/`/`processing/`/`inbox/`
+ * dedup index and is deduped there. The sole path that carries an original
+ * (old) `receivedAt` back into the queue is `replayProcessingToInbox`, which
+ * writes straight to `inbox/` and bypasses the stale gate entirely. So
+ * `claim_check_stale_enqueue` is unreachable via redelivery today. If any
+ * redelivery source is ever changed to carry the ORIGINAL `receivedAt` into
+ * `enqueueInbox`, stale becomes reachable, the horizon must then be >= that
+ * source's maximum redelivery window, and `StaleInboxEnqueueError`'s
+ * withhold-not-ack handling becomes load-bearing; a breach surfaces LOUDLY (an
+ * old-`receivedAt` re-submission is refused at enqueue) rather than as silent
+ * double-processing.
  */
 export const DEFAULT_CONSUMED_RETENTION_MS = 24 * 60 * 60 * 1000;
 /**
@@ -221,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.
@@ -229,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,
@@ -238,6 +305,42 @@ const CLAIM_CHECK_SUBDIRS = new Set([
 ]);
 /** Per-event filename shape: a decimal integer followed by `.json`. */
 const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
+/**
+ * Parse the seq from a per-event log filename `<seq>.json` under
+ * `runs/<runId>/events/`. Returns the non-negative integer seq, or
+ * `null` when the name is not a legal per-event filename. This is the
+ * one place the filename shape is defined; every reader of the event log
+ * narrows names through it rather than re-encoding the regex. Callers
+ * decide what an illegal name means -- a foreign entry to skip, or a
+ * substrate-invariant violation to surface -- since `validatePush` is
+ * the authority that keeps illegal names from landing in the first place.
+ */
+export function parseEventSeq(filename) {
+    const match = EVENT_FILENAME_RE.exec(filename);
+    if (match === null)
+        return null;
+    const seqStr = match[1];
+    if (seqStr === undefined)
+        return null;
+    return Number.parseInt(seqStr, 10);
+}
+/**
+ * Narrow a per-event filename to its seq, throwing when it is illegal.
+ * A reader that enumerates the committed event log to act on its entries
+ * uses this rather than `parseEventSeq`: `validatePush` is the authority
+ * that keeps an illegal name from ever landing under
+ * `runs/<runId>/events/`, so a name that reaches a reader is corruption,
+ * and silently skipping it would drop an event from processing. `context`
+ * is the repo-root-relative blob path, surfaced in the error so the
+ * offending entry is identifiable.
+ */
+export function requireEventSeq(filename, context) {
+    const seq = parseEventSeq(filename);
+    if (seq === null) {
+        throw new Error(`event_filename_invalid: ${context}`);
+    }
+    return seq;
+}
 /**
  * Per-blob filename shape for the `runs/<runId>/blobs/` subtree: a
  * lowercase 64-character sha256 hex string. Pins the regex to the key
@@ -248,11 +351,39 @@ const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
  */
 const BLOB_FILENAME_RE = /^[0-9a-f]{64}$/;
 /**
- * Subdirectories the kind handler accepts under `runs/<runId>/`. The
- * `events/` subtree carries the append-only event log; the `blobs/`
- * subtree carries opaque, content-addressed step outputs the
- * `BlobSubstrate` adapter spills there when a value exceeds the
- * inline-encoding threshold.
+ * 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
+ * opaque, content-addressed step outputs the `BlobSubstrate` adapter spills
+ * there when a value exceeds the inline-encoding threshold; `grants.json`
+ * carries the run's authorization grants, delivered by the hub's
+ * `run.grants` frame ahead of the trigger and read back by the sidecar's
+ * `onRunStart` barrier. The grants file is a run-dir sibling of `events/`,
+ * not part of the event log, so the event-shape and blob-immutability walks
+ * treat it as inert.
  */
 const RUN_DIR_ALLOWED_CHILDREN = new Set([
     WORKFLOW_RUN_EVENTS_DIR,
@@ -260,6 +391,11 @@ const RUN_DIR_ALLOWED_CHILDREN = new Set([
     // A terminated run's event log, sealed from the per-event `events/`
     // 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:
@@ -318,6 +454,10 @@ const ConsumedEnvelope = type({
         store: "string > 0",
         path: "string > 0",
     },
+    "rejection?": {
+        code: "string > 0",
+        message: "string > 0",
+    },
     "+": "ignore",
 });
 /**
@@ -331,26 +471,38 @@ const WatermarkEnvelope = type({
     watermark: "number >= 0",
     "+": "ignore",
 });
+const TERMINAL_EVENT_STATUS = new Map([
+    ["RunCompleted", "completed"],
+    ["RunFailed", "failed"],
+    ["RunCancelled", "cancelled"],
+]);
 /**
- * Terminal event discriminators. A run whose log contains an entry
- * with one of these `type` values must not receive any event with a
- * strictly greater seq.
- *
- * This set 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 MUST stay in sync with that canonical
- * definition:
- * if the runtime adds or removes a terminal run phase, update this set too.
- * Drift silently reopens the restore-time double-driver collision that
- * `readOwnedMessageIds` (below) exists to prevent.
+ * Membership set of terminal event types, derived from
+ * `TERMINAL_EVENT_STATUS` so it always covers exactly the mapped types and
+ * the two cannot drift apart.
  */
-const TERMINAL_EVENT_TYPES = new Set([
-    "RunCompleted",
-    "RunFailed",
-    "RunCancelled",
-]);
+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
@@ -406,12 +558,12 @@ const SidecarPrincipal = type({
 });
 const WorkflowProcessPrincipal = type({
     kind: "'workflow-process'",
-    deploymentId: "string",
+    anchorRunId: "string",
     "runId?": "string",
 });
 const SupervisorPrincipal = type({
     kind: "'supervisor'",
-    deploymentId: "string",
+    anchorRunId: "string",
 });
 /**
  * Resolve the substrate's `changedPathPrefixes` into the set of run ids
@@ -484,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}", and "${WORKFLOW_RUN_EVENTS_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);
@@ -500,6 +652,18 @@ async function enumerateEventBlobs(listDir, scopeRunIds) {
         if (hasCombined)
             continue;
         if (!hasPerEvent) {
+            // 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 {
                 ok: false,
                 reason: `run directory ${runDirPath} is missing required "${WORKFLOW_RUN_EVENTS_DIR}" subdirectory`,
@@ -738,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
@@ -849,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);
@@ -863,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 };
@@ -903,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) {
@@ -1619,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
@@ -1640,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",
@@ -1669,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}"`,
                 };
             }
         }
@@ -1698,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) {
@@ -1768,10 +2247,26 @@ export const workflowRunKindHandler = {
                             reason: `event ${entry.blobPath} CancelRequested origin must be a string`,
                         };
                     }
-                    const principalCheck = checkCancelOriginPrincipal(entry.blobPath, origin, principal);
-                    if (!principalCheck.ok) {
-                        logger.debug `workflow-run validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${principalCheck.reason}`;
-                        return principalCheck;
+                    // Enforce the cancel-origin principal only for a NEWLY-ADDED blob.
+                    // A CancelRequested's origin-vs-signer rule is a write-time
+                    // authorization: it belongs to the commit that authors the event. A
+                    // later commit that merely carries the event forward -- e.g. the
+                    // run's own workflow-process cascade write of CancelPropagated /
+                    // RunCancelled, which re-lists the whole events prefix -- must not be
+                    // rejected because the carried-forward cancel was authored under a
+                    // different (supervisor) signer. Re-checking it protects nothing: the
+                    // byte-equality check above already proves a carried-forward blob is
+                    // unchanged, and the deletion-direction check proves it cannot be
+                    // dropped. A tampered (byte-diverged) blob never reaches here --
+                    // checkPriorByteEquality rejects it first. Mirrors the newly-terminal
+                    // gate below, which likewise acts only on a blob absent from the
+                    // prior tree.
+                    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}`;
+                            return principalCheck;
+                        }
                     }
                 }
                 if (terminalSeq !== null) {
@@ -1780,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
@@ -1791,10 +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) {
+                    if (await blobIsNewlyAdded(entry.blobPath, priorReadBlob)) {
                         const terminalBytes = await readBlob(entry.blobPath);
                         newlyTerminalRuns.push({
                             runId,
+                            status: classified.status,
                             terminalEventJson: new TextDecoder().decode(terminalBytes),
                         });
                     }
@@ -1868,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() {
@@ -1893,10 +2403,10 @@ export const workflowRunAuthorize = (principal, repoId, ref, action) => {
                 reason: `workflow-process principal is malformed: ${parsed.summary}`,
             };
         }
-        if (parsed.deploymentId !== repoId.id) {
+        if (parsed.anchorRunId !== repoId.id) {
             return {
                 allowed: false,
-                reason: `workflow-process deployment ${parsed.deploymentId} cannot access workflow-run ${repoId.id}`,
+                reason: `workflow-process deployment ${parsed.anchorRunId} cannot access workflow-run ${repoId.id}`,
             };
         }
         switch (action) {
@@ -1923,10 +2433,10 @@ export const workflowRunAuthorize = (principal, repoId, ref, action) => {
                 reason: `supervisor principal is malformed: ${parsed.summary}`,
             };
         }
-        if (parsed.deploymentId !== repoId.id) {
+        if (parsed.anchorRunId !== repoId.id) {
             return {
                 allowed: false,
-                reason: `supervisor deployment ${parsed.deploymentId} cannot access workflow-run ${repoId.id}`,
+                reason: `supervisor deployment ${parsed.anchorRunId} cannot access workflow-run ${repoId.id}`,
             };
         }
         switch (action) {
@@ -1974,64 +2484,18 @@ 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
+    // grant owner, not a workflow-run repo bearer, and never carries a
+    // workflow-run push here -- so it is intentionally left denied.
     return {
         allowed: false,
         reason: `unknown principal kind: ${principal.kind}`,
@@ -2191,6 +2655,49 @@ function parseWatermark(bytes, watermarkFull) {
     }
     return validated.watermark;
 }
+/**
+ * Internal signal thrown from the `enqueueInbox` merge callback when the
+ * messageId is already present in a queue state. Caught at the `enqueueInbox`
+ * boundary and turned into an `already-present` outcome; never escapes. It
+ * carries the specific `reason` so the boundary maps it without re-deriving.
+ */
+class InboxEntryAlreadyPresent extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "InboxEntryAlreadyPresent";
+    }
+}
+/**
+ * Thrown by `enqueueInbox` when the inbound's `receivedAt` is strictly below
+ * the address's retention watermark. This is refusal under UNCERTAINTY, not
+ * proof of prior receipt: the consumed dedup entry that would rule out a
+ * duplicate may have been pruned, so the substrate can no longer tell a
+ * duplicate from a never-processed message and refuses rather than risk
+ * reprocessing. A caller gating a durable-receipt ack MUST NOT acknowledge on
+ * this -- acking an "I cannot tell" would terminally drop a message that was
+ * never written. It is its own type (not a generic Error) so that a caller,
+ * and monitoring, can surface it as a distinct loud signal rather than
+ * blending it into ordinary I/O-failure noise.
+ *
+ * Structurally unreachable on the mail-inbound path today: `enqueueInbox` is
+ * only ever called with a freshly stamped `receivedAt` (a redelivery
+ * re-stamps `Date.now()` rather than carrying the original), and the watermark
+ * only ever advances to at most `consumedAt - retentionHorizonMs <= now`, so a
+ * fresh `receivedAt` sits a full horizon above it. The sole path that carries
+ * an original (old) `receivedAt` back into the queue is
+ * `replayProcessingToInbox`, which writes straight to `inbox/` and bypasses
+ * this gate entirely. If any redelivery source is ever changed to carry the
+ * original `receivedAt` into `enqueueInbox`, this becomes reachable and its
+ * withhold-not-ack handling becomes load-bearing.
+ */
+export class StaleInboxEnqueueError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StaleInboxEnqueueError";
+    }
+}
 /**
  * Append a new inbox entry for `address`. The merge callback reads
  * the address subtree under the per-repo lock, augments the inbox
@@ -2219,46 +2726,63 @@ export async function enqueueInbox(store, principal, repoId, args) {
     const inboxFname = `${inboxKey}.json`;
     const consumedFname = `${args.messageId}.json`;
     const messageIdSuffix = `-${args.messageId}.json`;
-    const { commitSha } = await store.writeTreeDelta(principal, repoId, ref, {
-        changedPathPrefixes: new Set([addressPrefix(addressSegment)]),
-        message: `enqueue inbox ${args.address} ${args.messageId}`,
-        computeDelta: async (_parentCommitSha, prior) => {
-            const listing = await readAddressListing(prior, addressSegment);
-            // Refuse a definitively-stale enqueue: a message whose receivedAt
-            // is strictly below the retention watermark could have had its
-            // consumed/ dedup entry pruned, so a duplicate can no longer be
-            // ruled out. Reject it LOUDLY rather than risk reprocessing. This
-            // is the second half of the exactly-once guarantee: above the
-            // watermark the consumed/ index is authoritative; below it, refuse.
-            if (args.receivedAt < listing.watermark) {
-                throw new Error(`claim_check_stale_enqueue: address ${args.address} message ${args.messageId} receivedAt ${String(args.receivedAt)} is below the retention watermark ${String(listing.watermark)}; its dedup entry may have been pruned, so it is refused as definitively-stale`);
-            }
-            if (listing.inbox.some((e) => e.name === inboxFname)) {
-                throw new Error(`claim_check_duplicate_inbox: ${newInboxPath} already exists`);
-            }
-            // consumed/ is keyed by messageId alone, so this is an exact
-            // filename lookup against the dedup index.
-            if (listing.consumed.some((e) => e.name === consumedFname)) {
-                throw new Error(`claim_check_already_consumed: address ${args.address} message ${args.messageId} is already in the consumed dedup index`);
-            }
-            if (listing.processing.some((e) => e.name.endsWith(messageIdSuffix))) {
-                throw new Error(`claim_check_already_processing: address ${args.address} message ${args.messageId} is currently in processing`);
-            }
-            // Reject a second inbox entry for the same messageId at a
-            // different receivedAt. The validatePush atomicity check also
-            // catches this on the commit path, but surfacing it here gives the
-            // caller a precise error and keeps the bad tree off the substrate.
-            const inboxDup = listing.inbox.find((e) => e.name.endsWith(messageIdSuffix));
-            if (inboxDup !== undefined) {
-                throw new Error(`claim_check_already_inbox: address ${args.address} message ${args.messageId} is already in the inbox at ${inboxPath(addressSegment, inboxDup.name.slice(0, -".json".length))}`);
-            }
-            return {
-                puts: { [newInboxPath]: utf8(JSON.stringify(envelope)) },
-                deletes: [],
-            };
-        },
-    });
-    return { commitSha, inboxKey, envelope };
+    // The already-present cases throw `InboxEntryAlreadyPresent` from the merge
+    // callback and are caught here into an `already-present` outcome; the
+    // stale-refusal throws `StaleInboxEnqueueError`, and a substrate/I/O failure
+    // throws a generic error -- both of those propagate. The return/throw split
+    // is deliberate and load-bearing: it is the ack/withhold boundary for a
+    // caller gating a durable-receipt ack (return = safe to ack, throw =
+    // withhold), so `stale` sits with I/O on the throw side, NOT with the
+    // already-present cases (see `StaleInboxEnqueueError`).
+    let commitSha;
+    try {
+        ({ commitSha } = await store.writeTreeDelta(principal, repoId, ref, {
+            changedPathPrefixes: new Set([addressPrefix(addressSegment)]),
+            message: `enqueue inbox ${args.address} ${args.messageId}`,
+            computeDelta: async (_parentCommitSha, prior) => {
+                const listing = await readAddressListing(prior, addressSegment);
+                // Refuse a definitively-stale enqueue: a message whose receivedAt
+                // is strictly below the retention watermark could have had its
+                // consumed/ dedup entry pruned, so a duplicate can no longer be
+                // ruled out. Reject it LOUDLY rather than risk reprocessing. This
+                // is the second half of the exactly-once guarantee: above the
+                // watermark the consumed/ index is authoritative; below it, refuse.
+                if (args.receivedAt < listing.watermark) {
+                    throw new StaleInboxEnqueueError(`claim_check_stale_enqueue: address ${args.address} message ${args.messageId} receivedAt ${String(args.receivedAt)} is below the retention watermark ${String(listing.watermark)}; its dedup entry may have been pruned, so it is refused as definitively-stale`);
+                }
+                if (listing.inbox.some((e) => e.name === inboxFname)) {
+                    throw new InboxEntryAlreadyPresent("duplicate", `claim_check_duplicate_inbox: ${newInboxPath} already exists`);
+                }
+                // consumed/ is keyed by messageId alone, so this is an exact
+                // filename lookup against the dedup index.
+                if (listing.consumed.some((e) => e.name === consumedFname)) {
+                    throw new InboxEntryAlreadyPresent("consumed", `claim_check_already_consumed: address ${args.address} message ${args.messageId} is already in the consumed dedup index`);
+                }
+                if (listing.processing.some((e) => e.name.endsWith(messageIdSuffix))) {
+                    throw new InboxEntryAlreadyPresent("processing", `claim_check_already_processing: address ${args.address} message ${args.messageId} is currently in processing`);
+                }
+                // Reject a second inbox entry for the same messageId at a
+                // different receivedAt. The validatePush atomicity check also
+                // catches this on the commit path, but surfacing it here gives the
+                // caller a precise error and keeps the bad tree off the substrate.
+                const inboxDup = listing.inbox.find((e) => e.name.endsWith(messageIdSuffix));
+                if (inboxDup !== undefined) {
+                    throw new InboxEntryAlreadyPresent("already_inbox", `claim_check_already_inbox: address ${args.address} message ${args.messageId} is already in the inbox at ${inboxPath(addressSegment, inboxDup.name.slice(0, -".json".length))}`);
+                }
+                return {
+                    puts: { [newInboxPath]: utf8(JSON.stringify(envelope)) },
+                    deletes: [],
+                };
+            },
+        }));
+    }
+    catch (err) {
+        if (err instanceof InboxEntryAlreadyPresent) {
+            return { outcome: "already-present", reason: err.reason };
+        }
+        throw err;
+    }
+    return { outcome: "enqueued", commitSha, inboxKey, envelope };
 }
 /**
  * Move the FIFO-first inbox entry for `address` to processing.
@@ -2346,7 +2870,7 @@ export async function dequeueToProcessing(store, principal, repoId, address) {
  * committed -- which is exactly when the supervisor forwards
  * `trigger.fired` -- observes the processing entry. Reading the working tree (rather than walking the
  * committed git tree) matches the workflow-process child's sibling
- * reads of `workflow.json` and `runs/<runId>/events/`. Because the
+ * read of `runs/<runId>/events/`. Because the
  * read issues no commit it cannot race the supervisor's `markConsumed`
  * write; it returns a point-in-time snapshot of the directory.
  */
@@ -2431,6 +2955,7 @@ export async function markConsumed(store, principal, repoId, args) {
                 runId: args.runId,
                 consumedAt: args.consumedAt,
                 mailAuditRef: processingEnvelope.mailAuditRef,
+                ...(args.rejection !== undefined ? { rejection: args.rejection } : {}),
             };
             consumedEnvelope = envelope;
             // The watermark may only advance, and never past the entry this
@@ -2479,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);
@@ -2509,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)
@@ -2534,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;
@@ -2546,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" ||
@@ -2567,12 +3129,136 @@ 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 };
+}
+/**
+ * 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 entries = await surface.listEventEntries();
+    const latest = entries.reduce((candidate, entry) => candidate === undefined || entry.seq > candidate.seq ? entry : candidate, undefined);
+    if (latest !== undefined) {
+        const parsed = await surface.readEvent(latest);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            "type" in parsed &&
+            typeof parsed.type === "string" &&
+            TERMINAL_EVENT_TYPES.has(parsed.type)) {
+            return "terminal";
+        }
+    }
+    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.
+ * `grants.json` alone is still an absent run: grants are staged before the
+ * first trigger, while the first event is the durable proof that the run was
+ * fired. A sealed event log is terminal by the kind handler's compaction
+ * invariant.
+ *
+ * The supervisor uses this when in-memory cohort membership is empty. That
+ * happens both for a genuinely new deployment and briefly during recovery,
+ * so treating both states as "fire" would start a second driver for a live
+ * log or reuse a terminal run.
+ */
+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);
+    const eventsDir = path.join(runDir, WORKFLOW_RUN_EVENTS_DIR);
+    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