@cohortapp/agent-sdk 2.5.1 → 2.6.1

package/lib/cost/ledger-row.mjs

@@ -0,0 +1,333 @@
+/**
+ * lib/cost/ledger-row.mjs — the ONE definition of "what did this ledger row
+ * cost, and do we actually know?"
+ *
+ * WHY THIS MODULE EXISTS
+ * ----------------------
+ * `state/cost-tracking/<date>.jsonl` has two writers with two different row
+ * shapes:
+ *
+ *   v1 — scripts/cost/track-claude-usage.mjs `record` (dispatcher +
+ *        cadence-consumer + responder: 100% of measured LLM spend today)
+ *   v2 — lib/model-router/ledger.mjs `writeLedgerRow` (llm-task + messaging
+ *        attribution)
+ *
+ * Every reader (budget-guard, doctor's cost tripwire, `maestro cost report`,
+ * fleet-digest) used to sum `estimated_usd` and count every line as a session.
+ * That was wrong three ways, and each way made the budget governor blinder:
+ *
+ *   1. `estimated_usd` on a v1 row was priced from a token table WITH NO CACHE
+ *      TIER. A real dispatcher row on 2026-08-12 reads input_tokens:16,
+ *      cache_read_input_tokens:553181, total_cost_usd:$0.533 — and priced out
+ *      at $0.075. Cache reads are ~90% of every prompt this agent sends, so the
+ *      day's spend read 2.6x-6.1x low ($90.79 vs $235.62 on 2026-08-11).
+ *   2. A row whose tokens were never measured (the tracker defaulted an absent
+ *      --input-tokens flag to 0) is INDISTINGUISHABLE from a genuine zero-token
+ *      row. A zero that means "unmeasured" is exactly what produces a governor
+ *      that can never trip.
+ *   3. Zero-LLM attribution rows (a message send: no model, no tokens, $0 by
+ *      construction) were counted as sessions, which armed doctor's "sessions
+ *      ran but spend is $0" tripwire on days when nothing but sends happened.
+ *
+ * So: classification and billing live HERE, once, and every reader imports it.
+ * Zero dependencies beyond the language — budget-guard is on the spawn hot path
+ * and its contract is Node built-ins only, never throws.
+ *
+ * ROW CONTRACT (forward-looking fields; legacy rows are inferred, see below)
+ *   measurement: "measured" | "unknown" | "n/a"
+ *     measured — input_tokens/output_tokens are real counts lifted from a
+ *                `claude --output-format json` envelope.
+ *     unknown  — a session ran, we could not read its usage. Tokens are null,
+ *                `unmeasured_reason` says why. NEVER write 0 here.
+ *     n/a      — no model was invoked (message-send attribution). $0 is a fact,
+ *                not an absence.
+ *   total_cost_usd — the CLI's authoritative figure. Preferred over any estimate.
+ *   estimated_usd  — token-derived fallback. Kept on every row for compatibility.
+ *
+ * @module lib/cost/ledger-row
+ */
+
+/** @typedef {"measured"|"unknown"|"n/a"|"invalid"} RowClass */
+
+export const MEASURED = "measured";
+export const UNKNOWN = "unknown";
+export const NON_LLM = "n/a";
+export const INVALID = "invalid";
+
+/**
+ * Numeric coercion that treats ABSENCE as absence.
+ *
+ * `Number(null)` and `Number("")` are both 0, so a naive coercion would turn a
+ * deliberately-null `input_tokens` back into a measured zero — re-creating the
+ * exact "unmeasured looks free" bug this module exists to prevent. Guard first.
+ */
+function num(v) {
+  if (v === null || v === undefined || v === "") return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Classify a ledger row. Explicit `measurement` wins; otherwise we infer from
+ * the row's shape so the ~200 rows already on disk classify correctly without a
+ * migration.
+ *
+ * Legacy inference:
+ *   - null/absent tokens on BOTH sides → unknown (the tracker only ever wrote
+ *     literal 0s, so this shape can only come from the new writer; harmless).
+ *   - no model AND zero tokens on both sides → n/a. This is precisely the
+ *     v2 messaging attribution row (`model:null, input_tokens:0`) and cannot
+ *     match a real session: every spawn path stamps a model.
+ *   - anything else → measured.
+ *
+ * @param {object} row
+ * @returns {RowClass}
+ */
+export function classifyRow(row) {
+  if (!row || typeof row !== "object") return INVALID;
+
+  const m = row.measurement;
+  if (m === MEASURED || m === UNKNOWN || m === NON_LLM) return m;
+
+  const inTok = num(row.input_tokens);
+  const outTok = num(row.output_tokens);
+  const hasModel = typeof row.model === "string" && row.model.length > 0;
+
+  // Checked BEFORE the cost test: a message-send row carries a real 0 cost, and
+  // we must not read that as "priced, therefore measured".
+  if (!hasModel && (inTok || 0) === 0 && (outTok || 0) === 0) return NON_LLM;
+
+  // A row that carries a NON-ZERO COST is measured, whatever its token fields
+  // look like. Cost is what readers bill; tokens are diagnostics. (This also
+  // keeps older cost-only rows billable instead of reclassifying history as
+  // blind.) A cost of exactly 0 on a row that NAMES A MODEL is not evidence of
+  // a free session — it is the writer's default standing in for "unpriceable",
+  // so it falls through to the token test below.
+  const cost = num(row.total_cost_usd) ?? num(row.estimated_usd);
+  if (cost !== null && cost > 0) return MEASURED;
+
+  // No usable cost. A model ran, so it generated tokens; zero or absent counts
+  // on BOTH sides therefore mean we failed to measure it, not that it was free.
+  // This is the same "a zero that means unmeasured" defect one layer down, and
+  // it is why an unpriced or catalog-missing model must never bill as $0.
+  if ((inTok || 0) === 0 && (outTok || 0) === 0) return UNKNOWN;
+
+  return MEASURED;
+}
+
+/**
+ * What did this row cost, and on what authority?
+ *
+ * Precedence — authoritative > estimated > unknown. `total_cost_usd` is the
+ * figure the Claude CLI reports for the session; it already accounts for cache
+ * read/write tiers, model class and any account-level pricing, none of which a
+ * local price table can track. We fall back to `estimated_usd` only when the
+ * authoritative number is absent, and we SAY SO in `basis` so the caller can
+ * log the degradation rather than silently under-count.
+ *
+ * @param {object} row
+ * @returns {{usd:number|null, basis:"authoritative"|"estimated"|"unmeasured"|"non_llm"|"invalid", cls:RowClass}}
+ */
+export function billableUsd(row) {
+  const cls = classifyRow(row);
+  if (cls === INVALID) return { usd: null, basis: "invalid", cls };
+  // A message send costs $0 because no model ran. That is a measurement, not a
+  // gap — it must not arm any blindness alarm.
+  if (cls === NON_LLM) return { usd: 0, basis: "non_llm", cls };
+  // A session we could not measure has an UNKNOWN cost. Returning 0 here is the
+  // original bug; the caller has to decide what to do with null (budget-guard
+  // imputes and logs; doctor goes red).
+  if (cls === UNKNOWN) return { usd: null, basis: "unmeasured", cls };
+
+  // `> 0`, not `>= 0`: a zero price on a row that named a model is the writer's
+  // "I could not price this" default (an absent catalog row, an unreadable usage
+  // envelope), and billing it as a free session is exactly how a pricing outage
+  // silences the governor. Fall through to UNKNOWN and let the caller impute.
+  const authoritative = num(row.total_cost_usd);
+  if (authoritative !== null && authoritative > 0) {
+    return { usd: authoritative, basis: "authoritative", cls };
+  }
+  const estimated = num(row.estimated_usd);
+  if (estimated !== null && estimated > 0) {
+    return { usd: estimated, basis: "estimated", cls };
+  }
+  // The row HAS usage but nothing could price it (no authoritative figure, and
+  // the catalog had no row for the model). Distinct from "unmeasured": the
+  // telemetry worked and the PRICING did not, which is a different bug with a
+  // different fix, and doctor says so. Either way it is not free.
+  return { usd: null, basis: "unpriced", cls: UNKNOWN };
+}
+
+function round6(n) {
+  return Number(n.toFixed(6));
+}
+
+/**
+ * Fold a day's rows into the numbers every reader needs, including the ones
+ * that used to be invisible.
+ *
+ * `sessions` counts LLM sessions only (measured + unmeasured) — non-LLM
+ * attribution rows are reported separately as `nonLlmRows`. Anything that
+ * degraded the number is listed in `degradations[]`: fail-open is fine, silent
+ * is not.
+ *
+ * @param {Array<object>} rows
+ * @returns {{
+ *   sessions:number, measured:number, unmeasured:number, nonLlmRows:number,
+ *   invalidRows:number, measuredUsd:number, authoritativeUsd:number,
+ *   estimatedFallbackUsd:number, estimatedFallbackRows:number,
+ *   blind:boolean, degradations:string[]
+ * }}
+ */
+export function summariseRows(rows) {
+  let measured = 0;
+  let unmeasured = 0;
+  let nonLlmRows = 0;
+  let invalidRows = 0;
+  let measuredUsd = 0;
+  let authoritativeUsd = 0;
+  let estimatedFallbackUsd = 0;
+  let estimatedFallbackRows = 0;
+  // `unmeasured` is the imputation base; these two say WHICH failure produced it.
+  let noTokenRows = 0;   // a session ran and nobody read its usage
+  let unpricedRows = 0;  // usage was read but nothing could price it
+
+  for (const row of rows || []) {
+    const { usd, basis } = billableUsd(row);
+    switch (basis) {
+      case "authoritative":
+        measured++;
+        measuredUsd += usd;
+        authoritativeUsd += usd;
+        break;
+      case "estimated":
+        measured++;
+        measuredUsd += usd;
+        estimatedFallbackUsd += usd;
+        estimatedFallbackRows++;
+        break;
+      case "unmeasured":
+        unmeasured++;
+        noTokenRows++;
+        break;
+      case "unpriced":
+        unmeasured++;
+        unpricedRows++;
+        break;
+      case "non_llm":
+        nonLlmRows++;
+        break;
+      default:
+        invalidRows++;
+    }
+  }
+
+  const degradations = [];
+  if (noTokenRows > 0) {
+    degradations.push(
+      `${noTokenRows} session row(s) recorded NO token counts (measurement:"unknown") — their spend is unknown, not zero`
+    );
+  }
+  if (unpricedRows > 0) {
+    degradations.push(
+      `${unpricedRows} session row(s) carry usage but NO price (no total_cost_usd, and the model is not in the catalog) — pricing is broken, and the rows are not free`
+    );
+  }
+  if (estimatedFallbackRows > 0) {
+    degradations.push(
+      `${estimatedFallbackRows} row(s) had no authoritative total_cost_usd; fell back to the local token estimate ($${round6(estimatedFallbackUsd)}), which under-prices cache reads`
+    );
+  }
+  if (invalidRows > 0) {
+    degradations.push(`${invalidRows} malformed ledger row(s) skipped`);
+  }
+
+  return {
+    sessions: measured + unmeasured,
+    measured,
+    unmeasured,
+    nonLlmRows,
+    invalidRows,
+    noTokenRows,
+    unpricedRows,
+    measuredUsd: round6(measuredUsd),
+    authoritativeUsd: round6(authoritativeUsd),
+    estimatedFallbackUsd: round6(estimatedFallbackUsd),
+    estimatedFallbackRows,
+    // Blind = sessions ran and we measured NONE of them. This is the precise
+    // condition doctor's tripwire is supposed to detect. An empty ledger is not
+    // blind — it is quiet.
+    blind: measured === 0 && unmeasured > 0,
+    degradations,
+  };
+}
+
+/**
+ * Impute a cost for the sessions we failed to measure, so a systematic parse
+ * regression cannot starve the budget governor into never tripping.
+ *
+ * The alternative — counting unmeasured sessions as $0 — is the exact failure
+ * this module exists to kill: a governor that goes quiet precisely when
+ * telemetry breaks.
+ *
+ * WHAT CHANGED, AND WHY THERE IS NO LONGER A MAGIC NUMBER
+ * ------------------------------------------------------
+ * This used to fall back to a hard-coded `floorUsd = 0.25` per session when the
+ * day had nothing measured. That number was sourced from nothing, and it was
+ * ~8x BELOW this fleet's observed mean ($1.95/session on 2026-08-12), so it
+ * defeated the property the docstring claimed: a total telemetry outage on a day
+ * that really cost $68.40 (274 % of a $25 cap → the refuse rung) imputed $8.75
+ * and reported band 0, mode normal. Under-imputing is not conservative; it is
+ * the silent-governor bug wearing a different hat.
+ *
+ * So the ladder is now evidence-only, and it ADMITS when it has none:
+ *   1. `day_mean`   — this day's own mean measured session cost. Best evidence.
+ *   2. `period_mean`— the caller's `fallbackPerSessionUsd` (budget-guard passes
+ *                     the MONTH's mean measured cost, which survives a day that
+ *                     is blind end to end).
+ *   3. `unpriceable`— no evidence at ANY horizon. We return $0 and set
+ *                     `unpriceable:true` rather than invent a price. The caller
+ *                     must not read that 0 as "cheap": `summariseRows().blind`
+ *                     is the signal, and `lib/budget-guard.dailyStatus` floors
+ *                     the enforcement band at DEGRADE when it is set. "We cannot
+ *                     measure, therefore we degrade" needs no price table.
+ *
+ * Every imputation is reported by the caller; none of it is silent.
+ *
+ * @param {ReturnType<typeof summariseRows>} summary
+ * @param {{fallbackPerSessionUsd?:number}|number} [opts] month/period mean, when
+ *        the day itself measured nothing. A bare number is accepted for
+ *        backward compatibility with the old positional `floorUsd`.
+ * @returns {{imputedUsd:number, perSessionUsd:number,
+ *            basis:"day_mean"|"period_mean"|"unpriceable"|"none",
+ *            unpriceable:boolean}}
+ */
+export function imputeUnmeasured(summary, opts = {}) {
+  if (!summary || summary.unmeasured <= 0) {
+    return { imputedUsd: 0, perSessionUsd: 0, basis: "none", unpriceable: false };
+  }
+  const fallback = typeof opts === "number"
+    ? opts
+    : num(opts && opts.fallbackPerSessionUsd);
+
+  const dayMean = summary.measured > 0 ? summary.measuredUsd / summary.measured : null;
+  if (dayMean !== null && dayMean > 0) {
+    return {
+      imputedUsd: round6(dayMean * summary.unmeasured),
+      perSessionUsd: round6(dayMean),
+      basis: "day_mean",
+      unpriceable: false,
+    };
+  }
+  if (fallback !== null && fallback > 0) {
+    return {
+      imputedUsd: round6(fallback * summary.unmeasured),
+      perSessionUsd: round6(fallback),
+      basis: "period_mean",
+      unpriceable: false,
+    };
+  }
+  return { imputedUsd: 0, perSessionUsd: 0, basis: "unpriceable", unpriceable: true };
+}
+
+export default { classifyRow, billableUsd, summariseRows, imputeUnmeasured, MEASURED, UNKNOWN, NON_LLM, INVALID };

package/lib/cost/ledger-row.test.mjs

@@ -0,0 +1,183 @@
+/**
+ * lib/cost/ledger-row.test.mjs — the measured / unmeasured / non-LLM contract.
+ *
+ * The bug these lock down: an absent token count and a genuine zero used to
+ * produce identical rows, and every reader summed both as $0. That is what made
+ * the budget governor unable to trip.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  classifyRow,
+  billableUsd,
+  summariseRows,
+  imputeUnmeasured,
+  MEASURED,
+  UNKNOWN,
+  NON_LLM,
+  INVALID,
+} from "./ledger-row.mjs";
+
+// A real dispatcher row copied from the live ledger (2026-08-12). Note the
+// shape that broke the old estimator: 16 uncached input tokens against 553k
+// cache reads, and an authoritative cost 7x the token-table estimate.
+const REAL_ROW = {
+  ts: "2026-08-12T00:09:36.073Z", cadence: "inbox", source: "dispatcher",
+  model: "sonnet", duration_ms: 64728, input_tokens: 16, output_tokens: 5000,
+  exit_code: 0, cache_read_input_tokens: 553181,
+  estimated_usd: 0.075048, total_cost_usd: 0.533412,
+};
+
+test("classifyRow: explicit measurement wins", () => {
+  assert.equal(classifyRow({ measurement: "measured", input_tokens: 1 }), MEASURED);
+  assert.equal(classifyRow({ measurement: "unknown", input_tokens: null }), UNKNOWN);
+  assert.equal(classifyRow({ measurement: "n/a" }), NON_LLM);
+  assert.equal(classifyRow(null), INVALID);
+  assert.equal(classifyRow("nope"), INVALID);
+});
+
+test("classifyRow: legacy rows are inferred without a migration", () => {
+  // Real dispatcher row, no `measurement` field.
+  assert.equal(classifyRow(REAL_ROW), MEASURED);
+  // Real messaging attribution row: no model, zero tokens => not a session.
+  assert.equal(
+    classifyRow({ source: "messaging", model: null, input_tokens: 0, output_tokens: 0, estimated_usd: 0 }),
+    NON_LLM
+  );
+  // Null tokens on both sides => unmeasured.
+  assert.equal(classifyRow({ model: "sonnet", input_tokens: null, output_tokens: null }), UNKNOWN);
+});
+
+test("classifyRow: a real session that used zero output tokens is still MEASURED", () => {
+  // The distinction that matters: a model ran and produced nothing is a
+  // measurement; it must not be confused with "we never looked".
+  assert.equal(classifyRow({ model: "sonnet", input_tokens: 120, output_tokens: 0 }), MEASURED);
+});
+
+test("billableUsd: authoritative CLI cost beats the local estimate", () => {
+  const { usd, basis } = billableUsd(REAL_ROW);
+  assert.equal(basis, "authoritative");
+  assert.equal(usd, 0.533412);
+  // The whole point: the old path would have billed the estimate.
+  assert.notEqual(usd, REAL_ROW.estimated_usd);
+});
+
+test("billableUsd: falls back to the estimate and says so", () => {
+  const { usd, basis } = billableUsd({ ...REAL_ROW, total_cost_usd: undefined });
+  assert.equal(basis, "estimated");
+  assert.equal(usd, 0.075048);
+});
+
+test("billableUsd: an unmeasured session costs NULL, not zero", () => {
+  const { usd, basis } = billableUsd({ measurement: "unknown", input_tokens: null, output_tokens: null });
+  assert.equal(usd, null);
+  assert.equal(basis, "unmeasured");
+});
+
+test("billableUsd: usage with no price is UNPRICED — a distinct bug from unmeasured, and still not free", () => {
+  const { usd, basis, cls } = billableUsd({ model: "sonnet", input_tokens: 5, output_tokens: 5 });
+  assert.equal(usd, null, "never 0 — a pricing outage must not read as a free session");
+  assert.equal(basis, "unpriced", "the telemetry worked; the PRICING did not");
+  assert.equal(cls, UNKNOWN);
+});
+
+test("billableUsd: a $0 price on a row that named a model is unpriceable, not free", () => {
+  // lib/model-router/ledger.mjs used to default `estimated_usd` to 0 whenever
+  // estimateCost returned null (a model missing from the catalog), and that 0
+  // billed as a measured free session. Both zeroes now fall through.
+  const zeroed = billableUsd({ model: "opus", input_tokens: 900, output_tokens: 40, total_cost_usd: 0, estimated_usd: 0 });
+  assert.equal(zeroed.usd, null);
+  assert.equal(zeroed.basis, "unpriced");
+});
+
+test("billableUsd: a zero-model attribution row is a real $0, not a gap", () => {
+  const { usd, basis } = billableUsd({ source: "messaging", model: null, input_tokens: 0, output_tokens: 0 });
+  assert.equal(usd, 0);
+  assert.equal(basis, "non_llm");
+});
+
+test("summariseRows: separates sessions from attribution rows", () => {
+  const s = summariseRows([
+    REAL_ROW,
+    { ...REAL_ROW, total_cost_usd: 1 },
+    { source: "messaging", model: null, input_tokens: 0, output_tokens: 0 },
+    { measurement: "unknown", input_tokens: null, output_tokens: null },
+  ]);
+  assert.equal(s.sessions, 3, "2 measured + 1 unmeasured; the send is not a session");
+  assert.equal(s.measured, 2);
+  assert.equal(s.unmeasured, 1);
+  assert.equal(s.nonLlmRows, 1);
+  assert.equal(s.measuredUsd, 1.533412);
+  assert.equal(s.blind, false);
+});
+
+test("summariseRows: blind only when sessions ran and NONE were measured", () => {
+  assert.equal(summariseRows([]).blind, false, "an empty ledger is quiet, not blind");
+  assert.equal(
+    summariseRows([{ source: "messaging", model: null, input_tokens: 0, output_tokens: 0 }]).blind,
+    false,
+    "attribution rows alone must not arm the alarm"
+  );
+  assert.equal(
+    summariseRows([{ measurement: "unknown", input_tokens: null, output_tokens: null }]).blind,
+    true
+  );
+});
+
+test("summariseRows: every degradation is reported, never swallowed", () => {
+  const s = summariseRows([
+    { measurement: "unknown", input_tokens: null, output_tokens: null },
+    { ...REAL_ROW, total_cost_usd: undefined },
+    "malformed",
+  ]);
+  assert.equal(s.degradations.length, 3);
+  assert.match(s.degradations.join(" | "), /recorded NO token counts/);
+  assert.match(s.degradations.join(" | "), /no authoritative total_cost_usd/);
+  assert.match(s.degradations.join(" | "), /malformed/);
+});
+
+test("imputeUnmeasured: unmeasured sessions cost the day's mean, not zero", () => {
+  const s = summariseRows([
+    { ...REAL_ROW, total_cost_usd: 2 },
+    { measurement: "unknown", input_tokens: null, output_tokens: null },
+    { measurement: "unknown", input_tokens: null, output_tokens: null },
+  ]);
+  const imp = imputeUnmeasured(s);
+  assert.equal(imp.basis, "day_mean");
+  assert.equal(imp.perSessionUsd, 2);
+  assert.equal(imp.imputedUsd, 4);
+});
+
+test("imputeUnmeasured: a blind day imputes from the PERIOD mean when the day has nothing", () => {
+  // The anti-starvation property, without a magic number. The old fallback was a
+  // hard-coded $0.25/session — ~8x below this fleet's observed $1.95 mean — so a
+  // total outage on a day that really cost $68.40 (274% of a $25 cap) imputed
+  // $8.75 and reported band 0. Under-imputing is the silent-governor bug.
+  const s = summariseRows([{ measurement: "unknown", input_tokens: null, output_tokens: null }]);
+  const imp = imputeUnmeasured(s, { fallbackPerSessionUsd: 1.95 });
+  assert.equal(imp.basis, "period_mean");
+  assert.equal(imp.perSessionUsd, 1.95);
+  assert.equal(imp.imputedUsd, 1.95);
+  assert.equal(imp.unpriceable, false);
+});
+
+test("imputeUnmeasured: with NO evidence at any horizon it refuses to invent a price", () => {
+  // And says so. The caller (lib/budget-guard.dailyStatus) floors the band at
+  // DEGRADE on `unpriceable`, which needs no price table: we cannot measure,
+  // therefore we degrade. Returning a made-up dollar figure here is what let a
+  // $68 day read as band 0.
+  const s = summariseRows([{ measurement: "unknown", input_tokens: null, output_tokens: null }]);
+  const imp = imputeUnmeasured(s);
+  assert.equal(imp.basis, "unpriceable");
+  assert.equal(imp.imputedUsd, 0);
+  assert.equal(imp.unpriceable, true);
+  assert.equal(s.blind, true, "the signal the band floor keys off");
+});
+
+test("imputeUnmeasured: nothing unmeasured means nothing imputed", () => {
+  const imp = imputeUnmeasured(summariseRows([REAL_ROW]));
+  assert.equal(imp.imputedUsd, 0);
+  assert.equal(imp.basis, "none");
+});

package/lib/execution/drive.mjs

@@ -48,6 +48,24 @@ export const EFFECT_FOR = Object.freeze({
 /** Dispositions after which the agent has SPOKEN (deepens a reply chain). */
 const SPEAKING = Object.freeze(["react_now"]);
 
+/**
+ * Did this effect actually put words in front of a person?
+ *
+ * The disposition alone cannot answer that any more. `escalate` and `delegate`
+ * now reach a human through the engagement judgement when one is warranted, and
+ * do not when it isn't — so whether the agent spoke is a property of what the
+ * effect DID, not of which lane it took. An effect that reached someone reports
+ * `ref.spoke === true`; anything else is taken at its disposition's word.
+ *
+ * This matters beyond bookkeeping: `spoke` is what a self-healing sweep reads to
+ * decide whether a human is still owed an answer. A lane that claims to have
+ * spoken when it only wrote a row makes that sweep conclude everything is fine.
+ */
+function didSpeak(decision, r) {
+  if (r && r.ref && typeof r.ref === "object" && r.ref.spoke === true) return true;
+  return r.ok && SPEAKING.includes(decision.disposition);
+}
+
 /**
  * Run one effect with uniform error capture. Returns a normalised result rather
  * than throwing, so the caller's sequencing stays linear.
@@ -331,6 +349,15 @@ export async function drive(decision, o = {}) {
     });
   }
   const r = await runEffect(effects[name], name, { decision, candidate: o.candidate, item: o.item });
+  // An effect that half-succeeded says so on its ref. Surfacing it here is what
+  // keeps "the person was reached but the audit row was not written" from
+  // reading as an unqualified success.
+  if (r.ref && typeof r.ref === "object" && Array.isArray(r.ref.degraded)) {
+    for (const d of r.ref.degraded) {
+      degraded.push(String(d));
+      log("warn", `${name} effect degraded: ${d}`, { key: decision.key });
+    }
+  }
   if (r.missing) {
     degraded.push(`${name}_effect_missing`);
     log("error", `no \`${name}\` effect wired — the event was decided but not acted on`, { key: decision.key });
@@ -341,7 +368,7 @@ export async function drive(decision, o = {}) {
   return finish({
     effect: name,
     ok: r.ok,
-    spoke: r.ok && SPEAKING.includes(decision.disposition),
+    spoke: didSpeak(decision, r),
     ref: r.ref,
     error: r.error,
     degraded,