Plan Codex Lab home and repo dotdir boundary before Code Bridge #59

Current Status

Updated 2026-06-14 by Code.

State: Active boundary-planning issue before Code Bridge. The previous framing, ~/.code config cutover before Code Bridge, is obsolete. The agreed direction is now a Codex Lab home and repo-dotdir boundary:

• ~/.code remains Code / Every Code operator state. CODE_HOME may be set and used by those tools, but Codex Lab must not consume it as a home selector.
• CODEX_HOME may be set for upstream Codex or compatibility tooling, but Codex Lab must not consume it as a home selector.
• ~/.codex-lab is the canonical Codex Lab user home, selected only by CODEX_LAB_HOME or used as the default when CODEX_LAB_HOME is unset.
• Repo .codex/ remains the project-owned tracked metadata/config namespace. It should be safe to review and commit, and Codex Lab should own .codex/.gitignore to prevent runtime/private bleed-in.
• Repo .code/ is private operator/runtime scratch. It is not durable plan state, not a Codex Lab config source, and cleanup is deferred until after Codex Lab migration is complete enough to know nothing active depends on it.

Manual migration scope:

• Perform any Every Code home migration from ~/.code to ~/.codex-lab manually, one item at a time.
• Candidate manual migration items are selected non-secret config, product-appropriate preferences, and skills linkage such as making both homes point at the shared skills source.
• Do not blindly copy auth material. auth.json, .credentials.json, OAuth/token files, API keys, private keys, shell env backups, sessions, histories, transcripts, logs, caches, bridge state, plugin runtime data, and unknown files are excluded from blind copy. Codex Lab auth should be re-established or handled by an explicit manual decision.

Repo evidence:

• Current repo .codex/ contains tracked environments and skills, which fits the repo-owned metadata rule.
• Current repo .code/ contains ignored agent/runtime output and should be treated as private scratch.
• The global ignore already ignores **/.code/ and Codex runtime leaves, but repo-level guardrails are still useful because global ignores are per-user.

Next implementation shape after this plan update:

1. Make a small guardrails PR for repo-level .code/ ignore coverage and Codex Lab-owned .codex/.gitignore.
2. Triage the current external-agent lifecycle auto-review P1s before relying heavily on the external-agent dogfood path.
3. Implement the Codex Lab home resolver / launch behavior for CODEX_LAB_HOME and ~/.codex-lab in a separate slice.
4. Only after the migration is verified, decide whether to archive or delete existing repo .code/ contents.

Finish Line

Codex Lab has an agreed and implementation-ready home/config boundary before Code Bridge work resumes:

• Codex Lab's canonical user home is ~/.codex-lab.
• CODEX_LAB_HOME is the only external environment variable that selects the Codex Lab home; when unset, Codex Lab defaults to ~/.codex-lab.
• CODE_HOME and CODEX_HOME may exist for Code / Every Code, upstream Codex, or compatibility tooling, but Codex Lab does not consult them for home selection.
• Repo-local .codex/ is Codex Lab-owned project metadata/config, like JetBrains .idea/: tracked, reviewed, and repo-owned only.
• Codex Lab owns .codex/.gitignore so runtime, private, generated, and machine-local files do not bleed into the repo-owned .codex/ namespace.
• Repo-local .code/ is private operator/runtime scratch, not durable state and not a Codex Lab config source; existing cleanup is deferred until after Codex Lab migration is complete enough to know nothing active depends on it.
• Manual one-time migration from ~/.code to ~/.codex-lab is documented as an item-by-item checklist for selected non-secret config and skills linkage. Auth is re-established or manually handled, never blindly copied.
• Code Bridge remains sequenced after this issue so bridge state starts from the settled Codex Lab home boundary.

Acceptance Criteria

• Replace the obsolete ~/.code cutover framing with the Codex Lab home and repo dotdir boundary framing.
• Define CODEX_LAB_HOME as the only Codex Lab home selector, defaulting to ~/.codex-lab when unset.
• State that CODE_HOME and CODEX_HOME may be present for other tools, but Codex Lab must not use them to choose its user home.
• Record repo-local .codex/ as repo-owned, tracked, reviewable project metadata/config only; no sessions, logs, auth, caches, temp files, agent outputs, private local config, migration markers, or machine-specific runtime state belong there.
• Add or plan Codex Lab-owned .codex/.gitignore guardrails without hiding intended tracked skills, environments, or future repo-owned metadata.
• Add or plan repo-level .code/ ignore coverage as a backstop because repo .code/ contains private operator/runtime scratch and global ignores are not shared across contributors.
• Define the manual one-time migration checklist from ~/.code to ~/.codex-lab, limited to selected non-secret config and skills linkage.
• Explicitly exclude auth.json, .credentials.json, OAuth/token files, private keys, shell env backups, sessions, histories, transcripts, logs, caches, agent outputs, bridge state, plugin runtime data, and unknown ownership files from blind copy.
• Require re-authentication or explicit manual auth handling for Codex Lab; do not add an automatic importer or auth copier.
• Identify existing scripts/docs that still imply CODE_HOME or CODEX_HOME fallback for Codex Lab behavior, including scripts/local/exec-harness-env.sh, and classify each as legacy/tooling cleanup or implementation work.
• Leave existing repo .code/ contents untouched until after the migration is verified, then handle cleanup/archive/delete as a separate explicit step.
• Leave Code Bridge until after this boundary is settled.

Relationships

Child of #53. Follows native Auto Review and native third-party agent dogfood path. Precedes Code Bridge work (#45-#50).