@cohortapp/agent-sdk 2.5.1 → 2.6.1

package/lib/plan/budget-enforcement.test.mjs

@@ -0,0 +1,400 @@
+/**
+ * budget-enforcement.test.mjs — the ceiling, enforced.
+ *
+ * Covers the three places a breach actually bites:
+ *   compile.applyBudgetPosture            the plan-level suspension (125%)
+ *   compile.obligationAllowedUnderPosture  the per-tick form the daemon uses
+ *   budget-runtime.reconcileBudgetPosture  the I/O around them (drift, band edge)
+ *
+ * The invariant every one of these tests exists to protect: WE DEGRADE, WE NEVER
+ * BRICK. At every band, the inline cadences still run and the seat still answers
+ * its inbox.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { compilePlan, applyBudgetPosture, obligationAllowedUnderPosture } from "./compile.mjs";
+import { reconcileBudgetPosture, readPosture } from "./budget-runtime.mjs";
+import { postureForBand } from "../budget-guard.mjs";
+
+// ---------------------------------------------------------------------------
+// fixtures
+// ---------------------------------------------------------------------------
+
+const manifest = () => ({
+  schemaVersion: 1,
+  entries: [
+    { id: "books_reports", plane: "protocol", kind: "method", reachable: true, blastRadius: "internal" },
+    { id: "board_ready", plane: "protocol", kind: "method", reachable: true, blastRadius: "internal" },
+    { id: "messaging_send", plane: "protocol", kind: "method", reachable: true, blastRadius: "external" },
+  ],
+});
+
+/** An adopted, fully-admissible objective — the kind that compiles obligations. */
+function objective(over = {}) {
+  return {
+    id: `obj-${over.key || "a"}`,
+    key: over.key || "a",
+    kind: "OBJECTIVE",
+    state: "active",
+    text: "an adopted objective",
+    memberId: "A016",
+    parentId: null,
+    parentKey: null,
+    charterSectionId: "sec-1",
+    metric: "gross_margin",
+    unit: "pct",
+    direction: "up",
+    baseline: 10,
+    target: 40,
+    value: 12,
+    tolerance: 1,
+    weight: 1,
+    cadence: "weekly",
+    sensor: { source: "method", capability: "books_reports", params: {} },
+    budgetCentsPerPeriod: null,
+    collaborators: [],
+    adoptedById: "HUMAN-1",
+    adoptedAt: "2026-06-01T00:00:00.000Z",
+    ...over,
+  };
+}
+
+function mandate(over = {}) {
+  return {
+    contractVersion: 1,
+    memberId: "A016",
+    objectives: [],
+    proposed: [],
+    budgetCentsPerPeriod: null,
+    seatBudgetCents: null,
+    budgetPeriod: null,
+    budgetSource: "employee.payBasis.meteredBudget",
+    collaborators: [],
+    reactsTo: [],
+    degradations: [],
+    generatedAt: "2026-06-01T00:00:00.000Z",
+    ...over,
+  };
+}
+
+const STANDARD = [
+  { id: "cadence-bus-heartbeat", mode: "inline", interval: 300 },
+  { id: "inbox-processor", mode: "guarded", calendar: { hour: 9 } },
+];
+
+function fundedPlan() {
+  return compilePlan({
+    mandate: mandate({
+      objectives: [objective({ key: "gross-margin", budgetCentsPerPeriod: 60_000 })],
+      seatBudgetCents: 60_000,
+      budgetPeriod: "monthly",
+    }),
+    manifest: manifest(),
+    standardCadences: STANDARD,
+    log: () => {},
+  });
+}
+
+// ---------------------------------------------------------------------------
+// the funded envelope reaches the obligations (the PROOF this all rests on)
+// ---------------------------------------------------------------------------
+
+test("a funded envelope produces per-obligation budgets derived from it", () => {
+  const plan = compilePlan({
+    mandate: mandate({
+      objectives: [
+        objective({ key: "a", budgetCentsPerPeriod: 45_000, weight: 3 }),
+        objective({ key: "b", budgetCentsPerPeriod: 15_000, weight: 1 }),
+      ],
+      seatBudgetCents: 60_000,
+      budgetPeriod: "monthly",
+    }),
+    manifest: manifest(),
+    standardCadences: STANDARD,
+    log: () => {},
+  });
+
+  const funded = plan.obligations.filter((o) => Number.isFinite(o.budget_cents_per_period));
+  assert.ok(funded.length >= 4, "each objective yields a measure SCHEDULE + an OUTCOME, both funded");
+  assert.equal(plan.obligations.find((o) => o.key === "outcome.a").budget_cents_per_period, 45_000);
+  assert.equal(plan.obligations.find((o) => o.key === "outcome.b").budget_cents_per_period, 15_000);
+  // The apportioned shares sum to the envelope — no cents invented, none leaked.
+  const outcomes = plan.obligations.filter((o) => o.kind === "OUTCOME");
+  assert.equal(outcomes.reduce((n, o) => n + o.budget_cents_per_period, 0), 60_000);
+  assert.equal(plan.contract.unmetered, false);
+
+  // And the obligations with NO objective behind them stay honestly unmetered
+  // rather than inheriting a fiction.
+  const standard = plan.obligations.find((o) => o.key === "schedule.inbox-processor");
+  assert.equal(standard.budget_cents_per_period, null);
+});
+
+test("an UNFUNDED seat compiles unmetered and says so — it does not invent 500c", () => {
+  const warnings = [];
+  const plan = compilePlan({
+    mandate: mandate({ objectives: [objective({ key: "a" })] }),
+    manifest: manifest(),
+    standardCadences: STANDARD,
+    log: (_l, m) => warnings.push(m),
+  });
+  assert.equal(plan.contract.unmetered, true);
+  assert.ok(plan.obligations.every((o) => o.budget_cents_per_period === null));
+  assert.ok(warnings.some((w) => /no seat envelope/.test(w) && /NOT enforced/.test(w)));
+});
+
+// ---------------------------------------------------------------------------
+// applyBudgetPosture — the 125% rung
+// ---------------------------------------------------------------------------
+
+test("below 125% nothing is suspended", () => {
+  const plan = fundedPlan();
+  for (const band of [0, 80, 100]) {
+    const r = applyBudgetPosture(plan, postureForBand(band));
+    assert.deepEqual(r.suspended, [], `band ${band} must not suspend obligations`);
+    assert.equal(r.drift.length, 0);
+  }
+});
+
+test("at 125% the objective's obligations suspend — and NOTHING else does", () => {
+  const plan = fundedPlan();
+  const r = applyBudgetPosture(plan, postureForBand(125), { spentUSD: 41, capUSD: 30 });
+
+  assert.ok(r.suspended.includes("outcome.gross-margin"));
+  assert.ok(r.suspended.includes("schedule.measure.gross-margin"),
+    "the measure cadence spends on the same warrant as its OUTCOME");
+
+  // The seat's own life-support is untouched at every band.
+  const heartbeat = r.obligations.find((o) => o.key === "schedule.cadence-bus-heartbeat");
+  assert.equal(heartbeat.status, "active", "an inline cadence costs nothing and must never be suspended");
+  // The trap this asserts against: OUTCOME rows are `offline_safe:true`, so an
+  // exemption keyed on that flag suspends nothing at all.
+  assert.equal(r.obligations.find((o) => o.key === "outcome.gross-margin").offline_safe, true);
+  assert.equal(r.obligations.find((o) => o.key === "outcome.gross-margin").status, "suspended");
+  const inbox = r.obligations.find((o) => o.key === "schedule.inbox-processor");
+  assert.equal(inbox.status, "active", "the seat keeps answering its inbox — Invariant #1");
+  for (const react of r.obligations.filter((o) => o.kind === "REACT")) {
+    assert.equal(react.status, "active", "REACT obligations are how a human reaches this seat");
+  }
+
+  // One drift row per suspended obligation, carrying the evidence.
+  assert.equal(r.drift.length, r.suspended.length);
+  for (const d of r.drift) {
+    assert.equal(d.kind, "budget_breach");
+    assert.equal(d.detail.band, 125);
+    assert.equal(d.detail.spentUSD, 41);
+    assert.equal(d.detail.capUSD, 30);
+  }
+});
+
+test("applyBudgetPosture is idempotent and does not mutate its input", () => {
+  const plan = fundedPlan();
+  const before = JSON.stringify(plan.obligations);
+  const once = applyBudgetPosture(plan, postureForBand(125));
+  const twice = applyBudgetPosture({ obligations: once.obligations }, postureForBand(125));
+  assert.equal(JSON.stringify(plan.obligations), before, "the compiled plan is not mutated");
+  assert.deepEqual(twice.suspended, [], "an already-suspended obligation is not re-suspended, nor re-drifted");
+  assert.equal(twice.drift.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// obligationAllowedUnderPosture — the per-tick form the daemon uses
+// ---------------------------------------------------------------------------
+
+test("the daemon's per-tick gate agrees with the plan-level transition", () => {
+  const outcomeCadence = { kind: "SCHEDULE", scope: "mandate", objective_id: "obj-a", offline_safe: false, mode: "guarded" };
+  const heartbeat = { kind: "SCHEDULE", scope: "standard", objective_id: null, offline_safe: true, mode: "inline" };
+  const standard = { kind: "SCHEDULE", scope: "standard", objective_id: null, offline_safe: false, mode: "guarded" };
+
+  assert.equal(obligationAllowedUnderPosture(outcomeCadence, postureForBand(100)).allowed, true);
+  assert.equal(obligationAllowedUnderPosture(outcomeCadence, postureForBand(125)).allowed, false);
+  assert.match(obligationAllowedUnderPosture(outcomeCadence, postureForBand(125)).reason, /suspended/);
+
+  // Life support, at the worst band there is.
+  assert.equal(obligationAllowedUnderPosture(heartbeat, postureForBand(150)).allowed, true);
+
+  // >150%: a plain standard cadence is a spawn that is not a human reply.
+  assert.equal(obligationAllowedUnderPosture(standard, postureForBand(125)).allowed, true);
+  assert.equal(obligationAllowedUnderPosture(standard, postureForBand(150)).allowed, false);
+  assert.match(obligationAllowedUnderPosture(standard, postureForBand(150)).reason, /not a direct human reply/);
+});
+
+// ---------------------------------------------------------------------------
+// reconcileBudgetPosture — drift on the band EDGE, plan file untouched
+// ---------------------------------------------------------------------------
+
+async function tmpRoot() {
+  const dir = join(tmpdir(), `budget-runtime-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(join(dir, "state", "plan"), { recursive: true });
+  return dir;
+}
+
+test("reconcile records budget_breach drift once per band edge, not once per tick", async () => {
+  const root = await tmpRoot();
+  try {
+    const plan = fundedPlan();
+    const drift = [];
+    const deps = { plan, appendDrift: (row) => { drift.push(row); return true; }, log: () => {} };
+
+    const first = await reconcileBudgetPosture({ agentRoot: root, posture: postureForBand(125), status: { spentUSD: 41, capUSD: 30, pct: 137 } }, deps);
+    assert.ok(first.suspended.length >= 2);
+    assert.equal(first.recorded, first.suspended.length);
+    assert.equal(readPosture(root).band, 125, "the acted-on band is persisted");
+
+    const again = await reconcileBudgetPosture({ agentRoot: root, posture: postureForBand(125), status: {} }, deps);
+    assert.equal(again.recorded, 0, "same band, same tick-after-tick: no new rows");
+    assert.equal(drift.length, first.recorded);
+
+    // Coming back DOWN is an edge too — a human who saw the suspension needs the
+    // clearing edge as well.
+    const down = await reconcileBudgetPosture({ agentRoot: root, posture: postureForBand(0), status: {} }, deps);
+    assert.equal(down.suspended.length, 0);
+    assert.equal(readPosture(root).band, 0);
+  } finally { await fsp.rm(root, { recursive: true, force: true }); }
+});
+
+test("a breach is mirrored to hq, and the clearing edge resolves it there", async () => {
+  const root = await tmpRoot();
+  try {
+    const plan = fundedPlan();
+    const mirrored = [];
+    const deps = {
+      plan,
+      appendDrift: () => true,
+      log: () => {},
+      mirrorDrift: async (row) => { mirrored.push(row); return { ok: true }; },
+    };
+
+    const up = await reconcileBudgetPosture({ agentRoot: root, posture: postureForBand(125), status: { spentUSD: 41, capUSD: 30 } }, deps);
+    assert.equal(up.mirrored, up.drift.length);
+    assert.ok(mirrored.every((m) => m.kind === "budget_breach" && !m.resolve));
+
+    // Back under the ceiling: the open rows are RESOLVED at hq, or the org shows
+    // a permanently-breached seat that has in fact recovered.
+    mirrored.length = 0;
+    const down = await reconcileBudgetPosture({ agentRoot: root, posture: postureForBand(0), status: {} }, deps);
+    assert.equal(down.suspended.length, 0);
+    assert.ok(mirrored.length > 0, "the clearing edge is reported too");
+    assert.ok(mirrored.every((m) => m.resolve === true));
+  } finally { await fsp.rm(root, { recursive: true, force: true }); }
+});
+
+test("an hq that rejects or throws never blocks the LOCAL suspension", async () => {
+  const root = await tmpRoot();
+  try {
+    const plan = fundedPlan();
+    const logged = [];
+    const local = [];
+    const r = await reconcileBudgetPosture(
+      { agentRoot: root, posture: postureForBand(125), status: {} },
+      {
+        plan,
+        appendDrift: (row) => { local.push(row); return true; },
+        log: (l, m) => logged.push(`${l}:${m}`),
+        mirrorDrift: async () => { throw new Error("hq unreachable"); },
+      }
+    );
+    assert.ok(r.suspended.length > 0, "the obligations are still suspended");
+    assert.equal(r.recorded, local.length, "and the local record is complete");
+    assert.equal(r.mirrored, 0);
+    assert.ok(logged.some((l) => /could not mirror/.test(l)), "the mirror failure is named, not swallowed");
+  } finally { await fsp.rm(root, { recursive: true, force: true }); }
+});
+
+test("a seat with no compiled plan reconciles cleanly instead of throwing", async () => {
+  const root = await tmpRoot();
+  try {
+    const logged = [];
+    const r = await reconcileBudgetPosture(
+      { agentRoot: root, posture: postureForBand(150), status: {} },
+      { log: (l, m) => logged.push(`${l}:${m}`) }
+    );
+    assert.equal(r.ok, true);
+    assert.deepEqual(r.suspended, []);
+    assert.match(r.reason, /config\/plan\.yaml is absent/);
+    assert.ok(logged.some((l) => /no plan to suspend/.test(l)), "and it says so rather than passing silently");
+  } finally { await fsp.rm(root, { recursive: true, force: true }); }
+});
+
+// ---------------------------------------------------------------------------
+// BAND 150 MUST NOT SILENCE THE INBOX
+// ---------------------------------------------------------------------------
+
+test("band 150 defers discretionary cadences but NEVER the human lane", () => {
+  // The 150% rung was implemented as `kind !== "REACT"`, and every cadence the
+  // consumer evaluates is a SCHEDULE — so `inbox-processor` and
+  // `messaging-inbound` (the only puller of org DMs and @mentions) were deferred
+  // too. It only looked harmless because both guards default to
+  // `decision:"inline"` and return before the gate; set INBOX_CADENCE_ESCALATE=1
+  // or MESSAGING_INBOUND_ESCALATE=1 — the documented cadence-only mode — and the
+  // seat stopped reading its inbox at a budget breach. That is the bricking
+  // Invariant #1 forbids.
+  const posture = postureForBand(150);
+  assert.equal(posture.refuseNonHumanSpawn, true);
+
+  const inbox = { key: "schedule.inbox-processor", kind: "SCHEDULE", mode: "guarded", human_lane: true, status: "active" };
+  const inbound = { key: "schedule.messaging-inbound", kind: "SCHEDULE", mode: "guarded", human_lane: true, status: "active" };
+  const backlog = { key: "schedule.backlog-executor", kind: "SCHEDULE", mode: "guarded", human_lane: false, status: "active" };
+  const react = { key: "react.task.assigned", kind: "REACT", mode: "escalate", status: "active" };
+
+  assert.equal(obligationAllowedUnderPosture(inbox, posture).allowed, true, "the seat keeps reading its inbox");
+  assert.equal(obligationAllowedUnderPosture(inbound, posture).allowed, true, "and keeps PULLING messages into it");
+  assert.equal(obligationAllowedUnderPosture(react, posture).allowed, true);
+  assert.equal(obligationAllowedUnderPosture(backlog, posture).allowed, false, "discretionary work does defer");
+  assert.match(obligationAllowedUnderPosture(backlog, posture).reason, /not a direct human reply/);
+});
+
+test("the compiler STAMPS the human lane on the plan, so an operator can read it", () => {
+  // Inferring the lane at enforcement time would leave the plan on disk silent
+  // about which obligations a breach may never stop.
+  const plan = compilePlan({
+    mandate: {},
+    manifest: { entries: [] },
+    standardCadences: [
+      { id: "inbox-processor", scope: "standard", mode: "guarded", interval: 300 },
+      { id: "messaging-inbound", scope: "standard", mode: "guarded", interval: 45 },
+      { id: "backlog-executor", scope: "standard", mode: "guarded", interval: 600 },
+      { id: "dynamic-jobs", scope: "standard", mode: "guarded", interval: 60 },
+    ],
+    log: () => {},
+  });
+  const laneOf = (id) => plan.obligations.find((o) => o.key === `schedule.${id}`).human_lane;
+  assert.equal(laneOf("inbox-processor"), true);
+  assert.equal(laneOf("messaging-inbound"), true);
+  assert.equal(laneOf("backlog-executor"), false);
+  assert.equal(laneOf("dynamic-jobs"), false, "the agent's own reminders are not somebody waiting on a reply");
+});
+
+test("STRUCTURAL: the drift return-leg runs on the MONEY clock, not the daily one", async () => {
+  // `reconcileBudgetPosture` had exactly one caller: `guardGoalSteward`, which
+  // `lib/cadences.mjs` schedules at 07:15 DAILY — while the band it reads resets
+  // at UTC midnight. A seat could hit 150% every afternoon for a month and hq
+  // would never see one `budget_breach` drift row, because by the next 07:15 the
+  // band it observed was 0 again. Local enforcement was fine (`governanceGate`
+  // re-reads per tick); it was the RECORD — the thing the person who funds the
+  // seat looks at — that never arrived.
+  const { readFileSync } = await import("node:fs");
+  const { fileURLToPath } = await import("node:url");
+  const root = fileURLToPath(new URL("../../", import.meta.url));
+
+  const consumer = readFileSync(`${root}scripts/daemon/cadence-consumer.mjs`, "utf-8");
+  assert.match(consumer, /reconcileBudgetPosture/, "the consumer reconciles the posture itself");
+
+  // It must live inside the escalation timer (the 5-minute one), not in a
+  // calendar-scheduled handler.
+  const timerAt = consumer.indexOf("const escalateTimer");
+  const reconcileAt = consumer.indexOf("reconcileBudgetPosture", timerAt);
+  const timerEndsAt = consumer.indexOf("}, budgetEscalateMs)", timerAt);
+  assert.ok(timerAt > 0 && reconcileAt > timerAt && reconcileAt < timerEndsAt,
+    "the reconcile is inside the budgetEscalateMs timer");
+  assert.match(consumer, /DEFAULT_BUDGET_ESCALATE_MS = 5 \* 60_000/, "and that timer is 5 minutes");
+
+  // The daily caller stays — it is idempotent and harmless — but it is no longer
+  // the only one.
+  const handlers = readFileSync(`${root}scripts/daemon/cadence-handlers.mjs`, "utf-8");
+  assert.match(handlers, /reconcileBudgetPosture/);
+});

package/lib/plan/budget-runtime.mjs

@@ -0,0 +1,215 @@
+/**
+ * lib/plan/budget-runtime.mjs — the 125 % rung, applied to the plan on disk.
+ *
+ * `compilePlan` suspends an objective whose apportioned share does not fit the
+ * seat envelope, but that is a PLAN-TIME judgement made once against the
+ * mandate's arithmetic. It cannot see what the seat has actually spent since.
+ * `applyBudgetPosture` (lib/plan/compile.mjs) is the same transition made at
+ * RUNTIME against the ledger — this module is the I/O around it:
+ *
+ *   config/plan.yaml  +  lib/budget-guard.dailyStatus().posture
+ *     → which obligations are suspended RIGHT NOW
+ *     → one `budget_breach` drift row each, in state/plan/drift.jsonl
+ *     → state/plan/budget-posture.json (the band we last acted on)
+ *
+ * WHY THE PLAN FILE IS NOT REWRITTEN. A breach is a transient fact about a
+ * ledger; the plan is a durable fact about a mandate. Emitting a suspended plan
+ * would drop the cadence from `config/cadences.yaml` and unload its launchd job,
+ * and the next recompile at a healthy band would have to put it back — a seat
+ * whose schedule flaps with its spend. So the compiled plan stays the plan, and
+ * the EFFECTIVE plan is `plan ⊕ posture`, computed on every read. The daemon
+ * enforces the same rule per-tick through
+ * `compile.obligationAllowedUnderPosture`, so the file and the daemon can never
+ * disagree about what is suspended.
+ *
+ * WHY DRIFT IS RECORDED ON BAND CHANGE ONLY. A drift row per obligation per tick
+ * would bury the signal in its own noise (the same reason `mandate.reportDrift`
+ * dedupes open rows server-side). We record when the band MOVES — including when
+ * it moves back down, which is the "resolved" edge a human needs to see.
+ *
+ * Never throws. Every degradation is returned AND logged: a governance step that
+ * fails quietly is the failure mode this whole subsystem exists to end.
+ *
+ * @module lib/plan/budget-runtime
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { applyBudgetPosture } from "./compile.mjs";
+import { writeJsonAtomic, appendJsonl } from "../fs-atomic.mjs";
+
+/** Where the last-acted-on band is remembered (git-ignored runtime state). */
+export const POSTURE_REL = join("state", "plan", "budget-posture.json");
+/** The same drift log `lib/execution/effects.writeDrift` appends to. */
+export const DRIFT_REL = join("state", "plan", "drift.jsonl");
+const PLAN_REL = join("config", "plan.yaml");
+
+function rootOf(agentRoot) {
+  return resolve(agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+}
+
+/** Read the compiled plan. Never throws; a missing plan is a legitimate state. */
+async function readPlan(agentRoot, deps = {}) {
+  if (deps.plan) return { plan: deps.plan, reason: null };
+  const p = join(rootOf(agentRoot), PLAN_REL);
+  if (!existsSync(p)) return { plan: null, reason: "config/plan.yaml is absent — nothing is compiled yet" };
+  let yaml = deps.yaml || null;
+  if (!yaml) {
+    try { yaml = (await import("js-yaml")).default; }
+    catch (err) { return { plan: null, reason: `js-yaml unavailable: ${err && err.message ? err.message : err}` }; }
+  }
+  try {
+    const doc = yaml.load(readFileSync(p, "utf-8"));
+    if (!doc || typeof doc !== "object") return { plan: null, reason: "config/plan.yaml did not parse to an object" };
+    return { plan: doc, reason: null };
+  } catch (err) {
+    return { plan: null, reason: `config/plan.yaml is unreadable: ${err && err.message ? err.message : err}` };
+  }
+}
+
+/** The band this seat last recorded drift for. Never throws. */
+export function readPosture(agentRoot, deps = {}) {
+  const p = join(rootOf(agentRoot), POSTURE_REL);
+  if (deps.posturePath === null) return { band: null, at: null };
+  if (!existsSync(p)) return { band: null, at: null };
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf-8"));
+    return { band: Number.isFinite(raw.band) ? raw.band : null, at: raw.at || null, suspended: raw.suspended || [] };
+  } catch {
+    return { band: null, at: null };
+  }
+}
+
+/**
+ * Reconcile the compiled plan against the live budget posture.
+ *
+ * @param {object} o
+ *   @param {string} o.agentRoot
+ *   @param {object} o.posture   `lib/budget-guard.postureForBand()` output
+ *   @param {object} [o.status]  the full `dailyStatus()` (folded into drift detail)
+ * @param {object} [deps] { plan?, yaml?, now?, log?, write?, appendDrift?, mirrorDrift? }
+ *   mirrorDrift — async ({kind,key,detail,resolve?}) => frame. Wired to
+ *   `mandate.reportDrift` in production so the org sees the suspension; omit it
+ *   and the record stays local (and says so).
+ * @returns {Promise<{ok:boolean, suspended:string[], drift:object[], recorded:number,
+ *                    mirrored:number, band:number, previousBand:number|null, reason:string|null}>}
+ */
+export async function reconcileBudgetPosture(o = {}, deps = {}) {
+  const agentRoot = rootOf(o.agentRoot);
+  const posture = o.posture || {};
+  const status = o.status || {};
+  const log = typeof deps.log === "function" ? deps.log : (level, msg) => {
+    (level === "error" ? console.error : console.warn)(`[budget-runtime] ${msg}`);
+  };
+  const nowMs = typeof deps.now === "function" ? deps.now() : Date.now();
+  const band = Number.isFinite(posture.band) ? posture.band : 0;
+  const previous = readPosture(agentRoot, deps);
+  const empty = { ok: true, suspended: [], drift: [], recorded: 0, mirrored: 0, band, previousBand: previous.band, reason: null };
+
+  const { plan, reason } = await readPlan(agentRoot, deps);
+  if (!plan) {
+    // Not an error: a seat with no adopted mandate legitimately has no plan.
+    if (band > 0) log("warn", `band ${band}% but no plan to suspend — ${reason}`);
+    return { ...empty, reason };
+  }
+
+  const applied = applyBudgetPosture(plan, posture, {
+    spentUSD: Number.isFinite(status.spentUSD) ? status.spentUSD : null,
+    capUSD: Number.isFinite(status.capUSD) ? status.capUSD : null,
+    pct: Number.isFinite(status.pct) ? status.pct : null,
+    capSource: status.capSource || null,
+    seatBudgetCents: (status.envelope && status.envelope.seatBudgetCents) ?? null,
+  });
+
+  // Nothing to say unless the band MOVED. Includes the downward edge: a human
+  // who saw "12 obligations suspended" needs to see them come back.
+  if (previous.band === band) {
+    return { ...empty, suspended: applied.suspended, drift: [] };
+  }
+
+  const append = deps.appendDrift || ((row) => appendJsonl(join(agentRoot, DRIFT_REL), row));
+  let recorded = 0;
+  for (const d of applied.drift) {
+    const ok = append({
+      at: new Date(nowMs).toISOString(),
+      kind: d.kind,
+      key: d.key,
+      detail: d.detail,
+      source: "budget-guard",
+    });
+    if (ok !== false) recorded += 1;
+  }
+
+  // MIRROR TO hq. A suspension that only exists in a jsonl file on one laptop is
+  // invisible to the person who funds the seat — and funding is the only thing
+  // that clears it. `mandate.reportDrift` dedupes an open row per
+  // (memberId, kind, key) server-side, so re-reporting is safe and the row stays
+  // current instead of going stale. Best-effort by construction: the local
+  // record is written FIRST, so an unreachable hq loses nothing.
+  let mirrored = 0;
+  if (typeof deps.mirrorDrift === "function") {
+    for (const d of applied.drift) {
+      try {
+        const res = await deps.mirrorDrift({ kind: d.kind, key: d.key, detail: d.detail });
+        if (res && res.ok === false) {
+          log("warn", `hq rejected the ${d.kind} drift for ${d.key}: ${(res.error && res.error.code) || "unknown"} — the local record stands`);
+        } else {
+          mirrored += 1;
+        }
+      } catch (err) {
+        log("warn", `could not mirror the ${d.kind} drift for ${d.key} to hq (${err && err.message ? err.message : err}) — the local record stands`);
+      }
+    }
+    // Clearing edge: the seat came back under the ceiling, so the open rows are
+    // resolved. Without this, hq shows a permanently-breached seat that has in
+    // fact recovered, and the drift list stops being worth reading.
+    if (applied.drift.length === 0 && (previous.suspended || []).length > 0) {
+      for (const key of previous.suspended) {
+        try { await deps.mirrorDrift({ kind: "budget_breach", key, detail: { band }, resolve: true }); }
+        catch (err) { log("warn", `could not resolve the budget_breach drift for ${key} at hq (${err && err.message ? err.message : err})`); }
+      }
+    }
+  }
+
+  if (applied.suspended.length > 0) {
+    log(
+      "warn",
+      `band ${previous.band ?? 0}% → ${band}%: SUSPENDING ${applied.suspended.length} obligation(s) ` +
+        `(${applied.suspended.slice(0, 5).join(", ")}${applied.suspended.length > 5 ? ", …" : ""}) — ` +
+        "inline + offline-safe cadences continue, and the seat keeps answering its inbox"
+    );
+  } else if ((previous.band ?? 0) >= 125 && band < 125) {
+    log("warn", `band ${previous.band}% → ${band}%: obligations are no longer suspended for budget`);
+  }
+
+  const write = deps.write || ((path, value) => writeJsonAtomic(path, value));
+  try {
+    write(join(agentRoot, POSTURE_REL), {
+      band,
+      mode: posture.mode || null,
+      at: new Date(nowMs).toISOString(),
+      suspended: applied.suspended,
+      spentUSD: status.spentUSD ?? null,
+      capUSD: status.capUSD ?? null,
+      capSource: status.capSource ?? null,
+    });
+  } catch (err) {
+    log("error", `could not persist the budget posture (${err && err.message ? err.message : err}) — the next tick will re-record this band's drift`);
+  }
+
+  return {
+    ok: true,
+    suspended: applied.suspended,
+    drift: applied.drift,
+    recorded,
+    mirrored,
+    band,
+    previousBand: previous.band,
+    reason: null,
+  };
+}
+
+export default { reconcileBudgetPosture, readPosture, POSTURE_REL, DRIFT_REL };