@intx/hub-sessions 0.2.2 → 0.3.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
@@ -173,6 +173,7 @@ 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";
@@ -195,15 +196,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;
 /**
@@ -238,6 +252,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 +298,15 @@ 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.
+ * 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 +314,7 @@ 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,
 ]);
 /**
  * Filename shape for inbox and processing entries:
@@ -318,6 +373,10 @@ const ConsumedEnvelope = type({
         store: "string > 0",
         path: "string > 0",
     },
+    "rejection?": {
+        code: "string > 0",
+        message: "string > 0",
+    },
     "+": "ignore",
 });
 /**
@@ -332,25 +391,32 @@ const WatermarkEnvelope = type({
     "+": "ignore",
 });
 /**
- * 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.
+ * 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 set is a hand-rolled copy of the runtime's terminal-run vocabulary
+ * 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 MUST stay in sync with that canonical
- * definition:
- * if the runtime adds or removes a terminal run phase, update this set too.
+ * 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_TYPES = new Set([
-    "RunCompleted",
-    "RunFailed",
-    "RunCancelled",
+const TERMINAL_EVENT_STATUS = new Map([
+    ["RunCompleted", "completed"],
+    ["RunFailed", "failed"],
+    ["RunCancelled", "cancelled"],
 ]);
+/**
+ * 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(TERMINAL_EVENT_STATUS.keys());
 /**
  * Recognised CancelRequested origins. Mirrors the workflow package's
  * `CANCEL_ORIGINS` vocabulary; inlined here so the substrate does
@@ -406,12 +472,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 +550,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}", and "${WORKFLOW_RUN_GRANTS_FILE}" are allowed`,
             };
         }
         const hasCombined = runChildren.includes(WORKFLOW_RUN_EVENTS_FILE);
@@ -500,6 +566,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) {
+                continue;
+            }
             return {
                 ok: false,
                 reason: `run directory ${runDirPath} is missing required "${WORKFLOW_RUN_EVENTS_DIR}" subdirectory`,
@@ -1768,10 +1844,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 priorReadBlob(entry.blobPath)) === null) {
+                        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) {
@@ -1792,9 +1884,14 @@ export const workflowRunKindHandler = {
                     // 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`);
+                        }
                         const terminalBytes = await readBlob(entry.blobPath);
                         newlyTerminalRuns.push({
                             runId,
+                            status,
                             terminalEventJson: new TextDecoder().decode(terminalBytes),
                         });
                     }
@@ -1893,10 +1990,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 +2020,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) {
@@ -2032,6 +2129,10 @@ export const workflowRunAuthorize = (principal, repoId, ref, action) => {
             reason: `authz verdict denied for ${expectedResource} ${expectedGrantVerb}`,
         };
     }
+    // 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 +2292,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 +2363,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 +2507,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 +2592,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
@@ -2574,6 +2736,114 @@ export async function readOwnedMessageIds(store, repoId) {
     }
     return owned;
 }
+/** 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)) {
+        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);
+    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 });
+        }
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            "type" in parsed &&
+            typeof parsed.type === "string" &&
+            TERMINAL_EVENT_TYPES.has(parsed.type)) {
+            return "terminal";
+        }
+    }
+    return eventEntries.length === 0 ? "absent" : "live";
+}
+/**
+ * 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);
+    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";
+}
 /**
  * Recovery path: move every processing entry at `address` back to
  * inbox preserving the original `<receivedAt>-<messageId>` filename

package/dist/workflow-run-reader.d.ts

@@ -22,7 +22,7 @@ export type WorkflowRunEvent = {
  * path computation) with direct `isomorphic-git` tree/blob reads. It
  * never writes, so it carries no authorize gate of its own; callers
  * gate access at their own boundary (the REST routes use a
- * `workflow-run:<deploymentId>` grant check).
+ * `workflow-run:<runId>` grant check).
  */
 export interface WorkflowRunReader {
     /**

package/dist/workflow-run-reader.js

@@ -1,8 +1,7 @@
 import fs from "node:fs";
 import git from "isomorphic-git";
-import { WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "./workflow-run-kind.js";
+import { requireEventSeq, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "./workflow-run-kind.js";
 import { WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, } from "./workflow-run-event-log.js";
-const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
 export function createWorkflowRunReader(repoStore) {
     function repoDirOrNull(repoId) {
         try {
@@ -106,12 +105,9 @@ export function createWorkflowRunReader(repoStore) {
         for (const entry of tree.tree) {
             if (entry.type !== "blob")
                 continue;
-            const m = EVENT_FILENAME_RE.exec(entry.path);
-            if (m === null || m[1] === undefined)
-                continue;
-            const seq = Number.parseInt(m[1], 10);
-            const blob = await git.readBlob({ fs, dir, oid: entry.oid });
             const path = `${eventsDir}/${entry.path}`;
+            const seq = requireEventSeq(entry.path, path);
+            const blob = await git.readBlob({ fs, dir, oid: entry.oid });
             const parsed = parseEventObject(new TextDecoder().decode(blob.blob), path);
             const type = parsed["type"];
             if (typeof type !== "string") {

package/dist/workflow-run-restore.d.ts

@@ -0,0 +1,15 @@
+import type { AgentRepoStore } from "./agent-repo.js";
+import type { AllocatedSidecarTarget, SidecarAllocationRouter } from "./ws/sidecar-handler.js";
+export declare const WORKFLOW_RUN_RESTORE_REFS: readonly ["refs/heads/main", "refs/heads/events"];
+/**
+ * Replay every authoritative workflow-run ref the runtime understands onto an
+ * exact replacement allocation. Refs are sent sequentially and the function
+ * resolves only after the worker acknowledges each one, making it a barrier
+ * the deploy path can place before supervisor spawn.
+ */
+export declare function restoreWorkflowRunToAllocation(args: {
+    agentRepoStore: AgentRepoStore;
+    allocationRouter: Pick<SidecarAllocationRouter, "sendWorkflowRunPackToAllocation">;
+    allocationTarget: AllocatedSidecarTarget;
+    agentAddress: string;
+}): Promise<void>;