@apralabs/apra-fleet 0.4.0 → 0.4.2

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 (548) hide show
  1. package/README.md +159 -13
  2. package/dist/agents/backlog-groomer.md +31 -19
  3. package/dist/agents/ci-watcher.md +16 -1
  4. package/dist/agents/deployer.md +37 -47
  5. package/dist/agents/doer.md +147 -114
  6. package/dist/agents/harvester.md +41 -34
  7. package/dist/agents/integ-test-runner.md +98 -114
  8. package/dist/agents/kb-reconciler.md +205 -0
  9. package/dist/agents/plan-reviewer.md +45 -44
  10. package/dist/agents/planner.md +121 -50
  11. package/dist/agents/regression-test-runner.md +84 -81
  12. package/dist/agents/reviewer.md +118 -44
  13. package/dist/agents/schemas/doer-output.json +63 -3
  14. package/dist/agents/schemas/harvester-output.json +59 -2
  15. package/dist/agents/schemas/integ-test-runner-output.json +3 -3
  16. package/dist/agents/schemas/kb-reconciler-output.json +87 -0
  17. package/dist/agents/schemas/planner-output.json +65 -0
  18. package/dist/agents/schemas/regression-test-runner-output.json +4 -17
  19. package/dist/agents/schemas/reviewer-output.json +105 -8
  20. package/dist/cli/auth.d.ts.map +1 -1
  21. package/dist/cli/auth.js +1 -2
  22. package/dist/cli/auth.js.map +1 -1
  23. package/dist/cli/config.d.ts +3 -3
  24. package/dist/cli/config.d.ts.map +1 -1
  25. package/dist/cli/config.js +4 -13
  26. package/dist/cli/config.js.map +1 -1
  27. package/dist/cli/install.d.ts +1 -0
  28. package/dist/cli/install.d.ts.map +1 -1
  29. package/dist/cli/install.js +141 -44
  30. package/dist/cli/install.js.map +1 -1
  31. package/dist/cli/join.js +1 -1
  32. package/dist/cli/join.js.map +1 -1
  33. package/dist/cli/kb-commit.d.ts +12 -0
  34. package/dist/cli/kb-commit.d.ts.map +1 -0
  35. package/dist/cli/kb-commit.js +53 -0
  36. package/dist/cli/kb-commit.js.map +1 -0
  37. package/dist/cli/kb-directives.d.ts +17 -0
  38. package/dist/cli/kb-directives.d.ts.map +1 -0
  39. package/dist/cli/kb-directives.js +146 -0
  40. package/dist/cli/kb-directives.js.map +1 -0
  41. package/dist/cli/kb-import.d.ts +13 -0
  42. package/dist/cli/kb-import.d.ts.map +1 -0
  43. package/dist/cli/kb-import.js +56 -0
  44. package/dist/cli/kb-import.js.map +1 -0
  45. package/dist/cli/register-member.js +1 -1
  46. package/dist/cli/start.d.ts.map +1 -1
  47. package/dist/cli/start.js +7 -0
  48. package/dist/cli/start.js.map +1 -1
  49. package/dist/cli/uninstall.d.ts.map +1 -1
  50. package/dist/cli/uninstall.js +16 -3
  51. package/dist/cli/uninstall.js.map +1 -1
  52. package/dist/cli/watch.d.ts +76 -4
  53. package/dist/cli/watch.d.ts.map +1 -1
  54. package/dist/cli/watch.js +150 -17
  55. package/dist/cli/watch.js.map +1 -1
  56. package/dist/commands/kb-server.d.ts +8 -0
  57. package/dist/commands/kb-server.d.ts.map +1 -0
  58. package/dist/commands/kb-server.js +221 -0
  59. package/dist/commands/kb-server.js.map +1 -0
  60. package/dist/index.js +77 -2
  61. package/dist/index.js.map +1 -1
  62. package/dist/os/git-bash-candidates.d.ts +35 -0
  63. package/dist/os/git-bash-candidates.d.ts.map +1 -0
  64. package/dist/os/git-bash-candidates.js +46 -0
  65. package/dist/os/git-bash-candidates.js.map +1 -0
  66. package/dist/os/index.d.ts +13 -4
  67. package/dist/os/index.d.ts.map +1 -1
  68. package/dist/os/index.js +17 -2
  69. package/dist/os/index.js.map +1 -1
  70. package/dist/os/linux.d.ts +1 -0
  71. package/dist/os/linux.d.ts.map +1 -1
  72. package/dist/os/linux.js +19 -2
  73. package/dist/os/linux.js.map +1 -1
  74. package/dist/os/os-commands.d.ts +12 -0
  75. package/dist/os/os-commands.d.ts.map +1 -1
  76. package/dist/os/os-commands.js.map +1 -1
  77. package/dist/os/windows-gitbash.d.ts +93 -0
  78. package/dist/os/windows-gitbash.d.ts.map +1 -0
  79. package/dist/os/windows-gitbash.js +244 -0
  80. package/dist/os/windows-gitbash.js.map +1 -0
  81. package/dist/os/windows.d.ts +35 -0
  82. package/dist/os/windows.d.ts.map +1 -1
  83. package/dist/os/windows.js +93 -35
  84. package/dist/os/windows.js.map +1 -1
  85. package/dist/providers/agy.d.ts +15 -3
  86. package/dist/providers/agy.d.ts.map +1 -1
  87. package/dist/providers/agy.js +145 -11
  88. package/dist/providers/agy.js.map +1 -1
  89. package/dist/providers/claude.d.ts +14 -3
  90. package/dist/providers/claude.d.ts.map +1 -1
  91. package/dist/providers/claude.js +69 -22
  92. package/dist/providers/claude.js.map +1 -1
  93. package/dist/providers/codex.d.ts +14 -3
  94. package/dist/providers/codex.d.ts.map +1 -1
  95. package/dist/providers/codex.js +34 -8
  96. package/dist/providers/codex.js.map +1 -1
  97. package/dist/providers/copilot.d.ts +14 -3
  98. package/dist/providers/copilot.d.ts.map +1 -1
  99. package/dist/providers/copilot.js +33 -8
  100. package/dist/providers/copilot.js.map +1 -1
  101. package/dist/providers/email/headers.d.ts +15 -0
  102. package/dist/providers/email/headers.d.ts.map +1 -0
  103. package/dist/providers/email/headers.js +42 -0
  104. package/dist/providers/email/headers.js.map +1 -0
  105. package/dist/providers/email/index.d.ts +18 -0
  106. package/dist/providers/email/index.d.ts.map +1 -0
  107. package/dist/providers/email/index.js +60 -0
  108. package/dist/providers/email/index.js.map +1 -0
  109. package/dist/providers/email/provider.d.ts +49 -0
  110. package/dist/providers/email/provider.d.ts.map +1 -0
  111. package/dist/providers/email/provider.js +2 -0
  112. package/dist/providers/email/provider.js.map +1 -0
  113. package/dist/providers/email/sendgrid.d.ts +12 -0
  114. package/dist/providers/email/sendgrid.d.ts.map +1 -0
  115. package/dist/providers/email/sendgrid.js +67 -0
  116. package/dist/providers/email/sendgrid.js.map +1 -0
  117. package/dist/providers/email/smtp.d.ts +65 -0
  118. package/dist/providers/email/smtp.d.ts.map +1 -0
  119. package/dist/providers/email/smtp.js +373 -0
  120. package/dist/providers/email/smtp.js.map +1 -0
  121. package/dist/providers/index.d.ts +0 -1
  122. package/dist/providers/index.d.ts.map +1 -1
  123. package/dist/providers/index.js +0 -3
  124. package/dist/providers/index.js.map +1 -1
  125. package/dist/providers/none.d.ts +14 -3
  126. package/dist/providers/none.d.ts.map +1 -1
  127. package/dist/providers/none.js +26 -2
  128. package/dist/providers/none.js.map +1 -1
  129. package/dist/providers/opencode.d.ts +14 -3
  130. package/dist/providers/opencode.d.ts.map +1 -1
  131. package/dist/providers/opencode.js +60 -6
  132. package/dist/providers/opencode.js.map +1 -1
  133. package/dist/providers/provider.d.ts +91 -5
  134. package/dist/providers/provider.d.ts.map +1 -1
  135. package/dist/providers/provider.js +45 -1
  136. package/dist/providers/provider.js.map +1 -1
  137. package/dist/services/agent-provisioner.d.ts.map +1 -1
  138. package/dist/services/agent-provisioner.js +5 -8
  139. package/dist/services/agent-provisioner.js.map +1 -1
  140. package/dist/services/cloud/activity.js +2 -2
  141. package/dist/services/cloud/activity.js.map +1 -1
  142. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  143. package/dist/services/cloud/lifecycle.js +3 -0
  144. package/dist/services/cloud/lifecycle.js.map +1 -1
  145. package/dist/services/cloud/task-wrapper.d.ts +18 -0
  146. package/dist/services/cloud/task-wrapper.d.ts.map +1 -1
  147. package/dist/services/cloud/task-wrapper.js +157 -0
  148. package/dist/services/cloud/task-wrapper.js.map +1 -1
  149. package/dist/services/context-admission.d.ts.map +1 -1
  150. package/dist/services/context-admission.js +9 -7
  151. package/dist/services/context-admission.js.map +1 -1
  152. package/dist/services/credential-cleanup.d.ts.map +1 -1
  153. package/dist/services/credential-cleanup.js +22 -3
  154. package/dist/services/credential-cleanup.js.map +1 -1
  155. package/dist/services/github-app.d.ts.map +1 -1
  156. package/dist/services/github-app.js +11 -2
  157. package/dist/services/github-app.js.map +1 -1
  158. package/dist/services/knowledge/audn.d.ts +37 -0
  159. package/dist/services/knowledge/audn.d.ts.map +1 -0
  160. package/dist/services/knowledge/audn.js +219 -0
  161. package/dist/services/knowledge/audn.js.map +1 -0
  162. package/dist/services/knowledge/file-hash.d.ts +11 -0
  163. package/dist/services/knowledge/file-hash.d.ts.map +1 -0
  164. package/dist/services/knowledge/file-hash.js +123 -0
  165. package/dist/services/knowledge/file-hash.js.map +1 -0
  166. package/dist/services/knowledge/http-provider.d.ts +46 -0
  167. package/dist/services/knowledge/http-provider.d.ts.map +1 -0
  168. package/dist/services/knowledge/http-provider.js +254 -0
  169. package/dist/services/knowledge/http-provider.js.map +1 -0
  170. package/dist/services/knowledge/kb-providers.d.ts +15 -0
  171. package/dist/services/knowledge/kb-providers.d.ts.map +1 -0
  172. package/dist/services/knowledge/kb-providers.js +92 -0
  173. package/dist/services/knowledge/kb-providers.js.map +1 -0
  174. package/dist/services/knowledge/kb-scope-input.d.ts +5 -0
  175. package/dist/services/knowledge/kb-scope-input.d.ts.map +1 -0
  176. package/dist/services/knowledge/kb-scope-input.js +11 -0
  177. package/dist/services/knowledge/kb-scope-input.js.map +1 -0
  178. package/dist/services/knowledge/kb-service.d.ts +3 -0
  179. package/dist/services/knowledge/kb-service.d.ts.map +1 -0
  180. package/dist/services/knowledge/kb-service.js +2 -0
  181. package/dist/services/knowledge/kb-service.js.map +1 -0
  182. package/dist/services/knowledge/path-validation.d.ts +2 -0
  183. package/dist/services/knowledge/path-validation.d.ts.map +1 -0
  184. package/dist/services/knowledge/path-validation.js +13 -0
  185. package/dist/services/knowledge/path-validation.js.map +1 -0
  186. package/dist/services/knowledge/pre-init.d.ts +14 -0
  187. package/dist/services/knowledge/pre-init.d.ts.map +1 -0
  188. package/dist/services/knowledge/pre-init.js +147 -0
  189. package/dist/services/knowledge/pre-init.js.map +1 -0
  190. package/dist/services/knowledge/project-slug.d.ts +2 -0
  191. package/dist/services/knowledge/project-slug.d.ts.map +1 -0
  192. package/dist/services/knowledge/project-slug.js +49 -0
  193. package/dist/services/knowledge/project-slug.js.map +1 -0
  194. package/dist/services/knowledge/sqlite-provider.d.ts +147 -0
  195. package/dist/services/knowledge/sqlite-provider.d.ts.map +1 -0
  196. package/dist/services/knowledge/sqlite-provider.js +1646 -0
  197. package/dist/services/knowledge/sqlite-provider.js.map +1 -0
  198. package/dist/services/knowledge/types.d.ts +163 -0
  199. package/dist/services/knowledge/types.d.ts.map +1 -0
  200. package/dist/services/knowledge/types.js +9 -0
  201. package/dist/services/knowledge/types.js.map +1 -0
  202. package/dist/services/member-home.d.ts +89 -0
  203. package/dist/services/member-home.d.ts.map +1 -0
  204. package/dist/services/member-home.js +259 -0
  205. package/dist/services/member-home.js.map +1 -0
  206. package/dist/services/member-remote-url.d.ts +34 -0
  207. package/dist/services/member-remote-url.d.ts.map +1 -0
  208. package/dist/services/member-remote-url.js +39 -0
  209. package/dist/services/member-remote-url.js.map +1 -0
  210. package/dist/services/model-pricing.d.ts.map +1 -1
  211. package/dist/services/model-pricing.js +0 -5
  212. package/dist/services/model-pricing.js.map +1 -1
  213. package/dist/services/orphan-recovery.d.ts +9 -3
  214. package/dist/services/orphan-recovery.d.ts.map +1 -1
  215. package/dist/services/orphan-recovery.js +22 -8
  216. package/dist/services/orphan-recovery.js.map +1 -1
  217. package/dist/services/preflight-check.d.ts +56 -0
  218. package/dist/services/preflight-check.d.ts.map +1 -0
  219. package/dist/services/preflight-check.js +277 -0
  220. package/dist/services/preflight-check.js.map +1 -0
  221. package/dist/services/shell-probe.d.ts +131 -0
  222. package/dist/services/shell-probe.d.ts.map +1 -0
  223. package/dist/services/shell-probe.js +210 -0
  224. package/dist/services/shell-probe.js.map +1 -0
  225. package/dist/services/singleton.d.ts +2 -0
  226. package/dist/services/singleton.d.ts.map +1 -1
  227. package/dist/services/singleton.js +1 -1
  228. package/dist/services/singleton.js.map +1 -1
  229. package/dist/services/ssh.js +2 -2
  230. package/dist/services/ssh.js.map +1 -1
  231. package/dist/services/stall/find-log-file.d.ts.map +1 -1
  232. package/dist/services/stall/find-log-file.js +22 -16
  233. package/dist/services/stall/find-log-file.js.map +1 -1
  234. package/dist/services/stall/log-path-resolver.d.ts +11 -8
  235. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  236. package/dist/services/stall/log-path-resolver.js +17 -40
  237. package/dist/services/stall/log-path-resolver.js.map +1 -1
  238. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  239. package/dist/services/stall/read-log-tail.js +6 -5
  240. package/dist/services/stall/read-log-tail.js.map +1 -1
  241. package/dist/services/stall/stall-detector.d.ts +32 -0
  242. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  243. package/dist/services/stall/stall-detector.js +149 -6
  244. package/dist/services/stall/stall-detector.js.map +1 -1
  245. package/dist/services/stall/stall-poller.d.ts +34 -0
  246. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  247. package/dist/services/stall/stall-poller.js +160 -35
  248. package/dist/services/stall/stall-poller.js.map +1 -1
  249. package/dist/services/strategy.d.ts +9 -0
  250. package/dist/services/strategy.d.ts.map +1 -1
  251. package/dist/services/strategy.js +41 -7
  252. package/dist/services/strategy.js.map +1 -1
  253. package/dist/services/tool-registry.d.ts.map +1 -1
  254. package/dist/services/tool-registry.js +87 -1
  255. package/dist/services/tool-registry.js.map +1 -1
  256. package/dist/services/user-config.js +1 -1
  257. package/dist/services/user-config.js.map +1 -1
  258. package/dist/services/vcs/azure-devops.d.ts +1 -1
  259. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  260. package/dist/services/vcs/azure-devops.js +105 -10
  261. package/dist/services/vcs/azure-devops.js.map +1 -1
  262. package/dist/services/vcs/bitbucket.d.ts.map +1 -1
  263. package/dist/services/vcs/bitbucket.js +16 -0
  264. package/dist/services/vcs/bitbucket.js.map +1 -1
  265. package/dist/services/vcs/github.d.ts.map +1 -1
  266. package/dist/services/vcs/github.js +56 -1
  267. package/dist/services/vcs/github.js.map +1 -1
  268. package/dist/services/vcs/types.d.ts +123 -2
  269. package/dist/services/vcs/types.d.ts.map +1 -1
  270. package/dist/services/version-check.d.ts +22 -0
  271. package/dist/services/version-check.d.ts.map +1 -0
  272. package/dist/services/version-check.js +103 -0
  273. package/dist/services/version-check.js.map +1 -0
  274. package/dist/skills/fleet-sprint-cli/SKILL.md +15 -3
  275. package/dist/skills/pm/SKILL.md +0 -1
  276. package/dist/skills/pm/beads.md +6 -0
  277. package/dist/skills/pm/cost.md +0 -1
  278. package/dist/skills/pm/fleet-addendum.md +6 -1
  279. package/dist/skills/pm/index.md +56 -0
  280. package/dist/skills/pm/kb-reconcile.md +132 -0
  281. package/dist/skills/pm/kb-review.md +109 -0
  282. package/dist/tools/check-status.d.ts +47 -0
  283. package/dist/tools/check-status.d.ts.map +1 -1
  284. package/dist/tools/check-status.js +245 -3
  285. package/dist/tools/check-status.js.map +1 -1
  286. package/dist/tools/child-id-allocator.d.ts +2 -2
  287. package/dist/tools/cloud-control.js +2 -2
  288. package/dist/tools/cloud-control.js.map +1 -1
  289. package/dist/tools/code-intelligence-codebase-memory.d.ts +11 -0
  290. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +1 -0
  291. package/dist/tools/code-intelligence-codebase-memory.js +270 -0
  292. package/dist/tools/code-intelligence-codebase-memory.js.map +1 -0
  293. package/dist/tools/code-intelligence-freshness.d.ts +2 -0
  294. package/dist/tools/code-intelligence-freshness.d.ts.map +1 -0
  295. package/dist/tools/code-intelligence-freshness.js +26 -0
  296. package/dist/tools/code-intelligence-freshness.js.map +1 -0
  297. package/dist/tools/code-intelligence-gitnexus.d.ts +14 -0
  298. package/dist/tools/code-intelligence-gitnexus.d.ts.map +1 -0
  299. package/dist/tools/code-intelligence-gitnexus.js +475 -0
  300. package/dist/tools/code-intelligence-gitnexus.js.map +1 -0
  301. package/dist/tools/code-intelligence-kb-enrich.d.ts +2 -0
  302. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +1 -0
  303. package/dist/tools/code-intelligence-kb-enrich.js +65 -0
  304. package/dist/tools/code-intelligence-kb-enrich.js.map +1 -0
  305. package/dist/tools/code-intelligence-reindex.d.ts +7 -0
  306. package/dist/tools/code-intelligence-reindex.d.ts.map +1 -0
  307. package/dist/tools/code-intelligence-reindex.js +106 -0
  308. package/dist/tools/code-intelligence-reindex.js.map +1 -0
  309. package/dist/tools/code-intelligence-telemetry.d.ts +5 -0
  310. package/dist/tools/code-intelligence-telemetry.d.ts.map +1 -0
  311. package/dist/tools/code-intelligence-telemetry.js +52 -0
  312. package/dist/tools/code-intelligence-telemetry.js.map +1 -0
  313. package/dist/tools/code-intelligence-tests.d.ts +2 -0
  314. package/dist/tools/code-intelligence-tests.d.ts.map +1 -0
  315. package/dist/tools/code-intelligence-tests.js +24 -0
  316. package/dist/tools/code-intelligence-tests.js.map +1 -0
  317. package/dist/tools/code-intelligence.d.ts +114 -0
  318. package/dist/tools/code-intelligence.d.ts.map +1 -0
  319. package/dist/tools/code-intelligence.js +124 -0
  320. package/dist/tools/code-intelligence.js.map +1 -0
  321. package/dist/tools/compose-permissions.d.ts +26 -0
  322. package/dist/tools/compose-permissions.d.ts.map +1 -1
  323. package/dist/tools/compose-permissions.js +257 -33
  324. package/dist/tools/compose-permissions.js.map +1 -1
  325. package/dist/tools/execute-command.d.ts +2 -0
  326. package/dist/tools/execute-command.d.ts.map +1 -1
  327. package/dist/tools/execute-command.js +114 -28
  328. package/dist/tools/execute-command.js.map +1 -1
  329. package/dist/tools/execute-prompt.d.ts +13 -1
  330. package/dist/tools/execute-prompt.d.ts.map +1 -1
  331. package/dist/tools/execute-prompt.js +310 -61
  332. package/dist/tools/execute-prompt.js.map +1 -1
  333. package/dist/tools/kb-capture.d.ts +53 -0
  334. package/dist/tools/kb-capture.d.ts.map +1 -0
  335. package/dist/tools/kb-capture.js +130 -0
  336. package/dist/tools/kb-capture.js.map +1 -0
  337. package/dist/tools/kb-context.d.ts +17 -0
  338. package/dist/tools/kb-context.d.ts.map +1 -0
  339. package/dist/tools/kb-context.js +29 -0
  340. package/dist/tools/kb-context.js.map +1 -0
  341. package/dist/tools/kb-export.d.ts +19 -0
  342. package/dist/tools/kb-export.d.ts.map +1 -0
  343. package/dist/tools/kb-export.js +344 -0
  344. package/dist/tools/kb-export.js.map +1 -0
  345. package/dist/tools/kb-feedback.d.ts +23 -0
  346. package/dist/tools/kb-feedback.d.ts.map +1 -0
  347. package/dist/tools/kb-feedback.js +43 -0
  348. package/dist/tools/kb-feedback.js.map +1 -0
  349. package/dist/tools/kb-freshness-sweep.d.ts +14 -0
  350. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -0
  351. package/dist/tools/kb-freshness-sweep.js +29 -0
  352. package/dist/tools/kb-freshness-sweep.js.map +1 -0
  353. package/dist/tools/kb-harvest.d.ts +20 -0
  354. package/dist/tools/kb-harvest.d.ts.map +1 -0
  355. package/dist/tools/kb-harvest.js +143 -0
  356. package/dist/tools/kb-harvest.js.map +1 -0
  357. package/dist/tools/kb-import.d.ts +44 -0
  358. package/dist/tools/kb-import.d.ts.map +1 -0
  359. package/dist/tools/kb-import.js +239 -0
  360. package/dist/tools/kb-import.js.map +1 -0
  361. package/dist/tools/kb-invalidate.d.ts +19 -0
  362. package/dist/tools/kb-invalidate.d.ts.map +1 -0
  363. package/dist/tools/kb-invalidate.js +34 -0
  364. package/dist/tools/kb-invalidate.js.map +1 -0
  365. package/dist/tools/kb-list.d.ts +32 -0
  366. package/dist/tools/kb-list.d.ts.map +1 -0
  367. package/dist/tools/kb-list.js +43 -0
  368. package/dist/tools/kb-list.js.map +1 -0
  369. package/dist/tools/kb-promote.d.ts +20 -0
  370. package/dist/tools/kb-promote.d.ts.map +1 -0
  371. package/dist/tools/kb-promote.js +20 -0
  372. package/dist/tools/kb-promote.js.map +1 -0
  373. package/dist/tools/kb-query.d.ts +35 -0
  374. package/dist/tools/kb-query.d.ts.map +1 -0
  375. package/dist/tools/kb-query.js +111 -0
  376. package/dist/tools/kb-query.js.map +1 -0
  377. package/dist/tools/kb-reconcile-prefilter.d.ts +14 -0
  378. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -0
  379. package/dist/tools/kb-reconcile-prefilter.js +26 -0
  380. package/dist/tools/kb-reconcile-prefilter.js.map +1 -0
  381. package/dist/tools/kb-resolve-contradiction.d.ts +23 -0
  382. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -0
  383. package/dist/tools/kb-resolve-contradiction.js +37 -0
  384. package/dist/tools/kb-resolve-contradiction.js.map +1 -0
  385. package/dist/tools/kb-session-prime.d.ts +26 -0
  386. package/dist/tools/kb-session-prime.d.ts.map +1 -0
  387. package/dist/tools/kb-session-prime.js +392 -0
  388. package/dist/tools/kb-session-prime.js.map +1 -0
  389. package/dist/tools/kb-setup.d.ts +20 -0
  390. package/dist/tools/kb-setup.d.ts.map +1 -0
  391. package/dist/tools/kb-setup.js +49 -0
  392. package/dist/tools/kb-setup.js.map +1 -0
  393. package/dist/tools/kb-stats.d.ts +20 -0
  394. package/dist/tools/kb-stats.d.ts.map +1 -0
  395. package/dist/tools/kb-stats.js +115 -0
  396. package/dist/tools/kb-stats.js.map +1 -0
  397. package/dist/tools/list-members.d.ts.map +1 -1
  398. package/dist/tools/list-members.js +6 -2
  399. package/dist/tools/list-members.js.map +1 -1
  400. package/dist/tools/member-detail.d.ts.map +1 -1
  401. package/dist/tools/member-detail.js +13 -3
  402. package/dist/tools/member-detail.js.map +1 -1
  403. package/dist/tools/member-reservation.d.ts.map +1 -1
  404. package/dist/tools/member-reservation.js +13 -1
  405. package/dist/tools/member-reservation.js.map +1 -1
  406. package/dist/tools/monitor-task.d.ts.map +1 -1
  407. package/dist/tools/monitor-task.js +38 -5
  408. package/dist/tools/monitor-task.js.map +1 -1
  409. package/dist/tools/provision-auth.d.ts.map +1 -1
  410. package/dist/tools/provision-auth.js +15 -8
  411. package/dist/tools/provision-auth.js.map +1 -1
  412. package/dist/tools/provision-vcs-auth.d.ts +5 -2
  413. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  414. package/dist/tools/provision-vcs-auth.js +58 -52
  415. package/dist/tools/provision-vcs-auth.js.map +1 -1
  416. package/dist/tools/register-member.d.ts +21 -12
  417. package/dist/tools/register-member.d.ts.map +1 -1
  418. package/dist/tools/register-member.js +70 -3
  419. package/dist/tools/register-member.js.map +1 -1
  420. package/dist/tools/remove-member.d.ts.map +1 -1
  421. package/dist/tools/remove-member.js +19 -5
  422. package/dist/tools/remove-member.js.map +1 -1
  423. package/dist/tools/report-status.d.ts.map +1 -1
  424. package/dist/tools/report-status.js +2 -1
  425. package/dist/tools/report-status.js.map +1 -1
  426. package/dist/tools/revoke-vcs-auth.js +2 -2
  427. package/dist/tools/revoke-vcs-auth.js.map +1 -1
  428. package/dist/tools/send-email.d.ts +69 -0
  429. package/dist/tools/send-email.d.ts.map +1 -0
  430. package/dist/tools/send-email.js +177 -0
  431. package/dist/tools/send-email.js.map +1 -0
  432. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  433. package/dist/tools/setup-ssh-key.js +4 -1
  434. package/dist/tools/setup-ssh-key.js.map +1 -1
  435. package/dist/tools/stop-prompt.js +2 -2
  436. package/dist/tools/stop-prompt.js.map +1 -1
  437. package/dist/tools/update-agent-cli.js +2 -2
  438. package/dist/tools/update-agent-cli.js.map +1 -1
  439. package/dist/tools/update-member.d.ts +21 -12
  440. package/dist/tools/update-member.d.ts.map +1 -1
  441. package/dist/tools/update-member.js +43 -2
  442. package/dist/tools/update-member.js.map +1 -1
  443. package/dist/types.d.ts +12 -1
  444. package/dist/types.d.ts.map +1 -1
  445. package/dist/utils/agent-helpers.d.ts +36 -0
  446. package/dist/utils/agent-helpers.d.ts.map +1 -1
  447. package/dist/utils/agent-helpers.js +39 -1
  448. package/dist/utils/agent-helpers.js.map +1 -1
  449. package/dist/utils/platform.d.ts +7 -0
  450. package/dist/utils/platform.d.ts.map +1 -1
  451. package/dist/utils/platform.js +11 -1
  452. package/dist/utils/platform.js.map +1 -1
  453. package/dist/utils/prompt-errors.js +1 -1
  454. package/dist/utils/prompt-errors.js.map +1 -1
  455. package/dist/utils/session-caller.d.ts +28 -0
  456. package/dist/utils/session-caller.d.ts.map +1 -0
  457. package/dist/utils/session-caller.js +24 -0
  458. package/dist/utils/session-caller.js.map +1 -0
  459. package/dist/utils/work-folder-validation.d.ts +39 -0
  460. package/dist/utils/work-folder-validation.d.ts.map +1 -0
  461. package/dist/utils/work-folder-validation.js +60 -0
  462. package/dist/utils/work-folder-validation.js.map +1 -0
  463. package/dist/utils/workspace-trust.d.ts.map +1 -1
  464. package/dist/utils/workspace-trust.js +5 -1
  465. package/dist/utils/workspace-trust.js.map +1 -1
  466. package/dist/workflows/auto-sprint.js +550 -23
  467. package/package.json +7 -4
  468. package/packages/apra-fleet-client/src/client/api.mjs +210 -7
  469. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +31 -19
  470. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +16 -1
  471. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +37 -47
  472. package/packages/apra-fleet-se/apra-pm/agents/doer.md +147 -114
  473. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +41 -34
  474. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +98 -114
  475. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +205 -0
  476. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +45 -44
  477. package/packages/apra-fleet-se/apra-pm/agents/planner.md +121 -50
  478. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +84 -81
  479. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +118 -44
  480. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +63 -3
  481. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +59 -2
  482. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +3 -3
  483. package/packages/apra-fleet-se/apra-pm/agents/schemas/kb-reconciler-output.json +87 -0
  484. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +65 -0
  485. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
  486. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +105 -8
  487. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +0 -1
  488. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +6 -0
  489. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -1
  490. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +6 -1
  491. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +56 -0
  492. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +132 -0
  493. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +109 -0
  494. package/packages/apra-fleet-se/bin/cli.mjs +139 -3
  495. package/packages/apra-fleet-se/bin/serve.mjs +49 -2
  496. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +182 -38
  497. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +23 -8
  498. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +258 -0
  499. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +1487 -0
  500. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +908 -0
  501. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +399 -0
  502. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
  503. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +1148 -0
  504. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +229 -112
  505. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +91 -6
  506. package/packages/apra-fleet-se/fleet-sprint/runner.js +2469 -238
  507. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
  508. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +154 -0
  509. package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
  510. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
  511. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +15 -3
  512. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +350 -0
  513. package/packages/apra-fleet-se/fleet-sprint/sprint-progress.mjs +101 -0
  514. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +51 -0
  515. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +657 -12
  516. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
  517. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +60 -30
  518. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +205 -2
  519. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +164 -0
  520. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +141 -26
  521. package/packages/apra-fleet-se/package.json +1 -0
  522. package/packages/apra-fleet-workflow/src/viewer/index.mjs +294 -14
  523. package/packages/apra-fleet-workflow/src/viewer/run-title.mjs +60 -0
  524. package/packages/apra-fleet-workflow/src/workflow/index.mjs +443 -35
  525. package/skills/fleet/SKILL.md +20 -9
  526. package/skills/fleet/auth-azdevops.md +44 -5
  527. package/skills/fleet/auth-bitbucket.md +3 -3
  528. package/skills/fleet/auth-github.md +2 -2
  529. package/skills/fleet/beads-conflict-resolution.md +141 -0
  530. package/skills/fleet/beads.md +16 -12
  531. package/skills/fleet/knowledge-agent.md +66 -0
  532. package/skills/fleet/onboarding.md +4 -4
  533. package/skills/fleet/permissions.md +32 -8
  534. package/skills/fleet/profiles/base-dev.json +10 -1
  535. package/skills/fleet/profiles/base-reviewer.json +8 -1
  536. package/skills/fleet/profiles/tag-kb-reconciler.json +20 -0
  537. package/skills/fleet/skill-matrix.md +1 -1
  538. package/skills/fleet/troubleshooting.md +2 -1
  539. package/version.json +1 -1
  540. package/dist/providers/gemini.d.ts +0 -42
  541. package/dist/providers/gemini.d.ts.map +0 -1
  542. package/dist/providers/gemini.js +0 -202
  543. package/dist/providers/gemini.js.map +0 -1
  544. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -151
  545. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +0 -127
  546. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +0 -339
  547. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +0 -360
  548. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +0 -363
@@ -0,0 +1,350 @@
1
+ ---
2
+ name: fleet-supervisor
3
+ description: How to start/smoke-test the supervisor process itself, and start, check, and kill fleet-sprints via its HTTP API only (POST /api/sprints on localhost:8787). Never call the fleet-sprint CLI directly. Trigger whenever asked to start/launch/check/stop/kill the supervisor or a sprint.
4
+ ---
5
+
6
+ # fleet-supervisor (supervisor API)
7
+
8
+ Sprints are started, checked, and killed through the supervisor's HTTP API.
9
+ Default port: **8787**. Never invoke `apra-fleet workflow fleet-sprint` or
10
+ `bin/cli.mjs` directly -- always go through this API.
11
+
12
+ ## 0. Start the supervisor (if not already running)
13
+
14
+ Check first: `curl -s -m 5 http://localhost:8787/api/sprints`. Connection
15
+ refused/timeout = not running. `{"sprints": [...]}` = already up, skip this.
16
+
17
+ Start it detached (it runs indefinitely -- exits only on `POST
18
+ /api/shutdown` or SIGINT/SIGTERM, never on its own):
19
+
20
+ ```bash
21
+ node packages/apra-fleet-se/bin/serve.mjs # background/detached, from repo root
22
+ ```
23
+
24
+ `--port <n>` overrides the default (8787). Self-logs to
25
+ `<dataDir>/logs/supervisor.log` in addition to stdout.
26
+
27
+ Smoke test (a few seconds after launch -- give it time to bind):
28
+ ```bash
29
+ curl -s -m 5 http://localhost:8787/api/sprints # expect {"sprints":[],...}
30
+ curl -s -m 5 http://localhost:8787/api/members # expect the registered fleet, non-empty
31
+ ```
32
+ Both must succeed before treating the supervisor as up -- a bound port with
33
+ a 500 on `/api/members` still means something is broken.
34
+
35
+ ## Stop the supervisor
36
+
37
+ Two paths: **graceful** (preferred -- lets in-flight requests finish and every
38
+ seam tear down cleanly) and **hard-stop** (only when the API itself is
39
+ unresponsive, e.g. a hung event loop). Resolve commands per the target
40
+ member's own OS (`agent.os`) -- do not assume the orchestrator's shell; some
41
+ members run PowerShell, not POSIX.
42
+
43
+ ### Graceful (preferred)
44
+
45
+ ```bash
46
+ curl -s -X POST http://localhost:8787/api/shutdown
47
+ ```
48
+ Returns `{"status":"shutting-down"}` immediately; the process then finishes
49
+ tearing down every seam (ledger, watchdog, dashboard, etc) and exits on its
50
+ own a moment later. Confirm it is actually gone:
51
+ ```bash
52
+ curl -s -m 5 http://localhost:8787/api/sprints # expect connection refused
53
+ ```
54
+ If that still connects after a few seconds, fall through to hard-stop below.
55
+
56
+ ### Find the supervisor's PID/port (when the API is unresponsive)
57
+
58
+ `GET /api/health` normally reports the running `pid` directly (`curl -s -m 5
59
+ http://localhost:8787/api/health`), but if the API itself is unresponsive
60
+ that call will hang or refuse -- fall back to an OS-level lookup by port
61
+ (default **8787**) or process name (`serve.mjs`):
62
+
63
+ **macOS / Linux:**
64
+ ```bash
65
+ lsof -i :8787 # shows the PID (COMMAND, PID columns) bound to the port
66
+ lsof -ti:8787 # PID only, convenient for command substitution
67
+ # or, by process name if the port lookup finds nothing (already unbound but
68
+ # the process is still alive/hung):
69
+ pgrep -f 'bin/serve.mjs'
70
+ ```
71
+
72
+ **Windows (PowerShell):**
73
+ ```powershell
74
+ Get-NetTCPConnection -LocalPort 8787 | Select-Object OwningProcess
75
+ Get-Process -Id <pid> # confirm it is the supervisor before killing it
76
+ # or, by process name:
77
+ Get-Process | Where-Object { $_.Path -like '*serve.mjs*' -or $_.CommandLine -like '*serve.mjs*' }
78
+ ```
79
+
80
+ **Windows (cmd.exe, if PowerShell is unavailable):**
81
+ ```cmd
82
+ netstat -ano | findstr :8787
83
+ tasklist /FI "PID eq <pid>"
84
+ ```
85
+
86
+ ### Hard-stop (PID-based kill)
87
+
88
+ Only once you have confirmed the PID above is actually the supervisor
89
+ process. Try a graceful signal first, then force:
90
+
91
+ **macOS / Linux:**
92
+ ```bash
93
+ kill <pid> # SIGTERM -- gives it a chance to exit cleanly
94
+ sleep 2
95
+ kill -0 <pid> 2>/dev/null && kill -9 <pid> # still alive? force it
96
+ ```
97
+
98
+ **Windows (PowerShell):**
99
+ ```powershell
100
+ Stop-Process -Id <pid> # graceful-ish first attempt
101
+ Stop-Process -Id <pid> -Force # still running? force-kill
102
+ ```
103
+
104
+ **Windows (cmd.exe):**
105
+ ```cmd
106
+ taskkill /PID <pid>
107
+ taskkill /PID <pid> /F
108
+ ```
109
+
110
+ After either path, verify the port is free before restarting:
111
+ `curl -s -m 5 http://localhost:8787/api/sprints` must refuse the connection
112
+ (macOS/Linux), or the port-lookup command above must return nothing
113
+ (Windows).
114
+
115
+ ## Restart the supervisor
116
+
117
+ A discrete stop-then-start procedure -- use this instead of assuming a bare
118
+ restart command exists:
119
+
120
+ 1. **Stop** it: graceful shutdown above; if that does not actually stop it
121
+ (still answering after a few seconds), fall back to the hard-stop path
122
+ above.
123
+ 2. **Confirm it is down**: `curl -s -m 5 http://localhost:8787/api/sprints`
124
+ must refuse the connection (or the per-OS port lookup above returns
125
+ nothing).
126
+ 3. **Start** it again: see section 0 ("Start the supervisor") above, then
127
+ run its smoke test (`GET /api/sprints`, `GET /api/members`) to confirm the
128
+ new process is actually serving before treating the restart as done.
129
+
130
+ ## Auto-start on login/boot
131
+
132
+ Instead of a human running `node bin/serve.mjs` by hand each session, the
133
+ supervisor can be registered with the OS to start automatically on
134
+ login/boot. Resolve commands per the target member's own OS (`agent.os`) --
135
+ do not assume the orchestrator's shell; some members run PowerShell, not
136
+ POSIX. Every example below assumes the repo root is
137
+ `/path/to/apra-fleet` (POSIX) or `C:\path\to\apra-fleet` (Windows) --
138
+ substitute the real path on the target member. After registering (any OS),
139
+ run the same-process smoke test from section 0 above (`GET /api/sprints`,
140
+ `GET /api/members`) against the newly auto-started instance to confirm it is
141
+ actually serving, not just that the OS accepted the registration.
142
+
143
+ ### Windows
144
+
145
+ **Option A -- Task Scheduler, "At log on" trigger** (simplest; runs in the
146
+ user's own session):
147
+
148
+ Register:
149
+ ```cmd
150
+ schtasks /Create /TN "ApraFleetSupervisor" /TR "node C:\path\to\apra-fleet\packages\apra-fleet-se\bin\serve.mjs" /SC ONLOGON /RL LIMITED
151
+ ```
152
+ De-register:
153
+ ```cmd
154
+ schtasks /Delete /TN "ApraFleetSupervisor" /F
155
+ ```
156
+ Confirm it registered:
157
+ ```cmd
158
+ schtasks /Query /TN "ApraFleetSupervisor"
159
+ ```
160
+
161
+ **Option B -- a Windows service via NSSM** (runs even with nobody logged
162
+ in; requires NSSM installed and on PATH):
163
+
164
+ Register:
165
+ ```cmd
166
+ nssm install ApraFleetSupervisor node "C:\path\to\apra-fleet\packages\apra-fleet-se\bin\serve.mjs"
167
+ nssm set ApraFleetSupervisor AppDirectory "C:\path\to\apra-fleet"
168
+ nssm start ApraFleetSupervisor
169
+ ```
170
+ De-register:
171
+ ```cmd
172
+ nssm stop ApraFleetSupervisor
173
+ nssm remove ApraFleetSupervisor confirm
174
+ ```
175
+
176
+ ### macOS (launchd user LaunchAgent)
177
+
178
+ Create `~/Library/LaunchAgents/com.apra-fleet.supervisor.plist`:
179
+ ```xml
180
+ <?xml version="1.0" encoding="UTF-8"?>
181
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
182
+ "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
183
+ <plist version="1.0">
184
+ <dict>
185
+ <key>Label</key>
186
+ <string>com.apra-fleet.supervisor</string>
187
+ <key>ProgramArguments</key>
188
+ <array>
189
+ <string>/usr/local/bin/node</string>
190
+ <string>/path/to/apra-fleet/packages/apra-fleet-se/bin/serve.mjs</string>
191
+ </array>
192
+ <key>RunAtLoad</key>
193
+ <true/>
194
+ <key>KeepAlive</key>
195
+ <false/>
196
+ <key>StandardOutPath</key>
197
+ <string>/tmp/apra-fleet-supervisor.log</string>
198
+ <key>StandardErrorPath</key>
199
+ <string>/tmp/apra-fleet-supervisor.log</string>
200
+ </dict>
201
+ </plist>
202
+ ```
203
+ `RunAtLoad` starts it at login; `KeepAlive` is deliberately `false` -- the
204
+ supervisor already runs indefinitely on its own (see section 0), so it does
205
+ not need launchd to respawn it on exit (an explicit `POST /api/shutdown`
206
+ should stay stopped, not bounce back up). launchd runs with a minimal PATH
207
+ (`/usr/bin:/bin:/usr/sbin:/sbin`), so a bare `node` command will not resolve
208
+ if node is installed via Homebrew or a version manager. Use the real path to
209
+ `node` on your system (`which node`) if it differs from `/usr/local/bin/node`.
210
+
211
+ Register (load) and start now:
212
+ ```bash
213
+ launchctl load ~/Library/LaunchAgents/com.apra-fleet.supervisor.plist
214
+ launchctl start com.apra-fleet.supervisor
215
+ ```
216
+ De-register (stop and unload, so it no longer starts at login):
217
+ ```bash
218
+ launchctl stop com.apra-fleet.supervisor
219
+ launchctl unload ~/Library/LaunchAgents/com.apra-fleet.supervisor.plist
220
+ ```
221
+
222
+ ### Linux (systemd --user unit)
223
+
224
+ Create `~/.config/systemd/user/apra-fleet-supervisor.service`:
225
+ ```ini
226
+ [Unit]
227
+ Description=Apra Fleet supervisor
228
+
229
+ [Service]
230
+ ExecStart=/usr/bin/node /path/to/apra-fleet/packages/apra-fleet-se/bin/serve.mjs
231
+ Restart=no
232
+ WorkingDirectory=/path/to/apra-fleet
233
+
234
+ [Install]
235
+ WantedBy=default.target
236
+ ```
237
+ `Restart=no` matches the launchd `KeepAlive=false` choice above: the
238
+ supervisor is already self-persistent (section 0), and an explicit `POST
239
+ /api/shutdown` should stay stopped rather than being auto-respawned by the
240
+ unit. Use the real path to `node` on the target member (`which node`) if it
241
+ differs from `/usr/bin/node`.
242
+
243
+ Register and start:
244
+ ```bash
245
+ systemctl --user daemon-reload
246
+ systemctl --user enable apra-fleet-supervisor.service
247
+ systemctl --user start apra-fleet-supervisor.service
248
+ ```
249
+ De-register (stop and disable, so it no longer starts at login/boot):
250
+ ```bash
251
+ systemctl --user stop apra-fleet-supervisor.service
252
+ systemctl --user disable apra-fleet-supervisor.service
253
+ ```
254
+ A user unit only starts at login unless lingering is enabled for boot-time
255
+ start with no login (`loginctl enable-linger <username>`).
256
+
257
+ ## 1. Before you launch a sprint
258
+
259
+ 1. If you just created/edited beads locally, push them first:
260
+ `bd dolt commit` then `bd dolt push`. Members pull their own copy; a
261
+ sprint launched before the push works from stale scope.
262
+ 2. Check no conflicting sprint is already running: `GET /api/sprints`.
263
+ 3. Multi-member sprints need all members on the SAME git HEAD, or the
264
+ launch crashes immediately with a topology error. If unsure, use ONE
265
+ member. Don't guess a member list -- ask, or default to one.
266
+
267
+ ## 2. Start a sprint
268
+
269
+ ```bash
270
+ curl -s -X POST http://localhost:8787/api/sprints \
271
+ -H "Content-Type: application/json" \
272
+ -d '{
273
+ "issue": "<id[,id2,...]>",
274
+ "branch": "<new-or-existing-branch>",
275
+ "base": "<base-branch>",
276
+ "members": ["<member-name>"],
277
+ "goal": "P1/P2"
278
+ }'
279
+ ```
280
+
281
+ Field names, exactly as the API expects them:
282
+
283
+ | Field | Required | Notes |
284
+ |---|---|---|
285
+ | `issue` | yes | comma-separated bead root IDs (parent/epic OR a standalone leaf bead). Alias: `target_issue`. |
286
+ | `branch` | yes | created from `base` if it doesn't exist yet. |
287
+ | `base` | yes | alias: `base_branch`. This is what the sprint branches FROM -- pass the branch you actually want, not always `main`. |
288
+ | `members` | yes | array of registered member names. One member = safest default. |
289
+ | `goal` | no | `P1`, `P1/P2` (default), or `P1/P2/P3`. |
290
+ | `maxCycles` | no | default 5. |
291
+ | `allowMissingMembers` | no | bool. |
292
+ | `requirementsFile` | no | path. |
293
+ | `roleMap` | no | `{"doer":["m1","m2"], "reviewer":["m3"]}`. |
294
+ | `budget` | no | USD cap. |
295
+ | `overrideRelaunchGate` | no | bool. See below. |
296
+
297
+ Response has `sprintId`, `pid`, `port` (its own dashboard), `logPath`.
298
+ **A 201 response does NOT mean the sprint is alive** -- it can crash in the
299
+ first few seconds (bad topology, bad member, etc). Always verify (step 3)
300
+ a few seconds after launch.
301
+
302
+ ## 3. Check status
303
+
304
+ All live sprints:
305
+ ```bash
306
+ curl -s http://localhost:8787/api/sprints
307
+ ```
308
+ Empty `sprints: []` after a launch = it already died. Check its `logPath`.
309
+
310
+ One sprint (live state, or its terminal record if it finished/crashed):
311
+ ```bash
312
+ curl -s http://localhost:8787/api/sprints/<sprintId>
313
+ ```
314
+
315
+ Sprint-scoped dashboard (per-role activity, bead DAG, cost, PR link):
316
+ `http://localhost:<port>` (the `port` from the launch response).
317
+
318
+ ## 4. Kill a sprint
319
+
320
+ ```bash
321
+ curl -s -X POST http://localhost:8787/api/sprints/<sprintId>/stop
322
+ ```
323
+
324
+ ## Relaunch gate
325
+
326
+ If a prior run of the SAME issue root ended in a deterministic, unaddressed
327
+ failure (crash, sync conflict, etc), a relaunch is refused with a 409. Once
328
+ you understand and have actually fixed the cause, retry with
329
+ `"overrideRelaunchGate": true` in the body. This is not a silent bypass --
330
+ only use it once you know why the prior run died.
331
+
332
+ ## Common launch-time crashes
333
+
334
+ - **Topology mismatch**: members are on different git commits. Fix: use one
335
+ member, or align them first (`git fetch && git checkout <branch>` on
336
+ each), or pass whatever sync option the engine currently exposes -- check
337
+ `docs/architecture.md` "Multi-member topology" section, don't guess.
338
+ - **Unregistered member**: `GET /api/members` to see valid names.
339
+ - **Stale LLM auth**: dispatch fails with `empty_response`. Re-run
340
+ `provision_llm_auth` for that member.
341
+
342
+ ## Member layout: isolate deploy/test roles from dev roles
343
+
344
+ For projects where the deployed software runs and is verified LOCALLY on the
345
+ member, give `deployer`, `integ-test-runner`, and `regression-test-runner` a
346
+ dedicated member with its own independent git clone (not a worktree),
347
+ separate from `planner`/`plan-reviewer`/`doer`/`reviewer`, via `roleMap`:
348
+ `{"deployer": ["<deploy-member>"], "integ-test-runner": ["<deploy-member>"],
349
+ "regression-test-runner": ["<deploy-member>"], "doer": ["<dev-member>"], ...}`.
350
+ Dev roles can all safely share one generic member.
@@ -0,0 +1,101 @@
1
+ // apra-fleet-x8r.1: closed/required bead-count derivation for the
2
+ // beads-closed/required progress-bar widget.
3
+ //
4
+ // Deliberately does NOT re-walk the parent-edge BFS runner.js's
5
+ // bdListScoped()/decomposedParentIds() already perform to discover "what is
6
+ // in scope for this sprint" -- that would be a second, independently
7
+ // maintained definition of "in scope" that could silently drift from the
8
+ // completion gate's own. Instead this takes the ALREADY-SCOPED bead list the
9
+ // caller already has on hand (dashboard.mjs's `sprintTasks`, itself built
10
+ // from `bdListScoped('')` -- see runner.js's updateDashboard()) and only
11
+ // derives the two counts a viewer needs from it: how many of those beads are
12
+ // closed, and how many total. Pure/sync, no I/O -- takes data, returns data.
13
+ //
14
+ // apra-fleet-4p5-style: also embedded verbatim (via `.toString()`) into
15
+ // viewer-extensions.mjs's browser-side `<script>` alongside renderBeadsHtml,
16
+ // so the exact function under test here is the exact function that renders
17
+ // the widget in the browser -- never a hand-duplicated copy.
18
+ //
19
+ // apra-fleet-x8r.4: `required` originally defaulted to `beads.length` --
20
+ // EVERY bead in the sprint's scope, regardless of priority or structure. But
21
+ // runner.js's real completion gate (~line 8134) computes
22
+ // `openAtGoal = bdListScoped('--status=<NOT_DONE> --priority-max=<goalMax>')
23
+ // MINUS decomposedParentIds()`: below-goal-priority beads and decomposed
24
+ // parent (grouping) nodes are NOT part of the required-to-close set that
25
+ // actually gates sprint exit. Left unfiltered, a sprint whose scope contains
26
+ // either could legitimately complete while this widget still showed less
27
+ // than N/N -- the opposite of "how much of this sprint's required work is
28
+ // done". `opts` is ADDITIVE-OPTIONAL (a bare `computeSprintProgress(beads)`
29
+ // call -- e.g. a caller that has not been plumbed a goalMax/decomposed set
30
+ // yet -- keeps its original all-of-scope behavior) so every existing/future
31
+ // call site stays valid without redesigning this signature again.
32
+ //
33
+ // Both fields are plumbed in from the SAME server-side sources runner.js's
34
+ // gate itself uses (goalPriorityMax(validated.goal), decomposedParentIds())
35
+ // -- never re-derived here or client-side, so there is exactly one
36
+ // "what does this sprint still need to close" definition in the package.
37
+
38
+ // apra-fleet-x8r.8: runner.js's partitionByGoalMembership() (eft.52.1.3) can
39
+ // place a below-goal-priority bead in the Sprint section via a documented
40
+ // blocks-edge exception -- a bead that BLOCKS an in-goal bead is admitted
41
+ // into 'sprint' placement even though its own priority is below goalMax. That
42
+ // server-computed decision is tagged verbatim onto the row as `placement`
43
+ // ('sprint' | 'backlog') and is exactly what the beads TREE (renderBeadsHtml)
44
+ // honors when deciding which section a row renders in. Before this fix,
45
+ // computeSprintProgress() re-derived membership from raw numeric priority
46
+ // alone (`priority > goalMax` -> excluded), ignoring `placement` -- so a
47
+ // blocks-exception bead could render as an open Sprint row in the tree while
48
+ // being silently excluded from the 'M/N' count directly above it (the bar
49
+ // reads N/N while a visibly-open row sits right below). Reusing `placement`
50
+ // when present (rather than re-deriving from priority) makes the bar and the
51
+ // tree agree on exactly the same admitted set.
52
+ /**
53
+ * @param {Array<{id?: string, status?: string, priority?: number, placement?: string}>} beads the
54
+ * sprint's already-scoped bead list (e.g. dashboard.mjs's `sprintTasks`,
55
+ * sourced from `bdListScoped('')`)
56
+ * @param {{ goalMax?: number, decomposedParentIds?: Iterable<string> }} [opts]
57
+ * `goalMax` is the NUMERIC worst priority tier named in the sprint's goal
58
+ * (e.g. `goalPriorityMax('P1/P2')` -> `'P2'` -> `goalMax: 2`) -- a bead
59
+ * whose `priority` is a finite number strictly greater than `goalMax` is
60
+ * below-goal and excluded from `required`/`closed`, UNLESS that bead
61
+ * carries a server-computed `placement` field (apra-fleet-eft.52.1.3),
62
+ * in which case `placement` decides membership instead (`'backlog'` ->
63
+ * excluded, anything else, e.g. `'sprint'` -> included) so the bar can
64
+ * never disagree with the tree it sits above (apra-fleet-x8r.8). Rows with
65
+ * no `placement` field (dashboard.mjs's listAllBeads-sourced rows never
66
+ * carry one) fall back to the plain numeric filter, unchanged.
67
+ * `decomposedParentIds` is the set of bead ids that are themselves someone
68
+ * else's `.parent` (any status) -- excluded the same way runner.js's exit
69
+ * gate excludes them, regardless of `placement`.
70
+ * Omitting `opts` (or either field) applies no filtering on that axis,
71
+ * preserving the pre-x8r.4 "every bead in scope" behavior.
72
+ * @returns {{ closed: number, required: number, fraction: number }}
73
+ * `fraction` is `closed / required`, clamped to 0 when `required` is 0
74
+ * (never NaN/Infinity from a divide-by-zero).
75
+ */
76
+ export function computeSprintProgress(beads, opts) {
77
+ const list = Array.isArray(beads) ? beads : [];
78
+ const goalMax = opts && typeof opts.goalMax === 'number' && Number.isFinite(opts.goalMax)
79
+ ? opts.goalMax
80
+ : null;
81
+ const decomposedParentIds = opts && opts.decomposedParentIds
82
+ ? new Set(opts.decomposedParentIds)
83
+ : null;
84
+ const filtered = list.filter((b) => {
85
+ if (!b) return false;
86
+ if (decomposedParentIds && decomposedParentIds.has(b.id)) return false;
87
+ if (typeof b.placement === 'string') {
88
+ // Server-computed placement already decided which section this
89
+ // bead belongs to (including the blocks-edge exception) -- reuse
90
+ // it verbatim instead of re-deriving from priority, so the bar
91
+ // agrees with the tree exactly.
92
+ return b.placement !== 'backlog';
93
+ }
94
+ if (goalMax !== null && typeof b.priority === 'number' && b.priority > goalMax) return false;
95
+ return true;
96
+ });
97
+ const required = filtered.length;
98
+ const closed = filtered.filter((b) => String(b.status).toLowerCase() === 'closed').length;
99
+ const fraction = required > 0 ? closed / required : 0;
100
+ return { closed, required, fraction };
101
+ }
@@ -404,8 +404,59 @@ export function capabilities(remoteUrl) {
404
404
  return { hasRemote: true, canOpenPullRequest: !!providerCaps.canOpenPullRequest, host: parsed.host };
405
405
  }
406
406
 
407
+ /**
408
+ * Resolve a git remote URL into the repository coordinates its OWN provider
409
+ * defines, by dispatching to that provider's optional parseRepoRef() hook
410
+ * (apra-fleet-5co8.1.2). This is the shared half of the remote-URL axis: the
411
+ * host is parsed here, the provider is chosen by the registry, and every
412
+ * provider-specific rule -- which URL shapes are legal, what the coordinates
413
+ * are called, what shape to tell the operator to use -- lives in the provider
414
+ * file, so no caller (runner.js in particular) needs a provider conditional.
415
+ *
416
+ * Three outcomes, deliberately distinct so a caller can tell "not my business"
417
+ * apart from "your remote is wrong":
418
+ * - null no provider claims this host, or the claiming provider
419
+ * has no parseRepoRef hook. The caller keeps its own
420
+ * generic owner/repo parse -- behavior unchanged for
421
+ * GitHub and every other provider.
422
+ * - { canonical, ref, provider }
423
+ * the provider recognized the remote; `canonical` is its
424
+ * display/identity key (e.g. org/project/repo for Azure
425
+ * DevOps) and `ref` the full coordinate object.
426
+ * - { error } the provider CLAIMS this host but does not recognize the
427
+ * URL -- a malformed remote, not an unknown one. A typed
428
+ * 'ERROR: ' string naming the shape the provider expects
429
+ * (its optional `repoRefHint`), for the caller to surface
430
+ * as a preflight failure rather than proceeding with
431
+ * half-parsed coordinates.
432
+ *
433
+ * @param {unknown} remoteUrl
434
+ * @returns {{ canonical: string, ref: object, provider: string }|{ error: string }|null}
435
+ */
436
+ export function parseProviderRepoRef(remoteUrl) {
437
+ const url = String(remoteUrl ?? '').trim();
438
+ const parsed = parseRemote(url);
439
+ if (!parsed || !parsed.host) return null;
440
+
441
+ const provider = resolveVcsProviderForHost(parsed.host);
442
+ if (!provider || typeof provider.parseRepoRef !== 'function') return null;
443
+
444
+ const ref = provider.parseRepoRef(url);
445
+ if (ref && typeof ref.canonical === 'string' && ref.canonical) {
446
+ return { canonical: ref.canonical, ref, provider: provider.name };
447
+ }
448
+
449
+ const hint = (typeof provider.repoRefHint === 'string' && provider.repoRefHint.trim())
450
+ ? provider.repoRefHint.trim()
451
+ : '(this provider documents no expected remote shape)';
452
+ return {
453
+ error: `ERROR: git remote '${url}' is claimed by VCS provider '${provider.name}' but is not a repository URL it recognizes; expected the shape ${hint}`,
454
+ };
455
+ }
456
+
407
457
  export const VCSModule = {
408
458
  buildCreatePrCommand,
459
+ parseProviderRepoRef,
409
460
  buildCommentCommand,
410
461
  classifyFailure,
411
462
  toGitVerdict,