@bitkyc08/opencodex 2.100.3 → 2.100.5-preview.20261118.1

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 (249) hide show
  1. package/AGENTS_INSTALL.md +23 -1
  2. package/bin/ocx.mjs +8 -1
  3. package/gui/dist/assets/{App-Dnb6VMsP.js → App-BiOGtxDS.js} +21 -20
  4. package/gui/dist/assets/{Tray-BV4ms9U9.js → Tray-BwsMejUO.js} +1 -1
  5. package/gui/dist/assets/brand-mark-BY1dgACL.js +1 -0
  6. package/gui/dist/assets/{index-DCdXsMyZ.js → index-CwHSKMdG.js} +46 -13
  7. package/gui/dist/assets/index-DJxM-imn.css +2 -0
  8. package/gui/dist/assets/{segment-thumb-features-DXSidY6D.js → segment-thumb-features-Bds9Hb_7.js} +1 -1
  9. package/gui/dist/classic/assets/{App-DA-scMPq.js → App-CGLOiqQL.js} +20 -19
  10. package/gui/dist/classic/assets/{Tray-BrHaVRAq.js → Tray-Da4r2O70.js} +1 -1
  11. package/gui/dist/classic/assets/{index-BqOaGLf5.js → index-CvoKXKL9.js} +46 -13
  12. package/gui/dist/classic/assets/quota-summary-DvqzfCmr.js +1 -0
  13. package/gui/dist/classic/index.html +1 -1
  14. package/gui/dist/index.html +2 -2
  15. package/native/ocx-child/src/cli.rs +5 -3
  16. package/native/ocx-child/src/codex_home.rs +1 -0
  17. package/native/ocx-child/src/link_ws.rs +24 -19
  18. package/native/ocx-child/src/link_ws_frame.rs +136 -50
  19. package/package.json +3 -3
  20. package/src/adapters/anthropic/per-message-effort.ts +296 -0
  21. package/src/adapters/anthropic-input-schema.ts +270 -0
  22. package/src/adapters/anthropic.ts +4 -63
  23. package/src/adapters/claude-cli/adapter.ts +1 -0
  24. package/src/adapters/command-code-tool-text.ts +9 -1
  25. package/src/adapters/command-code.ts +18 -2
  26. package/src/adapters/devin/cloud-direct/chat.ts +95 -14
  27. package/src/adapters/devin/live-models.ts +11 -1
  28. package/src/adapters/google-errors.ts +14 -2
  29. package/src/adapters/kiro/reasoning.ts +3 -0
  30. package/src/adapters/kiro-tools.ts +14 -9
  31. package/src/adapters/openai-responses/passthrough.ts +3 -1
  32. package/src/adapters/openai-responses/request-strips.ts +1 -0
  33. package/src/adapters/qoder/adapter.ts +9 -1
  34. package/src/adapters/tool-catalog-nudge.ts +1 -1
  35. package/src/adapters/zed.ts +4 -2
  36. package/src/claude/chat-tool-dispatch.ts +4 -1
  37. package/src/claude/desktop-remote-store.ts +60 -10
  38. package/src/cli/account-api.ts +4 -0
  39. package/src/cli/account-auth.ts +30 -2
  40. package/src/cli/account-extended.ts +33 -2
  41. package/src/cli/capabilities-access-remote.ts +3 -3
  42. package/src/cli/capabilities-accounts.ts +3 -3
  43. package/src/cli/capabilities-base.ts +11 -6
  44. package/src/cli/capabilities-observe-system.ts +2 -2
  45. package/src/cli/claude.ts +3 -3
  46. package/src/cli/disconnect-runtime.ts +16 -6
  47. package/src/cli/dispatch.ts +7 -1
  48. package/src/cli/index.ts +2 -2
  49. package/src/cli/link-apply-restart.ts +4 -2
  50. package/src/cli/link-routes.ts +4 -1
  51. package/src/cli/link.ts +5 -4
  52. package/src/cli/logout-command.ts +23 -4
  53. package/src/cli/preflight-exemptions.ts +3 -0
  54. package/src/cli/provider.ts +3 -2
  55. package/src/cli/registry.ts +5 -2
  56. package/src/cli/resolve.ts +23 -8
  57. package/src/cli/restart-failure.ts +11 -1
  58. package/src/cli/runtime-api.ts +4 -0
  59. package/src/cli/status.ts +4 -1
  60. package/src/cli/system-command.ts +1 -1
  61. package/src/cli/system-restart-client.ts +9 -3
  62. package/src/cli/system-settings-parity.ts +2 -1
  63. package/src/client/connect.ts +73 -11
  64. package/src/client/desktop-refusal.ts +38 -0
  65. package/src/client/lifecycle-lock.ts +29 -4
  66. package/src/client/runtime-restart.ts +27 -15
  67. package/src/client/runtime.ts +4 -2
  68. package/src/client/state.ts +14 -0
  69. package/src/clients/config-export.ts +12 -7
  70. package/src/codex/account-lifecycle.ts +3 -1
  71. package/src/codex/account-pause.ts +4 -0
  72. package/src/codex/account-runtime-state.ts +4 -0
  73. package/src/codex/auth-api/main-account-probe.ts +3 -1
  74. package/src/codex/auth-api/main-hard-lock-refusal-read.ts +172 -0
  75. package/src/codex/auth-context.ts +40 -2
  76. package/src/codex/catalog/build-entries.ts +10 -0
  77. package/src/codex/catalog/derive-entry.ts +7 -0
  78. package/src/codex/catalog/metadata.ts +8 -0
  79. package/src/codex/catalog/native-models.ts +16 -6
  80. package/src/codex/catalog/pinned-models.ts +1 -0
  81. package/src/codex/catalog/provider-models.ts +5 -5
  82. package/src/codex/catalog/reserve-warn.ts +7 -5
  83. package/src/codex/catalog/reserve.ts +4 -3
  84. package/src/codex/catalog/retained-sync.ts +2 -0
  85. package/src/codex/catalog/routed-defaults.ts +35 -0
  86. package/src/codex/catalog-auto-refresh.ts +13 -2
  87. package/src/codex/config-drift-heal.ts +40 -12
  88. package/src/codex/config-write-lock.ts +39 -1
  89. package/src/codex/convergence.ts +2 -0
  90. package/src/codex/data/roster-pinned-models.json +346 -1
  91. package/src/codex/inject/config-write-section.ts +39 -1
  92. package/src/codex/inject/plan.ts +10 -8
  93. package/src/codex/inject/remove.ts +21 -19
  94. package/src/codex/inject/restore.ts +5 -1
  95. package/src/codex/inject-coordination.ts +58 -7
  96. package/src/codex/inject.ts +10 -12
  97. package/src/codex/journal-config-restore.ts +42 -0
  98. package/src/codex/journal.ts +62 -8
  99. package/src/codex/loopback-target.ts +22 -8
  100. package/src/codex/main-account.ts +94 -30
  101. package/src/codex/native-main-auth-file.ts +14 -0
  102. package/src/codex/native-main-credentials.ts +276 -0
  103. package/src/codex/native-main-owner.ts +3 -0
  104. package/src/codex/native-main-refresh-mode.ts +14 -1
  105. package/src/codex/quota.ts +63 -14
  106. package/src/combos/failover.ts +195 -1
  107. package/src/combos/index.ts +5 -0
  108. package/src/combos/resolve.ts +115 -19
  109. package/src/config/diagnostics.ts +3 -0
  110. package/src/config/live-reconcile.ts +6 -3
  111. package/src/config/load-degrade.ts +2 -0
  112. package/src/config/persisted-mutation.ts +2 -2
  113. package/src/config/persisted-projections.ts +18 -0
  114. package/src/config/process-state.ts +4 -3
  115. package/src/config/reserve-capability.ts +96 -0
  116. package/src/config/schema/config-schema.ts +6 -0
  117. package/src/config/schema/leaf-validators.ts +2 -0
  118. package/src/config/schema/routed-catalog-defaults.ts +49 -0
  119. package/src/config/subagent-models.ts +20 -12
  120. package/src/config.ts +7 -7
  121. package/src/desktop-update/acquire.ts +202 -0
  122. package/src/desktop-update/cli.ts +168 -0
  123. package/src/desktop-update/drain.ts +40 -0
  124. package/src/desktop-update/headless.ts +285 -0
  125. package/src/desktop-update/image.ts +85 -0
  126. package/src/desktop-update/install.ts +53 -0
  127. package/src/desktop-update/msi.ts +72 -0
  128. package/src/desktop-update/release.ts +128 -0
  129. package/src/desktop-update/runtime.ts +155 -0
  130. package/src/desktop-update/staging.ts +118 -0
  131. package/src/desktop-update/trust.ts +45 -0
  132. package/src/generated/compatibility-version.json +327 -195
  133. package/src/generated/model-metadata.ts +3 -3
  134. package/src/images/fulfill-video.ts +3 -3
  135. package/src/images/loop.ts +6 -2
  136. package/src/images/plan.ts +147 -11
  137. package/src/images/types.ts +13 -4
  138. package/src/images/xai-video-client.ts +72 -10
  139. package/src/lib/client-error-body.ts +6 -0
  140. package/src/lib/developer-role-rejection.ts +15 -0
  141. package/src/lib/gcp-adc.ts +48 -4
  142. package/src/lib/offline-resend.ts +150 -0
  143. package/src/lib/paced-stream.ts +3 -3
  144. package/src/lib/provider-outbound.ts +17 -6
  145. package/src/lib/request-failure-model.ts +2 -0
  146. package/src/lib/response-body-inactivity.ts +23 -1
  147. package/src/lib/upstream-retry.ts +39 -6
  148. package/src/link/explicit-route.ts +4 -4
  149. package/src/link/remote-windows.ts +79 -31
  150. package/src/link/residual-recovery.ts +20 -8
  151. package/src/messaging/budget.ts +23 -5
  152. package/src/messaging/remote-ports.ts +22 -10
  153. package/src/messaging/rpc.ts +4 -4
  154. package/src/oauth/antigravity-risk.ts +126 -0
  155. package/src/oauth/credential-siblings.ts +32 -0
  156. package/src/oauth/generic-account-failover.ts +113 -30
  157. package/src/oauth/generic-session-affinity.ts +10 -3
  158. package/src/oauth/index.ts +22 -14
  159. package/src/oauth/login-cli.ts +35 -1
  160. package/src/oauth/pool-kernel.ts +3 -3
  161. package/src/oauth/store.ts +38 -7
  162. package/src/providers/anthropic-billing-refusal.ts +27 -3
  163. package/src/providers/anthropic-reset-grants.ts +4 -0
  164. package/src/providers/claude-cli-usage.ts +2 -0
  165. package/src/providers/codebuddy-models.ts +11 -0
  166. package/src/providers/google-vertex-model-discovery.ts +49 -15
  167. package/src/providers/kiro-models.ts +5 -0
  168. package/src/providers/model-rename-fields.ts +2 -0
  169. package/src/providers/quota/workbuddy.ts +6 -2
  170. package/src/providers/registry/entries-core.ts +9 -3
  171. package/src/providers/registry/entries-extended.ts +20 -9
  172. package/src/providers/registry/model-seeds.ts +4 -1
  173. package/src/providers/stale-context-window-migration.ts +2 -0
  174. package/src/providers/workbuddy-credit-balance.ts +125 -16
  175. package/src/responses/citation-markers.ts +26 -23
  176. package/src/responses/effort-history.ts +732 -0
  177. package/src/routing/history/integrity.ts +41 -4
  178. package/src/server/auth-cors.ts +13 -3
  179. package/src/server/codex-model-list.ts +2 -1
  180. package/src/server/direct-local-http.ts +26 -3
  181. package/src/server/index/link-listener.ts +20 -14
  182. package/src/server/index/serve-options.ts +1 -0
  183. package/src/server/index.ts +3 -2
  184. package/src/server/link-turn.ts +17 -5
  185. package/src/server/management/config-routes.ts +39 -3
  186. package/src/server/management/link-child-preflight.ts +1 -1
  187. package/src/server/management/link-enrollment.ts +3 -3
  188. package/src/server/management/link-route-edit.ts +20 -1
  189. package/src/server/management/link-route-request.ts +11 -5
  190. package/src/server/management/oauth-account-routes.ts +43 -13
  191. package/src/server/management/provider-credential-release.ts +44 -0
  192. package/src/server/management/provider-overwrite-carry.ts +3 -0
  193. package/src/server/management/provider-routes.ts +12 -12
  194. package/src/server/management/static-catalog-probe.ts +33 -0
  195. package/src/server/management/usage-aggregate-cache.ts +6 -3
  196. package/src/server/messages-native.ts +16 -2
  197. package/src/server/proxy-liveness.ts +54 -9
  198. package/src/server/relay.ts +6 -1
  199. package/src/server/request-log-conversation.ts +8 -4
  200. package/src/server/request-log-failure-detail.ts +26 -9
  201. package/src/server/request-log.ts +5 -1
  202. package/src/server/reserve-capability-startup.ts +32 -0
  203. package/src/server/responses/adapter-continuation.ts +59 -25
  204. package/src/server/responses/adapter-delivery.ts +2 -0
  205. package/src/server/responses/adapter-dispatch.ts +39 -18
  206. package/src/server/responses/antigravity-fault-rotation.ts +24 -0
  207. package/src/server/responses/antigravity-validation-refusal.ts +43 -6
  208. package/src/server/responses/codex-tool-catalog.ts +47 -10
  209. package/src/server/responses/combo-selection-keepalive.ts +254 -0
  210. package/src/server/responses/combo-session-recall.ts +26 -1
  211. package/src/server/responses/combo-stream-preflight.ts +35 -26
  212. package/src/server/responses/core-combo-failure.ts +6 -0
  213. package/src/server/responses/core-combo-native.ts +2 -1
  214. package/src/server/responses/core-combo.ts +67 -28
  215. package/src/server/responses/core-errors.ts +9 -6
  216. package/src/server/responses/core-options.ts +10 -0
  217. package/src/server/responses/core.ts +21 -0
  218. package/src/server/responses/estimated-usage.ts +115 -0
  219. package/src/server/responses/input-admission.ts +41 -3
  220. package/src/server/responses/jev-model-invoke.ts +7 -2
  221. package/src/server/responses/passthrough-completion.ts +6 -3
  222. package/src/server/responses/passthrough-delivery.ts +47 -8
  223. package/src/server/responses/passthrough-dispatch.ts +3 -0
  224. package/src/server/responses/request-prepare.ts +9 -5
  225. package/src/server/responses/request-send-budget.ts +1 -1
  226. package/src/server/responses/request-transport.ts +10 -2
  227. package/src/server/responses/sidecar-execution.ts +11 -4
  228. package/src/service/desktop-supervision.d.mts +2 -0
  229. package/src/service/desktop-supervision.mjs +5 -0
  230. package/src/service/windows-checked-stop-live.ts +28 -5
  231. package/src/stall-timeout.ts +11 -0
  232. package/src/types/config.ts +15 -92
  233. package/src/types/provider.ts +13 -0
  234. package/src/types/request.ts +23 -3
  235. package/src/types/routed-catalog-defaults.ts +17 -0
  236. package/src/types/routing-profile.ts +90 -0
  237. package/src/types.ts +1 -0
  238. package/src/update/index.ts +1 -1
  239. package/src/usage/expected-prices.ts +35 -0
  240. package/src/usage/ledger-scanner.ts +44 -10
  241. package/src/usage/log.ts +14 -4
  242. package/src/usage/telemetry-contract.ts +1 -0
  243. package/src/web-search/loop.ts +20 -2
  244. package/src/web-search/parse.ts +2 -12
  245. package/src/web-search/passthrough-bridge.ts +7 -0
  246. package/src/web-search/sources.ts +13 -0
  247. package/gui/dist/assets/brand-mark-XOLJbomA.js +0 -1
  248. package/gui/dist/assets/index-DQtCRNAw.css +0 -2
  249. package/gui/dist/classic/assets/quota-summary-Dy5_wfTT.js +0 -1
@@ -21,6 +21,8 @@
21
21
  * - exit 1 when the CLI cannot resolve: an invalid config.json must NOT be answered
22
22
  * with `loadConfig`'s repair-to-defaults behaviour, because that hands the caller
23
23
  * a guessed port; and unknown liveness must not be answered as absence.
24
+ * Under `--json` that exit still prints its one document: a `ResolveFailureJson`
25
+ * (`ok: false` plus a fixed `reason`) beside the unchanged stderr line (#8318).
24
26
  * - exit 64 for any argument, pre-parsed in src/cli/root.ts before preflight side
25
27
  * effects, mirroring `ocx ready`. The verb is read-only and listed in
26
28
  * skipsCodexShimAutoRestore, so a lookup made to populate a consent surface never
@@ -136,6 +138,18 @@ export type ResolveTakeover =
136
138
  | { kind: "supported"; protocolVersion: number; minimumCliVersion: string; token: string }
137
139
  | { kind: "blocked"; reason: string; detail: string; minimumCliVersion: string };
138
140
 
141
+ /**
142
+ * The document `--json` prints when resolve exits 1 (#8318). It carries no liveness, port or
143
+ * ownership field, so nothing in it can be read as absence; `error` repeats the stderr line.
144
+ * A shell that keys on the exit status, as the desktop does, can ignore it.
145
+ */
146
+ export interface ResolveFailureJson {
147
+ schema: typeof RESOLVE_SCHEMA;
148
+ ok: false;
149
+ reason: "config_unreadable" | "config_invalid" | "discovery_failed" | "liveness_unknown";
150
+ error: string;
151
+ }
152
+
139
153
  export interface ResolveArgs {
140
154
  json: boolean;
141
155
  }
@@ -273,28 +287,30 @@ export async function runResolve(args: ResolveArgs, io: ResolveIo = {}): Promise
273
287
  const resolveState = io.resolveState ?? resolveServiceState;
274
288
  const observeManagers = io.observeManagers ?? observeManagingClis;
275
289
  const configHome = configDir();
290
+ const fail = (reason: ResolveFailureJson["reason"], error: string): number => {
291
+ stderr.error(error);
292
+ if (args.json) stdout.log(JSON.stringify({ schema: RESOLVE_SCHEMA, ok: false, reason, error } satisfies ResolveFailureJson));
293
+ return 1;
294
+ };
276
295
  let diagnostics: ConfigDiagnostics;
277
296
  try {
278
297
  diagnostics = readDiagnostics();
279
298
  } catch (error) {
280
299
  // A resolution that could not run must not read as "no proxy": the caller has to
281
300
  // refuse to guess (D5) rather than treat this as a proven-absent verdict.
282
- stderr.error(`resolve failed: ${error instanceof Error ? error.message : String(error)}`);
283
- return 1;
301
+ return fail("config_unreadable", `resolve failed: ${error instanceof Error ? error.message : String(error)}`);
284
302
  }
285
303
  if (diagnostics.source === "fallback") {
286
304
  // An invalid config must not resolve to defaults: the effective port would be a
287
305
  // guess at 10100 while the operator's config.port is unread. The repair-to-defaults
288
306
  // policy in loadConfig is for interactive recovery, not for a shell contract.
289
- stderr.error(`resolve failed: the config in ${configHome} is invalid (${diagnostics.error ?? "unknown error"}); refusing to guess.`);
290
- return 1;
307
+ return fail("config_invalid", `resolve failed: the config in ${configHome} is invalid (${diagnostics.error ?? "unknown error"}); refusing to guess.`);
291
308
  }
292
309
  let live: LiveProxy | null;
293
310
  try {
294
311
  live = await findLive();
295
312
  } catch (error) {
296
- stderr.error(`resolve failed: ${error instanceof Error ? error.message : String(error)}`);
297
- return 1;
313
+ return fail("discovery_failed", `resolve failed: ${error instanceof Error ? error.message : String(error)}`);
298
314
  }
299
315
  if (!live) {
300
316
  // findLiveProxy collapses "definitely nothing" and "could not tell" into the same
@@ -310,8 +326,7 @@ export async function runResolve(args: ResolveArgs, io: ResolveIo = {}): Promise
310
326
  provenDown = false;
311
327
  }
312
328
  if (!provenDown) {
313
- stderr.error("resolve: liveness is unknown (a probe timed out or a listener withheld /healthz); refusing to treat unknown as absent.");
314
- return 1;
329
+ return fail("liveness_unknown", "resolve: liveness is unknown (a probe timed out or a listener withheld /healthz); refusing to treat unknown as absent.");
315
330
  }
316
331
  }
317
332
  let ownership: ServiceOwnershipResolution;
@@ -1,6 +1,13 @@
1
1
  import type { ProxyRestartResult } from "./tray-proxy";
2
2
 
3
- export type RestartSupervisor = "desktop" | "service" | "service-unproven";
3
+ export type RestartSupervisor = "desktop" | "service" | "service-unproven" | "legacy-flag";
4
+
5
+ /**
6
+ * Why a client runtime with only a bare OCX_SERVICE=1 is kept (#8545 owner decision, 2026-11-16), and the one-time fix.
7
+ * `ocx service repair` rewrites a legacy registration with the current ownership marker (OCX_SERVICE_MANAGED or the
8
+ * Windows wrapper marker) and reloads it, after which restart, disconnect and sync hand the runtime to that service.
9
+ */
10
+ export const LEGACY_FLAG_OWNER_ADVICE = "It carries only the bare OCX_SERVICE=1 flag, which a background service registered before OpenCodex 2.49 and the proxies started by ocx claude, ocx codex and ocx opencode all share, so its owner cannot be proven. If a background service runs it, re-register the service once with `ocx service repair` (this writes the current ownership marker and restarts it). If ocx claude, ocx codex or ocx opencode started it, run `ocx stop` and start it again.";
4
11
 
5
12
  /** Only the bound client's explicit refusal establishes a supervisor for sync. */
6
13
  export function supervisedRestartRefusal(result: ProxyRestartResult): RestartSupervisor | null {
@@ -8,6 +15,7 @@ export function supervisedRestartRefusal(result: ProxyRestartResult): RestartSup
8
15
  if (result.error.message === "restart_supervised_desktop") return "desktop";
9
16
  if (result.error.message === "restart_supervised_service") return "service";
10
17
  if (result.error.message === "restart_supervised_service-unproven") return "service-unproven";
18
+ if (result.error.message === "restart_supervised_legacy-flag") return "legacy-flag";
11
19
  return null;
12
20
  }
13
21
 
@@ -38,6 +46,8 @@ export function reportRestartFailure(result: Extract<ProxyRestartResult, { ok: f
38
46
  console.error("Restart not performed; the running client runtime was kept. Its background service owns it: run `ocx service restart`.");
39
47
  } else if (code === "restart_supervised_service-unproven") {
40
48
  console.error("Restart not performed; the running client runtime was kept. A service manager started it (systemd opencodex-proxy.service, launchd com.opencodex.proxy or the Windows OpenCodex service), but it is not enabled or its relaunch could not be verified: restart it through the manager with 'ocx service restart', or check 'ocx service status'.");
49
+ } else if (code === "restart_supervised_legacy-flag") {
50
+ console.error(`Restart not performed; the running client runtime was kept and nothing was stopped. ${LEGACY_FLAG_OWNER_ADVICE}`);
41
51
  } else if (code === "restart_supervised_desktop") {
42
52
  console.error("Restart not performed; the running client runtime was kept. The OpenCodex desktop app owns it while its connection is current: use Quit in the OpenCodex tray menu, then reopen it. After `ocx disconnect`, `ocx restart` hands it to the app.");
43
53
  } else {
@@ -20,6 +20,8 @@ export type CliStdin = NodeJS.ReadableStream & { isTTY?: boolean; readableEnded?
20
20
 
21
21
  export const MAX_LINK_CREDENTIAL_BYTES = 4 * 1024;
22
22
 
23
+ import type { AntigravityRiskSeams } from "../oauth/antigravity-risk";
24
+
23
25
  export interface RuntimeApiDeps {
24
26
  baseUrl?: string;
25
27
  fetchImpl?: typeof fetch;
@@ -32,6 +34,8 @@ export interface RuntimeApiDeps {
32
34
  findLiveProxy?: (io?: LivenessIo) => Promise<LiveProxy | null>;
33
35
  /** Remote Link Child: how allowlisted reads reach the Home (#6957). */
34
36
  linkHome?: LinkHomeDeps;
37
+ /** Test seams for the Google Antigravity acknowledgement (agent detection, prompt visibility). */
38
+ antigravityRisk?: AntigravityRiskSeams;
35
39
  }
36
40
 
37
41
  export class CliUsageError extends Error {
package/src/cli/status.ts CHANGED
@@ -38,6 +38,7 @@ import { LOCAL_MANAGEMENT_READ_PATHS } from "../lib/local-management-capability"
38
38
  import { fetchBoundLocalManagementRead } from "../server/local-management-read-client";
39
39
  import { collectAppliedCodexSettingsStatus, type CliAppliedCodexSettingsStatus } from "./status-codex-settings";
40
40
  import { installDetectionStatus, type InstallDetectionStatus } from "./status-install";
41
+ import { windowsDesktopInstall, withDesktopSkewAdvice } from "../desktop-update/install";
41
42
  import { collectLocalCredentials, type LocalCredentialSnapshot } from "../local-credentials/inventory";
42
43
  import { collectLinkConnectionGeneration } from "./status-link";
43
44
 
@@ -944,7 +945,9 @@ export async function collectStatus(options: { mainAccountPolicy?: boolean } = {
944
945
  const pid = resolveStatusPid(live, pidFile);
945
946
  // No extra request: findLiveProxy's identity probe already parsed and validated the
946
947
  // healthz body, so the version came back with the liveness result.
947
- const versionSkew = computeVersionSkew(packageVersion(), live?.version);
948
+ // #8246: on a Windows Desktop installation a newer CLI means the MSI installed an update that the
949
+ // running runtime has not picked up; the warning says so with the command that finishes it.
950
+ const versionSkew = withDesktopSkewAdvice(computeVersionSkew(packageVersion(), live?.version), windowsDesktopInstall(), live?.source);
948
951
  // OCX-6: what this machine applied and, on a Child, when its runtime started. Additive and
949
952
  // always present (null when unknown), so `schemaVersion` stays 1.
950
953
  const appliedCodexSettings = await collectAppliedCodexSettingsStatus(config, live);
@@ -19,7 +19,7 @@ const USAGE = `Usage:
19
19
  ocx system settings [--auto-start <on|off>] [--stream-mode <auto|legacy-tee|eager-relay>]
20
20
  [--desktop-authless <on|off>] [--client-compaction <on|off>]
21
21
  [--show-codex-credits <on|off>] [--account-picker <on|off>] [--main-account-hard-lock <on|off>]
22
- [--ultra-fast-tier <on|off>] [--fast-rows <on|off>] [--json]
22
+ [--ultra-fast-tier <on|off>] [--fast-rows <on|off>] [--reserve <on|off>] [--json]
23
23
  ocx system startup <health|install-service|install-shim> [--json]
24
24
  ocx system diagnostics [--json]
25
25
  ocx system sync [--json]
@@ -44,6 +44,12 @@ export interface BoundSystemRestartDeps {
44
44
  /** Invoking CLI version for the skew guard; defaults to this bundle's package version. */
45
45
  cliVersion?: string;
46
46
  readUpdateHome?: typeof readUpdateRestartHome;
47
+ /**
48
+ * The caller proved the runtime's image is the installed executable whose version is
49
+ * `cliVersion` (the headless Desktop updater, #8246). Its in-place respawn then runs those
50
+ * installed bytes, so a CLI-newer skew is the expected state rather than a reason to refuse.
51
+ */
52
+ respawnRunsInstalledImage?: boolean;
47
53
  }
48
54
 
49
55
  function rejected(code: string): ProxyRestartRequestOutcome {
@@ -162,7 +168,7 @@ export async function requestBoundSystemRestart(
162
168
  return rejected("restart_target_recheck_failed");
163
169
  }
164
170
  if (!sameRestartTarget(target, observed)) return rejected("restart_target_changed");
165
- if (skew.relation === "cli-newer") {
171
+ if (skew.relation === "cli-newer" && !deps.respawnRunsInstalledImage) {
166
172
  if (!updateHome) return rejected("update_restart_home_unverified");
167
173
  try {
168
174
  if (JSON.stringify((deps.readUpdateHome ?? readUpdateRestartHome)()) !== JSON.stringify(updateHome)) {
@@ -226,14 +232,14 @@ export async function requestBoundSystemRestart(
226
232
  * A client runtime under the desktop app or a service answers 409 `restart_supervised` and keeps
227
233
  * serving (OCX-6). Read that small body and return the validated supervisor, or null.
228
234
  */
229
- async function supervisedRefusal(response: Response): Promise<"service" | "desktop" | "service-unproven" | null> {
235
+ async function supervisedRefusal(response: Response): Promise<"service" | "desktop" | "service-unproven" | "legacy-flag" | null> {
230
236
  try {
231
237
  const read = await readBoundedResponseBytes(response, { maxBytes: 1024, signal: AbortSignal.timeout(SYSTEM_RESTART_REQUEST_TIMEOUT_MS) });
232
238
  if (read.oversized) return null;
233
239
  const body = JSON.parse(new TextDecoder().decode(read.bytes)) as { error?: { code?: unknown; supervisor?: unknown } } | null;
234
240
  if (body?.error?.code !== RESTART_SUPERVISED_ERROR) return null;
235
241
  const supervisor = body.error.supervisor;
236
- return supervisor === "service" || supervisor === "desktop" || supervisor === "service-unproven" ? supervisor : null;
242
+ return supervisor === "service" || supervisor === "desktop" || supervisor === "service-unproven" || supervisor === "legacy-flag" ? supervisor : null;
237
243
  } catch {
238
244
  return null;
239
245
  }
@@ -3,10 +3,11 @@ import { serializeManagementJson } from "./json-input";
3
3
  import { printSettingsResult, projectSettingsApply } from "./settings-result";
4
4
  import { CliUsageError, runtimeBaseUrl, runtimeRequest, takeFlag, takeOptionWithSyntax, type RuntimeApiDeps } from "./runtime-api";
5
5
 
6
- export const SYSTEM_PARITY_OPTIONS = ["--show-codex-credits", "--account-picker", "--main-account-hard-lock", "--ultra-fast-tier", "--fast-rows"] as const;
6
+ export const SYSTEM_PARITY_OPTIONS = ["--show-codex-credits", "--account-picker", "--main-account-hard-lock", "--ultra-fast-tier", "--fast-rows", "--reserve"] as const;
7
7
  const BOOLEAN_FIELDS: Readonly<Record<string, string>> = {
8
8
  "--show-codex-credits": "showCodexCredits", "--account-picker": "codexAccountPickerEnabled",
9
9
  "--main-account-hard-lock": "codexMainAccountHardLock", "--ultra-fast-tier": "ultraFastTier", "--fast-rows": "fastRows",
10
+ "--reserve": "codexReserveEnabled",
10
11
  "--auto-start": "codexAutoStart", "--desktop-authless": "codexDesktopAuthless", "--client-compaction": "codexClientCompaction",
11
12
  };
12
13
  function record(value: unknown): value is Record<string, unknown> {
@@ -13,15 +13,16 @@ import { getConfigDir, withConfigDirHardeningSettled } from "../config/paths";
13
13
  import { claudeDesktopIntegrationEnabledNow } from "../codex/desired-state";
14
14
  import { siblingOfLivePort, siblingSkipMessage } from "../codex/sibling-start";
15
15
  import {
16
- inspectRemoteDesktopStore, readDesktopDisconnectReceipt, writeDesktopDisconnectReceipt,
16
+ inspectRemoteDesktopStore, readDesktopDisconnectReceipt, writeDesktopDisconnectReceipt, removeDesktopDisconnectReceipt,
17
17
  replaceRemoteDesktopCredential, restoreRemoteDesktopStore, finishRemoteDesktopCleanup,
18
18
  type DesktopDisconnectReceipt, type DesktopRemoteOwner, type DesktopStoreResult,
19
19
  } from "../claude/desktop-remote-store";
20
20
  import {
21
- withClientLifecycle, withClientLifecycleSync,
21
+ withClientDisconnectAttempt, withClientLifecycle, withClientLifecycleSync,
22
22
  type ClientLifecycleHeld, type ClientLifecycleLockDeps,
23
23
  } from "./lifecycle-lock";
24
24
  import { invalidateCodexModelsCache, invalidateCodexModelsCacheWithPermit } from "../codex/catalog/sync";
25
+ import { desktopLifecycleRefusal } from "./desktop-refusal";
25
26
  import { withCatalogWriteSerialization } from "../codex/catalog-write-serialization";
26
27
  import {
27
28
  injectCodexConfig,
@@ -37,6 +38,7 @@ import {
37
38
  journalOwner,
38
39
  restoreJournalState,
39
40
  } from "../codex/journal";
41
+ import { ConfigWriteContentChanged } from "../codex/config-write-lock";
40
42
  import { readCodexHomeJournal } from "../codex/codex-home-owner";
41
43
  import { DEFAULT_CATALOG_PATH, getCodexHome } from "../codex/paths";
42
44
  import {
@@ -893,8 +895,15 @@ async function connectClientUnlocked(
893
895
  } catch (error) {
894
896
  const rollbackFailures: string[] = [];
895
897
  if (injectionCommitted) {
896
- const restored = restoreJournalState();
897
- if (!restored.complete) rollbackFailures.push("Codex journal restore was partial");
898
+ try {
899
+ const restored = restoreJournalState();
900
+ if (!restored.complete) rollbackFailures.push("Codex journal restore was partial");
901
+ } catch (restoreError) {
902
+ // A concurrent config.toml write refuses the restore and keeps the journal; report it as a
903
+ // partial rollback instead of abandoning the rest of the rollback.
904
+ if (!(restoreError instanceof ConfigWriteContentChanged)) throw restoreError;
905
+ rollbackFailures.push("Codex journal restore deferred: config.toml changed during rollback");
906
+ }
898
907
  }
899
908
  try {
900
909
  withClientLifecycleSync(() => withConfigMutationLockSync(() => {
@@ -1265,6 +1274,47 @@ function restoreConnectedCodex(connection: OcxClientConnectionConfig, receipt: D
1265
1274
  }
1266
1275
  }
1267
1276
 
1277
+ /**
1278
+ * Abort a disconnect that failed before its commit point.
1279
+ *
1280
+ * Until `desktop_restored` the receipt records intent only, so removing it returns the Child to a plain
1281
+ * connected state; left in place it made every client start refuse with client_disconnect_pending
1282
+ * until someone moved the folder aside by hand. A receipt this attempt wrote is removed outright:
1283
+ * D excludes other disconnects and every Desktop writer refuses while it exists. A receipt an
1284
+ * earlier run left (including one stuck by an older release) is removed only while the Desktop
1285
+ * store shows no restore has started; that run may have stopped inside the Desktop restore before
1286
+ * it could record desktop_restored, and then the receipt is the gate a retry needs.
1287
+ *
1288
+ * On a link Child the route-intent drain runs before the Codex restore, so by then the file
1289
+ * integrations the link routed may already be off. That is not undone here: the connection stays,
1290
+ * and the runtime's next route-intent apply turns them back on, as it does after any Home change.
1291
+ */
1292
+ function abortPreparedDisconnect(
1293
+ prepared: { receipt: DesktopDisconnectReceipt; created: boolean; connection: OcxClientConnectionConfig | null },
1294
+ error: unknown,
1295
+ deps: Pick<ClientConnectDeps, "lifecycleLockDeps">,
1296
+ ): Error {
1297
+ const base = error instanceof Error ? error.message : String(error);
1298
+ let outcome: "removed" | "desktop_started";
1299
+ try {
1300
+ outcome = withClientLifecycleSync(held => withConfigMutationLockSync(() => {
1301
+ if (!prepared.created && !UNTOUCHED_DESKTOP.has(inspectRemoteDesktopStore(prepared.receipt.owner).kind)) return "desktop_started" as const;
1302
+ removeDesktopDisconnectReceipt(held, prepared.receipt);
1303
+ return "removed" as const;
1304
+ }), deps.lifecycleLockDeps);
1305
+ } catch {
1306
+ return new Error(`${base}. The disconnect receipt could not be rolled back; run ocx disconnect again to finish it or roll it back.`, { cause: error });
1307
+ }
1308
+ const drained = prepared.connection?.transport === "link"
1309
+ ? " File integrations this link routed may already be off; the runtime's next route-intent apply turns them back on." : "";
1310
+ return new Error(outcome === "removed"
1311
+ ? `${base}. The disconnect was rolled back: this Child is still connected and its runtime can start.${drained}`
1312
+ : `${base}. A Claude Desktop restore had already started under this disconnect, so its receipt was kept; once the cause above is fixed, run ocx disconnect again to finish it.`, { cause: error });
1313
+ }
1314
+
1315
+ /** Desktop store states an interrupted disconnect cannot have produced: no restore has begun. */
1316
+ const UNTOUCHED_DESKTOP: ReadonlySet<string> = new Set(["absent", "active", "legacy_current_connection"]);
1317
+
1268
1318
  /**
1269
1319
  * `ocx disconnect --expect-link <id>`: refuse unless this machine is connected to that link (the same
1270
1320
  * check `ocx sync --expect-link` makes), read-only under the client lifecycle and config locks. A Home's
@@ -1333,6 +1383,16 @@ function drainLoneNativeIntentOriginals(lifecycleLockDeps?: ClientLifecycleLockD
1333
1383
  }
1334
1384
 
1335
1385
  export async function disconnectClient(
1386
+ options: Parameters<typeof disconnectClientAttempt>[0] = {},
1387
+ deps: Pick<ClientConnectDeps, "lifecycleLockDeps"> = {},
1388
+ ): ReturnType<typeof disconnectClientAttempt> {
1389
+ // The attempt lock is a file under the config directory: wait for parent ACL admission first,
1390
+ // as every other phase does, so nothing is created under a directory still being hardened.
1391
+ await withConfigDirHardeningSettled(getConfigDir(), () => undefined);
1392
+ return withClientDisconnectAttempt(() => disconnectClientAttempt(options, deps), deps.lifecycleLockDeps);
1393
+ }
1394
+
1395
+ async function disconnectClientAttempt(
1336
1396
  options: { keepCatalog?: boolean; expectedOwner?: DesktopRemoteOwner; expectLink?: string; recoverConfig?: boolean } = {},
1337
1397
  deps: Pick<ClientConnectDeps, "lifecycleLockDeps"> = {},
1338
1398
  ): Promise<{
@@ -1367,6 +1427,7 @@ export async function disconnectClient(
1367
1427
  throw new Error("client_disconnect_expected_owner_changed");
1368
1428
  }
1369
1429
  let receipt = previous;
1430
+ let created = false;
1370
1431
  let connection: OcxClientConnectionConfig | null = null;
1371
1432
  if (state.kind === "connected") {
1372
1433
  connection = state.value;
@@ -1383,19 +1444,17 @@ export async function disconnectClient(
1383
1444
  }
1384
1445
  if (!receipt) {
1385
1446
  const desktop = inspectRemoteDesktopStore(desktopOwner(connection));
1386
- if (desktop.reason === "root_without_state") {
1387
- throw new Error(`desktop_lifecycle_unsafe: ${desktop.path} exists but holds no Claude Desktop remote state or disconnect receipt (a leftover or renamed file), so disconnect cannot tell what it would restore. Move that folder aside, then run ocx disconnect again.`);
1388
- }
1389
- if (desktop.kind === "unsafe" || desktop.kind === "conflict") throw new Error(`desktop_lifecycle_unsafe: the Claude Desktop remote profile store could not be verified (${desktop.kind}); nothing was changed.`);
1447
+ if (desktop.kind === "unsafe" || desktop.kind === "conflict") throw new Error(desktopLifecycleRefusal(desktop));
1390
1448
  preflightDisconnectCatalog(connection, keepCatalog);
1391
1449
  receipt = { version: 1, owner: desktopOwner(connection), tokenFingerprint: connection.tokenFingerprint, keepCatalog, phase: "prepared" };
1392
1450
  writeDesktopDisconnectReceipt(held, previous, receipt);
1451
+ created = true;
1393
1452
  }
1394
1453
  } else if (state.kind !== "disconnected" || !receipt || !disconnectAtLeast(receipt, "clearing_connection")) {
1395
1454
  throw new Error("disconnect refused: no recoverable connected state; if this is not a Hub and no admission secret or installed service uses the token, inspect it and use ocx disconnect --orphaned-token --yes");
1396
1455
  }
1397
1456
  if (!receipt || receipt.keepCatalog !== keepCatalog) throw new Error("client_disconnect_options_changed");
1398
- return { receipt, connection };
1457
+ return { receipt, connection, created };
1399
1458
  }), deps.lifecycleLockDeps));
1400
1459
 
1401
1460
  // This sibling step owns only file integrations; failures retain the prepared receipt/token.
@@ -1407,8 +1466,11 @@ export async function disconnectClient(
1407
1466
  }
1408
1467
  // The prepared receipt blocks even a sync queued for its actual N/C injection commit.
1409
1468
  // Codex-only restore MUST stay outside L; it never invokes Desktop cleanup.
1410
- const recoveryBackupDir = prepared.connection && !disconnectAtLeast(prepared.receipt, "desktop_restored")
1411
- ? restoreConnectedCodex(prepared.connection, prepared.receipt, options.recoverConfig === true) : undefined;
1469
+ let recoveryBackupDir: string | undefined;
1470
+ if (prepared.connection && !disconnectAtLeast(prepared.receipt, "desktop_restored")) {
1471
+ try { recoveryBackupDir = restoreConnectedCodex(prepared.connection, prepared.receipt, options.recoverConfig === true); }
1472
+ catch (error) { throw abortPreparedDisconnect(prepared, error, deps); }
1473
+ }
1412
1474
 
1413
1475
  return withConfigDirHardeningSettled(getConfigDir(), () => withClientLifecycleSync(held => withConfigMutationLockSync(() => {
1414
1476
  const read = readDesktopDisconnectReceipt();
@@ -0,0 +1,38 @@
1
+ import type { DesktopStoreInspectReason } from "../claude/desktop-remote-store";
2
+
3
+ const FOLDER = "the desktop-remote folder in the OpenCodex home";
4
+
5
+ /**
6
+ * The `ocx disconnect` refusal for a Claude Desktop remote store it cannot verify: what was found,
7
+ * where, and the step that clears it, with the machine-readable code last. Each fix leaves the next
8
+ * inspection able to decide; none is run for the person, because each gives up or rewrites
9
+ * something in Claude Desktop that only they can judge.
10
+ */
11
+ export function desktopLifecycleRefusal(desktop: { kind: string; reason?: DesktopStoreInspectReason; path?: string }): string {
12
+ const at = desktop.path;
13
+ const body = (() => {
14
+ switch (desktop.reason) {
15
+ case "root_without_state":
16
+ return `${at} exists but holds no Claude Desktop remote state or disconnect receipt (a leftover or renamed file), so disconnect cannot tell what it would restore. Nothing was changed. Move that folder aside, then run ocx disconnect again.`;
17
+ case "store_unreadable":
18
+ return `OpenCodex cannot read safely the Claude Desktop remote state in ${at ?? FOLDER}: state.json or baseline.json is not an owner-only regular file, is not valid, or was written for another OpenCodex home or Claude Desktop library. Nothing was changed. If either file is not owner-only, make it so (chmod 600) and retry. Otherwise move that folder aside and keep it (its baseline.json holds the Claude Desktop profile OpenCodex replaced); disconnect then gives Claude Desktop's OpenCodex profile its standard settings. In either case, then run ocx disconnect again.`;
19
+ case "store_other_connection":
20
+ return `${at} records a Claude Desktop profile applied for a different connection (another Home or an earlier link), so this disconnect cannot restore it. Nothing was changed. In Claude Desktop, remove that connection's OpenCodex profile; then move ${FOLDER} aside, then run ocx disconnect again.`;
21
+ case "library_unreadable":
22
+ return `the Claude Desktop profile list in ${at} (_meta.json or the selected profile file) could not be read safely. Nothing was changed. Restore that file to valid JSON from Claude Desktop or a backup, then run ocx disconnect again.`;
23
+ case "profile_missing":
24
+ return `the OpenCodex profile in the Claude Desktop library ${at} was removed or renamed outside OpenCodex, so disconnect cannot restore the profile it replaced. Nothing was changed. Rename it back to "opencodex" in Claude Desktop; if it was deleted, move ${FOLDER} aside instead; then run ocx disconnect again.`;
25
+ case "profile_edited":
26
+ return `the OpenCodex profile ${at} was edited outside OpenCodex after it was applied. Nothing was changed. Disconnect restores the profile OpenCodex replaced, which discards those edits: copy anything you want to keep from that file, undo the edits, then run ocx disconnect again.`;
27
+ case "profile_ambiguous":
28
+ return `a profile in the Claude Desktop library ${at} reaches this Home, but disconnect cannot identify it as OpenCodex's current profile (it has another name, an older key, or is a second copy). Nothing was changed. In Claude Desktop, remove every profile that reaches this Home except one named "opencodex" that uses this connection's current key; if the only one left uses an older key, remove that one too, then run ocx disconnect again.`;
29
+ case "token_unreadable":
30
+ return `the service token or its rotation backup (${at}) is not a safe regular file, so disconnect cannot tell which keys belong to this connection. Nothing was changed. Make both files owner-only regular files (move a directory or link at that path aside), then run ocx disconnect again.`;
31
+ case "connection_changed":
32
+ return `the saved connection changed while disconnect was checking Claude Desktop. Nothing was changed. Check ocx connect status, then run ocx disconnect again.`;
33
+ default:
34
+ return `the Claude Desktop remote profile store could not be verified (${desktop.kind}). Nothing was changed. Check ${FOLDER} and the Claude Desktop profile library, then run ocx disconnect again.`;
35
+ }
36
+ })();
37
+ return `Disconnect refused: ${body} (code desktop_lifecycle_unsafe)`;
38
+ }
@@ -1,4 +1,7 @@
1
- /** Client/Desktop lifecycle exclusion. Lock order: N -> L -> C; never acquire N inside L. */
1
+ /**
2
+ * Client/Desktop lifecycle exclusion. Lock order: D -> N -> L -> C; never acquire N inside L.
3
+ * D (one disconnect attempt) is outermost and taken by nothing else.
4
+ */
2
5
  import { Database } from "bun:sqlite";
3
6
  import { chmodSync, closeSync, lstatSync, mkdirSync, openSync } from "node:fs";
4
7
  import { dirname, join, resolve } from "node:path";
@@ -54,14 +57,14 @@ function preparePath(lockPath: string): void {
54
57
  assertPath(lockPath, false);
55
58
  }
56
59
 
57
- function acquire(deps: ClientLifecycleLockDeps): Database {
60
+ function acquire(deps: ClientLifecycleLockDeps, name = "client-desktop-lifecycle.sqlite", suffix = ""): Database {
58
61
  let database: Database | undefined;
59
62
  try {
60
63
  // The production namespace belongs to the effective OS user, never HOME,
61
64
  // OPENCODEX_HOME, Desktop library overrides or an environment test switch.
62
65
  const path = deps.lockPath === undefined
63
- ? join(resolveEffectiveUserRuntimeRoot(resolveEffectiveUserIdentity()), "client-desktop-lifecycle.sqlite")
64
- : resolve(deps.lockPath);
66
+ ? join(resolveEffectiveUserRuntimeRoot(resolveEffectiveUserIdentity()), name)
67
+ : resolve(deps.lockPath) + suffix;
65
68
  preparePath(path);
66
69
  database = new Database(path, { create: true });
67
70
  database.exec("PRAGMA locking_mode = NORMAL; PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
@@ -127,3 +130,25 @@ export function withClientLifecycleSync<T>(
127
130
  finally { activeLeases.delete(held); }
128
131
  return finish(database, outcome);
129
132
  }
133
+
134
+ /**
135
+ * D: one ocx disconnect attempt at a time, held across the whole attempt.
136
+ *
137
+ * A disconnect restores Codex outside L, so two attempts used to share one prepared receipt
138
+ * there; rolling back one attempt's receipt then removed the other's while it was still
139
+ * restoring. D is a separate lock so taking it never orders against N, L or C.
140
+ */
141
+ export async function withClientDisconnectAttempt<T>(work: () => Promise<T>, deps: ClientLifecycleLockDeps = {}): Promise<T> {
142
+ let database: Database;
143
+ try { database = acquire(deps, "client-disconnect-attempt.sqlite", ".disconnect-attempt"); }
144
+ catch (error) {
145
+ if (errorCode(error) === "client_lifecycle_busy") {
146
+ throw new ClientLifecycleError("client_disconnect_busy: another ocx disconnect is running on this machine; let it finish, then run ocx disconnect again");
147
+ }
148
+ throw error;
149
+ }
150
+ let outcome: Outcome<T>;
151
+ try { outcome = { ok: true, value: await work() }; }
152
+ catch (error) { outcome = { ok: false, error }; }
153
+ return finish(database, outcome);
154
+ }
@@ -6,7 +6,8 @@
6
6
  * when this process starts its own replacement, so:
7
7
  *
8
8
  * - Under the desktop app or a viable service supervisor the restart is refused (409
9
- * `restart_supervised`) and the runtime keeps serving. The supervisor owns this process and its
9
+ * `restart_supervised`) and the runtime keeps serving. A runtime whose only owner evidence is a
10
+ * bare OCX_SERVICE=1 is always refused (`legacy-flag`), connection ended or not (#8545). The supervisor owns this process and its
10
11
  * port; handing off to it means exiting before anything proves the replacement can start.
11
12
  * - Unless the connection it serves is no longer the durable one (`ocx disconnect`, or a newer
12
13
  * connect). Then there is nothing to keep, and under every owner the restart hands off to the
@@ -36,12 +37,18 @@ type ClientConnectionState = ReturnType<typeof readClientConnectionState>;
36
37
  * `service-unproven`: a service manager's marker shows it launched and owns this process, but its
37
38
  * relaunch cannot be proven (for example a systemd unit started by hand while disabled). Neither
38
39
  * exiting for it nor detaching from it is safe, so the restart is refused.
40
+ *
41
+ * `legacy-flag`: the only owner evidence is a bare OCX_SERVICE=1, which a service registered before
42
+ * the manager marker existed (before 2.49.0) and the proxies of ocx claude, ocx codex and ocx opencode
43
+ * all carry. Nothing tells them apart, and the owner is never inferred (not from the service
44
+ * diagnostic, not from the parent's command line), so the restart is refused with advice to
45
+ * re-register the service once (#8545 owner decision, 2026-11-16).
39
46
  */
40
- export type ClientRestartSupervisor = "service" | "desktop" | "service-unproven";
47
+ export type ClientRestartSupervisor = "service" | "desktop" | "service-unproven" | "legacy-flag";
41
48
 
42
- /** Verdicts that keep the runtime: an owner exists, but exiting for it or detaching is not proven safe. */
43
- export function restartRefusedByOwner(supervisor: ClientRestartSupervisor | null): supervisor is "service-unproven" {
44
- return supervisor === "service-unproven";
49
+ /** Verdicts that keep the runtime: exiting for the owner or detaching from it is not proven safe. */
50
+ export function restartRefusedByOwner(supervisor: ClientRestartSupervisor | null): supervisor is "service-unproven" | "legacy-flag" {
51
+ return supervisor === "service-unproven" || supervisor === "legacy-flag";
45
52
  }
46
53
 
47
54
  export type ClientRestartAdmission =
@@ -58,7 +65,7 @@ export interface ClientRestartIo {
58
65
  connectionChanged?: () => boolean;
59
66
  /**
60
67
  * Positive evidence of who owns this process ({@link restartOwnerProven}). Without it the
61
- * ended-connection recycle is never reached and the restart is origin/dev's.
68
+ * ended-connection recycle is never reached, and the supervisor check refuses the restart.
62
69
  */
63
70
  ownerProven?: () => boolean;
64
71
  /**
@@ -140,7 +147,7 @@ export function createClientRestartController(io: ClientRestartIo): ClientRestar
140
147
  async request() {
141
148
  if (io.stopping?.()) return { kind: "stopping" };
142
149
  // Only positive ownership evidence opens the ended-connection recycle; without it (a bare
143
- // OCX_SERVICE=1) the request takes origin/dev's path below.
150
+ // OCX_SERVICE=1) the supervisor check below refuses the request as `legacy-flag`.
144
151
  if (io.recycle && (io.ownerProven?.() ?? true) && io.connectionChanged?.()) {
145
152
  if (flight) return { kind: "accepted", alreadyRestarting: true };
146
153
  // An owner that cannot be proven to relaunch this process keeps it, connection ended or not.
@@ -175,8 +182,7 @@ export function createClientRestartController(io: ClientRestartIo): ClientRestar
175
182
  /** Production supervision check: the desktop app, then a service that will really relaunch us. */
176
183
  export async function clientRestartSupervisor(): Promise<ClientRestartSupervisor | null> {
177
184
  const { diagnoseService } = await import("../service/diagnostics");
178
- const { isServiceViable } = await import("../service/orchestration");
179
- return classifyClientRestartSupervisor({ desktop: isDesktopSupervised(), env: process.env, diagnose: diagnoseService, legacyServiceViable: isServiceViable });
185
+ return classifyClientRestartSupervisor({ desktop: isDesktopSupervised(), env: process.env, diagnose: diagnoseService });
180
186
  }
181
187
 
182
188
  /**
@@ -202,26 +208,32 @@ export function restartOwnerEvidence(input: { desktop: boolean; env: NodeJS.Proc
202
208
  return input.env.OCX_SERVICE !== "1" ? "none" : null;
203
209
  }
204
210
 
211
+ /** What a client runtime with a bare OCX_SERVICE=1 states in its record: no owner, and `ocx disconnect` gives the advice. */
212
+ export const LEGACY_FLAG_RESTART_OWNER = "legacy-flag";
213
+ export type RecordedRestartOwner = RestartOwner | typeof LEGACY_FLAG_RESTART_OWNER;
214
+
215
+ /** The record's `restartOwner`: the proven owner, or `legacy-flag` for a bare OCX_SERVICE=1. */
216
+ export function recordedRestartOwner(input: { desktop: boolean; env: NodeJS.ProcessEnv; managed?: (env: NodeJS.ProcessEnv) => boolean }): RecordedRestartOwner {
217
+ return restartOwnerEvidence(input) ?? LEGACY_FLAG_RESTART_OWNER;
218
+ }
219
+
205
220
  /**
206
221
  * Ownership and relaunch are separate facts. With a manager's marker, only a service diagnostic
207
222
  * that is viable and running lets this process exit for the manager to relaunch it; otherwise it is
208
- * `service-unproven` and keeps the runtime. A bare OCX_SERVICE=1 keeps origin/dev's decision
209
- * unchanged (b1148220574917c8 src/client/runtime-restart.ts:114-119): a viable service, else none.
223
+ * `service-unproven` and keeps the runtime. A bare OCX_SERVICE=1 is `legacy-flag` whatever the
224
+ * service diagnostic says: refused, never stopped or replaced on inference (#8545).
210
225
  */
211
226
  export function classifyClientRestartSupervisor(input: {
212
227
  desktop: boolean;
213
228
  env: NodeJS.ProcessEnv;
214
229
  diagnose: () => { viable: boolean; running: boolean };
215
- /** origin/dev's check for a bare OCX_SERVICE=1: src/service/orchestration.ts isServiceViable. */
216
- legacyServiceViable: () => boolean;
217
230
  /** Manager-launched evidence; defaults to the current markers only (isMarkedSupervisedServiceChild). */
218
231
  managed?: (env: NodeJS.ProcessEnv) => boolean;
219
232
  }): ClientRestartSupervisor | null {
220
233
  if (input.desktop) return "desktop";
221
234
  // The managed marker (launchd, systemd, WinSW) or the Windows wrapper's protocol marker.
222
235
  if (!(input.managed ?? isMarkedSupervisedServiceChild)(input.env)) {
223
- if (input.env.OCX_SERVICE !== "1") return null;
224
- return input.legacyServiceViable() ? "service" : null;
236
+ return input.env.OCX_SERVICE !== "1" ? null : "legacy-flag";
225
237
  }
226
238
  // Relaunch needs positive evidence: viable AND running (launchd's viable also covers an
227
239
  // unknown load state for its other callers; running there means loaded).
@@ -31,7 +31,7 @@ import { clientLinkStatePath, isChildInitiatedLink, recordChildInitiatedLink } f
31
31
  import { startMachineListener, type MachineListenerDeps } from "./machine-listener";
32
32
  import { isLinkConnection, readClientConnectionState, readClientConnectionStateWithEvidence } from "./state";
33
33
  import { withClientLifecycleSync } from "./lifecycle-lock";
34
- import { clientConnectionEnded, clientRestartRollbackAction, clientRestartSupervisor, createClientRestartController, restartOwnerEvidence, type ClientRestartController, type RestartOwner } from "./runtime-restart";
34
+ import { clientConnectionEnded, clientRestartRollbackAction, clientRestartSupervisor, createClientRestartController, LEGACY_FLAG_RESTART_OWNER, restartOwnerEvidence, type ClientRestartController, type RecordedRestartOwner, type RestartOwner } from "./runtime-restart";
35
35
  import { createLinkParityReporter, type LinkParityReporter } from "./link-parity-reporter";
36
36
  import { restoreLinkClientRouting } from "./stop-routing";
37
37
  import { SUPERVISOR_MARKER_ENVS } from "../lib/supervisor-markers";
@@ -110,7 +110,7 @@ export function clientRuntimeRecord(
110
110
  pid: number,
111
111
  port: number,
112
112
  attestationSecret: string = createLocalAttestationSecret(),
113
- owner: RestartOwner | null = classifiedOwner(),
113
+ owner: RecordedRestartOwner | null = recordedOwner(),
114
114
  ): RuntimePortState {
115
115
  let command: string[] | undefined;
116
116
  try { command = currentServingCommand(); } catch { /* no reliable relaunch identity; update admission fails closed */ }
@@ -124,6 +124,8 @@ function classifiedOwner(): RestartOwner | null {
124
124
  return ownerMemo.value;
125
125
  }
126
126
  const ownerProven = (): boolean => classifiedOwner() !== null;
127
+ /** The record's owner: the proven one, or legacy-flag for a bare OCX_SERVICE=1 (#8545; recordedRestartOwner). */
128
+ const recordedOwner = (): RecordedRestartOwner => classifiedOwner() ?? LEGACY_FLAG_RESTART_OWNER;
127
129
 
128
130
  export function standaloneRecycleEnv(
129
131
  env: NodeJS.ProcessEnv,
@@ -162,6 +162,20 @@ export function assertNoClientDisconnectPending(): void {
162
162
  }
163
163
  }
164
164
 
165
+ /**
166
+ * The message client startup refuses with. A pending disconnect names the command that clears it:
167
+ * under the desktop app or a service the supervisor only logs this line, and on 2.100.2 a person
168
+ * had to move desktop-remote/ aside by hand because nothing said a retry would finish or roll back.
169
+ */
170
+ export function clientStartupRefusalMessage(reason: string): string {
171
+ if (reason !== "client_disconnect_pending") return `client startup refused: ${reason}`;
172
+ const receipt = readDesktopDisconnectReceipt();
173
+ const valid = receipt.kind === "valid" ? receipt.value : null;
174
+ const command = valid?.keepCatalog ? "ocx disconnect --keep-catalog" : "ocx disconnect";
175
+ return `client startup refused: an ocx disconnect on this machine stopped part way${valid ? ` at phase ${valid.phase}` : ""}. `
176
+ + `Run ${command} again to finish it or roll it back. (code client_disconnect_pending)`;
177
+ }
178
+
165
179
  /** Full snapshot CAS for work returning from an await, including selection and rotation state. */
166
180
  export function assertClientConnectionUnchanged(expected: OcxClientConnectionConfig): void {
167
181
  assertNoClientDisconnectPending();