docs(devlog): 260712 PR batch landing unit (#96-#103) — plan, audits, DONE record

Author: lidge-jun

devlog/_plan/260712_pr_batch_landing/000_plan.md

@@ -0,0 +1,107 @@
+# 260712 — PR batch landing (#96–#103) with review fixes
+
+## Objective
+
+Land all 8 open PRs from Wibias on lidge-jun/opencodex, honoring the parallel sol-reviewer
+verdicts (2026-07-12 session 019f54d8): merge approved content, fix the named blockers on the
+PR branches, merge in stack order, and leave main green with zero open PRs from the batch.
+
+## Ground truth (explored)
+
+- Stack: `cde614a1`(#96) → `c6af7f90`(#97) → `6bb3aecf`(#98) → `e8794d22`(#99) →
+  `84d601f9`(#100) → `37b4b2d6`(#101) → `21e58b09`(#102), all on fork `Wibias/opencodex`,
+  all base=main. #103 = `aa888074` (independent; overlaps only `src/server/management-api.ts`,
+  `gui/src/pages/Debug.tsx`).
+- Permissions: admin on repo; `maintainerCanModify: true` on PRs → can push fix commits to fork
+  branches. main unprotected; merge-commit method is repo precedent (PR #87).
+- `origin/dev` == `origin/main` == `182ddae9` (v2.7.8). Land to main; fast-forward dev in WP7.
+- Bun 1.3.14 `node:zlib` enforces `maxOutputLength` for gzip AND zstd (verified:
+  ERR_BUFFER_TOO_LARGE) → bomb fix is straightforward.
+- Worktree HEAD has an unrelated unpushed commit `953fb5b9` (another task's work) — do not
+  touch it; all landing work happens on branches cut from `origin/main` / fork branches.
+
+## Landing mechanics (decision)
+
+Fix-on-fork-branch + `gh pr merge N --merge` in stack order. Identical SHAs reach main, so each
+successor PR's ORIGINAL stack prefix disappears from its diff; GitHub marks each PR merged
+(attribution preserved). Drafts get `gh pr ready N` first. `--merge` is REQUIRED throughout —
+squash/rebase would break the ancestry assumption (audit blocker 3). Fix commits pushed to a
+predecessor branch land on main via that predecessor's merge; successor branches never contain
+them, but 3-way merges cannot revert them (successor side unchanged since base). After EVERY
+merge, verify the next PR's `mergeStateStatus` and effective diff before merging it.
+
+Merge order: #103 → #96 → #97 → #98 → #99 → #100 → #101 → #102.
+
+Known conflict point (audit blocker 2, verified via merge-tree): after #103 lands,
+`gui/src/pages/Debug.tsx` CONFLICTS for #99..#102 tips. Resolution: WP5 merges origin/main into
+the #99 branch and resolves Debug.tsx ONCE (combine #99 lint refactor + #103 injection wiring).
+After #99 lands, #100–#102 merge cleanly (their own commits don't touch Debug.tsx, so 3-way has
+only one changed side). #96–#98 are unaffected (verified: no conflict vs aa888074).
+
+## Work-phase map (dependency-ordered, one PABCD cycle each)
+
+| WP | Doc | Content |
+|----|-----|---------|
+| 1 | 010 | Plan (this doc set) + merge #103 |
+| 2 | 020 | #96 + bounded decompression + SSRF resolution/reserved-ranges + activation tests → merge |
+| 3 | 030 | #97 + restore GUI build gate in ci.yml → merge |
+| 4 | 040 | #98 as-is → merge |
+| 5 | 050 | #99 + Usage.tsx cancellation guard → merge |
+| 6 | 060 | #100/#101/#102 as-is → merge |
+| 7 | 070 | Closeout: verify zero open batch PRs, main CI green, dev fast-forward, comments |
+
+## Reviewer verdicts folded in
+
+- #96 BLOCK: bomb cap post-allocation (`src/server/request-decompress.ts:43-48`); SSRF passes
+  non-literal hostnames unresolved (`src/lib/destination-policy.ts:82-110`); reserved IPv4
+  ranges incomplete. → WP2 fixes.
+- #97 BLOCK: deletes GUI build gate (`.github/workflows/ci.yml:73-76`). → WP3 restores.
+- #99 BLOCK: `gui/src/pages/Usage.tsx` fetch has no cancellation → stale overwrite. → WP5 fixes.
+- #98/#101/#102/#103 approved (nits recorded, non-blocking). #100 fixture commit legitimate.
+
+## Rebutted residuals (recorded, not implemented)
+
+- DNS rebinding pinning + redirect-hop validation (reviewer #96): the proxy is a loopback
+  service whose providers are configured by the machine owner; validation-time resolution +
+  reserved-range default-deny is proportionate. Full dial-time pinning needs a custom dialer
+  Bun fetch does not expose. Recorded here + in WP2 commit message.
+- #103 locale-time nit, #102 exhaustion-test nit, #98 adapter-level regression tests: cosmetic /
+  non-blocking; noted for future work, not this batch.
+
+## Rollback / partial-landing policy (audit blocker 5)
+
+- Capture each merge-commit SHA in the goalplan ledger as it lands.
+- If main CI fails after merge N: STOP merging successors; prefer fix-forward on main; if
+  infeasible, `git revert -m 1 <merge-sha>` in reverse landing order back to the last green SHA.
+- If a pushed fork fix must be withdrawn pre-merge: push a revert commit to the fork branch
+  (never force-push another author's branch).
+
+## Verification contract
+
+Each WP: targeted `bun test` locally on the fix branch before push; PR checks green before
+merge; WP6/WP7 run the full suite. Security fixes carry activation tests
+(C-ACTIVATION-GROUNDING-01). Final: `gh pr list` empty for batch, `gh run list --branch main`
+green.
+
+## DONE — 2026-07-12 landing record
+
+All 8 PRs merged in planned order; every merge gated on the predecessor's main CI green.
+
+| PR | Merge SHA | Fix commits added on branch |
+|----|-----------|------------------------------|
+| #103 | d7b0a3fb | — |
+| #96 | 93fd0897 | 94a1ce72 (inflation-time cap), 74202966 (SSRF DNS + reserved ranges) |
+| #97 | d55a1e3a | — (amended: gate returns enhanced in #99; see 030) |
+| #98 | 576d8c45 | — |
+| #99 | 44db2ec1 | a0257db2 (Debug.tsx resolution), 77efcaf7 (Usage.tsx abort guard) |
+| #100 | 464fd7d4 | — |
+| #101 | 5dadf6d8 | 910fcaca (GUI-gate contract test) |
+| #102 | 47072be3 | — |
+
+Evidence: full suite 2145 pass / 0 fail at WP5 tip; gui lint+build clean; typecheck exit 0;
+per-PR CI green at each tip; `dev` fast-forwarded to main (47072be3). Out-of-scope: dependabot
+PRs #105+ opened by #97's new dependabot.yml — left for the owner. Deferred nits: #102
+retry-exhaustion test, #98 adapter-level regression tests, #103 locale-time format.
+What did NOT happen (LOOP-PESSIMIST-01): dial-time DNS pinning/redirect validation
+(rebutted residual, loopback threat model); a #97 gate-restore commit (superseded by
+stack-internal #99 re-introduction — first plan draft had it wrong).

devlog/_plan/260712_pr_batch_landing/010_wp1_merge_103.md

@@ -0,0 +1,18 @@
+# WP1 — Merge PR #103 (debug log GUI wiring)
+
+Reviewer: MERGE, CI 6/6 green, non-draft, mergeState CLEAN. No code changes needed.
+
+## Steps
+
+1. `gh pr merge 103 --merge` (merge commit, repo precedent).
+2. Verify: `gh pr view 103 --json state,mergedAt` shows MERGED.
+3. `git fetch origin main` — confirm `aa888074` reachable from origin/main.
+
+## Accept criteria
+
+- c1: `gh pr view 103` state MERGED.
+- Expected repository diff: merge commit of `aa888074` only (no local edits) —
+  merge-only WP (audit blocker 6 declaration).
+- Post-merge conflict map (verified via merge-tree, audit blocker 2): #96–#98 stay clean;
+  #99–#102 become CONFLICTING on `gui/src/pages/Debug.tsx` — planned resolution happens once
+  at WP5; do NOT attempt to fix it here.

devlog/_plan/260712_pr_batch_landing/020_wp2_pr96_security.md

@@ -0,0 +1,86 @@
+# WP2 — Land #96 with security fixes
+
+Base: fork branch `codex/harden-request-provider-security` (tip `cde614a1`). Fix commits go on
+this branch, pushed to the fork (maintainerCanModify), then `gh pr ready 96` + merge. If #103's
+merge made #96 CONFLICTING (management-api.ts), first `git merge origin/main` on the branch.
+
+## Fix 1 — bounded decompression (MODIFY `src/server/request-decompress.ts`)
+
+Current (branch): `Bun.zstdDecompressSync` / `Bun.gunzipSync` / `Bun.inflateSync` fully
+allocate, then `assertBodySizeWithinLimit` checks. Verified Bun 1.3.14 `node:zlib` sync fns
+enforce `maxOutputLength` during inflation (ERR_BUFFER_TOO_LARGE).
+
+Diff sketch:
+
+```ts
+import { gunzipSync, inflateSync, zstdDecompressSync } from "node:zlib";
+
+export function decodeRequestBody(raw, contentEncoding, maxBytes = MAX_DECOMPRESSED_BODY_BYTES) {
+  // identity path: assertBodySizeWithinLimit(raw, maxBytes)
+  const opts = { maxOutputLength: maxBytes };            // per-call, from the PARAM
+  try {
+    if (encoding === "zstd") decoded = zstdDecompressSync(compressed, opts);
+    else if (encoding === "gzip" || encoding === "x-gzip") decoded = gunzipSync(compressed, opts);
+    else if (encoding === "deflate") decoded = inflateSync(compressed, opts);
+    else throw new UnsupportedContentEncodingError(encoding);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === "ERR_BUFFER_TOO_LARGE") {
+      throw new DecompressedBodyTooLargeError(maxBytes); // PARAM, not constant
+    }
+    throw err;
+  }
+  return assertBodySizeWithinLimit(decoded, maxBytes);   // PARAM threaded through
+}
+```
+
+(`assertBodySizeWithinLimit` and `DecompressedBodyTooLargeError` gain the byte-limit parameter;
+re-audit blocker: options/error/assertion must all derive from the param, never the constant.)
+
+Activation test (MODIFY `tests/request-decompress.test.ts`) — audit blocker 4 fold-back:
+refactor `decodeRequestBody(raw, contentEncoding, maxBytes = MAX_DECOMPRESSED_BODY_BYTES)` so
+tests INJECT a small cap (e.g. 1024) and feed a ~64KB-inflating payload per codec
+(zstd/gzip/deflate) — cheap, deterministic, no giant buffers, and it activates the exact
+ERR_BUFFER_TOO_LARGE → DecompressedBodyTooLargeError path during inflation.
+
+## Fix 2 — SSRF hostname resolution + reserved ranges (MODIFY `src/lib/destination-policy.ts`)
+
+a) Extend `classifyIpv4` reserved/non-public ranges (after existing checks):
+
+```ts
+if (a === 192 && b === 0 && (o3 === 0 || o3 === 2)) return { kind: "private", detail: "reserved address" };
+if (a === 198 && (b === 18 || b === 19)) return { kind: "private", detail: "benchmark address" };
+if (a === 198 && b === 51 && o3 === 100) return { kind: "private", detail: "documentation address" };
+if (a === 203 && b === 0 && o3 === 113) return { kind: "private", detail: "documentation address" };
+if (a >= 224) return { kind: "private", detail: "multicast/reserved address" };
+```
+
+(destructure `const [a, b, o3] = octets`.)
+
+b) NEW async export `providerDestinationResolvedError(name, provider): Promise<string|null>` —
+for `kind === "hostname"` destinations, `dns.promises.lookup(hostname, { all: true, verbatim: true })`,
+classify every returned address with classifyIpv4/6; any non-public result → same error string
+contract as the sync path. DNS failure (ENOTFOUND etc.) → null (config-time advisory, do not
+hard-fail offline startup). Wiring (audit blocker 1 fold-back): the sync helper in
+`src/server/auth-cors.ts:155-171` stays sync; the AWAIT goes in the async management write
+handler at `src/server/management-api.ts:289-290` right after the existing sync check.
+`management-api.ts` overlaps #103 — therefore FIRST merge origin/main (which then contains
+#103's aa888074) into the #96 branch, THEN edit. `src/config.ts:147-173` is sync by design —
+no DNS there. Router hot path (`src/router.ts:84,114`) stays sync-literal-only — rationale in
+000 §Rebutted.
+
+Activation test (MODIFY `tests/*destination*` or the suite covering destination-policy): mock
+`node:dns` lookup (bun test `mock.module`) to return `127.0.0.1` / `10.0.0.5` for a hostname →
+expect error; `93.184.216.34` → expect null. Literal-range tests for each new reserved block.
+
+## Steps
+
+1. Branch from fork tip; `git merge origin/main` (brings #103, resolves management-api overlap
+   deterministically — expected clean for #96 per merge-tree); apply fixes;
+   `bun test tests/request-decompress.test.ts <dest-policy tests>` + full `bun test`.
+2. Push to fork branch; wait `gh pr checks 96 --watch`; `gh pr ready 96`; `gh pr merge 96 --merge`.
+
+## Accept criteria
+
+- c2: oversized compressed body rejected during inflation (test output) — no full allocation.
+- c3: hostname→private DNS result rejected at management write path; new reserved ranges classified (test output).
+- Full suite 0 fail on the branch before merge; PR checks green; #96 MERGED.

devlog/_plan/260712_pr_batch_landing/030_wp3_pr97_ci_gate.md

@@ -0,0 +1,30 @@
+# WP3 — Land #97 as-is (gate returns enhanced in #99) — AMENDED at WP3-P
+
+Base: fork branch `codex/strengthen-ci-release` (tip `c6af7f90`, contains #96 commits below).
+After #96 merges, this PR's effective diff = c6af7f90 only.
+
+## AMENDMENT (WP3-P discovery)
+
+Stack inspection shows `e8794d22` (#99) RE-ADDS the gate STRONGER — separate "GUI lint" +
+"GUI build" steps at the same location (verified:
+`git diff wibias/codex/strengthen-ci-release wibias/codex/gui-lint-remediation -- .github/workflows/ci.yml`).
+The #97 deletion is a stack-internal transition, not a permanent regression. Restoring the old
+step on #97 would only create an extra ci.yml conflict at WP5's already-manual merge.
+
+Decision: merge #97 AS-IS. The gate gap on main is bounded to this controlled landing window
+(only this batch lands between #97 and #99; both merges happen in this session). Final main
+state carries the ENHANCED gate. Reviewer's High blocker is satisfied at batch end; disposition
+recorded here + in the ledger. Guard against future silent gate removal moves to WP6: add an
+assertion to `tests/ci-workflows.test.ts` (owned by #101's branch) that ci.yml contains the
+GUI lint + GUI build steps.
+
+## Steps
+
+1. Wait main CI green for the #96 merge (rollback policy).
+2. `gh pr ready 97` → `gh pr merge 97 --merge` (branch is MERGEABLE/CLEAN, no local edits).
+
+## Accept criteria
+
+- c4 (final-state, verified at WP5 close + WP6): ci.yml on main contains GUI lint+build steps;
+  ci-workflows test asserts their presence (added at WP6).
+- #97 MERGED; checks green. Expected repository diff this WP: none (merge-only).

devlog/_plan/260712_pr_batch_landing/040_wp4_pr98_retry_refactor.md

@@ -0,0 +1,15 @@
+# WP4 — Land #98 (shared upstream retry/error refactor) as-is
+
+Reviewer: MERGE-WITH-NITS (behavior-equivalent; nit = adapter-level regression tests, deferred).
+No code changes. After #96+#97 merge, effective diff = `6bb3aecf` only.
+
+## Steps
+
+1. If GitHub reports conflicts post-predecessor-merges: merge origin/main into fork branch, push.
+2. Local check on branch tip: `bun test tests/upstream-retry.test.ts tests/upstream-http-error.test.ts` + full `bun test`.
+3. Checks green → `gh pr ready 98` → `gh pr merge 98 --merge`.
+
+## Accept criteria
+
+- c5: full suite 0 fail; #98 MERGED.
+- Expected repository diff: none beyond merging existing `6bb3aecf` (merge-only WP).

devlog/_plan/260712_pr_batch_landing/050_wp5_pr99_usage_guard.md

@@ -0,0 +1,82 @@
+# WP5 — Land #99 with Usage.tsx cancellation guard restored
+
+Base: fork branch `codex/gui-lint-remediation` (tip `e8794d22`). Reviewer blockers: stale
+response can overwrite newer state after the refactor dropped the `cancelled` guard.
+
+ALSO at this WP (audit blocker 2): `git merge origin/main` into the branch and resolve the
+known `gui/src/pages/Debug.tsx` conflict ONCE — combine #99's lint refactor with #103's
+injection-stream wiring (keep both: injection stream entries + lint-clean patterns). This
+resolution reaches main with #99's merge; #100–#102 then merge cleanly (verified 3-way logic:
+their own commits don't touch Debug.tsx).
+
+## Fix — AbortController (MODIFY `gui/src/pages/Usage.tsx`)
+
+Current (branch, ~:196):
+
+```tsx
+const fetchUsage = useCallback(async (nextRange: Range) => {
+  setLoading(true);
+  try {
+    const res = await fetch(`${apiBase}/api/usage?range=${nextRange}`);
+    if (!res.ok) throw new Error("fetch failed");
+    setData(await res.json() as UsageResponse);
+  } catch {
+    setData(null);
+  } finally {
+    setLoading(false);
+  }
+}, [apiBase]);
+
+useEffect(() => {
+  const timeout = window.setTimeout(() => { void fetchUsage(range); }, 0);
+  return () => window.clearTimeout(timeout);
+}, [fetchUsage, range]);
+```
+
+Replace with:
+
+```tsx
+const fetchUsage = useCallback(async (nextRange: Range, signal: AbortSignal) => {
+  setLoading(true);
+  try {
+    const res = await fetch(`${apiBase}/api/usage?range=${nextRange}`, { signal });
+    if (!res.ok) throw new Error("fetch failed");
+    const json = await res.json() as UsageResponse;
+    if (signal.aborted) return;
+    setData(json);
+  } catch {
+    if (signal.aborted) return; // stale request: a newer effect owns state now
+    setData(null);
+  } finally {
+    if (!signal.aborted) setLoading(false);
+  }
+}, [apiBase]);
+
+useEffect(() => {
+  const controller = new AbortController();
+  const timeout = window.setTimeout(() => { void fetchUsage(range, controller.signal); }, 0);
+  return () => { window.clearTimeout(timeout); controller.abort(); };
+}, [fetchUsage, range]);
+```
+
+Covers: range/apiBase change mid-flight AND unmount (abort → no setState).
+
+## Verification
+
+- `cd gui && bun run lint && bun run build` (repo's GUI gates; #99 is the lint PR, lint must stay clean).
+- No existing GUI unit-test harness expected — verify at build/lint level + reviewer-cited
+  behavior reasoning; if a gui test runner exists (check gui/package.json at B), add a
+  hook-level test; otherwise record C evidence as lint+build plus manual reasoning
+  (activation = abort path exercised by unmount in dev-mode double-effect, noted in commit msg).
+- Reviewer's Low finding (hash-sync via effect) — accepted as-is (observable but harmless),
+  recorded in 000 §Rebutted-adjacent; no change.
+
+## Steps
+
+1. Branch from fork tip; `git merge origin/main`; resolve Debug.tsx (see above); apply Usage.tsx
+   fix; `cd gui && bun run lint && bun run build`; full `bun test`.
+2. Push, checks green, `gh pr ready 99`, `gh pr merge 99 --merge`.
+
+## Accept criteria
+
+- c6: guard present on main (file:line) + gui lint/build output clean; #99 MERGED.

devlog/_plan/260712_pr_batch_landing/060_wp6_pr100_102_tests.md

@@ -0,0 +1,20 @@
+# WP6 — Land #100, #101, #102 (test stabilization + isolation + rename retry)
+
+All three reviewer-approved at focus-commit level; blockers were only "stack not yet merged",
+which WP2–WP5 resolve. After predecessors merge, each PR's effective diff = its own commit:
+`84d601f9` (fixtures), `37b4b2d6` (--isolate), `21e58b09` (Windows rename retry).
+
+## Steps (per PR, in order 100 → 101 → 102)
+
+1. If conflicted after predecessor merges: merge origin/main into fork branch, push.
+2. Local: full `bun test` at #102 tip (covers all three).
+3. `gh pr ready N` → checks green → `gh pr merge N --merge`.
+
+Nits deferred (recorded): #102 exhaustion-path test, #100 stale focus-commit metadata in PR body.
+
+## Accept criteria
+
+- c7: full suite 0 fail at final tip; #100/#101/#102 MERGED.
+- Expected repository diff: none beyond merging existing `84d601f9`/`37b4b2d6`/`21e58b09`
+  (merge-only WP; Debug.tsx conflicts already resolved on main by WP5 — expect clean merges,
+  verify mergeStateStatus per PR before merging).

devlog/_plan/260712_pr_batch_landing/070_wp7_closeout.md

@@ -0,0 +1,22 @@
+# WP7 — Closeout
+
+## Steps
+
+1. `gh pr list --state open` — confirm none of #96–#103 open.
+2. `gh run list --branch main --limit 3` — latest run green (CI runs on main push).
+3. Fast-forward dev: `git push origin origin/main:dev` (dev==main precedent, keeps flow intact).
+4. PR comments: each merged PR gets a short disposition comment naming the review fix folded in
+   (#96 security hardening amendments, #97 gate restore, #99 cancellation guard) so the fork
+   author sees what changed on their branch. Approved-as-is PRs need no comment beyond merge.
+5. Devlog: `_fin` holds decade-numbered feature units (100_*, 110_*...), while dated units
+   stay in `_plan` (precedent: 260710_codex_warmup_preview_release) — this unit STAYS in
+   `_plan`; append a DONE section to 000_plan.md with merge SHAs. Commit devlog updates to main.
+6. Goalplan: mark criteria met with captured evidence; `cxc loop validate` must pass (E8).
+
+Expected repository diff: devlog unit updates only (000 DONE section); everything else is
+PR-state/CI verification (merge-only closeout). Rollback policy: 000 §Rollback.
+
+## Accept criteria
+
+- c8: zero open batch PRs + disposition comments posted.
+- c9: latest main CI run success.