instar 1.3.456 → 1.3.458

package/upgrades/1.3.458.md

@@ -0,0 +1,62 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Adds the **proactive pre-limit swap** — the missing half of the Subscription &
+Auth Standard's continuity guarantee. A new `ProactiveSwapMonitor` moves a session
+OFF an account BEFORE it walls, at a lag-aware measured threshold (`thresholdPct`,
+default 80 — below the real limit because the polled reading trails real usage).
+Critically, it covers the session you actually use: an UNTAGGED session (the
+primary interactive session running on the default login) is resolved to its real
+account via `InUseAccountResolver`, so it is moved pre-emptively instead of wedging
+at the wall. Bounded by a per-cycle cap, per-session cooldown, an
+alternate-must-be-below-threshold anti-thrash guard, and a near-the-wall poll
+refresh. Two routes: `GET /subscription-pool/proactive-swap` (status) and
+`POST /subscription-pool/proactive-swap/check` (run one pass on demand). Gated
+OFF by default behind `subscriptionPool.proactiveSwap.enabled` (moving live
+sessions is real authority — same authority as the reactive `autoSwapOnRateLimit`,
+just an earlier trigger). Disabled → strict no-op; the routes answer
+`200 { enabled:false }`.
+
+## What to Tell Your User
+
+Your accounts now swap *before* one runs out, not just after. Before, the agent
+would ride an account all the way to its limit and then either blip onto a fresh
+account — or, if it was the main session you chat with, get stuck until you
+manually switched accounts. Now, when an account crosses ~80% of its limit, I move
+the session to one with room to spare while preserving the conversation, with
+margin to spare (your real usage runs a few points ahead of what I can poll). It's
+off by default; just tell me to turn on proactive swapping and I'll enable it, and
+you can ask me to run a check on demand to watch it work.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Proactive pre-limit swap (before the wall) | set `subscriptionPool.proactiveSwap.enabled: true` (restart to apply) |
+| Tune the trigger | `subscriptionPool.proactiveSwap.thresholdPct` (default 80), `maxSwapsPerCycle`, `cooldownMs`, `tickMs`, `watchMarginPct` |
+| See status | `GET /subscription-pool/proactive-swap` |
+| Run one pass now | `POST /subscription-pool/proactive-swap/check` |
+
+## Evidence
+
+Reproduction (live, 2026-06-09): the operator's interactive session was running
+on the default login (pointed at SageMind - Adriana). Adriana's 5-hour window
+filled; the session wedged. The reactive auto-swap could not rescue it — it only
+fires after a rate-limit escalation, AND the session carried no
+`subscriptionAccountId` (the main interactive session is untagged), so the swap
+engine had nothing to move. The operator had to swap the default login manually to
+unblock it.
+
+After the fix: the monitor resolves the untagged session's effective account from
+the default login and pre-emptively swaps it at the measured threshold. The e2e
+test (`subscription-proactive-swap-lifecycle.test.ts`) drives exactly this case
+end-to-end over HTTP — an untagged session on an at-pressure default login is
+swapped before the wall, conversation preserved. The unit suite asserts both sides
+of every boundary (at-pressure vs. below, tagged vs. untagged-via-default,
+alternate-exists vs. anti-thrash, cap, cooldown, recency ordering, watch-zone poll
+refresh). tsc + lint clean; sibling subscription/quota suites and all 358
+PostUpdateMigrator tests green.

package/upgrades/side-effects/dev-gated-features-registry.md

@@ -0,0 +1,70 @@
+# Side-Effects Review — Dev-Gated-Feature Registry + Both-Sides Wiring Test (Slice 2)
+
+**Change:** Slice 2 of DEV-AGENT-DARK-GATE-CONFORMANCE-SPEC (the converged +
+operator-approved spec). Adds the layer that catches a dev-gated feature wired to
+resolve **dark on a dev agent** — the gap Slice 1's lint cannot see.
+
+- `src/core/devGatedFeatures.ts` (new) — `DEV_GATED_FEATURES` registry (name +
+  config path + description) and a `getConfigByPath` reader.
+- `tests/unit/devGatedFeatures-wiring.test.ts` (new) — for each registered
+  feature, applies the REAL `getMigrationDefaults` and asserts
+  `resolveDevAgentGate(<configPath>)` is **true** under a `developmentAgent: true`
+  config and **false** under a fleet config, plus a "teeth" test confirming an
+  injected `enabled: false` default fails the live-on-dev assertion (the literal
+  #1001 mechanism).
+
+**Registry membership (the design decision in this slice):** only features whose
+intent is "dark fleet / LIVE on dev" are included (growthAnalyst, coherenceJournal,
+warmSessionA2A, secretSync, geminiLoopDriver, respawnBuildContext,
+selfKnowledgeSessionContext — verified to omit `enabled` in defaults). Deliberately
+EXCLUDED, with reasons in code: `monitoring.mcpProcessReaper` (destructive — ships
+OFF + dry-run for everyone incl. dev by design) and `monitoring.resourceLedger`
+(ledger defaults `enabled: true`; only sampling rides the gate off the same key).
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+The test asserts every registered feature is live-on-dev / dark-on-fleet. A
+feature that legitimately ships dark-everywhere or live-everywhere would fail if
+wrongly added to the registry — but membership is a deliberate, reviewed choice
+(the two non-conforming features are explicitly excluded with documented reasons),
+so the test only constrains features that genuinely follow the convention.
+
+## 2. Under-block — what failure modes does this still miss?
+Catches the hardcoded-default half of the #1001 shape (a `false` baked into the
+feature's default → `applyDefaults` injects it → live-on-dev assertion fails) for
+**registered** features. Still misses: (a) a dev-gated feature never added to the
+registry; (b) the construction-side half where a site reads `enabled === true`
+without any gate (no default to catch) — that is Slice 3's spec-intent cross-check.
+Both limits are named in the spec's layer table.
+
+## 3. Level-of-abstraction fit — right layer?
+Yes — a unit test over the real config-default assembly (`applyDefaults` +
+`getMigrationDefaults`), the same path PostUpdateMigrator uses. It exercises the
+actual default→gate resolution, not a source regex, so it catches the mechanism
+rather than a spelling.
+
+## 4. Signal vs authority compliance
+The test is CI authority (fails the build) over a deterministic, mechanical
+property — same posture as the rest of the suite. The registry is inert data; it
+holds no runtime authority (Slice 3 consumes it read-only).
+
+## 5. Interactions — shadowing, double-fire, races?
+None. `devGatedFeatures.ts` is pure data + a pure path reader; the test builds
+throwaway config objects. No shared state, no runtime wiring in this slice.
+
+## 6. External surfaces — visible to other agents/users/systems?
+None. No routes, no config, no agent-installed files. Repo-internal source + test.
+No Migration Parity entry needed.
+
+## 7. Rollback cost — back-out if wrong?
+Trivial — delete the two files. No runtime behavior, no state, no deployed artifact.
+
+## No deferrals
+Slice 3 (spec-intent cross-check) is the next slice of the same approved spec,
+tracked under CMT-1253 — not a deferral of this slice's scope. <!-- tracked: CMT-1253 -->
+
+## Second-pass review (independent)
+The registry membership was derived by auditing each `resolveDevAgentGate` site's
+default against the convention: the 7 included features verified to omit `enabled`
+(test green on all = no hidden hardcoded default); the 2 excluded features
+(mcpProcessReaper, resourceLedger) inspected and confirmed intentionally NOT
+dark-on-fleet. The teeth test confirms the guard fires on a planted regression.

package/upgrades/side-effects/proactive-prelimit-swap.md

@@ -0,0 +1,64 @@
+# Side-effects review — Proactive pre-limit account swap
+
+## Blast radius when DISABLED (default)
+
+Strict no-op. `subscriptionPool.proactiveSwap.enabled` defaults to absent/false →
+the `ProactiveSwapMonitor` is never constructed, never started, never wired into
+the AgentServer ctx. The two new routes answer `200 { enabled:false }` (never
+503). No new background loop, no polling, no session restarts. An agent that
+doesn't set the flag behaves byte-for-byte as before.
+
+## Blast radius when ENABLED
+
+- **It restarts live sessions.** A proactive swap drives the same
+  `SessionRefresh` account-swap path the reactive `autoSwapOnRateLimit` already
+  uses (kill → respawn with `--resume`, conversation preserved via the topic's
+  resume UUID). Same authority and same disruption profile as the already-shipped
+  reactive swap — only the trigger is earlier (a measured threshold vs. an actual
+  rate-limit escalation). This is why it is opt-in.
+- **It can move UNTAGGED sessions.** An untagged session's effective account is
+  resolved from the default-config login via `InUseAccountResolver` (cached
+  `claude auth status`). A wrong/blank resolution degrades to "no default
+  account" → that session is simply not a candidate (fail-safe, never a wrong
+  swap). After a swap the session becomes tagged with its new account.
+
+## Bounding / anti-footgun
+
+- `maxSwapsPerCycle` (default 3) caps restarts per pass; per-session `cooldownMs`
+  (default 10m) prevents double-swapping a session whose restart is still
+  settling; an alternate-must-be-below-threshold guard prevents moving onto a
+  nearly-full login (anti-thrash). Near the wall the monitor refreshes the poll
+  before deciding so a fast burn isn't missed.
+- Complements (never conflicts with) the reactive swap: once proactive moves a
+  session off a hot login, the reactive escalation for that login can't fire for
+  it. Both can be enabled together.
+
+## Interactions
+
+- Reads `state.listSessions({status:'running'})`, `subscriptionPool.list()`,
+  `inUseAccountResolver.resolve()`, and calls `quotaPoller.pollAll()` +
+  `quotaAwareScheduler.onQuotaPressure()` — all existing surfaces, no schema
+  changes. Adds `subscriptionAccountId`-keyed logic but writes no new state.
+- CapabilityIndex gains two endpoints + a `proactiveSwap` flag; the subscription
+  capability description is extended. No prefix added (rides `/subscription-pool`).
+
+## Migration parity
+
+New `subscriptionPool.proactiveSwap` config is purely additive (absence = off →
+no `migrateConfig` needed). CLAUDE.md awareness ships in the template AND via a
+dedicated idempotent `migrateClaudeMd` patch for existing agents (the
+section-install guard skips agents that already have the section).
+
+## Framework generality
+
+Does not touch the framework launch/inject abstraction. The pool is
+Claude-subscription-specific by nature (claude-code accounts); the monitor only
+considers `framework === 'claude-code'` (or legacy undefined) sessions, so
+codex-cli / gemini-cli / pi-cli sessions are correctly ignored.
+
+## Tests
+
+Unit (16) — both sides of every boundary incl. the untagged→default-login
+resolution; integration (6) — full HTTP for both routes incl. dark 200s; e2e (2)
+— feature-alive in dark + live. Sibling subscription/quota suites + all 358
+PostUpdateMigrator tests stay green.