instar 1.3.728 → 1.3.730

package/upgrades/1.3.729.md

@@ -0,0 +1,92 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+The multi-machine mesh ran two contradictory write models at once: the
+one-awake model flips the WHOLE StateManager read-only on every non-lease-holder
+(one process-wide boolean), while the active-active session pool deliberately
+places owned, serving sessions on those same "standby" machines. F9's sharpest
+line: a machine can be read-only ("standby") while actively OWNING pool topics —
+so its writes about sessions it owns and serves were blocked
+(`[SessionManager] Failed to record build context … StateManager is read-only`),
+and every added machine became a standby-shaped writer-that-can't-write.
+Separately, the P2-6 family showed mutating routes (`POST /evolution/actions`,
+`POST /attention`) hanging open-endedly instead of refusing.
+
+Per `docs/specs/standby-write-reconciliation.md` (review-converged round 3,
+approved), writes are now classified into a write **domain**
+(machine-local / session-scoped / topic-scoped / cluster-shared) by a single
+source of truth (`WriteDomainRegistry`) and admitted by ONE synchronous
+in-memory decision point (`WriteAdmission` — no fs/network/LLM on the admission
+path; p99 < 1ms pinned by test):
+
+- **machine-local** writes admit EVERYWHERE — even on a read-only standby (the
+  F9 fix: the per-machine build-context write is no longer blocked).
+- **session-/topic-scoped** writes admit iff THIS machine owns the record per
+  the session-pool FSM's single-owner guarantee (boot-warmed `OwnershipIndex`
+  + onCommit hook on BOTH ownership substrates); a not-owner refusal NAMES the
+  owner.
+- **cluster-shared** keeps byte-identical authority to today: holder admits,
+  standby refuses.
+- Every inadmissible write gets a **typed, machine-readable 409 refusal**
+  (`error/code/domain/scope/owner/leaseHolder/asOf/retryable` + `Retry-After`)
+  in well under 2s — never a hang; refuse-before-touch (a refused write mutates
+  nothing). The legacy read-only message string is preserved for log scraping.
+- `SessionBuildContextStore` re-keyed per machine (§3.3) with a one-time
+  lease-holder legacy-key cleanup; `FileClassifier` sync exclusions for
+  attention-items + evolution (the second convergence axis).
+- Observability: `GET /write-admission` (mode, per-domain counters, recent
+  refusals, ownership-index stats) + an event-loop-lag gauge on the AUTHED
+  `/health` extension only. Refusal storms raise exactly ONE deduped attention
+  item (burst invariant pinned by test).
+- Ships dev-gated dark (`multiMachine.writeAdmission` — enabled OMITTED →
+  resolveDevAgentGate) AND dryRun-first with a §9.14 double latch: config
+  `dryRun:false` alone grants NO refusal authority until the write-surface
+  inventory constant is flipped in code. On the fleet nothing changes; the
+  legacy blanket guard keeps enforcing until graduation. Rollback: set
+  `multiMachine.writeAdmission.enabled` to false (or leave the gate dark).
+
+## What to Tell Your User
+
+<!-- audience: agent-only, maturity: experimental -->
+- **My machines no longer block their own homework (experimental, dark)**: when
+  I run on more than one machine, a machine that isn't "in charge" used to be
+  forbidden from writing ANY of its own notes — even notes about conversations
+  it was actively serving. Now each write is checked against who actually owns
+  that piece of work: notes about this machine's own work always go through,
+  notes about work another machine owns are politely declined with a clear,
+  fast "machine X owns this, retry shortly" answer instead of hanging forever.
+  Nothing changes on your setup yet — this ships dark and observation-first,
+  and I can turn it on deliberately when it has soaked.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Ownership-scoped write admission (dev-gated dark, dryRun-first) | `multiMachine.writeAdmission` in `.instar/config.json` (enabled omitted → live on dev agents, dark on fleet) |
+| Typed 409 write refusal with Retry-After | Automatic on inadmissible writes when live; body carries code/domain/owner/leaseHolder |
+| Write-admission observability | `GET /write-admission` (Bearer; 503 when dark) |
+| Event-loop-lag gauge | Authed `GET /health` extension only |
+
+## Evidence
+
+- Root cause grounded live (2026-07-02, Laptop stderr): `[SessionManager]
+  Failed to record build context … StateManager is read-only (this machine is
+  on standby). Blocked: set` — a write about a session this machine OWNS,
+  blocked by the blanket lease boolean (F9).
+- Spec converged round 3 (0 MUST-FIX / 0 SHOULD-FIX; external gemini-2.5-pro
+  CONVERGE), approved under standing Session-A preapproval (topic 29836).
+- All three test tiers shipped and green: unit (110 tests — §3.2 verdict table
+  both sides, typed-refusal contract, ownership-index parity on BOTH
+  substrates, registry I9 story validation, StateManager one-way attach +
+  fail-toward-today, conformance ratchet + write-surface inventory baseline),
+  integration (13 tests — P2-6 family 201s on a standby-that-owns, typed 409 +
+  Retry-After through the real HTTP pipeline in <2s, refuse-before-touch store
+  snapshot, dark = 503), e2e lifecycle (8 tests — production init path,
+  live-on-dev 200 / fleet-dark 503, §9.14 double latch at the production
+  constant, F9 fix alive end-to-end, burst invariant ≤1 attention item).
+- I2 hard properties pinned by test: ZERO fs on the admission path (including
+  negative lookups) and p99 < 1ms over 10k evaluate calls.

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/standby-write-reconciliation.md

@@ -0,0 +1,62 @@
+# Side-Effects Review — Standby-Write Reconciliation + Typed Refusal (P2-6 / F9)
+
+**Spec:** docs/specs/standby-write-reconciliation.md (converged round-3 + approved — operator standing preapproval, topic 29836). **Parent:** A Refusal Stays a Refusal — a write the server cannot complete returns an immediate typed refusal or a bounded error, never an open-ended hang.
+**Ships dev-gated DARK** (`multiMachine.writeAdmission.enabled` OMITTED from ConfigDefaults → resolveDevAgentGate: live on a development agent, dark on the fleet) **and dry-run FIRST** (`dryRun: true` even on dev — FD-7 telemetry pattern). Refusal authority is DOUBLE-latched: `dryRun:false` AND the compiled `WRITE_SURFACE_INVENTORY_COMPLETE` constant (§9.14), which ships `false` and is flipped only by the wave-2 PR that lands the reviewed write-surface inventory — config alone can never grant authority.
+**Files:** src/core/WriteAdmission.ts (new), src/core/WriteDomainRegistry.ts (new), src/core/StateManager.ts, src/core/SessionBuildContextStore.ts, src/core/SessionManager.ts, src/core/LocalSessionOwnershipStore.ts, src/core/SessionOwnershipRegistry.ts, src/core/FileClassifier.ts, src/core/devGatedFeatures.ts, src/core/types.ts, src/core/PostUpdateMigrator.ts, src/config/ConfigDefaults.ts, src/monitoring/guardManifest.ts, src/scaffold/templates.ts, src/server/AgentServer.ts, src/server/routes.ts, src/commands/server.ts
+
+## What changed
+
+1. **WriteAdmission.ts (new):** the single synchronous, in-memory admission decision point (I2 — zero fs/network/LLM/await on the admission path). Implements the §3.2 decision table split by domain: `machine-local` admits everywhere; `cluster-shared` rides the legacy lease boolean verbatim; `session-scoped` admits unbound/absent/released (today-equivalent to the pool-active carve-out — M2 reachability) and refuses only a record positively naming another machine; `topic-scoped` absent/released collapses to the legacy lease boolean (§9.18 — I4 by construction) unless an I9-audited absent-window story opts in. Owns the boot-warmed `OwnershipIndex` (one synchronous `store.all()` scan at construction + the interface-level `onCommit` hook, hook-registered BEFORE the warm so no commit can interleave) with ingest validation (round-2 L1: malformed ⇒ `ownership-unresolved` fail-closed, never `not-owner` with `owner:null`). Typed refusals per §3.4 (409 + Retry-After, refusal bodies from LOCAL knowledge only — I7). Route-seam throw splits by domain (§9.16: machine-local proceeds, scoped/shared refuse typed `admission-error`); store-seam throw falls back to the legacy verdict and is recorded (`noteStoreSeamError`). §6 observability: per-domain counters, ≤50-entry refusal ring, bounded+rotated `logs/write-admission.jsonl` (buffered — flushed OFF the admission path), the `monitorEventLoopDelay` gauge (the P2-6 hang-attribution instrument), and the ≥N-per-window ONE-deduped-attention-item aggregate (flood lesson).
+2. **WriteDomainRegistry.ts (new):** the single source of truth (ops / EXACT kv keys / route prefixes → domain + two-axis convergence story). I9 enforced structurally: a machine-local entry with no story, or on a git-synced shared path with no file-level arm, is REFUSED the classification and downgraded to cluster-shared (recorded in `refusedClassifications`). Exports `WRITE_SURFACE_INVENTORY_COMPLETE=false` (the §9.14 latch), `sessionBuildContextKeyFor` (charset-jailed per-machine key), and `buildWriteDomainRegistry` — the ONE builder the server wires and the tests read (PR-#334 registry↔wiring identity).
+3. **StateManager.ts:** `guardWrite` gains `key`/`scope` opts and delegates to the attached admission layer; `'legacy'` verdicts fall through to the blanket boolean verbatim; refusals throw `WriteRefusedError` (legacy message string preserved for log-scraping continuity). `attachWriteAdmission` is ONE-WAY (second attach throws) and lands before routes are wired (§3.2 pre-construction window); pre-attach behavior is byte-identical to today. New `sessionPoolActive` getter.
+4. **SessionBuildContextStore.ts + SessionManager.ts + server.ts:** the store is re-keyed PER MACHINE (`session-build-context-<jailed-machine-id>`, literal `local` on identity-less installs — round-2 L3: coordinator/mesh identity, never the caller-less `StateManager.setMachineId`), via a late-resolving getter threaded through SessionManagerOptions. This is the F9 fix (the 2026-07-02 "Failed to record build context … read-only" stderr line). The LEGACY shared key stays unclassified (cluster-shared, I8), self-drains (6h max age), and gets a one-time lease-holder cleanup at boot.
+5. **LocalSessionOwnershipStore.ts + SessionOwnershipRegistry.ts:** `onCommit` added to the `SessionOwnershipStore` INTERFACE (round-2 S4) and fired at each substrate's own mutation point (Local: `persist()` after `cache.set`; InMemory: `casWrite()` at `recs.set`) — both mutation paths (`registry.cas()`, `OwnershipApplier`) funnel through `casWrite`, so the index can never miss a local transition. A listener throw never fails the CAS (guarded).
+6. **FileClassifier.ts:** `.instar/state/attention-items.json` + `.instar/state/evolution/` added to the git-sync exclusions (the I9 second-axis wave-1 build item, round-2 S1) — deliberately NOT the whole `.instar/state/` tree.
+7. **routes.ts:** the route seam `refuseInadmissibleWrite` — admission is the FIRST await-free statement after body validation (I1) on the wave-1 P2-6 families (`POST/PATCH /evolution/*`, `POST/PATCH /attention*`), BEFORE the tone gate on `POST /attention` (I3 refuse-before-touch). `GET /write-admission` (503 when dark) + the event-loop gauge on the AUTHED `/health` extension ONLY (§6 — a load oracle is never handed to an unauthenticated caller).
+8. **server.ts:** production wiring — gate → construct (registry + real ownership store boot-warm + attention hook + logDir) → one-way attach → AgentServer/routes. Init failure is non-fatal (layer stays null → route 503s, legacy guard keeps enforcing).
+9. **guardManifest.ts / devGatedFeatures.ts / ConfigDefaults.ts / types.ts:** the `writeAdmission` posture row (`loadBearing:false` while the legacy guard enforces — re-reviewed at fleet graduation), the DEV_GATED_FEATURES registration, the SHARED_DEFAULTS block (no `enabled:` literal — the #1001 anti-pattern avoided), the `WriteAdmissionConfig` type.
+10. **PostUpdateMigrator.ts + templates.ts:** the Write Admission CLAUDE.md section (Agent Awareness), shipped to new agents via `generateClaudeMd` and to existing agents via the content-sniffed idempotent `migrateClaudeMd` patch. Honestly tagged experimental/dry-run (Maturity Honesty).
+
+## Blast radius
+
+- **Dry-run carries ZERO authority.** In every shipped configuration (fleet dark; dev live+dryRun) the legacy blanket guard keeps enforcing byte-identically; the new layer only evaluates and logs would-verdicts. The only execution-path deltas that are live everywhere are (a) the SessionBuildContextStore per-machine RE-KEY (single-writer-per-file by construction; the legacy key self-drains) and (b) the FileClassifier sync exclusions (both stores already wrote locally on every machine — the exclusion closes a PRE-EXISTING git-sync fork surface, §3.1).
+- **Fork-safety never weakens (I4).** cluster-shared refuses on every non-holder in EVERY mode; topic-scoped absent/released IS the legacy boolean; session-scoped only ever TIGHTENS relative to the existing pool-active carve-out. Single-machine agents: strict no-op (I6).
+- **A broken guard fails toward today.** Store seam: any admission throw → legacy verdict + recorded occurrence. Route seam: machine-local proceeds (refusing would create a NEW outage for writes safe everywhere), scoped/shared refuse typed `admission-error` (a broken guard must not enable a fork). Construction failure at boot: layer null, route 503, legacy guard enforcing.
+- **No egress, no spend, no new HTTP mutation surface.** The only new route is the read-only `GET /write-admission`. The aggregate attention item is throttled to ONE per (surface, code, direction) window.
+
+## Risk + mitigation
+
+- **Risk:** the admission path regresses request latency or does I/O. **Mitigation:** I2 enforced by test (fs spied on every admission call including negative lookups; p99 <1ms over 10k calls); log rows are buffered and flushed on a timer OFF the admission path.
+- **Risk:** the ownership index diverges from the store. **Mitigation:** hook-then-warm ordering inside a synchronous constructor; parity tests run the SAME cas/applier sequences against BOTH shipped substrates and assert index≡store.
+- **Risk:** `dryRun:false` leaks refusal authority before the wave-2 inventory is reviewed. **Mitigation:** the compiled `WRITE_SURFACE_INVENTORY_COMPLETE=false` latch — config cannot flip it; proven by the e2e double-latch test at the production constant.
+- **Risk:** a refusal storm floods Telegram topics. **Mitigation:** aggregate-only alerting (≥N per window ⇒ ONE deduped item), proven by the e2e burst-invariant test (40 refusals ⇒ exactly 1 item).
+- **Risk:** the re-key strands existing build-context entries. **Mitigation:** entries carry a 6h max age (self-drain); restore is inherently machine-local (worktree paths are per-disk), so no cross-machine read ever needed the shared key; one-time lease-holder cleanup removes the inert file.
+
+## Migration parity
+
+- Config: the `multiMachine.writeAdmission` block lives in SHARED_DEFAULTS, which feeds BOTH `getInitDefaults` (new agents) and `getMigrationDefaults` → `applyDefaults` (existing agents, existence-checked, `_instar_noMigrate`-respecting, idempotent). No `enabled:` literal (dev-gate rides resolveDevAgentGate).
+- CLAUDE.md: `WRITE_ADMISSION_CLAUDEMD_SECTION` shared by `generateClaudeMd` (new) and the content-sniffed `migrateClaudeMd` patch (existing) — single source, can't drift.
+- No hook/skill/wire-protocol changes; old-version PEERS need nothing (admission is machine-local, no cross-machine dependency — the F4 mixed-pair row in §5).
+
+## Dark-gate line-map
+
+- The new `multiMachine.writeAdmission` block (11 lines, no `enabled:` literal) shifts every multiMachine-onward `enabled: false` attribution DOWN by +11 — the EXPECTED map in tests/unit/lint-dev-agent-dark-gate.test.ts is updated and re-verified via the attributor (866→877, 870→881, 877→888, 887→898, 1124→1135, 1150→1161, 1160→1171, 1189→1200, 1377→1388, 1518→1529, 1563→1574, 1588→1599). `writeAdmission` registered in DEV_GATED_FEATURES.
+
+## Rollback
+
+- Fleet: already dark (gate resolves off) — zero presence, route 503s. Dev: set `multiMachine.writeAdmission.enabled: false` (force-dark even on a dev agent) → the layer is never constructed, StateManager keeps the legacy blanket verdict. The re-key rollback is inert by design: reverting to the legacy key merely resumes the old shared-file behavior; per-machine files self-drain in 6h.
+
+## Tests (all three tiers)
+
+- **Tier 1 (unit):** tests/unit/write-admission.test.ts (37 — the full §3.2 verdict table: every domain × role × ownership state × pool-active × dryRun, both sides of every boundary; I2 fs-spy + p99 timing; refusal schema + Retry-After; route/store throw splits), tests/unit/write-admission-ownership-index.test.ts (10 — parity across arbitrary cas/applier sequences against BOTH substrates; ingest validation; boot-warm completeness), tests/unit/write-domain-registry.test.ts (16 — I9 both axes; exact-key kv; legacy key stays cluster-shared), tests/unit/state-manager-write-admission.test.ts (11 — delegation, one-way attach, legacy fallback on throw, journal path jail survives), tests/unit/write-domain-conformance-ratchet.test.ts (6 — the §3.5 ratchet over routes.ts + the recorded TODO-classify baseline in tests/fixtures/write-surface-inventory.json, down-only), tests/unit/session-build-context-store.test.ts (re-key + per-machine isolation), tests/unit/lint-dev-agent-dark-gate.test.ts (line-map).
+- **Tier 2 (integration):** tests/integration/write-admission-routes.test.ts (13 — the wave-1 families 201 on a standby-that-owns-topics; cluster-shared 409 typed + Retry-After + zero store mutation (I3 store snapshot); dryRun legacy behavior + would-verdict rows; admission-throw per-seam fail directions).
+- **Tier 3 (e2e):** tests/e2e/write-admission-lifecycle.test.ts (8 — production init path with the REAL gate/registry/on-disk ownership store; live-on-dev 200 / fleet-dark 503 / explicit-false force-dark; the §9.14 double latch at the PRODUCTION constant; the F9 fix end-to-end on a read-only standby; burst invariant ≤1 attention item; GUARD_MANIFEST row + GET /guards posture row over real disk config).
+
+## CI follow-up (2026-07-03): discoverability + delivery-completeness classification
+
+Two conformance ratchets (unit shards 1 + 4) required deliberate classifications the feature commit had not made — both are metadata-only, zero behavior change:
+
+- **`/write-admission` route prefix → `INTERNAL_PREFIXES`** (src/server/CapabilityIndex.ts): the read-only status surface is dev-gated dark (503 on the fleet) and agent-surfaced via the CLAUDE.md "Write Admission" awareness section rather than `/capabilities` discovery — same class as `/mesh-selfheal` and `/worktrees/agent-reaper`. No route, verdict, or admission behavior changes.
+- **`'Write Admission'` migrator section → tracked in `legacyMigratorSections`** (tests/unit/feature-delivery-completeness.test.ts): records the template+migrator parity already implemented via the shared `WRITE_ADMISSION_CLAUDEMD_SECTION` (dark/dry-run, not framework-shadowed — same class as 'Mesh Self-Healing').
+
+Side effects: none (a capability-index classification entry + a test allowlist entry). Rollback: revert the two hunks.

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.