@lyupro/codex-bridge 0.5.5 → 0.6.1

package/cli/model.mjs

@@ -0,0 +1,84 @@
+/** Shows and edits machine-wide delegated profiles using the live catalogue (Plan_56). */
+import path from 'node:path';
+import { AGENTS } from '../src/home/lib/agents.mjs';
+import { CONFIG_PATH, readRunConfig } from '../src/home/lib/run-config.mjs';
+import { runProfile } from '../src/home/lib/runner/codex-args.mjs';
+import { fetchCatalogue, parseCatalogue } from './model-catalogue.mjs';
+import { editModelProfile } from './model-set.mjs';
+import { editModelSpeed } from './model-speed.mjs';
+import { readCodexUserTier } from './codex-user-config.mjs';
+import { renderTable } from './table.mjs';
+
+const PROFILE_COLUMNS = ['role', 'model', 'effort', 'speed', 'source']
+  .map((key) => ({ key, header: key, fixed: true }));
+const CATALOGUE_COLUMNS = ['slug', 'reasoning levels', 'default level', 'fast tier', 'visibility']
+  .map((key) => ({ key, header: key, fixed: true }));
+
+// An unpinned model is not a default this package supplies — Codex picks one, and saying
+// "built-in default" would credit the package with a choice it never made. The three cases stay
+// three, because provenance is half of what this command exists to answer.
+const MODEL_SOURCE = { config: 'config file' };
+const EFFORT_SOURCE = { config: 'config file', request: 'this run' };
+
+function profileSource(profile, role, userTier) {
+  const model = MODEL_SOURCE[profile.model_source] ?? 'not set (Codex chooses)';
+  const effort = EFFORT_SOURCE[profile.effort_source] ?? 'package default';
+  const source = model === effort ? model : `model: ${model}; effort: ${effort}`;
+  const speed = profile.speed_source === 'config' ? 'config file'
+    : role === 'build' && userTier ? `operator Codex config (${userTier})` : 'not pinned';
+  const ignored = role === 'build' ? '' : ' (operator Codex config not read)';
+  return `${source}; speed: ${speed}${ignored}`;
+}
+
+/** Returns output for the dispatcher; explicit edit actions use the shared config writer. */
+export async function model(argv = [], options = {}) {
+  let action;
+  let optionArgs = argv;
+  if (argv[0] && !argv[0].startsWith('-')) {
+    action = argv[0];
+    optionArgs = argv.slice(1);
+  }
+  if (action === 'set' || action === 'unset') {
+    return editModelProfile(action, optionArgs, options);
+  }
+  if (action === 'speed') return editModelSpeed(optionArgs, options);
+  if (action && action !== 'list') {
+    return { exitCode: 2, output: `codex-bridge model: unknown action "${action}". Use model, model list, model set, model unset or model speed.` };
+  }
+  if (optionArgs.length) {
+    return { exitCode: 2, output: `codex-bridge model: unexpected argument "${optionArgs[0]}".` };
+  }
+
+  try {
+    if (action === 'list') {
+      const rows = parseCatalogue(await (options.fetchCatalogue ?? fetchCatalogue)());
+      return {
+        exitCode: 0,
+        output: renderTable(CATALOGUE_COLUMNS, rows, options.terminalWidth)
+          + (rows.length ? '' : '\nNo models returned by the live catalogue.'),
+      };
+    }
+
+    const configPath = path.resolve(options.configPath ?? CONFIG_PATH);
+    const config = readRunConfig(configPath);
+    const userTier = readCodexUserTier(options);
+    const rows = Object.entries(AGENTS).map(([agent, { role }]) => {
+      const profile = runProfile({ agent, models: config.models });
+      return {
+        role,
+        model: profile.model || 'Codex default (not pinned)',
+        effort: profile.effort,
+        speed: profile.speed || 'not pinned',
+        source: profileSource(profile, role, userTier),
+      };
+    });
+    return {
+      exitCode: 0,
+      output: `${renderTable(PROFILE_COLUMNS, rows, options.terminalWidth)}\n\nConfig file: ${configPath}\n`
+        + 'Machine-wide: shared by every project on this machine, not per-project.',
+    };
+  } catch (error) {
+    const subject = action === 'list' ? 'live catalogue unavailable; refusing to list models' : 'cannot read profile';
+    return { exitCode: 1, output: `codex-bridge model: ${subject}: ${error?.message ?? String(error)}` };
+  }
+}

package/cli/package-source.mjs

@@ -0,0 +1,59 @@
+/**
+ * Which copy of the package is answering, and whether the operator is standing in another one.
+ *
+ * Plan_19 gives the CLI a second name, and a global install puts a second copy of the package on
+ * the machine beside any clone. Every command copies host files from whichever copy launched it,
+ * so the answer depends on which copy that was — and until 2026-09-07 only `doctor` said so. That
+ * day the operator ran `codex-bridge update --force` from a 0.6.0 clone while PATH still held the
+ * previous release: the command compared the home against its OWN files, found them current, and
+ * answered "codex-bridge is up to date" without naming the package it meant. The fix is not a
+ * second detector — it is this one, shared.
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
+
+const PACKAGE_NAME = '@lyupro/codex-bridge';
+
+/** The kind of the copy at a known root. A path separator on Windows is a backslash too. */
+export function sourceAt(root) {
+  const resolved = path.resolve(root);
+  return {
+    root: resolved,
+    kind: resolved.split(/[\\/]/).includes('node_modules') ? 'installed copy' : 'clone',
+  };
+}
+
+export function packageSource() {
+  return sourceAt(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'));
+}
+
+function readPackage(file) {
+  try {
+    const value = readJsonFileSync(file);
+    return value?.name === PACKAGE_NAME && typeof value.version === 'string' ? value : null;
+  } catch {
+    // A directory that merely holds an unreadable package.json is not a checkout of this package.
+    return null;
+  }
+}
+
+/**
+ * The checkout the operator is standing in, when that is a different copy than the one running.
+ * Walking up from the working directory is how the case reproduces: the operator was inside the
+ * clone, the command came from PATH, and nothing in the answer connected the two.
+ */
+export function checkoutAt(cwd = process.cwd(), source = packageSource()) {
+  let directory = path.resolve(cwd);
+  for (;;) {
+    const found = readPackage(path.join(directory, 'package.json'));
+    if (found) {
+      return path.resolve(directory) === path.resolve(source.root)
+        ? null
+        : { root: directory, version: found.version, name: found.name };
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}

package/cli/permissions.mjs

@@ -22,20 +22,31 @@ function buildRules(commandTransform) {
  * source list answer two different questions and let a future alias bypass one of them.
  *
  * The deny half subtracts `prune` from the allow half rather than guarding it: `Bash(codex-bridge:*)`
- * would otherwise hand out the deletion this package refuses to give an agent. Its refusal is never
- * seen in a live session — a PreToolUse hook answers before permissions are consulted, and
- * prune-guard is installed always while these rules are optional. The 2026-08-09 run held that
- * observation open as a checklist item until it turned out to be the answer, not the obstacle.
+ * would otherwise hand out the deletion this package refuses to give an agent. Plan_56's
+ * 2026-09-07 reconnaissance established deny, ask, allow ordering before PreToolUse hooks:
+ * the narrow speed ask therefore wins over the broad allow, and no hook can waive it.
  */
 export const PERMISSION_RULES = Object.freeze({
   allow: buildRules((command) => command),
   deny: buildRules((command) => `${command} prune`),
+  ask: buildRules((command) => `${command} model speed`),
 });
 
-const allRules = new Set([...PERMISSION_RULES.allow, ...PERMISSION_RULES.deny]);
+const allRules = new Set(Object.values(PERMISSION_RULES).flat());
 const ruleLists = Object.freeze(['allow', 'deny', 'ask']);
-const activeLists = Object.freeze(['allow', 'deny']);
-const totalRules = PERMISSION_RULES.allow.length + PERMISSION_RULES.deny.length;
+const activeLists = ruleLists;
+const totalRules = allRules.size;
+
+/**
+ * Which lists a count covers, spelled once.
+ *
+ * Two sentences report that count — this module's own line and doctor's — and both used to name
+ * the lists in prose. Adding `ask` in Plan_56 updated one and left the other saying `allow/deny`
+ * over a number that already included the third list: a true number under a false label, which is
+ * the same defect Plan_22-1 caught in this very line. Derived from the list of lists so a fourth
+ * one cannot introduce a third spelling.
+ */
+export const RULE_LIST_NAMES = ruleLists.join('/');
 
 function listValue(settings, name) {
   const list = settings?.permissions?.[name];
@@ -47,19 +58,20 @@ function matchingRules(list, rules) {
 }
 
 /**
- * A count of strings in allow and deny is not the state of the set, because `ask` outranks `allow`:
+ * A count of installed strings is not the state of the set, because `ask` outranks `allow`:
  * a copy sitting there keeps asking the question the rule was added to end. The live run of
  * Plan_22-1 caught doctor reporting `installed (24/24)` over exactly that arrangement — the number
  * was true and the conclusion drawn from it was false. Every consumer reads the state, so the
- * shadow has to live in the state rather than in one command's wording.
+ * shadow has to live in the state rather than in one command's wording. Plan_56's own speed ask
+ * rules are intentional; only allow strings copied into ask count as that shadow.
  */
 function permissionStatus(settings) {
   const counts = Object.fromEntries(activeLists.map((name) => [
     name,
     matchingRules(listValue(settings, name), PERMISSION_RULES[name]),
   ]));
-  const askCount = matchingRules(listValue(settings, 'ask'), [...allRules]);
-  const present = counts.allow + counts.deny;
+  const askCount = matchingRules(listValue(settings, 'ask'), PERMISSION_RULES.allow);
+  const present = counts.allow + counts.deny + counts.ask;
   const complete = present === totalRules;
   const state = askCount
     ? (complete ? 'shadowed by ask' : 'partially installed, shadowed by ask')
@@ -138,31 +150,35 @@ export async function removePermissionRules(settingsPath, { dryRun = false } = {
   });
 }
 
-function statusOutput(status) {
-  const moved = status.askCount
+function statusOutput(status, action) {
+  const moved = status.askCount && action !== 'add'
     ? `; ${status.askCount} own string(s) in ask, which outranks allow`
     : '';
-  return `Permissions: ${status.state} (${status.present}/${status.total} own strings in allow/deny${moved}).`;
+  return `Permissions: ${status.state} (${status.present}/${status.total} own strings in ${RULE_LIST_NAMES}${moved}).`;
 }
 
 async function permissionsInRun({ host, action } = {}) {
   if (!host?.settingsPath) throw new TypeError('permissions requires a resolved host');
   if (!action) {
     const status = await inspectPermissions(host.settingsPath);
-    return { exitCode: 0, output: statusOutput(status), ...status };
+    return { exitCode: 0, output: statusOutput(status, action), ...status };
   }
   if (action === 'add') {
     const result = await addPermissionRules(host.settingsPath);
     // A string the operator moved into `ask` outranks the copy `add` just put into `allow`, so the
     // command would report a complete set while the questions it was run to end keep appearing.
-    // `ask` stays untouched — it is a hand-made decision — but silence about it is a false success.
+    // That allow string stays in `ask` — it is a hand-made decision — alongside our speed rules.
     const status = await inspectPermissions(host.settingsPath);
     const conflict = status.askCount
       ? ` ${status.askCount} own string(s) also sit in ask, which outranks allow; they were left there.`
       : '';
+    // The 2026-09-07, 0.6.0 install incident mistook a zero delta for failure; report the set too.
+    const added = result.added > 0
+      ? `Added ${result.added} permission rule string${result.added === 1 ? '' : 's'}. `
+      : '';
     return {
       exitCode: 0,
-      output: `Added ${result.added} permission rule string${result.added === 1 ? '' : 's'}.${conflict}`,
+      output: `${added}${statusOutput(status, action)}${conflict}`,
       ...result,
       askCount: status.askCount,
     };

package/cli/prune-plan.mjs

@@ -51,7 +51,7 @@ function gentleAction(root, project, run) {
   if (!files.length) return null;
   return {
     kind: 'run',
-    mode: 'gentle',
+    strategy: 'gentle',
     project,
     run: run.run,
     path: runDir,
@@ -65,7 +65,7 @@ function runPurgeAction(root, project, run) {
   const runDir = path.join(root, project, run.run);
   return {
     kind: 'run',
-    mode: 'purge',
+    strategy: 'purge',
     project,
     run: run.run,
     path: runDir,
@@ -79,7 +79,7 @@ function projectPurgeAction(root, project, runs) {
   const projectDir = path.join(root, project);
   return {
     kind: 'project',
-    mode: 'purge',
+    strategy: 'purge',
     project,
     run: null,
     path: projectDir,
@@ -194,7 +194,7 @@ export function prunePlan(args = {}, options = {}) {
   return {
     root,
     scope,
-    mode: args.purge ? 'purge' : 'gentle',
+    strategy: args.purge ? 'purge' : 'gentle',
     project: args.projectName || null,
     run: args.runName || null,
     olderThan: age,

package/cli/prune.mjs

@@ -34,7 +34,7 @@ function commandText(args) {
 function actionPayload(action) {
   return {
     kind: action.kind,
-    mode: action.mode,
+    strategy: action.strategy,
     project: action.project,
     run: action.run,
     targets: action.targets,
@@ -45,7 +45,7 @@ function actionPayload(action) {
 function basePayload(plan) {
   return {
     scope: plan.scope,
-    mode: plan.mode,
+    strategy: plan.strategy,
     project: plan.project,
     run: plan.run,
     olderThan: ageText(plan.olderThan),
@@ -57,7 +57,7 @@ function basePayload(plan) {
 
 function planLines(plan, args) {
   const lines = [
-    `Prune plan: ${plan.mode} ${plan.scope}.`,
+    `Prune plan: ${plan.strategy} ${plan.scope}.`,
     plan.olderThan ? `Age filter: older than ${ageText(plan.olderThan)} (folder name date).` : 'Age filter: none.',
   ];
   for (const action of plan.actions) {
@@ -160,8 +160,8 @@ function linkedSegment(target, root) {
   return null;
 }
 
-function currentTargetBytes(target, mode) {
-  if (mode === 'purge') {
+function currentTargetBytes(target, strategy) {
+  if (strategy === 'purge') {
     // The inventory's recursive measurement is the same accounting used by projects and keeps
     // the report honest when a purge contains nested files.
     return recursiveSize(target);
@@ -176,7 +176,7 @@ function currentTargetBytes(target, mode) {
 async function confirmAll(plan, args, options) {
   const prompt = options.prompt || defaultPrompt;
   for (const action of plan.actions) {
-    const question = action.mode === 'purge'
+    const question = action.strategy === 'purge'
       ? `Delete folder ${action.path}?`
       : `Delete archived transport from ${action.project}/${action.run}?\n  ${action.targets.join('\n  ')}`;
     let answer;
@@ -211,9 +211,9 @@ async function execute(plan, options) {
         failed.push({ target, error: `refusing to delete through a link: ${linked}` });
         continue;
       }
-      const bytes = currentTargetBytes(target, action.mode);
+      const bytes = currentTargetBytes(target, action.strategy);
       try {
-        fs.rmSync(target, { recursive: action.mode === 'purge', force: false });
+        fs.rmSync(target, { recursive: action.strategy === 'purge', force: false });
         removed.push(target);
         sizes.push(bytes);
       } catch (err) {

package/cli/rules-owners.mjs

@@ -4,14 +4,12 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { normalizeRepoPath } from '../src/home/lib/runner/project-dir.mjs';
 import { readJsonFile } from '../src/home/lib/json-file.mjs';
+import { withFileLock } from '../src/home/lib/file-lock.mjs';
+export { isLockTaken } from '../src/home/lib/file-lock.mjs';
 
 export const RULES_REGISTRY_NAME = '.codex-bridge-rules.json';
 export const RULES_REGISTRY_VERSION = 1;
 
-const REGISTRY_LOCK_RETRIES = 200;
-const REGISTRY_LOCK_DELAY_MS = 5;
-const REGISTRY_LOCK_STALE_MS = 30_000;
-
 export function rulesRegistryPath(host) {
   return path.join(host.codexRulesDir, RULES_REGISTRY_NAME);
 }
@@ -77,73 +75,8 @@ function registryLockPath(host) {
   return `${rulesRegistryPath(host)}.lock`;
 }
 
-function waitForRegistryLock() {
-  return new Promise((resolve) => setTimeout(resolve, REGISTRY_LOCK_DELAY_MS));
-}
-
-/**
- * A lock nobody released is worse than no lock: interrupting an install left the file behind and
- * every later install and uninstall died on it until someone deleted it by hand (reproduced
- * 2026-08-04). An owner update takes milliseconds, so a lock older than the staleness window
- * belongs to a process that is gone.
- */
-async function dropStaleLock(lockPath) {
-  try {
-    const { mtimeMs } = await fs.stat(lockPath);
-    if (Date.now() - mtimeMs < REGISTRY_LOCK_STALE_MS) return false;
-    await fs.rm(lockPath, { force: true });
-    return true;
-  } catch {
-    // Vanished or unreadable — let the next open() decide rather than guess here.
-    return false;
-  }
-}
-
-/**
- * Windows answers a taken lock with three different codes, and only one of them is EEXIST. A file
- * whose last handle closed while a delete was pending stays visible but refuses to be opened:
- * `open(..., 'wx')` comes back EPERM, and a file another process still holds comes back EBUSY.
- * Treating those as fatal is what made `tests/cli/rules-owners.test.mjs` fail twice on 2026-08-11
- * with EPERM on the lock file — the suite went red over a lock that was simply busy for one more
- * millisecond. All three mean the same thing to a caller waiting for a lock: not yours yet.
- */
-const LOCK_TAKEN_CODES = new Set(['EEXIST', 'EPERM', 'EBUSY']);
-
-/** Exported so the retry contract is asserted directly; the race itself reproduces only by luck. */
-export function isLockTaken(err) {
-  return LOCK_TAKEN_CODES.has(err?.code);
-}
-
-async function acquireRegistryLock(host) {
-  await fs.mkdir(host.codexRulesDir, { recursive: true });
-  const lockPath = registryLockPath(host);
-  let lastTaken;
-  for (let attempt = 0; attempt < REGISTRY_LOCK_RETRIES; attempt += 1) {
-    try {
-      const handle = await fs.open(lockPath, 'wx');
-      return { handle, lockPath };
-    } catch (err) {
-      if (!isLockTaken(err)) throw err;
-      lastTaken = err;
-      if (!(await dropStaleLock(lockPath))) await waitForRegistryLock();
-    }
-  }
-  // The code is part of the message: a timeout on EPERM points at a delete that never completed,
-  // a timeout on EEXIST at an owner that never released.
-  throw new Error(
-    `timed out waiting for rules ownership registry lock: ${lockPath} (last attempt: ${lastTaken.code})`,
-    { cause: lastTaken },
-  );
-}
-
 async function withRegistryLock(host, action) {
-  const lock = await acquireRegistryLock(host);
-  try {
-    return await action();
-  } finally {
-    await lock.handle.close().catch(() => {});
-    await fs.rm(lock.lockPath, { force: true }).catch(() => {});
-  }
+  return withFileLock(registryLockPath(host), action, { description: 'rules ownership registry' });
 }
 
 export async function readRulesRegistry(host) {

package/cli/table.mjs

@@ -23,10 +23,10 @@ export function truncateStart(value, width) {
   return `…${Array.from(text).slice(-(width - 1)).join('')}`;
 }
 
-function fit(value, width, mode) {
+function fit(value, width, truncate) {
   if (displayWidth(value) <= width) return value;
-  if (mode === 'start') return truncateStart(value, width);
-  if (mode === 'end') return `${Array.from(value).slice(0, Math.max(0, width - 1)).join('')}…`;
+  if (truncate === 'start') return truncateStart(value, width);
+  if (truncate === 'end') return `${Array.from(value).slice(0, Math.max(0, width - 1)).join('')}…`;
   return value;
 }
 
@@ -39,7 +39,7 @@ function normalizeColumn(column) {
     header: String(column.header ?? column.label ?? column.key),
     kind,
     align: column.align || (kind === 'number' ? 'right' : 'left'),
-    mode: column.truncate === undefined ? (fixed ? null : 'start') : column.truncate,
+    truncate: column.truncate === undefined ? (fixed ? null : 'start') : column.truncate,
   };
 }
 
@@ -65,7 +65,7 @@ function columnWidths(columns, rows, width) {
 
   const flexible = columns
     .map((column, index) => ({ column, index }))
-    .filter(({ column }) => column.mode === 'start' || column.mode === 'end');
+    .filter(({ column }) => column.truncate === 'start' || column.truncate === 'end');
   while (spare < 0) {
     let changed = false;
     for (const { column, index } of flexible) {
@@ -84,7 +84,7 @@ function columnWidths(columns, rows, width) {
 function renderRow(row, columns, widths, header = false) {
   return columns.map((column, index) => {
     const value = header ? column.header : rowValue(row, column);
-    const rendered = fit(value, widths[index], header ? null : column.mode);
+    const rendered = fit(value, widths[index], header ? null : column.truncate);
     const padding = Math.max(0, widths[index] - displayWidth(rendered));
     if (index === columns.length - 1) {
       return column.align === 'right' ? `${' '.repeat(padding)}${rendered}` : rendered;

package/cli/update.mjs

@@ -1,6 +1,7 @@
 /** Updates a recorded installation without overwriting unapproved host changes. */
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { packageSource, sourceAt, checkoutAt } from './package-source.mjs';
 import { install } from './install.mjs';
 import {
   buildInstallPlan,
@@ -197,6 +198,18 @@ async function updateInRun({ host, dryRun = false, force = false, packageRoot, e
   }
 
   const currentPackage = await packageInfo(packageRoot);
+  // The 2026-09-07, 0.6.0 install incident hid which package's files update actually compared.
+  const resolved = packageRoot ? sourceAt(packageRoot) : packageSource();
+  const source = `${currentPackage.name}@${currentPackage.version} from ${resolved.root}`
+    + ` (${resolved.kind === 'installed copy' ? 'installed package' : resolved.kind})`;
+  // Standing in one checkout while another copy answers is how that install went wrong: the reply
+  // was true about the package that ran and silent about the one the operator had on screen.
+  const elsewhere = checkoutAt(env.CODEX_BRIDGE_CWD ?? process.cwd(), resolved);
+  const mismatch = elsewhere && elsewhere.version !== currentPackage.version
+    ? `\nRun from ${currentPackage.version}; the checkout at ${elsewhere.root} is ${elsewhere.version}.`
+      + ' The home was updated from the copy that answered, not from that checkout'
+      + ` (npm i -g ${currentPackage.name}@${elsewhere.version} changes which one that is).`
+    : '';
   const targets = hookTargets(host, env, currentPackage.version);
   const inspectedHooks = await Promise.all(targets.map(async (target) => ({
     target,
@@ -217,10 +230,10 @@ async function updateInRun({ host, dryRun = false, force = false, packageRoot, e
       // it on this path costs nothing when there is nothing left to retire.
       await retireLegacyLayout(host);
     }
-    return { exitCode: 0, output: 'codex-bridge is up to date' };
+    return { exitCode: 0, output: `codex-bridge is up to date with ${source}${mismatch}` };
   }
   if (dryRun) {
-    return { exitCode: 0, output: dryRunOutput(states, inspectedHooks, legacy, oldHooks) };
+    return { exitCode: 0, output: `Would update codex-bridge with ${source}.${mismatch}\n${dryRunOutput(states, inspectedHooks, legacy, oldHooks)}` };
   }
 
   for (const state of orphanStates) {
@@ -236,7 +249,7 @@ async function updateInRun({ host, dryRun = false, force = false, packageRoot, e
   const installed = await install({ host, force: true, packageRoot, env });
   if (installed.exitCode !== 0) return installed;
   await retireLegacyLayout(host);
-  return { exitCode: 0, output: appliedOutput(states) };
+  return { exitCode: 0, output: `${appliedOutput(states)}\nSource: ${source}${mismatch}` };
 }
 
 export async function update(options = {}) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.5.5",
-  "description": "Claude Code-to-Codex delegation with 6 guards, 817 tests, zero runtime dependencies, and zero build steps.",
+  "version": "0.6.1",
+  "description": "Claude Code-to-Codex delegation with 6 guards, 963 tests, zero runtime dependencies, and zero build steps.",
   "keywords": [
     "claude-code",
     "codex",

package/src/agents/codex-review.md

@@ -23,9 +23,9 @@ opinion, not a verdict.
 ## What you receive as input
 
 - What to review. One of these modes:
-  - uncommitted changes (default) — `--mode uncommitted`;
-  - branch against base — `--mode base:<branch>`;
-  - specific commit — `--mode commit:<sha>`.
+  - uncommitted changes (default) — `--changeset uncommitted`;
+  - branch against base — `--changeset base:<branch>`;
+  - specific commit — `--changeset commit:<sha>`.
 - The path to the repository. If none is given, use the current working directory.
 - The path to a task file containing the review focus verbatim. The orchestrator supplies this
   path; pass it as `--task-file` and never create, read or rewrite it. Writing that file yourself
@@ -72,7 +72,7 @@ three in sequence and ended by telling its operator to grant a rule on `run-code
 ## The only thing you do
 
 ```bash
-codex-bridge run --agent codex-review --repo "<repository-path or .>" --mode "<one mode from the list above>" --slug "<slug>" --order-id "<order id from the orchestrator>" --task-file "<task-file path from the orchestrator>"
+codex-bridge run --agent codex-review --repo "<repository-path or .>" --changeset "<one changeset from the list above>" --slug "<slug>" --order-id "<order id from the orchestrator>" --task-file "<task-file path from the orchestrator>"
 ```
 
 Add `--effort "<value>"` only when the orchestrator named a depth, and only with one of

package/src/commands/model.md

@@ -0,0 +1,55 @@
+---
+description: Show, list or change the model and reasoning depth each delegated Codex role runs on
+allowed-tools: Bash
+argument-hint: "[list | set <role> <model> [effort] | unset <role> | speed <role> <tier> [confirm] | speed <role> unset]"
+---
+
+<!-- Part of the agents/codex-bridge/ package. The file lives here out of necessity: the slash
+     command name is set by its location under commands/<namespace>/, and Claude Code understands neither
+     symlinks nor pointer files (verified 2026-08-02). Edit it here; it travels as a copy when the
+     package is installed. -->
+
+Which model each delegated role runs on. The three roles are the scout, the builder and the
+reviewer, and each carries its own model and reasoning depth.
+
+Run exactly this command, substituting the user's arguments (`$ARGUMENTS`), and return its output
+verbatim. Add nothing and recompute nothing:
+
+```bash
+codex-bridge model $ARGUMENTS
+```
+
+Unlike the older `/codex-bridge:env`, this calls the short package command rather than a path to a
+file (Plan_56 D1). The operator's standing permission rule is written for that spelling, and moving
+the installed files can no longer break the call.
+
+Call forms:
+
+- no arguments — the model, reasoning depth, pinned speed tier and provenance of each role, plus the path of the
+  config file;
+- `list` — the live catalogue from Codex: every model, the reasoning levels it accepts, its default
+  level and its accelerated service tier identifiers (parallel speed labels are not extra tiers);
+- `set <role> <model> [effort]` — pin one role, with `--model` and `--effort` accepted instead of
+  the positions. The pair is checked against that model's own catalogue entry before anything is
+  written, so an unsupported depth is refused with the depths that model does accept, and a role
+  whose existing depth or pinned speed tier the new model cannot keep is refused with its supported values;
+- `unset <role>` — remove that role's profile, returning it to whatever Codex chooses;
+- `speed <role> <tier>` — preview an accelerated tier from the pinned model's live catalogue entry.
+  Pin a model with `set` first. The preview quotes the tier description verbatim and separately links
+  to https://learn.chatgpt.com/docs/agent-configuration/speed for credit multipliers; it writes nothing;
+- `speed <role> <tier> confirm` — fetch and validate again, then pin that exact tier and report the
+  previous and new profile. Unknown tiers or an unavailable catalogue are refused without a write;
+- `speed <role> unset` — remove only the speed pin immediately, preserving model and effort.
+  This needs no confirmation or catalogue; with no pin the package does not interfere with speed.
+
+Two things the output says that are worth repeating to the operator if they ask:
+
+- The profile is **machine-wide**. One config file serves every project on this machine, so
+  changing a role's model changes it for all of them, not for the repository you are standing in.
+- The catalogue is asked live every time. There is no cache and no bundled copy, because the copy
+  inside the Codex binary lists models the server no longer has — an operator who picked one from a
+  stale list would lose the quota before the run started.
+
+`set` and `unset` apply immediately; pinning a paid speed tier requires the second call ending in
+`confirm`. Never edit the config file directly to do what these commands do — model, effort and
+tier pins are checked against the live catalogue before writing.

package/src/home/hooks/order-gate.mjs

@@ -14,6 +14,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { AGENTS } from '../lib/agents.mjs';
 import { readJsonFileSync } from '../lib/json-file.mjs';
 import {
   diagnoseInput,
@@ -31,7 +32,7 @@ import { parseTaskDocument } from '../lib/runner/task-file.mjs';
 
 const HOME = os.homedir();
 const LOG_DIR = path.join(HOME, '.claude', 'logs');
-const GUARDED = new Set(['codex-scout', 'codex-build', 'codex-review']);
+const GUARDED = new Set(Object.keys(AGENTS));
 /**
  * Both spellings of the subagent-launching tool, from the same list the installer builds its
  * matcher from. Recognising only the name this host happens to use would make the gate silent

package/src/home/hooks/reply-guard.mjs

@@ -29,6 +29,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { AGENTS } from '../lib/agents.mjs';
 import { runOrderMismatch, transcriptOrderId } from '../lib/dispatcher-order.mjs';
 import { recognizeHostRefusal } from '../lib/host-refusal.mjs';
 import { readJsonFileSync } from '../lib/json-file.mjs';
@@ -65,7 +66,7 @@ import {
 // The broader hook-directory scan protects the extracted verdict text from the same incident.
 const HOME = os.homedir();
 const LOG_DIR = path.join(HOME, '.claude', 'logs');
-const GUARDED = new Set(['codex-scout', 'codex-build', 'codex-review']);
+const GUARDED = new Set(Object.keys(AGENTS));
 
 /**
  * How many times a single agent may be blocked over the SHAPE of its reply — no RUN= line,