@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/lib/plan/compile.mjs

@@ -17,6 +17,9 @@
  *      + ALTITUDE_CADENCES             → SCHEDULE, origin "archetype"
  *   3. each ADOPTED objective w/ sensor → SCHEDULE `schedule.measure.<key>`
  *                                        + OUTCOME `outcome.<key>`
+ *                                        "adopted" means `state:"active"` AND
+ *                                        adopted by somebody other than the
+ *                                        owner — see rule 3 below
  *   4. each adopted objective with a
  *      REVIEWER collaborator           → SCHEDULE `schedule.review.<key>`
  *   5. mandate `reactsTo[]` + the four
@@ -41,9 +44,18 @@
 import { createHash } from "node:crypto";
 import { canonical } from "../mandate/cache.mjs";
 import { assertMandateContract } from "../mandate/contract.mjs";
+import { adoptedObjectives, adoptionDefect, memberIdOf, validateMandateBody } from "../mandate/model.mjs";
+import { isHumanLaneCadence } from "../cadences.mjs";
 
-/** Bump when emission rules change — it is part of `inputsHash`. */
-export const COMPILER_VERSION = 1;
+/**
+ * Bump when emission rules change — it is part of `inputsHash`.
+ *
+ * 2: adopted objectives are now filtered through `mandate/model.adoptedObjectives`
+ *    (the client-side half of the anti-Goodhart law) instead of a bare
+ *    `state === "active"` check, so a self-adopted or structurally-invalid node
+ *    compiles nothing and surfaces as drift.
+ */
+export const COMPILER_VERSION = 2;
 
 /** Read primitives every session-spawning obligation may use. */
 export const BASELINE_TOOLS = Object.freeze(["Read", "Grep", "Glob", "LS"]);
@@ -320,6 +332,10 @@ export function compilePlan(input = {}) {
       uses,
       budget_cents_per_period: defaultBudget,
       offline_safe: c.mode === "inline",
+      // The human-reply lane — see isHumanLaneObligation. Stamped here (not
+      // inferred at enforcement time) so the plan on disk SAYS which obligations
+      // a budget breach may never stop, and an operator can read it.
+      human_lane: isHumanLaneCadence(c.id),
       status: "active",
     });
   }
@@ -351,8 +367,43 @@ export function compilePlan(input = {}) {
   }
 
   // ── 3/4. adopted objectives → measure + outcome (+ review) ──────────────
-  const adopted = (Array.isArray(mandate.objectives) ? mandate.objectives : [])
-    .filter((o) => o && o.state === "active" && o.kind !== "PILLAR");
+  // THE ANTI-GOODHART LAW, CLIENT SIDE. This used to be `state === "active"` and
+  // nothing else — which meant the compiler trusted the snapshot's state column
+  // and NOTHING about who put it there. hq now refuses self-adoption and
+  // peer-adoption at the handler, but the compiler is the offline half of the
+  // same law: an agent that is partitioned, replaying a cached body, or handed a
+  // hand-edited state file must not compile a graded OUTCOME obligation from a
+  // number it adopted for itself. `adoptedObjectives` drops self-adopted and
+  // structurally-invalid nodes; `validateMandateBody` says why, out loud.
+  const owner = memberIdOf(mandate) || input.memberId || null;
+  const validation = validateMandateBody(mandate, { ownerMemberId: owner });
+  for (const err of validation.errors) note("error", `[compilePlan] mandate: ${err}`);
+  for (const w of validation.warnings) note("warn", `[compilePlan] mandate: ${w}`);
+  const adopted = adoptedObjectives(mandate, {
+    ownerMemberId: owner,
+    badKeys: validation.badKeys,
+  }).filter((o) => o.kind !== "PILLAR");
+  // Named separately so a REFUSAL is never indistinguishable from an absence:
+  // "you have 4 active objectives and I compiled 0" is a bug report, and it has
+  // to be legible from the plan alone.
+  for (const o of (Array.isArray(mandate.objectives) ? mandate.objectives : [])) {
+    if (!o || o.state !== "active" || o.kind === "PILLAR") continue;
+    if (adopted.includes(o)) continue;
+    const defect = adoptionDefect(o, owner);
+    const reason =
+      defect === "self_adopted"
+        ? `adoptedById equals the owning seat (${owner}) \u2014 a seat cannot define, measure and be graded on the same number`
+        : defect === "missing_adoption_provenance"
+          ? "the objective is active but carries NO adoptedById \u2014 nobody is on record as having handed this seat the number, so it cannot drive graded work (a deleted field is the cheapest tamper there is, and it used to fail open)"
+          : "the objective did not validate; see plan warnings";
+    drift.push({
+      kind: defect || "invalid_objective",
+      key: o.key ? `outcome.${o.key}` : null,
+      detail: { objectiveKey: o.key || null, reason },
+    });
+    note("error",
+      `[compilePlan] objective "${o.key || "?"}" is active but compiles NOTHING: ${reason}`);
+  }
   const proposedCount = (Array.isArray(mandate.objectives) ? mandate.objectives : []).filter((o) => o && o.state === "proposed").length;
 
   // Budget envelope: highest-weight objectives get the envelope first; the rest
@@ -544,6 +595,150 @@ export function compilePlan(input = {}) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// The RUNTIME budget transition
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply a live budget posture to an already-compiled plan.
+ *
+ * `compilePlan` already suspends an objective whose apportioned share does not
+ * fit the seat envelope — but that is a PLAN-TIME decision made once, against
+ * the mandate's arithmetic. It cannot see what the seat actually spent since.
+ * This is the same transition made at RUNTIME, against the ledger, so the 125 %
+ * rung of the ladder ("suspend the obligations, not the seat") is real rather
+ * than a sentence in a design doc.
+ *
+ * WHAT IT SUSPENDS: obligations that exist because of an adopted objective —
+ * `OUTCOME` rows and the `measure`/`review` SCHEDULEs that serve them (they carry
+ * `objective_id`). Those are the seat's discretionary, funded work.
+ *
+ * WHAT IT NEVER SUSPENDS, at any band:
+ *   - `mode:"inline"` obligations. They are deterministic local computation with
+ *     no model call — they cost nothing, so suspending them buys nothing and
+ *     stops the seat's heartbeat.
+ *   - standard cadences and REACTs with no objective behind them — the seat's
+ *     inbox and its ability to answer a human.
+ * Invariant #1: we degrade, we never brick.
+ *
+ * `offline_safe` IS NOT AN EXEMPTION, and the trap is worth naming: the compiler
+ * marks every OUTCOME and every `schedule.measure.*` as `offline_safe:true`
+ * (they can run without the network), so treating that flag as "free" exempts
+ * precisely the obligations this rung exists to suspend — the ceiling compiles,
+ * fires, and suspends nothing. Offline-safe means "does not need hq"; it says
+ * nothing about whether the work spends money.
+ *
+ * PURE and idempotent: applying the same posture twice yields the same plan and
+ * the same single drift row per obligation. Never throws — a governance bug must
+ * not be able to wedge a plan.
+ *
+ * @param {object} plan     a `compilePlan` result (or `{obligations}`)
+ * @param {object} posture  `lib/budget-guard.postureForBand()` output
+ * @param {object} [detail] extra fields folded into each drift record (spend, cap…)
+ * @returns {{obligations:object[], drift:object[], suspended:string[], counts:object}}
+ */
+export function applyBudgetPosture(plan, posture, detail = {}) {
+  const obligations = Array.isArray(plan && plan.obligations) ? plan.obligations : Array.isArray(plan) ? plan : [];
+  const drift = [];
+  const suspended = [];
+  const suspend = !!(posture && posture.suspendOutcomeObligations);
+
+  const out = obligations.map((ob) => {
+    if (!ob || typeof ob !== "object") return ob;
+    if (!suspend) return ob;
+    if (ob.status !== "active") return ob; // already suspended at plan time
+    if (ob.mode === "inline") return ob;   // deterministic, zero-cost, load-bearing
+    // "Because of an adopted objective" is the test — not the obligation kind.
+    // A `schedule.measure.*` costs the seat money on the same warrant its
+    // OUTCOME does, and leaving it running would keep spending while the thing
+    // it measures is suspended.
+    const fromObjective = ob.kind === "OUTCOME" || (ob.objective_id != null && ob.scope === "mandate");
+    if (!fromObjective) return ob;
+
+    suspended.push(ob.key);
+    drift.push({
+      kind: "budget_breach",
+      key: ob.key,
+      detail: {
+        reason: "runtime spend breached the seat envelope",
+        band: posture.band,
+        mode: posture.mode,
+        objective_id: ob.objective_id || null,
+        budget_cents_per_period: Number.isFinite(ob.budget_cents_per_period) ? ob.budget_cents_per_period : null,
+        ...detail,
+      },
+    });
+    return { ...ob, status: "suspended", suspended_by: "budget", suspended_band: posture.band };
+  });
+
+  return {
+    obligations: out,
+    drift,
+    suspended,
+    counts: {
+      total: out.length,
+      suspended: out.filter((o) => o && o.status === "suspended").length,
+      active: out.filter((o) => o && o.status === "active").length,
+    },
+  };
+}
+
+/**
+ * May THIS obligation run right now, under this posture?
+ *
+ * The single-obligation form of {@link applyBudgetPosture}, for the hot path:
+ * the cadence consumer holds a registry entry, not a plan. Same rule, same
+ * exemptions, so the daemon and the plan can never disagree about what is
+ * suspended.
+ *
+ * @param {{kind?:string, scope?:string, objective_id?:string|null,
+ *          mode?:string, status?:string}} ob
+ * @param {object} posture
+ * @returns {{allowed:boolean, reason:string}}
+ */
+export function obligationAllowedUnderPosture(ob = {}, posture = {}) {
+  if (ob.status && ob.status !== "active") {
+    return { allowed: false, reason: `obligation status is ${ob.status}` };
+  }
+  // Only INLINE work is unconditionally free. `offline_safe` is not an
+  // exemption — see applyBudgetPosture; every OUTCOME carries it.
+  if (ob.mode === "inline") {
+    return { allowed: true, reason: "inline work is deterministic and costs nothing — it continues at every band" };
+  }
+  if (posture.refuseNonHumanSpawn && !isHumanLaneObligation(ob)) {
+    return {
+      allowed: false,
+      reason: `budget band ${posture.band}% — refusing spawns that are not a direct human reply`,
+    };
+  }
+  const fromObjective = ob.kind === "OUTCOME" || (ob.objective_id != null && ob.scope === "mandate");
+  if (posture.suspendOutcomeObligations && fromObjective) {
+    return { allowed: false, reason: `budget band ${posture.band}% — OUTCOME obligations are suspended` };
+  }
+  return { allowed: true, reason: "within the seat envelope" };
+}
+
+/**
+ * Is a human waiting on the other end of this obligation?
+ *
+ * The 150 % rung refuses "anything that is not a direct human reply", and that
+ * predicate used to be `kind === "REACT"`. Every cadence the consumer evaluates
+ * is a SCHEDULE, so at band 150 the gate blocked `inbox-processor` and
+ * `messaging-inbound` — the cadence that pulls org DMs and @mentions into the
+ * inbox pipeline at all. A budget rung that stops the seat reading its inbox is
+ * precisely the bricking Invariant #1 forbids, so the lane is now explicit:
+ *
+ *   REACT              — fires on an org event somebody else caused. Human-facing
+ *                        by construction (an assignment, an approval request, a DM).
+ *   human_lane:true    — stamped by the compiler from lib/cadences.HUMAN_LANE_CADENCES.
+ *
+ * Kept as a positive allow-list rather than a deny-list: a new cadence added
+ * next quarter defaults to "deferrable under a breach", which is the safe side.
+ */
+export function isHumanLaneObligation(ob = {}) {
+  return ob.human_lane === true || ob.kind === "REACT";
+}
+
 /** The identity-bearing projection an obligationsHash is taken over. */
 function identityOf(ob) {
   return {
@@ -583,5 +778,6 @@ function usesForArchetypeCadence(c, reachable) {
 
 export default {
   COMPILER_VERSION, BASELINE_TOOLS, STANDARD_CADENCE_USES, STANDARD_REACTS,
-  compilePlan, solveSlot, busyWindows, allowedToolsFor, actionClassesFor, toolNameFor, rankOf,
+  compilePlan, applyBudgetPosture, obligationAllowedUnderPosture, isHumanLaneObligation,
+  solveSlot, busyWindows, allowedToolsFor, actionClassesFor, toolNameFor, rankOf,
 };

package/lib/plan/compile.test.mjs

@@ -42,7 +42,10 @@ function objective(over = {}) {
     key: "pipeline-coverage", kind: "OBJECTIVE", text: "Pipeline coverage", state: "active",
     metric: "pipeline_coverage_x", unit: "x", direction: "up", target: 3, tolerance: 0.2,
     weight: 1, cadence: "weekly", sensor: { capability: "crm_list_deals", params: { stage: "open" }, source: "method" },
-    collaborators: [], id: "obj_7Kx", charterSectionId: "cs_12", ...over,
+    // `adoptedById` is part of the fixture because it is part of the LAW: an
+    // active objective with no adopter on record compiles nothing (see
+    // lib/mandate/model.adoptionDefect). It must differ from the body's memberId.
+    collaborators: [], id: "obj_7Kx", charterSectionId: "cs_12", adoptedById: "M-SUPERVISOR", ...over,
   };
 }
 
@@ -314,14 +317,23 @@ test("deriveMandate: charter pillars become PILLARs, KPI categories become OBJEC
       { kind: "PILLAR", order: 0, body: "1) Own the agent-platform substrate — runtime, memory, tools." },
       { kind: "PILLAR", order: 1, body: "2) Make the fleet governable: every capability observable." },
     ],
-    kpiCategories: [{ id: "execution", name: "Execution & Follow-Through", examples: ["Commitment-closure rate"] }],
+    kpiCategories: [
+      { id: "execution", name: "Fleet execution & follow-through", examples: ["Commitment-closure rate"] },
+      // Overlaps neither pillar's words. It is CARRIED but left unplaced —
+      // the old deriver silently parented it onto pillar #1.
+      { id: "warehouse-latency", name: "Warehouse latency", examples: ["p95 ms"] },
+    ],
     manifest: manifest(),
   });
   assert.equal(d.counts.pillars, 2);
-  assert.equal(d.counts.objectives, 1);
+  assert.equal(d.counts.objectives, 2);
   const exec = d.objectives.find((o) => o.key === "execution");
   assert.equal(exec.kind, "OBJECTIVE");
-  assert.ok(exec.parentKey, "every objective hangs off a pillar (provenance)");
+  assert.ok(exec.parentKey, "every PLACEABLE objective hangs off a pillar (provenance)");
+  assert.ok(exec.charterSectionId !== undefined);
+  const orphan = d.objectives.find((o) => o.key === "warehouse-latency");
+  assert.equal(orphan.parentKey, null, "no fabricated pillar edge");
+  assert.ok(d.degradations.some((x) => x.kind === "no_pillar_trace" && x.key === "warehouse-latency"));
   assert.equal(exec.state, "proposed", "NOTHING is adopted by the agent");
   assert.equal(exec.sensor.source, "method");
   assert.equal(exec.sensor.capability, "board_ready", "bound to a REACHABLE capability");
@@ -359,7 +371,9 @@ test("end to end: derive → compile produces a plan whose obligations trace bac
     manifest: manifest(),
   });
   // Simulate the human adoption step in hq.
-  const adopted = d.objectives.map((o) => (o.kind === "OBJECTIVE" ? { ...o, state: "active", target: 0.95, id: `obj_${o.key}` } : o));
+  // Simulating hq's adopt handler means simulating ALL of it — including the
+  // `adoptedById` column it stamps. Without one the compiler refuses the row.
+  const adopted = d.objectives.map((o) => (o.kind === "OBJECTIVE" ? { ...o, state: "active", target: 0.95, id: `obj_${o.key}`, adoptedById: "M-SUPERVISOR" } : o));
   const p = compilePlan({ mandate: toMandateBody({ objectives: adopted }), manifest: manifest(), standardCadences: STANDARD });
   const outcome = p.obligations.find((o) => o.kind === "OUTCOME");
   assert.ok(outcome, "adoption turns the proposal into a real obligation");

package/lib/plan/emit.mjs

@@ -95,6 +95,14 @@ export function toRegistry(obligations) {
       guardModule: ob.guard_module || null,
       budgetCents: Number.isFinite(ob.budget_cents_per_period) ? ob.budget_cents_per_period : null,
       obligationKey: ob.key,
+      // The three fields the RUNTIME budget gate needs (see
+      // `lib/plan/compile.obligationAllowedUnderPosture`). The consumer holds a
+      // registry entry, not a plan, and without these it could not tell a
+      // funded objective's cadence from the seat's heartbeat — so a budget
+      // breach either suspended everything or nothing.
+      scope: ob.scope || "mandate",
+      objectiveId: ob.objective_id || null,
+      offlineSafe: ob.offline_safe === true,
     };
   }
   return reg;

package/lib/plan/emit.test.mjs

@@ -42,6 +42,7 @@ const ARCHETYPE = [
 function adoptedObjective() {
   return {
     key: "pipeline-coverage", kind: "OBJECTIVE", text: "Pipeline coverage", state: "active", id: "obj_7Kx",
+    adoptedById: "M-SUPERVISOR",
     metric: "pipeline_coverage_x", direction: "up", target: 3, tolerance: 0.2, weight: 1, cadence: "weekly",
     sensor: { capability: "crm_list_deals", params: { stage: "open" }, source: "method" }, collaborators: [],
   };
@@ -184,6 +185,23 @@ test("SUSPENDED obligations are in plan.yaml but never in the schedule artefacts
   assert.deepEqual(toTsvLines(obs), ["b|60|"]);
 });
 
+test("the registry carries the provenance the RUNTIME budget gate needs", () => {
+  const obs = [
+    { key: "schedule.measure.gm", kind: "SCHEDULE", cadence_id: "measure-gm", scope: "mandate", objective_id: "obj_7Kx", mode: "guarded", prompt: "p.md", schedule: { interval: 60 }, status: "active", uses: [], allowed_tools: ["Read"], action_classes: [], offline_safe: true, source: { origin: "mandate", ref: "gm" }, budget_cents_per_period: 100 },
+    { key: "schedule.cadence-bus-heartbeat", kind: "SCHEDULE", cadence_id: "cadence-bus-heartbeat", scope: "standard", mode: "inline", prompt: "p.md", schedule: { interval: 300 }, status: "active", uses: [], allowed_tools: [], action_classes: [], offline_safe: false, source: { origin: "standard", ref: "cadence-bus-heartbeat" }, budget_cents_per_period: null },
+  ];
+  const reg = toRegistry(obs);
+  // Without these three the consumer cannot tell a funded objective's cadence
+  // from the seat's own heartbeat, so a budget breach would suspend either
+  // everything or nothing.
+  assert.equal(reg["measure-gm"].scope, "mandate");
+  assert.equal(reg["measure-gm"].objectiveId, "obj_7Kx");
+  assert.equal(reg["measure-gm"].offlineSafe, true);
+  assert.equal(reg["cadence-bus-heartbeat"].scope, "standard");
+  assert.equal(reg["cadence-bus-heartbeat"].objectiveId, null);
+  assert.equal(reg["cadence-bus-heartbeat"].offlineSafe, false);
+});
+
 // ---------------------------------------------------------------------------
 // The no-op guard (SPEC §6.4: "if obligationsHash is unchanged, nothing on disk
 // moves"). config/plan.yaml is TRACKED, so a recompile that changes nothing must

package/lib/resource-governor.mjs

@@ -29,9 +29,13 @@
  *   liveRSS + 750MB > 0.60*totalmem                    → QUEUE
  *   else                                               → ADMIT
  *
- * Plus a budget `mode`: when essential-only (budget at 100%),
- * source==="backlog"/"cadence" → DEFER; inbox → still goes through the normal
- * ADMIT/QUEUE path (never go dark on the user).
+ * Plus the budget ladder (`mode`, from `lib/budget-guard.dailyStatus().mode`),
+ * banded against the seat's hq-funded envelope rather than a local config cap:
+ *   degraded  (≥100%)  source==="backlog"            → DEFER (D3 stops)
+ *   suspended (≥125%)  source==="backlog"|"cadence"  → DEFER
+ *   refused   (>150%)  anything that is not a direct human reply → DEFER
+ * Inbox always goes through the normal ADMIT/QUEUE path — never go dark on the
+ * user — and no band ever hard-refuses: DEFER leaves the work on disk.
  *
  * Purity: `admit` is a pure function of its injected `deps` snapshot. The
  * default `deps` reads real os.* + a 2s-cached `liveClaudeStats()` (via ps) +
@@ -256,13 +260,33 @@ const ADMIT = "ADMIT";
 const QUEUE = "QUEUE";
 const DEFER = "DEFER";
 
+/**
+ * Normalise a budget mode onto the governance ladder.
+ *
+ * `lib/budget-guard.dailyStatus().mode` is the authority; the legacy
+ * `"essential-only"` string (and the `essentialOnly:true` flag) map onto
+ * `"suspended"`, which is exactly what that mode always did — defer non-inbox
+ * work, keep answering the human. Anything unrecognised is `"normal"`: an
+ * unknown mode must not silently become a stricter one.
+ */
+function budgetModeOf(req) {
+  const raw = String(req.mode || (req.essentialOnly ? "essential-only" : "") || "").toLowerCase();
+  if (raw === "refused") return "refused";
+  if (raw === "suspended" || raw === "essential-only") return "suspended";
+  if (raw === "degraded") return "degraded";
+  return "normal";
+}
+
 /**
  * The admission decision.
  *
- * @param {object} req                 { source, priority, mode }
- *   source:   "inbox" | "backlog" | "cadence"  (default "backlog")
- *   priority: "critical"|"high"|"normal"|"low" (default "normal")
- *   mode:     "essential-only" flips budget gating (else normal)
+ * @param {object} req                 { source, priority, mode, humanReply }
+ *   source:     "inbox" | "backlog" | "cadence"  (default "backlog")
+ *   priority:   "critical"|"high"|"normal"|"low" (default "normal")
+ *   mode:       budget posture — "normal" | "degraded" | "suspended" | "refused"
+ *               (legacy "essential-only" ≡ "suspended")
+ *   humanReply: this spawn is a direct reply to a human. Only `source:"inbox"`
+ *               work qualifies by default; pass it explicitly to be certain.
  * @param {object} [deps]              injected snapshot; defaults to defaultDeps()
  *   { freemem, totalmem, loadavg, cpus, liveClaude:{count,rssMB}, throttleCeiling }
  * @returns {{ decision:"ADMIT"|"QUEUE"|"DEFER", reason:string, snapshot:object }}
@@ -270,7 +294,11 @@ const DEFER = "DEFER";
 export function admit(req = {}, deps) {
   const d = deps || defaultDeps();
   const source = req.source || "backlog";
-  const mode = req.mode || (req.essentialOnly ? "essential-only" : null);
+  const budgetMode = budgetModeOf(req);
+  const mode = budgetMode === "normal" ? null : budgetMode;
+  // A direct human reply is the ONE thing no budget band may stop. Invariant #1:
+  // we degrade, we never go dark on the user.
+  const humanReply = req.humanReply === true || source === "inbox";
 
   const totalmem = numField(d.totalmem, os.totalmem());
   const freemem = numField(d.freemem, os.freemem());
@@ -300,10 +328,28 @@ export function admit(req = {}, deps) {
 
   const decide = (decision, reason) => ({ decision, reason, snapshot });
 
-  // (0) Budget essential-only: non-inbox work is deferred entirely. Inbox
-  //     falls through to the normal pressure gating below (we keep replying).
-  if (mode === "essential-only" && (source === "backlog" || source === "cadence")) {
-    return decide(DEFER, "essential-only: daily budget cap reached; deferring non-inbox work");
+  // (0) THE BUDGET LADDER. Three rungs, and none of them is a seat-level refuse:
+  //
+  //     refused  (>150% of the funded envelope) — DEFER everything that is not a
+  //              direct human reply. This is the "REFUSE, at spawn level only"
+  //              rung: the work stays on disk and the sweep retries it, the seat
+  //              keeps talking to its human. A hard refuse here would brick the
+  //              seat, which Invariant #1 forbids.
+  //     suspended (≥125%) — DEFER backlog + cadence work; inbox falls through.
+  //              (This is what the legacy "essential-only" mode always did.)
+  //     degraded  (≥100%) — self-directed BACKLOG work stops, but obligations
+  //              (cadences) keep running on the cheapest model class. The rung
+  //              that used to be missing entirely: enforcement was binary.
+  //
+  //     Inbox work always falls through to the normal pressure gating below.
+  if (mode === "refused" && !humanReply) {
+    return decide(DEFER, `budget refused (>150% of the seat envelope): deferring ${source} work; direct human replies continue`);
+  }
+  if (mode === "suspended" && (source === "backlog" || source === "cadence")) {
+    return decide(DEFER, "budget suspended (>=125% of the seat envelope): deferring non-inbox work");
+  }
+  if (mode === "degraded" && source === "backlog") {
+    return decide(DEFER, "budget degraded (>=100% of the seat envelope): self-directed backlog work stopped; obligations + inbox continue");
   }
 
   // (1) Concurrency ceiling → QUEUE (work re-derivable from the queue).

package/lib/resource-governor.test.mjs

@@ -172,9 +172,11 @@ test("admit: load exactly at the threshold is still ADMIT (strict >)", () => {
 // ---------------------------------------------------------------------------
 
 test("essential-only: backlog → DEFER without burning resources", () => {
+  // The legacy mode name still maps onto the SUSPENDED rung — same behaviour it
+  // always had, so no caller loses its gate during the rollout.
   const r = admit({ source: "backlog", mode: "essential-only" }, deps());
   assert.equal(r.decision, DECISIONS.DEFER);
-  assert.match(r.reason, /essential-only/);
+  assert.match(r.reason, /budget suspended/);
 });
 
 test("essential-only: cadence → DEFER", () => {
@@ -280,3 +282,41 @@ test("admit reads a real throttle.json from agentRoot and clamps", async () => {
     assert.equal(r.decision, DECISIONS.QUEUE);
   } finally { await fsp.rm(dir, { recursive: true, force: true }); }
 });
+
+// ---------------------------------------------------------------------------
+// the budget ladder (banded against the seat's hq-funded envelope)
+// ---------------------------------------------------------------------------
+
+test("degraded (>=100%): self-directed backlog stops, obligations + inbox continue", () => {
+  assert.equal(admit({ source: "backlog", mode: "degraded" }, deps()).decision, "DEFER");
+  assert.match(admit({ source: "backlog", mode: "degraded" }, deps()).reason, /self-directed backlog work stopped/);
+  assert.equal(admit({ source: "cadence", mode: "degraded" }, deps()).decision, "ADMIT",
+    "an obligation is not discretionary — it degrades, it does not stop");
+  assert.equal(admit({ source: "inbox", mode: "degraded" }, deps()).decision, "ADMIT");
+});
+
+test("suspended (>=125%): backlog + cadence DEFER, inbox continues", () => {
+  assert.equal(admit({ source: "backlog", mode: "suspended" }, deps()).decision, "DEFER");
+  assert.equal(admit({ source: "cadence", mode: "suspended" }, deps()).decision, "DEFER");
+  assert.equal(admit({ source: "inbox", mode: "suspended" }, deps()).decision, "ADMIT");
+});
+
+test("refused (>150%): everything that is not a human reply DEFERs — and it DEFERs, never refuses", () => {
+  for (const source of ["backlog", "cadence", "sweep"]) {
+    const r = admit({ source, mode: "refused" }, deps());
+    assert.equal(r.decision, "DEFER", `${source} must defer`);
+    assert.match(r.reason, /direct human replies continue/);
+  }
+  // The one thing no band may stop.
+  assert.equal(admit({ source: "inbox", mode: "refused" }, deps()).decision, "ADMIT");
+  assert.equal(admit({ source: "cadence", mode: "refused", humanReply: true }, deps()).decision, "ADMIT",
+    "an explicit human reply is admitted whatever its source");
+  // DEFER leaves the work on disk for the sweep; nothing is dropped, and the
+  // seat is never bricked (Invariant #1).
+  assert.notEqual(admit({ source: "backlog", mode: "refused" }, deps()).decision, "REFUSE");
+});
+
+test("an unrecognised budget mode is treated as normal, never as something stricter", () => {
+  assert.equal(admit({ source: "backlog", mode: "catastrophic" }, deps()).decision, "ADMIT");
+  assert.equal(admit({ source: "backlog", mode: "normal" }, deps()).decision, "ADMIT");
+});

package/lib/security/audit-engine.mjs

@@ -36,6 +36,7 @@
 import * as nodeFs from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
+import { resolveBackupPlan } from "../backup/policy.mjs";
 
 // Severity ordering — used to decide which unsuppressed failures fail the run
 // and to sort the summary. `info` never fails a run on its own.
@@ -316,27 +317,63 @@ export const CHECKS = [
   {
     id: "backup-configured",
     severity: "medium",
-    title: "Off-machine backup is configured and enabled",
+    title: "Disaster-recovery backup is configured and enabled",
+    // ASKS THE DR CODE, rather than re-deriving "configured" from regexes.
+    //
+    // The regex form false-greened on two configs the DR code itself calls
+    // broken, because both patterns were anchored with `^\s*` under /m:
+    //   - `bucket: ""` — the value THIS PROJECT SHIPS in its own default config
+    //     — satisfied /^\s*bucket:\s*\S/m, because `\S` matches the quote
+    //     character. The audit reported "off-machine tier set" while
+    //     resolveBackupPlan reported offsiteConfigured:false and the runner
+    //     logged "offsite is NOT configured".
+    //   - top-level `enabled: false` with a nested `local.enabled: true` passed
+    //     /^\s*enabled:\s*true/m on the INDENTED key, so the audit was green on
+    //     a machine where backup-run.mjs refuses to run and doctor FAILs.
+    // Three subsystems, three answers, one file. lib/backup/policy.mjs is the
+    // single source of truth by design; this check now uses it. It costs one
+    // js-yaml import, which the module already ships as a dependency.
     run(agentRoot, deps) {
       const { fs } = resolveDeps(deps);
-      const cfg = safeRead(fs, join(agentRoot, ".maestro/backup-config.yaml"));
-      if (!cfg) {
+      const plan = resolveBackupPlan({ agentRoot, fs });
+      if (!plan.present) {
         return {
           ok: false,
           detail: "no .maestro/backup-config.yaml — a dead Mac mini loses all audit/cost history (G6/G16)",
-          fix: "configure off-machine backup (scripts/maintenance/backup-to-cloud.sh) and set enabled: true",
+          fix: "maestro init backup-replication --apply (writes the default: nightly local restore points, no credentials needed)",
           fixable: false,
         };
       }
-      if (!/enabled:\s*true/.test(cfg)) {
+      if (!plan.readable) {
         return {
           ok: false,
-          detail: "backup config present but enabled: false",
-          fix: "set enabled: true in .maestro/backup-config.yaml and schedule the backup job",
+          detail: ".maestro/backup-config.yaml is present but unparseable — the nightly backup cannot run",
+          fix: "fix the YAML, or delete it and re-run: maestro init backup-replication --apply",
           fixable: false,
         };
       }
-      return { ok: true, detail: "off-machine backup configured (enabled: true)" };
+      if (!plan.enabled) {
+        return {
+          ok: false,
+          detail: "backup config present but enabled is not true — backup-run.mjs REFUSES to run",
+          fix: "set enabled: true in .maestro/backup-config.yaml",
+          fixable: false,
+        };
+      }
+      if (!plan.include.length) {
+        return {
+          ok: false,
+          detail: `backup enabled but every include path was rejected (${plan.violations.map((v) => `${v.path} → ${v.pattern}`).join(", ") || "empty include list"}) — the archive would be empty`,
+          fix: "restore the include list (state, knowledge, memory, outputs, config, .maestro)",
+          fixable: false,
+        };
+      }
+      return {
+        ok: true,
+        detail: plan.tier === "offsite"
+          ? `DR backup configured, off-machine tier set (${plan.offsite.provider}://${plan.offsite.bucket})`
+          : "DR backup configured — LOCAL restore points only; no off-machine copy (set offsite.provider + offsite.bucket)",
+      };
     },
   },
 

package/lib/security/audit-engine.test.mjs

@@ -211,6 +211,41 @@ test("runAudit: backup not configured is a failure", async () => {
   } finally { cleanup(root); }
 });
 
+test("runAudit: backup — an EMPTY bucket is not an off-machine tier", async () => {
+  // The regex form matched /^\s*bucket:\s*\S/m against `bucket: ""` — `\S` hits
+  // the quote character — and that is the value THIS PROJECT SHIPS in its own
+  // default config. The audit said "off-machine tier set" while
+  // resolveBackupPlan said offsiteConfigured:false and the runner logged
+  // "offsite is NOT configured": three subsystems, three answers, one file.
+  const root = makeGoodAgent();
+  try {
+    writeFileSync(
+      join(root, ".maestro/backup-config.yaml"),
+      "enabled: true\nprefix: acme\nlocal:\n  enabled: true\noffsite:\n  provider: gcs\n  bucket: \"\"\n"
+    );
+    const r = await runAudit(root, { env: { MAESTRO_SCOPED_PERMISSIONS: "1" } });
+    const b = r.results.find((x) => x.id === "backup-configured");
+    assert.equal(b.ok, true, "local restore points are a real posture");
+    assert.match(b.detail, /LOCAL restore points only/, "but it must not claim off-machine");
+  } finally { cleanup(root); }
+});
+
+test("runAudit: backup — top-level `enabled: false` is a FAILURE even with a nested local.enabled: true", async () => {
+  // `^\s*` under /m matched the INDENTED key, so the audit passed on a machine
+  // where backup-run.mjs refuses to run and doctor FAILs.
+  const root = makeGoodAgent();
+  try {
+    writeFileSync(
+      join(root, ".maestro/backup-config.yaml"),
+      "enabled: false\nprefix: acme\nlocal:\n  enabled: true\n"
+    );
+    const r = await runAudit(root, { env: { MAESTRO_SCOPED_PERMISSIONS: "1" } });
+    const b = r.results.find((x) => x.id === "backup-configured");
+    assert.equal(b.ok, false);
+    assert.match(b.detail, /REFUSES to run/);
+  } finally { cleanup(root); }
+});
+
 test("runAudit: a check that throws becomes an ok:false posture row, not a crash", async () => {
   const root = makeGoodAgent();
   try {