@bitkyc08/opencodex 2.86.0 → 2.87.0

package/src/clients/config-export.ts

@@ -20,6 +20,9 @@
  * targeting it is the caller's explicit act.
  */
 import { homedir } from "node:os";
+import { gentleShellPaths } from "./gentle-shell-path";
+import { absoluteClientPath, ClientPathError, piAgentDir } from "./client-path";
+export { ClientPathError, piAgentDir } from "./client-path";
 import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve, win32 } from "node:path";
 import { shouldInjectApiAuthHeader, standaloneCodexRoutingTarget } from "../codex/inject";
@@ -213,21 +216,6 @@ function ompProfileName(env: OpencodeLaunchEnv): string | undefined {
   return profile;
 }
 
-/**
- * Pi resolves its agent directory from `PI_CODING_AGENT_DIR`, falling back to
- * `~/.pi/agent`. `ompAgentDir` below already reads that variable — OMP is a Pi
- * derivative — so Pi's own resolver honoring it is what makes the two agree
- * rather than a new claim about Pi's contract.
- *
- * A relative override is refused for the same reason MCode's and ZCode's are: a
- * background proxy and a foreground client can have different working
- * directories, and would otherwise disagree about which file is named.
- */
-export function piAgentDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
-  const override = env.PI_CODING_AGENT_DIR?.trim();
-  if (override) return absoluteClientPath(override, home, "PI_CODING_AGENT_DIR");
-  return join(home, ".pi", "agent");
-}
 
 /** Pi's canonical custom-provider catalog. */
 export function piConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
@@ -289,35 +277,6 @@ export function hermesConfigPath(env: OpencodeLaunchEnv = process.env, home: str
   return join(hermesHomeDir(env, home), "config.yaml");
 }
 
-/**
- * Expand `~` against the effective home; REFUSE anything still relative.
- *
- * A first attempt at this called `resolve()` and claimed the path would "mean
- * the same thing next time". It does not: `resolve()` only anchors the current
- * invocation, so applying from one directory and disabling from another still
- * resolved two different files — the second reported "not applied" and left
- * the managed block behind with nothing claiming it.
- *
- * There is no honest way to recover the other process's cwd, so a relative
- * selector is refused at the boundary instead of being silently anchored to
- * whichever directory we happened to start in. A `~` path IS stable, because
- * it anchors to the effective home rather than the cwd.
- */
-export class ClientPathError extends Error {}
-
-function absoluteClientPath(raw: string, home: string, variable: string): string {
-  const trimmed = raw.trim();
-  if (trimmed === "~") return home;
-  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) return join(home, trimmed.slice(2));
-  if (!isAbsolute(trimmed)) {
-    throw new ClientPathError(
-      `${variable} must be an absolute path or start with ~; "${trimmed}" depends on the working directory, `
-      + "so opencodex and the client would disagree about which file it names.",
-    );
-  }
-  return trimmed;
-}
-
 /**
  * OpenClaw's EFFECTIVE home: `OPENCLAW_HOME` outranks the OS home.
  *
@@ -1711,6 +1670,21 @@ export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
     buildContribution: buildDroidContribution,
     loopbackOnly: true,
   },
+  "gentle-shell": {
+    id: "gentle-shell",
+    filename: "gentle-shell-models.json",
+    destination: env => gentleShellPaths(env).configPath,
+    apiKeyEnv: "",
+    exportHint: "Gentle Shell uses its persistent selected home; restart the shell to load the catalog. Link/shared homes use the Pi integration.",
+    build: ctx => buildPiClientConfig(ctx, PI_EXPORT_OPTIONS),
+    format: "json",
+    summarize: summarizePi,
+    buildContribution: ctx => {
+      const doc = buildPiClientConfig(ctx, PI_EXPORT_OPTIONS);
+      return singleFragment("gentle-shell", ["providers", OPENCODE_PROVIDER_ID], doc.providers[OPENCODE_PROVIDER_ID]);
+    },
+    loopbackOnly: true,
+  },
 };
 
 export const EXPORT_CLIENT_IDS: readonly ExportClientId[] = Object.keys(EXPORT_CLIENTS) as ExportClientId[];

package/src/clients/gentle-shell-path.ts

@@ -0,0 +1,87 @@
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { readBoundedRegularFileSync } from "../lib/bounded-file-read";
+import { ClientPathError, piAgentDir } from "./client-path";
+
+interface BootstrapIO {
+  readText(path: string): { kind: "text"; text: string } | { kind: "missing" } | { kind: "failed" };
+}
+
+function absolute(raw: string, label: string): string {
+  // Unlike Pi's resolver, the Shell launcher does not expand a literal '~'.
+  if (!isAbsolute(raw)) throw new ClientPathError(`${label} must be an absolute path; the proxy cannot infer the launcher's working directory.`);
+  return resolve(raw);
+}
+
+function readBootstrap(path: string, io?: BootstrapIO): string | undefined {
+  try {
+    if (!io) return readBoundedRegularFileSync(path, 64 * 1024).toString("utf8");
+    const read = io.readText(path);
+    if (read.kind === "missing") return undefined;
+    if (read.kind === "text" && Buffer.byteLength(read.text, "utf8") <= 64 * 1024) return read.text;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+  }
+  throw new ClientPathError(`Cannot read Gentle Shell launcher config at ${path}; no catalog was selected.`);
+}
+
+/** Resolve existing ancestors too, so a not-yet-created catalog cannot hide a directory alias. */
+function canonical(path: string): string {
+  const missing: string[] = [];
+  let current = resolve(path);
+  for (;;) {
+    try {
+      const value = join(realpathSync.native(current), ...missing);
+      return process.platform === "win32" ? value.toLowerCase() : value;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT" || dirname(current) === current) {
+        throw new ClientPathError(`Cannot verify Gentle Shell destination ${path}.`);
+      }
+      missing.unshift(basename(current));
+      current = dirname(current);
+    }
+  }
+}
+
+function sameFile(left: string, right: string): boolean {
+  if (canonical(left) === canonical(right)) return true;
+  // Hard-linked catalogs can have different canonical names but the same identity.
+  try {
+    const a = statSync(left, { bigint: true });
+    const b = statSync(right, { bigint: true });
+    return a.ino !== 0n && a.dev === b.dev && a.ino === b.ino;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw new ClientPathError("Cannot verify Gentle Shell and Pi catalog identities.");
+  }
+}
+
+/** Persistent selectors only: a proxy cannot observe one-off `gentle-shell --home` flags. */
+export function gentleShellPaths(
+  env: NodeJS.ProcessEnv = process.env,
+  home: string = homedir(),
+  io?: BootstrapIO,
+): { configPath: string; detectDir: string } {
+  const config = env.GENTLE_SHELL_CONFIG
+    ? absolute(env.GENTLE_SHELL_CONFIG, "GENTLE_SHELL_CONFIG")
+    : join(home, ".gentle-shell", "config.json");
+  const text = readBootstrap(config, io);
+  let selector: unknown;
+  try {
+    const parsed: unknown = text === undefined ? undefined : JSON.parse(text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) selector = (parsed as Record<string, unknown>).home;
+  } catch { /* The launcher also falls back to isolated for malformed JSON. */ }
+  const shared = "Gentle Shell uses a Pi destination; use the Pi integration for link/shared homes.";
+  if (selector === "link") throw new ClientPathError(shared);
+  const dir = typeof selector === "string" && selector.length > 0 && selector !== "isolated"
+    ? absolute(selector, "Gentle Shell saved home")
+    : env.GENTLE_SHELL_HOME
+      ? absolute(env.GENTLE_SHELL_HOME, "GENTLE_SHELL_HOME")
+      : join(home, ".gentle-shell", "agent");
+  const configPath = join(dir, "models.json");
+  const piHomes = [join(home, ".pi", "agent"), piAgentDir(env, home)];
+  if (env.GENTLE_SHELL_USER_PI_HOME) piHomes.push(absolute(env.GENTLE_SHELL_USER_PI_HOME, "GENTLE_SHELL_USER_PI_HOME"));
+  if (piHomes.some(pi => sameFile(configPath, join(pi, "models.json")))) throw new ClientPathError(shared);
+  return { configPath, detectDir: dir };
+}

package/src/codex/account-auto-switch.ts

@@ -1,6 +1,7 @@
 import type { OcxConfig } from "../types";
 import { deleteConfigObjectChildKey } from "../config/rebase-provenance";
 import { isValidCodexAccountId, MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+import { codexAccountUsesRemainingQuota } from "./account-use-remaining";
 
 export const DEFAULT_CODEX_AUTO_SWITCH_THRESHOLD = 80;
 export const MIN_CODEX_AUTO_SWITCH_THRESHOLD = 0;
@@ -34,6 +35,7 @@ export function getEffectiveCodexAutoSwitchThreshold(
   config: OcxConfig,
   accountId: string,
 ): number {
+  if (codexAccountUsesRemainingQuota(config, accountId)) return 0;
   const override = getCodexAccountAutoSwitchThresholdOverride(config, accountId);
   if (override !== null) return override;
   return config.autoSwitchThreshold ?? DEFAULT_CODEX_AUTO_SWITCH_THRESHOLD;

package/src/codex/account-identity.ts

@@ -0,0 +1,29 @@
+import type { OcxConfig } from "../types";
+import { codexLoginIdentity as identity, codexTokenIdentity, type CodexLoginIdentity } from "./signed-in-identity";
+import { MAIN_CODEX_ACCOUNT_ID, isSelectableCodexPoolAccount } from "./account-id";
+import type { CodexTokenReadResult } from "./auth-collision";
+import { getCodexAccountCredential } from "./account-store";
+
+/** Match existing entries from an already-owned main observation, without exposing identity fields. */
+export function linkedCodexAccountIds(config: OcxConfig, selectedId: string, main: CodexTokenReadResult | { status: "api-key-only" }): string[] | undefined {
+  // Unknown main identity must not produce a successful but incomplete pause.
+  if (main.status === "unreadable" || main.status === "invalid") return undefined;
+  const identities = new Map<string, CodexLoginIdentity | undefined>();
+  if (main.status === "ok") {
+    const selected = codexTokenIdentity(main.tokens);
+    if (selected === null) return undefined;
+    identities.set(MAIN_CODEX_ACCOUNT_ID, selected);
+  }
+  for (const account of config.codexAccounts ?? []) {
+    if (!isSelectableCodexPoolAccount(account)) continue;
+    const credential = getCodexAccountCredential(account.id);
+    identities.set(account.id, identity(credential?.chatgptAccountId, account.email));
+  }
+  const selected = identities.get(selectedId);
+  // Missing identity evidence never links unrelated logins, including members of one workspace.
+  if (!selected) return [selectedId];
+  return [selectedId, ...[...identities].flatMap(([id, candidate]) => (
+    id !== selectedId && candidate?.accountId === selected.accountId && candidate.email === selected.email
+      ? [id] : []
+  ))];
+}

package/src/codex/account-label.ts

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import type { CodexAccount, OcxConfig } from "../types";
 import type { CodexAuthContext } from "./auth-context";
 import type { ProviderApiKeySelection } from "../types/provider";
-import { MAIN_CODEX_ACCOUNT_ID } from "./main-account";
+import { MAIN_CODEX_ACCOUNT_ID } from "./account-id";
 
 export const CODEX_ACCOUNT_LOG_LABEL_RE = /^p[a-f0-9]{6}$/;
 

package/src/codex/account-lifecycle.ts

@@ -1,3 +1,4 @@
+import { observeSignedInCodexIdentity } from "./signed-in-identity";
 import { existsSync, readFileSync } from "node:fs";
 import {
   deleteConfigTopLevelKey,
@@ -8,17 +9,20 @@ import {
 import { captureConfigTopLevelRollback } from "../config/rebase-provenance";
 import { removeCodexAccountCredential } from "./account-store";
 import { clearAccountNeedsReauth } from "./account-runtime-state";
-import { getMainChatgptAccountId, readCodexTokensResult } from "./auth-collision";
+import { readCodexTokensResult } from "./auth-collision";
 import { MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
 import { clearAccountQuota } from "./quota";
-import { clearCodexUpstreamHealthForAccount, clearThreadAccountMapForAccount } from "./routing";
+import { forgetManualPreference } from "./routing/active-account";
+import { deleteAllHealthForAccount } from "./routing/health-store";
+import { clearThreadAccountMapForAccount } from "./routing/thread-affinity";
 
 import { clearCodexPoolRefreshFailure } from "./pool-refresh-backoff";
 import { invalidateCodexWebSocketsForAccount } from "./websocket-registry";
 import { clearMainAccountCredentialPresence, clearMainAccountInfoCache, observeMainQuotaCredential, observeMainQuotaIdentity } from "./main-account-cache";
-import { extractAccountIdClaims } from "../oauth/chatgpt";
+import { extractAccountId, extractAccountIdClaims } from "../oauth/chatgpt";
 import { forgetCodexAccountPause } from "./account-pause";
 import { forgetCodexAccountCreditUse } from "./account-credit-use";
+import { setCodexAccountUseRemainingQuota } from "./account-use-remaining";
 import { clearCodexAccountPin, forgetCodexAccountPriority } from "./account-priority";
 import { forgetCodexQuotaAutoRefreshAccount } from "./quota-auto-refresh-state";
 import { forgetCodexAccountAutoSwitchThreshold } from "./account-auto-switch";
@@ -45,7 +49,11 @@ export function purgeCodexAccountRuntimeState(accountId: string): void {
   clearAccountNeedsReauth(accountId);
   clearAccountQuota(accountId);
   clearThreadAccountMapForAccount(accountId);
-  clearCodexUpstreamHealthForAccount(accountId);
+  // Deliberately not via `./routing`: the account-delete path only needs the health rows and
+  // the manual preference gone, and importing the router here closed a cycle through
+  // routing/health-store and routing/active-account.
+  deleteAllHealthForAccount(accountId);
+  forgetManualPreference(accountId);
   clearCodexPoolRefreshFailure(accountId);
   if (accountId === MAIN_CODEX_ACCOUNT_ID) {
     clearMainAccountInfoCache();
@@ -66,7 +74,11 @@ function purgeMainCodexAccountRuntimeState(): void {
  * cooldown, quota, reauth, and thread affinity do not leak across accounts.
  */
 export function reconcileMainCodexAccountRuntimeState(): boolean {
-  const currentAccountId = getMainChatgptAccountId();
+  const read = readCodexTokensResult();
+  const currentAccountId = read.status === "ok"
+    ? extractAccountId(read.tokens.id_token, read.tokens.access_token) ?? (read.tokens.account_id || null)
+    : null;
+  if (read.status === "ok") observeSignedInCodexIdentity(read.tokens);
   // A missing/malformed auth.json is an unknown identity, not a confirmed account switch. Keep the
   // prior observation and its safety state until a real account id can be read again.
   if (currentAccountId === null) return false;
@@ -110,6 +122,7 @@ export function initializeMainAccountPolicyBinding(authPath: string): boolean {
   const previousAccountId = observedMainChatgptAccountId;
   observedMainChatgptAccountId = accountId;
   if (previousAccountId !== undefined && previousAccountId !== accountId) purgeMainCodexAccountRuntimeState();
+  observeSignedInCodexIdentity(tokens);
   observeMainQuotaIdentity(accountId);
   return observeMainQuotaCredential(tokens.access_token, accountId) !== undefined;
 }
@@ -122,6 +135,7 @@ export function applyConfirmedMainCodexAccountTransition(
   fromAccountId: string,
   toAccountId: string,
 ): boolean {
+  observeSignedInCodexIdentity();
   if (!fromAccountId || !toAccountId || fromAccountId === toAccountId) {
     if (toAccountId) {
       observedMainChatgptAccountId = toAccountId;
@@ -137,6 +151,7 @@ export function applyConfirmedMainCodexAccountTransition(
 
 export function resetMainCodexAccountIdentityTrackingForTests(): void {
   observedMainChatgptAccountId = undefined;
+  observeSignedInCodexIdentity();
   clearMainAccountCredentialPresence();
 }
 
@@ -183,6 +198,7 @@ export function deleteCodexAccount(runtimeConfig: OcxConfig, accountId: string):
     forgetCodexAccountCreditUse(runtimeConfig, accountId);
     forgetCodexAccountPriority(runtimeConfig, accountId);
     forgetCodexAccountAutoSwitchThreshold(runtimeConfig, accountId);
+    setCodexAccountUseRemainingQuota(runtimeConfig, accountId, false);
     if (runtimeConfig.codexQuotaAutoRefresh?.[accountId]) {
       const retained = { ...runtimeConfig.codexQuotaAutoRefresh };
       delete retained[accountId];

package/src/codex/account-preservation.ts

@@ -0,0 +1,28 @@
+import type { OcxConfig } from "../types";
+import { MAIN_CODEX_ACCOUNT_ID, isSelectableCodexPoolAccount } from "./account-id";
+import { getCodexAccountCredential } from "./account-store";
+import { codexAccountPriorityLookup } from "./account-priority";
+import { MIN_ACCOUNT_PRIORITY, MAX_ACCOUNT_PRIORITY } from "./pool-rotation";
+import { codexLoginIdentity, getSignedInCodexIdentity, sameCodexLogin } from "./signed-in-identity";
+
+/** Resolve current rows afresh: a pool replacement must not inherit the prior login's role. */
+export function signedInCodexAccountIds(config: OcxConfig): ReadonlySet<string> {
+  const ids = new Set([MAIN_CODEX_ACCOUNT_ID]);
+  const main = getSignedInCodexIdentity();
+  if (!main) return ids;
+  for (const account of config.codexAccounts ?? []) {
+    if (!isSelectableCodexPoolAccount(account)) continue;
+    const credential = getCodexAccountCredential(account.id);
+    if (sameCodexLogin(main, codexLoginIdentity(credential?.chatgptAccountId, account.email))) ids.add(account.id);
+  }
+  return ids;
+}
+
+/** Two disjoint bands, preserving custom order inside each; never writes the stored priorities. */
+export function codexSelectionPriorityLookup(config: OcxConfig): (id: string) => number {
+  const priority = codexAccountPriorityLookup(config);
+  if (config.codexPreserveSignedInAccount !== true) return priority;
+  const reserved = signedInCodexAccountIds(config);
+  const band = MAX_ACCOUNT_PRIORITY - MIN_ACCOUNT_PRIORITY + 1;
+  return id => priority(id) - (reserved.has(id) ? band : 0);
+}

package/src/codex/account-use-remaining.ts

@@ -0,0 +1,23 @@
+import type { OcxConfig } from "../types";
+import { deleteConfigTopLevelKey } from "../config/rebase-provenance";
+import { isValidCodexAccountId, MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+
+type Policy = Pick<OcxConfig, "codexUseRemainingQuotaAccountIds">;
+
+/** Included-quota preference only; never grants permission to spend credits. */
+export function codexAccountUsesRemainingQuota(config: Policy | undefined, accountId: string): boolean {
+  return config?.codexUseRemainingQuotaAccountIds?.includes(accountId) ?? false;
+}
+
+export function validRemainingQuotaAccountIds(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(id => id === MAIN_CODEX_ACCOUNT_ID || isValidCodexAccountId(id));
+}
+
+/** Preserve the underlying thresholds so turning this off restores their current values. */
+export function setCodexAccountUseRemainingQuota(config: OcxConfig, accountId: string, enabled: boolean): void {
+  const ids = new Set(config.codexUseRemainingQuotaAccountIds ?? []);
+  if (enabled) ids.add(accountId);
+  else ids.delete(accountId);
+  if (ids.size) config.codexUseRemainingQuotaAccountIds = [...ids];
+  else deleteConfigTopLevelKey(config, "codexUseRemainingQuotaAccountIds");
+}

package/src/codex/app-server-processes.ts

@@ -14,7 +14,7 @@ import {
   resolveTrustedWindowsPowerShellExe,
   resolveTrustedWindowsTaskkillExe,
 } from "../lib/windows-elevation";
-import { readCodexCatalogPath } from "./catalog/parsing";
+import { readCodexCatalogPath } from "./paths";
 
 export const STALE_CODEX_APP_SERVER_HINT =
   "If Codex still shows an older model list, run `ocx sync --restart-codex`: it restarts the long-lived app-server "
@@ -332,6 +332,32 @@ export function isCodexAppServerCommandLine(commandLine: string, executable?: st
   return false;
 }
 
+/**
+ * True when the command line is ANY live Codex session, not just an app-server.
+ *
+ * The update-blocking contract needs the broader reading: an interactive TUI, a
+ * one-shot `codex exec`, or an app-server all have the package's binaries in use,
+ * so every subcommand counts. The executable identity stays exactly as strict as
+ * {@link isCodexAppServerCommandLine} - only the argv discipline is dropped. A
+ * coincidental codex-shaped argument can never open this matcher.
+ */
+export function isCodexSessionCommandLine(commandLine: string, executable?: string): boolean {
+  const trimmed = commandLine.trim();
+  let tokens = tokenizeCommandLine(trimmed);
+  if (executable) {
+    if (isCodeModeHostToken(executable) || isCodexExecutableToken(executable)) return true;
+  }
+  if (tokens.length === 0) return false;
+  if (isCodeModeHostProcess(tokens)) return true;
+  // Same interpreter unwrap the app-server matcher uses: a codex-shaped token must
+  // immediately follow the interpreter so an interpreter flag value is never read
+  // as the entrypoint.
+  if (isInterpreterToken(tokens[0]!) && tokens.length > 1 && isCodexExecutableToken(tokens[1]!)) {
+    tokens = tokens.slice(1);
+  }
+  return isCodexExecutableToken(tokens[0]!);
+}
+
 function parseUnixProcStatusUid(status: string): number | undefined {
   const match = /^Uid:\s+(\d+)/m.exec(status);
   if (!match) return undefined;
@@ -339,7 +365,7 @@ function parseUnixProcStatusUid(status: string): number | undefined {
   return Number.isSafeInteger(uid) ? uid : undefined;
 }
 
-function listUnixProcSnapshots(uid: number | undefined): ProcessSnapshot[] {
+function listUnixProcSnapshots(uid: number | undefined, requireComplete = true): ProcessSnapshot[] {
   // procfs missing on a Linux-shaped platform is an enumeration failure, not
   // "no processes" — the staleness collector must not read it as not_running.
   if (!existsSync("/proc")) throw new Error("procfs_unavailable");
@@ -359,8 +385,10 @@ function listUnixProcSnapshots(uid: number | undefined): ProcessSnapshot[] {
       const commandLine = argv.join(" ").trim();
       if (!commandLine) continue;
       out.push({ pid, commandLine, executable: argv[0], uid: processUid });
-    } catch {
-      /* process exited mid-scan */
+    } catch (error) {
+      // Complete observations may ignore only disappearance. Restart target
+      // enumeration can skip an unreadable PID while retaining verified ones.
+      if (requireComplete && (error as NodeJS.ErrnoException)?.code !== "ENOENT") throw error;
     }
   }
   return out;
@@ -518,10 +546,10 @@ async function listWindowsSnapshotsAsync(): Promise<ProcessSnapshot[]> {
   return parseWindowsSnapshotOutput(output);
 }
 
-function defaultListSnapshots(platform: NodeJS.Platform, getuid: () => number | undefined): ProcessSnapshot[] {
+function defaultListSnapshots(platform: NodeJS.Platform, getuid: () => number | undefined, requireComplete = true): ProcessSnapshot[] {
   if (platform === "win32") return listWindowsSnapshots();
   if (platform === "darwin") return listDarwinSnapshots(getuid());
-  return listUnixProcSnapshots(getuid());
+  return listUnixProcSnapshots(getuid(), requireComplete);
 }
 
 export interface ListProcessSnapshotsOptions {
@@ -565,7 +593,7 @@ export function listCodexAppServerProcesses(io: CodexAppServerProcessIo = {}): C
     // Restart/kill contract (#476): enumeration failure means no targets —
     // never signal a process we could not verify.
     try {
-      snapshots = defaultListSnapshots(platform, getuid);
+      snapshots = defaultListSnapshots(platform, getuid, false);
     } catch {
       snapshots = [];
     }
@@ -581,6 +609,68 @@ export function listCodexAppServerProcesses(io: CodexAppServerProcessIo = {}): C
   return matched;
 }
 
+/**
+ * Enumeration outcome for callers that must DEFER on an unreadable process table.
+ *
+ * {@link listCodexAppServerProcesses} maps enumeration failure to an empty list because its
+ * kill contract must never signal a process it could not verify. The Codex CLI update
+ * workflow needs the opposite reading: "no matches" and "could not look" lead to different
+ * decisions, and only the first one may allow an install to proceed.
+ */
+export type CodexAppServerProcessScan =
+  | Readonly<{ kind: "observed"; processes: readonly CodexAppServerProcess[] }>
+  | Readonly<{ kind: "unavailable" }>;
+
+function scanProcessSnapshots(
+  io: CodexAppServerProcessIo,
+  matches: (commandLine: string, executable?: string) => boolean,
+): CodexAppServerProcessScan {
+  const platform = io.platform ?? process.platform;
+  const getuid = io.getuid ?? (() => {
+    try {
+      return typeof process.getuid === "function" ? process.getuid() : undefined;
+    } catch {
+      return undefined;
+    }
+  });
+  let snapshots: ProcessSnapshot[];
+  try {
+    snapshots = io.listSnapshots ? io.listSnapshots() : defaultListSnapshots(platform, getuid);
+  } catch {
+    return Object.freeze({ kind: "unavailable" as const });
+  }
+  const seen = new Set<number>();
+  const matched: CodexAppServerProcess[] = [];
+  for (const snapshot of snapshots) {
+    if (seen.has(snapshot.pid)) continue;
+    if (!matches(snapshot.commandLine, snapshot.executable)) continue;
+    seen.add(snapshot.pid);
+    matched.push({ pid: snapshot.pid, commandLine: snapshot.commandLine });
+  }
+  return Object.freeze({ kind: "observed" as const, processes: Object.freeze(matched) });
+}
+
+/** Same matcher and snapshot sources as {@link listCodexAppServerProcesses}, failing closed. */
+export function scanCodexAppServerProcesses(io: CodexAppServerProcessIo = {}): CodexAppServerProcessScan {
+  return scanProcessSnapshots(io, isCodexAppServerCommandLine);
+}
+
+/**
+ * {@link isCodexSessionCommandLine} over the same snapshot sources, failing closed.
+ *
+ * Any live Codex session counts - TUI, exec or app-server all hold the installed
+ * package open while npm would be replacing it, and a missed TUI was the reported
+ * source of a half-written install on Linux. The kill path keeps the narrower
+ * {@link isCodexAppServerCommandLine} because a signal must never leave its
+ * verified contract; this scan decides whether it is SAFE to install, so it may
+ * only err toward deferring.
+ */
+export function scanCodexSessionProcesses(io: CodexAppServerProcessIo = {}): CodexAppServerProcessScan {
+  // Shared installs may be held open by another readable user's session. This
+  // read-only scan is broader than the unchanged same-user restart/kill path.
+  return scanProcessSnapshots({ ...io, getuid: io.getuid ?? (() => undefined) }, isCodexSessionCommandLine);
+}
+
 export function formatStaleCodexAppServerWarning(
   processes: readonly { pid: number }[],
 ): string {

package/src/codex/app-server-restart-service.ts

@@ -34,6 +34,7 @@ import type {
   CodexRestartResponse,
 } from "../lib/codex-restart-contract";
 import { getServerListenPort } from "../server/lifecycle";
+import type { DesktopPickerState } from "./desktop-app/picker-freshness";
 
 async function defaultRestartDesktopApp(): Promise<CodexDesktopRestartSummary> {
   const { restartCodexDesktopApp } = await import("./desktop-app-restart");
@@ -47,9 +48,40 @@ async function defaultRestartDesktopApp(): Promise<CodexDesktopRestartSummary> {
   };
 }
 
+async function defaultDesktopPickerState(): Promise<DesktopPickerState> {
+  const { readCodexDesktopPickerState } = await import("./desktop-app/picker-freshness");
+  return readCodexDesktopPickerState();
+}
+
+async function defaultCatalogBinding(): Promise<string | null> {
+  const { readCodexCatalogBinding } = await import("./desktop-app/picker-freshness");
+  return readCodexCatalogBinding();
+}
+
+async function readBinding(io: CodexRestartServiceIo): Promise<string | null | undefined> {
+  try {
+    return await (io.catalogBinding ?? defaultCatalogBinding)();
+  } catch {
+    // Distinct from null ("binds no catalog"): an unreadable binding cannot prove sameness.
+    return undefined;
+  }
+}
+
+async function readPickerState(io: CodexRestartServiceIo): Promise<DesktopPickerState> {
+  try {
+    return await (io.desktopPickerState ?? defaultDesktopPickerState)();
+  } catch {
+    return "unknown";
+  }
+}
+
 export interface CodexRestartServiceIo {
   /** Desktop-restart seam, so a route test cannot terminate the developer's own Codex. */
   restartDesktopApp?: () => Promise<CodexDesktopRestartSummary>;
+  /** Whether the desktop picker predates the catalog; decides if the shell must restart. */
+  desktopPickerState?: () => Promise<DesktopPickerState>;
+  /** The catalog config.toml binds, read before and after the sync to catch a rebinding. */
+  catalogBinding?: () => Promise<string | null>;
   /** Process-layer seam, forwarded to every app-server-processes call. */
   processIo?: CodexAppServerProcessIo;
   /** Catalog refresh seam. Resolves to whether a catalog or cache write happened. */
@@ -133,6 +165,7 @@ async function runCodexRestart(io: CodexRestartServiceIo): Promise<CodexRestartR
   // roster; stopping app-servers before the write would hand the replacement the
   // same stale file it just lost.
   let synced = false;
+  const bindingBefore = await readBinding(io);
   try {
     const port = (io.listenPort ?? getServerListenPort)();
     synced = await (io.syncCatalog ?? defaultSyncCatalog)(port);
@@ -146,15 +179,33 @@ async function runCodexRestart(io: CodexRestartServiceIo): Promise<CodexRestartR
   (io.resetStateCache ?? resetCodexAppServerCatalogStateCache)();
   const before = (io.collectState ?? collectCodexAppServerCatalogState)(io.processIo ?? {});
 
-  // Done here, before the early returns, because the model picker lives in the DESKTOP
-  // app: "no app-server is running" is not a reason to leave a stale roster on screen,
-  // and an operator who pressed restart still wants the app back on the current catalog.
+  // Decided here, before the early returns, because the model picker lives in the DESKTOP
+  // app: "no app-server is running" is not a reason to leave a stale roster on screen.
+  //
+  // The shell restarts only when its picker predates the catalog (#4761). Quitting it
+  // discards composer drafts, unsent picker selections and pending approvals, and when
+  // the picker is already current the app-server restart below is all the operator
+  // needs: the desktop respawns its app-server child, which rereads config and catalog.
+  // An unreadable picker state takes the full restart, the behaviour before #4761.
   //
   // allowHandoff is false and that is deliberate. The handoff waits for the CALLING
   // process to exit, and this runs inside a long-lived proxy that does not, so every
   // handoff started here would sit out its window and fail after the operator had
   // already been told it was handed off. An honest refusal beats that.
-  const desktop = await (io.restartDesktopApp ?? defaultRestartDesktopApp)();
+  //
+  // A sync that rebinds model_catalog_json without rewriting the catalog bytes leaves the
+  // catalog mtime older than the shell, yet the shell loaded the previous binding. Seen
+  // across this request's own sync, that is proof of staleness, so it skips the probe.
+  const bindingAfter = await readBinding(io);
+  const rebound = bindingBefore === undefined || bindingAfter === undefined || bindingBefore !== bindingAfter;
+  const picker: DesktopPickerState = rebound ? "stale" : await readPickerState(io);
+  const desktop: CodexDesktopRestartSummary = picker === "current" || picker === "not_running"
+    ? {
+      attempted: false, stopped: [], surviving: [], relaunch: "skipped",
+      reason: picker === "current" ? "picker_current" : "no_targets",
+      pickerState: picker,
+    }
+    : { ...await (io.restartDesktopApp ?? defaultRestartDesktopApp)(), pickerState: picker };
 
   const nothingToDo = (): CodexRestartResponse => ({
     desktopApp: desktop,

package/src/codex/auth-api/account-list.ts

@@ -10,6 +10,7 @@ import { ConfigMutationLockError, mutatePersistedConfig } from "../../config";
 import { reconcileMainCodexAccountRuntimeState } from "../account-lifecycle";
 import { isCodexAccountPaused, setCodexAccountPaused } from "../account-pause";
 import { codexAccountUsesCreditsAfterLimit } from "../account-credit-use";
+import { codexAccountUsesRemainingQuota } from "../account-use-remaining";
 import { getCodexAccountPriority } from "../account-priority";
 import { getCodexAccountAutoSwitchThresholdOverride } from "../account-auto-switch";
 import { clearThreadAccountMapForAccount, isCodexAccountPlanExcluded, reconcileCodexActiveAfterExclusion } from "../routing";
@@ -143,6 +144,7 @@ export function poolAccountDto(
     priority,
     autoSwitchThresholdOverride: getCodexAccountAutoSwitchThresholdOverride(config, account.id),
     creditsAfterLimit: codexAccountUsesCreditsAfterLimit(config, account.id),
+    useRemainingQuota: codexAccountUsesRemainingQuota(config, account.id),
     quota: quota ? { ...quota } : null,
     ...codexCreditsDtoField(config, account.id, poolQuotaHistoryIdentity(account.id) ?? null),
     needsReauth: needsReauth || health.status === "reauth_required",
@@ -171,6 +173,7 @@ export interface CodexAuthAccountDto {
   autoSwitchThresholdOverride: number | null;
   /** False keeps the account out of selection while one of its usage windows is full. */
   creditsAfterLimit?: boolean;
+  useRemainingQuota?: boolean;
   quota: (StoredAccountQuota | (Omit<StoredAccountQuota, "updatedAt"> & { updatedAt: number })) | null;
   credits?: CodexCredits;
   needsReauth?: boolean;
@@ -405,6 +408,7 @@ export async function listCodexAuthAccountsSnapshot(
       priority: getCodexAccountPriority(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
       autoSwitchThresholdOverride: getCodexAccountAutoSwitchThresholdOverride(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
       creditsAfterLimit: codexAccountUsesCreditsAfterLimit(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
+      useRemainingQuota: codexAccountUsesRemainingQuota(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
       hasCredential: hasMainCredential,
       needsReauth: mainNeedsReauth,
       ...(mainReauthReason !== undefined ? { reauthReason: mainReauthReason } : {}),