fix(codex-shim): name the path and chmod fix when a private shim artifact is group-writable

[sungyongcho]

Summary

ocx codex-shim install refuses to migrate a legacy in-place Unix shim when ~/.opencodex/codex-shim.json is group- or world-writable. Older releases wrote that file with the process umask, so a umask of 002 (the Ubuntu desktop default) left it at 0664. The refusal said only "Private Codex artifact is not an owned regular file". It named neither the file nor the reason, while ocx codex-shim status kept advising the same ocx codex-shim install.

The trust check in snapshot() is unchanged. Its refusal now names the path and the failed condition: not a regular file, owned by another uid, or group/world-writable with its mode. For the writable case it also gives the exact fix, for example:

Private Codex artifact is not an owned regular file: /home/u/.opencodex/codex-shim.json is group- or world-writable (mode 0664); run chmod 600 '/home/u/.opencodex/codex-shim.json' and retry

OpenCodex deliberately does not loosen the check or chmod the file itself. The CLI reference documents the refusal next to the legacy-migration paragraph.

Refs #6668. This delivers the "at minimum" outcome listed in the issue. Automatic tightening of the legacy state file is left to maintainers' judgement, because it would relax a trust boundary.

Verification

• bun run typecheck: pass
• bun run structure:check: pass
• bun run privacy:scan: pass
• New case in tests/codex-integration/codex-shim-migration.test.ts. A 0664 legacy state file refuses with the path, the mode and the chmod hint, and leaves the state and the legacy wrapper untouched. After chmod 600, migration commits schema 2. The case fails without the source change.
• bun test tests/codex-integration/codex-shim* plus tests/ci-workflows/skill-ocx-generated.test.ts and tests/ci-workflows/file-size-ratchet.test.ts, with umask 022 and no proxy env vars: all pass. With the machine's umask 002, 7 shim tests fail identically on unchanged dev. Their fixtures create private homes that inherit the umask.
• Reproduced end to end on a real machine (2.78.0 .deb): the refusal, then chmod 600 and a successful migration.
• I did not run the full bun run test locally (memory limits on this machine). I'm leaving it to CI.

Maintainer sweep refresh (head 159d4f7704)

Refreshed by the maintainer compat sweep (lane D): merged origin/dev 38455fb245 into the branch (no force-push) and added 159d4f7704:

• The lifecycle reference now says chmod 600 clears only the group/world-writable refusal; symlink and foreign-owner refusals remain.
• tests/codex-integration/codex-shim-migration.test.ts runs the printed hint through /bin/sh for a state path containing a space and an apostrophe, then checks mode 0600 and the schema-2 migration.
• structure/runtime.md names the refusal contract and its test.

Commands on this head: bun test tests/codex-integration/codex-shim-migration.test.ts 23 pass / 0 fail; bun test tests/test-layout.test.ts tests/test-layout-tooling.test.ts tests/ci-workflows/file-size-ratchet.test.ts 27 pass / 0 fail; bun run typecheck exit 0; bun run structure:check pass; docs-site bun run build pass. An independent review re-ran 92 related tests (0 fail) and confirmed the new assertions fail against the old refusal. The full local suite was not run because parallel lanes share this machine; the rest is left to hosted CI on this head.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed. (reference/cli/lifecycle.md)
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. (The check is unchanged; only the message is new. The message carries the local path, not file contents.)

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• Bug Fixes
  • Unix Codex shim migration now refuses to proceed if its state file is group- or world-writable, in addition to existing checks for symlinks, non-regular files, and files owned by another user.
  • The refusal message identifies the file and its permissions and provides a chmod 600 command. OpenCodex does not change the file’s permissions; migration can proceed after you correct them.

[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: 6351f859-0ba4-4ff1-a624-3a477aa2479f

📥 Commits

Reviewing files that changed from the base of the PR and between 38455fb and 159d4f7.

📒 Files selected for processing (4)

• docs-site/src/content/docs/reference/cli/lifecycle.md
• src/codex/shim-overlay.ts
• structure/runtime.md
• tests/codex-integration/codex-shim-migration.test.ts

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

---

📝 Walkthrough

Walkthrough

Unix shim migration now reports which trust check failed for an artifact. Integration tests cover writable state-file refusal, safely quoted chmod 600 hints, and successful migration after correcting permissions.

Changes

Unix shim migration

Layer / File(s)

Summary

Trust errors and migration tests src/codex/shim-overlay.ts, tests/codex-integration/codex-shim-migration.test.ts, docs-site/src/content/docs/reference/cli/lifecycle.md, structure/runtime.md

Artifact errors identify non-regular files or symlinks, mismatched ownership, and group- or world-writable permissions. Writable-file errors include the observed mode and a chmod 600 hint. Tests verify refusal without changing the state file or shim, successful migration after permission correction, and safe quoting for paths with spaces and apostrophes. The CLI and runtime documentation describe the checks and hint.

Priority: ⬇️ Low

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

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 159d4

The migration hint safely quotes paths and does not weaken the existing refusal checks. No actionable merge risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: the group-writable shim-artifact refusal now names the path and recommends a chmod fix.

Full details: Docstring Coverage

Explanation

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

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · 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.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

✅ READY

• all PR quality gates passed; the review readiness checklist is complete.

Review readiness checklist

• ✅ Required local validation passed; commands, results, and any full-suite exception are documented.
• ✅ I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
• ✅ I resolved all correct Codex and CodeRabbit findings.
• ✅ My PR is ready for review.

✅ 4/4 boxes ticked.

This pull request has been marked Ready for Review.
The review-ready label marks this PR as ready; review automation runs independently.
Maintainers notified: @lidge-jun @Ingwannu

[lidge-jun]

Maintainer integration into dev (MAINTAINERS.md dev-only maintainer integration; not a self-approval or an independent review).

• Exact head: 159d4f7704ba5138a5fbafc98eaec82e02dca231
• Hosted CI on that head: all 38 latest check runs completed and every applicable one succeeded. Skipped jobs are gated off by their own path/event conditions.
• fix(codex-shim): name the path and chmod fix when a private shim artifact is group-writable #6680, fix(service): credit Linux desktop Start at Login as restart protection in doctor #6679 and fix(lifecycle): retryable restart-drain code and quiet journal no-op recovery #6686 share structure/runtime.md, and fix(service): credit Linux desktop Start at Login as restart protection in doctor #6679/fix(lifecycle): retryable restart-drain code and quiet journal no-op recovery #6686 also share scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json and structure/ops/service-and-sidecars.md. The coordinator merged all three onto dev origin/dev in this order in a scratch worktree: clean auto-merge, layout.json at 1998 lines, and on that exact union tree bun test of the layout/tooling/file-size-ratchet guards (27 pass) and of the three PRs' changed test files (86 pass), bun run structure:check and bun x tsc --noEmit all passed.
• Review: independent gpt-6.1-sol review in the compat sweep lane (PASS); no unresolved review threads, no maintainer change requests.
• Scope: codex-shim install names the legacy state file, the failing permission condition and a shell-quoted chmod 600 fix when a private shim artifact is group-writable (refs [Bug][Linux] codex-shim install cannot migrate a legacy shim whose codex-shim.json was written group-writable (umask 002) #6668); no gui/ paths.
• Full local suite not run (parallel lanes share one machine); the dev push CI after this merge is the remaining check.