@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/context/budget.mjs

@@ -0,0 +1,327 @@
+/**
+ * lib/context/budget.mjs — the declared token budget for an inbound prompt.
+ *
+ * Every bound in this repo up to now has been a row count or a `.slice(n)` char
+ * clamp (design §5.4, R8). Both are proxies: a row count cannot tell a one-word
+ * turn from a pasted stack trace, and a char clamp spends the allowance on
+ * whichever section happens to be assembled first. So the prompt that reaches
+ * the model is whatever the assembly order happened to produce, and the parts
+ * that fall off do so SILENTLY — the model reads a thread with a hole in it and
+ * cannot tell the hole from a conversation that never happened.
+ *
+ * This module states the budget instead of discovering it:
+ *
+ *   1. a budget PER TIER (§5.1) — an Answer gets 6k input tokens, Work 12k,
+ *      Plan 20k. Context rot is measured: accuracy falls with input length well
+ *      before the window limit, so a bigger prompt is not a better one.
+ *   2. sections filled in PRIORITY order ({@link SECTION_ORDER}) — the trigger
+ *      is the thing being answered and is never dropped whole; the backlog is
+ *      the first thing to go.
+ *   3. every drop VISIBLE — `… 14 earlier turns not shown`, in the prompt, where
+ *      the model reads it. A section that did not fit at all still leaves a line
+ *      saying so.
+ *
+ * PURE. No clock, no env, no fs, no network: tokens are estimated from
+ * character length at {@link CHARS_PER_TOKEN}, the same ratio
+ * `context-compiler.mjs` already uses, so the two agree. A caller that has a
+ * real tokeniser passes `estimate` and this module uses it instead.
+ *
+ * Char clamps stay where they are as a second belt — this is the first one.
+ *
+ * @module lib/context/budget
+ */
+
+"use strict";
+
+/** Characters per token. The estimate `scripts/daemon/context-compiler.mjs` uses. */
+export const CHARS_PER_TOKEN = 4;
+
+/**
+ * Input-token budget per reply tier (design §5.4). A tier is the ack/effort
+ * tier from `lib/assurance/tier.mjs` — answer | work | plan.
+ */
+export const TIER_BUDGETS = Object.freeze({
+  answer: 6000,
+  work: 12000,
+  plan: 20000,
+});
+
+/**
+ * FILL priority. Earlier wins the budget; later is dropped first.
+ *
+ *   trigger  the message being answered — without it there is nothing to answer
+ *   thread   the conversation it sits in
+ *   entity   the anchored artifact: the task card, the doc body, the decision
+ *   digest   the distilled record of this thread
+ *   memory   recalled facts from elsewhere
+ *   backlog  what else is open — useful, never load-bearing
+ */
+export const FILL_PRIORITY = Object.freeze([
+  "trigger",
+  "thread",
+  "entity",
+  "digest",
+  "memory",
+  "backlog",
+]);
+
+/**
+ * RENDER order — a DIFFERENT question, and conflating the two costs the cache.
+ *
+ * Fill priority asks "who wins the budget"; the trigger wins it, because a
+ * prompt without the message being answered is not a smaller prompt but a
+ * broken one. Render order asks "what byte comes first", and design §4 is
+ * explicit about the consequence: "any byte change before a breakpoint
+ * invalidates everything after it". Rendering the trigger first — the ONE
+ * section that is different on every single inbound — gives the block a
+ * zero-length stable prefix, so WP-4's `cache_control` breakpoint would sit
+ * after volatile content and every read would be a silent miss. Prompt caching
+ * is the highest-ROI latency lever in the research pass; this is what it needs.
+ *
+ * So: stable first, volatile last, trigger last of all. `thread` sits second to
+ * last because it is append-only and rendered oldest-first, which makes its own
+ * prefix stable between turns even as it grows.
+ */
+export const RENDER_ORDER = Object.freeze([
+  "entity",
+  "digest",
+  "backlog",
+  "memory",
+  "thread",
+  "trigger",
+]);
+
+/**
+ * @deprecated Read {@link FILL_PRIORITY} or {@link RENDER_ORDER} by name — the
+ * whole point of the split is that "the section order" is two different orders.
+ * Kept as an alias so an existing importer does not silently get the wrong one.
+ */
+export const SECTION_ORDER = FILL_PRIORITY;
+
+/** Sections that must render SOMETHING rather than be dropped whole. */
+const NEVER_DROPPED_WHOLE = new Set(["trigger"]);
+
+/** A blank-safe string. */
+function s(v) {
+  return v == null ? "" : String(v);
+}
+
+/** The declared budget for a tier; an unknown tier takes the middle one. */
+export function budgetFor(tier) {
+  const key = s(tier).toLowerCase();
+  return Object.prototype.hasOwnProperty.call(TIER_BUDGETS, key) ? TIER_BUDGETS[key] : TIER_BUDGETS.work;
+}
+
+/** Estimated tokens for a string, rounded up so a partial token still costs one. */
+export function estimateTokens(text, charsPerToken = CHARS_PER_TOKEN) {
+  const t = s(text);
+  if (!t) return 0;
+  const per = Number.isFinite(charsPerToken) && charsPerToken > 0 ? charsPerToken : CHARS_PER_TOKEN;
+  return Math.ceil(t.length / per);
+}
+
+/** Where a section sorts in a declared order; unknown names sort last, stably. */
+function rankIn(order, name) {
+  const i = order.indexOf(name);
+  return i === -1 ? order.length : i;
+}
+
+/** `1 earlier turn` / `14 earlier turns` — the count is the point, so it leads. */
+function turnNote(n) {
+  return `… ${n} earlier turn${n === 1 ? "" : "s"} not shown`;
+}
+
+/** `… 1,204 characters not shown`. */
+function charNote(n) {
+  return `… ${n.toLocaleString("en-US")} character${n === 1 ? "" : "s"} not shown`;
+}
+
+/**
+ * @typedef {Object} SectionInput
+ * @property {string} name             one of {@link SECTION_ORDER}, or any name (sorts last)
+ * @property {string} [title]          heading rendered above the body
+ * @property {string} [text]           a whole-text section
+ * @property {string[]} [turns]        a turn-structured section, OLDEST FIRST
+ */
+
+/**
+ * @typedef {Object} FittedSection
+ * @property {string} name
+ * @property {boolean} included        false == dropped whole (still rendered as a note)
+ * @property {string} text             what was kept, drop note included
+ * @property {number} keptTurns
+ * @property {number} droppedTurns
+ * @property {number} droppedChars
+ * @property {number} tokens
+ */
+
+/**
+ * Fit the sections into the tier's budget.
+ *
+ * Turn-structured sections spend the budget from the NEWEST turn backwards —
+ * the turns nearest the message being answered are the ones that explain it
+ * (the same rule `lib/org/inbound/hydrate.mjs#renderThread` follows, and for the
+ * same reason: clipping the joined string keeps the oldest turns and drops the
+ * newest, which is the exact inverse of what context is for).
+ *
+ * NEVER THROWS. A malformed section is skipped; a missing budget takes the
+ * tier's. The prompt path must not be able to fail on its own budgeting.
+ *
+ * @param {Object} o
+ * @param {SectionInput[]} o.sections
+ * @param {string} [o.tier]                    answer | work | plan
+ * @param {number} [o.budgetTokens]            override the tier's budget
+ * @param {number} [o.charsPerToken]
+ * @param {(text:string)=>number} [o.estimate] a real tokeniser, when the caller has one
+ * @returns {{tier:string, budgetTokens:number, usedTokens:number,
+ *           sections:FittedSection[], drops:Array<object>, text:string}}
+ */
+export function fitSections(o = {}) {
+  const tier = s(o.tier).toLowerCase() || "work";
+  const budgetTokens = Number.isFinite(o.budgetTokens) && o.budgetTokens > 0
+    ? Math.floor(o.budgetTokens)
+    : budgetFor(tier);
+  const charsPerToken = Number.isFinite(o.charsPerToken) && o.charsPerToken > 0 ? o.charsPerToken : CHARS_PER_TOKEN;
+  const tokensOf = typeof o.estimate === "function" ? o.estimate : (t) => estimateTokens(t, charsPerToken);
+
+  const input = (Array.isArray(o.sections) ? o.sections : [])
+    .map((sec, i) => ({ sec, i }))
+    .filter(({ sec }) => sec && typeof sec === "object" && s(sec.name))
+    .sort((a, b) => rankIn(FILL_PRIORITY, s(a.sec.name)) - rankIn(FILL_PRIORITY, s(b.sec.name)) || a.i - b.i);
+
+  const out = [];
+  const drops = [];
+  let used = 0;
+
+  for (const { sec } of input) {
+    const name = s(sec.name);
+    const title = s(sec.title);
+    const headCost = title ? tokensOf(`${title}\n`) : 0;
+    const room = budgetTokens - used - headCost;
+
+    const fitted = Array.isArray(sec.turns)
+      ? fitTurns(sec.turns, room, tokensOf)
+      : fitText(s(sec.text), room, tokensOf, charsPerToken);
+
+    // A section with no content at all is simply absent — there is nothing to
+    // report the loss of, and a note about an empty section is noise.
+    if (fitted.empty) continue;
+
+    if (!fitted.body && !NEVER_DROPPED_WHOLE.has(name)) {
+      // Dropped whole. It still shows: an absence the reader cannot see is the
+      // failure this module exists to prevent.
+      const note = `… ${name} not shown`;
+      const cost = tokensOf(note);
+      if (used + cost <= budgetTokens) {
+        out.push({ name, included: false, text: note, keptTurns: 0, droppedTurns: fitted.droppedTurns, droppedChars: fitted.droppedChars, tokens: cost });
+        used += cost;
+      } else {
+        out.push({ name, included: false, text: "", keptTurns: 0, droppedTurns: fitted.droppedTurns, droppedChars: fitted.droppedChars, tokens: 0 });
+      }
+      drops.push({ section: name, turns: fitted.droppedTurns, chars: fitted.droppedChars, note });
+      continue;
+    }
+
+    // The trigger is the thing being answered: it always renders something,
+    // even when the budget cannot pay for it. A prompt with no trigger is not a
+    // smaller prompt, it is a broken one.
+    let body = fitted.body;
+    if (!body && NEVER_DROPPED_WHOLE.has(name)) {
+      const minChars = Math.max(1, Math.floor(Math.max(room, 1) * charsPerToken));
+      const whole = Array.isArray(sec.turns) ? sec.turns.filter(Boolean).map(s).join("\n") : s(sec.text);
+      body = whole.slice(0, minChars);
+      const lost = whole.length - body.length;
+      if (lost > 0) {
+        body += `\n${charNote(lost)}`;
+        drops.push({ section: name, turns: 0, chars: lost, note: charNote(lost) });
+      }
+    } else if (fitted.droppedTurns > 0) {
+      drops.push({ section: name, turns: fitted.droppedTurns, chars: 0, note: turnNote(fitted.droppedTurns) });
+    } else if (fitted.droppedChars > 0) {
+      drops.push({ section: name, turns: 0, chars: fitted.droppedChars, note: charNote(fitted.droppedChars) });
+    }
+
+    const text = title ? `${title}\n${body}` : body;
+    const cost = tokensOf(text);
+    out.push({
+      name,
+      included: true,
+      text,
+      keptTurns: fitted.keptTurns,
+      droppedTurns: fitted.droppedTurns,
+      droppedChars: fitted.droppedChars,
+      tokens: cost,
+    });
+    used += cost;
+  }
+
+  // Filled in priority order, RENDERED in cache order. The two are separate
+  // arrays for the reason RENDER_ORDER states, and this is the only place the
+  // difference is applied.
+  const rendered = out
+    .map((sec, i) => ({ sec, i }))
+    .sort((a, b) => rankIn(RENDER_ORDER, a.sec.name) - rankIn(RENDER_ORDER, b.sec.name) || a.i - b.i)
+    .map(({ sec }) => sec);
+
+  return {
+    tier,
+    budgetTokens,
+    usedTokens: used,
+    sections: rendered,
+    drops,
+    text: rendered.map((sec) => sec.text).filter(Boolean).join("\n\n"),
+  };
+}
+
+/** Keep the newest turns that fit; report the rest as a visible note. */
+function fitTurns(turns, room, tokensOf) {
+  const rows = (Array.isArray(turns) ? turns : []).filter((t) => s(t).trim()).map((t) => s(t));
+  if (rows.length === 0) return { empty: true, body: "", keptTurns: 0, droppedTurns: 0, droppedChars: 0 };
+  if (room <= 0) return { empty: false, body: "", keptTurns: 0, droppedTurns: rows.length, droppedChars: 0 };
+
+  const kept = [];
+  let used = 0;
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const cost = tokensOf(rows[i]) + (kept.length ? 1 : 0);
+    // The note itself has to fit, or the drop would be the silent kind.
+    const reserve = i > 0 ? tokensOf(turnNote(i)) + 1 : 0;
+    if (used + cost + reserve > room) break;
+    kept.unshift(rows[i]);
+    used += cost;
+  }
+  const dropped = rows.length - kept.length;
+  if (kept.length === 0) return { empty: false, body: "", keptTurns: 0, droppedTurns: dropped, droppedChars: 0 };
+  const body = dropped > 0 ? [turnNote(dropped), ...kept].join("\n") : kept.join("\n");
+  return { empty: false, body, keptTurns: kept.length, droppedTurns: dropped, droppedChars: 0 };
+}
+
+/** Keep the head that fits; report the tail as a visible note. */
+function fitText(text, room, tokensOf, charsPerToken) {
+  const t = s(text).trim();
+  if (!t) return { empty: true, body: "", keptTurns: 0, droppedTurns: 0, droppedChars: 0 };
+  if (room <= 0) return { empty: false, body: "", keptTurns: 0, droppedTurns: 0, droppedChars: t.length };
+  if (tokensOf(t) <= room) return { empty: false, body: t, keptTurns: 1, droppedTurns: 0, droppedChars: 0 };
+
+  // Reserve room for the note, then take the largest head that still fits.
+  let chars = Math.max(0, Math.floor(room * charsPerToken));
+  let head = t.slice(0, chars);
+  let note = charNote(t.length - head.length);
+  while (head.length > 0 && tokensOf(`${head}\n${note}`) > room) {
+    chars = Math.floor(chars * 0.8);
+    head = t.slice(0, chars);
+    note = charNote(t.length - head.length);
+  }
+  if (!head) return { empty: false, body: "", keptTurns: 0, droppedTurns: 0, droppedChars: t.length };
+  return { empty: false, body: `${head}\n${note}`, keptTurns: 1, droppedTurns: 0, droppedChars: t.length - head.length };
+}
+
+export default {
+  TIER_BUDGETS,
+  FILL_PRIORITY,
+  RENDER_ORDER,
+  SECTION_ORDER,
+  CHARS_PER_TOKEN,
+  budgetFor,
+  estimateTokens,
+  fitSections,
+};

package/lib/context/history-scope.mjs

@@ -0,0 +1,138 @@
+/**
+ * lib/context/history-scope.mjs — which interaction logs may be read for THIS
+ * reply.
+ *
+ * THE DEFECT THIS EXISTS TO CLOSE
+ *
+ * `scripts/daemon/responder.mjs#logInteraction` files every exchange under
+ * `memory/interactions/<service>/…`, and it files each one TWICE: once under the
+ * room (`<channelId>`) and once under the person (`dm-<sender-slug>`). The two
+ * readers — `prompt-builder.mjs` and `context-compiler.mjs` — then merged every
+ * candidate directory into one timestamp-sorted block headed "Recent
+ * conversation history with this sender".
+ *
+ * While that read was pinned to `…/slack/…` the merge was inert for every other
+ * service. Reading the item's own service (design §3 R12) makes it live, and
+ * Cohort is the one service where a person's DMs and the public rooms they post
+ * in share a namespace. So: Dana DMs the agent something private, later
+ * @-mentions the agent in a public channel, and the public room's prompt
+ * carries the DM sentence verbatim. That is design §5.5's resource-scope leak —
+ * "per-person facts may inform a reply but are NEVER quoted into a shared room"
+ * — arriving through the back door of a directory list.
+ *
+ * THE RULE, stated once so both readers and the writer cannot drift:
+ *
+ *   A per-person directory is readable only when the reply itself is going to
+ *   that person privately. In a shared room only the room's own log is read.
+ *   Unknown is not private: an item that does not positively say it is a DM is
+ *   treated as a room.
+ *
+ * PURE. Everything arrives on the argument; nothing is read from disk, the
+ * clock or the environment.
+ *
+ * @module lib/context/history-scope
+ */
+
+"use strict";
+
+/** A blank-safe string. */
+function s(v) {
+  return v == null ? "" : String(v);
+}
+
+/**
+ * Is this inbound item a private 1:1 (or small group DM) conversation?
+ *
+ * The signals, in the order they are trusted:
+ *   1. `is_dm` — set from Cohort's `channel_kind` (`lib/org/inbound/project.mjs`)
+ *      and from Slack's `channel_type` (`scripts/poller/utils.mjs`). A literal
+ *      `false` is a positive assertion of "room" and ends the question.
+ *   2. `channel_type` — Slack's own envelope field: `im` / `mpim`.
+ *   3. A Slack channel id beginning `D` — the convention the raw_ref parser in
+ *      `prompt-builder.mjs` already relies on.
+ *   4. A `dm/<name>` channel label, which is what the Telegram and Slack
+ *      adapters write for a private chat.
+ *
+ * Anything else is a room. That direction is deliberate and is the opposite of
+ * this module's neighbours: everywhere else in hydration an unknown degrades
+ * towards MORE context, because the cost is a thinner prompt. Here the cost of
+ * guessing wrong is one person's private sentence in a public channel, so
+ * unknown buys nothing.
+ *
+ * @param {object} item inbound item (`{service, is_dm, channel_type, channel_id, channel}`)
+ * @returns {boolean}
+ */
+export function isPrivateConversation(item) {
+  if (!item || typeof item !== "object") return false;
+  if (item.is_dm === true) return true;
+  if (item.is_dm === false) return false;
+
+  const type = s(item.channel_type).toLowerCase();
+  if (type === "im" || type === "mpim") return true;
+  if (type === "channel" || type === "group") return false;
+
+  // Slack's own id convention. `service` defaults to slack here for the same
+  // reason both readers write `String(item.service || "slack")` — an item that
+  // predates the per-service split carries no service field, and a `D…` id on
+  // such an item is a Slack DM.
+  const service = s(item.service) || "slack";
+  const channelId = s(item.channel_id || item.channelId);
+  if (service === "slack" && /^D[A-Z0-9]+$/.test(channelId)) return true;
+
+  if (/^dm\//i.test(s(item.channel))) return true;
+
+  return false;
+}
+
+/**
+ * The interaction-log directory NAMES this reply may read, relative to
+ * `memory/interactions/<service>/`. Callers join them onto the service root.
+ *
+ * Ordered room-first so a merged read still prefers the room's own record.
+ * Slack keeps its legacy bare `<sender-slug>` directory alongside the `dm-`
+ * one — historical logs live there and must not go dark — and it is subject to
+ * exactly the same gate.
+ *
+ * @param {object} o
+ * @param {string|null} [o.channelId]  the room/DM channel id, when known
+ * @param {string|null} [o.senderSlug] the sender, slugified
+ * @param {boolean} [o.isPrivate]      is the reply going to that person privately
+ * @param {string} [o.service]
+ * @returns {string[]} directory names, possibly empty
+ */
+export function historyDirNames({ channelId, senderSlug, isPrivate, service } = {}) {
+  const dirs = [];
+  const cid = s(channelId);
+  const slug = s(senderSlug);
+  if (cid) dirs.push(cid);
+  if (isPrivate === true && slug) {
+    dirs.push(`dm-${slug}`);
+    if ((s(service) || "slack") === "slack") dirs.push(slug);
+  }
+  return dirs;
+}
+
+/**
+ * The directories `logInteraction` may WRITE this exchange to.
+ *
+ * The read gate above is the one that stops the leak, but leaving the writer
+ * unconditional keeps every per-person directory permanently contaminated with
+ * public-room content — so a future reader, or an operator grepping the tree,
+ * meets the same defect again. One rule, both ends.
+ *
+ * @param {object} o
+ * @param {string|null} [o.channelId]
+ * @param {string|null} [o.senderSlug]
+ * @param {boolean} [o.isPrivate]
+ * @returns {string[]}
+ */
+export function interactionWriteDirNames({ channelId, senderSlug, isPrivate } = {}) {
+  const dirs = [];
+  const cid = s(channelId);
+  const slug = s(senderSlug);
+  if (cid) dirs.push(cid);
+  if (isPrivate === true && slug) dirs.push(`dm-${slug}`);
+  return dirs;
+}
+
+export default { isPrivateConversation, historyDirNames, interactionWriteDirNames };

package/lib/diagnostics/alerts.mjs

@@ -91,6 +91,16 @@ export const DEFAULT_THRESHOLDS = Object.freeze({
     warnSec: 120, // 2 min (heartbeat refreshes ~15s)
     critSec: 300, // 5 min
   }),
+  cadenceOutputMissing: Object.freeze({
+    // A scheduled workflow finished without leaving its output artefacts behind.
+    // This is the ONLY rule here not derived from the cadence bus, and that is
+    // the point: the evening wrap missed 5 of 9 days in Aug/Sep 2026 and the bus
+    // logged one of those misses as stage="processed". A rule reading the bus's
+    // own decision is green during that outage. See
+    // lib/diagnostics/cadence-output-freshness.mjs.
+    warnCount: 1, // one missing artefact is already a real miss
+    critCount: 2, // both artefacts gone = the workflow did not run at all
+  }),
 });
 
 const SEVERITY_RANK = { critical: 0, warning: 1 };
@@ -243,6 +253,9 @@ function round2(n) {
  *                                   optionally with `perSessionUSD: number[]`
  * @param {object} [args.presence]   `{ heartbeatAgeSec?, daemonHealthAgeSec?,
  *                                       daemonDown? }`
+ * @param {object} [args.outputs]    cadence output verdict from
+ *                                   lib/diagnostics/cadence-output-freshness.mjs
+ *                                   `{ ok, days, checked, missing[] }`
  * @param {object} [args.thresholds] merged thresholds (default DEFAULT_THRESHOLDS)
  * @param {number} [args.now]        clock in epoch ms (reserved; rules are
  *                                   age-based via injected `*AgeSec`)
@@ -254,6 +267,7 @@ export function evaluateAlerts(args = {}) {
     const snapshot = args.snapshot && typeof args.snapshot === "object" ? args.snapshot : {};
     const ledger = args.ledger && typeof args.ledger === "object" ? args.ledger : {};
     const presence = args.presence && typeof args.presence === "object" ? args.presence : {};
+    const outputs = args.outputs && typeof args.outputs === "object" ? args.outputs : {};
     const t = mergeThresholds(DEFAULT_THRESHOLDS, args.thresholds || {});
 
     push(alerts, refusalSpikeRule(snapshot, t.refusalSpike));
@@ -261,6 +275,7 @@ export function evaluateAlerts(args = {}) {
     push(alerts, costPerSessionRule(ledger, t.costPerSessionP99));
     push(alerts, absentAgentRule(presence, t.absentAgent));
     push(alerts, daemonDownRule(presence, t.daemonDown));
+    push(alerts, cadenceOutputMissingRule(outputs, t.cadenceOutputMissing));
 
     // Deterministic order: critical first, then by id, so identical inputs always
     // produce identical output (a de-dupe upstream can key on id).
@@ -365,6 +380,40 @@ function daemonDownRule(presence, cfg = {}) {
   };
 }
 
+/**
+ * A scheduled workflow completed without producing its output artefacts.
+ *
+ * Unlike every other rule here, this one is NOT derived from the lane it judges.
+ * It reads files on disk that the workflow's own steps write, so it stays true
+ * when the cadence bus is wrong about itself — which is the failure this exists
+ * to catch (a timed-out evening wrap recorded as stage="processed", 29 Aug 2026).
+ *
+ * `checked === 0` means nothing was in scope (e.g. every candidate day predates
+ * its cadence). That is silence, not health, so it does not fire.
+ */
+function cadenceOutputMissingRule(outputs, cfg = {}) {
+  const missing = Array.isArray(outputs.missing) ? outputs.missing : null;
+  if (!missing || !num(outputs.checked)) return null; // nothing in scope
+  const count = missing.length;
+  const sev = severityFor(count, num(cfg.warnCount, Infinity), num(cfg.critCount, Infinity));
+  if (!sev) return null;
+
+  // Name the days and the workflow — an alert saying only "2 artefacts missing"
+  // sends the reader back to the bus log, which is exactly where the answer is not.
+  const days = [...new Set(missing.map((m) => m.day))].sort();
+  const labels = [...new Set(missing.map((m) => m.label || m.cadence))].sort();
+  const detail = missing
+    .slice(0, 4)
+    .map((m) => `${m.path} (${m.reason})`)
+    .join("; ");
+  const more = count > 4 ? ` +${count - 4} more` : "";
+  return {
+    id: "cadence_output_missing",
+    severity: sev,
+    detail: `${labels.join(", ")} produced no usable output for ${days.join(", ")}: ${detail}${more}. Checked on disk, independently of the cadence bus — the bus may still report this run as processed.`,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // emitAlerts
 // ---------------------------------------------------------------------------