@bitkyc08/opencodex 2.100.1 → 2.100.3

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 (624) hide show
  1. package/README.md +1 -1
  2. package/bin/ocx.mjs +32 -18
  3. package/gui/dist/assets/{App-COo8Yopd.css → App-BGP8I0V4.css} +1 -1
  4. package/gui/dist/assets/App-Dnb6VMsP.js +59 -0
  5. package/gui/dist/assets/Tray-BV4ms9U9.js +1 -0
  6. package/gui/dist/assets/{brand-mark-nr3ziR-T.js → brand-mark-XOLJbomA.js} +1 -1
  7. package/gui/dist/assets/index-DCdXsMyZ.js +105 -0
  8. package/gui/dist/assets/index-DQtCRNAw.css +2 -0
  9. package/gui/dist/assets/{segment-thumb-features-DKCVUUTi.js → segment-thumb-features-DXSidY6D.js} +1 -1
  10. package/gui/dist/classic/assets/App-DA-scMPq.js +58 -0
  11. package/gui/dist/classic/assets/{Tray-BedmOsE7.js → Tray-BrHaVRAq.js} +1 -1
  12. package/gui/dist/classic/assets/index-BqOaGLf5.js +105 -0
  13. package/gui/dist/classic/assets/quota-summary-Dy5_wfTT.js +1 -0
  14. package/gui/dist/classic/index.html +1 -1
  15. package/gui/dist/index.html +2 -2
  16. package/native/ocx-child/Cargo.toml +9 -0
  17. package/native/ocx-child/src/cli.rs +402 -20
  18. package/native/ocx-child/src/codex_home.rs +98 -14
  19. package/native/ocx-child/src/daemon.rs +2 -1
  20. package/native/ocx-child/src/lib.rs +3 -0
  21. package/native/ocx-child/src/link_ws.rs +2598 -0
  22. package/native/ocx-child/src/link_ws_advert.rs +346 -0
  23. package/native/ocx-child/src/link_ws_frame.rs +749 -0
  24. package/native/ocx-child/src/parity.rs +5 -1
  25. package/native/ocx-child/src/platform.rs +152 -6
  26. package/native/ocx-child/src/relay.rs +150 -19
  27. package/package.json +3 -3
  28. package/src/adapters/anthropic/advisor-tool.ts +176 -0
  29. package/src/adapters/anthropic/beta-body-pairs.ts +6 -0
  30. package/src/adapters/anthropic/client-identity.ts +3 -1
  31. package/src/adapters/anthropic/passthrough.ts +9 -3
  32. package/src/adapters/anthropic.ts +31 -14
  33. package/src/adapters/client-fingerprint.ts +6 -4
  34. package/src/adapters/cursor/discovery.ts +17 -0
  35. package/src/adapters/cursor/native-exec-desktop.ts +2 -1
  36. package/src/adapters/cursor/native-exec-shell.ts +2 -1
  37. package/src/adapters/cursor/native-exec.ts +3 -2
  38. package/src/adapters/cursor/protobuf-request.ts +8 -8
  39. package/src/adapters/cursor/tool-guidance.ts +3 -3
  40. package/src/adapters/cursor/tool-wording.ts +10 -1
  41. package/src/adapters/cursor.ts +7 -6
  42. package/src/adapters/devin/cloud-direct/tool-schema.ts +20 -2
  43. package/src/adapters/google-antigravity-wire.ts +15 -6
  44. package/src/adapters/google-truncation.ts +4 -2
  45. package/src/adapters/google-wire-compiler.ts +2 -2
  46. package/src/adapters/google.ts +17 -4
  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/openai-chat/tool-schema.ts +9 -0
  54. package/src/adapters/openai-responses/tool-schema.ts +18 -4
  55. package/src/adapters/run-turn-queue.ts +139 -5
  56. package/src/adapters/upstream-http-error.ts +4 -2
  57. package/src/adapters/zed.ts +3 -0
  58. package/src/advisor/consult.ts +15 -4
  59. package/src/advisor/context.ts +12 -3
  60. package/src/advisor/runtime.ts +35 -5
  61. package/src/advisor/settings.ts +8 -0
  62. package/src/advisor/synthetic-tool.ts +21 -8
  63. package/src/bridge/response-json.ts +11 -2
  64. package/src/bridge/sse.ts +51 -9
  65. package/src/claude/auth-detect.ts +21 -33
  66. package/src/claude/chat-tool-dispatch.ts +233 -0
  67. package/src/claude/desktop-3p.ts +11 -5
  68. package/src/claude/desktop-gateway-state.ts +2 -0
  69. package/src/claude/desktop-remote-store-artifact.ts +14 -3
  70. package/src/claude/desktop-remote-store.ts +24 -4
  71. package/src/claude/inbound-content-options.ts +31 -16
  72. package/src/claude/inbound-tool-loading.ts +42 -17
  73. package/src/claude/outbound.ts +13 -3
  74. package/src/cli/account-api.ts +23 -1
  75. package/src/cli/account-auth.ts +54 -21
  76. package/src/cli/account-extended.ts +60 -6
  77. package/src/cli/account-key-quota.ts +56 -7
  78. package/src/cli/account.ts +5 -3
  79. package/src/cli/advisor.ts +7 -4
  80. package/src/cli/alias.ts +38 -1
  81. package/src/cli/capabilities-access-remote.ts +137 -2
  82. package/src/cli/capabilities-accounts.ts +3 -3
  83. package/src/cli/capabilities-agents-routing.ts +17 -10
  84. package/src/cli/capabilities-base.ts +43 -18
  85. package/src/cli/capabilities-integrations.ts +2 -2
  86. package/src/cli/capabilities-provider-models.ts +18 -2
  87. package/src/cli/capabilities-route-to.ts +43 -0
  88. package/src/cli/capabilities.ts +2 -0
  89. package/src/cli/capability-contracts.ts +1 -1
  90. package/src/cli/claude-desktop.ts +30 -11
  91. package/src/cli/claude.ts +36 -17
  92. package/src/cli/codex-launcher.ts +3 -1
  93. package/src/cli/codex-shim-autorestore.ts +5 -42
  94. package/src/cli/config-command.ts +38 -2
  95. package/src/cli/config-root-startup.ts +34 -0
  96. package/src/cli/connect.ts +124 -19
  97. package/src/cli/desktop-runtime-guidance.ts +1 -1
  98. package/src/cli/disconnect-runtime.ts +168 -0
  99. package/src/cli/dispatch.ts +54 -12
  100. package/src/cli/export-command.ts +1 -1
  101. package/src/cli/gui-pair-client.ts +29 -5
  102. package/src/cli/gui.ts +10 -5
  103. package/src/cli/help-catalog.ts +11 -0
  104. package/src/cli/help.ts +5 -4
  105. package/src/cli/hub.ts +18 -1
  106. package/src/cli/index.ts +83 -92
  107. package/src/cli/inspect.ts +11 -2
  108. package/src/cli/integrations.ts +26 -1
  109. package/src/cli/link-capture.ts +64 -0
  110. package/src/cli/link-child-ops.ts +314 -0
  111. package/src/cli/link-cleanup.ts +8 -5
  112. package/src/cli/link-diagnostics.ts +67 -0
  113. package/src/cli/link-enrollment.ts +158 -12
  114. package/src/cli/link-operations.ts +52 -0
  115. package/src/cli/link-recover.ts +152 -0
  116. package/src/cli/link-routes.ts +87 -0
  117. package/src/cli/link-status-child.ts +137 -0
  118. package/src/cli/link-status-traffic.ts +34 -0
  119. package/src/cli/link.ts +327 -37
  120. package/src/cli/message-command.ts +1 -1
  121. package/src/cli/message-mcp-command.ts +23 -10
  122. package/src/cli/models-runtime.ts +3 -3
  123. package/src/cli/opencode.ts +3 -1
  124. package/src/cli/pi-sync.ts +35 -0
  125. package/src/cli/preflight-exemptions.ts +46 -0
  126. package/src/cli/registry.ts +29 -12
  127. package/src/cli/restart-failure.ts +5 -2
  128. package/src/cli/root.ts +5 -1
  129. package/src/cli/route-to.ts +172 -0
  130. package/src/cli/runtime-api.ts +5 -8
  131. package/src/cli/status.ts +3 -1
  132. package/src/cli/stop-approval.ts +66 -19
  133. package/src/cli/stop-report.ts +23 -0
  134. package/src/cli/stop-windows-checked.ts +304 -0
  135. package/src/cli/sync-command.ts +70 -13
  136. package/src/cli/sync-fanout.ts +81 -99
  137. package/src/cli/sync-flags.ts +40 -3
  138. package/src/cli/sync-link-status.ts +18 -2
  139. package/src/cli/sync-update-guard.ts +7 -2
  140. package/src/cli/system-restart-client.ts +3 -2
  141. package/src/cli/uninstall-plan.ts +77 -5
  142. package/src/cli/uninstall-stop.ts +152 -0
  143. package/src/cli/v2-input.ts +10 -6
  144. package/src/cli/v2-local-output.ts +3 -2
  145. package/src/cli/v2-runtime.ts +10 -3
  146. package/src/cli/v2.ts +22 -7
  147. package/src/client/connect.ts +321 -34
  148. package/src/client/link-home-features.ts +27 -0
  149. package/src/client/link-home.ts +92 -4
  150. package/src/client/link-ingress.ts +21 -3
  151. package/src/client/link-join.ts +12 -2
  152. package/src/client/link-parity-reporter.ts +60 -6
  153. package/src/client/link-readiness.ts +16 -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-status.ts +76 -0
  161. package/src/client/link-tunnel.ts +56 -5
  162. package/src/client/link-websocket-limits.ts +89 -0
  163. package/src/client/link-websocket.ts +586 -0
  164. package/src/client/link-ws-advertisement.ts +100 -0
  165. package/src/client/link-ws-framer.ts +241 -0
  166. package/src/client/link-ws-transport.ts +177 -0
  167. package/src/client/machine-api.ts +13 -2
  168. package/src/client/machine-listener.ts +48 -7
  169. package/src/client/route-intent-apply.ts +293 -0
  170. package/src/client/route-intent-file-originals.ts +97 -0
  171. package/src/client/route-intent-native-originals.ts +201 -0
  172. package/src/client/route-intent-watch.ts +141 -0
  173. package/src/client/runtime-restart.ts +127 -5
  174. package/src/client/runtime.ts +61 -15
  175. package/src/client/state.ts +30 -0
  176. package/src/client/sync-expectation.ts +36 -2
  177. package/src/client/sync-runtime.ts +7 -0
  178. package/src/clients/config-export/alias-selectors.ts +63 -40
  179. package/src/clients/config-export/contracts.ts +2 -0
  180. package/src/clients/config-export/nested-selectors.ts +42 -0
  181. package/src/clients/config-export.ts +36 -4
  182. package/src/codex/account-resume-health.ts +41 -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/login-flow.ts +6 -0
  187. package/src/codex/auth-api/routes.ts +35 -2
  188. package/src/codex/auth-collision.ts +23 -22
  189. package/src/codex/auth-context.ts +21 -6
  190. package/src/codex/catalog/gather-capture.ts +10 -2
  191. package/src/codex/catalog/parsing.ts +7 -3
  192. package/src/codex/catalog/provider-models.ts +67 -23
  193. package/src/codex/catalog/retained-sync.ts +2 -1
  194. package/src/codex/catalog/routed-gather.ts +1 -1
  195. package/src/codex/catalog-auto-refresh.ts +11 -0
  196. package/src/codex/cli-update-job.ts +35 -13
  197. package/src/codex/convergence-types.ts +2 -0
  198. package/src/codex/convergence.ts +2 -2
  199. package/src/codex/desktop-compatibility/native-identity.ts +4 -8
  200. package/src/codex/features.ts +2 -2
  201. package/src/codex/history-provider.ts +31 -0
  202. package/src/codex/inject/multi-agent-v2.ts +9 -3
  203. package/src/codex/inject/paginated-openai-compat.ts +54 -1
  204. package/src/codex/inject/plan.ts +20 -2
  205. package/src/codex/inject.ts +2 -0
  206. package/src/codex/journal-config-restore.ts +217 -0
  207. package/src/codex/journal.ts +75 -6
  208. package/src/codex/main-account.ts +23 -30
  209. package/src/codex/native-main-auth-file.ts +104 -0
  210. package/src/codex/native-profile-manager.ts +4 -3
  211. package/src/codex/native-profile-store.ts +3 -61
  212. package/src/codex/orca-import.ts +10 -1
  213. package/src/codex/quota-history.ts +13 -0
  214. package/src/codex/quota-window-conflict.ts +103 -0
  215. package/src/codex/quota.ts +134 -7
  216. package/src/codex/subagent-model-fallback.ts +3 -1
  217. package/src/codex/websocket-activity.ts +171 -16
  218. package/src/codex/websocket-registry.ts +11 -4
  219. package/src/combos/cooldown-store.ts +228 -0
  220. package/src/combos/failover.ts +760 -35
  221. package/src/config/dashboard-trusted-proxy.ts +83 -0
  222. package/src/config/diagnostics.ts +28 -0
  223. package/src/config/feature-flags.ts +9 -0
  224. package/src/config/live-reconcile.ts +10 -1
  225. package/src/config/load-degrade.ts +12 -1
  226. package/src/config/multi-agent-surface.ts +28 -5
  227. package/src/config/pending-teardown.ts +60 -3
  228. package/src/config/process-state.ts +175 -4
  229. package/src/config/provider-validation.ts +4 -4
  230. package/src/config/salvage.ts +1 -0
  231. package/src/config/schema/config-schema.ts +12 -3
  232. package/src/config/schema/leaf-validators.ts +43 -14
  233. package/src/config/windows-process-command-line.ts +107 -0
  234. package/src/generated/compatibility-version.json +1077 -429
  235. package/src/generated/model-metadata.ts +1 -1
  236. package/src/images/loop.ts +3 -0
  237. package/src/integrations/model-name-guard.ts +25 -0
  238. package/src/integrations/route-intent-catalog.ts +26 -0
  239. package/src/integrations/route-intent-connected.ts +262 -0
  240. package/src/integrations/route-intent-contract.ts +55 -0
  241. package/src/integrations/route-intent-disconnect.ts +109 -0
  242. package/src/integrations/route-intent-initial.ts +64 -0
  243. package/src/integrations/route-intent-state.ts +117 -0
  244. package/src/integrations/route-intent-tick.ts +65 -0
  245. package/src/integrations/route-intent.ts +212 -0
  246. package/src/integrations/writer.ts +44 -11
  247. package/src/lib/catalog-etag.ts +10 -0
  248. package/src/lib/client-error-body.ts +15 -0
  249. package/src/lib/client-retry-after.ts +29 -0
  250. package/src/lib/config-ownership.ts +13 -0
  251. package/src/lib/context-overflow-verdict.ts +266 -9
  252. package/src/lib/desktop-gui-origin.ts +28 -0
  253. package/src/lib/errors.ts +1 -1
  254. package/src/lib/failure-detail.ts +72 -3
  255. package/src/lib/gui-pair-capability.ts +2 -1
  256. package/src/lib/hard-refusal.ts +259 -0
  257. package/src/lib/messages-error-body.ts +4 -1
  258. package/src/lib/outbound-credential-registry.ts +362 -4
  259. package/src/lib/paced-stream.ts +34 -0
  260. package/src/lib/passive-key-fetch-proof.ts +30 -0
  261. package/src/lib/passive-read.ts +5 -0
  262. package/src/lib/process-control.ts +76 -12
  263. package/src/lib/redact.ts +84 -8
  264. package/src/lib/state-store-registrations.ts +11 -0
  265. package/src/lib/state-store-sweeper.ts +4 -0
  266. package/src/lib/supervisor-markers.ts +18 -0
  267. package/src/lib/terminal-safe-text.ts +58 -0
  268. package/src/lib/translator-budget.ts +3 -2
  269. package/src/lib/upstream-retry.ts +14 -4
  270. package/src/link/alias-lock.ts +119 -0
  271. package/src/link/child-activity.ts +83 -0
  272. package/src/link/child-binary-cache-fill.d.mts +50 -0
  273. package/src/link/child-binary-cache-fill.mjs +494 -0
  274. package/src/link/child-binary-cache-start.ts +73 -0
  275. package/src/link/child-binary-source.ts +12 -5
  276. package/src/link/child-catalog-freshness.ts +149 -0
  277. package/src/link/child-gated-ocx.ts +135 -0
  278. package/src/link/child-observations.ts +206 -0
  279. package/src/link/child-observe.ts +121 -0
  280. package/src/link/child-ops-engine.ts +230 -0
  281. package/src/link/child-ops-host.ts +138 -0
  282. package/src/link/child-ops-runners.ts +319 -0
  283. package/src/link/child-ops-scheduler.ts +207 -0
  284. package/src/link/child-ops-types.ts +89 -0
  285. package/src/link/child-parity.ts +23 -4
  286. package/src/link/child-policy.ts +93 -0
  287. package/src/link/child-update-contract.ts +174 -0
  288. package/src/link/codex-settings.ts +1 -1
  289. package/src/link/compatibility.ts +18 -1
  290. package/src/link/diagnostics-read.ts +163 -0
  291. package/src/link/diagnostics.ts +20 -7
  292. package/src/link/explicit-route.ts +209 -0
  293. package/src/link/link-recover.ts +113 -0
  294. package/src/link/management-routes.ts +3 -1
  295. package/src/link/operation-recovery-slot.ts +44 -0
  296. package/src/link/operations-journal.ts +408 -0
  297. package/src/link/paths.ts +5 -0
  298. package/src/link/peer-report.ts +1 -1
  299. package/src/link/relay-auth.ts +14 -0
  300. package/src/link/remote-plant.ts +152 -14
  301. package/src/link/remote-platform.ts +21 -10
  302. package/src/link/remote-probe.ts +11 -3
  303. package/src/link/remote-windows.ts +88 -12
  304. package/src/link/request-compression.ts +30 -0
  305. package/src/link/residual-recovery.ts +54 -0
  306. package/src/link/retirement.ts +128 -0
  307. package/src/link/route-intent-watch.ts +41 -0
  308. package/src/link/route-intent.ts +209 -0
  309. package/src/link/route-proof.ts +82 -0
  310. package/src/link/route-rounds.ts +579 -0
  311. package/src/link/route-select.ts +95 -0
  312. package/src/link/route-trust.ts +96 -0
  313. package/src/link/ssh-argv.ts +285 -43
  314. package/src/link/ssh-capture-redact.ts +253 -0
  315. package/src/link/ssh-capture.ts +497 -0
  316. package/src/link/ssh-runner.ts +141 -14
  317. package/src/link/status-projection.ts +160 -0
  318. package/src/link/store.ts +54 -1
  319. package/src/link/supervisor.ts +543 -55
  320. package/src/link/sync-fanout-classify.ts +114 -0
  321. package/src/link/sync-then-restart.ts +65 -0
  322. package/src/link/tombstones.ts +209 -0
  323. package/src/link/traffic.ts +178 -0
  324. package/src/link/tunnel-state.ts +10 -4
  325. package/src/link/ws-activity-holds.ts +474 -0
  326. package/src/local-credentials/publication-fence.ts +20 -1
  327. package/src/messaging/mcp-queue-rpc.ts +3 -2
  328. package/src/messaging/mcp-queue-server.ts +21 -1
  329. package/src/messaging/mcp-reply-tools.ts +24 -9
  330. package/src/messaging/mcp-reply-wait.ts +70 -0
  331. package/src/messaging/mcp-resume-tools.ts +25 -0
  332. package/src/messaging/remote-enrollment.ts +3 -3
  333. package/src/messaging/remote-tunnels.ts +2 -2
  334. package/src/messaging/resume-permissions.ts +27 -0
  335. package/src/messaging/rpc.ts +46 -2
  336. package/src/oauth/account-resume-health.ts +60 -0
  337. package/src/oauth/anthropic-continuity.ts +23 -7
  338. package/src/oauth/anthropic-routing.ts +5 -2
  339. package/src/oauth/anthropic.ts +22 -2
  340. package/src/oauth/claude-keychain-read.ts +78 -68
  341. package/src/oauth/index.ts +25 -6
  342. package/src/oauth/local-token-detect.ts +8 -29
  343. package/src/oauth/login-cli-errors.ts +5 -1
  344. package/src/oauth/login-cli.ts +33 -18
  345. package/src/oauth/login-flow-state.ts +26 -3
  346. package/src/oauth/meta-muse.ts +1 -1
  347. package/src/oauth/store.ts +51 -1
  348. package/src/oauth/xai.ts +248 -14
  349. package/src/protocols/contract.ts +4 -0
  350. package/src/protocols/encoders/messages.ts +1 -0
  351. package/src/providers/alias-template.ts +48 -0
  352. package/src/providers/anthropic-billing-ownership.ts +2 -0
  353. package/src/providers/anthropic-output-caps.ts +46 -0
  354. package/src/providers/anthropic-reset-grant-ledger.ts +9 -3
  355. package/src/providers/antigravity-effort-families.ts +11 -3
  356. package/src/providers/antigravity-models.ts +32 -9
  357. package/src/providers/antigravity-wire-snapshot.ts +3 -2
  358. package/src/providers/api-key-pause-state.ts +23 -0
  359. package/src/providers/api-key-pause.ts +71 -10
  360. package/src/providers/api-key-resolve.ts +49 -7
  361. package/src/providers/api-key-response-ownership.ts +2 -0
  362. package/src/providers/api-key-selection-capture.ts +3 -1
  363. package/src/providers/api-key-selection.ts +54 -11
  364. package/src/providers/api-keys.ts +24 -7
  365. package/src/providers/cache-affinity-identity.ts +73 -0
  366. package/src/providers/cache-affinity.ts +256 -0
  367. package/src/providers/claude-cli-usage-state.ts +11 -6
  368. package/src/providers/claude-cli-usage.ts +27 -9
  369. package/src/providers/codex-capacity.ts +11 -2
  370. package/src/providers/default-aliases.ts +98 -20
  371. package/src/providers/google-vertex-model-discovery.ts +510 -0
  372. package/src/providers/key-failover.ts +136 -14
  373. package/src/providers/key-store.ts +3 -3
  374. package/src/providers/kiro-models.ts +3 -5
  375. package/src/providers/label.ts +31 -5
  376. package/src/providers/mistral-transport.ts +17 -4
  377. package/src/providers/model-discovery-config.ts +31 -0
  378. package/src/providers/model-discovery-diagnostic.ts +34 -3
  379. package/src/providers/model-discovery.ts +43 -7
  380. package/src/providers/model-rename-fields.ts +5 -0
  381. package/src/providers/muse-key-quota.ts +14 -6
  382. package/src/providers/new-model-policy-runtime.ts +17 -4
  383. package/src/providers/new-model-policy.ts +30 -4
  384. package/src/providers/openai-sidecar.ts +15 -2
  385. package/src/providers/passive-key-observation.ts +252 -0
  386. package/src/providers/provider-id-rewrite.ts +3 -0
  387. package/src/providers/quota/account-cache.ts +53 -34
  388. package/src/providers/quota/anthropic-cooldown-recovery-worker.ts +121 -0
  389. package/src/providers/quota/anthropic-usage-windows.ts +19 -9
  390. package/src/providers/quota/passive-key-limits.ts +272 -0
  391. package/src/providers/quota/passive-wire-model.ts +126 -0
  392. package/src/providers/quota/report-cache.ts +112 -5
  393. package/src/providers/quota/vendor-probes-key.ts +73 -0
  394. package/src/providers/quota/vendor-probes-oauth.ts +57 -3
  395. package/src/providers/quota-key-accounts.ts +22 -10
  396. package/src/providers/quota-mistral-budget.ts +18 -0
  397. package/src/providers/quota-types.ts +43 -0
  398. package/src/providers/quota.ts +31 -32
  399. package/src/providers/reasoning-metadata.ts +1051 -12
  400. package/src/providers/registry/entries-core.ts +34 -16
  401. package/src/providers/registry/entries-extended.ts +32 -0
  402. package/src/providers/registry/model-seeds.ts +35 -0
  403. package/src/providers/resolved-model-policy.ts +7 -0
  404. package/src/providers/routed-config.ts +8 -3
  405. package/src/providers/xai-transport.ts +3 -0
  406. package/src/quota/reset-observer.ts +4 -2
  407. package/src/quota/reset-seen-store.ts +9 -0
  408. package/src/quota/window-mapping.ts +1 -0
  409. package/src/quota-pool/assemble.ts +4 -1
  410. package/src/remote/features.ts +17 -0
  411. package/src/responses/anthropic-progress.ts +10 -4
  412. package/src/responses/citation-markers.ts +231 -0
  413. package/src/responses/hosted-tool-policy.ts +56 -12
  414. package/src/responses/spill-store.ts +5 -1
  415. package/src/responses/state/replay-input.ts +50 -0
  416. package/src/responses/state/replay-owner.ts +24 -0
  417. package/src/responses/state/snapshot-codec.ts +9 -0
  418. package/src/responses/state/spill-queue.ts +1 -0
  419. package/src/responses/state.ts +42 -60
  420. package/src/router.ts +4 -2
  421. package/src/routing/home-route-capture.ts +123 -0
  422. package/src/routing/home-route-intent.ts +200 -0
  423. package/src/routing/route-intent-state.ts +178 -0
  424. package/src/routing/route-to-live-settings.ts +35 -0
  425. package/src/routing/route-to-local.ts +145 -0
  426. package/src/routing/route-to-status.ts +94 -0
  427. package/src/routing/route-to-sync-child.ts +32 -0
  428. package/src/server/adapter-resolve.ts +21 -1
  429. package/src/server/admitted-http-turn.ts +3 -0
  430. package/src/server/auth-cors.ts +109 -8
  431. package/src/server/bare-upstream-error.ts +220 -0
  432. package/src/server/catalog-download.ts +3 -5
  433. package/src/server/chat-native.ts +25 -7
  434. package/src/server/claude-messages.ts +8 -5
  435. package/src/server/codex-model-list.ts +2 -1
  436. package/src/server/configured-credentials.ts +37 -5
  437. package/src/server/gui-desktop-authorization.ts +36 -0
  438. package/src/server/gui-pair-delivery.ts +6 -3
  439. package/src/server/gui-session.ts +10 -1
  440. package/src/server/images.ts +41 -13
  441. package/src/server/inbound-body-admission.ts +17 -4
  442. package/src/server/index/link-listener.ts +203 -11
  443. package/src/server/index/link-management.ts +15 -1
  444. package/src/server/index/link-relay-sessions.ts +128 -8
  445. package/src/server/index/link-websocket-limits.ts +136 -0
  446. package/src/server/index/link-websocket.ts +692 -0
  447. package/src/server/index/optional-listeners.ts +115 -7
  448. package/src/server/index/route-intent-watch.ts +47 -0
  449. package/src/server/index/serve-contract.ts +86 -0
  450. package/src/server/index/serve-options.ts +35 -86
  451. package/src/server/index/startup-warnings.ts +8 -2
  452. package/src/server/index/websocket-handler.ts +26 -4
  453. package/src/server/index.ts +12 -2
  454. package/src/server/inference/client-encoder-delivery.ts +2 -0
  455. package/src/server/inspection-tee.ts +39 -2
  456. package/src/server/lifecycle.ts +2 -0
  457. package/src/server/link-turn.ts +137 -0
  458. package/src/server/management/advisor-routes.ts +10 -2
  459. package/src/server/management/agent-settings-routes.ts +50 -16
  460. package/src/server/management/anthropic-reset-grant-routes.ts +1 -1
  461. package/src/server/management/config-routes.ts +7 -1
  462. package/src/server/management/context.ts +9 -2
  463. package/src/server/management/desktop-authorization.ts +41 -0
  464. package/src/server/management/desktop-compatibility-routes.ts +9 -8
  465. package/src/server/management/desktop-compatibility-runtime-routes.ts +3 -2
  466. package/src/server/management/desktop-compatibility-settings-routes.ts +5 -3
  467. package/src/server/management/home-integration-decision.ts +89 -0
  468. package/src/server/management/integration-routes.ts +208 -81
  469. package/src/server/management/link-child-ops-routes.ts +218 -0
  470. package/src/server/management/link-child-preflight.ts +31 -0
  471. package/src/server/management/link-diagnostics-route.ts +29 -0
  472. package/src/server/management/link-enrollment.ts +199 -47
  473. package/src/server/management/link-operation.ts +609 -0
  474. package/src/server/management/link-recover-route.ts +103 -0
  475. package/src/server/management/link-route-edit.ts +173 -0
  476. package/src/server/management/link-route-request.ts +62 -0
  477. package/src/server/management/link-route-state.ts +92 -6
  478. package/src/server/management/link-routes.ts +563 -51
  479. package/src/server/management/link-traffic-status.ts +13 -0
  480. package/src/server/management/model-routes.ts +122 -36
  481. package/src/server/management/model-rows.ts +2 -1
  482. package/src/server/management/native-integration-routes.ts +176 -70
  483. package/src/server/management/oauth-account-routes.ts +69 -17
  484. package/src/server/management/protocol-routes.ts +7 -0
  485. package/src/server/management/provider-completion-test.ts +4 -4
  486. package/src/server/management/provider-overwrite-carry.ts +39 -3
  487. package/src/server/management/provider-routes.ts +80 -72
  488. package/src/server/management/provider-routing-quota.ts +45 -0
  489. package/src/server/management/route-registry.ts +25 -3
  490. package/src/server/management/route-to-routes.ts +257 -0
  491. package/src/server/management/system-restart.ts +4 -2
  492. package/src/server/management/usage-aggregate-cache.ts +101 -66
  493. package/src/server/management-api.ts +17 -3
  494. package/src/server/management-auth.ts +13 -1
  495. package/src/server/messages-native-preflight.ts +27 -4
  496. package/src/server/messages-native.ts +22 -5
  497. package/src/server/persistent-gui-session.ts +6 -3
  498. package/src/server/proxy-liveness.ts +33 -6
  499. package/src/server/relay-eager.ts +36 -12
  500. package/src/server/relay.ts +183 -116
  501. package/src/server/request-body-facts.ts +48 -0
  502. package/src/server/request-decompress.ts +65 -2
  503. package/src/server/request-log-account-rotation.ts +6 -0
  504. package/src/server/request-log-attempt-usage.ts +69 -0
  505. package/src/server/request-log-cache-affinity.ts +60 -0
  506. package/src/server/request-log-conversation.ts +45 -2
  507. package/src/server/request-log-failure-detail.ts +59 -1
  508. package/src/server/request-log-terminal-status.ts +210 -24
  509. package/src/server/request-log.ts +71 -79
  510. package/src/server/responses/adapter-continuation.ts +2 -1
  511. package/src/server/responses/adapter-delivery.ts +2 -0
  512. package/src/server/responses/adapter-dispatch.ts +40 -51
  513. package/src/server/responses/advisor-plan-slot.ts +33 -1
  514. package/src/server/responses/advisor-question.ts +21 -0
  515. package/src/server/responses/advisor-slot.ts +10 -3
  516. package/src/server/responses/bare-namespace-aliases.ts +18 -0
  517. package/src/server/responses/buffered-sse-json.ts +9 -3
  518. package/src/server/responses/code-mode-collab-surface.ts +11 -0
  519. package/src/server/responses/codex-tool-catalog.ts +156 -0
  520. package/src/server/responses/combo-required-tool-fulfillments.ts +4 -2
  521. package/src/server/responses/combo-stream-preflight.ts +701 -81
  522. package/src/server/responses/compact.ts +47 -12
  523. package/src/server/responses/context-overflow.ts +58 -2
  524. package/src/server/responses/core-codex-account.ts +17 -3
  525. package/src/server/responses/core-combo-failure.ts +37 -4
  526. package/src/server/responses/core-combo-native.ts +3 -1
  527. package/src/server/responses/core-combo.ts +62 -7
  528. package/src/server/responses/core-errors.ts +8 -3
  529. package/src/server/responses/core-lifetime.ts +3 -2
  530. package/src/server/responses/core-normalize.ts +3 -1
  531. package/src/server/responses/core-opaque-recovery.ts +45 -2
  532. package/src/server/responses/core-options.ts +18 -0
  533. package/src/server/responses/core.ts +2 -0
  534. package/src/server/responses/fetch-helpers.ts +15 -10
  535. package/src/server/responses/native-replay-guard.ts +57 -0
  536. package/src/server/responses/opengateway-completion-guard.ts +10 -4
  537. package/src/server/responses/outbound-request-body.ts +29 -0
  538. package/src/server/responses/passthrough-completion.ts +105 -8
  539. package/src/server/responses/passthrough-delivery.ts +31 -11
  540. package/src/server/responses/passthrough-dispatch.ts +99 -106
  541. package/src/server/responses/policy-fallback.ts +13 -1
  542. package/src/server/responses/request-prepare.ts +50 -6
  543. package/src/server/responses/request-transport.ts +53 -17
  544. package/src/server/responses/reset-replay.ts +104 -4
  545. package/src/server/responses/run-turn-execution.ts +58 -30
  546. package/src/server/responses/sidecar-execution.ts +14 -0
  547. package/src/server/responses/terminal-error-redaction.ts +222 -25
  548. package/src/server/responses/ws-upstream.ts +2 -2
  549. package/src/server/sse-payload-rewrite.ts +3 -2
  550. package/src/server/stop-service-route.ts +85 -0
  551. package/src/server/system-env-shell.ts +12 -1
  552. package/src/server/system-env.ts +5 -3
  553. package/src/server/windows-tcp-drop.ts +21 -4
  554. package/src/server/workflow-refusal.ts +8 -0
  555. package/src/server/ws-bridge.ts +191 -12
  556. package/src/service/cli-windows-stop.ts +189 -0
  557. package/src/service/cli.ts +41 -12
  558. package/src/service/disconnected-client-restart.ts +60 -0
  559. package/src/service/guarded-manager-target.ts +18 -1
  560. package/src/service/health.ts +99 -6
  561. package/src/service/launchd.ts +84 -31
  562. package/src/service/orchestration.ts +418 -91
  563. package/src/service/repair.ts +223 -6
  564. package/src/service/restart-proxy-stop.ts +79 -0
  565. package/src/service/service-child-ownership.ts +6 -2
  566. package/src/service/windows-checked-stop-live.ts +467 -0
  567. package/src/service/windows-checked-stop.ts +435 -0
  568. package/src/service/windows-command-line-token.ts +23 -0
  569. package/src/service/windows-guarded-manager.ts +77 -34
  570. package/src/service/windows-ops.ts +38 -56
  571. package/src/service/windows-process-evidence.ts +292 -0
  572. package/src/service/windows-process-native.ts +262 -0
  573. package/src/service/windows-service-stop.ts +321 -0
  574. package/src/service/windows-stop-binding.ts +187 -0
  575. package/src/service/windows-stop-budget.ts +123 -0
  576. package/src/service/windows-stop-confirm.ts +158 -0
  577. package/src/service/windows-stop-deadline.ts +56 -0
  578. package/src/service.ts +2 -2
  579. package/src/types/claude-tool-loading.ts +48 -0
  580. package/src/types/config.ts +47 -53
  581. package/src/types/link.ts +20 -0
  582. package/src/types/multi-agent.ts +13 -0
  583. package/src/types/provider.ts +68 -2
  584. package/src/types/request.ts +4 -0
  585. package/src/types.ts +4 -0
  586. package/src/update/guarded-runtime-ops.ts +5 -7
  587. package/src/update/index.ts +25 -10
  588. package/src/update/install-detection.mjs +3 -1
  589. package/src/update/job-pinned-start.ts +2 -0
  590. package/src/update/job-windows-restart.ts +19 -32
  591. package/src/update/job.ts +12 -5
  592. package/src/update/npm-install.d.mts +11 -0
  593. package/src/update/npm-install.mjs +44 -7
  594. package/src/update/orchestrated-entry.ts +1 -1
  595. package/src/update/orchestrated-node-driver.mjs +3 -2
  596. package/src/update/orchestrated-pnpm.d.mts +4 -0
  597. package/src/update/orchestrated-pnpm.mjs +50 -6
  598. package/src/update/orchestrated-session.d.mts +3 -1
  599. package/src/update/orchestrated-session.mjs +21 -6
  600. package/src/update/pnpm-global-install.d.mts +21 -3
  601. package/src/update/pnpm-global-install.mjs +322 -19
  602. package/src/update/pnpm-store-layout.mjs +46 -0
  603. package/src/update/sync-update-mutex.d.mts +3 -2
  604. package/src/update/sync-update-mutex.mjs +57 -8
  605. package/src/update/transactional-install.d.mts +3 -1
  606. package/src/update/transactional-install.mjs +545 -12
  607. package/src/update/windows-installer-marker.d.mts +1 -0
  608. package/src/update/windows-installer-marker.mjs +44 -0
  609. package/src/usage/expected-prices.ts +8 -0
  610. package/src/usage/filter-index.ts +326 -77
  611. package/src/usage/ledger-scanner.ts +15 -0
  612. package/src/usage/link-log-fields.ts +48 -0
  613. package/src/usage/log.ts +43 -2
  614. package/src/usage/request-body.ts +37 -0
  615. package/src/web-search/loop.ts +3 -0
  616. package/src/web-search/parse.ts +21 -2
  617. package/gui/dist/assets/App-g3Cm2xhZ.js +0 -59
  618. package/gui/dist/assets/Tray-BMDkAiXy.js +0 -1
  619. package/gui/dist/assets/index-Bziu8gTy.css +0 -2
  620. package/gui/dist/assets/index-OYzhQUNP.js +0 -94
  621. package/gui/dist/classic/assets/App-CgPBKUP-.js +0 -58
  622. package/gui/dist/classic/assets/index-BR-HhNrp.js +0 -94
  623. package/gui/dist/classic/assets/quota-summary-CXKhvSmQ.js +0 -1
  624. package/src/server/management/desktop-compatibility-authorization.ts +0 -12
@@ -0,0 +1,149 @@
1
+ import { statSync } from "node:fs";
2
+ import { dirname, join } from "node:path";
3
+ import { catalogEtag } from "../lib/catalog-etag";
4
+ import { patchChildObservation, updateChildObservations } from "./child-observations";
5
+ import { linkStorePath } from "./paths";
6
+ import { readLinkStore, type LinkStore } from "./store";
7
+
8
+ /** One completed `/v1/catalog` fetch by a Child: when, and the etag of the bytes served. Proves a fetch only. */
9
+ export interface CatalogPull { at: number; etag: string }
10
+
11
+ export interface CatalogPullRecorder {
12
+ /** From the relay's onCatalogServed; keyId resolves through links.json when linkId is null. */
13
+ record(served: { linkId: string | null; keyId: string | null; etag: string }): void;
14
+ pulled(linkId: string): CatalogPull | null;
15
+ /** Equals pulled(linkId)?.at ?? null. */
16
+ pulledAt(linkId: string): number | null;
17
+ /** Write every pull not yet persisted, ignoring the per-link interval. */
18
+ flush(): void;
19
+ }
20
+
21
+ export const CATALOG_PULL_WRITE_INTERVAL_MS = 30_000;
22
+
23
+ const errorName = (error: unknown): string => error instanceof Error ? error.name : "unknown";
24
+
25
+ /**
26
+ * A linkId absent from links.json, or a keyId no link holds, records nothing. Memory is updated synchronously; the file
27
+ * write is deferred to a microtask (no timer) and happens at most once per link per 30 s. A later pull inside that
28
+ * window stays in memory and is written by the next pull after the window or by flush(). A failed write (for example
29
+ * ConfigMutationLockError under contention) keeps the memory value and is retried on the next write attempt.
30
+ */
31
+ export function createCatalogPullRecorder(deps: {
32
+ storePath?: string; readStore?: () => LinkStore; now?: () => number; debounceMs?: number;
33
+ write?: (linkId: string, pull: CatalogPull) => void;
34
+ } = {}): CatalogPullRecorder {
35
+ const now = deps.now ?? Date.now;
36
+ const debounceMs = deps.debounceMs ?? CATALOG_PULL_WRITE_INTERVAL_MS;
37
+ const readStore = deps.readStore ?? (() => readLinkStore(deps.storePath ?? linkStorePath()));
38
+ const write = deps.write ?? ((linkId: string, pull: CatalogPull) => {
39
+ updateChildObservations(file => patchChildObservation(file, linkId, { catalogPulledAt: pull.at, catalogPulledEtag: pull.etag }, new Date(pull.at)),
40
+ deps.storePath ? { storePath: deps.storePath, path: join(dirname(deps.storePath), "child-observations.json") } : {});
41
+ });
42
+ const pulls = new Map<string, CatalogPull>();
43
+ const lastWrite = new Map<string, number>();
44
+ const dirty = new Set<string>();
45
+ let scheduled = false;
46
+ const writeOne = (linkId: string): void => {
47
+ const pull = pulls.get(linkId);
48
+ if (!pull) { dirty.delete(linkId); return; }
49
+ try {
50
+ write(linkId, pull);
51
+ dirty.delete(linkId);
52
+ lastWrite.set(linkId, now());
53
+ } catch (error) {
54
+ console.warn(`[link] catalog pull write failed linkId=${linkId} error=${errorName(error)}`);
55
+ }
56
+ };
57
+ const writeDue = (): void => {
58
+ scheduled = false;
59
+ for (const linkId of [...dirty]) {
60
+ const last = lastWrite.get(linkId);
61
+ if (last === undefined || now() - last >= debounceMs) writeOne(linkId);
62
+ }
63
+ };
64
+ return {
65
+ record(served) {
66
+ let store: LinkStore;
67
+ try { store = readStore(); } catch { return; }
68
+ const link = served.linkId !== null
69
+ ? store.links.find(candidate => candidate.id === served.linkId)
70
+ : served.keyId !== null ? store.links.find(candidate => candidate.apiKeyId === served.keyId) : undefined;
71
+ if (!link) return;
72
+ pulls.set(link.id, { at: now(), etag: served.etag });
73
+ dirty.add(link.id);
74
+ if (!scheduled) { scheduled = true; queueMicrotask(writeDue); }
75
+ },
76
+ pulled: linkId => pulls.get(linkId) ?? null,
77
+ pulledAt: linkId => pulls.get(linkId)?.at ?? null,
78
+ flush() { for (const linkId of [...dirty]) writeOne(linkId); },
79
+ };
80
+ }
81
+
82
+ /** The Home catalog's identity. changedAt is display only: no verdict compares times. */
83
+ export interface CatalogRevision { etag: string; changedAt: number }
84
+ export interface CatalogRevisionMonitor { current(): CatalogRevision | null }
85
+
86
+ /**
87
+ * Checked on each read, never on a timer: stat the catalog file, hash only when its size or mtime changed, persist
88
+ * `homeCatalog` only when the etag moved. changedAt = min(now, mtimeMs). A persist failure (lock contention) keeps the
89
+ * revision in memory and is retried on the next read, so a status read never fails on it. An unreadable file is null.
90
+ */
91
+ export function createCatalogRevisionMonitor(deps: {
92
+ catalogPath: () => string; read: (path: string) => string | null; load: () => CatalogRevision | null;
93
+ persist: (revision: CatalogRevision) => void; now?: () => number;
94
+ stat?: (path: string) => { size: number; mtimeMs: number };
95
+ }): CatalogRevisionMonitor {
96
+ const now = deps.now ?? Date.now;
97
+ const stat = deps.stat ?? ((path: string) => statSync(path));
98
+ let cache: { path: string; size: number; mtimeMs: number; revision: CatalogRevision | null } | null = null;
99
+ let known: CatalogRevision | null | undefined;
100
+ let pending: CatalogRevision | null = null;
101
+ const persistPending = (): void => {
102
+ if (!pending) return;
103
+ try {
104
+ deps.persist(pending);
105
+ pending = null;
106
+ } catch (error) {
107
+ console.warn(`[link] catalog revision save deferred error=${errorName(error)}`);
108
+ }
109
+ };
110
+ return {
111
+ current() {
112
+ let path: string;
113
+ let info: { size: number; mtimeMs: number };
114
+ try {
115
+ path = deps.catalogPath();
116
+ info = stat(path);
117
+ } catch { cache = null; return null; }
118
+ if (cache && cache.path === path && cache.size === info.size && cache.mtimeMs === info.mtimeMs) {
119
+ persistPending();
120
+ return cache.revision;
121
+ }
122
+ let body: string | null;
123
+ try { body = deps.read(path); } catch { body = null; }
124
+ if (body === null) { cache = { path, size: info.size, mtimeMs: info.mtimeMs, revision: null }; return null; }
125
+ const etag = catalogEtag(body);
126
+ if (known === undefined) {
127
+ try { known = deps.load(); } catch { known = null; }
128
+ }
129
+ let revision: CatalogRevision;
130
+ if (known && known.etag === etag) revision = known;
131
+ else {
132
+ revision = { etag, changedAt: Math.min(now(), Math.floor(info.mtimeMs)) };
133
+ known = revision;
134
+ pending = revision;
135
+ }
136
+ cache = { path, size: info.size, mtimeMs: info.mtimeMs, revision };
137
+ persistPending();
138
+ return revision;
139
+ },
140
+ };
141
+ }
142
+
143
+ export type CatalogState = "current" | "behind" | "unknown";
144
+
145
+ /** Etag equality, never time order. syncedEtag is 030's catalogSyncedEtag (a Home-run sync that synced). */
146
+ export function catalogVerdict(pulledEtag: string | null, syncedEtag: string | null, revision: CatalogRevision | null): CatalogState {
147
+ if (revision === null || (pulledEtag === null && syncedEtag === null)) return "unknown";
148
+ return pulledEtag === revision.etag || syncedEtag === revision.etag ? "current" : "behind";
149
+ }
@@ -0,0 +1,135 @@
1
+ import { LinkSshArgumentError, remoteGatedOcxArgv } from "./ssh-argv";
2
+ import { parseStrictSemver } from "../lib/strict-semver";
3
+ import { classifyChildUpdatePlan, mapUpdateApplyExit, parseChildUpdatePlan, PLAN_TOKEN_PATTERN, type PlanClassification,
4
+ type UpdateApplyVerdict } from "./child-update-contract";
5
+
6
+ export type SshResult = { code: number; stdout: string; stderr: string };
7
+ export type GatedRefusal = "child-ocx-lacks-expect-link" | "child-ocx-lacks-orchestrated-update" | "child-ocx-version-unknown" | "child-ocx-ephemeral"
8
+ | "child-node-unavailable" | "child-gate-failed";
9
+ export type GatedFraming =
10
+ | { kind: "transport"; reason: "ssh-failed" | "child-ocx-not-found" | "child-ocx-not-contained" | "child-platform-unsupported" }
11
+ | { kind: "refused"; reason: GatedRefusal }
12
+ | { kind: "ran"; code: number; selectedVersion: string; entry: "pair" | "binary" | null; childNowMs: number | null;
13
+ launcher: "available" | "unavailable" | "exec" | null; payload: string; lastStderrLine: string | undefined }
14
+ | { kind: "invalid" };
15
+
16
+ function assertHomeVersion(version: string): void {
17
+ if (version.length > 128 || !parseStrictSemver(version)) throw new LinkSshArgumentError("invalid Home version");
18
+ }
19
+ const UPDATE_GATE = { minVersion: "2.97.0", lacksMarker: "child-ocx-lacks-orchestrated-update", acceptEphemeral: false, reportEntry: true, reportClock: false,
20
+ launcher: "none" } as const;
21
+
22
+ /**
23
+ * Never mutates an install: below 2.97.0 the gate exits 121 before update runs, and update --plan only computes.
24
+ * Not free of side effects on every Child: without a census pair (an npm/pnpm Child whose service never recorded one)
25
+ * the script execs the ocx shim, so the Node launcher's ordinary bootstrap runs first (sync-guard bookkeeping, Bun
26
+ * resolution; the Desktop handoff is disabled), exactly as for every pinned sync already sent to that Child. The probe
27
+ * prints the Child's clock so the apply deadline can be set in the Child's time, and (A4) reports whether a Node that
28
+ * could run the package launcher answers --version; it always plans through the served entry, whatever that report says.
29
+ */
30
+ export function remoteUpdatePlanArgv(homeVersion: string, platform: "posix" | "windows"): string[] {
31
+ assertHomeVersion(homeVersion);
32
+ return remoteGatedOcxArgv({ ...UPDATE_GATE, reportClock: true, launcher: "report", args: ["update", "--plan", "--json", "--version", homeVersion] }, platform);
33
+ }
34
+
35
+ /**
36
+ * The shipped builders refuse Windows apply: a dropped channel kills the orchestrating parent with the Job.
37
+ * A token starting with "-" cannot pass the Child's --expect-plan parser (orchestrated-arguments.mjs refuses a value
38
+ * that looks like a flag), so it is omitted; the apply stays pinned by --version, bounded by --not-after, serialized
39
+ * by the Child's update mutex and refused on downgrade. Only the plan-consistency check is lost for that token.
40
+ * viaLauncher (A4): the caller sets it only for a plan whose installer is npm or pnpm; the apply then runs through
41
+ * <node> <root>/bin/ocx.mjs of the served package, or exits 121 child-node-unavailable before anything runs.
42
+ */
43
+ export function remoteUpdateApplyArgv(input: { homeVersion: string; planToken: string; notAfter: number; viaLauncher: boolean },
44
+ platform: "posix" | "windows"): string[] {
45
+ if (platform === "windows") throw new LinkSshArgumentError("unsupported:windows-apply");
46
+ assertHomeVersion(input.homeVersion);
47
+ if (!PLAN_TOKEN_PATTERN.test(input.planToken)) throw new LinkSshArgumentError("invalid plan token");
48
+ if (!Number.isSafeInteger(input.notAfter) || input.notAfter <= 0) throw new LinkSshArgumentError("invalid deadline");
49
+ if (typeof input.viaLauncher !== "boolean") throw new LinkSshArgumentError("invalid launcher route");
50
+ const expectPlan = input.planToken.startsWith("-") ? [] : ["--expect-plan", input.planToken];
51
+ return remoteGatedOcxArgv({ ...UPDATE_GATE, launcher: input.viaLauncher ? "apply" : "none", args: ["update", "--yes", "--json", "--version", input.homeVersion,
52
+ ...expectPlan, "--not-after", String(input.notAfter)] }, platform);
53
+ }
54
+
55
+ const REFUSAL = /^ocx-fanout:(child-ocx-lacks-expect-link|child-ocx-lacks-orchestrated-update|child-ocx-version-unknown|child-ocx-ephemeral|child-node-unavailable)$/;
56
+ const CHILD_NOW = "ocx-fanout:child-now:";
57
+ const LAUNCHER = "ocx-fanout:launcher:";
58
+
59
+ /**
60
+ * The framing classifySyncResult applies, generalised to every gated command. A run is recognised by exactly one
61
+ * selection marker and one stdout delimiter before the exit code is read, so an exit the selected ocx itself returns
62
+ * after selection (even 121, 126, 127 or 255) is a run, never a transport failure or a gate refusal.
63
+ */
64
+ export function readGatedFraming(result: SshResult): GatedFraming {
65
+ const { code, stdout, stderr } = result;
66
+ const lines = stderr.split(/\r?\n/);
67
+ const last = stderr.trimEnd().split(/\r?\n/).at(-1);
68
+ const selected = lines.map(line => /^ocx-fanout:selected:(.+)$/.exec(line)).filter(match => match !== null);
69
+ const out = stdout.split(/\r?\n/);
70
+ const delimiters = out.flatMap((line, index) => line === "ocx-fanout:stdout-begin" ? [index] : []);
71
+ if (selected.length !== 1 || delimiters.length !== 1) {
72
+ if (code === 255) return { kind: "transport", reason: "ssh-failed" };
73
+ if (code === 127) return { kind: "transport", reason: "child-ocx-not-found" };
74
+ if (code === 126) return { kind: "transport", reason: "child-ocx-not-contained" };
75
+ if (code === 125) return { kind: "transport", reason: "child-platform-unsupported" };
76
+ if (code === 121) return { kind: "refused", reason: (REFUSAL.exec(last ?? "")?.[1] ?? "child-gate-failed") as GatedRefusal };
77
+ return { kind: "invalid" };
78
+ }
79
+ if (!parseStrictSemver(selected[0]![1]!)) return { kind: "invalid" };
80
+ const entries = lines.filter(line => /^ocx-fanout:entry:(pair|binary)$/.test(line));
81
+ if (entries.length > 1) return { kind: "invalid" };
82
+ // Capture any value and validate it afterwards, so a malformed clock makes the framing invalid instead of absent.
83
+ const clocks = lines.filter(line => line.startsWith(CHILD_NOW)).map(line => line.slice(CHILD_NOW.length));
84
+ if (clocks.length > 1 || (clocks.length === 1 && (!/^[0-9]{10,16}$/.test(clocks[0]!) || !Number.isSafeInteger(Number(clocks[0]))))) return { kind: "invalid" };
85
+ // A4: at most one launcher line, from a closed set; anything else breaks the framing like a malformed clock does.
86
+ const launchers = lines.filter(line => line.startsWith(LAUNCHER)).map(line => line.slice(LAUNCHER.length));
87
+ if (launchers.length > 1 || (launchers.length === 1 && !/^(available|unavailable|exec)$/.test(launchers[0]!))) return { kind: "invalid" };
88
+ return { kind: "ran", code, selectedVersion: selected[0]![1]!, entry: entries.length ? (entries[0]!.slice("ocx-fanout:entry:".length) as "pair" | "binary") : null,
89
+ childNowMs: clocks.length ? Number(clocks[0]) : null, launcher: launchers.length ? launchers[0] as "available" | "unavailable" | "exec" : null,
90
+ payload: out.slice(delimiters[0]! + 1).join("\n").trim(), lastStderrLine: last };
91
+ }
92
+
93
+ export type PlanProbeVerdict =
94
+ | { kind: "plan"; selectedVersion: string; classification: PlanClassification; childNowMs: number | null }
95
+ | { kind: "legacy"; reason: "child-ocx-lacks-orchestrated-update" | "child-ocx-version-unknown" }
96
+ | { kind: "ephemeral" }
97
+ | { kind: "offline"; reason: "ssh-failed" }
98
+ | { kind: "failed"; reason: string };
99
+
100
+ /** platform "windows": the Windows script prints no entry marker because it reads no census, so the entry is "binary". */
101
+ export function classifyUpdatePlanProbe(result: SshResult, ctx: { homeVersion: string; desktopUpdateRequest: boolean; platform?: "posix" | "windows" }): PlanProbeVerdict {
102
+ const framing = readGatedFraming(result);
103
+ if (framing.kind === "transport") return framing.reason === "ssh-failed" ? { kind: "offline", reason: "ssh-failed" } : { kind: "failed", reason: framing.reason };
104
+ if (framing.kind === "refused") {
105
+ if (framing.reason === "child-ocx-ephemeral") return { kind: "ephemeral" };
106
+ if (framing.reason === "child-ocx-lacks-orchestrated-update" || framing.reason === "child-ocx-version-unknown") return { kind: "legacy", reason: framing.reason };
107
+ return { kind: "failed", reason: framing.reason };
108
+ }
109
+ if (framing.kind === "invalid") return { kind: "failed", reason: "child-output-invalid" };
110
+ if (framing.code !== 0) return { kind: "failed", reason: framing.code === 64 ? "contract-usage" : "child-plan-failed" };
111
+ const parsed = parseChildUpdatePlan(framing.payload);
112
+ if (!parsed.ok) return { kind: "failed", reason: parsed.reason };
113
+ const entry = framing.entry ?? (ctx.platform === "windows" ? "binary" : null);
114
+ return { kind: "plan", selectedVersion: framing.selectedVersion, childNowMs: framing.childNowMs,
115
+ // A plan never execs the launcher; an exec line here is treated as no report.
116
+ classification: classifyChildUpdatePlan(parsed.value, { homeVersion: ctx.homeVersion, desktopUpdateRequest: ctx.desktopUpdateRequest, entry,
117
+ launcher: framing.launcher === "exec" ? null : framing.launcher }) };
118
+ }
119
+
120
+ export function classifyUpdateApply(result: SshResult): UpdateApplyVerdict {
121
+ const framing = readGatedFraming(result);
122
+ if (framing.kind === "transport") return framing.reason === "ssh-failed"
123
+ ? { state: "uncertain", reason: "ssh-failed", suppressTarget: false, reobserve: true }
124
+ : { state: "failed", reason: framing.reason, suppressTarget: false, reobserve: false };
125
+ if (framing.kind === "refused") return framing.reason === "child-ocx-ephemeral"
126
+ ? { state: "unsupported", reason: "ephemeral", suppressTarget: false, reobserve: false }
127
+ // A4: the npm/pnpm launcher route found no Node on the Child; nothing ran.
128
+ : framing.reason === "child-node-unavailable"
129
+ ? { state: "owner-action", reason: "launcher-node-missing", suppressTarget: false, reobserve: false }
130
+ : { state: "owner-action", reason: framing.reason === "child-gate-failed" ? "child-gate-failed" : "legacy-ocx", suppressTarget: false, reobserve: false };
131
+ // Framing broken after a command may have run: never assume it did not.
132
+ if (framing.kind === "invalid") return { state: "uncertain", reason: "child-output-invalid", suppressTarget: false, reobserve: true };
133
+ return mapUpdateApplyExit(framing.code, framing.payload);
134
+ }
135
+
@@ -0,0 +1,206 @@
1
+ import { chmodSync, mkdirSync, readFileSync } from "node:fs";
2
+ import { dirname, join } from "node:path";
3
+ import { atomicWriteFile } from "../config/atomic-write";
4
+ import { withConfigMutationLockSync } from "../config/mutation-lock";
5
+ import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
6
+ import { parseStrictSemver } from "../lib/strict-semver";
7
+ import { hardenSecretDir } from "../lib/windows-secret-acl";
8
+ import { PLAN_RUNTIME_OWNERS, type InstallKind, type PlanRuntimeOwner, type UpdateRoute } from "./child-update-contract";
9
+ import { childObservationsPath } from "./paths";
10
+ import { readLinkStore } from "./store";
11
+
12
+ /**
13
+ * What the Home last learned about each Child, keyed by link id, in <configDir>/link/child-observations.json.
14
+ * A cache, not a trust boundary: unlike links.json's strict record keys, unknown keys are dropped, an invalid entry is
15
+ * dropped and a damaged or foreign file reads as empty, so a downgraded Home ignores it and links.json never changes.
16
+ */
17
+ export const CHILD_OBSERVATIONS_SCHEMA = "ocx.link.child-observations/1";
18
+ export const CHILD_OBSERVATIONS_MAX_BYTES = 1024 * 1024;
19
+ export const DEFAULT_MAX_CHILD_OBSERVATIONS = 256;
20
+ export type ChildOp = "observe" | "sync" | "restart-codex" | "update";
21
+ /** The persisted slice of a wp3 job item. */
22
+ export interface ChildOperationSummary {
23
+ op: ChildOp; jobId: string; state: string; reason: string | null;
24
+ fromVersion?: string; toVersion?: string; finishedAt: string;
25
+ }
26
+ export interface ChildObservation {
27
+ observedAt: string; source: "plan" | "inspect" | "peer";
28
+ installedVersion: string | null; installKind: InstallKind; runtimeOwner: PlanRuntimeOwner | null;
29
+ updateRoute: UpdateRoute; updateReason: string | null; targetVersion: string | null;
30
+ catalogPulledAt: number | null; lastOperation: ChildOperationSummary | null; suppressedTarget: string | null;
31
+ /** Etag of the catalog bytes served with the pull at catalogPulledAt. Display verdict only. */
32
+ catalogPulledEtag: string | null;
33
+ /** Home catalog etag current when a Home-run pinned sync of this Child last reported synced. Fan-out eligibility
34
+ * uses this field, never catalogPulledAt: a GET of /v1/catalog only proves a fetch. */
35
+ catalogSyncedEtag: string | null;
36
+ /** Counted automatic update attempts for one target; survives a Home restart. */
37
+ autoUpdateAttempts: { target: string; count: number } | null;
38
+ /** plan.updateInFlight from the last ocx.update.plan/1 probe; null when the observation did not come from a plan.
39
+ * Not a carried field: every observe replaces it. */
40
+ updateInFlight: boolean | null;
41
+ /** An update whose result is unknown. A record carrying desktopRequestId is cleared only by the Desktop route's
42
+ * status reconciliation or by expiry, never by a sync. */
43
+ pendingUpdateRecovery: { target: string; since: string; until: string; desktopRequestId?: string } | null;
44
+ }
45
+ /** Fields an operation or the Home owns; a fresh observe never overwrites them. Missing in an older file ⇒ null. */
46
+ export const CARRIED_OBSERVATION_FIELDS = ["catalogPulledAt", "catalogPulledEtag", "catalogSyncedEtag", "lastOperation",
47
+ "suppressedTarget", "autoUpdateAttempts", "pendingUpdateRecovery"] as const;
48
+ export interface ChildObservationsFile {
49
+ schema: typeof CHILD_OBSERVATIONS_SCHEMA;
50
+ homeCatalog: { etag: string; changedAt: number } | null;
51
+ children: Record<string, ChildObservation>;
52
+ }
53
+
54
+ const LINK_ID = /^lnk_[0-9a-f]{16}$/;
55
+ // Underscores: the sync classifier's reasons carry the Child's own mismatch token (child-link-mismatch:other_link).
56
+ const REASON = /^[a-z][a-z0-9:_-]{0,79}$/;
57
+ const STATE = /^[a-z][a-z0-9-]{0,63}$/;
58
+ const OPAQUE_ID = /^[A-Za-z0-9_.:-]{1,128}$/;
59
+ const SOURCES: ReadonlySet<string> = new Set(["plan", "inspect", "peer"]);
60
+ const OPS: ReadonlySet<string> = new Set<ChildOp>(["observe", "sync", "restart-codex", "update"]);
61
+ const INSTALL_KINDS: ReadonlySet<string> = new Set<InstallKind>(["npm", "pnpm", "bun", "source", "mise", "desktop-app", "goat", "standalone", "ocx-child", "unknown"]);
62
+ const ROUTES: ReadonlySet<string> = new Set<UpdateRoute>(["orchestrated", "desktop-request", "owner-action", "replant", "none"]);
63
+
64
+ /** Thrown inside a field reader; the entry that holds the field is dropped. */
65
+ class Drop extends Error {}
66
+ const drop = (): never => { throw new Drop(); };
67
+ const isObject = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
68
+ const version = (value: unknown): string => typeof value === "string" && value.length <= 128 && parseStrictSemver(value) ? value : drop();
69
+ const nullable = <T>(value: unknown, read: (value: unknown) => T): T | null => value === null || value === undefined ? null : read(value);
70
+ const time = (value: unknown): string => typeof value === "string" && value.length <= 64 && !Number.isNaN(Date.parse(value)) ? value : drop();
71
+ const epoch = (value: unknown): number => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : drop();
72
+ const token = (pattern: RegExp) => (value: unknown): string => typeof value === "string" && pattern.test(value) ? value : drop();
73
+ const member = <T extends string>(set: ReadonlySet<string>) => (value: unknown): T => typeof value === "string" && set.has(value) ? value as T : drop();
74
+ // Etags are quoted opaque strings; anything printable and bounded is kept.
75
+ const etag = (value: unknown): string => typeof value === "string" && value.length >= 1 && value.length <= 256 && /^[\x20-\x7e]+$/.test(value) ? value : drop();
76
+
77
+ function summary(value: unknown): ChildOperationSummary {
78
+ if (!isObject(value)) return drop();
79
+ return {
80
+ op: member<ChildOp>(OPS)(value.op), jobId: token(OPAQUE_ID)(value.jobId), state: token(STATE)(value.state),
81
+ reason: nullable(value.reason, token(REASON)),
82
+ ...(value.fromVersion === undefined ? {} : { fromVersion: version(value.fromVersion) }),
83
+ ...(value.toVersion === undefined ? {} : { toVersion: version(value.toVersion) }),
84
+ finishedAt: time(value.finishedAt),
85
+ };
86
+ }
87
+ function attempts(value: unknown): { target: string; count: number } {
88
+ if (!isObject(value)) return drop();
89
+ const count = value.count;
90
+ return { target: version(value.target), count: typeof count === "number" && Number.isSafeInteger(count) && count >= 0 ? count : drop() };
91
+ }
92
+ function recovery(value: unknown): NonNullable<ChildObservation["pendingUpdateRecovery"]> {
93
+ if (!isObject(value)) return drop();
94
+ return { target: version(value.target), since: time(value.since), until: time(value.until),
95
+ ...(value.desktopRequestId === undefined ? {} : { desktopRequestId: token(OPAQUE_ID)(value.desktopRequestId) }) };
96
+ }
97
+ function observation(value: unknown): ChildObservation {
98
+ if (!isObject(value)) return drop();
99
+ return {
100
+ observedAt: time(value.observedAt), source: member<ChildObservation["source"]>(SOURCES)(value.source),
101
+ installedVersion: nullable(value.installedVersion, version), installKind: member<InstallKind>(INSTALL_KINDS)(value.installKind),
102
+ runtimeOwner: nullable(value.runtimeOwner, member<PlanRuntimeOwner>(PLAN_RUNTIME_OWNERS)),
103
+ updateRoute: member<UpdateRoute>(ROUTES)(value.updateRoute), updateReason: nullable(value.updateReason, token(REASON)),
104
+ targetVersion: nullable(value.targetVersion, version), catalogPulledAt: nullable(value.catalogPulledAt, epoch),
105
+ lastOperation: nullable(value.lastOperation, summary), suppressedTarget: nullable(value.suppressedTarget, version),
106
+ catalogPulledEtag: nullable(value.catalogPulledEtag, etag), catalogSyncedEtag: nullable(value.catalogSyncedEtag, etag),
107
+ autoUpdateAttempts: nullable(value.autoUpdateAttempts, attempts),
108
+ updateInFlight: nullable(value.updateInFlight, item => typeof item === "boolean" ? item : drop()),
109
+ pendingUpdateRecovery: nullable(value.pendingUpdateRecovery, recovery),
110
+ };
111
+ }
112
+ function homeCatalog(value: unknown): ChildObservationsFile["homeCatalog"] {
113
+ if (!isObject(value)) return null;
114
+ try { return { etag: etag(value.etag), changedAt: epoch(value.changedAt) }; } catch (error) {
115
+ if (error instanceof Drop) return null;
116
+ throw error;
117
+ }
118
+ }
119
+
120
+ export function emptyChildObservations(): ChildObservationsFile {
121
+ return { schema: CHILD_OBSERVATIONS_SCHEMA, homeCatalog: null, children: {} };
122
+ }
123
+
124
+ export function withoutCarriedFields(value: ChildObservation): Partial<ChildObservation> {
125
+ const copy: Partial<ChildObservation> = { ...value };
126
+ for (const field of CARRIED_OBSERVATION_FIELDS) delete copy[field];
127
+ return copy;
128
+ }
129
+
130
+ /** Tolerant: unknown keys dropped, an invalid entry dropped, an invalid file or wrong schema reads as empty. */
131
+ export function parseChildObservations(text: string): ChildObservationsFile {
132
+ let raw: unknown;
133
+ try { raw = JSON.parse(text); } catch { return emptyChildObservations(); }
134
+ if (!isObject(raw) || raw.schema !== CHILD_OBSERVATIONS_SCHEMA) return emptyChildObservations();
135
+ const file: ChildObservationsFile = { schema: CHILD_OBSERVATIONS_SCHEMA, homeCatalog: homeCatalog(raw.homeCatalog), children: {} };
136
+ if (!isObject(raw.children)) return file;
137
+ for (const [linkId, entry] of Object.entries(raw.children)) {
138
+ if (!LINK_ID.test(linkId)) continue;
139
+ try { file.children[linkId] = observation(entry); } catch (error) {
140
+ if (!(error instanceof Drop)) throw error;
141
+ }
142
+ }
143
+ return file;
144
+ }
145
+
146
+ /** Missing, unreadable, larger than 1 MiB or damaged → empty. Never throws for content. */
147
+ export function readChildObservations(path: string = childObservationsPath()): ChildObservationsFile {
148
+ let bytes: Buffer;
149
+ try { bytes = readFileSync(path); } catch { return emptyChildObservations(); }
150
+ if (bytes.length > CHILD_OBSERVATIONS_MAX_BYTES) return emptyChildObservations();
151
+ return parseChildObservations(bytes.toString("utf8"));
152
+ }
153
+
154
+ /** Keep the most recently observed entries when the file holds more than maxEntries. */
155
+ function capEntries(file: ChildObservationsFile, maxEntries: number): void {
156
+ const entries = Object.entries(file.children);
157
+ if (entries.length <= maxEntries) return;
158
+ entries.sort(([, a], [, b]) => Date.parse(b.observedAt) - Date.parse(a.observedAt));
159
+ file.children = Object.fromEntries(entries.slice(0, Math.max(0, maxEntries)));
160
+ }
161
+
162
+ /**
163
+ * Read–mutate–write under withConfigMutationLockSync. Inside the lock it reads links.json and drops entries whose link
164
+ * id is absent; a damaged links.json disables pruning for that write only. Dir 0700 (hardenSecretDir on Windows), file
165
+ * written with atomicWriteFile then chmod 0600, as writeLinkStore. Throws ConfigMutationLockError on contention
166
+ * (busy_timeout=0); callers decide whether to retry.
167
+ */
168
+ export function updateChildObservations(mutate: (file: ChildObservationsFile) => void,
169
+ deps: { path?: string; storePath?: string; maxEntries?: number } = {}): ChildObservationsFile {
170
+ const path = deps.path ?? childObservationsPath();
171
+ const dir = dirname(path), configDir = dirname(dir);
172
+ assertNotRealHomeUnderTest(configDir);
173
+ return withConfigMutationLockSync(() => {
174
+ const current = readChildObservations(path);
175
+ mutate(current);
176
+ const next = parseChildObservations(JSON.stringify(current));
177
+ let linkIds: Set<string> | null = null;
178
+ try { linkIds = new Set(readLinkStore(deps.storePath ?? join(dir, "links.json")).links.map(link => link.id)); } catch { linkIds = null; }
179
+ if (linkIds) for (const linkId of Object.keys(next.children)) if (!linkIds.has(linkId)) delete next.children[linkId];
180
+ capEntries(next, deps.maxEntries ?? DEFAULT_MAX_CHILD_OBSERVATIONS);
181
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
182
+ if (process.platform === "win32") hardenSecretDir(dir, { required: true });
183
+ else chmodSync(dir, 0o700);
184
+ atomicWriteFile(path, `${JSON.stringify(next, null, 2)}\n`);
185
+ if (process.platform !== "win32") chmodSync(path, 0o600);
186
+ return next;
187
+ }, configDir);
188
+ }
189
+
190
+ /**
191
+ * Merge a patch into one Child's entry and stamp observedAt with now. A patch of carried fields only (a catalog pull,
192
+ * an operation summary) keeps an existing entry's observedAt, so install facts never read fresher than they are.
193
+ * A Child never observed before starts as an unknown "inspect" record with every field null, so an operation summary
194
+ * can be stored before the first observe; that new entry is stamped.
195
+ */
196
+ export function patchChildObservation(file: ChildObservationsFile, linkId: string, patch: Partial<ChildObservation>, now: Date): void {
197
+ const existing = file.children[linkId];
198
+ const base: ChildObservation = existing ?? {
199
+ observedAt: now.toISOString(), source: "inspect", installedVersion: null, installKind: "unknown", runtimeOwner: null,
200
+ updateRoute: "none", updateReason: null, targetVersion: null, catalogPulledAt: null, lastOperation: null, suppressedTarget: null,
201
+ catalogPulledEtag: null, catalogSyncedEtag: null, autoUpdateAttempts: null, updateInFlight: null, pendingUpdateRecovery: null,
202
+ };
203
+ const carriedOnly = Object.keys(patch).every(key => (CARRIED_OBSERVATION_FIELDS as readonly string[]).includes(key));
204
+ file.children[linkId] = { ...base, ...patch, observedAt: carriedOnly && existing ? base.observedAt : now.toISOString() };
205
+ }
206
+
@@ -0,0 +1,121 @@
1
+ import { classifyUpdatePlanProbe, remoteUpdatePlanArgv, type SshResult } from "./child-gated-ocx";
2
+ import type { PlanClassification } from "./child-update-contract";
3
+ import type { ChildObservation } from "./child-observations";
4
+ import type { LinkPeerEntry } from "./peer-report";
5
+ import type { inspectRemoteChildRuntime } from "./remote-plant";
6
+ import { buildExecArgv, LinkSshArgumentError } from "./ssh-argv";
7
+ import { SshRunnerError, type SshRunner } from "./ssh-runner";
8
+ import type { LinkRecord } from "./store";
9
+ import { parseOcxVersion } from "./sync-fanout-classify";
10
+ import { parseStrictSemver } from "../lib/strict-semver";
11
+
12
+ export const OBSERVE_TIMEOUT_MS = 60_000;
13
+ export const OBSERVE_MAX_OUTPUT_BYTES = 65_536;
14
+
15
+ export interface ObserveDeps {
16
+ runner: Pick<SshRunner, "run">; knownHostsFile: string; homeVersion: string;
17
+ peer: (linkId: string) => LinkPeerEntry; platformOf: (record: LinkRecord) => Promise<"posix" | "windows">;
18
+ inspect: typeof inspectRemoteChildRuntime; now: () => Date;
19
+ }
20
+
21
+ /**
22
+ * Set only for a parsed plan. childNowMs is the Child's clock from the gate; startedAt is the Home's clock when the probe
23
+ * was sent; platform is the one observe resolved, so the wp3 update runner never probes it again.
24
+ */
25
+ export interface ObserveProbe { classification: PlanClassification; childNowMs: number | null; startedAt: number; platform: "posix" | "windows" }
26
+
27
+ /** observation is a whole ChildObservation with every carried field null; writers strip them with withoutCarriedFields. */
28
+ export interface ObserveOutcome {
29
+ state: "succeeded" | "owner-action" | "unsupported" | "offline" | "failed"; reason: string | null;
30
+ observation: ChildObservation | null; probe: ObserveProbe | null;
31
+ }
32
+
33
+ type ObservedFields = Pick<ChildObservation, "source" | "installedVersion" | "installKind" | "runtimeOwner" | "updateRoute" | "updateReason"
34
+ | "targetVersion" | "updateInFlight">;
35
+
36
+ function observation(fields: ObservedFields, now: Date): ChildObservation {
37
+ return {
38
+ observedAt: now.toISOString(), ...fields,
39
+ catalogPulledAt: null, catalogPulledEtag: null, catalogSyncedEtag: null, lastOperation: null, suppressedTarget: null,
40
+ autoUpdateAttempts: null, pendingUpdateRecovery: null,
41
+ };
42
+ }
43
+
44
+ const strictVersion = (value: string | null | undefined): string | null => typeof value === "string" && parseStrictSemver(value) ? value : null;
45
+ const peerVersion = (deps: ObserveDeps, record: LinkRecord): string | null => strictVersion(deps.peer(record.id).observed?.version);
46
+ const outcome = (state: ObserveOutcome["state"], reason: string | null, value: ChildObservation | null = null): ObserveOutcome =>
47
+ ({ state, reason, observation: value, probe: null });
48
+
49
+ function ephemeral(now: Date): ObserveOutcome {
50
+ // An ocx-child's version is a protocol constant (D10), so no version is stored.
51
+ return outcome("succeeded", null, observation({ source: "peer", installedVersion: null, installKind: "ocx-child", runtimeOwner: null,
52
+ updateRoute: "replant", updateReason: "ocx-child", targetVersion: null, updateInFlight: null }, now));
53
+ }
54
+
55
+ function runnerFailure(error: unknown): ObserveOutcome {
56
+ if (error instanceof SshRunnerError && error.code === "output_limit") return outcome("failed", "ssh-output-limit");
57
+ if (error instanceof SshRunnerError && error.code === "decode") return outcome("failed", "ssh-output-decode");
58
+ return outcome("offline", "ssh-error");
59
+ }
60
+
61
+ /**
62
+ * The observe operation (D3): one gated `ocx update --plan` over the link's pinned SSH channel, reduced to closed
63
+ * tokens. It never changes an install. Client-initiated and ocx-child links never reach SSH; a pre-2.97 POSIX Child
64
+ * costs one more read-only SSH call to read its version. No remote text is returned.
65
+ */
66
+ export async function observeChild(record: LinkRecord, deps: ObserveDeps): Promise<ObserveOutcome> {
67
+ if (record.direction === "client-initiated") {
68
+ return { state: "unsupported", reason: "child-initiated", probe: null, observation: observation({ source: "peer",
69
+ installedVersion: peerVersion(deps, record), installKind: "unknown", runtimeOwner: null, updateRoute: "none",
70
+ updateReason: "child-initiated", targetVersion: null, updateInFlight: null }, deps.now()) };
71
+ }
72
+ if (record.childKind === "ephemeral") return ephemeral(deps.now());
73
+ let platform: "posix" | "windows";
74
+ try { platform = record.remotePlatform ?? await deps.platformOf(record); } catch { return outcome("offline", "platform-unknown"); }
75
+ let argv: string[];
76
+ try {
77
+ argv = buildExecArgv({ alias: record.alias, knownHostsFile: deps.knownHostsFile, argv: remoteUpdatePlanArgv(deps.homeVersion, platform), route: record.explicitRoute ?? null });
78
+ } catch (error) {
79
+ if (error instanceof LinkSshArgumentError && error.message === "windows-command-too-long") return outcome("failed", "windows-command-too-long");
80
+ if (error instanceof LinkSshArgumentError && error.message === "invalid Home version") return outcome("failed", "home-version-invalid");
81
+ return outcome("failed", "ssh-argument-invalid");
82
+ }
83
+ const startedAt = deps.now().getTime();
84
+ let result: SshResult;
85
+ try {
86
+ result = await deps.runner.run(argv, { timeoutMs: OBSERVE_TIMEOUT_MS, maxOutputBytes: OBSERVE_MAX_OUTPUT_BYTES });
87
+ } catch (error) { return runnerFailure(error); }
88
+ const peerFeatures = deps.peer(record.id).observed?.features ?? [];
89
+ // Always pass the platform: the Windows script prints no entry marker and only this lets the classifier infer binary.
90
+ const verdict = classifyUpdatePlanProbe(result, { homeVersion: deps.homeVersion, desktopUpdateRequest: peerFeatures.includes("desktop-update-request/1"), platform });
91
+ switch (verdict.kind) {
92
+ case "plan": {
93
+ const { classification } = verdict;
94
+ return { state: "succeeded", reason: null, probe: { classification, childNowMs: verdict.childNowMs, startedAt, platform },
95
+ observation: observation({ source: "plan", installedVersion: strictVersion(classification.installedVersion),
96
+ installKind: classification.installKind, runtimeOwner: classification.runtimeOwner, updateRoute: classification.updateRoute,
97
+ updateReason: classification.updateReason, targetVersion: strictVersion(classification.targetVersion),
98
+ updateInFlight: classification.updateInFlight }, deps.now()) };
99
+ }
100
+ case "ephemeral": return ephemeral(deps.now());
101
+ case "legacy": {
102
+ let installedVersion: string | null;
103
+ let source: ChildObservation["source"];
104
+ if (platform === "posix") {
105
+ source = "inspect";
106
+ try {
107
+ const inspected = await deps.inspect(deps.runner, record.alias, record.explicitRoute ?? null, deps.knownHostsFile, "posix");
108
+ installedVersion = parseOcxVersion(inspected?.ocxVersionLine ?? "");
109
+ } catch { installedVersion = null; }
110
+ } else {
111
+ // Windows inspection does not read the served census, so the peer report is the better source.
112
+ source = "peer";
113
+ installedVersion = peerVersion(deps, record);
114
+ }
115
+ return outcome("owner-action", "legacy-ocx", observation({ source, installedVersion, installKind: "unknown", runtimeOwner: null,
116
+ updateRoute: "owner-action", updateReason: "legacy-ocx", targetVersion: null, updateInFlight: null }, deps.now()));
117
+ }
118
+ case "offline": return outcome("offline", "ssh-failed");
119
+ case "failed": return outcome("failed", verdict.reason);
120
+ }
121
+ }