@bitkyc08/opencodex 2.75.0 → 2.76.0

package/src/cli/runtime-api.ts

@@ -200,6 +200,7 @@ export function takeOption(args: string[], flag: string): string | undefined {
   return value;
 }
 
+/** Consume one boolean option using the supported on/off synonyms; reject other values. */
 export function takeBooleanOption(args: string[], flag: string): boolean | undefined {
   const raw = takeOption(args, flag);
   if (raw === undefined) return undefined;
@@ -208,11 +209,13 @@ export function takeBooleanOption(args: string[], flag: string): boolean | undef
   throw new CliUsageError(`${flag} must be on or off`);
 }
 
+/** Parse a decimal safe integer, allowing separators only between digits. */
 export function takeIntegerOption(args: string[], flag: string, options: { min?: number } = {}): number | undefined {
   const raw = takeOption(args, flag);
   if (raw === undefined) return undefined;
-  const value = Number(raw.replace(/[_,]/g, ""));
-  if (!Number.isInteger(value) || value < (options.min ?? Number.MIN_SAFE_INTEGER)) {
+  const decimal = raw.trim();
+  const value = /^[+-]?\d+(?:[_,]\d+)*$/.test(decimal) ? Number(decimal.replace(/[_,]/g, "")) : NaN;
+  if (!Number.isSafeInteger(value) || value < (options.min ?? Number.MIN_SAFE_INTEGER)) {
     throw new CliUsageError(`${flag} must be an integer${options.min !== undefined ? ` >= ${options.min}` : ""}`);
   }
   return value;

package/src/cli/status-oauth.ts

@@ -72,6 +72,11 @@ export function formatOAuthHealthForStatus(
       parts.push(CODEX_HEALTH_MANAGEMENT_API_UNAVAILABLE_NOTE);
       break;
   }
+  const policy = report.mainAccountHardLock;
+  if (policy) {
+    const warning = policy.externalUsage ? "; possible usage outside opencodex — the lock may not prevent exhaustion" : "";
+    parts.push(`Codex main-account protection: ${policy.state} (5h ≥ ${policy.thresholds.short}%, weekly/monthly ≥ ${policy.thresholds.long}%)${warning}`);
+  }
   const oauthBlock = formatEntryBlock(report.entries);
   if (oauthBlock) parts.push(oauthBlock);
   return parts.join("\n");

package/src/cli/status.ts

@@ -1,3 +1,4 @@
+import type { CodexMainAccountPolicyHealth } from "../oauth/health";
 import { durableBunRuntime } from "../lib/bun-runtime";
 import { existsSync, readFileSync } from "node:fs";
 import { codexAutoStartEnabled, getConfigPath, readConfigDiagnostics } from "../config";
@@ -104,6 +105,7 @@ export type CliRemoteHubStatus = {
 };
 
 export type CliStatusJson = {
+  mainAccountHardLock?: CodexMainAccountPolicyHealth;
   schemaVersion: 1;
   /**
    * This machine's topology role, named rather than inferred (#4236).
@@ -676,7 +678,8 @@ export function missingCodexCatalogLines(missingCatalogPath: string | null): str
   ];
 }
 
-export async function collectStatus(): Promise<CliStatusView> {
+/** `mainAccountPolicy`: only `--json` asks; the human report reads the same accounts once via OAuth health. */
+export async function collectStatus(options: { mainAccountPolicy?: boolean } = {}): Promise<CliStatusView> {
   const configDiagnostics = readConfigDiagnostics();
   const config = configDiagnostics.config;
   const claudeDesktop = {
@@ -714,6 +717,9 @@ export async function collectStatus(): Promise<CliStatusView> {
   const live = await findLiveProxy({
     configFn: () => ({ port: config.port, hostname: config.hostname }),
   });
+  const mainAccountHardLock = options.mainAccountPolicy && live
+    ? (await (await import("../oauth/health")).fetchCodexHealthFromLiveProxy(undefined, async () => live)).mainAccountHardLock
+    : undefined;
   const pidFile = readPid();
   // Preserve an authoritative null from orphan/legacy liveness — do not restore pidFile.
   const pid = resolveStatusPid(live, pidFile);
@@ -865,6 +871,7 @@ export async function collectStatus(): Promise<CliStatusView> {
     proxyLabel,
     healthLabel: health.label,
     json: {
+      ...(mainAccountHardLock ? { mainAccountHardLock } : {}),
       schemaVersion: 1,
       runtimeRole: config.runtimeRole ?? "standalone",
       proxy: {

package/src/cli/stop-approval.ts

@@ -64,19 +64,41 @@ export function parseStopApproval(argv: string[]): StopApprovalParse {
 }
 
 export function matchesStopApproval(expected: StopApproval, now: ResolveJson): boolean {
-  return now.schema === "ocx-resolve/1" && now.liveness.status === "live"
-    && now.liveness.pid === expected.pid && now.liveness.port === expected.port
-    && now.port.effective === expected.port && (now.liveness.hostname ?? "") === expected.hostname
-    && now.liveness.role !== "client" && now.configHome === expected.configHome
-    && now.cliVersion === expected.cliVersion && now.ownership.kind !== "unknown"
-    && now.takeover.kind === "supported" && now.takeover.token === expected.compatibilityToken;
+  return stopApprovalMismatch(expected, now) === null;
 }
 
-export function approvalChanged(): StopOutcome {
+/**
+ * The single guard fact that no longer holds, or null when everything still matches.
+ * The guarded stop collapses every re-verification into one `approval-changed` outcome;
+ * without the specific check, a desktop log cannot tell a genuine ownership or token
+ * drift from a transient probe failure on an unchanged runtime.
+ */
+export function stopApprovalMismatch(expected: StopApproval, now: ResolveJson): string | null {
+  if (now.schema !== "ocx-resolve/1") return "the resolve contract changed";
+  if (now.liveness.status !== "live") return `the approved runtime is no longer live (${now.liveness.status})`;
+  if (now.liveness.pid !== expected.pid) {
+    return `the live PID is now ${now.liveness.pid ?? "unverified"} (approved ${expected.pid})`;
+  }
+  if (now.liveness.port !== expected.port) return `the live port is now ${now.liveness.port} (approved ${expected.port})`;
+  if (now.port.effective !== expected.port) return `the effective port is now ${now.port.effective} (approved ${expected.port})`;
+  if ((now.liveness.hostname ?? "") !== expected.hostname) return "the bind hostname changed";
+  if (now.liveness.role === "client") return "the runtime now routes as a client";
+  if (now.configHome !== expected.configHome) return "the config home changed";
+  if (now.cliVersion !== expected.cliVersion) return `the resolving CLI is now ${now.cliVersion} (approved ${expected.cliVersion})`;
+  if (now.ownership.kind === "unknown") return "the ownership claim could not be re-verified";
+  if (now.takeover.kind !== "supported") {
+    return `takeover compatibility is now blocked (${now.takeover.reason})`;
+  }
+  if (now.takeover.token !== expected.compatibilityToken) return "the compatibility fingerprint changed";
+  return null;
+}
+
+export function approvalChanged(detail?: string): StopOutcome {
   return { ok: false, summary: {
     schema: STOP_SUMMARY_SCHEMA, ok: false, outcome: "approval-changed", exitCode: 1,
     runtimeDown: false, service: "absent", proxy: "unknown", sharedTeardown: "skipped",
-    message: "The approved runtime or managing CLI changed; no stop was attempted.",
+    ...(detail ? { detail } : {}),
+    message: `The approved runtime or managing CLI changed${detail ? `: ${detail}` : ""}; no stop was attempted.`,
   } };
 }
 
@@ -104,10 +126,20 @@ export async function runApprovedStop(
     const now = await read();
     const target = tracked();
     const manager = managerTarget();
-    if (!now || !matchesStopApproval(expected, now) || !target
-      || target.pid !== expected.pid || target.port !== expected.port
-      || target.hostname !== expected.hostname || manager.kind === "unknown"
-      || (manager.kind === "bound" && manager.pid !== expected.pid)) return approvalChanged();
+    if (now === null) return approvalChanged("the runtime could not be re-resolved");
+    const mismatch = stopApprovalMismatch(expected, now);
+    if (mismatch !== null) return approvalChanged(mismatch);
+    if (target === null) return approvalChanged("the tracked runtime record could not be verified");
+    if (target.pid !== expected.pid || target.port !== expected.port
+      || target.hostname !== expected.hostname) {
+      return approvalChanged("the tracked runtime record changed");
+    }
+    if (manager.kind === "unknown") {
+      return approvalChanged(`the service manager could not be re-verified (${manager.reason})`);
+    }
+    if (manager.kind === "bound" && manager.pid !== expected.pid) {
+      return approvalChanged("a different manager owns the approved runtime");
+    }
     snapshot = { approval: expected, manager };
   } catch { return approvalChanged(); }
   return snapshot ? stop(snapshot) : approvalChanged();
@@ -149,13 +181,20 @@ export async function runGuardedManagerStep(
     managerState: () => Promise<"inactive" | "active" | "unknown">;
   },
 ): Promise<{ service: StopServiceOutcome; effect: "stopped" | "approval-changed" | "manager-still-active" | "failed";
-  proxy: "stopped" | "unknown"; handledByProxy: boolean }> {
+  proxy: "stopped" | "unknown"; handledByProxy: boolean; detail?: string }> {
   try {
-    if (!sameGuardedManager(snapshot.manager, io.revalidateManager())) {
-      return { service: "absent", effect: "approval-changed", proxy: "unknown", handledByProxy: false };
+    const current = io.revalidateManager();
+    if (!sameGuardedManager(snapshot.manager, current)) {
+      // An unprovable manager is not a proven change: name the observation failure,
+      // not a swap, or the stop log loses why the revalidation could not answer.
+      const detail = current.kind === "unknown"
+        ? `the service manager could not be re-verified (${current.reason})`
+        : "the service manager changed between approval and stop";
+      return { service: "absent", effect: "approval-changed", proxy: "unknown", handledByProxy: false, detail };
     }
   } catch {
-    return { service: "absent", effect: "approval-changed", proxy: "unknown", handledByProxy: false };
+    return { service: "absent", effect: "approval-changed", proxy: "unknown", handledByProxy: false,
+      detail: "the service manager could not be re-validated" };
   }
   const service = snapshot.manager.kind === "absent" ? "absent" : io.stopManager();
   if (snapshot.manager.kind === "bound"

package/src/cli/stop-report.ts

@@ -76,6 +76,11 @@ export interface StopSummaryJson {
   sharedTeardown: StopSharedTeardownOutcome;
   /** One stable human-readable line for a caller's UI. */
   message: string;
+  /**
+   * The single guard fact that failed on a `approval-changed` refusal, when the
+   * run can name one. Additive on `ocx-stop/1`; absent on every other outcome.
+   */
+  detail?: string;
 }
 
 /** What handleStop returns: the pre-existing boolean plus the structured twin. */

package/src/clients/lazycodex.ts

@@ -0,0 +1,48 @@
+/**
+ * Detection of Codex-based omo (LazyCodex), the variant that reads Codex role files and
+ * `codex.agents.<role>.model` in `~/.omo/omo.jsonc`.
+ *
+ * "omo" names three products. Pi-based omo (senpi) owns `~/.omo/agent` and is the omo file
+ * integration in `src/integrations/registry.ts`; OpenCode-based omo (oh-my-opencode) keeps its
+ * own config under OpenCode. Neither proves LazyCodex is installed, and `~/.omo` exists for all
+ * of them, so this reads only LazyCodex's footprint inside CODEX_HOME: the Codex plugin
+ * `omo@sisyphuslabs` enabled in config.toml (the key LazyCodex's own doctor checks) and an
+ * installed copy of it carrying the `lazycodex-install.json` receipt its installer writes.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const LAZYCODEX_PLUGIN_ID = "omo@sisyphuslabs";
+
+export interface LazyCodexDetection {
+  readonly detected: boolean;
+  readonly pluginEnabled: boolean;
+  readonly pluginInstalled: boolean;
+}
+
+function pluginEnabled(codexHome: string): boolean {
+  let parsed: unknown;
+  try {
+    parsed = Bun.TOML.parse(readFileSync(join(codexHome, "config.toml"), "utf8"));
+  } catch {
+    return false;
+  }
+  const plugins = (parsed as { plugins?: Record<string, { enabled?: unknown } | undefined> } | null)?.plugins;
+  return plugins?.[LAZYCODEX_PLUGIN_ID]?.enabled === true;
+}
+
+function pluginInstalled(codexHome: string): boolean {
+  const root = join(codexHome, "plugins", "cache", "sisyphuslabs", "omo");
+  try {
+    return readdirSync(root, { withFileTypes: true })
+      .some(entry => entry.isDirectory() && existsSync(join(root, entry.name, "lazycodex-install.json")));
+  } catch {
+    return false;
+  }
+}
+
+export function detectLazyCodex(codexHome: string): LazyCodexDetection {
+  const enabled = pluginEnabled(codexHome);
+  const installed = pluginInstalled(codexHome);
+  return { detected: enabled && installed, pluginEnabled: enabled, pluginInstalled: installed };
+}

package/src/clients/omo-role-models.ts

@@ -0,0 +1,111 @@
+/**
+ * omo (Codex / LazyCodex)'s per-role model setting, `codex.agents.<role>.model` in `~/.omo/omo.jsonc`.
+ *
+ * LazyCodex 5.1.1 and later reads it, and callers reach this only after `detectLazyCodex`
+ * says LazyCodex is installed. The file is omo's, so this writes only on an explicit
+ * dashboard or CLI pick, never creates the file, and refuses a file with comments: the write
+ * re-serializes JSON, and a comment the user wrote would be lost without a word.
+ */
+import { lstatSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { atomicWriteFileNoFollowUnclaimed } from "../config/atomic-write";
+import { assertIntegrationWriteOwnership } from "../integrations/config-io";
+import { hasJsoncComments, parseJsonc } from "../lib/jsonc";
+
+export type OmoRoleModelsState =
+  | { readonly state: "absent" }
+  | { readonly state: "comments" }
+  | { readonly state: "invalid" }
+  | { readonly state: "unreadable" }
+  | { readonly state: "present"; readonly models: Readonly<Record<string, string>> };
+
+export type OmoRoleModelWriteStatus = "written" | "unchanged" | "absent" | "skipped_comments" | "invalid";
+
+/** omo resolves its home from HOME, then USERPROFILE, then the OS home; this follows it. */
+export function omoJsoncPath(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
+  const base = env.HOME?.trim() || env.USERPROFILE?.trim() || home;
+  return join(base, ".omo", "omo.jsonc");
+}
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+type Loaded =
+  | { kind: "absent" | "comments" | "invalid" }
+  | { kind: "document"; text: string; doc: JsonObject };
+
+function load(path: string): Loaded {
+  let text: string;
+  try {
+    if (!lstatSync(path).isFile()) return { kind: "invalid" };
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { kind: "absent" };
+    throw error;
+  }
+  if (hasJsoncComments(text)) return { kind: "comments" };
+  try {
+    const doc = parseJsonc(text.replace(/^\ufeff/, ""));
+    return isObject(doc) ? { kind: "document", text, doc } : { kind: "invalid" };
+  } catch {
+    return { kind: "invalid" };
+  }
+}
+
+function agentsOf(doc: JsonObject): JsonObject | null | undefined {
+  const codex = doc.codex;
+  if (codex === undefined) return undefined;
+  if (!isObject(codex)) return null;
+  const agents = codex.agents;
+  if (agents === undefined) return undefined;
+  return isObject(agents) ? agents : null;
+}
+
+export function readOmoRoleModels(path: string = omoJsoncPath()): OmoRoleModelsState {
+  let loaded: Loaded;
+  try {
+    loaded = load(path);
+  } catch {
+    return { state: "unreadable" };
+  }
+  if (loaded.kind !== "document") return { state: loaded.kind };
+  const agents = agentsOf(loaded.doc);
+  if (agents === null) return { state: "invalid" };
+  const models: Record<string, string> = {};
+  for (const [role, entry] of Object.entries(agents ?? {})) {
+    if (isObject(entry) && typeof entry.model === "string") models[role] = entry.model;
+  }
+  return { state: "present", models };
+}
+
+function serialize(text: string, doc: JsonObject): string {
+  const indent = /\n([ \t]+)"/.exec(text)?.[1] ?? "  ";
+  let out = JSON.stringify(doc, null, indent);
+  if (/\r?\n$/.test(text)) out += "\n";
+  if (text.includes("\r\n")) out = out.replace(/\n/g, "\r\n");
+  return text.startsWith("\ufeff") ? `\ufeff${out}` : out;
+}
+
+export function writeOmoRoleModel(role: string, model: string, path: string = omoJsoncPath()): OmoRoleModelWriteStatus {
+  const loaded = load(path);
+  if (loaded.kind !== "document") return loaded.kind === "comments" ? "skipped_comments" : loaded.kind;
+  const { doc, text } = loaded;
+  // Only an absent key is created; an explicit null is a value the reader calls invalid.
+  const codex = doc.codex === undefined ? {} : doc.codex;
+  if (!isObject(codex)) return "invalid";
+  const agents = codex.agents === undefined ? {} : codex.agents;
+  if (!isObject(agents)) return "invalid";
+  const entry = agents[role] === undefined ? {} : agents[role];
+  if (!isObject(entry)) return "invalid";
+  if (entry.model === model) return "unchanged";
+  agents[role] = { ...entry, model };
+  codex.agents = agents;
+  doc.codex = codex;
+  assertIntegrationWriteOwnership(path);
+  atomicWriteFileNoFollowUnclaimed(path, serialize(text, doc));
+  return "written";
+}

package/src/codex/account-credit-use.ts

@@ -0,0 +1,99 @@
+import type { OcxConfig } from "../types";
+import { deleteConfigTopLevelKey } from "../config/rebase-provenance";
+import { isThirtyDayOnlyCodexPlan } from "./plan";
+import {
+  CODEX_EXHAUSTED_USAGE_PERCENT,
+  isTerminalShortWindow,
+  resetAtToMs,
+  type StoredAccountQuota,
+} from "./quota-types";
+
+/**
+ * Whether an account may keep serving once one of its usage windows is full (#6334).
+ *
+ * Upstream does not refuse an account that holds ChatGPT credits at 100%: it serves the request
+ * and draws the balance. Selection only takes an account off on quota after a refusal, so an
+ * account with credits was never moved off. Spending is opt-in: only the ids in
+ * `creditCodexAccountIds` may keep serving from credits, and every other account leaves rotation
+ * at 100% and comes back after its reset. Pool accounts and the `__main__` login both carry the
+ * switch; the main login is also checked where the main-account hard lock is.
+ */
+export function codexAccountUsesCreditsAfterLimit(
+  config: Pick<OcxConfig, "creditCodexAccountIds">,
+  accountId: string,
+): boolean {
+  return config.creditCodexAccountIds?.includes(accountId) ?? false;
+}
+
+/** Persist the switch for one account. Only the accounts allowed to spend credits are stored. */
+export function setCodexAccountCreditsAfterLimit(config: OcxConfig, accountId: string, enabled: boolean): void {
+  const ids = new Set(config.creditCodexAccountIds ?? []);
+  if (enabled) ids.add(accountId);
+  else ids.delete(accountId);
+  writeCreditAccountIds(config, ids);
+}
+
+/**
+ * The dashboard's global switch. On allows every account the caller passes, which is every
+ * current account; off clears the list, so a later account still starts with spending off.
+ */
+export function setAllCodexAccountsCreditsAfterLimit(config: OcxConfig, accountIds: readonly string[], enabled: boolean): void {
+  writeCreditAccountIds(config, new Set(enabled ? accountIds : []));
+}
+
+function writeCreditAccountIds(config: OcxConfig, ids: ReadonlySet<string>): void {
+  if (ids.size > 0) config.creditCodexAccountIds = [...ids];
+  else deleteConfigTopLevelKey(config, "creditCodexAccountIds");
+}
+
+export function forgetCodexAccountCreditUse(config: OcxConfig, accountId: string): void {
+  setCodexAccountCreditsAfterLimit(config, accountId, false);
+}
+
+/**
+ * A usage window that is full right now.
+ *
+ * Stricter than the selection score about time, on purpose. The score keeps a 100% reading until
+ * a new observation replaces it, which is safe there because an account at 100% still receives
+ * traffic and that traffic brings the next observation. An account held by this switch receives
+ * none, so the reading itself has to say when it ends: a long window counts only while its reset
+ * is still ahead, and one without a reset is not trusted. The burst window uses the rule routing
+ * and the dashboard already share.
+ */
+export function isCodexUsageLimitReached(quota: StoredAccountQuota | null, plan: unknown, now: number): boolean {
+  return codexUsageLimitResetAt(quota, plan, now) !== undefined;
+}
+
+/**
+ * When the full window ends, in milliseconds, or undefined when no window is full. With several
+ * full windows the latest reset is the earliest moment the account is usable again.
+ */
+export function codexUsageLimitResetAt(quota: StoredAccountQuota | null, plan: unknown, now: number): number | undefined {
+  if (!quota) return undefined;
+  const full: number[] = [];
+  if (isTerminalShortWindow(quota, now)) {
+    // A reset-less burst reading counts while it is fresh, so there is no instant to report.
+    full.push(typeof quota.shortResetAt === "number" && quota.shortResetAt > 0 ? resetAtToMs(quota.shortResetAt) : now);
+  }
+  const longWindows: Array<[number | undefined, number | undefined]> = isThirtyDayOnlyCodexPlan(plan)
+    ? [[quota.monthlyPercent, quota.monthlyResetAt]]
+    : [[quota.weeklyPercent, quota.weeklyResetAt], [quota.monthlyPercent, quota.monthlyResetAt]];
+  for (const [percent, resetAt] of longWindows) {
+    if (typeof percent !== "number" || percent < CODEX_EXHAUSTED_USAGE_PERCENT) continue;
+    if (typeof resetAt !== "number" || !Number.isFinite(resetAt) || resetAt <= 0) continue;
+    const resetMs = resetAtToMs(resetAt);
+    if (resetMs > now) full.push(resetMs);
+  }
+  return full.length > 0 ? Math.max(...full) : undefined;
+}
+
+/** Whether automatic selection must skip this account so that it keeps its credits. */
+export function isCodexAccountHeldForCredits(
+  config: Pick<OcxConfig, "creditCodexAccountIds">,
+  accountId: string,
+  quota: StoredAccountQuota | null,
+  plan: unknown,
+  now: number,
+): boolean {
+  return !codexAccountUsesCreditsAfterLimit(config, accountId) && isCodexUsageLimitReached(quota, plan, now);
+}

package/src/codex/account-lifecycle.ts

@@ -18,6 +18,7 @@ import { invalidateCodexWebSocketsForAccount } from "./websocket-registry";
 import { clearMainAccountCredentialPresence, clearMainAccountInfoCache, observeMainQuotaCredential, observeMainQuotaIdentity } from "./main-account-cache";
 import { extractAccountIdClaims } from "../oauth/chatgpt";
 import { forgetCodexAccountPause } from "./account-pause";
+import { forgetCodexAccountCreditUse } from "./account-credit-use";
 import { clearCodexAccountPin, forgetCodexAccountPriority } from "./account-priority";
 import { forgetCodexQuotaAutoRefreshAccount } from "./quota-auto-refresh-state";
 import { forgetCodexAccountAutoSwitchThreshold } from "./account-auto-switch";
@@ -179,6 +180,7 @@ export function deleteCodexAccount(runtimeConfig: OcxConfig, accountId: string):
     runtimeConfig.codexAccounts = (runtimeConfig.codexAccounts ?? [])
       .filter(account => account.isMain || account.id !== accountId);
     forgetCodexAccountPause(runtimeConfig, accountId);
+    forgetCodexAccountCreditUse(runtimeConfig, accountId);
     forgetCodexAccountPriority(runtimeConfig, accountId);
     forgetCodexAccountAutoSwitchThreshold(runtimeConfig, accountId);
     if (runtimeConfig.codexQuotaAutoRefresh?.[accountId]) {

package/src/codex/agent-role-models.ts

@@ -0,0 +1,171 @@
+/**
+ * The dashboard's write of one Codex agent role's model, and optionally its reasoning effort.
+ *
+ * Codex overrides the spawn-time model with the root `model` pin in
+ * `$CODEX_HOME/agents/<role>.toml`, so that pin is what decides a child's model. This module
+ * edits exactly that value, plus the root `model_reasoning_effort` when a caller passes one, and
+ * nothing else: every other byte of the file, including the instructions multiline string that
+ * usually mentions `model =` in prose, is left as it was.
+ * It runs only on an explicit user action; no sync or startup path calls it.
+ */
+import { lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileNoFollowUnclaimed } from "../config/atomic-write";
+import { assertIntegrationWriteOwnership } from "../integrations/config-io";
+import { encodeBasicString, findInvalidCharacter } from "./prompt-layers/encoding";
+import { dominantEol } from "./prompt-layers/toml-edit";
+import { isDeclaredReasoningEffort } from "../reasoning-effort";
+import {
+  listCodexAgentRoles,
+  locateTomlModelKey,
+  locateTomlReasoningEffortKey,
+  type TomlModelKeyLocation,
+} from "./subagent-model-fallback";
+
+export type AgentRoleModelErrorCode =
+  | "unknown_role"
+  | "invalid_model"
+  | "invalid_effort"
+  | "unsupported_model_value"
+  | "unsafe_target"
+  | "invalid_role_file";
+
+export class AgentRoleModelError extends Error {
+  constructor(readonly code: AgentRoleModelErrorCode, message: string) {
+    super(message);
+  }
+}
+
+export interface CodexAgentRoleModel {
+  readonly role: string;
+  readonly model: string | null;
+}
+
+export function validateAgentRoleModel(model: unknown): string {
+  if (typeof model !== "string") throw new AgentRoleModelError("invalid_model", "model must be a string");
+  const trimmed = model.trim();
+  if (trimmed === "") throw new AgentRoleModelError("invalid_model", "model must not be empty");
+  if (trimmed.includes("\n") || findInvalidCharacter(trimmed) !== null) {
+    throw new AgentRoleModelError("invalid_model", "model must not contain control characters");
+  }
+  return trimmed;
+}
+
+export function validateAgentRoleEffort(effort: unknown): string {
+  if (typeof effort !== "string" || !isDeclaredReasoningEffort(effort)) {
+    throw new AgentRoleModelError("invalid_effort", "effort must be a reasoning effort level such as low, medium or high");
+  }
+  return effort;
+}
+
+/**
+ * Set a root string key. An existing value is replaced inside its quotes and keeps its
+ * quote style when the new value allows it; a missing key is inserted after the leading
+ * comment block with the file's own line ending.
+ */
+function setTomlRootString(content: string, location: TomlModelKeyLocation | null, key: string, value: string): string {
+  if (location?.inRootTable) {
+    if (!location.span) {
+      throw new AgentRoleModelError("unsupported_model_value", `the existing ${key} value is not a one-line string`);
+    }
+    const lines = content.split("\n");
+    const line = lines[location.line]!;
+    const literal = line[location.span.start] === "'" && !value.includes("'")
+      ? `'${value}'`
+      : encodeBasicString(value);
+    lines[location.line] = line.slice(0, location.span.start) + literal + line.slice(location.span.end);
+    return lines.join("\n");
+  }
+  const eol = dominantEol(content);
+  const bom = content.startsWith("\ufeff") ? 1 : 0;
+  const lines = content.slice(bom).split("\n");
+  let offset = bom;
+  for (const line of lines) {
+    if (!/^\s*#/.test(line)) break;
+    offset += line.length + 1;
+  }
+  const assignment = `${key} = ${encodeBasicString(value)}`;
+  if (offset > content.length) return `${content}${eol}${assignment}${eol}`;
+  return `${content.slice(0, offset)}${assignment}${eol}${content.slice(offset)}`;
+}
+
+export function setTomlRootModel(content: string, model: string): string {
+  return setTomlRootString(content, locateTomlModelKey(content), "model", model);
+}
+
+export function setTomlRootReasoningEffort(content: string, effort: string): string {
+  return setTomlRootString(content, locateTomlReasoningEffortKey(content), "model_reasoning_effort", effort);
+}
+
+export function readCodexAgentRoleEffort(role: string, codexHome: string): string | null {
+  try {
+    const location = locateTomlReasoningEffortKey(readFileSync(roleFile(role, codexHome), "utf8"));
+    return location?.inRootTable ? location.value : null;
+  } catch {
+    return null;
+  }
+}
+
+function roleFile(role: string, codexHome: string): string {
+  return join(codexHome, "agents", `${role}.toml`);
+}
+
+function requireKnownRole(role: string, codexHome: string): void {
+  // Membership in the directory listing is the whole path check: a name with a separator or
+  // `..` can never equal a listed file stem.
+  if (!listCodexAgentRoles(codexHome).includes(role)) {
+    throw new AgentRoleModelError("unknown_role", `no Codex agent role named ${JSON.stringify(role)}`);
+  }
+}
+
+export function listCodexAgentRoleModels(codexHome: string): CodexAgentRoleModel[] {
+  return listCodexAgentRoles(codexHome).sort().map(role => {
+    let model: string | null = null;
+    try {
+      const location = locateTomlModelKey(readFileSync(roleFile(role, codexHome), "utf8"));
+      model = location?.inRootTable ? location.value : null;
+    } catch { /* an unreadable role reports no pin */ }
+  return { role, model };
+  });
+}
+
+/**
+ * Codex refuses a role file that is not valid TOML. Editing one anyway could turn a role that
+ * Codex rejects into one it loads, so both the original and the edited document must parse.
+ */
+function assertValidRoleToml(role: string, text: string, stage: "before" | "after"): void {
+  try {
+    Bun.TOML.parse(text);
+  } catch {
+    throw new AgentRoleModelError(
+      "invalid_role_file",
+      stage === "before"
+        ? `${role}.toml is not valid TOML; fix it before setting a model`
+        : `setting the model would leave ${role}.toml invalid; the file was not changed`,
+    );
+  }
+}
+
+export function writeCodexAgentRoleModel(
+  role: string,
+  model: string,
+  codexHome: string,
+  effort?: string,
+): { status: "written" | "unchanged" } {
+  requireKnownRole(role, codexHome);
+  const path = roleFile(role, codexHome);
+  if (!lstatSync(path).isFile()) {
+    throw new AgentRoleModelError("unsafe_target", `${role}.toml is not a regular file; edit it where it points`);
+  }
+  const before = readFileSync(path, "utf8");
+  assertValidRoleToml(role, before, "before");
+  const withModel = setTomlRootModel(before, validateAgentRoleModel(model));
+  const after = effort === undefined
+    ? withModel
+    : setTomlRootReasoningEffort(withModel, validateAgentRoleEffort(effort));
+  if (after === before) return { status: "unchanged" };
+  assertValidRoleToml(role, after, "after");
+  assertIntegrationWriteOwnership(path);
+  atomicWriteFileNoFollowUnclaimed(path, after);
+  return { status: "written" };
+}