@desplega.ai/agent-swarm 1.90.0 → 1.92.0

package/src/commands/profile-sync.ts

@@ -0,0 +1,310 @@
+/**
+ * Harness-agnostic FS → DB profile sync (worker-side, HTTP-only).
+ *
+ * Persists an agent's self-editable identity / config files back to the API:
+ *   - SOUL.md / IDENTITY.md / TOOLS.md / HEARTBEAT.md  (bundled identity POST)
+ *   - ~/.claude/CLAUDE.md                              (claude POST)
+ *   - /workspace/start-up.sh (agent-managed section)   (setup POST)
+ *
+ * This mirrors the per-session sync that the Claude plugin hooks
+ * (`src/hooks/hook.ts`) and the pi extension (`src/providers/pi-mono-extension.ts`)
+ * already perform, but lifted into a single shared module the runner can call
+ * at session end for ANY `hasLocalEnvironment` harness (claude, pi, codex,
+ * opencode). Before this module, codex/opencode had no sync path at all and
+ * pi's path could silently not-fire (2026-06-01 regression).
+ *
+ * Boundary rules (enforced by CI):
+ *   - MUST NOT import `src/be/db` or `bun:sqlite` (worker/API DB boundary —
+ *     `scripts/check-db-boundary.sh`). This module is HTTP-only.
+ *   - MUST NOT read the API key from `process.env` directly
+ *     (`scripts/check-api-key-boundary.sh`). The caller passes the key
+ *     (resolved via `getApiKey()`) in `opts.apiKey`.
+ *
+ * Hardening vs. the original copies: every POST checks `resp.ok` and surfaces
+ * a scrubbed warning on a non-2xx response or thrown error instead of
+ * silently swallowing it (the swallow is exactly what hid the 2026-06-01 pi
+ * drop). The sync stays NON-FATAL — a failed sync must never fail the task —
+ * but it must be VISIBLE.
+ */
+
+import { scrubSecrets } from "../utils/secret-scrubber.ts";
+
+export const SOUL_MD_PATH = "/workspace/SOUL.md";
+export const IDENTITY_MD_PATH = "/workspace/IDENTITY.md";
+export const TOOLS_MD_PATH = "/workspace/TOOLS.md";
+export const HEARTBEAT_MD_PATH = "/workspace/HEARTBEAT.md";
+export const SETUP_SCRIPT_PATH = "/workspace/start-up.sh";
+/**
+ * Claude Code's personal-file CLAUDE.md path. This is what the Claude plugin
+ * Stop hook reads and owns — the runner only uses it as a backstop for an
+ * all-Claude batch (never overwriting it with the workspace materialization).
+ */
+export const CLAUDE_MD_PATH = `${process.env.HOME}/.claude/CLAUDE.md`;
+/**
+ * Workspace CLAUDE.md — the agent-level instructions file the runner
+ * materializes from the `claudeMd` DB field at boot (`runner.ts`) and that the
+ * base-prompt truncation notice tells NON-Claude harnesses (codex/pi/opencode)
+ * to edit. Distinct from CLAUDE_MD_PATH; this is the FS→DB source for the
+ * non-Claude providers that previously had no sync path at all.
+ */
+export const WORKSPACE_CLAUDE_MD_PATH = "/workspace/CLAUDE.md";
+
+// Minimum length for SOUL.md and IDENTITY.md to prevent accidental corruption.
+// Mirrors `hook.ts` (raised from 100 to 500 after profile-corruption recurrences
+// where a short test sentinel synced into the real agent's DB row).
+const IDENTITY_FILE_MIN_LENGTH = 500;
+// Maximum file size we are willing to sync (>64KB is almost certainly not a
+// hand-edited identity/config file).
+const MAX_FILE_LENGTH = 65536;
+
+const SETUP_MARKER_START = "# === Agent-managed setup (from DB) ===";
+const SETUP_MARKER_END = "# === End agent-managed setup ===";
+
+export type ProfileSyncField = "identity" | "claude" | "setup";
+export type ProfileChangeSource = "self_edit" | "session_sync";
+
+export interface ProfileSyncOptions {
+  agentId: string;
+  apiUrl: string;
+  apiKey: string;
+  /** Session-end sync uses "session_sync"; on-edit hooks use "self_edit". */
+  changeSource?: ProfileChangeSource;
+  /** Subset of field groups to sync. Defaults to all three. */
+  fields?: ProfileSyncField[];
+  /**
+   * Path to read the CLAUDE.md source from. Defaults to CLAUDE_MD_PATH (Claude
+   * Code's personal-file path). Non-Claude local harnesses must pass
+   * WORKSPACE_CLAUDE_MD_PATH so their `/workspace/CLAUDE.md` edits sync. See
+   * `resolveClaudeMdPath`.
+   */
+  claudeMdPath?: string;
+  /** Injectable fetch for tests. Defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Choose which CLAUDE.md source the runner should sync, given the harness
+ * providers of the completed local sessions in a batch. Claude Code's personal
+ * file lives at `~/.claude/CLAUDE.md` (CLAUDE_MD_PATH — the Stop hook's path);
+ * every other local harness edits `/workspace/CLAUDE.md` (the file the runner
+ * materializes and the base prompt points them to). When a batch mixes
+ * providers, the presence of any non-Claude session means the workspace file is
+ * the edited source of truth; an all-Claude batch uses the personal-file path,
+ * where the runner only acts as a backstop for a Stop hook that didn't fire and
+ * never clobbers a real personal-file edit with the stale workspace copy.
+ */
+export function resolveClaudeMdPath(completedProviders: readonly string[]): string {
+  const anyNonClaude = completedProviders.some((p) => p !== "claude");
+  return anyNonClaude ? WORKSPACE_CLAUDE_MD_PATH : CLAUDE_MD_PATH;
+}
+
+/** A single profile-update POST body, tagged with a label for logging. */
+interface ProfilePayload {
+  label: string;
+  body: Record<string, unknown>;
+}
+
+/**
+ * Pure: given the raw `start-up.sh` contents, return the agent-managed content
+ * to sync, or `null` if there is nothing syncable. Extracts ONLY the content
+ * between the agent-managed markers when present (so operator content isn't
+ * duplicated); otherwise treats the whole file (minus a leading shebang) as
+ * agent-managed.
+ */
+export function extractSetupScriptContent(raw: string): string | null {
+  if (!raw.trim()) return null;
+
+  const startIdx = raw.indexOf(SETUP_MARKER_START);
+  const endIdx = raw.indexOf(SETUP_MARKER_END);
+
+  let content: string;
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Markers present — extract ONLY the content between them.
+    content = raw.substring(startIdx + SETUP_MARKER_START.length, endIdx).trim();
+  } else {
+    // No markers — agent created/replaced the entire file. Store as-is minus shebang.
+    content = raw.replace(/^#!\/bin\/bash\n/, "").trim();
+  }
+
+  if (!content || content.length > MAX_FILE_LENGTH) return null;
+  return content;
+}
+
+/**
+ * Pure: build the bundled identity-update body from raw file contents. Applies
+ * the trim / max-length guards and the SOUL/IDENTITY min-length guard. Returns
+ * an empty object when nothing is syncable (callers should skip the POST).
+ * `undefined` inputs mean the file was absent.
+ */
+export function buildIdentityPayload(files: {
+  soulMd?: string;
+  identityMd?: string;
+  toolsMd?: string;
+  heartbeatMd?: string;
+}): Record<string, string> {
+  const updates: Record<string, string> = {};
+
+  if (files.soulMd !== undefined) {
+    const content = files.soulMd;
+    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+      if (content.length < IDENTITY_FILE_MIN_LENGTH) {
+        console.error(
+          `[profile-sync] Skipping SOUL.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
+        );
+      } else {
+        updates.soulMd = content;
+      }
+    }
+  }
+
+  if (files.identityMd !== undefined) {
+    const content = files.identityMd;
+    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+      if (content.length < IDENTITY_FILE_MIN_LENGTH) {
+        console.error(
+          `[profile-sync] Skipping IDENTITY.md sync: content too short (${content.length} chars, minimum ${IDENTITY_FILE_MIN_LENGTH}). This prevents accidental profile corruption.`,
+        );
+      } else {
+        updates.identityMd = content;
+      }
+    }
+  }
+
+  if (files.toolsMd !== undefined) {
+    const content = files.toolsMd;
+    if (content.trim() && content.length <= MAX_FILE_LENGTH) {
+      updates.toolsMd = content;
+    }
+  }
+
+  if (files.heartbeatMd !== undefined) {
+    const content = files.heartbeatMd;
+    if (content.length <= MAX_FILE_LENGTH) {
+      updates.heartbeatMd = content;
+    }
+  }
+
+  return updates;
+}
+
+/** Reads a file's text, returning `undefined` when it does not exist. */
+export type FileReader = (path: string) => Promise<string | undefined>;
+
+/** Default file reader — reads from the worker's local FS via Bun. */
+async function readFileIfExists(path: string): Promise<string | undefined> {
+  try {
+    const file = Bun.file(path);
+    if (!(await file.exists())) return undefined;
+    return await file.text();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Collect the profile-update POST bodies to send. Each entry is one POST.
+ * `fields` selects which groups to include. The file reader is injectable so
+ * the field-selection / guard logic can be unit-tested without touching the FS.
+ */
+export async function collectProfilePayloads(
+  fields: ProfileSyncField[],
+  changeSource: ProfileChangeSource,
+  readFile: FileReader = readFileIfExists,
+  claudeMdPath: string = CLAUDE_MD_PATH,
+): Promise<ProfilePayload[]> {
+  const payloads: ProfilePayload[] = [];
+
+  if (fields.includes("identity")) {
+    const updates = buildIdentityPayload({
+      soulMd: await readFile(SOUL_MD_PATH),
+      identityMd: await readFile(IDENTITY_MD_PATH),
+      toolsMd: await readFile(TOOLS_MD_PATH),
+      heartbeatMd: await readFile(HEARTBEAT_MD_PATH),
+    });
+    if (Object.keys(updates).length > 0) {
+      payloads.push({ label: "identity", body: { ...updates, changeSource } });
+    }
+  }
+
+  if (fields.includes("claude")) {
+    const raw = await readFile(claudeMdPath);
+    if (raw?.trim() && raw.length <= MAX_FILE_LENGTH) {
+      payloads.push({ label: "claude", body: { claudeMd: raw, changeSource } });
+    }
+  }
+
+  if (fields.includes("setup")) {
+    const raw = await readFile(SETUP_SCRIPT_PATH);
+    if (raw !== undefined) {
+      const content = extractSetupScriptContent(raw);
+      if (content !== null) {
+        payloads.push({ label: "setup", body: { setupScript: content, changeSource } });
+      }
+    }
+  }
+
+  return payloads;
+}
+
+/**
+ * POST a single profile update. NON-FATAL but VISIBLE: a non-2xx response or a
+ * thrown error is logged (scrubbed) and swallowed so it never fails the task,
+ * but — unlike the original copies — it is never silently ignored.
+ */
+export async function postProfileUpdate(
+  opts: Pick<ProfileSyncOptions, "agentId" | "apiUrl" | "apiKey" | "fetchImpl">,
+  payload: ProfilePayload,
+): Promise<void> {
+  const doFetch = opts.fetchImpl ?? fetch;
+  try {
+    const resp = await doFetch(`${opts.apiUrl}/api/agents/${opts.agentId}/profile`, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${opts.apiKey}`,
+        "X-Agent-ID": opts.agentId,
+      },
+      body: JSON.stringify(payload.body),
+    });
+    if (!resp.ok) {
+      let detail = "";
+      try {
+        detail = (await resp.text()).slice(0, 500);
+      } catch {
+        /* ignore body read failure */
+      }
+      console.warn(
+        scrubSecrets(
+          `[profile-sync] ${payload.label} sync failed: HTTP ${resp.status}${detail ? ` — ${detail}` : ""}`,
+        ),
+      );
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(scrubSecrets(`[profile-sync] ${payload.label} sync errored: ${msg}`));
+  }
+}
+
+/**
+ * Sync the agent's local profile files back to the API. Reads SOUL/IDENTITY/
+ * TOOLS/HEARTBEAT/CLAUDE.md + the agent-managed section of start-up.sh and
+ * POSTs each changed group. Idempotent server-side: the profile route only
+ * writes a new `context_versions` row when the content hash changes, so a
+ * redundant sync (pi extension + runner, or an unchanged file) is a no-op.
+ *
+ * Always resolves (never throws) — failures are logged, not propagated.
+ */
+export async function syncProfileFilesToServer(opts: ProfileSyncOptions): Promise<void> {
+  const changeSource = opts.changeSource ?? "session_sync";
+  const fields = opts.fields ?? ["identity", "claude", "setup"];
+
+  const payloads = await collectProfilePayloads(
+    fields,
+    changeSource,
+    readFileIfExists,
+    opts.claudeMdPath ?? CLAUDE_MD_PATH,
+  );
+  for (const payload of payloads) {
+    await postProfileUpdate(opts, payload);
+  }
+}

package/src/commands/runner.ts

@@ -36,12 +36,15 @@ import { initTelemetry, telemetry } from "../telemetry.ts";
 import type { ProviderName, RepoGuidelines } from "../types.ts";
 import { getApiKey } from "../utils/api-key.ts";
 import { computeBudgetBackoffMs } from "../utils/budget-backoff.ts";
+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";
@@ -52,6 +55,7 @@ import { validateJsonSchema } from "../workflows/json-schema-validator.ts";
 import { interpolate } from "../workflows/template.ts";
 import { buildContextPreamble, buildResumeContextPreamble } from "./context-preamble.ts";
 import { awaitCredentials, BootMaxWaitExceededError, EX_CONFIG } from "./credential-wait.ts";
+import { resolveClaudeMdPath, syncProfileFilesToServer } from "./profile-sync.ts";
 import {
   buildCredStatusReport,
   buildLatestModelReport,
@@ -70,6 +74,34 @@ import "./templates.ts";
 /** Throttle interval for progress updates (3 seconds). */
 const PROGRESS_THROTTLE_MS = 3000;
 
+/** Minimum spacing for explicit runner GC sweeps. */
+const RUNNER_GC_MIN_INTERVAL_MS = 5 * 60 * 1000;
+
+let lastRunnerGcAt = 0;
+
+type GcCapableGlobal = typeof globalThis & { gc?: () => void };
+
+function scheduleRunnerGc(reason: string): boolean {
+  const gc = (globalThis as GcCapableGlobal).gc;
+  if (typeof gc !== "function") return false;
+
+  const now = Date.now();
+  if (now - lastRunnerGcAt < RUNNER_GC_MIN_INTERVAL_MS) return false;
+  lastRunnerGcAt = now;
+
+  const timer = setTimeout(() => {
+    const startedAt = Date.now();
+    try {
+      gc();
+      console.log(`[runner] Explicit GC completed after ${reason} in ${Date.now() - startedAt}ms`);
+    } catch (err) {
+      console.warn(`[runner] Explicit GC failed after ${reason}: ${err}`);
+    }
+  }, 0);
+  timer.unref?.();
+  return true;
+}
+
 /** Save PM2 process list for persistence across container restarts */
 async function savePm2State(role: string): Promise<void> {
   try {
@@ -394,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",
 ]);
 
 /**
@@ -1424,6 +1457,21 @@ interface RunningTask {
     keySuffix: string;
     keyIndex: number;
   };
+  /**
+   * Harness provider this session was actually spawned/resumed on, snapshotted
+   * at spawn time. The runner lets in-flight sessions finish on their original
+   * adapter after a live provider swap, so the session-end profile sync must
+   * decide based on THIS value — not the mutable global `state.harnessProvider`.
+   */
+  harnessProvider: ProviderName;
+  /**
+   * Whether this session ran in a local `/workspace` environment, snapshotted
+   * from `adapter.traits.hasLocalEnvironment` at spawn time. Gates the
+   * session-end FS → DB profile sync per finished session (a session that
+   * started local must still sync even if the worker was swapped to a remote
+   * provider before it completed, and vice versa).
+   */
+  hasLocalEnvironment: boolean;
 }
 
 /** Runner state for tracking concurrent tasks */
@@ -1438,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 */
@@ -3010,6 +3065,7 @@ async function spawnProviderProcess(
         }
         closeActiveToolSpans(result.exitCode === 0 ? "ok" : "error", result.failureReason);
         sessionSpan.end();
+        scheduleRunnerGc("session completion");
 
         return result;
       }),
@@ -3024,6 +3080,7 @@ async function spawnProviderProcess(
         });
         closeActiveToolSpans("error", error instanceof Error ? error.message : String(error));
         sessionSpan.end();
+        scheduleRunnerGc("session error");
         throw error;
       }),
     );
@@ -3046,6 +3103,11 @@ async function spawnProviderProcess(
     promise,
     result: null,
     credentialInfo,
+    // Snapshot the provider + local-env trait of the adapter this session is
+    // spawned on, so the session-end sync decision survives a live provider
+    // swap that mutates the global RunnerState (review finding 2).
+    harnessProvider: opts.harnessProvider,
+    hasLocalEnvironment: adapter.traits.hasLocalEnvironment,
   };
 
   // Non-blocking completion tracking
@@ -3073,6 +3135,8 @@ async function checkCompletedProcesses(
     cursorUpdates?: Array<{ channelId: string; ts: string }>;
     workingDir?: string;
     credentialInfo?: RunningTask["credentialInfo"];
+    harnessProvider: ProviderName;
+    hasLocalEnvironment: boolean;
   }> = [];
 
   for (const [taskId, task] of state.activeTasks) {
@@ -3088,6 +3152,8 @@ async function checkCompletedProcesses(
         cursorUpdates: task.cursorUpdates,
         workingDir: task.workingDir,
         credentialInfo: task.credentialInfo,
+        harnessProvider: task.harnessProvider,
+        hasLocalEnvironment: task.hasLocalEnvironment,
       });
     }
   }
@@ -3153,6 +3219,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();
           }
@@ -3217,6 +3289,40 @@ async function checkCompletedProcesses(
       }
     }
   }
+
+  // Harness-agnostic FS → DB profile sync at session end.
+  //
+  // The Claude plugin Stop hook and the pi extension sync SOUL/IDENTITY/TOOLS/
+  // CLAUDE.md + start-up.sh on their own, but codex/opencode have no such path
+  // and pi's can silently not-fire (2026-06-01 regression). Running the sync
+  // here — at the single point where every completed harness session converges
+  // (including crashes, since the process resolved with an exit code) — makes
+  // persistence reliable for ALL local-environment harnesses without
+  // per-adapter code. Idempotent: the profile route only writes a new context
+  // version when the content hash changes, so pi's double-sync and claude's
+  // redundant POST collapse to a no-op. NON-FATAL — never blocks completion;
+  // failures are logged (scrubbed) inside the helper.
+  //
+  // The local-env gate is per FINISHED session, snapshotted at spawn time —
+  // NOT the mutable global `state.hasLocalEnvironment`. The runner lets
+  // in-flight sessions finish on their original adapter after a live provider
+  // swap, so reading the global would (a) skip a session that started local
+  // when the worker has since flipped to a remote provider, and (b) sync stale
+  // local files after a remote session finishes once the worker flipped local.
+  // We sync when ANY finished session in this batch ran locally, and pick the
+  // CLAUDE.md source from those sessions' providers (review finding 2 + 1).
+  const localCompleted = completedTasks.filter((t) => t.hasLocalEnvironment);
+  if (apiConfig && localCompleted.length > 0) {
+    await syncProfileFilesToServer({
+      agentId: apiConfig.agentId,
+      apiUrl: apiConfig.apiUrl,
+      apiKey: apiConfig.apiKey,
+      changeSource: "session_sync",
+      claudeMdPath: resolveClaudeMdPath(localCompleted.map((t) => t.harnessProvider)),
+    }).catch((err) => {
+      console.warn(`[${role}] ${scrubSecrets(`Profile sync failed: ${err}`)}`);
+    });
+  }
 }
 
 const TEMPLATE_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
@@ -3299,7 +3405,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   // Get agent identity and swarm URL for base prompt
   const agentId = process.env.AGENT_ID || "unknown";
 
-  const apiUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+  const apiUrl = getMcpBaseUrl();
   const swarmUrl = process.env.SWARM_URL || "localhost";
   const apiKey = getApiKey();
 
@@ -3313,10 +3419,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}`);
@@ -3520,6 +3638,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
@@ -3600,6 +3719,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) {

package/src/hooks/hook.ts

@@ -11,6 +11,7 @@ import {
 } from "../be/memory/raters/llm";
 import type { Agent } from "../types";
 import { getApiKey } from "../utils/api-key";
+import { getMcpBaseUrl } from "../utils/constants";
 import { summarizeSession as runSummarize } from "../utils/internal-ai";
 import { checkToolLoop, clearToolHistory } from "./tool-loop-detection";
 
@@ -82,6 +83,27 @@ interface CancelledTasksResponse {
   cancelled: CancelledTask[];
 }
 
+/**
+ * Decide whether to show the "not registered — use join-swarm" nudge.
+ *
+ * Rules:
+ *  1. Only nudge on SessionStart — other events should not prompt re-registration.
+ *  2. If X-Agent-ID header is present the agent is pre-assigned; a null lookup
+ *     is transient, not a real "unregistered" state → suppress the nudge.
+ *  3. Only genuinely-unregistered agents (no X-Agent-ID, null lookup, SessionStart)
+ *     see the nudge.
+ */
+export function shouldShowRegistrationNudge(opts: {
+  agentInfoPresent: boolean;
+  eventType: string;
+  hasAgentIdHeader: boolean;
+}): boolean {
+  if (opts.agentInfoPresent) return false;
+  if (opts.eventType !== "SessionStart") return false;
+  if (opts.hasAgentIdHeader) return false;
+  return true;
+}
+
 /**
  * Check if a path is under the agent's own subdirectory on the shared disk.
  * Shared disk categories: thoughts, memory, downloads, misc.
@@ -150,7 +172,7 @@ async function readTaskFile(): Promise<TaskFileData | null> {
 async function fetchTaskDetails(
   taskId: string,
 ): Promise<{ id: string; task: string; progress?: string } | null> {
-  const apiUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+  const apiUrl = getMcpBaseUrl();
   const apiKey = getApiKey();
   const headers: Record<string, string> = {};
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
@@ -889,13 +911,15 @@ export async function handleHook(): Promise<void> {
         console.log(tray);
       }
     }
-  } else {
+  } else if (
+    shouldShowRegistrationNudge({
+      agentInfoPresent: false,
+      eventType: msg.hook_event_name,
+      hasAgentIdHeader: hasAgentIdHeader(),
+    })
+  ) {
     console.log(
-      `You are not registered in the agent swarm yet. Use the join-swarm tool to register yourself, then check your status with my-agent-info.
-
-If the ${SERVER_NAME} server is not running or disabled, disregard this message.
-
-${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?.headers["X-Agent-ID"]}, it will be used automatically on join-swarm.` : "You do not have a pre-defined agent ID, you will receive one when you join the swarm, or optionally you can request one when calling join-swarm."}`,
+      `You are not registered in the agent swarm yet. Use the join-swarm tool to register yourself, then check your status with my-agent-info.\n\nIf the ${SERVER_NAME} server is not running or disabled, disregard this message.\n\nYou do not have a pre-defined agent ID, you will receive one when you join the swarm, or optionally you can request one when calling join-swarm.`,
     );
   }
 
@@ -1151,8 +1175,7 @@ ${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?
             editedPath.startsWith("/workspace/shared/memory/"))
         ) {
           try {
-            const apiUrl =
-              process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+            const apiUrl = getMcpBaseUrl();
             const apiKey = getApiKey();
             const fileContent = await Bun.file(editedPath).text();
             const isShared = editedPath.startsWith("/workspace/shared/");

package/src/http/db-query.ts

@@ -11,6 +11,24 @@ export interface DbQueryResult {
   total: number;
 }
 
+export const DbQueryInputShape = {
+  sql: z.string().min(1).max(10_000).optional(),
+  query: z.string().min(1).max(10_000).optional().describe("Deprecated runtime alias for sql."),
+  params: z.array(z.any()).optional().default([]),
+};
+
+export const DbQueryInputSchema = z
+  .object(DbQueryInputShape)
+  .refine((body) => body.sql !== undefined || body.query !== undefined, {
+    message: "Either sql or query is required",
+  });
+
+export type DbQueryInput = z.infer<typeof DbQueryInputSchema>;
+
+export function resolveDbQuerySql(input: Pick<DbQueryInput, "sql" | "query">): string {
+  return input.sql ?? input.query ?? "";
+}
+
 function stripTrailingSemicolon(sql: string): string {
   return sql.trim().replace(/;\s*$/, "").trim();
 }
@@ -67,10 +85,7 @@ const dbQueryRoute = route({
   pattern: ["api", "db-query"],
   summary: "Execute a read-only SQL query",
   tags: ["Debug"],
-  body: z.object({
-    sql: z.string().min(1).max(10_000),
-    params: z.array(z.any()).optional().default([]),
-  }),
+  body: DbQueryInputSchema,
   responses: {
     200: {
       description: "Query results",
@@ -100,7 +115,7 @@ export async function handleDbQuery(
   if (!parsed) return true;
 
   try {
-    const result = executeReadOnlyQuery(parsed.body.sql, parsed.body.params);
+    const result = executeReadOnlyQuery(resolveDbQuerySql(parsed.body), parsed.body.params);
     json(res, result);
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);