@desplega.ai/agent-swarm 1.165.0 → 1.167.0

package/src/be/seed-pricing.ts

@@ -183,6 +183,55 @@ function projectCostBlock(
   return rows;
 }
 
+/** A projected row plus the models.dev id it came from, before normalized ids are collapsed. */
+interface SourcedSeedRow {
+  sourceId: string;
+  row: PricingSeedRow;
+}
+
+/** Whether `candidate` beats `current` as the source of a normalized `key`. */
+function outranksSource(candidate: string, current: string, key: string): boolean {
+  const a = candidate.toLowerCase();
+  const b = current.toLowerCase();
+  if ((a === key) !== (b === key)) return a === key;
+  return a > b;
+}
+
+/**
+ * `normalizeModelKey` can fold several models.dev ids onto one key: amp strips
+ * OpenAI's dated snapshots, so `gpt-4o`, `gpt-4o-2024-05-13`, `gpt-4o-2024-08-06`
+ * and `gpt-4o-2024-11-20` all become `amp|gpt-4o`, at different prices. The
+ * refresh writes every changed row at one `effective_from`, so two prices for
+ * one (provider, model, tokenClass) hit the pricing primary key and roll back
+ * the whole batch.
+ *
+ * Rule: one source id wins per (provider, normalized model), and all its token
+ * classes come from it. The id that is already canonical (the undated alias)
+ * wins; failing that, the greatest id, i.e. the newest dated snapshot. A source
+ * id repeated across catalog sections keeps its first row per token class.
+ */
+function collapseNormalizedIds(sourced: SourcedSeedRow[]): PricingSeedRow[] {
+  const modelKey = (row: PricingSeedRow) => `${row.provider}\u0000${row.model}`;
+  const winners = new Map<string, string>();
+  for (const { sourceId, row } of sourced) {
+    const current = winners.get(modelKey(row));
+    if (current === undefined || outranksSource(sourceId, current, row.model)) {
+      winners.set(modelKey(row), sourceId);
+    }
+  }
+
+  const seen = new Set<string>();
+  const rows: PricingSeedRow[] = [];
+  for (const { sourceId, row } of sourced) {
+    if (winners.get(modelKey(row)) !== sourceId) continue;
+    const rowKey = `${modelKey(row)}\u0000${row.tokenClass}`;
+    if (seen.has(rowKey)) continue;
+    seen.add(rowKey);
+    rows.push(row);
+  }
+  return rows;
+}
+
 /**
  * Build the full set of seed rows from a loaded models.dev cache.
  *
@@ -191,7 +240,10 @@ function projectCostBlock(
  * explicit and auditable.
  */
 export function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[] {
-  const rows: PricingSeedRow[] = [];
+  const sourced: SourcedSeedRow[] = [];
+  const add = (sourceId: string, projected: PricingSeedRow[]) => {
+    for (const row of projected) sourced.push({ sourceId, row });
+  };
 
   // ---- Anthropic / claude family ----------------------------------------
   // The 'claude' provider (local-CLI adapter) reports the model id as the
@@ -202,9 +254,7 @@ export function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[]
   for (const [id, model] of Object.entries(anthropic)) {
     if (!model?.cost) continue;
     for (const provider of ["claude", "claude-managed"] as const) {
-      for (const row of projectCostBlock(provider, id, model.cost)) {
-        rows.push(row);
-      }
+      add(id, projectCostBlock(provider, id, model.cost));
     }
   }
   // Anthropic shortnames (opus/sonnet/haiku) → resolve to the current default.
@@ -214,9 +264,7 @@ export function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[]
       (cache.anthropic ? ANTHROPIC_SHORTNAME_PRICING_FALLBACKS[fullId] : undefined);
     if (!cost) continue;
     for (const provider of ["claude", "claude-managed"] as const) {
-      for (const row of projectCostBlock(provider, shortname, cost)) {
-        rows.push(row);
-      }
+      add(shortname, projectCostBlock(provider, shortname, cost));
     }
   }
   // Pi-mono uses anthropic models via OpenRouter mirrors; project those too.
@@ -225,9 +273,7 @@ export function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[]
       anthropic[fullId]?.cost ??
       (cache.anthropic ? ANTHROPIC_SHORTNAME_PRICING_FALLBACKS[fullId] : undefined);
     if (!cost) continue;
-    for (const row of projectCostBlock("pi", shortname, cost, { anthropicBilled: true })) {
-      rows.push(row);
-    }
+    add(shortname, projectCostBlock("pi", shortname, cost, { anthropicBilled: true }));
   }
 
   // ---- Amp (Anthropic, OpenAI, Google and Fireworks models by id) ---------
@@ -237,9 +283,7 @@ export function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[]
   for (const section of ["anthropic", "openai", "google", "fireworks-ai"]) {
     for (const [id, model] of Object.entries(cache[section]?.models ?? {})) {
       if (!model?.cost) continue;
-      for (const row of projectCostBlock("amp", id, model.cost)) {
-        rows.push(row);
-      }
+      add(id, projectCostBlock("amp", id, model.cost));
     }
   }
 
@@ -247,16 +291,12 @@ export function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[]
   const openai = cache.openai?.models ?? {};
   for (const [id, model] of Object.entries(openai)) {
     if (!model?.cost) continue;
-    for (const row of projectCostBlock("codex", id, model.cost)) {
-      rows.push(row);
-    }
+    add(id, projectCostBlock("codex", id, model.cost));
     // Phase 2 fix — pi-mono can route to openai models through the
     // github-copilot proxy (`github-copilot/gpt-5.4`). The lookup helper
     // strips the prefix, so we seed the bare id under `pi` too. Without this
     // every gh-copilot-backed pi run fell through to `costSource='unpriced'`.
-    for (const row of projectCostBlock("pi", id, model.cost)) {
-      rows.push(row);
-    }
+    add(id, projectCostBlock("pi", id, model.cost));
   }
 
   // ---- Cursor (bare vendor ids through Cursor's hosted inference) --------
@@ -267,27 +307,21 @@ export function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[]
   for (const vendor of ["openai", "anthropic", "google", "xai"] as const) {
     for (const [id, model] of Object.entries(cache[vendor]?.models ?? {})) {
       if (!model?.cost) continue;
-      for (const row of projectCostBlock("cursor", id, model.cost, { anthropicBilled: false })) {
-        rows.push(row);
-      }
+      add(id, projectCostBlock("cursor", id, model.cost, { anthropicBilled: false }));
     }
   }
 
   // ---- Grok CLI (bare xAI ids, billed at xAI's API rates via XAI_API_KEY) --
   for (const [id, model] of Object.entries(cache.xai?.models ?? {})) {
     if (!model?.cost) continue;
-    for (const row of projectCostBlock("grok", id, model.cost, { anthropicBilled: false })) {
-      rows.push(row);
-    }
+    add(id, projectCostBlock("grok", id, model.cost, { anthropicBilled: false }));
   }
 
   // ---- DeepSeek direct API (dsh with DEEPSEEK_API_KEY, bare ids) ---------
   const deepseek = cache.deepseek?.models ?? {};
   for (const [id, model] of Object.entries(deepseek)) {
     if (!model?.cost) continue;
-    for (const row of projectCostBlock("dsh", id, model.cost)) {
-      rows.push(row);
-    }
+    add(id, projectCostBlock("dsh", id, model.cost));
   }
 
   // ---- OpenRouter passthrough (covers gemini + every opencode-routed model)
@@ -295,48 +329,45 @@ export function buildModelsDevSeedRows(cache: ModelsDevCache): PricingSeedRow[]
   for (const [id, model] of Object.entries(openrouter)) {
     if (!model?.cost) continue;
     // opencode routes whatever model the user picks; we project them all.
-    for (const row of projectCostBlock("opencode", id, model.cost)) {
-      rows.push(row);
-    }
+    add(id, projectCostBlock("opencode", id, model.cost));
     // pi-mono also routes via OpenRouter when only OPENROUTER_API_KEY is set
     // (see src/providers/pi-mono-adapter.ts). Without this projection, pi runs
     // against non-anthropic models (e.g. deepseek/deepseek-v4-flash) fall
     // through to costSource='unpriced' even though the model is in the
     // models.dev snapshot.
-    for (const row of projectCostBlock("pi", id, model.cost, {
-      anthropicBilled: id.startsWith("anthropic/"),
-    })) {
-      rows.push(row);
-    }
+    add(
+      id,
+      projectCostBlock("pi", id, model.cost, {
+        anthropicBilled: id.startsWith("anthropic/"),
+      }),
+    );
     // dsh routes `openrouter/<id>` models (all four tier defaults) through
     // OpenRouter, so it bills at the same rates.
-    for (const row of projectCostBlock("dsh", id, model.cost, {
-      anthropicBilled: id.startsWith("anthropic/"),
-    })) {
-      rows.push(row);
-    }
+    add(
+      id,
+      projectCostBlock("dsh", id, model.cost, {
+        anthropicBilled: id.startsWith("anthropic/"),
+      }),
+    );
     // grok runs `openrouter/<id>` models as OpenAI-compatible BYOK models.
-    for (const row of projectCostBlock("grok", id, model.cost, {
-      anthropicBilled: id.startsWith("anthropic/"),
-    })) {
-      rows.push(row);
-    }
+    add(
+      id,
+      projectCostBlock("grok", id, model.cost, {
+        anthropicBilled: id.startsWith("anthropic/"),
+      }),
+    );
     // Gemini specifically: also project under the 'gemini' provider so
     // internal-ai callers that tag with provider='gemini' find a hit.
     if (id.startsWith("google/")) {
       const geminiKey = id.replace(/^google\//, "");
-      for (const row of projectCostBlock("gemini", geminiKey, model.cost)) {
-        rows.push(row);
-      }
+      add(geminiKey, projectCostBlock("gemini", geminiKey, model.cost));
       // Also store under the full openrouter id so the same row resolves
       // whether the caller passes "google/..." or the stripped name.
-      for (const row of projectCostBlock("gemini", id, model.cost)) {
-        rows.push(row);
-      }
+      add(id, projectCostBlock("gemini", id, model.cost));
     }
   }
 
-  return rows;
+  return collapseNormalizedIds(sourced);
 }
 
 /** Build the exact provider rows inserted by the boot-time pricing seeder. */

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

@@ -1,6 +1,7 @@
 import { normalizeSlackReactionShortcode } from "../slack/reaction-shortcode";
 import { ProviderNameSchema } from "../types";
 import { API_DRAIN_MAX_MS_LIMIT } from "../utils/api-drain";
+import { parseEnabledTools } from "../utils/enabled-tools";
 import { parseTaskToolManifest } from "../utils/task-tool-manifest";
 import { isTierConfigKey, validateTierConfigValue } from "./model-tier-keys";
 
@@ -212,6 +213,17 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
       return "Invalid TASK_TOOL_MANIFESTS (expected JSON with taskTypes and/or schedules maps, each selecting at most 16 known swarm tools)";
     }
   },
+  // MCP tool allowlist: comma-separated names or a JSON array of strings.
+  // Unknown names are accepted here and warned about at session init.
+  SWARM_ENABLED_TOOLS: (value) => {
+    try {
+      if (typeof value !== "string") throw new Error("Expected string");
+      parseEnabledTools(value);
+      return null;
+    } catch {
+      return "Invalid SWARM_ENABLED_TOOLS (expected comma-separated tool names or a JSON array of strings)";
+    }
+  },
   FEEDBACK_ENDPOINT: (value) => {
     if (typeof value !== "string") {
       return "Invalid FEEDBACK_ENDPOINT (must use HTTPS, or HTTP on a loopback host)";
@@ -304,6 +316,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "PI_TOOL_DEFERRAL",
     "PI_CODEMODE",
     "PI_CODEMODE_MODELS",
+    "OPENROUTER_APP_ATTRIBUTION",
     "CURSOR_NATIVE_SYSTEM_PROMPT",
     "SLACK_DISABLE",
     "SLACK_RENDER_V2",

package/src/be/workflow-replay.ts

@@ -0,0 +1,77 @@
+import { openSealedJson } from "./sealed-json";
+
+/**
+ * Which copy of a workflow payload a reader gets.
+ *
+ * - `replay`: the exact value from the sealed `*_replay` column. Resume, retry,
+ *   dedup and recovery rebuild the live ctx from it, so a downstream consumer
+ *   sees the same bytes after a restart as in the uninterrupted run.
+ * - `display`: the scrubbed column, for API responses, MCP tools and the UI.
+ */
+export type WorkflowPayloadView = "replay" | "display";
+
+/**
+ * A sealed replay copy exists but cannot be opened (missing or rotated
+ * encryption key, corrupt ciphertext). The scrubbed copy holds redaction
+ * markers, so replaying it would silently feed them to downstream nodes: the
+ * run fails with this error instead.
+ */
+export class WorkflowReplayStateError extends Error {
+  constructor(
+    readonly runId: string,
+    readonly target: string,
+    cause: unknown,
+  ) {
+    super(
+      `Workflow run ${runId} cannot replay ${target}: its sealed replay copy could not be opened (${
+        cause instanceof Error ? cause.message : String(cause)
+      }). The redacted copy is never replayed. Restore the SECRETS_ENCRYPTION_KEY that sealed it, then retry the run.`,
+    );
+    this.name = "WorkflowReplayStateError";
+  }
+}
+
+/**
+ * Set `target[key]` from a workflow payload pair.
+ *
+ * `display` parses the scrubbed column. `replay` opens the sealed column
+ * lazily, on first read of the property: status-only readers (cancel, polls,
+ * cooldown) never decrypt and keep working without the key. Rows written before
+ * the replay columns existed have no sealed copy and fall back to the plain
+ * column.
+ */
+export function defineWorkflowPayload<T extends object>(
+  target: T,
+  key: keyof T & string,
+  plain: string | null | undefined,
+  sealed: string | null | undefined,
+  view: WorkflowPayloadView,
+  where: { runId: string; target: string },
+): T {
+  if (view === "display" || !sealed) {
+    (target as Record<string, unknown>)[key] = plain ? JSON.parse(plain) : undefined;
+    return target;
+  }
+  let opened = false;
+  let value: unknown;
+  Object.defineProperty(target, key, {
+    enumerable: true,
+    configurable: true,
+    get() {
+      if (!opened) {
+        try {
+          value = openSealedJson(sealed);
+        } catch (err) {
+          throw new WorkflowReplayStateError(where.runId, where.target, err);
+        }
+        opened = true;
+      }
+      return value;
+    },
+    set(next: unknown) {
+      value = next;
+      opened = true;
+    },
+  });
+  return target;
+}

package/src/commands/provider-credentials.ts

@@ -19,6 +19,7 @@
  */
 
 import { deriveDefaultRoute, validateRoute } from "@desplega/model-routing";
+import { ACP_TARGET_IDS, isAcpTarget } from "../providers/acp-target-catalog";
 import { checkAmpCredentials, liveTestAmpCredentials } from "../providers/amp-adapter";
 import { checkClaudeCredentials } from "../providers/claude-adapter";
 import { checkClaudeManagedCredentials } from "../providers/claude-managed-adapter";
@@ -38,7 +39,10 @@ import type {
   ReasoningEffort,
 } from "../types";
 import { CLAUDE_CREDENTIALS_HINT } from "../utils/credentials";
-import { getOpenRouterBaseUrl } from "../utils/openrouter-base-url";
+import {
+  getOpenRouterAttributionHeaders,
+  getOpenRouterBaseUrl,
+} from "../utils/openrouter-base-url";
 import { scrubSecrets } from "../utils/secret-scrubber";
 
 export type SupportedProvider =
@@ -114,7 +118,7 @@ export const REQUIRED_CRED_VARS_BY_PROVIDER: Record<SupportedProvider, readonly
   devin: ["DEVIN_API_KEY", "DEVIN_ORG_ID"],
   opencode: ["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
   pi: ["ANTHROPIC_API_KEY", "OPENROUTER_API_KEY", "OPENAI_API_KEY"],
-  // The ACP target process owns its own auth, so the swarm requires nothing.
+  // The ACP target owns its auth; custom targets still need a command.
   acp: [],
   dsh: ["DEEPSEEK_API_KEY", "OPENROUTER_API_KEY"],
   amp: ["AMP_API_KEY"],
@@ -142,7 +146,25 @@ export const CREDENTIAL_PROVIDER_CHECKERS: Record<SupportedProvider, CredentialC
     const { checkPiMonoCredentials } = await import("../providers/pi-mono-adapter");
     return checkPiMonoCredentials(env, opts);
   },
-  acp: () => ({ ready: true, missing: [], satisfiedBy: "sdk-delegated" }),
+  acp: (env) => {
+    const target = env.ACP_TARGET ?? "custom";
+    if (!isAcpTarget(target)) {
+      return {
+        ready: false,
+        missing: ["ACP_TARGET"],
+        hint: `Set ACP_TARGET to one of: ${ACP_TARGET_IDS.join(", ")}.`,
+      };
+    }
+    const command = env.ACP_TARGET_COMMAND ?? env.ACP_COMMAND;
+    if (target === "custom" && !command?.trim()) {
+      return {
+        ready: false,
+        missing: ["ACP_TARGET_COMMAND"],
+        hint: "Set ACP_TARGET_COMMAND (or ACP_COMMAND) to an ACP-compatible executable, or select a preset with ACP_TARGET.",
+      };
+    }
+    return { ready: true, missing: [], satisfiedBy: "sdk-delegated" };
+  },
 };
 
 /**
@@ -288,9 +310,10 @@ async function checkXaiApiKey(apiKey: string): Promise<LiveValidationResult> {
 }
 
 async function checkOpenRouter(apiKey: string): Promise<LiveValidationResult> {
-  const r = await timedFetch(`${getOpenRouterBaseUrl()}/models`, {
+  const url = `${getOpenRouterBaseUrl()}/models`;
+  const r = await timedFetch(url, {
     method: "GET",
-    headers: { Authorization: `Bearer ${apiKey}` },
+    headers: { ...getOpenRouterAttributionHeaders(url), Authorization: `Bearer ${apiKey}` },
   });
   if (r.ok) return { ok: true, latency_ms: r.latency_ms };
   return {

package/src/commands/runner.ts

@@ -21,7 +21,10 @@ import {
 import { type RelevantMemory, renderMemoriesPrompt } from "../prompts/memories.ts";
 import { configureHttpResolver, resolveTemplateAsync } from "../prompts/resolver.ts";
 import { renderSteeringDelivery } from "../prompts/steering-delivery.ts";
-import { authJsonToCredentialSelection } from "../providers/codex-oauth/auth-json.js";
+import {
+  authJsonToCredentialSelection,
+  credentialsToAuthJson,
+} from "../providers/codex-oauth/auth-json.js";
 import { materializeCodexAuthJson } from "../providers/codex-oauth/auth-json-fs.js";
 import {
   CODEX_OAUTH_POOL_SLOTS_ENV,
@@ -1937,17 +1940,9 @@ export async function resolveCodexOAuthCredentialInfo(
           await materializeCodexAuthJson(selectedSlot, slotEntry.creds, {
             includeRefreshToken: false,
           });
-          const authJson = {
-            auth_mode: "chatgpt" as const,
-            OPENAI_API_KEY: null,
-            tokens: {
-              id_token: slotEntry.creds.access,
-              access_token: slotEntry.creds.access,
-              refresh_token: slotEntry.creds.refresh,
-              account_id: slotEntry.creds.accountId,
-            },
-            last_refresh: new Date(slotEntry.creds.expires).toISOString(),
-          };
+          const authJson = credentialsToAuthJson(slotEntry.creds, {
+            includeRefreshToken: false,
+          });
           const sel = {
             ...authJsonToCredentialSelection(authJson, selectedSlot, slots.length),
             authFailureFence,

package/src/heartbeat/heartbeat.ts

@@ -1,3 +1,4 @@
+import pkg from "../../package.json";
 import {
   autoCancelStaleApprovalRequests,
   timeoutExpiredApprovalRequests,
@@ -247,6 +248,15 @@ function isHeartbeatChecklistDisabled(): boolean {
   return isEnvFlagEnabled("HEARTBEAT_CHECKLIST_DISABLE", false);
 }
 
+/**
+ * Whether to create the boot-triage task even when the boot is clean (no
+ * interrupted, stalled, orphaned, or resume-less superseded work). Off by
+ * default: a clean boot only logs a one-line note.
+ */
+function isBootTriageAlways(): boolean {
+  return isEnvFlagEnabled("HEARTBEAT_BOOT_TRIAGE_ALWAYS", false);
+}
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -1576,24 +1586,7 @@ export async function gatherSystemStatus(options?: { isBootTriage?: boolean }):
     }
 
     // Orphaned pending/offered tasks (assigned to workers with no active session)
-    const orphanedTasks: AgentTask[] = [];
-
-    for (const status of ["pending", "offered"] as const) {
-      const tasks = await getTasksByStatus(status);
-
-      for (const task of tasks) {
-        // 'pending' tasks carry their holder in agentId; 'offered' tasks have
-        // not been accepted yet, so agentId is still NULL and the offeree
-        // lives in offeredTo instead (#1190) — `!task.agentId` alone used to
-        // skip every offered row here, hiding this whole class of orphan.
-        const holderId = status === "offered" ? task.offeredTo : task.agentId;
-        if (!holderId) continue;
-        const agent = agents.find((a) => a.id === holderId);
-        if (!agent || agent.status === "offline") {
-          orphanedTasks.push(task);
-        }
-      }
-    }
+    const orphanedTasks = await getOrphanedPendingOrOfferedTasks(agents);
 
     if (orphanedTasks.length > 0) {
       sections.push("");
@@ -1617,6 +1610,60 @@ export async function gatherSystemStatus(options?: { isBootTriage?: boolean }):
   return sections.join("\n");
 }
 
+/** Pending/offered tasks whose holder is offline or no longer registered. */
+async function getOrphanedPendingOrOfferedTasks(
+  agents: Awaited<ReturnType<typeof getAllAgents>>,
+): Promise<AgentTask[]> {
+  const orphanedTasks: AgentTask[] = [];
+
+  for (const status of ["pending", "offered"] as const) {
+    const tasks = await getTasksByStatus(status);
+
+    for (const task of tasks) {
+      // 'pending' tasks carry their holder in agentId; 'offered' tasks have
+      // not been accepted yet, so agentId is still NULL and the offeree
+      // lives in offeredTo instead (#1190) — `!task.agentId` alone used to
+      // skip every offered row here, hiding this whole class of orphan.
+      const holderId = status === "offered" ? task.offeredTo : task.agentId;
+      if (!holderId) continue;
+      const agent = agents.find((a) => a.id === holderId);
+      if (!agent || agent.status === "offline") {
+        orphanedTasks.push(task);
+      }
+    }
+  }
+
+  return orphanedTasks;
+}
+
+export interface BootTriageFindings {
+  rebootInterrupted: number;
+  stalled: number;
+  orphaned: number;
+  supersededWithoutResume: number;
+}
+
+/**
+ * Count the boot signals the Lead would have to act on. All zero means a
+ * clean boot: nothing was interrupted, stuck, orphaned, or left without a
+ * resume, so a Lead task would only echo the deploy.
+ */
+export async function getBootTriageFindings(): Promise<BootTriageFindings> {
+  const now = Date.now();
+  const agents = await getAllAgents();
+  return {
+    rebootInterrupted: getRebootAffectedTasks().length,
+    stalled: (await getStalledInProgressTasks(stallThresholdMinutes())).length,
+    orphaned: (await getOrphanedPendingOrOfferedTasks(agents)).length,
+    supersededWithoutResume: (
+      await getSupersededTasksWithoutResume(
+        new Date(now - ORPHAN_SUPERSEDE_MIN_AGE_MS).toISOString(),
+        new Date(now - ORPHAN_SUPERSEDE_MAX_AGE_MS).toISOString(),
+      )
+    ).length,
+  };
+}
+
 /**
  * Check HEARTBEAT.md content and create a checklist task for the lead if needed.
  */
@@ -1858,6 +1905,8 @@ export function stopHeartbeat(): void {
 /**
  * Create a one-off boot triage task for the lead after a server restart.
  * Uses the same HEARTBEAT.md content but with reboot-specific context prepended.
+ * Skipped on a clean boot (see getBootTriageFindings) unless
+ * HEARTBEAT_BOOT_TRIAGE_ALWAYS is set.
  */
 export async function createBootTriageTask(): Promise<void> {
   const lead = await getLeadAgent();
@@ -1876,7 +1925,30 @@ export async function createBootTriageTask(): Promise<void> {
   );
   if (existing) return;
 
-  const systemStatus = await gatherSystemStatus({ isBootTriage: true });
+  if (!isBootTriageAlways()) {
+    // A failed read falls through to the Lead task: an unknown boot is not a
+    // clean one.
+    const findings = await getBootTriageFindings().catch((err) => {
+      console.error(
+        "[Heartbeat] Boot triage findings failed, creating Lead task:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      );
+      return null;
+    });
+    if (findings && Object.values(findings).every((count) => count === 0)) {
+      console.log(
+        `[Heartbeat] Clean boot (v${pkg.version}): 0 interrupted, stalled, orphaned, or resume-less superseded tasks; no boot-triage task for lead ${lead.name}`,
+      );
+      return;
+    }
+  }
+
+  // A reader that failed above can fail again here; the task must still land.
+  const systemStatus = await gatherSystemStatus({ isBootTriage: true }).catch((err) => {
+    const reason = scrubSecrets(err instanceof Error ? err.message : String(err));
+    console.error("[Heartbeat] Boot triage status gathering failed:", reason);
+    return `## System status unavailable\n\nStatus gathering failed after this boot (${reason}). Investigate the task, agent, and DB state directly.`;
+  });
 
   const result = resolveTemplate("heartbeat.boot-triage", {
     system_status: systemStatus,