@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/clients/config-export/qoder.ts

@@ -0,0 +1,93 @@
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { isLoopbackHostname, shouldInjectApiAuthHeader } from "../../codex/loopback-target";
+import { formatSelectorConjunction } from "../../integrations/merge";
+import { ClientPathError } from "../config-export";
+import type { ExportContext, ManagedContribution, OpencodeLaunchEnv } from "./contracts";
+import { LOOPBACK_API_KEY_PLACEHOLDER, OPENCODE_PROVIDER_ID } from "./constants";
+import { authoritativeContextWindow, normalizeExportModels } from "./model-metadata";
+
+/**
+ * Qoder's configuration directory: `QODER_CONFIG_DIR` when set, otherwise `~/.qoder`
+ * (https://docs.qoder.com/cli/settings-reference). Export and detection both resolve it here.
+ * A relative override is refused because opencodex and Qoder would anchor it to different cwds.
+ */
+export function qoderHomeDir(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  const override = env.QODER_CONFIG_DIR?.trim();
+  if (!override) return join(home, ".qoder");
+  if (override === "~") return home;
+  if (override.startsWith("~/") || override.startsWith("~\\")) return join(home, override.slice(2));
+  if (!isAbsolute(override)) {
+    throw new ClientPathError(
+      `QODER_CONFIG_DIR must be an absolute path or start with ~; "${override}" depends on the working directory, `
+      + "so opencodex and Qoder would disagree about which file it names.",
+    );
+  }
+  return override;
+}
+
+export function qoderConfigPath(env: OpencodeLaunchEnv = process.env, home: string = homedir()): string {
+  return join(qoderHomeDir(env, home), "settings.json");
+}
+
+/** Qoder IDE and qodercli share this provider and custom-model catalog. */
+export function buildQoderClientConfig(ctx: ExportContext) {
+  if (shouldInjectApiAuthHeader(ctx.config) || !isLoopbackHostname(new URL(ctx.baseUrl).hostname)) {
+    throw new Error("Qoder's placeholder API key requires a loopback-only listener.");
+  }
+  return qoderDocument(ctx);
+}
+
+function qoderDocument(ctx: ExportContext) {
+  const models = normalizeExportModels(ctx.models);
+  return {
+    providers: {
+      [OPENCODE_PROVIDER_ID]: {
+        type: "openai-compatible",
+        protocol: "openai",
+        displayName: "opencodex",
+        baseUrl: ctx.baseUrl,
+        apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
+        ...(models[0] ? { defaultModel: models[0].namespaced } : {}),
+        models: models.map(model => ({ model: model.namespaced })),
+      },
+    },
+    modelConfigs: {
+      customModels: models.map(model => ({
+        provider: OPENCODE_PROVIDER_ID,
+        apiKey: LOOPBACK_API_KEY_PLACEHOLDER,
+        model: model.namespaced,
+        baseURL: ctx.baseUrl,
+        displayName: model.namespaced,
+        maxInputTokens: authoritativeContextWindow(model.contextWindow) ?? 128000,
+      })),
+    },
+  };
+}
+
+export type QoderGeneratedConfig = ReturnType<typeof buildQoderClientConfig>;
+
+export function summarizeQoder(document: unknown): { modelCount: number; modelsWithoutLimits: number } {
+  const models = (document as QoderGeneratedConfig | undefined)?.modelConfigs?.customModels ?? [];
+  return { modelCount: models.length, modelsWithoutLimits: 0 };
+}
+
+export function buildQoderContribution(ctx: ExportContext): ManagedContribution {
+  // The writer gates admission before applying. Classification and disable must
+  // still work after the operator changes the proxy to a non-loopback bind.
+  const doc = qoderDocument(ctx);
+  return {
+    clientId: "qoder",
+    fragments: [
+      { path: ["providers", OPENCODE_PROVIDER_ID], value: doc.providers[OPENCODE_PROVIDER_ID] },
+      ...doc.modelConfigs.customModels.map(model => {
+        const selector = formatSelectorConjunction([
+          { field: "provider", value: OPENCODE_PROVIDER_ID },
+          { field: "model", value: model.model },
+        ]);
+        if (selector === null) throw new Error("Qoder model ID cannot be represented by a managed array selector.");
+        return { path: ["modelConfigs", "customModels", selector], value: model };
+      }),
+    ],
+  };
+}

package/src/clients/config-export.ts

@@ -20,10 +20,14 @@
  * 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";
 import { FORMAT_MEDIA_TYPE, serializeDocument, type ConfigFormat } from "../integrations/serialize";
+import { fileIO } from "../integrations/config-io";
 import { canonicalizeReasoningEfforts } from "../reasoning-effort";
 import { expandFastExportModels } from "./config-export/fast-models";
 import { probeHostname } from "../server/proxy-liveness";
@@ -81,6 +85,8 @@ import {
 
 export type { CommandCodeGeneratedConfig, CommandCodeModelEntry, CommandCodeProviderBlock };
 export { buildCommandCodeClientConfig, summarizeCommandCode, buildCommandCodeContribution, commandCodeProviderRoot };
+import { buildQoderClientConfig, summarizeQoder, buildQoderContribution, qoderConfigPath } from "./config-export/qoder";
+export { buildQoderClientConfig, qoderConfigPath, qoderHomeDir, type QoderGeneratedConfig } from "./config-export/qoder";
 
 
 
@@ -210,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 {
@@ -286,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.
  *
@@ -475,10 +437,8 @@ export type ZcodePathIO = {
   readText: (path: string) => { kind: "text"; text: string } | { kind: "missing" } | { kind: "failed"; code?: string };
 };
 const zcodePathIO: ZcodePathIO = {
-  readText: path => {
-    try { return { kind: "text", text: readFileSync(path, "utf8") }; }
-    catch (error) { return (error as NodeJS.ErrnoException).code === "ENOENT" ? { kind: "missing" } : { kind: "failed" }; }
-  },
+  /** Shares the integration reader's four-MiB limit and regular-file-only bootstrap contract. */
+  readText: path => fileIO().readText(path),
 };
 export class ZcodeSettingsPathError extends ClientPathError {}
 
@@ -1429,6 +1389,18 @@ export function clineSettingsDir(env: OpencodeLaunchEnv = process.env, home: str
 }
 
 export const EXPORT_CLIENTS: Record<ExportClientId, ExportClientSpec> = {
+  qoder: {
+    id: "qoder",
+    filename: "qoder-settings.json",
+    destination: env => qoderConfigPath(env),
+    apiKeyEnv: "",
+    exportHint: "Qoder reads a non-secret placeholder from settings.json; loopback needs no key.",
+    build: buildQoderClientConfig,
+    format: "json",
+    summarize: summarizeQoder,
+    buildContribution: buildQoderContribution,
+    loopbackOnly: true,
+  },
   opencode: {
     id: "opencode",
     filename: "opencode.json",
@@ -1698,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 {