instar 1.3.910 → 1.3.912

package/upgrades/side-effects/agent-awareness-dark-monitoring-routes.md

@@ -0,0 +1,111 @@
+# Side-Effects Review — dark monitoring-route agent awareness
+
+**Version / slug:** `agent-awareness-dark-monitoring-routes`
+**Date:** `2026-07-23`
+**Author:** `Instar Agent (instar-codey)`
+**Second-pass reviewer:** `capability_honesty` (independent Codex review)
+
+## Summary of the change
+
+Adds shared CLAUDE.md awareness sections for the already-existing
+`GET /pool/failover-gap` and `GET /pool/missing-login` status routes. Fresh
+agents receive the sections from `generateClaudeMd`; existing agents receive
+them through content-sniffed, additive, idempotent migration. The two existing
+CapabilityIndex entries are intentionally unchanged.
+
+## Decision-point inventory
+
+- `migrateClaudeMd` heading checks — add — deterministic presence checks decide
+  whether to append documentation. They do not inspect runtime health or decide
+  any monitoring outcome.
+- Runtime guard decisions and Attention emission — pass-through — unchanged.
+
+## 1. Over-block
+
+No block/allow surface is added or changed. The migration only appends missing
+documentation.
+
+## 2. Under-block
+
+The awareness text cannot make a dark guard live and cannot repair either
+condition. It explicitly says a 503 is unknown posture, not a healthy verdict,
+and that dry-run sends no Attention item.
+
+## 3. Level-of-abstraction fit
+
+One shared source generates both fresh-install and migration text, preventing
+documentation drift. Each route retains its own heading and content sniff, so a
+partially upgraded agent receives only the genuinely missing section.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no new block/allow surface.
+
+Both runtime features remain signal-only. The new text describes status and
+proactive read triggers; it grants no recovery, credential, session, or
+notification authority.
+
+## 4b. Judgment-point check
+
+No competing-signal or semantic judgment point is added. Heading presence is
+an enumerable migration invariant.
+
+## 5. Interactions
+
+- **Shadowing:** each distinct heading is checked independently.
+- **Double-fire:** a second migration is byte-identical and records no second
+  upgrade.
+- **Races:** migration uses the existing single-file migration path.
+- **Feedback loops:** reading either status route changes no state.
+
+## 6. External surfaces
+
+No API, configuration, persistence, notification, or UI surface changes. The
+existing routes and registry entries are only documented to agents.
+
+## 6b. Operator-surface quality
+
+No new operator UI. The agent-facing prose leads with posture, uses plain
+language, distinguishes 503 from health, and names when to consult each route.
+
+## 7. Multi-machine posture
+
+The failover route observes peer availability; the missing-login route observes
+machine-local login/session correlation. This change does not alter either
+scope. It tells agents to report the observed route posture rather than
+guessing across machines.
+
+## 8. Rollback cost
+
+Revert and ship a patch. Previously appended awareness prose remains harmless;
+no state or runtime repair is required.
+
+## Conclusion
+
+The change closes only the awareness and migration-parity gap. Runtime guards,
+dark gates, dry-run posture, CapabilityIndex ownership, and all authority remain
+unchanged.
+
+## Second-pass review
+
+**Independent read:** concur after two documentation corrections.
+
+The reviewer verified the exact runtime posture, route predicates, action
+boundaries, independent content sniffs, second-run byte idempotency, and the
+decision to leave both existing CapabilityIndex entries untouched. The review
+caught wording that called the guards “development-only”; this was narrowed to
+“dev-gated and fleet-dark by default” because an explicit operator
+`enabled:true` remains supported. The upgrade message was also narrowed from
+claiming Instar can always answer to saying agents know where to check when the
+route is available.
+
+## Evidence pointers
+
+- `tests/unit/PostUpdateMigrator-darkMonitoringRoutes.test.ts`
+- `tests/unit/feature-delivery-completeness.test.ts`
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect or self-triggered controller is added.

package/upgrades/side-effects/session-pool-promotion-activation.md

@@ -0,0 +1,52 @@
+# Side-Effects Review — Session-pool promotion activation
+
+**Version / slug:** `session-pool-promotion-activation`
+**Date:** `2026-07-23`
+**Author:** Instar Agent (instar-codey)
+
+## Summary
+
+This change activates the already-merged session-pool rollout driver behind an
+explicit, default-off selector. Auto-climb schedules one driver tick per
+cadence; operator mode exposes only the authenticated one-step route. Both
+paths reuse the signed E2E result store and StageAdvancer.
+
+## Decision-point inventory
+
+- The config resolver accepts only `off`, `operator`, and `auto-climb`; unknown
+  values fail closed to off.
+- The activation controller invokes the existing driver only in a selected
+  live model.
+- The existing driver and StageAdvancer retain green-evidence, commit-binding,
+  one-step, and ceiling authority.
+- The route returns 503 when activation is absent/off and 200 only after a live
+  model invokes the driver.
+
+## Seven-dimension review
+
+1. **Over-block:** operator mode remains available on demand, and the manual
+   route is also available during auto-climb.
+2. **Under-block:** model and ceiling both default dark; invalid config cannot
+   activate promotion.
+3. **Abstraction:** the controller owns activation only; rollout policy remains
+   in the existing driver/advancer.
+4. **Signal vs authority:** signed E2E evidence remains the promotion gate.
+5. **Interactions:** the pre-existing demotion timer is preserved independently.
+6. **External surfaces:** one authenticated local HTTP mutation route is added;
+   it performs no network call and is classified cluster-shared, so standby
+   write admission cannot fork the coherence-critical rollout stage.
+7. **Rollback:** set the selector off or revert; no stored data needs repair.
+
+## Class-Closure Declaration
+
+`unbounded-self-action` closes as a **guard**. Auto-climb is rate-bounded to one
+tick per minute, each tick can write at most one adjacent stage, and the finite
+operator ceiling makes stage mutation settle to zero. The off and operator
+models schedule no autonomous promotion. The boundary unit test and real-driver
+end-to-end test pin those brakes.
+
+## Evidence
+
+Unit coverage pins both activation boundaries and defaults. Integration coverage
+pins dark 503 versus live 200. End-to-end coverage reaches the real server,
+route, rollout driver, signed result store, and stage writer.