@desplega.ai/agent-swarm 1.158.0 → 1.159.0

package/src/commands/runner.ts

@@ -36,7 +36,9 @@ import {
 import type { SteerDeliveryResult } from "../providers/types.ts";
 import { initTelemetry, telemetry } from "../telemetry.ts";
 import {
+  type ModelTierOverrides,
   type ProviderName,
+  parseWorkerModelTierOverrides,
   type ReasoningEffort,
   type RepoGuidelines,
   resolveTaskModelSelection,
@@ -55,9 +57,11 @@ import {
   type RateLimitWindowTelemetry,
   resolveCodexCreditsExhaustedCooldownMs,
 } from "../utils/error-tracker.ts";
+import { probeHarnessCliVersion, reportHarnessModelOutcome } from "../utils/harness-cli-version.ts";
 import { resolveHarnessProvider } from "../utils/harness-provider.ts";
 import { prettyPrintLine, prettyPrintStderr } from "../utils/pretty-print.ts";
 import { terminateRegisteredProcessGroups } from "../utils/process-group.ts";
+import { refreshRuntimeModelCatalog } from "../utils/runtime-model-catalog.ts";
 import { resolveScriptsOnlyMode } from "../utils/scripts-only-mode.ts";
 import { scrubSecrets } from "../utils/secret-scrubber.ts";
 import { refreshSkillsIfChanged } from "../utils/skills-refresh.ts";
@@ -1220,6 +1224,8 @@ const SWARM_TOOL_LABELS: Record<string, string | null> = {
   "set-config": "⚙️ Setting config",
   "list-config": "⚙️ Listing config",
   "delete-config": "⚙️ Deleting config",
+  "model-catalog-refresh": "🧠 Refreshing model catalog",
+  "model-catalog-overlay-upsert": "🧠 Updating model catalog overlay",
   // Schedules
   "create-schedule": "📅 Creating schedule",
   "list-schedules": "📅 Listing schedules",
@@ -2909,6 +2915,16 @@ interface PollOptions {
   pollInterval: number;
   pollTimeout: number;
   since?: string; // Optional: for filtering finished tasks
+  /** Live harness provider; keys the MODEL_TIER_* overrides sent with the poll. */
+  harnessProvider?: ProviderName;
+}
+
+/**
+ * The worker's own MODEL_TIER_* overrides, parsed from its process env (not
+ * the swarm_config-merged env: global config is already visible server-side).
+ */
+function workerModelTierOverrides(provider: ProviderName): ModelTierOverrides {
+  return parseWorkerModelTierOverrides(process.env, provider);
 }
 
 type RequesterProfile = NonNullable<Trigger["requestedBy"]>;
@@ -2990,6 +3006,8 @@ export async function registerAgent(opts: {
       provider,
       harness_provider: harnessProvider,
       runtimeInstanceId: opts.runtimeInstanceId,
+      modelTierOverrides: workerModelTierOverrides(harnessProvider),
+      harnessCliVersion: (await probeHarnessCliVersion(harnessProvider)) ?? undefined,
     }),
   });
 
@@ -3035,6 +3053,14 @@ async function pollForTrigger(opts: PollOptions): Promise<Trigger | null> {
 
 async function pollForTriggerOnce(opts: PollOptions): Promise<Trigger | null> {
   const startTime = Date.now();
+  // Keep the process-wide model catalog fresh (TTL-cached, never throws) so
+  // context windows, pricing and reasoning levels cover models added to the
+  // API's catalog after this worker booted.
+  void refreshRuntimeModelCatalog({
+    apiUrl: opts.apiUrl,
+    apiKey: opts.apiKey,
+    agentId: opts.agentId,
+  });
   const headers: Record<string, string> = {
     "X-Agent-ID": opts.agentId,
   };
@@ -3045,6 +3071,11 @@ async function pollForTriggerOnce(opts: PollOptions): Promise<Trigger | null> {
     headers.Authorization = `Bearer ${opts.apiKey}`;
   }
   injectTraceContext(headers);
+  if (opts.harnessProvider) {
+    headers["X-Model-Tier-Overrides"] = encodeURIComponent(
+      JSON.stringify(workerModelTierOverrides(opts.harnessProvider)),
+    );
+  }
 
   while (Date.now() - startTime < opts.pollTimeout) {
     try {
@@ -3527,6 +3558,9 @@ async function spawnProviderProcess(
     taskId?: string;
     model?: string;
     modelTier?: string;
+    /** Server claim-time resolution (task.resolvedModel); wins over the local one. */
+    resolvedModel?: string;
+    modelSource?: string;
     effort?: ReasoningEffort;
     resumeSessionId?: string;
     harnessProvider: ProviderName;
@@ -3562,7 +3596,7 @@ async function spawnProviderProcess(
       opts.apiKey,
       opts.agentId,
       process.env,
-      opts.model,
+      opts.resolvedModel || opts.model,
       {
         repoId: sessionRepo?.id,
         provider: adapter.name as ProviderName,
@@ -3619,7 +3653,20 @@ async function spawnProviderProcess(
     harnessProvider: opts.harnessProvider,
     env: freshEnv,
   });
-  const taskModel = taskModelSelection.model || "";
+  // The server resolves the model at claim time (worker-env > tier-config >
+  // tier-default, `latest:` aliases, guardrails) and records it on the task.
+  // The local resolution stays as a check: a difference usually means the
+  // server saw a stale MODEL_TIER_* override or a swarm_config tier value.
+  if (
+    opts.resolvedModel &&
+    taskModelSelection.model &&
+    taskModelSelection.model !== opts.resolvedModel
+  ) {
+    console.log(
+      `[${opts.role}] model resolution mismatch for task ${opts.taskId ?? "?"}: server=${opts.resolvedModel} (${opts.modelSource ?? "?"}) local=${taskModelSelection.model}; using server value`,
+    );
+  }
+  const taskModel = opts.resolvedModel || taskModelSelection.model || "";
   const model = taskModel || configModel || "";
 
   // Resolve Codex OAuth pool slot BEFORE building ProviderSessionConfig so we
@@ -4517,6 +4564,17 @@ async function checkCompletedProcesses(
         console.log(`[${role}] Detected error for task ${taskId.slice(0, 8)}: ${failureReason}`);
       }
 
+      // Record whether this worker's CLI accepts the model (harness_model_support).
+      void reportHarnessModelOutcome({
+        apiUrl: apiConfig.apiUrl,
+        apiKey: apiConfig.apiKey,
+        agentId: apiConfig.agentId,
+        harness: harnessProvider,
+        model,
+        exitCode: result.exitCode,
+        failureReason,
+      });
+
       // If rate-limited and we know which key was used, report it.
       // Codex adapter prefixes failure reasons with `[rate-limit]` /
       // `[usage-limit]` (see codex-adapter.formatTerminalError); Claude
@@ -5911,6 +5969,8 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
               taskId: task.id,
               model: (task as { model?: string }).model,
               modelTier: (task as { modelTier?: string }).modelTier,
+              resolvedModel: (task as { resolvedModel?: string }).resolvedModel,
+              modelSource: (task as { modelSource?: string }).modelSource,
               effort: (task as { effort?: ReasoningEffort }).effort,
               harnessProvider: state.harnessProvider,
               cwd: resumeCwd,
@@ -6127,6 +6187,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
         pollInterval: PollIntervalMs,
         runtimeInstanceId,
         pollTimeout: effectiveTimeout,
+        harnessProvider: state.harnessProvider,
       });
 
       if (trigger) {
@@ -6407,6 +6468,16 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
           .join("\n\n");
         const taskSystemPrompt = taskPromptParts + cwdWarning;
 
+        // The server refused the task's explicit model for this worker's CLI
+        // version (harness_model_support = unsupported): fail fast, no spawn.
+        const modelUnsupported = (trigger.task as { modelUnsupported?: string } | undefined)
+          ?.modelUnsupported;
+        if (trigger.taskId && modelUnsupported) {
+          console.log(`[${role}] ${modelUnsupported}`);
+          await ensureTaskFinished(apiConfig, role, trigger.taskId, 1, modelUnsupported);
+          continue;
+        }
+
         iteration++;
         const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
         const taskIdSlice = trigger.taskId?.slice(0, 8) || "notask";
@@ -6472,6 +6543,9 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
               taskId: trigger.taskId,
               model: taskModel,
               modelTier: taskModelTier,
+              resolvedModel: (trigger.task as { resolvedModel?: string } | undefined)
+                ?.resolvedModel,
+              modelSource: (trigger.task as { modelSource?: string } | undefined)?.modelSource,
               effort: taskEffort,
               harnessProvider: state.harnessProvider,
               cwd: effectiveCwd,

package/src/extensions/contract-types.generated.ts

@@ -1,4 +1,4 @@
 // Generated by scripts/bundle-extension-types.ts. Do not edit.
 // biome-ignore-all lint/suspicious/noTemplateCurlyInString: Type declarations contain literal template placeholders.
 export const EXTENSION_TYPE_DEFINITIONS =
-  '// biome-ignore-all lint/suspicious/noConfusingVoidType: Extension handlers may explicitly return no result.\ndeclare module "swarm-extension" {\n  export type CreateTaskOptions = {\n    key?: string | undefined;\n    agentId?: string | null | undefined;\n    creatorAgentId?: string | undefined;\n    source?:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "system"\n      | "linear"\n      | "jira"\n      | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    taskType?: string | undefined;\n    tags?: string[] | undefined;\n    priority?: number | undefined;\n    dependsOn?: string[] | undefined;\n    offeredTo?: string | undefined;\n    status?: "draft" | "backlog" | "unassigned" | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    overrideSlackContext?: boolean | undefined;\n    vcsProvider?: "github" | "gitlab" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | undefined;\n    workflowRunStepId?: string | undefined;\n    sourceTaskId?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    inheritParentOutputSchema?: boolean | undefined;\n    inheritParentRoutingAffinity?: boolean | undefined;\n    inheritParentFollowUpConfig?: boolean | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    requestedByUserId?: string | undefined;\n    contextKey?: string | undefined;\n    bypassTrackerContextDedup?: boolean | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n  };\n\n  export type AgentTask = {\n    id: string;\n    key: string;\n    agentId: string | null;\n    task: string;\n    status:\n      | "draft"\n      | "backlog"\n      | "unassigned"\n      | "offered"\n      | "reviewing"\n      | "pending"\n      | "in_progress"\n      | "paused"\n      | "completed"\n      | "failed"\n      | "cancelled"\n      | "superseded";\n    source:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "system"\n      | "linear"\n      | "jira";\n    tags: string[];\n    priority: number;\n    dependsOn: string[];\n    createdAt: string;\n    lastUpdatedAt: string;\n    slackReplySent: boolean;\n    wasPaused: boolean;\n    creatorAgentId?: string | undefined;\n    title?: string | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    taskType?: string | undefined;\n    offeredTo?: string | undefined;\n    offeredAt?: string | undefined;\n    acceptedAt?: string | undefined;\n    rejectionReason?: string | undefined;\n    finishedAt?: string | undefined;\n    notifiedAt?: string | undefined;\n    failureReason?: string | undefined;\n    output?: string | undefined;\n    progress?: string | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    slackProgressMessageTs?: string | undefined;\n    slackTreeRootMessageTs?: string | undefined;\n    vcsProvider?: "github" | "gitlab" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    claudeSessionId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | null | undefined;\n    workflowRunStepId?: string | null | undefined;\n    contextKey?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    deferredAt?: string | undefined;\n    compactionCount?: number | undefined;\n    peakContextPercent?: number | undefined;\n    peakContextTokens?: number | undefined;\n    contextWindowSize?: number | undefined;\n    credentialKeySuffix?: string | undefined;\n    credentialKeyType?: string | undefined;\n    requestedByUserId?: string | undefined;\n    swarmVersion?: string | undefined;\n    provider?:\n      | "claude"\n      | "codex"\n      | "pi"\n      | "devin"\n      | "claude-managed"\n      | "opencode"\n      | "acp"\n      | "dsh"\n      | undefined;\n    providerMeta?: Record<string, unknown> | undefined;\n    harnessVariant?: string | undefined;\n    harnessVariantMeta?: Record<string, unknown> | undefined;\n    totalCostUsd?: number | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n    routingAffinityInvalid?: boolean | undefined;\n  };\n\n  export type ActiveSession = {\n    id: string;\n    agentId: string;\n    taskId: string | null;\n    triggerType: string;\n    inboxMessageId: string | null;\n    taskDescription: string | null;\n    runnerSessionId: string | null;\n    providerSessionId: string | null;\n    startedAt: string;\n    lastHeartbeatAt: string;\n    runtimeInstanceId?: string | null | undefined;\n  };\n\n  export type RequestInfo = {\n    sessionId: string | undefined;\n    agentId: string | undefined;\n    runtimeInstanceId: string | undefined;\n    sourceTaskId: string | undefined;\n    contextKey: string | undefined;\n    callOrigin: "mcp" | "extension" | "script-sdk";\n  };\n\n  import type { SwarmSdk } from "swarm-sdk";\n  import type { z } from "zod";\n  export type Runtime = "api" | "worker";\n  export interface ExtensionScriptAsset {\n    name: string;\n    file: string;\n    description: string;\n    intent?: string;\n  }\n  export interface ExtensionScheduleAsset {\n    name: string;\n    description?: string;\n    script: string;\n    cronExpression?: string;\n    intervalMs?: number;\n    timezone?: string;\n    args?: Record<string, unknown>;\n  }\n  export interface ExtensionWorkflowAsset {\n    file: string;\n  }\n  export interface ExtensionSkillAsset {\n    dir: string;\n  }\n  export interface ExtensionManifest {\n    $schema?: string;\n    name: string;\n    description: string;\n    version: string;\n    runtime: Runtime;\n    assets: {\n      hooks: string;\n      scripts?: readonly ExtensionScriptAsset[];\n      schedules?: readonly ExtensionScheduleAsset[];\n      workflows?: readonly ExtensionWorkflowAsset[];\n      skills?: readonly ExtensionSkillAsset[];\n    };\n    homepage?: string;\n    author?: string;\n  }\n  export interface HooksModule {\n    default: SwarmExtension;\n    config?: z.ZodTypeAny;\n  }\n  export interface ExtensionState {\n    get<T = unknown>(key: string): Promise<T | null>;\n    set<T>(key: string, value: T): Promise<void>;\n    incr(key: string, by?: number): Promise<number>;\n    del(key: string): Promise<void>;\n  }\n  export interface ExtensionLogger {\n    debug(message: string, data?: unknown): void;\n    info(message: string, data?: unknown): void;\n    warn(message: string, data?: unknown): void;\n    error(message: string, data?: unknown): void;\n  }\n  type ConfigFor<M extends ExtensionManifest> = M extends {\n    config: infer C extends z.ZodTypeAny;\n  }\n    ? z.infer<C>\n    : Record<string, unknown>;\n  export interface ApiCtx<Config = Record<string, unknown>> {\n    swarm: SwarmSdk;\n    state: ExtensionState;\n    config: Config;\n    log: ExtensionLogger;\n    signal: AbortSignal;\n    event: {\n      name: keyof SwarmEventMap;\n      at: string;\n      extension: {\n        id: string;\n        version: number;\n      };\n    };\n  }\n  export interface WorkerCtx<Config = Record<string, unknown>>\n    extends Omit<ApiCtx<Config>, "swarm"> {\n    swarm: SwarmSdk;\n    worker: {\n      agentId: string;\n      taskId: string;\n      harness: string;\n    };\n  }\n  export type CtxFor<M extends ExtensionManifest> = M["runtime"] extends "api"\n    ? ApiCtx<ConfigFor<M>>\n    : WorkerCtx<ConfigFor<M>>;\n  export type PreResult<Modify> =\n    | void\n    | {\n        action: "continue";\n      }\n    | {\n        action: "modify";\n        data: Modify;\n      }\n    | {\n        action: "block";\n        reason: string;\n      };\n  export type TaskCreateOrigin =\n    | "rest"\n    | "app"\n    | "mcp"\n    | "slack"\n    | "schedule"\n    | "workflow"\n    | "webhook"\n    | "followUp"\n    | `extension:${string}`;\n  export interface TaskCreateEvent {\n    options: CreateTaskOptions;\n    description: string;\n    origin: TaskCreateOrigin;\n    requestInfo?: RequestInfo;\n  }\n  export type TaskCreateModify = Partial<\n    Pick<\n      CreateTaskOptions,\n      | "agentId"\n      | "creatorAgentId"\n      | "source"\n      | "taskType"\n      | "tags"\n      | "priority"\n      | "dependsOn"\n      | "offeredTo"\n      | "vcsProvider"\n      | "vcsRepo"\n      | "vcsEventType"\n      | "vcsNumber"\n      | "vcsCommentId"\n      | "vcsAuthor"\n      | "vcsUrl"\n      | "vcsInstallationId"\n      | "vcsNodeId"\n      | "agentmailInboxId"\n      | "agentmailMessageId"\n      | "agentmailThreadId"\n      | "mentionMessageId"\n      | "mentionChannelId"\n      | "dir"\n      | "model"\n      | "modelTier"\n      | "effort"\n      | "outputSchema"\n      | "followUpConfig"\n      | "bypassTrackerContextDedup"\n    >\n  > & {\n    description?: string;\n  };\n  export interface TaskFollowUpEvent {\n    completedTask: AgentTask;\n    status: "completed" | "failed";\n    output?: string;\n    failureReason?: string;\n    workerAgentId: string;\n    leadAgentId: string;\n    summary: string;\n  }\n  export type TaskFollowUpModify = Partial<\n    Pick<CreateTaskOptions, "agentId" | "priority" | "followUpConfig">\n  > & {\n    description?: string;\n  };\n  export interface SlackRouteEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    botMentioned: boolean;\n    threadContext?: {\n      channelId: string;\n      threadTs: string;\n    };\n  }\n  export interface SlackRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        };\n  }\n  export type HeartbeatClassification = "no-session" | "stale-session" | "fresh-stalled";\n  export type HeartbeatAction = "supersede-resume" | "fail" | "record";\n  export interface HeartbeatRemediateEvent {\n    task: AgentTask;\n    session?: ActiveSession;\n    classification: HeartbeatClassification;\n    proposedAction: HeartbeatAction;\n    reason: string;\n    taskAgeMs: number;\n    sessionHeartbeatAgeMs?: number;\n  }\n  export interface HeartbeatRemediateModify {\n    proposedAction: HeartbeatAction;\n  }\n  export interface ToolCallEvent {\n    tool: string;\n    args: unknown;\n    requestInfo: RequestInfo;\n  }\n  export interface ToolCallModify {\n    args: unknown;\n  }\n  export interface TaskEvent {\n    task: AgentTask;\n  }\n  export interface TaskCompletedEvent extends TaskEvent {\n    output: string;\n  }\n  export interface TaskFailedEvent extends TaskEvent {\n    failureReason: string;\n  }\n  export interface TaskSupersededEvent extends TaskEvent {\n    supersededBy: string;\n  }\n  export interface TaskProgressEvent extends TaskEvent {\n    progress: string;\n  }\n  export interface SlackMessageEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    taskId?: string;\n  }\n  export interface ToolCallCompletedEvent extends ToolCallEvent {\n    result: unknown;\n    durationMs: number;\n  }\n  export interface SwarmEventMap {\n    "pre.task.create": {\n      event: TaskCreateEvent;\n      modify: TaskCreateModify;\n      result: PreResult<TaskCreateModify>;\n    };\n    "pre.task.followUp": {\n      event: TaskFollowUpEvent;\n      modify: TaskFollowUpModify;\n      result: PreResult<TaskFollowUpModify>;\n    };\n    "pre.slack.route": {\n      event: SlackRouteEvent;\n      modify: SlackRouteModify;\n      result: PreResult<SlackRouteModify>;\n    };\n    "pre.heartbeat.remediate": {\n      event: HeartbeatRemediateEvent;\n      modify: HeartbeatRemediateModify;\n      result: PreResult<HeartbeatRemediateModify>;\n    };\n    "pre.tool.call": {\n      event: ToolCallEvent;\n      modify: ToolCallModify;\n      result: PreResult<ToolCallModify>;\n    };\n    "post.task.created": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.completed": {\n      event: TaskCompletedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.failed": {\n      event: TaskFailedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.cancelled": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.superseded": {\n      event: TaskSupersededEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.progress": {\n      event: TaskProgressEvent;\n      modify: never;\n      result: void;\n    };\n    "post.slack.message": {\n      event: SlackMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.tool.call": {\n      event: ToolCallCompletedEvent;\n      modify: never;\n      result: void;\n    };\n  }\n  export interface ExtensionApi<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > {\n    on<E extends keyof SwarmEventMap>(\n      event: E,\n      handler: (\n        event: SwarmEventMap[E]["event"],\n        ctx: CtxFor<M>,\n      ) => Promise<SwarmEventMap[E]["result"]> | SwarmEventMap[E]["result"],\n      opts?: {\n        priority?: number;\n      },\n    ): void;\n  }\n  export type SwarmExtension<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > = (api: ExtensionApi<M>) => void;\n  export { block, modify } from "./contract-runtime";\n}\n';
+  '// biome-ignore-all lint/suspicious/noConfusingVoidType: Extension handlers may explicitly return no result.\ndeclare module "swarm-extension" {\n  export type CreateTaskOptions = {\n    key?: string | undefined;\n    agentId?: string | null | undefined;\n    creatorAgentId?: string | undefined;\n    source?:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "system"\n      | "linear"\n      | "jira"\n      | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    taskType?: string | undefined;\n    tags?: string[] | undefined;\n    priority?: number | undefined;\n    dependsOn?: string[] | undefined;\n    offeredTo?: string | undefined;\n    status?: "draft" | "backlog" | "unassigned" | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    overrideSlackContext?: boolean | undefined;\n    vcsProvider?: "github" | "gitlab" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | undefined;\n    workflowRunStepId?: string | undefined;\n    sourceTaskId?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    inheritParentOutputSchema?: boolean | undefined;\n    inheritParentRoutingAffinity?: boolean | undefined;\n    inheritParentFollowUpConfig?: boolean | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    requestedByUserId?: string | undefined;\n    contextKey?: string | undefined;\n    bypassTrackerContextDedup?: boolean | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n  };\n\n  export type AgentTask = {\n    id: string;\n    key: string;\n    agentId: string | null;\n    task: string;\n    status:\n      | "draft"\n      | "backlog"\n      | "unassigned"\n      | "offered"\n      | "reviewing"\n      | "pending"\n      | "in_progress"\n      | "paused"\n      | "completed"\n      | "failed"\n      | "cancelled"\n      | "superseded";\n    source:\n      | "workflow"\n      | "schedule"\n      | "slack"\n      | "agentmail"\n      | "mcp"\n      | "api"\n      | "ui"\n      | "github"\n      | "gitlab"\n      | "system"\n      | "linear"\n      | "jira";\n    tags: string[];\n    priority: number;\n    dependsOn: string[];\n    createdAt: string;\n    lastUpdatedAt: string;\n    slackReplySent: boolean;\n    wasPaused: boolean;\n    creatorAgentId?: string | undefined;\n    title?: string | undefined;\n    routingReason?:\n      | "skill"\n      | "continuity"\n      | "overflow"\n      | "human_pinned"\n      | "reroute_fault"\n      | undefined;\n    routingSource?: "declared" | "engine_default" | undefined;\n    routingNote?: string | undefined;\n    taskType?: string | undefined;\n    offeredTo?: string | undefined;\n    offeredAt?: string | undefined;\n    acceptedAt?: string | undefined;\n    rejectionReason?: string | undefined;\n    finishedAt?: string | undefined;\n    notifiedAt?: string | undefined;\n    failureReason?: string | undefined;\n    output?: string | undefined;\n    progress?: string | undefined;\n    slackChannelId?: string | undefined;\n    slackThreadTs?: string | undefined;\n    slackTriggerMessageTs?: string | undefined;\n    slackUserId?: string | undefined;\n    slackProgressMessageTs?: string | undefined;\n    slackTreeRootMessageTs?: string | undefined;\n    vcsProvider?: "github" | "gitlab" | undefined;\n    vcsRepo?: string | undefined;\n    vcsEventType?: string | undefined;\n    vcsNumber?: number | undefined;\n    vcsCommentId?: number | undefined;\n    vcsAuthor?: string | undefined;\n    vcsUrl?: string | undefined;\n    vcsInstallationId?: number | undefined;\n    vcsNodeId?: string | undefined;\n    agentmailInboxId?: string | undefined;\n    agentmailMessageId?: string | undefined;\n    agentmailThreadId?: string | undefined;\n    mentionMessageId?: string | undefined;\n    mentionChannelId?: string | undefined;\n    dir?: string | undefined;\n    parentTaskId?: string | undefined;\n    claudeSessionId?: string | undefined;\n    model?: string | undefined;\n    modelTier?: "smol" | "regular" | "smart" | "ultra" | undefined;\n    effort?: "off" | "low" | "medium" | "high" | "xhigh" | "max" | undefined;\n    resolvedModel?: string | undefined;\n    modelSource?: string | undefined;\n    modelAlias?: string | undefined;\n    scheduleId?: string | undefined;\n    workflowRunId?: string | null | undefined;\n    workflowRunStepId?: string | null | undefined;\n    contextKey?: string | undefined;\n    outputSchema?: Record<string, unknown> | undefined;\n    followUpConfig?:\n      | {\n          disabled?: boolean | undefined;\n          onCompleted?: string | undefined;\n          onFailed?: string | undefined;\n        }\n      | undefined;\n    deferredAt?: string | undefined;\n    compactionCount?: number | undefined;\n    peakContextPercent?: number | undefined;\n    peakContextTokens?: number | undefined;\n    contextWindowSize?: number | undefined;\n    credentialKeySuffix?: string | undefined;\n    credentialKeyType?: string | undefined;\n    requestedByUserId?: string | undefined;\n    swarmVersion?: string | undefined;\n    provider?:\n      | "claude"\n      | "codex"\n      | "pi"\n      | "devin"\n      | "claude-managed"\n      | "opencode"\n      | "acp"\n      | "dsh"\n      | undefined;\n    providerMeta?: Record<string, unknown> | undefined;\n    harnessVariant?: string | undefined;\n    harnessVariantMeta?: Record<string, unknown> | undefined;\n    totalCostUsd?: number | undefined;\n    routingAffinity?:\n      | {\n          capabilities: string[];\n          sourceAgentId?: string | undefined;\n          role?: string | undefined;\n          harnessProvider?:\n            | "claude"\n            | "codex"\n            | "pi"\n            | "devin"\n            | "claude-managed"\n            | "opencode"\n            | "acp"\n            | "dsh"\n            | undefined;\n          leadOnly?: boolean | undefined;\n        }\n      | undefined;\n    routingAffinityInvalid?: boolean | undefined;\n  };\n\n  export type ActiveSession = {\n    id: string;\n    agentId: string;\n    taskId: string | null;\n    triggerType: string;\n    inboxMessageId: string | null;\n    taskDescription: string | null;\n    runnerSessionId: string | null;\n    providerSessionId: string | null;\n    startedAt: string;\n    lastHeartbeatAt: string;\n    runtimeInstanceId?: string | null | undefined;\n  };\n\n  export type RequestInfo = {\n    sessionId: string | undefined;\n    agentId: string | undefined;\n    runtimeInstanceId: string | undefined;\n    sourceTaskId: string | undefined;\n    contextKey: string | undefined;\n    callOrigin: "mcp" | "extension" | "script-sdk";\n  };\n\n  import type { SwarmSdk } from "swarm-sdk";\n  import type { z } from "zod";\n  export type Runtime = "api" | "worker";\n  export interface ExtensionScriptAsset {\n    name: string;\n    file: string;\n    description: string;\n    intent?: string;\n  }\n  export interface ExtensionScheduleAsset {\n    name: string;\n    description?: string;\n    script: string;\n    cronExpression?: string;\n    intervalMs?: number;\n    timezone?: string;\n    args?: Record<string, unknown>;\n  }\n  export interface ExtensionWorkflowAsset {\n    file: string;\n  }\n  export interface ExtensionSkillAsset {\n    dir: string;\n  }\n  export interface ExtensionManifest {\n    $schema?: string;\n    name: string;\n    description: string;\n    version: string;\n    runtime: Runtime;\n    assets: {\n      hooks: string;\n      scripts?: readonly ExtensionScriptAsset[];\n      schedules?: readonly ExtensionScheduleAsset[];\n      workflows?: readonly ExtensionWorkflowAsset[];\n      skills?: readonly ExtensionSkillAsset[];\n    };\n    homepage?: string;\n    author?: string;\n  }\n  export interface HooksModule {\n    default: SwarmExtension;\n    config?: z.ZodTypeAny;\n  }\n  export interface ExtensionState {\n    get<T = unknown>(key: string): Promise<T | null>;\n    set<T>(key: string, value: T): Promise<void>;\n    incr(key: string, by?: number): Promise<number>;\n    del(key: string): Promise<void>;\n  }\n  export interface ExtensionLogger {\n    debug(message: string, data?: unknown): void;\n    info(message: string, data?: unknown): void;\n    warn(message: string, data?: unknown): void;\n    error(message: string, data?: unknown): void;\n  }\n  type ConfigFor<M extends ExtensionManifest> = M extends {\n    config: infer C extends z.ZodTypeAny;\n  }\n    ? z.infer<C>\n    : Record<string, unknown>;\n  export interface ApiCtx<Config = Record<string, unknown>> {\n    swarm: SwarmSdk;\n    state: ExtensionState;\n    config: Config;\n    log: ExtensionLogger;\n    signal: AbortSignal;\n    event: {\n      name: keyof SwarmEventMap;\n      at: string;\n      extension: {\n        id: string;\n        version: number;\n      };\n    };\n  }\n  export interface WorkerCtx<Config = Record<string, unknown>>\n    extends Omit<ApiCtx<Config>, "swarm"> {\n    swarm: SwarmSdk;\n    worker: {\n      agentId: string;\n      taskId: string;\n      harness: string;\n    };\n  }\n  export type CtxFor<M extends ExtensionManifest> = M["runtime"] extends "api"\n    ? ApiCtx<ConfigFor<M>>\n    : WorkerCtx<ConfigFor<M>>;\n  export type PreResult<Modify> =\n    | void\n    | {\n        action: "continue";\n      }\n    | {\n        action: "modify";\n        data: Modify;\n      }\n    | {\n        action: "block";\n        reason: string;\n      };\n  export type TaskCreateOrigin =\n    | "rest"\n    | "app"\n    | "mcp"\n    | "slack"\n    | "schedule"\n    | "workflow"\n    | "webhook"\n    | "followUp"\n    | `extension:${string}`;\n  export interface TaskCreateEvent {\n    options: CreateTaskOptions;\n    description: string;\n    origin: TaskCreateOrigin;\n    requestInfo?: RequestInfo;\n  }\n  export type TaskCreateModify = Partial<\n    Pick<\n      CreateTaskOptions,\n      | "agentId"\n      | "creatorAgentId"\n      | "source"\n      | "taskType"\n      | "tags"\n      | "priority"\n      | "dependsOn"\n      | "offeredTo"\n      | "vcsProvider"\n      | "vcsRepo"\n      | "vcsEventType"\n      | "vcsNumber"\n      | "vcsCommentId"\n      | "vcsAuthor"\n      | "vcsUrl"\n      | "vcsInstallationId"\n      | "vcsNodeId"\n      | "agentmailInboxId"\n      | "agentmailMessageId"\n      | "agentmailThreadId"\n      | "mentionMessageId"\n      | "mentionChannelId"\n      | "dir"\n      | "model"\n      | "modelTier"\n      | "effort"\n      | "outputSchema"\n      | "followUpConfig"\n      | "bypassTrackerContextDedup"\n    >\n  > & {\n    description?: string;\n  };\n  export interface TaskFollowUpEvent {\n    completedTask: AgentTask;\n    status: "completed" | "failed";\n    output?: string;\n    failureReason?: string;\n    workerAgentId: string;\n    leadAgentId: string;\n    summary: string;\n  }\n  export type TaskFollowUpModify = Partial<\n    Pick<CreateTaskOptions, "agentId" | "priority" | "followUpConfig">\n  > & {\n    description?: string;\n  };\n  export interface SlackRouteEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    botMentioned: boolean;\n    threadContext?: {\n      channelId: string;\n      threadTs: string;\n    };\n  }\n  export interface SlackRouteModify {\n    target:\n      | {\n          kind: "agent";\n          agentId: string;\n        }\n      | {\n          kind: "lead";\n        }\n      | {\n          kind: "broadcast";\n        };\n  }\n  export type HeartbeatClassification = "no-session" | "stale-session" | "fresh-stalled";\n  export type HeartbeatAction = "supersede-resume" | "fail" | "record";\n  export interface HeartbeatRemediateEvent {\n    task: AgentTask;\n    session?: ActiveSession;\n    classification: HeartbeatClassification;\n    proposedAction: HeartbeatAction;\n    reason: string;\n    taskAgeMs: number;\n    sessionHeartbeatAgeMs?: number;\n  }\n  export interface HeartbeatRemediateModify {\n    proposedAction: HeartbeatAction;\n  }\n  export interface ToolCallEvent {\n    tool: string;\n    args: unknown;\n    requestInfo: RequestInfo;\n  }\n  export interface ToolCallModify {\n    args: unknown;\n  }\n  export interface TaskEvent {\n    task: AgentTask;\n  }\n  export interface TaskCompletedEvent extends TaskEvent {\n    output: string;\n  }\n  export interface TaskFailedEvent extends TaskEvent {\n    failureReason: string;\n  }\n  export interface TaskSupersededEvent extends TaskEvent {\n    supersededBy: string;\n  }\n  export interface TaskProgressEvent extends TaskEvent {\n    progress: string;\n  }\n  export interface SlackMessageEvent {\n    channelId: string;\n    userId: string;\n    text: string;\n    threadTs?: string;\n    taskId?: string;\n  }\n  export interface ToolCallCompletedEvent extends ToolCallEvent {\n    result: unknown;\n    durationMs: number;\n  }\n  export interface SwarmEventMap {\n    "pre.task.create": {\n      event: TaskCreateEvent;\n      modify: TaskCreateModify;\n      result: PreResult<TaskCreateModify>;\n    };\n    "pre.task.followUp": {\n      event: TaskFollowUpEvent;\n      modify: TaskFollowUpModify;\n      result: PreResult<TaskFollowUpModify>;\n    };\n    "pre.slack.route": {\n      event: SlackRouteEvent;\n      modify: SlackRouteModify;\n      result: PreResult<SlackRouteModify>;\n    };\n    "pre.heartbeat.remediate": {\n      event: HeartbeatRemediateEvent;\n      modify: HeartbeatRemediateModify;\n      result: PreResult<HeartbeatRemediateModify>;\n    };\n    "pre.tool.call": {\n      event: ToolCallEvent;\n      modify: ToolCallModify;\n      result: PreResult<ToolCallModify>;\n    };\n    "post.task.created": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.completed": {\n      event: TaskCompletedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.failed": {\n      event: TaskFailedEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.cancelled": {\n      event: TaskEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.superseded": {\n      event: TaskSupersededEvent;\n      modify: never;\n      result: void;\n    };\n    "post.task.progress": {\n      event: TaskProgressEvent;\n      modify: never;\n      result: void;\n    };\n    "post.slack.message": {\n      event: SlackMessageEvent;\n      modify: never;\n      result: void;\n    };\n    "post.tool.call": {\n      event: ToolCallCompletedEvent;\n      modify: never;\n      result: void;\n    };\n  }\n  export interface ExtensionApi<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > {\n    on<E extends keyof SwarmEventMap>(\n      event: E,\n      handler: (\n        event: SwarmEventMap[E]["event"],\n        ctx: CtxFor<M>,\n      ) => Promise<SwarmEventMap[E]["result"]> | SwarmEventMap[E]["result"],\n      opts?: {\n        priority?: number;\n      },\n    ): void;\n  }\n  export type SwarmExtension<\n    M extends ExtensionManifest = ExtensionManifest & {\n      runtime: "api";\n    },\n  > = (api: ExtensionApi<M>) => void;\n  export { block, modify } from "./contract-runtime";\n}\n';

package/src/heartbeat/heartbeat.ts

@@ -28,6 +28,7 @@ import {
   getStaleUnassignedAffinityTasks,
   getStalledInProgressTasks,
   getSupersededTasksWithoutResume,
+  getSupersededTasksWithUnsettledDependents,
   getTaskById,
   getTaskStats,
   getTasksByStatus,
@@ -42,6 +43,7 @@ import {
   releaseStaleOfferedTasksForOfflineAgents,
   releaseStaleProcessingInbox,
   releaseStaleReviewingTasks,
+  settleSupersededTaskDependents,
   supersedeTask,
   updateAgentStatus,
 } from "../be/db";
@@ -66,6 +68,7 @@ import {
   resolveLeadOnlyRecoveryAssignment,
 } from "../tasks/worker-follow-up";
 import type { AgentTask } from "../types";
+import { isEnvFlagEnabled } from "../utils/env-flag";
 import { isMultiRuntimeEnabled } from "../utils/multi-runtime";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { getExecutorRegistry } from "../workflows";
@@ -217,12 +220,30 @@ export const HEARTBEAT_RESUME_PIN_GRACE_MIN = (() => {
  */
 const POOL_AFFINITY_ESCALATION_MIN = Number(process.env.POOL_AFFINITY_ESCALATION_MIN) || 15;
 
-/** Heartbeat checklist interval: how often to check HEARTBEAT.md (default: 30 min) */
-const HEARTBEAT_CHECKLIST_INTERVAL_MS =
-  Number(process.env.HEARTBEAT_CHECKLIST_INTERVAL_MS) || 30 * 60 * 1000;
+const DEFAULT_HEARTBEAT_CHECKLIST_INTERVAL_MS = 30 * 60 * 1000;
 
-/** Whether to disable the heartbeat checklist entirely */
-const HEARTBEAT_CHECKLIST_DISABLE = Boolean(process.env.HEARTBEAT_CHECKLIST_DISABLE);
+/**
+ * Heartbeat checklist interval: how often to check HEARTBEAT.md (default: 30 min).
+ *
+ * An explicit `0` (or negative) turns the RECURRING checklist tick off; the
+ * one-shot boot triage still runs. Absent, empty, or non-numeric values fall
+ * back to the default (not `Number(x) || default`, which would coerce `0` to 30 min).
+ */
+function heartbeatChecklistIntervalMs(): number {
+  const raw = process.env.HEARTBEAT_CHECKLIST_INTERVAL_MS?.trim();
+  if (!raw) return DEFAULT_HEARTBEAT_CHECKLIST_INTERVAL_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return DEFAULT_HEARTBEAT_CHECKLIST_INTERVAL_MS;
+  return Math.max(0, parsed);
+}
+
+/**
+ * Whether to disable the heartbeat checklist entirely (recurring tick AND boot
+ * triage). Parsed with the shared env-flag helper, so `"false"`/`"0"` keep it on.
+ */
+function isHeartbeatChecklistDisabled(): boolean {
+  return isEnvFlagEnabled("HEARTBEAT_CHECKLIST_DISABLE", false);
+}
 
 // ============================================================================
 // Types
@@ -275,6 +296,7 @@ export interface HeartbeatFindings {
 
 let heartbeatInterval: ReturnType<typeof setInterval> | null = null;
 let checklistInterval: ReturnType<typeof setInterval> | null = null;
+let bootTriageTimeout: ReturnType<typeof setTimeout> | null = null;
 let isSweeping = false;
 let beforeHeartbeatSupersedeForTests: ((task: AgentTask) => void | Promise<void>) | null = null;
 
@@ -530,10 +552,15 @@ async function repairSupersededWithoutResume(findings: HeartbeatFindings): Promi
     new Date(now - ORPHAN_SUPERSEDE_MAX_AGE_MS).toISOString(),
   );
   for (const task of orphans) {
-    if (!task.agentId) continue;
-    if (getNextResumeGeneration(task) > maxResumeGenerations()) continue;
-    const resume = await createResumeFollowUp({ parentId: task.id, reason: "crash_recovery" });
-    if (resume.kind !== "created") continue;
+    const resume =
+      task.agentId && getNextResumeGeneration(task) <= maxResumeGenerations()
+        ? await createResumeFollowUp({ parentId: task.id, reason: "crash_recovery" })
+        : null;
+    if (resume?.kind !== "created" || !task.agentId) {
+      // No resume will carry the work: its dependents fail as they would have.
+      await settleSupersededTaskDependents(task.id, null);
+      continue;
+    }
     await backfillSupersedeTaskResumeTaskId(task.id, resume.task.id);
     findings.autoResumedTasks.push({
       taskId: task.id,
@@ -545,6 +572,16 @@ async function repairSupersededWithoutResume(findings: HeartbeatFindings): Promi
       `[Heartbeat] Created missing resume ${resume.task.id.slice(0, 8)} for superseded task ${task.id.slice(0, 8)}`,
     );
   }
+
+  // A crash after the resume was created but before the backfill leaves
+  // dependents waiting on the superseded task; settle them onto that resume.
+  const unsettled = await getSupersededTasksWithUnsettledDependents(
+    new Date(now - ORPHAN_SUPERSEDE_MIN_AGE_MS).toISOString(),
+    new Date(now - ORPHAN_SUPERSEDE_MAX_AGE_MS).toISOString(),
+  );
+  for (const { taskId, resumeTaskId } of unsettled) {
+    await settleSupersededTaskDependents(taskId, resumeTaskId);
+  }
 }
 
 function isRemediationAction(value: unknown): value is RemediationAction {
@@ -679,6 +716,7 @@ async function remediateCrashedWorkerTask(
       resume.kind === "skipped"
         ? `resume_creation_skipped_${resume.reason}`
         : "resume_creation_skipped_workflow";
+    await settleSupersededTaskDependents(task.id, null);
     const failed = await failTask(task.id, reason);
     if (failed) {
       findings.autoFailedTasks.push({
@@ -1835,19 +1873,26 @@ export async function createBootTriageTask(): Promise<void> {
 /**
  * Start the heartbeat checklist polling loop (separate from the infrastructure sweep).
  */
-export function startHeartbeatChecklist(intervalMs = HEARTBEAT_CHECKLIST_INTERVAL_MS): void {
-  if (HEARTBEAT_CHECKLIST_DISABLE) {
+export function startHeartbeatChecklist(intervalMs = heartbeatChecklistIntervalMs()): void {
+  if (isHeartbeatChecklistDisabled()) {
     console.log("[Heartbeat] Checklist disabled via HEARTBEAT_CHECKLIST_DISABLE");
     return;
   }
-  if (checklistInterval) {
+  if (checklistInterval || bootTriageTimeout) {
     return; // Already running
   }
 
-  console.log(`[Heartbeat] Checklist starting with ${intervalMs}ms interval`);
-
   // Boot triage at T+90s — after reboot sweep (T+5s) has completed and results are available
-  setTimeout(() => createBootTriageTask(), 90_000);
+  bootTriageTimeout = setTimeout(() => createBootTriageTask(), 90_000);
+
+  if (intervalMs <= 0) {
+    console.log(
+      "[Heartbeat] Recurring checklist off (HEARTBEAT_CHECKLIST_INTERVAL_MS=0); boot triage still scheduled",
+    );
+    return;
+  }
+
+  console.log(`[Heartbeat] Checklist starting with ${intervalMs}ms interval`);
 
   // Recurring checklist starts from the second interval onward
   checklistInterval = setInterval(() => {
@@ -1864,6 +1909,10 @@ export function startHeartbeatChecklist(intervalMs = HEARTBEAT_CHECKLIST_INTERVA
  * Stop the heartbeat checklist polling loop.
  */
 export function stopHeartbeatChecklist(): void {
+  if (bootTriageTimeout) {
+    clearTimeout(bootTriageTimeout);
+    bootTriageTimeout = null;
+  }
   if (checklistInterval) {
     clearInterval(checklistInterval);
     checklistInterval = null;

package/src/heartbeat/templates.ts

@@ -28,8 +28,8 @@ Goal: Review system status and your standing orders, take action if needed.
 ## Instructions
 1. **Read your HEARTBEAT.md** — run \`read /workspace/HEARTBEAT.md\` to get the latest standing orders (the snapshot above may be slightly stale).
 2. **Prune tracked HEARTBEAT items FIRST.** Active Blockers + Watch Items + Open Discussion combined must stay at ≤10 items; 20 is the absolute max only when genuinely super busy. This cap does not apply to evergreen Standing Orders / Governance / Playbook-index reference sections. Before adding anything, re-check every tracked item against its lift trigger and remove anything resolved, stale, or past its trigger date. Lift incident detail to memory; never keep it inline in HEARTBEAT.md. Every new tracked item must include an explicit lift trigger + date; if it has no removal condition, do not add it. If the tracked list is already at/over cap, prune before (or instead of) adding — the cap is binding.
-3. **Run seeded heartbeat data-gathering.** Use \`script-run\` with global script \`Heartbeat Audit\` and pass the current HEARTBEAT.md text as \`heartbeatMarkdown\`. It covers Rules #10/#13/#15/#16/#17: resolved stale PRs, pool-target risk schedules, schedule/provider failure clusters, and whether daily-blocker-digest ran today. The Slack thread-reply check (Rule #11) stays Lead-side; the script runtime has no Slack token.
-4. Review the system status above plus the \`Heartbeat Audit\` result for anything that needs attention (stalled tasks, idle workers with available work, anomalies).
+3. **Run seeded heartbeat data-gathering.** Use \`script-run\` with the global scripts \`schedule-health\` and \`task-failure-audit\`, both with args \`{ "days": 1, "publishPage": false }\`. They report failing schedules and failure clusters. Check any other standing order in HEARTBEAT.md yourself. Scripts can read Slack too (\`ctx.swarm.slack_read\` or the seeded \`slack-thread-flatten\` script), so a recurring Slack check can be scripted.
+4. Review the system status above plus the script results for anything that needs attention (stalled tasks, idle workers with available work, anomalies).
 5. **CRITICAL — Reboot failure triage:** Failures with reason "worker session not found" or "worker session heartbeat is stale" indicate tasks that were INTERRUPTED by a server restart. These are NOT "expected auto-cleanup" — they represent work that was lost mid-execution. For each such failure:
    - Check what the task was (via \`get-task-details\` with the task ID from the failure)
    - If a retry task was auto-created (tagged \`reboot-retry\`), verify it is progressing

package/src/http/agents.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { isAlias } from "@desplega/model-catalog";
 import { ensure } from "@desplega.ai/business-use";
 import { z } from "zod";
 import {
@@ -29,6 +30,12 @@ import {
   upsertSwarmConfig,
 } from "../be/db";
 import { createEvent } from "../be/events";
+import { setAgentHarnessCliVersion } from "../be/harness-model-support";
+import {
+  sanitizeModelTierOverrides,
+  setAgentModelTierOverrides,
+} from "../be/model-tier-resolution";
+import { explicitModelError } from "../be/model-validation";
 import {
   getRuntimeInstanceById,
   listRuntimeInstancesForAgent,
@@ -150,6 +157,14 @@ const registerAgent = route({
      * enforcing the mode-dependent requirement.
      */
     runtimeInstanceId: z.string().min(1).optional(),
+    /**
+     * The worker's parsed MODEL_TIER_* env overrides, {provider: {tier: model}}.
+     * Values only. Stored on the agent row for claim-time resolution; `{}`
+     * clears, omitted leaves the stored value unchanged.
+     */
+    modelTierOverrides: z.record(z.string(), z.record(z.string(), z.string())).optional(),
+    /** The worker's harness CLI version (`claude --version` / `codex --version`). */
+    harnessCliVersion: z.string().max(64).optional(),
   }),
   responses: {
     200: {
@@ -246,7 +261,7 @@ const updateAgentRuntimeRoute = route({
   pattern: ["api", "agents", null, "runtime"],
   summary: "Update an agent's runtime harness and default model",
   description:
-    "Updates `agents.harness_provider` and agent-scoped runtime config. The settings apply to future provider sessions. For `model`, `reasoning_effort`, and `claude.transport`: omit the field to leave it unchanged, send `null` to clear the corresponding override, or send a value to set it.",
+    "Updates `agents.harness_provider` and agent-scoped runtime config. The settings apply to future provider sessions. For `model`, `reasoning_effort`, and `claude.transport`: omit the field to leave it unchanged, send `null` to clear the corresponding override, or send a value to set it. A `model` the model catalog does not list is a 400 unless `allow_custom_model` is true. A `latest:` alias is not accepted here (aliases resolve for a task's model and for `MODEL_TIER_*` values); `reasoning_effort` must be one the harness and model support.",
   tags: ["Agents"],
   params: z.object({ id: z.string() }),
   query: z.object({ repoId: z.string().optional() }),
@@ -708,6 +723,17 @@ export async function handleAgentRegister(
       return { agent, created: true };
     });
 
+    if (parsed.body.harnessCliVersion !== undefined) {
+      await setAgentHarnessCliVersion(agentId, parsed.body.harnessCliVersion.trim() || null);
+    }
+
+    if (parsed.body.modelTierOverrides) {
+      await setAgentModelTierOverrides(
+        agentId,
+        sanitizeModelTierOverrides(parsed.body.modelTierOverrides),
+      );
+    }
+
     telemetry.agent("registered", {
       role: parsed.body.role,
       capabilities: parsed.body.capabilities ?? [],
@@ -1108,6 +1134,28 @@ export async function handleAgentsRest(
       }
     }
 
+    // An explicit model must be in the catalog unless the caller marks it custom
+    // (`allow_custom_model`). `null` clears the override and `undefined` leaves it.
+    if (typeof model === "string" && isAlias(model)) {
+      jsonError(
+        res,
+        `A latest: alias cannot be an agent's default model ("${model}"). Set the alias on a task, or as a MODEL_TIER_<PROVIDER>_<TIER> value.`,
+        400,
+      );
+      return true;
+    }
+    if (typeof model === "string") {
+      const modelError = await explicitModelError({
+        model,
+        allowCustomModel: allow_custom_model,
+        harnessProvider: harness_provider,
+      });
+      if (modelError) {
+        jsonError(res, modelError, 400);
+        return true;
+      }
+    }
+
     let agent: Agent | null;
     try {
       agent = await getDbClient().transaction(async () => {

package/src/http/index.ts

@@ -15,6 +15,7 @@ import {
   upsertSwarmConfig,
 } from "../be/db";
 import { startDbRetention, stopDbRetention } from "../be/db-retention";
+import { startHumanFreeDrain, stopHumanFreeDrain } from "../be/human-free-drain";
 import {
   enqueueAuditRow,
   flushAuditBuffer,
@@ -488,6 +489,9 @@ async function shutdown() {
   // Stop opt-in session, agent-log, and event retention before closing SQLite.
   await stopDbRetention();
 
+  // Stop the human-free reclassification drain before closing SQLite.
+  stopHumanFreeDrain();
+
   // Stop scratch-script retention garbage collector
   stopScratchScriptGc();
 
@@ -771,6 +775,10 @@ httpServer
     // read on each tick, so config reloads take effect without a restart.
     await startDbRetention();
 
+    // Finish the human-free reclassification a request left queued (a very large
+    // task tree, or a restart mid-drain). Wakes on demand; see human-free-drain.ts.
+    startHumanFreeDrain();
+
     // (RBAC audit sink is wired pre-listen — see above httpServer.listen.)
 
     // Background backfill: re-embed any agent_memory rows with wrong-dimension