refactor(cli): fold internal-dispatch and pin help banner

src/cli/dispatch.ts

@@ -14,7 +14,6 @@ import type { ReadyArgs } from "./ready";
 import type { LiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import { hasHelpFlag, printSubcommandUsage, printUsage } from "./help";
-import { dispatchInternalCliCommand, type InternalCliCommand } from "./internal-dispatch";
 import { setIntegrationEnabled, shouldSyncCodexOnStart } from "../codex/desired-state";
 import { syncModelsToCodex } from "../codex/sync";
 import { collectOrcaCodexHomeDiagnostic } from "../codex/home";
@@ -50,18 +49,6 @@ export interface CliDispatchDeps {
 
 type CommandRunner = (deps: CliDispatchDeps) => Promise<number>;
 
-async function runInternalTrayCommand(deps: CliDispatchDeps): Promise<number> {
-  await dispatchInternalCliCommand(deps.command as InternalCliCommand, {
-    trayStart: async () => { await deps.handleTrayProxyStart(); },
-    trayRestart: deps.handleTrayProxyRestart,
-    startupHealth: async () => {
-      const { collectStartupHealth } = await import("../codex/autostart-health");
-      console.log(JSON.stringify(collectStartupHealth(deps.loadConfig())));
-    },
-  });
-  return 0;
-}
-
 const commandRunners: Record<string, CommandRunner> = {
   init: async () => {
     const { runInit } = await import("./init");
@@ -329,12 +316,18 @@ const commandRunners: Record<string, CommandRunner> = {
     await refreshVersionCache(channel);
     return 0;
   },
-  "__tray-start": runInternalTrayCommand,
+  "__tray-start": async deps => {
+    return (await deps.handleTrayProxyStart()) ? 0 : 1;
+  },
   "__tray-restart": async deps => {
     await deps.handleTrayProxyRestart();
     return Number(process.exitCode ?? 0);
   },
-  "__startup-health": runInternalTrayCommand,
+  "__startup-health": async deps => {
+    const { collectStartupHealth } = await import("../codex/autostart-health");
+    console.log(JSON.stringify(collectStartupHealth(deps.loadConfig())));
+    return 0;
+  },
   "__tray-host": async () => {
     const { runWindowsTrayHost } = await import("../tray/windows");
     await runWindowsTrayHost();

src/cli/help.ts

@@ -51,6 +51,12 @@ Usage:
   ocx combo <sub>             Combo failover/round-robin routing
   ocx agent <sub>             Subagents, injection, effort caps, and sidecars
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
+  ocx route <sub>             Routing features (combo, policy)
+  ocx logs [filters]          Alias of ocx observe logs
+  ocx usage [--range <7d|30d|all>]  Alias of ocx observe usage
+  ocx storage [--json]        Alias of ocx observe storage
+  ocx memory [--json]         Alias of ocx observe memory
+  ocx api-key <sub>           Alias of ocx access key
   ocx access <sub>            External API keys and endpoint information
   ocx export --client <id>    Print a client config wired to the running proxy (7 clients)
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration

tests/cli-registry.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { CLI_COMMANDS, findCommand } from "../src/cli/registry";
 import { DISPATCH_ALIASES, DISPATCH_COMMANDS } from "../src/cli/dispatch";
 
@@ -76,8 +78,53 @@ describe("CLI command registry parity", () => {
     }
   });
 
+  test("internal tray commands are dispatched as explicit runners", () => {
+    const internalRunners = [
+      "__tray-start",
+      "__tray-restart",
+      "__startup-health",
+      "__tray-host",
+      "__gui-update-worker",
+      "__refresh-version",
+    ];
+    for (const name of internalRunners) {
+      expect(DISPATCH_COMMANDS).toContain(name);
+      const entry = CLI_COMMANDS.find(command => command.name === name);
+      expect(entry?.hidden).toBe(true);
+    }
+  });
+
   test("entry names are unique", () => {
     const names = CLI_COMMANDS.map(entry => entry.name);
     expect(new Set(names).size).toBe(names.length);
   });
 });
+
+describe("help banner command coverage", () => {
+  // The banner is curated (aliases shown inline, subcommands elided), so it is
+  // not required to match the registry exactly. It must never drop a visible
+  // command entirely: every visible canonical command has to appear.
+  test("every visible canonical command appears in the printUsage banner", () => {
+    const helpSrc = readFileSync(fileURLToPath(new URL("../src/cli/help.ts", import.meta.url)), "utf8");
+
+    // Commands whose `name` is only ever used as another entry's alias
+    // (setup/eject/remove/model) are shown inline as "(alias: ...)" rather
+    // than as their own banner line, so they are not required here.
+    const aliasNames = new Set<string>();
+    for (const entry of CLI_COMMANDS) {
+      for (const alias of entry.aliases ?? []) aliasNames.add(alias);
+    }
+
+    const missing = CLI_COMMANDS.filter(entry => {
+      if (entry.hidden) return false;
+      if (aliasNames.has(entry.name)) return false;
+      // A command counts as covered when the banner carries its full usage
+      // line or its canonical name at the start of an `ocx <name>` banner line.
+      const escaped = entry.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const commandLine = new RegExp(`^\\s*ocx\\s+${escaped}(?:\\s|$)`, "m");
+      return !helpSrc.includes(entry.usage) && !commandLine.test(helpSrc);
+    }).map(entry => entry.name);
+
+    expect(missing).toEqual([]);
+  });
+});