Skip to content

fix(container): persist Codex home separately - #3788

Merged
lidge-jun merged 8 commits into
devfrom
codex/track3-container-codex-home-a4b0
Sep 6, 2026
Merged

fix(container): persist Codex home separately#3788
lidge-jun merged 8 commits into
devfrom
codex/track3-container-codex-home-a4b0

Conversation

@lidge-jun

@lidge-jun lidge-jun commented Sep 6, 2026

Copy link
Copy Markdown
Owner

Summary

Track 3 manual stack, layer 2. Depends on #3786; this PR's base is its parent branch. No native stack registration.

Verification

  • Independent Astra high plan audit and separate main implementation/security review: PASS, no blockers.
  • git diff --cached --check passed. No local suites, typecheck, build or Docker run were performed, per explicit maintainer instruction.
  • Runtime validation: the cumulative exact-source CI evidence is recorded below; lower-layer tests are deferred under the explicit maintainer policy.
  • The regressions inspect actual deployment declarations and real catalog resolution in isolated child processes. Actual image build/mount enforcement/container recreation remain unverified; these tests do not prove them. Documentation build has not been run locally.

Cumulative tested source: 9ea896737bd17085ebb8a69b3320c9cace61889e, based on dev eff908e0fb9452d5ff2952af1c5dafc1c4c35dd9.

  • Cross-platform CI: all 25 jobs successful. Attempt 1 failed only the existing Windows cli-models first-child 15-second watchdog. One unchanged-head rerun of that shard completed 3,489 cases (3,465 pass, 24 skip, 0 fail); the first models case took 943 ms. The initial failure is retained; the slow phase remains unproven and no flakiness fix is claimed.
  • Service lifecycle: Linux, macOS and Windows passed on the same source head.
  • Documentation build: passed after checking out and asserting that exact source. Its isolated workflow-definition commit is different and is not part of this stack; no deployment occurred.
  • Independent scoped code/security and integration reviews: PASS. The two earlier Windows fixture-budget changes retain production behavior and original assertions, backed by readiness controls and quota restart controls. Diagnostic workflows, instrumentation and mutations are excluded from delivery.

The maintainer explicitly authorizes dev admin integration and final-head-first validation for this manual chain: #3786#3788#3789#3790#3796#3802. Lower automatic tests are deferred with [skip ci], not represented as passing. No local tests, typecheck, builds or suites were run; pushes used --no-verify. Merge commits preserve source ancestry and suppress duplicate lower CI; fresh head/base/actor/review checks and resulting tree checks accompany each merge.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed.
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Co-authored-by: Ingwannu ingwannu@users.noreply.github.com

Landing confirmed: merged into dev as ad5285e415f76100be17e2a5f1039053f3cb3dc4. The final chain merge is f89b815090020f52089801b50f569a777bdfdc0a; its tree 846b8ffc383fc0ba99486917bdfb820a0fa432ba equals the tested cumulative source. Source ancestry and every merge were verified after fetching dev.

t and others added 2 commits September 7, 2026 01:45
Preserve complete recovery records across handled publication failures and keep existing partial-purge restoration boundaries. Refs #3778. Local checks deferred to final stack CI by maintainer instruction.
Carry #3747 for #3746 with isolated serializer regressions and explicit volume lifecycle documentation. Runtime image recreation remains unverified; final stack CI is pending.

Co-authored-by: Ingwannu <ingwannu@users.noreply.github.com>
@coderabbitai

coderabbitai Bot commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 2f83c782-3b61-48d4-8911-2afce78431ee

📥 Commits

Reviewing files that changed from the base of the PR and between eff908e and b6d3626.

📒 Files selected for processing (14)
  • Dockerfile
  • compose.yaml
  • docs-site/src/content/docs/fr/guides/remote-hub.md
  • docs-site/src/content/docs/guides/remote-hub.md
  • docs-site/src/content/docs/ja/guides/remote-hub.md
  • docs-site/src/content/docs/ko/guides/remote-hub.md
  • docs-site/src/content/docs/reference/management-api.md
  • docs-site/src/content/docs/ru/guides/remote-hub.md
  • docs-site/src/content/docs/tr/guides/remote-hub.md
  • docs-site/src/content/docs/zh-cn/guides/remote-hub.md
  • src/storage/cleanup.ts
  • structure/02_config-and-codex-home.md
  • tests/service/container-bootstrap.test.ts
  • tests/storage/storage-cleanup.test.ts

📝 Walkthrough

Walkthrough

The changes add persistent Codex Docker state and catalog coverage. They also replace direct cleanup writes with atomic publication and add failure-path tests and documentation.

Changes

Docker Codex persistence

Layer / File(s) Summary
Codex runtime and volume wiring
Dockerfile, compose.yaml, tests/service/container-bootstrap.test.ts
Docker and Compose set CODEX_HOME, create separate owner-only state, mount codex-state, and validate the deployment contract.
Catalog behavior and deployment guidance
tests/service/container-bootstrap.test.ts, docs-site/src/content/docs/guides/remote-hub.md, docs-site/src/content/docs/*/guides/remote-hub.md, structure/02_config-and-codex-home.md
Catalog lookup tests cover default and custom paths, malformed or missing catalogs, and authentication preservation. Documentation covers volume persistence, migration, rollback, catalog placement, and destructive volume removal.

Atomic cleanup publication

Layer / File(s) Summary
Atomic private-file publication
src/storage/cleanup.ts
writePrivateFile now uses exclusive temporary files, fsync, atomic replacement, parent-directory syncing, and cleanup. Satellite backups use the shared writer.
Manifest replacement hooks and recovery validation
src/storage/cleanup.ts, tests/storage/storage-cleanup.test.ts, structure/02_config-and-codex-home.md, docs-site/src/content/docs/reference/management-api.md
Manifest replacement hooks cover staging, pre-commit, and purge-incomplete phases. Tests verify prior-record retention, temporary-file cleanup, and restore behavior after failures. Documentation describes atomic publication and restore limits.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Hub
  participant CodexHome
  Client->>Hub: Authenticated GET /v1/catalog
  Hub->>CodexHome: Resolve and read opencodex-catalog.json
  CodexHome-->>Hub: Catalog bytes or missing catalog
  Hub-->>Client: Catalog response or catalog_not_found
Loading
sequenceDiagram
  participant Cleanup
  participant ManifestStore
  participant Restore
  Cleanup->>ManifestStore: Publish manifest through a temporary file
  ManifestStore-->>Cleanup: Replacement succeeds or fails
  Cleanup->>Restore: Restore using the retained complete manifest
  Restore-->>Cleanup: Restored files or fail-closed result
Loading
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/track3-container-codex-home-a4b0

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the bug Something isn't working label Sep 6, 2026
@lidge-jun

Copy link
Copy Markdown
Owner Author

리뷰 · 우선순위 62 / 80

현재 devcompose.yamlocx-state/home/bun/.opencodex에 붙이고, Dockerfile runtime도 OPENCODEX_HOME과 그 VOLUME만 준비합니다. CODEX_HOME은 이미지에 안 박혀 있고, Codex 홈용 named volume도 없습니다. read-only 루트 컨테이너에서는 /home/bun/.codex가 쓰기 가능·영속이지 않아서, /v1/catalog가 기대하는 opencodex-catalog.json이 컨테이너를 다시 만들면 사라지거나 아예 못 씁니다. 이슈 #3746이 그 증상입니다.

이 PR은 CODEX_HOME=/home/bun/.codex를 이미지·Compose에 명시하고, codex-state volume을 추가하며, bun 사용자용 owner-only 디렉터리를 둘 다 만듭니다. OCX 홈과 Codex 홈을 합치지 않습니다. 두 제품의 auth.json 형식이 달라서 합치면 위험합니다. 영문 remote-hub 가이드와 fr/ja/ko/ru/tr/zh-cn 번역, structure/02_config-and-codex-home.md Decision Log, tests/service/container-bootstrap.test.ts의 Compose/Dockerfile 계약 테스트까지 같이 갑니다. “카탈로그를 자동 생성하지 않는다”, “빈 홈의 catalog_not_found는 정상”, “docker compose down --volumes는 파괴적”을 여러 언어로 같은 뜻으로 적었습니다.

base는 #3786 브랜치(codex/track3-storage-manifests-a4b0)입니다. 같은 주제의 열린 PR #3747(ingw/fix-container-codex-volume, 역시 #3746)과 목표가 겹칩니다. Track 3 수동 스택을 밀 거면 이 층이 정본이 되고, #3747은 중복으로 닫는 쪽이 기여자 혼란을 줄입니다. types/config 분할과는 무관합니다. 런타임 프록시 로직보다 Docker 배포 계약 수정에 가깝지만, 허브 이미지 쓰는 사용자에게는 #3746이 바로 막히는 우선순위입니다.

compose.yaml - HEAD는 ocx-state만 있다. 이 PR의 codex-state + CODEX_HOME 매핑이 #3746 핵심 수정이다.
Dockerfile runtime ENV/VOLUME - HEAD에 CODEX_HOME/home/bun/.codex VOLUME이 없다. 이미지 시드 디렉터리와 Compose mount가 같이 있어야 기존 ocx-state가 이미지 시드를 가려도 Codex 홈이 산다.
docs guides/remote-hub.md (다국어) - 업그레이드 시 파일 자동 이전이 없다고 못 박은 점이 좋다. 예전 workaround로 .opencodex에 둔 카탈로그는 수동 복사 안내가 필요하다.
tests/service/container-bootstrap.test.ts - Compose YAML 파싱으로 두 홈·read_only 계약을 고정한다. 실제 docker compose up E2E는 이 테스트 범위 밖이다.
PR #3747 - 동일 #3746 수정의 다른 브랜치. Track 3을 택하면 #3747은 close-don't-rebase(중복)가 맞다.

메인테이너의 판단이 필요한 지점

  • Track 3 층으로 fix(storage): publish cleanup manifests atomically #3786 위에 올릴지, #3747과 내용 비교 후 하나만 남길지
  • 기존 배포가 카탈로그를 .opencodex에 둔 경우, 릴리즈 노트에 수동 이전 체크리스트를 넣을지
  • Compose 프로젝트 이름이 바뀌면 named volume이 갈라지는데, 그 경고를 CHANGELOG에도 반복할지

너의 추천
#3786 머지 전제 후 이 층을 이어서 머지. #3746을 닫는 정본으로 보고, 겹치는 #3747은 landed-via/superseded로 닫아라. 카탈로그 자동 생성은 범위 밖이니 기대치를 릴리즈 노트에 한 줄로 남기면 된다.

이 댓글은 grok-bot이 작성했습니다

@lidge-jun
lidge-jun changed the base branch from codex/track3-storage-manifests-a4b0 to dev September 6, 2026 20:19
@lidge-jun
lidge-jun marked this pull request as ready for review September 6, 2026 20:19
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner September 6, 2026 20:19
@lidge-jun
lidge-jun merged commit ad5285e into dev Sep 6, 2026
18 of 21 checks passed
@lidge-jun
lidge-jun deleted the codex/track3-container-codex-home-a4b0 branch September 6, 2026 20:19
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 6, 2026

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review Completed 2026-09-06T20:21:20.256245Z b6d3626 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant