instar 1.3.122 → 1.3.123

package/upgrades/1.3.123.md

@@ -0,0 +1,105 @@
+# Instar Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Codex usage is now readable over HTTP — the codex `/status` rate-limit
+windows, without the interactive TUI.** Codex has no public usage API, but the
+codex CLI persists the authoritative account rate-limit windows it gets back
+from OpenAI — primary (5h rolling) and secondary (weekly) — into each session
+rollout's `token_count` events. A new reader
+(`readLatestCodexUsage`) finds the newest rollout, reads only its tail (the
+windows are appended per-turn, so the freshest is near the end), and returns a
+structured snapshot. A new read-only route, `GET /codex/usage`, surfaces it:
+
+```
+{ "available": true,
+  "usage": {
+    "primary":   { "usedPercent": 13, "remainingPercent": 87, "windowMinutes": 300,   "resetsAtIso": "…", "resetsInSeconds": … },
+    "secondary": { "usedPercent": 93, "remainingPercent": 7,  "windowMinutes": 10080, "resetsAtIso": "…", "resetsInSeconds": … },
+    "model": "gpt-5.5", "planType": "plus", "rateLimitReachedType": null } }
+```
+
+`available:false` (still HTTP 200, never 503 — it is a disk reader) means there
+is simply no codex session data on disk yet (e.g. a pure-Claude agent). This is
+the data an agent needs to answer "how much codex usage is left?" and to drive a
+model-swap when a window is exhausted (`rateLimitReachedType` non-null, or
+`secondary.remainingPercent` low).
+
+The route is classified in the capability index (discoverable via
+`GET /capabilities`), surfaced in the CLAUDE.md template for new agents, and
+back-filled into existing agents' CLAUDE.md by the migrator (so deployed agents
+learn it on update). Also restores the feature-delivery-completeness test to
+green by tracking two prior dark/operational migrator sections
+(`Autonomous-fix loop`, `Multi-Machine Session Pool`) that had not been
+registered.
+
+**Codex agents can auto-swap to a fallback model when their weekly window is
+exhausted (ships DARK).** Building on the usage reader above: at codex session
+launch, if the main model's weekly window is spent (or codex flags a limit hit),
+the next session launches on a configured fallback model that draws on a separate
+quota bucket — instead of stalling. The decision is a pure policy
+(`resolveCodexLaunchModel`) wired into both codex launch paths in
+`SessionManager` (headless + interactive). Gated behind
+`codex.rateLimitModelSwap.{enabled,fallbackModel,weeklyRemainingThreshold}`;
+off by default with zero spawn-path overhead. The fallback model id is operator
+config — never hardcoded — because the exact id and its subscription
+availability are the account owner's to confirm.
+
+## Summary of New Capabilities
+
+- `GET /codex/usage` — the freshest codex account rate-limit snapshot (primary
+  5h + secondary weekly windows, with used/remaining percent, window length,
+  absolute + relative reset, plan type, and which window — if any — is
+  exhausted). Read-only; never mutates session state.
+- An optional `?codexHome=` query parameter targets a specific `$CODEX_HOME`
+  (defaults to `~/.codex`).
+- Agent-awareness: the capability appears in `GET /capabilities`, the CLAUDE.md
+  template, and is migrated into existing agents.
+- Codex rate-limit model-swap (dark): `codex.rateLimitModelSwap` —
+  auto-launch the next codex session on `fallbackModel` when the weekly window's
+  remaining percent is at or below `weeklyRemainingThreshold` (default 10) or
+  codex reports a limit hit. Off by default; best-effort and fail-safe (a usage
+  read never blocks a launch).
+
+## What to Tell Your User
+
+You can now ask me how much codex usage is left and I can answer directly,
+without opening the codex status screen myself — I read the same five-hour and
+weekly limit windows the codex tool reports. I can tell you the percent used and
+remaining on each window, when each one resets, which model is in effect, and
+whether either window is currently maxed out. This also gives me the signal I
+need to switch models before the weekly limit runs out. Nothing changes for you
+on update; the capability is simply there when you need it.
+
+And if you want it, I can now do that switch automatically: when a codex agent's
+weekly model quota is nearly spent, the next session it starts can launch on a
+backup model that has its own separate budget, so it keeps working instead of
+stalling. This is off until you turn it on and tell me which backup model to use
+— the exact name and whether it works on your subscription is something only you
+can confirm — so nothing changes by default.
+
+## Evidence
+
+**Source of truth.** Inspected a live codex rollout
+(`~/.codex/sessions/2026/05/30/rollout-…jsonl`) and confirmed each
+`token_count` event carries `payload.rate_limits` with `primary`
+(window_minutes 300) and `secondary` (window_minutes 10080) sub-objects, each
+with `used_percent` and `resets_at`, plus `plan_type` and
+`rate_limit_reached_type`. The observed `secondary.used_percent` of 93 (i.e. 7%
+weekly remaining) matched the codex `/status` screen at the same moment —
+verifying the on-disk windows equal the TUI's.
+
+**Before:** there was no way for an agent to read codex usage programmatically —
+the only surface was the interactive TUI (`UsageMeterProvider.isAuthoritative()`
+returns false and only does local token accounting), so an agent could not
+answer "where does codex usage sit?" or react to an exhausted window.
+
+**After:** `GET /codex/usage` returns the structured snapshot above. Verified by
+a 3-tier test suite (16 tests, all green): unit tests parse the latest
+`token_count` (newest event wins; malformed lines skipped; missing-window
+tolerated; reached-type surfaced), an integration test drives the route over
+HTTP against a rollout fixture (data → `available:true`; none → `available:false`
++ 200), and a Tier-3 lifecycle test boots the real AgentServer and confirms the
+route is alive (200, Bearer-gated, read-only POST→404).

package/upgrades/side-effects/codex-model-swap.md

@@ -0,0 +1,134 @@
+# Side-Effects Review — Codex rate-limit model-swap (directive #4b)
+
+**Version / slug:** `codex-model-swap`
+**Date:** 2026-05-30
+**Author:** Echo (instar-dev agent)
+**Second-pass reviewer:** REQUIRED (touches session spawn / lifecycle) — see verdict at end
+
+## Summary of the change
+
+At codex session launch, if the agent's main model has exhausted its weekly
+window, launch the next session on a configured fallback model (separate quota
+bucket) instead of stalling. New pure policy
+(`src/providers/adapters/openai-codex/observability/codexModelSwapPolicy.ts`) +
+a private `SessionManager.resolveCodexLaunchModel` helper wired into BOTH codex
+launch paths (`spawnSession`→`buildHeadlessLaunch`,
+`spawnInteractiveSession`→`buildInteractiveLaunch`). Consumes the on-disk
+`readLatestCodexUsage` reader (shipped in CODEX-USAGE-VISIBILITY). Ships DARK
+behind `config.codex.rateLimitModelSwap.{enabled,fallbackModel,weeklyRemainingThreshold}`.
+
+## Decision-point inventory
+
+- `SessionManager.resolveCodexLaunchModel` (NEW decision) — picks the launch
+  model for a codex spawn. Add. It is a model SELECTION, not a block/allow gate:
+  the only outcomes are "requested model" or "configured fallback model". Both
+  spawn paths consume it (pass-through for non-codex / disabled).
+
+---
+
+## 1. Over-block
+
+**No block/allow surface — over-block not applicable.** The policy never rejects
+or cancels a launch. Its worst "wrong" outcome is launching on the fallback
+model when it didn't strictly need to (e.g. weekly at exactly the threshold) —
+which still produces a working session, just on the other quota bucket.
+
+## 2. Under-block
+
+**Not a blocker.** The closest "miss": the swap only takes effect at the NEXT
+launch — a session already mid-turn on an exhausted model still fails that turn
+(it can't change model mid-flight). That is inherent to how model selection
+works and is the correct scope; the RateLimitSentinel covers the in-flight
+throttle messaging separately. Also: if usage can't be read, no swap happens
+(fail-safe) — a genuinely-exhausted agent with an unreadable rollout would not
+swap. Acceptable: it degrades to today's behavior (launch on the main model).
+
+## 3. Level-of-abstraction fit
+
+Right layer. The decision lives in the openai-codex observability namespace
+(beside the reader it consumes) as a pure function; the WIRING lives in
+SessionManager at the single point where the launch model is finalized for each
+spawn path. It does not belong in the reader (that's a pure read surface) nor in
+a separate poller (a poller would have to persist an override and re-apply it —
+more state, more drift; deciding at launch is stateless and exact).
+
+## 4. Signal vs authority compliance
+
+**Compliant.** Pure signal-driven decision, zero blocking authority (ref
+`docs/signal-vs-authority.md`). It consumes the authoritative usage signal and
+selects a model. No brittle gate, no veto. Fails safe (read failure → requested
+model). The signal producer (the reader) and this consumer are cleanly split.
+
+## 5. Interactions
+
+- **Shadowing / double-fire:** none. It's the only thing that selects the codex
+  launch model; it runs once per spawn. The two call sites are mutually
+  exclusive (headless vs interactive spawn of a given session).
+- **RateLimitSentinel:** complementary, not conflicting. The sentinel handles an
+  IN-FLIGHT throttle (backoff + notify + verify recovery); this picks the model
+  for the NEXT launch. They operate at different moments and don't race.
+- **`/local-model` + `frameworkDefaultModels`:** the swap takes `options.model`
+  / `defaultModel` (already resolved from those) as its INPUT and only overrides
+  when armed + exhausted, so an explicit per-call/local model still flows through
+  untouched when the feature is off (default) or the window is healthy.
+- **Shared `~/.codex/config.toml`:** unaffected — the model flows via the launch
+  flag (`-c model=` / `--model`), the per-spawn override that already wins over
+  the shared config (same mechanism as `codexThreadlineMcpFlags`). No multi-agent
+  config collision.
+- **Spawn-path latency:** when DISABLED (default) the fast-path guards return
+  before any disk read — zero added latency. When enabled, the read is the same
+  bounded path the shipped `/codex/usage` route uses: a recursive walk of
+  `$CODEX_HOME/sessions` (`listAllRollouts`, capped to the newest few) plus a
+  tail-read of the newest rollout. All async fs, wrapped best-effort (never
+  throws, never blocks the spawn). Only runs when the feature is armed.
+
+## 6. External surfaces
+
+- **Behavioral, opt-in:** when an operator enables it with a verified
+  `fallbackModel`, a codex session may launch on a different model than the
+  configured default once the weekly window is low. That is the intended,
+  operator-armed behavior. A `[SessionManager]` log line records every swap with
+  the reason.
+- No new HTTP surface, no new message, no change visible to other agents.
+- Off by default → no change for any existing agent on update.
+
+## 7. Rollback cost
+
+Low. Pure additive + dark. Back-out = revert the policy module + the
+SessionManager helper/wiring + tests; no data migration, no agent-state repair.
+In the field, neutralise instantly by not setting (or removing)
+`codex.rateLimitModelSwap.enabled` — no redeploy of code required.
+
+---
+
+## Phase 5 — Second-pass reviewer verdict
+
+**Concur with the review.** An independent reviewer subagent audited this artifact
+AND the actual code (not just the claims), verifying each risk with file:line
+citations:
+
+- **Never blocks/delays/breaks a launch:** the single new
+  `await this.resolveCodexLaunchModel(...)` on each spawn path delegates to
+  `resolveCodexLaunchModelWithUsage`, whose disk read is `try/catch`-wrapped and
+  returns no-swap on any throw (`codexModelSwapPolicy.ts:125-129`); the helper
+  always returns `string | undefined`, never throws (`SessionManager.ts`).
+- **Zero disk I/O when disabled:** the three fast-path guards (non-codex /
+  disabled-or-no-fallback / already-on-fallback) all return BEFORE the
+  `read(...)` call; unit tests assert `read===0` for each.
+- **Disabled/default path is byte-identical:** on every fast-path the helper
+  returns the requested model unchanged, so the builder input is unchanged for
+  non-codex agents and codex agents with no config block.
+- **Swap-decision correctness:** swaps only on the documented conjunction; uses
+  the weekly (`secondary`) window not `primary`; `<=` threshold off-by-one
+  covered both ways; never swaps to an empty model.
+- **Both spawn paths covered**, enforced by source-assertion tests.
+- **No conflict** with RateLimitSentinel (different moment), the shared
+  `~/.codex/config.toml` (per-spawn flag override wins), or `/local-model`
+  (its model is the helper's input, passes through when off).
+
+Reviewer notes addressed: §5's spawn-path-latency wording was corrected to
+acknowledge the `listAllRollouts` directory walk (not just a single tail-read).
+One non-blocking nit noted for a future graduation-out-of-dark: the config is
+read via an inline cast rather than a typed `codex?` field on
+`SessionManagerConfig` — intentional to keep the feature dark without a schema
+change; can be promoted to a typed field if/when it ships on by default.

package/upgrades/side-effects/codex-usage-visibility.md

@@ -0,0 +1,107 @@
+# Side-Effects Review — Codex usage over HTTP (GET /codex/usage)
+
+**Version / slug:** `codex-usage-visibility`
+**Date:** 2026-05-30
+**Author:** Echo (instar-dev agent)
+**Second-pass reviewer:** not required (no block/allow/lifecycle decision surface)
+
+## Summary of the change
+
+Adds a read-only way to see codex account rate-limit usage (the codex `/status`
+windows) without the interactive TUI. A new reader
+(`src/providers/adapters/openai-codex/observability/codexRateLimitReader.ts`)
+finds the newest codex rollout, tail-reads its freshest `token_count`
+`rate_limits`, and returns a structured snapshot. A new route
+(`src/server/routes.ts` → `GET /codex/usage`) surfaces it. Discoverability +
+awareness via `src/server/CapabilityIndex.ts` (capabilities entry),
+`src/scaffold/templates.ts` (new-agent CLAUDE.md section), and
+`src/core/PostUpdateMigrator.ts` (existing-agent back-fill). Also registers two
+prior dark/operational migrator sections in
+`tests/unit/feature-delivery-completeness.test.ts` that were untracked
+(pre-existing red on main). No runtime decision point is touched.
+
+## Decision-point inventory
+
+- No decision point. The reader returns data; the route returns it over HTTP.
+  Nothing is gated, blocked, filtered, or routed based on the result. The route
+  is read-only (GET) and Bearer-gated by the existing auth middleware (not new
+  logic).
+
+---
+
+## 1. Over-block
+
+**No block/allow surface — over-block not applicable.** The route is a read-only
+GET that returns 200 with either the snapshot or `available:false`. It rejects
+nothing.
+
+## 2. Under-block
+
+**No block/allow surface — under-block not applicable.** There is no failure
+mode the change is meant to catch-and-stop; it only reports.
+
+The closest "miss" is data freshness: the snapshot reflects the last
+`token_count` codex wrote, which can lag the true account state by up to one
+codex turn. This is acceptable and documented — it is the same data the `/status`
+screen shows, which is also turn-stamped. Callers that need to react to a hard
+exhaustion should treat `rateLimitReachedType` as the authoritative "we are
+limited now" flag (codex sets it when a window is actually hit).
+
+## 3. Level-of-abstraction fit
+
+Correct layer. It sits in the openai-codex observability namespace alongside
+`sessionPaths`/`usageMeterProvider` (it reuses `listAllRollouts`), and is exposed
+through the same HTTP routes layer as the other read-only observability surfaces
+(`/tokens/*`, `/sessions/reap-log`). It does NOT belong in the
+`UsageMeterProvider` interface, because that interface's `read()` is a generic
+token-accounting contract and this is codex-specific authoritative rate-limit
+data — conflating them would muddy the `isAuthoritative()` semantics (the meter
+is correctly non-authoritative; these windows ARE authoritative). A future
+refactor could expose this through a dedicated authoritative-windows method, but
+the standalone reader is the right minimal surface now.
+
+## 4. Signal vs authority compliance
+
+**Compliant.** This is a pure signal producer with zero blocking authority (ref
+`docs/signal-vs-authority.md`). It reads on-disk data and returns it. The
+model-swap policy that will *consume* this signal is a separate change; keeping
+the reader authority-free is exactly the prescribed split (brittle/cheap signal
+at the edge, decisions made by a downstream consumer).
+
+## 5. Interactions
+
+- **Shadowing:** none. No other route serves `/codex/usage`; no existing reader
+  parses `rate_limits`. It reuses `listAllRollouts` (read-only) but does not
+  change it.
+- **Double-fire / race:** none. Stateless per-request disk read; no writes, no
+  locks, no shared mutable state. Concurrent requests each open + close their own
+  file handles.
+- **Adjacent cleanup:** the codex rollout files it reads are owned/rotated by the
+  codex CLI; this reader never deletes or mutates them, so it cannot race
+  rollout rotation destructively (a rotated-away file just yields the next
+  newest, or `null`).
+- **Capabilities lint:** the new `/codex` prefix is now classified in
+  `CapabilityIndex`, satisfying the capabilities-discoverability lint (verified
+  green).
+
+## 6. External surfaces
+
+- **New HTTP route** visible to any Bearer-authenticated caller: `GET
+  /codex/usage`. It exposes the account's codex rate-limit percentages, reset
+  times, plan type, and active model — the same information the account owner
+  already sees on the codex `/status` screen. No secrets, tokens, or message
+  content are exposed.
+- **CLAUDE.md** gains a "Codex Usage" section for new agents (templates.ts) and
+  existing agents (migrator back-fill, idempotent content-sniff). This changes
+  agent-visible instructions, handled per Migration Parity.
+- **Timing dependence:** only freshness (see §2) — bounded by codex's per-turn
+  write cadence. No dependence on conversation state or uncontrolled runtime
+  conditions.
+
+## 7. Rollback cost
+
+Low. Pure additive feature. Back-out = revert the route + reader + the
+CapabilityIndex/template/migrator/test entries. No data migration, no agent-state
+repair, no release coordination beyond a normal patch. The migrator block is
+idempotent (content-sniffed on `/codex/usage`), so partial application or re-run
+is safe.