@cohortapp/agent-sdk 2.14.0 → 2.16.0

package/lib/assurance/room-budget.test.mjs

@@ -0,0 +1,486 @@
+/**
+ * room-budget.test.mjs — one room, one interim, whatever else is going on.
+ *
+ * The production failure this pins: the interim budget was per OBLIGATION and
+ * never per ROOM. Eight agents with N concurrent obligations each in
+ * `capital-formation` emitted up to N acks + 2N progress pings + N failure
+ * notices into one channel — 9,187 messages in 21 days, ~45 % of them exact
+ * duplicates, two independent timers narrating the same overlapping work at the
+ * same timestamp. Every one of those decisions was individually correct.
+ *
+ * Run: node --test lib/assurance/room-budget.test.mjs
+ */
+
+import { test, describe, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  DEFAULT_ROOM_INTERIM_WINDOW_MS,
+  DEFAULT_ROOM_NOTICE_WINDOW_MS,
+  roomInterimWindowMs,
+  roomNoticeWindowMs,
+  roomKey,
+  noticeKey,
+  textDigest,
+  interimAllowed,
+  noticeAllowed,
+  recordInterim,
+  recordNotice,
+  pruneLedger,
+  claimRoomInterim,
+  claimRoomNotice,
+  ledgerPath,
+  LEDGER_BASENAME,
+  readLedger,
+  _emptyLedger,
+} from "./room-budget.mjs";
+
+const ROOM_INTERIM_WINDOW_MS = DEFAULT_ROOM_INTERIM_WINDOW_MS;
+
+const T0 = 1_757_000_000_000; // a fixed instant; nothing here reads a clock
+
+// ---------------------------------------------------------------------------
+// The pure half
+// ---------------------------------------------------------------------------
+
+describe("roomKey — a room is (service, channel) and nothing else", () => {
+  test("service and channel together name the room", () => {
+    assert.equal(roomKey({ service: "cohort", channel: "C-CAPFORM" }), "cohort|c-capform");
+  });
+
+  test("case and surrounding space never make two rooms out of one", () => {
+    assert.equal(roomKey({ service: "Cohort", channel: " C-CapForm " }), roomKey({ service: "cohort", channel: "c-capform" }));
+  });
+
+  test("a missing channel is still a room, not a crash", () => {
+    assert.equal(typeof roomKey({ service: "cohort", channel: null }), "string");
+    assert.equal(typeof roomKey({}), "string");
+    assert.equal(typeof roomKey(), "string");
+  });
+
+  test("two different channels on one service are two rooms", () => {
+    assert.notEqual(roomKey({ service: "cohort", channel: "A" }), roomKey({ service: "cohort", channel: "B" }));
+  });
+
+  test("the same channel name on two services is two rooms", () => {
+    assert.notEqual(roomKey({ service: "cohort", channel: "general" }), roomKey({ service: "slack", channel: "general" }));
+  });
+});
+
+describe("interimAllowed — the pure decision", () => {
+  test("an empty ledger allows the first interim", () => {
+    const v = interimAllowed({ ledger: _emptyLedger(), service: "cohort", channel: "C1", now: T0 });
+    assert.equal(v.allowed, true);
+    assert.equal(v.reason, "room-budget-free");
+  });
+
+  test("a second interim inside the window is refused, and says which room and when", () => {
+    const led = recordInterim({ ledger: _emptyLedger(), service: "cohort", channel: "C1", now: T0 });
+    const v = interimAllowed({ ledger: led, service: "cohort", channel: "C1", now: T0 + 60_000 });
+    assert.equal(v.allowed, false);
+    assert.equal(v.reason, "room-budget-spent");
+    assert.equal(v.lastAt, T0);
+    assert.equal(v.room, roomKey({ service: "cohort", channel: "C1" }));
+  });
+
+  test("the window reopens exactly at the boundary, not a millisecond early", () => {
+    const led = recordInterim({ ledger: _emptyLedger(), service: "cohort", channel: "C1", now: T0 });
+    assert.equal(interimAllowed({ ledger: led, service: "cohort", channel: "C1", now: T0 + ROOM_INTERIM_WINDOW_MS - 1 }).allowed, false);
+    assert.equal(interimAllowed({ ledger: led, service: "cohort", channel: "C1", now: T0 + ROOM_INTERIM_WINDOW_MS }).allowed, true);
+  });
+
+  test("a spent room never silences a DIFFERENT room", () => {
+    const led = recordInterim({ ledger: _emptyLedger(), service: "cohort", channel: "C1", now: T0 });
+    assert.equal(interimAllowed({ ledger: led, service: "cohort", channel: "C2", now: T0 + 1 }).allowed, true);
+    assert.equal(interimAllowed({ ledger: led, service: "slack", channel: "C1", now: T0 + 1 }).allowed, true);
+  });
+
+  test("a clock that goes backwards does not hand out a free interim", () => {
+    // NTP steps, a restored snapshot, a test harness. `now` before the recorded
+    // stamp must read as "inside the window", never as "the window elapsed".
+    const led = recordInterim({ ledger: _emptyLedger(), service: "cohort", channel: "C1", now: T0 });
+    assert.equal(interimAllowed({ ledger: led, service: "cohort", channel: "C1", now: T0 - 60 * 60_000 }).allowed, false);
+  });
+
+  test("a corrupt or absent entry reads as 'never spoken here', never as a permanent gag", () => {
+    for (const bad of [{ rooms: null }, { rooms: { "cohort|c1": "yesterday" } }, {}, null, undefined, "nonsense"]) {
+      assert.equal(interimAllowed({ ledger: bad, service: "cohort", channel: "C1", now: T0 }).allowed, true, `${JSON.stringify(bad)} must fail open`);
+    }
+  });
+
+  test("the decision is pure: it never mutates the ledger it is given", () => {
+    const led = recordInterim({ ledger: _emptyLedger(), service: "cohort", channel: "C1", now: T0 });
+    const before = JSON.stringify(led);
+    interimAllowed({ ledger: led, service: "cohort", channel: "C1", now: T0 + 1 });
+    assert.equal(JSON.stringify(led), before);
+  });
+
+  test("the window is env-tunable and defaults to fifteen minutes", () => {
+    assert.equal(DEFAULT_ROOM_INTERIM_WINDOW_MS, 15 * 60_000);
+    const led = recordInterim({ ledger: _emptyLedger(), service: "cohort", channel: "C1", now: T0 });
+    assert.equal(interimAllowed({ ledger: led, service: "cohort", channel: "C1", now: T0 + 2000, windowMs: 1000 }).allowed, true);
+  });
+});
+
+describe("recordInterim / pruneLedger", () => {
+  test("recording returns a NEW ledger and leaves the old one untouched", () => {
+    const led = _emptyLedger();
+    const next = recordInterim({ ledger: led, service: "cohort", channel: "C1", now: T0 });
+    assert.notEqual(led, next);
+    assert.deepEqual(led.rooms, {});
+    assert.equal(next.rooms[roomKey({ service: "cohort", channel: "C1" })], T0);
+  });
+
+  test("the ledger does not grow without bound — entries older than two windows are dropped", () => {
+    // The store is a durable file on a machine that runs for months. An entry
+    // that can never refuse anything again is landfill.
+    let led = _emptyLedger();
+    for (let i = 0; i < 50; i++) led = recordInterim({ ledger: led, service: "cohort", channel: `OLD-${i}`, now: T0 });
+    led = recordInterim({ ledger: led, service: "cohort", channel: "FRESH", now: T0 + 3 * ROOM_INTERIM_WINDOW_MS });
+    const pruned = pruneLedger({ ledger: led, now: T0 + 3 * ROOM_INTERIM_WINDOW_MS });
+    assert.equal(Object.keys(pruned.rooms).length, 1);
+    assert.ok(pruned.rooms[roomKey({ service: "cohort", channel: "FRESH" })]);
+  });
+
+  test("pruning never drops an entry that can still refuse an interim", () => {
+    const led = recordInterim({ ledger: _emptyLedger(), service: "cohort", channel: "C1", now: T0 });
+    const pruned = pruneLedger({ ledger: led, now: T0 + ROOM_INTERIM_WINDOW_MS });
+    assert.equal(interimAllowed({ ledger: pruned, service: "cohort", channel: "C1", now: T0 + ROOM_INTERIM_WINDOW_MS - 1 }).allowed, false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The durable edge
+// ---------------------------------------------------------------------------
+
+describe("claimRoomInterim — the durable edge, with an injected clock and fs", () => {
+  let ROOT;
+  beforeEach(() => {
+    if (ROOT) { try { rmSync(ROOT, { recursive: true, force: true }); } catch { /* */ } }
+    ROOT = mkdtempSync(join(tmpdir(), "room-budget-"));
+  });
+
+  test("THE FLOOD FIX: N concurrent obligations in one room yield exactly ONE interim", () => {
+    // 8 agents' worth of concurrent asks, arriving together, as measured.
+    const said = [];
+    for (let i = 0; i < 40; i++) {
+      const v = claimRoomInterim({ service: "cohort", channel: "capital-formation", now: T0 + i * 1000, agentRoot: ROOT });
+      if (v.allowed) said.push(i);
+    }
+    assert.deepEqual(said, [0], `expected one interim across 40 obligations, got ${said.length}`);
+  });
+
+  test("…and the next window allows exactly one more, not a backlog burst", () => {
+    for (let i = 0; i < 40; i++) claimRoomInterim({ service: "cohort", channel: "capital-formation", now: T0 + i * 1000, agentRoot: ROOT });
+    let allowed = 0;
+    for (let i = 0; i < 40; i++) {
+      if (claimRoomInterim({ service: "cohort", channel: "capital-formation", now: T0 + ROOM_INTERIM_WINDOW_MS + i * 1000, agentRoot: ROOT }).allowed) allowed++;
+    }
+    assert.equal(allowed, 1);
+  });
+
+  test("a refused claim writes nothing and does not move the window", () => {
+    claimRoomInterim({ service: "cohort", channel: "C1", now: T0, agentRoot: ROOT });
+    claimRoomInterim({ service: "cohort", channel: "C1", now: T0 + 10 * 60_000, agentRoot: ROOT });
+    // If the refused claim had stamped the ledger, the window would run from
+    // T0+10min and the room would stay gagged past T0+15min.
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "C1", now: T0 + ROOM_INTERIM_WINDOW_MS, agentRoot: ROOT }).allowed, true);
+  });
+
+  test("busy rooms never gag quiet ones", () => {
+    for (let i = 0; i < 20; i++) claimRoomInterim({ service: "cohort", channel: "busy", now: T0 + i, agentRoot: ROOT });
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "quiet", now: T0 + 100, agentRoot: ROOT }).allowed, true);
+  });
+
+  test("the store is durable — a fresh process sees the spend", () => {
+    claimRoomInterim({ service: "cohort", channel: "C1", now: T0, agentRoot: ROOT });
+    const onDisk = JSON.parse(readFileSync(ledgerPath(ROOT), "utf-8"));
+    assert.equal(onDisk.rooms[roomKey({ service: "cohort", channel: "C1" })], T0);
+    assert.equal(readLedger({ agentRoot: ROOT }).rooms[roomKey({ service: "cohort", channel: "C1" })], T0);
+  });
+
+  test("it lives beside the obligation ledger it governs", () => {
+    assert.equal(ledgerPath(ROOT), join(ROOT, "state", "obligations", "room-budget.json"));
+  });
+
+  test("an unreadable store fails OPEN — a broken file may not silence a human", () => {
+    mkdirSync(join(ROOT, "state", "obligations"), { recursive: true });
+    writeFileSync(ledgerPath(ROOT), "{ this is not json");
+    const v = claimRoomInterim({ service: "cohort", channel: "C1", now: T0, agentRoot: ROOT });
+    assert.equal(v.allowed, true);
+    assert.equal(v.degraded, true, "…but it SAYS it is degraded, so the condition is measurable");
+  });
+
+  test("an unwritable store still lets the message out, and says so", () => {
+    const v = claimRoomInterim({
+      service: "cohort", channel: "C1", now: T0, agentRoot: ROOT,
+      deps: { writeImpl: () => { throw new Error("EROFS"); } },
+    });
+    assert.equal(v.allowed, true);
+    assert.equal(v.degraded, true);
+  });
+
+  test("the clock is injected, never read from the wall", () => {
+    // Passing `now` is the contract; omitting it is a caller bug, not a licence
+    // to read Date.now() from inside a decision module.
+    const v = claimRoomInterim({ service: "cohort", channel: "C1", agentRoot: ROOT });
+    assert.equal(v.allowed, false);
+    assert.equal(v.reason, "no-clock");
+  });
+
+  test("fs is injectable end to end — no real filesystem needed", () => {
+    let stored = null;
+    const deps = {
+      readImpl: () => stored,
+      writeImpl: (_p, obj) => { stored = obj; },
+    };
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "C1", now: T0, agentRoot: ROOT, deps }).allowed, true);
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "C1", now: T0 + 1, agentRoot: ROOT, deps }).allowed, false);
+    assert.equal(stored.rooms[roomKey({ service: "cohort", channel: "C1" })], T0);
+  });
+});
+
+describe("claimRoomInterim commit:false — ask without spending", () => {
+  let ROOT;
+  beforeEach(() => {
+    if (ROOT) { try { rmSync(ROOT, { recursive: true, force: true }); } catch { /* */ } }
+    ROOT = mkdtempSync(join(tmpdir(), "room-budget-peek-"));
+  });
+
+  test("a peek does not spend the budget", () => {
+    // The interim's text comes from a model call that can fail. Spending the
+    // room's fifteen minutes BEFORE the message exists gags the room in
+    // exchange for nothing — so the caller asks first, composes, then claims.
+    const peek = claimRoomInterim({ service: "cohort", channel: "C1", now: T0, agentRoot: ROOT, commit: false });
+    assert.equal(peek.allowed, true);
+    assert.equal(peek.committed, false);
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "C1", now: T0 + 1, agentRoot: ROOT }).allowed, true, "the peek left the budget unspent");
+  });
+
+  test("a peek still reports a spent room", () => {
+    claimRoomInterim({ service: "cohort", channel: "C1", now: T0, agentRoot: ROOT });
+    const peek = claimRoomInterim({ service: "cohort", channel: "C1", now: T0 + 1000, agentRoot: ROOT, commit: false });
+    assert.equal(peek.allowed, false);
+    assert.equal(peek.reason, "room-budget-spent");
+  });
+
+  test("a committing claim says so", () => {
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "C1", now: T0, agentRoot: ROOT }).committed, true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The HONEST SCOPE of the guarantee
+// ---------------------------------------------------------------------------
+
+describe("the budget is per (SEAT, service, channel) — not per (service, channel)", () => {
+  let A, B;
+  beforeEach(() => {
+    A = mkdtempSync(join(tmpdir(), "room-seat-a-"));
+    B = mkdtempSync(join(tmpdir(), "room-seat-b-"));
+  });
+
+  test("two seats in ONE room each get their own interim, because they share no store", () => {
+    // This is the arithmetic the module header now states rather than glosses.
+    // `agentRoot` is AGENT_DIR — one agent's repo on one Mac mini. There is no
+    // shared filesystem between seats, so the guarantee this module can make is
+    // per seat. The measured room had EIGHT seats in it: the ceiling this gate
+    // alone imposes there is 8 x (60/15) = 32 interims an hour, against a
+    // measured content-free rate of ~14/h. It is the backstop, not the thing
+    // that removed the measured flood.
+    //
+    // Pinned as a TEST rather than left in prose because the comment that said
+    // otherwise survived a review: an operator who reads "one room, one message"
+    // will size the next change wrong.
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "capital-formation", now: T0, agentRoot: A }).allowed, true);
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "capital-formation", now: T0 + 1, agentRoot: B }).allowed, true,
+      "a second SEAT is not gagged by the first — there is no store between them");
+    // …and within either seat the guarantee still holds absolutely.
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "capital-formation", now: T0 + 2, agentRoot: A }).allowed, false);
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "capital-formation", now: T0 + 3, agentRoot: B }).allowed, false);
+  });
+
+  test("the eight-seat ceiling is exactly eight per window, and no more", () => {
+    const seats = [];
+    for (let i = 0; i < 8; i++) seats.push(mkdtempSync(join(tmpdir(), `room-seat-${i}-`)));
+    let spoke = 0;
+    // Each seat tries ten times inside one window; each may speak once.
+    for (const seat of seats) {
+      for (let i = 0; i < 10; i++) {
+        if (claimRoomInterim({ service: "cohort", channel: "capital-formation", now: T0 + i, agentRoot: seat }).allowed) spoke++;
+      }
+    }
+    assert.equal(spoke, 8, "eight seats, eight interims per window — the honest ceiling");
+    for (const seat of seats) rmSync(seat, { recursive: true, force: true });
+  });
+});
+
+describe("the window default is resolved at the EDGE, never captured at import", () => {
+  // The gate report for this package claimed the pure modules read no
+  // clock/env/fs. A `const X = process.env.Y` at module scope falsified that
+  // and, more concretely, meant an operator who exported the variable after the
+  // first import silently got the stale default.
+  test("roomInterimWindowMs reads the env it is given, every time it is called", () => {
+    assert.equal(roomInterimWindowMs({}), DEFAULT_ROOM_INTERIM_WINDOW_MS);
+    assert.equal(roomInterimWindowMs({ ASSURANCE_ROOM_INTERIM_WINDOW_MS: "60000" }), 60_000);
+    assert.equal(roomNoticeWindowMs({ ASSURANCE_ROOM_NOTICE_WINDOW_MS: "1000" }), 1000);
+    // Garbage falls back rather than producing NaN, which would compare false
+    // against every elapsed time and make the budget decorative.
+    assert.equal(roomInterimWindowMs({ ASSURANCE_ROOM_INTERIM_WINDOW_MS: "soon" }), DEFAULT_ROOM_INTERIM_WINDOW_MS);
+    assert.equal(roomNoticeWindowMs(undefined) > 0, true);
+  });
+
+  test("an env set AFTER this module was first imported still takes effect", () => {
+    const ROOT = mkdtempSync(join(tmpdir(), "room-env-"));
+    const prev = process.env.ASSURANCE_ROOM_INTERIM_WINDOW_MS;
+    try {
+      process.env.ASSURANCE_ROOM_INTERIM_WINDOW_MS = "1000";
+      assert.equal(claimRoomInterim({ service: "cohort", channel: "C1", now: T0, agentRoot: ROOT }).allowed, true);
+      assert.equal(claimRoomInterim({ service: "cohort", channel: "C1", now: T0 + 999, agentRoot: ROOT }).allowed, false);
+      assert.equal(claimRoomInterim({ service: "cohort", channel: "C1", now: T0 + 1000, agentRoot: ROOT }).allowed, true,
+        "the one-second window was honoured, so the value was not folded at import time");
+    } finally {
+      if (prev === undefined) delete process.env.ASSURANCE_ROOM_INTERIM_WINDOW_MS;
+      else process.env.ASSURANCE_ROOM_INTERIM_WINDOW_MS = prev;
+      rmSync(ROOT, { recursive: true, force: true });
+    }
+  });
+
+  test("the pure decision never reads the environment — it defaults to the CONSTANT", () => {
+    const prev = process.env.ASSURANCE_ROOM_INTERIM_WINDOW_MS;
+    try {
+      process.env.ASSURANCE_ROOM_INTERIM_WINDOW_MS = "1000";
+      const led = recordInterim({ ledger: _emptyLedger(), service: "cohort", channel: "C1", now: T0 });
+      assert.equal(
+        interimAllowed({ ledger: led, service: "cohort", channel: "C1", now: T0 + 2000 }).allowed,
+        false,
+        "the pure function used the 15-minute constant, not the environment",
+      );
+    } finally {
+      if (prev === undefined) delete process.env.ASSURANCE_ROOM_INTERIM_WINDOW_MS;
+      else process.env.ASSURANCE_ROOM_INTERIM_WINDOW_MS = prev;
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Identical outcome notices
+// ---------------------------------------------------------------------------
+
+describe("textDigest / noticeKey", () => {
+  test("the same sentence digests the same however it is spaced", () => {
+    assert.equal(textDigest("Couldn't finish this — it timed out."), textDigest("  Couldn't finish   this — it timed out.  "));
+  });
+
+  test("a different sentence digests differently", () => {
+    assert.notEqual(textDigest("Hit a problem — it timed out. Retrying now."), textDigest("Couldn't finish this — it timed out."));
+  });
+
+  test("the key separates room, notice id and sentence", () => {
+    const base = { service: "cohort", channel: "C1", notice: "failure:final", text: "same" };
+    assert.notEqual(noticeKey(base), noticeKey({ ...base, channel: "C2" }));
+    assert.notEqual(noticeKey(base), noticeKey({ ...base, notice: "failure:retrying" }));
+    assert.notEqual(noticeKey(base), noticeKey({ ...base, text: "different" }));
+    assert.equal(noticeKey(base), noticeKey({ ...base }));
+  });
+});
+
+describe("claimRoomNotice — a byte-identical outcome notice is not said twice in one room", () => {
+  let ROOT;
+  const STALE = "Couldn't finish this — the work never came back with a result and has now outrun its time limit. I've stopped retrying and flagged it so it isn't lost.";
+  beforeEach(() => { ROOT = mkdtempSync(join(tmpdir(), "room-notice-")); });
+
+  test("THE SIBLING CASE: twenty debts, one sentence, one message", () => {
+    // The per-obligation notice ledger cannot reach this: twenty separate asks
+    // are twenty separate records, and the stale sentence carries nothing about
+    // which ask it is, so the reader gets the identical line twenty times and
+    // cannot tell any of them apart.
+    let said = 0;
+    for (let i = 0; i < 20; i++) {
+      if (claimRoomNotice({ service: "cohort", channel: "C-CAPFORM", notice: "failure:final", text: STALE, now: T0 + i * 1000, agentRoot: ROOT }).allowed) said++;
+    }
+    assert.equal(said, 1, `twenty identical failure sentences must reach one room once — got ${said}`);
+  });
+
+  test("a DIFFERENT sentence is never suppressed, at any volume", () => {
+    // This is the safety argument. Suppressing information a reader does not
+    // have re-creates the original bug: a person never told their work died.
+    let said = 0;
+    for (let i = 0; i < 20; i++) {
+      const text = `Couldn't finish this — cause number ${i}. I've stopped retrying.`;
+      if (claimRoomNotice({ service: "cohort", channel: "C-CAPFORM", notice: "failure:final", text, now: T0 + i * 1000, agentRoot: ROOT }).allowed) said++;
+    }
+    assert.equal(said, 20, "every distinct fact is still said");
+  });
+
+  test("'a retry is running' and 'I have stopped' stay separately sayable", () => {
+    const retrying = "Hit a problem — it timed out. Retrying now; if it fails again I'll come straight back.";
+    assert.equal(claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:retrying", text: retrying, now: T0, agentRoot: ROOT }).allowed, true);
+    assert.equal(claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:final", text: STALE, now: T0 + 1, agentRoot: ROOT }).allowed, true);
+  });
+
+  test("a different ROOM is never gagged by a busy one", () => {
+    claimRoomNotice({ service: "cohort", channel: "busy", notice: "failure:final", text: STALE, now: T0, agentRoot: ROOT });
+    assert.equal(claimRoomNotice({ service: "cohort", channel: "quiet", notice: "failure:final", text: STALE, now: T0 + 1, agentRoot: ROOT }).allowed, true);
+  });
+
+  test("the window reopens, because the same fact a day later is news again", () => {
+    claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:final", text: STALE, now: T0, agentRoot: ROOT });
+    assert.equal(claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:final", text: STALE, now: T0 + DEFAULT_ROOM_NOTICE_WINDOW_MS - 1, agentRoot: ROOT }).allowed, false);
+    assert.equal(claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:final", text: STALE, now: T0 + DEFAULT_ROOM_NOTICE_WINDOW_MS, agentRoot: ROOT }).allowed, true);
+  });
+
+  test("commit:false asks without spending", () => {
+    const peek = claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:final", text: STALE, now: T0, agentRoot: ROOT, commit: false });
+    assert.equal(peek.allowed, true);
+    assert.equal(peek.committed, false);
+    assert.equal(claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:final", text: STALE, now: T0 + 1, agentRoot: ROOT }).allowed, true,
+      "the peek left it unspent — a send that never happened must not silence the next one");
+  });
+
+  test("FAIL-OPEN, and the OPPOSITE way to the interim: no clock ⇒ say it", () => {
+    // An interim is a courtesy and is safe to drop. "Your work died" is not.
+    const v = claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:final", text: STALE, agentRoot: ROOT });
+    assert.equal(v.allowed, true);
+    assert.equal(v.degraded, true);
+  });
+
+  test("an unreadable ledger lets the notice through, flagged", () => {
+    mkdirSync(join(ROOT, "state", "obligations"), { recursive: true });
+    writeFileSync(ledgerPath(ROOT), "{ not json");
+    const v = claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:final", text: STALE, now: T0, agentRoot: ROOT });
+    assert.equal(v.allowed, true);
+    assert.equal(v.degraded, true);
+  });
+
+  test("interims and notices share one file without evicting each other", () => {
+    claimRoomInterim({ service: "cohort", channel: "C1", now: T0, agentRoot: ROOT });
+    claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:final", text: STALE, now: T0 + 1, agentRoot: ROOT });
+    const led = JSON.parse(readFileSync(ledgerPath(ROOT), "utf-8"));
+    assert.equal(Object.keys(led.rooms).length, 1, "the interim spend survived the notice write");
+    assert.equal(Object.keys(led.notices).length, 1);
+    assert.equal(claimRoomInterim({ service: "cohort", channel: "C1", now: T0 + 2, agentRoot: ROOT }).allowed, false);
+    assert.equal(claimRoomNotice({ service: "cohort", channel: "C1", notice: "failure:final", text: STALE, now: T0 + 3, agentRoot: ROOT }).allowed, false);
+  });
+
+  test("the notice map is pruned too, so the file cannot grow without bound", () => {
+    let led = _emptyLedger();
+    for (let i = 0; i < 50; i++) {
+      led = recordNotice({ ledger: led, service: "cohort", channel: "C1", notice: "failure:final", text: `old ${i}`, now: T0 });
+    }
+    const pruned = pruneLedger({ ledger: led, now: T0 + 3 * DEFAULT_ROOM_NOTICE_WINDOW_MS });
+    assert.equal(Object.keys(pruned.notices).length, 0);
+  });
+});
+
+describe("the ledger basename is exported, because its reader has to skip it", () => {
+  test("LEDGER_BASENAME is the file ledgerPath produces", () => {
+    // `assurance.listObligations` parses every *.json in this directory as a
+    // debt record. It skips this one BY NAME, so the name must be one string.
+    assert.equal(ledgerPath("/tmp/x").endsWith(`/${LEDGER_BASENAME}`), true);
+    assert.equal(LEDGER_BASENAME, "room-budget.json");
+  });
+});

package/lib/assurance/tier.mjs

@@ -0,0 +1,166 @@
+/**
+ * lib/assurance/tier.mjs — how loud may this ask make the agent?
+ *
+ * THE MEASUREMENT THIS EXISTS TO ANSWER
+ *
+ * Production, org_default_adaptic, the fourteen days to 2026-09-12: 10,667
+ * agent messages, of which 3,069 (28.8 %) were opening acknowledgements and 961
+ * (9.0 %) were clock-derived progress nags — 37.8 % content-free. 272 of those
+ * acknowledgements were never followed by a substantive reply within the hour.
+ * Agent-to-human volume went from 2:1 to 158:1 in a fortnight, and 9,187 of
+ * ~11,400 messages in 21 days landed in ONE channel from eight agents.
+ *
+ * The cause was not a bad message. It was the absence of a decision: every
+ * inbound ask that spawned a session earned an interim, so the interim rate was
+ * the session rate. This module is that missing decision.
+ *
+ * THE RULE
+ *
+ *   Silence is the default. An interim message is never a reflex; it is either
+ *   absent, or it is a plan.
+ *
+ *   answer — the reply arrives in this turn. Nothing is said. The reply IS the
+ *            acknowledgement (typing indicator aside).
+ *   work   — a session is spawning against a single objective. Nothing is said
+ *            for ACK_AFTER_MS; after that, at most ONE line, and only if the
+ *            room's own budget allows it.
+ *   plan   — the work is big enough that a human genuinely needs to know the
+ *            shape of it. ONE message, and it is the plan: what will be done,
+ *            in what order, and what comes back.
+ *
+ * PURE. Everything arrives on the argument; nothing is read from disk, the
+ * clock, the environment or the network. That is what lets a routing decision
+ * be replayed offline from a journal row, and what lets the whole matrix below
+ * be pinned by a test rather than sampled by a daemon.
+ *
+ * WHAT "rung" MEANS HERE
+ *
+ * The execution rung from `lib/execution/route.mjs` — 0 function call, 1 skill,
+ * 2 plugin, 3 session, 4 workflow, 5 sub-agent team. It is an INPUT, not a
+ * guess: an unrouted item (rung null, which is every inbound item until WP-2
+ * wires effort routing) is treated as unknown, and unknown buys nothing. It
+ * does not qualify for the answer tier's silence and it does not qualify for
+ * the plan tier's licence to speak. `lib/backlog` learned the same lesson from
+ * the other side — "absence must not become rung 0 — that is the cheapest
+ * rung".
+ *
+ * FAIL-OPEN DIRECTION. Garbage in gives `work` out: the tier that can still
+ * speak once, never the tier that cannot speak at all. A broken classifier must
+ * not silently mute an agent — that is the failure the obligation ledger was
+ * built to end, and it outranks tidiness.
+ *
+ * @module lib/assurance/tier
+ */
+
+"use strict";
+
+/** The only three answers this module can give. */
+export const TIERS = Object.freeze(["answer", "work", "plan"]);
+
+/** Highest rung that can still be answered inside the turn. */
+export const ANSWER_MAX_RUNG = 1;
+
+/** Lowest rung whose shape a human deserves to be told before it runs. */
+export const PLAN_MIN_RUNG = 3;
+
+/** Classifier actions whose high-priority form is worth a plan. */
+export const PLAN_ACTIONS = Object.freeze(["research", "draft"]);
+
+/** …and the priorities at which they are. */
+export const PLAN_PRIORITIES = Object.freeze(["critical", "high"]);
+
+/** Rungs, as `lib/execution/route.RUNGS` numbers them. */
+const MIN_RUNG = 0;
+const MAX_RUNG = 5;
+
+/**
+ * A rung we are willing to reason from, or null.
+ *
+ * Only an in-range integer counts. A string "3", a NaN, a 6 — each is a caller
+ * bug or a stale field, and reading any of them as a rung would let a typo
+ * decide whether a human is spoken to.
+ *
+ * @param {unknown} rung
+ * @returns {number|null}
+ */
+function routedRung(rung) {
+  if (typeof rung !== "number") return null;
+  if (!Number.isInteger(rung)) return null;
+  if (rung < MIN_RUNG || rung > MAX_RUNG) return null;
+  return rung;
+}
+
+/**
+ * Decide the reply tier for one inbound ask.
+ *
+ * The order of the rules is the policy, so it is stated rather than implied:
+ *
+ *   1. The caller asserts no session is spawning ⇒ `answer`. This is a fact about control flow,
+ *      not a classifier opinion, and it is the same fact `shouldAcknowledge`
+ *      has always turned on: if the answer arrives in this turn, an interim in
+ *      front of it is pure noise.
+ *   2. The classifier says answerable AND the routed rung is 0 or 1 AND the
+ *      caller has NOT asserted that a session is spawning ⇒ `answer`. All
+ *      three halves are required, and the third was once missing — see
+ *      THE FALL-THROUGH HAZARD below.
+ *   3. A routed rung of 3+ ⇒ `plan`. A workflow or a sub-agent team is not a
+ *      reply, it is a project; a human who is about to wait on one is owed its
+ *      shape.
+ *   4. research/draft at critical or high ⇒ `plan`, even unrouted. These are
+ *      the asks where the first thing a human wants is the approach, not the
+ *      output.
+ *   5. Otherwise ⇒ `work`.
+ *
+ * @param {object} [o]
+ * @param {boolean} [o.answerable]        classifier verdict: answerable in one reply
+ * @param {string}  [o.action]            classifier action (respond|draft|research|queue|archive|ignore)
+ * @param {string}  [o.priority]          classifier priority (critical|high|normal|ignore)
+ * @param {number|null} [o.rung]          routed execution rung, or null when unrouted
+ * @param {boolean} [o.willSpawnSession]  is a session being dispatched for this item.
+ *        `false` asserts it is not, and buys total silence (rule 1). `true`
+ *        asserts one is, and DISQUALIFIES the answer tier (rule 2) however
+ *        answerable the classifier thought the item was. Absent means unknown,
+ *        which buys nothing either way.
+ * @returns {"answer"|"work"|"plan"}
+ */
+export function replyTier(o) {
+  const a = o && typeof o === "object" ? o : {};
+
+  // (1) Control flow, not classification. `=== false` and not merely falsy:
+  // "no session is spawning" is a fact the caller must ASSERT, because it buys
+  // total silence. An absent or malformed flag is unknown, and unknown must not
+  // mute an agent — it falls through to `work`, which speaks once at most.
+  if (a.willSpawnSession === false) return "answer";
+
+  const rung = routedRung(a.rung);
+
+  // (2) Answerable AND cheap AND not, in fact, spawning a session.
+  //
+  // THE FALL-THROUGH HAZARD. `agent-daemon.mjs` tries a quick reply first; if
+  // that reply fails transiently or is blocked by validation it falls THROUGH
+  // to a full session dispatch and then asks this module for a tier with
+  // `willSpawnSession: true` while `classResult.answerable` is still true. The
+  // premise of the answer tier — "the reply arrives in this turn" — is exactly
+  // what the fall-through has already falsified. Without the third clause, the
+  // moment WP-2 routes `rung` (it is null today, so this is latent rather than
+  // live) that item would land in `answer`, `shouldAcknowledge` would return
+  // ack:false, the sweep would read the durable tier as never-speak, and a
+  // 15-45 minute session would run with the human hearing NOTHING at all.
+  //
+  // `!== true` and not `=== false`: the two ways the caller can leave this
+  // unknown (absent, malformed) are handled by rule (5), which speaks once.
+  // Only an ASSERTED spawn disqualifies the answer tier here — which is the
+  // mirror of rule (1), where only an ASSERTED non-spawn qualifies for it.
+  if (a.willSpawnSession !== true && a.answerable === true && rung != null && rung <= ANSWER_MAX_RUNG) return "answer";
+
+  // (3) Routed to machinery that is a project, not a reply.
+  if (rung != null && rung >= PLAN_MIN_RUNG) return "plan";
+
+  // (4) The two actions whose high-priority form a human wants the shape of.
+  if (PLAN_ACTIONS.includes(a.action) && PLAN_PRIORITIES.includes(a.priority)) return "plan";
+
+  // (5) The common case, and the one the flood was made of.
+  return "work";
+}
+
+export default { replyTier, TIERS, ANSWER_MAX_RUNG, PLAN_MIN_RUNG, PLAN_ACTIONS, PLAN_PRIORITIES };