@lyupro/codex-bridge 0.5.5 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-09-07
+
+### Added
+
+- `codex-bridge model` answers which model and reasoning depth each of the three roles runs on, and
+  where each value comes from — the operator's config file or the package default. The config is one
+  file per machine, shared by every project on it, and the command says so: changing a model here
+  changes the executor for every repository this host delegates from.
+- `codex-bridge model list` prints the live catalogue, hidden models included and marked as hidden.
+  A model Codex does not advertise is still a model the operator may choose; omitting it would mean
+  deciding for them and then explaining why the system has a model the list denies.
+- `codex-bridge model set <role> <model> [effort]` and `model unset <role>` write that choice. The
+  pair is checked against the catalogue entry of that very model at the moment of writing, so
+  `ultra` — supported by the newest model and rejected by the package's own flat list until now —
+  became reachable, and a depth the chosen model does not offer is refused with its supported
+  depths named. Nothing is substituted silently: the command never changes what it was not asked to.
+- `codex-bridge model speed <role> <tier>` pins a paid acceleration tier, and `model speed <role>
+  unset` removes it. The tier is spelled with the identifier the catalogue reports for that model,
+  never a word held in the package, and the command writes nothing until a second call ends in
+  `confirm` — the first prints the catalogue's own description of the tier and a link to the page
+  carrying the credit multipliers. The installer now also places one `ask` rule of its own, so the
+  host asks the operator before an agent can run that command at all.
+- A pinned tier reaches the run: the launcher passes `-c service_tier=<id>` when, and only when, a
+  role has one pinned.
+
+### Changed
+
+- The depth of a run is no longer validated against a list held in the package. That list had
+  drifted from the server in both directions — it offered a depth no model accepts and refused one
+  the newest model supports — so the writing command asks the catalogue and the hot path checks only
+  the shape of the value. The arbiter at run time is Codex itself, whose refusal is more accurate
+  than a copy of its data.
+- One boundary now owns every write to the run config, and it persists only the edit it was given.
+  Reading merges the package defaults, and the previous writer saved that merged object, so a single
+  edit would have frozen every default into the operator's file — worst of all the list of
+  environment paths, which the package extends as it learns of new ones and which decides whether a
+  change belongs to the run or to the environment.
+- The word `mode` no longer names three different things in this package. The reviewer's flag is
+  `--changeset`, the prune says which strategy, the table which truncation, and one registry answers
+  who the three agents are.
+- The README states the suite size it actually has.
+
+### Fixed
+
+- Two edits of the config racing each other can no longer lose one of them. Both commands read the
+  role profiles, waited seconds for the catalogue, then wrote what they had read, and three
+  concurrent processes all reported success while one edit was missing from the file. The edit
+  boundary now reads the file itself, hands the fresh value to the caller's transformer, compares
+  the bytes immediately before publishing, and holds the lock this package already used for the
+  rules-ownership registry — one definition now serves both writers.
+- The worktree lock reads the shell rather than the prose someone wrote into a document. A plain
+  `cat > file << EOF` handed the whole command, heredoc body included, to the analysis, so the word
+  `touch` inside an English sentence made the next words look like files being written. The reverse
+  hole closed with it: the tail after a heredoc's closing marker was not parsed at all.
+- A dead run stays dead even when Windows hands its process id to someone else.
+- The reader of the Codex user configuration answers about configuration, not about prose inside it.
+  A multi-line TOML literal could contain a line indistinguishable from an assignment, and it was
+  read as the setting; an empty argument threw past the module's own error boundary, which exists so
+  the table renders whatever state the file is in.
+
 ## [0.5.5] - 2026-08-28
 
 ### Fixed

package/README.md

@@ -26,6 +26,8 @@ Shipped agents invoke delegated runs through `codex-bridge run`. This is a permi
 not a style choice: the stable package command lets host permission rules match the invocation
 without exposing an installation-specific absolute path and prompting on every delegation.
 
+Installing optional permission rules now adds `model speed` rules to `ask`, previously left to the operator, alongside `allow` and `deny`. These narrow prompts outrank the broad command allow rules and are checked before hooks, so an agent must ask the operator before switching tiers even when acting in good faith. Removing the rules takes back these exact strings while preserving other operator settings.
+
 Use `--scope project` to install the Claude Code-facing files under `<repo>/.claude`; the default user scope uses `~/.claude`.
 
 Installation has two roots:
@@ -60,7 +62,7 @@ If a global install and a clone coexist, you have two package copies. `codex-bri
 - **Every run leaves an audit folder.** The verbatim task, scope, before/after git state, events, report, verdict, and reason remain together.
 - **Zero runtime dependencies and zero build steps.** The package is plain `.mjs` on the Node.js standard library.
 
-The current suite contains **817 automated tests: 816 passing and 1 skipped**.
+The current suite contains **961 automated tests: 960 passing and 1 skipped**.
 
 ## Verify
 
@@ -128,6 +130,7 @@ Transport files from runs at least **30 days** old are pruned automatically when
 | `uninstall [--scope user\|project] [--host <path>] [--dry-run]` | Remove recorded package files while preserving run artifacts. |
 | `doctor [--scope user\|project] [--host <path>] [--probe-contract]` | Diagnose the selected host and Codex connection. `--probe-contract` measures on a live host whether it still honours a hook refusal, and records the answer. |
 | `run <runner options> --task-file <abs path>` | Start or attach to a delegated run through the permission-stable package command. The task file carries the statement, the scout questions and the verification command; its path must be absolute. Piping the statement on stdin is the alternative channel, and the two cannot be combined. |
+| `model [list\|set\|unset\|speed]` | Show the model, effort, pinned speed tier and provenance of each role, with the config path; `model list` prints the live catalogue from Codex, hidden models included and marked; `model set <role> <model> [effort]` checks the pair and any retained speed tier against that model's catalogue entry, and `model unset <role>` removes the profile. `model speed <role> <tier>` previews a live accelerated tier and its quoted cost description; repeat with trailing `confirm` to pin it. `model speed <role> unset` removes only speed, without confirmation. The profile is machine-wide, shared by every project on this machine. |
 | `projects [<name>] [--json]` | List projects or runs in the run store. |
 | `prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]`<br>`prune --all-projects [--older-than <age>] [-f] [--json]` | Plan or perform operator-confirmed cleanup, for one project or across the whole run store. |
 | `unlock [<project>\|--all]` | Close records whose runner is gone. |

package/bin/codex-bridge.mjs

@@ -5,8 +5,9 @@ import { probeContract } from '../cli/probe-contract.mjs';
 import { isInvokedDirectly } from '../cli/invoked-directly.mjs';
 import { hook } from '../cli/hook.mjs';
 import { resolveHost } from '../cli/hosts.mjs';
-import { install } from '../cli/install.mjs';
-import { projects } from '../cli/projects.mjs';
+import { install } from '../cli/install.mjs';
+import { model } from '../cli/model.mjs';
+import { projects } from '../cli/projects.mjs';
 import { read } from '../cli/read.mjs';
 import { runCodexCommand } from '../src/home/lib/run-codex.mjs';
 import { packageInfo } from '../cli/manifest.mjs';
@@ -25,8 +26,9 @@ Usage:
   codex-bridge permissions [add|remove] [--scope user|project] [--host <path>]
   codex-bridge uninstall [--scope user|project] [--host <path>] [--dry-run]
   codex-bridge doctor [--scope user|project] [--host <path>] [--probe-contract]
-  codex-bridge run <runner options> --task-file <path>
-  codex-bridge projects [<name>] [--json]
+  codex-bridge run <runner options> --task-file <path>
+  codex-bridge model [list]
+  codex-bridge projects [<name>] [--json]
   codex-bridge prune <project> [<run>] [--purge] [--older-than <age>] [-f] [--json]
   codex-bridge prune --all-projects [--older-than <age>] [-f] [--json]
   codex-bridge unlock [<project>|--all]
@@ -43,8 +45,9 @@ Commands:
   permissions Show, add, or remove optional shell permission rules
   uninstall Remove installed files while preserving run artifacts
   doctor    Diagnose the selected Claude Code host (--probe-contract measures on a live host)
-  run       Start or attach to a delegated Codex run
-  projects  List projects or runs from the run store
+  run       Start or attach to a delegated Codex run
+  model     Show machine-wide model profiles or list the live catalogue
+  projects  List projects or runs from the run store
   prune     Remove archived transport, or purge selected run folders
   unlock    Close running records whose runner is gone
   read      Render a run's structured event stream
@@ -127,12 +130,17 @@ export async function main(argv, io = console) {
     io.log(result.output);
     return result.exitCode;
   }
-  if (command === 'projects') {
+  if (command === 'projects') {
     const result = projects(rest);
     io.log(result.output);
-    return result.exitCode;
-  }
-  if (command === 'prune') {
+    return result.exitCode;
+  }
+  if (command === 'model') {
+    const result = await model(rest);
+    io.log(result.output);
+    return result.exitCode;
+  }
+  if (command === 'prune') {
     const result = await prune(rest);
     io.log(result.output);
     return result.exitCode;

package/cli/codex-user-config.mjs

@@ -0,0 +1,36 @@
+/** Reads only the operator's root tier; Plan_56 keeps this separate from package profile pins. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveHost } from './hosts.mjs';
+
+export function readCodexUserTier(options) {
+  // Destructured inside the boundary, not in the signature: a null argument would throw past the
+  // catch below, and this reader exists so the profile table renders whatever the file holds.
+  try {
+    const { codexHome, homedir } = options ?? {};
+    const { codexRulesDir } = resolveHost({ codexHome, homedir });
+    const configPath = path.join(codexRulesDir, '..', 'config.toml');
+    const content = fs.readFileSync(configPath, 'utf8');
+    // A multi-line literal can hold anything, including a line that looks like a table header or
+    // like this very assignment. Tracking the delimiter keeps text inside a value from being read
+    // as configuration — the alternative is answering confidently with someone's prose.
+    let openDelimiter = '';
+    for (const line of content.split(/\r?\n/)) {
+      if (openDelimiter) {
+        if (line.includes(openDelimiter)) openDelimiter = '';
+        continue;
+      }
+      const opening = /(?:^|=)\s*("""|''')/.exec(line);
+      if (opening && line.split(opening[1]).length === 2) {
+        openDelimiter = opening[1];
+        continue;
+      }
+      if (/^\s*\[/.test(line)) break;
+      const match = line.match(/^\s*service_tier\s*=\s*(?:"([^"]*)"|'([^']*)')\s*(?:#.*)?$/);
+      if (match) return match[1] ?? match[2];
+    }
+  } catch {
+    // Plan_56: optional user-config provenance must not prevent the profile table from rendering.
+  }
+  return '';
+}

package/cli/doctor-installation.mjs

@@ -7,7 +7,7 @@ import {
   fileFingerprint,
 } from './manifest.mjs';
 import { plannedContent } from './copy.mjs';
-import { inspectPermissions } from './permissions.mjs';
+import { RULE_LIST_NAMES, inspectPermissions } from './permissions.mjs';
 import { readRulesRegistry } from './rules-owners.mjs';
 import { parseFrontmatter } from './frontmatter.mjs';
 import { check } from './doctor-format.mjs';
@@ -104,7 +104,7 @@ export async function permissionsCheck(host) {
     // is not: the live run of Plan_22-1 found this line saying `installed (24/24)` over it.
     const shadow = status.askCount ? `, ${status.askCount} shadowed by ask` : '';
     return check('permissions', status.state === 'installed' ? 'ok' : 'warn',
-      `${status.state} (${status.present}/${status.total} own strings in allow/deny${shadow})`);
+      `${status.state} (${status.present}/${status.total} own strings in ${RULE_LIST_NAMES}${shadow})`);
   } catch (err) {
     return check('permissions', 'warn', `cannot inspect permission rules: ${err.message}`);
   }

package/cli/install-record.mjs

@@ -4,6 +4,17 @@ import path from 'node:path';
 import { readJsonFile } from '../src/home/lib/json-file.mjs';
 import { HOOK_DEFINITIONS } from '../src/home/lib/hook-definitions.mjs';
 
+/**
+ * The record's own spelling of the field saying how the package was installed, and its one value.
+ *
+ * Plan_56 D11 keeps that field spelled `mode` on disk: install records already sit on three hosts,
+ * and renaming a field nobody reads by eye would cost compatibility for tidiness. D20 keeps the
+ * word out of the code regardless — one constant knows the spelling, reader and writer go through
+ * it, and the guard forbidding `mode` as a name needs no exclusion list to stay quiet here.
+ */
+export const INSTALL_METHOD_KEY = 'mode';
+export const INSTALL_METHOD_COPY = 'copy';
+
 export const INSTALL_RECORD_NAME = '.installed.json';
 export const LEGACY_INSTALL_RECORD_NAME = '.codex-bridge-install.json';
 export const RULES_NAME = 'codex-bridge.rules';
@@ -145,10 +156,12 @@ export function validateInstallRecord(record) {
   if (!record || typeof record !== 'object' || Array.isArray(record)) {
     throw new Error('installation record must be an object');
   }
-  for (const key of ['name', 'version', 'installedAt', 'mode']) {
+  for (const key of ['name', 'version', 'installedAt', INSTALL_METHOD_KEY]) {
     if (typeof record[key] !== 'string' || !record[key]) throw new Error(`installation record has invalid ${key}`);
   }
-  if (record.mode !== 'copy') throw new Error('installation record mode must be copy');
+  if (record[INSTALL_METHOD_KEY] !== INSTALL_METHOD_COPY) {
+    throw new Error(`installation record ${INSTALL_METHOD_KEY} must be ${INSTALL_METHOD_COPY}`);
+  }
   if (Number.isNaN(Date.parse(record.installedAt))) throw new Error('installation record installedAt is invalid');
   const files = normalizedFiles(record);
   if (record.fingerprints !== undefined) fingerprintPairs(files, record.fingerprints);

package/cli/install.mjs

@@ -16,7 +16,7 @@ import {
 } from './manifest.mjs';
 import { copyPlannedFile, targetMatches } from './copy.mjs';
 import { hookTargets } from './hook-targets.mjs';
-import { fingerprintFor } from './install-record.mjs';
+import { fingerprintFor, INSTALL_METHOD_COPY, INSTALL_METHOD_KEY } from './install-record.mjs';
 import {
   commandFor,
   hookRegistration,
@@ -255,7 +255,7 @@ async function installInRun({
   await writeInstallRecord(host, {
     ...currentPackage,
     installedAt: new Date().toISOString(),
-    mode: 'copy',
+    [INSTALL_METHOD_KEY]: INSTALL_METHOD_COPY,
     files: plan.map((item) => ({ root: item.root, path: item.relativeToRoot })),
     fingerprints,
     rules: { path: rule.target, fingerprint: await fileFingerprint(rule.target) },

package/cli/manifest.mjs

@@ -51,7 +51,7 @@ const RULES_SOURCE = `src/rules/${RULES_NAME}`;
 /**
  * Files the operator owns once they exist. Seeded on first install so the defaults are
  * visible and editable, then never written, never compared, never removed: config.json
- * is where a host states which model each mode runs on, conventions.md is the rule set it hands
+ * is where a host states which model each role runs on, conventions.md is the rule set it hands
  * every run, and an installer that overwrites either would erase host decisions on the next
  * update — the same way overwriting a .env would.
  */

package/cli/model-catalogue.mjs

@@ -0,0 +1,81 @@
+/** Fetches and validates the raw Codex catalogue for Plan_56 step 2. */
+import { spawnSync } from 'node:child_process';
+import { parseJsonText } from '../src/home/lib/json-file.mjs';
+
+export function fetchCatalogue({ run = spawnSync } = {}) {
+  const command = process.platform === 'win32' ? process.env.ComSpec || 'cmd.exe' : 'codex';
+  const args = process.platform === 'win32'
+    ? ['/d', '/s', '/c', 'codex debug models'] : ['debug', 'models'];
+  // Plan_56: each invocation asks Codex again; its bundled catalogue is not live availability.
+  const result = run(command, args, {
+    encoding: 'utf8', windowsHide: true, timeout: 30_000, maxBuffer: 16 * 1024 * 1024,
+  });
+  // Plan_56: Codex can emit bundled JSON with status 0 after reporting a refresh failure.
+  const refreshFailed = /failed to refresh available models/i.test(result.stderr || '');
+  if (result.error || result.signal || result.status !== 0 || refreshFailed) {
+    const cause = [
+      result.error && `${result.error.code || 'process error'}: ${result.error.message}`,
+      result.stderr?.trim(),
+      result.signal && `signal ${result.signal}`,
+      result.status != null && `exit code ${result.status}`,
+    ].filter(Boolean).join('; ');
+    throw new Error(`codex debug models failed: ${cause || 'no process exit status'}`);
+  }
+  return result.stdout;
+}
+
+function textField(value, field) {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`codex debug models: ${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function listField(value, field) {
+  if (!Array.isArray(value)) throw new Error(`codex debug models: ${field} must be an array`);
+  return value;
+}
+
+function catalogueRow(entry, index) {
+  const field = `models[${index}]`;
+  const slug = textField(entry?.slug, `${field}.slug`);
+  const levels = listField(entry.supported_reasoning_levels, `${field}.supported_reasoning_levels`)
+    .map((level, position) => textField(level?.effort, `${field}.supported_reasoning_levels[${position}].effort`));
+  const defaultLevel = entry.default_reasoning_level == null
+    ? 'not specified' : textField(entry.default_reasoning_level, `${field}.default_reasoning_level`);
+  const visibility = textField(entry.visibility, `${field}.visibility`);
+  if (!['list', 'hide', 'none'].includes(visibility)) {
+    throw new Error(`codex debug models: ${field}.visibility is unknown: ${visibility}`);
+  }
+  if (entry.additional_speed_tiers !== undefined) {
+    listField(entry.additional_speed_tiers, `${field}.additional_speed_tiers`)
+      .forEach((tier, position) => textField(tier, `${field}.additional_speed_tiers[${position}]`));
+  }
+  const serviceTiers = entry.service_tiers === undefined ? []
+    : listField(entry.service_tiers, `${field}.service_tiers`)
+      .map((tier, position) => ({
+        id: textField(tier?.id, `${field}.service_tiers[${position}].id`),
+        description: textField(tier?.description, `${field}.service_tiers[${position}].description`),
+      }));
+  // Plan_56 step 4: parallel speed labels describe the same tiers; only service IDs are pins.
+  const fastTiers = [...new Set(serviceTiers.map(({ id }) => id))];
+  return {
+    slug,
+    supportedReasoningLevels: levels,
+    serviceTiers,
+    hidden: visibility !== 'list',
+    'reasoning levels': levels.length ? levels.join(', ') : 'not specified',
+    'default level': defaultLevel,
+    'fast tier': fastTiers.length ? `yes (${fastTiers.join(', ')})` : 'no',
+    visibility: visibility === 'list' ? 'listed' : `hidden (${visibility})`,
+  };
+}
+
+export function parseCatalogue(json) {
+  // Through the shared reader, not JSON.parse: one place strips the byte-order mark and names the
+  // source in the error, and a gate keeps every module on it. The "file" here is the command whose
+  // output failed, which is what the operator needs to see.
+  const catalogue = parseJsonText('codex debug models', json);
+  // Plan_56: invalid metadata refuses the whole list instead of silently dropping working models.
+  return listField(catalogue?.models, 'models').map(catalogueRow);
+}

package/cli/model-set.mjs

@@ -0,0 +1,141 @@
+/** Writes only the requested role; Plan_56 step 3 validates its pair before the shared edit. */
+import path from 'node:path';
+import { CONFIG_PATH } from '../src/home/lib/run-config.mjs';
+import { ROLES, validateRunConfig } from '../src/home/lib/config-validate.mjs';
+import { readJsonFileSync } from '../src/home/lib/json-file.mjs';
+import { editRunConfig } from '../src/home/lib/config-edit.mjs';
+import { fetchCatalogue, parseCatalogue } from './model-catalogue.mjs';
+
+const failure = (exitCode, message) => ({ exitCode, output: `codex-bridge model: ${message}` });
+const refusal = (message) => Object.assign(new Error(message), { exitCode: 2 });
+
+function parseChanges(args) {
+  const changes = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    let field;
+    let value = argument;
+    if (argument.startsWith('-')) {
+      if (argument !== '--model' && argument !== '--effort') {
+        throw new Error(`unexpected argument "${argument}".`);
+      }
+      field = argument.slice(2);
+      value = args[++index];
+      if (value === undefined || value.startsWith('-')) throw new Error(`missing value for ${argument}.`);
+    } else {
+      field = ['model', 'effort'].find((key) => changes[key] === undefined);
+      if (!field) throw new Error(`unexpected argument "${argument}".`);
+    }
+    if (changes[field] !== undefined) throw new Error(`${field} was supplied more than once.`);
+    if (!value || /\s/.test(value)) {
+      throw new Error(`${field} must be a non-empty single word with no whitespace.`);
+    }
+    changes[field] = value;
+  }
+  if (!Object.keys(changes).length) throw new Error('set requires a model or --effort value.');
+  return changes;
+}
+
+export function readProfiles(configPath) {
+  let config;
+  try {
+    config = readJsonFileSync(configPath);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    config = {};
+  }
+  validateRunConfig(configPath, config);
+  // The reader trims fields and drops empty profiles. Those are not edits the operator asked for.
+  return { ...config.models };
+}
+
+// The same sentence the config module already prints for a profile. A serialized object here
+// would be the second spelling of one idea, and the operator reading it is a person, not a parser.
+export function describe(profile) {
+  if (!profile || !Object.keys(profile).length) return 'not set (Codex chooses)';
+  const model = profile.model || 'default model';
+  return `${model}${profile.effort ? ` at ${profile.effort} effort` : ''}`
+    + (profile.speed ? ` on ${profile.speed} tier` : '');
+}
+
+export async function editModelProfile(action, argv, options) {
+  const [role, ...args] = argv;
+  if (!ROLES.includes(role)) {
+    return failure(2, `${role ? `unknown role "${role}"` : 'role is required'}. Allowed roles: ${ROLES.join(', ')}.`);
+  }
+  let changes;
+  try {
+    if (action === 'unset' && args.length) throw new Error(`unexpected argument "${args[0]}".`);
+    if (action === 'set') changes = parseChanges(args);
+  } catch (error) {
+    return failure(2, error.message);
+  }
+
+  try {
+    const configPath = path.resolve(options.configPath ?? CONFIG_PATH);
+    let catalogue;
+    if (action === 'set') {
+      try {
+        catalogue = parseCatalogue(await (options.fetchCatalogue ?? fetchCatalogue)());
+      } catch (error) {
+        return failure(1, `live catalogue unavailable; refusing to set ${role}: ${error?.message ?? String(error)}`);
+      }
+    }
+    let profiles;
+    let before;
+    let hiddenNotice = '';
+    let catalogueModel;
+    await editRunConfig('models', (current) => {
+      // An absent key is a config that has no profiles yet, not a malformed one: validating
+      // {models: undefined} turned "no configured model" into the validator's own refusal.
+      if (current !== undefined) validateRunConfig(configPath, { models: current });
+      profiles = { ...current };
+      before = profiles[role];
+      hiddenNotice = '';
+      if (action === 'set') {
+        const after = { ...before, ...changes };
+        const modelId = after.model?.trim();
+        const effort = after.effort?.trim();
+        // D40/D41: a retry cannot apply a catalogue decision to a different role model.
+        if (catalogueModel !== undefined && modelId !== catalogueModel) {
+          throw new Error('The profile changed while the catalogue was being read; nothing was written. Run the command again.');
+        }
+        if (!modelId) throw refusal(`${role} has no configured model; supply a model or --model.`);
+        const entry = catalogue.find(({ slug }) => slug === modelId);
+        if (!entry) {
+          throw refusal(`unknown model "${after.model}". Available models: ${catalogue.map(({ slug }) => slug).join(', ') || '(empty catalogue)'}. Nothing written.`);
+        }
+        if (effort !== undefined && !entry.supportedReasoningLevels.includes(effort)) {
+          const origin = changes.effort === undefined ? 'existing effort' : 'effort';
+          throw refusal(`${origin} "${after.effort}" is not supported by model "${after.model}". `
+            + `Supported depths: ${entry.supportedReasoningLevels.join(', ') || '(no depths advertised)'}. `
+            + 'Supply a supported effort explicitly. Nothing written.');
+        }
+        if (after.speed !== undefined && !entry.serviceTiers.some(({ id }) => id === after.speed.trim())) {
+          // Two sentences rather than a list that reads "tiers: (no tier)": a model offering none at
+          // all is a different answer from one offering others, and the operator acts on it differently.
+          const offered = entry.serviceTiers.length
+            ? `Accelerated tiers it does offer: ${entry.serviceTiers.map(({ id }) => id).join(', ')}.`
+            : 'That model offers no accelerated tier at all.';
+          throw refusal(`existing speed "${after.speed}" is not supported by model "${after.model}". `
+            + `${offered} `
+            + `Remove the pin with model speed ${role} unset first. Nothing written.`);
+        }
+        catalogueModel = entry.slug;
+        if (entry.hidden) hiddenNotice = `Model "${entry.slug}" is hidden in the Codex catalogue.\n`;
+        profiles[role] = after;
+      } else {
+        delete profiles[role];
+      }
+      return profiles;
+    }, configPath);
+    return {
+      exitCode: 0,
+      output: `${hiddenNotice}${role}: ${describe(before)} -> ${describe(profiles[role])}\nConfig file: ${configPath}\n`
+        + 'Machine-wide: shared by every project on this machine, not per-project.',
+    };
+  } catch (error) {
+    if (error.exitCode === 2) return failure(2, error.message);
+    return failure(1, `cannot ${action} profile: ${error?.message ?? String(error)}`);
+  }
+}

package/cli/model-speed.mjs

@@ -0,0 +1,96 @@
+/** Plan_56 step 4: paid tiers are catalogue decisions applied only by an explicit second call. */
+import path from 'node:path';
+import { CONFIG_PATH } from '../src/home/lib/run-config.mjs';
+import { ROLES, validateRunConfig } from '../src/home/lib/config-validate.mjs';
+import { editRunConfig } from '../src/home/lib/config-edit.mjs';
+import { fetchCatalogue, parseCatalogue } from './model-catalogue.mjs';
+import { describe, readProfiles } from './model-set.mjs';
+
+const failure = (exitCode, message) => ({ exitCode, output: `codex-bridge model: ${message}` });
+const refusal = (message) => Object.assign(new Error(message), { exitCode: 2 });
+
+export async function editModelSpeed(argv, options) {
+  const [role, speed, confirmation, ...extra] = argv;
+  if (!ROLES.includes(role)) {
+    return failure(2, `${role ? `unknown role "${role}"` : 'role is required'}. Allowed roles: ${ROLES.join(', ')}.`);
+  }
+  if (typeof speed !== 'string' || !speed || /\s/.test(speed)) {
+    return failure(2, 'speed requires a tier identifier: a non-empty single word with no whitespace, or unset.');
+  }
+  if (confirmation !== undefined && (speed === 'unset' || confirmation !== 'confirm')) {
+    return failure(2, `unexpected argument "${confirmation}".`);
+  }
+  if (extra.length) return failure(2, `unexpected argument "${extra[0]}".`);
+
+  try {
+    const configPath = path.resolve(options.configPath ?? CONFIG_PATH);
+    let catalogue;
+    let tier;
+    if (speed !== 'unset') {
+      if (!readProfiles(configPath)[role]?.model) {
+        return failure(2, `${role} has no configured model; run model set ${role} <model> first. Nothing written.`);
+      }
+      try {
+        catalogue = parseCatalogue(await (options.fetchCatalogue ?? fetchCatalogue)());
+      } catch (error) {
+        return failure(1, `live catalogue unavailable; refusing to set ${role} speed: ${error?.message ?? String(error)}`);
+      }
+    }
+
+    let change;
+    let catalogueModel;
+    const transform = (current) => {
+      // Same absent-key rule as model-set: a missing config still answers about the role.
+      if (current !== undefined) validateRunConfig(configPath, { models: current });
+      const profiles = { ...current };
+      if (speed !== 'unset') {
+        const modelId = profiles[role]?.model?.trim();
+        // D40/D41: reusing a tier decision after a role changes model would validate the wrong pair.
+        if (catalogueModel !== undefined && modelId !== catalogueModel) {
+          throw new Error('The profile changed while the catalogue was being read; nothing was written. Run the command again.');
+        }
+        if (!modelId) {
+          throw refusal(`${role} has no configured model; run model set ${role} <model> first. Nothing written.`);
+        }
+        const entry = catalogue.find(({ slug }) => slug === modelId);
+        if (!entry) {
+          throw refusal(`unknown model "${modelId}". Available models: ${catalogue.map(({ slug }) => slug).join(', ') || '(empty catalogue)'}. Nothing written.`);
+        }
+        if (!entry.serviceTiers.length) {
+          throw refusal(`model "${modelId}" has no accelerated tier. Nothing written.`);
+        }
+        tier = entry.serviceTiers.find(({ id }) => id === speed);
+        if (!tier) {
+          throw refusal(`speed "${speed}" is not supported by model "${modelId}". `
+            + `Accelerated tiers: ${entry.serviceTiers.map(({ id }) => id).join(', ')}. Nothing written.`);
+        }
+        catalogueModel = entry.slug;
+      }
+      const before = profiles[role];
+      const after = { ...before };
+      if (speed === 'unset') delete after.speed;
+      else after.speed = speed;
+      change = `${role}: ${describe(before)} -> ${describe(after)}`;
+      if (before || speed !== 'unset') profiles[role] = after;
+      return profiles;
+    };
+    if (speed !== 'unset' && confirmation !== 'confirm') {
+      transform(readProfiles(configPath));
+      return {
+        exitCode: 0,
+        output: `Preview — ${change}\nCatalogue description: "${tier.description}"\n`
+          + 'Credit multipliers: https://learn.chatgpt.com/docs/agent-configuration/speed\n'
+          + `Run a second call ending in confirm to apply: codex-bridge model speed ${role} ${speed} confirm\nNothing written.`,
+      };
+    }
+    await editRunConfig('models', transform, configPath);
+    return {
+      exitCode: 0,
+      output: `${change}\nConfig file: ${configPath}\n`
+        + 'Machine-wide: shared by every project on this machine, not per-project.',
+    };
+  } catch (error) {
+    if (error.exitCode === 2) return failure(2, error.message);
+    return failure(1, `cannot ${speed === 'unset' ? 'unset' : 'set'} speed: ${error?.message ?? String(error)}`);
+  }
+}