fix(ce-setup): detect leftover Codex tool-map sentinels

skills/ce-setup/SKILL.md

@@ -70,6 +70,7 @@ Also remediate these project issues when the report names them:
 - `.compound-engineering/config.example.yaml` is missing or outdated
 - the health report marks the `ce-work` skill implementation engine unavailable or invalid, detects retired scalar routing keys, or reports malformed dormant `work_engine_preferences`
 - the health report marks `docs_root` invalid (`Invalid docs_root ...`) — CE artifacts will not be written until it is fixed
+- the health report names a **legacy Compound Codex tool map** in `$CODEX_HOME/AGENTS.md` (or a profile copy) — session-level; follow `references/legacy-codex-tool-map.md` in this skill. Do not rewrite `ce-work` skip phrases in this skill.
 
 If optional tools are missing, do not offer a bulk install. The diagnostic already printed the relevant install command or project URL. Say: "Install optional tools only for the workflows you use."
 

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

@@ -0,0 +1,30 @@
+# Remove the retired Compound Codex tool map
+
+The Bun-era convert/install path could insert a managed block into
+global Codex instructions:
+
+`<!-- BEGIN COMPOUND CODEX TOOL MAP -->` … `<!-- END COMPOUND CODEX TOOL MAP -->`
+
+in `$CODEX_HOME/AGENTS.md` (default `~/.codex/AGENTS.md`) and in named
+profile copies under `~/.codex/profiles/*/AGENTS.md`.
+
+That Claude-compat map is obsolete — CE skills name Codex tools inline —
+and one line incorrectly told Codex to collapse subagent dispatch onto
+the main thread. Native plugin install does **not** add this block.
+
+## Safe removal
+
+1. Check `$CODEX_HOME/AGENTS.md` if `CODEX_HOME` is set, otherwise
+   `~/.codex/AGENTS.md`. 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). Leave 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 of what changed (or say the block was
+   already absent). Do not add a replacement tool map.
+
+This file ships with the `ce-setup` skill so marketplace/converted
+installs still have the procedure without the repo `docs/` tree.

skills/ce-setup/scripts/check-health

@@ -289,6 +289,40 @@ 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 / #1559). Exact sentinels from docs/install/upgrading.md.
+CODEX_TOOL_MAP_START="<!-- BEGIN COMPOUND CODEX TOOL MAP -->"
+CODEX_TOOL_MAP_END="<!-- END COMPOUND CODEX TOOL MAP -->"
+codex_home="${CODEX_HOME:-$HOME/.codex}"
+default_codex_home="$HOME/.codex"
+legacy_codex_map_files=()
+scan_codex_agents_file() {
+  local f="$1"
+  local existing
+  [ -f "$f" ] || return 0
+  for existing in "${legacy_codex_map_files[@]}"; do
+    [ "$existing" = "$f" ] && return 0
+  done
+  if grep -F -q -- "$CODEX_TOOL_MAP_START" "$f" && grep -F -q -- "$CODEX_TOOL_MAP_END" "$f"; then
+    legacy_codex_map_files+=("$f")
+  fi
+}
+scan_codex_profile_tree() {
+  local root="$1"
+  local f
+  [ -d "$root/profiles" ] || return 0
+  for f in "$root/profiles"/*/AGENTS.md; do
+    [ -f "$f" ] || continue
+    scan_codex_agents_file "$f"
+  done
+}
+scan_codex_agents_file "$codex_home/AGENTS.md"
+scan_codex_profile_tree "$codex_home"
+# Named profiles live under ~/.codex even when CODEX_HOME points at an active profile.
+# Do not scan inactive ~/.codex/AGENTS.md — that file is not the current session.
+if [ "$codex_home" != "$default_codex_home" ]; then
+  scan_codex_profile_tree "$default_codex_home"
+fi
+
 # =====================================================
 #  Check optional capabilities
 # =====================================================
@@ -627,4 +661,14 @@ if [ "$capability_missing" -gt 0 ]; then
   echo "     Missing optional tools do not block setup; install them only for the workflows you use."
 fi
 
+if [ "${#legacy_codex_map_files[@]}" -gt 0 ]; then
+  echo ""
+  section "Codex instructions"
+  for f in "${legacy_codex_map_files[@]}"; do
+    warn "Legacy Compound Codex tool map still present in $f"
+  done
+  detail "This retired block can make Codex skip ce-code-review as if no runner exists."
+  detail "Remove only the BEGIN/END COMPOUND CODEX TOOL MAP span — see this skill's references/legacy-codex-tool-map.md"
+fi
+
 echo ""

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

@@ -17,13 +17,20 @@ type RunResult = {
   stderr: string
 }
 
-async function runCheckHealth(cwd: string, pathValue: string): Promise<RunResult> {
+async function runCheckHealth(
+  cwd: string,
+  pathValue: string,
+  extraEnv: Record<string, string> = {},
+): Promise<RunResult> {
   const proc = Bun.spawn(["bash", checkHealthScript], {
     cwd,
     env: {
       ...process.env,
       HOME: cwd,
       PATH: pathValue,
+      // Isolate from the host Codex install (CI/dev machines often set CODEX_HOME).
+      CODEX_HOME: path.join(cwd, ".codex"),
+      ...extraEnv,
     },
     stderr: "pipe",
     stdout: "pipe",
@@ -57,6 +64,95 @@ describe("ce-setup check-health", () => {
     expect(script).not.toMatch(/<<<\s/)
   })
 
+  test("reports the legacy Codex tool map when both sentinels are present", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ce-setup-health-"))
+    try {
+      await initGitRepo(root)
+      await mkdir(path.join(root, ".codex"), { recursive: true })
+      await writeFile(
+        path.join(root, ".codex", "AGENTS.md"),
+        [
+          "keep this",
+          "<!-- BEGIN COMPOUND CODEX TOOL MAP -->",
+          "Task (subagent dispatch) / Subagent / Parallel: run sequentially in main thread",
+          "<!-- END COMPOUND CODEX TOOL MAP -->",
+          "",
+        ].join("\n"),
+      )
+      const result = await runCheckHealth(root, "/usr/bin:/bin")
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toContain("Legacy Compound Codex tool map still present")
+      expect(result.stdout).toContain("references/legacy-codex-tool-map.md")
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
+  test("does not warn when Codex AGENTS.md has no tool-map sentinels", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ce-setup-health-"))
+    try {
+      await initGitRepo(root)
+      await mkdir(path.join(root, ".codex"), { recursive: true })
+      await writeFile(path.join(root, ".codex", "AGENTS.md"), "# user instructions\n")
+      const result = await runCheckHealth(root, "/usr/bin:/bin")
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).not.toContain("Legacy Compound Codex tool map still present")
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
+  test("still finds named-profile copies under ~/.codex when CODEX_HOME is elsewhere", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ce-setup-health-"))
+    try {
+      await initGitRepo(root)
+      const customHome = path.join(root, "custom-codex")
+      await mkdir(customHome, { recursive: true })
+      await writeFile(path.join(customHome, "AGENTS.md"), "# active profile, no map\n")
+      await mkdir(path.join(root, ".codex", "profiles", "work"), { recursive: true })
+      await writeFile(
+        path.join(root, ".codex", "profiles", "work", "AGENTS.md"),
+        [
+          "<!-- BEGIN COMPOUND CODEX TOOL MAP -->",
+          "Task (subagent dispatch) / Subagent / Parallel: run sequentially in main thread",
+          "<!-- END COMPOUND CODEX TOOL MAP -->",
+          "",
+        ].join("\n"),
+      )
+      const result = await runCheckHealth(root, "/usr/bin:/bin", { CODEX_HOME: customHome })
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toContain("Legacy Compound Codex tool map still present")
+      expect(result.stdout).toContain("references/legacy-codex-tool-map.md")
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
+  test("does not warn on inactive ~/.codex/AGENTS.md when CODEX_HOME is a custom home", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ce-setup-health-"))
+    try {
+      await initGitRepo(root)
+      const customHome = path.join(root, "custom-codex")
+      await mkdir(customHome, { recursive: true })
+      await writeFile(path.join(customHome, "AGENTS.md"), "# active profile, no map\n")
+      await mkdir(path.join(root, ".codex"), { recursive: true })
+      await writeFile(
+        path.join(root, ".codex", "AGENTS.md"),
+        [
+          "<!-- BEGIN COMPOUND CODEX TOOL MAP -->",
+          "Task (subagent dispatch) / Subagent / Parallel: run sequentially in main thread",
+          "<!-- END COMPOUND CODEX TOOL MAP -->",
+          "",
+        ].join("\n"),
+      )
+      const result = await runCheckHealth(root, "/usr/bin:/bin", { CODEX_HOME: customHome })
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).not.toContain("Legacy Compound Codex tool map still present")
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
   test("advertises agent-browser only for its current consumers", async () => {
     const [script, setupDocs, polishSkill, polishRun, polishDocs] = await Promise.all([
       readFile(checkHealthScript, "utf8"),