@cohortapp/agent-sdk 2.5.1 → 2.6.1

package/lib/backup/policy.test.mjs

@@ -0,0 +1,305 @@
+/**
+ * policy.test.mjs — coverage for lib/backup/policy.mjs.
+ *
+ * The load-bearing cases are the two that a silent bug would make invisible:
+ *   1. the hard deny-list actually drops `.env` / `.cohort-key.json` even when
+ *      the config asks for them (credential exfiltration via backup), and
+ *   2. the severity ladder distinguishes "no restore point at all" (fail) from
+ *      "restore points that would not survive a house fire" (warn).
+ *
+ * Hermetic: tmp agent roots, injected env/home. No tar, no network, no launchd.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  DEFAULT_INCLUDE,
+  DENY_PATTERNS,
+  backupVerdict,
+  defaultConfigYaml,
+  defaultLocalRoot,
+  denyMatch,
+  parseBackupConfig,
+  resolveBackupPlan,
+  sanitisePrefix,
+  tarExcludeArgs,
+  scanTextForSecrets,
+  scanIncludesForSecrets,
+} from "./policy.mjs";
+
+function makeAgent(configBody) {
+  const root = mkdtempSync(join(tmpdir(), "bkpol-"));
+  mkdirSync(join(root, ".maestro"), { recursive: true });
+  if (configBody !== undefined) {
+    writeFileSync(join(root, ".maestro", "backup-config.yaml"), configBody);
+  }
+  return root;
+}
+const cleanup = (root) => rmSync(root, { recursive: true, force: true });
+
+// ── deny-list ──────────────────────────────────────────────────────────────
+
+test("deny-list rejects live credentials by exact name and by glob", () => {
+  assert.equal(denyMatch(".env"), ".env");
+  assert.equal(denyMatch(".env.local"), ".env.*");
+  assert.equal(denyMatch(".cohort-key.json"), ".cohort-key.json");
+  assert.equal(denyMatch(".claude/.credentials.json"), ".claude/.credentials.json");
+  assert.ok(denyMatch("config/tls/server.pem"));
+  assert.ok(denyMatch("secrets/id_rsa"));
+});
+
+test("deny-list applies to nested segments (node_modules at any depth)", () => {
+  assert.equal(denyMatch("node_modules"), "node_modules");
+  assert.equal(denyMatch("plugins/x/node_modules/y"), "node_modules");
+  assert.equal(denyMatch("state/rag/index/vectors.bin"), "state/rag/index");
+});
+
+test("deny-list leaves the durable state we DO want alone", () => {
+  for (const p of ["state", "state/queues/action-stack.yaml", "knowledge", "memory", "outputs", "config/agent.json", ".maestro/last-backup.json"]) {
+    assert.equal(denyMatch(p), null, `${p} must be backupable`);
+  }
+});
+
+test("a config that asks for .env gets it DROPPED and reported, not obeyed", () => {
+  const root = makeAgent(`enabled: true
+prefix: test
+include:
+  - state
+  - .env
+  - .cohort-key.json
+  - ../../etc
+`);
+  const plan = resolveBackupPlan({ agentRoot: root, env: { MAESTRO_BACKUP_DIR: "/tmp/b" } });
+  cleanup(root);
+  assert.deepEqual(plan.include, ["state"]);
+  const denied = plan.violations.map((v) => v.path).sort();
+  assert.deepEqual(denied, ["../../etc", ".cohort-key.json", ".env"]);
+  assert.ok(plan.violations.some((v) => v.pattern === "outside-agent-root"));
+});
+
+test("tar exclude args always carry the hard deny-list first", () => {
+  const args = tarExcludeArgs({ exclude: ["outputs/scratch"] });
+  assert.ok(args.includes("--exclude=.env"));
+  assert.ok(args.includes("--exclude=.cohort-key.json"));
+  assert.ok(args.includes("--exclude=node_modules"));
+  assert.ok(args.includes("--exclude=*/node_modules"));
+  assert.ok(args.includes("--exclude=outputs/scratch"));
+  assert.ok(args.indexOf("--exclude=.env") < args.indexOf("--exclude=outputs/scratch"));
+});
+
+test("every deny pattern is non-empty and lowercase-stable", () => {
+  for (const p of DENY_PATTERNS) assert.ok(typeof p === "string" && p.length > 0);
+});
+
+// ── config parsing / plan resolution ───────────────────────────────────────
+
+test("missing config → tier none, nothing enabled", () => {
+  const root = makeAgent();
+  const plan = resolveBackupPlan({ agentRoot: root });
+  cleanup(root);
+  assert.equal(plan.present, false);
+  assert.equal(plan.tier, "none");
+  assert.equal(plan.enabled, false);
+});
+
+test("malformed YAML → present but unreadable (a DIFFERENT problem from absent)", () => {
+  const root = makeAgent("enabled: true\n  : : broken\n\t- x");
+  const plan = resolveBackupPlan({ agentRoot: root });
+  cleanup(root);
+  assert.equal(plan.present, true);
+  assert.equal(plan.readable, false);
+  assert.equal(plan.tier, "unreadable");
+});
+
+test("the shipped default config resolves to the LOCAL tier with no credentials", () => {
+  const root = makeAgent(defaultConfigYaml({ prefix: "astra-ai" }));
+  const plan = resolveBackupPlan({ agentRoot: root, home: "/Users/fake" });
+  cleanup(root);
+  assert.equal(plan.enabled, true);
+  assert.equal(plan.tier, "local");
+  assert.equal(plan.prefix, "astra-ai");
+  assert.equal(plan.local.enabled, true);
+  assert.equal(plan.offsite.configured, false);
+  assert.deepEqual(plan.include, [...DEFAULT_INCLUDE]);
+  assert.deepEqual(plan.violations, []);
+  assert.ok(plan.local.dir.endsWith("/Maestro/backups/astra-ai"));
+});
+
+test("offsite provider + bucket promotes the tier to offsite", () => {
+  const root = makeAgent(`enabled: true
+prefix: astra-ai
+offsite:
+  provider: s3
+  bucket: acme-agent-backups
+`);
+  const plan = resolveBackupPlan({ agentRoot: root, home: "/Users/fake" });
+  cleanup(root);
+  assert.equal(plan.tier, "offsite");
+  assert.equal(plan.offsite.provider, "s3");
+  assert.equal(plan.offsite.bucket, "acme-agent-backups");
+});
+
+test("an unknown offsite provider does not count as configured", () => {
+  const root = makeAgent(`enabled: true
+offsite:
+  provider: dropbox
+  bucket: nope
+`);
+  const plan = resolveBackupPlan({ agentRoot: root, home: "/Users/fake" });
+  cleanup(root);
+  assert.equal(plan.offsite.configured, false);
+  assert.equal(plan.tier, "local");
+});
+
+test("enabled:false → tier disabled even with a full config", () => {
+  const root = makeAgent(`enabled: false
+offsite:
+  provider: gcs
+  bucket: b
+`);
+  const plan = resolveBackupPlan({ agentRoot: root, home: "/Users/fake" });
+  cleanup(root);
+  assert.equal(plan.tier, "disabled");
+});
+
+test("MAESTRO_BACKUP_DIR overrides the local root", () => {
+  assert.equal(defaultLocalRoot({ env: { MAESTRO_BACKUP_DIR: "/mnt/dr" } }), "/mnt/dr");
+  assert.equal(
+    defaultLocalRoot({ env: {}, home: "/Users/x" }),
+    "/Users/x/Library/Application Support/Maestro/backups"
+  );
+});
+
+test("parseBackupConfig never throws and rejects non-objects", () => {
+  assert.equal(parseBackupConfig(""), null);
+  assert.equal(parseBackupConfig("- a\n- b"), null);
+  assert.equal(parseBackupConfig("just a string"), null);
+  assert.deepEqual(parseBackupConfig("enabled: true"), { enabled: true });
+});
+
+test("prefixes are sanitised into safe archive/bucket keys", () => {
+  assert.equal(sanitisePrefix("Astra AI"), "astra-ai");
+  assert.equal(sanitisePrefix("../../etc/passwd"), "etc-passwd");
+  assert.equal(sanitisePrefix(""), "agent");
+});
+
+// ── severity ladder ────────────────────────────────────────────────────────
+
+const FRESH = { configured: true, lastBackupAt: "2026-08-12T03:10:00Z", ageHours: 6, stale: false };
+
+test("no config → FAIL naming the one command that fixes it", () => {
+  const v = backupVerdict({ present: false }, {});
+  assert.equal(v.level, "fail");
+  assert.match(v.fix, /maestro init backup-replication --apply/);
+});
+
+test("configured + enabled but never run → FAIL (there is no restore point)", () => {
+  const root = makeAgent(defaultConfigYaml({ prefix: "a" }));
+  const plan = resolveBackupPlan({ agentRoot: root, home: "/Users/fake" });
+  cleanup(root);
+  const v = backupVerdict(plan, { configured: true, lastBackupAt: null, ageHours: null, stale: true });
+  assert.equal(v.level, "fail");
+  assert.match(v.msg, /NEVER completed/);
+});
+
+test("local-only but fresh → WARN that names the residual machine-loss risk", () => {
+  const root = makeAgent(defaultConfigYaml({ prefix: "a" }));
+  const plan = resolveBackupPlan({ agentRoot: root, home: "/Users/fake" });
+  cleanup(root);
+  const v = backupVerdict(plan, FRESH);
+  assert.equal(v.level, "warn");
+  assert.match(v.msg, /LOCAL-ONLY/);
+  assert.match(v.fix, /offsite\.provider/);
+});
+
+test("offsite + fresh → the only OK", () => {
+  const root = makeAgent(`enabled: true
+prefix: a
+offsite:
+  provider: gcs
+  bucket: agent-backups
+`);
+  const plan = resolveBackupPlan({ agentRoot: root, home: "/Users/fake" });
+  cleanup(root);
+  const v = backupVerdict(plan, FRESH);
+  assert.equal(v.level, "ok");
+  assert.match(v.msg, /gcs:\/\/agent-backups/);
+});
+
+test("stale beats local-only: a stale offsite backup still WARNs", () => {
+  const root = makeAgent(`enabled: true
+offsite:
+  provider: s3
+  bucket: b
+`);
+  const plan = resolveBackupPlan({ agentRoot: root, home: "/Users/fake" });
+  cleanup(root);
+  const v = backupVerdict(plan, { configured: true, lastBackupAt: "2026-08-01T00:00:00Z", ageHours: 200, stale: true });
+  assert.equal(v.level, "warn");
+  assert.match(v.msg, /stale/);
+});
+
+test("an include list that is entirely denied FAILs rather than shipping an empty archive", () => {
+  const root = makeAgent(`enabled: true
+include:
+  - .env
+`);
+  const plan = resolveBackupPlan({ agentRoot: root, home: "/Users/fake" });
+  cleanup(root);
+  const v = backupVerdict(plan, FRESH);
+  assert.equal(v.level, "fail");
+  assert.match(v.msg, /every include path was rejected/);
+});
+
+// ---------------------------------------------------------------------------
+// THE CONTENT DENY-LIST — the hole a path deny-list cannot see
+// ---------------------------------------------------------------------------
+
+test("scanTextForSecrets catches the credential shapes that authenticate AS this agent", () => {
+  // The real leak: state/setup/progress.json carried "orgToken":"nlk_…" — the
+  // byte-identical value of COHORT_API_KEY in .env — inside an included tree,
+  // while the runner logged "archive verified clean".
+  assert.deepEqual(scanTextForSecrets('{"orgToken":"nlk_7bc80020aa11bb22cc33dd44ee55ff66"}'), ["cohort-api-key"]);
+  assert.deepEqual(scanTextForSecrets("sk-ant-api03-AAAAAAAAAAAAAAAAAAAAAAAA"), ["anthropic-key"]);
+  assert.deepEqual(scanTextForSecrets("-----BEGIN OPENSSH PRIVATE KEY-----"), ["private-key-block"]);
+  assert.deepEqual(scanTextForSecrets("ghp_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"), ["github-token"]);
+  // And does not fire on ordinary prose or config.
+  assert.deepEqual(scanTextForSecrets('{"orgAuthMethod":"apikey","orgBase":"https://hq.example"}'), []);
+  assert.deepEqual(scanTextForSecrets("the token lives in .env"), []);
+});
+
+test("scanIncludesForSecrets finds a credential INSIDE an included file", () => {
+  const root = mkdtempSync(join(tmpdir(), "backup-content-"));
+  try {
+    mkdirSync(join(root, "state", "setup"), { recursive: true });
+    mkdirSync(join(root, "knowledge"), { recursive: true });
+    writeFileSync(join(root, "state", "setup", "progress.json"),
+      JSON.stringify({ answers: { orgId: "acme", orgToken: "nlk_7bc80020aa11bb22cc33dd44ee55ff66" } }));
+    writeFileSync(join(root, "state", "notes.md"), "no secrets here");
+    writeFileSync(join(root, "knowledge", "faq.md"), "the api key is in .env");
+
+    const plan = { include: ["state", "knowledge"], exclude: [] };
+    const r = scanIncludesForSecrets(plan, root);
+    assert.deepEqual(r.leaks.map((l) => l.path), ["state/setup/progress.json"]);
+    assert.deepEqual(r.leaks[0].patterns, ["cohort-api-key"]);
+    assert.equal(r.truncated, false);
+    assert.ok(r.scanned >= 3);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test("the content scan skips path-denied trees and binary files", () => {
+  const root = mkdtempSync(join(tmpdir(), "backup-content-"));
+  try {
+    // A dependency full of example keys must not cost us the whole DR posture.
+    mkdirSync(join(root, "state", "node_modules", "pkg"), { recursive: true });
+    writeFileSync(join(root, "state", "node_modules", "pkg", "readme.md"), "sk-ant-api03-BBBBBBBBBBBBBBBBBBBBBBBB");
+    writeFileSync(join(root, "state", "blob.bin"), Buffer.from([0x00, 0x01, 0x02, 0x00]));
+    const r = scanIncludesForSecrets({ include: ["state"], exclude: [] }, root);
+    assert.deepEqual(r.leaks, [], "node_modules is already path-denied");
+    assert.equal(r.skippedBinary, 1);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});

package/lib/budget-escalate.mjs

@@ -0,0 +1,133 @@
+/**
+ * lib/budget-escalate.mjs — the 80 % rung's delivery leg.
+ *
+ * `lib/budget-guard.maybeNotify` decides WHETHER a notice fires, at which band,
+ * and WHO it is addressed to (the seat's REVIEWER collaborator —
+ * `WorkforceMember.supervisorId` as hq published it on the mandate body). This
+ * module is the only thing that puts that notice on the wire.
+ *
+ * NEVER TO THE OWNER. The seat is not told its own budget band. An agent that
+ * knows it is running out of money has every incentive to optimise the meter
+ * rather than the work, and the meter is the one number it must not be able to
+ * move. When there is no supervisor edge the notice is LOGGED as an error and
+ * delivered nowhere — an unsupervised seat is a provisioning gap, and the fix is
+ * to set `supervisorId`, not to hand the agent its own alarm.
+ *
+ * DELIVERY, with no new protocol surface:
+ *   channel.resolveOrCreateDm(memberId)  → the deterministic 1:1 DM channel
+ *   messaging.send(channelId, body)      → the notice
+ * Both are existing, idempotent methods on `messaging.write`; `resolveOrCreateDm`
+ * is replay-safe by construction (deterministic `dm-<sorted slugs>` slug), so a
+ * retried escalation reuses the same channel rather than littering DMs.
+ *
+ * FAIL-OPEN, NEVER FAIL-SILENT. Every failure path returns `{ok:false, reason}`
+ * AND logs: a spend escalation that quietly does not arrive is worse than no
+ * escalation, because the operator believes the channel works.
+ *
+ * @module lib/budget-escalate
+ */
+
+"use strict";
+
+import { maybeNotify } from "./budget-guard.mjs";
+
+/**
+ * Fire the period's budget notice, if one is due, to the supervisor.
+ *
+ * @param {object} o
+ *   @param {string} o.agentRoot
+ *   @param {object} [o.conn]  { base, token, orgId } — the org credential
+ * @param {object} [deps] { now?, log?, callImpl?, notifyImpl?, sendImpl? }
+ * @returns {Promise<{ok:boolean, notified:boolean, band:number, delivered:boolean,
+ *                     recipient:object|null, reason:string|null, status?:object}>}
+ */
+export async function escalateBudget(o = {}, deps = {}) {
+  const log = typeof deps.log === "function"
+    ? deps.log
+    : (level, msg) => { (level === "error" ? console.error : console.warn)(`[budget-escalate] ${msg}`); };
+
+  const notify = deps.notifyImpl || maybeNotify;
+  let notice;
+  try {
+    // `retryMs` rides through: the guard records an ATTEMPT and backs off between
+    // them, and this timer's own period is what that backoff is calibrated to.
+    notice = notify({ agentRoot: o.agentRoot, now: deps.now, retryMs: deps.retryMs, log });
+  } catch (err) {
+    log("error", `the budget guard threw while deciding whether to escalate (${err && err.message ? err.message : err}) — NO notice was sent`);
+    return { ok: false, notified: false, band: 0, delivered: false, recipient: null, reason: "guard-threw" };
+  }
+
+  if (!notice || !notice.notified) {
+    return { ok: true, notified: false, band: (notice && notice.band) || 0, delivered: false, recipient: null, reason: null, status: notice && notice.status };
+  }
+  // maybeNotify has already logged the "no supervisor edge" error loudly; the
+  // band is recorded either way so it does not re-fire every tick.
+  if (!notice.recipient) {
+    return { ok: true, notified: true, band: notice.band, delivered: false, recipient: null, reason: "no-supervisor-edge", status: notice.status };
+  }
+
+  const conn = o.conn || {};
+  if (!conn.base || !conn.token) {
+    log("error", `band ${notice.band}% notice for supervisor ${notice.recipient.memberId} could not be sent: no org credential on this seat`);
+    return { ok: false, notified: true, band: notice.band, delivered: false, recipient: notice.recipient, reason: "no-credential", status: notice.status };
+  }
+
+  const call = deps.callImpl || (await import("./org/client.mjs")).call;
+  let channelId = null;
+  try {
+    const frame = await call("channel.resolveOrCreateDm", { memberId: notice.recipient.memberId }, conn);
+    if (frame && frame.ok && frame.result) {
+      channelId = frame.result.channelId || frame.result.id || (frame.result.channel && frame.result.channel.id) || null;
+    }
+    if (!channelId) {
+      const code = (frame && frame.error && frame.error.code) || "unknown";
+      log("error", `band ${notice.band}% notice undeliverable: could not resolve a DM channel with supervisor ${notice.recipient.memberId} (${code})`);
+      return { ok: false, notified: true, band: notice.band, delivered: false, recipient: notice.recipient, reason: `dm-resolve-failed:${code}`, status: notice.status };
+    }
+  } catch (err) {
+    log("error", `band ${notice.band}% notice undeliverable: channel.resolveOrCreateDm threw (${err && err.message ? err.message : err})`);
+    return { ok: false, notified: true, band: notice.band, delivered: false, recipient: notice.recipient, reason: "dm-resolve-threw", status: notice.status };
+  }
+
+  // The body names the seat, the band, the money and the enforcement now in
+  // force — a supervisor must be able to act on it without opening a dashboard.
+  const body = `**Seat budget — band ${notice.band}%**\n\n${notice.message}\n\n_This notice goes to you rather than to the seat: an agent must not be handed its own meter. Raise the envelope on the member's Employee record (payBasis.meteredBudget) to clear it._`;
+
+  try {
+    const send = deps.sendImpl || (await import("./org/messaging.mjs")).sendMessage;
+    const res = await send(
+      {
+        channel: channelId,
+        body,
+        // Stable per (band, period): a retried escalation dedupes server-side
+        // instead of DMing the supervisor twice about the same rung.
+        idempotencyId: `budget-${notice.status.date}-${notice.band}`,
+      },
+      { cfg: o.cfg, agentRoot: o.agentRoot, base: conn.base, token: conn.token, fetchImpl: deps.fetchImpl }
+    );
+    if (!res || res.ok === false) {
+      const code = (res && res.error && res.error.code) || "unknown";
+      log("error", `band ${notice.band}% notice REJECTED by messaging.send (${code}) — the supervisor was not told`);
+      return { ok: false, notified: true, band: notice.band, delivered: false, recipient: notice.recipient, reason: `send-failed:${code}`, status: notice.status };
+    }
+  } catch (err) {
+    log("error", `band ${notice.band}% notice threw on send (${err && err.message ? err.message : err}) — the supervisor was not told`);
+    return { ok: false, notified: true, band: notice.band, delivered: false, recipient: notice.recipient, reason: "send-threw", status: notice.status };
+  }
+
+  // ── COMMIT ONLY NOW ────────────────────────────────────────────────────────
+  // `maybeNotify` records an ATTEMPT; the band is consumed here, after the send
+  // actually succeeded. Before this, the band was written to disk before the
+  // first byte went out, so a single transient failure (hq restarting, the org
+  // credential not yet resolved) permanently dropped the period's escalation —
+  // the timer polled forever and never retried. Every failure path above returns
+  // WITHOUT committing, which is what makes the retry real.
+  if (typeof notice.commit === "function") {
+    try { notice.commit(); }
+    catch (err) { log("error", `band ${notice.band}% notice was delivered but could not be recorded (${err && err.message ? err.message : err}) — it may be re-sent; messaging.send is idempotent on the same key`); }
+  }
+  log("warn", `band ${notice.band}% notice delivered to supervisor ${notice.recipient.memberId}`);
+  return { ok: true, notified: true, band: notice.band, delivered: true, recipient: notice.recipient, reason: null, status: notice.status };
+}
+
+export default { escalateBudget };

package/lib/budget-escalate.test.mjs

@@ -0,0 +1,232 @@
+/**
+ * budget-escalate.test.mjs — the 80% rung reaches a HUMAN, or says why not.
+ *
+ * The rule under test is the anti-Goodhart one: the notice goes to the
+ * supervisor and NEVER to the seat that is spending the money. Everything else
+ * here is about the second rule — a notice that cannot be delivered is an ERROR
+ * in the log, never a silent no-op.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { escalateBudget } from "./budget-escalate.mjs";
+
+const STATUS = { date: "2026-06-15", spentUSD: 27, capUSD: 30, pct: 90, capSource: "seat-envelope" };
+const CONN = { base: "https://hq.example", token: "t0ken", orgId: "org_1" };
+
+function notice(over = {}) {
+  return {
+    notified: true,
+    band: 80,
+    message: "Seat spend at 90% ($27.00 / $30.00 today) — heads-up only.",
+    recipient: { memberId: "M-SUPERVISOR", role: "REVIEWER" },
+    status: STATUS,
+    ...over,
+  };
+}
+
+test("a due notice is DM'd to the supervisor over resolveOrCreateDm + messaging.send", async () => {
+  const calls = [];
+  const sent = [];
+  const r = await escalateBudget(
+    { agentRoot: "/tmp/x", conn: CONN },
+    {
+      log: () => {},
+      notifyImpl: () => notice(),
+      callImpl: async (method, params) => {
+        calls.push([method, params]);
+        return { ok: true, result: { channelId: "chan_dm_1", created: false } };
+      },
+      sendImpl: async (params) => { sent.push(params); return { ok: true, result: { id: "msg_1" } }; },
+    }
+  );
+
+  assert.equal(r.ok, true);
+  assert.equal(r.delivered, true);
+  assert.deepEqual(calls[0], ["channel.resolveOrCreateDm", { memberId: "M-SUPERVISOR" }]);
+  assert.equal(sent[0].channel, "chan_dm_1");
+  assert.match(sent[0].body, /band 80%/i);
+  assert.match(sent[0].body, /an agent must not be handed its own meter/);
+  // Idempotent per (period, band): a retry does not DM the supervisor twice.
+  assert.equal(sent[0].idempotencyId, "budget-2026-06-15-80");
+});
+
+test("no supervisor edge → nothing is sent ANYWHERE, least of all to the owner", async () => {
+  const calls = [];
+  const sent = [];
+  const r = await escalateBudget(
+    { agentRoot: "/tmp/x", conn: CONN },
+    {
+      log: () => {},
+      notifyImpl: () => notice({ recipient: null }),
+      callImpl: async (...a) => { calls.push(a); return { ok: true, result: {} }; },
+      sendImpl: async (p) => { sent.push(p); return { ok: true }; },
+    }
+  );
+  assert.equal(r.notified, true);
+  assert.equal(r.delivered, false);
+  assert.equal(r.reason, "no-supervisor-edge");
+  assert.equal(calls.length, 0, "no channel is opened");
+  assert.equal(sent.length, 0, "and no message is sent — the seat is never told its own band");
+});
+
+test("an undeliverable notice is an ERROR in the log, never a silent no-op", async () => {
+  for (const [label, deps, expected] of [
+    [
+      "no credential",
+      { notifyImpl: () => notice(), callImpl: async () => ({ ok: true, result: { channelId: "c" } }), sendImpl: async () => ({ ok: true }) },
+      "no-credential",
+    ],
+    [
+      "DM resolve rejected",
+      {
+        notifyImpl: () => notice(),
+        callImpl: async () => ({ ok: false, error: { code: "FORBIDDEN_SCOPE" } }),
+        sendImpl: async () => ({ ok: true }),
+      },
+      "dm-resolve-failed:FORBIDDEN_SCOPE",
+    ],
+    [
+      "send rejected",
+      {
+        notifyImpl: () => notice(),
+        callImpl: async () => ({ ok: true, result: { channelId: "c" } }),
+        sendImpl: async () => ({ ok: false, error: { code: "BAD_REQUEST" } }),
+      },
+      "send-failed:BAD_REQUEST",
+    ],
+  ]) {
+    const logged = [];
+    const conn = label === "no credential" ? {} : CONN;
+    const r = await escalateBudget({ agentRoot: "/tmp/x", conn }, { ...deps, log: (l, m) => logged.push(`${l}:${m}`) });
+    assert.equal(r.delivered, false, label);
+    assert.equal(r.reason, expected, label);
+    assert.ok(logged.some((l) => l.startsWith("error:")), `${label} must log an error`);
+  }
+});
+
+test("a throwing transport degrades to a logged failure, never an exception", async () => {
+  const logged = [];
+  const r = await escalateBudget(
+    { agentRoot: "/tmp/x", conn: CONN },
+    {
+      log: (l, m) => logged.push(`${l}:${m}`),
+      notifyImpl: () => notice(),
+      callImpl: async () => { throw new Error("socket hang up"); },
+    }
+  );
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, "dm-resolve-threw");
+  assert.ok(logged.some((l) => /socket hang up/.test(l)));
+});
+
+test("no band due → no traffic at all", async () => {
+  let calls = 0;
+  const r = await escalateBudget(
+    { agentRoot: "/tmp/x", conn: CONN },
+    { log: () => {}, notifyImpl: () => ({ notified: false, band: 0, status: STATUS }), callImpl: async () => { calls++; return { ok: true }; } }
+  );
+  assert.equal(r.notified, false);
+  assert.equal(calls, 0);
+});
+
+test("a throwing budget guard does not take the daemon down", async () => {
+  const logged = [];
+  const r = await escalateBudget(
+    { agentRoot: "/tmp/x", conn: CONN },
+    { log: (l, m) => logged.push(`${l}:${m}`), notifyImpl: () => { throw new Error("ledger unreadable"); } }
+  );
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, "guard-threw");
+  assert.ok(logged.some((l) => l.startsWith("error:") && /NO notice was sent/.test(l)));
+});
+
+// ---------------------------------------------------------------------------
+// THE REAL maybeNotify — write-AFTER-delivery, not write-then-hope
+// ---------------------------------------------------------------------------
+// Every test above stubs `notifyImpl`, i.e. it mocks the component that owns the
+// ordering under test. These use the real guard against a real temp agent root,
+// which is the only way to catch "the band was consumed before the first byte
+// went out".
+
+import { promises as fsp } from "node:fs";
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const FIXED = Date.UTC(2026, 5, 15, 12, 0, 0);
+const DAY = "2026-06-15";
+
+async function escalateRoot({ spentUsd = 27, seatBudgetCents = 3_000 } = {}) {
+  const dir = join(tmpdir(), `bg-escalate-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  mkdirSync(join(dir, "state", "cost-tracking"), { recursive: true });
+  mkdirSync(join(dir, "state", "mandate"), { recursive: true });
+  writeFileSync(
+    join(dir, "state", "mandate", "cache.json"),
+    JSON.stringify({
+      version: 1, checksum: "x", source: "server", fetchedAt: new Date(FIXED).toISOString(),
+      body: {
+        contractVersion: 1, memberId: "A016", objectives: [], seatBudgetCents,
+        budgetPeriod: "monthly", budgetSource: "employee.payBasis.meteredBudget",
+        collaborators: [{ memberId: "M-SUPERVISOR", role: "REVIEWER", source: "workforceMember.supervisorId" }],
+        degradations: [],
+      },
+    })
+  );
+  writeFileSync(
+    join(dir, "state", "cost-tracking", `${DAY}.jsonl`),
+    JSON.stringify({ ts: `${DAY}T10:00:00Z`, model: "opus", source: "dispatcher", input_tokens: 10, output_tokens: 10, total_cost_usd: spentUsd, estimated_usd: spentUsd }) + "\n"
+  );
+  return dir;
+}
+const notifiedBands = (dir) => {
+  const p = join(dir, "state", "cost-tracking", `${DAY}.budget.json`);
+  return existsSync(p) ? (JSON.parse(readFileSync(p, "utf-8")).notified_bands || []) : [];
+};
+
+test("a transient delivery failure does NOT burn the period's band — it is retried", async () => {
+  // The defect: `maybeNotify` wrote `notified_bands` BEFORE any delivery was
+  // attempted, and nothing could un-mark it. One ECONNREFUSED (or a daemon that
+  // started before the org credential resolved) permanently dropped the 80% rung
+  // for the whole period, and the 5-minute timer then polled forever without
+  // ever retrying. The rung's entire purpose is to tell the supervisor.
+  const dir = await escalateRoot();
+  try {
+    const deps = (callImpl) => ({
+      log: () => {}, now: () => FIXED, retryMs: 0, callImpl,
+      sendImpl: async () => ({ ok: true, result: { id: "m1" } }),
+    });
+
+    const t1 = await escalateBudget({ agentRoot: dir, conn: CONN }, deps(async () => { throw new Error("ECONNREFUSED"); }));
+    assert.equal(t1.notified, true);
+    assert.equal(t1.delivered, false);
+    assert.deepEqual(notifiedBands(dir), [], "the band is NOT consumed by a failed attempt");
+
+    // hq recovers. The next tick must actually deliver.
+    const sent = [];
+    const t2 = await escalateBudget({ agentRoot: dir, conn: CONN }, {
+      ...deps(async () => ({ ok: true, result: { channelId: "chan_1" } })),
+      sendImpl: async (p) => { sent.push(p); return { ok: true, result: { id: "m1" } }; },
+    });
+    assert.equal(t2.delivered, true, "the retry lands");
+    assert.equal(sent.length, 1);
+    assert.ok(notifiedBands(dir).includes(80), "and NOW the band is consumed");
+
+    // And it does not re-send afterwards.
+    const t3 = await escalateBudget({ agentRoot: dir, conn: CONN }, deps(async () => ({ ok: true, result: { channelId: "chan_1" } })));
+    assert.equal(t3.notified, false, "at most one notice per band per period");
+  } finally { await fsp.rm(dir, { recursive: true, force: true }); }
+});
+
+test("a persistent outage gives up LOUDLY rather than retrying forever in silence", async () => {
+  const dir = await escalateRoot();
+  try {
+    const logged = [];
+    const deps = { log: (lvl, msg) => logged.push(`${lvl} ${msg}`), now: () => FIXED, retryMs: 0,
+      callImpl: async () => { throw new Error("ECONNREFUSED"); }, sendImpl: async () => ({ ok: true }) };
+    for (let i = 0; i < 8; i++) await escalateBudget({ agentRoot: dir, conn: CONN }, deps);
+    assert.ok(notifiedBands(dir).includes(80), "the band is finally consumed so the log stops spinning");
+    assert.ok(logged.some((l) => /ABANDONED after/.test(l)), "and giving up is an ERROR, not a shrug");
+  } finally { await fsp.rm(dir, { recursive: true, force: true }); }
+});