@cursor/july 0.1.45 → 0.1.46

package/src/internal/ledger-serving.ts

@@ -1,117 +1,173 @@
 /**
- * Ledger-mode serving seam (`serving: "ledger"` on `defineAgent`):
- * coordination only, no inbox. Every engine `send` acquires the session
- * lease before its turn runs and commits (head+1, lease released) after
- * it completes, so cross-pod mutual exclusion, generation fencing, and
- * the committed head sequence are real.
+ * Ledger-mode serving seam (`serving: "ledger"` on `defineAgent`): an event
+ * pump that routes every engine `send` through the KV session ledger
+ * instead of starting turns directly.
  *
- * **Durability trade-off (deliberate):** there is no durable mailbox.
- * An event that arrives while the lease is held does NOT park in the
- * store — the delivering pod waits *in-process*: local concurrent sends
- * serialize on a per-session promise chain (no claim spinning), and a
- * lease held by another pod is waited out with bounded claim retries. A
- * crash therefore loses the in-flight event exactly as resident serving
- * does. A dead pod's lease simply expires (~30s TTL); the next delivery
- * claims at generation+1 — no janitor is needed because nothing is
- * parked.
+ * Delivery: ensureSession (continuation key, as today) → principal gate
+ * (an existing session rejects a sender that is not its principal BEFORE
+ * anything is parked; mirrors the resident `samePrincipal` check) →
+ * appendEvent (payload + CAS — the source ack point moves after this) →
+ * claim → drain → run the drained turns through the resident engine path →
+ * commit (heartbeats while turns run) → repeat while the commit reports
+ * pending. A deliver that finds the lease held walks away (the holder's
+ * commit sees the append); the janitor recovers sessions whose holder
+ * died. A foreign-principal envelope that reaches the mailbox anyway is
+ * consumed and committed away at drain (warn log), never replayed.
  *
- * Re-entrancy caveat (same shape as resident `waitForCompletion`): a
- * send issued from *inside* a running turn against the same session
- * chains behind that turn's serve, so awaiting its resolution from the
- * turn would deadlock. Fire-and-forget such sends.
+ * v1 scope: the mailbox envelope carries `message`, `auth`, `title`,
+ * `state`, `mode`, `purpose`, and the isolation-relevant per-send
+ * overrides `workspaceDir` and `cloud` — the two options
+ * `resolveSessionRuntime` and harness-cwd selection read. Dropping
+ * those is a sandbox escape, not a feature gap: without them a drained
+ * GitHub/Slack turn falls back to the local runtime with the default
+ * harness cwd, so untrusted channel content drives tools on the serve
+ * host instead of the cloud VM / channel worktree. `coalesceSourceTs`
+ * (when present) is used as the drain-ordering `sourceTs`. Deferred
+ * (documented, not silently faked — deliver logs a warning naming what
+ * it dropped): `workspaceFiles` and per-turn `images` (content
+ * injection, and their base64 payloads can blow the mailbox blob past
+ * hosted KV value caps), `sdkAgentId` seeding, and `admission`
+ * semantics (both `"preempt"` and Slack `"coalesce"` nudge bookkeeping
+ * — ledger draining already serializes turns, but nothing is
+ * interrupted or coalesced through the mailbox).
  */
 
 import { randomBytes, randomUUID } from "node:crypto";
-import type { SessionLedger } from "../ledger/session-ledger.js";
+import type {
+  JanitorClaimedSession,
+  LedgerJanitor,
+} from "../ledger/janitor.js";
+import { createLedgerJanitor } from "../ledger/janitor.js";
+import type { LedgerLease, SessionLedger } from "../ledger/session-ledger.js";
 import {
   HEARTBEAT_INTERVAL_MS,
-  LEASE_TTL_MS,
   LedgerFencedError,
 } from "../ledger/session-ledger.js";
-import type { ChannelSession, SendMessageOptions } from "../types.js";
+import type {
+  AgentCloudOptions,
+  AuthContext,
+  ChannelSession,
+  JsonValue,
+  SendMessageOptions,
+  SessionPurpose,
+} from "../types.js";
+import { SessionAuthError, samePrincipal } from "./auth.js";
+import { describeError } from "./describe-error.js";
 import { newContinuationKey } from "./ids.js";
 
-/** Wait between claim retries while another holder has the lease. */
-export const CLAIM_RETRY_DELAY_MS = 250;
-/**
- * Give up waiting for the lease after this long — two full lease TTLs,
- * so a dead holder's expiry (~30s) is always survived with margin.
- */
-export const CLAIM_WAIT_TIMEOUT_MS: number = 2 * LEASE_TTL_MS;
-
-/** The `send` options a ledger delivery carries to the resident turn. */
-export type LedgerDeliverOptions = SendMessageOptions & {
-  mode?: "chat" | "task";
-};
-
-/** One delivery handed back to the engine's resident path. */
-export interface LedgerTurnRequest {
+/** The JSON payload stored in `mailbox/<sessionId>/<eventId>`. */
+export interface LedgerDeliveryEnvelope {
   channelId: string;
   continuationToken: string;
   message: string;
-  options: LedgerDeliverOptions;
+  auth: AuthContext | null;
+  title?: string;
+  state?: JsonValue;
+  mode?: "chat" | "task";
+  purpose?: SessionPurpose;
+  /**
+   * Isolation-relevant per-send overrides, reapplied on the resident
+   * send at drain. Absent on envelopes parked by earlier builds — the
+   * drain then behaves as those builds did (agent-default runtime/cwd).
+   */
+  workspaceDir?: string;
+  cloud?: AgentCloudOptions;
 }
 
+/** The `send` options the envelope can carry through the mailbox. */
+export type LedgerDeliverOptions = SendMessageOptions & {
+  mode?: "chat" | "task";
+};
+
 export interface LedgerServingOptions {
   ledger: SessionLedger;
   /**
-   * Run one delivery as a resident-path turn (the engine's `send` with
-   * the internal ledger-delivery flag). Must resolve once the turn is
-   * admitted; the pump awaits `waitForCompletion` itself.
+   * Run one drained event as a resident-path turn (the engine's `send`
+   * with the internal `fromLedgerPump` flag). Must resolve once the turn
+   * is admitted; the pump awaits `waitForCompletion` itself.
    */
-  deliverTurn: (request: LedgerTurnRequest) => Promise<ChannelSession>;
+  deliverTurn: (envelope: LedgerDeliveryEnvelope) => Promise<ChannelSession>;
+  /** Engine continuation lookup (local index + lazy storage restore). */
+  findSession: (
+    channelId: string,
+    continuationToken: string
+  ) => Promise<ChannelSession | undefined>;
   logger?: (line: string) => void;
-  /** Lease heartbeat cadence while the turn runs (default 10s). */
+  /** Lease heartbeat cadence while turns run (default 10s). */
   heartbeatIntervalMs?: number;
-  /** Claim retry cadence while the lease is held (default 250ms). */
-  claimRetryDelayMs?: number;
-  /** Give-up bound for lease waiting (default 2× lease TTL). */
-  claimWaitTimeoutMs?: number;
+  /** Janitor scan cadence (default `DEFAULT_JANITOR_INTERVAL_MS`). */
+  janitorIntervalMs?: number;
   clock?: () => number;
-  /** Injectable wait (tests use short real delays; keep them tiny). */
-  sleep?: (ms: number) => Promise<void>;
 }
 
 export class LedgerServing {
   private readonly ledger: SessionLedger;
   private readonly deliverTurn: LedgerServingOptions["deliverTurn"];
+  private readonly findSession: LedgerServingOptions["findSession"];
   private readonly logger: (line: string) => void;
   private readonly heartbeatIntervalMs: number;
-  private readonly claimRetryDelayMs: number;
-  private readonly claimWaitTimeoutMs: number;
   private readonly clock: () => number;
-  private readonly sleep: (ms: number) => Promise<void>;
-  /**
-   * Per-ledger-session in-process serialization: local concurrent sends
-   * queue here instead of spinning claim retries against our own lease.
-   */
-  private readonly chains = new Map<string, Promise<unknown>>();
+  private readonly janitor: LedgerJanitor;
+  /** One pump per ledger session — the in-process face of the lease. */
+  private readonly pumps = new Map<string, Promise<void>>();
+  /** Fire-and-forget re-pump checks, awaited on close. */
+  private readonly background = new Set<Promise<void>>();
 
   constructor(options: LedgerServingOptions) {
     this.ledger = options.ledger;
     this.deliverTurn = options.deliverTurn;
+    this.findSession = options.findSession;
     this.logger = options.logger ?? (() => {});
     this.heartbeatIntervalMs =
       options.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
-    this.claimRetryDelayMs = options.claimRetryDelayMs ?? CLAIM_RETRY_DELAY_MS;
-    this.claimWaitTimeoutMs =
-      options.claimWaitTimeoutMs ?? CLAIM_WAIT_TIMEOUT_MS;
     this.clock = options.clock ?? Date.now;
-    this.sleep =
-      options.sleep ??
-      ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.janitor = createLedgerJanitor({
+      ledger: options.ledger,
+      onSession: (claimed) => this.serveClaimed(claimed),
+      // Consumed mailbox blobs (full message envelopes) would otherwise
+      // accumulate forever; the default TTL (1h) is far beyond any lease
+      // or turn horizon, so only truly dead blobs are collected.
+      orphanSweep: {},
+      ...(options.janitorIntervalMs === undefined
+        ? {}
+        : { intervalMs: options.janitorIntervalMs }),
+      onError: (error, sessionId) => {
+        this.logger(
+          `[ledger] janitor error${sessionId === undefined ? "" : ` (session ${sessionId})`}: ${describeError(error)}`
+        );
+      },
+      clock: this.clock,
+    });
   }
 
-  /** Settle every queued and in-flight delivery. */
+  /** Start the janitor loop (recovers expired-lease sessions). */
+  start(): void {
+    this.janitor.start();
+  }
+
+  /** Stop the janitor and settle in-flight pumps and re-pump checks. */
   async close(): Promise<void> {
-    await Promise.allSettled([...this.chains.values()]);
+    // Awaiting stop() matters: an in-flight janitor pass can claim a
+    // session and register a pump after this method snapshots the maps.
+    await this.janitor.stop();
+    await Promise.allSettled([...this.pumps.values()]);
+    await Promise.allSettled([...this.background]);
   }
 
   /**
-   * Ledger-mode `send`: resolve the session identity, wait for the
-   * lease (in-process queue first, then cross-pod claim retries), run
-   * the turn, commit. Resolves with the engine session handle after the
-   * commit released the lease.
+   * Ledger-mode `send`: append the message to the session mailbox, then
+   * serve pending events (or walk away if another holder is already
+   * serving them). Resolves with the engine session handle once one
+   * exists — the ack point is the durable append, not turn completion —
+   * so HTTP create/follow-up can return a session id while the holder is
+   * still in flight. When this process wins the claim, the pump keeps
+   * draining in the background; callers that need the turn to finish use
+   * `waitForCompletion` (and the lease releases on the pump's commit).
+   * When another holder is serving the session and no engine session
+   * exists on this pod, the delivery is still a success — the event is
+   * durably parked and the holder's commit (or the janitor) drains it —
+   * so the resolved handle is a parked stand-in carrying the durable
+   * session identity.
    */
   async deliver(
     channelId: string,
@@ -119,46 +175,277 @@ export class LedgerServing {
     options: LedgerDeliverOptions
   ): Promise<ChannelSession> {
     const continuationToken = options.continuationToken ?? newContinuationKey();
+    this.warnOnDroppedOptions(channelId, options);
     const ensured = await this.ledger.ensureSession(
       `${channelId}/${continuationToken}`
     );
-    return this.enqueue(ensured.session.sessionId, () =>
-      this.serveOne(ensured.session.sessionId, {
-        channelId,
-        continuationToken,
-        message,
-        options,
-      })
-    );
+    const ledgerSessionId = ensured.session.sessionId;
+    // Principal gate BEFORE the durable append: once an envelope is
+    // parked it WILL be drained, so a foreign sender must be rejected
+    // here — not on the resident path after the mailbox write. A new
+    // ledger session has no owner yet: the creating sender becomes it,
+    // exactly as on resident session creation.
+    if (!ensured.created) {
+      const existing = await this.findSession(channelId, continuationToken);
+      if (existing !== undefined) {
+        if (!samePrincipal(existing.info.auth, options.auth ?? null)) {
+          throw new SessionAuthError(existing.id);
+        }
+      }
+      // No handle: the engine session does not exist yet (the first
+      // parked event has not run — the lease holder creates it) or a
+      // cross-pod restore transiently failed. Park rather than fail
+      // closed: rejecting here would bounce the legitimate owner racing
+      // the session's first turn. This is not fail-open — the resident
+      // path re-checks the principal when the event drains, and the
+      // drain treats a SessionAuthError as consume-and-commit, so a
+      // foreign envelope that parks through this window costs one warn
+      // line and never actuates, bricks, or replays the session.
+    }
+    const envelope: LedgerDeliveryEnvelope = {
+      channelId,
+      continuationToken,
+      message,
+      auth: options.auth ?? null,
+      ...(options.title === undefined ? {} : { title: options.title }),
+      ...(options.state === undefined ? {} : { state: options.state }),
+      ...(options.mode === undefined ? {} : { mode: options.mode }),
+      ...(options.purpose === undefined ? {} : { purpose: options.purpose }),
+      ...(options.workspaceDir === undefined
+        ? {}
+        : { workspaceDir: options.workspaceDir }),
+      ...(options.cloud === undefined ? {} : { cloud: options.cloud }),
+    };
+    await this.ledger.appendEvent(ledgerSessionId, {
+      eventId: `evt_${randomBytes(12).toString("hex")}`,
+      envelope: envelope as unknown as JsonValue,
+      sourceTs: this.resolveSourceTs(options),
+    });
+    // Ack point: the event is durable (mailbox blob + ledger pending).
+    // Do not await the pump: awaiting turns here would block HTTP create
+    // until the first turn committed, so a client could never park a
+    // mid-turn follow-up and a second pod would see a released lease.
+    const serving = this.servePending(ledgerSessionId);
+    return this.resolveDeliverHandle({
+      channelId,
+      continuationToken,
+      ledgerSessionId,
+      envelope,
+      created: ensured.created,
+      serving,
+    });
   }
 
-  /** Chain a delivery behind the session's in-flight ones. */
-  private enqueue(
+  /**
+   * The stand-in handle for a delivery whose event is parked while
+   * another holder serves the session: real durable identity, no local
+   * turn. `waitForCompletion` resolves immediately — the parked event's
+   * turn runs on the holder, so there is nothing local to await (the
+   * same contract as a coalesced send, whose outcome is not its own
+   * message's turn). The event stream and re-keying live wherever the
+   * turn runs, so both fail loudly here.
+   */
+  private parkedSession(
     ledgerSessionId: string,
-    run: () => Promise<ChannelSession>
-  ): Promise<ChannelSession> {
-    const prior = this.chains.get(ledgerSessionId) ?? Promise.resolve();
-    const next = prior.then(
-      () => run(),
-      () => run()
-    );
-    this.chains.set(ledgerSessionId, next);
-    void next
-      .catch(() => {})
-      .finally(() => {
-        if (this.chains.get(ledgerSessionId) === next) {
-          this.chains.delete(ledgerSessionId);
-        }
+    envelope: LedgerDeliveryEnvelope,
+    isNew: boolean
+  ): ChannelSession {
+    const unavailable = (what: string): Error =>
+      new Error(
+        `ledger serving: ${what} is unavailable for session ${ledgerSessionId}: the parked event runs on the session's current lease holder, not this process`
+      );
+    return {
+      id: ledgerSessionId,
+      continuationToken: envelope.continuationToken,
+      isNew,
+      info: {
+        id: ledgerSessionId,
+        channelId: envelope.channelId,
+        mode: envelope.mode ?? "chat",
+        auth: envelope.auth,
+        ...(envelope.title === undefined ? {} : { title: envelope.title }),
+        ...(envelope.purpose === undefined
+          ? {}
+          : { purpose: envelope.purpose }),
+        continuationKey: envelope.continuationToken,
+      },
+      getEventStream: () => Promise.reject(unavailable("the event stream")),
+      waitForCompletion: async () => ({ status: "finished" }),
+      setContinuationToken: () =>
+        Promise.reject(unavailable("re-keying the continuation token")),
+    };
+  }
+
+  /**
+   * Return a handle as soon as the engine session exists, without waiting
+   * for the pump to commit. If the pump settles without creating a
+   * session (walk-away, or a throw before admit), surface that: rethrow
+   * a failed claimant turn, otherwise the parked stand-in.
+   */
+  private async resolveDeliverHandle(args: {
+    channelId: string;
+    continuationToken: string;
+    ledgerSessionId: string;
+    envelope: LedgerDeliveryEnvelope;
+    created: boolean;
+    serving: Promise<void>;
+  }): Promise<ChannelSession> {
+    const {
+      channelId,
+      continuationToken,
+      ledgerSessionId,
+      envelope,
+      created,
+      serving,
+    } = args;
+    for (;;) {
+      const handle = await this.findSession(channelId, continuationToken);
+      if (handle !== undefined) {
+        return handle;
+      }
+      const pump = this.pumps.get(ledgerSessionId);
+      if (pump !== undefined) {
+        await Promise.race([
+          new Promise<void>((resolve) => {
+            setTimeout(resolve, 15);
+          }),
+          pump.then(
+            () => undefined,
+            () => undefined
+          ),
+        ]);
+        continue;
+      }
+      const createdLate = await this.findSession(channelId, continuationToken);
+      if (createdLate !== undefined) {
+        return createdLate;
+      }
+      await serving;
+      this.logger(
+        `[ledger] deliver on channel "${channelId}": event parked for session ${ledgerSessionId} (continuation ${continuationToken}); another holder is serving it and no local session exists — its commit (or the janitor) drains the event`
+      );
+      return this.parkedSession(ledgerSessionId, envelope, created);
+    }
+  }
+
+  /**
+   * Drain ordering: prefer the real source time over this pod's receipt
+   * time. `coalesceSourceTs` is a Slack-style seconds string
+   * (`"1712345678.000100"`); normalize sub-epoch-ms values to ms so they
+   * stay comparable with the `Date.now()` fallback.
+   */
+  private resolveSourceTs(options: LedgerDeliverOptions): number {
+    if (options.coalesceSourceTs !== undefined) {
+      const parsed = Number(options.coalesceSourceTs);
+      if (Number.isFinite(parsed) && parsed > 0) {
+        return parsed < 1e11 ? Math.round(parsed * 1000) : parsed;
+      }
+    }
+    return this.clock();
+  }
+
+  /**
+   * One warning per delivery naming the send options the mailbox does not
+   * replay — better a loud line than an author silently losing images or
+   * admission semantics on a ledger-mode agent.
+   */
+  private warnOnDroppedOptions(
+    channelId: string,
+    options: LedgerDeliverOptions
+  ): void {
+    const dropped = (
+      ["images", "sdkAgentId", "admission", "workspaceFiles"] as const
+    ).filter((name) => options[name] !== undefined);
+    if (dropped.length > 0) {
+      this.logger(
+        `[ledger] deliver on channel "${channelId}": dropping send options not replayed through the mailbox: ${dropped.join(", ")}`
+      );
+    }
+  }
+
+  /**
+   * Serve a session's pending events. When a pump is already running the
+   * caller walks away (the holder's commit re-reads pending) — except
+   * that the holder's *final* commit may have released before this
+   * append landed, so a re-check is chained behind it. Deliver never
+   * awaits this promise for its full lifetime: awaiting a new pump would
+   * block HTTP until the turn committed, and awaiting a running pump
+   * would deadlock a send issued from inside one of its turns.
+   */
+  private servePending(ledgerSessionId: string): Promise<void> {
+    const running = this.pumps.get(ledgerSessionId);
+    if (running !== undefined) {
+      const recheck = running
+        .catch(() => {})
+        .then(() => this.repumpIfPending(ledgerSessionId))
+        .catch(() => {});
+      this.background.add(recheck);
+      void recheck.finally(() => {
+        this.background.delete(recheck);
       });
-    return next;
+      return Promise.resolve();
+    }
+    return this.track(ledgerSessionId, () => this.runPump(ledgerSessionId));
+  }
+
+  /** Claim-or-defer entry used after an append and after a pump settles. */
+  private async runPump(ledgerSessionId: string): Promise<void> {
+    const claim = await this.ledger.claim(ledgerSessionId);
+    if (!claim.claimed) {
+      return;
+    }
+    await this.runClaimedTurns(ledgerSessionId, claim.lease);
+  }
+
+  /** Janitor hand-off: the claim already happened, just run the turns. */
+  private serveClaimed(claimed: JanitorClaimedSession): Promise<void> {
+    return this.track(claimed.sessionId, () =>
+      this.runClaimedTurns(claimed.sessionId, claimed.lease)
+    );
+  }
+
+  /**
+   * Re-pump after the previous holder settled, covering the release window
+   * where an append landed after that holder's final commit.
+   */
+  private async repumpIfPending(ledgerSessionId: string): Promise<void> {
+    if (this.pumps.has(ledgerSessionId)) {
+      return;
+    }
+    const snapshot = await this.ledger.readLedger(ledgerSessionId);
+    if (snapshot === undefined || snapshot.pending.length === 0) {
+      return;
+    }
+    if (snapshot.lease !== null && snapshot.lease.expiresAt > this.clock()) {
+      return;
+    }
+    await this.track(ledgerSessionId, () => this.runPump(ledgerSessionId));
   }
 
-  /** claim (waiting) → resident turn → commit-release. */
-  private async serveOne(
+  /** Register a pump in the per-session map for its lifetime. */
+  private track(
     ledgerSessionId: string,
-    request: LedgerTurnRequest
-  ): Promise<ChannelSession> {
-    const lease = await this.claimWithWait(ledgerSessionId);
+    run: () => Promise<void>
+  ): Promise<void> {
+    const tracked: Promise<void> = run().finally(() => {
+      if (this.pumps.get(ledgerSessionId) === tracked) {
+        this.pumps.delete(ledgerSessionId);
+      }
+    });
+    this.pumps.set(ledgerSessionId, tracked);
+    return tracked;
+  }
+
+  /**
+   * The drain → turn → commit loop for a held lease. Heartbeats extend the
+   * lease while turns run; a fenced heartbeat (or fenced commit) means a
+   * new holder took over — discard without committing; the new holder
+   * re-drains (at-least-once actuation, exactly-once ledger apply).
+   */
+  private async runClaimedTurns(
+    ledgerSessionId: string,
+    lease: LedgerLease
+  ): Promise<void> {
     let fenced = false;
     const heartbeat = setInterval(() => {
       this.ledger.heartbeat(ledgerSessionId, lease.generation).then(
@@ -174,64 +461,68 @@ export class LedgerServing {
     }, this.heartbeatIntervalMs);
     heartbeat.unref?.();
     try {
-      let handle: ChannelSession;
-      try {
-        handle = await this.deliverTurn(request);
-        await handle.waitForCompletion();
-      } catch (error) {
-        // The turn never committed; free the session for the next
-        // delivery instead of making it wait out the TTL. A fenced
-        // holder's release is a no-op.
-        await this.ledger
-          .release(ledgerSessionId, lease.generation)
-          .catch(() => {});
-        throw error;
+      for (;;) {
+        if (fenced) {
+          return;
+        }
+        const { head, events } = await this.ledger.drain(ledgerSessionId);
+        if (events.length === 0) {
+          await this.ledger.release(ledgerSessionId, lease.generation);
+          return;
+        }
+        for (const event of events) {
+          if (fenced) {
+            return;
+          }
+          const envelope = event.envelope as unknown as LedgerDeliveryEnvelope;
+          try {
+            const session = await this.deliverTurn(envelope);
+            await session.waitForCompletion();
+          } catch (error) {
+            if (!(error instanceof SessionAuthError)) {
+              throw error;
+            }
+            // Defense in depth behind deliver's principal gate: a parked
+            // envelope from a foreign principal (gate raced the session's
+            // first turn, or a pre-gate build wrote it) is consumed and
+            // committed away like any drained event. Aborting the batch
+            // instead would replay the already-actuated turns before it
+            // and re-throw on every future drain — one poison event must
+            // cost a log line, never a stuck session.
+            this.logger(
+              `[ledger] session ${ledgerSessionId}: discarding parked event ${event.eventId} — its sender is not the session's principal (${describeError(error)})`
+            );
+          }
+        }
+        const commit = await this.ledger.commit(ledgerSessionId, {
+          drainedEventIds: events.map((event) => event.eventId),
+          generation: lease.generation,
+          expectedHead: head,
+          commitId: randomUUID(),
+        });
+        if (commit.leaseReleased) {
+          return;
+        }
       }
-      if (fenced) {
-        // A new holder took over mid-turn (our lease lapsed). Discard:
-        // committing would fence anyway, and warm state is now stale.
+    } catch (error) {
+      if (error instanceof LedgerFencedError) {
         this.logger(
-          `[ledger] session ${ledgerSessionId} fenced mid-turn (generation ${lease.generation}); discarding without commit`
-        );
-        throw new LedgerFencedError(
-          `deliver(${ledgerSessionId}): fenced mid-turn at generation ${lease.generation}`
+          `[ledger] session ${ledgerSessionId} fenced mid-turn (generation ${lease.generation}); discarding — the new holder re-drains`
         );
+        return;
       }
-      await this.ledger.commit(ledgerSessionId, {
-        generation: lease.generation,
-        expectedHead: lease.head,
-        commitId: randomUUID(),
-      });
-      return handle;
+      // The turn never committed; free the session for the next
+      // append-driven claim instead of making it wait out the lease TTL
+      // (and the janitor cadence). Best-effort: a fenced holder's
+      // release is a no-op, and the events stay pending either way.
+      await this.ledger
+        .release(ledgerSessionId, lease.generation)
+        .catch(() => {});
+      throw error;
     } finally {
       clearInterval(heartbeat);
     }
   }
-
-  /**
-   * Claim the lease, waiting out another holder with bounded retries.
-   * The common waits are short: our own pod's deliveries never reach
-   * here concurrently (the in-process chain serializes them), so a held
-   * lease means another pod is serving — usually for one turn — or died
-   * (expiry unblocks us at ~30s).
-   */
-  private async claimWithWait(
-    ledgerSessionId: string
-  ): Promise<{ generation: number; head: number }> {
-    const start = this.clock();
-    for (;;) {
-      const claim = await this.ledger.claim(ledgerSessionId);
-      if (claim.claimed) {
-        return { generation: claim.lease.generation, head: claim.head };
-      }
-      if (this.clock() - start >= this.claimWaitTimeoutMs) {
-        throw new Error(
-          `ledger serving: session ${ledgerSessionId} is still leased by ${claim.holder} after ${this.claimWaitTimeoutMs}ms; giving up on this delivery`
-        );
-      }
-      await this.sleep(this.claimRetryDelayMs);
-    }
-  }
 }
 
 /** Mint the lease holder id for this process. */