@desplega.ai/agent-swarm 1.158.0 → 1.160.0

package/src/be/seed/runner.ts

@@ -10,6 +10,7 @@ import type { Seeder, SeederResult, SeederRunOptions } from "./types";
 /**
  * Apply one seeder. Idempotent and version-aware:
  *   - upstream absent              -> create
+ *   - upstream identical to src    -> no-op (re-baselines seed state)
  *   - upstream pristine, src moved -> update
  *   - upstream pristine, src same  -> no-op
  *   - upstream user-modified       -> preserve (never overwrite)
@@ -38,12 +39,25 @@ export async function runSeeder(seeder: Seeder, opts?: SeederRunOptions): Promis
       }
 
       const state = await getSeedState(seeder.kind, item.key);
+
+      if (upstream === item.contentHash) {
+        // Live copy is byte-identical to the current source, so there is nothing
+        // user-authored to lose. Treat it as in sync regardless of seed state:
+        // adopt an unrecorded entity, and re-baseline one whose recorded hash
+        // drifted (edited, then reset to source) so the next source change is
+        // detectable as an update instead of being preserved forever.
+        if (state?.seededHash !== item.contentHash) {
+          await recordSeedState(seeder.kind, item.key, item.contentHash);
+        }
+        result.skippedUnchanged += 1;
+        continue;
+      }
+
       // "Pristine" = the live upstream copy still matches what we last seeded.
       // With no recorded state (first run after this framework landed, or a
-      // pre-existing entity) we can only treat it as pristine when it is
-      // byte-identical to the source — otherwise we conservatively assume a
-      // user authored it and must not be clobbered.
-      const pristine = state ? upstream === state.seededHash : upstream === item.contentHash;
+      // pre-existing entity) the live copy already differs from source here, so
+      // we conservatively assume a user authored it and must not clobber it.
+      const pristine = state ? upstream === state.seededHash : false;
 
       if (!pristine) {
         // A user changed the upstream copy since our last seed — preserve it.
@@ -51,14 +65,6 @@ export async function runSeeder(seeder: Seeder, opts?: SeederRunOptions): Promis
         continue;
       }
 
-      if (upstream === item.contentHash) {
-        // Neither side changed. Adopt an unrecorded-but-identical entity so the
-        // next source change is correctly detectable as an update.
-        if (!state) await recordSeedState(seeder.kind, item.key, item.contentHash);
-        result.skippedUnchanged += 1;
-        continue;
-      }
-
       // Pristine upstream + changed source -> update to the new source version.
       await seeder.apply(item, "update", opts);
       await recordSeedState(seeder.kind, item.key, item.contentHash);

package/src/be/seed/types.ts

@@ -9,6 +9,7 @@
  *
  * Versioning rule (per item, evaluated against the `seed_state` table):
  *   - upstream entity absent              -> create
+ *   - upstream identical to source        -> no-op (seed state re-baselined)
  *   - upstream pristine + source changed  -> update
  *   - upstream pristine + source same     -> no-op
  *   - upstream user-modified              -> never overwrite (preserve)

package/src/be/seed-scripts/catalog/task-failure-audit.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { publishCatalogReportPage } from "./catalog-report";
 
+const MAX_TASK_SCAN_LIMIT = 500;
+
 export const argsSchema = z.object({
   days: z
     .number()
@@ -16,8 +18,9 @@ export const argsSchema = z.object({
     .number()
     .int()
     .positive()
+    .max(MAX_TASK_SCAN_LIMIT)
     .optional()
-    .describe("Max failed tasks to scan (default 500)"),
+    .describe("Max failed tasks to scan (default 500, max 500)"),
   publishPage: z.boolean().optional().describe("Publish an authed HTML page (default true)"),
 });
 
@@ -25,20 +28,37 @@ const REASON_PATTERNS: any[] = [
   { key: "sigterm/killed", re: /sigterm|sigkill|killed|143|137/i },
   { key: "timeout", re: /time?d?\s*out|timeout|deadline/i },
   { key: "context-window", re: /context (window|limit|saturat)|peakcontext|compact/i },
+  { key: "reboot-sweep", re: /reboot sweep/i },
   { key: "not-found", re: /not found|404|missing|no such/i },
   { key: "auth/credentials", re: /unauthorized|401|403|credential|token|forbidden/i },
-  { key: "ci/checks-failed", re: /ci|check.?s? fail|lint|tsc|test.?s? fail/i },
+  { key: "ci/checks-failed", re: /\bci\b|check.?s? fail|lint|tsc|test.?s? fail/i },
   { key: "network", re: /network|econn|fetch failed|socket|dns|502|503|504/i },
   { key: "cancelled", re: /cancel|aborted/i },
 ];
 
+function sanitizeUntrustedReasonSample(reason: unknown): string {
+  return String(reason)
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 200);
+}
+
+function rowsToObjects(result: any): any[] {
+  const payload = result?.data ?? result;
+  const columns: string[] = payload?.columns ?? [];
+  return (payload?.rows ?? []).map((row: any) =>
+    Array.isArray(row) ? Object.fromEntries(columns.map((column, i) => [column, row[i]])) : row,
+  );
+}
+
 function reasonCluster(reason: string): string {
   const r = (reason || "").trim();
   if (!r) return "(no reason given)";
   for (const p of REASON_PATTERNS) {
     if (p.re.test(r)) return p.key;
   }
-  return r.toLowerCase().slice(0, 48);
+  return "other";
 }
 
 /** Cluster recently failed swarm tasks by reason, agent, or schedule. */
@@ -47,7 +67,7 @@ export default async function taskFailureAudit(args: any, ctx: any) {
   if (!parsed.success) return { error: "invalid args: " + parsed.error.message };
   const days = parsed.data.days || 7;
   const groupBy = parsed.data.groupBy || "reason";
-  const limit = parsed.data.limit || 500;
+  const limit = Math.min(parsed.data.limit ?? MAX_TASK_SCAN_LIMIT, MAX_TASK_SCAN_LIMIT);
   const publishPage = parsed.data.publishPage !== false;
 
   const since = new Date(Date.now() - days * 86400000).toISOString();
@@ -62,17 +82,49 @@ export default async function taskFailureAudit(args: any, ctx: any) {
   const payload: any = res && res.data ? res.data : res;
   const tasks: any = payload && Array.isArray(payload.tasks) ? payload.tasks : [];
 
+  const failureReasons = new Map<string, string>();
+  // Projected for every groupBy mode: task_list omits failureReason, and
+  // schedule/agent groups still need a populated sample.
+  const tasksNeedingReason = tasks.filter((task: any) => !task.failureReason && task.id);
+  const taskIds = tasksNeedingReason.map((task: any) => task.id as string);
+  if (taskIds.length > 0) {
+    const placeholders = taskIds.map(() => "?").join(", ");
+    const reasonResult: any = await ctx.swarm.db_query({
+      sql: `SELECT id, failureReason FROM agent_tasks WHERE id IN (${placeholders})`,
+      params: taskIds,
+    });
+    const reasonPayload: any = reasonResult?.data ?? reasonResult;
+    if (
+      reasonResult?.success === false ||
+      reasonPayload?.success === false ||
+      reasonPayload?.error
+    ) {
+      return { error: "failure reason projection failed with status " + reasonResult?.status };
+    }
+    if (reasonPayload?.truncated) {
+      return {
+        error: `failure reason projection truncated (${reasonPayload.rows?.length ?? 0} of ${reasonPayload.total ?? "unknown"} rows)`,
+      };
+    }
+    for (const row of rowsToObjects(reasonResult)) {
+      if (typeof row?.id === "string" && typeof row.failureReason === "string") {
+        failureReasons.set(row.id, row.failureReason);
+      }
+    }
+  }
+
   const groups: any = {};
   for (const t of tasks) {
     let key: string;
     if (groupBy === "agent") key = t.agentId || "(unassigned)";
     else if (groupBy === "schedule") key = t.scheduleId || "(not scheduled)";
-    else key = reasonCluster(t.failureReason || "");
-    if (!groups[key]) groups[key] = { key, count: 0, taskIds: [], sampleReason: "" };
+    else key = reasonCluster(failureReasons.get(t.id) || t.failureReason || "");
+    if (!groups[key]) groups[key] = { key, count: 0, taskIds: [], untrustedWorkerTextSample: "" };
     groups[key].count++;
     if (groups[key].taskIds.length < 5) groups[key].taskIds.push(t.id);
-    if (!groups[key].sampleReason && t.failureReason) {
-      groups[key].sampleReason = String(t.failureReason).slice(0, 200);
+    const failureReason = failureReasons.get(t.id) || t.failureReason;
+    if (!groups[key].untrustedWorkerTextSample && failureReason) {
+      groups[key].untrustedWorkerTextSample = sanitizeUntrustedReasonSample(failureReason);
     }
   }
 
@@ -118,7 +170,7 @@ export default async function taskFailureAudit(args: any, ctx: any) {
                   key: group.key,
                   count: group.count,
                   taskIds: group.taskIds,
-                  sampleReason: group.sampleReason,
+                  untrustedWorkerTextSample: group.untrustedWorkerTextSample,
                 },
               ],
             })),

package/src/be/swarm-config-guard.ts

@@ -1,6 +1,7 @@
 import { normalizeSlackReactionShortcode } from "../slack/reaction-shortcode";
 import { ProviderNameSchema } from "../types";
 import { parseTaskToolManifest } from "../utils/task-tool-manifest";
+import { isTierConfigKey, validateTierConfigValue } from "./model-tier-keys";
 
 /**
  * Guards against storing reserved keys in the swarm_config table.
@@ -274,6 +275,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     return null;
   },
   ...booleanValidators([
+    "SWARM_DEV_MODE",
     "MULTI_RUNTIME_ENABLED",
     "STEERING_ENABLED",
     "MEMORY_HYBRID_SEARCH",
@@ -283,6 +285,8 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "POOL_AFFINITY_ENFORCEMENT",
     "SCRIPTS_ONLY_MCP",
     "TASK_TOOL_PRELOAD_ENABLED",
+    "PI_TOOL_DEFERRAL",
+    "PI_CODEMODE",
     "SLACK_DISABLE",
     "SLACK_RENDER_V2",
     "SLACK_RENDER_V2_DELEGATION",
@@ -304,6 +308,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "SWARM_HIDE_CLOUD_PROMO",
     "DB_QUERY_BOUNDED_ENABLED",
     "DB_RETENTION_DRY_RUN",
+    "MODEL_AUTO_UPGRADE",
   ]),
   ...enumValidator("SLACK_MODE", ["socket", "http"]),
   ...enumValidator("SLACK_THREAD_STEERING", ["off", "lead", "all"]),
@@ -359,6 +364,8 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
   ),
   // 0 is meaningful here: "auto-assign nothing this sweep".
   ...integerValidators(["HEARTBEAT_MAX_AUTO_ASSIGN"], 0),
+  // 0 disables the `latest:...@stable` soak window.
+  ...integerValidators(["MODEL_LATEST_SOAK_DAYS"], 0),
   // 0 turns approval auto-cancellation off.
   ...integerValidators(["APPROVAL_REQUEST_AUTO_CANCELLATION_DAYS"], 0),
   // Below ~100 tokens the preamble can't fit a useful summary; above 20000
@@ -378,6 +385,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
 };
 
 export function validateConfigValue(key: string, value: unknown): string | null {
+  if (isTierConfigKey(key)) return validateTierConfigValue(key.toUpperCase(), value);
   const validator = VALIDATED_KEYS[key.toUpperCase()];
   return validator ? validator(value) : null;
 }

package/src/cli.tsx

@@ -717,6 +717,16 @@ if (args.showHelp || args.command === "help" || args.command === undefined) {
 } else if (args.command === "version") {
   console.log(`${binName} v${pkg.version}`);
   process.exit(0);
+} else if (args.command === "onboard" && !process.versions.bun) {
+  // The published bin uses Node, but the onboarding wizard requires Bun APIs.
+  const { spawnSync } = await import("node:child_process");
+  const result = spawnSync("bun", process.argv.slice(1), { stdio: "inherit" });
+  if (result.error) {
+    console.error(
+      "Onboarding requires Bun. Install Bun from https://bun.sh, then retry this command.",
+    );
+  }
+  process.exit(result.status ?? 1);
 } else if (args.command === "docs") {
   const docsUrl = "https://docs.agent-swarm.dev";
   console.log(`\n${binName} docs — v${pkg.version}\n`);

package/src/commands/claude-managed-setup.ts

@@ -34,6 +34,7 @@ import type { SkillCreateResponse } from "@anthropic-ai/sdk/resources/beta/skill
 import { toFile } from "@anthropic-ai/sdk/uploads";
 
 import { buildSkillContent, type SkillTemplateConfig } from "../be/seed-skills/render";
+import { DEFAULT_MODEL_TIER_MAP } from "../types";
 import { getApiKey } from "../utils/api-key";
 import { promptHiddenInput } from "./codex-login.js";
 
@@ -65,7 +66,8 @@ export type ClaudeManagedSetupResult = {
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
-const DEFAULT_AGENT_MODEL = "claude-sonnet-5";
+/** The claude-managed `regular` tier default — no per-model constant here. */
+const DEFAULT_AGENT_MODEL = DEFAULT_MODEL_TIER_MAP["claude-managed"].regular;
 const SKILLS_DIR_RELATIVE = "plugin/commands";
 const SEEDED_SKILLS_DIR_RELATIVE = "templates/skills";
 const SKILLS_BETA_HEADER = "skills-2025-10-02";

package/src/commands/codex-login.ts

@@ -12,6 +12,7 @@
 import { exec } from "node:child_process";
 import { emitKeypressEvents } from "node:readline";
 
+import { deriveCodexKeySuffix } from "../providers/codex-oauth/auth-json.js";
 import { loginCodexOAuth } from "../providers/codex-oauth/flow.js";
 import {
   loadAllCodexOAuthSlots,
@@ -35,11 +36,59 @@ type RunCodexLoginDeps = {
   login?: typeof loginCodexOAuth;
   store?: typeof storeCodexOAuth;
   loadAllSlots?: typeof loadAllCodexOAuthSlots;
+  clearAuthBench?: typeof clearCodexAuthBench;
+  readAuthFence?: typeof readCodexAuthFailureFence;
   log?: (message: string) => void;
   error?: (message: string) => void;
   exit?: (code: number) => void;
 };
 
+/**
+ * Read the API's `authFailureFence` for the Codex pool. `runCodexLogin` reads it
+ * BEFORE it stores the fresh credentials, so the clear below lifts only failures
+ * recorded before that write.
+ */
+export async function readCodexAuthFailureFence(apiUrl: string, apiKey: string): Promise<number> {
+  const resp = await fetch(`${apiUrl}/api/keys/available?keyType=CODEX_OAUTH&totalKeys=1`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (!resp.ok) throw new Error(`keys/available returned ${resp.status}`);
+  const data = (await resp.json()) as { authFailureFence?: number };
+  if (typeof data.authFailureFence !== "number") throw new Error("no authFailureFence in response");
+  return data.authFailureFence;
+}
+
+/**
+ * Lift an auth-failure bench on the re-logged key. A fresh login is proof of
+ * health, so it passes `clearAuthBench: true` (the API also deletes the
+ * `codex-auth-watch` bench marker). `authFence` binds the clear to the credential
+ * write: failures recorded after the fresh login survive a late clear. It also
+ * passes the slot, so the API retires a different login that the slot held
+ * before. Returns `true` when a bench was lifted.
+ */
+export async function clearCodexAuthBench(
+  apiUrl: string,
+  apiKey: string,
+  keySuffix: string,
+  slot: number,
+  authFence: number,
+): Promise<boolean> {
+  const resp = await fetch(`${apiUrl}/api/keys/clear-rate-limit`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify({
+      keyType: "CODEX_OAUTH",
+      keySuffix,
+      clearAuthBench: true,
+      keyIndex: slot,
+      authFence,
+    }),
+  });
+  if (!resp.ok) throw new Error(`clear-rate-limit returned ${resp.status}`);
+  const data = (await resp.json()) as { cleared?: boolean };
+  return data.cleared === true;
+}
+
 type ParsedCodexLoginArgs = {
   apiUrl?: string;
   apiKey?: string;
@@ -207,6 +256,8 @@ export async function runCodexLogin(args: string[], deps: RunCodexLoginDeps = {}
   const login = deps.login ?? loginCodexOAuth;
   const store = deps.store ?? storeCodexOAuth;
   const loadAllSlots = deps.loadAllSlots ?? loadAllCodexOAuthSlots;
+  const clearAuthBench = deps.clearAuthBench ?? clearCodexAuthBench;
+  const readAuthFence = deps.readAuthFence ?? readCodexAuthFailureFence;
   const log = deps.log ?? console.log;
   const error = deps.error ?? console.error;
   const exit = deps.exit ?? ((code: number) => process.exit(code));
@@ -283,11 +334,27 @@ export async function runCodexLogin(args: string[], deps: RunCodexLoginDeps = {}
     log(`  Account ID: ${creds.accountId}`);
     log(`  Expires: ${new Date(creds.expires).toISOString()}`);
 
+    // Read the auth-failure fence before the credential write (see clearCodexAuthBench).
+    const authFence = await readAuthFence(apiUrl, apiKey).catch((err: unknown) => err);
+
     // Store credentials in the swarm API config store
     log("\nStoring credentials in swarm API config store...");
     await store(apiUrl, apiKey, creds, slot);
     log(`Credentials stored successfully in slot ${slot}!`);
 
+    // A re-login returns an auth-benched slot to the pool right away.
+    // Non-fatal: the credentials are stored; a later re-login also lifts it.
+    const keySuffix = deriveCodexKeySuffix(creds.access, creds.accountId);
+    try {
+      if (typeof authFence !== "number") throw authFence;
+      if (await clearAuthBench(apiUrl, apiKey, keySuffix, slot, authFence)) {
+        log(`Lifted the auth-failure bench on key ...${keySuffix}.`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      error(`Warning: could not lift the auth-failure bench on key ...${keySuffix}: ${message}`);
+    }
+
     log("\nDeployed Codex workers will automatically restore these credentials at boot.");
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/src/commands/credential-outcome-report.ts

@@ -0,0 +1,191 @@
+import type { RateLimitWindowTelemetry } from "../utils/error-tracker";
+import { modelFamilyOf } from "../utils/model-rate-limit-windows";
+import { buildFinalRateLimitWindows, classifyRateLimitOutcome } from "./rate-limit-outcome";
+import { reportSeatMismatchOutcome } from "./seat-mismatch-report";
+
+/** Report a rate-limited key to the API (fire-and-forget) */
+async function reportKeyRateLimit(
+  apiUrl: string,
+  apiKey: string,
+  keyType: string,
+  keySuffix: string,
+  keyIndex: number,
+  rateLimitedUntil: string,
+): Promise<void> {
+  try {
+    await fetch(`${apiUrl}/api/keys/report-rate-limit`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        keyType,
+        keySuffix,
+        keyIndex,
+        rateLimitedUntil,
+      }),
+    });
+    console.log(
+      `[credentials] Reported key ...${keySuffix} as rate-limited until ${rateLimitedUntil}`,
+    );
+  } catch {
+    // Non-blocking
+  }
+}
+
+/**
+ * Reports rate-limit window telemetry for a key. Returns the underlying
+ * fetch promise (does not swallow errors) so a caller that needs the post to
+ * complete before the task finishes (a model-scoped block) can await it and
+ * decide how to handle a failure; a caller that wants the legacy
+ * fire-and-forget behavior appends `.catch(() => {})`.
+ *
+ * Throws on a non-2xx response so a failed persistence surfaces to the
+ * caller instead of logging success while only the in-process guard took
+ * effect — otherwise other workers redraw the same exhausted key at once.
+ *
+ * `logKeySuffix` defaults to true for the legacy full-telemetry call site;
+ * the model-scoped call site passes false since it already logs the model
+ * family and key index itself (see the `[credential] model window ...`
+ * log above the call).
+ */
+export async function reportKeyRateLimitWindows(
+  apiUrl: string,
+  apiKey: string,
+  keyType: string,
+  keySuffix: string,
+  keyIndex: number,
+  windows: RateLimitWindowTelemetry,
+  logKeySuffix = true,
+): Promise<void> {
+  if (Object.keys(windows).length === 0) return;
+  const response = await fetch(`${apiUrl}/api/keys/report-rate-limit-windows`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      keyType,
+      keySuffix,
+      keyIndex,
+      windows,
+    }),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Failed to report rate-limit windows for key #${keyIndex}: HTTP ${response.status}`,
+    );
+  }
+  if (logKeySuffix) {
+    console.log(`[credentials] Reported rate-limit windows for key ...${keySuffix}`);
+  }
+}
+
+export interface CredentialOutcomeInput {
+  apiUrl: string;
+  apiKey: string;
+  credentialInfo?: { keyType: string; keySuffix: string; keyIndex: number };
+  /** The finished session's `ProviderResult`. */
+  result: Parameters<typeof classifyRateLimitOutcome>[0];
+  failureReason: string | undefined;
+  model: string | undefined;
+  codexCreditsExhaustedCooldownMs: number;
+  /** Runner-local model window guard, keyed `keyType:keyIndex:window`. */
+  modelWindowBlocks: Map<string, number>;
+}
+
+/**
+ * Reports a finished session's credential outcome, then calls `finish`.
+ *
+ * If rate-limited and we know which key was used, report it. Codex adapter
+ * prefixes failure reasons with `[rate-limit]` / `[usage-limit]` (see
+ * codex-adapter.formatTerminalError); Claude surfaces "rate limit" / "hit
+ * your limit" via SessionErrorTracker.
+ *
+ * classifyRateLimitOutcome tests model-scoped windows (Fable/Opus/Sonnet
+ * weekly limits) before the legacy key-wide gate, so a model-scoped
+ * rejection blocks only that model family on this key — never the whole
+ * key — via report-rate-limit-windows instead of report-rate-limit. A
+ * key-wide rejection seen in the same session is still reported alongside
+ * it (windows are independent). The session's window telemetry and the
+ * classified model rejection go out as ONE payload, so an older `allowed`
+ * snapshot never overwrites the terminal rejection.
+ *
+ * Reports that gate admission on other workers (a seat mismatch, a model
+ * window rejection) land before `finish` runs. Plain telemetry and the
+ * key-wide report stay fire-and-forget.
+ */
+export async function reportCredentialOutcomeThenFinish(
+  input: CredentialOutcomeInput,
+  finish: () => Promise<void>,
+): Promise<void> {
+  const { apiUrl, apiKey, credentialInfo, result, failureReason, model } = input;
+  if (credentialInfo) {
+    const outcome = classifyRateLimitOutcome(
+      result,
+      failureReason,
+      Date.now(),
+      input.codexCreditsExhaustedCooldownMs,
+      modelFamilyOf(model),
+    );
+    // A seat mismatch is not a rate limit: the key stays available for
+    // every model its seat can run. A seat outcome carries
+    // `keyRateLimitedUntil` only for an independent key-wide rejection seen
+    // earlier in the same session, which is still reported below.
+    if (outcome.kind === "seat") {
+      await reportSeatMismatchOutcome(apiUrl, apiKey, credentialInfo, outcome.model);
+    }
+    const keyRateLimitedUntil =
+      outcome.kind === "key"
+        ? outcome.rateLimitedUntil
+        : outcome.kind === "model" || outcome.kind === "seat"
+          ? outcome.keyRateLimitedUntil
+          : undefined;
+    if (keyRateLimitedUntil) {
+      console.log(`[credentials] Rate limit reset: ${keyRateLimitedUntil}`);
+      reportKeyRateLimit(
+        apiUrl,
+        apiKey,
+        credentialInfo.keyType,
+        credentialInfo.keySuffix,
+        credentialInfo.keyIndex,
+        keyRateLimitedUntil,
+      ).catch(() => {});
+    }
+    if (outcome.kind === "model") {
+      const resetsAtIso = new Date(outcome.resetsAtSec * 1000).toISOString();
+      const blockKey = `${credentialInfo.keyType}:${credentialInfo.keyIndex}:${outcome.window}`;
+      input.modelWindowBlocks.set(blockKey, outcome.resetsAtSec * 1000);
+      console.log(
+        `[credential] ${outcome.model} weekly window exhausted (${outcome.window}) on key #${credentialInfo.keyIndex} until ${resetsAtIso}`,
+      );
+    }
+
+    const finalWindows = buildFinalRateLimitWindows(
+      result.rateLimitWindows,
+      outcome,
+      new Date().toISOString(),
+    );
+    if (finalWindows) {
+      const report = reportKeyRateLimitWindows(
+        apiUrl,
+        apiKey,
+        credentialInfo.keyType,
+        credentialInfo.keySuffix,
+        credentialInfo.keyIndex,
+        finalWindows,
+        outcome.kind !== "model",
+      ).catch((err) => {
+        console.warn(
+          `[credential] Failed to report rate-limit windows: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+      // A model rejection gates admission on other workers: land it before
+      // the task finishes. Plain telemetry stays fire-and-forget.
+      if (outcome.kind === "model") await report;
+    }
+  }
+  await finish();
+}

package/src/commands/rate-limit-outcome.ts

@@ -8,6 +8,7 @@ import {
 } from "../utils/error-tracker";
 import {
   type ModelFamily,
+  parseCreditsRequiredMessage,
   parseModelLimitMessage,
   windowForModelFamily,
 } from "../utils/model-rate-limit-windows";
@@ -15,6 +16,20 @@ import {
 export type RateLimitOutcome =
   | { kind: "none" }
   | { kind: "key"; rateLimitedUntil: string }
+  /**
+   * The key's seat cannot run the model (`credits_required`). Not a rate
+   * limit: the seat rejection never marks the key by itself.
+   */
+  | {
+      kind: "seat";
+      model: ModelFamily;
+      source: "event" | "text";
+      /**
+       * An independent key-wide rejection observed earlier in the same
+       * session, still to enforce. The seat outcome never erases it.
+       */
+      keyRateLimitedUntil?: string;
+    }
   | {
       kind: "model";
       model: ModelFamily;
@@ -38,6 +53,7 @@ interface ClassifiableResult {
   rateLimitResetAt?: string;
   rateLimitWindows?: RateLimitWindowTelemetry;
   modelRateLimit?: { window: string; model: ModelFamily; resetAt: string; observedAt?: string };
+  creditsRequired?: { observedAt: string; overageDisabledReason?: string };
 }
 
 function clampMs(candidateMs: number, nowMs: number): number {
@@ -48,10 +64,15 @@ function clampMs(candidateMs: number, nowMs: number): number {
 
 /**
  * Classifies a finished provider session's rate-limit signal into one of
- * three outcomes: no rate limit, a key-wide rate limit (legacy path), or a
- * model-scoped weekly-window rejection (Fable/Opus/Sonnet). Model outcomes
- * are tested before key outcomes so a model-scoped event or message never
- * falls into the legacy key-wide gate and marks the whole key.
+ * four outcomes: no rate limit, a key-wide rate limit (legacy path), a
+ * model-scoped weekly-window rejection (Fable/Opus/Sonnet), or a seat
+ * mismatch (`credits_required`: the seat cannot run the model). Seat
+ * outcomes are tested first and model outcomes before key outcomes, so
+ * neither falls into the legacy key-wide gate and marks the whole key.
+ *
+ * `taskModelFamily` is the family of the task's model. A structured
+ * `credits_required` event names no model, so without it (and without the
+ * failure text) the event cannot be attributed and is not a seat outcome.
  *
  * `codexCreditsExhaustedCooldownMs` defaults to the fixed constant so the
  * function stays pure and testable with 3 args; the runner call site passes
@@ -62,12 +83,21 @@ export function classifyRateLimitOutcome(
   failureReason: string | undefined,
   nowMs: number,
   codexCreditsExhaustedCooldownMs: number = CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS,
+  taskModelFamily?: ModelFamily,
 ): RateLimitOutcome {
   const keyRateLimitedUntil = result.rateLimitResetAt
     ? new Date(clampMs(new Date(result.rateLimitResetAt).getTime(), nowMs)).toISOString()
     : undefined;
   const keyExtra = keyRateLimitedUntil ? { keyRateLimitedUntil } : {};
 
+  if (failureReason != null) {
+    const seatFamily = parseCreditsRequiredMessage(failureReason);
+    if (seatFamily) return { kind: "seat", model: seatFamily, source: "text", ...keyExtra };
+  }
+  if (result.creditsRequired && taskModelFamily) {
+    return { kind: "seat", model: taskModelFamily, source: "event", ...keyExtra };
+  }
+
   if (result.modelRateLimit) {
     const resetsAtSec = Math.floor(new Date(result.modelRateLimit.resetAt).getTime() / 1000);
     const { observedAt } = result.modelRateLimit;