instar 1.3.330 → 1.3.332

package/upgrades/1.3.332.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Audit fix #3 under "No Unbounded Loops" (P19, Eternal Sentinel condition 4):
+the live-tail flusher's capped backoff (#867) correctly retries a failing topic
+forever, but a topic whose standby copy went stale never said so. Now a
+per-topic episode latch (the `SlowRetrySentinelEscalation` shape) fires once
+per outage when flushes have failed ≥30min: one log line + one
+`DegradationReporter` record (`LiveTail.standbyFreshness`, topic NAME included,
+housekeeping channel — the reporter's per-feature 1h cooldown bounds even an
+all-topics-stale storm to a single alert). Success clears the episode. The
+`reportStaleStandby` dep is optional — omitted, behavior is byte-identical.
+
+## What to Tell Your User
+
+Only relevant if I run on more than one machine: when the standby machine's
+copy of a conversation falls behind for over half an hour (because syncs to it
+keep failing), that fact is now recorded in my health/degradation log instead
+of being invisible. Nothing pings you — but if a machine takeover ever resumes
+a conversation from an older point, there's now a checkable record explaining
+exactly which conversation was behind and since when.
+
+## Summary of New Capabilities
+
+- Stale-standby visibility: one degradation record per conversation per outage
+  when cross-machine sync has been failing ≥30min (`LiveTail.standbyFreshness`
+  in the degradation log / Process Health surfaces); retries continue
+  unchanged. No configuration needed.
+
+## Evidence
+
+Gap noted by #867's own second-pass reviewer ("backoff but no breaker") and
+resolved per the ratified Eternal Sentinel clause: persistence kept, silence
+removed. Focused adversarial second-pass: CONCUR (episode timing, firing bound
+= threshold + one backoff window, recordNoNewContent edge traced safe,
+DegradationReporter flood analysis). Tests: 21 green in LiveTailSource.test.ts
+incl. the P19 sustained-failure bound (~100 failing windows → exactly 1
+signal) and the server.ts wiring pin; tsc clean.

package/upgrades/side-effects/livetail-stale-signal.md

@@ -0,0 +1,43 @@
+# Side-Effects Review — Live-Tail Stale-Standby Signal
+
+**Version / slug:** `livetail-stale-signal`
+**Date:** `2026-06-06`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `focused adversarial reviewer subagent — CONCUR (all four novel-integration probes clean; the episode-latch pattern itself carries two same-night CONCUR reviews)`
+
+## Summary of the change
+
+`LiveTailSource` gains the Eternal Sentinel's condition-4 observability for its capped-backoff retry loop: per-topic `failingSince` episode stamp + episode-keyed one-shot latch; the first attempt at/after `staleSignalAfterMs` (default 30min) logs once and calls the optional `reportStaleStandby` dep once per episode; success clears both. `server.ts` wires the dep to `DegradationReporter` (`LiveTail.standbyFreshness`, topic name resolved). Files: `LiveTailSource.ts`, one wiring block in `server.ts`, tests.
+
+## Decision-point inventory
+
+- `LiveTailSource` failure branch — **modify (additive)** — adds episode accounting + one-shot signal; backoff, retry, delta, and seq semantics untouched.
+- `server.ts` LiveTailSource construction — **modify** — wires the reporter dep.
+
+## 1. Over-block / 2. Under-block
+
+Nothing blocked — pure signal. Detection bound: threshold + one backoff window (≤5min at cap; reviewer-confirmed attempts always resume when the window opens). Known pre-existing edge (traced by reviewer, probe 3): content reverted to exactly-streamed state while failures>0 keeps rebuilding content per tick (version gate stays bypassed) — a #867-era micro-inefficiency in a bizarre edge, unchanged here; `failingSince` persisting there is correct (success remains the only exit). Remaining audit targets <!-- tracked: CMT-1109 -->.
+
+## 3. Level-of-abstraction fit / 4. Signal vs authority
+
+The latch lives in the loop it observes (third use of the established suppressor shape tonight); delivery rides the standard degradation channel — deliberately NOT the attention queue or Telegram (a stale standby copy is operator-relevant housekeeping, not a user decision). **Signal-only** per `docs/signal-vs-authority.md`: the dep can only record; removing it restores byte-identical behavior (test-pinned).
+
+## 5. Interactions
+
+- **Concurrency:** flushAll is sequential; all map mutations are post-await synchronous code — no double-stamp path (reviewer probe 1).
+- **Flood:** all topics share ONE reporter feature key with a 1h alert cooldown — N simultaneously-stale topics ⇒ at most one user-facing alert; per-topic records remain for inspection (reviewer probe 4). Bounded Notification Surface: no topic creation, no per-element pings.
+- **Handoff force path:** shares failure accounting — a forced attempt's failure correctly extends the episode.
+
+## 6. External surfaces / 7. Rollback
+
+Logs + degradation records only; no API/schema/config/persistent state (defaults in code; dep optional). Rollback = revert; only the silence returns.
+
+## Conclusion
+
+Third and final observability fix in tonight's P19 series: the reaper loop got its back-off (#863), the supervisor healer got its voice (#871), the lease wire got its brakes (#874), and now the live-tail's sanctioned forever-retry can no longer go quietly stale. Persistence everywhere, silence nowhere.
+
+---
+
+## Phase 5 — Second-pass review (cross-machine continuity → performed)
+
+The episode-keyed one-shot latch pattern carries two same-night line-level CONCUR reviews (supervisor escalation; mesh brakes). A focused adversarial pass probed only this PR's novel integration points: (1) episode-stamp timing across the awaited broadcast + same-topic concurrency — no double-stamp (sequential flushAll, single-threaded post-await mutations); (2) firing bound under backoff gating — threshold + ≤1 backoff window, and no stuck-in-backoff-without-attempts path exists; (3) the `recordNoNewContent`-while-failing edge — traced: cannot fire spuriously, cannot wedge, success is the only episode exit; (4) DegradationReporter flood analysis — per-feature 1h cooldown caps user-facing volume at one alert regardless of topic count. Ran the 21-test suite + tsc — green/clean. **Verdict: CONCUR.**

package/upgrades/side-effects/provider-substrate-live-wiring.md

@@ -0,0 +1,145 @@
+# Side-Effects Review — Provider-Substrate Live Wiring (June-15 readiness PR 1)
+
+**Version / slug:** `provider-substrate-live-wiring`
+**Date:** `2026-06-05`
+**Author:** `echo (Claude Opus)`
+**Second-pass reviewer:** `5-agent verification panel (build Phase 3, LARGE)`
+
+## Summary of the change
+
+Wires the already-built provider substrate into production: registers both
+Anthropic adapters with the providers registry at server boot (gated,
+idempotent, lazy), plumbs a real TTL-cached SDK-credit reader into the
+CostAwareRoutingPolicy (replacing the `() => null` stub), and adds an
+opt-in `intelligence.subscriptionPath` mode (`off`/`auto`/`force`) that
+routes the internal-intelligence funnel between `claude -p` (SDK-credit
+path) and the interactive REPL pool (subscription floor) per spec 04
+Rule 1. Files: `src/providers/bootRegistration.ts` (new),
+`src/core/InteractivePoolIntelligenceProvider.ts` (new),
+`src/core/AnthropicSubscriptionRouter.ts` (new),
+`src/providers/costAwareRouting.ts` (decision extracted to shared pure fn),
+`src/providers/adapters/anthropic-interactive-pool/{config,pool}.ts`
+(model knob), `src/core/intelligenceProviderFactory.ts` (option),
+`src/core/types.ts` (config type), `src/commands/server.ts` (boot+shutdown
+wiring), `src/server/routes.ts` (GET /providers/registry).
+
+## Decision-point inventory
+
+- `registerAnthropicAdapters` gates (claudeForbidden, enabledFrameworks) — add — refuse Claude adapters on codex-only agents
+- `decideSdkVsSubscription` (extracted) — modify (refactor, semantics identical, existing tests pass) — SDK-pot vs subscription threshold
+- `AnthropicSubscriptionRouter.evaluate` mode branch — add — off/auto/force routing of internal LLM calls
+- `buildIntelligenceProvider` claude-code case — modify — wraps with router ONLY when the new option is passed; otherwise byte-identical
+- shutdown pool dispose — add — kills pool tmux sessions at server stop
+- `GET /providers/registry` — add — read-only introspection
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+In `force` mode, a pool outage (tmux missing, spawn failure) makes internal
+LLM calls fail even though `claude -p` would have worked — by design (force
+mode's contract is zero `claude -p` traffic), and loudly. Fleet default is
+`off`, so nobody is exposed without an explicit flip. The codex-only gate
+refuses registration on codex-only agents — correct, mirrors the existing
+ClaudeCliIntelligenceProvider guard. No other block/allow surface.
+
+## 2. Under-block
+
+**What should be rejected but passes?**
+
+`auto` mode falls back across paths on ANY primary error, including
+prompt-shaped errors (e.g. timeout from an oversized prompt) where the
+retry will likely fail again — one wasted call, bounded (exactly one
+fallback attempt, then a loud throw). The pool's `--dangerously-skip-
+permissions` spawn means a prompt-injected judgment call could in principle
+invoke tools inside the pool session; mitigated by the empty scratch
+workdir and unchanged from the adapter's prototyped+parity-tested shape;
+hardening is tracked in the spec (CMT-1105).
+
+## 3. Level-of-abstraction fit
+
+Registration lives in `src/providers/` (substrate layer), the two
+IntelligenceProvider implementations in `src/core/` next to their peers,
+and the mode wiring at the composition root (server.ts) — matching the
+existing layering (IntelligenceRouter precedent). The threshold logic was
+EXTRACTED to one shared pure function rather than duplicated across the
+two routing layers.
+
+## 4. Signal vs authority compliance
+
+The router treats config (`mode`) as authority and credit snapshots as
+signal: unknown signal degrades conservatively (subscription floor), never
+blocks the call path. onRoute/onDegrade are observability taps with no
+authority. No LLM judgment gates any decision here — all routing is
+deterministic from config + credit state.
+
+## 5. Interactions
+
+- **Circuit breaker**: router sits INSIDE the breaker wrap — a rate-limit
+  on the surviving path still trips the account-global breaker. Unchanged
+  for mode off.
+- **Per-component IntelligenceRouter**: claude-code builds inherit the same
+  subscriptionPath option, so codex-default agents with claude-routed
+  components stay consistent.
+- **/metrics/features**: pool-served calls still attribute calls+latency;
+  token columns read 0 (pool reports no per-call usage; onUsage is
+  deliberately not invoked with fake zeros).
+- **SessionReaper/tmux tooling**: pool sessions are named `instar-pool-*`;
+  they are adapter-managed (maxIdle 30m, maxMessages 50, dispose at
+  shutdown). Reaper does not manage them (they are not instar sessions in
+  the session store).
+- **QuotaTracker**: unaffected — file-based scheduler shedding stays as-is.
+
+## 6. External surfaces
+
+`GET /providers/registry` (Bearer-authed like its router peers) returns
+adapter ids + capability flag names + a policy-installed boolean. No prompt
+content, no credentials; integration test asserts no key-material shapes in
+the payload. The usage-meter call (`/api/oauth/usage`) is the EXISTING
+read-only observability exception under spec 04 Rule 2, now TTL-cached
+(60s) so routing volume cannot hammer it.
+
+## 7. Rollback cost
+
+Mode is config-gated default-off: rollback = remove the config key (or set
+`off`) + restart — no data, no state, no migration. Registration itself is
+inert without the mode (lazy pool, no spawns). Worst-case orphan: pool tmux
+sessions if the server dies UNgracefully mid-soak; bounded by poolSize
+(default 2) and visible via `tmux ls` (`instar-pool-*`).
+
+## Conclusion
+
+Ship. Default-off + pinned-argv invariance test means zero fleet behavior
+change at merge; the June-15 lever becomes a config flip backed by 44 new
+tests across all three tiers.
+
+## Second-pass review (if required)
+
+Build Phase 3 runs the 5-agent verification panel (LARGE build) before
+commit; findings folded back into code/spec before the convergence tag.
+
+## Evidence pointers
+
+- Unit: `tests/unit/providers/bootRegistration.test.ts`,
+  `tests/unit/anthropic-subscription-router.test.ts`,
+  `tests/unit/intelligence-provider-factory-subscription-path.test.ts`,
+  `tests/unit/providers/adapters/anthropic-interactive-pool/pool-model-flag.test.ts`
+- Integration: `tests/integration/providers-registry-route.test.ts`
+- E2E: `tests/e2e/provider-substrate-live-wiring.test.ts`
+- Spec: `docs/specs/provider-substrate-live-wiring.md` (+ `.eli16.md`)
+- Live exposure measurement driving the work: /metrics/features 24h on echo
+  (~1,014 real internal calls, ~26.7M tokens-in).
+
+## CI-green follow-up (same PR)
+
+- New side effect: a FAILED boot registration/policy install now emits a
+  DegradationReporter event (`serverBoot.anthropicProviderRegistration`) in
+  addition to the yellow boot log line — so a dark June-15 routing install is
+  visible in the degradation feed, not just scrollback. No behavior change on
+  the success path.
+- Silent-fallback ratchet lowered 459 → 458 (that catch is now reporter-wired);
+  two non-degradation catches carry in-brace `@silent-fallback-ok`
+  justifications (raced tmux kill-session; HTTP 500 surfaced to caller).
+- `/providers/registry` tracked in the feature-delivery-completeness guard
+  (read-surface class, like `/session/clock`; no framework shadow — the lever
+  only applies to claude-code internal traffic).