@bitkyc08/opencodex 2.77.0 → 2.78.0

package/src/cli/config-command.ts

@@ -14,7 +14,7 @@ const USAGE = `Usage:
   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 export <path|-> [--json]
   ocx config import <path|-> --yes [--json]`;
 
 /**
@@ -205,14 +205,21 @@ function validate(value: unknown): OcxConfig {
 }
 
 export async function handleConfigCommand(argv: string[]): Promise<number> {
-  return runCliAction(async () => {
+  let outcome = 0;
+  const status = await runCliAction(async () => {
     const args = [...argv];
-    const action = (args.shift() ?? "show").toLowerCase();
     const wantsJson = takeFlag(args, "--json");
+    const source = takeFlag(args, "--source");
+    if (args.includes("--json") || args.includes("--source")) throw new CliUsageError("config flags may only be specified once", USAGE);
+    const action = (args.shift() ?? "show").toLowerCase();
+    if (source && action !== "show") throw new CliUsageError("--source is only supported for config show", USAGE);
     if (action === "show") {
-      const source = takeFlag(args, "--source");
       rejectArgs(args, USAGE);
       const diagnostics = readConfigDiagnostics();
+      if (diagnostics.source === "fallback" || diagnostics.error) {
+        console.error(`Warning: Config at ${getConfigPath()} is invalid or unreadable; defaults are being shown for invalid settings. Run: ocx config validate. Inspect: ocx config show --source.`);
+        if (!source) outcome = 1;
+      }
       const redacted = redact(diagnostics.config);
       const note = await readRemoteHubConfigNote(diagnostics.config);
       // First key, not last: it has to be read before the empty `providers` map that misled a
@@ -228,7 +235,12 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       const path = args.shift();
       if (!path) throw new CliUsageError("config path is required", USAGE);
       rejectArgs(args, USAGE);
-      const value = redact(getPath(readConfigDiagnostics().config, path), pathSegments(path).at(-1));
+      const diagnostics = readConfigDiagnostics();
+      if (diagnostics.source === "fallback" || diagnostics.error) {
+        console.error(`Warning: Config at ${getConfigPath()} is invalid or unreadable; defaults are being shown for invalid settings. Run: ocx config validate. Inspect: ocx config show --source.`);
+        outcome = 1;
+      }
+      const value = redact(getPath(diagnostics.config, path), pathSegments(path).at(-1));
       if (wantsJson || typeof value === "object") console.log(JSON.stringify(value, null, 2));
       else console.log(String(value));
       return;
@@ -236,7 +248,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
     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);
+      if (!path || (action === "set" && raw === undefined)) throw new CliUsageError(action === "unset" ? "config path is required" : "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.
@@ -288,7 +300,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       })();
       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;
+      if (!result.ok) outcome = 1;
       return;
     }
     if (action === "export") {
@@ -297,7 +309,10 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       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}.`); }
+      else {
+        writeFileSync(path, content, { encoding: "utf8", mode: 0o600 });
+        printData({ ok: true, path }, wantsJson, [`Exported config to ${path}.`]);
+      }
       return;
     }
     if (action === "import") {
@@ -312,6 +327,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
     }
     throw new CliUsageError(`unknown config command ${action}`, USAGE);
   });
+  return status || outcome;
 }
 
 export const CONFIG_USAGE = USAGE;

package/src/cli/dispatch.ts

@@ -10,8 +10,7 @@ import type { ProxyRestartStartOutcome } from "./tray-proxy";
  * never needs to import the entry module back (no cycle).
  */
 import { CLI_COMMANDS } from "./registry";
-import { isValidProviderName } from "../config/provider-name";
-import type { CliHead } from "./root";
+import { uninstallArgsError, type CliHead } from "./root";
 import type { ReadyArgs } from "./ready";
 import type { LivenessIo, LiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
@@ -300,6 +299,11 @@ const commandRunners: Record<string, CommandRunner> = {
     return Number(process.exitCode ?? 0);
   },
   uninstall: async deps => {
+    const error = uninstallArgsError("uninstall", deps.args);
+    if (error) {
+      console.error(error);
+      return 2;
+    }
     await deps.handleUninstall();
     return Number(process.exitCode ?? 0);
   },
@@ -376,62 +380,8 @@ const commandRunners: Record<string, CommandRunner> = {
     return 0;
   },
   logout: async deps => {
-    // Argv is parsed BEFORE any store access, which is the whole point of this shape.
-    // Previously `args[1]` was taken as the provider name with no parsing, so
-    // `ocx logout --json` called removeCredential("--json"), printed "Logged out of
-    // --json." and exited 0 -- a silent false success, the worst outcome for a caller
-    // that can only see the exit code.
-    //
-    // That is not merely a wasted call. `normalizeAuthStore` copies every top-level key
-    // it finds, so a hand-edited, legacy, or corrupted auth.json containing a `--json`
-    // key would have its active account deleted -- and the key dropped entirely if that
-    // was its last account. A flag must never reach the store as a provider name.
-    const logoutArgs = deps.args.slice(1);
-    const wantsJson = logoutArgs.includes("--json");
-    // Any leading dash is an option, not a provider. Matching only `--` left the same defect
-    // one dash shorter: `ocx logout -j` treated `-j` as the provider name and, with a `-j` key
-    // present in the store, deleted it and exited 0.
-    const isOption = (arg: string): boolean => arg.startsWith("-");
-    const positionals = logoutArgs.filter(arg => !isOption(arg));
-    const unknownFlags = logoutArgs.filter(arg => isOption(arg) && arg !== "--json");
-    const name = (positionals[0] ?? "").trim().toLowerCase();
-
-    // Usage failures exit 2 and touch nothing. A missing provider is a usage error; a
-    // provider that simply has no credential is a not-found (4) further down, because the
-    // vocabulary distinguishes "you called this wrong" from "the thing is not there".
-    //
-    // The shape check is `isValidProviderName`, not another dash test. Rejecting a leading
-    // ASCII `-` fixed `-j` and still let `logout —json` through with a Unicode dash, which is
-    // the same defect a third time: each patch named one spelling instead of the class. The
-    // canonical validator states the rule positively -- start and end alphanumeric, internal
-    // `._-` allowed -- so `github-copilot` and `google-antigravity` pass while every dash
-    // variant, empty string, and reserved name fails. Anything that is not a possible
-    // provider id cannot reach the store at all.
-    const malformedName = Boolean(name) && !isValidProviderName(name);
-    if (unknownFlags.length > 0 || positionals.length > 1 || !name || malformedName) {
-      const problem = unknownFlags.length > 0
-        ? `unknown option ${unknownFlags[0]}`
-        : positionals.length > 1 ? "too many arguments"
-        : malformedName ? `not a valid provider name: ${name}`
-        : "missing provider";
-      console.error(`Usage: ocx logout <provider> [--json]  (${problem})`);
-      return 2;
-    }
-
-    // The disposition comes from inside the store mutation, not from a read-then-remove
-    // preflight. `mutateStore` serializes writes, so a preflight leaves a window where a
-    // concurrent logout removes the same account and BOTH callers exit 0 claiming a removal --
-    // a false success again, just a narrower one than the flag bug above.
-    const { removeCredential } = await import("../oauth/store");
-    const outcome = await removeCredential(name);
-    if (outcome === "not-found") {
-      if (wantsJson) console.log(JSON.stringify({ schemaVersion: 1, ok: false, provider: name, removed: false, reason: "not_found" }, null, 2));
-      else console.error(`No stored credential for '${name}'.`);
-      return 4;
-    }
-    if (wantsJson) console.log(JSON.stringify({ schemaVersion: 1, ok: true, provider: name, removed: true }, null, 2));
-    else console.log(`Logged out of ${name}.`);
-    return 0;
+    const { handleLogoutCommand } = await import("./logout-command");
+    return handleLogoutCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   sync: async deps => {
     const syncArgs = deps.args.slice(1);
@@ -538,7 +488,7 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   v2: async deps => {
     const { cmdV2 } = await import("./v2");
-    return await cmdV2(deps.args.slice(1), {}, async () => (await deps.findLiveProxy())?.port);
+    return await cmdV2(deps.args.slice(1), { runtimeApi: { findLiveProxy: deps.findLiveProxy } }, async () => (await deps.findLiveProxy())?.port);
   },
   connect: async deps => {
     const { handleConnectCommand } = await import("./connect");
@@ -550,7 +500,7 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   "remote-workspace": async deps => {
     const { runRemoteWorkspaceCommand } = await import("./remote-workspace");
-    return await runRemoteWorkspaceCommand(deps.args.slice(1));
+    return await runRemoteWorkspaceCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   disconnect: async deps => {
     const { handleDisconnectCommand } = await import("./connect");
@@ -570,7 +520,8 @@ const commandRunners: Record<string, CommandRunner> = {
     const cacheGateSnapshot = deps.loadConfig();
     const desiredDisabled = !shouldSyncCodexOnStart(cacheGateSnapshot);
     const invalidated = withCatalogWriteSerialization(owningCodexHome, permit =>
-      invalidateCodexModelsCacheWithPermitOutcome(permit, owningCodexHome, { allowWhenDesiredDisabled: true }));
+      invalidateCodexModelsCacheWithPermitOutcome(permit, owningCodexHome, { allowWhenDesiredDisabled: true }),
+    { intent: "cache", writer: "sync-cache" });
     const cacheJson = cacheArgs.includes("--json");
     const jsonSafeLog = cacheJson
       ? { log: (...values: unknown[]) => console.error(...values), error: (...values: unknown[]) => console.error(...values) }
@@ -633,6 +584,10 @@ const commandRunners: Record<string, CommandRunner> = {
       console.log("No Codex catalog to derive a cache from; nothing to sync.");
     } else if (unchanged) {
       console.log("Codex model cache is already current; nothing to sync.");
+    } else if (invalidated.kind === "unavailable"
+      && (invalidated.reason === "foreign-owner" || invalidated.reason === "owner-unknown")) {
+      const { FOREIGN_CODEX_HOME_OWNER_MESSAGE, UNKNOWN_CODEX_HOME_OWNER_MESSAGE } = await import("../codex/catalog/routed-removal");
+      console.error(invalidated.reason === "foreign-owner" ? FOREIGN_CODEX_HOME_OWNER_MESSAGE : UNKNOWN_CODEX_HOME_OWNER_MESSAGE);
     } else if (!ok) {
       console.error(`Cache refresh did not complete (${invalidated.kind}). The Codex model cache was not rewritten.`);
     }
@@ -697,19 +652,33 @@ const commandRunners: Record<string, CommandRunner> = {
     switch (deps.args[1]) {
       case "install": {
         const r = installCodexShim();
-        const { healthy, summary } = diagnoseCodexShim();
+        const { healthy, runnable, active, summary } = diagnoseCodexShim();
+        const success = !r.refused && (runnable ?? healthy);
         const { collectCodexShimReadinessWarnings } = await import("./codex-shim-readiness");
-        const warnings = healthy
+        const warnings = success
           ? collectCodexShimReadinessWarnings()
           : [];
-        console.log(`${r.installed && warnings.length === 0 ? "✅ " : "⚠️  "}${r.message}`);
+        console.log(`${success && healthy && warnings.length === 0 ? "✅ " : "⚠️  "}${r.message}`);
         for (const warning of warnings) console.warn(`   ${warning}`);
-        if (!healthy) console.error(`Codex shim installation is unhealthy: ${summary}`);
-        return healthy ? 0 : 1;
+        if (success && active !== undefined && active !== true) {
+          const { overlayActivationHint } = await import("../codex/shim-overlay");
+          console.warn(`   ${overlayActivationHint()}`);
+        }
+        if (!success) console.error(`${r.refused ? "Codex shim installation was refused" : "Codex shim installation is unhealthy"}: ${summary}`);
+        return success ? 0 : 1;
       }
-      case "status":
+      case "status": {
+        const extra = deps.args.slice(2);
+        if (extra.length > 0) {
+          console.error(extra.some(isJsonOption)
+            ? "ocx codex-shim status does not support --json; use ocx status --json (codexShim)."
+            : "ocx codex-shim status does not accept arguments or options.");
+          console.error("Usage: ocx codex-shim status");
+          return 2;
+        }
         console.log(codexShimStatus());
         break;
+      }
       case "uninstall":
       case "remove": {
         const r = uninstallCodexShim();
@@ -731,7 +700,7 @@ const commandRunners: Record<string, CommandRunner> = {
     }
     const { runUpdate } = await import("../update");
     await runUpdate();
-    return 0;
+    return Number(process.exitCode ?? 0);
   },
   "__refresh-version": async deps => {
     // Hidden, detached helper spawned by the update prompt to refresh the
@@ -786,6 +755,10 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   health: async deps => {
     const healthArgs = deps.args.slice(1);
+    if (healthArgs.length > 1 || (healthArgs.length === 1 && healthArgs[0] !== "--json")) {
+      console.error("Usage: ocx health [--json]\nSee: ocx help health");
+      return 2;
+    }
     const wantsHealthJson = healthArgs.includes("--json");
     // A proxy that has only just bound can miss a single probe while its event loop
     // is still settling startup work — the same just-started race the stop paths
@@ -844,7 +817,7 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   companion: async deps => {
     const { handleCompanionCommand } = await import("./companion");
-    return await handleCompanionCommand(deps.args.slice(1));
+    return await handleCompanionCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   route: async deps => {
     if (deps.args[1] !== "combo" && deps.args[1] !== "policy") {
@@ -869,7 +842,7 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   observe: async deps => {
     const { handleObserveCommand } = await import("./observe");
-    return await handleObserveCommand(deps.args.slice(1));
+    return await handleObserveCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   inspect: async deps => {
     const { handleInspectCommand } = await import("./inspect");
@@ -877,11 +850,11 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   logs: async deps => {
     const { handleObserveCommand } = await import("./observe");
-    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
+    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)], { findLiveProxy: deps.findLiveProxy });
   },
   usage: async deps => {
     const { handleObserveCommand } = await import("./observe");
-    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
+    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)], { findLiveProxy: deps.findLiveProxy });
   },
   storage: async deps => {
     // `ocx storage` used to be a pure alias of `observe storage`, which reached only the report
@@ -897,11 +870,11 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   access: async deps => {
     const { handleAccessCommand } = await import("./access");
-    return await handleAccessCommand(deps.args.slice(1));
+    return await handleAccessCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   "api-key": async deps => {
     const { handleAccessCommand } = await import("./access");
-    return await handleAccessCommand(["key", ...deps.args.slice(1)]);
+    return await handleAccessCommand(["key", ...deps.args.slice(1)], { findLiveProxy: deps.findLiveProxy });
   },
   api: async deps => {
     const { handleApiCommand } = await import("./api-protocols");
@@ -925,21 +898,21 @@ const commandRunners: Record<string, CommandRunner> = {
       // integrations `client` manages, so they get their own subcommand rather than being
       // folded into one that means something else.
       const { handleIntegrationCommand } = await import("./inspect");
-      return await handleIntegrationCommand(deps.args.slice(1));
+      return await handleIntegrationCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
     } else if (integration === "claude") {
       const { handleClaudeConfigCommand } = await import("./integrations");
       return await handleClaudeConfigCommand(deps.args.slice(2));
     } else if (integration === "client") {
       const { handleClientIntegrationCommand } = await import("./integrations");
-      return await handleClientIntegrationCommand(deps.args.slice(2));
+      return await handleClientIntegrationCommand(deps.args.slice(2), { findLiveProxy: deps.findLiveProxy });
     } else {
-      console.error("Usage: ocx integration <claude|grok|client> <subcommand>");
+      console.error("Usage: ocx integration <claude|grok|client|native> <subcommand>\nSee: ocx help integration");
       return 2;
     }
   },
   system: async deps => {
     const { handleSystemCommand } = await import("./system-command");
-    return await handleSystemCommand(deps.args.slice(1));
+    return await handleSystemCommand(deps.args.slice(1), { findLiveProxy: deps.findLiveProxy });
   },
   config: async deps => {
     const { handleConfigCommand } = await import("./config-command");
@@ -958,7 +931,7 @@ const commandRunners: Record<string, CommandRunner> = {
     // "ocx claude desktop" → write Desktop 3P config
     if (deps.args[1] === "desktop") {
       const { handleClaudeDesktopCommand } = await import("./claude-desktop");
-      const exitCode = await handleClaudeDesktopCommand(deps.args.slice(2));
+      const exitCode = await handleClaudeDesktopCommand(deps.args.slice(2), { findLiveProxyImpl: deps.findLiveProxy });
       if (exitCode !== 0) return exitCode;
       return 0;
     }

package/src/cli/doctor.ts

@@ -33,6 +33,7 @@ import {
 } from "../codex/subagent-model-fallback";
 import { readCatalog, readCodexCatalogPath, readConfiguredDefaultModel } from "../codex/catalog/parsing";
 import { diagnoseCodexShim, findCodexOnPath, isWindowsInteropDir, type CodexShimDiagnostic } from "../codex/shim";
+import { overlayActivationHint } from "../codex/shim-overlay";
 import { providerTableString, rootTomlString } from "../codex/injected-marker";
 import { countPendingOpencodexHistory } from "../codex/history-provider";
 import {
@@ -481,28 +482,41 @@ export function collectProviderApiKeyDiagnostics(
 
 export type CodexEnvKeyReadinessDiagnostic = {
   envName: string;
-  shimState: "missing" | "unhealthy";
+  shimState: "missing" | "unhealthy" | "inactive";
   detail: string;
   action: string;
 };
 
+/** Shell activation and legacy migration are independent of admission-token readiness. */
+export function formatCodexShimDoctorLines(shim: CodexShimDiagnostic, platform = process.platform): string[] {
+  if (platform === "win32" || !shim.installed) return [];
+  const inactiveOverlay = shim.runnable === true && shim.active === false;
+  const healthyLegacy = shim.healthy && shim.runnable === undefined;
+  return inactiveOverlay || healthyLegacy ? shim.summary.split("\n").map(line => `       ${line}`) : [];
+}
+
 /** Warn when routed Codex cannot obtain its configured admission token at launch. */
 export function collectCodexEnvKeyReadiness(
   configText: string | null,
   env: EnvMap,
   shim: CodexShimDiagnostic,
   serviceTokenPresent: boolean,
+  shimActivationShown = false,
 ): CodexEnvKeyReadinessDiagnostic | null {
   if (!configText || rootTomlString(configText, "model_provider") !== "opencodex") return null;
   const envName = providerTableString(configText, "opencodex", "env_key")?.trim();
   const envValue = envName ? ownEnvValue(env, envName) : undefined;
   if (!envName || envValue?.trim() || shim.healthy || !serviceTokenPresent) return null;
-  const shimState = shim.installed ? "unhealthy" : "missing";
+  const shimState = shim.runnable && shim.active === false ? "inactive" : shim.installed ? "unhealthy" : "missing";
   return {
     envName,
     shimState,
     detail: `Codex uses env_key ${envName}, but that variable is unset and the OpenCodex shim is ${shimState}; the service token file exists but plain Codex does not load it`,
-    action: `Run 'ocx codex-shim install' to repair launch-time token injection, or export ${envName} in the process that starts Codex`,
+    action: shimState === "inactive"
+      ? shimActivationShown
+        ? `Activate the PATH shim as shown under Codex restart safety, or export ${envName} in the process that starts Codex`
+        : `${overlayActivationHint()} Or export ${envName} in the process that starts Codex`
+      : `Run 'ocx codex-shim install' to repair launch-time token injection, or export ${envName} in the process that starts Codex`,
   };
 }
 
@@ -1349,11 +1363,14 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     try { return readFileSync(codexConfigPath, "utf8"); } catch { return null; }
   })();
   const serviceTokenPresent = Boolean(readInstalledServiceToken()?.trim());
+  const codexShim = diagnoseCodexShim();
+  const codexShimLines = formatCodexShimDoctorLines(codexShim);
   const codexEnvKeyReadiness = collectCodexEnvKeyReadiness(
     codexConfigText,
     process.env,
-    diagnoseCodexShim(),
+    codexShim,
     serviceTokenPresent,
+    codexShimLines.length > 0,
   );
   // Use the same attested live startup verdict as `ocx status` when the proxy is already
   // identity-verified. A shell-local systemd probe can be a false negative for a system-wide
@@ -1366,6 +1383,7 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   console.log("\nCodex restart safety");
   console.log(`  ${startup.rebootSafe ? "ok " : "!! "} ${startupHealthSummary(startup)}`);
   console.log(`       ${formatStartupRoutingDetail(startup)}`);
+  for (const line of codexShimLines) console.log(line);
 
   console.log("\nCodex runtime selection");
   {

package/src/cli/help-catalog.ts

@@ -2,8 +2,8 @@ import { CAPABILITIES, type Capability } from "./capabilities";
 import { CLI_COMMANDS, findCommand, type CliCommandEntry } from "./registry";
 
 export type HelpResolution =
-  | { kind: "entry"; entry: CliCommandEntry; canonicalName: string; children: readonly Capability[] }
-  | { kind: "capability"; path: string[]; capability: Capability }
+  | { kind: "entry"; entry: CliCommandEntry; canonicalName: string; capability?: Capability; children: readonly Capability[] }
+  | { kind: "capability"; path: string[]; capability: Capability; children: readonly Capability[] }
   | { kind: "prefix"; path: string[]; children: readonly Capability[] }
   | { kind: "models-context"; path: string[] }
   | { kind: "unavailable"; path: string[]; parent?: string[] };
@@ -22,6 +22,18 @@ function canonicalEntry(entry: CliCommandEntry): CliCommandEntry {
   return CLI_COMMANDS.find(candidate => candidate.aliases?.includes(entry.name)) ?? entry;
 }
 
+/** Help-only aliases from access dispatch; never rewrite execution argv or operands. */
+function canonicalHelpPath(requested: readonly string[], entry: CliCommandEntry): string[] {
+  const path = entry.name === "api-key"
+    ? ["access", "key", ...requested.slice(1)]
+    : [canonicalEntry(entry).name, ...requested.slice(1)];
+  if (path[0] === "access") {
+    if (path[1] === "keys") path[1] = "key";
+    if (path[1] === "key" && path[2] === "delete") path[2] = "remove";
+  }
+  return path;
+}
+
 export interface HelpRecoveryCandidate {
   names: string[];
   path: string[];
@@ -35,19 +47,24 @@ export function helpRecoveryCandidates(parent: readonly string[] = []): HelpReco
       if (entry.hidden) continue;
       const canonical = canonicalEntry(entry);
       if (canonical.hidden) continue;
-      const candidate = candidates.get(canonical.name) ?? { names: [], path: [canonical.name] };
+      const path = canonicalHelpPath([entry.name], entry);
+      const identity = path.join(" ");
+      const candidate = candidates.get(identity) ?? { names: [], path };
       candidate.names = [...new Set([...candidate.names, entry.name, ...(entry.aliases ?? [])])];
-      candidates.set(canonical.name, candidate);
+      candidates.set(identity, candidate);
     }
   } else {
-    if (parent.length >= MAX_DOCUMENTED_DEPTH) return [];
     const entry = findCommand(parent[0]);
     if (!entry || entry.hidden) return [];
-    const prefix = [canonicalEntry(entry).name, ...parent.slice(1)];
+    const prefix = canonicalHelpPath(parent, entry);
+    if (prefix.length >= MAX_DOCUMENTED_DEPTH) return [];
     for (const documented of DOCUMENTED_PATHS) {
       if (documented.length <= prefix.length || !startsWithPath(documented, prefix)) continue;
       const path = documented.slice(0, prefix.length + 1);
-      candidates.set(path.join(" "), { names: [path[path.length - 1]], path });
+      const names = [path[path.length - 1]];
+      if (path.join(" ") === "access key") names.push("keys");
+      if (path.join(" ") === "access key remove") names.push("delete");
+      candidates.set(path.join(" "), { names, path });
     }
   }
   return [...candidates.values()];
@@ -58,19 +75,19 @@ export function resolveHelpPath(requested: readonly string[]): HelpResolution {
   const entry = requested[0] ? findCommand(requested[0]) : undefined;
   if (!entry) return { kind: "unavailable", path: [...requested] };
   // Keep exact-name alias entries for root help; nested topics use the owner.
-  const canonical = canonicalEntry(entry);
+  const path = canonicalHelpPath(requested, entry);
   const declared = CAPABILITIES.filter(capability => !findCommand(capability.command[0])?.hidden);
   if (requested.length === 1) return {
-    kind: "entry", entry, canonicalName: canonical.name,
-    children: entry.hidden ? [] : declared.filter(candidate => candidate.command.length > 1 && candidate.command[0] === canonical.name),
+    kind: "entry", entry, canonicalName: path.join(" "),
+    capability: entry.hidden ? undefined : declared.find(candidate => candidate.command.length === path.length && startsWithPath(candidate.command, path)),
+    children: entry.hidden ? [] : declared.filter(candidate => candidate.command.length > path.length && startsWithPath(candidate.command, path)),
   };
-  const path = [canonical.name, ...requested.slice(1)];
   if (path.length === 2 && path[0] === "models" && path[1] === "context") {
     return { kind: "models-context", path };
   }
   const capability = declared.find(candidate => candidate.command.length === path.length && startsWithPath(candidate.command, path));
-  if (capability) return { kind: "capability", path, capability };
-  const children = declared.filter(candidate => startsWithPath(candidate.command, path));
+  const children = declared.filter(candidate => candidate.command.length > path.length && startsWithPath(candidate.command, path));
+  if (capability) return { kind: "capability", path, capability, children };
   if (children.length) return { kind: "prefix", path, children };
 
   for (let length = Math.min(path.length - 1, MAX_DOCUMENTED_DEPTH); length > 1; length--) {
@@ -80,5 +97,5 @@ export function resolveHelpPath(requested: readonly string[]): HelpResolution {
       return { kind: "unavailable", path, parent };
     }
   }
-  return { kind: "unavailable", path, parent: [canonical.name] };
+  return { kind: "unavailable", path, parent: [path[0]] };
 }

package/src/cli/help-recovery.ts

@@ -35,9 +35,9 @@ function distance(left: string, right: string, limit: number): number {
 export function suggestHelpPaths(path: readonly string[]): string[][] {
   if (!path.length || path.length > MAX_PATH_DEPTH || !path.every(safeToken)) return [];
   const result = resolveHelpPath(path);
-  if (result.kind !== "unavailable") return [];
+  if (result.kind !== "unavailable" || result.path.length > MAX_PATH_DEPTH) return [];
   const parent = result.parent ?? [];
-  const token = path[parent.length].toLowerCase();
+  const token = result.path[parent.length].toLowerCase();
   const limit = token.length < 6 ? 1 : 2;
   return helpRecoveryCandidates(parent).map(candidate => ({
     path: candidate.path,

package/src/cli/help.ts

@@ -1,4 +1,5 @@
 import { resolveHelpPath } from "./help-catalog";
+import type { Capability } from "./capabilities";
 import { MODELS_CONTEXT_DETAILS, MODELS_CONTEXT_USAGE } from "./help-models-context";
 import { renderRootHelp } from "./help-navigation";
 import { formatHelpRecovery } from "./help-recovery";
@@ -40,7 +41,7 @@ Usage:
   ocx recover-history --ocx-compaction <thread-id> --yes
                                Back up and make one ocx1-compacted thread replayable by native Codex
   ocx uninstall               Remove service/shim/config and restore native Codex (alias: remove)
-  ocx service [sub]           Run as a background service (default: install/update/start)
+  ocx service [sub]           Run as a background service (default: install if absent, otherwise repair)
   ocx codex-shim <sub>        Auto-start proxy when \`codex\` launches (install|status|uninstall|remove)
   ocx tray <sub>              Windows status tray (install|start|stop|status|uninstall)
   ocx ensure                  Ensure the proxy is running and Codex config/cache are current
@@ -94,9 +95,9 @@ Usage:
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection
-  ocx config <sub>            Validated configuration show/get/set/import/export
+  ocx config [sub]            Validated configuration show/get/set/import/export
   ocx companion <show|set|reset>  Menu-bar and widget companion usage settings
-  ocx lab <sub>               Read-only Compatibility Lab projection inspection
+  ocx lab <sub>               Inspect Lab evidence and control local automation
   ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile
@@ -122,6 +123,17 @@ export function hasHelpFlag(values: string[]): boolean {
   return values.some(value => value === "--help" || value === "-h" || value === "help");
 }
 
+function printCapabilityDetails(capability: Capability, write: (text: string) => void, shown: readonly string[] = []): void {
+  if (capability.flags.length) {
+    write("\nDeclared flags:");
+    for (const flag of capability.flags) {
+      write(`  ${flag.name}${flag.value && flag.value !== "boolean" ? ` <${flag.value}>` : ""}${flag.required ? " (required)" : ""}  ${flag.summary}`);
+    }
+  }
+  const details = capability.details?.filter(detail => !shown.includes(detail));
+  if (details?.length) write(`\n${details.join("\n")}`);
+}
+
 export function printSubcommandUsage(
   name: string | undefined,
   path?: readonly string[],
@@ -142,6 +154,7 @@ export function printSubcommandUsage(
   if (result.kind === "entry") {
     write(`Usage: ${result.entry.usage}\n\n${result.entry.summary}`);
     if (result.entry.details?.length) write(`\n${result.entry.details.join("\n")}`);
+    if (result.capability) printCapabilityDetails(result.capability, write, result.entry.details);
     if (result.children.length) {
       write("\nDeclared commands (incomplete):");
       for (const child of result.children) write(`  ocx help ${child.command.join(" ")}  ${child.summary}`);
@@ -154,15 +167,16 @@ export function printSubcommandUsage(
     write(`Usage:\n${MODELS_CONTEXT_USAGE}\n\n${MODELS_CONTEXT_DETAILS.join("\n")}`);
   } else if (result.kind === "capability") {
     const { capability } = result;
-    write(`Command: ocx ${result.path.join(" ")}\n\n${capability.summary}`);
-    if (capability.flags.length) {
-      write("\nDeclared flags:");
-      for (const flag of capability.flags) {
-        write(`  ${flag.name}${flag.value && flag.value !== "boolean" ? ` <${flag.value}>` : ""}${flag.required ? " (required)" : ""}  ${flag.summary}`);
-      }
+    const heading = capability.usage !== undefined ? `Usage: ${capability.usage}` : `Command: ocx ${result.path.join(" ")}`;
+    write(`${heading}\n\n${capability.summary}`);
+    printCapabilityDetails(capability, write);
+    if (result.children.length) {
+      write("\nDeclared commands (incomplete):");
+      for (const child of result.children) write(`  ocx help ${child.command.join(" ")}  ${child.summary}`);
+    }
+    if (capability.usage === undefined) {
+      write("\nCapability metadata is incomplete; this is not the full operand grammar.");
     }
-    if (capability.details?.length) write(`\n${capability.details.join("\n")}`);
-    write("\nCapability metadata is incomplete; this is not the full operand grammar.");
   } else {
     write(`Command group: ocx ${result.path.join(" ")}\n\nDeclared commands (incomplete):`);
     for (const child of result.children) write(`  ocx ${child.command.join(" ")}  ${child.summary}`);