instar 1.3.640 → 1.3.642

package/dist/monitoring/LlmQueue.js

@@ -8,9 +8,14 @@ export class LlmQueue {
     maxConcurrent;
     interactiveReservePct;
     maxDailyCents;
+    backgroundDispatchMinGapMs;
     now;
     inFlight = new Set();
     waiters = [];
+    /** Wall-clock (via `now`) of the last BACKGROUND-lane dispatch — herd-pacing window anchor. */
+    lastBackgroundStartAt = 0;
+    /** At most one pending paced re-drain timer; null when none scheduled. */
+    pacingTimer = null;
     /** Daily spend ledger: { dateKey: 'YYYY-MM-DD', cents: number, interactive: number } */
     dailySpendCents = 0;
     dailyInteractiveCents = 0;
@@ -19,6 +24,7 @@ export class LlmQueue {
         this.maxConcurrent = opts.maxConcurrent ?? 3;
         this.interactiveReservePct = opts.interactiveReservePct ?? 0.4;
         this.maxDailyCents = opts.maxDailyCents ?? 100;
+        this.backgroundDispatchMinGapMs = opts.backgroundDispatchMinGapMs ?? 0;
         this.now = opts.now ?? (() => Date.now());
     }
     /**
@@ -62,6 +68,23 @@ export class LlmQueue {
         while (this.waiters.length > 0) {
             const next = this.waiters[0];
             if (this.inFlight.size < this.maxConcurrent) {
+                // Herd guard (§3c): pace BACKGROUND-lane dispatches so a burst of queued calls can't re-trip
+                // a just-recovered provider. Interactive bypasses (latency-sensitive + preemptive). When a
+                // background dispatch is too soon after the previous one, schedule a paced re-drain instead of
+                // starting now. Because interactive waiters sort ahead, a background head means no interactive
+                // is waiting — so deferring it blocks nothing else. OFF when backgroundDispatchMinGapMs <= 0.
+                if (next.lane === 'background' && this.backgroundDispatchMinGapMs > 0 && this.lastBackgroundStartAt > 0) {
+                    const since = this.now() - this.lastBackgroundStartAt;
+                    // Jitter the gap (full-jitter low half) so independent recoveries don't re-sync into a herd.
+                    const gap = Math.floor(this.backgroundDispatchMinGapMs * (0.5 + Math.random() * 0.5));
+                    if (since < gap) {
+                        this.schedulePacedDrain(gap - since);
+                        break;
+                    }
+                }
+                if (next.lane === 'background' && this.backgroundDispatchMinGapMs > 0) {
+                    this.lastBackgroundStartAt = this.now();
+                }
                 this.waiters.shift();
                 this.start(next);
                 continue;
@@ -82,6 +105,19 @@ export class LlmQueue {
             break;
         }
     }
+    /**
+     * Schedule a single paced re-drain (§3c herd guard). Coalesces to at most one pending timer so a
+     * burst of background enqueues can't stack timers. `unref`'d so it never holds the process open.
+     */
+    schedulePacedDrain(delayMs) {
+        if (this.pacingTimer)
+            return;
+        this.pacingTimer = setTimeout(() => {
+            this.pacingTimer = null;
+            this.drain();
+        }, Math.max(1, delayMs));
+        this.pacingTimer.unref?.();
+    }
     start(w) {
         const controller = new AbortController();
         const inflight = {

package/dist/monitoring/LlmQueue.js.map

@@ -1 +1 @@
-{"version":3,"file":"LlmQueue.js","sourceRoot":"","sources":["../../src/monitoring/LlmQueue.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"LlmQueue.js","sourceRoot":"","sources":["../../src/monitoring/LlmQueue.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.640",
+  "version": "1.3.642",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-22T03:15:59.405Z",
-  "instarVersion": "1.3.640",
+  "generatedAt": "2026-06-22T07:19:14.502Z",
+  "instarVersion": "1.3.642",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "b8cabbf22cdb28187bc70a5337a9e340996eb8eace88790b9bf8ba2d9a2b5630",
+      "contentHash": "80fdbcd7e2b0c600a1766e7ebc736aa394e0eb8ccf73417a10a9643903d7a7b4",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.641.md

@@ -0,0 +1,51 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+The last rung of the rate-limit principle: **wait for capacity before falling back.** When an internal
+background check gets rate-limited and has already tried slowing-down-and-retrying and switching
+frameworks, it can now WAIT in a small queue for capacity to free up — instead of immediately giving up
+and dropping to a basic rule. The wait is bounded and rate-aware (it rides the same circuit-breaker
+timing that protects the account), so a burst of queued checks can't re-trip the limit the moment it
+recovers. Only background, non-urgent checks queue; anything the agent is actively waiting on still
+fails fast. If the queue is full or over its daily budget, the check falls through to its basic rule
+exactly as before — never silently dropped.
+
+This is **off by default** (on for the dev agent first), reuses the existing wedge-safe queue, and
+changes nothing for any other queue user.
+
+## What to Tell Your User
+
+Nothing changes unless you turn it on. Once on, if a background check hits a rate limit, it will
+briefly wait its turn for capacity to come back before falling back to a simpler rule — so you lose the
+smart answer less often. Urgent checks you are waiting on still respond fast, and if there is no spare
+capacity the check just uses its basic rule like before.
+
+## Summary of New Capabilities
+
+- `IntelligenceRouter` DEFERRABLE queue rung (`tryDeferrableQueue`): a non-gating call that exhausts
+  backoff + framework-swap enqueues onto a dedicated `LlmQueue` (background lane) and WAITS for
+  capacity (the enqueued `provider.evaluate` honors the account-global breaker's `retryAfterMs`)
+  before dropping to the caller's heuristic. Inserted at both fall-through points.
+- A GATING call is NEVER queued (`deferrable = !gating && …`, code-enforced — D5). An enqueue
+  rejection (daily-cap / interactive-reserve) or queued-call failure falls through to the heuristic,
+  never dropped. Two new `onDegrade` reasons (`queued` / `queue-rejected`) for `/metrics/features` (D7).
+- `LlmQueue` opt-in `backgroundDispatchMinGapMs` (§3c herd guard): a jittered minimum gap between
+  background dispatches; interactive bypasses; default 0 = off (zero change for existing callers).
+- Config `intelligence.degradationLadder.queue` → `{ enabled?, attemptTimeoutMs?, drainMinGapMs? }`;
+  `DEV_GATED_FEATURES` entry `degradationLadderQueue` (live-on-dev / dark-on-fleet).
+
+## Evidence
+
+**Before:** a deferrable internal call that exhausted backoff + framework-swap dropped STRAIGHT to its
+heuristic — even when capacity would have freed up moments later. **After:** with the rung enabled, it
+WAITS for capacity in a bounded, rate-aware queue first, and only falls back if the queue rejects it or
+the queued call fails. Reproduced by `tests/unit/degradation-ladder.test.ts` (7 queue cases: success +
+auto-resolve; order backoff/swap → queue → success; GATING never queued; enqueue-rejection ⇒ heuristic
+fallthrough; non-deferrable never queued; no-llmQueue no-op; queueEnabled:false not enqueued) and
+`tests/unit/LlmQueue.test.ts` (3 pacing cases). The rung reuses the existing wedge-safe `LlmQueue` and
+never calls the DegradationReporter alert machinery, so the 2026-06-21 event-loop wedge cannot recur.
+Full `tsc` + dark-gate lint green; `no-silent-fallbacks` holds at baseline 476.

package/upgrades/1.3.642.md

@@ -0,0 +1,46 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+A new guard in the agent's Stop hook catches a specific, recurring self-sabotage: the agent names
+clear work it knows how to do next, then stops anyway with a self-protective excuse — "this session
+is too long," "it's late," "I made mistakes so I'll be careful," "I don't want to rush," "it's
+tracked so it won't slip," "I'll do it next session." Those are false reasons to stop. The guard
+detects the pattern (a named next action plus one of those rationalizations) and blocks the stop
+once, re-feeding a reminder that the excuse is false and to proceed now. It can never trap the agent
+in a loop, and it leaves a genuine stop alone (a real external blocker, work actually finished, or a
+decision only the user can make).
+
+## What to Tell Your User
+
+Your agent should stop wasting your time by quitting partway through work it clearly knows how to
+finish. If it tries to stop with an excuse like "it's late" or "let's do this next session" while
+there's an obvious next step, it now gets caught and nudged to just do the thing — so you no longer
+have to come back and say "okay, do the thing you just said you'd do."
+
+## Summary of New Capabilities
+
+- `stop-gate-router` hook gains a mode-independent `falseExcuseDeferralGuard`: when the final message
+  contains BOTH a named piece of remaining work AND a self-protective deferral rationalization
+  (session-length, time-of-day, made-mistakes, don't-rush, tracked-so-it-won't-slip, next-session),
+  it blocks the stop once and re-feeds a "this is false — proceed now" directive.
+- Pure substring matching, fires once per stop (the `stop_hook_active` loop guard prevents traps),
+  and requires the AND of both signals so a genuine completion or a no-work time reference is not
+  blocked.
+- Ships to every agent automatically via the always-overwrite hook update path (no per-agent
+  migration needed).
+
+## Evidence
+
+**Before:** the Stop gate only caught "stated-continuation" (the agent saying "I'll do X now" then
+not). It did NOT catch the inverse — the agent explicitly justifying NOT doing the clear next thing
+("after a long session I won't rush this; it's tracked"). That pattern repeatedly ended sessions
+early and forced the operator to re-issue "do the thing you just said." **After:** the new guard
+catches it. Reproduced by `tests/unit/stop-gate-false-excuse-deferral.test.ts` (6 cases): it renders
+valid JS, blocks the real-world excuse-stop and a session-length/next-session deferral, does NOT
+block a genuine completion or a time reference with no pending work, and does NOT re-block under
+`stop_hook_active`. The existing `stop-gate-stated-continuation` + `generated-hooks-parse` suites
+stay green.

package/upgrades/side-effects/false-excuse-deferral-stop-guard.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — False-Excuse Deferral Stop-Guard
+
+**Slug:** `false-excuse-deferral-stop-guard` · **Tier:** 1 (small, low-risk hook behavior addition;
+operator-requested direct fix, no spec). Touches `PostUpdateMigrator.getStopGateRouterHook()` (a
+hook template), so the tier signal flags `belowFloor` (a PostUpdateMigrator touch raises the floor) —
+accepted: the change is a self-contained substring guard, fully reversible, no external surface.
+
+## Summary of the change
+
+`stop-gate-router` hook gains `falseExcuseDeferralGuard`, mirroring the existing
+`statedContinuationGuard`: a mode-independent IIFE that, on a Stop, blocks ONCE when the final
+assistant message contains BOTH (a) a named piece of remaining work AND (b) a self-protective
+deferral rationalization (session-length / time-of-day / made-mistakes / don't-rush /
+tracked-so-it-won't-slip / next-session), re-feeding a "this excuse is false — proceed" directive.
+Same change in the deployed copy is overwritten from this source on the next update (Migration
+Parity — always-overwrite built-in hooks), so it reaches every agent.
+
+## 1. Over-block / false positive
+
+The AND-of-both-signals requirement is the false-positive control: a self-protective phrase alone
+(e.g. "it's late, but everything is done") does NOT block — `knownWork` must also match. Tested:
+a genuine completion and a time-reference-with-no-pending-work both pass through (no block). Cost of
+any residual false positive is bounded to ONE extra turn (the agent re-affirms and re-stops), because
+the guard fires once.
+
+## 2. Under-block
+
+If the agent stops with an excuse but uses wording outside the phrase lists, it slips through (a
+false negative) — acceptable: the guard is a high-precision catch for the documented recurring
+phrasings, not a complete classifier. The lists cover the operator-cited forms and the agent's actual
+observed messages. Tunable by extending the arrays.
+
+## 4. Signal vs authority
+
+The guard is a one-shot re-feed (block decision with a reminder), exactly like the
+stated-continuation guard. It never silences or rewrites a message and takes no destructive action.
+The `stop_hook_active` loop guard guarantees the agent is never trapped — a legitimate stop (real
+external blocker / work complete / a user-only decision) re-stops cleanly on the next attempt.
+
+## 5. Interactions
+
+Sits directly after `statedContinuationGuard` in the same hook, before the server round-trip — so it
+works even when the server-side stop-gate is in shadow/off mode (which is exactly when these stalls
+slip through). No new dependency, no network call, no state. Pure substring matching. Cannot recurse
+or grow unbounded.
+
+## 6. External surfaces
+
+None. No route, no egress, no spend (no LLM call — deterministic substring matching in the hook
+subprocess).
+
+## 7. Multi-machine posture
+
+Machine-local: the hook runs per-session on whichever machine hosts the session. No replicated state.
+Each agent on each machine gets the guard via the standard hook update.
+
+## 8. Rollback cost
+
+Trivial: delete the `falseExcuseDeferralGuard` IIFE from `getStopGateRouterHook()`; the next update
+overwrites the deployed copy back to guard-free. No data, no migration to unwind.
+
+## Evidence pointers
+
+- `tests/unit/stop-gate-false-excuse-deferral.test.ts` (6): renders valid JS containing the guard;
+  blocks the real-world excuse-stop (named work + self-protective excuse); blocks a
+  session-length/next-session deferral; does NOT block a genuine completion; does NOT block a time
+  reference with no deferred work (false-positive control); does NOT re-block under `stop_hook_active`.
+- `tests/unit/stop-gate-stated-continuation.test.ts` + `tests/unit/generated-hooks-parse.test.ts`
+  stay green (the template literal still renders valid JS). Full `tsc` clean.
+
+## Conclusion
+
+Delivers the operator-requested structural catch for the recurring false-excuse early-stop, as an
+instar feature that ships to every agent. High-precision, loop-safe, reversible, no external surface.
+Ship.

package/upgrades/side-effects/resilient-degradation-ladder-increment-3.md

@@ -0,0 +1,108 @@
+# Side-Effects Review — Resilient Degradation Ladder Increment 3 (queue rung)
+
+**Slug:** `resilient-degradation-ladder-increment-3` · **Tier:** 2 (spec-driven; the spec converged +
+operator-approved, rode Increments 1/2). **Spec:** `docs/specs/resilient-degradation-ladder.md` §3b.3,
+§3c, D1/D5/D7.
+
+## Summary of the change
+
+The third (and final) rung of the operator's degradation principle — "prefer slowing down over
+falling back". Dark/dev-gated:
+
+- `IntelligenceRouter` gains a DEFERRABLE **queue rung** (`tryDeferrableQueue`): a non-gating call
+  that has exhausted backoff + framework-swap now WAITS for capacity in a dedicated `LlmQueue`
+  (`background` lane) before dropping to the caller's heuristic. The enqueued `provider.evaluate`
+  honors the account-global breaker's `retryAfterMs` via `acquireOrWait` — that IS the §3b.3
+  rate-awareness. Inserted at BOTH fall-through points (no-swap-configured AND swap-exhausted) before
+  the existing `onHeuristicFallthrough` + throw.
+- A structural `DeferrableQueue` interface declared in `core` (the real `LlmQueue` satisfies it) so
+  `core` does NOT import `monitoring` (no layering cycle).
+- `LlmQueue` gains an opt-in `backgroundDispatchMinGapMs` (§3c herd guard): a jittered minimum gap
+  between BACKGROUND-lane dispatches; interactive bypasses. Default 0 = OFF (today's greedy drain).
+- Server wires a DEDICATED `LlmQueue` for the rung (built ONLY when the gate-resolved `queueEnabled`
+  is true), gate-resolves `queueEnabled`/`queueAttemptTimeoutMs` via `resolveDevAgentGate`, and the
+  ladder object is now present when ANY rung (backoff OR queue) is active.
+- `DEV_GATED_FEATURES` registration (`degradationLadderQueue`).
+- Config type extended: `degradationLadder.queue` → `{ enabled?, attemptTimeoutMs?, drainMinGapMs? }`.
+
+## Decision-point inventory (frozen)
+
+D1 (config + dark rollout), D5 (`gating:true` ⇒ queue-skipped, code-enforced), D7 (reason taxonomy
+`queued` / `queue-rejected`). Increment-3 bounds (sensible defaults, dark/reversible, fit D1's
+`{enabled, …bounds}` structure): `queueAttemptTimeoutMs` 60000, dedicated queue `maxConcurrent` 1 +
+`maxDailyCents` 25, `drainMinGapMs` 0 (off).
+
+**D9 (new, recorded here) — the §3c herd guard is opt-in, realized two ways:** (1) the PRIMARY
+rate-awareness is the provider-layer `acquireOrWait` — each enqueued `evaluate` waits for the
+account-global breaker window, so queued calls don't hammer a rate-limited account; (2) the dedicated
+queue's `maxConcurrent: 1` serializes deferrable retries (naturally herd-safe); (3) `drainMinGapMs`
+adds an OPTIONAL jittered inter-dispatch gap (off by default). Explicit pacing is opt-in so existing
+`LlmQueue` callers (PresenceProxy / PromiseBeacon) see ZERO behavior change. This faithfully delivers
+§3b.3/§3c without rebuilding shared infrastructure (round-1 "extend, don't rebuild").
+
+## 1. Over-block / false positive
+
+The rung only ADDS a wait-for-capacity step on a DEFERRABLE call that already exhausted swap; it never
+blocks an interactive/gating call. A queued call that fails or is rejected falls through to exactly
+today's heuristic — strictly no worse than before. No new block surface.
+
+## 2. Under-block
+
+A GATING call NEVER reaches the queue rung: `deferrable = !gating && options.deferrable === true`, so
+`if (deferrable) …tryDeferrableQueue` is structurally unreachable for a gate (D5). Unit-tested
+(`GATING is NEVER queued`). The gating fail-closed boundary is unchanged.
+
+## 4. Signal vs authority
+
+The queue rung takes no destructive action — it waits for capacity then returns a real answer, or
+falls through. The two `onDegrade` emissions (`queued` / `queue-rejected`) are observability signals
+(D7), never gates. Consistent with Signal-vs-Authority.
+
+## 5. Interactions — wedge-safety
+
+Reuses the EXISTING `LlmQueue` (the wedge-safe, bounded, daily-capped queue). The new drain-pacing is
+a bounded `setTimeout` coalesced to at most one pending timer (no stacking), `unref`'d (never holds the
+process open). No new recursion, no growing array, no `report()`/`reportEvent()` call from the rung —
+the 2026-06-21 DegradationReporter wedge class cannot recur here. The dedicated queue is built only
+when the rung is active, so the fleet allocates nothing.
+
+## 6. External surfaces
+
+No new route. No new egress — a queued call is the SAME provider.evaluate that would otherwise have
+run; it just waits for capacity. The new config (`intelligence.degradationLadder.queue.*`) is opt-in.
+
+## Framework generality
+
+Framework-agnostic — the rung keys on the resolved framework and enqueues whatever provider the
+component routes to.
+
+## 7. Multi-machine posture
+
+Machine-local: each machine's router + its dedicated queue are independent. No replicated state, no
+cross-machine contract (the dedicated queue is per-process, same posture as the existing per-sentinel
+queues).
+
+## 8. Rollback cost
+
+Trivial: dark on the fleet (`queueEnabled` resolves dark; no dedicated queue is built, the ladder's
+`queueEnabled` is false, and `tryDeferrableQueue` returns `{ ok: false }` immediately ⇒ exactly
+today's heuristic-on-exhaustion). Revert = remove an unused-on-fleet code path. `drainMinGapMs` defaults
+0 so existing `LlmQueue` callers are untouched.
+
+## Evidence pointers
+
+- `tests/unit/degradation-ladder.test.ts` (+7 queue cases): queue success + onResolved; order
+  backoff/swap → queue → success; GATING never queued (D5); enqueue REJECTION ⇒ heuristic fallthrough
+  + onHeuristicFallthrough; non-deferrable never queued; queueEnabled-but-no-llmQueue no-op;
+  queueEnabled:false not enqueued.
+- `tests/unit/LlmQueue.test.ts` (+3 pacing cases): paces a 2nd background dispatch when the gap is set;
+  no pacing when off (both start at once); interactive bypasses pacing.
+- `tests/unit/devGatedFeatures-wiring.test.ts` auto-covers `degradationLadderQueue` (live-on-dev /
+  dark-on-fleet). `tests/unit/no-silent-fallbacks.test.ts` stays at baseline 476. Full `tsc` +
+  `lint-dev-agent-dark-gate` green.
+
+## Conclusion
+
+Delivers the final rung of the operator's degradation principle — a deferrable call now WAITS for
+capacity (slow down) before ever dropping to a brittle heuristic, with the provider breaker supplying
+rate-awareness and an opt-in herd gap on top. Dark/dev-gated, no-op when off, wedge-safe. Ship.