@moretea-labs/forge 1.6.0 → 1.7.0

package/src/cli/mcp/auth.ts

@@ -25,7 +25,7 @@ export interface McpLocalConfig {
     localEndpoint?: string;
   };
   profile?: string;
-  toolset?: 'core' | 'advanced' | 'full';
+  toolset?: 'facade' | 'core' | 'advanced' | 'full';
   /** Compatibility marker retained for previously persisted toolset choices. */
   toolsetExplicit?: boolean;
   accessMode?: AccessMode;
@@ -88,7 +88,7 @@ export interface McpRuntimeState {
     forgeVersion?: string;
     toolSurfaceFingerprint?: string;
     runtimeToolSurfaceFingerprint?: string;
-    toolset?: 'core' | 'advanced' | 'full';
+    toolset?: 'facade' | 'core' | 'advanced' | 'full';
     configuredAccessMode?: AccessMode;
     effectiveAccessMode?: AccessMode;
     effectiveToolset?: McpToolset;
@@ -131,7 +131,7 @@ export interface McpRuntimeState {
   }>;
 }
 
-export type McpHttpAuthMode = 'oauth' | 'bearer';
+export type McpHttpAuthMode = 'oauth' | 'bearer' | 'none';
 
 export function mcpLocalConfigPath(repoRoot: string): string {
   return join(repoRoot, '.forge', 'mcp.local.json');
@@ -356,8 +356,8 @@ export function syncMcpControllerHomeBearerToken(
 
 export function parseMcpHttpAuthMode(value: string | undefined): McpHttpAuthMode {
   const mode = (value ?? 'oauth').trim().toLowerCase();
-  if (mode === 'oauth' || mode === 'bearer') return mode;
-  throw new Error(`invalid --auth "${value}" (expected: oauth, bearer)`);
+  if (mode === 'oauth' || mode === 'bearer' || mode === 'none') return mode;
+  throw new Error(`invalid --auth "${value}" (expected: oauth, bearer, none)`);
 }
 
 export function readMcpOAuthPassphrase(repoRoot: string): string | null {

package/src/cli/mcp/instructions.ts

@@ -10,10 +10,11 @@ export function mcpServerInstructions(profile: McpProfileName): string {
     return [
       ...common,
       'Use the shortest valid execution path. Investigation or parallelism alone must not create durable Work, Issues, Plans, Agents, isolation, or worktrees; escalate only for actual recovery, dependency, risk, scope, external-effect, or long-running requirements.',
-      'For bounded implementation, use rh_context(operation=search, retrieval_mode=implementation) once as the default code retrieval router when the exact path is unknown. Its current raw snippets and file SHA identities are valid implementation evidence; ChatGPT decides semantic sufficiency and should request wider exact ranges only when impact ambiguity, truncation, drift, or an expansion signal can materially change the edit. For cross-cutting state/time/schema/cache/API/event/concurrency changes, ChatGPT should select relevant impact_domains in that first search so Forge expands those evidence dimensions mechanically in the same call; Forge never infers that the selected domains are semantically complete. Use retrieval_mode=plan|debug|review when the task intentionally needs a broader evidence surface. Do not fall back to shell grep unless retrieval is unavailable or raw Git semantics are explicitly needed. The low-level search_repository handler is compatibility/internal surface, not a second default search path. Prefer repository_command_execute for ordinary local Git and shell operations, repository_safe_patch_apply for bounded source changes, and rh_work only when the task genuinely requires durable orchestration.',
+      'For bounded implementation, start with rh_context(operation=search, retrieval_mode=implementation) as the default code retrieval router when the exact path is unknown, then repeat it with exact paths, symbols, tests, relationships, or impact domains whenever more evidence can materially improve correctness. Its current raw snippets and file SHA identities are valid implementation evidence; ChatGPT alone decides semantic sufficiency. For cross-cutting state/time/schema/cache/API/event/concurrency changes, ChatGPT should select relevant impact_domains so Forge expands those evidence dimensions mechanically; Forge never infers that the selected domains are semantically complete. Use retrieval_mode=plan|debug|review when the task intentionally needs a broader evidence surface. Do not fall back to shell grep unless retrieval is unavailable or raw Git semantics are explicitly needed. The low-level search_repository handler is compatibility/internal surface, not a second default search path. Prefer repository_command_execute for ordinary local Git and shell operations, repository_safe_patch_apply for bounded source changes, and rh_work only when the task genuinely requires durable orchestration.',
       'Do not preflight unrelated Git history, prior Work, plugins, permissions, TCC, browser mode, maintenance, or recovery state. Inspect them only when the requested operation depends on them or a real failure points there.',
+      'Minimize mechanically redundant MCP round trips. For an ongoing Forge-controlled task, prefer one rh_status(summary) as the initial controller snapshot: it includes bounded readiness, repository identity, top active Work, active Plans, and pending handoffs. Do not immediately follow it with rh_work(plan_list) or rh_context(list/get) unless the next decision needs details that the snapshot does not contain. Use rh_context(work_id=..., detail_level=summary) for one Work, and request detail/raw or capability hydration only when that extra evidence can change the decision.',
       'Run independent reads, searches, diagnostics, checks, repositories, checkouts, and tasks concurrently by default. Serialize only on a real dependency or Resource Claim conflict, and reuse existing projections, process handles, and check evidence instead of repeating successful observations.',
-      'Validation must be proportional to the change: cheap patch-safety checks belong to every coherent edit batch, focused tests run after that batch is stable, and expensive full-suite checks belong at candidate/release or explicitly high-risk boundaries. When a Direct Edit batch is stable, repository_safe_patch_apply may receive explicit check_ids to start revision-bound validation; omit check_ids during intermediate edits. Long checks return managed Processes: continue independent read/review work, then use validation_only with the returned edit-session/validation ids as the synchronization join instead of polling repeatedly. Do not perform maintenance or deep runtime diagnosis before ordinary work unless execution is actually blocked.',
+      'Validation must be proportional to the change: cheap patch-safety checks belong to every coherent edit batch, focused tests run after that batch is stable, and expensive full-suite checks belong at candidate/release or explicitly high-risk boundaries. When a Direct Edit batch is stable, repository_safe_patch_apply may receive explicit check_ids to start revision-bound validation; omit check_ids during intermediate edits. Long checks return managed Processes: continue independent read/review work. Do not call process_wait while useful independent work remains. Use process_get only when a non-blocking observation can change the next decision; when the exact check result becomes a dependency, attach with process_wait (or validation_only with the returned edit-session/validation ids). An attach is transport-bounded: if it returns a running handle, resume useful work and attach again only at a later real dependency boundary, never as periodic polling. Do not perform maintenance or deep runtime diagnosis before ordinary work unless execution is actually blocked.',
       'repository_safe_patch_apply returns bounded edit-session diff evidence for semantic review. Review that evidence directly instead of issuing a mandatory follow-up diff/status call; expand it only when truncated or semantically ambiguous. After a bounded successful change, finish the requested delivery directly. Avoid additional investigation whose result cannot change implementation or acceptance, and do not invoke hidden atomic compatibility tools merely because they exist in the full profile.',
     ].join(' ');
   }

package/src/cli/mcp/legacy-tool-service.ts

@@ -113,7 +113,6 @@ import type {
 import {
   gitDiff,
   gitSnapshot,
-  readRepositoryRange,
   searchRepository,
 } from "../repository/inspector";
 import {
@@ -1634,29 +1633,6 @@ export function buildMcpToolDefinitions(
         },
         annotations: readOnly,
       },
-      {
-        name: "controller_context_pack",
-        description:
-          "Build a bounded code context pack for a task: relevant files, search-hit line ranges, and raw snippets. This is for scoped investigation, not blind implementation.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            description: { type: "string" },
-            issue_id: { type: "string" },
-            task_id: { type: "string" },
-            known_paths: { type: "array", items: { type: "string" } },
-            include_globs: { type: "array", items: { type: "string" } },
-            exclude_globs: { type: "array", items: { type: "string" } },
-            search_terms: { type: "array", items: { type: "string" } },
-            max_files: { type: "number" },
-            max_snippets: { type: "number" },
-            max_chars_per_snippet: { type: "number" },
-            structural_context: { type: "string", enum: ["off", "auto", "required"], description: "Optional CodeGraph structural context. Defaults to off so ordinary Direct work pays no graph startup cost." },
-          },
-          additionalProperties: false,
-        },
-        annotations: readOnly,
-      },
       {
         name: "quick_agent_session",
         description:
@@ -1807,22 +1783,6 @@ export function buildMcpToolDefinitions(
         },
         annotations: readOnly,
       },
-      {
-        name: "read_repository_file",
-        description:
-          "Read a line range from one policy-readable repository file.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            path: { type: "string" },
-            start_line: { type: "number" },
-            end_line: { type: "number" },
-          },
-          required: ["path"],
-          additionalProperties: false,
-        },
-        annotations: readOnly,
-      },
       {
         name: "get_git_diff",
         description:
@@ -1844,25 +1804,6 @@ export function buildMcpToolDefinitions(
         inputSchema: EMPTY_SCHEMA,
         annotations: readOnly,
       },
-      {
-        name: "run_check",
-        description:
-          "Start one named focused repository check as a Local Job and return immediately; inspect it with get_local_job.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            check_id: { type: "string" },
-            timeout_ms: { type: "number" },
-          },
-          required: ["check_id"],
-          additionalProperties: false,
-        },
-        annotations: {
-          readOnlyHint: false,
-          openWorldHint: false,
-          destructiveHint: false,
-        },
-      },
       {
         name: "list_issues",
         description: "List controller-managed issues and task summaries.",
@@ -3306,28 +3247,6 @@ export async function callMcpTool(
         audit(ctx, name, "ok", args);
         return textResult(payload);
       }
-      case "controller_context_pack": {
-        if (ctx.policy.profile !== "controller")
-          return errorResult(
-            "TOOL_DISABLED",
-            "controller_context_pack requires the controller profile",
-          );
-        const pack = buildControllerContextPack(ctx.repoRoot, ctx.policy, {
-          description: typeof args.description === "string" ? args.description : undefined,
-          issueId: typeof args.issue_id === "string" ? args.issue_id : undefined,
-          taskId: typeof args.task_id === "string" ? args.task_id : undefined,
-          knownPaths: stringList(args.known_paths),
-          includeGlobs: stringList(args.include_globs),
-          excludeGlobs: stringList(args.exclude_globs),
-          searchTerms: stringList(args.search_terms),
-          maxFiles: typeof args.max_files === "number" ? args.max_files : undefined,
-          maxSnippets: typeof args.max_snippets === "number" ? args.max_snippets : undefined,
-          maxCharsPerSnippet: typeof args.max_chars_per_snippet === "number" ? args.max_chars_per_snippet : undefined,
-          structuralContext: args.structural_context === "auto" || args.structural_context === "required" ? args.structural_context : "off",
-        });
-        audit(ctx, name, "ok", args);
-        return textResult(pack);
-      }
       case "controller_context": {
         if (ctx.policy.profile !== "controller")
           return errorResult(
@@ -3563,36 +3482,6 @@ export async function callMcpTool(
         audit(ctx, name, "ok", args);
         return textResult(result);
       }
-      case "read_repository_file": {
-        if (ctx.policy.profile !== "controller")
-          return errorResult(
-            "TOOL_DISABLED",
-            "read_repository_file requires the controller profile",
-          );
-        const path = String(args.path ?? "");
-        const session = ctx.sessionId && ctx.repoId
-          ? {
-            sessionId: ctx.sessionId,
-            repoId: ctx.repoId,
-            checkoutId: ctx.checkoutId ?? ctx.repoId,
-          }
-          : undefined;
-        const result = readRepositoryRange(
-          ctx.repoRoot,
-          ctx.policy,
-          path,
-          typeof args.start_line === "number" ? args.start_line : 1,
-          typeof args.end_line === "number" ? args.end_line : 200,
-          session,
-        );
-        const redacted = redactMcpText(result.content);
-        audit(ctx, name, "ok", args, result.path);
-        return textResult({
-          ...result,
-          content: redacted.text,
-          redactions: redacted.redactions,
-        });
-      }
       case "get_git_diff": {
         if (ctx.policy.profile !== "controller")
           return errorResult(
@@ -3640,84 +3529,6 @@ export async function callMcpTool(
         audit(ctx, name, "ok", args);
         return textResult({ checks });
       }
-      case "run_check": {
-        if (ctx.policy.profile !== "controller")
-          return errorResult(
-            "TOOL_DISABLED",
-            "run_check requires the controller profile",
-          );
-        // Prefer Unified Process Runtime for ordinary checks. Multi-phase and
-        // release checks require an explicit external Controller instead.
-        const checkId = String(args.check_id ?? "").trim();
-        const forceDurable = args.force_durable === true
-          || args.apply_mode === "async"
-          || args.mode === "durable";
-        if (!forceDurable && checkId) {
-          try {
-            const { checkRequiresDurableWorkflow, runCheckViaProcessRuntime } = await import(
-              "../../runtime/execution/process-runtime"
-            );
-            const { resolveRepoPreferredControllerHome } = await import("../repositories/controller-home");
-            const { resolveRepositorySelection } = await import("../repositories/registry");
-            if (!checkRequiresDurableWorkflow(checkId)) {
-              const controllerHome = resolveRepoPreferredControllerHome(ctx.repoRoot);
-              const repository = resolveRepositorySelection({
-                explicitPath: ctx.repoRoot,
-                controllerHome,
-                allowSoleRepository: true,
-              });
-              if (repository) {
-                const facade = await runCheckViaProcessRuntime({
-                  controllerHome,
-                  repoId: repository.repoId,
-                  checkoutId: repository.activeCheckoutId,
-                  repoRoot: repository.canonicalRoot,
-                  checkId,
-                  timeoutMs: typeof args.timeout_ms === "number" ? args.timeout_ms : undefined,
-                  requestId: typeof args.request_id === "string" ? args.request_id.trim() || undefined : undefined,
-                  executionIdentity: {
-                    schemaVersion: 1,
-                    repositoryId: repository.repoId,
-                    checkoutId: repository.activeCheckoutId,
-                    canonicalRoot: repository.canonicalRoot,
-                  },
-                });
-                if (facade.mode !== "durable" && facade.process) {
-                  audit(ctx, name, "ok", args);
-                  return textResult({
-                    mode: facade.mode,
-                    path: facade.mode === "direct" ? "process_direct" : "process_managed",
-                    checkId: facade.checkId,
-                    processId: facade.process.processId,
-                    status: facade.process.status,
-                    completed: facade.process.completed === true,
-                    ok: facade.process.ok,
-                    exitCode: facade.process.exitCode,
-                    timedOut: facade.process.timedOut,
-                    stdout: facade.process.stdout,
-                    stderr: facade.process.stderr,
-                    durableSideEffects: facade.durableSideEffects,
-                    next: facade.process.completed
-                      ? "Check finished on Process Runtime without LocalBridgeJob / ExecutionJob / Worker."
-                      : `Managed process ${facade.process.processId} still running; poll process_get / process_wait / process_logs.`,
-                  });
-                }
-              }
-            }
-          } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const code = message.includes(":") ? message.slice(0, message.indexOf(":")) : "PROCESS_RUNTIME_FAILED";
-            audit(ctx, name, "failed", args, undefined, message);
-            return errorResult(code, message, { checkId });
-          }
-        }
-        audit(ctx, name, "blocked", args);
-        return errorResult(
-          "PROCESS_RUNTIME_REQUIRED",
-          "This check cannot create a Local Bridge Job. Run a registered ordinary check through Process Runtime or use external Controller handling for durable checks.",
-          { checkId },
-        );
-      }
       case "list_issues": {
         if (ctx.policy.profile !== "controller")
           return errorResult(

package/src/cli/mcp/multi-repository.ts

@@ -87,8 +87,8 @@ export function parseMcpToolset(value: unknown, profile: string): McpToolset {
   if (profile !== 'controller') return 'full';
   const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
   if (!normalized) return 'advanced';
-  if (normalized === 'core' || normalized === 'advanced' || normalized === 'full') return normalized;
-  throw new Error(`invalid MCP toolset "${String(value)}" (expected: core, advanced, or full)`);
+  if (normalized === 'facade' || normalized === 'core' || normalized === 'advanced' || normalized === 'full') return normalized;
+  throw new Error(`invalid MCP toolset "${String(value)}" (expected: facade, core, advanced, or full)`);
 }
 
 function repositoryForExplicitPath(path: string, controllerHome: string): RepositoryRecord | undefined {
@@ -295,13 +295,24 @@ export function repositoryScopedToolArgs(
   input: Record<string, unknown>,
   repository: RepositoryRecord,
 ): Record<string, unknown> {
-  // Preserve resolved repository/checkout identity for every downstream call.
-  // Deleting these fields forced re-resolution and allowed silent route drift.
+  // Preserve resolved repository identity for every downstream call. Exact
+  // claimed Work calls are the one exception for checkout injection: when the
+  // caller omitted checkout_id, repository tools must resolve the Work-owned
+  // checkout after validating the authenticated principal instead of inheriting
+  // the repository's currently active checkout.
+  const workOwnedCheckoutResolution = [
+    'repository_command_preview',
+    'repository_command_execute',
+    'repository_safe_patch_apply',
+  ].includes(name)
+    && typeof input.work_id === 'string'
+    && input.work_id.trim().length > 0
+    && !(typeof input.checkout_id === 'string' && input.checkout_id.trim().length > 0);
   const args: Record<string, unknown> = {
     ...input,
     repo_id: repository.repoId,
-    checkout_id: repository.activeCheckoutId,
   };
+  if (!workOwnedCheckoutResolution) args.checkout_id = repository.activeCheckoutId;
 
   const github = repository.github;
   const githubRepo = github ? `${github.owner}/${github.repo}` : undefined;

package/src/cli/mcp/oauth.ts

@@ -1,5 +1,16 @@
 import { randomUUID } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'fs';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'fs';
 import { dirname } from 'path';
 import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js';
 import { InvalidGrantError, InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
@@ -25,6 +36,20 @@ function issueToken(): string {
   return randomUUID();
 }
 
+function fsyncFile(path: string): void {
+  const fd = openSync(path, 'r');
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function fsyncDirectory(path: string): void {
+  try {
+    const fd = openSync(path, 'r');
+    try { fsyncSync(fd); } finally { closeSync(fd); }
+  } catch {
+    // Directory fsync is unavailable on some supported platforms/filesystems.
+  }
+}
+
 export class McpOAuthTokenStore implements OAuthRegisteredClientsStore {
   private accessTokens = new Map<string, AuthInfo>();
   private refreshTokens = new Map<string, string>();
@@ -33,8 +58,12 @@ export class McpOAuthTokenStore implements OAuthRegisteredClientsStore {
   constructor(private readonly path: string, private readonly fallbackPaths: string[] = []) {}
 
   load(): void {
+    this.accessTokens.clear();
+    this.refreshTokens.clear();
+    this.clients.clear();
     let loaded = false;
     let mergedFallback = false;
+    let primaryCorrupt = false;
     for (const [index, path] of [this.path, ...this.fallbackPaths].entries()) {
       if (!existsSync(path)) continue;
       try {
@@ -59,22 +88,35 @@ export class McpOAuthTokenStore implements OAuthRegisteredClientsStore {
         }
         loaded = true;
       } catch (_error) {
-        // Corrupt local auth state should not prevent starting the server.
+        if (index === 0) primaryCorrupt = true;
       }
     }
-    if (loaded && mergedFallback) this.flush();
+    if (primaryCorrupt && !loaded) {
+      throw new Error('MCP_OAUTH_STORE_CORRUPT: primary OAuth state is unreadable and no valid fallback is available');
+    }
+    if (loaded && (mergedFallback || primaryCorrupt)) this.flush();
   }
 
   flush(): void {
-    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
-    chmodSync(dirname(this.path), 0o700);
+    const directory = dirname(this.path);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    chmodSync(directory, 0o700);
     const data: TokenData = {
       accessTokens: Object.fromEntries(this.accessTokens),
       refreshTokens: Object.fromEntries(this.refreshTokens),
       clients: Object.fromEntries(this.clients),
     };
-    writeFileSync(this.path, `${JSON.stringify(data, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
-    chmodSync(this.path, 0o600);
+    const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temporary, `${JSON.stringify(data, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+      chmodSync(temporary, 0o600);
+      fsyncFile(temporary);
+      renameSync(temporary, this.path);
+      chmodSync(this.path, 0o600);
+      fsyncDirectory(directory);
+    } finally {
+      rmSync(temporary, { force: true });
+    }
   }
 
   getClient(clientId: string): OAuthClientInformationFull | undefined {
@@ -127,10 +169,115 @@ export class McpOAuthTokenStore implements OAuthRegisteredClientsStore {
     }
     return undefined;
   }
+
+  setTokenPair(accessToken: string, info: AuthInfo, refreshToken: string): void {
+    this.accessTokens.set(accessToken, info);
+    this.refreshTokens.set(refreshToken, accessToken);
+    this.flush();
+  }
+
+  rotateRefreshToken(
+    previousRefreshToken: string,
+    nextRefreshToken: string,
+    accessToken: string,
+    info: AuthInfo,
+  ): void {
+    this.refreshTokens.delete(previousRefreshToken);
+    this.accessTokens.set(accessToken, info);
+    this.refreshTokens.set(nextRefreshToken, accessToken);
+    this.flush();
+  }
+
+  revokeToken(token: string): void {
+    const linkedAccessToken = this.refreshTokens.get(token);
+    if (linkedAccessToken) {
+      this.refreshTokens.delete(token);
+      this.accessTokens.delete(linkedAccessToken);
+      for (const [refreshToken, accessToken] of this.refreshTokens) {
+        if (accessToken === linkedAccessToken) this.refreshTokens.delete(refreshToken);
+      }
+      this.flush();
+      return;
+    }
+
+    this.accessTokens.delete(token);
+    for (const [refreshToken, accessToken] of this.refreshTokens) {
+      if (accessToken === token) this.refreshTokens.delete(refreshToken);
+    }
+    this.flush();
+  }
 }
 
-export function createMcpOAuthProvider(store: McpOAuthTokenStore): OAuthServerProvider {
-  const authCodes = new Map<string, { challenge: string; clientId: string }>();
+interface PendingAuthorizationCode {
+  challenge: string;
+  clientId: string;
+  issuedAt: number;
+  expiresAt: number;
+}
+
+export interface McpOAuthProviderOptions {
+  now?: () => number;
+  authorizationCodeTtlSeconds?: number;
+  maxPendingAuthorizationCodes?: number;
+  maxPendingAuthorizationCodesPerClient?: number;
+}
+
+const DEFAULT_AUTHORIZATION_CODE_TTL_SECONDS = 10 * 60;
+const DEFAULT_MAX_PENDING_AUTHORIZATION_CODES = 512;
+const DEFAULT_MAX_PENDING_AUTHORIZATION_CODES_PER_CLIENT = 32;
+
+export function createMcpOAuthProvider(
+  store: McpOAuthTokenStore,
+  options: McpOAuthProviderOptions = {},
+): OAuthServerProvider {
+  const authCodes = new Map<string, PendingAuthorizationCode>();
+  const currentTime = options.now ?? nowSeconds;
+  const ttlSeconds = Math.max(30, Math.trunc(options.authorizationCodeTtlSeconds ?? DEFAULT_AUTHORIZATION_CODE_TTL_SECONDS));
+  const globalLimit = Math.max(8, Math.trunc(options.maxPendingAuthorizationCodes ?? DEFAULT_MAX_PENDING_AUTHORIZATION_CODES));
+  const clientLimit = Math.max(2, Math.min(globalLimit, Math.trunc(
+    options.maxPendingAuthorizationCodesPerClient ?? DEFAULT_MAX_PENDING_AUTHORIZATION_CODES_PER_CLIENT,
+  )));
+
+  const purgeExpiredCodes = (now = currentTime()): void => {
+    for (const [code, pending] of authCodes) {
+      if (pending.expiresAt <= now) authCodes.delete(code);
+    }
+  };
+
+  const evictOldest = (predicate: (entry: PendingAuthorizationCode) => boolean): boolean => {
+    let oldest: { code: string; issuedAt: number } | undefined;
+    for (const [code, pending] of authCodes) {
+      if (!predicate(pending)) continue;
+      if (!oldest || pending.issuedAt < oldest.issuedAt) oldest = { code, issuedAt: pending.issuedAt };
+    }
+    if (!oldest) return false;
+    authCodes.delete(oldest.code);
+    return true;
+  };
+
+  const reserveAuthorizationCodeCapacity = (clientId: string, now: number): void => {
+    purgeExpiredCodes(now);
+    while ([...authCodes.values()].filter((pending) => pending.clientId === clientId).length >= clientLimit) {
+      if (!evictOldest((pending) => pending.clientId === clientId)) break;
+    }
+    while (authCodes.size >= globalLimit) {
+      if (!evictOldest(() => true)) break;
+    }
+  };
+
+  const pendingAuthorizationCode = (
+    client: OAuthClientInformationFull,
+    authorizationCode: string,
+  ): PendingAuthorizationCode => {
+    const now = currentTime();
+    purgeExpiredCodes(now);
+    const stored = authCodes.get(authorizationCode);
+    if (!stored || stored.clientId !== client.client_id || stored.expiresAt <= now) {
+      if (stored?.expiresAt !== undefined && stored.expiresAt <= now) authCodes.delete(authorizationCode);
+      throw new InvalidGrantError('Invalid authorization code');
+    }
+    return stored;
+  };
 
   return {
     get clientsStore(): OAuthRegisteredClientsStore {
@@ -138,10 +285,14 @@ export function createMcpOAuthProvider(store: McpOAuthTokenStore): OAuthServerPr
     },
 
     async authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res): Promise<void> {
+      const now = currentTime();
+      reserveAuthorizationCodeCapacity(client.client_id, now);
       const code = issueToken();
       authCodes.set(code, {
         challenge: params.codeChallenge,
         clientId: client.client_id,
+        issuedAt: now,
+        expiresAt: now + ttlSeconds,
       });
       const redirectUrl = new URL(params.redirectUri);
       redirectUrl.searchParams.set('code', code);
@@ -149,10 +300,8 @@ export function createMcpOAuthProvider(store: McpOAuthTokenStore): OAuthServerPr
       res.redirect(302, redirectUrl.toString());
     },
 
-    async challengeForAuthorizationCode(_client: OAuthClientInformationFull, authorizationCode: string): Promise<string> {
-      const stored = authCodes.get(authorizationCode);
-      if (!stored) throw new InvalidGrantError('Invalid authorization code');
-      return stored.challenge;
+    async challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string> {
+      return pendingAuthorizationCode(client, authorizationCode).challenge;
     },
 
     async exchangeAuthorizationCode(
@@ -160,22 +309,21 @@ export function createMcpOAuthProvider(store: McpOAuthTokenStore): OAuthServerPr
       authorizationCode: string,
       _codeVerifier?: string,
     ): Promise<OAuthTokens> {
-      const stored = authCodes.get(authorizationCode);
-      if (!stored || stored.clientId !== client.client_id) {
-        throw new InvalidGrantError('Invalid authorization code');
-      }
+      pendingAuthorizationCode(client, authorizationCode);
+      // Delete before issuing credentials. A failed downstream persistence is
+      // retried as a new OAuth flow rather than making an authorization code
+      // replayable after a partial token response.
       authCodes.delete(authorizationCode);
       const accessToken = issueToken();
       const refreshToken = issueToken();
       const expiresIn = 30 * 24 * 60 * 60;
       const expiresAt = nowSeconds() + expiresIn;
-      store.setAccessToken(accessToken, {
+      store.setTokenPair(accessToken, {
         token: accessToken,
         clientId: client.client_id,
         scopes: ['forge'],
         expiresAt,
-      });
-      store.setRefreshToken(refreshToken, accessToken);
+      }, refreshToken);
       return {
         access_token: accessToken,
         token_type: 'Bearer',
@@ -191,11 +339,14 @@ export function createMcpOAuthProvider(store: McpOAuthTokenStore): OAuthServerPr
       if (!accessToken || !existing || existing.clientId !== client.client_id) {
         throw new InvalidGrantError('Invalid refresh token');
       }
-      store.deleteRefreshToken(refreshToken);
       const nextRefreshToken = issueToken();
       const expiresIn = 30 * 24 * 60 * 60;
-      store.setAccessToken(accessToken, { ...existing, expiresAt: nowSeconds() + expiresIn });
-      store.setRefreshToken(nextRefreshToken, accessToken);
+      store.rotateRefreshToken(
+        refreshToken,
+        nextRefreshToken,
+        accessToken,
+        { ...existing, expiresAt: nowSeconds() + expiresIn },
+      );
       return {
         access_token: accessToken,
         token_type: 'Bearer',
@@ -218,9 +369,7 @@ export function createMcpOAuthProvider(store: McpOAuthTokenStore): OAuthServerPr
     },
 
     async revokeToken(_client: OAuthClientInformationFull, request: OAuthTokenRevocationRequest): Promise<void> {
-      store.deleteAccessToken(request.token);
-      const refreshToken = store.findRefreshTokenByAccessToken(request.token);
-      if (refreshToken) store.deleteRefreshToken(refreshToken);
+      store.revokeToken(request.token);
     },
   };
 }