@desplega.ai/agent-swarm 1.91.0 → 1.92.1

package/src/be/seed-scripts/catalog/task-context-gathering.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+export const argsSchema = z.object({
+  taskId: z.string().describe("Task ID to fetch details for"),
+  queries: z
+    .array(z.string())
+    .min(1)
+    .describe("Search queries from the task description — 2-4 recommended"),
+  scope: z
+    .enum(["all", "agent", "swarm"])
+    .optional()
+    .describe("Memory scope filter (default all)"),
+  memoryLimit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Max memories per query before dedup (default 8)"),
+});
+
+function slimTask(task: any) {
+  if (!task || typeof task !== "object") return null;
+  return {
+    id: task.id,
+    status: task.status,
+    description: task.task,
+    dependsOn: task.dependsOn,
+    slackChannelId: task.slackChannelId,
+    slackThreadTs: task.slackThreadTs,
+    createdAt: task.createdAt,
+    finishedAt: task.finishedAt,
+    agentId: task.agentId,
+    output: task.output,
+    failureReason: task.failureReason,
+  };
+}
+
+/** Fetch slim task details plus deduped multi-query memories for task onboarding. */
+export default async function taskContextGathering(args: any, ctx: any) {
+  const parsed = argsSchema.safeParse(args);
+  if (!parsed.success) return { error: "invalid args: " + parsed.error.message };
+  const { taskId, queries, scope = "all", memoryLimit = 8 } = parsed.data;
+
+  const taskRes: any = await ctx.swarm.task_get({ taskId });
+  const taskPayload = taskRes?.data ?? taskRes;
+  if (taskPayload?.success === false) {
+    return { error: taskPayload.message ?? "task_get failed", taskId };
+  }
+
+  const allResults: any[] = [];
+  for (const query of queries) {
+    const res: any = await ctx.swarm.memory_search({ query, scope, limit: memoryLimit });
+    const payload = res?.data ?? res;
+    const results = payload?.results ?? [];
+    for (const memory of results) {
+      allResults.push({ ...memory, querySource: query });
+    }
+  }
+
+  const byId = new Map<string, any>();
+  const hitCounts = new Map<string, number>();
+  for (const memory of allResults) {
+    const id = typeof memory.id === "string" ? memory.id : JSON.stringify(memory);
+    hitCounts.set(id, (hitCounts.get(id) ?? 0) + 1);
+    const existing = byId.get(id);
+    const similarity = typeof memory.similarity === "number" ? memory.similarity : 0;
+    const existingSimilarity =
+      existing && typeof existing.similarity === "number" ? existing.similarity : -Infinity;
+    if (!existing || similarity > existingSimilarity) byId.set(id, memory);
+  }
+
+  const memories = Array.from(byId.entries()).map(([id, memory]) => {
+    const hits = hitCounts.get(id) ?? 1;
+    const similarity = typeof memory.similarity === "number" ? memory.similarity : 0;
+    return {
+      ...memory,
+      hits,
+      compositeScore: similarity + 0.05 * hits,
+    };
+  });
+  memories.sort((a: any, b: any) => b.compositeScore - a.compositeScore);
+
+  return {
+    task: slimTask(taskPayload?.task),
+    requestedBy: taskPayload?.requestedBy,
+    attachments: taskPayload?.attachments ?? [],
+    queriesRun: queries.length,
+    totalCandidates: allResults.length,
+    uniqueMemories: memories.length,
+    memories: memories.slice(0, memoryLimit * 2),
+  };
+}

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { publishCatalogReportPage } from "./catalog-report";
 
 export const argsSchema = z.object({
   days: z
@@ -17,6 +18,7 @@ export const argsSchema = z.object({
     .positive()
     .optional()
     .describe("Max failed tasks to scan (default 500)"),
+  publishPage: z.boolean().optional().describe("Publish an authed HTML page (default true)"),
 });
 
 const REASON_PATTERNS: any[] = [
@@ -46,6 +48,7 @@ export default async function taskFailureAudit(args: any, ctx: any) {
   const days = parsed.data.days || 7;
   const groupBy = parsed.data.groupBy || "reason";
   const limit = parsed.data.limit || 500;
+  const publishPage = parsed.data.publishPage !== false;
 
   const since = new Date(Date.now() - days * 86400000).toISOString();
   const res: any = await ctx.swarm.task_list({
@@ -77,11 +80,55 @@ export default async function taskFailureAudit(args: any, ctx: any) {
     .map((k: string) => groups[k])
     .sort((a: any, b: any) => b.count - a.count);
 
-  return {
+  const result: any = {
     days,
     groupBy,
     totalFailed: tasks.length,
     clusterCount: rows.length,
     groups: rows,
   };
+
+  if (publishPage) {
+    result.page = await publishCatalogReportPage(
+      {
+        title: "Task Failure Audit",
+        slug: "task-failure-audit",
+        description: "Clustered audit of recently failed swarm tasks.",
+        generatedAt: new Date().toISOString(),
+        lede: `Clustered ${tasks.length} failed task(s) over ${days} day(s) by ${groupBy}.`,
+        metrics: [
+          ["Failed tasks", tasks.length],
+          ["Clusters", rows.length],
+          ["Days", days],
+          ["Limit", limit],
+        ],
+        sections: [
+          {
+            key: "failure-clusters",
+            goal: "Surface repeated failure modes before they become operational drift.",
+            findingCount: rows.length,
+            checks: { totalFailed: tasks.length, clusterCount: rows.length, groupBy },
+            findings: rows.map((group: any) => ({
+              id: `failure.${group.key}`,
+              severity: group.count >= 5 ? "high" : group.count >= 2 ? "medium" : "low",
+              summary: `${group.count} failed task(s) in ${group.key}.`,
+              action: "Inspect the sample task IDs and decide whether this needs a fix, retry, or HEARTBEAT watch item.",
+              samples: [
+                {
+                  key: group.key,
+                  count: group.count,
+                  taskIds: group.taskIds,
+                  sampleReason: group.sampleReason,
+                },
+              ],
+            })),
+          },
+        ],
+        appendix: result,
+      },
+      ctx,
+    );
+  }
+
+  return result;
 }

package/src/be/seed-scripts/catalog/tool-usage.ts

@@ -25,7 +25,7 @@ export default async function toolUsage(args: any, ctx: any) {
   const agentId = parsed.data.agentId;
 
   const agentFilter = agentId ? `AND agent_id = '${agentId}'` : "";
-  const query = `
+  const sql = `
     SELECT tool_name, count(*) as calls
     FROM session_logs
     WHERE tool_name IS NOT NULL
@@ -36,9 +36,12 @@ export default async function toolUsage(args: any, ctx: any) {
     LIMIT ${limit}
   `;
 
-  const res: any = await ctx.swarm.db_query({ query });
+  const res: any = await ctx.swarm.db_query({ sql });
   const payload = res?.data ?? res;
-  const rows: any[] = payload?.rows ?? [];
+  const columns: string[] = payload?.columns ?? [];
+  const rows: any[] = (payload?.rows ?? []).map((row: any[]) =>
+    Object.fromEntries(columns.map((column, index) => [column, row[index]])),
+  );
 
   const totalCalls = rows.reduce((sum: number, r: any) => sum + (r.calls ?? 0), 0);
 

package/src/be/seed-scripts/index.ts

@@ -22,6 +22,9 @@ import { getScript, upsertScriptByName } from "../scripts/db";
 import { extractArgsJsonSchema } from "../scripts/extract-schema";
 import { typecheckScript } from "../scripts/typecheck";
 import type { Seeder, SeedItem } from "../seed/types";
+import bootTriageSrc from "./catalog/boot-triage.ts" with { type: "text" };
+// @ts-expect-error Bun text imports return the raw source string for bundling standalone scripts.
+import catalogReportSrc from "./catalog/catalog-report.ts" with { type: "text" };
 import compoundInsightsSrc from "./catalog/compound-insights.ts" with { type: "text" };
 import dateResolveSrc from "./catalog/date-resolve.ts" with { type: "text" };
 import fetchReadableSrc from "./catalog/fetch-readable.ts" with { type: "text" };
@@ -30,9 +33,12 @@ import groupCountSrc from "./catalog/group-count.ts" with { type: "text" };
 import jsonQuerySrc from "./catalog/json-query.ts" with { type: "text" };
 import linearIssueSrc from "./catalog/linear-issue.ts" with { type: "text" };
 import memoryDedupCheckSrc from "./catalog/memory-dedup-check.ts" with { type: "text" };
+import memoryEvalSrc from "./catalog/memory-eval.ts" with { type: "text" };
+import opsCatalogAuditSrc from "./catalog/ops-catalog-audit.ts" with { type: "text" };
 import scheduleHealthSrc from "./catalog/schedule-health.ts" with { type: "text" };
 import slackThreadFlattenSrc from "./catalog/slack-thread-flatten.ts" with { type: "text" };
 import smartRecallSrc from "./catalog/smart-recall.ts" with { type: "text" };
+import taskContextGatheringSrc from "./catalog/task-context-gathering.ts" with { type: "text" };
 import taskFailureAuditSrc from "./catalog/task-failure-audit.ts" with { type: "text" };
 import textDiffSrc from "./catalog/text-diff.ts" with { type: "text" };
 import toolUsageSrc from "./catalog/tool-usage.ts" with { type: "text" };
@@ -48,6 +54,14 @@ export type SeedScript = {
 // module's default export, so the cast restores the real shape.
 const asText = (s: unknown): string => s as string;
 
+const CATALOG_REPORT_IMPORT_RE = /^import\s+\{[^}]*\}\s+from "\.\/catalog-report";\n\n?/m;
+
+function bundleCatalogReport(source: string): string {
+  const helper = asText(catalogReportSrc);
+  if (!CATALOG_REPORT_IMPORT_RE.test(source)) return source;
+  return `${helper}\n\n${source.replace(CATALOG_REPORT_IMPORT_RE, "")}`;
+}
+
 export const SEED_SCRIPTS: SeedScript[] = [
   {
     name: "gh-pr-snapshot",
@@ -101,7 +115,7 @@ export const SEED_SCRIPTS: SeedScript[] = [
       "Scan recently failed swarm tasks and cluster them by failure reason, agent or schedule to surface recurring problems.",
     intent:
       "Find patterns in swarm task failures — which agent, schedule or error keeps breaking — for a reliability review.",
-    source: asText(taskFailureAuditSrc),
+    source: bundleCatalogReport(asText(taskFailureAuditSrc)),
   },
   {
     name: "memory-dedup-check",
@@ -134,13 +148,21 @@ export const SEED_SCRIPTS: SeedScript[] = [
       "Recall relevant memories using multiple search angles — better coverage than a single query. Use for task onboarding, context gathering, or before writing new memories.",
     source: asText(smartRecallSrc),
   },
+  {
+    name: "task-context-gathering",
+    description:
+      "Get task details and recall relevant memories in one call — returns a slimmed task projection plus deduped and reranked memories from multi-query fan-out.",
+    intent:
+      "Task onboarding: one call instead of task_get plus multiple memory_search calls. Pass the task description split into 2-4 natural-language queries.",
+    source: asText(taskContextGatheringSrc),
+  },
   {
     name: "schedule-health",
     description:
       "Per-schedule failure rate check over recent tasks — flags schedules with failure rates above a configurable threshold.",
     intent:
       "Find unhealthy schedules that keep failing — for daily compounding, reliability reviews, or ops triage.",
-    source: asText(scheduleHealthSrc),
+    source: bundleCatalogReport(asText(scheduleHealthSrc)),
   },
   {
     name: "tool-usage",
@@ -153,10 +175,34 @@ export const SEED_SCRIPTS: SeedScript[] = [
   {
     name: "compound-insights",
     description:
-      "All-in-one swarm-wide daily ops snapshot: task completion/failure summary, real failure clusters (excludes superseded/cancelled bookkeeping), schedule health flags, tool usage top-25, memory health stats, and a per-agent breakdown. Aggregates across ALL agents via direct read-only SQL.",
+      "All-in-one swarm-wide daily ops snapshot: task completion/failure summary, real failure clusters (excludes superseded/cancelled bookkeeping), schedule health flags, tool usage top-25, memory health/pollution stats, seed-script candidate tool triplets, and a per-agent breakdown. Aggregates across ALL agents via direct read-only SQL.",
+    intent:
+      "Single-call daily compounding Phase 0 helper — replaces ~25 raw tool roundtrips with one compressed JSON result covering every agent. For daily evolution, self-scripting candidates, ops reviews, or heartbeat context.",
+    source: bundleCatalogReport(asText(compoundInsightsSrc)),
+  },
+  {
+    name: "memory-eval",
+    description:
+      "3-axis memory quality evaluation: carry-forward context (do follow-up tasks retrieve useful memories from prior tasks?), follow preferences (are CLAUDE.md/IDENTITY.md/SOUL.md/TOOLS.md memories retrieved and useful?), and stay current (what fraction of retrieved memories are fresh vs stale?). Outputs a baseline report to agent-fs + a swarm Page.",
+    intent:
+      "Measure memory system health across OpenAI Dreaming-inspired axes — before/after baseline for architecture changes, blog-post numbers, daily quality monitoring.",
+    source: asText(memoryEvalSrc),
+  },
+  {
+    name: "ops-catalog-audit",
+    description:
+      "Audit-as-code catalog check for schedules, workflows, and prompt/template drift. Clusters actionable findings by goal and can publish an authed HTML report page.",
+    intent:
+      "Re-run the ops inventory audit in one call: duplicate/dead schedules, code-work routing risks, enabled workflow fixtures, structured-output gate gaps, prompt registry drift, stale hosts, and systemDefault skill duplicates.",
+    source: bundleCatalogReport(asText(opsCatalogAuditSrc)),
+  },
+  {
+    name: "boot-triage",
+    description:
+      "Post-restart heartbeat triage snapshot: deploy restart PR context, recent real failures, stuck offline-agent work, orphaned tasks, and superseded tasks missing resume children.",
     intent:
-      "Single-call daily compounding Phase 0 helper — replaces ~25 raw tool roundtrips with one compressed JSON result covering every agent. For daily evolution, ops reviews, or heartbeat context.",
-    source: asText(compoundInsightsSrc),
+      "Run immediately after a swarm restart to gather deterministic boot triage data in one read-only call before the Lead decides what to retry, cancel, or escalate.",
+    source: asText(bootTriageSrc),
   },
 ];
 

package/src/be/seed-skills/index.ts

@@ -25,10 +25,10 @@ import kvStorageContent from "../../../templates/skills/kv-storage/content.md" w
 };
 import pagesConfig from "../../../templates/skills/pages/config.json" with { type: "text" };
 import pagesContent from "../../../templates/skills/pages/content.md" with { type: "text" };
-import scheduledTaskResilienceConfig from "../../../templates/skills/scheduled-task-resilience/config.json" with {
+import scriptWorkflowsConfig from "../../../templates/skills/script-workflows/config.json" with {
   type: "text",
 };
-import scheduledTaskResilienceContent from "../../../templates/skills/scheduled-task-resilience/content.md" with {
+import scriptWorkflowsContent from "../../../templates/skills/script-workflows/content.md" with {
   type: "text",
 };
 import swarmScriptsConfig from "../../../templates/skills/swarm-scripts/config.json" with {
@@ -71,7 +71,7 @@ const BUILT_IN_SKILL_SOURCES = [
   { config: artifactsConfig, body: artifactsContent },
   { config: kvStorageConfig, body: kvStorageContent },
   { config: pagesConfig, body: pagesContent },
-  { config: scheduledTaskResilienceConfig, body: scheduledTaskResilienceContent },
+  { config: scriptWorkflowsConfig, body: scriptWorkflowsContent },
   { config: swarmScriptsConfig, body: swarmScriptsContent },
   { config: workflowIterateConfig, body: workflowIterateContent },
   { config: workflowStructuredOutputConfig, body: workflowStructuredOutputContent },

package/src/be/skill-sync.ts

@@ -8,10 +8,11 @@
  * This runs on the API side — workers call it via POST /api/skills/sync-filesystem.
  */
 
+import type { Dirent } from "node:fs";
 import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { getAgentSkills } from "./db";
+import { dirname, join } from "node:path";
+import { getAgentSkills, getSkillFiles } from "./db";
 
 export interface SkillSyncResult {
   synced: number;
@@ -29,11 +30,68 @@ export interface SkillSyncResult {
  */
 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;
+}
+
 /**
  * Sync agent's installed skills to the filesystem.
  *
  * For simple skills (content in DB): writes SKILL.md to ~/.claude/skills/<name>/
- * For complex skills (isComplex=true): skipped here (handled by npx in entrypoint)
+ * 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.
  */
 export function syncSkillsToFilesystem(
   agentId: string,
@@ -44,6 +102,7 @@ export function syncSkillsToFilesystem(
   const home = homeOverride ?? homedir();
   const errors: string[] = [];
   let synced = 0;
+  let removed = 0;
 
   // Directories to write to
   const skillDirs: string[] = [];
@@ -67,7 +126,8 @@ export function syncSkillsToFilesystem(
 
   for (const skill of skills) {
     if (!skill.isActive || !skill.isEnabled) continue;
-    if (skill.isComplex) continue; // Complex skills handled by npx
+    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)
@@ -75,6 +135,9 @@ export function syncSkillsToFilesystem(
     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);
@@ -83,14 +146,36 @@ export function syncSkillsToFilesystem(
 
       try {
         mkdirSync(skillDir, { recursive: true });
+        removed += reconcileManagedSkillFiles(skillDir, currentBundledFilePaths);
         writeFileSync(skillFile, skill.content, "utf-8");
         writeFileSync(markerFile, "", "utf-8");
         synced++;
       } catch (err) {
-        errors.push(
-          `${skill.name} -> ${skillDir}: ${err instanceof Error ? err.message : "Unknown error"}`,
+        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}`,
+          );
+        }
+      }
     }
   }
 
@@ -98,7 +183,6 @@ export function syncSkillsToFilesystem(
   // present). Leaves user-installed personal skills alone — important on
   // local dev where ~/.codex/skills holds skills the user installed
   // outside the swarm.
-  let removed = 0;
   for (const baseDir of skillDirs) {
     if (!existsSync(baseDir)) continue;
 

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

@@ -41,6 +41,23 @@ const VALIDATED_KEYS: Record<string, (value: unknown) => string | null> = {
     if (parsed.success) return null;
     return `Invalid HARNESS_PROVIDER value (must be one of: ${ProviderNameSchema.options.join(", ")})`;
   },
+  // Codex credits-exhausted cooldown (ms). Permissive on range here (positive
+  // integer) — the worker clamps to [5m, 7d] via resolveCodexCreditsExhaustedCooldownMs.
+  CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS: (value) => {
+    const str = String(value).trim();
+    if (!/^\d+$/.test(str) || Number(str) <= 0) {
+      return "Invalid CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS (must be a positive integer of milliseconds)";
+    }
+    return null;
+  },
+  SWARM_USE_CLAUDE_BRIDGE: (value) => {
+    if (typeof value !== "string") {
+      return "Invalid SWARM_USE_CLAUDE_BRIDGE value (must be one of: true, false, 1, 0)";
+    }
+    const normalized = value.trim().toLowerCase();
+    if (["true", "false", "1", "0"].includes(normalized)) return null;
+    return "Invalid SWARM_USE_CLAUDE_BRIDGE value (must be one of: true, false, 1, 0)";
+  },
 };
 
 export function validateConfigValue(key: string, value: unknown): string | null {

package/src/commands/runner.ts

@@ -40,9 +40,11 @@ import { getMcpBaseUrl } from "../utils/constants.ts";
 import { getContextWindowSize } from "../utils/context-window.ts";
 import { type CredentialSelection, resolveCredentialPools } from "../utils/credentials.ts";
 import {
+  isCodexCreditsExhaustedMessage,
   isRateLimitMessage,
   MAX_RATE_LIMIT_RESET_MS,
   parseRateLimitResetTime,
+  resolveCodexCreditsExhaustedCooldownMs,
 } from "../utils/error-tracker.ts";
 import { resolveHarnessProvider } from "../utils/harness-provider.ts";
 import { prettyPrintLine, prettyPrintStderr } from "../utils/pretty-print.ts";
@@ -424,6 +426,7 @@ async function fetchResolvedEnv(
 const RELOADABLE_ENV_KEYS: ReadonlySet<string> = new Set([
   "MODEL_OVERRIDE",
   "AGENT_FS_SHARED_ORG_ID",
+  "SWARM_USE_CLAUDE_BRIDGE",
 ]);
 
 /**
@@ -1483,6 +1486,13 @@ interface RunnerState {
    * (per-task live re-resolution) will mutate this between tasks.
    */
   harnessProvider: ProviderName;
+  /**
+   * Effective Codex credits-exhausted cooldown (ms), resolved from `swarm_config`
+   * (key `CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS`) > default 2h constant, clamped to
+   * [5m, 7d]. Reconciled live by `applySwarmConfigDrift` — read at the cooldown
+   * application site so a fresh value applies to the next credits-exhausted failure.
+   */
+  codexCreditsExhaustedCooldownMs: number;
 }
 
 /** Buffer for session logs */
@@ -3117,6 +3127,7 @@ async function checkCompletedProcesses(
   state: RunnerState,
   role: string,
   apiConfig?: ApiConfig,
+  cancelledSignaled?: Set<string>,
 ): Promise<void> {
   const completedTasks: Array<{
     taskId: string;
@@ -3151,6 +3162,9 @@ 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) {
     state.activeTasks.delete(taskId);
+    vcsDetectedTasks.delete(taskId);
+    vcsCheckTimestamps.delete(taskId);
+    cancelledSignaled?.delete(taskId);
 
     if (apiConfig) {
       removeActiveSession(apiConfig, taskId);
@@ -3209,6 +3223,12 @@ async function checkCompletedProcesses(
             console.log(
               `[credentials] Parsed rate limit reset time from error: ${rateLimitedUntil}`,
             );
+          } else if (isCodexCreditsExhaustedMessage(failureReason)) {
+            const cooldownMs = state.codexCreditsExhaustedCooldownMs;
+            rateLimitedUntil = new Date(Date.now() + cooldownMs).toISOString();
+            console.log(
+              `[credentials] Codex credits exhausted — applying cooldown (${cooldownMs}ms): ${rateLimitedUntil}`,
+            );
           } else {
             rateLimitedUntil = new Date(Date.now() + 5 * 60 * 1000).toISOString();
           }
@@ -3403,10 +3423,22 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   // Failures (network, API down, malformed value) fall back to env then "claude"
   // so a swarm_config outage cannot wedge boot.
   let bootProvider: ProviderName;
+  // Codex credits-exhausted cooldown is sourced solely from the global swarm_config
+  // (key `CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS`). Initialize to the default constant
+  // for the case where it is unset, then apply the swarm_config value below; on a
+  // boot-fetch failure it stays at the default. Reconciled live thereafter by
+  // `applySwarmConfigDrift`.
+  let bootCooldownMs = resolveCodexCreditsExhaustedCooldownMs(undefined);
   try {
-    bootProvider = (await fetchResolvedEnv(apiUrl, apiKey, agentId)).resolvedProvider;
+    const bootEnv = await fetchResolvedEnv(apiUrl, apiKey, agentId);
+    bootProvider = bootEnv.resolvedProvider;
+    bootCooldownMs = resolveCodexCreditsExhaustedCooldownMs(
+      bootEnv.env.CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS,
+    );
   } catch (err) {
-    console.warn(`[runner] fetchResolvedEnv failed at boot, falling back to env: ${err}`);
+    console.warn(
+      `[runner] fetchResolvedEnv failed at boot, falling back to env for provider and the default cooldown: ${err}`,
+    );
     bootProvider = resolveHarnessProvider({}, process.env);
   }
   console.log(`[runner] Resolved HARNESS_PROVIDER: ${bootProvider}`);
@@ -3610,6 +3642,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
     activeTasks: new Map(),
     maxConcurrent,
     harnessProvider: bootProvider,
+    codexCreditsExhaustedCooldownMs: bootCooldownMs,
   };
 
   // Track tasks already signaled for cancellation to avoid repeated SIGTERM
@@ -3690,6 +3723,18 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
       agentVisibleChanged = true;
     }
 
+    // (2b) Codex credits-exhausted cooldown — operator-tunable live. Not
+    // agent-visible (doesn't change provider/maxConcurrent → no re-register).
+    const nextCooldown = resolveCodexCreditsExhaustedCooldownMs(
+      freshEnv.CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS,
+    );
+    if (nextCooldown !== state.codexCreditsExhaustedCooldownMs) {
+      console.log(
+        `[${role}] [config] codexCreditsExhaustedCooldownMs: ${state.codexCreditsExhaustedCooldownMs} → ${nextCooldown}`,
+      );
+      state.codexCreditsExhaustedCooldownMs = nextCooldown;
+    }
+
     // (3) Apply the small allowlist of safe-to-mutate env keys to process.env.
     const changedKeys = applyResolvedEnvToProcessEnv(freshEnv);
     if (changedKeys.length > 0) {
@@ -4081,7 +4126,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
 
         // Wait if at capacity (though unlikely on fresh startup)
         while (state.activeTasks.size >= state.maxConcurrent) {
-          await checkCompletedProcesses(state, role, apiConfig);
+          await checkCompletedProcesses(state, role, apiConfig, cancelledSignaled);
           await Bun.sleep(1000);
         }
 
@@ -4300,7 +4345,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
     await pingServer(apiConfig, role);
 
     // Check for completed processes first and ensure tasks are marked as finished
-    await checkCompletedProcesses(state, role, apiConfig);
+    await checkCompletedProcesses(state, role, apiConfig, cancelledSignaled);
 
     // Live HARNESS_PROVIDER reconciliation. Re-fetches `swarm_config` (overlaid
     // on env) and swaps the adapter if the resolved provider changed —