@bitkyc08/opencodex 2.87.0 → 2.89.0

package/src/cli/message-command.ts

@@ -2,13 +2,16 @@ import { MessageBudget } from "../messaging/budget";
 import { readMessageInput } from "../messaging/input";
 import { localSessions, messageFailure, sendLocalMessage } from "../messaging/send";
 import { parseMessageArgs } from "./message-args";
+import { parseRemoteMessageArgs } from "./message-remote-args";
 import { terminalSafeText } from "./runtime-api";
 
 /** Run one local messaging operation after pure syntax validation, then release owned resources. */
 export async function runMessageCommand(argv: readonly string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
+  const remote = parseRemoteMessageArgs(argv);
+  if (remote) return (await import("./message-remote-command")).runRemoteMessageCommand(remote, env);
   const args = parseMessageArgs(argv);
   if (!args) {
-    console.error("Usage: ocx message sessions [--json] | send (--thread <uuid> | --name <exact-name>) --stdin [--kind request|response|notification] [--in-reply-to <uuid>] [--json]");
+    console.error("Usage: ocx message sessions [--host <peer>] [--json] | send (--thread <uuid> | --name <exact-name>) --stdin [--host <peer>] [--kind request|response|notification] [--in-reply-to <uuid>] [--json] | enable [--port <port>] | disable | status | hosts <probe|add|list|remove|abandon|allow-inbound|deny-inbound> | serve [--host <peer>]...");
     return 64;
   }
   const controller = new AbortController();

package/src/cli/message-remote-args.ts

@@ -0,0 +1,69 @@
+import { validAlias, validPort, REMOTE_LIMITS } from "../messaging/remote-contract";
+import { isSshAlias } from "../link/ssh-argv";
+import { parseMessageArgs, type MessageArgs } from "./message-args";
+import { isThreadId } from "../messaging/types";
+
+export type RemoteMessageArgs = { action: "enable"; port?: number; json: boolean }
+  | { action: "disable" | "status" | "hosts-list" | "_control" | "_port"; json: boolean }
+  | { action: "serve"; hosts: string[]; json: boolean }
+  | { action: "hosts-probe"; ssh: string; json: boolean }
+  | { action: "hosts-add"; alias: string; ssh: string; fingerprint: string; json: boolean }
+  | { action: "hosts-remove"; host: string; transaction?: string; json: boolean }
+  | { action: "hosts-allow-inbound" | "hosts-deny-inbound"; host: string; json: boolean }
+  | { action: "hosts-abandon"; transaction: string; json: boolean }
+  | { action: "remote-operation"; host: string; local: MessageArgs; json: boolean };
+
+/** Pure remote syntax validation precedes state, home selection, listeners or SSH allocation. */
+export function parseRemoteMessageArgs(argv: readonly string[]): RemoteMessageArgs | null {
+  let action = argv[0], start = 1, positional: string | undefined;
+  if (action === "sessions" || action === "send") {
+    const hostIndex = argv.indexOf("--host");
+    if (hostIndex < 0 || argv.lastIndexOf("--host") !== hostIndex || !validAlias(argv[hostIndex + 1])) return null;
+    const local = parseMessageArgs([...argv.slice(0, hostIndex), ...argv.slice(hostIndex + 2)]);
+    return local ? { action: "remote-operation", host: argv[hostIndex + 1]!, local, json: local.json } : null;
+  }
+  if (action === "hosts") {
+    if (!["list", "probe", "add", "remove", "abandon", "allow-inbound", "deny-inbound"].includes(argv[1] ?? "")) return null;
+    action = `hosts-${argv[1]}`; start = 2;
+    if (["hosts-add", "hosts-remove", "hosts-allow-inbound", "hosts-deny-inbound"].includes(action)) {
+      positional = argv[start++]; if (!validAlias(positional)) return null;
+    }
+  }
+  const seen = new Set<string>(), flags: Record<string, string> = {}, hosts: string[] = [];
+  for (let index = start; index < argv.length; index++) {
+    const flag = argv[index]!;
+    if (seen.has(flag) && !(action === "serve" && flag === "--host")) return null;
+    seen.add(flag);
+    if (flag === "--json") continue;
+    const allowed = action === "enable" ? ["--port"] : action === "serve" ? ["--host"]
+      : action === "hosts-probe" ? ["--ssh"] : action === "hosts-add" ? ["--ssh", "--fingerprint"]
+        : action === "hosts-abandon" || action === "hosts-remove" ? ["--transaction"] : [];
+    if (!allowed.includes(flag)) return null;
+    const value = argv[++index]; if (!value || value.startsWith("--")) return null;
+    flags[flag] = value; if (flag === "--host") hosts.push(value);
+  }
+  const json = seen.has("--json");
+  if (action === "enable") {
+    if (flags["--port"] !== undefined && (!/^\d{4,5}$/.test(flags["--port"]) || !validPort(Number(flags["--port"])))) return null;
+    return { action, json, ...(flags["--port"] ? { port: Number(flags["--port"]) } : {}) };
+  }
+  if (action === "serve") return hosts.length <= REMOTE_LIMITS.peers && hosts.every(validAlias)
+    && new Set(hosts).size === hosts.length ? { action, hosts, json } : null;
+  if (["disable", "status", "hosts-list", "_control", "_port"].includes(action ?? "")) {
+    return { action: action as "disable", json };
+  }
+  if (action === "hosts-remove") {
+    const transaction = flags["--transaction"];
+    if (transaction !== undefined && !isThreadId(transaction)) return null;
+    return { action, host: positional!, json, ...(transaction !== undefined ? { transaction } : {}) };
+  }
+  if (action === "hosts-allow-inbound" || action === "hosts-deny-inbound") return { action, host: positional!, json };
+  if (action === "hosts-abandon" && isThreadId(flags["--transaction"])) return { action, transaction: flags["--transaction"]!, json };
+  if ((action === "hosts-probe" || action === "hosts-add") && flags["--ssh"] && isSshAlias(flags["--ssh"])) {
+    if (action === "hosts-probe") return { action, ssh: flags["--ssh"], json };
+    if (/^SHA256:[A-Za-z0-9+/=]{1,64}$/.test(flags["--fingerprint"] ?? "")) return {
+      action, alias: positional!, ssh: flags["--ssh"], fingerprint: flags["--fingerprint"], json,
+    };
+  }
+  return null;
+}

package/src/cli/message-remote-command.ts

@@ -0,0 +1,77 @@
+import { getConfigDir } from "../config/paths";
+import { MessageBudget } from "../messaging/budget";
+import { readMessageInput } from "../messaging/input";
+import { RemoteCapacity } from "../messaging/remote-contract";
+import { enrollRemoteHost, handleEnrollmentControl, probeRemoteHost, removeRemoteHost } from "../messaging/remote-enrollment";
+import { abandonRemoteEnrollment, pendingRemoteEnrollment } from "../messaging/remote-enrollment-recovery";
+import { remoteControl } from "../messaging/remote-auth";
+import { ownerEndpoint, startRemoteOwner } from "../messaging/remote-owner";
+import { remotePortCandidate } from "../messaging/remote-ports";
+import { remoteSessions, sendRemoteMessage } from "../messaging/remote-send";
+import { RemoteMessageStore } from "../messaging/remote-store";
+import { messageFailure } from "../messaging/send";
+import { messageCodexHome } from "./message-runtime";
+import { terminalSafeText } from "./runtime-api";
+import type { RemoteMessageArgs } from "./message-remote-args";
+
+/** Activate remote resources only after an explicit remote command's pure parser succeeds. */
+export async function runRemoteMessageCommand(args: RemoteMessageArgs, env: NodeJS.ProcessEnv): Promise<number> {
+  const store = new RemoteMessageStore(getConfigDir()), controller = new AbortController(), capacity = new RemoteCapacity();
+  const cancel = () => controller.abort();
+  process.once("SIGINT", cancel); process.once("SIGTERM", cancel);
+  const emit = (value: unknown) => console.log(args.json || args.action.startsWith("_")
+    ? JSON.stringify(value) : terminalSafeText(JSON.stringify(value)));
+  try {
+    if (args.action === "serve") {
+      const owner = await startRemoteOwner(store, messageCodexHome(env), args.hosts, controller.signal);
+      try {
+        emit({ protocol: "ocx-message-remote/1", running: true, port: owner.port });
+        await Promise.race([owner.finished, new Promise<void>(resolve => {
+          controller.signal.addEventListener("abort", () => resolve(), { once: true });
+          if (controller.signal.aborted) resolve();
+        })]);
+        if (!controller.signal.aborted) { emit({ running: false, error: { code: "owner_retired", message: "Foreground messaging owner retired; restart explicitly after resolving its route/configuration failure." } }); return 1; }
+      } finally { await owner.close(); }
+      return 0;
+    }
+    const budget = new MessageBudget(30000, controller.signal);
+    try {
+      if (args.action === "enable") { store.enable(args.port ?? store.read()?.port ?? 39176); emit(store.publicState()); }
+      else if (args.action === "disable") { store.disable(); emit(store.publicState()); }
+      else if (args.action === "hosts-list") emit({ ...store.publicState(), pendingEnrollment: pendingRemoteEnrollment(store) });
+      else if (args.action === "hosts-abandon") { emit(abandonRemoteEnrollment(store, args.transaction)); return 3; }
+      else if (args.action === "status") {
+        const state = store.read(); let running = false, routes: unknown = [];
+        if (state?.enabled) {
+          try { const result = await remoteControl(state, ownerEndpoint(state), "message/routes", {}, budget);
+            running = true; routes = result; } catch { /* Disabled/offline is not activation or repair. */ }
+        }
+        emit({ ...store.publicState(), running, routes, pendingEnrollment: pendingRemoteEnrollment(store) });
+      } else if (args.action === "hosts-probe") emit({ ssh: args.ssh, fingerprint: (await probeRemoteHost(args.ssh, budget, capacity)).fingerprint });
+      else if (args.action === "hosts-add") emit(await enrollRemoteHost(store, args.alias, args.ssh, args.fingerprint, budget, capacity));
+      else if (args.action === "hosts-allow-inbound" || args.action === "hosts-deny-inbound") {
+        emit(store.setInbound(args.host, args.action === "hosts-allow-inbound"));
+      }
+      else if (args.action === "hosts-remove") {
+        const receipt = await removeRemoteHost(store, args.host, budget, capacity, undefined, undefined, args.transaction); emit(receipt);
+        return receipt.remote === "removed" ? 0 : 3;
+      } else if (args.action === "_control") {
+        emit(handleEnrollmentControl(store, JSON.parse(await readMessageInput(Bun.stdin.stream(), budget))));
+      } else if (args.action === "_port") { store.requireEnabled(); emit({ port: remotePortCandidate() }); }
+      else if (args.action === "remote-operation") {
+        if (args.local.action === "sessions") emit(await remoteSessions(store, args.host, budget));
+        else {
+          const body = await readMessageInput(Bun.stdin.stream(), budget);
+          const receipt = await sendRemoteMessage(store, { ...args.local, host: args.host, body },
+            { home: messageCodexHome(env), senderId: env.CODEX_THREAD_ID }, budget);
+          emit(receipt); return receipt.status === "queued" ? 0 : receipt.status === "unknown" ? 3 : 1;
+        }
+      }
+      return 0;
+    } finally { budget.dispose(); }
+  } catch (error) {
+    // Control errors never echo stdin, SSH output, keys or paths; a failed enrollment keeps its transaction.
+    const failure = messageFailure(error), unknown = ["enrollment_unknown", "remote_control_unknown", "remote_storage_unknown", "cleanup_incomplete"].includes(failure.code);
+    emit({ schema: "ocx-message-error/1", ...(unknown ? { status: "unknown" } : args.action === "remote-operation" && args.local.action === "send" ? { status: "not_sent" } : {}), error: failure }); return unknown ? 3 : 1;
+  } finally { process.removeListener("SIGINT", cancel); process.removeListener("SIGTERM", cancel); }
+}

package/src/cli/provider-runtime.ts

@@ -10,8 +10,10 @@ import {
   takeBooleanOption,
   takeFlag,
   takeOption,
+  terminalSafeText,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import { interactiveConfirm } from "./interactive-confirm";
 import { takeProviderEditSettings } from "./provider-settings";
 import { printProviderReceipt, runProviderAction } from "./provider-result";
 import { providerQuotaLine } from "./account-extended";
@@ -46,7 +48,7 @@ const USAGE = `Usage:
       [--retain-models <id,id|->] [--model <id> --text-only]
       [--xai-chat <on|off>] [--upstream-http-version <http1.1|->] [--fast <on|off>] [--context-window <tokens|->]
       [--allow-private-network <on|off>] [--model-context-tier <model=default|long_context>] [--json]
-  ocx provider test <name> [--json]
+  ocx provider test <name> [--model <id> [--yes]] [--json]
   ocx provider quota [--refresh] [--json]
   ocx provider resets [--limit <n>] [--json]
   ocx provider presets [--json]
@@ -147,12 +149,78 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   return printProviderReceipt(result, wantsJson, "Provider edit");
 }
 
+interface CompletionTestDto {
+  applicable: boolean;
+  reason?: string;
+  detail?: string;
+  adapter?: string;
+  ok?: boolean;
+  wireModel?: string;
+  upstreamModel?: string | null;
+  modelComparison?: "match" | "mismatch" | "unknown";
+  comparisonNote?: "missing_metadata" | "conflicting_metadata";
+  ttftMs?: number | null;
+  totalLatencyMs?: number;
+  error?: { code: string; message: string; status?: number } | null;
+}
+
+async function testCompletion(name: string, model: string, yes: boolean, wantsJson: boolean, deps: RuntimeApiDeps): Promise<number> {
+  const input = deps.stdinImpl ?? process.stdin;
+  if (!yes && (wantsJson || !input.isTTY)) {
+    throw new CliUsageError("completion tests consume quota and may incur cost; --yes is required with --json or non-interactive input", USAGE);
+  }
+  const warning = terminalSafeText(`${name}: completion test for model ${model}. Warning: this sends an upstream request, consumes quota and may incur cost.`);
+  if (wantsJson) console.error(warning);
+  else console.log(warning);
+  if (!yes && !await interactiveConfirm({
+    question: "Run this completion test?", defaultYes: false, input: input as NodeJS.ReadStream,
+  })) {
+    console.log("cancelled");
+    return 1;
+  }
+  const result = await runtimeRequest<CompletionTestDto>(`/api/providers/test-completion?name=${encodeURIComponent(name)}`, {
+    method: "POST", redirect: "error", body: JSON.stringify({ model, confirm: true }),
+  }, deps);
+  if (result.applicable === false) {
+    printData(result, wantsJson, [
+      `${name}: not applicable — ${result.reason}`,
+      ...(result.detail ? [`Detail: ${result.detail}`] : []),
+      ...(result.adapter ? [`Adapter: ${result.adapter}`] : []),
+    ]);
+    return 0;
+  }
+  if (result.ok === true) {
+    printData(result, wantsJson, [
+      `${name}: connected`,
+      `TTFT: ${result.ttftMs ?? "unknown"} ms`,
+      `Total latency: ${result.totalLatencyMs ?? "unknown"} ms`,
+      `Upstream reported ${result.upstreamModel ?? "unknown"} for ${result.wireModel} — ${result.modelComparison}${result.comparisonNote ? ` (${result.comparisonNote})` : ""}`,
+      "metadata only — not proof of model identity",
+    ]);
+    return 0;
+  }
+  printData(result, wantsJson, [
+    `${name}: failed`,
+    `${result.error?.code ?? "unknown"}: ${result.error?.message ?? "Completion test failed"}${result.error?.status === undefined ? "" : ` (HTTP ${result.error.status})`}`,
+  ]);
+  return 1;
+}
+
 async function testProvider(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   const args = [...argv];
   const name = args.shift()?.trim();
   const wantsJson = takeFlag(args, "--json");
   if (!name) throw new CliUsageError("provider name is required", USAGE);
+  const model = takeOption(args, "--model")?.trim();
+  const yes = takeFlag(args, "--yes");
   rejectArgs(args, USAGE);
+  if (yes && model === undefined) throw new CliUsageError("--yes requires --model", USAGE);
+  if (model !== undefined) {
+    if (!model || model.length > 256 || /[\x00-\x1f\x7f-\x9f]/.test(model)) {
+      throw new CliUsageError("--model must contain 1..256 characters without control characters", USAGE);
+    }
+    return testCompletion(name, model, yes, wantsJson, deps);
+  }
   const result = await runtimeRequest<Record<string, unknown>>(`/api/providers/test?name=${encodeURIComponent(name)}`, {
     method: "POST",
   }, deps);

package/src/cli/registry.ts

@@ -16,9 +16,9 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "message",
-    usage: "ocx message <sessions|send> [options]",
-    summary: "Discover loaded local Codex sessions and submit one queued peer message.",
-    details: ["Local Unix transport only; starts no daemon. queued is submission, not processing; never replay an unknown send."],
+    usage: "ocx message <sessions|send|enable|disable|status|hosts|serve> [options]",
+    summary: "Discover loaded Codex sessions and queue messages locally or through explicit SSH peers.",
+    details: ["Remote listeners/tunnels require explicit foreground serve; no daemon start. queued is submission, not processing; never replay an unknown send."],
   },
   {
     name: "chatgpt",

package/src/codex/account-pause.ts

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+import type { AccountPauseDetails } from "../types/account-auto-pause";
 import type { OcxConfig } from "../types";
 import { deleteConfigTopLevelKey } from "../config/rebase-provenance";
 
@@ -7,7 +9,9 @@ export function isCodexAccountPaused(config: OcxConfig, accountId: string): bool
 }
 
 /** Persist the account's pool eligibility without changing credentials or runtime health. */
-export function setCodexAccountPaused(config: OcxConfig, accountId: string, paused: boolean): void {
+export function setCodexAccountPaused(config: OcxConfig, accountId: string, paused: boolean, details?: AccountPauseDetails): void {
+  config.codexAccountPauseState = { ...config.codexAccountPauseState,
+    [accountId]: { revision: randomUUID(), ...(paused && details ? { details } : {}) } };
   const pausedIds = new Set(config.pausedCodexAccountIds ?? []);
   if (paused) pausedIds.add(accountId);
   else pausedIds.delete(accountId);
@@ -18,4 +22,5 @@ export function setCodexAccountPaused(config: OcxConfig, accountId: string, paus
 
 export function forgetCodexAccountPause(config: OcxConfig, accountId: string): void {
   setCodexAccountPaused(config, accountId, false);
+  if (config.codexAccountPauseState) delete config.codexAccountPauseState[accountId];
 }

package/src/codex/account-runtime-state.ts

@@ -1,3 +1,4 @@
+import { setDecisionAccountUsable } from "../lib/decision-quota-sink";
 import { captureConfigGeneration, type GenerationContext } from "../lib/state-store-sweeper";
 import { isCodexAccountGenerationLive } from "./account-store";
 
@@ -39,12 +40,14 @@ export function clearMainRefreshGrantRejection(key: string): void {
 }
 
 
+/** Quarantine a Codex account (or one credential generation) after an auth failure, and mark its advisory decision-quota row unusable so routing evidence cannot treat it as healthy. */
 export function markAccountNeedsReauth(
   id: string,
   writerGeneration = captureConfigGeneration(),
   credentialGeneration?: number,
 ): void {
   if (writerGeneration < lastReconciledGeneration && !liveAccountIds.has(id)) return;
+  setDecisionAccountUsable(id === "__main__" ? "codex-main" : "codex", id, false, credentialGeneration);
   // An account-wide mark supersedes a generation-scoped one: it is the stronger claim.
   if (credentialGeneration === undefined || !reauthAccounts.has(id)) {
     reauthAccounts.set(id, credentialGeneration);
@@ -81,6 +84,7 @@ export function isAccountNeedsReauth(id: string): boolean {
   return true;
 }
 
+/** Lift a reauth quarantine only when the proof matches the quarantined credential generation, and restore the advisory decision-quota row's usability. */
 export function clearAccountNeedsReauth(id: string, credentialGeneration?: number): void {
   // A model response proves only the credential it used. Keep account-wide
   // quarantine and evidence from another generation intact.
@@ -88,4 +92,5 @@ export function clearAccountNeedsReauth(id: string, credentialGeneration?: numbe
     && (reauthAccounts.get(id) !== credentialGeneration
       || !isCodexAccountGenerationLive(id, credentialGeneration))) return;
   reauthAccounts.delete(id);
+  setDecisionAccountUsable(id === "__main__" ? "codex-main" : "codex", id, true, credentialGeneration);
 }

package/src/codex/account-store.ts

@@ -14,6 +14,7 @@ import {
   hardenExistingSecret,
   withConfigMutationLockSync,
 } from "../config";
+import { notifyCodexStoreLoaded } from "../lib/decision-quota-sink";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import type { CodexAccountCredentialRecord, CodexAccountCredentials } from "../types";
 import { advanceCodexCredentialMutationEpoch } from "./credential-mutation-epoch";
@@ -113,30 +114,56 @@ function normalizeRecord(value: CodexAccountCredentials | CodexAccountCredential
   return undefined;
 }
 
+/**
+ * Observe-only read for the JEV quota activation owner: the same normalization as the loader,
+ * without hardening, invalid-file backup or slot notification. Absent or invalid stores read as empty.
+ */
+export function peekCodexAccountRecordStore(): Record<string, CodexAccountCredentialRecord> {
+  const path = codexAccountsPath();
+  if (!existsSync(path)) return {};
+  const normalized: Record<string, CodexAccountCredentialRecord> = {};
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf-8")) as RawCodexAccountStore;
+    for (const [id, value] of Object.entries(raw)) {
+      const record = normalizeRecord(value);
+      if (record) normalized[id] = record;
+    }
+  } catch {
+    return {};
+  }
+  return normalized;
+}
+
+/** Read the Codex account record store from disk with hardened permissions, and hand it to the opt-in decision-quota slot (a no-op unless JEV quota signals are active). */
 function loadCodexAccountRecordStore(): CodexAccountStore {
   const path = codexAccountsPath();
   hardenConfigDir();
   hardenExistingSecret(path);
-  if (!existsSync(path)) return {};
+  if (!existsSync(path)) { notifyCodexStoreLoaded({}); return {}; }
+  const normalized: CodexAccountStore = {};
   try {
     const raw = JSON.parse(readFileSync(path, "utf-8")) as RawCodexAccountStore;
-    const normalized: CodexAccountStore = {};
     for (const [id, value] of Object.entries(raw)) {
       const record = normalizeRecord(value);
       if (record) normalized[id] = record;
     }
-    return normalized;
   } catch {
     backupInvalidConfig(path);
+    notifyCodexStoreLoaded({});
     return {};
   }
+  // Outside the parse try: roster publication is advisory and must never route a loaded store into the invalid-config backup path.
+  notifyCodexStoreLoaded(normalized);
+  return normalized;
 }
 
+/** Atomically write the Codex account store, then hand it to the opt-in decision-quota slot so active advisory evidence tracks the persisted credentials. */
 function persist(store: CodexAccountStore): void {
   const dir = getConfigDir();
   assertNotRealHomeUnderTest(dir);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
   atomicWriteFile(codexAccountsPath(), JSON.stringify(store, null, 2) + "\n");
+  notifyCodexStoreLoaded(store);
 }
 
 function persistCredentialMutation(store: CodexAccountStore): void {

package/src/codex/auth-api/account-list.ts

@@ -141,6 +141,7 @@ export function poolAccountDto(
     logLabel: codexAccountLogLabel(account),
     isMain: false,
     paused,
+    ...(config.codexAccountPauseState?.[account.id]?.details ? { pauseDetails: config.codexAccountPauseState[account.id]!.details } : {}),
     priority,
     autoSwitchThresholdOverride: getCodexAccountAutoSwitchThresholdOverride(config, account.id),
     creditsAfterLimit: codexAccountUsesCreditsAfterLimit(config, account.id),
@@ -167,6 +168,7 @@ export interface CodexAuthAccountDto {
   logLabel?: string;
   isMain: boolean;
   paused: boolean;
+  pauseDetails?: import("../../types/account-auto-pause").AccountPauseDetails;
   /** Selection order; higher is used earlier. Always present, 0 when unset. */
   priority: number;
   /** Null inherits the global usage-switch threshold; 0 disables it for this account. */
@@ -403,6 +405,7 @@ export async function listCodexAuthAccountsSnapshot(
       logLabel: "main",
       isMain: true,
       paused: isCodexAccountPaused(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
+      ...(runtimeConfig.codexAccountPauseState?.[MAIN_CODEX_ACCOUNT_ID]?.details ? { pauseDetails: runtimeConfig.codexAccountPauseState[MAIN_CODEX_ACCOUNT_ID]!.details } : {}),
       mainAccountHardLock: { ...getMainAccountHardLockStatus(runtimeConfig),
         externalUsage: getMainAccountExternalUsageWarning(getObservedMainQuotaIdentityKey()) },
       priority: getCodexAccountPriority(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),

package/src/codex/auth-api/main-account-probe.ts

@@ -6,7 +6,7 @@ import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../.
 import { providerCodexAccountMode } from "../../providers/registry";
 import { isSelectableCodexPoolAccount } from "../account-id";
 import type { OcxConfig } from "../../types";
-import { parseMainPolicyUsageQuota, parseUsageQuota, setAccountQuotaFromParsed } from "../quota";
+import { isValidWhamHistoryObservation, parseMainPolicyUsageQuota, parseUsageQuota, setAccountQuotaFromParsed } from "../quota";
 import type { StoredAccountQuota, WhamUsageResponse } from "../quota";
 import { reconcileMainCodexAccountRuntimeState } from "../account-lifecycle";
 import { getMainChatgptAccountId, readCodexTokensResult } from "../auth-collision";
@@ -278,6 +278,7 @@ export async function fetchMainAccountInfoWhileOwned(
   let quotaPhase: "request" | "body" | "decode" | "publish" = "request";
   let quotaRefreshGeneration = captureMainAccountIdentityGeneration();
   const readState: { owner?: CodexUsageOwner<MainAccountInfoFetchResult>; usable: boolean } = { usable: false };
+  /** Perform one single-flight main-account usage read: classify auth failures and publish parsed quota and decision evidence only while the dispatch and credential are still current. */
   const read = async (): Promise<MainAccountInfoFetchResult> => {
     try {
       let dispatchSequence = 0;
@@ -398,7 +399,7 @@ export async function fetchMainAccountInfoWhileOwned(
       // score and auto-switch the main account exactly like a pool account (Option A).
       setMainAccountPlan(result.plan);
       if (result.quota) {
-        setAccountQuotaFromParsed(MAIN_CODEX_ACCOUNT_ID, result.quota, writerGeneration, mainQuotaWriter, policyQuota);
+        setAccountQuotaFromParsed(MAIN_CODEX_ACCOUNT_ID, result.quota, writerGeneration, mainQuotaWriter, policyQuota, undefined, false, false, isValidWhamHistoryObservation(usage) ? quota : null);
       }
       publishQuotaDispatch(dispatchSequence);
       readState.usable = quota !== null;

package/src/codex/auth-context.ts

@@ -69,7 +69,7 @@ import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
 import { maskAccountId } from "../lib/privacy";
 import { formatErrorResponse, formatUsageLimitReachedResponse } from "../bridge";
 import { nextCodexPoolRecoveryAt } from "./routing/pool-recovery";
-import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, getMainPolicyQuota, parseUsageQuota, parseMainPolicyUsageQuota, setAccountQuotaFromParsed } from "./quota";
+import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota, getMainPolicyQuota, isValidWhamHistoryObservation, parseUsageQuota, parseMainPolicyUsageQuota, setAccountQuotaFromParsed } from "./quota";
 import { codexAccountUsesCreditsAfterLimit, codexUsageLimitResetAt } from "./account-credit-use";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
@@ -665,6 +665,7 @@ function assertReserveAdmission(config: CodexAuthPolicyConfig): void {
   }
 }
 
+/** Authorize a reserve request for the main credential, re-checking admission and writer liveness, and publish the ordinary quota observed during the capability read. */
 async function authorizeReserveCredential(
   token: { accessToken: string; chatgptAccountId: string },
   writer: MainQuotaWriter | undefined,
@@ -681,9 +682,11 @@ async function authorizeReserveCredential(
   const authorization = isMainReserveAuthorizationLive(existing, token) ? existing
     : await getMainReserveAuthorization({
       token, writer, signal,
+      /** Publish the ordinary usage observed during the reserve capability read: parse it once and reuse that observation as the advisory decision evidence when it is a valid history observation. */
       observeOrdinaryQuota(data, capturedWriter) {
-        setAccountQuotaFromParsed(MAIN_CODEX_ACCOUNT_ID, parseUsageQuota(data), writerGeneration,
-          capturedWriter, parseMainPolicyUsageQuota(data));
+        const parsed = parseUsageQuota(data);
+        setAccountQuotaFromParsed(MAIN_CODEX_ACCOUNT_ID, parsed, writerGeneration,
+          capturedWriter, parseMainPolicyUsageQuota(data), undefined, false, false, isValidWhamHistoryObservation(data) ? parsed : null);
       },
     });
   // The capability read also publishes ordinary quota. A new 99% reading or cooldown wins.
@@ -769,8 +772,10 @@ export function createCodexAuthDispatchGuard(
   terminalHelper = false,
 ): ((headers: Headers) => void) | undefined {
   const reserveGuard = createCodexReserveDispatchGuard(ctx, config, modelId, admission, terminalHelper);
-  if (ctx.kind !== "pool") return reserveGuard;
+  if (ctx.kind !== "pool" && ctx.kind !== "main-pool") return reserveGuard;
   return headers => {
+    if (config.pausedCodexAccountIds?.includes(ctx.accountId)) throw new CodexPoolAuthenticationError("Selected Codex account is paused; resume it in account settings");
+    if (ctx.kind === "main-pool") { reserveGuard?.(headers); return; }
     assertPoolAccountCredits(ctx.accountId, poolContextCreditHoldResetAt(ctx, config));
     reserveGuard?.(headers);
   };

package/src/codex/catalog/aggregation.ts

@@ -195,6 +195,7 @@ export function deriveComboCatalogModel(
     ...(combo.alias ? { alias: combo.alias } : {}),
     ...(combo.nativeAlias ? { nativeAlias: true } : {}),
     ...(combo.displayName ? { displayName: combo.displayName } : {}),
+    ...(combo.description ? { description: combo.description } : {}),
     ...(defaultReasoningEffort ? { defaultReasoningEffort } : {}),
     ...(members.every(member => member.parallelToolCalls === true)
       ? { parallelToolCalls: true }
@@ -401,6 +402,20 @@ export function exactComboCatalogSlugs(
   }));
 }
 
+/** Current combo row descriptions by public catalog slug, for retained-row re-projection (#7229). */
+export function comboCatalogDescriptions(
+  config: Pick<OcxConfig, "combos" | "disabledModels">,
+): Map<string, string> {
+  const current = exactComboCatalogSlugs(config);
+  return new Map(listComboIds(config).flatMap(id => {
+    const raw = config.combos?.[id];
+    const alias = typeof raw?.alias === "string" ? raw.alias.trim() : "";
+    const publicSlug = alias || comboModelId(id);
+    const description = typeof raw?.description === "string" ? raw.description.trim() : "";
+    return description && current.has(publicSlug) ? [[publicSlug, description] as const] : [];
+  }));
+}
+
 export function normalizedOpenAiApiSignature(model: CatalogModel): string {
   const normalized = {
     provider: model.provider,

package/src/codex/catalog/auto-review.ts

@@ -5,6 +5,7 @@ import { encodeRoutedModelId } from "../../providers/slug-codec";
 import { canonicalAutoReviewModelKey, isValidAutoReviewModel as isValidAutoReviewTarget } from "../../config/provider-validation";
 import { readConfiguredAutoReviewModel } from "./parsing";
 import type { RawEntry } from "./parsing";
+import { hasOcxRoutedAuthorship } from "./ownership";
 import { configuredCatalogEntry } from "./subagent-roster";
 
 const AUTO_REVIEW_ROOT_MARKER = "opencodex_auto_review_root";
@@ -38,7 +39,7 @@ function isRoutedCatalogEntry(entry: RawEntry): boolean {
   if (isCodexControlPlaneModel(entry.slug)) return false;
   const slug = typeof entry.slug === "string" ? entry.slug : "";
   return slug.includes("/")
-    || (typeof entry.description === "string" && entry.description.startsWith("Routed via opencodex → "));
+    || hasOcxRoutedAuthorship(entry);
 }
 
 /** Restore an owned native value, retaining provenance to avoid legacy reclassification. */

package/src/codex/catalog/build-entries.ts

@@ -4,6 +4,7 @@ import { CODEX_REASONING_LEVELS, type CodexReasoningLevel } from "../../reasonin
 import { clearModelCache } from "../model-cache";
 import { routedSlug, slugEquivalenceKey } from "../../providers/slug-codec";
 import { COMBO_NAMESPACE } from "../../combos";
+import { hasOcxComboAuthorship, hasOcxRoutedAuthorship, reapplyRetainedComboDescription, ROUTED_DESCRIPTION_PREFIX } from "./ownership";
 import {
   CODEX_CUSTOM_MODEL_CATALOG_KIND,
   CODEX_PROVIDER_MODEL_CATALOG_KIND,
@@ -218,7 +219,7 @@ export function buildCatalogEntriesFromObservedState({
     const routed = deriveEntry(
       template,
       slug,
-      `Routed via opencodex → ${nativeAlias.provider} (${nativeAlias.owned_by ?? nativeAlias.provider}).`,
+      `${ROUTED_DESCRIPTION_PREFIX}${nativeAlias.provider} (${nativeAlias.owned_by ?? nativeAlias.provider}).`,
       5,
       nativeAlias,
       exactComboSlugs,
@@ -276,7 +277,7 @@ export function buildCatalogEntriesFromObservedState({
     const e = deriveEntry(
       template,
       slug,
-      `Routed via opencodex → ${m.provider} (${m.owned_by ?? m.provider}).`,
+      `${ROUTED_DESCRIPTION_PREFIX}${m.provider} (${m.owned_by ?? m.provider}).`,
       5,
       m,
       exactComboSlugs,
@@ -380,15 +381,15 @@ export function orderForModelPicker(
  * True when an existing catalog row was authored by OpenCodex routing (#855).
  * Every generated routed row — current full-slug form, the June–July 2026
  * provider-name form, and legacy combo aliases — carries the stable
- * description prefix `Routed via opencodex → `; foreign rows from Cursor or
+ * description prefix `Routed via opencodex → `, or — when a combo overrides its description
+ * (#7229) — the `opencodex_routed_origin` marker (./ownership); foreign rows from Cursor or
  * user tooling do not. `owned_by` describes upstream ownership, and `comp_hash`
  * describes history compatibility; neither is an authorship signal.
  */
 export function isOcxAuthoredRoutedEntry(entry: RawEntry): boolean {
   if (isNativeAliasCatalogEntry(entry)) return true;
-  const desc = typeof entry.description === "string" ? entry.description : "";
   const slug = typeof entry.slug === "string" ? entry.slug : "";
-  return slug.includes("/") && desc.startsWith("Routed via opencodex → ");
+  return slug.includes("/") && hasOcxRoutedAuthorship(entry);
 }
 
 function recoverableNativeSlug(entry: RawEntry): string | null {
@@ -503,6 +504,11 @@ export interface ObservedCatalogMergeInput {
   readonly multiAgentV2Enabled: boolean;
   readonly keepNativeChatGptOnV1?: boolean;
   readonly exactComboSlugs: ReadonlySet<string>;
+  /**
+   * Current combo row descriptions by public slug (#7229). When supplied, retained combo rows
+   * are re-projected onto it; absent means the caller has no config and leaves them unchanged.
+   */
+  readonly comboDescriptions?: ReadonlyMap<string, string>;
   readonly hasPhysicalComboProvider: boolean;
   readonly includeNativeOpenAi: boolean;
   readonly accountBoundEntries: readonly RawEntry[];
@@ -545,6 +551,7 @@ export function mergeCatalogEntriesFromObservedState({
   multiAgentV2Enabled,
   keepNativeChatGptOnV1,
   exactComboSlugs,
+  comboDescriptions,
   hasPhysicalComboProvider,
   includeNativeOpenAi,
   accountBoundEntries,
@@ -639,8 +646,7 @@ export function mergeCatalogEntriesFromObservedState({
   }
   const freshExactComboEntries = new Set(admittedRoutedEntries.filter(entry => (
     isExactComboCatalogEntry(entry, exactComboSlugs)
-    && typeof entry.description === "string"
-    && entry.description.startsWith(`Routed via opencodex → ${COMBO_NAMESPACE} (`)
+    && hasOcxComboAuthorship(entry)
   )));
   const rank = new Map(featured.map((slug, i) => [slug, i] as const));
   const freshEquivalentKeys = new Set(admittedRoutedEntries.flatMap(entry => (
@@ -802,6 +808,10 @@ export function mergeCatalogEntriesFromObservedState({
       delete entry[SPAWN_PRIORITY_FIELD];
     }
     const slug = String(entry.slug);
+    if (comboDescriptions !== undefined && exactComboSlugs.has(slug)
+      && (isNativeAliasCatalogEntry(entry) || (entry.owned_by === COMBO_NAMESPACE && hasOcxComboAuthorship(entry)))) {
+      reapplyRetainedComboDescription(entry, comboDescriptions.get(slug));
+    }
     if (!isOcxAuthoredRoutedEntry(entry)) continue;
     // The builder no longer copies a template's comp_hash onto routed rows (#5796), but a row
     // kept from disk may still carry one. Custom rows, Codex-forward aliases included, never