instar 1.3.646 → 1.3.648

package/upgrades/1.3.648.md

@@ -0,0 +1,99 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Fork-bomb prevention — the SIMPLE design (`docs/specs/forkbomb-prevention-simple.md`).
+On 2026-06-20 the Instar server fork-bombed its macOS host into OOM **twice**
+(~230-289 concurrent `claude -p` ≈ 90-115GB): `evaluate()` spawned one LLM
+subprocess per call with **zero** concurrency control, `CoherenceGate` fanned ~10
+reviewers in parallel per message, and up to three server instances each
+re-flooded. This release adds the three structural primitives that make that
+physically impossible:
+
+- **P1 — Host-wide concurrent-spawn cap (the PRIMARY control).** A host-local
+  counting semaphore (`src/core/hostSpawnSemaphore.ts`) bounds how many LLM
+  subprocesses run **at once** across every compliant Instar process on the host
+  (default **8**). It uses a holder-SET model (count live holder records under an
+  exclusive flock, not decrement/increment counter math) so it is crash-safe by
+  construction — a double-release is a no-op, a pid-reuse can't steal a slot, a
+  partial write is discarded, a crashed holder is reclaimed (pid-dead AND
+  heartbeat-stale, **this host only**; a foreign-hostname holder is NEVER
+  reclaimed; a `df -P` host-local-disk check gates reclaim, fail-closed). The cap
+  is enforced by a per-`evaluate()` wrapper provider
+  (`src/core/SpawnCapIntelligenceProvider.ts`) installed at **every** return arm
+  of `buildIntelligenceProvider` (the factory funnel) — so CoherenceGate's
+  shared-instance fan-out is bound per call. A lint
+  (`scripts/lint-no-unbounded-llm-spawn.js`) forward-guards any new provider
+  constructed outside the funnel.
+- **P2 — Single-instance lock (`src/core/SingleInstanceLock.ts`).** Refuses a
+  duplicate server instance of the same agent on a host (the 3× launchd/fleet/tmux
+  multiplier), with a bounded deploy-handoff grace so a normal restart hands off
+  cleanly. Foreign-host locks are never reclaimed; `INSTAR_ALLOW_SECOND_INSTANCE=1`
+  overrides for a deliberate second instance.
+- **P3 — Bounded ingress.** A saturated cap makes a spawn request poll-retry up to
+  `acquireMs` (default 5000ms, ~100ms interval, no in-memory waiter queue so no
+  heap growth), bounded by a concurrent-poller ceiling (`waitersMax`, default 64).
+  On genuine exhaustion the call throws a typed `LlmCapacityUnavailableError`. The
+  **four safety-gating seams** fail CLOSED on that shed instead of auto-passing:
+  `MessageSentinel.classify` (held, not `normal`), `InputGuard.reviewTopicCoherence`
+  (flagged `suspicious`, not `coherent`), `MessagingToneGate.review` (held
+  `pass:false`), and the outbound `CoherenceGate` reviewer path (block-the-turn
+  `pass:false`). The deterministic emergency-stop keyword pre-check runs **before**
+  the LLM classifier and is **exempt** from the cap — a "stop everything" halt
+  always halts.
+
+The cap is a **SAFETY FLOOR**: it ships **ON by default** for every agent (read
+with a plain `?? default`, never a dev gate), tunable via `intelligence.spawnCap`
+(`maxConcurrent`/`acquireMs`/`waitersMax`) or env (`INSTAR_HOST_SPAWN_MAX`,
+`INSTAR_SPAWN_ACQUIRE_MS`, `INSTAR_SPAWN_WAITERS_MAX`). A new `GET /spawn-limiter`
+route reports live holder count, cap, available slots, saturation, and waiters. A
+conservative OS-level `NumberOfProcesses` ceiling (512) is added to the launchd
+plist as a host-global belt under the semaphore. A new constitutional standard —
+**"Bounded Blast Radius"** — lands in `docs/STANDARDS-REGISTRY.md` with its lint +
+burst-invariant ratchet in the same PR.
+
+## What to Tell Your User
+
+- **Fork-bomb protection is on**: "I now have a hard ceiling on how much work I can
+  run at the same time, so I can never flood your machine into running out of
+  memory again — there's a safe limit (8 by default) that's always on, plus a guard
+  that stops a duplicate of me from starting up. You can ask me 'are we protected
+  against a fork-bomb?' or 'how many tasks am I running right now?' any time."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Host-wide concurrent-LLM-spawn cap (SEV-1 OOM fix) | Automatic — on by default (limit 8); tune with `intelligence.spawnCap` or env |
+| Spawn-cap status | `GET /spawn-limiter` |
+| Single-instance lock (no duplicate server) | Automatic at server boot; override with `INSTAR_ALLOW_SECOND_INSTANCE=1` |
+| Fail-closed gating under capacity pressure | Automatic — the four inbound/outbound safety gates hold instead of auto-passing |
+
+## Evidence
+
+This release fixes a SEV-1 (full host OOM ×2 on 2026-06-20). Evidence:
+
+- **Reproduction → fix mechanism.** The incident driver — one `claude -p` per
+  `evaluate()` with no concurrency control, fanned ~10-wide by CoherenceGate — is
+  now bound at the factory funnel: every provider `buildIntelligenceProvider`
+  returns is wrapped per-call by `SpawnCapIntelligenceProvider`, which acquires a
+  host-wide slot before the inner spawn and releases it in `finally`.
+- **Burst-invariant ratchet** (`tests/unit/host-spawn-semaphore-burst-invariant.test.ts`):
+  10,000 churned acquire/release attempts NEVER let live holders exceed the cap;
+  a TRUE multi-process test forks 12 OS processes racing for 3 slots and observes
+  ≤3 successes (the cross-process flock holds the cap). This is the standing
+  Bounded-Accumulation proof that the OOM vector cannot recur.
+- **Four fail-closed seams** (`tests/unit/spawn-cap-fail-closed-gates.test.ts`): a
+  capacity shed at each gating seam is asserted to HOLD (not produce
+  `normal`/`coherent`/`pass:true`), while a generic LLM error still fails open —
+  proving capacity is the only new hold. Emergency-stop is asserted exempt
+  (classified by the deterministic fast-path before any LLM call).
+- **E2E lifecycle** (`tests/e2e/spawn-cap-forkbomb-lifecycle.test.ts`):
+  `GET /spawn-limiter` is alive (200, cap 8, on by default) on a production-init
+  server, and a second single-instance-lock acquisition while a live holder exists
+  is refused (the duplicate-flood guard), while a clean release hands off.
+- All three test tiers green; `tsc --noEmit` clean; the new lint + the
+  `no-silent-llm-fallback` + `no-silent-fallbacks` ratchets green.

package/upgrades/eli16/eventloop-bounded-jsonl-reads.md

@@ -0,0 +1,47 @@
+# Bounded tail-reads for the 12MB telegram-log + 14MB feedback-store — ELI16
+
+## What this is
+
+Your agent's server runs everything on one main thread. If any single operation makes that thread
+wait, *everything* waits — the dashboard, your messages, every background check. When that wait is
+long enough, the dashboard's live connection drops (the "Disconnected" flapping you may have seen).
+
+This fixes the THIRD and FOURTH freezes behind that flapping. (The first was a slow shared terminal
+manager; the second was reading the macOS keychain the blocking way; the third was a 13MB job-history
+file re-read whole every minute — all already fixed.) This one is about two more big files.
+
+## What was wrong
+
+Your agent keeps a running log of every Telegram message it has ever sent or received, in a file
+called `telegram-messages.jsonl`. That file has grown to about **12 megabytes**. Several background
+checks only ever need to glance at the LAST few messages in that log — the last 50, or the last 100.
+But the way they were written, they read the **entire 12MB file** from disk and chopped it up, just
+to look at the tail. And some of these checks run on a **5-minute timer**, every few minutes, forever.
+Each one froze the server for up to **20 seconds**. (A second large file, a 14MB feedback log, had
+the same problem: it was re-read and re-parsed from scratch every processing pass even when nothing
+had changed.)
+
+A frozen main thread uses almost no CPU, so the freeze even looked to the agent like the laptop had
+briefly gone to sleep — a misleading signal on top of a real problem.
+
+## What's new
+
+Two simple changes, both behavior-preserving:
+
+- The background checks that only want the tail of the message log now read just the **last chunk**
+  of the file (a 512-kilobyte window — far more than enough to hold the last few hundred messages),
+  not the whole thing. So they're instant no matter how big the file gets.
+- The 14MB feedback log now remembers the file's size and last-modified time. If nothing changed
+  since it last read it, it returns the copy it already has, reading nothing from disk.
+
+So those per-call whole-file reads are gone from every one of these hot paths, and the freezes they
+caused are eliminated. Everything these checks actually do — what they look for, how they parse,
+how they recover from a corrupt file — is unchanged, and proven by tests. One of the new tests even
+plants a problem message at the very END of a multi-megabyte log to prove the tail-read still catches
+recent entries.
+
+## What you need to decide
+
+Nothing. It's self-contained and low-risk, fully covered by tests. One honest note: the log files
+themselves still grow large over time — putting a size cap on them is a separate cleanup I've flagged
+to track, not fixed here. Reading them is no longer a freeze; capping their growth comes next.

package/upgrades/side-effects/eventloop-bounded-jsonl-reads.md

@@ -0,0 +1,96 @@
+# Side-Effects Review — bounded tail-reads for the 12MB telegram-log + 14MB feedback-store (event-loop freeze fix)
+
+**Slug:** `eventloop-bounded-jsonl-reads` · **Tier:** 1 (focused low-risk bounded-read class fix, no
+spec; live-profiler root-cause). Parent principles: **Structure beats Willpower** — never block the
+event loop (the THIRD + FOURTH distinct event-loop-blocker class behind the dashboard "disconnected"
+flapping, after sync tmux + sync keychain + the JobRunHistory 13MB re-read); and **Bounded
+Accumulation** (the size of an append-only log must never determine the cost of reading it).
+
+## Summary of the change
+
+FOUR callers each did `fs.readFileSync(messageLogPath, 'utf-8')` on the ~12MB
+`.instar/telegram-messages.jsonl` just to inspect the last 50–200 lines:
+- `CommitmentSentinel.parseRecentMessages` (`src/monitoring/CommitmentSentinel.ts`) — 5-minute timer,
+  only ever looks at the last `maxMessagesPerScan*10` lines.
+- `CoherenceMonitor` output-sanity check (`src/monitoring/CoherenceMonitor.ts`) — 5-minute timer,
+  only ever looks at the last 50 agent messages.
+- `checkLogForAgentResponse` (PresenceProxy ack path, `src/commands/server.ts`) — event-driven on
+  every PresenceProxy tier verdict, only ever looks at the last 50 lines.
+- `TelegramAdapter.getMessageLog` (`src/messaging/TelegramAdapter.ts`) — analysis route, only ever
+  returns the last `limit` (default 100) entries.
+
+A 12MB synchronous read + `.split('\n')` on a 5-minute timer froze the event loop for up to ~20s per
+pass — the same ~0-CPU false-sleep signature the JobRunHistory fix removed. PLUS `JsonlFeedbackStore`
+(`src/feedback-factory/store/JsonlFeedbackStore.ts`) re-read + re-`JSON.parse`d the entire ~14MB
+`feedback.jsonl` at the start of every processing pass even when nothing had changed.
+
+The fix is two behavior-preserving mechanisms:
+
+**(A) A shared bounded tail-read utility** — `src/utils/jsonl-tail.ts` (`readJsonlTailLines` /
+`readJsonlTailLastLines`). It `statSync`s the file (O(1)), `openSync` + `readSync`s only the trailing
+`maxBytes` (default 512KB ≈ ~2,600 recent lines, far more than any caller needs) into a fixed buffer,
+drops the first partial line when the window started mid-file, and returns the trailing lines in file
+order. It NEVER loads the whole file and NEVER throws (a read failure returns an empty result,
+matching the `@silent-fallback-ok` behavior of every former full-file caller). It mirrors
+`CoherenceJournal.readTailTolerant`, generalized off that journal's typed-entry shape. The four
+telegram-log readers above now call it instead of `readFileSync`.
+
+**(B) A `(size, mtimeMs)` load cache in `JsonlFeedbackStore.loadJsonl`** — when the on-disk file is
+byte-for-byte the one last folded, it serves a clone of the prior parse with ZERO IO/parse; any
+change (append, shrink, delete) re-reads from disk. Mirrors the JobRunHistory cache pattern. The
+clone-on-serve guarantees a caller mutating the returned Map can never poison the cache.
+
+## 1. Correctness / behavioral equivalence
+
+The telegram-log readers each consumed only a fixed tail (last 50 / last 200 / last `limit`) of the
+log, so the 512KB window (≈ 2,600 lines) is strictly a superset of every caller's need — the parsed +
+filtered result is identical to the old full-split-then-slice. The partial-first-line drop guarantees
+a truncated record at the window boundary is never mis-parsed. The feedback store's load semantics
+(per-line parse, dedup-last-wins-by-id, torn-line skip, corrupt-file recovery) are preserved exactly;
+the cache is only consulted when the fingerprint matches and is invalidated on any change. Verified:
+48/48 across the four touched test files (`jsonl-tail` 9, `CoherenceMonitor-bounded-read` 2,
+`CommitmentSentinel` 26, `jsonl-feedback-store` 11) plus the cross-impact suites; tsc exit 0; lints
+green. The two new regression tests spy on `fs.readFileSync` to FAIL if the whole telegram log is
+read, AND prove a bad pattern in a RECENT agent message at the END of a multi-MB log is still
+detected via the tail.
+
+## 2. Cache-coherence / multi-writer safety
+
+The telegram-log tail-read holds no state — every call re-reads the live tail, so a concurrent
+appender is always reflected. The feedback-store `(size, mtimeMs)` key invalidates on any byte/mtime
+change (append, compaction rewrite, delete-then-recreate), so an unchanged file is the only cache-hit
+case and a stale fold can never be served. The cache is per-process in-memory (not shared) — no
+cross-process coherence concern (each process reads its own view, same as before). `loadCache` is
+keyed per absolute path and dropped on `existsSync` failure.
+
+## 3. Fail-safe
+
+`jsonl-tail.ts` never throws: missing file, stat failure, open/read failure each return an empty
+result — exactly the prior `@silent-fallback-ok` degradation of the full-file callers (an
+observability/housekeeping read must never endanger the observed operation). The feedback store's
+stat-failure path falls through to a full read (`/* fall through to a full read — never let stat
+failure skip the load */`), so a stat error degrades to the correct (slow) result, never wrong data.
+
+## 4. Blast radius
+
+One new utility module + its test; four read-site one-liner swaps (CommitmentSentinel, CoherenceMonitor,
+server.ts PresenceProxy ack, TelegramAdapter.getMessageLog); one read-path cache in JsonlFeedbackStore
++ a test-only cache-clear export. No API/route change, no schema change, no write-path semantics
+change, no new external surface.
+
+## 5. Residual (tracked, NOT fixed here — out of scope)
+
+The existing `lint-no-wholefile-sync-read` ratchet only catches LITERAL path basenames in the read
+call, but these four sites read VARIABLE paths (`this.messageLogPath`, a `logPath` param), so the
+lint could never have flagged them — which is why they survived the earlier sweeps. The durable
+structural prevention is an **accessor funnel** (route all append-log reads through a single bounded
+accessor that the lint can enforce), which is **Bounded Accumulation Increment 2** — a tracked
+follow-up named here so it is not silently dropped. Separately, the telegram-messages.jsonl and
+feedback.jsonl files themselves still grow UNBOUNDED — a size/retention cap is the same Bounded
+Accumulation track. This change makes READS cheap regardless of size; it does not cap the files.
+
+## 6. Rollback
+
+Revert the source files. The change is purely read-path (a bounded tail-read + a fingerprint cache);
+reverting restores the (slow but correct) full-read behavior. No data migration, no on-disk format
+change to undo.

package/upgrades/side-effects/forkbomb-prevention-simple.md

@@ -0,0 +1,138 @@
+# Side-Effects Review — fork-bomb prevention (SIMPLE): host-wide spawn cap + single-instance lock + bounded ingress
+
+**Slug:** `forkbomb-prevention-simple` · **Tier:** 2 (converged + approved spec —
+`docs/specs/forkbomb-prevention-simple.md`, cross-model + lessons-aware convergence at
+`docs/specs/reports/forkbomb-prevention-simple-convergence.md`). Parent principles:
+**Structure beats Willpower** (a hard ceiling enforced in code, not a "don't spawn too much"
+note) and **Bounded Blast Radius** (the new constitutional standard this PR lands — safety
+must be physical/capacity-bounded, not only semantic). This is the SEV-1 fix for the
+2026-06-20 host-OOM incident: the Instar server fork-bombed its macOS host into OOM **twice**
+(~230–289 concurrent `claude -p`, ≈ 90–115 GB) because `IntelligenceProvider.evaluate()`
+spawned one LLM subprocess per call with **zero** concurrency control, `CoherenceGate` fanned
+~10 reviewers in parallel per message, and up to three server instances each re-flooded.
+
+This is the deliberately SIMPLE redesign — three primitives, ON by default. It SUPERSEDES the
+earlier elaborate predecessor (`docs/specs/forkbomb-prevention.md`): the lanes / reserve-math /
+hysteresis / per-gate-typed-shed of that design are explicitly OUT of scope. The cap caps the
+unbounded LLM-subprocess spawns that directly produced the real crash-loop.
+
+## Summary of the change — the 3 primitives + the 4 fail-closed seams
+
+**P1 — Host-wide concurrent-spawn cap (the PRIMARY control).** A host-local counting semaphore
+(`src/core/hostSpawnSemaphore.ts`) bounds how many LLM subprocesses run **at once** across every
+compliant Instar process on the host (default **8**). Holder-SET model: it counts live holder
+records under an exclusive `O_CREAT|O_EXCL` flock (reusing the `ProjectRoundLock` primitive), not
+decrement/increment counter math, so it is crash-safe by construction — a double-release is a
+no-op, pid-reuse can't steal a slot, a partial write is discarded. A crashed holder is reclaimed
+only when pid-dead AND heartbeat-stale **on this host**; a foreign-hostname holder is NEVER
+reclaimed (refuse-loud), and a `df -P` host-local-disk check gates reclaim (fail-closed). The cap
+is enforced by a per-`evaluate()` **wrapper provider** (`src/core/SpawnCapIntelligenceProvider.ts`)
+installed at **every** return arm of `buildIntelligenceProvider`, INSIDE the circuit-breaker wrap —
+so `CoherenceGate`'s shared-instance fan-out (one `intelligence` field fanned ~10-wide via
+`Promise.allSettled`) is bound per call. `reflect.ts`'s former raw-fallback construction is routed
+through the same factory funnel.
+
+**P2 — Single-instance lock (`src/core/SingleInstanceLock.ts`).** Refuses a duplicate server
+instance of the same agent on a host (the 3× launchd/fleet/tmux multiplier that made the flood
+worse), via the same O_CREAT|O_EXCL pid+hostname+heartbeat holder record. Foreign-host locks are
+never reclaimed; release runs via `finally` + SIGTERM/SIGINT/exit handlers; a bounded deploy-handoff
+grace lets a normal restart hand off cleanly; `INSTAR_ALLOW_SECOND_INSTANCE=1` overrides for a
+deliberate second instance. A genuine duplicate refuses-loud rather than starting a second flooder.
+
+**P3 — Bounded ingress + 4 fail-CLOSED gate seams.** A saturated cap makes a spawn request
+poll-retry every ~100 ms up to `acquireMs` (default 5000 ms) — poll-retry, NOT an in-memory waiter
+queue, so no per-waiter heap growth — bounded by a concurrent-poller ceiling (`waitersMax`, default
+64). On genuine exhaustion the call throws a typed `LlmCapacityUnavailableError`
+(`isCapacityUnavailable`). The **four safety-gating seams** fail CLOSED on that shed instead of
+auto-passing:
+1. `MessageSentinel.classify` → held, NOT `category:'normal'`.
+2. `InputGuard.reviewTopicCoherence` → flagged `suspicious`, NOT `verdict:'coherent'`.
+3. `MessagingToneGate.review` → records unavailable, holds `pass:false`.
+4. the OUTBOUND `CoherenceGate` reviewer path → block-the-turn `pass:false`, NOT `pass:true`.
+
+A non-gating (background) call sheds to its existing heuristic path — loud + counted, **never
+silent**. The deterministic emergency-stop keyword pre-check runs BEFORE the LLM classifier and is
+EXEMPT from the cap — a "stop everything" halt is never gated on capacity.
+
+**Safety-floor posture + observability.** The cap is read with a plain `?? default` (NOT a dev gate)
+— it ships **ON by default for every agent**, tunable via `intelligence.spawnCap`
+(`maxConcurrent`/`acquireMs`/`waitersMax`) or env (`INSTAR_HOST_SPAWN_MAX`, `INSTAR_SPAWN_ACQUIRE_MS`,
+`INSTAR_SPAWN_WAITERS_MAX`), migrated existence-checked. A new `GET /spawn-limiter` route reports
+live holder count, cap, available slots, saturation, and waiters. A conservative OS-level
+`NumberOfProcesses` ceiling (512) is added to the launchd plist as a host-global belt under the
+semaphore. The **"Bounded Blast Radius"** constitutional standard lands in
+`docs/STANDARDS-REGISTRY.md` with its lint + burst-invariant ratchet in the same PR.
+
+## 1. Correctness / behavioral equivalence
+
+The wrapper is a pure pass-through except for the acquire/release bracket: `evaluate()` acquires a
+host slot, calls `inner.evaluate()`, releases in `finally`. When a slot is available (the normal,
+unsaturated case — ≤8 concurrent) behavior is byte-identical to before; the cap only changes
+behavior under genuine saturation, where the four gating seams hold (the safe direction) and
+background calls degrade to their existing heuristics. The breaker-INSIDE ordering (breaker →
+spawn-cap → provider) ensures a breaker-open shed never holds a slot. Emergency-stop is unchanged:
+it is classified by the deterministic fast-path before any LLM call. Verified: the four fail-closed
+seams are asserted (a capacity shed does NOT produce `normal`/`coherent`/`pass:true`) while a generic
+LLM error still fails open — proving capacity is the ONLY new hold.
+
+## 2. Concurrency / multi-process safety
+
+The semaphore is the load-bearing concurrency primitive. The burst-invariant ratchet
+(`tests/unit/host-spawn-semaphore-burst-invariant.test.ts`) churns 10,000 acquire/release attempts
+and asserts live holders NEVER exceed the cap (the standing Bounded-Accumulation proof that the OOM
+vector cannot recur), and a TRUE multi-process test forks 12 OS processes racing for 3 slots and
+observes ≤3 successes — the cross-process flock holds the cap. Every mutation is under the exclusive
+flock; the holder-SET model makes double-release / pid-reuse / partial-write all safe by
+construction. The single-instance lock uses the same flock primitive with the same foreign-host /
+host-local-disk guards.
+
+## 3. Fail-safe / fail-closed
+
+Two deliberately opposite directions, both safe:
+- **Gating calls fail CLOSED** under capacity shed (hold the inbound/outbound turn) — a security/
+  coherence gate must never auto-pass when it could not actually evaluate.
+- **Background (non-gating) calls fail OPEN to their heuristic** — loud + counted, never silent
+  (each is tagged `@silent-fallback-ok` only where genuinely fail-safe; the `no-silent-llm-fallback`
+  + `no-silent-fallbacks` ratchets stay green).
+- Reclaim is fail-closed: a foreign-hostname holder is never reclaimed; a `df -P` non-host-local-disk
+  result refuses reclaim. Uncertainty never frees a slot it shouldn't.
+
+## 4. Blast radius
+
+New: 3 source modules (`hostSpawnSemaphore`, `SpawnCapIntelligenceProvider`, `SingleInstanceLock`),
+1 lint, 1 route (`GET /spawn-limiter`). Touched: the factory funnel + `reflect.ts` (route the raw
+fallback), `server.ts` boot (configure semaphore + acquire/release the instance lock), the four gate
+seams, `types.ts` + `ConfigDefaults.ts` (the `spawnCap` config), `routes.ts` + `CapabilityIndex.ts`
+(the route), `setup.ts` (launchd belt), `STANDARDS-REGISTRY.md` (the standard),
+`templates.ts` + `PostUpdateMigrator.ts` (CLAUDE.md awareness), `package.json` + the destructive-lint
+allowlist (wire the new lint). No schema change, no write-path semantics change beyond the
+acquire/release bracket. The cap is ON by default — this is intentional (a SAFETY FLOOR), and the
+unsaturated path is behavior-preserving.
+
+## 5. On-by-default justification
+
+This is a safety floor, not a feature behind a dev gate. The 2026-06-20 incident was a full host OOM
+×2; the failure mode the cap prevents is catastrophic and physical. Reading the cap with `?? default`
+(default 8) means every agent — new and updated — gets the protection without opting in. The default
+of 8 is conservative (well below the ~230+ that OOM'd a 128 GB box) yet ample for normal CoherenceGate
+fan-out; it is fully tunable for a larger host. Migration is existence-checked so an operator's
+explicit override is never clobbered.
+
+## 6. Residual (tracked, NOT fixed here — out of scope)
+
+- The elaborate predecessor's lanes / reserve-math / hysteresis / per-gate-typed-shed are
+  deliberately deferred — the simple design was chosen precisely because it is implementable
+  CORRECTLY in one pass. If real load data later shows the single global cap is too coarse, the lane
+  model is the documented follow-up.
+- The launchd `NumberOfProcesses` belt is macOS-only; a Linux/systemd equivalent is a follow-up for
+  non-macOS hosts (the in-process semaphore is OS-agnostic and is the primary control regardless).
+- No baseline JSON for the new lint — it ships clean (zero violations), so a baseline would be an
+  empty no-op (the sibling `lint-no-unfunneled-headless-launch.js` has none either).
+
+## 7. Rollback
+
+Revert the source files. The semaphore/lock/wrapper are additive; reverting the factory-funnel wrap +
+the `server.ts` boot lines restores the prior unbounded-spawn behavior, and reverting the four gate
+seams restores their prior fail-open. No data migration and no on-disk format to undo — the
+host-spawn-holders / single-instance-lock files are host-local runtime state that is simply abandoned
+on revert. The config defaults are additive and harmless if left in place.