@apralabs/apra-fleet 0.4.2 → 0.4.3

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 (370) hide show
  1. package/README.md +38 -5
  2. package/dist/agents/backlog-groomer.md +25 -0
  3. package/dist/agents/ci-watcher.md +11 -0
  4. package/dist/agents/deployer.md +37 -2
  5. package/dist/agents/doer.md +36 -12
  6. package/dist/agents/harvester.md +11 -0
  7. package/dist/agents/integ-test-runner.md +11 -0
  8. package/dist/agents/kb-reconciler.md +9 -0
  9. package/dist/agents/plan-reviewer.md +110 -22
  10. package/dist/agents/planner.md +125 -37
  11. package/dist/agents/regression-test-runner.md +11 -0
  12. package/dist/agents/reviewer.md +13 -2
  13. package/dist/agents/schemas/plan-reviewer-output.json +37 -0
  14. package/dist/cli/agent-transform.d.ts +83 -2
  15. package/dist/cli/agent-transform.d.ts.map +1 -1
  16. package/dist/cli/agent-transform.js +266 -21
  17. package/dist/cli/agent-transform.js.map +1 -1
  18. package/dist/cli/auth.d.ts.map +1 -1
  19. package/dist/cli/auth.js +28 -9
  20. package/dist/cli/auth.js.map +1 -1
  21. package/dist/cli/config.d.ts +7 -5
  22. package/dist/cli/config.d.ts.map +1 -1
  23. package/dist/cli/config.js +44 -34
  24. package/dist/cli/config.js.map +1 -1
  25. package/dist/cli/install.d.ts +33 -0
  26. package/dist/cli/install.d.ts.map +1 -1
  27. package/dist/cli/install.js +290 -23
  28. package/dist/cli/install.js.map +1 -1
  29. package/dist/cli/kb-directives.d.ts.map +1 -1
  30. package/dist/cli/kb-directives.js +2 -1
  31. package/dist/cli/kb-directives.js.map +1 -1
  32. package/dist/cli/register-member.d.ts.map +1 -1
  33. package/dist/cli/register-member.js +6 -2
  34. package/dist/cli/register-member.js.map +1 -1
  35. package/dist/commands/kb-server.d.ts +3 -0
  36. package/dist/commands/kb-server.d.ts.map +1 -1
  37. package/dist/commands/kb-server.js +43 -3
  38. package/dist/commands/kb-server.js.map +1 -1
  39. package/dist/index.js +3 -3
  40. package/dist/os/linux.d.ts +6 -0
  41. package/dist/os/linux.d.ts.map +1 -1
  42. package/dist/os/linux.js +35 -2
  43. package/dist/os/linux.js.map +1 -1
  44. package/dist/os/os-commands.d.ts +61 -2
  45. package/dist/os/os-commands.d.ts.map +1 -1
  46. package/dist/os/windows-gitbash.d.ts +5 -0
  47. package/dist/os/windows-gitbash.d.ts.map +1 -1
  48. package/dist/os/windows-gitbash.js +15 -0
  49. package/dist/os/windows-gitbash.js.map +1 -1
  50. package/dist/os/windows.d.ts +6 -0
  51. package/dist/os/windows.d.ts.map +1 -1
  52. package/dist/os/windows.js +46 -3
  53. package/dist/os/windows.js.map +1 -1
  54. package/dist/providers/agy.d.ts +115 -6
  55. package/dist/providers/agy.d.ts.map +1 -1
  56. package/dist/providers/agy.js +569 -53
  57. package/dist/providers/agy.js.map +1 -1
  58. package/dist/providers/claude.d.ts +81 -3
  59. package/dist/providers/claude.d.ts.map +1 -1
  60. package/dist/providers/claude.js +344 -10
  61. package/dist/providers/claude.js.map +1 -1
  62. package/dist/providers/codex.d.ts +4 -2
  63. package/dist/providers/codex.d.ts.map +1 -1
  64. package/dist/providers/codex.js +19 -2
  65. package/dist/providers/codex.js.map +1 -1
  66. package/dist/providers/copilot.d.ts +4 -2
  67. package/dist/providers/copilot.d.ts.map +1 -1
  68. package/dist/providers/copilot.js +20 -2
  69. package/dist/providers/copilot.js.map +1 -1
  70. package/dist/providers/none.d.ts +4 -2
  71. package/dist/providers/none.d.ts.map +1 -1
  72. package/dist/providers/none.js +17 -2
  73. package/dist/providers/none.js.map +1 -1
  74. package/dist/providers/opencode.d.ts +3 -1
  75. package/dist/providers/opencode.d.ts.map +1 -1
  76. package/dist/providers/opencode.js +22 -2
  77. package/dist/providers/opencode.js.map +1 -1
  78. package/dist/providers/provider.d.ts +201 -6
  79. package/dist/providers/provider.d.ts.map +1 -1
  80. package/dist/providers/provider.js +56 -0
  81. package/dist/providers/provider.js.map +1 -1
  82. package/dist/services/agy-project.d.ts +102 -0
  83. package/dist/services/agy-project.d.ts.map +1 -0
  84. package/dist/services/agy-project.js +356 -0
  85. package/dist/services/agy-project.js.map +1 -0
  86. package/dist/services/auth-socket.js +4 -4
  87. package/dist/services/auth-web.js +1 -1
  88. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  89. package/dist/services/cloud/lifecycle.js +33 -4
  90. package/dist/services/cloud/lifecycle.js.map +1 -1
  91. package/dist/services/credential-cleanup.d.ts.map +1 -1
  92. package/dist/services/credential-cleanup.js +35 -17
  93. package/dist/services/credential-cleanup.js.map +1 -1
  94. package/dist/services/exit-drain.d.ts +44 -0
  95. package/dist/services/exit-drain.d.ts.map +1 -0
  96. package/dist/services/exit-drain.js +52 -0
  97. package/dist/services/exit-drain.js.map +1 -0
  98. package/dist/services/github-app.d.ts.map +1 -1
  99. package/dist/services/github-app.js +32 -4
  100. package/dist/services/github-app.js.map +1 -1
  101. package/dist/services/http-transport.d.ts +1 -0
  102. package/dist/services/http-transport.d.ts.map +1 -1
  103. package/dist/services/http-transport.js +48 -1
  104. package/dist/services/http-transport.js.map +1 -1
  105. package/dist/services/knowledge/kb-config.d.ts +42 -0
  106. package/dist/services/knowledge/kb-config.d.ts.map +1 -0
  107. package/dist/services/knowledge/kb-config.js +54 -0
  108. package/dist/services/knowledge/kb-config.js.map +1 -0
  109. package/dist/services/knowledge/kb-providers.d.ts +7 -1
  110. package/dist/services/knowledge/kb-providers.d.ts.map +1 -1
  111. package/dist/services/knowledge/kb-providers.js +191 -17
  112. package/dist/services/knowledge/kb-providers.js.map +1 -1
  113. package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
  114. package/dist/services/knowledge/require-sqlite-project.d.ts.map +1 -0
  115. package/dist/services/knowledge/require-sqlite-project.js +38 -0
  116. package/dist/services/knowledge/require-sqlite-project.js.map +1 -0
  117. package/dist/services/model-pricing.d.ts.map +1 -1
  118. package/dist/services/model-pricing.js +7 -3
  119. package/dist/services/model-pricing.js.map +1 -1
  120. package/dist/services/secret-token.d.ts +38 -0
  121. package/dist/services/secret-token.d.ts.map +1 -0
  122. package/dist/services/secret-token.js +51 -0
  123. package/dist/services/secret-token.js.map +1 -0
  124. package/dist/services/service-manager/types.d.ts +3 -1
  125. package/dist/services/service-manager/types.d.ts.map +1 -1
  126. package/dist/services/service-manager/windows.d.ts +14 -2
  127. package/dist/services/service-manager/windows.d.ts.map +1 -1
  128. package/dist/services/service-manager/windows.js +65 -7
  129. package/dist/services/service-manager/windows.js.map +1 -1
  130. package/dist/services/ssh.d.ts.map +1 -1
  131. package/dist/services/ssh.js +58 -2
  132. package/dist/services/ssh.js.map +1 -1
  133. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  134. package/dist/services/stall/read-log-tail.js +20 -10
  135. package/dist/services/stall/read-log-tail.js.map +1 -1
  136. package/dist/services/stall/stall-detector.d.ts +53 -4
  137. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  138. package/dist/services/stall/stall-detector.js +212 -34
  139. package/dist/services/stall/stall-detector.js.map +1 -1
  140. package/dist/services/strategy.d.ts.map +1 -1
  141. package/dist/services/strategy.js +79 -2
  142. package/dist/services/strategy.js.map +1 -1
  143. package/dist/services/substitution-engine.js +2 -2
  144. package/dist/services/substitution-engine.js.map +1 -1
  145. package/dist/services/tool-registry.d.ts.map +1 -1
  146. package/dist/services/tool-registry.js +5 -3
  147. package/dist/services/tool-registry.js.map +1 -1
  148. package/dist/services/vcs/azure-devops.d.ts +66 -1
  149. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  150. package/dist/services/vcs/azure-devops.js +192 -21
  151. package/dist/services/vcs/azure-devops.js.map +1 -1
  152. package/dist/services/vcs/types.d.ts +1 -1
  153. package/dist/skills/fleet-sprint-cli/SKILL.md +18 -0
  154. package/dist/skills/pm/SKILL.md +1 -1
  155. package/dist/skills/pm/cost.md +0 -3
  156. package/dist/skills/pm/fleet-addendum.md +2 -2
  157. package/dist/tools/check-status.d.ts +7 -4
  158. package/dist/tools/check-status.d.ts.map +1 -1
  159. package/dist/tools/check-status.js +2 -0
  160. package/dist/tools/check-status.js.map +1 -1
  161. package/dist/tools/compose-permissions.d.ts +6 -0
  162. package/dist/tools/compose-permissions.d.ts.map +1 -1
  163. package/dist/tools/compose-permissions.js +182 -34
  164. package/dist/tools/compose-permissions.js.map +1 -1
  165. package/dist/tools/credential-store-set.js +1 -1
  166. package/dist/tools/execute-command.d.ts.map +1 -1
  167. package/dist/tools/execute-command.js +31 -20
  168. package/dist/tools/execute-command.js.map +1 -1
  169. package/dist/tools/execute-prompt.d.ts +15 -2
  170. package/dist/tools/execute-prompt.d.ts.map +1 -1
  171. package/dist/tools/execute-prompt.js +1196 -892
  172. package/dist/tools/execute-prompt.js.map +1 -1
  173. package/dist/tools/kb-capture.d.ts +2 -2
  174. package/dist/tools/kb-capture.d.ts.map +1 -1
  175. package/dist/tools/kb-capture.js +29 -5
  176. package/dist/tools/kb-capture.js.map +1 -1
  177. package/dist/tools/kb-export.d.ts +2 -2
  178. package/dist/tools/kb-export.d.ts.map +1 -1
  179. package/dist/tools/kb-export.js +3 -28
  180. package/dist/tools/kb-export.js.map +1 -1
  181. package/dist/tools/kb-feedback.d.ts.map +1 -1
  182. package/dist/tools/kb-feedback.js +3 -1
  183. package/dist/tools/kb-feedback.js.map +1 -1
  184. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -1
  185. package/dist/tools/kb-freshness-sweep.js +3 -1
  186. package/dist/tools/kb-freshness-sweep.js.map +1 -1
  187. package/dist/tools/kb-import.d.ts.map +1 -1
  188. package/dist/tools/kb-import.js +2 -1
  189. package/dist/tools/kb-import.js.map +1 -1
  190. package/dist/tools/kb-list.d.ts.map +1 -1
  191. package/dist/tools/kb-list.js +3 -1
  192. package/dist/tools/kb-list.js.map +1 -1
  193. package/dist/tools/kb-query.d.ts +2 -2
  194. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -1
  195. package/dist/tools/kb-reconcile-prefilter.js +3 -1
  196. package/dist/tools/kb-reconcile-prefilter.js.map +1 -1
  197. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -1
  198. package/dist/tools/kb-resolve-contradiction.js +3 -1
  199. package/dist/tools/kb-resolve-contradiction.js.map +1 -1
  200. package/dist/tools/kb-setup.d.ts.map +1 -1
  201. package/dist/tools/kb-setup.js +125 -20
  202. package/dist/tools/kb-setup.js.map +1 -1
  203. package/dist/tools/kb-stats.d.ts.map +1 -1
  204. package/dist/tools/kb-stats.js +64 -43
  205. package/dist/tools/kb-stats.js.map +1 -1
  206. package/dist/tools/list-members.d.ts +2 -2
  207. package/dist/tools/list-members.d.ts.map +1 -1
  208. package/dist/tools/list-members.js +1 -0
  209. package/dist/tools/list-members.js.map +1 -1
  210. package/dist/tools/member-detail.d.ts +2 -2
  211. package/dist/tools/member-detail.d.ts.map +1 -1
  212. package/dist/tools/member-detail.js +17 -0
  213. package/dist/tools/member-detail.js.map +1 -1
  214. package/dist/tools/member-reservation.d.ts +58 -1
  215. package/dist/tools/member-reservation.d.ts.map +1 -1
  216. package/dist/tools/member-reservation.js +61 -20
  217. package/dist/tools/member-reservation.js.map +1 -1
  218. package/dist/tools/provision-auth.d.ts +80 -1
  219. package/dist/tools/provision-auth.d.ts.map +1 -1
  220. package/dist/tools/provision-auth.js +142 -54
  221. package/dist/tools/provision-auth.js.map +1 -1
  222. package/dist/tools/provision-vcs-auth.d.ts +91 -1
  223. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  224. package/dist/tools/provision-vcs-auth.js +209 -49
  225. package/dist/tools/provision-vcs-auth.js.map +1 -1
  226. package/dist/tools/register-member.d.ts +12 -9
  227. package/dist/tools/register-member.d.ts.map +1 -1
  228. package/dist/tools/register-member.js +99 -12
  229. package/dist/tools/register-member.js.map +1 -1
  230. package/dist/tools/remove-member.d.ts.map +1 -1
  231. package/dist/tools/remove-member.js +27 -2
  232. package/dist/tools/remove-member.js.map +1 -1
  233. package/dist/tools/send-email.d.ts +2 -2
  234. package/dist/tools/setup-git-app.d.ts.map +1 -1
  235. package/dist/tools/setup-git-app.js +11 -7
  236. package/dist/tools/setup-git-app.js.map +1 -1
  237. package/dist/tools/shutdown-server.d.ts +2 -0
  238. package/dist/tools/shutdown-server.d.ts.map +1 -1
  239. package/dist/tools/shutdown-server.js +23 -1
  240. package/dist/tools/shutdown-server.js.map +1 -1
  241. package/dist/tools/update-member.d.ts +12 -9
  242. package/dist/tools/update-member.d.ts.map +1 -1
  243. package/dist/tools/update-member.js +43 -11
  244. package/dist/tools/update-member.js.map +1 -1
  245. package/dist/tools/vcs-credential-exec.d.ts +127 -0
  246. package/dist/tools/vcs-credential-exec.d.ts.map +1 -0
  247. package/dist/tools/vcs-credential-exec.js +197 -0
  248. package/dist/tools/vcs-credential-exec.js.map +1 -0
  249. package/dist/types.d.ts +13 -0
  250. package/dist/types.d.ts.map +1 -1
  251. package/dist/utils/log-helpers.d.ts.map +1 -1
  252. package/dist/utils/log-helpers.js +2 -2
  253. package/dist/utils/log-helpers.js.map +1 -1
  254. package/dist/utils/prompt-errors.d.ts.map +1 -1
  255. package/dist/utils/prompt-errors.js +7 -1
  256. package/dist/utils/prompt-errors.js.map +1 -1
  257. package/dist/utils/shell-escape.d.ts +16 -0
  258. package/dist/utils/shell-escape.d.ts.map +1 -1
  259. package/dist/utils/shell-escape.js +22 -2
  260. package/dist/utils/shell-escape.js.map +1 -1
  261. package/dist/utils/vcs-provider-detect.d.ts +65 -0
  262. package/dist/utils/vcs-provider-detect.d.ts.map +1 -0
  263. package/dist/utils/vcs-provider-detect.js +109 -0
  264. package/dist/utils/vcs-provider-detect.js.map +1 -0
  265. package/dist/utils/workspace-trust.d.ts +20 -17
  266. package/dist/utils/workspace-trust.d.ts.map +1 -1
  267. package/dist/utils/workspace-trust.js +87 -1
  268. package/dist/utils/workspace-trust.js.map +1 -1
  269. package/dist/workflows/auto-sprint.js +176 -15
  270. package/package.json +6 -4
  271. package/packages/apra-fleet-client/src/client/api.mjs +319 -17
  272. package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
  273. package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
  274. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +25 -0
  275. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +11 -0
  276. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +37 -2
  277. package/packages/apra-fleet-se/apra-pm/agents/doer.md +36 -12
  278. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +11 -0
  279. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +11 -0
  280. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +9 -0
  281. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +110 -22
  282. package/packages/apra-fleet-se/apra-pm/agents/planner.md +125 -37
  283. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +11 -0
  284. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +13 -2
  285. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
  286. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +1 -1
  287. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -3
  288. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -2
  289. package/packages/apra-fleet-se/bin/cli.mjs +149 -1
  290. package/packages/apra-fleet-se/bin/serve.mjs +78 -4
  291. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +481 -0
  292. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +491 -0
  293. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +282 -0
  294. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +208 -0
  295. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +638 -0
  296. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +301 -0
  297. package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
  298. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +8 -0
  299. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +61 -14
  300. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +516 -0
  301. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +184 -0
  302. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1121 -0
  303. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
  304. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +1 -1
  305. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +276 -0
  306. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +1 -1
  307. package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
  308. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
  309. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +996 -32
  310. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +267 -0
  311. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
  312. package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
  313. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
  314. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +556 -0
  315. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +495 -0
  316. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +564 -0
  317. package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
  318. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +728 -0
  319. package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
  320. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +252 -0
  321. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +581 -0
  322. package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
  323. package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
  324. package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
  325. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +136 -0
  326. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +822 -0
  327. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +294 -0
  328. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +403 -0
  329. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +180 -0
  330. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
  331. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +390 -0
  332. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +323 -0
  333. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +232 -0
  334. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +174 -0
  335. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +197 -0
  336. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +305 -0
  337. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +559 -0
  338. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1416 -0
  339. package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
  340. package/packages/apra-fleet-se/fleet-sprint/runner.js +1467 -9798
  341. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +17 -12
  342. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +304 -0
  343. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +18 -0
  344. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +21 -2
  345. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +454 -0
  346. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +239 -0
  347. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +163 -0
  348. package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
  349. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +211 -0
  350. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1279 -0
  351. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +153 -19
  352. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +71 -21
  353. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
  354. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +131 -0
  355. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +140 -16
  356. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +1 -0
  357. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +77 -2
  358. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
  359. package/packages/apra-fleet-se/package.json +1 -1
  360. package/packages/apra-fleet-workflow/src/viewer/index.mjs +17 -6
  361. package/packages/apra-fleet-workflow/src/workflow/index.mjs +49 -7
  362. package/skills/fleet/SKILL.md +8 -8
  363. package/skills/fleet/auth-azdevops.md +14 -3
  364. package/skills/fleet/auth-bitbucket.md +2 -2
  365. package/skills/fleet/auth-github.md +5 -4
  366. package/skills/fleet/onboarding.md +3 -3
  367. package/skills/fleet/permissions.md +5 -1
  368. package/skills/fleet/profiles/node.json +1 -1
  369. package/skills/fleet/troubleshooting.md +3 -3
  370. package/version.json +1 -1
@@ -0,0 +1,491 @@
1
+ // Child-bead allocation and batched-claim surface for fleet-sprint
2
+ // (apra-fleet-3swo.6.13). Extracted out of runner.js; runner.js re-exports
3
+ // every symbol it previously exported from this region, so existing importers
4
+ // of fleet-sprint/runner.js resolve unchanged.
5
+ //
6
+ // This module owns the bd COMMAND SITES that create/claim/verify child beads:
7
+ // - computeChildFloor: best-effort read of a parent's existing direct
8
+ // children, used to seed the id allocator's floor.
9
+ // - createChildBeadWithAllocatedId: the single bead-creation seam every
10
+ // proposed newTask flows through (allocate -> bd create -> bd update
11
+ // --parent -> confirm/release).
12
+ // - verifyDoerStreakClosed: the orchestrator's post-streak D-pull + `bd
13
+ // show` verification read.
14
+ // - claimBeadsBatched: the batched `bd update ... --claim --json` streak
15
+ // work-claiming call.
16
+ //
17
+ // Deliberately kept OUT of coordination.mjs: coordination.mjs owns the
18
+ // TRANSPORT clients for the child-id allocator and the dolt push mutex
19
+ // (createHttpChildIdAllocatorClient, createMcpChildIdAllocatorClient and
20
+ // friends) -- this module's four functions are the CALLERS that issue bd
21
+ // commands on top of that transport. Mixing them would put a bd command
22
+ // surface inside a module whose whole point is transport.
23
+ //
24
+ // resolveSettleShell did NOT move -- it is module-private composition-root
25
+ // wiring that test/sprint-state.test.mjs anchors to runner.js by symbol, and
26
+ // six of its seven call sites are runner.js's own orchestrator-side settle
27
+ // brackets -- so this module imports it back from runner.js, the same
28
+ // back-import pattern member-sync.mjs already uses.
29
+
30
+ import { parseBdJson } from './beads-scope.mjs';
31
+ import { stageCommandBodyMemberSide } from './member-provisioning.mjs';
32
+ import { DoltSync } from './dolt-sync.mjs';
33
+ import { buildSettleCallback } from './dolt-settle.mjs';
34
+ import { resolveSettleShell } from './runner.js';
35
+
36
+ /**
37
+ * The count of children a parent ALREADY has, i.e. the highest trailing `.N`
38
+ * segment across its direct children. Passed to the allocator as `floor` so
39
+ * that on its FIRST allocation under a parent it never mints an id colliding
40
+ * with a child created before the allocator's persisted state was seeded.
41
+ * Best-effort: a failed or unparseable list yields 0 (the allocator's own
42
+ * persisted high-water still guards against re-minting after that).
43
+ *
44
+ * MUST include closed children (documented `--all` flag): `bd list --parent`
45
+ * excludes closed issues by default, so once every existing child under a
46
+ * parent is closed an unfiltered list would return [], the floor would
47
+ * compute to 0, and the allocator would re-mint already-used ids (`.1`/`.2`,
48
+ * ...) -- the trigger for the id-collision overwrite bug (apra-fleet-btj9).
49
+ * `--all` ("Show all issues including closed") is `bd list`'s documented
50
+ * spelling for this, per `bd list --help` on installed bd 1.1.0 -- `--status
51
+ * all` is undocumented there (it is a documented value for `bd search`'s `-s`
52
+ * flag, not `bd list`'s).
53
+ *
54
+ * SILENT FAILURE, apra-fleet-btj9.3: every failure mode here -- `bd` exiting
55
+ * non-zero on a rejected flag, a dispatch timeout, unparseable JSON --
56
+ * collapses to "this parent has no children", re-seeding the floor to 0 and
57
+ * letting the allocator re-mint an already-used id. The best-effort RETURN
58
+ * VALUE (0) is deliberate and stays; the optional `log` callback below makes
59
+ * the failure itself visible to sprint output instead of vanishing into a
60
+ * bare catch, matching the injected-log convention this module's other
61
+ * functions already use (see createChildBeadWithAllocatedId's/
62
+ * claimBeadsBatched's `log = () => {}` default).
63
+ *
64
+ * SUCCESS-PATH LOG, apra-fleet-btj9.3: a non-zero result is ALSO logged (a
65
+ * zero floor -- the common "parent has no children yet" case -- is not, to
66
+ * stay non-noisy). This is the only externally observable signal that the
67
+ * `--all` closed-children read actually found and counted a prior child,
68
+ * which is what lets a replayed mock-sprint scenario prove end to end that
69
+ * this read reaches a genuine non-zero floor rather than only being covered
70
+ * by the direct unit tests in child-floor-includes-closed-children.test.mjs.
71
+ *
72
+ * @param {{ command: Function, member: string, parentId: string, log?: Function }} opts
73
+ * @returns {Promise<number>}
74
+ */
75
+ export async function computeChildFloor({ command, member, parentId, log = () => {} }) {
76
+ try {
77
+ const label = `bd list --parent ${parentId} --json --all`;
78
+ const raw = await command(label, { member_name: member, silent: true });
79
+ const beads = parseBdJson(raw, label);
80
+ let max = 0;
81
+ const prefix = `${parentId}.`;
82
+ for (const b of beads) {
83
+ if (!b || typeof b.id !== 'string' || !b.id.startsWith(prefix)) continue;
84
+ const tail = b.id.slice(prefix.length);
85
+ // Only a DIRECT child (single trailing numeric segment) counts.
86
+ if (!/^\d+$/.test(tail)) continue;
87
+ const n = Number(tail);
88
+ if (Number.isInteger(n) && n > max) max = n;
89
+ }
90
+ if (max > 0) {
91
+ log(`[id-allocator] computeChildFloor: parent ${parentId} closed-children read found floor ${max}`);
92
+ }
93
+ return max;
94
+ } catch (err) {
95
+ log(`[id-allocator] computeChildFloor: bd list --parent ${parentId} --json --all failed or was unparseable (${err.message}); falling back to floor 0`);
96
+ return 0;
97
+ }
98
+ }
99
+
100
+ /**
101
+ * Classifies a `bd show <id> --json` probe failure (apra-fleet-btj9.6) into
102
+ * one of two outcomes, so the collision guard above can tell a genuine "the
103
+ * id is free" result apart from "the probe itself could not be evaluated":
104
+ *
105
+ * - 'absent': the thrown error's payload positively matches bd's documented
106
+ * no-such-issue shape (`{"error": "no issues found matching the provided
107
+ * IDs", ...}`, verified against installed bd 1.1.0). This is the ordinary,
108
+ * expected outcome of probing a genuinely free id.
109
+ * - 'unknown': anything else -- unparseable output, a differently-shaped
110
+ * error payload, a transport/dispatch fault. The caller MUST fail closed
111
+ * on this outcome rather than assume the id is free.
112
+ *
113
+ * Reads `probeErr.details.text` first (the raw stdout a typed CommandError
114
+ * carries, see packages/apra-fleet-workflow/src/workflow/errors.mjs) and
115
+ * falls back to `probeErr.message` (which production's FleetWorkflow.command()
116
+ * also embeds the same raw stdout into, e.g. `Exit code 1: {...}`) for
117
+ * callers/fakes that only ever throw a plain Error.
118
+ *
119
+ * @param {Error} probeErr
120
+ * @returns {'absent'|'unknown'}
121
+ */
122
+ export function classifyBdShowProbeError(probeErr) {
123
+ const text = (probeErr && probeErr.details && typeof probeErr.details.text === 'string')
124
+ ? probeErr.details.text
125
+ : (probeErr && typeof probeErr.message === 'string' ? probeErr.message : '');
126
+ const match = text.match(/\{[\s\S]*\}/);
127
+ if (match) {
128
+ try {
129
+ const parsed = JSON.parse(match[0]);
130
+ if (parsed && typeof parsed.error === 'string' && /no issues found/i.test(parsed.error)) {
131
+ return 'absent';
132
+ }
133
+ } catch {
134
+ // Not JSON, or not the expected shape -- fall through to unknown.
135
+ }
136
+ }
137
+ return 'unknown';
138
+ }
139
+
140
+ /**
141
+ * The probe-and-refuse half of the explicit-id collision guard, extracted
142
+ * (apra-fleet-btj9.7) out of createChildBeadWithAllocatedId's inline block so
143
+ * it is a single reusable, exported seam rather than logic private to that one
144
+ * function. `bd create --id <id>` SILENTLY OVERWRITES an existing bead (open
145
+ * OR closed) that already holds that id -- it reuses the same row and
146
+ * clobbers its title/description/priority/type with no error. This function
147
+ * probes for an existing bead at `childId` FIRST and throws rather than let
148
+ * the caller proceed into an overwrite:
149
+ *
150
+ * - ABSENT (the common, expected case): resolves normally, no throw.
151
+ * - PRESENT: throws, naming the existing bead's status.
152
+ * - UNKNOWN (the probe itself could not be evaluated -- unparseable output,
153
+ * an unrecognized error payload, a transport/dispatch fault): throws,
154
+ * FAILING CLOSED rather than assuming the id is free (apra-fleet-btj9.6).
155
+ *
156
+ * Does NOT touch the allocator reservation itself (release/confirm) -- that
157
+ * stays the caller's responsibility, exactly as it was before extraction, so
158
+ * a future caller with a different reservation lifecycle can reuse this probe
159
+ * without inheriting allocator-specific side effects.
160
+ *
161
+ * @param {{ command: Function, member: string, childId: string, parentId: string }} opts
162
+ * @returns {Promise<void>}
163
+ */
164
+ export async function assertChildIdFree({ command, member, childId, parentId }) {
165
+ const probeLabel = `bd show ${childId} --json`;
166
+ let existing = null;
167
+ try {
168
+ const raw = await command(probeLabel, { member_name: member, silent: true });
169
+ const beads = parseBdJson(raw, probeLabel);
170
+ const list = Array.isArray(beads) ? beads : (beads ? [beads] : []);
171
+ existing = list.find((b) => b && b.id === childId) || null;
172
+ } catch (probeErr) {
173
+ // VERIFIED against installed bd 1.1.0 (8e4e59d3): `bd show
174
+ // <missing-id> --json` does NOT yield `[]` -- it exits non-zero and
175
+ // prints `{"error": "no issues found matching the provided IDs",
176
+ // "schema_version": 1}`. So the free-id case (the common, expected
177
+ // outcome of this probe) always lands here, indistinguishable at
178
+ // the throw site alone from a genuine dispatch fault. Classify the
179
+ // catch into ABSENT (bd positively reported no such issue -- proceed)
180
+ // vs UNKNOWN (anything else -- the probe could not be evaluated).
181
+ //
182
+ // FleetWorkflow.command() (packages/apra-fleet-workflow/src/workflow
183
+ // /index.mjs _commandDispatch) DOES surface the child process's raw
184
+ // stdout on a non-zero exit: a typed CommandError carries it on
185
+ // `.details.text`, and its `.message` also embeds it (`Exit code N:
186
+ // ${outText}`). That makes option 1 (parse the error payload)
187
+ // implementable, so it is used here rather than the parent-listing
188
+ // probe alternative.
189
+ const outcome = classifyBdShowProbeError(probeErr);
190
+ if (outcome === 'absent') {
191
+ // The id is free -- the common path. Stay fast and non-noisy:
192
+ // no log line, proceed to create exactly as before.
193
+ existing = null;
194
+ } else {
195
+ // UNKNOWN: the probe itself could not be evaluated (unparseable
196
+ // or unrecognized error payload, e.g. a transient dispatch
197
+ // fault). FAIL CLOSED rather than silently degrading back into
198
+ // the overwrite behavior apra-fleet-btj9 exists to prevent.
199
+ throw new Error(
200
+ `[id-allocator] refusing to create child bead at id '${childId}': the collision probe could not be ` +
201
+ `evaluated (${probeErr.message}) -- treating as UNKNOWN, not a confirmed-free id. Released the reservation ` +
202
+ 'rather than risking an overwrite.',
203
+ );
204
+ }
205
+ }
206
+ if (existing) {
207
+ throw new Error(
208
+ `[id-allocator] refusing to create child bead at id '${childId}': a bead with that id already exists ` +
209
+ `(status: ${existing.status ?? 'unknown'}); a 'bd create --id' on that id would silently overwrite it. ` +
210
+ 'Released the reservation rather than clobbering the existing bead.',
211
+ );
212
+ }
213
+ }
214
+
215
+ /**
216
+ * Create a child bead under `parentId` using an allocator-minted,
217
+ * collision-free explicit id. This is the single bead-creation seam every
218
+ * proposed newTask flows through, so that two concurrent sprints never mint
219
+ * the same child id.
220
+ *
221
+ * Sequence (mirrors the allocator's reserve -> confirm/release contract):
222
+ * 1. allocate() reserves the next distinct child id under the shared parent.
223
+ * 1a. Explicit-id path only: probe (`bd show <childId> --json`) that no bead
224
+ * already holds that id. `bd create --id` SILENTLY OVERWRITES an existing
225
+ * bead, so a collision releases the reservation and throws rather than
226
+ * clobbering it.
227
+ * 2. `bd create` runs with `--id <childId>` (or, under the null client where
228
+ * childId is null, lets bd derive the id from `--parent`).
229
+ * 3. confirm() as soon as `bd create` lands (the id is now durably used --
230
+ * release() from here on would hand out an id that is genuinely
231
+ * occupied, apra-fleet-btj9.2). release() only fires if step 2 itself
232
+ * (staging the description or the `bd create` dispatch) fails, so the
233
+ * reserved id returns to the pool with no permanent gap. confirm()
234
+ * ITSELF can fail (allocator transport fault, apra-fleet-btj9.5); that
235
+ * failure is caught (never released -- the bead already exists) and
236
+ * reported via a distinct orphan-naming error after step 4 runs.
237
+ * 4. On the explicit-id path only, a follow-up `bd update <childId> --parent
238
+ * <parentId>` establishes the real parent edge, attempted regardless of
239
+ * whether confirm() in step 3 failed. A failure here does NOT release
240
+ * the reservation (the bead already exists) -- it throws a distinct
241
+ * "created but UNLINKED" error naming the orphan id so an operator can
242
+ * re-link it, rather than leaving the id allocator's next probe hit a
243
+ * confusing already-exists refusal. If step 3's confirm() ALSO failed,
244
+ * that failure is reported instead (with the link outcome folded in),
245
+ * never masked by this one.
246
+ *
247
+ * `bd create` REJECTS `--id` and `--parent` together, so on the explicit-id
248
+ * path `--parent` must be dropped: the allocator's `${parentId}.${seq}` id
249
+ * shape already encodes the hierarchy. A dotted id alone does NOT record the
250
+ * explicit parent edge, which is what the separate `bd update --parent`
251
+ * supplies; that link step is deliberately NOT best-effort -- a failure
252
+ * throws and degrades loudly rather than leaving an edgeless child, but
253
+ * (unlike the create step) it does NOT release the reservation, because by
254
+ * that point the bead genuinely exists at the allocated id.
255
+ *
256
+ * @param {{
257
+ * command: Function, allocator: { allocate: Function, confirm: Function, release: Function },
258
+ * member: string, title: string, description: string, priority: string,
259
+ * parentId: string, sprintId?: string, floor?: number, label?: string,
260
+ * log?: Function,
261
+ * }} opts
262
+ * @returns {Promise<{ childId: string|null }>}
263
+ */
264
+ export async function createChildBeadWithAllocatedId(opts) {
265
+ const { command, allocator, member, title, description, priority, parentId, sprintId, floor, label, log = () => {} } = opts;
266
+ const grant = await allocator.allocate(parentId, { pid: process.pid, sprintId, floor });
267
+ // The explicit-id path relies on the allocator's `${parentId}.${seq}` id
268
+ // shape to carry the hierarchy that `--parent` can no longer carry
269
+ // alongside `--id` (see the doc comment above). Fail loudly rather than
270
+ // create a child whose id does not place it under this parent at all.
271
+ if (grant.childId && !String(grant.childId).startsWith(`${parentId}.`)) {
272
+ await allocator.release(grant.token);
273
+ throw new Error(
274
+ `[id-allocator] allocated child id '${grant.childId}' is not a child of parent '${parentId}' ` +
275
+ '(expected the `<parentId>.<seq>` shape); released the reservation rather than creating an unparented bead',
276
+ );
277
+ }
278
+ // Collision guard: `bd create --id <childId>` SILENTLY OVERWRITES an
279
+ // existing bead (open OR closed) that already holds that id -- it reuses the
280
+ // same row and clobbers its title/description/priority/type with no error.
281
+ // The allocator should never hand back an in-use id, but a crashed/partial
282
+ // prior run, a stale persisted high-water, or a manually-created bead can
283
+ // leave one occupied. So on the explicit-id path only, probe for an existing
284
+ // bead at that id FIRST via the shared assertChildIdFree() seam (apra-fleet-
285
+ // btj9.7) and REFUSE (release the reservation, throw loudly) rather than
286
+ // overwrite. The null-allocator path (`bd create --parent`) lets bd mint a
287
+ // fresh id natively and never collides, so it needs no probe.
288
+ if (grant.childId) {
289
+ try {
290
+ await assertChildIdFree({ command, member, childId: grant.childId, parentId });
291
+ } catch (probeErr) {
292
+ await allocator.release(grant.token);
293
+ throw probeErr;
294
+ }
295
+ }
296
+ // `bd create` refuses `--id` together with `--parent`: carry EITHER the
297
+ // allocator-minted explicit id (hierarchy encoded in the id, parent edge
298
+ // linked immediately after the create) OR `--parent` and let bd derive the
299
+ // id (null-allocator path).
300
+ const parentageFlags = grant.childId ? `--id ${grant.childId}` : `--parent ${parentId}`;
301
+ // The description is LLM-authored free text: stage it to a member-local
302
+ // temp file (see stageCommandBodyMemberSide) and hand THAT path to `bd
303
+ // create --body-file` rather than interpolating it into the shell command
304
+ // string. Only `title` (short, allowlist-validated by validateNewTask)
305
+ // remains inline.
306
+ try {
307
+ const descriptionFile = await stageCommandBodyMemberSide({
308
+ command, member, content: description,
309
+ label: `Stage newTask description for '${title}'`,
310
+ });
311
+ await command(
312
+ `bd create "${title}" --body-file "${descriptionFile}" -p "${priority}" ${parentageFlags} --silent`,
313
+ { member_name: member, silent: true, label: label ?? `Create follow-up task: ${title}` }
314
+ );
315
+ } catch (err) {
316
+ // The create did NOT land -- return the reserved id to the pool so the
317
+ // next allocation reuses it (no permanent gap), then re-throw.
318
+ await allocator.release(grant.token);
319
+ log(`[id-allocator] bd create failed for '${grant.childId ?? '(bd-derived)'}'; released reservation: ${err.message}`);
320
+ throw err;
321
+ }
322
+ // The create landed locally -- durably commit the id BEFORE the D-push, so a
323
+ // crash after this point can never reclaim an id that now genuinely exists.
324
+ // From here on the reservation MUST stay confirmed: the bead already
325
+ // exists at grant.childId (or bd's own derived id), so releasing it back
326
+ // to the pool after this point would hand out an id that is genuinely
327
+ // occupied -- the exact collision assertChildIdFree exists to refuse
328
+ // (apra-fleet-btj9.2).
329
+ //
330
+ // confirm() itself can fail (an HTTP allocator route erroring, an MCP
331
+ // transport fault, a supervisor restart) -- apra-fleet-btj9.5. That
332
+ // failure sits OUTSIDE any release-on-failure try/catch, by design: the
333
+ // bead already exists at this id, so release() must NEVER fire here,
334
+ // exactly as for a link failure below. Capture the error instead of
335
+ // letting it propagate raw, so the caller gets an orphan-naming message
336
+ // rather than a bare transport-fault string with no indication that a
337
+ // child bead now exists, is possibly unlinked, and may not be durably
338
+ // confirmed in the allocator's own state.
339
+ let confirmError = null;
340
+ try {
341
+ await allocator.confirm(grant.token);
342
+ } catch (err) {
343
+ confirmError = err;
344
+ log(`[id-allocator] bd create landed for '${grant.childId ?? '(bd-derived)'}' but allocator.confirm() failed; reservation stays UNRELEASED (the id is genuinely in use) but may not be durably confirmed in the allocator's own state: ${err.message}`);
345
+ }
346
+ // Explicit-id path only: record the real parent edge that `--parent`
347
+ // would have recorded, had bd allowed it on the same create. Deliberately
348
+ // OUTSIDE the create's release-on-failure try/catch above: a failure here
349
+ // must not release grant.token (the id is already in use, not free) and
350
+ // must not be conflated with the create's own failure. Throw a distinct,
351
+ // orphan-naming error instead so an operator can re-link rather than hit
352
+ // an inexplicable id-already-exists refusal on the next newTask under
353
+ // this parent.
354
+ //
355
+ // DECISION (apra-fleet-btj9.5): the link is attempted even when confirm()
356
+ // above already failed. confirm() talks to the id-allocator's own
357
+ // bookkeeping (HTTP/MCP transport); the link is a separate `bd update`
358
+ // dispatch against bd itself, and a fault in the former says nothing
359
+ // about whether the latter would also fail -- attempting it anyway means
360
+ // a transient confirm blip does not ALSO cost the parent edge. If the
361
+ // link then also fails, the confirm failure is still reported (it is the
362
+ // more actionable signal: durable allocator state is what guards against
363
+ // a future re-mint) with the link outcome folded into the SAME message,
364
+ // rather than thrown separately, so the confirm failure is never masked
365
+ // by a later link error.
366
+ let linkError = null;
367
+ if (grant.childId) {
368
+ try {
369
+ await command(
370
+ `bd update ${grant.childId} --parent ${parentId}`,
371
+ { member_name: member, silent: true, label: `Link follow-up task ${grant.childId} under ${parentId}` }
372
+ );
373
+ } catch (err) {
374
+ linkError = err;
375
+ log(`[id-allocator] bd create landed for '${grant.childId}' but the follow-up bd update --parent link failed; reservation stays confirmed (the id is genuinely in use): ${err.message}`);
376
+ }
377
+ }
378
+ if (confirmError) {
379
+ const idLabel = grant.childId ?? '(bd-derived id, unknown to the allocator)';
380
+ throw new Error(
381
+ `[id-allocator] child bead '${idLabel}' was created but allocator.confirm() FAILED: ${confirmError.message}. ` +
382
+ `The bead exists at that id and is ${linkError ? 'also UNLINKED from' : 'linked under'} parent '${parentId}', ` +
383
+ "and the reservation may not be durably confirmed in the allocator's own state -- do NOT release this id; " +
384
+ 'investigate the allocator directly rather than retrying newTask under this parent.' +
385
+ (linkError ? ` (the follow-up parent-link dispatch also failed: ${linkError.message})` : ''),
386
+ );
387
+ }
388
+ if (linkError) {
389
+ throw new Error(
390
+ `[id-allocator] child bead '${grant.childId}' was created but is UNLINKED under parent '${parentId}': ` +
391
+ `the follow-up 'bd update ${grant.childId} --parent ${parentId}' failed (${linkError.message}). The id is ` +
392
+ 'genuinely in use -- re-link it manually rather than retrying newTask under this parent.',
393
+ );
394
+ }
395
+ return { childId: grant.childId ?? null };
396
+ }
397
+
398
+ /**
399
+ * The orchestrator's post-streak verification read, with its mandatory
400
+ * D-pull. A remote doer closes its assigned beads in its OWN clone and
401
+ * D-pushes them, so the orchestrator MUST D-pull its own clone BEFORE the `bd
402
+ * show` -- otherwise it reads stale (still-open) status and falsely reports
403
+ * every remote doer streak as FAILED.
404
+ *
405
+ * Returns the ids that are NOT closed after the D-pull-then-read. An empty
406
+ * array means the streak genuinely closed everything it was assigned.
407
+ *
408
+ * @param {{ command: Function, orchestratorMember: string, beadIds: string[], log?: Function, args?: { callTool?: Function }, sprintState?: object }} opts
409
+ * @returns {Promise<string[]>} the still-unclosed bead ids
410
+ */
411
+ export async function verifyDoerStreakClosed({ command, orchestratorMember, beadIds, log = () => {}, args, sprintState }) {
412
+ // D-pull FIRST so the orchestrator's clone observes the doer's just-pushed
413
+ // closes. Routed through the single dolt-sync module's purpose-based BEFORE
414
+ // bracket (apra-fleet-417.2.1); behavior is identical to the previous
415
+ // direct doltPullBefore() call.
416
+ // Thread the orchestrator member's REGISTERED shell into dolt-settle,
417
+ // guarded on args.callTool the same way the pre-dispatch bracket is
418
+ // (apra-fleet-7dir.24).
419
+ const shell = await resolveSettleShell({ args, member: orchestratorMember, log, sprintState });
420
+ await DoltSync.syncBefore(orchestratorMember, { command, log, fatal: true, settle: buildSettleCallback(orchestratorMember, { command, log, shell }) });
421
+ const label = `bd show ${beadIds.join(' ')} --json`;
422
+ const showRes = await command(label, { member_name: orchestratorMember, silent: true });
423
+ const showBeads = parseBdJson(showRes, label);
424
+ const statusById = new Map(showBeads.map((b) => [b.id, b.status]));
425
+ return beadIds.filter((id) => statusById.get(id) !== 'closed');
426
+ }
427
+
428
+ /**
429
+ * Batched per-streak work-claiming (apra-fleet-7h6n.7, audit R6): claims
430
+ * every id in `beadIds` with ONE `bd update <id...> --claim --json`
431
+ * invocation instead of one `bd update <id> --claim` call per bead.
432
+ *
433
+ * RESEARCH FINDING this batching relies on (verified against real `bd`
434
+ * 1.1.0, both by reading `bd update --help`'s `Usage: bd update [id...]`
435
+ * and by exercising a scratch sandbox DB): `bd update` DOES accept a
436
+ * variadic id list, and `--claim --json` on a MULTI-id invocation returns a
437
+ * JSON array containing ONLY the issues that were successfully claimed --
438
+ * an id that fails to resolve, or is already claimed by a DIFFERENT
439
+ * assignee, is silently dropped from the array (its error goes to stderr,
440
+ * not stdout) rather than aborting the whole call. Two non-obvious
441
+ * consequences, both load-bearing for this function's design:
442
+ * 1. This is NOT atomic in the transactional sense -- ids before a
443
+ * failing one are still committed, there is no all-or-nothing
444
+ * rollback. It IS enough to cut the streak's claim step from N
445
+ * subprocess spawns to 1, which is this bead's actual goal.
446
+ * 2. The process exit code stays 0 even when SOME ids in the batch
447
+ * failed to claim (verified: a lone failing id exits 1, but the exact
448
+ * same failure mixed into a multi-id batch with a succeeding id exits
449
+ * 0) -- so, unlike the old single-id-per-call loop, success can NEVER
450
+ * be inferred from "command() did not throw". The returned JSON array
451
+ * is the only reliable signal, which is why this function always
452
+ * diffs `beadIds` against the parsed array rather than relying on a
453
+ * catch block.
454
+ *
455
+ * A total call failure (command() itself throws -- e.g. a transient
456
+ * dispatch/network fault reaching the member) is treated the same way the
457
+ * old loop treated "every id failed": every id is reported skipped, never
458
+ * thrown, so one bad batch degrades the streak (all its beads stay
459
+ * unclaimed, caller decides whether to skip the streak) rather than
460
+ * crashing the sprint.
461
+ *
462
+ * @param {{ command: Function, orchestratorMember: string, beadIds: string[], log?: Function }} opts
463
+ * @returns {Promise<{ claimedBeadIds: string[], skippedBeadIds: string[] }>}
464
+ */
465
+ export async function claimBeadsBatched({ command, orchestratorMember, beadIds, log = () => {} }) {
466
+ if (!Array.isArray(beadIds) || beadIds.length === 0) {
467
+ return { claimedBeadIds: [], skippedBeadIds: [] };
468
+ }
469
+ const label = `bd update ${beadIds.join(' ')} --claim --json`;
470
+ let raw;
471
+ try {
472
+ raw = await command(label, { member_name: orchestratorMember, silent: true });
473
+ } catch (err) {
474
+ // A dispatch/exec-level failure (member unreachable, transient
475
+ // network fault) degrades gracefully -- every id in this batch
476
+ // stays unclaimed, same as the old per-id loop's catch-and-skip.
477
+ // This is DISTINCT from a malformed-JSON parse failure below, which
478
+ // stays fatal (per parseBdJson's own doc comment: a parse failure
479
+ // must be LOUD, never silently swallowed as "everything skipped").
480
+ log(`Batched claim failed for [${beadIds.join(', ')}]: ${err.message}`);
481
+ return { claimedBeadIds: [], skippedBeadIds: [...beadIds] };
482
+ }
483
+ const claimed = parseBdJson(raw, label);
484
+ const claimedIds = new Set((Array.isArray(claimed) ? claimed : []).map((b) => b && b.id).filter(Boolean));
485
+ const claimedBeadIds = beadIds.filter((id) => claimedIds.has(id));
486
+ const skippedBeadIds = beadIds.filter((id) => !claimedIds.has(id));
487
+ if (skippedBeadIds.length > 0) {
488
+ log(`Batched claim: claimed ${claimedBeadIds.length} bead(s) [${claimedBeadIds.join(', ')}]; skipped ${skippedBeadIds.length} already-claimed/unresolvable bead(s) [${skippedBeadIds.join(', ')}].`);
489
+ }
490
+ return { claimedBeadIds, skippedBeadIds };
491
+ }