@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/lib/budget-guard.mjs

@@ -1,33 +1,54 @@
 /**
- * lib/budget-guard.mjs — daily spend cap + essential-only mode (WS4).
- *
- * Sums today's per-session cost rows from the existing ledger
- * (`state/cost-tracking/<date>.jsonl`, written by
- * scripts/cost/track-claude-usage.mjs) and reports where the day sits against
- * a configured cap. As spend crosses 50 / 75 / 90 %, a single escalating
- * notice is emitted PER BAND PER DAY (tracked in
- * `state/cost-tracking/<date>.budget.json` so we never spam). At 100 % the
- * governor flips to `essentialOnly`: backlog + cadence-escalation work is
- * DEFERRED, but inbox DMs are still answered (Invariant #1 — never brick; we
- * degrade, we don't go dark on the user).
+ * lib/budget-guard.mjs — the seat's ceiling, and what happens when it is hit.
+ *
+ * Sums today's per-session cost rows from the ledger
+ * (`state/cost-tracking/<date>.jsonl`) and reports where the period sits against
+ * the seat's FUNDED ENVELOPE, plus the enforcement posture that band implies.
+ *
+ * ── WHERE THE CEILING COMES FROM (this is the part that was missing) ────────
+ * It used to be `DAILY_SPEND_CAP_USD` / `config/recovery.yaml` — files that live
+ * inside the agent's own repo, which is to say: the seat set its own budget. The
+ * real number is `Employee.payBasis.meteredBudget` in hq, published on the
+ * mandate body as `seatBudgetCents` and cached at `state/mandate/cache.json`.
+ *
+ *   hq Employee.payBasis.meteredBudget → mandate body seatBudgetCents
+ *     → state/mandate/cache.json → readSeatEnvelope → dailyAllowance
+ *     → every decision below.
+ *
+ * The envelope is monthly; today's allowance is the REMAINING envelope over the
+ * REMAINING days (a quiet week funds a busy one). The local cap survives as a
+ * SAFETY NET: when the two disagree the lower binds, and the disagreement is
+ * logged. When hq published nothing, the local cap binds and every read carries
+ * an "UNFUNDED SEAT" degradation — an agent that cannot know its funding must
+ * say so loudly rather than assume a number. (The last time something assumed
+ * one, the whole fleet ran on an invented 500c-per-obligation allowance.)
+ *
+ * ── THE LADDER (a ladder, not a cliff) — see `postureForBand` ───────────────
+ *   80 %   escalate to the supervisor (never to the owner)
+ *   100 %  degrade the rung: cheapest model class, fan-out 1, D3 stops
+ *   125 %  suspend the OUTCOME obligations (not the seat)
+ *   >150 % refuse at spawn level: DEFER anything that is not a human reply
+ *
+ * No band self-clears by agent action. Bands reset at the period boundary (the
+ * ledger + notice files are UTC-date-stamped) or when a supervisor/human RAISES
+ * the envelope — fingerprinted on the binding cap, which the seat cannot raise
+ * on its own (the binding cap is the LOWER of envelope and local config).
  *
  * Config knobs (env-overridable; tests inject via deps):
- *   DAILY_SPEND_CAP_USD     hard cap in USD (default 25)
+ *   DAILY_SPEND_CAP_USD     local safety-net cap in USD (default 25)
  *   DAILY_ITERATION_CAP     optional cap on session count (default 0 = off)
  *
- * The window resets at UTC midnight automatically — the ledger + budget files
- * are date-stamped, so "today" is simply the current UTC date.
- *
  * Constraints (CLAUDE.md): ESM, Node built-ins only, injectable clock +
  * ledger path so tests are hermetic. Never throws on I/O failure: a guard
- * that can't read the ledger reports band 0 (essentialOnly:false) — degrade
- * toward keeping work flowing, not toward bricking.
+ * that can't read the ledger reports band 0 — degrade toward keeping work
+ * flowing, not toward bricking. FAIL-OPEN IS FINE; SILENT IS NOT.
  */
 
 import {
   existsSync,
   mkdirSync,
   readFileSync,
+  readdirSync,
   writeFileSync,
   renameSync,
   unlinkSync,
@@ -35,6 +56,8 @@ import {
 import { join, resolve, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 
+import { summariseRows, imputeUnmeasured } from "./cost/ledger-row.mjs";
+
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
@@ -42,6 +65,29 @@ import { randomBytes } from "node:crypto";
 export const DEFAULT_DAILY_SPEND_CAP_USD = 25;
 export const DEFAULT_DAILY_ITERATION_CAP = 0; // 0 = no session-count cap
 
+/**
+ * Envelope freshness, mirroring `lib/mandate/cache.mjs` TIERS (duplicated as two
+ * numbers rather than imported: this module's contract is Node built-ins only
+ * because it sits on the spawn hot path and must never throw on an import).
+ *   AGING   report it, keep enforcing it.
+ *   EXPIRY  stop treating the cached number as hq's decision.
+ */
+export const ENVELOPE_AGING_SEC = 24 * 3600;
+export const ENVELOPE_EXPIRY_SEC = 7 * 24 * 3600;
+
+/**
+ * The band a seat sits at when sessions ran and NONE of them could be measured
+ * or priced from evidence at any horizon.
+ *
+ * DEGRADE, not normal, and not refuse. "We cannot measure, therefore we degrade"
+ * is a decision that needs no price table: it costs the seat its frontier models
+ * and its self-directed work while leaving every inbox reply intact, and it
+ * cannot be reached by a seat that is simply cheap today (an empty ledger is
+ * quiet, not blind — `summariseRows().blind` requires sessions to have run).
+ * Without it, `blind` was computed, surfaced, and enforced by nobody.
+ */
+export const BLIND_MIN_BAND = 100;
+
 /**
  * Read the daily spend cap from config/recovery.yaml, if present. We extract the
  * single scalar we need with a targeted regex rather than pulling in a YAML
@@ -109,14 +155,18 @@ function todayUtc(deps) {
   return new Date(clock(deps)()).toISOString().slice(0, 10);
 }
 
+function agentRootOf(deps) {
+  return resolve(
+    (deps && deps.agentRoot) ||
+      process.env.AGENT_ROOT ||
+      process.env.AGENT_DIR ||
+      process.cwd()
+  );
+}
+
 function ledgerDir(deps) {
   if (deps && deps.ledgerDir) return resolve(deps.ledgerDir);
-  const root =
-    (deps && deps.agentRoot) ||
-    process.env.AGENT_ROOT ||
-    process.env.AGENT_DIR ||
-    process.cwd();
-  return join(resolve(root), "state", "cost-tracking");
+  return join(agentRootOf(deps), "state", "cost-tracking");
 }
 
 function ledgerFile(deps) {
@@ -128,20 +178,92 @@ function budgetStateFile(deps) {
 }
 
 // ---------------------------------------------------------------------------
-// Banding
+// Banding + enforcement posture
 // ---------------------------------------------------------------------------
 
-/** Bands are the integer thresholds we notify at. 0 = below 50 %. */
-export const BANDS = [50, 75, 90, 100];
+/**
+ * The governance bands, as INCLUSIVE LOWER BOUNDS on `pct`. 0 = under 80 %.
+ *
+ * These replaced [50, 75, 90, 100]. The old set banded a LOCAL cap using an
+ * under-read numerator: three of its four rungs fired before anything was at
+ * risk, and only the top rung had teeth (and it was binary — essential-only or
+ * nothing). The new set bands the SEAT ENVELOPE hq published, using the
+ * authoritative cost, so 100 % means "this seat has spent what the org funded",
+ * not "a config file in the agent's own repo said 25".
+ *
+ * 150 is inclusive on purpose (the decision writes ">150 %"): a seat sitting at
+ * exactly 1.5x its funded envelope is already over, and a strict `>` would make
+ * the refuse rung unreachable at the round number most likely to be hit.
+ */
+export const BANDS = [80, 100, 125, 150];
+
+/** Enforcement modes, ascending. The resource governor consumes these by name. */
+export const MODES = Object.freeze({
+  NORMAL: "normal",
+  DEGRADED: "degraded",
+  SUSPENDED: "suspended",
+  REFUSED: "refused",
+});
+
+/** `lib/execution/route.mjs` rung 5 = `team` (sub-agent fan-out). */
+const TEAM_RUNG = 5;
 
 function bandForPct(pct) {
+  if (!Number.isFinite(pct)) return 0;
+  if (pct >= 150) return 150;
+  if (pct >= 125) return 125;
   if (pct >= 100) return 100;
-  if (pct >= 90) return 90;
-  if (pct >= 75) return 75;
-  if (pct >= 50) return 50;
+  if (pct >= 80) return 80;
   return 0;
 }
 
+/**
+ * The structured enforcement instruction for a band. PURE, total, never throws.
+ *
+ * Every consumer reads THIS instead of re-deriving thresholds from `band`, so
+ * the ladder is written down exactly once:
+ *   lib/model-router/economics.budgetLadder → routing (cheapest class)
+ *   lib/resource-governor.admit             → spawn admission
+ *   lib/plan/compile.applyBudgetPosture     → obligation suspension
+ *   scripts/daemon/cadence-handlers         → D3 self-directed work
+ *
+ * The rungs, and why each is where it is:
+ *   80  ESCALATE — one notice to the SUPERVISOR, once per band per period.
+ *       Never to the owner: an agent told it is running out of money has every
+ *       incentive to optimise the meter instead of the work.
+ *   100 DEGRADE THE RUNG — cheapest model class, fan-out capped at 1 (the
+ *       `team` rung becomes unavailable), self-directed D3 work stops. Inbox
+ *       DMs are still answered, at the degraded rung. This is the rung that was
+ *       missing: enforcement used to be binary.
+ *   125 SUSPEND THE OBLIGATIONS, NOT THE SEAT — OUTCOME obligations flip to
+ *       `suspended` with a `budget_breach` drift row. Inline/offline_safe
+ *       cadences continue.
+ *   150 REFUSE, AT SPAWN LEVEL ONLY — DEFER (never hard-refuse) anything that is
+ *       not a direct human reply. A seat-level refuse would brick the seat, and
+ *       Invariant #1 forbids that.
+ *
+ * @param {number} band 0|80|100|125|150
+ */
+export function postureForBand(band) {
+  const b = Number(band) || 0;
+  const mode =
+    b >= 150 ? MODES.REFUSED
+      : b >= 125 ? MODES.SUSPENDED
+        : b >= 100 ? MODES.DEGRADED
+          : MODES.NORMAL;
+  return Object.freeze({
+    band: b,
+    mode,
+    escalateToSupervisor: b >= 80,
+    cheapModelOnly: b >= 100,
+    maxFanout: b >= 100 ? 1 : null,
+    maxRung: b >= 100 ? TEAM_RUNG - 1 : null,
+    selfDirected: b < 100,
+    suspendOutcomeObligations: b >= 125,
+    refuseNonHumanSpawn: b >= 150,
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Ledger sum
 // ---------------------------------------------------------------------------
@@ -149,23 +271,378 @@ function bandForPct(pct) {
 /**
  * Sum today's spend + session count from the JSONL ledger. Never throws;
  * malformed lines are skipped, a missing file yields zeroes.
+ *
+ * WHAT CHANGED AND WHY (2026-08-12)
+ * ---------------------------------
+ * This used to sum `row.estimated_usd` and count every line as one session.
+ * Both halves were wrong, and both made the cap unable to bind:
+ *
+ *  - `estimated_usd` on the v1 tracker rows was priced from a table with NO
+ *    CACHE TIER, while ~99% of this agent's prompt tokens are cache reads. The
+ *    governor saw $90.79 on a day that actually cost $235.62 against a $25 cap.
+ *    We now bill against the CLI's authoritative `total_cost_usd` and fall back
+ *    to the (now cache-aware) estimate only when it is absent — logged, never
+ *    silent. See lib/cost/ledger-row.mjs.
+ *  - Rows with no measured tokens summed as $0, so a systematic usage-parse
+ *    regression would quietly drive the day's spend toward zero exactly when
+ *    telemetry broke. Unmeasured sessions are now imputed at the day's mean
+ *    measured cost and reported in `degradations`.
+ *  - Zero-LLM attribution rows (message sends) were counted as sessions,
+ *    inflating the iteration-cap denominator. They are excluded from `sessions`
+ *    and reported as `nonLlmRows`.
  */
 function sumToday(deps) {
   const file = ledgerFile(deps);
-  let spentUSD = 0;
-  let sessions = 0;
-  if (!existsSync(file)) return { spentUSD: 0, sessions: 0 };
+  const emptyResult = {
+    spentUSD: 0, sessions: 0, measuredUSD: 0, imputedUSD: 0,
+    unmeasuredSessions: 0, nonLlmRows: 0, blind: false, degradations: [],
+  };
+  if (!existsSync(file)) return emptyResult;
   let body;
-  try { body = readFileSync(file, "utf-8"); } catch { return { spentUSD: 0, sessions: 0 }; }
+  try { body = readFileSync(file, "utf-8"); } catch { return emptyResult; }
+
+  const rows = [];
+  let malformed = 0;
   for (const line of body.split("\n")) {
     if (!line.trim()) continue;
-    let row;
-    try { row = JSON.parse(line); } catch { continue; }
-    const usd = Number(row.estimated_usd);
-    if (Number.isFinite(usd)) spentUSD += usd;
-    sessions += 1;
+    try { rows.push(JSON.parse(line)); } catch { malformed += 1; }
+  }
+
+  const summary = summariseRows(rows);
+  // When TODAY measured nothing, fall back to the month's mean measured session
+  // cost rather than to an invented per-session floor. A day that is blind end
+  // to end is exactly when a made-up number does the most damage: the previous
+  // $0.25/session constant was ~8x below this fleet's observed $1.95 mean, so a
+  // total outage on a $68 day imputed $8.75 and reported band 0.
+  const imputed = imputeUnmeasured(summary, {
+    fallbackPerSessionUsd: deps && deps.__monthMeanUsd !== undefined
+      ? deps.__monthMeanUsd
+      : monthMeanSessionUsd(deps),
+  });
+  const degradations = [...summary.degradations];
+  if (malformed > 0) degradations.push(`${malformed} unparseable ledger line(s) skipped`);
+  if (imputed.imputedUsd > 0) {
+    degradations.push(
+      `imputed $${imputed.imputedUsd} for ${summary.unmeasured} unmeasured session(s) at $${imputed.perSessionUsd}/session (${imputed.basis}) — counted toward the cap so a telemetry outage cannot silence the governor`
+    );
+  }
+  if (imputed.unpriceable) {
+    degradations.push(
+      `${summary.unmeasured} unmeasured session(s) and NO measured session at any horizon (today or month-to-date) — ` +
+      "their cost cannot be imputed from evidence and is NOT being invented. The band is floored at DEGRADE instead " +
+      "(see BLIND_MIN_BAND): we cannot measure, therefore we degrade."
+    );
+  }
+
+  return {
+    spentUSD: +(summary.measuredUsd + imputed.imputedUsd).toFixed(6),
+    measuredUSD: summary.measuredUsd,
+    imputedUSD: imputed.imputedUsd,
+    sessions: summary.sessions,
+    unmeasuredSessions: summary.unmeasured,
+    nonLlmRows: summary.nonLlmRows,
+    blind: summary.blind,
+    unpriceable: imputed.unpriceable === true,
+    degradations,
+  };
+}
+
+/**
+ * The month's mean measured session cost — the second rung of the imputation
+ * ladder, used when TODAY has measured nothing at all. Evidence, not a constant.
+ * Returns null when the whole month is unmeasured (then nothing is invented).
+ */
+function monthMeanSessionUsd(deps) {
+  const dir = ledgerDir(deps);
+  const month = todayUtc(deps).slice(0, 7);
+  let files = [];
+  try {
+    files = readdirSync(dir).filter((f) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f) && f.startsWith(month));
+  } catch {
+    return null;
+  }
+  let usd = 0;
+  let n = 0;
+  for (const f of files) {
+    let body;
+    try { body = readFileSync(join(dir, f), "utf-8"); } catch { continue; }
+    const rows = [];
+    for (const line of body.split("\n")) {
+      if (!line.trim()) continue;
+      try { rows.push(JSON.parse(line)); } catch { /* skip */ }
+    }
+    const s = summariseRows(rows);
+    usd += s.measuredUsd;
+    n += s.measured;
+  }
+  return n > 0 && usd > 0 ? usd / n : null;
+}
+
+// ---------------------------------------------------------------------------
+// The denominator — what the ORG funded, not what the seat configured
+// ---------------------------------------------------------------------------
+
+/**
+ * Sum every date-stamped ledger file in the current UTC month.
+ *
+ * This is what lets a quiet week fund a busy one: the daily allowance is the
+ * REMAINING envelope over the REMAINING days, not a flat 1/N slice that expires
+ * unused each midnight.
+ */
+export function monthToDate(deps) {
+  const dir = ledgerDir(deps);
+  const month = todayUtc(deps).slice(0, 7); // YYYY-MM
+  let files = [];
+  try {
+    files = readdirSync(dir).filter((f) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f) && f.startsWith(month));
+  } catch {
+    return { spentUSD: 0, days: 0 };
+  }
+  // One month-wide mean, computed once, so a day that measured NOTHING still
+  // imputes from evidence instead of contributing $0 to the month's total.
+  const fallbackPerSessionUsd = monthMeanSessionUsd(deps);
+  let spentUSD = 0;
+  for (const f of files.sort()) {
+    let body;
+    try { body = readFileSync(join(dir, f), "utf-8"); } catch { continue; }
+    const rows = [];
+    for (const line of body.split("\n")) {
+      if (!line.trim()) continue;
+      try { rows.push(JSON.parse(line)); } catch { /* skip */ }
+    }
+    const summary = summariseRows(rows);
+    spentUSD += summary.measuredUsd + imputeUnmeasured(summary, { fallbackPerSessionUsd }).imputedUsd;
+  }
+  return { spentUSD: +spentUSD.toFixed(6), days: files.length };
+}
+
+/**
+ * Read the seat's FUNDED envelope off the cached mandate body.
+ *
+ * The chain, end to end, with no invented link:
+ *   hq `Employee.payBasis.meteredBudget` (dollars/month, `ai_seat` basis)
+ *     → `loadMandateEnvelope` (× 100)
+ *     → mandate body `seatBudgetCents` + `budgetPeriod:"monthly"`
+ *     → `mandate.get` → `state/mandate/cache.json`
+ *     → HERE → `dailyAllowance` → every enforcement decision below.
+ *
+ * A null at any link travels as a null and NAMES ITSELF; nothing downstream
+ * substitutes a number for it. (The last time something did, every obligation in
+ * the fleet ran on an invented 500c allowance for months.)
+ *
+ * @returns {{ seatBudgetCents:number|null, budgetPeriod:string|null,
+ *             supervisorMemberId:string|null, source:string, reason:string|null }}
+ */
+export function readSeatEnvelope(deps) {
+  if (deps && deps.seatEnvelope !== undefined) {
+    const e = deps.seatEnvelope || {};
+    return {
+      seatBudgetCents: Number.isFinite(e.seatBudgetCents) ? e.seatBudgetCents : null,
+      budgetPeriod: e.budgetPeriod || (Number.isFinite(e.seatBudgetCents) ? "monthly" : null),
+      supervisorMemberId: e.supervisorMemberId || null,
+      source: e.source || "injected",
+      reason: e.reason || (Number.isFinite(e.seatBudgetCents) ? null : "the injected envelope carries no seatBudgetCents"),
+    };
+  }
+  const path =
+    (deps && deps.mandateCachePath) ||
+    join(agentRootOf(deps), "state", "mandate", "cache.json");
+  const miss = (reason, source = "mandate-cache") => ({
+    seatBudgetCents: null, budgetPeriod: null, supervisorMemberId: null, source, reason,
+  });
+  if (!existsSync(path)) return miss("no state/mandate/cache.json — this seat has never fetched a mandate");
+  let record;
+  try {
+    record = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (err) {
+    return miss(`state/mandate/cache.json is unreadable (${err && err.message ? err.message : err})`);
+  }
+  const body = (record && record.body) || {};
+  const supervisor =
+    (Array.isArray(body.collaborators) ? body.collaborators : []).find(
+      (c) => c && String(c.role || "").toUpperCase() === "REVIEWER" && c.memberId
+    ) || null;
+
+  if (!Number.isFinite(body.seatBudgetCents)) {
+    // Carry hq's OWN words when it published them — hq knows which link is null,
+    // and paraphrasing it here would lose the one actionable sentence.
+    const named = (Array.isArray(body.degradations) ? body.degradations : []).find(
+      (d) => d && d.field === "seatBudgetCents"
+    );
+    return {
+      seatBudgetCents: null,
+      budgetPeriod: null,
+      supervisorMemberId: supervisor ? supervisor.memberId : null,
+      source: record && record.source === "server" ? "hq" : `mandate-cache:${(record && record.source) || "unknown"}`,
+      reason: named
+        ? `hq published no envelope: ${named.reason}`
+        : record && record.source !== "server"
+          ? "the mandate cache is LOCAL (never adopted from hq), so it carries no funded envelope"
+          : "hq published seatBudgetCents:null — the seat has no funded envelope",
+    };
+  }
+  // ── PROVENANCE + STALENESS, ON THE SUCCESS PATH ───────────────────────────
+  // `record.source` was checked only in the MISS branch, and `fetchedAt` was not
+  // read at all. Both matter here, and neither is cosmetic:
+  //
+  //   provenance — a `source:"local"` cache is one the seat wrote for itself
+  //     (`lib/setup/sections/mandate.mjs` derives a local body offline). A
+  //     seatBudgetCents on such a record is the seat setting its own ceiling,
+  //     which is the ONE thing this module exists to prevent. Refuse it; the
+  //     local safety-net cap binds instead, loudly.
+  //   staleness — hq can revoke funding (`Employee.payBasis.meteredBudget` →
+  //     null) while the agent is partitioned. Without an expiry the cached
+  //     number keeps producing `funded:true` and a live daily allowance forever,
+  //     and the "employee.payBasis.meteredBudget" label is then a provenance
+  //     claim asserted rather than verified. Past the mandate cache's own
+  //     EXPIRED tier (7d, lib/mandate/cache.mjs TIERS.stale) the envelope stops
+  //     being authoritative. AGING is kept but reported.
+  const recordSource = (record && record.source) || "unknown";
+  if (recordSource !== "server") {
+    return {
+      seatBudgetCents: null,
+      budgetPeriod: null,
+      supervisorMemberId: supervisor ? supervisor.memberId : null,
+      source: `mandate-cache:${recordSource}`,
+      reason:
+        `the mandate cache carries a seatBudgetCents but its source is "${recordSource}", not "server" — ` +
+        "a locally-derived body is the SEAT's own number and may not be used as the org-funded ceiling",
+    };
+  }
+  const ageSec = envelopeAgeSeconds(record, clock(deps)());
+  if (ageSec >= ENVELOPE_EXPIRY_SEC) {
+    return {
+      seatBudgetCents: null,
+      budgetPeriod: null,
+      supervisorMemberId: supervisor ? supervisor.memberId : null,
+      source: "mandate-cache:expired",
+      reason:
+        `the cached envelope was fetched ${Math.floor(ageSec / 3600)}h ago (> ${ENVELOPE_EXPIRY_SEC / 3600}h) — ` +
+        "hq may have changed or revoked this seat's funding since, so the number is no longer authoritative. " +
+        "Run `maestro mandate sync` (or let the mandate cadence refresh it) to re-establish the ceiling.",
+    };
   }
-  return { spentUSD: +spentUSD.toFixed(6), sessions };
+
+  return {
+    seatBudgetCents: body.seatBudgetCents,
+    budgetPeriod: body.budgetPeriod || "monthly",
+    supervisorMemberId: supervisor ? supervisor.memberId : null,
+    source: body.budgetSource || "employee.payBasis.meteredBudget",
+    reason: null,
+    ageSeconds: ageSec,
+    // Kept as a DEGRADATION rather than a refusal: an envelope nobody has
+    // refreshed in a day or three is still hq's number, and refusing it would
+    // brick a seat whose only sin is a quiet mandate cadence.
+    staleReason: ageSec >= ENVELOPE_AGING_SEC
+      ? `the funded envelope was last fetched from hq ${Math.floor(ageSec / 3600)}h ago — it is still being enforced, but it expires at ${ENVELOPE_EXPIRY_SEC / 3600}h`
+      : null,
+  };
+}
+
+/** Seconds since the mandate cache was fetched; Infinity when never/unparseable. */
+function envelopeAgeSeconds(record, nowMs) {
+  const at = record && record.fetchedAt;
+  if (!at) return Infinity;
+  const then = Date.parse(String(at));
+  if (!Number.isFinite(then) || !Number.isFinite(nowMs)) return Infinity;
+  return Math.max(0, (nowMs - then) / 1000);
+}
+
+function daysInUtcMonth(ms) {
+  const d = new Date(ms);
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0)).getUTCDate();
+}
+
+/**
+ * The binding daily allowance, and how it was arrived at.
+ *
+ * The envelope is monthly dollars. Today's allowance is the REMAINING envelope
+ * spread over the REMAINING days of the month, reconciled against month-to-date
+ * actuals — an under-spent week raises today's ceiling instead of expiring.
+ *
+ * When the envelope and the local `DAILY_SPEND_CAP_USD` disagree, THE LOWER ONE
+ * BINDS and the disagreement is logged: a seat may not spend past what the org
+ * funded, and a local config file may not be used to authorise MORE than the org
+ * funded either. With no envelope at all the local cap binds and that fact is a
+ * degradation on every single read — an agent that cannot know its funding says
+ * so, loudly, rather than assuming a number.
+ */
+export function dailyAllowance(deps) {
+  const degradations = [];
+  const configuredCapUSD = cfgSpendCap(deps);
+  const env = readSeatEnvelope(deps);
+  const now = clock(deps)();
+  const daysInMonth = daysInUtcMonth(now);
+  const dayOfMonth = new Date(now).getUTCDate();
+  const mtd = monthToDate(deps);
+  const today = sumToday(deps);
+
+  if (env.seatBudgetCents == null) {
+    degradations.push(
+      `UNFUNDED SEAT: ${env.reason || "no funded envelope"} — falling back to the LOCAL cap ` +
+      `($${configuredCapUSD}/day, which this seat can edit). The org-funded ceiling is NOT being enforced.`
+    );
+    return {
+      allowanceUSD: configuredCapUSD,
+      capSource: "local-config",
+      configuredCapUSD,
+      funded: false,
+      envelope: { seatBudgetCents: null, monthUSD: null, source: env.source, supervisorMemberId: env.supervisorMemberId },
+      month: { spentUSD: mtd.spentUSD, pct: null, daysInMonth, dayOfMonth },
+      degradations,
+      disagreementUSD: null,
+    };
+  }
+
+  const monthUSD = env.seatBudgetCents / 100;
+  const remainingDays = Math.max(1, daysInMonth - dayOfMonth + 1);
+  // Month-to-date INCLUDING today would charge today's spend against today's own
+  // allowance twice, so the allowance is set from the days already closed.
+  const spentBeforeToday = Math.max(0, mtd.spentUSD - today.spentUSD);
+  const remainingUSD = monthUSD - spentBeforeToday;
+  const envelopeAllowanceUSD = remainingUSD > 0 ? remainingUSD / remainingDays : 0;
+
+  let allowanceUSD = envelopeAllowanceUSD;
+  let capSource = "seat-envelope";
+  let disagreementUSD = null;
+  if (Number.isFinite(configuredCapUSD) && configuredCapUSD > 0) {
+    disagreementUSD = +(envelopeAllowanceUSD - configuredCapUSD).toFixed(6);
+    if (configuredCapUSD < envelopeAllowanceUSD) {
+      allowanceUSD = configuredCapUSD;
+      capSource = "local-config";
+    }
+    if (Math.abs(disagreementUSD) > 0.01) {
+      degradations.push(
+        `the seat envelope allows $${envelopeAllowanceUSD.toFixed(2)} today ` +
+        `(remaining $${remainingUSD.toFixed(2)} over ${remainingDays} day(s)) but the local cap says ` +
+        `$${configuredCapUSD.toFixed(2)} — the LOWER binds ($${allowanceUSD.toFixed(2)}, ${capSource})`
+      );
+    }
+  }
+
+  return {
+    allowanceUSD: +allowanceUSD.toFixed(6),
+    capSource,
+    configuredCapUSD,
+    funded: true,
+    envelope: {
+      seatBudgetCents: env.seatBudgetCents,
+      monthUSD,
+      source: env.source,
+      supervisorMemberId: env.supervisorMemberId,
+      remainingUSD: +remainingUSD.toFixed(6),
+      remainingDays,
+      allowanceUSD: +envelopeAllowanceUSD.toFixed(6),
+    },
+    month: {
+      spentUSD: mtd.spentUSD,
+      pct: monthUSD > 0 ? +((mtd.spentUSD / monthUSD) * 100).toFixed(2) : null,
+      daysInMonth,
+      dayOfMonth,
+    },
+    degradations,
+    disagreementUSD,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -173,53 +650,233 @@ function sumToday(deps) {
 // ---------------------------------------------------------------------------
 
 /**
- * Compute the day's budget status.
+ * Compute the period's budget status and the enforcement posture it implies.
+ *
+ * The band is the WORSE of two readings, because either one alone is gameable by
+ * the calendar:
+ *   dayPct    today's spend against today's binding allowance
+ *   monthPct  month-to-date spend against the whole funded envelope
+ * A seat that blew the month on the 3rd is in the suspend band on the 4th even
+ * though "today" looks quiet; a seat with a healthy month that spikes 3x in one
+ * day still degrades today.
  *
- * @param {object} [deps] { now?, ledgerDir?, agentRoot?, capUSD?, iterationCap? }
- * @returns {{
- *   spentUSD:number, capUSD:number, pct:number, band:0|50|75|90|100,
- *   essentialOnly:boolean, sessions:number, iterationCap:number, date:string
- * }}
+ * @param {object} [deps] { now?, ledgerDir?, agentRoot?, capUSD?, iterationCap?,
+ *                          seatEnvelope?, mandateCachePath?, log? }
  */
 export function dailyStatus(deps) {
-  const capUSD = cfgSpendCap(deps);
   const iterationCap = cfgIterationCap(deps);
-  const { spentUSD, sessions } = sumToday(deps);
+  const today = sumToday(deps);
+  const { spentUSD, sessions } = today;
+  const allowance = dailyAllowance(deps);
+  const extraDegradations = [];
 
-  const spendPct = capUSD > 0 ? (spentUSD / capUSD) * 100 : 0;
+  // ── THE LATCH: a seat may not demote its own band by editing its own repo ──
+  // The module invariant is "no band self-clears by agent action", and the
+  // fingerprint half of it was true only when the ENVELOPE was already the
+  // binding cap. In the ordinary posture — a $25 local `config/recovery.yaml`
+  // cap under a larger envelope share — the local file IS the binding cap, so
+  // raising it raised the ceiling, dropped the percentage, and walked the seat
+  // out of `degraded` (measured: $28 spent, band 100 → one edit → band 80).
+  // So for BANDING we use the lowest binding cap observed this period. It resets
+  // when hq moves the envelope (an act the seat cannot perform) and at the
+  // period boundary. Lowering the local cap still tightens immediately.
+  const latched = readCapLatch(deps, allowance);
+  const capUSD = allowance.allowanceUSD;
+  const bandingCapUSD = latched.bandingCapUSD;
+  if (bandingCapUSD < capUSD - 0.005) {
+    extraDegradations.push(
+      `the binding daily cap read $${capUSD.toFixed(2)} but this period already ran under $${bandingCapUSD.toFixed(2)} ` +
+      `(${latched.source}); banding uses the LOWER — a seat cannot raise its own ceiling out of a band it is already in. ` +
+      "Only hq (Employee.payBasis.meteredBudget) can raise it."
+    );
+  }
+
+  // `null`, not 0, when there is no allowance left to divide by. Forcing this to
+  // 0 reported "0 % of today's allowance" for a seat whose envelope was fully
+  // spent — a reading that is not merely useless but backwards.
+  const spendPct = bandingCapUSD > 0
+    ? (spentUSD / bandingCapUSD) * 100
+    : spentUSD > 0 ? null : 0;
+  if (spendPct === null) {
+    extraDegradations.push(
+      `today's allowance is $0.00 (the monthly envelope is spent out) and $${spentUSD.toFixed(2)} was spent anyway — ` +
+      "the day percentage is undefined, not 0; the MONTH percentage is the binding reading"
+    );
+  }
+  const monthPct = Number.isFinite(allowance.month.pct) ? allowance.month.pct : 0;
   const iterPct = iterationCap > 0 ? (sessions / iterationCap) * 100 : 0;
-  // The binding constraint is whichever is closer to the cap.
-  const pct = Math.max(spendPct, iterPct);
-  const band = bandForPct(pct);
+  // The binding constraint is whichever is closest to (or furthest past) the cap.
+  // A null day-reading contributes nothing; the exhausted-envelope case is
+  // already ≥100 % on the month, so nothing is lost by skipping it.
+  const pct = Math.max(spendPct ?? 0, monthPct, iterPct);
+  let band = bandForPct(pct);
+
+  // ── BLIND ⇒ DEGRADE ────────────────────────────────────────────────────────
+  // `blind` (sessions ran, none measured) was computed and reported and enforced
+  // by nothing. It is now load-bearing: we do not invent a price, we lower the
+  // rung. Only when the day is TRULY unpriceable — if a month mean was available
+  // the spend was imputed from it and the ordinary band applies.
+  if (today.blind && today.unpriceable && band < BLIND_MIN_BAND) {
+    extraDegradations.push(
+      `band raised ${band}% → ${BLIND_MIN_BAND}%: ${today.unmeasuredSessions} session(s) ran today and NONE could be ` +
+      "measured or priced. An unmeasurable seat is degraded, not trusted."
+    );
+    band = BLIND_MIN_BAND;
+  }
+  const posture = postureForBand(band);
+
+  const degradations = [...today.degradations, ...allowance.degradations, ...extraDegradations];
+  // Degradations ride on the returned status AND go to the log: the daemon is
+  // usually the only thing awake when telemetry breaks, and a governor that
+  // quietly under-counts is the failure mode this module now exists to prevent.
+  if (degradations.length > 0) {
+    for (const d of degradations) {
+      try { console.warn(`[budget-guard] degraded: ${d}`); } catch { /* never throw */ }
+    }
+  }
 
   return {
     spentUSD,
     capUSD,
+    // The cap the BAND was computed against (the latch above). Equal to capUSD
+    // except when the seat raised its own local cap mid-period.
+    bandingCapUSD,
     pct: +pct.toFixed(2),
+    dayPct: spendPct === null ? null : +spendPct.toFixed(2),
+    monthPct: +monthPct.toFixed(2),
     band,
-    essentialOnly: band >= 100,
+    mode: posture.mode,
+    posture,
+    // Legacy field, kept so no caller silently loses its gate during the
+    // rollout. It now means the SUSPEND band (125 %) — the rung whose behaviour
+    // matches what `essentialOnly` always did: defer non-inbox work.
+    essentialOnly: band >= 125,
     sessions,
     iterationCap,
     date: todayUtc(deps),
+    // Where the ceiling came from. `funded:false` means hq published no envelope
+    // and the number below is the seat's own config, not the org's decision.
+    funded: allowance.funded,
+    capSource: allowance.capSource,
+    configuredCapUSD: allowance.configuredCapUSD,
+    envelope: allowance.envelope,
+    month: allowance.month,
+    supervisorMemberId: allowance.envelope.supervisorMemberId || null,
+    // Measurement provenance — a caller can tell a cheap day from a blind one.
+    measuredUSD: today.measuredUSD,
+    imputedUSD: today.imputedUSD,
+    unmeasuredSessions: today.unmeasuredSessions,
+    nonLlmRows: today.nonLlmRows,
+    blind: today.blind,
+    degradations,
   };
 }
 
 /**
- * Read the per-day notification ledger ({ notified_bands: number[] }). Never
- * throws.
+ * The lowest binding cap this period has run under, and the envelope it belongs
+ * to. See the LATCH comment in {@link dailyStatus} for why banding may not use a
+ * cap the seat just raised for itself.
+ *
+ * Stored beside the notice ledger (same UTC-date-stamped file, so it resets at
+ * the period boundary). The latch is dropped when the ENVELOPE fingerprint
+ * changes — hq raising or lowering the funded envelope is a real governance act
+ * and must take effect immediately, in both directions.
+ *
+ * Never throws; on any read/write failure the current cap is used unlatched
+ * (fail-open) and the caller sees `source:"unlatched"`.
  */
-export function readNotified(deps) {
+function readCapLatch(deps, allowance) {
+  const current = Number(allowance && allowance.allowanceUSD);
+  const envelopeFp = `${(allowance && allowance.envelope && allowance.envelope.seatBudgetCents) ?? "null"}:${(allowance && allowance.envelope && allowance.envelope.source) || "none"}`;
+  if (!Number.isFinite(current) || current <= 0) {
+    return { bandingCapUSD: Number.isFinite(current) ? current : 0, source: "unlatched" };
+  }
   const p = budgetStateFile(deps);
-  if (!existsSync(p)) return { notified_bands: [] };
+  let prior = null;
+  try {
+    if (existsSync(p)) prior = JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return { bandingCapUSD: current, source: "unlatched" };
+  }
+  const priorMin = prior && Number(prior.min_binding_cap_usd);
+  const priorFp = prior && prior.envelope_id;
+  const keep =
+    Number.isFinite(priorMin) && priorMin > 0 && priorFp === envelopeFp
+      ? Math.min(priorMin, current)
+      : current;
+
+  if (!prior || prior.min_binding_cap_usd !== keep || prior.envelope_id !== envelopeFp) {
+    writeNotified(
+      {
+        ...(prior && typeof prior === "object" ? prior : {}),
+        min_binding_cap_usd: +keep.toFixed(6),
+        envelope_id: envelopeFp,
+      },
+      deps
+    );
+  }
+  return {
+    bandingCapUSD: +keep.toFixed(6),
+    source: keep < current ? `the lowest cap seen this period under the same envelope` : "current",
+  };
+}
+
+/**
+ * Read the per-period notification ledger. Never throws.
+ *
+ * `envelope_fingerprint` is what makes "NO BAND SELF-CLEARS BY AGENT ACTION"
+ * enforceable. Notices clear only when the BINDING cap moves UP — and the seat
+ * cannot do that to itself, because the binding cap is the LOWER of the org
+ * envelope and the local config: editing the local file upward changes nothing,
+ * and editing it downward only tightens. Raising the ceiling is a supervisor /
+ * human act in hq, exactly like adoption.
+ *
+ * @param {object} [deps]
+ * @param {string} [currentFingerprint] `${capUSD}:${capSource}` for this read
+ */
+export function readNotified(deps, currentFingerprint) {
+  const p = budgetStateFile(deps);
+  if (!existsSync(p)) return { notified_bands: [], envelope_fingerprint: currentFingerprint ?? null };
   try {
     const raw = JSON.parse(readFileSync(p, "utf-8"));
     const arr = Array.isArray(raw.notified_bands) ? raw.notified_bands.filter((n) => BANDS.includes(n)) : [];
-    return { notified_bands: arr };
+    const stored = raw.envelope_fingerprint ?? null;
+    const delivery = raw.delivery && typeof raw.delivery === "object" ? raw.delivery : {};
+    // The period file ALSO carries the cap latch (`min_binding_cap_usd` /
+    // `envelope_id`). Carry those through untouched: `maybeNotify` merge-writes
+    // over whatever this returns, so dropping them here would silently reset the
+    // latch on the first notice — and the latch is what stops a seat demoting
+    // its own band.
+    const latch = {
+      ...(raw.min_binding_cap_usd !== undefined ? { min_binding_cap_usd: raw.min_binding_cap_usd } : {}),
+      ...(raw.envelope_id !== undefined ? { envelope_id: raw.envelope_id } : {}),
+    };
+    if (currentFingerprint != null && stored != null && stored !== currentFingerprint) {
+      const now = Number(String(currentFingerprint).split(":")[0]);
+      const before = Number(String(stored).split(":")[0]);
+      if (Number.isFinite(now) && Number.isFinite(before) && now > before) {
+        return { ...latch, notified_bands: [], envelope_fingerprint: currentFingerprint, cleared: "envelope-raised", delivery: {} };
+      }
+    }
+    return { ...latch, notified_bands: arr, envelope_fingerprint: stored, delivery };
   } catch {
-    return { notified_bands: [] };
+    return { notified_bands: [], envelope_fingerprint: currentFingerprint ?? null, delivery: {} };
   }
 }
 
+/**
+ * Delivery retry policy for a band notice. See {@link maybeNotify}.
+ *
+ * A band is marked notified only once the caller CONFIRMS delivery, or once we
+ * have tried `MAX_DELIVERY_ATTEMPTS` times and given up (which is logged as an
+ * error, because a rung whose whole purpose is "tell the supervisor" silently
+ * not telling anybody is the failure this subsystem exists to end).
+ */
+export const MAX_DELIVERY_ATTEMPTS = 6;
+/** Matches the cadence consumer's 5-minute escalation timer. */
+export const DELIVERY_RETRY_MS = 5 * 60_000;
+
+/** Merge-write the period state file (it carries the notice ledger AND the cap latch). */
 function writeNotified(state, deps) {
   const p = budgetStateFile(deps);
   try {
@@ -234,22 +891,52 @@ function writeNotified(state, deps) {
 }
 
 /**
- * Emit AT MOST ONE notice per band per day. If the current band is above any
- * not-yet-notified band threshold(s), returns the highest such band as the
- * notice to surface and records every crossed band as notified (so a jump
- * from 40 %→95 % notifies once at 90, not three times). When `notify` is
- * provided it is invoked with a structured payload; otherwise the caller can
- * use the return value.
- *
- * @param {object} [deps] { now?, ledgerDir?, capUSD?, notify? }
- * @returns {{ notified:boolean, band:0|50|75|90|100, status:object, message?:string }}
+ * The fingerprint notices are keyed to. THE ENVELOPE ONLY — never the binding
+ * cap.
+ *
+ * It used to be `${capUSD}:${capSource}`, which meant a seat that raised its own
+ * `config/recovery.yaml` cap moved the fingerprint upward and `readNotified`
+ * read that as "a supervisor raised the ceiling", wiping the notice ledger. The
+ * seat could then re-clear its own alarms indefinitely. `seatBudgetCents` is set
+ * in hq on the Employee record and is the one number the seat cannot write.
+ */
+function fingerprintOf(status) {
+  const cents = (status.envelope && status.envelope.seatBudgetCents) ?? null;
+  return `${cents == null ? "unfunded" : cents}:${(status.envelope && status.envelope.source) || "none"}`;
+}
+
+/**
+ * Emit AT MOST ONE notice per band per period, ADDRESSED TO THE SUPERVISOR.
+ *
+ * If the current band is above any not-yet-notified threshold(s), the highest
+ * such band is surfaced and every crossed band is recorded (so a jump from
+ * 40 %→130 % notifies once at 125, not three times).
+ *
+ * THE RECIPIENT IS NOT THE OWNER. It is the seat's REVIEWER collaborator —
+ * `WorkforceMember.supervisorId` as hq published it on the mandate body. An
+ * agent told "you are running out of money" has every incentive to optimise the
+ * meter rather than the work, and the meter is the one number it must not be
+ * able to move. When no supervisor edge exists the notice is LOGGED LOUDLY and
+ * sent NOWHERE: an unsupervised seat is a provisioning gap, not a licence to
+ * hand the agent its own budget alarm.
+ *
+ * @param {object} [deps] { now?, ledgerDir?, capUSD?, notify?, log? }
+ * @returns {{ notified:boolean, band:0|80|100|125|150, status:object,
+ *             message?:string, recipient?:{memberId:string, role:"REVIEWER"}|null }}
  */
 export function maybeNotify(deps) {
+  const log = (deps && typeof deps.log === "function")
+    ? deps.log
+    : (level, msg) => { (level === "error" ? console.error : console.warn)(`[budget-guard] ${msg}`); };
   const status = dailyStatus(deps);
   if (status.band === 0) return { notified: false, band: 0, status };
 
-  const { notified_bands } = readNotified(deps);
-  const already = new Set(notified_bands);
+  const fp = fingerprintOf(status);
+  const prior = readNotified(deps, fp);
+  const already = new Set(prior.notified_bands);
+  if (prior.cleared === "envelope-raised") {
+    log("warn", `budget notices cleared: the binding ceiling moved up to $${status.capUSD.toFixed(2)} (${status.capSource})`);
+  }
 
   // Every band threshold at or below the current band that hasn't fired yet.
   const crossed = BANDS.filter((b) => status.band >= b && !already.has(b));
@@ -257,23 +944,114 @@ export function maybeNotify(deps) {
     return { notified: false, band: status.band, status };
   }
 
-  // Mark them all notified; surface ONE notice at the highest crossed band.
+  // Surface ONE notice at the highest crossed band.
   const topBand = crossed[crossed.length - 1];
-  writeNotified({ notified_bands: [...notified_bands, ...crossed].sort((a, b) => a - b) }, deps);
+
+  // ── ATTEMPT, NOT COMPLETION ────────────────────────────────────────────────
+  // The band used to be written into `notified_bands` HERE, before anything was
+  // put on the wire — so one ECONNREFUSED (or a daemon that started before the
+  // org credential resolved) burned the rung for the whole period and the
+  // 5-minute timer then polled forever without ever retrying. The band is now
+  // recorded as an ATTEMPT with a backoff, and only `commit()` — called by the
+  // delivery leg after a successful send — marks it notified. After
+  // MAX_DELIVERY_ATTEMPTS we stop retrying and record it as UNDELIVERED, loudly:
+  // giving up quietly is the same bug wearing a hat.
+  const now = clock(deps)();
+  const track = prior.delivery && prior.delivery[String(topBand)];
+  const attempts = Number(track && track.attempts) || 0;
+  const lastAt = Number(track && track.lastAttemptMs) || 0;
+  const retryMs = Number.isFinite(deps && deps.retryMs) ? deps.retryMs : DELIVERY_RETRY_MS;
+
+  if (attempts > 0 && attempts < MAX_DELIVERY_ATTEMPTS && now - lastAt < retryMs) {
+    return {
+      notified: false,
+      band: status.band,
+      status,
+      deferred: true,
+      reason: `retry backoff: attempt ${attempts}/${MAX_DELIVERY_ATTEMPTS} was ${Math.round((now - lastAt) / 1000)}s ago`,
+    };
+  }
+
+  const persist = (patch) =>
+    writeNotified({ ...prior, envelope_fingerprint: fp, ...patch }, deps);
+
+  const markNotified = () =>
+    persist({
+      notified_bands: [...prior.notified_bands, ...crossed].sort((a, b) => a - b),
+      delivery: { ...prior.delivery, [String(topBand)]: { attempts: attempts + 1, lastAttemptMs: now, delivered: true } },
+    });
+
+  // Record the attempt immediately so a crashed process cannot spin, but do NOT
+  // consume the band.
+  const gaveUp = attempts + 1 >= MAX_DELIVERY_ATTEMPTS;
+  persist({
+    notified_bands: gaveUp
+      ? [...prior.notified_bands, ...crossed].sort((a, b) => a - b)
+      : prior.notified_bands,
+    delivery: {
+      ...prior.delivery,
+      [String(topBand)]: { attempts: attempts + 1, lastAttemptMs: now, delivered: false, gaveUp },
+    },
+  });
+  if (gaveUp) {
+    log(
+      "error",
+      `band ${topBand}% notice ABANDONED after ${MAX_DELIVERY_ATTEMPTS} delivery attempts — the supervisor was never told. ` +
+        "This is a delivery outage, not a quiet period: check the org credential and channel.resolveOrCreateDm."
+    );
+  }
 
   const message = formatNotice(topBand, status);
+  const recipient = status.supervisorMemberId
+    ? { memberId: status.supervisorMemberId, role: "REVIEWER" }
+    : null;
+  if (!recipient) {
+    log(
+      "error",
+      `band ${topBand}% reached and this seat has NO supervisor edge (the mandate body carries no REVIEWER ` +
+        `collaborator) — the notice has nowhere to go and is deliberately NOT being sent to the owner. ${message}`
+    );
+    // Nothing can be delivered, so retrying every 5 minutes forever would only
+    // spam the log. Consume the band; the missing edge is a provisioning fact
+    // doctor reports separately.
+    markNotified();
+    return { notified: true, band: topBand, status, message, recipient: null, commit: () => {}, delivered: false };
+  }
+  log("warn", `band ${topBand}% → notifying supervisor ${recipient.memberId}: ${message}`);
+
   const notifyFn = deps && typeof deps.notify === "function" ? deps.notify : null;
   if (notifyFn) {
-    try { notifyFn({ band: topBand, status, message }); } catch { /* notice is best-effort */ }
+    // An injected `notify` IS the delivery leg (tests, and any caller that wires
+    // one). A throw means it did not arrive, so the band stays uncommitted.
+    try {
+      notifyFn({ band: topBand, status, message, recipient });
+      markNotified();
+      return { notified: true, band: topBand, status, message, recipient, commit: () => {}, delivered: true };
+    } catch (err) {
+      log("error", `band ${topBand}% notice threw on delivery (${err && err.message ? err.message : err}) — NOT marking the band notified; it will be retried`);
+      return { notified: true, band: topBand, status, message, recipient, commit: markNotified, delivered: false };
+    }
   }
-  return { notified: true, band: topBand, status, message };
+
+  // No injected delivery: the caller (lib/budget-escalate.mjs) owns the wire and
+  // MUST call `commit()` once the notice is actually delivered.
+  return { notified: true, band: topBand, status, message, recipient, commit: markNotified, delivered: false, attempts: attempts + 1 };
 }
 
 function formatNotice(band, status) {
   const usd = status.spentUSD.toFixed(2);
   const cap = status.capUSD.toFixed(2);
+  const envelope = status.envelope && status.envelope.monthUSD != null
+    ? ` Seat envelope $${status.envelope.monthUSD.toFixed(2)}/month (${status.capSource}); month-to-date $${status.month.spentUSD.toFixed(2)} (${status.monthPct}%).`
+    : " NO org-funded envelope is published for this seat — only the seat's own local cap binds.";
+  if (band >= 150) {
+    return `Seat spend at ${status.pct}% of its ceiling ($${usd} / $${cap} today). REFUSING new sessions that are not a direct human reply; inbox replies continue.${envelope}`;
+  }
+  if (band >= 125) {
+    return `Seat spend at ${status.pct}% ($${usd} / $${cap} today). OUTCOME obligations SUSPENDED (budget_breach drift recorded); inline + offline-safe cadences continue.${envelope}`;
+  }
   if (band >= 100) {
-    return `Daily spend cap reached: $${usd} / $${cap} (${status.pct}%). Entering essential-only mode — inbox replies continue; backlog + scheduled work deferred until UTC midnight.`;
+    return `Seat spend at ${status.pct}% ($${usd} / $${cap} today). Degrading: cheapest model class, sub-agent fan-out capped at 1, self-directed work stopped. Inbox replies continue.${envelope}`;
   }
-  return `Daily spend at ${band}%: $${usd} / $${cap} (${status.pct}%).`;
+  return `Seat spend at ${status.pct}% ($${usd} / $${cap} today) — heads-up only, nothing is degraded yet.${envelope}`;
 }