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`

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/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")