@bermudi/pi-delegate 0.1.18 → 0.1.20

package/pool.ts

@@ -9,7 +9,7 @@ import { fmtDuration, fmtTokens, shortenPath } from "./format.ts";
 // ── Public value types (cross the seam) ───────────────────────────────────
 
 /** Immutable config captured when a session enters the pool. Write-once: once
- * stored it never changes — only stats mutate, and only via {@link commit}.
+ * stored it never changes — only stats mutate, and only via {@link SessionPool.commit}.
  * Reuse always validates cwd/thinking/tools and validates an explicitly
  * requested model or base prompt against this frozen configuration. */
 export interface FrozenConfig {
@@ -51,7 +51,7 @@ export interface ConfigMismatch {
   requested: string;
 }
 
-/** Result of {@link checkout}. Discriminated so the caller handles
+/** Result of {@link SessionPool.checkout}. Discriminated so the caller handles
  *  hit/miss/mismatch without parsing. checkout is PURE — it does not bump
  *  lastUsed (that is commit's job), so a speculative checkout that bails leaves
  *  no trace. */
@@ -67,7 +67,7 @@ export type CheckoutResult =
   | { status: "miss" }
   | { status: "mismatch"; mismatches: ConfigMismatch[] };
 
-/** Payload for {@link commit}. The caller always assembles the full payload on
+/** Payload for {@link SessionPool.commit}. The caller always assembles the full payload on
  *  a successful run; commit decides insert-vs-recordUse by map presence (sound
  *  because the per-session lock serializes same-sessionId tasks). */
 export interface CommitPayload {
@@ -78,8 +78,6 @@ export interface CommitPayload {
   tokens: number;
 }
 
-// ── Internal state (PRIVATE — callers cross the seam, never the Map) ───────
-
 interface PooledAgent {
   /** The live AgentSession — reused across prompts for this sessionId. */
   session: AgentSession;
@@ -95,497 +93,563 @@ interface PooledAgent {
   promptCount: number;
 }
 
-/** Module-level pool — lives for the entire Pi session. Not exported: callers
- * use checkout/commit/configFor/closePooledAgent/closeAllPooledAgents/listPooledAgents. */
-const agentPool = new Map<string, PooledAgent>();
-
-// AgentSession.abort() normally settles promptly, but a provider or tool can
-// ignore cancellation. Cleanup must not make parent-session shutdown hostage to
-// that promise, so close operations use a bounded wait before forced disposal.
-const DEFAULT_POOL_ABORT_TIMEOUT_MS = 10_000;
-let poolAbortTimeoutMs = DEFAULT_POOL_ABORT_TIMEOUT_MS;
-
-/** Per-session lock — serializes access to a pooled agent so concurrent
- *  delegate calls with the same sessionId queue instead of interleaving. */
-const sessionLocks = new Map<string, Promise<void>>();
-
 type PoolShutdownState = "open" | "closing" | "closed";
-let poolState: PoolShutdownState = "open";
-let closePromise: Promise<void> | null = null;
 
-function now(): number {
-  return Date.now();
+interface AbortOutcome {
+  error?: unknown;
+  timedOut?: boolean;
 }
 
-function assertPoolOpenForNormalWork(): void {
-  if (poolState !== "open") {
-    throw new Error("Session pool is not accepting new work.");
+/** Encapsulated pooled-session state and policy. Each instance owns its own
+ *  entries, per-session locks, shutdown state/promise, and abort timeout so
+ *  injected runtimes are fully isolated from one another and from the default
+ *  module-level pool. */
+export class SessionPool {
+  static readonly DEFAULT_ABORT_TIMEOUT_MS = 10_000;
+
+  private entries = new Map<string, PooledAgent>();
+  private readonly sessionLocks = new Map<string, Promise<void>>();
+  private state: PoolShutdownState = "open";
+  private closePromise: Promise<void> | null = null;
+  private abortTimeoutMs = SessionPool.DEFAULT_ABORT_TIMEOUT_MS;
+  private quarantineWithoutDisposalOverride:
+    ((sessionId: string, expectedSession: AgentSession) => boolean) | undefined;
+
+  private now(): number {
+    return Date.now();
   }
-}
 
-function waitForActiveSessionLocks(): Promise<void> {
-  const locks = [...sessionLocks.values()];
-  return Promise.all(locks).then(() => undefined);
-}
-
-function deepFreeze<T>(value: T, seen = new WeakSet<object>()): T {
-  if (typeof value !== "object" || value === null || seen.has(value)) {
-    return value;
+  private assertPoolOpenForNormalWork(): void {
+    if (this.state !== "open") {
+      throw new Error("Session pool is not accepting new work.");
+    }
   }
-  seen.add(value);
-  const record = value as Record<PropertyKey, unknown>;
-  for (const key of Reflect.ownKeys(value)) deepFreeze(record[key], seen);
-  return Object.freeze(value);
-}
-
-/** Defensive value copy for the capability configuration crossing the pool seam. */
-function cloneFrozenConfig(config: FrozenConfig): FrozenConfig {
-  return deepFreeze(structuredClone(config));
-}
 
-// ── Read + validate ───────────────────────────────────────────────────────
-
-/** Look up a pooled session and validate a reuse request against its frozen
- *  config. PURE: no lastUsed bump, no sweep — safe to call speculatively, even
- *  outside the session lock (the frozen config is write-once, so a concurrent
- *  commit cannot tear the read).
- *
- *  - hit      → pooled, and {cwd,thinking,tools} match frozen. Returns the live
- *               handles + the frozen model id.
- *  - miss     → not pooled (never inserted, closed, or parent session ended).
- *               Caller materializes.
- *  - mismatch → pooled but its immutable configuration conflicts with this
- *               request. Caller formats the structured diff into an error.
- *
- *  lastUsed is bumped by recordUse() after a completed pool hit, not here — so
- *  a checkout that bails (e.g. a resumeFrom conflict) does not affect stats. */
-export function checkout(
-  sessionId: string,
-  candidate: ConfigCandidate,
-): CheckoutResult {
-  const pooled = agentPool.get(sessionId);
-  if (!pooled) return { status: "miss" };
-
-  const frozen = pooled.config;
-  const mismatches: ConfigMismatch[] = [];
-  if (frozen.cwd !== candidate.cwd) {
-    mismatches.push({
-      field: "cwd",
-      frozen: frozen.cwd,
-      requested: candidate.cwd,
-    });
-  }
-  if (frozen.thinking !== candidate.thinking) {
-    mismatches.push({
-      field: "thinking",
-      frozen: frozen.thinking,
-      requested: candidate.thinking,
-    });
-  }
-  // Tools are compared as order-independent sets (sorted join), so a reuse that
-  // lists the same tools in a different order is not a false mismatch.
-  const frozenTools = [...frozen.tools].sort().join(",");
-  const requestedTools = [...candidate.tools].sort().join(",");
-  if (frozenTools !== requestedTools) {
-    mismatches.push({
-      field: "tools",
-      frozen: frozenTools,
-      requested: requestedTools,
-    });
-  }
-  if (
-    candidate.model &&
-    (frozen.model.provider !== candidate.model.provider ||
-      frozen.model.id !== candidate.model.id)
-  ) {
-    mismatches.push({
-      field: "model",
-      frozen: `${frozen.model.provider}/${frozen.model.id}`,
-      requested: `${candidate.model.provider}/${candidate.model.id}`,
-    });
+  private waitForActiveSessionLocks(): Promise<void> {
+    const locks = [...this.sessionLocks.values()];
+    return Promise.all(locks).then(() => undefined);
   }
-  if (
-    candidate.systemPrompt !== undefined &&
-    frozen.systemPrompt !== candidate.systemPrompt
-  ) {
-    // Prompts can be large and sensitive; callers need the conflicting field,
-    // not the instruction text in their tool-result context.
-    mismatches.push({
-      field: "systemPrompt",
-      frozen: "<frozen>",
-      requested: "<requested>",
-    });
-  }
-  if (frozen.providerExtensions !== candidate.providerExtensions) {
-    // This field is derived from configured package sources, which may contain
-    // credentials. Never expose either the sources or their digest through the
-    // public checkout result; a digest can still enable dictionary guessing.
-    mismatches.push({
-      field: "providerExtensions",
-      frozen: "<redacted>",
-      requested: "<redacted>",
-    });
+
+  private deepFreeze<T>(value: T, seen = new WeakSet<object>()): T {
+    if (typeof value !== "object" || value === null || seen.has(value)) {
+      return value;
+    }
+    seen.add(value);
+    const record = value as Record<PropertyKey, unknown>;
+    for (const key of Reflect.ownKeys(value))
+      this.deepFreeze(record[key], seen);
+    return Object.freeze(value);
   }
-  if (mismatches.length) return { status: "mismatch", mismatches };
-
-  return {
-    status: "hit",
-    session: pooled.session,
-    sessionManager: pooled.sessionManager,
-    sessionFile: pooled.sessionFile,
-    modelId: frozen.model.id,
-  };
-}
 
-// ── The sole mutator (besides close) ──────────────────────────────────────
+  /** Defensive value copy for the capability configuration crossing the pool seam. */
+  private cloneFrozenConfig(config: FrozenConfig): FrozenConfig {
+    return this.deepFreeze(structuredClone(config));
+  }
 
-/**
- * Insert the first successful prompt for a fresh/resumed session into the pool.
- *
- *  MUST be called inside withSessionLock(sessionId, …) and only when this run
- *  should transfer ownership from lifecycle to the pool. Returns true when the
- *  session is now pool-owned, false when insertion is blocked (shutdown) or
- *  impossible (missing manager/file).
- */
-export function commit(sessionId: string, payload: CommitPayload): boolean {
-  // Shutdown-aware policy: once shutdown has started, inserting a new pool entry
-  // is unsafe. The lifecycle handles the still-owned session (abort/cleanup) and
-  // should dispose it instead of inserting it after the barrier begins.
-  if (poolState !== "open") {
-    return false;
+  /** Look up a pooled session and validate a reuse request against its frozen
+   *  config. PURE: no lastUsed bump, no sweep — safe to call speculatively, even
+   *  outside the session lock (the frozen config is write-once, so a concurrent
+   *  commit cannot tear the read).
+   *
+   *  - hit      → pooled, and {cwd,thinking,tools} match frozen. Returns the live
+   *               handles + the frozen model id.
+   *  - miss     → not pooled (never inserted, closed, or parent session ended).
+   *               Caller materializes.
+   *  - mismatch → pooled but its immutable configuration conflicts with this
+   *               request. Caller formats the structured diff into an error.
+   *
+   *  lastUsed is bumped by recordUse() after a completed pool hit, not here — so
+   *  a checkout that bails (e.g. a resumeFrom conflict) does not affect stats. */
+  checkout(sessionId: string, candidate: ConfigCandidate): CheckoutResult {
+    const pooled = this.entries.get(sessionId);
+    if (!pooled) return { status: "miss" };
+
+    const frozen = pooled.config;
+    const mismatches: ConfigMismatch[] = [];
+    if (frozen.cwd !== candidate.cwd) {
+      mismatches.push({
+        field: "cwd",
+        frozen: frozen.cwd,
+        requested: candidate.cwd,
+      });
+    }
+    if (frozen.thinking !== candidate.thinking) {
+      mismatches.push({
+        field: "thinking",
+        frozen: frozen.thinking,
+        requested: candidate.thinking,
+      });
+    }
+    // Tools are compared as order-independent sets (sorted join), so a reuse that
+    // lists the same tools in a different order is not a false mismatch.
+    const frozenTools = [...frozen.tools].sort().join(",");
+    const requestedTools = [...candidate.tools].sort().join(",");
+    if (frozenTools !== requestedTools) {
+      mismatches.push({
+        field: "tools",
+        frozen: frozenTools,
+        requested: requestedTools,
+      });
+    }
+    if (
+      candidate.model &&
+      (frozen.model.provider !== candidate.model.provider ||
+        frozen.model.id !== candidate.model.id)
+    ) {
+      mismatches.push({
+        field: "model",
+        frozen: `${frozen.model.provider}/${frozen.model.id}`,
+        requested: `${candidate.model.provider}/${candidate.model.id}`,
+      });
+    }
+    if (
+      candidate.systemPrompt !== undefined &&
+      frozen.systemPrompt !== candidate.systemPrompt
+    ) {
+      // Prompts can be large and sensitive; callers need the conflicting field,
+      // not the instruction text in their tool-result context.
+      mismatches.push({
+        field: "systemPrompt",
+        frozen: "<frozen>",
+        requested: "<requested>",
+      });
+    }
+    if (frozen.providerExtensions !== candidate.providerExtensions) {
+      // This field is derived from configured package sources, which may contain
+      // credentials. Never expose either the sources or their digest through the
+      // public checkout result; a digest can still enable dictionary guessing.
+      mismatches.push({
+        field: "providerExtensions",
+        frozen: "<redacted>",
+        requested: "<redacted>",
+      });
+    }
+    if (mismatches.length) return { status: "mismatch", mismatches };
+
+    return {
+      status: "hit",
+      session: pooled.session,
+      sessionManager: pooled.sessionManager,
+      sessionFile: pooled.sessionFile,
+      modelId: frozen.model.id,
+    };
   }
 
-  // Miss → success: insert. A pooled entry needs a concrete file/manager.
-  if (!payload.sessionManager || !payload.sessionFile) return false;
-
-  if (agentPool.has(sessionId)) return false;
-  agentPool.set(sessionId, {
-    session: payload.session,
-    sessionManager: payload.sessionManager,
-    sessionFile: payload.sessionFile,
-    config: cloneFrozenConfig(payload.frozen),
-    lastUsed: now(),
-    createdAt: now(),
-    totalTokens: payload.tokens,
-    promptCount: 1,
-  });
-  return true;
-}
+  /**
+   * Insert the first successful prompt for a fresh/resumed session into the pool.
+   *
+   *  MUST be called inside withSessionLock(sessionId, …) and only when this run
+   *  should transfer ownership from lifecycle to the pool. Returns true when the
+   *  session is now pool-owned, false when insertion is blocked (shutdown) or
+   *  impossible (missing manager/file).
+   */
+  commit(sessionId: string, payload: CommitPayload): boolean {
+    // Shutdown-aware policy: once shutdown has started, inserting a new pool entry
+    // is unsafe. The lifecycle handles the still-owned session (abort/cleanup) and
+    // should dispose it instead of inserting it after the barrier begins.
+    if (this.state !== "open") {
+      return false;
+    }
 
-/** Record a completed run against an existing pooled session. This is separate
- *  from commit() so lifecycle can distinguish ownership transfer from hit
- *  accounting. Returns true only when the sessionId is currently pooled.
- */
-export function recordUse(sessionId: string, tokens: number): boolean {
-  const existing = agentPool.get(sessionId);
-  if (!existing) return false;
+    // Miss → success: insert. A pooled entry needs a concrete file/manager.
+    if (!payload.sessionManager || !payload.sessionFile) return false;
+
+    if (this.entries.has(sessionId)) return false;
+    this.entries.set(sessionId, {
+      session: payload.session,
+      sessionManager: payload.sessionManager,
+      sessionFile: payload.sessionFile,
+      config: this.cloneFrozenConfig(payload.frozen),
+      lastUsed: this.now(),
+      createdAt: this.now(),
+      totalTokens: payload.tokens,
+      promptCount: 1,
+    });
+    return true;
+  }
 
-  existing.lastUsed = now();
-  existing.totalTokens += tokens;
-  existing.promptCount++;
-  return true;
-}
+  /** Record a completed run against an existing pooled session. This is separate
+   *  from commit() so lifecycle can distinguish ownership transfer from hit
+   *  accounting. Returns true only when the sessionId is currently pooled. */
+  recordUse(sessionId: string, tokens: number): boolean {
+    const existing = this.entries.get(sessionId);
+    if (!existing) return false;
+
+    existing.lastUsed = this.now();
+    existing.totalTokens += tokens;
+    existing.promptCount++;
+    return true;
+  }
 
-/** Remove an exact live session from reuse without aborting or disposing it.
- * Lifecycle uses this only after runner reports quiescence abandonment: any
- * ordinary pool close would race provider/extension work that may still be
- * running. The caller retains the detached session until its background safety
- * promise resolves. */
-export function _quarantinePooledAgentWithoutDisposal(
-  sessionId: string,
-  expectedSession: AgentSession,
-): boolean {
-  const existing = agentPool.get(sessionId);
-  if (!existing || existing.session !== expectedSession) return false;
-  agentPool.delete(sessionId);
-  return true;
-}
+  /** Remove an exact live session from reuse without aborting or disposing it.
+   * Lifecycle uses this only after runner reports quiescence abandonment: any
+   * ordinary pool close would race provider/extension work that may still be
+   * running. The caller retains the detached session until its background safety
+   * promise resolves. */
+  quarantinePooledAgentWithoutDisposal(
+    sessionId: string,
+    expectedSession: AgentSession,
+  ): boolean {
+    if (this.quarantineWithoutDisposalOverride) {
+      return this.quarantineWithoutDisposalOverride(sessionId, expectedSession);
+    }
+    const existing = this.entries.get(sessionId);
+    if (!existing || existing.session !== expectedSession) return false;
+    this.entries.delete(sessionId);
+    return true;
+  }
 
-// ── Read-only defaults (for task-resolution) ──────────────────────────────
+  /** @internal Test-only override for the quarantine-without-disposal path. */
+  _setQuarantinePooledAgentWithoutDisposalForTesting(
+    override:
+      | ((sessionId: string, expectedSession: AgentSession) => boolean)
+      | undefined,
+  ): void {
+    this.quarantineWithoutDisposalOverride = override;
+  }
 
-/** Frozen config for a pooled session, or undefined if not pooled. Lock-free —
- *  safe because the stored config is a deeply frozen defensive copy. Callers
- *  receive another frozen copy so values crossing the pool seam cannot mutate
- *  its capability contract. Used by resolveTasks to default {systemPrompt,
- *  model, thinking, tools} for a task that supplies only a sessionId. */
-export function configFor(
-  sessionId: string,
-): Readonly<FrozenConfig> | undefined {
-  const config = agentPool.get(sessionId)?.config;
-  return config ? cloneFrozenConfig(config) : undefined;
-}
+  /** Frozen config for a pooled session, or undefined if not pooled. Lock-free —
+   *  safe because the stored config is a deeply frozen defensive copy. Callers
+   *  receive another frozen copy so values crossing the pool seam cannot mutate
+   *  its capability contract. Used by resolveTasks to default {systemPrompt,
+   *  model, thinking, tools} for a task that supplies only a sessionId. */
+  configFor(sessionId: string): Readonly<FrozenConfig> | undefined {
+    const config = this.entries.get(sessionId)?.config;
+    return config ? this.cloneFrozenConfig(config) : undefined;
+  }
 
-// ── Lock primitive (D1) ───────────────────────────────────────────────────
-
-/** Per-session lock — serializes concurrent calls with the same sessionId.
- *  Different ids run in parallel. Exported as a primitive so the caller
- *  (lifecycle) can bracket the ENTIRE acquire/run/commit flow; checkout/commit
- *  do NOT lock internally because their only caller is already inside this
- *  bracket. Close is also invoked under this lock, so it never disposes an
- *  in-flight prompt.
- *
- *  External callers must go through this exported path only while the pool is
- *  open. Internal callers that are already synchronized by a higher-level lock
- *  can use `withSessionLockInternal`.
- */
-export async function withSessionLock<T>(
-  sessionId: string,
-  fn: () => Promise<T>,
-): Promise<T> {
-  assertPoolOpenForNormalWork();
-  return withSessionLockInternal(sessionId, fn);
-}
+  /** Per-session lock — serializes concurrent calls with the same sessionId.
+   *  Different ids run in parallel. Exported as a primitive so the caller
+   *  (lifecycle) can bracket the ENTIRE acquire/run/commit flow; checkout/commit
+   *  do NOT lock internally because their only caller is already inside this
+   *  bracket. Close is also invoked under this lock, so it never disposes an
+   *  in-flight prompt.
+   *
+   *  External callers must go through this exported path only while the pool is
+   *  open. Internal callers that are already synchronized by a higher-level lock
+   *  can use `withSessionLockInternal`.
+   */
+  withSessionLock<T>(sessionId: string, fn: () => Promise<T>): Promise<T> {
+    this.assertPoolOpenForNormalWork();
+    return this.withSessionLockInternal(sessionId, fn);
+  }
 
-/** Internal lock variant that does not reject during shutdown. Use only from
- *  lifecycle/control paths that already account for pool shutdown state.
- */
-async function withSessionLockInternal<T>(
-  sessionId: string,
-  fn: () => Promise<T>,
-): Promise<T> {
-  const prev = sessionLocks.get(sessionId);
-  let resolve!: () => void;
-  const promise = new Promise<void>((r) => {
-    resolve = r;
-  });
-  // Install ourselves BEFORE awaiting — so the next waiter queues behind us,
-  // not behind the same predecessor we're waiting on.
-  sessionLocks.set(sessionId, promise);
-  try {
-    if (prev) await prev;
-    return await fn();
-  } finally {
-    resolve();
-    // Only clean up if no one queued behind us (our promise is still current).
-    // If a waiter installed their own promise, leave it — deleting would
-    // clobber their map entry and break the chain.
-    if (sessionLocks.get(sessionId) === promise) {
-      sessionLocks.delete(sessionId);
+  /** Internal lock variant that does not reject during shutdown. Use only from
+   *  lifecycle/control paths that already account for pool shutdown state. */
+  private async withSessionLockInternal<T>(
+    sessionId: string,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    const prev = this.sessionLocks.get(sessionId);
+    let resolve!: () => void;
+    const promise = new Promise<void>((r) => {
+      resolve = r;
+    });
+    // Install ourselves BEFORE awaiting — so the next waiter queues behind us,
+    // not behind the same predecessor we’re waiting on.
+    this.sessionLocks.set(sessionId, promise);
+    try {
+      if (prev) await prev;
+      return await fn();
+    } finally {
+      resolve();
+      // Only clean up if no one queued behind us (our promise is still current).
+      // If a waiter installed their own promise, leave it — deleting would
+      // clobber their map entry and break the chain.
+      if (this.sessionLocks.get(sessionId) === promise) {
+        this.sessionLocks.delete(sessionId);
+      }
     }
   }
-}
 
-// ── Teardown / display ────────────────────────────────────────────────────
-
-interface AbortOutcome {
-  error?: unknown;
-  timedOut?: boolean;
-}
-
-/** Start cancellation without letting a cleanup failure become unhandled while
- * a holder of the per-session lock is still unwinding. A wedged provider/tool
- * cannot keep disposal or parent shutdown waiting forever. */
-function beginAbort(session: AgentSession): Promise<AbortOutcome> {
-  return new Promise((resolve) => {
-    let settled = false;
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const finish = (outcome: AbortOutcome): void => {
-      if (settled) return;
-      settled = true;
-      if (timer !== undefined) clearTimeout(timer);
-      resolve(outcome);
-    };
+  /** Start cancellation without letting a cleanup failure become unhandled while
+   * a holder of the per-session lock is still unwinding. A wedged provider/tool
+   * cannot keep disposal or parent shutdown waiting forever. */
+  private beginAbort(session: AgentSession): Promise<AbortOutcome> {
+    return new Promise((resolve) => {
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const finish = (outcome: AbortOutcome): void => {
+        if (settled) return;
+        settled = true;
+        if (timer !== undefined) clearTimeout(timer);
+        resolve(outcome);
+      };
+
+      timer = setTimeout(() => finish({ timedOut: true }), this.abortTimeoutMs);
+      try {
+        void session.abort().then(
+          () => finish({}),
+          (error: unknown) => finish({ error }),
+        );
+      } catch (error) {
+        finish({ error });
+      }
+    });
+  }
 
-    timer = setTimeout(() => finish({ timedOut: true }), poolAbortTimeoutMs);
+  /** Close and dispose one pooled session. A caller holds the per-session lock
+   *  while closing, so abort cannot race a reuse. All cleanup is attempted before
+   *  an error is surfaced; a removed session is never silently retained. */
+  private async closePooledAgentAfterAbort(
+    sessionId: string,
+    abort: Promise<AbortOutcome>,
+  ): Promise<boolean> {
+    const pooled = this.entries.get(sessionId);
+    if (!pooled) return false;
+
+    const failures: unknown[] = [];
+    let abortOutcome: AbortOutcome;
     try {
-      void session.abort().then(
-        () => finish({}),
-        (error: unknown) => finish({ error }),
+      abortOutcome = await abort;
+    } catch (error) {
+      // beginAbort currently normalizes rejection, but keep the teardown seam
+      // fail-closed if a future caller supplies a raw abort promise.
+      failures.push(error);
+      abortOutcome = {};
+    }
+    if (abortOutcome.error !== undefined) failures.push(abortOutcome.error);
+    if (abortOutcome.timedOut) {
+      failures.push(
+        new Error(
+          `Timed out after ${this.abortTimeoutMs}ms waiting for session '${sessionId}' to abort.`,
+        ),
       );
+    }
+    try {
+      pooled.session.dispose();
     } catch (error) {
-      finish({ error });
+      failures.push(error);
     }
-  });
-}
+    if (this.entries.get(sessionId) === pooled) this.entries.delete(sessionId);
 
-/** Close and dispose one pooled session. A caller holds the per-session lock
- *  while closing, so abort cannot race a reuse. All cleanup is attempted before
- *  an error is surfaced; a removed session is never silently retained. */
-async function closePooledAgentAfterAbort(
-  sessionId: string,
-  abort: Promise<AbortOutcome>,
-): Promise<boolean> {
-  const pooled = agentPool.get(sessionId);
-  if (!pooled) return false;
-
-  const failures: unknown[] = [];
-  let abortOutcome: AbortOutcome;
-  try {
-    abortOutcome = await abort;
-  } catch (error) {
-    // beginAbort currently normalizes rejection, but keep the teardown seam
-    // fail-closed if a future caller supplies a raw abort promise.
-    failures.push(error);
-    abortOutcome = {};
+    if (failures.length) {
+      throw new AggregateError(
+        failures,
+        `Failed to close pooled session '${sessionId}'.`,
+      );
+    }
+    return true;
   }
-  if (abortOutcome.error !== undefined) failures.push(abortOutcome.error);
-  if (abortOutcome.timedOut) {
-    failures.push(
-      new Error(
-        `Timed out after ${poolAbortTimeoutMs}ms waiting for session '${sessionId}' to abort.`,
-      ),
+
+  /** Internal close helper for callers that already own (or are obtaining) the
+   *  session lock. */
+  private closePooledAgentAfterLock(sessionId: string): Promise<boolean> {
+    const pooled = this.entries.get(sessionId);
+    if (!pooled) return Promise.resolve(false);
+    return this.closePooledAgentAfterAbort(
+      sessionId,
+      this.beginAbort(pooled.session),
     );
   }
-  try {
-    pooled.session.dispose();
-  } catch (error) {
-    failures.push(error);
-  }
-  if (agentPool.get(sessionId) === pooled) agentPool.delete(sessionId);
 
-  if (failures.length) {
-    throw new AggregateError(
-      failures,
-      `Failed to close pooled session '${sessionId}'.`,
-    );
+  /** @internal Close while the caller already owns the per-session lock. */
+  closePooledAgentWithoutLock(sessionId: string): Promise<boolean> {
+    return this.closePooledAgentAfterLock(sessionId);
   }
-  return true;
-}
 
-/** Internal close helper for callers that already own (or are obtaining) the
- *  session lock. */
-async function closePooledAgentAfterLock(sessionId: string): Promise<boolean> {
-  const pooled = agentPool.get(sessionId);
-  if (!pooled) return false;
-  return closePooledAgentAfterAbort(sessionId, beginAbort(pooled.session));
-}
+  /** Abort, dispose, and remove one pooled session. Returns false when the id
+   * is already absent; cleanup failures are aggregated after removal.
+   * During shutdown or after close, this waits for shutdown to finish and
+   * returns `false` instead of throwing.
+   */
+  async closePooledAgent(sessionId: string): Promise<boolean> {
+    if (this.state !== "open") {
+      const existing = this.closePromise;
+      if (existing) {
+        try {
+          await existing;
+        } catch {
+          // Keep public close idempotent during and after shutdown.
+        }
+      }
+      return false;
+    }
 
-/** @internal Close while the caller already owns the per-session lock. */
-export async function _closePooledAgentWithoutLock(
-  sessionId: string,
-): Promise<boolean> {
-  return closePooledAgentAfterLock(sessionId);
-}
+    let awaitShutdown: Promise<void> | undefined;
+    let closed = false;
 
-/** Abort, dispose, and remove one pooled session. Returns false when the id
- * is already absent; cleanup failures are aggregated after removal.
- * During shutdown or after close, this waits for shutdown to finish and
- * returns `false` instead of throwing.
- */
-export async function closePooledAgent(sessionId: string): Promise<boolean> {
-  if (poolState !== "open") {
-    const existing = closePromise;
-    if (existing) {
+    await this.withSessionLockInternal(sessionId, async () => {
+      // A shutdown can begin while this call waits for its lock. Avoid waiting
+      // for closePromise inside this lock: do that work after releasing it, so
+      // closeAll can acquire the lock and dispose the same session.
+      if (this.state !== "open") {
+        awaitShutdown = this.closePromise ?? undefined;
+        return;
+      }
+      closed = await this.closePooledAgentAfterLock(sessionId);
+    });
+
+    if (awaitShutdown) {
       try {
-        await existing;
+        await awaitShutdown;
       } catch {
         // Keep public close idempotent during and after shutdown.
       }
     }
-    return false;
-  }
 
-  let awaitShutdown: Promise<void> | undefined;
-  let closed = false;
+    return closed;
+  }
 
-  await withSessionLockInternal(sessionId, async () => {
-    // A shutdown can begin while this call waits for its lock. Avoid waiting
-    // for closePromise inside this lock: do that work after releasing it, so
-    // closeAll can acquire the lock and dispose the same session.
-    if (poolState !== "open") {
-      awaitShutdown = closePromise ?? undefined;
-      return;
+  /** Dispose every live pooled session when the parent Pi session ends. First
+   * request cancellation immediately, then wait for all in-flight session locks,
+   * then acquire each remaining session's lock before disposal. Attempts are
+   * executed for all sessions before reporting failures. Idempotent callers share
+   * the same completion promise, including failures.
+   */
+  async closeAllPooledAgents(): Promise<void> {
+    if (this.closePromise) {
+      return this.closePromise;
     }
-    closed = await closePooledAgentAfterLock(sessionId);
-  });
-
-  if (awaitShutdown) {
-    try {
-      await awaitShutdown;
-    } catch {
-      // Keep public close idempotent during and after shutdown.
+    if (this.state === "closed") {
+      const completed = Promise.resolve();
+      this.closePromise = completed;
+      return completed;
     }
+
+    this.state = "closing";
+
+    const completion = (async () => {
+      const aborts = new Map<string, Promise<AbortOutcome>>(
+        [...this.entries].map(([sessionId, pooled]) => [
+          sessionId,
+          this.beginAbort(pooled.session),
+        ]),
+      );
+
+      await this.waitForActiveSessionLocks();
+
+      const results = await Promise.allSettled(
+        [...aborts].map(([sessionId, abort]) =>
+          this.withSessionLockInternal(sessionId, () =>
+            this.closePooledAgentAfterAbort(sessionId, abort),
+          ),
+        ),
+      );
+      const failures = results
+        .filter(
+          (result): result is PromiseRejectedResult =>
+            result.status === "rejected",
+        )
+        .map((result) => result.reason);
+      if (failures.length) {
+        throw new AggregateError(
+          failures,
+          "Failed to close one or more pooled sessions.",
+        );
+      }
+    })();
+
+    this.closePromise = completion.finally(() => {
+      this.state = "closed";
+    });
+    return this.closePromise;
   }
 
-  return closed;
-}
+  /** List live pooled agents. Sessions remain available until explicit close or
+   * parent-session shutdown; idle/age are observability statistics, not expiry. */
+  listPooledAgents(): string[] {
+    const lines: string[] = [];
+    if (this.entries.size === 0) return ["_(no active sessions)_"];
+    const t = this.now();
+    for (const [id, pooled] of this.entries) {
+      const idle = fmtDuration(t - pooled.lastUsed);
+      const age = fmtDuration(t - pooled.createdAt);
+      lines.push(
+        `- **${id}** · ${pooled.promptCount} prompts · ${fmtTokens(pooled.totalTokens)} tokens · idle ${idle} · age ${age} · ${shortenPath(pooled.sessionFile)}`,
+      );
+    }
+    return lines;
+  }
 
-/** Dispose every live pooled session when the parent Pi session ends. First
- * request cancellation immediately, then wait for all in-flight session locks,
- * then acquire each remaining session's lock before disposal. Attempts are
- * executed for all sessions before reporting failures. Idempotent callers share
- * the same completion promise, including failures.
- */
-export async function closeAllPooledAgents(): Promise<void> {
-  if (closePromise) {
-    return closePromise;
+  /** @internal Clear all pool state for test isolation. Tests use fake sessions,
+   * so no live resource teardown is needed here. */
+  resetForTesting(): void {
+    this.entries.clear();
+    this.sessionLocks.clear();
+    this.state = "open";
+    this.closePromise = null;
+    this.abortTimeoutMs = SessionPool.DEFAULT_ABORT_TIMEOUT_MS;
+    this.quarantineWithoutDisposalOverride = undefined;
   }
-  if (poolState === "closed") {
-    const completed = Promise.resolve();
-    closePromise = completed;
-    return completed;
+
+  /** @internal Override the abort wait in tests without waiting ten seconds. */
+  setAbortTimeoutForTesting(timeoutMs: number | undefined): void {
+    this.abortTimeoutMs = timeoutMs ?? SessionPool.DEFAULT_ABORT_TIMEOUT_MS;
   }
+}
 
-  poolState = "closing";
+// ── Default module-level pool and compatibility wrappers ──────────────────
 
-  const completion = (async () => {
-    const aborts = new Map<string, Promise<AbortOutcome>>(
-      [...agentPool].map(([sessionId, pooled]) => [
-        sessionId,
-        beginAbort(pooled.session),
-      ]),
-    );
+/** Default pool instance used by the module-level wrappers and the default
+ *  {@link getDefaultDelegateRuntime}. Exported so callers can build a
+ *  {@link DelegateRuntime} that shares the same default pool. */
+export const defaultSessionPool = new SessionPool();
 
-    await waitForActiveSessionLocks();
+export function checkout(
+  sessionId: string,
+  candidate: ConfigCandidate,
+): CheckoutResult {
+  return defaultSessionPool.checkout(sessionId, candidate);
+}
 
-    const results = await Promise.allSettled(
-      [...aborts].map(([sessionId, abort]) =>
-        withSessionLockInternal(sessionId, () =>
-          closePooledAgentAfterAbort(sessionId, abort),
-        ),
-      ),
-    );
-    const failures = results
-      .filter(
-        (result): result is PromiseRejectedResult =>
-          result.status === "rejected",
-      )
-      .map((result) => result.reason);
-    if (failures.length) {
-      throw new AggregateError(
-        failures,
-        "Failed to close one or more pooled sessions.",
-      );
-    }
-  })();
+export function commit(sessionId: string, payload: CommitPayload): boolean {
+  return defaultSessionPool.commit(sessionId, payload);
+}
 
-  closePromise = completion.finally(() => {
-    poolState = "closed";
-  });
-  return closePromise;
+export function recordUse(sessionId: string, tokens: number): boolean {
+  return defaultSessionPool.recordUse(sessionId, tokens);
+}
+
+export function configFor(
+  sessionId: string,
+): Readonly<FrozenConfig> | undefined {
+  return defaultSessionPool.configFor(sessionId);
+}
+
+export function withSessionLock<T>(
+  sessionId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return defaultSessionPool.withSessionLock(sessionId, fn);
+}
+
+export async function closePooledAgent(sessionId: string): Promise<boolean> {
+  return defaultSessionPool.closePooledAgent(sessionId);
+}
+
+export async function closeAllPooledAgents(): Promise<void> {
+  return defaultSessionPool.closeAllPooledAgents();
 }
 
-/** List live pooled agents. Sessions remain available until explicit close or
- * parent-session shutdown; idle/age are observability statistics, not expiry. */
 export function listPooledAgents(): string[] {
-  const lines: string[] = [];
-  if (agentPool.size === 0) return ["_(no active sessions)_"];
-  const t = now();
-  for (const [id, pooled] of agentPool) {
-    const idle = fmtDuration(t - pooled.lastUsed);
-    const age = fmtDuration(t - pooled.createdAt);
-    lines.push(
-      `- **${id}** · ${pooled.promptCount} prompts · ${fmtTokens(pooled.totalTokens)} tokens · idle ${idle} · age ${age} · ${shortenPath(pooled.sessionFile)}`,
-    );
-  }
-  return lines;
+  return defaultSessionPool.listPooledAgents();
+}
+
+export function _quarantinePooledAgentWithoutDisposal(
+  sessionId: string,
+  expectedSession: AgentSession,
+): boolean {
+  return defaultSessionPool.quarantinePooledAgentWithoutDisposal(
+    sessionId,
+    expectedSession,
+  );
 }
 
-// ── Test seam (internal — imported directly by tests, not re-exported) ────
+export function _closePooledAgentWithoutLock(
+  sessionId: string,
+): Promise<boolean> {
+  return defaultSessionPool.closePooledAgentWithoutLock(sessionId);
+}
 
 /** @internal Override the abort wait in tests without waiting ten seconds. */
 export function _setPoolAbortTimeoutForTesting(
   timeoutMs: number | undefined,
 ): void {
-  poolAbortTimeoutMs = timeoutMs ?? DEFAULT_POOL_ABORT_TIMEOUT_MS;
+  defaultSessionPool.setAbortTimeoutForTesting(timeoutMs);
 }
 
-/** @internal Clear all pool state for test isolation. Tests use fake sessions,
- * so no live resource teardown is needed here. */
+/** @internal Clear all default pool state for test isolation. */
 export function _resetPoolForTesting(): void {
-  agentPool.clear();
-  sessionLocks.clear();
-  poolState = "open";
-  closePromise = null;
-  poolAbortTimeoutMs = DEFAULT_POOL_ABORT_TIMEOUT_MS;
+  defaultSessionPool.resetForTesting();
 }