fix(ce-setup): detect the retired Codex tool map

docs/install/upgrading.md

@@ -60,11 +60,10 @@ Paste this into Codex (or any agent with access to your home directory) to remov
 ```text
 Remove the obsolete Compound Engineering Codex tool-map block from my Codex home AGENTS.md.
 
-1. Check `$CODEX_HOME/AGENTS.md` if CODEX_HOME is set, otherwise `~/.codex/AGENTS.md`. If I use Codex profiles, also check `~/.codex/profiles/*/AGENTS.md`.
-2. Look for the exact sentinels `<!-- BEGIN COMPOUND CODEX TOOL MAP -->` and `<!-- END COMPOUND CODEX TOOL MAP -->`.
-3. If both are present, delete only the span from the BEGIN line through the END line (inclusive), leaving any other user content untouched. Do not edit project/repo AGENTS.md unless those exact sentinels are present there.
-4. If the file is empty after the removal, delete the file.
-5. Show a short before/after summary of what you changed (or say the block was already absent). Do not add a replacement tool map.
+1. Check `$CODEX_HOME/AGENTS.md` if CODEX_HOME is set, otherwise `~/.codex/AGENTS.md`.
+2. Delete the managed block: the line `<!-- BEGIN COMPOUND CODEX TOOL MAP -->` through the next line `<!-- END COMPOUND CODEX TOOL MAP -->`. If that pair is not present as two whole lines in that order, the block is not there -- change nothing.
+3. Leave the rest of the file untouched, and delete the file if nothing is left. Do not add a replacement tool map, and do not edit project/repo AGENTS.md.
+4. Show a short before/after summary of what you changed (or say the block was already absent).
 ```
 
 Re-running the Bun convert/install CLI for Codex also strips the block if it is still present; it no longer inserts it.

skills/ce-setup/SKILL.md

@@ -63,6 +63,8 @@ After the health report, decide Phase 2 from writable-checkout availability:
 - If this session has no writable checkout, but the user named a repository and the harness exposes a remote repo-work surface with a writable checkout, run Phase 2 on that surface instead and report the remote repo-local fixes in Phase 3.
 - Otherwise skip Phase 2 and go to Phase 3, saying repo-local writes were skipped because no writable checkout is available.
 
+If the report names a legacy Compound Codex tool map, offer to remove it following `references/legacy-codex-tool-map.md` from this skill's directory. That block lives in the user's Codex home, not the checkout, so the offer stands whether or not Phase 2 runs.
+
 Also remediate these project issues when the report names them:
 
 - obsolete `compound-engineering.local.md`
@@ -88,8 +90,8 @@ Display a brief summary:
 ```text
 ✅ Compound Engineering setup complete
 
-Fixed:     <repo-local fixes applied, or none>
-Skipped:   <repo-local fixes declined, or none>
+Fixed:     <fixes applied, or none>
+Skipped:   <fixes declined, or none>
 Optional:  <missing optional tools, or all available>
 
 Run `<rendered invocation>` anytime to re-check.

skills/ce-setup/references/legacy-codex-tool-map.md

@@ -0,0 +1,15 @@
+# Remove the retired Compound Codex tool map
+
+The Bun-era `convert` / `install --to codex` path inserted a managed block into the global Codex instructions file:
+
+`<!-- BEGIN COMPOUND CODEX TOOL MAP -->` … `<!-- END COMPOUND CODEX TOOL MAP -->`
+
+in `${CODEX_HOME:-$HOME/.codex}/AGENTS.md`. That Claude-compat map is obsolete — CE skills name Codex tools inline — and one of its lines told Codex to collapse subagent dispatch onto the main thread. Native plugin install does not add it, and re-running the Bun CLI for Codex strips it.
+
+## Removal
+
+Delete the managed block from that file: the line `<!-- BEGIN COMPOUND CODEX TOOL MAP -->` through the next line `<!-- END COMPOUND CODEX TOOL MAP -->`. If that pair is not present as two whole lines in that order, the block is not there — change nothing.
+
+Leave the rest of the file untouched, and delete the file if nothing is left. Do not add a replacement map, and do not touch a project or repo `AGENTS.md`: the Bun installer only ever wrote the Codex home file.
+
+Show the user a short before/after of what changed, or say the block was already absent.

skills/ce-setup/references/repo-fixes.md

@@ -10,6 +10,7 @@ When the bundled `scripts/check-health` is unavailable, perform these checks by
 4. Check whether `.compound-engineering/config.yaml` exists.
 5. Check whether `.compound-engineering/config.local.yaml` exists and, if it does, whether `git check-ignore -q .compound-engineering/config.local.yaml` succeeds.
 6. Compare `.compound-engineering/config.example.yaml` with `references/config-template.yaml` when the template is readable; otherwise report that the example refresh must be done manually.
+7. Report a legacy Compound Codex tool map when `${CODEX_HOME:-$HOME/.codex}/AGENTS.md` contains a standalone `<!-- BEGIN COMPOUND CODEX TOOL MAP -->` line followed by a standalone `<!-- END COMPOUND CODEX TOOL MAP -->` line.
 
 This file is read at two points: from Step 2 whenever the bundled health script is unavailable, for the inline equivalent above; and before any Phase 2 write, once Step 3 has decided that a writable checkout exists and which reported issues need remediation. Ask with the blocking question tool named in SKILL.md. Maintaining the generated example files is the work this phase does on its own — Step 5's refresh and its removal of the superseded `config.local.example.yaml`. Every change to a user-owned file is offered and applied only if the user approves.
 

skills/ce-setup/scripts/check-health

@@ -289,6 +289,23 @@ read_work_engine_preferences() {
 has_brew=$(command -v brew >/dev/null 2>&1 && echo "yes" || echo "no")
 in_repo=$(git rev-parse --is-inside-work-tree >/dev/null 2>&1 && echo "yes" || echo "no")
 
+# Retired Bun-era Codex tool map (#1099). The block is present only when a
+# standalone BEGIN line is followed by a standalone END line.
+has_codex_tool_map() {
+  awk '
+    { sub(/\r$/, "") }
+    $0 == "<!-- BEGIN COMPOUND CODEX TOOL MAP -->" { seen = 1 }
+    seen && $0 == "<!-- END COMPOUND CODEX TOOL MAP -->" { found = 1; exit }
+    END { exit found ? 0 : 1 }
+  ' "$1"
+}
+
+codex_agents_file="${CODEX_HOME:-$HOME/.codex}/AGENTS.md"
+legacy_codex_map="no"
+if [ -f "$codex_agents_file" ] && has_codex_tool_map "$codex_agents_file"; then
+  legacy_codex_map="yes"
+fi
+
 # =====================================================
 #  Check optional capabilities
 # =====================================================
@@ -528,6 +545,13 @@ for result in "${results[@]}"; do
   fi
 done
 
+if [ "$legacy_codex_map" = "yes" ]; then
+  section "Codex instructions"
+  warn "Legacy Compound Codex tool map in ${codex_agents_file}"
+  detail "Retired block from a pre-native Bun install; one line tells Codex to collapse subagent dispatch."
+  detail "Remove it -- see this skill's references/legacy-codex-tool-map.md"
+fi
+
 if [ "$in_repo" = "yes" ]; then
   section "Project config"
 
@@ -623,6 +647,10 @@ else
   echo " ⚠️   ${project_issues} project issue(s) found. Optional capabilities available: ${capability_ok}/${capability_total}"
 fi
 
+if [ "$legacy_codex_map" = "yes" ]; then
+  echo "     Environment: the legacy Codex tool map above still needs attention."
+fi
+
 if [ "$capability_missing" -gt 0 ]; then
   echo "     Missing optional tools do not block setup; install them only for the workflows you use."
 fi

tests/skills/ce-setup-check-health.test.ts

@@ -24,6 +24,8 @@ async function runCheckHealth(cwd: string, pathValue: string): Promise<RunResult
       ...process.env,
       HOME: cwd,
       PATH: pathValue,
+      // A host CODEX_HOME would otherwise decide what the tool-map scan reads.
+      CODEX_HOME: path.join(cwd, ".codex"),
     },
     stderr: "pipe",
     stdout: "pipe",
@@ -51,6 +53,50 @@ async function initConfiguredRepo(root: string, localConfig: string): Promise<vo
 }
 
 describe("ce-setup check-health", () => {
+  async function runWithCodexAgents(contents: string): Promise<RunResult> {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ce-setup-health-codex-"))
+    try {
+      await initGitRepo(root)
+      await mkdir(path.join(root, ".codex"), { recursive: true })
+      await writeFile(path.join(root, ".codex", "AGENTS.md"), contents)
+      return await runCheckHealth(root, "/usr/bin:/bin")
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  }
+
+  test("reports the legacy Codex tool map and keeps the verdict from reading all-clear", async () => {
+    const result = await runWithCodexAgents(
+      [
+        "my notes",
+        "<!-- BEGIN COMPOUND CODEX TOOL MAP -->",
+        "Task (subagent dispatch): run sequentially in main thread",
+        "<!-- END COMPOUND CODEX TOOL MAP -->",
+        "",
+      ].join("\n"),
+    )
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain("Legacy Compound Codex tool map in")
+    expect(result.stdout).toContain("references/legacy-codex-tool-map.md")
+    expect(result.stdout).toContain("legacy Codex tool map above still needs attention")
+  })
+
+  test("reports no tool map without an ordered pair of standalone sentinel lines", async () => {
+    const result = await runWithCodexAgents(
+      [
+        "The retired map used `<!-- BEGIN COMPOUND CODEX TOOL MAP -->` to `<!-- END COMPOUND CODEX TOOL MAP -->` inline.",
+        "<!-- END COMPOUND CODEX TOOL MAP -->",
+        "my notes",
+        "<!-- BEGIN COMPOUND CODEX TOOL MAP -->",
+        "",
+      ].join("\n"),
+    )
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).not.toContain("Legacy Compound Codex tool map")
+  })
+
   test("does not require temporary-file-backed here-strings", async () => {
     const script = await readFile(checkHealthScript, "utf8")