@bitkyc08/opencodex 2.91.0 → 2.93.0-preview.20261027

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (360) hide show
  1. package/bin/ocx.mjs +47 -8
  2. package/gui/dist/assets/App-CJZoq-uF.js +58 -0
  3. package/gui/dist/assets/{Tray-BuLy7hL1.js → Tray-BWQPcgZn.js} +1 -1
  4. package/gui/dist/assets/index-DRe8Hhfz.css +1 -0
  5. package/gui/dist/assets/index-Xfct8owH.js +94 -0
  6. package/gui/dist/assets/quota-summary-DxToX1rV.js +1 -0
  7. package/gui/dist/index.html +2 -2
  8. package/gui/dist/provider-icons/workbuddy-color.svg +29 -0
  9. package/package.json +8 -7
  10. package/src/adapters/anthropic.ts +28 -5
  11. package/src/adapters/coding-agent/batch-dispatcher.ts +122 -0
  12. package/src/adapters/coding-agent/profile.ts +54 -16
  13. package/src/adapters/coding-agent/turn.ts +30 -2
  14. package/src/adapters/command-code.ts +114 -7
  15. package/src/adapters/cursor/native-exec-fs.ts +11 -9
  16. package/src/adapters/devin/live-models.ts +4 -0
  17. package/src/adapters/google-vertex-endpoint.ts +9 -1
  18. package/src/adapters/google-vertex-key-project.ts +223 -0
  19. package/src/adapters/google-wire-compiler.ts +1 -2
  20. package/src/adapters/google.ts +13 -3
  21. package/src/adapters/kiro/reasoning.ts +2 -0
  22. package/src/adapters/kiro-refusal.ts +6 -1
  23. package/src/adapters/kiro-wire.ts +1 -1
  24. package/src/adapters/openai-chat/messages.ts +8 -2
  25. package/src/adapters/openai-chat/passthrough.ts +35 -14
  26. package/src/adapters/openai-chat/reasoning-replay.ts +27 -16
  27. package/src/adapters/openai-chat/reasoning-wire.ts +117 -8
  28. package/src/adapters/openai-chat/required-tool-result.ts +64 -0
  29. package/src/adapters/openai-chat/tool-name-registry.ts +3 -1
  30. package/src/adapters/openai-chat.ts +9 -10
  31. package/src/adapters/openai-responses/passthrough.ts +7 -4
  32. package/src/adapters/openai-responses/reasoning.ts +13 -0
  33. package/src/adapters/openai-responses/request-strips.ts +60 -0
  34. package/src/adapters/qoder/adapter.ts +129 -8
  35. package/src/adapters/qoder/scaffold-guard.ts +5 -0
  36. package/src/adapters/reasoning-controls.ts +16 -0
  37. package/src/adapters/registry.ts +5 -0
  38. package/src/adapters/tool-call-id.ts +1 -3
  39. package/src/adapters/workbuddy-schema.ts +61 -0
  40. package/src/adapters/workbuddy.ts +68 -0
  41. package/src/bridge/errors.ts +27 -0
  42. package/src/bridge/response-json.ts +1 -1
  43. package/src/bridge/sse.ts +1 -1
  44. package/src/bridge.ts +1 -1
  45. package/src/chat/inbound.ts +4 -1
  46. package/src/chat/outbound.ts +20 -6
  47. package/src/chat/reasoning-details.ts +28 -5
  48. package/src/claude/desktop-first-party.ts +54 -4
  49. package/src/claude/desktop-picker.ts +11 -8
  50. package/src/claude/first-party-settings.ts +3 -1
  51. package/src/claude/inbound.ts +2 -1
  52. package/src/claude/intercept/local-ca.ts +2 -1
  53. package/src/claude/intercept/picker-ca-cleanup.ts +4 -2
  54. package/src/claude/intercept/picker-ca-startup.ts +3 -1
  55. package/src/claude/intercept/picker-models.ts +6 -3
  56. package/src/claude/intercept/picker-runtime.ts +3 -2
  57. package/src/claude/intercept/runtime.ts +6 -3
  58. package/src/claude/model-info.ts +31 -8
  59. package/src/cli/account-api.ts +11 -0
  60. package/src/cli/capabilities-agents-routing.ts +3 -3
  61. package/src/cli/capabilities-base.ts +7 -1
  62. package/src/cli/capabilities-observe-system.ts +10 -0
  63. package/src/cli/claude-desktop.ts +9 -8
  64. package/src/cli/claude.ts +3 -2
  65. package/src/cli/codex-cli-update.ts +8 -0
  66. package/src/cli/codex-shim-autorestore.ts +9 -0
  67. package/src/cli/combo-result.ts +13 -0
  68. package/src/cli/combo-stats.ts +3 -0
  69. package/src/cli/combo.ts +83 -41
  70. package/src/cli/cross-home-owner.ts +13 -1
  71. package/src/cli/dispatch.ts +25 -6
  72. package/src/cli/ensure-desired-integrations.ts +8 -6
  73. package/src/cli/export-command.ts +4 -1
  74. package/src/cli/help.ts +2 -1
  75. package/src/cli/index.ts +45 -45
  76. package/src/cli/integration-plan-dto.ts +4 -0
  77. package/src/cli/launcher-context.ts +49 -2
  78. package/src/cli/link.ts +45 -32
  79. package/src/cli/opencode.ts +20 -9
  80. package/src/cli/provider.ts +2 -1
  81. package/src/cli/registry.ts +6 -4
  82. package/src/cli/root.ts +9 -0
  83. package/src/cli/status.ts +59 -1
  84. package/src/cli/stop-restore.ts +113 -0
  85. package/src/cli/sync-expectation.ts +60 -0
  86. package/src/cli/uninstall-integrations.ts +41 -7
  87. package/src/cli/usage-compare.ts +68 -12
  88. package/src/client/connect.ts +40 -3
  89. package/src/client/link-home.ts +10 -1
  90. package/src/client/link-ingress.ts +1 -1
  91. package/src/client/link-readiness.ts +97 -0
  92. package/src/client/link-relay-transport.ts +79 -11
  93. package/src/client/link-relay.ts +74 -15
  94. package/src/client/link-tunnel.ts +45 -18
  95. package/src/client/machine-api.ts +3 -1
  96. package/src/client/machine-listener.ts +20 -2
  97. package/src/client/runtime.ts +20 -2
  98. package/src/client/sync-expectation.ts +118 -0
  99. package/src/clients/config-export/agent-clients.ts +96 -0
  100. package/src/clients/config-export/contracts.ts +25 -7
  101. package/src/clients/config-export/qoder.ts +38 -23
  102. package/src/clients/config-export/reasoning-metadata.ts +55 -8
  103. package/src/clients/config-export.ts +12 -0
  104. package/src/clients/lazycodex.ts +7 -2
  105. package/src/clients/reasoning-controls.ts +49 -0
  106. package/src/codex/account-store.ts +17 -3
  107. package/src/codex/app-server-restart-service.ts +6 -5
  108. package/src/codex/auth-api/account-identity.ts +14 -0
  109. package/src/codex/auth-api/account-list.ts +29 -2
  110. package/src/codex/auth-api/http.ts +13 -0
  111. package/src/codex/auth-api/main-account-probe.ts +2 -2
  112. package/src/codex/auth-api/pool-mode-gate.ts +16 -3
  113. package/src/codex/auth-api/pool-quota-probe.ts +15 -0
  114. package/src/codex/auth-context.ts +15 -12
  115. package/src/codex/catalog/build-entries.ts +22 -0
  116. package/src/codex/catalog/configured-tiers.ts +70 -0
  117. package/src/codex/catalog/effort.ts +52 -11
  118. package/src/codex/catalog/gather-capture.ts +5 -2
  119. package/src/codex/catalog/heal-observation.ts +155 -13
  120. package/src/codex/catalog/metadata.ts +6 -0
  121. package/src/codex/catalog/model-hints.ts +60 -11
  122. package/src/codex/catalog/model-visibility.ts +3 -2
  123. package/src/codex/catalog/native-models.ts +18 -3
  124. package/src/codex/catalog/parsing.ts +10 -8
  125. package/src/codex/catalog/pinned-models.ts +2 -1
  126. package/src/codex/catalog/provider-models.ts +18 -13
  127. package/src/codex/catalog/retained-sync.ts +2 -1
  128. package/src/codex/catalog/routed-gather.ts +19 -20
  129. package/src/codex/catalog/write-audit.ts +3 -2
  130. package/src/codex/catalog-self-heal.ts +43 -23
  131. package/src/codex/chatgpt-refresh-failure.ts +6 -2
  132. package/src/codex/cli-install-provenance.ts +418 -0
  133. package/src/codex/cli-installation-targets.ts +5 -1
  134. package/src/codex/cli-update-plan.ts +43 -16
  135. package/src/codex/collision-identity.ts +30 -5
  136. package/src/codex/convergence.ts +4 -3
  137. package/src/codex/data/roster-pinned-models.json +177 -1
  138. package/src/codex/desired-state.ts +6 -1
  139. package/src/codex/desktop-app/picker-freshness.ts +10 -8
  140. package/src/codex/desktop-compatibility/installed-build.ts +88 -12
  141. package/src/codex/desktop-compatibility/runtime.ts +29 -5
  142. package/src/codex/desktop-compatibility/usage-activation.ts +2 -1
  143. package/src/codex/desktop-compatibility/usage-controller.ts +9 -1
  144. package/src/codex/desktop-compatibility/windows-certificate-trust.ts +46 -12
  145. package/src/codex/inject/config-toml.ts +0 -18
  146. package/src/codex/inject/plan.ts +18 -3
  147. package/src/codex/inject/remove.ts +6 -2
  148. package/src/codex/inject.ts +1 -1
  149. package/src/codex/journal.ts +61 -1
  150. package/src/codex/model-entitlements.ts +1 -1
  151. package/src/codex/native-main-owner.ts +27 -1
  152. package/src/codex/native-profile-store.ts +2 -1
  153. package/src/codex/pool-credit-policy.ts +35 -1
  154. package/src/codex/pool-refresh-backoff.ts +3 -1
  155. package/src/codex/quota-types.ts +3 -0
  156. package/src/codex/quota.ts +24 -4
  157. package/src/codex/role-auto-assign.ts +6 -2
  158. package/src/codex/subagent-defaults.ts +49 -4
  159. package/src/codex/user-identity.ts +35 -6
  160. package/src/codex/windows-current-sid.ts +162 -0
  161. package/src/combos/failover.ts +17 -2
  162. package/src/combos/jev-decision-contract.ts +22 -1
  163. package/src/combos/jev-quota-activation.ts +5 -1
  164. package/src/combos/jev-quota-route.ts +1 -1
  165. package/src/combos/jev-quota.ts +9 -1
  166. package/src/combos/jev-service-exchange.ts +3 -1
  167. package/src/combos/jev-session-pin-config.ts +51 -0
  168. package/src/combos/jev.ts +101 -9
  169. package/src/combos/resolve.ts +45 -1
  170. package/src/combos/types.ts +43 -0
  171. package/src/config/load-degrade.ts +5 -0
  172. package/src/config/paths.ts +19 -3
  173. package/src/config/pending-teardown.ts +22 -1
  174. package/src/config/provider-validation.ts +22 -4
  175. package/src/config/removed-opencode-free.ts +11 -0
  176. package/src/config/schema/leaf-validators.ts +6 -0
  177. package/src/generated/compatibility-version.json +467 -311
  178. package/src/generated/model-metadata.ts +5 -5
  179. package/src/images/loop.ts +16 -2
  180. package/src/integrations/catalog-refresh.ts +1 -1
  181. package/src/integrations/hermes-profiles.ts +251 -0
  182. package/src/integrations/merge.ts +8 -0
  183. package/src/integrations/mutation-plan.ts +19 -4
  184. package/src/integrations/registry.ts +5 -0
  185. package/src/integrations/state.ts +36 -1
  186. package/src/integrations/writer.ts +18 -4
  187. package/src/lib/bun-path-runtime.mjs +2 -1
  188. package/src/lib/decision-quota-sink.ts +10 -0
  189. package/src/lib/errors.ts +62 -0
  190. package/src/lib/eventstream-decoder.ts +81 -37
  191. package/src/lib/opaque-proxy-tunnel.ts +32 -8
  192. package/src/lib/pinned-http.ts +35 -2
  193. package/src/lib/process-control.ts +13 -1
  194. package/src/lib/socks5-fetch.ts +59 -64
  195. package/src/lib/socks5-upload-waiter.ts +50 -0
  196. package/src/lib/sse-decoder.ts +7 -2
  197. package/src/lib/state-store-sweeper.ts +40 -14
  198. package/src/lib/translator-budget.ts +4 -4
  199. package/src/lib/upstream-retry.ts +4 -1
  200. package/src/lib/windows-native-principal-worker.ts +14 -0
  201. package/src/lib/windows-native-principal.ts +188 -0
  202. package/src/lib/windows-secret-acl.ts +39 -3
  203. package/src/lib/windows-user-principal.ts +62 -18
  204. package/src/link/diagnostics.ts +193 -0
  205. package/src/link/relay-auth.ts +6 -0
  206. package/src/link/ssh-config.ts +35 -3
  207. package/src/link/status-projection.ts +39 -0
  208. package/src/link/supervisor.ts +45 -12
  209. package/src/link/tunnel-history.ts +109 -0
  210. package/src/link/tunnel-state.ts +80 -17
  211. package/src/messaging/remote-files.ts +24 -1
  212. package/src/oauth/generic-account-failover.ts +91 -7
  213. package/src/oauth/index.ts +15 -0
  214. package/src/oauth/model-discovery-auth.ts +5 -0
  215. package/src/oauth/store.ts +4 -1
  216. package/src/oauth/token-guardian.ts +7 -0
  217. package/src/oauth/types.ts +9 -0
  218. package/src/oauth/workbuddy.ts +139 -0
  219. package/src/providers/account-quota-disk.ts +12 -4
  220. package/src/providers/antigravity-quota-identity.ts +37 -0
  221. package/src/providers/base-url-choices.ts +8 -5
  222. package/src/providers/codebuddy-models.ts +6 -0
  223. package/src/providers/codex-capacity.ts +3 -1
  224. package/src/providers/derive.ts +51 -3
  225. package/src/providers/kiro-models.ts +3 -0
  226. package/src/providers/mimo-thinking.ts +12 -0
  227. package/src/providers/model-discovery.ts +2 -0
  228. package/src/providers/model-rename-fields.ts +2 -0
  229. package/src/providers/model-rename-migration.ts +10 -0
  230. package/src/providers/openai-sidecar-credit.ts +2 -2
  231. package/src/providers/quota/account-cache.ts +3 -2
  232. package/src/providers/quota/antigravity.ts +25 -14
  233. package/src/providers/quota/report-cache.ts +13 -4
  234. package/src/providers/quota/vendor-probes-key.ts +60 -0
  235. package/src/providers/quota/workbuddy.ts +83 -0
  236. package/src/providers/quota-decision-antigravity.ts +64 -0
  237. package/src/providers/quota-decision-publication.ts +11 -0
  238. package/src/providers/quota-decision-snapshot.ts +21 -4
  239. package/src/providers/quota-types.ts +2 -0
  240. package/src/providers/quota.ts +3 -1
  241. package/src/providers/reasoning-capabilities.ts +76 -0
  242. package/src/providers/registry/entries-core.ts +23 -12
  243. package/src/providers/registry/entries-extended.ts +83 -27
  244. package/src/providers/registry/model-ids.ts +5 -0
  245. package/src/providers/registry/model-seeds.ts +120 -56
  246. package/src/providers/registry/types.ts +29 -2
  247. package/src/providers/resolved-model-policy.ts +30 -10
  248. package/src/providers/routed-config.ts +24 -1
  249. package/src/providers/stale-model-roster-migration.ts +123 -18
  250. package/src/providers/workbuddy-credit-balance.ts +81 -0
  251. package/src/providers/workbuddy-models.ts +37 -0
  252. package/src/providers/workbuddy.ts +60 -0
  253. package/src/remote-control/workspace-pi-runtime.ts +11 -6
  254. package/src/responses/compaction-summary.ts +45 -0
  255. package/src/responses/muse-tool-name-alias.ts +1 -2
  256. package/src/responses/parser.ts +3 -2
  257. package/src/responses/reasoning-replay-cache.ts +18 -14
  258. package/src/responses/schema.ts +1 -0
  259. package/src/responses/thought-signature-replay.ts +10 -2
  260. package/src/router.ts +2 -0
  261. package/src/routing/analytics.ts +2 -3
  262. package/src/routing/capability.ts +8 -2
  263. package/src/routing/fallback-policy.ts +3 -3
  264. package/src/routing/history/ingest.ts +28 -3
  265. package/src/server/auth-cors.ts +4 -2
  266. package/src/server/chat-completions.ts +21 -1
  267. package/src/server/chat-native-eligibility.ts +7 -0
  268. package/src/server/chat-native-reasoning.ts +24 -7
  269. package/src/server/chat-native.ts +13 -2
  270. package/src/server/claude-messages.ts +3 -0
  271. package/src/server/direct-local-http.ts +5 -2
  272. package/src/server/effort-policy.ts +5 -1
  273. package/src/server/index/link-relay-sessions.ts +9 -5
  274. package/src/server/index/live-sideband.ts +18 -15
  275. package/src/server/index/optional-listeners.ts +4 -0
  276. package/src/server/index/serve-options.ts +5 -4
  277. package/src/server/local-management-read-client.ts +3 -1
  278. package/src/server/management/agent-settings-routes.ts +27 -15
  279. package/src/server/management/combo-routes.ts +14 -4
  280. package/src/server/management/config-routes.ts +2 -2
  281. package/src/server/management/decision-discovery.ts +12 -2
  282. package/src/server/management/hermes-profile-routes.ts +156 -0
  283. package/src/server/management/integration-routes.ts +85 -24
  284. package/src/server/management/link-routes.ts +5 -2
  285. package/src/server/management/model-routes.ts +2 -2
  286. package/src/server/management/model-row-export-metadata.ts +25 -6
  287. package/src/server/management/model-rows.ts +15 -20
  288. package/src/server/management/native-integration-routes.ts +11 -8
  289. package/src/server/management/provider-routes.ts +1 -1
  290. package/src/server/management/route-registry.ts +4 -0
  291. package/src/server/management-api.ts +5 -0
  292. package/src/server/models-capabilities.ts +21 -3
  293. package/src/server/port-reclaim.ts +51 -9
  294. package/src/server/request-log-conversation.ts +49 -0
  295. package/src/server/request-log.ts +2 -0
  296. package/src/server/responses/adapter-delivery.ts +11 -1
  297. package/src/server/responses/adapter-dispatch.ts +2 -2
  298. package/src/server/responses/anthropic-thinking-recovery.ts +1 -0
  299. package/src/server/responses/codex-ws-exchange.ts +39 -9
  300. package/src/server/responses/codex-ws-session.ts +38 -4
  301. package/src/server/responses/codex-ws-wire.ts +6 -1
  302. package/src/server/responses/combo-required-tool-contract.ts +103 -0
  303. package/src/server/responses/combo-stream-preflight.ts +8 -1
  304. package/src/server/responses/compact.ts +14 -5
  305. package/src/server/responses/context-overflow.ts +8 -1
  306. package/src/server/responses/core-combo-failure.ts +10 -0
  307. package/src/server/responses/core-combo.ts +74 -44
  308. package/src/server/responses/core-lifetime.ts +5 -2
  309. package/src/server/responses/core-normalize.ts +17 -4
  310. package/src/server/responses/core-opaque-recovery.ts +1 -0
  311. package/src/server/responses/core-options.ts +7 -0
  312. package/src/server/responses/core-replay.ts +2 -1
  313. package/src/server/responses/jev-combo-choice.ts +39 -0
  314. package/src/server/responses/jev-session-pin.ts +203 -0
  315. package/src/server/responses/main-hard-lock-routing.ts +60 -44
  316. package/src/server/responses/passthrough-delivery.ts +44 -2
  317. package/src/server/responses/policy-fallback.ts +6 -1
  318. package/src/server/responses/request-compression.ts +12 -7
  319. package/src/server/responses/request-prepare.ts +32 -7
  320. package/src/server/responses/request-sidecar-auth.ts +2 -0
  321. package/src/server/responses/request-transport.ts +25 -6
  322. package/src/server/responses/response-effects.ts +22 -10
  323. package/src/server/responses/run-turn-execution.ts +2 -4
  324. package/src/server/responses/sidecar-execution.ts +13 -7
  325. package/src/server/responses-phase-inference.ts +267 -0
  326. package/src/server/sse-payload-rewrite.ts +14 -1
  327. package/src/server/stop-teardown.ts +36 -1
  328. package/src/server/ws-bridge.ts +1 -1
  329. package/src/service/definition.ts +20 -8
  330. package/src/service/desktop-supervision.d.mts +7 -4
  331. package/src/service/desktop-supervision.mjs +90 -13
  332. package/src/service/ownership-mutation-lease.mjs +21 -7
  333. package/src/types/config.ts +14 -2
  334. package/src/types/provider.ts +29 -7
  335. package/src/types/request.ts +11 -0
  336. package/src/types/wire.ts +1 -0
  337. package/src/types.ts +1 -0
  338. package/src/update/bind-probe.ts +29 -0
  339. package/src/update/codex-cli-update-launch-policy.d.mts +9 -0
  340. package/src/update/codex-cli-update-launch-policy.mjs +30 -0
  341. package/src/update/job.ts +10 -29
  342. package/src/update/npm-install-job.ps1 +173 -0
  343. package/src/update/npm-install.mjs +70 -0
  344. package/src/update/stop-contract.d.mts +1 -0
  345. package/src/update/stop-contract.mjs +14 -0
  346. package/src/update/stop-decision.d.mts +1 -1
  347. package/src/update/stop-decision.mjs +13 -3
  348. package/src/update/teardown-handover.ts +166 -0
  349. package/src/update/transactional-install.d.mts +14 -3
  350. package/src/update/transactional-install.mjs +33 -7
  351. package/src/usage/expected-prices.ts +64 -31
  352. package/src/usage/jev-stats.ts +54 -14
  353. package/src/usage/timeline.ts +19 -9
  354. package/src/vision/eligibility.ts +15 -5
  355. package/src/vision/plan.ts +2 -2
  356. package/src/web-search/loop.ts +16 -2
  357. package/gui/dist/assets/App-nZ34cR5G.js +0 -58
  358. package/gui/dist/assets/index-DGXS51sp.js +0 -94
  359. package/gui/dist/assets/index-DPeB9HpV.css +0 -1
  360. package/gui/dist/assets/quota-summary-DO1Sx5TM.js +0 -1
@@ -0,0 +1,97 @@
1
+ /**
2
+ * Whether a Remote Link Child can serve relayed requests right now, for its `GET /readyz`.
3
+ *
4
+ * `/healthz` keeps meaning "this process answers". A Child whose tunnel is down still answers it,
5
+ * yet every relayed turn fails with 503, so readiness is where that shows: not ready, with one
6
+ * fixed reason word. Nothing here carries ssh output, host names, ports or keys.
7
+ *
8
+ * - A Child-initiated link reads its own tunnel supervisor; no network traffic.
9
+ * - A Home-initiated link has no local tunnel to inspect (the Home runs `ssh -R`), so it runs
10
+ * the credential-free relay preflight through the tunnel port. One preflight runs at a time, a
11
+ * verdict is reused for `LINK_READINESS_TTL_MS`, and a request waits at most
12
+ * `LINK_READINESS_WAIT_MS` for a running preflight before it answers `link_unverified`. An
13
+ * unauthenticated caller can therefore cause at most one preflight per TTL.
14
+ */
15
+ import { LINK_RELAY_AUTH_TIMEOUT_MS } from "../link/relay-auth";
16
+ import { isLinkPort } from "../link/ports";
17
+ import { probeLinkRelayPreflight, type BoundLinkRelayTarget, type LinkRelayPreflightResult } from "./link-relay-transport";
18
+ import type { ClientLinkSupervisorStatus } from "./link-tunnel";
19
+
20
+ export type LinkReadinessReason =
21
+ | "tunnel_idle" | "tunnel_connecting" | "tunnel_failed" | "tunnel_unavailable" | "sidecar_invalid"
22
+ | "home_unreachable" | "home_unauthorized" | "link_auth_failed" | "link_credential_unavailable"
23
+ | "link_unverified";
24
+
25
+ export type LinkReadiness = { ready: true } | { ready: false; reason: LinkReadinessReason };
26
+
27
+ export const LINK_READINESS_TTL_MS = 5_000;
28
+ export const LINK_READINESS_WAIT_MS = 500;
29
+
30
+ const READY: LinkReadiness = { ready: true };
31
+ const notReady = (reason: LinkReadinessReason): LinkReadiness => ({ ready: false, reason });
32
+
33
+ /**
34
+ * A Child-initiated link from its supervisor. The keyed probe the supervisor runs every 30 seconds
35
+ * while connected is display-only for the tunnel, but a Home that stopped answering or refuses the
36
+ * key cannot serve a turn, so readiness follows it. A Home whose own startup readiness is pending
37
+ * still serves relayed requests (the probe's `home_not_ready`), so that reads ready.
38
+ */
39
+ export function clientInitiatedLinkReadiness(status: ClientLinkSupervisorStatus): LinkReadiness {
40
+ if (status.kind === "failed") return notReady("sidecar_invalid");
41
+ if (status.kind === "stopped") return notReady("tunnel_idle");
42
+ const { state, probe } = status;
43
+ if (state.kind === "connected") {
44
+ if (probe === "home_unreachable") return notReady("home_unreachable");
45
+ if (probe === "unauthorized") return notReady("home_unauthorized");
46
+ return READY;
47
+ }
48
+ if (state.kind === "connecting" || state.kind === "reconnecting") return notReady("tunnel_connecting");
49
+ if (state.kind === "failed") return notReady(state.inFlight ? "tunnel_connecting" : "tunnel_failed");
50
+ return notReady("tunnel_idle");
51
+ }
52
+
53
+ function fromPreflight(result: LinkRelayPreflightResult): LinkReadiness {
54
+ if (result === "ok") return READY;
55
+ return notReady(result === "unreachable" ? "home_unreachable" : "link_auth_failed");
56
+ }
57
+
58
+ export interface HomeInitiatedLinkReadinessDeps {
59
+ target: Omit<BoundLinkRelayTarget, "admissionKey">;
60
+ linkKey: () => string | null;
61
+ probe?: (target: BoundLinkRelayTarget, options: { timeoutMs: number }) => Promise<LinkRelayPreflightResult>;
62
+ now?: () => number;
63
+ /** Resolves after `ms`; the wait for a running preflight. */
64
+ delay?: (ms: number) => Promise<void>;
65
+ }
66
+
67
+ /** The readiness of a Home-initiated link, from a shared, rate-limited relay preflight. */
68
+ export function createHomeInitiatedLinkReadiness(deps: HomeInitiatedLinkReadinessDeps): () => Promise<LinkReadiness> {
69
+ const probe = deps.probe ?? probeLinkRelayPreflight;
70
+ const now = deps.now ?? Date.now;
71
+ const delay = deps.delay ?? (ms => new Promise<void>(resolve => {
72
+ const timer = setTimeout(resolve, ms);
73
+ (timer as { unref?: () => void }).unref?.();
74
+ }));
75
+ let last: { at: number; verdict: LinkReadiness } | undefined;
76
+ let flight: Promise<LinkReadiness> | undefined;
77
+ const run = (admissionKey: string): Promise<LinkReadiness> => {
78
+ flight ??= probe({ ...deps.target, admissionKey }, { timeoutMs: LINK_RELAY_AUTH_TIMEOUT_MS })
79
+ .then(fromPreflight, () => notReady("home_unreachable"))
80
+ .then(verdict => {
81
+ last = { at: now(), verdict };
82
+ return verdict;
83
+ })
84
+ .finally(() => { flight = undefined; });
85
+ return flight;
86
+ };
87
+ return async () => {
88
+ if (!isLinkPort(deps.target.tunnelPort)) return notReady("tunnel_unavailable");
89
+ let admissionKey: string | null;
90
+ try { admissionKey = deps.linkKey(); } catch { admissionKey = null; }
91
+ if (!admissionKey) return notReady("link_credential_unavailable");
92
+ const at = now();
93
+ if (last && at >= last.at && at - last.at < LINK_READINESS_TTL_MS) return last.verdict;
94
+ const unverified = notReady("link_unverified");
95
+ return await Promise.race([run(admissionKey), delay(LINK_READINESS_WAIT_MS).then(() => unverified)]);
96
+ };
97
+ }
@@ -9,7 +9,7 @@ import { linkPeerReportHeaders } from "../link/peer-report";
9
9
  import { buildPeerFeatures } from "../remote/features";
10
10
  import {
11
11
  LINK_RELAY_AUTH_PATH, LINK_RELAY_AUTH_TIMEOUT_MS, LINK_RELAY_AUTH_VERSION,
12
- LINK_RELAY_SESSION_HEADER, linkRelayChallenge, linkRelayProofMatches,
12
+ LINK_RELAY_PROBE_HEADER, LINK_RELAY_SESSION_HEADER, linkRelayChallenge, linkRelayProofMatches,
13
13
  } from "../link/relay-auth";
14
14
 
15
15
  export interface BoundLinkRelayTarget {
@@ -27,6 +27,14 @@ export class LinkRelayAuthenticationError extends Error {
27
27
  }
28
28
  }
29
29
 
30
+ /** Only the credential-free preflight deadline expired; no data request has begun. */
31
+ export class LinkRelayAuthTimeoutError extends Error {
32
+ constructor() {
33
+ super("link relay authentication timed out");
34
+ this.name = "LinkRelayAuthTimeoutError";
35
+ }
36
+ }
37
+
30
38
  /** One physical connection, ever. A closed keep-alive socket cannot trigger a silent reconnect. */
31
39
  class SingleConnectionAgent extends Agent {
32
40
  socket: Socket | undefined;
@@ -153,21 +161,76 @@ async function responseOnConnection(incoming: IncomingMessage, agent: SingleConn
153
161
 
154
162
  let peerReport: Record<string, string> | undefined;
155
163
 
156
- /** Authenticate and stream one request on the SAME socket; never fall back to an ordinary fetch. */
157
- export async function fetchBoundLinkRelay(target: BoundLinkRelayTarget, destination: string, init: RequestInit): Promise<Response> {
164
+ /** The credential-free challenge for one connection; the proof binds this nonce to the link key. */
165
+ function relayChallenge(target: BoundLinkRelayTarget, origin: URL) {
166
+ const challenge = linkRelayChallenge(serviceApiTokenFingerprint(target.admissionKey), target.apiKeyId!, target.linkId!);
167
+ const probe = new URL(LINK_RELAY_AUTH_PATH, origin);
168
+ probe.search = new URLSearchParams({ version: LINK_RELAY_AUTH_VERSION, key: target.apiKeyId!,
169
+ link: target.linkId!, nonce: challenge.nonce, proof: challenge.caller }).toString();
170
+ // The challenge also carries this Child's version and features for the Home's link status.
171
+ peerReport ??= linkPeerReportHeaders(packageVersion("0.0.0"), buildPeerFeatures());
172
+ return { challenge, probe, headers: peerReport };
173
+ }
174
+
175
+ /**
176
+ * The outcome of the credential-free preflight alone: `ok` when the Home answered with a proof
177
+ * only the holder of the link key can make, `unrecognized` for a peer without the route (404),
178
+ * `auth_failed` for any other answer, and `unreachable` when nothing answered in time.
179
+ */
180
+ export type LinkRelayPreflightResult = "ok" | "unreachable" | "auth_failed" | "unrecognized";
181
+
182
+ /**
183
+ * Run only the preflight a relayed request starts with, on its own connection, and close it. It
184
+ * sends no link key, no data request and no body; the Child's readiness uses it to learn whether
185
+ * the Home answers through the tunnel right now. It is marked probe-only, so the Home reserves no
186
+ * session for a data request that never comes. The response body is never read.
187
+ */
188
+ export async function probeLinkRelayPreflight(
189
+ target: BoundLinkRelayTarget, options: { timeoutMs?: number } = {},
190
+ ): Promise<LinkRelayPreflightResult> {
191
+ const timeoutMs = options.timeoutMs ?? LINK_RELAY_AUTH_TIMEOUT_MS;
192
+ if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new RangeError("invalid link relay preflight timeout");
193
+ if (!target.linkId || !target.apiKeyId) return "auth_failed";
194
+ const origin = new URL(`http://127.0.0.1:${target.tunnelPort}`);
195
+ let request: ReturnType<typeof relayChallenge>;
196
+ try { request = relayChallenge(target, origin); } catch { return "auth_failed"; }
197
+ const agent = new SingleConnectionAgent({ keepAlive: false, maxSockets: 1, maxFreeSockets: 0 });
198
+ const deadline = clearableDeadline(timeoutMs);
199
+ try {
200
+ const response = await requestOnConnection(request.probe, {
201
+ method: "GET", signal: deadline.signal, headers: { ...request.headers, [LINK_RELAY_PROBE_HEADER]: "1" },
202
+ }, agent);
203
+ const proof = response.headers["x-opencodex-link-proof"];
204
+ if (response.statusCode === 204 && typeof proof === "string" && linkRelayProofMatches(proof, request.challenge.expected)) return "ok";
205
+ return response.statusCode === 404 ? "unrecognized" : "auth_failed";
206
+ } catch {
207
+ return "unreachable";
208
+ } finally {
209
+ deadline.clear();
210
+ await agent.close();
211
+ }
212
+ }
213
+
214
+ /**
215
+ * Authenticate and stream one request on the SAME socket; never fall back to an ordinary fetch.
216
+ * LinkRelayAuthTimeoutError certifies that only the credential-free preflight expired before
217
+ * data-request construction. Caller aborts and failures after that boundary keep their own errors.
218
+ */
219
+ export async function fetchBoundLinkRelay(
220
+ target: BoundLinkRelayTarget, destination: string, init: RequestInit,
221
+ options: { authTimeoutMs?: number } = {},
222
+ ): Promise<Response> {
223
+ const authTimeoutMs = options.authTimeoutMs ?? LINK_RELAY_AUTH_TIMEOUT_MS;
224
+ if (!Number.isFinite(authTimeoutMs) || authTimeoutMs <= 0) throw new RangeError("invalid link relay auth timeout");
158
225
  if (!target.linkId || !target.apiKeyId) throw new LinkRelayAuthenticationError();
159
226
  const url = new URL(destination);
160
227
  if (url.origin !== `http://127.0.0.1:${target.tunnelPort}`) throw new LinkRelayAuthenticationError();
161
- const challenge = linkRelayChallenge(serviceApiTokenFingerprint(target.admissionKey), target.apiKeyId, target.linkId);
162
- const probe = new URL(LINK_RELAY_AUTH_PATH, url);
163
- probe.search = new URLSearchParams({ version: LINK_RELAY_AUTH_VERSION, key: target.apiKeyId,
164
- link: target.linkId, nonce: challenge.nonce, proof: challenge.caller }).toString();
228
+ const { challenge, probe, headers: preflightHeaders } = relayChallenge(target, url);
165
229
  const agent = new SingleConnectionAgent({ keepAlive: true, maxSockets: 1, maxFreeSockets: 1 });
166
- const deadline = clearableDeadline(LINK_RELAY_AUTH_TIMEOUT_MS, init.signal ?? undefined);
230
+ const deadline = clearableDeadline(authTimeoutMs, init.signal ?? undefined);
231
+ let dataRequestStarted = false;
167
232
  try {
168
- // The challenge also carries this Child's version and features for the Home's link status.
169
- peerReport ??= linkPeerReportHeaders(packageVersion("0.0.0"), buildPeerFeatures());
170
- const response = await requestOnConnection(probe, { method: "GET", signal: deadline.signal, headers: peerReport }, agent);
233
+ const response = await requestOnConnection(probe, { method: "GET", signal: deadline.signal, headers: preflightHeaders }, agent);
171
234
  const socket = agent.socket;
172
235
  const proof = response.headers["x-opencodex-link-proof"];
173
236
  if (response.statusCode !== 204 || typeof proof !== "string" || !linkRelayProofMatches(proof, challenge.expected)) {
@@ -177,15 +240,20 @@ export async function fetchBoundLinkRelay(target: BoundLinkRelayTarget, destinat
177
240
  for await (const chunk of response) {
178
241
  if (chunk.length) throw new LinkRelayAuthenticationError();
179
242
  }
243
+ deadline.signal.throwIfAborted();
180
244
  deadline.clear();
181
245
  init.signal?.throwIfAborted();
182
246
  if (!socket || socket.destroyed || socket !== agent.socket) throw new LinkRelayAuthenticationError();
183
247
  const headers = new Headers(init.headers);
184
248
  headers.set(LINK_RELAY_SESSION_HEADER, challenge.nonce);
249
+ dataRequestStarted = true;
185
250
  const incoming = await requestOnConnection(url, { ...init, headers }, agent, socket);
186
251
  return await responseOnConnection(incoming, agent, init.method ?? "GET");
187
252
  } catch (error) {
253
+ const authDeadlineExpired = !dataRequestStarted && deadline.didExpire()
254
+ && !(error instanceof LinkRelayAuthenticationError);
188
255
  await agent.close();
256
+ if (authDeadlineExpired && !init.signal?.aborted) throw new LinkRelayAuthTimeoutError();
189
257
  throw error;
190
258
  } finally { deadline.clear(); }
191
259
  }
@@ -1,4 +1,5 @@
1
- import { fetchBoundLinkRelay, LinkRelayAuthenticationError } from "./link-relay-transport";
1
+ import { randomUUID } from "node:crypto";
2
+ import { fetchBoundLinkRelay, LinkRelayAuthenticationError, LinkRelayAuthTimeoutError } from "./link-relay-transport";
2
3
  import { homeUnreachableBody } from "./home-unreachable";
3
4
  import {
4
5
  boundedRelayResponseStream,
@@ -6,6 +7,7 @@ import {
6
7
  headersWithinLimit,
7
8
  validateHubRelayRequestHeaders,
8
9
  } from "./hub-relay";
10
+ import type { LinkDiagnosticRecord, LinkDiagnosticSink } from "../link/diagnostics";
9
11
  import { linkRouteAllowed } from "../link/routes";
10
12
  import { isLinkPort } from "../link/ports";
11
13
  import { resolveInboundBodyLimitBytes } from "../server/request-decompress";
@@ -26,14 +28,23 @@ export interface LinkRelayClock {
26
28
  clearTimeout: typeof clearTimeout;
27
29
  }
28
30
 
31
+ /** A fresh admission verdict plus optional diagnostic evidence; metadata never grants admission. */
32
+ export interface LinkAdmissionResult {
33
+ kind: "match" | "mismatch" | "lookup_error" | "deadline" | "stale" | "identity_unknown" | "identity_mismatch" | "unavailable";
34
+ elapsedMs?: number;
35
+ generation?: number;
36
+ state?: string;
37
+ checkId?: string;
38
+ }
39
+
29
40
  /**
30
41
  * The Child's tunnel as the relay sees it (the client link supervisor implements it). A request
31
42
  * waits on it only while the tunnel is being (re)established. Every relayed fetch waits for a
32
43
  * fresh bounded asynchronous ownership proof, including after a reconnect or refused retry.
33
44
  */
34
45
  export interface LinkTunnelGate {
35
- /** True only while a keyed probe has established this live tunnel. */
36
- connected(): boolean | Promise<boolean>;
46
+ /** Admission and its evidence are returned together; only match permits a fetch. */
47
+ connected(context?: { requestId?: string }): LinkAdmissionResult | Promise<LinkAdmissionResult>;
37
48
  /** True while the tunnel is connecting or reconnecting. */
38
49
  pending(): boolean;
39
50
  /**
@@ -51,12 +62,13 @@ export interface LinkTunnelGate {
51
62
  * supervisor, and a relay with no gate at all still refuses every request.
52
63
  */
53
64
  export const HOME_INITIATED_LINK_TUNNEL: LinkTunnelGate = {
54
- connected: () => true,
65
+ connected: () => ({ kind: "match" }),
55
66
  pending: () => false,
56
67
  waitForConnected: async () => false,
57
68
  };
58
69
 
59
70
  export interface LinkRelayDeps {
71
+ diagnostic?: LinkDiagnosticSink;
60
72
  /** Trusted complete-send test seam. Production always uses the connection-bound transport. */
61
73
  fetchImpl?: typeof fetch;
62
74
  clock?: LinkRelayClock;
@@ -136,6 +148,7 @@ function relayAuthenticationFailed(error: string): Response {
136
148
  });
137
149
  }
138
150
 
151
+ /** Preserve path/query on a fixed IPv4 loopback origin; throw when the tunnel port is invalid. */
139
152
  export function linkRelayDestination(url: URL, target: Pick<LinkRelayTarget, "tunnelPort">): string {
140
153
  if (!isLinkPort(target.tunnelPort)) {
141
154
  throw new RangeError("invalid link tunnel port");
@@ -180,6 +193,7 @@ function linkRequestHeaders(
180
193
  return headers;
181
194
  }
182
195
 
196
+ /** Drop hop-by-hop and stale length/encoding headers before exposing the decoded response. */
183
197
  export function sanitizeLinkResponseHeaders(source: Headers): Headers {
184
198
  const connectionNamed = new Set((source.get("connection") ?? "")
185
199
  .split(",").map(value => value.trim().toLowerCase()).filter(Boolean));
@@ -328,6 +342,11 @@ function idleBoundedStream(
328
342
  });
329
343
  }
330
344
 
345
+ /**
346
+ * Admit an allowlisted route and stream it through the authenticated tunnel with bounded bodies.
347
+ * Owner/auth preflight deadlines share one recovery attempt before data dispatch; an ambiguous
348
+ * post-dispatch failure never earns that recovery. Diagnostic failures cannot change admission.
349
+ */
331
350
  export async function relayLinkDataRequest(
332
351
  req: Request,
333
352
  target: LinkRelayTarget,
@@ -352,6 +371,16 @@ export async function relayLinkDataRequest(
352
371
  return jsonError(431, "link relay request headers too large");
353
372
  }
354
373
 
374
+ const requestId = randomUUID();
375
+ let admission: LinkAdmissionResult = { kind: "unavailable" };
376
+ let recoveryAttempts = 0;
377
+ const diagnostic = (event: LinkDiagnosticRecord["event"], outcome: LinkDiagnosticRecord["outcome"], elapsedMs?: number) => {
378
+ try { deps.diagnostic?.({ event, outcome, requestId,
379
+ checkId: admission.checkId, generation: admission.generation,
380
+ state: admission.state, elapsedMs: admission.elapsedMs,
381
+ ...(elapsedMs !== undefined ? { elapsedMs } : {}), attempt: recoveryAttempts }); }
382
+ catch { /* diagnostics never alter admission */ }
383
+ };
355
384
  const relayAbort = new AbortController();
356
385
  const clock = deps.clock ?? defaultClock;
357
386
  let headerTimer: ReturnType<typeof setTimeout> | undefined = clock.setTimeout(() => {
@@ -390,20 +419,45 @@ export async function relayLinkDataRequest(
390
419
  const remaining = holdUntil - now;
391
420
  return remaining > 0 && await gate.waitForConnected(remaining, relayAbort.signal);
392
421
  };
393
- const tunnelUnavailable = async (): Promise<Response> => {
422
+ const tunnelUnavailable = async (
423
+ reason: LinkDiagnosticRecord["outcome"] = admission.kind === "match" ? "unavailable" : admission.kind,
424
+ message = "link tunnel unavailable",
425
+ elapsedMs?: number,
426
+ ): Promise<Response> => {
427
+ diagnostic("relay_failure", relayAbort.signal.aborted
428
+ ? req.signal.aborted ? "client_abort" : "header_timeout" : reason, elapsedMs);
394
429
  cleanup();
395
430
  try { await body?.cancel(); } catch { /* best effort */ }
396
- return homeUnreachable("link tunnel unavailable");
431
+ const response = reason === "auth_failed" ? relayAuthenticationFailed(message) : homeUnreachable(message);
432
+ response.headers.set("x-opencodex-link-request-id", requestId);
433
+ return response;
434
+ };
435
+ const retryPreflight = (reason: "deadline" | "auth_timeout", elapsedMs?: number): boolean => {
436
+ if (recoveryAttempts >= 1 || relayAbort.signal.aborted || bodyOverflow || bodyCancelled || body?.locked) return false;
437
+ recoveryAttempts += 1;
438
+ diagnostic("relay_retry", reason, elapsedMs);
439
+ return true;
440
+ };
441
+ const checkConnected = async (): Promise<boolean> => {
442
+ admission = tunnel ? await tunnel.connected({ requestId }) : { kind: "unavailable" };
443
+ return admission.kind === "match";
397
444
  };
398
445
  const readyForFetch = async (): Promise<boolean> => {
399
- if (!tunnel) return false;
400
- if (await tunnel.connected()) return true;
401
- return tunnel.pending() && await holdForTunnel(tunnel) && await tunnel.connected();
446
+ if (!tunnel || relayAbort.signal.aborted) return false;
447
+ if (await checkConnected()) return !relayAbort.signal.aborted;
448
+ // No fetch or body read has occurred. A deadline proves neither a foreign owner nor a
449
+ // broken SSH process: give this request one fresh proof, without caching or restarting it.
450
+ if (admission.kind === "deadline" && retryPreflight("deadline")) {
451
+ if (await checkConnected()) return !relayAbort.signal.aborted;
452
+ }
453
+ return !relayAbort.signal.aborted && tunnel.pending() && await holdForTunnel(tunnel)
454
+ && await checkConnected() && !relayAbort.signal.aborted;
402
455
  };
403
456
 
404
457
  let upstream: Response | undefined;
405
458
  while (!upstream) {
406
459
  if (!await readyForFetch()) return await tunnelUnavailable();
460
+ const fetchStartedAt = performance.now();
407
461
  try {
408
462
  const init: RequestInit & { duplex?: "half" } = {
409
463
  method: req.method,
@@ -415,24 +469,28 @@ export async function relayLinkDataRequest(
415
469
  upstream = await (deps.fetchImpl ? deps.fetchImpl(destination, init) : fetchBoundLinkRelay(target, destination, init));
416
470
  } catch (error) {
417
471
  if (error instanceof LinkRelayAuthenticationError) {
418
- cleanup();
419
- try { await body?.cancel(); } catch { /* an upload might already be drained */ }
420
- return relayAuthenticationFailed(error.message);
472
+ return await tunnelUnavailable("auth_failed", error.message);
421
473
  }
422
474
  if (bodyOverflow) {
423
475
  cleanup();
424
476
  return jsonError(413, "link relay request body too large");
425
477
  }
478
+ if (error instanceof LinkRelayAuthTimeoutError) {
479
+ // The transport certifies that only its credential-free challenge was sent. A new
480
+ // iteration obtains a fresh ownership proof and a new authenticated physical socket.
481
+ const elapsedMs = performance.now() - fetchStartedAt;
482
+ if (retryPreflight("auth_timeout", elapsedMs)) continue;
483
+ return await tunnelUnavailable("auth_timeout", "link tunnel unavailable", elapsedMs);
484
+ }
426
485
  // A refused connection sent nothing, and an untouched body can go again once the tunnel
427
486
  // is back inside the same hold window. Anything else is never replayed.
428
487
  const resendable = connectionRefused(error) && (body === null || (!body.locked && !bodyCancelled));
429
- if (!tunnel || !resendable || !tunnel.pending() || !await holdForTunnel(tunnel)) return await tunnelUnavailable();
488
+ if (!tunnel || !resendable || !tunnel.pending() || !await holdForTunnel(tunnel)) return await tunnelUnavailable("transport_error");
430
489
  }
431
490
  }
432
491
  if (relayAbort.signal.aborted) {
433
- cleanup();
434
492
  try { await upstream.body?.cancel(); } catch { /* best effort */ }
435
- return homeUnreachable("link tunnel unavailable");
493
+ return await tunnelUnavailable();
436
494
  }
437
495
 
438
496
  const sse = isSse(upstream.headers);
@@ -449,6 +507,7 @@ export async function relayLinkDataRequest(
449
507
  try { await upstream.body?.cancel(); } catch { /* best effort */ }
450
508
  return jsonError(502, "link relay response body too large");
451
509
  }
510
+ if (recoveryAttempts > 0 && upstream.ok) diagnostic("relay_recovered", "recovered");
452
511
  if (req.method === "HEAD" || !upstream.body) {
453
512
  cleanup();
454
513
  try { await upstream.body?.cancel(); } catch { /* best effort */ }
@@ -1,3 +1,4 @@
1
+ import { randomUUID } from "node:crypto";
1
2
  import { chmodSync, mkdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
2
3
  import { execFile } from "node:child_process";
3
4
  import { readFile as readFileAsync } from "node:fs/promises";
@@ -13,17 +14,18 @@ import {
13
14
  CLIENT_TUNNEL_RETRY_POLICY,
14
15
  classifySshStderr,
15
16
  dueForSpawn,
16
- failedTunnel,
17
+ failedSpawnTunnel,
17
18
  IDLE,
18
19
  reduceTunnel,
19
20
  type StderrClass,
20
21
  type TunnelState,
21
22
  } from "../link/tunnel-state";
22
23
  import { isLinkPort } from "../link/ports";
23
- import { ownsIpv4LoopbackListener } from "../server/port-reclaim";
24
+ import { inspectIpv4LoopbackListener, type LoopbackOwnerLookupResult } from "../server/port-reclaim";
25
+ import type { LinkDiagnosticSink } from "../link/diagnostics";
24
26
  import { isLinkConnection, readClientConnectionState } from "./state";
25
27
  import { clientLinkStatePath, readClientLinkState, type ClientLinkState } from "./link-state";
26
- import type { LinkTunnelGate } from "./link-relay";
28
+ import type { LinkTunnelGate, LinkAdmissionResult } from "./link-relay";
27
29
 
28
30
  /**
29
31
  * The client-owned `ssh -N -L 127.0.0.1:<tunnelPort>:127.0.0.1:<peerListenerPort> <alias>`
@@ -134,7 +136,8 @@ export interface ClientLinkSupervisorDeps extends ClientLinkTunnelDeps, OrphanRe
134
136
  /** The link key for the keyed readiness probe. The runtime passes its cached key source. */
135
137
  linkKey?: () => string | null;
136
138
  /** Async local IPv4 LISTEN ownership; an unknown or foreign owner never receives the link key. */
137
- ownsLoopbackListener?: (port: number, pid: number) => Promise<boolean>;
139
+ inspectLoopbackListener?: (port: number, pid: number) => Promise<LoopbackOwnerLookupResult>;
140
+ diagnostic?: LinkDiagnosticSink;
138
141
  fetchImpl?: typeof fetch;
139
142
  now?: () => number;
140
143
  random?: () => number;
@@ -563,6 +566,10 @@ async function probeTunnel(fetchImpl: typeof fetch, tunnelPort: number, key: str
563
566
  }
564
567
  }
565
568
 
569
+ /**
570
+ * Own the Child's SSH lifecycle and reconnect holds. Each connected() call checks fresh listener
571
+ * ownership and fences results against tunnel replacement or stop; diagnostics cannot admit it.
572
+ */
566
573
  export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}): ClientLinkSupervisor {
567
574
  const sidecarPath = (): string => clientLinkStatePath(deps.configDir);
568
575
  const readSidecar = deps.readSidecar ?? readWhenFileChanges(sidecarPath, () => readClientLinkState(sidecarPath()));
@@ -573,7 +580,7 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
573
580
  const policy = CLIENT_TUNNEL_RETRY_POLICY;
574
581
  const isAlive = deps.isAlive ?? defaultIsAlive;
575
582
  const linkKey = deps.linkKey ?? (() => null);
576
- const ownerLookup = deps.ownsLoopbackListener ?? ownsIpv4LoopbackListener;
583
+ const ownerLookup = deps.inspectLoopbackListener ?? inspectIpv4LoopbackListener;
577
584
  const fetchImpl = deps.fetchImpl ?? fetch;
578
585
  const setSupervisorTimer = deps.setTimer ?? ((callback: () => void, ms: number) => {
579
586
  const interval = setInterval(callback, ms);
@@ -620,9 +627,16 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
620
627
  if (pid === null || pid === undefined || (adopted !== null && !adoptedRecord)) return null;
621
628
  return { pid, generation: ownerGeneration };
622
629
  };
623
- const listenerOwnedByTunnel = async (port: number): Promise<boolean> => {
630
+ const listenerOwnedByTunnel = async (port: number, context?: { requestId?: string }): Promise<LinkAdmissionResult> => {
624
631
  const candidate = ownerCandidate(port);
625
- if (!candidate) return false;
632
+ if (!candidate) return { kind: "unavailable" };
633
+ const checkId = randomUUID();
634
+ const report = (kind: LinkAdmissionResult["kind"], elapsedMs = 0): LinkAdmissionResult => {
635
+ const check = { kind, elapsedMs, checkId, generation: candidate.generation, state: state.kind };
636
+ if (kind !== "match") try { deps.diagnostic?.({ event: "owner_lookup", outcome: kind, requestId: context?.requestId,
637
+ checkId, generation: candidate.generation, state: state.kind, elapsedMs }); } catch { /* best effort */ }
638
+ return check;
639
+ };
626
640
  if (adopted !== null) {
627
641
  const record = adoptedRecord;
628
642
  const identity = record ? await inspectAdoptedIdentity(record, deps) : "unknown";
@@ -640,16 +654,28 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
640
654
  invalidateOwnerProof();
641
655
  setState(IDLE);
642
656
  }
643
- return false;
657
+ return report(identity === "mismatch" ? "identity_mismatch" : "identity_unknown");
644
658
  }
645
659
  }
646
- const owned = await Promise.resolve().then(() => ownerLookup(port, candidate.pid)).catch(() => false);
647
- return owned && !stopping && ownerGeneration === candidate.generation
648
- && ownerCandidate(port)?.pid === candidate.pid;
660
+ const result = await Promise.resolve().then(() => ownerLookup(port, candidate.pid))
661
+ .catch((): LoopbackOwnerLookupResult => ({ kind: "lookup_error", elapsedMs: 0 }));
662
+ if (stopping || failure !== undefined || ownerGeneration !== candidate.generation || ownerCandidate(port)?.pid !== candidate.pid) {
663
+ return report("stale", result.elapsedMs);
664
+ }
665
+ return report(result.kind, result.elapsedMs);
666
+ };
667
+ const connected = async (context?: { requestId?: string }): Promise<LinkAdmissionResult> => {
668
+ if (!started || stopping || failure !== undefined || state.kind !== "connected" || linkId === null || tunnelPort === null) {
669
+ return { kind: "unavailable" };
670
+ }
671
+ const result = await listenerOwnedByTunnel(tunnelPort, context);
672
+ // State may change during the asynchronous lookup or an optional diagnostic callback.
673
+ if (result.kind === "match" && (!started || stopping || failure !== undefined
674
+ || state.kind !== "connected" || result.generation !== ownerGeneration)) {
675
+ return { ...result, kind: "stale" };
676
+ }
677
+ return result;
649
678
  };
650
- const connected = async (): Promise<boolean> => started && !stopping && failure === undefined
651
- && state.kind === "connected" && linkId !== null && tunnelPort !== null
652
- && await listenerOwnedByTunnel(tunnelPort);
653
679
 
654
680
  const settleWaiters = (): void => {
655
681
  if (waiters.size === 0) return;
@@ -733,7 +759,8 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
733
759
  peerListenerPort: sidecar.peerListenerPort,
734
760
  }, deps);
735
761
  } catch {
736
- setState(failedTunnel("forward", timestamp, policy, state.kind === "failed" ? state.since : timestamp));
762
+ // A due retry that cannot start counts as a failed retry, so the backoff keeps its step.
763
+ setState(failedSpawnTunnel(state, "forward", timestamp, policy));
737
764
  deps.warn?.("client link tunnel could not be started");
738
765
  return;
739
766
  }
@@ -800,7 +827,7 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
800
827
  probeFlight = flight;
801
828
  const wasConnected = state.kind === "connected";
802
829
  void (async () => {
803
- if (!await listenerOwnedByTunnel(tunnelPort)) return;
830
+ if ((await listenerOwnedByTunnel(tunnelPort)).kind !== "match") return;
804
831
  if (probeFlight !== flight || stopping || flight.abort.signal.aborted
805
832
  || child !== flight.child || adopted !== flight.adopted) return;
806
833
  const key = linkKey();
@@ -808,7 +835,7 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
808
835
  const result = await probeTunnel(fetchImpl, tunnelPort, key, flight.abort.signal);
809
836
  // An aborted probe, or one whose listener changed while it ran, proves nothing.
810
837
  if (probeFlight !== flight || stopping || child !== flight.child || adopted !== flight.adopted
811
- || !await listenerOwnedByTunnel(tunnelPort)) return;
838
+ || (await listenerOwnedByTunnel(tunnelPort)).kind !== "match") return;
812
839
  applyProbe(result, wasConnected);
813
840
  })().catch(() => undefined).finally(() => {
814
841
  if (probeFlight === flight) probeFlight = undefined;
@@ -971,7 +998,7 @@ export function createClientLinkSupervisor(deps: ClientLinkSupervisorDeps = {}):
971
998
  pending,
972
999
  connected,
973
1000
  waitForConnected(timeoutMs: number, signal?: AbortSignal): Promise<boolean> {
974
- if (state.kind === "connected") return connected();
1001
+ if (state.kind === "connected") return connected().then(result => result.kind === "match");
975
1002
  if (!pending() || waiters.size >= CLIENT_LINK_MAX_HOLDS || signal?.aborted || !(timeoutMs > 0)) {
976
1003
  return Promise.resolve(false);
977
1004
  }
@@ -106,7 +106,9 @@ export async function handleMachineApi(
106
106
  return Response.json({ error: "invalid sync request" }, { status: 400 });
107
107
  }
108
108
  try {
109
- const result = await deps.sync(
109
+ // `connection` is the full saved connection (token fingerprint, prior catalog) for local
110
+ // callers; it is not part of this response.
111
+ const { connection: _connection, ...result } = await deps.sync(
110
112
  input.restartCodex === undefined ? {} : { restartCodex: input.restartCodex },
111
113
  );
112
114
  deps.setHubReachability?.("online");
@@ -1,3 +1,4 @@
1
+ import { recordLinkDiagnostic } from "../link/diagnostics";
1
2
  import type { Server } from "bun";
2
3
  import { loadConfig } from "../config";
3
4
  import { browserSecurityHeaders, requestPolicyView } from "../server/auth-cors";
@@ -21,6 +22,7 @@ import type { LinkTunnelGate } from "./link-relay";
21
22
  import { readClientLinkState, type ClientLinkState } from "./link-state";
22
23
  import { projectClientLinkChild, type ClientLinkSidecarRead } from "./link-status";
23
24
  import type { ClientLinkSupervisorStatus } from "./link-tunnel";
25
+ import type { LinkReadiness } from "./link-readiness";
24
26
  import { packageVersion } from "../lib/package-version";
25
27
  import { createLocalAttestationProof, LOCAL_ATTESTATION_CHALLENGE_HEADER, LOCAL_ATTESTATION_PROOF_HEADER } from "../lib/local-management-attestation";
26
28
  import {
@@ -65,6 +67,11 @@ export interface MachineListenerDeps {
65
67
  linkTunnel?: LinkTunnelGate;
66
68
  /** Link mode: relay seams (deadline clock and byte cap). */
67
69
  linkRelay?: LinkIngress["relay"];
70
+ /**
71
+ * Link mode: whether relayed requests can be served now. `GET /readyz` answers 503 `pending`
72
+ * with `link.reason` while it is not; `/healthz` is unaffected (`link-readiness.ts`).
73
+ */
74
+ linkReadiness?: () => LinkReadiness | Promise<LinkReadiness>;
68
75
  /**
69
76
  * The bound restart (OCX-6). With it, `/healthz` proves this process's identity to a challenge,
70
77
  * advertises `restartCapability` and `startedAt`, and `POST /api/system/restart` accepts a
@@ -152,7 +159,7 @@ export function startMachineListener(
152
159
  apiKeyId: connection.apiKeyId,
153
160
  policy: requestPolicyView(config, "127.0.0.1"),
154
161
  linkKey: deps.linkKeySource ?? createLinkKeySource(connection.tokenFingerprint, deps.linkKey),
155
- relay: { fetchImpl: deps.fetchImpl, bodyLimitBytes: inboundBodyLimit, tunnel: deps.linkTunnel, ...deps.linkRelay },
162
+ relay: { diagnostic: recordLinkDiagnostic, fetchImpl: deps.fetchImpl, bodyLimitBytes: inboundBodyLimit, tunnel: deps.linkTunnel, ...deps.linkRelay },
156
163
  }
157
164
  : null;
158
165
  return (deps.serve ?? (options => Bun.serve(options)))({
@@ -186,7 +193,18 @@ export function startMachineListener(
186
193
  return await handleBoundRestart(req, server, deps.restart);
187
194
  }
188
195
  if (url.pathname === "/readyz" && req.method === "GET") {
189
- return Response.json({ service: "opencodex", version: VERSION, role: "client", status: "ready", uptime: process.uptime(), pid: process.pid, port: server.port, protocolVersion: 1 });
196
+ const identity = { service: "opencodex", version: VERSION, role: "client" } as const;
197
+ const facts = { uptime: process.uptime(), pid: process.pid, port: server.port, protocolVersion: 1 };
198
+ let link: LinkReadiness | null = null;
199
+ if (linkMode && deps.linkReadiness) {
200
+ try { link = await deps.linkReadiness(); } catch { link = { ready: false, reason: "link_unverified" }; }
201
+ }
202
+ if (link && !link.ready) {
203
+ // The /readyz contract: not ready is 503 with Retry-After and status pending or failed.
204
+ return Response.json({ ...identity, status: "pending", ...facts, link: { state: "unavailable", reason: link.reason } },
205
+ { status: 503, headers: { "Retry-After": "1", "Cache-Control": "no-store" } });
206
+ }
207
+ return Response.json({ ...identity, status: "ready", ...facts, ...(link ? { link: { state: "available" } } : {}) });
190
208
  }
191
209
  if (url.pathname.startsWith("/api/machine/hub-relay/")) {
192
210
  if (!relayEnabled) return json404(req);