@apralabs/apra-fleet 0.4.2 → 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (997) hide show
  1. package/README.md +103 -34
  2. package/dist/agents/backlog-groomer.md +87 -14
  3. package/dist/agents/ci-watcher.md +35 -9
  4. package/dist/agents/deployer.md +63 -11
  5. package/dist/agents/doer.md +99 -41
  6. package/dist/agents/harvester.md +47 -27
  7. package/dist/agents/integ-test-runner.md +38 -10
  8. package/dist/agents/kb-reconciler.md +37 -7
  9. package/dist/agents/plan-reviewer.md +145 -32
  10. package/dist/agents/planner.md +180 -69
  11. package/dist/agents/regression-test-runner.md +98 -64
  12. package/dist/agents/reviewer.md +117 -45
  13. package/dist/agents/schemas/backlog-groomer-output.json +1 -1
  14. package/dist/agents/schemas/doer-output.json +32 -0
  15. package/dist/agents/schemas/harvester-input.json +1 -5
  16. package/dist/agents/schemas/plan-reviewer-output.json +37 -0
  17. package/dist/agents/schemas/planner-output.json +1 -1
  18. package/dist/agents/schemas/regression-test-runner-output.json +41 -7
  19. package/dist/agents/schemas/reviewer-output.json +62 -3
  20. package/dist/cli/agent-transform.d.ts +90 -2
  21. package/dist/cli/agent-transform.js +310 -20
  22. package/dist/cli/auth.d.ts +1 -0
  23. package/dist/cli/auth.js +66 -17
  24. package/dist/cli/beads-install.d.ts +35 -0
  25. package/dist/cli/beads-install.js +125 -0
  26. package/dist/cli/beads-pin.d.ts +5 -0
  27. package/dist/cli/beads-pin.js +27 -0
  28. package/dist/cli/call.d.ts +27 -0
  29. package/dist/cli/call.js +177 -0
  30. package/dist/cli/config.d.ts +31 -6
  31. package/dist/cli/config.js +113 -36
  32. package/dist/cli/dolt-install.d.ts +18 -2
  33. package/dist/cli/dolt-install.js +46 -15
  34. package/dist/cli/fleet-se-guard.d.ts +51 -0
  35. package/dist/cli/fleet-se-guard.js +215 -0
  36. package/dist/cli/install-guard.d.ts +54 -0
  37. package/dist/cli/install-guard.js +132 -4
  38. package/dist/cli/install.d.ts +100 -11
  39. package/dist/cli/install.js +864 -139
  40. package/dist/cli/kb-commit.d.ts +2 -1
  41. package/dist/cli/kb-commit.js +1 -1
  42. package/dist/cli/kb-directives.js +2 -1
  43. package/dist/cli/kb-import.d.ts +2 -1
  44. package/dist/cli/kb-import.js +1 -1
  45. package/dist/cli/register-member.js +26 -5
  46. package/dist/cli/remove-member.d.ts +4 -0
  47. package/dist/cli/remove-member.js +63 -0
  48. package/dist/cli/secret.js +9 -0
  49. package/dist/cli/start.js +59 -4
  50. package/dist/cli/status.d.ts +3 -0
  51. package/dist/cli/status.js +45 -12
  52. package/dist/cli/stop.js +64 -9
  53. package/dist/cli/uninstall.js +101 -15
  54. package/dist/cli/update.js +33 -2
  55. package/dist/cli/watch.js +1 -1
  56. package/dist/cli/workflow.js +3 -2
  57. package/dist/commands/kb-server.d.ts +3 -0
  58. package/dist/commands/kb-server.js +52 -5
  59. package/dist/hub-service/http-server.d.ts +5 -1
  60. package/dist/hub-service/http-server.js +55 -5
  61. package/dist/index.js +158 -11
  62. package/dist/os/child-env-bound.d.ts +77 -0
  63. package/dist/os/child-env-bound.js +171 -0
  64. package/dist/os/linux.d.ts +13 -2
  65. package/dist/os/linux.js +75 -16
  66. package/dist/os/macos.d.ts +1 -1
  67. package/dist/os/macos.js +2 -11
  68. package/dist/os/os-commands.d.ts +78 -4
  69. package/dist/os/windows-gitbash.d.ts +6 -0
  70. package/dist/os/windows-gitbash.js +32 -3
  71. package/dist/os/windows-wrapper.d.ts +0 -4
  72. package/dist/os/windows-wrapper.js +2 -1
  73. package/dist/os/windows.d.ts +11 -2
  74. package/dist/os/windows.js +121 -32
  75. package/dist/paths.d.ts +21 -0
  76. package/dist/paths.js +35 -0
  77. package/dist/providers/agy.d.ts +120 -7
  78. package/dist/providers/agy.js +741 -86
  79. package/dist/providers/claude-permission-denial.d.ts +7 -0
  80. package/dist/providers/claude-permission-denial.js +137 -0
  81. package/dist/providers/claude.d.ts +132 -6
  82. package/dist/providers/claude.js +644 -48
  83. package/dist/providers/codex.d.ts +4 -2
  84. package/dist/providers/codex.js +23 -2
  85. package/dist/providers/copilot.d.ts +4 -2
  86. package/dist/providers/copilot.js +24 -2
  87. package/dist/providers/none.d.ts +4 -2
  88. package/dist/providers/none.js +17 -2
  89. package/dist/providers/opencode.d.ts +12 -2
  90. package/dist/providers/opencode.js +135 -54
  91. package/dist/providers/provider.d.ts +368 -35
  92. package/dist/providers/provider.js +219 -2
  93. package/dist/services/agent-provisioner.d.ts +29 -0
  94. package/dist/services/agent-provisioner.js +107 -0
  95. package/dist/services/agent-shadow.d.ts +96 -0
  96. package/dist/services/agent-shadow.js +479 -0
  97. package/dist/services/agy-project.d.ts +103 -0
  98. package/dist/services/agy-project.js +354 -0
  99. package/dist/services/auth-socket.d.ts +25 -0
  100. package/dist/services/auth-socket.js +72 -27
  101. package/dist/services/auth-web.js +2 -2
  102. package/dist/services/budget-awareness.d.ts +11 -11
  103. package/dist/services/budget-awareness.js +15 -3
  104. package/dist/services/claude-local-scope-mcp.d.ts +19 -0
  105. package/dist/services/claude-local-scope-mcp.js +91 -0
  106. package/dist/services/cloud/aws.js +2 -1
  107. package/dist/services/cloud/lifecycle.js +52 -6
  108. package/dist/services/cloud/task-wrapper.d.ts +0 -9
  109. package/dist/services/cloud/task-wrapper.js +15 -6
  110. package/dist/services/credential-cleanup.js +35 -17
  111. package/dist/services/event-loop-watchdog.d.ts +32 -0
  112. package/dist/services/event-loop-watchdog.js +140 -0
  113. package/dist/services/exit-drain.d.ts +44 -0
  114. package/dist/services/exit-drain.js +52 -0
  115. package/dist/services/github-app.js +32 -4
  116. package/dist/services/http-transport.d.ts +50 -1
  117. package/dist/services/http-transport.js +238 -25
  118. package/dist/services/in-flight-agents.d.ts +2 -0
  119. package/dist/services/in-flight-agents.js +4 -0
  120. package/dist/services/knowledge/bible-basis-filter.d.ts +53 -0
  121. package/dist/services/knowledge/bible-basis-filter.js +134 -0
  122. package/dist/services/knowledge/bible-blob-id.d.ts +44 -0
  123. package/dist/services/knowledge/bible-blob-id.js +113 -0
  124. package/dist/services/knowledge/bible-import.d.ts +65 -0
  125. package/dist/services/knowledge/bible-import.js +211 -0
  126. package/dist/services/knowledge/file-hash.d.ts +31 -0
  127. package/dist/services/knowledge/file-hash.js +153 -23
  128. package/dist/services/knowledge/http-provider.d.ts +4 -3
  129. package/dist/services/knowledge/http-provider.js +17 -5
  130. package/dist/services/knowledge/kb-config.d.ts +42 -0
  131. package/dist/services/knowledge/kb-config.js +54 -0
  132. package/dist/services/knowledge/kb-maintainer-grant.d.ts +15 -0
  133. package/dist/services/knowledge/kb-maintainer-grant.js +34 -0
  134. package/dist/services/knowledge/kb-providers.d.ts +11 -1
  135. package/dist/services/knowledge/kb-providers.js +199 -17
  136. package/dist/services/knowledge/kb-removed-scope-keys.d.ts +28 -0
  137. package/dist/services/knowledge/kb-removed-scope-keys.js +59 -0
  138. package/dist/services/knowledge/kb-scopes.d.ts +14 -0
  139. package/dist/services/knowledge/kb-scopes.js +47 -0
  140. package/dist/services/knowledge/kb-self.d.ts +91 -0
  141. package/dist/services/knowledge/kb-self.js +198 -0
  142. package/dist/services/knowledge/member-bible-view.d.ts +21 -0
  143. package/dist/services/knowledge/member-bible-view.js +194 -0
  144. package/dist/services/knowledge/pre-init.js +1 -0
  145. package/dist/services/knowledge/project-slug.js +2 -2
  146. package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
  147. package/dist/services/knowledge/require-sqlite-project.js +38 -0
  148. package/dist/services/knowledge/sqlite-provider.d.ts +64 -11
  149. package/dist/services/knowledge/sqlite-provider.js +303 -41
  150. package/dist/services/knowledge/types.d.ts +45 -2
  151. package/dist/services/member-access-secret.d.ts +70 -0
  152. package/dist/services/member-access-secret.js +195 -0
  153. package/dist/services/member-call-counts.d.ts +24 -0
  154. package/dist/services/member-call-counts.js +58 -0
  155. package/dist/services/member-config-io.d.ts +192 -0
  156. package/dist/services/member-config-io.js +443 -0
  157. package/dist/services/member-fleet-install.d.ts +710 -0
  158. package/dist/services/member-fleet-install.js +1895 -0
  159. package/dist/services/member-secret-env.d.ts +42 -0
  160. package/dist/services/member-secret-env.js +68 -0
  161. package/dist/services/member-tool-allowlist.d.ts +49 -0
  162. package/dist/services/member-tool-allowlist.js +111 -0
  163. package/dist/services/model-pricing.d.ts +19 -0
  164. package/dist/services/model-pricing.js +60 -10
  165. package/dist/services/port-holder.d.ts +86 -0
  166. package/dist/services/port-holder.js +351 -0
  167. package/dist/services/preflight-check.js +2 -0
  168. package/dist/services/registry.d.ts +13 -2
  169. package/dist/services/registry.js +27 -1
  170. package/dist/services/relay-strategy.d.ts +2 -0
  171. package/dist/services/relay-strategy.js +8 -0
  172. package/dist/services/secret-token.d.ts +38 -0
  173. package/dist/services/secret-token.js +51 -0
  174. package/dist/services/server-lifecycle.d.ts +26 -0
  175. package/dist/services/server-lifecycle.js +85 -0
  176. package/dist/services/service-manager/index.d.ts +7 -1
  177. package/dist/services/service-manager/index.js +17 -4
  178. package/dist/services/service-manager/linux.d.ts +1 -1
  179. package/dist/services/service-manager/linux.js +15 -7
  180. package/dist/services/service-manager/macos.d.ts +11 -1
  181. package/dist/services/service-manager/macos.js +45 -7
  182. package/dist/services/service-manager/service-path.d.ts +24 -0
  183. package/dist/services/service-manager/service-path.js +55 -0
  184. package/dist/services/service-manager/types.d.ts +39 -2
  185. package/dist/services/service-manager/types.js +29 -0
  186. package/dist/services/service-manager/windows.d.ts +194 -3
  187. package/dist/services/service-manager/windows.js +705 -30
  188. package/dist/services/service-notice.d.ts +14 -0
  189. package/dist/services/service-notice.js +62 -0
  190. package/dist/services/service-start-guard.d.ts +20 -0
  191. package/dist/services/service-start-guard.js +86 -0
  192. package/dist/services/session-cost.d.ts +24 -0
  193. package/dist/services/session-cost.js +105 -0
  194. package/dist/services/session-mcp-config.d.ts +83 -0
  195. package/dist/services/session-mcp-config.js +211 -0
  196. package/dist/services/sftp.d.ts +34 -0
  197. package/dist/services/sftp.js +304 -76
  198. package/dist/services/shell-probe.d.ts +0 -24
  199. package/dist/services/shell-probe.js +28 -3
  200. package/dist/services/singleton.d.ts +68 -2
  201. package/dist/services/singleton.js +168 -11
  202. package/dist/services/sprint-coordination.js +9 -3
  203. package/dist/services/ssh.d.ts +27 -0
  204. package/dist/services/ssh.js +287 -40
  205. package/dist/services/stall/find-log-file.js +12 -5
  206. package/dist/services/stall/index.d.ts +1 -1
  207. package/dist/services/stall/read-log-tail.d.ts +23 -0
  208. package/dist/services/stall/read-log-tail.js +53 -12
  209. package/dist/services/stall/stall-detector.d.ts +78 -5
  210. package/dist/services/stall/stall-detector.js +296 -39
  211. package/dist/services/stall/stall-poller.d.ts +16 -0
  212. package/dist/services/stall/stall-poller.js +50 -6
  213. package/dist/services/stopped-marker.d.ts +16 -0
  214. package/dist/services/stopped-marker.js +55 -0
  215. package/dist/services/strategy.d.ts +33 -1
  216. package/dist/services/strategy.js +165 -19
  217. package/dist/services/substitution-engine.js +2 -2
  218. package/dist/services/supervisor-service-cleanup.d.ts +52 -0
  219. package/dist/services/supervisor-service-cleanup.js +332 -0
  220. package/dist/services/tool-registry.d.ts +8 -1
  221. package/dist/services/tool-registry.js +164 -61
  222. package/dist/services/tool-scope.d.ts +58 -0
  223. package/dist/services/tool-scope.js +99 -0
  224. package/dist/services/vcs/azure-devops.d.ts +66 -1
  225. package/dist/services/vcs/azure-devops.js +192 -21
  226. package/dist/services/vcs/types.d.ts +1 -1
  227. package/dist/services/watch/project-resolver.js +1 -0
  228. package/dist/skills/auto-sprint-args/SKILL.md +2 -2
  229. package/dist/skills/fleet-sprint-cli/SKILL.md +48 -6
  230. package/dist/skills/pm/SKILL.md +4 -4
  231. package/dist/skills/pm/cost.md +0 -3
  232. package/dist/skills/pm/fleet-addendum.md +2 -2
  233. package/dist/skills/pm/index.md +4 -2
  234. package/dist/skills/pm/kb-reconcile.md +29 -14
  235. package/dist/skills/pm/kb-review.md +1 -0
  236. package/dist/skills/pm/sprint.md +5 -5
  237. package/dist/tools/check-status.d.ts +60 -9
  238. package/dist/tools/check-status.js +211 -52
  239. package/dist/tools/child-id-allocator.d.ts +2 -2
  240. package/dist/tools/child-id-allocator.js +1 -1
  241. package/dist/tools/code-index-heal.d.ts +8 -0
  242. package/dist/tools/code-index-heal.js +21 -0
  243. package/dist/tools/code-index-state.d.ts +45 -0
  244. package/dist/tools/code-index-state.js +115 -0
  245. package/dist/tools/code-intelligence-codebase-memory.js +6 -33
  246. package/dist/tools/code-intelligence-freshness.js +1 -1
  247. package/dist/tools/code-intelligence-gitnexus.d.ts +30 -0
  248. package/dist/tools/code-intelligence-gitnexus.js +333 -57
  249. package/dist/tools/code-intelligence-kb-enrich.js +7 -6
  250. package/dist/tools/code-intelligence-readiness.d.ts +99 -0
  251. package/dist/tools/code-intelligence-readiness.js +206 -0
  252. package/dist/tools/code-intelligence-reindex.d.ts +195 -0
  253. package/dist/tools/code-intelligence-reindex.js +530 -50
  254. package/dist/tools/code-intelligence-telemetry.d.ts +6 -1
  255. package/dist/tools/code-intelligence-telemetry.js +12 -3
  256. package/dist/tools/code-intelligence.d.ts +81 -31
  257. package/dist/tools/code-intelligence.js +156 -52
  258. package/dist/tools/compose-permissions.d.ts +63 -2
  259. package/dist/tools/compose-permissions.js +673 -72
  260. package/dist/tools/credential-store-set.js +1 -1
  261. package/dist/tools/execute-command.d.ts +11 -0
  262. package/dist/tools/execute-command.js +111 -32
  263. package/dist/tools/execute-prompt.d.ts +69 -12
  264. package/dist/tools/execute-prompt.js +1610 -895
  265. package/dist/tools/kb-bible-commit.d.ts +65 -0
  266. package/dist/tools/kb-bible-commit.js +239 -0
  267. package/dist/tools/kb-capture.d.ts +15 -11
  268. package/dist/tools/kb-capture.js +71 -16
  269. package/dist/tools/kb-context.d.ts +27 -7
  270. package/dist/tools/kb-context.js +60 -9
  271. package/dist/tools/kb-export.d.ts +98 -9
  272. package/dist/tools/kb-export.js +230 -92
  273. package/dist/tools/kb-feedback.d.ts +13 -9
  274. package/dist/tools/kb-feedback.js +16 -8
  275. package/dist/tools/kb-freshness-sweep.d.ts +11 -7
  276. package/dist/tools/kb-freshness-sweep.js +10 -8
  277. package/dist/tools/kb-harvest.d.ts +11 -7
  278. package/dist/tools/kb-harvest.js +7 -7
  279. package/dist/tools/kb-import.d.ts +26 -10
  280. package/dist/tools/kb-import.js +170 -159
  281. package/dist/tools/kb-invalidate.d.ts +17 -10
  282. package/dist/tools/kb-invalidate.js +41 -8
  283. package/dist/tools/kb-list.d.ts +14 -10
  284. package/dist/tools/kb-list.js +33 -11
  285. package/dist/tools/kb-promote.d.ts +11 -7
  286. package/dist/tools/kb-promote.js +14 -8
  287. package/dist/tools/kb-query.d.ts +21 -11
  288. package/dist/tools/kb-query.js +76 -13
  289. package/dist/tools/kb-reconcile-prefilter.d.ts +11 -7
  290. package/dist/tools/kb-reconcile-prefilter.js +13 -9
  291. package/dist/tools/kb-resolve-contradiction.d.ts +11 -7
  292. package/dist/tools/kb-resolve-contradiction.js +10 -8
  293. package/dist/tools/kb-session-prime.d.ts +14 -7
  294. package/dist/tools/kb-session-prime.js +44 -44
  295. package/dist/tools/kb-setup.d.ts +11 -4
  296. package/dist/tools/kb-setup.js +146 -27
  297. package/dist/tools/kb-stats.d.ts +11 -10
  298. package/dist/tools/kb-stats.js +84 -82
  299. package/dist/tools/list-members.d.ts +2 -2
  300. package/dist/tools/list-members.js +6 -2
  301. package/dist/tools/member-detail.d.ts +5 -2
  302. package/dist/tools/member-detail.js +105 -17
  303. package/dist/tools/member-reservation.d.ts +60 -3
  304. package/dist/tools/member-reservation.js +61 -20
  305. package/dist/tools/provision-auth.d.ts +118 -1
  306. package/dist/tools/provision-auth.js +402 -92
  307. package/dist/tools/provision-vcs-auth.d.ts +93 -3
  308. package/dist/tools/provision-vcs-auth.js +209 -49
  309. package/dist/tools/receive-files.js +3 -1
  310. package/dist/tools/register-member.d.ts +44 -15
  311. package/dist/tools/register-member.js +175 -70
  312. package/dist/tools/remove-member.js +118 -15
  313. package/dist/tools/send-email.d.ts +2 -2
  314. package/dist/tools/send-files.js +6 -4
  315. package/dist/tools/session-stats.d.ts +17 -0
  316. package/dist/tools/session-stats.js +27 -0
  317. package/dist/tools/setup-git-app.js +11 -7
  318. package/dist/tools/shutdown-server.d.ts +2 -0
  319. package/dist/tools/shutdown-server.js +28 -1
  320. package/dist/tools/update-agent-cli.d.ts +19 -0
  321. package/dist/tools/update-agent-cli.js +59 -2
  322. package/dist/tools/update-member.d.ts +23 -17
  323. package/dist/tools/update-member.js +181 -18
  324. package/dist/tools/vcs-credential-exec.d.ts +127 -0
  325. package/dist/tools/vcs-credential-exec.js +203 -0
  326. package/dist/types.d.ts +111 -1
  327. package/dist/utils/agent-helpers.js +2 -0
  328. package/dist/utils/auth-env.d.ts +15 -4
  329. package/dist/utils/auth-env.js +52 -23
  330. package/dist/utils/find-on-path.d.ts +37 -0
  331. package/dist/utils/find-on-path.js +85 -0
  332. package/dist/utils/log-helpers.d.ts +37 -0
  333. package/dist/utils/log-helpers.js +108 -22
  334. package/dist/utils/owner-only-fs.d.ts +56 -0
  335. package/dist/utils/owner-only-fs.js +98 -0
  336. package/dist/utils/process-utils.d.ts +28 -0
  337. package/dist/utils/process-utils.js +68 -0
  338. package/dist/utils/prompt-errors.js +11 -2
  339. package/dist/utils/session-caller.d.ts +4 -2
  340. package/dist/utils/session-caller.js +3 -2
  341. package/dist/utils/shell-escape.d.ts +58 -3
  342. package/dist/utils/shell-escape.js +91 -5
  343. package/dist/utils/ssh-error-messages.js +3 -0
  344. package/dist/utils/vcs-provider-detect.d.ts +65 -0
  345. package/dist/utils/vcs-provider-detect.js +109 -0
  346. package/dist/utils/workspace-trust.d.ts +26 -0
  347. package/dist/utils/workspace-trust.js +91 -1
  348. package/dist/workflows/auto-sprint.js +397 -56
  349. package/package.json +15 -10
  350. package/packages/apra-fleet-client/package.json +2 -2
  351. package/packages/apra-fleet-client/src/client/api.mjs +864 -31
  352. package/packages/apra-fleet-client/src/client/auto-start.mjs +434 -0
  353. package/packages/apra-fleet-client/src/client/client.mjs +9 -0
  354. package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
  355. package/packages/apra-fleet-client/src/client/factory.mjs +23 -4
  356. package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +137 -0
  357. package/packages/apra-fleet-client/src/client/server-resolution.mjs +267 -30
  358. package/packages/apra-fleet-client/src/client/transport.mjs +37 -3
  359. package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
  360. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +87 -14
  361. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +35 -9
  362. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +63 -11
  363. package/packages/apra-fleet-se/apra-pm/agents/doer.md +99 -41
  364. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +47 -27
  365. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +38 -10
  366. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +37 -7
  367. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +145 -32
  368. package/packages/apra-fleet-se/apra-pm/agents/planner.md +180 -69
  369. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +98 -64
  370. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +117 -45
  371. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +1 -1
  372. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +32 -0
  373. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +1 -5
  374. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
  375. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +1 -1
  376. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +41 -7
  377. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +62 -3
  378. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +4 -4
  379. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -3
  380. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -2
  381. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +4 -2
  382. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +29 -14
  383. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +1 -0
  384. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +5 -5
  385. package/packages/apra-fleet-se/bin/cli.mjs +326 -48
  386. package/packages/apra-fleet-se/bin/serve.mjs +218 -11
  387. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +517 -0
  388. package/packages/apra-fleet-se/fleet-sprint/backlog-role.mjs +93 -0
  389. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +646 -0
  390. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +825 -0
  391. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +217 -0
  392. package/packages/apra-fleet-se/fleet-sprint/beads-memory-hygiene.mjs +201 -0
  393. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +745 -0
  394. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +447 -0
  395. package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
  396. package/packages/apra-fleet-se/fleet-sprint/ci-gate.mjs +353 -0
  397. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +20 -0
  398. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +121 -15
  399. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +539 -0
  400. package/packages/apra-fleet-se/fleet-sprint/dispatch-accounting.mjs +270 -0
  401. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +204 -0
  402. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1310 -0
  403. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
  404. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +53 -15
  405. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +281 -0
  406. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +1 -1
  407. package/packages/apra-fleet-se/fleet-sprint/docs/fleet-sprint-diagram.md +3 -3
  408. package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
  409. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
  410. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1327 -44
  411. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +470 -4
  412. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
  413. package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
  414. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
  415. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +747 -0
  416. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +543 -0
  417. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +613 -0
  418. package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
  419. package/packages/apra-fleet-se/fleet-sprint/kb-hints.mjs +181 -0
  420. package/packages/apra-fleet-se/fleet-sprint/kb-injection.mjs +64 -0
  421. package/packages/apra-fleet-se/fleet-sprint/kb-maintainer.mjs +298 -0
  422. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +1684 -0
  423. package/packages/apra-fleet-se/fleet-sprint/lower-quality.mjs +39 -0
  424. package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
  425. package/packages/apra-fleet-se/fleet-sprint/member-align.mjs +391 -0
  426. package/packages/apra-fleet-se/fleet-sprint/member-call.mjs +374 -0
  427. package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +644 -0
  428. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +699 -0
  429. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +802 -0
  430. package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
  431. package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
  432. package/packages/apra-fleet-se/fleet-sprint/orphan-reclaim.mjs +153 -0
  433. package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
  434. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +218 -0
  435. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +869 -0
  436. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +295 -0
  437. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +466 -0
  438. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +212 -0
  439. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
  440. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +395 -0
  441. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +345 -0
  442. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +264 -0
  443. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +179 -0
  444. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +230 -0
  445. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +365 -0
  446. package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +259 -0
  447. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +617 -0
  448. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1434 -0
  449. package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
  450. package/packages/apra-fleet-se/fleet-sprint/runner.js +2289 -9928
  451. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +24 -0
  452. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +147 -12
  453. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +111 -0
  454. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +347 -0
  455. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +48 -6
  456. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +98 -25
  457. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +590 -0
  458. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +339 -0
  459. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +185 -0
  460. package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
  461. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +218 -0
  462. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1445 -0
  463. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +284 -23
  464. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +170 -21
  465. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
  466. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +354 -0
  467. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +189 -16
  468. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +9 -4
  469. package/packages/apra-fleet-se/fleet-sprint/verify-block.mjs +152 -0
  470. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +311 -22
  471. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
  472. package/packages/apra-fleet-se/package.json +2 -2
  473. package/packages/apra-fleet-se/src/supervisor/api.mjs +919 -0
  474. package/packages/apra-fleet-se/src/supervisor/backlog-member.mjs +332 -0
  475. package/packages/apra-fleet-se/src/supervisor/backlog.mjs +982 -0
  476. package/packages/apra-fleet-se/src/supervisor/beads-identity.mjs +246 -0
  477. package/packages/apra-fleet-se/src/supervisor/beads-view.mjs +438 -0
  478. package/packages/apra-fleet-se/src/supervisor/child-port.mjs +36 -0
  479. package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +1659 -0
  480. package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +350 -0
  481. package/packages/apra-fleet-se/src/supervisor/dolt-orphan-sweep.mjs +338 -0
  482. package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +279 -0
  483. package/packages/apra-fleet-se/src/supervisor/history-view.mjs +276 -0
  484. package/packages/apra-fleet-se/src/supervisor/history.mjs +328 -0
  485. package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +521 -0
  486. package/packages/apra-fleet-se/src/supervisor/launch-form.mjs +444 -0
  487. package/packages/apra-fleet-se/src/supervisor/ledger.mjs +629 -0
  488. package/packages/apra-fleet-se/src/supervisor/lib/exec-bd.mjs +303 -0
  489. package/packages/apra-fleet-se/src/supervisor/log-timestamp.mjs +51 -0
  490. package/packages/apra-fleet-se/src/supervisor/log-view.mjs +159 -0
  491. package/packages/apra-fleet-se/src/supervisor/proxy.mjs +474 -0
  492. package/packages/apra-fleet-se/src/supervisor/readopt.mjs +136 -0
  493. package/packages/apra-fleet-se/src/supervisor/reconcile.mjs +263 -0
  494. package/packages/apra-fleet-se/src/supervisor/rename-with-retry.mjs +87 -0
  495. package/packages/apra-fleet-se/src/supervisor/scope-overlap.mjs +327 -0
  496. package/packages/apra-fleet-se/src/supervisor/self-log.mjs +133 -0
  497. package/packages/apra-fleet-se/src/supervisor/server.mjs +399 -0
  498. package/packages/apra-fleet-se/src/supervisor/spawner.mjs +542 -0
  499. package/packages/apra-fleet-se/src/supervisor/sprint-identity.mjs +96 -0
  500. package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +987 -0
  501. package/packages/apra-fleet-workflow/package.json +1 -1
  502. package/packages/apra-fleet-workflow/src/viewer/index.mjs +81 -15
  503. package/packages/apra-fleet-workflow/src/viewer/run-summary.mjs +127 -0
  504. package/packages/apra-fleet-workflow/src/workflow/index.mjs +118 -10
  505. package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +75 -25
  506. package/skills/fleet/SKILL.md +8 -8
  507. package/skills/fleet/auth-azdevops.md +14 -3
  508. package/skills/fleet/auth-bitbucket.md +2 -2
  509. package/skills/fleet/auth-github.md +5 -4
  510. package/skills/fleet/onboarding.md +3 -3
  511. package/skills/fleet/permissions.md +14 -1
  512. package/skills/fleet/profiles/node.json +1 -1
  513. package/skills/fleet/profiles/tag-kb-reconciler.json +2 -6
  514. package/skills/fleet/troubleshooting.md +3 -3
  515. package/version.json +1 -1
  516. package/dist/cli/agent-transform.d.ts.map +0 -1
  517. package/dist/cli/agent-transform.js.map +0 -1
  518. package/dist/cli/auth.d.ts.map +0 -1
  519. package/dist/cli/auth.js.map +0 -1
  520. package/dist/cli/config.d.ts.map +0 -1
  521. package/dist/cli/config.js.map +0 -1
  522. package/dist/cli/dolt-install.d.ts.map +0 -1
  523. package/dist/cli/dolt-install.js.map +0 -1
  524. package/dist/cli/install-guard.d.ts.map +0 -1
  525. package/dist/cli/install-guard.js.map +0 -1
  526. package/dist/cli/install.d.ts.map +0 -1
  527. package/dist/cli/install.js.map +0 -1
  528. package/dist/cli/join.d.ts.map +0 -1
  529. package/dist/cli/join.js.map +0 -1
  530. package/dist/cli/kb-commit.d.ts.map +0 -1
  531. package/dist/cli/kb-commit.js.map +0 -1
  532. package/dist/cli/kb-directives.d.ts.map +0 -1
  533. package/dist/cli/kb-directives.js.map +0 -1
  534. package/dist/cli/kb-import.d.ts.map +0 -1
  535. package/dist/cli/kb-import.js.map +0 -1
  536. package/dist/cli/register-member.d.ts.map +0 -1
  537. package/dist/cli/register-member.js.map +0 -1
  538. package/dist/cli/restart.d.ts.map +0 -1
  539. package/dist/cli/restart.js.map +0 -1
  540. package/dist/cli/secret.d.ts.map +0 -1
  541. package/dist/cli/secret.js.map +0 -1
  542. package/dist/cli/spoke.d.ts.map +0 -1
  543. package/dist/cli/spoke.js.map +0 -1
  544. package/dist/cli/start.d.ts.map +0 -1
  545. package/dist/cli/start.js.map +0 -1
  546. package/dist/cli/status.d.ts.map +0 -1
  547. package/dist/cli/status.js.map +0 -1
  548. package/dist/cli/stop.d.ts.map +0 -1
  549. package/dist/cli/stop.js.map +0 -1
  550. package/dist/cli/uninstall.d.ts.map +0 -1
  551. package/dist/cli/uninstall.js.map +0 -1
  552. package/dist/cli/update.d.ts.map +0 -1
  553. package/dist/cli/update.js.map +0 -1
  554. package/dist/cli/watch.d.ts.map +0 -1
  555. package/dist/cli/watch.js.map +0 -1
  556. package/dist/cli/workflow-assets.d.ts.map +0 -1
  557. package/dist/cli/workflow-assets.js.map +0 -1
  558. package/dist/cli/workflow.d.ts.map +0 -1
  559. package/dist/cli/workflow.js.map +0 -1
  560. package/dist/commands/kb-server.d.ts.map +0 -1
  561. package/dist/commands/kb-server.js.map +0 -1
  562. package/dist/delivery-mode.d.ts.map +0 -1
  563. package/dist/delivery-mode.js.map +0 -1
  564. package/dist/hub-service/activity.d.ts.map +0 -1
  565. package/dist/hub-service/activity.js.map +0 -1
  566. package/dist/hub-service/audit-log.d.ts.map +0 -1
  567. package/dist/hub-service/audit-log.js.map +0 -1
  568. package/dist/hub-service/db/pool.d.ts.map +0 -1
  569. package/dist/hub-service/db/pool.js.map +0 -1
  570. package/dist/hub-service/enrollment.d.ts.map +0 -1
  571. package/dist/hub-service/enrollment.js.map +0 -1
  572. package/dist/hub-service/envelope-routes.d.ts.map +0 -1
  573. package/dist/hub-service/envelope-routes.js.map +0 -1
  574. package/dist/hub-service/handlers/installers.d.ts.map +0 -1
  575. package/dist/hub-service/handlers/installers.js.map +0 -1
  576. package/dist/hub-service/http-server.d.ts.map +0 -1
  577. package/dist/hub-service/http-server.js.map +0 -1
  578. package/dist/hub-service/hub-jwt.d.ts.map +0 -1
  579. package/dist/hub-service/hub-jwt.js.map +0 -1
  580. package/dist/hub-service/jwt-revocation.d.ts.map +0 -1
  581. package/dist/hub-service/jwt-revocation.js.map +0 -1
  582. package/dist/hub-service/machines.d.ts.map +0 -1
  583. package/dist/hub-service/machines.js.map +0 -1
  584. package/dist/hub-service/main.d.ts.map +0 -1
  585. package/dist/hub-service/main.js.map +0 -1
  586. package/dist/hub-service/member-tokens.d.ts.map +0 -1
  587. package/dist/hub-service/member-tokens.js.map +0 -1
  588. package/dist/hub-service/member-view.d.ts.map +0 -1
  589. package/dist/hub-service/member-view.js.map +0 -1
  590. package/dist/hub-service/members.d.ts.map +0 -1
  591. package/dist/hub-service/members.js.map +0 -1
  592. package/dist/hub-service/presence.d.ts.map +0 -1
  593. package/dist/hub-service/presence.js.map +0 -1
  594. package/dist/hub-service/project-view.d.ts.map +0 -1
  595. package/dist/hub-service/project-view.js.map +0 -1
  596. package/dist/hub-service/projects.d.ts.map +0 -1
  597. package/dist/hub-service/projects.js.map +0 -1
  598. package/dist/hub-service/relay-queue.d.ts.map +0 -1
  599. package/dist/hub-service/relay-queue.js.map +0 -1
  600. package/dist/hub-service/session-jwt.d.ts.map +0 -1
  601. package/dist/hub-service/session-jwt.js.map +0 -1
  602. package/dist/hub-service/usage.d.ts.map +0 -1
  603. package/dist/hub-service/usage.js.map +0 -1
  604. package/dist/hub-service/users.d.ts.map +0 -1
  605. package/dist/hub-service/users.js.map +0 -1
  606. package/dist/hub-service/workspaces.d.ts.map +0 -1
  607. package/dist/hub-service/workspaces.js.map +0 -1
  608. package/dist/index.d.ts.map +0 -1
  609. package/dist/index.js.map +0 -1
  610. package/dist/onboarding/text.d.ts.map +0 -1
  611. package/dist/onboarding/text.js.map +0 -1
  612. package/dist/os/git-bash-candidates.d.ts.map +0 -1
  613. package/dist/os/git-bash-candidates.js.map +0 -1
  614. package/dist/os/index.d.ts.map +0 -1
  615. package/dist/os/index.js.map +0 -1
  616. package/dist/os/linux.d.ts.map +0 -1
  617. package/dist/os/linux.js.map +0 -1
  618. package/dist/os/macos.d.ts.map +0 -1
  619. package/dist/os/macos.js.map +0 -1
  620. package/dist/os/os-commands.d.ts.map +0 -1
  621. package/dist/os/os-commands.js.map +0 -1
  622. package/dist/os/windows-gitbash.d.ts.map +0 -1
  623. package/dist/os/windows-gitbash.js.map +0 -1
  624. package/dist/os/windows-wrapper.d.ts.map +0 -1
  625. package/dist/os/windows-wrapper.js.map +0 -1
  626. package/dist/os/windows.d.ts.map +0 -1
  627. package/dist/os/windows.js.map +0 -1
  628. package/dist/paths.d.ts.map +0 -1
  629. package/dist/paths.js.map +0 -1
  630. package/dist/providers/agy.d.ts.map +0 -1
  631. package/dist/providers/agy.js.map +0 -1
  632. package/dist/providers/claude.d.ts.map +0 -1
  633. package/dist/providers/claude.js.map +0 -1
  634. package/dist/providers/codex.d.ts.map +0 -1
  635. package/dist/providers/codex.js.map +0 -1
  636. package/dist/providers/copilot.d.ts.map +0 -1
  637. package/dist/providers/copilot.js.map +0 -1
  638. package/dist/providers/email/headers.d.ts.map +0 -1
  639. package/dist/providers/email/headers.js.map +0 -1
  640. package/dist/providers/email/index.d.ts.map +0 -1
  641. package/dist/providers/email/index.js.map +0 -1
  642. package/dist/providers/email/provider.d.ts.map +0 -1
  643. package/dist/providers/email/provider.js.map +0 -1
  644. package/dist/providers/email/sendgrid.d.ts.map +0 -1
  645. package/dist/providers/email/sendgrid.js.map +0 -1
  646. package/dist/providers/email/smtp.d.ts.map +0 -1
  647. package/dist/providers/email/smtp.js.map +0 -1
  648. package/dist/providers/index.d.ts.map +0 -1
  649. package/dist/providers/index.js.map +0 -1
  650. package/dist/providers/none.d.ts.map +0 -1
  651. package/dist/providers/none.js.map +0 -1
  652. package/dist/providers/opencode.d.ts.map +0 -1
  653. package/dist/providers/opencode.js.map +0 -1
  654. package/dist/providers/provider.d.ts.map +0 -1
  655. package/dist/providers/provider.js.map +0 -1
  656. package/dist/services/agent-provisioner.d.ts.map +0 -1
  657. package/dist/services/agent-provisioner.js.map +0 -1
  658. package/dist/services/auth-socket.d.ts.map +0 -1
  659. package/dist/services/auth-socket.js.map +0 -1
  660. package/dist/services/auth-web.d.ts.map +0 -1
  661. package/dist/services/auth-web.js.map +0 -1
  662. package/dist/services/budget-awareness.d.ts.map +0 -1
  663. package/dist/services/budget-awareness.js.map +0 -1
  664. package/dist/services/cloud/activity.d.ts.map +0 -1
  665. package/dist/services/cloud/activity.js.map +0 -1
  666. package/dist/services/cloud/aws.d.ts.map +0 -1
  667. package/dist/services/cloud/aws.js.map +0 -1
  668. package/dist/services/cloud/cost.d.ts.map +0 -1
  669. package/dist/services/cloud/cost.js.map +0 -1
  670. package/dist/services/cloud/idle-manager.d.ts.map +0 -1
  671. package/dist/services/cloud/idle-manager.js.map +0 -1
  672. package/dist/services/cloud/lifecycle.d.ts.map +0 -1
  673. package/dist/services/cloud/lifecycle.js.map +0 -1
  674. package/dist/services/cloud/task-wrapper.d.ts.map +0 -1
  675. package/dist/services/cloud/task-wrapper.js.map +0 -1
  676. package/dist/services/cloud/types.d.ts.map +0 -1
  677. package/dist/services/cloud/types.js.map +0 -1
  678. package/dist/services/cloud-sync.d.ts.map +0 -1
  679. package/dist/services/cloud-sync.js.map +0 -1
  680. package/dist/services/context-admission.d.ts.map +0 -1
  681. package/dist/services/context-admission.js.map +0 -1
  682. package/dist/services/credential-cleanup.d.ts.map +0 -1
  683. package/dist/services/credential-cleanup.js.map +0 -1
  684. package/dist/services/credential-store.d.ts.map +0 -1
  685. package/dist/services/credential-store.js.map +0 -1
  686. package/dist/services/event-bus.d.ts.map +0 -1
  687. package/dist/services/event-bus.js.map +0 -1
  688. package/dist/services/file-chunker.d.ts.map +0 -1
  689. package/dist/services/file-chunker.js.map +0 -1
  690. package/dist/services/file-transfer-relay.d.ts.map +0 -1
  691. package/dist/services/file-transfer-relay.js.map +0 -1
  692. package/dist/services/file-transfer.d.ts.map +0 -1
  693. package/dist/services/file-transfer.js.map +0 -1
  694. package/dist/services/git-config.d.ts.map +0 -1
  695. package/dist/services/git-config.js.map +0 -1
  696. package/dist/services/github-app.d.ts.map +0 -1
  697. package/dist/services/github-app.js.map +0 -1
  698. package/dist/services/http-transport.d.ts.map +0 -1
  699. package/dist/services/http-transport.js.map +0 -1
  700. package/dist/services/hub-client.d.ts.map +0 -1
  701. package/dist/services/hub-client.js.map +0 -1
  702. package/dist/services/icons.d.ts.map +0 -1
  703. package/dist/services/icons.js.map +0 -1
  704. package/dist/services/jwt.d.ts.map +0 -1
  705. package/dist/services/jwt.js.map +0 -1
  706. package/dist/services/knowledge/audn.d.ts.map +0 -1
  707. package/dist/services/knowledge/audn.js.map +0 -1
  708. package/dist/services/knowledge/file-hash.d.ts.map +0 -1
  709. package/dist/services/knowledge/file-hash.js.map +0 -1
  710. package/dist/services/knowledge/http-provider.d.ts.map +0 -1
  711. package/dist/services/knowledge/http-provider.js.map +0 -1
  712. package/dist/services/knowledge/kb-providers.d.ts.map +0 -1
  713. package/dist/services/knowledge/kb-providers.js.map +0 -1
  714. package/dist/services/knowledge/kb-scope-input.d.ts +0 -5
  715. package/dist/services/knowledge/kb-scope-input.d.ts.map +0 -1
  716. package/dist/services/knowledge/kb-scope-input.js +0 -11
  717. package/dist/services/knowledge/kb-scope-input.js.map +0 -1
  718. package/dist/services/knowledge/kb-service.d.ts.map +0 -1
  719. package/dist/services/knowledge/kb-service.js.map +0 -1
  720. package/dist/services/knowledge/path-validation.d.ts.map +0 -1
  721. package/dist/services/knowledge/path-validation.js.map +0 -1
  722. package/dist/services/knowledge/pre-init.d.ts.map +0 -1
  723. package/dist/services/knowledge/pre-init.js.map +0 -1
  724. package/dist/services/knowledge/project-slug.d.ts.map +0 -1
  725. package/dist/services/knowledge/project-slug.js.map +0 -1
  726. package/dist/services/knowledge/sqlite-provider.d.ts.map +0 -1
  727. package/dist/services/knowledge/sqlite-provider.js.map +0 -1
  728. package/dist/services/knowledge/types.d.ts.map +0 -1
  729. package/dist/services/knowledge/types.js.map +0 -1
  730. package/dist/services/known-hosts.d.ts.map +0 -1
  731. package/dist/services/known-hosts.js.map +0 -1
  732. package/dist/services/known-sessions.d.ts.map +0 -1
  733. package/dist/services/known-sessions.js.map +0 -1
  734. package/dist/services/member-home.d.ts.map +0 -1
  735. package/dist/services/member-home.js.map +0 -1
  736. package/dist/services/member-remote-url.d.ts.map +0 -1
  737. package/dist/services/member-remote-url.js.map +0 -1
  738. package/dist/services/model-pricing.d.ts.map +0 -1
  739. package/dist/services/model-pricing.js.map +0 -1
  740. package/dist/services/onboarding.d.ts.map +0 -1
  741. package/dist/services/onboarding.js.map +0 -1
  742. package/dist/services/orphan-recovery.d.ts.map +0 -1
  743. package/dist/services/orphan-recovery.js.map +0 -1
  744. package/dist/services/pending-responses.d.ts.map +0 -1
  745. package/dist/services/pending-responses.js.map +0 -1
  746. package/dist/services/preflight-check.d.ts.map +0 -1
  747. package/dist/services/preflight-check.js.map +0 -1
  748. package/dist/services/registry.d.ts.map +0 -1
  749. package/dist/services/registry.js.map +0 -1
  750. package/dist/services/relay-context.d.ts.map +0 -1
  751. package/dist/services/relay-context.js.map +0 -1
  752. package/dist/services/relay-executor.d.ts.map +0 -1
  753. package/dist/services/relay-executor.js.map +0 -1
  754. package/dist/services/relay-request.d.ts.map +0 -1
  755. package/dist/services/relay-request.js.map +0 -1
  756. package/dist/services/relay-strategy.d.ts.map +0 -1
  757. package/dist/services/relay-strategy.js.map +0 -1
  758. package/dist/services/service-manager/index.d.ts.map +0 -1
  759. package/dist/services/service-manager/index.js.map +0 -1
  760. package/dist/services/service-manager/linux.d.ts.map +0 -1
  761. package/dist/services/service-manager/linux.js.map +0 -1
  762. package/dist/services/service-manager/macos.d.ts.map +0 -1
  763. package/dist/services/service-manager/macos.js.map +0 -1
  764. package/dist/services/service-manager/types.d.ts.map +0 -1
  765. package/dist/services/service-manager/types.js.map +0 -1
  766. package/dist/services/service-manager/windows.d.ts.map +0 -1
  767. package/dist/services/service-manager/windows.js.map +0 -1
  768. package/dist/services/session-registry.d.ts.map +0 -1
  769. package/dist/services/session-registry.js.map +0 -1
  770. package/dist/services/sftp.d.ts.map +0 -1
  771. package/dist/services/sftp.js.map +0 -1
  772. package/dist/services/shell-probe.d.ts.map +0 -1
  773. package/dist/services/shell-probe.js.map +0 -1
  774. package/dist/services/singleton.d.ts.map +0 -1
  775. package/dist/services/singleton.js.map +0 -1
  776. package/dist/services/sprint-coordination.d.ts.map +0 -1
  777. package/dist/services/sprint-coordination.js.map +0 -1
  778. package/dist/services/ssh.d.ts.map +0 -1
  779. package/dist/services/ssh.js.map +0 -1
  780. package/dist/services/stall/find-log-file.d.ts.map +0 -1
  781. package/dist/services/stall/find-log-file.js.map +0 -1
  782. package/dist/services/stall/index.d.ts.map +0 -1
  783. package/dist/services/stall/index.js.map +0 -1
  784. package/dist/services/stall/log-path-resolver.d.ts.map +0 -1
  785. package/dist/services/stall/log-path-resolver.js.map +0 -1
  786. package/dist/services/stall/read-log-tail.d.ts.map +0 -1
  787. package/dist/services/stall/read-log-tail.js.map +0 -1
  788. package/dist/services/stall/stall-detector.d.ts.map +0 -1
  789. package/dist/services/stall/stall-detector.js.map +0 -1
  790. package/dist/services/stall/stall-poller.d.ts.map +0 -1
  791. package/dist/services/stall/stall-poller.js.map +0 -1
  792. package/dist/services/stall/time-utils.d.ts.map +0 -1
  793. package/dist/services/stall/time-utils.js.map +0 -1
  794. package/dist/services/statusline.d.ts.map +0 -1
  795. package/dist/services/statusline.js.map +0 -1
  796. package/dist/services/strategy.d.ts.map +0 -1
  797. package/dist/services/strategy.js.map +0 -1
  798. package/dist/services/substitution-engine.d.ts.map +0 -1
  799. package/dist/services/substitution-engine.js.map +0 -1
  800. package/dist/services/task-cleanup.d.ts.map +0 -1
  801. package/dist/services/task-cleanup.js.map +0 -1
  802. package/dist/services/token-issuer.d.ts.map +0 -1
  803. package/dist/services/token-issuer.js.map +0 -1
  804. package/dist/services/tool-registry.d.ts.map +0 -1
  805. package/dist/services/tool-registry.js.map +0 -1
  806. package/dist/services/update-check.d.ts.map +0 -1
  807. package/dist/services/update-check.js.map +0 -1
  808. package/dist/services/user-config.d.ts.map +0 -1
  809. package/dist/services/user-config.js.map +0 -1
  810. package/dist/services/vcs/azure-devops.d.ts.map +0 -1
  811. package/dist/services/vcs/azure-devops.js.map +0 -1
  812. package/dist/services/vcs/bitbucket.d.ts.map +0 -1
  813. package/dist/services/vcs/bitbucket.js.map +0 -1
  814. package/dist/services/vcs/constants.d.ts.map +0 -1
  815. package/dist/services/vcs/constants.js.map +0 -1
  816. package/dist/services/vcs/github.d.ts.map +0 -1
  817. package/dist/services/vcs/github.js.map +0 -1
  818. package/dist/services/vcs/types.d.ts.map +0 -1
  819. package/dist/services/vcs/types.js.map +0 -1
  820. package/dist/services/version-check.d.ts.map +0 -1
  821. package/dist/services/version-check.js.map +0 -1
  822. package/dist/services/watch/fleet-log.d.ts.map +0 -1
  823. package/dist/services/watch/fleet-log.js.map +0 -1
  824. package/dist/services/watch/project-resolver.d.ts.map +0 -1
  825. package/dist/services/watch/project-resolver.js.map +0 -1
  826. package/dist/services/watch/transcript-formatter.d.ts.map +0 -1
  827. package/dist/services/watch/transcript-formatter.js.map +0 -1
  828. package/dist/smoke-test.d.ts.map +0 -1
  829. package/dist/smoke-test.js.map +0 -1
  830. package/dist/tools/check-status.d.ts.map +0 -1
  831. package/dist/tools/check-status.js.map +0 -1
  832. package/dist/tools/child-id-allocator.d.ts.map +0 -1
  833. package/dist/tools/child-id-allocator.js.map +0 -1
  834. package/dist/tools/cloud-control.d.ts.map +0 -1
  835. package/dist/tools/cloud-control.js.map +0 -1
  836. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +0 -1
  837. package/dist/tools/code-intelligence-codebase-memory.js.map +0 -1
  838. package/dist/tools/code-intelligence-freshness.d.ts.map +0 -1
  839. package/dist/tools/code-intelligence-freshness.js.map +0 -1
  840. package/dist/tools/code-intelligence-gitnexus.d.ts.map +0 -1
  841. package/dist/tools/code-intelligence-gitnexus.js.map +0 -1
  842. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +0 -1
  843. package/dist/tools/code-intelligence-kb-enrich.js.map +0 -1
  844. package/dist/tools/code-intelligence-reindex.d.ts.map +0 -1
  845. package/dist/tools/code-intelligence-reindex.js.map +0 -1
  846. package/dist/tools/code-intelligence-telemetry.d.ts.map +0 -1
  847. package/dist/tools/code-intelligence-telemetry.js.map +0 -1
  848. package/dist/tools/code-intelligence-tests.d.ts.map +0 -1
  849. package/dist/tools/code-intelligence-tests.js.map +0 -1
  850. package/dist/tools/code-intelligence.d.ts.map +0 -1
  851. package/dist/tools/code-intelligence.js.map +0 -1
  852. package/dist/tools/compose-permissions.d.ts.map +0 -1
  853. package/dist/tools/compose-permissions.js.map +0 -1
  854. package/dist/tools/credential-store-delete.d.ts.map +0 -1
  855. package/dist/tools/credential-store-delete.js.map +0 -1
  856. package/dist/tools/credential-store-list.d.ts.map +0 -1
  857. package/dist/tools/credential-store-list.js.map +0 -1
  858. package/dist/tools/credential-store-set.d.ts.map +0 -1
  859. package/dist/tools/credential-store-set.js.map +0 -1
  860. package/dist/tools/credential-store-update.d.ts.map +0 -1
  861. package/dist/tools/credential-store-update.js.map +0 -1
  862. package/dist/tools/dolt-push-mutex.d.ts.map +0 -1
  863. package/dist/tools/dolt-push-mutex.js.map +0 -1
  864. package/dist/tools/execute-command.d.ts.map +0 -1
  865. package/dist/tools/execute-command.js.map +0 -1
  866. package/dist/tools/execute-prompt.d.ts.map +0 -1
  867. package/dist/tools/execute-prompt.js.map +0 -1
  868. package/dist/tools/get-member-model-pricing.d.ts.map +0 -1
  869. package/dist/tools/get-member-model-pricing.js.map +0 -1
  870. package/dist/tools/kb-capture.d.ts.map +0 -1
  871. package/dist/tools/kb-capture.js.map +0 -1
  872. package/dist/tools/kb-context.d.ts.map +0 -1
  873. package/dist/tools/kb-context.js.map +0 -1
  874. package/dist/tools/kb-export.d.ts.map +0 -1
  875. package/dist/tools/kb-export.js.map +0 -1
  876. package/dist/tools/kb-feedback.d.ts.map +0 -1
  877. package/dist/tools/kb-feedback.js.map +0 -1
  878. package/dist/tools/kb-freshness-sweep.d.ts.map +0 -1
  879. package/dist/tools/kb-freshness-sweep.js.map +0 -1
  880. package/dist/tools/kb-harvest.d.ts.map +0 -1
  881. package/dist/tools/kb-harvest.js.map +0 -1
  882. package/dist/tools/kb-import.d.ts.map +0 -1
  883. package/dist/tools/kb-import.js.map +0 -1
  884. package/dist/tools/kb-invalidate.d.ts.map +0 -1
  885. package/dist/tools/kb-invalidate.js.map +0 -1
  886. package/dist/tools/kb-list.d.ts.map +0 -1
  887. package/dist/tools/kb-list.js.map +0 -1
  888. package/dist/tools/kb-promote.d.ts.map +0 -1
  889. package/dist/tools/kb-promote.js.map +0 -1
  890. package/dist/tools/kb-query.d.ts.map +0 -1
  891. package/dist/tools/kb-query.js.map +0 -1
  892. package/dist/tools/kb-reconcile-prefilter.d.ts.map +0 -1
  893. package/dist/tools/kb-reconcile-prefilter.js.map +0 -1
  894. package/dist/tools/kb-resolve-contradiction.d.ts.map +0 -1
  895. package/dist/tools/kb-resolve-contradiction.js.map +0 -1
  896. package/dist/tools/kb-session-prime.d.ts.map +0 -1
  897. package/dist/tools/kb-session-prime.js.map +0 -1
  898. package/dist/tools/kb-setup.d.ts.map +0 -1
  899. package/dist/tools/kb-setup.js.map +0 -1
  900. package/dist/tools/kb-stats.d.ts.map +0 -1
  901. package/dist/tools/kb-stats.js.map +0 -1
  902. package/dist/tools/list-members.d.ts.map +0 -1
  903. package/dist/tools/list-members.js.map +0 -1
  904. package/dist/tools/member-detail.d.ts.map +0 -1
  905. package/dist/tools/member-detail.js.map +0 -1
  906. package/dist/tools/member-reservation.d.ts.map +0 -1
  907. package/dist/tools/member-reservation.js.map +0 -1
  908. package/dist/tools/monitor-task.d.ts.map +0 -1
  909. package/dist/tools/monitor-task.js.map +0 -1
  910. package/dist/tools/provision-auth.d.ts.map +0 -1
  911. package/dist/tools/provision-auth.js.map +0 -1
  912. package/dist/tools/provision-vcs-auth.d.ts.map +0 -1
  913. package/dist/tools/provision-vcs-auth.js.map +0 -1
  914. package/dist/tools/receive-files.d.ts.map +0 -1
  915. package/dist/tools/receive-files.js.map +0 -1
  916. package/dist/tools/register-member.d.ts.map +0 -1
  917. package/dist/tools/register-member.js.map +0 -1
  918. package/dist/tools/remove-member.d.ts.map +0 -1
  919. package/dist/tools/remove-member.js.map +0 -1
  920. package/dist/tools/report-status.d.ts.map +0 -1
  921. package/dist/tools/report-status.js.map +0 -1
  922. package/dist/tools/respond-to-message.d.ts.map +0 -1
  923. package/dist/tools/respond-to-message.js.map +0 -1
  924. package/dist/tools/revoke-vcs-auth.d.ts.map +0 -1
  925. package/dist/tools/revoke-vcs-auth.js.map +0 -1
  926. package/dist/tools/send-email.d.ts.map +0 -1
  927. package/dist/tools/send-email.js.map +0 -1
  928. package/dist/tools/send-files.d.ts.map +0 -1
  929. package/dist/tools/send-files.js.map +0 -1
  930. package/dist/tools/send-message.d.ts.map +0 -1
  931. package/dist/tools/send-message.js.map +0 -1
  932. package/dist/tools/setup-git-app.d.ts.map +0 -1
  933. package/dist/tools/setup-git-app.js.map +0 -1
  934. package/dist/tools/setup-ssh-key.d.ts.map +0 -1
  935. package/dist/tools/setup-ssh-key.js.map +0 -1
  936. package/dist/tools/shutdown-server.d.ts.map +0 -1
  937. package/dist/tools/shutdown-server.js.map +0 -1
  938. package/dist/tools/stop-prompt.d.ts.map +0 -1
  939. package/dist/tools/stop-prompt.js.map +0 -1
  940. package/dist/tools/update-agent-cli.d.ts.map +0 -1
  941. package/dist/tools/update-agent-cli.js.map +0 -1
  942. package/dist/tools/update-member.d.ts.map +0 -1
  943. package/dist/tools/update-member.js.map +0 -1
  944. package/dist/tools/version.d.ts.map +0 -1
  945. package/dist/tools/version.js.map +0 -1
  946. package/dist/types.d.ts.map +0 -1
  947. package/dist/types.js.map +0 -1
  948. package/dist/utils/agent-helpers.d.ts.map +0 -1
  949. package/dist/utils/agent-helpers.js.map +0 -1
  950. package/dist/utils/ansi.d.ts.map +0 -1
  951. package/dist/utils/ansi.js.map +0 -1
  952. package/dist/utils/auth-env.d.ts.map +0 -1
  953. package/dist/utils/auth-env.js.map +0 -1
  954. package/dist/utils/collect-secret.d.ts.map +0 -1
  955. package/dist/utils/collect-secret.js.map +0 -1
  956. package/dist/utils/credential-validation.d.ts.map +0 -1
  957. package/dist/utils/credential-validation.js.map +0 -1
  958. package/dist/utils/crypto.d.ts.map +0 -1
  959. package/dist/utils/crypto.js.map +0 -1
  960. package/dist/utils/deep-merge.d.ts.map +0 -1
  961. package/dist/utils/deep-merge.js.map +0 -1
  962. package/dist/utils/file-permissions.d.ts.map +0 -1
  963. package/dist/utils/file-permissions.js.map +0 -1
  964. package/dist/utils/gpu-parser.d.ts.map +0 -1
  965. package/dist/utils/gpu-parser.js.map +0 -1
  966. package/dist/utils/log-helpers.d.ts.map +0 -1
  967. package/dist/utils/log-helpers.js.map +0 -1
  968. package/dist/utils/oob-timeout.d.ts.map +0 -1
  969. package/dist/utils/oob-timeout.js.map +0 -1
  970. package/dist/utils/opencode-model-validation.d.ts.map +0 -1
  971. package/dist/utils/opencode-model-validation.js.map +0 -1
  972. package/dist/utils/pid-helpers.d.ts.map +0 -1
  973. package/dist/utils/pid-helpers.js.map +0 -1
  974. package/dist/utils/platform.d.ts.map +0 -1
  975. package/dist/utils/platform.js.map +0 -1
  976. package/dist/utils/process-utils.d.ts.map +0 -1
  977. package/dist/utils/process-utils.js.map +0 -1
  978. package/dist/utils/prompt-errors.d.ts.map +0 -1
  979. package/dist/utils/prompt-errors.js.map +0 -1
  980. package/dist/utils/resolve-member.d.ts.map +0 -1
  981. package/dist/utils/resolve-member.js.map +0 -1
  982. package/dist/utils/secure-input.d.ts.map +0 -1
  983. package/dist/utils/secure-input.js.map +0 -1
  984. package/dist/utils/session-caller.d.ts.map +0 -1
  985. package/dist/utils/session-caller.js.map +0 -1
  986. package/dist/utils/shell-escape.d.ts.map +0 -1
  987. package/dist/utils/shell-escape.js.map +0 -1
  988. package/dist/utils/skill-matrix.d.ts.map +0 -1
  989. package/dist/utils/skill-matrix.js.map +0 -1
  990. package/dist/utils/ssh-error-messages.d.ts.map +0 -1
  991. package/dist/utils/ssh-error-messages.js.map +0 -1
  992. package/dist/utils/work-folder-validation.d.ts.map +0 -1
  993. package/dist/utils/work-folder-validation.js.map +0 -1
  994. package/dist/utils/workspace-trust.d.ts.map +0 -1
  995. package/dist/utils/workspace-trust.js.map +0 -1
  996. package/dist/version.d.ts.map +0 -1
  997. package/dist/version.js.map +0 -1
@@ -0,0 +1,1895 @@
1
+ /**
2
+ * Member apra-fleet install service (apra-fleet-b4g.56.1).
3
+ *
4
+ * register_member / update_member use this to make sure a REMOTE member runs
5
+ * its own apra-fleet, at least as new as the orchestrator, installed in HTTP
6
+ * member mode (`install --llm <provider> --member --workflows none --transport
7
+ * http`). The flow is:
8
+ *
9
+ * 1. probe the member's own install for its version (`--version` on
10
+ * <member home>/.apra-fleet/bin/apra-fleet[.exe]);
11
+ * 2. if it is missing or older than this orchestrator build, pick an install
12
+ * source:
13
+ * - member OS+arch == orchestrator OS+arch AND the orchestrator runs as
14
+ * a single-executable binary -> copy the orchestrator's own executable;
15
+ * - otherwise -> the tagged GitHub release asset for the orchestrator's
16
+ * version, when one exists for the member's platform;
17
+ * - otherwise -> a typed `unavailable(<reason>)` result. Absence is an
18
+ * OBSERVATION, never a throw: the caller's registration still succeeds;
19
+ * 3. stage the installer under <member home>/.apra-fleet/staging and run it
20
+ * in member mode, then re-probe to confirm the installed version.
21
+ *
22
+ * The version probe is ported from closed PR 543 (branch
23
+ * fix/fleet-status-cwd-independent), including its PowerShell $LASTEXITCODE
24
+ * fix; that branch resolved a stdio launch descriptor, this one installs.
25
+ *
26
+ * Every member-bound command is built HERE in JavaScript for the member's
27
+ * OS/shell (isPosixShell, wrapPowerShellEncoded). No command contains a shell
28
+ * expansion token ($VAR, ~/, backticks): every path is resolved first from the
29
+ * member's probed home directory (member-home.ts) and passed as a quoted
30
+ * literal.
31
+ *
32
+ * Every transport (exec, file transfer, home probe, release download,
33
+ * orchestrator platform/executable/version) is injected through
34
+ * MemberFleetInstallDeps so tests drive the whole flow with a fake transport.
35
+ */
36
+ import crypto from 'node:crypto';
37
+ import fs from 'node:fs';
38
+ import os from 'node:os';
39
+ import path from 'node:path';
40
+ import { getStrategy } from './strategy.js';
41
+ import { getMemberHomeDir } from './member-home.js';
42
+ import { getAgentOS, getAgentShell, isPosixShell } from '../utils/agent-helpers.js';
43
+ import { escapePowerShellArgInner, escapeShellArgInner } from '../utils/shell-escape.js';
44
+ import { wrapPowerShellEncoded } from '../os/windows.js';
45
+ import { serverVersion } from '../version.js';
46
+ import { BUILTIN_DEFAULT_PORT, validPort } from '../paths.js';
47
+ import { FULL_INSTALL_RUNNING_CODE } from '../cli/install-guard.js';
48
+ import { parseVersion, isNewer } from './update-check.js';
49
+ import { recordFleetMcpStatus, updateAgent } from './registry.js';
50
+ import { encryptPassword } from '../utils/crypto.js';
51
+ import { ensureRemoteMemberAccessSecret } from './member-access-secret.js';
52
+ import { removeMemberSecretFile, writeMemberSecretFile } from './member-secret-env.js';
53
+ import { probeMemberClaudeConfigDir, claudeLocalScopeConfigFile } from '../providers/claude.js';
54
+ import { OPENCODE_PROJECT_CONFIG } from '../providers/opencode.js';
55
+ import { readMemberJson, joinMemberPath, memberFileExistsPosixCommand, memberFileExistsPwshCommand, resolveClaudeProjectKey, MEMBER_MCP_SERVER_NAME } from './member-config-io.js';
56
+ /** Emitted by the probe when the install path is not present/executable. */
57
+ export const NO_INSTALL_SENTINEL = '__APRA_FLEET_NO_INSTALL__';
58
+ /** Emitted by the probe when the path exists but running it failed. */
59
+ export const EXEC_FAILED_SENTINEL = '__APRA_FLEET_EXEC_FAILED__';
60
+ const PROBE_TIMEOUT_MS = 15_000;
61
+ const INSTALL_TIMEOUT_MS = 5 * 60_000;
62
+ /** GitHub repo the tagged release assets are published to (.github/workflows/ci.yml). */
63
+ export const RELEASE_REPO = 'Apra-Labs/apra-fleet';
64
+ /** `apra-fleet --version` prints `apra-fleet <version>` on its FIRST line
65
+ * (src/index.ts), e.g. `apra-fleet v0.4.4` or `apra-fleet v0.4.4_abc123` for
66
+ * a dev build. Scanned line-by-line so a shell banner on either side is
67
+ * skipped. */
68
+ const VERSION_LINE_RE = /^apra-fleet\s+(v?\d+\.\d+\.\d+\S*)\s*$/;
69
+ // ---------------------------------------------------------------------------
70
+ // Pure helpers (exported for tests)
71
+ // ---------------------------------------------------------------------------
72
+ /** Executable name apra-fleet installs itself as on the member's OS. */
73
+ export function binaryNameFor(targetOs) {
74
+ return targetOs === 'windows' ? 'apra-fleet.exe' : 'apra-fleet';
75
+ }
76
+ /** Join path segments with the member's separator. A POSIX shell on Windows
77
+ * (gitbash) has a POSIX-style home (/c/Users/x) and takes '/'. */
78
+ export function memberJoin(targetOs, shell, ...parts) {
79
+ const sep = isPosixShell(targetOs, shell) ? '/' : '\\';
80
+ const trimmed = parts.map((p, i) => (i === 0 ? p.replace(/[\\/]+$/, '') : p.replace(/^[\\/]+|[\\/]+$/g, '')));
81
+ return trimmed.filter(p => p.length > 0).join(sep);
82
+ }
83
+ /** Pick the POSIX or PowerShell form of a member-bound command. PowerShell is
84
+ * always delivered via -EncodedCommand so no intermediate shell re-tokenizes it. */
85
+ export function memberCommandFor(targetOs, shell, forms) {
86
+ return isPosixShell(targetOs, shell) ? forms.posix : wrapPowerShellEncoded(forms.powershell);
87
+ }
88
+ function posixQuote(s) {
89
+ return `'${escapeShellArgInner(s)}'`;
90
+ }
91
+ function psQuote(s) {
92
+ return `'${escapePowerShellArgInner(s)}'`;
93
+ }
94
+ /**
95
+ * The member-side version probe, built from an already-resolved absolute path.
96
+ *
97
+ * Both branches exit 0 and TAG their outcome in stdout, so a non-zero exit
98
+ * means "the shell/transport itself failed" and nothing else.
99
+ *
100
+ * POWERSHELL BRANCH -- DO NOT "SIMPLIFY" THE $LASTEXITCODE TEST OR THE TRAILING
101
+ * `exit 0` (ported from PR 543). PowerShell raises NO terminating error when a
102
+ * NATIVE executable exits non-zero, so a bare try/catch never reaches its catch
103
+ * for a present-but-broken install: the probe would return partial stdout (which
104
+ * may even look like a version) and wrapPowerShellEncoded would propagate the
105
+ * leftover $LASTEXITCODE as the exit code. The explicit $LASTEXITCODE branch
106
+ * reports such an install as EXEC_FAILED instead of reading its output as a
107
+ * version; the catch still covers a path that cannot be launched at all.
108
+ */
109
+ export function buildFleetVersionProbe(binPath, targetOs, shell) {
110
+ const p = posixQuote(binPath);
111
+ const ps = psQuote(binPath);
112
+ return memberCommandFor(targetOs, shell, {
113
+ posix: `if [ -x ${p} ]; then ${p} --version 2>/dev/null || ` +
114
+ `printf '%s\\n' '${EXEC_FAILED_SENTINEL}'; else printf '%s\\n' '${NO_INSTALL_SENTINEL}'; fi`,
115
+ powershell: `if (Test-Path -LiteralPath ${ps}) { try { $out = & ${ps} --version; ` +
116
+ `if ($LASTEXITCODE -ne 0) { [Console]::Out.Write('${EXEC_FAILED_SENTINEL}') } ` +
117
+ `else { [Console]::Out.Write(($out | Out-String)) } } catch ` +
118
+ `{ [Console]::Out.Write('${EXEC_FAILED_SENTINEL}') } } else ` +
119
+ `{ [Console]::Out.Write('${NO_INSTALL_SENTINEL}') }; exit 0`,
120
+ });
121
+ }
122
+ /** The member's CPU architecture, as one raw token on stdout. */
123
+ export function buildArchProbe(targetOs, shell) {
124
+ return memberCommandFor(targetOs, shell, {
125
+ posix: 'uname -m',
126
+ powershell: '[Console]::Out.Write($env:PROCESSOR_ARCHITECTURE)',
127
+ });
128
+ }
129
+ /** Normalize uname -m / PROCESSOR_ARCHITECTURE output to Node's process.arch names. */
130
+ export function normalizeArch(raw) {
131
+ const token = raw.split(/\r?\n/).map(l => l.trim()).filter(Boolean).pop()?.toLowerCase();
132
+ if (!token)
133
+ return null;
134
+ if (token === 'x86_64' || token === 'amd64' || token === 'x64')
135
+ return 'x64';
136
+ if (token === 'aarch64' || token === 'arm64' || token === 'armv8')
137
+ return 'arm64';
138
+ return token;
139
+ }
140
+ /** First `apra-fleet <version>` line in the probe output, or null. */
141
+ export function parseFleetVersion(stdout) {
142
+ for (const raw of stdout.split(/\r?\n/)) {
143
+ const m = VERSION_LINE_RE.exec(raw.trim());
144
+ if (m && parseVersion(m[1]))
145
+ return m[1];
146
+ }
147
+ return null;
148
+ }
149
+ /** True when the member's version is older than the orchestrator's (semver
150
+ * core only; a dev build's _hash suffix is ignored). */
151
+ export function isOlderThan(memberVersion, orchestratorVersion) {
152
+ return isNewer(orchestratorVersion, memberVersion);
153
+ }
154
+ /** The `_build` suffix of a version ("v0.4.4_abc" -> "abc"), or "" when none. */
155
+ function buildSuffixOf(version) {
156
+ const i = version.indexOf('_');
157
+ return i < 0 ? '' : version.slice(i + 1);
158
+ }
159
+ /**
160
+ * Build-aware outdated check for the member install (exported for tests).
161
+ * Rule: a member core OLDER than the orchestrator's is always outdated; a
162
+ * NEWER core never is (never downgrade, whatever the suffixes). At the SAME
163
+ * core, a differing build suffix counts as outdated only when
164
+ * `canSupplyOrchestratorBuild` -- i.e. the source installs exactly the
165
+ * orchestrator's build: its own executable, or (suffixed orchestrator) a
166
+ * release whose BUILD_INFO names that build (sourceSuppliesBuild). A bare
167
+ * release orchestrator installs whatever build its stable tag has, so a
168
+ * same-core build difference there is "up to date" (else it would reinstall
169
+ * on every registration and report install-unverified). Mixed
170
+ * suffix/no-suffix at the same core follows the same rule; identical
171
+ * versions are never outdated.
172
+ * isNewer/parseVersion (shared with the CLI self-update check) are untouched.
173
+ */
174
+ export function isMemberOutdated(memberVersion, orchestratorVersion, canSupplyOrchestratorBuild) {
175
+ if (isOlderThan(memberVersion, orchestratorVersion))
176
+ return true;
177
+ if (isNewer(memberVersion, orchestratorVersion))
178
+ return false;
179
+ return canSupplyOrchestratorBuild && buildSuffixOf(memberVersion) !== buildSuffixOf(orchestratorVersion);
180
+ }
181
+ /** Release asset names published by .github/workflows/ci.yml, by platform. */
182
+ export const RELEASE_ASSETS = {
183
+ 'linux/x64': 'apra-fleet-installer-linux-x64',
184
+ 'macos/arm64': 'apra-fleet-installer-darwin-arm64',
185
+ 'macos/x64': 'apra-fleet-installer-darwin-x64',
186
+ 'windows/x64': 'apra-fleet-installer-win-x64.exe',
187
+ };
188
+ export function releaseAssetNameFor(platform) {
189
+ return RELEASE_ASSETS[`${platform.os}/${platform.arch}`] ?? null;
190
+ }
191
+ /** `v0.4.4_abc123` -> `v0.4.4`: the STABLE release tag of a build's core version. */
192
+ export function releaseTagFor(version) {
193
+ return `v${version.replace(/^v/, '').split('_')[0]}`;
194
+ }
195
+ /** `v0.4.4_abc123` -> `v0.4.4_abc123`: the exact-build prerelease tag CI
196
+ * publishes for builds of its prerelease branches (ci.yml job prerelease),
197
+ * or null for a bare release version, which has no build to match. */
198
+ export function prereleaseTagFor(version) {
199
+ const v = version.startsWith('v') ? version : `v${version}`;
200
+ return buildSuffixOf(v) ? v : null;
201
+ }
202
+ /** Anonymous download URL of `fileName` in the release tagged `tag`. */
203
+ export function releaseFileUrl(tag, fileName) {
204
+ return `https://github.com/${RELEASE_REPO}/releases/download/${tag}/${fileName}`;
205
+ }
206
+ /** Human-browsable page of the release tagged `tag`. */
207
+ export function releasePageUrl(tag) {
208
+ return `https://github.com/${RELEASE_REPO}/releases/tag/${tag}`;
209
+ }
210
+ export function releaseCandidatesFor(version) {
211
+ const pre = prereleaseTagFor(version);
212
+ return [
213
+ { tag: releaseTagFor(version), channel: 'stable' },
214
+ ...(pre ? [{ tag: pre, channel: 'prerelease' }] : []),
215
+ ];
216
+ }
217
+ /** The URL the installer tries first for `version` (the stable release). */
218
+ export function releaseAssetUrl(version, assetName) {
219
+ return releaseFileUrl(releaseCandidatesFor(version)[0].tag, assetName);
220
+ }
221
+ /** True when a release source supplies exactly the orchestrator's build: a
222
+ * dev/branch build only ever accepts a release whose BUILD_INFO names that
223
+ * build, so the installed member reports the same suffix. A bare release
224
+ * version accepts any build of its core (the stable tag build). */
225
+ function releaseSuppliesExactBuild(orchestratorVersion) {
226
+ return buildSuffixOf(orchestratorVersion) !== '';
227
+ }
228
+ /** Whether the chosen source installs exactly the orchestrator's build. */
229
+ function sourceSuppliesBuild(source, orchestratorVersion) {
230
+ return source.kind === 'orchestrator-executable' || releaseSuppliesExactBuild(orchestratorVersion);
231
+ }
232
+ /**
233
+ * Choose where the member's install comes from (pure; exported for tests).
234
+ * same OS+arch and a copyable orchestrator executable -> that executable;
235
+ * otherwise a release asset for the member's platform;
236
+ * otherwise unavailable(<reason>).
237
+ */
238
+ export function chooseInstallSource(member, orchestrator, orchestratorExecutable, orchestratorVersion) {
239
+ const samePlatform = member.os === orchestrator.os && member.arch === orchestrator.arch;
240
+ if (samePlatform && orchestratorExecutable) {
241
+ return { kind: 'orchestrator-executable', localPath: orchestratorExecutable };
242
+ }
243
+ const assetName = releaseAssetNameFor(member);
244
+ if (assetName) {
245
+ return {
246
+ kind: 'release-asset', assetName,
247
+ url: releaseAssetUrl(orchestratorVersion, assetName),
248
+ candidates: releaseCandidatesFor(orchestratorVersion),
249
+ };
250
+ }
251
+ if (samePlatform) {
252
+ return {
253
+ kind: 'unavailable',
254
+ reason: 'no-install-source',
255
+ detail: `member platform ${member.os}/${member.arch} matches this orchestrator, but the orchestrator does not ` +
256
+ `run as a single-executable binary to copy and no release asset is published for that platform`,
257
+ };
258
+ }
259
+ return {
260
+ kind: 'unavailable',
261
+ reason: 'unsupported-platform',
262
+ detail: `member platform ${member.os}/${member.arch} differs from this orchestrator ` +
263
+ `(${orchestrator.os}/${orchestrator.arch}) and no apra-fleet release asset exists for it`,
264
+ };
265
+ }
266
+ /** The member-mode install command line arguments (exported for tests). */
267
+ export function memberInstallArgs(provider) {
268
+ // --force stops a running member server before the binary is replaced, so an
269
+ // upgrade of a live member does not abort on the running-process guard.
270
+ // --force-stop-full-install is NEVER added: the fleet cannot tell a human
271
+ // full install from an unmarked older member install, so overriding a
272
+ // refusal is left to the owner on the member (see buildFullInstallReplaceHint).
273
+ return ['install', '--llm', provider, '--member', '--workflows', 'none', '--transport', 'http', '--force'];
274
+ }
275
+ /** Command that makes the staged installer executable and runs it in member mode. */
276
+ export function buildInstallCommand(installerPath, provider, targetOs, shell) {
277
+ const args = memberInstallArgs(provider);
278
+ return memberCommandFor(targetOs, shell, {
279
+ posix: `chmod +x ${posixQuote(installerPath)} && ${posixQuote(installerPath)} ${args.map(posixQuote).join(' ')}`,
280
+ powershell: `& ${psQuote(installerPath)} ${args.map(psQuote).join(' ')}`,
281
+ });
282
+ }
283
+ // ---------------------------------------------------------------------------
284
+ // Production transports
285
+ // ---------------------------------------------------------------------------
286
+ function hostPlatform() {
287
+ const osName = process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'macos' : 'linux';
288
+ return { os: osName, arch: process.arch };
289
+ }
290
+ /** Bound on each release HTTP request (asset and checksum list). */
291
+ export const DOWNLOAD_TIMEOUT_MS = 120_000;
292
+ /** Name of the checksum list published next to the release assets (ci.yml release job). */
293
+ export const CHECKSUM_ASSET = 'SHA256SUMS';
294
+ /** Build marker published next to the release assets (ci.yml release and
295
+ * prerelease jobs): `version=<exact build version>` and `commit=<full sha>`
296
+ * lines, itself listed in SHA256SUMS. */
297
+ export const BUILD_INFO_ASSET = 'BUILD_INFO';
298
+ /** A typed download failure; ensureOnce maps `reason` onto the fleetMcp status. */
299
+ export class ReleaseDownloadError extends Error {
300
+ reason;
301
+ status;
302
+ constructor(reason, message,
303
+ /** HTTP status of the failed request, when it got an answer. */
304
+ status) {
305
+ super(message);
306
+ this.reason = reason;
307
+ this.status = status;
308
+ this.name = 'ReleaseDownloadError';
309
+ }
310
+ }
311
+ /** Map a download failure onto the install reason recorded in fleetMcp. */
312
+ function downloadFailureReason(err) {
313
+ if (!(err instanceof ReleaseDownloadError))
314
+ return 'download-failed';
315
+ if (err.reason === 'release-not-found' || err.reason === 'build-mismatch')
316
+ return 'no-matching-release';
317
+ return err.reason;
318
+ }
319
+ /** Parse BUILD_INFO (`key=value` lines). */
320
+ export function parseBuildInfo(text) {
321
+ const out = {};
322
+ for (const line of text.split(/\r?\n/)) {
323
+ const m = /^\s*(version|commit)\s*=\s*(\S+)\s*$/.exec(line);
324
+ if (m)
325
+ out[m[1]] = m[2];
326
+ }
327
+ return out;
328
+ }
329
+ /**
330
+ * Does a release's BUILD_INFO describe the build `expected` (the
331
+ * orchestrator's version)? A dev/branch build `v<x.y.z>_<sha6>` matches only
332
+ * the same version, or the same core built from a commit starting with that
333
+ * sha; a bare release version `v<x.y.z>` matches any build of that core.
334
+ */
335
+ export function buildInfoMatches(info, expected) {
336
+ if (!info.version)
337
+ return false;
338
+ const norm = (v) => (v.startsWith('v') ? v : `v${v}`);
339
+ const want = norm(expected);
340
+ const got = norm(info.version);
341
+ if (releaseTagFor(got) !== releaseTagFor(want))
342
+ return false;
343
+ const suffix = buildSuffixOf(want);
344
+ if (!suffix)
345
+ return true;
346
+ return got === want || (!!info.commit && info.commit.toLowerCase().startsWith(suffix.toLowerCase()));
347
+ }
348
+ /** The expected hex digest for `assetName` in a `sha256sum`-format list, or null. */
349
+ export function parseSha256Sums(text, assetName) {
350
+ for (const line of text.split(/\r?\n/)) {
351
+ const m = /^([0-9a-fA-F]{64})\s+\*?(\S+)\s*$/.exec(line.trim());
352
+ if (m && m[2] === assetName)
353
+ return m[1].toLowerCase();
354
+ }
355
+ return null;
356
+ }
357
+ /** Anonymous GET: no Authorization header, ever (release assets of the public
358
+ * repo download without a GitHub account). */
359
+ async function boundedGet(url, opts) {
360
+ const doFetch = opts.fetchImpl ?? fetch;
361
+ const timeoutMs = opts.timeoutMs ?? DOWNLOAD_TIMEOUT_MS;
362
+ try {
363
+ const res = await doFetch(url, {
364
+ headers: { 'User-Agent': `apra-fleet/${serverVersion}` },
365
+ signal: AbortSignal.timeout(timeoutMs),
366
+ });
367
+ if (!res.ok)
368
+ throw new ReleaseDownloadError('download-failed', `GET ${url} -> HTTP ${res.status}`, res.status);
369
+ return Buffer.from(await res.arrayBuffer());
370
+ }
371
+ catch (err) {
372
+ if (err instanceof ReleaseDownloadError)
373
+ throw err;
374
+ const name = err instanceof Error ? err.name : '';
375
+ if (name === 'TimeoutError' || name === 'AbortError') {
376
+ throw new ReleaseDownloadError('download-timeout', `GET ${url} did not complete within ${Math.round(timeoutMs / 1000)}s`);
377
+ }
378
+ throw new ReleaseDownloadError('download-failed', `GET ${url}: ${err instanceof Error ? err.message : String(err)}`);
379
+ }
380
+ }
381
+ /**
382
+ * Download a release asset to a temp file, bounded by a timeout, and verify its
383
+ * SHA-256 against the release's published SHA256SUMS before returning the path.
384
+ * Fails closed: a missing checksum is `checksum-unavailable`, a differing one
385
+ * `checksum-mismatch`; nothing unverified is ever written to disk.
386
+ */
387
+ export async function downloadVerifiedAsset(url, assetName, opts = {}) {
388
+ const base = url.slice(0, url.lastIndexOf('/') + 1);
389
+ const sumsUrl = base + CHECKSUM_ASSET;
390
+ let sums;
391
+ try {
392
+ sums = (await boundedGet(sumsUrl, opts)).toString('utf8');
393
+ }
394
+ catch (err) {
395
+ if (err instanceof ReleaseDownloadError && err.reason === 'download-timeout')
396
+ throw err;
397
+ if (opts.expectBuild && err instanceof ReleaseDownloadError && err.status === 404) {
398
+ throw new ReleaseDownloadError('release-not-found', `no release at ${base} (${sumsUrl} -> HTTP 404)`, 404);
399
+ }
400
+ // No HTTP answer at all (DNS, connection reset, TLS): a network failure,
401
+ // reported as such -- not as a missing checksum.
402
+ if (err instanceof ReleaseDownloadError && err.status === undefined)
403
+ throw err;
404
+ throw new ReleaseDownloadError('checksum-unavailable', `no published checksum could be fetched (${err instanceof Error ? err.message : String(err)})`);
405
+ }
406
+ if (opts.expectBuild) {
407
+ // The release must be THIS build: its BUILD_INFO, verified against the same
408
+ // SHA256SUMS, names the build version and commit.
409
+ const infoSha = parseSha256Sums(sums, BUILD_INFO_ASSET);
410
+ if (!infoSha)
411
+ throw new ReleaseDownloadError('build-mismatch', `${sumsUrl} lists no ${BUILD_INFO_ASSET}, so the release cannot be matched to build ${opts.expectBuild}`);
412
+ const infoBody = await boundedGet(base + BUILD_INFO_ASSET, opts);
413
+ if (crypto.createHash('sha256').update(infoBody).digest('hex') !== infoSha) {
414
+ throw new ReleaseDownloadError('checksum-mismatch', `${BUILD_INFO_ASSET} at ${base} does not match its published SHA256SUMS entry`);
415
+ }
416
+ const info = parseBuildInfo(infoBody.toString('utf8'));
417
+ if (!buildInfoMatches(info, opts.expectBuild)) {
418
+ throw new ReleaseDownloadError('build-mismatch', `the release at ${base} is build ${info.version ?? '(unnamed)'}${info.commit ? ` (commit ${info.commit.slice(0, 12)})` : ''}, not ${opts.expectBuild}`);
419
+ }
420
+ }
421
+ const expected = parseSha256Sums(sums, assetName);
422
+ if (!expected)
423
+ throw new ReleaseDownloadError('checksum-unavailable', `${sumsUrl} does not list ${assetName}`);
424
+ const body = await boundedGet(url, opts);
425
+ const actual = crypto.createHash('sha256').update(body).digest('hex');
426
+ if (actual !== expected) {
427
+ throw new ReleaseDownloadError('checksum-mismatch', `${assetName} sha256 ${actual} does not match the published ${expected}`);
428
+ }
429
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'apra-fleet-member-install-'));
430
+ const out = path.join(dir, assetName);
431
+ fs.writeFileSync(out, body);
432
+ return out;
433
+ }
434
+ const defaultDownload = (url, assetName, expectBuild) => downloadVerifiedAsset(url, assetName, expectBuild ? { expectBuild } : {});
435
+ /**
436
+ * Fetch the verified installer for the orchestrator's build from the first
437
+ * candidate release that has it: the stable release whose BUILD_INFO names
438
+ * this build, then the exact-build prerelease, then -- only with
439
+ * `allowSameCoreStable` (member has no apra-fleet or an older core) -- the
440
+ * signed stable release of the same core (never across cores). Only a
441
+ * missing release or one that is not this build moves on to the next
442
+ * candidate; any other failure (network, timeout, checksum) is reported as
443
+ * itself, never hidden behind the fallback. Anonymous URLs only.
444
+ */
445
+ export async function fetchReleaseInstaller(deps, source, orchestratorVersion, opts = {}) {
446
+ const tried = [];
447
+ for (const c of source.candidates) {
448
+ const url = releaseFileUrl(c.tag, source.assetName);
449
+ try {
450
+ return { localPath: await deps.downloadReleaseAsset(url, source.assetName, orchestratorVersion), url, tag: c.tag };
451
+ }
452
+ catch (err) {
453
+ if (err instanceof ReleaseDownloadError && (err.reason === 'release-not-found' || err.reason === 'build-mismatch')) {
454
+ tried.push(`${c.channel} ${c.tag}: ${err.message}`);
455
+ continue;
456
+ }
457
+ throw err;
458
+ }
459
+ }
460
+ const exactMissing = `no published release carries the ${source.assetName} installer for build ${orchestratorVersion} (tried ${tried.join('; ')})`;
461
+ // Same-core stable fallback (never across cores): only for a suffixed build
462
+ // whose exact build is unpublished, and only when the caller allows it (the
463
+ // member has no apra-fleet or an older core). Accepts any build of the core
464
+ // whose BUILD_INFO says so -- the signed stable release.
465
+ const core = releaseTagFor(orchestratorVersion);
466
+ if (opts.allowSameCoreStable && prereleaseTagFor(orchestratorVersion)) {
467
+ const url = releaseFileUrl(core, source.assetName);
468
+ try {
469
+ const localPath = await deps.downloadReleaseAsset(url, source.assetName, core);
470
+ return { localPath, url, tag: core, sameCoreFallback: { wantedBuild: orchestratorVersion, why: exactMissing } };
471
+ }
472
+ catch (err) {
473
+ if (err instanceof ReleaseDownloadError && (err.reason === 'release-not-found' || err.reason === 'build-mismatch')) {
474
+ tried.push(`same-core stable fallback ${core}: ${err.message}`);
475
+ throw new ReleaseDownloadError('no-matching-release', `no published release carries the ${source.assetName} installer for build ${orchestratorVersion} or its core ${core} (tried ${tried.join('; ')})`);
476
+ }
477
+ throw err;
478
+ }
479
+ }
480
+ throw new ReleaseDownloadError('no-matching-release', exactMissing);
481
+ }
482
+ export function defaultMemberFleetInstallDeps() {
483
+ return {
484
+ exec: (agent, command, timeoutMs) => getStrategy(agent).execCommand(command, timeoutMs),
485
+ transfer: (agent, localPaths, destinationDir) => getStrategy(agent).transferFiles(localPaths, destinationDir),
486
+ resolveHome: agent => getMemberHomeDir(agent),
487
+ orchestratorPlatform: hostPlatform,
488
+ orchestratorExecutable: seaExecutable,
489
+ orchestratorVersion: () => serverVersion,
490
+ downloadReleaseAsset: defaultDownload,
491
+ removeLocal: p => {
492
+ try {
493
+ fs.rmSync(path.dirname(p), { recursive: true, force: true });
494
+ }
495
+ catch { /* best effort */ }
496
+ },
497
+ };
498
+ }
499
+ let seaExecutableCache;
500
+ function seaExecutable() {
501
+ if (seaExecutableCache !== undefined)
502
+ return seaExecutableCache;
503
+ try {
504
+ // node:sea exists only inside a single-executable build; under ESM/dev the
505
+ // require is unavailable and we correctly report "nothing to copy".
506
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
507
+ const sea = typeof require === 'function' ? require('node:sea') : null;
508
+ seaExecutableCache = sea && sea.isSea() ? process.execPath : null;
509
+ }
510
+ catch {
511
+ seaExecutableCache = null;
512
+ }
513
+ return seaExecutableCache;
514
+ }
515
+ // ---------------------------------------------------------------------------
516
+ // Probe + install
517
+ // ---------------------------------------------------------------------------
518
+ /** Basename on either separator: the local installer path follows the
519
+ * ORCHESTRATOR's convention, which need not match this host's path module. */
520
+ function anyBasename(p) {
521
+ return p.split(/[\\/]/).filter(Boolean).pop() ?? p;
522
+ }
523
+ /** Where the member's own apra-fleet lives: <home>/.apra-fleet/bin/<exe>. */
524
+ export function memberBinPath(home, targetOs, shell) {
525
+ return memberJoin(targetOs, shell, home, '.apra-fleet', 'bin', binaryNameFor(targetOs));
526
+ }
527
+ /** Where installers are staged before running: <home>/.apra-fleet/staging. */
528
+ export function memberStagingDir(home, targetOs, shell) {
529
+ return memberJoin(targetOs, shell, home, '.apra-fleet', 'staging');
530
+ }
531
+ /** Probe a member's apra-fleet at `binPath`. Never throws. */
532
+ export async function probeMemberFleetVersion(agent, binPath, deps) {
533
+ const targetOs = getAgentOS(agent);
534
+ const shell = getAgentShell(agent);
535
+ let result;
536
+ try {
537
+ result = await deps.exec(agent, buildFleetVersionProbe(binPath, targetOs, shell), PROBE_TIMEOUT_MS);
538
+ }
539
+ catch (err) {
540
+ return { kind: 'probe-failed', detail: `probe threw: ${err instanceof Error ? err.message : String(err)}` };
541
+ }
542
+ if (result.stdout.includes(NO_INSTALL_SENTINEL))
543
+ return { kind: 'missing', binPath };
544
+ if (result.stdout.includes(EXEC_FAILED_SENTINEL)) {
545
+ return { kind: 'broken', binPath, detail: 'the executable exited non-zero or could not be launched' };
546
+ }
547
+ if (result.code !== 0) {
548
+ return { kind: 'probe-failed', detail: `probe exited ${result.code}: ${result.stderr.trim().slice(0, 300)}` };
549
+ }
550
+ const version = parseFleetVersion(result.stdout);
551
+ if (!version) {
552
+ return { kind: 'broken', binPath, detail: `unparseable --version output: ${result.stdout.trim().slice(0, 200)}` };
553
+ }
554
+ return { kind: 'installed', version, binPath };
555
+ }
556
+ async function probeMemberArch(agent, deps) {
557
+ const targetOs = getAgentOS(agent);
558
+ try {
559
+ const r = await deps.exec(agent, buildArchProbe(targetOs, getAgentShell(agent)), PROBE_TIMEOUT_MS);
560
+ if (r.code !== 0)
561
+ return null;
562
+ return normalizeArch(r.stdout);
563
+ }
564
+ catch {
565
+ return null;
566
+ }
567
+ }
568
+ /**
569
+ * The manual steps an OWNER runs on the member to replace an unmarked install
570
+ * (a full install, or a member install older than the marker) with a member
571
+ * install, which writes the marker. Every path is resolved here in JS from the
572
+ * probed home -- no ~ or $HOME -- and quoted for the member's shell. The fleet
573
+ * never runs these itself. Steps use the INSTALLED binary only for `uninstall`
574
+ * (present in old installs) and the freshly STAGED current installer for the
575
+ * install, so no flag the old binary predates is ever needed. ASCII, one line.
576
+ */
577
+ export function buildFullInstallReplaceHint(opts) {
578
+ const { home, targetOs, shell, provider, installer } = opts;
579
+ const posix = isPosixShell(targetOs, shell);
580
+ const q = posix ? posixQuote : psQuote;
581
+ const j = (...parts) => memberJoin(targetOs, shell, home, ...parts);
582
+ const data = j('.apra-fleet', 'data');
583
+ const key = j('.apra-fleet', 'fleet.key');
584
+ const backup = j('.apra-fleet-data.full-install.bak');
585
+ const aside = j('.apra-fleet', 'data.replaced');
586
+ const bin = memberBinPath(home, targetOs, shell);
587
+ const installerPath = installer.staged ? installer.path : installer.target;
588
+ const steps = [];
589
+ if (!installer.staged) {
590
+ steps.push(`(0) the current installer could not be staged on the member (${installer.why}); ` +
591
+ (installer.fetchCommand
592
+ ? `fetch it with: ${installer.fetchCommand}`
593
+ : `download the apra-fleet installer for this platform from the release page to ${installerPath}`));
594
+ }
595
+ steps.push(posix
596
+ ? `(1) back up, including the signing key that lives outside data/: cp -R ${q(data)} ${q(backup)} && cp ${q(key)} ${q(backup + '/')}`
597
+ : `(1) back up, including the signing key that lives outside data/: Copy-Item -Recurse -LiteralPath ${q(data)} -Destination ${q(backup)}; Copy-Item -LiteralPath ${q(key)} -Destination ${q(backup + String.fromCharCode(92))}`, `(2) uninstall with the INSTALLED binary (keeps data/): ${posix ? '' : '& '}${q(bin)} uninstall --force --yes`, posix
598
+ ? `(3) move the old data aside (the backup stays as the rollback copy): mv ${q(data)} ${q(aside)}`
599
+ : `(3) move the old data aside (the backup stays as the rollback copy): Move-Item -LiteralPath ${q(data)} -Destination ${q(aside)}`);
600
+ if (targetOs === 'linux') {
601
+ const unit = j('.config', 'systemd', 'user', 'fleet-supervisor.service');
602
+ steps.push(`(3b) linux only: uninstall leaves fleet-supervisor.service running with its serve.mjs deleted; stop it: ` +
603
+ `systemctl --user stop fleet-supervisor; systemctl --user disable fleet-supervisor; mv ${q(unit)} ${q(backup + '/')}; systemctl --user daemon-reload`);
604
+ }
605
+ steps.push(posix
606
+ ? `(4) run the current installer: chmod +x ${q(installerPath)} && ${q(installerPath)} install --member --llm ${provider} --force`
607
+ : `(4) run the current installer: & ${q(installerPath)} install --member --llm ${provider} --force`, '(5) on the orchestrator: update_member {member_id, fleet_install: "auto"} for every member on that Unix user (one member install per Unix user; each member self-registers its own uuid)');
608
+ return ('The fleet does not touch an apra-fleet install without the member-install marker (a full install, or a member install older than the marker). ' +
609
+ `To replace it with a member install, its owner runs on the member: ${steps.join('; ')}. ` +
610
+ `Or opt in to the fleet running these steps itself (back up data and fleet.key, uninstall, member install, self-register): update_member {member_id, fleet_install: "${REPLACE_FULL_INSTALL}"}.`);
611
+ }
612
+ // ---------------------------------------------------------------------------
613
+ // Opt-in full-install replacement (fleet_install "replace-full")
614
+ // ---------------------------------------------------------------------------
615
+ /** The explicit fleet_install value that lets the fleet replace an unmarked
616
+ * (full) install with a member install. Never implied by "auto". */
617
+ export const REPLACE_FULL_INSTALL = 'replace-full';
618
+ /** Tag the linux supervisor step prints when it moved a unit file into the backup. */
619
+ export const SUPERVISOR_MOVED_SENTINEL = '__APRA_FLEET_SUPERVISOR_MOVED__';
620
+ /** Path-safe UTC stamp (no ':'): 20261006T143000Z. */
621
+ export function replaceBackupStamp(d) {
622
+ return d.toISOString().replace(/\.\d+Z$/, 'Z').replace(/[-:]/g, '');
623
+ }
624
+ /**
625
+ * The member-bound command sequence of the opt-in replacement (pure; exported
626
+ * for tests). Every path is resolved here from the probed home and quoted for
627
+ * the member's shell; PowerShell is wrapped via -EncodedCommand. Steps:
628
+ * backup -- copy data/ and fleet.key (outside data/) into a timestamped dir;
629
+ * uninstall -- the INSTALLED binary's own uninstall --force --yes;
630
+ * supervisor -- linux: stop/disable the fleet-supervisor user unit when its
631
+ * unit file exists, move the file into the backup, daemon-reload
632
+ * (uninstall leaves it running);
633
+ * move-data -- move data/ aside;
634
+ * install -- the staged CURRENT installer in member mode.
635
+ * Self-registration and the per-folder MCP entry follow in the probe.
636
+ */
637
+ export function buildReplaceFullInstallPlan(opts) {
638
+ const { home, targetOs, shell, provider, installerPath, stamp } = opts;
639
+ const posix = isPosixShell(targetOs, shell);
640
+ const j = (...parts) => memberJoin(targetOs, shell, home, ...parts);
641
+ const data = j('.apra-fleet', 'data');
642
+ const key = j('.apra-fleet', 'fleet.key');
643
+ const bin = memberBinPath(home, targetOs, shell);
644
+ const backupDir = j(`.apra-fleet-replace-backup-${stamp}`);
645
+ const backupData = memberJoin(targetOs, shell, backupDir, 'data');
646
+ const backupKey = memberJoin(targetOs, shell, backupDir, 'fleet.key');
647
+ const dataAside = j('.apra-fleet', `data.replaced-${stamp}`);
648
+ const unitName = 'fleet-supervisor.service';
649
+ const unit = j('.config', 'systemd', 'user', unitName);
650
+ const backupUnit = memberJoin(targetOs, shell, backupDir, unitName);
651
+ const q = posix ? posixQuote : psQuote;
652
+ // PowerShell steps run inside wrapPowerShellEncoded, which sets
653
+ // $ErrorActionPreference = 'Stop' and exits non-zero on an error or a native
654
+ // non-zero $LASTEXITCODE: a failed copy, move or uninstall is a failed step.
655
+ const cmd = (posixForm, psForm) => memberCommandFor(targetOs, shell, { posix: posixForm, powershell: psForm });
656
+ const steps = [
657
+ {
658
+ name: 'backup',
659
+ command: cmd(`mkdir -p ${q(backupDir)} && cp -R ${q(data)} ${q(backupData)} && if [ -f ${q(key)} ]; then cp ${q(key)} ${q(backupKey)}; fi`, `New-Item -ItemType Directory -Force -Path ${q(backupDir)} | Out-Null; Copy-Item -Recurse -LiteralPath ${q(data)} -Destination ${q(backupData)}; if (Test-Path -LiteralPath ${q(key)} -PathType Leaf) { Copy-Item -LiteralPath ${q(key)} -Destination ${q(backupKey)} }`),
660
+ },
661
+ {
662
+ name: 'uninstall',
663
+ command: cmd(`${q(bin)} uninstall --force --yes`, `& ${q(bin)} uninstall --force --yes`),
664
+ },
665
+ ];
666
+ if (targetOs === 'linux' && posix) {
667
+ steps.push({
668
+ name: 'supervisor',
669
+ command: `if [ -f ${q(unit)} ]; then systemctl --user stop fleet-supervisor || true; systemctl --user disable fleet-supervisor || true; ` +
670
+ `mv ${q(unit)} ${q(backupUnit)} && printf '%s\\n' '${SUPERVISOR_MOVED_SENTINEL}' && (systemctl --user daemon-reload || true); fi`,
671
+ });
672
+ }
673
+ steps.push({
674
+ name: 'move-data',
675
+ command: cmd(`mv ${q(data)} ${q(dataAside)}`, `Move-Item -LiteralPath ${q(data)} -Destination ${q(dataAside)}`),
676
+ }, { name: 'install', command: buildInstallCommand(installerPath, provider, targetOs, shell) });
677
+ // The rollback depends on how far the replacement got. Before step 4 completed
678
+ // the in-place data/ is intact (uninstall keeps it) and must NOT be replaced by
679
+ // the backup, which was copied while the old server was still running and may
680
+ // be torn. From step 5 on, data/ was moved aside AFTER the server stopped, so
681
+ // that consistent copy is the source; the backup is a last resort used only
682
+ // when the aside copy is gone.
683
+ const unitRestore = targetOs === 'linux' && posix
684
+ ? [`if [ -f ${q(backupUnit)} ]; then mkdir -p ${q(j('.config', 'systemd', 'user'))} && mv ${q(backupUnit)} ${q(unit)} && systemctl --user daemon-reload && systemctl --user enable --now fleet-supervisor; fi`]
685
+ : [];
686
+ const reinstall = posix
687
+ ? `chmod +x ${q(installerPath)} && ${q(installerPath)} install --llm ${provider} --force`
688
+ : `& ${q(installerPath)} install --llm ${provider} --force`;
689
+ const keyRestoreIfMissing = posix
690
+ ? `if [ ! -f ${q(key)} ] && [ -f ${q(backupKey)} ]; then cp ${q(backupKey)} ${q(key)}; fi`
691
+ : `if (-not (Test-Path -LiteralPath ${q(key)} -PathType Leaf) -and (Test-Path -LiteralPath ${q(backupKey)} -PathType Leaf)) { Copy-Item -LiteralPath ${q(backupKey)} -Destination ${q(key)} }`;
692
+ const dataInPlace = [keyRestoreIfMissing, ...unitRestore, reinstall];
693
+ const dataFromAside = [
694
+ posix
695
+ ? `if [ -d ${q(dataAside)} ]; then rm -rf ${q(data)} && mv ${q(dataAside)} ${q(data)}; else rm -rf ${q(data)} && cp -R ${q(backupData)} ${q(data)}; fi`
696
+ : `if (Test-Path -LiteralPath ${q(data)}) { Remove-Item -Recurse -Force -LiteralPath ${q(data)} }; if (Test-Path -LiteralPath ${q(dataAside)}) { Move-Item -LiteralPath ${q(dataAside)} -Destination ${q(data)} } else { Copy-Item -Recurse -LiteralPath ${q(backupData)} -Destination ${q(data)} }`,
697
+ keyRestoreIfMissing,
698
+ ...unitRestore,
699
+ reinstall,
700
+ ];
701
+ const rollbackFor = {
702
+ backup: [],
703
+ uninstall: dataInPlace,
704
+ supervisor: dataInPlace,
705
+ 'move-data': dataInPlace,
706
+ install: dataFromAside,
707
+ verify: dataFromAside,
708
+ };
709
+ return { backupDir, dataAside, steps, rollbackFor };
710
+ }
711
+ const REPLACE_STEP_LABEL = {
712
+ backup: 'step 1 (back up data and fleet.key)',
713
+ uninstall: 'step 2 (uninstall with the installed binary)',
714
+ supervisor: 'step 3 (stop and disable the fleet-supervisor user unit)',
715
+ 'move-data': 'step 4 (move data aside)',
716
+ install: 'step 5 (run the current installer in member mode)',
717
+ };
718
+ /**
719
+ * Replace an unmarked (full) install at `binPath` with a member install. The
720
+ * caller has already established: the opt-in was given, an apra-fleet install
721
+ * runs there, and the marker probe answered cleanly "absent". The installer is
722
+ * fetched and staged BEFORE anything destructive, so a download, checksum or
723
+ * transfer failure leaves the install untouched. Never throws.
724
+ */
725
+ async function replaceFullInstall(agent, deps, home, binPath, previousVersion, ctx = {}) {
726
+ const targetOs = getAgentOS(agent);
727
+ const shell = getAgentShell(agent);
728
+ const provider = agent.llmProvider ?? 'claude';
729
+ const orchestratorVersion = deps.orchestratorVersion();
730
+ const untouched = (reason, detail) => ({
731
+ state: 'unavailable', reason, detail: `${detail}; the full install was not replaced and nothing on the member was changed`, version: previousVersion,
732
+ });
733
+ const arch = await probeMemberArch(agent, deps);
734
+ ctx.arch = arch;
735
+ if (!arch)
736
+ return untouched('arch-unknown', 'the member CPU architecture could not be probed');
737
+ const source = chooseInstallSource({ os: targetOs, arch }, deps.orchestratorPlatform(), deps.orchestratorExecutable(), orchestratorVersion);
738
+ if (source.kind === 'unavailable')
739
+ return untouched(source.reason, source.detail);
740
+ let localPath;
741
+ let downloaded = false;
742
+ let sameCoreFallback;
743
+ if (source.kind === 'orchestrator-executable') {
744
+ localPath = source.localPath;
745
+ }
746
+ else {
747
+ try {
748
+ // Same-core stable fallback only when the replaced install is an older core.
749
+ const fetched = await fetchReleaseInstaller(deps, source, orchestratorVersion, { allowSameCoreStable: isOlderThan(previousVersion, orchestratorVersion) });
750
+ localPath = fetched.localPath;
751
+ sameCoreFallback = fetched.sameCoreFallback ? { tag: fetched.tag, ...fetched.sameCoreFallback } : undefined;
752
+ downloaded = true;
753
+ }
754
+ catch (err) {
755
+ return untouched(downloadFailureReason(err), err instanceof Error ? err.message : String(err));
756
+ }
757
+ }
758
+ const stagingDir = memberStagingDir(home, targetOs, shell);
759
+ try {
760
+ const sent = await deps.transfer(agent, [localPath], stagingDir);
761
+ if (sent.failed.length > 0 || sent.success.length === 0) {
762
+ return untouched('transfer-failed', sent.failed.map(f => `${f.path}: ${f.error}`).join('; ') || 'nothing was transferred');
763
+ }
764
+ }
765
+ finally {
766
+ if (downloaded)
767
+ deps.removeLocal(localPath);
768
+ }
769
+ const installerPath = memberJoin(targetOs, shell, stagingDir, anyBasename(localPath));
770
+ const stamp = replaceBackupStamp(deps.now ? deps.now() : new Date());
771
+ const plan = buildReplaceFullInstallPlan({ home, targetOs, shell, provider, installerPath, stamp });
772
+ let supervisorMoved = false;
773
+ const failedAt = (name, why) => {
774
+ const label = name === 'verify' ? 'the version check after step 5' : REPLACE_STEP_LABEL[name];
775
+ const detail = name === 'backup'
776
+ ? `replacing the full install failed at ${label}: ${why}. Nothing was removed; the apra-fleet ${previousVersion} full install is unchanged`
777
+ : `replacing the full install failed at ${label}: ${why}. The backup is at ${plan.backupDir}. To roll back, run on the member: ${plan.rollbackFor[name].join('; ')}`;
778
+ return { state: 'unavailable', reason: 'replace-failed', detail, version: previousVersion };
779
+ };
780
+ for (const step of plan.steps) {
781
+ let r;
782
+ try {
783
+ r = await deps.exec(agent, step.command, step.name === 'install' || step.name === 'uninstall' ? INSTALL_TIMEOUT_MS : MEMBER_CALL_TIMEOUT_MS);
784
+ }
785
+ catch (err) {
786
+ return failedAt(step.name, err instanceof Error ? err.message : String(err));
787
+ }
788
+ if (r.code !== 0) {
789
+ return failedAt(step.name, `exited ${r.code}: ${(r.stderr.trim() || r.stdout.trim()).slice(-400)}`);
790
+ }
791
+ if (step.name === 'supervisor' && r.stdout.includes(SUPERVISOR_MOVED_SENTINEL))
792
+ supervisorMoved = true;
793
+ }
794
+ const after = await probeMemberFleetVersion(agent, binPath, deps);
795
+ if (after.kind !== 'installed' || isMemberOutdated(after.version, orchestratorVersion, !sameCoreFallback && sourceSuppliesBuild(source, orchestratorVersion))) {
796
+ const seen = after.kind === 'installed' ? `reports ${after.version}` : after.kind === 'probe-failed' ? after.detail : after.kind;
797
+ return failedAt('verify', `after install the member ${seen}; expected >= ${orchestratorVersion}`);
798
+ }
799
+ const removed = [
800
+ `the apra-fleet ${previousVersion} full install (uninstalled with its own binary)`,
801
+ ...(supervisorMoved ? [`the fleet-supervisor user unit (stopped, disabled, unit file moved into the backup)`] : []),
802
+ `its data directory (moved aside to ${plan.dataAside})`,
803
+ ];
804
+ return {
805
+ state: 'available', version: after.version, installed: true, source: source.kind, binPath,
806
+ replaced: { previousVersion, removed, backupPath: plan.backupDir },
807
+ ...(sameCoreFallback ? { sameCoreFallback } : {}),
808
+ };
809
+ }
810
+ /**
811
+ * Stage the orchestrator's installer on the member (same staging dir and
812
+ * source logic as an upgrade) so the replacement hint can name a path that
813
+ * exists. When `stage` is false nothing is transferred or downloaded. A failure
814
+ * never throws: it is returned so the hint names it and gives the download
815
+ * command for the platform instead.
816
+ */
817
+ async function stageReplacementInstaller(agent, deps, home, source, stage) {
818
+ const targetOs = getAgentOS(agent);
819
+ const shell = getAgentShell(agent);
820
+ const stagingDir = memberStagingDir(home, targetOs, shell);
821
+ const fallbackTarget = memberJoin(targetOs, shell, stagingDir, binaryNameFor(targetOs));
822
+ // The release-asset download for THIS member's platform, whatever the staging
823
+ // source was: it is what the owner runs when staging did not leave an
824
+ // installer on the member (and on the status-only path).
825
+ const releaseFetch = async () => {
826
+ const arch = await probeMemberArch(agent, deps);
827
+ const assetName = arch ? releaseAssetNameFor({ os: targetOs, arch }) : null;
828
+ if (!assetName)
829
+ return null;
830
+ const url = releaseAssetUrl(deps.orchestratorVersion(), assetName);
831
+ const target = memberJoin(targetOs, shell, stagingDir, assetName);
832
+ const fetchCommand = isPosixShell(targetOs, shell)
833
+ ? `mkdir -p ${posixQuote(stagingDir)} && curl -fL -o ${posixQuote(target)} ${posixQuote(url)}`
834
+ : `New-Item -ItemType Directory -Force -Path ${psQuote(stagingDir)} | Out-Null; Invoke-WebRequest -Uri ${psQuote(url)} -OutFile ${psQuote(target)}`;
835
+ return { target, fetchCommand };
836
+ };
837
+ const notStaged = async (why, dflt) => {
838
+ const f = await releaseFetch().catch(() => null);
839
+ return f ? { staged: false, why, target: f.target, fetchCommand: f.fetchCommand } : { staged: false, why, target: dflt };
840
+ };
841
+ try {
842
+ if (!source) {
843
+ const arch = await probeMemberArch(agent, deps);
844
+ if (!arch)
845
+ return { staged: false, why: 'the member CPU architecture could not be probed', target: fallbackTarget };
846
+ const chosen = chooseInstallSource({ os: targetOs, arch }, deps.orchestratorPlatform(), deps.orchestratorExecutable(), deps.orchestratorVersion());
847
+ if (chosen.kind === 'unavailable')
848
+ return { staged: false, why: chosen.detail, target: fallbackTarget };
849
+ source = chosen;
850
+ }
851
+ const baseName = source.kind === 'release-asset' ? source.assetName : anyBasename(source.localPath);
852
+ const target = memberJoin(targetOs, shell, stagingDir, baseName);
853
+ if (!stage)
854
+ return notStaged('not staged by this check; run update_member with fleet_install "auto" to stage it', target);
855
+ let localPath;
856
+ let downloaded = false;
857
+ if (source.kind === 'orchestrator-executable') {
858
+ localPath = source.localPath;
859
+ }
860
+ else {
861
+ try {
862
+ localPath = (await fetchReleaseInstaller(deps, source, deps.orchestratorVersion())).localPath;
863
+ downloaded = true;
864
+ }
865
+ catch (err) {
866
+ return notStaged(`download failed: ${err instanceof Error ? err.message : String(err)}`, target);
867
+ }
868
+ }
869
+ try {
870
+ const sent = await deps.transfer(agent, [localPath], stagingDir);
871
+ if (sent.failed.length > 0 || sent.success.length === 0) {
872
+ const why = sent.failed.map(f => `${f.path}: ${f.error}`).join('; ') || 'nothing was transferred';
873
+ return notStaged(`transfer failed: ${why}`, target);
874
+ }
875
+ }
876
+ finally {
877
+ if (downloaded)
878
+ deps.removeLocal(localPath);
879
+ }
880
+ return { staged: true, path: target };
881
+ }
882
+ catch (err) {
883
+ return notStaged(err instanceof Error ? err.message : String(err), fallbackTarget);
884
+ }
885
+ }
886
+ /** The member-install marker on the member: <home>/.apra-fleet/data/member-install.json
887
+ * (written by `install --member`, cleared by a full install; see
888
+ * src/cli/install-guard.ts writeMemberInstallMarker). Built in JS from the
889
+ * probed home. */
890
+ export function memberInstallMarkerPathFor(home, agent) {
891
+ const targetOs = getAgentOS(agent);
892
+ return joinMemberPath(home, '.apra-fleet/data/member-install.json', targetOs === 'windows', getAgentShell(agent));
893
+ }
894
+ /**
895
+ * Probe whether the member's apra-fleet install carries the member-install
896
+ * marker, i.e. it is a member install the fleet may manage and self-register
897
+ * into.
898
+ *
899
+ * The marker is the SOLE fleet-ownership signal. An install without it is
900
+ * either a human full install or a member install made before the marker
901
+ * existed; nothing on the member tells the two apart (both may hold a LOCAL
902
+ * registry entry for this member's uuid, because builds before this rule
903
+ * self-registered into any install), so the fleet treats both as not its own:
904
+ * it never self-registers into them and never sends --force-stop-full-install.
905
+ *
906
+ * Three outcomes: present (exit 0), cleanly absent (`test -f` / Test-Path exit
907
+ * 1) and probe-failed (a timeout or transport error, or any other non-zero
908
+ * exit such as 126/127/255) with the reason. A probe failure is never read as
909
+ * "absent": a slow or flaky member is not an unowned one. Never throws.
910
+ */
911
+ export async function probeMemberInstallMarker(agent, home, deps) {
912
+ const posix = isPosixShell(getAgentOS(agent), getAgentShell(agent));
913
+ const markerPath = memberInstallMarkerPathFor(home, agent);
914
+ const cmd = posix ? memberFileExistsPosixCommand(markerPath) : memberFileExistsPwshCommand(markerPath);
915
+ let r;
916
+ try {
917
+ r = await deps.exec(agent, cmd, PROBE_TIMEOUT_MS);
918
+ }
919
+ catch (err) {
920
+ return { kind: 'probe-failed', detail: `the member-install marker probe failed: ${err instanceof Error ? err.message : String(err)}` };
921
+ }
922
+ if (r.code === 0)
923
+ return { kind: 'present' };
924
+ if (r.code === 1)
925
+ return { kind: 'absent' };
926
+ return { kind: 'probe-failed', detail: `the member-install marker probe exited ${r.code}: ${r.stderr.trim().slice(0, 300)}` };
927
+ }
928
+ /**
929
+ * Ensure a REMOTE member runs an apra-fleet at least as new as this
930
+ * orchestrator, installed in HTTP member mode. Never throws: every failure is a
931
+ * typed `unavailable(<reason>)` result so the caller's registration proceeds.
932
+ */
933
+ export async function ensureMemberFleetInstall(agent, deps = defaultMemberFleetInstallDeps(), opts = {}) {
934
+ const ctx = {};
935
+ let r;
936
+ try {
937
+ r = await ensureOnce(agent, deps, opts.force === true, opts.replaceFull === true, ctx);
938
+ }
939
+ catch (err) {
940
+ r = { state: 'unavailable', reason: 'probe-failed', detail: `install flow threw: ${err instanceof Error ? err.message : String(err)}` };
941
+ }
942
+ if (r.state === 'unavailable' && !r.manualSteps) {
943
+ let manualSteps;
944
+ try {
945
+ manualSteps = buildManualInstallSteps({
946
+ home: ctx.home ?? null,
947
+ targetOs: getAgentOS(agent),
948
+ shell: getAgentShell(agent),
949
+ provider: agent.llmProvider ?? 'claude',
950
+ arch: ctx.arch ?? null,
951
+ orchestratorVersion: deps.orchestratorVersion(),
952
+ reason: r.reason,
953
+ });
954
+ }
955
+ catch (err) {
956
+ manualSteps = `could not build the manual steps: ${err instanceof Error ? err.message : String(err)}`;
957
+ }
958
+ r = { ...r, manualSteps };
959
+ }
960
+ return r;
961
+ }
962
+ /**
963
+ * The exact steps an owner runs ON THE MEMBER to install this orchestrator's
964
+ * build by hand when the fleet could not (pure; exported for tests). Built in
965
+ * JS for the member's OS/shell from the probed home -- no ~, $HOME or other
966
+ * shell expansion -- with every path and URL quoted. The download is the
967
+ * anonymous release URL the fleet itself tried first (no GitHub account
968
+ * needed); the SHA-256 check uses the release's SHA256SUMS (sha256sum on
969
+ * linux and Git Bash, shasum -a 256 on macOS, Get-FileHash in PowerShell).
970
+ * ASCII; one step per line.
971
+ */
972
+ export function buildManualInstallSteps(opts) {
973
+ const { home, targetOs, shell, provider, arch, orchestratorVersion, reason } = opts;
974
+ const finish = 'then on the orchestrator run update_member {member_id, fleet_install: "auto"} so the fleet self-registers the member into that install and verifies it';
975
+ if (reason === 'full-install-running' || reason === 'replace-failed') {
976
+ return `follow the owner steps in the reason above, ${finish}.`;
977
+ }
978
+ if (!home || reason === 'home-unresolved' || reason === 'probe-failed') {
979
+ return `make the member reachable (member_detail shows its connectivity and the error), ${finish}.`;
980
+ }
981
+ const asset = arch ? releaseAssetNameFor({ os: targetOs, arch }) : null;
982
+ const pre = prereleaseTagFor(orchestratorVersion);
983
+ // A dev/branch build's installer lives in its exact-build prerelease; a
984
+ // released build's in the stable release (its BUILD_INFO names the build,
985
+ // and its Windows installer is signed), noted below.
986
+ const stableTag = releaseTagFor(orchestratorVersion);
987
+ const tag = pre ?? stableTag;
988
+ const args = memberInstallArgs(provider);
989
+ if (!asset) {
990
+ return [
991
+ arch
992
+ ? `no apra-fleet installer is published for ${targetOs}/${arch}; build it from source on the member:`
993
+ : `the member CPU architecture could not be probed; pick the installer for its OS/arch from ${releasePageUrl(tag)}, or build it from source on the member:`,
994
+ `(1) git clone https://github.com/${RELEASE_REPO}.git and check out ${pre ? `commit ${buildSuffixOf(pre)}` : `tag ${tag}`}, then npm install && npm run build:binary`,
995
+ `(2) run the built installer (dist/apra-fleet-installer-*) with: ${args.join(' ')}`,
996
+ `(3) ${finish}.`,
997
+ ].join('\n');
998
+ }
999
+ const posix = isPosixShell(targetOs, shell);
1000
+ const q = posix ? posixQuote : psQuote;
1001
+ const staging = memberStagingDir(home, targetOs, shell);
1002
+ const file = memberJoin(targetOs, shell, staging, asset);
1003
+ const sums = memberJoin(targetOs, shell, staging, CHECKSUM_ASSET);
1004
+ const url = releaseFileUrl(tag, asset);
1005
+ const sumsUrl = releaseFileUrl(tag, CHECKSUM_ASSET);
1006
+ const lines = [];
1007
+ if (reason === 'no-matching-release') {
1008
+ lines.push(`no release for build ${orchestratorVersion} is published yet${pre ? ` (prereleases exist only for builds pushed to the release branches, newest 3 per branch)` : ''}; ` +
1009
+ `either run the orchestrator from a published build (${`https://github.com/${RELEASE_REPO}/releases`}) and re-run update_member, or build ${asset} from source ` +
1010
+ `(${pre ? `commit ${buildSuffixOf(pre)}` : `tag ${tag}`}: npm install && npm run build:binary) and copy it to ${file}, skip steps 1-2, and continue at step 3. ` +
1011
+ `Once ${releasePageUrl(tag)} exists, steps 1-4 install it:`);
1012
+ }
1013
+ else {
1014
+ lines.push(`install apra-fleet ${orchestratorVersion} from ${releasePageUrl(tag)} (anonymous download, no GitHub account needed):`);
1015
+ }
1016
+ if (pre) {
1017
+ lines.push(`(if ${releaseFileUrl(stableTag, BUILD_INFO_ASSET)} names version=${orchestratorVersion}, this orchestrator is a released build: use tag ${stableTag} instead of ${pre} in the URLs below -- its Windows installer is signed)`);
1018
+ }
1019
+ if (posix) {
1020
+ const shaTool = targetOs === 'macos' ? 'shasum -a 256 -c -' : 'sha256sum -c -';
1021
+ lines.push(`(1) download: mkdir -p ${q(staging)} && curl -fL -o ${q(file)} ${q(url)} && curl -fL -o ${q(sums)} ${q(sumsUrl)}`, `(2) verify the SHA-256 (must print OK): cd ${q(staging)} && grep ${q(` ${asset}`)} ${q(CHECKSUM_ASSET)} | ${shaTool}`, `(3) install in member mode: chmod +x ${q(file)} && ${q(file)} ${args.map(q).join(' ')}`);
1022
+ }
1023
+ else {
1024
+ lines.push(
1025
+ // $ProgressPreference / $h / $line are PowerShell variables the owner's
1026
+ // own session sets and reads; no path or value depends on expansion.
1027
+ `(1) download: $ProgressPreference = 'SilentlyContinue'; New-Item -ItemType Directory -Force -Path ${q(staging)} | Out-Null; Invoke-WebRequest -UseBasicParsing -Uri ${q(url)} -OutFile ${q(file)}; Invoke-WebRequest -UseBasicParsing -Uri ${q(sumsUrl)} -OutFile ${q(sums)}`, `(2) verify the SHA-256 (throws on a mismatch; do not run the installer then): $h = (Get-FileHash -Algorithm SHA256 -LiteralPath ${q(file)}).Hash.ToLower(); $line = (Select-String -LiteralPath ${q(sums)} -SimpleMatch ${q(` ${asset}`)} | Select-Object -First 1).Line; if (-not $line -or ($line -split '\\s+')[0].ToLower() -ne $h) { throw ${q(`SHA-256 mismatch for ${asset}: do not run it`)} } else { 'OK' }`, `(3) install in member mode: & ${q(file)} ${args.map(q).join(' ')}`);
1028
+ }
1029
+ lines.push(`(4) ${finish}.`);
1030
+ return lines.join('\n');
1031
+ }
1032
+ /**
1033
+ * The prominent WARNING register_member / update_member print when a
1034
+ * requested apra-fleet install/upgrade on the member did not happen, or null
1035
+ * when there is nothing to warn about. Names (a) the consequence, (b) the
1036
+ * exact reason and (c) the manual steps. The tool call itself succeeds. ASCII.
1037
+ */
1038
+ export function fleetInstallWarning(memberName, status) {
1039
+ if (!status.manualInstall && status.sameCoreFallback) {
1040
+ const f = status.sameCoreFallback;
1041
+ return [
1042
+ `NOTICE: member "${memberName}" got apra-fleet from the same-core stable release: installed signed stable ${f.tag}${status.version ? ` (${status.version})` : ''}, not the exact build ${f.wantedBuild}.`,
1043
+ ` Why: ${f.why}`,
1044
+ ' KB/code tools work on that build; to get the exact build, publish it (or run the orchestrator from a published build) and run update_member {member_id, fleet_install: "auto"} again.',
1045
+ ].join('\n');
1046
+ }
1047
+ if (!status.manualInstall)
1048
+ return null;
1049
+ const reason = status.installFailure?.reason ?? status.reason ?? 'unknown';
1050
+ const detail = status.installFailure?.detail ?? status.detail;
1051
+ const consequence = status.state === 'available'
1052
+ ? `the member keeps its installed apra-fleet ${status.version ?? '(unknown version)'} instead of this orchestrator's build, so its KB/code tools run on that build until it is updated. Nothing else is affected.`
1053
+ : 'the member will not get the KB/code tools (kb_*, code_*) of its own apra-fleet. That is the only consequence: the member works for everything else.';
1054
+ const indent = (s) => s.split('\n').map(l => ` ${l}`).join('\n');
1055
+ return [
1056
+ `WARNING: apra-fleet on member "${memberName}" was not installed/updated to this orchestrator's build.`,
1057
+ ` Consequence: ${consequence}`,
1058
+ ` Reason: ${reason}${detail ? ` -- ${detail}` : ''}`,
1059
+ ' Manual steps on the member:',
1060
+ indent(status.manualInstall),
1061
+ ].join('\n');
1062
+ }
1063
+ async function ensureOnce(agent, deps, force, replaceFull = false, ctx = {}) {
1064
+ const targetOs = getAgentOS(agent);
1065
+ const shell = getAgentShell(agent);
1066
+ const provider = agent.llmProvider ?? 'claude';
1067
+ const orchestratorVersion = deps.orchestratorVersion();
1068
+ const home = await deps.resolveHome(agent);
1069
+ if (home)
1070
+ ctx.home = home;
1071
+ if (!home) {
1072
+ return { state: 'unavailable', reason: 'home-unresolved', detail: 'the member home directory could not be probed' };
1073
+ }
1074
+ const binPath = memberBinPath(home, targetOs, shell);
1075
+ const before = await probeMemberFleetVersion(agent, binPath, deps);
1076
+ if (before.kind === 'probe-failed') {
1077
+ return { state: 'unavailable', reason: 'probe-failed', detail: before.detail };
1078
+ }
1079
+ // Opt-in replacement (fleet_install "replace-full"): decided BEFORE the
1080
+ // up-to-date gates, so a same-version full install is replaced too. Only a
1081
+ // clean "absent" marker answer on a working install replaces; a probe failure
1082
+ // refuses with no destructive command; a marked install takes the normal
1083
+ // upgrade path below.
1084
+ if (replaceFull && before.kind === 'installed') {
1085
+ const marker = await probeMemberInstallMarker(agent, home, deps);
1086
+ if (marker.kind === 'probe-failed') {
1087
+ return { state: 'unavailable', reason: 'probe-failed', detail: `${marker.detail}; the opt-in full-install replacement was not run`, version: before.version };
1088
+ }
1089
+ if (marker.kind === 'absent')
1090
+ return replaceFullInstall(agent, deps, home, binPath, before.version, ctx);
1091
+ }
1092
+ // Pre-gate: only a strictly older core is outdated for certain; a same-core
1093
+ // build difference is decided below once the install source is known.
1094
+ if (!force && before.kind === 'installed' && !isMemberOutdated(before.version, orchestratorVersion, true)) {
1095
+ return { state: 'available', version: before.version, installed: false, binPath };
1096
+ }
1097
+ const priorVersion = before.kind === 'installed' ? before.version : undefined;
1098
+ const coreOutdated = before.kind !== 'installed' || isOlderThan(before.version, orchestratorVersion);
1099
+ const arch = await probeMemberArch(agent, deps);
1100
+ ctx.arch = arch;
1101
+ if (!arch && !force && !coreOutdated && before.kind === 'installed') {
1102
+ // Build-only difference and no way to tell the source: leave it alone.
1103
+ return { state: 'available', version: before.version, installed: false, binPath };
1104
+ }
1105
+ if (!arch) {
1106
+ return { state: 'unavailable', reason: 'arch-unknown', detail: 'the member CPU architecture could not be probed', version: priorVersion };
1107
+ }
1108
+ const source = chooseInstallSource({ os: targetOs, arch }, deps.orchestratorPlatform(), deps.orchestratorExecutable(), orchestratorVersion);
1109
+ if (source.kind === 'unavailable') {
1110
+ if (!force && !coreOutdated && before.kind === 'installed') {
1111
+ // Build-only difference and the orchestrator cannot supply its build.
1112
+ return { state: 'available', version: before.version, installed: false, binPath };
1113
+ }
1114
+ return { state: 'unavailable', reason: source.reason, detail: source.detail, version: priorVersion };
1115
+ }
1116
+ if (!force && !coreOutdated && before.kind === 'installed' &&
1117
+ !isMemberOutdated(before.version, orchestratorVersion, sourceSuppliesBuild(source, orchestratorVersion))) {
1118
+ // Same core, release-asset source: same core = up to date.
1119
+ return { state: 'available', version: before.version, installed: false, binPath };
1120
+ }
1121
+ // An existing install without the member-install marker is never installed
1122
+ // over: it may be a human full install whose server is simply not running
1123
+ // (no refusal would fire), and installing --member over it would hand it to
1124
+ // the fleet. Only a missing install, or a marked one, is (re)installed.
1125
+ if (before.kind !== 'missing') {
1126
+ const marker = await probeMemberInstallMarker(agent, home, deps);
1127
+ // A probe failure is never "a full install is present": report it as such.
1128
+ if (marker.kind === 'probe-failed') {
1129
+ return { state: 'unavailable', reason: 'probe-failed', detail: marker.detail, version: priorVersion };
1130
+ }
1131
+ if (marker.kind === 'absent') {
1132
+ const installer = await stageReplacementInstaller(agent, deps, home, source, true);
1133
+ return {
1134
+ state: 'unavailable',
1135
+ reason: 'full-install-running',
1136
+ detail: `the apra-fleet at ${binPath} has no member-install marker, so the fleet did not install over it. ${buildFullInstallReplaceHint({ home, targetOs, shell, provider, installer })}`,
1137
+ version: priorVersion,
1138
+ };
1139
+ }
1140
+ }
1141
+ let localPath;
1142
+ let downloaded = false;
1143
+ let sameCoreFallback;
1144
+ if (source.kind === 'orchestrator-executable') {
1145
+ localPath = source.localPath;
1146
+ }
1147
+ else {
1148
+ try {
1149
+ // The same-core stable fallback only when the member has no apra-fleet or
1150
+ // an older core: a signed stable build of the core beats nothing.
1151
+ const fetched = await fetchReleaseInstaller(deps, source, orchestratorVersion, { allowSameCoreStable: coreOutdated });
1152
+ localPath = fetched.localPath;
1153
+ sameCoreFallback = fetched.sameCoreFallback ? { tag: fetched.tag, ...fetched.sameCoreFallback } : undefined;
1154
+ downloaded = true;
1155
+ }
1156
+ catch (err) {
1157
+ return {
1158
+ state: 'unavailable',
1159
+ reason: downloadFailureReason(err),
1160
+ detail: err instanceof Error ? err.message : String(err),
1161
+ version: priorVersion,
1162
+ };
1163
+ }
1164
+ }
1165
+ try {
1166
+ const stagingDir = memberStagingDir(home, targetOs, shell);
1167
+ const sent = await deps.transfer(agent, [localPath], stagingDir);
1168
+ if (sent.failed.length > 0 || sent.success.length === 0) {
1169
+ const why = sent.failed.map(f => `${f.path}: ${f.error}`).join('; ') || 'nothing was transferred';
1170
+ return { state: 'unavailable', reason: 'transfer-failed', detail: why, version: priorVersion };
1171
+ }
1172
+ const installerPath = memberJoin(targetOs, shell, stagingDir, anyBasename(localPath));
1173
+ const run = await deps.exec(agent, buildInstallCommand(installerPath, provider, targetOs, shell), INSTALL_TIMEOUT_MS);
1174
+ if (run.code !== 0) {
1175
+ const tail = (run.stderr.trim() || run.stdout.trim()).slice(-400);
1176
+ // A refusal means the running server has no member-install marker: a
1177
+ // human full install or an unmarked older member install. The fleet
1178
+ // never overrides it (see probeMemberInstallMarker); only the owner can.
1179
+ if (`${run.stdout}\n${run.stderr}`.includes(FULL_INSTALL_RUNNING_CODE)) {
1180
+ return {
1181
+ state: 'unavailable',
1182
+ reason: 'full-install-running',
1183
+ detail: `a running apra-fleet server on the member was not started by a member install and was left running: ${tail}. ${buildFullInstallReplaceHint({ home, targetOs, shell, provider, installer: { staged: true, path: installerPath } })}`,
1184
+ version: priorVersion,
1185
+ };
1186
+ }
1187
+ return { state: 'unavailable', reason: 'install-failed', detail: `installer exited ${run.code}: ${tail}`, version: priorVersion };
1188
+ }
1189
+ }
1190
+ finally {
1191
+ if (downloaded)
1192
+ deps.removeLocal(localPath);
1193
+ }
1194
+ const after = await probeMemberFleetVersion(agent, binPath, deps);
1195
+ if (after.kind !== 'installed' || isMemberOutdated(after.version, orchestratorVersion, !sameCoreFallback && sourceSuppliesBuild(source, orchestratorVersion))) {
1196
+ const seen = after.kind === 'installed' ? `reports ${after.version}` : after.kind === 'probe-failed' ? after.detail : after.kind;
1197
+ return {
1198
+ state: 'unavailable',
1199
+ reason: 'install-unverified',
1200
+ detail: `after install the member ${seen}; expected >= ${orchestratorVersion}`,
1201
+ version: priorVersion,
1202
+ };
1203
+ }
1204
+ return { state: 'available', version: after.version, installed: true, source: source.kind, binPath, ...(sameCoreFallback ? { sameCoreFallback } : {}) };
1205
+ }
1206
+ /**
1207
+ * One-line operator fix per fleetMcp reason. ASCII only, no newlines. Covers
1208
+ * every FleetMcpUnavailableReason plus the provider-level reasons the sprint
1209
+ * init records (opencode: no-per-tool-deny; agy: no-per-project-mcp).
1210
+ */
1211
+ export const FLEET_MCP_FIX = {
1212
+ 'home-unresolved': 'Check the member is reachable and its home directory resolves, then run member_detail with refresh:true.',
1213
+ 'probe-failed': 'Check the member is reachable (member_detail shows connectivity), then run member_detail with refresh:true.',
1214
+ 'arch-unknown': 'Check the member shell works (uname -m / PROCESSOR_ARCHITECTURE), then run update_member with fleet_install "auto".',
1215
+ 'unsupported-platform': 'Install apra-fleet on the member by hand; no release asset exists for its OS/arch.',
1216
+ 'no-install-source': 'Run the orchestrator as the single-executable binary or make release assets reachable, then run update_member with fleet_install "auto".',
1217
+ 'download-failed': 'Check the member/orchestrator can reach the release host, then run update_member with fleet_install "auto".',
1218
+ 'download-timeout': 'The release download did not finish in time; check the network to the release host, then run update_member with fleet_install "auto".',
1219
+ 'checksum-mismatch': 'The downloaded installer did not match its published SHA256SUMS; do not install it -- run update_member with fleet_install "auto" again, and report it if it repeats.',
1220
+ 'checksum-unavailable': 'No published SHA256SUMS lists this installer (release missing or incomplete); publish the release assets, then run update_member with fleet_install "auto".',
1221
+ 'no-matching-release': 'No published release carries an installer for this orchestrator build (no exact-build prerelease, and the stable release is a different build); install it on the member by hand with the steps in the update_member/register_member WARNING, or run the orchestrator from a published build, then run update_member with fleet_install "auto".',
1222
+ 'full-install-running': 'The member apra-fleet install has no member-install marker (a full install, or a member install older than the marker), so the fleet leaves it alone; its owner replaces it with a member install using the steps in the detail (back up data and fleet.key, uninstall with the installed binary, run the staged current installer with install --member), then update_member {member_id, fleet_install: "auto"} -- or opts in to the fleet doing it with update_member {member_id, fleet_install: "replace-full"}.',
1223
+ 'transfer-failed': 'Check file transfer to the member works (disk space, permissions), then run update_member with fleet_install "auto".',
1224
+ 'install-failed': 'Run the apra-fleet installer on the member by hand and read its error, then member_detail with refresh:true.',
1225
+ 'replace-failed': 'The full-install replacement stopped at the step named in the detail; run the rollback commands in the detail (if listed; they restore the consistent data copy, the backup only as a last resort), fix the cause, then run update_member {member_id, fleet_install: "replace-full"} again.',
1226
+ 'install-unverified': 'Run update_member {member_id, fleet_install: "auto"} to upgrade apra-fleet on the member to the orchestrator version, then member_detail with refresh:true.',
1227
+ 'install-too-old': 'Run update_member {member_id, fleet_install: "auto"} to upgrade apra-fleet on the member (its install predates register-member --id), then member_detail with refresh:true.',
1228
+ 'E-FOLDER-TAKEN': 'The member install has this work folder registered under another id; unregister it there, then member_detail with refresh:true.',
1229
+ 'register-failed': 'Run update_member {member_id, fleet_install: "auto"} to upgrade apra-fleet on the member and re-register it (read fleetMcp detail for the error), then member_detail with refresh:true.',
1230
+ 'mcp-entry-missing': 'Re-run compose_permissions for the member so its per-folder apra-fleet MCP entry points at ?member=<uuid>, then member_detail with refresh:true.',
1231
+ 'role-agents-hide-member-tools': 'Remote member: run update_member for it (re-provisions its role agent files); local member: the probe already tried to rewrite the role files in ~/.claude/agents, so make them writable (or re-run apra-fleet install on the orchestrator). Then member_detail with refresh:true.',
1232
+ 'no-per-project-mcp': 'agy has no per-project MCP config; its roles get injected knowledge only. Use another provider for KB/code tools.',
1233
+ 'provider-unsupported': 'This LLM provider has no MCP entry fleet configures; its roles get injected knowledge only.',
1234
+ 'member-config-unreadable': 'Fix permissions on the member config file named in the detail, then re-run compose_permissions.',
1235
+ 'member-config-unparseable': 'Make the member config file named in the detail strict JSON, then re-run compose_permissions.',
1236
+ 'opencode-config-tracked': 'Untrack opencode.json from git (add it to .gitignore), then re-run compose_permissions.',
1237
+ 'opencode-config-unparseable': 'Make the work folder opencode.json strict JSON (no comments), then re-run compose_permissions.',
1238
+ 'member-session-failed': 'Check the member apra-fleet server is running (apra-fleet status / start on the member), then member_detail with refresh:true.',
1239
+ 'member-tools-missing': 'Run update_member {member_id, fleet_install: "auto"} to upgrade apra-fleet on the member so its session lists kb_* and code_* tools, then member_detail with refresh:true.',
1240
+ 'member-secret-unavailable': 'Check the member access secret file named in the detail is readable by the member user (and that SFTP works on the member, which creates it), then run update_member {member_id, fleet_install: "auto"}.',
1241
+ 'no-per-tool-deny': 'opencode cannot deny individual tools, so its roles get injected knowledge only. Use another provider for KB/code tools.',
1242
+ };
1243
+ /**
1244
+ * The one-line fix to show for a fleetMcp status, or null when the member's KB
1245
+ * and code tools are usable (available and not flagged unverified).
1246
+ */
1247
+ export function fleetMcpFixLine(status) {
1248
+ if (!status)
1249
+ return null;
1250
+ if (status.state === 'available' && !status.unverified) {
1251
+ // Usable on an older install after a failed upgrade: show the upgrade fix.
1252
+ const f = status.installFailure ? FLEET_MCP_FIX[status.installFailure.reason] : undefined;
1253
+ return f ?? null;
1254
+ }
1255
+ const known = status.reason ? FLEET_MCP_FIX[status.reason] : undefined;
1256
+ return known ?? 'Run member_detail with refresh:true after fixing the cause named in the detail; KB/code tools are unverified on this member.';
1257
+ }
1258
+ let mcpDepsOverride = null;
1259
+ /** Test-only: replace the production transports used by register/update/remove_member and member_detail. Pass null to restore. */
1260
+ export function __setMemberFleetMcpDeps(deps) {
1261
+ mcpDepsOverride = deps;
1262
+ }
1263
+ /** The deps the tool handlers use (production transports unless a test injected fakes). */
1264
+ export function getMemberFleetMcpDeps() {
1265
+ return mcpDepsOverride ?? defaultMemberFleetMcpDeps();
1266
+ }
1267
+ export function defaultMemberFleetMcpDeps() {
1268
+ return {
1269
+ ...defaultMemberFleetInstallDeps(),
1270
+ connectLocalMember: async (memberId) => {
1271
+ const m = await import('@apralabs/apra-fleet-client/server-resolution');
1272
+ return m.connectFleetMember(memberId);
1273
+ },
1274
+ now: () => new Date(),
1275
+ record: (memberId, status) => { recordFleetMcpStatus(memberId, status); },
1276
+ roleAgents: async (agent) => {
1277
+ const m = await import('./agent-provisioner.js');
1278
+ return m.checkRoleAgentMemberTools(agent);
1279
+ },
1280
+ writeMcpEntry: async (agent) => {
1281
+ const m = await import('../tools/compose-permissions.js');
1282
+ return m.writeMemberMcpEntry(agent);
1283
+ },
1284
+ stageSecretFile: (agent, content) => writeMemberSecretFile(agent, content, 'member-access'),
1285
+ recordMemberSecret: (memberId, secret) => { updateAgent(memberId, { encryptedMemberMcpSecret: encryptPassword(secret) }); },
1286
+ };
1287
+ }
1288
+ const MEMBER_CALL_TIMEOUT_MS = 60_000;
1289
+ /** `register-member` on the member's own install, as a LOCAL member under the
1290
+ * orchestrator's id for it (exported for tests). */
1291
+ export function buildSelfRegisterCommand(binPath, agent, targetOs, shell) {
1292
+ const args = [
1293
+ 'register-member', '--type', 'local', '--id', agent.id,
1294
+ '--name', agent.friendlyName, '--path', agent.workFolder,
1295
+ '--llm', agent.llmProvider ?? 'claude',
1296
+ ];
1297
+ return memberCommandFor(targetOs, shell, {
1298
+ posix: `${posixQuote(binPath)} ${args.map(posixQuote).join(' ')}`,
1299
+ powershell: `& ${psQuote(binPath)} ${args.map(psQuote).join(' ')}`,
1300
+ });
1301
+ }
1302
+ /** `remove-member` on the member's own install (exported for tests). */
1303
+ export function buildSelfRemoveCommand(binPath, memberId, targetOs, shell) {
1304
+ const args = ['remove-member', '--id', memberId, '--force'];
1305
+ return memberCommandFor(targetOs, shell, {
1306
+ posix: `${posixQuote(binPath)} ${args.map(posixQuote).join(' ')}`,
1307
+ powershell: `& ${psQuote(binPath)} ${args.map(psQuote).join(' ')}`,
1308
+ });
1309
+ }
1310
+ /** `call --member <uuid> version` (with a `{}` args file written first) or
1311
+ * `call --member <uuid> --list-tools`, on the member (exported for tests). */
1312
+ export function buildMemberCallCommand(binPath, memberId, what, argsPath, targetOs, shell) {
1313
+ const callArgs = what === 'list-tools'
1314
+ ? ['call', '--member', memberId, '--list-tools']
1315
+ : ['call', '--member', memberId, 'version', '--args-file', argsPath, '--rm-args-file'];
1316
+ if (what === 'list-tools') {
1317
+ return memberCommandFor(targetOs, shell, {
1318
+ posix: `${posixQuote(binPath)} ${callArgs.map(posixQuote).join(' ')}`,
1319
+ powershell: `& ${psQuote(binPath)} ${callArgs.map(psQuote).join(' ')}`,
1320
+ });
1321
+ }
1322
+ return memberCommandFor(targetOs, shell, {
1323
+ posix: `printf '%s' '{}' > ${posixQuote(argsPath)} && ${posixQuote(binPath)} ${callArgs.map(posixQuote).join(' ')}`,
1324
+ powershell: `Set-Content -LiteralPath ${psQuote(argsPath)} -Value '{}' -NoNewline -Encoding ascii; ` +
1325
+ `& ${psQuote(binPath)} ${callArgs.map(psQuote).join(' ')}`,
1326
+ });
1327
+ }
1328
+ /**
1329
+ * Cap on member-side error text recorded in fleetMcp.detail. Large enough that
1330
+ * the leading ERROR line plus its cause (e.g. compose_permissions' full
1331
+ * searched-path list) always survive; only a runaway output is truncated.
1332
+ */
1333
+ export const MEMBER_ERROR_DETAIL_MAX = 4000;
1334
+ /**
1335
+ * The member-side error text to record in fleetMcp.detail. Keeps the HEAD of
1336
+ * the output (the `ERROR: ...` line and its cause come first), never the tail:
1337
+ * a tail slice drops the leading cause and leaves only the end of a long list.
1338
+ */
1339
+ export function memberErrorDetail(out, max = MEMBER_ERROR_DETAIL_MAX) {
1340
+ let text = out.trim();
1341
+ if (text.length <= max)
1342
+ return text;
1343
+ // Over the cap: start at the first ERROR line when log noise precedes it,
1344
+ // so the cap is spent on the error and its cause.
1345
+ const errAt = text.search(/^.*\bERROR\b/m);
1346
+ if (errAt > 0)
1347
+ text = text.slice(errAt);
1348
+ if (text.length <= max)
1349
+ return text;
1350
+ return `${text.slice(0, max)} ... [${text.length - max} more chars truncated]`;
1351
+ }
1352
+ /** Last parseable JSON object line in command output. */
1353
+ function lastJsonObject(text) {
1354
+ const lines = text.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
1355
+ for (let i = lines.length - 1; i >= 0; i--) {
1356
+ if (!lines[i].startsWith('{'))
1357
+ continue;
1358
+ try {
1359
+ const v = JSON.parse(lines[i]);
1360
+ if (v && typeof v === 'object' && !Array.isArray(v))
1361
+ return v;
1362
+ }
1363
+ catch { /* keep looking */ }
1364
+ }
1365
+ return null;
1366
+ }
1367
+ function toolResultText(result) {
1368
+ const content = result?.content;
1369
+ return Array.isArray(content) ? content.map(c => c?.text ?? '').join('\n') : '';
1370
+ }
1371
+ function toolNames(list) {
1372
+ const tools = list?.tools;
1373
+ return Array.isArray(tools) ? tools.map(t => String(t?.name ?? '')).filter(Boolean) : [];
1374
+ }
1375
+ const VERSION_TOKEN_RE = /v?\d+\.\d+\.\d+[^\s"',]*/;
1376
+ /** Judge a MEMBER session's version + tools/list answers. */
1377
+ function judgeSession(versionResult, list) {
1378
+ if (versionResult?.isError) {
1379
+ return { ok: false, reason: 'member-session-failed', detail: `version returned an error: ${toolResultText(versionResult).slice(0, 200)}` };
1380
+ }
1381
+ const names = toolNames(list);
1382
+ const hasKb = names.some(n => n.startsWith('kb_'));
1383
+ const hasCode = names.some(n => n.startsWith('code_'));
1384
+ if (!hasKb || !hasCode) {
1385
+ return {
1386
+ ok: false,
1387
+ reason: 'member-tools-missing',
1388
+ detail: `member session tools/list lacks ${[!hasKb && 'kb_*', !hasCode && 'code_*'].filter(Boolean).join(' and ')} (got ${names.length} tools)`,
1389
+ };
1390
+ }
1391
+ const m = VERSION_TOKEN_RE.exec(toolResultText(versionResult));
1392
+ return { ok: true, version: m?.[0] };
1393
+ }
1394
+ /** Parse `apra-fleet call` output; a {"error":{code,message}} line is a failure. */
1395
+ function parseCallOutput(r, what) {
1396
+ const parsed = lastJsonObject(`${r.stdout}\n${r.stderr}`);
1397
+ const err = parsed?.error;
1398
+ if (err && typeof err === 'object')
1399
+ return { ok: false, detail: `${what}: ${err.code ?? 'E-REMOTE'}: ${err.message ?? ''}`.trim() };
1400
+ if (r.code !== 0)
1401
+ return { ok: false, detail: `${what} exited ${r.code}: ${(r.stderr || r.stdout).trim().slice(-300)}` };
1402
+ if (!parsed)
1403
+ return { ok: false, detail: `${what}: unparseable output: ${r.stdout.trim().slice(0, 200)}` };
1404
+ return { ok: true, value: parsed };
1405
+ }
1406
+ /**
1407
+ * The URL of the member's per-folder apra-fleet MCP entry written by
1408
+ * compose_permissions, or null when there is none. claude:
1409
+ * <config dir>/.claude.json projects[<folder>].mcpServers['apra-fleet'].url;
1410
+ * opencode: <workFolder>/opencode.json mcp['apra-fleet'].url.
1411
+ */
1412
+ export async function readMemberMcpEntryUrl(agent, home, deps) {
1413
+ const targetOs = getAgentOS(agent);
1414
+ const shell = getAgentShell(agent);
1415
+ const isWindows = targetOs === 'windows';
1416
+ const posix = isPosixShell(targetOs, shell);
1417
+ const exec = (cmd, t) => deps.exec(agent, cmd, t ?? PROBE_TIMEOUT_MS);
1418
+ const rec = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : null;
1419
+ try {
1420
+ if ((agent.llmProvider ?? 'claude') === 'claude') {
1421
+ const configDir = await probeMemberClaudeConfigDir(exec, targetOs, shell);
1422
+ const file = claudeLocalScopeConfigFile(configDir, home, isWindows, shell).file;
1423
+ const config = await readMemberJson(exec, file, posix);
1424
+ const key = await resolveClaudeProjectKey(exec, agent.workFolder, isWindows, posix);
1425
+ const entry = rec(rec(rec(rec(config.projects)?.[key])?.mcpServers)?.[MEMBER_MCP_SERVER_NAME]);
1426
+ return typeof entry?.url === 'string' ? entry.url : null;
1427
+ }
1428
+ const file = joinMemberPath(agent.workFolder, OPENCODE_PROJECT_CONFIG, isWindows, shell);
1429
+ const config = await readMemberJson(exec, file, posix);
1430
+ const entry = rec(rec(config.mcp)?.[MEMBER_MCP_SERVER_NAME]);
1431
+ return typeof entry?.url === 'string' ? entry.url : null;
1432
+ }
1433
+ catch {
1434
+ return null;
1435
+ }
1436
+ }
1437
+ /**
1438
+ * The port a REMOTE member's own apra-fleet install listens on, resolved on
1439
+ * the member: the `port` its member-install marker
1440
+ * (<home>/.apra-fleet/data/member-install.json) records. server.json in the
1441
+ * same data dir is only advisory -- a no-op `apra-fleet start` never rewrites
1442
+ * it, so it can describe an older instance -- and a disagreement is reported
1443
+ * in `note` while the marker wins. A marker that records no port (an install
1444
+ * from before port recording) resolves to the built-in default with a note
1445
+ * saying so. Read commands carry resolved, quoted paths built here in JS (no
1446
+ * shell variable expansion). Never throws.
1447
+ */
1448
+ export async function resolveMemberMcpPort(agent, home, deps) {
1449
+ const targetOs = getAgentOS(agent);
1450
+ const shell = getAgentShell(agent);
1451
+ const posix = isPosixShell(targetOs, shell);
1452
+ const exec = (cmd, t) => deps.exec(agent, cmd, t ?? PROBE_TIMEOUT_MS);
1453
+ const markerPath = memberInstallMarkerPathFor(home, agent);
1454
+ let marker;
1455
+ try {
1456
+ marker = await readMemberJson(exec, markerPath, posix);
1457
+ }
1458
+ catch (err) {
1459
+ return { kind: 'failed', detail: `the member's apra-fleet port could not be read from ${markerPath}: ${err instanceof Error ? err.message : String(err)}` };
1460
+ }
1461
+ let serverPort;
1462
+ try {
1463
+ const info = await readMemberJson(exec, joinMemberPath(home, '.apra-fleet/data/server.json', targetOs === 'windows', shell), posix);
1464
+ serverPort = validPort(info.port);
1465
+ }
1466
+ catch { /* advisory only */ }
1467
+ const recorded = validPort(marker.port);
1468
+ if (recorded === undefined) {
1469
+ const seen = serverPort !== undefined && serverPort !== BUILTIN_DEFAULT_PORT ? ` (server.json there records port ${serverPort}, not used)` : '';
1470
+ return {
1471
+ kind: 'resolved', port: BUILTIN_DEFAULT_PORT, source: 'default',
1472
+ note: `the member install did not record its port in ${markerPath}, so the built-in default port ${BUILTIN_DEFAULT_PORT} is used${seen}; re-run update_member with fleet_install "auto" to record it`,
1473
+ };
1474
+ }
1475
+ if (serverPort !== undefined && serverPort !== recorded) {
1476
+ return {
1477
+ kind: 'resolved', port: recorded, source: 'marker',
1478
+ note: `the member-install marker records port ${recorded} but server.json records port ${serverPort}; using the marker's port ${recorded} (server.json may describe a stale or other instance)`,
1479
+ };
1480
+ }
1481
+ return { kind: 'resolved', port: recorded, source: 'marker' };
1482
+ }
1483
+ function memberQuery(agent) {
1484
+ return `?member=${encodeURIComponent(agent.id)}`;
1485
+ }
1486
+ /** Providers whose per-folder apra-fleet entry this module can verify. */
1487
+ const PER_FOLDER_PROVIDERS = new Set(['claude', 'opencode']);
1488
+ /**
1489
+ * Observe a member's apra-fleet MCP server and return its fleetMcp status.
1490
+ * Never throws and never records -- see refreshMemberFleetMcp for that.
1491
+ *
1492
+ * - agy: unavailable(no-per-project-mcp), unverified; nothing is probed.
1493
+ * - providers with no per-folder fleet entry: unavailable(provider-unsupported), unverified.
1494
+ * - LOCAL members: no install and no per-folder entry (a claude dispatch gets
1495
+ * the member config per session, --mcp-config). Verified by opening a
1496
+ * MEMBER session for the uuid on this server through the client's own
1497
+ * server resolution (registered member, version answers, kb_* / code_*
1498
+ * listed) -- the same server and member identity the injected URL names,
1499
+ * not a request to that literal URL or a run of the CLI with the file.
1500
+ * - remote members: ensure the install (opts.install, default true; false
1501
+ * only probes the version), register the member on its own install
1502
+ * (`register-member --type local --id <uuid>`), check the per-folder MCP
1503
+ * entry (not for claude: per-session config, the entry is only its
1504
+ * fallback), then verify a MEMBER session through `apra-fleet call`.
1505
+ * - claude, both: the role files `--agent <role>` loads must grant the member
1506
+ * tools; roleAgents heals them (local rewrite, remote re-provision) first.
1507
+ */
1508
+ export async function probeMemberFleetMcp(agent, deps = defaultMemberFleetMcpDeps(), opts = {}) {
1509
+ const ctx = { installedNow: false };
1510
+ const status = await probeMemberFleetMcpInner(agent, deps, opts, ctx);
1511
+ // Stamp fleetInstalledAt only from a successful fleet install in THIS probe;
1512
+ // otherwise carry the previously recorded value forward unchanged.
1513
+ const stamp = ctx.installedNow ? status.checkedAt : agent.fleetMcp?.fleetInstalledAt;
1514
+ const stamped = stamp ? { ...status, fleetInstalledAt: stamp } : status;
1515
+ // Local members share this orchestrator's install (its installer reports bd).
1516
+ if (agent.agentType === 'local')
1517
+ return stamped;
1518
+ const beads = await probeMemberBeads(agent, deps);
1519
+ return beads ? { ...stamped, beads } : stamped;
1520
+ }
1521
+ /** Fix line recorded with a missing/broken bd on a member. ASCII, one line. */
1522
+ export const BEADS_MISSING_FIX = 'Run update_member {member_id, fleet_install: "auto"} so the member installer puts bd in <home>/.apra-fleet/bin (or install bd on the member so bd --version works), then member_detail with refresh:true.';
1523
+ /** Suffix for a register/update fleetMcp result line: names a missing bd, else ''. */
1524
+ export function beadsStatusNote(status) {
1525
+ return status.beads ? ` -- warning: bd ${status.beads.state} on the member (${status.beads.detail}). Fix: ${status.beads.fix}` : '';
1526
+ }
1527
+ /** Where the member installer places bd when npm -g is not writable. */
1528
+ export function memberBeadsPath(home, targetOs, shell) {
1529
+ return memberJoin(targetOs, shell, home, '.apra-fleet', 'bin', targetOs === 'windows' ? 'bd.exe' : 'bd');
1530
+ }
1531
+ /**
1532
+ * The member-side bd probe: bd on the member's PATH first, else the member
1533
+ * install's <home>/.apra-fleet/bin copy -- the same order every fleet-built
1534
+ * member command resolves it in (BIN_DIR is appended to PATH). Tagged like
1535
+ * buildFleetVersionProbe: always exits 0, outcome in stdout.
1536
+ */
1537
+ export function buildBeadsProbe(bdPath, targetOs, shell) {
1538
+ const p = posixQuote(bdPath);
1539
+ const ps = psQuote(bdPath);
1540
+ return memberCommandFor(targetOs, shell, {
1541
+ posix: `if command -v bd >/dev/null 2>&1; then bd --version 2>/dev/null || printf '%s\\n' '${EXEC_FAILED_SENTINEL}'; ` +
1542
+ `elif [ -x ${p} ]; then ${p} --version 2>/dev/null || printf '%s\\n' '${EXEC_FAILED_SENTINEL}'; ` +
1543
+ `else printf '%s\\n' '${NO_INSTALL_SENTINEL}'; fi`,
1544
+ powershell: `if (Get-Command bd -ErrorAction SilentlyContinue) { $bd = 'bd' } elseif (Test-Path -LiteralPath ${ps}) { $bd = ${ps} } else { $bd = $null }; ` +
1545
+ `if ($bd) { try { $out = & $bd --version; if ($LASTEXITCODE -ne 0) { [Console]::Out.Write('${EXEC_FAILED_SENTINEL}') } ` +
1546
+ `else { [Console]::Out.Write(($out | Out-String)) } } catch { [Console]::Out.Write('${EXEC_FAILED_SENTINEL}') } } ` +
1547
+ `else { [Console]::Out.Write('${NO_INSTALL_SENTINEL}') }; exit 0`,
1548
+ });
1549
+ }
1550
+ /**
1551
+ * Probe bd on a remote member. Returns the `beads` field to record when bd is
1552
+ * missing or broken there, or null when it works or the probe itself could
1553
+ * not run (an unreachable member is reported by the fleetMcp status already).
1554
+ * Never throws.
1555
+ */
1556
+ export async function probeMemberBeads(agent, deps) {
1557
+ try {
1558
+ const targetOs = getAgentOS(agent);
1559
+ const shell = getAgentShell(agent);
1560
+ const home = await deps.resolveHome(agent);
1561
+ if (!home)
1562
+ return null;
1563
+ const bdPath = memberBeadsPath(home, targetOs, shell);
1564
+ const r = await deps.exec(agent, buildBeadsProbe(bdPath, targetOs, shell), PROBE_TIMEOUT_MS);
1565
+ if (r.stdout.includes(NO_INSTALL_SENTINEL)) {
1566
+ return { state: 'missing', detail: `bd is not on the member PATH and not at ${bdPath}`, fix: BEADS_MISSING_FIX };
1567
+ }
1568
+ if (r.stdout.includes(EXEC_FAILED_SENTINEL)) {
1569
+ return { state: 'broken', detail: 'bd is present on the member but bd --version failed', fix: BEADS_MISSING_FIX };
1570
+ }
1571
+ return null;
1572
+ }
1573
+ catch {
1574
+ return null;
1575
+ }
1576
+ }
1577
+ async function probeMemberFleetMcpInner(agent, deps, opts, ctx) {
1578
+ const checkedAt = () => deps.now().toISOString();
1579
+ const unavailable = (reason, detail, extra = {}) => ({
1580
+ state: 'unavailable', reason, checkedAt: checkedAt(), ...(detail ? { detail } : {}), ...extra,
1581
+ });
1582
+ try {
1583
+ const provider = agent.llmProvider ?? 'claude';
1584
+ if (provider === 'agy') {
1585
+ return unavailable('no-per-project-mcp', 'agy has no per-project MCP config fleet can point at the member session', { unverified: true });
1586
+ }
1587
+ if (!PER_FOLDER_PROVIDERS.has(provider)) {
1588
+ return unavailable('provider-unsupported', `fleet writes no per-folder apra-fleet MCP entry for provider "${provider}"`, { unverified: true });
1589
+ }
1590
+ const status = agent.agentType === 'local'
1591
+ ? await probeLocal(agent, deps, unavailable, checkedAt)
1592
+ : await probeRemote(agent, deps, opts.install !== false, unavailable, checkedAt, opts.forceInstall === true, ctx, opts.writeMcpEntry === true, opts.replaceFull === true);
1593
+ // The member session listing kb_*/code_* proves the server, not what a
1594
+ // dispatched role sees: roles run as `claude --agent <role>`, whose tools
1595
+ // list filters the session. Verify that path too.
1596
+ if (status.state === 'available' && provider === 'claude' && deps.roleAgents) {
1597
+ const roles = await deps.roleAgents(agent);
1598
+ if (!roles.ok) {
1599
+ const { state: _s, checkedAt: _c, detail: prior, ...keep } = status;
1600
+ return unavailable('role-agents-hide-member-tools', prior ? `${roles.detail}. Also: ${prior}` : roles.detail, keep);
1601
+ }
1602
+ if (roles.healed && roles.healed.length > 0) {
1603
+ const note = `rewrote role files that hid the member kb_*/code_* tools: ${roles.healed.join(', ')}`;
1604
+ return { ...status, detail: status.detail ? `${status.detail}. ${note}` : note };
1605
+ }
1606
+ }
1607
+ return status;
1608
+ }
1609
+ catch (err) {
1610
+ return unavailable('probe-failed', `probe threw: ${err instanceof Error ? err.message : String(err)}`);
1611
+ }
1612
+ }
1613
+ /**
1614
+ * Install failures the member probe never falls back from: the installer ran
1615
+ * (or was refused) on the member, or the member could not be probed at all.
1616
+ * Every other install failure happened before the member was touched, so an
1617
+ * older install there is intact and stays in use (reported, never silent).
1618
+ */
1619
+ const INSTALL_FAIL_CLOSED = new Set([
1620
+ 'install-failed', 'install-unverified', 'full-install-running', 'probe-failed', 'home-unresolved', 'replace-failed',
1621
+ ]);
1622
+ /** One line naming a failed upgrade and the older install still in use. */
1623
+ function installFailureNote(f, version) {
1624
+ return `the apra-fleet upgrade on the member failed (${f.reason}${f.detail ? `: ${f.detail.replace(/\.\s*$/, '')}` : ''}); the older apra-fleet ${version ?? '(unknown version)'} install is in use`;
1625
+ }
1626
+ async function probeLocal(agent, deps, unavailable, checkedAt) {
1627
+ let session;
1628
+ try {
1629
+ session = await deps.connectLocalMember(agent.id);
1630
+ }
1631
+ catch (err) {
1632
+ const e = err;
1633
+ return unavailable('member-session-failed', e.status === 403
1634
+ ? `server refused member ${agent.id}: not a registered member (HTTP 403)`
1635
+ : `could not open a member session: ${e.message ?? String(err)}`);
1636
+ }
1637
+ try {
1638
+ const versionResult = await session.mcpClient.callTool('version', {});
1639
+ const list = await session.mcpClient.listTools();
1640
+ const judged = judgeSession(versionResult, list);
1641
+ if (!judged.ok)
1642
+ return unavailable(judged.reason, judged.detail);
1643
+ return { state: 'available', checkedAt: checkedAt(), ...(judged.version ? { version: judged.version } : {}) };
1644
+ }
1645
+ catch (err) {
1646
+ return unavailable('member-session-failed', `member session call failed: ${err instanceof Error ? err.message : String(err)}`);
1647
+ }
1648
+ finally {
1649
+ try {
1650
+ if (session.close)
1651
+ await session.close();
1652
+ else
1653
+ session.transport?.stop?.();
1654
+ }
1655
+ catch { /* ignore */ }
1656
+ }
1657
+ }
1658
+ async function probeRemote(agent, deps, install, unavailable, checkedAt, forceInstall = false, ctx = { installedNow: false }, writeMcpEntry = false, replaceFull = false) {
1659
+ const targetOs = getAgentOS(agent);
1660
+ const shell = getAgentShell(agent);
1661
+ const home = await deps.resolveHome(agent);
1662
+ if (!home)
1663
+ return unavailable('home-unresolved', 'the member home directory could not be probed');
1664
+ const binPath = memberBinPath(home, targetOs, shell);
1665
+ // 1. Install (or, when not installing, just observe the version).
1666
+ let version;
1667
+ let installedNow = false;
1668
+ // A requested upgrade that failed BEFORE anything on the member was touched,
1669
+ // while the older install keeps serving: carried into the final status.
1670
+ let installFailure;
1671
+ // A full install this probe replaced (opt-in): reported on every outcome.
1672
+ let replaced;
1673
+ // Manual install steps for the member when a requested install did not happen.
1674
+ let manualInstall;
1675
+ // The signed same-core stable release installed instead of the exact build.
1676
+ let sameCoreFallback;
1677
+ if (install) {
1678
+ const r = await ensureMemberFleetInstall(agent, deps, { force: forceInstall, replaceFull });
1679
+ if (r.state === 'available') {
1680
+ version = r.version;
1681
+ if (r.installed) {
1682
+ ctx.installedNow = true;
1683
+ installedNow = true;
1684
+ }
1685
+ replaced = r.replaced;
1686
+ sameCoreFallback = r.sameCoreFallback;
1687
+ }
1688
+ // Fail closed -- with the install's OWN reason and detail, never a later
1689
+ // step's error (apra-fleet-b4g.73) -- when the installer ran or was
1690
+ // refused on the member, the probe itself failed, there is no older
1691
+ // install, or a provider change forced the install (the old install is
1692
+ // configured for the old provider).
1693
+ else if (!r.version || forceInstall || INSTALL_FAIL_CLOSED.has(r.reason)) {
1694
+ const detail = r.version
1695
+ ? `${(r.detail ?? r.reason).replace(/\.\s*$/, '')}; the member still has apra-fleet ${r.version}, which was not used`
1696
+ : r.detail;
1697
+ return unavailable(r.reason, detail, { ...(r.version ? { version: r.version } : {}), ...(r.manualSteps ? { manualInstall: r.manualSteps } : {}) });
1698
+ }
1699
+ // Otherwise the upgrade failed before the member was touched (no arch, no
1700
+ // source, download/checksum/transfer failure): the older install is
1701
+ // intact, so keep the member usable on it -- still only through the 2a
1702
+ // marker check below -- and report the failed upgrade in every outcome.
1703
+ else {
1704
+ version = r.version;
1705
+ installFailure = { reason: r.reason, ...(r.detail ? { detail: r.detail } : {}) };
1706
+ manualInstall = r.manualSteps;
1707
+ }
1708
+ }
1709
+ else {
1710
+ const p = await probeMemberFleetVersion(agent, binPath, deps);
1711
+ if (p.kind === 'probe-failed')
1712
+ return unavailable('probe-failed', p.detail);
1713
+ if (p.kind !== 'installed')
1714
+ return unavailable('install-unverified', p.kind === 'broken' ? p.detail : 'apra-fleet is not installed on the member');
1715
+ version = p.version;
1716
+ }
1717
+ const withVersion = {
1718
+ version,
1719
+ ...(installFailure ? { installFailure } : {}),
1720
+ ...(replaced ? { replacedFullInstall: replaced } : {}),
1721
+ ...(sameCoreFallback ? { sameCoreFallback } : {}),
1722
+ };
1723
+ const upgradeNote = installFailure ? installFailureNote(installFailure, version) : undefined;
1724
+ const replaceNote = replaced
1725
+ ? `replaced the apra-fleet ${replaced.previousVersion} full install with a member install ${version}; removed: ${replaced.removed.join('; ')}; backup at ${replaced.backupPath}`
1726
+ : undefined;
1727
+ // Set once the member's port is resolved (step 2c): the port fields and the
1728
+ // note about it ride on every later outcome, like a failed upgrade.
1729
+ let portFields = {};
1730
+ let portNote;
1731
+ const notes = () => [replaceNote, upgradeNote, portNote].filter((n) => !!n);
1732
+ // Every later outcome keeps a failed upgrade visible: a later step's error
1733
+ // must never hide it, and an available status still names it.
1734
+ const fail = (reason, detail) => {
1735
+ const also = notes();
1736
+ return unavailable(reason, also.length ? `${(detail ?? reason).replace(/\.\s*$/, '')}. Also: ${also.join('. ')}` : detail, { ...withVersion, ...(manualInstall ? { manualInstall } : {}), ...portFields });
1737
+ };
1738
+ // 2a. Self-register ONLY into a member install (marker present). An install
1739
+ // without the marker -- a human full install at the same <home>/.apra-fleet
1740
+ // path, or an unmarked older member install -- is never written to: a LOCAL
1741
+ // entry for this uuid there would let a later run mistake it for the fleet's
1742
+ // own. An install this probe just ran (--member) wrote the marker itself.
1743
+ if (!installedNow) {
1744
+ const marker = await probeMemberInstallMarker(agent, home, deps);
1745
+ if (marker.kind === 'probe-failed')
1746
+ return fail('probe-failed', marker.detail);
1747
+ if (marker.kind === 'absent') {
1748
+ // Stage the current installer only when an install was requested; a plain
1749
+ // status refresh must not copy or download a binary on every probe.
1750
+ const installer = await stageReplacementInstaller(agent, deps, home, null, install);
1751
+ if (install)
1752
+ manualInstall = manualInstall ?? `follow the owner steps in the reason above, then on the orchestrator run update_member {member_id, fleet_install: "auto"} so the fleet self-registers the member into that install and verifies it.`;
1753
+ return fail('full-install-running', `the apra-fleet ${version} at ${binPath} has no member-install marker, so the member was not registered into it. ${buildFullInstallReplaceHint({ home, targetOs, shell, provider: agent.llmProvider ?? 'claude', installer })}`);
1754
+ }
1755
+ }
1756
+ // 2c. The port the member's own install listens on, from its marker: the
1757
+ // per-folder entry written below and every later session config use it.
1758
+ // An unreadable marker keeps the previously recorded port (never a silent
1759
+ // fall back to the default, which another user's server may hold).
1760
+ const portRes = await resolveMemberMcpPort(agent, home, deps);
1761
+ let portAgent = agent;
1762
+ if (portRes.kind === 'resolved') {
1763
+ portFields = { port: portRes.port, portSource: portRes.source };
1764
+ portNote = portRes.note;
1765
+ portAgent = { ...agent, memberMcpPort: portRes.source === 'marker' ? portRes.port : undefined };
1766
+ }
1767
+ else {
1768
+ portNote = portRes.detail;
1769
+ }
1770
+ // 2d. The member install's access secret: its server refuses a ?member=
1771
+ // session without it, so the per-folder entry written below and every
1772
+ // session config carry it. An install older than the secret has none; when
1773
+ // an install was requested (fleet_install "auto") it is created there
1774
+ // through the secret-file channel, never a command string.
1775
+ const secretRes = await ensureRemoteMemberAccessSecret(agent, home, { exec: (cmd, t) => deps.exec(agent, cmd, t ?? PROBE_TIMEOUT_MS), stage: deps.stageSecretFile, removeStaged: removeMemberSecretFile }, install);
1776
+ if (secretRes.kind === 'failed')
1777
+ return fail('member-secret-unavailable', secretRes.detail);
1778
+ // 'absent' (read-only probe of an install older than the secret): its
1779
+ // server does not check one, so sessions there work without it.
1780
+ if (secretRes.kind === 'found' || secretRes.kind === 'created') {
1781
+ deps.recordMemberSecret?.(agent.id, secretRes.secret);
1782
+ portAgent = { ...portAgent, encryptedMemberMcpSecret: encryptPassword(secretRes.secret) };
1783
+ }
1784
+ // 2b. Register the member on its own install under the orchestrator's id.
1785
+ const reg = await deps.exec(agent, buildSelfRegisterCommand(binPath, agent, targetOs, shell), MEMBER_CALL_TIMEOUT_MS);
1786
+ if (reg.code !== 0) {
1787
+ const out = `${reg.stdout}\n${reg.stderr}`;
1788
+ if (/E-FOLDER-TAKEN/.test(out))
1789
+ return fail('E-FOLDER-TAKEN', memberErrorDetail(out));
1790
+ if (/unknown or unexpected argument "--id"/i.test(out) || /unknown (?:option|command|argument)[^\n]*(?:--id|register-member)/i.test(out)) {
1791
+ return fail('install-too-old', `the member's apra-fleet ${version} does not support register-member --id`);
1792
+ }
1793
+ return fail('register-failed', `register-member exited ${reg.code}: ${memberErrorDetail(out)}`);
1794
+ }
1795
+ // 3a. Write the per-folder MCP entry (the compose_permissions writer) so one
1796
+ // register/update call ends with it in place -- after self-registration, so
1797
+ // nothing the member-side register does can race it.
1798
+ // 3b. The per-folder MCP entry must point at this member -- for providers
1799
+ // whose dispatched session reads it. A claude dispatch gets the member
1800
+ // config per session (--mcp-config, see session-mcp-config.ts) once this
1801
+ // probe reports available, so for claude the entry is only the fallback:
1802
+ // it is still written (best effort) but neither its write nor its check gates.
1803
+ const perFolderGates = (agent.llmProvider ?? 'claude') !== 'claude';
1804
+ if (writeMcpEntry && deps.writeMcpEntry) {
1805
+ const w = await deps.writeMcpEntry(portAgent);
1806
+ if (!w.ok && perFolderGates)
1807
+ return fail(w.reason ?? 'mcp-entry-missing', w.detail);
1808
+ }
1809
+ if (perFolderGates) {
1810
+ const url = await readMemberMcpEntryUrl(agent, home, deps);
1811
+ if (!url || !url.endsWith(memberQuery(agent))) {
1812
+ return fail('mcp-entry-missing', url
1813
+ ? `per-folder apra-fleet entry points at ${url}, not ${memberQuery(agent)}`
1814
+ : 'no per-folder apra-fleet MCP entry for the work folder; run compose_permissions');
1815
+ }
1816
+ }
1817
+ // 4. A MEMBER session on the member answers version and lists kb_* / code_*.
1818
+ const argsPath = memberJoin(targetOs, shell, home, '.apra-fleet', `version-args-${agent.id}.json`);
1819
+ const v = parseCallOutput(await deps.exec(agent, buildMemberCallCommand(binPath, agent.id, 'version', argsPath, targetOs, shell), MEMBER_CALL_TIMEOUT_MS), 'call version');
1820
+ if (!v.ok)
1821
+ return fail('member-session-failed', v.detail);
1822
+ const l = parseCallOutput(await deps.exec(agent, buildMemberCallCommand(binPath, agent.id, 'list-tools', argsPath, targetOs, shell), MEMBER_CALL_TIMEOUT_MS), 'call --list-tools');
1823
+ if (!l.ok)
1824
+ return fail('member-session-failed', l.detail);
1825
+ const judged = judgeSession(v.value, l.value);
1826
+ if (!judged.ok)
1827
+ return fail(judged.reason, judged.detail);
1828
+ const finalNotes = notes();
1829
+ return {
1830
+ state: 'available', version, checkedAt: checkedAt(),
1831
+ ...(installFailure ? { installFailure } : {}),
1832
+ ...(manualInstall ? { manualInstall } : {}),
1833
+ ...(replaced ? { replacedFullInstall: replaced } : {}),
1834
+ ...(sameCoreFallback ? { sameCoreFallback } : {}),
1835
+ ...(finalNotes.length ? { detail: finalNotes.join('. ') } : {}),
1836
+ ...portFields,
1837
+ };
1838
+ }
1839
+ /**
1840
+ * Probe and RECORD the member's fleetMcp status on its registry entry. The
1841
+ * record is an observation, overwritten on every call, so a re-probe after a
1842
+ * manual fix flips unavailable -> available with no restart.
1843
+ */
1844
+ export async function refreshMemberFleetMcp(agent, deps = defaultMemberFleetMcpDeps(), opts = {}) {
1845
+ const status = await probeMemberFleetMcp(agent, deps, opts);
1846
+ deps.record(agent.id, status);
1847
+ return status;
1848
+ }
1849
+ /**
1850
+ * Remove the member's self-registration from its OWN install (remove_member's
1851
+ * counterpart of the register step). Local members share this orchestrator's
1852
+ * install, whose registry remove_member already edits, so nothing runs for
1853
+ * them. A member with no install has nothing to remove. Never throws.
1854
+ */
1855
+ export async function removeMemberFromOwnInstall(agent, deps = defaultMemberFleetInstallDeps()) {
1856
+ if (agent.agentType === 'local')
1857
+ return { removed: false, detail: 'local member: shares this install; nothing to remove member-side' };
1858
+ try {
1859
+ const targetOs = getAgentOS(agent);
1860
+ const shell = getAgentShell(agent);
1861
+ const home = await deps.resolveHome(agent);
1862
+ if (!home)
1863
+ return { removed: false, reason: 'home-unresolved', detail: 'the member home directory could not be probed' };
1864
+ const binPath = memberBinPath(home, targetOs, shell);
1865
+ const probe = await probeMemberFleetVersion(agent, binPath, deps);
1866
+ if (probe.kind === 'missing')
1867
+ return { removed: false, detail: 'apra-fleet is not installed on the member; nothing to remove' };
1868
+ if (probe.kind === 'probe-failed')
1869
+ return { removed: false, reason: 'probe-failed', detail: probe.detail };
1870
+ // The marker is the sole ownership signal: never touch an install the fleet
1871
+ // does not own, and never read a failed probe as ownership.
1872
+ const marker = await probeMemberInstallMarker(agent, home, deps);
1873
+ if (marker.kind === 'absent') {
1874
+ return { removed: false, skipped: true, reason: 'not-fleet-owned', detail: `skipped the member-side registration removal: the apra-fleet install at ${binPath} has no member-install marker, so it is not fleet-owned` };
1875
+ }
1876
+ if (marker.kind === 'probe-failed') {
1877
+ return { removed: false, skipped: true, reason: 'probe-failed', detail: `skipped the member-side registration removal: ownership of the member install could not be established (${marker.detail})` };
1878
+ }
1879
+ const r = await deps.exec(agent, buildSelfRemoveCommand(binPath, agent.id, targetOs, shell), MEMBER_CALL_TIMEOUT_MS);
1880
+ const out = `${r.stdout}\n${r.stderr}`;
1881
+ if (r.code === 0) {
1882
+ return /E-NOT-REGISTERED/.test(out)
1883
+ ? { removed: false, detail: `member ${agent.id} was not registered on its own install` }
1884
+ : { removed: true, detail: `removed member ${agent.id} from its own install` };
1885
+ }
1886
+ if (/unknown (?:option|command|argument)[^\n]*remove-member/i.test(out) || /remove-member/.test(out) && /unknown/i.test(out)) {
1887
+ return { removed: false, reason: 'install-too-old', detail: 'the member install has no remove-member verb' };
1888
+ }
1889
+ return { removed: false, reason: 'remove-failed', detail: `remove-member exited ${r.code}: ${out.trim().slice(-300)}` };
1890
+ }
1891
+ catch (err) {
1892
+ return { removed: false, reason: 'remove-failed', detail: err instanceof Error ? err.message : String(err) };
1893
+ }
1894
+ }
1895
+ //# sourceMappingURL=member-fleet-install.js.map