@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/cli/account-auth.ts

@@ -6,6 +6,7 @@ import { warnIfCodexCatalogRefreshPending } from "./account-catalog-refresh";
 import { isCodexResetCreditOperationId } from "../codex/reset-credit-recovery";
 import { BROWSER_LAUNCH_FAILED_NOTICE } from "../lib/browser-launch-notice";
 import {
+  RuntimeApiError,
   CliUsageError,
   printData,
   readSecretLine,
@@ -465,18 +466,25 @@ async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<v
   }
   rejectArgs(args, USAGE);
   const accountId = rawId ? (rawId === "main" ? "__main__" : rawId) : undefined;
-  const result = consume
-    ? await runtimeRequest("/api/grok/reset-coupons/consume", {
-      method: "POST",
-      // Spread, not `operationId: undefined`: the server distinguishes an absent
-      // key from a caller who asked for a stable idempotency identity.
-      body: JSON.stringify({ accountId, tokenId, ...(operationId === undefined ? {} : { operationId }) }),
-    }, deps)
-    : await runtimeRequest(
-      `/api/grok/reset-coupons${accountId ? `?accountId=${encodeURIComponent(accountId)}` : ""}`,
-      {},
-      deps,
-    );
+  const effectiveOperationId = consume ? operationId ?? crypto.randomUUID() : undefined;
+  let result: unknown;
+  try {
+    result = consume
+      ? await runtimeRequest("/api/grok/reset-coupons/consume", {
+        method: "POST", body: JSON.stringify({ accountId, tokenId, operationId: effectiveOperationId }),
+      }, deps)
+      : await runtimeRequest(`/api/grok/reset-coupons${accountId ? `?accountId=${encodeURIComponent(accountId)}` : ""}`, {}, deps);
+  } catch (error) {
+    const apiError = error instanceof RuntimeApiError ? error : undefined;
+    const body = apiError?.body as { error?: { code?: string } } | null | undefined;
+    const code = body && typeof body === "object" ? body.error?.code : undefined;
+    if (consume && (!apiError || (!apiError.code && (
+      (!code && apiError.status >= 500) || ["attempt_unresolved", "attempt_in_progress", "attempt_reconcile_failed", "operation_state_changed", "redeem_failed"].includes(code ?? "")
+    )))) {
+      throw new RuntimeApiError(`Coupon redemption outcome is unconfirmed. Preserve --operation-id ${effectiveOperationId}; reuse it to inspect this attempt and do not create a replacement operation.`, apiError?.status ?? 503, apiError?.body ?? null);
+    }
+    throw error;
+  }
   printData(result, wantsJson);
 }
 

package/src/cli/agent.ts

@@ -30,7 +30,7 @@ const USAGE = `Usage:
   ocx agent subagents <status|set|clear> [model,model...] [--json]
   ocx agent subagents force <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 roles [status|set <role> <model> [--effort <level>]|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> (vision)] [--enabled <on|off>]
@@ -311,7 +311,7 @@ async function sidecar(argv: string[], deps: RuntimeApiDeps): Promise<void> {
 interface CodexAgentRolesStatus {
   lazycodex?: { detected?: boolean };
   omoJsonc?: { state?: string } | null;
-  roles?: Array<{ role: string; model: string | null; omoJsoncModel: string | null }>;
+  roles?: Array<{ role: string; model: string | null; effort?: string | null; omoJsoncModel: string | null }>;
 }
 
 interface CodexRoleProposal {
@@ -393,7 +393,7 @@ async function roles(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     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)"}`)),
+      ...(rows.length === 0 ? ["No Codex agent roles found."] : rows.map(row => `${row.role}: ${row.model ?? "(no model pin)"}${row.effort ? ` (${row.effort})` : ""}`)),
       `omo.jsonc: ${result.omoJsonc?.state ?? "unknown"}`,
     ]);
     return;
@@ -403,18 +403,22 @@ async function roles(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     return;
   }
   if (action !== "set") throw new CliUsageError(`unknown roles action ${action}`, USAGE);
+  const effort = takeOption(args, "--effort");
+  // An empty value is a supplied flag, not an absent one: dropping it would change the model and
+  // silently ignore the effort the operator asked for.
+  if (effort !== undefined && effort.trim() === "") throw new CliUsageError("--effort needs a reasoning level", 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 }) },
+    { method: "PUT", body: JSON.stringify(effort !== undefined ? { model, effort } : { model }) },
     deps,
   );
   const omo = result.omoJsonc?.status;
   printData(result, wantsJson, [
-    `${role}: ${model} (role TOML ${result.toml?.status ?? "unknown"})`,
+    `${role}: ${model}${effort ? ` (${effort})` : ""} (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"}`,

package/src/cli/aside-profile-recovery.ts

@@ -0,0 +1,33 @@
+/**
+ * Recovery guidance for Aside profiles whose sync preference is off while their managed block is stale (#6757).
+ *
+ * Sync refreshes only profiles whose preference is on, and an OFF preference is the operator's decision, so an
+ * "off (stale)" profile needs an explicit, reviewed enable. This module renders text only: it issues no request,
+ * reads no state and never changes a preference. Sync cannot name real profile IDs without a status read that may
+ * run integration maintenance, so its empty result points at status, which already holds the rows.
+ */
+export const ASIDE_SYNC_EMPTY_LINES: readonly string[] = [
+  "No eligible Aside profiles to synchronize. Sync refreshes only profiles whose sync preference is on.",
+  "List profiles with: ocx integration client status --client aside",
+  "For a profile shown as off (stale), review: ocx integration client preview --client aside --operation apply --profile <N>",
+  "Then, if the preview permits the change and you accept it: ocx integration client enable --client aside --profile <N>",
+];
+
+function recoveryProfileId(row: unknown): number | null {
+  if (!row || typeof row !== "object") return null;
+  const { profileId, enabled, state } = row as Record<string, unknown>;
+  // Only an explicit OFF beside a stale block qualifies. Conflict and unsafe blocks need inspection, not an enable.
+  if (enabled !== false || state !== "stale") return null;
+  return typeof profileId === "number" && Number.isSafeInteger(profileId) && profileId >= 0 && !Object.is(profileId, -0)
+    ? profileId : null;
+}
+
+/** Per-profile preview-then-enable commands for status rows that are off with a stale managed block. */
+export function asideProfileRecoveryLines(rows: readonly unknown[]): string[] {
+  const ids = [...new Set(rows.map(recoveryProfileId).filter((id): id is number => id !== null))];
+  return ids.flatMap(id => [
+    `Aside profile ${id} is off (stale). To reconnect it, review: ocx integration client preview --client aside --operation apply --profile ${id}`,
+    `Then, if the preview permits the change and you accept it: ocx integration client enable --client aside --profile ${id}`,
+  ]);
+}
+

package/src/cli/capabilities-base.ts

@@ -571,11 +571,11 @@ export const CAPABILITIES: readonly Capability[] = [
     command: ["claude","config"],
     summary: "Read or update Claude Code settings, including independent CLI first-party routing.",
     routes: [{"method":"GET","path":"/api/claude-code"},{"method":"PUT","path":"/api/claude-code"}],
-    flags: [{"name":"--enabled","value":"string","summary":"on or off."},{"name":"--auth-mode","value":"string","summary":"auto, proxy or subscription."},{"name":"--system-env","value":"string","summary":"on or off."},{"name":"--fast-mode","value":"string","summary":"on or off."},{"name":"--auto-context","value":"string","summary":"on or off."},{"name":"--compact-window","value":"string","summary":"Positive token count or default to clear."},{"name":"--inject-agents","value":"string","summary":"on or off."},{"name":"--small-fast-model","value":"string","summary":"Model ID; - clears."},{"name":"--model-map","value":"string","summary":"Comma-separated from=to mappings; - clears."},{"name":"--blocked-skills","value":"string","summary":"Comma-separated names; - clears."},{"name":"--web-model","value":"string","summary":"Model ID; - clears."},{"name":"--web-backend","value":"string","summary":"openai, anthropic, xai, gemini, exa or -."},{"name":"--vision-model","value":"string","summary":"Model ID; - clears."},{"name":"--vision-backend","value":"string","summary":"openai, anthropic or -."},{"name":"--first-party","value":"string","summary":"on or off; must be the only setting."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."}],
+    flags: [{"name":"--enabled","value":"string","summary":"on or off."},{"name":"--auth-mode","value":"string","summary":"auto, proxy or subscription."},{"name":"--system-env","value":"string","summary":"on or off."},{"name":"--fast-mode","value":"string","summary":"on or off."},{"name":"--auto-context","value":"string","summary":"on or off."},{"name":"--compact-window","value":"string","summary":"Positive token count or default to clear."},{"name":"--context-accounting","value":"string","summary":"1m (default) or 200k."},{"name":"--inject-agents","value":"string","summary":"on or off."},{"name":"--small-fast-model","value":"string","summary":"Model ID; - clears."},{"name":"--model-map","value":"string","summary":"Comma-separated from=to mappings; - clears."},{"name":"--blocked-skills","value":"string","summary":"Comma-separated names; - clears."},{"name":"--web-model","value":"string","summary":"Model ID; - clears."},{"name":"--web-backend","value":"string","summary":"openai, anthropic, xai, gemini, exa or -."},{"name":"--vision-model","value":"string","summary":"Model ID; - clears."},{"name":"--vision-backend","value":"string","summary":"openai, anthropic or -."},{"name":"--first-party","value":"string","summary":"on or off; must be the only setting."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."}],
     mutates: true,
     json: "payload",
     details: ["At least one setting is required. --first-party must be set alone and writes Claude settings immediately.","Clear both helper model and backend with - to restore inheritance. Preserve shared_proxy_retained warnings."],
-    usage: "ocx claude config status [--json]; ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
+    usage: "ocx claude config status [--json]; ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--context-accounting <1m|200k>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
   },
   {
     command: ["claude","intercept","start"],
@@ -714,11 +714,11 @@ export const CAPABILITIES: readonly Capability[] = [
     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."}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the role list, the write result or the proposals as JSON."},{"name":"--effort","value":"string","summary":"set: also write the role's reasoning effort."},{"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."],
-    usage: "ocx agent roles [status] [--json]; ocx agent roles set <role> <model> [--json]; ocx agent roles suggest [--model <id>] [--apply] [--json]",
+    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, plus model_reasoning_effort with --effort; omo.jsonc gets the same model and, when LazyCodex has that level, the effort as reasoning; it 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."],
+    usage: "ocx agent roles [status] [--json]; ocx agent roles set <role> <model> [--effort <level>] [--json]; ocx agent roles suggest [--model <id>] [--apply] [--json]",
   },
   {
     command: ["agent","injection"],

package/src/cli/capabilities-integrations.ts

@@ -139,10 +139,10 @@ export const INTEGRATION_CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["claude", "config", "set"],
-    usage: "ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
+    usage: "ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--context-accounting <1m|200k>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
     summary: "Change Claude Code settings through the runtime owner.",
     routes: [{"method": "PUT", "path": "/api/claude-code"}],
-    flags: [{"name": "--enabled", "value": "string", "summary": "on or off."}, {"name": "--auth-mode", "value": "string", "summary": "auto, proxy or subscription."}, {"name": "--system-env", "value": "string", "summary": "on or off."}, {"name": "--fast-mode", "value": "string", "summary": "on or off."}, {"name": "--auto-context", "value": "string", "summary": "on or off."}, {"name": "--compact-window", "value": "string", "summary": "Positive token count or default to clear."}, {"name": "--inject-agents", "value": "string", "summary": "on or off."}, {"name": "--small-fast-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--model-map", "value": "string", "summary": "Comma-separated from=to mappings; - clears."}, {"name": "--blocked-skills", "value": "string", "summary": "Comma-separated names; - clears."}, {"name": "--web-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--web-backend", "value": "string", "summary": "openai, anthropic, xai, gemini, exa or -."}, {"name": "--vision-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--vision-backend", "value": "string", "summary": "openai, anthropic or -."}, {"name": "--first-party", "value": "string", "summary": "on or off; must be the only setting."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    flags: [{"name": "--enabled", "value": "string", "summary": "on or off."}, {"name": "--auth-mode", "value": "string", "summary": "auto, proxy or subscription."}, {"name": "--system-env", "value": "string", "summary": "on or off."}, {"name": "--fast-mode", "value": "string", "summary": "on or off."}, {"name": "--auto-context", "value": "string", "summary": "on or off."}, {"name": "--compact-window", "value": "string", "summary": "Positive token count or default to clear."}, {"name": "--context-accounting", "value": "string", "summary": "1m (default) or 200k."}, {"name": "--inject-agents", "value": "string", "summary": "on or off."}, {"name": "--small-fast-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--model-map", "value": "string", "summary": "Comma-separated from=to mappings; - clears."}, {"name": "--blocked-skills", "value": "string", "summary": "Comma-separated names; - clears."}, {"name": "--web-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--web-backend", "value": "string", "summary": "openai, anthropic, xai, gemini, exa or -."}, {"name": "--vision-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--vision-backend", "value": "string", "summary": "openai, anthropic or -."}, {"name": "--first-party", "value": "string", "summary": "on or off; must be the only setting."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
     mutates: true,
     json: "payload",
     details: ["At least one setting is required. --first-party must be set alone and writes Claude settings immediately.", "Clear both helper model and backend with - to restore inheritance. Preserve shared_proxy_retained warnings."],

package/src/cli/cli-path-diagnostics.ts

@@ -0,0 +1,132 @@
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+import { readDesktopCliRecord, type DesktopCliRecordRead, desktopCliRecordPath, DESKTOP_CLI_RECORD_MAX_BYTES } from "../lib/desktop-cli-record.mjs";
+import { redactUserPath } from "../lib/redact";
+
+export type CliCommandIssue = Extract<DesktopCliRecordRead, { issue: string }>["issue"]
+  | "cleanup-pending"
+  | "desktop-target-missing" | "desktop-target-unusable"
+  | "expected-command-missing" | "expected-command-unusable"
+  | "path-missing" | "path-first-not-desktop" | "path-unreadable"
+  | "path-scan-truncated" | "windows-current-directory-shadow";
+export type CliPathCandidate = {
+  path: string; realpath: string; pathIndex: number; extension: string;
+};
+export type CliPathDiagnostics = {
+  configured: boolean;
+  recordPath: string;
+  packageHandoff: "enabled" | "disabled-on-windows";
+  recordState: DesktopCliRecordRead["state"];
+  expectedExecutable: string | null;
+  handoffTarget: string | null;
+  candidates: CliPathCandidate[];
+  pathFirst: CliPathCandidate | null;
+  desktopFirstOnPath: boolean | null;
+  currentDirectoryCandidate: CliPathCandidate | null;
+  shellResolution: "unobserved";
+  issues: CliCommandIssue[];
+};
+export type CliPathObservation =
+  | { kind: "usable"; realpath: string }
+  | { kind: "missing" | "unusable" | "unreadable" };
+export type CliPathDiagnosticOptions = {
+  platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; cwd?: string; home?: string;
+  recordRead?: DesktopCliRecordRead;
+  observe?: (path: string) => CliPathObservation;
+};
+
+export function collectCliPathDiagnostics(options: CliPathDiagnosticOptions = {}): CliPathDiagnostics {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const api = platform === "win32" ? win32 : posix;
+  const cwd = options.cwd ?? process.cwd();
+  const home = options.home ?? (platform === "win32" ? env.USERPROFILE || homedir() : homedir());
+  const read = options.recordRead ?? readDesktopCliRecord({ platform, env, home, recordPath: desktopCliRecordPath({ platform, env, home }) });
+  const configured = read.state === "ready";
+  const target = configured && read.state === "ready" ? read.record.cliExecutable : null;
+  const expected = configured ? (platform === "win32" ? target : api.join(home, ".opencodex-desktop", "bin", "ocx")) : null;
+  const issues: CliCommandIssue[] = [];
+  const add = (issue: CliCommandIssue): void => { if (!issues.includes(issue)) issues.push(issue); };
+  if (read.state === "invalid" || read.state === "unreadable") add(read.issue);
+  if (read.state === "disabled" && read.cleanupPending) add("cleanup-pending");
+  const observe = options.observe ?? ((path: string): CliPathObservation => {
+    try {
+      if (!statSync(path).isFile()) return { kind: "unusable" };
+      accessSync(path, platform === "win32" ? constants.F_OK : constants.X_OK);
+      return { kind: "usable", realpath: realpathSync(path) };
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      return { kind: code === "ENOENT" || code === "ENOTDIR" ? "missing" : code === "EACCES" ? "unusable" : "unreadable" };
+    }
+  });
+  const key = (path: string): string => platform === "win32" ? path.toLowerCase() : path;
+  const same = (a: string, b: string): boolean => key(a) === key(b);
+  const envValue = (name: string): string | undefined => platform === "win32"
+    ? env[Object.keys(env).find(key => key.toLowerCase() === name.toLowerCase()) ?? name] : env[name];
+  const path = envValue("PATH");
+  const rawExtensions = platform === "win32"
+    ? (envValue("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(ext => /^\.[A-Za-z0-9]+$/.test(ext)) : [];
+  const uniqueExtensions = [...new Set(rawExtensions.map(ext => ext.toLowerCase()))];
+  const extensions = platform === "win32" ? [...uniqueExtensions.slice(0, 32), ""] : [""];
+  if (uniqueExtensions.length > 32) add("path-scan-truncated");
+  const directories = path === undefined ? [] : path.split(platform === "win32" ? ";" : ":");
+  if (directories.length > 256) add("path-scan-truncated");
+  const candidates: CliPathCandidate[] = [];
+  const scan = (directory: string, pathIndex: number): CliPathCandidate[] => {
+    const result: CliPathCandidate[] = [];
+    const unquoted = platform === "win32" && directory.startsWith('"') && directory.endsWith('"') ? directory.slice(1, -1) : directory;
+    for (const extension of extensions) {
+      const candidate = api.resolve(cwd, unquoted || ".", `ocx${extension}`);
+      const found = observe(candidate);
+      if (found.kind === "unreadable") add("path-unreadable");
+      if (found.kind === "usable") result.push({ path: candidate, realpath: found.realpath, pathIndex, extension });
+    }
+    return result;
+  };
+  for (const [index, directory] of directories.slice(0, 256).entries()) candidates.push(...scan(directory, index));
+  const pathFirst = candidates[0] ?? null;
+  const currentDirectoryCandidate = platform === "win32" ? scan(cwd, -1)[0] ?? null : null;
+  let expectedRealpath: string | null = null;
+  if (target) {
+    const found = observe(target);
+    if (found.kind === "missing") add("desktop-target-missing");
+    else if (found.kind !== "usable") add("desktop-target-unusable");
+  }
+  if (expected) {
+    const found = observe(expected);
+    if (found.kind === "missing") add("expected-command-missing");
+    else if (found.kind !== "usable") add("expected-command-unusable");
+    else expectedRealpath = found.realpath;
+    if (!pathFirst) add("path-missing");
+    else if (!same(pathFirst.path, expected) && (!expectedRealpath || !same(pathFirst.realpath, expectedRealpath))) add("path-first-not-desktop");
+    if (currentDirectoryCandidate && !same(currentDirectoryCandidate.path, expected)
+      && (!expectedRealpath || !same(currentDirectoryCandidate.realpath, expectedRealpath))) add("windows-current-directory-shadow");
+  }
+  return {
+    configured, recordPath: read.path, packageHandoff: platform === "win32" ? "disabled-on-windows" : "enabled",
+    recordState: read.state, expectedExecutable: expected, handoffTarget: platform === "win32" ? null : target,
+    candidates, pathFirst,
+    desktopFirstOnPath: configured && !issues.includes("path-unreadable") && !issues.includes("path-scan-truncated")
+      ? Boolean(pathFirst && expected && expectedRealpath
+        && (same(pathFirst.path, expected) || same(pathFirst.realpath, expectedRealpath))) : null,
+    currentDirectoryCandidate, shellResolution: "unobserved", issues,
+  };
+}
+
+export function formatCliCommandLine(value: CliPathDiagnostics): string {
+  const first = value.pathFirst ? redactUserPath(value.pathFirst.path).replace(/[\x00-\x1f\x7f]/g, "?") : "none observed";
+  return `ocx command: PATH first=${first}; Desktop=${!value.configured ? "not configured" : value.desktopFirstOnPath === null ? "unobserved" : value.desktopFirstOnPath ? "first" : "not first"}; ${value.packageHandoff === "disabled-on-windows" ? "package handoff=disabled on Windows (user Path selects Desktop); " : ""}shell=unobserved${value.issues.length ? `; issues=${value.issues.join(",")}` : ""}`;
+}
+
+export function formatCliStatusHealthLabel(health: string, value: CliPathDiagnostics, local: boolean): string {
+  return `${health}${local ? " (local)" : ""}\n   ${formatCliCommandLine(value)}`;
+}
+
+export function cliCommandDoctorChecks(value: CliPathDiagnostics): { level: "OK" | "WARN" | "FAIL"; message: string }[] {
+  const hard = value.issues.some(issue => issue.startsWith("record-") || issue.startsWith("desktop-target-") || issue.startsWith("expected-command-"));
+  const recovery = value.issues.some(issue => issue.startsWith("record-"))
+    ? ` The terminal-command record at ${redactUserPath(value.recordPath).replace(/[\x00-\x1f\x7f]/g, "?")} could not be used. Open OpenCodex Desktop to repair the terminal command.${value.packageHandoff === "disabled-on-windows" ? "" : " Or run with OCX_NO_DESKTOP_HANDOFF=1."}${value.issues.includes("record-too-large") ? ` The record limit is ${DESKTOP_CLI_RECORD_MAX_BYTES} bytes.` : ""}`
+    : value.issues.includes("cleanup-pending") ? " Open OpenCodex Desktop to finish terminal-command cleanup." : "";
+  return [{ level: hard ? "FAIL" : value.issues.length ? "WARN" : "OK", message: formatCliCommandLine(value) + recovery }];
+}

package/src/cli/desktop-runtime-guidance.ts

@@ -0,0 +1,65 @@
+import { createSupervisionLatch, inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
+import type { DesktopSupervision, SupervisionInspector } from "../service/desktop-command-guard";
+import { UpdateRestartRequired } from "./update-restart-candidate";
+import { runProxyRestart, type ProxyRestartIo } from "./tray-proxy";
+
+function evidenceForTarget(evidence: DesktopSupervision, pid: number | null | undefined): DesktopSupervision {
+  // Injected inspectors must obey the same target binding as the production inspector.
+  return evidence.kind === "desktop" && pid != null && evidence.runtimePid !== pid
+    ? { kind: "unknown", reason: "unrelated-target", desktopSeen: false } : evidence;
+}
+
+export function duplicateRuntimeMessage(
+  pid: number | null | undefined,
+  port: number,
+  inspect: SupervisionInspector = inspectDesktopSupervision,
+): string {
+  const latch = createSupervisionLatch();
+  const evidence = evidenceForTarget(inspect({ targetPid: pid ?? undefined }), pid);
+  if (pid != null && latch.observe(evidence)) {
+    const supervisor = evidence.kind === "desktop" ? `, ${evidence.app}` : "";
+    return `OpenCodex Desktop supervises the running proxy (pid ${pid}${supervisor}, port ${port}). `
+      + "Use the running proxy, or quit OpenCodex before starting it from this CLI.";
+  }
+  return `⚠️  Proxy already running (PID ${pid ?? "unknown"}, port ${port}). Use 'ocx stop' first.`;
+}
+
+export function desktopStopNotice(evidence: DesktopSupervision): string | null {
+  const latch = createSupervisionLatch();
+  return latch.observe(evidence)
+    ? "OpenCodex Desktop may start this proxy again after a short backoff. Use Stop Proxy or Quit in the OpenCodex menu to keep it stopped."
+    : null;
+}
+
+export function runDesktopAwareProxyRestart(
+  io: ProxyRestartIo,
+  inspect: SupervisionInspector = inspectDesktopSupervision,
+  info: (line: string) => void = console.log,
+) {
+  const latch = createSupervisionLatch();
+  let targetPid: number | undefined;
+  let supervisedRequest = false;
+  return runProxyRestart({
+    ...io,
+    requestInPlaceRestart: async previous => {
+      targetPid = previous.pid ?? undefined;
+      const evidence = evidenceForTarget(inspect({ targetPid }), targetPid);
+      supervisedRequest = latch.observe(evidence);
+      const result = await io.requestInPlaceRestart(previous);
+      if (evidence.kind === "desktop" && result.accepted) {
+        info("Restart requested; OpenCodex Desktop starts the replacement.");
+      }
+      if (supervisedRequest && !result.accepted && !result.uncertain && result.error instanceof UpdateRestartRequired) {
+        info("OpenCodex Desktop supervises this proxy. Use the app's updater (tray → Check for Updates), or quit OpenCodex before updating and restarting from this CLI.");
+        return { accepted: false as const, uncertain: false, error: new Error("restart_desktop_update_required") };
+      }
+      return result;
+    },
+    startWhenStopped: async recovering => {
+      const blocked = latch.observe(evidenceForTarget(inspect({ targetPid }), targetPid));
+      // An accepted supervised handoff keeps its replacement intent through temporary absence.
+      if (supervisedRequest || blocked) return { status: "skipped" as const };
+      return io.startWhenStopped(recovering);
+    },
+  });
+}

package/src/cli/dispatch.ts

@@ -37,6 +37,8 @@ import { parseStopApproval, type StopApproval } from "./stop-approval";
 import type { ResolveArgs } from "./resolve";
 import type { ClientConnectionState } from "../client/state";
 import { OCX_NATIVE_REPLAY_RECOVERY_NOTE } from "../responses/compaction";
+import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
+import { desktopStopNotice } from "./desktop-runtime-guidance";
 
 export interface CliDispatchDeps {
   args: string[];
@@ -51,6 +53,7 @@ export interface CliDispatchDeps {
   spawnDetached: (argv: readonly string[]) => void;
   handleStart: () => Promise<void>;
   handleStop: (approval?: StopApproval) => Promise<StopOutcome>;
+  inspectDesktopSupervision?: typeof inspectDesktopSupervision;
   handleEnsure: (options?: { existingIsSuccess?: boolean }) => Promise<boolean>;
   handleResolve: (args: ResolveArgs) => Promise<number>;
   handleTrayProxyStart: (existingIsSuccess?: boolean) => Promise<boolean>;
@@ -112,6 +115,8 @@ const commandRunners: Record<string, CommandRunner> = {
     // re-start the proxy immediately, so warning there would contradict the next line.
     const warning = "⚠️  Codex/Claude requests through the proxy will fail until it is restarted ('ocx start' or 'ocx service start').";
     if (!parsed.json) {
+      const notice = desktopStopNotice((deps.inspectDesktopSupervision ?? inspectDesktopSupervision)());
+      if (notice) console.error(notice);
       // handleStop returns the structured outcome now; an object is always truthy, so
       // the warning must key on .ok — otherwise a failed stop would still claim downtime.
       if ((await deps.handleStop()).ok) console.log(warning);

package/src/cli/doctor.ts

@@ -7,11 +7,13 @@
  * it never sets proxy env, relocates state dirs, mutates quota, or changes
  * networking. See devlog/_plan/260630_wsl-account-autoswitch/30_*.
  */
+import { cliCommandDoctorChecks, collectCliPathDiagnostics } from "./cli-path-diagnostics";
 import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { getConfigDir, getConfigPath, readConfigDiagnostics } from "../config";
 import { readPid } from "../config/process-state";
+import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
 import { fetchLiveStartupHealth, probeUncleanExitState, selectStatusStartupHealth } from "./status";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
@@ -1324,6 +1326,12 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     console.log(`  ${row.exists ? "ok " : "-- "} ${row.label}: ${row.path}${flags ? `  (${flags})` : ""}`);
   }
 
+  console.log("\nocx command selection");
+  for (const check of cliCommandDoctorChecks(collectCliPathDiagnostics())) {
+    console.log(`  ${check.level === "OK" ? "ok " : "!! "} ${check.message}`);
+    if (check.level === "FAIL") recordDoctorFailure();
+  }
+
   // Runs without the proxy on purpose: the worst accumulation happens when the proxy will
   // not start, which is exactly when the in-process periodic reclaim never ticks.
   const reclaimTemps = args.includes(RECLAIM_RESPONSE_TEMPS_FLAG);
@@ -1379,7 +1387,8 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     configFn: () => ({ port: doctorConfig.port, hostname: doctorConfig.hostname }),
   });
   const liveStartup = live ? await fetchLiveStartupHealth(live) : null;
-  const startup = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(doctorConfig));
+  const { startup } = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(doctorConfig),
+    live?.pid != null ? () => inspectDesktopSupervision({ targetPid: live.pid! }) : undefined, live?.pid);
   console.log("\nCodex restart safety");
   console.log(`  ${startup.rebootSafe ? "ok " : "!! "} ${startupHealthSummary(startup)}`);
   console.log(`       ${formatStartupRoutingDetail(startup)}`);
@@ -1685,8 +1694,12 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   const anyDrvfs = paths.some(p => detectFsType(p.path, mounts).isDrvfs || detectFsType(p.path, mounts).isMntDrive);
   const noProxy = currentProxyEnv.every(p => !p.present) && !configuredProxy.present;
   if (!startup.rebootSafe) {
-    const command = startup.recommendedCommand ?? startup.commands.restoreNative;
-    hints.push(`Codex is pinned to the local proxy without persistent startup protection. After restart, requests can reconnect indefinitely. Run '${command}'.`);
+    if (startup.recommendedAction || startup.desktop?.supervisor) {
+      hints.push(`Codex is pinned to the local proxy without persistent startup protection. ${startup.recommendedAction ?? "Reopen OpenCodex and check Start at Login."}`);
+    } else {
+      const command = startup.recommendedCommand ?? startup.commands.restoreNative;
+      hints.push(`Codex is pinned to the local proxy without persistent startup protection. After restart, requests can reconnect indefinitely. Run '${command}'.`);
+    }
   }
   if (anyDrvfs) {
     hints.push("State dir is on a Windows-mounted (/mnt) drive. Prefer the Linux home (~) under WSL for token/lock reliability.");

package/src/cli/index.ts

@@ -8,6 +8,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { currentServingCommand, deferServiceChildToNewerRuntime, markDelegatedServiceReady, recordServingRuntime } from "../config/serving-runtimes";
 import { packageVersion } from "../lib/package-version";
+import { codexHomeIsAbsent } from "../codex/codex-home-owner";
+import { getCodexHome } from "../codex/paths";
 import { admitUpdateRestartChild } from "./update-restart-child";
 import { UpdateRestartRequired } from "./update-restart-candidate";
 import { describeUpdateRestartFailure, restartFromCurrentInstallation } from "./update-restart";
@@ -75,7 +77,7 @@ import {
   pendingTeardownsAreExactly,
   quarantinePendingTeardown,
 } from "../config/pending-teardown";
-import { collectStatus, deadProxyRoutingAdviceLines, detectMissingCodexCatalogPath, hubStatusLines, missingCodexCatalogLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
+import { collectStatus, deadProxyRoutingAdviceLines, detectMissingCodexCatalogPath, hubStatusLines, missingCodexCatalogLines, remoteHubBannerLine, remoteHubStatusLines, runtimeSupervisorLine, unusedProxyWarningLines } from "./status";
 import { endpointsToProve, everyEndpointProvenDownAsync, sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
 import { takeFlag } from "./runtime-api";
 import { parseStartOptions, StartArgsError } from "./start-args";
@@ -85,11 +87,11 @@ import {
   recheckRestartFailedStart, reobserveRestartReplacement,
   restartStartOutcome,
   waitForProxyReplacement,
-  runProxyRestart,
   runTrayProxyStart,
   type ProxyRestartLive,
   type ProxyRestartStartOutcome,
 } from "./tray-proxy";
+import { duplicateRuntimeMessage, runDesktopAwareProxyRestart } from "./desktop-runtime-guidance";
 import { reportRestartFailure } from "./restart-failure";
 import { requestBoundSystemRestart } from "./system-restart-client";
 import { installCrashGuards } from "../lib/crash-guard";
@@ -329,7 +331,7 @@ async function chooseListenPort(
         throw new StartCommandExit(serviceStayOutExitCode());
       }
       if (decision === "refuse-live-proxy") {
-        console.error(`⚠️  Proxy already running (PID ${holder?.pid ?? "unknown"}, port ${preferred}). Use 'ocx stop' first.`);
+        console.error(duplicateRuntimeMessage(holder?.pid, preferred));
         throw new StartCommandExit(1);
       }
       if (decision === "refuse-unidentified-holder") {
@@ -444,7 +446,7 @@ async function handleStart(options: { block?: boolean } = {}) {
       process.exit(serviceStayOutExitCode());
     }
     if (decision === "refuse" || decision === "await-parent") {
-      console.error(`⚠️  Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}). Use 'ocx stop' first.`);
+      console.error(duplicateRuntimeMessage(owner.live.pid ?? owner.pidSnapshot, owner.live.port));
       process.exit(1);
     }
     // Sibling path. The new instance takes over this home's ocx.pid / runtime-port.json while
@@ -654,10 +656,12 @@ async function handleStart(options: { block?: boolean } = {}) {
     removeRuntimePort(process.pid);
     if (teardown.restoreNativeCodex && !currentExternalCodexModelProvider()) {
       try {
-        const restored = restoreNativeCodex();
-        if (!restored.success) {
-          cleanupSucceeded = false;
-          console.error(`⚠️  Native Codex restore failed during shutdown: ${restored.message}`);
+        if (!codexHomeIsAbsent(getCodexHome())) {
+          const restored = restoreNativeCodex();
+          if (!restored.success) {
+            cleanupSucceeded = false;
+            console.error(`⚠️  Native Codex restore failed during shutdown: ${restored.message}`);
+          }
         }
       } catch (error) {
         cleanupSucceeded = false;
@@ -928,7 +932,7 @@ async function handleProxyRestart(
   startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>,
 ): Promise<boolean> {
   const deadlineAt = Date.now() + PROXY_RESTART_OBSERVE_MS;
-  const result = await runProxyRestart({
+  const result = await runDesktopAwareProxyRestart({
     findLive: () => discoverStableProxyForRestart({
       findLive: () => findLiveProxy({ deadlineAt, attempts: 2, acceptPackageTreeFenced: true }),
       expired: () => Date.now() >= deadlineAt,
@@ -1785,6 +1789,7 @@ async function handleStatus() {
   console.log(`   Config: ${status.json.paths.config}${local}`);
   console.log(`   PID file: ${status.json.paths.pid}${local}`);
   console.log(`   Runtime: ${status.json.paths.runtime}${local}`);
+  if (runtimeSupervisorLine(status.json.startup)) console.log(`   ${runtimeSupervisorLine(status.json.startup)}`);
   console.log(`   Runtime source: ${status.json.runtime.source}${status.json.runtime.overrideEnv ? ` (${status.json.runtime.overrideEnv})` : ""}${local}`);
   // On a client this is the local default, which routing does not use — the hub applies its own.
   console.log(`   Default provider: ${status.json.defaultProvider}${local}`);

package/src/cli/integration-aside-sync.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redactUserPath } from "../lib/redact";
 import type { RefusalReason } from "../integrations/mutation-plan";
+import { ASIDE_SYNC_EMPTY_LINES } from "./aside-profile-recovery";
 import { refreshAsideProfilesThroughServer } from "./aside-profiles";
 import { runCatalogAction } from "./catalog-command-result";
 import { CliUsageError, RuntimeApiError, printData, takeFlag, takeOption, type RuntimeApiDeps } from "./runtime-api";
@@ -56,7 +57,7 @@ export function handleIntegrationAsideSync(argv: string[], deps: AsideSyncCliDep
     const parsed = resultsSchema.safeParse(outcomes);
     if (!parsed.success) throw new Error("Invalid Aside synchronization outcome");
     const results = parsed.data;
-    const lines = results.length === 0 ? ["No eligible Aside profiles to synchronize. Check integration status and profile sync preferences."]
+    const lines = results.length === 0 ? [...ASIDE_SYNC_EMPTY_LINES]
       : results.flatMap(row => [
         `Aside profile ${row.profileId}: ${row.ok ? row.changed ? "updated" : "unchanged" : "failed"}.`,
         ...(row.reason ? [row.reason] : []),