@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/link.ts

@@ -11,7 +11,9 @@ import {
   runtimeBaseUrl,
   runtimeRequest,
   takeIntegerOption,
+  takeFlag,
   takeJsonFlag,
+  printData,
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
@@ -20,7 +22,9 @@ export const LINK_USAGE = `Usage:
   ocx link port [--json]
   ocx link issue --alias <alias> --tunnel-port <port> [--json]
   ocx link status [--json]
-  ocx link revoke --link-id <id> [--json]`;
+  ocx link revoke --link-id <id> [--force --yes] [--json]
+
+Forced revoke skips remote cleanup. Run ocx disconnect on the remote client.`;
 
 type LinkState = "connecting" | "connected" | "reconnecting" | "failed" | "idle";
 type ListenerState = "off" | "listening" | "failed";
@@ -258,19 +262,43 @@ async function runStatus(args: string[], deps: LinkCliDeps): Promise<void> {
 }
 
 async function runRevoke(args: string[], deps: LinkCliDeps): Promise<void> {
-  takeJsonFlag(args);
+  const wantsJson = takeJsonFlag(args);
+  const force = takeFlag(args, "--force");
+  const confirmed = takeFlag(args, "--yes");
   const linkId = takeOption(args, "--link-id");
   if (!linkId || !LINK_ID.test(linkId)) throw new CliUsageError("revoke requires a valid --link-id", LINK_USAGE);
   rejectArgs(args, LINK_USAGE);
+  if (force && !confirmed) throw new CliUsageError("forced revoke skips remote cleanup; pass --yes to confirm", LINK_USAGE);
+  if (confirmed && !force) throw new CliUsageError("--yes requires --force", LINK_USAGE);
+  let remoteCleanup: "skipped" | "unverified" = "skipped";
   try {
-    const response = await linkRequest<unknown>(`/api/link/${encodeURIComponent(linkId)}`, { method: "DELETE" }, deps);
+    const response = await linkRequest<unknown>(`/api/link/${encodeURIComponent(linkId)}`, force ? {
+      method: "DELETE",
+      redirect: "error",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ force: true }),
+    } : { method: "DELETE" }, deps);
+    // Legacy revoke accepts an empty response; a forced receipt needs observed identity.
+    if (force && response === null) throw new Error("invalid link API response: revoke object");
     validateRevoke(response, linkId);
   } catch (error) {
     // Revoke is idempotent: a link the Home no longer has is already revoked, and a Child retrying
     // a join rollback depends on that answer being success. A 404 without this code comes from a
     // listener that does not serve the management API and stays a failure.
     const code = error instanceof RuntimeApiError && error.status === 404 ? errorCodeBody(error.body)?.error.code : undefined;
-    if (code !== "link_not_found") throw error;
+    if (code !== "link_not_found") {
+      if (force && !(error instanceof RuntimeApiError)) throw new Error("Forced link revoke failed; inspect link status before retrying.");
+      throw error;
+    }
+    remoteCleanup = "unverified";
+  }
+  if (force) {
+    const recovery = "Run ocx disconnect on the remote client.";
+    printData({ linkId, remoteCleanup, recovery }, wantsJson, [
+      remoteCleanup === "skipped" ? `Revoked ${linkId}; remote cleanup was skipped.` : `Link ${linkId} is already absent; remote cleanup is unverified.`,
+      recovery,
+    ]);
+    return;
   }
   console.log(JSON.stringify({ linkId }));
 }

package/src/cli/local-sync-result.ts

@@ -0,0 +1,41 @@
+import type { CodexSyncResult } from "../codex/sync";
+import { FOREIGN_CODEX_HOME_OWNER_MESSAGE, UNKNOWN_CODEX_HOME_OWNER_MESSAGE,
+  unbackedRoutedRemovalMessage } from "../codex/catalog/routed-removal";
+
+/** Safe local evidence; callers own required versus opportunistic sync policy. */
+export interface LocalSyncResult {
+  status: CodexSyncResult["status"] | "not-running" | "not-attempted" | "failed";
+  ok: boolean;
+  /** Only the catalog owner's fixed, path-free safety guidance; never a raw warning. */
+  warning?: string;
+  configApplied?: boolean;
+  catalog?: { exists: boolean; written: boolean; cacheSynced: boolean; converged: boolean };
+}
+
+/** Project only the catalog owner's path-free safety guidance, not arbitrary sync errors. */
+function catalogSafetyWarning(warning: string | undefined): string | undefined {
+  if (!warning) return undefined;
+  for (const message of [FOREIGN_CODEX_HOME_OWNER_MESSAGE, UNKNOWN_CODEX_HOME_OWNER_MESSAGE]) {
+    if (warning.startsWith(message)) return message;
+  }
+  const countText = /^Codex catalog left unchanged: this refresh would remove the routed models of (\d+) /.exec(warning)?.[1];
+  if (!countText) return undefined;
+  const count = Number(countText);
+  if (!Number.isSafeInteger(count) || count < 1) return undefined;
+  const message = unbackedRoutedRemovalMessage(count);
+  return warning.startsWith(message) ? message : undefined;
+}
+
+/** No discovery, sync, logging, private paths or raw warning/error projection. */
+export function projectLocalSyncResult(result: CodexSyncResult): LocalSyncResult {
+  const warning = catalogSafetyWarning(result.warning);
+  const converged = result.catalogExists && result.refreshOutcome !== "refused" && !warning;
+  return {
+    status: result.status,
+    ...(warning ? { warning } : {}),
+    ok: result.ok && (result.status === "skipped" || (result.status !== "refused" && converged)),
+    configApplied: result.status === "applied" && result.ok,
+    catalog: { exists: result.catalogExists, written: result.catalogWritten,
+      cacheSynced: result.cacheSynced, converged },
+  };
+}

package/src/cli/log-follow.ts

@@ -0,0 +1,84 @@
+import { decodeRequestLogCursor } from "../server/request-log-cursor";
+import { printData } from "./runtime-api";
+import { ObservationError, withObserveStream, type ObserveStreamDeps } from "./observe-stream";
+
+type LogRow = Record<string, unknown>;
+interface Poll { rows: LogRow[]; cursor: string | null; reset: boolean }
+
+function parsePoll(body: unknown, limit: number): Poll {
+  let rows: unknown;
+  let cursor: string | null = null;
+  let reset = false;
+  if (Array.isArray(body)) rows = body;
+  else if (body && typeof body === "object") {
+    const value = body as Record<string, unknown>;
+    if (Object.hasOwn(value, "cursor") || Object.hasOwn(value, "reset")) {
+      if (typeof value.cursor !== "string" || !decodeRequestLogCursor(value.cursor) || typeof value.reset !== "boolean") {
+        throw new ObservationError("Invalid log cursor response. Upgrade the runtime and restart follow.");
+      }
+      cursor = value.cursor;
+      reset = value.reset;
+      rows = value.logs;
+    } else {
+      for (const key of ["logs", "entries", "requests"]) {
+        if (Object.hasOwn(value, key)) { rows = value[key]; break; }
+      }
+    }
+  }
+  if (!Array.isArray(rows) || rows.length > limit || rows.some(row => !row || typeof row !== "object" || Array.isArray(row))) {
+    throw new ObservationError("Invalid log window. Check --limit and upgrade the runtime before restarting follow.");
+  }
+  return { rows: rows as LogRow[], cursor, reset };
+}
+
+/** Compare row occurrences, not request IDs: identical duplicates each consume one match. */
+function newOccurrences(previous: LogRow[], incoming: LogRow[]): LogRow[] {
+  const counts = new Map<string, number>();
+  for (const row of previous) {
+    const key = JSON.stringify(row);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return incoming.filter(row => {
+    const key = JSON.stringify(row);
+    const remaining = counts.get(key) ?? 0;
+    if (!remaining) return true;
+    counts.set(key, remaining - 1);
+    return false;
+  });
+}
+
+export async function followLogs(
+  options: { query: URLSearchParams; limit: number; jsonl: boolean; events: boolean; formatRow: (row: LogRow) => string },
+  deps: ObserveStreamDeps,
+): Promise<number> {
+  return withObserveStream(deps, async stream => {
+    let window: LogRow[] = [];
+    let cursor: string | null = null;
+    let initial = true;
+    while (true) {
+      const query = new URLSearchParams(options.query);
+      if (cursor !== null) query.set("cursor", cursor);
+      const poll = parsePoll(await stream.get("/api/logs", query), options.limit);
+      stream.signal.throwIfAborted();
+      const append = !initial && cursor !== null && poll.cursor !== null && !poll.reset;
+      const next = append ? [...window, ...poll.rows].slice(-options.limit) : poll.rows;
+      if (options.events) {
+        const changed = JSON.stringify(next) !== JSON.stringify(window);
+        if (initial || poll.reset || (append ? poll.rows.length > 0 : changed)) {
+          console.log(JSON.stringify({ schemaVersion: 1, type: append ? "append" : "snapshot", rows: poll.rows, cursor: poll.cursor, limit: options.limit }));
+        }
+      } else {
+        const emitted = append ? poll.rows : newOccurrences(window, next);
+        for (const row of emitted) {
+          stream.signal.throwIfAborted();
+          if (options.jsonl) console.log(JSON.stringify(row));
+          else printData(row, false, [options.formatRow(row)]);
+        }
+      }
+      window = next;
+      cursor = poll.cursor;
+      initial = false;
+      await stream.wait();
+    }
+  });
+}

package/src/cli/log-view-filter.ts

@@ -0,0 +1,146 @@
+/** GUI-equivalent selection within one bounded, observed request-log window. */
+import { parseProtocolTraceV1 } from "../protocols/dto";
+import { decodeRequestLogCursor } from "../server/request-log-cursor";
+import { matchesLogConversationId, normalizeLogConversationId, LOG_CONVERSATION_ID_INPUT_MAX } from "../server/request-log-conversation";
+import { CliUsageError, printData, runCliAction, takeFlag, takeOptionWithSyntax } from "./runtime-api";
+import { ObservationError, withObserveStream, type ObserveStreamDeps } from "./observe-stream";
+
+type LogRow = Record<string, unknown>;
+export interface LogViewFilterDeps extends ObserveStreamDeps { now?: () => number }
+const MAX_WINDOW = 2000;
+const WINDOWS = { all: undefined, "15m": 15 * 60_000, "1h": 60 * 60_000, "24h": 24 * 60 * 60_000 };
+
+function enumOption<T extends string>(args: string[], flag: string, choices: readonly T[], fallback: T): T {
+  const value = takeOptionWithSyntax(args, flag)?.value;
+  if (value === undefined) return fallback;
+  if (!choices.includes(value as T)) throw new CliUsageError(`${flag} must be ${choices.join("|")}`);
+  return value as T;
+}
+
+function numberOption(args: string[], flag: string, integer = false): number | undefined {
+  const raw = takeOptionWithSyntax(args, flag)?.value;
+  if (raw === undefined) return undefined;
+  const value = raw.trim() === "" ? NaN : Number(raw);
+  if (!Number.isFinite(value) || value < 0 || (integer && (!Number.isInteger(value) || value < 1 || value > MAX_WINDOW))) {
+    throw new CliUsageError(`${flag} must be ${integer ? "an integer between 1 and 2000" : "a finite nonnegative number"}`);
+  }
+  return value;
+}
+
+function parseOptions(argv: string[]) {
+  const args = [...argv];
+  const json = takeFlag(args, "--json"), jsonl = takeFlag(args, "--jsonl");
+  const surface = enumOption(args, "--surface", ["all", "codex", "claude", "grok"], "all");
+  const model = (takeOptionWithSyntax(args, "--model")?.value ?? "").trim().toLowerCase();
+  const provider = (takeOptionWithSyntax(args, "--provider")?.value ?? "").trim().toLowerCase();
+  const status = enumOption(args, "--status", ["all", "success", "errors"], "all");
+  const timeWindow = enumOption(args, "--time-window", ["all", "15m", "1h", "24h"], "all");
+  const protocolMode = enumOption(args, "--protocol-mode", ["all", "native", "translated", "legacy-bridge", "blocked", "none"], "all");
+  const minTokPerSec = numberOption(args, "--min-tok-per-sec");
+  const maxTokPerSec = numberOption(args, "--max-tok-per-sec");
+  const interceptedOnly = takeFlag(args, "--intercepted-only");
+  const conversation = takeOptionWithSyntax(args, "--conversation")?.value;
+  const alias = takeOptionWithSyntax(args, "--conversationId")?.value;
+  if (conversation !== undefined && alias !== undefined) throw new CliUsageError("Use only one conversation option");
+  const rawConversation = conversation ?? alias;
+  if (rawConversation !== undefined && (rawConversation.length > LOG_CONVERSATION_ID_INPUT_MAX
+    || /[\x00-\x1f\x7f-\x9f\u2028\u2029]/.test(rawConversation) || !normalizeLogConversationId(rawConversation))) {
+    throw new CliUsageError("Conversation must be a nonempty, control-free identifier of at most 4096 characters");
+  }
+  const scanLimit = numberOption(args, "--scan-limit", true) ?? MAX_WINDOW;
+  const limit = numberOption(args, "--limit", true) ?? 200;
+  if (args.length) throw new CliUsageError("Unknown or repeated option. Use ocx logs filter --help; follow/events are not supported");
+  if (json && jsonl) throw new CliUsageError("--json and --jsonl cannot be combined");
+  if (minTokPerSec !== undefined && maxTokPerSec !== undefined && minTokPerSec >= maxTokPerSec) {
+    throw new CliUsageError("--min-tok-per-sec must be less than --max-tok-per-sec");
+  }
+  return { json, jsonl, scanLimit, limit, filters: {
+    surface, model, provider, status, timeWindow, protocolMode, minTokPerSec, maxTokPerSec,
+    interceptedOnly, conversationId: rawConversation?.trim() ?? "",
+  } };
+}
+
+function record(value: unknown): value is LogRow {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseWindow(body: unknown, limit: number): { logs: LogRow[]; cursor: string | null } {
+  let rows: unknown = body;
+  let cursor: string | null = null;
+  if (record(body)) {
+    if (Object.hasOwn(body, "cursor") || Object.hasOwn(body, "reset")) {
+      if (typeof body.cursor !== "string" || !decodeRequestLogCursor(body.cursor) || typeof body.reset !== "boolean") {
+        throw new ObservationError("Invalid log cursor response. Upgrade the runtime and retry the command.");
+      }
+      cursor = body.cursor;
+      rows = body.logs;
+    } else {
+      for (const key of ["logs", "entries", "requests"]) {
+        if (Object.hasOwn(body, key)) { rows = body[key]; break; }
+      }
+    }
+  }
+  if (!Array.isArray(rows) || rows.length > limit || !rows.every(record)) {
+    throw new ObservationError("Invalid log window. Check --scan-limit and upgrade the runtime before retrying the command.");
+  }
+  return { logs: rows, cursor };
+}
+
+function normalized(value: unknown): string | undefined {
+  return typeof value === "string" ? value.trim().toLowerCase() : undefined;
+}
+
+function matches(row: LogRow, filters: ReturnType<typeof parseOptions>["filters"], now: number): boolean {
+  const { surface, status, protocolMode, model, provider, conversationId } = filters;
+  if (surface === "codex" && row.surface !== undefined) return false;
+  if (surface === "claude" && row.surface !== "claude" && row.surface !== "claude-desktop") return false;
+  if (surface === "grok" && row.surface !== "grok") return false;
+  if (filters.interceptedOnly && typeof row.shadowCallRewrittenFrom !== "string") return false;
+  if (protocolMode !== "all") {
+    const mode = parseProtocolTraceV1(row.protocolTrace)?.mode;
+    if (protocolMode === "none" ? mode !== undefined : mode !== protocolMode) return false;
+  }
+  if (conversationId && !matchesLogConversationId(typeof row.conversationId === "string" ? row.conversationId : undefined, conversationId)) return false;
+  if (status !== "all") {
+    if (typeof row.status !== "number" || !Number.isInteger(row.status)) return false;
+    if (status === "success" ? row.status < 200 || row.status >= 300 : row.status < 400 || row.status > 599) return false;
+  }
+  const attempts = Array.isArray(row.attempts) ? row.attempts.filter(record) : [];
+  if (model && ![row.model, row.resolvedModel, row.servedModel, ...attempts.map(attempt => attempt.model)].some(value => normalized(value) === model)) return false;
+  if (provider && ![row.provider, ...attempts.map(attempt => attempt.provider)].some(value => normalized(value) === provider)) return false;
+  const duration = WINDOWS[filters.timeWindow];
+  if (duration !== undefined && (typeof row.timestamp !== "number" || !Number.isFinite(row.timestamp) || row.timestamp < now - duration)) return false;
+  const metric = record(row.displayMetrics) ? row.displayMetrics.tokPerSecond : undefined;
+  const speed = record(metric) && metric.kind === "value" && typeof metric.value === "number" && Number.isFinite(metric.value) ? metric.value : undefined;
+  if (filters.minTokPerSec !== undefined && (speed === undefined || speed < filters.minTokPerSec)) return false;
+  if (filters.maxTokPerSec !== undefined && (speed === undefined || speed >= filters.maxTokPerSec)) return false;
+  return true;
+}
+
+/** argv starts after `logs filter`; the shared renderer escapes human row values. */
+export async function handleLogFilterCommand(
+  argv: string[], deps: LogViewFilterDeps, formatRow: (row: LogRow) => string,
+): Promise<number> {
+  let result = 0;
+  const parsingExit = await runCliAction(async () => {
+    const options = parseOptions(argv);
+    result = await withObserveStream(deps, async stream => {
+      const snapshot = parseWindow(await stream.get("/api/logs", new URLSearchParams({ limit: String(options.scanLimit) })), options.scanLimit);
+      stream.signal.throwIfAborted();
+      const now = (deps.now ?? Date.now)();
+      const selected = snapshot.logs.filter(row => matches(row, options.filters, now));
+      const logs = selected.slice(-options.limit);
+      const window = { scanLimit: options.scanLimit, loaded: snapshot.logs.length, matched: selected.length, returned: logs.length, limit: options.limit };
+      if (options.json) printData({ schemaVersion: 1, logs, cursor: snapshot.cursor, filters: options.filters, window }, true);
+      else if (options.jsonl) {
+        for (const row of logs) { stream.signal.throwIfAborted(); console.log(JSON.stringify(row)); }
+      } else {
+        printData(null, false, [
+          `${logs.length} returned / ${selected.length} matched / ${snapshot.logs.length} scanned (current window; scan limit ${options.scanLimit}, output limit ${options.limit}).`,
+          ...(logs.length ? logs.map(formatRow) : ["No matching logs in this window. Widen filters or increase --scan-limit to inspect a larger current window."]),
+        ]);
+      }
+    }, { kind: "snapshot", limitOption: "--scan-limit" });
+  });
+  return parsingExit || result;
+}

package/src/cli/logout-command.ts

@@ -0,0 +1,44 @@
+import { isValidProviderName } from "../config/provider-name";
+import { runCatalogAction } from "./catalog-command-result";
+import { CliUsageError, printData, runtimeBaseUrl, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
+
+export interface LogoutCommandDeps extends RuntimeApiDeps {
+  /** Atomic store disposition; test callers use a synthetic store only. */
+  removeCredential?: (provider: string) => Promise<"removed" | "not-found">;
+}
+
+/** Explicit target selection precedes all credential access; never fall back between targets. */
+export async function handleLogoutCommand(argv: string[], deps: LogoutCommandDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const json = takeFlag(args, "--json");
+    const live = takeFlag(args, "--live");
+    const provider = args.shift()?.trim().toLowerCase();
+    if (!provider || !isValidProviderName(provider) || args.length) {
+      throw new CliUsageError("Expected one provider and no unknown or repeated options.", "Usage: ocx logout <provider> [--live] [--json]");
+    }
+    if (live) {
+      const { isPublicOAuthProvider } = await import("../oauth");
+      if (!isPublicOAuthProvider(provider)) throw new CliUsageError("Live logout requires a public OAuth provider; Codex and native-main logout are not supported.");
+      const pinned = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
+      const data = await runtimeRequest<unknown>(`/api/oauth/logout?provider=${encodeURIComponent(provider)}`, {
+        method: "POST", redirect: "error",
+      }, pinned);
+      if (!data || typeof data !== "object" || Array.isArray(data) || (data as Record<string, unknown>).success !== true) {
+        throw new Error("Unverified logout result");
+      }
+      printData({ schemaVersion: 1, success: true, provider, live: true }, json, [`Logged out of ${provider} on the selected proxy.`]);
+      return 0;
+    }
+    const remove = deps.removeCredential ?? (await import("../oauth/store")).removeCredential;
+    const outcome = await remove(provider);
+    if (outcome === "not-found") {
+      if (json) printData({ schemaVersion: 1, ok: false, provider, removed: false, reason: "not_found" }, true);
+      else console.error(`No stored credential for '${provider}'.`);
+      return 4;
+    }
+    if (outcome !== "removed") throw new Error("Unverified local logout result");
+    printData({ schemaVersion: 1, ok: true, provider, removed: true }, json, [`Logged out of ${provider}.`]);
+    return 0;
+  });
+}

package/src/cli/model-picker-ordering.ts

@@ -0,0 +1,137 @@
+// Deliberate pure port of gui/src/model-picker-order.ts; test-only conformance guards drift.
+export type ModelPickerOrderMode = "default" | "alphabetical" | "provider" | "most-used" | "custom";
+export type SavedModelPickerOrderMode = Exclude<ModelPickerOrderMode, "default" | "custom">;
+export interface ModelPickerUsage {
+  provider: string;
+  model: string;
+  resolvedModel?: string;
+  requests: number;
+}
+export interface PickerModelIdentity { provider: string; id: string; namespaced: string }
+export interface PickerOrderSaved {
+  pickerOrder: string[];
+  pickerOrderMode: SavedModelPickerOrderMode | null;
+}
+export interface PickerOrderSettings extends PickerOrderSaved { pickerAvailable: string[]; chosen?: string[] }
+
+function stringList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(id => typeof id === "string" && id.trim().length > 0);
+}
+function savedMode(value: unknown): value is SavedModelPickerOrderMode | null {
+  return value === null || value === "alphabetical" || value === "provider" || value === "most-used";
+}
+export function isPickerOrderSaved(value: unknown): value is PickerOrderSaved {
+  if (value === null || typeof value !== "object") return false;
+  const row = value as Record<string, unknown>;
+  return stringList(row.pickerOrder) && savedMode(row.pickerOrderMode);
+}
+export function isPickerOrderSettings(value: unknown): value is PickerOrderSettings {
+  if (!isPickerOrderSaved(value)) return false;
+  const row = value as PickerOrderSettings;
+  // Roster writes accept every string, including blanks; picker fields remain nonempty-string lists.
+  return stringList(row.pickerAvailable) && (!("chosen" in row)
+    || (Array.isArray(row.chosen) && row.chosen.every(id => typeof id === "string")));
+}
+export function isModelPickerUsage(value: unknown): value is ModelPickerUsage[] {
+  return Array.isArray(value) && value.every(row => row !== null && typeof row === "object"
+    && typeof row.provider === "string" && typeof row.model === "string"
+    && (row.resolvedModel === undefined || typeof row.resolvedModel === "string")
+    && typeof row.requests === "number" && Number.isFinite(row.requests) && row.requests >= 0);
+}
+function parts(slug: string): [string, string] {
+  const slash = slug.indexOf("/");
+  return slash < 0 ? ["", slug] : [slug.slice(0, slash), slug.slice(slash + 1)];
+}
+// Fixed locale makes snapshots independent of the user's display language/OS locale.
+const compare = (a: string, b: string) => a.localeCompare(b, "en");
+function byProvider(a: string, b: string): number {
+  const [ap, am] = parts(a), [bp, bm] = parts(b);
+  return compare(ap, bp) || compare(am, bm);
+}
+
+export function modelPickerOrder(
+  mode: Exclude<ModelPickerOrderMode, "custom">,
+  models: readonly string[],
+  usage: readonly ModelPickerUsage[] = [],
+  identities: readonly PickerModelIdentity[] = [],
+): string[] | null {
+  if (mode === "default") return null;
+  const unique = [...new Set(models)];
+  if (mode === "alphabetical") return unique.sort((a, b) => compare(parts(a)[1], parts(b)[1]) || byProvider(a, b));
+  if (mode === "provider") return unique.sort(byProvider);
+  const candidates = new Set(unique);
+  const raw = new Map<string, Set<string>>();
+  const owners = new Map<string, Set<string>>();
+  for (const row of identities) {
+    if (!candidates.has(row.namespaced)) continue;
+    const key = JSON.stringify([row.provider, row.id]);
+    const values = raw.get(key) ?? new Set<string>();
+    values.add(row.namespaced);
+    raw.set(key, values);
+    const sources = owners.get(row.namespaced) ?? new Set<string>();
+    sources.add(key);
+    owners.set(row.namespaced, sources);
+  }
+  const unambiguous = (slug: string): string | null => (owners.get(slug)?.size ?? 0) > 1 ? null : slug;
+  const resolve = (provider: string, id: string): string | null | undefined => {
+    const exact = raw.get(JSON.stringify([provider, id]));
+    if (exact) return exact.size === 1 ? unambiguous([...exact][0]!) : null;
+    // A raw upstream slash is not a namespace. Use the observed identity table above;
+    // only fall back to an exact same-provider catalog id or an ordinary bare model id.
+    if (id.startsWith(`${provider}/`) && candidates.has(id)) return unambiguous(id);
+    const slug = `${provider}/${id}`;
+    return !id.includes("/") && candidates.has(slug) ? unambiguous(slug) : undefined;
+  };
+  const counts = new Map<string, number>();
+  for (const row of usage) {
+    // Summary buckets are keyed by requested model. resolvedModel is only a
+    // representative observation, not proof that every request used that target.
+    const target = resolve(row.provider, row.model);
+    if (target) counts.set(target, (counts.get(target) ?? 0) + row.requests);
+  }
+  return unique.sort((a, b) => (counts.get(b) ?? 0) - (counts.get(a) ?? 0) || byProvider(a, b));
+}
+
+/** Resolve exact canonical ids before legacy provider/raw spellings; never guess a bare native id. */
+export function normalizePickerIds(ids: readonly string[], available: readonly string[], identities: readonly PickerModelIdentity[]): string[] {
+  const candidates = new Set(available.filter(id => id.includes("/")));
+  const resolve = (id: string): string | undefined => {
+    if (candidates.has(id)) return id;
+    const matches = new Set(identities.filter(row => candidates.has(row.namespaced)
+      && id === `${row.provider}/${row.id}`).map(row => row.namespaced));
+    return matches.size === 1 ? [...matches][0] : undefined;
+  };
+  return [...new Set(ids.map(id => resolve(id.trim())).filter((id): id is string => id !== undefined))];
+}
+
+/** Every candidate needs one observed provider/raw identity, with no encoded/raw collisions. */
+export function pickerIdentityCoverage(available: readonly string[], identities: readonly PickerModelIdentity[]): boolean {
+  const candidates = new Set(available.filter(id => id.includes("/")));
+  const rawBySlug = new Map<string, Set<string>>(), slugsByRaw = new Map<string, Set<string>>();
+  for (const row of identities) {
+    if (!candidates.has(row.namespaced)) continue;
+    const raw = `${row.provider}/${row.id}`;
+    const raws = rawBySlug.get(row.namespaced) ?? new Set<string>();
+    const slugs = slugsByRaw.get(raw) ?? new Set<string>();
+    raws.add(raw); slugs.add(row.namespaced);
+    rawBySlug.set(row.namespaced, raws); slugsByRaw.set(raw, slugs);
+  }
+  return [...candidates].every(slug => {
+    const raws = rawBySlug.get(slug);
+    return raws?.size === 1 && slugsByRaw.get([...raws][0]!)?.size === 1;
+  });
+}
+
+export function customPickerRows(settings: PickerOrderSettings, identities: readonly PickerModelIdentity[]): { order: string[]; fixed: string[] } | null {
+  // Unknown featured state and complete/native orders cannot safely become routed-only drafts.
+  if (settings.chosen === undefined || settings.pickerOrder.some(id => !id.includes("/"))) return null;
+  const available = [...new Set(settings.pickerAvailable.filter(id => id.includes("/")))];
+  if (!pickerIdentityCoverage(available, identities)) return null;
+  // Roster strings stay verbatim. Map uses the LAST occurrence; each row prefers its exact canonical rank.
+  const chosenRank = new Map(settings.chosen.map((id, index) => [id, index]));
+  const rawBySlug = new Map(identities.map(row => [row.namespaced, `${row.provider}/${row.id}`]));
+  const rankOf = (slug: string) => chosenRank.get(slug) ?? chosenRank.get(rawBySlug.get(slug)!);
+  const fixed = available.filter(slug => rankOf(slug) !== undefined).sort((a, b) => rankOf(a)! - rankOf(b)!);
+  const saved = normalizePickerIds(settings.pickerOrder, available, identities);
+  return { fixed, order: [...new Set([...fixed, ...saved, ...available])] };
+}

package/src/cli/models-custom-input.ts

@@ -0,0 +1,107 @@
+import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort } from "../reasoning-effort";
+import { isValidProviderName } from "../config/provider-name";
+import { CliUsageError, takeOptionWithSyntax } from "./runtime-api";
+
+/**
+ * Parse and validate the reasoning flags shared by `ocx models add` (offline path).
+ * "-" means "inherit" and omits the field entirely; "" means an explicit empty ladder
+ * ("no reasoning" override, the same state the dashboard stores for the toggle-off
+ * checkbox set). Malformed CSV like `low,,high` or `,,` is rejected instead of being
+ * silently normalized. Values are canonicalized into Codex ladder order so the stored
+ * config matches what the API stores.
+ */
+export function parseReasoningArgs(
+  reasoningEffortsValue: string | undefined,
+  defaultEffortValue: string | undefined,
+): { reasoningEfforts?: string[]; defaultReasoningEffort?: string; error?: string } {
+  if (reasoningEffortsValue === undefined && defaultEffortValue === undefined) return {};
+  let reasoningEfforts: string[] | undefined;
+  if (reasoningEffortsValue !== undefined) {
+    const trimmed = reasoningEffortsValue.trim();
+    if (trimmed === "-") {
+      reasoningEfforts = undefined;
+    } else if (trimmed === "") {
+      // Explicit no-reasoning override, exactly like the API's [] / the dashboard's
+      // uncheck-all state.
+      reasoningEfforts = [];
+    } else {
+      const parts = trimmed.split(",").map(value => value.trim());
+      if (parts.some(part => part === "")) {
+        return { error: "--reasoning-efforts must be comma-separated values from none, minimal, low, medium, high, xhigh, max, ultra (\"\" for no reasoning, \"-\" to inherit)" };
+      }
+      const invalid = parts.filter(value => !isDeclaredReasoningEffort(value));
+      if (invalid.length > 0) {
+        return { error: `unsupported reasoning effort: ${invalid.join(", ")} (allowed: none, minimal, low, medium, high, xhigh, max, ultra)` };
+      }
+      reasoningEfforts = canonicalizeReasoningEfforts(parts);
+    }
+  }
+  let defaultReasoningEffort: string | undefined;
+  if (defaultEffortValue !== undefined) {
+    const trimmed = defaultEffortValue.trim();
+    if (trimmed === "-") {
+      defaultReasoningEffort = undefined;
+    } else {
+      if (!isDeclaredReasoningEffort(trimmed)) {
+        return { error: `unsupported reasoning effort: ${trimmed} (allowed: none, minimal, low, medium, high, xhigh, max, ultra)` };
+      }
+      if (!reasoningEfforts || reasoningEfforts.length === 0) {
+        return { error: "--default-reasoning-effort requires --reasoning-efforts" };
+      }
+      if (!reasoningEfforts.includes(trimmed)) {
+        return { error: `--default-reasoning-effort "${trimmed}" is not in the declared reasoning efforts` };
+      }
+      defaultReasoningEffort = trimmed;
+    }
+  }
+  return { reasoningEfforts, defaultReasoningEffort };
+}
+
+export interface CustomModelAddInput {
+  provider: string;
+  modelId: string;
+  displayName?: string;
+  contextWindow?: number;
+  inputModalities?: string[];
+  reasoningEfforts?: string[];
+  defaultReasoningEffort?: string;
+}
+
+/** Parses only the existing add fields; the caller consumes --live and --json. */
+export function parseCustomModelAddInput(args: string[]): CustomModelAddInput {
+  const display = takeOptionWithSyntax(args, "--display-name")?.value;
+  const context = takeOptionWithSyntax(args, "--context-window")?.value;
+  const modalities = takeOptionWithSyntax(args, "--modalities")?.value;
+  // The inline empty value is meaningful here, unlike ordinary value options.
+  const emptyReasoning = args.indexOf("--reasoning-efforts=");
+  if (emptyReasoning >= 0) args.splice(emptyReasoning, 1, "--reasoning-efforts", "");
+  const efforts = takeOptionWithSyntax(args, "--reasoning-efforts")?.value;
+  const defaultEffort = takeOptionWithSyntax(args, "--default-reasoning-effort")?.value;
+  if (args.length !== 2 || args.some(arg => !arg.trim() || arg.startsWith("-"))) {
+    throw new CliUsageError("A provider and model ID are required; unexpected arguments are not accepted");
+  }
+  const provider = args[0]!.trim();
+  const modelId = args[1]!.trim();
+  if (!isValidProviderName(provider)) throw new CliUsageError("Invalid provider name");
+  const input: CustomModelAddInput = { provider, modelId };
+  const displayName = display?.trim();
+  if (displayName?.includes("/")) throw new CliUsageError("Display name must not contain /");
+  if (displayName) input.displayName = displayName;
+  if (context !== undefined) {
+    const value = Number(context);
+    if (!Number.isSafeInteger(value) || value <= 0) throw new CliUsageError("Context window must be a positive safe integer");
+    input.contextWindow = value;
+  }
+  if (modalities !== undefined) {
+    const values = modalities.split(",").map(value => value.trim());
+    if (values.some(value => !["text", "image", "audio"].includes(value))) {
+      throw new CliUsageError("Modalities must be comma-separated text, image or audio");
+    }
+    input.inputModalities = [...new Set(values)];
+  }
+  const parsed = parseReasoningArgs(efforts, defaultEffort);
+  if (parsed.error) throw new CliUsageError("Invalid reasoning options");
+  if (parsed.reasoningEfforts !== undefined) input.reasoningEfforts = parsed.reasoningEfforts;
+  if (parsed.defaultReasoningEffort !== undefined) input.defaultReasoningEffort = parsed.defaultReasoningEffort;
+  return input;
+}