cohorte 2.9.0 → 2.10.1

package/core/hooks/gate.py

@@ -23,7 +23,7 @@ and subagents spawned by the Workflow runtime alike. Workflow subagents run in
 acceptEdits regardless of the session's permission mode (their Write/Edit calls
 are auto-approved), but acceptEdits does NOT auto-approve Bash or Task, so this
 gate still sees and can block them. In bypassPermissions (headless `claude -p`,
-dashboard actions) there is no human to answer a prompt, so every `ask` match is
+unattended workflow runs) there is no human to answer a prompt, so every `ask` match is
 escalated to a hard deny with the reason attached — a clear refusal beats a
 prompt that can never be answered.
 
@@ -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/core/workflows/review.js

@@ -395,7 +395,7 @@ const staging = await agent(
     : 'the blocking list is empty, so <FP> is the empty string "":\n') +
   `${verdictJson}\n` +
   // Per-surface verdicts (not the merged one stamped on every row — one BLOCK used to
-  // mark ALL surfaces failed on the dashboard), and dead reviewers logged as "dead"
+  // mark ALL surfaces failed), and dead reviewers logged as "dead"
   // per SCHEMA.md §Dead agents — an incomplete batch is the batch worth recording.
   `3. Append one line to $(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl: ` +
   `{"ts":"<ISO now>","feature":"${feature}","phase":"review","seconds":0,"tokens":${Math.max(0, spentNow() - spentStart)},"surfaces":{${

package/{dashboard/server → lib}/doctor.js

@@ -1,12 +1,13 @@
 'use strict';
-// Programmatic port of the /cohorte-doctor checks (core/commands/doctor.md), for the dashboard.
+// Programmatic port of the /cohorte-doctor checks (core/commands/cohorte-doctor.md), so
+// `cohorte doctor` can report without a coding agent in the loop.
 // Read-only: inspects files only. Checks that need a live process (MCP connectivity,
 // git worktree state, DesignSync) are reported as `skip` with a note — the node server
 // can't run them, and honest "not checked here" beats a false green.
 
 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');
 
@@ -53,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) {
@@ -98,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));
 
@@ -247,7 +258,7 @@ function gateRegs(settingsPath, event) {
 
 function checkHooks(projectRoot, globalDir, installMode, all) {
   // A registration can exist without a discoverable core — a repo whose core lives in a global
-  // dir the dashboard was not pointed at, or one predating `runtimes.json`. Falling through to
+  // dir the caller was not pointed at, or one predating `runtimes.json`. Falling through to
   // "no runtime installed" there would hide a real double-registration, so assume the Claude
   // layout: before the adapter it was the only one, and it is the only one whose hook can be
   // registered outside its own core dir.
@@ -275,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
@@ -286,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})`);
@@ -297,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}` : ''})`);
@@ -318,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.
@@ -460,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/{dashboard/server → lib}/runtime.js

@@ -1,7 +1,7 @@
 'use strict';
 // Which coding agent(s) this project is wired for, and where each one keeps its files.
 //
-// Before 2.2.0 every path in the dashboard was `.claude/…`. That is now one layout of five:
+// Before 2.2.0 every path here was `.claude/…`. That is now one layout of five:
 // a repo driven from Cursor keeps its core in `.cohorte/cursor/`, its agents in
 // `.cursor/agents/` and its gate registration in `.cursor/hooks.json`. Checking the Claude
 // paths there reports a perfectly healthy install as broken — "no core", "no rendered agent",
@@ -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/{dashboard/server → lib}/versions.js

@@ -30,12 +30,12 @@ function pointerAt(projectRoot) {
 
 // Latest published version — registry fetch first, `npm view` as a fallback (it uses the
 // user's configured registry/proxy, which works where a raw fetch may be blocked). Cached
-// briefly so the dashboard's poll doesn't hammer the network. null only if both fail.
+// briefly so repeated calls don't hammer the network. null only if both fail.
 let _cache = { value: null, at: 0 };
 const CACHE_MS = 5 * 60 * 1000;
 // Failures are cached too, briefly. Without this an offline machine paid the FULL
 // 5s fetch timeout + 8s `npm view` timeout on every call — and /api/fleet calls
-// this once per tracked project, so the dashboard's 15s poll never finished.
+// this once per tracked project, so a batch of probes never finished.
 const FAIL_CACHE_MS = 60 * 1000;
 
 async function fetchRegistry(timeoutMs = 5000) {

package/package.json

@@ -1,26 +1,21 @@
 {
   "name": "cohorte",
-  "version": "2.9.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"
   },
-  "scripts": {
-    "build:dashboard": "npm --prefix dashboard/app ci && npm --prefix dashboard/app run build",
-    "prepack": "npm run build:dashboard"
-  },
   "files": [
     "bin",
+    "lib",
     "core",
     "profile",
     "scripts",
     "!scripts/new-feature.sh",
     "!scripts/remove-feature.sh",
+    "!scripts/demo",
     "!core/hooks/__pycache__",
     "!**/*.pyc",
-    "dashboard/server",
-    "dashboard/dist",
-    "dashboard/README.md",
     "install.sh",
     "install.ps1",
     "CHANGELOG.md"

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
 
@@ -176,7 +199,7 @@ the **main checkout's** `<state>/pipeline-metrics.jsonl` (gitignored) — one JS
 and `/cohorte-fix`.
 **`surfaces` keys are surface keys, nothing else** — run-level facts go in their own top-level
 fields. Anything put inside `surfaces` is read
-as a surface: the dashboard renders it as a row in the per-surface table and scores a non-`ok`
+as a surface: `cohorte doctor` renders it as a row in the per-surface table and scores a non-`ok`
 value as that surface failing. Always the main checkout, never the feature worktree (which dies at teardown while
 metrics must accumulate across features) — resolve from anywhere with
 `$(dirname "$(git rev-parse --git-common-dir)")/<state>/pipeline-metrics.jsonl`. Read it before
@@ -189,7 +212,7 @@ what's SLOW. Tokens are recorded only where they can be read honestly: the **wor
 (`loop.js`, `review.js`) stamp an approximate `tokens` field per batch from the runtime's own
 counter (`budget.spent()` deltas), and the loop's return carries a per-round breakdown in its
 `history`. The **conversational** commands still record none — a lead cannot reliably read a
-subagent's token count, and a guessed number is worse than a missing one. The dashboard sums
+subagent's token count, and a guessed number is worse than a missing one. `cohorte metrics` sums
 whatever is stamped (a token-less line aggregates as 0, rendered as absent, never as "free").
 For exact spend, use Claude Code's own accounting:
 
@@ -231,7 +254,7 @@ storing a bare `pnpm test` as the thing agents execute; `/cohorte-update-pipelin
 ## Spec status — the lifecycle state machine
 
 A spec's front-matter `status` is not a label, it is the pipeline's **state**: every command routes on
-it, the dashboard boards on it, and the kanban backfill maps it to a column. Six states:
+it, `cohorte specs` boards on it, and the kanban backfill maps it to a column. Six states:
 
 | status | meaning | written by | who may build it |
 | --- | --- | --- | --- |
@@ -371,7 +394,7 @@ project has *decided*. Without somewhere for those, every `/cohorte-spec` re-dis
 - **Never read by implementers or reviewers.** They work from the frozen contract, which already tells
   them what to do; shipping them the rationale would cost `surfaces × dispatches` tokens per feature
   for a fact they cannot act on. This is what keeps the journal cheap enough to be worth having.
-- The `_` prefix is load-bearing: `/cohorte-doctor`, the dashboard spec scanner and the kanban backfill all skip
+- The `_` prefix is load-bearing: `/cohorte-doctor`, the `cohorte specs` scanner and the kanban backfill all skip
   `specs/_*.md`, so the journal is never mistaken for a spec (no phantom card, no bogus stage).
 
 ## Preflight — the deterministic phase gate
@@ -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."
@@ -626,7 +664,7 @@ notes a human writes as sub-bullets under an Ideas card are seed context for `/c
 the trailing `%% kanban:settings … %%` block or the `kanban-plugin: board` front-matter.
 
 Once shipped, `/cohorte-ship` appends the **PR number** to the card — `- [ ] <title> #<feature_id> — PR #<num>`.
-The bare `#<num>` is what the dashboard renders as a clickable link to the GitHub PR, so `/cohorte-ship` always
+The bare `#<num>` is what a board reader renders as a clickable link to the GitHub PR, so `/cohorte-ship` always
 writes it when a PR was actually created.
 
 **Move a card (the core op).** One call — the script does resolution AND the move outside the
@@ -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);
   }
 }