@bitkyc08/opencodex 2.92.0 → 2.93.0-preview.20261027

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 (259) hide show
  1. package/bin/ocx.mjs +10 -5
  2. package/gui/dist/assets/App-CJZoq-uF.js +58 -0
  3. package/gui/dist/assets/{Tray-BSsxznDm.js → Tray-BWQPcgZn.js} +1 -1
  4. package/gui/dist/assets/index-DRe8Hhfz.css +1 -0
  5. package/gui/dist/assets/{index-BlFE_VB_.js → index-Xfct8owH.js} +12 -12
  6. package/gui/dist/assets/{quota-summary-BRlbXgw0.js → quota-summary-DxToX1rV.js} +1 -1
  7. package/gui/dist/index.html +2 -2
  8. package/package.json +5 -5
  9. package/src/adapters/anthropic.ts +28 -5
  10. package/src/adapters/coding-agent/batch-dispatcher.ts +122 -0
  11. package/src/adapters/coding-agent/profile.ts +54 -16
  12. package/src/adapters/coding-agent/turn.ts +30 -2
  13. package/src/adapters/command-code.ts +114 -7
  14. package/src/adapters/cursor/native-exec-fs.ts +11 -9
  15. package/src/adapters/devin/live-models.ts +4 -0
  16. package/src/adapters/google-wire-compiler.ts +1 -2
  17. package/src/adapters/kiro/reasoning.ts +2 -0
  18. package/src/adapters/kiro-refusal.ts +6 -1
  19. package/src/adapters/kiro-wire.ts +1 -1
  20. package/src/adapters/openai-chat/messages.ts +8 -2
  21. package/src/adapters/openai-chat/passthrough.ts +35 -14
  22. package/src/adapters/openai-chat/reasoning-replay.ts +27 -16
  23. package/src/adapters/openai-chat/reasoning-wire.ts +117 -8
  24. package/src/adapters/openai-chat/required-tool-result.ts +64 -0
  25. package/src/adapters/openai-chat.ts +7 -8
  26. package/src/adapters/openai-responses/passthrough.ts +7 -4
  27. package/src/adapters/openai-responses/reasoning.ts +13 -0
  28. package/src/adapters/openai-responses/request-strips.ts +1 -1
  29. package/src/adapters/qoder/adapter.ts +129 -8
  30. package/src/adapters/qoder/scaffold-guard.ts +5 -0
  31. package/src/adapters/reasoning-controls.ts +16 -0
  32. package/src/adapters/tool-call-id.ts +1 -3
  33. package/src/bridge/errors.ts +27 -0
  34. package/src/bridge.ts +1 -1
  35. package/src/chat/inbound.ts +4 -1
  36. package/src/chat/outbound.ts +9 -2
  37. package/src/chat/reasoning-details.ts +28 -5
  38. package/src/claude/desktop-first-party.ts +54 -4
  39. package/src/claude/desktop-picker.ts +11 -8
  40. package/src/claude/first-party-settings.ts +3 -1
  41. package/src/claude/inbound.ts +2 -1
  42. package/src/claude/intercept/local-ca.ts +2 -1
  43. package/src/claude/intercept/picker-ca-cleanup.ts +4 -2
  44. package/src/claude/intercept/picker-ca-startup.ts +3 -1
  45. package/src/claude/intercept/picker-models.ts +6 -3
  46. package/src/claude/intercept/picker-runtime.ts +3 -2
  47. package/src/claude/intercept/runtime.ts +6 -3
  48. package/src/claude/model-info.ts +31 -8
  49. package/src/cli/account-api.ts +11 -0
  50. package/src/cli/capabilities-agents-routing.ts +2 -2
  51. package/src/cli/capabilities-base.ts +7 -1
  52. package/src/cli/capabilities-observe-system.ts +10 -0
  53. package/src/cli/claude-desktop.ts +9 -8
  54. package/src/cli/claude.ts +3 -2
  55. package/src/cli/codex-shim-autorestore.ts +9 -0
  56. package/src/cli/combo-result.ts +7 -0
  57. package/src/cli/combo.ts +18 -0
  58. package/src/cli/cross-home-owner.ts +13 -1
  59. package/src/cli/dispatch.ts +25 -6
  60. package/src/cli/ensure-desired-integrations.ts +8 -6
  61. package/src/cli/export-command.ts +4 -1
  62. package/src/cli/help.ts +2 -1
  63. package/src/cli/index.ts +45 -45
  64. package/src/cli/integration-plan-dto.ts +4 -0
  65. package/src/cli/opencode.ts +20 -9
  66. package/src/cli/registry.ts +6 -4
  67. package/src/cli/root.ts +9 -0
  68. package/src/cli/status.ts +59 -1
  69. package/src/cli/stop-restore.ts +113 -0
  70. package/src/cli/sync-expectation.ts +60 -0
  71. package/src/cli/uninstall-integrations.ts +41 -7
  72. package/src/client/connect.ts +40 -3
  73. package/src/client/link-home.ts +10 -1
  74. package/src/client/machine-api.ts +3 -1
  75. package/src/client/sync-expectation.ts +118 -0
  76. package/src/clients/config-export/agent-clients.ts +96 -0
  77. package/src/clients/config-export/contracts.ts +25 -7
  78. package/src/clients/config-export/qoder.ts +38 -23
  79. package/src/clients/config-export/reasoning-metadata.ts +55 -8
  80. package/src/clients/config-export.ts +12 -0
  81. package/src/clients/lazycodex.ts +7 -2
  82. package/src/clients/reasoning-controls.ts +49 -0
  83. package/src/codex/auth-api/account-identity.ts +14 -0
  84. package/src/codex/auth-api/account-list.ts +29 -2
  85. package/src/codex/auth-api/http.ts +13 -0
  86. package/src/codex/auth-api/main-account-probe.ts +2 -2
  87. package/src/codex/auth-api/pool-mode-gate.ts +16 -3
  88. package/src/codex/auth-api/pool-quota-probe.ts +15 -0
  89. package/src/codex/auth-context.ts +15 -12
  90. package/src/codex/catalog/build-entries.ts +22 -0
  91. package/src/codex/catalog/configured-tiers.ts +70 -0
  92. package/src/codex/catalog/effort.ts +44 -10
  93. package/src/codex/catalog/gather-capture.ts +1 -0
  94. package/src/codex/catalog/heal-observation.ts +155 -13
  95. package/src/codex/catalog/metadata.ts +6 -0
  96. package/src/codex/catalog/model-hints.ts +60 -11
  97. package/src/codex/catalog/model-visibility.ts +3 -2
  98. package/src/codex/catalog/native-models.ts +18 -3
  99. package/src/codex/catalog/parsing.ts +10 -8
  100. package/src/codex/catalog/pinned-models.ts +2 -1
  101. package/src/codex/catalog/provider-models.ts +4 -5
  102. package/src/codex/catalog/retained-sync.ts +2 -1
  103. package/src/codex/catalog/routed-gather.ts +19 -20
  104. package/src/codex/catalog/write-audit.ts +3 -2
  105. package/src/codex/catalog-self-heal.ts +43 -23
  106. package/src/codex/collision-identity.ts +30 -5
  107. package/src/codex/convergence.ts +4 -3
  108. package/src/codex/data/roster-pinned-models.json +177 -1
  109. package/src/codex/desired-state.ts +6 -1
  110. package/src/codex/desktop-compatibility/installed-build.ts +88 -12
  111. package/src/codex/desktop-compatibility/runtime.ts +29 -5
  112. package/src/codex/desktop-compatibility/usage-controller.ts +2 -0
  113. package/src/codex/desktop-compatibility/windows-certificate-trust.ts +46 -12
  114. package/src/codex/inject/config-toml.ts +0 -18
  115. package/src/codex/inject/plan.ts +18 -3
  116. package/src/codex/inject/remove.ts +6 -2
  117. package/src/codex/inject.ts +1 -1
  118. package/src/codex/journal.ts +61 -1
  119. package/src/codex/model-entitlements.ts +1 -1
  120. package/src/codex/native-main-owner.ts +27 -1
  121. package/src/codex/native-profile-store.ts +2 -1
  122. package/src/codex/pool-credit-policy.ts +35 -1
  123. package/src/codex/quota-types.ts +3 -0
  124. package/src/codex/quota.ts +24 -4
  125. package/src/codex/role-auto-assign.ts +6 -2
  126. package/src/codex/subagent-defaults.ts +49 -4
  127. package/src/combos/failover.ts +17 -2
  128. package/src/combos/jev-decision-contract.ts +22 -1
  129. package/src/combos/jev-service-exchange.ts +3 -1
  130. package/src/combos/jev.ts +95 -9
  131. package/src/combos/resolve.ts +45 -1
  132. package/src/combos/types.ts +24 -0
  133. package/src/config/load-degrade.ts +5 -0
  134. package/src/config/paths.ts +19 -3
  135. package/src/config/pending-teardown.ts +22 -1
  136. package/src/config/provider-validation.ts +15 -4
  137. package/src/config/removed-opencode-free.ts +11 -0
  138. package/src/config/schema/leaf-validators.ts +5 -0
  139. package/src/generated/compatibility-version.json +314 -230
  140. package/src/generated/model-metadata.ts +5 -5
  141. package/src/images/loop.ts +16 -2
  142. package/src/integrations/catalog-refresh.ts +1 -1
  143. package/src/integrations/hermes-profiles.ts +251 -0
  144. package/src/integrations/merge.ts +8 -0
  145. package/src/integrations/mutation-plan.ts +19 -4
  146. package/src/integrations/registry.ts +5 -0
  147. package/src/integrations/state.ts +36 -1
  148. package/src/integrations/writer.ts +18 -4
  149. package/src/lib/bun-path-runtime.mjs +2 -1
  150. package/src/lib/errors.ts +62 -0
  151. package/src/lib/eventstream-decoder.ts +81 -37
  152. package/src/lib/opaque-proxy-tunnel.ts +32 -8
  153. package/src/lib/pinned-http.ts +35 -2
  154. package/src/lib/process-control.ts +13 -1
  155. package/src/lib/socks5-fetch.ts +59 -64
  156. package/src/lib/socks5-upload-waiter.ts +50 -0
  157. package/src/lib/sse-decoder.ts +7 -2
  158. package/src/lib/state-store-sweeper.ts +40 -14
  159. package/src/lib/windows-native-principal-worker.ts +14 -0
  160. package/src/lib/windows-native-principal.ts +188 -0
  161. package/src/lib/windows-secret-acl.ts +39 -3
  162. package/src/lib/windows-user-principal.ts +62 -18
  163. package/src/link/ssh-config.ts +35 -3
  164. package/src/providers/account-quota-disk.ts +12 -4
  165. package/src/providers/codebuddy-models.ts +6 -0
  166. package/src/providers/codex-capacity.ts +3 -1
  167. package/src/providers/derive.ts +28 -0
  168. package/src/providers/kiro-models.ts +3 -0
  169. package/src/providers/mimo-thinking.ts +12 -0
  170. package/src/providers/model-rename-fields.ts +1 -0
  171. package/src/providers/model-rename-migration.ts +10 -0
  172. package/src/providers/openai-sidecar-credit.ts +2 -2
  173. package/src/providers/reasoning-capabilities.ts +76 -0
  174. package/src/providers/registry/entries-core.ts +14 -12
  175. package/src/providers/registry/entries-extended.ts +63 -20
  176. package/src/providers/registry/model-ids.ts +2 -0
  177. package/src/providers/registry/model-seeds.ts +93 -28
  178. package/src/providers/registry/types.ts +10 -1
  179. package/src/providers/resolved-model-policy.ts +26 -6
  180. package/src/providers/routed-config.ts +9 -1
  181. package/src/providers/stale-model-roster-migration.ts +44 -7
  182. package/src/remote-control/workspace-pi-runtime.ts +11 -6
  183. package/src/responses/compaction-summary.ts +45 -0
  184. package/src/responses/muse-tool-name-alias.ts +1 -2
  185. package/src/responses/parser.ts +3 -2
  186. package/src/responses/schema.ts +1 -0
  187. package/src/responses/thought-signature-replay.ts +10 -2
  188. package/src/routing/capability.ts +8 -2
  189. package/src/routing/history/ingest.ts +28 -3
  190. package/src/server/auth-cors.ts +3 -2
  191. package/src/server/chat-completions.ts +7 -0
  192. package/src/server/chat-native-eligibility.ts +7 -0
  193. package/src/server/chat-native-reasoning.ts +14 -4
  194. package/src/server/direct-local-http.ts +5 -2
  195. package/src/server/effort-policy.ts +5 -1
  196. package/src/server/index/live-sideband.ts +18 -15
  197. package/src/server/index/serve-options.ts +5 -4
  198. package/src/server/management/agent-settings-routes.ts +27 -15
  199. package/src/server/management/combo-routes.ts +4 -0
  200. package/src/server/management/config-routes.ts +2 -2
  201. package/src/server/management/decision-discovery.ts +12 -2
  202. package/src/server/management/hermes-profile-routes.ts +156 -0
  203. package/src/server/management/integration-routes.ts +85 -24
  204. package/src/server/management/model-routes.ts +2 -2
  205. package/src/server/management/model-row-export-metadata.ts +25 -6
  206. package/src/server/management/model-rows.ts +15 -20
  207. package/src/server/management/native-integration-routes.ts +11 -8
  208. package/src/server/management/route-registry.ts +4 -0
  209. package/src/server/management-api.ts +5 -0
  210. package/src/server/models-capabilities.ts +21 -3
  211. package/src/server/responses/adapter-delivery.ts +11 -1
  212. package/src/server/responses/adapter-dispatch.ts +2 -2
  213. package/src/server/responses/codex-ws-exchange.ts +39 -9
  214. package/src/server/responses/codex-ws-session.ts +38 -4
  215. package/src/server/responses/codex-ws-wire.ts +6 -1
  216. package/src/server/responses/combo-required-tool-contract.ts +103 -0
  217. package/src/server/responses/combo-stream-preflight.ts +8 -1
  218. package/src/server/responses/compact.ts +4 -3
  219. package/src/server/responses/context-overflow.ts +8 -1
  220. package/src/server/responses/core-combo-failure.ts +10 -0
  221. package/src/server/responses/core-combo.ts +23 -15
  222. package/src/server/responses/core-lifetime.ts +3 -0
  223. package/src/server/responses/core-normalize.ts +11 -1
  224. package/src/server/responses/core-options.ts +2 -0
  225. package/src/server/responses/main-hard-lock-routing.ts +60 -44
  226. package/src/server/responses/passthrough-delivery.ts +40 -2
  227. package/src/server/responses/policy-fallback.ts +6 -1
  228. package/src/server/responses/request-compression.ts +12 -7
  229. package/src/server/responses/request-prepare.ts +22 -2
  230. package/src/server/responses/request-sidecar-auth.ts +2 -0
  231. package/src/server/responses/response-effects.ts +22 -10
  232. package/src/server/responses/sidecar-execution.ts +11 -3
  233. package/src/server/stop-teardown.ts +36 -1
  234. package/src/server/ws-bridge.ts +1 -1
  235. package/src/service/desktop-supervision.d.mts +7 -4
  236. package/src/service/desktop-supervision.mjs +90 -13
  237. package/src/service/ownership-mutation-lease.mjs +21 -7
  238. package/src/types/config.ts +8 -2
  239. package/src/types/provider.ts +20 -6
  240. package/src/types/request.ts +10 -0
  241. package/src/types.ts +1 -0
  242. package/src/update/bind-probe.ts +29 -0
  243. package/src/update/job.ts +10 -29
  244. package/src/update/npm-install-job.ps1 +173 -0
  245. package/src/update/npm-install.mjs +70 -0
  246. package/src/update/stop-contract.d.mts +1 -0
  247. package/src/update/stop-contract.mjs +14 -0
  248. package/src/update/stop-decision.d.mts +1 -1
  249. package/src/update/stop-decision.mjs +13 -3
  250. package/src/update/teardown-handover.ts +166 -0
  251. package/src/update/transactional-install.d.mts +14 -3
  252. package/src/update/transactional-install.mjs +33 -7
  253. package/src/usage/expected-prices.ts +64 -31
  254. package/src/usage/timeline.ts +19 -9
  255. package/src/vision/eligibility.ts +15 -5
  256. package/src/vision/plan.ts +2 -2
  257. package/src/web-search/loop.ts +16 -2
  258. package/gui/dist/assets/App-sUf_8afJ.js +0 -58
  259. package/gui/dist/assets/index-DPeB9HpV.css +0 -1
@@ -27,6 +27,9 @@ export const FILE_INTEGRATION_CLIENTS = [
27
27
  "kilo",
28
28
  "droid",
29
29
  "qoder",
30
+ "qoder-cn",
31
+ "workbuddy",
32
+ "workbuddy-ai",
30
33
  "gentle-shell",
31
34
  ] as const;
32
35
 
@@ -57,6 +60,7 @@ const MISSING_STORE_DOCUMENT = /^[\x20-\x7e]{1,64}$/;
57
60
  const PLAN_CHANGE_KEYS = new Set(["kind", "path"]);
58
61
  const PLAN_PSEUDO_PATHS = new Set(["$snapshot", "$ownership", "$journal"]);
59
62
  const PLAN_SCHEMA_PATHS = new Set([
63
+ "*", // A WorkBuddy legacy document is a top-level model array.
60
64
  "provider.opencodex",
61
65
  "providers.opencodex",
62
66
  "models.providers.opencodex",
@@ -40,6 +40,7 @@ import type {
40
40
  OpencodeV2ProviderBlock,
41
41
  } from "../clients/config-export";
42
42
  import type { EffectiveModelExportMetadata } from "../clients/config-export/contracts";
43
+ import { resolveExportReasoningAxes } from "../clients/config-export/reasoning-metadata";
43
44
  import { filterCatalogVisibleModels, visibleNativeSlugs } from "../codex/catalog";
44
45
  import { commandInvocation } from "../lib/win-exec";
45
46
  import { configuredAdminToken, opencodeCatalogToken } from "../lib/admin-secrets";
@@ -91,6 +92,11 @@ export interface OpencodeRoutedModel {
91
92
  displayName?: string;
92
93
  /** Declared effort ladder; exported as opencode model variants when present. */
93
94
  reasoningEfforts?: readonly string[];
95
+ supportsReasoning?: boolean;
96
+ supportsThinkingToggle?: boolean;
97
+ supportsReasoningEffort?: boolean;
98
+ defaultThinkingEnabled?: boolean;
99
+ defaultReasoningEffort?: string;
94
100
  }
95
101
 
96
102
  /** Row shape from authenticated GET /api/models on the running proxy. */
@@ -120,6 +126,9 @@ export interface OpencodeProxyModelRow {
120
126
  inputModalities?: string[];
121
127
  /** Declared effort ladder from `/api/models`; carried into opencode model variants. */
122
128
  reasoningEfforts?: string[];
129
+ supportsThinkingToggle?: boolean;
130
+ supportsReasoningEffort?: boolean;
131
+ defaultThinkingEnabled?: boolean;
123
132
  /** Declared default effort from `/api/models`. */
124
133
  defaultReasoningEffort?: string;
125
134
  /**
@@ -180,9 +189,14 @@ function opencodeLaunchCatalog(
180
189
  id: model.id,
181
190
  contextWindow: model.contextWindow,
182
191
  displayName: model.displayName,
183
- ...(model.reasoningEfforts && model.reasoningEfforts.length > 0
192
+ ...(model.reasoningEfforts !== undefined
184
193
  ? { reasoningEfforts: [...model.reasoningEfforts] }
185
194
  : {}),
195
+ ...(model.supportsReasoning !== undefined ? { supportsReasoning: model.supportsReasoning } : {}),
196
+ ...(model.supportsThinkingToggle !== undefined ? { supportsThinkingToggle: model.supportsThinkingToggle } : {}),
197
+ ...(model.supportsReasoningEffort !== undefined ? { supportsReasoningEffort: model.supportsReasoningEffort } : {}),
198
+ ...(model.defaultThinkingEnabled !== undefined ? { defaultThinkingEnabled: model.defaultThinkingEnabled } : {}),
199
+ ...(model.defaultReasoningEffort !== undefined ? { defaultReasoningEffort: model.defaultReasoningEffort } : {}),
186
200
  })),
187
201
  ];
188
202
  }
@@ -372,14 +386,8 @@ export function opencodeCatalogFromProxyRows(
372
386
  const maxTokens = effective?.maxTokens ?? row.maxOutputTokens;
373
387
  const maxInputTokens = effective?.maxInputTokens ?? row.maxInputTokens;
374
388
  const inputModalities = effective?.inputModalities ?? row.inputModalities;
375
- const reasoningEfforts = effective?.reasoningEfforts ?? row.reasoningEfforts;
376
- // The projection is the authority on the default: when it exists, an absent default means
377
- // NO declared default, and falling back to the row would reintroduce the picker's
378
- // synthetic medium/low value. Rows without one (older hubs, hand-built rows) keep the
379
- // row's own value.
380
- const defaultReasoningEffort = effective !== undefined
381
- ? effective.defaultReasoningEffort
382
- : row.defaultReasoningEffort;
389
+ const { supportsThinkingToggle, supportsReasoningEffort, defaultThinkingEnabled,
390
+ reasoningEfforts, defaultReasoningEffort } = resolveExportReasoningAxes(effective, row);
383
391
  const supportsTools = effective?.supportsTools ?? row.supportsTools;
384
392
  const supportsReasoning = effective?.supportsReasoning ?? row.supportsReasoning;
385
393
  const supportsReasoningSummaries = effective?.supportsReasoningSummaries ?? row.supportsReasoningSummaries;
@@ -398,6 +406,9 @@ export function opencodeCatalogFromProxyRows(
398
406
  ...(typeof row.fastRowAvailable === "boolean" ? { fastRowAvailable: row.fastRowAvailable } : {}),
399
407
  // `[]` is a declaration, not an absence: an explicit no-rungs ladder stays empty here.
400
408
  ...(Array.isArray(reasoningEfforts) ? { reasoningEfforts: [...reasoningEfforts] } : {}),
409
+ ...(typeof supportsThinkingToggle === "boolean" ? { supportsThinkingToggle } : {}),
410
+ ...(typeof supportsReasoningEffort === "boolean" ? { supportsReasoningEffort } : {}),
411
+ ...(typeof defaultThinkingEnabled === "boolean" ? { defaultThinkingEnabled } : {}),
401
412
  ...(typeof defaultReasoningEffort === "string" && defaultReasoningEffort.length > 0
402
413
  ? { defaultReasoningEffort }
403
414
  : {}),
@@ -50,7 +50,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
50
50
  {
51
51
  name: "stop",
52
52
  usage: "ocx stop [--json]",
53
- summary: "Stop the proxy and restore native Codex config.",
53
+ summary: "Stop the proxy; preserve connected-client integrations, restore native Codex config for standalone owners.",
54
54
  details: [
55
55
  "--json keeps the stop path unchanged and prints one structured summary document on stdout; human output moves to stderr.",
56
56
  "Exit codes are identical with and without --json: 0, 1, 79 (history cleanup incomplete), 80 (teardown deferred).",
@@ -181,13 +181,15 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
181
181
  },
182
182
  {
183
183
  name: "sync",
184
- usage: "ocx sync [--restart-codex] [--restart-app-server-only]",
184
+ usage: "ocx sync [--expect-link <linkId> | --expect-hub-key <apiKeyId>] [--restart-codex] [--restart-app-server-only]",
185
185
  summary: "Fetch provider models and inject them into Codex config.",
186
186
  details: [
187
187
  "After writing the catalog, warns if long-lived Codex app-server processes are still running.",
188
188
  "--restart-codex restarts the app-servers AND fully quits and relaunches the Codex desktop app on macOS, Linux and Windows, after catalog/cache writes or a committed configuration change. It ends live conversations.",
189
189
  "--restart-app-server-only keeps the narrow behaviour: SIGTERM to matching app-server / code-mode-host processes, desktop app left running. It wins over --restart-codex when both are given.",
190
190
  "--restart-desktop-app is a deprecated alias of --restart-codex and prints a notice.",
191
+ "--expect-link <linkId> syncs only when this machine is a connected Remote Link Child of that link (ocx connect status --json reports link.linkId); --expect-hub-key <apiKeyId> does the same for a hub client's key. The check runs under the lock that chooses the sync path.",
192
+ "Any other state (disconnected, another link or key, the other client kind, a pending key rotation, connect or disconnect) changes nothing, never syncs local providers, exits 5, and prints {\"phase\":\"child_link_mismatch\"|\"hub_client_mismatch\",\"reason\":...} as the last stderr line. A malformed or repeated flag exits 2.",
191
193
  ],
192
194
  },
193
195
  {
@@ -516,8 +518,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
516
518
  },
517
519
  {
518
520
  name: "export",
519
- usage: "ocx export --client <qoder|opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|commandcode|prime|aside|raycast|omo|cline|kilo|droid|gentle-shell> [--json] [--out <path>] [--force]",
520
- summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Command Code, Prime Agent, Aside, Raycast, omo, Cline, Kilo, Factory Droid, Qoder, Gentle Shell) wired to the running proxy.",
521
+ usage: "ocx export --client <qoder|qoder-cn|workbuddy|workbuddy-ai|opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|commandcode|prime|aside|raycast|omo|cline|kilo|droid|gentle-shell> [--json] [--out <path>] [--force]",
522
+ summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, gjc, DeepSeek Harness, MiniMax Code, ZCode, Command Code, Prime Agent, Aside, Raycast, omo, Cline, Kilo, Factory Droid, Qoder, Qoder CN, WorkBuddy, WorkBuddy AI, Gentle Shell) wired to the running proxy.",
521
523
  details: [
522
524
  "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
523
525
  "--out <path> writes the native config there and refuses to replace an existing file without --force.",
package/src/cli/root.ts CHANGED
@@ -12,6 +12,7 @@ import { printFullUsage, printSubcommandUsage, printUsage, printVersion } from "
12
12
  import { parseReadyArgs, type ReadyArgs } from "./ready";
13
13
  import { parseResolveArgs, type ResolveArgs } from "./resolve";
14
14
  import { parseStopApproval } from "./stop-approval";
15
+ import { parseSyncExpectation, SYNC_EXPECTATION_USAGE_EXIT } from "./sync-expectation";
15
16
  import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
16
17
  import { findCommand } from "./registry";
17
18
  import { printUnknownCommand } from "./help-recovery";
@@ -142,6 +143,14 @@ export async function runCli(argv: string[]): Promise<CliHead> {
142
143
  console.error(uninstallError);
143
144
  process.exit(2);
144
145
  }
146
+ // #7694: a malformed pinned sync is refused before any preflight reads or repairs anything.
147
+ if (head.command === "sync") {
148
+ const pinned = parseSyncExpectation(head.args.slice(1));
149
+ if (!pinned.ok) {
150
+ console.error(pinned.message);
151
+ process.exit(SYNC_EXPECTATION_USAGE_EXIT);
152
+ }
153
+ }
145
154
  await maybeNoticeVersionSkew(head.command, head.args);
146
155
  maybeAutoRestoreCodexShim(head.command, head.args);
147
156
  return head;
package/src/cli/status.ts CHANGED
@@ -715,12 +715,34 @@ export function resolveStatusPid(
715
715
  * unused", but startupHealthSummary already renders both as AT RISK with a
716
716
  * remedy command, and `custom-remote` is a deliberate operator choice. Warning
717
717
  * on all four would teach operators to skip the line that matters.
718
+ *
719
+ * A connected client (hub client or Remote Link Child) needs a different remedy (#7563): its
720
+ * runtime never writes Codex routing on start, so `ocx start` cannot re-point it — with the
721
+ * proxy up it only answers "already running". `ocx sync --restart-codex` writes the routing
722
+ * and restarts Codex. A client whose proxy is also down is told to start it first, because
723
+ * nothing else in the not-running report mentions that its routing is native.
718
724
  */
719
725
  export function unusedProxyWarningLines(input: {
720
726
  proxyUp: boolean;
721
727
  routingKind: StartupHealth["routingKind"];
728
+ connectedClient?: { transport: "hub" | "link"; serviceInstalled: boolean };
722
729
  }): string[] {
723
- if (!input.proxyUp || input.routingKind !== "native") return [];
730
+ if (input.routingKind !== "native") return [];
731
+ const client = input.connectedClient;
732
+ if (client) {
733
+ const peer = client.transport === "link" ? "the Home" : "the hub";
734
+ if (input.proxyUp) {
735
+ return [
736
+ "⚠️ Codex routing is native — this client's proxy is unused.",
737
+ ` Codex requests go to OpenAI, not ${peer}. Re-point with: ocx sync --restart-codex`,
738
+ ];
739
+ }
740
+ return [
741
+ `⚠️ Codex routing is native, so Codex requests go to OpenAI, not ${peer}.`,
742
+ ` Start this client's proxy with '${client.serviceInstalled ? "ocx service start" : "ocx start"}', then re-point with: ocx sync --restart-codex`,
743
+ ];
744
+ }
745
+ if (!input.proxyUp) return [];
724
746
  return [
725
747
  "⚠️ Codex routing is native — the running proxy is unused.",
726
748
  " Codex requests go to OpenAI, not this proxy. Re-point with: ocx start",
@@ -746,11 +768,47 @@ export function unusedProxyWarningLines(input: {
746
768
  export function deadProxyRoutingAdviceLines(input: {
747
769
  proxyUp: boolean;
748
770
  routingKind: StartupHealth["routingKind"];
771
+ /** #7563: on a connected client nothing but `ocx sync` writes the routing back after a restore. */
772
+ connectedClient?: boolean;
749
773
  }): string[] {
750
774
  if (input.proxyUp || input.routingKind !== "opencodex-local") return [];
751
775
  return [
752
776
  "Codex is still pointed at this proxy, so sign-in and model requests both fail while it is down.",
753
777
  "To hand Codex back to its own account and endpoints without starting anything: ocx restore",
778
+ ...(input.connectedClient ? ["After a restore, 'ocx sync --restart-codex' points Codex back at this client."] : []),
779
+ ];
780
+ }
781
+
782
+ type StatusRoutingView = Pick<CliStatusJson, "proxy" | "startup" | "remoteHub" | "connection">;
783
+
784
+ export function statusProxyUp(json: StatusRoutingView): boolean {
785
+ return json.remoteHub.connected && json.connection.transport === "link"
786
+ ? json.proxy.health.ok : Boolean(json.proxy.pid || json.proxy.health.ok);
787
+ }
788
+
789
+ /** `unusedProxyWarningLines` for the human `ocx status` report, role taken from the report itself. */
790
+ export function statusUnusedProxyLines(json: StatusRoutingView): string[] {
791
+ return unusedProxyWarningLines({
792
+ proxyUp: statusProxyUp(json),
793
+ routingKind: json.startup.routingKind,
794
+ ...(json.remoteHub.connected ? { connectedClient: {
795
+ transport: json.connection.transport === "link" ? "link" as const : "hub" as const,
796
+ serviceInstalled: json.startup.serviceInstalled && !json.startup.serviceConflict,
797
+ } } : {}),
798
+ });
799
+ }
800
+
801
+ /** `deadProxyRoutingAdviceLines` for the not-running half of the human `ocx status` report. */
802
+ export function statusDeadProxyLines(json: StatusRoutingView): string[] {
803
+ return [
804
+ json.startup.routingKind === "native"
805
+ ? "↳ Not running — Claude requests will fail with connection errors."
806
+ : "↳ Not running — Codex/Claude requests will fail with connection errors.",
807
+ ...deadProxyRoutingAdviceLines({
808
+ proxyUp: false,
809
+ routingKind: json.startup.routingKind,
810
+ connectedClient: json.remoteHub.connected,
811
+ }),
754
812
  ];
755
813
  }
756
814
 
@@ -1,6 +1,119 @@
1
1
  import { restoreNativeCodexAsync } from "../codex/inject";
2
2
  import type { RetainedCodexProviderTable } from "../codex/inject/restore";
3
3
  import { stripGrokConfig } from "../grok/inject";
4
+ import { readClientConnectionState, type ClientConnectionState } from "../client/state";
5
+ import { readPid, readRuntimePort } from "../config/process-state";
6
+ import { loadConfig } from "../config";
7
+ import { configuredAdminToken } from "../lib/admin-secrets";
8
+ import { readBoundedResponseBody } from "../lib/bounded-body";
9
+ import { gracefulStopHost, isProcessAlive, ProxyOwnershipRefusedError } from "../lib/process-control";
10
+ import { directLocalHttpFetch } from "../server/direct-local-http";
11
+ import { findLiveProxy, probeEndpointLiveness, proveLiveProxyOwnedByHome } from "../server/proxy-liveness";
12
+ import { observeGuardedManagerStopped } from "../service/guarded-manager-target";
13
+ import type { StartExitTeardown } from "./dispatch";
14
+ import type { StopOutcome } from "./stop-report";
15
+
16
+ /** Re-read ownership when an ordinary runtime actually exits, including after API drain. */
17
+ export function preserveConnectedClientRoutingOnExit(teardown: StartExitTeardown): StartExitTeardown {
18
+ return readClientConnectionState().kind === "connected"
19
+ ? { ...teardown, restoreNativeCodex: false, stripGrokConfig: false }
20
+ : teardown;
21
+ }
22
+
23
+ type ConnectedStopTarget = { pid: number; port: number; hostname?: string };
24
+ const CONNECTED_STOP_PROBE_MS = 2000;
25
+ const unsupportedConnectedStop = () => new ProxyOwnershipRefusedError(
26
+ "Connected-client stop refused: runtime identity, shutdown preservation or safe runtime absence could not be verified. Inspect 'ocx service status' and update/restart an incompatible runtime through its supervisor, then retry; use 'ocx disconnect' only if you intend to release those integrations.",
27
+ "connected_client_stop_unsupported",
28
+ );
29
+
30
+ /** A positive, PID-bound contract is required; old and new builds may share a version. */
31
+ export async function assertConnectedClientStopSupported(target: ConnectedStopTarget | null): Promise<void> {
32
+ if (!target) throw unsupportedConnectedStop();
33
+ if (!isProcessAlive(target.pid)) return; // A manager may already have ended this exact target.
34
+ const origin = `http://${gracefulStopHost(target.hostname)}:${target.port}`;
35
+ const signal = AbortSignal.timeout(CONNECTED_STOP_PROBE_MS);
36
+ const probe = async (path: string, authenticated: boolean): Promise<Record<string, unknown> | null> => {
37
+ try {
38
+ const headers: Record<string, string> = {};
39
+ if (authenticated) {
40
+ const token = configuredAdminToken(process.env.OPENCODEX_HOME?.trim() || undefined, process.env);
41
+ if (token) headers["x-opencodex-api-key"] = token;
42
+ }
43
+ const response = await directLocalHttpFetch(`${origin}${path}`, { method: "GET", headers, redirect: "error", signal },
44
+ { timeoutMs: CONNECTED_STOP_PROBE_MS });
45
+ if (!response.ok) { void response.body?.cancel().catch(() => {}); return null; }
46
+ const body = await readBoundedResponseBody(response, { maxBytes: 4096, signal, fatalUtf8: true });
47
+ if (body.truncated) return null;
48
+ const parsed: unknown = JSON.parse(body.text);
49
+ return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : null;
50
+ } catch { return null; }
51
+ };
52
+ const health = await probe("/healthz", false);
53
+ // The native machine listener has always preserved integrations on signal and 404s /api/stop.
54
+ if (health?.service === "opencodex" && health.role === "client" && health.pid === target.pid) return;
55
+ const capability = await probe("/api/stop", true);
56
+ if (capability?.schema === "ocx-stop-capabilities/1"
57
+ && capability.pid === target.pid && capability.connectedClientOwnership === true) return;
58
+ throw unsupportedConnectedStop();
59
+ }
60
+
61
+ /** Fail before either service-manager path, including a manager that cascades process exit. */
62
+ export async function preflightConnectedClientStop(approved?: ConnectedStopTarget): Promise<StopOutcome | "already-stopped" | null> {
63
+ try {
64
+ let target = approved;
65
+ if (!target) {
66
+ const pid = readPid();
67
+ const runtime = readRuntimePort(pid ?? undefined);
68
+ if (pid && isProcessAlive(pid)) {
69
+ if (!runtime) throw unsupportedConnectedStop();
70
+ target = { ...runtime, pid };
71
+ }
72
+ else {
73
+ const live = await findLiveProxy({ acceptPackageTreeFenced: true });
74
+ if (live?.pid) {
75
+ if (await proveLiveProxyOwnedByHome(live) !== "proven") throw unsupportedConnectedStop();
76
+ target = { ...live, pid: live.pid };
77
+ } else {
78
+ const config = loadConfig();
79
+ const endpoints = [...(runtime ? [runtime] : []), { port: config.port, hostname: config.hostname }];
80
+ if (endpoints.some(endpoint => !Number.isInteger(endpoint.port) || endpoint.port <= 0 || endpoint.port > 65535)
81
+ || await observeGuardedManagerStopped({ kind: "absent" }) !== "inactive") throw unsupportedConnectedStop();
82
+ for (const endpoint of endpoints) {
83
+ if (await probeEndpointLiveness(endpoint) !== "dead") throw unsupportedConnectedStop();
84
+ }
85
+ return "already-stopped";
86
+ }
87
+ }
88
+ }
89
+ if (!isProcessAlive(target.pid)) throw unsupportedConnectedStop();
90
+ await assertConnectedClientStopSupported(target);
91
+ return null;
92
+ } catch {
93
+ const error = unsupportedConnectedStop();
94
+ console.error(error.message);
95
+ process.exitCode = 1;
96
+ return { ok: false, summary: { schema: "ocx-stop/1", ok: false, outcome: "failed", exitCode: 1,
97
+ runtimeDown: false, service: "absent", proxy: "ownership-refused", sharedTeardown: "skipped", message: error.message } };
98
+ }
99
+ }
100
+
101
+ /**
102
+ * The line `ocx stop` prints in place of the shared teardown on a connected client, or null
103
+ * when this home is not one (#7563).
104
+ *
105
+ * A hub client or Remote Link Child gets its Codex routing and catalog from `ocx connect` /
106
+ * `ocx sync`, and its client runtime never writes them on start. The standalone teardown
107
+ * restored native Codex, rewrote the catalog and stripped the Grok block, and nothing on the
108
+ * client put any of it back: `ocx start` brought the runtime up with Codex still native and
109
+ * Grok unconfigured. Leaving them in place makes stop/start a round trip; `ocx disconnect`
110
+ * remains the teardown that owns them, with its own ownership checks.
111
+ */
112
+ export function connectedClientStopSkipLine(state: ClientConnectionState): string | null {
113
+ if (state.kind !== "connected") return null;
114
+ const role = state.value.transport === "link" ? "Remote Link Child" : "hub client";
115
+ return `↩️ Codex routing, its catalog and the Grok config stay as they are: this ${role}'s connection owns them, and 'ocx start' serves them again. To hand Codex back to its own account, run 'ocx disconnect'.`;
116
+ }
4
117
 
5
118
  /**
6
119
  * Restore shared client state after a stop.
@@ -0,0 +1,60 @@
1
+ /**
2
+ * `ocx sync --expect-link <linkId>` / `--expect-hub-key <apiKeyId>` (#7694): argument parsing and
3
+ * the refusal report. The check itself runs under the client locks in
4
+ * `src/client/sync-expectation.ts`; this module only turns argv into an expectation and a
5
+ * mismatch into the documented exit code and stderr lines.
6
+ */
7
+ import type { ClientSyncExpectation } from "../client/sync-expectation";
8
+
9
+ /** Exit code of a refused expectation: the machine is not in the state the caller named. */
10
+ export const SYNC_EXPECTATION_MISMATCH_EXIT = 5;
11
+ export const SYNC_EXPECTATION_USAGE_EXIT = 2;
12
+
13
+ const LINK_ID = /^lnk_[0-9a-f]{16}$/;
14
+ const FLAGS = ["--expect-link", "--expect-hub-key"] as const;
15
+
16
+ export type ParsedSyncExpectation =
17
+ | { ok: true; expectation?: ClientSyncExpectation }
18
+ | { ok: false; message: string };
19
+
20
+ /** Reads both flags in `--flag value` or `--flag=value` form; any doubt is a usage error. */
21
+ export function parseSyncExpectation(args: readonly string[]): ParsedSyncExpectation {
22
+ const found: { flag: typeof FLAGS[number]; value: string | undefined }[] = [];
23
+ for (let index = 0; index < args.length; index += 1) {
24
+ const arg = args[index]!;
25
+ for (const flag of FLAGS) {
26
+ if (arg === flag) {
27
+ const next = args[index + 1];
28
+ found.push({ flag, value: next === undefined || next.startsWith("--") ? undefined : next });
29
+ if (next !== undefined && !next.startsWith("--")) index += 1;
30
+ } else if (arg.startsWith(`${flag}=`)) {
31
+ found.push({ flag, value: arg.slice(flag.length + 1) });
32
+ }
33
+ }
34
+ }
35
+ if (found.length === 0) return { ok: true };
36
+ if (found.length > 1) {
37
+ return { ok: false, message: "ocx sync accepts one --expect-link or --expect-hub-key, given once." };
38
+ }
39
+ const [{ flag, value }] = found as [typeof found[number]];
40
+ if (flag === "--expect-link") {
41
+ if (value === undefined || !LINK_ID.test(value)) {
42
+ return { ok: false, message: "--expect-link needs a link id of the form lnk_ followed by 16 hex digits (see ocx connect status --json)." };
43
+ }
44
+ return { ok: true, expectation: { kind: "link", linkId: value } };
45
+ }
46
+ if (value === undefined || value.trim() === "" || value.trim() !== value || value.length > 256) {
47
+ return { ok: false, message: "--expect-hub-key needs the connected API key id (see ocx connect status --json)." };
48
+ }
49
+ return { ok: true, expectation: { kind: "hub", apiKeyId: value } };
50
+ }
51
+
52
+ /** A refusal prints one human line, then one JSON line a caller can parse as the last stderr line. */
53
+ export function reportSyncExpectationMismatch(
54
+ error: { phase: string; reason: string },
55
+ log: Pick<Console, "error">,
56
+ ): number {
57
+ log.error(`Sync refused (${error.phase}: ${error.reason}); nothing was changed and local providers were not synced.`);
58
+ log.error(JSON.stringify({ phase: error.phase, reason: error.reason }));
59
+ return SYNC_EXPECTATION_MISMATCH_EXIT;
60
+ }
@@ -1,10 +1,12 @@
1
+ import { basename, dirname } from "node:path";
1
2
  import type { ExportModel } from "../clients/config-export";
2
3
  import { guardAsideProfileIO, listAsideProfiles } from "../clients/aside-profiles";
3
4
  import { loadConfig } from "../config";
4
5
  import { listAsideProfileStores } from "../integrations/aside-profile-context";
6
+ import { hermesProfileBoundary, listHermesProfileStores } from "../integrations/hermes-profiles";
5
7
  import { isIntegrationClientId, type IntegrationClientId } from "../integrations/registry";
6
8
  import { createIntegrationStateStore, type IntegrationStateStore } from "../integrations/store";
7
- import { disableIntegrationCoordinated, type WriteOutcome } from "../integrations/writer";
9
+ import { disableIntegrationCoordinated, type CoordinatedIntegrationOptions, type WriteOutcome } from "../integrations/writer";
8
10
  import { loadExportModels } from "../server/management/model-rows";
9
11
  import type { OcxConfig } from "../types";
10
12
 
@@ -12,7 +14,7 @@ export interface UninstallIntegrationCleanupDeps {
12
14
  createStore: () => IntegrationStateStore;
13
15
  loadConfig: () => OcxConfig;
14
16
  loadModels: (config: OcxConfig) => Promise<ExportModel[]>;
15
- disable: (input: Parameters<typeof disableIntegrationCoordinated>[0]) => Promise<WriteOutcome>;
17
+ disable: (input: Parameters<typeof disableIntegrationCoordinated>[0], options?: CoordinatedIntegrationOptions) => Promise<WriteOutcome>;
16
18
  env?: NodeJS.ProcessEnv;
17
19
  home?: string;
18
20
  }
@@ -21,7 +23,7 @@ const defaults: UninstallIntegrationCleanupDeps = {
21
23
  createStore: () => createIntegrationStateStore(),
22
24
  loadConfig,
23
25
  loadModels: config => loadExportModels(config),
24
- disable: input => disableIntegrationCoordinated(input),
26
+ disable: (input, options) => disableIntegrationCoordinated(input, options),
25
27
  };
26
28
 
27
29
  export interface UninstallIntegrationCleanupResult {
@@ -46,7 +48,7 @@ export async function cleanupOwnedIntegrationsBeforeUninstall(
46
48
  }
47
49
  }
48
50
  type CleanupTarget = Pick<Parameters<typeof disableIntegrationCoordinated>[0], "clientId" | "store" | "io" | "resolvedPaths">
49
- & { store: IntegrationStateStore; profileId?: number };
51
+ & { store: IntegrationStateStore; profileId?: number; guard?: CoordinatedIntegrationOptions["guard"] };
50
52
  const targets: CleanupTarget[] = (rawIds as IntegrationClientId[]).sort()
51
53
  .map(clientId => ({ clientId, store }));
52
54
  // Read every child before any mutation. A broken child must not look like no ownership.
@@ -57,6 +59,38 @@ export async function cleanupOwnedIntegrationsBeforeUninstall(
57
59
  }
58
60
  if (childRecords.aside) targets.push({ clientId: "aside", ...child });
59
61
  }
62
+ // Named Hermes profiles keep their own stores (#7674). The record names the file we wrote; it
63
+ // must be that profile's config.yaml, so a record cannot aim this disable at any other file.
64
+ for (const child of listHermesProfileStores(store)) {
65
+ const childRecords = child.store.readRecordsStrict();
66
+ if (Object.keys(childRecords).some(id => id !== "hermes")) {
67
+ throw new Error("integration cleanup refused: Hermes profile storage names another client");
68
+ }
69
+ const configPath = childRecords.hermes?.configPath;
70
+ if (configPath === undefined) continue;
71
+ const profileHome = dirname(configPath);
72
+ if (basename(configPath) !== "config.yaml" || basename(profileHome) !== child.name
73
+ || basename(dirname(profileHome)) !== "profiles") {
74
+ throw new Error("integration cleanup refused: Hermes profile ownership is mismatched");
75
+ }
76
+ // Pinned now, before any await, and checked again inside the disable itself: a profile or
77
+ // `profiles` directory swapped for a link while models load cannot redirect this cleanup.
78
+ let holds: () => void;
79
+ try { holds = hermesProfileBoundary({ name: child.name, home: profileHome, configPath }, child.store); }
80
+ catch (error) {
81
+ throw new Error(`integration cleanup refused for Hermes profile ${child.name}: ${error instanceof Error ? error.message : String(error)}`);
82
+ }
83
+ targets.push({
84
+ clientId: "hermes", store: child.store, resolvedPaths: { configPath, detectDir: profileHome },
85
+ guard: () => {
86
+ try { holds(); return null; }
87
+ catch (error) {
88
+ return { ok: false, reason: "unsafe", state: "unsafe", clientId: "hermes",
89
+ message: error instanceof Error ? error.message : "Hermes profile cannot be changed safely" };
90
+ }
91
+ },
92
+ });
93
+ }
60
94
  if (targets.length === 0) return { attempted: 0, changed: 0 };
61
95
 
62
96
  const asideTargets = targets.filter(target => target.clientId === "aside");
@@ -85,7 +119,7 @@ export async function cleanupOwnedIntegrationsBeforeUninstall(
85
119
  const config = deps.loadConfig();
86
120
  const models = await deps.loadModels(config);
87
121
  let changed = 0;
88
- for (const { clientId, store: targetStore, io, resolvedPaths } of targets) {
122
+ for (const { clientId, store: targetStore, io, resolvedPaths, guard } of targets) {
89
123
  const result = await deps.disable({
90
124
  clientId,
91
125
  models,
@@ -96,7 +130,7 @@ export async function cleanupOwnedIntegrationsBeforeUninstall(
96
130
  ...(resolvedPaths ? { resolvedPaths } : {}),
97
131
  ...(deps.env ? { env: deps.env } : {}),
98
132
  ...(deps.home ? { home: deps.home } : {}),
99
- });
133
+ }, guard ? { guard } : undefined);
100
134
  if (!result.ok) {
101
135
  throw new Error(`integration cleanup refused for ${clientId}: ${result.message}`
102
136
  + (result.residual ? "; recovery did not complete; inspect the client file and retained snapshots before retrying" : ""));
@@ -107,7 +141,7 @@ export async function cleanupOwnedIntegrationsBeforeUninstall(
107
141
  if (result.changed) changed++;
108
142
  }
109
143
  // A profile can gain ownership while catalog loading or an earlier disable awaited its lock.
110
- if ([store, ...listAsideProfileStores(store).map(child => child.store)]
144
+ if ([store, ...listAsideProfileStores(store).map(child => child.store), ...listHermesProfileStores(store).map(child => child.store)]
111
145
  .some(current => Object.keys(current.readRecordsStrict()).length > 0)) {
112
146
  throw new Error("integration cleanup refused: ownership changed before removal");
113
147
  }
@@ -74,6 +74,9 @@ import {
74
74
  assertNoClientDisconnectPending, assertClientConnectionUnchanged, sameClientConnectionOwner,
75
75
  } from "./state";
76
76
  import { assertClientCatalogCompatible, type CatalogCompatibilityDeps } from "./catalog-compatibility";
77
+ import {
78
+ assertClientSyncExpectation, ClientSyncExpectationError, isClientSyncLockBusy, type ClientSyncExpectation,
79
+ } from "./sync-expectation";
77
80
  import { overlayHomeCodexSettings } from "../link/codex-settings";
78
81
  import {
79
82
  clearHomeCodexSettingsRecord,
@@ -840,6 +843,21 @@ export interface ConnectedSyncResult {
840
843
  appliedRecord?: HomeCodexSettingsRecord;
841
844
  /** The Home's settings were injected but their record could not be written (OCX-6). */
842
845
  applyRecordFailed?: true;
846
+ /**
847
+ * The connection this sync ran under, read inside its lock and compare-and-swapped on every
848
+ * write. Callers decide link-vs-hub wording and restart ownership from this, never from a read
849
+ * they made before the lock.
850
+ */
851
+ connection: OcxClientConnectionConfig;
852
+ }
853
+
854
+ export interface ConnectedSyncOptions {
855
+ restartCodex?: boolean;
856
+ /**
857
+ * #7694: refuse unless this is the connection found under the lock. A mismatch throws
858
+ * `ClientSyncExpectationError` before any request or write.
859
+ */
860
+ expect?: ClientSyncExpectation;
843
861
  }
844
862
 
845
863
  /**
@@ -848,18 +866,36 @@ export interface ConnectedSyncResult {
848
866
  * never interleaves with another apply, and its record names what its own injection wrote.
849
867
  */
850
868
  export async function syncConnectedClient(
851
- options: { restartCodex?: boolean } = {},
869
+ options: ConnectedSyncOptions = {},
852
870
  deps: ClientConnectDeps = {},
853
871
  ): Promise<ConnectedSyncResult> {
854
- return withLinkApply(() => syncConnectedClientUnlocked(options, deps), deps.linkApplyLockPath);
872
+ let checked = false;
873
+ try {
874
+ return await withLinkApply(() => syncConnectedClientUnlocked(options, deps, () => { checked = true; }), deps.linkApplyLockPath);
875
+ } catch (error) {
876
+ // #7694: a pinned sync that cannot take a lock its check needs (a link connect holds the apply
877
+ // lock across its network reads) is refused as pending, with nothing written; it never surfaces
878
+ // as a generic failure the caller cannot tell from a broken sync.
879
+ if (options.expect && !checked && isClientSyncLockBusy(error)) {
880
+ throw new ClientSyncExpectationError(options.expect, "pending_operation");
881
+ }
882
+ throw error;
883
+ }
855
884
  }
856
885
 
857
886
  async function syncConnectedClientUnlocked(
858
- _options: { restartCodex?: boolean } = {},
887
+ options: ConnectedSyncOptions = {},
859
888
  deps: ClientConnectDeps = {},
889
+ markChecked: () => void = () => {},
860
890
  ): Promise<ConnectedSyncResult> {
861
891
  if (siblingOfLivePort() !== null) throw new Error(siblingSkipMessage());
862
892
  const initial = withClientLifecycleSync(() => withConfigMutationLockSync(() => {
893
+ // The expectation is checked by the read that selects this path; everything after is
894
+ // compare-and-swapped against the connection it passed (#7694).
895
+ if (options.expect) {
896
+ assertClientSyncExpectation(options.expect);
897
+ markChecked();
898
+ }
863
899
  assertNoClientDisconnectPending();
864
900
  const state = readClientConnectionState();
865
901
  if (state.kind !== "connected" || state.value.pendingOperation) throw new Error("client_sync_unavailable");
@@ -949,6 +985,7 @@ async function syncConnectedClientUnlocked(
949
985
  ...(homeSettings ? { homeSettings } : {}),
950
986
  ...(appliedRecord ? { appliedRecord } : {}),
951
987
  ...(applyRecordFailed ? { applyRecordFailed } : {}),
988
+ connection: next,
952
989
  };
953
990
  }
954
991
 
@@ -137,6 +137,15 @@ export function withdrawChangingHomeCodexSettingsRecord(linkId: string, document
137
137
  return true;
138
138
  }
139
139
 
140
+ /** The apply lock is held by another apply or a link connect in flight; nothing ran. */
141
+ export class LinkApplyBusyError extends Error {
142
+ readonly code = "link_apply_busy";
143
+ constructor() {
144
+ super("another Home settings apply is in progress on this machine; retry when it finishes");
145
+ this.name = "LinkApplyBusyError";
146
+ }
147
+ }
148
+
140
149
  /**
141
150
  * Serialize applies of the Home's settings on this Child, from the Home read through the Codex
142
151
  * injection to the record write, so a receipt always names the settings the injection wrote.
@@ -152,7 +161,7 @@ export async function withLinkApply<T>(work: () => Promise<T>, lockPath: string
152
161
  return await withClientLifecycle(() => { entered = true; return work(); }, { lockPath });
153
162
  } catch (error) {
154
163
  if (!entered && error instanceof Error && error.message === "client_lifecycle_busy") {
155
- throw new Error("another Home settings apply is in progress on this machine; retry when it finishes");
164
+ throw new LinkApplyBusyError();
156
165
  }
157
166
  throw error;
158
167
  }
@@ -106,7 +106,9 @@ export async function handleMachineApi(
106
106
  return Response.json({ error: "invalid sync request" }, { status: 400 });
107
107
  }
108
108
  try {
109
- const result = await deps.sync(
109
+ // `connection` is the full saved connection (token fingerprint, prior catalog) for local
110
+ // callers; it is not part of this response.
111
+ const { connection: _connection, ...result } = await deps.sync(
110
112
  input.restartCodex === undefined ? {} : { restartCodex: input.restartCodex },
111
113
  );
112
114
  deps.setHubReachability?.("online");