fix(codex): avoid false doctor integrity failure on checkpointed WAL history

[lidge-jun]

Summary

• Fix the false Codex history integrity warning in ocx doctor when a healthy WAL-mode state_5.sqlite has no -wal or -shm files. The guardian's pending-history probe now reuses openCodexStateForPreflight, including its narrowly gated immutable fallback.
• Add a real checkpointed WAL database regression, plus deterministic constructor/first-read SQLITE_CANTOPEN coverage. Update the Codex-home contract and CLI diagnostics documentation.
• Closes [Bug]: ocx doctor reports a false history integrity failure when state_5.sqlite is WAL without -shm #7044.

Verification

• Before the fix: bun test tests/codex-integration/codex-history-pending-wal.test.ts — 0 pass, 3 fail; the real fixture reproduced failureReason: "integrity" on macOS.
• After the fix: bun test tests/codex-integration/codex-history-pending-wal.test.ts tests/codex-integration/codex-history-provider.test.ts tests/codex-integration/codex-coordinator-doctor.test.ts tests/test-layout.test.ts tests/test-layout-tooling.test.ts — 132 pass, 0 fail.
• bun test tests/ci-workflows/file-size-ratchet.test.ts — 9 pass, 0 fail. No cap increased.
• bun run typecheck — passed.
• bun run structure:check — passed.
• bun run privacy:scan — passed.
• In docs-site: bun install --frozen-lockfile and bun run build — passed; 569 pages and 79,403 internal links checked.
• bun run test:changed — failed: 37,389 pass, 107 skip, 22 fail, 4 errors across 1,697 files (358.6s after a 60s shared-lock wait). Failure groups: service ownership/SQLite-home/diagnostics, native Codex/Grok toggles, composed toggle acceptance, live audio closure, and a sibling ensure subprocess timeout. This run is not claimed green.
• Isolated follow-up: bun test tests/service/service-sqlite-home.test.ts tests/service/service-ownership-state.test.ts tests/service/service.test.ts tests/codex-integration/native-grok-toggle.test.ts tests/codex-integration/native-codex-toggle.test.ts tests/codex-integration/codex-composed-acceptance.test.ts tests/cli/cli-access-audio-live.test.ts tests/cli/sibling-home-client-sync.test.ts — 376 pass, 1 fail, 1 error across 8 files. Only the sibling ensure 30s timeout remains; the other broad-run failures did not reproduce in this smaller run.
• Baseline check with the original origin/dev history-provider implementation temporarily restored: bun test tests/cli/sibling-home-client-sync.test.ts -t 'a secondary ensure parent preserves shared Grok, Codex and Claude agent bytes' — reproduces the same 30s timeout (0 pass, 1 fail, 1 error, 32 filtered out). The fixed source was restored afterward and the worktree is clean.
• Baseline service/toggle subset with the original opener: bun test tests/service/service-sqlite-home.test.ts tests/service/service-ownership-state.test.ts tests/codex-integration/native-grok-toggle.test.ts tests/codex-integration/native-codex-toggle.test.ts — 89 pass, 0 fail.
• Full local suite omitted because multiple triage worktrees are validating concurrently. Focused behavior, existing integrity checks, and layout/size guards were run explicitly; the changed-test result and its limitations are recorded above; PR CI provides the broader validation.
• Risk: the existing fallback is used only for SQLITE_CANTOPEN when both sidecars are absent. Live-WAL reads and manifest/restore-target integrity validation retain their existing behavior. No GUI, authentication, credential, or dependency changes.

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. No security boundary changes; privacy scan passed.

[chatgpt-codex-connector]

Codex Review Summary

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

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T15:33:19.280020Z	c8c3245	PR opened

ℹ️ 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.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: d8ec58aa-bf3e-4109-9df5-0c68baf0190d

📥 Commits

Reviewing files that changed from the base of the PR and between f5f73ff and c8c3245.

📒 Files selected for processing (6)

• docs-site/src/content/docs/reference/cli/lifecycle.md
• scripts/test-layout/layout.json
• src/codex/history-provider.ts
• structure/codex-home.md
• tests/codex-integration/codex-history-pending-wal.test.ts
• tests/fixtures/test-layout-expected.json

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📝 Walkthrough

The pending-history probe now uses the shared preflight opener for Codex state databases. Integration tests cover checkpointed WAL databases without sidecars and injected SQLite open and read failures. Documentation describes the sidecar behavior and the integrity checks that still apply to backup manifests and restore targets.

Changes: History preflight

Layer / File(s)	Summary
Use the preflight opener and verify sidecar-free WAL handling src/codex/history-provider.ts, tests/codex-integration/codex-history-pending-wal.test.ts, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json, docs-site/src/content/docs/reference/cli/lifecycle.md, structure/codex-home.md	countPendingOpencodexHistory now uses openCodexStateForPreflight. Integration tests verify zero pending rows and backup entries for a checkpointed WAL database without sidecars, including injected open and first-read failures. Test-layout mappings and documentation are updated.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to c8c32

The WAL compatibility change has no identified issue requiring resolution before merge; normal checks remain appropriate.

Pre-merge checks · 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (4 skipped: 4…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Issue #7044 requires ocx doctor to avoid a false history-integrity failure for a healthy checkpointed WAL state_5.sqlite with no -wal or -shm sidecars. In src/codex/history-provider.ts, `cou…
Out of Scope Changes check		The reported changes stay within issue #7044. The new integration test and test-only failure hook validate the required fallback behavior. The scripts/test-layout/layout.json and `tests/fixtures/tes…
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title accurately summarizes the primary change: preventing a false ocx doctor integrity failure for checkpointed WAL history without sidecar files. It is concise, specific, and clearly related t…

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (4 skipped: 4 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[lidge-jun]

Maintainer integration record (MAINTAINERS.md dev exception): squash-merged into dev by @lidge-jun without a second maintainer approval as part of the 2026-10-14 triage. Exact-head verification: every required check on head c8c324532bed0338d52641aff0092db61ff2d1b3 completed successfully (typecheck, test shards 1–4, gates, structure gate, hygiene, enforce-target, docs build, storage policy, api usage, docker smoke, npm-global ubuntu, keyring ubuntu; macOS/Windows jobs skipped per the PR CI policy). The merge was pinned to that head with --match-head-commit. No outstanding maintainer change requests. Low-risk, non-UI bug fix with a focused regression test.