@bitkyc08/opencodex 2.93.0 → 2.95.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (582) hide show
  1. package/README.md +27 -8
  2. package/bin/ocx.mjs +215 -63
  3. package/gui/dist/assets/App-8yedBkhm.js +58 -0
  4. package/gui/dist/assets/App-B4j-Txmb.css +1 -0
  5. package/gui/dist/assets/Tray-erSMzxPG.js +1 -0
  6. package/gui/dist/assets/index-CHWwDo9L.css +1 -0
  7. package/gui/dist/assets/index-D7DCm5eQ.js +94 -0
  8. package/gui/dist/assets/quota-summary-BK4VuQNc.js +1 -0
  9. package/gui/dist/index.html +2 -2
  10. package/gui/dist/provider-icons/t3code.svg +4 -0
  11. package/package.json +7 -4
  12. package/src/adapters/anthropic/account-metadata.ts +34 -3
  13. package/src/adapters/anthropic/beta-allowlist.ts +5 -5
  14. package/src/adapters/anthropic/passthrough.ts +5 -2
  15. package/src/adapters/anthropic.ts +27 -7
  16. package/src/adapters/antigravity-refusal.ts +29 -0
  17. package/src/adapters/base.ts +11 -1
  18. package/src/adapters/client-fingerprint.ts +43 -9
  19. package/src/adapters/coding-agent/protocol.ts +19 -9
  20. package/src/adapters/command-code-project-context.ts +3 -3
  21. package/src/adapters/command-code.ts +4 -5
  22. package/src/adapters/cursor/catalog.ts +5 -3
  23. package/src/adapters/cursor/claude-id.ts +30 -19
  24. package/src/adapters/cursor/cursor-errors.ts +5 -2
  25. package/src/adapters/cursor/h2-pool.ts +9 -7
  26. package/src/adapters/cursor/http1-bidi.ts +1 -0
  27. package/src/adapters/cursor/live-models.ts +4 -2
  28. package/src/adapters/cursor.ts +4 -1
  29. package/src/adapters/devin/cloud-direct/chat.ts +18 -2
  30. package/src/adapters/google-antigravity-replay.ts +13 -2
  31. package/src/adapters/google-antigravity-wire.ts +8 -3
  32. package/src/adapters/google-errors.ts +33 -0
  33. package/src/adapters/google-http.ts +41 -16
  34. package/src/adapters/google-wire-compiler.ts +4 -0
  35. package/src/adapters/google.ts +21 -10
  36. package/src/adapters/kiro/adapter.ts +7 -1
  37. package/src/adapters/kiro/stream.ts +19 -13
  38. package/src/adapters/kiro-events.ts +1 -0
  39. package/src/adapters/openai-chat/completed-tool-blocks.ts +65 -0
  40. package/src/adapters/openai-chat/messages.ts +42 -17
  41. package/src/adapters/openai-chat/passthrough.ts +4 -2
  42. package/src/adapters/openai-chat/required-tool-result.ts +3 -3
  43. package/src/adapters/openai-chat/serialized-tool-call-content.ts +5 -0
  44. package/src/adapters/openai-chat/single-system.ts +24 -0
  45. package/src/adapters/openai-chat/wire.ts +9 -0
  46. package/src/adapters/openai-chat.ts +18 -17
  47. package/src/adapters/openai-responses/image-gen.ts +15 -1
  48. package/src/adapters/openai-responses/muse-tool-catalog.ts +87 -0
  49. package/src/adapters/openai-responses/passthrough.ts +53 -41
  50. package/src/adapters/openai-responses/prompt-cache.ts +3 -1
  51. package/src/adapters/openai-responses/request-strips.ts +23 -4
  52. package/src/adapters/openai-responses/tool-output-recovery.ts +21 -8
  53. package/src/adapters/openai-responses/tool-schema.ts +20 -8
  54. package/src/adapters/openai-responses/transport.ts +20 -2
  55. package/src/adapters/openai-responses/usage.ts +34 -0
  56. package/src/adapters/opencode-go-additional-tools.ts +39 -6
  57. package/src/adapters/qoder/adapter.ts +9 -15
  58. package/src/adapters/qoder/image-input.ts +52 -0
  59. package/src/adapters/routed-agent-messages.ts +3 -0
  60. package/src/adapters/unique-tool-call-ids.ts +2 -2
  61. package/src/adapters/xai-web-search.ts +6 -3
  62. package/src/adapters/zed-additional-tools.ts +51 -0
  63. package/src/adapters/zed-diagnostic-usage.ts +22 -0
  64. package/src/adapters/zed-json-tokens.ts +166 -0
  65. package/src/adapters/zed-openai-stream.ts +723 -0
  66. package/src/adapters/zed-tool-arguments.ts +79 -0
  67. package/src/adapters/zed.ts +48 -3
  68. package/src/advisor/consult.ts +39 -5
  69. package/src/advisor/runtime.ts +12 -3
  70. package/src/bridge/errors.ts +22 -1
  71. package/src/bridge/max-output-completion.ts +41 -0
  72. package/src/bridge/response-json.ts +13 -5
  73. package/src/bridge/sse.ts +34 -14
  74. package/src/chat/inbound.ts +13 -2
  75. package/src/chatgpt/app-server-shim/bundle-trust-async.ts +111 -0
  76. package/src/chatgpt/app-server-shim/bundle-trust-policy.ts +88 -0
  77. package/src/chatgpt/app-server-shim/bundle-trust.ts +15 -72
  78. package/src/chatgpt/app-server-shim/launcher.ts +40 -6
  79. package/src/claude/compatibility.ts +5 -1
  80. package/src/claude/desktop-3p.ts +27 -6
  81. package/src/claude/desktop-first-party.ts +16 -5
  82. package/src/claude/desktop-gateway-state.ts +4 -0
  83. package/src/claude/desktop-model-visibility.ts +141 -0
  84. package/src/claude/desktop-remote-store-io.ts +8 -8
  85. package/src/claude/inbound-content-options.ts +11 -1
  86. package/src/claude/inbound-tool-loading.ts +93 -0
  87. package/src/claude/intercept/picker-listener.ts +33 -1
  88. package/src/claude/intercept/proxy-auth.ts +16 -16
  89. package/src/claude/model-info.ts +29 -4
  90. package/src/claude/outbound.ts +33 -13
  91. package/src/cli/account-main.ts +44 -5
  92. package/src/cli/capabilities-base.ts +22 -5
  93. package/src/cli/capabilities-integrations.ts +4 -4
  94. package/src/cli/capabilities-provider-models.ts +7 -0
  95. package/src/cli/chatgpt-command.ts +1 -1
  96. package/src/cli/claude-desktop.ts +139 -98
  97. package/src/cli/codex-cli-update.ts +102 -48
  98. package/src/cli/codex-launch-auth.ts +93 -0
  99. package/src/cli/codex-launch-command.ts +32 -0
  100. package/src/cli/codex-launch-diagnostics.ts +37 -0
  101. package/src/cli/codex-launch-ownership.ts +307 -0
  102. package/src/cli/codex-launch-policy.ts +84 -0
  103. package/src/cli/codex-launcher.ts +322 -0
  104. package/src/cli/codex-shim-autorestore.ts +21 -1
  105. package/src/cli/config-command.ts +9 -4
  106. package/src/cli/config-mutation.ts +13 -0
  107. package/src/cli/dispatch.ts +19 -13
  108. package/src/cli/doctor.ts +5 -5
  109. package/src/cli/effort.ts +19 -14
  110. package/src/cli/ensure-desired-integrations.ts +21 -14
  111. package/src/cli/ensure-desktop-cold-start.ts +41 -10
  112. package/src/cli/export-command.ts +8 -4
  113. package/src/cli/help.ts +3 -1
  114. package/src/cli/index.ts +62 -73
  115. package/src/cli/init.ts +2 -2
  116. package/src/cli/integration-input.ts +12 -0
  117. package/src/cli/integration-plan-dto.ts +2 -0
  118. package/src/cli/integration-preview.ts +6 -3
  119. package/src/cli/integrations.ts +2 -1
  120. package/src/cli/internal-command.ts +29 -2
  121. package/src/cli/link-cleanup.ts +8 -23
  122. package/src/cli/link-enrollment.ts +1 -4
  123. package/src/cli/link.ts +1 -1
  124. package/src/cli/loopback-family.ts +2 -31
  125. package/src/cli/models.ts +62 -49
  126. package/src/cli/provider-cc-switch-import.ts +185 -0
  127. package/src/cli/provider.ts +151 -139
  128. package/src/cli/registry.ts +35 -3
  129. package/src/cli/restart-scope.ts +2 -2
  130. package/src/cli/root.ts +8 -6
  131. package/src/cli/start-owner-fence.ts +22 -3
  132. package/src/cli/status-link.ts +28 -0
  133. package/src/cli/status.ts +15 -0
  134. package/src/cli/stop-approval.ts +15 -1
  135. package/src/cli/stop-restore-guard.ts +48 -0
  136. package/src/cli/stop-restore.ts +117 -36
  137. package/src/cli/system-command.ts +2 -0
  138. package/src/cli/v2.ts +86 -23
  139. package/src/client/lifecycle-lock.ts +1 -1
  140. package/src/client/link-connection.ts +19 -0
  141. package/src/client/link-relay-transport.ts +25 -3
  142. package/src/client/link-tunnel.ts +10 -0
  143. package/src/client/machine-api.ts +2 -2
  144. package/src/client/machine-listener.ts +7 -1
  145. package/src/client/restore-ownership.ts +45 -0
  146. package/src/client/runtime.ts +13 -1
  147. package/src/client/state.ts +1 -1
  148. package/src/clients/client-ids.ts +7 -0
  149. package/src/clients/client-path.ts +13 -5
  150. package/src/clients/config-export/agent-clients.ts +3 -6
  151. package/src/clients/config-export/alias-selectors.ts +85 -0
  152. package/src/clients/config-export/contracts.ts +6 -25
  153. package/src/clients/config-export/dsh.ts +8 -1
  154. package/src/clients/config-export/model-metadata.ts +19 -0
  155. package/src/clients/config-export/model-names.ts +31 -0
  156. package/src/clients/config-export/qoder.ts +3 -11
  157. package/src/clients/config-export/t3code.ts +141 -0
  158. package/src/clients/config-export.ts +65 -18
  159. package/src/clients/gentle-shell-path.ts +3 -3
  160. package/src/codex/account-cooldown-response.ts +18 -0
  161. package/src/codex/account-lifecycle.ts +27 -13
  162. package/src/codex/account-store.ts +32 -6
  163. package/src/codex/app-server-processes.ts +84 -1
  164. package/src/codex/app-server-restart-service.ts +2 -2
  165. package/src/codex/auth-api/login-flow.ts +2 -2
  166. package/src/codex/auth-api/main-account-probe.ts +50 -11
  167. package/src/codex/auth-api/pool-mode-gate.ts +16 -8
  168. package/src/codex/auth-api/pool-quota-probe.ts +2 -2
  169. package/src/codex/auth-context.ts +49 -8
  170. package/src/codex/catalog/antigravity-discovery.ts +59 -0
  171. package/src/codex/catalog/build-entries.ts +12 -13
  172. package/src/codex/catalog/bundled.ts +67 -10
  173. package/src/codex/catalog/derive-entry.ts +2 -0
  174. package/src/codex/catalog/gather-capture.ts +3 -0
  175. package/src/codex/catalog/metadata.ts +10 -10
  176. package/src/codex/catalog/model-hints.ts +36 -4
  177. package/src/codex/catalog/native-omission.ts +28 -0
  178. package/src/codex/catalog/native-priority.ts +63 -0
  179. package/src/codex/catalog/native-template.ts +58 -0
  180. package/src/codex/catalog/parsing.ts +3 -29
  181. package/src/codex/catalog/provider-models.ts +22 -5
  182. package/src/codex/catalog/retained-sync.ts +16 -6
  183. package/src/codex/catalog/write-audit.ts +18 -18
  184. package/src/codex/chatgpt-refresh-failure.ts +2 -2
  185. package/src/codex/cli-install-provenance.ts +103 -74
  186. package/src/codex/cli-installation-identity.ts +1 -1
  187. package/src/codex/cli-installation-limits.ts +7 -0
  188. package/src/codex/cli-update-apply.ts +391 -0
  189. package/src/codex/cli-update-artifacts.ts +259 -0
  190. package/src/codex/cli-update-files.ts +100 -0
  191. package/src/codex/cli-update-inspection-context.ts +49 -0
  192. package/src/codex/cli-update-job-execution.ts +77 -0
  193. package/src/codex/cli-update-job-store-windows.ts +1082 -0
  194. package/src/codex/cli-update-job-worker.ts +385 -0
  195. package/src/codex/cli-update-job.ts +369 -0
  196. package/src/codex/cli-update-lease.ts +71 -0
  197. package/src/codex/cli-update-paths.ts +76 -0
  198. package/src/codex/cli-update-plan.ts +180 -47
  199. package/src/codex/cli-update-recovery.ts +282 -0
  200. package/src/codex/cli-update-selection-gate.ts +305 -0
  201. package/src/codex/cli-update-windows-apply.ts +308 -0
  202. package/src/codex/cli-update-windows-layout.ts +110 -0
  203. package/src/codex/cli-update-windows-observation.ts +91 -0
  204. package/src/codex/cli-update-windows-paths.ts +26 -0
  205. package/src/codex/cli-update-worker-recovery.ts +32 -0
  206. package/src/codex/cli-update-worker.ts +185 -0
  207. package/src/codex/cli-windows-plan-provenance.ts +268 -0
  208. package/src/codex/codex-home-owner.ts +9 -8
  209. package/src/codex/convergence.ts +13 -3
  210. package/src/codex/coordinator-doctor.ts +14 -8
  211. package/src/codex/desktop-app/handoff.ts +1 -1
  212. package/src/codex/desktop-app-restart.ts +32 -3
  213. package/src/codex/exec-boundary.ts +229 -0
  214. package/src/codex/forward-transport-headers.ts +80 -0
  215. package/src/codex/history-job.ts +7 -0
  216. package/src/codex/history-provider.ts +16 -12
  217. package/src/codex/history-worker.ts +20 -1
  218. package/src/codex/inject/bounded-config-reader.ts +14 -13
  219. package/src/codex/inject/restore.ts +57 -25
  220. package/src/codex/internal/history-writer.ts +2 -1
  221. package/src/codex/mac-app-bundle.ts +52 -0
  222. package/src/codex/main-account.ts +167 -29
  223. package/src/codex/native-main-auth-temp.ts +3 -2
  224. package/src/codex/native-main-lock-file.ts +13 -12
  225. package/src/codex/native-main-refresh-mode.ts +18 -3
  226. package/src/codex/native-profile-manager.ts +8 -6
  227. package/src/codex/native-profile-store.ts +9 -0
  228. package/src/codex/native-residue.ts +18 -14
  229. package/src/codex/ocx-compaction-history.ts +3 -2
  230. package/src/codex/orca-auth-source.ts +8 -7
  231. package/src/codex/prompt-text-probe.ts +211 -69
  232. package/src/codex/quota-types.ts +5 -0
  233. package/src/codex/quota.ts +58 -7
  234. package/src/codex/role-auto-assign.ts +50 -26
  235. package/src/codex/role-capability.ts +160 -0
  236. package/src/codex/role-model-history.ts +253 -0
  237. package/src/codex/role-sizing.ts +24 -6
  238. package/src/codex/routing/cooldown-math.ts +3 -2
  239. package/src/codex/runtime.ts +161 -72
  240. package/src/codex/shim-fingerprint.ts +11 -9
  241. package/src/codex/shim-inspect.ts +3 -2
  242. package/src/codex/shim-overlay.ts +22 -3
  243. package/src/codex/shim-restore-lock.ts +11 -14
  244. package/src/codex/shim-state-file.ts +22 -14
  245. package/src/codex/shim-templates.ts +5 -2
  246. package/src/codex/shim-wrapper-write.ts +137 -0
  247. package/src/codex/shim.ts +48 -126
  248. package/src/codex/transition-state.ts +5 -4
  249. package/src/codex/windows-cli-child-native.ts +119 -0
  250. package/src/codex/windows-cli-child-pipe.ts +87 -0
  251. package/src/codex/windows-cli-child.ts +260 -0
  252. package/src/codex/windows-cli-recovery-guardian.ts +89 -0
  253. package/src/codex/windows-cli-recovery.ts +39 -0
  254. package/src/codex/windows-installation-files.ts +52 -6
  255. package/src/codex/windows-npm-execution.ts +25 -0
  256. package/src/combos/failover.ts +127 -9
  257. package/src/combos/index.ts +1 -0
  258. package/src/combos/resolve.ts +60 -22
  259. package/src/config/atomic-write.ts +113 -29
  260. package/src/config/diagnostics.ts +21 -10
  261. package/src/config/initialize.ts +6 -6
  262. package/src/config/live-reconcile.ts +11 -3
  263. package/src/config/load-degrade.ts +2 -0
  264. package/src/config/owner-registry.ts +5 -4
  265. package/src/config/persist-unlocked.ts +34 -8
  266. package/src/config/persisted-mutation.ts +7 -0
  267. package/src/config/process-state.ts +32 -10
  268. package/src/config/removed-opencode-free-backup.ts +99 -0
  269. package/src/config/removed-opencode-free.ts +4 -8
  270. package/src/config/salvage.ts +2 -0
  271. package/src/config/schema/config-schema.ts +44 -1
  272. package/src/config/schema/leaf-validators.ts +22 -0
  273. package/src/config/schema/workflow-budget.ts +43 -0
  274. package/src/config/tracked-runtime-inspection.ts +188 -0
  275. package/src/config.ts +4 -4
  276. package/src/generated/compatibility-version.json +962 -434
  277. package/src/grok/inject.ts +2 -1
  278. package/src/grok/sync.ts +5 -2
  279. package/src/images/loop.ts +14 -5
  280. package/src/integrations/aside-profile-context.ts +1 -1
  281. package/src/integrations/catalog-refresh.ts +1 -1
  282. package/src/integrations/droid-settings.ts +4 -4
  283. package/src/integrations/hermes-profiles.ts +3 -3
  284. package/src/integrations/hermes-refresh.ts +28 -0
  285. package/src/integrations/model-name-guard.ts +31 -0
  286. package/src/integrations/mutation-plan.ts +17 -4
  287. package/src/integrations/ownership.ts +3 -0
  288. package/src/integrations/registry.ts +10 -1
  289. package/src/integrations/state.ts +6 -0
  290. package/src/integrations/writer.ts +64 -59
  291. package/src/lib/abort.ts +8 -4
  292. package/src/lib/bounded-body.ts +7 -1
  293. package/src/lib/bounded-file-read.ts +3 -9
  294. package/src/lib/bun-runtime-preflight.ts +9 -8
  295. package/src/lib/config-ownership.ts +4 -0
  296. package/src/lib/errors.ts +2 -0
  297. package/src/lib/eventstream-decoder.ts +3 -2
  298. package/src/lib/file-identity.ts +15 -0
  299. package/src/lib/http-response-semantics.ts +9 -6
  300. package/src/lib/inbound-body-policy.ts +11 -0
  301. package/src/lib/jsonc.ts +7 -2
  302. package/src/lib/local-chat-completion.ts +8 -6
  303. package/src/lib/local-destinations.ts +32 -3
  304. package/src/lib/local-management-capability.ts +3 -1
  305. package/src/lib/local-upstream.ts +22 -26
  306. package/src/lib/loopback-family.ts +31 -0
  307. package/src/lib/plain-data.ts +7 -5
  308. package/src/lib/process-control.ts +30 -5
  309. package/src/lib/redact-folding.ts +9 -0
  310. package/src/lib/shadow-call.ts +55 -1
  311. package/src/lib/spend-pool-alias-validation.ts +6 -6
  312. package/src/lib/state-store-registrations.ts +2 -0
  313. package/src/lib/test-home-guard.ts +37 -9
  314. package/src/lib/tool-argument-integers.ts +99 -7
  315. package/src/lib/upstream-retry.ts +6 -1
  316. package/src/lib/windows-elevation.ts +34 -11
  317. package/src/lib/windows-owner-acl.ts +272 -32
  318. package/src/lib/windows-secret-acl.ts +328 -44
  319. package/src/lib/windows-service-wrappers.ts +10 -7
  320. package/src/lib/winsw.ts +8 -4
  321. package/src/lib/workflow-budget-config.ts +39 -0
  322. package/src/link/relay-auth.ts +38 -1
  323. package/src/link/remote-platform.ts +11 -23
  324. package/src/link/remote-probe.ts +3 -1
  325. package/src/link/remote-windows.ts +150 -0
  326. package/src/link/ssh-argv.ts +13 -5
  327. package/src/link/store.ts +4 -1
  328. package/src/link/supervisor.ts +9 -0
  329. package/src/local-credentials/generation.ts +242 -0
  330. package/src/local-credentials/inventory.ts +405 -0
  331. package/src/local-credentials/observation-lease.ts +83 -0
  332. package/src/local-credentials/publication-fence.ts +81 -0
  333. package/src/local-credentials/references.ts +36 -0
  334. package/src/local-credentials/runtime-observation.ts +28 -0
  335. package/src/messaging/remote-forward-failure.ts +35 -0
  336. package/src/messaging/remote-ports.ts +27 -5
  337. package/src/messaging/remote-process.ts +30 -4
  338. package/src/messaging/remote-tunnels.ts +80 -15
  339. package/src/oauth/account-auto-pause-policy.ts +11 -0
  340. package/src/oauth/anthropic-account-refusal.ts +1 -0
  341. package/src/oauth/anthropic-rate-limit-policy.ts +26 -2
  342. package/src/oauth/anthropic-routing.ts +34 -44
  343. package/src/oauth/anthropic-session-affinity-store.ts +177 -0
  344. package/src/oauth/antigravity-discovery-diagnostics.ts +65 -0
  345. package/src/oauth/chatgpt.ts +11 -9
  346. package/src/oauth/cursor.ts +8 -2
  347. package/src/oauth/generic-account-failover.ts +33 -2
  348. package/src/oauth/generic-session-affinity.ts +7 -0
  349. package/src/oauth/google-antigravity.ts +49 -12
  350. package/src/oauth/index.ts +3 -0
  351. package/src/oauth/kiro-device-login.ts +87 -30
  352. package/src/oauth/kiro-iam-identity-center.ts +107 -0
  353. package/src/oauth/store.ts +41 -11
  354. package/src/protocols/encoders/adapter-events.ts +7 -4
  355. package/src/protocols/encoders/messages.ts +1 -1
  356. package/src/providers/account-quota-disk.ts +18 -4
  357. package/src/providers/antigravity-account-roster.ts +73 -7
  358. package/src/providers/antigravity-models.ts +8 -4
  359. package/src/providers/api-key-resolve.ts +16 -3
  360. package/src/providers/cc-switch-import-bytes.ts +991 -0
  361. package/src/providers/cc-switch-import-source.ts +1083 -0
  362. package/src/providers/cc-switch-import.ts +942 -0
  363. package/src/providers/claude-cli-identity.ts +2 -0
  364. package/src/providers/codex-capacity.ts +3 -2
  365. package/src/providers/derive.ts +6 -0
  366. package/src/providers/free-directory.ts +10 -2
  367. package/src/providers/key-store.ts +7 -2
  368. package/src/providers/model-discovery-diagnostic.ts +4 -0
  369. package/src/providers/model-discovery.ts +4 -4
  370. package/src/providers/model-rename-fields.ts +2 -0
  371. package/src/providers/model-rename-migration.ts +41 -6
  372. package/src/providers/provider-id-rewrite.ts +3 -0
  373. package/src/providers/quota/antigravity.ts +6 -4
  374. package/src/providers/quota/report-cache.ts +17 -4
  375. package/src/providers/quota/vendor-probes-oauth.ts +0 -1
  376. package/src/providers/quota.ts +2 -2
  377. package/src/providers/reasoning-metadata.ts +31 -15
  378. package/src/providers/registry/entries-core.ts +1 -1
  379. package/src/providers/registry/entries-extended.ts +1 -1
  380. package/src/providers/registry/model-ids.ts +1 -0
  381. package/src/providers/registry/model-seeds.ts +2 -1
  382. package/src/providers/registry/types.ts +3 -1
  383. package/src/providers/resolved-model-policy.ts +2 -2
  384. package/src/providers/routed-config.ts +2 -0
  385. package/src/providers/stale-model-roster-migration.ts +8 -1
  386. package/src/providers/xai-transport.ts +4 -4
  387. package/src/quota-pool/assemble.ts +51 -21
  388. package/src/quota-pool/pooled.ts +162 -0
  389. package/src/remote-control/workspace-codex-runtime.ts +63 -20
  390. package/src/remote-control/workspace-executor.ts +14 -13
  391. package/src/responses/apply-patch-envelope.ts +35 -0
  392. package/src/responses/compaction-history-framing.ts +15 -4
  393. package/src/responses/custom-tool-compat.ts +2 -1
  394. package/src/responses/item-provenance.ts +79 -0
  395. package/src/responses/namespace-tool-compat.ts +21 -3
  396. package/src/responses/turn-membership.ts +111 -0
  397. package/src/router.ts +21 -2
  398. package/src/routing/analytics.ts +3 -5
  399. package/src/routing/fallback-policy.ts +7 -3
  400. package/src/routing/health.ts +5 -3
  401. package/src/routing/history/build-file.ts +6 -0
  402. package/src/routing/history/indexer.ts +158 -31
  403. package/src/routing/history/ingest.ts +1 -1
  404. package/src/routing/history/integrity.ts +208 -0
  405. package/src/routing/history/rebuild-job.ts +20 -6
  406. package/src/routing/history/rebuild-protocol.ts +2 -1
  407. package/src/routing/history/rebuild-worker.ts +18 -0
  408. package/src/routing/history/sqlite-errors.ts +9 -0
  409. package/src/server/admission-model-scope.ts +21 -4
  410. package/src/server/advisor-admission-scope.ts +72 -0
  411. package/src/server/audio-upstream.ts +10 -2
  412. package/src/server/auth-cors.ts +28 -2
  413. package/src/server/bind-host.ts +5 -0
  414. package/src/server/capture-admission-policy.ts +91 -0
  415. package/src/server/chat-completions.ts +47 -6
  416. package/src/server/chat-native.ts +16 -11
  417. package/src/server/claude-messages.ts +99 -3
  418. package/src/server/codex-model-list.ts +47 -0
  419. package/src/server/configured-credentials.ts +5 -0
  420. package/src/server/gui-session.ts +5 -2
  421. package/src/server/inbound-body-admission.ts +21 -13
  422. package/src/server/inbound-body-budget.ts +128 -0
  423. package/src/server/index/link-listener.ts +3 -1
  424. package/src/server/index/link-relay-sessions.ts +9 -2
  425. package/src/server/index/optional-listeners.ts +1 -0
  426. package/src/server/index/serve-options.ts +21 -45
  427. package/src/server/index/websocket-handler.ts +10 -0
  428. package/src/server/index.ts +6 -5
  429. package/src/server/inference/client-encoder-delivery.ts +3 -1
  430. package/src/server/lifecycle.ts +8 -1
  431. package/src/server/management/advisor-routes.ts +26 -9
  432. package/src/server/management/agent-settings-routes.ts +455 -549
  433. package/src/server/management/anthropic-reset-grant-routes.ts +2 -1
  434. package/src/server/management/claude-code-settings-patch.ts +211 -0
  435. package/src/server/management/claude-desktop-config-writers.ts +78 -0
  436. package/src/server/management/codex-agent-role-routes.ts +80 -2
  437. package/src/server/management/codex-cli-update-routes.ts +55 -0
  438. package/src/server/management/codex-prompt-routes.ts +2 -1
  439. package/src/server/management/codex-role-auto-assign.ts +50 -6
  440. package/src/server/management/config-routes.ts +459 -384
  441. package/src/server/management/consent-session.ts +6 -0
  442. package/src/server/management/context.ts +3 -0
  443. package/src/server/management/desktop-compatibility-authorization.ts +12 -0
  444. package/src/server/management/desktop-compatibility-routes.ts +3 -2
  445. package/src/server/management/desktop-compatibility-runtime-routes.ts +2 -1
  446. package/src/server/management/desktop-compatibility-settings-routes.ts +2 -1
  447. package/src/server/management/integration-routes.ts +45 -5
  448. package/src/server/management/link-enrollment.ts +21 -32
  449. package/src/server/management/link-route-state.ts +1 -0
  450. package/src/server/management/link-routes.ts +4 -1
  451. package/src/server/management/model-routes.ts +22 -6
  452. package/src/server/management/model-rows.ts +3 -1
  453. package/src/server/management/native-integration-routes.ts +112 -38
  454. package/src/server/management/oauth-account-routes.ts +28 -11
  455. package/src/server/management/provider-overwrite-carry.ts +21 -0
  456. package/src/server/management/provider-routes.ts +3 -1
  457. package/src/server/management/route-registry.ts +10 -3
  458. package/src/server/management/session-routes.ts +20 -2
  459. package/src/server/management/shadow-call-validation.ts +43 -2
  460. package/src/server/management/shared.ts +17 -1
  461. package/src/server/management/sidebar-routes.ts +2 -1
  462. package/src/server/management/system-restart.ts +47 -7
  463. package/src/server/management/workflow-budget-routes.ts +70 -3
  464. package/src/server/management-api.ts +61 -51
  465. package/src/server/management-auth.ts +11 -3
  466. package/src/server/messages-native-eligibility.ts +6 -5
  467. package/src/server/messages-native-scope.ts +6 -1
  468. package/src/server/messages-native.ts +21 -7
  469. package/src/server/messages-shared.ts +161 -29
  470. package/src/server/persistent-gui-session.ts +155 -0
  471. package/src/server/port-reclaim.ts +29 -5
  472. package/src/server/proxy-liveness.ts +110 -33
  473. package/src/server/request-decompress.ts +5 -1
  474. package/src/server/request-log.ts +30 -2
  475. package/src/server/responses/account-change-state.ts +14 -2
  476. package/src/server/responses/adapter-continuation.ts +5 -4
  477. package/src/server/responses/adapter-delivery.ts +24 -5
  478. package/src/server/responses/adapter-dispatch.ts +39 -45
  479. package/src/server/responses/advisor-plan-slot.ts +7 -0
  480. package/src/server/responses/advisor-slot.ts +77 -48
  481. package/src/server/responses/antigravity-model-denial-recovery.ts +70 -0
  482. package/src/server/responses/antigravity-validation-refusal.ts +6 -0
  483. package/src/server/responses/codex-auth-error.ts +5 -1
  484. package/src/server/responses/combo-required-tool-contract.ts +29 -1
  485. package/src/server/responses/combo-required-tool-fulfillments.ts +58 -0
  486. package/src/server/responses/combo-required-tool-stream.ts +119 -0
  487. package/src/server/responses/combo-stream-preflight.ts +47 -7
  488. package/src/server/responses/compact.ts +18 -8
  489. package/src/server/responses/compaction-recovery.ts +2 -1
  490. package/src/server/responses/core-auth.ts +2 -1
  491. package/src/server/responses/core-codex-account.ts +1 -0
  492. package/src/server/responses/core-combo-failure.ts +13 -6
  493. package/src/server/responses/core-combo-native.ts +6 -5
  494. package/src/server/responses/core-combo.ts +159 -25
  495. package/src/server/responses/core-lifetime.ts +4 -0
  496. package/src/server/responses/core-options.ts +16 -0
  497. package/src/server/responses/core.ts +2 -0
  498. package/src/server/responses/fetch-helpers.ts +5 -1
  499. package/src/server/responses/jev-model-invoke.ts +10 -3
  500. package/src/server/responses/memory-models.ts +3 -2
  501. package/src/server/responses/passthrough-delivery.ts +36 -8
  502. package/src/server/responses/passthrough-dispatch.ts +17 -16
  503. package/src/server/responses/policy-fallback.ts +2 -0
  504. package/src/server/responses/request-prepare.ts +14 -6
  505. package/src/server/responses/request-send-budget.ts +2 -1
  506. package/src/server/responses/request-sidecar-auth.ts +1 -0
  507. package/src/server/responses/request-transport.ts +43 -9
  508. package/src/server/responses/run-turn-execution.ts +15 -3
  509. package/src/server/responses/sidecar-execution.ts +26 -5
  510. package/src/server/responses/turn-membership.ts +30 -0
  511. package/src/server/responses-custom-tool-repair.ts +86 -11
  512. package/src/server/responses-image-gen-repair.ts +1 -1
  513. package/src/server/responses-snapshot-repair.ts +18 -4
  514. package/src/server/responses-undeclared-tool-guard.ts +4 -0
  515. package/src/server/restart-parent-ownership.ts +49 -0
  516. package/src/server/stop-teardown.ts +46 -9
  517. package/src/server/windows-tcp-drop.ts +4 -2
  518. package/src/server/workflow-refusal.ts +2 -1
  519. package/src/service/desktop-recovery-process.ts +341 -0
  520. package/src/service/desktop-recovery.ts +172 -0
  521. package/src/service/state-lock.ts +12 -11
  522. package/src/service/windows-ops.ts +6 -3
  523. package/src/service/windows-scheduler.ts +29 -6
  524. package/src/service-manager-probe.ts +53 -8
  525. package/src/stall-timeout.ts +47 -0
  526. package/src/tray/windows.ts +6 -4
  527. package/src/types/admission-policy.ts +13 -0
  528. package/src/types/config.ts +86 -10
  529. package/src/types/provider.ts +10 -0
  530. package/src/types/request.ts +8 -1
  531. package/src/types.ts +2 -0
  532. package/src/update/async-check.ts +4 -3
  533. package/src/update/bind-probe.ts +2 -2
  534. package/src/update/codex-cli-update-launch-policy.mjs +9 -0
  535. package/src/update/guarded-port-reclaim.ts +14 -0
  536. package/src/update/guarded-runtime-ops.ts +58 -0
  537. package/src/update/guarded-tray-ops.ts +9 -0
  538. package/src/update/index.ts +196 -58
  539. package/src/update/job-pinned-start.ts +53 -0
  540. package/src/update/job-supervised-restart.ts +23 -6
  541. package/src/update/job-update-home.ts +62 -0
  542. package/src/update/job-update-tray.ts +29 -0
  543. package/src/update/job-windows-restart.ts +39 -0
  544. package/src/update/job.ts +199 -193
  545. package/src/update/mutation-guard.d.mts +30 -0
  546. package/src/update/mutation-guard.mjs +103 -0
  547. package/src/update/notify.ts +2 -2
  548. package/src/update/npm-cache-preflight.mjs +4 -4
  549. package/src/update/npm-install.mjs +5 -3
  550. package/src/update/pnpm-read-policy.mjs +3 -2
  551. package/src/update/proxy-liveness-probe.mjs +2 -2
  552. package/src/update/service-home-authority.ts +35 -0
  553. package/src/update/service-home-package-only-protocol.json +1 -0
  554. package/src/update/service-home-policy.d.mts +25 -0
  555. package/src/update/service-home-policy.mjs +112 -0
  556. package/src/update/service-home-probe-entry.ts +9 -0
  557. package/src/update/service-home-probe.d.mts +15 -0
  558. package/src/update/service-home-probe.mjs +79 -0
  559. package/src/update/service-home-protocol.json +1 -0
  560. package/src/update/supervised-recovery.d.mts +2 -2
  561. package/src/update/supervised-recovery.mjs +14 -7
  562. package/src/update/transactional-install.d.mts +3 -1
  563. package/src/update/transactional-install.mjs +29 -19
  564. package/src/update/update-failure-guidance.mjs +1 -1
  565. package/src/update/worker-launch.ts +74 -4
  566. package/src/usage/log.ts +25 -4
  567. package/src/vision/anthropic-describe.ts +2 -1
  568. package/src/vision/index.ts +2 -0
  569. package/src/vision/plan.ts +4 -0
  570. package/src/vision/routed-describe.ts +38 -23
  571. package/src/web-search/anthropic-executor.ts +2 -1
  572. package/src/web-search/anthropic-history.ts +1 -0
  573. package/src/web-search/format-result.ts +3 -2
  574. package/src/web-search/header-deadline.ts +3 -2
  575. package/src/web-search/loop.ts +113 -12
  576. package/src/web-search/parse.ts +201 -40
  577. package/gui/dist/assets/App-CizjBqyk.js +0 -58
  578. package/gui/dist/assets/App-DMps4OLk.css +0 -1
  579. package/gui/dist/assets/Tray-DamiMqcX.js +0 -1
  580. package/gui/dist/assets/index-DQsht3vH.js +0 -94
  581. package/gui/dist/assets/index-DRe8Hhfz.css +0 -1
  582. package/gui/dist/assets/quota-summary-BXu4zE8H.js +0 -1
@@ -1,3 +1,10 @@
1
+ import { prepareClaudeCodePatch } from "./claude-code-settings-patch";
2
+ import { beginCodexCliSelectionParentWriteAsync, withCodexCliSelectionParentWriteAsync,
3
+ CodexCliSelectionMutationBusyError, type CodexCliSelectionAsyncParentWrite } from "../../codex/cli-update-selection-gate";
4
+ import { readConfigForAdmittedMutation } from "../../config/persisted-mutation";
5
+ import { mirrorDesiredEnabledOntoSnapshot, persistDesktopModeField, persistDesktopProfileField } from "./claude-desktop-config-writers";
6
+ import { getConfigDir as configRoot, withConfigDirHardeningSettled as settleConfigRoot } from "../../config/paths";
7
+ import { WindowsSecretAclSettleTimeoutError } from "../../lib/windows-secret-acl";
1
8
  import { ensureManagementClaudeIntercept, interceptStartRefusal, interceptStatus } from "./claude-intercept-routes";
2
9
  import { persistCommittedDesktopGateway } from "../../claude/desktop-gateway-state";
3
10
  import { captureDesktopAppliedMarker, commitDesktopAppliedMarker } from "../../claude/desktop-applied-marker";
@@ -13,7 +20,7 @@ import { mergeModelPinnedEfforts, modelPinnedEffortsConfigError } from "../../co
13
20
  import { MULTI_AGENT_SURFACE_ADVISORY_VERSION, multiAgentSurfaceAdvisory, resolveMultiAgentMode } from "../../config/multi-agent-surface";
14
21
  import { captureConfigTopLevelRollback, parsedConfigRebaseDeletionKeys, projectConfigRebaseProvenance } from "../../config/rebase-provenance";
15
22
  import { anthropicSidecarPatchError } from "../../config/schema/anthropic-account-pool";
16
- import { isAnthropicInstanceId, type AnthropicInstanceId } from "../../providers/anthropic-instance-id";
23
+ import { isAnthropicInstanceId } from "../../providers/anthropic-instance-id";
17
24
  import {
18
25
  adoptPersistedClaudeCode,
19
26
  DEFAULT_SUBAGENT_MODELS,
@@ -67,7 +74,7 @@ import {
67
74
  setDebugSettings,
68
75
  type DebugFlag,
69
76
  } from "../../lib/debug-settings";
70
- import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
77
+ import type { OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
71
78
  import {
72
79
  visionCandidateRows,
73
80
  visionDescriberIsProvablyBlind,
@@ -103,66 +110,6 @@ let grokApplyTestHooks: { now?: () => number; run?: () => Promise<unknown> } | n
103
110
 
104
111
  class GrokApplyBusyError extends Error {}
105
112
 
106
- /**
107
- * Mirror a durable desired-state transition onto the long-lived server snapshot.
108
- *
109
- * `setIntegrationEnabled` writes DISK only. The server reuses one `config` object
110
- * for every request, so leaving it stale makes the native GET report the opposite
111
- * of what was just persisted, and makes any later whole-snapshot save (the Desktop
112
- * profile PUT does exactly that) write the stale value back over the transition.
113
- * ON is the ABSENCE of the key, matching `setIntegrationEnabled`'s on-disk shape.
114
- */
115
- function mirrorDesiredEnabledOntoSnapshot(config: OcxConfig, client: "claude-desktop", enabled: boolean): void {
116
- const integrations = { ...(config.clientIntegrations ?? {}) };
117
- if (enabled) delete integrations[client];
118
- else integrations[client] = false;
119
- if (Object.keys(integrations).length === 0) deleteConfigTopLevelKey(config, "clientIntegrations");
120
- else config.clientIntegrations = integrations;
121
- }
122
-
123
- /**
124
- * Persist ONLY `claudeCode.desktopProfile`, field-scoped, against the CURRENT
125
- * on-disk config.
126
- *
127
- * `saveConfigPreservingClaudeCode(ctx.config)` writes the whole long-lived server
128
- * snapshot. On the apply path that snapshot still carries the `clientIntegrations`
129
- * it was loaded with, so a save right after `setIntegrationEnabled("claude-desktop",
130
- * true)` carried the stale OFF back over the enable and made the route cancel its
131
- * own apply. Mutating one field under the config-mutation lock cannot regress an
132
- * unrelated key another writer just committed.
133
- */
134
- function persistDesktopProfileField(
135
- config: OcxConfig,
136
- desktopProfile: NonNullable<OcxConfig["claudeCode"]>["desktopProfile"],
137
- ): { ok: true } | { ok: false; reason: "missing" | "invalid" | "conflict" } {
138
- const outcome = mutatePersistedConfig(persisted => {
139
- persisted.claudeCode = { ...(persisted.claudeCode ?? {}), desktopProfile };
140
- return { changed: true, value: structuredClone(persisted.claudeCode) };
141
- });
142
- // Only mirror into memory once the durable write actually landed; an
143
- // `unavailable` outcome must not leave the snapshot claiming a saved profile.
144
- if (outcome.status === "unavailable") return { ok: false, reason: outcome.reason };
145
- adoptPersistedClaudeCode(config, outcome.value);
146
- return { ok: true };
147
- }
148
-
149
- async function persistDesktopModeField(
150
- config: OcxConfig,
151
- desktopMode: "first-party" | "gateway",
152
- ): Promise<{ ok: true } | { ok: false; reason: "missing" | "invalid" | "conflict" }> {
153
- const { recordClaudeDesktopMode } = await import("../../claude/desktop-first-party");
154
- const outcome = mutatePersistedConfig(persisted => {
155
- const mutation = recordClaudeDesktopMode(persisted, desktopMode);
156
- return { changed: mutation.changed, value: structuredClone(persisted.claudeCode) };
157
- });
158
- if (outcome.status === "unavailable") return { ok: false, reason: outcome.reason };
159
- // First-party apply ends here — no profile-marker write follows — so without
160
- // adopting, live diverges from the armed baseline and a later whole-config
161
- // save reads that divergence as a pending mutation and stomps hand edits.
162
- adoptPersistedClaudeCode(config, outcome.value);
163
- return { ok: true };
164
- }
165
-
166
113
  export function grokApplyFlightSnapshot(): { currentBytes: number; highWaterBytes: number; active: number } {
167
114
  return {
168
115
  currentBytes: grokApplyFlight?.bytes ?? 0,
@@ -258,6 +205,15 @@ export async function injectionModelView(config: OcxConfig, routed: readonly Cat
258
205
  }
259
206
 
260
207
  export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise<Response | null> {
208
+ try { return await handleAgentSettingsRoutesImpl(ctx); }
209
+ catch (error) {
210
+ if (error instanceof CodexCliSelectionMutationBusyError) return jsonResponse({ error: error.message, retryable: true }, 503);
211
+ if (!(error instanceof WindowsSecretAclSettleTimeoutError)) throw error;
212
+ return jsonResponse({ error: "Could not save settings", code: "write_failed", diagnostic: { stage: "ca", cause: "ETIMEDOUT" } }, 500);
213
+ }
214
+ }
215
+
216
+ async function handleAgentSettingsRoutesImpl(ctx: ManagementContext): Promise<Response | null> {
261
217
  const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
262
218
 
263
219
  /** Best-effort Desktop 3P config auto-reconcile when providers change. */
@@ -282,9 +238,9 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
282
238
  if (siblingOfLivePort() !== null) return;
283
239
  // Serialized with Desktop mode transitions: a first-party switch cannot interleave with this write.
284
240
  const { runPickerTransition } = await import("./claude-desktop-picker-routes");
285
- await runPickerTransition(admitted, async () => {
241
+ await runPickerTransition(admitted, () => settleConfigRoot(configRoot(), () => {
286
242
  if (siblingOfLivePort() !== null) return undefined;
287
- const current = loadConfig();
243
+ const current = readConfigForAdmittedMutation();
288
244
  // This is the real guard: the catalog await admits a concurrent explicit OFF.
289
245
  if (!claudeDesktopIntegrationEnabled(current)) return undefined;
290
246
  // …and a concurrent switch to first-party.
@@ -313,7 +269,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
313
269
  console.warn("[claude-desktop] provider-change applied marker skipped");
314
270
  }
315
271
  }
316
- });
272
+ }));
317
273
  } catch { /* best-effort */ }
318
274
  }
319
275
 
@@ -412,19 +368,32 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
412
368
  return jsonResponse({ error: "body.multiAgentSurfaceAdvisoryAcknowledged must be a boolean" }, 400);
413
369
  }
414
370
  const mode = wantsMode ? body.multiAgentMode as "v1" | "default" | "v2" : undefined;
415
- const effectiveMode = mode ?? config.multiAgentMode ?? "default";
416
- const effectiveKeepNative = wantsKeepNative
417
- ? body.keepNativeChatGptOnV1 === true
418
- : config.keepNativeChatGptOnV1 === true;
419
- const hybridPinActive = effectiveMode === "v2" && effectiveKeepNative;
420
- const modeFlag = mode === "v2" ? !hybridPinActive : mode === "v1" ? false : undefined;
421
- if (wantsFlag && modeFlag !== undefined && body.enabled !== modeFlag) {
422
- return jsonResponse({
423
- error: hybridPinActive
424
- ? "body.enabled=true conflicts with keepNativeChatGptOnV1: Codex's global multi_agent_v2 override outranks catalog pins"
425
- : `body.enabled conflicts with multiAgentMode '${mode}'`,
426
- }, 400);
427
- }
371
+ const readModePlan = () => {
372
+ const effectiveMode = mode ?? config.multiAgentMode ?? "default";
373
+ const effectiveKeepNative = wantsKeepNative
374
+ ? body.keepNativeChatGptOnV1 === true
375
+ : config.keepNativeChatGptOnV1 === true;
376
+ const hybridPinActive = effectiveMode === "v2" && effectiveKeepNative;
377
+ const modeFlag = mode === "v2" ? !hybridPinActive : mode === "v1" ? false : undefined;
378
+ if (wantsFlag && modeFlag !== undefined && body.enabled !== modeFlag) {
379
+ return jsonResponse({
380
+ error: hybridPinActive
381
+ ? "body.enabled=true conflicts with keepNativeChatGptOnV1: Codex's global multi_agent_v2 override outranks catalog pins"
382
+ : `body.enabled conflicts with multiAgentMode '${mode}'`,
383
+ }, 400);
384
+ }
385
+ if (wantsFlag && body.enabled === true && hybridPinActive) {
386
+ return jsonResponse({
387
+ error: "body.enabled=true conflicts with keepNativeChatGptOnV1: Codex's global multi_agent_v2 override outranks catalog pins",
388
+ }, 400);
389
+ }
390
+ const requestedFlag = wantsFlag
391
+ ? body.enabled as boolean
392
+ : modeFlag ?? (wantsKeepNative && hybridPinActive ? false : undefined);
393
+ return { effectiveMode, requestedFlag };
394
+ };
395
+ const initialPlan = readModePlan();
396
+ if (initialPlan instanceof Response) return initialPlan;
428
397
  const {
429
398
  isMultiAgentV2Enabled, hasAgentsMaxThreads, getLogicalMaxThreads, transitionMultiAgentV2,
430
399
  getAgentsEnabled, getAgentsMaxDepth, getSubagentDeveloperInstructions,
@@ -436,20 +405,11 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
436
405
  // repeats this check, but doing it here prevents an earlier flag/mode/agents
437
406
  // write from landing before an unsupported runtime returns 502.
438
407
  if (wantsModeHintText && body.multiAgentModeHintText !== null
439
- && probeCodexSupportsModeHint() === false) {
440
- return jsonResponse({
441
- error: `writing multiAgentModeHintText failed: ${MODE_HINT_UNSUPPORTED_ERROR}`,
442
- }, 502);
408
+ && await withCodexCliSelectionParentWriteAsync(probeCodexSupportsModeHint, { signal: req.signal }) === false) {
409
+ return jsonResponse({ error: `writing multiAgentModeHintText failed: ${MODE_HINT_UNSUPPORTED_ERROR}` }, 502);
443
410
  }
444
411
  const warnings: string[] = [];
445
- if (wantsFlag && body.enabled === true && hybridPinActive) {
446
- return jsonResponse({
447
- error: "body.enabled=true conflicts with keepNativeChatGptOnV1: Codex's global multi_agent_v2 override outranks catalog pins",
448
- }, 400);
449
- }
450
- const requestedFlag = wantsFlag
451
- ? body.enabled as boolean
452
- : modeFlag ?? (wantsKeepNative && hybridPinActive ? false : undefined);
412
+ let requestedFlag: boolean | undefined;
453
413
  /*
454
414
  * One held section for every config.toml write this PUT makes — the
455
415
  * feature transition plus each scalar edit. Individually-locked writers
@@ -457,83 +417,97 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
457
417
  * combination on disk; the lock is released before the post-write readers
458
418
  * and catalog converge below.
459
419
  */
460
- const needsCodexConfigWrites = requestedFlag !== undefined || wantsThreads
420
+ const needsCodexConfigWrites = initialPlan.requestedFlag !== undefined || wantsThreads
461
421
  || wantsAgentsEnabled || wantsMaxDepth || wantsSubagentInstructions || wantsModeHintText;
462
422
  if (needsCodexConfigWrites && codexHomeIsAbsent(dirname(activeCodexConfigPath()))) {
463
423
  return jsonResponse({ error: `config.toml not readable at ${activeCodexConfigPath()}` }, 502);
464
424
  }
465
425
  const { acquireConfigWriteLock, releaseConfigWriteLock, configWriteLockFailureMessage } = await import("../../codex/config-write-lock");
426
+ const { runCodexFeaturesCommand } = await import("../../cli/v2");
466
427
  const configWriteLock = needsCodexConfigWrites ? await acquireConfigWriteLock(activeCodexConfigPath()) : null;
467
428
  if (configWriteLock !== null && !configWriteLock.ok) {
468
429
  return jsonResponse({ error: configWriteLockFailureMessage(configWriteLock), retryable: configWriteLock.error === "locked" }, 502);
469
430
  }
470
431
  const heldWriteLock = configWriteLock !== null && configWriteLock.ok ? configWriteLock.handle : undefined;
432
+ let selectionWrite: CodexCliSelectionAsyncParentWrite | undefined;
471
433
  try {
472
- if (requestedFlag !== undefined || wantsThreads) {
473
- const targetFlag = requestedFlag ?? isMultiAgentV2Enabled();
474
- let toggle = deps.toggleCodexMultiAgentV2;
475
- if (!toggle) {
476
- const { runCodexFeaturesCommand } = await import("../../cli/v2");
477
- toggle = (enabled, env, validate) => runCodexFeaturesCommand(enabled ? "enable" : "disable", "multi_agent_v2", env, validate);
434
+ if (wantsFlag || wantsMode || wantsThreads || wantsKeepNative || (wantsModeHintText && body.multiAgentModeHintText !== null)) {
435
+ selectionWrite = await beginCodexCliSelectionParentWriteAsync({ signal: req.signal });
436
+ if (!selectionWrite.entered) return jsonResponse({ error: "codex_cli_selection_busy", retryable: true }, 503);
478
437
  }
479
- const result = transitionMultiAgentV2(targetFlag, toggle, {
480
- ...(wantsThreads ? { threadLimit: body.maxConcurrentThreadsPerSession as number } : {}),
481
- heldConfigWriteLock: heldWriteLock,
482
- });
483
- if (!result.ok) return jsonResponse({ error: `multi_agent_v2 transition failed: ${result.error}`, ...(result.retryable === false ? { retryable: false } : {}) }, 502);
484
- if (result.changed && result.threadLimit !== null) warnings.push(`Thread limit ${result.threadLimit} preserved for ${targetFlag ? "v2" : "v1"}.`);
485
- }
486
- if (wantsMode) {
487
- if (mode === "default") deleteConfigTopLevelKey(config, "multiAgentMode");
488
- else config.multiAgentMode = mode;
489
- saveConfigPreservingClaudeCode(config);
490
- warnings.push(`Multi-agent mode set to '${mode}'. Applies to new sessions.`);
491
- }
492
- if (wantsKeepNative) {
493
- if (body.keepNativeChatGptOnV1 === true) config.keepNativeChatGptOnV1 = true;
494
- else deleteConfigTopLevelKey(config, "keepNativeChatGptOnV1");
495
- saveConfigPreservingClaudeCode(config);
496
- warnings.push(body.keepNativeChatGptOnV1 === true
497
- ? (effectiveMode === "v2"
498
- ? "ChatGPT-native models stay on v1 while other models use v2. Applies to new sessions."
499
- : "keepNativeChatGptOnV1 is stored but inactive until multi-agent mode is v2. Applies to new sessions.")
500
- : "ChatGPT-native models follow the selected v1/v2/base surface. Applies to new sessions.");
501
- }
502
- // Written after the mode, so a landed acknowledgement implies the mode write it was
503
- // sent with already landed. The converse does not hold: this writer throws rather than
504
- // reporting, exactly as the mode write above it does, so a failure here surfaces the
505
- // mode change with the advisory still raised. That is the benign direction — the
506
- // operator is asked again — and it is why this is not claimed as a transaction.
507
- if (wantsAdvisoryAck && body.multiAgentSurfaceAdvisoryAcknowledged === true) {
508
- config.multiAgentSurfaceAdvisoryVersion = MULTI_AGENT_SURFACE_ADVISORY_VERSION;
509
- saveConfigPreservingClaudeCode(config);
510
- }
511
- // New-key scalar writes: each writer is individually atomic, so apply them in
512
- // sequence after the transition. A failure here is a persistence failure (the
513
- // writers' ok:false result or a throw from the underlying atomic write helper),
514
- // reported as 502 naming the failed key plus the writes that already landed.
515
- // NOTE: do not name that helper literally here — tests/providers/xai/grok-writer-boundary.test.ts
516
- // asserts this route file contains no direct write primitive, and matches on the
517
- // symbol name even inside a comment.
518
- const scalarWrites: Array<{ field: string; run: () => { ok: true; changed: boolean } | { ok: false; error: string } }> = [];
519
- if (wantsAgentsEnabled) scalarWrites.push({ field: "agentsEnabled", run: () => setAgentsEnabled(body.agentsEnabled as boolean | null, undefined, heldWriteLock) });
520
- if (wantsMaxDepth) scalarWrites.push({ field: "agentsMaxDepth", run: () => setAgentsMaxDepth(body.agentsMaxDepth as number | null, undefined, heldWriteLock) });
521
- if (wantsSubagentInstructions) scalarWrites.push({ field: "subagentDeveloperInstructions", run: () => setSubagentDeveloperInstructions(body.subagentDeveloperInstructions as string | null, undefined, heldWriteLock) });
522
- if (wantsModeHintText) scalarWrites.push({ field: "multiAgentModeHintText", run: () => setMultiAgentModeHintText(body.multiAgentModeHintText as string | null, undefined, heldWriteLock) });
523
- const landed: string[] = [];
524
- for (const write of scalarWrites) {
525
- try {
526
- const result = write.run();
527
- if (!result.ok) {
528
- return jsonResponse({ error: `writing ${write.field} failed: ${result.error}${landed.length > 0 ? ` (already applied: ${landed.join(", ")})` : ""}` }, 502);
438
+ const commit = () => {
439
+ const currentPlan = readModePlan();
440
+ if (currentPlan instanceof Response) return currentPlan;
441
+ const { effectiveMode } = currentPlan;
442
+ requestedFlag = currentPlan.requestedFlag;
443
+ if (requestedFlag !== undefined && !heldWriteLock) return jsonResponse({ error: "Multi-agent configuration changed during admission", code: "config_changed" }, 409);
444
+ if (requestedFlag !== undefined || wantsThreads) {
445
+ const targetFlag = requestedFlag ?? isMultiAgentV2Enabled();
446
+ const toggle = deps.toggleCodexMultiAgentV2
447
+ ?? ((enabled, env, validate) => runCodexFeaturesCommand(enabled ? "enable" : "disable", "multi_agent_v2", env, validate));
448
+ const result = transitionMultiAgentV2(targetFlag, toggle, {
449
+ ...(wantsThreads ? { threadLimit: body.maxConcurrentThreadsPerSession as number } : {}),
450
+ heldConfigWriteLock: heldWriteLock,
451
+ });
452
+ if (!result.ok) return jsonResponse({ error: `multi_agent_v2 transition failed: ${result.error}`, ...(result.retryable === false ? { retryable: false } : {}) }, 502);
453
+ if (result.changed && result.threadLimit !== null) warnings.push(`Thread limit ${result.threadLimit} preserved for ${targetFlag ? "v2" : "v1"}.`);
529
454
  }
530
- landed.push(write.field);
531
- } catch (err) {
532
- const message = err instanceof Error ? err.message : String(err);
533
- return jsonResponse({ error: `writing ${write.field} failed: ${message}${landed.length > 0 ? ` (already applied: ${landed.join(", ")})` : ""}` }, 502);
534
- }
535
- }
455
+ if (wantsMode) {
456
+ if (mode === "default") deleteConfigTopLevelKey(config, "multiAgentMode");
457
+ else config.multiAgentMode = mode;
458
+ saveConfigPreservingClaudeCode(config);
459
+ warnings.push(`Multi-agent mode set to '${mode}'. Applies to new sessions.`);
460
+ }
461
+ if (wantsKeepNative) {
462
+ if (body.keepNativeChatGptOnV1 === true) config.keepNativeChatGptOnV1 = true;
463
+ else deleteConfigTopLevelKey(config, "keepNativeChatGptOnV1");
464
+ saveConfigPreservingClaudeCode(config);
465
+ warnings.push(body.keepNativeChatGptOnV1 === true
466
+ ? (effectiveMode === "v2"
467
+ ? "ChatGPT-native models stay on v1 while other models use v2. Applies to new sessions."
468
+ : "keepNativeChatGptOnV1 is stored but inactive until multi-agent mode is v2. Applies to new sessions.")
469
+ : "ChatGPT-native models follow the selected v1/v2/base surface. Applies to new sessions.");
470
+ }
471
+ // Written after the mode, so a landed acknowledgement implies the mode write it was
472
+ // sent with already landed. The converse does not hold: this writer throws rather than
473
+ // reporting, exactly as the mode write above it does, so a failure here surfaces the
474
+ // mode change with the advisory still raised. That is the benign direction — the
475
+ // operator is asked again — and it is why this is not claimed as a transaction.
476
+ if (wantsAdvisoryAck && body.multiAgentSurfaceAdvisoryAcknowledged === true) {
477
+ config.multiAgentSurfaceAdvisoryVersion = MULTI_AGENT_SURFACE_ADVISORY_VERSION;
478
+ saveConfigPreservingClaudeCode(config);
479
+ }
480
+ // New-key scalar writes: each writer is individually atomic, so apply them in
481
+ // sequence after the transition. A failure here is a persistence failure (the
482
+ // writers' ok:false result or a throw from the underlying atomic write helper),
483
+ // reported as 502 naming the failed key plus the writes that already landed.
484
+ // NOTE: do not name that helper literally here — tests/providers/xai/grok-writer-boundary.test.ts
485
+ // asserts this route file contains no direct write primitive, and matches on the
486
+ // symbol name even inside a comment.
487
+ const scalarWrites: Array<{ field: string; run: () => { ok: true; changed: boolean } | { ok: false; error: string } }> = [];
488
+ if (wantsAgentsEnabled) scalarWrites.push({ field: "agentsEnabled", run: () => setAgentsEnabled(body.agentsEnabled as boolean | null, undefined, heldWriteLock) });
489
+ if (wantsMaxDepth) scalarWrites.push({ field: "agentsMaxDepth", run: () => setAgentsMaxDepth(body.agentsMaxDepth as number | null, undefined, heldWriteLock) });
490
+ if (wantsSubagentInstructions) scalarWrites.push({ field: "subagentDeveloperInstructions", run: () => setSubagentDeveloperInstructions(body.subagentDeveloperInstructions as string | null, undefined, heldWriteLock) });
491
+ if (wantsModeHintText) scalarWrites.push({ field: "multiAgentModeHintText", run: () => setMultiAgentModeHintText(body.multiAgentModeHintText as string | null, undefined, heldWriteLock) });
492
+ const landed: string[] = [];
493
+ for (const write of scalarWrites) {
494
+ try {
495
+ const result = write.run();
496
+ if (!result.ok) {
497
+ return jsonResponse({ error: `writing ${write.field} failed: ${result.error}${landed.length > 0 ? ` (already applied: ${landed.join(", ")})` : ""}` }, 502);
498
+ }
499
+ landed.push(write.field);
500
+ } catch (err) {
501
+ const message = err instanceof Error ? err.message : String(err);
502
+ return jsonResponse({ error: `writing ${write.field} failed: ${message}${landed.length > 0 ? ` (already applied: ${landed.join(", ")})` : ""}` }, 502);
503
+ }
504
+ }
505
+ return null;
506
+ };
507
+ const writeRefusal = await settleConfigRoot(configRoot(), () => selectionWrite ? selectionWrite.commit(commit) : commit());
508
+ if (writeRefusal) return writeRefusal;
536
509
  } finally {
510
+ selectionWrite?.exit();
537
511
  if (heldWriteLock) releaseConfigWriteLock(heldWriteLock);
538
512
  }
539
513
  // Derived from fresh post-write readers (readConfigText is uncached): upstream
@@ -592,9 +566,9 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
592
566
  let toggle = deps.toggleDefaultModeRequestUserInput;
593
567
  if (!toggle) {
594
568
  try {
595
- const { codexFeaturesInvocation, runCodexFeaturesCommand } = await import("../../cli/v2");
569
+ const { codexFeaturesInvocationAsync, runCodexFeaturesCommand } = await import("../../cli/v2");
596
570
  const action = body.enabled ? "enable" : "disable";
597
- const invocation = codexFeaturesInvocation(action, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY, process.platform, { requireAvailable: true });
571
+ const invocation = await codexFeaturesInvocationAsync(action, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY, process.platform, { requireAvailable: true });
598
572
  toggle = (_enabled, env, validate) => runCodexFeaturesCommand(action, DEFAULT_MODE_REQUEST_USER_INPUT_FEATURE_KEY, env, validate, invocation);
599
573
  } catch (error) {
600
574
  return jsonResponse({ error: `default_mode_request_user_input toggle failed: ${error instanceof Error ? error.message : String(error)}` }, 502);
@@ -699,13 +673,11 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
699
673
  };
700
674
  const { isCodexReasoningEffort } = await import("../../reasoning-effort");
701
675
 
702
- let nextEnabled = config.multiAgentGuidanceEnabled;
703
- // Start from the effective state reported by GET. A stale hand-edited
704
- // `true` without a model must not spring back on during a model-only PUT.
705
- let nextSyncCodexSubagentDefaults = subagentDefaultSyncEffective(config);
706
- let nextModel = config.injectionModel;
707
- let nextEffort = config.injectionEffort;
708
- let nextPrompt = config.injectionPrompt;
676
+ let nextEnabled: OcxConfig["multiAgentGuidanceEnabled"];
677
+ let nextSyncCodexSubagentDefaults: boolean | undefined;
678
+ let nextModel: OcxConfig["injectionModel"];
679
+ let nextEffort: OcxConfig["injectionEffort"];
680
+ let nextPrompt: OcxConfig["injectionPrompt"];
709
681
 
710
682
  if ("multiAgentGuidanceEnabled" in body) {
711
683
  if (typeof body.multiAgentGuidanceEnabled !== "boolean") {
@@ -737,29 +709,38 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
737
709
  else if (body.prompt === null || body.prompt === "") nextPrompt = undefined;
738
710
  else return jsonResponse({ error: "prompt must be a string or null" }, 400);
739
711
  }
740
- // Clearing the model always clears model-dependent settings before sync/effort gates.
741
- if (!nextModel) {
742
- nextEffort = undefined;
743
- nextSyncCodexSubagentDefaults = false;
744
- }
745
- if (body.syncCodexSubagentDefaults === true && !nextModel?.trim()) {
746
- return jsonResponse({ error: "syncCodexSubagentDefaults requires an injection model" }, 400);
747
- }
748
- if (nextSyncCodexSubagentDefaults && nextEffort !== undefined && !isCodexReasoningEffort(nextEffort)) {
749
- return jsonResponse({ error: "syncCodexSubagentDefaults requires a supported Codex reasoning effort" }, 400);
750
- }
712
+ const refusal = await settleConfigRoot(configRoot(), () => {
713
+ if (!("multiAgentGuidanceEnabled" in body)) nextEnabled = config.multiAgentGuidanceEnabled;
714
+ if (!("syncCodexSubagentDefaults" in body)) nextSyncCodexSubagentDefaults = subagentDefaultSyncEffective(config);
715
+ if (!("model" in body)) nextModel = config.injectionModel;
716
+ if (!("effort" in body)) nextEffort = config.injectionEffort;
717
+ if (!("prompt" in body)) nextPrompt = config.injectionPrompt;
718
+ // Clearing the model always clears model-dependent settings before sync/effort gates.
719
+ if (!nextModel) {
720
+ nextEffort = undefined;
721
+ nextSyncCodexSubagentDefaults = false;
722
+ }
723
+ if (body.syncCodexSubagentDefaults === true && !nextModel?.trim()) {
724
+ return jsonResponse({ error: "syncCodexSubagentDefaults requires an injection model" }, 400);
725
+ }
726
+ if (nextSyncCodexSubagentDefaults && nextEffort !== undefined && !isCodexReasoningEffort(nextEffort)) {
727
+ return jsonResponse({ error: "syncCodexSubagentDefaults requires a supported Codex reasoning effort" }, 400);
728
+ }
751
729
 
752
- config.multiAgentGuidanceEnabled = nextEnabled;
753
- if (nextSyncCodexSubagentDefaults) config.syncCodexSubagentDefaults = true;
754
- else deleteConfigTopLevelKey(config, "syncCodexSubagentDefaults");
755
- if (nextModel) config.injectionModel = nextModel;
756
- else deleteConfigTopLevelKey(config, "injectionModel");
757
- if (nextEffort) config.injectionEffort = nextEffort;
758
- else deleteConfigTopLevelKey(config, "injectionEffort");
759
- if (nextPrompt) config.injectionPrompt = nextPrompt;
760
- else deleteConfigTopLevelKey(config, "injectionPrompt");
730
+ config.multiAgentGuidanceEnabled = nextEnabled;
731
+ if (nextSyncCodexSubagentDefaults) config.syncCodexSubagentDefaults = true;
732
+ else deleteConfigTopLevelKey(config, "syncCodexSubagentDefaults");
733
+ if (nextModel) config.injectionModel = nextModel;
734
+ else deleteConfigTopLevelKey(config, "injectionModel");
735
+ if (nextEffort) config.injectionEffort = nextEffort;
736
+ else deleteConfigTopLevelKey(config, "injectionEffort");
737
+ if (nextPrompt) config.injectionPrompt = nextPrompt;
738
+ else deleteConfigTopLevelKey(config, "injectionPrompt");
761
739
 
762
- saveConfigPreservingClaudeCode(config);
740
+ saveConfigPreservingClaudeCode(config);
741
+ return null;
742
+ });
743
+ if (refusal) return refusal;
763
744
  return jsonResponse({
764
745
  ok: true,
765
746
  multiAgentGuidanceEnabled: multiAgentGuidanceEnabled(config),
@@ -790,45 +771,57 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
790
771
  }
791
772
  const patch = body as Record<string, unknown>;
792
773
  const { isCodexReasoningEffort } = await import("../../reasoning-effort");
793
- const draft = { ...projectConfigRebaseProvenance(config) };
794
- const touched: (keyof OcxConfig)[] = [];
795
- for (const key of ["effortCap", "subagentEffortCap"] as const) {
796
- if (!Object.hasOwn(patch, key)) continue;
797
- const value = patch[key];
798
- if (value === null || value === "") deleteConfigTopLevelKey(draft, key);
799
- else if (typeof value === "string" && isCodexReasoningEffort(value)) draft[key] = value;
800
- else return jsonResponse({ error: "caps must be valid reasoning efforts or null" }, 400);
801
- touched.push(key);
802
- }
803
- if (Object.hasOwn(patch, "modelPinnedEfforts")) {
804
- const error = modelPinnedEffortsConfigError(patch.modelPinnedEfforts, "modelPinnedEfforts", true);
805
- if (error) return jsonResponse({ error }, 400);
806
- const pins = mergeModelPinnedEfforts(config.modelPinnedEfforts, patch.modelPinnedEfforts);
807
- if (pins) draft.modelPinnedEfforts = pins;
808
- else deleteConfigTopLevelKey(draft, "modelPinnedEfforts");
809
- touched.push("modelPinnedEfforts");
810
- }
811
- const validation = validateConfigCandidate(draft);
812
- if (!validation.ok) return jsonResponse({ error: validation.error }, 400);
813
- if (touched.some(key => !Object.hasOwn(draft, key)) && config.configRebaseProvenance !== undefined
814
- && parsedConfigRebaseDeletionKeys(config) === null) {
815
- return jsonResponse({ error: "unsupported config deletion provenance" }, 409);
816
- }
817
- const projected = projectConfigRebaseProvenance(draft);
818
- touched.push("configRebaseProvenance");
819
- const rollback = captureConfigTopLevelRollback(config, touched);
820
- try {
821
- for (const key of touched) {
822
- if (Object.hasOwn(projected, key)) Object.defineProperty(config, key, {
823
- value: projected[key], writable: true, enumerable: true, configurable: true,
824
- });
825
- else deleteConfigTopLevelKey(config, key);
774
+ const prepare = () => {
775
+ const draft = { ...projectConfigRebaseProvenance(config) };
776
+ const touched: (keyof OcxConfig)[] = [];
777
+ for (const key of ["effortCap", "subagentEffortCap"] as const) {
778
+ if (!Object.hasOwn(patch, key)) continue;
779
+ const value = patch[key];
780
+ if (value === null || value === "") deleteConfigTopLevelKey(draft, key);
781
+ else if (typeof value === "string" && isCodexReasoningEffort(value)) draft[key] = value;
782
+ else return jsonResponse({ error: "caps must be valid reasoning efforts or null" }, 400);
783
+ touched.push(key);
826
784
  }
827
- (deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode)(config);
828
- } catch (error) {
829
- rollback();
830
- throw error;
831
- }
785
+ if (Object.hasOwn(patch, "modelPinnedEfforts")) {
786
+ const error = modelPinnedEffortsConfigError(patch.modelPinnedEfforts, "modelPinnedEfforts", true);
787
+ if (error) return jsonResponse({ error }, 400);
788
+ const pins = mergeModelPinnedEfforts(config.modelPinnedEfforts, patch.modelPinnedEfforts);
789
+ if (pins) draft.modelPinnedEfforts = pins;
790
+ else deleteConfigTopLevelKey(draft, "modelPinnedEfforts");
791
+ touched.push("modelPinnedEfforts");
792
+ }
793
+ const validation = validateConfigCandidate(draft);
794
+ if (!validation.ok) return jsonResponse({ error: validation.error }, 400);
795
+ if (touched.some(key => !Object.hasOwn(draft, key)) && config.configRebaseProvenance !== undefined
796
+ && parsedConfigRebaseDeletionKeys(config) === null) {
797
+ return jsonResponse({ error: "unsupported config deletion provenance" }, 409);
798
+ }
799
+ const projected = projectConfigRebaseProvenance(draft);
800
+ touched.push("configRebaseProvenance");
801
+ return { touched, projected };
802
+ };
803
+ const checked = prepare();
804
+ if (checked instanceof Response) return checked;
805
+ const refusal = await settleConfigRoot(configRoot(), () => {
806
+ const prepared = prepare();
807
+ if (prepared instanceof Response) return prepared;
808
+ const { touched, projected } = prepared;
809
+ const rollback = captureConfigTopLevelRollback(config, touched);
810
+ try {
811
+ for (const key of touched) {
812
+ if (Object.hasOwn(projected, key)) Object.defineProperty(config, key, {
813
+ value: projected[key], writable: true, enumerable: true, configurable: true,
814
+ });
815
+ else deleteConfigTopLevelKey(config, key);
816
+ }
817
+ (deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode)(config);
818
+ } catch (error) {
819
+ rollback();
820
+ throw error;
821
+ }
822
+ return null;
823
+ });
824
+ if (refusal) return refusal;
832
825
  return jsonResponse({
833
826
  ok: true,
834
827
  effortCap: config.effortCap ?? null,
@@ -873,8 +866,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
873
866
  if (!body || typeof body !== "object" || Array.isArray(body)) {
874
867
  return jsonResponse({ error: "invalid JSON body" }, 400);
875
868
  }
876
- let nextModels = config.subagentModelFallback;
877
- let nextPollMs = config.subagentModelFallbackPollMs;
869
+ let nextModels: OcxConfig["subagentModelFallback"];
870
+ let nextPollMs: OcxConfig["subagentModelFallbackPollMs"];
878
871
  if ("models" in body) {
879
872
  if (!Array.isArray(body.models)) return jsonResponse({ error: "models must be an array" }, 400);
880
873
  const models: string[] = [];
@@ -900,11 +893,15 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
900
893
  return jsonResponse({ error: "pollMs must be an integer between 5000 and 600000" }, 400);
901
894
  }
902
895
  }
903
- if (nextModels !== undefined) config.subagentModelFallback = nextModels;
904
- else deleteConfigTopLevelKey(config, "subagentModelFallback");
905
- if (nextPollMs !== undefined) config.subagentModelFallbackPollMs = nextPollMs;
906
- else deleteConfigTopLevelKey(config, "subagentModelFallbackPollMs");
907
- saveConfigPreservingClaudeCode(config);
896
+ await settleConfigRoot(configRoot(), () => {
897
+ if (!("models" in body)) nextModels = config.subagentModelFallback;
898
+ if (!("pollMs" in body)) nextPollMs = config.subagentModelFallbackPollMs;
899
+ if (nextModels !== undefined) config.subagentModelFallback = nextModels;
900
+ else deleteConfigTopLevelKey(config, "subagentModelFallback");
901
+ if (nextPollMs !== undefined) config.subagentModelFallbackPollMs = nextPollMs;
902
+ else deleteConfigTopLevelKey(config, "subagentModelFallbackPollMs");
903
+ saveConfigPreservingClaudeCode(config);
904
+ });
908
905
  return jsonResponse({
909
906
  ok: true,
910
907
  models: config.subagentModelFallback ?? [],
@@ -944,9 +941,11 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
944
941
  // cannot grow config.json without bound.
945
942
  const excluded = [...new Set(raw as string[])].sort();
946
943
  if (excluded.length > 2000) return jsonResponse({ error: "excluded list is too large" }, 400);
947
- if (excluded.length === 0) deleteConfigTopLevelKey(config, "grokExcludedModels");
948
- else config.grokExcludedModels = excluded;
949
- saveConfigPreservingClaudeCode(config);
944
+ await settleConfigRoot(configRoot(), () => {
945
+ if (excluded.length === 0) deleteConfigTopLevelKey(config, "grokExcludedModels");
946
+ else config.grokExcludedModels = excluded;
947
+ saveConfigPreservingClaudeCode(config);
948
+ });
950
949
  return jsonResponse({ ok: true, excluded });
951
950
  }
952
951
 
@@ -981,13 +980,19 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
981
980
  }
982
981
  }
983
982
  if (url.pathname === "/api/claude-desktop" && req.method === "PUT") {
984
- let body: { profile?: unknown };
983
+ let body: { profile?: unknown; visibility?: unknown };
985
984
  try { body = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
986
985
  try {
987
986
  const { parseDesktopProfile, preserveDesktopAppliedState, reconcileDesktopProfile, sameProfileContent } = await import("../../claude/desktop-profile");
988
987
  const parsed = parseDesktopProfile(body.profile);
989
988
  const initial = loadConfig();
990
989
  const current = await buildClaudeDesktopState(initial);
990
+ // #7702: absent keeps the stored selection, null clears it (list every model).
991
+ const { parseDesktopModelVisibility, desktopRouteVisible, readDesktopModelVisibility, sameDesktopModelVisibility } = await import("../../claude/desktop-model-visibility");
992
+ const visibility = body.visibility === undefined || body.visibility === null ? body.visibility : parseDesktopModelVisibility(body.visibility);
993
+ if (visibility && !current.models.some(model => model.available && desktopRouteVisible(visibility, model.route))) {
994
+ throw new Error("Claude Desktop needs at least one visible available model");
995
+ }
991
996
  const availableRoutes = new Set(current.models.filter(item => item.available).map(item => item.route));
992
997
  for (const route of Object.keys(parsed.assignments)) {
993
998
  if (!current.profile.assignments[route] && !availableRoutes.has(route)) {
@@ -1014,17 +1019,40 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1014
1019
  const state = await buildClaudeDesktopState(initial, editable);
1015
1020
  const rebuilt = reconcileDesktopProfile(state.profile, state.models);
1016
1021
  const expectedProfile = initial.claudeCode?.desktopProfile;
1017
- const outcome = mutatePersistedConfig<OcxConfig["claudeCode"] | null>(persisted => {
1018
- const latest = persisted.claudeCode?.desktopProfile;
1019
- if ((latest == null) !== (expectedProfile == null)
1020
- || (latest && expectedProfile && !sameProfileContent(latest, expectedProfile))) {
1021
- return { changed: false, value: null };
1022
+ const outcome = await settleConfigRoot(configRoot(), () => {
1023
+ const outcome = mutatePersistedConfig<OcxConfig["claudeCode"] | null>(persisted => {
1024
+ const latest = persisted.claudeCode?.desktopProfile;
1025
+ if ((latest == null) !== (expectedProfile == null)
1026
+ || (latest && expectedProfile && !sameProfileContent(latest, expectedProfile))) {
1027
+ return { changed: false, value: null };
1028
+ }
1029
+ if (visibility !== undefined && !sameDesktopModelVisibility(
1030
+ readDesktopModelVisibility(persisted.claudeCode), readDesktopModelVisibility(initial.claudeCode),
1031
+ )) return { changed: false, value: null };
1032
+ persisted.claudeCode = {
1033
+ ...(persisted.claudeCode ?? {}),
1034
+ desktopProfile: preserveDesktopAppliedState(latest ?? current.profile, rebuilt),
1035
+ };
1036
+ if (visibility) persisted.claudeCode.desktopModelVisibility = visibility;
1037
+ else if (visibility === null) delete persisted.claudeCode.desktopModelVisibility;
1038
+ return { changed: true, value: structuredClone(persisted.claudeCode) };
1039
+ });
1040
+ if (outcome.status !== "unavailable" && outcome.value !== null) {
1041
+ adoptPersistedClaudeCode(config, outcome.value);
1042
+ // An unarmed live snapshot may prefer its old marker during reconciliation.
1043
+ // Pin the field this route just committed while leaving other live leaves intact.
1044
+ if (outcome.value?.desktopProfile) {
1045
+ config.claudeCode = {
1046
+ ...(config.claudeCode ?? {}),
1047
+ desktopProfile: structuredClone(outcome.value.desktopProfile),
1048
+ };
1049
+ }
1050
+ if (visibility !== undefined && config.claudeCode) {
1051
+ if (outcome.value?.desktopModelVisibility) config.claudeCode.desktopModelVisibility = structuredClone(outcome.value.desktopModelVisibility);
1052
+ else delete config.claudeCode.desktopModelVisibility;
1053
+ }
1022
1054
  }
1023
- persisted.claudeCode = {
1024
- ...(persisted.claudeCode ?? {}),
1025
- desktopProfile: preserveDesktopAppliedState(latest ?? current.profile, rebuilt),
1026
- };
1027
- return { changed: true, value: structuredClone(persisted.claudeCode) };
1055
+ return outcome;
1028
1056
  });
1029
1057
  if (outcome.status === "unavailable" && outcome.reason !== "conflict") {
1030
1058
  return jsonResponse({ error: "Claude Desktop profile could not be saved (config " + outcome.reason + ")" }, 500);
@@ -1032,23 +1060,17 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1032
1060
  if (outcome.status === "unavailable" || outcome.value === null) {
1033
1061
  return jsonResponse({ error: "Claude Desktop profile changed during save" }, 409);
1034
1062
  }
1035
- adoptPersistedClaudeCode(config, outcome.value);
1036
- // An unarmed live snapshot may prefer its old marker during reconciliation.
1037
- // Pin the field this route just committed while leaving other live leaves intact.
1038
- if (outcome.value?.desktopProfile) {
1039
- config.claudeCode = {
1040
- ...(config.claudeCode ?? {}),
1041
- desktopProfile: structuredClone(outcome.value.desktopProfile),
1042
- };
1043
- }
1044
1063
  const saved = await buildClaudeDesktopState(config);
1045
1064
  const runtimePort = managementInferencePort(ctx);
1046
1065
  return jsonResponse({ ok: true, ...saved, port: runtimePort });
1047
1066
  } catch (error) {
1067
+ if (error instanceof WindowsSecretAclSettleTimeoutError) return jsonResponse({ error: "Could not save settings", code: "write_failed", diagnostic: { stage: "ca", cause: "ETIMEDOUT" } }, 500);
1048
1068
  return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
1049
1069
  }
1050
1070
  }
1051
1071
  if (url.pathname === "/api/claude-desktop/apply" && req.method === "POST") {
1072
+ let committedIntent = false, savedProfile = false, pickerDisabled = false;
1073
+ let appliedMode: "first-party" | "gateway" | undefined, appliedPath = "", modeCommitted = false;
1052
1074
  try {
1053
1075
  // #859: the CLI delegates here so the registry is built in the serving
1054
1076
  // process. `mode` selects the Desktop mode: `first-party` (default when the
@@ -1062,7 +1084,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1062
1084
  rethrowManagementBodyTooLarge(error);
1063
1085
  return jsonResponse({ error: "invalid JSON body" }, 400);
1064
1086
  }
1065
- const { resolveClaudeDesktopApplyMode, observeClaudeDesktopMode, applyDesktopFirstParty, withFirstPartySecretsSettled, captureDesktopFirstPartyRollback, removeDesktopFirstPartySettled } = await import("../../claude/desktop-first-party");
1087
+ const { resolveClaudeDesktopApplyMode, observeClaudeDesktopMode, applyDesktopFirstParty, withFirstPartySecretsSettled, captureDesktopFirstPartyRollback, rollbackDesktopFirstPartySettled, removeDesktopFirstPartySettled } = await import("../../claude/desktop-first-party");
1066
1088
  const requested = (parsed as { mode?: unknown } | null)?.mode;
1067
1089
  let desktopMode: "first-party" | "gateway" = resolveClaudeDesktopApplyMode(config, observeClaudeDesktopMode(config));
1068
1090
  if (requested !== undefined) {
@@ -1097,16 +1119,21 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1097
1119
  const configured = claudeInterceptProxyPort(config, config.port ?? 10100);
1098
1120
  if (started.state.proxyPort !== configured) return jsonResponse({ ok: false, code: "port_mismatch", bound: started.state.proxyPort, configured }, 409);
1099
1121
  const { setIntegrationEnabled } = await import("../../codex/desired-state");
1100
- const desired = setIntegrationEnabled("claude-desktop", true);
1101
- if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
1102
- mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
1122
+ const desired = await withFirstPartySecretsSettled(configRoot(), () => {
1123
+ const result = setIntegrationEnabled("claude-desktop", true);
1124
+ if (result.ok) mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
1125
+ return result;
1126
+ });
1127
+ if (!desired.ok) return "path" in desired ? jsonResponse({ ...desired, code: desired.reason }, 500)
1128
+ : jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
1129
+ committedIntent = true;
1103
1130
  const { pickerPreferenceOn, pickerStatusFor, runPickerTransition } = await import("./claude-desktop-picker-routes");
1104
1131
  // The whole switch runs under the picker lock, in today's order: env first, then gateway cleanup.
1105
1132
  return await runPickerTransition(config, async ops => {
1106
1133
  const { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot } = await import("../../claude/desktop-3p");
1107
- const rollback = captureDesktopFirstPartyRollback(config);
1108
- const { getConfigDir, withConfigDirHardeningSettled } = await import("../../config/paths");
1109
- const applied = await withFirstPartySecretsSettled(getConfigDir(), () => applyDesktopFirstParty(config));
1134
+ let rollback!: ReturnType<typeof captureDesktopFirstPartyRollback>;
1135
+ const { getConfigDir } = await import("../../config/paths");
1136
+ const applied = await withFirstPartySecretsSettled(getConfigDir(), () => { rollback = captureDesktopFirstPartyRollback(config); return applyDesktopFirstParty(config); });
1110
1137
  if (!applied.ok) {
1111
1138
  const { firstPartyRefusalMessage } = await import("./native-integration-routes");
1112
1139
  return jsonResponse({
@@ -1117,22 +1144,32 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1117
1144
  ...(applied.diagnostic ? { diagnostic: applied.diagnostic } : {}),
1118
1145
  }, applied.reason === "foreign_env" || applied.reason === "intercept_disabled" ? 409 : 500);
1119
1146
  }
1147
+ appliedMode = "first-party"; appliedPath = applied.path;
1148
+ let gatewayRemoved = false;
1149
+ try {
1120
1150
  // Remove the gateway only after the replacement env was written.
1121
1151
  const appliedFingerprint = config.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
1122
1152
  const library = inspectDesktop3pConfigLibrary({ appliedFingerprint });
1123
- let gatewayRemoved = false;
1124
1153
  if (library.kind === "gateway_ours" || library.kind === "gateway_drifted") {
1125
- const removed = (deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint, replaceWhileEnabled: true });
1154
+ let removed: ReturnType<typeof removeDesktop3pStandardPivot>;
1155
+ try { removed = await settleConfigRoot(configRoot(), () => (deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint: readConfigForAdmittedMutation().claudeCode?.desktopProfile?.appliedFingerprint ?? null, replaceWhileEnabled: true })); }
1156
+ catch (error) {
1157
+ removed = { ok: false, changed: false, kind: "write_failed", libraryPath: library.libraryPath,
1158
+ reason: error instanceof WindowsSecretAclSettleTimeoutError ? "acl_settlement_timeout" : "desktop_mutation_failed" };
1159
+ }
1126
1160
  if (!removed.ok) {
1127
- const restored = removed.changed || !applied.changed || await withConfigDirHardeningSettled(getConfigDir(), rollback);
1161
+ const restored = removed.changed || !applied.changed || await rollbackDesktopFirstPartySettled(getConfigDir(), rollback).catch(() => false);
1162
+ if (!removed.changed && restored && applied.changed) appliedMode = undefined;
1128
1163
  const modeSaved = !removed.changed || (await persistDesktopModeField(config, "first-party")).ok;
1129
1164
  const warning = [restored ? "" : "first-party settings rollback did not complete",
1130
1165
  modeSaved ? "" : "first-party is active but its mode marker was not saved"].filter(Boolean).join("; ");
1131
1166
  return jsonResponse({
1132
1167
  error: removed.kind === "cleanup_incomplete"
1133
1168
  ? "Claude Desktop now points at standard mode, but gateway credential cleanup is incomplete; the first-party connection remains active."
1169
+ : !restored ? "The gateway profile could not be removed and first-party settings rollback did not complete; the mode switch is incomplete."
1134
1170
  : "The gateway profile could not be removed safely, so first-party mode was not applied.",
1135
1171
  code: "claude_desktop_gateway_removal_failed",
1172
+ desiredEnabled: true, saved: removed.changed && modeSaved, applied: removed.changed || !restored || !applied.changed,
1136
1173
  ...(warning ? { warning } : {}),
1137
1174
  reason: removed.reason ?? removed.kind,
1138
1175
  ...(removed.residualPaths ? { residualPaths: removed.residualPaths } : {}),
@@ -1141,6 +1178,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1141
1178
  gatewayRemoved = removed.changed;
1142
1179
  }
1143
1180
  const modeSaved = await persistDesktopModeField(config, "first-party");
1181
+ modeCommitted = modeSaved.ok;
1144
1182
  const { firstPartyAccountRisk } = await import("../../claude/desktop-risk");
1145
1183
  // Picker mode is on by default in first-party; only a committed mode turns it on.
1146
1184
  const picker = modeSaved.ok && pickerPreferenceOn(loadConfig())
@@ -1161,28 +1199,43 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1161
1199
  picker,
1162
1200
  ...(modeSaved.ok ? {} : { warning: `First-party env was applied, but the mode marker was not saved (${modeSaved.reason}).` }),
1163
1201
  });
1202
+ } catch {
1203
+ const retained = gatewayRemoved || modeCommitted;
1204
+ const restored = retained || !applied.changed || await rollbackDesktopFirstPartySettled(getConfigDir(), rollback).catch(() => false);
1205
+ return jsonResponse({ error: "First-party mode follow-up did not complete", code: "claude_desktop_gateway_removal_failed",
1206
+ desiredEnabled: true, saved: modeCommitted, applied: retained || !restored || !applied.changed,
1207
+ warning: retained ? "First-party settings remain applied."
1208
+ : restored ? "First-party settings were rolled back; Desktop enable intent remains saved." : "first-party settings rollback did not complete" }, 500);
1209
+ }
1164
1210
  });
1165
1211
  }
1166
1212
  const { setIntegrationEnabled, claudeDesktopIntegrationEnabled } = await import("../../codex/desired-state");
1167
- const desired = setIntegrationEnabled("claude-desktop", true);
1213
+ const desired = await settleConfigRoot(configRoot(), () => {
1214
+ const result = setIntegrationEnabled("claude-desktop", true);
1215
+ if (result.ok) mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
1216
+ return result;
1217
+ });
1168
1218
  if (!desired.ok) return jsonResponse({ error: desired.message }, desired.retryable ? 409 : 500);
1219
+ committedIntent = true;
1169
1220
  // Disk now says ON; the reused server snapshot must agree, or the native
1170
1221
  // GET reports OFF and a later whole-snapshot save undoes this transition.
1171
- mirrorDesiredEnabledOntoSnapshot(config, "claude-desktop", true);
1222
+ const expectedProfile = structuredClone(loadConfig().claudeCode?.desktopProfile);
1172
1223
  const state = await buildClaudeDesktopState(config, profileOverride);
1173
1224
  // `setIntegrationEnabled` above wrote desired ON to DISK; it does not touch
1174
1225
  // this long-lived server snapshot. Saving the snapshot wholesale would carry
1175
1226
  // its stale `clientIntegrations` back over that write and turn the enable
1176
1227
  // action into an immediate self-cancelling OFF — the guard below would then
1177
1228
  // refuse the apply it was asked to perform. Persist ONLY the profile field.
1178
- const profileSaved = persistDesktopProfileField(config, state.profile);
1229
+ const profileSaved = await persistDesktopProfileField(config, state.profile, expectedProfile);
1179
1230
  if (!profileSaved.ok) {
1180
1231
  return jsonResponse({
1181
1232
  error: `Claude Desktop profile could not be saved (${profileSaved.reason}); nothing was applied.`,
1182
1233
  saved: false,
1183
1234
  applied: false,
1235
+ desiredEnabled: true,
1184
1236
  }, profileSaved.reason === "conflict" ? 409 : 500);
1185
1237
  }
1238
+ savedProfile = true;
1186
1239
  const { writeDesktop3pConfig } = await import("../../claude/desktop-3p");
1187
1240
  const { desktopVisibleNativeSlugs } = await import("../../codex/catalog");
1188
1241
  const routed = state.models
@@ -1195,7 +1248,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1195
1248
  const outcome = await runPickerTransition(config, async ops => {
1196
1249
  // State construction can await catalog work; never write from the stale
1197
1250
  // config captured before that await if another request turned Desktop off.
1198
- const latest = loadConfig();
1251
+ let latest = loadConfig();
1199
1252
  if (!claudeDesktopIntegrationEnabled(latest)) {
1200
1253
  return { response: jsonResponse({
1201
1254
  error: "Claude Desktop apply was cancelled because the desired state changed to off.",
@@ -1208,7 +1261,11 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1208
1261
  }
1209
1262
  // Picker mode belongs to first-party: stop terminating claude.ai before the gateway lands.
1210
1263
  const pickerOff = await ops.disableLocked({ persist: false });
1211
- const result = (deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
1264
+ pickerDisabled = true;
1265
+ const result = await settleConfigRoot(configRoot(), () => {
1266
+ latest = readConfigForAdmittedMutation();
1267
+ if (!claudeDesktopIntegrationEnabled(latest) || JSON.stringify(latest.claudeCode?.desktopProfile) !== JSON.stringify(state.profile)) return null;
1268
+ return (deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
1212
1269
  managementInferencePort({ config: latest, deps }),
1213
1270
  [...desktopVisibleNativeSlugs(latest)],
1214
1271
  routed,
@@ -1216,9 +1273,14 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1216
1273
  mode,
1217
1274
  state.profile,
1218
1275
  nativeContextLimits(latest),
1219
- );
1276
+ ); });
1277
+ if (result === null) return { response: jsonResponse({ error: "Desktop configuration changed during apply", code: "config_changed", saved: true, applied: false }, 409) };
1220
1278
  if (!result.written) return { response: jsonResponse({ error: result.reason ?? "Claude Desktop apply failed", saved: true, path: result.path }, 500) };
1221
- const committed = persistCommittedDesktopGateway(config, state.profile, result.fingerprint);
1279
+ appliedMode = "gateway"; appliedPath = result.path;
1280
+ const committed = await settleConfigRoot(configRoot(), () => persistCommittedDesktopGateway(config, state.profile, result.fingerprint)).catch(() => {
1281
+ return { ok: false, reason: "unavailable" } as const;
1282
+ });
1283
+ modeCommitted = committed.ok;
1222
1284
  const modeWarning = committed.ok ? undefined : `Gateway applied, but its mode/profile state was not saved (${committed.reason}).`;
1223
1285
  // The durable marker describes the committed gateway even if old-mode cleanup fails.
1224
1286
  const firstPartyRemoved = await removeDesktopFirstPartySettled(loadConfig);
@@ -1257,6 +1319,13 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1257
1319
  });
1258
1320
  } catch (error) {
1259
1321
  rethrowManagementBodyTooLarge(error);
1322
+ if (committedIntent || error instanceof WindowsSecretAclSettleTimeoutError) return jsonResponse({
1323
+ error: error instanceof WindowsSecretAclSettleTimeoutError ? "Config-directory ACL settlement timed out" : "Desktop apply did not complete", code: "write_failed",
1324
+ ...(error instanceof WindowsSecretAclSettleTimeoutError ? { diagnostic: { stage: "ca", cause: "ETIMEDOUT" } } : {}),
1325
+ ...(committedIntent ? { desiredEnabled: true, saved: appliedMode ? modeCommitted : savedProfile, applied: appliedMode !== undefined,
1326
+ ...(appliedMode ? { mode: appliedMode, path: appliedPath } : {}),
1327
+ warning: `Desktop enable intent${savedProfile ? " and profile were" : " was"} saved; Desktop ${appliedMode ? "was applied but follow-up did not complete" : "was not applied"}.${pickerDisabled ? " Picker disable was already attempted." : ""}` } : {}),
1328
+ }, 500);
1260
1329
  return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
1261
1330
  }
1262
1331
  }
@@ -1337,6 +1406,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1337
1406
  savedFingerprint,
1338
1407
  onDiskFingerprint: observed.fingerprint ?? null,
1339
1408
  configPath: observed.selectedProfilePath,
1409
+ // The list Desktop runs now (#7702), so the dashboard can count and diff against it.
1410
+ appliedModels: gatewayApplied ? (await import("../../claude/desktop-model-visibility")).readAppliedDesktopModels(observed.selectedProfilePath) : null,
1340
1411
  stale,
1341
1412
  // Tri-state by ID match, independent of profile health: null =
1342
1413
  // undeterminable (no/unreadable metadata or no appliedId); a readable
@@ -1364,7 +1435,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1364
1435
  const state = await buildClaudeDesktopState(config);
1365
1436
  const availableRoutes = new Set(state.models.filter(model => model.available).map(model => model.route));
1366
1437
  let rejection: string | null = null;
1367
- const outcome = mutatePersistedConfig<OcxConfig["claudeCode"]>(persisted => {
1438
+ const outcome = await settleConfigRoot(configRoot(), () => {
1439
+ const outcome = mutatePersistedConfig<OcxConfig["claudeCode"]>(persisted => {
1368
1440
  const current = readInterceptBindings(persisted.claudeCode);
1369
1441
  const next = applyInterceptBindingPatch(current, patch, availableRoutes);
1370
1442
  if (!next.ok) {
@@ -1381,10 +1453,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1381
1453
  persisted.claudeCode = claudeCode;
1382
1454
  return { changed: true, value: structuredClone(persisted.claudeCode) };
1383
1455
  });
1384
- if (rejection) return jsonResponse({ error: rejection }, 400);
1385
- if (outcome.status === "unavailable") {
1386
- return jsonResponse({ error: `First-party bindings could not be saved (config ${outcome.reason})` }, outcome.reason === "conflict" ? 409 : 500);
1387
- }
1456
+ if (!rejection && outcome.status !== "unavailable") {
1388
1457
  adoptPersistedClaudeCode(config, outcome.value);
1389
1458
  // Pin the committed leaf: an unarmed live snapshot may otherwise keep its old intercept block.
1390
1459
  const committedIntercept = outcome.value?.intercept;
@@ -1392,8 +1461,16 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1392
1461
  if (committedIntercept) liveClaudeCode.intercept = structuredClone(committedIntercept);
1393
1462
  else delete liveClaudeCode.intercept;
1394
1463
  config.claudeCode = liveClaudeCode;
1464
+ }
1465
+ return outcome;
1466
+ });
1467
+ if (rejection) return jsonResponse({ error: rejection }, 400);
1468
+ if (outcome.status === "unavailable") {
1469
+ return jsonResponse({ error: `First-party bindings could not be saved (config ${outcome.reason})` }, outcome.reason === "conflict" ? 409 : 500);
1470
+ }
1395
1471
  return jsonResponse({ ok: true, modelBindings: readInterceptBindings(config.claudeCode) });
1396
1472
  } catch (error) {
1473
+ if (error instanceof WindowsSecretAclSettleTimeoutError) return jsonResponse({ error: "Could not save settings", code: "write_failed", diagnostic: { stage: "ca", cause: "ETIMEDOUT" } }, 500);
1397
1474
  return jsonResponse({ error: error instanceof Error ? error.message : String(error) }, 400);
1398
1475
  }
1399
1476
  }
@@ -1587,7 +1664,8 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1587
1664
  pinnedMode: "first-party" | "gateway" | undefined; retainedAmbiguous: boolean };
1588
1665
  let outcome: ReturnType<typeof mutatePersistedConfig<FirstPartyMutation>>;
1589
1666
  try {
1590
- outcome = mutatePersistedConfig<FirstPartyMutation>(persisted => {
1667
+ outcome = await settleConfigRoot(configRoot(), () => {
1668
+ const outcome = mutatePersistedConfig<FirstPartyMutation>(persisted => {
1591
1669
  if (body.cliFirstParty) {
1592
1670
  if (!claudeInterceptEnabled(persisted)) return { changed: false, value: {
1593
1671
  refusal: { error: "Claude intercept is disabled", code: "disabled" as const } } };
@@ -1617,20 +1695,27 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1617
1695
  const retainedAmbiguous = !body.cliFirstParty && previous.value && pinnedMode === "first-party";
1618
1696
  return { changed: true, value: { claudeCode: structuredClone(persisted.claudeCode), previous, pinnedMode, retainedAmbiguous } };
1619
1697
  });
1620
- } catch { return jsonResponse({ error: "Could not save Claude settings", code: "write_failed" }, 500); }
1621
- if (outcome.status === "unavailable") return jsonResponse({ error: "Could not save Claude settings", code: "write_failed" }, 500);
1622
- const committed = outcome.value;
1623
- if ("refusal" in committed) return jsonResponse(committed.refusal, 409);
1698
+ if (outcome.status !== "unavailable" && !("refusal" in outcome.value)) {
1699
+ const committed = outcome.value;
1624
1700
  adoptPersistedClaudeCode(config, committed.claudeCode);
1625
1701
  const live = { ...(config.claudeCode ?? {}) };
1626
1702
  if (body.cliFirstParty) live.cliFirstParty = true; else delete live.cliFirstParty;
1627
1703
  if (committed.pinnedMode) live.desktopMode = committed.pinnedMode;
1628
1704
  config.claudeCode = live;
1705
+ }
1706
+ return outcome;
1707
+ });
1708
+ } catch (error) { return jsonResponse({ error: "Could not save Claude settings", code: "write_failed",
1709
+ ...(error instanceof WindowsSecretAclSettleTimeoutError ? { diagnostic: { stage: "ca", cause: "ETIMEDOUT" } } : {}) }, 500); }
1710
+ if (outcome.status === "unavailable") return jsonResponse({ error: "Could not save Claude settings", code: "write_failed" }, 500);
1711
+ const committed = outcome.value;
1712
+ if ("refusal" in committed) return jsonResponse(committed.refusal, 409);
1629
1713
  let result: ReturnType<typeof reconcileClaudeFirstPartySettings> | undefined;
1630
1714
  const { getConfigDir, withConfigDirHardeningSettled } = await import("../../config/paths");
1631
- try { result = await withFirstPartySecretsSettled(getConfigDir(), () =>
1632
- (deps.reconcileClaudeFirstPartySettings ?? reconcileClaudeFirstPartySettings)(config,
1633
- firstPartyDesired(config, observeClaudeDesktopMode(config)))); }
1715
+ try { result = await withFirstPartySecretsSettled(getConfigDir(), () => {
1716
+ if (body.cliFirstParty) restoreSettings = captureDesktopFirstPartyRollback(config);
1717
+ return (deps.reconcileClaudeFirstPartySettings ?? reconcileClaudeFirstPartySettings)(config,
1718
+ firstPartyDesired(config, observeClaudeDesktopMode(config))); }); }
1634
1719
  catch { /* An unexpected settings failure is mapped after conditional rollback. */ }
1635
1720
  if (!result?.ok) {
1636
1721
  let settingsRestored = true;
@@ -1638,7 +1723,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1638
1723
  try { settingsRestored = result?.reason === "ca_unavailable" || await withConfigDirHardeningSettled(getConfigDir(), () => restoreSettings?.() ?? false); } catch { settingsRestored = false; }
1639
1724
  let rollback: ReturnType<typeof mutatePersistedConfig<OcxConfig["claudeCode"]>>;
1640
1725
  try {
1641
- rollback = mutatePersistedConfig(persisted => {
1726
+ rollback = await settleConfigRoot(configRoot(), () => mutatePersistedConfig(persisted => {
1642
1727
  const block = { ...(persisted.claudeCode ?? {}) };
1643
1728
  if (block.cliFirstParty === true) {
1644
1729
  if (committed.previous.present) block.cliFirstParty = committed.previous.value;
@@ -1648,10 +1733,10 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1648
1733
  delete block.desktopMode;
1649
1734
  persisted.claudeCode = block;
1650
1735
  return { changed: true, value: structuredClone(block) };
1651
- });
1652
- } catch { return jsonResponse({ error: "Claude settings rollback failed", code: "write_failed",
1736
+ }));
1737
+ } catch { return jsonResponse({ error: "Claude settings rollback failed", code: "write_failed", cliFirstParty: true,
1653
1738
  warnings: ["settings_rollback_incomplete"] }, 500); }
1654
- if (rollback.status === "unavailable") return jsonResponse({ error: "Claude settings rollback failed", code: "write_failed",
1739
+ if (rollback.status === "unavailable") return jsonResponse({ error: "Claude settings rollback failed", code: "write_failed", cliFirstParty: true,
1655
1740
  warnings: ["settings_rollback_incomplete"] }, 500);
1656
1741
  adoptPersistedClaudeCode(config, rollback.value);
1657
1742
  }
@@ -1675,274 +1760,95 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1675
1760
  ...(residual ? ["settings_residual"] : []),
1676
1761
  ] });
1677
1762
  }
1678
- const instanceError = anthropicSidecarPatchError(config, body, true);
1679
- if (instanceError) return jsonResponse({ error: instanceError }, 400);
1680
- for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
1681
- const section = body[field];
1682
- if (section === undefined || section === null) continue;
1683
- if (!isPlainObject(section)) return jsonResponse({ error: `${field} must be an object or null` }, 400);
1684
- if (section.enabled !== undefined && typeof section.enabled !== "boolean") {
1685
- return jsonResponse({ error: `${field}.enabled must be a boolean` }, 400);
1686
- }
1687
- // Both overrides now speak their full unions (roadmap 060 web, 170
1688
- // vision revised). Vision's third arm is "routed" (loopback through the
1689
- // proxy's own router), never exa: exa is not an LLM, and accepting an
1690
- // unknown literal would persist a backend the vision resolver reads as
1691
- // unset (review F1's failure mode).
1692
- const allowedBackends = field === "webSearchSidecar"
1693
- ? ["openai", "anthropic", "xai", "gemini", "exa"]
1694
- : ["openai", "anthropic", "routed"];
1695
- if (section.backend !== undefined && section.backend !== null
1696
- && !allowedBackends.includes(section.backend as string)) {
1697
- return jsonResponse({ error: `${field}.backend must be ${allowedBackends.join(", ")}, or null` }, 400);
1698
- }
1699
- if (section.model !== undefined && typeof section.model !== "string") {
1700
- return jsonResponse({ error: `${field}.model must be a string` }, 400);
1701
- }
1702
- // Vision override only: reject a model we can prove is blind. Unknown ids stay
1703
- // allowed. Shares one policy module with /api/sidecar-settings so the two
1704
- // gates cannot drift.
1705
- if (field === "visionSidecar" && typeof section.model === "string" && section.model !== "") {
1706
- const requested = section.model;
1707
- const candidates = await visionCandidateRows({ ...config, visionSidecar: {
1708
- ...config.visionSidecar, ...sidecarSettingsAfterPatch(config.claudeCode?.visionSidecar, section),
1709
- } });
1710
- const hint = section.backend === "anthropic" || section.backend === "openai"
1711
- || section.backend === "routed"
1712
- ? section.backend
1713
- : config.claudeCode?.visionSidecar?.backend;
1714
- // Same coherence rule as /api/sidecar-settings (roadmap 170 r2).
1715
- const effectiveBackend = hint ?? "openai";
1716
- const namespaced = requested.includes("/");
1717
- if (namespaced && effectiveBackend !== "routed") {
1718
- return jsonResponse({ error: `visionSidecar.model "${requested}" is provider-namespaced; it requires backend "routed"` }, 400);
1719
- }
1720
- if (!namespaced && effectiveBackend === "routed") {
1721
- return jsonResponse({ error: `visionSidecar.backend "routed" requires a provider-namespaced model ("provider/model"); got "${requested}"` }, 400);
1722
- }
1723
- if (visionDescriberIsProvablyBlind(config, requested, candidates, hint)) {
1724
- return jsonResponse(visionDescriberRejection("visionSidecar.model", requested, config, candidates), 400);
1725
- }
1726
- }
1727
- // Web-search override: membership gate (#2188). The executor set is closed,
1728
- // so an id outside (runnable candidates ∪ auth slots) can never run. Same
1729
- // module as /api/sidecar-settings — a gate on one route and a stale copy on
1730
- // the other is no gate at all.
1731
- if (field === "webSearchSidecar"
1732
- && (section.model !== undefined || section.backend !== undefined || section.anthropicInstance !== undefined)) {
1733
- const stored = config.claudeCode?.webSearchSidecar;
1734
- // Validate against the SUBMITTED backend across the whole union, not
1735
- // just openai/anthropic (#2457). allowedBackends above already refused
1736
- // unknown literals; Array.includes does not narrow, hence the cast.
1737
- // null keeps its own meaning here — drop the override and inherit the
1738
- // global backend — which is deliberately NOT the sidecar-settings rule.
1739
- const submittedBackend = section.backend;
1740
- const effectiveBackend = typeof submittedBackend === "string"
1741
- && allowedBackends.includes(submittedBackend)
1742
- ? submittedBackend as WebSearchBackend
1743
- : submittedBackend === null
1744
- ? config.webSearchSidecar?.backend ?? "openai"
1745
- : stored?.backend ?? config.webSearchSidecar?.backend ?? "openai";
1746
- const effectiveModel = section.model === ""
1747
- ? config.webSearchSidecar?.model
1748
- : typeof section.model === "string"
1749
- ? section.model
1750
- : stored?.model ?? config.webSearchSidecar?.model;
1751
- const candidates = await webSearchCandidateRows({ ...config, webSearchSidecar: {
1752
- ...config.webSearchSidecar, ...sidecarSettingsAfterPatch(config.claudeCode?.webSearchSidecar, section),
1753
- } });
1754
- if (effectiveModel && webSearchModelIsRejected(effectiveBackend, effectiveModel, candidates)) {
1755
- return jsonResponse(webSearchModelRejection(
1756
- "webSearchSidecar.model",
1757
- effectiveBackend,
1758
- effectiveModel,
1759
- candidates,
1760
- ), 400);
1761
- }
1762
- }
1763
- }
1764
- const next = { ...(config.claudeCode ?? {}) };
1765
- for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
1766
- const section = body[field];
1767
- if (section === undefined) continue;
1768
- if (section === null || Object.keys(section as Record<string, unknown>).length === 0) {
1769
- delete next[field];
1770
- continue;
1771
- }
1772
- // The per-field validation above guarantees vision only ever carries the two-member
1773
- // union; the cast is the loop's shared-shape compromise, not a wider write path.
1774
- const requested = section as { enabled?: boolean; backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa" | null; model?: string; anthropicInstance?: AnthropicInstanceId | null };
1775
- const override = { ...next[field] } as NonNullable<OcxClaudeCodeConfig[typeof field]>;
1776
- if (requested.enabled !== undefined) override.enabled = requested.enabled;
1777
- if (requested.anthropicInstance === null) delete override.anthropicInstance;
1778
- else if (isAnthropicInstanceId(requested.anthropicInstance)) override.anthropicInstance = requested.anthropicInstance;
1779
- if (requested.backend === null) delete override.backend;
1780
- else if (requested.backend !== undefined) override.backend = requested.backend as never;
1781
- if (requested.model === "") delete override.model;
1782
- else if (requested.model !== undefined) override.model = requested.model;
1783
- // Indexed write across the field union collapses to an intersection; runtime
1784
- // validation above already guarantees the per-field shape.
1785
- if (Object.keys(override).length > 0) next[field] = override as never;
1786
- else delete next[field];
1787
- }
1788
- if (body.enabled !== undefined) {
1789
- if (typeof body.enabled !== "boolean") return jsonResponse({ error: "enabled must be a boolean" }, 400);
1790
- next.enabled = body.enabled;
1791
- }
1792
- if (body.authMode !== undefined) {
1793
- // Three-state intent: "proxy" and "subscription" are stored literally and stick
1794
- // forever; "auto" DELETES the key so the mode is resolved from detected Claude
1795
- // auth on every launch. The 260720 round-trip contract survives as a superset —
1796
- // storing "subscription" literally is also backward-safe, since older readers
1797
- // only ever recognised "proxy".
1798
- if (body.authMode !== "proxy" && body.authMode !== "subscription" && body.authMode !== "auto") {
1799
- return jsonResponse({ error: "authMode must be \"auto\", \"proxy\", or \"subscription\"" }, 400);
1800
- }
1801
- if (body.authMode === "auto") delete next.authMode;
1802
- else next.authMode = body.authMode;
1803
- }
1804
- if (body.systemEnv !== undefined) {
1805
- if (typeof body.systemEnv !== "boolean") return jsonResponse({ error: "systemEnv must be a boolean" }, 400);
1806
- next.systemEnv = body.systemEnv;
1807
- }
1808
- if (body.alwaysEnableEffort !== undefined) {
1809
- if (typeof body.alwaysEnableEffort !== "boolean") return jsonResponse({ error: "alwaysEnableEffort must be a boolean" }, 400);
1810
- if (body.alwaysEnableEffort) next.alwaysEnableEffort = true;
1811
- else delete next.alwaysEnableEffort;
1812
- }
1813
- if (body.maxContextTokens !== undefined) {
1814
- // CONFIG-ONLY back-compat (GUI control removed — superseded by auto-context):
1815
- // null clears; otherwise a positive integer (devlog 136 B6).
1816
- if (body.maxContextTokens === null) {
1817
- delete next.maxContextTokens;
1818
- } else if (typeof body.maxContextTokens !== "number" || !Number.isInteger(body.maxContextTokens) || body.maxContextTokens <= 0) {
1819
- return jsonResponse({ error: "maxContextTokens must be a positive integer or null" }, 400);
1820
- } else {
1821
- next.maxContextTokens = body.maxContextTokens;
1822
- }
1823
- }
1824
- if (body.autoContext !== undefined) {
1825
- // Default-on boolean (devlog 260712 020): true = drop the key, false = store.
1826
- if (typeof body.autoContext !== "boolean") return jsonResponse({ error: "autoContext must be a boolean" }, 400);
1827
- if (body.autoContext) delete next.autoContext;
1828
- else next.autoContext = false;
1829
- }
1830
- if (body.contextAccounting !== undefined) {
1831
- // Sparse like autoContext (devlog/_plan/261009_claude_1m_default/030): "1m" is the default
1832
- // and drops the key; "200k" is the only stored value.
1833
- if (body.contextAccounting !== "1m" && body.contextAccounting !== "200k") {
1834
- return jsonResponse({ error: "contextAccounting must be \"1m\" or \"200k\"" }, 400);
1835
- }
1836
- if (body.contextAccounting === "200k") next.contextAccounting = "200k";
1837
- else delete next.contextAccounting;
1838
- }
1839
- if (body.injectAgents !== undefined) {
1840
- // Default-on boolean (devlog 260712 070): true = drop the key, false = store.
1841
- if (typeof body.injectAgents !== "boolean") return jsonResponse({ error: "injectAgents must be a boolean" }, 400);
1842
- if (body.injectAgents) delete next.injectAgents;
1843
- else next.injectAgents = false;
1844
- }
1845
- if (body.autoCompactWindow !== undefined) {
1846
- // null resets to the 350k default; otherwise the binary-accepted range
1847
- // 100_000..1_000_000 (2.1.207 pSo/yDs — audit 021 #1).
1848
- if (body.autoCompactWindow === null) {
1849
- delete next.autoCompactWindow;
1850
- } else if (typeof body.autoCompactWindow !== "number" || !Number.isInteger(body.autoCompactWindow) || body.autoCompactWindow < 100_000 || body.autoCompactWindow > 1_000_000) {
1851
- return jsonResponse({ error: "autoCompactWindow must be an integer between 100000 and 1000000, or null" }, 400);
1852
- } else {
1853
- next.autoCompactWindow = body.autoCompactWindow;
1854
- }
1855
- }
1856
- if (body.blockedSkills !== undefined) {
1857
- // null resets to the default (["claude-api"]); an array (possibly empty = off)
1858
- // must contain non-empty strings (devlog 060).
1859
- if (body.blockedSkills === null) {
1860
- delete next.blockedSkills;
1861
- } else if (!Array.isArray(body.blockedSkills) || body.blockedSkills.some(s => typeof s !== "string" || s.trim() === "")) {
1862
- return jsonResponse({ error: "blockedSkills must be an array of non-empty strings, or null" }, 400);
1863
- } else {
1864
- next.blockedSkills = (body.blockedSkills as string[]).map(s => s.trim());
1865
- }
1866
- }
1867
- if (body.tierModels !== undefined) {
1868
- // Family defaults also serve third-party callers that request native tier aliases.
1869
- if (body.tierModels === null) {
1870
- delete next.tierModels;
1871
- } else if (!isPlainObject(body.tierModels)) {
1872
- return jsonResponse({ error: "tierModels must be an object with string values, or null" }, 400);
1873
- } else {
1874
- for (const [tier, value] of Object.entries(body.tierModels)) {
1875
- if (typeof value !== "string") return jsonResponse({ error: `tierModels.${tier} must be a string` }, 400);
1876
- }
1877
- const tierModels = body.tierModels as Record<string, string>;
1878
- const tiers: Record<string, string> = {};
1879
- for (const tier of ["opus", "sonnet", "haiku", "fable"] as const) {
1880
- const value = tierModels[tier];
1881
- if (value !== undefined && value.trim() !== "") tiers[tier] = value.trim();
1882
- }
1883
- if (Object.keys(tiers).length > 0) next.tierModels = tiers;
1884
- else delete next.tierModels;
1885
- }
1886
- }
1887
- let nextFastMode = config.fastMode;
1888
- if (body.fastMode !== undefined) {
1889
- if (body.fastMode !== true && body.fastMode !== false && body.fastMode !== null) {
1890
- return jsonResponse({ error: "fastMode must be true, false, or null" }, 400);
1891
- }
1892
- nextFastMode = body.fastMode === null ? undefined : body.fastMode;
1893
- }
1894
- for (const field of ["model", "smallFastModel", "classifierModel"] as const) {
1895
- const value = body[field];
1896
- if (value === undefined) continue;
1897
- if (typeof value !== "string") return jsonResponse({ error: `${field} must be a string` }, 400);
1898
- if (value.trim() === "") delete next[field];
1899
- else next[field] = value.trim();
1900
- }
1901
- if (body.classifierFallbacks !== undefined) {
1902
- if (body.classifierFallbacks === null) {
1903
- delete next.classifierFallbacks;
1904
- } else {
1905
- if (!Array.isArray(body.classifierFallbacks)) {
1906
- return jsonResponse({ error: "classifierFallbacks must be an array of strings, or null" }, 400);
1907
- }
1908
- const list: string[] = [];
1909
- for (const entry of body.classifierFallbacks) {
1910
- if (typeof entry !== "string" || entry.trim() === "") {
1911
- return jsonResponse({ error: "classifierFallbacks entries must be non-empty strings" }, 400);
1763
+ const checked = prepareClaudeCodePatch(config, body);
1764
+ if (checked instanceof Response) return checked;
1765
+ const evidenceState = JSON.stringify(config);
1766
+ const visionPatch = body.visionSidecar;
1767
+ const webPatch = body.webSearchSidecar;
1768
+ const visionEvidence = isPlainObject(visionPatch) && typeof visionPatch.model === "string" && visionPatch.model !== ""
1769
+ ? await visionCandidateRows({ ...config, visionSidecar: { ...config.visionSidecar, ...sidecarSettingsAfterPatch(config.claudeCode?.visionSidecar, visionPatch) } }) : undefined;
1770
+ const webEvidence = isPlainObject(webPatch) && (webPatch.model !== undefined || webPatch.backend !== undefined || webPatch.anthropicInstance !== undefined)
1771
+ ? await webSearchCandidateRows({ ...config, webSearchSidecar: { ...config.webSearchSidecar, ...sidecarSettingsAfterPatch(config.claudeCode?.webSearchSidecar, webPatch) } }) : undefined;
1772
+ const { commitClaudeCodeBlock } = await import("../../claude/claude-code-block");
1773
+ const { saveConfigPreservingClaudeCode: save } = await import("../../config");
1774
+ const refusal = await settleConfigRoot(configRoot(), () => {
1775
+ if ((visionEvidence || webEvidence) && JSON.stringify(config) !== evidenceState) return jsonResponse({ error: "Sidecar validation state changed during discovery", code: "config_changed" }, 409);
1776
+ const instanceError = anthropicSidecarPatchError(config, body, true);
1777
+ if (instanceError) return jsonResponse({ error: instanceError }, 400);
1778
+ for (const field of ["webSearchSidecar", "visionSidecar"] as const) {
1779
+ const section = body[field] as Record<string, unknown> | null | undefined;
1780
+ if (section === undefined || section === null) continue;
1781
+ // Vision override only: reject a model we can prove is blind. Unknown ids stay
1782
+ // allowed. Shares one policy module with /api/sidecar-settings so the two
1783
+ // gates cannot drift.
1784
+ if (field === "visionSidecar" && typeof section.model === "string" && section.model !== "") {
1785
+ const requested = section.model;
1786
+ const candidates = visionEvidence!;
1787
+ const hint = section.backend === "anthropic" || section.backend === "openai"
1788
+ || section.backend === "routed"
1789
+ ? section.backend
1790
+ : config.claudeCode?.visionSidecar?.backend;
1791
+ // Same coherence rule as /api/sidecar-settings (roadmap 170 r2).
1792
+ const effectiveBackend = hint ?? "openai";
1793
+ const namespaced = requested.includes("/");
1794
+ if (namespaced && effectiveBackend !== "routed") {
1795
+ return jsonResponse({ error: `visionSidecar.model "${requested}" is provider-namespaced; it requires backend "routed"` }, 400);
1796
+ }
1797
+ if (!namespaced && effectiveBackend === "routed") {
1798
+ return jsonResponse({ error: `visionSidecar.backend "routed" requires a provider-namespaced model ("provider/model"); got "${requested}"` }, 400);
1799
+ }
1800
+ if (visionDescriberIsProvablyBlind(config, requested, candidates, hint)) {
1801
+ return jsonResponse(visionDescriberRejection("visionSidecar.model", requested, config, candidates), 400);
1912
1802
  }
1913
- list.push(entry.trim());
1914
- }
1915
- if (list.length > 0) next.classifierFallbacks = list;
1916
- else delete next.classifierFallbacks;
1917
- }
1918
- }
1919
- if (body.modelMap !== undefined) {
1920
- if (body.modelMap === null) {
1921
- delete next.modelMap;
1922
- } else {
1923
- if (!isPlainObject(body.modelMap)) {
1924
- return jsonResponse({ error: "modelMap must be an object of string->string, or null" }, 400);
1925
1803
  }
1926
- const map: Record<string, string> = {};
1927
- for (const [k, v] of Object.entries(body.modelMap)) {
1928
- if (typeof v !== "string" || k.trim() === "" || v.trim() === "") {
1929
- return jsonResponse({ error: "modelMap entries must be non-empty strings" }, 400);
1804
+ // Web-search override: membership gate (#2188). The executor set is closed,
1805
+ // so an id outside (runnable candidates ∪ auth slots) can never run. Same
1806
+ // module as /api/sidecar-settings — a gate on one route and a stale copy on
1807
+ // the other is no gate at all.
1808
+ if (field === "webSearchSidecar"
1809
+ && (section.model !== undefined || section.backend !== undefined || section.anthropicInstance !== undefined)) {
1810
+ const stored = config.claudeCode?.webSearchSidecar;
1811
+ // Validate against the SUBMITTED backend across the whole union, not
1812
+ // just openai/anthropic (#2457). allowedBackends above already refused
1813
+ // unknown literals; Array.includes does not narrow, hence the cast.
1814
+ // null keeps its own meaning here — drop the override and inherit the
1815
+ // global backend — which is deliberately NOT the sidecar-settings rule.
1816
+ const submittedBackend = section.backend;
1817
+ const effectiveBackend = typeof submittedBackend === "string"
1818
+ ? submittedBackend as WebSearchBackend
1819
+ : submittedBackend === null
1820
+ ? config.webSearchSidecar?.backend ?? "openai"
1821
+ : stored?.backend ?? config.webSearchSidecar?.backend ?? "openai";
1822
+ const effectiveModel = section.model === ""
1823
+ ? config.webSearchSidecar?.model
1824
+ : typeof section.model === "string"
1825
+ ? section.model
1826
+ : stored?.model ?? config.webSearchSidecar?.model;
1827
+ const candidates = webEvidence!;
1828
+ if (effectiveModel && webSearchModelIsRejected(effectiveBackend, effectiveModel, candidates)) {
1829
+ return jsonResponse(webSearchModelRejection(
1830
+ "webSearchSidecar.model",
1831
+ effectiveBackend,
1832
+ effectiveModel,
1833
+ candidates,
1834
+ ), 400);
1930
1835
  }
1931
- map[k.trim()] = v.trim();
1932
1836
  }
1933
- if (Object.keys(map).length > 0) next.modelMap = map;
1934
- else delete next.modelMap;
1935
1837
  }
1936
- }
1937
- if (body.fastMode !== undefined) config.fastMode = nextFastMode;
1938
- // Stamps the auth-mode migration sentinel on EVERY persist of this block. Without it,
1939
- // choosing Auto (which DELETES authMode) or merely toggling Claude on (App.tsx PUTs
1940
- // `{enabled}` alone and creates the block) would be converted into a sticky manual
1941
- // subscription by the next startServer, with no way back.
1942
- const { commitClaudeCodeBlock } = await import("../../claude/claude-code-block");
1943
- commitClaudeCodeBlock(config, next);
1944
- const { saveConfigPreservingClaudeCode: save } = await import("../../config");
1945
- save(config);
1838
+ const prepared = prepareClaudeCodePatch(config, body);
1839
+ if (prepared instanceof Response) return prepared;
1840
+ const { next, nextFastMode } = prepared;
1841
+ // Stamps the auth-mode migration sentinel on EVERY persist of this block. Without it,
1842
+ // choosing Auto (which DELETES authMode) or merely toggling Claude on (App.tsx PUTs
1843
+ // `{enabled}` alone and creates the block) would be converted into a sticky manual
1844
+ // subscription by the next startServer, with no way back.
1845
+
1846
+ if (body.fastMode !== undefined) config.fastMode = nextFastMode;
1847
+ commitClaudeCodeBlock(config, next);
1848
+ save(config);
1849
+ return null;
1850
+ });
1851
+ if (refusal) return refusal;
1946
1852
  const warnings: string[] = [];
1947
1853
  // authMode changes must reconcile the injected system env too: switching back to
1948
1854
  // Subscription has to remove the opencodex-owned dummy ANTHROPIC_AUTH_TOKEN
@@ -1961,7 +1867,7 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
1961
1867
  // Keep the file-backed live registry symmetric: OFF prunes immediately, while
1962
1868
  // ON and config changes restore definitions without requiring a restart.
1963
1869
  await syncClaudeAgentDefsBestEffort();
1964
- return jsonResponse({ ok: true, enabled: next.enabled !== false, warnings });
1870
+ return jsonResponse({ ok: true, enabled: config.claudeCode?.enabled !== false, warnings });
1965
1871
  }
1966
1872
  return null;
1967
1873
  }