@maestrofrontier/frontier 1.4.4 → 1.4.5

package/README.md

@@ -17,15 +17,20 @@
   <a href="#the-frontier-engine"><img src="https://img.shields.io/badge/Frontier-fusion%20engine-f59e0b" alt="Frontier fusion engine"></a>
   <img src="https://img.shields.io/badge/agents-Claude%20Code%20%7C%20Gemini%20%7C%20Codex%20%7C%20Cursor-5b82d6" alt="Claude Code | Gemini | Codex | Cursor">
   <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey" alt="macOS | Linux | Windows">
-  <img src="https://img.shields.io/badge/install-2%20lines-blueviolet" alt="2-line plugin install">
+  <img src="https://img.shields.io/badge/install-plugins%20%2B%20portable-blueviolet" alt="Native plugins and portable installs">
   <a href="#contributing"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"></a>
 </p>
 
 <p align="center">
-  <sub>13 fixture tasks &middot; 123 valid A/B runs &middot; 11 voids excluded &amp; re-run &middot; 6 hooks, all tested &middot; ~8 KB always-on kernel &middot; 2-line plugin install</sub>
+  <sub>13 fixture tasks &middot; 123 valid A/B runs &middot; 11 voids excluded &amp; re-run &middot; 6 hooks, all tested &middot; ~8 KB always-on kernel &middot; plugin + portable installs</sub>
 </p>
 
-> **Install — run the one line for your tool, inside that tool.** Each installs only that tool's setup (the portable `AGENTS.md` doctrine, that tool's adapter, `docs/orchestration.md`, the Frontier engine, and that tool's `/frontier` command) — **append-only; it never overwrites or deletes your files.**
+> **Install — run the command block for your tool, inside that tool.**
+> Claude Code and Codex use native plugins. Cursor, Gemini, Cline,
+> Windsurf, and other CLIs use the portable installer, which copies
+> Maestro's runtime-agnostic files into the current project/workspace by
+> default. Global/user installs are optional when you intentionally want
+> cross-project behavior.
 
 **Claude Code / Desktop** — native plugin (enforcement hooks, `/maestro:*` commands, skills, status line, Frontier auto-run):
 
@@ -34,22 +39,75 @@
 /plugin install maestro@maestro
 ```
 
-**Every other CLI / Desktop app** — run its line in that tool's terminal, or just ask its agent to run it. It auto-targets that tool and installs nothing for the others:
+**Codex CLI / Desktop** — native Codex plugin via the Maestro repo
+marketplace (skills, trusted hooks, and Frontier auto-run after you review
+and trust the hooks):
+
+```text
+codex plugin marketplace add mbanderas/maestro
+codex plugin add maestro@maestro
+```
+
+Start a new Codex thread after installing or changing plugin trust so the
+bundled skills and hooks reload.
+
+**Portable installs for other CLI / Desktop apps** — run the matching line
+in that tool's terminal, or ask its agent to run it. These integrations are
+prompt/skill/workflow shortcuts around the portable CLI unless the tool has
+native hook support.
 
 | Tool | Install (run inside the tool) |
 |------|-------------------------------|
-| Codex (CLI / Desktop) | `npx github:mbanderas/maestro install --target codex` |
 | Cursor | `npx github:mbanderas/maestro install --target cursor` |
 | Gemini CLI | `npx github:mbanderas/maestro install --target gemini` |
 | Cline | `npx github:mbanderas/maestro install --target cline` |
 | Windsurf / Devin | `npx github:mbanderas/maestro install --target windsurf` |
 | Not sure / auto-detect | `npx github:mbanderas/maestro install --target auto` |
 
-Per tool it lays down `AGENTS.md` + that tool's adapter (`CLAUDE.md` / `GEMINI.md` / `.cursorrules`; Codex, Cline, and Windsurf read `AGENTS.md` directly), `docs/orchestration.md`, the zero-dependency Frontier engine, and that tool's `/frontier` command. Confirm with `maestro frontier status` (or `node bin/maestro.cjs frontier status` if `maestro` is not on PATH). Once published, swap `github:mbanderas/maestro` for `@maestrofrontier/frontier`.
+Portable installs lay down `AGENTS.md` plus that tool's adapter or
+integration file, `docs/orchestration.md`, the zero-dependency Frontier
+engine, and the relevant command/skill files. Codex does not need that copy
+path for normal use: the repo is its marketplace
+(`.agents/plugins/marketplace.json`) and plugin
+(`.codex-plugin/plugin.json`), bundling the Codex skills, hooks, Frontier
+engine, settings CLI, commands, and `docs/codex.md`. The older
+`maestro install --target codex` path remains a manual fallback when you
+intentionally want project files instead of the plugin. Once published, swap
+`github:mbanderas/maestro` for `@maestrofrontier/frontier` for portable npm
+installs.
+
+> **Want the bare `maestro` command on your `PATH`?** Native plugins can run
+> the bundled engine from their plugin cache, and portable installs can run
+> `node bin/maestro.cjs frontier ...` from the installed project root. Install
+> globally only if you want to type `maestro` from any shell:
+> `npm install -g github:mbanderas/maestro` (swap for
+> `@maestrofrontier/frontier` once published), then fully restart the tool so
+> it picks up the new `PATH`.
+
+Frontier stays **off** until you arm it, then normal prompts auto-route until
+disabled in runtimes with trusted hooks.
+
+- Claude Code: `/maestro:frontier fusion opus-gpt` (or
+  `/maestro:frontier off`).
+- Codex: after installing the plugin and trusting hooks, ask the bundled
+  `maestro-frontier` skill to arm the project scope, for example "Use
+  Maestro Frontier with ChatGPT duo", "Show Maestro Frontier status", or
+  "Turn Maestro Frontier off." The skill runs the plugin-bundled engine; no
+  `npx` or global `maestro` binary is required.
+- Shell/advanced: from a checkout or global install, the equivalent CLI form
+  is:
 
-> **Want the bare `maestro` command (and the `/frontier` command it powers) on your `PATH`?** The `npx … install` above copies files into the project but does **not** register a global `maestro` binary — so the dropped `/frontier` command and the Codex skills, which call a bare `maestro`, will report `maestro: not recognized` until you add it. Install it once globally — `npm install -g github:mbanderas/maestro` (swap for `@maestrofrontier/frontier` once published) — then fully restart the tool so it picks up the new `PATH`. Without the global install, drive the engine with the `node bin/maestro.cjs frontier …` form from the project root instead.
+```text
+maestro frontier mode fusion --preset chatgpt-duo --scope codex-project
+maestro frontier mode fusion --preset frontier-trio --judge chatgpt --synth chatgpt --scope codex-project
+maestro frontier mode off --scope codex-project
+```
 
-Frontier stays **off** until you arm it: `/maestro:frontier fusion opus-gpt` (Claude Code) or `maestro frontier mode fusion --preset opus-gpt --scope <tool>` elsewhere (armed state stays per-CLI-global; `--scope codex`/`cursor`/`gemini`/`cline`/`windsurf`).
+Use `node bin/maestro.cjs frontier ...` in place of `maestro frontier ...`
+when the binary is not on `PATH`. `codex-project` expands to the repo's
+`codex-<8hex>` workspace scope, matching the trusted Codex plugin hook.
+`maestro frontier run "<prompt>" ...` is still available for advanced/debug
+one-offs, but arming mode is the normal autorun flow.
 
 ---
 
@@ -70,12 +128,14 @@ members — fusing the CLIs you already run buys frontier-tier results. It
 is the project's new default identity; the doctrine, hooks, skills, and
 benchmarks are unchanged; the discipline layer is its foundation.
 
-It ships with the plugin and is driven by `/maestro:frontier`. Three
-modes, switched at will, **`off` by default** so installing or
-upgrading changes nothing until you opt in. **Arming it — `single` or
-`fusion` — makes it auto-run on every prompt**: a `UserPromptSubmit`
-hook routes each prompt through the engine and the live session relays
-the synthesized answer. `off` is the disable path.
+It ships with the native plugins. Claude Code drives it with
+`/maestro:frontier`, Codex drives it with the `maestro-frontier` skill, and
+other CLIs can use `maestro frontier ...` or the `node bin/maestro.cjs
+frontier ...` fallback. Three modes, switched at will, **`off` by default**
+so installing or upgrading changes nothing until you opt in. **Arming it —
+`single` or `fusion` — makes it auto-run on every prompt**: a
+`UserPromptSubmit` hook routes each prompt through the engine and the live
+session relays the synthesized answer. `off` is the disable path.
 
 | Mode | Behavior |
 |---|---|
@@ -83,6 +143,8 @@ the synthesized answer. `off` is the disable path.
 | `single <model>` | Auto-runs every prompt through one local CLI and relays its answer. No panel, no judge, no synth. |
 | `fusion <preset>` | Auto-runs every prompt through your panel -> a judge model's analysis -> a grounded synthesis, with graceful degradation and one-level recursion bounds. |
 
+Claude Code examples:
+
 ```text
 /maestro:frontier status                       # show current mode
 /maestro:frontier single opus                  # arm one-CLI auto-run
@@ -91,12 +153,16 @@ the synthesized answer. `off` is the disable path.
 /maestro:frontier off                          # disable auto-run; back to normal Maestro
 ```
 
+In Codex, ask the bundled `maestro-frontier` skill for the same status,
+single, fusion, run, or off operation; it resolves the plugin-bundled engine
+when the bare `maestro` command is not on `PATH`.
+
 Presets define the panel; the judge and synthesizer default to Opus 4.8
 (`claude -p`), and you override either with `--judge` / `--synth`:
 
 - **`opus-duo`**: two independent Opus runs, isolating the synthesis lift.
 - **`opus-gpt`**: Opus + GPT-5.5 (via `codex exec`); the recommended default for bounded spend.
-- **`gpt-duo`**: two GPT-5.5 runs whose judge and synthesizer also run on GPT-5.5: a Codex-only fusion that needs no `claude`.
+- **`chatgpt-duo`** (`gpt-duo` alias): two ChatGPT/Codex runs whose judge and synthesizer also run on ChatGPT/Codex: a Codex-only fusion that needs no `claude`.
 - **`frontier-trio`**: Opus + GPT-5.5 + Gemini 3.1 Pro (via `gemini -p`).
 - **`custom`**: 1-8 of the known models.
 
@@ -114,7 +180,7 @@ failure synthesizes from the raw responses; a hard failure returns a typed
 Honest scope, measured rather than implied: the **engine is built,
 unit-tested (degradation, recursion, budget, anti-majority all covered),
 and verified end-to-end on real runs of `single` mode and the
-`opus-gpt`, `opus-duo`, and `frontier-trio` presets**. The `gpt-duo`
+`opus-gpt`, `opus-duo`, and `frontier-trio` presets**. The `chatgpt-duo`
 preset and `--judge`/`--synth` selection share that same code path and
 are unit-tested, but not yet live-run. The quality *lift* of local fusion
 is **measured, not asserted**: on a 100-task suite (93 scored) every
@@ -178,7 +244,18 @@ Maestro separates **portable orchestration doctrine** from **runtime-specific ad
 | `.cursorrules` | Cursor adapter | Kernel copy (Cursor does not support imports); full S2-S6 in docs/orchestration.md |
 | [`docs/codex.md`](docs/codex.md) | Codex guide | AGENTS.md precedence and 32 KiB cap, Codex subagent mapping, Automations long-horizon mapping (Codex reads `AGENTS.md` natively) |
 
-Maestro's tools run on **both Claude Code and Codex** — in Claude Code as `/maestro:*` slash commands, and in Codex as installable skills, with the portable `node settings/cli.cjs` and `maestro frontier ...` CLIs working on any other agent too. The Codex skills (`frontier`, `terse`, `settings`, `update`) are installed to `.agents/skills/<name>/SKILL.md` by `maestro install --target codex`. When Frontier mode is on, the `frontier` skill leads each Codex reply with `Maestro Frontier ON (<label>)` (`single · <model>` or `fusion · <preset>`) — the Codex analog of Claude Code's armed Frontier indicator; run `maestro frontier status --scope codex` to check. This indicator is Codex-scoped only.
+Maestro's tools run on **both Claude Code and Codex** — in Claude Code as
+`/maestro:*` slash commands, and in Codex as plugin-bundled skills plus
+trusted hooks. The portable `node settings/cli.cjs` and `maestro frontier ...`
+CLIs also work on any other agent. The Codex skills
+(`maestro-frontier`, `maestro-terse`, `maestro-settings`, `maestro-update`)
+ship from the Maestro plugin; the older `maestro install --target codex` path
+still works for manual project copies. When Frontier mode is on, the
+`maestro-frontier` skill leads each Codex reply with `Maestro Frontier ON
+(<label>)` (`single · <model>` or `fusion · <preset>`) — the Codex analog of
+Claude Code's armed Frontier indicator; ask the skill to show status, or run
+`maestro frontier status --scope codex-project` from a shell when using the
+CLI directly.
 
 GitHub Copilot, Cline, and Windsurf read `AGENTS.md` directly, so the portable core works there with no adapter. Maestro's always-on kernel (`AGENTS.md`) is ~8 KB, under Windsurf's 12,000-character limit and roughly a quarter of Codex's 32 KiB budget; the full multi-agent protocol loads on demand from `docs/orchestration.md`.
 
@@ -202,7 +279,9 @@ Optional Claude Code machinery; full install steps in the linked docs.
 
 ## Commands & Settings
 
-Every Maestro slash command in Claude Code is namespaced `/maestro:<name>`. The same tools run on Codex as installed skills (`.agents/skills/<name>/SKILL.md`, via `maestro install --target codex`); on any CLI the same actions also run through the portable scripts noted below.
+Every Maestro slash command in Claude Code is namespaced `/maestro:<name>`.
+The same tools run on Codex as plugin-bundled skills; on any CLI the same
+actions also run through the portable scripts noted below.
 
 | Command | What it does | Usage |
 |---|---|---|
@@ -219,14 +298,15 @@ Every Maestro slash command in Claude Code is namespaced `/maestro:<name>`. The
 | Toggle | Values | What it controls |
 |---|---|---|
 | `terse` | `off`, `lite`, `full`, `ultra` | Output-token reduction. Shows an amber level badge (`ULTRA`) on the status bar. |
-| `frontier` | `off`; `single:` `opus` / `gpt-5.5` / `gemini`; `fusion:` `opus-duo` / `opus-gpt` / `gpt-duo` / `frontier-trio` / `custom`, each with optional `--judge` / `--synth` | The local fusion engine. When armed it auto-runs on every prompt. The blue `f` panel badge means auto-run is on: `fO+C`, `fO+C+G`, `f*3` (`O`=Opus, `C`=ChatGPT/GPT-5.5, `G`=Gemini). |
+| `frontier` | `off`; `single:` `opus` / `gpt-5.5` / `gemini`; `fusion:` `opus-duo` / `opus-gpt` / `chatgpt-duo` / `frontier-trio` / `custom`, each with optional `--judge` / `--synth` | The local fusion engine. When armed it auto-runs on every prompt. The blue `f` panel badge means auto-run is on: `fO+C`, `fO+C+G`, `f*3` (`O`=Opus, `C`=ChatGPT/GPT-5.5, `G`=Gemini). |
 | `context-bar` | `on`, `off` | The status-line context-window progress bar. |
 
-Portable everywhere, Codex included: `node settings/cli.cjs status | list | help | set <key> <value>` (frontier also takes `--judge`, `--synth`, `--models a,b,c`). Full references: [`docs/settings.md`](docs/settings.md) and [`docs/context-bar.md`](docs/context-bar.md).
+Portable everywhere, Codex included: `node settings/cli.cjs status | list | help | set <key> <value>` (frontier also takes `--judge`, `--synth`, `--models a,b,c`, and `--scope <scope>`). Full references: [`docs/settings.md`](docs/settings.md) and [`docs/context-bar.md`](docs/context-bar.md).
 
 ## Updating Maestro
 
-Maestro no longer pins a plugin version. The marketplace always resolves to the latest `main`, so updating is a single refresh — no version bump needed in any file.
+Maestro's marketplaces track `main`, so updating is a refresh rather than a
+manual version edit.
 
 ### Claude Code
 
@@ -245,7 +325,17 @@ It can't run the reload for you (a slash command can't invoke another slash comm
 
 `/reload-plugins` applies the update in the running session; if Claude Code warns that a restart is required, restart it. Non-interactive equivalent of the pull: `claude plugin marketplace update maestro`.
 
-### Codex / Cursor (portable installs, no plugin system)
+### Codex
+
+```text
+codex plugin marketplace upgrade maestro
+codex plugin add maestro@maestro
+```
+
+Open a new thread after reinstalling so Codex reloads bundled skills and hook
+definitions.
+
+### Cursor / Portable Installs
 
 - **Git clone:** `git pull` inside the Maestro clone directory.
 - **Downloaded copy:** re-run `npx github:mbanderas/maestro install --target auto --project .` from the project root, or re-download the tarball and re-copy `frontier/`, `bin/maestro.cjs`, plus your integration command file from the latest `main`.

package/docs/codex.md

@@ -4,6 +4,8 @@ Codex reads `AGENTS.md` natively, no adapter file needed. This page
 maps Maestro's concepts onto Codex specifics. All behavior below was
 verified against the official Codex docs
 ([AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md),
+[config reference](https://developers.openai.com/codex/config-reference#configtoml),
+[plugin-bundled hooks](https://developers.openai.com/codex/hooks#plugin-bundled-hooks),
 [Automations](https://developers.openai.com/codex/app/automations.md),
 [Subagents](https://developers.openai.com/codex/subagents.md))
 on 2026-06-12.
@@ -38,6 +40,40 @@ Practical consequences for Maestro:
   the doctrine to every project; per-repo files then layer on top and
   win where they conflict.
 
+## Config, hooks, and trust
+
+Codex user config lives at `~/.codex/config.toml`. Project overrides can
+live in `.codex/config.toml`, but Codex loads project-local config,
+hooks, and rules only for trusted projects. Untrusted projects skip
+those local surfaces.
+
+Codex also supports plugin-bundled lifecycle hooks. Enabled plugins can
+ship hooks alongside user, project, and managed hooks; the default plugin
+hook file is `hooks/hooks.json`, and manifests can reference `./` paths
+or inline hook definitions. Treat plugin hooks as executable code:
+review and trust the plugin before enabling them. Codex sets
+`PLUGIN_ROOT` and `PLUGIN_DATA` for plugin hooks, and also sets
+`CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` for compatibility.
+
+For Codex CLI/Desktop, install Maestro as a native Codex plugin:
+
+```text
+codex plugin marketplace add mbanderas/maestro
+codex plugin add maestro@maestro
+```
+
+The repo is a Codex marketplace because it ships
+`.agents/plugins/marketplace.json`; the plugin itself is described by
+`.codex-plugin/plugin.json`. That manifest points at the plugin-bundled Codex
+skills (`./skills/`); the hook bundle lives at Codex's default plugin hook path
+`./hooks/hooks.json`, so Codex can install the plugin without `npx`. Restart
+Codex or start a new thread after changing plugin installation/trust state,
+then review and trust the bundled hooks before expecting autorun.
+
+`maestro install --target codex` remains as a portable/manual fallback when
+you specifically want to copy files into a project instead of installing the
+Codex plugin.
+
 ## Multi-agent routing (S2-S6 mapping)
 
 Codex supports subagent workflows in the CLI and app, but current Codex
@@ -75,24 +111,57 @@ memory), and an explicit final report instead of a zombie loop. For
 project-scoped automations note the Codex requirement that the local
 app is running and the project is on disk.
 
-## What does not transfer
+## Frontier autorun and scope
 
-Codex has no user-hook system equivalent to Claude Code's, so Maestro's
-structural enforcement pack (subagent guard, loop guard, phase-scope
-guard, gate telemetry) does not run on Codex. The prose doctrine in
-`AGENTS.md` is the enforcement surface; S7.3's verification gate relies
-on the model honoring it rather than on a hook.
+Frontier is off until you arm it. For Codex, the normal workflow is:
 
-The Maestro context bar also does not apply: Codex CLI ships a native
+```text
+maestro frontier mode fusion --preset chatgpt-duo --scope codex-project
+maestro frontier mode fusion --preset frontier-trio --judge chatgpt --synth chatgpt --scope codex-project
+maestro frontier mode off --scope codex-project
+```
+
+Once the Maestro Codex plugin hook is installed, enabled, and trusted,
+normal Codex prompts route through Frontier until you turn it off.
+`maestro frontier run "<prompt>" ...` remains available for advanced/debug
+one-offs, but it is not the everyday Codex flow.
+
+Project/workspace scope is the recommended default for repo installs:
+it keeps one repository's armed state from leaking into another. In a
+Codex plugin context Maestro resolves this automatically to a
+`codex-<8hex>` workspace scope. From a shell in the repo, pass
+`--scope codex-project` (or `codex-workspace`) to resolve the same project
+scope. Global/user scope is optional: choose an explicit name such as
+`--scope codex-global` only when you deliberately want the same state across
+projects.
+
+Use the same active scope for all lifecycle commands:
+
+```text
+maestro frontier status --scope codex-project
+maestro frontier mode off --scope codex-project
+maestro frontier mode fusion --preset chatgpt-duo --scope codex-project
+maestro frontier mode fusion --preset frontier-trio --judge chatgpt --synth chatgpt --scope codex-project
+```
+
+## What differs from Claude Code
+
+Claude Code-specific UI such as the Maestro context bar does not apply:
+Codex CLI ships a native
 context-usage indicator (`/statusline` picker, or `context` in
 `[tui].status_line` in `~/.codex/config.toml`).
 
 ## Skills and the Frontier ON indicator
 
-`maestro install --target codex` installs the `frontier`, `terse`, `settings`,
-and `update` Maestro commands as Codex skills (no-clobber) to
-`.agents/skills/<name>/SKILL.md` (per-repo) or `~/.agents/skills/<name>/SKILL.md`
-(global). When `maestro frontier status --scope codex` reports mode != off, the
-`frontier` skill instructs Codex to lead its reply with
+Codex skills can live in personal `$HOME/.agents/skills`, repo
+`.agents/skills`, or installed plugins. The normal Codex path is the Maestro
+plugin, which bundles `maestro-frontier`, `maestro-settings`, `maestro-terse`,
+and `maestro-update` from `./skills/`. The portable
+`maestro install --target codex` fallback still installs those same skills to
+`.agents/skills/<name>/SKILL.md` for project installs or
+`~/.agents/skills/<name>/SKILL.md` for global/user installs.
+
+When `maestro frontier status --scope codex-project` reports mode != off,
+the `maestro-frontier` skill instructs Codex to lead its reply with
 `Maestro Frontier ON (<label>)` — `single · <model>` or `fusion · <preset>`. When
 mode is off, no indicator line appears.

package/frontier/cli.cjs

@@ -5,7 +5,7 @@
 
 const fs = require('fs');
 const { DEFAULTS, loadState, saveState, resolveScope, validateMode, validatePreset, validateModel, adoptLegacyState } = require('./config.cjs');
-const { runFrontier } = require('./run.cjs');
+const { runFrontier, canonicalModelId, canonicalPresetId } = require('./run.cjs');
 
 // ---------- arg helpers ----------
 
@@ -63,7 +63,8 @@ function cmdMode(argv, scope) {
   if (newMode === 'off') {
     state = { mode: 'off' };
   } else if (newMode === 'single') {
-    const model = getFlag(argv, '--model');
+    const rawModel = getFlag(argv, '--model');
+    const model = rawModel && canonicalModelId(rawModel);
     if (!model) {
       process.stderr.write('ERROR: --model required for single mode\n');
       process.exit(2);
@@ -75,7 +76,8 @@ function cmdMode(argv, scope) {
     state = { mode: 'single', model };
   } else {
     // fusion
-    const preset = getFlag(argv, '--preset');
+    const rawPreset = getFlag(argv, '--preset');
+    const preset = rawPreset && canonicalPresetId(rawPreset);
     if (!preset) {
       process.stderr.write('ERROR: --preset required for fusion mode\n');
       process.exit(2);
@@ -90,7 +92,7 @@ function cmdMode(argv, scope) {
         process.stderr.write('ERROR: --models required for custom preset\n');
         process.exit(2);
       }
-      const models = modelsRaw.split(',').map(m => m.trim()).filter(Boolean);
+      const models = modelsRaw.split(',').map(m => canonicalModelId(m.trim())).filter(Boolean);
       state = { mode: 'fusion', preset: 'custom', models };
     } else {
       state = { mode: 'fusion', preset };
@@ -99,7 +101,8 @@ function cmdMode(argv, scope) {
     // Optional judge/synth model overrides — apply to any fusion preset so
     // users can mix freely (e.g. --judge opus --synth gpt-5.5). Unset =
     // the preset's own stage model (presetStages) or the global default.
-    const judge = getFlag(argv, '--judge');
+    const rawJudge = getFlag(argv, '--judge');
+    const judge = rawJudge !== null ? canonicalModelId(rawJudge) : null;
     if (judge !== null) {
       if (!validateModel(judge)) {
         process.stderr.write('ERROR: unknown judge model: ' + judge + '\n');
@@ -107,7 +110,8 @@ function cmdMode(argv, scope) {
       }
       state.judgeModel = judge;
     }
-    const synth = getFlag(argv, '--synth');
+    const rawSynth = getFlag(argv, '--synth');
+    const synth = rawSynth !== null ? canonicalModelId(rawSynth) : null;
     if (synth !== null) {
       if (!validateModel(synth)) {
         process.stderr.write('ERROR: unknown synth model: ' + synth + '\n');

package/frontier/config.cjs

@@ -71,26 +71,50 @@ function sanitizeScope(v) {
   return s.length > 0 ? s : 'default';
 }
 
+function workspaceCwd(opts) {
+  return (opts && opts.cwd) || process.env.CLAUDE_PROJECT_DIR || process.env.CODEX_PROJECT_DIR || process.cwd();
+}
+
+function resolveScopeAlias(scope, opts) {
+  const clean = sanitizeScope(scope);
+  if (['codex-project', 'codex-workspace', 'codex-repo'].includes(clean)) {
+    return 'codex-' + workspaceHash(workspaceCwd(opts));
+  }
+  if (['claude-project', 'claude-workspace', 'cc-project', 'cc-workspace'].includes(clean)) {
+    return 'cc-' + workspaceHash(workspaceCwd(opts));
+  }
+  return clean;
+}
+
 /**
  * Resolve the active scope from argv + environment. Precedence:
  *   1. --scope <value> flag in argv
  *   2. process.env.MAESTRO_SCOPE
- *   3. Autodetect: CLAUDE_PLUGIN_ROOT || CLAUDECODE truthy -> 'cc-<8hex>'
+ *   3. Autodetect: PLUGIN_ROOT truthy -> 'codex-<8hex>'
+ *   4. Autodetect: CLAUDE_PLUGIN_ROOT || CLAUDECODE truthy -> 'cc-<8hex>'
+ *   5. Autodetect: PLUGIN_DATA truthy -> 'codex-<8hex>'
  *      where <8hex> is derived from the workspace root (opts.cwd,
- *      CLAUDE_PROJECT_DIR, or process.cwd()) via workspaceHash().
- *   4. 'default'
- * The chosen value for steps 1-2 is always passed through sanitizeScope.
+ *      CLAUDE_PROJECT_DIR, CODEX_PROJECT_DIR, or process.cwd()) via
+ *      workspaceHash().
+ *   6. 'default'
+ * The chosen value for steps 1-2 is sanitized, and project aliases such as
+ * codex-project/codex-workspace are expanded to per-workspace scopes.
  * @param {string[]} argv
  * @param {{ cwd?: string }} [opts]
  * @returns {string}
  */
 function resolveScope(argv, opts) {
   const flagVal = getFlag(argv, '--scope');
-  if (flagVal !== null) return sanitizeScope(flagVal);
-  if (process.env.MAESTRO_SCOPE) return sanitizeScope(process.env.MAESTRO_SCOPE);
+  if (flagVal !== null) return resolveScopeAlias(flagVal, opts);
+  if (process.env.MAESTRO_SCOPE) return resolveScopeAlias(process.env.MAESTRO_SCOPE, opts);
+  if (process.env.PLUGIN_ROOT) {
+    return 'codex-' + workspaceHash(workspaceCwd(opts));
+  }
   if (process.env.CLAUDE_PLUGIN_ROOT || process.env.CLAUDECODE) {
-    const cwd = (opts && opts.cwd) || process.env.CLAUDE_PROJECT_DIR || process.cwd();
-    return 'cc-' + workspaceHash(cwd);
+    return 'cc-' + workspaceHash(workspaceCwd(opts));
+  }
+  if (process.env.PLUGIN_DATA) {
+    return 'codex-' + workspaceHash(workspaceCwd(opts));
   }
   return 'default';
 }
@@ -111,6 +135,7 @@ function legacyStatePath() {
  */
 function statePath(scope) {
   if (scope === undefined) scope = resolveScope([]);
+  else scope = resolveScopeAlias(scope);
   if (scope === 'default') return path.join(configDir(), 'frontier-state.json');
   return path.join(configDir(), 'frontier-state.' + scope + '.json');
 }
@@ -163,25 +188,26 @@ function _readValidatedStateFile(p) {
 
 /**
  * Load frontier state for the given scope.
- * D3 MIGRATION: if scope !== 'default' and scope does NOT match /^cc-/
+ * D3 MIGRATION: if scope !== 'default' and scope does NOT match /^(cc|codex)-/
  * and the scoped file does NOT exist AND the legacy frontier-state.json
  * DOES exist, seed from the legacy file (read-only — never write during
- * load). Same symlink/parse guards apply. cc-* scopes are excluded from
- * migration because they are per-workspace and must not inherit global
- * legacy state. Named scopes (e.g. 'codex', 'cursor') still migrate.
+ * load). Same symlink/parse guards apply. cc-* and codex-* scopes are
+ * excluded from migration because they are per-workspace and must not inherit
+ * global legacy state. Named scopes (e.g. 'codex', 'cursor') still migrate.
  * Falls back to {mode:'off'} on any failure.
  * @param {string} [scope] Omit to autodetect the runtime scope via resolveScope([]).
  * @returns {object}
  */
 function loadState(scope) {
   if (scope === undefined) scope = resolveScope([]);
+  else scope = resolveScopeAlias(scope);
   try {
     const p = statePath(scope);
     const result = _readStateFile(p);
     if (result !== null) return result;
 
-    // File absent. For non-default, non-cc-* scopes attempt migration from legacy file.
-    if (scope !== 'default' && !/^cc-/.test(scope)) {
+    // File absent. For non-default, non-workspace scopes attempt migration from legacy file.
+    if (scope !== 'default' && !/^(cc|codex)-/.test(scope)) {
       const legacyResult = _readStateFile(legacyStatePath());
       if (legacyResult !== null) return legacyResult;
     }
@@ -201,6 +227,7 @@ function loadState(scope) {
  */
 function saveState(state, scope) {
   if (scope === undefined) scope = resolveScope([]);
+  else scope = resolveScopeAlias(scope);
   try {
     const p = statePath(scope);
     const dir = path.dirname(p);

package/frontier/run.cjs

@@ -17,6 +17,37 @@ const dispatch = require('./dispatch.cjs');
 const judge = require('./judge.cjs');
 const synthesize = require('./synthesize.cjs');
 
+const MODEL_ALIASES = {
+  chatgpt: 'gpt-5.5',
+};
+
+const PRESET_ALIASES = {
+  'chatgpt-duo': 'gpt-duo',
+};
+
+/** @param {string} model @returns {string} */
+function canonicalModelId(model) {
+  return MODEL_ALIASES[model] || model;
+}
+
+/** @param {string} preset @returns {string} */
+function canonicalPresetId(preset) {
+  return PRESET_ALIASES[preset] || preset;
+}
+
+/** @param {object} state @returns {object} */
+function normalizeStateAliases(state) {
+  const normalized = { ...state };
+  if (normalized.model) normalized.model = canonicalModelId(normalized.model);
+  if (normalized.preset) normalized.preset = canonicalPresetId(normalized.preset);
+  if (Array.isArray(normalized.models)) {
+    normalized.models = normalized.models.map(canonicalModelId);
+  }
+  if (normalized.judgeModel) normalized.judgeModel = canonicalModelId(normalized.judgeModel);
+  if (normalized.synthModel) normalized.synthModel = canonicalModelId(normalized.synthModel);
+  return normalized;
+}
+
 /**
  * @param {{ prompt:string, state:object, cfg?:object, deps?:object }} opts
  * @returns {Promise<object>}
@@ -24,6 +55,7 @@ const synthesize = require('./synthesize.cjs');
 async function runFrontier({ prompt, state, cfg, deps }) {
   cfg = cfg || DEFAULTS;
   deps = deps || {};
+  state = normalizeStateAliases(state || {});
 
   const spawnOne  = deps.spawnOne  || dispatch.spawnOne;
   const fanOut    = deps.fanOut    || dispatch.fanOut;
@@ -145,4 +177,4 @@ async function runFrontier({ prompt, state, cfg, deps }) {
   return { status: 'error', mode: state.mode, error: 'unknown mode', failure_reason: 'unexpected_error' };
 }
 
-module.exports = { runFrontier };
+module.exports = { runFrontier, canonicalModelId, canonicalPresetId, normalizeStateAliases };

package/hooks/frontier-autorun.cjs

@@ -45,12 +45,8 @@ if (Number.isFinite(fusionDepth) && fusionDepth >= 1) noop();
 let state;
 try {
   const cfg = require('../frontier/config.cjs');
-  const cwd = data.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
-  // This hook only ever runs under Claude Code, so force a per-workspace
-  // scope; resolveScope honors --scope/MAESTRO_SCOPE first, then we ensure
-  // we never fall back to the shared legacy 'default' file.
-  let scope = cfg.resolveScope([], { cwd });
-  if (scope === 'default') scope = 'cc-' + cfg.workspaceHash(cwd);
+  const cwd = data.cwd || process.env.CLAUDE_PROJECT_DIR || process.env.CODEX_PROJECT_DIR || process.cwd();
+  const scope = cfg.resolveScope([], { cwd });
   state = cfg.loadState(scope);
 } catch {
   noop();

package/hooks/hooks.json

@@ -40,7 +40,7 @@
           },
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/frontier-autorun.cjs\"",
+            "command": "node -e \"require(require('path').join(process.env.CLAUDE_PLUGIN_ROOT || process.env.PLUGIN_ROOT, 'hooks', 'frontier-autorun.cjs'))\"",
             "timeout": 300
           }
         ]