@desplega.ai/agent-swarm 1.158.0 → 1.160.0

package/src/commands/seat-mismatch-report.ts

@@ -0,0 +1,46 @@
+import type { ModelFamily } from "../utils/model-rate-limit-windows";
+
+export interface SeatMismatchCredential {
+  keyType: string;
+  keySuffix: string;
+  keyIndex: number;
+}
+
+/**
+ * Reports a seat mismatch (`credits_required`) for a key: its subscription
+ * seat cannot run `model`. Never marks the key rate-limited: the key stays
+ * available for every model its seat can run.
+ *
+ * The completion loop awaits this before it finishes the task, so the seat
+ * block reaches the API before another worker admits the next task. A failed
+ * report is logged and never throws.
+ */
+export async function reportSeatMismatchOutcome(
+  apiUrl: string,
+  apiKey: string,
+  credential: SeatMismatchCredential,
+  model: ModelFamily,
+): Promise<void> {
+  const { keyType, keySuffix, keyIndex } = credential;
+  const modelLabel = model.charAt(0).toUpperCase() + model.slice(1);
+  console.log(
+    `[credential] seat mismatch: key #${keyIndex} (...${keySuffix}) cannot run ${modelLabel}`,
+  );
+  try {
+    const response = await fetch(`${apiUrl}/api/keys/report-seat-mismatch`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({ keyType, keySuffix, keyIndex, model }),
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+  } catch (err) {
+    console.warn(
+      `[credential] Failed to report seat mismatch for key #${keyIndex}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}

package/src/extensions/apply-task-create.ts

@@ -1,3 +1,4 @@
+import { explicitModelErrorForAgent } from "../be/model-validation";
 import type { RequestInfo } from "../tools/utils";
 import { type CreateTaskOptions, CreateTaskOptionsSchema } from "../types";
 import { scrubSecrets } from "../utils/secret-scrubber";
@@ -48,6 +49,8 @@ type ApplyPreTaskCreateArgs = {
   options: CreateTaskOptions;
   origin: TaskCreateOrigin;
   requestInfo?: RequestInfo;
+  /** The caller's escape hatch for an uncatalogued `model`; the harness check ignores it. */
+  allowCustomModel?: boolean;
 };
 
 export type ApplyPreTaskCreateResult =
@@ -77,6 +80,9 @@ export async function applyPreTaskCreate(
     ? (`extension:${creatingExtension.record.name}` as const)
     : args.origin;
 
+  // The last extension that rewrote `model` or `agentId`. The final pair is re-checked
+  // against the assignee's harness, because the caller validated the pre-hook pair only.
+  let modelEditor: { id: string; name: string } | undefined;
   const result = await dispatchPre(
     "pre.task.create",
     {
@@ -110,6 +116,9 @@ export async function applyPreTaskCreate(
 
         const { description: _description, ...optionChanges } = filtered;
         CreateTaskOptionsSchema.parse({ ...currentOptions, ...optionChanges });
+        if ("model" in optionChanges || "agentId" in optionChanges) {
+          modelEditor = { id: extension.id, name: extension.name };
+        }
         return filtered;
       },
     },
@@ -127,9 +136,26 @@ export async function applyPreTaskCreate(
   }
 
   const { description, ...optionChanges } = result.data;
+  const options = CreateTaskOptionsSchema.parse({ ...args.options, ...optionChanges });
+  if (modelEditor) {
+    const modelError = await explicitModelErrorForAgent({
+      model: options.model,
+      // An unchanged model already passed the caller's catalog check; only the harness
+      // check is new for it.
+      allowCustomModel: args.allowCustomModel || options.model === args.options.model,
+      agentId: options.agentId,
+    });
+    if (modelError) {
+      return {
+        kind: "blocked",
+        reason: `pre.task.create rewrite from extension "${modelEditor.name}" is invalid: ${modelError}`,
+        extension: modelEditor,
+      };
+    }
+  }
   return {
     kind: "proceed",
     description: description ?? args.description,
-    options: CreateTaskOptionsSchema.parse({ ...args.options, ...optionChanges }),
+    options,
   };
 }

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,10 +43,12 @@ import {
   releaseStaleOfferedTasksForOfflineAgents,
   releaseStaleProcessingInbox,
   releaseStaleReviewingTasks,
+  settleSupersededTaskDependents,
   supersedeTask,
   updateAgentStatus,
 } from "../be/db";
 import { repointTrackerSyncBySwarmId } from "../be/db-queries/tracker";
+import { poolTaskRunsOnHarness } from "../be/model-validation";
 import {
   agentsWithLiveRuntime,
   countActiveRuntimeInstancesForAgent,
@@ -66,6 +69,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 +221,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 +297,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 +553,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 +573,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 +717,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({
@@ -1107,7 +1146,9 @@ async function autoAssignPoolTasks(findings: HeartbeatFindings): Promise<void> {
         for (const w of idleWorkers) {
           if (
             (await reservedForWorker(w.id)) < (w.maxTasks ?? 1) &&
-            isAgentEligibleForTask(w, task)
+            isAgentEligibleForTask(w, task) &&
+            // A pinned model from another harness family waits for a compatible worker.
+            (await poolTaskRunsOnHarness(task, w.harnessProvider ?? w.provider ?? null))
           ) {
             worker = w;
             break;
@@ -1264,7 +1305,17 @@ async function escalateStarvedPoolTasks(findings: HeartbeatFindings): Promise<vo
   const registeredAgents = (await getAllAgents()).filter((a) => !a.isLead);
 
   for (const task of candidates) {
-    const hasEligibleAgent = registeredAgents.some((agent) => isAgentEligibleForTask(agent, task));
+    let hasEligibleAgent = false;
+    for (const agent of registeredAgents) {
+      // Eligible means routable AND able to run the task's pinned model on its harness.
+      if (
+        isAgentEligibleForTask(agent, task) &&
+        (await poolTaskRunsOnHarness(task, agent.harnessProvider ?? agent.provider ?? null))
+      ) {
+        hasEligibleAgent = true;
+        break;
+      }
+    }
     if (hasEligibleAgent) continue; // Someone (any status) matches — keep queued.
 
     const decision = await createPoolStarvationDecisionTask({ original: task });
@@ -1835,19 +1886,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 +1922,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, harnessModelErrorFor } 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() }),
@@ -659,6 +674,19 @@ export async function handleAgentRegister(
           parsed.body.harness_provider !== existingAgent.harnessProvider
         ) {
           await setAgentHarnessProvider(existingAgent.id, parsed.body.harness_provider);
+          // The agent-scope MODEL_OVERRIDE may still name the old harness family. The worker
+          // falls back to its adapter default at spawn; the row stays for a human to fix.
+          const harness = parsed.body.harness_provider;
+          const override = (
+            await getSwarmConfigs({ scope: "agent", scopeId: agentId, key: "MODEL_OVERRIDE" })
+          )[0]?.value;
+          if (override && (await harnessModelErrorFor(override, harness))) {
+            getDbClient().afterCommit(() => {
+              console.warn(
+                `[agents] MODEL_OVERRIDE ${override} of agent ${agentId} does not run on its new ${harness} harness (was ${existingAgent.harnessProvider ?? "unset"}); update or clear it`,
+              );
+            });
+          }
         }
         await resetEmptyPollCount(existingAgent.id);
         if (multiRuntime && parsed.body.runtimeInstanceId) {
@@ -708,6 +736,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 +1147,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 () => {