instar 1.3.213 → 1.3.215

package/upgrades/1.3.214.md

@@ -0,0 +1,65 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Secret Drop's stored-submission lifetime was reworked so a submitted secret can no
+longer be deleted out from under an active consumer.
+
+- **Server (`SecretDrop.ts`)** — the post-submission store now uses a **sliding idle
+  window** instead of a fixed 5-minute timer. The cleanup timer re-arms on every
+  `peekReceived`, so a secret that is actively being retrieved never expires. The idle
+  window is 15 minutes (was 5) and a new per-token `receivedDeadline` enforces a hard
+  **30-minute absolute cap** (`armReceivedCleanup` clamps each re-arm with
+  `Math.min(idle, deadline − now)`), so even a continuously-polled secret is purged.
+  `consumeReceived`/`shutdown` clear the new deadline map; the stuck-consumer event's
+  `minutesUntilCleanup` is derived from the deadline.
+- **Consumer (`secret-drop-retrieve.mjs`)** — new `--run -- <cmd>` mode performs an
+  **atomic use-and-consume**: it pipes the field value to the command's stdin and
+  consumes the submission only if the command exits 0. A failed or launch-error
+  handoff never destroys the secret, making consume-on-failure structurally impossible.
+- **Awareness/migration** — the CLAUDE.md scaffold documents `--run` for new agents;
+  an idempotent `PostUpdateMigrator` block adds the guidance to existing agents that
+  already have the hardened helper. The helper script itself ships via the existing
+  always-overwrite relay-script refresh.
+
+## What to Tell Your User
+
+- **Secret Drop is now sturdier**: "If you hand me a password or key through a secure
+  link, it won't quietly expire while I'm in the middle of using it anymore — so you
+  shouldn't have to send the same thing twice. And if a step fails, I keep what you
+  sent so we can retry, instead of throwing it away." (Note: a secret still lives only
+  in memory, so a server restart still clears anything not yet used — that's the
+  security trade-off, unchanged.)
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Sliding retrieval window + 30-min cap | automatic |
+| Atomic use-and-consume | `secret-drop-retrieve.mjs TOKEN field --run -- <cmd>` |
+
+## Evidence
+
+**Reproduction (observed live, 2026-06-02):** during a multi-step credential handoff
+(Bitwarden login, then a GitHub token) the operator had to resubmit the same secret
+roughly six times. Each time, the submission sat in the store while a multi-step
+retrieval ran; the fixed 5-minute timer deleted it mid-flow regardless of the active
+retrievals, and a standalone consume fired after a step that had not yet succeeded —
+destroying the secret with no recovery but resubmission.
+
+**Before/after (deterministic, fake-timer unit tests in
+`tests/unit/SecretDrop.test.ts`):**
+- Before this change, a submission was unconditionally deleted 5 minutes after
+  submit. After it: a submission peeked at 14 min and again at 28 min is still present
+  (the window slid on each read); an untouched submission is still cleaned up after the
+  idle window; and a submission polled every 10 min is nonetheless purged once past the
+  30-min absolute cap.
+- `--run` mode: consume is invoked only on child exit 0; on non-zero exit or a launch
+  error the submission is left intact (verified by inspecting the spawnSync branch and
+  the documented `gh auth login --with-token` example).
+
+Suites: SecretDrop 37/37, migration 15/15 green; `tsc --noEmit` clean. An independent
+second-pass reviewer concurred with the side-effects review.

package/upgrades/1.3.215.md

@@ -0,0 +1,41 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Gemini CLI one-shot calls now have a provider-specific capacity policy. When
+Gemini reports a 429, `QUOTA_EXHAUSTED`, `resource exhausted`, or a usage/quota
+limit, Instar parses any reset window Gemini provides, retries only short
+capacity windows once, and otherwise records a local defer window so subsequent
+calls fail fast instead of spawning another doomed Gemini process.
+
+Explicit caller-supplied raw Gemini model ids continue to pass through to the
+Gemini CLI. Only the automatic `capacityPolicy.fallbackModel` path is
+constrained to the known local Gemini model set. When that fallback is valid,
+both Gemini execution paths rebuild `gemini -m <model>` on retry from the
+policy-selected model, so fallback configuration is not just resolved, it is
+actually applied to the next CLI invocation.
+
+## What to Tell Your User
+
+- **Gemini quota handling is calmer:** "When Gemini says its quota is exhausted,
+  I now remember the reset window and stop repeatedly poking it. Short capacity
+  blips get one bounded retry; longer quota windows are surfaced as a clear
+  defer instead of looking like a stalled agent."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|------------|
+| Gemini capacity defer window | Automatic for Gemini CLI one-shot calls |
+| Short Gemini capacity retry | Automatic, one bounded retry for short windows |
+| Known-only Gemini capacity fallback | Automatic; `fallbackModel` swaps only when the fallback is a known Gemini model |
+
+## Evidence
+
+- `npx vitest run tests/unit/gemini-cli-adapter.test.ts tests/unit/geminiCapacityPolicy.test.ts tests/unit/frameworkSessionLaunch.test.ts tests/integration/gemini-capacity-policy-integration.test.ts tests/e2e/gemini-capacity-policy-lifecycle.test.ts`
+  — 5 files / 80 tests passed, including raw-model pass-through and spawned
+  retry argv assertions.
+- `npx tsc --noEmit`

package/upgrades/gemini-capacity-policy.eli16.md

@@ -0,0 +1,21 @@
+# Gemini Capacity Handling — ELI16
+
+Viewable private artifact:
+https://codey.dawn-tunnel.dev/view/b5873ea2-17ba-4adf-9d1a-f0e1c48f781e?sig=3e2c7d2f4e0852cf91496f79ce25aeca72ce778c92d3278e101b63bec90400af
+
+Gemini sometimes says, "I'm out of capacity right now; try again after this
+reset window." Before this change, Instar treated that too much like an ordinary
+failure. The next Gemini call could try again immediately, hit the same quota
+wall, and make the agent look stuck. One fallback path also guessed an old model
+name, `gemini-2.0-flash`, which Gemini rejected.
+
+This change gives Gemini its own capacity rule. If the reset is short, Instar
+waits briefly and tries once. If Gemini gives a longer reset window, Instar
+remembers it and refuses later Gemini calls locally until the window passes.
+That means no repeated doomed Gemini subprocesses and a clearer error for the
+agent/operator.
+
+It also limits Gemini model choices to the verified names we know work:
+`gemini-2.5-flash` and `gemini-2.5-pro`. If some code asks for an unknown Gemini
+model, Instar falls back to `gemini-2.5-flash` instead of sending a guessed model
+to Gemini and getting a 404.

package/upgrades/side-effects/gemini-capacity-policy.md

@@ -0,0 +1,139 @@
+# Side-Effects Review — Gemini capacity policy
+
+**Version / slug:** `gemini-capacity-policy`
+**Date:** `2026-06-03`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change adds a Gemini-specific capacity policy beside the existing Gemini
+adapter observability code. Gemini one-shot calls now classify quota/rate-limit
+failures, parse reset windows such as `quota will reset after 7h32m28s`, retry
+only short capacity windows once, and record a process-local defer window for
+longer quota exhaustion. While deferred, later calls fail locally with a retry
+hint instead of spawning another Gemini CLI process that would hit the same
+quota wall.
+
+Review update: the optional `capacityPolicy.fallbackModel` is now wired into
+the retry loop instead of only being resolved in the policy decision. Both
+Gemini execution paths rebuild `gemini -m <model>` on each retry attempt from
+the current policy-selected model, so a configured fallback actually changes
+the spawned CLI argv. Explicit caller-supplied raw model ids still pass through
+the primary resolver; only automatic capacity fallback is constrained to known
+Gemini models.
+
+The change also constrains automatic Gemini fallback selection to verified known
+models: `gemini-2.5-flash` and `gemini-2.5-pro`. Explicit raw Gemini model ids
+continue to pass through to the CLI because they represent caller intent. The
+bad `gemini-2.0-flash` fallback observed during the mentor loop is avoided by
+the known-only fallback helper rather than by rewriting every raw model id.
+
+## Decision-point inventory
+
+- `isGeminiCapacityError` — add — classifies Gemini quota/rate-limit/capacity
+  error strings.
+- `parseGeminiRetryAfterMs` — add — extracts reset windows from Gemini stderr.
+- `decideGeminiCapacityPolicy` — add — chooses `none`, `retry`, or `defer`.
+- `recordGeminiCapacityDeferral` / `getGeminiCapacityGate` — add — process-local
+  defer state for Gemini calls.
+- Gemini fallback resolution — modify — automatic capacity fallback ids must be
+  in the known set or the current caller-selected model is kept.
+- `GeminiCliIntelligenceProvider` and adapter one-shot transport — modify — both
+  apply the policy before and after spawning Gemini.
+- Retry argv rebuild — modify — short-window retries rebuild the Gemini argv
+  from `decision.model`, so `capacityPolicy.fallbackModel` is applied to the
+  next spawned process.
+
+---
+
+## 1. Over-block
+
+The main over-block risk is a false-positive capacity classification that defers
+Gemini when the failure was not actually quota related. The classifier is
+deliberately narrow: explicit `429`, `QUOTA_EXHAUSTED`, `resource exhausted`,
+`rate limit`, quota, usage-limit, or capacity language. Generic parse errors,
+syntax errors, binary-not-found errors, and ordinary non-zero exits do not defer.
+
+The known-model constraint applies only to automatic capacity fallback. Explicit
+caller-selected Gemini model ids still pass through to the CLI, so newly valid
+Gemini ids are not blocked by this policy. If `capacityPolicy.fallbackModel` is
+unknown, the retry keeps the caller's current model instead of swapping to a
+guessed fallback.
+
+## 2. Under-block
+
+This policy is process-local. A server restart forgets the defer window and the
+first post-restart Gemini call may probe the provider again. That matches the
+existing LLM circuit-breaker shape and keeps the change small. A future durable
+capacity ledger could persist provider reset windows across restarts if repeated
+restart-probes become noisy.
+
+This does not discover the full Gemini model catalog dynamically. It uses the
+currently verified set and keeps the list explicit. Dynamic discovery is a
+separate model-catalog problem, not part of quota handling.
+
+## 3. Level-of-abstraction fit
+
+The policy belongs at the Gemini provider boundary, not at each caller. The
+adapter one-shot transport and live `GeminiCliIntelligenceProvider` are the
+places that see Gemini stderr and own whether to spawn Gemini again. Keeping the
+decision there means reviewers, route, setup narrative calls, and future Gemini
+one-shots share the same capacity behavior.
+
+Known-model fallback belongs in the capacity-policy fallback helper because that
+is the only automatic model swap path in this change. Primary model resolution
+still maps canonical tiers and otherwise respects explicit raw model ids.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] Not applicable to conversational/product judgment — this is deterministic
+  provider-capacity handling and model-id validation at the transport boundary.
+
+The defer gate is not making a semantic judgment about user intent. It acts only
+after Gemini itself reports a quota/capacity condition or while the recorded
+reset window from that provider report is still active.
+
+## 5. Interactions
+
+- **Global LLM circuit breaker:** The Gemini provider still throws clear
+  quota/rate-limit text, so the existing circuit breaker can continue to observe
+  and pause broader LLM-backed work. The Gemini policy additionally prevents
+  repeated Gemini subprocesses during a known Gemini reset window.
+- **Setup wizard:** Gemini narrative fallback continues to work; quota failures
+  become clearer and do not repeatedly spawn Gemini.
+- **Route override detector:** The known-model list now includes
+  `gemini-2.5-flash`, so the verified default is recognized.
+- **Session launch:** Unchanged by the capacity fallback review fix; the
+  known-model gate is isolated to automatic provider retry fallback.
+
+## 6. External surfaces
+
+Users may see clearer Gemini quota/defer errors instead of a generic Gemini CLI
+failure or a stalled task. Operators can rely on `gemini-2.5-flash` as the safe
+automatic capacity fallback when configured. Explicit caller-supplied model ids
+continue to pass through. No config migration, schema change, or external API
+change is introduced.
+
+## 7. Rollback cost
+
+Rollback is a code revert of the Gemini policy module, the two provider wiring
+changes, the fallback known-list change, tests, and these artifacts. No
+data migration is required. A running process that had recorded a defer window
+would forget it on restart.
+
+## Conclusion
+
+The change is a narrow sibling to the Codex capacity/model-swap work, scoped to
+Gemini's actual error and model surfaces. It prevents repeated doomed Gemini CLI
+spawns during quota windows, avoids guessed model fallbacks, and pins the
+behavior with unit, integration, and E2E tests.
+
+## Evidence pointers
+
+- `tests/unit/geminiCapacityPolicy.test.ts`
+- `tests/integration/gemini-capacity-policy-integration.test.ts`
+- `tests/e2e/gemini-capacity-policy-lifecycle.test.ts`
+- `tests/unit/frameworkSessionLaunch.test.ts`

package/upgrades/side-effects/secret-drop-sliding-window.md

@@ -0,0 +1,83 @@
+# Side-effects review — Secret Drop Sliding Window + Atomic Use-and-Consume
+
+**Spec:** `docs/specs/secret-drop-sliding-window.md`
+**Files:** `src/server/SecretDrop.ts`, `src/templates/scripts/secret-drop-retrieve.mjs`, `tests/unit/SecretDrop.test.ts`, `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts`, `src/core/PostUpdateMigrator.ts`, `src/scaffold/templates.ts`
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+Nothing new is rejected. Submission validation (CSRF, required fields, R1a signature)
+is unchanged. The sliding window only affects how long an accepted submission is
+*retained*; it never rejects a submission or a retrieve. `--run` adds a code path but
+the default retrieve/`--names`/`--consume` behaviors are byte-for-byte unchanged.
+
+## 2. Under-block — what failure modes does this still miss?
+
+- **Server restart loses an unconsumed secret.** Explicitly out of scope (in-memory by
+  design); contract documented in the spec; encrypted-at-rest tracked as follow-up
+  (`fb-391a4a30-de9`).
+- **An agent that uses the destructive `consumeReceived`/`--consume` mid-flow can still
+  drop a secret.** The `--run` mode + CLAUDE.md guidance steer away from this, but the
+  standalone `--consume` is retained for back-compat and is still misusable. Mitigated,
+  not eliminated. Accepted: removing `--consume` outright would be a breaking change to
+  any caller already using it.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. Lifetime management belongs in `SecretDrop` (it owns the store and the
+timers). The atomic use-and-consume belongs in the consumer helper (it owns the
+hand-off to the command). No higher/lower layer is a better owner, and no smarter gate
+exists that this should feed instead.
+
+## 4. Signal vs authority compliance
+
+Compliant. This adds no decision point that gates information flow or blocks actions.
+The `--run` "consume only on exit 0" is a success gate on a local subprocess, not an
+authority over agent behavior. No brittle-check-with-blocking-authority is introduced.
+(Ref: `docs/signal-vs-authority.md`.)
+
+## 5. Interactions
+
+- **Stuck-consumer timer:** still fires at 60s; `minutesUntilCleanup` now derives from
+  `receivedDeadline` (true purge time) — more accurate, not less. The stuck timer is
+  NOT re-armed on peek (deliberate: it's a "nobody has consumed this yet" nudge, and
+  the absolute deadline it reports is fixed at submit). No double-fire, no race.
+- **Cleanup timer:** centralized in `armReceivedCleanup`; each re-arm clears the prior
+  timer first (no timer leak). `consumeReceived`/`shutdown` clear the timer, the stuck
+  timer, AND the new `receivedDeadline` map (no map leak).
+- **`--consume` flag and `--run`:** mutually independent; `--run` consumes via the same
+  `?consume=true` endpoint after success. No shadowing.
+
+## 6. External surfaces
+
+- **Other agents:** the helper template change reaches every agent via the
+  always-overwrite relay-script refresh; the server change ships via npm. CLAUDE.md
+  awareness reaches new agents (scaffold) and existing agents (idempotent migrator
+  block, tested). No external API shape change — `/secrets/retrieve/:token` and
+  `?consume=true` are unchanged.
+- **Timing/runtime dependence:** the window is wall-clock based (setTimeout); fake-timer
+  tests cover the boundaries deterministically. No dependence on conversation state.
+
+## 7. Rollback cost
+
+Pure code revert — no data migration, no agent-state repair. Reverting restores the
+fixed 5-min window and removes `--run`; the standalone `--consume` path is untouched
+throughout, so nothing depends on the new behavior to function. The migrator block is
+idempotent and additive (a revert simply stops adding the bullet; already-migrated
+CLAUDE.md files keep a harmless accurate bullet).
+
+## Tier
+
+**Tier 2.** Risk floor 2 (safety-invariant proximity: SecretDrop / never-on-disk).
+Declared at the floor — not below it. Full ceremony: converged + approved spec, ELI16,
+this artifact, second-pass review, trace.
+
+## Second-pass review (independent)
+
+An independent reviewer audited this artifact against the code and verified each
+claim: (1) no timer/`receivedDeadline` map leak — every add has a matching clear on
+consume/shutdown/re-arm; (2) the sliding window cannot exceed the 30-min cap (the
+`Math.min(IDLE, deadline−now)` clamp enforces it); (3) `--run` consumes only on exit
+0, never on launch error or non-zero exit, and the value reaches the subprocess via
+stdin only — never stdout/argv; (4) signal-vs-authority compliant (no brittle gate
+with blocking authority); (5) the stuck-consumer timer is correctly NOT re-armed on
+peek. **Verdict: "Concur with the review."**