@desplega.ai/agent-swarm 1.149.1 → 1.151.0

package/src/be/migrations/154_routing_source.sql

@@ -0,0 +1,3 @@
+-- Historical routing reasons have unknown provenance; do not backfill them.
+ALTER TABLE agent_tasks ADD COLUMN routing_source TEXT
+  CHECK (routing_source IN ('declared', 'engine_default'));

package/src/be/migrations/155_extensions.sql

@@ -0,0 +1,66 @@
+CREATE TABLE extensions (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  description TEXT NOT NULL DEFAULT '',
+  runtime TEXT NOT NULL DEFAULT 'api' CHECK(runtime IN ('api', 'worker')),
+  manifestJson TEXT NOT NULL,
+  contentHash TEXT NOT NULL,
+  version INTEGER NOT NULL DEFAULT 1,
+  activeVersion INTEGER NOT NULL DEFAULT 1,
+  enabled INTEGER NOT NULL DEFAULT 0,
+  priority INTEGER NOT NULL DEFAULT 100,
+  configJson TEXT NOT NULL DEFAULT '{}',
+  status TEXT NOT NULL DEFAULT 'disabled'
+    CHECK(status IN ('disabled', 'enabled', 'error', 'auto-disabled')),
+  consecutiveFailures INTEGER NOT NULL DEFAULT 0,
+  lastError TEXT,
+  agentId TEXT,
+  createdByAgentId TEXT,
+  created_by TEXT,
+  updated_by TEXT,
+  createdAt TEXT NOT NULL DEFAULT (datetime('now')),
+  updatedAt TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE extension_files (
+  id TEXT PRIMARY KEY,
+  extensionId TEXT NOT NULL REFERENCES extensions(id) ON DELETE CASCADE,
+  path TEXT NOT NULL,
+  content TEXT NOT NULL,
+  contentHash TEXT NOT NULL,
+  created_by TEXT,
+  updated_by TEXT,
+  UNIQUE(extensionId, path)
+);
+
+CREATE TABLE extension_versions (
+  id TEXT PRIMARY KEY,
+  extensionId TEXT NOT NULL REFERENCES extensions(id) ON DELETE CASCADE,
+  version INTEGER NOT NULL,
+  manifestJson TEXT NOT NULL,
+  filesJson TEXT NOT NULL,
+  contentHash TEXT NOT NULL,
+  changedByAgentId TEXT,
+  changedAt TEXT NOT NULL DEFAULT (datetime('now')),
+  changeReason TEXT,
+  created_by TEXT,
+  updated_by TEXT,
+  UNIQUE(extensionId, version)
+);
+
+CREATE TABLE extension_runs (
+  id TEXT PRIMARY KEY,
+  extensionId TEXT NOT NULL REFERENCES extensions(id) ON DELETE CASCADE,
+  version INTEGER NOT NULL,
+  event TEXT NOT NULL,
+  action TEXT NOT NULL
+    CHECK(action IN ('continue', 'modify', 'block', 'error', 'timeout', 'load-error')),
+  durationMs INTEGER,
+  message TEXT,
+  agentId TEXT,
+  subject TEXT,
+  createdAt TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX idx_extension_runs_extension_created
+  ON extension_runs(extensionId, createdAt);

package/src/be/migrations/156_inbox_item_state_read_at.sql

@@ -0,0 +1,7 @@
+-- Adds a first-viewed timestamp to inbox_item_state, independent of status.
+--
+-- The notification bell needs to stop counting an item as unread once the
+-- user has opened the panel and seen it, without moving the item out of the
+-- "open" (un-actioned) bucket -- dismiss/done stay reserved for explicit user
+-- actions. readAt is set once on first view and never cleared.
+ALTER TABLE inbox_item_state ADD COLUMN readAt TEXT;

package/src/be/rbac-roles.ts

@@ -1,5 +1,6 @@
 import type { PermissionVerb } from "../rbac";
 import { PermissionVerbSchema } from "../rbac";
+import { isEnvFlagEnabled } from "../utils/env-flag";
 import { getDb, getDbClient } from "./db";
 
 export const DEFAULT_ROLE_ID = "rbac-role-admin";
@@ -358,8 +359,8 @@ export function ensureRbacSeedsSynced(opts?: { quiet?: boolean }): RbacSeedSyncS
 
 function describeRbacFlag(): string {
   const raw = process.env.RBAC_ENABLED;
-  if (raw === undefined) return "unset (off)";
-  return `${raw} (${raw === "true" ? "on" : "off"})`;
+  if (raw === undefined) return "unset (on)";
+  return `${raw} (${isEnvFlagEnabled("RBAC_ENABLED", true) ? "on" : "off"})`;
 }
 
 function printRolesTable(rows: RbacRoleSummaryRow[]): void {

package/src/be/scripts/typecheck.ts

@@ -38,10 +38,14 @@ export type ScriptApiDefaultOptions = { raw?: false };
 export type RoutingReason = "skill" | "continuity" | "overflow" | "human_pinned" | "reroute_fault";
 export type TaskSendArgs = Record<string, unknown> & {
   task: string;
-  routingNote?: string;
 } & (
-  | { agentId: string; routingReason: RoutingReason }
-  | { agentId?: never; routingReason?: never }
+  | {
+      agentId: string;
+      routingReason: RoutingReason;
+      /** At least 10 characters after trim; maximum 200. */
+      routingNote: string;
+    }
+  | { agentId?: never; routingReason?: never; routingNote?: string }
 );
 export type AgentTaskStepConfig = {
   template?: string;
@@ -311,6 +315,10 @@ export interface SwarmSdk {
   script_getRun(args: { id: string }): Promise<unknown>;
   script_listRuns(args?: { status?: "running" | "paused" | "completed" | "failed" | "cancelled" | "aborted_limit"; agentId?: string; limit?: number; offset?: number }): Promise<unknown>;
 
+  // --- write: extensions ---
+  extension_install(args: { manifest: Record<string, unknown>; files: Record<string, string>; priority?: number; config?: Record<string, unknown> }): Promise<unknown>;
+  extension_list(args?: { enabledOnly?: boolean }): Promise<unknown>;
+
   // --- write: repos ---
   repo_update(args: Record<string, unknown>): Promise<unknown>;
 
@@ -457,7 +465,7 @@ export async function scriptSdkTypesWithGeneratedApis(
   return `${SCRIPT_SDK_TYPES}\n${apiTypes}\n${mcpTypes}\n${resolvedAppTypes}\n`;
 }
 
-const STDLIB_MODULE_TYPES = `
+export const SCRIPT_STDLIB_MODULE_TYPES = `
 declare module "stdlib" {
   export interface Redacted<T> {
     readonly __redactedBrand?: T;
@@ -478,7 +486,7 @@ declare module "stdlib" {
 `;
 
 function stdlibTypesFor(sdkModuleBody: string): string {
-  return `${STDLIB_MODULE_TYPES}
+  return `${SCRIPT_STDLIB_MODULE_TYPES}
 declare module "swarm-sdk" {
 ${sdkModuleBody.replace(/^/gm, "  ")}
 }
@@ -836,8 +844,6 @@ interface Window {
 
 const USER_FILE = "/virtual/user-script.ts";
 const CHECK_FILE = "/virtual/check.ts";
-const SDK_FILE = "/virtual/swarm-sdk.d.ts";
-const STDLIB_FILE = "/virtual/stdlib.d.ts";
 const RUNTIME_GLOBALS_FILE = "/virtual/runtime-globals.d.ts";
 
 /**
@@ -859,6 +865,7 @@ function scriptTypesBase(): string {
 function createCompilerHost(
   files: Map<string, string>,
   options: ts.CompilerOptions,
+  virtualModules: ReadonlyMap<string, string> = new Map(),
 ): ts.CompilerHost {
   const host = ts.createCompilerHost(options, true);
   const originalGetSourceFile = host.getSourceFile.bind(host);
@@ -891,11 +898,9 @@ function createCompilerHost(
       if (moduleName === "./user-script") {
         return { resolvedFileName: USER_FILE, extension: ts.Extension.Ts };
       }
-      if (moduleName === "swarm-sdk") {
-        return { resolvedFileName: SDK_FILE, extension: ts.Extension.Dts };
-      }
-      if (moduleName === "stdlib") {
-        return { resolvedFileName: STDLIB_FILE, extension: ts.Extension.Dts };
+      const virtualModule = virtualModules.get(moduleName);
+      if (virtualModule) {
+        return { resolvedFileName: virtualModule, extension: ts.Extension.Dts };
       }
       // For external packages, resolve from project root so node_modules is found
       const base = containingFile.startsWith("/virtual/") ? projectBase : containingFile;
@@ -980,10 +985,12 @@ function toStructured(diag: ts.Diagnostic): ScriptDiagnostic {
   };
 }
 
-export async function typecheckScript(
-  source: string,
-  context: ScriptTypeContext = {},
-): Promise<ScriptTypecheckResult> {
+export async function typecheckWithAmbient(args: {
+  source: string;
+  modules: Record<string, string>;
+  ambient?: Record<string, string>;
+  checkFile: string;
+}): Promise<ScriptTypecheckResult> {
   const options: ts.CompilerOptions = {
     allowImportingTsExtensions: true,
     lib: ["lib.es2022.d.ts"],
@@ -996,35 +1003,23 @@ export async function typecheckScript(
     types: [],
   };
 
-  const apiTypes = getScriptApiTypes(context);
-  const mcpTypes = getScriptMcpTypes(context);
-  const appTypes = await getScriptAppTypes(context);
-  const sdkTypes = await scriptSdkTypesWithGeneratedApis(apiTypes, mcpTypes, appTypes);
-  const stdlibTypes = appTypes
-    ? await scriptStdlibTypesWithGeneratedApis(apiTypes, mcpTypes, appTypes)
-    : SCRIPT_STDLIB_TYPES;
   const files = new Map<string, string>([
-    [USER_FILE, source],
-    [SDK_FILE, sdkTypes],
-    [STDLIB_FILE, stdlibTypes],
+    [USER_FILE, args.source],
     [RUNTIME_GLOBALS_FILE, SCRIPT_RUNTIME_GLOBALS],
-    [
-      CHECK_FILE,
-      `/// <reference path="./runtime-globals.d.ts" />
-import run from "./user-script";
-import type { ScriptMain } from "swarm-sdk";
-const _scriptMain: ScriptMain = run;
-void _scriptMain;
-`,
-    ],
+    [CHECK_FILE, args.checkFile],
   ]);
+  const virtualModules = new Map<string, string>();
+  for (const [moduleName, source] of Object.entries(args.modules)) {
+    const fileName = `/virtual/${moduleName.replace(/[^A-Za-z0-9_.-]/g, "_")}.d.ts`;
+    files.set(fileName, source);
+    virtualModules.set(moduleName, fileName);
+  }
+  for (const [name, source] of Object.entries(args.ambient ?? {})) {
+    files.set(`/virtual/ambient-${name.replace(/[^A-Za-z0-9_.-]/g, "_")}.d.ts`, source);
+  }
 
-  const host = createCompilerHost(files, options);
-  const program = ts.createProgram(
-    [USER_FILE, CHECK_FILE, SDK_FILE, STDLIB_FILE, RUNTIME_GLOBALS_FILE],
-    options,
-    host,
-  );
+  const host = createCompilerHost(files, options, virtualModules);
+  const program = ts.createProgram([...files.keys()], options, host);
   const diagnostics = [
     ...program.getSyntacticDiagnostics(),
     ...program.getSemanticDiagnostics(),
@@ -1049,3 +1044,26 @@ void _scriptMain;
     structured: diagnostics.map(toStructured),
   };
 }
+
+export async function typecheckScript(
+  source: string,
+  context: ScriptTypeContext = {},
+): Promise<ScriptTypecheckResult> {
+  const apiTypes = getScriptApiTypes(context);
+  const mcpTypes = getScriptMcpTypes(context);
+  const appTypes = await getScriptAppTypes(context);
+  const sdkTypes = await scriptSdkTypesWithGeneratedApis(apiTypes, mcpTypes, appTypes);
+  const stdlibTypes = appTypes
+    ? await scriptStdlibTypesWithGeneratedApis(apiTypes, mcpTypes, appTypes)
+    : SCRIPT_STDLIB_TYPES;
+  return typecheckWithAmbient({
+    source,
+    modules: { "swarm-sdk": sdkTypes, stdlib: stdlibTypes },
+    checkFile: `/// <reference path="./runtime-globals.d.ts" />
+import run from "./user-script";
+import type { ScriptMain } from "swarm-sdk";
+const _scriptMain: ScriptMain = run;
+void _scriptMain;
+`,
+  });
+}

package/src/be/seed/schedules-seeder.ts

@@ -11,6 +11,12 @@ import dailyCompoundingReflectionConfig from "../../../templates/schedules/daily
 import dailyCompoundingReflectionContent from "../../../templates/schedules/daily-compounding-reflection/content.md" with {
   type: "text",
 };
+import dailyHnBriefingConfig from "../../../templates/schedules/daily-hn-briefing/config.json" with {
+  type: "text",
+};
+import dailyHnBriefingContent from "../../../templates/schedules/daily-hn-briefing/content.md" with {
+  type: "text",
+};
 import dailyStatusReportConfig from "../../../templates/schedules/daily-status-report/config.json" with {
   type: "text",
 };
@@ -53,6 +59,12 @@ import weeklyDoraMetricsConfig from "../../../templates/schedules/weekly-dora-me
 import weeklyDoraMetricsContent from "../../../templates/schedules/weekly-dora-metrics/content.md" with {
   type: "text",
 };
+import weeklyHarnessUpgradeCheckConfig from "../../../templates/schedules/weekly-harness-upgrade-check/config.json" with {
+  type: "text",
+};
+import weeklyHarnessUpgradeCheckContent from "../../../templates/schedules/weekly-harness-upgrade-check/content.md" with {
+  type: "text",
+};
 import type { AutomationIntegrationId, ScheduledTask } from "../../types";
 import {
   computeContentHash,
@@ -107,6 +119,7 @@ const BUILT_IN_SCHEDULE_SOURCES: readonly ScheduleTemplateSource[] = [
     config: asText(dailyCompoundingReflectionConfig),
     content: asText(dailyCompoundingReflectionContent),
   },
+  { config: asText(dailyHnBriefingConfig), content: asText(dailyHnBriefingContent) },
   { config: asText(dailyStatusReportConfig), content: asText(dailyStatusReportContent) },
   {
     config: asText(dailySwarmUpdateCheckConfig),
@@ -126,6 +139,10 @@ const BUILT_IN_SCHEDULE_SOURCES: readonly ScheduleTemplateSource[] = [
     content: asText(weeklyDependabotTriageContent),
   },
   { config: asText(weeklyDoraMetricsConfig), content: asText(weeklyDoraMetricsContent) },
+  {
+    config: asText(weeklyHarnessUpgradeCheckConfig),
+    content: asText(weeklyHarnessUpgradeCheckContent),
+  },
 ];
 
 function parseScheduleSource(source: ScheduleTemplateSource): SeedSchedule | null {
@@ -137,7 +154,8 @@ function parseScheduleSource(source: ScheduleTemplateSource): SeedSchedule | nul
     ? scheduleHeading.index! + scheduleHeading[0].length
     : source.content.indexOf("```json");
   const scheduleText = source.content.slice(scheduleStart);
-  const blockMatch = scheduleText.match(/(?:```json\s*\n)?(\{[\s\S]*?\})(?:\n```)?/);
+  const blockMatch =
+    scheduleText.match(/^\s*```json\s*\n([\s\S]*?)\n```/) ?? scheduleText.match(/(\{[\s\S]*?\})/);
   if (!blockMatch?.[1]) throw new Error(`Schedule template ${config.name} has no schedule JSON`);
   const block = JSON.parse(blockMatch[1]) as ScheduleBlock;
   const afterBlock = scheduleStart + blockMatch.index! + blockMatch[0].length;
@@ -205,9 +223,14 @@ function scheduleFromRow(schedule: ScheduledTask): SeedSchedule {
 
 function nextRunAt(schedule: SeedSchedule): string | null {
   try {
+    // Disabled templates can await a required timezone parameter. Validate the
+    // cron in UTC until setup supplies it, retaining the placeholder in the row.
+    const timezonePending =
+      !schedule.enabled &&
+      schedule.requiredParams.some((param) => schedule.timezone.includes(`{{${param}}}`));
     const interval = CronExpressionParser.parse(schedule.cronExpression, {
       currentDate: new Date(),
-      tz: schedule.timezone,
+      tz: timezonePending ? "UTC" : schedule.timezone,
     });
     return schedule.enabled ? interval.next().toISOString() : null;
   } catch (error) {

package/src/be/seed/workflows-seeder.ts

@@ -10,6 +10,12 @@ import autopilotConfig from "../../../templates/workflows/autopilot/config.json"
 import autopilotContent from "../../../templates/workflows/autopilot/content.md" with {
   type: "text",
 };
+import claudeCodeChangelogWatchConfig from "../../../templates/workflows/claude-code-changelog-watch/config.json" with {
+  type: "text",
+};
+import claudeCodeChangelogWatchContent from "../../../templates/workflows/claude-code-changelog-watch/content.md" with {
+  type: "text",
+};
 import competitorRadarConfig from "../../../templates/workflows/competitor-radar/config.json" with {
   type: "text",
 };
@@ -22,6 +28,12 @@ import docsSiteReleasesConfig from "../../../templates/workflows/docs-site-relea
 import docsSiteReleasesContent from "../../../templates/workflows/docs-site-releases/content.md" with {
   type: "text",
 };
+import gscTopicMinerConfig from "../../../templates/workflows/gsc-topic-miner/config.json" with {
+  type: "text",
+};
+import gscTopicMinerContent from "../../../templates/workflows/gsc-topic-miner/content.md" with {
+  type: "text",
+};
 import linearDrainLoopConfig from "../../../templates/workflows/linear-drain-loop/config.json" with {
   type: "text",
 };
@@ -101,8 +113,13 @@ const asText = (value: unknown): string => value as string;
 const BUILT_IN_WORKFLOW_SOURCES: readonly WorkflowTemplateSource[] = [
   { config: asText(alertsTriageConfig), content: asText(alertsTriageContent) },
   { config: asText(autopilotConfig), content: asText(autopilotContent) },
+  {
+    config: asText(claudeCodeChangelogWatchConfig),
+    content: asText(claudeCodeChangelogWatchContent),
+  },
   { config: asText(competitorRadarConfig), content: asText(competitorRadarContent) },
   { config: asText(docsSiteReleasesConfig), content: asText(docsSiteReleasesContent) },
+  { config: asText(gscTopicMinerConfig), content: asText(gscTopicMinerContent) },
   { config: asText(linearDrainLoopConfig), content: asText(linearDrainLoopContent) },
   { config: asText(llmSafeReleaseContextConfig), content: asText(llmSafeReleaseContextContent) },
   { config: asText(prReviewStatusSweepConfig), content: asText(prReviewStatusSweepContent) },

package/src/be/seed-scripts/catalog/delegate.ts

@@ -3,7 +3,9 @@ import { z } from "zod";
 export const argsSchema = z.object({
   agentName: z.string().describe("Target agent's name (case-insensitive) — resolved to its id"),
   routingReason: z.enum(["skill", "continuity", "overflow", "human_pinned", "reroute_fault"]),
-  routingNote: z.string().max(200).optional(),
+  routingNote: z.string().max(200).refine((note) => note.trim().length >= 10, {
+    message: "routingNote must contain at least 10 characters after trim",
+  }),
   task: z.string().describe("Full task prompt for the target agent"),
   parentTaskId: z
     .string()

package/src/be/seed-skills/bundled-files.generated.json

@@ -36,7 +36,7 @@
   "delegate-work": [
     {
       "path": "scripts/codex-exec.sh",
-      "content": "#!/usr/bin/env bash\n#\n# codex-exec.sh — invoke `codex exec` (non-interactive) for delegated\n# implementation work. This is the SINGLE SOURCE OF TRUTH for the invocation\n# flags. The delegate-work skill calls only this script; its routing matrix\n# decides WHICH gpt-5.6 variant (-m) and effort (-e) each task gets:\n#   luna  = mechanical/bounded     terra = everyday frozen-spec slice\n#   sol   = hard/long-horizon      effort: medium|high|xhigh|max (never ultra)\n#\n# Usage:\n#   codex-exec.sh [-m <model>] [-e <effort>] -C <workdir> -o <last-message-file> [-l <log-file>] \"PROMPT\"\n#   printf '%s' \"$PROMPT\" | codex-exec.sh -C <workdir> -o <file>     # prompt via stdin (preferred)\n#\n# Notes:\n#   * -C sets codex's working root (the git worktree, for parallel isolation).\n#   * -o writes codex's final message (its report) to a file you can read back.\n#   * Reads the prompt from stdin when no positional PROMPT is given.\n#   * In `exec` mode approvals are already \"never\", so nothing hangs waiting for\n#     a human. The sandbox mode below bounds what codex may WRITE.\n#\n# Sandbox default: `workspace-write` — codex may freely edit files inside its\n# working root (the worktree) and read elsewhere on disk (so it can read the\n# plan by absolute path), but cannot write outside the workspace. This keeps\n# parallel worktree runs from clobbering each other or the main tree.\n#\n# Env overrides (flags -m/-e take precedence):\n#   CODEX_MODEL   default: gpt-5.6-sol          gpt-5.6-sol | gpt-5.6-terra | gpt-5.6-luna\n#   CODEX_EFFORT  default: high                 reasoning effort (never \"fast\"/low)\n#   CODEX_SANDBOX default: workspace-write      read-only | workspace-write | danger-full-access\n#   CODEX_BYPASS  set to 1 to use --dangerously-bypass-approvals-and-sandbox\n#                 (fully unsandboxed — opt in only when a phase must write\n#                 outside its worktree; overrides CODEX_SANDBOX)\nset -euo pipefail\n\nWORKDIR=\".\"\nOUTFILE=\"\"\nLOGFILE=\"\"\nPROMPT=\"\"\nMODEL_FLAG=\"\"\nEFFORT_FLAG=\"\"\n\nwhile [[ $# -gt 0 ]]; do\n  case \"$1\" in\n    -m|--model)  MODEL_FLAG=\"$2\"; shift 2 ;;\n    -e|--effort) EFFORT_FLAG=\"$2\"; shift 2 ;;\n    -C|--cd)  WORKDIR=\"$2\"; shift 2 ;;\n    -o|--out) OUTFILE=\"$2\"; shift 2 ;;\n    -l|--log) LOGFILE=\"$2\"; shift 2 ;;\n    --)       shift; PROMPT=\"${1:-}\"; break ;;\n    -*)       echo \"codex-exec.sh: unknown flag: $1\" >&2; exit 2 ;;\n    *)        PROMPT=\"$1\"; shift ;;\n  esac\ndone\n\nMODEL=\"${MODEL_FLAG:-${CODEX_MODEL:-gpt-5.6-sol}}\"\nEFFORT=\"${EFFORT_FLAG:-${CODEX_EFFORT:-high}}\"\nSANDBOX=\"${CODEX_SANDBOX:-workspace-write}\"\n\nargs=( exec\n  -m \"$MODEL\"\n  -c \"model_reasoning_effort=\\\"$EFFORT\\\"\"\n  -C \"$WORKDIR\"\n)\nif [[ \"${CODEX_BYPASS:-0}\" == \"1\" ]]; then\n  args+=( --dangerously-bypass-approvals-and-sandbox )\nelse\n  args+=( -s \"$SANDBOX\" )\nfi\n[[ -n \"$OUTFILE\" ]] && args+=( -o \"$OUTFILE\" )\n\n# Prompt source: positional arg if present, otherwise stdin (`-`).\nif [[ -n \"$PROMPT\" ]]; then\n  set -- \"$PROMPT\"\nelse\n  set -- \"-\"\nfi\n\nif [[ -n \"$LOGFILE\" ]]; then\n  codex \"${args[@]}\" \"$@\" 2>&1 | tee \"$LOGFILE\"\nelse\n  codex \"${args[@]}\" \"$@\"\nfi\n"
+      "content": "#!/usr/bin/env bash\n#\n# codex-exec.sh — invoke `codex exec` (non-interactive) for delegated\n# implementation work. This is the SINGLE SOURCE OF TRUTH for the invocation\n# flags. The delegate-work skill calls only this script; its routing matrix\n# decides WHICH gpt-5.6 variant (-m) and effort (-e) each task gets:\n#   luna  = mechanical/bounded     terra = everyday frozen-spec slice\n#   sol   = hard/long-horizon      effort: medium|high|xhigh|max (never ultra)\n#\n# Usage:\n#   codex-exec.sh [-m <model>] [-e <effort>] -C <workdir> -o <last-message-file> [-l <log-file>] \"PROMPT\"\n#   printf '%s' \"$PROMPT\" | codex-exec.sh -C <workdir> -o <file>     # prompt via stdin (preferred)\n#\n# Notes:\n#   * -C sets codex's working root (the git worktree, for parallel isolation).\n#   * -o writes codex's final message (its report) to a file you can read back.\n#   * Reads the prompt from stdin when no positional PROMPT is given.\n#   * In `exec` mode approvals are already \"never\", so nothing hangs waiting for\n#     a human. The sandbox mode below bounds what codex may WRITE.\n#\n# Sandbox default: `workspace-write` — codex may freely edit files inside its\n# working root (the worktree) and read elsewhere on disk (so it can read the\n# plan by absolute path), but cannot write outside the workspace. This keeps\n# parallel worktree runs from clobbering each other or the main tree.\n#\n# Env overrides (flags -m/-e take precedence):\n#   CODEX_MODEL   default: gpt-5.6-sol          gpt-5.6-sol | gpt-5.6-terra | gpt-5.6-luna\n#   CODEX_EFFORT  default: high                 reasoning effort (never \"fast\"/low)\n#   CODEX_SANDBOX default: workspace-write (passed to codex's -s option)\n#   CODEX_BYPASS  set to 1 to use --dangerously-bypass-approvals-and-sandbox\n#                 (fully unsandboxed — opt in only when a phase must write\n#                 outside its worktree; overrides CODEX_SANDBOX)\nset -euo pipefail\n\nWORKDIR=\".\"\nOUTFILE=\"\"\nLOGFILE=\"\"\nPROMPT=\"\"\nMODEL_FLAG=\"\"\nEFFORT_FLAG=\"\"\n\nwhile [[ $# -gt 0 ]]; do\n  case \"$1\" in\n    -m|--model)  MODEL_FLAG=\"$2\"; shift 2 ;;\n    -e|--effort) EFFORT_FLAG=\"$2\"; shift 2 ;;\n    -C|--cd)  WORKDIR=\"$2\"; shift 2 ;;\n    -o|--out) OUTFILE=\"$2\"; shift 2 ;;\n    -l|--log) LOGFILE=\"$2\"; shift 2 ;;\n    --)       shift; PROMPT=\"${1:-}\"; break ;;\n    -*)       echo \"codex-exec.sh: unknown flag: $1\" >&2; exit 2 ;;\n    *)        PROMPT=\"$1\"; shift ;;\n  esac\ndone\n\nMODEL=\"${MODEL_FLAG:-${CODEX_MODEL:-gpt-5.6-sol}}\"\nEFFORT=\"${EFFORT_FLAG:-${CODEX_EFFORT:-high}}\"\nSANDBOX=\"${CODEX_SANDBOX:-workspace-write}\"\n\nargs=( exec\n  -m \"$MODEL\"\n  -c \"model_reasoning_effort=\\\"$EFFORT\\\"\"\n  -C \"$WORKDIR\"\n)\nif [[ \"${CODEX_BYPASS:-0}\" == \"1\" ]]; then\n  args+=( --dangerously-bypass-approvals-and-sandbox )\nelse\n  args+=( -s \"$SANDBOX\" )\nfi\n[[ -n \"$OUTFILE\" ]] && args+=( -o \"$OUTFILE\" )\n\n# Prompt source: positional arg if present, otherwise stdin (`-`).\nif [[ -n \"$PROMPT\" ]]; then\n  set -- \"$PROMPT\"\nelse\n  set -- \"-\"\nfi\n\nif [[ -n \"$LOGFILE\" ]]; then\n  codex \"${args[@]}\" \"$@\" 2>&1 | tee \"$LOGFILE\"\nelse\n  codex \"${args[@]}\" \"$@\"\nfi\n"
     }
   ],
   "design-docs": [

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

@@ -200,6 +200,12 @@ import stepRunningConfig from "../../../templates/skills/step-running/config.jso
 import stepRunningContent from "../../../templates/skills/step-running/content.md" with {
   type: "text",
 };
+import swarmExtensionsConfig from "../../../templates/skills/swarm-extensions/config.json" with {
+  type: "text",
+};
+import swarmExtensionsContent from "../../../templates/skills/swarm-extensions/content.md" with {
+  type: "text",
+};
 import swarmScriptsConfig from "../../../templates/skills/swarm-scripts/config.json" with {
   type: "text",
 };
@@ -347,6 +353,7 @@ const BUILT_IN_SKILL_SOURCES = [
   { config: reviewingConfig, body: reviewingContent },
   { config: scheduledTaskResilienceConfig, body: scheduledTaskResilienceContent },
   { config: schedulingConfig, body: schedulingContent },
+  { config: swarmExtensionsConfig, body: swarmExtensionsContent },
   { config: scriptBuilderConfig, body: scriptBuilderContent },
   { config: scriptWorkflowsConfig, body: scriptWorkflowsContent },
   { config: slackInteractionConfig, body: slackInteractionContent },

package/src/be/steering.ts

@@ -76,6 +76,7 @@ export async function promoteSteeringToTask(
   return await createTaskExtended(message.body, {
     agentId: task.agentId,
     routingReason: task.agentId ? "continuity" : undefined,
+    routingSource: task.agentId ? "engine_default" : undefined,
     creatorAgentId: message.createdByAgentId,
     source: message.source === "script" ? "api" : message.source,
     taskType: "follow-up",

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

@@ -284,7 +284,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "DB_QUERY_BOUNDED_ENABLED",
     "DB_RETENTION_DRY_RUN",
   ]),
-  ...enumValidator("SLACK_THREAD_STEERING", ["lead", "all"]),
+  ...enumValidator("SLACK_THREAD_STEERING", ["off", "lead", "all"]),
   ...enumValidator("SLACK_THREAD_STEERING_MODE", ["steer", "queue"]),
   ...shortcodeValidators([
     "SLACK_REACTION_ACCEPTED",
@@ -308,6 +308,8 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
       "WORKFLOW_MAX_ITERATIONS",
       "WORKFLOW_MAX_STEPS_PER_RUN",
       "SCHEDULER_INTERVAL_MS",
+      "EXTENSION_HANDLER_TIMEOUT_MS",
+      "EXTENSION_MAX_CONSECUTIVE_FAILURES",
       "RUNTIME_STALE_THRESHOLD_MIN",
       "SCRIPT_RUN_CONCURRENCY_CAP",
       "WORKER_API_READY_TIMEOUT_SECONDS",

package/src/commands/credential-refresh.ts

@@ -0,0 +1,70 @@
+import {
+  buildCredStatusReport,
+  isCredCheckDisabled,
+  sendCredStatusReport,
+  shouldRefreshBedrockStatus,
+} from "./provider-credentials";
+import type { ApiConfig } from "./runner";
+
+export const CREDENTIAL_RETRY_INTERVAL_MS = 30_000;
+const BEDROCK_REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+
+export interface CredentialRefreshState {
+  harnessProvider: string | null;
+  // null means the last attempt failed before readiness could be acknowledged.
+  ready: boolean | null;
+  lastRefreshAt: number;
+  inFlight: boolean;
+}
+
+/**
+ * Called on each runner tick after env reconciliation. Provider changes refresh
+ * immediately; blocked/failed reports retry on a bounded interval until the API
+ * acknowledges readiness. Only one build/report may be in flight at a time.
+ */
+export async function refreshCredentialStatus(
+  api: ApiConfig,
+  state: CredentialRefreshState,
+  harnessProvider: string,
+  env: Record<string, string | undefined>,
+  now = Date.now(),
+): Promise<void> {
+  if (isCredCheckDisabled(env) || state.inFlight) return;
+  const providerChanged = state.harnessProvider !== harnessProvider;
+  const retryDue =
+    state.ready !== true && now - state.lastRefreshAt >= CREDENTIAL_RETRY_INTERVAL_MS;
+  if (
+    !providerChanged &&
+    !retryDue &&
+    !shouldRefreshBedrockStatus({
+      harnessProvider,
+      env,
+      lastRefreshAt: state.lastRefreshAt,
+      now,
+      intervalMs: BEDROCK_REFRESH_INTERVAL_MS,
+    })
+  ) {
+    return;
+  }
+
+  state.harnessProvider = harnessProvider;
+  state.lastRefreshAt = now;
+  state.ready = null;
+  state.inFlight = true;
+  try {
+    const snapshot = await buildCredStatusReport(harnessProvider, { ...env }, {}, "post_task");
+    // The runner invalidates this cache on a live provider swap. Discard a
+    // snapshot built for the old provider; the next tick checks the new one.
+    if (state.harnessProvider !== harnessProvider) return;
+    await sendCredStatusReport(api.apiUrl, api.apiKey, api.agentId, api.runtimeInstanceId, {
+      ready: snapshot.ready,
+      missing: snapshot.missing,
+      credStatus: snapshot,
+    });
+    if (state.harnessProvider === harnessProvider) state.ready = snapshot.ready;
+  } finally {
+    // Errors propagate to the runner's non-fatal logger, leaving ready unknown
+    // so even a lost ready:true write is retried without a restart.
+    state.inFlight = false;
+  }
+}

package/src/commands/onboard/compose-generator.ts

@@ -8,6 +8,10 @@ const DEFAULT_WORKER_MAX_CONCURRENT_TASKS = 1;
 // noTemplateCurlyInString rule. We collect them via a helper to keep the
 // suppression comments in one place.
 
+// Image tag for the API and agent images. Blank or unset resolves to `latest`,
+// which moves on every commit to main; operators pin a release in .env.
+// biome-ignore lint/suspicious/noTemplateCurlyInString: Docker Compose env var syntax
+const IMAGE_TAG_EXPRESSION = "${AGENT_SWARM_VERSION:-latest}";
 // biome-ignore lint/suspicious/noTemplateCurlyInString: Docker Compose env var syntax
 const ENV_API_KEY = "      - API_KEY=${API_KEY}";
 // biome-ignore lint/suspicious/noTemplateCurlyInString: Docker Compose env var syntax
@@ -108,12 +112,20 @@ export function generateCompose(state: OnboardState): string {
   lines.push("#");
   lines.push("# Usage:");
   lines.push("#   docker compose --env-file .env up -d");
+  lines.push("#");
+  lines.push("# Image version: set AGENT_SWARM_VERSION in .env to a published release.");
+  lines.push("# Blank falls back to `latest`, which moves on every commit to main and is");
+  lines.push("# not a release. Releases: https://github.com/desplega-ai/agent-swarm/releases");
+  lines.push("# Upgrade/rollback (migrations are forward-only, so back up first):");
+  lines.push(
+    "# https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/upgrade.md",
+  );
   lines.push("");
   lines.push("services:");
 
   // ── API service ──
   lines.push("  swarm-api:");
-  lines.push('    image: "ghcr.io/desplega-ai/agent-swarm:latest"');
+  lines.push(`    image: "ghcr.io/desplega-ai/agent-swarm:${IMAGE_TAG_EXPRESSION}"`);
   lines.push("    container_name: swarm-api");
   lines.push(`    pull_policy: ${state.pullPolicy}`);
   lines.push("    stop_grace_period: 60s");
@@ -165,7 +177,7 @@ export function generateCompose(state: OnboardState): string {
 
     lines.push("");
     lines.push(`  ${svc.name}:`);
-    lines.push('    image: "ghcr.io/desplega-ai/agent-swarm-worker:latest"');
+    lines.push(`    image: "ghcr.io/desplega-ai/agent-swarm-worker:${IMAGE_TAG_EXPRESSION}"`);
     lines.push(`    container_name: ${svc.containerName}`);
     lines.push(`    pull_policy: ${state.pullPolicy}`);
     lines.push("    stop_grace_period: 60s");

package/src/commands/onboard/env-generator.ts

@@ -16,6 +16,13 @@ export function generateEnv(state: OnboardState): string {
   lines.push(`MCP_BASE_URL=http://localhost:${port}`);
   lines.push("APP_URL=https://app.agent-swarm.dev");
 
+  // Image pin. Blank resolves to `latest`, which moves on every commit to main
+  // and is not a release. Left blank so a fresh install behaves as before;
+  // operators set a published release from
+  // https://github.com/desplega-ai/agent-swarm/releases before depending on it.
+  lines.push("# Pin a release, e.g. AGENT_SWARM_VERSION=1.150.0. Blank tracks `latest`.");
+  lines.push("AGENT_SWARM_VERSION=");
+
   // Install path — read by src/telemetry.ts at boot to attribute the
   // "which entry point produced this install" cohort. Boolean/enum only,
   // never an identifier. Installs that never ran the wizard (hand-written

package/src/commands/provider-credentials.ts

@@ -10,8 +10,8 @@
  * Used by:
  * - The worker boot loop (`src/commands/credential-wait.ts`) to decide
  *   whether the worker can claim tasks yet.
- * - The worker post-task hook (`src/commands/runner.ts`) to refresh on
- *   harness_provider changes.
+ * - The worker steady-state refresh (`src/commands/credential-refresh.ts`)
+ *   to check provider changes and recover blocked credentials.
  *
  * Reports flow worker → API as JSON via the existing PATCH /agents/:id
  * endpoint (see `AgentCredStatusSchema` in `src/types.ts`). The API never
@@ -537,29 +537,6 @@ export async function sendCredStatusReport(
   }
 }
 
-/**
- * Fire-and-forget wrapper around {@link sendCredStatusReport}. Used by the
- * post-task cache-miss path (`runner.ts`), where a stale dashboard is
- * acceptable and blocking the worker is not.
- */
-export async function reportCredStatus(
-  apiUrl: string,
-  apiKey: string,
-  agentId: string,
-  runtimeInstanceId: string | undefined,
-  credStatus: AgentCredStatus,
-): Promise<void> {
-  try {
-    await sendCredStatusReport(apiUrl, apiKey, agentId, runtimeInstanceId, {
-      ready: credStatus.ready,
-      missing: credStatus.missing,
-      credStatus,
-    });
-  } catch (err) {
-    console.warn(`[cred-status] POST failed (non-fatal): ${err}`);
-  }
-}
-
 export async function reportLatestModel(
   apiUrl: string,
   apiKey: string,