instar 1.3.457 → 1.3.459

package/upgrades/1.3.459.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added Slice 3 (final layer) of the dev-agent dark-gate conformance guard: the
+GrowthMilestoneAnalyst gains rule **R6 (dev-gate conformance)**. On a development
+agent, every registered dev-gated feature (the Slice-2 `DEV_GATED_FEATURES`
+registry) must resolve LIVE; one observed DARK is surfaced as a proactive
+growth-analyst finding ("dev-gated feature X is dark on this dev agent — likely a
+hardcoded enabled:false default or an operator override"). This catches the
+forgot-the-gate-entirely / misconfig class that the Slice-1 lint can't see and
+the Slice-2 default-test only catches at the default level — and it catches it on
+the live config of the very dev agent it affects.
+
+## What to Tell Your User
+
+Nothing requiring action. On a development agent the growth digest may now include
+a "dev-gated feature X is dark" finding if a feature is misconfigured — that is the
+guard working. No fleet-facing change (dark for the fleet, live on dev agents).
+
+## Summary of New Capabilities
+
+- GrowthMilestoneAnalyst rule R6 (`devGateConformance`, default on) + `liveConfig`
+  dep + `devGateDark` digest count.
+- Completes the dev-gate guard (lint → default-test → runtime cross-check) —
+  CMT-1253. <!-- tracked: CMT-1253 -->
+
+## Evidence
+
+R6 is a preventive/observability layer, so "evidence" is a both-sides demonstration:
+- **Catches the regression:** on a `developmentAgent: true` config with a
+  registered feature's flag forced `false`, `computeFindings()` emits an R6
+  finding for that feature and `buildDigest().counts.devGateDark > 0` (test:
+  `growth-analyst-devgate-r6.test.ts`).
+- **Stays quiet otherwise:** all-live-on-dev → no R6; fleet agent (even with a
+  feature forced dark) → no R6 (fleet darkness is expected); `liveConfig` absent →
+  skipped; `devGateConformance` rule disabled → skipped.
+- **No regression to existing rules:** the 42 existing GrowthMilestoneAnalyst /
+  routes / gate-wiring tests stay green (R6 is inert without `liveConfig`).

package/upgrades/side-effects/dev-gate-conformance-r6.md

@@ -0,0 +1,73 @@
+# Side-Effects Review — Dev-Gate Conformance Cross-Check (Slice 3, GrowthMilestoneAnalyst R6)
+
+**Change:** Slice 3 of DEV-AGENT-DARK-GATE-CONFORMANCE-SPEC (converged + approved).
+The layer that catches the forgot-the-gate-entirely / misconfig class: on a
+development agent, every registered dev-gated feature (Slice 2's
+`DEV_GATED_FEATURES`) MUST resolve LIVE — one observed DARK is surfaced as a
+proactive growth-analyst finding on the very agent it affects.
+
+- `src/monitoring/GrowthMilestoneAnalyst.ts` — new rule **R6 (devGateConformance)**:
+  `computeDevGateConformanceFindings()` iterates the registry, resolves each via
+  `resolveDevAgentGate(getConfigByPath(liveConfig, path), liveConfig)`, and emits a
+  finding for any that resolve DARK on a dev agent. New `liveConfig?` dep, new
+  `devGateDark` digest count, new `rules.devGateConformance` flag (default on),
+  R6 wired into `computeFindings` + `buildDigest` + `activeSummary`.
+- `src/server/AgentServer.ts` — feeds `liveConfig: options.config` into the analyst.
+- `tests/unit/growth-analyst-devgate-r6.test.ts` — both sides of the R6 boundary.
+
+**Implementation-locus note (deviation from the spec's prose, documented honestly):**
+the spec's Slice 3 said "Extend FeatureRolloutReconciler … surfaces as a
+growth-analyst finding." I implemented the cross-check **in the GrowthMilestoneAnalyst
+itself** (rule R6), not in FeatureRolloutReconciler, because (a) the analyst is the
+finding/digest surface the spec's outcome names, (b) it is itself dev-gated-LIVE so
+it runs on the affected dev agent, and (c) it already consumes the registry pattern.
+Same outcome (a growth-analyst finding), cleaner locus. The reconciler was not
+modified.
+
+## 1. Over-block — what legitimate inputs does this reject?
+R6 is observe-only — it emits a *finding* (signal), never blocks or mutates. A
+false positive would be a feature that is *intentionally* dark on a dev agent but
+sits in the registry; that is prevented by Slice 2's curation (mcpProcessReaper /
+resourceLedger are excluded). Adding a non-conforming feature to the registry is
+the only way to mis-flag, and that is a deliberate, reviewed act.
+
+## 2. Under-block — what does it still miss?
+A dev-gated feature never added to the registry is invisible to R6 (same registry
+dependency as Slice 2). And R6 only runs on a dev agent (`developmentAgent === true`)
+with `liveConfig` present — on the fleet it is silent by design (fleet darkness is
+expected). These are the intended bounds.
+
+## 3. Level-of-abstraction fit
+Right layer: the analyst already computes findings from sensors; R6 is one more
+read-only rule over the live config + the registry. No new subsystem.
+
+## 4. Signal vs authority
+SIGNAL only. R6 produces a digest finding (the analyst never sends/blocks — it
+COMPUTES findings exposed via read routes). It holds no authority over runtime.
+
+## 5. Interactions — shadowing, double-fire, races?
+None. Pure computation over injected `liveConfig` + the static registry. Wrapped
+in try/catch per feature (a bad path routes to `onError`, never throws). Other
+rules (R1–R5) are untouched; R6 is additive in `computeFindings`/`buildDigest`.
+
+## 6. External surfaces
+The existing `/growth/digest` + `/growth/status` routes now may include R6
+findings + a `devGateDark` count — additive fields, no breaking change. Dark for
+the fleet, live on dev agents (the analyst's own gate). No agent-installed files,
+no Migration Parity entry.
+
+## 7. Rollback cost
+Low — revert the analyst R6 additions + the one AgentServer line + the test.
+Behavior reverts to R1–R5 only; no state, no deployed artifact.
+
+## No deferrals
+This is the final slice of the initiative (CMT-1253). With Slices 1–3 shipped, the
+dev-gate guard spans: lint (drift) → registry+default test (hardcoded default) →
+R6 runtime cross-check (forgot-the-gate / misconfig on a live dev agent). <!-- tracked: CMT-1253 -->
+
+## Second-pass review (independent)
+Verified: R6 default-on but inert without `liveConfig` (42 existing analyst tests
+unchanged green); both sides covered (hardcoded-dark on dev → finding; all-live on
+dev → none; fleet → none; absent config → skip; rule-disabled → skip; digest count
++ calm-break asserted). tsc clean; the Slice-1 dark-gate lint stays clean (R6 reads
+the gate via the funnel, hardcodes nothing).

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.