@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/lib/budget-guard.test.mjs

@@ -31,9 +31,26 @@ async function makeLedgerDir() {
 }
 async function rm(dir) { try { await fsp.rm(dir, { recursive: true, force: true }); } catch { /* */ } }
 
-/** Write `rows` (array of {estimated_usd}) into today's ledger file. */
+/**
+ * Write `rows` (array of {usd}) into today's ledger file as MEASURED sessions.
+ *
+ * `total_cost_usd` + real token counts, because that is what a row from a
+ * correctly-instrumented caller looks like and it is the column the governor
+ * now bills against (lib/cost/ledger-row.mjs). A row carrying only
+ * `estimated_usd` and no tokens classifies as `unknown` — deliberately, so an
+ * unmeasured session can never read as a free one — and would be imputed rather
+ * than summed, which is not what these band tests are about.
+ */
 function seedLedger(dir, rows) {
-  const body = rows.map((r) => JSON.stringify({ ts: `${DATE}T10:00:00.000Z`, estimated_usd: r.usd, model: "sonnet", cadence: "x" })).join("\n") + "\n";
+  const body = rows.map((r) => JSON.stringify({
+    ts: `${DATE}T10:00:00.000Z`,
+    total_cost_usd: r.usd,
+    estimated_usd: r.usd,
+    model: "sonnet",
+    cadence: "x",
+    input_tokens: 1000,
+    output_tokens: 200,
+  })).join("\n") + "\n";
   writeFileSync(join(dir, `${DATE}.jsonl`), body);
 }
 
@@ -41,12 +58,13 @@ function seedLedger(dir, rows) {
 // banding
 // ---------------------------------------------------------------------------
 
-test("dailyStatus: below 50% is band 0, not essential-only", async () => {
+test("dailyStatus: below 80% is band 0, nothing degraded", async () => {
   const dir = await makeLedgerDir();
   try {
     seedLedger(dir, [{ usd: 4 }]); // $4 of $10 = 40%
     const s = dailyStatus({ ledgerDir: dir, now: clk, capUSD: 10 });
     assert.equal(s.band, 0);
+    assert.equal(s.mode, "normal");
     assert.equal(s.essentialOnly, false);
     assert.equal(s.spentUSD, 4);
     assert.equal(s.pct, 40);
@@ -54,7 +72,8 @@ test("dailyStatus: below 50% is band 0, not essential-only", async () => {
 });
 
 test("dailyStatus: crossing each threshold lands in the right band", async () => {
-  for (const [usd, expected] of [[5, 50], [7.5, 75], [9, 90], [10, 100], [12, 100]]) {
+  // The governance ladder: 80 notify · 100 degrade · 125 suspend · 150 refuse.
+  for (const [usd, expected] of [[5, 0], [8, 80], [9.9, 80], [10, 100], [12.5, 125], [15, 150], [40, 150]]) {
     const dir = await makeLedgerDir();
     try {
       seedLedger(dir, [{ usd }]);
@@ -91,7 +110,8 @@ test("dailyStatus: iteration cap can be the binding constraint", async () => {
     const s = dailyStatus({ ledgerDir: dir, now: clk, capUSD: 1000, iterationCap: 10 });
     assert.equal(s.sessions, 10);
     assert.equal(s.band, 100, "iteration cap should drive band to 100");
-    assert.equal(s.essentialOnly, true);
+    assert.equal(s.mode, "degraded");
+    assert.equal(s.posture.selfDirected, false, "D3 stops at the degrade rung");
   } finally { await rm(dir); }
 });
 
@@ -99,12 +119,15 @@ test("dailyStatus: iteration cap can be the binding constraint", async () => {
 // essential-only at 100%
 // ---------------------------------------------------------------------------
 
-test("essentialOnly is true only at/after 100%", async () => {
+test("essentialOnly (the legacy flag) now means the SUSPEND rung at 125%", async () => {
   const dir = await makeLedgerDir();
   try {
-    seedLedger(dir, [{ usd: 9.99 }]);
-    assert.equal(dailyStatus({ ledgerDir: dir, now: clk, capUSD: 10 }).essentialOnly, false);
+    // 100% degrades — inbox + obligations continue on the cheapest class — so
+    // the legacy all-or-nothing flag must NOT be set there. That rung was the
+    // one the old binary gate collapsed.
     seedLedger(dir, [{ usd: 10 }]);
+    assert.equal(dailyStatus({ ledgerDir: dir, now: clk, capUSD: 10 }).essentialOnly, false);
+    seedLedger(dir, [{ usd: 12.5 }]);
     assert.equal(dailyStatus({ ledgerDir: dir, now: clk, capUSD: 10 }).essentialOnly, true);
   } finally { await rm(dir); }
 });
@@ -119,24 +142,29 @@ test("maybeNotify fires once per band and never repeats within the day", async (
     const notices = [];
     const notify = (n) => notices.push(n.band);
 
-    // 60% → notify band 50 once.
-    seedLedger(dir, [{ usd: 6 }]);
-    let r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify });
+    // A supervisor must exist or the notice is logged and sent nowhere by
+    // design — see maybeNotify. Inject one.
+    const seat = { seatEnvelope: { seatBudgetCents: null, supervisorMemberId: "M-SUP" } };
+
+    // 85% → notify band 80 once.
+    seedLedger(dir, [{ usd: 8.5 }]);
+    let r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify, ...seat });
     assert.equal(r.notified, true);
-    assert.equal(r.band, 50);
+    assert.equal(r.band, 80);
+    assert.deepEqual(r.recipient, { memberId: "M-SUP", role: "REVIEWER" });
 
-    // Still 60% → no repeat.
-    r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify });
+    // Still 85% → no repeat.
+    r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify, ...seat });
     assert.equal(r.notified, false);
 
-    // Climb to 80% → notify band 75 once.
-    seedLedger(dir, [{ usd: 8 }]);
-    r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify });
+    // Climb to 105% → notify band 100 once.
+    seedLedger(dir, [{ usd: 10.5 }]);
+    r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify, ...seat });
     assert.equal(r.notified, true);
-    assert.equal(r.band, 75);
+    assert.equal(r.band, 100);
 
-    assert.deepEqual(notices, [50, 75]);
-    assert.deepEqual(readNotified({ ledgerDir: dir, now: clk }).notified_bands, [50, 75]);
+    assert.deepEqual(notices, [80, 100]);
+    assert.deepEqual(readNotified({ ledgerDir: dir, now: clk }).notified_bands, [80, 100]);
   } finally { await rm(dir); }
 });
 
@@ -144,42 +172,63 @@ test("maybeNotify on a big jump notifies once at the highest crossed band", asyn
   const dir = await makeLedgerDir();
   try {
     const notices = [];
-    // Jump straight from $0 to 95% — should surface ONE notice at band 90,
-    // and record 50/75/90 as all notified so they never re-fire.
-    seedLedger(dir, [{ usd: 9.5 }]);
-    const r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n.band) });
+    // Jump straight from $0 to 130% — ONE notice at band 125, with 80/100/125
+    // all recorded so they never re-fire.
+    const seat = { seatEnvelope: { seatBudgetCents: null, supervisorMemberId: "M-SUP" } };
+    seedLedger(dir, [{ usd: 13 }]);
+    const r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n.band), ...seat });
     assert.equal(r.notified, true);
-    assert.equal(r.band, 90);
-    assert.deepEqual(notices, [90], "exactly one notice surfaced");
-    assert.deepEqual(readNotified({ ledgerDir: dir, now: clk }).notified_bands, [50, 75, 90]);
+    assert.equal(r.band, 125);
+    assert.deepEqual(notices, [125], "exactly one notice surfaced");
+    assert.deepEqual(readNotified({ ledgerDir: dir, now: clk }).notified_bands, [80, 100, 125]);
 
     // A later check at the same level does nothing.
-    const r2 = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n.band) });
+    const r2 = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n.band), ...seat });
     assert.equal(r2.notified, false);
-    assert.deepEqual(notices, [90]);
+    assert.deepEqual(notices, [125]);
   } finally { await rm(dir); }
 });
 
-test("maybeNotify reaching 100% surfaces the essential-only notice once", async () => {
+test("maybeNotify past 150% surfaces the refuse notice once", async () => {
   const dir = await makeLedgerDir();
   try {
     const notices = [];
-    seedLedger(dir, [{ usd: 11 }]); // 110%
-    const r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n) });
+    const seat = { seatEnvelope: { seatBudgetCents: null, supervisorMemberId: "M-SUP" } };
+    seedLedger(dir, [{ usd: 16 }]); // 160%
+    const r = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n), ...seat });
     assert.equal(r.notified, true);
-    assert.equal(r.band, 100);
-    assert.match(r.message, /essential-only/i);
-    assert.equal(r.status.essentialOnly, true);
+    assert.equal(r.band, 150);
+    assert.match(r.message, /REFUSING new sessions that are not a direct human reply/);
+    assert.equal(r.status.posture.refuseNonHumanSpawn, true);
     // All bands recorded; a repeat is a no-op.
-    assert.deepEqual(readNotified({ ledgerDir: dir, now: clk }).notified_bands, [50, 75, 90, 100]);
-    const r2 = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n) });
+    assert.deepEqual(readNotified({ ledgerDir: dir, now: clk }).notified_bands, [80, 100, 125, 150]);
+    const r2 = maybeNotify({ ledgerDir: dir, now: clk, capUSD: 10, notify: (n) => notices.push(n), ...seat });
     assert.equal(r2.notified, false);
     assert.equal(notices.length, 1);
   } finally { await rm(dir); }
 });
 
-test("BANDS is the canonical 50/75/90/100 ladder", () => {
-  assert.deepEqual(BANDS, [50, 75, 90, 100]);
+test("a seat with NO supervisor edge is never told its own budget band", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    const notices = [];
+    const logged = [];
+    seedLedger(dir, [{ usd: 9 }]); // 90% → band 80
+    const r = maybeNotify({
+      ledgerDir: dir, now: clk, capUSD: 10,
+      notify: (n) => notices.push(n),
+      log: (level, msg) => logged.push(`${level}:${msg}`),
+    });
+    assert.equal(r.band, 80);
+    assert.equal(r.recipient, null);
+    assert.equal(notices.length, 0, "no notice may be delivered to the owner");
+    assert.ok(logged.some((l) => l.startsWith("error:") && /NO supervisor edge/.test(l)),
+      "the missing edge must be LOUD, not silent");
+  } finally { await rm(dir); }
+});
+
+test("BANDS is the canonical 80/100/125/150 governance ladder", () => {
+  assert.deepEqual(BANDS, [80, 100, 125, 150]);
 });
 
 // ---------------------------------------------------------------------------
@@ -204,7 +253,7 @@ test("dailyStatus reads the cap from config/recovery.yaml when present", async (
     assert.equal(s.capUSD, 40, "cap should come from recovery.yaml, not the 25 default");
     assert.equal(s.spentUSD, 20);
     assert.equal(s.pct, 50, "20/40 = 50%");
-    assert.equal(s.band, 50);
+    assert.equal(s.band, 0, "50% of the ceiling degrades nothing");
   } finally { await rm(dir); }
 });
 
@@ -218,8 +267,8 @@ test("recovery.yaml cap takes precedence over DAILY_SPEND_CAP_USD env", async ()
     seedLedger(join(dir, "state", "cost-tracking"), [{ usd: 10 }]);
     const s = dailyStatus({ agentRoot: dir, now: clk });
     assert.equal(s.capUSD, 10, "yaml cap must win over the env cap");
-    assert.equal(s.band, 100, "10/10 spent under the yaml cap is 100% (essential-only)");
-    assert.equal(s.essentialOnly, true);
+    assert.equal(s.band, 100, "10/10 spent under the yaml cap is the 100% degrade rung");
+    assert.equal(s.mode, "degraded");
   } finally {
     if (prevEnv === undefined) delete process.env.DAILY_SPEND_CAP_USD;
     else process.env.DAILY_SPEND_CAP_USD = prevEnv;

package/lib/cadences.mjs

@@ -48,6 +48,11 @@ export const STANDARD_CADENCES = [
   // job is actually due, so the consumer spawns a session to action it.
   // nightly-cost-reconcile: three-way spend reconcile vs the Admin Cost API
   // (fails open with no fetchImpl); flags drift > 10%. Inline, no prompt.
+  // nightly-backup: the DR job. Inline (tar + optional upload, no LLM). 03:10 —
+  // quiet hours, and ahead of nightly-cost-reconcile so the archive captures the
+  // day's ledger before anything rewrites it. See lib/backup/policy.mjs for what
+  // is archived, where, and what is never archived at all.
+  { id: "nightly-backup", scope: "standard", mode: "inline", calendar: { hour: 3, minute: 10 } },
   { id: "nightly-cost-reconcile", scope: "standard", mode: "inline", calendar: { hour: 3, minute: 30 } },
   // fleet-cost-digest: build the daily fleet LLM-spend digest. Inline, no prompt.
   { id: "fleet-cost-digest", scope: "standard", mode: "inline", calendar: { hour: 7, minute: 0 } },
@@ -113,6 +118,34 @@ export const ALTITUDE_CADENCES = {
   ],
 };
 
+/**
+ * THE HUMAN LANE. Cadences whose job is getting a human's message to the agent
+ * and the agent's answer back — the work Invariant #1 says never goes dark.
+ *
+ * This exists because the budget ladder's top rung ("refuse anything that is not
+ * a direct human reply") was implemented as `obligation.kind !== "REACT"`, and
+ * every cadence the consumer evaluates is a SCHEDULE. At band 150 that blocked
+ * 19 of 26 obligations including `inbox-processor` and `messaging-inbound` — the
+ * cadence that PULLS Cohort DMs and @mentions into the inbox pipeline at all. It
+ * only looked harmless because both guards default to `decision:"inline"` and
+ * return before the gate; set `INBOX_CADENCE_ESCALATE=1` or
+ * `MESSAGING_INBOUND_ESCALATE=1` (the documented cadence-only mode for operators
+ * running without the reactive daemon) and the seat stopped answering its inbox
+ * at 150 %, which is the exact failure the rung was written to avoid.
+ *
+ * Membership test: does a human wait on the other end of this cadence?
+ *   inbox-processor    — drains the inbox a human wrote into.
+ *   messaging-inbound  — the only puller of org DMs/@mentions.
+ *   dynamic-jobs       — DELIBERATELY NOT here: those are the agent's own
+ *                        reminders to itself, not somebody waiting on a reply.
+ */
+export const HUMAN_LANE_CADENCES = Object.freeze(new Set(["inbox-processor", "messaging-inbound"]));
+
+/** Is this cadence part of the human-reply lane? See {@link HUMAN_LANE_CADENCES}. */
+export function isHumanLaneCadence(id) {
+  return HUMAN_LANE_CADENCES.has(String(id || ""));
+}
+
 /** Cadence keywords that map to a recurring schedule (event-driven is excluded). */
 export const RECURRING = new Set(["daily", "weekly", "monthly", "quarterly", "continuous"]);
 

package/lib/channels/orgmail/adapter.mjs

@@ -50,6 +50,10 @@ import { BaseAdapter, CHANNEL_COUNTERS } from "../base-adapter.mjs";
 import { randomUUID } from "node:crypto";
 import { loadOrgConfig, configFromAgent } from "../../org/client.mjs";
 import { emailSend, emailMarkRead, emailInbox, emailMessage } from "../../org/ui-parity.mjs";
+import { RepeatSuppressor } from "../repeat-suppressor.mjs";
+// One classifier for every surface that reports an email.* failure (this poll
+// loop, `maestro doctor`, `maestro setup`) — see lib/org/email-remedy.mjs.
+import { remedyFor } from "../../org/email-remedy.mjs";
 
 export const ORGMAIL_CAPABILITIES = [
   CHANNEL_CAPABILITIES.SEND,
@@ -60,6 +64,17 @@ export const ORGMAIL_CAPABILITIES = [
 /** Default poll cadence — the messaging-inbound rhythm. */
 export const DEFAULT_POLL_MS = 45_000;
 
+/**
+ * Poll cadence while a TERMINAL condition stands (no mailbox assigned, key not
+ * paired, key lacks the email scope). These need a human act in Cohort; the
+ * 45s rhythm cannot fix them and only produces log noise and pointless load, so
+ * the loop drops to 10 minutes and self-heals the moment the condition clears.
+ */
+export const DEGRADED_POLL_MS = 10 * 60_000;
+
+/** Condition key for the standing-inbox-failure suppressor. */
+const INBOX_CONDITION = "email.inbox";
+
 export class OrgMailAdapter extends BaseAdapter {
   /**
    * @param {object} opts
@@ -88,6 +103,13 @@ export class OrgMailAdapter extends BaseAdapter {
     this._pollMs = resolvePollMs(opts.pollMs, gate, process.env);
     this._timer = null;
     this._polling = false;
+    // Standing-condition tracker: a mailbox that does not exist is one FACT,
+    // not one fact per 45 seconds. See lib/channels/repeat-suppressor.mjs.
+    this._suppressor = opts.suppressor || new RepeatSuppressor({ restateMs: opts.restateMs });
+    // Set while a terminal condition stands, so healthCheck and the daemon can
+    // report WHY the lane is down without re-probing.
+    this._standingFault = null;
+    this._degraded = false;
   }
 
   /** Resolve {base, token, orgId} from config/org.yaml (the enrollment SoT). */
@@ -122,10 +144,31 @@ export class OrgMailAdapter extends BaseAdapter {
     }
 
     await tick(); // first sweep immediately so start() sees a live adapter
-    this._timer = this._setInterval(tick, this._pollMs);
+    this._startTimer(tick);
+  }
+
+  /**
+   * (Re)arm the poll timer at the cadence the CURRENT state deserves: the
+   * configured rhythm normally, DEGRADED_POLL_MS while a terminal condition
+   * stands. Called on every transition so recovery is immediate — the first
+   * successful sweep after an admin assigns the mailbox restores 45s polling.
+   */
+  _startTimer(tick) {
+    if (this._timer) this._clearInterval(this._timer);
+    const ms = this._degraded ? DEGRADED_POLL_MS : this._pollMs;
+    this._tick = tick;
+    this._timer = this._setInterval(tick, ms);
     if (this._timer && typeof this._timer.unref === "function") this._timer.unref();
   }
 
+  /** Enter/leave degraded cadence, re-arming the timer only on a transition. */
+  _setDegraded(next, reason) {
+    if (this._degraded === next) return;
+    this._degraded = next;
+    this._standingFault = next ? reason : null;
+    if (this._tick) this._startTimer(this._tick);
+  }
+
   /**
    * One inbox sweep: list unread summaries, fetch each full DTO (newest LAST
    * so downstream sees chronological order), hand off, then markRead ONLY on a
@@ -137,9 +180,30 @@ export class OrgMailAdapter extends BaseAdapter {
     if (!o.base || !o.token) return; // not enrolled — dormant, never throws
     const inbox = await emailInbox({ unreadOnly: true, limit: 50 }, o);
     if (!inbox.ok) {
-      this.log("warn", `email.inbox error: ${inbox.error?.code || "?"} ${inbox.error?.message || ""}`);
+      // A standing failure is ONE fact, not one fact per tick. Before this, a
+      // seat with no mailbox wrote the same NOT_FOUND line 478 times in a day —
+      // true every time, useful once, and loud enough to bury everything else.
+      // Now: full detail on the first occurrence, a re-statement with the
+      // suppressed count once an hour, an explicit RESOLVED line on recovery,
+      // and a 10-minute poll while the condition needs a human to clear it.
+      const code = inbox.error?.code || "?";
+      const seen = this._suppressor.observe(INBOX_CONDITION, { code });
+      if (seen.emit) {
+        this.log(
+          seen.terminal ? "error" : "warn",
+          `email.inbox ${code}: ${inbox.error?.message || "no detail"}` +
+            (seen.terminal ? ` — ${remedyFor(code)}` : "") +
+            seen.suffix
+        );
+      }
+      this._setDegraded(seen.terminal, seen.terminal ? { code, message: inbox.error?.message || "", since: new Date().toISOString() } : null);
       return;
     }
+    const recovered = this._suppressor.clear(INBOX_CONDITION);
+    if (recovered.wasActive) {
+      this.log("info", `email.inbox ${recovered.message} — the workspace mailbox lane is live again`);
+    }
+    this._setDegraded(false, null);
     const summaries = Array.isArray(inbox.result?.messages) ? inbox.result.messages : [];
     // Server returns newest-first (keyset createdAt desc); we deliver newest-LAST.
     const ordered = [...summaries].reverse();
@@ -289,7 +353,28 @@ export class OrgMailAdapter extends BaseAdapter {
       const addr = r.result?.mailbox?.address || "";
       return { ok: true, detail: `orgmail mailbox ${addr || "reachable"}` };
     }
-    return { ok: false, detail: `orgmail: ${r.error?.code || "?"} ${r.error?.message || "unreachable"}` };
+    // Suppressing the POLL log must not suppress the health ANSWER: the whole
+    // point of throttling repeats is that the standing condition stays legible
+    // somewhere. It lives here, and in `standingFault()`, so anything that asks
+    // gets the full story including the remedy.
+    const code = r.error?.code || "?";
+    const remedy = remedyFor(code);
+    return {
+      ok: false,
+      detail:
+        `orgmail: ${code} ${r.error?.message || "unreachable"}` +
+        (remedy ? ` — ${remedy}` : "") +
+        (this._degraded ? " (poll is degraded to 10m until this clears)" : ""),
+    };
+  }
+
+  /**
+   * The standing terminal condition, if any — `{code, message, since}`. Read by
+   * the daemon/doctor so "this lane is down and here is why" survives the log
+   * throttle. Null when the lane is healthy.
+   */
+  standingFault() {
+    return this._standingFault;
   }
 
   async stop() {

package/lib/channels/orgmail/adapter.test.mjs

@@ -20,6 +20,7 @@ import {
   resolvePollMs,
   htmlToText,
   DEFAULT_POLL_MS,
+  DEGRADED_POLL_MS,
   ORGMAIL_CAPABILITIES,
 } from "./adapter.mjs";
 import { getPlatform, isDaemonManagedPlatform } from "../contract.mjs";
@@ -309,3 +310,139 @@ test("healthCheck: missing enrollment is an honest unhealthy, not a throw", asyn
   assert.equal(h.ok, false);
   assert.match(h.detail, /enrollment missing/);
 });
+
+// ── standing-fault throttle (the 478-lines-a-day incident) ─────────────────
+//
+// A member with no mailbox made every 45s poll write the same NOT_FOUND line:
+// 478 of them on 2026-08-11, 164 the day before. The lane was dead and the
+// only signal was noise. These tests pin the fix: full detail once, silence in
+// between, a degraded poll while it needs a human, and an explicit recovery.
+
+/** A fake hq whose email.inbox fails with `code` until `heal()` is called. */
+function failingInbox(code, message = "no active mailbox is assigned to this agent") {
+  const state = { healed: false };
+  const fn = async (url) => {
+    const u = String(url);
+    const respond = (payload, status = 200, ok = true) => ({ ok, status, json: async () => payload, headers: { get: () => undefined } });
+    if (u.endsWith("/api/v1/email.inbox")) {
+      if (state.healed) {
+        return respond({ ok: true, result: { mailbox: { address: "astra@agents.example" }, messages: [], nextCursor: null } });
+      }
+      return respond({ ok: false, error: { code, message } }, 404, false);
+    }
+    return respond({ ok: true, result: {} });
+  };
+  fn.heal = () => { state.healed = true; };
+  return fn;
+}
+
+/** Build an adapter that captures its log lines and lets tests drive ticks. */
+function makeLoggingAdapter(fetchImpl, over = {}) {
+  const logs = [];
+  const intervals = [];
+  const a = new OrgMailAdapter({
+    agentRoot: "/tmp/orgmail-test",
+    orgConfig: ORG_CFG,
+    config: { orgmail: { enabled: true, poll_seconds: 45, mark_read: true } },
+    fetchImpl,
+    supervise: false,
+    sendGate: false,
+    setInterval: (fn, ms) => { intervals.push({ fn, ms }); return { unref() {} }; },
+    clearInterval: () => {},
+    log: (level, msg) => logs.push({ level, msg }),
+    ...over,
+  });
+  return { a, logs, intervals };
+}
+
+test("standing NOT_FOUND: the first poll logs it IN FULL with the remedy", async () => {
+  const { a, logs } = makeLoggingAdapter(failingInbox("NOT_FOUND"));
+  await a.start({ onInbound: () => {} });
+  await settle();
+  const line = logs.find((l) => /email\.inbox NOT_FOUND/.test(l.msg));
+  assert.ok(line, "the first occurrence must be logged");
+  assert.equal(line.level, "error", "a dead lane is not a warning");
+  assert.match(line.msg, /workspace ADMIN/, "an ACTOR");
+  assert.match(line.msg, /Settings → Email → Mailboxes/, "and an ACT");
+  await a.stop();
+});
+
+test("standing NOT_FOUND: 40 further polls add ZERO lines (the incident, prevented)", async () => {
+  const { a, logs, intervals } = makeLoggingAdapter(failingInbox("NOT_FOUND"));
+  await a.start({ onInbound: () => {} });
+  await settle();
+  const afterFirst = logs.length;
+  const tick = intervals[intervals.length - 1].fn;
+  for (let i = 0; i < 40; i += 1) { await tick(); await settle(); }
+  assert.equal(logs.length, afterFirst, `expected no repeats, got ${logs.length - afterFirst}`);
+  await a.stop();
+});
+
+test("standing NOT_FOUND degrades the poll to 10m — no point hammering a human-gated fault", async () => {
+  const { a, intervals } = makeLoggingAdapter(failingInbox("NOT_FOUND"));
+  await a.start({ onInbound: () => {} });
+  await settle();
+  assert.equal(intervals[intervals.length - 1].ms, DEGRADED_POLL_MS);
+  await a.stop();
+});
+
+test("recovery: the mailbox appearing logs RESOLVED and restores the normal cadence", async () => {
+  const fetchImpl = failingInbox("NOT_FOUND");
+  const { a, logs, intervals } = makeLoggingAdapter(fetchImpl);
+  await a.start({ onInbound: () => {} });
+  await settle();
+  const tick = intervals[intervals.length - 1].fn;
+  for (let i = 0; i < 5; i += 1) { await tick(); await settle(); }
+
+  fetchImpl.heal(); // an admin assigns the mailbox
+  await tick();
+  await settle();
+
+  const resolved = logs.find((l) => /RESOLVED/.test(l.msg));
+  assert.ok(resolved, "recovery must be stated explicitly, not inferred from silence");
+  assert.match(resolved.msg, /6 failed attempt/);
+  assert.match(resolved.msg, /live again/);
+  assert.equal(intervals[intervals.length - 1].ms, 45_000, "normal cadence restored");
+  assert.equal(a.standingFault(), null);
+  await a.stop();
+});
+
+test("a NON-terminal error keeps the normal cadence and stays a warn", async () => {
+  const { a, logs, intervals } = makeLoggingAdapter(failingInbox("INTERNAL", "boom"));
+  await a.start({ onInbound: () => {} });
+  await settle();
+  const line = logs.find((l) => /email\.inbox INTERNAL/.test(l.msg));
+  assert.equal(line.level, "warn", "a transient server error is not a dead lane");
+  assert.equal(intervals[intervals.length - 1].ms, 45_000);
+  assert.equal(a.standingFault(), null);
+  await a.stop();
+});
+
+test("throttling the LOG never throttles the ANSWER: healthCheck still states the fault + remedy", async () => {
+  const { a, intervals } = makeLoggingAdapter(failingInbox("NOT_FOUND"));
+  await a.start({ onInbound: () => {} });
+  await settle();
+  const tick = intervals[intervals.length - 1].fn;
+  for (let i = 0; i < 20; i += 1) { await tick(); await settle(); }
+  const h = await a.healthCheck();
+  assert.equal(h.ok, false);
+  assert.match(h.detail, /NOT_FOUND/);
+  assert.match(h.detail, /workspace ADMIN/);
+  assert.match(h.detail, /degraded to 10m/);
+  // And the machine-readable form, for doctor / state files.
+  const fault = a.standingFault();
+  assert.equal(fault.code, "NOT_FOUND");
+  assert.match(fault.since, /^\d{4}-/);
+  await a.stop();
+});
+
+test("FORBIDDEN_SCOPE gets the KEY remedy, not the mailbox one", async () => {
+  const { a, logs } = makeLoggingAdapter(failingInbox("FORBIDDEN_SCOPE", "not paired"));
+  await a.start({ onInbound: () => {} });
+  await settle();
+  const line = logs.find((l) => /email\.inbox FORBIDDEN_SCOPE/.test(l.msg));
+  assert.equal(line.level, "error");
+  assert.match(line.msg, /Settings → API keys/);
+  assert.ok(!/Settings → Email → Mailboxes/.test(line.msg), "wrong remedy for this cause");
+  await a.stop();
+});