@desplega.ai/agent-swarm 1.166.0 → 1.168.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)";
@@ -251,6 +263,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     return `Invalid HARNESS_PROVIDER value (must be one of: ${ProviderNameSchema.options.join(", ")})`;
   },
   ...enumValidator("CLAUDE_TRANSPORT", ["cli", "sdk"]),
+  ...enumValidator("SCRIPT_EXECUTOR", ["native", "quickjs"]),
   // fail: worker fails a task fast when every key has exhausted the task
   // model's weekly window (Fable/Opus/Sonnet). fallback: legacy random pick.
   ...enumValidator("MODEL_WINDOW_EXHAUSTED_POLICY", ["fail", "fallback"]),
@@ -304,6 +317,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/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/extensions/catalog.generated.json

@@ -84,6 +84,23 @@
     },
     "readme": "# require-verification-note\n\nGuards `store-progress` with `status: \"completed\"`. The call is refused until the `output` contains the configured marker (default `Verified:`). The agent sees the reason as a tool error and can retry with a corrected output.\n\nConfig:\n\n```json\n{ \"marker\": \"Verified:\" }\n```\n\nThe guard covers agent MCP calls only. REST and dashboard completions are not tool calls and pass through.\n"
   },
+  "slack-reply-gate": {
+    "manifestFile": "manifest.json",
+    "manifest": {
+      "$schema": "../manifest.schema.json",
+      "name": "slack-reply-gate",
+      "description": "Asks Jev (TypeSafe or OpenRouter) whether Lead should answer a buffered Slack thread follow-up, and drops the wake-up when it should not",
+      "version": "1.2.0",
+      "runtime": "api",
+      "assets": {
+        "hooks": "hooks.ts"
+      }
+    },
+    "files": {
+      "hooks.ts": "import { type ApiCtx, block, type SwarmExtension } from \"swarm-extension\";\nimport { z } from \"zod\";\n\n/**\n * slack-reply-gate\n *\n * Every human message in a Slack thread the swarm takes part in is buffered and\n * flushed into a Lead task (\"[Thread follow-up — N message(s) buffered]\"), even\n * \"lol\", \":joy:\" or two people bantering. This hook asks TypeSafe Jev whether\n * Lead should answer, and drops the wake-up when the answer is no.\n *\n * Hook: `pre.task.create`, origin \"slack\", description carrying the\n * thread-buffer header. `pre.slack.route` cannot be used: the buffered thread\n * path returns before that hook is dispatched, and its result can only\n * re-target a message, never drop it.\n *\n * Rules:\n *   - A message that @mentions Lead passes without a Jev call.\n *   - Otherwise one Jev `choice` question classifies the message into a reason;\n *     reply=false only for reaction_only | banter_between_others |\n *     not_addressed_to_lead, and only when the summed probability of those\n *     three labels is >= minConfidence (a banter/reaction split is still a skip).\n *   - Fails OPEN on every error, timeout or missing key.\n *\n * Transport (config.provider): Jev is served by TypeSafe directly and by\n * OpenRouter's Decisions endpoint. Both take the same {model, state, questions}\n * body and return the same `answers` shape. `auto` uses TYPESAFE_API_KEY when\n * set, else OPENROUTER_API_KEY.\n *\n * modes (config.mode):\n *   off     -> never evaluate\n *   shadow  -> evaluate + record, never block (default)\n *   enforce -> record, block the task when reply=false, and mark the\n *              triggering Slack message with :mute: (config.muteReaction)\n *\n * Muting: no swarm tool or ctx method adds a Slack reaction, so the hook calls\n * the Slack Web API (reactions.remove / reactions.add) with the bot token. It\n * first removes the bot's own acceptance reactions (:eyes:, :heavy_plus_sign:,\n * :zap:, :speech_balloon:, or their SLACK_REACTION_* overrides), the same set\n * the engine clears when it finalizes a task, then adds :mute:. With\n * muteReaction \"\" it only removes them: a true no-op on the message. It runs after\n * the block decision returns, so a slow or failing Slack call never delays or\n * changes the drop; its errors go to the same KV namespace.\n *\n * Every decision lands in KV namespace `ext:slack-reply-gate`.\n */\n\nexport const config = z.object({\n  mode: z.enum([\"off\", \"shadow\", \"enforce\"]).default(\"shadow\"),\n  timeoutMs: z.number().int().positive().default(3000),\n  provider: z.enum([\"auto\", \"typesafe\", \"openrouter\"]).default(\"auto\"),\n  /** Jev model on the TypeSafe transport. */\n  model: z.string().default(\"jev-latest\"),\n  /** Jev model on the OpenRouter transport. */\n  openrouterModel: z.string().default(\"typesafe/jev-1.13\"),\n  minConfidence: z.number().min(0).max(1).default(0.55),\n  contextMessages: z.number().int().min(0).max(20).default(6),\n  leadAliases: z.array(z.string()).default([\"lead\"]),\n  botSlackUserIds: z.array(z.string()).default([]),\n  /** Explicit TypeSafe key; otherwise TYPESAFE_API_KEY from the API process env. */\n  apiKey: z.string().optional(),\n  /**\n   * Reaction for a dropped message in enforce mode. \"\" only removes the bot's\n   * acceptance reaction(s) and adds nothing.\n   */\n  muteReaction: z.string().default(\"mute\"),\n  slackTimeoutMs: z.number().int().positive().default(5000),\n});\n\ntype Cfg = z.infer<typeof config>;\ntype Swarm = ApiCtx[\"swarm\"];\n\nconst NS = \"ext:slack-reply-gate\";\nconst TYPESAFE_ENDPOINT = \"https://api.typesafe.ai/v1/systemone\";\nconst OPENROUTER_ENDPOINT = \"https://openrouter.ai/api/alpha/decisions\";\nconst HEADER_LINE_RE = /(?:^|\\n)\\[Thread follow-up — \\d+ message\\(s\\) buffered\\]\\n/g;\nconst CTX_OPEN = \"<thread_context>\";\nconst CTX_CLOSE = \"</thread_context>\";\n// The dispatcher cancels a handler after 5 s; leave room for the KV writes.\nconst MAX_TIMEOUT_MS = 4000;\n\nexport const REASONS = {\n  direct_ask:\n    \"Asks Lead (or the swarm, the bot, 'you' meaning the AI) a question or for something, explicitly or clearly implied.\",\n  followup_to_lead:\n    \"Answers, confirms, corrects or continues something Lead or another swarm agent ([Agent]) just said or asked, so Lead needs it to proceed.\",\n  instruction_to_lead:\n    \"Gives a task, instruction, request or decision for the AI to act on, even without naming it (for example 'can you create X', 'ship it', 'do it').\",\n  reaction_only:\n    \"Only a reaction: emoji, laughter (lol, haha, jaja), 'boom!', 'nice', 'thanks', '+1', with no request and nothing new for Lead.\",\n  banter_between_others:\n    \"Chat between the humans, or between other people and other bots, that is not aimed at Lead.\",\n  not_addressed_to_lead:\n    \"Addressed to a specific other person or another assistant, or an FYI that needs no answer from Lead.\",\n  other: \"None of the above, or unclear.\",\n} as const;\n\nexport type Reason = keyof typeof REASONS;\nconst SKIP_REASONS: ReadonlySet<string> = new Set([\n  \"reaction_only\",\n  \"banter_between_others\",\n  \"not_addressed_to_lead\",\n]);\n\nconst cfgOf = (raw: unknown): Cfg => {\n  const parsed = config.safeParse(raw ?? {});\n  return parsed.success ? parsed.data : config.parse({});\n};\n\n// kv keys accept [a-zA-Z0-9._:/%-]\nconst safeKey = (raw: string | undefined | null): string =>\n  (raw && raw.length > 0 ? raw : \"unknown\").replace(/[^a-zA-Z0-9._:-]/g, \"_\").slice(0, 120);\n\nconst escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n\n/**\n * Locate the engine's follow-up header (src/slack/thread-buffer.ts): at the start of the\n * description, or right after the closing `</thread_context>`. Thread context quotes old\n * messages verbatim, so a header (or a `</thread_context>`) quoted inside it is skipped.\n */\nconst findHeader = (description: string): { index: number; end: number } | null => {\n  for (const m of description.matchAll(HEADER_LINE_RE)) {\n    const index = m.index! + (m[0].startsWith(\"\\n\") ? 1 : 0);\n    const before = description.slice(0, index);\n    const open = before.indexOf(CTX_OPEN);\n    if (open < 0 || before.trimEnd().endsWith(CTX_CLOSE)) {\n      return { index, end: m.index! + m[0].length };\n    }\n  }\n  return null;\n};\n\n/**\n * Split a buffered follow-up description into thread context and new messages, or null\n * when the description is not a buffered follow-up. Only `messages` is new text.\n */\nexport const parseFollowUp = (\n  description: string,\n): { context: string[]; messages: string[] } | null => {\n  const header = findHeader(description);\n  if (!header) return null;\n  const before = description.slice(0, header.index).trimEnd();\n  const open = before.indexOf(CTX_OPEN);\n  const context =\n    open >= 0\n      ? before\n          .slice(open + CTX_OPEN.length, before.length - CTX_CLOSE.length)\n          .split(/\\n(?=<@[A-Z0-9]+[|>]|\\[Agent\\]:)/)\n          .map((m) => m.trim())\n          .filter(Boolean)\n      : [];\n  const messages = description\n    .slice(header.end)\n    .split(\"\\n---\\n\")\n    .map((m) => m.trim())\n    .filter(Boolean);\n  return { context, messages };\n};\n\n/** True when the new text addresses Lead with an @mention. */\nexport const mentionsLead = (text: string, aliases: readonly string[]): boolean => {\n  // The buffer rewrites a mention of the swarm's own bot to `<@U…> (that's you)`.\n  if (/<@[A-Z0-9]+>\\s*\\(that's you\\)/.test(text)) return true;\n  const names = aliases\n    .map((a) => a.trim())\n    .filter(Boolean)\n    .map(escapeRe);\n  if (names.length === 0) return false;\n  const alt = names.join(\"|\");\n  return (\n    new RegExp(`(^|[^\\\\w@])@(${alt})\\\\b`, \"i\").test(text) ||\n    new RegExp(`<@[A-Z0-9]+\\\\|(${alt})>`, \"i\").test(text)\n  );\n};\n\nconst secretCache = new Map<string, { value: string; at: number }>();\nconst KEY_TTL_MS = 5 * 60 * 1000;\nconst usable = (v: string): boolean => Boolean(v) && !v.startsWith(\"[REDACTED\");\nconst envOf = (name: string): string => String(process.env[name] ?? \"\");\n\n/**\n * Resolve a secret: explicit value, then the API process env. The API process loads\n * global swarm_config rows into process.env at boot and on config reload.\n * ctx.swarm.config_get cannot serve it: the SDK scrubs secrets to \"[REDACTED:<name>]\".\n */\nconst secret = (name: string, explicit?: string): string => {\n  const cached = secretCache.get(name);\n  if (cached && Date.now() - cached.at < KEY_TTL_MS) return cached.value;\n  const value = [String(explicit ?? \"\"), envOf(name)].find(usable) ?? \"\";\n  if (usable(value)) secretCache.set(name, { value, at: Date.now() });\n  return value;\n};\n\n/** Test hook: forget cached secrets. */\nexport const resetKeyCache = (): void => {\n  secretCache.clear();\n};\n\nexport type JevTransport = {\n  provider: \"typesafe\" | \"openrouter\";\n  endpoint: string;\n  key: string;\n  model: string;\n};\n\n/**\n * Pick the Jev transport. `auto` prefers TypeSafe and falls back to OpenRouter.\n * Throws when the chosen provider has no usable key; the handler fails open.\n */\nexport const resolveTransport = (cfg: Cfg): JevTransport => {\n  const typesafe = (): JevTransport | null => {\n    const key = secret(\"TYPESAFE_API_KEY\", cfg.apiKey);\n    return usable(key)\n      ? { provider: \"typesafe\", endpoint: TYPESAFE_ENDPOINT, key, model: cfg.model }\n      : null;\n  };\n  const openrouter = (): JevTransport | null => {\n    const key = secret(\"OPENROUTER_API_KEY\");\n    return usable(key)\n      ? { provider: \"openrouter\", endpoint: OPENROUTER_ENDPOINT, key, model: cfg.openrouterModel }\n      : null;\n  };\n  const transport =\n    cfg.provider === \"typesafe\"\n      ? typesafe()\n      : cfg.provider === \"openrouter\"\n        ? openrouter()\n        : (typesafe() ?? openrouter());\n  if (transport) return transport;\n  throw new Error(\n    cfg.provider === \"typesafe\"\n      ? \"no TYPESAFE_API_KEY\"\n      : cfg.provider === \"openrouter\"\n        ? \"no OPENROUTER_API_KEY\"\n        : \"no TYPESAFE_API_KEY or OPENROUTER_API_KEY\",\n  );\n};\n\nconst SLACK_API = \"https://slack.com/api\";\n// The engine's acceptance reactions (src/slack/reaction-shortcode.ts), by config key.\nconst ACCEPTANCE_REACTIONS: ReadonlyArray<[string, string]> = [\n  [\"SLACK_REACTION_ACCEPTED\", \"eyes\"],\n  [\"SLACK_REACTION_BUFFERED\", \"heavy_plus_sign\"],\n  [\"SLACK_REACTION_NOW\", \"zap\"],\n  [\"SLACK_REACTION_STEERED\", \"speech_balloon\"],\n];\nconst SHORTCODE_RE = /^[a-z0-9_+'-]+(::skin-tone-[2-6])?$/;\nconst shortcode = (raw: string): string | null => {\n  const s = raw.trim().replace(/^:/, \"\").replace(/:$/, \"\").toLowerCase();\n  return s && SHORTCODE_RE.test(s) ? s : null;\n};\n\n/** The acceptance reactions the engine may have put on the message, deduplicated. */\nexport const acceptanceReactions = (): string[] => [\n  ...new Set(ACCEPTANCE_REACTIONS.map(([key, fallback]) => shortcode(envOf(key)) ?? fallback)),\n];\n\nconst slackCall = async (\n  method: string,\n  token: string,\n  body: Record<string, string>,\n  timeoutMs: number,\n): Promise<{ ok: boolean; error?: string }> => {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), timeoutMs);\n  try {\n    const res = await fetch(`${SLACK_API}/${method}`, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json; charset=utf-8\",\n        Authorization: `Bearer ${token}`,\n      },\n      body: JSON.stringify(body),\n      signal: controller.signal,\n    });\n    if (!res.ok) return { ok: false, error: `http_${res.status}` };\n    const data = (await res.json()) as { ok?: boolean; error?: string };\n    return { ok: data?.ok === true, error: data?.error };\n  } finally {\n    clearTimeout(timer);\n  }\n};\n\nexport type MuteResult = { removed: string[]; added: boolean; errors: string[] };\n\n/**\n * Replace the bot's acceptance reaction(s) on one message with `name`, or only\n * remove them when `name` is \"\". `reactions.remove` only removes the calling\n * bot's own reaction, so a human's :eyes: stays. Never throws: every failure\n * lands in `errors`.\n */\nexport const muteMessage = async (\n  token: string,\n  channel: string,\n  timestamp: string,\n  name: string,\n  timeoutMs: number,\n): Promise<MuteResult> => {\n  const result: MuteResult = { removed: [], added: false, errors: [] };\n  const call = (method: string, reaction: string) =>\n    slackCall(method, token, { channel, timestamp, name: reaction }, timeoutMs).catch(\n      (err): { ok: boolean; error?: string } => ({ ok: false, error: String(err).slice(0, 120) }),\n    );\n  const removals = acceptanceReactions().filter((r) => r !== name);\n  const removed = await Promise.all(removals.map((r) => call(\"reactions.remove\", r)));\n  removed.forEach((res, i) => {\n    const reaction = removals[i]!;\n    if (res.ok) result.removed.push(reaction);\n    else if (res.error !== \"no_reaction\" && res.error !== \"invalid_name\")\n      result.errors.push(`remove ${reaction}: ${res.error ?? \"unknown\"}`);\n  });\n  if (!name) return result;\n  const added = await call(\"reactions.add\", name);\n  if (added.ok || added.error === \"already_reacted\") result.added = true;\n  else result.errors.push(`add ${name}: ${added.error ?? \"unknown\"}`);\n  return result;\n};\n\n// In-flight mutes, so tests can await the work the handler does not wait for.\nconst pendingMutes = new Set<Promise<void>>();\n/** Test hook: wait for every in-flight mute. */\nexport const settleMutes = async (): Promise<void> => {\n  await Promise.allSettled([...pendingMutes]);\n};\n\nexport type JevVerdict = {\n  reason: string;\n  confidence: number | null;\n  probabilities: Record<string, number> | null;\n  latencyMs: number;\n};\n\n/**\n * One Jev call: classify the newest message into a reason. Throws on any failure.\n * TypeSafe and OpenRouter share the request body and the `answers` response shape.\n */\nexport const askJev = async (\n  input: {\n    messages: string[];\n    context: string[];\n    sender: string;\n    leadNames: readonly string[];\n  },\n  transport: JevTransport,\n  cfg: Cfg,\n  outer?: AbortSignal,\n): Promise<JevVerdict> => {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), Math.min(cfg.timeoutMs, MAX_TIMEOUT_MS));\n  const onOuterAbort = () => controller.abort();\n  outer?.addEventListener(\"abort\", onOuterAbort);\n  const t0 = Date.now();\n  try {\n    const res = await fetch(transport.endpoint, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n        Authorization: `Bearer ${transport.key}`,\n      },\n      body: JSON.stringify({\n        state: {\n          role: \"Decide whether Lead, the coordinating AI agent of a team's agent swarm, should answer a new Slack message in a thread it takes part in. Lead is woken by every message in the thread, including ones not meant for it. Answering noise wastes everyone's time; missing a real ask is worse.\",\n          lead_names: input.leadNames,\n          recent_thread_messages: input.context,\n          new_message: input.messages.join(\"\\n---\\n\"),\n          new_message_sender: input.sender,\n        },\n        model: transport.model,\n        questions: {\n          reason: {\n            type: \"choice\",\n            instructions:\n              \"Which label best describes new_message from Lead's point of view? Use recent_thread_messages to tell who it is talking to. Lines starting with [Agent] are swarm bots.\",\n            criteria: REASONS,\n          },\n        },\n      }),\n      signal: controller.signal,\n    });\n    if (!res.ok) throw new Error(`${transport.provider} ${res.status}`);\n    const body = (await res.json()) as {\n      answers?: { reason?: { choice?: unknown; confidence?: unknown; probabilities?: unknown } };\n    } | null;\n    const answer = body?.answers?.reason;\n    const reason = typeof answer?.choice === \"string\" ? answer.choice : \"\";\n    if (!(reason in REASONS)) throw new Error(`unexpected choice: ${String(reason).slice(0, 60)}`);\n    const confidence = typeof answer?.confidence === \"number\" ? answer.confidence : null;\n    const probabilities =\n      answer?.probabilities && typeof answer.probabilities === \"object\"\n        ? (answer.probabilities as Record<string, number>)\n        : null;\n    return { reason, confidence, probabilities, latencyMs: Date.now() - t0 };\n  } finally {\n    clearTimeout(timer);\n    outer?.removeEventListener(\"abort\", onOuterAbort);\n  }\n};\n\n/** Probability that the message needs no reply: the summed mass of the skip labels. */\nexport const skipProbability = (verdict: JevVerdict): number | null => {\n  if (verdict.probabilities) {\n    let sum = 0;\n    for (const [label, p] of Object.entries(verdict.probabilities)) {\n      if (SKIP_REASONS.has(label) && typeof p === \"number\") sum += p;\n    }\n    return sum;\n  }\n  return verdict.confidence;\n};\n\n/** Map a Jev verdict to the typed decision. An unsure skip verdict replies. */\nexport const decide = (\n  verdict: JevVerdict,\n  minConfidence: number,\n): { reply: boolean; reason: Reason; skipP: number | null; lowConfidence: boolean } => {\n  const reason = verdict.reason as Reason;\n  const skipP = skipProbability(verdict);\n  if (!SKIP_REASONS.has(reason)) return { reply: true, reason, skipP, lowConfidence: false };\n  const lowConfidence = skipP !== null && skipP < minConfidence;\n  return { reply: lowConfidence, reason, skipP, lowConfidence };\n};\n\nconst record = async (\n  swarm: Swarm,\n  entry: Record<string, unknown>,\n  counters: string[],\n  prefix: \"d\" | \"m\" = \"d\",\n) => {\n  const at = new Date().toISOString();\n  const thread = safeKey(`${entry.channelId ?? \"\"}_${entry.threadTs ?? \"\"}`);\n  const value = { at, ...entry };\n  await Promise.allSettled([\n    swarm.kv_set({ namespace: NS, key: `${prefix}:${Date.now()}:${thread}`, value }),\n    // `last` stays the latest decision; mute outcomes only get their own row.\n    ...(prefix === \"d\" ? [swarm.kv_set({ namespace: NS, key: \"last\", value })] : []),\n    ...counters.map((c) => swarm.kv_incr({ namespace: NS, key: safeKey(c) })),\n  ]);\n};\n\n/** Mute the triggering message and log the outcome. Never throws. */\nconst muteTrigger = async (\n  swarm: Swarm,\n  cfg: Cfg,\n  base: Record<string, unknown>,\n): Promise<void> => {\n  try {\n    const channel = String(base.channelId ?? \"\");\n    const ts = String(base.triggerTs ?? \"\");\n    if (!channel || !ts) throw new Error(\"no slackChannelId or slackTriggerMessageTs\");\n    const token = secret(\"SLACK_BOT_TOKEN\");\n    if (!usable(token)) throw new Error(\"no SLACK_BOT_TOKEN\");\n    const result = await muteMessage(token, channel, ts, cfg.muteReaction, cfg.slackTimeoutMs);\n    // \"\" adds nothing: success is clearing the acceptance reaction(s).\n    const done = cfg.muteReaction ? \"muted\" : \"unreacted\";\n    const ok = (result.added || !cfg.muteReaction) && result.errors.length === 0;\n    const action = ok ? done : \"mute-error\";\n    await record(swarm, { ...base, action, ...result }, [action], \"m\");\n  } catch (err) {\n    await record(\n      swarm,\n      { ...base, action: \"mute-error\", errors: [String(err).slice(0, 300)] },\n      [\"mute-error\"],\n      \"m\",\n    ).catch(() => {});\n  }\n};\n\nconst extension: SwarmExtension = (api) => {\n  api.on(\"pre.task.create\", async (event, ctx) => {\n    if (event.origin !== \"slack\") return;\n    // Only buffered follow-ups. A direct @mention task never carries the header outside\n    // its thread context.\n    const followUp = parseFollowUp(event.description);\n    if (!followUp) return;\n\n    const cfg = cfgOf(ctx.config);\n    if (cfg.mode === \"off\") return;\n\n    const opts = event.options;\n    const base = {\n      mode: cfg.mode,\n      channelId: opts.slackChannelId,\n      threadTs: opts.slackThreadTs,\n      triggerTs: opts.slackTriggerMessageTs,\n      senderSlackId: opts.slackUserId,\n    };\n\n    try {\n      // A draft follow-up carries downloaded files: always let Lead see them.\n      if (opts.status === \"draft\") {\n        await record(ctx.swarm, { ...base, action: \"pass\", reason: \"has_files\" }, [\n          \"total\",\n          \"files\",\n        ]);\n        return;\n      }\n\n      // The mention check reads only the new messages, never the thread context.\n      const { context, messages } = followUp;\n      const preview = messages.join(\" | \").slice(0, 300);\n\n      if (messages.some((m) => mentionsLead(m, cfg.leadAliases))) {\n        await record(ctx.swarm, { ...base, action: \"pass\", reason: \"mention\", preview }, [\n          \"total\",\n          \"mention\",\n        ]);\n        return;\n      }\n\n      const transport = resolveTransport(cfg);\n\n      const sender =\n        opts.slackUserId && cfg.botSlackUserIds.includes(opts.slackUserId)\n          ? \"bot\"\n          : opts.requestedByUserId\n            ? \"human (known teammate)\"\n            : \"unknown (not a known teammate; may be a bot or an external person)\";\n\n      const verdict = await askJev(\n        {\n          messages,\n          context: context.slice(-cfg.contextMessages).map((m) => m.slice(0, 500)),\n          sender,\n          leadNames: cfg.leadAliases,\n        },\n        transport,\n        cfg,\n        ctx.signal,\n      );\n      const decision = decide(verdict, cfg.minConfidence);\n\n      const skip = !decision.reply;\n      const action = skip ? (cfg.mode === \"enforce\" ? \"skipped\" : \"shadow-skip\") : \"pass\";\n      await record(\n        ctx.swarm,\n        {\n          ...base,\n          action,\n          reply: decision.reply,\n          reason: decision.reason,\n          confidence: verdict.confidence,\n          skipP: decision.skipP,\n          lowConfidence: decision.lowConfidence,\n          latencyMs: verdict.latencyMs,\n          provider: transport.provider,\n          sender,\n          preview,\n        },\n        [\"total\", skip ? action : \"reply\", `reason:${decision.reason}`],\n      );\n\n      if (skip && cfg.mode === \"enforce\") {\n        // Not awaited: the block must return inside the dispatcher's 5 s budget\n        // whatever Slack does, and a failed reaction never changes the drop.\n        // An empty (or invalid) muteReaction still clears the acceptance reaction(s).\n        const muteReaction = shortcode(cfg.muteReaction) ?? \"\";\n        const pending = muteTrigger(ctx.swarm, { ...cfg, muteReaction }, base);\n        pendingMutes.add(pending);\n        void pending.finally(() => pendingMutes.delete(pending));\n        return block(\n          `slack-reply-gate: no reply needed (${decision.reason}${decision.skipP !== null ? `, p(skip) ${decision.skipP.toFixed(2)}` : \"\"})`,\n        );\n      }\n      return;\n    } catch (err) {\n      // Fail open, always.\n      try {\n        await record(\n          ctx.swarm,\n          { ...base, action: \"fail-open\", error: String(err).slice(0, 300) },\n          [\"total\", \"error\"],\n        );\n      } catch {\n        /* ignore */\n      }\n      ctx.log.warn(\"slack-reply-gate: failing open\", { error: String(err) });\n      return;\n    }\n  });\n};\n\nexport default extension;\n"
+    },
+    "readme": "# slack-reply-gate\n\nLead is woken by every human message in a Slack thread the swarm takes part in, including \"lol\", an emoji, or two people chatting with each other. This extension asks Jev, [TypeSafe](https://typesafe.ai)'s decision model, whether Lead should answer a new thread message, and drops the wake-up when it should not.\n\nInstall config:\n\n```json\n{ \"mode\": \"shadow\" }\n```\n\nStart in `shadow`, read the decisions in KV for a few days, then switch to `enforce`.\n\n## Modes\n\n| `mode` | Effect |\n|---|---|\n| `off` | Never evaluates. |\n| `shadow` (default) | Asks Jev and records the verdict. Never blocks. |\n| `enforce` | Asks Jev, records the verdict, and blocks the Lead task when the answer is no. The message gets :mute: instead: no Lead task, no reply, no outcome card. |\n\n## What it gates\n\nHook: `pre.task.create`, for tasks with origin `slack` whose description carries the thread buffer's header `[Thread follow-up — N message(s) buffered]`. Those are the non-mention thread replies that `src/slack/thread-buffer.ts` batches into a Lead task. A direct @mention of the bot creates a task without that header and is never gated.\n\nThe header counts only at the start of the description or right after the closing `</thread_context>`. Thread context quotes old messages verbatim, and an older Lead reply can quote the header itself, so a header inside the context is ignored. Only the text after the real header is treated as new.\n\n## Decision\n\n1. A follow-up with downloaded files (status `draft`) passes without a Jev call.\n2. **@mention pass-through.** A new message that @mentions Lead passes without a Jev call. A mention is the bot mention the engine rewrites to `<@U…> (that's you)`, a resolved `<@U…|lead>`, or a literal `@lead` (any name in `leadAliases`). Only the new messages are scanned, never the thread context, so an old mention earlier in the thread does not pass later banter.\n3. Otherwise one Jev call (one `choice` question, see [Jev transport](#jev-transport)) with the new message(s), the sender kind, and the last `contextMessages` thread messages. Labels: `direct_ask`, `followup_to_lead`, `instruction_to_lead`, `reaction_only`, `banter_between_others`, `not_addressed_to_lead`, `other`.\n4. The answer is no only when the top label is `reaction_only`, `banter_between_others`, or `not_addressed_to_lead`, and the summed probability of those three labels is at least `minConfidence`. A split between two skip labels is still a skip. An unsure verdict replies.\n\nSeveral buffered messages are judged together. One mention in any of them passes the batch.\n\n## Jev transport\n\nJev is reachable two ways. Both take the same request and return the same answer, so the decision is identical whichever one runs.\n\n| `provider` | Endpoint | Key | Model |\n|---|---|---|---|\n| `typesafe` | `POST https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY` (or `apiKey`) | `model`, default `jev-latest` |\n| `openrouter` | `POST https://openrouter.ai/api/alpha/decisions` | `OPENROUTER_API_KEY` | `openrouterModel`, default `typesafe/jev-1.13` |\n| `auto` (default) | TypeSafe when its key is set, else OpenRouter | | |\n\nUnder `auto`, `TYPESAFE_API_KEY` wins when both keys are set. With neither key, every message fails open and the KV row names both secrets. Each decision row records the `provider` that answered.\n\n## Fail open\n\nEvery error lets the task through: a missing key, a TypeSafe HTTP error, a network error, a timeout, a malformed answer, or an unknown label. The handler never throws, so an outage cannot auto-disable the extension. Each failure is recorded as `fail-open` in KV and logged as a warning.\n\n## :mute: on drop (enforce)\n\nNo swarm tool or extension `ctx` method adds a Slack reaction, so the hook calls the Slack Web API with the bot token. It needs the `reactions:write` scope, which the Slack app already uses for its acceptance reactions.\n\n1. `reactions.remove` for each acceptance reaction the engine may have put on the triggering message: `eyes`, `heavy_plus_sign`, `zap`, `speech_balloon`, or their `SLACK_REACTION_ACCEPTED`, `SLACK_REACTION_BUFFERED`, `SLACK_REACTION_NOW`, and `SLACK_REACTION_STEERED` overrides. Slack only removes the bot's own reaction, so a human's :eyes: stays.\n2. `reactions.add` with `muteReaction` (default `mute`). `already_reacted` counts as success. Skipped when `muteReaction` is `\"\"`.\n\nThe block returns first and the Slack calls run after it. A slow or failing Slack call never delays the drop or turns it back into a task. Set `muteReaction` to `\"\"` for a true no-op: step 1 still clears the bot's acceptance reaction(s), and nothing is added.\n\n## Config\n\n| Key | Default | Notes |\n|---|---|---|\n| `mode` | `shadow` | `off`, `shadow`, or `enforce` |\n| `timeoutMs` | `3000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |\n| `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |\n| `model` | `jev-latest` | Jev model on TypeSafe |\n| `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |\n| `minConfidence` | `0.55` | Minimum summed skip probability to skip |\n| `contextMessages` | `6` | Thread messages sent to Jev, 0 to 20 |\n| `leadAliases` | `[\"lead\"]` | A literal `@alias` in a new message counts as a mention |\n| `botSlackUserIds` | `[]` | Slack user ids labelled `bot` as the sender for Jev |\n| `apiKey` | unset | Explicit TypeSafe key. Prefer the `TYPESAFE_API_KEY` secret below |\n| `muteReaction` | `mute` | Reaction for a dropped message; `\"\"` only removes the acceptance reaction(s) |\n| `slackTimeoutMs` | `5000` | Timeout per Slack call |\n\n## Required secrets\n\nAll are read from the API process environment at call time. Set them as global `swarm_config` secrets: the API process loads global rows into `process.env` at boot and on config reload.\n\n- `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`: one is required for any evaluation. Under `auto`, TypeSafe wins when both are set. Without either, every message fails open.\n- `SLACK_BOT_TOKEN`: the Slack app's bot token. A swarm with Slack connected already has it. Without it, `enforce` still drops the message but cannot touch its reactions, and logs a `mute-error`.\n\nNo key is written to config, KV, logs, or a description.\n\n## KV namespace `ext:slack-reply-gate`\n\n- `d:<epochMs>:<channel>_<threadTs>`: one row per decision, with `action` (`pass`, `shadow-skip`, `skipped`, `fail-open`), `provider`, `reason`, `confidence`, `skipP`, `latencyMs`, `sender`, and a 300-character `preview`.\n- `m:<epochMs>:<channel>_<threadTs>`: one row per mute attempt, with `action` (`muted`, `unreacted` when `muteReaction` is `\"\"`, `mute-error`), `removed`, `added`, and `errors`.\n- `last`: the latest decision. Mute rows never overwrite it.\n- Counters: `total`, `mention`, `files`, `reply`, `shadow-skip`, `skipped`, `error`, `muted`, `unreacted`, `mute-error`, and `reason:<label>`.\n\n## Known limits\n\n- When Lead already has an active task in the thread, the buffer steers that task instead of creating one, so `pre.task.create` does not fire and the gate does not run.\n- A blocked flush makes the thread buffer log a `TaskCreationBlockedError`. Nothing is lost: the next follow-up's `<thread_context>` carries the earlier messages.\n- A flush of several messages mutes only the triggering (last) message. The others keep their acceptance reaction.\n"
+  },
   "task-digest": {
     "manifestFile": "manifest.yaml",
     "manifest": {

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,