@bitkyc08/opencodex 2.88.0 → 2.90.0

package/src/claude/desktop-3p.ts

@@ -6,7 +6,7 @@ import { canonicalDirectory } from "./desktop-remote-store-io";
 import {
   resolveDesktop3pConfigLibraryPath, parseMetadata, SAFE_DESKTOP_PROFILE_ID, isRecord,
   isOwnedDesktopEntry, isOwnedDesktopGatewayEntry, profilePath, readDesktopProfileSnapshot, readDesktopLibraryText, readDesktopLibraryBytes,
-  readOptionalDesktopLibraryBytes,
+  readOptionalDesktopLibraryBytes, assertDesktopLibraryTextSize, serializeDesktopLibraryJson,
   type Desktop3pConfigLibraryOptions, type Desktop3pMetadata, type Desktop3pMetadataEntry,
 } from "./desktop-3p-library";
 export { resolveDesktop3pConfigLibraryPath, type Desktop3pConfigLibraryOptions } from "./desktop-3p-library";
@@ -642,13 +642,24 @@ function removeDesktop3pStandardPivotLocal(
     if (targetIds.length === 0) return { ok: true, changed: false, kind: "noop", libraryPath: inspected.libraryPath };
 
     let metadataAfterPivot = metadata;
+    let standardPath: string | undefined;
+    let pivotMetadataJson: string | undefined;
     if (selectedOwnedGatewayActive) {
       const standardId = randomUUID();
-      const standardPath = profilePath(inspected.libraryPath, standardId);
-      atomicWriteFile(standardPath, "{}\n");
+      standardPath = profilePath(inspected.libraryPath, standardId);
       const standardEntry: Desktop3pMetadataEntry = { id: standardId, name: "opencodex-standard" };
       metadataAfterPivot = { ...metadata, appliedId: standardId, entries: [...metadata.entries, standardEntry] };
-      atomicWriteFile(metadataPath, JSON.stringify(metadataAfterPivot, null, 2) + "\n");
+      pivotMetadataJson = serializeDesktopLibraryJson(metadataAfterPivot);
+    }
+    // Bound the final metadata before any unlink so a size refusal cannot strand
+    // a row pointing at an already-deleted profile.
+    const removalMetadataJson = serializeDesktopLibraryJson({
+      ...metadataAfterPivot,
+      entries: metadataAfterPivot.entries.filter(entry => !targetIds.includes(entry.id)),
+    });
+    if (standardPath !== undefined && pivotMetadataJson !== undefined) {
+      atomicWriteFile(standardPath, "{}\n");
+      atomicWriteFile(metadataPath, pivotMetadataJson);
     }
 
     const residualPaths: string[] = [];
@@ -674,10 +685,7 @@ function removeDesktop3pStandardPivotLocal(
     }
     // Do not leave a metadata row pointing at a deleted profile. For a foreign
     // selection this only removes proven opencodex residues; appliedId is kept.
-    atomicWriteFile(
-      metadataPath,
-      JSON.stringify({ ...metadataAfterPivot, entries: metadataAfterPivot.entries.filter(entry => !targetIds.includes(entry.id)) }, null, 2) + "\n",
-    );
+    atomicWriteFile(metadataPath, removalMetadataJson);
     return { ok: true, changed: true, kind: "removed", libraryPath: inspected.libraryPath };
   } catch (error) {
     return { ok: false, changed: false, kind: "write_failed", libraryPath: inspected.libraryPath, reason: desktopMutationFailureReason(error) };
@@ -831,7 +839,7 @@ function writeDesktop3pConfigWithGenerator(
 
     const generated = generate();
     const previous = readDesktopProfileSnapshot(configPath);
-    const configJson = JSON.stringify({ ...previous.foreign, ...generated }, null, 2) + "\n";
+    const configJson = serializeDesktopLibraryJson({ ...previous.foreign, ...generated });
     const fingerprint = createHash("sha256").update(configJson).digest("hex").slice(0, 16);
     if (refreshOnly) {
       atomicWriteFileNoFollow(configPath, configJson, undefined, {
@@ -849,9 +857,10 @@ function writeDesktop3pConfigWithGenerator(
       });
       return { written: true, path: configPath, fingerprint };
     }
+    const metadataJson = serializeDesktopLibraryJson({ ...metadata, appliedId: id, entries });
     atomicReplaceDesktopConfig(configPath, configJson, previous.bytes);
     try {
-      atomicWriteFile(metadataPath, JSON.stringify({ ...metadata, appliedId: id, entries }, null, 2) + "\n");
+      atomicWriteFile(metadataPath, metadataJson);
     } catch (metaError) {
       // Roll back from the verified bytes in memory: reopening the backup could meet a swapped
       // entry and leave the new profile beside the old metadata. A profile this call created is
@@ -895,6 +904,7 @@ export function atomicReplaceDesktopConfig(
   previous: Buffer | undefined,
   writer: typeof atomicWriteFileNoFollow = atomicWriteFileNoFollow,
 ): { backupPath?: string } {
+  assertDesktopLibraryTextSize(content);
   const validateBeforeRename = () => assertDesktopProfileUnchanged(path, previous);
   validateBeforeRename();
   const backupPath = `${path}.bak`;

package/src/claude/desktop-picker-profile.ts

@@ -19,6 +19,7 @@ import {
   readDesktopLibraryText,
   resolveDesktop3pConfigLibraryPath,
   SAFE_DESKTOP_PROFILE_ID,
+  serializeDesktopLibraryJson,
   type Desktop3pConfigLibraryOptions,
   type Desktop3pMetadata,
   type Desktop3pMetadataEntry,
@@ -48,7 +49,7 @@ function metadataPath(libraryPath: string): string {
 }
 
 function metadataJson(metadata: Desktop3pMetadata): string {
-  return JSON.stringify(metadata, null, 2) + "\n";
+  return serializeDesktopLibraryJson(metadata);
 }
 
 function isValidMetadata(metadata: Desktop3pMetadata): boolean {
@@ -190,6 +191,10 @@ function applyDesktopPickerProfileLocked(options: { proxyPort: number } & Deskto
     const changed = !alreadySelected || !oldProfile.exists || oldProfile.content !== target;
     if (!changed) return { ok: true, changed: false, path: profile };
 
+    const entries = existing
+      ? metadata.entries.map(entry => entry.id === entryId ? { ...entry, name: DESKTOP_PICKER_ENTRY_NAME } : entry)
+      : [...metadata.entries, { id: entryId, name: DESKTOP_PICKER_ENTRY_NAME }];
+    const nextMetadataJson = metadataJson({ ...metadata, appliedId: entryId, entries });
     mkdirSync(join(configDir, PICKER_DIRECTORY), { recursive: true, mode: 0o700 });
     try {
       // Keep the same backup convention as the existing Desktop writer. It is removed with the
@@ -199,10 +204,7 @@ function applyDesktopPickerProfileLocked(options: { proxyPort: number } & Deskto
       if (!alreadySelected) {
         atomicWriteFile(previousStatePath, JSON.stringify({ entryId, previousAppliedId }) + "\n");
       }
-      const entries = existing
-        ? metadata.entries.map(entry => entry.id === entryId ? { ...entry, name: DESKTOP_PICKER_ENTRY_NAME } : entry)
-        : [...metadata.entries, { id: entryId, name: DESKTOP_PICKER_ENTRY_NAME }];
-      atomicWriteFile(metaPath, metadataJson({ ...metadata, appliedId: entryId, entries }));
+      atomicWriteFile(metaPath, nextMetadataJson);
     } catch {
       try {
         restoreFile(metaPath, oldMeta);
@@ -246,6 +248,8 @@ function removeDesktopPickerProfileLocked(options: DesktopPickerProfileOptions):
     try { state = readPickerState(statePath); } catch { return { ok: false, reason: "profile_state_unreadable" }; }
 
     let metadataAfterPivot = metadata;
+    let standardPath: string | undefined;
+    let pivotMetadataJson: string | undefined;
     if (selected) {
       const previous = state?.entryId === picker.id ? state.previousAppliedId : null;
       const previousExists = previous !== null && previous !== picker.id && metadata.entries.some(entry => entry.id === previous);
@@ -253,16 +257,22 @@ function removeDesktopPickerProfileLocked(options: DesktopPickerProfileOptions):
         metadataAfterPivot = { ...metadata, appliedId: previous };
       } else {
         const standardId = randomUUID();
-        atomicWriteFile(profilePath(libraryPath, standardId), "{}\n");
+        standardPath = profilePath(libraryPath, standardId);
         metadataAfterPivot = {
           ...metadata,
           appliedId: standardId,
           entries: [...metadata.entries, { id: standardId, name: "opencodex-standard" }],
         };
       }
-      atomicWriteFile(metaPath, metadataJson(metadataAfterPivot));
+      pivotMetadataJson = metadataJson(metadataAfterPivot);
     }
 
+    const entries = metadataAfterPivot.entries.filter(entry => entry.id !== picker.id);
+    const finalMetadataJson = metadataJson({ ...metadataAfterPivot, entries });
+
+    if (standardPath !== undefined) atomicWriteFile(standardPath, "{}\n");
+    if (pivotMetadataJson !== undefined) atomicWriteFile(metaPath, pivotMetadataJson);
+
     const residualPaths: string[] = [];
     for (const path of [profilePath(libraryPath, picker.id), `${profilePath(libraryPath, picker.id)}.bak`]) {
       try { unlinkIfPresent(path); } catch { /* report the path without exposing file contents */ }
@@ -272,9 +282,8 @@ function removeDesktopPickerProfileLocked(options: DesktopPickerProfileOptions):
       return { ok: false, reason: "cleanup_incomplete", residualPaths };
     }
 
-    const entries = metadataAfterPivot.entries.filter(entry => entry.id !== picker.id);
     try {
-      atomicWriteFile(metaPath, metadataJson({ ...metadataAfterPivot, entries }));
+      atomicWriteFile(metaPath, finalMetadataJson);
       try { unlinkIfPresent(statePath); } catch { /* residual is reported below */ }
       if (existsSync(statePath)) return { ok: false, reason: "cleanup_incomplete", residualPaths: [statePath] };
     } catch {

package/src/claude/desktop-remote-store-io.ts

@@ -2,7 +2,7 @@ import { chmodSync, lstatSync, mkdirSync, realpathSync, unlinkSync } from "node:
 import { basename, dirname, join, resolve } from "node:path";
 import { atomicWriteFile, getConfigDir } from "../config";
 import { hardenSecretDir } from "../lib/windows-secret-acl";
-import { isRecord, readDesktopLibraryBytes, resolveDesktop3pConfigLibraryPath, SAFE_DESKTOP_PROFILE_ID, type Desktop3pMetadata } from "./desktop-3p-library";
+import { isRecord, MAX_DESKTOP_PROFILE_FILE_BYTES, readDesktopLibraryBytes, resolveDesktop3pConfigLibraryPath, SAFE_DESKTOP_PROFILE_ID, type Desktop3pMetadata } from "./desktop-3p-library";
 import { DesktopStoreError, digest } from "./desktop-remote-store-state";
 
 export const MAX_DESKTOP_METADATA_ENTRIES = 256;
@@ -45,7 +45,7 @@ export class StoreIO {
     try {
       // The shared verified regular-file read keeps a swapped FIFO from parking this
       // open before the post-read identity recheck below can run.
-      const bytes = readDesktopLibraryBytes(path);
+      const bytes = readDesktopLibraryBytes(path, Math.min(maxBytes, MAX_DESKTOP_PROFILE_FILE_BYTES));
       if (bytes.byteLength > maxBytes || identity(lstatSync(path)) !== identity(stat)) throw new DesktopStoreError("conflict");
       const value: unknown = JSON.parse(bytes.toString("utf8"));
       if (!isRecord(value)) throw new DesktopStoreError("unsafe");

package/src/claude/inbound.ts

@@ -21,6 +21,7 @@ import { stabilizeClaudeInstructionsForPromptCache } from "./inbound-cache-stabi
 import { decodeReasoningEnvelope, encodeReasoningEnvelope, OCX_REASONING_PREFIX } from "../responses/reasoning-envelope";
 import { inlineDocumentMarker } from "../responses/inline-document";
 import { createTranslatorBudget, type TranslatorBudget } from "../lib/translator-budget";
+import { collectAnthropicCacheTtls } from "../adapters/anthropic/cache-retention";
 
 
 
@@ -390,34 +391,19 @@ export type ClaudeCacheKeySource = "metadata" | "system" | null;
 /**
  * The translated lane places its own prompt-cache breakpoints, so the caller's are dropped;
  * their TTL is the one thing worth keeping. When every caller breakpoint asks for `ttl: "1h"`
- * (Claude Code on a subscription marks them so) this maps to `cacheRetention: "long"`. A mixed
- * caller (1h prefix, 5m tail) stays on the default: "long" also makes the moving per-turn
- * breakpoint 1h, which bills writes the caller asked to keep at the 5m rate at the 1h rate.
- * Read out of body: the Responses body has no field for it.
+ * (Claude Code on a subscription marks them so) this maps to `cacheRetention: "long"`. A caller
+ * that pins any breakpoint to an explicit non-1h TTL ("5m") maps to "short": "long" would also
+ * make the moving per-turn breakpoint 1h and bill writes the caller asked to keep at 5m at the
+ * 1h rate. Breakpoints without a TTL express no preference, so they fall through to the
+ * destination default (1h on first-party Anthropic). Read out of body: the Responses body has
+ * no field for it.
  */
-export function callerCacheRetention(raw: unknown): "long" | undefined {
-  if (!isRec(raw)) return undefined;
+export function callerCacheRetention(raw: unknown): "long" | "short" | undefined {
   // Top-level automatic caching is a breakpoint too, and content blocks nest (tool_result,
-  // search_result, document sources), so every block container is walked. Tool inputs and
-  // schemas are caller data, not blocks: a `cache_control` key there is not a breakpoint.
-  const ttls: unknown[] = [];
-  const visit = (node: unknown, depth: number): void => {
-    if (depth > 16) return;
-    if (Array.isArray(node)) { for (const item of node) visit(item, depth + 1); return; }
-    if (!isRec(node)) return;
-    if (isRec(node.cache_control)) ttls.push(node.cache_control.ttl);
-    for (const [key, value] of Object.entries(node)) {
-      if (key !== "cache_control" && key !== "input" && key !== "input_schema"
-        && (Array.isArray(value) || isRec(value))) visit(value, depth + 1);
-    }
-  };
-  if (isRec(raw.cache_control)) ttls.push(raw.cache_control.ttl);
-  visit(raw.system, 0);
-  visit(raw.tools, 0);
-  visit(raw.messages, 0);
-  return ttls.length > 0 && ttls.every(ttl => ttl === "1h")
-    ? "long"
-    : undefined;
+  // search_result, document sources), so every block container is walked.
+  const ttls = collectAnthropicCacheTtls(raw);
+  if (ttls.some(ttl => ttl !== undefined && ttl !== "1h")) return "short";
+  return ttls.length > 0 && ttls.every(ttl => ttl === "1h") ? "long" : undefined;
 }
 
 export interface ClaudeInboundTranslation {

package/src/claude/outbound.ts

@@ -156,6 +156,8 @@ export function anthropicUsage(usage: unknown, webSearchRequests = 0): Rec {
   const details = isRec(u.input_tokens_details) ? u.input_tokens_details : {};
   const cached = typeof details.cached_tokens === "number" ? details.cached_tokens : 0;
   const cacheWrite = typeof details.cache_write_tokens === "number" ? details.cache_write_tokens : 0;
+  const cacheWrite1h = typeof details.cache_write_1h_tokens === "number"
+    ? Math.max(0, Math.min(details.cache_write_1h_tokens, cacheWrite)) : undefined;
   const input = typeof u.input_tokens === "number" ? u.input_tokens : 0;
   const output = typeof u.output_tokens === "number" ? u.output_tokens : 0;
   return {
@@ -163,6 +165,9 @@ export function anthropicUsage(usage: unknown, webSearchRequests = 0): Rec {
     output_tokens: output,
     cache_read_input_tokens: cached,
     cache_creation_input_tokens: cacheWrite,
+    ...(cacheWrite1h !== undefined
+      ? { cache_creation: { ephemeral_5m_input_tokens: cacheWrite - cacheWrite1h, ephemeral_1h_input_tokens: cacheWrite1h } }
+      : {}),
     // Only successful searches are billed/counted (Anthropic contract; Claude Code cost accounting).
     ...(webSearchRequests > 0 ? { server_tool_use: { web_search_requests: webSearchRequests } } : {}),
   };

package/src/cli/account-api.ts

@@ -16,6 +16,7 @@ import { projectApiKeyQuotaRows } from "./account-key-quota";
 import { projectAccountHealth } from "./account-next-actions";
 import type { OAuthHealthLabel } from "../oauth/health";
 
+import { accountPauseDetailsSchema } from "../config/schema/account-auto-pause";
 export type AccountType = "codex" | "oauth" | "api-key";
 
 export interface AccountRow {
@@ -61,6 +62,7 @@ export interface AccountRow {
    * human listing (#2703).
    */
   paused?: boolean;
+  pauseDetails?: import("../types/account-auto-pause").AccountPauseDetails;
 }
 
 export type ClassifyResult = { type: AccountType } | { error: string };
@@ -342,6 +344,7 @@ interface CodexAccountDto {
   quota?: CodexQuotaDto | null;
   quotaRefresh?: unknown;
   paused?: boolean;
+  pauseDetails?: import("../types/account-auto-pause").AccountPauseDetails;
 }
 
 function projectQuota(quota: CodexQuotaDto | null | undefined): CodexQuotaDto | null {
@@ -415,6 +418,8 @@ export async function fetchCodexRows(
       ? a.autoSwitchThresholdOverride
       : null,
     paused: a.paused === true,
+    // Unknown display details are dropped defensively; the pause state above is retained.
+    pauseDetails: accountPauseDetailsSchema.safeParse(a.pauseDetails).data,
     ...(includeQuota ? {
       quota: projectQuota(a.quota),
       quotaRefresh: projectCodexQuotaRefreshOutcome(a.quotaRefresh),
@@ -432,6 +437,7 @@ interface OAuthAccountDto {
   healthLabel?: unknown;
   /** Present only for providers that support operator pause (generic OAuth pools). */
   paused?: boolean;
+  pauseDetails?: import("../types/account-auto-pause").AccountPauseDetails;
   autoSwitchThresholdOverride?: number | null;
   needsReauthReason?: "verify_account";
   autoSelectable?: boolean;
@@ -475,7 +481,8 @@ async function fetchOAuthRows(
     active: a.active ?? a.id === activeId,
     needsReauth: a.needsReauth,
     ...projectAccountHealth(a, name, a.id),
-    ...(a.paused === true ? { paused: true } : {}),
+    // Unknown display details are dropped defensively; paused remains authoritative.
+    ...(a.paused === true ? { paused: true, pauseDetails: accountPauseDetailsSchema.safeParse(a.pauseDetails).data } : {}),
     ...(isAnthropicOAuthInstance(name) && Object.hasOwn(a, "autoSwitchThresholdOverride") ? { autoSwitchThresholdOverride: a.autoSwitchThresholdOverride } : {}),
     ...(a.needsReauthReason === "verify_account" ? { needsReauthReason: a.needsReauthReason } : {}),
     ...(name === "kiro" && typeof a.autoSelectable === "boolean"
@@ -495,6 +502,8 @@ async function fetchOAuthRows(
 }
 
 interface ApiKeyDto {
+  disabled?: boolean;
+  pauseDetails?: import("../types/account-auto-pause").AccountPauseDetails;
   id: string;
   label?: string;
   masked?: string;
@@ -523,6 +532,9 @@ async function fetchKeyRows(deps: AccountDeps, baseUrl: string, name: string, qu
     label: k.label ?? k.masked,
     masked: k.masked,
     active: k.active ?? k.id === activeId,
+    paused: k.disabled === true,
+    // Unknown display details are dropped defensively; disabled still keeps the key paused.
+    pauseDetails: accountPauseDetailsSchema.safeParse(k.pauseDetails).data,
   }));
   return { rows, activeId, status: 200 };
 }

package/src/cli/account-extended.ts

@@ -260,7 +260,7 @@ function resetIso(value: number | undefined): string | null {
 
 function refreshLine(row: FamilyRows["rows"][number]): string {
   const parts = [row.id === MAIN_ID ? "main" : row.id, row.email, row.plan];
-  if (row.paused) parts.push("paused");
+  if (row.paused) parts.push(row.pauseDetails ? `paused(${row.pauseDetails.reason})` : "paused");
   // Was a second quota dialect: it gated the whole block on weekly/monthly, so an account
   // reporting only a 5h window printed `quota: unknown` while `quotaParts` five lines below
   // rendered the same data correctly for the provider path (#2703). Two halves of one file
@@ -786,7 +786,7 @@ export async function cmdPriority(args: string[], deps: AccountDeps): Promise<nu
   return 0;
 }
 
-function resolveGenericOAuthAccountTarget(accounts: unknown[], requested: string): { id: string } | { error: string } {
+function resolveGenericOAuthAccountTarget(accounts: unknown[], requested: string, kind: "OAuth" | "API key" = "OAuth"): { id: string } | { error: string } {
   const rows = accounts.filter((value): value is { id: string; alias?: unknown } =>
     typeof value === "object" && value !== null && typeof (value as { id?: unknown }).id === "string",
   );
@@ -797,10 +797,10 @@ function resolveGenericOAuthAccountTarget(accounts: unknown[], requested: string
     : rows.filter(account => typeof account.alias === "string" && account.alias.toLowerCase() === requested.toLowerCase());
   if (matches.length === 1) return { id: matches[0]!.id };
   if (matches.length > 1) return { error: `alias "${requested}" names ${matches.length} accounts; use the account id` };
-  return { error: `Account not found: no OAuth account has the id or alias "${requested}"` };
+  return { error: `Account not found: no ${kind} account has the id or alias "${requested}"` };
 }
 
-/** Pause or resume a Codex or OAuth provider account, including Anthropic. */
+/** Pause or resume a Codex, OAuth, or API-key pool account. */
 export async function cmdPause(args: string[], deps: AccountDeps, paused: boolean): Promise<number> {
   const wantsJson = flag(args, "--json");
   const name = args.shift();
@@ -839,8 +839,20 @@ export async function cmdPause(args: string[], deps: AccountDeps, paused: boolea
     return 0;
   }
 
+  if (classified.type === "api-key") {
+    const rows = await fetchRows(deps, baseUrl, name, "api-key");
+    if (rows.status === 0) return proxyUnreachable(rows.transportError);
+    if (rows.status !== 200) return apiError(rows.errorJson ?? {}, "failed to list API key accounts", rows.status);
+    const target = resolveGenericOAuthAccountTarget(rows.rows.map(row => ({ id: row.id, alias: row.label })), requestedId, "API key");
+    if ("error" in target) return usage(`Error: ${target.error}`);
+    const result = await apiJson(deps, baseUrl, "PUT", "/api/providers/keys/pause", { name, id: target.id, paused });
+    if (result.status === 0) return proxyUnreachable(result.transportError);
+    if (result.status !== 200) return apiError(result.json, `failed to ${verb} account`, result.status);
+    console.log(wantsJson ? JSON.stringify({ ok: true, provider: name, id: target.id, paused }, null, 2) : `${name}: account ${paused ? "paused" : "resumed"}`);
+    return 0;
+  }
   if (classified.type !== "codex") {
-    return usage(`Error: ${verb} applies to the openai Codex account pool or a generic OAuth provider`);
+    return usage(`Error: ${verb} applies to the openai Codex account pool, a generic OAuth provider, or an API-key pool`);
   }
   const target = await resolveCodexAccountTarget(deps, baseUrl, requestedId);
   if ("networkDown" in target) return proxyUnreachable(target.transportError);

package/src/cli/account-key-quota.ts

@@ -2,6 +2,7 @@
 import { parseQuotaFailureCode, type AccountQuotaFields, type ProviderQuota, type ProviderQuotaWindow, type ProviderQuotaCreditsUsd } from "../providers/quota-types";
 import { terminalSafeText } from "./runtime-api";
 import type { AccountRow, FamilyRows } from "./account-api";
+import { accountPauseDetailsSchema } from "../config/schema/account-auto-pause";
 
 function record(value: unknown): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Malformed API-key quota response.");
@@ -88,7 +89,9 @@ export function projectApiKeyQuotaRows(value: unknown, provider: string): Family
     }
     const masked = optionalString(row, "masked");
     return { provider, type: "api-key", id, label: optionalString(row, "label") ?? masked,
-      masked, active: optionalBoolean(row, "active") ?? id === activeId, ...fields };
+      masked, active: optionalBoolean(row, "active") ?? id === activeId,
+      // Same projection as the plain key listing: disabled keeps the key paused, unknown details drop.
+      paused: row.disabled === true, pauseDetails: accountPauseDetailsSchema.safeParse(row.pauseDetails).data, ...fields };
   });
   return { rows, activeId, status: 200 };
 }

package/src/cli/account.ts

@@ -119,7 +119,7 @@ function statusText(row: AccountRow): string {
   // `paused` leads, and does NOT replace `selected`. A paused-but-selected account is the
   // state an operator most needs named -- requests route to it while the pool believes it is
   // held out -- so printing only one of the two would hide exactly the confusing case (#2703).
-  if (row.paused) parts.push("paused");
+  if (row.paused) parts.push(row.pauseDetails ? `paused(${row.pauseDetails.reason})` : "paused");
   if (row.active) parts.push(row.type === "codex" ? "selected" : "active");
   if (row.needsReauth && !(row.provider === "kiro" && row.skipReason === "needs_reauth")) {
     parts.push(row.needsReauthReason === "verify_account" ? "needs-reauth(verify)" : "needs-reauth");

package/src/cli/capabilities-agents-routing.ts

@@ -3,15 +3,15 @@ import type { Capability } from "./capability-types";
 export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
   {
     command: ["message", "sessions"],
-    summary: "Discover already-loaded local Codex sessions without reading conversation history.",
-    routes: [], flags: [{ name: "--json", value: "boolean", summary: "Emit a versioned local session directory." }],
+    summary: "Discover already-loaded Codex sessions locally or on an explicitly enrolled peer.",
+    routes: [], flags: [{ name: "--json", value: "boolean", summary: "Emit a versioned session directory." }, { name: "--host", value: "string", summary: "Exact enrolled peer alias or machine UUID; requires a live foreground owner." }],
     mutates: false, json: "envelope",
-    bannerLines: ["ocx message <sub>           Loaded local Codex sessions and queued peer messages (sessions|send)"],
-    details: ["Linux/macOS Unix socket only. Uses effective CODEX_HOME; starts no daemon and returns no partial directory."],
+    bannerLines: ["ocx message <sub>           Codex queued messages, explicit SSH peers and foreground ownership"],
+    details: ["Linux/macOS only. Local discovery uses the effective CODEX_HOME Unix socket; --host uses the live foreground owner's authenticated loopback route. Starts no daemon and returns no partial directory."],
   },
   {
     command: ["message", "send"],
-    summary: "Submit one correlated peer message to an exact loaded local Codex destination.",
+    summary: "Submit one correlated peer message to an exact loaded Codex destination.",
     routes: [], mutates: true, json: "envelope",
     flags: [
       { name: "--thread", value: "string", summary: "Exact loaded UUID; choose this or --name." },
@@ -20,10 +20,11 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
       { name: "--kind", value: "string", summary: "request (default), response or notification." },
       { name: "--in-reply-to", value: "string", summary: "Request message UUID; required only for a response." },
       { name: "--json", value: "boolean", summary: "Emit a receipt with not_sent, queued or unknown status." },
+      { name: "--host", value: "string", summary: "Exact enrolled peer alias or machine UUID; omit for the unchanged local path." },
     ],
     details: ["Requires daemon support for experimental thread/queue/add. Sender context comes from CODEX_THREAD_ID, not an authentication claim.",
       "queued means submitted, not processed. unknown must not be replayed; no automatic retry, daemon start or thread resume.",
-      "Exit 0: queued; 1: not sent; 3: unknown; 64: invalid usage. No remote/Claude transport or skill installation."],
+      "Exit 0: queued; 1: not sent; 3: unknown; 64: invalid usage. No Claude transport, native lifecycle mutation or skill installation."],
   },
   {
     command: ["advisor"],
@@ -46,6 +47,42 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
     ],
   },
 
+  {
+    command: ["message", "enable"], summary: "Explicitly enable private remote messaging state, without starting a listener.", routes: [],
+    flags: [{ name: "--port", value: "number", summary: "Unprivileged IPv4-loopback port; defaults to 39176 on first enable." },
+      { name: "--json", value: "boolean", summary: "Emit configuration without credentials." }], mutates: true, json: "envelope",
+  },
+  { command: ["message", "disable"], summary: "Disable remote admission and retire the foreground owner generation.", routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit safe configuration." }], mutates: true, json: "envelope" },
+  { command: ["message", "status"], summary: "Read enabled, running and leased/initiated route states without activation.", routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit safe configuration and owner observations." }], mutates: false, json: "envelope" },
+  { command: ["message", "serve"], summary: "Own a foreground listener and optional duplex SSH peer routes; no automatic reconnect.", routes: [],
+    flags: [{ name: "--host", value: "string", summary: "Exact initiating peer; repeat for at most four distinct peers." },
+      { name: "--json", value: "boolean", summary: "Emit the startup observation without credentials." }], mutates: true, json: "envelope" },
+  { command: ["message", "hosts", "probe"], summary: "Offer an SSH host fingerprint without enrollment or persistent changes.", routes: [],
+    flags: [{ name: "--ssh", value: "string", required: true, summary: "OpenSSH destination/alias." },
+      { name: "--json", value: "boolean", summary: "Emit the offered fingerprint." }], mutates: false, json: "envelope" },
+  { command: ["message", "hosts", "add"], usage: "ocx message hosts add <alias> --ssh <destination> --fingerprint <SHA256> [--json]",
+    summary: "Enroll outbound delivery and correlated return replies after SSH fingerprint confirmation.", routes: [],
+    flags: [{ name: "--ssh", value: "string", required: true, summary: "OpenSSH destination/alias." },
+      { name: "--fingerprint", value: "string", required: true, summary: "Explicitly confirmed offered SSH host-key fingerprint." },
+      { name: "--json", value: "boolean", summary: "Emit enrollment metadata, never credentials." }], mutates: true, json: "envelope" },
+  { command: ["message", "hosts", "allow-inbound"], usage: "ocx message hosts allow-inbound <alias-or-machine-uuid> [--json]",
+    summary: "Explicitly allow this enrolled peer to send any message kind to local loaded sessions.", routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the local inbound grant, without credentials." }], mutates: true, json: "envelope" },
+  { command: ["message", "hosts", "deny-inbound"], usage: "ocx message hosts deny-inbound <alias-or-machine-uuid> [--json]",
+    summary: "Restrict this peer to correlated replies on locally opened reply routes.", routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the narrowed local inbound grant." }], mutates: true, json: "envelope" },
+  { command: ["message", "hosts", "list"], summary: "List exact peer identities without credentials or listener activation.", routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit safe peer metadata." }], mutates: false, json: "envelope" },
+  { command: ["message", "hosts", "remove"], usage: "ocx message hosts remove <alias-or-machine-uuid> [--transaction <uuid>] [--json]",
+    summary: "Revoke local admission first and report any unconfirmed remote cleanup explicitly.", routes: [],
+    flags: [{ name: "--transaction", value: "string", summary: "Remove only this exact enrollment; refuse a replacement transaction." },
+      { name: "--json", value: "boolean", summary: "Emit local and remote revocation outcomes." }], mutates: true, json: "envelope" },
+  { command: ["message", "hosts", "abandon"], usage: "ocx message hosts abandon --transaction <uuid> [--json]",
+    summary: "Abandon an exact pending local enrollment; remote cleanup remains unconfirmed (exit 3).", routes: [],
+    flags: [{ name: "--transaction", value: "string", required: true, summary: "Exact pending UUID from hosts list or status; never an alias." },
+      { name: "--json", value: "boolean", summary: "Emit local abandonment and explicit remote-cleanup guidance." }], mutates: true, json: "envelope" },
   {
     command: ["agent", "status"],
     usage: "ocx agent status [--json]",
@@ -298,10 +335,10 @@ export const AGENT_ROUTING_CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["combo","set"],
-    usage: "ocx combo set <id> [--targets <provider/model[:weight],...> | --targets-file <FILE|->] [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->] [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->] [--alias <name|->] [--native-alias [on|off]] [--allow-metered-targets <on|off>] [--display-name <label|->] [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->] [--rename-from <id>] [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>] [--json]",
+    usage: "ocx combo set <id> [--targets <provider/model[:weight],...> | --targets-file <FILE|->] [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->] [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->] [--alias <name|->] [--native-alias [on|off]] [--allow-metered-targets <on|off>] [--display-name <label|->] [--description <text|->] [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->] [--decision-quota-signals <on|off|->] [--decision-quota-tiers <JSON|->] [--rename-from <id>] [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>] [--json]",
     summary: "Create, update or rename a combo.",
     routes: [{"method":"GET","path":"/api/combos"},{"method":"PUT","path":"/api/combos"}],
-    flags: [{"name":"--allow-metered-targets","value":"string","summary":"on grants operator consent to metered targets only on a loopback-only proxy; off clears it."},{"name":"--targets","value":"string","summary":"Ordered provider/model[:weight] list; required for creation."},{"name":"--strategy","value":"string","summary":"Routing strategy."},{"name":"--sticky","value":"string","summary":"Round-robin limit 1-100; - resets."},{"name":"--effort","value":"string","summary":"Default effort; - clears."},{"name":"--effort-mode","value":"string","summary":"fallback or force; - resets to fallback."},{"name":"--alias","value":"string","summary":"Alias; - clears."},{"name":"--display-name","value":"string","summary":"Label; - clears."},{"name":"--decision-provider","value":"string","summary":"JEV provider; - clears."},{"name":"--decision-model","value":"string","summary":"JEV route; - clears; exclusive with provider."},{"name":"--decision-timeout","value":"string","summary":"JEV deadline 1000-120000 ms; - clears."},{"name":"--rename-from","value":"string","summary":"Existing combo ID to rename."},{"name":"--json","value":"boolean","summary":"Emit structured JSON."},{"name":"--native-alias","value":"string","summary":"Bare legacy flag means on; explicit on/off preserves presence, including false."},{"name":"--targets-file","value":"string","summary":"Bounded ordered target JSON array, exclusive with --targets; preserves effort/profile/last-resort metadata."},{"name":"--image-input","value":"string","summary":"auto or disabled; explicit auto clears the previous disabled choice."},{"name":"--reasoning-effort-mode","value":"string","summary":"strict or adaptive, distinct from --effort-mode fallback/force."}],
+    flags: [{"name":"--allow-metered-targets","value":"string","summary":"on grants operator consent to metered targets only on a loopback-only proxy; off clears it."},{"name":"--targets","value":"string","summary":"Ordered provider/model[:weight] list; required for creation."},{"name":"--strategy","value":"string","summary":"Routing strategy."},{"name":"--sticky","value":"string","summary":"Round-robin limit 1-100; - resets."},{"name":"--effort","value":"string","summary":"Default effort; - clears."},{"name":"--effort-mode","value":"string","summary":"fallback or force; - resets to fallback."},{"name":"--alias","value":"string","summary":"Alias; - clears."},{"name":"--display-name","value":"string","summary":"Label; - clears."},{"name":"--description","value":"string","summary":"Catalog row description; - clears."},{"name":"--decision-provider","value":"string","summary":"JEV provider; - clears."},{"name":"--decision-model","value":"string","summary":"JEV route; - clears; exclusive with provider."},{"name":"--decision-timeout","value":"string","summary":"JEV deadline 1000-120000 ms; - clears."},{"name":"--decision-quota-signals","value":"string","summary":"JEV advisory quota on/off; - clears."},{"name":"--decision-quota-tiers","value":"string","summary":"Partial JSON thresholds; - clears."},{"name":"--rename-from","value":"string","summary":"Existing combo ID to rename."},{"name":"--json","value":"boolean","summary":"Emit structured JSON."},{"name":"--native-alias","value":"string","summary":"Bare legacy flag means on; explicit on/off preserves presence, including false."},{"name":"--targets-file","value":"string","summary":"Bounded ordered target JSON array, exclusive with --targets; preserves effort/profile/last-resort metadata."},{"name":"--image-input","value":"string","summary":"auto or disabled; explicit auto clears the previous disabled choice."},{"name":"--reasoning-effort-mode","value":"string","summary":"strict or adaptive, distinct from --effort-mode fallback/force."}],
     mutates: true,
     json: "payload",
     details: ["create and update are aliases of set. Existing fields are read before writing; --targets replaces targets.","force overrides valid client effort and may increase cost and latency.","Only the implemented target grammar is supported; full GUI target metadata and routing-profile writes are separate tasks.","New file/flag conflicts refuse before transport. Partial edits preserve target metadata; explicit false/default values override server carry. Turning a native alias off may also require clearing its incompatible alias.","Read/merge/write uses one target and remains an upsert without revision CAS. Saved-but-incomplete catalog outcomes return nonzero with their receipt."],

package/src/cli/capabilities-base.ts

@@ -340,18 +340,18 @@ export const CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["account","pause"],
-    summary: "Exclude one account in a Codex, Anthropic or supported generic OAuth pool from automatic selection.",
-    routes: [{"method":"GET","path":"/api/codex-auth/accounts"},{"method":"PUT","path":"/api/codex-auth/accounts/pause"},{"method":"GET","path":"/api/oauth/accounts"},{"method":"PUT","path":"/api/oauth/accounts/pause"}],
+    summary: "Exclude one account in a Codex, Anthropic, generic OAuth or API-key pool from automatic selection.",
+    routes: [{"method":"GET","path":"/api/codex-auth/accounts"},{"method":"PUT","path":"/api/codex-auth/accounts/pause"},{"method":"GET","path":"/api/oauth/accounts"},{"method":"PUT","path":"/api/oauth/accounts/pause"},{"method":"GET","path":"/api/providers/keys"},{"method":"PUT","path":"/api/providers/keys/pause"}],
     flags: [{"name":"--json","value":"boolean","summary":"Emit the pause result as JSON."}],
     mutates: true,
     json: "envelope",
-    details: ["Codex pause unbinds pinned threads and selects a fallback when possible; with no fallback, a paused-but-selected Codex account still receives requests. Anthropic and generic OAuth pause exclude the account from new requests, failover and refresh, and an all-paused pool answers 403. Credentials and health are preserved; already-sent turns are not cancelled."],
+    details: ["Codex pause unbinds pinned threads and selects a fallback when possible; with no fallback, the paused account cannot dispatch until resumed. Anthropic and generic OAuth pause exclude the account from new requests, failover and refresh, and an all-paused pool answers 403. Credentials and health are preserved; already-sent turns are not cancelled."],
     usage: "ocx account pause <provider> <account-id|alias|main> [--json]",
   },
   {
     command: ["account","resume"],
-    summary: "Return a paused account to a Codex, Anthropic or supported generic OAuth pool.",
-    routes: [{"method":"GET","path":"/api/codex-auth/accounts"},{"method":"PUT","path":"/api/codex-auth/accounts/pause"},{"method":"GET","path":"/api/oauth/accounts"},{"method":"PUT","path":"/api/oauth/accounts/pause"}],
+    summary: "Return a paused account to a Codex, Anthropic, generic OAuth or API-key pool.",
+    routes: [{"method":"GET","path":"/api/codex-auth/accounts"},{"method":"PUT","path":"/api/codex-auth/accounts/pause"},{"method":"GET","path":"/api/oauth/accounts"},{"method":"PUT","path":"/api/oauth/accounts/pause"},{"method":"GET","path":"/api/providers/keys"},{"method":"PUT","path":"/api/providers/keys/pause"}],
     flags: [{"name":"--json","value":"boolean","summary":"Emit the resume result as JSON."}],
     mutates: true,
     json: "envelope",

package/src/cli/capabilities-provider-models.ts

@@ -49,10 +49,11 @@ export const PROVIDER_MODEL_CAPABILITIES: readonly Capability[] = [
     details: ["At least one edit is required; only supplied fields are patched. update is an existing alias. Use provider show only for local state, not as proof of the live write.","Management errors use safe fixed provider diagnostics; catalog failures retain the saved receipt and a nonzero exit."],
   },
   {
-    command: ["provider", "test"], summary: "Probe a provider's live model discovery connectivity.",
-    usage: "ocx provider test <name> [--json]", routes: [{ method: "POST", path: "/api/providers/test" }], mutates: true, json: "payload",
-    flags: [{ name: "--json", value: "boolean", summary: "Emit the probe result." }],
-    details: ["May contact the upstream provider; requires operator intent to probe. Static catalogs can return applicable:false; failed connectivity exits nonzero."],
+    command: ["provider", "test"], summary: "Probe discovery connectivity or explicitly test one model completion.",
+    usage: "ocx provider test <name> [--model <id> [--yes]] [--json]",
+    routes: [{ method: "POST", path: "/api/providers/test" }, { method: "POST", path: "/api/providers/test-completion" }], mutates: true, json: "payload",
+    flags: [{ name: "--model", value: "string", summary: "Run one bounded completion for this model instead of discovery." }, { name: "--yes", value: "boolean", summary: "Confirm completion quota/cost; requires --model. Mandatory with --json or non-interactive input." }, { name: "--json", value: "boolean", summary: "Emit the probe result; completion warnings go to stderr." }],
+    details: ["Without --model, discovery behavior is unchanged; static catalogs can return applicable:false. Completion tests print a quota/cost warning and require a default-No terminal confirmation or --yes; cancellation exits 1 without a request.", "Completion output includes TTFT, total latency, upstream/wire model metadata and comparison. Metadata is not proof of model identity; mismatch still exits 0. Failed tests exit 1; non-applicable results exit 0."],
   },
   {
     command: ["provider", "quota"], summary: "Read provider quota reports, optionally refreshing them.",

package/src/cli/combo-result.ts

@@ -1,3 +1,4 @@
+import { normalizeJevQuotaTiers } from "../combos/jev-quota-config";
 import { parseComboTargets } from "./combo-input";
 import { printCatalogResult } from "./catalog-command-result";
 
@@ -7,7 +8,7 @@ const ENUMS: Readonly<Record<string, readonly (string | null)[]>> = {
   defaultEffortMode: ["fallback", "force"], reasoningEffortMode: ["strict", "adaptive"],
   imageInput: ["auto", "disabled"], cooldownWaitPolicy: ["before-last-resort"],
 };
-const STRINGS = new Set(["alias", "displayName", "decisionProvider", "decisionModel"]);
+const STRINGS = new Set(["alias", "displayName", "description", "decisionProvider", "decisionModel"]);
 const RANGES: Readonly<Record<string, readonly [number, number]>> = {
   stickyLimit: [1, 100], cooldownMs: [1, 600_000], waitForCooldownMs: [0, 600_000],
   decisionTimeoutMs: [1_000, 120_000],
@@ -33,7 +34,12 @@ function publicCombo(value: unknown): Record<string, unknown> {
     } else if (Object.hasOwn(RANGES, key)) {
       const [min, max] = RANGES[key]!;
       if (typeof child !== "number" || !Number.isSafeInteger(child) || child < min || child > max) invalid();
-    } else if (key === "nativeAlias" || key === "allowMeteredTargets") {
+    } else if (key === "decisionQuotaTiers") {
+      const tiers = normalizeJevQuotaTiers(child);
+      if (!tiers) invalid();
+      result[key] = tiers;
+      continue;
+    } else if (key === "nativeAlias" || key === "allowMeteredTargets" || key === "decisionQuotaSignals") {
       if (typeof child !== "boolean") invalid();
     } else invalid();
     result[key] = child;