@apralabs/apra-fleet 0.4.3 → 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 (951) hide show
  1. package/README.md +66 -30
  2. package/dist/agents/backlog-groomer.md +75 -27
  3. package/dist/agents/ci-watcher.md +37 -22
  4. package/dist/agents/deployer.md +39 -22
  5. package/dist/agents/doer.md +74 -40
  6. package/dist/agents/harvester.md +49 -40
  7. package/dist/agents/integ-test-runner.md +40 -23
  8. package/dist/agents/kb-reconciler.md +28 -7
  9. package/dist/agents/plan-reviewer.md +49 -24
  10. package/dist/agents/planner.md +66 -43
  11. package/dist/agents/regression-test-runner.md +101 -78
  12. package/dist/agents/reviewer.md +117 -56
  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/planner-output.json +1 -1
  17. package/dist/agents/schemas/regression-test-runner-output.json +41 -7
  18. package/dist/agents/schemas/reviewer-output.json +62 -3
  19. package/dist/cli/agent-transform.d.ts +7 -0
  20. package/dist/cli/agent-transform.js +46 -1
  21. package/dist/cli/auth.d.ts +1 -0
  22. package/dist/cli/auth.js +38 -8
  23. package/dist/cli/beads-install.d.ts +35 -0
  24. package/dist/cli/beads-install.js +125 -0
  25. package/dist/cli/beads-pin.d.ts +5 -0
  26. package/dist/cli/beads-pin.js +27 -0
  27. package/dist/cli/call.d.ts +27 -0
  28. package/dist/cli/call.js +177 -0
  29. package/dist/cli/config.d.ts +24 -1
  30. package/dist/cli/config.js +69 -2
  31. package/dist/cli/dolt-install.d.ts +18 -2
  32. package/dist/cli/dolt-install.js +46 -15
  33. package/dist/cli/fleet-se-guard.d.ts +51 -0
  34. package/dist/cli/fleet-se-guard.js +215 -0
  35. package/dist/cli/install-guard.d.ts +54 -0
  36. package/dist/cli/install-guard.js +132 -4
  37. package/dist/cli/install.d.ts +77 -21
  38. package/dist/cli/install.js +610 -152
  39. package/dist/cli/kb-commit.d.ts +2 -1
  40. package/dist/cli/kb-commit.js +1 -1
  41. package/dist/cli/kb-import.d.ts +2 -1
  42. package/dist/cli/kb-import.js +1 -1
  43. package/dist/cli/register-member.js +20 -3
  44. package/dist/cli/remove-member.d.ts +4 -0
  45. package/dist/cli/remove-member.js +63 -0
  46. package/dist/cli/secret.js +9 -0
  47. package/dist/cli/start.js +59 -4
  48. package/dist/cli/status.d.ts +3 -0
  49. package/dist/cli/status.js +45 -12
  50. package/dist/cli/stop.js +64 -9
  51. package/dist/cli/uninstall.js +101 -15
  52. package/dist/cli/update.js +33 -2
  53. package/dist/cli/watch.js +1 -1
  54. package/dist/cli/workflow.js +3 -2
  55. package/dist/commands/kb-server.js +9 -2
  56. package/dist/hub-service/http-server.d.ts +5 -1
  57. package/dist/hub-service/http-server.js +55 -5
  58. package/dist/index.js +155 -8
  59. package/dist/os/child-env-bound.d.ts +77 -0
  60. package/dist/os/child-env-bound.js +171 -0
  61. package/dist/os/linux.d.ts +7 -2
  62. package/dist/os/linux.js +40 -14
  63. package/dist/os/macos.d.ts +1 -1
  64. package/dist/os/macos.js +2 -11
  65. package/dist/os/os-commands.d.ts +17 -2
  66. package/dist/os/windows-gitbash.d.ts +1 -0
  67. package/dist/os/windows-gitbash.js +17 -3
  68. package/dist/os/windows-wrapper.d.ts +0 -4
  69. package/dist/os/windows-wrapper.js +2 -1
  70. package/dist/os/windows.d.ts +5 -2
  71. package/dist/os/windows.js +75 -29
  72. package/dist/paths.d.ts +21 -0
  73. package/dist/paths.js +35 -0
  74. package/dist/providers/agy.d.ts +6 -2
  75. package/dist/providers/agy.js +245 -106
  76. package/dist/providers/claude-permission-denial.d.ts +7 -0
  77. package/dist/providers/claude-permission-denial.js +137 -0
  78. package/dist/providers/claude.d.ts +86 -38
  79. package/dist/providers/claude.js +426 -164
  80. package/dist/providers/codex.js +5 -1
  81. package/dist/providers/copilot.js +5 -1
  82. package/dist/providers/opencode.d.ts +10 -2
  83. package/dist/providers/opencode.js +114 -53
  84. package/dist/providers/provider.d.ts +171 -33
  85. package/dist/providers/provider.js +164 -3
  86. package/dist/services/agent-provisioner.d.ts +29 -0
  87. package/dist/services/agent-provisioner.js +107 -0
  88. package/dist/services/agent-shadow.d.ts +96 -0
  89. package/dist/services/agent-shadow.js +479 -0
  90. package/dist/services/agy-project.d.ts +2 -1
  91. package/dist/services/agy-project.js +15 -17
  92. package/dist/services/auth-socket.d.ts +25 -0
  93. package/dist/services/auth-socket.js +68 -23
  94. package/dist/services/auth-web.js +1 -1
  95. package/dist/services/budget-awareness.d.ts +11 -11
  96. package/dist/services/budget-awareness.js +15 -3
  97. package/dist/services/claude-local-scope-mcp.d.ts +19 -0
  98. package/dist/services/claude-local-scope-mcp.js +91 -0
  99. package/dist/services/cloud/aws.js +2 -1
  100. package/dist/services/cloud/lifecycle.js +19 -2
  101. package/dist/services/cloud/task-wrapper.d.ts +0 -9
  102. package/dist/services/cloud/task-wrapper.js +15 -6
  103. package/dist/services/event-loop-watchdog.d.ts +32 -0
  104. package/dist/services/event-loop-watchdog.js +140 -0
  105. package/dist/services/http-transport.d.ts +49 -1
  106. package/dist/services/http-transport.js +190 -24
  107. package/dist/services/in-flight-agents.d.ts +2 -0
  108. package/dist/services/in-flight-agents.js +4 -0
  109. package/dist/services/knowledge/bible-basis-filter.d.ts +53 -0
  110. package/dist/services/knowledge/bible-basis-filter.js +134 -0
  111. package/dist/services/knowledge/bible-blob-id.d.ts +44 -0
  112. package/dist/services/knowledge/bible-blob-id.js +113 -0
  113. package/dist/services/knowledge/bible-import.d.ts +65 -0
  114. package/dist/services/knowledge/bible-import.js +211 -0
  115. package/dist/services/knowledge/file-hash.d.ts +31 -0
  116. package/dist/services/knowledge/file-hash.js +153 -23
  117. package/dist/services/knowledge/http-provider.d.ts +4 -3
  118. package/dist/services/knowledge/http-provider.js +17 -5
  119. package/dist/services/knowledge/kb-maintainer-grant.d.ts +15 -0
  120. package/dist/services/knowledge/kb-maintainer-grant.js +34 -0
  121. package/dist/services/knowledge/kb-providers.d.ts +4 -0
  122. package/dist/services/knowledge/kb-providers.js +8 -0
  123. package/dist/services/knowledge/kb-removed-scope-keys.d.ts +28 -0
  124. package/dist/services/knowledge/kb-removed-scope-keys.js +59 -0
  125. package/dist/services/knowledge/kb-scopes.d.ts +14 -0
  126. package/dist/services/knowledge/kb-scopes.js +47 -0
  127. package/dist/services/knowledge/kb-self.d.ts +91 -0
  128. package/dist/services/knowledge/kb-self.js +198 -0
  129. package/dist/services/knowledge/member-bible-view.d.ts +21 -0
  130. package/dist/services/knowledge/member-bible-view.js +194 -0
  131. package/dist/services/knowledge/pre-init.js +1 -0
  132. package/dist/services/knowledge/project-slug.js +2 -2
  133. package/dist/services/knowledge/sqlite-provider.d.ts +64 -11
  134. package/dist/services/knowledge/sqlite-provider.js +303 -41
  135. package/dist/services/knowledge/types.d.ts +45 -2
  136. package/dist/services/member-access-secret.d.ts +70 -0
  137. package/dist/services/member-access-secret.js +195 -0
  138. package/dist/services/member-call-counts.d.ts +24 -0
  139. package/dist/services/member-call-counts.js +58 -0
  140. package/dist/services/member-config-io.d.ts +192 -0
  141. package/dist/services/member-config-io.js +443 -0
  142. package/dist/services/member-fleet-install.d.ts +710 -0
  143. package/dist/services/member-fleet-install.js +1895 -0
  144. package/dist/services/member-secret-env.d.ts +42 -0
  145. package/dist/services/member-secret-env.js +68 -0
  146. package/dist/services/member-tool-allowlist.d.ts +49 -0
  147. package/dist/services/member-tool-allowlist.js +111 -0
  148. package/dist/services/model-pricing.d.ts +19 -0
  149. package/dist/services/model-pricing.js +54 -8
  150. package/dist/services/port-holder.d.ts +86 -0
  151. package/dist/services/port-holder.js +351 -0
  152. package/dist/services/preflight-check.js +2 -0
  153. package/dist/services/registry.d.ts +13 -2
  154. package/dist/services/registry.js +27 -1
  155. package/dist/services/relay-strategy.d.ts +2 -0
  156. package/dist/services/relay-strategy.js +8 -0
  157. package/dist/services/server-lifecycle.d.ts +26 -0
  158. package/dist/services/server-lifecycle.js +85 -0
  159. package/dist/services/service-manager/index.d.ts +7 -1
  160. package/dist/services/service-manager/index.js +17 -4
  161. package/dist/services/service-manager/linux.d.ts +1 -1
  162. package/dist/services/service-manager/linux.js +15 -7
  163. package/dist/services/service-manager/macos.d.ts +11 -1
  164. package/dist/services/service-manager/macos.js +45 -7
  165. package/dist/services/service-manager/service-path.d.ts +24 -0
  166. package/dist/services/service-manager/service-path.js +55 -0
  167. package/dist/services/service-manager/types.d.ts +38 -3
  168. package/dist/services/service-manager/types.js +29 -0
  169. package/dist/services/service-manager/windows.d.ts +181 -2
  170. package/dist/services/service-manager/windows.js +666 -49
  171. package/dist/services/service-notice.d.ts +14 -0
  172. package/dist/services/service-notice.js +62 -0
  173. package/dist/services/service-start-guard.d.ts +20 -0
  174. package/dist/services/service-start-guard.js +86 -0
  175. package/dist/services/session-cost.d.ts +24 -0
  176. package/dist/services/session-cost.js +105 -0
  177. package/dist/services/session-mcp-config.d.ts +83 -0
  178. package/dist/services/session-mcp-config.js +211 -0
  179. package/dist/services/sftp.d.ts +34 -0
  180. package/dist/services/sftp.js +304 -76
  181. package/dist/services/shell-probe.d.ts +0 -24
  182. package/dist/services/shell-probe.js +28 -3
  183. package/dist/services/singleton.d.ts +68 -2
  184. package/dist/services/singleton.js +168 -11
  185. package/dist/services/sprint-coordination.js +9 -3
  186. package/dist/services/ssh.d.ts +27 -0
  187. package/dist/services/ssh.js +229 -38
  188. package/dist/services/stall/find-log-file.js +12 -5
  189. package/dist/services/stall/index.d.ts +1 -1
  190. package/dist/services/stall/read-log-tail.d.ts +23 -0
  191. package/dist/services/stall/read-log-tail.js +33 -2
  192. package/dist/services/stall/stall-detector.d.ts +25 -1
  193. package/dist/services/stall/stall-detector.js +85 -6
  194. package/dist/services/stall/stall-poller.d.ts +16 -0
  195. package/dist/services/stall/stall-poller.js +50 -6
  196. package/dist/services/stopped-marker.d.ts +16 -0
  197. package/dist/services/stopped-marker.js +55 -0
  198. package/dist/services/strategy.d.ts +33 -1
  199. package/dist/services/strategy.js +86 -17
  200. package/dist/services/supervisor-service-cleanup.d.ts +52 -0
  201. package/dist/services/supervisor-service-cleanup.js +332 -0
  202. package/dist/services/tool-registry.d.ts +8 -1
  203. package/dist/services/tool-registry.js +160 -59
  204. package/dist/services/tool-scope.d.ts +58 -0
  205. package/dist/services/tool-scope.js +99 -0
  206. package/dist/services/watch/project-resolver.js +1 -0
  207. package/dist/skills/auto-sprint-args/SKILL.md +2 -2
  208. package/dist/skills/fleet-sprint-cli/SKILL.md +39 -15
  209. package/dist/skills/pm/SKILL.md +3 -3
  210. package/dist/skills/pm/index.md +4 -2
  211. package/dist/skills/pm/kb-reconcile.md +29 -14
  212. package/dist/skills/pm/kb-review.md +1 -0
  213. package/dist/skills/pm/sprint.md +5 -5
  214. package/dist/tools/check-status.d.ts +53 -5
  215. package/dist/tools/check-status.js +210 -53
  216. package/dist/tools/child-id-allocator.d.ts +2 -2
  217. package/dist/tools/child-id-allocator.js +1 -1
  218. package/dist/tools/code-index-heal.d.ts +8 -0
  219. package/dist/tools/code-index-heal.js +21 -0
  220. package/dist/tools/code-index-state.d.ts +45 -0
  221. package/dist/tools/code-index-state.js +115 -0
  222. package/dist/tools/code-intelligence-codebase-memory.js +6 -33
  223. package/dist/tools/code-intelligence-freshness.js +1 -1
  224. package/dist/tools/code-intelligence-gitnexus.d.ts +30 -0
  225. package/dist/tools/code-intelligence-gitnexus.js +333 -57
  226. package/dist/tools/code-intelligence-kb-enrich.js +7 -6
  227. package/dist/tools/code-intelligence-readiness.d.ts +99 -0
  228. package/dist/tools/code-intelligence-readiness.js +206 -0
  229. package/dist/tools/code-intelligence-reindex.d.ts +195 -0
  230. package/dist/tools/code-intelligence-reindex.js +530 -50
  231. package/dist/tools/code-intelligence-telemetry.d.ts +6 -1
  232. package/dist/tools/code-intelligence-telemetry.js +12 -3
  233. package/dist/tools/code-intelligence.d.ts +81 -31
  234. package/dist/tools/code-intelligence.js +156 -52
  235. package/dist/tools/compose-permissions.d.ts +57 -2
  236. package/dist/tools/compose-permissions.js +497 -44
  237. package/dist/tools/execute-command.d.ts +11 -0
  238. package/dist/tools/execute-command.js +80 -12
  239. package/dist/tools/execute-prompt.d.ts +59 -15
  240. package/dist/tools/execute-prompt.js +544 -133
  241. package/dist/tools/kb-bible-commit.d.ts +65 -0
  242. package/dist/tools/kb-bible-commit.js +239 -0
  243. package/dist/tools/kb-capture.d.ts +13 -9
  244. package/dist/tools/kb-capture.js +42 -11
  245. package/dist/tools/kb-context.d.ts +27 -7
  246. package/dist/tools/kb-context.js +60 -9
  247. package/dist/tools/kb-export.d.ts +96 -7
  248. package/dist/tools/kb-export.js +228 -65
  249. package/dist/tools/kb-feedback.d.ts +13 -9
  250. package/dist/tools/kb-feedback.js +13 -7
  251. package/dist/tools/kb-freshness-sweep.d.ts +11 -7
  252. package/dist/tools/kb-freshness-sweep.js +7 -7
  253. package/dist/tools/kb-harvest.d.ts +11 -7
  254. package/dist/tools/kb-harvest.js +7 -7
  255. package/dist/tools/kb-import.d.ts +26 -10
  256. package/dist/tools/kb-import.js +169 -159
  257. package/dist/tools/kb-invalidate.d.ts +17 -10
  258. package/dist/tools/kb-invalidate.js +41 -8
  259. package/dist/tools/kb-list.d.ts +14 -10
  260. package/dist/tools/kb-list.js +30 -10
  261. package/dist/tools/kb-promote.d.ts +11 -7
  262. package/dist/tools/kb-promote.js +14 -8
  263. package/dist/tools/kb-query.d.ts +21 -11
  264. package/dist/tools/kb-query.js +76 -13
  265. package/dist/tools/kb-reconcile-prefilter.d.ts +11 -7
  266. package/dist/tools/kb-reconcile-prefilter.js +10 -8
  267. package/dist/tools/kb-resolve-contradiction.d.ts +11 -7
  268. package/dist/tools/kb-resolve-contradiction.js +7 -7
  269. package/dist/tools/kb-session-prime.d.ts +14 -7
  270. package/dist/tools/kb-session-prime.js +44 -44
  271. package/dist/tools/kb-setup.d.ts +11 -4
  272. package/dist/tools/kb-setup.js +25 -11
  273. package/dist/tools/kb-stats.d.ts +11 -10
  274. package/dist/tools/kb-stats.js +22 -41
  275. package/dist/tools/list-members.js +5 -2
  276. package/dist/tools/member-detail.d.ts +3 -0
  277. package/dist/tools/member-detail.js +88 -17
  278. package/dist/tools/member-reservation.d.ts +2 -2
  279. package/dist/tools/provision-auth.d.ts +39 -1
  280. package/dist/tools/provision-auth.js +269 -47
  281. package/dist/tools/provision-vcs-auth.d.ts +2 -2
  282. package/dist/tools/receive-files.js +3 -1
  283. package/dist/tools/register-member.d.ts +34 -8
  284. package/dist/tools/register-member.js +76 -58
  285. package/dist/tools/remove-member.js +110 -32
  286. package/dist/tools/send-email.d.ts +2 -2
  287. package/dist/tools/send-files.js +6 -4
  288. package/dist/tools/session-stats.d.ts +17 -0
  289. package/dist/tools/session-stats.js +27 -0
  290. package/dist/tools/shutdown-server.js +5 -0
  291. package/dist/tools/update-agent-cli.d.ts +19 -0
  292. package/dist/tools/update-agent-cli.js +59 -2
  293. package/dist/tools/update-member.d.ts +13 -10
  294. package/dist/tools/update-member.js +138 -7
  295. package/dist/tools/vcs-credential-exec.js +8 -2
  296. package/dist/types.d.ts +98 -1
  297. package/dist/utils/agent-helpers.js +2 -0
  298. package/dist/utils/auth-env.d.ts +15 -4
  299. package/dist/utils/auth-env.js +52 -23
  300. package/dist/utils/find-on-path.d.ts +37 -0
  301. package/dist/utils/find-on-path.js +85 -0
  302. package/dist/utils/log-helpers.d.ts +37 -0
  303. package/dist/utils/log-helpers.js +106 -20
  304. package/dist/utils/owner-only-fs.d.ts +56 -0
  305. package/dist/utils/owner-only-fs.js +98 -0
  306. package/dist/utils/process-utils.d.ts +28 -0
  307. package/dist/utils/process-utils.js +68 -0
  308. package/dist/utils/prompt-errors.js +4 -1
  309. package/dist/utils/session-caller.d.ts +4 -2
  310. package/dist/utils/session-caller.js +3 -2
  311. package/dist/utils/shell-escape.d.ts +42 -3
  312. package/dist/utils/shell-escape.js +70 -4
  313. package/dist/utils/ssh-error-messages.js +3 -0
  314. package/dist/utils/workspace-trust.d.ts +24 -1
  315. package/dist/utils/workspace-trust.js +21 -17
  316. package/dist/workflows/auto-sprint.js +223 -43
  317. package/package.json +11 -8
  318. package/packages/apra-fleet-client/package.json +2 -2
  319. package/packages/apra-fleet-client/src/client/api.mjs +558 -27
  320. package/packages/apra-fleet-client/src/client/auto-start.mjs +434 -0
  321. package/packages/apra-fleet-client/src/client/client.mjs +9 -0
  322. package/packages/apra-fleet-client/src/client/factory.mjs +23 -4
  323. package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +137 -0
  324. package/packages/apra-fleet-client/src/client/server-resolution.mjs +267 -30
  325. package/packages/apra-fleet-client/src/client/transport.mjs +37 -3
  326. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +75 -27
  327. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +37 -22
  328. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +39 -22
  329. package/packages/apra-fleet-se/apra-pm/agents/doer.md +74 -40
  330. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +49 -40
  331. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +40 -23
  332. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +28 -7
  333. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +49 -24
  334. package/packages/apra-fleet-se/apra-pm/agents/planner.md +66 -43
  335. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +101 -78
  336. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +117 -56
  337. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +1 -1
  338. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +32 -0
  339. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +1 -5
  340. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +1 -1
  341. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +41 -7
  342. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +62 -3
  343. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +3 -3
  344. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +4 -2
  345. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +29 -14
  346. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +1 -0
  347. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +5 -5
  348. package/packages/apra-fleet-se/bin/cli.mjs +184 -54
  349. package/packages/apra-fleet-se/bin/serve.mjs +143 -10
  350. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +56 -20
  351. package/packages/apra-fleet-se/fleet-sprint/backlog-role.mjs +93 -0
  352. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +208 -53
  353. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +576 -33
  354. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +9 -0
  355. package/packages/apra-fleet-se/fleet-sprint/beads-memory-hygiene.mjs +201 -0
  356. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +114 -7
  357. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +154 -8
  358. package/packages/apra-fleet-se/fleet-sprint/ci-gate.mjs +353 -0
  359. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +12 -0
  360. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +60 -1
  361. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +25 -2
  362. package/packages/apra-fleet-se/fleet-sprint/dispatch-accounting.mjs +270 -0
  363. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +22 -2
  364. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +205 -16
  365. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +52 -14
  366. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +6 -1
  367. package/packages/apra-fleet-se/fleet-sprint/docs/fleet-sprint-diagram.md +3 -3
  368. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +339 -20
  369. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +210 -11
  370. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +4 -4
  371. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +200 -9
  372. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +57 -9
  373. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +53 -4
  374. package/packages/apra-fleet-se/fleet-sprint/kb-hints.mjs +181 -0
  375. package/packages/apra-fleet-se/fleet-sprint/kb-injection.mjs +64 -0
  376. package/packages/apra-fleet-se/fleet-sprint/kb-maintainer.mjs +298 -0
  377. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +1257 -301
  378. package/packages/apra-fleet-se/fleet-sprint/lower-quality.mjs +39 -0
  379. package/packages/apra-fleet-se/fleet-sprint/member-align.mjs +391 -0
  380. package/packages/apra-fleet-se/fleet-sprint/member-call.mjs +374 -0
  381. package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +644 -0
  382. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +447 -0
  383. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +250 -29
  384. package/packages/apra-fleet-se/fleet-sprint/orphan-reclaim.mjs +153 -0
  385. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +82 -0
  386. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +97 -50
  387. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +1 -0
  388. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +81 -18
  389. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +43 -11
  390. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +6 -6
  391. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +20 -15
  392. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +60 -38
  393. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +42 -10
  394. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +16 -11
  395. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +36 -3
  396. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +72 -12
  397. package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +259 -0
  398. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +83 -25
  399. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +19 -1
  400. package/packages/apra-fleet-se/fleet-sprint/runner.js +834 -142
  401. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +24 -0
  402. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +130 -0
  403. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +111 -0
  404. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +44 -1
  405. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +39 -15
  406. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +84 -30
  407. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +138 -2
  408. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +111 -11
  409. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +22 -0
  410. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +7 -0
  411. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +180 -14
  412. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +134 -7
  413. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +99 -0
  414. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +223 -0
  415. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +49 -0
  416. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +8 -4
  417. package/packages/apra-fleet-se/fleet-sprint/verify-block.mjs +152 -0
  418. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +235 -21
  419. package/packages/apra-fleet-se/package.json +2 -2
  420. package/packages/apra-fleet-se/src/supervisor/api.mjs +919 -0
  421. package/packages/apra-fleet-se/src/supervisor/backlog-member.mjs +332 -0
  422. package/packages/apra-fleet-se/src/supervisor/backlog.mjs +982 -0
  423. package/packages/apra-fleet-se/src/supervisor/beads-identity.mjs +246 -0
  424. package/packages/apra-fleet-se/src/supervisor/beads-view.mjs +438 -0
  425. package/packages/apra-fleet-se/src/supervisor/child-port.mjs +36 -0
  426. package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +1659 -0
  427. package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +350 -0
  428. package/packages/apra-fleet-se/src/supervisor/dolt-orphan-sweep.mjs +338 -0
  429. package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +279 -0
  430. package/packages/apra-fleet-se/src/supervisor/history-view.mjs +276 -0
  431. package/packages/apra-fleet-se/src/supervisor/history.mjs +328 -0
  432. package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +521 -0
  433. package/packages/apra-fleet-se/src/supervisor/launch-form.mjs +444 -0
  434. package/packages/apra-fleet-se/src/supervisor/ledger.mjs +629 -0
  435. package/packages/apra-fleet-se/src/supervisor/lib/exec-bd.mjs +303 -0
  436. package/packages/apra-fleet-se/src/supervisor/log-timestamp.mjs +51 -0
  437. package/packages/apra-fleet-se/src/supervisor/log-view.mjs +159 -0
  438. package/packages/apra-fleet-se/src/supervisor/proxy.mjs +474 -0
  439. package/packages/apra-fleet-se/src/supervisor/readopt.mjs +136 -0
  440. package/packages/apra-fleet-se/src/supervisor/reconcile.mjs +263 -0
  441. package/packages/apra-fleet-se/src/supervisor/rename-with-retry.mjs +87 -0
  442. package/packages/apra-fleet-se/src/supervisor/scope-overlap.mjs +327 -0
  443. package/packages/apra-fleet-se/src/supervisor/self-log.mjs +133 -0
  444. package/packages/apra-fleet-se/src/supervisor/server.mjs +399 -0
  445. package/packages/apra-fleet-se/src/supervisor/spawner.mjs +542 -0
  446. package/packages/apra-fleet-se/src/supervisor/sprint-identity.mjs +96 -0
  447. package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +987 -0
  448. package/packages/apra-fleet-workflow/package.json +1 -1
  449. package/packages/apra-fleet-workflow/src/viewer/index.mjs +64 -9
  450. package/packages/apra-fleet-workflow/src/viewer/run-summary.mjs +127 -0
  451. package/packages/apra-fleet-workflow/src/workflow/index.mjs +71 -5
  452. package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +75 -25
  453. package/skills/fleet/permissions.md +9 -0
  454. package/skills/fleet/profiles/tag-kb-reconciler.json +2 -6
  455. package/version.json +1 -1
  456. package/dist/cli/agent-transform.d.ts.map +0 -1
  457. package/dist/cli/agent-transform.js.map +0 -1
  458. package/dist/cli/auth.d.ts.map +0 -1
  459. package/dist/cli/auth.js.map +0 -1
  460. package/dist/cli/config.d.ts.map +0 -1
  461. package/dist/cli/config.js.map +0 -1
  462. package/dist/cli/dolt-install.d.ts.map +0 -1
  463. package/dist/cli/dolt-install.js.map +0 -1
  464. package/dist/cli/install-guard.d.ts.map +0 -1
  465. package/dist/cli/install-guard.js.map +0 -1
  466. package/dist/cli/install.d.ts.map +0 -1
  467. package/dist/cli/install.js.map +0 -1
  468. package/dist/cli/join.d.ts.map +0 -1
  469. package/dist/cli/join.js.map +0 -1
  470. package/dist/cli/kb-commit.d.ts.map +0 -1
  471. package/dist/cli/kb-commit.js.map +0 -1
  472. package/dist/cli/kb-directives.d.ts.map +0 -1
  473. package/dist/cli/kb-directives.js.map +0 -1
  474. package/dist/cli/kb-import.d.ts.map +0 -1
  475. package/dist/cli/kb-import.js.map +0 -1
  476. package/dist/cli/register-member.d.ts.map +0 -1
  477. package/dist/cli/register-member.js.map +0 -1
  478. package/dist/cli/restart.d.ts.map +0 -1
  479. package/dist/cli/restart.js.map +0 -1
  480. package/dist/cli/secret.d.ts.map +0 -1
  481. package/dist/cli/secret.js.map +0 -1
  482. package/dist/cli/spoke.d.ts.map +0 -1
  483. package/dist/cli/spoke.js.map +0 -1
  484. package/dist/cli/start.d.ts.map +0 -1
  485. package/dist/cli/start.js.map +0 -1
  486. package/dist/cli/status.d.ts.map +0 -1
  487. package/dist/cli/status.js.map +0 -1
  488. package/dist/cli/stop.d.ts.map +0 -1
  489. package/dist/cli/stop.js.map +0 -1
  490. package/dist/cli/uninstall.d.ts.map +0 -1
  491. package/dist/cli/uninstall.js.map +0 -1
  492. package/dist/cli/update.d.ts.map +0 -1
  493. package/dist/cli/update.js.map +0 -1
  494. package/dist/cli/watch.d.ts.map +0 -1
  495. package/dist/cli/watch.js.map +0 -1
  496. package/dist/cli/workflow-assets.d.ts.map +0 -1
  497. package/dist/cli/workflow-assets.js.map +0 -1
  498. package/dist/cli/workflow.d.ts.map +0 -1
  499. package/dist/cli/workflow.js.map +0 -1
  500. package/dist/commands/kb-server.d.ts.map +0 -1
  501. package/dist/commands/kb-server.js.map +0 -1
  502. package/dist/delivery-mode.d.ts.map +0 -1
  503. package/dist/delivery-mode.js.map +0 -1
  504. package/dist/hub-service/activity.d.ts.map +0 -1
  505. package/dist/hub-service/activity.js.map +0 -1
  506. package/dist/hub-service/audit-log.d.ts.map +0 -1
  507. package/dist/hub-service/audit-log.js.map +0 -1
  508. package/dist/hub-service/db/pool.d.ts.map +0 -1
  509. package/dist/hub-service/db/pool.js.map +0 -1
  510. package/dist/hub-service/enrollment.d.ts.map +0 -1
  511. package/dist/hub-service/enrollment.js.map +0 -1
  512. package/dist/hub-service/envelope-routes.d.ts.map +0 -1
  513. package/dist/hub-service/envelope-routes.js.map +0 -1
  514. package/dist/hub-service/handlers/installers.d.ts.map +0 -1
  515. package/dist/hub-service/handlers/installers.js.map +0 -1
  516. package/dist/hub-service/http-server.d.ts.map +0 -1
  517. package/dist/hub-service/http-server.js.map +0 -1
  518. package/dist/hub-service/hub-jwt.d.ts.map +0 -1
  519. package/dist/hub-service/hub-jwt.js.map +0 -1
  520. package/dist/hub-service/jwt-revocation.d.ts.map +0 -1
  521. package/dist/hub-service/jwt-revocation.js.map +0 -1
  522. package/dist/hub-service/machines.d.ts.map +0 -1
  523. package/dist/hub-service/machines.js.map +0 -1
  524. package/dist/hub-service/main.d.ts.map +0 -1
  525. package/dist/hub-service/main.js.map +0 -1
  526. package/dist/hub-service/member-tokens.d.ts.map +0 -1
  527. package/dist/hub-service/member-tokens.js.map +0 -1
  528. package/dist/hub-service/member-view.d.ts.map +0 -1
  529. package/dist/hub-service/member-view.js.map +0 -1
  530. package/dist/hub-service/members.d.ts.map +0 -1
  531. package/dist/hub-service/members.js.map +0 -1
  532. package/dist/hub-service/presence.d.ts.map +0 -1
  533. package/dist/hub-service/presence.js.map +0 -1
  534. package/dist/hub-service/project-view.d.ts.map +0 -1
  535. package/dist/hub-service/project-view.js.map +0 -1
  536. package/dist/hub-service/projects.d.ts.map +0 -1
  537. package/dist/hub-service/projects.js.map +0 -1
  538. package/dist/hub-service/relay-queue.d.ts.map +0 -1
  539. package/dist/hub-service/relay-queue.js.map +0 -1
  540. package/dist/hub-service/session-jwt.d.ts.map +0 -1
  541. package/dist/hub-service/session-jwt.js.map +0 -1
  542. package/dist/hub-service/usage.d.ts.map +0 -1
  543. package/dist/hub-service/usage.js.map +0 -1
  544. package/dist/hub-service/users.d.ts.map +0 -1
  545. package/dist/hub-service/users.js.map +0 -1
  546. package/dist/hub-service/workspaces.d.ts.map +0 -1
  547. package/dist/hub-service/workspaces.js.map +0 -1
  548. package/dist/index.d.ts.map +0 -1
  549. package/dist/index.js.map +0 -1
  550. package/dist/onboarding/text.d.ts.map +0 -1
  551. package/dist/onboarding/text.js.map +0 -1
  552. package/dist/os/git-bash-candidates.d.ts.map +0 -1
  553. package/dist/os/git-bash-candidates.js.map +0 -1
  554. package/dist/os/index.d.ts.map +0 -1
  555. package/dist/os/index.js.map +0 -1
  556. package/dist/os/linux.d.ts.map +0 -1
  557. package/dist/os/linux.js.map +0 -1
  558. package/dist/os/macos.d.ts.map +0 -1
  559. package/dist/os/macos.js.map +0 -1
  560. package/dist/os/os-commands.d.ts.map +0 -1
  561. package/dist/os/os-commands.js.map +0 -1
  562. package/dist/os/windows-gitbash.d.ts.map +0 -1
  563. package/dist/os/windows-gitbash.js.map +0 -1
  564. package/dist/os/windows-wrapper.d.ts.map +0 -1
  565. package/dist/os/windows-wrapper.js.map +0 -1
  566. package/dist/os/windows.d.ts.map +0 -1
  567. package/dist/os/windows.js.map +0 -1
  568. package/dist/paths.d.ts.map +0 -1
  569. package/dist/paths.js.map +0 -1
  570. package/dist/providers/agy.d.ts.map +0 -1
  571. package/dist/providers/agy.js.map +0 -1
  572. package/dist/providers/claude.d.ts.map +0 -1
  573. package/dist/providers/claude.js.map +0 -1
  574. package/dist/providers/codex.d.ts.map +0 -1
  575. package/dist/providers/codex.js.map +0 -1
  576. package/dist/providers/copilot.d.ts.map +0 -1
  577. package/dist/providers/copilot.js.map +0 -1
  578. package/dist/providers/email/headers.d.ts.map +0 -1
  579. package/dist/providers/email/headers.js.map +0 -1
  580. package/dist/providers/email/index.d.ts.map +0 -1
  581. package/dist/providers/email/index.js.map +0 -1
  582. package/dist/providers/email/provider.d.ts.map +0 -1
  583. package/dist/providers/email/provider.js.map +0 -1
  584. package/dist/providers/email/sendgrid.d.ts.map +0 -1
  585. package/dist/providers/email/sendgrid.js.map +0 -1
  586. package/dist/providers/email/smtp.d.ts.map +0 -1
  587. package/dist/providers/email/smtp.js.map +0 -1
  588. package/dist/providers/index.d.ts.map +0 -1
  589. package/dist/providers/index.js.map +0 -1
  590. package/dist/providers/none.d.ts.map +0 -1
  591. package/dist/providers/none.js.map +0 -1
  592. package/dist/providers/opencode.d.ts.map +0 -1
  593. package/dist/providers/opencode.js.map +0 -1
  594. package/dist/providers/provider.d.ts.map +0 -1
  595. package/dist/providers/provider.js.map +0 -1
  596. package/dist/services/agent-provisioner.d.ts.map +0 -1
  597. package/dist/services/agent-provisioner.js.map +0 -1
  598. package/dist/services/agy-project.d.ts.map +0 -1
  599. package/dist/services/agy-project.js.map +0 -1
  600. package/dist/services/auth-socket.d.ts.map +0 -1
  601. package/dist/services/auth-socket.js.map +0 -1
  602. package/dist/services/auth-web.d.ts.map +0 -1
  603. package/dist/services/auth-web.js.map +0 -1
  604. package/dist/services/budget-awareness.d.ts.map +0 -1
  605. package/dist/services/budget-awareness.js.map +0 -1
  606. package/dist/services/cloud/activity.d.ts.map +0 -1
  607. package/dist/services/cloud/activity.js.map +0 -1
  608. package/dist/services/cloud/aws.d.ts.map +0 -1
  609. package/dist/services/cloud/aws.js.map +0 -1
  610. package/dist/services/cloud/cost.d.ts.map +0 -1
  611. package/dist/services/cloud/cost.js.map +0 -1
  612. package/dist/services/cloud/idle-manager.d.ts.map +0 -1
  613. package/dist/services/cloud/idle-manager.js.map +0 -1
  614. package/dist/services/cloud/lifecycle.d.ts.map +0 -1
  615. package/dist/services/cloud/lifecycle.js.map +0 -1
  616. package/dist/services/cloud/task-wrapper.d.ts.map +0 -1
  617. package/dist/services/cloud/task-wrapper.js.map +0 -1
  618. package/dist/services/cloud/types.d.ts.map +0 -1
  619. package/dist/services/cloud/types.js.map +0 -1
  620. package/dist/services/cloud-sync.d.ts.map +0 -1
  621. package/dist/services/cloud-sync.js.map +0 -1
  622. package/dist/services/context-admission.d.ts.map +0 -1
  623. package/dist/services/context-admission.js.map +0 -1
  624. package/dist/services/credential-cleanup.d.ts.map +0 -1
  625. package/dist/services/credential-cleanup.js.map +0 -1
  626. package/dist/services/credential-store.d.ts.map +0 -1
  627. package/dist/services/credential-store.js.map +0 -1
  628. package/dist/services/event-bus.d.ts.map +0 -1
  629. package/dist/services/event-bus.js.map +0 -1
  630. package/dist/services/exit-drain.d.ts.map +0 -1
  631. package/dist/services/exit-drain.js.map +0 -1
  632. package/dist/services/file-chunker.d.ts.map +0 -1
  633. package/dist/services/file-chunker.js.map +0 -1
  634. package/dist/services/file-transfer-relay.d.ts.map +0 -1
  635. package/dist/services/file-transfer-relay.js.map +0 -1
  636. package/dist/services/file-transfer.d.ts.map +0 -1
  637. package/dist/services/file-transfer.js.map +0 -1
  638. package/dist/services/git-config.d.ts.map +0 -1
  639. package/dist/services/git-config.js.map +0 -1
  640. package/dist/services/github-app.d.ts.map +0 -1
  641. package/dist/services/github-app.js.map +0 -1
  642. package/dist/services/http-transport.d.ts.map +0 -1
  643. package/dist/services/http-transport.js.map +0 -1
  644. package/dist/services/hub-client.d.ts.map +0 -1
  645. package/dist/services/hub-client.js.map +0 -1
  646. package/dist/services/icons.d.ts.map +0 -1
  647. package/dist/services/icons.js.map +0 -1
  648. package/dist/services/jwt.d.ts.map +0 -1
  649. package/dist/services/jwt.js.map +0 -1
  650. package/dist/services/knowledge/audn.d.ts.map +0 -1
  651. package/dist/services/knowledge/audn.js.map +0 -1
  652. package/dist/services/knowledge/file-hash.d.ts.map +0 -1
  653. package/dist/services/knowledge/file-hash.js.map +0 -1
  654. package/dist/services/knowledge/http-provider.d.ts.map +0 -1
  655. package/dist/services/knowledge/http-provider.js.map +0 -1
  656. package/dist/services/knowledge/kb-config.d.ts.map +0 -1
  657. package/dist/services/knowledge/kb-config.js.map +0 -1
  658. package/dist/services/knowledge/kb-providers.d.ts.map +0 -1
  659. package/dist/services/knowledge/kb-providers.js.map +0 -1
  660. package/dist/services/knowledge/kb-scope-input.d.ts +0 -5
  661. package/dist/services/knowledge/kb-scope-input.d.ts.map +0 -1
  662. package/dist/services/knowledge/kb-scope-input.js +0 -11
  663. package/dist/services/knowledge/kb-scope-input.js.map +0 -1
  664. package/dist/services/knowledge/kb-service.d.ts.map +0 -1
  665. package/dist/services/knowledge/kb-service.js.map +0 -1
  666. package/dist/services/knowledge/path-validation.d.ts.map +0 -1
  667. package/dist/services/knowledge/path-validation.js.map +0 -1
  668. package/dist/services/knowledge/pre-init.d.ts.map +0 -1
  669. package/dist/services/knowledge/pre-init.js.map +0 -1
  670. package/dist/services/knowledge/project-slug.d.ts.map +0 -1
  671. package/dist/services/knowledge/project-slug.js.map +0 -1
  672. package/dist/services/knowledge/require-sqlite-project.d.ts.map +0 -1
  673. package/dist/services/knowledge/require-sqlite-project.js.map +0 -1
  674. package/dist/services/knowledge/sqlite-provider.d.ts.map +0 -1
  675. package/dist/services/knowledge/sqlite-provider.js.map +0 -1
  676. package/dist/services/knowledge/types.d.ts.map +0 -1
  677. package/dist/services/knowledge/types.js.map +0 -1
  678. package/dist/services/known-hosts.d.ts.map +0 -1
  679. package/dist/services/known-hosts.js.map +0 -1
  680. package/dist/services/known-sessions.d.ts.map +0 -1
  681. package/dist/services/known-sessions.js.map +0 -1
  682. package/dist/services/member-home.d.ts.map +0 -1
  683. package/dist/services/member-home.js.map +0 -1
  684. package/dist/services/member-remote-url.d.ts.map +0 -1
  685. package/dist/services/member-remote-url.js.map +0 -1
  686. package/dist/services/model-pricing.d.ts.map +0 -1
  687. package/dist/services/model-pricing.js.map +0 -1
  688. package/dist/services/onboarding.d.ts.map +0 -1
  689. package/dist/services/onboarding.js.map +0 -1
  690. package/dist/services/orphan-recovery.d.ts.map +0 -1
  691. package/dist/services/orphan-recovery.js.map +0 -1
  692. package/dist/services/pending-responses.d.ts.map +0 -1
  693. package/dist/services/pending-responses.js.map +0 -1
  694. package/dist/services/preflight-check.d.ts.map +0 -1
  695. package/dist/services/preflight-check.js.map +0 -1
  696. package/dist/services/registry.d.ts.map +0 -1
  697. package/dist/services/registry.js.map +0 -1
  698. package/dist/services/relay-context.d.ts.map +0 -1
  699. package/dist/services/relay-context.js.map +0 -1
  700. package/dist/services/relay-executor.d.ts.map +0 -1
  701. package/dist/services/relay-executor.js.map +0 -1
  702. package/dist/services/relay-request.d.ts.map +0 -1
  703. package/dist/services/relay-request.js.map +0 -1
  704. package/dist/services/relay-strategy.d.ts.map +0 -1
  705. package/dist/services/relay-strategy.js.map +0 -1
  706. package/dist/services/secret-token.d.ts.map +0 -1
  707. package/dist/services/secret-token.js.map +0 -1
  708. package/dist/services/service-manager/index.d.ts.map +0 -1
  709. package/dist/services/service-manager/index.js.map +0 -1
  710. package/dist/services/service-manager/linux.d.ts.map +0 -1
  711. package/dist/services/service-manager/linux.js.map +0 -1
  712. package/dist/services/service-manager/macos.d.ts.map +0 -1
  713. package/dist/services/service-manager/macos.js.map +0 -1
  714. package/dist/services/service-manager/types.d.ts.map +0 -1
  715. package/dist/services/service-manager/types.js.map +0 -1
  716. package/dist/services/service-manager/windows.d.ts.map +0 -1
  717. package/dist/services/service-manager/windows.js.map +0 -1
  718. package/dist/services/session-registry.d.ts.map +0 -1
  719. package/dist/services/session-registry.js.map +0 -1
  720. package/dist/services/sftp.d.ts.map +0 -1
  721. package/dist/services/sftp.js.map +0 -1
  722. package/dist/services/shell-probe.d.ts.map +0 -1
  723. package/dist/services/shell-probe.js.map +0 -1
  724. package/dist/services/singleton.d.ts.map +0 -1
  725. package/dist/services/singleton.js.map +0 -1
  726. package/dist/services/sprint-coordination.d.ts.map +0 -1
  727. package/dist/services/sprint-coordination.js.map +0 -1
  728. package/dist/services/ssh.d.ts.map +0 -1
  729. package/dist/services/ssh.js.map +0 -1
  730. package/dist/services/stall/find-log-file.d.ts.map +0 -1
  731. package/dist/services/stall/find-log-file.js.map +0 -1
  732. package/dist/services/stall/index.d.ts.map +0 -1
  733. package/dist/services/stall/index.js.map +0 -1
  734. package/dist/services/stall/log-path-resolver.d.ts.map +0 -1
  735. package/dist/services/stall/log-path-resolver.js.map +0 -1
  736. package/dist/services/stall/read-log-tail.d.ts.map +0 -1
  737. package/dist/services/stall/read-log-tail.js.map +0 -1
  738. package/dist/services/stall/stall-detector.d.ts.map +0 -1
  739. package/dist/services/stall/stall-detector.js.map +0 -1
  740. package/dist/services/stall/stall-poller.d.ts.map +0 -1
  741. package/dist/services/stall/stall-poller.js.map +0 -1
  742. package/dist/services/stall/time-utils.d.ts.map +0 -1
  743. package/dist/services/stall/time-utils.js.map +0 -1
  744. package/dist/services/statusline.d.ts.map +0 -1
  745. package/dist/services/statusline.js.map +0 -1
  746. package/dist/services/strategy.d.ts.map +0 -1
  747. package/dist/services/strategy.js.map +0 -1
  748. package/dist/services/substitution-engine.d.ts.map +0 -1
  749. package/dist/services/substitution-engine.js.map +0 -1
  750. package/dist/services/task-cleanup.d.ts.map +0 -1
  751. package/dist/services/task-cleanup.js.map +0 -1
  752. package/dist/services/token-issuer.d.ts.map +0 -1
  753. package/dist/services/token-issuer.js.map +0 -1
  754. package/dist/services/tool-registry.d.ts.map +0 -1
  755. package/dist/services/tool-registry.js.map +0 -1
  756. package/dist/services/update-check.d.ts.map +0 -1
  757. package/dist/services/update-check.js.map +0 -1
  758. package/dist/services/user-config.d.ts.map +0 -1
  759. package/dist/services/user-config.js.map +0 -1
  760. package/dist/services/vcs/azure-devops.d.ts.map +0 -1
  761. package/dist/services/vcs/azure-devops.js.map +0 -1
  762. package/dist/services/vcs/bitbucket.d.ts.map +0 -1
  763. package/dist/services/vcs/bitbucket.js.map +0 -1
  764. package/dist/services/vcs/constants.d.ts.map +0 -1
  765. package/dist/services/vcs/constants.js.map +0 -1
  766. package/dist/services/vcs/github.d.ts.map +0 -1
  767. package/dist/services/vcs/github.js.map +0 -1
  768. package/dist/services/vcs/types.d.ts.map +0 -1
  769. package/dist/services/vcs/types.js.map +0 -1
  770. package/dist/services/version-check.d.ts.map +0 -1
  771. package/dist/services/version-check.js.map +0 -1
  772. package/dist/services/watch/fleet-log.d.ts.map +0 -1
  773. package/dist/services/watch/fleet-log.js.map +0 -1
  774. package/dist/services/watch/project-resolver.d.ts.map +0 -1
  775. package/dist/services/watch/project-resolver.js.map +0 -1
  776. package/dist/services/watch/transcript-formatter.d.ts.map +0 -1
  777. package/dist/services/watch/transcript-formatter.js.map +0 -1
  778. package/dist/smoke-test.d.ts.map +0 -1
  779. package/dist/smoke-test.js.map +0 -1
  780. package/dist/tools/check-status.d.ts.map +0 -1
  781. package/dist/tools/check-status.js.map +0 -1
  782. package/dist/tools/child-id-allocator.d.ts.map +0 -1
  783. package/dist/tools/child-id-allocator.js.map +0 -1
  784. package/dist/tools/cloud-control.d.ts.map +0 -1
  785. package/dist/tools/cloud-control.js.map +0 -1
  786. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +0 -1
  787. package/dist/tools/code-intelligence-codebase-memory.js.map +0 -1
  788. package/dist/tools/code-intelligence-freshness.d.ts.map +0 -1
  789. package/dist/tools/code-intelligence-freshness.js.map +0 -1
  790. package/dist/tools/code-intelligence-gitnexus.d.ts.map +0 -1
  791. package/dist/tools/code-intelligence-gitnexus.js.map +0 -1
  792. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +0 -1
  793. package/dist/tools/code-intelligence-kb-enrich.js.map +0 -1
  794. package/dist/tools/code-intelligence-reindex.d.ts.map +0 -1
  795. package/dist/tools/code-intelligence-reindex.js.map +0 -1
  796. package/dist/tools/code-intelligence-telemetry.d.ts.map +0 -1
  797. package/dist/tools/code-intelligence-telemetry.js.map +0 -1
  798. package/dist/tools/code-intelligence-tests.d.ts.map +0 -1
  799. package/dist/tools/code-intelligence-tests.js.map +0 -1
  800. package/dist/tools/code-intelligence.d.ts.map +0 -1
  801. package/dist/tools/code-intelligence.js.map +0 -1
  802. package/dist/tools/compose-permissions.d.ts.map +0 -1
  803. package/dist/tools/compose-permissions.js.map +0 -1
  804. package/dist/tools/credential-store-delete.d.ts.map +0 -1
  805. package/dist/tools/credential-store-delete.js.map +0 -1
  806. package/dist/tools/credential-store-list.d.ts.map +0 -1
  807. package/dist/tools/credential-store-list.js.map +0 -1
  808. package/dist/tools/credential-store-set.d.ts.map +0 -1
  809. package/dist/tools/credential-store-set.js.map +0 -1
  810. package/dist/tools/credential-store-update.d.ts.map +0 -1
  811. package/dist/tools/credential-store-update.js.map +0 -1
  812. package/dist/tools/dolt-push-mutex.d.ts.map +0 -1
  813. package/dist/tools/dolt-push-mutex.js.map +0 -1
  814. package/dist/tools/execute-command.d.ts.map +0 -1
  815. package/dist/tools/execute-command.js.map +0 -1
  816. package/dist/tools/execute-prompt.d.ts.map +0 -1
  817. package/dist/tools/execute-prompt.js.map +0 -1
  818. package/dist/tools/get-member-model-pricing.d.ts.map +0 -1
  819. package/dist/tools/get-member-model-pricing.js.map +0 -1
  820. package/dist/tools/kb-capture.d.ts.map +0 -1
  821. package/dist/tools/kb-capture.js.map +0 -1
  822. package/dist/tools/kb-context.d.ts.map +0 -1
  823. package/dist/tools/kb-context.js.map +0 -1
  824. package/dist/tools/kb-export.d.ts.map +0 -1
  825. package/dist/tools/kb-export.js.map +0 -1
  826. package/dist/tools/kb-feedback.d.ts.map +0 -1
  827. package/dist/tools/kb-feedback.js.map +0 -1
  828. package/dist/tools/kb-freshness-sweep.d.ts.map +0 -1
  829. package/dist/tools/kb-freshness-sweep.js.map +0 -1
  830. package/dist/tools/kb-harvest.d.ts.map +0 -1
  831. package/dist/tools/kb-harvest.js.map +0 -1
  832. package/dist/tools/kb-import.d.ts.map +0 -1
  833. package/dist/tools/kb-import.js.map +0 -1
  834. package/dist/tools/kb-invalidate.d.ts.map +0 -1
  835. package/dist/tools/kb-invalidate.js.map +0 -1
  836. package/dist/tools/kb-list.d.ts.map +0 -1
  837. package/dist/tools/kb-list.js.map +0 -1
  838. package/dist/tools/kb-promote.d.ts.map +0 -1
  839. package/dist/tools/kb-promote.js.map +0 -1
  840. package/dist/tools/kb-query.d.ts.map +0 -1
  841. package/dist/tools/kb-query.js.map +0 -1
  842. package/dist/tools/kb-reconcile-prefilter.d.ts.map +0 -1
  843. package/dist/tools/kb-reconcile-prefilter.js.map +0 -1
  844. package/dist/tools/kb-resolve-contradiction.d.ts.map +0 -1
  845. package/dist/tools/kb-resolve-contradiction.js.map +0 -1
  846. package/dist/tools/kb-session-prime.d.ts.map +0 -1
  847. package/dist/tools/kb-session-prime.js.map +0 -1
  848. package/dist/tools/kb-setup.d.ts.map +0 -1
  849. package/dist/tools/kb-setup.js.map +0 -1
  850. package/dist/tools/kb-stats.d.ts.map +0 -1
  851. package/dist/tools/kb-stats.js.map +0 -1
  852. package/dist/tools/list-members.d.ts.map +0 -1
  853. package/dist/tools/list-members.js.map +0 -1
  854. package/dist/tools/member-detail.d.ts.map +0 -1
  855. package/dist/tools/member-detail.js.map +0 -1
  856. package/dist/tools/member-reservation.d.ts.map +0 -1
  857. package/dist/tools/member-reservation.js.map +0 -1
  858. package/dist/tools/monitor-task.d.ts.map +0 -1
  859. package/dist/tools/monitor-task.js.map +0 -1
  860. package/dist/tools/provision-auth.d.ts.map +0 -1
  861. package/dist/tools/provision-auth.js.map +0 -1
  862. package/dist/tools/provision-vcs-auth.d.ts.map +0 -1
  863. package/dist/tools/provision-vcs-auth.js.map +0 -1
  864. package/dist/tools/receive-files.d.ts.map +0 -1
  865. package/dist/tools/receive-files.js.map +0 -1
  866. package/dist/tools/register-member.d.ts.map +0 -1
  867. package/dist/tools/register-member.js.map +0 -1
  868. package/dist/tools/remove-member.d.ts.map +0 -1
  869. package/dist/tools/remove-member.js.map +0 -1
  870. package/dist/tools/report-status.d.ts.map +0 -1
  871. package/dist/tools/report-status.js.map +0 -1
  872. package/dist/tools/respond-to-message.d.ts.map +0 -1
  873. package/dist/tools/respond-to-message.js.map +0 -1
  874. package/dist/tools/revoke-vcs-auth.d.ts.map +0 -1
  875. package/dist/tools/revoke-vcs-auth.js.map +0 -1
  876. package/dist/tools/send-email.d.ts.map +0 -1
  877. package/dist/tools/send-email.js.map +0 -1
  878. package/dist/tools/send-files.d.ts.map +0 -1
  879. package/dist/tools/send-files.js.map +0 -1
  880. package/dist/tools/send-message.d.ts.map +0 -1
  881. package/dist/tools/send-message.js.map +0 -1
  882. package/dist/tools/setup-git-app.d.ts.map +0 -1
  883. package/dist/tools/setup-git-app.js.map +0 -1
  884. package/dist/tools/setup-ssh-key.d.ts.map +0 -1
  885. package/dist/tools/setup-ssh-key.js.map +0 -1
  886. package/dist/tools/shutdown-server.d.ts.map +0 -1
  887. package/dist/tools/shutdown-server.js.map +0 -1
  888. package/dist/tools/stop-prompt.d.ts.map +0 -1
  889. package/dist/tools/stop-prompt.js.map +0 -1
  890. package/dist/tools/update-agent-cli.d.ts.map +0 -1
  891. package/dist/tools/update-agent-cli.js.map +0 -1
  892. package/dist/tools/update-member.d.ts.map +0 -1
  893. package/dist/tools/update-member.js.map +0 -1
  894. package/dist/tools/vcs-credential-exec.d.ts.map +0 -1
  895. package/dist/tools/vcs-credential-exec.js.map +0 -1
  896. package/dist/tools/version.d.ts.map +0 -1
  897. package/dist/tools/version.js.map +0 -1
  898. package/dist/types.d.ts.map +0 -1
  899. package/dist/types.js.map +0 -1
  900. package/dist/utils/agent-helpers.d.ts.map +0 -1
  901. package/dist/utils/agent-helpers.js.map +0 -1
  902. package/dist/utils/ansi.d.ts.map +0 -1
  903. package/dist/utils/ansi.js.map +0 -1
  904. package/dist/utils/auth-env.d.ts.map +0 -1
  905. package/dist/utils/auth-env.js.map +0 -1
  906. package/dist/utils/collect-secret.d.ts.map +0 -1
  907. package/dist/utils/collect-secret.js.map +0 -1
  908. package/dist/utils/credential-validation.d.ts.map +0 -1
  909. package/dist/utils/credential-validation.js.map +0 -1
  910. package/dist/utils/crypto.d.ts.map +0 -1
  911. package/dist/utils/crypto.js.map +0 -1
  912. package/dist/utils/deep-merge.d.ts.map +0 -1
  913. package/dist/utils/deep-merge.js.map +0 -1
  914. package/dist/utils/file-permissions.d.ts.map +0 -1
  915. package/dist/utils/file-permissions.js.map +0 -1
  916. package/dist/utils/gpu-parser.d.ts.map +0 -1
  917. package/dist/utils/gpu-parser.js.map +0 -1
  918. package/dist/utils/log-helpers.d.ts.map +0 -1
  919. package/dist/utils/log-helpers.js.map +0 -1
  920. package/dist/utils/oob-timeout.d.ts.map +0 -1
  921. package/dist/utils/oob-timeout.js.map +0 -1
  922. package/dist/utils/opencode-model-validation.d.ts.map +0 -1
  923. package/dist/utils/opencode-model-validation.js.map +0 -1
  924. package/dist/utils/pid-helpers.d.ts.map +0 -1
  925. package/dist/utils/pid-helpers.js.map +0 -1
  926. package/dist/utils/platform.d.ts.map +0 -1
  927. package/dist/utils/platform.js.map +0 -1
  928. package/dist/utils/process-utils.d.ts.map +0 -1
  929. package/dist/utils/process-utils.js.map +0 -1
  930. package/dist/utils/prompt-errors.d.ts.map +0 -1
  931. package/dist/utils/prompt-errors.js.map +0 -1
  932. package/dist/utils/resolve-member.d.ts.map +0 -1
  933. package/dist/utils/resolve-member.js.map +0 -1
  934. package/dist/utils/secure-input.d.ts.map +0 -1
  935. package/dist/utils/secure-input.js.map +0 -1
  936. package/dist/utils/session-caller.d.ts.map +0 -1
  937. package/dist/utils/session-caller.js.map +0 -1
  938. package/dist/utils/shell-escape.d.ts.map +0 -1
  939. package/dist/utils/shell-escape.js.map +0 -1
  940. package/dist/utils/skill-matrix.d.ts.map +0 -1
  941. package/dist/utils/skill-matrix.js.map +0 -1
  942. package/dist/utils/ssh-error-messages.d.ts.map +0 -1
  943. package/dist/utils/ssh-error-messages.js.map +0 -1
  944. package/dist/utils/vcs-provider-detect.d.ts.map +0 -1
  945. package/dist/utils/vcs-provider-detect.js.map +0 -1
  946. package/dist/utils/work-folder-validation.d.ts.map +0 -1
  947. package/dist/utils/work-folder-validation.js.map +0 -1
  948. package/dist/utils/workspace-trust.d.ts.map +0 -1
  949. package/dist/utils/workspace-trust.js.map +0 -1
  950. package/dist/version.d.ts.map +0 -1
  951. package/dist/version.js.map +0 -1
@@ -0,0 +1,919 @@
1
+ // =============================================================================
2
+ // fleet-sprint supervisor -- operator HTTP endpoints (apra-fleet-eft.4.4)
3
+ // members / backlog / sprints CRUD / stop proxy
4
+ // =============================================================================
5
+ //
6
+ // The six operator-facing endpoints the always-on supervisor (server.mjs)
7
+ // exposes on top of its lifecycle-owned /api/health and /api/shutdown:
8
+ //
9
+ // GET /api/members list_members plus a live-reservation overlay
10
+ // GET /api/backlog the fleet backlog
11
+ // POST /api/sprints validated launch; forwards the per-request goal
12
+ // into the detached child's argv (eft.4.2 spawner)
13
+ // GET /api/sprints every live sprint (from the reservation ledger)
14
+ // GET /api/sprints/:id LIVE child state proxied from the child's /state
15
+ // when running, else the historical record
16
+ // POST /api/sprints/:id/stop proxy the child's own cooperative /stop endpoint
17
+ //
18
+ // SINGLE SOURCE OF TRUTH FOR VALIDATION (acceptance criterion): request
19
+ // validation REUSES the exported runner.js helpers validateIssueId /
20
+ // validateBranchName and the cli.mjs resolveRoleMap helper -- it never
21
+ // re-implements the id/branch regexes here. A malformed issue id or branch name
22
+ // is rejected with a 400 that names the offending field, before any child is
23
+ // spawned. apra-fleet-ymf.1: `issue` accepts the SAME comma-separated
24
+ // multi-root form as the CLI's `--issue` flag (splitIssueIds() mirrors
25
+ // bin/cli.mjs:468's split/trim/filter exactly) -- each id is validated
26
+ // individually and forwarded as `issueRoots` (a string[], one root per
27
+ // entry), never as one opaque joined string.
28
+ //
29
+ // COLLABORATOR SEAMS: every side-effecting collaborator (spawner, ledger,
30
+ // history, member/backlog sources, and the child HTTP proxies) is injected, so
31
+ // this module is unit-testable without real processes, sockets, or a live
32
+ // fleet transport. eft.5.2's all-or-nothing member-union overlap check (409 on
33
+ // conflict, see defaultMemberOverlapGuard() below) is the DEFAULT `beforeLaunch`
34
+ // -- it runs unless a caller injects its own, e.g. to compose it with the
35
+ // eft.5.3 issue-scope guard. The check runs strictly BEFORE ledger.claim(), so
36
+ // a rejected launch never touches the ledger (byte-identical, no partial claim).
37
+ // =============================================================================
38
+
39
+ import http from 'node:http';
40
+ import { createHash, randomUUID } from 'node:crypto';
41
+ import { statSync } from 'node:fs';
42
+ import { fileURLToPath } from 'node:url';
43
+
44
+ import { readJsonBody, sendJson } from './server.mjs';
45
+ import { validateIssueId, validateBranchName, validateBranchPair } from '../../fleet-sprint/runner.js';
46
+ import { resolveRoleMap } from '../../bin/cli.mjs';
47
+ import { resolveBacklogRoleAlias, ROLE_BACKLOG } from '../../fleet-sprint/backlog-role.mjs';
48
+ import { normalizeRole } from '../../fleet-sprint/contracts.mjs';
49
+ import { isDeterministicTerminalReason } from './history.mjs';
50
+ import { defaultHasTerminalState } from './watchdog.mjs';
51
+ import { toBeadsSummary } from './beads-identity.mjs';
52
+ import { fleetMembersUnavailableReason, fleetMembersStoppedByUserReason } from './fleet-members.mjs';
53
+
54
+ /** This module's own on-disk path -- the default build-version stamp's source (see defaultBuildVersion() below). */
55
+ const API_MODULE_PATH = fileURLToPath(import.meta.url);
56
+
57
+ /** A controller error carrying an HTTP status and (optionally) the bad field. */
58
+ /** Hard cap on a generated sprint id's length (it is also the --run-id, ledger key and log file stem). */
59
+ export const MAX_SPRINT_ID_LENGTH = 48;
60
+ const SPRINT_ID_ROOT_LENGTH = 20;
61
+
62
+ /**
63
+ * Bounded, launch-unique sprint id: `<first-root>-<count>-<hash>-<uuid8>`.
64
+ * The full issue list is NOT encoded in the id (it lives in the sprint
65
+ * record's issueRoots and the child argv), so the id -- and the log file name
66
+ * derived from it -- stays the same length for 1 or 100 roots. Uniqueness
67
+ * per launch comes from the uuid fragment.
68
+ * @param {string} issue - comma-joined issue roots
69
+ * @returns {string}
70
+ */
71
+ export function defaultGenerateSprintId(issue) {
72
+ const roots = String(issue ?? '').split(',').map((r) => r.trim()).filter(Boolean);
73
+ const first = (roots[0] ?? 'sprint').replace(/[^A-Za-z0-9._-]/g, '_').slice(0, SPRINT_ID_ROOT_LENGTH);
74
+ const hash = createHash('sha256').update(roots.join(',')).digest('hex').slice(0, 6);
75
+ return `${first}-${roots.length}-${hash}-${randomUUID().slice(0, 8)}`;
76
+ }
77
+
78
+ export class ApiError extends Error {
79
+ /**
80
+ * @param {number} status
81
+ * @param {string} message
82
+ * @param {string} [field]
83
+ */
84
+ constructor(status, message, field) {
85
+ super(message);
86
+ this.name = 'ApiError';
87
+ this.status = status;
88
+ if (field) this.field = field;
89
+ }
90
+ }
91
+
92
+ /**
93
+ * apra-fleet-ymf.1: split a request's `issue` field into individual ids,
94
+ * mirroring bin/cli.mjs:468's `values.issue.split(',').map(s =>
95
+ * s.trim()).filter(Boolean)` exactly -- so a comma-separated multi-root
96
+ * request (`{"issue": "epic-1,epic-2"}`) reaches the same targetIssues shape
97
+ * the CLI path already feeds runner.js, instead of 400ing on the whole
98
+ * opaque string. A non-string `value` (including `undefined`) returns `[]`
99
+ * so the caller falls through to `validateIssueId(value)` for byte-identical
100
+ * error text on the missing/malformed cases this never used to split.
101
+ * @param {*} value
102
+ * @returns {string[]}
103
+ */
104
+ function splitIssueIds(value) {
105
+ if (typeof value !== 'string') return [];
106
+ return value.split(',').map((s) => s.trim()).filter(Boolean);
107
+ }
108
+
109
+ /** Normalize a `members` request value (array OR comma string) into a deduped array. */
110
+ function normalizeMembers(value) {
111
+ let items;
112
+ if (Array.isArray(value)) items = value;
113
+ else if (typeof value === 'string') items = value.split(',');
114
+ else return [];
115
+ const out = [];
116
+ const seen = new Set();
117
+ for (const raw of items) {
118
+ if (typeof raw !== 'string') continue;
119
+ const m = raw.trim();
120
+ if (m.length === 0 || seen.has(m)) continue;
121
+ seen.add(m);
122
+ out.push(m);
123
+ }
124
+ return out;
125
+ }
126
+
127
+ /**
128
+ * The full member set a reservation covers: the union of --members and every
129
+ * roleMap value. `exclude` (unreservable member names -- see
130
+ * unreservableMemberNamesFromList() below) is subtracted from the union: a shared
131
+ * backlog member is never part of a sprint's exclusive reservation, so it
132
+ * never reaches `beforeLaunch` or `ledger.claim`.
133
+ */
134
+ function memberUnion(members, roleMap, exclude) {
135
+ const seen = new Set();
136
+ const out = [];
137
+ const add = (m) => {
138
+ if (typeof m === 'string' && m.length > 0 && !seen.has(m) && !(exclude && exclude.has(m))) {
139
+ seen.add(m);
140
+ out.push(m);
141
+ }
142
+ };
143
+ for (const m of members) add(m);
144
+ if (roleMap && typeof roleMap === 'object') {
145
+ for (const list of Object.values(roleMap)) {
146
+ if (Array.isArray(list)) for (const m of list) add(m);
147
+ }
148
+ }
149
+ return out;
150
+ }
151
+
152
+ /**
153
+ * Pure extractor: the set of member names flagged `unreservable: true` in an
154
+ * ALREADY-FETCHED `listMembers()`-shaped result (raw array or `{members}`).
155
+ * No I/O, so callers that already hold a fetched list (e.g. `launch()` below,
156
+ * which needs exactly one listMembers() read shared with the overlap guard)
157
+ * never trigger a second fetch just to compute this.
158
+ * @param {object|object[]} raw
159
+ * @returns {Set<string>}
160
+ */
161
+ function unreservableMemberNamesFromList(raw) {
162
+ const list = Array.isArray(raw) ? raw : (raw && Array.isArray(raw.members) ? raw.members : []);
163
+ const out = new Set();
164
+ for (const m of list) {
165
+ if (m && typeof m === 'object' && m.name && m.unreservable) out.add(m.name);
166
+ }
167
+ return out;
168
+ }
169
+
170
+
171
+ /**
172
+ * Human-readable rejection message naming every conflicting sprint and the
173
+ * overlapping member names, for surfacing to the launch caller / API response.
174
+ * @param {Array<{ sprintId: string, members: string[] }>} conflicts
175
+ * @returns {string}
176
+ */
177
+ export function formatMemberConflict(conflicts) {
178
+ const parts = conflicts.map(
179
+ (c) => `sprint '${c.sprintId}' already claims [${c.members.join(', ')}]`,
180
+ );
181
+ return `member overlap rejects launch: ${parts.join('; ')}`;
182
+ }
183
+
184
+ /**
185
+ * apra-fleet-eft.5.2 (extended by eft.26.2, Hole 2): the DEFAULT member-axis
186
+ * overlap guard used as `beforeLaunch` when the caller does not inject its
187
+ * own. All-or-nothing: ANY member in the incoming union (members + every
188
+ * roleMap value, INCLUDING the backlog role UNLESS that member is
189
+ * flagged `unreservable` -- memberUnion() already folds roleMap values in and
190
+ * subtracts unreservable names) that is also held by any OTHER active
191
+ * reservation rejects
192
+ * the ENTIRE launch with a 409, naming the conflicting sprint id(s) and the
193
+ * specific overlapping member names. This throws BEFORE ledger.claim() is
194
+ * ever called, so a rejected launch leaves the ledger byte-identical -- no
195
+ * partial claim.
196
+ *
197
+ * Two reservation sources are consulted, merged into ONE conflict set:
198
+ * 1. This supervisor's OWN ledger (`ledger.list()`) -- reservations made by
199
+ * launches routed through THIS supervisor's POST /api/sprints.
200
+ * 2. (eft.26.2) The fleet server's OWN per-member `reservedBy` record, read
201
+ * via the injected `listMembers` (the same collaborator GET /api/members
202
+ * already uses) -- reservations made by ANY OTHER means, e.g. a
203
+ * workflow/cli-launched sprint that reserved directly via
204
+ * `member_reservation` (apra-fleet-eft.26.1) and was never routed
205
+ * through this ledger at all. Without this second source, a launch could
206
+ * land a member ALREADY reserved server-side and the two sprints would
207
+ * interleave dispatches on it.
208
+ *
209
+ * `listMembers` is optional (backward compatible: omitting it checks only the
210
+ * local ledger, exactly as before eft.26.2).
211
+ *
212
+ * apra-fleet: the caller MAY pass `ctx.membersList` -- an already-fetched
213
+ * `listMembers()` result -- to skip this guard's own fetch entirely. `launch()`
214
+ * already needs one `listMembers()` read to compute the unreservable-exclude
215
+ * set for `memberUnion()`; without this, that same read was repeated here,
216
+ * opening a second short-lived MCP transport for what is logically one
217
+ * request-scoped read.
218
+ *
219
+ * @param {{ list: () => Array<{ sprintId: string, members?: string[] }> }} ledger
220
+ * @param {() => Promise<object|object[]>|object|object[]} [listMembers]
221
+ * @returns {(ctx: { members: string[], issueRoots: string[], membersList?: object|object[] }) => Promise<void>}
222
+ */
223
+ export function defaultMemberOverlapGuard(ledger, listMembers) {
224
+ return async ({ members: requestMembers, membersList }) => {
225
+ const requestSet = new Set(requestMembers ?? []);
226
+ // sprintId -> Set<member>, merged across both sources so a member
227
+ // conflicting via both the local ledger AND the server record is
228
+ // named once, not twice.
229
+ const conflictsBySprint = new Map();
230
+ const addConflict = (sprintId, member) => {
231
+ if (!sprintId) return;
232
+ if (!conflictsBySprint.has(sprintId)) conflictsBySprint.set(sprintId, new Set());
233
+ conflictsBySprint.get(sprintId).add(member);
234
+ };
235
+
236
+ for (const reservation of ledger.list()) {
237
+ for (const m of (reservation.members ?? [])) {
238
+ if (requestSet.has(m)) addConflict(reservation.sprintId, m);
239
+ }
240
+ }
241
+
242
+ // eft.26.2: also consult the fleet server's own reservedBy record so
243
+ // a server-side reservation made by other means (not this ledger) is
244
+ // still caught. Best-effort: a failure to reach listMembers must not
245
+ // block the local-ledger check above from still protecting the launch.
246
+ if (membersList !== undefined || typeof listMembers === 'function') {
247
+ try {
248
+ const raw = membersList !== undefined ? membersList : await listMembers();
249
+ const list = Array.isArray(raw) ? raw : (raw && Array.isArray(raw.members) ? raw.members : []);
250
+ for (const m of list) {
251
+ if (!m || typeof m !== 'object') continue;
252
+ if (m.unreservable) continue;
253
+ if (m.name && m.reservedBy && requestSet.has(m.name)) {
254
+ addConflict(m.reservedBy, m.name);
255
+ }
256
+ }
257
+ } catch {
258
+ // Non-fatal: fall through with whatever the local ledger
259
+ // already found. The server-side check is defense in depth on
260
+ // top of the ledger, not a replacement for it.
261
+ }
262
+ }
263
+
264
+ if (conflictsBySprint.size > 0) {
265
+ const conflicts = [...conflictsBySprint.entries()]
266
+ .map(([sprintId, members]) => ({ sprintId, members: [...members].sort() }))
267
+ .sort((a, b) => a.sprintId.localeCompare(b.sprintId));
268
+ throw new ApiError(409, formatMemberConflict(conflicts), 'members');
269
+ }
270
+ };
271
+ }
272
+
273
+ /** Default child HTTP proxy: GET the child's viewer `/state` and JSON-parse it. */
274
+ export function proxyChildState(port, opts = {}) {
275
+ const host = opts.host ?? '127.0.0.1';
276
+ const timeoutMs = Number.isInteger(opts.timeoutMs) ? opts.timeoutMs : 2000;
277
+ return new Promise((resolve, reject) => {
278
+ const req = http.request({ host, port, path: '/state', method: 'GET', timeout: timeoutMs }, (res) => {
279
+ const chunks = [];
280
+ res.on('data', (c) => chunks.push(c));
281
+ res.on('end', () => {
282
+ const body = Buffer.concat(chunks).toString('utf-8');
283
+ try { resolve(body.length ? JSON.parse(body) : {}); }
284
+ catch (err) { reject(new Error(`child /state returned invalid JSON: ${err.message}`)); }
285
+ });
286
+ });
287
+ req.on('timeout', () => { req.destroy(new Error('child /state timed out')); });
288
+ req.on('error', reject);
289
+ req.end();
290
+ });
291
+ }
292
+
293
+ /** Default child HTTP proxy: POST the child's cooperative `/stop` endpoint. */
294
+ export function proxyChildStop(port, opts = {}) {
295
+ const host = opts.host ?? '127.0.0.1';
296
+ const timeoutMs = Number.isInteger(opts.timeoutMs) ? opts.timeoutMs : 2000;
297
+ return new Promise((resolve, reject) => {
298
+ const req = http.request({ host, port, path: '/stop', method: 'POST', timeout: timeoutMs }, (res) => {
299
+ res.resume();
300
+ res.on('end', () => resolve({ statusCode: res.statusCode }));
301
+ });
302
+ req.on('timeout', () => { req.destroy(new Error('child /stop timed out')); });
303
+ req.on('error', reject);
304
+ req.end();
305
+ });
306
+ }
307
+
308
+ /**
309
+ * apra-fleet-gey.2: default build-version stamp -- this module's own on-disk
310
+ * mtime. This package runs directly from source (no separate compiled
311
+ * artifact, no reliable package.json version bump per fix), and api.mjs IS
312
+ * where the launch/relaunch logic this gate protects lives, so its mtime is
313
+ * a fast, dependency-free proxy for "has the code changed since this process
314
+ * started". Deliberately fs.statSync(), NOT a subprocess (e.g. `git
315
+ * rev-parse HEAD`) -- this runs on every controller creation AND every
316
+ * launch(), and a spawned subprocess there measurably added contention under
317
+ * concurrent test/supervisor boots. Called ONCE at controller creation
318
+ * (captures what this RUNNING process was started from) and again on every
319
+ * launch() (reads what's on disk RIGHT NOW) -- see createSprintController()'s
320
+ * `stampedBuildVersion` below. Returns `null` (never throws) when the file is
321
+ * unreadable, so a stamp failure only skips the stale-build warning, it never
322
+ * blocks a launch.
323
+ * @returns {string|null}
324
+ */
325
+ export function defaultBuildVersion() {
326
+ try {
327
+ return `${statSync(API_MODULE_PATH).mtimeMs}`;
328
+ } catch {
329
+ return null;
330
+ }
331
+ }
332
+
333
+ /**
334
+ * Create the supervisor sprint/member/backlog controller. All collaborators are
335
+ * injected.
336
+ *
337
+ * @param {{
338
+ * ledger: {
339
+ * list: () => Array<object>,
340
+ * get: (id: string) => object|undefined,
341
+ * claim: (id: string, r: object) => Promise<object>,
342
+ * },
343
+ * spawner: {
344
+ * spawnSprint: (opts: object) => Promise<{ pid: number, port: number, args?: string[], logPath?: string }>,
345
+ * getLiveEntry?: (pid: number) => { port: number, logPath?: string }|undefined,
346
+ * },
347
+ * history?: {
348
+ * latestFor: (id: string) => object|undefined,
349
+ * forSprint: (id: string) => object[],
350
+ * latestForIssueRoot?: (issue: string) => object|undefined,
351
+ * },
352
+ * listMembers: () => Promise<object|object[]>|object|object[],
353
+ * getBacklog: () => Promise<any>|any,
354
+ * proxyState?: (port: number) => Promise<object>,
355
+ * proxyStop?: (port: number) => Promise<object>,
356
+ * resolvePort?: (pid: number|null) => number|undefined,
357
+ * hasTerminalState?: (sprintId: string, branch: string|null) => object|null,
358
+ * apra-fleet-2l4.1: defaults to watchdog.mjs's defaultHasTerminalState()
359
+ * (a pure on-disk read of the engine's own persisted old_runs/<runId>.json
360
+ * terminal record). getSprint()/stopSprint() consult this BEFORE
361
+ * resolvePort()/proxyState()/proxyStop() -- a persisted terminal state can
362
+ * exist while the child's OS process is still alive in its post-terminal
363
+ * dashboard-linger window (its embedded HTTP viewer server closes before
364
+ * the process itself exits), a window PID-liveness-based resolvePort()
365
+ * cannot see on its own and would otherwise proxy into a closed port
366
+ * (ECONNREFUSED surfacing as a raw 500). Inject to stub without real fs
367
+ * reads in tests.
368
+ * beforeLaunch?: (ctx: { members: string[], issueRoots: string[] }) => Promise<void>|void,
369
+ * Defaults to defaultMemberOverlapGuard(ledger) (eft.5.2): rejects with a
370
+ * 409 ApiError on any member overlap with an active reservation. Inject to
371
+ * override or compose (e.g. with the eft.5.3 issue-scope guard).
372
+ * generateSprintId?: (issue: string) => string,
373
+ * resolveRoleMap?: (raw: string|undefined) => Promise<object|undefined>,
374
+ * getBuildVersion?: () => string|null,
375
+ * apra-fleet-gey.2: defaults to defaultBuildVersion() (this module's own
376
+ * on-disk mtime via fs.statSync() -- deliberately NOT a `git rev-parse
377
+ * HEAD` subprocess; see defaultBuildVersion()'s own doc comment for why).
378
+ * Called once at controller creation to stamp what this process is
379
+ * running, and again on every launch() to read what's on disk now --
380
+ * see launch()'s buildVersionWarning below.
381
+ * beadsIdentity?: { get: () => object|null },
382
+ * src/supervisor/beads-identity.mjs's createBeadsIdentityState() handle.
383
+ * When present, launch() records toBeadsSummary(get()) as the ledger
384
+ * entry's `beads` field; absent (tests, older wiring) -> null.
385
+ * backlogMember?: { get: () => { member: { name: string }|null, status: 'ready'|'degraded', reason: string|null } },
386
+ * src/supervisor/backlog-member.mjs's ensureBacklogMember() handle. When
387
+ * present, launch() HARD-PINS roleMap.backlog to that member (see
388
+ * launch()): degraded -> 503 with the reason; member list unreadable ->
389
+ * 503; absent backlog role -> injected; a different member -> 400.
390
+ * Absent (tests, older wiring) -> today's unpinned behaviour.
391
+ * }} deps
392
+ */
393
+ export function createSprintController(deps = {}) {
394
+ const { ledger, spawner } = deps;
395
+ if (!ledger || typeof ledger.list !== 'function' || typeof ledger.get !== 'function' || typeof ledger.claim !== 'function') {
396
+ throw new TypeError('createSprintController requires a ledger with list()/get()/claim()');
397
+ }
398
+ if (!spawner || typeof spawner.spawnSprint !== 'function') {
399
+ throw new TypeError('createSprintController requires a spawner with spawnSprint()');
400
+ }
401
+ const history = deps.history ?? { latestFor: () => undefined, forSprint: () => [], latestForIssueRoot: () => undefined };
402
+ const listMembers = deps.listMembers ?? (() => ({ members: [] }));
403
+ const getBacklog = deps.getBacklog ?? (() => ({ tasks: [] }));
404
+ const proxyState = deps.proxyState ?? proxyChildState;
405
+ const proxyStop = deps.proxyStop ?? proxyChildStop;
406
+ const roleMapResolver = deps.resolveRoleMap ?? resolveRoleMap;
407
+ const beadsIdentity = deps.beadsIdentity ?? null;
408
+ const backlogMemberHandle = deps.backlogMember && typeof deps.backlogMember.get === 'function' ? deps.backlogMember : null;
409
+ const beadsSummaryForLaunch = () => {
410
+ if (!beadsIdentity || typeof beadsIdentity.get !== 'function') return null;
411
+ try {
412
+ return toBeadsSummary(beadsIdentity.get());
413
+ } catch {
414
+ return null;
415
+ }
416
+ };
417
+ // eft.5.2: the default beforeLaunch is the all-or-nothing member-axis
418
+ // overlap guard (409 on conflict), not a no-op. Callers may still inject
419
+ // their own beforeLaunch (e.g. to compose it with the eft.5.3 issue-scope
420
+ // guard) -- this default is what runs when nothing is injected.
421
+ const beforeLaunch = deps.beforeLaunch ?? defaultMemberOverlapGuard(ledger, listMembers);
422
+ const generateSprintId = deps.generateSprintId ?? defaultGenerateSprintId;
423
+ const resolvePort = deps.resolvePort
424
+ ?? ((pid) => (pid != null && spawner.getLiveEntry ? spawner.getLiveEntry(pid)?.port : undefined));
425
+ // apra-fleet-2l4.1: same collaborator watchdog.mjs's classifySprint() uses
426
+ // to distinguish CRASHED from FINISHED -- reused here so getSprint()/
427
+ // stopSprint() can detect "already terminal" independently of PID
428
+ // liveness, before ever touching the child's viewer port.
429
+ const hasTerminalState = deps.hasTerminalState ?? defaultHasTerminalState;
430
+ const getBuildVersion = deps.getBuildVersion ?? defaultBuildVersion;
431
+ // apra-fleet-gey.2: stamped ONCE, at controller creation (supervisor
432
+ // startup) -- deliberately never re-read afterward, so this stays "what
433
+ // code this running process was actually started from", distinct from
434
+ // launch()'s own re-read of getBuildVersion() for "what's on disk now".
435
+ const stampedBuildVersion = getBuildVersion();
436
+
437
+ /** Validate a launch request against the SHARED runner.js helpers. */
438
+ function validateLaunchRequest(body) {
439
+ const rawIssue = body.issue ?? body.target_issue;
440
+ const branch = body.branch;
441
+ const base = body.base ?? body.base_branch;
442
+ const members = normalizeMembers(body.members);
443
+
444
+ // apra-fleet-ymf.1: `issue` may be a single id OR a comma-separated
445
+ // list of ids (mirroring bin/cli.mjs:468's --issue flag / runner.js's
446
+ // targetIssues), so it is split and EACH id validated individually
447
+ // rather than passing the whole raw string to validateIssueId (whose
448
+ // ISSUE_ID_PATTERN has no comma in its charset and would 400 the
449
+ // entire multi-root request). When the split yields nothing (missing,
450
+ // non-string, empty, whitespace-only, or comma-only input),
451
+ // validateIssueId(rawIssue) is called directly on the ORIGINAL value
452
+ // so the error text for those edge cases is byte-identical to the
453
+ // pre-fix single-id behavior.
454
+ const issueIds = splitIssueIds(rawIssue);
455
+ if (issueIds.length === 0) {
456
+ try { validateIssueId(rawIssue); }
457
+ catch (err) { throw new ApiError(400, err.message, 'issue'); }
458
+ // validateIssueId only throws on a falsy/malformed value, so an
459
+ // empty split with a value it accepts should be unreachable --
460
+ // guarded anyway so a launch can never proceed with zero roots.
461
+ throw new ApiError(400, `[Arg Contract] issue must contain at least one id, got "${rawIssue}".`, 'issue');
462
+ }
463
+ for (const id of issueIds) {
464
+ try { validateIssueId(id); }
465
+ catch (err) { throw new ApiError(400, err.message, 'issue'); }
466
+ }
467
+ try { validateBranchName(branch, 'branch'); }
468
+ catch (err) { throw new ApiError(400, err.message, 'branch'); }
469
+ try { validateBranchName(base, 'base'); }
470
+ catch (err) { throw new ApiError(400, err.message, 'base'); }
471
+ try { validateBranchPair(branch, base); }
472
+ catch (err) { throw new ApiError(400, err.message, 'branch'); }
473
+ if (members.length === 0) {
474
+ throw new ApiError(400, 'members must be a non-empty list of member names', 'members');
475
+ }
476
+ // phases (optional): per-launch phase settings. Only `regression` is
477
+ // supported: "run" (default) or "skip". Anything else is rejected here,
478
+ // before any spawn, so a typo can never silently run or skip a phase.
479
+ let skipRegression = false;
480
+ if (body.phases !== undefined) {
481
+ const phases = body.phases;
482
+ if (phases === null || typeof phases !== 'object' || Array.isArray(phases)) {
483
+ throw new ApiError(400, 'phases must be an object, e.g. {"regression":"skip"}', 'phases');
484
+ }
485
+ const unknownPhaseKeys = Object.keys(phases).filter((k) => k !== 'regression');
486
+ if (unknownPhaseKeys.length > 0) {
487
+ throw new ApiError(400, `phases has unknown key(s): ${unknownPhaseKeys.join(', ')}; only "regression" is supported`, 'phases');
488
+ }
489
+ if (phases.regression !== undefined && phases.regression !== 'run' && phases.regression !== 'skip') {
490
+ throw new ApiError(400, `phases.regression must be "run" or "skip", got ${JSON.stringify(phases.regression)}`, 'phases');
491
+ }
492
+ skipRegression = phases.regression === 'skip';
493
+ }
494
+ // `issue` stays a single comma-joined string (the exact shape
495
+ // buildSprintArgv/cli.mjs's --issue flag expects, and byte-identical
496
+ // to the input for the single-id case); `issueIds` is the split array
497
+ // callers use for issueRoots / per-root history lookups.
498
+ return { issue: issueIds.join(','), issueIds, branch, base, members, skipRegression };
499
+ }
500
+
501
+ // -- GET /api/members : list_members + live-reservation overlay -----------
502
+ // apra-fleet-eft.26.2 (Hole 2): the overlay now surfaces BOTH reservation
503
+ // sources -- this supervisor's own ledger (local launches) AND the fleet
504
+ // server's own `reservedBy` record already present on each raw member
505
+ // (e.g. set by a workflow/cli-launched sprint via `member_reservation`,
506
+ // apra-fleet-eft.26.1, which never touches this ledger at all). The local
507
+ // ledger wins when both are present (it is this supervisor's own,
508
+ // most-specific knowledge); the server record is the fallback so a
509
+ // member reserved by some OTHER means is still shown as reserved here,
510
+ // not silently reported as free.
511
+ async function members() {
512
+ const raw = await listMembers();
513
+ const list = Array.isArray(raw) ? raw : (raw && Array.isArray(raw.members) ? raw.members : []);
514
+ // member name -> sprintId that reserves it (first LOCAL reservation wins).
515
+ const reservedBy = new Map();
516
+ for (const r of ledger.list()) {
517
+ for (const m of (r.members ?? [])) {
518
+ if (!reservedBy.has(m)) reservedBy.set(m, r.sprintId);
519
+ }
520
+ }
521
+ return {
522
+ members: list.map((m) => {
523
+ const base = typeof m === 'string' ? { name: m } : { ...m };
524
+ const sid = reservedBy.get(base.name) ?? base.reservedBy ?? null;
525
+ return { ...base, reserved: sid != null, reservedBy: sid };
526
+ }),
527
+ };
528
+ }
529
+
530
+ // -- GET /api/backlog -----------------------------------------------------
531
+ async function backlog() {
532
+ const result = await getBacklog();
533
+ const freshness = ledger.getScopeFreshness();
534
+ return { ...result, scopeFreshness: freshness };
535
+ }
536
+
537
+ // -- POST /api/sprints : validated, goal-forwarding launch ----------------
538
+ async function launch(body = {}) {
539
+ const { issue, issueIds, branch, base, members, skipRegression } = validateLaunchRequest(body);
540
+ // An '@file' roleMap is a CLI-only convenience: over HTTP it would make
541
+ // the supervisor read an arbitrary server-side path named by the request
542
+ // body, and the alias warning could not be computed from it. Reject it.
543
+ if (typeof body.roleMap === 'string' && body.roleMap.trim().startsWith('@')) {
544
+ throw new ApiError(400, "[Arg Contract] roleMap '@file' references are not accepted over HTTP; send the role map as a JSON object or JSON string", 'roleMap');
545
+ }
546
+ const rawRoleMap = body.roleMap === undefined
547
+ ? undefined
548
+ : (typeof body.roleMap === 'string' ? body.roleMap : JSON.stringify(body.roleMap));
549
+ // Backlog-role alias: a conflicting deprecated-alias/backlog
550
+ // pair is a 400 on field 'roleMap' (before any child spawns); the
551
+ // deprecation warning for the alias is surfaced in the response. The
552
+ // operator's ORIGINAL (key-normalized, alias intact) map is what the
553
+ // child CLI receives, so its run log carries the warning too.
554
+ let aliasWarnings = [];
555
+ let forwardRoleMap;
556
+ if (rawRoleMap !== undefined) {
557
+ let parsedRaw;
558
+ try { parsedRaw = JSON.parse(rawRoleMap); } catch { parsedRaw = undefined; }
559
+ if (parsedRaw && typeof parsedRaw === 'object' && !Array.isArray(parsedRaw)) {
560
+ const normalizedRaw = {};
561
+ for (const [k, v] of Object.entries(parsedRaw)) normalizedRaw[normalizeRole(k)] = v;
562
+ try {
563
+ aliasWarnings = resolveBacklogRoleAlias(normalizedRaw).warnings;
564
+ } catch (err) {
565
+ throw new ApiError(400, `[Arg Contract] Invalid roleMap: ${err.message}`, 'roleMap');
566
+ }
567
+ forwardRoleMap = normalizedRaw;
568
+ }
569
+ }
570
+ let roleMap;
571
+ try {
572
+ roleMap = await roleMapResolver(rawRoleMap);
573
+ } catch (err) {
574
+ throw new ApiError(400, err.message, 'roleMap');
575
+ }
576
+ // apra-fleet: ONE listMembers() read, shared with beforeLaunch below
577
+ // (via ctx.membersList) -- both need to know which members are
578
+ // currently flagged unreservable, and issuing two separate fetches
579
+ // per launch opened two separate short-lived MCP transports for what
580
+ // is logically one request-scoped read. A fetch failure here degrades
581
+ // to "no member known unreservable" (best-effort, not the sole
582
+ // enforcement point -- member-reservation.ts's server-side no-op
583
+ // still protects a flagged member even if this can't see it) and
584
+ // leaves membersListRaw undefined so beforeLaunch falls back to its
585
+ // own (equally best-effort) fetch attempt.
586
+ // Backlog hard pin, part 1: a supervisor whose backlog member is
587
+ // not ready cannot launch at all (before any member read or spawn).
588
+ let pinnedBacklogName = null;
589
+ if (backlogMemberHandle) {
590
+ const st = backlogMemberHandle.get() ?? {};
591
+ if (st.status !== 'ready' || !st.member || !st.member.name) {
592
+ throw new ApiError(503, `this supervisor's backlog member is not ready: ${st.reason ?? 'unknown reason'}`);
593
+ }
594
+ pinnedBacklogName = st.member.name;
595
+ }
596
+ let membersListRaw;
597
+ let membersListError = null;
598
+ try {
599
+ membersListRaw = await listMembers();
600
+ } catch (err) {
601
+ membersListError = err && err.message ? err.message : String(err);
602
+ console.error(`[unreservable] listMembers() failed while computing the unreservable-member exclude set (treating as none this launch): ${membersListError}`);
603
+ membersListRaw = undefined;
604
+ }
605
+ // The fleet server was stopped on purpose ('apra-fleet stop'): refuse
606
+ // the launch with that actionable message instead of spawning a
607
+ // sprint that could only fail at connect.
608
+ const stoppedByUser = fleetMembersStoppedByUserReason(membersListRaw);
609
+ if (stoppedByUser) throw new ApiError(503, stoppedByUser);
610
+ // Backlog hard pin, part 2: the pin is only enforceable against a
611
+ // member list that was actually read. listFleetMembers() never
612
+ // throws, so its unavailable marker (not the catch above) is the
613
+ // production signal; either one refuses the launch -- never a
614
+ // silent skip of the check.
615
+ if (pinnedBacklogName) {
616
+ const unavailable = membersListError ?? fleetMembersUnavailableReason(membersListRaw);
617
+ if (unavailable) {
618
+ throw new ApiError(503, `cannot verify backlog member '${pinnedBacklogName}': fleet member list unavailable (${unavailable})`);
619
+ }
620
+ }
621
+ const unreservable = membersListRaw !== undefined ? unreservableMemberNamesFromList(membersListRaw) : new Set();
622
+ const union = memberUnion(members, roleMap, unreservable);
623
+ // apra-fleet-ymf.1: issueRoots is the SPLIT array of individual ids
624
+ // (never the raw comma-joined string) -- the same shape the CLI path
625
+ // already feeds runner.js's targetIssues, and what the ledger schema,
626
+ // history.latestForIssueRoot(), and the eft.5.3 issue-scope overlap
627
+ // guard all expect: one root id per array entry, not one entry
628
+ // holding every root joined together.
629
+ const issueRoots = issueIds;
630
+
631
+ // apra-fleet-gey.2 (extended by ymf.1 for multi-root requests): gate
632
+ // this relaunch on the prior incarnation's terminal record, BEFORE
633
+ // the member-overlap guard/spawn -- a deterministic, unaddressed
634
+ // prior failure (e.g. the engine's own BEADS_SYNC_CONFLICT, or a
635
+ // gey.1 LAUNCH_FAILED fast-exit) will almost certainly recur on an
636
+ // identical relaunch, so there is no reason to burn a
637
+ // spawn/reservation attempt re-hitting it. Checked per-root (in
638
+ // request order) since a multi-root request's ledger history is keyed
639
+ // by INDIVIDUAL root ids, not the joined string -- the first root
640
+ // with a deterministic prior terminal record gates the whole launch.
641
+ // The request's `overrideRelaunchGate: true` is the documented,
642
+ // explicit escape hatch -- never a silent bypass.
643
+ let priorTerminal;
644
+ let priorTerminalRoot;
645
+ if (typeof history.latestForIssueRoot === 'function') {
646
+ for (const root of issueRoots) {
647
+ const found = history.latestForIssueRoot(root);
648
+ if (found && isDeterministicTerminalReason(found)) {
649
+ priorTerminal = found;
650
+ priorTerminalRoot = root;
651
+ break;
652
+ }
653
+ }
654
+ }
655
+ if (priorTerminal && body.overrideRelaunchGate !== true) {
656
+ const namedReason = priorTerminal.terminalReason ?? priorTerminal.reason ?? priorTerminal.event;
657
+ throw new ApiError(
658
+ 409,
659
+ `relaunch of '${priorTerminalRoot}' refused: its prior incarnation ('${priorTerminal.sprintId}') ended with ` +
660
+ `'${namedReason}', which is treated as deterministic and unaddressed -- pass ` +
661
+ `overrideRelaunchGate: true to relaunch anyway.`,
662
+ 'issue',
663
+ );
664
+ }
665
+
666
+ // Backlog hard pin, part 3: checked AFTER resolveBacklogRoleAlias, so
667
+ // the resolved `roleMap.backlog` already carries a deprecated
668
+ // `orchestrator` alias. Absent -> injected into the map the child
669
+ // actually receives (forwardRoleMap when set, else the resolved map);
670
+ // naming any other member -> 400. The pinned member is unreservable,
671
+ // so it stays out of `union` exactly as before.
672
+ let childRoleMap = forwardRoleMap ?? roleMap;
673
+ if (pinnedBacklogName) {
674
+ const raw = roleMap && typeof roleMap === 'object' ? roleMap[ROLE_BACKLOG] : undefined;
675
+ const requested = (Array.isArray(raw) ? raw : (raw === undefined || raw === null ? [] : [raw]))
676
+ .filter((m) => typeof m === 'string' && m.trim().length > 0)
677
+ .map((m) => m.trim());
678
+ if (requested.length === 0) {
679
+ childRoleMap = { ...(childRoleMap && typeof childRoleMap === 'object' ? childRoleMap : {}), [ROLE_BACKLOG]: [pinnedBacklogName] };
680
+ } else if (requested.some((m) => m !== pinnedBacklogName)) {
681
+ throw new ApiError(
682
+ 400,
683
+ `[Arg Contract] roleMap.backlog must be this supervisor's backlog member '${pinnedBacklogName}' (or omitted, ` +
684
+ `which assigns it automatically); got [${requested.join(', ')}].`,
685
+ 'roleMap',
686
+ );
687
+ }
688
+ }
689
+
690
+ // eft.5.2 seam: reject overlapping launches (409) BEFORE spawning a child.
691
+ await beforeLaunch({ members: union, issueRoots, membersList: membersListRaw });
692
+
693
+ // apra-fleet-k7b.1: generate the sprintId BEFORE spawning (not after,
694
+ // as before) so it can be forwarded into the child's own argv as
695
+ // --run-id (buildSprintArgv) -- the SAME incarnation-unique id this
696
+ // ledger reservation uses, so the engine's run-state and the ledger
697
+ // agree on one identity for this launch instead of the child falling
698
+ // back to reusing the (relaunch-shared) branch name.
699
+ const sprintId = generateSprintId(issue);
700
+
701
+ // Forward the per-request goal straight into the child argv (buildSprintArgv
702
+ // pushes `--goal <goal>` when goal !== undefined).
703
+ const spawnOpts = {
704
+ issue,
705
+ members: members.join(','),
706
+ branch,
707
+ base,
708
+ goal: body.goal,
709
+ maxCycles: body.maxCycles,
710
+ allowMissingMembers: body.allowMissingMembers,
711
+ requirementsFile: body.requirementsFile,
712
+ roleMap: childRoleMap,
713
+ budget: body.budget,
714
+ runId: sprintId,
715
+ skipRegression,
716
+ };
717
+ let spawned;
718
+ try {
719
+ spawned = await spawner.spawnSprint(spawnOpts);
720
+ } catch (err) {
721
+ if (err instanceof ApiError) throw err;
722
+ // Name the failing step and the underlying cause (code + message,
723
+ // e.g. an ENOENT on the log path) instead of letting the generic
724
+ // 'internal supervisor error' 500 hide it.
725
+ const code = err && err.code ? `${err.code}: ` : '';
726
+ const detail = err && err.message ? err.message : String(err);
727
+ console.error(`[supervisor] launch of '${sprintId}' failed at step 'spawn sprint child':`, err && err.stack ? err.stack : err);
728
+ throw new ApiError(500, `sprint launch failed at step 'spawn sprint child': ${code}${detail}`);
729
+ }
730
+ // apra-fleet-gey.2: best-effort stale-process detection -- compare
731
+ // the build this supervisor process STAMPED at startup against
732
+ // what's on disk RIGHT NOW. A mismatch means code changed after this
733
+ // process started (the apra-fleet-bnb-e828ded6 incident: a relaunch
734
+ // re-hit an already-fixed-on-disk bug because it ran against the
735
+ // stale pre-fix process) -- reported here, never blocking, since the
736
+ // launch itself is not wrong, only worth a supervisor restart first.
737
+ const currentBuildVersion = getBuildVersion();
738
+ const buildVersionWarning = (stampedBuildVersion != null && currentBuildVersion != null && stampedBuildVersion !== currentBuildVersion)
739
+ ? `running supervisor build (${stampedBuildVersion}) differs from the on-disk build (${currentBuildVersion}) -- ` +
740
+ `if code changed after this process started, restart the supervisor before relying on this relaunch.`
741
+ : null;
742
+ // apra-fleet-3i3.2: persist enough launch metadata (branch/base/goal,
743
+ // alongside the two reservation axes already claimed here) that a
744
+ // future Restart control can reconstruct this exact POST /api/sprints
745
+ // request without operator re-entry. `goal` normalizes `undefined`
746
+ // (the "no goal supplied" case validateLaunchRequest/buildSprintArgv
747
+ // already treat as omitted) to `null`, matching how the ledger treats
748
+ // a pre-existing entry that predates this field.
749
+ // apra-fleet-ou7.1: spawner.spawnSprint() always opens a per-sprint
750
+ // raw stdout/stderr log file before spawning -- record its path on
751
+ // the SAME claim() call that sets childPid, so a dashboard/consumer
752
+ // reading the ledger can find it for a live OR crashed sprint alike.
753
+ // apra-fleet-k7b.2: also record the launch branch on the reservation --
754
+ // hasTerminalState()'s legacy fallback needs it as a lookup key for
755
+ // reservations claimed before k7b.1's run-id plumbing shipped.
756
+ await ledger.claim(sprintId, {
757
+ members: union,
758
+ issueRoots,
759
+ childPid: spawned.pid,
760
+ logPath: spawned.logPath,
761
+ branch,
762
+ base,
763
+ goal: body.goal ?? null,
764
+ // Which .beads this supervisor resolved at launch time (see
765
+ // beads-identity.mjs) -- the same identity the child received as
766
+ // --expect-beads, recorded so the dashboard can show it per row.
767
+ beads: beadsSummaryForLaunch(),
768
+ });
769
+
770
+ return {
771
+ sprintId,
772
+ pid: spawned.pid,
773
+ port: spawned.port,
774
+ logPath: spawned.logPath,
775
+ issueRoots,
776
+ members: union,
777
+ goal: body.goal ?? null,
778
+ buildVersionWarning,
779
+ warnings: aliasWarnings,
780
+ };
781
+ }
782
+
783
+ // -- GET /api/sprints : every live sprint ---------------------------------
784
+ async function listSprints() {
785
+ const freshness = ledger.getScopeFreshness();
786
+ return {
787
+ sprints: ledger.list().map((r) => ({
788
+ sprintId: r.sprintId,
789
+ members: r.members,
790
+ issueRoots: r.issueRoots,
791
+ childPid: r.childPid ?? null,
792
+ port: resolvePort(r.childPid ?? null) ?? null,
793
+ })),
794
+ scopeFreshness: freshness,
795
+ };
796
+ }
797
+
798
+ // -- GET /api/sprints/:id : live child state, else history ----------------
799
+ async function getSprint(id) {
800
+ const reservation = ledger.get(id);
801
+ if (reservation) {
802
+ // apra-fleet-2l4.1: check FIRST whether the engine has already
803
+ // persisted a terminal run-state for this sprint (old_runs/
804
+ // <runId>.json) -- independent of PID liveness, so a child in its
805
+ // post-terminal dashboard-linger window (OS process still alive,
806
+ // but its embedded HTTP viewer server has already closed) is
807
+ // reported cleanly here instead of proxying into a closed port
808
+ // and surfacing a raw ECONNREFUSED-derived 500.
809
+ const terminalState = hasTerminalState(id, reservation.branch ?? null);
810
+ if (terminalState) {
811
+ return { sprintId: id, live: false, terminal: true, state: terminalState };
812
+ }
813
+ const port = resolvePort(reservation.childPid ?? null);
814
+ if (port != null) {
815
+ const state = await proxyState(port);
816
+ return { sprintId: id, live: true, state };
817
+ }
818
+ }
819
+ // Not live (finished/gone, or port unknown): return the historical record.
820
+ const latest = history.latestFor(id);
821
+ if (latest) {
822
+ return { sprintId: id, live: false, history: history.forSprint(id), latest };
823
+ }
824
+ throw new ApiError(404, `no sprint '${id}' is live or in history`);
825
+ }
826
+
827
+ // -- POST /api/sprints/:id/stop : proxy the child's /stop -----------------
828
+ async function stopSprint(id) {
829
+ const reservation = ledger.get(id);
830
+ if (!reservation) {
831
+ throw new ApiError(404, `no live sprint '${id}' to stop`);
832
+ }
833
+ // apra-fleet-2l4.1: same terminal-state check as getSprint() above,
834
+ // BEFORE resolving/proxying the child's viewer port -- a persisted
835
+ // terminal run-state means there is genuinely nothing left to stop,
836
+ // even while the child's OS process is still alive in its
837
+ // post-terminal dashboard-linger window. Returns a clean no-op
838
+ // success instead of a doomed proxyStop() call against an
839
+ // already-closed port (previously surfaced as a raw 500
840
+ // ECONNREFUSED -- apra-fleet-2l4).
841
+ const terminalState = hasTerminalState(id, reservation.branch ?? null);
842
+ if (terminalState) {
843
+ return { sprintId: id, status: 'already-terminal', child: null };
844
+ }
845
+ const port = resolvePort(reservation.childPid ?? null);
846
+ if (port == null) {
847
+ throw new ApiError(409, `sprint '${id}' has no reachable child (port unknown)`);
848
+ }
849
+ const result = await proxyStop(port);
850
+ return { sprintId: id, status: 'stopping', child: result ?? null };
851
+ }
852
+
853
+ return {
854
+ name: 'sprint-controller',
855
+ members,
856
+ backlog,
857
+ launch,
858
+ listSprints,
859
+ getSprint,
860
+ stopSprint,
861
+ };
862
+ }
863
+
864
+ /**
865
+ * Register the six operator endpoints against a supervisor (server.mjs). Each
866
+ * handler maps an ApiError to its status (naming the bad field on a 400) and
867
+ * lets any other error bubble to the supervisor's 500 isolation wrapper.
868
+ *
869
+ * @param {{ route: (method: string, path: string, handler: Function) => void }} supervisor
870
+ * @param {ReturnType<typeof createSprintController>} controller
871
+ */
872
+ export function registerSprintRoutes(supervisor, controller) {
873
+ const onApiError = (res, err) => {
874
+ if (err instanceof ApiError) {
875
+ const payload = { error: err.message };
876
+ if (err.field) payload.field = err.field;
877
+ sendJson(res, err.status, payload);
878
+ return true;
879
+ }
880
+ return false;
881
+ };
882
+
883
+ supervisor.route('GET', '/api/members', async (req, res) => {
884
+ sendJson(res, 200, await controller.members());
885
+ });
886
+
887
+ supervisor.route('GET', '/api/backlog', async (req, res) => {
888
+ sendJson(res, 200, await controller.backlog());
889
+ });
890
+
891
+ supervisor.route('POST', '/api/sprints', async (req, res) => {
892
+ const body = (await readJsonBody(req)) ?? {};
893
+ try {
894
+ sendJson(res, 201, await controller.launch(body));
895
+ } catch (err) {
896
+ if (!onApiError(res, err)) throw err;
897
+ }
898
+ });
899
+
900
+ supervisor.route('GET', '/api/sprints', async (req, res) => {
901
+ sendJson(res, 200, await controller.listSprints());
902
+ });
903
+
904
+ supervisor.route('GET', '/api/sprints/:id', async (req, res, ctx) => {
905
+ try {
906
+ sendJson(res, 200, await controller.getSprint(ctx.params.id));
907
+ } catch (err) {
908
+ if (!onApiError(res, err)) throw err;
909
+ }
910
+ });
911
+
912
+ supervisor.route('POST', '/api/sprints/:id/stop', async (req, res, ctx) => {
913
+ try {
914
+ sendJson(res, 200, await controller.stopSprint(ctx.params.id));
915
+ } catch (err) {
916
+ if (!onApiError(res, err)) throw err;
917
+ }
918
+ });
919
+ }