cxc-worktree-guardian

# Worktree Guardian — Codex-app managed worktrees The Codex desktop app creates one worktree per thread under `$CODEX_HOME/worktrees/` (hash or date-slug slot dirs, e.g. `~/.codex/worktrees/7627/opencodex`), checked out from the selected base branch, usually **detached HEAD**. These sessions look like scratch directories but are not: the app binds the thread to that directory. ## 1. Three namespaces (WG-CONCEPT-01) | Namespace | What it is | How to rename | |-----------|-----------|---------------| | branch | a git ref | `git branch -m <name>` (or `git switch -c <name>` from detached HEAD), run inside the worktree | | worktree | a directory + its `.git/worktrees/<id>` admin entry | `git worktree move <old> <new>` — never for the ACTIVE one (WG-MOVE-01) | | thread title | the Codex app sidebar entry | the user renames it in the app; agents cannot | "워크트리 이름 붙여줘 / name the worktree" can mean any of these. Default: name the branch in place and tell the user to rename the thread in the app. ## 2. Managed-worktree facts (WG-FACTS-01) - Root: `$CODEX_HOME/worktrees` (default `~/.codex/worktrees`); the app setting can move it (Settings → Worktrees) — codexclaw detection then needs `CODEXCLAW_WORKTREE_ROOTS` (WG-LIMIT-01). - Managed worktrees are per-chat disposable; the app retains the latest N (15 by default) and **auto-deletes the worktree when the chat is archived** (a snapshot is kept for restore). Commit early. - Source: developers.openai.com/codex/environments/git-worktrees; identity fragility is a known upstream area (openai/codex issues #10917, #10522, #14498, #34662; naming contract still a proposal, #12862). **One worktree per THREAD, not per agent (WG-FACTS-02).** The per-chat worktree belongs to the Codex task. A subagent spawned with `spawn_agent` inherits this same directory: same path, same branch, same HEAD, and its writes appear in this worktree's `git status`. It never gets a worktree of its own, so spawning agents is not a way to parallelize branch work — that needs one task per lane, each with its own worktree. See [Dispatch surfaces](../pabcd/references/dispatch-surfaces.md). ## 3. Never-list (WG-NEVER-01) - Never `git worktree remove` or `rm -rf` the session's OWN worktree, slot dir, or any ancestor of cwd — not even to "start clean". codexclaw's PreToolUse guard (WORKTREE-GUARD-03) denies it; do not try to bypass the deny. - Never copy the work elsewhere and delete the original — that loses the app binding and any uncommitted state you missed. - Never delete another slot under `~/.codex/worktrees` without the user explicitly naming that path — another live session may be bound to it. ## 4. Safe procedures (WG-PROC-*) **Adopt-and-continue (DEFAULT for "이름 붙이고 새로 시작"):** 1. Stay in the worktree. `git switch -c <name>` (detached HEAD) or `git branch -m <name>`. 2. Commit the work in progress (archive auto-deletes managed worktrees). 3. Tell the user the thread title can be renamed in the app sidebar. **Move/repair — OTHER, inactive worktrees only (WG-MOVE-01):** `git worktree move <old> <new>` (refuses the main worktree, locked worktrees, and worktrees containing submodules). After a manual directory move: `git worktree repair <new-path>`. Feature-detect with `git worktree move -h` / `git worktree repair -h`; do not version-gate. Moving the ACTIVE worktree kills the session's cwd (next command: ENOENT) and app rebinding is undocumented — don't. **Cleanup of other worktrees:** verify clean (`git status`), merged (`git merge-base --is-ancestor`), no open PR head, not any session's cwd; then `git worktree remove <path>` — never `rm -rf`. A directory deleted without `git worktree remove` leaves admin state under `.git/worktrees/`; recover with `git worktree prune` (dry-run first). Automated or bulk cleanup of other worktrees follows `cxc-dev-devops` `references/local-gc.md` (DEVOPS-LOCAL-GC-01); the never-list above still wins. ## 5. Defense-in-depth limits (WG-LIMIT-01) - The PreToolUse guard matches literal paths. Pure variable/glob indirection that never mentions the slot path is out of scope — treat the deny as a seatbelt, not a sandbox. - Detection covers the default root + `CODEX_HOME` + `CODEXCLAW_WORKTREE_ROOTS` (path.delimiter-separated). A custom app-side root needs that env. ## 6. Hook interplay (WG-HOOK-01) - WORKTREE-GUARD-01 (SessionStart): identity block when cwd is managed. - WORKTREE-GUARD-02 (UserPromptSubmit): this guidance, once per session, on rename intent. - WORKTREE-GUARD-03 (PreToolUse, `^Bash$`): deterministic deny of self-worktree deletion — applies to subagent turns too. The deny is intentional; follow §4 instead of routing around it. - WORKTREE-GUARD-04 (same PreToolUse hook): when the session bound a source worktree with `cxc session source`, git writes (commit, cherry-pick, merge, rebase, reset, checkout/switch, am, revert, push, pull, branch -D/-f/-m) whose repository is another worktree of the same repo are denied. Hooks receive only the command text, never exec_command's `workdir`, so write `git -C <source> ...` or `cd <source> && ...`. `--abort`/`--quit` stay allowed. - SHELL-SUBST-01 (same hook): a backtick or `$(...)` that the shell will execute and that runs a git write or `gh pr merge/close`, `gh issue close` is denied with or without a binding; other backticks inside double quotes get an advisory. Pass generated text through apply_patch, files, or `<<'EOF'`. ## 7. AGENTS.md snippet (WG-AGENTS-01) For repos where codexclaw hooks are not installed: ```md ## Worktree safety This session may run inside a Codex-app-managed worktree (~/.codex/worktrees/<slot>/<repo>). Never delete or recreate that directory to "rename" it. Adopt in place: `git switch -c <name>` / `git branch -m <name>`, commit early, and ask the user to rename the thread in the app. `git worktree move` is for other, inactive worktrees only. ```