[WRONG BRANCH] release: promote 2.48.0 to main

devlog/_fin/260907_init_publication_guidance/010_implementation.md

@@ -0,0 +1,28 @@
+# Issue #3893: implementation plan
+
+Satisfy-spec work, triggered by issue #3893 and the request to implement separate draft PRs. Goal: actionable first-run publication diagnostics. Non-goals: changing file writes, permissions, replacement/cleanup guarantees, or adding a filesystem fallback. Stop after a verified draft PR; unresolved platform checks are reported, never marked passed. Escalate if resolving the issue requires weakening publication guarantees. This file records the plan and eventual evidence.
+
+Class C2: diagnostic propagation and user documentation. One independent branch from 522ce5f8c; no branch dependencies or orchestration state changes.
+
+File map:
+- MODIFY src/config/initialize.ts: add an optional hardeningFailed flag to constructor options; select a fixed privacy-safe permission diagnostic when hardening throws. Track the flag around the existing harden call only, and pass it in the existing error options. Append supported-location guidance to denied-link diagnostics. All I/O order and cleanup remain identical.
+- MODIFY tests/config/config-mutation-lock.test.ts: inject a harden failure and prove write/link never happen, target remains absent, no residue remains, and raw error details do not appear. Assert all five denied-link codes provide recovery guidance while retaining uncertain-publication state. Partial-write errors must not be mislabeled as permission failures.
+- MODIFY tests/service/init-eof.test.ts: use its existing child bootstrap seam to inject publication errors during the real CLI wizard; verify exit=1, diagnostics and residue warnings, no configuration/backup damage or integration prompts.
+- MODIFY docs-site/src/content/docs/getting-started/quickstart.md and structure/02_config-and-codex-home.md: explain supported locations, inspection before retry, separate permission and link failures, and fresh-install OPENCODEX_HOME examples. Existing translations reviewed for contradictions.
+
+Optional constructor input chain: created by the publication function; consumed by Error.message; no config serialization, migration, or persistent state. Existing constructor calls keep their meaning.
+
+Verification: focused config/init tests read the real publication and CLI code; typecheck includes src; privacy scan; required docs-site build. Baseline focused run: 35 pass, 3 skip, 2 fail (Windows file-symlink privilege: symlinkSync EPERM and dependent missing-residue assertion). No baseline failure will be hidden by changing tests. New regression checks must pass. Windows-native filesystem support remains bounded by the host.
+
+Audit: direct O_EXCL and replacement fallbacks rejected because they change complete-file/no-replace guarantees. Reuse the existing error and test seams; no new diagnostic module. Guidance never prints raw cause text or candidate bytes.
+
+## Verification before draft publication
+
+- `bun install --frozen-lockfile`: passed; lockfile unchanged.
+- New diagnostics were observed failing before implementation: 9 failures across the focused hardening/link/CLI fault cases. After implementation: 9 passed.
+- `bun test tests/config/config-mutation-lock.test.ts tests/service/init-eof.test.ts`: 38 passed, 3 skipped, 2 failed. The same two tests failed on unchanged 522ce5f8c: file-symlink creation is denied on this Windows host, and the swapped-symlink test then lacks its expected residue. New recovery tests pass; no skips or weakened assertions were added.
+- `bun run typecheck`: passed.
+- `bun run privacy:scan`: passed.
+- `cd docs-site; bun install --frozen-lockfile; bun run build`: passed, 425 pages. Translated quickstarts contain no conflicting recovery/fallback instructions.
+- CLI fault scenarios verify exit=1, distinct permission/link messages, uncertain-publication/residue warnings, backup preservation and no integration prompts. Partial-write errors keep the generic diagnostic.
+- No physical non-NTFS filesystem support is claimed. Maintainer review remains required; this is a draft handoff.

devlog/_fin/260908_b_track_quota_recovery_stack/000_plan.md

@@ -0,0 +1,69 @@
+# 000_plan.md — B트랙 대화 복구·quota 스택 배송
+
+## 목표
+#3889(만료된 forward continuation의 WebSocket 복구)과 #3934(자격증명 세대 기반 늦은 WS quota 차단)를
+원저자 기여를 보존한 수동 종속 브랜치 체인으로 재구성하고, 최종 tip 한 곳에서만 CI를 태워
+green이면 tip을 dev에 통합한다.
+
+## 제약 (사용자 지시)
+- 로컬 스위트 절대 실행 금지: bun run test / test:changed / typecheck / build / install 모두 NOT RUN.
+- 푸시는 `--no-verify`.
+- CI는 최종 tip에만 트리거한다. 하위 레이어에는 PR을 열지 않는다.
+- 원작 PR이 있으면 원저자를 Co-authored-by로 보존한다.
+- tip이 dev에 머지되는 순간 연결 이슈도 닫는다.
+
+## CI 트리거 계약 (근거)
+`.github/workflows/ci.yml`의 `on.pull_request`에는 base 브랜치 필터가 없다(주석에 stacked child PR을
+일부러 포함시켰다고 명시). 따라서 **PR을 여는 것 자체가 CI run을 만든다.**
+`push:`는 `branches: [main, preview, dev]`로 제한되므로 포크/작업 브랜치 푸시는 CI를 만들지 않는다.
+결론: 하위 레이어 L1은 **브랜치 푸시만** 하고 PR을 열지 않는다. tip L2에만 PR을 연다.
+
+## 의존성 정렬 (PHASE-SPLIT-01)
+효율이 아니라 의존 구조로 나눈다. 두 변경 모두 `src/server/responses/core.ts`를 만지므로
+같은 파일 위에서 순서를 가진 체인으로 쌓는다.
+
+- L1 = #3889 continuation 복구 (core.ts:3598 부근 오류 코드 계약)
+- L2 = #3934 WS quota 세대 펜싱 (core.ts:1004 부근 observer) — L1 위에 쌓는다
+
+텍스트 충돌은 없다(두 훅 사이 거리 약 2600줄). 체인 순서는 리뷰 단위 분리를 위한 것이다.
+
+## 파일 변경 맵
+### L1 (#3889, 원저자 ykvv / y2ambition-ai)
+- MODIFY `src/server/responses/core.ts` — 400 응답 코드를 `invalid_request_error` → `previous_response_not_found`,
+  메시지를 "전체 대화를 다시 보내라"로 변경. HTTP 상태와 인증 전 거부 위치는 유지.
+- MODIFY `tests/codex-integration/issue-702-expired-replay-state.test.ts` — 기존 HTTP 기대값의 code 갱신 +
+  expired/missing 두 모드의 WebSocket 재연결·전체 도구 이력 재전송 회귀 추가.
+- MODIFY `docs-site/src/content/docs/guides/codex-integration.md`, `.../ko/guides/codex-integration.md`
+
+### L2 (#3934, 원저자 luvs01)
+- MODIFY `src/server/responses/core.ts` — `codexWsQuotaObserver`에서 pool 자격증명 generation을 포착하고
+  `isCodexAccountGenerationLive`가 false면 늦게 도착한 quota 프레임을 무시.
+- MODIFY `tests/responses/responses-account-label.test.ts` — 교체된 자격증명의 늦은 quota가 지워진 상태를
+  되살리지 못하는 회귀 추가.
+
+## 범위 밖 (OUT)
+- `REPLAY_TTL_MS` 등 캐시 보존 기간 변경
+- 인증/자격증명 회전 정책 변경
+- main-pool writer 소유권 규칙 변경
+- B트랙 외 항목(#3906/#3886/#3922/#3917/#3900/#3896/#3924/#3930/#3890)
+
+## 검증자 (PLAN-VERIFIER-REAL-01)
+로컬 스위트가 금지되었으므로 **로컬 검증자는 NOT RUN으로 기록한다**. 유일한 실행 검증자는
+tip PR head SHA에 대한 hosted Cross-platform CI다. 관측 대상: 4 Linux shard, Windows,
+macOS lane, gates(typecheck/lint/privacy scan), packaging.
+- `gh api repos/lidge-jun/opencodex/actions/runs?head_sha=<tip>` → conclusion=success
+- 이 CI는 `src/**`와 `tests/**`를 changes 필터에 포함하므로 실제로 이번 변경 대상을 관측한다.
+
+## 수용 기준
+1. L1/L2 커밋 각각에 원저자 Co-authored-by 트레일러가 살아 있다.
+2. L1에는 PR이 없고 CI run도 없다. CI run은 tip 하나뿐이다.
+3. tip head SHA의 CI conclusion이 success다.
+4. 로컬 스위트 미실행, 푸시는 --no-verify.
+5. tip이 dev 조상이 되고, #3889/#3934가 정리되며 연결 이슈가 닫힌다.
+
+## 우회 경로 (PLAN-BYPASS-NAMED-01)
+- tier: E2 (hosted CI 게이트)
+- 실행 주체: GitHub Actions + maintainer 통합
+- 알려진 우회: admin 권한 보유자는 CI 미완료 상태에서도 머지 가능. 이 계획은 그러지 않는다.
+- 잔여 위험: 하위 레이어 L1은 자체 CI 없이 tip 누적 CI로만 증명된다. 사용자 지시에 따른 의도된 선택.
+- 문구 하향: 없음.

devlog/_fin/260908_b_track_quota_recovery_stack/010_phase1_l1_continuation_recovery.md

@@ -0,0 +1,56 @@
+# 010_phase1_l1_continuation_recovery.md — L1 (#3889) 브랜치 구성
+
+## 목적
+만료·부재한 forward continuation 상태를 Codex WebSocket 클라이언트가 스스로 복구할 수 있게,
+프록시가 돌려주는 400 오류의 코드를 클라이언트가 인식하는 `previous_response_not_found`로 바꾼다.
+
+## 브랜치
+`codex/b-stack-l1-continuation-recovery`, base = `origin/dev`.
+
+## 커밋 계약
+원저자 보존이 필수다. 체리픽으로 원 커밋의 author를 그대로 유지한다.
+
+```
+git cherry-pick -x e8d82a181ea0daa06c5111c09e0148475e45458f
+```
+
+체리픽은 원 커밋의 author(ykvv <229483879+y2ambition-ai@users.noreply.github.com>)를 보존한다.
+squash 병합 시 author가 소실될 수 있으므로 커밋 메시지에 트레일러도 추가한다:
+
+```
+Co-authored-by: ykvv <229483879+y2ambition-ai@users.noreply.github.com>
+```
+
+## 정확한 변경 (before → after)
+`src/server/responses/core.ts` 약 3598행:
+
+```diff
+   if (
+     hasUnexpandedPreviousResponse
+     && isCanonicalOpenAiForwardProvider(route.provider)
+   ) {
+     return formatErrorResponse(
+       400,
+-      "invalid_request_error",
+-      "OpenAI forward continuation state is unavailable or expired; start a new session instead of reusing this previous_response_id.",
++      "previous_response_not_found",
++      "OpenAI forward continuation state is unavailable or expired; resend the full conversation without previous_response_id.",
+     );
+   }
+```
+
+가드 위치(인증·어댑터·upstream I/O 이전)는 바뀌지 않는다. HTTP 상태 400도 유지한다.
+
+테스트: `tests/codex-integration/issue-702-expired-replay-state.test.ts`
+- 기존 HTTP 케이스: `code`를 `previous_response_not_found`로 갱신, `type`은 `invalid_request_error` 유지.
+- 신규: expired/missing 두 모드로 WebSocket 연결 → 거부 확인 → upstream 요청 0건 확인 →
+  재연결 후 전체 이력 재전송 → upstream 1건 + `previous_response_id` 없음 + 도구 호출/결과 쌍 보존.
+
+문서: `docs-site/src/content/docs/guides/codex-integration.md` 및 한국어 페이지에 복구 경계 문단 추가.
+
+## 검증
+로컬 스위트 NOT RUN(사용자 금지). 이 레이어는 PR을 열지 않으므로 자체 CI도 없다.
+증명은 L2 tip의 누적 CI가 담당한다.
+
+## 감사 반영
+서브에이전트 audit-3889의 결과에 따라 문서의 TTL 수치와 error type/code 매핑을 확정한다.

devlog/_fin/260908_b_track_quota_recovery_stack/020_phase2_l2_ws_quota_generation_fence.md

@@ -0,0 +1,54 @@
+# 020_phase2_l2_ws_quota_generation_fence.md — L2 (#3934) tip 레이어
+
+## 목적
+pool 자격증명이 교체된 뒤 이전 WebSocket 연결에서 늦게 도착한 quota 프레임이,
+새 자격증명을 위해 비워둔 quota 상태를 되살리지 못하게 막는다.
+
+## 브랜치
+`codex/b-stack-l2-ws-quota-generation`, base = `codex/b-stack-l1-continuation-recovery` (L1 위에 쌓음).
+이 브랜치가 스택의 tip이며, **PR은 여기에만 연다.**
+
+## 커밋 계약
+```
+git cherry-pick -x e5c01f44e9736baba5b3a993c7f489f6b60d5ddd
+```
+원저자 luvs01 <luvs01@hanmail.net> 보존 + `Co-authored-by: luvs01 <luvs01@hanmail.net>` 트레일러.
+
+## 정확한 변경 (before → after)
+`src/server/responses/core.ts` 약 1004행:
+
+```diff
++import { isCodexAccountGenerationLive } from "../../codex/account-store";
+
+ function codexWsQuotaObserver(authCtx, provider): CodexWsQuotaObserver | undefined {
+   if (!isCanonicalOpenAiForwardProvider(provider) || !usesCodexForwardPoolAuth(authCtx, provider)) return undefined;
+   const { accountId, writerGeneration } = authCtx;
++  const credentialGeneration = authCtx.kind === "pool" ? authCtx.generation : undefined;
+   const mainWriter = authCtx.kind === "main-pool" ? authCtx.mainQuotaWriter : undefined;
+-  return headers => applyCapturedCodexQuota(accountId, headers, writerGeneration, mainWriter);
++  return headers => {
++    if (credentialGeneration !== undefined && !isCodexAccountGenerationLive(accountId, credentialGeneration)) return;
++    applyCapturedCodexQuota(accountId, headers, writerGeneration, mainWriter);
++  };
+ }
+```
+
+`credentialGeneration === undefined`면 기존 동작을 그대로 유지한다(main-pool·비pool 경로 무변경).
+
+테스트: `tests/responses/responses-account-label.test.ts`
+- quota 10 전달 → 자격증명 교체 → quota clear → 옛 연결에서 quota 100 전달 → 최종 상태가 null인지 확인.
+
+## L1과의 관계
+같은 파일이지만 서로 다른 함수(약 2600줄 간격)라 텍스트 충돌이 없다.
+체인 순서는 리뷰 단위를 나누기 위한 것이며, L2 diff는 이 변경만 보여준다.
+
+## CI 계약
+`.github/workflows/ci.yml`의 `on.pull_request`는 base 필터가 없어 PR 생성 즉시 CI가 붙는다.
+따라서 L1에는 PR을 열지 않고, tip인 L2에만 PR을 연다 → CI run 정확히 1개.
+`changes` 필터가 `src/**`, `tests/**`, `docs-site` 외 경로를 보므로 이 변경 세트는 `ci=true`가 되어
+4개 Linux shard, Windows, macOS lane, gates가 모두 돈다.
+
+## 머지 후 처리
+- tip PR 머지 → `git merge-base --is-ancestor`로 dev 조상 확인
+- #3889, #3934: 내용이 dev에 들어갔으므로 원저자 크레딧을 명시하며 닫는다
+- 연결 이슈: dev 머지 시점에 닫는다 (PR base가 dev라 GitHub 자동 종료가 안 됨 — AGENTS.md 명시)

devlog/_fin/260908_b_track_quota_recovery_stack/030_outcome.md

@@ -0,0 +1,58 @@
+# 030_outcome.md — 배송 결과
+
+## 결과
+PR [#3937](https://github.com/lidge-jun/opencodex/pull/3937)이 `dev`에 머지되었다.
+머지 커밋 `ca381ea764cfbc63bec978f53eb58e96c00c0c64`, 2026-09-07T18:31:27Z.
+
+## 스택 구조 (실제)
+```
+dev 942c02873
+ └─ 7273a0d1f  docs(devlog): plan the B-track ...        [계획]
+     └─ 531753340  fix(responses): recover expired ...   [L1, author ykvv]
+         └─ a06bfa2f2  fix(codex): fence late WS quota   [L2 = tip, author luvs01]
+```
+L1에는 PR을 열지 않았다. tip에만 PR을 열어 CI를 1회 트리거했다.
+
+## CI 증거
+- tip `a06bfa2f2`: Cross-platform CI run 1건, conclusion=success, run_attempt=1
+  ([run 34149252860](https://github.com/lidge-jun/opencodex/actions/runs/34149252860)).
+  잡 21/21 완료, failure 0. Linux shard 4, macOS lane 2, gates, packaging, keyring, Docker smoke 포함.
+- 하위 레이어 `531753340`: workflow run **0건**. 브랜치 푸시가 CI를 만들지 않는다는 계약이 실측으로 확인됐다.
+- `enforce-target`은 동시성 그룹 충돌로 1차 시도가 취소되어, 대기 중이던 중복 run을 취소하고 재실행해 success를 받았다.
+
+## 검증 한계 (사실대로 기록)
+- **로컬 제품 스위트는 한 번도 실행하지 않았다** (`bun run test`/`test:changed`/`typecheck`/`build`/`install`: NOT RUN).
+  사용자 지시에 따른 것이며, hosted CI가 유일한 실행 검증자였다. 푸시는 전부 `--no-verify`.
+- tip SHA에 취소된 체크 2건이 남아 있다: `enforce-target`(101832157192, 옛 시도)과 `label`(101827844691).
+  같은 워크플로의 후속 시도가 success로 끝났고 failure는 0건이다. 체크 목록이 전부 깨끗하다고 말하면 사실이 아니다.
+- CI가 검증한 트리(tip)와 최종 dev 트리는 동일하지 않다. 머지 직전 별도 PR #3936(문서)이 먼저 착륙해
+  lifecycle 문서 5개가 차이로 남는다. `git diff --exit-code a06bfa2f2 ca381ea76 -- src tests`는 exit 0으로,
+  **소스와 테스트는 CI가 본 그대로** 착륙했다.
+
+## 감사 (astra-high 서브에이전트 4기)
+1. `audit-3889`: PASS. `formatErrorResponse`의 2번째 인자는 `classifyError` 입력이며
+   `previous_response_not_found` 분기가 `type=invalid_request_error`/`code=previous_response_not_found`를 만든다
+   (`src/bridge.ts:2130`, `src/lib/errors.ts:179`). 문서의 1시간은 `RESPONSE_TTL_MS=3_600_000`과 일치.
+2. `audit-3934`: PASS. `main-pool`에 `generation`이 없는 것은 의도된 분리이며 `mainQuotaWriter`가 별도 펜싱한다.
+   `writerGeneration`(설정 재조정)과 `generation`(영속 자격증명)은 다른 개념이라 새 검사가 중복이 아니다.
+   generation `0`은 엄격 동등으로 정상 처리된다.
+3. `verify-stack`: PASS. 체리픽 hunk 무결성, 두 변경의 공존, import/export, 테스트 심볼, layout, privacy 6항목.
+4. `verify-landing`: 7개 주장 중 6개 CONFIRMED, 1개 REFUTED(위 취소 체크 건). 이 문서가 그 반증을 반영한다.
+
+## 원저자 크레딧
+머지 커밋에 두 트레일러가 모두 살아 있다.
+```
+Co-authored-by: ykvv <229483879+y2ambition-ai@users.noreply.github.com>
+Co-authored-by: luvs01 <luvs01@hanmail.net>
+```
+원본 PR #3889·#3934는 배송 완료 안내와 함께 closed(미머지)로 처리했다.
+
+## 연결 이슈
+GraphQL `closingIssuesReferences`로 확인한 결과 #3889·#3934·#3937 모두 종료 대상 이슈가 **0건**이다.
+따라서 이번 머지로 닫을 이슈는 없었다. (#3885는 A트랙 #3886 소관이라 대상이 아니다.)
+
+## 이번에 나아지지 않은 것
+- 하위 레이어 L1은 자체 CI 증거 없이 tip 누적 CI로만 증명됐다. 사용자 지시에 따른 의도된 선택이며,
+  레이어별 독립 회귀 증거가 필요한 변경에는 이 방식을 그대로 쓰면 안 된다.
+- `enforce-target` 동시성 충돌은 재실행으로 우회했을 뿐 원인을 고치지 않았다.
+  같은 SHA에 워크플로가 두 번 트리거되는 조건이 남아 있다.

devlog/_fin/260908_bug6_manual_stack/000_plan.md

@@ -0,0 +1,18 @@
+# Six-item bug stack — completed delivery
+
+All five new product PRs merged into `dev` on 2026-09-08. The sixth source item, #3965, had independently landed and required no duplicate PR. [071](071_delivery.md) records verification and retained failure history; [072](072_final_proof.md) records actual landing proof.
+
+| Source | Delivery | Disposition |
+| --- | --- | --- |
+| #3838 Go placement/stateless residual | #3986 | Landed; source closed; lossy mixed-ciphertext filtering declined |
+| #3907 xAI string child result | #3991 | Landed; issue completed |
+| #3944 V2 proxy guidance | #3992 | Landed; source closed |
+| #3951 server-owned delegation preset | #3993 | Landed; source closed |
+| #3965 canonical operation alias | Existing merge402be7c1f | Verified landed NOOP for another PR |
+| #3973 cooldown recovery, consolidated #3995 | #4002 | Landed; issue completed and source PR closed |
+
+This was one ordinary manual chain. Children were retargeted to dev before their parents merged because repository settings automatically delete merged branches. Original authorship and Co-authored-by trailers were preserved. #3997/#3996 remain outside this delivery.
+
+The earlier decade documents are historical plans and audit amendments. Their future-tense steps describe what was required at that point; this outcome and the final ledger are authoritative for completion. The work used repeated PABCD cycles and independent Astra high source/security reviews.
+
+Local product tests, installs, typechecks and builds: **NOT RUN**, by owner instruction. Commits disabled hooks per invocation and pushes used --no-verify. Hosted CI, synthetic dashboard observation and isolated remote documentation builds supplied verification. No release, deployment, main/preview promotion, live account operation or reset credit was used. All 30 pre-existing user files were preserved.