@bitkyc08/opencodex 2.100.2 → 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 (561) 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-BcaI-VCr.js → Tray-BV4ms9U9.js} +1 -1
  6. package/gui/dist/assets/{brand-mark-DU-0Vdkr.js → brand-mark-XOLJbomA.js} +1 -1
  7. package/gui/dist/assets/index-DCdXsMyZ.js +105 -0
  8. package/gui/dist/assets/{index-DJEkIDAi.css → index-DQtCRNAw.css} +1 -1
  9. package/gui/dist/assets/{segment-thumb-features-e9A_FogJ.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-DT146AhS.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-CakPe9Ni.js → quota-summary-Dy5_wfTT.js} +1 -1
  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 +3 -3
  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/protobuf-request.ts +8 -8
  38. package/src/adapters/cursor.ts +7 -6
  39. package/src/adapters/google-antigravity-wire.ts +7 -5
  40. package/src/adapters/google-wire-compiler.ts +2 -2
  41. package/src/adapters/google.ts +9 -2
  42. package/src/adapters/kiro/payload.ts +7 -4
  43. package/src/adapters/kiro/reasoning.ts +44 -1
  44. package/src/adapters/kiro/structured-output.ts +10 -8
  45. package/src/adapters/kiro-tools.ts +61 -15
  46. package/src/adapters/openai-chat/destination-policy.ts +16 -0
  47. package/src/adapters/openai-chat/reasoning-replay.ts +4 -1
  48. package/src/adapters/zed.ts +3 -0
  49. package/src/advisor/consult.ts +15 -4
  50. package/src/advisor/context.ts +12 -3
  51. package/src/advisor/runtime.ts +35 -5
  52. package/src/advisor/settings.ts +8 -0
  53. package/src/advisor/synthetic-tool.ts +21 -8
  54. package/src/bridge/response-json.ts +11 -2
  55. package/src/bridge/sse.ts +43 -8
  56. package/src/claude/auth-detect.ts +21 -33
  57. package/src/claude/desktop-3p.ts +11 -5
  58. package/src/claude/desktop-gateway-state.ts +2 -0
  59. package/src/claude/desktop-remote-store-artifact.ts +14 -3
  60. package/src/claude/desktop-remote-store.ts +24 -4
  61. package/src/claude/inbound-content-options.ts +31 -16
  62. package/src/claude/outbound.ts +13 -3
  63. package/src/cli/account-api.ts +17 -1
  64. package/src/cli/account-auth.ts +54 -21
  65. package/src/cli/account-key-quota.ts +34 -5
  66. package/src/cli/account.ts +4 -2
  67. package/src/cli/advisor.ts +7 -4
  68. package/src/cli/alias.ts +38 -1
  69. package/src/cli/capabilities-access-remote.ts +128 -3
  70. package/src/cli/capabilities-accounts.ts +3 -3
  71. package/src/cli/capabilities-agents-routing.ts +17 -10
  72. package/src/cli/capabilities-base.ts +41 -16
  73. package/src/cli/capabilities-integrations.ts +2 -2
  74. package/src/cli/capabilities-provider-models.ts +18 -2
  75. package/src/cli/capabilities-route-to.ts +43 -0
  76. package/src/cli/capabilities.ts +2 -0
  77. package/src/cli/capability-contracts.ts +1 -1
  78. package/src/cli/claude-desktop.ts +30 -11
  79. package/src/cli/claude.ts +17 -3
  80. package/src/cli/codex-launcher.ts +3 -1
  81. package/src/cli/codex-shim-autorestore.ts +5 -42
  82. package/src/cli/config-command.ts +14 -1
  83. package/src/cli/config-root-startup.ts +34 -0
  84. package/src/cli/connect.ts +88 -16
  85. package/src/cli/desktop-runtime-guidance.ts +1 -1
  86. package/src/cli/disconnect-runtime.ts +168 -0
  87. package/src/cli/dispatch.ts +54 -12
  88. package/src/cli/export-command.ts +1 -1
  89. package/src/cli/gui-pair-client.ts +6 -3
  90. package/src/cli/gui.ts +10 -5
  91. package/src/cli/help-catalog.ts +11 -0
  92. package/src/cli/help.ts +4 -3
  93. package/src/cli/index.ts +83 -92
  94. package/src/cli/inspect.ts +11 -2
  95. package/src/cli/integrations.ts +26 -1
  96. package/src/cli/link-capture.ts +64 -0
  97. package/src/cli/link-child-ops.ts +218 -40
  98. package/src/cli/link-cleanup.ts +8 -5
  99. package/src/cli/link-diagnostics.ts +67 -0
  100. package/src/cli/link-enrollment.ts +158 -12
  101. package/src/cli/link-operations.ts +52 -0
  102. package/src/cli/link-recover.ts +152 -0
  103. package/src/cli/link-routes.ts +87 -0
  104. package/src/cli/link-status-child.ts +44 -1
  105. package/src/cli/link-status-traffic.ts +34 -0
  106. package/src/cli/link.ts +314 -37
  107. package/src/cli/message-command.ts +1 -1
  108. package/src/cli/message-mcp-command.ts +23 -10
  109. package/src/cli/models-runtime.ts +3 -3
  110. package/src/cli/opencode.ts +3 -1
  111. package/src/cli/pi-sync.ts +35 -0
  112. package/src/cli/preflight-exemptions.ts +46 -0
  113. package/src/cli/registry.ts +28 -12
  114. package/src/cli/restart-failure.ts +5 -2
  115. package/src/cli/root.ts +5 -1
  116. package/src/cli/route-to.ts +172 -0
  117. package/src/cli/runtime-api.ts +5 -8
  118. package/src/cli/status.ts +3 -1
  119. package/src/cli/stop-approval.ts +66 -19
  120. package/src/cli/stop-report.ts +23 -0
  121. package/src/cli/stop-windows-checked.ts +304 -0
  122. package/src/cli/sync-command.ts +70 -15
  123. package/src/cli/sync-fanout.ts +74 -19
  124. package/src/cli/sync-flags.ts +40 -3
  125. package/src/cli/sync-link-status.ts +18 -2
  126. package/src/cli/sync-update-guard.ts +7 -2
  127. package/src/cli/system-restart-client.ts +3 -2
  128. package/src/cli/uninstall-plan.ts +77 -5
  129. package/src/cli/uninstall-stop.ts +152 -0
  130. package/src/cli/v2-input.ts +10 -6
  131. package/src/cli/v2-local-output.ts +3 -2
  132. package/src/cli/v2-runtime.ts +10 -3
  133. package/src/cli/v2.ts +22 -7
  134. package/src/client/connect.ts +321 -34
  135. package/src/client/link-home-features.ts +27 -0
  136. package/src/client/link-home.ts +92 -4
  137. package/src/client/link-ingress.ts +21 -3
  138. package/src/client/link-join.ts +12 -2
  139. package/src/client/link-parity-reporter.ts +60 -6
  140. package/src/client/link-relay-transport.ts +161 -36
  141. package/src/client/link-relay.ts +150 -6
  142. package/src/client/link-request-compression.ts +84 -0
  143. package/src/client/link-state.ts +11 -5
  144. package/src/client/link-status.ts +39 -1
  145. package/src/client/link-teardown.ts +1 -0
  146. package/src/client/link-tunnel.ts +56 -5
  147. package/src/client/link-websocket-limits.ts +89 -0
  148. package/src/client/link-websocket.ts +586 -0
  149. package/src/client/link-ws-advertisement.ts +100 -0
  150. package/src/client/link-ws-framer.ts +241 -0
  151. package/src/client/link-ws-transport.ts +177 -0
  152. package/src/client/machine-api.ts +13 -2
  153. package/src/client/machine-listener.ts +48 -7
  154. package/src/client/route-intent-apply.ts +293 -0
  155. package/src/client/route-intent-file-originals.ts +97 -0
  156. package/src/client/route-intent-native-originals.ts +201 -0
  157. package/src/client/route-intent-watch.ts +141 -0
  158. package/src/client/runtime-restart.ts +127 -5
  159. package/src/client/runtime.ts +61 -15
  160. package/src/client/state.ts +30 -0
  161. package/src/client/sync-expectation.ts +36 -2
  162. package/src/client/sync-runtime.ts +7 -0
  163. package/src/clients/config-export/alias-selectors.ts +63 -40
  164. package/src/clients/config-export/contracts.ts +2 -0
  165. package/src/clients/config-export/nested-selectors.ts +42 -0
  166. package/src/clients/config-export.ts +22 -3
  167. package/src/codex/account-store.ts +12 -3
  168. package/src/codex/account-usability.ts +13 -0
  169. package/src/codex/auth-api/account-list.ts +29 -3
  170. package/src/codex/auth-collision.ts +23 -22
  171. package/src/codex/auth-context.ts +21 -6
  172. package/src/codex/catalog/gather-capture.ts +8 -2
  173. package/src/codex/catalog/parsing.ts +7 -3
  174. package/src/codex/catalog/provider-models.ts +54 -15
  175. package/src/codex/catalog/retained-sync.ts +2 -1
  176. package/src/codex/catalog/routed-gather.ts +1 -1
  177. package/src/codex/catalog-auto-refresh.ts +11 -0
  178. package/src/codex/cli-update-job.ts +35 -13
  179. package/src/codex/convergence.ts +2 -2
  180. package/src/codex/desktop-compatibility/native-identity.ts +4 -8
  181. package/src/codex/features.ts +2 -2
  182. package/src/codex/history-provider.ts +31 -0
  183. package/src/codex/inject/multi-agent-v2.ts +9 -3
  184. package/src/codex/inject/paginated-openai-compat.ts +54 -1
  185. package/src/codex/inject/plan.ts +20 -2
  186. package/src/codex/inject.ts +2 -0
  187. package/src/codex/journal-config-restore.ts +217 -0
  188. package/src/codex/journal.ts +75 -6
  189. package/src/codex/main-account.ts +23 -30
  190. package/src/codex/native-main-auth-file.ts +104 -0
  191. package/src/codex/native-profile-manager.ts +4 -3
  192. package/src/codex/native-profile-store.ts +3 -61
  193. package/src/codex/orca-import.ts +10 -1
  194. package/src/codex/quota-history.ts +13 -0
  195. package/src/codex/quota-window-conflict.ts +103 -0
  196. package/src/codex/quota.ts +23 -1
  197. package/src/codex/subagent-model-fallback.ts +3 -1
  198. package/src/codex/websocket-activity.ts +171 -16
  199. package/src/codex/websocket-registry.ts +11 -4
  200. package/src/combos/cooldown-store.ts +25 -5
  201. package/src/combos/failover.ts +330 -2
  202. package/src/config/dashboard-trusted-proxy.ts +83 -0
  203. package/src/config/diagnostics.ts +28 -0
  204. package/src/config/feature-flags.ts +9 -0
  205. package/src/config/live-reconcile.ts +10 -1
  206. package/src/config/load-degrade.ts +12 -1
  207. package/src/config/multi-agent-surface.ts +28 -5
  208. package/src/config/pending-teardown.ts +60 -3
  209. package/src/config/process-state.ts +175 -4
  210. package/src/config/provider-validation.ts +4 -4
  211. package/src/config/schema/config-schema.ts +6 -0
  212. package/src/config/schema/leaf-validators.ts +9 -2
  213. package/src/config/windows-process-command-line.ts +107 -0
  214. package/src/generated/compatibility-version.json +948 -392
  215. package/src/generated/model-metadata.ts +1 -1
  216. package/src/images/loop.ts +3 -0
  217. package/src/integrations/model-name-guard.ts +25 -0
  218. package/src/integrations/route-intent-catalog.ts +26 -0
  219. package/src/integrations/route-intent-connected.ts +262 -0
  220. package/src/integrations/route-intent-contract.ts +55 -0
  221. package/src/integrations/route-intent-disconnect.ts +109 -0
  222. package/src/integrations/route-intent-initial.ts +64 -0
  223. package/src/integrations/route-intent-state.ts +117 -0
  224. package/src/integrations/route-intent-tick.ts +65 -0
  225. package/src/integrations/route-intent.ts +212 -0
  226. package/src/integrations/writer.ts +44 -11
  227. package/src/lib/client-retry-after.ts +29 -0
  228. package/src/lib/config-ownership.ts +13 -0
  229. package/src/lib/desktop-gui-origin.ts +28 -0
  230. package/src/lib/errors.ts +1 -1
  231. package/src/lib/gui-pair-capability.ts +2 -1
  232. package/src/lib/messages-error-body.ts +4 -1
  233. package/src/lib/outbound-credential-registry.ts +362 -4
  234. package/src/lib/paced-stream.ts +34 -0
  235. package/src/lib/passive-key-fetch-proof.ts +30 -0
  236. package/src/lib/passive-read.ts +5 -0
  237. package/src/lib/process-control.ts +76 -12
  238. package/src/lib/redact.ts +84 -8
  239. package/src/lib/state-store-registrations.ts +11 -0
  240. package/src/lib/state-store-sweeper.ts +4 -0
  241. package/src/lib/supervisor-markers.ts +18 -0
  242. package/src/lib/terminal-safe-text.ts +58 -0
  243. package/src/lib/translator-budget.ts +3 -2
  244. package/src/lib/upstream-retry.ts +14 -4
  245. package/src/link/alias-lock.ts +119 -0
  246. package/src/link/child-activity.ts +28 -2
  247. package/src/link/child-binary-cache-fill.d.mts +50 -0
  248. package/src/link/child-binary-cache-fill.mjs +494 -0
  249. package/src/link/child-binary-cache-start.ts +73 -0
  250. package/src/link/child-binary-source.ts +12 -5
  251. package/src/link/child-gated-ocx.ts +29 -11
  252. package/src/link/child-observations.ts +2 -1
  253. package/src/link/child-observe.ts +2 -2
  254. package/src/link/child-ops-engine.ts +159 -91
  255. package/src/link/child-ops-host.ts +138 -0
  256. package/src/link/child-ops-runners.ts +319 -0
  257. package/src/link/child-ops-scheduler.ts +207 -0
  258. package/src/link/child-ops-types.ts +89 -0
  259. package/src/link/child-parity.ts +23 -4
  260. package/src/link/child-policy.ts +93 -0
  261. package/src/link/child-update-contract.ts +12 -3
  262. package/src/link/codex-settings.ts +1 -1
  263. package/src/link/compatibility.ts +18 -1
  264. package/src/link/diagnostics-read.ts +163 -0
  265. package/src/link/diagnostics.ts +20 -7
  266. package/src/link/explicit-route.ts +209 -0
  267. package/src/link/link-recover.ts +113 -0
  268. package/src/link/management-routes.ts +3 -1
  269. package/src/link/operation-recovery-slot.ts +44 -0
  270. package/src/link/operations-journal.ts +408 -0
  271. package/src/link/peer-report.ts +1 -1
  272. package/src/link/relay-auth.ts +14 -0
  273. package/src/link/remote-plant.ts +152 -14
  274. package/src/link/remote-platform.ts +21 -10
  275. package/src/link/remote-probe.ts +11 -3
  276. package/src/link/remote-windows.ts +50 -10
  277. package/src/link/request-compression.ts +30 -0
  278. package/src/link/residual-recovery.ts +54 -0
  279. package/src/link/retirement.ts +128 -0
  280. package/src/link/route-intent-watch.ts +41 -0
  281. package/src/link/route-intent.ts +209 -0
  282. package/src/link/route-proof.ts +82 -0
  283. package/src/link/route-rounds.ts +579 -0
  284. package/src/link/route-select.ts +95 -0
  285. package/src/link/route-trust.ts +96 -0
  286. package/src/link/ssh-argv.ts +172 -24
  287. package/src/link/ssh-capture-redact.ts +253 -0
  288. package/src/link/ssh-capture.ts +497 -0
  289. package/src/link/ssh-runner.ts +141 -14
  290. package/src/link/status-projection.ts +87 -0
  291. package/src/link/store.ts +54 -1
  292. package/src/link/supervisor.ts +543 -55
  293. package/src/link/sync-fanout-classify.ts +16 -0
  294. package/src/link/sync-then-restart.ts +65 -0
  295. package/src/link/tombstones.ts +209 -0
  296. package/src/link/traffic.ts +178 -0
  297. package/src/link/ws-activity-holds.ts +474 -0
  298. package/src/local-credentials/publication-fence.ts +20 -1
  299. package/src/messaging/mcp-queue-rpc.ts +1 -1
  300. package/src/messaging/mcp-queue-server.ts +16 -1
  301. package/src/messaging/mcp-resume-tools.ts +25 -0
  302. package/src/messaging/remote-enrollment.ts +3 -3
  303. package/src/messaging/remote-tunnels.ts +2 -2
  304. package/src/messaging/resume-permissions.ts +27 -0
  305. package/src/messaging/rpc.ts +46 -2
  306. package/src/oauth/anthropic-continuity.ts +23 -7
  307. package/src/oauth/anthropic-routing.ts +5 -2
  308. package/src/oauth/anthropic.ts +22 -2
  309. package/src/oauth/claude-keychain-read.ts +78 -68
  310. package/src/oauth/index.ts +24 -6
  311. package/src/oauth/local-token-detect.ts +8 -29
  312. package/src/oauth/login-cli-errors.ts +5 -1
  313. package/src/oauth/login-cli.ts +33 -18
  314. package/src/oauth/login-flow-state.ts +26 -3
  315. package/src/oauth/meta-muse.ts +1 -1
  316. package/src/oauth/store.ts +7 -0
  317. package/src/oauth/xai.ts +248 -14
  318. package/src/protocols/contract.ts +4 -0
  319. package/src/protocols/encoders/messages.ts +1 -0
  320. package/src/providers/alias-template.ts +48 -0
  321. package/src/providers/anthropic-billing-ownership.ts +2 -0
  322. package/src/providers/anthropic-output-caps.ts +46 -0
  323. package/src/providers/anthropic-reset-grant-ledger.ts +9 -3
  324. package/src/providers/antigravity-effort-families.ts +11 -3
  325. package/src/providers/antigravity-models.ts +32 -9
  326. package/src/providers/antigravity-wire-snapshot.ts +3 -2
  327. package/src/providers/api-key-pause.ts +3 -0
  328. package/src/providers/api-key-resolve.ts +49 -7
  329. package/src/providers/api-key-response-ownership.ts +2 -0
  330. package/src/providers/api-key-selection.ts +51 -9
  331. package/src/providers/api-keys.ts +6 -2
  332. package/src/providers/cache-affinity-identity.ts +73 -0
  333. package/src/providers/cache-affinity.ts +256 -0
  334. package/src/providers/default-aliases.ts +98 -20
  335. package/src/providers/google-vertex-model-discovery.ts +510 -0
  336. package/src/providers/key-failover.ts +123 -8
  337. package/src/providers/key-store.ts +3 -3
  338. package/src/providers/kiro-models.ts +3 -5
  339. package/src/providers/label.ts +31 -5
  340. package/src/providers/mistral-transport.ts +17 -4
  341. package/src/providers/model-rename-fields.ts +3 -0
  342. package/src/providers/muse-key-quota.ts +14 -6
  343. package/src/providers/new-model-policy-runtime.ts +17 -4
  344. package/src/providers/new-model-policy.ts +30 -4
  345. package/src/providers/passive-key-observation.ts +252 -0
  346. package/src/providers/quota/account-cache.ts +2 -1
  347. package/src/providers/quota/anthropic-cooldown-recovery-worker.ts +121 -0
  348. package/src/providers/quota/passive-key-limits.ts +272 -0
  349. package/src/providers/quota/passive-wire-model.ts +126 -0
  350. package/src/providers/quota/report-cache.ts +61 -2
  351. package/src/providers/quota-key-accounts.ts +11 -6
  352. package/src/providers/quota-types.ts +18 -0
  353. package/src/providers/quota.ts +11 -12
  354. package/src/providers/registry/entries-core.ts +34 -16
  355. package/src/providers/registry/entries-extended.ts +32 -0
  356. package/src/providers/registry/model-seeds.ts +35 -0
  357. package/src/providers/resolved-model-policy.ts +7 -0
  358. package/src/providers/routed-config.ts +8 -3
  359. package/src/providers/xai-transport.ts +3 -0
  360. package/src/remote/features.ts +17 -0
  361. package/src/responses/anthropic-progress.ts +10 -4
  362. package/src/responses/citation-markers.ts +231 -0
  363. package/src/responses/spill-store.ts +5 -1
  364. package/src/responses/state/replay-input.ts +50 -0
  365. package/src/responses/state/replay-owner.ts +24 -0
  366. package/src/responses/state/snapshot-codec.ts +9 -0
  367. package/src/responses/state/spill-queue.ts +1 -0
  368. package/src/responses/state.ts +42 -60
  369. package/src/router.ts +2 -2
  370. package/src/routing/home-route-capture.ts +123 -0
  371. package/src/routing/home-route-intent.ts +200 -0
  372. package/src/routing/route-intent-state.ts +178 -0
  373. package/src/routing/route-to-live-settings.ts +35 -0
  374. package/src/routing/route-to-local.ts +145 -0
  375. package/src/routing/route-to-status.ts +94 -0
  376. package/src/routing/route-to-sync-child.ts +32 -0
  377. package/src/server/adapter-resolve.ts +21 -1
  378. package/src/server/admitted-http-turn.ts +3 -0
  379. package/src/server/auth-cors.ts +98 -0
  380. package/src/server/bare-upstream-error.ts +220 -0
  381. package/src/server/chat-native.ts +14 -5
  382. package/src/server/claude-messages.ts +6 -4
  383. package/src/server/codex-model-list.ts +2 -1
  384. package/src/server/configured-credentials.ts +37 -5
  385. package/src/server/gui-desktop-authorization.ts +36 -0
  386. package/src/server/gui-pair-delivery.ts +6 -3
  387. package/src/server/gui-session.ts +10 -1
  388. package/src/server/inbound-body-admission.ts +17 -4
  389. package/src/server/index/link-listener.ts +190 -12
  390. package/src/server/index/link-management.ts +15 -1
  391. package/src/server/index/link-relay-sessions.ts +87 -8
  392. package/src/server/index/link-websocket-limits.ts +136 -0
  393. package/src/server/index/link-websocket.ts +692 -0
  394. package/src/server/index/optional-listeners.ts +97 -7
  395. package/src/server/index/route-intent-watch.ts +47 -0
  396. package/src/server/index/serve-contract.ts +86 -0
  397. package/src/server/index/serve-options.ts +35 -86
  398. package/src/server/index/startup-warnings.ts +8 -2
  399. package/src/server/index/websocket-handler.ts +26 -4
  400. package/src/server/index.ts +12 -2
  401. package/src/server/inference/client-encoder-delivery.ts +2 -0
  402. package/src/server/inspection-tee.ts +39 -2
  403. package/src/server/lifecycle.ts +2 -0
  404. package/src/server/link-turn.ts +137 -0
  405. package/src/server/management/advisor-routes.ts +10 -2
  406. package/src/server/management/agent-settings-routes.ts +50 -16
  407. package/src/server/management/anthropic-reset-grant-routes.ts +1 -1
  408. package/src/server/management/context.ts +9 -2
  409. package/src/server/management/desktop-authorization.ts +41 -0
  410. package/src/server/management/desktop-compatibility-routes.ts +9 -8
  411. package/src/server/management/desktop-compatibility-runtime-routes.ts +3 -2
  412. package/src/server/management/desktop-compatibility-settings-routes.ts +5 -3
  413. package/src/server/management/home-integration-decision.ts +89 -0
  414. package/src/server/management/integration-routes.ts +208 -81
  415. package/src/server/management/link-child-ops-routes.ts +145 -43
  416. package/src/server/management/link-child-preflight.ts +31 -0
  417. package/src/server/management/link-diagnostics-route.ts +29 -0
  418. package/src/server/management/link-enrollment.ts +199 -47
  419. package/src/server/management/link-operation.ts +609 -0
  420. package/src/server/management/link-recover-route.ts +103 -0
  421. package/src/server/management/link-route-edit.ts +173 -0
  422. package/src/server/management/link-route-request.ts +62 -0
  423. package/src/server/management/link-route-state.ts +83 -7
  424. package/src/server/management/link-routes.ts +553 -51
  425. package/src/server/management/link-traffic-status.ts +13 -0
  426. package/src/server/management/model-routes.ts +122 -36
  427. package/src/server/management/model-rows.ts +2 -1
  428. package/src/server/management/native-integration-routes.ts +176 -70
  429. package/src/server/management/oauth-account-routes.ts +36 -13
  430. package/src/server/management/protocol-routes.ts +7 -0
  431. package/src/server/management/provider-completion-test.ts +4 -4
  432. package/src/server/management/provider-overwrite-carry.ts +11 -0
  433. package/src/server/management/provider-routes.ts +64 -61
  434. package/src/server/management/provider-routing-quota.ts +45 -0
  435. package/src/server/management/route-registry.ts +22 -3
  436. package/src/server/management/route-to-routes.ts +257 -0
  437. package/src/server/management/system-restart.ts +4 -2
  438. package/src/server/management/usage-aggregate-cache.ts +101 -66
  439. package/src/server/management-api.ts +17 -3
  440. package/src/server/management-auth.ts +13 -1
  441. package/src/server/messages-native-preflight.ts +27 -4
  442. package/src/server/messages-native.ts +17 -5
  443. package/src/server/persistent-gui-session.ts +6 -3
  444. package/src/server/proxy-liveness.ts +33 -6
  445. package/src/server/relay-eager.ts +36 -12
  446. package/src/server/relay.ts +183 -116
  447. package/src/server/request-body-facts.ts +48 -0
  448. package/src/server/request-decompress.ts +65 -2
  449. package/src/server/request-log-account-rotation.ts +6 -0
  450. package/src/server/request-log-attempt-usage.ts +69 -0
  451. package/src/server/request-log-cache-affinity.ts +60 -0
  452. package/src/server/request-log-conversation.ts +45 -2
  453. package/src/server/request-log-terminal-status.ts +210 -24
  454. package/src/server/request-log.ts +71 -79
  455. package/src/server/responses/adapter-continuation.ts +2 -1
  456. package/src/server/responses/adapter-delivery.ts +2 -0
  457. package/src/server/responses/adapter-dispatch.ts +5 -7
  458. package/src/server/responses/advisor-plan-slot.ts +33 -1
  459. package/src/server/responses/advisor-question.ts +21 -0
  460. package/src/server/responses/advisor-slot.ts +10 -3
  461. package/src/server/responses/bare-namespace-aliases.ts +18 -0
  462. package/src/server/responses/buffered-sse-json.ts +9 -3
  463. package/src/server/responses/code-mode-collab-surface.ts +11 -0
  464. package/src/server/responses/codex-tool-catalog.ts +156 -0
  465. package/src/server/responses/combo-required-tool-fulfillments.ts +4 -2
  466. package/src/server/responses/combo-stream-preflight.ts +557 -54
  467. package/src/server/responses/compact.ts +32 -8
  468. package/src/server/responses/core-codex-account.ts +17 -3
  469. package/src/server/responses/core-combo-failure.ts +8 -0
  470. package/src/server/responses/core-combo.ts +32 -4
  471. package/src/server/responses/core-errors.ts +5 -2
  472. package/src/server/responses/core-lifetime.ts +3 -2
  473. package/src/server/responses/core-normalize.ts +3 -1
  474. package/src/server/responses/core-options.ts +6 -0
  475. package/src/server/responses/core.ts +2 -0
  476. package/src/server/responses/fetch-helpers.ts +15 -10
  477. package/src/server/responses/native-replay-guard.ts +57 -0
  478. package/src/server/responses/opengateway-completion-guard.ts +10 -4
  479. package/src/server/responses/outbound-request-body.ts +29 -0
  480. package/src/server/responses/passthrough-completion.ts +105 -8
  481. package/src/server/responses/passthrough-delivery.ts +31 -11
  482. package/src/server/responses/passthrough-dispatch.ts +74 -73
  483. package/src/server/responses/policy-fallback.ts +13 -1
  484. package/src/server/responses/request-prepare.ts +50 -6
  485. package/src/server/responses/request-transport.ts +10 -3
  486. package/src/server/responses/reset-replay.ts +46 -2
  487. package/src/server/responses/run-turn-execution.ts +2 -0
  488. package/src/server/responses/sidecar-execution.ts +14 -0
  489. package/src/server/responses/terminal-error-redaction.ts +222 -25
  490. package/src/server/responses/ws-upstream.ts +2 -2
  491. package/src/server/sse-payload-rewrite.ts +3 -2
  492. package/src/server/stop-service-route.ts +85 -0
  493. package/src/server/system-env-shell.ts +12 -1
  494. package/src/server/system-env.ts +5 -3
  495. package/src/server/windows-tcp-drop.ts +21 -4
  496. package/src/server/workflow-refusal.ts +8 -0
  497. package/src/server/ws-bridge.ts +191 -12
  498. package/src/service/cli-windows-stop.ts +189 -0
  499. package/src/service/cli.ts +41 -12
  500. package/src/service/disconnected-client-restart.ts +60 -0
  501. package/src/service/guarded-manager-target.ts +18 -1
  502. package/src/service/health.ts +99 -6
  503. package/src/service/launchd.ts +84 -31
  504. package/src/service/orchestration.ts +418 -91
  505. package/src/service/repair.ts +223 -6
  506. package/src/service/restart-proxy-stop.ts +79 -0
  507. package/src/service/service-child-ownership.ts +6 -2
  508. package/src/service/windows-checked-stop-live.ts +467 -0
  509. package/src/service/windows-checked-stop.ts +435 -0
  510. package/src/service/windows-command-line-token.ts +23 -0
  511. package/src/service/windows-guarded-manager.ts +77 -34
  512. package/src/service/windows-ops.ts +38 -56
  513. package/src/service/windows-process-evidence.ts +292 -0
  514. package/src/service/windows-process-native.ts +262 -0
  515. package/src/service/windows-service-stop.ts +321 -0
  516. package/src/service/windows-stop-binding.ts +187 -0
  517. package/src/service/windows-stop-budget.ts +123 -0
  518. package/src/service/windows-stop-confirm.ts +158 -0
  519. package/src/service/windows-stop-deadline.ts +56 -0
  520. package/src/service.ts +2 -2
  521. package/src/types/config.ts +42 -18
  522. package/src/types/link.ts +20 -0
  523. package/src/types/multi-agent.ts +13 -0
  524. package/src/types/provider.ts +47 -2
  525. package/src/types/request.ts +4 -0
  526. package/src/types.ts +3 -0
  527. package/src/update/guarded-runtime-ops.ts +5 -7
  528. package/src/update/index.ts +25 -10
  529. package/src/update/install-detection.mjs +3 -1
  530. package/src/update/job-pinned-start.ts +2 -0
  531. package/src/update/job-windows-restart.ts +19 -32
  532. package/src/update/job.ts +12 -5
  533. package/src/update/npm-install.d.mts +11 -0
  534. package/src/update/npm-install.mjs +44 -7
  535. package/src/update/orchestrated-entry.ts +1 -1
  536. package/src/update/orchestrated-node-driver.mjs +3 -2
  537. package/src/update/orchestrated-pnpm.d.mts +4 -0
  538. package/src/update/orchestrated-pnpm.mjs +50 -6
  539. package/src/update/orchestrated-session.d.mts +3 -1
  540. package/src/update/orchestrated-session.mjs +21 -6
  541. package/src/update/pnpm-global-install.d.mts +21 -3
  542. package/src/update/pnpm-global-install.mjs +322 -19
  543. package/src/update/pnpm-store-layout.mjs +46 -0
  544. package/src/update/sync-update-mutex.d.mts +3 -2
  545. package/src/update/sync-update-mutex.mjs +57 -8
  546. package/src/update/transactional-install.d.mts +3 -1
  547. package/src/update/transactional-install.mjs +545 -12
  548. package/src/update/windows-installer-marker.d.mts +1 -0
  549. package/src/update/windows-installer-marker.mjs +44 -0
  550. package/src/usage/expected-prices.ts +8 -0
  551. package/src/usage/filter-index.ts +326 -77
  552. package/src/usage/ledger-scanner.ts +15 -0
  553. package/src/usage/link-log-fields.ts +48 -0
  554. package/src/usage/log.ts +43 -2
  555. package/src/usage/request-body.ts +37 -0
  556. package/src/web-search/loop.ts +3 -0
  557. package/gui/dist/assets/App-BpJOzw4F.js +0 -59
  558. package/gui/dist/assets/index-Bbor_y80.js +0 -94
  559. package/gui/dist/classic/assets/App-BrIlUiLc.js +0 -58
  560. package/gui/dist/classic/assets/index-DyJHagvT.js +0 -94
  561. package/src/server/management/desktop-compatibility-authorization.ts +0 -12
@@ -0,0 +1,319 @@
1
+ import { buildExecArgv, LinkSshArgumentError, remotePinnedSyncArgv } from "./ssh-argv";
2
+ import { classifyUpdateApply, remoteUpdateApplyArgv } from "./child-gated-ocx";
3
+ import { requireRemotePlatform } from "./remote-platform";
4
+ import { SshRunnerError, type SshRunResult } from "./ssh-runner";
5
+ import { classifySyncResult, childSkipHint } from "./sync-fanout-classify";
6
+ import { parseStrictSemver } from "../lib/strict-semver";
7
+ import type { LinkRecord } from "./store";
8
+ import { RESTART_SKIPPED, type ChildJob, type ChildJobItem, type ChildOpsEnv, type ChildRestart, type ItemOutcome,
9
+ type ItemRunner } from "./child-ops-types";
10
+ import { withoutCarriedFields } from "./child-observations";
11
+ import { pinnedSyncRanNothing, RESTART_RESULT_UNKNOWN, syncThenRestart } from "./sync-then-restart";
12
+
13
+ export const SYNC_TIMEOUT_MS = 180_000;
14
+ /** The --not-after window, counted on the Child's clock from the plan probe (M9). */
15
+ export const APPLY_NOT_AFTER_MS = 120_000;
16
+ /** Less than this left of the window when the apply would be sent ⇒ do not send; the next run re-plans. */
17
+ export const APPLY_MIN_REMAINING_MS = 15_000;
18
+ export const APPLY_GRACE_MS = 120_000;
19
+ /**
20
+ * The documented bound of an orchestrated apply (ORCHESTRATED_MUTATION_BOUND_MS on the Child). A Child that reports a
21
+ * larger mutationBoundMs (its contract allows up to an hour) cannot hold the engine's single update place longer.
22
+ */
23
+ export const APPLY_MUTATION_BOUND_MAX_MS = 900_000;
24
+ export const POST_UPDATE_SYNC_RETRY_MS = 30_000;
25
+ /** Revision 4: how long an uncertain update stays recorded for recovery (070 imports it from here). */
26
+ export const UNCERTAIN_RECOVERY_WINDOW_MS = 3_600_000;
27
+ const iso = (ms: number): string => new Date(ms).toISOString();
28
+ type Platform = "posix" | "windows";
29
+ type SyncResult = NonNullable<ChildJobItem["sync"]>;
30
+ type RestartReport = NonNullable<ChildJobItem["restart"]>;
31
+ /** A pinned sync's verdict plus whether it certainly ran nothing on the Child (Revision 6 F2). */
32
+ interface PinnedSyncRun { sync: SyncResult; notRun: boolean }
33
+
34
+ function unreachable(record: LinkRecord, env: ChildOpsEnv): ItemOutcome | null {
35
+ const wire = env.wireState(record.id);
36
+ if (wire === null) return { state: "offline", reason: "link-not-in-runtime" };
37
+ return wire === "connected" ? null : { state: "offline", reason: `tunnel-${wire}` };
38
+ }
39
+
40
+ async function platformOf(record: LinkRecord, env: ChildOpsEnv): Promise<Platform | ItemOutcome> {
41
+ if (record.remotePlatform) return record.remotePlatform;
42
+ try { return await requireRemotePlatform(env.runner, record.alias, record.explicitRoute ?? null, env.knownHostsFile); }
43
+ catch (error) {
44
+ return error instanceof SshRunnerError && error.code === "timeout"
45
+ ? { state: "offline", reason: "ssh-timeout" } : { state: "failed", reason: "platform-probe-failed" };
46
+ }
47
+ }
48
+
49
+ /** A2 / M8: read when the item runs, not when the job was queued. Unknown activity counts as in flight (020). */
50
+ function linkBusy(record: LinkRecord, env: ChildOpsEnv): boolean {
51
+ return (env.activity(record.id)?.inFlight ?? 1) > 0;
52
+ }
53
+
54
+ /**
55
+ * D8: the operator's explicit restart past activity (--ignore-activity): a manual job only, never an automatic one.
56
+ * It overrides the activity gate alone; platform, Child kind and sync refusals still apply. Logged with counts only.
57
+ */
58
+ function ignoresActivity(record: LinkRecord, job: Readonly<Pick<ChildJob, "trigger" | "ignoreActivity">>, env: ChildOpsEnv): boolean {
59
+ if (job.ignoreActivity !== true || job.trigger !== "manual") return false;
60
+ const inFlight = env.activity(record.id)?.inFlight;
61
+ console.log(`[link] restart past activity by the operator linkId=${record.id} inFlight=${inFlight ?? "unknown"}`);
62
+ return true;
63
+ }
64
+
65
+ /**
66
+ * Item hints never embed the SSH alias (up to 253 characters, and already on the item as alias), so each one is a
67
+ * bounded sentence under the job document's 256-character string limit and is never cut by the engine's cap.
68
+ */
69
+ export const HINT_SUBJECT = "this Child";
70
+ /** A4 owner action: the npm or pnpm launcher route needs a Node the Child's SSH session can find. */
71
+ export const LAUNCHER_HINT = "Install Node.js where the npm or pnpm that installed OpenCodex on this Child can find it, or update there with ocx update.";
72
+ export const CLOCK_SKEW_HINT = "The clocks of this Home and this Child differ (clock-skew); correct the Child's clock or run the update again.";
73
+ export function syncSkipHint(reason: string | null): string {
74
+ return childSkipHint(reason, HINT_SUBJECT);
75
+ }
76
+ /** Revision 4 (4529522006): the update stands, but routing may be gone. linkId is always lnk_ plus 16 hex. */
77
+ export function postUpdateSyncHint(linkId: string): string {
78
+ return `The update stands, but routing may be gone; run ocx link sync --link-id ${linkId} to restore it.`;
79
+ }
80
+
81
+ async function runPinnedSync(record: LinkRecord, platform: Platform, restart: ChildRestart, env: ChildOpsEnv): Promise<PinnedSyncRun> {
82
+ let argv: string[];
83
+ try {
84
+ argv = buildExecArgv({ alias: record.alias, knownHostsFile: env.knownHostsFile, route: record.explicitRoute ?? null,
85
+ argv: remotePinnedSyncArgv(record.id, platform, restart === "none" ? {} : { restart }) });
86
+ } catch (error) {
87
+ if (error instanceof LinkSshArgumentError) return { sync: { state: "failed", reason: "ssh-argument-invalid" }, notRun: true };
88
+ throw error;
89
+ }
90
+ // Revision 4 (4529521968): read the etag before the sync. If the catalog changes during the sync, the recorded etag
91
+ // is the older one, so the fan-out sees the Child as behind and syncs again; it is never credited with a newer one.
92
+ const etag = env.catalogEtag();
93
+ let result: SshRunResult;
94
+ try {
95
+ result = await env.runner.run(argv, { timeoutMs: SYNC_TIMEOUT_MS });
96
+ } catch (error) {
97
+ // A spawn failure sent nothing; a timeout, an output limit or a decode failure may follow a run.
98
+ return { sync: error instanceof SshRunnerError && error.code === "timeout"
99
+ ? { state: "timed-out", reason: "deadline-exceeded" } : { state: "failed", reason: "ssh-runner-failed" },
100
+ notRun: error instanceof SshRunnerError && error.code === "spawn" };
101
+ }
102
+ // wp1's classifier reads the selected-kind marker only when asked, and remotePinnedSyncArgv prints it only for a
103
+ // restarting sync; without the option executable is never set.
104
+ const sync: SyncResult = classifySyncResult(result, { expectSelectedKind: restart !== "none" });
105
+ // Only a synced Home-run sync proves the Child applied the catalog; a GET of /v1/catalog proves only a fetch.
106
+ if (sync.state === "synced" && etag !== null) env.writeObservation(record.id, { catalogSyncedEtag: etag });
107
+ return { sync, notRun: pinnedSyncRanNothing(sync, result) };
108
+ }
109
+
110
+ /** The pinned sync --expect-link of one Child, with an optional restart flag (D13). */
111
+ export async function pinnedSync(record: LinkRecord, platform: Platform, restart: ChildRestart, env: ChildOpsEnv): Promise<SyncResult> {
112
+ return (await runPinnedSync(record, platform, restart, env)).sync;
113
+ }
114
+
115
+ /**
116
+ * The pinned sync with an optional restart that obeys A2: unsupported where it cannot run, withheld while busy. The
117
+ * sequence lives in sync-then-restart.ts, shared with ocx sync --restart-children.
118
+ */
119
+ async function syncWithRestart(record: LinkRecord, platform: Platform, requested: ChildRestart,
120
+ env: ChildOpsEnv, idleGate?: { idleAtStart: boolean }, ignoreActivity = false): Promise<{ sync: SyncResult; restart?: RestartReport; restartUnknown?: true }> {
121
+ const { sync, restart, restartUnknown } = await syncThenRestart({ requested, platform, childKind: record.childKind,
122
+ runPinned: next => runPinnedSync(record, platform, next, env),
123
+ // linkBusy's rule: unknown (null) counts as in flight. An automatic restart (050 Revision 6) also needs the idle
124
+ // window, both when its item started and just before the restart goes out; a link short of it reads as active.
125
+ // The operator's explicit override (manual only) reads as idle.
126
+ readActivity: async () => {
127
+ if (ignoreActivity) return { inFlight: 0 };
128
+ const activity = env.activity(record.id);
129
+ if (!idleGate || activity === null) return activity;
130
+ return idleGate.idleAtStart && activity.idle ? activity : { inFlight: Math.max(1, activity.inFlight) };
131
+ } });
132
+ return { sync, ...(restart ? { restart } : {}), ...(restartUnknown ? { restartUnknown } : {}) };
133
+ }
134
+
135
+ export function syncOutcome(sync: SyncResult): ItemOutcome {
136
+ if (sync.state === "synced") return { state: "succeeded", reason: null, sync };
137
+ if (sync.state === "timed-out") return { state: "uncertain", reason: "deadline-exceeded", sync };
138
+ if (sync.state === "skipped") {
139
+ const reason = sync.reason ?? "child-sync-skipped";
140
+ const hint = syncSkipHint(reason);
141
+ if (reason === "child-updating") return { state: "busy", reason, hint, sync };
142
+ if (reason === "child-ocx-lacks-expect-link") return { state: "owner-action", reason, hint, sync };
143
+ if (reason === "child-platform-unsupported") return { state: "unsupported", reason, hint, sync };
144
+ return { state: "refused", reason, hint, sync }; // child-link-mismatch:*, version unknown
145
+ }
146
+ return sync.reason === "ssh-failed" ? { state: "offline", reason: "ssh-failed", sync }
147
+ : { state: "failed", reason: sync.reason ?? "child-sync-failed", sync };
148
+ }
149
+
150
+ /** wp2's observe dispatch as a runner: fresh fields only, so every carried field survives. */
151
+ export const runObserveItem: ItemRunner = async (record, _job, env) => {
152
+ let outcome: Awaited<ReturnType<ChildOpsEnv["observe"]>>;
153
+ // wp2 reports a throwing observe as failed/observe-error, not the engine's internal-error; keep that reason.
154
+ try { outcome = await env.observe(record); } catch (error) {
155
+ console.warn(`[link] child observe failed linkId=${record.id} error=${error instanceof Error ? error.name : "unknown"}`);
156
+ return { state: "failed", reason: "observe-error" };
157
+ }
158
+ // Revision 4: every carried field (010 CARRIED_OBSERVATION_FIELDS) survives, including the three revision 4 added.
159
+ if (outcome.observation) env.writeObservation(record.id, withoutCarriedFields(outcome.observation));
160
+ return { state: outcome.state, reason: outcome.reason };
161
+ };
162
+
163
+ export const runSyncItem: ItemRunner = async (record, job, env) => {
164
+ // 4529522063: the scheduler checked idle and the settings digest when it queued the job; the item may have waited
165
+ // behind other Children since. Re-ask at item start; a no answer is busy with no SSH, retried at the next poll.
166
+ if (job.trigger === "auto" && env.autoSyncAllowed?.(record.id) === false) return { state: "busy", reason: "link-active" };
167
+ // 050 Revision 6: an automatic job's restart was chosen for an idle link; it stands only if the link is still idle now.
168
+ const idleGate = job.trigger === "auto" && job.restart !== "none" ? { idleAtStart: env.activity(record.id)?.idle === true } : undefined;
169
+ const offline = unreachable(record, env);
170
+ if (offline) return offline;
171
+ const platform = await platformOf(record, env);
172
+ if (typeof platform !== "string") return platform;
173
+ const ignore = job.restart !== "none" && ignoresActivity(record, job, env);
174
+ const { sync, restart, restartUnknown } = await syncWithRestart(record, platform, job.restart, env, idleGate, ignore);
175
+ if (restartUnknown) return { state: "uncertain", reason: RESTART_RESULT_UNKNOWN, sync, restart };
176
+ const outcome = syncOutcome(sync);
177
+ if (restart) outcome.restart = restart;
178
+ // The sync is the job's purpose here; a withheld restart is reported, not a failure (A2).
179
+ if (restart?.outcome === "skipped" && outcome.state === "succeeded") outcome.reason = RESTART_SKIPPED;
180
+ return outcome;
181
+ };
182
+
183
+ export const runRestartCodexItem: ItemRunner = async (record, job, env) => {
184
+ const requested = job.restart === "codex" ? "codex" : "app-server";
185
+ const refused = (reason: string): ItemOutcome =>
186
+ ({ state: "unsupported", reason, restart: { requested, outcome: "unsupported" } });
187
+ if (record.remotePlatform === "windows") return refused("windows-restart"); // D20, no SSH at all
188
+ const offline = unreachable(record, env);
189
+ if (offline) return offline;
190
+ const platform = await platformOf(record, env);
191
+ if (typeof platform !== "string") return platform;
192
+ if (platform === "windows") return refused("windows-restart");
193
+ if (record.childKind === "ephemeral") {
194
+ // ocx-child accepts and ignores the restart flags (F2): sync without them, report unsupported.
195
+ const sync = await pinnedSync(record, platform, "none", env);
196
+ const outcome = syncOutcome(sync);
197
+ return outcome.state === "succeeded" ? { ...refused("ephemeral-restart"), sync } : { ...outcome, restart: { requested, outcome: "not-run" } };
198
+ }
199
+ // A2 / M8: the restart is the purpose of this op, so a busy link runs nothing (no SSH) and reports partial (exit 6).
200
+ const ignore = ignoresActivity(record, job, env);
201
+ if (!ignore && linkBusy(record, env)) return { state: "busy", reason: RESTART_SKIPPED, restart: { requested, outcome: "skipped" } };
202
+ // Revision 4: same two-step path as sync with a restart, so activity is read again just before the restart goes out.
203
+ const { sync, restart, restartUnknown } = await syncWithRestart(record, platform, requested, env, undefined, ignore);
204
+ if (restartUnknown) return { state: "uncertain", reason: RESTART_RESULT_UNKNOWN, sync, restart };
205
+ if (restart!.outcome === "unsupported") return syncOutcome(sync).state === "succeeded"
206
+ ? { ...refused("ephemeral-restart"), sync } : { ...syncOutcome(sync), restart: { requested, outcome: "not-run" } };
207
+ if (restart!.outcome === "skipped") return { state: "busy", reason: RESTART_SKIPPED, sync, restart };
208
+ return { ...syncOutcome(sync), restart };
209
+ };
210
+
211
+ export const runUpdateItem: ItemRunner = async (record, job, env) => {
212
+ if (record.childKind === "ephemeral") return { state: "unsupported", reason: "ephemeral" }; // D10
213
+ const offline = unreachable(record, env);
214
+ if (offline) return offline;
215
+ // Revision 4 (4529521925): bind the Child's identity before anything can mutate it. The pinned sync is the Child's own
216
+ // check (sync --expect-link, under its lifecycle lock): a Child that disconnected or linked to another Home answers
217
+ // child-link-mismatch:* and nothing below runs. It precedes the plan probe, so the probe's 120 s window is not spent
218
+ // on it; the gap left before apply is the probe itself (at most 60 s).
219
+ const identityPlatform = await platformOf(record, env);
220
+ if (typeof identityPlatform !== "string") return identityPlatform;
221
+ const identity = await pinnedSync(record, identityPlatform, "none", env);
222
+ if (identity.state !== "synced") return syncOutcome(identity);
223
+ // D3: a fresh plan every time. Windows Children are observed too: desktop-request is the one route they can take (H4, A5).
224
+ const observed = await env.observe(record);
225
+ if (observed.observation) env.writeObservation(record.id, withoutCarriedFields(observed.observation));
226
+ const probe = observed.probe;
227
+ // 4529522000: observe ends "succeeded" with probe null for a record without childKind whose Child runs ocx-child.
228
+ // Nothing was updated, so this is unsupported, never a success.
229
+ if (observed.state === "succeeded" && probe === null) return { state: "unsupported", reason: "ephemeral" };
230
+ if (observed.state !== "succeeded" || probe === null) return { state: observed.state, reason: observed.reason };
231
+ const plan = probe.classification;
232
+ const target = env.homeVersion;
233
+ const versions = { ...(plan.installedVersion ? { fromVersion: plan.installedVersion } : {}), toVersion: target };
234
+ if (plan.updateRoute === "none") return plan.updateReason === "up-to-date"
235
+ ? { state: "up-to-date", reason: null, ...(plan.installedVersion ? { fromVersion: plan.installedVersion, toVersion: plan.installedVersion } : {}) }
236
+ : { state: "refused", reason: plan.updateReason ?? "plan-unavailable", ...versions };
237
+ if (plan.updateRoute === "owner-action" || plan.updateRoute === "replant") return { state: "owner-action", reason: plan.updateReason,
238
+ ...(plan.updateReason === "launcher-node-missing" ? { hint: LAUNCHER_HINT } : {}), ...versions };
239
+ if (plan.updateInFlight) return { state: "busy", reason: "update-in-flight", ...versions };
240
+ const suppressed = env.readObservation(record.id)?.suppressedTarget ?? null;
241
+ if (job.trigger === "auto") {
242
+ if (suppressed === target) return { state: "refused", reason: "target-failed-before", ...versions };
243
+ if (env.activity(record.id)?.idle !== true) return { state: "busy", reason: "link-active", ...versions };
244
+ } else if (suppressed !== null) {
245
+ env.writeObservation(record.id, { suppressedTarget: null }); // a manual update clears it (D12 step 2)
246
+ }
247
+ // H4: the Desktop branch precedes the Windows refusal. 080 replaces this line with the Desktop request runner.
248
+ if (plan.updateRoute === "desktop-request") return { state: "owner-action", reason: "desktop-app", ...versions };
249
+ if (probe.platform === "windows") return { state: "unsupported", reason: "windows-apply", ...versions }; // D20
250
+ // updateRoute === "orchestrated" on POSIX.
251
+ // M9: --not-after is evaluated on the Child's clock. childNowMs was printed at the start of the plan probe, so the
252
+ // window counts from the plan; what is left of it is the window minus the Home's own elapsed time since the probe.
253
+ // Defensive (audit r2 R3): the 60 s probe bound and no queueing between observe and apply make it unreachable today.
254
+ const remaining = APPLY_NOT_AFTER_MS - (env.now() - probe.startedAt);
255
+ if (remaining < APPLY_MIN_REMAINING_MS) return { state: "busy", reason: "plan-expired", ...versions };
256
+ const homeClock = probe.childNowMs === null; // marker missing (should not happen): fall back to the Home clock
257
+ const notAfter = homeClock ? env.now() + remaining : probe.childNowMs! + APPLY_NOT_AFTER_MS;
258
+ const viaLauncher = plan.installKind === "npm" || plan.installKind === "pnpm"; // A4 (H2): apply only, npm/pnpm only
259
+ // F8: built before anything is sent, so a builder refusal is a plain failure with no recovery record.
260
+ let argv: string[];
261
+ try {
262
+ if (plan.planToken === null) throw new LinkSshArgumentError("invalid plan token");
263
+ argv = buildExecArgv({ alias: record.alias, knownHostsFile: env.knownHostsFile, route: record.explicitRoute ?? null,
264
+ argv: remoteUpdateApplyArgv({ homeVersion: target, planToken: plan.planToken, notAfter, viaLauncher }, "posix") });
265
+ } catch (error) {
266
+ if (error instanceof LinkSshArgumentError) return { state: "failed", reason: "ssh-argument-invalid", ...versions };
267
+ throw error;
268
+ }
269
+ let result: SshRunResult;
270
+ try {
271
+ result = await env.runner.run(argv, { timeoutMs: Math.min(plan.mutationBoundMs, APPLY_MUTATION_BOUND_MAX_MS) + APPLY_GRACE_MS });
272
+ } catch (error) {
273
+ // A spawn failure sent nothing to the Child (as for the sync path), so there is nothing to recover.
274
+ if (error instanceof SshRunnerError && error.code === "spawn") return { state: "failed", reason: "ssh-spawn-failed", ...versions };
275
+ // The Child's update keeps running or has finished; only a re-observe can tell (R2 hazard 4).
276
+ // Revision 4 (4529522112, 4529521944): recorded apart from lastOperation, which the next observe replaces; 070
277
+ // re-observes it, never re-applies, and resyncs once the Child reports no update in flight.
278
+ env.writeObservation(record.id, { pendingUpdateRecovery: { target, since: iso(env.now()),
279
+ until: iso(env.now() + UNCERTAIN_RECOVERY_WINDOW_MS) } });
280
+ return { state: "uncertain", reason: error instanceof SshRunnerError && error.code === "timeout"
281
+ ? "deadline-exceeded" : "ssh-runner-failed", ...versions };
282
+ }
283
+ const verdict = classifyUpdateApply(result);
284
+ if (verdict.suppressTarget) env.writeObservation(record.id, { suppressedTarget: target });
285
+ const verdictVersions = { ...versions, ...(verdict.fromVersion ? { fromVersion: verdict.fromVersion } : {}),
286
+ ...(verdict.toVersion ? { toVersion: verdict.toVersion } : {}) };
287
+ if (verdict.state === "refused" && verdict.reason === "deadline-passed") return { state: "refused", reason: "deadline-passed",
288
+ ...(homeClock ? { hint: CLOCK_SKEW_HINT } : {}),
289
+ ...verdictVersions };
290
+ if (verdict.state === "up-to-date") return { state: "up-to-date", reason: null, ...verdictVersions };
291
+ if (verdict.state === "owner-action" && verdict.reason === "launcher-node-missing") {
292
+ return { state: "owner-action", reason: verdict.reason, hint: LAUNCHER_HINT, ...verdictVersions };
293
+ }
294
+ if (verdict.state === "uncertain") env.writeObservation(record.id, { pendingUpdateRecovery: { target,
295
+ since: iso(env.now()), until: iso(env.now() + UNCERTAIN_RECOVERY_WINDOW_MS) } });
296
+ // 4529521944: a failed or rolled-back apply may already have stopped the proxy unsupervised, which removes routing.
297
+ // Resync without a restart; the verdict (and any suppressedTarget written above) stands, the sync is reported beside it.
298
+ if (verdict.state === "failed") return { state: "failed", reason: verdict.reason, ...verdictVersions,
299
+ sync: await pinnedSync(record, "posix", "none", env) };
300
+ if (verdict.state !== "succeeded") return { state: verdict.state, reason: verdict.reason, ...verdictVersions };
301
+ // Always resync: an unsupervised stop removed routing and start alone does not reapply it. The restart obeys A2.
302
+ let { sync, restart, restartUnknown } = await syncWithRestart(record, "posix", job.restart, env);
303
+ if (sync.state === "skipped" && sync.reason === "child-updating") {
304
+ await env.sleep(POST_UPDATE_SYNC_RETRY_MS);
305
+ ({ sync, restart, restartUnknown } = await syncWithRestart(record, "posix", job.restart, env));
306
+ }
307
+ // The Child's own result names the version it now runs; the Home target stands in when that is not a strict version.
308
+ const installed = verdict.toVersion && verdict.toVersion.length <= 128 && parseStrictSemver(verdict.toVersion) ? verdict.toVersion : target;
309
+ env.writeObservation(record.id, { installedVersion: installed, targetVersion: target, updateRoute: "none",
310
+ updateReason: "up-to-date", observedAt: iso(env.now()), source: "plan" });
311
+ const extra = { ...verdictVersions, sync, ...(restart ? { restart } : {}) };
312
+ // The update stands in every branch below; only what follows it is reported.
313
+ if (restartUnknown) return { state: "succeeded", reason: RESTART_RESULT_UNKNOWN, ...extra };
314
+ return sync.state === "synced"
315
+ ? { state: "succeeded", reason: restart?.outcome === "skipped" ? RESTART_SKIPPED : null, ...extra }
316
+ // Revision 4 (4529522006): the update stands, but routing may be gone; the CLI exits 6 for this reason (Section 3).
317
+ : { state: "succeeded", reason: "post-update-sync-failed",
318
+ hint: postUpdateSyncHint(record.id), ...extra };
319
+ };
@@ -0,0 +1,207 @@
1
+ import type { ChildOpsEngine } from "./child-ops-engine";
2
+ import type { ChildJob, ChildOpsEnv } from "./child-ops-types";
3
+ import type { ChildPolicyRead } from "./child-policy";
4
+
5
+ /**
6
+ * The Home's automatic catalog fan-out (050): after a Home catalog change settles, one no-restart sync job per pass for
7
+ * every eligible Child through the shared Child-ops engine. Timers come from the host (unref'd); this module starts
8
+ * none of its own, and nothing loads it on a Home without links (INV-LINK-CHILD-OPS-01).
9
+ */
10
+ export const QUIET_PERIOD_MS = 60_000;
11
+ export const QUIET_MAX_DEFER_MS = 300_000;
12
+ export const CATALOG_POLL_MS = 300_000;
13
+ export const BACKOFF_MIN_MS = 300_000;
14
+ export const BACKOFF_MAX_MS = 21_600_000;
15
+ /** States that grow the backoff for catalog fan-out; busy is retried at the next poll without growth. */
16
+ export const BACKOFF_STATES: ReadonlySet<string> = new Set(["failed", "offline", "uncertain", "refused", "unsupported"]);
17
+ export const CATALOG_BACKOFF_KEY = "catalog";
18
+
19
+ export interface LinkBackoff {
20
+ /** key: CATALOG_BACKOFF_KEY for fan-out; the target version for automatic updates (070). */
21
+ blocked(linkId: string, key: string, now: number, peerVersion: string | null): boolean;
22
+ record(linkId: string, key: string, outcome: { state: string; reason: string | null }, now: number, peerVersion: string | null): void;
23
+ /** Attempts recorded for (link, key) since its last success. 070 caps automatic update attempts with it. */
24
+ attempts(linkId: string, key: string): number;
25
+ /** Last attempt for the link under any key; 070 rotates candidates by it (least recent first). */
26
+ lastAttemptAt(linkId: string): number | null;
27
+ }
28
+ /** legacy: a Child below 2.93 (lacks --expect-link). legacyAtVersion null means its version was not known yet. */
29
+ interface BackoffEntry { until: number; delayMs: number; attempts: number; legacy: boolean; legacyAtVersion: string | null }
30
+
31
+ /** Per-link exponential backoff shared by the catalog fan-out (here) and the update sweep (070). Memory only. */
32
+ export function createLinkBackoff(options: { growOn?: ReadonlySet<string>; countOn?: ReadonlySet<string>; minMs?: number;
33
+ maxMs?: number } = {}): LinkBackoff {
34
+ const growOn = options.growOn ?? BACKOFF_STATES;
35
+ // Revision 4 (4529522103): only these states count toward attempts(); absent ⇒ every non-success outcome counts.
36
+ const countOn = options.countOn ?? null;
37
+ const minMs = options.minMs ?? BACKOFF_MIN_MS, maxMs = options.maxMs ?? BACKOFF_MAX_MS;
38
+ const entries = new Map<string, BackoffEntry>();
39
+ const last = new Map<string, number>();
40
+ const key = (linkId: string, name: string): string => `${linkId}\u0000${name}`;
41
+ return {
42
+ blocked(linkId, name, now, peerVersion) {
43
+ const entry = entries.get(key(linkId, name));
44
+ if (!entry) return false;
45
+ // A Child below 2.93 is retried only after it reports a different version (D6). Revision 4 (4529522058): with no
46
+ // version known at the time, any reported version, or the end of the maxMs backoff, allows one retry.
47
+ // #8557 review: once a version was recorded, a report without one is not "another version".
48
+ if (entry.legacy) return entry.legacyAtVersion !== null ? peerVersion === null || peerVersion === entry.legacyAtVersion
49
+ : peerVersion === null && now < entry.until;
50
+ return now < entry.until;
51
+ },
52
+ record(linkId, name, { state, reason }, now, peerVersion) {
53
+ last.set(linkId, now);
54
+ const k = key(linkId, name);
55
+ const previous = entries.get(k);
56
+ if (state === "succeeded" || state === "up-to-date") { entries.delete(k); return; }
57
+ const attempts = (previous?.attempts ?? 0) + (countOn === null || countOn.has(state) ? 1 : 0);
58
+ if (state === "owner-action" && reason === "child-ocx-lacks-expect-link") {
59
+ entries.set(k, { until: peerVersion === null ? now + maxMs : Number.POSITIVE_INFINITY, delayMs: maxMs, attempts,
60
+ legacy: true, legacyAtVersion: peerVersion });
61
+ return;
62
+ }
63
+ if (!growOn.has(state)) { entries.set(k, { until: now, delayMs: previous?.delayMs ?? 0, attempts, legacy: false, legacyAtVersion: null }); return; }
64
+ const delayMs = previous && previous.delayMs > 0 ? Math.min(previous.delayMs * 2, maxMs) : minMs;
65
+ entries.set(k, { until: now + delayMs, delayMs, attempts, legacy: false, legacyAtVersion: null });
66
+ },
67
+ attempts: (linkId, name) => entries.get(key(linkId, name))?.attempts ?? 0,
68
+ lastAttemptAt: linkId => last.get(linkId) ?? null,
69
+ };
70
+ }
71
+
72
+ export interface ChildOpsSchedulerDeps {
73
+ engine: ChildOpsEngine;
74
+ env: () => ChildOpsEnv;
75
+ readPolicy: () => ChildPolicyRead;
76
+ revision: { current(): { etag: string | null; changedAt: number | null }; recompute(): Promise<boolean> };
77
+ /** Revision 4 (4529521968): 030's catalogSyncedEtag; a GET of /v1/catalog does not count as delivered. */
78
+ syncedEtag: (linkId: string) => string | null;
79
+ /** codexSettingsDigest of the Home settings; null when they cannot be projected. */
80
+ homeDigest: () => string | null;
81
+ /** The Child's parity report appliedCodexSettingsDigest. */
82
+ childDigest: (linkId: string) => string | null;
83
+ /** The relay peer report's version. */
84
+ peerVersion: (linkId: string) => string | null;
85
+ /** 050 Revision 6: a runtime whose runtimeRole is client operates no Children. */
86
+ isClientRuntime: () => boolean;
87
+ setCatalogChangedSlot: (fanout: (() => void) | null) => void;
88
+ setTimeout: (fn: () => void, ms: number) => unknown;
89
+ clearTimeout: (handle: unknown) => void;
90
+ setInterval: (fn: () => void, ms: number) => unknown;
91
+ clearInterval: (handle: unknown) => void;
92
+ /** Extension point for wp7; called once per poll after the catalog pass. Unset in wp5. */
93
+ afterPoll?: () => Promise<void>;
94
+ }
95
+
96
+ export interface ChildOpsScheduler {
97
+ start(): void;
98
+ stop(): void;
99
+ notifyCatalogChanged(): void;
100
+ /** Test seam: run one evaluation now and wait for the jobs it submitted. */
101
+ evaluateForTest(): Promise<ChildJob[]>;
102
+ }
103
+
104
+ export function createChildOpsScheduler(deps: ChildOpsSchedulerDeps): ChildOpsScheduler {
105
+ const backoff = createLinkBackoff();
106
+ let quiet: unknown = null;
107
+ let firstChangeAt: number | null = null;
108
+ let poll: unknown = null;
109
+ let running = false;
110
+ let rerun = false;
111
+ let stopped = true;
112
+
113
+ // Etag equality, never time order (4529521959); an unreadable Home catalog makes no Child behind.
114
+ const behind = (linkId: string): boolean => {
115
+ const etag = deps.revision.current().etag;
116
+ return etag !== null && deps.syncedEtag(linkId) !== etag;
117
+ };
118
+
119
+ const record = (job: ChildJob, now: number): void => {
120
+ for (const item of job.items) backoff.record(item.linkId, CATALOG_BACKOFF_KEY, item, now, deps.peerVersion(item.linkId));
121
+ };
122
+
123
+ const evaluate = async (): Promise<ChildJob[]> => {
124
+ if (stopped || deps.isClientRuntime()) return [];
125
+ // 050 Revision 6: a quiet timer that fires during a pass is not lost; the pass evaluates once more when it ends.
126
+ if (running) { rerun = true; return []; }
127
+ const { policy } = deps.readPolicy();
128
+ if (policy.catalogFanout !== "auto") return [];
129
+ running = true;
130
+ try {
131
+ const env = deps.env();
132
+ const now = env.now();
133
+ const homeDigest = deps.homeDigest();
134
+ const plain: string[] = [];
135
+ const withRestart: string[] = [];
136
+ for (const link of env.readStore().links) {
137
+ if (link.direction !== "hub-initiated" || env.wireState(link.id) !== "connected") continue;
138
+ if (deps.engine.activeJob(link.id) || backoff.blocked(link.id, CATALOG_BACKOFF_KEY, now, deps.peerVersion(link.id)) || !behind(link.id)) continue;
139
+ const idle = env.activity(link.id)?.idle === true;
140
+ const sameSettings = homeDigest !== null && deps.childDigest(link.id) === homeDigest;
141
+ // Digest rule (D6): a sync that applies changed settings restarts the Child's client runtime and cuts relayed
142
+ // streams, so a busy Child is synced only when its settings already match.
143
+ if (!idle && !sameSettings) continue;
144
+ (idle && policy.childCodexRestart === "app-server-when-idle" ? withRestart : plain).push(link.id);
145
+ }
146
+ const jobs: ChildJob[] = [];
147
+ for (const [ids, restart] of [[plain, "none"], [withRestart, "app-server"]] as const) {
148
+ if (ids.length === 0) continue;
149
+ // #8557 review: the first group's job can run for minutes. A stop() (listener closed, shutdown) or a policy
150
+ // change in that time governs the next group, which is admitted against the policy as it is now.
151
+ const current = deps.readPolicy().policy;
152
+ if (stopped || deps.isClientRuntime() || current.catalogFanout !== "auto") break;
153
+ const restartNow = restart === "app-server" && current.childCodexRestart === "app-server-when-idle" ? "app-server" : "none";
154
+ // submit reads links.json and can throw (the POST route maps that to 503); the next poll retries.
155
+ let result: ReturnType<ChildOpsEngine["submit"]>;
156
+ try { result = deps.engine.submit({ op: "sync", linkIds: [...ids], restart: restartNow, trigger: "auto" }, env); } catch { continue; }
157
+ if (!result.ok) continue; // a single-link list held by a job or a reserve() answers link_operation_in_progress
158
+ const done = await deps.engine.whenDone(result.job.jobId);
159
+ if (done) { record(done, env.now()); jobs.push(done); }
160
+ }
161
+ return jobs;
162
+ } finally {
163
+ running = false;
164
+ if (rerun) { rerun = false; if (!stopped) void evaluate().catch(() => []); }
165
+ }
166
+ };
167
+
168
+ const armQuiet = (): void => {
169
+ if (stopped) return;
170
+ const now = deps.env().now();
171
+ firstChangeAt ??= now;
172
+ if (quiet !== null) deps.clearTimeout(quiet);
173
+ const wait = Math.min(QUIET_PERIOD_MS, Math.max(0, firstChangeAt + QUIET_MAX_DEFER_MS - now));
174
+ quiet = deps.setTimeout(() => { quiet = null; firstChangeAt = null; void evaluate().catch(() => []); }, wait);
175
+ };
176
+
177
+ const onPoll = async (): Promise<void> => {
178
+ let changed = false;
179
+ try { changed = await deps.revision.recompute(); } catch { /* next poll */ }
180
+ if (changed) armQuiet();
181
+ else if (quiet === null) await evaluate().catch(() => []); // retries idle-blocked and backed-off links
182
+ await deps.afterPoll?.().catch(() => {});
183
+ };
184
+
185
+ return {
186
+ start() {
187
+ if (!stopped) return;
188
+ stopped = false;
189
+ deps.setCatalogChangedSlot(() => armQuiet());
190
+ poll = deps.setInterval(() => { void onPoll(); }, CATALOG_POLL_MS);
191
+ // A Home restarted after a change still owes its Children a sync.
192
+ void deps.revision.recompute().catch(() => false).then(() => armQuiet());
193
+ },
194
+ stop() {
195
+ if (stopped) return;
196
+ stopped = true;
197
+ deps.setCatalogChangedSlot(null);
198
+ if (quiet !== null) deps.clearTimeout(quiet);
199
+ if (poll !== null) deps.clearInterval(poll);
200
+ quiet = poll = null;
201
+ firstChangeAt = null;
202
+ rerun = false;
203
+ },
204
+ notifyCatalogChanged: armQuiet,
205
+ evaluateForTest: evaluate,
206
+ };
207
+ }
@@ -0,0 +1,89 @@
1
+ import type { LinkRecord, LinkStore } from "./store";
2
+ import type { SshRunner } from "./ssh-runner";
3
+ import type { LinkWireState } from "./status-projection";
4
+ import type { ChildObservation, ChildOp } from "./child-observations";
5
+ import type { ObserveOutcome } from "./child-observe";
6
+
7
+ /**
8
+ * The ocx.link.child-job/1 vocabulary (030 2.1). ChildOp is declared once, in child-observations.ts; the GUI keeps its
9
+ * own wire mirror. Item states and reasons are closed tokens produced by this Home, never remote text.
10
+ */
11
+ export type { ChildOp } from "./child-observations";
12
+ export const CHILD_JOB_SCHEMA = "ocx.link.child-job/1" as const;
13
+ export const CHILD_OPS = ["observe", "sync", "restart-codex", "update"] as const satisfies readonly ChildOp[];
14
+ /** The most link ids one operations request may name; the dashboard splits a larger bulk list into groups of this size. */
15
+ export const CHILD_OPS_MAX_LINK_IDS = 64;
16
+ export type ChildRestart = "none" | "app-server" | "codex";
17
+ export type ChildTrigger = "manual" | "auto";
18
+ export const CHILD_ITEM_STATES = ["queued", "running", "succeeded", "up-to-date", "busy", "offline",
19
+ "refused", "owner-action", "unsupported", "failed", "uncertain"] as const;
20
+ export type ChildItemState = typeof CHILD_ITEM_STATES[number];
21
+ /**
22
+ * requested: the restart went out (its effect is not confirmed). unsupported: Windows, ocx-child or an ephemeral Child.
23
+ * not-run: the sync before it did not reach synced, or the restarting call was refused before an ocx was selected.
24
+ * skipped: withheld because a relayed model request was in flight (A2, reason restart-skipped:link-active).
25
+ */
26
+ export type ChildRestartOutcome = "requested" | "unsupported" | "not-run" | "skipped";
27
+ export const RESTART_SKIPPED = "restart-skipped:link-active";
28
+
29
+ export interface ChildJobItem {
30
+ linkId: string;
31
+ alias: string;
32
+ state: ChildItemState;
33
+ /** Closed reason vocabulary (030 Section 4). Never remote output. */
34
+ reason: string | null;
35
+ hint?: string;
36
+ fromVersion?: string;
37
+ toVersion?: string;
38
+ /** executable: set only when 010's selected-kind marker reported ocx-child (Revision 4). */
39
+ sync?: { state: "synced" | "skipped" | "failed" | "timed-out"; reason: string | null; executable?: "ocx-child" };
40
+ restart?: { requested: "app-server" | "codex"; outcome: ChildRestartOutcome };
41
+ startedAt: string | null;
42
+ finishedAt: string | null;
43
+ }
44
+
45
+ export interface ChildJob {
46
+ schema: typeof CHILD_JOB_SCHEMA;
47
+ /** "ljob_" + 16 lowercase hex. */
48
+ jobId: string;
49
+ op: ChildOp;
50
+ trigger: ChildTrigger;
51
+ restart: ChildRestart;
52
+ /** D8: present only on a manual restart the operator sent past activity (--ignore-activity); never on an automatic job. */
53
+ ignoreActivity?: true;
54
+ state: "queued" | "running" | "done";
55
+ createdAt: string;
56
+ finishedAt: string | null;
57
+ items: ChildJobItem[];
58
+ }
59
+
60
+ export type ItemOutcome = Omit<ChildJobItem, "linkId" | "alias" | "startedAt" | "finishedAt">;
61
+
62
+ /** Everything an item needs from the Home process; built per submit by the route (030 2.4) or the wp5 host. */
63
+ export interface ChildOpsEnv {
64
+ readStore(): LinkStore;
65
+ runner: Pick<SshRunner, "run">;
66
+ knownHostsFile: string;
67
+ wireState(linkId: string): LinkWireState | null;
68
+ /** idle = isLinkIdle(snapshot, now, idleAfterMs); null when the listener has no activity book (never idle). */
69
+ activity(linkId: string): { idle: boolean; inFlight: number } | null;
70
+ homeVersion: string;
71
+ now(): number;
72
+ sleep(ms: number): Promise<void>;
73
+ /** observeChild(record, ObserveDeps) bound to this env's runner, known hosts, Home version and peer reports. */
74
+ observe(record: LinkRecord): Promise<ObserveOutcome>;
75
+ readObservation(linkId: string): ChildObservation | null;
76
+ /**
77
+ * updateChildObservations(file => patchChildObservation(file, linkId, patch, new Date(now()))). Never throws: the
78
+ * file is a cache and the job document already carries the result, so a failed write is logged by error name and
79
+ * dropped. Every runner relies on this contract.
80
+ */
81
+ writeObservation(linkId: string, patch: Partial<ChildObservation>): void;
82
+ /** Revision 4: the Home catalog etag now (020 monitor); a synced item records it as catalogSyncedEtag. */
83
+ catalogEtag(): string | null;
84
+ /** Revision 4: 050's host sets it for automatic jobs; a sync item re-asks it when the item starts. Absent ⇒ allowed. */
85
+ autoSyncAllowed?(linkId: string): boolean;
86
+ }
87
+
88
+ export type ItemRunner = (record: LinkRecord, job: Readonly<Pick<ChildJob, "op" | "trigger" | "restart" | "ignoreActivity">>,
89
+ env: ChildOpsEnv) => Promise<ItemOutcome>;