instar 1.3.647 → 1.3.649

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/1.3.649.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Three small, pre-existing dashboard issues, found while verifying the dashboard-freeze fix (#1253). None affect the dashboard connection.
+
+1. The dashboard polled the WhatsApp QR endpoint every 3s and never stopped when WhatsApp wasn't configured — the route answers 503, but the poll kept firing, piling ~20 console 503 errors/min into the browser for the whole session. It now stops the poll on the first 503.
+2. A parse-time script block attached a WebSocket "message" listener to `ws` before `connectWebSocket()` had assigned it, so `ws` was null and `ws.onmessage` threw "Cannot read properties of null (reading 'onmessage')" on every page load (and the paste-panel refresh it enabled never actually worked). Paste handling moved into the main `handleMessage` switch — no more error, and it now survives reconnects.
+3. The `/health` "Degraded" badge turned orange whenever any degradation event had ever been recorded, and those events never self-clear — so one transient/benign fallback pinned the badge red for the whole process lifetime even after recovery. `/health` now counts only degradations from the last 30 minutes (`DegradationReporter.getRecentEvents`); a persistent problem keeps re-reporting so it stays visible, a one-off ages out. An unparseable timestamp is kept (fail-safe). The full degradation log and the mark-reported path are unchanged, and on a Telegram agent the `status` field never gated restarts.
+
+## What to Tell Your User
+
+If your dashboard's health badge was stuck on "Degraded" even though everything looked fine, that's fixed — it now reflects current health and clears once a transient blip has passed (a real, ongoing problem still shows). You won't notice the other two fixes directly: they quietly remove browser-console noise and an on-load error. (A separate, deeper item — a "system review" panel showing days-old data because it never re-runs — is tracked separately.)
+
+## Summary of New Capabilities
+
+- `DegradationReporter.getRecentEvents(windowMs = 30min, now)` — a time-windowed view of degradation events. `/health` uses it for `status` + the reported count/summary, so the dashboard "Degraded" badge reflects CURRENT health rather than any-event-ever-recorded. The full append-only log (`getEvents`) and the mark-reported path are untouched.
+- Dashboard: the WhatsApp QR poll stops on a 503 (adapter absent) — removes ~20 console 503s/min of noise.
+- Dashboard: paste WebSocket events (`paste_delivered` / `paste_acknowledged`) are handled in the main message router — removes the on-load null-deref TypeError and makes the paste-panel refresh survive reconnects.
+
+## Evidence
+
+Observed live on this agent (Echo) while verifying #1253:
+
+1. **WhatsApp poll spam** — Before: with no WhatsApp adapter configured, the browser console accumulated repeated `GET /whatsapp/qr 503` errors at the 3s poll cadence (~20/min) for the whole session. After: the poll stops on the first 503 (`stopWaPolling()`), so the console stays clean.
+2. **On-load null deref** — Before: `Uncaught TypeError: Cannot read properties of null (reading 'onmessage')` fired at `dashboard:~9289` on every page load (the block ran at parse time, before `connectWebSocket()` assigned `ws`), and the paste-panel refresh it was meant to wire never ran. After: paste events are handled in `handleMessage`; the parse-time block is gone, so the load-time TypeError no longer occurs.
+3. **Stuck "Degraded" badge** — Before: `curl /health` on a healthy box returned `{"status":"degraded","degradations":2,...}` where both events were a benign `"Stop event allowed without authority ruling … fail-open"` recorded earlier in the boot — never cleared, pinning the badge red. After (unit-proven, `tests/unit/degradation-reporter.test.ts`): `getRecentEvents()` returns only events within the 30-min window, so once those benign events age out `status` returns to `ok`; a re-reported (persistent) degradation stays inside the window and keeps the badge red.

package/upgrades/eli16/autoupdate-strand-detector.md

@@ -0,0 +1,22 @@
+# ELI16 — Notice when an update silently fell off the truck
+
+## The problem in plain words
+
+Instar updates itself by installing the new version into a private folder (the "shadow install") and then restarting onto it. To avoid loops, it keeps a note: "I already applied version X." On each check, if that note matches the latest version, it shrugs and says "downloaded, just waiting for a restart."
+
+But that note is just a *memory* — it's not the same as *checking the folder*. And the version number the program reports for itself is read once when it starts up and then cached, so it never notices if the folder changes underneath it.
+
+So here's the failure: an update installs successfully (the folder now has the new version, the note says "applied X"). Then something knocks the folder back to the OLD version — for example, a crash-loop where two copies of the program fight, or a half-finished re-install. Now the note still says "I applied X," but X isn't actually in the folder anymore. The updater believes it's up to date, refuses to re-apply, and every time it checks it cheerfully reports "downloaded, waiting for a restart" — which is a lie. The agent is quietly stuck on the old version forever, and nobody can tell from the message.
+
+This really happened: an agent got stranded on the old version while its note insisted it had the new one. It only got unstuck when a human manually re-installed.
+
+## The fix
+
+Add a way to read the *live* version straight from the folder on disk (uncached), and use it. When the updater is about to print "downloaded, waiting for a restart," it now first checks the folder. If the folder doesn't actually have the version the note claims, it knows it's stranded — so instead of the misleading "waiting for a restart" it prints a loud warning and sends one honest heads-up: "an update was recorded as installed but isn't actually on disk — I'm stuck on the old version and won't auto-update until this is re-applied. Nothing's broken, but I won't pick up new versions until it's fixed."
+
+## What it does and doesn't do
+
+- It does: catch the stranded state immediately and tell a human (and the logs) the truth, with the exact versions involved and how to re-apply.
+- It doesn't (yet): automatically fix the strand by re-installing. That auto-repair is a deliberate follow-up, because re-installing on the critical update path can loop if the folder keeps getting knocked back, so it needs a careful retry limit and proper review. This change is the safe, observe-only first step: stop hiding the problem.
+
+Low risk: it's a new read plus a corrected message; it only triggers on the genuine strand (a normal "applied, waiting for restart" never reaches it), and it's covered by tests.

package/upgrades/eli16/dashboard-health-signal-polish.md

@@ -0,0 +1,26 @@
+# ELI16 — Three small dashboard annoyances, cleaned up
+
+## The problem in plain words
+
+While fixing the big "dashboard keeps saying Disconnected" bug, I noticed three smaller, pre-existing issues. None of them break the connection — they're noise and one misleading light — but they're the kind of papercut that makes a healthy system look unwell.
+
+**1. A button that never stopped knocking.** The dashboard checks "is WhatsApp set up?" every 3 seconds by pinging a WhatsApp address. If WhatsApp *isn't* set up (the normal case here), that address politely answers "not available" — but the dashboard kept asking anyway, forever. The result was about twenty error lines a minute piling up in the browser's hidden console. Harmless, but messy, and it buries real errors in the noise.
+
+**2. An error thrown on every page load.** Tucked at the very end of the dashboard's code was a line that tried to hook into the live connection to refresh a small "paste" panel. But it ran *too early* — before the connection actually existed — so it tried to use something that wasn't there yet and threw a "can't read a property of nothing" error each time the page loaded. Worse, because it ran at the wrong moment, the paste-refresh it was supposed to enable never actually worked.
+
+**3. A warning light stuck on.** At the top of the dashboard there's a little health badge: green "Healthy" or orange "Degraded". It turns orange if *anything* ever reported a hiccup. The catch: those hiccup reports are never erased. So one tiny, long-recovered blip would keep the badge orange for the entire time the server was running — telling you something's wrong when everything is actually fine.
+
+## The fix
+
+**1.** When the WhatsApp check gets the "not available" answer, stop checking. (If WhatsApp gets set up later, a page refresh starts it again.) The console noise is gone.
+
+**2.** Move the paste-refresh handling into the dashboard's normal message router — the place that's always listening once the connection is live. That removes the early-run error *and* makes the paste-refresh actually work, even after the connection drops and comes back.
+
+**3.** Make the health badge only count hiccups from the last 30 minutes. A real, ongoing problem keeps reporting itself, so it stays visible — but a one-off blip that recovered quietly ages out, and the badge goes back to green like it should. To be safe, a hiccup with a missing or garbled timestamp is always kept (better to show a maybe-stale warning than to hide a real one).
+
+## What it does and doesn't do
+
+- It does: silence the console spam, remove the on-load error (and revive the paste-refresh), and make the "Degraded" badge tell the truth about *current* health.
+- It doesn't: change anything about restarts (on this agent the badge doesn't control restarts — that's decided separately by whether the server process is actually alive), and it doesn't touch the full record of past hiccups — only the *summary badge* is time-windowed.
+
+Low risk: two of the three are small front-end guards in the dashboard page; the third is a contained, well-tested change to which hiccups the health summary counts. A separate, deeper issue — a different "system review" panel showing data from days ago because it never re-runs — is left for a follow-up, because re-running its checks on a schedule is a bigger, cost-bearing change.

package/upgrades/eli16/worktree-monitor-async-git.md

@@ -0,0 +1,24 @@
+# ELI16 — Make the worktree scan stop freezing the server
+
+## The problem in plain words
+
+Instar's server runs everything on a single thread — one line at a time, like a single cashier serving a queue. If any one task takes a long time, *everything else waits*: the dashboard's live connection, the message handlers, all of it.
+
+One of the background helpers, the **WorktreeMonitor**, periodically looks at all the git "worktrees" (separate working copies of the code) to spot abandoned work. To do that it shells out to `git worktree list` and a few other git commands. The way it called git was **synchronous** — meaning the single thread sat there and *waited* for git to finish before doing anything else.
+
+That's fine when there are a handful of worktrees. But on a machine where worktrees pile up (one agent had ~282 of them!), `git worktree list` takes a few *seconds*. And this scan ran on a 5-minute timer **and** every time a background job finished. So every few minutes the whole server froze for a second or two.
+
+## Why it showed up as "dashboard disconnected"
+
+On the local address you'd never notice — the dashboard's live connection just reconnects instantly. But when you reach the dashboard through the internet tunnel, a one- or two-second server freeze is enough to **drop the live connection and time out the data**. The result is the dashboard showing "Disconnected, 0 sessions, 0% memory" — even though the server is actually fine, it was just frozen for a moment.
+
+## The fix
+
+Make the git calls **asynchronous**. Instead of the single thread sitting and waiting for git, it kicks off the git command and goes back to serving everyone else; when git finishes, it picks the result back up. Same scans, same schedule, same results — but the server stays responsive the whole time, so the dashboard's live connection never drops.
+
+## What changed and what didn't
+
+- Changed: the worktree scan's git calls no longer block the server thread.
+- Unchanged: it still scans on the same 5-minute timer and after each job, still reports the same things, and the `/hooks/worktrees` endpoint returns the exact same data. The git calls keep their old behavior of returning whatever output they produced even if git exits with an error.
+
+It's a small, low-risk change covered by the existing tests (all green), and it's the permanent replacement for a quick hotpatch that had temporarily disabled the scans to stop the freezing.

package/upgrades/side-effects/autoupdate-strand-detector.md

@@ -0,0 +1,36 @@
+# Side-Effects Review — Auto-update version-strand detector
+
+**Version / slug:** `autoupdate-strand-detector`
+**Date:** `2026-06-23`
+**Author:** Echo (autonomous)
+**Tier:** 1 (observe-only diagnostic — no change to update behavior, no new config, no decision points)
+**Second-pass reviewer:** not-required (Tier 1; the new method + a corrected log/notify branch, covered by unit tests)
+
+## Summary of the change
+
+The AutoUpdater has a loop-breaker (`if lastAppliedVersion === latestVersion`) that, on every tick, assumes the recorded-applied version is genuinely installed in the shadow and prints a benign "downloaded, waiting for a restart" message. But `getInstalledVersion()` caches the version the running process booted with — it does NOT reflect the LIVE shadow on disk.
+
+If the shadow REVERTS after a successful apply (e.g., crash-loop collateral, or a partial re-install) while `lastAppliedVersion` still records the new version, the agent is **stranded**: the updater believes it is current, the loop-breaker never re-applies, and the misleading "waiting for a restart" message hides a permanent stuck state. This actually happened (an agent stranded on the old version while `lastAppliedVersion` claimed the new one).
+
+## The change
+
+- `src/core/UpdateChecker.ts` — new `getShadowInstalledVersion(): string | null`, an **uncached** read of `{stateDir}/shadow-install/node_modules/instar/package.json`. Distinct from `getInstalledVersion()` (which caches the running-process version).
+- `src/core/AutoUpdater.ts` — in the loop-breaker, read the live shadow-disk version; if it differs from `lastAppliedVersion` (the shadow doesn't actually have what the record claims), emit a distinct loud STRAND warning + a one-time honest notification ("an update was recorded as installed but isn't on disk — I'm stuck until it's re-applied") instead of the benign "awaiting restart" message.
+- `tests/unit/UpdateChecker.test.ts` — 4 tests for `getShadowInstalledVersion` (reads the disk version, reflects a reverted version uncached, returns null when absent / version-less).
+
+## Side effects & risk
+
+- **Observe-only.** Update behavior is unchanged: the strand path still `return`s (no auto re-apply — a bounded auto-heal is a deliberate follow-up). The change only corrects the diagnosis and the one-time notification text.
+- **No false positives on the benign case.** A genuine "applied, awaiting restart" has shadow-disk === lastAppliedVersion → `updateAvailable` is false → the tick returns before the loop-breaker. Reaching the loop-breaker with shadow-disk ≠ lastAppliedVersion is the strand.
+- **Fail-safe reads.** `getShadowInstalledVersion()` returns null on any read error; a null shadow version never trips the strand branch (it falls through to the existing benign messages).
+- **Risk:** low. New diagnostic method + a corrected branch, both covered by unit tests; AutoUpdater's existing 29 tests stay green.
+
+## Verification
+
+- `tsc --noEmit`: 0 errors.
+- `tests/unit/UpdateChecker.test.ts`: 17/17 (incl. 4 new).
+- `tests/unit/AutoUpdater.test.ts` + `tests/unit/auto-updater-failures.test.ts`: 29/29.
+
+## Rollout
+
+No flag, no migration. Strictly additive diagnostic — surfaces a previously-silent stuck state. The bounded auto-re-apply self-heal (which would also FIX the strand, not just surface it) is a tracked Tier-2 follow-up (it mutates the critical update path and warrants spec-converge review).

package/upgrades/side-effects/dashboard-health-signal-polish.md

@@ -0,0 +1,59 @@
+# Side-Effects Review — Dashboard health-signal polish (3 pre-existing fixes)
+
+**Version / slug:** `dashboard-health-signal-polish`
+**Date:** `2026-06-23`
+**Author:** Echo (autonomous)
+**Tier:** 1 (three contained, low-risk fixes — two client-side dashboard guards + one health-status windowing on an endpoint whose `status` field does not gate restarts on this agent)
+**Second-pass reviewer:** not-required (Tier 1; small contained fixes, the server-side change covered by new unit tests)
+
+## Summary of the change
+
+Three minor, pre-existing dashboard issues found while verifying the dashboard-freeze fix (#1253). None affect the dashboard connection; all are noise/cosmetic.
+
+1. **WhatsApp QR poll spam.** `pollWaQr()` polls `/whatsapp/qr` every 3s. When WhatsApp isn't configured the route returns 503, but the poll loop was never stopped — so the browser console accumulated ~20 503s/min for the whole session. Fix: call `stopWaPolling()` on the 503 (adapter absent).
+2. **Null-deref TypeError on load.** A parse-time block attached a `'message'` listener to `ws`, guarded by `if (typeof ws !== 'undefined')`. `ws` is a declared `let` that is **null** at parse time (`connectWebSocket()` runs later in a `.then()`), and `typeof null === 'object' !== 'undefined'`, so the guard passed and `ws.onmessage` threw `Cannot read properties of null (reading 'onmessage')` on every load. The block was the only place paste WebSocket events refreshed the drop-zone — so the feature was also effectively dead. Fix: fold `paste_delivered` / `paste_acknowledged` into the main `handleMessage` switch (where it survives reconnects) and remove the broken parse-time block.
+3. **Stale "Degraded" badge.** The vital-signs badge renders `/health`'s `status`, which is `degraded` whenever `DegradationReporter.getEvents().length > 0`. Degradation events are append-only and never self-clear, so a single transient/benign fallback pins the badge red for the entire process lifetime even after recovery. Fix: `/health` now uses a new `DegradationReporter.getRecentEvents()` (30-min window) for status + the reported count/summary — a persistent problem keeps re-reporting so it stays visible; a one-off ages out.
+
+## The change
+
+- `dashboard/index.html` — (1) `stopWaPolling()` on 503; (2) paste cases added to `handleMessage`, broken parse-time block removed.
+- `src/monitoring/DegradationReporter.ts` — new `getRecentEvents(windowMs = HEALTH_WINDOW_MS, now = Date.now())` + `static HEALTH_WINDOW_MS = 30min`. Filters by event `timestamp`; an unparseable timestamp is KEPT (fail-safe: surface, never hide). `getEvents()` (full log) is unchanged.
+- `src/server/routes.ts` — `/health` calls `getRecentEvents()` instead of `getEvents()` for the `degradations` list that feeds `status` + `degradations` count + `degradationSummary`.
+- `tests/unit/degradation-reporter.test.ts` — 3 new tests (recent kept / old aged out / unparseable kept).
+
+## Side effects & risk
+
+- **`/health` status semantics.** `status` flips back to `ok` once degradations age past 30 min without recurring. Reviewed consumers: the **Telegram lifeline** derives `serverHealthy` from the supervisor's process status, NOT from `/health.status`, so this never affects restart behavior on a Telegram agent (Echo). `SlackLifeline` keys on `status === 'ok'` only to detect the unhealthy→healthy *recovery* transition (a log/notify), not to trigger restarts. The change makes status MORE truthful (reflects current health), and is the safe direction (a real, recurring problem keeps re-reporting and stays visible).
+- **The full degradation log is untouched.** `getEvents()`, `getUnreportedEvents()`, mark-reported, and persistence all still see every event — only the /health *status view* is windowed.
+- **Client-side fixes are isolated** to the dashboard static asset; no server behavior changes; the dashboard isn't in the typecheck/test suite, so both were syntax-checked with `node --check`.
+- **Risk:** low. No new config, no new route, no migration (the dashboard asset + core source ship with the package on update). Reversible (revert the three edits).
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+This change touches `dashboard/index.html`. It alters **background behavior**, not layout or primary actions — so it adds no new operator-facing controls or content. Against the four criteria:
+
+1. **Leads with the primary action?** Unchanged — the dashboard still leads with the session list + vital-signs strip. No new primary action is introduced; nothing is moved, collapsed, or pushed below the fold.
+2. **Zero raw internals as primary content?** Yes — the change adds NO displayed content. It REMOVES noise (the WhatsApp console 503 spam) and an on-load TypeError, and makes the existing plain-language health badge ("Healthy" / uptime vs "Degraded") accurate. No JSON/UUID/fingerprint/hash is shown.
+3. **Destructive actions de-emphasized?** N/A — no destructive control is added or touched.
+4. **Plain language + phone width?** Yes — the only user-visible behavioral change is the top-of-dashboard badge now correctly reads "Healthy" when the box is healthy (it was stuck on "Degraded"). Plain wording, same layout, same width — no new elements, so no phone-width regression.
+
+(The dashboard's pre-existing raw-input field — the PIN/token unlock — already carries the co-located `operator-surface-power-user` marker and is untouched here.)
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** The vital-signs badge reads THIS machine's `/health`; each machine's `DegradationReporter` and health state are local, per-machine observability (a degradation on machine A is machine A's concern). The dashboard already exposes pool-wide state through separate `?scope=pool` surfaces (sessions, guards, attention, …), which this change does not touch. The WhatsApp poll and the paste WS handler are pure client-side, per-browser-tab.
+
+- **User-facing notices?** None emitted — no one-voice gating concern.
+- **Durable state strand on topic transfer?** No durable state added; nothing strands.
+- **Generated URLs?** None.
+
+## Verification
+
+- `tsc --noEmit`: 0 errors.
+- `tests/unit/degradation-reporter.test.ts`: 20/20 (incl. 3 new windowing tests).
+- `tests/unit/{routes-degradations-mark-reported,degradation-never-silent,degradation-reporter-reentrancy-wedge}.test.ts`: 14/14 (no regression on the mark-reported / never-silent paths).
+- `dashboard/index.html` embedded script: `node --check` passes.
+
+## Rollout
+
+No flag, no migration. Three additive fixes that surface previously-hidden console errors and make the health badge truthful. The genuinely-stale `systemReview` *panel* (last ran 2026-06-20, never re-runs) is a SEPARATE, more-involved concern (re-running 16 probes on a cadence is cost-bearing) — explicitly NOT bundled here; tracked for follow-up.

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.

package/upgrades/side-effects/worktree-monitor-async-git.md

@@ -0,0 +1,39 @@
+# Side-Effects Review — WorktreeMonitor async git scans
+
+**Version / slug:** `worktree-monitor-async-git`
+**Date:** `2026-06-23`
+**Author:** Echo (autonomous)
+**Tier:** 1 (behavior-preserving async refactor — no new feature, no decision points, no dark-gate, no migration)
+**Second-pass reviewer:** not-required (Tier 1; small, low-risk, fully covered by existing unit tests)
+
+## Summary of the change
+
+`WorktreeMonitor.scanWorktrees()` issues several git commands — `git worktree list --porcelain` plus per-worktree `rev-list`/`diff` — through a private `gitCommand()` that used **`spawnSync('/bin/sh', ['-c', 'git …'])`**. On a repository with many worktrees (Echo accumulated ~282) `git worktree list` alone takes seconds, and the scan ran on BOTH a 5-minute periodic timer AND on every `sessionComplete` event. Each scan therefore blocked the **server event loop** synchronously for seconds.
+
+That freeze was invisible on `localhost` (the dashboard websocket reconnects instantly), but over the Cloudflare tunnel (`echo.dawn-tunnel.dev`) a 1–2s freeze times out in-flight requests, dropping the dashboard websocket and failing its polls → the user-visible "Disconnected / 0 sessions / Mem 0%". This is the residual event-loop-block cause behind the dashboard "disconnected" reports, after the sync-READ fixes in #1247–#1251.
+
+## The change
+
+Convert `gitCommand` from `spawnSync` to async `execFile` (promisified), and propagate `await` through the scan call graph so the event loop stays responsive while git runs in the background.
+
+Files modified:
+- `src/monitoring/WorktreeMonitor.ts` — `gitCommand` → `async` (execFile, stdout-on-nonzero-exit/timeout semantics preserved to exactly match the old `spawnSync result.stdout ?? ''`); `listWorktrees`, `checkUnmergedWork`, `findOrphanBranches`, `getDefaultBranch`, `getWorktreeAge`, `scanWorktrees` → `async`; `periodicScan` resolves worktree ages with `Promise.all` before filtering; `formatPeriodicAlert` → `async`.
+- `src/server/routes.ts` — `GET /hooks/worktrees` handler → `async`, awaits `scanWorktrees()`.
+- `tests/unit/worktree-monitor.test.ts` — the 13 tests that called the now-async methods updated to `await` them.
+
+## Side effects & risk
+
+- **Behavior preserved.** The scans still run on the same triggers and the same 5-minute interval; only the blocking changed to non-blocking. `gitCommand`'s return contract (stdout even on a non-zero exit / timeout) is kept identically, so callers see the same strings.
+- **No external surface change.** `GET /hooks/worktrees` returns the same JSON; the periodic + post-session alert paths are unchanged.
+- **Concurrency.** Scans are serialized per the existing event flow (no new parallelism introduced beyond `Promise.all` over `getWorktreeAge`, which is read-only `git show` per worktree).
+- **Risk:** low. A behavior-preserving async conversion, fully covered by the existing 22 unit tests (updated to await) + the serendipity-routes integration tests, both green.
+
+## Verification
+
+- `tsc --noEmit`: 0 errors.
+- `tests/unit/worktree-monitor.test.ts`: 22/22 pass.
+- `tests/integration/serendipity-routes.test.ts`: 22/22 pass.
+
+## Rollout
+
+No flag, no migration — the fix is strictly better behavior on the existing code path and ships on the next release. (A shadow-dist hotpatch — disabling both scan triggers — relieved the freeze immediately on the affected agent; this PR is the durable replacement that keeps the feature working without blocking.)