@cohortapp/agent-sdk 2.3.0

package/lib/resource-governor.mjs

@@ -0,0 +1,297 @@
+/**
+ * lib/resource-governor.mjs — one admission gate before every spawn (WS4).
+ *
+ * `admit({source, priority, mode}, deps?)` decides, deterministically given
+ * its inputs, whether a new `claude --print` sub-session may launch:
+ *
+ *   ADMIT  — launch now.
+ *   QUEUE  — keep the work in the in-memory dispatcher queue (re-derivable
+ *            from durable state/queues/*.yaml); it spawns when a slot frees.
+ *   DEFER  — leave the work on disk untouched (backlog: the 10-min sweep
+ *            retries; cadence: requeueTick). DEFER must NEVER burn retry
+ *            budget (the callers honour this — they do not call failTick on a
+ *            governor deferral).
+ *
+ * The whole point (Invariants): under pressure work is QUEUED or DEFERRED —
+ * never dropped — and the agent throttles instead of bricking.
+ *
+ * Dynamic ceiling (replaces the hardcoded MAX_CONCURRENT=10):
+ *   dynamicMax  = clamp(floor(totalmem * 0.60 / 750MB), 1, min(10, cpus))
+ *   effectiveMax = min(dynamicMax, throttleCeiling)
+ * where throttleCeiling comes from state/throttle.json (written by the memory
+ * watchdog's SOFT tier; auto-expiring). The governor only READS that file —
+ * it never writes it.
+ *
+ * Thresholds (env GOV_* overridable; tests inject `deps` instead):
+ *   liveCount >= effectiveMax                         → QUEUE
+ *   freemem < totalmem*0.15  OR  < 2*750MB headroom    → DEFER
+ *   loadavg1 > cpus*1.5                                → DEFER
+ *   liveRSS + 750MB > 0.60*totalmem                    → QUEUE
+ *   else                                               → ADMIT
+ *
+ * Plus a budget `mode`: when essential-only (budget at 100%),
+ * source==="backlog"/"cadence" → DEFER; inbox → still goes through the normal
+ * ADMIT/QUEUE path (never go dark on the user).
+ *
+ * Purity: `admit` is a pure function of its injected `deps` snapshot. The
+ * default `deps` reads real os.* + a 2s-cached `liveClaudeStats()` (via ps) +
+ * state/throttle.json, but tests pass an explicit `deps` and get fully
+ * deterministic decisions.
+ *
+ * Constraints (CLAUDE.md): ESM, execFile (not exec), Node built-ins only.
+ */
+
+import os from "node:os";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Per-session RAM budget heuristic (Claude Code sub-session working set). */
+export const PER_SESSION_MB = num(process.env.GOV_PER_SESSION_MB, 750);
+const MB = 1024 * 1024;
+
+/** Fraction of total RAM the governor is willing to hand to claude sessions. */
+export const RAM_FRACTION = frac(process.env.GOV_RAM_FRACTION, 0.6);
+/** Free-memory floor as a fraction of total RAM. */
+export const FREEMEM_FLOOR_FRACTION = frac(process.env.GOV_FREEMEM_FLOOR, 0.15);
+/** Load-average multiplier over cpu count that triggers a DEFER. */
+export const LOAD_FACTOR = num(process.env.GOV_LOAD_FACTOR, 1.5);
+/** Hard ceiling on dynamicMax regardless of RAM. */
+export const HARD_MAX = num(process.env.GOV_HARD_MAX, 10);
+/** Minimum dynamicMax (always allow at least one session). */
+const MIN_MAX = 1;
+
+function num(v, dflt) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+function frac(v, dflt) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 && n < 1 ? n : dflt;
+}
+
+// ---------------------------------------------------------------------------
+// throttle.json (written by the watchdog SOFT tier; we only read it)
+// ---------------------------------------------------------------------------
+
+function throttlePath(deps) {
+  if (deps && deps.throttlePath) return resolve(deps.throttlePath);
+  const root =
+    (deps && deps.agentRoot) ||
+    process.env.AGENT_ROOT ||
+    process.env.AGENT_DIR ||
+    process.cwd();
+  return join(resolve(root), "state", "throttle.json");
+}
+
+/**
+ * Read the soft-throttle ceiling. Returns Infinity when no (unexpired)
+ * throttle is in force, so `min(dynamicMax, ceiling)` is a no-op by default.
+ * Never throws.
+ *
+ * @returns {{ ceiling:number, reason?:string, expiresAt?:number }}
+ */
+export function readThrottle(deps) {
+  const now = (deps && typeof deps.now === "function" ? deps.now : Date.now)();
+  const p = throttlePath(deps);
+  if (!existsSync(p)) return { ceiling: Infinity };
+  try {
+    const raw = JSON.parse(readFileSync(p, "utf-8"));
+    const expiresAt = Number(raw.expires_at ?? raw.expiresAt);
+    // Auto-expire: a stale throttle file (watchdog died before clearing it)
+    // must not pin the ceiling forever.
+    if (Number.isFinite(expiresAt) && now >= expiresAt) return { ceiling: Infinity };
+    const ceiling = Number(raw.ceiling);
+    if (!Number.isFinite(ceiling) || ceiling < 0) return { ceiling: Infinity };
+    return { ceiling, reason: raw.reason, expiresAt: Number.isFinite(expiresAt) ? expiresAt : undefined };
+  } catch {
+    return { ceiling: Infinity };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Live claude process stats (cached 2s) via ps
+// ---------------------------------------------------------------------------
+
+let _liveCache = { at: 0, value: null };
+const LIVE_CACHE_MS = 2_000;
+
+/**
+ * Count live `claude` CLI processes + their total RSS (MB) via `ps`. Cached
+ * for 2s so a burst of admit() calls doesn't fork ps repeatedly. Best-effort:
+ * on any failure returns { count:0, rssMB:0 } (fail-open-for-work).
+ *
+ * @returns {{ count:number, rssMB:number }}
+ */
+export function liveClaudeStats(opts = {}) {
+  const now = opts.now || Date.now;
+  const t = now();
+  if (!opts.force && _liveCache.value && t - _liveCache.at < LIVE_CACHE_MS) {
+    return _liveCache.value;
+  }
+  let value = { count: 0, rssMB: 0 };
+  try {
+    // pid, rss(KB), comm — mirror the watchdog's filter set so the governor's
+    // view of "live claude" matches what the watchdog would act on.
+    const out = execFileSync("/bin/ps", ["-eo", "pid,rss,comm"], { encoding: "utf-8", timeout: 4000 });
+    let count = 0;
+    let rssKb = 0;
+    for (const line of out.split("\n")) {
+      const l = line.trim();
+      if (!l) continue;
+      if (!/claude/i.test(l)) continue;
+      if (/Claude\.app|Claude Helper|watchdog|grep|ps -eo/.test(l)) continue;
+      const parts = l.split(/\s+/);
+      const rss = Number(parts[1]);
+      if (Number.isFinite(rss)) rssKb += rss;
+      count += 1;
+    }
+    value = { count, rssMB: Math.round(rssKb / 1024) };
+  } catch {
+    value = { count: 0, rssMB: 0 };
+  }
+  _liveCache = { at: t, value };
+  return value;
+}
+
+/** Reset the live-stats cache (tests). */
+export function _resetLiveCache() { _liveCache = { at: 0, value: null }; }
+
+// ---------------------------------------------------------------------------
+// Default deps snapshot
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the real-world deps snapshot the governor reasons over. Tests bypass
+ * this entirely by passing their own `deps`.
+ */
+export function defaultDeps(extra = {}) {
+  const live = liveClaudeStats();
+  const throttle = readThrottle(extra);
+  return {
+    freemem: os.freemem(),
+    totalmem: os.totalmem(),
+    loadavg: os.loadavg(),
+    cpus: os.cpus().length || 1,
+    liveClaude: live,
+    throttleCeiling: throttle.ceiling,
+    throttleReason: throttle.reason,
+    ...extra,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dynamic ceiling
+// ---------------------------------------------------------------------------
+
+/**
+ * dynamicMax = clamp(floor(totalmem*RAM_FRACTION / PER_SESSION_MB), 1, min(HARD_MAX, cpus))
+ */
+export function dynamicMax(deps) {
+  const totalmem = numField(deps && deps.totalmem, os.totalmem());
+  const cpus = Math.max(1, numField(deps && deps.cpus, os.cpus().length || 1));
+  const byRam = Math.floor((totalmem * RAM_FRACTION) / (PER_SESSION_MB * MB));
+  const upper = Math.min(HARD_MAX, cpus);
+  return clamp(byRam, MIN_MAX, Math.max(MIN_MAX, upper));
+}
+
+function clamp(v, lo, hi) { return Math.min(hi, Math.max(lo, v)); }
+function numField(v, dflt) { const n = Number(v); return Number.isFinite(n) ? n : dflt; }
+
+// ---------------------------------------------------------------------------
+// admit()
+// ---------------------------------------------------------------------------
+
+const ADMIT = "ADMIT";
+const QUEUE = "QUEUE";
+const DEFER = "DEFER";
+
+/**
+ * The admission decision.
+ *
+ * @param {object} req                 { source, priority, mode }
+ *   source:   "inbox" | "backlog" | "cadence"  (default "backlog")
+ *   priority: "critical"|"high"|"normal"|"low" (default "normal")
+ *   mode:     "essential-only" flips budget gating (else normal)
+ * @param {object} [deps]              injected snapshot; defaults to defaultDeps()
+ *   { freemem, totalmem, loadavg, cpus, liveClaude:{count,rssMB}, throttleCeiling }
+ * @returns {{ decision:"ADMIT"|"QUEUE"|"DEFER", reason:string, snapshot:object }}
+ */
+export function admit(req = {}, deps) {
+  const d = deps || defaultDeps();
+  const source = req.source || "backlog";
+  const mode = req.mode || (req.essentialOnly ? "essential-only" : null);
+
+  const totalmem = numField(d.totalmem, os.totalmem());
+  const freemem = numField(d.freemem, os.freemem());
+  const cpus = Math.max(1, numField(d.cpus, os.cpus().length || 1));
+  const load1 = Array.isArray(d.loadavg) ? numField(d.loadavg[0], 0) : numField(d.loadavg, 0);
+  const live = d.liveClaude || { count: 0, rssMB: 0 };
+  const liveCount = numField(live.count, 0);
+  const liveRssMB = numField(live.rssMB, 0);
+  const throttleCeiling = numField(d.throttleCeiling, Infinity);
+
+  const dMax = dynamicMax(d);
+  const effectiveMax = Math.max(1, Math.min(dMax, throttleCeiling));
+
+  const snapshot = {
+    source,
+    mode: mode || "normal",
+    dynamicMax: dMax,
+    effectiveMax,
+    throttleCeiling: throttleCeiling === Infinity ? null : throttleCeiling,
+    liveCount,
+    liveRssMB,
+    freememMB: Math.round(freemem / MB),
+    totalmemMB: Math.round(totalmem / MB),
+    load1,
+    cpus,
+  };
+
+  const decide = (decision, reason) => ({ decision, reason, snapshot });
+
+  // (0) Budget essential-only: non-inbox work is deferred entirely. Inbox
+  //     falls through to the normal pressure gating below (we keep replying).
+  if (mode === "essential-only" && (source === "backlog" || source === "cadence")) {
+    return decide(DEFER, "essential-only: daily budget cap reached; deferring non-inbox work");
+  }
+
+  // (1) Concurrency ceiling → QUEUE (work re-derivable from the queue).
+  if (liveCount >= effectiveMax) {
+    const why = throttleCeiling < dMax
+      ? `at throttled ceiling (${liveCount}/${effectiveMax}; soft-throttle active)`
+      : `at concurrency ceiling (${liveCount}/${effectiveMax})`;
+    return decide(QUEUE, why);
+  }
+
+  // (2) Free-memory floor → DEFER. Two guards: a percentage floor AND an
+  //     absolute headroom of at least 2 sessions' worth of RAM.
+  const freememFloor = totalmem * FREEMEM_FLOOR_FRACTION;
+  const headroomBytes = 2 * PER_SESSION_MB * MB;
+  if (freemem < freememFloor || freemem < headroomBytes) {
+    return decide(DEFER, `low free memory (${snapshot.freememMB}MB free; need >=${Math.round(Math.max(freememFloor, headroomBytes) / MB)}MB)`);
+  }
+
+  // (3) Load average → DEFER. A box already thrashing shouldn't take more on.
+  if (load1 > cpus * LOAD_FACTOR) {
+    return decide(DEFER, `load too high (1m load ${load1.toFixed(2)} > ${(cpus * LOAD_FACTOR).toFixed(1)} = cpus*${LOAD_FACTOR})`);
+  }
+
+  // (4) Projected RSS → QUEUE. If admitting one more session would push the
+  //     claude working set past the RAM fraction, wait for a slot rather than
+  //     risk an OOM kill.
+  const projectedMB = liveRssMB + PER_SESSION_MB;
+  const rssCapMB = (totalmem * RAM_FRACTION) / MB;
+  if (projectedMB > rssCapMB) {
+    return decide(QUEUE, `projected RSS ${projectedMB}MB would exceed ${Math.round(rssCapMB)}MB (${Math.round(RAM_FRACTION * 100)}% of RAM)`);
+  }
+
+  // (5) Healthy.
+  return decide(ADMIT, "resources healthy");
+}
+
+export const DECISIONS = { ADMIT, QUEUE, DEFER };

package/lib/resource-governor.test.mjs

@@ -0,0 +1,262 @@
+/**
+ * resource-governor.test.mjs — node:test coverage for the admission gate.
+ *
+ * Every test injects a full `deps` snapshot so admit() is a pure, deterministic
+ * function — no real os.* reads, no ps fork. We exercise each decision branch
+ * (ADMIT / QUEUE / DEFER), the dynamicMax sizing across 8/16/32GB boxes, the
+ * throttle-ceiling clamp, and essential-only mode.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  admit,
+  dynamicMax,
+  readThrottle,
+  PER_SESSION_MB,
+  RAM_FRACTION,
+  DECISIONS,
+} from "./resource-governor.mjs";
+
+const GB = 1024 * 1024 * 1024;
+const MB = 1024 * 1024;
+
+/**
+ * Build a healthy baseline deps snapshot for an N-GB / C-cpu box with `live`
+ * sessions already running and `liveRssMB` total. Override any field.
+ */
+function deps(over = {}) {
+  const totalmem = over.totalmem ?? 16 * GB;
+  return {
+    totalmem,
+    freemem: over.freemem ?? totalmem * 0.5, // plenty free
+    loadavg: over.loadavg ?? [0.5, 0.5, 0.5],
+    cpus: over.cpus ?? 8,
+    liveClaude: over.liveClaude ?? { count: 0, rssMB: 0 },
+    throttleCeiling: over.throttleCeiling ?? Infinity,
+    ...over,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// dynamicMax sizing
+// ---------------------------------------------------------------------------
+
+test("dynamicMax sizes by RAM, clamped to min(HARD_MAX, cpus)", () => {
+  // 8GB: floor(8*0.6/0.75) = floor(6.4) = 6, capped by cpus too.
+  assert.equal(dynamicMax({ totalmem: 8 * GB, cpus: 8 }), 6);
+  // 16GB: floor(16*0.6/0.75)=12 → clamp to min(10, cpus). cpus=8 → 8.
+  assert.equal(dynamicMax({ totalmem: 16 * GB, cpus: 8 }), 8);
+  // 16GB with 16 cpus → min(10,16)=10, byRam=12 → clamp to 10.
+  assert.equal(dynamicMax({ totalmem: 16 * GB, cpus: 16 }), 10);
+  // 32GB with 16 cpus: byRam=floor(32*0.6/0.75)=25 → clamp to min(10,16)=10.
+  assert.equal(dynamicMax({ totalmem: 32 * GB, cpus: 16 }), 10);
+  // Tiny box always yields at least 1.
+  assert.equal(dynamicMax({ totalmem: 1 * GB, cpus: 1 }), 1);
+});
+
+test("dynamicMax never returns 0 even on a starved box", () => {
+  assert.ok(dynamicMax({ totalmem: 512 * MB, cpus: 2 }) >= 1);
+});
+
+// ---------------------------------------------------------------------------
+// ADMIT
+// ---------------------------------------------------------------------------
+
+test("admit: healthy box with spare capacity → ADMIT", () => {
+  const r = admit({ source: "backlog" }, deps());
+  assert.equal(r.decision, DECISIONS.ADMIT);
+  assert.equal(r.snapshot.dynamicMax, 8);
+  assert.equal(r.snapshot.effectiveMax, 8);
+});
+
+test("admit: inbox on a healthy box → ADMIT", () => {
+  const r = admit({ source: "inbox", priority: "high" }, deps());
+  assert.equal(r.decision, DECISIONS.ADMIT);
+});
+
+// ---------------------------------------------------------------------------
+// QUEUE — concurrency ceiling
+// ---------------------------------------------------------------------------
+
+test("admit: at the concurrency ceiling → QUEUE", () => {
+  // effectiveMax = 8; 8 already live → QUEUE.
+  const r = admit({ source: "backlog" }, deps({ liveClaude: { count: 8, rssMB: 2000 } }));
+  assert.equal(r.decision, DECISIONS.QUEUE);
+  assert.match(r.reason, /concurrency ceiling/);
+});
+
+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 } }));
+  assert.equal(r.decision, DECISIONS.QUEUE);
+  assert.equal(r.snapshot.effectiveMax, 3);
+  assert.match(r.reason, /soft-throttle/);
+});
+
+// ---------------------------------------------------------------------------
+// QUEUE — projected RSS
+// ---------------------------------------------------------------------------
+
+test("admit: projected RSS over the RAM fraction → QUEUE", () => {
+  // 16GB → RAM fraction cap = 16*0.6*1024 ≈ 9830MB. Live RSS 9500MB + 750 > cap.
+  // Keep count below ceiling and memory/load healthy so RSS is the trigger.
+  const r = admit({ source: "backlog" }, deps({
+    liveClaude: { count: 2, rssMB: 9500 },
+    freemem: 16 * GB * 0.5,
+  }));
+  assert.equal(r.decision, DECISIONS.QUEUE);
+  assert.match(r.reason, /projected RSS/);
+});
+
+// ---------------------------------------------------------------------------
+// DEFER — free memory
+// ---------------------------------------------------------------------------
+
+test("admit: free memory below the 15% floor → DEFER", () => {
+  const r = admit({ source: "backlog" }, deps({ freemem: 16 * GB * 0.10 }));
+  assert.equal(r.decision, DECISIONS.DEFER);
+  assert.match(r.reason, /low free memory/);
+});
+
+test("admit: free memory below the 2-session absolute headroom → DEFER", () => {
+  // Big box where 15% is generous, but absolute free < 2*750MB = 1500MB.
+  const r = admit({ source: "backlog" }, deps({ totalmem: 64 * GB, freemem: 1000 * MB }));
+  assert.equal(r.decision, DECISIONS.DEFER);
+  assert.match(r.reason, /low free memory/);
+});
+
+// ---------------------------------------------------------------------------
+// DEFER — load average
+// ---------------------------------------------------------------------------
+
+test("admit: 1-minute load above cpus*1.5 → DEFER", () => {
+  // cpus=8 → threshold 12. load 13 → DEFER. Keep memory healthy.
+  const r = admit({ source: "backlog" }, deps({ loadavg: [13, 5, 5] }));
+  assert.equal(r.decision, DECISIONS.DEFER);
+  assert.match(r.reason, /load too high/);
+});
+
+test("admit: load exactly at the threshold is still ADMIT (strict >)", () => {
+  const r = admit({ source: "backlog" }, deps({ loadavg: [12, 1, 1], cpus: 8 }));
+  assert.equal(r.decision, DECISIONS.ADMIT);
+});
+
+// ---------------------------------------------------------------------------
+// essential-only mode
+// ---------------------------------------------------------------------------
+
+test("essential-only: backlog → DEFER without burning resources", () => {
+  const r = admit({ source: "backlog", mode: "essential-only" }, deps());
+  assert.equal(r.decision, DECISIONS.DEFER);
+  assert.match(r.reason, /essential-only/);
+});
+
+test("essential-only: cadence → DEFER", () => {
+  const r = admit({ source: "cadence", mode: "essential-only" }, deps());
+  assert.equal(r.decision, DECISIONS.DEFER);
+});
+
+test("essential-only: inbox still flows through normal gating (ADMIT when healthy)", () => {
+  const r = admit({ source: "inbox", mode: "essential-only" }, deps());
+  assert.equal(r.decision, DECISIONS.ADMIT, "inbox must keep replying even at budget cap");
+});
+
+test("essential-only: inbox still QUEUEs (not DEFERs) under concurrency pressure", () => {
+  const r = admit({ source: "inbox", mode: "essential-only" }, deps({ liveClaude: { count: 8, rssMB: 2000 } }));
+  assert.equal(r.decision, DECISIONS.QUEUE);
+});
+
+// ---------------------------------------------------------------------------
+// precedence — ceiling QUEUE beats memory DEFER? No: budget→ceiling→mem→load→rss.
+// Verify the documented order is honoured.
+// ---------------------------------------------------------------------------
+
+test("decision precedence: essential-only beats everything for backlog", () => {
+  // Even with a healthy box, essential-only short-circuits to DEFER.
+  const r = admit({ source: "backlog", mode: "essential-only" }, deps({ liveClaude: { count: 0, rssMB: 0 } }));
+  assert.equal(r.decision, DECISIONS.DEFER);
+});
+
+test("decision precedence: concurrency QUEUE is checked before memory DEFER", () => {
+  // At ceiling AND low memory → spec orders ceiling first → QUEUE.
+  const r = admit({ source: "backlog" }, deps({
+    liveClaude: { count: 8, rssMB: 1000 },
+    freemem: 16 * GB * 0.05,
+  }));
+  assert.equal(r.decision, DECISIONS.QUEUE);
+});
+
+// ---------------------------------------------------------------------------
+// readThrottle — auto-expiry
+// ---------------------------------------------------------------------------
+
+test("readThrottle returns Infinity when no file present", async () => {
+  const dir = join(tmpdir(), `gov-throttle-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(join(dir, "state"), { recursive: true });
+  try {
+    assert.equal(readThrottle({ agentRoot: dir }).ceiling, Infinity);
+  } finally { await fsp.rm(dir, { recursive: true, force: true }); }
+});
+
+test("readThrottle honours ceiling while unexpired, ignores once expired", async () => {
+  const dir = join(tmpdir(), `gov-throttle2-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(join(dir, "state"), { recursive: true });
+  try {
+    const now = 1_000_000;
+    writeFileSync(join(dir, "state", "throttle.json"), JSON.stringify({
+      ceiling: 2, reason: "SOFT", set_at: now - 1000, expires_at: now + 60_000,
+    }));
+    // Unexpired → ceiling honoured.
+    assert.equal(readThrottle({ agentRoot: dir, now: () => now }).ceiling, 2);
+    // After expiry → ignored.
+    assert.equal(readThrottle({ agentRoot: dir, now: () => now + 120_000 }).ceiling, Infinity);
+  } finally { await fsp.rm(dir, { recursive: true, force: true }); }
+});
+
+test("governor reads the EXACT throttle.json byte-shape the watchdog SOFT tier writes", async () => {
+  // This is the contract between scripts/watchdog/memory-watchdog.sh (writer)
+  // and the governor (reader). The watchdog writes ceiling + reason + EPOCH-MS
+  // set_at/expires_at. If either side drifts, throttling silently no-ops — so
+  // pin the shape here.
+  const dir = join(tmpdir(), `gov-wd-shape-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(join(dir, "state"), { recursive: true });
+  try {
+    const nowSec = 1_700_000_000;          // arbitrary epoch seconds
+    const setMs = nowSec * 1000;
+    const expMs = (nowSec + 300) * 1000;   // THROTTLE_TTL_SECONDS = 300
+    // Byte-for-byte the printf in write_throttle():
+    writeFileSync(join(dir, "state", "throttle.json"),
+      `{"ceiling":3,"reason":"soft-tier","set_at":${setMs},"expires_at":${expMs}}\n`);
+
+    // While unexpired → ceiling honoured.
+    const t1 = readThrottle({ agentRoot: dir, now: () => setMs + 1000 });
+    assert.equal(t1.ceiling, 3);
+    assert.equal(t1.reason, "soft-tier");
+    // After TTL → ignored (governor auto-expires even if the watchdog died).
+    const t2 = readThrottle({ agentRoot: dir, now: () => expMs + 1 });
+    assert.equal(t2.ceiling, Infinity);
+  } finally { await fsp.rm(dir, { recursive: true, force: true }); }
+});
+
+test("admit reads a real throttle.json from agentRoot and clamps", async () => {
+  const dir = join(tmpdir(), `gov-throttle3-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(join(dir, "state"), { recursive: true });
+  try {
+    const now = 2_000_000;
+    writeFileSync(join(dir, "state", "throttle.json"), JSON.stringify({
+      ceiling: 1, reason: "SOFT", expires_at: now + 60_000,
+    }));
+    // Build a deps snapshot that reads the throttle file: pass throttleCeiling
+    // from readThrottle so the integration is exercised end-to-end.
+    const t = readThrottle({ agentRoot: dir, now: () => now });
+    const r = admit({ source: "backlog" }, deps({ throttleCeiling: t.ceiling, liveClaude: { count: 1, rssMB: 500 } }));
+    assert.equal(r.snapshot.effectiveMax, 1);
+    assert.equal(r.decision, DECISIONS.QUEUE);
+  } finally { await fsp.rm(dir, { recursive: true, force: true }); }
+});