@yansigit/opencodex 2.31.0

package/src/cli/combo.ts

@@ -0,0 +1,127 @@
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  takeFlag,
+  takeIntegerOption,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx combo [list] [--json]
+  ocx combo show <id> [--json]
+  ocx combo set <id> --targets <provider/model[:weight],...>
+      [--strategy <failover|round-robin>] [--sticky <1-100>]
+      [--effort <low|medium|high|xhigh|max|ultra|->] [--alias <name|->]
+      [--native-alias] [--display-name <label|->]
+      [--rename-from <id>] [--json]
+  ocx combo remove <id> --yes [--json]`;
+
+type ComboRow = Record<string, unknown> & { id?: string; model?: string };
+
+function parseTargets(value: string): Array<{ provider: string; model: string; weight?: number }> {
+  const targets = value.split(",").map(part => part.trim()).filter(Boolean).map(part => {
+    const colon = part.lastIndexOf(":");
+    let selector = part;
+    let weight: number | undefined;
+    if (colon > part.indexOf("/")) {
+      const maybeWeight = Number(part.slice(colon + 1));
+      if (Number.isInteger(maybeWeight)) {
+        selector = part.slice(0, colon);
+        weight = maybeWeight;
+      }
+    }
+    const slash = selector.indexOf("/");
+    if (slash <= 0 || slash === selector.length - 1) throw new CliUsageError(`invalid target "${part}"; use provider/model[:weight]`, USAGE);
+    const target = { provider: selector.slice(0, slash), model: selector.slice(slash + 1), ...(weight !== undefined ? { weight } : {}) };
+    if (weight !== undefined && (weight < 1 || weight > 10_000)) throw new CliUsageError(`target weight must be 1-10000: ${part}`, USAGE);
+    return target;
+  });
+  if (targets.length === 0) throw new CliUsageError("--targets requires at least one provider/model", USAGE);
+  return targets;
+}
+
+async function list(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps);
+  const rows = result.combos ?? [];
+  printData(result, wantsJson, rows.length ? rows.map(row => `${String(row.id)}  ${String(row.model ?? `combo/${row.id}`)}`) : ["No combos configured."]);
+}
+
+async function show(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const id = args.shift();
+  const wantsJson = takeFlag(args, "--json");
+  if (!id) throw new CliUsageError("combo id is required", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps);
+  const combo = (result.combos ?? []).find(row => row.id === id);
+  if (!combo) throw new CliUsageError(`unknown combo ${id}`);
+  printData(combo, wantsJson);
+}
+
+async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const id = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  if (!id) throw new CliUsageError("combo id is required", USAGE);
+  const targetsRaw = takeOption(args, "--targets");
+  if (!targetsRaw) throw new CliUsageError("--targets is required", USAGE);
+  const strategy = takeOption(args, "--strategy") ?? "failover";
+  if (strategy !== "failover" && strategy !== "round-robin") throw new CliUsageError("--strategy must be failover or round-robin", USAGE);
+  const stickyLimit = takeIntegerOption(args, "--sticky", { min: 1 }) ?? 1;
+  if (stickyLimit > 100) throw new CliUsageError("--sticky must be <= 100", USAGE);
+  const effort = takeOption(args, "--effort");
+  const alias = takeOption(args, "--alias");
+  const nativeAlias = takeFlag(args, "--native-alias");
+  const displayName = takeOption(args, "--display-name");
+  const renameFrom = takeOption(args, "--rename-from");
+  rejectArgs(args, USAGE);
+  const combo: Record<string, unknown> = {
+    strategy,
+    stickyLimit,
+    targets: parseTargets(targetsRaw),
+  };
+  if (effort !== undefined) combo.defaultEffort = effort === "-" ? null : effort;
+  if (alias !== undefined) combo.alias = alias === "-" ? "" : alias;
+  if (nativeAlias) combo.nativeAlias = true;
+  if (displayName !== undefined) combo.displayName = displayName === "-" ? "" : displayName;
+  const current = await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps);
+  const existing = (current.combos ?? []).find(row => row.id === (renameFrom ?? id));
+  if (existing?.imageInput === "disabled") combo.imageInput = "disabled";
+  const result = await runtimeRequest("/api/combos", {
+    method: "PUT",
+    body: JSON.stringify({ id, combo, ...(renameFrom ? { renameFrom } : {}) }),
+  }, deps);
+  printData(result, wantsJson, [`Saved combo ${id}.`]);
+}
+
+async function remove(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const id = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const yes = takeFlag(args, "--yes");
+  if (!id) throw new CliUsageError("combo id is required", USAGE);
+  if (!yes) throw new CliUsageError("remove requires --yes", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest(`/api/combos?id=${encodeURIComponent(id)}`, { method: "DELETE" }, deps);
+  printData(result, wantsJson, [`Removed combo ${id}.`]);
+}
+
+export async function handleComboCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "list", ...rest] = argv;
+    if (sub === "list") await list(rest, deps);
+    else if (sub === "show") await show(rest, deps);
+    else if (sub === "set" || sub === "create" || sub === "update") await set(rest, deps);
+    else if (sub === "remove" || sub === "delete") await remove(rest, deps);
+    else throw new CliUsageError(`unknown combo command ${sub}`, USAGE);
+  });
+}
+
+export const COMBO_USAGE = USAGE;

package/src/cli/config-command.ts

@@ -0,0 +1,209 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { clearCodexAccountPin } from "../codex/account-priority";
+import { getConfigPath, mutatePersistedConfig, readConfigDiagnostics, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate } from "../config";
+import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../reasoning-effort";
+import type { OcxConfig } from "../types";
+import { normalizeVisionReasoningForModel } from "../vision/reasoning";
+import { CliUsageError, printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx config [show] [--json] [--source]
+  ocx config get <dot.path> [--json]
+  ocx config set <dot.path> <json-or-string> [--json]
+  ocx config unset <dot.path> [--json]
+  ocx config validate [path|-] [--json]
+  ocx config export <path|->
+  ocx config import <path|-> --yes [--json]`;
+
+const SECRET_KEYS = /^(apiKey|key|accessToken|refreshToken|idToken|token|password|clientSecret)$/i;
+const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+
+function redact(value: unknown, key = ""): unknown {
+  if (SECRET_KEYS.test(key) && typeof value === "string") return value ? "********" : value;
+  // modelCosts rows are keyed by model id; a pasted API key in a key position
+  // must not be echoed back by config show/get (values are already redacted).
+  if (key === "modelCosts") return sanitizeModelCostsForDisplay(value);
+  if (Array.isArray(value)) return value.map(item => redact(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([childKey, child]) => [childKey, redact(child, childKey)]));
+  }
+  return value;
+}
+
+function pathSegments(path: string): string[] {
+  const segments = path.split(".").map(part => part.trim()).filter(Boolean);
+  if (segments.length === 0 || segments.some(part => BLOCKED_SEGMENTS.has(part))) throw new CliUsageError("invalid config path", USAGE);
+  return segments;
+}
+
+function getPath(root: unknown, path: string): unknown {
+  let current = root;
+  for (const segment of pathSegments(path)) {
+    if (!current || typeof current !== "object" || !Object.hasOwn(current, segment)) throw new CliUsageError(`config path not found: ${path}`);
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+function setPath(root: Record<string, unknown>, path: string, value: unknown, remove = false): void {
+  const segments = pathSegments(path);
+  let current = root;
+  for (const segment of segments.slice(0, -1)) {
+    const next = current[segment];
+    if (!next || typeof next !== "object" || Array.isArray(next)) throw new CliUsageError(`config parent path not found: ${segment}`, USAGE);
+    current = next as Record<string, unknown>;
+  }
+  const leaf = segments.at(-1)!;
+  if (remove && !Object.hasOwn(current, leaf)) throw new CliUsageError(`config path not found: ${path}`);
+  if (remove) delete current[leaf];
+  else current[leaf] = value;
+}
+
+function parseValue(raw: string): unknown {
+  try { return JSON.parse(raw); }
+  catch { return raw; }
+}
+
+function loadInput(path: string): unknown {
+  const raw = path === "-" ? readFileSync(0, "utf8") : readFileSync(path, "utf8");
+  try { return JSON.parse(raw); }
+  catch { throw new CliUsageError(`invalid JSON in ${path}`); }
+}
+
+function visionReasoningError(value: unknown): string | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const vision = (value as Record<string, unknown>).visionSidecar;
+  if (!vision || typeof vision !== "object" || Array.isArray(vision)) return null;
+  const reasoning = (vision as Record<string, unknown>).reasoning;
+  if (reasoning === undefined || isVisionReasoningEffort(reasoning)) return null;
+  return `schema_invalid: visionSidecar.reasoning: must be one of ${VISION_REASONING_EFFORTS.join(", ")}`;
+}
+
+function validateCandidate(value: unknown): ReturnType<typeof validateConfigCandidate> {
+  const error = visionReasoningError(value);
+  return error ? { ok: false, error } : validateConfigCandidate(value);
+}
+
+function normalizeVisionConfig(config: OcxConfig): OcxConfig {
+  const vision = config.visionSidecar;
+  if (!vision || vision.reasoning === undefined) return config;
+  // Keep CLI import/set semantics aligned with the execution path: an omitted or blank model means
+  // the bounded OpenAI vision default, gpt-5.4-mini, not the Dashboard's web-search default.
+  const model = vision.model || "gpt-5.4-mini";
+  const normalized = normalizeVisionReasoningForModel(model, vision.reasoning);
+  if (normalized === undefined) delete vision.reasoning;
+  else vision.reasoning = normalized;
+  return config;
+}
+
+function validate(value: unknown): OcxConfig {
+  const result = validateCandidate(value);
+  if (!result.ok) throw new CliUsageError(result.error);
+  return normalizeVisionConfig(result.config);
+}
+
+export async function handleConfigCommand(argv: string[]): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const action = (args.shift() ?? "show").toLowerCase();
+    const wantsJson = takeFlag(args, "--json");
+    if (action === "show") {
+      const source = takeFlag(args, "--source");
+      rejectArgs(args, USAGE);
+      const diagnostics = readConfigDiagnostics();
+      const config = redact(diagnostics.config);
+      const result = source ? { config, source: diagnostics.source, error: diagnostics.error, warnings: diagnostics.warnings ?? [] } : config;
+      printData(result, true);
+      return;
+    }
+    if (action === "get") {
+      const path = args.shift();
+      if (!path) throw new CliUsageError("config path is required", USAGE);
+      rejectArgs(args, USAGE);
+      const value = redact(getPath(readConfigDiagnostics().config, path), path.split(".").at(-1));
+      if (wantsJson || typeof value === "object") console.log(JSON.stringify(value, null, 2));
+      else console.log(String(value));
+      return;
+    }
+    if (action === "set" || action === "unset") {
+      const path = args.shift();
+      const raw = action === "set" ? args.shift() : undefined;
+      if (!path || (action === "set" && raw === undefined)) throw new CliUsageError("config path and value are required", USAGE);
+      rejectArgs(args, USAGE);
+      // #1835/#1838: the read used to happen OUTSIDE the mutation lock, so a concurrent
+      // edit landing between it and the save was reverted by this whole-snapshot write.
+      // `mutatePersistedConfig` reruns this callback against the latest validated disk
+      // state, so the operation is applied to what is actually there at commit time.
+      let savedValue: unknown = null;
+      const outcome = mutatePersistedConfig(fresh => {
+        // Snapshot BEFORE mutating: comparing after the write compares a value with
+        // itself and would report every no-op as a change, bumping the generation.
+        const before = JSON.stringify(fresh);
+        const candidate = structuredClone(fresh) as unknown as Record<string, unknown>;
+        setPath(candidate, path, raw === undefined ? undefined : parseValue(raw), action === "unset");
+        const config = validate(candidate);
+        savedValue = action === "unset" ? null : getPath(config, path);
+        // Setting the order here is the operator restating it, exactly as through
+        // `ocx account priority` or the management route, so it releases the manual pin
+        // for the same reason those do: a pin made before any order existed would
+        // otherwise outrank every order set afterwards, capping the pool at the pinned
+        // account's tier with nothing on any surface explaining why. `import` is
+        // deliberately not covered — that file supplies its own pin, so there is no
+        // stale one to release.
+        if (pathSegments(path)[0] === "codexAccountPriorities") clearCodexAccountPin(config);
+        // REPLACE rather than merge: `Object.assign` alone cannot remove a key that
+        // `unset` deleted, which would make unset silently succeed while changing nothing.
+        for (const key of Object.keys(fresh)) {
+          if (!(key in (config as unknown as Record<string, unknown>))) {
+            delete (fresh as unknown as Record<string, unknown>)[key];
+          }
+        }
+        Object.assign(fresh, config);
+        return { changed: JSON.stringify(fresh) !== before, value: undefined };
+      });
+      if (outcome.status === "unavailable") {
+        throw new Error(outcome.reason === "conflict"
+          ? "config changed while applying this update; retry"
+          : `config is ${outcome.reason}`);
+      }
+      printData({ ok: true, path, value: redact(savedValue, path.split(".").at(-1)) }, wantsJson,
+        [`${action === "unset" ? "Unset" : "Set"} ${path}.`]);
+      return;
+    }
+    if (action === "validate") {
+      const path = args.shift();
+      rejectArgs(args, USAGE);
+      const result = path ? validateCandidate(loadInput(path)) : (() => {
+        const diagnostics = readConfigDiagnostics();
+        if (diagnostics.error) return { ok: false as const, error: diagnostics.error };
+        return validateCandidate(diagnostics.config);
+      })();
+      printData(result.ok ? { ok: true, source: path ?? getConfigPath() } : result, wantsJson,
+        [result.ok ? "Config is valid." : `Config is invalid: ${result.error}`]);
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+    if (action === "export") {
+      const path = args.shift();
+      if (!path) throw new CliUsageError("export path is required", USAGE);
+      rejectArgs(args, USAGE);
+      const content = `${JSON.stringify(readConfigDiagnostics().config, null, 2)}\n`;
+      if (path === "-") process.stdout.write(content);
+      else { writeFileSync(path, content, { encoding: "utf8", mode: 0o600 }); console.log(`Exported config to ${path}.`); }
+      return;
+    }
+    if (action === "import") {
+      const path = args.shift();
+      const yes = takeFlag(args, "--yes");
+      if (!path) throw new CliUsageError("import path is required", USAGE);
+      if (!yes) throw new CliUsageError("import requires --yes", USAGE);
+      rejectArgs(args, USAGE);
+      saveConfig(validate(loadInput(path)));
+      printData({ ok: true, source: path }, wantsJson, [`Imported config from ${path}. Restart or run ocx sync if needed.`]);
+      return;
+    }
+    throw new CliUsageError(`unknown config command ${action}`, USAGE);
+  });
+}
+
+export const CONFIG_USAGE = USAGE;

package/src/cli/debug.ts

@@ -0,0 +1,228 @@
+import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
+import { DEBUG_ENV, type DebugSettingsView } from "../lib/debug-settings";
+import { runningProxyUpdateHeaders } from "../oauth/login-cli";
+
+type DebugScope = "provider" | "usage" | "injection" | "claude";
+
+async function requireLiveProxy() {
+  const live = await findLiveProxy();
+  if (!live) {
+    console.error("Proxy is not running. Start it with: ocx start");
+    process.exit(1);
+  }
+  return live;
+}
+
+async function fetchDebugSettings(): Promise<DebugSettingsView> {
+  const live = await requireLiveProxy();
+  try {
+    const res = await fetch(`http://${probeHostname(live.hostname)}:${live.port}/api/debug`, {
+      headers: runningProxyUpdateHeaders(),
+    });
+    if (!res.ok) {
+      console.error(`Failed to read debug settings (${res.status})`);
+      process.exit(1);
+    }
+    return await res.json() as DebugSettingsView;
+  } catch (err) {
+    console.error(`Proxy is running but /api/debug is unreachable: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+async function putDebugSettings(body: Record<string, unknown>): Promise<DebugSettingsView> {
+  const live = await requireLiveProxy();
+  const res = await fetch(`http://${probeHostname(live.hostname)}:${live.port}/api/debug`, {
+    method: "PUT",
+    headers: runningProxyUpdateHeaders(),
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    console.error(`Failed to update debug settings (${res.status})${text ? `: ${text.slice(0, 200)}` : ""}`);
+    process.exit(1);
+  }
+  return await res.json() as DebugSettingsView;
+}
+
+function printScopeStatus(scope: DebugScope, view: DebugSettingsView): void {
+  if (scope === "provider") {
+    console.log(`Provider debug: ${view.enabled ? "ON" : "off"}`);
+    console.log(`  env=${view.env.debug ? "on" : "off"}, runtime=${view.runtimeOverride.debug === undefined ? "env/default" : view.runtimeOverride.debug ? "on" : "off"}`);
+    console.log("  Tail: ocx debug provider logs [-f]");
+  } else if (scope === "usage") {
+    console.log(`Usage debug: ${view.usage ? "ON" : "off"}`);
+    console.log(`  env=${view.env.usage ? "on" : "off"}, runtime=${view.runtimeOverride.usage === undefined ? "env/default" : view.runtimeOverride.usage ? "on" : "off"}`);
+    console.log("  Tail: ocx debug usage logs [-f] (via running proxy API)");
+  } else if (scope === "injection") {
+    console.log(`Injection debug: ${view.injection ? "ON" : "off"}`);
+    console.log(`  env=${view.env.injection ? "on" : "off"}, runtime=${view.runtimeOverride.injection === undefined ? "env/default" : view.runtimeOverride.injection ? "on" : "off"}`);
+    console.log("  Lines appear on the proxy console when multi-agent guidance is injected.");
+  } else {
+    console.log(`Claude inbound debug: ${view.claude ? "ON" : "off"}`);
+    console.log(`  env=${view.env.claude ? "on" : "off"}, runtime=${view.runtimeOverride.claude === undefined ? "env/default" : view.runtimeOverride.claude ? "on" : "off"}`);
+    console.log("  View: ocx observe claude-inbound");
+  }
+}
+
+function envDebugEnabled(): boolean {
+  return process.env.OCX_DEBUG === "1"
+    || process.env.OCX_DEBUG_FRAMES === "1";
+}
+
+async function printProviderLogs(follow: boolean): Promise<void> {
+  const live = await requireLiveProxy();
+  const base = `http://${probeHostname(live.hostname)}:${live.port}/api/debug/logs`;
+
+  let after = 0;
+  try {
+    const res = await fetch(`${base}?limit=500`, { headers: runningProxyUpdateHeaders() });
+    if (!res.ok) {
+      console.error(`Failed to read debug logs (${res.status})`);
+      process.exit(1);
+    }
+    const entries = await res.json() as { seq: number; line: string }[];
+    for (const entry of entries) console.log(entry.line);
+    if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+  } catch (err) {
+    console.error(`Failed to read debug logs: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  if (!follow) return;
+
+  while (true) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    try {
+      const res = await fetch(`${base}?after=${after}&limit=500`, { headers: runningProxyUpdateHeaders() });
+      if (!res.ok) continue;
+      const entries = await res.json() as { seq: number; line: string }[];
+      for (const entry of entries) console.log(entry.line);
+      if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+    } catch {
+      /* keep following */
+    }
+  }
+}
+
+async function printUsageLogs(follow: boolean): Promise<void> {
+  const live = await requireLiveProxy();
+  const base = `http://${probeHostname(live.hostname)}:${live.port}/api/debug/usage-logs`;
+
+  let after = 0;
+  try {
+    const res = await fetch(`${base}?limit=500`, { headers: runningProxyUpdateHeaders() });
+    if (!res.ok) {
+      console.error(`Failed to read usage debug logs (${res.status})`);
+      process.exit(1);
+    }
+    const entries = await res.json() as { seq: number; line: string }[];
+    for (const entry of entries) console.log(entry.line);
+    if (entries.length === 0) console.log("(empty — enable with: ocx debug usage on)");
+    if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+  } catch (err) {
+    console.error(`Failed to read usage debug logs: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+
+  if (!follow) return;
+
+  while (true) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    try {
+      const res = await fetch(`${base}?after=${after}&limit=500`, { headers: runningProxyUpdateHeaders() });
+      if (!res.ok) continue;
+      const entries = await res.json() as { seq: number; line: string }[];
+      for (const entry of entries) console.log(entry.line);
+      if (entries.length > 0) after = entries[entries.length - 1]!.seq;
+    } catch {
+      /* keep following */
+    }
+  }
+}
+
+async function handleScopeCommand(scope: DebugScope, actionArgv: string[]): Promise<void> {
+  const action = (actionArgv[0] ?? "status").trim().toLowerCase();
+
+  if (action === "on" || action === "off") {
+    const enabled = action === "on";
+    const body = scope === "provider" ? { debug: enabled }
+      : scope === "usage" ? { usage: enabled }
+        : scope === "injection" ? { injection: enabled }
+          : { claude: enabled };
+    printScopeStatus(scope, await putDebugSettings(body));
+    console.log(`\n${scope} debug is now ${enabled ? "enabled" : "disabled"}.`);
+    return;
+  }
+
+  if (action === "status") {
+    printScopeStatus(scope, await fetchDebugSettings());
+    return;
+  }
+
+  if (action === "reset") {
+    const resetKey = scope === "provider" ? "provider" : scope;
+    printScopeStatus(scope, await putDebugSettings({ reset: resetKey }));
+    console.log(`\nRuntime override cleared for ${scope}; effective value follows env again.`);
+    return;
+  }
+
+  if (action === "logs") {
+    if (scope === "injection" || scope === "claude") {
+      console.error(scope === "claude"
+        ? "Use: ocx observe claude-inbound"
+        : "Injection debug has no buffered log stream; use: ocx observe injection");
+      process.exit(1);
+    }
+    const follow = actionArgv.slice(1).some(arg => arg === "-f" || arg === "--follow");
+    if (scope === "provider") await printProviderLogs(follow);
+    else await printUsageLogs(follow);
+    return;
+  }
+
+  console.error(scope === "injection" || scope === "claude"
+    ? `Usage: ocx debug ${scope} on|off|status|reset`
+    : `Usage: ocx debug ${scope} on|off|status|reset|logs [-f]`);
+  process.exit(1);
+}
+
+function printTopLevelHelp(): void {
+  console.log("Debug commands (proxy must be running):");
+  console.log("");
+  console.log("  ocx debug provider on|off|status|reset|logs [-f]");
+  console.log("  ocx debug usage on|off|status|reset|logs [-f]");
+  console.log("  ocx debug injection on|off|status|reset");
+  console.log("  ocx debug claude on|off|status|reset");
+  console.log("");
+  console.log("Env defaults on start:");
+  console.log("  provider → OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)");
+  console.log(`  usage    → ${DEBUG_ENV.usage}=1`);
+  console.log(`  injection→ ${DEBUG_ENV.injection}=1`);
+  console.log(`  claude   → ${DEBUG_ENV.claude}=1`);
+}
+
+export async function handleDebugCommand(argv: string[]): Promise<void> {
+  const sub = (argv[0] ?? "").trim().toLowerCase();
+
+  if (sub === "provider" || sub === "usage" || sub === "injection" || sub === "claude") {
+    await handleScopeCommand(sub, argv.slice(1));
+    return;
+  }
+
+  if (sub === "" || sub === "help" || sub === "--help" || sub === "-h") {
+    const live = await findLiveProxy();
+    if (!live) {
+      console.log("Proxy is not running — env defaults for the next start:");
+      console.log(`  provider → OCX_DEBUG = ${envDebugEnabled() ? "on" : "off"}`);
+      console.log(`  usage    → ${DEBUG_ENV.usage} = ${process.env[DEBUG_ENV.usage] === "1" ? "on" : "off"}`);
+      console.log(`  injection→ ${DEBUG_ENV.injection} = ${process.env[DEBUG_ENV.injection] === "1" ? "on" : "off"}`);
+      console.log(`  claude   → ${DEBUG_ENV.claude} = ${process.env[DEBUG_ENV.claude] === "1" ? "on" : "off"}`);
+      console.log("");
+    }
+    printTopLevelHelp();
+    return;
+  }
+
+  printTopLevelHelp();
+  process.exit(1);
+}