@cursor/july 0.1.40 → 0.1.42

package/src/internal/discovery.ts

@@ -28,6 +28,7 @@ import {
   type AgentProject,
   type AgentProjectInfo,
   type AgentRuntime,
+  type AgentServingMode,
   type ArtifactsDefinition,
   type BuiltinToolsConfig,
   type ChannelDefinition,
@@ -188,11 +189,20 @@ export async function loadAgentProjects(
     );
   }
   const results: Array<{ slug: string; project: AgentProject }> = [];
+  // Storage namespaces (session mirror, host kv, durable-session ledger)
+  // key on the project NAME, not the mount slug — two co-hosted agents
+  // sharing a name would silently share sessions and coordination state.
+  const slugByName = new Map<string, string>();
   for (const child of children) {
-    results.push({
-      slug: child.slug,
-      project: await loadAgentProject(child.dir, options),
-    });
+    const project = await loadAgentProject(child.dir, options);
+    const priorSlug = slugByName.get(project.name);
+    if (priorSlug !== undefined) {
+      throw new Error(
+        `Duplicate agent name "${project.name}" under ${resolved}: agents "${priorSlug}" and "${child.slug}" both resolve to it (package.json "name", or the directory name when unset). Co-hosted agents must have distinct names — their storage and session namespaces key on the name.`
+      );
+    }
+    slugByName.set(project.name, child.slug);
+    results.push({ slug: child.slug, project });
   }
   return results;
 }
@@ -420,6 +430,7 @@ async function loadAgent(
         };
   const hosting = resolveHosting(ctx, agentDir, config?.hosting);
   const concurrency = resolveConcurrency(ctx, agentDir, config?.concurrency);
+  const serving = resolveServing(ctx, agentDir, config?.serving);
 
   if (runtime === "cloud") {
     warnCloudRuntimeLimitations(ctx, agentDir, {
@@ -443,6 +454,7 @@ async function loadAgent(
     local,
     hosting,
     concurrency,
+    serving,
     tools,
     skills,
     connections,
@@ -451,6 +463,27 @@ async function loadAgent(
   };
 }
 
+/**
+ * Validate the authored serving mode. An unrecognized value is an error
+ * diagnostic and falls back to undefined (resident) — a typo must not
+ * silently opt an agent into (or out of) ledger coordination.
+ */
+function resolveServing(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  serving: AgentServingMode | undefined
+): AgentServingMode | undefined {
+  if (serving === undefined || serving === "resident" || serving === "ledger") {
+    return serving;
+  }
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, join(agentDir, "agent.ts")),
+    message: `serving must be "resident" or "ledger"; got ${JSON.stringify(serving)}.`,
+  });
+  return undefined;
+}
+
 /** Absolute harness cwd parent, or undefined when unset / blank. */
 function resolveAgentCwd(
   ctx: DiscoveryContext,
@@ -504,7 +537,7 @@ function resolveHosting(
       warn(`hosting.secretNames: ${nameError}`);
     } else if (isReservedSecretName(name)) {
       warn(
-        `hosting.secretNames: ${JSON.stringify(name)} is platform-managed (CURSOR_* / Cursor-hosted storage) and injected automatically; omit it from secretNames.`
+        `hosting.secretNames: ${JSON.stringify(name)} is platform-managed (CURSOR_* / reserved hosted-storage names); omit it from secretNames.`
       );
     }
   }
@@ -1863,6 +1896,10 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
       name: connection.name,
       transport: connectionTransportLabel(connection.transport),
       hostOnly: connection.hostOnly,
+      cursorAccountServers:
+        "cursorAccount" in connection.transport
+          ? (connection.transport.servers ?? "*")
+          : undefined,
     })),
     subagents: agent.subagents.map((subagent) => ({
       name: subagent.name,

package/src/internal/distribution.ts

@@ -108,8 +108,10 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["evals/loaders", "evals/loaders.js"],
   ["ab", "ab.js"],
   ["artifacts", "artifacts.js"],
+  ["kv", "kv.js"],
+  ["kv/memory", "kv/memory-kv.js"],
+  ["ledger", "ledger.js"],
   ["storage", "storage.js"],
   ["storage/file-kv", "storage-backends/file-kv.js"],
-  ["storage/postgres-kv", "storage-backends/postgres-kv.js"],
   ["storage/cursor-hosted", "storage-backends/cursor-hosted.js"],
 ];

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

@@ -0,0 +1,95 @@
+/**
+ * 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, leases,
+ * fenced commits). The ledger consumes {@link SessionLedgerKv} — exactly
+ * the three CAS methods it uses, nothing more; this module adapts a
+ * storage backend's `cas` group 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";
+
+export interface StorageCasKvArgs {
+  agentName: string;
+  projectRoot: string;
+}
+
+/**
+ * Adapt a storage backend's `cas` group into the ledger's KV interface.
+ * Throws when the backend does not implement `cas` — 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)"
+    );
+  }
+  return {
+    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);
+    },
+  };
+}
+
+/**
+ * The one place the ledger's physical namespace is minted:
+ * `agentkit/v1/<agent>/durable-session/` — the {@link STORAGE_KEY_ROOT}
+ * conventions with the agent segment encoded like every other
+ * caller-controlled segment. The ledger itself never sees this string;
+ * it speaks bare `session/…` / `ledger/…` keys against a handle that
+ * {@link namespacedKv} has already scoped.
+ */
+export function ledgerKeyPrefix(agentName: string): string {
+  return `${STORAGE_KEY_ROOT}/${keySegment(agentName)}/durable-session/`;
+}
+
+/**
+ * Scope a raw store handle under a namespace, prepending it to every
+ * key on the way in. 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 {
+    getWithVersion: (key) => store.getWithVersion(namespace + key),
+    putIfAbsent: (key, value) => store.putIfAbsent(namespace + key, value),
+    putIfVersion: (key, value, expectedVersion) =>
+      store.putIfVersion(namespace + key, value, expectedVersion),
+  };
+}

package/src/internal/hosting.ts

@@ -15,7 +15,7 @@ export const MAX_SECRETS = 32;
 export const MAX_SECRET_VALUE_BYTES = 4096;
 /** Max secret name length. */
 export const MAX_SECRET_NAME_LENGTH = 64;
-/** Secret names the platform injects; user writes are rejected. */
+/** Secret names the platform manages; user writes are rejected. */
 export const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
 
 /**
@@ -84,7 +84,7 @@ export function validateSettableSecretName(name: string): string | undefined {
     return nameError;
   }
   if (isReservedSecretName(name)) {
-    return `Secret name ${JSON.stringify(name)} is platform-managed; the platform injects CURSOR_* and Cursor-hosted storage values automatically.`;
+    return `Secret name ${JSON.stringify(name)} is platform-managed; user secrets cannot claim CURSOR_* or reserved hosted-storage names.`;
   }
   return undefined;
 }

package/src/internal/init-project.ts

@@ -3,6 +3,7 @@
  */
 
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import type { ModelSetting } from "../types.js";
@@ -104,6 +105,7 @@ export async function initProject(
         description: `agent project: ${name}`,
         scripts: {
           check: "tsc --noEmit",
+          dev: "agent-sdk dev",
         },
         dependencies: {
           [PACKAGE_NAME]: `^${packageVersion()}`,
@@ -256,6 +258,141 @@ export async function installScaffoldDependencies(
   };
 }
 
+export interface LinkCliOntoPathOptions {
+  stdio?: "inherit" | "pipe";
+  runner?: (args: {
+    command: string;
+    args: string[];
+    cwd: string;
+    stdio: "inherit" | "pipe";
+  }) => Promise<{ exitCode: number; stderr: string }>;
+  /** Test seam — absolute path of the linked CLI when present. */
+  whichImpl?: (
+    command: string
+  ) => string | undefined | Promise<string | undefined>;
+}
+
+export interface LinkCliOntoPathResult {
+  ok: boolean;
+  exitCode: number;
+  stderr: string;
+  /** Absolute path to the linked `agent-sdk` when it resolves on PATH. */
+  resolvedPath?: string;
+}
+
+/**
+ * Put `agent-sdk` on the user PATH by installing the already-downloaded
+ * project copy into the npm global prefix. `npx @cursor/july init` only
+ * runs the package; this is the install that makes bare `agent-sdk …`
+ * work afterward.
+ */
+export async function linkCliOntoPath(
+  rootDir: string,
+  options: LinkCliOntoPathOptions = {}
+): Promise<LinkCliOntoPathResult> {
+  const packageDir = join(rootDir, "node_modules", PACKAGE_NAME);
+  if (!existsSync(packageDir)) {
+    return {
+      ok: false,
+      exitCode: 1,
+      stderr: `missing ${PACKAGE_NAME} under ${packageDir} (run npm install first)`,
+    };
+  }
+  const stdio = options.stdio ?? "inherit";
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  const args = ["install", "--global", "--no-fund", "--no-audit", packageDir];
+  const runner = options.runner ?? defaultNpmInstallRunner;
+  const result = await runner({ command, args, cwd: rootDir, stdio });
+  if (result.exitCode !== 0) {
+    return {
+      ok: false,
+      exitCode: result.exitCode,
+      stderr: result.stderr,
+    };
+  }
+  const whichImpl = options.whichImpl ?? resolveLinkedCli;
+  const resolvedPath = await whichImpl(CLI_COMMAND_NAME);
+  return {
+    ok: resolvedPath !== undefined,
+    exitCode: 0,
+    stderr:
+      resolvedPath === undefined
+        ? `${CLI_COMMAND_NAME} linked into the npm global prefix but is not on PATH; open a new shell or add that bin directory to PATH`
+        : "",
+    resolvedPath,
+  };
+}
+
+/** Prefer the npm-global bin; ignore an older `agent-sdk` earlier on PATH. */
+async function resolveLinkedCli(
+  commandName: string
+): Promise<string | undefined> {
+  const prefix = await npmGlobalPrefix();
+  if (prefix === undefined) {
+    return whichOnPath(commandName);
+  }
+  const binDir = process.platform === "win32" ? prefix : join(prefix, "bin");
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+      : [""];
+  for (const ext of exts) {
+    const candidate = join(binDir, `${commandName}${ext}`);
+    if (!existsSync(candidate)) {
+      continue;
+    }
+    // Only claim PATH success when this linked bin is the first hit.
+    const onPath = whichOnPath(commandName);
+    return onPath === candidate ? candidate : undefined;
+  }
+  return undefined;
+}
+
+async function npmGlobalPrefix(): Promise<string | undefined> {
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  return await new Promise((resolvePromise) => {
+    const child = spawn(command, ["prefix", "-g"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      env: process.env,
+    });
+    let out = "";
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => {
+      out += chunk;
+    });
+    child.on("error", () => resolvePromise(undefined));
+    child.on("close", (code) => {
+      if (code !== 0) {
+        resolvePromise(undefined);
+        return;
+      }
+      const prefix = out.trim();
+      resolvePromise(prefix === "" ? undefined : prefix);
+    });
+  });
+}
+
+function whichOnPath(commandName: string): string | undefined {
+  const pathEnv = process.env.PATH ?? "";
+  const sep = process.platform === "win32" ? ";" : ":";
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+      : [""];
+  for (const dir of pathEnv.split(sep)) {
+    if (dir === "") {
+      continue;
+    }
+    for (const ext of exts) {
+      const candidate = join(dir, `${commandName}${ext}`);
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return undefined;
+}
+
 async function defaultNpmInstallRunner(args: {
   command: string;
   args: string[];
@@ -323,6 +460,11 @@ export interface InitNextStepsOptions {
    * `login` (used for `--json` and when an interactive login attempt failed).
    */
   signedIn: boolean;
+  /**
+   * True when `agent-sdk` resolves on PATH after init linked the CLI.
+   * When false, next steps include a PATH export for `node_modules/.bin`.
+   */
+  cliOnPath: boolean;
   /** Override TTY color detection (tests / `--json` callers). */
   color?: boolean;
 }
@@ -415,6 +557,12 @@ function initNextStepEntries(options: InitNextStepsOptions): Array<{
   if (cd !== undefined) {
     steps.push({ command: cd });
   }
+  if (!options.cliOnPath) {
+    steps.push({
+      command: 'export PATH="$PWD/node_modules/.bin:$PATH"',
+      note: "use the project-local agent-sdk bin",
+    });
+  }
   if (!options.signedIn) {
     steps.push({
       command: `${CLI_COMMAND_NAME} login`,
@@ -436,6 +584,7 @@ export function initNextCommands(options: {
   rootDir: string;
   cwd: string;
   signedIn: boolean;
+  cliOnPath: boolean;
 }): string[] {
   return initNextStepEntries(options).map((step) => step.command);
 }
@@ -448,10 +597,10 @@ export function printInitGuide(): void {
   process.stdout.write(`${CLI_COMMAND_NAME} — coding agent setup
 
 Scaffold a project, then open the playground:
-  ${CLI_COMMAND_NAME} init ./my-agent   # installs deps; signs you in when needed
+  npx ${PACKAGE_NAME} init ./my-agent   # installs deps + puts agent-sdk on PATH
   cd ./my-agent && ${CLI_COMMAND_NAME} dev
 
-Recommended loop once the project exists:
+Recommended loop once the project exists (from the project directory):
   1. Edit agent/ + tools under agent/tools/
   2. ${CLI_COMMAND_NAME} info --dir . --json
   3. ${CLI_COMMAND_NAME} run --dir . --message "..."

package/src/internal/ledger-serving.ts

@@ -0,0 +1,240 @@
+/**
+ * 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.
+ *
+ * **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.
+ *
+ * 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.
+ */
+
+import { randomBytes, randomUUID } from "node:crypto";
+import type { 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 { 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 {
+  channelId: string;
+  continuationToken: string;
+  message: string;
+  options: LedgerDeliverOptions;
+}
+
+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.
+   */
+  deliverTurn: (request: LedgerTurnRequest) => Promise<ChannelSession>;
+  logger?: (line: string) => void;
+  /** Lease heartbeat cadence while the turn runs (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;
+  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 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>>();
+
+  constructor(options: LedgerServingOptions) {
+    this.ledger = options.ledger;
+    this.deliverTurn = options.deliverTurn;
+    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)));
+  }
+
+  /** Settle every queued and in-flight delivery. */
+  async close(): Promise<void> {
+    await Promise.allSettled([...this.chains.values()]);
+  }
+
+  /**
+   * 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.
+   */
+  async deliver(
+    channelId: string,
+    message: string,
+    options: LedgerDeliverOptions
+  ): Promise<ChannelSession> {
+    const continuationToken = options.continuationToken ?? newContinuationKey();
+    const ensured = await this.ledger.ensureSession(
+      `${channelId}/${continuationToken}`
+    );
+    return this.enqueue(ensured.session.sessionId, () =>
+      this.serveOne(ensured.session.sessionId, {
+        channelId,
+        continuationToken,
+        message,
+        options,
+      })
+    );
+  }
+
+  /** Chain a delivery behind the session's in-flight ones. */
+  private enqueue(
+    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);
+        }
+      });
+    return next;
+  }
+
+  /** claim (waiting) → resident turn → commit-release. */
+  private async serveOne(
+    ledgerSessionId: string,
+    request: LedgerTurnRequest
+  ): Promise<ChannelSession> {
+    const lease = await this.claimWithWait(ledgerSessionId);
+    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 {
+      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;
+      }
+      if (fenced) {
+        // A new holder took over mid-turn (our lease lapsed). Discard:
+        // committing would fence anyway, and warm state is now stale.
+        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}`
+        );
+      }
+      await this.ledger.commit(ledgerSessionId, {
+        generation: lease.generation,
+        expectedHead: lease.head,
+        commitId: randomUUID(),
+      });
+      return handle;
+    } 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. */
+export function newLedgerPodId(): string {
+  return `pod_${randomBytes(6).toString("hex")}`;
+}