fix(responses,usage): bundle L5 continuation, retry and usage boundary work

devlog/_plan/260923_luvs_l5_responses_usage/000_plan.md

@@ -0,0 +1,89 @@
+# L5 luvs01 bundle: Responses continuation, retry and usage boundaries
+
+Lane L5 of the luvs01 contributor-PR bundling. Eight open originals become one branch,
+`codex/260923-luvs-l5-responses-usage`, cut from `origin/dev` at `a4bdc03054`, with ordered
+attributable commits and one pull request to `dev`. Landing is decided by the maintainer; this
+unit never merges.
+
+## Constraints
+
+- Local verification is not run in this lane (no test, typecheck, build, install, CLI or service
+  commands). Hosted exact-head CI is the verifier; every report says "local checks: NOT RUN".
+- Push only `HEAD:codex/260923-luvs-l5-responses-usage`. Never write to contributor branches, to
+  `stack/*` branches, or to `dev`.
+- `tests/fixtures/file-size-baseline.json` caps never move up. Overflow moves byte for byte to a
+  sibling file registered in `scripts/test-layout/layout.json` `explicit` and
+  `tests/fixtures/test-layout-expected.json`.
+- Security-sensitive review notes stay in scratch space, never in this directory.
+
+## Dispositions (pinned heads, re-checked 2026-09-23)
+
+| Original | Head | Disposition | Evidence |
+|---|---|---|---|
+| #5474 cursor replay bound | `f4eab495c3` | ALREADY ON DEV (index) + DROP (cutoff) | The constant-time replacement index landed in `74490eee36` (#5507), which says it partially carries #5474. The remaining 4,096-message cutoff can begin inside a user turn, and its new test expects the initiating user root to vanish; #5507 deferred it for that reason. |
+| #5305 usage.jsonl size cap | `fa7f53fee3` | DROP | Unconditional 64 MiB rotation and legacy-ledger deletion contradict the documented opt-in `usageLedgerMaxBytes` retention (`src/usage/ledger-retention.ts`, configuration reference). Readers only read `usage.jsonl`, so rotated rows disappear from totals. |
+| #5434 OAuth rotation attribution | `f6778bfb70` | CHERRY-PICK | Both commits apply cleanly; `hasEligibleGenericOAuthFailoverTarget` is absent from dev. |
+| #5560 continuation boundaries | `2ec0cd12f5` | REIMPLEMENT (net) + CHERRY-PICK | Final tree merges cleanly. The xAI empty-catalog selector part is already on dev in `b20acc79d2` (#5376); the first two commits are combined into their net change. The other nine commits carry in order. |
+| #5542 tool normalization | `b57d7c5da0` | REIMPLEMENT (selective) | The four native-Responses commits are on dev in `53654291cd` (#5508). The five tool-normalization commits carry, with ADR-0097 renamed to ADR-0099 and dev's newer #5508 docs/tests kept on the three conflicts. |
+| #5553 retry/compaction/account | `67c4f579e4` | REIMPLEMENT (selective) | `35fb727ddf` and `940b318292` are on dev in `b7351ddef3` (#5575), which widened the replacement fence. Fifteen commits carry; the retry conflicts keep dev's side. |
+| #5562 search replay boundaries | `6ea3a95c21` | REIMPLEMENT (selective) | `76aa665e64` and `7e826dc089` are on dev in `b7351ddef3` (#5575). Combo isolation and terminal repair carry. Dev's caller-principal and single send-budget contracts are kept. `421ba780ae` and the lifecycle helper from `6b122cd2f0` are carried by open #5549 (another lane); the key-failover fixture adoption that depends on that helper is dropped from this lane and handed back to the maintainer. |
+| #5556 usage observation | `d3589638a8` | CHERRY-PICK + REIMPLEMENT (one hunk) | Ten commits carry. The attribution-timestamp check is tightened to the producer's canonical ISO form. The merge-only commit and the screenshot-only commit are omitted. |
+
+## Commit ledger for the dropped originals
+
+| Commit | Disposition | Reason |
+|---|---|---|
+| #5474 `49a9c15988` | ALREADY ON DEV (index) + DROP (cutoff) | `entryIndex` replacement is in `74490eee36`; the raw 4,096-message cutoff is dropped. |
+| #5474 `68f74eb844` | DROP | The test asserts that the initiating user root disappears. |
+| #5474 `f4eab495c3` | DROP | Merge from dev; no own change. |
+| #5305 `fa7f53fee3` | DROP | Conflicts with the opt-in ledger retention contract. |
+
+## Transitive provenance
+
+| Carrier | Source PRs and authors |
+|---|---|
+| #5474 | contributor fork PR #348 (luvs01) |
+| #5560 | #5350 (Yeonwoo Choi / twoimo), #5420 (maosisheng, Cursor co-author), `82a5f6da81` (Epinephrine), `aac783fe8d` (Devin AI, Epinephrine co-author) |
+| #5542 | #5508 (already on dev; itself carried #5479, #5470, #5492 by luvs01), #5230 (kosta), #5352 (Flowershangfromthebranches), `7cbbf44f6c` (Epinephrine), `19a2005e41` (Devin AI) |
+| #5553 | #5446, #5423, #5415 (luvs01), compaction identity and scoped quota series (Epinephrine, Devin AI) |
+| #5562 | #5480, #5365 (luvs01), `973a4ac702` (Devin AI, Epinephrine co-author) |
+| #5556 | #5358, #5283, #5275, #5255 (luvs01) |
+
+Cherry-picked commits keep their authors and gain `-x` source trailers. Reimplemented commits
+carry `Co-authored-by` trailers for every source author.
+
+## Work-phase map
+
+| Phase | Doc | Content |
+|---|---|---|
+| wp1 | this file | roadmap (docs only) |
+| wp2 | `010_phase1_small_units.md` | #5434 |
+| wp3 | `020_phase2_responses_sequence.md` | #5560, #5542, #5553 on the shared dispatch file |
+| wp4 | `030_phase3_search_usage.md` | #5562, #5556 |
+| wp5 | `040_phase4_pr_ci_review.md` | push, PR, review waves, exact-head CI, security verdict |
+| wp6 | `050_phase5_close_originals.md` | close superseded originals with credit |
+
+## Shared files
+
+- `src/server/responses/passthrough-dispatch.ts`: #5560 (error mapping near the custom-tool
+  admission), #5542 (native-control authorization), #5553 (OpenCode Go reset exception), #5434
+  (OAuth budget-denial attribution). Disjoint hunks, applied in wp2 then wp3 order.
+- `structure/transports/responses.md`: every carrier except #5562 edits a separate paragraph;
+  union the paragraphs and keep dev's #5575 status table.
+- `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`: additive
+  entries only.
+- Capped files touched: `src/server/responses/core.ts` (210/210, one-line re-export kept),
+  `tests/responses/responses-compaction-routing.test.ts` (2776 cap, carry reaches 2772),
+  `tests/server/server-auth.test.ts` (shrinks), `tests/providers/cursor/cursor-blob.test.ts`
+  (net zero), `tests/responses/openai-responses-passthrough.test.ts` (net zero after extraction),
+  `gui/src/pages/Models.tsx` (2792 cap, carry reaches 2783).
+
+## Cross-lane seams
+
+`src/server/responses/request-prepare.ts`, `passthrough-delivery.ts`, `src/codex/auth-context.ts`,
+`src/server/responses/compact.ts`, `core-codex-account.ts`, `src/usage/log.ts`,
+`src/bridge/sse.ts`, `structure/ops/docs-and-release.md`, and both test-layout registries.
+`src/responses/parser.ts` and `src/responses/plaintext-v2-agent-messages.ts` are not touched (the
+#5542 hunk on the latter is already on dev). `421ba780ae` and the whole of `6b122cd2f0`/
+`6ea3a95c21` depend on the sandbox-cleanup helper that open #5549 carries; they stay out of this
+lane so no change is applied twice.

devlog/_plan/260923_luvs_l5_responses_usage/010_phase1_small_units.md

@@ -0,0 +1,23 @@
+# wp2: #5434 OAuth rotation attribution
+
+Source: #5434 head `f6778bfb70`. #5474 (`49a9c15988`, `68f74eb844`, merge `f4eab495c3`) and
+#5305 (`fa7f53fee3`) close without a carry; the commit ledger is in `000_plan.md`.
+
+## Recipe
+
+```sh
+git cherry-pick -x 1ac1ba0c8f f6778bfb70
+```
+
+Files (MODIFY): `src/oauth/generic-account-failover.ts` (new non-mutating
+`hasEligibleGenericOAuthFailoverTarget` using the same eligibility predicate as rotation),
+`src/server/responses/adapter-continuation.ts`, `src/server/responses/passthrough-dispatch.ts`,
+`src/server/responses/run-turn-execution.ts` (gate `noteAttemptRecoveryWithheld` on the probe),
+`structure/transports/responses.md` (cooldown-aware attribution sentence),
+`tests/oauth/generic-oauth-failover.test.ts` (negative cooldown case, positive eligible case,
+source-oracle assertion over the three call sites).
+
+## Check
+
+Static: `git diff --check origin/dev...HEAD`; merge preview clean. A reviewer confirms the probe
+matches `rotateGenericOAuthAccountOn429`'s predicate and that the three sites are gated.

devlog/_plan/260923_luvs_l5_responses_usage/020_phase2_responses_sequence.md

@@ -0,0 +1,53 @@
+# wp3: #5560, #5542, #5553 on the shared Responses dispatch path
+
+Applied after wp2 in this order. Each hunk on `passthrough-dispatch.ts` is disjoint.
+
+## #5560 (head `2ec0cd12f5`)
+
+1. Combine `71a9fe575b` and `ffd50f485c` (both Yeonwoo Choi) into one commit authored by
+   Yeonwoo Choi: `git cherry-pick -n 71a9fe575b ffd50f485c`, then restore
+   `src/adapters/xai-web-search.ts` to `origin/dev` (dev `b20acc79d2` already owns the selector
+   rule), keeping the net Cursor continuation, blob-estimate, xAI custom item-ID repair, extracted
+   tests and docs. The net diff leaves `tests/providers/cursor/cursor-blob.test.ts` at 3,657 lines
+   and `tests/responses/openai-responses-passthrough.test.ts` at 4,809.
+2. `git cherry-pick -x 31f21f0370 a326b67338 7e8fb09b39 57407be416 c7781bf81c fbecefa18b 82a5f6da81 aac783fe8d 2ec0cd12f5`
+   Layout-map conflicts resolve by union.
+
+## #5542 (head `b57d7c5da0`)
+
+Skip `43f1c19fbe`, `10bf60cea3`, `d61ec2e603` (on dev in `53654291cd`) and `7f3f18aed8` (merge).
+
+1. `git cherry-pick -x e555e7305b`. Its decision record is added as ADR-0097 and renamed to
+   ADR-0099 by `b57d7c5da0` below (dev's ADR-0097 is unrelated); the head has no duplicate.
+2. `git cherry-pick -x 7cbbf44f6c 19a2005e41 9662528195`.
+3. `git cherry-pick -x b57d7c5da0`. As a single-commit pick it carries only its own delta (the
+   ADR rename and the combined JSON/SSE regression), so dev's #5508 versions of
+   `docs-site/.../guides/codex-integration.md`, `structure/transports/streaming-health.md` and
+   `tests/responses/ws-native-injection.test.ts` stay intact. A dry run on `a4bdc03054` applied
+   every wp3 commit without conflict.
+
+## #5553 (head `67c4f579e4`)
+
+Skip `35fb727ddf`, `940b318292` (on dev in `b7351ddef3`) and `67c4f579e4` (merge).
+
+1. `git cherry-pick -x b8f9a45761 808dd85a9f db854bf306 b037810fe2 e6f9339f83 f86a53437c 76b40f9fd0 385f338d82 feb0c160aa 466c75c89c 9050722914 b2eda92b1b 1069b541f7 37a006e223`
+2. Conflicts in `src/lib/upstream-retry.ts`, `src/lib/errors.ts`, `tests/lib/upstream-retry.test.ts`,
+   `tests/usage/request-log.test.ts` keep dev's #5575 side (`invitesResendAfterReplacement`, the
+   whole-sentence refusal matcher and its status table).
+3. `git cherry-pick -x be1fee99aa`, then a follow-up commit (luvs01 co-author trailer) rewrites
+   the transport-doc paragraph so it references dev's broader replacement fence instead of a
+   5xx-only rule. The dry run applied it without conflict; the wording is the only repair.
+
+Cap checks after the phase: `src/server/responses/core.ts` 210,
+`tests/responses/responses-compaction-routing.test.ts` at most 2,776.
+
+## Outcome (wp3)
+
+All planned commits applied without conflict on `a077087b74`. Review follow-ups:
+`test(cursor): pin exact host-wrapper classification in continuation scope` (exact summary and
+ambient wrappers are classified by shape, matching the Codex client; documented in
+`structure/providers/cursor.md`) and `test(server): prove a suppressed same-workspace alternate is
+never sent` (exact one-send assertion; the transport contract now limits suppression to the
+in-request move). A later request can still select a same-workspace sibling that was not itself
+refused; that selection behavior predates this carry and is reported to the maintainer.
+Local checks: NOT RUN. Static gate passed; hosted CI verifies in wp5.

devlog/_plan/260923_luvs_l5_responses_usage/030_phase3_search_usage.md

@@ -0,0 +1,64 @@
+# wp4: #5562 and #5556
+
+## #5562 (head `6ea3a95c21`)
+
+Skip `76aa665e64`, `7e826dc089` (on dev in `b7351ddef3`), `65c3477dd2` (merge), and
+`421ba780ae`, `6b122cd2f0`, `6ea3a95c21`: open #5549 carries the sandbox-cleanup helper,
+`createTestCaseLifecycle` and their tests (its `ef5c002220` and `8dc4050fad`). The key-failover
+fixture adoption in `6b122cd2f0` imports that helper, so it cannot land here without applying the
+helper twice; it is dropped from this lane and reported to the maintainer for a follow-up after
+#5549.
+
+1. `git cherry-pick -x 7f45883fb5 c4fa8c8d8f`.
+2. `git cherry-pick -x 8d46989165 3f3fdf17f4`. Once the two already-landed commits are skipped,
+   both apply cleanly (dry run on `a4bdc03054`): `request-prepare.ts` keeps dev's caller-principal
+   block from #5575 and gains only the early combo intersection and shadow marker.
+4. `git cherry-pick -x 973a4ac702 bb49c9f582`, then a follow-up commit (luvs01 co-author) adapts
+   `tests/web-search/web-search-passthrough-bridge.test.ts` (the `clientPrincipalId: "loopback"`
+   expectation) to dev's documented rule that keyless callers get no bridged replay: configure an
+   inbound API key, assert the derived principal, keep a keyless miss control.
+5. `ae52669293`: cherry-pick.
+6. Keep dev's `src/web-search/executor.ts`, `tests/web-search/web-search-sidecar-429.test.ts`, the
+   negative controls in `tests/web-search/web-search-bridge-replay.test.ts`, and the single
+   physical-send budget wording in `structure/runtime.md` and `structure/providers-and-adapters.md`.
+
+## #5556 (head `d3589638a8`)
+
+1. `git cherry-pick -x 0f0ef96ea3 83514c382f`.
+2. `138069331f` reimplemented: in `src/cli/access.ts` treat `attributionSince` as valid only when
+   it round-trips through `new Date(value).toISOString()`; add a malformed-but-parseable case
+   (for example `"0"`) next to the invalid-string case in `tests/cli/cli-dto-fidelity.test.ts`.
+3. `git cherry-pick -x 5563577fc2 c8a9d1a75e 823a7d2d9f 22ee516602 1a8d5f7ded 2241d03f44 ddfef1320b`.
+4. Omit `96602cd13d` (merge of `41ec40f7e3`, already an ancestor of dev) and `d3589638a8`
+   (screenshot asset only; the PR description links the existing capture).
+
+Cap check: `gui/src/pages/Models.tsx` at most 2,792.
+
+## Amendments after review (wp4 P)
+
+- #5562 `3f3fdf17f4`: drop its early combo intersection hunk in
+  `src/server/responses/request-prepare.ts`. It sampled a combo target with `routeModel` before
+  dispatch, so the decision could follow a different pick than the one sent and could advance
+  round-robin or random state. Dev's #4129 rule stays: a shadow call rewritten to a combo enters
+  the combo and carries `shadowCallIntercepted`. The test
+  `a combo whose first target intersects the source still routes as a combo` keeps dev's
+  assertions. The combo-child isolation marker and its tests remain.
+- #5562 `bb49c9f582` follow-up: the bridge replay test configures an inbound API key, derives the
+  principal with `resolveContextPrincipal`, passes the full loopback admission, and adds a keyless
+  miss control.
+- #5556 `138069331f` follow-up: accept `attributionSince` only in canonical
+  `toISOString()` form; positive fixtures use `.000Z`; malformed cases include `"0"`.
+- #5556 selector encoding: `encodePersistedRequestedModel` must stay idempotent because rows are
+  normalized again on read, so a literal selector equal to another selector's encoded form
+  aliases it. Document the limitation in the code comment and pin it with a test; a digest column
+  would remove it and is reported to the maintainer.
+
+## Outcome (wp4)
+
+#5562: seven commits carried; follow-ups `fix(responses): keep combo shadow interception on the
+dispatch pick` and `test(web-search): bind repaired-leg replay to a keyed caller principal`.
+`421ba780ae`, `6b122cd2f0` and `6ea3a95c21` stay with #5549.
+#5556: ten commits carried; follow-ups `fix(cli): accept only an ISO-8601 UTC attributionSince`
+and `docs(usage): state the aliasing limit of the idempotent selector encoding`. The screenshot
+commit is not carried; the PR links the existing capture.
+Local checks: NOT RUN. Static gate passed; hosted CI verifies in wp5.

devlog/_plan/260923_luvs_l5_responses_usage/040_phase4_pr_ci_review.md

@@ -0,0 +1,12 @@
+# wp5: pull request, review, CI, security verdict
+
+1. `git push --no-verify -u origin HEAD:codex/260923-luvs-l5-responses-usage`.
+2. Open one ordinary pull request to `dev` (not draft) with every section of
+   `.github/PULL_REQUEST_TEMPLATE.md`, the disposition table, a "Cross-lane seams" section,
+   "local checks: NOT RUN", and a screenshot link for the Models tab lifecycle change.
+3. Independent reviewers read each carried unit; each confirmed defect gets a fix and a focused
+   regression test in a new commit.
+4. CI is judged on the latest run per job at the current head. Missing, queued, skipped or
+   cancelled jobs are not success. If no cross-platform run appears after a push, close and reopen
+   once.
+5. An independent security reviewer reads the final diff and posts a short verdict comment.

devlog/_plan/260923_luvs_l5_responses_usage/050_phase5_close_originals.md

@@ -0,0 +1,6 @@
+# wp6: close superseded originals
+
+For each original: re-read its head; if it moved past the pinned SHA, re-carry first. Then close
+with a short credit comment naming the bundle PR (ALREADY ON DEV names the dev commit; DROP gives
+the reason). Transitive source PRs owned by other contributors (#5350, #5420, #5230, #5352) are not
+closed by this lane; the bundle description credits them.

docs-site/src/content/docs/guides/codex-integration.md

@@ -586,6 +586,14 @@ Codex. Native custom calls and converted function calls use the same completion
 patch previews are held while their executable form is unresolved. JavaScript that merely
 contains patch text and unrelated native custom payloads stay unchanged.
 
+A routed model can also mistakenly send a shell-argument object such as
+`{"cmd":"git status --short"}` to code-mode `exec`. For a verified code-mode catalog,
+opencodex converts an unambiguous shell object into `tools.exec_command(...)` JavaScript
+and forwards its output through `text(...)`. Shell options are preserved, and Codex still
+executes and authorizes the command. Valid JavaScript fallback fields, ambiguous objects,
+and unrelated tool namespaces are not converted. This compatibility repair does not bypass
+provider rate limits or change the configured retry policy.
+
 Routed code-mode turns are also told the host's rules for the nested helpers before the first
 call: `tools.apply_patch` takes one string that opens and closes with the bare patch marker lines,
 the isolate has no `import`, and long-running commands are polled through `write_stdin`. When a