@bitkyc08/opencodex 2.75.0 → 2.76.0

package/src/claude/intercept/picker-models.ts

@@ -7,8 +7,8 @@ import { dirname } from "node:path";
 import { nativeOpenAiContextWindow, type NativeContextLimitsInput } from "../../codex/catalog";
 import type { OcxClaudeDesktopProfile } from "../../types";
 import { aliasForRoute, claudeCodeNativeAlias } from "../alias";
-import { AUTO_CONTEXT_OFF, withOneMillionMarker } from "../context-windows";
-import { displayModelId, type Desktop3pRoutedModel } from "../desktop-3p";
+import { AUTO_CONTEXT_OFF, stripOneMillionMarker, withOneMillionMarker } from "../context-windows";
+import { activeDesktop3pAlias, displayModelId, resolveDesktop3pAlias, type Desktop3pRoutedModel } from "../desktop-3p";
 import { reconcileDesktopProfile, renderDesktopProfile, type DesktopProfileModel } from "../desktop-profile";
 import type { PickerModelEntry } from "./picker-bootstrap";
 
@@ -19,7 +19,8 @@ export interface PickerRouteInput {
   nativeContextCap?: NativeContextLimitsInput;
 }
 
-export function buildPickerModels(input: PickerRouteInput): PickerModelEntry[] {
+/** Candidate routes in the gateway profile's order and with its labels. */
+function renderPickerCandidates(input: PickerRouteInput): DesktopProfileModel[] {
   const candidates: DesktopProfileModel[] = [
     ...input.nativeSlugs.map(id => {
       const contextWindow = nativeOpenAiContextWindow(id, input.nativeContextCap);
@@ -35,27 +36,64 @@ export function buildPickerModels(input: PickerRouteInput): PickerModelEntry[] {
       ...(contextWindow === undefined ? {} : { contextWindow }),
     })),
   ];
-  const rendered = input.profile
+  return input.profile
     ? renderDesktopProfile(reconcileDesktopProfile(input.profile, candidates), candidates)
     : candidates;
+}
+
+function splitRoute(route: string): { provider: string; id: string } {
+  const slash = route.indexOf("/");
+  return { provider: route.slice(0, slash), id: route.slice(slash + 1) };
+}
+
+/** Desktop runners do not inherit the proxy's compaction env: mark only real >=1M windows. */
+function pickerSelector(alias: string, contextWindow: number | undefined): string {
+  return withOneMillionMarker(alias, contextWindow === undefined ? {} : { [alias]: contextWindow }, AUTO_CONTEXT_OFF)!;
+}
+
+export function buildPickerModels(input: PickerRouteInput): PickerModelEntry[] {
+  const rendered = renderPickerCandidates(input);
   const out: PickerModelEntry[] = [];
   const seen = new Set<string>();
   for (const model of rendered) {
-    const slash = model.route.indexOf("/");
-    const provider = model.route.slice(0, slash);
-    const id = model.route.slice(slash + 1);
+    const { provider, id } = splitRoute(model.route);
     if (provider === "anthropic" && id.startsWith("claude-")) continue;
     const alias = provider === "native" ? claudeCodeNativeAlias(id) : aliasForRoute(provider, id);
     if (!alias || seen.has(alias)) continue;
     seen.add(alias);
-    // Desktop runners do not inherit the proxy's compaction env: mark only real >=1M windows.
-    const selector = withOneMillionMarker(alias, model.contextWindow === undefined ? {} : { [alias]: model.contextWindow }, AUTO_CONTEXT_OFF)!;
-    out.push({ id: selector, name: model.label,
+    out.push({ id: pickerSelector(alias, model.contextWindow), name: model.label,
       ...(model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow }) });
   }
   return out;
 }
 
+/**
+ * Rows for the Claude Code CLI's `cc` catalog. The CLI only offers Claude-shaped ids, so each route
+ * uses its Desktop 3P registry alias, and only one the registry decodes back to the same route: an
+ * id the router cannot resolve is never advertised. Real Anthropic rows are already in the catalog.
+ */
+export function buildCliPickerModels(input: PickerRouteInput): PickerModelEntry[] {
+  const out: PickerModelEntry[] = [];
+  const seen = new Set<string>();
+  for (const model of renderPickerCandidates(input)) {
+    const { provider, id } = splitRoute(model.route);
+    if (provider === "anthropic" && id.startsWith("claude-")) continue;
+    const alias = activeDesktop3pAlias(provider, id);
+    if (seen.has(alias) || resolveDesktop3pAlias(alias) !== model.route) continue;
+    seen.add(alias);
+    out.push({ id: pickerSelector(alias, model.contextWindow), name: model.label,
+      description: `opencodex · ${model.route}`, route: model.route,
+      ...(model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow }) });
+  }
+  return out;
+}
+
+/** Rows whose alias still decodes to the route it was minted for: the registry can be rebuilt after a snapshot was taken. */
+export function routableCliPickerModels(models: readonly PickerModelEntry[]): PickerModelEntry[] {
+  return models.filter(model => model.route !== undefined
+    && resolveDesktop3pAlias(stripOneMillionMarker(model.id)) === model.route);
+}
+
 export interface PickerModelSnapshot {
   current(): { models: PickerModelEntry[]; builtAt: number } | null;
   refresh(): Promise<void>;
@@ -68,11 +106,17 @@ function parseSnapshot(value: unknown): { models: PickerModelEntry[]; builtAt: n
   if (typeof candidate.builtAt !== "number" || !Number.isFinite(candidate.builtAt) || !Array.isArray(candidate.models)) return null;
   if (!candidate.models.every(model => model && typeof model === "object"
     && typeof model.id === "string" && typeof model.name === "string"
-    && (model.contextWindow === undefined || typeof model.contextWindow === "number"))) return null;
+    && (model.contextWindow === undefined || typeof model.contextWindow === "number")
+    && (model.description === undefined || typeof model.description === "string")
+    && (model.route === undefined || typeof model.route === "string"))) return null;
   return { models: candidate.models as PickerModelEntry[], builtAt: candidate.builtAt };
 }
 
-export function createPickerModelSnapshot(load: () => Promise<PickerRouteInput>, persistPath?: string): PickerModelSnapshot {
+export function createPickerModelSnapshot(
+  load: () => Promise<PickerRouteInput>,
+  persistPath?: string,
+  build: (input: PickerRouteInput) => PickerModelEntry[] = buildPickerModels,
+): PickerModelSnapshot {
   let snapshot: { models: PickerModelEntry[]; builtAt: number } | null = null;
   if (persistPath) {
     try { snapshot = parseSnapshot(JSON.parse(readFileSync(persistPath, "utf8")) as unknown); } catch { /* No usable prior snapshot. */ }
@@ -82,7 +126,7 @@ export function createPickerModelSnapshot(load: () => Promise<PickerRouteInput>,
     if (pending) return pending;
     pending = (async () => {
       try {
-        const models = buildPickerModels(await load());
+        const models = build(await load());
         const next = { models, builtAt: Date.now() };
         if (persistPath) {
           mkdirSync(dirname(persistPath), { recursive: true, mode: 0o700 });

package/src/claude/intercept/runtime.ts

@@ -4,6 +4,7 @@ import { getConfigDir } from "../../config/paths";
 import type { DesktopPickerController } from "../desktop-picker";
 import type { ClaudeFirstPartyDesired } from "../first-party-settings";
 import { classifyInterceptClient, interceptRouteFor } from "./client-class";
+import { createCliCatalogProvider } from "./cli-picker";
 import { CLAUDE_INTERCEPT_HOSTS, isBrowserConnect, startConnectProxy, type ConnectProxyHandle } from "./connect-proxy";
 import { startClaudeInterceptListener } from "./listener";
 import { claudeInterceptCaCertPath, ensureLocalInterceptCaForStartup, issueLocalInterceptLeaf } from "./local-ca";
@@ -50,7 +51,11 @@ export function claudePickerProxyPort(config: Pick<OcxConfig, "claudeCode">, pub
   return interceptPort < 65535 ? interceptPort + 1 : interceptPort - 1;
 }
 
+export type ClaudeInterceptOutcome = { ok: true; state: ClaudeInterceptState } | { ok: false; reason: "disabled" | "client_role" | "ephemeral_port" | "port_in_use" | "stopped" | "failed"; port?: number; message?: string };
+
 export interface ClaudeInterceptState {
+  pickerReason?: "port_in_use" | "failed" | null;
+  pickerFailurePort?: number;
   proxyPort: number;
   caCertPath: string;
   /** Desktop egress proxy for picker mode; null when the picker is not wired or could not bind. */
@@ -101,6 +106,14 @@ export async function createPickerPreferenceWriter(live: OcxConfig): Promise<(va
   };
 }
 
+export class ClaudeInterceptProxyBindError extends Error {
+  readonly code: unknown;
+  constructor(error: unknown, readonly port: number) {
+    super(error instanceof Error ? error.message : "CONNECT proxy bind failed", { cause: error });
+    this.code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+  }
+}
+
 export interface StartClaudeInterceptOptions<T> {
   config: OcxConfig;
   /** Bound public port; the derived proxy port is offset from it. */
@@ -160,6 +173,10 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
     dispatch: options.dispatch,
     ...(options.desiredClients ? { route: (req: Request) =>
       interceptRouteFor(classifyInterceptClient(req.headers.get("user-agent")), options.desiredClients!()) } : {}),
+    // The CLI's /model catalog (cli-picker.ts): wired from the routes alone, never from Desktop picker state.
+    ...(options.loadPickerRoutes && options.desiredClients ? { cliCatalog: createCliCatalogProvider({
+      configDir, loadRoutes: options.loadPickerRoutes, desiredClients: options.desiredClients,
+    }) } : {}),
     upstreamBase: options.config.claudeCode?.anthropicBaseUrl,
     ...(options.maxRequestBodySize !== undefined ? { maxRequestBodySize: options.maxRequestBodySize } : {}),
   });
@@ -173,13 +190,15 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
     });
   } catch (error) {
     await listener.stop(true);
-    throw error;
+    throw new ClaudeInterceptProxyBindError(error, claudeInterceptProxyPort(options.config, options.publicPort));
   }
   // Widened on purpose: assignments happen in nested awaits the catch below must still see.
   let picker = null as PickerRuntime | null;
   let pickerProxy = null as ConnectProxyHandle | null;
   let controller = null as DesktopPickerController | null;
   let pickerProxyLive = false;
+  let pickerReason: ClaudeInterceptState["pickerReason"] = null;
+  let pickerFailurePort: number | undefined;
   try {
     if (options.loadPickerRoutes) {
       // A picker authority is process-scoped, and older releases persisted an exportable ca.key
@@ -208,9 +227,11 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
         }
       } catch (error) {
         pickerBlocked = true;
+        pickerReason = "failed";
         console.warn(`⚠ Claude Desktop picker CA cleanup deferred: ${error instanceof Error ? error.message : String(error)}`);
       }
       if (pickerBlocked) {
+        pickerReason = "failed";
         console.warn("⚠ Claude Desktop picker disabled: the previous certificate could not be untrusted");
         if (pickerProfile.kind === "applied") {
           // Keep Desktop's actual pinned egress alive without ever constructing a TLS terminator.
@@ -223,6 +244,8 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
             });
             pickerProxyLive = true;
           } catch (error) {
+            pickerReason = error && typeof error === "object" && "code" in error && error.code === "EADDRINUSE" ? "port_in_use" : "failed";
+            if (pickerReason === "port_in_use") pickerFailurePort = port;
             console.warn(`⚠ Claude Desktop blind egress relay could not start: ${error instanceof Error ? error.message : String(error)}`);
           }
         }
@@ -241,8 +264,9 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
       if (picker) {
         const runtime = picker;
         const interceptPort = listener.port!;
+        const pickerPort = claudePickerProxyPort(options.config, options.publicPort);
         try {
-          pickerProxy = await startProxy(claudePickerProxyPort(options.config, options.publicPort), {
+          pickerProxy = await startProxy(pickerPort, {
             interceptPort,
             // No authToken: Desktop's egressProxyUrl cannot present proxy credentials, so this
             // listener stays an unauthenticated loopback relay until the profile format can carry
@@ -267,6 +291,8 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
           // Picker mode is optional: a busy port leaves the intercept pair running without it.
           // The selected profile row survives, so the next startup retries the restore once the
           // port is free again.
+          pickerReason = error && typeof error === "object" && "code" in error && error.code === "EADDRINUSE" ? "port_in_use" : "failed";
+          if (pickerReason === "port_in_use") pickerFailurePort = pickerPort;
           console.warn(`⚠ Claude Desktop picker proxy could not start: ${error instanceof Error ? error.message : String(error)}`);
           await runtime.stop();
           picker = null;
@@ -313,6 +339,8 @@ export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptio
     throw error;
   }
   const state: ClaudeInterceptState = {
+    pickerReason,
+    pickerFailurePort,
     proxyPort: proxy.port,
     caCertPath: claudeInterceptCaCertPath(configDir),
     pickerProxyPort: pickerProxy?.port ?? null,

package/src/claude/intercept/settings.ts

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { atomicWriteFile } from "../../config/atomic-write";
 import { claudeConfigDir } from "../auth-detect";
+import { invalidateClaudeCodeServedCatalog } from "./cli-catalog";
 
 /**
  * Claude Code `settings.json` env block for intercept mode.
@@ -115,6 +116,8 @@ function writeSettings(path: string, doc: SettingsDoc): void {
   // The managed env embeds the proxy token, so the file must stay owner-only:
   // atomicWriteFile applies the real NTFS ACL on Windows where chmod is a no-op.
   atomicWriteFile(path, `${JSON.stringify(doc, null, 2)}\n`);
+  // Whether Claude Code reaches the proxy just changed, so its cached /model list is stale.
+  invalidateClaudeCodeServedCatalog(dirname(path));
 }
 
 export type ClaudeInterceptSettingsWrite =

package/src/cli/agent.ts

@@ -25,9 +25,11 @@ const USAGE = `Usage:
   ocx agent [status] [--json]
   ocx agent injection <status|set> [--model <id|->] [--effort <level|->]
       [--prompt <text|->] [--guidance <on|off>] [--json]
+  ocx agent injection suggest <work description> [--model <id>] [--apply] [--json]
   ocx agent effort <status|set> [--main <level|->] [--subagent <level|->] [--json]
   ocx agent subagents <status|set|clear> [model,model...] [--json]
   ocx agent fallback <status|set|clear> [model,model...] [--poll-ms <5000-600000>] [--json]
+  ocx agent roles [status|set <role> <model>|suggest [--model <id>] [--apply]] [--json]
   ocx agent sidecar <status|web|vision> [--list] [--model <id|->]
       [--backend web:<openai|anthropic|xai|gemini|exa|-> vision:<openai|anthropic|routed|->]
       [--reasoning <level>] [--max-descriptions <n>] [--enabled <on|off>] [--json]
@@ -53,6 +55,58 @@ async function status(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, summaryLines(result));
 }
 
+interface DelegationProposal {
+  model: string | null;
+  effort: string | null;
+  status: "proposed" | "unassigned" | "unsized";
+  tier?: string;
+  effortIntent?: string;
+  rationale?: string;
+  moveUpIf?: string;
+  moveDownIf?: string;
+  proposedModel?: string | null;
+  proposedEffort?: string | null;
+  reason?: string | null;
+}
+
+async function suggestInjection(args: string[], wantsJson: boolean, deps: RuntimeApiDeps): Promise<void> {
+  const model = takeOption(args, "--model");
+  const apply = takeFlag(args, "--apply");
+  if (args.some(arg => arg.startsWith("--"))) rejectArgs(args, USAGE);
+  const work = args.join(" ").trim();
+  if (!work) throw new CliUsageError("describe the delegated work to size", USAGE);
+  const result = await runtimeRequest<{ sizingModel?: string; proposal?: DelegationProposal }>(
+    "/api/injection-model/suggest",
+    { method: "POST", body: JSON.stringify({ work, ...(model ? { model } : {}) }) },
+    deps,
+  );
+  const p = result.proposal;
+  const alreadySet = p?.status === "proposed" && !!p.proposedModel
+    && p.proposedModel === p.model && (p.proposedEffort ?? null) === (p.effort ?? null);
+  let applied: { model: string; effort: string | null } | null = null;
+  if (apply && !alreadySet && p?.status === "proposed" && p.proposedModel) {
+    applied = { model: p.proposedModel, effort: p.proposedEffort ?? null };
+    await runtimeRequest("/api/injection-model", { method: "PUT", body: JSON.stringify(applied) }, deps);
+  }
+  printData(apply ? { ...result, applied, alreadySet } : result, wantsJson, [
+    `Sized with ${result.sizingModel ?? "unknown"}.`,
+    !p || p.status === "unsized"
+      ? `Not sized (${p?.reason ?? "unknown"}).`
+      : p.status === "unassigned"
+        ? `${p.tier}/${p.effortIntent}, no model (${p.reason ?? "unknown"})`
+        : `${p.model ?? "(none)"}${p.effort ? ` (${p.effort})` : ""} -> ${p.proposedModel}${p.proposedEffort ? ` (${p.proposedEffort})` : ""} [${p.tier}/${p.effortIntent}] ${p.rationale ?? ""}`,
+    ...(p?.moveUpIf ? [`Move up if: ${p.moveUpIf}`] : []),
+    ...(p?.moveDownIf ? [`Move down if: ${p.moveDownIf}`] : []),
+    apply
+      ? (applied
+        ? "Applied to the delegation model."
+        : alreadySet
+          ? `Already set to ${p!.proposedModel}${p!.proposedEffort ? ` (${p!.proposedEffort})` : ""}; nothing applied.`
+          : "Nothing to apply.")
+      : "Nothing was written; rerun with --apply to set the delegation model.",
+  ]);
+}
+
 async function injection(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const action = (args.shift() ?? "status").toLowerCase();
@@ -63,6 +117,10 @@ async function injection(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     printData(result, wantsJson, summaryLines(result));
     return;
   }
+  if (action === "suggest") {
+    await suggestInjection(args, wantsJson, deps);
+    return;
+  }
   if (action !== "set") throw new CliUsageError(`unknown injection action ${action}`, USAGE);
   const model = clearable(takeOption(args, "--model"));
   const effort = clearable(takeOption(args, "--effort"));
@@ -236,6 +294,119 @@ async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, lines);
 }
 
+interface CodexAgentRolesStatus {
+  lazycodex?: { detected?: boolean };
+  omoJsonc?: { state?: string } | null;
+  roles?: Array<{ role: string; model: string | null; omoJsoncModel: string | null }>;
+}
+
+interface CodexRoleProposal {
+  role: string;
+  model: string | null;
+  effort?: string | null;
+  status: "proposed" | "unassigned" | "unsized";
+  tier?: string;
+  effortIntent?: string;
+  rationale?: string;
+  proposedModel?: string | null;
+  proposedEffort?: string | null;
+  reason?: string | null;
+}
+
+function proposalAlreadySet(proposal: CodexRoleProposal): boolean {
+  return proposal.proposedModel === proposal.model
+    && (proposal.proposedEffort == null || proposal.proposedEffort === proposal.effort);
+}
+
+const OMO_JSONC_NOT_WRITTEN = new Set(["skipped_comments", "invalid", "write_failed"]);
+
+async function suggestRoles(args: string[], wantsJson: boolean, deps: RuntimeApiDeps): Promise<void> {
+  const model = takeOption(args, "--model");
+  const apply = takeFlag(args, "--apply");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ sizingModel?: string; proposals?: CodexRoleProposal[] }>(
+    "/api/codex-agent-roles/auto-assign",
+    { method: "POST", body: JSON.stringify(model ? { model } : {}) },
+    deps,
+  );
+  const proposals = result.proposals ?? [];
+  const applied: Array<{ role: string; model: string; effort?: string }> = [];
+  const skipped: string[] = [];
+  const omoJsoncNotWritten: Array<{ role: string; status: string }> = [];
+  if (apply) {
+    for (const proposal of proposals) {
+      if (proposal.status !== "proposed" || !proposal.proposedModel) continue;
+      if (proposalAlreadySet(proposal)) {
+        skipped.push(proposal.role);
+        continue;
+      }
+      const body = { model: proposal.proposedModel, ...(proposal.proposedEffort ? { effort: proposal.proposedEffort } : {}) };
+      const written = await runtimeRequest<{ omoJsonc?: { status?: string } } | null>(
+        `/api/codex-agent-roles/${encodeURIComponent(proposal.role)}`,
+        { method: "PUT", body: JSON.stringify(body) },
+        deps,
+      );
+      applied.push({ role: proposal.role, ...body });
+      const omoStatus = written?.omoJsonc?.status;
+      if (omoStatus && OMO_JSONC_NOT_WRITTEN.has(omoStatus)) omoJsoncNotWritten.push({ role: proposal.role, status: omoStatus });
+    }
+  }
+  printData(apply ? { ...result, applied, skipped, omoJsoncNotWritten } : result, wantsJson, [
+    `Sized with ${result.sizingModel ?? "unknown"}.`,
+    ...proposals.map(p => p.status === "unsized"
+      ? `${p.role}: not sized (${p.reason ?? "unknown"})`
+      : p.status === "unassigned"
+        ? `${p.role}: ${p.tier}/${p.effortIntent}, no model (${p.reason ?? "unknown"})`
+        : `${p.role}: ${p.model ?? "(no pin)"} -> ${p.proposedModel}${p.proposedEffort ? ` (${p.proposedEffort})` : ""} [${p.tier}/${p.effortIntent}] ${p.rationale ?? ""}`),
+    apply
+      ? `Applied ${applied.length} of ${proposals.length} roles.${skipped.length > 0 ? ` Skipped ${skipped.length} already set: ${skipped.join(", ")}.` : ""}`
+      : "Nothing was written; rerun with --apply to write every proposal that differs from the role's current pin.",
+    ...omoJsoncNotWritten.map(entry => `${entry.role}: omo.jsonc not written (${entry.status}); the role TOML was updated.`),
+  ]);
+}
+
+async function roles(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const action = (args.shift() ?? "status").toLowerCase();
+  if (action === "status") {
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest<CodexAgentRolesStatus>("/api/codex-agent-roles", {}, deps);
+    if (result.lazycodex?.detected !== true) {
+      printData(result, wantsJson, ["omo (Codex / LazyCodex) is not installed in this CODEX_HOME; role models are managed only with it."]);
+      return;
+    }
+    const rows = result.roles ?? [];
+    printData(result, wantsJson, [
+      "omo (Codex / LazyCodex): detected",
+      ...(rows.length === 0 ? ["No Codex agent roles found."] : rows.map(row => `${row.role}: ${row.model ?? "(no model pin)"}`)),
+      `omo.jsonc: ${result.omoJsonc?.state ?? "unknown"}`,
+    ]);
+    return;
+  }
+  if (action === "suggest") {
+    await suggestRoles(args, wantsJson, deps);
+    return;
+  }
+  if (action !== "set") throw new CliUsageError(`unknown roles action ${action}`, USAGE);
+  const role = args.shift();
+  const model = args.shift();
+  if (!role || !model) throw new CliUsageError("a role and a model are required", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ toml?: { status?: string }; omoJsonc?: { status?: string } }>(
+    `/api/codex-agent-roles/${encodeURIComponent(role)}`,
+    { method: "PUT", body: JSON.stringify({ model }) },
+    deps,
+  );
+  const omo = result.omoJsonc?.status;
+  printData(result, wantsJson, [
+    `${role}: ${model} (role TOML ${result.toml?.status ?? "unknown"})`,
+    omo === "skipped_comments"
+      ? "omo.jsonc: not written, because it contains comments that a rewrite would lose."
+      : `omo.jsonc: ${omo ?? "unknown"}`,
+  ]);
+}
+
 export async function handleAgentCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
   return runCliAction(async () => {
     const [sub = "status", ...rest] = argv;
@@ -244,6 +415,7 @@ export async function handleAgentCommand(argv: string[], deps: RuntimeApiDeps =
     else if (sub === "effort") await effort(rest, deps);
     else if (sub === "subagents" || sub === "roster") await subagents(rest, deps);
     else if (sub === "fallback") await fallback(rest, deps);
+    else if (sub === "roles") await roles(rest, deps);
     else if (sub === "sidecar") await sidecar(rest, deps);
     // Lives here rather than as a top-level verb because it is an agent-behavior feature flag:
     // it controls whether default mode may ask the operator a question mid-task.

package/src/cli/alias.ts

@@ -12,10 +12,11 @@ function selector(value: string): { provider: string; model?: string } {
   return slash < 0 ? { provider: value } : { provider: value.slice(0, slash), model: value.slice(slash + 1) };
 }
 
+/** Manage model aliases, consuming JSON output selection before the default list action. */
 export async function handleAliasCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
   const args = [...argv];
-  const action = (args.shift() ?? "list").toLowerCase();
   const wantsJson = takeFlag(args, "--json");
+  const action = (args.shift() ?? "list").toLowerCase();
   if (action === "list") {
     rejectArgs(args, USAGE);
     const result = await runtimeRequest<Record<string, unknown>>("/api/aliases", {}, deps);

package/src/cli/capabilities-command.ts

@@ -45,14 +45,15 @@ function renderHuman(caps: readonly Capability[], includeHead: boolean): void {
   }
 }
 
+/** Render declared capabilities; reject invalid arguments with 64 and report unmatched routes with 4. */
 export async function runCapabilities(argv: string[]): Promise<number> {
   const args = [...argv];
   const json = takeFlag(args, "--json");
   const mutatingOnly = takeFlag(args, "--mutating-only");
   const route = takeValueFlag(args, "--route");
 
-  if (route !== undefined && route.length === 0) {
-    console.error("Usage: ocx capabilities --route <path>");
+  if (args.length > 0 || (route !== undefined && route.trim().length === 0)) {
+    console.error("Usage: ocx capabilities [--json] [--mutating-only] [--route <path>]");
     return 64;
   }
 

package/src/cli/capabilities.ts

@@ -95,6 +95,13 @@ export const HEAD_CAPABILITIES: readonly HeadCapability[] = [
  * A capability must not name a route the command does not actually fetch.
  */
 export const CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["chatgpt"],
+    summary: "Experimental ChatGPT app-server shim: launch, restore or status (macOS only).",
+    routes: [], flags: [], mutates: true, json: "none",
+    bannerLines: ["ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)"],
+    details: ["Default off; launch requires chatgptDesktop.appServerShim: true. Restore removes the generated launcher."],
+  },
   {
     command: ["link", "port"],
     summary: "Allocate a free loopback port for a remote home link.",
@@ -908,6 +915,14 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: ["`status` reads the route; `set` writes only submitted fields. Enabling first-party requires a running Claude intercept."],
   },
+  {
+    command: ["claude", "intercept", "start"],
+    summary: "Start the local Claude interception pair on demand.",
+    routes: [{ method: "POST", path: "/api/claude-intercept/start" }],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the management response as JSON." }],
+    mutates: true,
+    json: "payload",
+  },
   {
     command: ["claude", "desktop", "status"],
     summary: "Applied-vs-desired Claude Desktop state, including staleness, drift, and health.",
@@ -1060,6 +1075,51 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: ["A bare invocation reads and never writes."],
   },
+  {
+    command: ["agent", "roles"],
+    summary: "omo (Codex / LazyCodex): show each Codex agent role's model pin, set one role's model in its TOML and in omo.jsonc, or suggest a model for every role.",
+    routes: [
+      { method: "GET", path: "/api/codex-agent-roles" },
+      { method: "PUT", path: "/api/codex-agent-roles/{role}" },
+      { method: "POST", path: "/api/codex-agent-roles/auto-assign" },
+    ],
+    flags: [
+      { name: "--json", value: "boolean", summary: "Emit the role list, the write result or the proposals as JSON." },
+      { name: "--model", value: "string", summary: "suggest: size the roles with this model instead of the Codex default model." },
+      { name: "--apply", value: "boolean", summary: "suggest: write every proposal through the role model write." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: [
+      "A bare invocation reads and never writes.",
+      "Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.",
+      "set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml; omo.jsonc is skipped when absent or when it contains comments.",
+      "suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort.",
+    ],
+  },
+  {
+    command: ["agent", "injection"],
+    summary: "Show or set the delegation model and effort, or suggest both for a described piece of delegated work.",
+    routes: [
+      { method: "GET", path: "/api/injection-model" },
+      { method: "PUT", path: "/api/injection-model" },
+      { method: "POST", path: "/api/injection-model/suggest" },
+    ],
+    flags: [
+      { name: "--json", value: "boolean", summary: "Emit the delegation settings, the write result or the proposal as JSON." },
+      { name: "--model", value: "string", summary: "set: the delegation model, - clears it. suggest: size the work with this model instead of the Codex default model." },
+      { name: "--effort", value: "string", summary: "set: the delegation reasoning effort, - clears it." },
+      { name: "--prompt", value: "string", summary: "set: a custom guidance prompt, - clears it." },
+      { name: "--guidance", value: "string", summary: "set: on or off for OpenCodex delegation guidance." },
+      { name: "--apply", value: "boolean", summary: "suggest: write the proposed model and effort through the delegation settings write." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: [
+      "A bare invocation reads and never writes.",
+      "suggest sizes the described work with one model call, picks the cheapest sufficient model the delegation picker offers, and writes nothing unless --apply is given.",
+    ],
+  },
   {
     command: ["api", "protocols"],
     summary: "Read the protocol contract version, API surfaces, protocol settings and feature vocabulary.",
@@ -1071,6 +1131,33 @@ export const CAPABILITIES: readonly Capability[] = [
     mutates: false,
     json: "payload",
   },
+  {
+    command: ["combo", "test"],
+    summary: "Run one JEV decision probe through a decision method: TypeSafe, a System One row, or an opencodex model.",
+    routes: [{ method: "POST", path: "/api/combos/decision-test" }],
+    flags: [
+      { name: "--combo", value: "string", summary: "Combo id whose saved decision method is probed and whose recursion rules apply." },
+      { name: "--decision-provider", value: "string", summary: "Probe a jev-decision provider row (or jev for TypeSafe) instead of the saved method." },
+      { name: "--decision-model", value: "string", summary: "Probe an opencodex-routed model instead of the saved method." },
+      { name: "--decision-timeout", value: "number", summary: "Decision deadline in milliseconds (1000-120000)." },
+      { name: "--json", value: "boolean", summary: "Emit the probe result." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: ["Sends one synthetic two-option decision; it may spend a decision call on the chosen backend."],
+  },
+  {
+    command: ["combo", "discover"],
+    summary: "List configured System One decision rows and catalog models that look like decision services.",
+    routes: [{ method: "GET", path: "/api/combos/decision-discovery" }],
+    flags: [
+      { name: "--query", value: "string", summary: "Match catalog rows by this text instead of the built-in decision-model hint." },
+      { name: "--json", value: "boolean", summary: "Emit the discovery payload." },
+    ],
+    mutates: false,
+    json: "payload",
+    details: ["Read-only: nothing is probed and no provider row is created."],
+  },
   {
     command: ["api", "explain"],
     summary: "Preview the request path a model would take from one inbound API, computed from config.",