@cursor/july 0.1.76 → 0.1.78

package/src/internal/durable-session-store.ts

@@ -1,134 +0,0 @@
-/**
- * Durable-session store resolution.
- *
- * Two APIs, one backend: `defineStorage` is the **storage API** (agent
- * state — session records, event chunks, author KV), and the session
- * ledger is the **durable session API** (session identity, mailboxes,
- * leases, fenced commits). The ledger consumes {@link SessionLedgerKv} —
- * the full CAS-capable KV surface, since the inbox reads/sweeps mailbox
- * payload blobs (`get`/`put`/`delete`) and scans by prefix (`listKeys`)
- * on top of the CAS trio; this module adapts a storage backend's methods
- * into that interface, so a deployment's one authored backend serves
- * both APIs by default.
- *
- * Calls go straight at the config's methods — NOT through the
- * StorageCoordinator: the coordinator's queue is bounded, serialized, and
- * at-most-once (mirror semantics), while ledger CAS calls are the
- * correctness path and must observe their own results synchronously.
- */
-
-import type { SessionLedgerKv } from "../ledger/session-ledger.js";
-import {
-  keySegment,
-  STORAGE_KEY_ROOT,
-  type StorageConfig,
-  type StorageContext,
-} from "../storage.js";
-import type { JsonValue } from "../types.js";
-
-export interface StorageCasKvArgs {
-  agentName: string;
-  projectRoot: string;
-}
-
-/**
- * The one place the ledger's physical namespace is minted: the per-agent
- * prefix for ledger state, following the {@link storageKeys} convention
- * (`<root>/<agent>/<family>/…`) so a store shared by several ledger-mode
- * agents (one fileKv dir, one hosted deployment) never mixes their
- * sessions, leases, or mailboxes — and so each agent's janitor
- * prefix-scan only ever sees its own ledgers. The extra
- * `durable-session` segment keeps the ledger's `session/` family out of
- * `storageKeys.sessionPrefix` scans (storage restore lists
- * `<root>/<agent>/session/`). The ledger itself never sees this string:
- * it speaks bare `session/…` / `ledger/…` / `mailbox/…` keys against a
- * handle that {@link namespacedKv} has already scoped.
- */
-export function ledgerKeyPrefix(agentName: string): string {
-  return `${STORAGE_KEY_ROOT}/${keySegment(agentName)}/durable-session/`;
-}
-
-/**
- * Adapt a storage backend into the ledger's KV interface. Throws when
- * the backend does not implement the `cas` group, or omits `get` /
- * `delete` (optional for resident-only sinks, but the ledger reads and
- * sweeps mailbox payload blobs through the same store) — the caller
- * turns that into the fail-fast startup error for `serving: "ledger"`.
- * Every call carries a `reason: "coordination"` {@link StorageContext}.
- */
-export function storageCasKv(
-  config: StorageConfig,
-  args: StorageCasKvArgs
-): SessionLedgerKv {
-  const ctx: StorageContext = {
-    agentName: args.agentName,
-    projectRoot: args.projectRoot,
-    reason: "coordination",
-  };
-  const { cas } = config;
-  if (cas === undefined) {
-    throw new Error(
-      "storageCasKv: the storage backend does not implement the cas group (conditional writes)"
-    );
-  }
-  const get = config.get;
-  const remove = config.delete;
-  if (get === undefined || remove === undefined) {
-    throw new Error(
-      "storageCasKv: the storage backend must implement get and delete (the session ledger reads and sweeps payload blobs through the same store)"
-    );
-  }
-  return {
-    async get(key): Promise<JsonValue | undefined> {
-      return (await get(key, ctx)) ?? undefined;
-    },
-    async put(key, value): Promise<void> {
-      await config.put(key, value, ctx);
-    },
-    async delete(key): Promise<void> {
-      await remove(key, ctx);
-    },
-    async getWithVersion(key) {
-      return await cas.getWithVersion(key, ctx);
-    },
-    async putIfAbsent(key, value) {
-      return await cas.putIfAbsent(key, value, ctx);
-    },
-    async putIfVersion(key, value, expectedVersion) {
-      return await cas.putIfVersion(key, value, expectedVersion, ctx);
-    },
-    async listKeys(prefix) {
-      return await cas.listKeys(prefix, ctx);
-    },
-  };
-}
-
-/**
- * Scope a raw store handle under a namespace: every key going in gets it
- * prepended, and `listKeys` results come back with it **stripped**, so a
- * caller that lists and then reads/deletes the returned keys stays fully
- * prefix-free (the janitor scan and the orphan sweep do exactly that).
- * Applied exactly once, where the engine constructs the ledger's store
- * handle — the same conceptual boundary where `host.kv` gets its agent
- * scoping. Internal: not part of the public kv interface, and callers
- * (including the explicit `durableSessionStore` override) always supply
- * the raw store — they never write prefixes.
- */
-export function namespacedKv(
-  store: SessionLedgerKv,
-  namespace: string
-): SessionLedgerKv {
-  return {
-    get: (key) => store.get(namespace + key),
-    put: (key, value) => store.put(namespace + key, value),
-    delete: (key) => store.delete(namespace + key),
-    getWithVersion: (key) => store.getWithVersion(namespace + key),
-    putIfAbsent: (key, value) => store.putIfAbsent(namespace + key, value),
-    putIfVersion: (key, value, expectedVersion) =>
-      store.putIfVersion(namespace + key, value, expectedVersion),
-    listKeys: async (prefix) => {
-      const keys = await store.listKeys(namespace + prefix);
-      return keys.map((key) => key.slice(namespace.length));
-    },
-  };
-}

package/src/internal/ledger-serving.ts

@@ -1,531 +0,0 @@
-/**
- * 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.
- *
- * 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.
- *
- * 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 {
-  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,
-  LedgerFencedError,
-} from "../ledger/session-ledger.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";
-
-/** The JSON payload stored in `mailbox/<sessionId>/<eventId>`. */
-export interface LedgerDeliveryEnvelope {
-  channelId: string;
-  continuationToken: string;
-  message: string;
-  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 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: (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 turns run (default 10s). */
-  heartbeatIntervalMs?: number;
-  /** Janitor scan cadence (default `DEFAULT_JANITOR_INTERVAL_MS`). */
-  janitorIntervalMs?: number;
-  clock?: () => number;
-}
-
-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 clock: () => number;
-  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.clock = options.clock ?? Date.now;
-    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,
-    });
-  }
-
-  /** 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> {
-    // 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`: 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,
-    message: string,
-    options: LedgerDeliverOptions
-  ): Promise<ChannelSession> {
-    const continuationToken = options.continuationToken ?? newContinuationKey();
-    this.warnOnDroppedOptions(channelId, options);
-    const ensured = await this.ledger.ensureSession(
-      `${channelId}/${continuationToken}`
-    );
-    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,
-    });
-  }
-
-  /**
-   * 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,
-    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 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));
-  }
-
-  /** Register a pump in the per-session map for its lifetime. */
-  private track(
-    ledgerSessionId: string,
-    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(
-        (result) => {
-          if (!result.ok) {
-            fenced = true;
-          }
-        },
-        () => {
-          // Transient KV failure: the next beat retries within the TTL.
-        }
-      );
-    }, this.heartbeatIntervalMs);
-    heartbeat.unref?.();
-    try {
-      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;
-        }
-      }
-    } catch (error) {
-      if (error instanceof LedgerFencedError) {
-        this.logger(
-          `[ledger] session ${ledgerSessionId} fenced mid-turn (generation ${lease.generation}); discarding — the new holder re-drains`
-        );
-        return;
-      }
-      // 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);
-    }
-  }
-}
-
-/** Mint the lease holder id for this process. */
-export function newLedgerPodId(): string {
-  return `pod_${randomBytes(6).toString("hex")}`;
-}