instar 1.3.729 → 1.3.730

package/upgrades/1.3.730.md

@@ -0,0 +1,112 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+The proactive subscription-account swap could thrash: on 2026-07-02 one dev
+agent executed 36 proactive swaps in 8 waves, round-tripping the same sessions
+between the same hot accounts and repeatedly killing six parallel build
+subagents mid-task — the continuity mechanism became the primary source of
+work destruction. Per `docs/specs/swap-continuity-antithrash.md` (converged
+round 6, approved), two composable pieces now bind at the swap chokepoints:
+
+**Piece 1 — anti-thrash brakes** at the proactive DECISION chokepoint
+(`ProactiveSwapMonitor`), engine `SwapAntiThrashEngine`:
+
+- **All-hot brake**: a proactive swap is REFUSED unless at least one eligible
+  target measures under the target ceiling (threshold − headroom, default
+  65%). When every account is hot, staying put wins — one reactive rescue
+  strictly dominates N pointless kills.
+- **Per-session dwell** (default 45 min): a just-swapped session is not moved
+  again, restart-safe via the new durable decision ledger
+  (`state/swap-ledger.jsonl`, single writer `SwapLedger`, O(1) segment
+  rotation).
+- **Target-materially-better**: a validity gate (quota reading PRESENT and
+  FRESH — an unmeasured account is never "0% cool", it counts toward all-hot)
+  plus absolute ceiling plus a 15-point improvement floor, in a normative
+  filter→score→verify order; the checked target IS the executed target
+  (`onQuotaPressure` gains an explicit-target funnel contract that
+  revalidates, never re-selects — closing the double-threshold seam).
+- **Two-tier thrash breaker** (T1 inversion / T2 rotation frequency) with
+  episode continuation, restart-proof derivation from the ledger, and ONE
+  deduped attention item per episode; execution failures write `failed` rows
+  with per-session backoff + streak escalation (the previously-silent
+  discarded reactive result promise is now observed).
+- Untagged sessions leave the proactive candidate set entirely (a background
+  optimizer must never mutate the default-slot binding). The REACTIVE
+  continuity guarantee is untouched (I6) — a genuinely walled session still
+  swaps, breaker/dwell notwithstanding.
+
+**Piece 2 — the in-flight work gate** (`SwapWorkGate`) at the
+`SessionRefresh.refreshSession` funnel, the primitive every session-killing
+mutation flows through:
+
+- A tri-state work probe (`SessionManager.checkSessionWorkState` — pane
+  footer + child-process legs, async + coalesced, one shared `ps` snapshot
+  per ~2s TTL) plus the subagent leg (`SubagentTracker`); uncertainty
+  resolves BUSY for optimization callers (I7; an id-less session is exiled,
+  never blindly killed).
+- Caller classes: `proactive-swap` DEFERS (retried each tick through the full
+  brake pipeline, dropped at a 30-min ceiling — the wall wins);
+  `reactive-swap` gets a bounded grace (default 120 s, proceeds at the first
+  not-busy observation) then proceeds WITH the F3 mitigations (enumerated
+  killed subagents + the last unanswered inbound re-injected as a quoted-data
+  envelope); `interactive-refresh` (the default for every unlisted caller)
+  gets a structured refusal; `recovery` is exempt.
+- `POST /sessions/refresh` answers busy PRE-202 with HTTP 409
+  `session-busy` (counts and ages only) and gains optional `force: true` —
+  force overrides ONLY the work gate, never the rate guard, and is recorded
+  bearer-level in the ledger.
+- The model-swap idle check gains a SUBAGENT leg behind its own micro-flag
+  (`models.tierEscalation.subagentIdleLeg`, concrete default false — dark;
+  graduates on its own rung).
+
+Observability: `GET /subscription-pool/proactive-swap` grows additive
+`brakes`/`deferrals` blocks (refusal counters, breaker state, ledger
+writability, hydration honesty); both pieces register in the guard manifest.
+
+Rollout: antiThrash resolves `enabled:true, dryRun:true` when absent (dry-run
+ledger rows only — decision behavior stays byte-identical to v1.3.722 until a
+deliberate `dryRun:false`); `swapContinuity` ships with the enabled key
+OMITTED (dev-agent gate: live-in-dry-run on a development agent, dark on the
+fleet) and is registered in `DEV_GATED_FEATURES`. Rollback:
+`antiThrash.dryRun:true` restores legacy decisions; removing the dev agent's
+swapContinuity enablement un-wires the gate entirely.
+
+## What to Tell Your User
+
+<!-- audience: agent-only, maturity: experimental -->
+- **My account-switching can no longer destroy my own work (experimental,
+  dark)**: when I juggle several subscription accounts, I used to sometimes
+  bounce conversations back and forth between two nearly-full accounts —
+  every bounce restarted the session and killed helpers working in the
+  background. Now the switcher has brakes: if every account is nearly full I
+  stay put, a just-moved conversation rests before it can move again, and a
+  move only happens when the destination is genuinely much cooler. Separately,
+  a switch will wait for in-flight work to finish instead of cutting it down
+  mid-task — and on the rare forced switch, the resumed conversation is told
+  exactly which helpers were interrupted and which message still needs an
+  answer. Nothing changes on your setup yet — the brakes observe first, and
+  the work protection ships dark until it has soaked.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Anti-thrash brakes on the proactive account swap (dry-run soak by default) | `subscriptionPool.proactiveSwap.antiThrash` in `.instar/config.json` (absent block = enabled + dry-run); live only at a deliberate `dryRun: false` |
+| Durable swap-decision ledger | `state/swap-ledger.jsonl` (single writer; restart-safe dwell/breaker state) |
+| Brake/deferral observability | `GET /subscription-pool/proactive-swap` → additive `brakes` / `deferrals` blocks |
+| In-flight work gate on session-killing mutations (dev-gated dark, dry-run first) | `subscriptionPool.swapContinuity` (enabled omitted → live on dev agents, dark on fleet); restart-required |
+| Pre-202 busy refusal + force on refresh | `POST /sessions/refresh` → 409 `session-busy` when busy; re-issue with `force: true` to override the gate (never the rate guard) |
+| Model-swap subagent idle leg (dark micro-flag) | `models.tierEscalation.subagentIdleLeg: true` (default false; own rollout rung) |
+
+## Evidence
+
+- Spec: `docs/specs/swap-continuity-antithrash.md` (converged round 6 — 0
+  CRITICAL / 0 MAJOR; approved under standing Session-A preapproval, topic
+  29836). Plain-English companion: `docs/specs/swap-continuity-antithrash.eli16.md`.
+- Incident data: `logs/server.log` (echo dev agent, v1.3.722, 2026-07-02 —
+  36 executed proactive swaps / 72 account-swap lines / 8 waves).
+- Side-effects review: `upgrades/side-effects/swap-continuity-antithrash.md`.

package/upgrades/side-effects/swap-continuity-antithrash.md

@@ -0,0 +1,118 @@
+# Side-Effects Review — swap-continuity anti-thrash brakes + in-flight work deferral
+
+Spec: `docs/specs/swap-continuity-antithrash.md` (converged round 6, approved).
+Roadmap: Session A item 4.4 + operator-priority thrash brake (2026-07-02 incident).
+
+## What changes at runtime
+
+1. **New durable state file**: `state/swap-ledger.jsonl` (single writer:
+   `SwapLedger`; O(1) segment rotation, 10 MB × keep 2). Absence = cold start
+   (dwell un-primed for the first 45 min — the §9 accepted one-time gap).
+2. **Proactive swap decisions** (only when `subscriptionPool.proactiveSwap.enabled`
+   is already opted into — fleet-dark today):
+   - antiThrash resolves `enabled:true, dryRun:true` when the block is absent →
+     the ONLY immediate effect on an opted-in install is dry-run ledger rows +
+     status counters (rung-1 honesty, §10). Decision behavior stays
+     byte-identical to v1.3.722 until a deliberate `dryRun:false`.
+   - Live (`dryRun:false`): untagged sessions leave the proactive candidate set
+     (I10); refusals (all-hot / dwell / no-material-target / target-unmeasured /
+     reversal / thrash-breaker / ledger-lost) bind; the executed target is the
+     brake-checked target (I1) with execute-time revalidation.
+3. **Reactive path**: decision behavior byte-identical (I6). Additive
+   observation only — reactive swaps write ledger rows; execution failures
+   (previously a silently-discarded promise) write `failed` rows and can raise
+   ONE deduped attention item per streak/hop-cascade/rate-cap-strand.
+4. **Session-killing mutations** (`SessionRefresh.refreshSession`): a work gate
+   consults in-flight state when `swapContinuity` resolves live (dev-agent gate
+   — key OMITTED from shipped config, dark on fleet). Caller classes:
+   proactive-swap defers; reactive-swap gets a bounded grace (≤120 s) then
+   proceeds WITH mitigations; interactive-refresh (the default for every
+   unlisted caller) gets a structured `session-busy` refusal + `force`;
+   recovery is exempt. Forced kills carry the F3 mitigation payload
+   (enumerated killed subagents + re-injected unanswered inbound, quoted-data
+   envelope).
+5. **HTTP surface**: `/subscription-pool/proactive-swap` gains additive
+   `brakes`/`deferrals` blocks; `/sessions/refresh` gains a pre-202 409
+   `session-busy` refusal + optional `force:true` (bearer-level, recorded as
+   such). No route renamed; nothing 503s that didn't.
+6. **Attention items**: one per thrash episode / failure streak /
+   measurement-blind episode / ledger-loss episode — episode-deduped (P17),
+   restart-proof via episodeId derivation from the ledger.
+
+## Failure directions (the load-bearing ones)
+
+- Ledger UNWRITABLE ⇒ proactive optimization PAUSES (`ledger-lost`,
+  counter-only), level-triggered resume + one `outage-summary` row; reactive
+  untouched (I12).
+- Quota reading ABSENT/STALE ⇒ NOT under the ceiling; counts toward all-hot;
+  never treated as 0% (bound 0, R4-M1). Whole-pool blindness pauses the
+  optimizer AND says so (I13).
+- Work-gate uncertainty ⇒ BUSY for optimization callers ('absent' behaves like
+  'indeterminate', R5-M1), busy-for-grace for reactive (never strands — the
+  grace deadline always proceeds).
+
+## Rollback levers
+
+- `antiThrash.dryRun:true` restores v1.3.722 decision behavior (keeps
+  observability). `antiThrash.enabled:false` disables the engine's binding
+  entirely (legacy path incl. legacy 10-min cooldown).
+- Removing the dev agent's `swapContinuity` enablement un-wires the gate
+  (SessionRefresh reverts to unconditional kill). `subagentIdleLeg` stays a
+  concrete `false` default on the model-swap block (rung 3a flip only).
+- Deleting `state/swap-ledger.jsonl` = cold start (bounded, logged, §9).
+
+## Blast radius
+
+Machine-local by design (§8): per-machine ledger, per-machine breaker, no
+cross-machine state. No egress, no spend, no credential surface. The only
+processes touched are the agent's own tmux sessions, and only through the
+pre-existing SessionRefresh funnel with strictly ADDED protection.
+
+## Wiring completion (second commit of this build)
+
+The core modules landed first (2866f1073); the wiring commit binds them:
+server.ts spine (unconditional ledger+engine hydration, live-knob getters,
+scheduler/monitor/SessionRefresh hooks), the SessionManager tri-state work
+probe (shared ps snapshot), the /sessions/refresh pre-202 409 + force,
+the AgentServer ModelSwapService subagent-leg probe (Q5 dark micro-flag),
+DEV_GATED_FEATURES + guard-manifest registration, CLAUDE.md template +
+PostUpdateMigrator awareness, and the release-note fragment. No new runtime
+side effects beyond those reviewed above — this section records that the
+dark/dry-run posture described above is now actually reachable end-to-end.
+
+## CI-green follow-up (third commit of this build)
+
+Scope: zero-runtime-behavior commit that turns the two red unit shards green.
+(1) Two pre-existing tests asserted the PRE-brake `/sessions/refresh` call
+shape (`refreshSession({ sessionName, followUpPrompt, reason, fresh })` and
+the exact-args spy without `force`); both now assert the documented §4.5
+shape (fresh forwarded, `force` pinned to a strict boolean, default false).
+(2) The no-silent-fallbacks ratchet counted 503 vs baseline 491: a
+base-vs-HEAD set-diff of the exact test heuristic showed the PR added 13
+genuinely-new flagged catches (every other +entry is a symmetric line-shift
+artifact — 59/59 commands/server.ts, 31/31 AgentServer.ts, 19/19 routes.ts,
+7/7 SessionManager.ts, 5/5 PostUpdateMigrator.ts). All 13 are the feature's
+DESIGNED fail-safes, each failing toward the safe direction: SwapWorkGate
+probe legs → indeterminate reads BUSY (I7, defer — never a wrong kill);
+SessionRefresh work-gate knob/probe/mitigation arms → gate-dark or refusal
+(the gate is ADDITIVE, §4.5 — a broken gate must never block a refresh, and
+mitigations never gate the respawn); ProactiveSwapMonitor safe-knob reads →
+feature-dark (legacy behavior holds); SwapLedger append/hydrate → loud warn
++ I12 optimization pause + counted loss classes (R4-m1), partial hydration
+surfaced via coveredWindow/corrupt. Each now carries an in-brace
+`@silent-fallback-ok` justification; the heuristic count returns to 490
+(≤ 491 baseline) — no baseline bump.
+
+Side-effects review of THIS commit: over-block — none (comments + test
+expectations only; no input is newly rejected). Under-block — none (no
+detector logic changed). Abstraction fit — the tags are the ratchet's
+designed exemption mechanism for reviewed fail-safes. Signal-vs-authority —
+no authority added; the tagged catches remain signal-preserving fail-safes
+(refusals/warns/counters are the loud surfaces). Interactions — none; the
+tags are inert at runtime. External surfaces — none. Multi-machine — n/a
+(no behavior change; feature posture unchanged, machine-local by design §8).
+Rollback — revert the commit; nothing durable depends on it. Second-pass —
+not required: although the touched files include gate/monitor modules, the
+source diff is comment-only (verified: `git diff` shows no executable-line
+changes in src/ beyond comment insertion) and the test diff asserts the
+already-reviewed §4.5 behavior.