instar 1.3.812 → 1.3.813

package/upgrades/1.3.813.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Solo Codex agents now feed real rollout quota windows into the global job/session load-shed brake.
+
+## What to Tell Your User
+
+A solo Codex agent stops starting work when its five-hour or weekly account window is exhausted. Missing, stale, unreadable, or incomplete Codex quota data now pauses new work conservatively instead of failing open into an unknown wall.
+
+## Summary of New Capabilities
+
+- Authoritative `codex-rollout` quota state for the global brake.
+- Healthy Codex windows allow work; exhausted windows shed it.
+- Missing or invalid Codex readings persist explicit uncertainty and fail safe.
+- Existing Claude OAuth-authoritative and JSONL-degraded behavior remains unchanged.
+
+## Evidence
+
+Scoped unit coverage exercises both sides of the gate and every uncertainty boundary. Collector-to-manager integration proves persisted wall shedding and replacement of prior healthy headroom when the reader disappears. Full lint, build, and CI matrix gate release.

package/upgrades/eli16/codex-quota-load-shed.md

@@ -0,0 +1,21 @@
+# ELI16 — Solo Codex agents stop spawning into a quota wall
+
+## What Changed
+
+Instar’s global quota brake already protected Claude and Gemini work, and the subscription pool already understood Codex quota. But a Codex agent with only one account had no producer feeding those real Codex windows into the global brake. When that account was exhausted—or when its quota reading disappeared—the agent could keep starting work that could not succeed.
+
+## What to Tell Your User
+
+Solo Codex agents now read the same authoritative five-hour and weekly rollout windows already used by the subscription pool. Healthy headroom allows work normally. A full window stops new jobs and sessions. If the Codex reading is missing, stale, unreadable, or incomplete, the Codex brake fails safe and pauses new work instead of repeatedly spending attempts against an unknown wall.
+
+## Summary of New Capabilities
+
+- Start the existing quota collector for Codex agents instead of skipping every non-Claude framework.
+- Convert the existing rollout reader’s primary and secondary windows into the shared quota-state shape with `codex-rollout` provenance.
+- Treat Codex rollout data as authoritative at the same load-shed decision layer as provider-native capacity signals.
+- Persist explicit uncertainty when a previously healthy reading disappears, preventing stale headroom from silently keeping the gate open.
+- Preserve Claude semantics: OAuth remains authoritative, JSONL remains bounded-degraded, and missing Claude data retains its existing behavior.
+
+## Evidence
+
+Focused unit tests cover healthy, exhausted, missing, unreadable, and first-boot Codex states plus explicit Claude regression boundaries. Integration coverage drives collector through QuotaManager into the persisted quota file and proves both wall shedding and healthy-to-unknown fail-safe replacement.

package/upgrades/side-effects/codex-quota-load-shed.md

@@ -0,0 +1,91 @@
+# Side-Effects Review — Codex quota load-shed parity
+
+**Version / slug:** `codex-quota-load-shed`
+**Date:** 2026-07-10
+**Author:** Instar-codey
+**Second-pass reviewer:** framework_guard_review
+
+## Summary of the change
+
+Boot now constructs `QuotaCollector` for `codex-cli`, using the existing rollout reader. The collector maps complete primary/secondary windows to shared `QuotaState`, persists explicit `quotaUnknown` when collection is missing or broken, and attributes both as `codex-rollout`. `QuotaTracker` treats complete Codex readings as authoritative and Codex uncertainty as fail-safe denial while preserving Claude semantics.
+
+## Decision-point inventory
+
+- Framework collector construction — modify — Codex gains a real quota producer; Claude construction is unchanged.
+- Codex rollout mapping — add — provider windows become shared quota state.
+- Solo-agent quota authority — modify — complete Codex state gates normally; Codex uncertainty sheds.
+- Existing-agent awareness migration — add — all framework templates learn the new safety posture.
+
+## 1. Over-block
+
+A Codex agent with no readable complete rollout pauses new jobs/sessions, including first boot before its first quota-bearing turn. This is intentional fail-safe behavior requested for a framework where unknown capacity may already be a hard wall. Existing live sessions are not killed. Claude missing data remains fail-open. Gemini's provider-native capacity signal is now explicitly authoritative; at the normal 100% wall behavior is unchanged, while an implausible >100% provider value now sheds all priorities instead of entering bounded-degraded mode—the safe direction for a native capacity signal.
+
+## 2. Under-block
+
+The newest persisted rollout can lag actual provider consumption until Codex emits another rate-limit-bearing event. Thresholds therefore remain the existing brake thresholds, not a prediction system. If quota tracking is disabled entirely, this subsystem remains intentionally absent. A complete but old snapshot is rejected by the tracker’s existing staleness bound and then follows Codex fail-safe denial.
+
+## 3. Level-of-abstraction fit
+
+The existing Codex rollout reader owns provider-log parsing. `QuotaCollector` owns normalization and persistence into the shared state shape. `QuotaTracker` remains the single job/session spawn authority. No second parser or parallel spawn gate is introduced.
+
+## 4. Signal vs authority compliance
+
+Required reference: [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — the rollout reader and collector produce structured provider signals consumed by the existing quota authority.
+
+Quota exhaustion and missing-data posture are constrained operational invariants, not conversational judgments. The tracker already owns this deterministic authority; the change supplies the missing Codex provenance and framework-specific uncertainty rule.
+
+## 5. Interactions
+
+- **Shadowing:** the Codex collector replaces the previous explicit “no framework usage meter” skip only for `codex-cli`.
+- **Double-fire:** a solo Codex agent has one `QuotaManager` and one collector. Subscription-pool polling writes account metadata, not this global quota file.
+- **Races:** `QuotaTracker.updateState` retains its atomic temp-write/rename. Failed collection writes explicit uncertainty so a prior cached healthy state cannot survive invisibly.
+- **Feedback loops:** shedding prevents new spawns; it does not start retries, migrations, or swaps. The next successful scheduled collection overwrites uncertainty and reopens the gate from real headroom.
+- **Gemini scope:** `gemini-cli-capacity` joins the explicit authoritative-source set. A regression test locks its real-wall and over-wall behavior so this additive safety choice is deliberate rather than a silent ride-along.
+
+## 6. External surfaces
+
+Codex agents may pause new background jobs and session spawns when capacity is exhausted or unknown. The existing quota-state file gains additive `codex-rollout` and `quotaUnknown` values. No endpoint, credential, network call, URL, or operator action is added; rollout reads are local and read-only.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture
+
+**Machine-local by design.** A rollout describes the Codex account/config home available on that machine, and the global spawn brake controls that machine’s work. Subscription-pool quota continues its separate replicated metadata path. This feature emits no direct user notice, holds only the existing per-machine quota-state file, does not strand topic state, and generates no URLs.
+
+## 8. Rollback cost
+
+Pure code and additive-state rollback. Older readers ignore the extra fields/source at runtime only after code rollback; deleting the optional quota-state file is not required because the collector will replace it. No database migration or credential repair exists.
+
+## Conclusion
+
+The change closes the last solo-Codex fail-open path at the existing choke point. The design deliberately persists uncertainty rather than letting yesterday’s healthy headroom survive a broken reader. Claude authority/degradation behavior is explicitly regression-tested. Clear to ship after scoped gates and authoritative CI.
+
+## Second-pass review
+
+**Reviewer:** framework_guard_review
+
+**First independent read: concern.** A corrupt quota-state file could return previously healthy cached Codex state, and a complete rollout without a valid capture timestamp was being stamped fresh. Both would let uncertainty masquerade as headroom.
+
+**Resolution:** Codex now clears cached state on corrupt/stale file reads while Claude preserves last-known-good behavior. Collector authority additionally requires a finite capture timestamp no older than the configured freshness window and no more than five minutes in the future; otherwise it persists `quotaUnknown`. Adversarial unit tests cover cached-healthy → corrupt and missing-timestamp → deny. Revised concurrence recorded below.
+
+**Final independent read: concur.** Fail-safe cache and timestamp handling are correct, Claude behavior is preserved, boot wiring is sound, and the reviewer’s focused suite passed 75/75.
+
+**CI follow-up:** The intentional framework-specific corrupt-file catch is classified inline with the repository's narrow `@silent-fallback-ok` annotation. This changes no runtime behavior; it makes the already-reviewed fail-safe fallback explicit to the no-silent-fallbacks enforcement test.
+
+**E2E clock follow-up:** The live Codex pool fixture now injects a fixed clock matching its recorded rollout. Its five-hour reset timestamp had crossed during CI, so the real poller correctly zeroed that expired window while the assertion still expected the pre-reset value. Freezing the fixture clock removes the wall-clock time bomb without changing production expiry behavior.
+
+## Evidence pointers
+
+- `tests/unit/codex-quota-load-shed.test.ts`
+- `tests/unit/quota-tracker.test.ts`
+- `tests/unit/quota-tracker-pool-aware.test.ts`
+- `tests/unit/quota-collector.test.ts`
+- `tests/integration/codex-quota-load-shed.integration.test.ts`
+
+## Class-Closure Declaration
+
+No agent-authored-artifact defect and no self-triggered controller — not applicable.