@bitkyc08/opencodex 2.75.0 → 2.76.0

package/src/codex/native-profile-processes.ts

@@ -81,14 +81,31 @@ export interface ListCodexClientProcessesOptions {
  */
 export function isCodexClientProcess(command: string, args: string): boolean {
   const comm = basename(command).toLowerCase();
-  const [rawArgv0 = "", rawEntrypoint = ""] = args.trim().split(/\s+/, 2);
-  const argv0 = basename(rawArgv0).toLowerCase();
-  const entrypoint = basename(rawEntrypoint).toLowerCase();
-  const isDirectCodex = DIRECT_CODEX_BASENAMES.has(comm)
-    || DIRECT_CODEX_BASENAMES.has(argv0);
-  const isInterpreterWrappedCodex = CODEX_INTERPRETER_BASENAMES.has(argv0)
-    && CODEX_ENTRYPOINT_BASENAMES.has(entrypoint);
-  return isDirectCodex || isInterpreterWrappedCodex;
+  if (DIRECT_CODEX_BASENAMES.has(comm)) return true;
+  // A full executable path is stronger evidence than ps's unquoted args.
+  // Splitting ".../Codex Framework.framework/.../browser_crashpad_handler"
+  // at its first space would otherwise manufacture an argv0 named Codex.
+  if (command.includes("/") && !CODEX_INTERPRETER_BASENAMES.has(comm)) return false;
+  const trimmedArgs = args.trim();
+  const hasExecutablePrefix = command && trimmedArgs.startsWith(command)
+    && /^(?:\s|$)/.test(trimmedArgs.slice(command.length));
+  const remainingArgs = hasExecutablePrefix ? trimmedArgs.slice(command.length).trim() : trimmedArgs;
+  const rawTokens = remainingArgs.split(/\s+/, 2);
+  // Even with only a comm basename, this initial token pair is the split
+  // Codex.app framework path, not a CLI executable plus an argument. Only
+  // inspect the executable or immediate script, never a later argument.
+  if (rawTokens[0]?.endsWith("/Codex.app/Contents/Frameworks/Codex")
+    && rawTokens[1]?.startsWith("Framework.framework/")) return false;
+  const quotedTokens = tokenizeCommandLine(remainingArgs);
+  // ps/procfs also leave literal apostrophes unescaped. Preserve a matching
+  // immediate raw entrypoint before interpreting shell-like quotes.
+  return [rawTokens, quotedTokens].some(tokens => {
+    const [rawArgv0 = "", rawEntrypoint = ""] = hasExecutablePrefix ? [command, ...tokens] : tokens;
+    const argv0 = basename(rawArgv0).toLowerCase();
+    const entrypoint = basename(rawEntrypoint).toLowerCase();
+    return DIRECT_CODEX_BASENAMES.has(argv0)
+      || (CODEX_INTERPRETER_BASENAMES.has(argv0) && CODEX_ENTRYPOINT_BASENAMES.has(entrypoint));
+  });
 }
 
 function parseUnixPsLine(line: string): { pid: number; command: string; args: string } | null {
@@ -147,9 +164,7 @@ export function listCodexClientProcesses({
 }
 
 function snapshotIsCodexClient(snapshot: ProcessSnapshot): boolean {
-  if (isCodexClientProcess(snapshot.executable ?? "", snapshot.commandLine)) return true;
-  const argv0 = tokenizeCommandLine(snapshot.commandLine)[0] ?? "";
-  return argv0 !== "" && isCodexClientProcess(argv0, snapshot.commandLine);
+  return isCodexClientProcess(snapshot.executable ?? "", snapshot.commandLine);
 }
 
 /** Async, shell-free child execution with runtime-enforced timeout and output bounds. */
@@ -192,15 +207,37 @@ async function windowsProcessCount(run: NativeProcessExecutor): Promise<number>
   return count;
 }
 
-async function unixProcessCount(run: NativeProcessExecutor, pid: number): Promise<number> {
-  const output = await run("ps", ["-eo", "pid=,comm=,args="], {
+async function unixProcessCount(run: NativeProcessExecutor, pid: number, platform: NodeJS.Platform): Promise<number> {
+  const options: NativeProcessExecOptions = {
     encoding: "utf8",
     timeout: 5_000,
     maxBuffer: PROCESS_LIST_MAX_BUFFER,
     shell: false,
     killSignal: "SIGKILL",
-  });
-  return unixCodexClientsFromPs(output, pid).length;
+  };
+  if (platform !== "darwin") {
+    const output = await run("ps", ["-eo", "pid=,comm=,args="], options);
+    return unixCodexClientsFromPs(output, pid).length;
+  }
+  // macOS comm is a full path and may contain spaces. Read the two fields
+  // separately, as the routing-adoption snapshot collector does, then join by PID.
+  const commands = new Map<number, string>();
+  const commOutput = await run("ps", ["-eo", "pid=,comm="], options);
+  for (const line of commOutput.split("\n")) {
+    const match = /^\s*(\d+)\s+(.+)$/.exec(line);
+    if (match) commands.set(Number(match[1]), match[2]!.trim());
+  }
+  const argsOutput = await run("ps", ["-eo", "pid=,args="], options);
+  let count = 0;
+  for (const line of argsOutput.split("\n")) {
+    const match = /^\s*(\d+)\s+(.+)$/.exec(line);
+    if (!match) continue;
+    const candidatePid = Number(match[1]);
+    const command = commands.get(candidatePid);
+    if (Number.isSafeInteger(candidatePid) && candidatePid !== pid && command
+      && isCodexClientProcess(command, match[2]!)) count++;
+  }
+  return count;
 }
 
 /** Best-effort, read-only process probe. It never terminates a user process. */
@@ -212,7 +249,7 @@ export async function probeNativeCodexProcesses({
   try {
     const count = await (platform === "win32"
       ? windowsProcessCount(run)
-      : unixProcessCount(run, pid));
+      : unixProcessCount(run, pid, platform));
     return count > 0 ? { status: "busy", count } : { status: "clear", count: 0 };
   } catch {
     return { status: "unknown", count: 0 };

package/src/codex/prompt-layers/toml-edit.ts

@@ -3,7 +3,7 @@ import { encodeBasicString } from "./encoding";
 import { TABLE_HEADER, ANY_DEV_INSTRUCTIONS, DEV_INSTRUCTIONS_KEY } from "./toml-read";
 
 /** Line editing, not re-serialization: the user's comments and layout survive. */
-function dominantEol(content: string): "\r\n" | "\n" {
+export function dominantEol(content: string): "\r\n" | "\n" {
   const crlf = (content.match(/\r\n/g) ?? []).length;
   if (crlf === 0) return "\n";
   const bareLf = (content.match(/\n/g) ?? []).length - crlf;

package/src/codex/quota-types.ts

@@ -1,12 +1,8 @@
 /** Quota wire/storage shapes. This leaf must not import credential or config owners. */
-/**
- * Observed usage at which new identity-matched main-account requests are refused (#5694).
- *
- * The policy is on by default, so this constant is what every installation without an explicit
- * `codexMainAccountHardLock: false` admits against. 98 leaves one point of headroom under the
- * exhausted reading Codex Desktop already treats as its own disabled send button.
- */
+/** Long-window default; explicit main-account hard-lock thresholds may override it. */
 export const MAIN_ACCOUNT_HARD_LOCK_PERCENT = 98;
+export const MAIN_ACCOUNT_HARD_LOCK_SHORT_PERCENT = 90;
+export const MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT = 80;
 
 /**
  * How recently a 100% burst reading must have been observed to exclude an account when it

package/src/codex/quota.ts

@@ -1,3 +1,4 @@
+import { forgetMainAccountUsage, observeMainAccountUsage, type FreshWindow } from "./main-account-external-usage";
 import { closeSync, constants as fsConstants, existsSync, fstatSync, openSync, readSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile, getConfigDir } from "../config";
@@ -10,7 +11,7 @@ import { getObservedMainQuotaIdentityKey, isMainQuotaWriterLive, type MainQuotaW
 
 import { CodexQuotaHistory, QUOTA_HISTORY_LIMITS, type QuotaHistoryWindow } from "./quota-history";
 import { isPoolQuotaWriterLive, poolQuotaHistoryIdentity } from "./account-store";
-import { CODEX_EXHAUSTED_USAGE_PERCENT, MAIN_ACCOUNT_HARD_LOCK_PERCENT, resetAtToMs } from "./quota-types";
+import { CODEX_EXHAUSTED_USAGE_PERCENT, MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT, resetAtToMs } from "./quota-types";
 import type { PoolQuotaWriter, StoredAccountQuota, WhamUsageResponse, WhamUsageWindow } from "./quota-types";
 
 export type { StoredAccountQuota, WhamUsageResponse } from "./quota-types";
@@ -260,7 +261,7 @@ function assignCarriedShort(
   const existingShortPercent = existing.shortPercent;
   const preserveBlockingEvidence = policyEvidence
     && finitePercent(existingShortPercent)
-    && existingShortPercent >= MAIN_ACCOUNT_HARD_LOCK_PERCENT
+    && existingShortPercent >= MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT
     && existingShortPercent <= 100;
   if (!preserveBlockingEvidence && shortResetHasElapsed(existing.shortResetAt, now)) return;
   if (existing.shortPercent !== undefined) next.shortPercent = existing.shortPercent;
@@ -315,6 +316,19 @@ export function setAccountQuotaFromParsed(
   const next = mergeAccountQuota(quota, legacyExisting, updatedAt);
   accountQuota.set(accountId, next);
   if (isMain) {
+    if (mainWriter && policyQuota && snapshotHasUsage(policyQuota)) {
+      const windows: FreshWindow[] = [];
+      const add = (kind: FreshWindow["kind"], percent: number | undefined, reset: number | undefined) => {
+        if (finitePercent(percent) && percent >= 0 && percent <= 100
+          && typeof reset === "number" && Number.isFinite(reset) && reset > 0) {
+          windows.push({ kind, percent, resetAtMs: resetAtToMs(reset) });
+        }
+      };
+      add("short", policyQuota.shortPercent, policyQuota.shortResetAt);
+      if (policyQuota.monthlyIsPrimaryWindow === true) add("long", policyQuota.monthlyPercent, policyQuota.monthlyResetAt);
+      else add("long", policyQuota.weeklyPercent, policyQuota.weeklyResetAt);
+      observeMainAccountUsage(mainWriter.identityKey, windows, updatedAt);
+    }
     const policyExisting = mainWriter && mainPolicyQuota?.identityKey === mainWriter.identityKey
       ? mainPolicyQuota.quota
       : undefined;
@@ -371,7 +385,7 @@ function mergeAccountQuota(
     && quota.weeklyPercent === undefined
     && quota.monthlyIsPrimaryWindow !== true
     && finitePercent(existingWeeklyPercent)
-    && existingWeeklyPercent >= MAIN_ACCOUNT_HARD_LOCK_PERCENT
+    && existingWeeklyPercent >= MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT
     && existingWeeklyPercent <= 100;
   if (snapshotHasWeekly(quota) && !preserveKnownWeekly) {
     if (quota.weeklyPercent !== undefined) next.weeklyPercent = quota.weeklyPercent;
@@ -404,7 +418,7 @@ function mergeAccountQuota(
   const preserveKnownShort = policyEvidence
     && quota.shortPercent === undefined
     && finitePercent(existingShortPercent)
-    && existingShortPercent >= MAIN_ACCOUNT_HARD_LOCK_PERCENT
+    && existingShortPercent >= MAIN_ACCOUNT_HARD_LOCK_MIN_PERCENT
     && existingShortPercent <= 100;
   if (snapshotHasShort(quota) && !preserveKnownShort) {
     if (quota.shortPercent !== undefined) {
@@ -778,6 +792,7 @@ function forgetCodexQuotaBaseline(accountId?: string): void {
 }
 
 export function clearAccountQuota(accountId?: string): void {
+  if (!accountId || accountId === MAIN_CODEX_ACCOUNT_ID) forgetMainAccountUsage();
   if (accountId) hydrateAccountQuotasFromDisk();
   quotaHistory.clear(accountId);
   if (accountId) {

package/src/codex/role-auto-assign.ts

@@ -0,0 +1,159 @@
+/**
+ * Turns a role's sized tier and effort into a concrete model and reasoning level. Deterministic:
+ * the sizing model never names a model, and nothing here asks one.
+ *
+ * Tier of a candidate model, first rule that applies:
+ * 1. codexRoleTiers in the opencodex config lists it under fast, standard or frontier.
+ * 2. It has a known price. Priced candidates are ranked by input plus output USD per 1M tokens.
+ *    Three or more split evenly across the three tiers by rank, cheapest in fast. Fewer than three
+ *    cannot fill every tier, so the ranking is anchored at the top: the dearest is frontier,
+ *    because it is the strongest model on offer, and each cheaper one sits one tier lower. One
+ *    priced model is frontier; two are standard and frontier. The tier left empty is fast, so a
+ *    fast role steps up to the cheapest model and a standard role keeps it instead of jumping to
+ *    the dearest, which keeps every role on the cheapest sufficient model on offer.
+ * 3. Otherwise it is unclassified and never proposed.
+ *
+ * A role gets the cheapest sufficient model: the lowest tier at or above what it was sized for,
+ * then the lowest price, then the picker's own order.
+ *
+ * Effort binds to positions on the chosen model's ladder: glance is the floor, measured is the
+ * model's default or the middle rung, exhaustive is the ceiling, and thorough is the rung above
+ * measured when that rung is not the ceiling. When no such interior rung exists, thorough
+ * collapses to the nearer of measured and the ceiling; the two are equally near, and the one
+ * above wins because thorough asks for more than the everyday setting. Nothing resolves outside
+ * the ladder.
+ */
+import { SIZING_TIERS, type RoleSizingOutcome, type SizingEffort, type SizingTier } from "./role-sizing";
+import { CODEX_REASONING_LEVELS } from "../reasoning-effort";
+
+export type RoleTierMapping = Partial<Record<SizingTier, readonly string[]>>;
+
+export interface RoleModelCandidate {
+  readonly model: string;
+  /** Input plus output USD per 1M tokens, or null when no price is known. */
+  readonly unitPrice: number | null;
+  readonly efforts: readonly string[];
+  readonly defaultEffort?: string;
+}
+
+export interface ClassifiedCandidate extends RoleModelCandidate {
+  readonly tier: SizingTier | null;
+  readonly tierSource: "mapping" | "price" | null;
+}
+
+const LADDER_ORDER = ["none", "minimal", ...CODEX_REASONING_LEVELS.map(level => level.effort)];
+
+export function effortLadder(efforts: readonly string[]): string[] {
+  return [...new Set(efforts)]
+    .filter(effort => LADDER_ORDER.includes(effort))
+    .sort((a, b) => LADDER_ORDER.indexOf(a) - LADDER_ORDER.indexOf(b));
+}
+
+export function mapEffortToLevel(intent: SizingEffort, efforts: readonly string[], defaultEffort?: string): string | null {
+  const ladder = effortLadder(efforts);
+  if (ladder.length === 0) return null;
+  const top = ladder.length - 1;
+  const measured = defaultEffort !== undefined && ladder.includes(defaultEffort)
+    ? ladder.indexOf(defaultEffort)
+    : Math.floor(top / 2);
+  switch (intent) {
+    case "glance": return ladder[0]!;
+    case "measured": return ladder[measured]!;
+    case "thorough": return ladder[Math.min(measured + 1, top)]!;
+    case "exhaustive": return ladder[top]!;
+  }
+}
+
+export function classifyRoleModelCandidates(
+  candidates: readonly RoleModelCandidate[],
+  mapping: RoleTierMapping = {},
+): ClassifiedCandidate[] {
+  const mapped = new Map<string, SizingTier>();
+  for (const tier of SIZING_TIERS) {
+    for (const model of mapping[tier] ?? []) if (!mapped.has(model)) mapped.set(model, tier);
+  }
+  const priced = candidates
+    .map((candidate, order) => ({ candidate, order }))
+    .filter(({ candidate }) => !mapped.has(candidate.model) && candidate.unitPrice !== null)
+    .sort((a, b) => a.candidate.unitPrice! - b.candidate.unitPrice! || a.order - b.order);
+  const byPrice = new Map<string, SizingTier>();
+  priced.forEach(({ candidate }, rank) => {
+    const top = SIZING_TIERS.length - 1;
+    const index = priced.length < SIZING_TIERS.length
+      ? top - (priced.length - 1 - rank)
+      : Math.round((rank * top) / (priced.length - 1));
+    byPrice.set(candidate.model, SIZING_TIERS[index]!);
+  });
+  return candidates.map(candidate => {
+    const fromMapping = mapped.get(candidate.model);
+    if (fromMapping) return { ...candidate, tier: fromMapping, tierSource: "mapping" as const };
+    const fromPrice = byPrice.get(candidate.model);
+    return fromPrice
+      ? { ...candidate, tier: fromPrice, tierSource: "price" as const }
+      : { ...candidate, tier: null, tierSource: null };
+  });
+}
+
+export function cheapestSufficientCandidate(
+  classified: readonly ClassifiedCandidate[],
+  tier: SizingTier,
+): ClassifiedCandidate | null {
+  const need = SIZING_TIERS.indexOf(tier);
+  const ranked = classified
+    .map((candidate, order) => ({ candidate, order, rank: candidate.tier ? SIZING_TIERS.indexOf(candidate.tier) : -1 }))
+    .filter(entry => entry.rank >= need)
+    .sort((a, b) => a.rank - b.rank
+      || (a.candidate.unitPrice ?? Infinity) - (b.candidate.unitPrice ?? Infinity)
+      || a.order - b.order);
+  return ranked[0]?.candidate ?? null;
+}
+
+export interface RoleProposalInput {
+  readonly role: string;
+  readonly model: string | null;
+  readonly effort: string | null;
+}
+
+export type RoleProposal = RoleProposalInput & (
+  | {
+    readonly status: "proposed" | "unassigned";
+    readonly tier: SizingTier;
+    readonly effortIntent: SizingEffort;
+    readonly rationale: string;
+    readonly moveUpIf: string;
+    readonly moveDownIf: string;
+    readonly proposedModel: string | null;
+    /** Only when the role already carries an effort, unless the caller asks for one always. */
+    readonly proposedEffort: string | null;
+    readonly reason: string | null;
+  }
+  | { readonly status: "unsized"; readonly reason: string }
+);
+
+export function buildRoleProposals(
+  roles: readonly RoleProposalInput[],
+  sizing: ReadonlyMap<string, RoleSizingOutcome>,
+  classified: readonly ClassifiedCandidate[],
+  options: { readonly alwaysProposeEffort?: boolean } = {},
+): RoleProposal[] {
+  return roles.map(role => {
+    const outcome = sizing.get(role.role) ?? { unsized: "the role was not sized" };
+    if ("unsized" in outcome) return { ...role, status: "unsized", reason: outcome.unsized };
+    const { tier, effort, rationale, moveUpIf, moveDownIf } = outcome.sizing;
+    const pick = cheapestSufficientCandidate(classified, tier);
+    const sized = { ...role, tier, effortIntent: effort, rationale, moveUpIf, moveDownIf };
+    if (!pick) {
+      return {
+        ...sized,
+        status: "unassigned",
+        proposedModel: null,
+        proposedEffort: null,
+        reason: `no available model is classified ${tier} or above`,
+      };
+    }
+    const proposedEffort = role.effort === null && !options.alwaysProposeEffort
+      ? null
+      : mapEffortToLevel(effort, pick.efforts, pick.defaultEffort);
+    return { ...sized, status: "proposed", proposedModel: pick.model, proposedEffort, reason: null };
+  });
+}

package/src/codex/role-sizing-limits.ts

@@ -0,0 +1,2 @@
+/** Input limits the sizing call enforces. A leaf with no imports so the GUI shares the same values. */
+export const ROLE_INSTRUCTIONS_EXCERPT_CHARS = 1500;

package/src/codex/role-sizing.ts

@@ -0,0 +1,216 @@
+/**
+ * The sizing rubric for Codex agent roles: which capability tier a role needs and how hard it
+ * should reason, on a neutral scale that never names a model.
+ *
+ * This is the one home of the rubric. The dashboard's auto-assign sends it as the system prompt
+ * and parses the answer here; any later surface that sizes a role imports it rather than
+ * restating it. Choosing the concrete model and the concrete effort level is not the sizing
+ * model's job: that mapping is deterministic code in "role-auto-assign.ts".
+ *
+ * The tier and effort definitions, the risk factors, and the rules are ported from the
+ * modelchk skill by LilMGenius,
+ * https://github.com/LilMGenius/paperthin/blob/main/skills/depth/modelchk/SKILL.md,
+ * adapted from sizing one task to sizing a standing role and given a strict JSON answer shape.
+ * That text is used under the MIT License:
+ *
+ *   Copyright (c) 2026 LilMGenius
+ *
+ *   Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ *   and associated documentation files (the "Software"), to deal in the Software without
+ *   restriction, including without limitation the rights to use, copy, modify, merge, publish,
+ *   distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
+ *   Software is furnished to do so, subject to the following conditions:
+ *
+ *   The above copyright notice and this permission notice shall be included in all copies or
+ *   substantial portions of the Software.
+ *
+ *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+ *   BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ *   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ *   DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+import { ROLE_INSTRUCTIONS_EXCERPT_CHARS } from "./role-sizing-limits";
+
+export { ROLE_INSTRUCTIONS_EXCERPT_CHARS };
+
+/** Capability tiers, cheapest first. */
+export const SIZING_TIERS = ["fast", "standard", "frontier"] as const;
+export type SizingTier = typeof SIZING_TIERS[number];
+
+/** Reasoning effort intents, least deliberation first. Positions on a ladder, never level names. */
+export const SIZING_EFFORTS = ["glance", "measured", "thorough", "exhaustive"] as const;
+export type SizingEffort = typeof SIZING_EFFORTS[number];
+
+const MAX_FIELD_CHARS = 400;
+
+export const ROLE_SIZING_SYSTEM_PROMPT = [
+  "You size Codex agent roles before anyone spends a run on them. Each role is a standing agent that",
+  "a parent hands many tasks of the kind its instructions describe. For each role, size two dials",
+  "from one assessment of risk and complexity: capability tier and reasoning effort.",
+  "",
+  "Capability tier is the cheapest sufficient class:",
+  "- fast: local, mechanical, reversible work with cheap, complete verification.",
+  "- standard: ordinary repo-grounded reasoning, multi-step drafting, normal coding, and conventional documentation or skill work.",
+  "- frontier: architecture, high ambiguity, safety/security/privacy/data-loss risk, release-critical review, cross-domain scope, or work where one wrong assumption wastes a large run.",
+  "",
+  "Reasoning effort is how hard the model should deliberate. From least to most deliberation:",
+  "- glance: minimal deliberation; take the direct path. Resolves to the model's floor.",
+  "- measured: ordinary deliberation. Resolves to the model's default, or the middle of its ladder if no default is named.",
+  "- thorough: work the alternatives and check assumptions. Resolves above the everyday setting, short of the top.",
+  "- exhaustive: maximal deliberation; exhaust the search and re-check the work. Resolves to the model's ceiling.",
+  "",
+  "The axes are independent. A bounded but fiddly role can be fast + thorough; a quick expert call can",
+  "be frontier + glance. In most work they move together, parting when a cheap task needs hard thinking",
+  "or a strong model needs only a quick call. Effort buys deliberation, never capability, and more",
+  "effort is not more correct.",
+  "",
+  "Assess risk and complexity once for both dials:",
+  "- file, module, or ownership boundary crossing;",
+  "- reversibility and blast radius;",
+  "- safety, security, privacy, publishing, or data-loss risk;",
+  "- novelty, ambiguity, and long-context synthesis load;",
+  "- need for external research, adversarial review, or careful release sequencing;",
+  "- cost of a wrong answer.",
+  "",
+  "Choose the cheapest capability tier whose ceiling covers the role's judgment and risk. Default effort",
+  "to track tier (fast->glance, standard->measured, frontier->thorough), reserving exhaustive for the",
+  "hardest, highest-stakes work. Raise effort when an otherwise cheap role needs ambiguity resolved, long",
+  "multi-step reasoning, or adversarial self-check; lower it for bounded work under a strong model.",
+  "",
+  "Rules:",
+  "- Default to the cheapest sufficient tier and the effort the work needs, not the strongest of either.",
+  "- Never raise effort to buy capability; raise the tier.",
+  "- Risk beats size: a narrow high-risk role can need frontier; a broad mechanical role can stay fast + thorough.",
+  "- Use only the neutral words above. Do not name concrete model products, vendors, versions, or vendor effort levels anywhere in the answer.",
+  "",
+  "Answer with one JSON object and nothing else, no prose and no code fence:",
+  '{"roles":{"<role name>":{"tier":"fast|standard|frontier","effort":"glance|measured|thorough|exhaustive","rationale":"<one sentence covering both dials>","move_up_if":"<signals that would justify a stronger tier or higher effort>","move_down_if":"<signals that would justify a cheaper tier or lower effort>"}}}',
+  "Include every role you were given, keyed by its exact name, with exactly those five fields.",
+].join("\n");
+
+/**
+ * The rubric for sizing one described piece of delegated work instead of a standing role. The role
+ * rubric is kept whole so both surfaces share one scale; the addendum only changes what is sized.
+ */
+export const DELEGATED_WORK_SIZING_SYSTEM_PROMPT = [
+  ROLE_SIZING_SYSTEM_PROMPT,
+  "",
+  "This request sizes one-shot delegated work rather than a standing role. The single entry's instructions",
+  "describe the work a parent hands off; size that work itself, as described, rather than every task a",
+  "role with that description might later receive. Answer in the same shape, keyed by the entry's exact name.",
+].join("\n");
+
+export interface RoleSizing {
+  readonly tier: SizingTier;
+  readonly effort: SizingEffort;
+  readonly rationale: string;
+  readonly moveUpIf: string;
+  readonly moveDownIf: string;
+}
+
+/** A role's sizing, or the reason it could not be sized. No reason is ever turned into a guess. */
+export type RoleSizingOutcome =
+  | { readonly sizing: RoleSizing }
+  | { readonly unsized: string };
+
+export interface RoleSizingInput {
+  readonly role: string;
+  readonly instructions: string;
+}
+
+function textField(value: unknown): string | null {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+
+/**
+ * What the sizing model reads about one role: its description, then its developer instructions,
+ * cut to ROLE_INSTRUCTIONS_EXCERPT_CHARS. Null when the file is not TOML or carries neither,
+ * because a role sized from its name alone would be a guess.
+ */
+export function roleInstructionsExcerpt(toml: string): string | null {
+  let document: unknown;
+  try {
+    document = Bun.TOML.parse(toml.replace(/^\ufeff/, ""));
+  } catch {
+    return null;
+  }
+  if (typeof document !== "object" || document === null) return null;
+  const fields = document as Record<string, unknown>;
+  const parts = [textField(fields.description), textField(fields.developer_instructions)]
+    .filter((part): part is string => part !== null);
+  if (parts.length === 0) return null;
+  return parts.join("\n\n").slice(0, ROLE_INSTRUCTIONS_EXCERPT_CHARS);
+}
+
+export function buildRoleSizingUserMessage(inputs: readonly RoleSizingInput[]): string {
+  return "Size these Codex agent roles.\n\n" + JSON.stringify({
+    roles: inputs.map(input => ({ name: input.role, instructions: input.instructions })),
+  }, null, 2);
+}
+
+function oneLine(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const collapsed = value.replace(/\s+/g, " ").trim();
+  return collapsed === "" || collapsed.length > MAX_FIELD_CHARS ? null : collapsed;
+}
+
+function isMember<T extends string>(set: readonly T[], value: unknown): value is T {
+  return typeof value === "string" && (set as readonly string[]).includes(value);
+}
+
+function validateEntry(entry: unknown): RoleSizingOutcome {
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    return { unsized: "the sizing answer for this role is not an object" };
+  }
+  const fields = entry as Record<string, unknown>;
+  if (!isMember(SIZING_TIERS, fields.tier)) return { unsized: "the sizing answer has no valid tier" };
+  if (!isMember(SIZING_EFFORTS, fields.effort)) return { unsized: "the sizing answer has no valid effort" };
+  const rationale = oneLine(fields.rationale);
+  const moveUpIf = oneLine(fields.move_up_if);
+  const moveDownIf = oneLine(fields.move_down_if);
+  if (rationale === null || moveUpIf === null || moveDownIf === null) {
+    return { unsized: "the sizing answer is missing a rationale or a move trigger" };
+  }
+  return { sizing: { tier: fields.tier, effort: fields.effort, rationale, moveUpIf, moveDownIf } };
+}
+
+const CODE_FENCE = /^\x60{3}(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n[ \t]*\x60{3}$/i;
+
+/**
+ * Validate the sizing model's answer for each requested role.
+ *
+ * The answer must be one JSON object of the shape the rubric asks for. Two leniencies, both for
+ * content the mapping never reads: a single surrounding code fence, which models add out of habit,
+ * and keys beyond the five fields in a role's entry, which are ignored. Every one of the five must
+ * still be present and valid. Anything else wrong marks the affected role, or every role when the
+ * whole answer is unusable, as unsized with the reason.
+ */
+export function parseRoleSizingResponse(text: string, roles: readonly string[]): Map<string, RoleSizingOutcome> {
+  const out = new Map<string, RoleSizingOutcome>();
+  const everyRole = (reason: string) => {
+    for (const role of roles) out.set(role, { unsized: reason });
+    return out;
+  };
+  const trimmed = text.trim();
+  const fenced = CODE_FENCE.exec(trimmed);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fenced ? fenced[1]! : trimmed);
+  } catch {
+    return everyRole("the sizing model did not answer with JSON");
+  }
+  const answered = typeof parsed === "object" && parsed !== null
+    ? (parsed as Record<string, unknown>).roles
+    : undefined;
+  if (typeof answered !== "object" || answered === null || Array.isArray(answered)) {
+    return everyRole("the sizing answer has no roles object");
+  }
+  for (const role of roles) {
+    out.set(role, Object.hasOwn(answered, role)
+      ? validateEntry((answered as Record<string, unknown>)[role])
+      : { unsized: "the sizing model did not size this role" });
+  }
+  return out;
+}

package/src/codex/routing/selection.ts

@@ -1,4 +1,5 @@
 import { getEffectiveCodexAutoSwitchThreshold } from "../account-auto-switch";
+import { isCodexAccountHeldForCredits } from "../account-credit-use";
 import { isCodexAccountPaused } from "../account-pause";
 import { codexAccountPriorityLookup, pinnedCodexAccountId } from "../account-priority";
 import { isSelectableCodexPoolAccount } from "../account-id";
@@ -82,6 +83,37 @@ export function isCodexAccountPlanExcluded(
   return plan !== undefined && excluded.has(plan);
 }
 
+/**
+ * Whether the operator turned credits off for this account and one of its usage windows is full
+ * now (#6334). Checked wherever plan exclusion is checked, for the reason given there: an account
+ * that is already active or bound is served without passing through the eligible list.
+ */
+export function isCodexAccountHeldAtUsageLimit(
+  config: OcxConfig,
+  accountId: string,
+  now: number,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): boolean {
+  return isCodexAccountHeldForCredits(
+    config,
+    accountId,
+    getAccountQuota(accountId),
+    getPoolAccountPlanForSelection(config, accountId, selectionOptions),
+    now,
+  );
+}
+
+/** The automatic-rotation policies that also bind the legacy keep-the-active-account fallback. */
+export function isCodexAccountRotationExcluded(
+  config: OcxConfig,
+  accountId: string,
+  now: number,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): boolean {
+  return isCodexAccountPlanExcluded(config, accountId)
+    || isCodexAccountHeldAtUsageLimit(config, accountId, now, selectionOptions);
+}
+
 export function isCodexAccountSelectable(
   config: OcxConfig,
   accountId: string,
@@ -91,6 +123,7 @@ export function isCodexAccountSelectable(
 ): boolean {
   return !isCodexAccountPaused(config, accountId)
     && !isCodexAccountPlanExcluded(config, accountId)
+    && !isCodexAccountHeldAtUsageLimit(config, accountId, now, selectionOptions)
     && getCodexQuotaHealthSnapshot(accountId, quotaScope, now) === null
     && !isCodexQuotaAvoided(accountId, quotaScope, now)
     && !isCodexAccountSoftAvoided(accountId, now)
@@ -117,6 +150,7 @@ export function codexAccountBlockReason(
 ): CodexAffinityReason | undefined {
   if (isCodexAccountPaused(config, accountId)) return "paused";
   if (isCodexAccountPlanExcluded(config, accountId)) return "plan_excluded";
+  if (isCodexAccountHeldAtUsageLimit(config, accountId, now, selectionOptions)) return "credits_off";
   if (getCodexQuotaHealthSnapshot(accountId, quotaScope, now) !== null) return "cooldown";
   if (isCodexQuotaAvoided(accountId, quotaScope, now)) return "quota_avoided";
   if (isCodexAccountSoftAvoided(accountId, now)) return "transient";
@@ -172,6 +206,7 @@ export function getEligiblePoolAccounts(
       && account.id !== excludeId
       && !isCodexAccountPaused(config, account.id)
       && !isCodexAccountPlanExcluded(config, account.id, excludedPlans)
+      && !isCodexAccountHeldAtUsageLimit(config, account.id, now, selectionOptions)
       && !isAccountNeedsReauth(account.id)
       && (!skipFailoverReadyCandidates || !shouldFailover(config, account.id, now)))
     .filter(account => getCodexQuotaHealthSnapshot(account.id, quotaScope, now) === null)
@@ -195,6 +230,7 @@ export function getEligiblePoolAccounts(
     // in between the main account returns as a first-class candidate.
     && !isCodexQuotaAvoided(MAIN_CODEX_ACCOUNT_ID, quotaScope, now)
     && !isCodexPoolRefreshCooling(MAIN_CODEX_ACCOUNT_ID, now)
+    && !isCodexAccountHeldAtUsageLimit(config, MAIN_CODEX_ACCOUNT_ID, now, selectionOptions)
     && (!skipFailoverReadyCandidates || !shouldFailover(config, MAIN_CODEX_ACCOUNT_ID, now))
     && isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID, selectionOptions)
   ) {

package/src/codex/routing/thread-affinity.ts

@@ -102,6 +102,8 @@ export type CodexAffinityReason =
   | "unusable"
   | "paused"
   | "plan_excluded"
+  /** Credits are off for the account and one of its usage windows is full (#6334). */
+  | "credits_off"
   | "cooldown"
   | "quota_avoided"
   | "generation"