@bitkyc08/opencodex 2.64.0 → 2.65.0-preview.20260925

package/src/cli/dispatch.ts

@@ -555,24 +555,24 @@ const commandRunners: Record<string, CommandRunner> = {
     const cacheArgs = deps.args.slice(1);
     const restartScope = readRestartScope(cacheArgs, console);
     const { withCatalogWriteSerialization } = await import("../codex/catalog-write-serialization");
-    const { invalidateCodexModelsCacheWithPermit } = await import("../codex/catalog/sync");
+    const { invalidateCodexModelsCacheWithPermitOutcome } = await import("../codex/catalog/sync");
     const { getCodexHome } = await import("../codex/paths");
-    const { readCodexCatalogPathForHome } = await import("../codex/catalog/parsing");
-    const { existsSync } = await import("node:fs");
     const owningCodexHome = getCodexHome();
     const cacheGateSnapshot = deps.loadConfig();
     const desiredDisabled = !shouldSyncCodexOnStart(cacheGateSnapshot);
     const invalidated = withCatalogWriteSerialization(owningCodexHome, permit =>
-      invalidateCodexModelsCacheWithPermit(permit, owningCodexHome, { allowWhenDesiredDisabled: true }));
+      invalidateCodexModelsCacheWithPermitOutcome(permit, owningCodexHome, { allowWhenDesiredDisabled: true }));
     const cacheJson = cacheArgs.includes("--json");
     const jsonSafeLog = cacheJson
       ? { log: (...values: unknown[]) => console.error(...values), error: (...values: unknown[]) => console.error(...values) }
       : console;
     // Only warn/restart when models_cache was actually rewritten from a readable catalog.
-    if (invalidated.kind === "completed" && invalidated.value) {
+    if (invalidated.kind === "completed" && invalidated.value === "written") {
       await handleRestartScopeAfterWrite(restartScope, jsonSafeLog);
-    } else if (desiredDisabled && !cacheJson) {
-      // Worth saying in the human path, because it explains why nothing was written.
+    } else if (!cacheJson && invalidated.kind === "completed" && invalidated.value === "desired_disabled") {
+      // Only when the OFF gate itself stopped the write does OFF explain the outcome. An
+      // explicit sync-cache refreshes regardless of the toggle, so an unchanged cache, a
+      // missing catalog, or a contended writer is reported below on its own terms.
       // Under --json this belongs on the envelope, not as a second stdout line.
       console.log(localClientSkipMessage(
         cacheGateSnapshot,
@@ -580,8 +580,8 @@ const commandRunners: Record<string, CommandRunner> = {
         "No catalog or cache write resulted.",
       ));
     }
-    // `completed` with a falsy value means the cache was NOT rewritten. Previously every
-    // outcome exited 0, so a script could not tell a refreshed cache from a skipped one.
+    // An identical cache is a successful no-op, not a failed refresh. Only a real write
+    // should restart Codex; a missing catalog or contended writer is also a benign skip.
     //
     // Losing the catalog write lock to another process is a skip, not a failure:
     // serialization working as designed is the expected outcome under concurrency, and a
@@ -596,30 +596,25 @@ const commandRunners: Record<string, CommandRunner> = {
     // means the user asked for it regardless of the toggle. Treating OFF as automatic success
     // would report exit 0 and `skipped: true` for a refresh that actually failed.
     //
-    // But `invalidateCodexModelsCacheWithPermit` returns a bare boolean for four different
-    // situations -- wrote it, no catalog file exists, the OFF gate fired, or it threw -- so
-    // `false` alone cannot be read as failure either. `!existsSync(catalogPath)` is a
-    // legitimate nothing-to-do: with no catalog there is no cache to derive, which is the
-    // normal state of a fully native home and the case
-    // `codex-composed-acceptance.test.ts` pins at exit 0. It is checked here rather than by
-    // widening that function's return type, because its boolean is consumed by a dozen
-    // management routes that have no use for the distinction.
-    const wrote = invalidated.kind === "completed" && Boolean(invalidated.value);
+    // The detailed outcome distinguishes an unchanged cache from a failed rewrite while
+    // the boolean wrapper remains available to callers that only care whether bytes changed.
+    const wrote = invalidated.kind === "completed" && invalidated.value === "written";
+    const unchanged = invalidated.kind === "completed" && invalidated.value === "unchanged";
     const contended = invalidated.kind === "unavailable" && invalidated.reason === "busy";
-    const noCatalog = !wrote && !existsSync(readCodexCatalogPathForHome(owningCodexHome));
-    const ok = wrote || contended || noCatalog;
+    const noCatalog = invalidated.kind === "completed" && invalidated.value === "missing_catalog";
+    const ok = wrote || unchanged || contended || noCatalog;
     if (cacheJson) {
       console.log(JSON.stringify({
         schemaVersion: 1,
         ok,
         wrote,
-        skipped: contended || noCatalog,
+        skipped: unchanged || contended || noCatalog,
         outcome: invalidated.kind,
         // `outcome` alone cannot separate a contended lock from a hard serialization
         // failure -- both are `unavailable`. Carry the reason so a caller can.
         reason: invalidated.kind === "unavailable" ? invalidated.reason : undefined,
-        // Which of the two benign skips this was, so `skipped: true` is never opaque.
-        skippedReason: contended ? "contended" : noCatalog ? "no_catalog" : undefined,
+        // Which of the three benign skips this was, so `skipped: true` is never opaque.
+        skippedReason: unchanged ? "unchanged" : contended ? "contended" : noCatalog ? "no_catalog" : undefined,
         desiredDisabled,
         codexHome: owningCodexHome,
       }, null, 2));
@@ -627,6 +622,8 @@ const commandRunners: Record<string, CommandRunner> = {
       console.log("Another process owns the catalog write; cache sync skipped.");
     } else if (noCatalog) {
       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 (!ok) {
       console.error(`Cache refresh did not complete (${invalidated.kind}). The Codex model cache was not rewritten.`);
     }
@@ -733,6 +730,15 @@ const commandRunners: Record<string, CommandRunner> = {
     await refreshVersionCache(channel);
     return 0;
   },
+  "__update-badge": async deps => {
+    if (deps.args.length !== 1) {
+      console.error("Usage: ocx __update-badge");
+      return 64;
+    }
+    const { readUpdateBadge } = await import("../update/badge");
+    console.log(JSON.stringify(readUpdateBadge()));
+    return 0;
+  },
   "__tray-start": async deps => {
     return (await deps.handleTrayProxyStart()) ? 0 : 1;
   },

package/src/cli/effort.ts

@@ -7,6 +7,8 @@ import {
   mapReasoningEffort,
   reasoningEffortMapFor,
 } from "../reasoning-effort";
+import { decodeRoutedModelId } from "../providers/slug-codec";
+import { knownModelIdsForProvider } from "../router";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { modelInList, type OcxConfig } from "../types";
 import {
@@ -290,19 +292,26 @@ function inspectModelEffort(modelTarget: string, wantsJson: boolean): void {
     );
   }
 
-  const isReasoningDisabled = modelInList(provider.noReasoningModels, modelId);
-  const efforts = configuredReasoningEfforts(provider, modelId);
-  const wireMap = reasoningEffortMapFor(provider, modelId);
+  // A Codex-facing slug encodes the inner "/" of a namespaced native id
+  // (`command-code/deepseek-deepseek-v4.1-flash` for `deepseek/deepseek-v4.1-flash`), so the
+  // literal id only resolves against the ladder through the decode the router already uses.
+  const known = knownModelIdsForProvider(providerName, provider, config);
+  const resolvedModelId = known.includes(modelId) ? modelId : decodeRoutedModelId(modelId, known);
+
+  const isReasoningDisabled = modelInList(provider.noReasoningModels, resolvedModelId);
+  const efforts = configuredReasoningEfforts(provider, resolvedModelId);
+  const wireMap = reasoningEffortMapFor(provider, resolvedModelId);
 
   // Derive sample ladder directly from canonical CODEX_REASONING_LEVELS (#3528 review)
   const mappedExamples: Record<string, string | undefined> = {};
   for (const { effort } of CODEX_REASONING_LEVELS) {
-    mappedExamples[effort] = mapReasoningEffort(provider, modelId, effort);
+    mappedExamples[effort] = mapReasoningEffort(provider, resolvedModelId, effort);
   }
 
   const result = {
     provider: providerName,
-    model: modelId,
+    model: resolvedModelId,
+    ...(resolvedModelId !== modelId ? { requestedModel: modelId } : {}),
     reasoningDisabled: isReasoningDisabled,
     supportedEfforts: efforts ?? null,
     wireMap: wireMap ?? null,
@@ -310,7 +319,8 @@ function inspectModelEffort(modelTarget: string, wantsJson: boolean): void {
   };
 
   const lines = [
-    `Reasoning effort configuration for ${providerName}/${modelId}:`,
+    `Reasoning effort configuration for ${providerName}/${resolvedModelId}:`,
+    ...(resolvedModelId !== modelId ? [`  Resolved from: ${modelId}`] : []),
     `  Reasoning disabled: ${isReasoningDisabled ? "yes (noReasoningModels)" : "no"}`,
     `  Supported ladder:   ${efforts ? efforts.join(", ") : "(default / unconstrained)"}`,
     `  Wire mapping overrides: ${wireMap ? JSON.stringify(wireMap) : "(standard provider mapping)"}`,

package/src/cli/ensure-desired-integrations.ts

@@ -9,11 +9,15 @@
  * each external-file mutation, and use that current config for sync inputs.
  */
 import { loadConfig } from "../config";
+import { removeDesktopPickerArtifacts } from "../claude/desktop-picker";
+import { findLiveProxy } from "../server/proxy-liveness";
+import { runtimeRequest } from "./runtime-api";
 import { stripGrokConfig, type GrokInjectResult } from "../grok/inject";
 import { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot } from "../claude/desktop-3p";
 import {
   applyDesktopFirstParty,
   inspectDesktopFirstParty,
+  observeClaudeDesktopMode,
   removeDesktopFirstParty,
   resolveClaudeDesktopMode,
 } from "../claude/desktop-first-party";
@@ -44,7 +48,11 @@ export interface EnsureDesiredIntegrationsDeps {
   removeDesktopFirstParty?: typeof removeDesktopFirstParty;
   applyDesktopFirstParty?: typeof applyDesktopFirstParty;
   inspectDesktopFirstParty?: typeof inspectDesktopFirstParty;
+  observeClaudeDesktopMode?: typeof observeClaudeDesktopMode;
   inspectDesktop3pConfigLibrary?: typeof inspectDesktop3pConfigLibrary;
+  findLiveProxyImpl?: typeof findLiveProxy;
+  runtimeRequestImpl?: typeof runtimeRequest;
+  removeDesktopPickerArtifacts?: typeof removeDesktopPickerArtifacts;
   log?: (message: string) => void;
   error?: (message: string) => void;
 }
@@ -130,13 +138,13 @@ export async function ensureGrokFenceMatchesDesired(
  * When it is ON in first-party mode, refresh a stale env (the intercept port follows the
  * public port, so a port change would otherwise leave Claude Code pointed at a dead proxy).
  */
-export function ensureClaudeDesktopMatchesDesired(
+export async function ensureClaudeDesktopMatchesDesired(
   deps: EnsureDesiredIntegrationsDeps = productionDeps,
-): void {
+): Promise<void> {
   const config = deps.loadConfig();
   const { log, error } = io(deps);
   if (claudeDesktopIntegrationEnabled(config)) {
-    if (resolveClaudeDesktopMode(config) !== "first-party") return;
+    if (resolveClaudeDesktopMode(config, (deps.observeClaudeDesktopMode ?? observeClaudeDesktopMode)(config)) !== "first-party") return;
     const library = (deps.inspectDesktop3pConfigLibrary ?? inspectDesktop3pConfigLibrary)({
       appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null,
     });
@@ -153,6 +161,23 @@ export function ensureClaudeDesktopMatchesDesired(
     else if (!applied.ok) error(`⚠️  Claude Desktop first-party env refresh skipped: ${applied.reason}.`);
     return;
   }
+  try {
+    const live = await (deps.findLiveProxyImpl ?? findLiveProxy)();
+    if (live) {
+      const request = deps.runtimeRequestImpl ?? runtimeRequest;
+      await request(
+        "/api/claude-desktop/picker",
+        { method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify({ enabled: false, persist: false }) },
+        deps.findLiveProxyImpl ? { findLiveProxy: deps.findLiveProxyImpl } : {},
+      );
+    } else {
+      const removed = await (deps.removeDesktopPickerArtifacts ?? removeDesktopPickerArtifacts)({});
+      if (!removed.ok) error(`⚠️  Claude Desktop picker cleanup skipped${removed.residual?.length ? `: ${removed.residual.join(", ")}` : ""}.`);
+    }
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    error(`⚠️  Claude Desktop picker cleanup skipped: ${detail}.`);
+  }
   try {
     const env = (deps.removeDesktopFirstParty ?? removeDesktopFirstParty)();
     if (env.ok && env.changed) log("   ↩️  Claude Desktop first-party env removed.");
@@ -196,5 +221,5 @@ export async function reconcileEnsureDesiredIntegrations(
     liveHost ? { hostname: liveHost } : {},
     deps,
   );
-  ensureClaudeDesktopMatchesDesired(deps);
+  await ensureClaudeDesktopMatchesDesired(deps);
 }

package/src/cli/ready.ts

@@ -199,7 +199,7 @@ export async function runReady(args: ReadyArgs, io: ReadyIo = {}): Promise<numbe
   if (!args.wait) {
     // Default: exactly one identity-checked readiness probe. No wait deadline —
     // bounded only by the probe's own default timeout (remainingMs=undefined so
-    // the production defaults keep their built-in 750ms ceiling; no semantic
+    // the production defaults keep their built-in DEFAULT_PROBE_TIMEOUT_MS ceiling; no semantic
     // regression vs. the single-probe behavior).
     const live = await find(undefined);
     if (!live) {

package/src/cli/registry.ts

@@ -451,6 +451,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "  ocx claude desktop [apply]                         Save and apply the four-family profile",
       "  ocx claude desktop show [--json]                   Show routes, families, and defaults",
       "  ocx claude desktop status [--json]                 Show applied state, drift, and health",
+      "  ocx claude desktop bind <picker-id> <route>        First-party: serve a Code tab picker model with a route",
+      "  ocx claude desktop unbind <picker-id>              Remove a first-party binding",
       "  ocx claude desktop move <route> <family> [--default]",
       "  ocx claude desktop default <family> <route|none>",
       "  ocx claude desktop export <path|->                 Export versioned JSON (`-` = stdout)",
@@ -591,6 +593,12 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx __refresh-version [preview|latest]",
     summary: "Hidden detached helper: refresh the cached latest version.",
   },
+  {
+    name: "__update-badge",
+    hidden: true,
+    usage: "ocx __update-badge",
+    summary: "Hidden internal: print cached package update badge JSON.",
+  },
   {
     name: "__tray-start",
     hidden: true,

package/src/cli/restart-scope.ts

@@ -6,7 +6,7 @@
  */
 import { afterCatalogWriteHandleAppServers } from "../codex/app-server-processes";
 import type { AfterCatalogWriteAppServerResult } from "../codex/app-server-processes";
-import type { DesktopAppRestartResult } from "../codex/desktop-app-restart";
+import type { DesktopAppRestartIo, DesktopAppRestartResult } from "../codex/desktop-app-restart";
 
 /**
  * Which restart a command was asked for.
@@ -102,10 +102,12 @@ export async function handleRestartScopeAfterWrite(
  */
 export async function handleDesktopAppRestart(
   log: Pick<Console, "log" | "error">,
+  io: DesktopAppRestartIo = {},
 ): Promise<DesktopAppRestartResult> {
   const { restartCodexDesktopApp } = await import("../codex/desktop-app-restart");
   const { startDesktopRestartHandoff } = await import("../codex/desktop-app/handoff");
   const result = restartCodexDesktopApp({
+    ...io,
     // 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).
@@ -123,6 +125,12 @@ export async function handleDesktopAppRestart(
         + "nothing was stopped.",
       );
       return result;
+    case "test_environment":
+      log.error(
+        "Skipped the Codex desktop app restart: this is an armed opencodex test process "
+        + "(OCX_TEST_HOME_GUARD=1), so the real app was not touched.",
+      );
+      return result;
     case "restart_in_flight":
       log.error(
         "Another Codex desktop-app restart is already running; this one did nothing. "

package/src/cli/runtime-api.ts

@@ -394,6 +394,23 @@ export function printData(value: unknown, wantsJson: boolean, lines?: string[]):
   else for (const line of lines) console.log(line);
 }
 
+/**
+ * Operator text for the Codex-config apply report a management write returns.
+ *
+ * The report shape is shared by every route that re-runs the injection on the spot: the Desktop
+ * switches (`ocx system settings`) and the web-search sidecar's master switch. One vocabulary for
+ * both, so the same failure cannot read as two different things depending on which command the
+ * operator used -- and because the reason codes are internal, the human line never prints them.
+ */
+export function desktopSwitchApplyReason(reason: unknown): string {
+  if (reason === "not_requested") return "no desktop switch rewrite was requested";
+  if (reason === "proxy_not_running") return "the proxy is not running";
+  if (reason === "integration_disabled") return "Codex integration is disabled";
+  if (reason === "write_lock_busy") return "the Codex config write lock is busy";
+  if (reason === "injection_refused") return "Codex config injection was refused";
+  return "the rewrite could not be completed";
+}
+
 /**
  * Render untrusted diagnostic text without letting it control the operator's terminal. Catalog
  * values are hub-supplied and surface on more than one CLI path -- first-time `ocx connect` and the

package/src/cli/system-command.ts

@@ -1,5 +1,6 @@
 import {
   CliUsageError,
+  desktopSwitchApplyReason,
   printData,
   rejectArgs,
   runCliAction,
@@ -56,15 +57,6 @@ function desktopSwitchInertReason(reason: unknown): string {
   return "the stored setting is not effective in the current runtime configuration";
 }
 
-function desktopSwitchApplyReason(reason: unknown): string {
-  if (reason === "not_requested") return "no desktop switch rewrite was requested";
-  if (reason === "proxy_not_running") return "the proxy is not running";
-  if (reason === "integration_disabled") return "Codex integration is disabled";
-  if (reason === "write_lock_busy") return "the Codex config write lock is busy";
-  if (reason === "injection_refused") return "Codex config injection was refused";
-  return "the rewrite could not be completed";
-}
-
 function settingsUpdateLines(
   result: unknown,
   changed: { desktopAuthless: boolean; clientCompaction: boolean },
@@ -202,13 +194,20 @@ export async function handleSystemCommand(argv: string[], deps: RuntimeApiDeps =
       printData(await runtimeRequest("/api/system/codex-app-server", {}, deps), wantsJson);
     } else if (sub === "codex-restart") {
       // --yes required: this fully quits and relaunches the user's Codex desktop app as well as
-      // restarting app-servers; an agent guessing a subcommand must not interrupt that session.
+      // restarting app-servers, which can discard unsaved drafts, selections, and approval prompts.
       const args = [...rest];
       const wantsJson = takeFlag(args, "--json");
       const yes = takeFlag(args, "--yes");
-      if (!yes) throw new CliUsageError("system codex-restart requires --yes: this fully quits and relaunches the Codex desktop app and restarts its app-servers", USAGE);
+      if (!yes) throw new CliUsageError(
+        "system codex-restart requires --yes: this fully quits and relaunches the Codex desktop app, so unsaved composer drafts, model-picker selections, and pending approval prompts may be lost; it also restarts the app-servers",
+        USAGE,
+      );
       rejectArgs(args, USAGE);
-      printData(await runtimeRequest("/api/system/codex-restart", { method: "POST" }, deps), wantsJson, ["Codex desktop app and app-server restart requested."]);
+      printData(
+        await runtimeRequest("/api/system/codex-restart", { method: "POST" }, deps),
+        wantsJson,
+        ["Codex desktop app and app-server restart requested. Unsaved composer drafts, model-picker selections, and pending approval prompts may be lost."],
+      );
     } else if (sub === "update") await update(rest, deps);
     else throw new CliUsageError(`unknown system command ${sub}`, USAGE);
   });

package/src/client/connect.ts

@@ -37,6 +37,7 @@ import {
   replaceServiceApiTokenFile,
   restoreTokenBackup,
   serviceApiTokenBackupPath,
+  serviceApiTokenFingerprint,
   writeTokenBackup,
   writeServiceApiTokenFile,
 } from "../lib/service-secrets";
@@ -65,6 +66,7 @@ import {
   clearClientConnection,
   commitClientConnection,
   readClientConnectionState,
+  markClientConnectPending, clearClientConnectPending, pendingClientConnectMayOwnToken,
   assertNoClientDisconnectPending, assertClientConnectionUnchanged, sameClientConnectionOwner,
 } from "./state";
 import { assertClientCatalogCompatible, type CatalogCompatibilityDeps } from "./catalog-compatibility";
@@ -492,6 +494,7 @@ function assertConnectingState(expectedTokenFingerprint?: string): void {
   }
 }
 
+/** Enroll a client key, keeping its pending ownership visible until commit or rollback. */
 export async function connectClient(
   options: ConnectOptions,
   deps: ClientConnectDeps = {},
@@ -501,6 +504,7 @@ export async function connectClient(
   let issued: IssuedClientKey | null = null;
   let cleanupCredential: { kind: "admin"; value: Uint8Array } | { kind: "gui-session"; value: ConnectGuiSession } | null = null;
   let tokenFingerprint: string | null = null;
+  let pendingConnectFingerprint: string | null = null;
   let priorCatalog: CatalogSnapshot | null = null;
   let writtenCatalogFingerprint: string | null = null;
   let injectionCommitted = false;
@@ -536,6 +540,9 @@ export async function connectClient(
 
     const initialFiles = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
       assertConnectingState();
+      const fingerprint = serviceApiTokenFingerprint(issued!.key);
+      markClientConnectPending(fingerprint);
+      pendingConnectFingerprint = fingerprint;
       return { prior: catalogSnapshot(), persisted: writeServiceApiTokenFile(issued!.key) };
     }), deps.lifecycleLockDeps);
     priorCatalog = initialFiles.prior;
@@ -602,6 +609,7 @@ export async function connectClient(
     };
     withClientLifecycleSync(() => withConfigMutationLockSync(() => {
       assertConnectingState(persisted.fingerprint);
+      clearClientConnectPending(persisted.fingerprint);
       commitClientConnection(connection);
       committed = true;
     }), deps.lifecycleLockDeps);
@@ -618,9 +626,11 @@ export async function connectClient(
         if (priorCatalog && writtenCatalogFingerprint && !restoreCatalogSnapshot(priorCatalog, writtenCatalogFingerprint)) {
           rollbackFailures.push("catalog rollback did not match the written artifact");
         }
-        if (tokenFingerprint) {
-          const removed = removeServiceApiTokenFileIfOwned(tokenFingerprint);
+        if (pendingConnectFingerprint) {
+          const removed = removeServiceApiTokenFileIfOwned(pendingConnectFingerprint);
           if (removed === "changed") rollbackFailures.push("service token changed during rollback");
+          // Final commit may fail after this attempt already cleared its marker under the same lock.
+          else if (pendingClientConnectMayOwnToken(pendingConnectFingerprint)) clearClientConnectPending(pendingConnectFingerprint);
         }
       }), deps.lifecycleLockDeps);
     } catch { rollbackFailures.push("client cleanup ownership unavailable"); }

package/src/client/state.ts

@@ -1,5 +1,7 @@
-import { readFileSync } from "node:fs";
+import { lstatSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
 import {
+  getConfigDir,
   getConfigPath,
   deleteConfigTopLevelKey,
   getDefaultConfig,
@@ -8,6 +10,7 @@ import {
   saveConfig,
   withConfigMutationLockSync,
 } from "../config";
+import { atomicWriteFileNoFollowUnclaimed } from "../config/atomic-write";
 import type { OcxClientConnectionConfig } from "../types";
 import { inspectRemoteDesktopStore, readDesktopDisconnectReceipt } from "../claude/desktop-remote-store";
 import { withClientLifecycleSync, type ClientLifecycleLockDeps } from "./lifecycle-lock";
@@ -23,6 +26,41 @@ export type ClientConnectionState =
   | { kind: "invalid"; reason: string }
   | { kind: "mismatched"; reason: string };
 
+const pendingConnectPath = (): string => join(getConfigDir(), "client-connect-pending");
+
+/** Validate pending ownership; an optional fingerprint restricts it to that exact key. */
+export function pendingClientConnectMayOwnToken(fingerprint?: string): boolean {
+  const path = pendingConnectPath();
+  let stat;
+  try { stat = lstatSync(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+  if (!stat.isFile() || stat.nlink !== 1 || stat.size !== 65) {
+    throw new Error("pending client connection owner is unsafe");
+  }
+  const marker = readFileSync(path, "utf8");
+  if (!/^[a-f0-9]{64}\n$/.test(marker)) throw new Error("pending client connection owner is malformed");
+  return fingerprint === undefined || marker === `${fingerprint}\n`;
+}
+
+/** Publish only the token fingerprint, before the key file, under the client lifecycle lock. */
+export function markClientConnectPending(fingerprint: string): void {
+  if (!/^[a-f0-9]{64}$/.test(fingerprint)) throw new Error("invalid pending client fingerprint");
+  atomicWriteFileNoFollowUnclaimed(pendingConnectPath(), `${fingerprint}\n`);
+}
+
+/** Clear only the marker for this connect attempt while the client lifecycle lock is held. */
+export function clearClientConnectPending(fingerprint: string): void {
+  const path = pendingConnectPath();
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.nlink !== 1 || stat.size !== 65 || readFileSync(path, "utf8") !== `${fingerprint}\n`) {
+    throw new Error("pending client connection owner changed");
+  }
+  unlinkSync(path);
+}
+
 export type ClientRotationRecoveryGate =
   | { kind: "clean" }
   | { kind: "orphan-cleaned" }

package/src/clients/config-export.ts

@@ -20,7 +20,7 @@
  * targeting it is the caller's explicit act.
  */
 import { homedir } from "node:os";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { shouldInjectApiAuthHeader, standaloneCodexRoutingTarget } from "../codex/inject";
 import { FORMAT_MEDIA_TYPE, serializeDocument, type ConfigFormat } from "../integrations/serialize";
@@ -556,7 +556,17 @@ export function omoConfigPath(env: OpencodeLaunchEnv = process.env, home: string
  * client-owned override to mirror, and this registry does not invent one.
  */
 export function asideHomeDir(_env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
-  return join(home, ".aside");
+  const root = join(home, ".aside");
+  // A user who relocated Aside (for example to an external volume) leaves ~/.aside as a
+  // symlink, and Aside itself follows it (issue 5648). Canonicalize only that top-level
+  // alias, once, and only onto a directory: every boundary below the root (u/, account
+  // directories, models.json) keeps refusing links against the canonical path.
+  try {
+    if (lstatSync(root).isSymbolicLink() && statSync(root).isDirectory()) return realpathSync.native(root);
+  } catch {
+    // Missing or unreadable: the literal path lets the profile reader report it.
+  }
+  return root;
 }
 
 /**
@@ -812,10 +822,34 @@ export interface PiProviderBlock {
   baseUrl: string;
   api: string;
   apiKey: string;
-  compat?: { sendSessionAffinityHeaders: boolean };
+  compat?: PiProviderCompat;
   models: PiModelEntry[];
 }
 
+/**
+ * The subset of Pi's per-provider `compat` block this export writes. Both keys are part of
+ * Pi's own model-config schema; an unknown key there would empty the whole config, so nothing
+ * outside this set is ever emitted.
+ */
+export interface PiProviderCompat {
+  sendSessionAffinityHeaders?: boolean;
+  supportsDeveloperRole?: boolean;
+}
+
+interface PiExportOptions {
+  sendSessionAffinityHeaders?: boolean;
+  /**
+   * Tell Pi to send its system prompt as `system` rather than `developer` (#5664).
+   *
+   * Pi sends `developer` for reasoning models by default. On `/v1/chat/completions` the proxy
+   * forwards the caller's roles verbatim unless a destination has recorded
+   * `foldDeveloperRoleToSystem`, and many OpenAI-compatible upstreams reject `developer` with a
+   * 400. `system` is accepted by every destination behind this one provider block, so the export
+   * states it rather than leaving each user to hand-edit a block the next export rewrites.
+   */
+  foldDeveloperRole?: boolean;
+}
+
 export interface PiGeneratedConfig {
   providers: Record<string, PiProviderBlock>;
 }
@@ -829,6 +863,8 @@ export interface HermesProviderBlock {
   api: string;
   api_key: string;
   api_mode: "chat_completions";
+  /** Header name only; Hermes supplies a dynamic per-conversation value. */
+  session_affinity_header: "session-id";
   /** We supply the list, so skip their live `/models` probe. */
   discover_models: false;
   models: Record<string, HermesModelEntry>;
@@ -935,7 +971,7 @@ export interface GajaeGeneratedConfig {
  * model. The rest of this contract (omitting `cost`) is still ours rather than
  * a claim about Pi's acceptance.
  */
-function buildPiClientConfig(ctx: ExportContext, sendSessionAffinityHeaders = false): PiGeneratedConfig {
+function buildPiClientConfig(ctx: ExportContext, options: PiExportOptions = {}): PiGeneratedConfig {
   const models: PiModelEntry[] = [];
   for (const model of normalizeExportModels(ctx.models)) {
     // Text is the one modality every routed model supports; anything richer must come
@@ -972,19 +1008,30 @@ function buildPiClientConfig(ctx: ExportContext, sendSessionAffinityHeaders = fa
     }
     models.push(entry);
   }
+  const compat: PiProviderCompat = {
+    ...(options.sendSessionAffinityHeaders ? { sendSessionAffinityHeaders: true } : {}),
+    ...(options.foldDeveloperRole ? { supportsDeveloperRole: false } : {}),
+  };
   return {
     providers: {
       [OPENCODE_PROVIDER_ID]: {
         baseUrl: ctx.baseUrl,
         api: PI_API_DIALECT,
         apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
-        ...(sendSessionAffinityHeaders ? { compat: { sendSessionAffinityHeaders: true } } : {}),
+        ...(Object.keys(compat).length > 0 ? { compat } : {}),
         models,
       },
     },
   };
 }
 
+/**
+ * Pi's export options, shared by `ocx export --client pi` and the managed contribution so the two
+ * never drift apart at the first refresh. omo uses the same options: senpi documents both keys in
+ * its models.json `compat` block (docs/models.md, docs/custom-provider.md).
+ */
+const PI_EXPORT_OPTIONS: PiExportOptions = { sendSessionAffinityHeaders: true, foldDeveloperRole: true };
+
 /** Do not let provider-controlled catalog text become an environment lookup. */
 function containsEnvInterpolation(value: string): boolean {
   return value.includes("${");
@@ -1006,6 +1053,7 @@ function buildHermesClientConfig(ctx: ExportContext): HermesGeneratedConfig {
         api: ctx.baseUrl,
         api_key: HERMES_API_KEY_ENV_REF,
         api_mode: "chat_completions",
+        session_affinity_header: "session-id",
         discover_models: false,
         models,
         ...(headers ? { extra_headers: headers } : {}),
@@ -1162,7 +1210,7 @@ function buildOpencodeContribution(ctx: ExportContext): ManagedContribution {
 }
 
 function buildPiContribution(ctx: ExportContext): ManagedContribution {
-  const doc = buildPiClientConfig(ctx, true);
+  const doc = buildPiClientConfig(ctx, PI_EXPORT_OPTIONS);
   return singleFragment("pi", ["providers", OPENCODE_PROVIDER_ID], doc.providers[OPENCODE_PROVIDER_ID]);
 }
 
@@ -1254,7 +1302,7 @@ function buildAsideContribution(ctx: ExportContext): ManagedContribution {
  * the two would drift apart at the first refresh.
  */
 function buildOmoContribution(ctx: ExportContext): ManagedContribution {
-  const doc = buildPiClientConfig(ctx, true);
+  const doc = buildPiClientConfig(ctx, PI_EXPORT_OPTIONS);
   return singleFragment("omo", ["providers", OPENCODE_PROVIDER_ID], doc.providers[OPENCODE_PROVIDER_ID]);
 }
 
@@ -1296,7 +1344,7 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     destination: env => piConfigPath(env),
     apiKeyEnv: "",
     exportHint: "Pi reads a non-secret placeholder from models.json; loopback needs no key.",
-    build: ctx => buildPiClientConfig(ctx, true),
+    build: ctx => buildPiClientConfig(ctx, PI_EXPORT_OPTIONS),
     format: "json",
     summarize: summarizePi,
     buildContribution: buildPiContribution,
@@ -1479,7 +1527,7 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     destination: env => omoConfigPath(env),
     apiKeyEnv: "",
     exportHint: "omo reads a non-secret placeholder from models.json; loopback needs no key.",
-    build: ctx => buildPiClientConfig(ctx, true),
+    build: ctx => buildPiClientConfig(ctx, PI_EXPORT_OPTIONS),
     format: "json",
     summarize: summarizePi,
     buildContribution: buildOmoContribution,