@bitkyc08/opencodex 2.100.2 → 2.100.4

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 (644) hide show
  1. package/AGENTS_INSTALL.md +23 -1
  2. package/README.md +1 -1
  3. package/bin/ocx.mjs +40 -19
  4. package/gui/dist/assets/{App-COo8Yopd.css → App-BGP8I0V4.css} +1 -1
  5. package/gui/dist/assets/App-DcpyI78f.js +60 -0
  6. package/gui/dist/assets/{Tray-BcaI-VCr.js → Tray-CzjPJprT.js} +1 -1
  7. package/gui/dist/assets/brand-mark-BTIi7e69.js +1 -0
  8. package/gui/dist/assets/index-DJxM-imn.css +2 -0
  9. package/gui/dist/assets/index-DVgU6S3y.js +138 -0
  10. package/gui/dist/assets/{segment-thumb-features-e9A_FogJ.js → segment-thumb-features-Bn6Y-g3R.js} +1 -1
  11. package/gui/dist/classic/assets/App-eYJAyNHM.js +59 -0
  12. package/gui/dist/classic/assets/{Tray-DT146AhS.js → Tray-xHMYxLkV.js} +1 -1
  13. package/gui/dist/classic/assets/index-DSaVRW4F.js +138 -0
  14. package/gui/dist/classic/assets/quota-summary-DyzHlkFl.js +1 -0
  15. package/gui/dist/classic/index.html +1 -1
  16. package/gui/dist/index.html +2 -2
  17. package/native/ocx-child/Cargo.toml +9 -0
  18. package/native/ocx-child/src/cli.rs +404 -20
  19. package/native/ocx-child/src/codex_home.rs +99 -14
  20. package/native/ocx-child/src/daemon.rs +2 -1
  21. package/native/ocx-child/src/lib.rs +3 -0
  22. package/native/ocx-child/src/link_ws.rs +2598 -0
  23. package/native/ocx-child/src/link_ws_advert.rs +346 -0
  24. package/native/ocx-child/src/link_ws_frame.rs +749 -0
  25. package/native/ocx-child/src/parity.rs +5 -1
  26. package/native/ocx-child/src/platform.rs +152 -6
  27. package/native/ocx-child/src/relay.rs +150 -19
  28. package/package.json +3 -3
  29. package/src/adapters/anthropic/advisor-tool.ts +176 -0
  30. package/src/adapters/anthropic/beta-body-pairs.ts +6 -0
  31. package/src/adapters/anthropic/client-identity.ts +3 -1
  32. package/src/adapters/anthropic/passthrough.ts +9 -3
  33. package/src/adapters/anthropic/per-message-effort.ts +296 -0
  34. package/src/adapters/anthropic.ts +34 -14
  35. package/src/adapters/claude-cli/adapter.ts +1 -0
  36. package/src/adapters/client-fingerprint.ts +3 -3
  37. package/src/adapters/cursor/discovery.ts +17 -0
  38. package/src/adapters/cursor/native-exec-desktop.ts +2 -1
  39. package/src/adapters/cursor/native-exec-shell.ts +2 -1
  40. package/src/adapters/cursor/protobuf-request.ts +8 -8
  41. package/src/adapters/cursor.ts +7 -6
  42. package/src/adapters/devin/cloud-direct/chat.ts +71 -14
  43. package/src/adapters/google-antigravity-wire.ts +7 -5
  44. package/src/adapters/google-errors.ts +14 -2
  45. package/src/adapters/google-wire-compiler.ts +2 -2
  46. package/src/adapters/google.ts +9 -2
  47. package/src/adapters/kiro/payload.ts +7 -4
  48. package/src/adapters/kiro/reasoning.ts +44 -1
  49. package/src/adapters/kiro/structured-output.ts +10 -8
  50. package/src/adapters/kiro-tools.ts +61 -15
  51. package/src/adapters/openai-chat/destination-policy.ts +16 -0
  52. package/src/adapters/openai-chat/reasoning-replay.ts +4 -1
  53. package/src/adapters/qoder/adapter.ts +9 -1
  54. package/src/adapters/zed.ts +7 -2
  55. package/src/advisor/consult.ts +15 -4
  56. package/src/advisor/context.ts +12 -3
  57. package/src/advisor/runtime.ts +35 -5
  58. package/src/advisor/settings.ts +8 -0
  59. package/src/advisor/synthetic-tool.ts +21 -8
  60. package/src/bridge/response-json.ts +11 -2
  61. package/src/bridge/sse.ts +43 -8
  62. package/src/claude/auth-detect.ts +21 -33
  63. package/src/claude/desktop-3p.ts +11 -5
  64. package/src/claude/desktop-gateway-state.ts +2 -0
  65. package/src/claude/desktop-remote-store-artifact.ts +14 -3
  66. package/src/claude/desktop-remote-store.ts +82 -12
  67. package/src/claude/inbound-content-options.ts +31 -16
  68. package/src/claude/outbound.ts +13 -3
  69. package/src/cli/account-api.ts +21 -1
  70. package/src/cli/account-auth.ts +83 -22
  71. package/src/cli/account-extended.ts +33 -2
  72. package/src/cli/account-key-quota.ts +34 -5
  73. package/src/cli/account.ts +4 -2
  74. package/src/cli/advisor.ts +7 -4
  75. package/src/cli/alias.ts +38 -1
  76. package/src/cli/capabilities-access-remote.ts +128 -3
  77. package/src/cli/capabilities-accounts.ts +6 -6
  78. package/src/cli/capabilities-agents-routing.ts +17 -10
  79. package/src/cli/capabilities-base.ts +49 -19
  80. package/src/cli/capabilities-integrations.ts +2 -2
  81. package/src/cli/capabilities-observe-system.ts +2 -2
  82. package/src/cli/capabilities-provider-models.ts +18 -2
  83. package/src/cli/capabilities-route-to.ts +43 -0
  84. package/src/cli/capabilities.ts +2 -0
  85. package/src/cli/capability-contracts.ts +1 -1
  86. package/src/cli/claude-desktop.ts +30 -11
  87. package/src/cli/claude.ts +17 -3
  88. package/src/cli/codex-launcher.ts +3 -1
  89. package/src/cli/codex-shim-autorestore.ts +5 -42
  90. package/src/cli/config-command.ts +14 -1
  91. package/src/cli/config-root-startup.ts +34 -0
  92. package/src/cli/connect.ts +88 -16
  93. package/src/cli/desktop-runtime-guidance.ts +1 -1
  94. package/src/cli/disconnect-runtime.ts +178 -0
  95. package/src/cli/dispatch.ts +61 -13
  96. package/src/cli/export-command.ts +1 -1
  97. package/src/cli/gui-pair-client.ts +6 -3
  98. package/src/cli/gui.ts +10 -5
  99. package/src/cli/help-catalog.ts +11 -0
  100. package/src/cli/help.ts +4 -3
  101. package/src/cli/index.ts +85 -94
  102. package/src/cli/inspect.ts +11 -2
  103. package/src/cli/integrations.ts +26 -1
  104. package/src/cli/link-apply-restart.ts +4 -2
  105. package/src/cli/link-capture.ts +64 -0
  106. package/src/cli/link-child-ops.ts +218 -40
  107. package/src/cli/link-cleanup.ts +8 -5
  108. package/src/cli/link-diagnostics.ts +67 -0
  109. package/src/cli/link-enrollment.ts +158 -12
  110. package/src/cli/link-operations.ts +52 -0
  111. package/src/cli/link-recover.ts +152 -0
  112. package/src/cli/link-routes.ts +90 -0
  113. package/src/cli/link-status-child.ts +44 -1
  114. package/src/cli/link-status-traffic.ts +34 -0
  115. package/src/cli/link.ts +315 -37
  116. package/src/cli/message-command.ts +1 -1
  117. package/src/cli/message-mcp-command.ts +23 -10
  118. package/src/cli/models-runtime.ts +3 -3
  119. package/src/cli/opencode.ts +3 -1
  120. package/src/cli/pi-sync.ts +35 -0
  121. package/src/cli/preflight-exemptions.ts +49 -0
  122. package/src/cli/registry.ts +33 -14
  123. package/src/cli/resolve.ts +23 -8
  124. package/src/cli/restart-failure.ts +15 -2
  125. package/src/cli/root.ts +5 -1
  126. package/src/cli/route-to.ts +172 -0
  127. package/src/cli/runtime-api.ts +9 -8
  128. package/src/cli/status.ts +7 -2
  129. package/src/cli/stop-approval.ts +66 -19
  130. package/src/cli/stop-report.ts +23 -0
  131. package/src/cli/stop-windows-checked.ts +304 -0
  132. package/src/cli/sync-command.ts +70 -15
  133. package/src/cli/sync-fanout.ts +74 -19
  134. package/src/cli/sync-flags.ts +40 -3
  135. package/src/cli/sync-link-status.ts +18 -2
  136. package/src/cli/sync-update-guard.ts +7 -2
  137. package/src/cli/system-command.ts +1 -1
  138. package/src/cli/system-restart-client.ts +10 -3
  139. package/src/cli/system-settings-parity.ts +2 -1
  140. package/src/cli/uninstall-plan.ts +77 -5
  141. package/src/cli/uninstall-stop.ts +152 -0
  142. package/src/cli/v2-input.ts +10 -6
  143. package/src/cli/v2-local-output.ts +3 -2
  144. package/src/cli/v2-runtime.ts +10 -3
  145. package/src/cli/v2.ts +22 -7
  146. package/src/client/connect.ts +376 -35
  147. package/src/client/desktop-refusal.ts +38 -0
  148. package/src/client/lifecycle-lock.ts +29 -4
  149. package/src/client/link-home-features.ts +27 -0
  150. package/src/client/link-home.ts +92 -4
  151. package/src/client/link-ingress.ts +21 -3
  152. package/src/client/link-join.ts +12 -2
  153. package/src/client/link-parity-reporter.ts +60 -6
  154. package/src/client/link-relay-transport.ts +161 -36
  155. package/src/client/link-relay.ts +150 -6
  156. package/src/client/link-request-compression.ts +84 -0
  157. package/src/client/link-state.ts +11 -5
  158. package/src/client/link-status.ts +39 -1
  159. package/src/client/link-teardown.ts +1 -0
  160. package/src/client/link-tunnel.ts +56 -5
  161. package/src/client/link-websocket-limits.ts +89 -0
  162. package/src/client/link-websocket.ts +586 -0
  163. package/src/client/link-ws-advertisement.ts +100 -0
  164. package/src/client/link-ws-framer.ts +241 -0
  165. package/src/client/link-ws-transport.ts +177 -0
  166. package/src/client/machine-api.ts +13 -2
  167. package/src/client/machine-listener.ts +48 -7
  168. package/src/client/route-intent-apply.ts +293 -0
  169. package/src/client/route-intent-file-originals.ts +97 -0
  170. package/src/client/route-intent-native-originals.ts +201 -0
  171. package/src/client/route-intent-watch.ts +141 -0
  172. package/src/client/runtime-restart.ts +141 -7
  173. package/src/client/runtime.ts +63 -15
  174. package/src/client/state.ts +44 -0
  175. package/src/client/sync-expectation.ts +36 -2
  176. package/src/client/sync-runtime.ts +7 -0
  177. package/src/clients/config-export/alias-selectors.ts +63 -40
  178. package/src/clients/config-export/contracts.ts +2 -0
  179. package/src/clients/config-export/nested-selectors.ts +42 -0
  180. package/src/clients/config-export.ts +22 -3
  181. package/src/codex/account-pause.ts +4 -0
  182. package/src/codex/account-runtime-state.ts +4 -0
  183. package/src/codex/account-store.ts +12 -3
  184. package/src/codex/account-usability.ts +13 -0
  185. package/src/codex/auth-api/account-list.ts +29 -3
  186. package/src/codex/auth-api/main-account-probe.ts +3 -1
  187. package/src/codex/auth-api/main-hard-lock-refusal-read.ts +172 -0
  188. package/src/codex/auth-collision.ts +23 -22
  189. package/src/codex/auth-context.ts +61 -8
  190. package/src/codex/catalog/build-entries.ts +10 -0
  191. package/src/codex/catalog/derive-entry.ts +7 -0
  192. package/src/codex/catalog/gather-capture.ts +8 -2
  193. package/src/codex/catalog/parsing.ts +7 -3
  194. package/src/codex/catalog/provider-models.ts +54 -15
  195. package/src/codex/catalog/reserve-warn.ts +7 -5
  196. package/src/codex/catalog/reserve.ts +4 -3
  197. package/src/codex/catalog/retained-sync.ts +4 -1
  198. package/src/codex/catalog/routed-defaults.ts +35 -0
  199. package/src/codex/catalog/routed-gather.ts +1 -1
  200. package/src/codex/catalog-auto-refresh.ts +11 -0
  201. package/src/codex/cli-update-job.ts +35 -13
  202. package/src/codex/convergence.ts +4 -2
  203. package/src/codex/desktop-compatibility/native-identity.ts +4 -8
  204. package/src/codex/features.ts +2 -2
  205. package/src/codex/history-provider.ts +31 -0
  206. package/src/codex/inject/multi-agent-v2.ts +9 -3
  207. package/src/codex/inject/paginated-openai-compat.ts +54 -1
  208. package/src/codex/inject/plan.ts +20 -2
  209. package/src/codex/inject.ts +2 -0
  210. package/src/codex/journal-config-restore.ts +217 -0
  211. package/src/codex/journal.ts +75 -6
  212. package/src/codex/loopback-target.ts +22 -8
  213. package/src/codex/main-account.ts +109 -57
  214. package/src/codex/native-main-auth-file.ts +118 -0
  215. package/src/codex/native-main-credentials.ts +270 -0
  216. package/src/codex/native-main-owner.ts +3 -0
  217. package/src/codex/native-main-refresh-mode.ts +14 -1
  218. package/src/codex/native-profile-manager.ts +4 -3
  219. package/src/codex/native-profile-store.ts +3 -61
  220. package/src/codex/orca-import.ts +10 -1
  221. package/src/codex/quota-history.ts +13 -0
  222. package/src/codex/quota-window-conflict.ts +103 -0
  223. package/src/codex/quota.ts +86 -15
  224. package/src/codex/subagent-model-fallback.ts +3 -1
  225. package/src/codex/websocket-activity.ts +171 -16
  226. package/src/codex/websocket-registry.ts +11 -4
  227. package/src/combos/cooldown-store.ts +25 -5
  228. package/src/combos/failover.ts +342 -3
  229. package/src/combos/index.ts +5 -0
  230. package/src/combos/resolve.ts +115 -19
  231. package/src/config/dashboard-trusted-proxy.ts +83 -0
  232. package/src/config/diagnostics.ts +31 -0
  233. package/src/config/feature-flags.ts +9 -0
  234. package/src/config/live-reconcile.ts +16 -4
  235. package/src/config/load-degrade.ts +14 -1
  236. package/src/config/multi-agent-surface.ts +28 -5
  237. package/src/config/pending-teardown.ts +60 -3
  238. package/src/config/persisted-mutation.ts +2 -2
  239. package/src/config/persisted-projections.ts +18 -0
  240. package/src/config/process-state.ts +176 -4
  241. package/src/config/provider-validation.ts +4 -4
  242. package/src/config/reserve-capability.ts +96 -0
  243. package/src/config/schema/config-schema.ts +12 -0
  244. package/src/config/schema/leaf-validators.ts +11 -2
  245. package/src/config/schema/routed-catalog-defaults.ts +49 -0
  246. package/src/config/windows-process-command-line.ts +107 -0
  247. package/src/config.ts +7 -7
  248. package/src/desktop-update/acquire.ts +202 -0
  249. package/src/desktop-update/cli.ts +168 -0
  250. package/src/desktop-update/drain.ts +40 -0
  251. package/src/desktop-update/headless.ts +285 -0
  252. package/src/desktop-update/image.ts +85 -0
  253. package/src/desktop-update/install.ts +53 -0
  254. package/src/desktop-update/msi.ts +72 -0
  255. package/src/desktop-update/release.ts +128 -0
  256. package/src/desktop-update/runtime.ts +155 -0
  257. package/src/desktop-update/staging.ts +118 -0
  258. package/src/desktop-update/trust.ts +45 -0
  259. package/src/generated/compatibility-version.json +1114 -442
  260. package/src/generated/model-metadata.ts +1 -1
  261. package/src/images/fulfill-video.ts +3 -3
  262. package/src/images/loop.ts +9 -2
  263. package/src/images/plan.ts +147 -11
  264. package/src/images/types.ts +13 -4
  265. package/src/images/xai-video-client.ts +72 -10
  266. package/src/integrations/model-name-guard.ts +25 -0
  267. package/src/integrations/route-intent-catalog.ts +26 -0
  268. package/src/integrations/route-intent-connected.ts +262 -0
  269. package/src/integrations/route-intent-contract.ts +55 -0
  270. package/src/integrations/route-intent-disconnect.ts +109 -0
  271. package/src/integrations/route-intent-initial.ts +64 -0
  272. package/src/integrations/route-intent-state.ts +117 -0
  273. package/src/integrations/route-intent-tick.ts +65 -0
  274. package/src/integrations/route-intent.ts +212 -0
  275. package/src/integrations/writer.ts +44 -11
  276. package/src/lib/client-retry-after.ts +29 -0
  277. package/src/lib/config-ownership.ts +13 -0
  278. package/src/lib/desktop-gui-origin.ts +28 -0
  279. package/src/lib/errors.ts +1 -1
  280. package/src/lib/gcp-adc.ts +48 -4
  281. package/src/lib/gui-pair-capability.ts +2 -1
  282. package/src/lib/messages-error-body.ts +4 -1
  283. package/src/lib/offline-resend.ts +150 -0
  284. package/src/lib/outbound-credential-registry.ts +362 -4
  285. package/src/lib/paced-stream.ts +34 -0
  286. package/src/lib/passive-key-fetch-proof.ts +30 -0
  287. package/src/lib/passive-read.ts +5 -0
  288. package/src/lib/process-control.ts +76 -12
  289. package/src/lib/provider-outbound.ts +17 -6
  290. package/src/lib/redact.ts +84 -8
  291. package/src/lib/request-failure-model.ts +2 -0
  292. package/src/lib/response-body-inactivity.ts +23 -1
  293. package/src/lib/state-store-registrations.ts +11 -0
  294. package/src/lib/state-store-sweeper.ts +4 -0
  295. package/src/lib/supervisor-markers.ts +18 -0
  296. package/src/lib/terminal-safe-text.ts +58 -0
  297. package/src/lib/translator-budget.ts +3 -2
  298. package/src/lib/upstream-retry.ts +52 -9
  299. package/src/link/alias-lock.ts +119 -0
  300. package/src/link/child-activity.ts +28 -2
  301. package/src/link/child-binary-cache-fill.d.mts +50 -0
  302. package/src/link/child-binary-cache-fill.mjs +494 -0
  303. package/src/link/child-binary-cache-start.ts +73 -0
  304. package/src/link/child-binary-source.ts +12 -5
  305. package/src/link/child-gated-ocx.ts +29 -11
  306. package/src/link/child-observations.ts +2 -1
  307. package/src/link/child-observe.ts +2 -2
  308. package/src/link/child-ops-engine.ts +159 -91
  309. package/src/link/child-ops-host.ts +138 -0
  310. package/src/link/child-ops-runners.ts +319 -0
  311. package/src/link/child-ops-scheduler.ts +207 -0
  312. package/src/link/child-ops-types.ts +89 -0
  313. package/src/link/child-parity.ts +23 -4
  314. package/src/link/child-policy.ts +93 -0
  315. package/src/link/child-update-contract.ts +12 -3
  316. package/src/link/codex-settings.ts +1 -1
  317. package/src/link/compatibility.ts +18 -1
  318. package/src/link/diagnostics-read.ts +163 -0
  319. package/src/link/diagnostics.ts +20 -7
  320. package/src/link/explicit-route.ts +209 -0
  321. package/src/link/link-recover.ts +113 -0
  322. package/src/link/management-routes.ts +3 -1
  323. package/src/link/operation-recovery-slot.ts +44 -0
  324. package/src/link/operations-journal.ts +408 -0
  325. package/src/link/peer-report.ts +1 -1
  326. package/src/link/relay-auth.ts +14 -0
  327. package/src/link/remote-plant.ts +152 -14
  328. package/src/link/remote-platform.ts +21 -10
  329. package/src/link/remote-probe.ts +11 -3
  330. package/src/link/remote-windows.ts +124 -36
  331. package/src/link/request-compression.ts +30 -0
  332. package/src/link/residual-recovery.ts +66 -0
  333. package/src/link/retirement.ts +128 -0
  334. package/src/link/route-intent-watch.ts +41 -0
  335. package/src/link/route-intent.ts +209 -0
  336. package/src/link/route-proof.ts +82 -0
  337. package/src/link/route-rounds.ts +579 -0
  338. package/src/link/route-select.ts +95 -0
  339. package/src/link/route-trust.ts +96 -0
  340. package/src/link/ssh-argv.ts +172 -24
  341. package/src/link/ssh-capture-redact.ts +253 -0
  342. package/src/link/ssh-capture.ts +497 -0
  343. package/src/link/ssh-runner.ts +141 -14
  344. package/src/link/status-projection.ts +87 -0
  345. package/src/link/store.ts +54 -1
  346. package/src/link/supervisor.ts +543 -55
  347. package/src/link/sync-fanout-classify.ts +16 -0
  348. package/src/link/sync-then-restart.ts +65 -0
  349. package/src/link/tombstones.ts +209 -0
  350. package/src/link/traffic.ts +178 -0
  351. package/src/link/ws-activity-holds.ts +474 -0
  352. package/src/local-credentials/publication-fence.ts +20 -1
  353. package/src/messaging/budget.ts +23 -5
  354. package/src/messaging/mcp-queue-rpc.ts +1 -1
  355. package/src/messaging/mcp-queue-server.ts +16 -1
  356. package/src/messaging/mcp-resume-tools.ts +25 -0
  357. package/src/messaging/remote-enrollment.ts +3 -3
  358. package/src/messaging/remote-tunnels.ts +2 -2
  359. package/src/messaging/resume-permissions.ts +27 -0
  360. package/src/messaging/rpc.ts +50 -6
  361. package/src/oauth/anthropic-continuity.ts +23 -7
  362. package/src/oauth/anthropic-routing.ts +5 -2
  363. package/src/oauth/anthropic.ts +22 -2
  364. package/src/oauth/antigravity-risk.ts +126 -0
  365. package/src/oauth/claude-keychain-read.ts +78 -68
  366. package/src/oauth/generic-account-failover.ts +89 -18
  367. package/src/oauth/generic-session-affinity.ts +10 -3
  368. package/src/oauth/index.ts +24 -6
  369. package/src/oauth/local-token-detect.ts +8 -29
  370. package/src/oauth/login-cli-errors.ts +5 -1
  371. package/src/oauth/login-cli.ts +68 -19
  372. package/src/oauth/login-flow-state.ts +26 -3
  373. package/src/oauth/meta-muse.ts +1 -1
  374. package/src/oauth/pool-kernel.ts +3 -3
  375. package/src/oauth/store.ts +7 -0
  376. package/src/oauth/xai.ts +248 -14
  377. package/src/protocols/contract.ts +4 -0
  378. package/src/protocols/encoders/messages.ts +1 -0
  379. package/src/providers/alias-template.ts +48 -0
  380. package/src/providers/anthropic-billing-ownership.ts +2 -0
  381. package/src/providers/anthropic-billing-refusal.ts +27 -3
  382. package/src/providers/anthropic-output-caps.ts +46 -0
  383. package/src/providers/anthropic-reset-grant-ledger.ts +9 -3
  384. package/src/providers/antigravity-effort-families.ts +11 -3
  385. package/src/providers/antigravity-models.ts +32 -9
  386. package/src/providers/antigravity-wire-snapshot.ts +3 -2
  387. package/src/providers/api-key-pause.ts +3 -0
  388. package/src/providers/api-key-resolve.ts +49 -7
  389. package/src/providers/api-key-response-ownership.ts +2 -0
  390. package/src/providers/api-key-selection.ts +51 -9
  391. package/src/providers/api-keys.ts +6 -2
  392. package/src/providers/cache-affinity-identity.ts +73 -0
  393. package/src/providers/cache-affinity.ts +256 -0
  394. package/src/providers/default-aliases.ts +98 -20
  395. package/src/providers/google-vertex-model-discovery.ts +515 -0
  396. package/src/providers/key-failover.ts +123 -8
  397. package/src/providers/key-store.ts +3 -3
  398. package/src/providers/kiro-models.ts +3 -5
  399. package/src/providers/label.ts +31 -5
  400. package/src/providers/mistral-transport.ts +17 -4
  401. package/src/providers/model-rename-fields.ts +5 -0
  402. package/src/providers/muse-key-quota.ts +14 -6
  403. package/src/providers/new-model-policy-runtime.ts +17 -4
  404. package/src/providers/new-model-policy.ts +30 -4
  405. package/src/providers/passive-key-observation.ts +252 -0
  406. package/src/providers/quota/account-cache.ts +2 -1
  407. package/src/providers/quota/anthropic-cooldown-recovery-worker.ts +121 -0
  408. package/src/providers/quota/passive-key-limits.ts +272 -0
  409. package/src/providers/quota/passive-wire-model.ts +126 -0
  410. package/src/providers/quota/report-cache.ts +61 -2
  411. package/src/providers/quota/workbuddy.ts +6 -2
  412. package/src/providers/quota-key-accounts.ts +11 -6
  413. package/src/providers/quota-types.ts +18 -0
  414. package/src/providers/quota.ts +11 -12
  415. package/src/providers/registry/entries-core.ts +34 -16
  416. package/src/providers/registry/entries-extended.ts +32 -0
  417. package/src/providers/registry/model-seeds.ts +35 -0
  418. package/src/providers/resolved-model-policy.ts +7 -0
  419. package/src/providers/routed-config.ts +8 -3
  420. package/src/providers/workbuddy-credit-balance.ts +125 -16
  421. package/src/providers/xai-transport.ts +3 -0
  422. package/src/remote/features.ts +17 -0
  423. package/src/responses/anthropic-progress.ts +10 -4
  424. package/src/responses/citation-markers.ts +231 -0
  425. package/src/responses/effort-history.ts +732 -0
  426. package/src/responses/spill-store.ts +5 -1
  427. package/src/responses/state/replay-input.ts +50 -0
  428. package/src/responses/state/replay-owner.ts +24 -0
  429. package/src/responses/state/snapshot-codec.ts +9 -0
  430. package/src/responses/state/spill-queue.ts +1 -0
  431. package/src/responses/state.ts +42 -60
  432. package/src/router.ts +2 -2
  433. package/src/routing/history/integrity.ts +41 -4
  434. package/src/routing/home-route-capture.ts +123 -0
  435. package/src/routing/home-route-intent.ts +200 -0
  436. package/src/routing/route-intent-state.ts +178 -0
  437. package/src/routing/route-to-live-settings.ts +35 -0
  438. package/src/routing/route-to-local.ts +145 -0
  439. package/src/routing/route-to-status.ts +94 -0
  440. package/src/routing/route-to-sync-child.ts +32 -0
  441. package/src/server/adapter-resolve.ts +21 -1
  442. package/src/server/admitted-http-turn.ts +3 -0
  443. package/src/server/auth-cors.ts +111 -3
  444. package/src/server/bare-upstream-error.ts +220 -0
  445. package/src/server/chat-native.ts +14 -5
  446. package/src/server/claude-messages.ts +6 -4
  447. package/src/server/codex-model-list.ts +4 -2
  448. package/src/server/configured-credentials.ts +37 -5
  449. package/src/server/direct-local-http.ts +26 -3
  450. package/src/server/gui-desktop-authorization.ts +36 -0
  451. package/src/server/gui-pair-delivery.ts +6 -3
  452. package/src/server/gui-session.ts +10 -1
  453. package/src/server/inbound-body-admission.ts +17 -4
  454. package/src/server/index/link-listener.ts +196 -12
  455. package/src/server/index/link-management.ts +15 -1
  456. package/src/server/index/link-relay-sessions.ts +87 -8
  457. package/src/server/index/link-websocket-limits.ts +136 -0
  458. package/src/server/index/link-websocket.ts +692 -0
  459. package/src/server/index/optional-listeners.ts +97 -7
  460. package/src/server/index/route-intent-watch.ts +47 -0
  461. package/src/server/index/serve-contract.ts +86 -0
  462. package/src/server/index/serve-options.ts +36 -86
  463. package/src/server/index/startup-warnings.ts +8 -2
  464. package/src/server/index/websocket-handler.ts +26 -4
  465. package/src/server/index.ts +15 -4
  466. package/src/server/inference/client-encoder-delivery.ts +2 -0
  467. package/src/server/inspection-tee.ts +39 -2
  468. package/src/server/lifecycle.ts +2 -0
  469. package/src/server/link-turn.ts +149 -0
  470. package/src/server/management/advisor-routes.ts +10 -2
  471. package/src/server/management/agent-settings-routes.ts +50 -16
  472. package/src/server/management/anthropic-reset-grant-routes.ts +1 -1
  473. package/src/server/management/config-routes.ts +39 -3
  474. package/src/server/management/context.ts +9 -2
  475. package/src/server/management/desktop-authorization.ts +41 -0
  476. package/src/server/management/desktop-compatibility-routes.ts +9 -8
  477. package/src/server/management/desktop-compatibility-runtime-routes.ts +3 -2
  478. package/src/server/management/desktop-compatibility-settings-routes.ts +5 -3
  479. package/src/server/management/home-integration-decision.ts +89 -0
  480. package/src/server/management/integration-routes.ts +208 -81
  481. package/src/server/management/link-child-ops-routes.ts +145 -43
  482. package/src/server/management/link-child-preflight.ts +31 -0
  483. package/src/server/management/link-diagnostics-route.ts +29 -0
  484. package/src/server/management/link-enrollment.ts +199 -47
  485. package/src/server/management/link-operation.ts +609 -0
  486. package/src/server/management/link-recover-route.ts +103 -0
  487. package/src/server/management/link-route-edit.ts +192 -0
  488. package/src/server/management/link-route-request.ts +62 -0
  489. package/src/server/management/link-route-state.ts +83 -7
  490. package/src/server/management/link-routes.ts +553 -51
  491. package/src/server/management/link-traffic-status.ts +13 -0
  492. package/src/server/management/model-routes.ts +122 -36
  493. package/src/server/management/model-rows.ts +2 -1
  494. package/src/server/management/native-integration-routes.ts +176 -70
  495. package/src/server/management/oauth-account-routes.ts +58 -18
  496. package/src/server/management/protocol-routes.ts +7 -0
  497. package/src/server/management/provider-completion-test.ts +4 -4
  498. package/src/server/management/provider-overwrite-carry.ts +14 -0
  499. package/src/server/management/provider-routes.ts +68 -65
  500. package/src/server/management/provider-routing-quota.ts +45 -0
  501. package/src/server/management/route-registry.ts +22 -3
  502. package/src/server/management/route-to-routes.ts +257 -0
  503. package/src/server/management/static-catalog-probe.ts +33 -0
  504. package/src/server/management/system-restart.ts +4 -2
  505. package/src/server/management/usage-aggregate-cache.ts +101 -66
  506. package/src/server/management-api.ts +17 -3
  507. package/src/server/management-auth.ts +13 -1
  508. package/src/server/messages-native-preflight.ts +27 -4
  509. package/src/server/messages-native.ts +17 -5
  510. package/src/server/persistent-gui-session.ts +6 -3
  511. package/src/server/proxy-liveness.ts +87 -15
  512. package/src/server/relay-eager.ts +36 -12
  513. package/src/server/relay.ts +189 -117
  514. package/src/server/request-body-facts.ts +48 -0
  515. package/src/server/request-decompress.ts +65 -2
  516. package/src/server/request-log-account-rotation.ts +6 -0
  517. package/src/server/request-log-attempt-usage.ts +69 -0
  518. package/src/server/request-log-cache-affinity.ts +60 -0
  519. package/src/server/request-log-conversation.ts +45 -2
  520. package/src/server/request-log-terminal-status.ts +210 -24
  521. package/src/server/request-log.ts +76 -80
  522. package/src/server/reserve-capability-startup.ts +32 -0
  523. package/src/server/responses/adapter-continuation.ts +2 -1
  524. package/src/server/responses/adapter-delivery.ts +4 -0
  525. package/src/server/responses/adapter-dispatch.ts +36 -17
  526. package/src/server/responses/advisor-plan-slot.ts +33 -1
  527. package/src/server/responses/advisor-question.ts +21 -0
  528. package/src/server/responses/advisor-slot.ts +10 -3
  529. package/src/server/responses/antigravity-fault-rotation.ts +24 -0
  530. package/src/server/responses/antigravity-validation-refusal.ts +43 -6
  531. package/src/server/responses/bare-namespace-aliases.ts +18 -0
  532. package/src/server/responses/buffered-sse-json.ts +9 -3
  533. package/src/server/responses/code-mode-collab-surface.ts +11 -0
  534. package/src/server/responses/codex-tool-catalog.ts +156 -0
  535. package/src/server/responses/combo-required-tool-fulfillments.ts +4 -2
  536. package/src/server/responses/combo-selection-keepalive.ts +254 -0
  537. package/src/server/responses/combo-stream-preflight.ts +557 -54
  538. package/src/server/responses/compact.ts +32 -8
  539. package/src/server/responses/core-codex-account.ts +17 -3
  540. package/src/server/responses/core-combo-failure.ts +8 -0
  541. package/src/server/responses/core-combo.ts +55 -12
  542. package/src/server/responses/core-errors.ts +13 -7
  543. package/src/server/responses/core-lifetime.ts +3 -2
  544. package/src/server/responses/core-normalize.ts +3 -1
  545. package/src/server/responses/core-options.ts +14 -0
  546. package/src/server/responses/core.ts +23 -0
  547. package/src/server/responses/estimated-usage.ts +115 -0
  548. package/src/server/responses/fetch-helpers.ts +15 -10
  549. package/src/server/responses/jev-model-invoke.ts +7 -2
  550. package/src/server/responses/native-replay-guard.ts +57 -0
  551. package/src/server/responses/opengateway-completion-guard.ts +10 -4
  552. package/src/server/responses/outbound-request-body.ts +29 -0
  553. package/src/server/responses/passthrough-completion.ts +109 -9
  554. package/src/server/responses/passthrough-delivery.ts +77 -18
  555. package/src/server/responses/passthrough-dispatch.ts +77 -73
  556. package/src/server/responses/policy-fallback.ts +13 -1
  557. package/src/server/responses/request-prepare.ts +59 -11
  558. package/src/server/responses/request-transport.ts +10 -3
  559. package/src/server/responses/reset-replay.ts +46 -2
  560. package/src/server/responses/run-turn-execution.ts +2 -0
  561. package/src/server/responses/sidecar-execution.ts +19 -0
  562. package/src/server/responses/terminal-error-redaction.ts +222 -25
  563. package/src/server/responses/ws-upstream.ts +2 -2
  564. package/src/server/sse-payload-rewrite.ts +3 -2
  565. package/src/server/stop-service-route.ts +85 -0
  566. package/src/server/system-env-shell.ts +12 -1
  567. package/src/server/system-env.ts +5 -3
  568. package/src/server/windows-tcp-drop.ts +21 -4
  569. package/src/server/workflow-refusal.ts +8 -0
  570. package/src/server/ws-bridge.ts +191 -12
  571. package/src/service/cli-windows-stop.ts +189 -0
  572. package/src/service/cli.ts +41 -12
  573. package/src/service/desktop-supervision.d.mts +2 -0
  574. package/src/service/desktop-supervision.mjs +5 -0
  575. package/src/service/disconnected-client-restart.ts +60 -0
  576. package/src/service/guarded-manager-target.ts +18 -1
  577. package/src/service/health.ts +99 -6
  578. package/src/service/launchd.ts +84 -31
  579. package/src/service/orchestration.ts +418 -91
  580. package/src/service/repair.ts +223 -6
  581. package/src/service/restart-proxy-stop.ts +79 -0
  582. package/src/service/service-child-ownership.ts +6 -2
  583. package/src/service/windows-checked-stop-live.ts +467 -0
  584. package/src/service/windows-checked-stop.ts +435 -0
  585. package/src/service/windows-command-line-token.ts +23 -0
  586. package/src/service/windows-guarded-manager.ts +77 -34
  587. package/src/service/windows-ops.ts +38 -56
  588. package/src/service/windows-process-evidence.ts +292 -0
  589. package/src/service/windows-process-native.ts +262 -0
  590. package/src/service/windows-service-stop.ts +321 -0
  591. package/src/service/windows-stop-binding.ts +187 -0
  592. package/src/service/windows-stop-budget.ts +123 -0
  593. package/src/service/windows-stop-confirm.ts +158 -0
  594. package/src/service/windows-stop-deadline.ts +56 -0
  595. package/src/service.ts +2 -2
  596. package/src/stall-timeout.ts +11 -0
  597. package/src/types/config.ts +57 -110
  598. package/src/types/link.ts +20 -0
  599. package/src/types/multi-agent.ts +13 -0
  600. package/src/types/provider.ts +60 -2
  601. package/src/types/request.ts +23 -0
  602. package/src/types/routed-catalog-defaults.ts +17 -0
  603. package/src/types/routing-profile.ts +90 -0
  604. package/src/types.ts +4 -0
  605. package/src/update/guarded-runtime-ops.ts +5 -7
  606. package/src/update/index.ts +26 -11
  607. package/src/update/install-detection.mjs +3 -1
  608. package/src/update/job-pinned-start.ts +2 -0
  609. package/src/update/job-windows-restart.ts +19 -32
  610. package/src/update/job.ts +12 -5
  611. package/src/update/npm-install.d.mts +11 -0
  612. package/src/update/npm-install.mjs +44 -7
  613. package/src/update/orchestrated-entry.ts +1 -1
  614. package/src/update/orchestrated-node-driver.mjs +3 -2
  615. package/src/update/orchestrated-pnpm.d.mts +4 -0
  616. package/src/update/orchestrated-pnpm.mjs +50 -6
  617. package/src/update/orchestrated-session.d.mts +3 -1
  618. package/src/update/orchestrated-session.mjs +21 -6
  619. package/src/update/pnpm-global-install.d.mts +21 -3
  620. package/src/update/pnpm-global-install.mjs +322 -19
  621. package/src/update/pnpm-store-layout.mjs +46 -0
  622. package/src/update/sync-update-mutex.d.mts +3 -2
  623. package/src/update/sync-update-mutex.mjs +57 -8
  624. package/src/update/transactional-install.d.mts +3 -1
  625. package/src/update/transactional-install.mjs +545 -12
  626. package/src/update/windows-installer-marker.d.mts +1 -0
  627. package/src/update/windows-installer-marker.mjs +44 -0
  628. package/src/usage/expected-prices.ts +8 -0
  629. package/src/usage/filter-index.ts +326 -77
  630. package/src/usage/ledger-scanner.ts +15 -0
  631. package/src/usage/link-log-fields.ts +48 -0
  632. package/src/usage/log.ts +57 -6
  633. package/src/usage/request-body.ts +37 -0
  634. package/src/usage/telemetry-contract.ts +1 -0
  635. package/src/web-search/loop.ts +3 -0
  636. package/src/web-search/passthrough-bridge.ts +7 -0
  637. package/gui/dist/assets/App-BpJOzw4F.js +0 -59
  638. package/gui/dist/assets/brand-mark-DU-0Vdkr.js +0 -1
  639. package/gui/dist/assets/index-Bbor_y80.js +0 -94
  640. package/gui/dist/assets/index-DJEkIDAi.css +0 -2
  641. package/gui/dist/classic/assets/App-BrIlUiLc.js +0 -58
  642. package/gui/dist/classic/assets/index-DyJHagvT.js +0 -94
  643. package/gui/dist/classic/assets/quota-summary-CakPe9Ni.js +0 -1
  644. package/src/server/management/desktop-compatibility-authorization.ts +0 -12
@@ -0,0 +1,34 @@
1
+ import type { LinkTrafficCounters } from "../link/traffic";
2
+
3
+ function isRecord(value: unknown): value is Record<string, unknown> {
4
+ return value !== null && typeof value === "object" && !Array.isArray(value);
5
+ }
6
+
7
+ function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
8
+ const actual = Object.keys(value);
9
+ return actual.length === keys.length && keys.every(key => Object.hasOwn(value, key));
10
+ }
11
+
12
+ function count(value: unknown): value is number {
13
+ return Number.isSafeInteger(value) && (value as number) >= 0;
14
+ }
15
+
16
+ const TRAFFIC_KEYS = ["since", "epoch", "generation", "requests", "incomplete", "toHomeBytes", "fromHomeBytes", "toHomeSource", "toHomeUncounted", "untrackedRequests"] as const;
17
+
18
+ function epoch(value: unknown): value is string {
19
+ return typeof value === "string" && /^[0-9a-f]{1,64}$/.test(value);
20
+ }
21
+
22
+ /** A row's `traffic` block from `?traffic=1` (#3023), validated key by key like the rest of the row. */
23
+ export function validateLinkTraffic(value: unknown, index: number): LinkTrafficCounters {
24
+ if (!isRecord(value) || !exactKeys(value, TRAFFIC_KEYS) || typeof value.since !== "string" || Number.isNaN(Date.parse(value.since))
25
+ || !epoch(value.epoch) || !count(value.generation) || !count(value.requests) || !count(value.incomplete) || !count(value.toHomeBytes) || !count(value.fromHomeBytes)
26
+ || (value.toHomeSource !== "relayed" && value.toHomeSource !== "content-length") || !count(value.toHomeUncounted) || !count(value.untrackedRequests)) {
27
+ throw new Error(`invalid link API response: link ${index} traffic`);
28
+ }
29
+ return {
30
+ since: value.since, epoch: value.epoch, generation: value.generation, requests: value.requests, incomplete: value.incomplete, toHomeBytes: value.toHomeBytes,
31
+ fromHomeBytes: value.fromHomeBytes, toHomeSource: value.toHomeSource, toHomeUncounted: value.toHomeUncounted,
32
+ untrackedRequests: value.untrackedRequests,
33
+ };
34
+ }
package/src/cli/link.ts CHANGED
@@ -7,19 +7,28 @@ import {
7
7
  import { TUNNEL_CAUSES } from "../link/tunnel-history";
8
8
  import { isEpochMs, type LinkChildParity } from "../link/child-parity";
9
9
  import { CODEX_SETTINGS_DIGEST_PATTERN } from "../link/codex-settings";
10
+ import { isRouteClientId, parseRouteClientOutcomes, ROUTE_INTENT_DIGEST_PATTERN, routeClientOutcomesForPeer } from "../link/route-intent";
10
11
  import type { LinkLocalPeer, LinkPeerStatus } from "../link/compatibility";
11
- import { runLinkEnrollment } from "./link-enrollment";
12
+ import { journalFullGuidance, runLinkEnrollment } from "./link-enrollment";
12
13
  import { runLinkCleanup, type LinkCleanupDeps } from "./link-cleanup";
13
- import { runLinkCheck } from "./link-child-ops";
14
- import { validateChildOps, type LinkChildOpsView } from "./link-status-child";
14
+ import { LINK_CAPTURE_USAGE, runLinkCapture, type LinkCaptureDeps } from "./link-capture";
15
+ import { LINK_CHILD_OPS_USAGE, runLinkActivity, runLinkCheck, runLinkChildOp, runLinkPolicy } from "./link-child-ops";
16
+ import { LINK_ROUTES_USAGE, runLinkRoutes } from "./link-routes";
17
+ import { LINK_OPERATIONS_USAGE, runLinkOperations } from "./link-operations";
18
+ import { LINK_DIAGNOSTICS_USAGE, runLinkDiagnostics } from "./link-diagnostics";
19
+ import { LINK_RECOVER_USAGE, runLinkRecover } from "./link-recover";
20
+ import { validateChildOps, validateLinkWs, type LinkChildOpsView, type LinkWsView } from "./link-status-child";
15
21
  import { assertSshAlias } from "../link/ssh-argv";
16
22
  import { boundHint } from "../link/ssh-runner";
17
23
  import { linkStorePath } from "../link/paths";
18
24
  import { isLinkPort } from "../link/ports";
19
25
  import { readLinkStore, type LinkDirection, type LinkStore } from "../link/store";
26
+ import { parseExplicitRoute } from "../link/explicit-route";
27
+ import { isOperationId } from "../link/operations-journal";
20
28
  import type { LinkChildKind } from "../link/store";
21
29
  import { findAvailablePort } from "../server/ports";
22
30
  import { viaLocalControlSocket, type LocalControlDeps } from "./link-local-control";
31
+ import { validateLinkTraffic } from "./link-status-traffic";
23
32
  import {
24
33
  CliUsageError,
25
34
  RuntimeApiError,
@@ -36,19 +45,31 @@ import {
36
45
  } from "./runtime-api";
37
46
 
38
47
  export const LINK_USAGE = `Usage:
39
- ocx link probe <alias> [--json]
40
- ocx link add <alias> [--plant] [--expect-fingerprint SHA256:…] [--json]
48
+ ocx link probe <alias> [--proxy-command <cmd> --ssh-user <user> --ssh-port <port> [--ssh-identity-file <path>]] [--exclusive] [--json]
49
+ ocx link add <alias> [--plant] [--expect-fingerprint SHA256:…] [--proxy-command <cmd> --ssh-user <user> --ssh-port <port> [--ssh-identity-file <path>]] [--exclusive] [--operation-id <id>] [--require-ephemeral] [--json]
41
50
  ocx link port [--json]
42
- ocx link issue --alias <alias> --tunnel-port <port> [--json]
51
+ ocx link issue --alias <alias> --tunnel-port <port> [--clients <id,...>] [--json]
43
52
  ocx link status [--json]
44
- ocx link revoke --link-id <id> [--purge] [--force --yes] [--json]
53
+ ${LINK_DIAGNOSTICS_USAGE}
54
+ ocx link revoke --link-id <id> [--purge] [--force --yes] [--operation-id <id>] [--json]
55
+ ${LINK_RECOVER_USAGE}
45
56
  ocx link reconnect --link-id <id> [--json]
57
+ ${LINK_ROUTES_USAGE.join("\n")}
58
+ ${LINK_OPERATIONS_USAGE.join("\n")}
46
59
  ocx link cleanup [--link-id <id>] [--json]
47
60
  ocx link check (--link-id <id> | --all) [--no-wait] [--json]
61
+ ${LINK_CHILD_OPS_USAGE.join("\n")}
62
+ ${LINK_CAPTURE_USAGE.join("\n")}
48
63
 
49
- Forced revoke skips remote cleanup. Run ocx disconnect on the remote client.
64
+ Forced revoke skips remote cleanup. On a full install run ocx disconnect --expect-link <id> there, which acts only while the machine is connected to this link; for a lightweight Child run ocx link recover --link-id <id> on this Home.
65
+ An explicit route (--proxy-command, --ssh-user and --ssh-port, with --exclusive) reaches ssh on the command line for every command and tunnel of the link, so ssh_config cannot change it; an exclusive link refuses route edits. --ssh-identity-file <path> makes ssh offer that private key alone (no agent, no default key) for every command and tunnel of the link.
66
+ Recover cleans an ephemeral Child a forced revoke or an interrupted enrollment left behind, over the link's pinned SSH trust.
50
67
  Cleanup reports each Child's platform with disconnect guidance; it changes nothing.
51
- Check reads each Home-initiated Child's installed version and update route; it changes no install.`;
68
+ Diagnostics reads this computer's bounded link diagnostics file directly; it contacts no proxy and writes nothing.
69
+ Check reads each Home-initiated Child's installed version and update route; it changes no install.
70
+ Update, sync and restart-codex run on the Child over the link's SSH trust and wait for the job unless --no-wait.
71
+ Capture opens a short, local window in which this machine's link tunnels log sanitized SSH diagnostics.
72
+ Policy reads or changes how this Home keeps its Children current; without flags it only reads.`;
52
73
 
53
74
  /**
54
75
  * What `ocx link status` prints: the runtime's status DTO itself, so a field the server adds (like
@@ -56,7 +77,7 @@ Check reads each Home-initiated Child's installed version and update route; it c
56
77
  * read tolerantly, so its type is this CLI's view of it.
57
78
  */
58
79
  export type LinkStatusPayload = Omit<LinkStatusDto, "links"> & {
59
- links: Array<Omit<LinkStatusDto["links"][number], "child"> & { child?: LinkChildOpsView }>;
80
+ links: Array<Omit<LinkStatusDto["links"][number], "child" | "ws"> & { child?: LinkChildOpsView; ws?: LinkWsView }>;
60
81
  };
61
82
 
62
83
  export interface LinkIssuePayload {
@@ -66,7 +87,7 @@ export interface LinkIssuePayload {
66
87
  listenerPort: number;
67
88
  }
68
89
 
69
- export interface LinkCliDeps extends RuntimeApiDeps, LocalControlDeps, Omit<LinkCleanupDeps, "readStore"> {
90
+ export interface LinkCliDeps extends RuntimeApiDeps, LocalControlDeps, LinkCaptureDeps, Omit<LinkCleanupDeps, "readStore"> {
70
91
  /** Test seam can shorten, never extend, the whole enrollment deadline. */
71
92
  enrollmentTimeoutMs?: number;
72
93
  choosePort?: () => Promise<number>;
@@ -76,6 +97,10 @@ export interface LinkCliDeps extends RuntimeApiDeps, LocalControlDeps, Omit<Link
76
97
  confirmFingerprint?: (host: { alias: string; fingerprint: string; keyType: string; ocxVersion?: string | null; runtimeKind?: "full" | "ephemeral" | "missing"; binarySizeBytes?: number }) => Promise<boolean>;
77
98
  readStore?: () => LinkStore;
78
99
  readAdminToken?: () => string | null;
100
+ /** Test seam for ocx link recover --forget, which a person must run (src/cli/agent-driven.ts). */
101
+ agentDriven?: () => boolean;
102
+ /** Test seam: the config directory whose link diagnostics `ocx link diagnostics` reads. */
103
+ linkConfigDir?: string;
79
104
  }
80
105
 
81
106
  const LINK_ID = /^lnk_[0-9a-f]{16}$/;
@@ -163,12 +188,14 @@ export function validateStatus(value: unknown): LinkStatusPayload {
163
188
  if (!isRecord(candidate)) throw new Error(`invalid link API response: link ${index}`);
164
189
  // The OCX-6 parity fields are optional on the wire (an older runtime omits them) and always
165
190
  // present in this output, null when absent.
166
- assertKeys(candidate, ["id", "alias", "direction", "state", "since", "reason", "tunnelPort"], [...PARITY_KEYS, "peer", "tunnel", "childKind", "child"], `link ${index}`);
191
+ assertKeys(candidate, ["id", "alias", "direction", "state", "since", "reason", "tunnelPort"], [...PARITY_KEYS, "peer", "tunnel", "childKind", "exclusive", "explicitRoute", "child", "ws", "traffic", "routes", "route", "routeBlocked"], `link ${index}`);
167
192
  const parity = validateParity(candidate, index);
168
193
  if (typeof candidate.id !== "string" || !LINK_ID.test(candidate.id)
169
194
  || !validString(candidate.alias) || (candidate.direction !== "hub-initiated" && candidate.direction !== "client-initiated")
170
195
  || (candidate.state !== "connecting" && candidate.state !== "connected" && candidate.state !== "reconnecting" && candidate.state !== "failed" && candidate.state !== "idle")
171
196
  || (candidate.childKind !== undefined && candidate.childKind !== "full" && candidate.childKind !== "ephemeral")
197
+ || (candidate.exclusive !== undefined && candidate.exclusive !== true)
198
+ || (candidate.explicitRoute !== undefined && (candidate.exclusive !== true || parseExplicitRoute(candidate.explicitRoute) === null))
172
199
  || !validString(candidate.since) || !validNullableString(candidate.reason) || !isLinkPort(candidate.tunnelPort)) {
173
200
  throw new Error(`invalid link API response: link ${index} fields`);
174
201
  }
@@ -181,10 +208,15 @@ export function validateStatus(value: unknown): LinkStatusPayload {
181
208
  reason: candidate.reason,
182
209
  tunnelPort: candidate.tunnelPort,
183
210
  ...(candidate.childKind !== undefined ? { childKind: candidate.childKind as LinkChildKind } : {}),
211
+ ...(candidate.exclusive === true ? { exclusive: true as const } : {}),
212
+ ...(candidate.explicitRoute !== undefined ? { explicitRoute: parseExplicitRoute(candidate.explicitRoute)! } : {}),
184
213
  ...parity,
185
214
  ...(candidate.peer !== undefined ? { peer: validatePeer(candidate.peer, index) } : {}),
186
215
  ...(candidate.tunnel !== undefined ? { tunnel: validateTunnel(candidate.tunnel, index) } : {}),
187
216
  ...(candidate.child !== undefined ? { child: validateChildOps(candidate.child, index) } : {}),
217
+ ...(candidate.ws !== undefined ? { ws: validateLinkWs(candidate.ws, index) } : {}),
218
+ ...(candidate.traffic !== undefined ? { traffic: validateLinkTraffic(candidate.traffic, index) } : {}),
219
+ ...validateRoutes(candidate, index),
188
220
  };
189
221
  });
190
222
  let child: LinkStatusPayload["child"] = null;
@@ -229,10 +261,15 @@ function validateIssue(value: unknown): LinkIssuePayload {
229
261
  };
230
262
  }
231
263
 
232
- function validateRevoke(value: unknown, expectedLinkId: string): void {
264
+ function validateRevoke(value: unknown, expectedLinkId: string, operationId?: string): void {
233
265
  if (value === null) return;
234
266
  if (!isRecord(value)) throw new Error("invalid link API response: revoke object");
235
- assertExactKeys(value, ["linkId"], "revoke");
267
+ if (operationId === undefined) assertExactKeys(value, ["linkId"], "revoke");
268
+ else {
269
+ // A journalled revoke (structure/remote-link.md, "Operation journal") answers its outcome and, for a purge, the receipt.
270
+ assertKeys(value, ["linkId", "operationId", "outcome"], ["purged"], "revoke");
271
+ if (value.operationId !== operationId || value.outcome !== "committed" || (value.purged !== undefined && value.purged !== true)) throw new Error("invalid link API response: revoke operation");
272
+ }
236
273
  if (value.linkId !== expectedLinkId) throw new Error("invalid link API response: revoke link id");
237
274
  }
238
275
 
@@ -262,7 +299,9 @@ async function linkRequest<T>(path: string, init: RequestInit, deps: LinkCliDeps
262
299
  }
263
300
  }
264
301
 
265
- function errorCodeBody(body: unknown): { error: { code: string; hint?: string }; residual?: true } | null {
302
+ const OPERATION_OUTCOMES = new Set(["committed", "failed_clean", "residual", "unknown"]);
303
+
304
+ function errorCodeBody(body: unknown): { error: { code: string; hint?: string; cause?: string }; residual?: true; operationId?: string; outcome?: string; residualKind?: string; residualInstall?: "ephemeral" | "full"; linkId?: string; remotePlatform?: "posix" | "windows"; operationState?: "open" | "unknown"; bound?: "unsettled" | "recent" } | null {
266
305
  if (!isRecord(body) || !isRecord(body.error)) return null;
267
306
  const code = body.error.code;
268
307
  if (typeof code !== "string" || !/^[a-z_]{1,64}$/.test(code)) return null;
@@ -270,7 +309,23 @@ function errorCodeBody(body: unknown): { error: { code: string; hint?: string };
270
309
  // line, already bounded and redacted, and it is bounded and redacted again here. The rest of
271
310
  // the body is still never echoed.
272
311
  const hint = typeof body.error.hint === "string" ? boundHint(body.error.hint) : undefined;
273
- return { error: { code, ...(hint ? { hint } : {}) }, ...(body.residual === true ? { residual: true as const } : {}) };
312
+ // A cause is a class word (an unproven route's `hostkey`, `auth`, ...): kept only in that shape.
313
+ const cause = typeof body.error.cause === "string" && /^[a-z_]{1,32}$/.test(body.error.cause) ? body.error.cause : undefined;
314
+ // An operation's id and outcome (structure/remote-link.md, "Operation journal") are closed forms, kept as such.
315
+ const operationId = typeof body.operationId === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(body.operationId) ? body.operationId : undefined;
316
+ const outcome = typeof body.outcome === "string" && OPERATION_OUTCOMES.has(body.outcome) ? body.outcome : undefined;
317
+ const residualKind = body.residualKind === "plant" || body.residualKind === "enrollment" ? body.residualKind : undefined;
318
+ // A residual's Child step is bound to the attempt's link id: a link id shape, the install and the platform as closed words.
319
+ const residualInstall = body.residualInstall === "ephemeral" || body.residualInstall === "full" ? body.residualInstall : undefined;
320
+ const linkId = typeof body.linkId === "string" && LINK_ID.test(body.linkId) ? body.linkId : undefined;
321
+ const remotePlatform = body.remotePlatform === "posix" || body.remotePlatform === "windows" ? body.remotePlatform : undefined;
322
+ // link_suspended names whether the revoke that keeps the link down is open (it did not record its outcome) or unknown.
323
+ const operationState = body.operationState === "open" || body.operationState === "unknown" ? body.operationState : undefined;
324
+ // operation_journal_full names which bound it hit.
325
+ const bound = body.bound === "unsettled" || body.bound === "recent" ? body.bound : undefined;
326
+ return { error: { code, ...(hint ? { hint } : {}), ...(cause ? { cause } : {}) }, ...(body.residual === true ? { residual: true as const } : {}),
327
+ ...(operationId ? { operationId } : {}), ...(outcome ? { outcome } : {}), ...(residualKind ? { residualKind } : {}), ...(residualInstall ? { residualInstall } : {}),
328
+ ...(linkId ? { linkId } : {}), ...(remotePlatform ? { remotePlatform } : {}), ...(operationState ? { operationState } : {}), ...(bound ? { bound } : {}) };
274
329
  }
275
330
 
276
331
  async function runPort(args: string[], deps: LinkCliDeps): Promise<void> {
@@ -284,6 +339,9 @@ async function runPort(args: string[], deps: LinkCliDeps): Promise<void> {
284
339
  async function runIssue(args: string[], deps: LinkCliDeps): Promise<void> {
285
340
  takeJsonFlag(args);
286
341
  const alias = takeOption(args, "--alias");
342
+ const rawClients = takeOption(args, "--clients");
343
+ const selectedClients = rawClients?.split(",");
344
+ if (selectedClients && (!selectedClients.length || !selectedClients.every(isRouteClientId) || new Set(selectedClients).size !== selectedClients.length)) throw new CliUsageError("--clients needs unique supported client IDs", LINK_USAGE);
287
345
  const tunnelPort = takeIntegerOption(args, "--tunnel-port", { min: 1024 });
288
346
  if (!alias || tunnelPort === undefined || !isLinkPort(tunnelPort)) {
289
347
  throw new CliUsageError("issue requires --alias and --tunnel-port", LINK_USAGE);
@@ -294,7 +352,7 @@ async function runIssue(args: string[], deps: LinkCliDeps): Promise<void> {
294
352
  const result = validateIssue(await linkRequest<unknown>("/api/link/issue", {
295
353
  method: "POST",
296
354
  headers: { "content-type": "application/json" },
297
- body: JSON.stringify({ alias, tunnelPort }),
355
+ body: JSON.stringify({ alias, tunnelPort, ...(selectedClients ? { selectedClients } : {}) }),
298
356
  }, deps));
299
357
  console.log(JSON.stringify(result));
300
358
  }
@@ -313,10 +371,10 @@ async function runStatus(args: string[], deps: LinkCliDeps): Promise<void> {
313
371
  }
314
372
  throw error;
315
373
  }
316
- // A proxy older than the compatibility report, the tunnel diagnostics or the Child block ignores
317
- // the query and answers without those fields.
374
+ // A proxy older than the compatibility report, the tunnel diagnostics, the Child block, the link WebSocket counters or
375
+ // the traffic counters ignores the query and answers without those fields.
318
376
  const result = validateStatus(await viaLocalControlSocket(baseUrl, deps,
319
- statusDeps => linkRequest<unknown>("/api/link/status?compatibility=1&diagnostics=1&children=1", {}, statusDeps)));
377
+ statusDeps => linkRequest<unknown>("/api/link/status?compatibility=1&diagnostics=1&children=1&transport=1&traffic=1&routes=1", {}, statusDeps)));
320
378
  console.log(JSON.stringify(result));
321
379
  }
322
380
 
@@ -326,34 +384,47 @@ async function runRevoke(args: string[], deps: LinkCliDeps): Promise<void> {
326
384
  const force = takeFlag(args, "--force");
327
385
  const confirmed = takeFlag(args, "--yes");
328
386
  const linkId = takeOption(args, "--link-id");
387
+ const operationId = takeOption(args, "--operation-id");
329
388
  if (!linkId || !LINK_ID.test(linkId)) throw new CliUsageError("revoke requires a valid --link-id", LINK_USAGE);
330
389
  rejectArgs(args, LINK_USAGE);
390
+ if (operationId !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(operationId)) throw new CliUsageError("--operation-id is not a valid operation id", LINK_USAGE);
391
+ const operationBody = operationId !== undefined ? { operationId } : {};
331
392
  if (purge && force) throw new CliUsageError("--purge cannot be combined with --force", LINK_USAGE);
332
393
  if (force && !confirmed) throw new CliUsageError("forced revoke skips remote cleanup; pass --yes to confirm", LINK_USAGE);
333
394
  if (confirmed && !force) throw new CliUsageError("--yes requires --force", LINK_USAGE);
334
- let wasEphemeral = false;
395
+ // The Child type the forced revoke's step depends on; unknown for a link saved before the Home recorded it, a link the store does
396
+ // not list, or a store the CLI cannot read (then no tombstone may have been kept, and the machine may run either install).
397
+ let childKind: "ephemeral" | "full" | "unknown" = "unknown";
335
398
  if (force) {
336
399
  try {
337
400
  const store = (deps.readStore ?? (() => readLinkStore(linkStorePath())))();
338
- wasEphemeral = store.links.find(l => l.id === linkId)?.childKind === "ephemeral";
339
- } catch { /* fallback to standard recovery message when store is unavailable */ }
401
+ const kind = store.links.find(l => l.id === linkId)?.childKind;
402
+ if (kind === "ephemeral" || kind === "full") childKind = kind;
403
+ } catch { /* the unknown-type step covers a store that cannot be read */ }
340
404
  }
341
405
  let remoteCleanup: "skipped" | "unverified" = "skipped";
406
+ let recordedOutcome: unknown;
342
407
  try {
343
408
  const response = await linkRequest<unknown>(`/api/link/${encodeURIComponent(linkId)}`, force ? {
344
409
  method: "DELETE",
345
410
  redirect: "error",
346
411
  headers: { "content-type": "application/json" },
347
- body: JSON.stringify({ force: true }),
348
- } : purge ? {
412
+ body: JSON.stringify({ force: true, ...operationBody }),
413
+ } : purge || operationId !== undefined ? {
349
414
  method: "DELETE",
350
415
  redirect: "error",
351
416
  headers: { "content-type": "application/json" },
352
- body: JSON.stringify({ purge: true }),
417
+ body: JSON.stringify({ ...(purge ? { purge: true } : {}), ...operationBody }),
353
418
  } : { method: "DELETE" }, deps);
354
- // Legacy revoke accepts an empty response; a forced receipt needs observed identity.
355
- if (force && response === null) throw new Error("invalid link API response: revoke object");
356
- validateRevoke(response, linkId);
419
+ // Legacy revoke accepts an empty response; a forced receipt needs observed identity, and so does an operation.
420
+ if ((force || operationId !== undefined) && response === null) throw new Error("invalid link API response: revoke object");
421
+ validateRevoke(response, linkId, operationId);
422
+ if (isRecord(response)) recordedOutcome = response.outcome;
423
+ if (operationId !== undefined && !force) {
424
+ const receipt = response as Record<string, unknown>;
425
+ console.log(JSON.stringify({ linkId, operationId, outcome: receipt.outcome, ...(receipt.purged === true ? { purged: true } : {}) }));
426
+ return;
427
+ }
357
428
  } catch (error) {
358
429
  // Revoke is idempotent: a link the Home no longer has is already revoked, and a Child retrying
359
430
  // a join rollback depends on that answer being success. A 404 without this code comes from a
@@ -361,15 +432,23 @@ async function runRevoke(args: string[], deps: LinkCliDeps): Promise<void> {
361
432
  const code = error instanceof RuntimeApiError && error.status === 404 ? errorCodeBody(error.body)?.error.code : undefined;
362
433
  if (code !== "link_not_found") {
363
434
  if (force && !(error instanceof RuntimeApiError)) throw new Error("Forced link revoke failed; inspect link status before retrying.");
364
- throw error;
435
+ throw operationId !== undefined ? journalledRevokeError(error, operationId, linkId) : plainRevokeError(error);
365
436
  }
437
+ // A journalled revoke must not read as done when nothing was journalled: the caller settles a vanished link itself.
438
+ if (operationId !== undefined) throw new RuntimeApiError("Link " + linkId + " is not on this Home; no revoke was journalled (code link_not_found).", 404, error instanceof RuntimeApiError ? error.body : null);
366
439
  remoteCleanup = "unverified";
367
440
  }
368
441
  if (force) {
369
- const recovery = wasEphemeral
370
- ? "Run ~/.cache/opencodex/bin/ocx-child detach on the remote client."
371
- : "Run ocx disconnect on the remote client.";
372
- printData({ linkId, remoteCleanup, recovery }, wantsJson, [
442
+ const recovery = childKind === "ephemeral"
443
+ // Never a bare local disconnect: a forced revoke is also the remedy when the Child now belongs to another link, a hub or
444
+ // another Home, and a disconnect run there would remove that link. The link-bound recover checks ownership itself.
445
+ ? `Run ocx link recover --link-id ${linkId} once the machine answers: it acts only when the machine's records name this link or nothing at all, and refuses a machine another link owns.`
446
+ // The bound disconnect (#8662) acts only while the machine is connected to this link, which closes the race between a check
447
+ // and a plain disconnect; an ocx older than the flag refuses it before it acts on the link, and then the check comes first.
448
+ : childKind === "unknown"
449
+ ? `The Child type is not known here (${remoteCleanup === "unverified" ? "the link is no longer on this Home, so no record of it says" : "the link was saved before the Home recorded it, or its record could not be read"}). If ocx link recover --list shows ${linkId}, run ocx link recover --link-id ${linkId} once the machine answers. Otherwise, once it answers, run ocx disconnect --expect-link ${linkId} on a full install, or the planted ocx-child's detach --expect-link ${linkId} on a lightweight Child (~/.cache/opencodex/bin/ocx-child; in Command Prompt on Windows %LOCALAPPDATA%\\opencodex\\bin\\ocx-child.exe, or %USERPROFILE%\\.cache\\opencodex\\bin\\ocx-child.exe where LOCALAPPDATA is not set): either refuses a machine that another link, a hub or another Home owns. A build older than that flag refuses it as a usage error before it acts on the link. Then, on a full install, check ocx connect status --json and run ocx disconnect only if it shows this link's id or no connection, right after that check (an enrollment that lands between the two commands would be removed); if it shows another link, a hub or another Home, or its state cannot be read, leave it as it is. On a lightweight Child, leave it as it is: its status cannot show an interrupted attach of another link, which a plain ocx-child detach would restore and then remove.`
450
+ : `Run ocx disconnect --expect-link ${linkId} on the remote client once it answers: it disconnects only while the machine is connected to this link, so a newer link is never removed. An OpenCodex older than that flag refuses it as a usage error before it acts on the link; then check ocx connect status --json there and run ocx disconnect only if it shows this link's id or no connection, right after that check (an enrollment that lands between the two commands would be removed). If it shows another link, a hub or another Home, or its state cannot be read, leave it as it is.`;
451
+ printData({ linkId, remoteCleanup, recovery, ...(operationId !== undefined && recordedOutcome !== undefined ? { operationId, outcome: recordedOutcome } : {}) }, wantsJson, [
373
452
  remoteCleanup === "skipped" ? `Revoked ${linkId}; remote cleanup was skipped.` : `Link ${linkId} is already absent; remote cleanup is unverified.`,
374
453
  recovery,
375
454
  ]);
@@ -383,13 +462,35 @@ async function runReconnect(args: string[], deps: LinkCliDeps): Promise<void> {
383
462
  const linkId = takeOption(args, "--link-id");
384
463
  if (!linkId || !LINK_ID.test(linkId)) throw new CliUsageError("reconnect requires a valid --link-id", LINK_USAGE);
385
464
  rejectArgs(args, LINK_USAGE);
386
- const response = await linkRequest<unknown>(`/api/link/${encodeURIComponent(linkId)}/reconnect`, { method: "POST" }, deps);
465
+ let response: unknown;
466
+ try {
467
+ response = await linkRequest<unknown>(`/api/link/${encodeURIComponent(linkId)}/reconnect`, { method: "POST" }, deps);
468
+ } catch (error) {
469
+ throw suspendedReconnect(error, linkId) ?? error;
470
+ }
387
471
  if (!isRecord(response)) throw new Error("invalid link API response: reconnect object");
388
472
  assertExactKeys(response, ["linkId"], "reconnect");
389
473
  if (response.linkId !== linkId) throw new Error("invalid link API response: reconnect link id");
390
474
  console.log(JSON.stringify({ linkId }));
391
475
  }
392
476
 
477
+ /**
478
+ * 409 link_suspended: an unsettled revoke keeps the link down. The next step is built here from the validated operation id,
479
+ * never from the server's text; a 409 keeps the CLI's exit 5.
480
+ */
481
+ function suspendedReconnect(error: unknown, linkId: string): RuntimeApiError | null {
482
+ if (!(error instanceof RuntimeApiError) || error.status !== 409 || errorCodeBody(error.body)?.error.code !== "link_suspended") return null;
483
+ const body = isRecord(error.body) ? error.body : {};
484
+ const op = isOperationId(body.operationId) ? body.operationId : null;
485
+ const resolve = op ? "ocx link operations resolve --operation-id " + op + " --yes" : null;
486
+ const message = !op
487
+ ? "Link " + linkId + " is kept down by an unsettled revoke; find it with ocx link operations, then resolve it."
488
+ : body.operationState === "open"
489
+ ? "Link " + linkId + " is kept down: revoke operation " + op + " did not record its outcome (the Home stopped or the revoke failed before writing it). Repeat it with the flags of the first attempt: ocx link revoke --link-id " + linkId + " --operation-id " + op + ", with --purge only if the first attempt had it (the journal keeps only a digest of the flags, so a different --purge answers operation_mismatch); if it then ends unknown, run: " + resolve
490
+ : "Link " + linkId + " is kept down: revoke operation " + op + " ended unknown and may have disconnected or purged the Child. Check the Child, then run: " + resolve;
491
+ return new RuntimeApiError(message, 409, error.body);
492
+ }
493
+
393
494
  export async function runLinkCommand(rawArgs: string[], deps: LinkCliDeps = {}): Promise<number> {
394
495
  // runCliAction maps thrown errors (2 usage, 4 on 404, 5 on 409, else 1) and returns 0 on success, so a
395
496
  // verb's own verdict exit (check: 6 for a partial result) travels beside it.
@@ -401,16 +502,58 @@ export async function runLinkCommand(rawArgs: string[], deps: LinkCliDeps = {}):
401
502
  else if (command === "port") await runPort(args, deps);
402
503
  else if (command === "issue") await runIssue(args, deps);
403
504
  else if (command === "status") await runStatus(args, deps);
505
+ else if (command === "diagnostics") await runLinkDiagnostics(args, deps, LINK_USAGE);
404
506
  else if (command === "revoke") await runRevoke(args, deps);
507
+ else if (command === "recover") await runLinkRecover(args, deps, linkRequest, LINK_USAGE);
405
508
  else if (command === "reconnect") await runReconnect(args, deps);
406
509
  else if (command === "cleanup") await runLinkCleanup(args, deps, LINK_USAGE);
407
510
  else if (command === "check") verdictExit = await runLinkCheck(args, deps, linkRequest, LINK_USAGE);
408
- else throw new CliUsageError("link requires one of: probe, add, port, issue, status, revoke, reconnect, cleanup, check", LINK_USAGE);
511
+ else if (command === "update" || command === "sync" || command === "restart-codex") verdictExit = await runLinkChildOp(command, args, deps, linkRequest, LINK_USAGE);
512
+ else if (command === "capture") await runLinkCapture(args, deps, LINK_USAGE);
513
+ else if (command === "policy") await runLinkPolicy(args, deps, linkRequest, LINK_USAGE);
514
+ else if (command === "routes") await runLinkRoutes(args, deps, linkRequest, LINK_USAGE);
515
+ else if (command === "operations") await runLinkOperations(args, deps, linkRequest, LINK_USAGE);
516
+ else if (command === "activity") await runLinkActivity(args, deps, linkRequest, LINK_USAGE);
517
+ else throw new CliUsageError("link requires one of: probe, add, port, issue, status, diagnostics, revoke, recover, reconnect, routes, operations, cleanup, check, update, sync, restart-codex, capture, policy, activity", LINK_USAGE);
409
518
  });
410
519
  return code === 0 ? verdictExit : code;
411
520
  }
412
521
 
413
- const PARITY_KEYS = ["lastApplyAt", "runtimeStartedAt", "appliedCodexSettingsDigest", "reportedAt"] as const;
522
+ const PARITY_KEYS = ["lastApplyAt", "runtimeStartedAt", "appliedCodexSettingsDigest", "reportedAt", "appliedRouteIntentDigest", "routeClientOutcomes"] as const;
523
+ const ROUTE_OUTCOMES = new Set(["transient", "readiness", "grant_unobserved", "forward", "auth", "hostkey"]);
524
+ const ROUTE_BLOCKS = new Set(["ssh_client_unsupported", "stop_unconfirmed"]);
525
+
526
+ /** The `?routes=1` fields of a multi-route row, all three or none. */
527
+ function validateRoutes(candidate: Record<string, unknown>, index: number): Pick<LinkStatusPayload["links"][number], "routes" | "route" | "routeBlocked"> {
528
+ const fail = (): never => { throw new Error(`invalid link API response: link ${index} routes`); };
529
+ const { routes, route, routeBlocked } = candidate;
530
+ if (routes === undefined && route === undefined && routeBlocked === undefined) return {};
531
+ if (!Array.isArray(routes) || routes.length < 2 || route === undefined || routeBlocked === undefined) return fail();
532
+ const parsed = routes.map(entry => {
533
+ if (!isRecord(entry)) return fail();
534
+ assertExactKeys(entry, ["name", "eligibleAt", "lastOutcome"], `link ${index} route entry`);
535
+ if (!validString(entry.name) || (entry.eligibleAt !== null && !validIso(entry.eligibleAt))) fail();
536
+ const outcome = entry.lastOutcome;
537
+ if (outcome !== null) {
538
+ if (!isRecord(outcome)) return fail();
539
+ assertExactKeys(outcome, ["class", "at"], `link ${index} route outcome`);
540
+ if (!ROUTE_OUTCOMES.has(outcome.class as string) || !validIso(outcome.at)) fail();
541
+ }
542
+ return entry as unknown as NonNullable<LinkStatusPayload["links"][number]["routes"]>[number];
543
+ });
544
+ if (route !== null) {
545
+ if (!isRecord(route)) return fail();
546
+ assertExactKeys(route, ["name", "index", "since"], `link ${index} route`);
547
+ if (!validString(route.name) || typeof route.index !== "number" || !Number.isSafeInteger(route.index) || route.index < 0
548
+ || route.index >= routes.length || !validIso(route.since)) fail();
549
+ }
550
+ if (routeBlocked !== null && !ROUTE_BLOCKS.has(routeBlocked as string)) fail();
551
+ return {
552
+ routes: parsed,
553
+ route: route as LinkStatusPayload["links"][number]["route"],
554
+ routeBlocked: routeBlocked as LinkStatusPayload["links"][number]["routeBlocked"],
555
+ };
556
+ }
414
557
  const WIRE_STATES = new Set(["connecting", "connected", "reconnecting", "failed", "idle"]);
415
558
  const CAUSES = new Set<string>(TUNNEL_CAUSES);
416
559
 
@@ -450,10 +593,145 @@ function validateParity(candidate: Record<string, unknown>, index: number): Link
450
593
  if (digest !== undefined && digest !== null && (typeof digest !== "string" || !CODEX_SETTINGS_DIGEST_PATTERN.test(digest))) {
451
594
  throw new Error(`invalid link API response: link ${index} appliedCodexSettingsDigest`);
452
595
  }
596
+ let route: Pick<LinkChildParity, "appliedRouteIntentDigest" | "routeClientOutcomes"> = {};
597
+ if (candidate.appliedRouteIntentDigest !== undefined || candidate.routeClientOutcomes !== undefined) {
598
+ const routeDigest = candidate.appliedRouteIntentDigest;
599
+ const outcomes = parseRouteClientOutcomes(candidate.routeClientOutcomes);
600
+ if ((routeDigest !== null && (typeof routeDigest !== "string" || !ROUTE_INTENT_DIGEST_PATTERN.test(routeDigest))) || !outcomes) {
601
+ throw new Error(`invalid link API response: link ${index} route intent`);
602
+ }
603
+ route = { appliedRouteIntentDigest: routeDigest, routeClientOutcomes: routeClientOutcomesForPeer(outcomes) };
604
+ }
453
605
  return {
454
606
  lastApplyAt: time("lastApplyAt"),
455
607
  runtimeStartedAt: time("runtimeStartedAt"),
456
608
  appliedCodexSettingsDigest: typeof digest === "string" ? digest : null,
457
609
  reportedAt: time("reportedAt"),
610
+ ...route,
458
611
  };
459
612
  }
613
+
614
+ /**
615
+ * A journalled revoke that did not complete: the CLI's own text from the filtered body only, the caller's validated
616
+ * operation id, the closed outcome and the filtered code, never the server's message. The status (and exit) stay.
617
+ */
618
+ export function journalledRevokeError(error: unknown, operationId: string, linkId?: string): unknown {
619
+ if (!(error instanceof RuntimeApiError) || !isRecord(error.body) || !isRecord(error.body.error) || typeof error.body.error.code !== "string") return error;
620
+ const code = error.body.error.code;
621
+ // The filtered body is re-checked here, as journalFullGuidance re-checks bound, so this helper is safe on its own.
622
+ if (!/^[a-z_]{1,64}$/.test(code)) return error;
623
+ // Commands are printed so that they run as printed: only a validated link id, a placeholder otherwise.
624
+ const shownLink = linkId !== undefined && LINK_ID.test(linkId) ? linkId : "<link id>";
625
+ if (code === "operation_journal_full") return new RuntimeApiError(journalFullGuidance(error.body, "revoke"), error.status, error.body);
626
+ if (Object.hasOwn(REVOKE_REFUSALS, code)) return new RuntimeApiError(REVOKE_REFUSALS[code] + " (code " + code + ")", error.status, error.body);
627
+ if (Object.hasOwn(RETIREMENT_GUIDANCE, code)) return new RuntimeApiError(RETIREMENT_GUIDANCE[code]!(shownLink) + " (code " + code + ")", error.status, error.body);
628
+ // A fresh forced revoke is refused before its tombstone, first intent and tunnel stop and its refusal is recorded; a resumed one
629
+ // (even one recorded failed_clean) may re-own its retirement receipt first and can finish under the same id once capacity is
630
+ // freed, while a new id is refused with link_retirement_owned (#8416). A second refusal proves nothing (the live limit can still be
631
+ // full), so the text never declares the refusal recorded: the same id first, then a new id, whose link_retirement_owned is safe.
632
+ // That answer names an unfinished removal of the link, which may belong to another operation or to a plain revoke, so the text
633
+ // points at the owner (ocx link operations) or a plain --force instead of claiming this id owns it.
634
+ // It never says the link or key stay active either: an earlier attempt of a resumed revoke may have revoked the key and stopped
635
+ // the tunnel before it failed and dropped its own tombstone, and this repeat then meets the limit while re-recording one. Nor that
636
+ // this attempt left the link alone: the commit-time check (#8662) meets the limit after this attempt stopped the tunnel.
637
+ if (code === "tombstone_limit") {
638
+ return new RuntimeApiError("Too many forced revokes of ephemeral Children are waiting for cleanup; this attempt revoked no key, removed no record and did not contact the Child. Recover them with ocx link recover --link-id <id> (ocx link recover --list shows them), or have a person on this Home run ocx link recover --forget --link-id <id> --yes for machines that are gone. Then repeat this revoke with the same operation id (ocx link revoke --link-id " + shownLink + " --operation-id " + operationId + " --force --yes): an interrupted removal resumes under it. If it answers this refusal again although capacity is free, try a new operation id; if that answers link_retirement_owned, an unfinished removal holds this link: repeat the revoke of this link that owns it, whatever its recorded state (ocx link operations --json shows each entry's linkId), or finish it with ocx link revoke --link-id " + shownLink + " --force --yes without --operation-id. (code tombstone_limit)", error.status, error.body);
639
+ }
640
+ const outcome = error.body.operationId === operationId && typeof error.body.outcome === "string" && OPERATION_OUTCOMES.has(error.body.outcome) ? error.body.outcome : undefined;
641
+ // Repeating first resumes a removal if this id still owns one (#8416); resolving first would leave its receipt and record behind. An
642
+ // unknown can also arise before any receipt was claimed (a disconnect timeout or failure, a journal write), so the resume is
643
+ // conditional. A resume while the record is still listed reopens the entry, and one that fails and cannot settle leaves it open,
644
+ // which resolve refuses (operation_not_resolvable), so the next step follows the state the repeat left: resolve only unknown or
645
+ // residual. A resume whose record was already gone settles committed, and clearing its receipt can still fail (503): one more
646
+ // repeat clears what it left.
647
+ const resolve = outcome === "unknown" ? "; repeat the revoke with the same operation id first (if this id still owns an unfinished removal, the repeat resumes it). If it does not finish, ocx link operations --operation-id " + operationId + " shows its state: if it reads committed, the removal finished: repeat it once more to clear what it left; if it reads unknown or residual, check the Child, then run ocx link operations resolve --operation-id " + operationId + " --yes; if it reads open, fix what stopped the revoke (for example the journal's disk) and repeat it with the same operation id" : "";
648
+ const next = Object.hasOwn(NEXT_STEP, code) ? ". " + NEXT_STEP[code] : "";
649
+ // A link-bound refusal's hint (#8662), only from the closed set and only in its plain-word form; never the server's text.
650
+ const hint = code === "remote_disconnect_failed" ? boundRefusalHint(error) : undefined;
651
+ const hinted = hint !== undefined ? ". " + BOUND_REFUSAL_HINTS[hint]!(againFor(outcome)) : "";
652
+ return new RuntimeApiError("Link revoke did not complete" + (outcome ? " (operation " + operationId + ": " + outcome + ")" : "") + " (code " + code + (hint !== undefined ? ", hint " + hint : "") + ")" + resolve + next + hinted, error.status, error.body);
653
+ }
654
+
655
+ /** The validated link-bound hint of a remote_disconnect_failed answer (#8662), only from the closed set and only in plain-word form. */
656
+ function boundRefusalHint(error: RuntimeApiError): string | undefined {
657
+ const body = error.body;
658
+ const raw = isRecord(body) && isRecord(body.error) && body.error.code === "remote_disconnect_failed" ? body.error.hint : undefined;
659
+ return typeof raw === "string" && /^[a-z0-9_-]{1,64}$/.test(raw) && Object.hasOwn(BOUND_REFUSAL_HINTS, raw) ? raw : undefined;
660
+ }
661
+
662
+ /** A plain revoke refused by the Child keeps the generic error unless its hint is in the closed set; the server's text is never shown. */
663
+ function plainRevokeError(error: unknown): unknown {
664
+ if (!(error instanceof RuntimeApiError)) return error;
665
+ const hint = boundRefusalHint(error);
666
+ if (hint === undefined) return error;
667
+ return new RuntimeApiError("Link revoke did not complete (code remote_disconnect_failed, hint " + hint + "). " + BOUND_REFUSAL_HINTS[hint]!(againFor(undefined)), error.status, error.body);
668
+ }
669
+
670
+ /**
671
+ * The step after a refused revoke, chosen by the outcome the answer recorded: a failed_clean entry only replays its answer, so
672
+ * the revoke runs again under a new id; an unknown one may own an unfinished removal, which the same id resumes.
673
+ */
674
+ function againFor(outcome: string | undefined): string {
675
+ if (outcome === "failed_clean") return "revoke again with a new operation id (repeating this id only replays this answer)";
676
+ if (outcome === "unknown") return "repeat the revoke with the same operation id";
677
+ return "revoke again";
678
+ }
679
+
680
+ /**
681
+ * What a link-bound refusal means (the hints of remote_disconnect_failed). A text claims only what this attempt's Child command
682
+ * did; an earlier attempt of a resumed revoke may have done more. A disconnect is named only after the check that allows it
683
+ * (this link's id or no connection); every other branch says what not to do and which Home-side command to run.
684
+ */
685
+ const BOUND_REFUSAL_HINTS: Record<string, (again: string) => string> = {
686
+ child_link_mismatch: again => "The Child refused because of who it belongs to or what state it is in, and this attempt left its link state as it was. Do not disconnect it there. Check it with ocx connect status --json (on a lightweight Child, connect status --json of its planted ocx-child, ~/.cache/opencodex/bin/ocx-child, or in Command Prompt on Windows %LOCALAPPDATA%\\opencodex\\bin\\ocx-child.exe, or %USERPROFILE%\\.cache\\opencodex\\bin\\ocx-child.exe where LOCALAPPDATA is not set): if it shows another link, a hub or another Home, or no connection, revoke this link with --force once any enrollment of this link has finished. If it shows this link's id, a connect or key rotation of it may be in progress: let it finish on the Child, then " + again + "; if the same answer comes back, revoke this link with --force once any enrollment of this link has finished. If its state cannot be read, repair it on the Child, then " + again + "; if you cannot, or the machine cannot be reached, revoke this link with --force once any enrollment of this link has finished",
687
+ child_residual: () => "The lightweight Child keeps records it cannot restore, and this attempt left them as they were. Do not run a plain ocx-child detach on it: an interrupted attach of another link can be what is left, and a plain detach would remove that link too. Revoke this link with --force",
688
+ child_disconnect_pending: again => "The Child has an unfinished disconnect it could not tie to this link and may be partly cleaned. Check it with ocx connect status --json, which cannot say whose disconnect it is: only if it shows no connection, finish it there with ocx disconnect, then " + again + ". If it shows any link, a hub or another Home, if its state cannot be read, or if the machine cannot be reached, leave it and revoke this link with --force. If ocx disconnect refuses the receipt as unsafe, revoke with --force too",
689
+ expect_link_unsupported: again => "The Child runs an ocx or ocx-child older than --expect-link and another Home-initiated link of this Home may reach the same machine, so it was not disconnected without the link check. Update OpenCodex on a full install, then " + again + " (an older planted ocx-child cannot be updated from this Home). Otherwise revoke this link with --force. Revoking the other link instead is no way out unless you mean to end it: no status check can show it is stale (an attach of it still in progress can show no link or an earlier one, and state that cannot be read shows none), under the same pinned host key its revoke is refused the same way, and through a shared route it disconnects the machine if the machine runs that link",
690
+ };
691
+
692
+ /**
693
+ * A next step for codes that keep the generic text because what an earlier step changed differs by path. Where a repeat can
694
+ * answer the same code again, the text says what that answer means and what a different step can and cannot do, so it never
695
+ * sends the caller round the same step for ever.
696
+ */
697
+ const NEXT_STEP: Record<string, string> = {
698
+ // A resumed owner can meet the same live write failure again and keep its receipt, so a repeat proves nothing: the same id after
699
+ // the fix, and a new id only through link_retirement_owned's guidance if one is tried.
700
+ operation_journal_failed: "The journal could not record a step: fix what keeps it from being written (disk space, permissions), then repeat the revoke with the same operation id. If it keeps answering operation_journal_failed, a new operation id can be tried; if that answers link_retirement_owned, this id may still own the removal: follow that answer",
701
+ // A stale retirement receipt (the record was edited after a removal claimed it) answers link_changed to every revoke, this id's
702
+ // resume included, until the record matches the receipt's copy again. A current Home refuses a route edit while a receipt is
703
+ // outstanding (link_retirement_pending, #8678), so only an older Home's ocx link routes, which did not check, or an edit by
704
+ // hand leaves one stale. A claim that met a changed record (no receipt for this id) is journalled, so this id replays it while a
705
+ // new id reads the record afresh; a commit that met one leaves this id's receipt, so its repeat resumes the removal and meets
706
+ // the same comparison. In one runtime a revoke and a route edit hold the same Child-job reservation, so the code never proves
707
+ // that the link changed while this revoke ran.
708
+ link_changed: "The link, or the record of its unfinished removal, no longer matches what this removal started from: read ocx link status, then repeat the revoke with the same operation id. If it answers link_changed again, the link was edited after its removal began, by ocx link routes on an older Home that did not refuse route edits during a removal or by hand. A new operation id can remove it only when no unfinished removal of this link remains; while one remains, no revoke finishes it until the link matches that removal's copy again",
709
+ };
710
+
711
+ /**
712
+ * #8416's refusals for an interrupted removal of the link. The owning operation and the way out are only in the server's message,
713
+ * which the CLI never prints, so these name where to look and make no claim about what an earlier attempt changed.
714
+ */
715
+ const RETIREMENT_GUIDANCE: Record<string, (link: string) => string> = {
716
+ // A journalled owner refuses any revoke without --force that is not its own id; a plain revoke without --force finishes only
717
+ // a removal no journalled operation owns (link-routes.ts foreignRetirement). A revoke without --force refuses --yes.
718
+ link_retirement_owned: link => "An unfinished removal holds this link. Repeat the revoke of this link that owns it, whatever its recorded state (ocx link operations --json shows each entry's linkId; another revoke's id answers its own outcome or this refusal again), or finish it with ocx link revoke --link-id " + link + " --force --yes without --operation-id. If no journalled operation owns it, ocx link revoke --link-id " + link + " without --operation-id and without --force also finishes it when its Child cleanup can run again.",
719
+ // Unreachable with --operation-id at this head (foreignRetirement admits only this operation's own receipt, resumed in its own
720
+ // mode); kept as a closed text with no state claim. "--force" with the same id would answer operation_mismatch, so it is not offered.
721
+ link_retirement_mode_mismatch: link => "This link's removal was interrupted in another mode than this revoke asks for. Repeat the revoke that started it with its options (ocx link operations --json shows each entry's linkId), or finish it with ocx link revoke --link-id " + link + " --force --yes without --operation-id.",
722
+ // Not a retirement refusal, but its way out names the link too, so it runs as printed. A replay that follows a resumed removal
723
+ // can meet an unreadable journal after that removal finished (#8416): no state claim.
724
+ operation_journal_unreadable: link => "The link operation journal (<configDir>/link/operations.json) is damaged or could not be read. Keep a copy, move it aside and repeat the revoke with the same operation id; if that answers link_not_found, the link is already gone (a resumed removal can finish before the read fails). A forced revoke runs without the journal: ocx link revoke --link-id " + link + " --force --yes, without --operation-id (it skips the Child's cleanup).",
725
+ };
726
+
727
+ /**
728
+ * Closed texts for refusals of a journalled revoke. Each claims only what holds on every path that answers the code, on a
729
+ * first and on a resumed attempt (the table in structure/remote-link.md, "Operation journal"); any other code, including ones
730
+ * a newer Home adds, keeps the generic text.
731
+ */
732
+ const REVOKE_REFUSALS: Record<string, string> = {
733
+ operation_mismatch: "This operation id was already used with other parameters. Nothing was changed; repeat it with the flags of its first attempt, or use a new operation id.",
734
+ link_operation_open: "An unfinished revoke holds this link; repeat it with its own operation id to settle it first. Nothing was changed.",
735
+ // A resumed revoke can re-own its retirement receipt before this 409 (#8416), so it claims only what holds for every path.
736
+ link_operation_in_progress: "Another link operation for this alias or link is running. This attempt did not touch the link, its key or the Child; retry when it ends.",
737
+ };
@@ -12,7 +12,7 @@ export async function runMessageCommand(argv: readonly string[], env: NodeJS.Pro
12
12
  if (remote) return (await import("./message-remote-command")).runRemoteMessageCommand(remote, env);
13
13
  const args = parseMessageArgs(argv);
14
14
  if (!args) {
15
- console.error("Usage: ocx message sessions [--host <peer>] [--json] | send (--thread <uuid> | --name <exact-name>) --stdin [--host <peer>] [--kind request|response|notification] [--in-reply-to <uuid>] [--json] | mcp --codex <absolute-cli-path> --codex-home <absolute-existing-home> [--allow-reply-read] | enable [--port <port>] | disable | status | hosts <probe|add|list|remove|abandon|allow-inbound|deny-inbound> | serve [--host <peer>]...");
15
+ console.error("Usage: ocx message sessions [--host <peer>] [--json] | send (--thread <uuid> | --name <exact-name>) --stdin [--host <peer>] [--kind request|response|notification] [--in-reply-to <uuid>] [--json] | mcp --codex <absolute-cli-path> --codex-home <absolute-existing-home> [--allow-reply-read] [--allow-resume --resume-socket <absolute-existing-unix-socket> --resume-permissions <profile-id>] | enable [--port <port>] | disable | status | hosts <probe|add|list|remove|abandon|allow-inbound|deny-inbound> | serve [--host <peer>]...");
16
16
  return 64;
17
17
  }
18
18
  const controller = new AbortController();