@desplega.ai/agent-swarm 1.90.0 → 1.92.0

package/src/prompts/session-templates.ts

@@ -378,11 +378,9 @@ registerTemplate({
 
 You have access to the \`context-mode\` MCP tools (\`batch_execute\`, \`execute\`, \`execute_file\`, \`search\`, \`fetch_and_index\`, \`index\`) which compress tool output to save context window space. For data-heavy operations (web fetches, large file reads, CLI output processing), prefer these over raw Bash/WebFetch to avoid flooding your context window with raw output.
 
-When a tool returns more than a few dozen lines — JSON payloads, log tails, search results, API responses — route it through \`ctx_execute\` or \`ctx_batch_execute\` so only the derived answer enters your conversation. This is especially important for tasks that make many Bash/Read/MCP calls in sequence; each raw response compounds context pressure.
-
 ### Agent Scripts — for bulk, repetitive, or data-heavy work
 
-Use **scripts** (\`script-upsert\` + \`script-run\`) when a task involves repetitive SDK calls, large data processing, or deterministic multi-step pipelines. Scripts run out-of-process and return only their final result — none of the intermediate output floods your context window.
+Use **scripts** (\`script-upsert\` + \`script-run\`) when a task involves repetitive SDK calls, large data processing, or deterministic multi-step pipelines. Scripts run out-of-process and return only their final result.
 
 **Decision rubric — when to use scripts vs. other approaches:**
 
@@ -394,7 +392,6 @@ Use **scripts** (\`script-upsert\` + \`script-run\`) when a task involves repeti
 | Single expensive web fetch | \`ctx_fetch_and_index\` (context-mode) |
 | Multi-agent fan-out, parallel work, deterministic pipeline | **Workflow** |
 | One-off bash/TS with no reuse needed | \`code-mode run\` (Bash) |
-| Same logic needed across sessions/agents | **Named script** (\`script-upsert\` + reuse) |
 
 The 5 script tools (\`script-search\`, \`script-run\`, \`script-upsert\`, \`script-delete\`, \`script-query-types\`) are deferred tools. Call ToolSearch to load \`script-upsert\`, \`script-run\`, and \`script-query-types\` before using them.
 
@@ -407,6 +404,27 @@ The 5 script tools (\`script-search\`, \`script-run\`, \`script-upsert\`, \`scri
   category: "system",
 });
 
+registerTemplate({
+  eventType: "system.agent.seed_scripts",
+  header: "",
+  defaultBody: `
+### Pre-built Seed Scripts
+
+The swarm ships named scripts at global scope — each replaces a multi-step tool chain.
+See the \`swarm-scripts\` skill for the full catalog, signatures, and usage patterns.
+
+**At every task start (do this FIRST):** Run \`task-context-gathering\` with the task ID and 2-4 queries from the task description. Returns a slimmed task projection + deduped memories in one call — replaces task_get + memory_search loops.
+
+**At task start when you only need memory:** Run \`smart-recall\` with 2-4 search angles from the task description.
+
+**For any other repetitive multi-tool pattern:** Call \`script-search\` with a natural-language description. If a script exists, use it.
+
+Script tools are deferred — load via \`ToolSearch("select:script-search,script-run")\` before first use.
+`,
+  variables: [],
+  category: "system",
+});
+
 // system.agent.guidelines removed — its content (communication etiquette, todos)
 // is covered by worker/lead templates and filesystem template respectively.
 
@@ -602,6 +620,7 @@ registerTemplate({
 {{@template[system.agent.filesystem]}}
 {{@template[system.agent.self_awareness]}}
 {{@template[system.agent.context_mode]}}
+{{@template[system.agent.seed_scripts]}}
 
 {{@template[system.agent.system]}}
 {{@template[system.agent.share_urls]}}
@@ -623,6 +642,7 @@ registerTemplate({
 {{@template[system.agent.filesystem]}}
 {{@template[system.agent.self_awareness]}}
 {{@template[system.agent.context_mode]}}
+{{@template[system.agent.seed_scripts]}}
 
 {{@template[system.agent.system]}}
 {{@template[system.agent.share_urls]}}

package/src/providers/claude-adapter.ts

@@ -108,6 +108,45 @@ export function resolveClaudeBinary(
   return candidate || "claude";
 }
 
+const CLAUDE_BRIDGE_BINARY = "claude-bridge";
+
+/**
+ * Parse a boolean env toggle. Only true/1 enable and false/0 disable; unset
+ * and invalid values are treated as disabled.
+ *
+ * Exported for unit testing.
+ */
+export function parseClaudeBridgeEnabled(raw: string | undefined): boolean {
+  const normalized = raw?.trim().toLowerCase();
+  return normalized === "true" || normalized === "1";
+}
+
+/**
+ * Resolve the reloadable claude-bridge toggle from the same resolved-env
+ * overlay used for `CLAUDE_BINARY`.
+ *
+ * Exported for unit testing.
+ */
+export function resolveClaudeBridgeEnabled(
+  resolvedEnv: Record<string, string | undefined>,
+  fallbackEnv: Record<string, string | undefined> = process.env,
+): boolean {
+  const candidate =
+    resolvedEnv.SWARM_USE_CLAUDE_BRIDGE?.trim() || fallbackEnv.SWARM_USE_CLAUDE_BRIDGE?.trim();
+  return parseClaudeBridgeEnabled(candidate);
+}
+
+function resolveClaudeBinaryArgv(
+  resolvedEnv: Record<string, string | undefined>,
+  fallbackEnv: Record<string, string | undefined> = process.env,
+): { raw: string; argv: string[]; useClaudeBridge: boolean } {
+  const useClaudeBridge = resolveClaudeBridgeEnabled(resolvedEnv, fallbackEnv);
+  const raw = useClaudeBridge
+    ? CLAUDE_BRIDGE_BINARY
+    : resolveClaudeBinary(resolvedEnv, fallbackEnv);
+  return { raw, argv: parseClaudeBinary(raw), useClaudeBridge };
+}
+
 /**
  * Pre-seed `~/.claude.json` so the per-project trust-dialog ("Quick safety
  * check: Is this a project you trust?") doesn't block on first run.
@@ -336,6 +375,30 @@ export function buildClaudeCodeOtelEnv(
   return otelEnv;
 }
 
+/**
+ * Claude Code runtime defaults for ephemeral swarm harness sessions.
+ *
+ * These are plain subprocess env vars, not prompt content. They are injected
+ * after the resolved swarm config so the worker enforces the memory/privacy
+ * guardrails consistently per spawn. Statsig/DNT opt-out is intentionally
+ * separate from our Claude Code OTel export path, which is controlled by
+ * buildClaudeCodeOtelEnv.
+ */
+export function buildClaudeCodeRuntimeEnv(
+  _sourceEnv: Record<string, string | undefined>,
+): Record<string, string> {
+  return {
+    ENABLE_TOOL_SEARCH: "true",
+    CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING: "1",
+    CLAUDE_CODE_SKIP_PROMPT_HISTORY: "1",
+    CLAUDE_CODE_DISABLE_ATTACHMENTS: "1",
+    DISABLE_TELEMETRY: "1",
+    DO_NOT_TRACK: "1",
+    DISABLE_FEEDBACK_COMMAND: "1",
+    DISABLE_BUG_COMMAND: "1",
+  };
+}
+
 /**
  * Resolve the path at which the per-task system prompt is staged on disk.
  *
@@ -398,11 +461,13 @@ class ClaudeSession implements ProviderSession {
     // so the freshly-computed TRACEPARENT wins over any stale value the
     // container env might carry.
     const otelEnv = buildClaudeCodeOtelEnv(sourceEnv);
+    const runtimeEnv = buildClaudeCodeRuntimeEnv(sourceEnv);
     this.proc = Bun.spawn(cmd, {
       cwd: this.config.cwd,
       env: {
         ENABLE_PROMPT_CACHING_1H: "1",
         ...sourceEnv,
+        ...runtimeEnv,
         ...otelEnv,
         TASK_FILE: taskFilePath,
         // Belt-and-braces: TASK_FILE on disk can disappear mid-session (race
@@ -771,12 +836,9 @@ export class ClaudeAdapter implements ProviderAdapter {
     console.log(`\x1b[2m[claude]\x1b[0m Using credential: ${credType}`);
 
     // Resolve the argv prefix. Same flags (`-p`, `--model`, ...) work across
-    // alternates; only argv[0..n] changes. `CLAUDE_BINARY` accepts a single
-    // binary (`"shannon"`, `"/usr/local/bin/shannon"`) or a whitespace-separated
-    // command string (`"bunx @dexh/shannon"`, `"npx -y @dexh/shannon"`).
-    // Setting it to anything containing `shannon` opts into the dexhorthy/shannon
-    // variant, which drives `claude` interactively in tmux to stay on the
-    // subscription credit pool after the 2026-06-15 programmatic-credit split.
+    // alternates; only argv[0..n] changes. Prefer SWARM_USE_CLAUDE_BRIDGE=true
+    // for the Desplega-owned bridge. CLAUDE_BINARY remains as the low-level
+    // override for custom binaries and the deprecated shannon path.
     //
     // `config.env` carries the swarm_config overlay (resolved repo > agent > global
     // by `fetchResolvedEnv` in src/commands/runner.ts), so operators can flip
@@ -785,19 +847,30 @@ export class ClaudeAdapter implements ProviderAdapter {
     //
     // See `docs-site/.../shannon-experimental.mdx` for the user-facing guide
     // and `runbooks/harness-providers.md` for engineering notes.
-    const claudeBinaryRaw = resolveClaudeBinary(config.env || process.env);
-    const claudeBinaryArgv = parseClaudeBinary(claudeBinaryRaw);
+    const {
+      raw: claudeBinaryRaw,
+      argv: claudeBinaryArgv,
+      useClaudeBridge,
+    } = resolveClaudeBinaryArgv(config.env || process.env);
     const isShannon = claudeBinaryRaw.toLowerCase().includes("shannon");
+    const configuredClaudeBinaryRaw = resolveClaudeBinary(config.env || process.env);
+    if (configuredClaudeBinaryRaw.toLowerCase().includes("shannon")) {
+      console.warn(
+        "\x1b[33m[claude]\x1b[0m CLAUDE_BINARY=shannon is deprecated; set SWARM_USE_CLAUDE_BRIDGE=true to use @desplega.ai/claude-bridge.",
+      );
+    }
 
     console.log(
-      `\x1b[2m[${config.role}]\x1b[0m Resolved CLAUDE_BINARY: ${claudeBinaryArgv.join(" ")} (isShannon: ${isShannon})`,
+      `\x1b[2m[${config.role}]\x1b[0m Resolved claude binary: ${claudeBinaryArgv.join(" ")} (useClaudeBridge: ${useClaudeBridge}, isShannon: ${isShannon})`,
     );
 
-    // Fail fast: shannon shells out to tmux. If it's missing, surface a
-    // clear error here rather than letting the spawn fail opaquely.
-    if (isShannon && !Bun.which("tmux")) {
+    // Fail fast: shannon and claude-bridge both shell out to tmux. If it's
+    // missing, surface a clear error here rather than letting startup fail
+    // opaquely.
+    if ((isShannon || useClaudeBridge) && !Bun.which("tmux")) {
+      const label = useClaudeBridge ? "SWARM_USE_CLAUDE_BRIDGE=true" : "CLAUDE_BINARY=shannon";
       throw new Error(
-        "CLAUDE_BINARY=shannon requires 'tmux' on PATH (install via apt/brew). See runbooks/harness-providers.md.",
+        `${label} requires 'tmux' on PATH (install via apt/brew). See runbooks/harness-providers.md.`,
       );
     }
 

package/src/script-workflows/executor.ts

@@ -0,0 +1,110 @@
+import { existsSync } from "node:fs";
+import { mkdir, rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { ScriptRun } from "../types";
+
+export type ScriptExecutionResult = {
+  exitCode: number | null;
+  stderr: string;
+};
+
+export type ScriptExecutionHandle = {
+  pid: number | null;
+  tmpdir: string;
+  startedAtMs: number;
+  exited: Promise<ScriptExecutionResult>;
+  terminate(signal?: NodeJS.Signals): void;
+  cleanup(): Promise<void>;
+};
+
+export type StartScriptExecutionInput = {
+  run: ScriptRun;
+  baseUrl: string;
+  apiKey: string;
+};
+
+export interface ScriptExecutor {
+  start(input: StartScriptExecutionInput): Promise<ScriptExecutionHandle>;
+  isRunning(pid: number): boolean;
+  terminatePid(pid: number, signal?: NodeJS.Signals): void;
+}
+
+export function getScriptWorkflowHarnessPath(): string {
+  const runtimeDir = process.env.SCRIPT_WORKFLOW_RUNTIME_DIR;
+  if (!runtimeDir) return new URL("./harness.ts", import.meta.url).pathname;
+
+  const bundledHarness = `${resolve(runtimeDir)}/harness.bundle.js`;
+  if (!existsSync(bundledHarness)) {
+    throw new Error(
+      `Script workflow harness bundle not found at ${bundledHarness}. ` +
+        "Build/copy harness.bundle.js and set SCRIPT_WORKFLOW_RUNTIME_DIR to its directory.",
+    );
+  }
+  return bundledHarness;
+}
+
+export class LocalProcessScriptExecutor implements ScriptExecutor {
+  async start(input: StartScriptExecutionInput): Promise<ScriptExecutionHandle> {
+    const { run, baseUrl, apiKey } = input;
+    const tmpdir = `${process.env.TMPDIR ?? "/tmp"}/script-workflow-${run.id}`;
+    await mkdir(tmpdir, { recursive: true });
+    const sourceFile = `${tmpdir}/source.ts`;
+    const argsFile = `${tmpdir}/args.json`;
+    await Bun.write(sourceFile, run.source);
+    await Bun.write(argsFile, JSON.stringify(run.args ?? null));
+
+    const proc = Bun.spawn(["bun", "run", getScriptWorkflowHarnessPath()], {
+      cwd: tmpdir,
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "pipe",
+      env: {
+        PATH: process.env.PATH ?? "/usr/bin:/bin",
+        HOME: process.env.HOME ?? "/tmp",
+        LANG: process.env.LANG ?? "C.UTF-8",
+        LC_ALL: process.env.LC_ALL ?? "C.UTF-8",
+        TMPDIR: tmpdir,
+        AGENT_SWARM_API_KEY: apiKey,
+        MCP_BASE_URL: baseUrl,
+        SCRIPT_RUN_ID: run.id,
+        SCRIPT_RUN_AGENT_ID: run.agentId,
+        SCRIPT_RUN_TMPDIR: tmpdir,
+        SCRIPT_RUN_SOURCE_FILE: sourceFile,
+        SCRIPT_RUN_ARGS_FILE: argsFile,
+      },
+    });
+
+    const stderrPromise = new Response(proc.stderr).text().catch(() => "");
+
+    return {
+      pid: proc.pid,
+      tmpdir,
+      startedAtMs: Date.now(),
+      exited: proc.exited.then(async (exitCode) => ({
+        exitCode,
+        stderr: await stderrPromise,
+      })),
+      terminate: (signal = "SIGTERM") => {
+        proc.kill(signal);
+      },
+      cleanup: async () => {
+        await rm(tmpdir, { recursive: true, force: true });
+      },
+    };
+  }
+
+  isRunning(pid: number): boolean {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  terminatePid(pid: number, signal: NodeJS.Signals = "SIGTERM"): void {
+    process.kill(pid, signal);
+  }
+}
+
+export const localProcessScriptExecutor = new LocalProcessScriptExecutor();

package/src/script-workflows/harness.ts

@@ -0,0 +1,73 @@
+import { buildWorkflowCtx } from "./workflow-ctx";
+
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing required env ${name}`);
+  return value;
+}
+
+async function postStatus(
+  runId: string,
+  baseUrl: string,
+  agentId: string,
+  apiKey: string,
+  body: Record<string, unknown>,
+): Promise<void> {
+  const res = await fetch(`${baseUrl}/api/internal/script-runs/${runId}/status`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "X-Agent-ID": agentId,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    throw new Error(`status callback failed with ${res.status}: ${await res.text()}`);
+  }
+}
+
+const runId = requiredEnv("SCRIPT_RUN_ID");
+const agentId = requiredEnv("SCRIPT_RUN_AGENT_ID");
+const apiKey = requiredEnv("AGENT_SWARM_API_KEY");
+const baseUrl = requiredEnv("MCP_BASE_URL").replace(/\/$/, "");
+const sourceFile = requiredEnv("SCRIPT_RUN_SOURCE_FILE");
+const argsFile = requiredEnv("SCRIPT_RUN_ARGS_FILE");
+const userModulePath = `${requiredEnv("SCRIPT_RUN_TMPDIR")}/user-script.ts`;
+
+const heartbeat = setInterval(() => {
+  fetch(`${baseUrl}/api/internal/script-runs/${runId}/heartbeat`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "X-Agent-ID": agentId,
+    },
+  }).catch(() => {});
+}, 10_000);
+heartbeat.unref?.();
+
+try {
+  const source = await Bun.file(sourceFile).text();
+  const args = JSON.parse(await Bun.file(argsFile).text());
+  await Bun.write(userModulePath, source);
+  const mod = await import(userModulePath);
+  if (typeof mod.default !== "function") {
+    throw new Error("Script workflow must export a default function");
+  }
+  const ctx = buildWorkflowCtx({ runId, agentId, apiKey, baseUrl, args });
+  const output = await mod.default(args, ctx);
+  await postStatus(runId, baseUrl, agentId, apiKey, {
+    status: "completed",
+    output: output ?? null,
+  });
+  process.exit(0);
+} catch (err) {
+  console.error(err instanceof Error ? err.stack || err.message : String(err));
+  await postStatus(runId, baseUrl, agentId, apiKey, {
+    status: "failed",
+    error: err instanceof Error ? err.message : String(err),
+  });
+  process.exit(1);
+} finally {
+  clearInterval(heartbeat);
+}

package/src/script-workflows/label-lint.ts

@@ -0,0 +1,51 @@
+export type LabelLintError = {
+  label: string;
+  lineNumber: number | null;
+  detail: string;
+};
+
+export type LabelLintResult = { ok: true } | { ok: false; errors: LabelLintError[] };
+
+const CTX_STEP_LITERAL_LABEL_PATTERN = /ctx\.step\.\w+\(\s*"([^"]+)"/g;
+const LOOP_PATTERNS = [
+  /\bfor\s*\(/,
+  /\bwhile\s*\(/,
+  /\.map\s*\(/,
+  /\.forEach\s*\(/,
+  /\.reduce\s*\(/,
+  /\.flatMap\s*\(/,
+];
+
+export function lintWorkflowLabels(source: string): LabelLintResult {
+  const errors: LabelLintError[] = [];
+  const lines = source.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    CTX_STEP_LITERAL_LABEL_PATTERN.lastIndex = 0;
+    let match = CTX_STEP_LITERAL_LABEL_PATTERN.exec(line);
+    while (match !== null) {
+      const label = match[1];
+      if (!label) {
+        match = CTX_STEP_LITERAL_LABEL_PATTERN.exec(line);
+        continue;
+      }
+      const windowStart = Math.max(0, i - 10);
+      const context = lines.slice(windowStart, i + 1).join("\n");
+      if (!LOOP_PATTERNS.some((pattern) => pattern.test(context))) {
+        match = CTX_STEP_LITERAL_LABEL_PATTERN.exec(line);
+        continue;
+      }
+      errors.push({
+        label,
+        lineNumber: i + 1,
+        detail:
+          `Literal string label "${label}" at line ${i + 1} appears inside a loop. ` +
+          "Labels must be unique per run; use a template literal that includes the loop variable.",
+      });
+      match = CTX_STEP_LITERAL_LABEL_PATTERN.exec(line);
+    }
+  }
+
+  return errors.length > 0 ? { ok: false, errors } : { ok: true };
+}

package/src/script-workflows/limits.ts

@@ -0,0 +1,22 @@
+const DEFAULT_MAX_STEPS = 1000;
+const DEFAULT_MAX_WALL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_MAX_AGENT_TASKS = 50;
+
+function positiveIntEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+export function scriptRunMaxSteps(): number {
+  return positiveIntEnv("SCRIPT_RUN_MAX_STEPS", DEFAULT_MAX_STEPS);
+}
+
+export function scriptRunMaxWallMs(): number {
+  return positiveIntEnv("SCRIPT_RUN_MAX_WALL_MS", DEFAULT_MAX_WALL_MS);
+}
+
+export function scriptRunMaxAgentTasks(): number {
+  return positiveIntEnv("SCRIPT_RUN_MAX_AGENT_TASKS", DEFAULT_MAX_AGENT_TASKS);
+}

package/src/script-workflows/supervisor.ts

@@ -0,0 +1,139 @@
+import { getRunningScriptRuns, getScriptRun, updateScriptRun } from "../be/db";
+import type { ScriptRun } from "../types";
+import { getApiKey } from "../utils/api-key";
+import {
+  localProcessScriptExecutor,
+  type ScriptExecutionHandle,
+  type ScriptExecutor,
+} from "./executor";
+import { scriptRunMaxWallMs } from "./limits";
+
+type ManagedRun = {
+  execution: ScriptExecutionHandle;
+};
+
+const managed = new Map<string, ManagedRun>();
+let reconcileTimer: ReturnType<typeof setInterval> | null = null;
+let scriptExecutor: ScriptExecutor = localProcessScriptExecutor;
+
+function supervisorDisabled(): boolean {
+  return process.env.SCRIPT_RUN_SUPERVISOR_DISABLE === "true";
+}
+
+export function setScriptRunExecutor(executor: ScriptExecutor): void {
+  scriptExecutor = executor;
+}
+
+export async function startScriptRunProcess(
+  run: ScriptRun,
+  baseUrl: string,
+  apiKeyOverride?: string,
+): Promise<void> {
+  if (supervisorDisabled()) return;
+  if (managed.has(run.id)) return;
+  const apiKey = apiKeyOverride ?? getApiKey();
+  if (!apiKey) throw new Error("AGENT_SWARM_API_KEY is required to spawn script runs");
+  if (process.env.SCRIPT_WORKFLOW_DEBUG === "true") {
+    console.error(
+      `[script-workflows] spawning ${run.id} auth override=${apiKeyOverride ? "yes" : "no"} len=${apiKey.length}`,
+    );
+  }
+
+  const execution = await scriptExecutor.start({ run, baseUrl, apiKey });
+  managed.set(run.id, { execution });
+  updateScriptRun(run.id, {
+    status: "running",
+    pid: execution.pid,
+    lastHeartbeatAt: new Date().toISOString(),
+  });
+
+  execution.exited
+    .then(async ({ exitCode, stderr }) => {
+      const current = getScriptRun(run.id);
+      if (current && current.status === "running") {
+        if (exitCode !== 0) {
+          console.error(
+            `[script-workflows] run ${run.id} subprocess exited ${exitCode}: ${stderr.trim() || "(no stderr)"}`,
+          );
+        }
+        updateScriptRun(run.id, {
+          status: exitCode === 0 ? "completed" : "failed",
+          pid: null,
+          finishedAt: new Date().toISOString(),
+          error:
+            exitCode === 0
+              ? null
+              : stderr.trim() || `Script workflow subprocess exited ${exitCode}`,
+        });
+      }
+    })
+    .finally(async () => {
+      managed.delete(run.id);
+      await execution.cleanup();
+    });
+}
+
+export function terminateScriptRunProcess(runId: string): boolean {
+  const managedRun = managed.get(runId);
+  const run = getScriptRun(runId);
+  if (managedRun) {
+    managedRun.execution.terminate("SIGTERM");
+    managed.delete(runId);
+    return true;
+  }
+  if (run?.pid && scriptExecutor.isRunning(run.pid)) {
+    scriptExecutor.terminatePid(run.pid, "SIGTERM");
+    return true;
+  }
+  return false;
+}
+
+export function pauseScriptRunProcess(runId: string): void {
+  terminateScriptRunProcess(runId);
+  updateScriptRun(runId, { status: "paused", pid: null });
+}
+
+export function abortScriptRunLimit(runId: string, reason: string): void {
+  terminateScriptRunProcess(runId);
+  updateScriptRun(runId, {
+    status: "aborted_limit",
+    pid: null,
+    finishedAt: new Date().toISOString(),
+    error: reason,
+  });
+}
+
+export function reconcileScriptRuns(baseUrl: string): void {
+  if (supervisorDisabled()) return;
+  for (const run of getRunningScriptRuns()) {
+    if (run.status === "paused") continue;
+    const current = managed.get(run.id);
+    if (current && Date.now() - current.execution.startedAtMs > scriptRunMaxWallMs()) {
+      abortScriptRunLimit(run.id, `SCRIPT_RUN_MAX_WALL_MS exceeded (${scriptRunMaxWallMs()})`);
+      continue;
+    }
+    if (!current && (!run.pid || !scriptExecutor.isRunning(run.pid))) {
+      startScriptRunProcess(run, baseUrl).catch((err) => {
+        updateScriptRun(run.id, {
+          status: "failed",
+          pid: null,
+          finishedAt: new Date().toISOString(),
+          error: err instanceof Error ? err.message : String(err),
+        });
+      });
+    }
+  }
+}
+
+export function startScriptRunSupervisor(baseUrl: string): void {
+  if (supervisorDisabled() || reconcileTimer) return;
+  reconcileScriptRuns(baseUrl);
+  reconcileTimer = setInterval(() => reconcileScriptRuns(baseUrl), 15_000);
+  reconcileTimer.unref?.();
+}
+
+export function stopScriptRunSupervisor(): void {
+  if (reconcileTimer) clearInterval(reconcileTimer);
+  reconcileTimer = null;
+  for (const runId of [...managed.keys()]) terminateScriptRunProcess(runId);
+}