@cohortapp/agent-sdk 2.11.13 → 2.11.15

package/lib/budget-guard.mjs

@@ -1086,3 +1086,99 @@ function formatNotice(band, status) {
   }
   return `Seat spend at ${status.pct}% ($${usd} / $${cap} today) — heads-up only, nothing is degraded yet.${envelope}`;
 }
+
+// ---------------------------------------------------------------------------
+// Rolling usage window (subscription seats: TOKEN VOLUME, not dollars)
+// ---------------------------------------------------------------------------
+//
+// A Max seat has no dollar meter; what it can exhaust is a rolling token window
+// (≈5-hour session + weekly). The exact caps are UNPUBLISHED, so pacing is
+// DEFAULT-OFF: with GOV_WINDOW_5H_TOKENS / GOV_WEEK_TOKENS unset (0),
+// windowBand() is always "ok" and nothing paces — but the rolling volume is
+// still COMPUTED and surfaced so an operator can watch usage climb and calibrate
+// the caps. Reads the SAME cost-tracking ledger dailyStatus uses; "tokens" here
+// is input+output+cache summed over the window. The hard safety net remains
+// rate-guard's usage-limit recognition (recordUsageLimit holds the breaker until
+// reset); this is the proactive, opt-in layer above it.
+
+const WINDOW_5H_MS = 5 * 60 * 60 * 1000;
+const WINDOW_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+export const WINDOW_5H_TOKEN_CAP = Math.max(0, parseInt(process.env.GOV_WINDOW_5H_TOKENS || "0", 10) || 0);
+export const WINDOW_WEEK_TOKEN_CAP = Math.max(0, parseInt(process.env.GOV_WEEK_TOKENS || "0", 10) || 0);
+export const WINDOW_APPROACH_FRACTION = (() => {
+  const f = parseFloat(process.env.GOV_WINDOW_APPROACH || "0.8");
+  return f > 0 && f < 1 ? f : 0.8;
+})();
+
+function rowTokens(r) {
+  return (
+    (Number(r.input_tokens) || 0) +
+    (Number(r.output_tokens) || 0) +
+    (Number(r.cache_read_input_tokens) || 0) +
+    (Number(r.cache_creation_input_tokens) || 0)
+  );
+}
+
+/**
+ * Rolling token volume + session count over the last 5 hours and 7 days, from
+ * the cost-tracking ledger. Never throws (a missing/unreadable ledger → zeros).
+ */
+export function rollingWindowUsage(deps) {
+  const now = clock(deps)();
+  const dir = ledgerDir(deps);
+  let t5 = 0, s5 = 0, t7 = 0, s7 = 0;
+  let files = [];
+  try {
+    files = readdirSync(dir).filter((f) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)).sort().slice(-8);
+  } catch {
+    return { window5hTokens: 0, window5hSessions: 0, week7dTokens: 0, week7dSessions: 0 };
+  }
+  for (const f of files) {
+    let body;
+    try { body = readFileSync(join(dir, f), "utf-8"); } catch { continue; }
+    for (const line of body.split("\n")) {
+      if (!line.trim()) continue;
+      let r;
+      try { r = JSON.parse(line); } catch { continue; }
+      const at = r && r.ts ? Date.parse(r.ts) : NaN;
+      if (!Number.isFinite(at)) continue;
+      const dt = now - at;
+      if (dt < 0 || dt > WINDOW_WEEK_MS) continue;
+      const tok = rowTokens(r);
+      t7 += tok; s7 += 1;
+      if (dt <= WINDOW_5H_MS) { t5 += tok; s5 += 1; }
+    }
+  }
+  return { window5hTokens: t5, window5hSessions: s5, week7dTokens: t7, week7dSessions: s7 };
+}
+
+/**
+ * The usage-window band: "ok" | "approaching" | "at". DEFAULT-OFF — an unset
+ * (0) cap yields "ok" for that horizon, so the fleet paces on the window only
+ * once an operator has calibrated GOV_WINDOW_5H_TOKENS / GOV_WEEK_TOKENS. The
+ * band is the WORSE of the 5h and weekly horizons.
+ */
+export function windowBand(deps) {
+  const u = rollingWindowUsage(deps);
+  // Caps come from deps first (tests / a per-seat override), else the env consts.
+  const cap5 = deps && deps.cap5h != null ? deps.cap5h : WINDOW_5H_TOKEN_CAP;
+  const cap7 = deps && deps.capWeek != null ? deps.capWeek : WINDOW_WEEK_TOKEN_CAP;
+  const frac = deps && deps.approachFraction != null ? deps.approachFraction : WINDOW_APPROACH_FRACTION;
+  const bandFor = (used, cap) => {
+    if (!cap || cap <= 0) return "ok";
+    if (used >= cap) return "at";
+    if (used >= cap * frac) return "approaching";
+    return "ok";
+  };
+  const rank = { ok: 0, approaching: 1, at: 2 };
+  const b5 = bandFor(u.window5hTokens, cap5);
+  const b7 = bandFor(u.week7dTokens, cap7);
+  const band = rank[b5] >= rank[b7] ? b5 : b7;
+  return {
+    band,
+    ...u,
+    cap5h: cap5 || null,
+    capWeek: cap7 || null,
+    active: cap5 > 0 || cap7 > 0,
+  };
+}

package/lib/budget-guard.test.mjs

@@ -18,6 +18,8 @@ import {
   readNotified,
   BANDS,
   DEFAULT_DAILY_SPEND_CAP_USD,
+  rollingWindowUsage,
+  windowBand,
 } from "./budget-guard.mjs";
 
 const FIXED = Date.UTC(2026, 5, 9, 12, 0, 0); // 2026-06-09T12:00:00Z
@@ -363,3 +365,63 @@ test("dailyStatus: a subscription-auth seat STILL bands on session volume (a rea
     assert.equal(sub.mode, "degraded");
   } finally { await rm(dir); }
 });
+
+// ---------------------------------------------------------------------------
+// rolling usage window (token volume) + windowBand (default-off pacing)
+// ---------------------------------------------------------------------------
+
+function seedWindowLedger(dir, rows) {
+  // rows: [{ minsAgo, tokens }] written to today's + yesterday's files by ts.
+  const now = FIXED;
+  const byFile = {};
+  for (const r of rows) {
+    const at = new Date(now - r.minsAgo * 60_000);
+    const day = at.toISOString().slice(0, 10);
+    (byFile[day] ||= []).push(JSON.stringify({
+      ts: at.toISOString(),
+      total_cost_usd: 0.1, model: "sonnet", cadence: "x",
+      input_tokens: r.tokens, output_tokens: 0,
+    }));
+  }
+  for (const [day, lines] of Object.entries(byFile)) {
+    writeFileSync(join(dir, `${day}.jsonl`), lines.join("\n") + "\n");
+  }
+}
+
+test("rollingWindowUsage sums tokens/sessions in the 5h and 7d windows", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    seedWindowLedger(dir, [
+      { minsAgo: 10, tokens: 1000 },   // in 5h + 7d
+      { minsAgo: 60, tokens: 2000 },   // in 5h + 7d
+      { minsAgo: 400, tokens: 500 },   // >5h (400m), in 7d
+      { minsAgo: 60 * 24 * 8, tokens: 9999 }, // >7d — excluded
+    ]);
+    const u = rollingWindowUsage({ ledgerDir: dir, now: clk });
+    assert.equal(u.window5hTokens, 3000);
+    assert.equal(u.window5hSessions, 2);
+    assert.equal(u.week7dTokens, 3500);
+    assert.equal(u.week7dSessions, 3);
+  } finally { await rm(dir); }
+});
+
+test("windowBand is DEFAULT-OFF: no caps → always 'ok' however high usage climbs", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    seedWindowLedger(dir, [{ minsAgo: 5, tokens: 10_000_000 }]);
+    const b = windowBand({ ledgerDir: dir, now: clk }); // no caps
+    assert.equal(b.band, "ok");
+    assert.equal(b.active, false);
+    assert.equal(b.window5hTokens, 10_000_000);
+  } finally { await rm(dir); }
+});
+
+test("windowBand bands 'approaching' then 'at' once a 5h cap is calibrated", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    seedWindowLedger(dir, [{ minsAgo: 5, tokens: 8500 }]);
+    assert.equal(windowBand({ ledgerDir: dir, now: clk, cap5h: 10_000 }).band, "approaching"); // 85% of 10k
+    assert.equal(windowBand({ ledgerDir: dir, now: clk, cap5h: 8000 }).band, "at");             // over 8k
+    assert.equal(windowBand({ ledgerDir: dir, now: clk, cap5h: 100_000 }).band, "ok");          // well under
+  } finally { await rm(dir); }
+});

package/lib/identity/persona.mjs

@@ -130,6 +130,35 @@ function voiceRules(a) {
   ];
 }
 
+/**
+ * Message-craft doctrine — the "how you shape an outbound message" half of the
+ * voice, injected into BOTH prompt-assembly paths so the two planes write the
+ * same way: the full-session prompt (scripts/daemon/prompt-builder.mjs
+ * #buildPrompt) and the quick-reply system prompt (scripts/daemon/responder.mjs
+ * #realGenerateResponse).
+ *
+ * Deliberately a separately-exported CONSTANT rather than part of voiceRules():
+ * the responder does not render the persona block — it calls neither renderPersona
+ * nor voiceRules — so folding it in would reach only full sessions and leave every
+ * reactive quick reply unshaped. As framework code it also survives per-seat
+ * CLAUDE.md drift, where the same doctrine lives as human-readable scaffold data.
+ *
+ * Phrased "distil by default; structure only when the message must be large" so it
+ * does NOT contradict the scaffold's `No unsolicited structure` rule
+ * (scaffold/CLAUDE.md `## Communication Rules`): headings/bullets are for the
+ * genuinely large message, never decoration on a small one. The attach-don't-dump
+ * bullet leans on mechanisms already sanctioned elsewhere in the prompt (the PDF
+ * builder, Slack upload, email --attachment) and on the standing "never reference a
+ * local file path" rule.
+ */
+export const MESSAGE_CRAFT = [
+  "How you shape a message:",
+  "- Distil to what matters, by default. Lead with the answer, the decision, or the ask; cut throat-clearing, restatement of the question, and background the reader already has. Most replies are a few sentences — send those as a few sentences, and keep them scannable.",
+  "- Offer depth, don't front-load it. Give the sharp version and add \"I can go deeper on X if useful\" rather than dumping every detail pre-emptively.",
+  "- When a message genuinely must be long, FORMAT it for legibility: a short intro line, then short paragraphs, a heading, or a few bullets for the parts that actually are a list. Structure serves a large message; it never decorates a small one, and it is never a wall of text.",
+  "- When the content is genuinely verbose — a full memo or report, a long analysis, a large table or dataset — do NOT dump it into the chat. Attach it as a document and put a two-to-three-line summary plus the attachment in the message: generate a branded PDF (scripts/pdf-generation/build-document.mjs, or `npm run pdf:memo -- --input <file.md>`) or upload the file (Slack: scripts/slack-upload-v2.py; email: send with --attachment). Never reference a local file path in an outbound message.",
+].join("\n");
+
 /**
  * Render the persona block from resolved config. Pure — no I/O, never throws.
  *

package/lib/identity/persona.test.mjs

@@ -4,7 +4,7 @@ import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { renderPersona, loadPersonaBlock } from "./persona.mjs";
+import { renderPersona, loadPersonaBlock, MESSAGE_CRAFT } from "./persona.mjs";
 
 const AGENT = {
   firstName: "Jamie",
@@ -100,6 +100,31 @@ test("junk values in list fields are dropped, not rendered", () => {
   assert.doesNotMatch(out, /\[object Object\]/);
 });
 
+// The message-craft doctrine is a separately-exported constant (NOT part of the
+// persona block) precisely so the responder — which never renders the persona —
+// can inject the identical string. These pin the substance both planes rely on.
+test("MESSAGE_CRAFT carries the distil-by-default / format-when-large / attach-when-verbose doctrine", () => {
+  // Distil by default; most replies are short.
+  assert.match(MESSAGE_CRAFT, /Distil to what matters, by default/);
+  assert.match(MESSAGE_CRAFT, /Lead with the answer, the decision, or the ask/);
+  // Offer depth on request rather than front-loading.
+  assert.match(MESSAGE_CRAFT, /Offer depth, don't front-load it/);
+  // Format only when the message must be large — never a wall of text.
+  assert.match(MESSAGE_CRAFT, /when a message genuinely must be long, FORMAT it/i);
+  assert.match(MESSAGE_CRAFT, /never a wall of text/);
+  // Attach verbose content with a short summary rather than dumping it.
+  assert.match(MESSAGE_CRAFT, /do NOT dump it into the chat/);
+  assert.match(MESSAGE_CRAFT, /two-to-three-line summary/);
+});
+
+test("MESSAGE_CRAFT names the REAL attach mechanisms and forbids local paths", () => {
+  assert.match(MESSAGE_CRAFT, /scripts\/pdf-generation\/build-document\.mjs/);
+  assert.match(MESSAGE_CRAFT, /npm run pdf:memo/);
+  assert.match(MESSAGE_CRAFT, /scripts\/slack-upload-v2\.py/);
+  assert.match(MESSAGE_CRAFT, /--attachment/);
+  assert.match(MESSAGE_CRAFT, /Never reference a local file path/);
+});
+
 test("loadPersonaBlock reads an agent repo, and fails open on a broken config", () => {
   const dir = mkdtempSync(join(tmpdir(), "persona-"));
   try {

package/lib/resource-governor.mjs

@@ -504,6 +504,16 @@ export function admit(req = {}, deps) {
   if (mode === "suspended" && (source === "backlog" || source === "cadence")) {
     return decide(DEFER, "budget suspended (>=125% of the seat envelope): deferring non-inbox work");
   }
+  // USAGE-WINDOW PACING (default-off; only active once GOV_WINDOW_* caps are
+  // calibrated — see budget-guard.windowBand). At the rolling window's limit,
+  // pause self-directed work so a burst spreads across windows instead of
+  // exhausting one; a direct human reply is never paced. "approaching" is folded
+  // into the concurrency ceiling below (throttle, don't stop). `windowBand`
+  // defaults to "ok" so an uncalibrated seat behaves exactly as before.
+  const windowBand = req.windowBand || "ok";
+  if (windowBand === "at" && !humanReply) {
+    return decide(DEFER, `usage window at limit: deferring ${source} work so it spreads across windows; direct human replies continue`);
+  }
   // NOTE: `degraded` (>=100% / unfunded) no longer hard-stops backlog. Owner
   // instruction (2026-08-25): THROTTLE, don't stop — the seat keeps a thin
   // trickle of self-directed work so autonomous progress never fully halts,
@@ -524,10 +534,14 @@ export function admit(req = {}, deps) {
   // ABOVE the REACTIVE_RESERVE math: reserve keeps steady-state headroom; this
   // clamps to a trickle for the seconds a human is actually waiting.
   const reactiveBusy = numField(d.reactiveInFlight, 0) > 0;
+  // "approaching" the usage window → throttle self-directed work toward a trickle
+  // (like a reactive turn) so the seat glides into the window rather than slamming
+  // it. Default-off: windowBand is "ok" unless GOV_WINDOW_* caps are set.
+  const windowApproaching = windowBand === "approaching";
   let sourceCeiling;
   if (humanReply) {
     sourceCeiling = effectiveMax;
-  } else if (reactiveBusy) {
+  } else if (reactiveBusy || windowApproaching) {
     sourceCeiling = Math.min(effectiveMax, REACTIVE_INFLIGHT_BACKLOG_MAX);
     if (mode === "degraded" && source === "backlog") {
       sourceCeiling = Math.min(sourceCeiling, DEGRADED_BACKLOG_MAX);
@@ -540,6 +554,8 @@ export function admit(req = {}, deps) {
   if (liveCount >= sourceCeiling) {
     const why = reactiveBusy
       ? `reactive turn in flight: self-directed ${source} yields the subscription, capped to ${sourceCeiling} (${liveCount} live)`
+      : windowApproaching
+      ? `usage window approaching: self-directed ${source} throttled to ${sourceCeiling} to spread across windows (${liveCount} live)`
       : mode === "degraded" && source === "backlog"
         ? `budget degraded: self-directed backlog throttled to ${sourceCeiling} (${liveCount} live; inbox unaffected)`
         : throttleCeiling < dMax

package/lib/resource-governor.test.mjs

@@ -180,6 +180,33 @@ test("admit: one backlog session is still allowed alongside a reply (cap 1, not
   assert.equal(r.decision, DECISIONS.ADMIT);
 });
 
+// ---------------------------------------------------------------------------
+// Usage-window pacing (default-off; driven by req.windowBand from budget-guard)
+// ---------------------------------------------------------------------------
+
+test("admit: windowBand 'at' DEFERS self-directed work; a human reply is never paced", () => {
+  assert.equal(admit({ source: "backlog", windowBand: "at" }, deps()).decision, DECISIONS.DEFER);
+  assert.equal(admit({ source: "cadence", windowBand: "at" }, deps()).decision, DECISIONS.DEFER);
+  // inbox / humanReply continue at the window limit
+  assert.equal(admit({ source: "inbox", windowBand: "at" }, deps()).decision, DECISIONS.ADMIT);
+  assert.equal(admit({ source: "backlog", humanReply: true, windowBand: "at" }, deps()).decision, DECISIONS.ADMIT);
+});
+
+test("admit: windowBand 'approaching' throttles backlog to a trickle (QUEUE), inbox unaffected", () => {
+  // 1 already live → backlog capped to REACTIVE_INFLIGHT_BACKLOG_MAX(1) → QUEUE
+  const r = admit({ source: "backlog", windowBand: "approaching" }, deps({ liveClaude: { count: 1, rssMB: 300 } }));
+  assert.equal(r.decision, DECISIONS.QUEUE);
+  assert.match(r.reason, /usage window approaching/);
+  // inbox still admits at the same live count
+  assert.equal(admit({ source: "inbox", windowBand: "approaching" }, deps({ liveClaude: { count: 1, rssMB: 300 } })).decision, DECISIONS.ADMIT);
+});
+
+test("admit: windowBand default (undefined/'ok') changes nothing — pacing is off by default", () => {
+  // 3 live, no window signal → backlog still ADMITs (reserve leaves 5)
+  assert.equal(admit({ source: "backlog" }, deps({ liveClaude: { count: 3, rssMB: 900 } })).decision, DECISIONS.ADMIT);
+  assert.equal(admit({ source: "backlog", windowBand: "ok" }, deps({ liveClaude: { count: 3, rssMB: 900 } })).decision, DECISIONS.ADMIT);
+});
+
 test("admit: throttle ceiling clamps effectiveMax below dynamicMax → QUEUE earlier", () => {
   // dynamicMax 8 but soft-throttle pinned the ceiling to 3; 3 live → QUEUE.
   const r = admit({ source: "backlog" }, deps({ throttleCeiling: 3, liveClaude: { count: 3, rssMB: 1000 } }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.11.13",
+  "version": "2.11.15",
   "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/scaffold/CLAUDE.md

@@ -103,6 +103,16 @@ message (Slack, email, WhatsApp, SMS, voice, drafted artefacts):
 - **Disagree when warranted.** Don't soften real concerns into politeness.
 - **Brevity is a feature.** If the answer is one sentence, send one
   sentence. Do not pad to look thorough.
+- **Distil by default; format only when large.** Lead with the answer,
+  the decision, or the ask; offer more detail on request rather than
+  front-loading it. When a message genuinely must be long, format it for
+  legibility (a short intro line, then short paragraphs or a few bullets)
+  — never a wall of text. When the content is genuinely verbose (a full
+  report, a long analysis, a large table), do NOT dump it in the chat:
+  attach it as a document and give a two-to-three-line summary. Generate a
+  branded PDF (`npm run pdf:memo -- --input <file.md>`) or upload the file
+  (Slack: `scripts/slack-upload-v2.py`; email: send with `--attachment`).
+  See Document Sharing below.
 
 System-style output (status indicators, checklists, formal headers) is
 opt-in — only when the user explicitly requests it or the medium clearly

package/scripts/daemon/cadence-consumer.mjs

@@ -601,8 +601,10 @@ export function startConsumer(opts = {}) {
       // as a human reply, and every cadence tick arrives as `source:"cadence"`.
       // Two gates, one predicate, or the rung silences the inbox on the second
       // hop instead of the first.
+      let windowBand;
+      try { windowBand = budgetGuardModule.windowBand?.({ agentRoot })?.band; } catch { /* default-off */ }
       const adm = governor.admit(
-        { source: "cadence", mode, humanReply: cadence ? isHumanLaneCadence(cadence) : false },
+        { source: "cadence", mode, humanReply: cadence ? isHumanLaneCadence(cadence) : false, windowBand },
         governor.defaultDeps({ agentRoot })
       );
       if (adm.decision !== "ADMIT") return { admit: false, reason: adm.reason || adm.decision };

package/scripts/daemon/dispatcher-governance.test.mjs

@@ -191,11 +191,45 @@ test("reconcile blocks a marker that is older than the freshness window", async
   } finally { await cleanup(dir); }
 });
 
+test("resume reconcile DEFERS (never re-storms) when the backlog budget is 0 (reactive-only seat)", async () => {
+  // DAEMON_MAX_CONCURRENT=3 → backlogCap = 3 - RESERVED_INBOX_SLOTS(3) = 0, so a
+  // reactive-only seat must resume NOTHING on boot — the fresh-seat storm root.
+  process.env.DAEMON_MAX_CONCURRENT = "3";
+  const { mod, dir } = await freshDispatcher();
+  try {
+    plantMarker(dir, "s-a", { itemId: "BL-A", sourceFile: "q.yaml", startedAt: Date.now() });
+    plantMarker(dir, "s-b", { itemId: "BL-B", sourceFile: "q.yaml", startedAt: Date.now() });
+    let spawned = 0;
+    const stats = mod.reconcileResumePending({ spawnResume: () => { spawned++; } });
+    assert.equal(spawned, 0, "no resume spawns on a budget-0 seat");
+    assert.equal(stats.resumed, 0);
+    assert.equal(stats.deferred, 2, "both live markers deferred, not blocked/expired");
+    // markers are LEFT on disk (deferred, not retired) for a later reconcile
+    const left = readdirSync(join(dir, "state/sessions/resume-pending")).filter((f) => f.endsWith(".json"));
+    assert.equal(left.length, 2, "deferred markers persist");
+  } finally { delete process.env.DAEMON_MAX_CONCURRENT; await cleanup(dir); }
+});
+
+test("resume reconcile is GATED (resumes nothing) while the shared breaker is open", async () => {
+  const { mod, dir } = await freshDispatcher();
+  try {
+    mod.setGovernanceForTests({ rateGuard: { checkRateLimit: () => ({ allowed: false, retryAt: Date.now() + 60_000 }) } });
+    plantMarker(dir, "s-x", { itemId: "BL-X", sourceFile: "q.yaml", startedAt: Date.now() });
+    let spawned = 0;
+    const stats = mod.reconcileResumePending({ spawnResume: () => { spawned++; } });
+    assert.equal(spawned, 0, "an open breaker (e.g. a usage-limit hold) blocks all resume");
+    assert.equal(stats.resumed, 0);
+    assert.equal(stats.scanned, 0, "returns before scanning when the breaker is open");
+    // the marker is untouched, ready for the next reconcile after the breaker clears
+    assert.equal(readdirSync(join(dir, "state/sessions/resume-pending")).filter((f) => f.endsWith(".json")).length, 1);
+  } finally { await cleanup(dir); }
+});
+
 test("reconcile on an empty resume-pending dir is a no-op", async () => {
   const { mod, dir } = await freshDispatcher();
   try {
     const stats = mod.reconcileResumePending({ spawnResume: () => { throw new Error("should not spawn"); } });
-    assert.deepEqual(stats, { scanned: 0, resumed: 0, blocked: 0, expired: 0 });
+    assert.deepEqual(stats, { scanned: 0, resumed: 0, blocked: 0, expired: 0, deferred: 0 });
   } finally { await cleanup(dir); }
 });
 

package/scripts/daemon/dispatcher.mjs

@@ -75,7 +75,11 @@ function admitFor(source, priority) {
         console.warn(`[dispatcher] budget ${st.mode}: ${st.pct}% of $${st.capUSD}/day (${st.capSource}) — gating ${source} work`);
       }
     } catch { /* budget read best-effort */ }
-    return governor.admit({ source, priority, mode }, governor.defaultDeps({ agentRoot: AGENT_REPO_DIR }));
+    // Usage-window band (default-off unless GOV_WINDOW_* caps set) → the governor
+    // paces self-directed work as the rolling window fills. Best-effort.
+    let windowBand;
+    try { windowBand = budgetGuard.windowBand?.({ agentRoot: AGENT_REPO_DIR })?.band; } catch { /* */ }
+    return governor.admit({ source, priority, mode, windowBand }, governor.defaultDeps({ agentRoot: AGENT_REPO_DIR }));
   } catch {
     return { decision: "ADMIT", reason: "governor-error-fail-open", snapshot: {} };
   }
@@ -499,13 +503,32 @@ export function resetActiveSessions(opts = {}) {
  */
 export function reconcileResumePending(opts = {}) {
   const now = (typeof opts.now === "function" ? opts.now : Date.now)();
-  const stats = { scanned: 0, resumed: 0, blocked: 0, expired: 0 };
+  const stats = { scanned: 0, resumed: 0, blocked: 0, expired: 0, deferred: 0 };
   let files = [];
   try {
     if (!existsSync(RESUME_PENDING_DIR)) return stats;
     files = readdirSync(RESUME_PENDING_DIR).filter((f) => f.endsWith(".json") && !f.endsWith(".tmp"));
   } catch { return stats; }
 
+  // ADMISSION GATE — resume must honour the same throttle as any backlog spawn,
+  // or a stormed seat's leftover markers bypass it and re-storm on every boot
+  // (the fresh-seat backlog-storm root). Two guards:
+  //  (1) if the shared breaker is open (a usage/rate limit is holding spawns),
+  //      resume NOTHING — resuming would hammer a drained pool the moment it
+  //      re-opens. Markers stay for the next reconcile after the breaker clears.
+  //  (2) cap resumes this pass to the BACKLOG concurrency (in-memory, race-free
+  //      — unlike the governor's ps count). DAEMON_MAX_CONCURRENT=3 →
+  //      RESERVED_INBOX_SLOTS(3) → budget 0 → a reactive-only seat resumes
+  //      nothing on boot (the item stays re-deliverable / the marker persists).
+  try {
+    const rb = rateGuard.checkRateLimit(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR });
+    if (rb && rb.allowed === false) {
+      logSession({ event: "resume_reconcile_gated", reason: "breaker_open", retry_at: rb.retryAt || null, markers: files.length });
+      return stats;
+    }
+  } catch { /* fail-open — a breaker read error must not strand recovery */ }
+  const resumeBudget = Math.max(0, MAX_CONCURRENT - RESERVED_INBOX_SLOTS - activeSessions.size);
+
   for (const file of files) {
     const path = join(RESUME_PENDING_DIR, file);
     stats.scanned++;
@@ -554,6 +577,15 @@ export function reconcileResumePending(opts = {}) {
       continue;
     }
 
+    // Over the backlog budget for this pass → DEFER (leave the marker, do NOT
+    // bump attempts — a deferral is not a try). The next reconcile picks it up
+    // once slots free / the throttle lifts. This is what stops the re-storm.
+    if (stats.resumed >= resumeBudget) {
+      logSession({ event: "resume_deferred_throttle", sessionId: marker.sessionId, item_id: marker.itemId, budget: resumeBudget });
+      stats.deferred++;
+      continue;
+    }
+
     // Bump the attempt count on the marker BEFORE re-dispatch so a crash mid-
     // resume still advances toward the 3-strike cap (no infinite loop).
     marker.recoveryAttempts = attempts + 1;
@@ -573,7 +605,7 @@ export function reconcileResumePending(opts = {}) {
     }
   }
   if (stats.scanned > 0) {
-    console.log(`[dispatcher] resume reconcile: ${stats.resumed} resumed, ${stats.blocked} blocked, ${stats.expired} expired (of ${stats.scanned})`);
+    console.log(`[dispatcher] resume reconcile: ${stats.resumed} resumed, ${stats.deferred} deferred, ${stats.blocked} blocked, ${stats.expired} expired (of ${stats.scanned})`);
   }
   return stats;
 }

package/scripts/daemon/prompt-builder.mjs

@@ -7,7 +7,7 @@ import { readFileSync, readdirSync } from "fs";
 import { join } from "path";
 import { createRequire } from "node:module";
 import { compileContext } from "./context-compiler.mjs";
-import { renderPersona } from "../../lib/identity/persona.mjs";
+import { renderPersona, MESSAGE_CRAFT } from "../../lib/identity/persona.mjs";
 import { wrapExternalContent } from "../../lib/security/external-content.mjs";
 import { isEnabled as orgEnabled } from "../../lib/org/client.mjs";
 import { recall as orgRecall } from "../../lib/org/knowledge.mjs";
@@ -876,6 +876,14 @@ export async function buildPrompt(item, classResult, options = {}) {
   parts.push(SKILLS_GUIDANCE);
   parts.push("");
 
+  // 1c. Message-craft doctrine — the shared "how you shape an outbound message"
+  // rule (distil by default; format only when the message must be large; attach
+  // rather than dump genuinely verbose content). Exported from persona.mjs and
+  // injected into the responder's quick-reply prompt too, so reactive replies and
+  // full sessions write outbound prose the same way.
+  parts.push(MESSAGE_CRAFT);
+  parts.push("");
+
   // 1a. Holding message warning — TOP OF PROMPT so Claude sees it before action instructions.
   // This is the most critical instruction in the prompt: prevents double-replies.
   // We repeat it at section 7a as well, immediately before the action block.

package/scripts/daemon/prompt-builder.test.mjs

@@ -212,6 +212,28 @@ test("buildPrompt caps the number of injected org facts (bounded)", async () =>
   });
 });
 
+// ---------------------------------------------------------------------------
+// Message-craft doctrine — the shared "how you shape an outbound message" rule
+// (distil by default; format only when the message must be large; attach
+// genuinely verbose content). The SAME constant leads the responder's quick-reply
+// system prompt, so reactive replies and full sessions write outbound prose the
+// same way.
+// ---------------------------------------------------------------------------
+
+test("buildPrompt injects the message-craft doctrine (distil / format / attach)", async () => {
+  writeOrgConfig(null);
+  const prompt = await buildPrompt(ITEM, CLASS, { type: "inbox" });
+  assert.match(prompt, /How you shape a message:/);
+  assert.match(prompt, /Distil to what matters, by default/);
+  assert.match(prompt, /when a message genuinely must be long, FORMAT it/i);
+  assert.match(prompt, /do NOT dump it into the chat/);
+  // The real attach mechanism, not a vague "share it somewhere".
+  assert.match(prompt, /scripts\/pdf-generation\/build-document\.mjs/);
+  assert.match(prompt, /scripts\/slack-upload-v2\.py/);
+  // The rest of the prompt is unchanged.
+  assert.ok(prompt.includes("--- INCOMING MESSAGE ---"));
+});
+
 test("buildPrompt states the acknowledgement was sent when it actually was", async () => {
   const prompt = await buildPrompt(ITEM, CLASS, {
     type: "inbox",

package/scripts/daemon/responder.mjs

@@ -60,6 +60,13 @@ import { startTyping, stopTyping } from "./typing-registry.mjs";
 // (in short: a 60s `claude --print` spawn to write "let me look into it" lost
 // its own race 2 times in 3, and lost it silently).
 import { composeAck } from "./assurance.mjs";
+// Shared message-craft doctrine (distil by default; format only when the message
+// must be large; attach genuinely verbose content rather than dumping it). The
+// SAME constant leads the full-session prompt in prompt-builder.mjs, so a reactive
+// quick reply and a full inbox/backlog session shape outbound prose identically.
+// This path never renders the persona block, which is why the doctrine is a
+// separately-exported constant rather than part of voiceRules().
+import { MESSAGE_CRAFT } from "../../lib/identity/persona.mjs";
 
 const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
 const SONNET_MODEL = "claude-sonnet-4-6";
@@ -708,7 +715,9 @@ If it's informational, acknowledge appropriately.
 
 Keep responses focused — 1-4 sentences for simple items, up to a short paragraph for more nuanced ones.
 Match the sender's tone and urgency level.
-${profile ? `\nSender profile:\n${profile}` : ""}`;
+${profile ? `\nSender profile:\n${profile}` : ""}
+
+${MESSAGE_CRAFT}`;
 
   const conversationHistory = await loadConversationHistory(item);