instar 1.3.676 → 1.3.678

package/upgrades/1.3.678.md

@@ -0,0 +1,110 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The provider-fallback default policy routed every internal off-Claude category
+(`sentinel`, `gate`, `reflector`) onto the same codex-first primary. But the
+`gate` category includes the **user-facing tone gate** — a synchronous check a
+human is waiting on — and `codex-cli` is the slowest off-Claude framework (~30s),
+which exceeds the 20s outbound-review budget and times the gate out (a cause of
+the 2026-06-25 silent-outbound incident). The `gate` category now resolves its
+default primary from a separate speed-ranked order (`pi → gemini → codex →
+claude`) — the fastest *active* off-Claude framework — while `sentinel`/`reflector`
+keep the codex-first load-spreading order. `failureSwap`, the gate's verdict
+logic, and the F4 degrade floor are all unchanged.
+
+The host spawn cap (the fork-bomb/OOM safety floor that bounds how many LLM
+subprocesses run at once) now reserves a little headroom for the user's reply. Under
+load, the user-facing tone gate used to wait in the same undifferentiated line as
+background sentinels and could time out (a cause of the 2026-06-25 silent-outbound
+incident). The cap now SUBDIVIDES into a small interactive reserve + a small background
+reserve, so a synchronous operator reply always has slots and is never starved by
+background chatter. The total cap is NEVER raised — only *who gets which slot* changes.
+Ships dark on the fleet / live on a development agent (dev-agent gate); byte-identical
+to today when off.
+
+Lands postmortem fix F7 (Blast-Radius / Verify-After), dark on the fleet / live on a dev
+agent. Two parts: (1) the live inbound spawn-guard is now a token-tagged
+`SpawningTopicsRegistry` — a hung session start no longer silently wedges a topic forever
+(ABA-safe; the `.finally` stays the sole clearer, no risky auto-clear). (2) a pure-signal
+`TopicReachabilityVerifier`: after a session is killed/reaped, it checks (after a grace
+window) that the conversation can still receive your next message, and if a genuine
+orphan (e.g. a wedged start-up) it surfaces ONE calm NORMAL heads-up. It mutates nothing —
+never kills, spawns, or clears. The probe is conservative + fail-safe (uncertain ⇒
+treated as reachable), so it never cries wolf on a normal idle kill.
+
+## What to Tell Your User
+
+Your replies' safety check now runs on the fastest available engine instead of
+the slowest, so it stops timing out under load — one fewer cause of slow or
+missing replies. Background checks are unchanged. If only one non-Claude engine is
+installed, nothing changes.
+
+When the machine is busy, your reply's safety check now jumps to a reserved slot instead
+of waiting behind background work — fewer slow/held replies under load. The crash
+protection is exactly as strong as before. Most setups see no change (it's off on the
+fleet for now).
+
+If I ever shut down a conversation's session and it genuinely can't be reached again
+(e.g. a start-up that hung), you now get one calm "this conversation may be unreachable"
+heads-up instead of your messages silently vanishing. Most of the time you see nothing,
+because most kills self-heal on your next message. It only watches — it never tries to
+auto-fix the stuck state (that proved too risky); the mechanical repair stays a tracked
+follow-up. Off on the fleet for now.
+
+## Summary of New Capabilities
+
+- The latency-sensitive `gate` category defaults to the fastest active off-Claude
+  framework (`LATENCY_SENSITIVE_FRAMEWORK_PREFERENCE`), not the codex-first order.
+- `sentinel`/`reflector`/`job`/`other` routing and `failureSwap` are unchanged.
+- An explicit `categories.gate` in config always overrides the computed default.
+- Single-off-Claude-framework agents and claude-only agents: byte-identical no-op.
+
+- `attribution.lane:'interactive'` requests reserved headroom — honored ONLY for an
+  allowlisted, user-blocking seam (the operator-facing tone gate); everything else stays
+  background.
+- Symmetric reservation within the existing cap N (`Ri`/`Rb`, default 2/2): interactive
+  guaranteed ≥Ri slots, background guaranteed ≥Rb — neither starves the other.
+- `/spawn-limiter` reports per-lane live counts + the reservation config.
+- Off (the fleet default) ⇒ byte-identical to the all-or-nothing cap (no `lane` written).
+
+- A hung session start-up can no longer permanently jam a conversation's inbound path
+  (token-tagged spawn guard; ABA-safe).
+- After a destructive session/routing op, a dev agent verifies the topic is still
+  reachable and surfaces a genuine orphan as ONE NORMAL attention item (deduped,
+  flap-backoff-capped, burst-rolled-up, pressure/emergency-stop aware with a re-sweep).
+- Visible in `/guards` (registered). Dark on the fleet (dev-agent gate). Mutates nothing.
+
+## Evidence
+
+- `internalFrameworkDefault.test.ts`: gate prefers fastest (pi) while sentinel
+  stays codex; pi-down→gemini (the gemini-serves-when-pi-down case); both-down→codex
+  (never worse than today); single-framework→no divergence. 17 unit tests pass.
+- `provider-fallback-default-routing.test.ts` (integration): the gate component on
+  `GET /intelligence/routing` reports the fastest active framework. 3 pass.
+- `provider-fallback-default-policy-lifecycle.test.ts` (e2e): route alive, policy
+  live. `tsc --noEmit` clean. 24 affected tests green.
+- Side-effects review: `upgrades/side-effects/latency-sensitive-gate-framework.md`.
+- Spec amendment: `docs/specs/provider-fallback-default-policy.md` §4.1.
+
+- `hostSpawnSemaphore-priority.test.ts` (10): symmetric reserve, OOM floor unconditional,
+  garbage-lane→background-never-dropped, clamp (N=1/N=2/oversized/0), off=byte-identical.
+- `spawn-cap-provider-lane.test.ts` (7): allowlist downgrade (CoherenceReviewer→background),
+  off→background, interactive fast-path, saturated interactive still fails closed,
+  membership pinned.
+- 25 existing spawn-cap tests + 160 tone-gate tests pass unchanged (no regression; the
+  fork-bomb burst-invariant test still green). `tsc --noEmit` clean.
+- Side-effects: `upgrades/side-effects/spawn-cap-interactive-priority.md`.
+- Spec (converged + approved): `docs/specs/spawn-cap-interactive-priority.md`.
+
+- `spawningTopicsRegistry.test.ts` (5): ABA token-guard; `.finally` sole clearer (no
+  timeout/sweep); stuck-age seam.
+- `topicReachabilityVerifier.test.ts` (8): grace; reachable-honesty (no false orphan on a
+  topic that self-heals); orphan→one NORMAL item; pressure/halt skip + re-sweep; flap
+  backoff; burst roll-up; coalescing.
+- `tsc --noEmit` clean.
+- Side-effects: `upgrades/side-effects/verify-after-reachability.md`.
+- Spec (converged + approved): `docs/specs/verify-after-reachability.md`.

package/upgrades/side-effects/latency-sensitive-gate-framework.md

@@ -0,0 +1,79 @@
+# Side-Effects Review — Latency-Sensitive Gate Framework Default
+
+**Version / slug:** `latency-sensitive-gate-framework`
+**Date:** `2026-06-26`
+**Author:** `Echo (instar-dev agent)`
+**Tier:** 1 (small, localized; one pure resolver function + its tests + docs)
+
+## Summary
+
+The provider-fallback default policy routes internal components off-Claude via a
+single codex-first preference chain (`codex-cli → pi-cli → gemini-cli →
+claude-code`). The `gate` category — which includes the **user-facing
+`MessagingToneGate`**, a synchronous check a human is waiting on — inherited that
+codex-first primary. But `codex-cli` is the SLOWEST off-Claude framework (~30s),
+which exceeds the 20s outbound-gate review budget and times the gate out (the
+2026-06-25 silent-outbound class). This change gives the `gate` category a
+SEPARATE, speed-ranked order (`LATENCY_SENSITIVE_FRAMEWORK_PREFERENCE = pi →
+gemini → codex → claude`) so it defaults to the FASTEST active off-Claude
+framework. `sentinel`/`reflector` (background) keep codex-first; `failureSwap` and
+all other categories are unchanged.
+
+## The 8 questions
+
+1. **Over-block** — N/A. This is not a gate; it selects which backend computes the
+   tone-gate verdict. It rejects nothing.
+2. **Under-block** — N/A. The tone gate's block/allow logic and its deterministic
+   degrade floor (F4) are byte-identical; only the LLM backend that produces the
+   verdict changes. A faster backend means FEWER budget-timeout degrades, i.e.
+   *more* real verdicts, not fewer.
+3. **Level-of-abstraction fit** — Correct. The change lives in the one pure policy
+   resolver (`resolveInternalFrameworkDefault`) that already computes per-category
+   primaries; `ComponentFrameworksConfig.categories` is already a per-category map,
+   so no routing-engine change is needed. The router consumes the config unchanged.
+4. **Signal vs authority** — No authority added. The resolver is a pure function
+   (active-set → config); it holds no blocking power. The tone gate's authority
+   (hold/send) is untouched. Complies with `docs/signal-vs-authority.md`.
+5. **Interactions** — The gate's PRIMARY now differs from `sentinel`/`reflector`.
+   `failureSwap` is the shared tail (`active.slice(1)`, codex-first); for a gate
+   whose primary is `pi`, the tail may list `pi` first (the just-tried framework) —
+   harmless: the failure-swap walk is circuit-checked, so a just-failed/open
+   provider is skipped. When only one off-Claude framework is active, `gatePrimary
+   === active[0]` (byte-identical no-op). No double-fire, no shadowing.
+6. **External surfaces** — `GET /intelligence/routing` now reports the gate
+   component on a (possibly) different framework than sentinels. That is the
+   intended, visible effect. No new route, no schema change.
+7. **Multi-machine posture** — **Machine-local BY DESIGN.** The default policy is
+   computed per-agent at boot from that agent's own active-framework set (which
+   frameworks' CLIs are installed/configured on THAT machine). No replication, no
+   cross-machine coupling. Each machine independently resolves the fastest gate
+   backend it has. Correct — framework availability is inherently per-machine.
+8. **Rollback cost** — Trivial. Revert the commit (one source file + tests + one
+   doc amendment). No state, no migration. An operator who wants the gate back on
+   codex sets `categories.gate` explicitly (the explicit config always wins over
+   the computed default). A single-off-Claude-framework agent is unaffected.
+
+## What it does NOT do
+
+- Does NOT change the tone gate's verdict/hold/send logic or the F4 degrade floor.
+- Does NOT touch `sentinel`/`reflector`/`job`/`other` routing, or `failureSwap`.
+- Does NOT introduce a measured latency model — the ranking (pi < gemini < codex)
+  is a documented static assertion from observed behavior (~6s / ~9-13s / ~30s),
+  owned in `LATENCY_SENSITIVE_FRAMEWORK_PREFERENCE` with a unit-tested enum guard.
+- Does NOT revoke the codex-first operator directive — it narrows it to exclude the
+  one latency-sensitive, user-blocking category.
+
+## Second-pass note (outbound-path touch)
+
+This touches the OUTBOUND tone-gate path, which is a Phase-5 trigger area. The
+substantive review point: the change adds NO block/allow authority — it only
+selects a faster backend for an existing gate, and the gate's safety behavior
+(including the deterministic degrade floor on backend failure) is unchanged. The
+decision boundary (gate diverges to fastest; background stays codex-first; single-
+framework is a no-op) is covered by the new unit + integration tests. A full
+independent reviewer was judged unnecessary for an authority-free routing-default
+change; the PR is the review surface.
+
+## Rollback
+
+Revert the commit. No migration, no state.

package/upgrades/side-effects/verify-after-reachability.md

@@ -0,0 +1,65 @@
+# Side-Effects Review — Verify-After Topic Reachability (F7 — core components)
+
+**Version / slug:** `verify-after-reachability`
+**Date:** `2026-06-26`
+**Author:** `Echo (instar-dev agent)`
+**Tier:** 2 (converged + approved spec: `docs/specs/verify-after-reachability.md`)
+**Scope:** the two pure components (first commit) PLUS the server wiring (this commit):
+Piece 1 (`spawningTopics` closure→`SpawningTopicsRegistry` refactor of the live inbound
+path, token-guarded at all 4 callsites) and Piece 2 (the verifier constructed dev-gated,
+triggered by `sessionReaped`, a conservative fail-safe probe, a 15s tick, NORMAL
+attention surfacing, and `guardRegistry` registration). The probe is deliberately
+CONSERVATIVE: a live session ⇒ reachable; a topic stuck-spawning past `stuckSpawnMs` ⇒
+orphan; ANYTHING ELSE ⇒ reachable (the next inbound self-heals) — so it never
+false-orphans an idle kill. The multi-machine released-no-placement + at-capacity orphan
+cases (placement reads) and a dedicated `/topic-reachability` route are a tracked
+follow-up; their absence means LESS coverage, never a false orphan (the probe fails safe
+to reachable). <!-- tracked: topic-28744 F7-followup multimachine-probe-and-route -->
+
+## What this commit adds
+
+- `SpawningTopicsRegistry` (src/core) — token-tagged replacement for the closure-local
+  `spawningTopics` Set: `add` returns a token, `clear` is token-guarded (the ABA fix so a
+  late `.finally` from a superseded spawn cannot delete a newer entry), `stuckSinceMs`
+  exposes in-flight age for the verifier. NO timeout, NO sweep — the `.finally` remains
+  the sole clearer (round-2 proved any external clear relocates the double-spawn race).
+- `TopicReachabilityVerifier` (src/monitoring) — the PURE-SIGNAL decision core: grace +
+  per-topic coalescing, the reachable-honesty guard (a topic that will self-heal on next
+  inbound is REACHABLE, not orphaned), NORMAL-priority surfacing with per-topic
+  exponential backoff (flap cap), burst roll-up, pressure-skip + emergency-stop-suppress
+  WITH a re-sweep on clear (no never-surfaced orphan). It MUTATES NOTHING.
+
+Neither component is wired into the running server yet (no runtime surface), so this
+commit is inert at runtime — pure library code under test.
+
+## The 8 questions (for the components as committed)
+
+1. **Over-block** — N/A. The verifier blocks nothing; it surfaces a signal. The registry
+   only guards double-spawn (existing behavior), now ABA-safe.
+2. **Under-block** — N/A.
+3. **Level-of-abstraction fit** — Correct. Pure decision logic separated from the server
+   wiring + live-state probe (the spec's design).
+4. **Signal vs authority** — The verifier is a pure signal (zero mutation). The registry's
+   only authority is the EXISTING token-guarded clear (no new clearer). Complies.
+5. **Interactions** — None at runtime (unwired). The registry, once wired, replaces the
+   closure Set; the token guard makes its clear idempotent/ABA-safe.
+6. **External surfaces** — None yet (unwired). The future wiring adds a NORMAL attention
+   item + a `/topic-reachability` status route + a `/guards` entry.
+7. **Multi-machine** — The verifier's released-no-placement detection (future probe) is
+   machine-local (reads the local placement snapshot, freshness-gated); machine-local BY
+   DESIGN. The components themselves hold no cross-machine state.
+8. **Rollback cost** — Trivial. Delete two new files + their tests; nothing references
+   them at runtime yet.
+
+## Tests
+
+- `spawningTopicsRegistry.test.ts` (5): the ABA token-guard, `.finally` is the sole
+  clearer (no timeout/sweep), `stuckSinceMs`, entries snapshot.
+- `topicReachabilityVerifier.test.ts` (8): grace; reachable-honesty (no false orphan);
+  orphan→one NORMAL item; pressure-skip+re-sweep; halt-suppress+re-sweep; flap backoff;
+  burst roll-up; coalescing.
+- `tsc --noEmit` clean.
+
+## Rollback
+
+Delete the two component files + tests. No runtime reference.

package/upgrades/1.3.676.md

@@ -1,45 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: patch -->
-
-## What Changed
-
-The host spawn cap (the fork-bomb/OOM safety floor that bounds how many LLM
-subprocesses run at once) now reserves a little headroom for the user's reply. Under
-load, the user-facing tone gate used to wait in the same undifferentiated line as
-background sentinels and could time out (a cause of the 2026-06-25 silent-outbound
-incident). The cap now SUBDIVIDES into a small interactive reserve + a small background
-reserve, so a synchronous operator reply always has slots and is never starved by
-background chatter. The total cap is NEVER raised — only *who gets which slot* changes.
-Ships dark on the fleet / live on a development agent (dev-agent gate); byte-identical
-to today when off.
-
-## What to Tell Your User
-
-When the machine is busy, your reply's safety check now jumps to a reserved slot instead
-of waiting behind background work — fewer slow/held replies under load. The crash
-protection is exactly as strong as before. Most setups see no change (it's off on the
-fleet for now).
-
-## Summary of New Capabilities
-
-- `attribution.lane:'interactive'` requests reserved headroom — honored ONLY for an
-  allowlisted, user-blocking seam (the operator-facing tone gate); everything else stays
-  background.
-- Symmetric reservation within the existing cap N (`Ri`/`Rb`, default 2/2): interactive
-  guaranteed ≥Ri slots, background guaranteed ≥Rb — neither starves the other.
-- `/spawn-limiter` reports per-lane live counts + the reservation config.
-- Off (the fleet default) ⇒ byte-identical to the all-or-nothing cap (no `lane` written).
-
-## Evidence
-
-- `hostSpawnSemaphore-priority.test.ts` (10): symmetric reserve, OOM floor unconditional,
-  garbage-lane→background-never-dropped, clamp (N=1/N=2/oversized/0), off=byte-identical.
-- `spawn-cap-provider-lane.test.ts` (7): allowlist downgrade (CoherenceReviewer→background),
-  off→background, interactive fast-path, saturated interactive still fails closed,
-  membership pinned.
-- 25 existing spawn-cap tests + 160 tone-gate tests pass unchanged (no regression; the
-  fork-bomb burst-invariant test still green). `tsc --noEmit` clean.
-- Side-effects: `upgrades/side-effects/spawn-cap-interactive-priority.md`.
-- Spec (converged + approved): `docs/specs/spawn-cap-interactive-priority.md`.