instar 1.3.122 → 1.3.124

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/1.3.124.md

@@ -0,0 +1,53 @@
+# Instar Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Fixed: `GET /codex/usage` (and the codex TokenLedger / resume scans) timed out
+on a large codex history.** The shared helper `listAllRollouts` walked the ENTIRE
+`$CODEX_HOME/sessions` tree and `stat`-ed every rollout file before slicing to
+the newest few. On a real account that history is large — one machine measured
+14,277 files / 1.4 GB — so the full walk plus ~14k sequential `stat`s, under
+live server load, made `GET /codex/usage` (shipped in v1.3.123) return a
+connection timeout. It now walks the date-partition directories
+(`sessions/YYYY/MM/DD/`) newest-first and `stat`s only the newest partitions
+(at least two, until it has `limit` candidates), with a full-walk fallback for
+any non-date-partitioned layout. The returned newest-N is unchanged; only the
+scan is bounded. This one change fixes all four callers of the helper (the
+codex-usage reader, the TokenLedger codex scan, the session-resume index, and
+the layout canary).
+
+## Summary of New Capabilities
+
+- No new capability — a performance fix. `listAllRollouts` is now bounded to the
+  most-recent date partitions (helpers `listDayPartitionsDescending` +
+  `readNamesDesc`), so codex usage/ledger/resume reads stay fast regardless of
+  how much rollout history has accumulated.
+
+## What to Tell Your User
+
+The codex usage check now answers instantly even on a heavy account. Before this
+fix, on an account with a very large codex history, asking how much codex usage
+was left could hang and time out, because the check was reading through the
+entire history to find the most recent record. It now looks only at the most
+recent day or two of records, so it returns right away. Nothing else changes.
+
+## Evidence
+
+**Reproduction.** On a real codex account with 14,277 rollout files (1.4 GB)
+under `~/.codex/sessions`, hitting `GET /codex/usage` on the running server
+returned a connection timeout — curl reported status 000 after a 30-second
+`--max-time`, while `GET /health` on the same server responded normally. Root
+cause confirmed by reading the code: `listAllRollouts` recursively walked the
+whole tree and awaited an `fs.stat` on every one of the 14k files before
+sorting and slicing.
+
+**Before / after.** The old full-walk timed out at 30 s+ under load. The fixed
+date-partition walk, run against the same live 14,277-file tree, completed in
+**59 ms** (it scanned the two newest day-partitions, found the newest rollout,
+and stopped) — returning the same newest record. A unit test with 206 fixture
+files across 42 partitions uses an `fs.stat` spy to assert fewer than 20 stats
+occur (only the newest partitions), versus 206 before. All three test tiers for
+the codex-usage feature plus the TokenLedger / resume / canary suites stay
+green.

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-rollout-scan-perf.md

@@ -0,0 +1,64 @@
+# Side-Effects Review — bound the codex rollout scan to the newest partitions
+
+**Version / slug:** `codex-rollout-scan-perf`
+**Date:** 2026-05-30
+**Author:** Echo (instar-dev agent)
+**Second-pass reviewer:** not required (pure read-path perf optimization; no block/allow/lifecycle/decision surface)
+
+## Summary of the change
+
+`listAllRollouts` (`src/providers/adapters/openai-codex/observability/sessionPaths.ts`)
+no longer walks + `stat`s the ENTIRE `$CODEX_HOME/sessions` tree to return the
+newest-N rollouts. It now walks date-partition dirs newest-first and stats only
+the newest partitions (>= 2, until `limit` candidates), with a full-walk
+fallback for non-date-partitioned layouts. Fixes the `GET /codex/usage` timeout
+(and the shared TokenLedger / resume-index cost) on a large codex history
+(measured 14,277 files / 1.4 GB → route timed out at 30 s; now 59 ms).
+
+## Decision-point inventory
+
+- No decision point. `listAllRollouts` returns data (a list of file paths +
+  mtimes). The change is purely the disk-scan strategy used to produce that
+  list; the returned newest-N is unchanged for the common case.
+
+---
+
+## 1. Over-block
+No block/allow surface — not applicable. It returns a file list; it rejects
+nothing.
+
+## 2. Under-block
+Not applicable. The closest "miss" is the documented trade-off: a session OLDER
+than the scanned partitions yet still the single most-recently-touched file on
+disk would not be in the candidate set. For the rate-limit reader this changes
+nothing (account-wide windows are identical across any recently-active session);
+for the resume/token-ledger callers it is a vanishingly rare miss (sessions are
+not active for days) and `MIN_PARTITIONS_SCANNED = 2` covers the common
+cross-midnight case.
+
+## 3. Level-of-abstraction fit
+Correct layer — the fix is in the shared helper, so all four callers
+(codex-usage reader, TokenLedger scan, resume index, layout canary) get the
+speedup from one change rather than each re-implementing a bounded scan.
+
+## 4. Signal vs authority compliance
+Compliant — no authority at all. A read helper that returns data; it gates,
+blocks, and decides nothing (`docs/signal-vs-authority.md` n/a beyond "this is
+not a decision point").
+
+## 5. Interactions
+- **Shared helper:** all callers benefit; none depend on the *full* unbounded
+  list (every caller passes a `limit` and wants newest-N). Verified the four
+  call sites pass a finite limit.
+- **No races / no writes:** read-only; opens + closes its own dir/file handles.
+- **Canary:** `codexSessionLayoutCanary` uses date-partitioned fixtures → hits
+  the fast path → stays green (verified).
+
+## 6. External surfaces
+- Makes `GET /codex/usage` actually responsive on a heavy account (it returns
+  fast instead of timing out). No change to the response shape or semantics.
+- No new route, no message, no change visible to other agents.
+
+## 7. Rollback cost
+Trivial. Revert the `listAllRollouts` rewrite + the two private helpers + the new
+test. No data, no migration, no behavior to repair — only the scan strategy.

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.