machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/worker/oauth-token-issuance.ts

@@ -0,0 +1,119 @@
+import {
+  pruneClientRecordByExpiry,
+  pruneRecordByExpiry,
+  randomToken,
+  sha256Hex,
+  type OAuthCode,
+  type OAuthRefreshStore,
+  type OAuthRefreshToken,
+  type OAuthStore,
+} from "./oauth-state.ts";
+import { HttpError, json, workerErrorClass } from "./http.ts";
+import { writeOAuthRefreshPersistenceEntries } from "./oauth-refresh-persistence.ts";
+import { deriveRefreshReplacementPair } from "./oauth-token-derivation.ts";
+import type { AuthorityRevocation } from "../shared/authority-revocation.mjs";
+
+const ACCESS_TOKEN_TTL_SECONDS = 15 * 60;
+const REFRESH_TOKEN_IDLE_TTL_SECONDS = 60 * 60 * 24 * 14;
+const REFRESH_TOKEN_FAMILY_TTL_SECONDS = 60 * 60 * 24 * 30;
+const MAX_ACCESS_TOKENS = 500;
+const MAX_ACCESS_TOKENS_PER_CLIENT = 20;
+const MAX_REFRESH_TOKENS = 500;
+const MAX_REFRESH_TOKENS_PER_CLIENT = 20;
+
+type OAuthLock = <T>(callback: () => Promise<T>) => Promise<T>;
+export type OAuthRefreshEvent = "rotated" | "retry_issued" | "retry_exhausted" | "family_revoked" | "rejected";
+
+export interface OAuthTokenExchangeOptions {
+  storage: DurableObjectStorage;
+  tokenVersion: string;
+  serverName: string;
+  loadOAuthStore: () => Promise<OAuthStore>;
+  withLock: OAuthLock;
+  onRefreshEvent?: (event: OAuthRefreshEvent) => void;
+  saveStores: (oauthStore: OAuthStore, refreshStore: OAuthRefreshStore, revocation?: AuthorityRevocation) => Promise<void>;
+}
+
+export interface IssuedTokenPair {
+  accessToken: string;
+  refreshToken: string;
+}
+
+export async function issueTokenPair(
+  oauthStore: OAuthStore,
+  refreshStore: OAuthRefreshStore,
+  source: OAuthCode | OAuthRefreshToken,
+  tokenVersion: string,
+  dpopJkt?: string,
+  issuance: { derivationSeed?: string; issuedAt?: number; accessScope?: string } = {},
+): Promise<IssuedTokenPair> {
+  if (!tokenVersion) throw new HttpError(503, "server_error", "OAuth token version is not configured");
+  const now = Number.isSafeInteger(issuance.issuedAt) && Number(issuance.issuedAt) > 0
+    ? Number(issuance.issuedAt)
+    : Math.floor(Date.now() / 1000);
+  const familyId = "family_id" in source && source.family_id ? source.family_id : randomToken("mcp_family");
+  const familyExpiresAt = "family_expires_at" in source && source.family_expires_at
+    ? source.family_expires_at
+    : now + REFRESH_TOKEN_FAMILY_TTL_SECONDS;
+  if (familyExpiresAt <= now) throw new HttpError(400, "invalid_grant", "refresh-token family expired");
+  const issued = issuance.derivationSeed
+    ? await deriveRefreshReplacementPair(tokenVersion, issuance.derivationSeed)
+    : { accessToken: randomToken("mcp_at"), refreshToken: randomToken("mcp_rt") };
+  const { accessToken, refreshToken } = issued;
+  const accessScope = typeof issuance.accessScope === "string" && issuance.accessScope.trim()
+    ? issuance.accessScope.trim()
+    : source.scope;
+  const common = {
+    client_id: source.client_id,
+    account_id: source.account_id,
+    account_version: source.account_version,
+    role: source.role,
+    resource: source.resource,
+    version: tokenVersion,
+    family_id: familyId,
+    ...(dpopJkt ? { dpop_jkt: dpopJkt } : {}),
+  };
+  oauthStore.tokens[`sha256:${await sha256Hex(accessToken)}`] = {
+    ...common,
+    scope: accessScope,
+    expires_at: now + ACCESS_TOKEN_TTL_SECONDS,
+  };
+  refreshStore.tokens[`sha256:${await sha256Hex(refreshToken)}`] = {
+    ...common,
+    scope: source.scope,
+    family_id: familyId,
+    family_expires_at: familyExpiresAt,
+    issued_at: now,
+    expires_at: Math.min(now + REFRESH_TOKEN_IDLE_TTL_SECONDS, familyExpiresAt),
+  };
+  pruneClientRecordByExpiry(oauthStore.tokens, source.client_id, MAX_ACCESS_TOKENS_PER_CLIENT);
+  pruneRecordByExpiry(oauthStore.tokens, MAX_ACCESS_TOKENS);
+  pruneClientRecordByExpiry(refreshStore.tokens, source.client_id, MAX_REFRESH_TOKENS_PER_CLIENT);
+  pruneRecordByExpiry(refreshStore.tokens, MAX_REFRESH_TOKENS);
+  return { accessToken, refreshToken };
+}
+
+export function tokenResponse(issued: IssuedTokenPair, scope: string, dpopJkt?: string): Response {
+  return json({
+    access_token: issued.accessToken,
+    refresh_token: issued.refreshToken,
+    token_type: dpopJkt ? "DPoP" : "Bearer",
+    expires_in: ACCESS_TOKEN_TTL_SECONDS,
+    scope,
+  }, 200, { pragma: "no-cache" });
+}
+
+export async function saveOAuthStores(
+  oauthStore: OAuthStore, refreshStore: OAuthRefreshStore, storage: DurableObjectStorage,
+): Promise<void> {
+  let stage = "oauth";
+  try {
+    await storage.transaction(async (tx) => {
+      await tx.put("oauth", oauthStore); stage = "refresh";
+      await writeOAuthRefreshPersistenceEntries(tx, refreshStore); stage = "commit";
+    });
+  } catch (error) {
+    const wrapped = new Error("OAuth store persistence failed", { cause: error });
+    wrapped.name = `oauth_store_persist_${stage}_${workerErrorClass(error)}`; throw wrapped;
+  }
+}

package/src/worker/oauth-tokens.ts

@@ -1,34 +1,18 @@
-import {
-  normalizeOAuthScope, pkceS256, pruneClientRecordByExpiry, pruneRecordByExpiry,
-  randomToken, safeEqual, sha256Hex,
-  type OAuthCode, type OAuthRefreshStore, type OAuthRefreshToken, type OAuthStore,
-} from "./oauth-state.ts";
+import { consumeDpopProof, verifyDpopProof, type VerifiedDpopProof } from "./dpop.ts";
 import { HttpError, json, parseRequestBody } from "./http.ts";
-import { loadOAuthRefreshStore, OAUTH_REFRESH_STORE_KEY, recordConsumedRefreshToken, revokeOAuthRefreshFamily } from "./oauth-refresh-families.ts";
+import { loadOAuthRefreshStore } from "./oauth-refresh-families.ts";
+import { exchangeRefreshToken } from "./oauth-refresh-exchange.ts";
+import {
+  issueTokenPair,
+  saveOAuthStores,
+  tokenResponse,
+  type OAuthTokenExchangeOptions,
+} from "./oauth-token-issuance.ts";
+import { normalizeOAuthScope, pkceS256, safeEqual } from "./oauth-state.ts";
 
-const ACCESS_TOKEN_TTL_SECONDS = 15 * 60;
-const REFRESH_TOKEN_IDLE_TTL_SECONDS = 60 * 60 * 24 * 14;
-const REFRESH_TOKEN_FAMILY_TTL_SECONDS = 60 * 60 * 24 * 30;
+export type { OAuthRefreshEvent } from "./oauth-token-issuance.ts";
 const OAUTH_BODY_LIMIT_BYTES = 64 * 1024;
-const MAX_ACCESS_TOKENS = 500;
-const MAX_ACCESS_TOKENS_PER_CLIENT = 20;
-const MAX_REFRESH_TOKENS = 500;
-const MAX_REFRESH_TOKENS_PER_CLIENT = 20;
-
-type OAuthLock = <T>(callback: () => Promise<T>) => Promise<T>;
-
-interface OAuthTokenExchangeOptions {
-  storage: DurableObjectStorage;
-  tokenVersion: string;
-  serverName: string;
-  loadOAuthStore: () => Promise<OAuthStore>;
-  withLock: OAuthLock;
-}
-
-interface IssuedTokenPair {
-  accessToken: string;
-  refreshToken: string;
-}
+type AuthorizationCodeStage = "lock" | "load_oauth" | "load_refresh" | "pkce" | "issue" | "persist" | "response";
 
 export async function exchangeOAuthToken(
   request: Request,
@@ -36,9 +20,12 @@ export async function exchangeOAuthToken(
   options: OAuthTokenExchangeOptions,
 ): Promise<Response> {
   const body = await parseRequestBody(request, OAUTH_BODY_LIMIT_BYTES);
+  const hasDpop = Boolean(request.headers.get("DPoP"));
+  const dpop = hasDpop ? await verifyDpopProof({ request, expectedMethod: "POST", expectedUrl: request.url }) : null;
+  if (hasDpop && !dpop) return json({ error: "invalid_dpop_proof" }, 400);
   const grantType = String(body.grant_type ?? "");
-  if (grantType === "authorization_code") return exchangeAuthorizationCode(body, base, options);
-  if (grantType === "refresh_token") return exchangeRefreshToken(body, base, options);
+  if (grantType === "authorization_code") return exchangeAuthorizationCode(body, base, options, dpop || undefined);
+  if (grantType === "refresh_token") return exchangeRefreshToken(body, base, options, dpop || undefined);
   return json({ error: "unsupported_grant_type" }, 400);
 }
 
@@ -46,172 +33,51 @@ async function exchangeAuthorizationCode(
   body: Record<string, unknown>,
   base: string,
   options: OAuthTokenExchangeOptions,
+  dpop?: VerifiedDpopProof,
 ): Promise<Response> {
   const code = String(body.code ?? "");
   const verifier = String(body.code_verifier ?? "");
   if (!/^[A-Za-z0-9._~-]{43,128}$/.test(verifier)) {
     return json({ error: "invalid_grant", error_description: "invalid code_verifier" }, 400);
   }
-  return options.withLock(async () => {
-    const oauthStore = await options.loadOAuthStore();
-    const refreshStore = await loadOAuthRefreshStore(oauthStore, options.storage);
-    const record = oauthStore.codes[code];
-    if (!record) return json({ error: "invalid_grant" }, 400);
-    if (String(body.client_id ?? "") !== record.client_id || String(body.redirect_uri ?? "") !== record.redirect_uri) {
-      return json({ error: "invalid_grant", error_description: "client or redirect mismatch" }, 400);
-    }
-    if (String(body.resource ?? record.resource) !== record.resource || record.resource !== `${base}/mcp`) {
-      return json({ error: "invalid_target", error_description: "resource mismatch" }, 400);
-    }
-    if (!(await safeEqual(await pkceS256(verifier), record.code_challenge))) {
-      return json({ error: "invalid_grant", error_description: "invalid code_verifier" }, 400);
-    }
-    const client = oauthStore.clients[record.client_id];
-    if (!client) return json({ error: "invalid_grant", error_description: "unknown client" }, 400);
-
-    const issued = await issueTokenPair(oauthStore, refreshStore, record, options.tokenVersion);
-    delete oauthStore.codes[code];
-    client.last_used_at = Math.floor(Date.now() / 1000);
-    await saveOAuthStores(oauthStore, refreshStore, options.storage);
-    return tokenResponse(issued, record.scope);
-  });
-}
-
-async function exchangeRefreshToken(
-  body: Record<string, unknown>,
-  base: string,
-  options: OAuthTokenExchangeOptions,
-): Promise<Response> {
-  const refreshToken = String(body.refresh_token ?? "");
-  if (!/^mcp_rt_[A-Za-z0-9_-]{43}$/.test(refreshToken)) return json({ error: "invalid_grant" }, 400);
-  return options.withLock(async () => {
-    const oauthStore = await options.loadOAuthStore();
-    const refreshStore = await loadOAuthRefreshStore(oauthStore, options.storage);
-    const refreshKey = `sha256:${await sha256Hex(refreshToken)}`;
-    const record = refreshStore.tokens[refreshKey];
-    if (!record) {
-      const consumed = refreshStore.consumed[refreshKey];
-      if (consumed && consumed.expires_at > Math.floor(Date.now() / 1000)) {
-        revokeOAuthRefreshFamily(oauthStore, refreshStore, consumed.family_id, consumed.expires_at);
-        await saveOAuthStores(oauthStore, refreshStore, options.storage);
+  let stage: AuthorizationCodeStage = "lock";
+  try {
+    return await options.withLock(async () => {
+      stage = "load_oauth";
+      const oauthStore = await options.loadOAuthStore();
+      stage = "load_refresh";
+      const refreshStore = await loadOAuthRefreshStore(oauthStore, options.storage);
+      const record = oauthStore.codes[code];
+      if (!record) return json({ error: "invalid_grant" }, 400);
+      if (String(body.client_id ?? "") !== record.client_id || String(body.redirect_uri ?? "") !== record.redirect_uri) {
+        return json({ error: "invalid_grant", error_description: "client or redirect mismatch" }, 400);
       }
-      return json({ error: "invalid_grant" }, 400);
-    }
-    if (refreshStore.revoked_families[record.family_id]) {
-      delete refreshStore.tokens[refreshKey];
-      await options.storage.put(OAUTH_REFRESH_STORE_KEY, refreshStore);
-      return json({ error: "invalid_grant" }, 400);
-    }
-    if (String(body.client_id ?? "") !== record.client_id) {
-      return json({ error: "invalid_grant", error_description: "client mismatch" }, 400);
-    }
-    if (String(body.resource ?? record.resource) !== record.resource || record.resource !== `${base}/mcp`) {
-      return json({ error: "invalid_target", error_description: "resource mismatch" }, 400);
-    }
-    if (body.scope !== undefined && normalizeOAuthScope(body.scope, options.serverName) !== record.scope) {
-      return json({ error: "invalid_scope" }, 400);
-    }
-    if (!options.tokenVersion) {
-      throw new HttpError(503, "server_error", "OAuth token version is not configured");
-    }
-    const account = oauthStore.accounts[record.account_id];
-    const client = oauthStore.clients[record.client_id];
-    if (
-      !record.version
-      || !(await safeEqual(record.version, options.tokenVersion))
-      || !account
-      || !account.active
-      || account.version !== record.account_version
-      || account.role !== record.role
-      || !client
-    ) {
-      delete refreshStore.tokens[refreshKey];
-      await options.storage.put(OAUTH_REFRESH_STORE_KEY, refreshStore);
-      return json({ error: "invalid_grant" }, 400);
-    }
-
-    let issued: IssuedTokenPair;
-    try {
-      issued = await issueTokenPair(oauthStore, refreshStore, record, options.tokenVersion);
-    } catch (error) {
-      if (error instanceof HttpError && error.code === "invalid_grant") {
-        delete refreshStore.tokens[refreshKey];
-        await options.storage.put(OAUTH_REFRESH_STORE_KEY, refreshStore);
-        return json({ error: "invalid_grant" }, 400);
+      if (String(body.resource ?? record.resource) !== record.resource || record.resource !== `${base}/mcp`) {
+        return json({ error: "invalid_target", error_description: "resource mismatch" }, 400);
       }
-      throw error;
-    }
-    delete refreshStore.tokens[refreshKey];
-    recordConsumedRefreshToken(
-      refreshStore,
-      refreshKey,
-      record.family_id,
-      record.family_expires_at,
-      Math.floor(Date.now() / 1000),
-    );
-    client.last_used_at = Math.floor(Date.now() / 1000);
-    await saveOAuthStores(oauthStore, refreshStore, options.storage);
-    return tokenResponse(issued, record.scope);
-  });
-}
-
-async function issueTokenPair(
-  oauthStore: OAuthStore,
-  refreshStore: OAuthRefreshStore,
-  source: OAuthCode | OAuthRefreshToken,
-  tokenVersion: string,
-): Promise<IssuedTokenPair> {
-  if (!tokenVersion) throw new HttpError(503, "server_error", "OAuth token version is not configured");
-  const now = Math.floor(Date.now() / 1000);
-  const familyId = "family_id" in source && source.family_id ? source.family_id : randomToken("mcp_family");
-  const familyExpiresAt = "family_expires_at" in source && source.family_expires_at
-    ? source.family_expires_at
-    : now + REFRESH_TOKEN_FAMILY_TTL_SECONDS;
-  if (familyExpiresAt <= now) throw new HttpError(400, "invalid_grant", "refresh-token family expired");
-  const accessToken = randomToken("mcp_at");
-  const refreshToken = randomToken("mcp_rt");
-  const common = {
-    client_id: source.client_id,
-    account_id: source.account_id,
-    account_version: source.account_version,
-    role: source.role,
-    scope: source.scope,
-    resource: source.resource,
-    version: tokenVersion,
-    family_id: familyId,
-  };
-  oauthStore.tokens[`sha256:${await sha256Hex(accessToken)}`] = {
-    ...common,
-    expires_at: now + ACCESS_TOKEN_TTL_SECONDS,
-  };
-  refreshStore.tokens[`sha256:${await sha256Hex(refreshToken)}`] = {
-    ...common,
-    family_id: familyId,
-    family_expires_at: familyExpiresAt,
-    issued_at: now,
-    expires_at: Math.min(now + REFRESH_TOKEN_IDLE_TTL_SECONDS, familyExpiresAt),
-  };
-  pruneClientRecordByExpiry(oauthStore.tokens, source.client_id, MAX_ACCESS_TOKENS_PER_CLIENT);
-  pruneRecordByExpiry(oauthStore.tokens, MAX_ACCESS_TOKENS);
-  pruneClientRecordByExpiry(refreshStore.tokens, source.client_id, MAX_REFRESH_TOKENS_PER_CLIENT);
-  pruneRecordByExpiry(refreshStore.tokens, MAX_REFRESH_TOKENS);
-  return { accessToken, refreshToken };
-}
-
-function tokenResponse(issued: IssuedTokenPair, scope: string): Response {
-  return json({
-    access_token: issued.accessToken,
-    refresh_token: issued.refreshToken,
-    token_type: "Bearer",
-    expires_in: ACCESS_TOKEN_TTL_SECONDS,
-    scope,
-  });
-}
-
-async function saveOAuthStores(
-  oauthStore: OAuthStore,
-  refreshStore: OAuthRefreshStore,
-  storage: DurableObjectStorage,
-): Promise<void> {
-  await storage.put({ oauth: oauthStore, [OAUTH_REFRESH_STORE_KEY]: refreshStore });
+      if (normalizeOAuthScope(record.scope, options.serverName) !== record.scope) {
+        return json({ error: "invalid_grant", error_description: "stored scope is invalid" }, 400);
+      }
+      stage = "pkce";
+      if (!(await safeEqual(await pkceS256(verifier), record.code_challenge))) {
+        return json({ error: "invalid_grant", error_description: "invalid code_verifier" }, 400);
+      }
+      const client = oauthStore.clients[record.client_id];
+      if (!client) return json({ error: "invalid_grant", error_description: "unknown client" }, 400);
+      if (dpop && !(await consumeDpopProof(options.storage, dpop))) return json({ error: "invalid_dpop_proof" }, 400);
+      stage = "issue";
+      const issued = await issueTokenPair(oauthStore, refreshStore, record, options.tokenVersion, dpop?.jkt);
+      delete oauthStore.codes[code];
+      client.last_used_at = Math.floor(Date.now() / 1000);
+      stage = "persist";
+      await saveOAuthStores(oauthStore, refreshStore, options.storage);
+      stage = "response";
+      return tokenResponse(issued, record.scope, dpop?.jkt);
+    });
+  } catch (error) {
+    if (error instanceof HttpError || (error instanceof Error && error.name.startsWith("oauth_store_persist_"))) throw error;
+    const staged = new Error("OAuth authorization-code exchange failed", { cause: error });
+    staged.name = `oauth_token_stage_${stage}`;
+    throw staged;
+  }
 }

package/src/worker/observability.ts

@@ -1,12 +1,24 @@
+import { sanitizePortableLogText } from "../shared/log-redaction.mjs";
+
 const MAX_ERROR_CODES = 64;
 const MAX_TOOLS = 128;
 const SENSITIVE_FIELD = /(?:authorization|cookie|credential|password|secret|token|verifier|private[_-]?key)/i;
 
+export type DaemonTerminalResultDisposition =
+  | "committed"
+  | "owner_missing_acknowledged"
+  | "stale_connection_rejected";
+
 export class WorkerObservability {
   private readonly startedAt = performance.now();
   private readonly requests = { total: 0, successful: 0, client_error: 0, server_error: 0 };
-  private readonly calls = { started: 0, completed: 0, failed: 0, cancelled: 0, timed_out: 0, unmatched_results: 0 };
+  private readonly calls = { started: 0, completed: 0, failed: 0, cancelled: 0, timed_out: 0 };
+  private readonly terminalResults = {
+    committed: 0, owner_missing_acknowledged: 0, stale_connection_rejected: 0,
+  };
   private readonly sockets = { candidates: 0, authenticated: 0, ready: 0, disconnected: 0, protocol_errors: 0 };
+  private readonly oauthRefresh = { rotated: 0, retry_issued: 0, retry_exhausted: 0, family_revoked: 0, rejected: 0 };
+  private readonly runtimeAlarm = { sets: 0, deletes: 0, noops: 0 };
   private readonly errors = new Map<string, number>();
   private readonly tools = new Map<string, { started: number; completed: number; failed: number; active: number }>();
 
@@ -39,7 +51,10 @@ export class WorkerObservability {
     this.incrementError(code);
   }
 
-  unmatchedResult(): void { this.calls.unmatched_results += 1; }
+  daemonTerminalResult(disposition: DaemonTerminalResultDisposition): void {
+    this.terminalResults[disposition] += 1;
+  }
+  recordError(code: string): void { this.incrementError(code); }
 
   socketCandidate(): void { this.sockets.candidates += 1; }
   socketAuthenticated(): void { this.sockets.authenticated += 1; }
@@ -50,12 +65,30 @@ export class WorkerObservability {
     this.incrementError(code || "protocol_error");
   }
 
+  oauthRefreshEvent(event: "rotated" | "retry_issued" | "retry_exhausted" | "family_revoked" | "rejected"): void {
+    this.oauthRefresh[event] += 1;
+  }
+
+  runtimeAlarmMutation(action: "set" | "delete" | "noop"): void {
+    if (action === "set") this.runtimeAlarm.sets += 1;
+    else if (action === "delete") this.runtimeAlarm.deletes += 1;
+    else this.runtimeAlarm.noops += 1;
+  }
+
   snapshot(): Record<string, unknown> {
     return {
       uptime_ms: Math.max(0, performance.now() - this.startedAt),
+      metric_scope: {
+        lifecycle: "current_worker_isolate",
+        request_scoped_calls: true,
+        counters_may_not_balance_across_isolate_restarts: true,
+      },
       requests: { ...this.requests },
       calls: { ...this.calls },
+      terminal_results: { ...this.terminalResults },
       sockets: { ...this.sockets },
+      oauth_refresh: { ...this.oauthRefresh },
+      runtime_alarm: { ...this.runtimeAlarm },
       errors: Object.fromEntries([...this.errors.entries()].sort(([left], [right]) => left.localeCompare(right))),
       tools: Object.fromEntries([...this.tools.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([name, metric]) => [name, { ...metric }])),
     };
@@ -63,11 +96,11 @@ export class WorkerObservability {
 
   event(level: "info" | "warn" | "error", event: string, fields: Record<string, unknown> = {}): void {
     const entry = {
+      ...sanitizeFields(fields),
       timestamp: new Date().toISOString(),
       level,
       component: "worker",
       event: sanitizeName(event),
-      ...sanitizeFields(fields),
     };
     const text = JSON.stringify(entry);
     if (level === "error") console.error(text);
@@ -99,7 +132,7 @@ function sanitizeName(value: unknown): string {
 }
 
 function sanitizeFields(fields: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
+  const out = Object.create(null) as Record<string, unknown>;
   for (const [key, value] of Object.entries(fields).slice(0, 32)) {
     const safeKey = sanitizeName(key);
     if (!safeKey) continue;
@@ -108,7 +141,7 @@ function sanitizeFields(fields: Record<string, unknown>): Record<string, unknown
       continue;
     }
     if (typeof value === "boolean" || typeof value === "number" || value === null) out[safeKey] = value;
-    else if (typeof value === "string") out[safeKey] = value.replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, 256);
+    else if (typeof value === "string") out[safeKey] = sanitizePortableLogText(value, { maxChars: 256 });
   }
   return out;
 }

package/src/worker/pending-admission.ts

@@ -0,0 +1,15 @@
+export class PendingAdmissionGate {
+  private tail: Promise<void> = Promise.resolve();
+
+  async run<T>(operation: () => T | Promise<T>): Promise<T> {
+    let release: () => void = () => {};
+    const predecessor = this.tail;
+    this.tail = new Promise<void>((resolve) => { release = resolve; });
+    await predecessor;
+    try {
+      return await operation();
+    } finally {
+      release();
+    }
+  }
+}

package/src/worker/pending-call-capacity.ts

@@ -0,0 +1,108 @@
+import {
+  CONTROL_PLANE_TOOL_NAMES,
+  toolCallAdmission,
+  toolCallCapacityConfig,
+  toolCallCapacityUsage,
+  type ToolCallAdmission,
+  type ToolCallCapacityConfig,
+} from "../shared/tool-call-capacity.mjs";
+import { WorkerToolError } from "./errors.ts";
+import type { PendingCallRecord } from "./pending-call-contract.ts";
+
+export { CONTROL_PLANE_TOOL_NAMES };
+
+export const MAX_PENDING_CALLS = 32;
+export const RESERVED_CONTROL_PENDING_CALLS = 2;
+export const WORKER_PENDING_CALL_CAPACITY = toolCallCapacityConfig(
+  MAX_PENDING_CALLS,
+  RESERVED_CONTROL_PENDING_CALLS,
+  CONTROL_PLANE_TOOL_NAMES,
+);
+export const WORKER_PENDING_REGISTRY_OPTIONS = Object.freeze({
+  reservedCapacity: RESERVED_CONTROL_PENDING_CALLS,
+  reservedTools: CONTROL_PLANE_TOOL_NAMES,
+});
+
+
+export type PendingRegistrySnapshot = PendingCapacitySnapshot & {
+  detached: number;
+  request_keys: number;
+  maximum: number;
+  ordinary_capacity: number;
+  reserved_capacity: number;
+  active_reserved: number;
+  active_ordinary: number;
+  oldest_ms: number;
+};
+
+export function pendingRegistrySnapshot(
+  records: Iterable<PendingCallRecord>,
+  requestKeyCount: number,
+  now: number,
+  config: ToolCallCapacityConfig,
+): PendingRegistrySnapshot {
+  const byTool = Object.create(null) as Record<string, number>;
+  let active = 0;
+  let detached = 0;
+  let oldestMs = 0;
+  for (const record of records) {
+    active += 1;
+    byTool[record.tool] = (byTool[record.tool] ?? 0) + 1;
+    detached += Number(!record.socket);
+    oldestMs = Math.max(oldestMs, now - record.startedAt);
+  }
+  const usage = toolCallCapacityUsage({ active, byTool }, config);
+  return {
+    active,
+    detached,
+    request_keys: requestKeyCount,
+    maximum: usage.maximum,
+    ordinary_capacity: usage.ordinaryMaximum,
+    reserved_capacity: usage.reserved,
+    active_reserved: usage.activeReserved,
+    active_ordinary: usage.activeOrdinary,
+    oldest_ms: oldestMs,
+    by_tool: byTool,
+  };
+}
+
+export type PendingCapacitySnapshot = {
+  active: number;
+  by_tool: Record<string, number>;
+};
+
+export function pendingCallAdmission(
+  pending: PendingCapacitySnapshot,
+  tool: string,
+  config: ToolCallCapacityConfig = WORKER_PENDING_CALL_CAPACITY,
+): ToolCallAdmission {
+  return toolCallAdmission(pending, config, tool);
+}
+
+export function pendingCapacityProjection(
+  pending: PendingRegistrySnapshot,
+  preDispatch: PendingCapacitySnapshot,
+): PendingRegistrySnapshot & Record<string, unknown> {
+  const byTool = { ...pending.by_tool };
+  for (const [tool, count] of Object.entries(preDispatch.by_tool)) byTool[tool] = (byTool[tool] ?? 0) + count;
+  const usage = toolCallCapacityUsage({ active: pending.active + preDispatch.active, byTool }, WORKER_PENDING_CALL_CAPACITY);
+  return Object.freeze({
+    ...pending,
+    pre_dispatch_waiters: preDispatch.active,
+    capacity_active: usage.active,
+    capacity_active_ordinary: usage.activeOrdinary,
+    capacity_active_reserved: usage.activeReserved,
+  });
+}
+
+export function assertWorkerPendingCallAdmission(
+  pending: PendingCapacitySnapshot,
+  tool: string,
+): void {
+  const decision = pendingCallAdmission(pending, tool);
+  if (decision.allowed) return;
+  const message = decision.reason === "ordinary_capacity"
+    ? `ordinary daemon-call capacity reached (${decision.ordinaryMaximum}); control-plane capacity is reserved for diagnosis and recovery`
+    : "too many concurrent daemon tool calls";
+  throw new WorkerToolError("limit_exceeded", message, true);
+}