cohorte 2.9.0 → 2.10.1

package/CHANGELOG.md

@@ -7,6 +7,39 @@ 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
+  dependency-free HTTP server, the Vite/React app and the prebuilt `dashboard/dist` that shipped
+  in every tarball — is removed, along with the fleet registry, kanban and usage readers that
+  only it consumed. It was a second surface for state the CLI already reports, with its own
+  build step, its own security posture (loopback-bound because its action endpoints executed
+  code: install, update, reset, and `/cohorte-init-pipeline`·`/cohorte-update-pipeline`·`/cohorte-audit`
+  through headless Claude), and its own drift to police. `cohorte doctor`, `cohorte specs` and
+  `cohorte metrics` answer the same questions from the shell, and `doctor` exits 1 on any bad
+  check, which the browser never could.
+
+  **What did not go with it:** the four modules those verbs actually run on — the JS port of
+  `/cohorte-doctor`, the runtime-layout resolver, the version prober and the block-YAML parser —
+  moved from `dashboard/server/` to **`lib/`**. `cohorte doctor` / `specs` / `version` behave
+  exactly as before, and so do the Francois extension's `--panel` payloads. Their test suite
+  moved with them (`scripts/test-dashboard.mjs` ⇒ `scripts/test-lib.mjs`, 54 assertions), minus
+  the cases that covered deleted code.
+
+  Fallout worth naming: the package no longer has a build step at all (`prepack` and
+  `build:dashboard` are gone, npm and CI no longer build a React app to publish), the tarball
+  drops from 88 files to 73, and `~/.claude/cohorte-dashboard.json` — the tracked-project list —
+  is now dead; delete it. `--port` / `--host` / `--open` and `COHORTE_DASHBOARD_PORT` /
+  `COHORTE_DASHBOARD_HOST` no longer exist; `cohorte dashboard` prints the usage and exits 2.
+
 ## 2.9.0 — 2026-08-22
 
 - **`/cohorte-intake` — the door before the doors.** Work has always entered the pipeline

package/README.md

@@ -24,6 +24,37 @@ Cursor, Gemini CLI or OpenCode. Install it once globally, then one command per p
   /cohorte-brainstorm → /cohorte-spec → (design) → /cohorte-build <id> → /cohorte-review → (/cohorte-fix) → /cohorte-ship
   ```
 
+<div align="center">
+  <img src="https://raw.githubusercontent.com/TheBidouilleAgency/cohorte/main/assets/demo-cli.gif" alt="cohorte doctor reporting a green pipeline, the spec board, and the gate denying a chained destructive command" width="760">
+  <br>
+  <sub><code>cohorte doctor</code> · the spec board · the gate refusing a hard-denied command chained behind a benign one.<br>
+  Recorded from the real CLI by <code>scripts/demo/record-cli.sh</code> — no output is hand-edited.</sub>
+</div>
+
+## Why a pipeline at all
+
+Your coding agent is already good at the first prompt of a feature. It gets worse at every one
+after — because what it knows lives in a conversation, and a conversation gets summarised,
+truncated, and re-sent at input price on every turn. Cohorte is the set of constraints that stop
+that degradation. Each one is a failure you have already had:
+
+| The failure | The constraint |
+| --- | --- |
+| *"It forgot what we decided."* | The spec is **frozen to disk** and re-read by every stateless agent. Nothing is remembered, so nothing is forgotten — and `/clear` between stages is always safe. |
+| *"The API and the UI don't fit."* | The **contract is authored before any implementer is dispatched**. Surfaces import it read-only and never talk to each other — which is what makes building them in parallel safe. |
+| *"It edited a file I didn't want it to."* | **One owner per tree**, enforced in the rendered agent's frontmatter — not requested politely in a prompt. |
+| *"It ran something it shouldn't have."* | `gate.py` is a **real blocking hook**, branch-aware, hard-denying destructive commands from every agent — subagents included. |
+| *"The review said it was fine."* | Review is a **separate read-only agent** that sees the spec and the diff, never the conversation that produced them. A dead reviewer's zero findings can't read as ship. |
+| *"Four agents just told me it doesn't compile."* | A **deterministic preflight** runs typecheck/lint/tests first. Red ⇒ **zero agents spawned**. |
+| *"We fixed this same thing last week."* | `/cohorte-retro` turns repeated findings into ratified conventions **baked into the implementers**, so the next build never produces them. |
+
+None of this is intelligence added to your agent — it's the opposite. It moves the decisions an
+agent makes badly under context pressure into files, hooks and ownership boundaries, where they're
+cheap and don't degrade with conversation length. Which is why it's markdown, shell and one Python
+hook: **your app code never imports anything from Cohorte.**
+
+[**The long version — including the four cases where you shouldn't use it →**](https://thebidouilleagency.github.io/cohorte/guide/why-cohorte)
+
 ## How it works — three layers
 
 | Layer | What it holds | Lives in | Scope |
@@ -206,45 +237,6 @@ decisions), surface agents are re-rendered, settings are patched additively, new
 wired. **`/cohorte-init-pipeline` is one-time per project** — after init, `/cohorte-update-pipeline` is the only
 maintenance command you ever run (`/cohorte-build` auto-grows surfaces as specs need them).
 
-## Dashboard — a local web cockpit
-
-A browser view of pipeline state, for when a checklist beats scanning files:
-
-```sh
-cohorte dashboard          # serves http://localhost:4317 (Ctrl-C to stop)
-cohorte dashboard <path>   # start focused on another project
-cohorte dashboard --port=4400 --open   # custom port, open the browser
-```
-
-**Bound to `127.0.0.1` by default** — the dashboard's actions execute code (install/update/reset,
-and `/cohorte-init-pipeline`·`/cohorte-update-pipeline`·`/cohorte-audit` via headless Claude), so it must stay on loopback. Each user
-runs their own agent and drives only their own machine. `--host=0.0.0.0` exposes it to the network
-(it prints a security warning) — only on a trusted network, since anyone who reaches the port can run
-those actions.
-
-- **Fleet overview** — the global core version vs npm latest, plus every tracked project's freshness
-  and health at a glance. Add a project by absolute path or with the **folder picker** (Browse…); the
-  set is remembered in `~/.claude/cohorte-dashboard.json`.
-- **Per-project drill-down** — Freshness (installed core vs npm), `/cohorte-doctor` rendered as a live
-  ✅/⚠️/❌ checklist (each failure with its fix), the **Surfaces ↔ agents** map from `PIPELINE.md`,
-  and one board: a **Kanban** if the project has a linked Obsidian board (columns + cards from the
-  vault, with clickable PR links + live open/merged/closed status and a ship-date-sorted Shipped
-  column, via `gh`), otherwise a **Specs board** from `specs/*.md` (by `draft · frozen · in-progress ·
-  in-review · blocked · shipped`). The Kanban supersedes the Specs board when both would apply.
-- **Actions** (stream their output live) — **Update / Install core** (the shared global core, or a
-  repo's bundled core); **Init-pipeline / Update-pipeline / Audit**, which run those Claude Code
-  commands **headless** (`claude -p`, autonomous — Init skips the interactive interview, so review
-  the result; Audit writes `specs/refactor-backlog.md`; headless runs start without any prompt and
-  have **no resume** if the session dies); and **Reset pipeline**, which backs up then wipes a
-  project's pipeline footprint and reinstalls a fresh core. Buttons render only when they apply
-  (e.g. Init only when there's no profile). The drill-down's health checklist also shows the
-  **workflows** state (scripts + profile-reader installed, which path a session will take).
-
-Runtime is **dependency-free** — node's built-in `http` server serves a prebuilt React app (the app
-source lives in `dashboard/app/`, built to `dashboard/dist/` at publish time). The `/cohorte-doctor` checks
-are reimplemented in JS, so the dashboard needs no Claude session to compute state. See
-[`dashboard/README.md`](dashboard/README.md) for the architecture.
-
 ## Reading a project without an agent
 
 The two read-only halves of the pipeline, in the shell:
@@ -260,8 +252,8 @@ extension below renders.
 
 `doctor`'s exit code makes it a CI step as-is. Add `--porcelain` for one record per line with
 `U+001F` between fields (a spec title with a space in it never misaligns a column), or `--json`
-for the native document. Both reuse the dashboard's own readers, so the board and the CLI can
-never give two answers about one repo.
+for the native document. Both read through `lib/`, so every consumer — the CLI, a Francois
+panel — answers from one implementation and the repo never gets two verdicts.
 
 `--panel` — on `specs`, `doctor` and `metrics` — emits the payload shape a
 [Francois](https://github.com/antoine-gmnz/francois) extension panel expects. It is the one
@@ -418,7 +410,10 @@ See `profile/SCHEMA.md` for every field in `PIPELINE.md` and how the pipeline us
 
 ```
 package.json            # npm package (cohorte) — semver source of truth
-bin/cli.js              # the npm CLI: install / update / dashboard / specs / doctor / metrics / version (cross-platform, no deps)
+bin/cli.js              # the npm CLI: install / update / specs / doctor / metrics / version (cross-platform, no deps)
+bin/report.js           # the four renderings of `specs` / `doctor` (human, porcelain, json, panel)
+lib/                    # shared readers behind those verbs — doctor.js (the JS port of
+                        #   /cohorte-doctor) + runtime.js / versions.js / yaml.js. No deps.
 install.sh              # script installer (fresh + --update) for npm-less setups — still needs Node
 install.ps1             # same installer for Windows PowerShell (fresh + -Update)
 core/                   # copied verbatim into ~/.claude (global) or <project>/.claude (bundled)
@@ -432,7 +427,4 @@ profile/
   SCHEMA.md             # field reference
   cohorte.config.template.yaml   # seeds ~/.claude/cohorte.config.yaml (kanban)
 scripts/                # worktree-isolation templates + the shipped preflight/kanban scripts
-dashboard/              # local web cockpit (cohorte dashboard) — see dashboard/README.md
-  server/               # dependency-free node runtime (serves the built app + JSON/stream API)
-  app/                  # Vite + React source (built to dashboard/dist/ at publish time)
 ```

package/bin/cli.js

@@ -40,7 +40,6 @@ function usage(code) {
 Usage:
   cohorte install   [target] [--global] [--runtime=a,b | --all-runtimes]
   cohorte update    [target] [--global] [--runtime=a,b | --all-runtimes]
-  cohorte dashboard [target] [--port=N] [--host=ADDR] [--open]
   cohorte metrics   [target] [--days=N] [--since=ISO] [--runs] [--json]
   cohorte specs     [target] [--porcelain | --json | --panel]
   cohorte doctor    [target] [--porcelain | --json | --panel]
@@ -53,11 +52,6 @@ Commands:
   update    Refresh the stack-agnostic core only. PIPELINE.md, rendered surface
             agents, gate-config.json, settings.json and your filled
             ~/.claude/cohorte.config.yaml are never touched.
-  dashboard Serve a local web cockpit for the pipeline (freshness, /cohorte-doctor
-            health, specs board, install/update actions). Binds 127.0.0.1:4317
-            by default (loopback only — its actions execute code). --host=ADDR
-            to expose (e.g. --host=0.0.0.0, prints a security warning). --open
-            to launch the browser.
   metrics   Cost and runtime per command, reconstructed from Claude Code's own
             transcripts (tokens, USD, wall/active time, subagent count). Reads
             ~/.claude/projects — nothing to enable, and it covers runs that
@@ -90,11 +84,6 @@ const args = process.argv.slice(2);
 let mode = null;
 let scope = 'project';
 let target = process.cwd();
-let port = parseInt(process.env.COHORTE_DASHBOARD_PORT, 10) || 4317;
-// Bind to loopback by default — the dashboard's action endpoints execute code (install/update/
-// reset/claude), so it must NOT be reachable from the network unless the user explicitly opts in.
-let host = process.env.COHORTE_DASHBOARD_HOST || '127.0.0.1';
-let openBrowser = false;
 
 // Flags that belong to `metrics` and are forwarded verbatim to the collector. They are
 // listed here rather than parsed, so the collector stays the single source of truth for
@@ -112,7 +101,7 @@ let format = 'human';
 let wantRuntimes = [];
 
 for (const a of args) {
-  if (a === 'install' || a === 'update' || a === 'dashboard' || a === 'metrics'
+  if (a === 'install' || a === 'update' || a === 'metrics'
       || a === 'specs' || a === 'doctor') mode = a;
   else if (a === '--porcelain' || a === '--panel') format = a.slice(2);
   else if (isMetricsFlag(a)) { if (a === '--json') format = 'json'; metricsFlags.push(a); }
@@ -131,40 +120,18 @@ for (const a of args) {
   }
   else if (a === 'version' || a === '--version' || a === '-v') { console.log(VERSION); process.exit(0); }
   else if (a === '--global' || a === '-g') scope = 'global';
-  else if (a.startsWith('--port=')) {
-    // A bad value used to land as NaN, which http.listen() silently treats as
-    // "any free port" — the banner then printed `localhost:NaN` and nothing worked.
-    port = parseInt(a.slice(7), 10);
-    if (!Number.isInteger(port) || port < 1 || port > 65535) {
-      console.error(`error: --port must be an integer 1-65535 (got "${a.slice(7)}")`);
-      process.exit(2);
-    }
-  } else if (a.startsWith('--host=')) {
-    host = a.slice(7).trim();
-    if (!host) { console.error('error: --host= needs an address (e.g. --host=0.0.0.0)'); process.exit(2); }
-  }
-  else if (a === '--open') { openBrowser = true; }
   else if (a === 'help' || a === '--help' || a === '-h') usage(0);
   else if (a.startsWith('-')) { console.error(`error: unknown flag: ${a}`); usage(2); }
   else target = path.resolve(a);
 }
 if (!mode) usage(args.length ? 2 : 0);
 
-// --- dashboard: local web cockpit -------------------------------------------
-// Short-circuits before the install/update machinery (CommonJS wraps the module,
-// so a top-level return is valid here). Runtime is dependency-free node `http`.
-if (mode === 'dashboard') {
-  const globalDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
-  require('../dashboard/server')({ projectRoot: target, globalDir, port, host, openBrowser, pkgRoot, version: VERSION });
-  return;
-}
-
 // --- specs / doctor: read-only reports on <target> ---------------------------
-// Both reuse the dashboard's own readers, so the board and the CLI can never drift
-// into two answers about the same repo. Nothing here writes or spawns anything.
+// Both read through lib/, so every consumer of the pipeline's state — the CLI, a
+// Francois panel — answers from one implementation. Nothing here writes or spawns.
 if (mode === 'specs' || mode === 'doctor') {
   const report = require('./report.js');
-  const { state, scanSpecs } = require('../dashboard/server/doctor.js');
+  const { state, scanSpecs } = require('../lib/doctor.js');
   const globalDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 
   if (mode === 'specs') {
@@ -253,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));
   }
 }
 
@@ -342,8 +308,10 @@ function copyCore() {
     paths: {
       core: paths.core, commands: paths.commands,
       agents: paths.agents || path.join(paths.core, 'agents'),
-      // Where the gate registration lives. The dashboard needs it to tell a registered hook
-      // from a missing one without re-deriving each runtime's config layout itself.
+      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,
       state: adapter.stateDir(runtime), config: adapter.configPath(runtime),
     },
@@ -565,7 +533,7 @@ async function seedConfig() {
   //
   // CLAUDE_CONFIG_DIR moves the whole `~/.claude` tree (globalDir already follows it), but
   // adapter.configPath() speaks in literal `~/.claude/…` — expanding through HOME alone
-  // seeded a file at a path no reader probes (kanban-move.sh and the dashboard follow
+  // seeded a file at a path no reader probes (kanban-move.sh follows
   // CLAUDE_CONFIG_DIR), missed a filled config there (re-seeding disabled defaults beside
   // it — the exact two-file fork this function's comments forbid), and printed a banner
   // path that did not exist. Re-root the claude-shaped path onto globalDir so the seed,
@@ -705,7 +673,7 @@ async function staleVersionNotice() {
   if (process.env.COHORTE_NO_VERSION_CHECK || process.env.CI) return;
   let latest = null;
   try {
-    const v = require('../dashboard/server/versions.js');
+    const v = require('../lib/versions.js');
     latest = await v.latestNpm({ timeoutMs: 2500, fallback: false });
     if (!latest || v.cmpSemver(VERSION, latest) >= 0) return;
   } catch { return; }
@@ -767,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/bin/report.js

@@ -1,8 +1,8 @@
 'use strict';
 // Machine-readable reports for `cohorte specs` and `cohorte doctor`.
 //
-// Both commands read what the dashboard already computes (dashboard/server/doctor.js:
-// `scanSpecs` and `state`) and render it four ways:
+// Both commands read what lib/doctor.js computes (`scanSpecs` and `state`) and
+// render it four ways:
 //
 //   default      a human table on a terminal
 //   --porcelain  one record per line, fields separated by U+001F (the ASCII unit

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-fleet.md

@@ -14,9 +14,8 @@ nothing more.
 fire a loop per worktree from here — is the 2.2.0 driver's grave: child sessions nobody
 supervises, stalling on prompts nobody sees. Each feature's build/review/loop runs in **its own
 worktree's session**, supervised like any other; the fleet plans, watches and rebases. State
-lives in `specs/reports/fleet.json` (the main checkout's gitignored buffer — not to be confused
-with the dashboard's multi-*project* fleet registry; this file is this repo's multi-*feature*
-flight plan).
+lives in `specs/reports/fleet.json` (the main checkout's gitignored buffer — this repo's
+multi-*feature* flight plan).
 
 > Read `PIPELINE.md` §`pipeline-profile` first: `surfaces` (paths — the overlap analysis keys
 > on them), `contract`, `vcs.default_branch`, and the `isolation` block. _Skip the re-read if

package/core/commands/cohorte-ship.md

@@ -98,8 +98,8 @@ watch, rather than letting the job go red.
 **Move the card to Shipped — required, and verify it actually moved.** Run
 `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS shipped --pr <num>`, which **appends the PR
 number** so the line reads `- [ ] <title> #$ARGUMENTS — PR #<num>`. Take `<num>` from the PR URL
-(`…/pull/13` ⇒ `13`); **always pass it when a PR was created** (the `gh` path) — it is what the
-dashboard turns into a PR link. If only a compare URL was emitted (no PR yet), drop `--pr`.
+(`…/pull/13` ⇒ `13`); **always pass it when a PR was created** (the `gh` path) — it is what a
+board reader turns into a PR link. If only a compare URL was emitted (no PR yet), drop `--pr`.
 
 Then **read the script's own output**, which is the verification: `moved #$ARGUMENTS -> Shipped
 (PR #<num>)` means done, and a `kanban: <reason>` line means the mirror is off and says why. Both are

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).