@bitkyc08/opencodex 2.60.0 → 2.61.0

package/src/codex/native-main-admission.ts

@@ -3,7 +3,13 @@ import {
   tryAcquireNativeMainProfileClaim as tryAcquireLifecycleNativeMainProfileClaim,
   tryClaimNativeMainProfileForTurn as tryClaimLifecycleNativeMainProfileForTurn,
 } from "../server/lifecycle";
+import {
+  MAIN_CODEX_ACCOUNT_ID,
+  MainAccountTokenRefreshError,
+  MainAuthJsonChangedDuringRefreshError,
+} from "./main-account";
 import { isNativeMainTrafficBlocked } from "./native-profile-startup";
+import { NativeProfileError } from "./native-profile-types";
 
 export interface NativeMainTurnClaimDeps {
   /** Test seams for the synchronous precheck/claim/postcheck transition. */
@@ -45,3 +51,80 @@ export function tryAcquireNativeMainProfileClaim(): AdmissionLease | null {
   claim.release();
   return null;
 }
+
+export interface NativeMainCredentialAdmissionDeps {
+  /** Test seam for the synchronous admission precheck. */
+  readonly acquireNativeMain?: () => AdmissionLease | null;
+}
+
+const NO_EXCLUDED_ACCOUNT_IDS: ReadonlySet<string> = new Set();
+const NATIVE_MAIN_EXCLUDED_ACCOUNT_IDS: ReadonlySet<string> = new Set([MAIN_CODEX_ACCOUNT_ID]);
+const RELEASE_NOTHING = () => {};
+
+/**
+ * Run credential-backed work inside the native-main lifecycle fence.
+ *
+ * The lease keeps startup recovery and profile drains from owning the physical
+ * credential while the operation reads it. Cross-process ownership of the file
+ * itself is already coordinated inside the refresh path's exclusive claim, so
+ * this fence deliberately does not take the shared claim: holding it across an
+ * operation that may refresh would ask for exclusive ownership against our own
+ * shared lock, and holding it across the upstream work that follows would
+ * stall an unrelated credential commit behind a network fetch.
+ *
+ * The fence covers only the credential read. The operation must invoke
+ * `releaseMainLease` as soon as the native-main credential settles — on both
+ * the success and the credential-error path — and before any upstream model
+ * listing, so a profile drain never waits on a network fetch while this turn
+ * is still counted. The wrapper releases on settle regardless, so an
+ * operation without a fenced credential phase may ignore the callback.
+ *
+ * When the gate refuses, or the credential cannot be read because another
+ * lifecycle owns it, the operation reruns with main excluded so independent
+ * Pool work is never suppressed by main's unavailability.
+ */
+export async function withNativeMainCredentialAdmission<T>(
+  operation: (
+    excludeAccountIds: ReadonlySet<string>,
+    releaseMainLease?: () => void,
+  ) => Promise<T>,
+  deps: NativeMainCredentialAdmissionDeps = {},
+): Promise<T> {
+  const lease = (deps.acquireNativeMain ?? tryAcquireNativeMainProfileClaim)();
+  if (!lease) return operation(NATIVE_MAIN_EXCLUDED_ACCOUNT_IDS, RELEASE_NOTHING);
+  let released = false;
+  const releaseMainLease = () => {
+    if (released) return;
+    released = true;
+    lease.release();
+  };
+  try {
+    return await operation(NO_EXCLUDED_ACCOUNT_IDS, releaseMainLease);
+  } catch (error) {
+    // The Pool-only retry never reads the native-main credential; release first
+    // so a profile drain is not kept waiting behind Pool network work.
+    releaseMainLease();
+    if (!isNativeMainCredentialUnavailableError(error)) throw error;
+    return await operation(NATIVE_MAIN_EXCLUDED_ACCOUNT_IDS, RELEASE_NOTHING);
+  } finally {
+    releaseMainLease();
+  }
+}
+
+/**
+ * The credential-ownership failures that make main unavailable for one
+ * operation: a foreign exclusive holder or an unsupported claim filesystem
+ * (NATIVE_MAIN_CLAIM_BUSY / NATIVE_MAIN_CLAIM_UNAVAILABLE), a writer that moved
+ * auth.json mid-refresh, or a grant that no longer refreshes. Like a Pool
+ * credential failure, none of them may suppress independent Pool discovery.
+ * Any other NativeProfileError — MAIN_REQUESTS_ACTIVE, VAULT_INVALID,
+ * INTERNAL_ERROR — is not a credential-ownership failure and propagates.
+ */
+function isNativeMainCredentialUnavailableError(error: unknown): boolean {
+  if (error instanceof NativeProfileError) {
+    return error.code === "NATIVE_MAIN_CLAIM_BUSY"
+      || error.code === "NATIVE_MAIN_CLAIM_UNAVAILABLE";
+  }
+  return error instanceof MainAuthJsonChangedDuringRefreshError
+    || error instanceof MainAccountTokenRefreshError;
+}

package/src/codex/routing/health-store.ts

@@ -350,6 +350,45 @@ export function deleteAccountHealth(accountId: string): void {
   upstreamHealth.delete(accountId);
 }
 
+export function carriesQuotaRefusal(health: CodexUpstreamHealth | undefined): boolean {
+  return health?.lastFailureStatus === 429 || health?.lastFailureStatus === 402;
+}
+
+/**
+ * Has this account refused a request on quota without serving one since?
+ *
+ * Thread affinity is a prompt-cache optimization and every rule around it is a preference:
+ * `autoSwitchThreshold` is a hint that an account is getting busy, and `pool.cacheAffinity`
+ * deliberately raises that bar further. A refusal is not a preference, and once the account has
+ * told THIS thread it cannot serve, the binding has nothing left to optimize.
+ *
+ * The distinction matters because the cooldown a 429 writes is deliberately short. A reset
+ * announcement is advisory — plan quota routinely frees up before the advertised instant — so
+ * {@link CODEX_MAX_RESET_DERIVED_COOLDOWN_MS} caps it at 15 minutes. The five-hour window that
+ * announcement describes is not capped, so an account whose burst window is spent looks
+ * selectable again long before it is. For an unbound request that is correct: going back to find
+ * out is how the pool learns the window moved. For a BOUND thread it is a loop with no exit —
+ * the cooldown lapses, the account still scores lowest on the only window this proxy has a
+ * reading for (its weekly bar, untouched by a burst limit), the thread rebinds, and earns the
+ * identical 429. Cleared affinity does not help: the next request re-derives the same choice.
+ * From the Codex side that reads exactly as reported — a new session rotates normally while an
+ * existing one is locked to an exhausted account until the proxy is restarted, because a restart
+ * is the only thing that drops the binding and the stale health together.
+ *
+ * `lastFailureStatus` is the right evidence because of when it ends: {@link preservedCooldownFields}
+ * strips it from every recovery write, so it survives exactly until the account actually serves a
+ * request again. Nothing here blocks that — selection is untouched, so unbound traffic still probes
+ * the account and the first success releases every thread this refused.
+ *
+ * Scope follows where the refusal was recorded. An account-wide throttle lands in
+ * `upstreamHealth` and releases every lane; a reset-derived refusal lands against one native
+ * quota group, so a spent Spark window still cannot displace the same thread's Terra binding.
+ */
+export function hasUnrecoveredCodexQuotaRefusal(accountId: string, quotaScope?: CodexQuotaScope): boolean {
+  if (carriesQuotaRefusal(getAccountHealth(accountId))) return true;
+  return quotaScope !== undefined && carriesQuotaRefusal(scopedHealthFor(accountId, quotaScope));
+}
+
 export function listScopedHealthEntries(accountId: string): Array<[CodexQuotaScope, CodexUpstreamHealth]> {
   return [...(quotaScopedHealth.get(accountId) ?? [])];
 }

package/src/codex/routing/selection.ts

@@ -22,6 +22,7 @@ import {
   dropSpentCredentialFailure,
   getAccountHealth,
   getCodexQuotaHealthSnapshot,
+  hasUnrecoveredCodexQuotaRefusal,
   isCodexAccountSoftAvoided,
   isCodexQuotaAvoided,
   isIndependentCodexQuotaScope,
@@ -276,6 +277,40 @@ export function isCacheAffinityEnabled(config: OcxConfig): boolean {
   return config.pool?.cacheAffinity !== false;
 }
 
+/**
+ * Whether quota may retire shared state while cache affinity is active.
+ *
+ * A threshold crossing is a hint that an account is getting busy, not evidence it cannot
+ * serve — the same bar {@link mayRebindAffinityForQuota} applies to a live binding. Shared
+ * state held across a model detour gets that exhaustion boundary for the same reason: the
+ * detour is request-scoped, so retiring the binding over a hint pays a cold prefix for
+ * nothing. New/unbound selection still reads {@link hasCodexQuotaHeadroom}; only
+ * preservation of an existing shared selection or thread binding qualifies here. Like the
+ * live-binding rule, the configured threshold plays no role once retention applies: a
+ * genuinely exhausted (>=100%) account releases even with threshold switching disabled,
+ * while the fallback above keeps a disabled threshold's "never drained on quota alone".
+ */
+export function hasCodexSharedStateQuotaHeadroom(
+  config: OcxConfig,
+  accountId: string,
+  quotaScope: CodexQuotaScope | undefined,
+  selectionOptions?: CodexAccountUsabilityOptions,
+  now: number = Date.now(),
+): boolean {
+  if (
+    !isCacheAffinityEnabled(config)
+    || accountPoolStrategyForScope(config, quotaScope) !== "quota"
+  ) {
+    return hasCodexQuotaHeadroom(config, accountId, selectionOptions, now);
+  }
+  const usage = computeCodexUsageScore(
+    getAccountQuota(accountId),
+    getPoolAccountPlanForSelection(config, accountId, selectionOptions),
+    now,
+  );
+  return isUnknownUsage(usage) || usage < 100;
+}
+
 /** Earliest future shared short/weekly reset; missing evidence and ties use usage order. */
 export function pickResetFirstCodexAccount(
   config: OcxConfig,
@@ -726,7 +761,8 @@ export function isHealthySharedCodexSelection(
   selectionOptions: CodexAccountUsabilityOptions | undefined,
 ): boolean {
   return isCodexAccountSelectable(config, accountId, now, quotaScope, selectionOptions)
-    && hasCodexQuotaHeadroom(config, accountId, selectionOptions, now)
+    && hasCodexSharedStateQuotaHeadroom(config, accountId, quotaScope, selectionOptions, now)
+    && !hasUnrecoveredCodexQuotaRefusal(accountId, quotaScope)
     && !shouldFailover(config, accountId, now);
 }
 

package/src/codex/routing.ts

@@ -28,6 +28,7 @@ import {
   type CodexUpstreamOutcomeMeta,
 } from "./routing/cooldown-math";
 import {
+  carriesQuotaRefusal,
   codexPoolKeyForScope,
   codexQuotaScopeForModel,
   deleteAccountHealth,
@@ -38,6 +39,7 @@ import {
   getCodexAccountCooldownUntil,
   getCodexAccountSoftAvoidUntil,
   getCodexQuotaHealthSnapshot,
+  hasUnrecoveredCodexQuotaRefusal,
   isCodexAccountSoftAvoided,
   isCodexQuotaAvoided,
   isHealthAccountAdmissible,
@@ -93,6 +95,7 @@ import {
   getEligiblePoolAccounts,
   getPoolAccountPlanForSelection,
   hasCodexQuotaHeadroom,
+  hasCodexSharedStateQuotaHeadroom,
   isCodexAccountPlanExcluded,
   isCodexAccountSelectable,
   isHealthySharedCodexSelection,
@@ -489,45 +492,6 @@ export function resolveCodexAccountForThread(
   return resolution.status === "selected" ? resolution.accountId : null;
 }
 
-function carriesQuotaRefusal(health: CodexUpstreamHealth | undefined): boolean {
-  return health?.lastFailureStatus === 429 || health?.lastFailureStatus === 402;
-}
-
-/**
- * Has this account refused a request on quota without serving one since?
- *
- * Thread affinity is a prompt-cache optimization and every rule around it is a preference:
- * `autoSwitchThreshold` is a hint that an account is getting busy, and `pool.cacheAffinity`
- * deliberately raises that bar further. A refusal is not a preference, and once the account has
- * told THIS thread it cannot serve, the binding has nothing left to optimize.
- *
- * The distinction matters because the cooldown a 429 writes is deliberately short. A reset
- * announcement is advisory — plan quota routinely frees up before the advertised instant — so
- * {@link CODEX_MAX_RESET_DERIVED_COOLDOWN_MS} caps it at 15 minutes. The five-hour window that
- * announcement describes is not capped, so an account whose burst window is spent looks
- * selectable again long before it is. For an unbound request that is correct: going back to find
- * out is how the pool learns the window moved. For a BOUND thread it is a loop with no exit —
- * the cooldown lapses, the account still scores lowest on the only window this proxy has a
- * reading for (its weekly bar, untouched by a burst limit), the thread rebinds, and earns the
- * identical 429. Cleared affinity does not help: the next request re-derives the same choice.
- * From the Codex side that reads exactly as reported — a new session rotates normally while an
- * existing one is locked to an exhausted account until the proxy is restarted, because a restart
- * is the only thing that drops the binding and the stale health together.
- *
- * `lastFailureStatus` is the right evidence because of when it ends: {@link preservedCooldownFields}
- * strips it from every recovery write, so it survives exactly until the account actually serves a
- * request again. Nothing here blocks that — selection is untouched, so unbound traffic still probes
- * the account and the first success releases every thread this refused.
- *
- * Scope follows where the refusal was recorded. An account-wide throttle lands in
- * `upstreamHealth` and releases every lane; a reset-derived refusal lands against one native
- * quota group, so a spent Spark window still cannot displace the same thread's Terra binding.
- */
-function hasUnrecoveredCodexQuotaRefusal(accountId: string, quotaScope?: CodexQuotaScope): boolean {
-  if (carriesQuotaRefusal(getAccountHealth(accountId))) return true;
-  return quotaScope !== undefined && carriesQuotaRefusal(scopedHealthFor(accountId, quotaScope));
-}
-
 function previewReusableAffinityAccount(
   entry: ThreadAffinityEntry | undefined,
   config: OcxConfig,
@@ -952,7 +916,7 @@ export function resolveCodexAccountForThreadDetailed(
     // the account has already told this thread it cannot serve it.
     const quotaRefused = hasUnrecoveredCodexQuotaRefusal(entry.accountId, quotaScope);
     const healthyForSharedAffinity = selectableForSharedState
-      && hasCodexQuotaHeadroom(config, entry.accountId, sharedSelectionOptions, now)
+      && hasCodexSharedStateQuotaHeadroom(config, entry.accountId, quotaScope, sharedSelectionOptions, now)
       && !quotaRefused
       && !failoverReady;
     if (
@@ -1150,7 +1114,7 @@ export function resolveCodexAccountForThreadDetailed(
     sharedSelectionOptions,
   );
   const activeHealthyForSharedSelection = activeSelectableForSharedState
-    && hasCodexQuotaHeadroom(config, active, sharedSelectionOptions, now)
+    && hasCodexSharedStateQuotaHeadroom(config, active, quotaScope, sharedSelectionOptions, now)
     && !shouldFailover(config, active, now);
   if (!isCodexAccountSelectable(config, active, now, quotaScope, selectionOptions)) {
     const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope, selectionOptions);

package/src/codex/shim-templates.ts

@@ -4,11 +4,29 @@ import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { windowsEnvIndirectBatchValue } from "../lib/win-paths";
 
 const SHIM_MARKER = "opencodex codex autostart shim";
-const UNIX_SHIM_REVISION_MARKER = "opencodex unix codex shim revision 2";
+const UNIX_SHIM_REVISION_MARKER = "opencodex unix codex shim revision 3";
 
 const CODEX_SHIM_REENTRY_EXIT_CODE = 126;
 const CODEX_SHIM_REENTRY_DIAGNOSTIC = "opencodex: saved Codex launcher resolved back to the autostart shim; run ocx codex-shim uninstall and reinstall Codex before enabling codexAutoStart.";
 
+/**
+ * Said once, on stderr, when `ocx ensure` could not bring the proxy up (#5261).
+ *
+ * The shim used to discard both of ensure's streams and ignore its exit status, so a failed
+ * autostart was completely silent: Codex launched against injected routing pointing at a port
+ * nothing was listening on, and every request — sign-in included — failed with no mention of
+ * opencodex anywhere.
+ *
+ * Ensure's own streams stay discarded rather than being let through. Ensure prints progress and
+ * warnings on exit-zero runs too, and a wrapper that leaked those would put noise in front of
+ * every ordinary Codex launch, which is how a diagnostic gets ignored. The exit status is the
+ * signal; this line is the whole message.
+ *
+ * It names `ocx restore` because bringing the proxy back is only half the choice. A user who
+ * cannot sign in needs the way out that does not require the proxy at all.
+ */
+export const CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC = "opencodex: proxy autostart failed; launching Codex anyway. Run 'ocx doctor' for details, or 'ocx restore' to hand Codex back to its own account.";
+
 const CODEX_INTERNAL_COMMANDS = [
   "app-server",
   "archive",
@@ -136,7 +154,9 @@ case "$ocx_subcommand" in
     ;;
   *)
     if [ -z "$OCX_SHIM_BYPASS" ]; then
-      ${BUN_RUNTIME_SOURCE_ENV}=${shQuote(bunRuntimeSource)} ${BUN_RUNTIME_PATH_ENV}=${shQuote(bunPath)} ${shQuote(bunPath)} ${shQuote(cliPath)} ensure >/dev/null 2>&1 || true
+      if ! ${BUN_RUNTIME_SOURCE_ENV}=${shQuote(bunRuntimeSource)} ${BUN_RUNTIME_PATH_ENV}=${shQuote(bunPath)} ${shQuote(bunPath)} ${shQuote(cliPath)} ensure >/dev/null 2>&1; then
+        printf '%s\\n' ${shQuote(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC)} >&2
+      fi
     fi
     ;;
 esac
@@ -197,6 +217,7 @@ setlocal\r
 ${windowsBatchSet(BUN_RUNTIME_SOURCE_ENV, bunRuntimeSource)}\r
 ${windowsBatchSet(BUN_RUNTIME_PATH_ENV, bunPath)}\r
 "%OCX_BUN%" "%OCX_CLI%" ensure >nul 2>nul\r
+if errorlevel 1 echo ${CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC} 1>&2\r
 endlocal\r
 :run_codex\r
 "%OCX_REAL_CODEX%" %*\r
@@ -239,13 +260,18 @@ if (-not $skipEnsure) {
   $priorRuntimePath = $env:${BUN_RUNTIME_PATH_ENV}
   $env:${BUN_RUNTIME_SOURCE_ENV} = ${psString(bunRuntimeSource)}
   $env:${BUN_RUNTIME_PATH_ENV} = ${psString(bunPath)}
-  try { & ${psString(bunPath)} ${psString(cliPath)} ensure *> $null }
+  $ocxEnsureFailed = $false
+  # Caught, not propagated: a throwing ensure used to escape this wrapper and Codex never
+  # launched at all, which is a lockout produced by the autostart helper itself (#5261).
+  try { & ${psString(bunPath)} ${psString(cliPath)} ensure *> $null; if ($LASTEXITCODE -ne 0) { $ocxEnsureFailed = $true } }
+  catch { $ocxEnsureFailed = $true }
   finally {
     if ($null -eq $priorRuntimeSource) { Remove-Item Env:\\${BUN_RUNTIME_SOURCE_ENV} -ErrorAction SilentlyContinue }
     else { $env:${BUN_RUNTIME_SOURCE_ENV} = $priorRuntimeSource }
     if ($null -eq $priorRuntimePath) { Remove-Item Env:\\${BUN_RUNTIME_PATH_ENV} -ErrorAction SilentlyContinue }
     else { $env:${BUN_RUNTIME_PATH_ENV} = $priorRuntimePath }
   }
+  if ($ocxEnsureFailed) { [Console]::Error.WriteLine(${psString(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC)}) }
 }
 & ${psString(realCodexPath)} @args
 $codexExitCode = $LASTEXITCODE

package/src/companion/settings.ts

@@ -0,0 +1,132 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config/paths";
+import {
+  TIMELINE_HOURS,
+  isTimelineModelId,
+  type TimelineAggregation,
+  type TimelineGrouping,
+  type TimelineMetric,
+} from "../usage/timeline";
+
+export interface CompanionSettings {
+  menuBarMetric: "requests" | "tokens" | "cost" | "quota" | "none";
+  menuBarTemplate: string | null;
+  showToday: boolean;
+  showChart: boolean;
+  showModels: boolean;
+  showCost: boolean;
+  showAccounts: boolean;
+  chartHours: typeof TIMELINE_HOURS[number];
+  bucketMinutes: number;
+  chartStyle: "line" | "stackedBar";
+  tokenMetric: TimelineMetric;
+  aggregation: TimelineAggregation;
+  chartGrouping: TimelineGrouping;
+  models: string[] | null;
+  hiddenProviders: string[];
+}
+
+export const DEFAULT_COMPANION_SETTINGS: CompanionSettings = {
+  menuBarMetric: "tokens",
+  menuBarTemplate: null,
+  showToday: true,
+  showChart: true,
+  showModels: true,
+  showCost: true,
+  showAccounts: true,
+  chartHours: 24,
+  bucketMinutes: 60,
+  chartStyle: "line",
+  tokenMetric: "total",
+  aggregation: "sum",
+  chartGrouping: "model",
+  models: null,
+  hiddenProviders: [],
+};
+
+const TEMPLATE_FIELDS = new Set(["requests", "totalTokens", "inputTokens", "outputTokens", "costUsd", "quotaPercent"]);
+const MENU_BAR_METRICS = new Set(["requests", "tokens", "cost", "quota", "none"]);
+const CHART_STYLES = new Set(["line", "stackedBar"]);
+const TIMELINE_METRICS = new Set(["total", "input", "output", "cached"]);
+const AGGREGATIONS = new Set(["sum", "average", "max"]);
+const GROUPINGS = new Set(["model", "modelAccount"]);
+const SETTINGS_KEYS = Object.keys(DEFAULT_COMPANION_SETTINGS) as (keyof CompanionSettings)[];
+
+export function companionSettingsPath(): string {
+  return join(getConfigDir(), "companion.json");
+}
+
+function invalid(message: string): { error: string } {
+  return { error: message };
+}
+
+function validModels(value: unknown, key: string): value is string[] | null {
+  return value === null
+    || (Array.isArray(value)
+      && value.length <= 100
+      && value.every(isTimelineModelId));
+}
+
+function validateValue(key: keyof CompanionSettings, value: unknown): string | null {
+  if (key === "menuBarMetric") return typeof value === "string" && MENU_BAR_METRICS.has(value) ? null : "menuBarMetric is invalid";
+  if (key === "menuBarTemplate") {
+    if (value === null) return null;
+    if (typeof value !== "string" || value.length > 200) return "menuBarTemplate must be null or at most 200 characters";
+    for (const match of value.matchAll(/\{([^{}]+)\}/g)) {
+      if (!TEMPLATE_FIELDS.has(match[1]!)) return `menuBarTemplate contains unknown placeholder: ${match[1]}`;
+    }
+    return null;
+  }
+  if (["showToday", "showChart", "showModels", "showCost", "showAccounts"].includes(key)) {
+    return typeof value === "boolean" ? null : `${key} must be a boolean`;
+  }
+  if (key === "chartHours") return TIMELINE_HOURS.includes(value as typeof TIMELINE_HOURS[number]) ? null : "chartHours is invalid";
+  if (key === "bucketMinutes") return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 1440 ? null : "bucketMinutes must be an integer from 1 through 1440";
+  if (key === "chartStyle") return typeof value === "string" && CHART_STYLES.has(value) ? null : "chartStyle is invalid";
+  if (key === "tokenMetric") return typeof value === "string" && TIMELINE_METRICS.has(value) ? null : "tokenMetric is invalid";
+  if (key === "aggregation") return typeof value === "string" && AGGREGATIONS.has(value) ? null : "aggregation is invalid";
+  if (key === "chartGrouping") return typeof value === "string" && GROUPINGS.has(value) ? null : "chartGrouping is invalid";
+  if (key === "models") return validModels(value, key) ? null : "models must be null or at most 100 provider/model identifiers";
+  if (key === "hiddenProviders") return Array.isArray(value) && value.length <= 100 && value.every(item => typeof item === "string" && item.length > 0 && !/\s/.test(item))
+    ? null : "hiddenProviders must contain at most 100 provider names";
+  return `${key} is unsupported`;
+}
+
+export function applyCompanionSettingsPatch(
+  current: CompanionSettings,
+  patch: unknown,
+): CompanionSettings | { error: string } {
+  if (!patch || typeof patch !== "object" || Array.isArray(patch)) return invalid("settings must be an object");
+  const values = patch as Record<string, unknown>;
+  for (const key of Object.keys(values)) {
+    if (!SETTINGS_KEYS.includes(key as keyof CompanionSettings)) return invalid(`unknown settings key: ${key}`);
+    const error = validateValue(key as keyof CompanionSettings, values[key]);
+    if (error) return invalid(error);
+  }
+  return { ...current, ...values } as CompanionSettings;
+}
+
+export function loadCompanionSettings(): { settings: CompanionSettings; updatedAt: number | null; corrupt?: true } {
+  const path = companionSettingsPath();
+  if (!existsSync(path)) return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    const settings = applyCompanionSettingsPatch(DEFAULT_COMPANION_SETTINGS, parsed);
+    if ("error" in settings) return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null, corrupt: true };
+    return { settings, updatedAt: statSync(path).mtimeMs };
+  } catch {
+    return { settings: { ...DEFAULT_COMPANION_SETTINGS }, updatedAt: null, corrupt: true };
+  }
+}
+
+export function saveCompanionSettings(settings: CompanionSettings): void {
+  const path = companionSettingsPath();
+  const dir = getConfigDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(temp, 0o600);
+  renameSync(temp, path);
+  chmodSync(path, 0o600);
+}

package/src/config/atomic-write.ts

@@ -2,6 +2,7 @@ import {
   chmodSync,
   closeSync,
   fchmodSync,
+  fsyncSync,
   fstatSync,
   lstatSync,
   openSync,
@@ -10,7 +11,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { dirname } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import {
@@ -162,6 +163,27 @@ function carryHardenAcrossContentWrite(path: string): void {
   reattributeHardenedSecretPath(path);
 }
 
+/**
+ * Commit the directory entry a rename just wrote.
+ *
+ * Best effort by platform, not by importance: Windows has no directory descriptor to sync and
+ * some filesystems refuse the open, and failing a replacement that already happened would be
+ * worse than reporting it. The throw that matters is the temp's own `fsync`, which runs before
+ * the rename and stops it.
+ */
+function syncParentDirectory(target: string): void {
+  if (process.platform === "win32") return;
+  let descriptor: number | undefined;
+  try {
+    descriptor = openSync(dirname(target), "r");
+    fsyncSync(descriptor);
+  } catch {
+    /* the rename already landed; a directory that cannot be synced is not a reason to undo it */
+  } finally {
+    if (descriptor !== undefined) { try { closeSync(descriptor); } catch { /* already closed */ } }
+  }
+}
+
 function writePrivateTempFile(
   path: string,
   content: string,
@@ -191,6 +213,40 @@ function writePrivateTempFile(
   carryHardenAcrossContentWrite(path);
 }
 
+/**
+ * The same private temp, filled by a writer that streams into the descriptor.
+ *
+ * For content that must not be held in memory as one string. The identity assertions, the
+ * ownership handshake and the hardening are the same; the difference is that the bytes arrive in
+ * bounded chunks and the descriptor is flushed before it closes.
+ *
+ * The `fsync` is not optional here and its failure is not swallowed. A replacement whose
+ * REPLACEMENT is not on disk can lose the rows it was supposed to retain, so the throw is what
+ * stops the rename from happening at all.
+ */
+function writePrivateTempFileWith(
+  path: string,
+  write: (descriptor: number) => void,
+  timeoutMemoKey: string,
+  onCreated: () => void,
+): void {
+  const descriptor = openSync(path, "wx", 0o600);
+  onCreated();
+  try {
+    if (windowsHardeningApplies()) {
+      hardenSecretPath(path, { required: true, timeoutMemoKey });
+    }
+    if (process.platform !== "win32") fchmodSync(descriptor, 0o600);
+    assertPrivateTempDescriptor(path, descriptor);
+    write(descriptor);
+    assertPrivateTempDescriptor(path, descriptor);
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+  carryHardenAcrossContentWrite(path);
+}
+
 async function writePrivateTempFileAsync(
   path: string,
   content: string,
@@ -215,14 +271,14 @@ async function writePrivateTempFileAsync(
   carryHardenAcrossContentWrite(path);
 }
 
-export function atomicWriteFile(
+function atomicWriteFileToTarget(
   path: string,
-  content: string,
+  content: string | ((descriptor: number) => void),
+  target: string,
   io?: AtomicWriteIO,
   hooks: AtomicWriteHooks = {},
 ): void {
   recordOwnedConfigPath(getConfigDir(), path);
-  const target = resolveWriteTarget(path);
   assertResolvedTargetAllowed(path, target);
   const tmp = `${target}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
   let hardened = false;
@@ -246,13 +302,26 @@ export function atomicWriteFile(
   };
   try {
     if (io) ownsTemp = true;
-    effective.write(tmp, content);
+    // A streaming writer bypasses the string form of `write` and nothing else. Every later
+    // step -- harden, the pre-rename hooks, the rename and the whole residual-cleanup path,
+    // which still scrubs through `effective.write(tmp, "")` -- is shared with the string form.
+    if (typeof content === "function") writePrivateTempFileWith(tmp, content, path, () => { ownsTemp = true; });
+    else effective.write(tmp, content);
     hooks.afterTempWrite?.(tmp, target);
     effective.harden(tmp);
     hardened = true;
     hooks.beforeRename?.(tmp, target);
     hooks.validateBeforeRename?.(target);
     effective.rename(tmp, target);
+    // The rename is only as durable as the directory entry recording it. Fsyncing the temp's
+    // CONTENT and then losing the entry in a power cut leaves the old file in place, or the
+    // directory in an indeterminate state, while the caller was told the replacement landed.
+    //
+    // Only the streaming form does this. It is the one that makes a durability claim -- a
+    // replacement is not an append, and losing it can lose the rows it was meant to keep -- and
+    // adding a directory sync to the string form would charge every config write for a promise
+    // its callers have never been given.
+    if (typeof content === "function") syncParentDirectory(target);
     forgetEphemeralSecretPath(tmp);
   } catch (cause) {
     if (!ownsTemp) throw cause;
@@ -287,6 +356,49 @@ export function atomicWriteFile(
   }
 }
 
+export function atomicWriteFile(
+  path: string,
+  content: string,
+  io?: AtomicWriteIO,
+  hooks: AtomicWriteHooks = {},
+): void {
+  atomicWriteFileToTarget(path, content, resolveWriteTarget(path), io, hooks);
+}
+
+/**
+ * Atomically replace a file with bytes produced straight into the temporary descriptor.
+ *
+ * Same publication contract as {@link atomicWriteFile}: an exclusively created private temp, the
+ * identity assertions around the write, `hooks.validateBeforeRename` immediately before the
+ * rename, the platform-aware replace, and the residual cleanup on any failure. A custom
+ * {@link AtomicWriteIO} is not accepted, because the point of this form is that the default
+ * writer owns the descriptor.
+ */
+export function atomicWriteFileStreamed(
+  path: string,
+  write: (descriptor: number) => void,
+  hooks: AtomicWriteHooks = {},
+): void {
+  atomicWriteFileToTarget(path, write, resolveWriteTarget(path), undefined, hooks);
+}
+
+/**
+ * Atomically replace the named directory entry without resolving a symlink at
+ * that entry. This is for files in directories writable by another process:
+ * a raced symlink is replaced, never followed to a more privileged target.
+ */
+export function atomicWriteFileNoFollow(
+  path: string,
+  content: string,
+  io?: AtomicWriteIO,
+  hooks: AtomicWriteHooks = {},
+): void {
+  // Only the final entry is no-follow: the parent still resolves, because an
+  // OS alias above the configured root (a home junction, /tmp) is legitimate
+  // and Windows cannot exclusive-create a temp through a junction.
+  atomicWriteFileToTarget(path, content, join(resolveWriteTarget(dirname(path)), basename(path)), io, hooks);
+}
+
 export interface AtomicWriteAsyncIO {
   write: (path: string, content: string) => void | Promise<void>;
   harden: (path: string) => void | Promise<void>;