cohorte 2.10.0 → 2.10.1

package/CHANGELOG.md

@@ -7,6 +7,14 @@ short, user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` secti
 > They are history and are deliberately not rewritten — every command gained a `cohorte-` prefix
 > in 2.0.0.
 
+## 2.10.1 — 2026-09-14
+
+- **Codex project isolation:** surface agents stay in each repository's `.codex/agents/*.toml`
+  even with a global core; no `CODEX_HOME` launcher or auth symlink is required.
+- **Codex correctness:** init/update/doctor use native TOML agents and MCP settings, preflight
+  covers `spawn_agent` dispatches, explicit Codex model choices survive, and implementer
+  templates no longer accidentally force a read-only sandbox. Added regression coverage.
+
 ## 2.10.0 — 2026-08-24
 
 - **The dashboard is gone.** The local web cockpit — the `cohorte dashboard` verb, the

package/bin/cli.js

@@ -220,8 +220,7 @@ function resolveTemplateConditionals(dir) {
     if (e.isDirectory()) { resolveTemplateConditionals(p); continue; }
     if (!p.endsWith('.md')) continue;
     const src = fs.readFileSync(p, 'utf8');
-    if (!src.includes('cohorte:if')) continue;
-    fs.writeFileSync(p, adapter.applyConditionals(src, runtime));
+    fs.writeFileSync(p, adapter.adaptInstructions(src, runtime));
   }
 }
 
@@ -309,6 +308,8 @@ function copyCore() {
     paths: {
       core: paths.core, commands: paths.commands,
       agents: paths.agents || path.join(paths.core, 'agents'),
+      surface_agents: runtime.id === 'codex' ? '.codex/agents' : undefined,
+      agent_ext: runtime.agent.ext,
       // Where the gate registration lives. `cohorte doctor` needs it to tell a registered
       // hook from a missing one without re-deriving each runtime's config layout itself.
       hooks_config: paths.hooks_config,
@@ -734,6 +735,10 @@ if (runtime.id !== 'claude') {
   invoke: ${runtime.command.invoke.replace('<name>', 'cohorte-init-pipeline')}
   agents: ${agentsWhere}
   gate: ${hookState}`);
+  if (runtime.id === 'codex') {
+    console.log('  surface agents: .codex/agents/*.toml in each project (generated by init/reconcile)');
+    console.log('  keep your normal CODEX_HOME; no project launcher or auth symlink is needed');
+  }
   if ((runtime.exclude_commands || []).length) {
     const named = runtime.exclude_commands.map((c) => runtime.command.invoke.replace('<name>', c));
     console.log(`  not installed here: ${named.join(', ')}${runtime.exclude_reason ? ` — ${runtime.exclude_reason}` : ''}`);

package/core/adapter/render.js

@@ -205,7 +205,8 @@ function configPath(runtime) {
 function preamble(runtime, paths, projectRoot, { kind = 'command' } = {}) {
   const caps = runtime.capabilities || {};
   const core = displayPath(paths.core, projectRoot);
-  const agentsDir = paths.agents ? displayPath(paths.agents, projectRoot) : `${core}/agents`;
+  const fixedAgentsDir = paths.agents ? displayPath(paths.agents, projectRoot) : `${core}/agents`;
+  const agentsDir = runtime.id === 'codex' ? '.codex/agents' : fixedAgentsDir;
   const L = [];
   L.push(`> **Runtime: ${runtime.label}.** Generated by the cohorte adapter — do not edit this file;`);
   L.push(`> edit \`core/${kind === 'agent' ? 'agents' : 'commands'}/\` in the cohorte source and re-install.`);
@@ -216,6 +217,11 @@ function preamble(runtime, paths, projectRoot, { kind = 'command' } = {}) {
   L.push(`> - \`<config>\` = \`${configPath(runtime)}\` — your user-level config (kanban boards, shared vault). One per human, never committed.`);
 
   L.push(`> - \`<agents>\` = \`${agentsDir}\` — real subagents. Dispatch: ${runtime.agent.dispatch}.`);
+  L.push(`> - \`<fixed-agents>\` = \`${fixedAgentsDir}\` — shipped review, release and profile-reader agents. Agent extension: \`${runtime.agent.ext}\`.`);
+  if (runtime.id === 'codex') {
+    L.push('> - Surface agents are always project-local `.codex/agents/*.toml`, even with a global core. Keep the normal user `CODEX_HOME`; no project launcher or authentication symlink is needed. Never overwrite another project\'s global agents.');
+    L.push('> - Agent files use TOML `name`, `description`, `developer_instructions`; optional `model` and `model_reasoning_effort` must be Codex-compatible. Omitted model settings inherit; never write Anthropic aliases. MCP registration lives in `.codex/config.toml`, not a standalone `.mcp.json`.');
+  }
 
   if (caps.hooks) {
     const cfg = displayPath(paths.hooks_config, projectRoot);
@@ -240,6 +246,14 @@ function preamble(runtime, paths, projectRoot, { kind = 'command' } = {}) {
   return L.join('\n') + '\n';
 }
 
+// Apply to commands AND the instruction templates they consume. Filenames here refer to
+// rendered agents, not to the Markdown source templates shipped inside the core.
+function adaptInstructions(text, runtime) {
+  const resolved = applyConditionals(text, runtime);
+  if (runtime.id !== 'codex') return resolved;
+  return resolved.replace(/(<(?:agents|fixed-agents)>\/[^\s`]+)\.md\b/g, '$1.toml');
+}
+
 // --- 3. surface encoding ------------------------------------------------------
 
 function parseFrontmatter(text) {
@@ -272,10 +286,11 @@ function substituteArgs(text, runtime) {
   return text.split('$ARGUMENTS').join(token);
 }
 
-// TOML basic-string escaping for the multi-line ''' form Gemini expects. A literal
-// ''' inside a prompt would close the string early, so it is the one sequence broken up.
+// Prefer readable multi-line literal TOML; fall back to basic strings for delimiter collisions.
 function tomlMultiline(s) {
-  return "'''\n" + s.replace(/'''/g, "''\\'") + "\n'''";
+  // Literal TOML strings cannot escape their delimiter. Use a basic string when the
+  // prompt itself contains triple apostrophes, preserving the content exactly.
+  return s.includes("'''") ? JSON.stringify(s) : "'''\n" + s + "\n'''";
 }
 function tomlBasic(s) {
   return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ') + '"';
@@ -287,7 +302,7 @@ function tomlBasic(s) {
  */
 function renderCommand({ source, name, runtime, paths, projectRoot }) {
   const { keys, body } = parseFrontmatter(source);
-  let out = applyConditionals(body, runtime);
+  let out = adaptInstructions(body, runtime);
   out = preamble(runtime, paths, projectRoot) + '\n' + out.replace(/^\n+/, '');
   out = substituteArgs(out, runtime);
 
@@ -322,6 +337,9 @@ function renderCommand({ source, name, runtime, paths, projectRoot }) {
 function isReadOnly(keys) {
   const tools = (keys.find(([k]) => k === 'tools') || [])[1];
   if (!tools) return false;
+  // The implementer template is rendered before its surface tool list is known.
+  // A placeholder is not evidence that the eventual worker must be read-only.
+  if (tools.includes('<SURFACE_TOOLS>')) return false;
   return !/\b(Write|Edit|MultiEdit|Bash|NotebookEdit)\b/.test(tools);
 }
 
@@ -336,7 +354,7 @@ function isReadOnly(keys) {
 function renderAgent({ source, name, runtime, paths, projectRoot }) {
   const { keys, body } = parseFrontmatter(source);
   const out = preamble(runtime, paths, projectRoot, { kind: 'agent' }) + '\n'
-    + applyConditionals(body, runtime).replace(/^\n+/, '');
+    + adaptInstructions(body, runtime).replace(/^\n+/, '');
   const spec = runtime.agent;
   const readonly = isReadOnly(keys);
 
@@ -345,7 +363,14 @@ function renderAgent({ source, name, runtime, paths, projectRoot }) {
     const lines = [`# cohorte — generated for ${runtime.label}. Do not edit; edit core/agents/${name}.md.`];
     lines.push(`name = ${tomlBasic(get('name') || name)}`);
     if (get('description')) lines.push(`description = ${tomlBasic(get('description'))}`);
-    if (spec.frontmatter.includes('model') && get('model')) lines.push(`model = ${tomlBasic(get('model'))}`);
+    const model = get('model');
+    if (spec.frontmatter.includes('model') && model
+        && !['inherit', 'sonnet', 'haiku', 'opus'].includes(model) && !model.startsWith('<')) {
+      lines.push(`model = ${tomlBasic(model)}`);
+    }
+    if (spec.frontmatter.includes('model_reasoning_effort') && get('model_reasoning_effort')) {
+      lines.push(`model_reasoning_effort = ${tomlBasic(get('model_reasoning_effort'))}`);
+    }
     if (readonly && spec.readonly_key) {
       lines.push(`${spec.readonly_key} = ${tomlBasic(spec.readonly_value)}`);
     }
@@ -380,6 +405,7 @@ module.exports = {
   expandHome,
   displayPath,
   applyConditionals,
+  adaptInstructions,
   testCondition,
   parseFrontmatter,
   emitFrontmatter,

package/core/commands/cohorte-doctor.md

@@ -30,13 +30,24 @@ fix only with the human's go-ahead (or hand them the command).
    commands' step files are present — `templates/steps/init-pipeline/` non-empty (a router whose
    `templates/steps/<cmd>/` dir is missing is a partial/stale install ⇒
    re-run install/update). **Shipped scripts present and executable** in `<core>/pipeline/scripts/`:
-   `kanban-move.sh`, `preflight.sh`,
-   `new-feature.sh.template`, `remove-feature.sh.template` — ❌ any missing one.
+   `kanban-move.sh`, `preflight.sh`; the `new-feature.sh.template` and
+   `remove-feature.sh.template` sources must be readable, not executable — ❌ any missing one.
    Every caller chains these with `|| true`, so an absent script is a **silent**
    no-op (no kanban card moves, no error anywhere) — this check is the only thing
    that sees it. Also flag ❌ a `VERSION` **newer than** the other `pipeline/` files (compare mtimes):
    a version bumped without a full re-copy is a half-done update ⇒ re-run install/update.
 2. **Profile.** `PIPELINE.md` exists and its `yaml pipeline-profile` block parses. Every
+<!-- cohorte:if runtime:codex -->
+   `surfaces[].agent` has a valid `.codex/agents/<agent>.toml` in this project, regardless of
+   core scope. Check `name`, `description`, `developer_instructions` and no unfilled placeholders.
+   Reconcile only this project's agents; never treat unrelated global agents as orphans.
+   Generic `review.toml`, `release.toml`, `profile-reader.toml` live under `<fixed-agents>/`.
+   The read-only generic agents must carry `sandbox_mode = "read-only"`.
+   Missing `model` means inheritance, not an error. Reject Anthropic aliases; compare explicit
+   Codex model pins with the profile when supplied. Claude `tools:` is not a Codex TOML field.
+   Flag project launchers that redefine `CODEX_HOME` just to discover local agents; native
+   project discovery needs no auth symlink. Do not delete global agents without checking ownership.
+<!-- cohorte:else -->
    `surfaces[].agent` has its `<agents>/<agent>.md` and every agent file has its `surfaces[]`
    entry — **no orphans either way** (SCHEMA.md rule). Each rendered agent's frontmatter `tools`
    matches its surface's `tools` (incl. `DesignSync` iff `uses_design`, retrieval MCP tools iff
@@ -46,6 +57,7 @@ fix only with the human's go-ahead (or hand them the command).
    dispatch); ⚠️ any `inherit` with the note that it bills at the lead's tier. The generic agents
    (`review.md`, `release.md`, `profile-reader.md` in `<agents>/`) must
    each carry their `model:` line too (sonnet/haiku/haiku).
+<!-- cohorte:endif -->
 <!-- cohorte:if runtime:claude -->
    **Command pins:** every mechanical command file
    (`build`, `review`, `fix`, `ship`, `audit`, `refactor`, `doctor`, `align-ds`,
@@ -62,8 +74,14 @@ fix only with the human's go-ahead (or hand them the command).
    double registration, it double-prompts — and its `command` points at a `gate.py` that exists.
    Check the **matcher** actually covers what it must: on Claude Code that means both `Bash` and
    `Task`, since the preflight phase gate keys off `Task` dispatches and a `Bash`-only matcher
-   leaves it silently dead (the 1.3.0–1.3.1 regression). Prove the wiring end to end rather than
-   trusting the file: `python3 <core>/hooks/gate.py --check "<a pattern from the ask list>"` must
+   leaves it silently dead (the 1.3.0–1.3.1 regression).
+<!-- cohorte:if runtime:codex -->
+   Codex's matcher must cover `Bash` plus `spawn_agent`/`Agent`, and
+   `gate.py` must read `tool_input.agent_type`. With preflight enabled and no fresh stamp,
+   a synthetic `spawn_agent` review payload must be denied. Check client hook enablement/trust
+   separately; a direct script check is not proof the client invoked it.
+<!-- cohorte:endif -->
+   Test the evaluator too: `python3 <core>/hooks/gate.py --check "<a pattern from the ask list>"` must
    return a non-`allow` verdict. If the Runtime preamble said this runtime has **no confirmation
    tier**, state it here too: every `ask` pattern behaves as a `deny`, which is safe but stricter
    than the profile reads, and a human who expects a prompt will read the refusal as a bug.
@@ -82,8 +100,14 @@ fix only with the human's go-ahead (or hand them the command).
    the committed copy lands in every clone and new worktree; the gate then blocks clean trees and
    greens unchecked ones. fix: `git rm --cached <state>/preflight.ok` + add it to `.gitignore`.
 4. **Retrieval** (if `retrieval.provider` ≠ `none`). Run the SCHEMA.md §Code retrieval health
+<!-- cohorte:if runtime:codex -->
+   check: CLI resolvable from PATH, `[mcp_servers.<provider>]` in `.codex/config.toml`,
+   `.serena/` gitignored, and tools actually connected in this session. A standalone
+   `.mcp.json` is not Codex project registration.
+<!-- cohorte:else -->
    check: CLI resolvable from PATH, `.mcp.json` entry present in PATH-proof launcher form,
    `.serena/` gitignored, server actually connects.
+<!-- cohorte:endif -->
 5. **Design** (if `design.enabled`). `snapshot_dir` exists and is committed; `ui_kit_path` +
    `tokens_path` exist; if `provider: claude-design`, `DesignSync` responds (`list_files` on the `design_system_project`) and
    `design_system_project` is reachable. Recall: spec `design_files` are full

package/core/commands/cohorte-update-pipeline.md

@@ -1,6 +1,6 @@
 ---
 model: sonnet
-description: Refresh the pipeline core (global ~/.claude, or a repo's bundled .claude) to the latest published cohorte version, then reconcile this repo's generated files to it — /cohorte-init-pipeline stays one-time.
+description: Refresh this runtime's global or project-local pipeline core, then reconcile the project's generated files — /cohorte-init-pipeline stays one-time.
 argument-hint: [path-to-local-checkout]
 ---
 
@@ -24,6 +24,17 @@ the human's choices — so `/cohorte-init-pipeline` never needs re-running for a
 
 ## 2. Run the update
 
+<!-- cohorte:if runtime:codex -->
+Preserve the existing install scope and explicitly select Codex:
+
+- Local source checkout supplied: `node <path>/bin/cli.js update --runtime=codex [--global]`.
+- Published release: `npm i -g cohorte@latest`, then `cohorte update --runtime=codex [--global]`.
+
+Expand `[--global]` to `--global` only for a global core; otherwise omit it. Run from the target
+project, or pass its path. Keep the user's normal `CODEX_HOME`. The global core and generic
+agents may be shared, but reconciliation always writes surface agents in this project's
+`.codex/agents/*.toml`.
+<!-- cohorte:else -->
 - If `$ARGUMENTS` is a path to a local checkout of the pipeline repo (contains `core/` + `install.sh`),
   run from there — useful when iterating on the pipeline itself:
 
@@ -51,6 +62,7 @@ the human's choices — so `/cohorte-init-pipeline` never needs re-running for a
   ```
 
   (The piped installer clones the repo itself; `-s --` forwards the flags.)
+<!-- cohorte:endif -->
 
 ## 3. Report old → new
 
@@ -77,7 +89,20 @@ or the **quiet command variants**: `test_quiet_cmd`/`lint_quiet_cmd` + `commands
 `lint_quiet`, proposing the detected bridled forms per §Output discipline; `gate.preflight` tops up
 silently at its defaults), re-render the surface agents from the current `implementer.template.md`
 (this refreshes each agent's **baked §Conventions slice** — required after any hand-edit of the
-profile's prose), additively patch `settings.json`/`gate-config.json` (including the `preflight`
+profile's prose).
+<!-- cohorte:if runtime:codex -->
+Write surface agents as `.codex/agents/*.toml`, validate TOML, and preserve explicit Codex model
+choices (legacy Anthropic aliases mean inheritance). Patch `<state>/gate-config.json` and
+verify the selected scope's hook covers shell and `spawn_agent`/`Agent`; do not duplicate it.
+Verify `<fixed-agents>/profile-reader.toml` and the other shipped generic agents. Workflows are
+unavailable on Codex and their absence is expected. Reconcile MCP in `.codex/config.toml` using
+SCHEMA.md §Code retrieval, preserving unrelated configuration and checking actual connectivity.
+If a previous install wrote this project's agents globally, compare ownership/content before
+moving them locally; never remove unrelated global agents or overwrite modified local copies.
+Remove project-only `CODEX_HOME` workarounds only after verifying native discovery. Do not copy
+authentication into the repository. Report what changed and anything still unverified.
+<!-- cohorte:else -->
+Additively patch `settings.json`/`gate-config.json` (including the `preflight`
 block and the workflow-agent `allow` entries from init step 5), and run any newly-added capability's
 wiring (e.g. Serena's project-scope `claude mcp add`). Verify the refreshed core actually carries
 `<core>/workflows/` + `agents/profile-reader.md` — missing means the update half-ran: re-run the
@@ -87,6 +112,7 @@ upgrading a bare `serena` entry to the PATH-proof launcher form, `.serena/` giti
 actually connected) and repair whatever fails — wiring that worked at
 init can rot (PATH changes, uninstalls, hand-edits). Report what was reconciled; if nothing was
 missing, say so. This is why `/cohorte-init-pipeline` never needs re-running for a core upgrade.
+<!-- cohorte:endif -->
 
 Four of the §Reconcile steps matter specifically here:
 
@@ -124,11 +150,16 @@ Four of the §Reconcile steps matter specifically here:
 
 ## 4. Tell the human the follow-ups
 
-- **Restart / reload the Claude Code session** so it picks up updated commands, agents, and any
+- **Restart / reload the coding-agent session** so it picks up updated commands, agents, and any
   newly-registered MCP server.
 - **Other repos using the global core:** their core is already fresh, but reconcile is per-repo — run
   `/cohorte-update-pipeline` inside each (it will skip the already-done core update and just reconcile).
+<!-- cohorte:if runtime:codex -->
+- **Commit** the reconciled `PIPELINE.md`, `.codex/agents/*.toml`, `.codex/config.toml` if added,
+  and versioned `<state>` files. Never commit auth or session state.
+<!-- cohorte:else -->
 - **Commit** the reconciled files (`PIPELINE.md`, `.claude/`, `.mcp.json` if added) so teammates get them.
+<!-- cohorte:endif -->
 - The kanban config is global and user-scoped
   (`<config>`) — never committed. The core update never touches it; only the
   reconcile above seeds the file and writes kanban board links (into that global file, not the repo).

package/core/hooks/gate.py

@@ -86,10 +86,12 @@ WS = re.compile(r"\s+")
 # stat data. Must stay ≥ the filesystem's mtime granularity (1 s on ext4/HFS+); 5 s covers a
 # clock that ticks backwards a little without costing anything on a quiet tree.
 RACY_WINDOW_S = 5
+HOOK_CWD = None
 
 
 def project_root() -> str:
-    return os.environ.get("COHORTE_PROJECT_DIR") or os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    return (os.environ.get("COHORTE_PROJECT_DIR") or os.environ.get("CLAUDE_PROJECT_DIR")
+            or HOOK_CWD or ".")
 
 
 # The generated per-project files (gate config + preflight stamp) live under `.claude/`
@@ -317,7 +319,8 @@ def check_preflight(payload: dict, cfg: dict) -> int:
     # carrying `subagent_type`; Gemini exposes each subagent as a tool of the SAME NAME, so the
     # dispatch arrives as `tool_name: review`. Accept both rather than gating only the shape
     # one vendor happens to use — a phase gate that silently never fires is the 1.3.0 bug.
-    subagent = (payload.get("tool_input") or {}).get("subagent_type", "") or ""
+    tool_input = payload.get("tool_input") or {}
+    subagent = tool_input.get("subagent_type") or tool_input.get("agent_type") or ""
     if not subagent and payload.get("tool_name") in agents:
         subagent = payload.get("tool_name")
     if subagent not in agents:
@@ -493,7 +496,7 @@ def main() -> int:
     if argv and argv[0] in ("--check", "--check-dispatch"):
         return check_cli(argv)
 
-    global RUNTIME
+    global RUNTIME, HOOK_CWD
     for i, a in enumerate(argv):
         if a == "--runtime" and i + 1 < len(argv):
             RUNTIME = argv[i + 1]
@@ -505,6 +508,11 @@ def main() -> int:
     except Exception:
         return 0  # malformed input → don't block
 
+    # Codex provides the project cwd in the envelope, not CLAUDE_PROJECT_DIR.
+    # A globally installed hook must inspect the calling project, not the process cwd.
+    if isinstance(payload.get("cwd"), str) and payload["cwd"]:
+        HOOK_CWD = payload["cwd"]
+
     tool = payload.get("tool_name")
     # Cursor's shell hook carries the command at the top level rather than in tool_input, and
     # names no tool. Normalise once here so every check below stays runtime-agnostic.
@@ -515,7 +523,7 @@ def main() -> int:
     cfg = load_config()
 
     # A dispatch, in whichever shape this runtime sends it (see check_preflight).
-    if tool == "Task" or tool in ((cfg.get("preflight") or {}).get("agents") or ["review"]):
+    if tool in ("Task", "spawn_agent", "Agent") or tool in ((cfg.get("preflight") or {}).get("agents") or ["review"]):
         return check_preflight(payload, cfg)
     # Bash is Claude's/Codex's name for the shell tool; Gemini calls it run_shell_command, and
     # Cursor's beforeShellExecution was normalised to "Bash" above. Anything else is not a

package/core/runtimes/codex.json

@@ -14,7 +14,7 @@
     "Subagents are TOML, one file per agent, and the body lives in `developer_instructions`.",
     "Hooks use the SAME PreToolUse envelope as Claude Code, with one difference that matters:",
     "`permissionDecision: ask` is parsed but not honoured, so gate.py escalates ask to deny here.",
-    "Model pins are NOT carried across: the profile names Anthropic aliases (sonnet/haiku), which are meaningless here and would either error or be silently ignored. Agents and commands inherit this runtime's own model selection instead."
+    "Anthropic model aliases are dropped and default to inheritance. Explicit Codex model and model_reasoning_effort values are preserved. Surface agents always live in the current project's .codex/agents, even with a global core; CODEX_HOME does not change."
   ],
   "scopes": {
     "global": {
@@ -56,7 +56,9 @@
     "body_key": "developer_instructions",
     "frontmatter": [
       "name",
-      "description"
+      "description",
+      "model",
+      "model_reasoning_effort"
     ],
     "readonly_key": "sandbox_mode",
     "readonly_value": "read-only",
@@ -66,7 +68,7 @@
   "hook": {
     "format": "claude",
     "event": "PreToolUse",
-    "matcher": "Bash|shell",
+    "matcher": "Bash|shell|spawn_agent|Agent",
     "supports_ask": false,
     "config_shape": "json"
   },

package/core/templates/steps/init-pipeline/04-write-render.md

@@ -4,8 +4,13 @@
 
 1. **Write `PIPELINE.md`** at the repo root (source: the installer's `pipeline/PIPELINE.template.md`).
 2. **Wire it into `<memory>`:** if `<memory>` exists, ensure it references the profile (add a line
+<!-- cohorte:if runtime:codex -->
+   near the top: `Read PIPELINE.md for the project profile and pipeline rules before pipeline work.`).
+   If absent, create `AGENTS.md` with that instruction and a one-paragraph project intro.
+<!-- cohorte:else -->
    near the top: `> Project profile & pipeline facts: **@PIPELINE.md**`). If not, create a minimal
    `<memory>` with that reference + a one-paragraph project intro.
+<!-- cohorte:endif -->
 3. **Render one agent per surface** — for each surface, follow SCHEMA.md §"Rendering / reconciling a
    surface agent" (steps 2–3): render `<agents>/<agent>.md` from the installer's
    `pipeline/implementer.template.md`, substituting `<SURFACE_AGENT>`, `<SURFACE_LABEL>`, `<SURFACE_PATH>`,
@@ -14,12 +19,28 @@
    PIPELINE.md you just wrote), and the surface-specific blocks
    (`<SURFACE_EXTRA_NEVER>`, `<SURFACE_DESIGN_INPUT>`, `<SURFACE_TDD_STEP1>` — fill design-related ones
    only when `uses_design`).
-   Leave the fixed agents as-is (generic, shipped by the installer): `review.md`, `release.md`,
-   `profile-reader.md`.
+   Leave the fixed agents as-is (generic, shipped by the installer under `<fixed-agents>/`).
+<!-- cohorte:if runtime:codex -->
+   Write `.codex/agents/<agent>.toml` in this project even when the core is global. Preserve
+   TOML syntax when substituting the template; parse every result before dispatch. Each file
+   needs `name`, `description`, and `developer_instructions`. Omit `model` for `inherit` or
+   legacy `sonnet`/`haiku` profiles; preserve an explicitly selected Codex model and reasoning
+   effort. Do not add Claude `tools:` frontmatter. Codex discovers these project files natively:
+   leave the user's `CODEX_HOME` unchanged and do not create a dedicated launcher or auth symlink.
+<!-- cohorte:endif -->
 4. **Generate `<state>/gate-config.json`** from the `gate` block — copy all five keys verbatim:
    `{"deny": [...], "ask": [...], "ask_on_default_branch": [...], "default_branch": "<vcs.default_branch>",
    "preflight": {"enabled": <gate.preflight.enabled>, "agents": [...], "max_age_minutes": <n>}}`
    (profile has no `preflight` block ⇒ omit the key — the hook then skips the phase gate).
+<!-- cohorte:if runtime:codex -->
+5. **Codex configuration.** Preserve `.codex/config.toml` and the user's configuration.
+   The installer registers `PreToolUse` in the selected scope's `hooks.json`; verify exactly
+   one Cohorte hook covering `Bash|shell|spawn_agent|Agent` with `--runtime codex`.
+   In global mode do not duplicate it locally. In project mode use `.codex/hooks.json`.
+   Check the hook is enabled/trusted in this client; a file alone does not prove enforcement.
+   Never write `.claude/settings.json` or Claude `Bash(...)` permission rules for Codex.
+   `ask` rules become `deny` in this hook; explain this stricter behavior.
+<!-- cohorte:else -->
 <!-- cohorte:if hooks -->
 5. **Write `.claude/settings.json`** permissions (`ask`/`deny` lists mirroring the gate, **plus an
    `allow` list of the project's read-only / verification commands** so agents don't stall on
@@ -53,7 +74,15 @@
    deny/ask patterns live, so fill it from the profile exactly and do not skip it. If this repo is
    also driven from Claude Code, that install's hook reads the same file; nothing to duplicate.
 <!-- cohorte:endif -->
+<!-- cohorte:endif -->
 6. **Wire the retrieval provider** (skip if `retrieval.provider: none`):
+<!-- cohorte:if runtime:codex -->
+   Follow SCHEMA.md §Code retrieval's Codex procedure: merge `[mcp_servers.serena]` into the
+   project's `.codex/config.toml`, preserve other settings, gitignore `.serena/`, then check
+   CLI availability, registration and actual session connectivity. Do not write a standalone
+   `.mcp.json` or run `claude mcp add`. Missing connectivity requires a restart/diagnosis,
+   not a claim that registration succeeded end to end.
+<!-- cohorte:else -->
    - **serena:** if the `serena` CLI is missing, have the human install it (`uv tool install -p 3.13
      serena-agent`) — or set the provider to `none` if they decline, and say `/cohorte-update-pipeline` can wire
      it later. If the binary exists (e.g. `~/.local/bin/serena`) but `command -v serena` fails,
@@ -74,6 +103,7 @@
      big changes.
    - Either way the rendered agents already carry the provider's MCP tools in their `tools:` list
      (step 3 / SCHEMA §Rendering); remind the human the new MCP server appears after a session restart.
+<!-- cohorte:endif -->
 7. **Render the isolation scripts** (if `isolation.enabled`) from the installer's
    `pipeline/scripts/*.template` to this repo's `scripts/new-feature.sh` and `scripts/remove-feature.sh`,
    substituting the `__TOKENS__` (project

package/lib/doctor.js

@@ -7,7 +7,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { layouts, primary, stateDirs } = require('./runtime.js');
+const { layouts, stateDirs } = require('./runtime.js');
 const { parseProfileBlock } = require('./yaml');
 const { versions } = require('./versions');
 
@@ -54,6 +54,15 @@ function mk(id, label, status, detail, fix) {
   return fix ? { id, label, status, detail, fix } : { id, label, status, detail };
 }
 
+function acrossRuntimes(all, check) {
+  const distinct = all.filter((l, i) => all.findIndex(other => other.id === l.id) === i);
+  const results = (distinct.length ? distinct : [null]).map(check);
+  if (results.length === 1) return results[0];
+  const rank = { skip: 0, ok: 1, warn: 2, bad: 3 };
+  const worst = results.reduce((a, b) => rank[b.status] > rank[a.status] ? b : a);
+  return { ...worst, detail: results.map((r, i) => `${distinct[i].label}: ${r.detail}`).join(' · ') };
+}
+
 // --- individual checks -------------------------------------------------------
 
 function checkCore(v) {
@@ -99,19 +108,20 @@ function checkAgents(profile, projectRoot, layout) {
   if (!layout) {
     return mk('agents', 'Surfaces ↔ agents', 'skip', 'no core installed — nothing renders agents yet');
   }
-  const agentsDir = layout.agents;
+  const agentsDir = layout.surfaceAgents || layout.agents;
+  const ext = layout.agentExt || (layout.id === 'codex' ? '.toml' : '.md');
   const surfaceAgents = profile.surfaces.map(s => s.agent).filter(Boolean);
 
-  const missing = surfaceAgents.filter(a => !exists(path.join(agentsDir, `${a}.md`)));
+  const missing = surfaceAgents.filter(a => !exists(path.join(agentsDir, `${a}${ext}`)));
 
   let files = [];
-  try { files = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).map(f => f.slice(0, -3)); }
+  try { files = fs.readdirSync(agentsDir).filter(f => f.endsWith(ext)).map(f => f.slice(0, -ext.length)); }
   catch { /* dir absent → handled by `missing` */ }
   // Orphan detection only makes sense against a PROJECT agents dir. A global install's
   // agents dir (~/.claude/agents) is the user's shared Claude Code space — their personal
   // agents and other cohorte projects' surface agents live there legitimately, and
   // flagging them sent humans deleting files that were not this project's to judge.
-  const orphans = layout.scope === 'global'
+  const orphans = layout.scope === 'global' && layout.id !== 'codex'
     ? []
     : files.filter(f => !FIXED_AGENTS.has(f) && !surfaceAgents.includes(f));
 
@@ -276,7 +286,7 @@ function checkHooks(projectRoot, globalDir, installMode, all) {
 
   const problems = [];
   const okLines = [];
-  for (const l of hosts) {
+  for (const l of hosts.filter((h, i) => hosts.findIndex(other => other.id === h.id) === i)) {
     const event = (l.id === 'cursor') ? 'beforeShellExecution'
       : (l.id === 'gemini') ? 'BeforeTool' : 'PreToolUse';
     // A Claude registration serves the project from EITHER scope: bundled repos get it from
@@ -287,7 +297,10 @@ function checkHooks(projectRoot, globalDir, installMode, all) {
       ? (installMode === 'global'
         ? [path.join(globalDir, 'settings.json'), path.join(projectRoot, '.claude', 'settings.json')]
         : [path.join(projectRoot, '.claude', 'settings.json'), path.join(globalDir, 'settings.json')])
-      : [l.hooksConfig];
+      : l.id === 'codex'
+        ? [...new Set([...hosts.filter(h => h.id === 'codex').map(h => h.hooksConfig),
+          path.join(projectRoot, '.codex', 'hooks.json')])]
+        : [l.hooksConfig];
     const found = paths.map(p2 => ({ path: p2, regs: gateRegs(p2, event) })).filter(f => f.regs.length);
     if (!found.length) {
       problems.push(`${l.label}: not registered (${event})`);
@@ -298,11 +311,16 @@ function checkHooks(projectRoot, globalDir, installMode, all) {
       problems.push(`${l.label}: registered ${total}× — it will double-prompt`);
       continue;
     }
-    // Only the matcher-group runtimes carry one, and only Claude dispatches subagents through
-    // a `Task` tool — a Bash-only matcher there leaves the preflight phase gate dead.
+    // Validate the regex against the host's real tool names, including dispatch aliases.
     const matcher = String(found[0].regs[0].matcher || '');
-    if (l.id === 'claude' && (!/\bTask\b/.test(matcher) || !/\bBash\b/.test(matcher))) {
-      problems.push(`${l.label}: matcher "${matcher}" must cover both Bash and Task`);
+    const matches = name => {
+      if (!matcher || matcher === '*') return true;
+      try { return new RegExp(matcher).test(name); } catch { return false; }
+    };
+    const dispatch = l.id === 'codex' ? ['spawn_agent', 'Agent'] : ['Task'];
+    if (['claude', 'codex'].includes(l.id)
+        && (!matches('Bash') || !dispatch.some(matches))) {
+      problems.push(`${l.label}: matcher "${matcher}" must cover Bash and ${dispatch.join('/')}`);
       continue;
     }
     okLines.push(`${l.label} (${event}${matcher ? `, ${matcher}` : ''})`);
@@ -319,11 +337,24 @@ function checkHooks(projectRoot, globalDir, installMode, all) {
   return mk('hooks', 'Gate hook', 'ok', `registered once for ${okLines.join(', ')}${tail}`);
 }
 
-function checkRetrieval(profile, projectRoot) {
+function checkRetrieval(profile, projectRoot, layout) {
   const provider = profile && profile.retrieval && profile.retrieval.provider;
   if (!provider || provider === 'none' || String(provider).startsWith('<')) {
     return mk('retrieval', 'Code retrieval', 'skip', 'provider: none');
   }
+  if (layout?.id === 'codex') {
+    const file = '.codex/config.toml';
+    const config = readText(path.join(projectRoot, file)) || '';
+    // Static registration check only, as for the JSON path below. Connectivity requires
+    // a live session. Anchor to table declarations so prose/comments cannot count as wired.
+    const tables = [...config.matchAll(/^\s*\[mcp_servers\.([^\]\n]+)\]\s*(?:#.*)?$/gm)]
+      .map(m => m[1].trim().replace(/^["']|["']$/g, ''));
+    const wired = tables.includes(String(provider));
+    return mk('retrieval', 'Code retrieval', wired ? 'ok' : 'warn', wired
+      ? `provider: ${provider} — table present in ${file} (validity/connectivity need in-session verification)`
+      : `profile says provider: ${provider} but ${file} has no matching server table`,
+    wired ? undefined : '$cohorte-update-pipeline   (merge the project MCP table)');
+  }
   // The profile alone isn't proof the provider was ever wired: /cohorte-init-pipeline
   // registers it at project scope in .mcp.json. Verify the entry exists on disk;
   // live connectivity still needs a session — note it, don't fake green.
@@ -461,18 +492,17 @@ async function state({ projectRoot, globalDir, cliVersion }) {
   // this rather than assuming `.claude/` — on a Cursor-only repo that assumption reported the
   // core, the agents, the artifacts and the hook as all broken, and every one of them was fine.
   const all = layouts({ projectRoot, globalDir });
-  const main = primary(all);
   const stateAbs = stateDirs(all, projectRoot);
   const stateRels = stateAbs.map(rel(projectRoot));
 
   const checks = [
     checkCore(v),
     checkProfile(profile, pipelineMd != null),
-    checkAgents(profile, projectRoot, main),
+    acrossRuntimes(all, layout => checkAgents(profile, projectRoot, layout)),
     checkGate(profile, projectRoot, stateAbs),
     checkLocalArtifacts(projectRoot, stateRels),
     checkHooks(projectRoot, globalDir, v.installMode, all),
-    checkRetrieval(profile, projectRoot),
+    acrossRuntimes(all, layout => checkRetrieval(profile, projectRoot, layout)),
     checkDesign(profile, projectRoot),
     checkIsolation(profile, projectRoot),
     checkWorkflows(projectRoot, globalDir, v.installMode, all),

package/lib/runtime.js

@@ -94,6 +94,11 @@ function layouts({ projectRoot, globalDir }) {
         scope: rec.scope || scope,
         core: dir,
         agents: abs(p.agents, path.join(dir, 'agents')),
+        // A global Codex core must never bind surface agents to its installing project.
+        // Also repair discovery for registries written before this distinction existed.
+        surfaceAgents: id === 'codex' ? path.join(projectRoot, '.codex', 'agents')
+          : abs(p.surface_agents || p.agents, path.join(dir, 'agents')),
+        agentExt: p.agent_ext || (id === 'codex' ? '.toml' : '.md'),
         commands: abs(p.commands, path.join(dir, 'commands')),
         state: abs(null, p.state || stateDirFor(id)),
         // Pre-2.2.0 cores carry no registry, so nothing records where the hook is registered.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "2.10.0",
+  "version": "2.10.1",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code, Codex CLI, Cursor, Gemini CLI and OpenCode — install the core, run /cohorte-init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"

package/profile/PIPELINE.template.md

@@ -37,7 +37,7 @@ repo:
 # wired. serena = live LSP symbol navigation (default, no index to maintain);
 # graphify = persistent tree-sitter knowledge graph over code + docs (needs an
 # index step + rescans); none = agents fall back to Grep/Glob/Read.
-# Registered by /cohorte-init-pipeline as a project-scope MCP server (committed .mcp.json).
+# Registered by /cohorte-init-pipeline in the runtime's project MCP configuration.
 retrieval:
   provider: serena                            # serena | graphify | none
 
@@ -53,12 +53,16 @@ surfaces:
   - key: backend                              # short id, used as agent name + scope
     path: apps/api                            # the ONLY tree this surface's agent may touch
     label: backend (AdonisJS)
-    agent: backend                            # rendered as backend.md in this runtime's agents dir
+    agent: backend                            # rendered in the runtime's project agents dir
     tools: [Read, Write, Edit, Bash, Grep, Glob, mcp__serena]   # mcp__<provider> mirrors retrieval.provider
+<!-- cohorte:if runtime:codex -->
+    model: inherit                            # omit the TOML model pin; explicit Codex models also allowed
+<!-- cohorte:else -->
     model: sonnet                             # frontmatter model tier: sonnet | haiku | inherit
                                               #   sonnet = default (applies the frozen contract — cheap
                                               #   vs the Opus lead); haiku = purely mechanical scaffolding;
                                               #   inherit = only for surfaces with real design decisions
+<!-- cohorte:endif -->
     test_cmd: pnpm --filter api test
     # Bridled variants — what agents actually RUN (dot reporter / failures-only /
     # --quiet), so a green run costs lines, not pages. "" ⇒ callers fall back to
@@ -76,10 +80,14 @@ surfaces:
     label: frontend (React/TanStack)
     agent: frontend
     tools: [Read, Write, Edit, Bash, Grep, Glob, DesignSync, mcp__serena]
+<!-- cohorte:if runtime:codex -->
+    model: inherit                            # use the session model unless explicitly configured
+<!-- cohorte:else -->
     model: sonnet                             # default even for design surfaces — designs + contract are
                                               #   frozen inputs the agent applies; `inherit` (bills at the
                                               #   lead's tier, often Opus) ONLY if this surface must make
                                               #   novel design decisions
+<!-- cohorte:endif -->
     test_cmd: pnpm --filter web test
     test_quiet_cmd: pnpm --filter web test --reporter=dot
     lint_cmd: pnpm --filter web lint

package/profile/SCHEMA.md

@@ -100,6 +100,28 @@ follow is provider-agnostic: _"prefer the retrieval MCP tools over Grep/Glob + w
 
 **Wiring (done by `/cohorte-init-pipeline`, or `/cohorte-update-pipeline` retroactively):**
 
+<!-- cohorte:if runtime:codex -->
+For `serena`, install its CLI if missing (`uv tool install -p 3.13 serena-agent`), then merge
+this project-scoped table into `.codex/config.toml`, preserving all existing settings:
+
+```toml
+[mcp_servers.serena]
+command = "sh"
+args = ["-c", 'exec "$(command -v serena || echo "$HOME/.local/bin/serena")" start-mcp-server --context codex --project-from-cwd --open-web-dashboard False']
+```
+
+On Windows without `sh`, use `command = "serena"` and the server arguments directly; ensure
+the CLI is on PATH. Gitignore `.serena/`. Keep `CODEX_HOME` at its normal user location;
+the project table is discovered natively once the project is trusted.
+For `graphify`, install its CLI and build/update the graph according to the provider's instructions;
+verify any required MCP registration in `.codex/config.toml` rather than `.mcp.json`.
+
+**Health check:** verify (1) `command -v serena`, (2) the `[mcp_servers.serena]` table,
+(3) `.serena/` ignored, (4) actual tools in the session. `codex mcp list` inspects registration,
+but is not proof of a live connection; restart the session when needed and report that limitation.
+Codex agents inherit MCP configuration; do not write a Claude `tools:` allowlist.
+Teammates receive `.codex/config.toml` and need the provider CLI installed and the project trusted.
+<!-- cohorte:else -->
 - `serena` — requires the `serena` CLI (`uv tool install -p 3.13 serena-agent`). For day-to-day CLI
   use it should also be on PATH (`uv tool update-shell`; uv installs to `~/.local/bin`). Register at
   **project scope** so the registration is committed and portable (`--project-from-cwd` resolves the
@@ -143,6 +165,7 @@ Report each check's result; never report Serena "wired" on registration alone.
 Teammates cloning the repo get the committed `.mcp.json` and only need the provider CLI installed
 and on PATH — if either is missing, the MCP server fails to start and agents silently fall back to
 Grep/Read; the health check above is the diagnostic.
+<!-- cohorte:endif -->
 
 ## Specialization — when to split one surface into more agents
 
@@ -412,6 +435,11 @@ this exact procedure so a surface is always defined the same way. To add surface
    scaffolding; `inherit` only when the surface makes real design decisions worth the lead's model),
    the five `*_cmd`s (derive from the surface's `package.json` / workspace
    filter, mirroring a sibling surface), and `uses_design`.
+<!-- cohorte:if runtime:codex -->
+   **Codex model policy:** use `model: inherit` by default, or a model explicitly selected for
+   Codex. Legacy `sonnet`/`haiku` values are not executable Codex pins: omit them in the rendered
+   agent and report inheritance. Preserve explicit Codex `model`/`model_reasoning_effort` choices.
+<!-- cohorte:endif -->
 2. **Render the agent file** `<agents>/<agent>.md` from `<core>/pipeline/implementer.template.md`
    — the template is already rendered for this runtime, so only the placeholders are yours to fill —
    substituting `<SURFACE_AGENT>`, `<SURFACE_LABEL>`,
@@ -440,6 +468,16 @@ this exact procedure so a surface is always defined the same way. To add surface
      says `none`): `DesignSync get_file(<projectId>, <file>)` for each link in the slot and translate
      each into the code design system (`@/components/ui/*`, `cn()` + CVA), mobile-first — never ad-hoc
      CSS. Then:"_
+<!-- cohorte:if runtime:codex -->
+   **Codex destination and format:** always write `.codex/agents/<agent>.toml` in the current
+   project, including with a global core. The source template has a `.md` filename but contains
+   TOML for this runtime. Validate TOML after substitutions; keep `name`, `description`, and
+   `developer_instructions`. Do not add Claude `tools:`/`model: sonnet` frontmatter.
+   Keep generic agents under `<fixed-agents>/`; never write surface agents there in global mode.
+   No `CODEX_HOME` override, auth symlink or per-project launcher is needed. When migrating an
+   old global surface agent, compare ownership/content with this project's profile before
+   removing its old copy; do not overwrite local customizations or touch other projects' agents.
+<!-- cohorte:endif -->
 3. **Add a §Conventions + §Testing stanza** for `S` in `PIPELINE.md` (mirror a sibling surface; keep it
    rule-shaped). If `S` is a shared-code surface, its convention is "single owner of shared X; slices
    consume, never redefine."
@@ -695,4 +733,3 @@ added vs. moved vs. already-correct.
 `<obsidian.vault_path>/<folder>/Tasks.md` with the `kanban-plugin: board` front-matter, one `## <heading>`
 per configured column in pipeline order, and the closing `%% kanban:settings %%` block
 (`{"kanban-plugin":"board","list-collapse":[false,…]}` with one `false` per column).
-

package/scripts/test-adapter.mjs

@@ -269,7 +269,76 @@ for (const id of RUNTIMES) {
     const text = readFileSync(step, "utf8");
     check(`${id}: templates carry no unresolved marker`, !/cohorte:(if|else|endif)/.test(text));
     check(`${id}: the settings/hook step matches this runtime`,
-      text.includes("Write `.claude/settings.json`") === rt.capabilities.hooks);
+      text.includes("Write `.claude/settings.json`") === (rt.capabilities.hooks && id !== "codex"));
+    if (id === "codex") {
+      check("codex: init generates native project agents and MCP config",
+        text.includes('.codex/agents/<agent>.toml') && text.includes('.codex/config.toml')
+        && !text.includes('render `<agents>/<agent>.md`') && !text.includes('`review.md`'));
+      const schema = readFileSync(join(p.core, 'pipeline', 'SCHEMA.md'), 'utf8');
+      check("codex: reconciliation preserves TOML destinations and Codex MCP context",
+        schema.includes('`<agents>/<agent>.toml`') && schema.includes('--context codex')
+        && !schema.includes('claude mcp add'));
+      const doctor = readFileSync(join(cmdDir, 'cohorte-doctor', 'SKILL.md'), 'utf8');
+      check("codex: doctor understands inherited models and TOML",
+        doctor.includes('Missing `model` means inheritance, not an error')
+        && !doctor.includes('sonnet/haiku/haiku'));
+      const update = readFileSync(join(cmdDir, 'cohorte-update-pipeline', 'SKILL.md'), 'utf8');
+      check("codex: update selects its runtime and does not demand Claude workflows",
+        update.includes('update --runtime=codex') && !update.includes('claude mcp add')
+        && !update.includes('`<core>/workflows/` + `agents/profile-reader.md`'));
+      const template = readFileSync(join(p.core, 'pipeline', 'PIPELINE.template.md'), 'utf8');
+      check("codex: new profiles default to inheritance",
+        /model: inherit/.test(template) && !/model: sonnet/.test(template));
+      const implementer = readFileSync(join(p.core, 'pipeline', 'implementer.template.md'), 'utf8');
+      check('codex: implementers are not accidentally pinned to a read-only sandbox',
+        !/^sandbox_mode = "read-only"/m.test(implementer));
+    }
+  }
+}
+
+group("codex — global core, project-local surfaces, native TOML");
+{
+  const env = { ...process.env, HOME: home, CLAUDE_CONFIG_DIR: '' };
+  const r = spawnSync(process.execPath,
+    [join(root, 'bin/cli.js'), 'install', '--global', '--runtime=codex'],
+    { cwd: proj, env, encoding: 'utf8' });
+  check('global Codex install succeeds', r.status === 0, r.stderr);
+  const init = readFileSync(join(home, '.agents/skills/cohorte-init-pipeline/SKILL.md'), 'utf8');
+  check('global skill resolves surfaces relative to whichever project invokes it',
+    init.includes('`<agents>` = `.codex/agents`') && !init.includes(proj));
+  check('generic agents retain their global destination',
+    existsSync(join(home, '.codex/agents/review.toml'))
+    && init.includes('`<fixed-agents>` = `~/.codex/agents`'));
+  const registry = JSON.parse(readFileSync(join(home, '.cohorte/codex/pipeline/runtimes.json'), 'utf8'));
+  check('global registry does not pin surface agents to the installer cwd',
+    registry.codex.paths.surface_agents === '.codex/agents'
+    && registry.codex.paths.agent_ext === '.toml');
+  const hook = JSON.parse(readFileSync(join(home, '.codex/hooks.json'), 'utf8')).hooks.PreToolUse[0];
+  check('installed Codex hook matches real shell and subagent calls',
+    ['Bash', 'spawn_agent', 'Agent'].every(n => new RegExp(hook.matcher).test(n)));
+  const rt = adapter.loadRuntime('codex');
+  const paths = adapter.resolvePaths(rt, 'global', proj);
+  const render = model => adapter.renderAgent({
+    source: `---\nname: example\ndescription: Test agent\nmodel: ${model}\nmodel_reasoning_effort: high\n---\nHandle literal ''' in instructions.`,
+    name: 'example', runtime: rt, paths, projectRoot: proj,
+  }).content;
+  const explicit = render('gpt-5.6-terra');
+  check('explicit Codex model and reasoning choices survive rendering',
+    explicit.includes('model = "gpt-5.6-terra"') && explicit.includes('model_reasoning_effort = "high"'));
+  check('inherit and legacy Anthropic aliases never become executable pins',
+    ['inherit', 'sonnet', 'haiku', 'opus'].every(m => !/^model =/m.test(render(m))));
+  const python = [process.env.COHORTE_TEST_PYTHON, 'python3', 'python'].filter(Boolean)
+    .find(p => spawnSync(p, ['-c', 'import tomllib']).status === 0);
+  if (!python) { check('Python 3.11+ available to validate emitted TOML', false); }
+  else {
+    const parsed = spawnSync(python, ['-c', 'import sys,tomllib; print(tomllib.loads(sys.stdin.read())["developer_instructions"])'],
+      { input: explicit, encoding: 'utf8' });
+    check('instructions containing triple apostrophes remain valid TOML',
+      parsed.status === 0 && parsed.stdout.includes("literal '''"), parsed.stderr);
+    const native = spawnSync(python, ['-c',
+      'import pathlib,sys,tomllib; [tomllib.loads(p.read_text()) for p in pathlib.Path(sys.argv[1]).glob("*.toml")]',
+      join(home, '.codex/agents')], { encoding: 'utf8' });
+    check('all installed generic agents parse as TOML', native.status === 0, native.stderr);
   }
 }
 

package/scripts/test-gate.mjs

@@ -395,6 +395,21 @@ console.log("gate.py — runtime dialects");
     cx.json?.hookSpecificOutput?.permissionDecision === "deny");
   check("…and the reason says why it was refused rather than queried",
     /no confirmation tier/.test(cx.json?.hookSpecificOutput?.permissionDecisionReason || ""));
+  for (const tool_name of ['spawn_agent', 'Agent']) {
+    const dispatch = raw({ tool_name, tool_input: { agent_type: 'review' }, cwd: d }, '--runtime', 'codex');
+    check(`codex: ${tool_name} with agent_type is denied without a preflight stamp`,
+      dispatch.json?.hookSpecificOutput?.permissionDecision === 'deny'
+      && /preflight/i.test(dispatch.json?.hookSpecificOutput?.permissionDecisionReason || ''));
+    check(`codex: ${tool_name} for an ungated implementer passes`,
+      raw({ tool_name, tool_input: { agent_type: 'backend' }, cwd: d }, '--runtime', 'codex').json === null);
+  }
+  const nativeCwd = spawnSync(python, [GATE, '--runtime', 'codex'], {
+    input: JSON.stringify({ tool_name: 'spawn_agent', tool_input: { agent_type: 'review' }, cwd: d }),
+    cwd: root, encoding: 'utf8',
+    env: { ...process.env, CLAUDE_PROJECT_DIR: '', COHORTE_PROJECT_DIR: '' },
+  });
+  check('codex: payload cwd locates project config without Claude environment variables',
+    JSON.parse(nativeCwd.stdout || '{}').hookSpecificOutput?.permissionDecision === 'deny');
 
   // Cursor sends the command at the top level and names no tool.
   const cu = raw({ hook_event_name: "beforeShellExecution", command: "git push", cwd: d },

package/scripts/test-lib.mjs

@@ -18,6 +18,7 @@ const require = createRequire(import.meta.url);
 const root = fileURLToPath(new URL("..", import.meta.url));
 const { parse, parseProfileBlock } = require(join(root, "lib/yaml.js"));
 const { state, scanSpecs } = require(join(root, "lib/doctor.js"));
+const adapter = require(join(root, 'core/adapter/render.js'));
 
 let failures = 0;
 const check = (name, cond, detail = "") => {
@@ -30,6 +31,11 @@ const eq = (name, got, want) =>
 const tmps = [];
 const scratch = () => { const d = mkdtempSync(join(tmpdir(), "cohorte-lib-")); tmps.push(d); return d; };
 const write = (p, s) => { mkdirSync(join(p, ".."), { recursive: true }); writeFileSync(p, s); };
+// Runtime discovery must not pick up Cohorte installations from the developer's real home.
+const os = require('node:os');
+const originalHomedir = os.homedir;
+os.homedir = () => isolatedHome;
+const isolatedHome = scratch();
 
 // ── yaml.js ──────────────────────────────────────────────────────────────────
 console.log("yaml.js — the profile parser");
@@ -55,7 +61,7 @@ console.log("yaml.js — the profile parser");
 
   // The real thing: the shipped template must round-trip.
   const tpl = readFileSync(join(root, "profile/PIPELINE.template.md"), "utf8");
-  const p = parseProfileBlock(tpl);
+  const p = parseProfileBlock(adapter.adaptInstructions(tpl, adapter.loadRuntime('claude')));
   check("the shipped PIPELINE.template.md parses", !!p);
   eq("…surfaces are a list of 2", (p.surfaces || []).length, 2);
   eq("…surface tools survive as an array", p.surfaces[0].tools.length, 7);
@@ -263,6 +269,46 @@ console.log("doctor.js — a non-Claude runtime layout");
     s.summary.bad === 0 && s.summary.warn === 0, JSON.stringify(s.summary));
 }
 
+// Codex's global core supplies fixed agents; each consuming repo owns its surfaces.
+{
+  const d = scratch();
+  const g = join(d, 'global');
+  write(join(g, 'pipeline/VERSION'), '9.9.9\n');
+  write(join(g, 'pipeline/runtimes.json'), JSON.stringify({ codex: {
+    label: 'Codex', scope: 'global', capabilities: { subagents: true, hooks: true, workflows: false },
+    paths: { core: g, agents: join(g, 'agents'), hooks_config: join(g, 'hooks.json'), state: '.cohorte' },
+  } }));
+  // Legacy registry intentionally has no surface_agents or agent_ext fields.
+  write(join(g, 'agents/unrelated.toml'), 'name = "unrelated"\n');
+  const hook = matcher => write(join(g, 'hooks.json'), JSON.stringify({ hooks: {
+    PreToolUse: [{ matcher, hooks: [{ command: `python3 ${g}/hooks/gate.py --runtime codex` }] }],
+  } }));
+  hook('Bash|shell');
+  const a = join(d, 'project-a'), b = join(d, 'project-b');
+  for (const repo of [a, b]) {
+    write(join(repo, 'PIPELINE.md'), '```yaml pipeline-profile\nname: example\nsurfaces:\n  - key: api\n    agent: api\nretrieval:\n  provider: serena\n```\n');
+    write(join(repo, '.codex/agents/api.toml'), 'name = "api"\ndescription = "API"\ndeveloper_instructions = "Implement"\n');
+    write(join(repo, '.codex/config.toml'), '[mcp_servers.serena]\ncommand = "serena"\n');
+  }
+  const inspect = repo => state({ projectRoot: repo, globalDir: g, cliVersion: '9.9.9' });
+  const status = (s, id) => s.checks.find(c => c.id === id)?.status;
+  let s = await inspect(a);
+  check('Codex doctor accepts project TOML agents with a legacy global registry', status(s, 'agents') === 'ok');
+  check('Codex doctor rejects a shell-only preflight hook', status(s, 'hooks') === 'warn');
+  check('Codex doctor finds native project MCP configuration', status(s, 'retrieval') === 'ok');
+  hook('Bash|spawn_agent');
+  s = await inspect(b);
+  check('a second project resolves its own agents without a launcher', status(s, 'agents') === 'ok');
+  check('Codex doctor accepts the native dispatch matcher', status(s, 'hooks') === 'ok');
+  write(join(b, '.codex/agents/stale.toml'), 'name = "stale"\n');
+  s = await inspect(b);
+  check('Codex doctor detects local orphans even with a global core', status(s, 'agents') === 'warn');
+  write(join(a, '.codex/config.toml'), '# [mcp_servers.serena]\n');
+  write(join(a, '.mcp.json'), JSON.stringify({ mcpServers: { serena: { command: 'serena' } } }));
+  s = await inspect(a);
+  check('a comment or Claude MCP config does not count as Codex registration', status(s, 'retrieval') === 'warn');
+}
+
 // ── runtime.js — stale absolute registry paths (a cloned/moved bundled core) ─
 // runtimes.json records install-time ABSOLUTE paths. A committed core cloned to
 // another machine (or a checkout simply moved) still carries the original paths;

package/scripts/validate-core.mjs

@@ -5,6 +5,8 @@
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+const { applyConditionals, loadRuntime } = createRequire(import.meta.url)('../core/adapter/render.js');
 
 // fileURLToPath, not .pathname — on Windows the latter yields "/C:/…", which
 // join() then resolves against the cwd drive ("C:\C:\…") and every read ENOENTs.
@@ -121,11 +123,14 @@ for (const p of ["profile/PIPELINE.template.md", "profile/SCHEMA.md",
   "profile/cohorte.config.template.yaml"])
   if (!existsSync(join(root, p))) fail(p, "missing");
 
-const tpl = read("profile/PIPELINE.template.md");
+const tpl = applyConditionals(read("profile/PIPELINE.template.md"), loadRuntime('claude'));
 if (/^\s*model:\s*inherit\b/m.test(tpl))
   fail("profile/PIPELINE.template.md",
     "a surfaces[] example pins `model: inherit` — examples must default to sonnet " +
     "(inherit bills at the lead session's model)");
+const codexTpl = applyConditionals(read('profile/PIPELINE.template.md'), loadRuntime('codex'));
+if (/^\s*model:\s*(sonnet|haiku|opus)\b/m.test(codexTpl))
+  fail('profile/PIPELINE.template.md', 'Codex examples must not pin Anthropic model aliases');
 
 // ── init-pipeline router steps ──────────────────────────────────────────────
 const steps = join(root, "core/templates/steps/init-pipeline");