codex-model-router 2.0.0 → 2.2.0

package/README.md

@@ -10,7 +10,7 @@ The normal installation uses free mode:
 
 - The user-selected primary model handles conversation, clarification, follow-ups, final replies, and trivial work.
 - Terra/high investigates, produces implementation-ready plans, verifies results, debugs, and replans.
-- Luna/max performs most clear, bounded, repetitive, or independently verifiable implementation work.
+- Luna/xhigh performs most clear, bounded, repetitive, or independently verifiable implementation work.
 - Sol/medium is read-only and used only when Terra still cannot resolve core logic after focused investigation and one materially revised plan, or when the user explicitly requests Sol.
 - Existing built-in and custom agents remain available and take precedence when they are a better match.
 
@@ -49,6 +49,47 @@ codex-model-router install --set-default
 
 Running a later plain `install` returns package-managed default settings to free mode. User-modified model settings are preserved.
 
+## Agent reasoning
+
+The managed agent defaults are Terra/high, Luna/xhigh, and Sol/medium. Override all agents or individual agents during installation:
+
+```sh
+codex-model-router install --agent-reasoning high
+codex-model-router install --terra-reasoning xhigh --luna-reasoning low --sol-reasoning max
+```
+
+Supported values are `none`, `low`, `medium`, `high`, `xhigh`, and `max`. Per-agent options override `--agent-reasoning`. Later installs preserve unchanged package-managed reasoning choices; manually edited agent files remain protected.
+
+## Optional experimental multi-agent V2
+
+Codex currently has an experimental `multi_agent_v2` configuration that is not part of the public configuration reference. It may be unavailable for some accounts or Codex builds, and its keys or behavior may change without notice.
+
+A normal install never enables it. Enable it explicitly for the current project only after accepting that compatibility risk:
+
+```sh
+codex-model-router v2 enable --dry-run
+codex-model-router v2 enable
+codex-model-router v2 status
+```
+
+The managed block is:
+
+```toml
+[features.multi_agent_v2]
+hide_spawn_agent_metadata = false
+tool_namespace = "agents"
+```
+
+Disable only the unchanged block created by this package:
+
+```sh
+codex-model-router v2 disable
+```
+
+Use `--global` with `enable`, `disable`, or `status` to target the user-level Codex configuration. Pre-existing V2 settings are treated as user-managed and are never overwritten. A normal package uninstall also removes an unchanged package-managed V2 block; modified V2 content is preserved and reported.
+
+Enabling this setting does not guarantee that every child agent resolves to the requested model. Verify actual subagent model usage from Codex session metadata when cost control depends on Luna being selected.
+
 ## Install
 
 Run from npm:
@@ -69,7 +110,7 @@ Installing the CLI globally only makes the command available system-wide. Use `i
 Install a specific GitHub release:
 
 ```sh
-npm install -g https://github.com/Honguan/codex-model-router/archive/refs/tags/v2.0.0.tar.gz
+npm install -g https://github.com/Honguan/codex-model-router/archive/refs/tags/v2.2.0.tar.gz
 codex-model-router install
 ```
 
@@ -78,11 +119,12 @@ codex-model-router install
 Project scope is the default and manages only:
 
 ```text
-.codex/config.toml                              # only with --set-default or a managed migration
+.codex/config.toml                              # only with --set-default, V2 opt-in, or a managed migration
 .codex/agents/terra.toml
 .codex/agents/luna.toml
 .codex/agents/sol.toml
 .codex/model-router-state.json
+.codex/model-router-v2-state.json               # only after explicit `v2 enable`
 .codex/config.toml.codex-model-router.bak       # only when needed
 .agents/skills/model-router/SKILL.md
 .agents/skills/implementation-planning/SKILL.md
@@ -93,6 +135,7 @@ Use global scope with:
 ```sh
 codex-model-router install --global
 codex-model-router doctor --global
+codex-model-router v2 enable --global
 ```
 
 Global scope stores agents under `$CODEX_HOME/agents` and skills under `~/.agents/skills`. When `CODEX_HOME` is unset, it defaults to `~/.codex`.
@@ -119,8 +162,13 @@ Terra verifies separately whether implementation matches the plan and whether th
 
 ```text
 codex-model-router install [--global] [--set-default] [--dry-run]
+  [--agent-reasoning <effort>]
+  [--terra-reasoning <effort>] [--luna-reasoning <effort>] [--sol-reasoning <effort>]
 codex-model-router uninstall [--global] [--dry-run]
 codex-model-router doctor [--global]
+codex-model-router v2 enable [--global] [--dry-run]
+codex-model-router v2 disable [--global] [--dry-run]
+codex-model-router v2 status [--global]
 codex-model-router --version
 ```
 
@@ -131,7 +179,8 @@ codex-model-router --version
 - Preserves unrelated TOML settings, comments, BOM, ordering, and LF/CRLF line endings.
 - Rejects malformed, non-UTF-8, duplicate, or unsafe configuration before writing.
 - Rejects symlinks and Windows junctions in managed paths.
-- Uses scope-level locking, atomic transactions, rollback, and conflict-safe recovery.
+- Uses scope-level locking, atomic transactions, rollback, and conflict-safe recovery for normal routing installation.
+- The optional V2 manager uses the same scope lock, atomic file replacement, an exact marked block, and a separate state file.
 - Never overwrites post-interruption user changes.
 - Dry-run creates no files, directories, backups, locks, journals, or state.
 - Never modifies AGENTS.md, shell profiles, editor settings, hooks, MCP servers, telemetry, accounts, or environment variables.
@@ -140,6 +189,8 @@ codex-model-router --version
 
 Compatibility is tested on Node.js 18, 20, 22, and 24 across Windows, Linux, and macOS runners. The selected Codex account must have access to gpt-5.6-terra, gpt-5.6-luna, and gpt-5.6-sol.
 
-Restart Codex after installation so new agents and skills are discovered. Use `doctor` for missing, user-modified, unsafe-state, lock, or interrupted-transaction reports.
+The optional V2 setting is intentionally excluded from compatibility guarantees because it is not publicly documented by OpenAI. Failure or removal of that experimental setting does not affect the normal V1/custom-agent installation.
+
+Restart Codex after installation or V2 changes so new agents, skills, and configuration are discovered. Use `doctor` for missing, user-modified, unsafe-state, lock, interrupted-transaction, or managed V2 reports.
 
 Security vulnerabilities should be reported privately according to [SECURITY.md](SECURITY.md). Maintainer setup and release steps are documented in [MAINTAINERS.md](MAINTAINERS.md).

package/bin/codex-model-router.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { run } from "../lib/router.js";
+import { runCli } from "../lib/agent-reasoning-cli.js";
 
-process.exitCode = await run(process.argv.slice(2), { output: console.log });
+process.exitCode = await runCli(process.argv.slice(2), { output: console.log });

package/lib/agent-reasoning-cli.js

@@ -0,0 +1,181 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  AGENT_NAMES,
+  configureAgentReasoning,
+  DEFAULT_AGENT_REASONING,
+  REASONING_EFFORTS,
+  VERSION
+} from "./manifest.js";
+import {
+  cleanupV2AfterUninstall,
+  reportV2Doctor,
+  runV2Command
+} from "./experimental-v2.js";
+import { run as runCore } from "./router.js";
+
+const OPTION_TO_AGENT = Object.freeze({
+  "--terra-reasoning": "terra",
+  "--luna-reasoning": "luna",
+  "--sol-reasoning": "sol"
+});
+
+function usage() {
+  return `codex-model-router ${VERSION}
+
+Usage:
+  codex-model-router install [--global] [--set-default] [--dry-run]
+    [--agent-reasoning <effort>]
+    [--terra-reasoning <effort>]
+    [--luna-reasoning <effort>]
+    [--sol-reasoning <effort>]
+  codex-model-router uninstall [--global] [--dry-run]
+  codex-model-router doctor [--global]
+  codex-model-router v2 enable [--global] [--dry-run]
+  codex-model-router v2 disable [--global] [--dry-run]
+  codex-model-router v2 status [--global]
+  codex-model-router --version
+
+Reasoning efforts: ${REASONING_EFFORTS.join(", ")}
+Defaults: Terra=${DEFAULT_AGENT_REASONING.terra}, Luna=${DEFAULT_AGENT_REASONING.luna}, Sol=${DEFAULT_AGENT_REASONING.sol}
+
+V2 commands manage an experimental, undocumented Codex setting and are never enabled by a normal install.`;
+}
+
+function optionValue(argv, index, option) {
+  const token = argv[index];
+  if (token.startsWith(`${option}=`)) return { value: token.slice(option.length + 1), consumed: 1 };
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) return { error: `missing value for ${option}` };
+  return { value, consumed: 2 };
+}
+
+function parseReasoningOptions(argv) {
+  const command = argv[0];
+  const cleaned = command ? [command] : [];
+  const overrides = {};
+  let all;
+
+  for (let index = 1; index < argv.length;) {
+    const token = argv[index];
+    const option = token.split("=", 1)[0];
+    const agent = OPTION_TO_AGENT[option];
+    if (option !== "--agent-reasoning" && !agent) {
+      cleaned.push(token);
+      index += 1;
+      continue;
+    }
+    if (command !== "install") return { error: `${option} is supported only for install` };
+    const parsed = optionValue(argv, index, option);
+    if (parsed.error) return parsed;
+    const reasoning = parsed.value.toLowerCase();
+    if (!REASONING_EFFORTS.includes(reasoning)) {
+      return { error: `unsupported reasoning effort: ${parsed.value}` };
+    }
+    if (agent) overrides[agent] = reasoning;
+    else all = reasoning;
+    index += parsed.consumed;
+  }
+  return { cleaned, overrides, all };
+}
+
+function digest(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+async function readRegularText(path) {
+  try {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink()) return null;
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function activeReasoning(content) {
+  const match = content.match(/^\s*model_reasoning_effort\s*=\s*"([^"\r\n]+)"\s*(?:#.*)?$/m);
+  return match && REASONING_EFFORTS.includes(match[1]) ? match[1] : null;
+}
+
+function versionAtLeast(version, minimum) {
+  const parse = (value) => String(value || "0").split(".").slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+  const left = parse(version);
+  const right = parse(minimum);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return true;
+}
+
+async function installedReasoning(argv, options) {
+  const global = argv.includes("--global");
+  const home = resolve(options.home ?? homedir());
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const env = options.env ?? process.env;
+  const codexHome = global
+    ? resolve(env.CODEX_HOME || join(home, ".codex"))
+    : join(cwd, ".codex");
+  const stateText = await readRegularText(join(codexHome, "model-router-state.json"));
+  if (!stateText) return { reasoning: {}, content: {}, packageVersion: null };
+
+  let state;
+  try {
+    state = JSON.parse(stateText);
+  } catch {
+    return { reasoning: {}, content: {}, packageVersion: null };
+  }
+
+  const physicalCodexHome = await realpath(codexHome);
+  const reasoning = {};
+  const content = {};
+  for (const name of AGENT_NAMES) {
+    const path = join(physicalCodexHome, "agents", `${name}.toml`);
+    const tracked = state.files?.[name];
+    const current = await readRegularText(path);
+    if (!tracked || !current || resolve(tracked.path) !== resolve(path) || digest(current) !== tracked.hash) continue;
+    const effort = activeReasoning(current);
+    if (!effort) continue;
+    reasoning[name] = effort;
+    content[name] = current;
+  }
+  return { reasoning, content, packageVersion: state.packageVersion };
+}
+
+export async function runCli(argv, options = {}) {
+  const output = options.output ?? console.log;
+  if (argv[0] === "v2") return runV2Command(argv.slice(1), options);
+  if (!argv.length || argv.includes("--help") || argv.includes("-h")) {
+    output(usage());
+    return 0;
+  }
+
+  const parsed = parseReasoningOptions(argv);
+  if (parsed.error) {
+    output(`${parsed.error}\n\n${usage()}`);
+    return 1;
+  }
+
+  const installed = await installedReasoning(parsed.cleaned, options);
+  const selected = { ...DEFAULT_AGENT_REASONING };
+  if (versionAtLeast(installed.packageVersion, "2.1.0")) Object.assign(selected, installed.reasoning);
+  if (parsed.all) {
+    for (const name of AGENT_NAMES) selected[name] = parsed.all;
+  }
+  Object.assign(selected, parsed.overrides);
+  configureAgentReasoning(selected, installed.content);
+
+  const result = await runCore(parsed.cleaned, options);
+  const command = parsed.cleaned[0];
+  if (command === "doctor") {
+    const v2Result = await reportV2Doctor(parsed.cleaned.slice(1), options);
+    return result || v2Result;
+  }
+  if (command === "uninstall" && result === 0) {
+    return cleanupV2AfterUninstall(parsed.cleaned.slice(1), options);
+  }
+  return result;
+}

package/lib/experimental-v2.js

@@ -0,0 +1,566 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, realpath, rename, rm, stat } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const STATE_FILE = "model-router-v2-state.json";
+const LOCK_FILE = "model-router.lock";
+const START_MARKER = "# >>> codex-model-router experimental multi-agent-v2 >>>";
+const END_MARKER = "# <<< codex-model-router experimental multi-agent-v2 <<<";
+const STATE_VERSION = 1;
+
+export const EXPERIMENTAL_V2_SETTINGS = Object.freeze({
+  hide_spawn_agent_metadata: false,
+  tool_namespace: "agents"
+});
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function normalizePath(path) {
+  const value = resolve(path);
+  return process.platform === "win32" ? value.toLowerCase() : value;
+}
+
+function isWithin(path, root) {
+  const value = relative(resolve(root), resolve(path));
+  return value === "" || (!value.startsWith(`..${sep}`) && value !== ".." && !isAbsolute(value));
+}
+
+async function nearestExistingAncestor(path) {
+  let current = resolve(path);
+  while (true) {
+    try {
+      await lstat(current);
+      return current;
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      const parent = dirname(current);
+      if (parent === current) throw new Error(`no existing ancestor for ${path}`);
+      current = parent;
+    }
+  }
+}
+
+async function canonicalize(path) {
+  const absolute = resolve(path);
+  const ancestor = await nearestExistingAncestor(absolute);
+  return resolve(await realpath(ancestor), relative(ancestor, absolute));
+}
+
+async function assertSafePath(target, root, anchor, label) {
+  const absoluteTarget = resolve(target);
+  const absoluteRoot = resolve(root);
+  const absoluteAnchor = resolve(anchor);
+  if (!isWithin(absoluteTarget, absoluteRoot) || !isWithin(absoluteTarget, absoluteAnchor)) {
+    throw new Error(`unsafe path for ${label}: ${absoluteTarget}`);
+  }
+
+  const physicalAnchor = await realpath(absoluteAnchor);
+  let current = absoluteAnchor;
+  const inspect = [current];
+  for (const component of relative(absoluteAnchor, absoluteTarget).split(sep).filter(Boolean)) {
+    current = join(current, component);
+    inspect.push(current);
+  }
+
+  for (let index = 0; index < inspect.length; index += 1) {
+    const candidate = inspect[index];
+    let info;
+    try {
+      info = await lstat(candidate);
+    } catch (error) {
+      if (error?.code === "ENOENT") break;
+      throw error;
+    }
+    if (info.isSymbolicLink()) throw new Error(`unsafe symbolic link or junction: ${candidate}`);
+    if (index < inspect.length - 1 && !info.isDirectory()) {
+      throw new Error(`unsafe non-directory path component: ${candidate}`);
+    }
+    const physical = await realpath(candidate);
+    const expected = resolve(physicalAnchor, relative(absoluteAnchor, candidate));
+    if (normalizePath(physical) !== normalizePath(expected)) {
+      throw new Error(`unsafe redirected path: ${candidate}`);
+    }
+  }
+}
+
+async function locationFor(options, global) {
+  const home = await canonicalize(options.home ?? homedir());
+  const cwd = await canonicalize(options.cwd ?? process.cwd());
+  const env = options.env ?? process.env;
+  const codexHome = global
+    ? resolve(env.CODEX_HOME || join(home, ".codex"))
+    : join(cwd, ".codex");
+  const anchor = global ? await nearestExistingAncestor(codexHome) : cwd;
+  const location = {
+    scope: global ? "global" : "project",
+    codexHome,
+    config: join(codexHome, "config.toml"),
+    state: join(codexHome, STATE_FILE),
+    lock: join(codexHome, LOCK_FILE),
+    anchor
+  };
+  await validateLocation(location);
+  return location;
+}
+
+async function validateLocation(location) {
+  for (const [label, target] of Object.entries({
+    "Codex home": location.codexHome,
+    "config.toml": location.config,
+    "experimental V2 state": location.state,
+    "scope lock": location.lock
+  })) {
+    await assertSafePath(target, location.codexHome, location.anchor, label);
+  }
+}
+
+async function readText(path) {
+  try {
+    const bytes = await readFile(path);
+    const text = bytes.toString("utf8");
+    if (!Buffer.from(text, "utf8").equals(bytes)) throw new Error(`${path} is not valid UTF-8`);
+    if (text.includes("\0")) throw new Error(`${path} contains a NUL byte`);
+    return { exists: true, text };
+  } catch (error) {
+    if (error?.code === "ENOENT") return { exists: false, text: "" };
+    throw error;
+  }
+}
+
+async function atomicWrite(path, content) {
+  await mkdir(dirname(path), { recursive: true });
+  let mode = 0o600;
+  try {
+    mode = (await stat(path)).mode;
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const temporary = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+  let handle;
+  try {
+    handle = await open(temporary, "wx", mode);
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await rename(temporary, path);
+  } catch (error) {
+    try { await handle?.close(); } catch {}
+    try { await rm(temporary, { force: true }); } catch {}
+    throw error;
+  }
+}
+
+function newlineFor(content) {
+  return content.includes("\r\n") ? "\r\n" : "\n";
+}
+
+function managedBlock(newline) {
+  return [
+    START_MARKER,
+    "[features.multi_agent_v2]",
+    "hide_spawn_agent_metadata = false",
+    'tool_namespace = "agents"',
+    END_MARKER,
+    ""
+  ].join(newline);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function findManagedV2Block(content) {
+  const starts = [...content.matchAll(new RegExp(`^${escapeRegExp(START_MARKER)}\\r?$`, "gm"))];
+  const ends = [...content.matchAll(new RegExp(`^${escapeRegExp(END_MARKER)}\\r?$`, "gm"))];
+  if (!starts.length && !ends.length) return null;
+  if (starts.length !== 1 || ends.length !== 1 || ends[0].index <= starts[0].index) {
+    return { error: "duplicate, incomplete, or misordered experimental V2 markers" };
+  }
+  const start = starts[0].index;
+  let end = ends[0].index + ends[0][0].length;
+  if (content[end] === "\n") end += 1;
+  return { start, end, content: content.slice(start, end) };
+}
+
+function stripInlineComment(line) {
+  let quote = null;
+  let escaped = false;
+  for (let index = 0; index < line.length; index += 1) {
+    const character = line[index];
+    if (quote) {
+      if (quote === '"' && character === "\\" && !escaped) {
+        escaped = true;
+        continue;
+      }
+      if (character === quote && !escaped) quote = null;
+      escaped = false;
+      continue;
+    }
+    if (character === '"' || character === "'") quote = character;
+    else if (character === "#") return line.slice(0, index);
+  }
+  return line;
+}
+
+function hasUnmanagedV2(content) {
+  return content.split(/\r?\n/).some((line) => /\bmulti_agent_v2\b/.test(stripInlineComment(line)));
+}
+
+function appendBlock(original) {
+  const newline = newlineFor(original);
+  const block = managedBlock(newline);
+  const hasBom = original.charCodeAt(0) === 0xfeff;
+  const body = original.slice(hasBom ? 1 : 0);
+  let separator = "";
+  if (body.length > 0) {
+    if (body.endsWith(`${newline}${newline}`)) separator = "";
+    else if (body.endsWith(newline)) separator = newline;
+    else separator = `${newline}${newline}`;
+  } else if (hasBom) {
+    separator = newline;
+  }
+  return { content: `${original}${separator}${block}`, block, separator };
+}
+
+function validateState(raw, location) {
+  if (!raw || typeof raw !== "object" || raw.version !== STATE_VERSION) {
+    throw new Error("experimental V2 state is invalid or unsupported");
+  }
+  if (raw.scope !== location.scope) throw new Error("experimental V2 state scope mismatch");
+  if (normalizePath(raw.configPath) !== normalizePath(location.config)) {
+    throw new Error("experimental V2 state path mismatch");
+  }
+  if (typeof raw.createdConfig !== "boolean") throw new Error("experimental V2 createdConfig is invalid");
+  if (typeof raw.separator !== "string" || !["", "\n", "\n\n", "\r\n", "\r\n\r\n"].includes(raw.separator)) {
+    throw new Error("experimental V2 separator is invalid");
+  }
+  if (!/^[a-f0-9]{64}$/.test(raw.blockHash || "")) throw new Error("experimental V2 block hash is invalid");
+  return raw;
+}
+
+async function loadState(location) {
+  const file = await readText(location.state);
+  if (!file.exists) return { exists: false, state: null };
+  let raw;
+  try {
+    raw = JSON.parse(file.text);
+  } catch {
+    throw new Error("experimental V2 state is not valid JSON");
+  }
+  return { exists: true, state: validateState(raw, location) };
+}
+
+async function inspect(location) {
+  const state = await loadState(location);
+  const config = await readText(location.config);
+  const block = findManagedV2Block(config.text);
+  if (block?.error) return { status: "invalid", detail: block.error, state, config, block };
+  if (!state.exists) {
+    if (block) return { status: "untracked", detail: "package markers exist without state", state, config, block };
+    if (hasUnmanagedV2(config.text)) {
+      return { status: "unmanaged", detail: "pre-existing V2 configuration is preserved", state, config, block };
+    }
+    return { status: "disabled", state, config, block };
+  }
+  if (!config.exists) return { status: "missing", detail: "config.toml is missing", state, config, block };
+  if (!block) return { status: "missing", detail: "managed V2 block is missing", state, config, block };
+  if (digest(block.content) !== state.state.blockHash) {
+    return { status: "user-modified", detail: "managed V2 block changed", state, config, block };
+  }
+  return { status: "managed", state, config, block };
+}
+
+async function inspectLock(location) {
+  const file = await readText(location.lock);
+  if (!file.exists) return { status: "none" };
+  let metadata;
+  try {
+    metadata = JSON.parse(file.text);
+  } catch {
+    return { status: "corrupt", detail: "lock file is not valid JSON" };
+  }
+  if (
+    !Number.isInteger(metadata.pid) ||
+    metadata.pid <= 0 ||
+    typeof metadata.hostname !== "string" ||
+    typeof metadata.token !== "string"
+  ) {
+    return { status: "corrupt", detail: "lock metadata is invalid" };
+  }
+  if (metadata.hostname !== hostname()) {
+    return { status: "active", metadata, detail: "lock belongs to another host" };
+  }
+  let alive = true;
+  try {
+    process.kill(metadata.pid, 0);
+  } catch (error) {
+    if (["ESRCH", "EINVAL"].includes(error?.code)) alive = false;
+    else if (error?.code !== "EPERM") throw error;
+  }
+  return alive ? { status: "active", metadata } : { status: "stale", metadata };
+}
+
+async function acquireLock(location, command) {
+  await mkdir(location.codexHome, { recursive: true });
+  await validateLocation(location);
+
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const token = randomUUID();
+    let handle;
+    try {
+      handle = await open(location.lock, "wx", 0o600);
+      await handle.writeFile(`${JSON.stringify({
+        version: 1,
+        token,
+        pid: process.pid,
+        hostname: hostname(),
+        command,
+        scope: location.scope,
+        startedAt: new Date().toISOString()
+      }, null, 2)}\n`, "utf8");
+      await handle.sync();
+      await handle.close();
+      return token;
+    } catch (error) {
+      try { await handle?.close(); } catch {}
+      if (error?.code !== "EEXIST") throw error;
+      const lock = await inspectLock(location);
+      if (lock.status === "none") continue;
+      if (lock.status === "stale") {
+        const before = await readText(location.lock);
+        const again = await readText(location.lock);
+        if (before.exists && again.exists && before.text === again.text) {
+          await rm(location.lock, { force: true });
+          continue;
+        }
+      }
+      const detail = lock.metadata
+        ? `${lock.metadata.command || "operation"} pid ${lock.metadata.pid}`
+        : lock.detail || "unknown lock owner";
+      throw new Error(`scope is locked by ${detail}`);
+    }
+  }
+  throw new Error("unable to acquire scope lock");
+}
+
+async function releaseLock(location, token) {
+  if (!token) return;
+  try {
+    const lock = await readText(location.lock);
+    if (!lock.exists) return;
+    const metadata = JSON.parse(lock.text);
+    if (metadata.token === token) await rm(location.lock, { force: true });
+  } catch {}
+}
+
+function print(output, status, detail) {
+  output?.(`${status}: experimental-v2${detail ? ` (${detail})` : ""}`);
+}
+
+function enablePlan(current, location) {
+  const next = appendBlock(current.config.text);
+  return {
+    configContent: next.content,
+    stateContent: `${JSON.stringify({
+      version: STATE_VERSION,
+      scope: location.scope,
+      configPath: location.config,
+      createdConfig: !current.config.exists,
+      separator: next.separator,
+      blockHash: digest(next.block),
+      enabledAt: new Date().toISOString()
+    }, null, 2)}\n`,
+    configStatus: current.config.exists ? "update" : "create"
+  };
+}
+
+function disablePlan(current) {
+  let before = current.config.text.slice(0, current.block.start);
+  const separator = current.state.state.separator;
+  if (separator && before.endsWith(separator)) before = before.slice(0, -separator.length);
+  const restored = `${before}${current.config.text.slice(current.block.end)}`;
+  const empty = restored.replace(/^\uFEFF/, "").trim() === "";
+  return {
+    restored,
+    deleteConfig: current.state.state.createdConfig && empty
+  };
+}
+
+async function restoreOriginalConfig(location, config) {
+  if (config.exists) await atomicWrite(location.config, config.text);
+  else await rm(location.config, { force: true });
+}
+
+async function enable(location, options) {
+  const preview = await inspect(location);
+  if (preview.status === "managed") {
+    print(options.output, "skip", "already enabled and managed");
+    return 0;
+  }
+  if (preview.status === "unmanaged") {
+    print(options.output, "preserve", preview.detail);
+    return 0;
+  }
+  if (preview.status !== "disabled") {
+    print(options.output, "fail", preview.detail || preview.status);
+    return 1;
+  }
+  if (options.dryRun) {
+    const plan = enablePlan(preview, location);
+    print(options.output, `would-${plan.configStatus}`, "config.toml");
+    print(options.output, "would-create", "experimental V2 state");
+    return 0;
+  }
+
+  let token;
+  try {
+    token = await acquireLock(location, "v2-enable");
+    const current = await inspect(location);
+    if (current.status !== "disabled") {
+      print(options.output, "fail", `state changed during enable: ${current.status}`);
+      return 1;
+    }
+    const plan = enablePlan(current, location);
+    await atomicWrite(location.config, plan.configContent);
+    try {
+      await atomicWrite(location.state, plan.stateContent);
+    } catch (error) {
+      await restoreOriginalConfig(location, current.config);
+      throw error;
+    }
+    print(options.output, plan.configStatus, "config.toml");
+    print(options.output, "create", "experimental V2 state");
+    return 0;
+  } finally {
+    await releaseLock(location, token);
+  }
+}
+
+async function disable(location, options) {
+  const preview = await inspect(location);
+  if (preview.status === "disabled" || preview.status === "unmanaged") {
+    if (!options.onlyManaged) print(options.output, preview.status === "disabled" ? "skip" : "preserve", preview.detail || "not enabled by this package");
+    return 0;
+  }
+  if (preview.status !== "managed") {
+    print(options.output, "preserve", preview.detail || preview.status);
+    return 1;
+  }
+  if (options.dryRun) {
+    const plan = disablePlan(preview);
+    print(options.output, plan.deleteConfig ? "would-remove" : "would-update", "config.toml");
+    print(options.output, "would-remove", "experimental V2 state");
+    return 0;
+  }
+
+  let token;
+  try {
+    token = await acquireLock(location, "v2-disable");
+    const current = await inspect(location);
+    if (current.status !== "managed") {
+      print(options.output, "preserve", `state changed during disable: ${current.status}`);
+      return 1;
+    }
+    const plan = disablePlan(current);
+    if (plan.deleteConfig) await rm(location.config, { force: true });
+    else await atomicWrite(location.config, plan.restored);
+    try {
+      await rm(location.state, { force: true });
+    } catch (error) {
+      await atomicWrite(location.config, current.config.text);
+      throw error;
+    }
+    print(options.output, plan.deleteConfig ? "remove" : "update", "config.toml");
+    print(options.output, "remove", "experimental V2 state");
+    return 0;
+  } finally {
+    await releaseLock(location, token);
+  }
+}
+
+async function status(location, options) {
+  const current = await inspect(location);
+  const mapping = {
+    managed: ["healthy", "managed experimental setting"],
+    disabled: ["disabled", "not enabled"],
+    unmanaged: ["preserve", current.detail],
+    untracked: ["unsafe-state", current.detail],
+    missing: ["missing", current.detail],
+    "user-modified": ["user-modified", current.detail],
+    invalid: ["invalid", current.detail]
+  };
+  const [label, detail] = mapping[current.status] || ["invalid", current.status];
+  if (!(options.quietIfDisabled && current.status === "disabled")) print(options.output, label, detail);
+  return ["managed", "disabled", "unmanaged"].includes(current.status) ? 0 : 1;
+}
+
+function parseArgs(argv) {
+  if (!argv.length || argv.includes("--help") || argv.includes("-h")) return { help: true };
+  const [action, ...flags] = argv;
+  if (!["enable", "disable", "status"].includes(action)) return { error: "unknown V2 action" };
+  const parsed = { action, global: false, dryRun: false };
+  for (const flag of flags) {
+    if (flag === "--global") parsed.global = true;
+    else if (flag === "--dry-run" && action !== "status") parsed.dryRun = true;
+    else return { error: `unsupported option for v2 ${action}: ${flag}` };
+  }
+  return parsed;
+}
+
+export function v2Usage() {
+  return `Experimental Codex multi-agent V2 settings\n\nUsage:\n  codex-model-router v2 enable [--global] [--dry-run]\n  codex-model-router v2 disable [--global] [--dry-run]\n  codex-model-router v2 status [--global]\n\nThis is an undocumented Codex setting and may change or stop working without notice.`;
+}
+
+export async function runV2Command(argv, options = {}) {
+  const output = options.output ?? console.log;
+  const parsed = parseArgs(argv);
+  if (parsed.help) {
+    output(v2Usage());
+    return 0;
+  }
+  if (parsed.error) {
+    output(`${parsed.error}\n\n${v2Usage()}`);
+    return 1;
+  }
+  try {
+    const location = await locationFor(options, parsed.global);
+    if (parsed.action === "enable") return enable(location, { output, dryRun: parsed.dryRun });
+    if (parsed.action === "disable") return disable(location, { output, dryRun: parsed.dryRun });
+    return status(location, { output });
+  } catch (error) {
+    print(output, "fail", error.message);
+    return 1;
+  }
+}
+
+function scopeFlags(argv) {
+  return { global: argv.includes("--global"), dryRun: argv.includes("--dry-run") };
+}
+
+export async function reportV2Doctor(argv, options = {}) {
+  const output = options.output ?? console.log;
+  try {
+    const location = await locationFor(options, scopeFlags(argv).global);
+    return status(location, { output, quietIfDisabled: true });
+  } catch (error) {
+    print(output, "fail", error.message);
+    return 1;
+  }
+}
+
+export async function cleanupV2AfterUninstall(argv, options = {}) {
+  const output = options.output ?? console.log;
+  try {
+    const flags = scopeFlags(argv);
+    const location = await locationFor(options, flags.global);
+    if (!(await readText(location.state)).exists) return 0;
+    return disable(location, { output, dryRun: flags.dryRun, onlyManaged: true });
+  } catch (error) {
+    print(output, "fail", error.message);
+    return 1;
+  }
+}

package/lib/manifest.js

@@ -87,7 +87,7 @@ Return only the artifact required by the current stage.
 const luna = `name = "luna"
 description = "Implements clear, bounded work from an approved plan."
 model = "gpt-5.6-luna"
-model_reasoning_effort = "max"
+model_reasoning_effort = "xhigh"
 sandbox_mode = "workspace-write"
 developer_instructions = """
 Implement the current approved plan with the smallest coherent change.
@@ -155,45 +155,91 @@ Omit irrelevant fields and vague instructions. Preserve verified work, revise on
 Verification answers separately: did implementation match the plan, and did the plan plus implementation satisfy the request? Use PASS, IMPLEMENTATION_FIX, PLAN_REVISION, EVIDENCE_GAP, or REQUIREMENT_CLARIFICATION.
 `;
 
-export const TEMPLATES = Object.freeze({
-  terra: Object.freeze({ relative: ["agents", "terra.toml"], content: terra }),
-  luna: Object.freeze({ relative: ["agents", "luna.toml"], content: luna }),
-  sol: Object.freeze({ relative: ["agents", "sol.toml"], content: sol }),
-  skill: Object.freeze({ relative: ["model-router", "SKILL.md"], content: skill }),
-  planning: Object.freeze({ relative: ["implementation-planning", "SKILL.md"], content: planning })
+export const REASONING_EFFORTS = Object.freeze([
+  "none",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max"
+]);
+
+export const DEFAULT_AGENT_REASONING = Object.freeze({
+  terra: "high",
+  luna: "xhigh",
+  sol: "medium"
 });
 
-export const MANAGED_FILE_NAMES = Object.freeze(["terra", "luna", "sol", "skill", "planning"]);
 export const AGENT_NAMES = Object.freeze(["terra", "luna", "sol"]);
 
-export const LEGACY_TEMPLATES = Object.freeze({
-  terra: Object.freeze([]),
-  luna: Object.freeze([legacyLunaV12]),
-  sol: Object.freeze([legacySolWorkspaceWrite, legacySolReadOnly]),
-  skill: Object.freeze([legacySkillWorkspaceWrite, legacySkillReadOnly]),
-  planning: Object.freeze([])
-});
+const AGENT_BASE_TEMPLATES = Object.freeze({ terra, luna, sol });
+
+function withReasoning(content, reasoning) {
+  const pattern = /^model_reasoning_effort = "[^"]+"$/m;
+  if (!pattern.test(content)) throw new Error("agent template is missing model_reasoning_effort");
+  return content.replace(pattern, `model_reasoning_effort = "${reasoning}"`);
+}
+
+export const TEMPLATES = {
+  terra: { relative: Object.freeze(["agents", "terra.toml"]), content: terra },
+  luna: { relative: Object.freeze(["agents", "luna.toml"]), content: luna },
+  sol: { relative: Object.freeze(["agents", "sol.toml"]), content: sol },
+  skill: { relative: Object.freeze(["model-router", "SKILL.md"]), content: skill },
+  planning: { relative: Object.freeze(["implementation-planning", "SKILL.md"]), content: planning }
+};
+
+export const MANAGED_FILE_NAMES = Object.freeze(["terra", "luna", "sol", "skill", "planning"]);
 
-export const AGENT_EXPECTATIONS = Object.freeze({
-  terra: Object.freeze({
+export const LEGACY_TEMPLATES = {
+  terra: [],
+  luna: [legacyLunaV12, withReasoning(luna, "max")],
+  sol: [legacySolWorkspaceWrite, legacySolReadOnly],
+  skill: [legacySkillWorkspaceWrite, legacySkillReadOnly],
+  planning: []
+};
+
+export const AGENT_EXPECTATIONS = {
+  terra: {
     name: "terra",
     model: "gpt-5.6-terra",
     model_reasoning_effort: "high",
     sandbox_mode: "read-only"
-  }),
-  luna: Object.freeze({
+  },
+  luna: {
     name: "luna",
     model: "gpt-5.6-luna",
-    model_reasoning_effort: "max",
+    model_reasoning_effort: "xhigh",
     sandbox_mode: "workspace-write"
-  }),
-  sol: Object.freeze({
+  },
+  sol: {
     name: "sol",
     model: "gpt-5.6-sol",
     model_reasoning_effort: "medium",
     sandbox_mode: "read-only"
-  })
-});
+  }
+};
+
+export function configureAgentReasoning(overrides = {}, migrateFrom = {}) {
+  const selected = { ...DEFAULT_AGENT_REASONING, ...overrides };
+  for (const [name, reasoning] of Object.entries(selected)) {
+    if (!AGENT_NAMES.includes(name)) throw new Error(`unknown agent: ${name}`);
+    if (!REASONING_EFFORTS.includes(reasoning)) {
+      throw new Error(`unsupported reasoning effort for ${name}: ${reasoning}`);
+    }
+  }
+
+  for (const name of AGENT_NAMES) {
+    const previous = migrateFrom[name];
+    if (typeof previous === "string" && !LEGACY_TEMPLATES[name].includes(previous)) {
+      LEGACY_TEMPLATES[name].push(previous);
+    }
+    TEMPLATES[name].content = withReasoning(AGENT_BASE_TEMPLATES[name], selected[name]);
+    AGENT_EXPECTATIONS[name].model_reasoning_effort = selected[name];
+  }
+  return Object.freeze({ ...selected });
+}
+
+configureAgentReasoning();
 
 export const SKILL_EXPECTATIONS = Object.freeze({
   skill: Object.freeze({

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "codex-model-router",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Safely install adaptive free-mode Codex routing for Terra, Luna, and Sol.",
   "type": "module",
   "bin": {
     "codex-model-router": "./bin/codex-model-router.js"
   },
   "scripts": {
-    "check": "node --check bin/codex-model-router.js && node --check lib/manifest.js && node --check lib/router.js && node --check lib/router-core.js && node --check lib/toml.js && node --check scripts/release-metadata.js && node --check scripts/verify-published.js",
-    "test": "node --test",
+    "check": "node --check bin/codex-model-router.js && node --check lib/agent-reasoning-cli.js && node --check lib/experimental-v2.js && node --check lib/manifest.js && node --check lib/router.js && node --check lib/router-core.js && node --check lib/toml.js && node --check scripts/run-tests.js && node --check scripts/release-metadata.js && node --check scripts/verify-published.js",
+    "test": "node scripts/run-tests.js",
     "test:package": "node scripts/package-smoke.js"
   },
   "engines": {
@@ -27,6 +27,7 @@
     "codex-cli",
     "openai",
     "model-router",
+    "multi-agent",
     "subagent",
     "subagents",
     "agent-routing",