deepline 0.1.181 → 0.1.183

package/dist/bundling-sources/apps/play-runner-workers/src/runtime/tool-dispatch.ts

@@ -0,0 +1,2381 @@
+import {
+  compileRequestsWithStrategy,
+  executeChunkedRequests,
+  type ChunkExecutionResult,
+} from '../../../../shared_libs/play-runtime/batch-runtime';
+import type { AnyBatchOperationStrategy } from '../../../../shared_libs/play-runtime/batching-types';
+import {
+  buildDurableToolCallAuthScopeDigest,
+  buildDurableToolCallCacheKey,
+  buildDurableToolAggregateProviderIdempotencyKey,
+  buildDurableToolAggregateReceiptKey,
+  buildDurableToolProviderIdempotencyKey,
+  buildDurableToolReceiptPrefix,
+} from '../../../../shared_libs/play-runtime/durable-call-cache';
+import {
+  RuntimeReceiptWaitTimeoutError,
+  resolveRuntimeToolReceiptWaitMaxAttempts,
+  waitForCompletedRuntimeReceipt,
+} from '../../../../shared_libs/play-runtime/durable-receipt-execution';
+import type { PlayExecutionGovernor } from '../../../../shared_libs/play-runtime/governor/governor';
+import { getToolHttpErrorReceiptFailureKind } from '../../../../shared_libs/play-runtime/tool-http-errors';
+import { ToolExecuteAuthScopeChangedError } from '../../../../shared_libs/play-runtime/tool-execute-retry-policy';
+import { getPlayRuntimeBatchStrategy } from '../../../../shared_libs/play-runtime/play-runtime-batching-registry';
+import {
+  RuntimePersistenceCircuitOpenError,
+  shouldShortenCompleteReceiptLadder,
+  tripRuntimePersistenceLatch,
+  type RuntimePersistenceLatch,
+} from '../../../../shared_libs/play-runtime/persistence-latch';
+import type { ReceiptSalvageBuffer } from '../../../../shared_libs/play-runtime/receipt-salvage';
+import type { ResolvedPacingPolicy } from '../../../../shared_libs/play-runtime/pacing';
+import type { RuntimeStepReceipt } from '../../../../shared_libs/play-runtime/ctx-types';
+import {
+  isPlayExecutionSuspendedError,
+  isPlayRowExecutionSuspendedError,
+} from '../../../../shared_libs/play-runtime/suspension';
+import {
+  QUERY_RESULT_DATASET_PAGE_SIZE,
+  isQueryResultDatasetReadRequest,
+  type QueryResultDatasetRequest,
+} from '../../../../shared_libs/play-runtime/query-result-dataset';
+import {
+  createToolExecuteResult,
+  isToolExecuteResult,
+  type ToolExecuteResult,
+  type ToolResultMetadataInput,
+} from '../../../../shared_libs/play-runtime/tool-result';
+import { toolExecutionMetadataForOutcome } from '../../../../shared_libs/play-runtime/tool-execution-outcome';
+import {
+  buildScopedWorkReceiptKey,
+  type WorkReceiptFailureKind,
+} from '../../../../shared_libs/play-runtime/work-receipts';
+import {
+  canReclaimFailedWorkerToolReceipt,
+  canReclaimTimedOutWorkerToolReceipt,
+  markWorkerToolReceiptResultCached,
+  markWorkerToolReceiptResultExecution,
+  planWorkerToolReceiptGroups,
+  resolveWorkerToolReceiptGroupWaitMaxAttempts,
+  resolveWorkerToolRuntimeTimeoutMs,
+} from './tool-receipts';
+import type {
+  WorkerRuntimeReceipt,
+  WorkerRuntimeReceiptClaim,
+  WorkerRuntimeReceiptStore,
+} from './receipts';
+import {
+  executeWithWorkerReceiptHeartbeats,
+  RuntimeLeaseLostError,
+} from './receipts';
+import { WORKER_PLATFORM_SUBREQUESTS_PER_UNBATCHED_TOOL_CALL } from './worker-platform-budget';
+import type { WorkerWorkBudgetMeter } from './work-budget';
+
+export type WorkerPacingResolver = (
+  toolId: string,
+) => Promise<
+  (ResolvedPacingPolicy & { retrySafeTransientHttp: boolean }) | null
+>;
+
+export type WorkerToolActionCacheVersionResolver = (
+  toolId: string,
+) => Promise<string>;
+
+export type WorkerToolAuthScopeDigestResolver = ((
+  toolId: string,
+) => Promise<string>) & {
+  invalidate?: (toolId?: string | null) => void;
+};
+
+export type WorkerToolDispatchCallbacks = {
+  onToolCalled?: (toolId: string, at?: number) => void;
+  onToolFailed?: (toolId: string, at?: number) => void;
+};
+
+export type WorkerToolDirectOptions = {
+  customerDbDataset?: QueryResultDatasetRequest;
+  attachCustomerDbDataset?: boolean;
+};
+
+export type WorkerToolDispatchRunRequest = {
+  runId: string;
+  runAttempt?: number | null;
+  orgId: string;
+  playName: string;
+};
+
+export type WorkflowStepLike = object;
+
+export type WorkerToolDispatchExecuteTool = (input: {
+  id: string;
+  toolId: string;
+  input: Record<string, unknown>;
+  workflowStep?: WorkflowStepLike;
+  callbacks?: WorkerToolDispatchCallbacks;
+  onProviderBackpressure?: (retryAfterMs: number) => void;
+  onRetryAttempt?: () => void;
+  transientHttpRetrySafe?: boolean;
+  durableCallReceiptKey?: string | null;
+  executionAuthScopeDigest?: string | null;
+  providerIdempotencyKey?: string | null;
+  runtimeTimeoutMs?: number;
+  directOptions?: WorkerToolDirectOptions;
+}) => Promise<ToolExecuteResult>;
+
+export type WorkerToolDispatchPerfRecorder = (input: {
+  phase: string;
+  ms?: number;
+  extra?: Record<string, unknown>;
+}) => void;
+
+export type ToolDispatchStore = {
+  receiptStore?: WorkerRuntimeReceiptStore;
+  serializeDurableValue: <T>(value: T) => T;
+  deserializeDurableValue: <T>(value: T) => T;
+  allowLocalRetryReceipts?: boolean;
+  runtimeReceiptHeartbeatIntervalMs?: number;
+  runtimeReceiptLeaseTtlMs?: number;
+};
+
+export type ToolDispatchGovernor = {
+  governor: Pick<
+    PlayExecutionGovernor,
+    | 'policy'
+    | 'acquireToolSlot'
+    | 'suggestedParallelism'
+    | 'chargeBudget'
+    | 'reportProviderBackpressure'
+  >;
+  resolvePacing: WorkerPacingResolver;
+  budgetMeter?: WorkerWorkBudgetMeter;
+};
+
+export type ToolExecutor = {
+  resolveToolActionCacheVersion: WorkerToolActionCacheVersionResolver;
+  resolveToolAuthScopeDigest: WorkerToolAuthScopeDigestResolver;
+  // REQUIRED: the AUTH_SCOPE_CHANGED re-claim depends on evicting the cached
+  // digest before re-resolving. When this was optional, the root (top-level)
+  // scheduler was constructed without it: the requeue silently reused the
+  // stale digest, re-claimed the SAME receipt key, collided with its own
+  // still-running receipt, and the run stalled until the whole workflow
+  // invocation was retried minutes later. A missing wiring must be a type
+  // error, not a 5-minute invisible stall.
+  invalidateToolAuthScopeDigest: (toolId: string) => void;
+  executeTool: WorkerToolDispatchExecuteTool;
+  callbacks?: WorkerToolDispatchCallbacks;
+  // Observability hook for the bounded AUTH_SCOPE_CHANGED re-claim: called
+  // once per requeued group so the runner can emit a durable run-log line
+  // (marker: auth_scope_changed_reclaim). The credential-swap transition must
+  // be visible in run logs, not a silent continuation.
+  onAuthScopeReclaim?: (input: {
+    toolId: string;
+    requestIds: string[];
+    previousReceiptKeys: Array<string | null>;
+    nextReceiptKeys: string[];
+  }) => void;
+};
+
+export type WorkerToolBatchSchedulerOptions = ToolDispatchStore &
+  ToolDispatchGovernor &
+  ToolExecutor & {
+    req: WorkerToolDispatchRunRequest;
+    nowMs: () => number;
+    batchGraceMs?: number;
+    recordPerfTrace?: WorkerToolDispatchPerfRecorder;
+    abortSignal?: AbortSignal;
+    onRequestsSettled?: (count: number) => void;
+    runtimeDeadlineMs?: number;
+    persistenceLatch?: RuntimePersistenceLatch;
+    receiptSalvage?: ReceiptSalvageBuffer;
+  };
+
+type WorkerToolBatchRequest = {
+  id: string;
+  cacheKey: string;
+  receiptKey: string | null;
+  executionAuthScopeDigest: string;
+  force: boolean;
+  runForceRefresh: boolean;
+  runForceFailedRefresh: boolean;
+  staleAfterSeconds?: number | null;
+  receiptWaitMaxAttempts: number;
+  authScopeRetryUsed?: boolean;
+  runtimeTimeoutMs?: number;
+  toolId: string;
+  input: Record<string, unknown>;
+  workflowStep?: WorkflowStepLike;
+  directOptions?: WorkerToolDirectOptions;
+  resolve: (value: unknown) => void;
+  reject: (error: unknown) => void;
+};
+
+type ClaimedWorkerToolBatchRequest = {
+  request: WorkerToolBatchRequest;
+  receiptKey: string | null;
+  receiptLeaseId: string | null;
+  providerForce?: boolean;
+  followers: WorkerToolBatchRequest[];
+};
+
+type PreparedWorkerToolBatchRequests = {
+  claimedRequests: ClaimedWorkerToolBatchRequest[];
+  deferredClaimedRequests: Promise<ClaimedWorkerToolBatchRequest[]>[];
+};
+
+type WorkerToolCompletionResult =
+  | { ok: true; value: unknown }
+  | { ok: false; error: unknown };
+
+const WORKER_TOOL_BATCH_GRACE_MS = 250;
+const COMPLETE_RECEIPT_RETRY_BACKOFFS_MS = [1_000, 3_000, 9_000] as const;
+const COMPLETE_RECEIPT_RETRY_MIN_HEADROOM_MS = 10_000;
+export const WORKER_TOOL_COMPLETE_RECEIPTS_MAX_BATCH_BYTES = 8 * 1024 * 1024;
+export const WORKER_TOOL_COMPLETE_RECEIPTS_MAX_BATCH_MEMBERS = 500;
+export const WORKER_TOOL_RECEIPT_RECOVERY_MAX_CONCURRENT_READS = 25;
+
+type DurableToolCompletionEntry = {
+  index: number;
+  claimed: ClaimedWorkerToolBatchRequest;
+  ownerResult: unknown;
+  receipt: {
+    runId: string;
+    runAttempt: number;
+    key: string;
+    leaseId: string | null;
+    output: unknown;
+  };
+  serializedBytes: number;
+};
+
+type DurableToolCompletionBatch = {
+  entries: DurableToolCompletionEntry[];
+  bytes: number;
+};
+
+const jsonByteLength = (value: unknown): number =>
+  new TextEncoder().encode(JSON.stringify(value)).byteLength;
+
+async function mapWithConcurrency<T>(
+  values: T[],
+  concurrency: number,
+  run: (value: T, index: number) => Promise<void>,
+): Promise<void> {
+  const workerCount = Math.max(
+    1,
+    Math.min(Math.floor(concurrency), values.length),
+  );
+  let nextIndex = 0;
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      while (true) {
+        const index = nextIndex;
+        nextIndex += 1;
+        if (index >= values.length) return;
+        await run(values[index]!, index);
+      }
+    }),
+  );
+}
+
+async function sleepWorkerMs(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function workReceiptFailureKindForError(
+  error: unknown,
+): WorkReceiptFailureKind {
+  if (
+    isPlayExecutionSuspendedError(error) ||
+    isPlayRowExecutionSuspendedError(error)
+  ) {
+    return 'repairable';
+  }
+  return getToolHttpErrorReceiptFailureKind(error) ?? 'terminal';
+}
+
+export class RuntimeReceiptPersistenceError extends Error {
+  readonly receiptKeys: string[];
+  readonly errors: unknown[];
+
+  constructor(input: {
+    message: string;
+    receiptKeys: string[];
+    errors?: unknown[];
+    cause?: unknown;
+  }) {
+    super(input.message, { cause: input.cause });
+    this.name = 'RuntimeReceiptPersistenceError';
+    this.receiptKeys = input.receiptKeys;
+    this.errors =
+      input.errors ?? (input.cause === undefined ? [] : [input.cause]);
+  }
+}
+
+function receiptPersistenceError(input: {
+  operation: 'complete' | 'fail';
+  receiptKeys: string[];
+  cause: unknown;
+}): RuntimeReceiptPersistenceError {
+  const keys = input.receiptKeys.filter((key) => key.trim().length > 0);
+  const keySummary =
+    keys.length === 0
+      ? 'unknown receipt'
+      : keys.length === 1
+        ? keys[0]!
+        : `${keys.length} receipts`;
+  return new RuntimeReceiptPersistenceError({
+    message: `Runtime receipt ${input.operation} persistence failed for ${keySummary}.`,
+    receiptKeys: keys,
+    cause: input.cause,
+  });
+}
+
+function buildBatchDurableCallReceiptKey(input: {
+  req: WorkerToolDispatchRunRequest;
+  batchOperation: string;
+  receiptKeys: string[];
+}): string {
+  return buildDurableToolAggregateReceiptKey({
+    receiptKeys: input.receiptKeys,
+    prefix: 'batch',
+    aggregateReceiptPrefix: buildDurableToolReceiptPrefix({
+      orgId: input.req.orgId,
+      toolId: input.batchOperation,
+    }),
+  });
+}
+
+function buildBatchProviderIdempotencyKey(input: {
+  aggregateReceiptKey: string;
+  receiptKeys: string[];
+  providerIdempotencyKeys: string[];
+}): string {
+  return buildDurableToolAggregateProviderIdempotencyKey({
+    aggregateReceiptKey: input.aggregateReceiptKey,
+    receiptKeys: input.receiptKeys,
+    providerIdempotencyKeys: input.providerIdempotencyKeys,
+  });
+}
+
+function durableCallReceiptKeyForClaimed(input: {
+  req: WorkerToolDispatchRunRequest;
+  claimed: ClaimedWorkerToolBatchRequest;
+}): string {
+  return input.claimed.receiptKey ?? input.claimed.request.cacheKey;
+}
+
+function providerIdempotencyKeyForClaimed(input: {
+  req: WorkerToolDispatchRunRequest;
+  claimed: ClaimedWorkerToolBatchRequest;
+}): string {
+  const fallbackAttemptId =
+    (input.claimed.providerForce === true || input.claimed.request.force) &&
+    !input.claimed.receiptLeaseId
+      ? input.claimed.request.id
+      : null;
+  return buildDurableToolProviderIdempotencyKey({
+    receiptKey: durableCallReceiptKeyForClaimed(input),
+    force: input.claimed.providerForce === true || input.claimed.request.force,
+    receiptLeaseId: input.claimed.receiptLeaseId,
+    fallbackAttemptId,
+  });
+}
+
+export function wrapWorkerToolResult(
+  toolId: string,
+  result: unknown,
+  metadata: ToolResultMetadataInput | null,
+  status = result == null ? 'no_result' : 'completed',
+): ToolExecuteResult {
+  return createToolExecuteResult({
+    status,
+    result,
+    metadata: metadata ?? { toolId },
+    execution: toolExecutionMetadataForOutcome({ kind: 'live' }),
+  });
+}
+
+function toolMetadataFallback(toolId: string): ToolResultMetadataInput {
+  if (toolId === 'test_rate_limit') {
+    // Batched members resolve metadata through this fallback because the lean
+    // worker does not bundle the catalog. It MUST mirror the same
+    // `email_status: emailStatus({...})` contract registered in
+    // src/lib/integrations/test/index.ts so batched results normalize to the
+    // same rich email_status OBJECT (status from statusMap, catch_all as a
+    // signal) that the single-execute real-metadata path produces.
+    return {
+      toolId,
+      extractors: {
+        email_status: {
+          paths: ['email_status'],
+          emailStatus: {
+            provider: 'test',
+            rawStatus: ['email_status'],
+            catchAll: ['mx_security_gateway'],
+            statusMap: {
+              valid: { status: 'valid', verdict: 'send', verified: true },
+              invalid: { status: 'invalid', verdict: 'drop', verified: false },
+              catch_all: {
+                status: 'catch_all',
+                verdict: 'verify_next',
+                verified: false,
+              },
+              unknown: { status: 'unknown', verdict: 'hold', verified: false },
+            },
+          },
+        },
+      },
+      targetGetters: {
+        email: ['email', 'value'],
+        email_status: ['email_status'],
+      },
+    };
+  }
+  return { toolId };
+}
+
+function workerDurableToolCallCacheKey(input: {
+  req: WorkerToolDispatchRunRequest;
+  toolId: string;
+  requestInput: Record<string, unknown>;
+  providerActionVersion: string;
+  executionAuthScopeDigest: string;
+  staleAfterSeconds?: number | null;
+}): string {
+  return buildDurableToolCallCacheKey({
+    orgId: input.req.orgId,
+    playLocalScope: input.req.playName,
+    toolId: input.toolId,
+    requestInput: input.requestInput,
+    authScopeDigest: buildDurableToolCallAuthScopeDigest({
+      orgId: input.req.orgId,
+      toolId: input.toolId,
+      executionAuthScopeDigest: input.executionAuthScopeDigest,
+    }),
+    providerActionVersion: input.providerActionVersion,
+    staleAfterSeconds: input.staleAfterSeconds,
+  });
+}
+
+function workerRuntimeReceiptKey(input: {
+  req: WorkerToolDispatchRunRequest;
+  key: string;
+}): string {
+  const orgId = input.req.orgId?.trim() || 'org';
+  if (input.key.startsWith(`ctx:${orgId}:`)) {
+    return input.key;
+  }
+  return buildScopedWorkReceiptKey({
+    orgId: input.req.orgId,
+    playName: input.req.playName,
+    key: input.key,
+  });
+}
+
+export class WorkerToolBatchScheduler {
+  private queue: WorkerToolBatchRequest[] = [];
+  private scheduled = false;
+  private drainTimer: ReturnType<typeof setTimeout> | null = null;
+  private immediateDrainQueued = false;
+
+  constructor(private readonly options: WorkerToolBatchSchedulerOptions) {}
+
+  private runtimeDeadlineRemainingMs(): number {
+    if (typeof this.options.runtimeDeadlineMs !== 'number') {
+      return Number.POSITIVE_INFINITY;
+    }
+    return Math.max(0, this.options.runtimeDeadlineMs - this.options.nowMs());
+  }
+
+  private async completeReceiptWithRetryLadder<T>(
+    run: () => Promise<T>,
+    onGiveUp?: (attempts: number) => void,
+  ): Promise<T> {
+    if (!this.options.persistenceLatch && !this.options.receiptSalvage) {
+      return await run();
+    }
+    const latch = this.options.persistenceLatch;
+    let attempt = 0;
+    let committedToFullLadder = false;
+    const giveUp = (error: unknown): never => {
+      if (latch) {
+        latch.latchRetryBudgetExhausted = true;
+        tripRuntimePersistenceLatch(latch, error);
+      }
+      onGiveUp?.(attempt);
+      throw error;
+    };
+    while (true) {
+      try {
+        return await run();
+      } catch (error) {
+        attempt += 1;
+        if (
+          this.options.abortSignal?.aborted ||
+          attempt > COMPLETE_RECEIPT_RETRY_BACKOFFS_MS.length ||
+          (latch &&
+            shouldShortenCompleteReceiptLadder(latch, committedToFullLadder))
+        ) {
+          return giveUp(error);
+        }
+        const backoffMs = COMPLETE_RECEIPT_RETRY_BACKOFFS_MS[attempt - 1]!;
+        if (
+          this.runtimeDeadlineRemainingMs() <=
+          backoffMs + COMPLETE_RECEIPT_RETRY_MIN_HEADROOM_MS
+        ) {
+          return giveUp(error);
+        }
+        committedToFullLadder = true;
+        await sleepWorkerMs(backoffMs);
+      }
+    }
+  }
+
+  private recordReceiptSalvage(input: {
+    claimed: ClaimedWorkerToolBatchRequest;
+    output: unknown;
+    attempts: number;
+  }): void {
+    if (!this.options.receiptSalvage || !input.claimed.receiptKey) return;
+    this.options.receiptSalvage.push({
+      receiptKey: input.claimed.receiptKey,
+      toolId: input.claimed.request.toolId,
+      cacheKey: input.claimed.request.cacheKey,
+      output: input.output,
+      completeAttempts: input.attempts,
+      firstErrorAt: this.options.nowMs(),
+    });
+  }
+
+  private runtimePersistenceCircuitOpenError(
+    skippedCalls: number,
+  ): Error | null {
+    const latch = this.options.persistenceLatch;
+    if (!latch?.tripped) return null;
+    latch.preventedCallCount += Math.max(1, skippedCalls);
+    return new RuntimePersistenceCircuitOpenError(latch);
+  }
+
+  /**
+   * Report a provider 429 / Retry-After back into the Governor's shared pacer
+   * so future acquires for this (org, provider) bucket back off across all
+   * isolates. Provider comes from the same pacing resolver the Governor uses
+   * (the worker has no local catalog), so callers pass only the toolId.
+   */
+  private reportBackpressure(toolId: string, retryAfterMs: number): void {
+    if (retryAfterMs <= 0) return;
+    void (async () => {
+      const pacing = await this.options.resolvePacing(toolId).catch(() => null);
+      if (pacing?.provider) {
+        this.options.governor.reportProviderBackpressure({
+          provider: pacing.provider,
+          retryAfterMs,
+        });
+      }
+    })();
+  }
+
+  async execute(
+    id: string,
+    toolId: string,
+    input: Record<string, unknown>,
+    workflowStep?: WorkflowStepLike,
+    options?: {
+      force?: boolean;
+      runForceRefresh?: boolean;
+      runForceFailedRefresh?: boolean;
+      staleAfterSeconds?: number | null;
+      timeoutMs?: number;
+      receiptWaitMs?: number;
+    },
+  ): Promise<unknown> {
+    this.options.budgetMeter?.count('tool');
+    const [providerActionVersion, executionAuthScopeDigest] = await Promise.all(
+      [
+        this.options.resolveToolActionCacheVersion(toolId),
+        this.options.resolveToolAuthScopeDigest(toolId),
+      ],
+    );
+    return await new Promise((resolve, reject) => {
+      const queuedAt = this.options.nowMs();
+      const receiptKey = workerDurableToolCallCacheKey({
+        req: this.options.req,
+        toolId,
+        requestInput: input,
+        providerActionVersion,
+        executionAuthScopeDigest,
+        staleAfterSeconds: options?.staleAfterSeconds,
+      });
+      const queryResultDatasetRead = isQueryResultDatasetReadRequest(
+        toolId,
+        input,
+      );
+      const receiptEligible = !queryResultDatasetRead;
+      this.queue.push({
+        id,
+        cacheKey: receiptEligible ? receiptKey : '',
+        receiptKey: receiptEligible ? receiptKey : null,
+        executionAuthScopeDigest,
+        force: options?.force === true,
+        runForceRefresh: options?.runForceRefresh === true,
+        runForceFailedRefresh: options?.runForceFailedRefresh === true,
+        staleAfterSeconds: options?.staleAfterSeconds ?? null,
+        receiptWaitMaxAttempts: resolveRuntimeToolReceiptWaitMaxAttempts(
+          typeof options?.receiptWaitMs === 'number'
+            ? { max_wait_ms: options.receiptWaitMs }
+            : input,
+        ),
+        runtimeTimeoutMs: options?.timeoutMs,
+        toolId,
+        input,
+        workflowStep,
+        ...(queryResultDatasetRead
+          ? {
+              directOptions: {
+                customerDbDataset: {
+                  offset: 0,
+                  pageSize: QUERY_RESULT_DATASET_PAGE_SIZE,
+                },
+              },
+            }
+          : {}),
+        resolve: (value) => {
+          this.options.recordPerfTrace?.({
+            phase: 'runner.tool.request',
+            ms: this.options.nowMs() - queuedAt,
+            extra: { id, toolId },
+          });
+          resolve(value);
+        },
+        reject,
+      });
+      this.scheduleDrain();
+    });
+  }
+
+  private scheduleDrain(): void {
+    if (this.shouldDrainQueuedToolsImmediately()) {
+      this.scheduleImmediateDrain();
+      return;
+    }
+    if (this.scheduled) return;
+    this.scheduled = true;
+    this.drainTimer = setTimeout(() => {
+      this.drainTimer = null;
+      this.scheduleImmediateDrain();
+    }, this.options.batchGraceMs ?? WORKER_TOOL_BATCH_GRACE_MS);
+  }
+
+  private scheduleImmediateDrain(): void {
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = null;
+    }
+    if (this.immediateDrainQueued) return;
+    this.scheduled = true;
+    this.immediateDrainQueued = true;
+    queueMicrotask(() => {
+      this.immediateDrainQueued = false;
+      void this.drain().catch((error) => {
+        const queued = this.queue;
+        this.queue = [];
+        this.scheduled = false;
+        if (queued.length > 0) {
+          this.rejectRawRequests(queued, error);
+        }
+      });
+    });
+  }
+
+  private shouldDrainQueuedToolsImmediately(): boolean {
+    if (!this.hasBatchableQueuedTool()) return true;
+    const byTool = new Map<string, number>();
+    for (const request of this.queue) {
+      if (request.toolId === 'test_wait_for_event') continue;
+      const strategy = getPlayRuntimeBatchStrategy(request.toolId);
+      if (!strategy) continue;
+      const nextCount = (byTool.get(request.toolId) ?? 0) + 1;
+      if (nextCount >= strategy.maxBatchSize) {
+        return true;
+      }
+      byTool.set(request.toolId, nextCount);
+    }
+    return false;
+  }
+
+  private hasBatchableQueuedTool(): boolean {
+    return this.queue.some(
+      (request) =>
+        request.toolId !== 'test_wait_for_event' &&
+        getPlayRuntimeBatchStrategy(request.toolId) !== null,
+    );
+  }
+
+  private async drain(): Promise<void> {
+    const requests = this.queue;
+    this.queue = [];
+    this.scheduled = false;
+    const drainStartedAt = this.options.nowMs();
+    await Promise.all(
+      [...groupWorkerToolRequestsByTool(requests).entries()].map(
+        async ([toolId, groupedRequests]) => {
+          try {
+            await this.executeToolGroup(toolId, groupedRequests);
+          } catch (error) {
+            this.rejectRawRequests(groupedRequests, error);
+          }
+        },
+      ),
+    );
+    this.options.recordPerfTrace?.({
+      phase: 'runner.tool.drain',
+      ms: this.options.nowMs() - drainStartedAt,
+      extra: { requests: requests.length },
+    });
+    if (this.queue.length > 0) {
+      this.scheduleDrain();
+    }
+  }
+
+  private async waitForDurableToolReceipt(input: {
+    receiptKey: string;
+    maxAttempts: number;
+  }): Promise<unknown> {
+    if (!this.options.receiptStore) {
+      throw new Error('No receipt store.');
+    }
+    if (!this.options.receiptStore.getReceipt) {
+      throw new Error('No receipt lookup.');
+    }
+    this.options.budgetMeter?.count('receipt');
+    const receipt = await waitForCompletedRuntimeReceipt({
+      receiptKey: input.receiptKey,
+      maxAttempts: input.maxAttempts,
+      abortSignal: this.options.abortSignal,
+      store: {
+        getMany: async (receiptKeys) => {
+          const receipts = new Map<string, RuntimeStepReceipt>();
+          await Promise.all(
+            receiptKeys.map(async (key) => {
+              const receipt = await this.options.receiptStore!.getReceipt!({
+                playName: this.options.req.playName,
+                key,
+              });
+              if (!receipt) return;
+              receipts.set(key, {
+                key: receipt.key,
+                status: receipt.status,
+                output: receipt.output,
+                error: receipt.error ?? undefined,
+                runId: receipt.runId ?? null,
+              });
+            }),
+          );
+          return receipts;
+        },
+      },
+    });
+    return markWorkerToolReceiptResultCached(
+      this.options.deserializeDurableValue(receipt.output),
+      input.receiptKey,
+      input.receiptKey,
+    );
+  }
+
+  private settleRequests(
+    claimed: ClaimedWorkerToolBatchRequest,
+    result: unknown,
+  ): void {
+    claimed.request.resolve(result);
+    for (const follower of claimed.followers) {
+      follower.resolve(
+        claimed.receiptKey
+          ? markWorkerToolReceiptResultExecution(result, {
+              kind: 'in_flight',
+              receiptKey: claimed.receiptKey,
+              attachedToReceiptKey: claimed.receiptKey,
+            })
+          : result,
+      );
+    }
+    this.options.onRequestsSettled?.(1 + claimed.followers.length);
+  }
+
+  private rejectRequests(
+    claimed: ClaimedWorkerToolBatchRequest,
+    error: unknown,
+  ): void {
+    claimed.request.reject(error);
+    for (const follower of claimed.followers) {
+      follower.reject(error);
+    }
+    this.options.onRequestsSettled?.(1 + claimed.followers.length);
+  }
+
+  private rejectRawRequests(
+    requests: WorkerToolBatchRequest[],
+    error: unknown,
+  ): void {
+    for (const request of requests) {
+      request.reject(error);
+    }
+    this.options.onRequestsSettled?.(requests.length);
+  }
+
+  private async requeueAfterAuthScopeChanged(
+    requests: WorkerToolBatchRequest[],
+    error: unknown,
+  ): Promise<boolean> {
+    if (!(error instanceof ToolExecuteAuthScopeChangedError)) {
+      return false;
+    }
+    const [first] = requests;
+    if (!first) return false;
+    if (requests.some((request) => request.authScopeRetryUsed === true)) {
+      return false;
+    }
+    this.options.invalidateToolAuthScopeDigest(first.toolId);
+    const [providerActionVersion, executionAuthScopeDigest] = await Promise.all(
+      [
+        this.options.resolveToolActionCacheVersion(first.toolId),
+        this.options.resolveToolAuthScopeDigest(first.toolId),
+      ],
+    );
+    const requeued = requests.map((request) => ({
+      request,
+      receiptKey: workerDurableToolCallCacheKey({
+        req: this.options.req,
+        toolId: request.toolId,
+        requestInput: request.input,
+        providerActionVersion,
+        executionAuthScopeDigest,
+        staleAfterSeconds: request.staleAfterSeconds,
+      }),
+    }));
+    // If the re-resolved scope produced the exact same receipt keys, the
+    // credential identity did NOT actually change from this isolate's point of
+    // view (stale cache, no-op invalidation, or a racing revert). Requeuing
+    // would claim the same key this group just left `running` and stall on its
+    // own abandoned receipt until the lease TTL. Refuse instead: the caller
+    // rejects the request with the typed 409 error — loud and immediate.
+    if (
+      requeued.every(
+        (entry) => entry.receiptKey === (entry.request.receiptKey ?? null),
+      )
+    ) {
+      return false;
+    }
+    for (const { request, receiptKey } of requeued) {
+      this.queue.push({
+        ...request,
+        cacheKey: receiptKey,
+        receiptKey,
+        executionAuthScopeDigest,
+        authScopeRetryUsed: true,
+      });
+    }
+    this.options.onAuthScopeReclaim?.({
+      toolId: first.toolId,
+      requestIds: requests.map((request) => request.id),
+      previousReceiptKeys: requests.map(
+        (request) => request.receiptKey ?? null,
+      ),
+      nextReceiptKeys: requeued.map((entry) => entry.receiptKey),
+    });
+    this.scheduleDrain();
+    return true;
+  }
+
+  private async reclaimTimedOutDurableToolReceiptGroup(input: {
+    group: WorkerToolBatchRequest[];
+    receiptKey: string;
+    runningReceipt: WorkerRuntimeReceipt;
+    waitError: unknown;
+  }): Promise<ClaimedWorkerToolBatchRequest[]> {
+    const [request, ...followers] = input.group;
+    if (!request || !this.options.receiptStore) {
+      this.rejectRawRequests(input.group, input.waitError);
+      return [];
+    }
+    if (
+      !canReclaimTimedOutWorkerToolReceipt({
+        ownerRunId: input.runningReceipt.runId,
+        currentRunId: this.options.req.runId,
+      })
+    ) {
+      this.rejectRawRequests(input.group, input.waitError);
+      return [];
+    }
+    let claim: WorkerRuntimeReceiptClaim;
+    try {
+      this.options.budgetMeter?.count('receipt');
+      claim = await this.options.receiptStore.claimReceipt({
+        playName: this.options.req.playName,
+        runId: this.options.req.runId,
+        runAttempt: this.options.req.runAttempt ?? 0,
+        key: input.receiptKey,
+        leaseAware: true,
+        leaseTtlMs: this.options.runtimeReceiptLeaseTtlMs,
+        reclaimRunning: true,
+      });
+    } catch (error) {
+      this.rejectRawRequests(input.group, error);
+      return [];
+    }
+    if (claim.disposition === 'claimed') {
+      return [
+        {
+          request,
+          receiptKey: input.receiptKey,
+          receiptLeaseId: claim.receipt.leaseId ?? null,
+          providerForce: true,
+          followers,
+        },
+      ];
+    }
+    if (claim.disposition === 'reused') {
+      const result = markWorkerToolReceiptResultCached(
+        this.options.deserializeDurableValue(claim.receipt.output),
+        request.cacheKey,
+        input.receiptKey,
+      );
+      for (const pending of input.group) {
+        pending.resolve(result);
+      }
+      this.options.onRequestsSettled?.(input.group.length);
+      return [];
+    }
+    if (claim.disposition === 'failed') {
+      this.rejectRawRequests(
+        input.group,
+        new Error(
+          `Durable tool call ${input.receiptKey} failed: ${claim.receipt.error ?? 'unknown error'}`,
+        ),
+      );
+      return [];
+    }
+    this.rejectRawRequests(input.group, input.waitError);
+    return [];
+  }
+
+  private async claimForcedDurableToolReceiptGroupAfterWait(input: {
+    group: WorkerToolBatchRequest[];
+    receiptKey: string;
+  }): Promise<ClaimedWorkerToolBatchRequest[]> {
+    const [request, ...followers] = input.group;
+    if (!request || !this.options.receiptStore) {
+      this.rejectRawRequests(
+        input.group,
+        new Error(
+          `No receipt store for forced durable tool call ${input.receiptKey}.`,
+        ),
+      );
+      return [];
+    }
+    let claim: WorkerRuntimeReceiptClaim;
+    try {
+      this.options.budgetMeter?.count('receipt');
+      claim = await this.options.receiptStore.claimReceipt({
+        playName: this.options.req.playName,
+        runId: this.options.req.runId,
+        runAttempt: this.options.req.runAttempt ?? 0,
+        key: input.receiptKey,
+        leaseAware: true,
+        leaseTtlMs: this.options.runtimeReceiptLeaseTtlMs,
+        forceRefresh: true,
+        reclaimRunning: true,
+      });
+    } catch (error) {
+      this.rejectRawRequests(input.group, error);
+      return [];
+    }
+    if (claim.disposition === 'claimed') {
+      return [
+        {
+          request,
+          receiptKey: input.receiptKey,
+          receiptLeaseId: claim.receipt.leaseId ?? null,
+          providerForce: true,
+          followers,
+        },
+      ];
+    }
+    const error =
+      claim.disposition === 'failed'
+        ? new Error(
+            `Durable tool call ${input.receiptKey} failed: ${claim.receipt.error ?? 'unknown error'}`,
+          )
+        : new Error(
+            `Forced durable tool call ${input.receiptKey} could not claim execution ownership after the active lease resolved; disposition=${claim.disposition}.`,
+          );
+    this.rejectRawRequests(input.group, error);
+    return [];
+  }
+
+  private async failureForRejectedToolRequest(
+    claimed: ClaimedWorkerToolBatchRequest,
+    error: unknown,
+  ): Promise<unknown> {
+    try {
+      if (
+        isPlayExecutionSuspendedError(error) ||
+        isPlayRowExecutionSuspendedError(error)
+      ) {
+        await this.releaseDurableToolRequest(claimed, error);
+      } else {
+        await this.failDurableToolRequest(claimed, error);
+      }
+      return error;
+    } catch (receiptError) {
+      return receiptPersistenceError({
+        operation: 'fail',
+        receiptKeys: claimed.receiptKey ? [claimed.receiptKey] : [],
+        cause: new AggregateError(
+          [error, receiptError],
+          'Receipt fail mark failed',
+        ),
+      });
+    }
+  }
+
+  private async claimDurableToolReceiptGroups(
+    groups: ReturnType<
+      typeof planWorkerToolReceiptGroups<WorkerToolBatchRequest>
+    >['durableGroups'],
+  ): Promise<
+    Array<{
+      group: ReturnType<
+        typeof planWorkerToolReceiptGroups<WorkerToolBatchRequest>
+      >['durableGroups'][number];
+      receiptKey: string;
+      claim: WorkerRuntimeReceiptClaim;
+    }>
+  > {
+    if (!this.options.receiptStore) return [];
+    const planned = groups.map((group) => ({
+      group,
+      receiptKey: workerRuntimeReceiptKey({
+        req: this.options.req,
+        key: group.claimableReceiptKey,
+      }),
+    }));
+    const claimOne = async (entry: (typeof planned)[number]) => {
+      this.options.budgetMeter?.count('receipt');
+      return {
+        ...entry,
+        claim: await this.options.receiptStore!.claimReceipt({
+          playName: this.options.req.playName,
+          runId: this.options.req.runId,
+          runAttempt: this.options.req.runAttempt ?? 0,
+          key: entry.receiptKey,
+          leaseAware: true,
+          leaseTtlMs: this.options.runtimeReceiptLeaseTtlMs,
+          ...(entry.group.forceDurableRefresh
+            ? { forceRefresh: true }
+            : entry.group.forceFailedDurableRefresh
+              ? { forceFailedRefresh: true }
+              : {}),
+        }),
+      };
+    };
+    if (!this.options.receiptStore.claimReceipts) {
+      return await Promise.all(planned.map(claimOne));
+    }
+    const claimed: Array<{
+      group: (typeof planned)[number]['group'];
+      receiptKey: string;
+      claim: WorkerRuntimeReceiptClaim;
+    }> = [];
+    for (const claimMode of ['normal', 'failed', 'full'] as const) {
+      const entries = planned.filter((entry) =>
+        claimMode === 'full'
+          ? entry.group.forceDurableRefresh
+          : claimMode === 'failed'
+            ? !entry.group.forceDurableRefresh &&
+              entry.group.forceFailedDurableRefresh
+            : !entry.group.forceDurableRefresh &&
+              !entry.group.forceFailedDurableRefresh,
+      );
+      if (entries.length === 0) continue;
+      // Bulk claim is a single service-binding RPC regardless of key count, so
+      // charge one subrequest per RPC issued (once per claimMode page), not one
+      // per receipt key.
+      this.options.budgetMeter?.count('receipt');
+      const claims = await this.options.receiptStore.claimReceipts({
+        playName: this.options.req.playName,
+        runId: this.options.req.runId,
+        runAttempt: this.options.req.runAttempt ?? 0,
+        keys: entries.map((entry) => entry.receiptKey),
+        leaseAware: true,
+        leaseTtlMs: this.options.runtimeReceiptLeaseTtlMs,
+        ...(claimMode === 'full'
+          ? { forceRefresh: true }
+          : claimMode === 'failed'
+            ? { forceFailedRefresh: true }
+            : {}),
+      });
+      entries.forEach((entry, index) => {
+        const claim = claims[index];
+        if (!claim) {
+          throw new Error(
+            `Runtime receipt batch claim did not return receipt ${entry.receiptKey}.`,
+          );
+        }
+        claimed.push({ ...entry, claim });
+      });
+    }
+    return claimed;
+  }
+
+  private async prepareDurableToolRequests(
+    requests: WorkerToolBatchRequest[],
+  ): Promise<PreparedWorkerToolBatchRequests> {
+    if (!this.options.receiptStore) {
+      return {
+        claimedRequests: requests.map((request) => ({
+          request,
+          receiptKey: null,
+          receiptLeaseId: null,
+          followers: [],
+        })),
+        deferredClaimedRequests: [],
+      };
+    }
+
+    const claimedRequests: ClaimedWorkerToolBatchRequest[] = [];
+    const deferredClaimedRequests: Promise<ClaimedWorkerToolBatchRequest[]>[] =
+      [];
+    const receiptGroupPlan = planWorkerToolReceiptGroups(requests, {
+      allowLocalRetryReceipts: this.options.allowLocalRetryReceipts === true,
+      getReceiptInput: (request) => ({
+        durableReceiptKey: request.receiptKey,
+        localRetryCacheKey: request.cacheKey,
+        force: request.force || request.runForceRefresh,
+        forceFailed: request.runForceFailedRefresh,
+      }),
+    });
+    for (const request of receiptGroupPlan.localRequests) {
+      claimedRequests.push({
+        request,
+        receiptKey: null,
+        receiptLeaseId: null,
+        followers: [],
+      });
+    }
+
+    try {
+      const claimEntries = await this.claimDurableToolReceiptGroups(
+        receiptGroupPlan.durableGroups,
+      );
+      for (const { group: groupState, receiptKey, claim } of claimEntries) {
+        const group = groupState.requests;
+        const [first] = group;
+        if (!first) continue;
+        if (
+          claim.disposition === 'failed' &&
+          !groupState.forceDurableRefresh &&
+          group.some((request) => request.runForceRefresh === true)
+        ) {
+          deferredClaimedRequests.push(
+            this.claimForcedDurableToolReceiptGroupAfterWait({
+              group,
+              receiptKey,
+            }),
+          );
+          continue;
+        }
+        if (claim.disposition === 'reused') {
+          const result = markWorkerToolReceiptResultCached(
+            this.options.deserializeDurableValue(claim.receipt.output),
+            first.cacheKey,
+            receiptKey,
+          );
+          for (const request of group) {
+            request.resolve(result);
+          }
+          this.options.onRequestsSettled?.(group.length);
+          continue;
+        }
+        if (claim.disposition === 'failed') {
+          if (
+            canReclaimFailedWorkerToolReceipt({
+              error: claim.receipt.error ?? null,
+            })
+          ) {
+            deferredClaimedRequests.push(
+              this.claimForcedDurableToolReceiptGroupAfterWait({
+                group,
+                receiptKey,
+              }),
+            );
+            continue;
+          }
+          this.rejectRawRequests(
+            group,
+            new Error(
+              `Durable tool call ${receiptKey} failed: ${claim.receipt.error ?? 'unknown error'}`,
+            ),
+          );
+          continue;
+        }
+        if (
+          claim.disposition === 'running' ||
+          claim.disposition === 'blocked_active_lease'
+        ) {
+          deferredClaimedRequests.push(
+            (async (): Promise<ClaimedWorkerToolBatchRequest[]> => {
+              let waitError: unknown = new RuntimeReceiptWaitTimeoutError(
+                receiptKey,
+              );
+              try {
+                const result = await this.waitForDurableToolReceipt({
+                  receiptKey,
+                  maxAttempts: resolveWorkerToolReceiptGroupWaitMaxAttempts(
+                    group,
+                    (request) => request.receiptWaitMaxAttempts,
+                  ),
+                });
+                if (groupState.forceDurableRefresh) {
+                  return await this.claimForcedDurableToolReceiptGroupAfterWait(
+                    {
+                      group,
+                      receiptKey,
+                    },
+                  );
+                }
+                for (const request of group) {
+                  request.resolve(
+                    markWorkerToolReceiptResultExecution(result, {
+                      kind: 'in_flight',
+                      receiptKey,
+                      attachedToReceiptKey: receiptKey,
+                    }),
+                  );
+                }
+                this.options.onRequestsSettled?.(group.length);
+                return [];
+              } catch (error) {
+                waitError = error;
+                if (!(error instanceof RuntimeReceiptWaitTimeoutError)) {
+                  this.rejectRawRequests(group, error);
+                  return [];
+                }
+              }
+              return await this.reclaimTimedOutDurableToolReceiptGroup({
+                group,
+                receiptKey,
+                runningReceipt: claim.receipt,
+                waitError,
+              });
+            })(),
+          );
+          continue;
+        }
+        const [request, ...followers] = group;
+        if (!request) continue;
+        claimedRequests.push({
+          request,
+          receiptKey,
+          receiptLeaseId: claim.receipt.leaseId ?? null,
+          providerForce: groupState.forceDurableRefresh,
+          followers,
+        });
+      }
+    } catch (error) {
+      for (const group of receiptGroupPlan.durableGroups) {
+        this.rejectRawRequests(group.requests, error);
+      }
+    }
+    return { claimedRequests, deferredClaimedRequests };
+  }
+
+  private async completeDurableToolRequest(
+    claimed: ClaimedWorkerToolBatchRequest,
+    result: unknown,
+  ): Promise<unknown> {
+    if (!this.options.receiptStore || !claimed.receiptKey) {
+      return result;
+    }
+    const ownerResult = markWorkerToolReceiptResultExecution(result, {
+      kind: 'live',
+      receiptKey: claimed.receiptKey,
+    });
+    this.options.budgetMeter?.count('receipt');
+    let completed: WorkerRuntimeReceipt | null;
+    try {
+      let completeAttempts = 0;
+      const output = this.options.serializeDurableValue(ownerResult);
+      completed = await this.completeReceiptWithRetryLadder(
+        async () => {
+          completeAttempts += 1;
+          return await this.options.receiptStore!.completeReceipt({
+            playName: this.options.req.playName,
+            runId: this.options.req.runId,
+            runAttempt: this.options.req.runAttempt ?? 0,
+            key: claimed.receiptKey!,
+            leaseId: claimed.receiptLeaseId,
+            output,
+          });
+        },
+        (attempts) =>
+          this.recordReceiptSalvage({
+            claimed,
+            output,
+            attempts: Math.max(attempts, completeAttempts),
+          }),
+      );
+    } catch (error) {
+      throw receiptPersistenceError({
+        operation: 'complete',
+        receiptKeys: [claimed.receiptKey],
+        cause: error,
+      });
+    }
+    const completedResult = this.completedDurableToolRequestResult({
+      claimed,
+      ownerResult,
+      completed,
+    });
+    if (completedResult.ok) return completedResult.value;
+    throw completedResult.error;
+  }
+
+  private completedDurableToolRequestResult(input: {
+    claimed: ClaimedWorkerToolBatchRequest;
+    ownerResult: unknown;
+    completed: WorkerRuntimeReceipt | null | undefined;
+  }): WorkerToolCompletionResult {
+    const { claimed, completed, ownerResult } = input;
+    if (
+      completed &&
+      (completed.status === 'completed' || completed.status === 'skipped') &&
+      completed.output !== undefined
+    ) {
+      const recovered = this.options.deserializeDurableValue(completed.output);
+      return {
+        ok: true,
+        value:
+          completed.runId && completed.runId !== this.options.req.runId
+            ? markWorkerToolReceiptResultCached(
+                recovered,
+                claimed.request.cacheKey,
+                claimed.receiptKey ?? claimed.request.cacheKey,
+              )
+            : recovered,
+      };
+    }
+    if (completed?.status === 'failed') {
+      const receiptKey = claimed.receiptKey ?? claimed.request.cacheKey;
+      return {
+        ok: false,
+        error: receiptPersistenceError({
+          operation: 'complete',
+          receiptKeys: [receiptKey],
+          cause: completed.error
+            ? new Error(completed.error)
+            : new Error(
+                `Durable tool call ${receiptKey} recovered failed receipt completion without an error message.`,
+              ),
+        }),
+      };
+    }
+    return {
+      ok: false,
+      error: receiptPersistenceError({
+        operation: 'complete',
+        receiptKeys: [claimed.receiptKey ?? claimed.request.cacheKey],
+        cause: new Error(
+          `Durable tool call ${claimed.receiptKey ?? claimed.request.cacheKey} lost receipt ownership before completion.`,
+        ),
+      }),
+    };
+  }
+
+  private async recoverCompletedDurableToolRequestResult(input: {
+    claimed: ClaimedWorkerToolBatchRequest;
+    ownerResult: unknown;
+    completed: WorkerRuntimeReceipt | null | undefined;
+    completeAttempts: number;
+  }): Promise<WorkerToolCompletionResult> {
+    const completedResult = this.completedDurableToolRequestResult(input);
+    if (completedResult.ok) {
+      return completedResult;
+    }
+
+    const receiptKey = input.claimed.receiptKey;
+    if (!receiptKey || !this.options.receiptStore?.getReceipt) {
+      return completedResult;
+    }
+
+    let receipt: WorkerRuntimeReceipt | null = null;
+    try {
+      this.options.budgetMeter?.count('receipt');
+      receipt = await this.options.receiptStore.getReceipt({
+        playName: this.options.req.playName,
+        key: receiptKey,
+      });
+    } catch (readError) {
+      this.recordReceiptSalvage({
+        claimed: input.claimed,
+        output: this.options.serializeDurableValue(input.ownerResult),
+        attempts: input.completeAttempts,
+      });
+      return {
+        ok: false,
+        error: receiptPersistenceError({
+          operation: 'complete',
+          receiptKeys: [receiptKey],
+          cause: new AggregateError(
+            [completedResult.error, readError],
+            'Receipt completion returned no terminal receipt and recovery read failed',
+          ),
+        }),
+      };
+    }
+
+    if (this.canCompleteRecoveredRunningReceipt(input.claimed, receipt)) {
+      const output = this.options.serializeDurableValue(input.ownerResult);
+      try {
+        this.options.budgetMeter?.count('receipt');
+        const completed = await this.completeReceiptWithRetryLadder(async () =>
+          this.options.receiptStore!.completeReceipt({
+            playName: this.options.req.playName,
+            runId: this.options.req.runId,
+            runAttempt: this.options.req.runAttempt ?? 0,
+            key: receiptKey,
+            leaseId: input.claimed.receiptLeaseId,
+            output,
+          }),
+        );
+        return this.completedDurableToolRequestResult({
+          claimed: input.claimed,
+          ownerResult: input.ownerResult,
+          completed,
+        });
+      } catch (completeError) {
+        this.recordReceiptSalvage({
+          claimed: input.claimed,
+          output,
+          attempts: input.completeAttempts,
+        });
+        return {
+          ok: false,
+          error: receiptPersistenceError({
+            operation: 'complete',
+            receiptKeys: [receiptKey],
+            cause: new AggregateError(
+              [completedResult.error, completeError],
+              'Receipt completion returned no terminal receipt and owned receipt recovery failed',
+            ),
+          }),
+        };
+      }
+    }
+
+    // Bulk complete can persist terminal receipts, throw once, then return null
+    // on retry because ownership is already gone. The durable row is the source
+    // of truth for that transition; read it before treating the call as lost.
+    const recoveredResult = this.completedDurableToolRequestResult({
+      claimed: input.claimed,
+      ownerResult: input.ownerResult,
+      completed: receipt,
+    });
+    if (recoveredResult.ok) {
+      return recoveredResult;
+    }
+
+    this.recordReceiptSalvage({
+      claimed: input.claimed,
+      output: this.options.serializeDurableValue(input.ownerResult),
+      attempts: input.completeAttempts,
+    });
+    if (receipt?.status === 'failed') {
+      return {
+        ok: false,
+        error: receiptPersistenceError({
+          operation: 'complete',
+          receiptKeys: [receiptKey],
+          cause: receipt.error
+            ? new AggregateError(
+                [completedResult.error, new Error(receipt.error)],
+                'Receipt completion recovered failed terminal receipt',
+              )
+            : completedResult.error,
+        }),
+      };
+    }
+    return completedResult;
+  }
+
+  private canCompleteRecoveredRunningReceipt(
+    claimed: ClaimedWorkerToolBatchRequest,
+    receipt: WorkerRuntimeReceipt | null,
+  ): boolean {
+    if (!claimed.receiptKey || !receipt || receipt.status !== 'running') {
+      return false;
+    }
+    const ownerRunId = receipt.leaseOwnerRunId ?? receipt.runId ?? null;
+    if (ownerRunId !== this.options.req.runId) {
+      return false;
+    }
+    const ownerAttempt =
+      typeof receipt.leaseOwnerAttempt === 'number'
+        ? receipt.leaseOwnerAttempt
+        : 0;
+    if (ownerAttempt !== (this.options.req.runAttempt ?? 0)) {
+      return false;
+    }
+    if (claimed.receiptLeaseId) {
+      return receipt.leaseId === claimed.receiptLeaseId;
+    }
+    return receipt.leaseId == null;
+  }
+
+  private buildDurableToolCompletionBatches(
+    entries: DurableToolCompletionEntry[],
+  ): DurableToolCompletionBatch[] {
+    const envelopeBytes = jsonByteLength({
+      playName: this.options.req.playName,
+      receipts: [],
+    });
+    const batches: DurableToolCompletionBatch[] = [];
+    let current: DurableToolCompletionBatch = {
+      entries: [],
+      bytes: envelopeBytes,
+    };
+    for (const entry of entries) {
+      const entryBytes = entry.serializedBytes;
+      const singleBytes = envelopeBytes + entryBytes;
+      if (singleBytes > WORKER_TOOL_COMPLETE_RECEIPTS_MAX_BATCH_BYTES) {
+        throw receiptPersistenceError({
+          operation: 'complete',
+          receiptKeys: [entry.receipt.key],
+          cause: new Error(
+            `Runtime receipt completion payload for ${entry.receipt.key} is ${singleBytes} bytes, exceeding the ${WORKER_TOOL_COMPLETE_RECEIPTS_MAX_BATCH_BYTES} byte service-binding cap.`,
+          ),
+        });
+      }
+      const commaBytes = current.entries.length > 0 ? 1 : 0;
+      const wouldExceedBytes =
+        current.bytes + commaBytes + entryBytes >
+        WORKER_TOOL_COMPLETE_RECEIPTS_MAX_BATCH_BYTES;
+      const wouldExceedMembers =
+        current.entries.length >=
+        WORKER_TOOL_COMPLETE_RECEIPTS_MAX_BATCH_MEMBERS;
+      if (
+        current.entries.length > 0 &&
+        (wouldExceedBytes || wouldExceedMembers)
+      ) {
+        batches.push(current);
+        current = { entries: [], bytes: envelopeBytes };
+      }
+      current.bytes += (current.entries.length > 0 ? 1 : 0) + entryBytes;
+      current.entries.push(entry);
+    }
+    if (current.entries.length > 0) {
+      batches.push(current);
+    }
+    return batches;
+  }
+
+  private async completeDurableToolRequests(
+    entries: Array<{ claimed: ClaimedWorkerToolBatchRequest; result: unknown }>,
+  ): Promise<WorkerToolCompletionResult[]> {
+    const results: WorkerToolCompletionResult[] = new Array(entries.length);
+    const durableEntries: DurableToolCompletionEntry[] = [];
+    for (let index = 0; index < entries.length; index += 1) {
+      const entry = entries[index]!;
+      if (!this.options.receiptStore || !entry.claimed.receiptKey) {
+        results[index] = { ok: true, value: entry.result };
+        continue;
+      }
+      const ownerResult = markWorkerToolReceiptResultExecution(entry.result, {
+        kind: 'live',
+        receiptKey: entry.claimed.receiptKey,
+      });
+      const receipt = {
+        runId: this.options.req.runId,
+        runAttempt: this.options.req.runAttempt ?? 0,
+        key: entry.claimed.receiptKey!,
+        leaseId: entry.claimed.receiptLeaseId,
+        output: this.options.serializeDurableValue(ownerResult),
+      };
+      durableEntries.push({
+        index,
+        claimed: entry.claimed,
+        ownerResult,
+        receipt,
+        serializedBytes: jsonByteLength(receipt),
+      });
+    }
+    if (durableEntries.length === 0) {
+      return results;
+    }
+    if (!this.options.receiptStore?.completeReceipts) {
+      await Promise.all(
+        durableEntries.map(async (entry) => {
+          try {
+            results[entry.index] = {
+              ok: true,
+              value: await this.completeDurableToolRequest(
+                entry.claimed,
+                entries[entry.index]!.result,
+              ),
+            };
+          } catch (error) {
+            results[entry.index] = { ok: false, error };
+          }
+        }),
+      );
+      return results;
+    }
+    const completionBatches =
+      this.buildDurableToolCompletionBatches(durableEntries);
+    let completeAttempts = 0;
+    for (const batch of completionBatches) {
+      this.options.budgetMeter?.count('receipt');
+      let completed: Array<WorkerRuntimeReceipt | null>;
+      try {
+        completeAttempts += 1;
+        completed = await this.options.receiptStore!.completeReceipts!({
+          playName: this.options.req.playName,
+          receipts: batch.entries.map((entry) => entry.receipt),
+        });
+      } catch (error) {
+        const persistenceError = receiptPersistenceError({
+          operation: 'complete',
+          receiptKeys: batch.entries.map((entry) => entry.receipt.key),
+          cause: error,
+        });
+        if (!this.options.receiptStore.getReceipt) {
+          for (const entry of batch.entries) {
+            this.recordReceiptSalvage({
+              claimed: entry.claimed,
+              output: entry.receipt.output,
+              attempts: completeAttempts,
+            });
+            results[entry.index] = { ok: false, error: persistenceError };
+          }
+          continue;
+        }
+        await mapWithConcurrency(
+          batch.entries,
+          WORKER_TOOL_RECEIPT_RECOVERY_MAX_CONCURRENT_READS,
+          async (entry) => {
+            const receiptKey = entry.receipt.key;
+            let receipt: WorkerRuntimeReceipt | null = null;
+            try {
+              this.options.budgetMeter?.count('receipt');
+              receipt = await this.options.receiptStore!.getReceipt!({
+                playName: this.options.req.playName,
+                key: receiptKey,
+              });
+            } catch (readError) {
+              this.recordReceiptSalvage({
+                claimed: entry.claimed,
+                output: entry.receipt.output,
+                attempts: completeAttempts,
+              });
+              results[entry.index] = {
+                ok: false,
+                error: receiptPersistenceError({
+                  operation: 'complete',
+                  receiptKeys: [receiptKey],
+                  cause: new AggregateError(
+                    [error, readError],
+                    'Receipt completion failed and receipt recovery read failed',
+                  ),
+                }),
+              };
+              return;
+            }
+            if (
+              receipt &&
+              (receipt.status === 'completed' ||
+                receipt.status === 'skipped') &&
+              receipt.output !== undefined
+            ) {
+              results[entry.index] = this.completedDurableToolRequestResult({
+                claimed: entry.claimed,
+                ownerResult: entry.ownerResult,
+                completed: receipt,
+              });
+              return;
+            }
+            if (
+              this.canCompleteRecoveredRunningReceipt(entry.claimed, receipt)
+            ) {
+              try {
+                results[entry.index] = {
+                  ok: true,
+                  value: await this.completeDurableToolRequest(
+                    entry.claimed,
+                    entries[entry.index]!.result,
+                  ),
+                };
+                return;
+              } catch (singleCompleteError) {
+                results[entry.index] = {
+                  ok: false,
+                  error: receiptPersistenceError({
+                    operation: 'complete',
+                    receiptKeys: [receiptKey],
+                    cause: new AggregateError(
+                      [error, singleCompleteError],
+                      'Receipt completion failed and owned receipt recovery failed',
+                    ),
+                  }),
+                };
+                return;
+              }
+            }
+            this.recordReceiptSalvage({
+              claimed: entry.claimed,
+              output: entry.receipt.output,
+              attempts: completeAttempts,
+            });
+            results[entry.index] = {
+              ok: false,
+              error: receiptPersistenceError({
+                operation: 'complete',
+                receiptKeys: [receiptKey],
+                cause: receipt?.error
+                  ? new AggregateError(
+                      [error, new Error(receipt.error)],
+                      'Receipt completion failed and receipt recovered failed',
+                    )
+                  : error,
+              }),
+            };
+          },
+        );
+        this.options.recordPerfTrace?.({
+          phase: 'worker.tool_receipts.partial_complete_recovery',
+          extra: {
+            recovered: batch.entries.filter((entry) => results[entry.index]?.ok)
+              .length,
+            failed: batch.entries.filter((entry) => {
+              const result = results[entry.index];
+              return result && !result.ok;
+            }).length,
+            total: batch.entries.length,
+            failedReceiptKeys: batch.entries
+              .filter((entry) => {
+                const result = results[entry.index];
+                return result && !result.ok;
+              })
+              .slice(0, 5)
+              .map((entry) => entry.receipt.key),
+          },
+        });
+        continue;
+      }
+      await mapWithConcurrency(
+        batch.entries,
+        WORKER_TOOL_RECEIPT_RECOVERY_MAX_CONCURRENT_READS,
+        async (entry, resultIndex) => {
+          results[entry.index] =
+            await this.recoverCompletedDurableToolRequestResult({
+              claimed: entry.claimed,
+              ownerResult: entry.ownerResult,
+              completed: completed[resultIndex],
+              completeAttempts,
+            });
+        },
+      );
+    }
+    return results;
+  }
+
+  private async failDurableToolRequest(
+    claimed: ClaimedWorkerToolBatchRequest,
+    error: unknown,
+  ): Promise<void> {
+    if (!this.options.receiptStore || !claimed.receiptKey) {
+      return;
+    }
+    this.options.budgetMeter?.count('receipt');
+    try {
+      await this.options.receiptStore.failReceipt({
+        playName: this.options.req.playName,
+        runId: this.options.req.runId,
+        runAttempt: this.options.req.runAttempt ?? 0,
+        key: claimed.receiptKey,
+        leaseId: claimed.receiptLeaseId,
+        error: error instanceof Error ? error.message : String(error),
+        failureKind: workReceiptFailureKindForError(error),
+      });
+    } catch (receiptError) {
+      if (this.options.persistenceLatch) {
+        tripRuntimePersistenceLatch(
+          this.options.persistenceLatch,
+          receiptError,
+        );
+      }
+      throw receiptPersistenceError({
+        operation: 'fail',
+        receiptKeys: [claimed.receiptKey],
+        cause: receiptError,
+      });
+    }
+  }
+
+  private async releaseDurableToolRequest(
+    claimed: ClaimedWorkerToolBatchRequest,
+    error: unknown,
+  ): Promise<void> {
+    if (!this.options.receiptStore || !claimed.receiptKey) {
+      return;
+    }
+    if (!this.options.receiptStore.releaseReceipt) {
+      throw new Error(
+        `Durable tool call ${claimed.receiptKey} suspended but the receipt store cannot release ownership.`,
+      );
+    }
+    this.options.budgetMeter?.count('receipt');
+    try {
+      const released = await this.options.receiptStore.releaseReceipt({
+        playName: this.options.req.playName,
+        runId: this.options.req.runId,
+        runAttempt: this.options.req.runAttempt ?? 0,
+        key: claimed.receiptKey,
+        leaseId: claimed.receiptLeaseId,
+      });
+      if (!released || released.status !== 'pending') {
+        throw new Error(
+          `Durable tool call ${claimed.receiptKey} suspended but receipt ownership could not be released.`,
+        );
+      }
+    } catch (receiptError) {
+      if (this.options.persistenceLatch) {
+        tripRuntimePersistenceLatch(
+          this.options.persistenceLatch,
+          receiptError,
+        );
+      }
+      throw receiptPersistenceError({
+        operation: 'fail',
+        receiptKeys: [claimed.receiptKey],
+        cause: new AggregateError(
+          [error, receiptError],
+          'Tool receipt release failed after durable suspension',
+        ),
+      });
+    }
+  }
+
+  private async failDurableToolRequests(
+    claimedRequests: ClaimedWorkerToolBatchRequest[],
+    error: unknown,
+  ): Promise<void> {
+    const durable = claimedRequests.filter(
+      (claimed) => this.options.receiptStore && claimed.receiptKey,
+    );
+    if (durable.length === 0) return;
+    if (
+      isPlayExecutionSuspendedError(error) ||
+      isPlayRowExecutionSuspendedError(error)
+    ) {
+      await Promise.all(
+        durable.map((claimed) =>
+          this.releaseDurableToolRequest(claimed, error),
+        ),
+      );
+      return;
+    }
+    if (!this.options.receiptStore?.failReceipts) {
+      await Promise.all(
+        durable.map((claimed) => this.failDurableToolRequest(claimed, error)),
+      );
+      return;
+    }
+    // Bulk fail is a single service-binding RPC regardless of key count.
+    this.options.budgetMeter?.count('receipt');
+    try {
+      await this.options.receiptStore.failReceipts({
+        playName: this.options.req.playName,
+        receipts: durable.map((claimed) => ({
+          runId: this.options.req.runId,
+          runAttempt: this.options.req.runAttempt ?? 0,
+          key: claimed.receiptKey!,
+          leaseId: claimed.receiptLeaseId,
+          error: error instanceof Error ? error.message : String(error),
+          failureKind: workReceiptFailureKindForError(error),
+        })),
+      });
+    } catch (receiptError) {
+      if (this.options.persistenceLatch) {
+        tripRuntimePersistenceLatch(
+          this.options.persistenceLatch,
+          receiptError,
+        );
+      }
+      throw receiptPersistenceError({
+        operation: 'fail',
+        receiptKeys: durable
+          .map((claimed) => claimed.receiptKey)
+          .filter((key): key is string => typeof key === 'string'),
+        cause: receiptError,
+      });
+    }
+  }
+
+  private async executeToolGroup(
+    toolId: string,
+    requests: WorkerToolBatchRequest[],
+  ): Promise<void> {
+    const { claimedRequests, deferredClaimedRequests } =
+      await this.prepareDurableToolRequests(requests);
+    await this.executeClaimedToolRequests(
+      toolId,
+      requests.length,
+      claimedRequests,
+    );
+    if (deferredClaimedRequests.length === 0) {
+      return;
+    }
+    const reclaimedRequests = (
+      await Promise.all(deferredClaimedRequests)
+    ).flat();
+    await this.executeClaimedToolRequests(
+      toolId,
+      requests.length,
+      reclaimedRequests,
+    );
+  }
+
+  private async executeClaimedToolRequests(
+    toolId: string,
+    requestCount: number,
+    claimedRequests: ClaimedWorkerToolBatchRequest[],
+  ): Promise<void> {
+    if (claimedRequests.length === 0) {
+      return;
+    }
+    const strategy = getPlayRuntimeBatchStrategy(toolId);
+    if (
+      !strategy ||
+      toolId === 'test_wait_for_event' ||
+      claimedRequests.length < 2
+    ) {
+      const groupStartedAt = this.options.nowMs();
+      await Promise.all(
+        claimedRequests.map(async (claimed) => {
+          const { request } = claimed;
+          const toolContract = await this.options
+            .resolvePacing(toolId)
+            .catch(() => null);
+          const circuitOpenError = this.runtimePersistenceCircuitOpenError(1);
+          if (circuitOpenError) {
+            this.rejectRequests(
+              claimed,
+              await this.failureForRejectedToolRequest(
+                claimed,
+                circuitOpenError,
+              ),
+            );
+            return;
+          }
+          // Each unbatched provider call takes its own tool slot: the Governor
+          // charges tool budget, holds a global tool-concurrency slot, and
+          // applies per-(org,provider) pacing before the call runs.
+          let slot: { release: () => void };
+          try {
+            slot = await this.options.governor.acquireToolSlot(toolId, {
+              signal: this.options.abortSignal,
+            });
+          } catch (error) {
+            this.rejectRequests(
+              claimed,
+              await this.failureForRejectedToolRequest(claimed, error),
+            );
+            return;
+          }
+          this.options.budgetMeter?.count('provider');
+          this.options.budgetMeter?.count(
+            'egress',
+            Math.max(
+              0,
+              WORKER_PLATFORM_SUBREQUESTS_PER_UNBATCHED_TOOL_CALL - 1,
+            ),
+          );
+          try {
+            let result: unknown;
+            try {
+              const durableReceiptKey = claimed.receiptKey
+                ? durableCallReceiptKeyForClaimed({
+                    req: this.options.req,
+                    claimed,
+                  })
+                : null;
+              result = await executeWithWorkerReceiptHeartbeats({
+                playName: this.options.req.playName,
+                runId: this.options.req.runId,
+                runAttempt: this.options.req.runAttempt ?? 0,
+                ...(this.options.receiptStore
+                  ? { receiptStore: this.options.receiptStore }
+                  : {}),
+                budgetMeter: this.options.budgetMeter,
+                heartbeatIntervalMs:
+                  this.options.runtimeReceiptHeartbeatIntervalMs,
+                targets: claimed.receiptKey
+                  ? [
+                      {
+                        key: claimed.receiptKey,
+                        leaseId: claimed.receiptLeaseId,
+                      },
+                    ]
+                  : [],
+                execute: () =>
+                  this.options.executeTool({
+                    id: request.id,
+                    toolId,
+                    input: request.input,
+                    workflowStep: request.workflowStep,
+                    callbacks: this.options.callbacks,
+                    onProviderBackpressure: (retryAfterMs) =>
+                      this.reportBackpressure(toolId, retryAfterMs),
+                    onRetryAttempt: () =>
+                      this.options.governor.chargeBudget('retry'),
+                    transientHttpRetrySafe:
+                      toolContract?.retrySafeTransientHttp === true,
+                    ...(durableReceiptKey
+                      ? {
+                          durableCallReceiptKey: durableReceiptKey,
+                          executionAuthScopeDigest:
+                            request.executionAuthScopeDigest,
+                          providerIdempotencyKey:
+                            providerIdempotencyKeyForClaimed({
+                              req: this.options.req,
+                              claimed,
+                            }),
+                        }
+                      : {}),
+                    runtimeTimeoutMs: resolveWorkerToolRuntimeTimeoutMs(
+                      [claimed],
+                      {
+                        resolveOwnerTimeoutMs: (request) =>
+                          request.runtimeTimeoutMs,
+                      },
+                    ),
+                    directOptions: request.directOptions,
+                  }),
+              });
+            } catch (error) {
+              if (error instanceof RuntimeLeaseLostError) {
+                this.rejectRequests(claimed, error);
+                return;
+              }
+              if (
+                await this.requeueAfterAuthScopeChanged(
+                  [request, ...claimed.followers],
+                  error,
+                )
+              ) {
+                return;
+              }
+              this.rejectRequests(
+                claimed,
+                await this.failureForRejectedToolRequest(claimed, error),
+              );
+              return;
+            }
+            try {
+              this.settleRequests(
+                claimed,
+                await this.completeDurableToolRequest(claimed, result),
+              );
+            } catch (receiptError) {
+              this.rejectRequests(claimed, receiptError);
+            }
+          } finally {
+            slot.release();
+          }
+        }),
+      );
+      this.options.recordPerfTrace?.({
+        phase: 'runner.tool.group',
+        ms: this.options.nowMs() - groupStartedAt,
+        extra: {
+          toolId,
+          requests: requestCount,
+          executed: claimedRequests.length,
+          batched: false,
+        },
+      });
+      return;
+    }
+
+    const batchStartedAt = this.options.nowMs();
+    await this.executeBatchedWorkerToolGroup({
+      sourceToolId: toolId,
+      requests: claimedRequests,
+      strategy,
+      suggestedParallelism: await this.options.governor.suggestedParallelism(
+        toolId,
+        this.options.governor.policy.pacing.workerToolBatchDefaultParallelism,
+      ),
+    });
+    this.options.recordPerfTrace?.({
+      phase: 'runner.tool.group',
+      ms: this.options.nowMs() - batchStartedAt,
+      extra: {
+        toolId,
+        requests: requestCount,
+        executed: claimedRequests.length,
+        batched: true,
+      },
+    });
+  }
+
+  private async executeBatchedWorkerToolGroup(input: {
+    sourceToolId: string;
+    requests: ClaimedWorkerToolBatchRequest[];
+    strategy: AnyBatchOperationStrategy;
+    suggestedParallelism: number;
+  }): Promise<void> {
+    const compiledBatches = compileRequestsWithStrategy({
+      requests: input.requests,
+      strategy: input.strategy,
+      getPayload: (request) => request.request.input,
+    });
+    this.options.recordPerfTrace?.({
+      phase: 'runner.tool.batch.compile',
+      ms: 0,
+      extra: {
+        sourceOperation: input.strategy.sourceOperation,
+        batchOperation: input.strategy.batchOperation,
+        requests: input.requests.length,
+        batches: compiledBatches.length,
+        batchSizes: compiledBatches.map((batch) => batch.memberRequests.length),
+      },
+    });
+    await executeChunkedRequests({
+      requests: compiledBatches,
+      // Chunk parallelism is the Governor's per-tool suggestion (provider rate
+      // hints tightened to the policy ceiling), bounded by the batch count.
+      batchSize: Math.max(
+        1,
+        Math.min(input.suggestedParallelism, compiledBatches.length || 1),
+      ),
+      execute: async (batch) => {
+        const toolContract = await this.options
+          .resolvePacing(batch.batchOperation)
+          .catch(() => null);
+        const circuitOpenError = this.runtimePersistenceCircuitOpenError(
+          batch.memberRequests.length,
+        );
+        if (circuitOpenError) {
+          throw circuitOpenError;
+        }
+        // One provider call per batch -> one tool slot (budget + global
+        // concurrency + per-(org,provider) pacing) around the whole batch.
+        const slot = await this.options.governor.acquireToolSlot(
+          batch.batchOperation,
+          {
+            signal: this.options.abortSignal,
+          },
+        );
+        this.options.budgetMeter?.count('provider');
+        try {
+          const receiptKeys = batch.memberRequests.map((member) =>
+            durableCallReceiptKeyForClaimed({
+              req: this.options.req,
+              claimed: member,
+            }),
+          );
+          const aggregateReceiptKey = buildBatchDurableCallReceiptKey({
+            req: this.options.req,
+            batchOperation: batch.batchOperation,
+            receiptKeys,
+          });
+          return await executeWithWorkerReceiptHeartbeats({
+            playName: this.options.req.playName,
+            runId: this.options.req.runId,
+            runAttempt: this.options.req.runAttempt ?? 0,
+            ...(this.options.receiptStore
+              ? { receiptStore: this.options.receiptStore }
+              : {}),
+            budgetMeter: this.options.budgetMeter,
+            heartbeatIntervalMs: this.options.runtimeReceiptHeartbeatIntervalMs,
+            targets: batch.memberRequests.map((member) => ({
+              key: member.receiptKey,
+              leaseId: member.receiptLeaseId,
+            })),
+            execute: () =>
+              this.options.executeTool({
+                id: `batch:${batch.memberRequests.map((request) => request.request.id).join('|')}`,
+                toolId: batch.batchOperation,
+                input: batch.batchPayload,
+                callbacks: this.options.callbacks,
+                onProviderBackpressure: (retryAfterMs) =>
+                  this.reportBackpressure(input.sourceToolId, retryAfterMs),
+                onRetryAttempt: () =>
+                  this.options.governor.chargeBudget('retry'),
+                transientHttpRetrySafe:
+                  toolContract?.retrySafeTransientHttp === true,
+                durableCallReceiptKey: aggregateReceiptKey,
+                executionAuthScopeDigest:
+                  batch.memberRequests[0]?.request.executionAuthScopeDigest ??
+                  null,
+                providerIdempotencyKey: buildBatchProviderIdempotencyKey({
+                  aggregateReceiptKey,
+                  receiptKeys,
+                  providerIdempotencyKeys: batch.memberRequests.map((member) =>
+                    providerIdempotencyKeyForClaimed({
+                      req: this.options.req,
+                      claimed: member,
+                    }),
+                  ),
+                }),
+                runtimeTimeoutMs: resolveWorkerToolRuntimeTimeoutMs(
+                  batch.memberRequests,
+                  {
+                    resolveOwnerTimeoutMs: (request) =>
+                      request.runtimeTimeoutMs,
+                  },
+                ),
+              }),
+          });
+        } finally {
+          slot.release();
+        }
+      },
+      onChunkComplete: async (
+        chunkResults: Array<
+          ChunkExecutionResult<(typeof compiledBatches)[number], unknown>
+        >,
+      ) => {
+        for (const entry of chunkResults) {
+          if (entry.error !== undefined) {
+            // One batch's provider error stays scoped to that batch's member
+            // requests. Sibling batches in this chunk keep their results so a
+            // single provider hiccup cannot cascade into a whole-map failure.
+            if (
+              entry.error instanceof ToolExecuteAuthScopeChangedError &&
+              entry.request.memberRequests.every(
+                (claimed) => claimed.request.authScopeRetryUsed !== true,
+              ) &&
+              (await this.requeueAfterAuthScopeChanged(
+                entry.request.memberRequests.map((claimed) => claimed.request),
+                entry.error,
+              ))
+            ) {
+              continue;
+            }
+            let rejection: unknown = entry.error;
+            if (!(entry.error instanceof RuntimeLeaseLostError)) {
+              try {
+                await this.failDurableToolRequests(
+                  entry.request.memberRequests,
+                  entry.error,
+                );
+              } catch (receiptError) {
+                rejection = receiptPersistenceError({
+                  operation: 'fail',
+                  receiptKeys: entry.request.memberRequests
+                    .map((claimed) => claimed.receiptKey)
+                    .filter((key): key is string => typeof key === 'string'),
+                  cause: new AggregateError(
+                    [entry.error, receiptError],
+                    'Tool receipts fail mark failed',
+                  ),
+                });
+              }
+            }
+            for (const claimed of entry.request.memberRequests) {
+              this.rejectRequests(claimed, rejection);
+            }
+            continue;
+          }
+          const batchResult = isToolExecuteResult(entry.result)
+            ? entry.result.toolOutput.raw
+            : entry.result;
+          const splitResults =
+            batchResult != null
+              ? entry.request.splitResults(batchResult)
+              : entry.request.memberRequests.map(() => null);
+          let completedResults: WorkerToolCompletionResult[];
+          try {
+            completedResults = await this.completeDurableToolRequests(
+              entry.request.memberRequests.map((claimed, index) => ({
+                claimed,
+                result: wrapWorkerToolResult(
+                  claimed.request.toolId,
+                  splitResults[index] ?? null,
+                  toolMetadataFallback(claimed.request.toolId),
+                ),
+              })),
+            );
+          } catch (receiptError) {
+            for (const claimed of entry.request.memberRequests) {
+              this.rejectRequests(claimed, receiptError);
+            }
+            continue;
+          }
+          for (let index = 0; index < completedResults.length; index += 1) {
+            const claimed = entry.request.memberRequests[index]!;
+            const completed = completedResults[index];
+            if (!completed) {
+              this.rejectRequests(
+                claimed,
+                new Error(
+                  `Tool batch completion did not return member ${claimed.request.id}.`,
+                ),
+              );
+            } else if (completed.ok) {
+              this.settleRequests(claimed, completed.value);
+            } else {
+              this.rejectRequests(claimed, completed.error);
+            }
+          }
+        }
+      },
+    }).catch(async (error) => {
+      let rejection: unknown = error;
+      if (
+        error instanceof ToolExecuteAuthScopeChangedError &&
+        (await this.requeueAfterAuthScopeChanged(
+          input.requests.map((claimed) => claimed.request),
+          error,
+        ))
+      ) {
+        return;
+      }
+      if (!(error instanceof RuntimeLeaseLostError)) {
+        try {
+          await this.failDurableToolRequests(input.requests, error);
+        } catch (receiptError) {
+          rejection = receiptPersistenceError({
+            operation: 'fail',
+            receiptKeys: input.requests
+              .map((claimed) => claimed.receiptKey)
+              .filter((key): key is string => typeof key === 'string'),
+            cause: new AggregateError(
+              [error, receiptError],
+              'Tool receipts fail mark failed',
+            ),
+          });
+        }
+      }
+      for (const claimed of input.requests) {
+        this.rejectRequests(claimed, rejection);
+      }
+    });
+  }
+}
+
+function groupWorkerToolRequestsByTool(
+  requests: WorkerToolBatchRequest[],
+): Map<string, WorkerToolBatchRequest[]> {
+  const byTool = new Map<string, WorkerToolBatchRequest[]>();
+  for (const request of requests) {
+    const existing = byTool.get(request.toolId);
+    if (existing) {
+      existing.push(request);
+    } else {
+      byTool.set(request.toolId, [request]);
+    }
+  }
+  return byTool;
+}