@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/scripts/daemon/cadence-consumer-governance.test.mjs

@@ -18,6 +18,9 @@ import { join, dirname } from "node:path";
 
 import { enqueueTick, busDepth, listInbox, getBusPaths } from "../../lib/cadence-bus.mjs";
 import { startConsumer } from "./cadence-consumer.mjs";
+import { obligationAllowedUnderPosture } from "../../lib/plan/compile.mjs";
+import { postureForBand } from "../../lib/budget-guard.mjs";
+import { isHumanLaneCadence } from "../../lib/cadences.mjs";
 
 async function makeAgentRoot() {
   const path = join(tmpdir(), `consumer-gov-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
@@ -218,3 +221,56 @@ test("L2: a 429 sub-session failure does NOT trip the per-cadence circuit", asyn
     assert.ok(stats.retries >= 1, "the tick was requeued");
   } finally { await consumer.stop(); await rmRoot(root); }
 });
+
+test("band 150 does not silence the inbox at EITHER gate", async () => {
+  // Two gates sit between a cadence tick and a spawn, and the 150% rung has to
+  // agree with itself across both:
+  //   1. `obligationAllowedUnderPosture` — was `kind !== "REACT"`, so every
+  //      cadence (all SCHEDULEs) was refused, including `messaging-inbound`, the
+  //      only puller of org DMs into the inbox pipeline.
+  //   2. `resource-governor.admit` — treats only `source:"inbox"` as a human
+  //      reply, and every cadence tick arrives as `source:"cadence"`, so fixing
+  //      gate 1 alone just moves the silence one hop down.
+  const posture = postureForBand(150);
+  const gov = await import("../../lib/resource-governor.mjs");
+  // An IDLE, roomy machine, injected. `defaultDeps` reads real freemem/loadavg/
+  // live-process counts, so asserting against it makes the test a measure of
+  // whatever else is running — this test is about the BUDGET rung, nothing else.
+  const deps = {
+    totalmem: 64 * 1024 ** 3,
+    freemem: 48 * 1024 ** 3,
+    cpus: 10,
+    loadavg: [0.1],
+    liveClaude: { count: 0, rssMB: 0 },
+    throttleCeiling: Infinity,
+  };
+
+  for (const id of ["inbox-processor", "messaging-inbound"]) {
+    assert.equal(
+      obligationAllowedUnderPosture(
+        { kind: "SCHEDULE", mode: "guarded", status: "active", human_lane: isHumanLaneCadence(id) },
+        posture
+      ).allowed,
+      true,
+      `${id} passes the obligation gate`
+    );
+    assert.notEqual(
+      gov.admit({ source: "cadence", mode: posture.mode, humanReply: isHumanLaneCadence(id) }, deps).decision,
+      "DEFER",
+      `${id} is not deferred by the spawn governor either`
+    );
+  }
+
+  // And discretionary cadences ARE still deferred, at both gates.
+  assert.equal(
+    obligationAllowedUnderPosture(
+      { kind: "SCHEDULE", mode: "guarded", status: "active", human_lane: isHumanLaneCadence("backlog-executor") },
+      posture
+    ).allowed,
+    false
+  );
+  assert.equal(
+    gov.admit({ source: "cadence", mode: posture.mode, humanReply: isHumanLaneCadence("backlog-executor") }, deps).decision,
+    "DEFER"
+  );
+});

package/scripts/daemon/cadence-consumer.mjs

@@ -36,6 +36,8 @@
  *   pollMs         drain interval (default 2_000).
  *   heartbeatMs    health.json refresh interval (default 15_000).
  *   recoveryMs     stale-claim sweep interval (default 5 * 60_000).
+ *   budgetEscalateMs  how often to check whether a budget-band notice is due
+ *                  for the SUPERVISOR (default 5 * 60_000; 0 disables).
  *   spawnSession   injected spawner for tests; defaults to a real
  *                  `claude --print <permission-args> <prompt>` child_process
  *                  .spawn. <permission-args> comes from
@@ -70,6 +72,8 @@ import {
 } from "../../lib/cadence-bus.mjs";
 import { resolveClaudeBin as sharedResolveClaude, augmentedPath, daemonClaudeArgs } from "../../lib/claude-bin.mjs";
 import { getCadenceDef } from "./cadence-handlers.mjs";
+import { obligationAllowedUnderPosture } from "../../lib/plan/compile.mjs";
+import { isHumanLaneCadence } from "../../lib/cadences.mjs";
 import { sessionPermissionArgs } from "../../lib/session-permissions.mjs";
 import { renderTemplate, buildContext } from "../../lib/render.mjs";
 // Model router (opt-in). A `schema_version: 2` config routes each cadence
@@ -104,6 +108,7 @@ const RATE_PROVIDER = process.env.MAESTRO_RATE_PROVIDER || "anthropic";
 const DEFAULT_POLL_MS = 2_000;
 const DEFAULT_HEARTBEAT_MS = 15_000;
 const DEFAULT_RECOVERY_MS = 5 * 60_000;
+const DEFAULT_BUDGET_ESCALATE_MS = 5 * 60_000;
 const DEFAULT_SPAWN_TIMEOUT_MS = 30 * 60_000;
 
 // Concurrency: at most one sub-session at a time per cadence consumer.
@@ -196,6 +201,10 @@ export function parseUsageFromStdout(stdoutPath) {
   const out = { ok: true, inputTokens, outputTokens };
   const cacheRead = Number(usage.cache_read_input_tokens);
   if (Number.isFinite(cacheRead)) out.cacheReadTokens = cacheRead;
+  // Cache CREATION tokens bill at 1.25x input; dropping them was a large slice
+  // of the gap between the local estimate and the CLI's authoritative cost.
+  const cacheWrite = Number(usage.cache_creation_input_tokens);
+  if (Number.isFinite(cacheWrite)) out.cacheWriteTokens = cacheWrite;
   const totalCost = Number(obj.total_cost_usd);
   if (Number.isFinite(totalCost) && totalCost >= 0) out.totalCostUsd = totalCost;
   // The CLI may report the resolved model (e.g. "claude-sonnet-4-6"); map it to
@@ -244,7 +253,8 @@ export function routeCadenceSpawn(agentRoot, cadence) {
     let band = 0;
     try {
       const st = budgetGuardForBand.dailyStatus({ agentRoot });
-      band = budgetLadder(st.spentUSD, st.capUSD).band;
+      // The governor's band, not a re-derivation — see dispatcher.currentBudgetBand.
+      band = budgetLadder(st.spentUSD, st.capUSD, { band: st.band }).band;
     } catch { /* band 0 on read failure */ }
     const req = {
       agent_role: "cadence",
@@ -465,11 +475,15 @@ function realSpawnSession({ agentRoot, cadence, promptPath, timeoutMs, log }) {
             trackerArgs.push("--input-tokens", String(usage.inputTokens));
             trackerArgs.push("--output-tokens", String(usage.outputTokens));
             if (usage.cacheReadTokens != null) trackerArgs.push("--cache-read-tokens", String(usage.cacheReadTokens));
+            if (usage.cacheWriteTokens != null) trackerArgs.push("--cache-creation-tokens", String(usage.cacheWriteTokens));
             if (usage.totalCostUsd != null) trackerArgs.push("--total-cost-usd", String(usage.totalCostUsd));
           } else {
-            // Parse failure: do NOT pass fabricated zeros — omit token flags
-            // (tracker defaults them to 0) and surface the gap in the bus log so
-            // a systematic parse regression is visible rather than silently $0.
+            // Parse failure: record the session as EXPLICITLY UNMEASURED. Omitting
+            // the token flags used to leave the tracker defaulting them to 0, so a
+            // systematic parse regression read as a run of free sessions and the
+            // budget governor went quiet exactly when telemetry broke. The row now
+            // says "unknown", and the bus log names the parse failure.
+            trackerArgs.push("--tokens-unknown", String(usage.reason || "usage-parse-failed"));
             log({ level: "warn", stage: "cost_usage_parse_failed", cadence, reason: usage.reason, stdout: stdoutPath });
           }
           spawn(process.execPath, trackerArgs, { stdio: "ignore", env: { ...env, AGENT_ROOT: agentRoot } }).unref();
@@ -519,6 +533,10 @@ export function startConsumer(opts = {}) {
   const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
   const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
   const recoveryMs = opts.recoveryMs ?? DEFAULT_RECOVERY_MS;
+  // How often the seat checks whether a budget band notice is due for its
+  // supervisor. 0 disables it (tests, and any deployment that delivers budget
+  // notices out of band).
+  const budgetEscalateMs = opts.budgetEscalateMs ?? DEFAULT_BUDGET_ESCALATE_MS;
   const maxSpawnMs = opts.maxSpawnMs ?? DEFAULT_SPAWN_TIMEOUT_MS;
   const spawnSession = opts.spawnSession || realSpawnSession;
   const userLogger = opts.logger;
@@ -538,14 +556,55 @@ export function startConsumer(opts = {}) {
    * any throw → admit (Invariant: a governance bug must not wedge cadences).
    * Returns { admit:boolean, reason }.
    */
-  function governanceGate() {
+  function governanceGate(cadence) {
     try {
       const rb = rateGuard.checkRateLimit(RATE_PROVIDER, { agentRoot });
       if (!rb.allowed) return { admit: false, reason: "rate-limited" };
       let mode = null;
-      try { if (budgetGuard.dailyStatus({ agentRoot }).essentialOnly) mode = "essential-only"; }
-      catch { /* budget read best-effort */ }
-      const adm = governor.admit({ source: "cadence", mode }, governor.defaultDeps({ agentRoot }));
+      let posture = null;
+      try {
+        const st = budgetGuard.dailyStatus({ agentRoot });
+        posture = st.posture;
+        if (st.mode && st.mode !== "normal") mode = st.mode;
+      } catch { /* budget read best-effort */ }
+
+      // THE 125% RUNG, PER OBLIGATION. `applyBudgetPosture` makes this transition
+      // on a whole plan; this is its single-obligation form on the hot path, so a
+      // breach suspends the OUTCOME work it is supposed to suspend and leaves the
+      // inline/offline-safe cadences that keep the seat alive running. Same
+      // predicate both places — the daemon and the plan cannot disagree about
+      // what is suspended.
+      if (posture && cadence) {
+        const def = getCadenceDef(cadence) || {};
+        const verdict = obligationAllowedUnderPosture(
+          {
+            kind: "SCHEDULE",
+            scope: def.scope || null,
+            objective_id: def.objectiveId || null,
+            offline_safe: def.offlineSafe === true,
+            // THE HUMAN LANE. Without this every cadence reaching the gate is a
+            // bare SCHEDULE, so the 150% rung ("refuse anything that is not a
+            // direct human reply") deferred `inbox-processor` and
+            // `messaging-inbound` too — the seat stopped reading its inbox at a
+            // budget breach, which is the bricking Invariant #1 forbids.
+            human_lane: isHumanLaneCadence(cadence),
+            mode: def.mode,
+          },
+          posture
+        );
+        if (!verdict.allowed) return { admit: false, reason: verdict.reason };
+      }
+
+      // THE HUMAN LANE, ONE LAYER DOWN. The obligation gate above lets
+      // `inbox-processor` and `messaging-inbound` through at band 150, and the
+      // governor would then DEFER them anyway — it treats only `source:"inbox"`
+      // as a human reply, and every cadence tick arrives as `source:"cadence"`.
+      // Two gates, one predicate, or the rung silences the inbox on the second
+      // hop instead of the first.
+      const adm = governor.admit(
+        { source: "cadence", mode, humanReply: cadence ? isHumanLaneCadence(cadence) : false },
+        governor.defaultDeps({ agentRoot })
+      );
       if (adm.decision !== "ADMIT") return { admit: false, reason: adm.reason || adm.decision };
       return { admit: true };
     } catch {
@@ -553,6 +612,16 @@ export function startConsumer(opts = {}) {
     }
   }
 
+  /** The seat's memberId from the cached mandate body. Never throws. */
+  function readMandateMemberId(root) {
+    try {
+      const raw = JSON.parse(readFileSync(join(root, "state", "mandate", "cache.json"), "utf-8"));
+      return (raw && raw.body && (raw.body.memberId || raw.body.member_id)) || null;
+    } catch {
+      return null;
+    }
+  }
+
   const stats = {
     started_at: new Date().toISOString(),
     received: 0,
@@ -738,7 +807,7 @@ export function startConsumer(opts = {}) {
     // not a per-event failure — burning retry budget here would eventually DLQ
     // a perfectly good cadence just because the box was busy).
     {
-      const gov = governanceGate();
+      const gov = governanceGate(event.cadence);
       if (!gov.admit) {
         log({
           level: "info",
@@ -1032,6 +1101,75 @@ export function startConsumer(opts = {}) {
   recoveryTimer.unref?.();
   timers.push(recoveryTimer);
 
+  // THE 80% RUNG'S DELIVERY LEG. `maybeNotify` fires at most once per band per
+  // period and addresses the notice to the SUPERVISOR (never to this seat), so
+  // this timer is cheap: after the first fire every subsequent call reads two
+  // small files and returns `notified:false`. It shares the recovery cadence
+  // because a spend escalation that arrives tomorrow morning is not an
+  // escalation — the goal-steward runs daily at 07:15, which is far too coarse
+  // for money. Fail-open and LOUD: an undeliverable notice logs an error rather
+  // than disappearing.
+  const escalateTimer = budgetEscalateMs > 0 ? setInterval(() => {
+    (async () => {
+      const { escalateBudget } = await import("../../lib/budget-escalate.mjs");
+      let conn = null;
+      try {
+        const { resolveOrgToolConfig } = await import("../../lib/org/tool-surface.mjs");
+        const c = resolveOrgToolConfig({ agentRoot });
+        conn = c ? { base: c.base || "", token: c.token || "", orgId: c.orgId || "" } : null;
+      } catch { /* no credential → escalateBudget reports it rather than sending */ }
+      const r = await escalateBudget(
+        { agentRoot, conn },
+        { log: (level, msg) => log({ level, stage: "budget_escalation", message: msg }) }
+      );
+      if (r.notified) {
+        log({ level: r.delivered ? "warn" : "error", stage: "budget_escalation", band: r.band, delivered: r.delivered, reason: r.reason });
+      }
+
+      // ── THE RETURN LEG, ON THE SAME CLOCK AS THE MONEY ────────────────────
+      // `reconcileBudgetPosture` used to be reachable ONLY from the goal-steward
+      // guard, which runs daily at 07:15 — 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 07:15 the next
+      // morning the band it observed was 0 again. Local enforcement was fine
+      // (`governanceGate` re-reads the posture per tick); it was specifically the
+      // record — the thing the person who FUNDS the seat looks at — that never
+      // arrived. Five minutes is the right clock for money.
+      try {
+        const bg = await import("../../lib/budget-guard.mjs");
+        const st = bg.dailyStatus({ agentRoot });
+        const { reconcileBudgetPosture } = await import("../../lib/plan/budget-runtime.mjs");
+        let mirrorDrift;
+        // The seat's own member id: the drift row is filed AGAINST this member.
+        // Same resolution ladder the goal-steward uses (env first, then the
+        // mandate cache the seat already holds), so the two agree.
+        const memberId = process.env.COHORT_AGENT_ID || readMandateMemberId(agentRoot);
+        if (conn && conn.base && conn.token && memberId) {
+          const { call } = await import("../../lib/org/client.mjs");
+          mirrorDrift = async ({ kind, key, detail, resolve }) =>
+            call("mandate.reportDrift", { memberId, kind, key, detail: detail || null, ...(resolve ? { resolve: true } : {}) }, conn);
+        } else if (st.band >= 125) {
+          log({ level: "warn", stage: "budget_posture", message: "band >=125% but no org credential/memberId — the suspension is recorded LOCALLY ONLY and hq will not show it" });
+        }
+        const rec = await reconcileBudgetPosture(
+          { agentRoot, posture: st.posture, status: st },
+          { log: (level, msg) => log({ level, stage: "budget_posture", message: msg }), mirrorDrift }
+        );
+        if (rec.recorded > 0 || rec.previousBand !== rec.band) {
+          log({ level: "warn", stage: "budget_posture", band: rec.band, previous_band: rec.previousBand, recorded: rec.recorded, mirrored: rec.mirrored, suspended: rec.suspended.length });
+        }
+      } catch (err) {
+        log({ level: "error", stage: "budget_posture_failed", error: err?.message || String(err) });
+      }
+    })().catch((err) => {
+      log({ level: "error", stage: "budget_escalation_failed", error: err?.message || String(err) });
+    });
+  }, budgetEscalateMs) : null;
+  if (escalateTimer) {
+    escalateTimer.unref?.();
+    timers.push(escalateTimer);
+  }
+
   // Initial sweep + heartbeat
   recoverStaleClaimsGuarded();
   heartbeat();

package/scripts/daemon/cadence-consumer.test.mjs

@@ -646,6 +646,12 @@ test("0.3: realSpawnSession argv requests --output-format json and records real
       new URL("../cost/track-claude-usage.mjs", import.meta.url),
       join(root, "scripts/cost/track-claude-usage.mjs")
     );
+    // ...and the shared billing contract it imports relative to itself.
+    mkdirSync(join(root, "lib/cost"), { recursive: true });
+    await fsp.copyFile(
+      new URL("../../lib/cost/ledger-row.mjs", import.meta.url),
+      join(root, "lib/cost/ledger-row.mjs")
+    );
 
     const argvFile = join(root, "shim-argv.txt");
     const shim = join(root, "claude-shim");

package/scripts/daemon/cadence-handlers.mjs

@@ -426,6 +426,72 @@ function loadAgentCfg(agentRoot) {
   return agent;
 }
 
+/**
+ * nightly-backup (inline): the disaster-recovery job.
+ *
+ * Runs scripts/maintenance/backup-run.mjs as a child process rather than
+ * in-process, deliberately: it shells out to `tar` (and possibly gsutil/aws),
+ * can take tens of seconds on a large state tree, and must not be able to wedge
+ * the persistent daemon's event loop or leave a half-written archive if the
+ * daemon is restarted mid-run. A non-zero exit is REPORTED, never swallowed —
+ * the whole reason this gap existed is that the old shell driver exited 0 in
+ * silence when unconfigured.
+ *
+ * Injectable via `opts.runImpl` for tests (no tar, no filesystem).
+ */
+async function handleNightlyBackup({ event, agentRoot, log }, opts = {}) {
+  const started = Date.now();
+  try {
+    const runner =
+      opts.runImpl ||
+      (async () => {
+        const { execFile } = await import("node:child_process");
+        const script = join(agentRoot, "scripts", "maintenance", "backup-run.mjs");
+        const fallback = join(__dirname, "..", "maintenance", "backup-run.mjs");
+        const target = existsSync(script) ? script : fallback;
+        return new Promise((resolvePromise) => {
+          execFile(
+            process.execPath,
+            [target, "--agent-dir", agentRoot],
+            { timeout: 20 * 60 * 1000, maxBuffer: 8 * 1024 * 1024 },
+            (err, stdout, stderr) => {
+              resolvePromise({
+                code: err ? (typeof err.code === "number" ? err.code : 1) : 0,
+                stdout: String(stdout || ""),
+                stderr: String(stderr || ""),
+              });
+            }
+          );
+        });
+      });
+
+    const res = await runner({ agentRoot });
+    const durationMs = Date.now() - started;
+    // Surface the runner's own warn/error lines into the daemon log so a
+    // degraded backup (offsite unconfigured, offsite push failed, include path
+    // dropped by the credential deny-list) is visible without opening a file.
+    const notable = `${res.stdout || ""}${res.stderr || ""}`
+      .split("\n")
+      .filter((l) => /\[(warn|error)\]/.test(l));
+    if (typeof log === "function") {
+      for (const line of notable.slice(0, 10)) log(res.code === 0 ? "warn" : "error", `[nightly-backup] ${line.trim()}`);
+    }
+    if (res.code !== 0) {
+      return {
+        ok: false,
+        decision: "inline",
+        cadence: event.cadence,
+        durationMs,
+        error: `backup-run.mjs exited ${res.code}`,
+        detail: notable.slice(0, 5),
+      };
+    }
+    return { ok: true, decision: "inline", cadence: event.cadence, durationMs, warnings: notable.length };
+  } catch (err) {
+    return { ok: false, decision: "inline", cadence: event.cadence, error: err && err.message ? err.message : String(err) };
+  }
+}
+
 /**
  * nightly-cost-reconcile (inline): three-way spend reconcile of today's local
  * router ledger against the Anthropic Admin Cost API. We pass NO fetchImpl, so
@@ -1198,6 +1264,84 @@ async function guardGoalSteward({ event, agentRoot, log }, opts = {}) {
       }
     }
 
+    // 2d. THE BUDGET LADDER'S 100% RUNG: "self-directed (D3) work stops."
+    //     THIS loop is D3 — the only thing in the system that creates work for
+    //     the seat out of its own gaps. Above the degrade rung it does not run
+    //     at all; below it, the seat's remaining envelope and the fan-out
+    //     ceiling are handed to `routeRung`, which already knows how to enqueue
+    //     rather than downgrade an over-budget item (`remainingCents`/`maxRung`
+    //     were parameters with no caller — this is the caller).
+    //
+    //     Measuring is NOT self-directed work and is deliberately not gated: a
+    //     seat that stops measuring because it is over budget also stops being
+    //     able to prove it, and the KPI series goes dark exactly when someone
+    //     needs it. Only the CREATE half is stopped, via enforcement=observe.
+    let budgetDeps = opts.budgetDeps;
+    if (budgetDeps === undefined) {
+      budgetDeps = {};
+      try {
+        const bg = await import("../../lib/budget-guard.mjs");
+        const st = bg.dailyStatus({ agentRoot });
+        if (!st.posture.selfDirected && enforcement === "active") {
+          say(
+            "warn",
+            `[goal-steward] budget ${st.mode} (${st.pct}% of $${st.capUSD}/day, ${st.capSource}) — self-directed work STOPS: ` +
+              "measuring continues, creating does not"
+          );
+          enforcement = "observe";
+        }
+        budgetDeps = {
+          budgetStatus: st,
+          maxRung: st.posture.maxRung ?? undefined,
+          // The seat's remaining envelope for the period, in cents — the same
+          // envelope hq funded, not a local guess. Null envelope ⇒ undefined ⇒
+          // routeRung's budget gate stays inert rather than inventing a ceiling.
+          remainingCents: st.envelope && Number.isFinite(st.envelope.remainingUSD)
+            ? Math.max(0, Math.round(st.envelope.remainingUSD * 100))
+            : undefined,
+        };
+
+        // THE 125% RUNG, on the plan. Reconcile the compiled plan against the
+        // live band: OUTCOME obligations (and the measure/review cadences that
+        // serve them) are suspended, one `budget_breach` drift row each, on the
+        // band EDGE only. The plan file itself is not rewritten — see
+        // lib/plan/budget-runtime.mjs for why a schedule that flaps with spend
+        // would be worse than the breach.
+        try {
+          const { reconcileBudgetPosture } = await import("../../lib/plan/budget-runtime.mjs");
+
+          // The return leg. A suspension only this laptop knows about is
+          // invisible to the person who funds the seat — and funding is the only
+          // thing that clears it. hq dedupes an open row per
+          // (memberId, kind, key), so re-reporting is safe.
+          let mirrorDrift;
+          if (conn && conn.base && conn.token) {
+            const { call } = await import("../../lib/org/client.mjs");
+            mirrorDrift = async ({ kind, key, detail, resolve }) =>
+              call(
+                "mandate.reportDrift",
+                { memberId, kind, key, detail: detail || null, ...(resolve ? { resolve: true } : {}) },
+                { ...conn, fetchImpl: opts.fetchImpl }
+              );
+          } else {
+            say("warn", "[goal-steward] no org credential — a budget suspension will be recorded LOCALLY ONLY and hq will not show it");
+          }
+
+          const rec = await reconcileBudgetPosture(
+            { agentRoot, posture: st.posture, status: st },
+            { now: opts.now, log: (level, msg) => say(level, `[goal-steward] ${msg}`), mirrorDrift }
+          );
+          if (rec.recorded > 0) {
+            say("warn", `[goal-steward] recorded ${rec.recorded} budget_breach drift row(s) at band ${rec.band}% (${rec.mirrored} mirrored to hq)`);
+          }
+        } catch (err) {
+          say("error", `[goal-steward] budget/plan reconcile failed (${err && err.message ? err.message : err}) — obligations are NOT suspended this tick`);
+        }
+      } catch (err) {
+        say("warn", `[goal-steward] could not read the budget posture (${err && err.message ? err.message : err}) — running UNMETERED this tick`);
+      }
+    }
+
     const run = opts.runImpl || (await import("../../lib/goals/loop.mjs")).runGoalSteward;
     const report = await run({
       agentRoot,
@@ -1207,6 +1351,7 @@ async function guardGoalSteward({ event, agentRoot, log }, opts = {}) {
       sensors,
       reachable,
       memberId,
+      ...budgetDeps,
       ...(conn || {}),
       ...(mirrorSample ? { mirrorSample } : {}),
       ...(opts.runDeps || {}),
@@ -1371,6 +1516,11 @@ export const CADENCE_REGISTRY = {
 
   // Economics / scheduling cadences (WS-economics). Deterministic → inline,
   // except dynamic-jobs (guarded escalate-when-due).
+  "nightly-backup": {
+    mode: "inline",
+    handler: handleNightlyBackup,
+    description: "Nightly DR backup — tar.gz of durable state to local restore points outside the repo, plus the offsite copy when configured. Inline (no LLM); a failed run is reported, never swallowed.",
+  },
   "nightly-cost-reconcile": {
     mode: "inline",
     handler: handleNightlyCostReconcile,
@@ -1525,6 +1675,13 @@ export function getCadenceDef(name) {
     if (Number.isFinite(cfg.budgetCents)) def.budgetCents = cfg.budgetCents;
     else _warnUnmetered(name, cfg.obligationKey);
     if (cfg.obligationKey) def.obligationKey = cfg.obligationKey;
+    // Provenance the RUNTIME budget gate needs (lib/plan/emit.toRegistry): which
+    // obligation this cadence serves, and whether it is free to keep running at
+    // a breached band. Without them the consumer cannot tell a funded
+    // objective's measure-cadence from the seat's own heartbeat.
+    if (cfg.scope) def.scope = cfg.scope;
+    if (cfg.objectiveId) def.objectiveId = cfg.objectiveId;
+    def.offlineSafe = cfg.offlineSafe === true;
     return def;
   }
   return null;
@@ -1548,6 +1705,7 @@ export { guardSkillCurator, maybeSpawnConsolidation };
 // them via CADENCE_REGISTRY). Each takes an optional second arg of injectable
 // seams (lib fn / clock / cfg) so tests never touch the network or real config.
 export {
+  handleNightlyBackup,
   handleNightlyCostReconcile,
   handleFleetCostDigest,
   handleOrgCostSync,

package/scripts/daemon/cadence-handlers.test.mjs

@@ -20,6 +20,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { guardSkillCurator, maybeSpawnConsolidation, CADENCE_REGISTRY,
+  handleNightlyBackup,
   handleNightlyCostReconcile, handleFleetCostDigest, handleOrgCostSync, guardDynamicJobs,
   guardMessagingInbound, guardDirectoryHygiene, guardBrandSteward } from "./cadence-handlers.mjs";
 import { writeSkill } from "../../lib/learning/skill-writer.mjs";
@@ -181,6 +182,69 @@ test("CADENCE_REGISTRY wires the economics/scheduling cadences with the right mo
   assert.ok(CADENCE_REGISTRY["dynamic-jobs"].prompt);
 });
 
+// ---------------------------------------------------------------------------
+// nightly-backup (DR) — the whole point is that a failed run is never silent
+// ---------------------------------------------------------------------------
+
+test("CADENCE_REGISTRY wires nightly-backup as an inline handler", () => {
+  assert.equal(CADENCE_REGISTRY["nightly-backup"].mode, "inline");
+  assert.equal(typeof CADENCE_REGISTRY["nightly-backup"].handler, "function");
+  // Inline cadences must NOT carry a prompt — a prompt would let the consumer
+  // spawn a Claude session for a tar job.
+  assert.ok(!CADENCE_REGISTRY["nightly-backup"].prompt);
+});
+
+test("nightly-backup: a clean run is ok and reports no warnings", async () => {
+  const res = await handleNightlyBackup(ev("nightly-backup"), {
+    runImpl: async () => ({ code: 0, stdout: "[info] backup complete (tier=offsite).\n", stderr: "" }),
+  });
+  assert.equal(res.ok, true);
+  assert.equal(res.decision, "inline");
+  assert.equal(res.cadence, "nightly-backup");
+  assert.equal(res.warnings, 0);
+});
+
+test("nightly-backup: a non-zero exit is REPORTED, not swallowed", async () => {
+  const logs = [];
+  const res = await handleNightlyBackup(
+    { event: { cadence: "nightly-backup" }, agentRoot: tmpRoot(), log: (lvl, m) => logs.push([lvl, m]) },
+    { runImpl: async () => ({ code: 1, stdout: "", stderr: "[error] REFUSING: no .maestro/backup-config.yaml\n" }) }
+  );
+  assert.equal(res.ok, false);
+  assert.match(res.error, /exited 1/);
+  assert.ok(logs.some(([lvl, m]) => lvl === "error" && /REFUSING/.test(m)), "the refusal must reach the daemon log");
+});
+
+test("nightly-backup: a degraded-but-successful run surfaces its warnings in the daemon log", async () => {
+  const logs = [];
+  const res = await handleNightlyBackup(
+    { event: { cadence: "nightly-backup" }, agentRoot: tmpRoot(), log: (lvl, m) => logs.push([lvl, m]) },
+    {
+      runImpl: async () => ({
+        code: 0,
+        stdout:
+          "[info] plan: tier=local\n" +
+          "[warn] offsite is NOT configured — these restore points do not survive losing this machine.\n" +
+          "[warn] include path DROPPED by the credential deny-list: .env (matched .env)\n",
+        stderr: "",
+      }),
+    }
+  );
+  assert.equal(res.ok, true);
+  assert.equal(res.warnings, 2);
+  assert.ok(logs.some(([, m]) => /offsite is NOT configured/.test(m)));
+  assert.ok(logs.some(([, m]) => /credential deny-list/.test(m)));
+  assert.ok(!logs.some(([, m]) => /\[info\]/.test(m)), "info noise stays in the backup log, not the daemon log");
+});
+
+test("nightly-backup: a throwing runner degrades to ok:false, never an unhandled rejection", async () => {
+  const res = await handleNightlyBackup(ev("nightly-backup"), {
+    runImpl: async () => { throw new Error("spawn ENOENT"); },
+  });
+  assert.equal(res.ok, false);
+  assert.match(res.error, /spawn ENOENT/);
+});
+
 test("nightly-cost-reconcile: inline, surfaces driftPct, passes NO fetchImpl (fails open)", async () => {
   let sawFetch = "unset";
   const fake = async (o) => {