@apralabs/apra-fleet 0.3.6 → 0.4.0

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 (569) hide show
  1. package/README.md +245 -257
  2. package/dist/agents/backlog-groomer.md +287 -0
  3. package/dist/agents/deployer.md +52 -11
  4. package/dist/agents/doer.md +32 -7
  5. package/dist/agents/integ-test-runner.md +151 -61
  6. package/dist/agents/plan-reviewer.md +74 -17
  7. package/dist/agents/planner.md +94 -14
  8. package/dist/agents/regression-test-runner.md +216 -0
  9. package/dist/agents/reviewer.md +21 -6
  10. package/dist/agents/schemas/backlog-groomer-input.json +35 -0
  11. package/dist/agents/schemas/backlog-groomer-output.json +164 -0
  12. package/dist/agents/schemas/integ-test-runner-output.json +34 -0
  13. package/dist/agents/schemas/regression-test-runner-input.json +15 -0
  14. package/dist/agents/schemas/regression-test-runner-output.json +50 -0
  15. package/dist/agents/schemas/reviewer-output.json +4 -0
  16. package/dist/cli/agent-transform.d.ts +1 -0
  17. package/dist/cli/agent-transform.d.ts.map +1 -1
  18. package/dist/cli/agent-transform.js +77 -0
  19. package/dist/cli/agent-transform.js.map +1 -1
  20. package/dist/cli/auth.d.ts +3 -0
  21. package/dist/cli/auth.d.ts.map +1 -1
  22. package/dist/cli/auth.js +181 -5
  23. package/dist/cli/auth.js.map +1 -1
  24. package/dist/cli/config.d.ts +5 -1
  25. package/dist/cli/config.d.ts.map +1 -1
  26. package/dist/cli/config.js +7 -1
  27. package/dist/cli/config.js.map +1 -1
  28. package/dist/cli/dolt-install.d.ts +91 -0
  29. package/dist/cli/dolt-install.d.ts.map +1 -0
  30. package/dist/cli/dolt-install.js +334 -0
  31. package/dist/cli/dolt-install.js.map +1 -0
  32. package/dist/cli/install-guard.d.ts +29 -0
  33. package/dist/cli/install-guard.d.ts.map +1 -0
  34. package/dist/cli/install-guard.js +153 -0
  35. package/dist/cli/install-guard.js.map +1 -0
  36. package/dist/cli/install.d.ts +44 -3
  37. package/dist/cli/install.d.ts.map +1 -1
  38. package/dist/cli/install.js +604 -108
  39. package/dist/cli/install.js.map +1 -1
  40. package/dist/cli/join.d.ts +12 -0
  41. package/dist/cli/join.d.ts.map +1 -0
  42. package/dist/cli/join.js +87 -0
  43. package/dist/cli/join.js.map +1 -0
  44. package/dist/cli/register-member.d.ts +2 -0
  45. package/dist/cli/register-member.d.ts.map +1 -0
  46. package/dist/cli/register-member.js +193 -0
  47. package/dist/cli/register-member.js.map +1 -0
  48. package/dist/cli/restart.d.ts +2 -0
  49. package/dist/cli/restart.d.ts.map +1 -0
  50. package/dist/cli/restart.js +7 -0
  51. package/dist/cli/restart.js.map +1 -0
  52. package/dist/cli/spoke.d.ts +35 -0
  53. package/dist/cli/spoke.d.ts.map +1 -0
  54. package/dist/cli/spoke.js +212 -0
  55. package/dist/cli/spoke.js.map +1 -0
  56. package/dist/cli/start.d.ts +2 -0
  57. package/dist/cli/start.d.ts.map +1 -0
  58. package/dist/cli/start.js +92 -0
  59. package/dist/cli/start.js.map +1 -0
  60. package/dist/cli/status.d.ts +2 -0
  61. package/dist/cli/status.d.ts.map +1 -0
  62. package/dist/cli/status.js +83 -0
  63. package/dist/cli/status.js.map +1 -0
  64. package/dist/cli/stop.d.ts +2 -0
  65. package/dist/cli/stop.d.ts.map +1 -0
  66. package/dist/cli/stop.js +51 -0
  67. package/dist/cli/stop.js.map +1 -0
  68. package/dist/cli/uninstall.d.ts.map +1 -1
  69. package/dist/cli/uninstall.js +109 -9
  70. package/dist/cli/uninstall.js.map +1 -1
  71. package/dist/cli/update.d.ts.map +1 -1
  72. package/dist/cli/update.js +10 -1
  73. package/dist/cli/update.js.map +1 -1
  74. package/dist/cli/workflow-assets.d.ts +37 -0
  75. package/dist/cli/workflow-assets.d.ts.map +1 -0
  76. package/dist/cli/workflow-assets.js +144 -0
  77. package/dist/cli/workflow-assets.js.map +1 -0
  78. package/dist/cli/workflow.d.ts +75 -0
  79. package/dist/cli/workflow.d.ts.map +1 -0
  80. package/dist/cli/workflow.js +397 -0
  81. package/dist/cli/workflow.js.map +1 -0
  82. package/dist/hub-service/activity.d.ts +30 -0
  83. package/dist/hub-service/activity.d.ts.map +1 -0
  84. package/dist/hub-service/activity.js +20 -0
  85. package/dist/hub-service/activity.js.map +1 -0
  86. package/dist/hub-service/audit-log.d.ts +19 -0
  87. package/dist/hub-service/audit-log.d.ts.map +1 -0
  88. package/dist/hub-service/audit-log.js +13 -0
  89. package/dist/hub-service/audit-log.js.map +1 -0
  90. package/dist/hub-service/db/pool.d.ts +19 -0
  91. package/dist/hub-service/db/pool.d.ts.map +1 -0
  92. package/dist/hub-service/db/pool.js +53 -0
  93. package/dist/hub-service/db/pool.js.map +1 -0
  94. package/dist/hub-service/enrollment.d.ts +29 -0
  95. package/dist/hub-service/enrollment.d.ts.map +1 -0
  96. package/dist/hub-service/enrollment.js +48 -0
  97. package/dist/hub-service/enrollment.js.map +1 -0
  98. package/dist/hub-service/envelope-routes.d.ts +46 -0
  99. package/dist/hub-service/envelope-routes.d.ts.map +1 -0
  100. package/dist/hub-service/envelope-routes.js +94 -0
  101. package/dist/hub-service/envelope-routes.js.map +1 -0
  102. package/dist/hub-service/handlers/installers.d.ts +14 -0
  103. package/dist/hub-service/handlers/installers.d.ts.map +1 -0
  104. package/dist/hub-service/handlers/installers.js +8 -0
  105. package/dist/hub-service/handlers/installers.js.map +1 -0
  106. package/dist/hub-service/http-server.d.ts +31 -0
  107. package/dist/hub-service/http-server.d.ts.map +1 -0
  108. package/dist/hub-service/http-server.js +711 -0
  109. package/dist/hub-service/http-server.js.map +1 -0
  110. package/dist/hub-service/hub-jwt.d.ts +30 -0
  111. package/dist/hub-service/hub-jwt.d.ts.map +1 -0
  112. package/dist/hub-service/hub-jwt.js +105 -0
  113. package/dist/hub-service/hub-jwt.js.map +1 -0
  114. package/dist/hub-service/jwt-revocation.d.ts +20 -0
  115. package/dist/hub-service/jwt-revocation.d.ts.map +1 -0
  116. package/dist/hub-service/jwt-revocation.js +18 -0
  117. package/dist/hub-service/jwt-revocation.js.map +1 -0
  118. package/dist/hub-service/machines.d.ts +16 -0
  119. package/dist/hub-service/machines.d.ts.map +1 -0
  120. package/dist/hub-service/machines.js +14 -0
  121. package/dist/hub-service/machines.js.map +1 -0
  122. package/dist/hub-service/main.d.ts +3 -0
  123. package/dist/hub-service/main.d.ts.map +1 -0
  124. package/dist/hub-service/main.js +64 -0
  125. package/dist/hub-service/main.js.map +1 -0
  126. package/dist/hub-service/member-tokens.d.ts +11 -0
  127. package/dist/hub-service/member-tokens.d.ts.map +1 -0
  128. package/dist/hub-service/member-tokens.js +49 -0
  129. package/dist/hub-service/member-tokens.js.map +1 -0
  130. package/dist/hub-service/member-view.d.ts +20 -0
  131. package/dist/hub-service/member-view.d.ts.map +1 -0
  132. package/dist/hub-service/member-view.js +76 -0
  133. package/dist/hub-service/member-view.js.map +1 -0
  134. package/dist/hub-service/members.d.ts +44 -0
  135. package/dist/hub-service/members.d.ts.map +1 -0
  136. package/dist/hub-service/members.js +25 -0
  137. package/dist/hub-service/members.js.map +1 -0
  138. package/dist/hub-service/presence.d.ts +40 -0
  139. package/dist/hub-service/presence.d.ts.map +1 -0
  140. package/dist/hub-service/presence.js +44 -0
  141. package/dist/hub-service/presence.js.map +1 -0
  142. package/dist/hub-service/project-view.d.ts +12 -0
  143. package/dist/hub-service/project-view.d.ts.map +1 -0
  144. package/dist/hub-service/project-view.js +34 -0
  145. package/dist/hub-service/project-view.js.map +1 -0
  146. package/dist/hub-service/projects.d.ts +48 -0
  147. package/dist/hub-service/projects.d.ts.map +1 -0
  148. package/dist/hub-service/projects.js +80 -0
  149. package/dist/hub-service/projects.js.map +1 -0
  150. package/dist/hub-service/relay-queue.d.ts +115 -0
  151. package/dist/hub-service/relay-queue.d.ts.map +1 -0
  152. package/dist/hub-service/relay-queue.js +148 -0
  153. package/dist/hub-service/relay-queue.js.map +1 -0
  154. package/dist/hub-service/session-jwt.d.ts +10 -0
  155. package/dist/hub-service/session-jwt.d.ts.map +1 -0
  156. package/dist/hub-service/session-jwt.js +69 -0
  157. package/dist/hub-service/session-jwt.js.map +1 -0
  158. package/dist/hub-service/usage.d.ts +40 -0
  159. package/dist/hub-service/usage.d.ts.map +1 -0
  160. package/dist/hub-service/usage.js +25 -0
  161. package/dist/hub-service/usage.js.map +1 -0
  162. package/dist/hub-service/users.d.ts +56 -0
  163. package/dist/hub-service/users.d.ts.map +1 -0
  164. package/dist/hub-service/users.js +72 -0
  165. package/dist/hub-service/users.js.map +1 -0
  166. package/dist/hub-service/workspaces.d.ts +20 -0
  167. package/dist/hub-service/workspaces.d.ts.map +1 -0
  168. package/dist/hub-service/workspaces.js +10 -0
  169. package/dist/hub-service/workspaces.js.map +1 -0
  170. package/dist/index.js +179 -132
  171. package/dist/index.js.map +1 -1
  172. package/dist/os/linux.d.ts +13 -0
  173. package/dist/os/linux.d.ts.map +1 -1
  174. package/dist/os/linux.js +62 -3
  175. package/dist/os/linux.js.map +1 -1
  176. package/dist/os/os-commands.d.ts +10 -0
  177. package/dist/os/os-commands.d.ts.map +1 -1
  178. package/dist/os/windows.d.ts +1 -0
  179. package/dist/os/windows.d.ts.map +1 -1
  180. package/dist/os/windows.js +21 -1
  181. package/dist/os/windows.js.map +1 -1
  182. package/dist/paths.d.ts +23 -0
  183. package/dist/paths.d.ts.map +1 -1
  184. package/dist/paths.js +29 -0
  185. package/dist/paths.js.map +1 -1
  186. package/dist/providers/agy.d.ts +9 -2
  187. package/dist/providers/agy.d.ts.map +1 -1
  188. package/dist/providers/agy.js +127 -14
  189. package/dist/providers/agy.js.map +1 -1
  190. package/dist/providers/claude.d.ts +6 -2
  191. package/dist/providers/claude.d.ts.map +1 -1
  192. package/dist/providers/claude.js +248 -9
  193. package/dist/providers/claude.js.map +1 -1
  194. package/dist/providers/codex.d.ts +3 -2
  195. package/dist/providers/codex.d.ts.map +1 -1
  196. package/dist/providers/codex.js +7 -0
  197. package/dist/providers/codex.js.map +1 -1
  198. package/dist/providers/copilot.d.ts +3 -2
  199. package/dist/providers/copilot.d.ts.map +1 -1
  200. package/dist/providers/copilot.js +8 -1
  201. package/dist/providers/copilot.js.map +1 -1
  202. package/dist/providers/gemini.d.ts +3 -2
  203. package/dist/providers/gemini.d.ts.map +1 -1
  204. package/dist/providers/gemini.js +11 -1
  205. package/dist/providers/gemini.js.map +1 -1
  206. package/dist/providers/index.d.ts +1 -0
  207. package/dist/providers/index.d.ts.map +1 -1
  208. package/dist/providers/index.js +3 -0
  209. package/dist/providers/index.js.map +1 -1
  210. package/dist/providers/none.d.ts +51 -0
  211. package/dist/providers/none.d.ts.map +1 -0
  212. package/dist/providers/none.js +103 -0
  213. package/dist/providers/none.js.map +1 -0
  214. package/dist/providers/opencode.d.ts +4 -2
  215. package/dist/providers/opencode.d.ts.map +1 -1
  216. package/dist/providers/opencode.js +49 -0
  217. package/dist/providers/opencode.js.map +1 -1
  218. package/dist/providers/provider.d.ts +79 -1
  219. package/dist/providers/provider.d.ts.map +1 -1
  220. package/dist/providers/provider.js +10 -0
  221. package/dist/providers/provider.js.map +1 -1
  222. package/dist/services/agent-provisioner.d.ts +3 -3
  223. package/dist/services/agent-provisioner.d.ts.map +1 -1
  224. package/dist/services/agent-provisioner.js +12 -5
  225. package/dist/services/agent-provisioner.js.map +1 -1
  226. package/dist/services/auth-socket.d.ts.map +1 -1
  227. package/dist/services/auth-socket.js +2 -0
  228. package/dist/services/auth-socket.js.map +1 -1
  229. package/dist/services/budget-awareness.d.ts +130 -0
  230. package/dist/services/budget-awareness.d.ts.map +1 -0
  231. package/dist/services/budget-awareness.js +129 -0
  232. package/dist/services/budget-awareness.js.map +1 -0
  233. package/dist/services/cloud-sync.d.ts +35 -0
  234. package/dist/services/cloud-sync.d.ts.map +1 -0
  235. package/dist/services/cloud-sync.js +90 -0
  236. package/dist/services/cloud-sync.js.map +1 -0
  237. package/dist/services/context-admission.d.ts +82 -0
  238. package/dist/services/context-admission.d.ts.map +1 -0
  239. package/dist/services/context-admission.js +136 -0
  240. package/dist/services/context-admission.js.map +1 -0
  241. package/dist/services/event-bus.d.ts +27 -0
  242. package/dist/services/event-bus.d.ts.map +1 -0
  243. package/dist/services/event-bus.js +20 -0
  244. package/dist/services/event-bus.js.map +1 -0
  245. package/dist/services/file-chunker.d.ts +38 -0
  246. package/dist/services/file-chunker.d.ts.map +1 -0
  247. package/dist/services/file-chunker.js +63 -0
  248. package/dist/services/file-chunker.js.map +1 -0
  249. package/dist/services/file-transfer-relay.d.ts +55 -0
  250. package/dist/services/file-transfer-relay.d.ts.map +1 -0
  251. package/dist/services/file-transfer-relay.js +115 -0
  252. package/dist/services/file-transfer-relay.js.map +1 -0
  253. package/dist/services/github-app.d.ts.map +1 -1
  254. package/dist/services/github-app.js +1 -0
  255. package/dist/services/github-app.js.map +1 -1
  256. package/dist/services/http-transport.d.ts +25 -0
  257. package/dist/services/http-transport.d.ts.map +1 -0
  258. package/dist/services/http-transport.js +371 -0
  259. package/dist/services/http-transport.js.map +1 -0
  260. package/dist/services/hub-client.d.ts +69 -0
  261. package/dist/services/hub-client.d.ts.map +1 -0
  262. package/dist/services/hub-client.js +217 -0
  263. package/dist/services/hub-client.js.map +1 -0
  264. package/dist/services/jwt.d.ts +17 -0
  265. package/dist/services/jwt.d.ts.map +1 -0
  266. package/dist/services/jwt.js +70 -0
  267. package/dist/services/jwt.js.map +1 -0
  268. package/dist/services/known-sessions.d.ts +8 -0
  269. package/dist/services/known-sessions.d.ts.map +1 -0
  270. package/dist/services/known-sessions.js +40 -0
  271. package/dist/services/known-sessions.js.map +1 -0
  272. package/dist/services/model-pricing.d.ts +36 -0
  273. package/dist/services/model-pricing.d.ts.map +1 -0
  274. package/dist/services/model-pricing.js +108 -0
  275. package/dist/services/model-pricing.js.map +1 -0
  276. package/dist/services/orphan-recovery.d.ts +56 -0
  277. package/dist/services/orphan-recovery.d.ts.map +1 -0
  278. package/dist/services/orphan-recovery.js +111 -0
  279. package/dist/services/orphan-recovery.js.map +1 -0
  280. package/dist/services/pending-responses.d.ts +23 -0
  281. package/dist/services/pending-responses.d.ts.map +1 -0
  282. package/dist/services/pending-responses.js +52 -0
  283. package/dist/services/pending-responses.js.map +1 -0
  284. package/dist/services/registry.d.ts +4 -1
  285. package/dist/services/registry.d.ts.map +1 -1
  286. package/dist/services/registry.js +3 -0
  287. package/dist/services/registry.js.map +1 -1
  288. package/dist/services/relay-context.d.ts +23 -0
  289. package/dist/services/relay-context.d.ts.map +1 -0
  290. package/dist/services/relay-context.js +8 -0
  291. package/dist/services/relay-context.js.map +1 -0
  292. package/dist/services/relay-executor.d.ts +68 -0
  293. package/dist/services/relay-executor.d.ts.map +1 -0
  294. package/dist/services/relay-executor.js +70 -0
  295. package/dist/services/relay-executor.js.map +1 -0
  296. package/dist/services/relay-request.d.ts +65 -0
  297. package/dist/services/relay-request.d.ts.map +1 -0
  298. package/dist/services/relay-request.js +129 -0
  299. package/dist/services/relay-request.js.map +1 -0
  300. package/dist/services/relay-strategy.d.ts +19 -0
  301. package/dist/services/relay-strategy.d.ts.map +1 -0
  302. package/dist/services/relay-strategy.js +111 -0
  303. package/dist/services/relay-strategy.js.map +1 -0
  304. package/dist/services/service-manager/index.d.ts +5 -0
  305. package/dist/services/service-manager/index.d.ts.map +1 -0
  306. package/dist/services/service-manager/index.js +66 -0
  307. package/dist/services/service-manager/index.js.map +1 -0
  308. package/dist/services/service-manager/linux.d.ts +10 -0
  309. package/dist/services/service-manager/linux.d.ts.map +1 -0
  310. package/dist/services/service-manager/linux.js +97 -0
  311. package/dist/services/service-manager/linux.js.map +1 -0
  312. package/dist/services/service-manager/macos.d.ts +10 -0
  313. package/dist/services/service-manager/macos.d.ts.map +1 -0
  314. package/dist/services/service-manager/macos.js +94 -0
  315. package/dist/services/service-manager/macos.js.map +1 -0
  316. package/dist/services/service-manager/types.d.ts +18 -0
  317. package/dist/services/service-manager/types.d.ts.map +1 -0
  318. package/dist/services/service-manager/types.js +5 -0
  319. package/dist/services/service-manager/types.js.map +1 -0
  320. package/dist/services/service-manager/windows.d.ts +10 -0
  321. package/dist/services/service-manager/windows.d.ts.map +1 -0
  322. package/dist/services/service-manager/windows.js +73 -0
  323. package/dist/services/service-manager/windows.js.map +1 -0
  324. package/dist/services/session-registry.d.ts +70 -0
  325. package/dist/services/session-registry.d.ts.map +1 -0
  326. package/dist/services/session-registry.js +91 -0
  327. package/dist/services/session-registry.js.map +1 -0
  328. package/dist/services/singleton.d.ts +15 -0
  329. package/dist/services/singleton.d.ts.map +1 -0
  330. package/dist/services/singleton.js +98 -0
  331. package/dist/services/singleton.js.map +1 -0
  332. package/dist/services/sprint-coordination.d.ts +168 -0
  333. package/dist/services/sprint-coordination.d.ts.map +1 -0
  334. package/dist/services/sprint-coordination.js +564 -0
  335. package/dist/services/sprint-coordination.js.map +1 -0
  336. package/dist/services/ssh.d.ts.map +1 -1
  337. package/dist/services/ssh.js +70 -3
  338. package/dist/services/ssh.js.map +1 -1
  339. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  340. package/dist/services/stall/log-path-resolver.js +8 -1
  341. package/dist/services/stall/log-path-resolver.js.map +1 -1
  342. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  343. package/dist/services/stall/stall-detector.js +39 -7
  344. package/dist/services/stall/stall-detector.js.map +1 -1
  345. package/dist/services/stall/stall-poller.d.ts +16 -0
  346. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  347. package/dist/services/stall/stall-poller.js +136 -18
  348. package/dist/services/stall/stall-poller.js.map +1 -1
  349. package/dist/services/strategy.d.ts.map +1 -1
  350. package/dist/services/strategy.js +55 -5
  351. package/dist/services/strategy.js.map +1 -1
  352. package/dist/services/substitution-engine.d.ts +20 -0
  353. package/dist/services/substitution-engine.d.ts.map +1 -0
  354. package/dist/services/substitution-engine.js +92 -0
  355. package/dist/services/substitution-engine.js.map +1 -0
  356. package/dist/services/task-cleanup.d.ts.map +1 -1
  357. package/dist/services/task-cleanup.js +1 -9
  358. package/dist/services/task-cleanup.js.map +1 -1
  359. package/dist/services/token-issuer.d.ts +47 -0
  360. package/dist/services/token-issuer.d.ts.map +1 -0
  361. package/dist/services/token-issuer.js +63 -0
  362. package/dist/services/token-issuer.js.map +1 -0
  363. package/dist/services/tool-registry.d.ts +3 -0
  364. package/dist/services/tool-registry.d.ts.map +1 -0
  365. package/dist/services/tool-registry.js +139 -0
  366. package/dist/services/tool-registry.js.map +1 -0
  367. package/dist/services/user-config.d.ts +14 -0
  368. package/dist/services/user-config.d.ts.map +1 -1
  369. package/dist/services/user-config.js +55 -0
  370. package/dist/services/user-config.js.map +1 -1
  371. package/dist/services/vcs/types.d.ts +44 -0
  372. package/dist/services/vcs/types.d.ts.map +1 -1
  373. package/dist/skills/fleet-sprint-cli/SKILL.md +103 -0
  374. package/dist/skills/pm/cost.md +3 -0
  375. package/dist/skills/pm/doer-reviewer-loop.md +3 -0
  376. package/dist/tools/check-status.d.ts.map +1 -1
  377. package/dist/tools/check-status.js +8 -2
  378. package/dist/tools/check-status.js.map +1 -1
  379. package/dist/tools/child-id-allocator.d.ts +45 -0
  380. package/dist/tools/child-id-allocator.d.ts.map +1 -0
  381. package/dist/tools/child-id-allocator.js +62 -0
  382. package/dist/tools/child-id-allocator.js.map +1 -0
  383. package/dist/tools/cloud-control.d.ts +2 -2
  384. package/dist/tools/compose-permissions.d.ts +12 -4
  385. package/dist/tools/compose-permissions.d.ts.map +1 -1
  386. package/dist/tools/compose-permissions.js +55 -4
  387. package/dist/tools/compose-permissions.js.map +1 -1
  388. package/dist/tools/dolt-push-mutex.d.ts +44 -0
  389. package/dist/tools/dolt-push-mutex.d.ts.map +1 -0
  390. package/dist/tools/dolt-push-mutex.js +83 -0
  391. package/dist/tools/dolt-push-mutex.js.map +1 -0
  392. package/dist/tools/execute-command.d.ts +11 -1
  393. package/dist/tools/execute-command.d.ts.map +1 -1
  394. package/dist/tools/execute-command.js +22 -5
  395. package/dist/tools/execute-command.js.map +1 -1
  396. package/dist/tools/execute-prompt.d.ts +72 -12
  397. package/dist/tools/execute-prompt.d.ts.map +1 -1
  398. package/dist/tools/execute-prompt.js +962 -71
  399. package/dist/tools/execute-prompt.js.map +1 -1
  400. package/dist/tools/get-member-model-pricing.d.ts +21 -0
  401. package/dist/tools/get-member-model-pricing.d.ts.map +1 -0
  402. package/dist/tools/get-member-model-pricing.js +29 -0
  403. package/dist/tools/get-member-model-pricing.js.map +1 -0
  404. package/dist/tools/list-members.d.ts.map +1 -1
  405. package/dist/tools/list-members.js +39 -7
  406. package/dist/tools/list-members.js.map +1 -1
  407. package/dist/tools/member-detail.d.ts +1 -1
  408. package/dist/tools/member-detail.d.ts.map +1 -1
  409. package/dist/tools/member-detail.js +8 -2
  410. package/dist/tools/member-detail.js.map +1 -1
  411. package/dist/tools/member-reservation.d.ts +29 -0
  412. package/dist/tools/member-reservation.d.ts.map +1 -0
  413. package/dist/tools/member-reservation.js +71 -0
  414. package/dist/tools/member-reservation.js.map +1 -0
  415. package/dist/tools/provision-vcs-auth.d.ts +7 -7
  416. package/dist/tools/provision-vcs-auth.js +1 -1
  417. package/dist/tools/provision-vcs-auth.js.map +1 -1
  418. package/dist/tools/register-member.d.ts +17 -5
  419. package/dist/tools/register-member.d.ts.map +1 -1
  420. package/dist/tools/register-member.js +144 -5
  421. package/dist/tools/register-member.js.map +1 -1
  422. package/dist/tools/remove-member.d.ts +1 -1
  423. package/dist/tools/report-status.d.ts +33 -0
  424. package/dist/tools/report-status.d.ts.map +1 -0
  425. package/dist/tools/report-status.js +44 -0
  426. package/dist/tools/report-status.js.map +1 -0
  427. package/dist/tools/respond-to-message.d.ts +21 -0
  428. package/dist/tools/respond-to-message.d.ts.map +1 -0
  429. package/dist/tools/respond-to-message.js +23 -0
  430. package/dist/tools/respond-to-message.js.map +1 -0
  431. package/dist/tools/send-files.d.ts +3 -0
  432. package/dist/tools/send-files.d.ts.map +1 -1
  433. package/dist/tools/send-files.js +88 -8
  434. package/dist/tools/send-files.js.map +1 -1
  435. package/dist/tools/send-message.d.ts +27 -0
  436. package/dist/tools/send-message.d.ts.map +1 -0
  437. package/dist/tools/send-message.js +46 -0
  438. package/dist/tools/send-message.js.map +1 -0
  439. package/dist/tools/shutdown-server.d.ts +2 -0
  440. package/dist/tools/shutdown-server.d.ts.map +1 -1
  441. package/dist/tools/shutdown-server.js +19 -0
  442. package/dist/tools/shutdown-server.js.map +1 -1
  443. package/dist/tools/update-member.d.ts +8 -8
  444. package/dist/tools/update-member.d.ts.map +1 -1
  445. package/dist/tools/update-member.js +11 -1
  446. package/dist/tools/update-member.js.map +1 -1
  447. package/dist/types.d.ts +15 -3
  448. package/dist/types.d.ts.map +1 -1
  449. package/dist/utils/agent-helpers.d.ts +2 -1
  450. package/dist/utils/agent-helpers.d.ts.map +1 -1
  451. package/dist/utils/agent-helpers.js +7 -2
  452. package/dist/utils/agent-helpers.js.map +1 -1
  453. package/dist/utils/pid-helpers.d.ts +15 -0
  454. package/dist/utils/pid-helpers.d.ts.map +1 -1
  455. package/dist/utils/pid-helpers.js +23 -0
  456. package/dist/utils/pid-helpers.js.map +1 -1
  457. package/dist/utils/process-utils.d.ts +3 -0
  458. package/dist/utils/process-utils.d.ts.map +1 -0
  459. package/dist/utils/process-utils.js +42 -0
  460. package/dist/utils/process-utils.js.map +1 -0
  461. package/dist/utils/prompt-errors.d.ts +2 -1
  462. package/dist/utils/prompt-errors.d.ts.map +1 -1
  463. package/dist/utils/prompt-errors.js +13 -3
  464. package/dist/utils/prompt-errors.js.map +1 -1
  465. package/dist/utils/workspace-trust.d.ts +24 -0
  466. package/dist/utils/workspace-trust.d.ts.map +1 -0
  467. package/dist/utils/workspace-trust.js +35 -0
  468. package/dist/utils/workspace-trust.js.map +1 -0
  469. package/dist/workflows/auto-sprint.js +450 -87
  470. package/package.json +35 -7
  471. package/packages/apra-fleet-client/package.json +26 -0
  472. package/packages/apra-fleet-client/src/client/api.mjs +396 -0
  473. package/packages/apra-fleet-client/src/client/client.mjs +146 -0
  474. package/packages/apra-fleet-client/src/client/errors.mjs +71 -0
  475. package/packages/apra-fleet-client/src/client/factory.mjs +65 -0
  476. package/packages/apra-fleet-client/src/client/server-resolution.mjs +265 -0
  477. package/packages/apra-fleet-client/src/client/transport.mjs +327 -0
  478. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +287 -0
  479. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +89 -0
  480. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +139 -0
  481. package/packages/apra-fleet-se/apra-pm/agents/doer.md +225 -0
  482. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +169 -0
  483. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +316 -0
  484. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +188 -0
  485. package/packages/apra-fleet-se/apra-pm/agents/planner.md +239 -0
  486. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +216 -0
  487. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +174 -0
  488. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-input.json +35 -0
  489. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +164 -0
  490. package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-input.json +26 -0
  491. package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-output.json +18 -0
  492. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-input.json +19 -0
  493. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +17 -0
  494. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-input.json +25 -0
  495. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +22 -0
  496. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +31 -0
  497. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +18 -0
  498. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-input.json +20 -0
  499. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +61 -0
  500. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-input.json +15 -0
  501. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +30 -0
  502. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-input.json +15 -0
  503. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +50 -0
  504. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-input.json +25 -0
  505. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +38 -0
  506. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +402 -0
  507. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +142 -0
  508. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +157 -0
  509. package/packages/apra-fleet-se/apra-pm/skills/pm/doer-reviewer-loop.md +300 -0
  510. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +121 -0
  511. package/packages/apra-fleet-se/apra-pm/skills/pm/simple-sprint.md +65 -0
  512. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +327 -0
  513. package/packages/apra-fleet-se/apra-pm/skills/pm/worktrees.md +92 -0
  514. package/packages/apra-fleet-se/apra-pm/version.json +3 -0
  515. package/packages/apra-fleet-se/bin/cli.mjs +857 -0
  516. package/packages/apra-fleet-se/bin/serve.mjs +383 -0
  517. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +178 -0
  518. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +914 -0
  519. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +177 -0
  520. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +191 -0
  521. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +151 -0
  522. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +127 -0
  523. package/packages/apra-fleet-se/fleet-sprint/docs/fleet-sprint-diagram.md +94 -0
  524. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +1125 -0
  525. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +72 -0
  526. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +339 -0
  527. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +360 -0
  528. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +363 -0
  529. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1244 -0
  530. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +572 -0
  531. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +118 -0
  532. package/packages/apra-fleet-se/fleet-sprint/runner.js +9447 -0
  533. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +103 -0
  534. package/packages/apra-fleet-se/fleet-sprint/sprint-lock.mjs +140 -0
  535. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +435 -0
  536. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +68 -0
  537. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +53 -0
  538. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +146 -0
  539. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/generic-git.mjs +176 -0
  540. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +222 -0
  541. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +218 -0
  542. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +882 -0
  543. package/packages/apra-fleet-se/package.json +28 -0
  544. package/packages/apra-fleet-se/workflow.json +1 -0
  545. package/packages/apra-fleet-workflow/package.json +30 -0
  546. package/packages/apra-fleet-workflow/src/viewer/command-output-cap.mjs +112 -0
  547. package/packages/apra-fleet-workflow/src/viewer/debounced-writer.mjs +153 -0
  548. package/packages/apra-fleet-workflow/src/viewer/html-utils.mjs +31 -0
  549. package/packages/apra-fleet-workflow/src/viewer/index.mjs +1325 -0
  550. package/packages/apra-fleet-workflow/src/viewer/lean-state.mjs +237 -0
  551. package/packages/apra-fleet-workflow/src/viewer/run-state-paths.mjs +130 -0
  552. package/packages/apra-fleet-workflow/src/viewer/sprint-state-paths.mjs +29 -0
  553. package/packages/apra-fleet-workflow/src/workflow/engine.mjs +200 -0
  554. package/packages/apra-fleet-workflow/src/workflow/errors.mjs +146 -0
  555. package/packages/apra-fleet-workflow/src/workflow/index.mjs +1723 -0
  556. package/packages/apra-fleet-workflow/src/workflow/journal.mjs +291 -0
  557. package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +99 -0
  558. package/packages/apra-fleet-workflow/src/workflow/vetting.mjs +111 -0
  559. package/scripts/agy-transcript-reader.js +1 -0
  560. package/scripts/fleet-statusline.sh +17 -13
  561. package/skills/fleet/SKILL.md +37 -2
  562. package/skills/fleet/beads.md +14 -7
  563. package/skills/fleet/permissions.md +50 -0
  564. package/skills/fleet/profiles/base-dev.json +1 -0
  565. package/skills/fleet/profiles/base-reviewer.json +1 -0
  566. package/skills/fleet/profiles/node.json +2 -2
  567. package/version.json +1 -1
  568. package/scripts/agy-settings-merge.js +0 -27
  569. /package/{dist → packages/apra-fleet-se/apra-pm}/agents/_shared/GRAPH-SEMANTICS.md +0 -0
@@ -0,0 +1,857 @@
1
+ #!/usr/bin/env node
2
+ import { parseArgs } from 'node:util';
3
+ import path from 'node:path';
4
+ import { fileURLToPath, pathToFileURL } from 'node:url';
5
+ import fs from 'node:fs/promises';
6
+ import { existsSync, realpathSync } from 'node:fs';
7
+ import { FleetWorkflow } from '@apralabs/apra-fleet-workflow';
8
+ import { WorkflowEngine } from '@apralabs/apra-fleet-workflow/engine';
9
+ import { createDashboardViewer } from '@apralabs/apra-fleet-workflow/viewer';
10
+ import { StreamableHttpTransport } from '@apralabs/apra-fleet-client/transport';
11
+ import { McpClient } from '@apralabs/apra-fleet-client/client';
12
+ import { ApraFleet } from '@apralabs/apra-fleet-client';
13
+ import {
14
+ resolveFleetServerCommand as sharedResolveFleetServerCommand,
15
+ resolveFleetServerConnection as sharedResolveFleetServerConnection,
16
+ getServerInfoPath,
17
+ } from '@apralabs/apra-fleet-client/server-resolution';
18
+ import { beadsExtension } from '../fleet-sprint/viewer-extensions.mjs';
19
+ import { validateIssueId, validateBranchName, checkMemberTopology, createMemberReservationClient } from '../fleet-sprint/runner.js';
20
+ import { normalizeRole } from '../fleet-sprint/contracts.mjs';
21
+
22
+ const __filename = fileURLToPath(import.meta.url);
23
+ const __dirname = path.dirname(__filename);
24
+
25
+ const DEFAULT_VIEWER_PORT = 8080;
26
+
27
+ /**
28
+ * Resolves the command used to launch the apra-fleet MCP server over
29
+ * stdio, layout-aware (apra-fleet-3ns.1) so it works whether this CLI is
30
+ * running dev-mode from a monorepo checkout or bundled as
31
+ * dist/fleet-sprint.mjs alongside the server's own dist/index.js
32
+ * (apra-fleet-3ns.2). Overridable via env for tests/CI/non-standard installs.
33
+ *
34
+ * THIN RE-EXPORT (docs/adr-workflow-server-resolution.md, Decision 2): the
35
+ * implementation now lives once in
36
+ * @apralabs/apra-fleet-client/server-resolution, shared with the
37
+ * `apra-fleet workflow` launcher (src/cli/workflow.ts) so the two can never
38
+ * drift. Name, signature, resolution tiers and error text are unchanged for
39
+ * existing callers/tests; only the default `dirname` is bound to this file's
40
+ * location (which is what the bundled/dev-monorepo tiers key off).
41
+ *
42
+ * Resolution order:
43
+ * 1. APRA_FLEET_SERVER_CMD -- an explicit full command + args string.
44
+ * 2. APRA_FLEET_SERVER_BIN -- an explicit server executable, resolved via
45
+ * PATH (not a literal file path, so no existsSync check applies).
46
+ * 3. <__dirname>/index.js -- the bundled layout.
47
+ * 4. <repoRoot>/dist/index.js -- the dev-monorepo layout.
48
+ *
49
+ * @param {{ env?: Record<string, string | undefined>, dirname?: string, exists?: (candidate: string) => boolean }} [deps]
50
+ * @returns {{ command: string, args: string[] }}
51
+ */
52
+ export function resolveFleetServerCommand(deps = {}) {
53
+ return sharedResolveFleetServerCommand({ dirname: __dirname, exists: existsSync, ...deps });
54
+ }
55
+
56
+ /**
57
+ * The full ADR resolution order (HTTP-singleton attach first, stdio self-spawn
58
+ * fallback) for callers that want it. This is exported so the resolution
59
+ * order has exactly one home.
60
+ *
61
+ * NOTE (apra-fleet-eft.7.1): fleet-sprint's own main() below calls this too,
62
+ * but treats anything other than `{ mode: 'http' }` as a hard failure -- see
63
+ * `FleetServerUnreachableError`. Plan Part 2.1 retired the per-invocation
64
+ * stdio self-spawn for cli.mjs specifically (it is now the supervisor's
65
+ * internal execution vehicle, launched once per sprint by the spawner), so
66
+ * the stdio branches this function can still return remain here only for
67
+ * other consumers (e.g. `apra-fleet workflow`) that intentionally allow them.
68
+ * @param {object} [deps]
69
+ */
70
+ export function resolveFleetServerConnection(deps = {}) {
71
+ return sharedResolveFleetServerConnection({ dirname: __dirname, exists: existsSync, ...deps });
72
+ }
73
+
74
+ /**
75
+ * Typed error thrown by main() (apra-fleet-eft.7.1) when no reachable fleet
76
+ * HTTP singleton is configured. cli.mjs deliberately does NOT fall back to
77
+ * self-spawning a stdio MCP server here -- under the service, every sprint
78
+ * child must share the one already-running fleet-server process, so a
79
+ * missing/unreachable singleton is a hard, explicit failure naming exactly
80
+ * what is missing rather than a silent private-server fallback.
81
+ */
82
+ export class FleetServerUnreachableError extends Error {
83
+ /**
84
+ * @param {string} message
85
+ * @param {{ code?: string, details?: object }} [opts]
86
+ */
87
+ constructor(message, { code, details } = {}) {
88
+ super(message);
89
+ this.name = 'FleetServerUnreachableError';
90
+ this.code = code || 'FLEET_SERVER_UNREACHABLE';
91
+ this.details = details;
92
+ }
93
+ }
94
+
95
+ /**
96
+ * Resolves the path to fleet-sprint's runner script, loaded at runtime via
97
+ * `engine.executeFile()` (NOT importable/bundlable -- it is read from disk
98
+ * and fed to the workflow engine as text). Layout-aware the same way as
99
+ * `resolveFleetServerCommand()` (apra-fleet-3ns.1): a bundled dist/auto-
100
+ * sprint.mjs ships this as a sibling dist asset (apra-fleet-3ns.2); a dev
101
+ * monorepo checkout resolves it relative to this file's own package tree.
102
+ * @param {{ dirname?: string, exists?: (candidate: string) => boolean }} [deps]
103
+ * @returns {string}
104
+ */
105
+ export function resolveRunnerScriptPath(deps = {}) {
106
+ const dirname = deps.dirname || __dirname;
107
+ const exists = deps.exists || existsSync;
108
+
109
+ const bundledRunnerAsset = path.join(dirname, 'fleet-sprint-runner.mjs');
110
+ const devRunnerPath = path.join(dirname, '../fleet-sprint/runner.js');
111
+
112
+ for (const candidate of [bundledRunnerAsset, devRunnerPath]) {
113
+ if (exists(candidate)) return candidate;
114
+ }
115
+
116
+ throw new Error(
117
+ '[apra-fleet-se] Could not locate the fleet-sprint runner script. Tried:\n' +
118
+ ` - ${bundledRunnerAsset} (bundled layout)\n` +
119
+ ` - ${devRunnerPath} (dev-monorepo layout)`,
120
+ );
121
+ }
122
+
123
+ /**
124
+ * The `node:util parseArgs` options spec for this CLI. Pulled out into its
125
+ * own function (rather than inlined in main()) so it is the single source of
126
+ * truth for both the real `parseArgs()` call and any test that needs to
127
+ * enumerate/exercise the supported flags.
128
+ * @returns {object}
129
+ */
130
+ export function buildOptionsSpec() {
131
+ return {
132
+ issue: { type: 'string', short: 'i' },
133
+ members: { type: 'string', short: 'm' },
134
+ branch: { type: 'string', short: 'b' },
135
+ base: { type: 'string', short: 'B' },
136
+ goal: { type: 'string', short: 'g', default: 'P1/P2' },
137
+ 'max-cycles': { type: 'string', short: 'c' },
138
+ 'allow-missing-members': { type: 'boolean' },
139
+ 'requirements-file': { type: 'string' },
140
+ 'role-map': { type: 'string' },
141
+ 'viewer-port': { type: 'string', default: String(DEFAULT_VIEWER_PORT) },
142
+ // apra-fleet-f34.1: the supervisor's own HTTP listen address, threaded
143
+ // in by src/supervisor/spawner.mjs's buildSprintArgv() when this CLI is
144
+ // launched as a supervisor-spawned child (see spawnSprint()). Optional
145
+ // -- when a sprint is launched directly (not via the supervisor), it is
146
+ // simply absent and runner.js falls back to its source-3 no-op clients
147
+ // exactly as before.
148
+ 'service-url': { type: 'string' },
149
+ // apra-fleet-k7b.1: the supervisor's own sprintId (ledger reservation
150
+ // key), threaded in by src/supervisor/spawner.mjs's buildSprintArgv()
151
+ // when this CLI is launched as a supervisor-spawned child. Used for
152
+ // the engine's run-state persistence (running/<id>.json ->
153
+ // old_runs/<id>.json) and dashboard viewer identity so relaunches on
154
+ // the same branch never overwrite prior run history. Optional --
155
+ // a direct/standalone CLI launch (no supervisor) falls back to
156
+ // --branch for this identity, exactly as before this flag existed.
157
+ 'run-id': { type: 'string' },
158
+ budget: { type: 'string' },
159
+ // Stabilization Issue 32: per-dispatch time budget in seconds
160
+ // (timeout_s == max_total_s at every dispatch; integ ceiling 2x).
161
+ 'dispatch-timeout-s': { type: 'string' },
162
+ // apra-fleet-eft.8.5: explicitly opt a multi-member run into synced
163
+ // topology mode (orchestrator-bracketed git sync -- same-origin +
164
+ // dolt-probe precondition, differing HEADs allowed). Omitted => legacy
165
+ // shared-workspace mode (same-HEAD). Mode is never inferred silently.
166
+ sync: { type: 'boolean' },
167
+ help: { type: 'boolean', short: 'h' },
168
+ };
169
+ }
170
+
171
+ const USAGE_TEXT = `
172
+ Usage: fleet-se sprint [options]
173
+
174
+ Options:
175
+ -i, --issue <ids> (REQUIRED) Target issue ID(s). Comma separated (e.g., epic-1,epic-2).
176
+ -m, --members <ids> (REQUIRED) Member IDs/names to use. Comma separated. Members act as repo targets for parallelism.
177
+ -b, --branch <name> (REQUIRED) Sprint branch to develop on (created from --base if it doesn't exist).
178
+ -B, --base <name> (REQUIRED) Base branch the sprint branch is created from and the eventual PR targets.
179
+ -g, --goal <goal> Sprint goal constraint. Options: P1, P1/P2, P1/P2/P3. Default: P1/P2.
180
+ -c, --max-cycles <n> Max plan/develop/review cycles. Default: 5.
181
+ --allow-missing-members Proceed (warn-and-continue) if some --members are not registered with the fleet.
182
+ Without this flag, any missing member aborts the sprint.
183
+ --requirements-file <p> Path to a requirements file threaded into the planner's prompt.
184
+ --role-map <json|@file> JSON object mapping role -> member[] (e.g. '{"doer":["m1","m2"]}'),
185
+ either inline JSON or '@path/to/file.json'.
186
+ --viewer-port <port> Port for the local dashboard viewer. Default: 8080.
187
+ --service-url <url> The supervisor's own HTTP service URL (e.g. http://localhost:8787),
188
+ enabling the HTTP-backed dolt-mutex/id-allocator clients. Normally
189
+ set automatically when the supervisor spawns this sprint; omit for
190
+ a directly-launched sprint (falls back to the no-op clients).
191
+ --run-id <id> Incarnation-unique run identity for engine run-state persistence
192
+ and the dashboard viewer (running/<id>.json -> old_runs/<id>.json).
193
+ Normally set automatically to the supervisor's sprintId when this
194
+ sprint is supervisor-spawned; omitted (direct/standalone launch)
195
+ falls back to --branch, exactly as before this flag existed.
196
+ --budget <usd> USD ceiling for this run's total estimated spend. Optional;
197
+ omitted (the default) means unlimited, identical to prior behavior.
198
+ --dispatch-timeout-s <s> Per-dispatch time budget in seconds (default 3600). Applied as both
199
+ the inactivity timeout and the hard ceiling on every agent dispatch
200
+ (the integration-test dispatch ceiling is 2x). Lower it for small
201
+ sprints so a hung dispatch costs minutes, not an hour. Minimum 60.
202
+ --sync Use synced topology mode (orchestrator-bracketed git sync):
203
+ members may sit on differing HEADs but must share the same
204
+ origin URL and pass a 'bd dolt pull' probe. Omitted (default)
205
+ uses legacy shared-workspace mode (all members on the same HEAD).
206
+ -h, --help Show this help message.
207
+ `.trim();
208
+
209
+ /**
210
+ * Parses argv with `strict: true` so an unrecognized/typo'd flag (e.g.
211
+ * `--max-cycle` instead of `--max-cycles`) fails loudly instead of being
212
+ * silently ignored with defaults applying (apra-fleet-unw2.16, N14 (a)).
213
+ * @param {string[]} argv - argv slice (no node/script entries), e.g. `process.argv.slice(2)`
214
+ * @returns {{ values: object, positionals: string[] }}
215
+ */
216
+ export function parseCliArgs(argv) {
217
+ try {
218
+ return parseArgs({ args: argv, options: buildOptionsSpec(), strict: true, allowPositionals: false });
219
+ } catch (err) {
220
+ throw new Error(
221
+ `Invalid command-line arguments: ${err.message}\n\n${USAGE_TEXT}`
222
+ );
223
+ }
224
+ }
225
+
226
+ /**
227
+ * Resolves `--role-map` into a plain object, supporting both inline JSON
228
+ * (`--role-map '{"doer":["m1"]}'`) and an `@path/to/file.json` indirection
229
+ * (`--role-map @role-map.json`), matching the read-and-parse pattern already
230
+ * used for `requirementsFile` content elsewhere in this package
231
+ * (fleet-sprint/runner.js reads requirementsFile content at sprint-start).
232
+ * @param {string|undefined} rawValue - the raw `--role-map` flag value
233
+ * @param {{ readFile?: (path: string, encoding: string) => Promise<string> }} [deps] - injectable for tests
234
+ * @returns {Promise<object|undefined>}
235
+ */
236
+ export async function resolveRoleMap(rawValue, deps = {}) {
237
+ if (rawValue === undefined) return undefined;
238
+ const readFile = deps.readFile || fs.readFile;
239
+
240
+ let jsonText = rawValue;
241
+ if (rawValue.startsWith('@')) {
242
+ const filePath = rawValue.slice(1);
243
+ try {
244
+ jsonText = await readFile(filePath, 'utf-8');
245
+ } catch (err) {
246
+ throw new Error(`Error: could not read --role-map file '${filePath}': ${err.message}`);
247
+ }
248
+ }
249
+
250
+ let parsed;
251
+ try {
252
+ parsed = JSON.parse(jsonText);
253
+ } catch (err) {
254
+ throw new Error(`Error: --role-map must be valid JSON (inline or @path/to/file.json): ${err.message}`);
255
+ }
256
+
257
+ if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
258
+ throw new Error('Error: --role-map JSON must be an object mapping role -> member[] (e.g. {"doer":["m1","m2"]}).');
259
+ }
260
+ for (const [role, members] of Object.entries(parsed)) {
261
+ if (!Array.isArray(members) || members.some((m) => typeof m !== 'string' || m.length === 0)) {
262
+ throw new Error(`Error: --role-map entry for role "${role}" must be a non-empty array of member-name strings.`);
263
+ }
264
+ }
265
+
266
+ // N15 (apra-fleet-unw2.11): normalize every key via
267
+ // contracts.normalizeRole() (trim + lowercase) HERE -- this is where
268
+ // roleMap keys first enter the system from a user-supplied
269
+ // `--role-map`/`@file.json` value, so callers of `resolveRoleMap()`
270
+ // (including this CLI's own pre-transport `orchestratorMember` lookup
271
+ // below, and runner.js's `validateArgs()`, which normalizes again
272
+ // defensively for callers that bypass the CLI and pass a raw roleMap
273
+ // straight to `engine.executeFile()`) can rely on keys already being in
274
+ // canonical lowercase form. This also covers the 'orchestrator'
275
+ // application-level pseudo-role key (see runner.js's ROLE_ORCHESTRATOR
276
+ // doc comment) -- it is not a vendored contracts.ROLES member but is
277
+ // still just a plain string key here, so the same normalization applies.
278
+ const normalized = {};
279
+ for (const [rawKey, members] of Object.entries(parsed)) {
280
+ const key = normalizeRole(rawKey);
281
+ if (Object.prototype.hasOwnProperty.call(normalized, key)) {
282
+ throw new Error(
283
+ `Error: --role-map key "${rawKey}" normalizes to "${key}", which collides with another key ` +
284
+ `already present in --role-map. Use a single casing/whitespace variant per role.`
285
+ );
286
+ }
287
+ normalized[key] = members;
288
+ }
289
+
290
+ return normalized;
291
+ }
292
+
293
+ /**
294
+ * Builds the exact args object handed to `engine.executeFile()`, i.e. the
295
+ * object `fleet-sprint/runner.js`'s `validateArgs()` consumes. Pulled into its
296
+ * own pure function so a test can assert `--requirements-file`/`--role-map`
297
+ * reach the runner's validated args correctly without standing up the fleet
298
+ * transport/workflow engine (apra-fleet-unw2.16, N14 (c)).
299
+ * @param {{
300
+ * targetIssues: string[], members: string[], branch: string, baseBranch: string,
301
+ * goal: string, maxCycles: number, requirementsFile: string|undefined, roleMap: object|undefined,
302
+ * budget: number|undefined,
303
+ * }} opts
304
+ * @returns {object}
305
+ */
306
+ export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goal, maxCycles, requirementsFile, roleMap, budget, dispatchTimeoutS, serviceUrl }) {
307
+ const args = {
308
+ target_issues: targetIssues,
309
+ members,
310
+ branch,
311
+ base_branch: baseBranch,
312
+ goal,
313
+ max_cycles: maxCycles,
314
+ };
315
+ if (requirementsFile !== undefined) args.requirementsFile = requirementsFile;
316
+ if (roleMap !== undefined) args.roleMap = roleMap;
317
+ if (budget !== undefined) args.budget = budget;
318
+ if (dispatchTimeoutS !== undefined) args.dispatch_timeout_s = dispatchTimeoutS;
319
+ // apra-fleet-f34.1: forwarded straight through to runner.js's validateArgs()
320
+ // (args.serviceUrl), which is what actually switches it onto the
321
+ // HTTP-backed dolt-mutex/id-allocator clients (fleet-sprint/runner.js
322
+ // ~5013-5052). Omitted when not supplied -- unchanged fallback behavior.
323
+ if (serviceUrl !== undefined) args.serviceUrl = serviceUrl;
324
+ return args;
325
+ }
326
+
327
+ /**
328
+ * Splits `--members` against the fleet's registered member names and decides
329
+ * whether the sprint may proceed.
330
+ *
331
+ * Before this issue, a missing configured member was only warned about and
332
+ * silently dropped -- shrinking the doer/reviewer pool without the user
333
+ * necessarily noticing. Now: any missing member ABORTS unless
334
+ * `--allow-missing-members` is explicitly passed, in which case the previous
335
+ * warn-and-continue behavior is preserved (apra-fleet-unw2.16, N14 (b)).
336
+ * @param {{ rawMembers: string[], registeredNames: Set<string>, allowMissingMembers: boolean }} opts
337
+ * @returns {{ ok: boolean, validMembers: string[], missingMembers: string[], message: string|null }}
338
+ */
339
+ export function resolveMemberValidation({ rawMembers, registeredNames, allowMissingMembers }) {
340
+ const validMembers = [];
341
+ const missingMembers = [];
342
+ for (const m of rawMembers) {
343
+ if (registeredNames.has(m)) validMembers.push(m);
344
+ else missingMembers.push(m);
345
+ }
346
+
347
+ if (validMembers.length === 0) {
348
+ return {
349
+ ok: false,
350
+ validMembers,
351
+ missingMembers,
352
+ message: `Error: All specified members are missing or invalid: ${rawMembers.join(', ')}`,
353
+ };
354
+ }
355
+
356
+ if (missingMembers.length > 0 && !allowMissingMembers) {
357
+ return {
358
+ ok: false,
359
+ validMembers,
360
+ missingMembers,
361
+ message:
362
+ `Error: The following configured members are missing from the fleet: ${missingMembers.join(', ')}. ` +
363
+ `Refusing to silently shrink the doer/reviewer pool. Pass --allow-missing-members to proceed with ` +
364
+ `only the remaining member(s) (${validMembers.join(', ')}).`,
365
+ };
366
+ }
367
+
368
+ const message = missingMembers.length > 0
369
+ ? `Warning: The following members are missing and will be ignored: ${missingMembers.join(', ')}`
370
+ : null;
371
+
372
+ return { ok: true, validMembers, missingMembers, message };
373
+ }
374
+
375
+ /**
376
+ * Verifies every target issue exists, run on the ORCHESTRATOR MEMBER via the
377
+ * fleet transport (`runBdShow`) -- NOT on the local machine. The sprint's own
378
+ * `bd` commands run against the orchestrator member's beads DB (see
379
+ * fleet-sprint/runner.js's SUPPORTED-TOPOLOGY NOTE), which can be a different
380
+ * database than whatever is local to wherever this CLI process happens to
381
+ * run. Checking locally could pass (or worse, resolve a same-named-but-
382
+ * different issue) while the actual sprint dispatch on the member fails
383
+ * (apra-fleet-unw2.16, N14 (d)). This runs AFTER the fleet transport/
384
+ * `initialize` handshake is established and BEFORE any sprint phase begins.
385
+ * @param {{ targetIssues: string[], member: string, runBdShow: (id: string, member: string) => Promise<{ isError?: boolean, content?: Array<{text: string}> }> }} opts
386
+ * @returns {Promise<{ ok: boolean, missing: string[], message: string }>}
387
+ */
388
+ export async function checkIssuesExistOnMember({ targetIssues, member, runBdShow }) {
389
+ const missing = [];
390
+ for (const id of targetIssues) {
391
+ try {
392
+ const res = await runBdShow(id, member);
393
+ if (res && res.isError) {
394
+ missing.push(id);
395
+ }
396
+ } catch (err) {
397
+ missing.push(id);
398
+ }
399
+ }
400
+ if (missing.length > 0) {
401
+ return {
402
+ ok: false,
403
+ missing,
404
+ message: `Error: The following target issues are missing from the database on member '${member}': ${missing.join(', ')}`,
405
+ };
406
+ }
407
+ return {
408
+ ok: true,
409
+ missing: [],
410
+ message: `[Precondition] All ${targetIssues.length} target issue(s) verified present on member '${member}'.`,
411
+ };
412
+ }
413
+
414
+ /**
415
+ * Formats a clean, actionable message for a viewer `server.listen()`
416
+ * failure -- in particular a port collision (EADDRINUSE) -- instead of
417
+ * letting it surface as an unhandled 'error' event / uncaught crash before
418
+ * the sprint even starts (apra-fleet-unw2.16, N14 (e)).
419
+ * @param {number} port
420
+ * @param {NodeJS.ErrnoException} err
421
+ * @returns {string}
422
+ */
423
+ export function formatViewerListenError(port, err) {
424
+ if (err && err.code === 'EADDRINUSE') {
425
+ return `viewer port ${port} is already in use, try --viewer-port <other port>.`;
426
+ }
427
+ return `viewer server error: ${err && err.message ? err.message : String(err)}`;
428
+ }
429
+
430
+ /**
431
+ * Attaches an `error` listener to the dashboard viewer's http.Server so a
432
+ * `server.listen()` failure (most commonly a port collision) reports a
433
+ * clean, actionable message via `onError` instead of an unhandled 'error'
434
+ * event crashing the process.
435
+ * @param {import('http').Server} server
436
+ * @param {number} port
437
+ * @param {{ onError?: (message: string, err: NodeJS.ErrnoException) => void }} [opts]
438
+ * @returns {import('http').Server}
439
+ */
440
+ export function attachViewerErrorHandler(server, port, opts = {}) {
441
+ server.on('error', (err) => {
442
+ const message = formatViewerListenError(port, err);
443
+ if (typeof opts.onError === 'function') opts.onError(message, err);
444
+ });
445
+ return server;
446
+ }
447
+
448
+ async function main() {
449
+ const { values } = parseCliArgs(process.argv.slice(2));
450
+
451
+ if (values.help) {
452
+ console.log(USAGE_TEXT);
453
+ process.exit(0);
454
+ }
455
+
456
+ const missing = [];
457
+ if (!values.issue) missing.push('--issue');
458
+ if (!values.members) missing.push('--members');
459
+ if (!values.branch) missing.push('--branch');
460
+ if (!values.base) missing.push('--base');
461
+
462
+ if (missing.length > 0) {
463
+ console.error(`Error: Missing required flags: ${missing.join(', ')}`);
464
+ process.exit(1);
465
+ }
466
+
467
+ // Split and clean comma-separated lists
468
+ const targetIssues = values.issue.split(',').map(s => s.trim()).filter(Boolean);
469
+ const rawMembers = values.members.split(',').map(s => s.trim()).filter(Boolean);
470
+ const branchName = values.branch;
471
+ const baseBranch = values.base;
472
+ const goal = values.goal;
473
+ const maxCycles = values['max-cycles'] !== undefined ? Number(values['max-cycles']) : 5;
474
+ const allowMissingMembers = Boolean(values['allow-missing-members']);
475
+ const requirementsFile = values['requirements-file'];
476
+ const viewerPort = values['viewer-port'] !== undefined ? Number(values['viewer-port']) : DEFAULT_VIEWER_PORT;
477
+ const serviceUrl = values['service-url'];
478
+ const budget = values.budget !== undefined ? Number(values.budget) : undefined;
479
+ // apra-fleet-k7b.1: prefer the supervisor-forwarded --run-id (this
480
+ // launch's incarnation-unique identity); fall back to the branch name
481
+ // for a direct/standalone CLI launch, which has no supervisor sprintId
482
+ // (unchanged pre-existing behavior in that case).
483
+ const effectiveRunId = values['run-id'] || branchName;
484
+ const dispatchTimeoutS = values['dispatch-timeout-s'] !== undefined ? Number(values['dispatch-timeout-s']) : undefined;
485
+
486
+ // --- A7 defense-in-depth: reject shell-unsafe issue ids / branch names
487
+ // BEFORE any bd/fleet dispatch happens. runner.js re-validates these
488
+ // independently (see fleet-sprint/runner.js validateArgs()) so a
489
+ // malformed id can never reach a shell command even if this CLI layer
490
+ // is somehow bypassed -- both layers share the exact same validators
491
+ // (imported from runner.js) so there is a single source of truth.
492
+ let roleMap;
493
+ try {
494
+ targetIssues.forEach(validateIssueId);
495
+ validateBranchName(branchName, 'branch');
496
+ validateBranchName(baseBranch, 'base');
497
+ roleMap = await resolveRoleMap(values['role-map']);
498
+ } catch (err) {
499
+ console.error(`Error: ${err.message}`);
500
+ process.exit(1);
501
+ }
502
+
503
+ if (!Number.isInteger(maxCycles) || maxCycles < 1) {
504
+ console.error(`Error: --max-cycles must be a positive integer, got "${values['max-cycles']}".`);
505
+ process.exit(1);
506
+ }
507
+
508
+ if (!Number.isInteger(viewerPort) || viewerPort < 1 || viewerPort > 65535) {
509
+ console.error(`Error: --viewer-port must be a valid TCP port number, got "${values['viewer-port']}".`);
510
+ process.exit(1);
511
+ }
512
+
513
+ // --budget is optional; omitted means unlimited (runner.js's validateArgs
514
+ // leaves context.budget.total as null in that case). When passed, reject
515
+ // non-numeric/negative values here at the CLI layer with a clear error,
516
+ // consistent with the strict-parsing conventions established for
517
+ // --max-cycles/--viewer-port above (apra-fleet-unw2.16, N14 (a)) -- this
518
+ // mirrors, but does not duplicate/conflict with, runner.js validateArgs's
519
+ // own budget check (non-negative finite number; see N10, apra-fleet-unw2.8).
520
+ if (dispatchTimeoutS !== undefined && (!Number.isInteger(dispatchTimeoutS) || dispatchTimeoutS < 60)) {
521
+ console.error(`Error: --dispatch-timeout-s must be an integer >= 60 (seconds), got "${values['dispatch-timeout-s']}".`);
522
+ process.exit(1);
523
+ }
524
+
525
+ if (budget !== undefined && (!Number.isFinite(budget) || budget < 0)) {
526
+ console.error(`Error: --budget must be a non-negative finite number (USD ceiling), got "${values.budget}".`);
527
+ process.exit(1);
528
+ }
529
+
530
+ // --- Precondition Validations ---
531
+
532
+ // 1. Attach to the fleet MCP transport FIRST, so member validation, the
533
+ // "bd show" issue precondition (below), and the sprint itself all run
534
+ // against the same live client/connection -- and so the issue
535
+ // precondition can target the orchestrator MEMBER rather than the local
536
+ // machine (apra-fleet-unw2.16, N14 (d): the sprint's own `bd` commands
537
+ // run on the member via the fleet transport, which can be a different
538
+ // database than whatever is local to this CLI process).
539
+ //
540
+ // apra-fleet-eft.7.1 (Plan Part 2.1 TRANSPORT decision): no per-sprint
541
+ // stdio MCP transport. cli.mjs is now the supervisor's internal execution
542
+ // vehicle -- every child it runs as (one per concurrent sprint) must
543
+ // attach to the EXISTING fleet singleton over streamable HTTP via
544
+ // resolveFleetServerConnection() rather than each spawning its own
545
+ // fleet-server process. If no reachable HTTP singleton is configured,
546
+ // fail fast with a typed error naming the missing connection config --
547
+ // silently self-spawning a private stdio server here would defeat the
548
+ // whole point of sharing one fleet-server connection across N children.
549
+ const connection = await resolveFleetServerConnection();
550
+ if (connection.mode !== 'http') {
551
+ const err = new FleetServerUnreachableError(
552
+ 'No reachable apra-fleet HTTP singleton was found. cli.mjs no longer ' +
553
+ 'self-spawns a per-invocation stdio MCP server (Plan Part 2.1) -- ' +
554
+ `resolution said: "${connection.reason}". Start the fleet server ` +
555
+ "('apra-fleet start' or 'apra-fleet install'), or check " +
556
+ `${getServerInfoPath()} (pid alive + GET /health) and the ` +
557
+ 'APRA_FLEET_TRANSPORT / APRA_FLEET_SERVER_CMD / APRA_FLEET_SERVER_BIN ' +
558
+ 'env vars for a stray override forcing stdio.',
559
+ { code: 'FLEET_SERVER_UNREACHABLE', details: { reason: connection.reason, mode: connection.mode } },
560
+ );
561
+ console.error(`Error: ${err.message}`);
562
+ process.exit(1);
563
+ return;
564
+ }
565
+ const transport = new StreamableHttpTransport(connection.url);
566
+ await transport.start();
567
+ const mcpClient = new McpClient(transport);
568
+
569
+ const fleetApi = new ApraFleet(mcpClient);
570
+
571
+ // 2. Validate members exist via the fleet's list_members tool.
572
+ let validMembers = [];
573
+ try {
574
+ const listRes = await fleetApi.listMembers({ format: 'json' });
575
+ const text = listRes && listRes.content && listRes.content[0] ? listRes.content[0].text : JSON.stringify(listRes);
576
+ const parsed = JSON.parse(text);
577
+ const registeredNames = new Set((parsed.members || []).map(m => m.name));
578
+ const result = resolveMemberValidation({ rawMembers, registeredNames, allowMissingMembers });
579
+ if (!result.ok) {
580
+ console.error(result.message);
581
+ transport.stop();
582
+ process.exit(1);
583
+ }
584
+ if (result.message) console.warn(result.message);
585
+ validMembers = result.validMembers;
586
+ } catch (err) {
587
+ console.error(`Error: Failed to list fleet members: ${err.message}`);
588
+ transport.stop();
589
+ process.exit(1);
590
+ }
591
+
592
+ // 3. bd show issue precondition -- run on the orchestrator MEMBER via the
593
+ // fleet transport (apra-fleet-unw2.16, N14 (d)), immediately after the
594
+ // transport/initialize handshake above and before any sprint phase
595
+ // begins. The orchestrator member mirrors fleet-sprint/runner.js's
596
+ // `getMemberForRole(ROLE_ORCHESTRATOR)` resolution: roleMap.orchestrator[0]
597
+ // if configured, else the first valid member. `roleMap` here is already
598
+ // key-normalized by `resolveRoleMap()` above (N15, apra-fleet-unw2.11),
599
+ // so the canonical lowercase 'orchestrator' key is the only one that can
600
+ // be present -- this must NOT read a capitalized 'Orchestrator' key (the
601
+ // N15 finding: that stray casing silently never matched a roleMap
602
+ // author's natural lowercase key).
603
+ const orchestratorMember = (roleMap && roleMap.orchestrator && roleMap.orchestrator[0]) || validMembers[0];
604
+ const issueCheck = await checkIssuesExistOnMember({
605
+ targetIssues,
606
+ member: orchestratorMember,
607
+ runBdShow: async (id, member) => fleetApi.executeCommand({ command: `bd show ${id}`, member_name: member }),
608
+ });
609
+ if (!issueCheck.ok) {
610
+ console.error(issueCheck.message);
611
+ transport.stop();
612
+ process.exit(1);
613
+ }
614
+
615
+ // 4. N4 (apra-fleet-unw2.4) multi-member topology precondition.
616
+ //
617
+ // LEGACY mode (default): the runner's cross-member coherence relies on
618
+ // every member sharing one workspace/DB -- every orchestrator-side `bd`
619
+ // command runs against the orchestrator member's beads DB, and the sprint
620
+ // git branch is only coherent if every member operates on the same working
621
+ // state. Enforce that by comparing `git rev-parse HEAD` across members and
622
+ // refusing to start on a mismatch.
623
+ //
624
+ // SYNCED mode (apra-fleet-eft.8.5, `--sync`): with the orchestrator-
625
+ // bracketed git sync layer, members are reconciled per-dispatch by
626
+ // fast-forward pull/push, so differing HEADs are expected and allowed. The
627
+ // precondition instead requires every member to share the same `git remote
628
+ // get-url origin` AND pass a `bd dolt pull` probe. Mode is chosen
629
+ // EXPLICITLY here (never inferred). Single-member trivially passes in
630
+ // either mode.
631
+ const syncedMode = Boolean(values.sync);
632
+ const runCommand = async (cmd, member) => {
633
+ const res = await fleetApi.executeCommand({ command: cmd, member_name: member });
634
+ if (res && res.isError) {
635
+ const errText = res.content && res.content[0] ? res.content[0].text : 'unknown error';
636
+ throw new Error(errText);
637
+ }
638
+ return res && res.content && res.content[0] ? res.content[0].text : '';
639
+ };
640
+ const topology = await checkMemberTopology({
641
+ members: validMembers,
642
+ mode: syncedMode ? 'synced' : 'legacy',
643
+ getIdentity: (member) => runCommand('git rev-parse HEAD', member),
644
+ getOriginUrl: (member) => runCommand('git remote get-url origin', member),
645
+ doltProbe: (member) => runCommand('bd dolt pull', member),
646
+ });
647
+ if (!topology.ok) {
648
+ console.error(`Error: ${topology.message}`);
649
+ transport.stop();
650
+ process.exit(1);
651
+ }
652
+ if (!topology.singleMember) {
653
+ console.log(topology.message);
654
+ }
655
+
656
+ console.log('Starting Auto-Sprint');
657
+ console.log(`Target Issues: ${targetIssues.join(', ')}`);
658
+ console.log(`Sprint Branch: ${branchName} (Base: ${baseBranch})`);
659
+ console.log(`Goal Constraint: ${goal}`);
660
+ console.log(`Max Cycles: ${maxCycles}`);
661
+ console.log(`Active Members (${validMembers.length}): ${validMembers.join(', ')}`);
662
+
663
+ const workflow = new FleetWorkflow(fleetApi);
664
+ const engine = new WorkflowEngine(workflow);
665
+
666
+ const server = createDashboardViewer(workflow, {
667
+ port: viewerPort,
668
+ name: 'Fleet-Sprint',
669
+ dashboardExtensions: [beadsExtension],
670
+ // apra-fleet-eft.37.1/37.2: the core viewer now speaks opts.runId
671
+ // (opts.sprintId is a deprecated BOUNDARY-COMPAT alias -- never use
672
+ // it from here).
673
+ //
674
+ // apra-fleet-k7b.1: effectiveRunId prefers the supervisor-forwarded
675
+ // --run-id (that sprint's ledger-reservation sprintId, incarnation-
676
+ // unique) over branchName, so relaunches on the SAME branch get
677
+ // DISTINCT running/<id>.json -> old_runs/<id>.json engine run-state
678
+ // files instead of one relaunch silently overwriting the prior
679
+ // incarnation's history. A direct/standalone CLI launch (no
680
+ // supervisor, so no --run-id) falls back to branchName exactly as
681
+ // before this flag existed -- still the SAME opaque per-sprint
682
+ // identity used for member reservation (`sprintId: branchName`
683
+ // below) and the runner's own dolt-mutex/allocator stamping
684
+ // (sprintMutexId, fleet-sprint/runner.js).
685
+ runId: effectiveRunId,
686
+ // BOUNDARY-COMPAT/user-facing convention (apra-fleet-eft.37.1): core's
687
+ // crash-net snapshot defaults are domain-neutral (workflow-logs/run_)
688
+ // now that sprintId->runId is renamed; auto-sprint keeps its historical
689
+ // sprint-logs/sprint_<HHMMSS>.json convention by passing these
690
+ // explicitly rather than picking up the new core defaults.
691
+ stateSnapshotDir: 'sprint-logs',
692
+ stateSnapshotPrefix: 'sprint_',
693
+ });
694
+
695
+ // apra-fleet-unw2.16, N14 (e): the viewer port was hardcoded with no
696
+ // `error` handler on `server.listen()`, so a port collision crashed the
697
+ // process uncleanly before the sprint even started. Report a clean,
698
+ // actionable message and exit instead.
699
+ let viewerFailed = false;
700
+ attachViewerErrorHandler(server, viewerPort, {
701
+ onError: (message) => {
702
+ viewerFailed = true;
703
+ console.error(`Error: ${message}`);
704
+ transport.stop();
705
+ process.exit(1);
706
+ },
707
+ });
708
+
709
+ console.log(`Dashboard live at http://localhost:${viewerPort}`);
710
+
711
+ if (viewerFailed) return; // process.exit already called synchronously above
712
+
713
+ // apra-fleet-eft.26.1 (Reservation interop gap, Hole 1): a sprint
714
+ // launched directly through this CLI (never routed through the
715
+ // supervisor's POST /api/sprints) never reserved its members
716
+ // server-side, so it was invisible to any interop -- neither the
717
+ // supervisor's overlap guard (eft.26.2) nor execute_prompt's
718
+ // dispatch-time reservedBy check (eft.10.3) had anything to consult.
719
+ // Reserve every member now, on the SAME opaque sprint id runner.js uses
720
+ // for the dolt-mutex/allocator (the sprint branch name), and release on
721
+ // EVERY exit path below: normal success, a caught failure/stall-abort,
722
+ // or SIGINT.
723
+ const sprintReservation = createMemberReservationClient({
724
+ callTool: (name, args) => mcpClient.callTool(name, args),
725
+ members: validMembers,
726
+ sprintId: branchName,
727
+ log: (msg) => console.log(msg),
728
+ });
729
+ await sprintReservation.reserveAll();
730
+
731
+ let reservationReleased = false;
732
+ const releaseReservationOnce = async () => {
733
+ if (reservationReleased) return;
734
+ reservationReleased = true;
735
+ await sprintReservation.releaseAll();
736
+ };
737
+ // Ctrl-C during an in-flight sprint previously had no handler at all (Node's
738
+ // default: immediate termination, no cleanup). Registering one here is what
739
+ // makes a released-on-SIGINT reservation possible; it is removed again
740
+ // (below) the instant the sprint settles so it can never fire during --
741
+ // or short-circuit -- the unrelated post-failure grace-window SIGINT
742
+ // listener registered further down in the catch branch.
743
+ const onSigint = () => {
744
+ releaseReservationOnce()
745
+ .catch((err) => console.error('[member-reservation] release-on-SIGINT failed:', err))
746
+ .finally(() => process.exit(130));
747
+ };
748
+ process.once('SIGINT', onSigint);
749
+
750
+ try {
751
+ const scriptPath = resolveRunnerScriptPath();
752
+ const res = await engine.executeFile(scriptPath, {
753
+ ...buildRunnerArgs({
754
+ targetIssues,
755
+ members: validMembers,
756
+ branch: branchName,
757
+ baseBranch,
758
+ goal,
759
+ maxCycles,
760
+ requirementsFile,
761
+ roleMap,
762
+ budget,
763
+ dispatchTimeoutS,
764
+ serviceUrl,
765
+ }),
766
+ // apra-fleet-eft.75.1: wires this already-connected mcpClient
767
+ // through to runner.js's createMemberSessionGuard (see its doc
768
+ // comment), so a resume re-dispatch after a presumed-dead/timed-
769
+ // out session (max_turns_exhausted) calls the fleet's own
770
+ // stop_prompt tool for that member FIRST -- verifying/killing a
771
+ // still-alive prior process before spawning a second one.
772
+ // Mirrors createMemberReservationClient's callTool wiring above.
773
+ callTool: (name, toolArgs) => mcpClient.callTool(name, toolArgs),
774
+ });
775
+ process.removeListener('SIGINT', onSigint);
776
+ await releaseReservationOnce();
777
+ console.log('Sprint finished:', res);
778
+ server.close();
779
+ transport.stop();
780
+ process.exit(0);
781
+ } catch (err) {
782
+ process.removeListener('SIGINT', onSigint);
783
+ await releaseReservationOnce();
784
+ // apra-fleet-xbu.4: a caught sprint-level failure (Planner retries
785
+ // exhausted, a StalledSprintError, pre-sprint validation, etc.) used
786
+ // to tear the dashboard server down in the same tick as the error --
787
+ // the one moment an operator most needs to see the FAILED state and
788
+ // read why, the dashboard became unreachable. This is a legitimate,
789
+ // fully-handled outcome, not a crash: the dashboard has no reason to
790
+ // die with it. Keep the server up for a bounded grace window so
791
+ // `http://localhost:<port>` stays inspectable, then exit -- SIGINT
792
+ // (Ctrl-C) or the grace window elapsing both end it; this is not an
793
+ // indefinite hang.
794
+ console.error('Sprint failed:', err);
795
+ process.exitCode = 1;
796
+ const graceMs = Number(process.env.AUTO_SPRINT_FAILURE_GRACE_MS ?? 5 * 60 * 1000);
797
+ if (graceMs > 0) {
798
+ console.log(
799
+ `Sprint FAILED. Dashboard remains live at http://localhost:${viewerPort} for ` +
800
+ `${Math.round(graceMs / 1000)}s so you can inspect the final state -- press Ctrl-C to exit sooner.`
801
+ );
802
+ await new Promise((resolve) => {
803
+ const timer = setTimeout(resolve, graceMs);
804
+ timer.unref?.();
805
+ process.once('SIGINT', () => {
806
+ clearTimeout(timer);
807
+ resolve();
808
+ });
809
+ });
810
+ }
811
+ server.close();
812
+ transport.stop();
813
+ process.exit(process.exitCode || 1);
814
+ }
815
+ }
816
+
817
+ function isMainModule() {
818
+ try {
819
+ if (process.argv[1] === undefined) return false;
820
+ const invokedUrl = pathToFileURL(process.argv[1]).href;
821
+ const moduleUrl = import.meta.url;
822
+ if (moduleUrl === invokedUrl) return true;
823
+
824
+ // On macOS, `mktemp -d` returns a path under /var/folders/... which is
825
+ // actually a symlink to /private/var/.... Node's ESM loader
826
+ // canonicalizes import.meta.url to the REAL path, but process.argv[1]
827
+ // is left un-canonicalized, so the raw URL comparison above can fail
828
+ // even though both paths point at the same file, silently skipping
829
+ // the self-executing block below (apra-fleet-eft.41.1). Fall back to
830
+ // comparing realpath'd paths on both sides; wrap in try/catch and
831
+ // fall back to "not main" (matching the already-failed raw
832
+ // comparison) if realpath fails for either side (e.g. ENOENT).
833
+ try {
834
+ const realInvokedUrl = pathToFileURL(realpathSync(process.argv[1])).href;
835
+ const realModuleUrl = pathToFileURL(realpathSync(fileURLToPath(moduleUrl))).href;
836
+ return realInvokedUrl === realModuleUrl;
837
+ } catch {
838
+ return false;
839
+ }
840
+ } catch {
841
+ return false;
842
+ }
843
+ }
844
+
845
+ // Declare the launcher contract (apra-fleet workflow imports this file and
846
+ // checks the flag after import): main() runs asynchronously, so without this
847
+ // declaration the launcher's non-executing backstop (apra-fleet-eft.41.2)
848
+ // cannot tell "started async" from "did nothing", fails loud, and its exit(1)
849
+ // kills the just-started sprint.
850
+ export const selfExecuting = true;
851
+
852
+ if (isMainModule()) {
853
+ main().catch(err => {
854
+ console.error(err);
855
+ process.exit(1);
856
+ });
857
+ }