@bitkyc08/opencodex 2.88.0 → 2.89.0

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;

package/src/cli/combo.ts

@@ -1,3 +1,4 @@
+import { normalizeJevQuotaTiers } from "../combos/jev-quota-config";
 import { JEV_DECISION_TIMEOUT_MAX_MS, JEV_DECISION_TIMEOUT_MIN_MS } from "../combos/types";
 import {
   CliUsageError,
@@ -24,8 +25,10 @@ const USAGE = `Usage:
       [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->]
       (force overrides valid client effort and can increase cost/latency) [--alias <name|->]
       [--native-alias [on|off]] [--allow-metered-targets <on|off>] [--display-name <label|->]
+      [--description <text|->]
       [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>]
       [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->]
+      [--decision-quota-signals <on|off|->] [--decision-quota-tiers <JSON|->]
       (jev only; the provider must be a configured jev-decision row)
       [--rename-from <id>] [--json]
   ocx combo stats <id> [--range <7d|30d|all>] [--json]
@@ -80,6 +83,7 @@ async function show(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(combo, wantsJson);
 }
 
+/** Handle `ocx combo set`: parse the combo id and flags (including `--decision-quota-signals` and `--decision-quota-tiers`), then create or update the combo through the management API. */
 async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   const args = [...argv];
   const id = args.shift()?.trim();
@@ -118,6 +122,7 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   const alias = takeOption(args, "--alias");
 
   const displayName = takeOption(args, "--display-name");
+  const description = takeOption(args, "--description");
   const decisionProvider = takeOption(args, "--decision-provider");
   const decisionModel = takeOption(args, "--decision-model");
   if (decisionModel !== undefined && decisionModel !== "-" && decisionProvider !== undefined && decisionProvider !== "-") {
@@ -129,6 +134,13 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   if (decisionProvider !== undefined && decisionProvider !== "-" && strategy !== "jev") {
     throw new CliUsageError("--decision-provider applies only to the jev strategy", USAGE);
   }
+  const quotaSignals = takeOption(args, "--decision-quota-signals");
+  const quotaTiers = takeOption(args, "--decision-quota-tiers");
+  if (quotaSignals !== undefined && !["on", "off", "-"].includes(quotaSignals)) throw new CliUsageError("--decision-quota-signals must be on, off or -", USAGE);
+  let parsedQuotaTiers: ReturnType<typeof normalizeJevQuotaTiers> | null;
+  try { parsedQuotaTiers = quotaTiers === undefined || quotaTiers === "-" ? null : normalizeJevQuotaTiers(JSON.parse(quotaTiers)); } catch { throw new CliUsageError("invalid --decision-quota-tiers JSON", USAGE); }
+  if (quotaTiers !== undefined && quotaTiers !== "-" && !parsedQuotaTiers) throw new CliUsageError("quota tiers must be finite 0..100 and strictly ascending", USAGE);
+  if (strategy !== "jev" && (quotaSignals !== undefined && quotaSignals !== "-" || quotaTiers !== undefined && quotaTiers !== "-")) throw new CliUsageError("quota settings apply only to jev", USAGE);
   const decisionTimeout = takeOption(args, "--decision-timeout");
   let decisionTimeoutMs: number | null | undefined;
   if (decisionTimeout !== undefined) {
@@ -164,15 +176,20 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   if (additional.imageInput !== undefined) combo.imageInput = additional.imageInput;
   if (additional.reasoningEffortMode !== undefined) combo.reasoningEffortMode = additional.reasoningEffortMode;
   if (displayName !== undefined) combo.displayName = displayName === "-" ? "" : displayName;
+  if (description !== undefined) combo.description = description === "-" ? "" : description;
   if (decisionProvider !== undefined) combo.decisionProvider = decisionProvider === "-" ? null : decisionProvider;
   if (decisionModel !== undefined) combo.decisionModel = decisionModel === "-" ? null : decisionModel;
   if (decisionProvider !== undefined && decisionProvider !== "-") combo.decisionModel = null;
   if (decisionModel !== undefined && decisionModel !== "-") combo.decisionProvider = null;
   if (decisionTimeoutMs !== undefined) combo.decisionTimeoutMs = decisionTimeoutMs;
+  if (quotaSignals !== undefined) combo.decisionQuotaSignals = quotaSignals === "-" ? null : quotaSignals === "on";
+  if (quotaTiers !== undefined) combo.decisionQuotaTiers = parsedQuotaTiers;
   if (strategy !== "jev") {
     delete combo.decisionProvider;
     delete combo.decisionModel;
     delete combo.decisionTimeoutMs;
+    delete combo.decisionQuotaSignals;
+    delete combo.decisionQuotaTiers;
   }
   const current = partialCurrent ?? await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", { redirect: "error" }, deps);
   const existing = (current.combos ?? []).find(row => row.id === (renameFrom ?? id));

package/src/cli/help.ts

@@ -79,7 +79,7 @@ Usage:
   ocx alias <sub>             Short names for providers and models (list, set, rm, defaults)
   ocx combo <sub>             Combo routing strategies and failover
   ocx agent <sub>             Subagents, injection, effort caps, and sidecars
-  ocx message <sub>           Loaded local Codex sessions and queued peer messages (sessions|send)
+  ocx message <sub>           Codex queued messages, explicit SSH peers and foreground ownership
   ocx effort [sub]            Inspect and configure reasoning effort caps and defaults
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
   ocx inspect <sub>           Effective config, catalog, analytics, pacing, client-config

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);