@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/adapters/openai-responses/plaintext-reasoning-notice.ts

@@ -0,0 +1,85 @@
+import { sanitizeLogMetadataString } from "../../lib/redact";
+import { isOpenAiOperatedResponsesDestination } from "../../providers/openai-tiers";
+import { normalizedProviderEndpoint, PROVIDER_REGISTRY } from "../../providers/registry";
+import type { OcxProviderConfig } from "../../types";
+
+/**
+ * #6675: a custom Responses provider drops replayed plaintext reasoning unless it sets
+ * `preserveResponsesReasoningContent`. That default is deliberate (the ChatGPT backend rejects
+ * echoed raw reasoning, and forwarding it costs tokens), but it is silent, and the similarly named
+ * Chat-wire `preserveReasoningContentModels` does not opt in. Say so once per destination.
+ *
+ * Only a hand-configured `openai-responses` row with key auth qualifies. Registry presets (matched
+ * by endpoint on either OpenAI wire, since a preset may be routed to Responses per model), OAuth and
+ * forward rows, Azure, and OpenAI-operated destinations are skipped: their replay contract is
+ * curated, so blanking there is a decision rather than a missing setting. The notice carries only
+ * the destination host and option names, never request content.
+ */
+const MAX_NOTICED_DESTINATIONS = 64;
+const noticedDestinations = new Set<string>();
+
+function destinationHost(baseUrl: unknown): string | undefined {
+  if (typeof baseUrl !== "string") return undefined;
+  try {
+    return sanitizeLogMetadataString(new URL(baseUrl).host, 128);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Azure OpenAI and Azure AI Foundry serve OpenAI-operated models under per-resource hosts. */
+const AZURE_OPENAI_HOST_SUFFIXES = [".openai.azure.com", ".services.ai.azure.com", ".cognitiveservices.azure.com"];
+
+function hostnameOf(url: string): string | undefined {
+  try {
+    return new URL(url).hostname.toLowerCase();
+  } catch {
+    return undefined;
+  }
+}
+
+/** A templated preset (`https://{resource}.openai.azure.com/...`) matches by host pattern. */
+function templatedHostMatches(template: string, hostname: string): boolean {
+  const host = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]+)/i.exec(template)?.[1];
+  if (!host || !/\{[^}]*\}/.test(host)) return false;
+  const pattern = host.toLowerCase().split(/\{[^}]*\}/).map(part => part.replace(/[.*+?^$()|[\]\\]/g, "\\$&")).join("[^.]+");
+  return new RegExp(`^${pattern}$`).test(hostname);
+}
+
+function isRegistryDestination(baseUrl: string): boolean {
+  const endpoint = normalizedProviderEndpoint(baseUrl);
+  const hostname = hostnameOf(baseUrl);
+  if (hostname && AZURE_OPENAI_HOST_SUFFIXES.some(suffix => hostname.endsWith(suffix))) return true;
+  return PROVIDER_REGISTRY.some(entry =>
+    normalizedProviderEndpoint(entry.baseUrl) === endpoint
+    || (hostname !== undefined && templatedHostMatches(entry.baseUrl, hostname))
+    || (entry.destinationAliases ?? []).some(alias => normalizedProviderEndpoint(alias.baseUrl) === endpoint));
+}
+
+function isCustomResponsesProvider(provider: OcxProviderConfig): boolean {
+  if (provider.adapter !== "openai-responses") return false;
+  if (provider.authMode !== undefined && provider.authMode !== "key") return false;
+  if (typeof provider.baseUrl !== "string" || !provider.baseUrl) return false;
+  return !isOpenAiOperatedResponsesDestination(provider) && !isRegistryDestination(provider.baseUrl);
+}
+
+export function plaintextReasoningDroppedNotice(host: string): string {
+  return `[opencodex] Replayed plaintext reasoning was dropped for the custom Responses provider at ${host}. `
+    + "If that endpoint accepts reasoning_text replay, set \"preserveResponsesReasoningContent\": true on the provider; "
+    + "\"preserveReasoningContentModels\" applies only to the Chat wire.";
+}
+
+export function notePlaintextReasoningDropped(
+  provider: OcxProviderConfig,
+  warn: (message: string) => void = message => console.warn(message),
+): void {
+  if (!isCustomResponsesProvider(provider)) return;
+  const host = destinationHost(provider.baseUrl);
+  if (!host || noticedDestinations.has(host) || noticedDestinations.size >= MAX_NOTICED_DESTINATIONS) return;
+  noticedDestinations.add(host);
+  warn(plaintextReasoningDroppedNotice(host));
+}
+
+export function resetPlaintextReasoningNoticesForTests(): void {
+  noticedDestinations.clear();
+}

package/src/adapters/openai-responses/reasoning.ts

@@ -78,6 +78,11 @@ export function sanitizeReasoningInputContent(
      * placeholder, rather than emitted in the shape the upstream 400s on.
      */
     requirePlaintextReasoning?: boolean;
+    /**
+     * Called once per sanitized body when a reasoning item that carried nonempty plaintext
+     * `reasoning_text` was blanked. Observability only; it never changes the body (#6675).
+     */
+    onPlaintextReasoningBlanked?: () => void;
   },
 ): unknown {
   if (!body || typeof body !== "object" || Array.isArray(body)) return body;
@@ -85,6 +90,7 @@ export function sanitizeReasoningInputContent(
   if (!Array.isArray(raw.input)) return body;
 
   let changed = false;
+  let blankedPlaintext = false;
   const input = raw.input.map(item => {
     if (!item || typeof item !== "object" || Array.isArray(item)) return item;
     const rec = item as Record<string, unknown>;
@@ -148,11 +154,15 @@ export function sanitizeReasoningInputContent(
     // guide merges reasoning items into the adjacent assistant message), so providers flagged
     // `preserveResponsesReasoningContent` keep it — deleting valid replay content there breaks
     // continuations after tool calls (issue #875 family).
-    if (blankContent) next.content = [];
+    if (blankContent) {
+      if (hasPlaintextReasoningContent(rec.content)) blankedPlaintext = true;
+      next.content = [];
+    }
     if (missingPlaintextReasoning) next.content = plaintextReasoningBackfill(next);
     return next;
   });
 
+  if (blankedPlaintext) opts?.onPlaintextReasoningBlanked?.();
   return changed ? { ...raw, input } : body;
 }
 

package/src/adapters/openai-responses/tool-output-recovery.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { EMPTY_TOOL_OUTPUT_ANNOTATION, isWhitespaceOnlyTextPartArray } from "../empty-tool-output-annotation";
 import { isPlainObject } from "./internal";
 import { peekBridgeSearchReplay } from "../../responses/bridge-search-replay-cache";
+import { externalTaskInputResponsesContent } from "../../responses/task-input";
 
 const MAX_RESPONSES_CALL_ID_LENGTH = 64;
 
@@ -169,6 +170,16 @@ export function repairUnidentifiedToolOutputItems(body: unknown): unknown {
       || (typeof item.call_id === "string" && item.call_id.length > 0)) {
       return item;
     }
+    // #6764: an external task envelope is user input, not an orphaned result. Recognize it
+    // before the generic repair so the summarizer and the destination see a plain user turn.
+    // Any nonempty string call_id stays a tool result, as on the parsed path: the request schema
+    // accepts a whitespace call_id as a function_call_output and strips the envelope fields
+    // (src/responses/schema.ts), so both paths must agree that it is not task input.
+    const taskInput = externalTaskInputResponsesContent(item);
+    if (taskInput) {
+      changed = true;
+      return { type: "message", role: "user", content: taskInput };
+    }
     if (!isRepairableToolOutput(item.output)) return item;
     changed = true;
     return {
@@ -380,6 +391,15 @@ export function repairOrphanedInputItems(
     const isCustomOutput = item.type === "custom_tool_call_output";
     if (isFnOutput || isCustomOutput) {
       flushPendingSyntheticOutputs();
+      // Same rule as repairUnidentifiedToolOutputItems: a nonempty string call_id is a tool result
+      // on the parsed path (the schema strips the envelope fields), so it is never task input here.
+      const hasStringCallId = typeof item.call_id === "string" && item.call_id.length > 0;
+      const taskInput = isFnOutput && !hasStringCallId ? externalTaskInputResponsesContent(item) : undefined;
+      if (taskInput) {
+        changed = true;
+        repaired.push({ type: "message", role: "user", content: taskInput });
+        continue;
+      }
       const callId = typeof item.call_id === "string" ? item.call_id : "";
       const paired = isFnOutput ? functionCallIds.has(callId) : customCallIds.has(callId);
       const usableOutput = isRepairableToolOutput(item.output);

package/src/bridge/errors.ts

@@ -12,6 +12,7 @@ import {
   cyberPolicyErrorType,
   CYBER_POLICY_ERROR_CODE,
   isCyberPolicyCode,
+  SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE,
   type OcxErrorPayload,
 } from "../lib/errors";
 
@@ -22,6 +23,10 @@ export function formatErrorResponse(
   options?: { code?: string | null; retryAfter?: string | null },
 ): Response {
   const error = classifyError(status, type, message);
+  if (options?.code === SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE) {
+    error.type = "server_error";
+    error.code = SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE;
+  }
   if (isCyberPolicyCode(options?.code)) {
     error.code = CYBER_POLICY_ERROR_CODE;
     error.type = cyberPolicyErrorType(type);
@@ -36,7 +41,8 @@ export function formatErrorResponse(
   // that would hand the client a 5xx it is configured to retry four times.
   const finalStatus = error.code === CYBER_POLICY_ERROR_CODE
     ? 400
-    : isReplayRefusalCode(error.code) ? REPLAY_REFUSED_STATUS : status;
+    : error.code === SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE ? 503
+      : isReplayRefusalCode(error.code) ? REPLAY_REFUSED_STATUS : status;
   const headers = new Headers({ "Content-Type": "application/json" });
   const retryAfter = options?.retryAfter?.trim();
   if (error.code !== CYBER_POLICY_ERROR_CODE

package/src/claude/agents-inject.ts

@@ -15,7 +15,8 @@ import { lstatSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileS
 import { join } from "node:path";
 import type { OcxConfig } from "../types";
 import { renameAtomicFile } from "../lib/windows-atomic-replace";
-import { entryParts, SAFE_AGENT_MODEL_ID, withSubagentContextMarker } from "./subagent-model";
+import { assertNotRealClaudeConfigUnderTest } from "../lib/test-home-guard";
+import { accountsAt200k, entryParts, SAFE_AGENT_MODEL_ID, withSubagentContextMarker } from "./subagent-model";
 import { stripOneMillionMarker } from "./context-windows";
 import { claudeConfigDir } from "./gateway-cache";
 import { DEFAULT_SUBAGENT_MODELS } from "../config";
@@ -97,7 +98,7 @@ export function buildClaudeAgentDefs(
     // Generated defs mark [1m] on the authoritative window only — never the
     // main-session auto-context predicate (a 372K route marked [1m] would be
     // accounted at 1M with no compaction safety net in the subagent).
-    const model = withSubagentContextMarker(alias, windows);
+    const model = withSubagentContextMarker(alias, windows, accountsAt200k(config));
     const bare = alias.toLowerCase();
     if (coveredModels.has(bare)) return;
     coveredModels.add(bare);
@@ -130,7 +131,7 @@ export function buildClaudeAgentDefs(
   // the next launch sync — documented limit. No resolvable default -> no self def.
   const selfModel = pickerDefaultModel(configDir) ?? (config.claudeCode?.model?.trim() || null);
   if (selfModel) {
-    const marked = withSubagentContextMarker(selfModel, windows);
+    const marked = withSubagentContextMarker(selfModel, windows, accountsAt200k(config));
     defs.push({
       file: `${OWNED_PREFIX}self.md`,
       name: `${OWNED_PREFIX}self`,
@@ -203,6 +204,16 @@ function isOwnedFile(path: string): boolean {
  * atomic (tmp + rename). Best-effort — returns null on any failure.
  */
 export function syncClaudeAgentDefs(defs: readonly ClaudeAgentDef[], configDir = claudeConfigDir()): string[] | null {
+  // Outside the best-effort catch: under an armed test process a write or prune of the
+  // real Claude agents directory must throw, never degrade to "returned null" (#6775).
+  // Every path written is judged by where it resolves, including a pre-placed link named like
+  // a definition or its temporary file.
+  const agentsDir = join(configDir, "agents");
+  assertNotRealClaudeConfigUnderTest(
+    configDir,
+    agentsDir,
+    ...defs.flatMap(def => [join(agentsDir, def.file), `${join(agentsDir, def.file)}.tmp-${process.pid}`]),
+  );
   try {
     const dir = join(configDir, "agents");
     if (defs.length === 0) {

package/src/claude/context-windows.ts

@@ -15,33 +15,19 @@ import { desktop3pAlias } from "./desktop-3p";
 import { nativeOpenAiContextWindow, type CatalogModel, type NativeContextLimitsInput } from "../codex/catalog";
 import { ANTHROPIC_MODEL_CONTEXT_WINDOWS } from "../providers/registry/model-seeds";
 import type { OcxClaudeCodeConfig } from "../types";
+import { AUTO_COMPACT_WINDOW_DEFAULT, AUTO_CONTEXT_FLOOR, ONE_MILLION } from "./long-context";
 
-const ONE_MILLION = 1_000_000;
+export { AUTO_COMPACT_WINDOW_DEFAULT, AUTO_CONTEXT_FLOOR } from "./long-context";
 
 /**
- * The native id each Claude Code tier alias resolves to (2.1.282: `--model opus` sends
- * `claude-opus-5-5`, `sonnet` sends `claude-sonnet-5`, `fable` sends `claude-fable-5-1`).
+ * The native id each Claude Code tier alias resolves to (2.1.296: `--model opus` sends
+ * `claude-opus-5-5`, `sonnet` sends `claude-sonnet-5-5`, `fable` sends `claude-fable-5-1`).
  * Behind a gateway Claude Code accounts an unmarked id at 200k, so an unset tier slot is filled
  * with this id when the map marks it (#5755). A marked alias cannot stand in: Claude Code sends
  * `sonnet[1m]` upstream unresolved. Haiku has no entry; its 200k window never marks.
  */
-const CLAUDE_CODE_NATIVE_TIERS = { opus: "claude-opus-5-5", sonnet: "claude-sonnet-5", fable: "claude-fable-5-1" } as const;
+const CLAUDE_CODE_NATIVE_TIERS = { opus: "claude-opus-5-5", sonnet: "claude-sonnet-5-5", fable: "claude-fable-5-1" } as const;
 
-/**
- * Auto-context defaults (devlog 260712 020, user-approved).
- *
- * The compact window is the token count at which Claude Code starts compacting, and it is
- * also the floor `shouldMarkOneMillion` uses — a model may only carry the marker if it can
- * host this window. 350,000 was chosen when the widest native row advertised 372,000.
- *
- * It now matches the auto-compaction limit the Codex catalog ships for the same models
- * (`nativeAutoCompactLimit`: 829,800 against the 922,000 native window). Leaving the two
- * apart meant one model compacting at 350k under Claude Code and at 829,800 under Codex.
- * The value stays clear of the measured 922,000 ceiling by ~92k, so compaction still has
- * room to run before the upstream refuses.
- */
-export const AUTO_COMPACT_WINDOW_DEFAULT = 829_800;
-export const AUTO_CONTEXT_FLOOR = 200_000;
 /** Binary-verified accepted range for CLAUDE_CODE_AUTO_COMPACT_WINDOW (2.1.207: pSo=1e5, yDs=1e6). */
 export const AUTO_COMPACT_WINDOW_MIN = 100_000;
 export const AUTO_COMPACT_WINDOW_MAX = ONE_MILLION;
@@ -59,14 +45,27 @@ export interface AutoContextMode {
   enabled: boolean;
   /** Effective CLAUDE_CODE_AUTO_COMPACT_WINDOW value (tokens). */
   compactWindow: number;
+  /** claudeCode.contextAccounting "200k": nothing is marked [1m] automatically, whatever its window. */
+  accounting200k?: true;
 }
 
 export const AUTO_CONTEXT_OFF: AutoContextMode = { enabled: false, compactWindow: AUTO_COMPACT_WINDOW_DEFAULT };
 
+/**
+ * Marking mode for surfaces whose runner may not inherit the compaction env (Desktop pickers,
+ * discovery, generated subagents). shouldMarkOneMillion under it equals isLongContextWindow
+ * (long-context.ts); kept as a mode so the existing marker helpers serve every surface.
+ */
+export const UNPAIRED_AUTO_CONTEXT: AutoContextMode = { enabled: true, compactWindow: AUTO_COMPACT_WINDOW_DEFAULT };
+
+/** The "200k" opt-in: no widening, no compact-window injection, no automatic marker. */
+export const ACCOUNTING_200K: AutoContextMode = { enabled: false, compactWindow: AUTO_COMPACT_WINDOW_DEFAULT, accounting200k: true };
+
 interface AutoContextConfigSlice {
   autoContext?: boolean;
   autoCompactWindow?: number;
   maxContextTokens?: number;
+  contextAccounting?: string;
 }
 
 function inAutoCompactRange(value: number): boolean {
@@ -90,6 +89,8 @@ function inAutoCompactRange(value: number): boolean {
  * to AUTO_COMPACT_WINDOW_DEFAULT (the management API rejects them; this guards hand-edits).
  */
 export function resolveAutoContext(claudeCode: AutoContextConfigSlice | undefined, envOverride?: string): AutoContextMode {
+  // The 200k opt-in wins over every other lever, a user-exported compact window included.
+  if (claudeCode?.contextAccounting === "200k") return ACCOUNTING_200K;
   if (claudeCode?.autoContext === false) return AUTO_CONTEXT_OFF;
   const maxCtx = claudeCode?.maxContextTokens;
   if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) return AUTO_CONTEXT_OFF;
@@ -132,6 +133,7 @@ export function claudeToolSearchEnv(value: boolean | string | undefined): string
  */
 export function shouldMarkOneMillion(window: number | undefined, auto: AutoContextMode): boolean {
   if (typeof window !== "number" || window <= 0) return false;
+  if (auto.accounting200k) return false;
   if (window >= ONE_MILLION) return true;
   return auto.enabled && window > AUTO_CONTEXT_FLOOR && window >= auto.compactWindow;
 }
@@ -248,7 +250,7 @@ export interface ClaudeTierModels {
  * value injected into BOTH haiku variables.
  */
 export function effectiveModelEnv(
-  claudeCode: { model?: string; smallFastModel?: string; tierModels?: ClaudeTierModels; autoContext?: boolean; autoCompactWindow?: number; maxContextTokens?: number } | undefined,
+  claudeCode: { model?: string; smallFastModel?: string; tierModels?: ClaudeTierModels; autoContext?: boolean; autoCompactWindow?: number; maxContextTokens?: number; contextAccounting?: string } | undefined,
   windows: Record<string, number>,
   autoOverride?: AutoContextMode,
 ): Record<string, string> {

package/src/claude/desktop-3p.ts

@@ -10,9 +10,10 @@ import {
 } from "./desktop-3p-library";
 export { resolveDesktop3pConfigLibraryPath, type Desktop3pConfigLibraryOptions } from "./desktop-3p-library";
 import { createHash, randomUUID } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, lstatSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile, readConfigDiagnostics, withConfigMutationLockSync } from "../config";
+import { atomicWriteFileNoFollow } from "../config/atomic-write";
 import { claudeDesktopIntegrationEnabled } from "../codex/desired-state";
 import type { OcxClaudeDesktopProfile } from "../types";
 import {
@@ -24,6 +25,7 @@ import {
 import { nativeOpenAiContextWindow, type NativeContextLimitsInput } from "../codex/catalog";
 import { localAdmissionToken, localInferenceDestination } from "../lib/local-destinations";
 import { assertDesktop3pModelsValid } from "./desktop-3p-guard";
+import { claudeSurfaceSupportsOneMillion, ONE_MILLION } from "./long-context";
 
 export interface Desktop3pModelEntry {
   name: string;
@@ -55,12 +57,12 @@ export interface Desktop3pRoutedModel {
 }
 
 /**
- * 1M-context eligibility, shared with the Desktop DTO so the dashboard's 1M chip can
- * never disagree with what the writer emits. The DTO imports this from here — keeping
- * the constant in this module avoids a cycle, since shared.ts already reads
- * claude/desktop-profile.
+ * The genuine-1M threshold real Anthropic rows still need. Every other row follows the
+ * long-window rule; the writer, the profile renderer and the dashboard DTO all decide through
+ * `claudeSurfaceSupportsOneMillion` (long-context.ts), so the 1M chip cannot disagree with the
+ * written config.
  */
-export const DESKTOP_SUPPORTS_1M_THRESHOLD = 1_000_000;
+export const DESKTOP_SUPPORTS_1M_THRESHOLD = ONE_MILLION;
 
 /** CLI arg parsing for `ocx claude desktop` mode flags (mutually exclusive). */
 export function parseDesktop3pModeArgs(flags: string[]): { mode: Desktop3pConfigMode } | { error: string } {
@@ -251,7 +253,7 @@ function collectDesktop3pModels(
   for (const { provider, id, contextWindow } of candidates) {
     const route = `${provider}/${id}`;
     const alias = desktop3pAlias(provider, id);
-    const supports1m = typeof contextWindow === "number" && contextWindow >= DESKTOP_SUPPORTS_1M_THRESHOLD
+    const supports1m = claudeSurfaceSupportsOneMillion(provider, id, contextWindow)
       ? { supports1m: true as const }
       : {};
     if (alias === id) {
@@ -317,16 +319,30 @@ export function buildDesktop3pRegistry(
 }
 
 /** Generate Claude Desktop 3P model entries from the proxy's available models. */
+export interface Desktop3pModelOptions {
+  /**
+   * false under claudeCode.contextAccounting "200k": a long-window model stays selectable at 1M
+   * (`supports1m`) but no longer defaults to it (`prefer1m` dropped).
+   */
+  preferOneMillion?: boolean;
+}
+
 export function generateDesktop3pModels(
   nativeSlugs: string[],
   routedModels: Array<Desktop3pRoutedModel>,
   profile?: OcxClaudeDesktopProfile,
   nativeContextCap?: NativeContextLimitsInput,
+  options: Desktop3pModelOptions = {},
 ): Desktop3pModelEntry[] {
   const { models, registry, realAnthropicIds } = collectDesktop3pModels(nativeSlugs, routedModels, profile, nativeContextCap);
   desktop3pRegistry = registry;
   desktop3pRealAnthropicIds = realAnthropicIds;
-  return models;
+  return options.preferOneMillion === false ? models.map(({ prefer1m: _prefer1m, ...model }) => model) : models;
+}
+
+/** The Desktop model options a config asks for (one place, so writer and export agree). */
+export function desktop3pModelOptions(claudeCode: { contextAccounting?: string } | undefined): Desktop3pModelOptions {
+  return { preferOneMillion: claudeCode?.contextAccounting !== "200k" };
 }
 
 /** Resolve an alias using the most recently generated Desktop model registry. */
@@ -382,6 +398,7 @@ export function generateDesktop3pConfig(
   mode: Desktop3pConfigMode = "static",
   profile?: OcxClaudeDesktopProfile,
   nativeContextCap?: NativeContextLimitsInput,
+  options: Desktop3pModelOptions = {},
 ): object {
   const base = {
     inferenceProvider: "gateway",
@@ -398,7 +415,7 @@ export function generateDesktop3pConfig(
     ...base,
     modelDiscoveryEnabled: mode === "hybrid",
     inferenceModels: (() => {
-      const models = generateDesktop3pModels(nativeSlugs, routedModels, profile, nativeContextCap);
+      const models = generateDesktop3pModels(nativeSlugs, routedModels, profile, nativeContextCap, options);
       // Fail loud at the write boundary rather than ship a config Desktop rejects:
       // the output counterpart of the request-path guards.
       assertDesktop3pModelsValid(models);
@@ -662,6 +679,7 @@ export function writeDesktop3pConfig(
   profile?: OcxClaudeDesktopProfile,
   nativeContextCap?: NativeContextLimitsInput,
   lifecycleLockDeps?: ClientLifecycleLockDeps,
+  refreshOnly?: { appliedFingerprint: string; admit: () => boolean },
 ): { written: boolean; path: string; reason?: string; fingerprint?: string } {
   try {
     return withClientLifecycleSync(() => withConfigMutationLockSync(() => {
@@ -674,9 +692,29 @@ export function writeDesktop3pConfig(
       if (!claudeDesktopIntegrationEnabled(latest.config)) {
         return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desired_state_changed" };
       }
+      if (refreshOnly && !desktopRefreshPathsSafe(resolveDesktop3pConfigLibraryPath())) {
+        return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desktop_refresh_only_skipped" };
+      }
       if (connection.kind === "connected" || inspectRemoteDesktopCleanup().kind !== "absent") {
         return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desktop_remote_store_active" };
       }
+      let requiredId: string | undefined;
+      if (refreshOnly) {
+        const refused = { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desktop_refresh_only_skipped" };
+        // Ownership and bytes must still match under L→C; discovery outside these locks is not authority.
+        if (!refreshOnly.admit() || latest.config.claudeCode?.desktopProfile?.appliedFingerprint !== refreshOnly.appliedFingerprint) return refused;
+        const inspected = inspectDesktop3pConfigLibrary({ appliedFingerprint: refreshOnly.appliedFingerprint });
+        if (inspected.kind !== "gateway_ours" || !inspected.appliedId || !inspected.selectedProfilePath) return refused;
+        if (!desktopRefreshPathsSafe(inspected.libraryPath, inspected.selectedProfilePath)) return refused;
+        const metadata = parseMetadata(join(inspected.libraryPath, "_meta.json"));
+        if (!isOwnedDesktopGatewayEntry(metadata.entries.find(entry => entry.id === inspected.appliedId))) return refused;
+        try {
+          const selected = JSON.parse(readFileSync(inspected.selectedProfilePath, "utf8")) as Record<string, unknown>;
+          mode = selected.modelDiscoveryEnabled !== true ? "static"
+            : Array.isArray(selected.inferenceModels) ? "hybrid" : "discovery";
+        } catch { return refused; }
+        requiredId = inspected.appliedId;
+      }
       // Claude Desktop runs on this machine, so it dials the unauthenticated loopback listener
       // when one is enabled — on such a hub that is the only credential-free local socket
       // (#4236) — and otherwise the bind address, which answers but demands data-plane
@@ -700,8 +738,9 @@ export function writeDesktop3pConfig(
         );
       }
       return writeDesktop3pConfigWithGenerator(() => (
-        generateDesktop3pConfig(destination.origin, nativeSlugs, routedModels, gatewayKey, mode, profile, nativeContextCap)
-      ));
+        generateDesktop3pConfig(destination.origin, nativeSlugs, routedModels, gatewayKey, mode, profile, nativeContextCap,
+          desktop3pModelOptions(latest.config.claudeCode))
+      ), requiredId && refreshOnly ? { requiredId, expectedFingerprint: refreshOnly.appliedFingerprint, admit: refreshOnly.admit } : undefined);
     }), lifecycleLockDeps);
   } catch { return { written: false, path: resolveDesktop3pConfigLibraryPath(), reason: "desktop_lifecycle_busy_or_unsafe" }; }
 }
@@ -734,17 +773,38 @@ export function writeRemoteDesktop3pConfig(options: {
   } catch { return { written: false, path: "", reason: "desktop_lifecycle_busy_or_unsafe" }; }
 }
 
+/** Refresh-only writes never follow links, including a dangling backup link. */
+function desktopRefreshPathsSafe(libraryPath: string, configPath?: string): boolean {
+  try {
+    if (!lstatSync(libraryPath).isDirectory() || !lstatSync(join(libraryPath, "_meta.json")).isFile()) return false;
+    if (configPath) {
+      if (!lstatSync(configPath).isFile()) return false;
+      try { if (lstatSync(`${configPath}.bak`).isSymbolicLink()) return false; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") return false; }
+    }
+    return true;
+  } catch { return false; }
+}
+
 function writeDesktop3pConfigWithGenerator(
   generate: () => object,
+  refreshOnly?: { requiredId: string; expectedFingerprint: string; admit: () => boolean },
 ): { written: boolean; path: string; reason?: string; fingerprint?: string } {
   const libraryPath = resolveDesktop3pConfigLibraryPath();
   const metadataPath = join(libraryPath, "_meta.json");
   let configPath = libraryPath;
 
   try {
-    mkdirSync(libraryPath, { recursive: true, mode: 0o700 });
+    if (refreshOnly && !desktopRefreshPathsSafe(libraryPath)) {
+      return { written: false, path: libraryPath, reason: "desktop_refresh_only_skipped" };
+    }
+    if (!refreshOnly) mkdirSync(libraryPath, { recursive: true, mode: 0o700 });
     const metadata = parseMetadata(metadataPath);
     const selected = metadata.entries.find(entry => entry?.id === metadata.appliedId && isOwnedDesktopGatewayEntry(entry));
+    // A refresh may reuse only the applied entry; fallback allocation would silently enroll again.
+    if (refreshOnly && selected?.id !== refreshOnly.requiredId) {
+      return { written: false, path: libraryPath, reason: "desktop_refresh_only_skipped" };
+    }
     const existing = selected ?? metadata.entries.find(entry => isOwnedDesktopGatewayEntry(entry) && typeof entry.id === "string");
     const id = existing?.id ?? randomUUID();
     configPath = profilePath(libraryPath, id);
@@ -757,6 +817,22 @@ function writeDesktop3pConfigWithGenerator(
     const preserved = readDesktopProfileForeignKeys(configPath);
     const configJson = JSON.stringify({ ...preserved, ...generated }, null, 2) + "\n";
     const fingerprint = createHash("sha256").update(configJson).digest("hex").slice(0, 16);
+    if (refreshOnly) {
+      atomicWriteFileNoFollow(configPath, configJson, undefined, {
+        validateBeforeRename: () => {
+          try {
+            if (!refreshOnly.admit() || !desktopRefreshPathsSafe(libraryPath, configPath)) throw new Error();
+            const freshMetadata = parseMetadata(metadataPath);
+            if (freshMetadata.appliedId !== refreshOnly.requiredId
+              || !isOwnedDesktopGatewayEntry(freshMetadata.entries.find(entry => entry.id === refreshOnly.requiredId))
+              || createHash("sha256").update(readFileSync(configPath)).digest("hex").slice(0, 16) !== refreshOnly.expectedFingerprint) {
+              throw new Error();
+            }
+          } catch { throw new Error("desktop_refresh_only_skipped"); }
+        },
+      });
+      return { written: true, path: configPath, fingerprint };
+    }
     const { backupPath } = atomicReplaceDesktopConfig(configPath, configJson);
     try {
       atomicWriteFile(metadataPath, JSON.stringify({ ...metadata, appliedId: id, entries }, null, 2) + "\n");

package/src/claude/desktop-picker.ts

@@ -2,7 +2,7 @@
  * Claude Desktop picker mode: the one server-side controller for every picker mutation.
  *
  * While a server runs, enable, disable and Desktop mode transitions run here, serialized by one
- * lock (devlog/_plan/260924_claude_desktop_picker_mode/030_wp4_picker_activation.md, D11).
+ * lock (devlog/_fin/260924_claude_desktop_picker_mode/030_wp4_picker_activation.md, D11).
  */
 import type { OcxConfig } from "../types";
 import { claudeDesktopIntegrationEnabled } from "../codex/desired-state";

package/src/claude/desktop-profile.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { routeSupportsOneMillion } from "./long-context";
 import type {
   OcxClaudeDesktopAssignment,
   OcxClaudeDesktopFamily,
@@ -359,7 +360,7 @@ export function renderDesktopProfile(
       name: isRealAnthropicRoute(route) ? assignment.alias : desktopProfileWireAlias(assignment.alias),
       family: assignment.family,
       isFamilyDefault: effectiveDefaults[assignment.family] === route,
-      supports1m: typeof model.contextWindow === "number" && model.contextWindow >= 1_000_000,
+      supports1m: routeSupportsOneMillion(route, model.contextWindow),
     };
   });
 }

package/src/claude/gateway-cache.ts

@@ -17,6 +17,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { localAdmissionToken, localInferenceDestination } from "../lib/local-destinations";
+import { assertNotRealClaudeConfigUnderTest } from "../lib/test-home-guard";
 import type { OcxConfig } from "../types";
 
 export interface GatewayModelRow {
@@ -46,11 +47,27 @@ export interface GatewayModelTarget {
 /** Claude Code config dir (CLAUDE_CONFIG_DIR override honored, like the CLI). */
 export function claudeConfigDir(): string {
   const custom = process.env.CLAUDE_CONFIG_DIR;
-  return custom && custom.length > 0 ? custom : join(homedir(), ".claude");
+  return custom && custom.length > 0 ? custom : join(currentUserHome(), ".claude");
+}
+
+/**
+ * The home Claude Code itself resolves. Claude Code runs on Node, whose `os.homedir()`
+ * consults HOME (POSIX) or USERPROFILE (Windows) at call time when it is set; Bun's
+ * `os.homedir()` keeps the value it read at startup. In production the two agree. Under
+ * the test preload, which rewrites HOME after Bun has started, only this one follows the
+ * sandbox — the cached value is the developer's real home (#6775). Exported for tests.
+ */
+export function currentUserHome(env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform): string {
+  const fromEnv = platform === "win32" ? env.USERPROFILE : env.HOME;
+  return fromEnv !== undefined && fromEnv !== "" ? fromEnv : homedir();
 }
 
 /** Write the cache file; returns its path or null (best-effort, never throws). */
 export function writeGatewayModelCache(baseUrl: string, models: readonly GatewayModelRow[], configDir = claudeConfigDir()): string | null {
+  // Outside the best-effort catch: an armed test process must not write here, and must
+  // fail loudly rather than degrade to "returned null".
+  // The file itself too: writeFileSync follows a link at gateway-models.json.
+  assertNotRealClaudeConfigUnderTest(configDir, join(configDir, "cache"), join(configDir, "cache", "gateway-models.json"));
   try {
     // Mirror the CLI's usable-id filter so our file matches what it would cache.
     const usable = models.filter(m => /(claude|anthropic)/i.test(m.id));