lidge-jun · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026
@@ -0,0 +1,41 @@
+# Release train 4: provider and API compatibility
+
+At `origin/dev` `24b2f39b77` (2026-09-27), carry only the managed Pool Images admission fix from #5927 and the response-tier evidence fix from #5497, each as a separate PR rebased on the then-current `dev`. The other candidates need permission, contract, safety, or performance evidence before they change a user path. The P1 Codex App report #4213 remains open until a sanitized failed call identifies the actual route and auth context; the Images route already exists, but can return a configuration error when no capable upstream is available.
+
+## Loop spec
+
+- **Archetype / trigger:** Satisfy-spec HOTL release lane, authorized by the train-4 provider-compat packet.
+- **Goal / stop:** Record all 7 PR and 6 issue verdicts, merge each safe carried fix after exact-head required CI, comment and close only resolved items, and confirm post-merge `dev` CI. A blocked upstream contract or missing live reproduction is a documented deferral, not a reason to widen scope.
+- **Non-goals:** No main/preview, release, deployment, version, GUI, client integration, account-pool redesign, keyless admission bypass, TLS fingerprint change, or logging of request bodies, credentials or account identifiers. Qoder client work belongs to clients-proxy.
+- **Verifier:** Focused adapter/server fixtures prove credential substitution and tier observation. `bun run typecheck`, `bun run test:changed`, `bun run structure:check`, `bun run privacy:scan`, `git diff --check`, exact-head required CI and post-merge `dev` CI prove their stated scopes. Seven simultaneous lanes make the local full suite disproportionately expensive; record every focused command and leave broad suite coverage to CI. Conditional cases and what must be observed are in the decade docs. `package.json` defines all named scripts; the six staged roadmap docs were checked with `git diff --cached --check` (exit 0), which reads the staged diff. Use `git diff --check` for later unstaged implementation edits. Run each other verifier before claiming it passed.
+- **Memory / terminal outcomes:** This numbered unit is the plan and evidence record. DONE means all criteria above have current evidence. NOOP means an item already has verified coverage. UNSAFE means a proposed contract cannot be safely admitted. NEEDS_HUMAN means a missing external decision or sanitized reproduction blocks a specific item. BLOCKED follows the host threshold, not a single delayed CI check. No user-imposed token or wall-clock bound exists; use the current GitHub credentials only for this repository and the dedicated worktree only for source changes.
+- **Escalation:** A discovered credential-destination change, live admission bypass, inability to obtain exact-head required CI, or current `dev` union break triggers replanning or maintainer security review before merge.
+
+## Work phases and dependencies
+
+| Phase | Depends on | Deliverable |
+| --- | --- | --- |
+| `wp0` | — | Docs-only candidate inventory and executable decade docs (`001`, `010`, `020`, `030`, `040`). No production patch. |
+| `wp1` | `wp0` | Carry #5927 on latest `dev`, security review, test, PR, merge, then post the initial #4213 diagnostic comment using the Images result; see `010_images.md`. |
+| `wp2` | `wp1` | Carry #5497 on latest `dev`, test, PR, merge; see `020_response_tier.md`. |
+| `wp3` | `wp2` | Recheck #4213 after the initial Images comment, diagnose #4143 with current code, and triage the remaining issues; see `030_issues.md`. |
+| `wp4` | `wp3` | Post candidate dispositions, close carried originals and verified-resolved issues, check post-merge `dev` CI; see `040_integration.md`. |
+
+`wp1` and `wp2` each make one cohesive code contract reviewable. Later phase P must recheck this plan against the latest `origin/dev` and amend stale line/path assumptions before implementation. Each phase gets P→A→B→C→D and a factual D entry here. The docs-only `wp0` locks this roadmap before code changes.
+
+## Files and source of truth
+
+Only `devlog/_plan/260927_release_train_4/provider-compat/` is this lane's planning write scope. `src/AGENTS.md` and `structure/INDEX.md` map the eventual runtime changes to `structure/data-planes/images.md`, `structure/providers-and-adapters.md`, `structure/transports/responses.md`, `structure/config.md`, `structure/runtime.md`, and `structure/gui-and-management-api.md`; update each relevant owner with its code change. `docs-site/src/content/docs/guides/codex-integration.md` and the provider configuration reference own user-facing text. No new top-level document convention is introduced.
+
+## Architect consultation and audit
+
+Architect handle `01a0e33e-0d4f-7331-9a06-9676194d930e` proposed T4-D0 (docs first), T4-C1 (Pool Images), T4-C2 (tier authority), and T4-I1 (issue-only diagnostics) against `24b2f39b77`. Accept D0, C1, C2 and I1. Amend C1's test location: `tests/server/server-images.test.ts` is exactly at its 2,755-line ratchet cap (`tests/fixtures/file-size-baseline.json:61`), so new cases go into a registered sibling file. Amend D0: general structure docs change with the owning code phase, while this phase records the planned before/after diff. Keep the architect's two code contracts separate so the pricing observation and tier policy land atomically. Same-handle reflection returned **ALIGNED** for all four IDs. Its three refinements were folded into the latest decade docs: name the negative Pool guard fixture in the sibling, name concrete cost/config test paths, and post the #4213 diagnostic after the Images result instead of waiting for the tier PR.
+
+Independent reviewer handle `01a0e348-c775-7a50-b2e5-25d11a5efb92` first returned FAIL on outbound header ownership and the #4213 comment timing/auth context. Both blockers were folded into `010_images.md`, `000_plan.md` and `030_issues.md`; the same reviewer re-audited and returned **PASS**. Its two nonblocking refinements were applied: split the safe-send and pre-fetch refusal fixture assertions, and name the staged-diff check accurately. The validator alone does not enforce the planned strict final Authorization shape; implementation must add it and trigger its negative fixture.
+
+## Phase results
+
+- **wp0 D, 2026-09-27:** Six docs committed at `d3f1dc9954` on `codex/t4-provider-compat-images`; independent roadmap audit ended PASS after two blockers were folded. `git diff HEAD^ HEAD --check` exited 0, privacy scan passed, and the inventory names 13/13 assigned candidates. No production source changed. **Direction for wp1 P:** recheck the Images plan at current `origin/dev`, then implement #5927 with separate Pool/Direct and final-header fixtures before opening a dev PR.
+
+Append the exact branch/PR, source and CI SHA, commands/results, issue disposition, and D conclusion for later phases without claiming an unrun suite.
+- **wp1 resume, 2026-09-28:** A successor task picked up the lane from the stopped thread's handoff, whose content is folded here, and removed the transfer note. The Codex P1 on #6097 (scoped key could reach Pool credential resolution before the scope check) is fixed by filtering forward candidates by admission scope before `resolveFirstUsableOpenAiSidecar`; see `010_images.md` "wp1 re-entry". An independent sol reviewer re-audited the plan (PASS) and re-verified all eleven non-carried verdicts in `001_candidate_inventory.md` against `origin/dev` `24b2f39b77` (AGREE on all; deferred PR heads unchanged).
@@ -0,0 +1,28 @@
+# Candidate inventory and release decision
+
+Read the final PR diffs against `origin/dev` `24b2f39b77` on 2026-09-27. The review is a release decision, not a claim that a candidate PR's own CI passed. PR head SHAs and re-entry requirements must be refreshed before commenting or integrating.
+
+| Candidate | Head at review | Train-4 decision and evidence | Re-entry condition |
+| --- | --- | --- | --- |
+| #5995 keyless Zen | `25ccb594a31d` | **Defer, keep open.** The published diff mints OpenCode-shaped session and User-Agent identity in `src/adapters/opencode-free-session.ts` and injects `shell`/`read` declarations in `src/adapters/opencode-free-tools.ts`. The keyless tier has no published third-party integration contract; OpenCode's keyed Zen guide describes API-key access. A later injected-tool rewrite cannot be assumed safe across multi-turn Responses history. No credential/admission bypass goes into this release. | OpenCode authorization for another harness and a three-turn tool-call/continuation fixture, followed by a fresh security review. |
+| #5927 Pool Images | `6ff9e6338daa` | **Carry scoped onto current dev.** `src/server/images.ts:663-678` currently rejects every forward candidate when the incoming bearer is a proxy admission secret. Pool resolves a separate stored credential in `src/providers/openai-sidecar.ts:197-216`. Exclude only Direct, preserve explicit keyed and fallback precedence, then verify the final outbound credential. The PR's test additions target a test file exactly at its cap. | Implement `010_images.md`; use a sibling fixture file and exact-head CI. Credit @rrmlima. |
+| #5497 Fastwire tier authority | `1152e3c9fc21` | **Carry scoped onto current dev.** `src/server/responses/core-normalize.ts:223` already treats canonical ChatGPT echoes as observational. Other relays can still downgrade Fast on a non-authoritative `default` echo, and `src/usage/cost.ts:441` can read it as pricing evidence. Optional provider declaration must travel through configuration, attempt log, and pricing together. The PR is draft and conflicts. | Implement `020_response_tier.md` with JSON/SSE, durable log and cost fixtures. Credit @hulkbig. |
+| #3282 Copilot context tier | `351d8ce04c14` | **Defer, keep open.** The 39-file diff adds a separate per-model map and advertises a million tokens for any configured model while current `src/types/provider.ts:264` has model capability declarations. Model eligibility is conditional; the old catalog hunk moved to `src/codex/catalog/model-hints.ts`. GUI is owned by another lane. | Model-specific authoritative tier/window proof, reduced current-dev adapter contract, and coordinated GUI work. |
+| #6003 first-output failover | `8442c7a7a5b4` | **Defer, keep open.** `src/server/first-output-failover.ts` eagerly calls `req.text()` for all requests when any rule exists, before the existing decoded-body limit. It starts the deadline after the first handler returns headers. These paths threaten compressed/large requests and miss header delay. | Bound and decode only eligible requests; start one deadline before dispatch; prove cancellation, real delta, and second-provider disclosure with fixtures. |
+| #4732 registry cache | `44bc1015d218` | **Defer, keep open.** Its `src/router.ts` maps may help, but no representative benchmark is supplied. Its older `src/responses/state.ts` snapshot rewrite conflicts with current spill-reference selection in `src/responses/state/snapshot-select.ts`. | Isolate router-only optimization, benchmark current dev, and keep snapshot byte/restore semantics unchanged. |
+| #3741 Antigravity TLS | `9764129f3ef7` | **Defer, keep open.** The old `src/server/responses/fetch-helpers.ts` integration predates current physical-send egress policy; the opt-in fingerprint transport crosses an authenticated destination boundary. Value is not yet demonstrated against the integration and review risk. | Reimplement at current egress boundary with fail-closed proxy/destination fixtures, explicit security review, and full exact-head CI. |
+
+## Issues
+
+| Issue | Train-4 decision and source evidence | Next observable proof |
+| --- | --- | --- |
+| #4213 P1 Codex App trial/image surfaces | **Keep open, diagnose and comment.** `src/server/index.ts:402-430` admits `POST /v1/images/generations`; `src/server/images.ts:678-690` can return 400 if no capable upstream is configured. The app trial call's method/path/status has never been captured; the default-deny 404 at `src/server/index/serve-options.ts:316-320` is a possible route, not a verified root cause. | Sanitized OCX/App versions and method/path/status for each symptom, plus whether the image request had a capable authenticated upstream. No body, token, query secret or account ID. |
+| #4143 desktop-only Terra | **Keep open pending current reproduction.** The report is from 2.49/Linux. Current `src/codex/catalog/native-models.ts:222,339` contains Terra, and docs describe `disabledModels`, suppression and stale app-server catalogs. | Current OCX/Desktop/CLI versions, selected home, whether Sol/Luna appear, redacted `disabledModels`, and catalog SHA/path after sync and restart. |
+| #3506 Cursor/Grok no-progress loop | **Defer, keep open.** `src/adapters/cursor/live-transport.ts:240-250,1094-1104` ends a turn when the client owns a tool; the result arrives in another request. A per-request proxy cutoff cannot classify the whole client trajectory. | A client progress signal or objectively defined cross-request budget and a sanitized trajectory fixture. |
+| #3765 Claude Messages→Astra cache plateau | **Defer, keep open.** `src/claude/inbound.ts:465-502` has different metadata/system fallback shapes; cache counters alone cannot identify the changed prefix or upstream placement. | Redacted warm/cold wire-shape comparison with stable system prefix and cache identity, no prompt text. |
+| #5270 Qoder MCP/tool calls | **Defer adapter implementation; keep open.** `src/adapters/qoder/adapter.ts:17-29` intentionally disables provider tools and persistence. Enabling tools requires preserving Codex-owned execution and call IDs; Qoder client installation belongs to clients-proxy. | Versioned Qoder tool intent/continuation fixture and an adapter-only mapping contract. |
+| #2511 provider request byte budget | **Design only; keep open.** `src/server/responses/outbound-body-guard.ts:67-89` already implements the refusal half. Image downscale/prune changes prompt content and needs a deterministic nesting/newest-turn policy. | Design with exact byte accounting, mutation order, and restoration/consent limits before code. |
+
+## Decision provenance
+
+The original PR authors are @rrmlima (#5927) and @hulkbig (#5497); carried commits need `Co-authored-by` trailers. Each original PR receives a link and thanks after its replacement lands. A rejected-but-viable PR stays open with a concrete English reason. Closed issues require a merged dev fix and a comment linking the merge. Existing issue comments for #3506, #5270 and #2511 already explain their core limitations; the train-4 disposition will link or update them only where new evidence changes it.