npm - @bitkyc08/opencodex - Versions diffs - 2.53.0 → 2.54.0 - Mend

@bitkyc08/opencodex 2.53.0 → 2.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/gui/dist/assets/{index-BlO4Yl6q.js → index-CkvITofZ.js} +2 -2
package/gui/dist/index.html +1 -1
package/package.json +1 -1
package/src/adapters/devin.ts +39 -7
package/src/cli/capabilities.ts +4 -2
package/src/cli/catalog.ts +39 -10
package/src/cli/dispatch.ts +19 -64
package/src/cli/doctor.ts +1 -1
package/src/cli/internal-command.ts +44 -0
package/src/cli/registry.ts +9 -7
package/src/cli/restart-scope.ts +184 -0
package/src/codex/app-server-processes.ts +20 -5
package/src/codex/app-server-restart-service.ts +29 -0
package/src/codex/catalog/provider-fetch.ts +13 -5
package/src/codex/catalog/sync.ts +12 -3
package/src/codex/desktop-app/darwin.ts +268 -0
package/src/codex/desktop-app/handoff.ts +303 -0
package/src/codex/desktop-app/linux.ts +388 -0
package/src/codex/desktop-app/lock.ts +226 -0
package/src/codex/desktop-app/types.ts +141 -0
package/src/codex/desktop-app/windows.ts +239 -0
package/src/codex/desktop-app-restart.ts +264 -279
package/src/codex/inject.ts +83 -21
package/src/codex/sync.ts +16 -22
package/src/generated/compatibility-version.json +58 -22
package/src/lib/codex-restart-contract.ts +31 -0
package/src/providers/registry.ts +13 -12
package/src/server/responses/core.ts +62 -4
package/src/server/responses/encrypted-payload.ts +161 -0
package/src/server/responses.ts +1 -1
package/src/types/provider.ts +6 -5
package/src/web-search/index.ts +14 -67
package/src/web-search/passthrough-bridge.ts +256 -32
package/src/web-search/sidecar-providers.ts +76 -0

package/gui/dist/index.html CHANGED Viewed

@@ -16,7 +16,7 @@
         } catch (e) {}
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-BlO4Yl6q.js"></script>
+    <script type="module" crossorigin src="/assets/index-CkvITofZ.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BBOZWGB6.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.53.0",
+  "version": "2.54.0",
   "description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",

package/src/adapters/devin.ts CHANGED Viewed

@@ -10,6 +10,7 @@ import type { AdapterEvent, OcxAssistantMessage, OcxContentPart, OcxMessage, Ocx
 import { namespacedToolName } from "../types";
 import type { IncomingMeta, ProviderAdapter } from "./base";
 import { streamChatEvents, allocateCascadeId, CloudChatError, type ChatHistoryItem, type ToolDef } from "./devin/cloud-direct";
+import type { ContentPart } from "./devin/cloud-direct/chat";
 import { getCachedCatalog } from "./devin/cloud-direct/catalog";
 import { collapseDevinModelUid } from "./devin/live-models";
 import { buildNonOpenAIToolCatalogNudgeForTools } from "./tool-catalog-nudge";
@@ -208,9 +209,31 @@ function textFromParts(content: string | OcxContentPart[] | undefined): string {
   return content.map((part) => (part.type === "text" ? part.text : "")).filter(Boolean).join("\n");
 }
-function toolResultText(message: OcxToolResultMessage): string {
-  const body = textFromParts(message.content);
-  return message.isError ? ("ERROR: " + body) : body;
+/**
+ * Convert inbound content parts to the multimodal shape the wire encoder accepts.
+ *
+ * The wire layer already carries images (ChatMessagePrompt field #10 ImageData),
+ * but every image was discarded at this boundary: textFromParts returned a
+ * text-only string and a message whose only content was an image was dropped
+ * entirely, which is why a pasted screenshot killed the turn and the only
+ * workaround was running OCR before sending. A data: URL carries everything
+ * field #10 needs; a remote https URL cannot be inlined without a fetch, so it
+ * stays as an explicit text reference rather than pretending the model can see
+ * a picture it cannot. Video has no Devin field and is skipped.
+ */
+function mapOcxContentToWire(content: string | OcxContentPart[] | undefined): string | ContentPart[] {
+  if (typeof content === "string" || !Array.isArray(content)) return content ?? "";
+  const out: ContentPart[] = [];
+  for (const part of content) {
+    if (part.type === "text" && part.text) {
+      out.push({ type: "text", text: part.text });
+    } else if (part.type === "image") {
+      const m = part.imageUrl.match(/^data:([^;]+);base64,(.+)$/);
+      if (m) out.push({ type: "image", mimeType: m[1]!, base64Data: m[2]! });
+      else out.push({ type: "text", text: `[image url: ${part.imageUrl}]` });
+    }
+  }
+  return out;
 }
 function assistantToolCalls(message: OcxAssistantMessage): Array<{ id: string; name: string; arguments: string }> {
@@ -290,9 +313,12 @@ export function mapOcxMessagesToDevin(parsed: OcxParsedRequest): ChatHistoryItem
 function mapOneMessage(message: OcxMessage): ChatHistoryItem | undefined {
   if (message.role === "user" || message.role === "developer") {
-    const text = textFromParts(message.content).trim();
-    if (!text) return undefined;
-    return { role: message.role === "developer" ? "system" : "user", content: text };
+    const content = mapOcxContentToWire(message.content);
+    // An image with no caption text is a complete user message on its own.
+    // Dropping it — which is what the text-only extraction did — is why a
+    // pasted screenshot killed the turn before the model ever saw anything.
+    if (typeof content === "string" ? !content.trim() : content.length === 0) return undefined;
+    return { role: message.role === "developer" ? "system" : "user", content };
   }
   if (message.role === "assistant") {
     const toolCalls = assistantToolCalls(message);
@@ -309,9 +335,15 @@ function mapOneMessage(message: OcxMessage): ChatHistoryItem | undefined {
     };
   }
   if (message.role === "toolResult") {
+    const wireContent = mapOcxContentToWire(message.content);
+    const toolContent = message.isError
+      ? (typeof wireContent === "string"
+          ? `ERROR: ${wireContent}`
+          : [{ type: "text", text: "ERROR:" } as ContentPart, ...wireContent])
+      : wireContent;
     return {
       role: "tool",
-      content: toolResultText(message),
+      content: toolContent,
       tool_call_id: message.toolCallId,
     };
   }

package/src/cli/capabilities.ts CHANGED Viewed

@@ -720,6 +720,7 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: [
       "`sync --restart-codex` is not a substitute: it restarts only as a side effect after a catalog or cache write, so it cannot restart a healthy install on request.",
+      "Restarts the Codex desktop app as well as the app-servers, through the same module the CLI uses. When the proxy itself runs inside the Codex app it refuses instead, because restarting the app would kill the request.",
       "--yes is mandatory because this interrupts a running editor session, which must never happen because an agent guessed a subcommand.",
     ],
   },
@@ -785,8 +786,9 @@ export const CAPABILITIES: readonly Capability[] = [
     summary: "Synchronize client catalogs, including Aside profiles through the running server's mutation owner.",
     routes: [{ method: "POST", path: "/api/client-integrations/aside/sync" }],
     flags: [
-      { name: "--restart-codex", value: "boolean", summary: "Restart Codex app-servers after a catalog or cache write." },
-      { name: "--restart-desktop-app", value: "boolean", summary: "Restart the Codex desktop app after a catalog or cache write." },
+      { name: "--restart-codex", value: "boolean", summary: "Restart the Codex app-servers and fully quit and relaunch the Codex desktop app after a catalog or cache write, on macOS, Linux and Windows." },
+      { name: "--restart-app-server-only", value: "boolean", summary: "Restart only the Codex app-servers and leave the desktop app running; wins over --restart-codex when both are given." },
+      { name: "--restart-desktop-app", value: "boolean", summary: "Deprecated alias of --restart-codex." },
     ],
     mutates: true,
     json: "none",

package/src/cli/catalog.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { afterCatalogWriteHandleAppServers } from "../codex/app-server-processes";
+import { handleRestartScopeAfterWrite, readRestartScope } from "./restart-scope";
 import { pullRemoteCatalog, RemoteCatalogError } from "../codex/catalog/remote";
 import { hasHelpFlag, printSubcommandUsage } from "./help";
@@ -9,6 +9,14 @@ export interface CatalogPullEnvelope {
   catalogWritten: boolean;
   cacheSynced: boolean;
   codexRestarted: boolean;
+  /**
+   * Whether the desktop app was actually restarted. Only ever true for a completed
+   * relaunch: a handoff is not a success, because the restart has not happened yet when
+   * this envelope is written and a script reading true would proceed on a promise.
+   * Separate from codexRestarted so a script reading the existing field is not silently
+   * handed a different answer.
+   */
+  desktopAppRestarted?: boolean;
   modelCount?: number;
   code?: string;
 }
@@ -21,14 +29,18 @@ function optionValue(args: string[], name: string): string | undefined {
 export async function handleCatalogCommand(args: string[]): Promise<number> {
   if (hasHelpFlag(args)) { printSubcommandUsage("catalog"); return 0; }
   const json = args.includes("--json");
-  const restartCodex = args.includes("--restart-codex");
+  const restartScope = readRestartScope(args, console);
   const authEnv = optionValue(args, "--auth-env");
   const positionals = args.filter((arg, index) => {
     if (arg === "--auth-env") return false;
     if (index > 0 && args[index - 1] === "--auth-env") return false;
     return !arg.startsWith("-");
   });
-  const knownFlags = new Set(["--json", "--restart-codex", "--auth-env"]);
+  // A closed set: an unknown flag is a usage error, so the new scope flags have to be
+  // listed here or catalog pull would reject the very flags sync accepts.
+  const knownFlags = new Set([
+    "--json", "--restart-codex", "--restart-desktop-app", "--restart-app-server-only", "--auth-env",
+  ]);
   const unknown = args.find((arg, index) => arg.startsWith("-") && !knownFlags.has(arg) && args[index - 1] !== "--auth-env");
   const validEnvName = authEnv === undefined || /^[A-Za-z_][A-Za-z0-9_]*$/.test(authEnv);
   if (positionals[0] !== "pull" || positionals.length !== 2 || unknown || !validEnvName
@@ -38,7 +50,7 @@ export async function handleCatalogCommand(args: string[]): Promise<number> {
       cacheSynced: false, codexRestarted: false, code: "usage",
     };
     if (json) console.log(JSON.stringify(envelope));
-    else console.error("Usage: ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]");
+    else console.error("Usage: ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex] [--restart-app-server-only]");
     return 2;
   }
   let token: string | undefined;
@@ -57,21 +69,35 @@ export async function handleCatalogCommand(args: string[]): Promise<number> {
   try {
     const result = await pullRemoteCatalog(positionals[1]!, { token });
     let codexRestarted = false;
+    let desktopAppRestarted = false;
     let restartIncomplete = false;
     if (result.catalogWritten) {
       const processLog = json
         ? { log: (...values: unknown[]) => console.error(...values), error: (...values: unknown[]) => console.error(...values) }
         : console;
-      const processResult = afterCatalogWriteHandleAppServers({ restart: restartCodex, log: processLog });
-      const restart = processResult.restart;
+      const outcome = await handleRestartScopeAfterWrite(restartScope, processLog);
+      const processResult = outcome.appServers;
+      const restart = processResult?.restart;
+      desktopAppRestarted = outcome.desktopApp?.relaunch === "started";
+      // A desktop restart that was asked for and did not relaunch is an incomplete
+      // restart, exactly like a surviving app-server. Without this the pull reports
+      // ok: true while the picker the operator was fixing is still stale.
+      // "Desktop app is not running" is the same nothing-to-do the app-server half
+      // already treats as success, so it must not read as an incomplete restart.
+      if (restartScope.desktopApp && !desktopAppRestarted
+        && outcome.desktopApp?.reason !== "no_targets") {
+        restartIncomplete = true;
+      }
       if (restart) {
         // A partial stop is not a restart. `restartCodexAppServers` reports failures and
         // survivors without throwing, so counting `stopped` alone reported success while a
         // stale app-server was still serving the previous catalog from memory.
         codexRestarted = restart.failed.length === 0
           && restart.surviving.length === 0
-          && restart.stopped.length === processResult.processes.length;
-        restartIncomplete = !codexRestarted;
+          && restart.stopped.length === (processResult?.processes.length ?? -1);
+        // Do not ASSIGN here: the desktop half may already have set this, and assigning
+        // would discard a failed desktop restart whenever any app-server was signalled.
+        if (!codexRestarted) restartIncomplete = true;
       }
     }
     if (restartIncomplete) {
@@ -81,7 +107,9 @@ export async function handleCatalogCommand(args: string[]): Promise<number> {
       const envelope: CatalogPullEnvelope = {
         schemaVersion: 1, ok: false, status: result.status,
         catalogWritten: result.catalogWritten, cacheSynced: result.cacheSynced,
-        codexRestarted: false, modelCount: result.modelCount, code: "restart_incomplete",
+        codexRestarted: false,
+        ...(restartScope.desktopApp ? { desktopAppRestarted } : {}),
+        modelCount: result.modelCount, code: "restart_incomplete",
       };
       if (json) console.log(JSON.stringify(envelope));
       else console.error("Remote Codex catalog installed, but a Codex app-server is still running the previous catalog.");
@@ -90,7 +118,8 @@ export async function handleCatalogCommand(args: string[]): Promise<number> {
     const envelope: CatalogPullEnvelope = {
       schemaVersion: 1, ok: true, status: result.status,
       catalogWritten: result.catalogWritten, cacheSynced: result.cacheSynced,
-      codexRestarted, modelCount: result.modelCount,
+      codexRestarted,
+        ...(restartScope.desktopApp ? { desktopAppRestarted } : {}), modelCount: result.modelCount,
     };
     if (json) console.log(JSON.stringify(envelope));
     else if (result.status === "unchanged") console.log("Remote Codex catalog is unchanged; no files or processes were touched.");

package/src/cli/dispatch.ts CHANGED Viewed

@@ -26,7 +26,7 @@ import { syncModelsToCodex } from "../codex/sync";
 import { collectOrcaCodexHomeDiagnostic } from "../codex/home";
 import { restoreNativeCodexAsync } from "../codex/inject";
 import { stripGrokConfig } from "../grok/inject";
-import { afterCatalogWriteHandleAppServers } from "../codex/app-server-processes";
+import { handleRestartScopeAfterWrite, readRestartScope, type RestartScope } from "./restart-scope";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
 import { isJsonOption, takeFlag } from "./runtime-api";
 import type { ClientConnectionState } from "../client/state";
@@ -378,10 +378,12 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   sync: async deps => {
     const syncArgs = deps.args.slice(1);
-    const restartCodex = syncArgs.includes("--restart-codex");
-    // Separate flag on purpose: --restart-codex promises app-server-only scope,
-    // and quitting the desktop app ends live conversations.
-    const restartDesktopApp = syncArgs.includes("--restart-desktop-app");
+    const restartScope = readRestartScope(syncArgs, console);
+    // The wire field keeps APP-SERVER-ONLY meaning and is deliberately not widened. A
+    // remote hub must not end a local user's conversations because a field name acquired
+    // a wider meaning underneath it; the maintainer decision widened a local CLI flag and
+    // said nothing about remote callers. syncConnectedClient ignores it either way.
+    const restartCodex = restartScope.appServers;
     const { readClientConnectionState } = await import("../client/state");
     const clientState = readClientConnectionState();
     if (clientState.kind === "invalid" || clientState.kind === "mismatched") {
@@ -395,7 +397,7 @@ const commandRunners: Record<string, CommandRunner> = {
         console.log(result.stale
           ? "Hub unavailable; retained and applied the last-known-good remote catalog (stale)."
           : "Remote hub catalog synchronized.");
-        await handleConnectedSyncCatalogWrite(result, restartCodex, restartDesktopApp);
+        await handleConnectedSyncCatalogWrite(result, restartScope);
         // `process.exitCode` rather than a literal 0, for the same reason every other
         // runner does it (tests/cli/cli-transport-honesty.test.ts): the catalog-write helper
         // drives app-server restarts, and one of those recording a failure must not be
@@ -434,8 +436,7 @@ const commandRunners: Record<string, CommandRunner> = {
     // so a sync can fail (`ok: false`) after the catalog was already rewritten — which is
     // exactly when a long-lived app-server is holding the stale list.
     if (synced.catalogWritten || synced.cacheSynced) {
-      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
-      if (restartDesktopApp) await handleDesktopAppRestart(console);
+      await handleRestartScopeAfterWrite(restartScope, console);
     }
     // `ocx sync` is a direct CLI path; it does not call the management
     // `/api/sync` route. Refresh already-connected file integrations here too,
@@ -496,8 +497,7 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   "sync-cache": async deps => {
     const cacheArgs = deps.args.slice(1);
-    const restartCodex = cacheArgs.includes("--restart-codex");
-    const restartDesktopApp = cacheArgs.includes("--restart-desktop-app");
+    const restartScope = readRestartScope(cacheArgs, console);
     const { withCatalogWriteSerialization } = await import("../codex/catalog-write-serialization");
     const { invalidateCodexModelsCacheWithPermit } = await import("../codex/catalog/sync");
     const { getCodexHome } = await import("../codex/paths");
@@ -514,8 +514,7 @@ const commandRunners: Record<string, CommandRunner> = {
       : console;
     // Only warn/restart when models_cache was actually rewritten from a readable catalog.
     if (invalidated.kind === "completed" && invalidated.value) {
-      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: jsonSafeLog });
-      if (restartDesktopApp) await handleDesktopAppRestart(jsonSafeLog);
+      await handleRestartScopeAfterWrite(restartScope, jsonSafeLog);
     } else if (desiredDisabled && !cacheJson) {
       // Worth saying in the human path, because it explains why nothing was written.
       // Under --json this belongs on the envelope, not as a second stdout line.
@@ -961,6 +960,12 @@ export async function dispatchCommand(head: CliHead, deps: CliDispatchDeps): Pro
     printUsage();
     return 0;
   }
+  if (command === "internal") {
+    // Routed here rather than as a runner key so it stays out of DISPATCH_COMMANDS and
+    // therefore out of the registry-parity gate. See src/cli/internal-command.ts.
+    const { handleInternalCommand } = await import("./internal-command");
+    return await handleInternalCommand(deps.args.slice(1));
+  }
   const runner = commandRunners[resolveDispatchCommand(command) ?? ""];
   if (!runner) {
     console.error(`Unknown command: ${command}`);
@@ -970,62 +975,12 @@ export async function dispatchCommand(head: CliHead, deps: CliDispatchDeps): Pro
   return await runner(deps);
 }
-/**
- * Report the outcome of an opt-in desktop-app restart. Kept next to the two
- * callers so `sync` and `sync-cache` cannot drift in what they tell the user.
- */
-async function handleDesktopAppRestart(log: Pick<Console, "log" | "error">): Promise<void> {
-  const { restartCodexDesktopApp } = await import("../codex/desktop-app-restart");
-  const result = restartCodexDesktopApp();
-  switch (result.reason) {
-    case "windows_only":
-      log.error("--restart-desktop-app is supported on Windows only; nothing was stopped.");
-      return;
-    case "package_discovery_failed":
-      log.error(
-        "Could not identify the installed Codex desktop package. Quit and relaunch the desktop app "
-        + "manually to refresh the model picker.",
-      );
-      return;
-    case "self_ancestry":
-      log.error(
-        "Refusing to restart the desktop app because this command is running inside it. "
-        + "Run 'ocx sync --restart-desktop-app' from an external terminal instead.",
-      );
-      return;
-    case "process_probe_failed":
-      // Distinct from `no_targets`: we could not look, which is not the same as looking and
-      // finding nothing. Saying "not running" here sent users away believing there was nothing
-      // to restart (#2557).
-      log.error(
-        "Could not enumerate Codex desktop processes, so the app was not restarted. "
-        + "Quit and relaunch the desktop app manually to refresh the model picker.",
-      );
-      return;
-    case "no_targets":
-      log.log("Codex desktop app is not running; nothing to restart.");
-      return;
-    case "targets_survived":
-      log.error(
-        `Codex desktop app PID(s) ${result.surviving.join(", ")} did not exit, so it was not relaunched. `
-        + "Quit the desktop app manually to refresh the model picker.",
-      );
-      return;
-    default:
-      if (result.relaunch === "started") {
-        log.log("Codex desktop app restarted; its model picker will re-read the catalog.");
-      }
-  }
-}
 async function handleConnectedSyncCatalogWrite(
   result: { catalogWritten: boolean; cacheSynced: boolean },
-  restartCodex: boolean,
-  restartDesktopApp: boolean,
+  scope: RestartScope,
 ): Promise<void> {
   if (!result.catalogWritten && !result.cacheSynced) return;
-  afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
-  if (restartDesktopApp) await handleDesktopAppRestart(console);
+  await handleRestartScopeAfterWrite(scope, console);
 }
 async function reconcileClientJournalBeforeLifecycle(

package/src/cli/doctor.ts CHANGED Viewed

@@ -1366,7 +1366,7 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   const { collectCodexAppServerCatalogState } = await import("../codex/app-server-processes");
   const catalogState = collectCodexAppServerCatalogState();
   if (catalogState.state === "stale") {
-    console.log(`  [WARN] Codex app-server (PID(s): ${catalogState.processes.map(p => p.pid).join(", ")}) started before the on-disk catalog changed; its in-memory model list disagrees with ocx. Action: restart Codex (or run \`ocx sync --restart-codex\`; on Windows the desktop app may need \`ocx sync --restart-desktop-app\`)`);
+    console.log(`  [WARN] Codex app-server (PID(s): ${catalogState.processes.map(p => p.pid).join(", ")}) started before the on-disk catalog changed; its in-memory model list disagrees with ocx. Action: run \`ocx sync --restart-codex\`, which restarts the app-servers and the Codex desktop app`);
   } else if (catalogState.state === "unknown") {
     console.log("  [WARN] Could not verify whether the running Codex app-server's model catalog is current (start time or catalog unreadable). Action: if the model list looks stale, restart Codex");
   } else if (catalogState.state === "fresh") {

package/src/cli/internal-command.ts ADDED Viewed

@@ -0,0 +1,44 @@
+/**
+ * Hidden `ocx internal ...` commands.
+ *
+ * Deliberately NOT in `src/cli/registry.ts` and NOT in `src/cli/capabilities.ts`, so it
+ * is absent from help, from the generated skill surface, and from the registry-parity
+ * gate. It is not a user-facing capability and must not become one: it exists so the
+ * detached restart helper is the same audited binary running the same audited ladder,
+ * rather than a second implementation in a shell script.
+ *
+ * It is routed before the dispatch table for the same reason `help` is - adding it as a
+ * runner key would make it a command the registry-parity test expects to find
+ * documented.
+ *
+ * It is intentionally unauthenticated, and that is not an oversight. Any process running
+ * as this user can invoke it with a hand-written plan file, and it gains nothing by
+ * doing so: the helper only does what the public `--restart-codex` flag already does for
+ * that same user, and a same-uid process could call `kill` directly. A token here would
+ * protect nothing and would imply a boundary that does not exist.
+ */
+const USAGE = "Usage: ocx internal desktop-restart-handoff --plan <path>";
+function optionValue(args: readonly string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+export async function handleInternalCommand(args: readonly string[]): Promise<number> {
+  const sub = args[0];
+  if (sub !== "desktop-restart-handoff") {
+    console.error(`Unknown internal command: ${sub ?? "(none)"}. ${USAGE}`);
+    return 2;
+  }
+  const plan = optionValue(args, "--plan");
+  if (!plan) {
+    console.error(USAGE);
+    return 2;
+  }
+  const { runDesktopRestartHandoff } = await import("../codex/desktop-app/handoff");
+  const outcome = await runDesktopRestartHandoff(plan);
+  // The operator is not watching this process - its terminal died with the app. The
+  // exit code exists for a supervisor, and the readable record is the handoff log.
+  return outcome === "restarted" ? 0 : 1;
+}

package/src/cli/registry.ts CHANGED Viewed

@@ -125,27 +125,29 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "sync",
-    usage: "ocx sync [--restart-codex] [--restart-desktop-app]",
+    usage: "ocx sync [--restart-codex] [--restart-app-server-only]",
     summary: "Fetch provider models and inject them into Codex config.",
     details: [
       "After writing the catalog, warns if long-lived Codex app-server processes are still running.",
-      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
-      "--restart-desktop-app (Windows only, opt-in) fully restarts the Codex desktop app so its model picker re-reads the catalog. Never implied by --restart-codex: it ends live conversations.",
+      "--restart-codex restarts the app-servers AND fully quits and relaunches the Codex desktop app on macOS, Linux and Windows, so its model picker re-reads the catalog. It ends live conversations.",
+      "--restart-app-server-only keeps the narrow behaviour: SIGTERM to matching app-server / code-mode-host processes, desktop app left running. It wins over --restart-codex when both are given.",
+      "--restart-desktop-app is a deprecated alias of --restart-codex and prints a notice.",
     ],
   },
   {
     name: "sync-cache",
-    usage: "ocx sync-cache [--restart-codex] [--restart-desktop-app]",
+    usage: "ocx sync-cache [--restart-codex] [--restart-app-server-only]",
     summary: "Refresh Codex's model cache from the active catalog.",
     details: [
       "Warns when Codex app-server processes still hold an in-memory model list.",
-      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
-      "--restart-desktop-app (Windows only, opt-in) fully restarts the Codex desktop app so its model picker re-reads the catalog. Never implied by --restart-codex: it ends live conversations.",
+      "--restart-codex restarts the app-servers AND fully quits and relaunches the Codex desktop app on macOS, Linux and Windows, so its model picker re-reads the catalog. It ends live conversations.",
+      "--restart-app-server-only keeps the narrow behaviour: SIGTERM to matching app-server / code-mode-host processes, desktop app left running. It wins over --restart-codex when both are given.",
+      "--restart-desktop-app is a deprecated alias of --restart-codex and prints a notice.",
     ],
   },
   {
     name: "catalog",
-    usage: "ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex]",
+    usage: "ocx catalog pull <https-url> [--auth-env <NAME>] [--json] [--restart-codex] [--restart-app-server-only]",
     summary: "Install a validated remote /v1/catalog snapshot into Codex.",
     details: [
       "Authentication is read only from the named environment variable and sent as a Bearer token.",

package/src/cli/restart-scope.ts ADDED Viewed

@@ -0,0 +1,184 @@
+/**
+ * The restart scope a command was asked for, and the post-write restart itself.
+ *
+ * Its own module because `sync`, `sync-cache` and `catalog pull` all need it, and
+ * having `catalog.ts` import it from `dispatch.ts` would make the two files circular.
+ */
+import { afterCatalogWriteHandleAppServers } from "../codex/app-server-processes";
+import type { AfterCatalogWriteAppServerResult } from "../codex/app-server-processes";
+import type { DesktopAppRestartResult } from "../codex/desktop-app-restart";
+/**
+ * Which restart a command was asked for.
+ *
+ * `--restart-codex` used to mean app-server-only, and the desktop restart was a
+ * separate Windows-only opt-in. That split existed because quitting the app ends live
+ * conversations, which is a bigger consent than restarting a background helper. The
+ * reasoning was sound and is superseded by an explicit maintainer decision:
+ * `--restart-codex` now means the app is fully stopped and started again. The narrow
+ * behaviour did not disappear, it moved to a flag that names it.
+ *
+ * One reader for every command, so `sync`, `sync-cache` and `catalog pull` cannot
+ * drift in what the same flag means.
+ */
+export interface RestartScope {
+  /** Signal matching app-server / code-mode-host processes. */
+  appServers: boolean;
+  /** Fully quit and relaunch the Codex desktop app. */
+  desktopApp: boolean;
+}
+export function readRestartScope(
+  args: readonly string[],
+  log: Pick<Console, "error">,
+): RestartScope {
+  const appServerOnly = args.includes("--restart-app-server-only");
+  const legacyDesktop = args.includes("--restart-desktop-app");
+  const restartCodex = args.includes("--restart-codex");
+  if (legacyDesktop) {
+    log.error(
+      "--restart-desktop-app is deprecated: --restart-codex now restarts the Codex "
+      + "desktop app on every platform. The flag still works and will be removed in a "
+      + "future release.",
+    );
+  }
+  if (appServerOnly && (restartCodex || legacyDesktop)) {
+    // Contradictory scopes, and the NARROW one wins. Losing live conversations is
+    // unrecoverable; a stale model picker is not. A user who typed the app-server-only
+    // flag asked not to lose them.
+    log.error(
+      "--restart-app-server-only overrides --restart-codex/--restart-desktop-app; "
+      + "the desktop app was left running.",
+    );
+    return { appServers: true, desktopApp: false };
+  }
+  if (appServerOnly) return { appServers: true, desktopApp: false };
+  if (restartCodex || legacyDesktop) return { appServers: true, desktopApp: true };
+  return { appServers: false, desktopApp: false };
+}
+export interface RestartScopeOutcome {
+  appServers?: AfterCatalogWriteAppServerResult;
+  desktopApp?: DesktopAppRestartResult;
+}
+/**
+ * The post-write restart, for every command that performs one.
+ *
+ * App-servers that belong to the desktop tree are excluded when a desktop restart is
+ * also going to run: the app-server is a CHILD of the app on every platform, so
+ * signalling it first and then quitting the app interrupts the operator's in-flight
+ * turn twice in one command. A discovery or probe failure yields no exclusion, which
+ * is the safe direction - a missed exclusion costs an extra interruption, a wrong one
+ * leaves a stale app-server serving a roster that no longer exists.
+ */
+export async function handleRestartScopeAfterWrite(
+  scope: RestartScope,
+  log: Pick<Console, "log" | "error">,
+): Promise<RestartScopeOutcome> {
+  const { listCodexDesktopAppPids } = await import("../codex/desktop-app-restart");
+  // KNOWN LIMITATION on Windows. The exclusion matches pids against the discovered
+  // desktop tree, and the Windows probe enumerates only ChatGPT.exe, while Windows
+  // app-servers run as codex.exe / codex-code-mode-host. They therefore never match and
+  // still receive SIGTERM before the app quits, so Windows keeps the double interruption
+  // this exclusion removes on macOS and Linux - where the app-server executable does live
+  // under the bundle or install root and is enumerated.
+  //
+  // Closing it means widening the Windows probe past ChatGPT.exe, which is the same query
+  // that decides what may be killed, so it needs its own verification rather than being
+  // appended here. The restart itself is correct on Windows either way; the cost is one
+  // extra interrupted turn.
+  const excludePids = scope.desktopApp ? (listCodexDesktopAppPids() ?? []) : [];
+  const appServers = afterCatalogWriteHandleAppServers({
+    restart: scope.appServers, log, excludePids,
+  });
+  const desktopApp = scope.desktopApp ? await handleDesktopAppRestart(log) : undefined;
+  return { appServers, desktopApp };
+}
+/**
+ * Report the outcome of a desktop-app restart. Kept next to the callers so every
+ * command tells the user the same thing.
+ */
+export async function handleDesktopAppRestart(
+  log: Pick<Console, "log" | "error">,
+): Promise<DesktopAppRestartResult> {
+  const { restartCodexDesktopApp } = await import("../codex/desktop-app-restart");
+  const { startDesktopRestartHandoff } = await import("../codex/desktop-app/handoff");
+  const result = restartCodexDesktopApp({
+    // The CLI is the one caller whose exit is exactly the signal the helper waits for,
+    // so it is the one caller allowed to hand off. The management service is not (it
+    // runs in a proxy that never exits) and the helper itself is not (recursion).
+    startHandoff: () => {
+      const outcome = startDesktopRestartHandoff();
+      return outcome.kind === "started"
+        ? { helperPid: outcome.helperPid, logPath: outcome.logPath }
+        : null;
+    },
+  });
+  switch (result.reason) {
+    case "unsupported_platform":
+      log.error(
+        `Restarting the Codex desktop app is not supported on ${process.platform}; `
+        + "nothing was stopped.",
+      );
+      return result;
+    case "restart_in_flight":
+      log.error(
+        "Another Codex desktop-app restart is already running; this one did nothing. "
+        + "Wait for it to finish and check again.",
+      );
+      return result;
+    case "relaunch_failed":
+      log.error(
+        "The Codex desktop app was stopped but could not be started again. Launch it manually.",
+      );
+      return result;
+    case "package_discovery_failed":
+      log.error(
+        "Could not identify the installed Codex desktop package. Quit and relaunch the desktop app "
+        + "manually to refresh the model picker.",
+      );
+      return result;
+    case "handoff_started":
+      // Saying the session will end is the point. The operator is about to lose the
+      // terminal they typed into, and a message that omits that reads as a hang.
+      log.log(
+        "This command is running inside the Codex app, so the restart was handed off to "
+        + `a detached helper (pid ${result.handoff?.helperPid ?? 0}). The app will quit and `
+        + `relaunch in a moment; this session will end with it. Outcome: ${result.handoff?.logPath ?? ""}`,
+      );
+      return result;
+    case "self_ancestry":
+      log.error(
+        "Refusing to restart the desktop app because this command is running inside it, "
+        + "and the restart could not be handed off to a detached helper. "
+        + "Run 'ocx sync --restart-codex' from a terminal outside the app instead.",
+      );
+      return result;
+    case "process_probe_failed":
+      // Distinct from `no_targets`: we could not look, which is not the same as looking and
+      // finding nothing. Saying "not running" here sent users away believing there was nothing
+      // to restart (#2557).
+      log.error(
+        "Could not enumerate Codex desktop processes, so the app was not restarted. "
+        + "Quit and relaunch the desktop app manually to refresh the model picker.",
+      );
+      return result;
+    case "no_targets":
+      log.log("Codex desktop app is not running; nothing to restart.");
+      return result;
+    case "targets_survived":
+      log.error(
+        `Codex desktop app PID(s) ${result.surviving.join(", ")} did not exit, so it was not relaunched. `
+        + "Quit the desktop app manually to refresh the model picker.",
+      );
+      return result;
+    default:
+      if (result.relaunch === "started") {
+        log.log("Codex desktop app restarted; its model picker will re-read the catalog.");
+      }
+      return result;
+  }
+}