docs(devlog): Gemini 3.8 Flash rollout closeout

devlog/_plan/260903_gemini_38_rollout/000_plan.md

@@ -0,0 +1,72 @@
+# Gemini 3.8 Flash rollout plan
+
+- Date: 2026-09-03
+- Session: `01a062e6-43d4-7ad2-8236-c75a8fb66a12`
+- Work class: C3 — provider catalog, CCA wire routing, persisted config surface, usage pricing, generated metadata, docs and tests move together.
+- Status: P (wp0, docs-only roadmap cycle).
+
+## Loop spec
+
+- Archetype: satisfy-spec integration.
+- Trigger: Google shipped Gemini 3.8 Flash on 2026-09-02, and authenticated Antigravity discovery already returns three 3.8 wire ids ranked FIRST in the Recommended sort.
+- Goal: make Gemini 3.8 Flash the selectable, correctly tiered Antigravity Flash model, and carry the same spec to every other surface that already names 3.6/3.7 — without inventing anything the vendor has not published.
+- Non-goals: Vertex routing, OrcaRouter/OpenRouter seeding, widening request transport beyond `text`+`image`, hand-editing generated metadata, deleting historical price rows or usage attribution, any release or publish.
+- Verifier: focused `bun test <file>` runs on the touched subsystems plus `bun run typecheck`. **The repository-wide local suite is forbidden by the user** ("로컬스위트는 절대 돌리지 말고"); exact-head GitHub CI is the authoritative full gate.
+- Stop condition: 3.8 is picker-visible with a working low/medium/high ladder, every inventoried 3.6/3.7 surface is updated or carries a recorded reason not to be, focused tests and typecheck pass, CI is green on the exact head SHA, and the PR is merged into `dev` with ancestry proof.
+- Memory artifact: this unit folder.
+- Expected terminal outcomes: `DONE`; `BLOCKED` if CI or branch protection refuses for a reason outside this change; `NEEDS_HUMAN` if a pricing claim turns out unprovable.
+- Escalation: each A gate dispatches one independent read-only reviewer on `gpt-5.6-sol` at high reasoning effort. After two failed reviewer correction loops on the same packet, the main session stops and reports.
+
+## The decision this plan turns on
+
+The 3.6 to 3.7 rollout (`devlog/_fin/260814_overnight_triage_release/020_gemini_37_flash.md`) was a **replacement**: the maintainer's operational fact was that Google pulls the previous Antigravity Flash model almost immediately, so 3.6 had to be deprecated in the same commit that introduced 3.7.
+
+**That premise does not hold for this launch, and both halves of the disproof are first-hand:**
+
+1. Google's own `latest-model` guide says Gemini 3.7 Flash "remains fully supported" and still lists it as Stable (see `001`).
+2. A live CCA `:fetchAvailableModels` call on 2026-09-03 returns 3.5, 3.6, 3.7 **and** 3.8 wire ids simultaneously (see `002`).
+
+So 3.8 lands **additively**: it becomes the default and the recommended Flash row, while 3.7 stays picker-visible and every existing retirement mapping is left exactly where it is. Copying the 3.7 unit's deprecation section would delete a model the backend is still serving.
+
+## The second decision: wire shape
+
+3.7 expresses its tiers as `thinkingLevel` against ONE wire id (`gemini-3.7-flash-tiered`). 3.8 does not: CCA publishes three suffixed wire ids and no `-tiered` row. That makes 3.8 structurally a **3.6-shaped** model, and it must be registered through `ANTIGRAVITY_EFFORT_WIRE_MAP` (rule 2/3), never through `ANTIGRAVITY_THINKING_LEVEL_MODELS` (rule 1b). Registering it the 3.7 way would send `thinkingLevel` against a nonexistent `gemini-3.8-flash-tiered` wire id.
+
+## Work-phase map (dependency-ordered, PHASE-SPLIT-01)
+
+| Phase | Doc | Consumes | Delivers |
+|---|---|---|---|
+| wp0 | this folder | — | research + diff-level roadmap |
+| wp1 | `010_wp1_antigravity_core.md` | wp0 | `antigravity-models.ts` catalog/ladder/routing + registry default |
+| wp2 | `020_wp2_metadata_pricing.md` | wp1 | expected-prices rows, metadata source + regen |
+| wp3 | `030_wp3_peripheral_surfaces.md` | wp2 | direct Google seed, free-directory, Cursor seed, sidecar default, docs |
+| wp4 | `040_wp4_delivery.md` | wp3 | branch, `--no-verify` push, PR, exact-head CI, merge |
+
+wp1 is first because every later surface keys off the picker id and ladder it establishes. wp2 depends on wp1 because the price overlay is keyed by the picker id and the suffix wire ids wp1 introduces. wp3 is last among the code phases because it is the set of surfaces that merely *reference* the model rather than define it.
+
+## Scope
+
+### IN
+
+- `src/providers/antigravity-models.ts`, `src/providers/registry.ts`
+- `src/usage/expected-prices.ts`, `scripts/model-metadata.source.json` (plus `bun run generate:model-metadata`)
+- `src/providers/free-directory.ts`, `src/adapters/cursor/effort-map.ts`, `src/adapters/cursor/catalog.ts`, `src/web-search/index.ts`
+- `docs-site/` provider and sidecar tables
+- focused tests beside the existing Antigravity/catalog/price tests
+
+### OUT
+
+- `src/adapters/google.ts` `GEMINI_DIRECT_WIRE_RENAMES`: no `gemini-3.8-flash-tiered` id is proven on any surface, so adding a rename would invent a wire id. Recorded in `030`.
+- `src/providers/model-rename-migration.ts`: nothing is retired by this change, so no new rename entry. The existing 3.6/3.5 to 3.7 entries stay, because 3.7 is still live.
+- `RETIRED_FLASH_TIERS` and `ANTIGRAVITY_USAGE_BASE_BY_ID`: unchanged for the same reason.
+- Vertex (`google-vertex` `defaultModel` stays frozen), OrcaRouter, OpenRouter, GitHub Copilot.
+
+## Accept criteria (goalplan c-1 through c-7)
+
+1. `gemini-3.8-flash` is one collapsed picker row, not three suffix rows.
+2. Each of `low`/`medium`/`high` resolves to its own `gemini-3.8-flash-{tier}` wire id.
+3. `gemini-3.7-flash` remains picker-visible and its `-tiered` routing is untouched.
+4. Retired 3.6/3.5 ids still route to 3.7 with their recorded tier and stay picker-invisible.
+5. Historical usage rows carrying 3.6/3.7 ids still aggregate under their own base.
+6. `bun run typecheck` exits 0; only focused test files are run locally.
+7. CI green on the exact head SHA and the PR merged into `dev`.

devlog/_plan/260903_gemini_38_rollout/001_vendor_claim_ledger.md

@@ -0,0 +1,54 @@
+# 001 — Gemini 3.8 Flash: vendor claim ledger
+
+Research snapshot 2026-09-03 (KST), collected by an independent read-only research lane on
+`gpt-5.6-sol` at high reasoning effort. Every row was verified by opening the linked official
+page. Unprovable fields say `NOT PROVEN` rather than borrowing 3.7's value.
+
+| Claim | Value | Source | Page date |
+|-------|-------|--------|-----------|
+| Canonical Developer API id | `gemini-3.8-flash` | ai.google.dev/gemini-api/docs/models/gemini-3.8-flash | 2026-09-02 |
+| Published aliases | stable id only; `-preview`/dated/`-latest` NOT PROVEN | same + docs/models | 2026-09-02 |
+| Release date | 2026-09-02 | deepmind.google model card; docs.cloud.google.com | 2026-09-02 |
+| Availability | GA, production-ready (not Preview) | latest-model guide | 2026-09-02 |
+| Context window | 1,048,576 input tokens | model page | 2026-09-02 |
+| Max output | 65,536 tokens | model page | 2026-09-02 |
+| Input price | $0.75 / 1M through 2026-12-31, $1.50 / 1M from 2027-01-01 | Developer API pricing | 2026-09-02 |
+| Output price (incl. thinking) | $3.75 / 1M through 2026-12-31, $7.50 / 1M from 2027-01-01 | Developer API pricing | 2026-09-02 |
+| Separate thinking price | none — thinking billed as output | pricing | 2026-09-02 |
+| Cache read | $0.075 / 1M through 2026-12-31, then $0.15 | pricing | 2026-09-02 |
+| Cache storage | $0.50 / 1M tokens/hour through 2026-12-31, then $1.00 | pricing | 2026-09-02 |
+| Batch / Flex | half of standard input and output | pricing | 2026-09-02 |
+| Priority | $1.35 in / $6.75 out per 1M through 2026-12-31 | pricing | 2026-09-02 |
+| Thinking parameter | `generation_config.thinking_level` (replaces `thinking_budget`) | latest-model | 2026-09-02 |
+| Thinking values | `low` / `medium` / `high`, default `medium` | latest-model; Cloud guide | 2026-09-02 |
+| `minimal` | unsupported — setting it returns a validation error | model page; Cloud guide | 2026-09-02 |
+| Inputs | text, image, video, audio, PDF | model page | 2026-09-02 |
+| Outputs | text only (no image/audio generation, no Live API) | model page | 2026-09-02 |
+| Knowledge cutoff | March 2026 (some domains still January 2025) | DeepMind model card | 2026-09-02 |
+| Antigravity default | proven for the Managed Agents agent and the Antigravity SDK; the desktop/CCA backend default is NOT PROVEN | latest-model | 2026-09-02 |
+| Vertex / Agent Platform id | `gemini-3.8-flash`, `publishers/google/models/gemini-3.8-flash:generateContent` | Cloud developer guide | 2026-09-02 |
+| **3.7 Flash deprecated?** | **No — Google says 3.7 Flash "remains fully supported" and still lists it Stable** | latest-model; models catalog | 2026-09-02 |
+| CCA billing equivalence | NOT PROVEN — the listed prices are Developer API prices | pricing | 2026-09-02 |
+
+## Other providers OpenCodex integrates
+
+| Provider | 3.8 model id published? | Source |
+|---|---|---|
+| OpenRouter | YES — `google/gemini-3.8-flash` | openrouter.ai model page |
+| Cursor | NO — models page and changelog still stop at 3.7 Flash | cursor.com/docs/models-and-pricing; /changelog |
+| GitHub Copilot | NO — supported-model table lists 3.5/3.6/3.7 only | docs.github.com Copilot supported models |
+
+## Unprovable fields
+
+- 3.8-specific preview, dated, or `-latest` aliases.
+- A standalone `blog.google` launch post (the date rests on the DeepMind card and the Cloud record).
+- Cloud Code Assist billing equivalence to Developer API list prices.
+- Cursor and GitHub Copilot 3.8 model ids.
+
+## Why the pricing row cannot be `verified` for Antigravity
+
+OpenCodex routes this model through CCA, and the pricing page distinguishes Developer API,
+Enterprise Agent Platform, and managed Antigravity-agent pricing without proving equivalence
+for the Cloud Code Assist backend. This is exactly the provenance caveat the 3.7 unit already
+recorded, and `src/usage/expected-prices.ts` already has the right enum member for it:
+`verified-derived`. Only a `google`-provider row may claim `verified`.

devlog/_plan/260903_gemini_38_rollout/002_live_cca_probe.md

@@ -0,0 +1,62 @@
+# 002 — Live Cloud Code Assist evidence
+
+Probes run 2026-09-03 from this worktree against `daily-cloudcode-pa.googleapis.com` using the
+already-stored local Antigravity OAuth credential and the repository's own
+`ANTIGRAVITY_REQUEST_UA`. No token, refresh token, or project id was printed or persisted; the
+probe scripts were removed after the run.
+
+## `v1internal:fetchAvailableModels` — the 3.8 rows
+
+| Wire id | displayName | maxTokens | maxOutputTokens | supportsThinking | thinkingBudget | minThinkingBudget | supportsImages | supportsVideo |
+|---|---|---:|---:|---|---:|---:|---|---|
+| `gemini-3.8-flash-low` | Gemini 3.8 Flash (Low) | 1048576 | 65536 | true | 1000 | 32 | true | true |
+| `gemini-3.8-flash-medium` | Gemini 3.8 Flash (Medium) | 1048576 | 65536 | true | 4000 | 32 | true | true |
+| `gemini-3.8-flash-high` | Gemini 3.8 Flash (High) | 1048576 | 65536 | true | -1 | 32 | true | true |
+
+**There is no `gemini-3.8-flash-tiered` row.** The payload does contain
+`gemini-3.7-flash-tiered` and `gemini-3.6-flash-tiered`, so its absence for 3.8 is a fact about
+this generation, not a gap in the probe.
+
+## `agentModelSorts` Recommended order (verbatim)
+
+```
+gemini-3.8-flash-high, gemini-3.8-flash-medium, gemini-3.8-flash-low,
+gemini-3.7-flash-high, gemini-3.7-flash-medium, gemini-3.7-flash-low,
+gemini-3.6-flash-high, gemini-3.6-flash-medium, gemini-3.6-flash-low,
+gemini-pro-agent, gemini-3.1-pro-low, claude-sonnet-4-6,
+claude-opus-4-6-thinking, gpt-oss-120b-medium
+```
+
+Two things follow. 3.8 outranks every other Flash generation, so it is the natural default. And
+**3.7 and 3.6 are both still being served** — the "previous Flash is pulled immediately"
+premise behind the 3.6 deprecation does not apply here.
+
+## `v1internal:generateContent` — all three tiers accept inference
+
+Minimal one-line prompts with `generationConfig.thinkingConfig.thinkingLevel` set to the
+matching tier:
+
+| Wire model | HTTP | Output marker |
+|---|---:|---|
+| `gemini-3.8-flash-low` | 200 | `OK-LOW` |
+| `gemini-3.8-flash-medium` | 200 | `OK-MEDIUM` |
+| `gemini-3.8-flash-high` | 200 | `OK-HIGH` |
+
+This is the same pre-exposure proof the 3.6 rollout recorded: all three ids accept inference
+before any catalog change ships, so the ladder in `010` cannot advertise a rung the backend
+would reject.
+
+## What the running proxy does with them today
+
+`ocx models live --provider google-antigravity` currently publishes the three 3.8 ids as
+**separate uncollapsed rows with `reasoningEfforts: []`** — the same broken shape #1897
+described. Discovery finds them, and no static rule knows they are one model, so they arrive as
+three effortless picker entries. That is the defect wp1 closes.
+
+## Security boundary for these probes
+
+- Assets: local Antigravity OAuth access token and discovered project id.
+- Trust boundary: local read of the existing credential store, then HTTPS to the fixed
+  registry-owned base URL. Model text cannot choose the destination, headers, or credential.
+- Controls: nothing credential-bearing printed or written; probe files deleted after the run.
+- Blast radius: three minimal quota-consuming inference calls. No configuration mutated.