@apralabs/apra-fleet 0.4.3 → 0.4.5

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