@desplega.ai/agent-swarm 1.92.2 → 1.94.0

package/src/be/skill-sync.ts

@@ -6,85 +6,19 @@
  * so Claude Code, Pi, and Codex discover them natively.
  *
  * This runs on the API side — workers call it via POST /api/skills/sync-filesystem.
+ * The actual FS write logic lives in the worker-safe src/utils/skill-fs-writer.ts
+ * so workers can also call it locally with their own homedir().
  */
 
-import type { Dirent } from "node:fs";
-import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import {
+  type SkillFsEntry,
+  type SkillSyncResult,
+  writeSkillsToFilesystem,
+} from "../utils/skill-fs-writer";
 import { getAgentSkills, getSkillFiles } from "./db";
 
-export interface SkillSyncResult {
-  synced: number;
-  removed: number;
-  errors: string[];
-}
-
-/**
- * Marker file written into every swarm-managed skill directory. Cleanup
- * only ever removes directories that contain this marker, so unrelated
- * personal skills the user installed via the harness's own tooling (e.g.
- * `codex skills add ...` writing into `~/.codex/skills/<name>/`) are left
- * untouched even when the API server shares a HOME with the worker (local
- * dev). See `~/.codex/skills` blast-radius note in PR #555.
- */
-const SWARM_MARKER_FILE = ".swarm-managed";
-
-function reconcileManagedSkillFiles(skillDir: string, currentRelativeFiles: Set<string>): number {
-  if (!existsSync(join(skillDir, SWARM_MARKER_FILE))) return 0;
-
-  let removed = 0;
-
-  const walk = (dir: string, relativeDir = ""): boolean => {
-    let entries: Dirent[];
-    try {
-      entries = readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return false;
-    }
-
-    let hasEntries = false;
-    for (const entry of entries) {
-      const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
-      const fullPath = join(dir, entry.name);
-
-      if (entry.isDirectory()) {
-        const childHasEntries = walk(fullPath, relativePath);
-        if (!childHasEntries) {
-          try {
-            rmSync(fullPath, { recursive: true, force: true });
-          } catch {
-            hasEntries = true;
-          }
-        } else {
-          hasEntries = true;
-        }
-        continue;
-      }
-
-      if (
-        relativePath === "SKILL.md" ||
-        relativePath === SWARM_MARKER_FILE ||
-        currentRelativeFiles.has(relativePath)
-      ) {
-        hasEntries = true;
-        continue;
-      }
-
-      try {
-        rmSync(fullPath, { force: true });
-        removed++;
-      } catch {
-        hasEntries = true;
-      }
-    }
-
-    return hasEntries;
-  };
-
-  walk(skillDir);
-  return removed;
-}
+export type { SkillSyncResult };
 
 /**
  * Sync agent's installed skills to the filesystem.
@@ -92,6 +26,9 @@ function reconcileManagedSkillFiles(skillDir: string, currentRelativeFiles: Set<
  * For simple skills (content in DB): writes SKILL.md to ~/.claude/skills/<name>/
  * For DB-backed complex skills: writes SKILL.md plus bundled skill_files rows.
  * Legacy complex skills without skill_files remain handled by npx in entrypoint.
+ *
+ * API-side adapter: fetches skill data from DB, builds SkillFsEntry[], then
+ * delegates all FS writes to writeSkillsToFilesystem() from skill-fs-writer.ts.
  */
 export function syncSkillsToFilesystem(
   agentId: string,
@@ -100,112 +37,24 @@ export function syncSkillsToFilesystem(
 ): SkillSyncResult {
   const skills = getAgentSkills(agentId);
   const home = homeOverride ?? homedir();
-  const errors: string[] = [];
-  let synced = 0;
-  let removed = 0;
-
-  // Directories to write to
-  const skillDirs: string[] = [];
-  if (harnessType === "claude" || harnessType === "all") {
-    skillDirs.push(join(home, ".claude", "skills"));
-  }
-  if (harnessType === "pi" || harnessType === "all") {
-    skillDirs.push(join(home, ".pi", "agent", "skills"));
-  }
-  if (harnessType === "codex" || harnessType === "all") {
-    skillDirs.push(join(home, ".codex", "skills"));
-  }
-
-  // Ensure base dirs exist
-  for (const dir of skillDirs) {
-    mkdirSync(dir, { recursive: true });
-  }
-
-  // Track which skill names we write (for cleanup)
-  const writtenNames = new Set<string>();
-
-  for (const skill of skills) {
-    if (!skill.isActive || !skill.isEnabled) continue;
-    const bundledFiles = skill.isComplex ? getSkillFiles(skill.id) : [];
-    if (skill.isComplex && bundledFiles.length === 0) continue; // Legacy complex skills handled by npx
-    if (!skill.content) continue;
-
-    // Sanitize skill name to prevent path traversal (strip /, .., and non-safe chars)
-    const safeName = skill.name.replace(/[^a-zA-Z0-9_-]/g, "_");
-    if (!safeName) continue;
-
-    writtenNames.add(safeName);
-    const currentBundledFilePaths = new Set(
-      bundledFiles.filter((file) => !file.isBinary).map((file) => file.path),
-    );
-
-    for (const baseDir of skillDirs) {
-      const skillDir = join(baseDir, safeName);
-      const skillFile = join(skillDir, "SKILL.md");
-      const markerFile = join(skillDir, SWARM_MARKER_FILE);
-
-      try {
-        mkdirSync(skillDir, { recursive: true });
-        removed += reconcileManagedSkillFiles(skillDir, currentBundledFilePaths);
-        writeFileSync(skillFile, skill.content, "utf-8");
-        writeFileSync(markerFile, "", "utf-8");
-        synced++;
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : "Unknown error";
-        errors.push(`${skill.name} -> ${skillDir}: ${msg}`);
-        console.error(
-          `[skill-sync] Failed to write SKILL.md for ${skill.name} to ${skillDir}: ${msg}`,
-        );
-      }
-
-      for (const file of bundledFiles) {
-        if (file.isBinary) {
-          console.log(`[skill-sync] Skipping binary skill file ${skill.name}/${file.path}`);
-          continue;
-        }
-
-        const targetPath = join(skillDir, file.path);
-        try {
-          mkdirSync(dirname(targetPath), { recursive: true });
-          writeFileSync(targetPath, file.content, "utf-8");
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : "Unknown error";
-          errors.push(`${skill.name}/${file.path} -> ${targetPath}: ${msg}`);
-          console.error(
-            `[skill-sync] Failed to write bundled file ${skill.name}/${file.path} to ${targetPath}: ${msg}`,
-          );
-        }
-      }
-    }
-  }
-
-  // Cleanup: only remove directories WE previously created (marker file
-  // present). Leaves user-installed personal skills alone — important on
-  // local dev where ~/.codex/skills holds skills the user installed
-  // outside the swarm.
-  for (const baseDir of skillDirs) {
-    if (!existsSync(baseDir)) continue;
-
-    try {
-      const existing = readdirSync(baseDir, { withFileTypes: true });
-      for (const entry of existing) {
-        if (!entry.isDirectory()) continue;
-        if (writtenNames.has(entry.name)) continue;
-        const skillDir = join(baseDir, entry.name);
-        if (!existsSync(join(skillDir, SWARM_MARKER_FILE))) continue;
-        try {
-          rmSync(skillDir, { recursive: true, force: true });
-          removed++;
-        } catch {
-          // Non-fatal — skip cleanup errors
-        }
-      }
-    } catch {
-      // Non-fatal — skip if we can't read the directory
-    }
-  }
 
-  return { synced, removed, errors };
+  const entries: SkillFsEntry[] = skills.map((skill) => ({
+    id: skill.id,
+    name: skill.name,
+    content: skill.content ?? null,
+    isComplex: skill.isComplex,
+    isEnabled: skill.isEnabled,
+    isActive: skill.isActive,
+    files: skill.isComplex
+      ? getSkillFiles(skill.id).map((f) => ({
+          path: f.path,
+          content: f.content,
+          isBinary: f.isBinary,
+        }))
+      : [],
+  }));
+
+  return writeSkillsToFilesystem(entries, harnessType, home);
 }
 
 export interface SkillsSignature {

package/src/commands/runner.ts

@@ -2,6 +2,7 @@ import { existsSync, statSync } from "node:fs";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { ensure, initialize } from "@desplega.ai/business-use";
 import type { TemplateResponse } from "../../templates/schema.ts";
+import { resolveTaskModelSelection } from "../model-tiers.ts";
 import {
   type Attributes,
   initOtel,
@@ -350,6 +351,7 @@ async function fetchResolvedEnv(
   apiKey: string,
   agentId: string,
   baseEnv: Record<string, string | undefined> = process.env,
+  taskModel?: string,
 ): Promise<ResolvedEnvResult> {
   const env: Record<string, string | undefined> = { ...baseEnv };
 
@@ -382,6 +384,12 @@ async function fetchResolvedEnv(
 
   const resolvedProvider = resolveHarnessProvider(env, baseEnv);
 
+  // Effective model: per-task model takes priority over the agent-level
+  // MODEL_OVERRIDE from swarm_config. Passed to resolveCredentialPools so
+  // the harness × model matrix can exclude incompatible credential vars
+  // (e.g. OPENAI_API_KEY when an OpenRouter model is selected on opencode).
+  const effectiveModel = taskModel || (env.MODEL_OVERRIDE as string | undefined) || "";
+
   const credentialSelections = await resolveCredentialPools(env, {
     apiUrl,
     apiKey,
@@ -393,6 +401,7 @@ async function fetchResolvedEnv(
     // Use the resolved provider (swarm_config > env) so an operator can flip
     // the worker's harness from the dashboard without restarting the container.
     provider: resolvedProvider,
+    model: effectiveModel,
   });
 
   return { env, credentialSelections, resolvedProvider };
@@ -867,6 +876,7 @@ export async function ensureTaskFinished(
    * from the resolved swarm_config value. Falls back to env when omitted.
    */
   provider?: ProviderName,
+  failureDiagnostics?: string,
 ): Promise<void> {
   const headers: Record<string, string> = {
     "X-Agent-ID": config.agentId,
@@ -883,6 +893,9 @@ export async function ensureTaskFinished(
 
   if (status === "failed") {
     body.failureReason = failureReason || `Claude process exited with code ${exitCode}`;
+    if (failureDiagnostics) {
+      body.failureReason = `${body.failureReason}\n\n${failureDiagnostics}`;
+    }
   } else if (providerOutput) {
     const validation = await validateProviderOutputIfNeeded(config, taskId, providerOutput);
     if (validation.ok) {
@@ -1110,6 +1123,35 @@ async function reportKeyRateLimit(
   }
 }
 
+/** Clear a stale rate-limit record after a successful task (fire-and-forget) */
+async function reportKeyClearRateLimit(
+  apiUrl: string,
+  apiKey: string,
+  keyType: string,
+  keySuffix: string,
+): Promise<void> {
+  try {
+    const resp = await fetch(`${apiUrl}/api/keys/clear-rate-limit`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({ keyType, keySuffix }),
+    });
+    if (resp.ok) {
+      const data = (await resp.json()) as { cleared?: boolean };
+      if (data.cleared) {
+        console.log(
+          `[credentials] Cleared stale rate-limit for ...${keySuffix} after successful task`,
+        );
+      }
+    }
+  } catch {
+    // Non-blocking
+  }
+}
+
 /**
  * Supersede a task via the API (for graceful shutdown / context-limit /
  * operator-triggered). Returns `{ ok: true, resumeTaskId }` on success.
@@ -1472,6 +1514,8 @@ interface RunningTask {
    * provider before it completed, and vice versa).
    */
   hasLocalEnvironment: boolean;
+  /** Harness variant captured on session_init (e.g. "bridge" or "stock") */
+  harnessVariant?: string;
 }
 
 /** Runner state for tracking concurrent tasks */
@@ -1590,6 +1634,8 @@ async function saveProviderSessionId(
   provider?: ProviderName,
   providerMeta?: Record<string, unknown>,
   model?: string,
+  harnessVariant?: string,
+  harnessVariantMeta?: Record<string, unknown>,
 ): Promise<void> {
   const headers: Record<string, string> = { "Content-Type": "application/json" };
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
@@ -1597,13 +1643,71 @@ async function saveProviderSessionId(
   if (provider !== undefined) body.provider = provider;
   if (providerMeta !== undefined) body.providerMeta = providerMeta;
   if (model !== undefined && model !== "") body.model = model;
-  await fetch(`${apiUrl}/api/tasks/${taskId}/claude-session`, {
+  if (harnessVariant !== undefined) body.harnessVariant = harnessVariant;
+  if (harnessVariantMeta !== undefined) body.harnessVariantMeta = harnessVariantMeta;
+  await fetch(`${apiUrl}/api/tasks/${taskId}/session`, {
     method: "PUT",
     headers,
     body: JSON.stringify(body),
   });
 }
 
+async function findBridgeFailureArtifact(cwd: string): Promise<string | undefined> {
+  try {
+    const bridgeDir = `${cwd}/.claude-bridge/runs`;
+    const dir = await Array.fromAsync(
+      new Bun.Glob("*/tmux-pane-final.txt").scan({ cwd: bridgeDir, absolute: true }),
+    );
+    if (dir.length === 0) return undefined;
+    dir.sort();
+    return dir[dir.length - 1];
+  } catch {
+    return undefined;
+  }
+}
+
+async function readBridgeFailureTail(
+  artifactPath: string,
+  maxLines = 40,
+  maxChars = 4000,
+): Promise<string | undefined> {
+  try {
+    const text = await Bun.file(artifactPath).text();
+    const tail = text.split(/\r?\n/).slice(-maxLines).join("\n").trim();
+    if (!tail) return undefined;
+    return tail.length > maxChars ? tail.slice(-maxChars) : tail;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function getBridgeFailureDiagnostics(
+  cwd: string,
+): Promise<{ artifactPath: string; paneTail?: string } | undefined> {
+  const artifactPath = await findBridgeFailureArtifact(cwd);
+  if (!artifactPath) return undefined;
+  return {
+    artifactPath,
+    paneTail: await readBridgeFailureTail(artifactPath),
+  };
+}
+
+async function updateHarnessVariantMeta(
+  apiUrl: string,
+  apiKey: string,
+  taskId: string,
+  claudeSessionId: string,
+  meta: Record<string, unknown>,
+): Promise<void> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  await fetch(`${apiUrl}/api/tasks/${taskId}/session`, {
+    method: "PUT",
+    headers,
+    body: JSON.stringify({ claudeSessionId, harnessVariantMeta: meta }),
+  });
+}
+
 /** Cache of tasks that already have VCS linked — prevents repeated gh pr list calls */
 const vcsDetectedTasks = new Set<string>();
 
@@ -2454,6 +2558,7 @@ async function spawnProviderProcess(
     iteration: number;
     taskId?: string;
     model?: string;
+    modelTier?: string;
     resumeSessionId?: string;
     harnessProvider: ProviderName;
     cwd?: string;
@@ -2467,11 +2572,15 @@ async function spawnProviderProcess(
   // Correlation ID for logs/display — always defined
   const effectiveTaskId = realTaskId || crypto.randomUUID();
 
-  // Resolve env first so we can use MODEL_OVERRIDE from config
+  // Resolve env first so we can use MODEL_OVERRIDE from config.
+  // Pass opts.model (per-task model) so the credential picker can apply
+  // the harness × model matrix (e.g. exclude OPENAI_API_KEY for OpenRouter models).
   const { env: freshEnv, credentialSelections } = await fetchResolvedEnv(
     opts.apiUrl,
     opts.apiKey,
     opts.agentId,
+    process.env,
+    opts.model,
   );
 
   // Report which key was selected for this task (fire-and-forget)
@@ -2488,15 +2597,31 @@ async function spawnProviderProcess(
   }
 
   const configModel = (freshEnv.MODEL_OVERRIDE as string | undefined) || "";
-  const model = opts.model || configModel || "";
+  const taskModelSelection = resolveTaskModelSelection({
+    model: opts.model,
+    modelTier: opts.modelTier,
+    harnessProvider: opts.harnessProvider,
+    env: freshEnv,
+  });
+  const taskModel = taskModelSelection.model || "";
+  const model = taskModel || configModel || "";
 
   // Resolve Codex OAuth pool slot BEFORE building ProviderSessionConfig so we
   // can pass codexSlot through and the adapter writes token refreshes back to
   // the correct slot key (codex_oauth_<slot>) instead of defaulting to slot 0.
+  //
+  // Always resolve for codex (not just when credentialSelections is empty) so
+  // that if the OPENAI_API_KEY credential is rate-limited we can fail over to
+  // a CODEX_OAUTH slot — even though the keyType differs.
   let oauthSelection: CredentialSelection | undefined;
-  if (adapter.name === "codex" && credentialSelections.length === 0) {
+  if (adapter.name === "codex") {
     oauthSelection = (await resolveCodexOAuthCredentialInfo(opts.apiUrl, opts.apiKey)) ?? undefined;
-    if (oauthSelection && realTaskId) {
+    const oauthIsPrimary =
+      credentialSelections.length === 0 ||
+      (credentialSelections[0]?.isRateLimitFallback &&
+        oauthSelection &&
+        !oauthSelection.isRateLimitFallback);
+    if (oauthSelection && realTaskId && oauthIsPrimary) {
       reportKeyUsage(
         opts.apiUrl,
         opts.apiKey,
@@ -2570,7 +2695,7 @@ async function spawnProviderProcess(
   );
   const initialModelReport = buildLatestModelReport({
     model,
-    taskModel: opts.model,
+    taskModel,
     configModel,
     taskId: realTaskId,
     harnessProvider: opts.harnessProvider,
@@ -2676,6 +2801,8 @@ async function spawnProviderProcess(
               event.provider,
               event.providerMeta,
               model,
+              event.harnessVariant,
+              event.harnessVariantMeta,
             ).catch((err) => console.warn(`[runner] Failed to save session ID: ${err}`));
           } else {
             // Pool task: save provider session ID on active session so it can be
@@ -2690,6 +2817,17 @@ async function spawnProviderProcess(
             );
           }
 
+          // Structured session-start log for observability (covers all providers)
+          {
+            const variant = event.harnessVariant ?? "unknown";
+            const version =
+              (event.harnessVariantMeta as Record<string, unknown> | undefined)?.version ??
+              "unknown";
+            console.log(
+              `[${opts.role}] [harness] provider=${event.provider ?? opts.harnessProvider} variant=${variant} version=${version} model=${model || "default"}`,
+            );
+          }
+
           // Buffer session start event
           bufferEvent({
             category: "session",
@@ -3085,8 +3223,23 @@ async function spawnProviderProcess(
       }),
     );
 
-  // Build credential info for rate limit tracking
-  const primarySelection = credentialSelections[0] ?? oauthSelection;
+  // Build credential info for rate limit tracking.
+  // For codex: when OPENAI_API_KEY is rate-limited but CODEX_OAUTH has
+  // available slots (or vice versa), prefer the healthy credential.
+  let primarySelection: CredentialSelection | undefined;
+  const firstCred = credentialSelections[0];
+  if (firstCred && oauthSelection) {
+    if (firstCred.isRateLimitFallback && !oauthSelection.isRateLimitFallback) {
+      primarySelection = oauthSelection;
+      console.log(
+        `[credentials] Cross-keyType failover: ${firstCred.keyType} all rate-limited, using ${oauthSelection.keyType} [...${oauthSelection.keySuffix}]`,
+      );
+    } else {
+      primarySelection = firstCred;
+    }
+  } else {
+    primarySelection = firstCred ?? oauthSelection;
+  }
   const credentialInfo = primarySelection
     ? {
         keyType: primarySelection.keyType,
@@ -3160,7 +3313,14 @@ async function checkCompletedProcesses(
   }
 
   // Remove completed tasks from the map and ensure they're marked as finished
-  for (const { taskId, result, cursorUpdates, workingDir, credentialInfo } of completedTasks) {
+  for (const {
+    taskId,
+    result,
+    cursorUpdates,
+    workingDir,
+    credentialInfo,
+    harnessProvider,
+  } of completedTasks) {
     state.activeTasks.delete(taskId);
     vcsDetectedTasks.delete(taskId);
     vcsCheckTimestamps.delete(taskId);
@@ -3244,6 +3404,20 @@ async function checkCompletedProcesses(
           rateLimitedUntil,
         ).catch(() => {});
       }
+      let bridgeDiagnostics: Awaited<ReturnType<typeof getBridgeFailureDiagnostics>> | undefined;
+      if (result.exitCode !== 0 && harnessProvider === "claude" && workingDir) {
+        bridgeDiagnostics = await getBridgeFailureDiagnostics(workingDir);
+        if (bridgeDiagnostics?.artifactPath && result.sessionId) {
+          console.log(`[${role}] Bridge failure artifact found: ${bridgeDiagnostics.artifactPath}`);
+          updateHarnessVariantMeta(apiConfig.apiUrl, apiConfig.apiKey, taskId, result.sessionId, {
+            failureArtifact: bridgeDiagnostics.artifactPath,
+          }).catch((err) => console.warn(`[runner] Failed to update harness variant meta: ${err}`));
+        }
+      }
+      const bridgeFailureDiagnostics =
+        bridgeDiagnostics?.paneTail != null
+          ? `Claude bridge final tmux pane tail (${bridgeDiagnostics.artifactPath}):\n${bridgeDiagnostics.paneTail}`
+          : undefined;
       await ensureTaskFinished(
         apiConfig,
         role,
@@ -3251,9 +3425,19 @@ async function checkCompletedProcesses(
         result.exitCode,
         failureReason,
         result.output,
-        state.harnessProvider,
+        harnessProvider,
+        bridgeFailureDiagnostics,
       );
 
+      if (result.exitCode === 0 && credentialInfo) {
+        reportKeyClearRateLimit(
+          apiConfig.apiUrl,
+          apiConfig.apiKey,
+          credentialInfo.keyType,
+          credentialInfo.keySuffix,
+        ).catch(() => {});
+      }
+
       ensure({
         id: "worker_process_finished",
         flow: "task",
@@ -4274,6 +4458,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
               iteration,
               taskId: task.id,
               model: (task as { model?: string }).model,
+              modelTier: (task as { modelTier?: string }).modelTier,
               harnessProvider: state.harnessProvider,
               cwd: resumeCwd,
               vcsRepo: task.vcsRepo,
@@ -4593,6 +4778,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
 
         // Extract model from task data for per-task model selection
         const taskModel = (trigger.task as { model?: string } | undefined)?.model;
+        const taskModelTier = (trigger.task as { modelTier?: string } | undefined)?.modelTier;
 
         // Detect Slack context for conditional prompt sections
         const taskSlackChannelId = (trigger.task as { slackChannelId?: string } | undefined)
@@ -4735,6 +4921,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
               iteration,
               taskId: trigger.taskId,
               model: taskModel,
+              modelTier: taskModelTier,
               harnessProvider: state.harnessProvider,
               cwd: effectiveCwd,
               vcsRepo: taskVcsRepo,

package/src/http/api-keys.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import {
+  clearKeyRateLimit,
   getAvailableKeyIndices,
   getKeyCostSummary,
   getKeyStatuses,
@@ -134,6 +135,26 @@ const setKeyName = route({
   auth: { apiKey: true },
 });
 
+const clearRateLimitRoute = route({
+  method: "post",
+  path: "/api/keys/clear-rate-limit",
+  pattern: ["api", "keys", "clear-rate-limit"],
+  summary: "Clear rate-limited status for a key after a successful use proves it is healthy",
+  tags: ["API Keys"],
+  body: z.object({
+    keyType: z.string(),
+    keySuffix: z.string().min(1).max(10),
+    scope: z.string().optional(),
+    scopeId: z.string().optional(),
+  }),
+  responses: {
+    200: { description: "Rate limit cleared (or key was not rate-limited)" },
+    400: { description: "Validation error" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleApiKeys(
@@ -242,5 +263,26 @@ export async function handleApiKeys(
     return true;
   }
 
+  // POST /api/keys/clear-rate-limit
+  if (clearRateLimitRoute.match(req.method, pathSegments)) {
+    const parsed = await clearRateLimitRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const { keyType, keySuffix, scope, scopeId } = parsed.body;
+    try {
+      const cleared = clearKeyRateLimit(keyType, keySuffix, scope, scopeId ?? null);
+      json(res, {
+        success: true,
+        cleared,
+        message: cleared
+          ? `Rate limit cleared for ...${keySuffix}`
+          : `Key ...${keySuffix} was not rate-limited`,
+      });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to clear rate limit", 500);
+    }
+    return true;
+  }
+
   return false;
 }