@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
@@ -30,8 +30,14 @@ orchestrator that planning has no input to work from -- do not create speculativ
30
30
 
31
31
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
32
32
 
33
+ <!-- if-tool: ToolSearch -->
33
34
  1. Run ToolSearch with query
34
35
  `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_stats,mcp__apra-fleet__kb_capture,mcp__apra-fleet__kb_feedback"`
36
+ <!-- else-tool: ToolSearch -->
37
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
38
+ tool it wants directly. Confirm your environment exposes those tools, then call
39
+ them as written.
40
+ <!-- end-tool: ToolSearch -->
35
41
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo you are
36
42
  planning for, and `hint_symbols`/`hint_modules` derived from the sprint goals /
37
43
  requirements you are about to decompose (skim them first to extract key symbol
@@ -64,7 +70,12 @@ orchestrator that planning has no input to work from -- do not create speculativ
64
70
  5. If a KB entry you retrieved proves wrong in practice, call `mcp__apra-fleet__kb_feedback`
65
71
  with the entry id and what was wrong.
66
72
 
73
+ <!-- if-tool: ToolSearch -->
67
74
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
75
+ <!-- else-tool: ToolSearch -->
76
+ If those KB tools are not available in your environment (MCP server not running), skip
77
+ these steps and proceed.
78
+ <!-- end-tool: ToolSearch -->
68
79
 
69
80
  ## Step 1 -- Explore the backlog
70
81
 
@@ -96,6 +107,23 @@ anywhere in the title, so the doubled `[regression][carry-over]` prefix is found
96
107
  extra quoting; and it EXCLUDES closed issues by default -- add `--status all` only when
97
108
  auditing history.
98
109
 
110
+ **Read NOTES before decomposing.** Before decomposing any bead -- sprint goal, feature,
111
+ or task -- that has a non-empty NOTES section, read NOTES in full, in chronological
112
+ order, as part of understanding the bead's current scope, not merely as optional
113
+ background context. A bead's NOTES section functions as an append-only changelog:
114
+ corrections, amendments, and design-review findings accumulate there over the bead's
115
+ lifetime, often after its DESCRIPTION was written. Treat a NOTES entry that explicitly
116
+ corrects, amends, or supersedes something in DESCRIPTION -- recognizable by language such
117
+ as "CORRECTION", "AMENDMENT", "SUPERSEDES", "REVISED", or an explicit "do X, not Y"
118
+ statement -- as authoritative over the DESCRIPTION passage it contradicts. When writing a
119
+ child's own DESCRIPTION/acceptance criteria (Steps 2 and 3 below), do not copy stale
120
+ DESCRIPTION language verbatim if a later NOTES entry corrected it -- write the child from
121
+ the corrected understanding. It is fine, and often preferable, for the child to
122
+ explicitly cite which correction it incorporates, so a later reader does not need to
123
+ cross-reference the parent's full history. This does not change how you decompose a bead
124
+ whose NOTES is empty or purely procedural (e.g. claim/close log lines) -- it applies only
125
+ when NOTES contains substantive corrections to DESCRIPTION.
126
+
99
127
  ## Step 2 -- Decompose sprint goals into features
100
128
 
101
129
  Every title you write below (Steps 2 and 3) is plain text only -- letters,
@@ -121,7 +149,11 @@ making them independent siblings.
121
149
  For each feature create two classes of tasks:
122
150
 
123
151
  **Implementation tasks** (`[impl]` prefix optional but helpful):
124
- - One task per cohesive code change (1-3 file changes max)
152
+ - One task per independently verifiable change. A task is the unit the doer commits and
153
+ closes; the LANE (below) is the unit the reviewer reviews. Keep a task small enough to
154
+ have crisp acceptance criteria (typically 1-4 files), but do NOT split a change into
155
+ several tasks just to keep each one small -- a chain of tiny dependent tasks is more
156
+ expensive to review than one lane that holds them together.
125
157
  - Title: specific and imperative ("Add password reset endpoint to auth router")
126
158
  - Description includes: expected files to change, expected behaviour, acceptance
127
159
  criteria. The file list is a best-effort scope estimate, NOT an allowlist -- phrase it
@@ -182,35 +214,75 @@ Pick from the models actually available in the current environment. A user overr
182
214
  always wins.
183
215
 
184
216
  **Streak lane metadata** (required on every task, both impl and test): in addition to
185
- `model`, record two lane fields through the SAME beads metadata channel at creation time --
217
+ `model`, record three lane fields through the SAME beads metadata channel at creation time --
186
218
  never in `--notes`, a METADATA-section comment, or anywhere else:
187
219
  ```bash
188
- bd create ... --metadata '{"model": "<cheap|standard|premium>", "streak": "<lane-id>", "streakOrder": <n>}'
220
+ bd create ... --metadata '{"model": "<cheap|standard|premium>", "size": "<S|M|L>", "streak": "<lane-id>", "streakOrder": <n>}'
189
221
  ```
190
222
  - `streak` -- a stable lane identifier (any short opaque string) shared by every task to
191
223
  be dispatched together to a single doer; read back via `bd show <id>` like `model`.
192
224
  - `streakOrder` -- an integer giving this task's intended position within its lane. Lower
193
- runs first; ties fall back to the existing `blocks` edges (see the graph-semantics
194
- section above).
195
-
196
- Group tasks into lanes for high cohesion, following these rules:
197
- - An `[impl]` task and its paired `[test]` task co-streak by default (they share one
198
- `streak`), so the doer that writes the code also runs its test in the same session.
199
- - Tasks that contend for a **mutex resource** -- a resource only one change may hold at a
200
- time, e.g. the same submodule pointer, a shared version/manifest field, or the same test
201
- fixture -- MUST share a lane and MUST NOT be separated into different streaks.
202
-
203
- **Effort-point splitting math.** Before finalizing a lane, size it so a single streak stays
204
- within one doer's reach:
205
- - size points per task: `S=1`, `M=2`, `L=4`
206
- - model weight per tier: `cheap=1`, `standard=10`, `premium=20`
207
- - `effort = (sum of size points over the lane's tasks) x (max model weight in the lane)`
208
-
209
- If a lane's `effort` exceeds the effort threshold constant (default `200`), split it into
210
- two or more streaks. Split ONLY at a `blocks`-edge boundary -- so each resulting streak is a
211
- contiguous prefix/suffix of the dependency order, never an arbitrary mid-lane cut -- and
212
- NEVER separate mutex-resource members (above) across the split, even if honoring that leaves
213
- a streak over threshold. Give each split streak a fresh `streak` id and renumber
225
+ runs first; ties break by insertion order -- do NOT use a `blocks` edge to break an
226
+ intra-lane tie (see the dependency-wiring rules below).
227
+ - `size` -- `S`/`M`/`L`, used for lane sizing below.
228
+
229
+ **Lanes are review units.** The engine dispatches every task in one lane to ONE doer in
230
+ `streakOrder`, and the reviewer reviews a whole Develop ROUND at once -- every lane
231
+ dispatched in that round together. A lane is therefore the SMALLEST thing a review can
232
+ cover: never split one coherent increment across two lanes joined by a `blocks` edge,
233
+ because each extra link in that chain costs a full review round (diff read + full test
234
+ run). Lanes with no `blocks` edge between them dispatch and review in the SAME round
235
+ whenever the round's doer count and effort budget allow (unlaned-but-independent lanes
236
+ overflow to the next round only under doer/budget pressure, not because they were kept
237
+ separate), so normally that costs nothing extra -- keep genuinely independent work in
238
+ separate lanes rather than merging it for size alone; merging removes parallelism without
239
+ reliably saving a review.
240
+
241
+ Put tasks in the SAME lane when they are highly coupled or cohesive -- any of:
242
+ - they touch the same files, module, or component, or the same test suite;
243
+ - one exists to enable the next (add a helper, then use it; change a schema, then its
244
+ consumer; implement, then its `[test]` task) -- an `[impl]` task and its paired `[test]`
245
+ task ALWAYS share a lane, UNLESS the feature's impl work itself had to span multiple
246
+ lanes under the sizing rules below -- then the feature's `[test]` task takes the LAST
247
+ impl lane, or ends its own final lane wired cross-lane to every impl lane it verifies;
248
+ - they contend for a **mutex resource** -- a resource only one change may hold at a time,
249
+ e.g. the same submodule pointer, a shared version/manifest field, or the same test
250
+ fixture -- these MUST share a lane and MUST NOT be separated into different streaks;
251
+ - reviewing one without the other would leave the reviewer unable to judge whether the
252
+ feature actually works.
253
+
254
+ Put tasks in DIFFERENT lanes only when at least one of these holds:
255
+ - they are genuinely independent (different feature areas, no shared files, no enabling
256
+ relationship) -- so multiple doers can run them in parallel;
257
+ - they sit on different sides of a RISK BOUNDARY: a change the reviewer must sign off
258
+ before further work is safe to build on (a public contract change, a data migration, a
259
+ security-sensitive path, a destructive operation);
260
+ - a later task cannot be reviewed until the earlier one's outcome has been judged (true
261
+ design uncertainty) -- write the later task's criteria as conditional on that outcome,
262
+ not left blank, and state the dependency explicitly in its description so the criteria
263
+ are never read as unconditional; the earlier task ends its lane, and the later one
264
+ starts a new lane in the next round;
265
+ - the lane would exceed the sizing limits below.
266
+
267
+ **Sizing a lane.** Size buckets are the same ones the plan reviewer classifies with:
268
+ S = 1 file/narrow, M = 2-3 files/moderate logic, L = 3+ files or non-trivial design (see
269
+ the `bd create ... --metadata` example above -- `size` is recorded there, alongside
270
+ `model`/`streak`/`streakOrder`, not as a separate call). Then check each lane against
271
+ these LANE SIZING PARAMETERS (fixed defaults for now -- no per-dispatch override channel
272
+ exists yet):
273
+ - `laneMaxTasks` (default `6`): hard cap on tasks per lane -- a reviewer must be able to
274
+ verify the whole lane in one pass.
275
+ - `laneMaxEffort` (default `200`): `effort = (sum of size points S=1/M=2/L=4) x (max model
276
+ weight in the lane, cheap=1/standard=10/premium=20)`; caps one doer session's load.
277
+ - `laneTargetEffort` (default `60`): a lane BELOW this that has a cohesive neighbour (per
278
+ the SAME-lane rules above) should be MERGED with it, not left as its own review round.
279
+ State in the lane's first task description why a lane was left below target if it was.
280
+
281
+ A lane over either cap is split ONLY at a point where the earlier part is a self-contained,
282
+ reviewable increment (never mid-refactor, never between mutex-resource members). An
283
+ `[impl]` lane may be split from its feature's `[test]` task ONLY as the exception above
284
+ describes -- the test task then ends the chain, cross-lane blocked on every impl lane it
285
+ verifies; it is never itself mid-split. Give each part its own `streak` id and renumber
214
286
  `streakOrder` from the start within it.
215
287
 
216
288
  Wire dependencies (semantics: `bd dep add A B` means A is blocked by B -- B must finish before A can close):
@@ -218,9 +290,16 @@ Wire dependencies (semantics: `bd dep add A B` means A is blocked by B -- B must
218
290
  do NOT `bd dep add <feature-id> <impl-task>` or `<feature-id> <test-task>`; a feature's
219
291
  "not done until its tasks close" status comes from its children, never from a `blocks`
220
292
  edge back onto them)
221
- - `bd dep add <test-task> <impl-task>` (test task blocked until impl task is done -- this
222
- IS correct: impl-task and test-task are siblings, not ancestor/descendant)
223
- - For tasks that depend on a prior sibling task: `bd dep add <later-task> <earlier-task>`
293
+ - INSIDE a lane, order comes from `streakOrder` ONLY. Do NOT add a `blocks` edge between
294
+ two tasks in the same lane -- the engine dispatches only currently-unblocked tasks, so an
295
+ intra-lane edge would push the later task into a separate review round and silently
296
+ defeat the lane. This includes the `[test]` task: it follows its `[impl]` task by
297
+ `streakOrder`, not by an edge.
298
+ - BETWEEN lanes, order comes from `blocks` edges: when lane B must not start until lane A
299
+ is done, add `bd dep add <B-task> <A-last-task>` for EVERY task in lane B against the
300
+ LAST (highest `streakOrder`) task of lane A. Wiring only B's first task would let B's
301
+ later tasks become ready out of order.
302
+ - Sibling tasks in different lanes with no enabling relationship get no edge.
224
303
 
225
304
  ## Step 4 -- Validate your own DAG
226
305
 
@@ -257,11 +336,18 @@ direction, and re-run the scoped `--ready` query to confirm issues are unblocked
257
336
  Also check each open feature:
258
337
  - Has at least one [impl] task AND one [test] task?
259
338
  - Every task description has clear acceptance criteria?
260
- - No task spans more than ~3 file changes?
261
- - Test tasks are downstream of implementation tasks?
262
- - Every task has a model tier set via `--metadata '{"model": "..."}'` (see Step 3)?
263
- - Every task carries `streak` and `streakOrder` lane metadata (see Step 3)? Impl/test
264
- pairs and mutex-resource members co-laned, and no lane's effort exceeds the threshold?
339
+ - Every task carries `model`, `size`, `streak`, `streakOrder` metadata via `--metadata`
340
+ (see Step 3) -- never `--notes`?
341
+ - Does every lane hold ONE reviewable increment (impl + its test, all mutex members, all
342
+ enabling chains), within `laneMaxTasks` / `laneMaxEffort`?
343
+ - Is every lane below `laneTargetEffort` either justified in its first task description or
344
+ merged with a cohesive neighbour?
345
+ - Is there NO `blocks` edge between two tasks that share a `streak` id?
346
+ - Does every cross-lane `blocks` edge target the upstream lane's LAST task and originate
347
+ from EVERY task of the downstream lane?
348
+ - Expected review rounds (= longest chain of lanes joined by `blocks` edges): state the
349
+ number in your `notes`. If it exceeds 3 for one sprint goal, re-examine whether the
350
+ chain can be shortened by merging lanes.
265
351
  - Where `kb_stats` backed a model tier choice, does the task description cite the
266
352
  coverage number (see Step 3)? Not required for tiers set on qualitative KB signals
267
353
  alone or when `kb_stats` was unavailable.
@@ -290,7 +376,7 @@ array (see Step 0.4 -- omit or send `[]` to capture nothing). Example instance:
290
376
  ```json
291
377
  {
292
378
  "status": "OK",
293
- "notes": "Created 2 features, 6 tasks across 3 streak lanes.",
379
+ "notes": "Created 2 features, 6 tasks across 3 streak lanes; expected review rounds: 2.",
294
380
  "featureIds": ["BD-20", "BD-21"],
295
381
  "taskIds": ["BD-22", "BD-23", "BD-24", "BD-25", "BD-26", "BD-27"],
296
382
  "kb_captures": []
@@ -304,7 +390,9 @@ array (see Step 0.4 -- omit or send `[]` to capture nothing). Example instance:
304
390
  - NEVER add scope beyond the sprint goals you were given and open bugs/features
305
391
  - Every task must be completable in one agent session
306
392
  - A task with no acceptance criteria is incomplete -- fix it before finishing
307
- - Every task must carry a model tier in `--metadata '{"model": "..."}'` -- fix before finishing
308
- - Every task must carry `streak`/`streakOrder` lane metadata alongside `model` in the same
309
- `--metadata` channel; lanes must respect the effort threshold and never split
310
- mutex-resource members apart -- fix before finishing
393
+ - Every task must carry `model`, `size`, `streak` and `streakOrder` in the SAME
394
+ `--metadata` channel at creation time -- never `--notes` -- fix before finishing
395
+ - Lanes must respect `laneMaxEffort`/`laneMaxTasks` and never split mutex-resource members
396
+ apart
397
+ - Never place a `blocks` edge between two tasks that share a `streak` id -- it silently
398
+ defeats the lane by pushing the later task into a separate review round
@@ -8,7 +8,13 @@ tools: [Read, Bash, Grep, Glob, ToolSearch]
8
8
 
9
9
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE bringing the sandbox up)
10
10
 
11
+ <!-- if-tool: ToolSearch -->
11
12
  1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
13
+ <!-- else-tool: ToolSearch -->
14
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
15
+ tool it wants directly. Confirm your environment exposes those tools, then call
16
+ them as written.
17
+ <!-- end-tool: ToolSearch -->
12
18
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo under test, and
13
19
  `hint_modules` naming the subsystems `regression-test-playbook.md` exercises. Trust
14
20
  CONFIRMED entries fully. Use INFERRED entries as hints, not facts. Known-flaky tests and
@@ -19,7 +25,12 @@ tools: [Read, Bash, Grep, Glob, ToolSearch]
19
25
  "runbook" or "learning". A regression gotcha you had to rediscover is exactly what the
20
26
  next sprint's run needs.
21
27
 
28
+ <!-- if-tool: ToolSearch -->
22
29
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
30
+ <!-- else-tool: ToolSearch -->
31
+ If those KB tools are not available in your environment (MCP server not running), skip
32
+ these steps and proceed.
33
+ <!-- end-tool: ToolSearch -->
23
34
 
24
35
  You own `regression-test-playbook.md` end to end: bring the test sandbox
25
36
  up, run both playbook parts, and ALWAYS tear the sandbox down -- pass or
@@ -31,11 +31,17 @@ stating exactly which input is missing and `reopenIds: []`, `newTasks: []`.
31
31
 
32
32
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
33
33
 
34
+ <!-- if-tool: ToolSearch -->
34
35
  1. Run ToolSearch with query
35
36
  `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_query,mcp__apra-fleet__kb_feedback,mcp__apra-fleet__code_context,mcp__apra-fleet__code_graph,mcp__apra-fleet__code_impact,mcp__apra-fleet__code_query"`
36
- (`kb_list`/`kb_promote`/`kb_capture` are deliberately NOT here -- captures and
37
+ <!-- else-tool: ToolSearch -->
38
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
39
+ tool it wants directly. Confirm your environment exposes those tools, then call
40
+ them as written.
41
+ <!-- end-tool: ToolSearch -->
42
+ Do not call `kb_list`/`kb_promote`/`kb_capture` directly -- captures and
37
43
  promotions both go through your structured output, not a direct tool call; see
38
- Step 5 for promotions and item 3 below for captures.)
44
+ Step 5 for promotions and item 3 below for captures.
39
45
  The `code_*` tools answer what the KB cannot: what the changed code actually connects
40
46
  to. Use `code_impact` on each changed file to judge blast radius, and
41
47
  `code_context`/`code_graph`/`code_query` to trace callers before accepting a signature
@@ -56,7 +62,12 @@ stating exactly which input is missing and `reopenIds: []`, `newTasks: []`.
56
62
  directly with the entry id and what was wrong -- this is a read/feedback operation, not
57
63
  a mutation, so it does not go through structured output.
58
64
 
65
+ <!-- if-tool: ToolSearch -->
59
66
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
67
+ <!-- else-tool: ToolSearch -->
68
+ If those KB tools are not available in your environment (MCP server not running), skip
69
+ these steps and proceed.
70
+ <!-- end-tool: ToolSearch -->
60
71
 
61
72
  ## Step 1 -- Context recovery
62
73
 
@@ -14,6 +14,43 @@
14
14
  "notes": {
15
15
  "type": "string"
16
16
  },
17
+ "findings": {
18
+ "type": "array",
19
+ "description": "Machine-readable per-bead findings: one entry per bead that must change, so a caller can route a CHANGES_NEEDED verdict without parsing notes. Populate on every CHANGES_NEEDED verdict. Return an empty array when the objection is genuinely plan-wide and names no individual bead -- an empty array is the explicit 'plan-wide' signal. Omit or return an empty array on APPROVED. Optional, and deliberately absent-tolerant for one release: a verdict produced against the previous contract still validates, and a caller may fall back to reading notes. notes stays the narration channel.",
20
+ "items": {
21
+ "type": "object",
22
+ "required": ["id", "kind", "detail"],
23
+ "properties": {
24
+ "id": {
25
+ "type": "string",
26
+ "description": "The bead this finding concerns, written exactly as it appears in taskAssignments (e.g. BD-14)."
27
+ },
28
+ "kind": {
29
+ "type": "string",
30
+ "description": "Which quality criterion failed, as a closed vocabulary mirroring the numbered criteria in the prose contract's Step 2. Use other only when no listed kind fits, and explain it in detail.",
31
+ "enum": [
32
+ "coverage",
33
+ "missing_test_task",
34
+ "acceptance_criteria",
35
+ "task_size",
36
+ "dependency_wiring",
37
+ "scope_creep",
38
+ "duplicate_work",
39
+ "feasibility",
40
+ "ready_work",
41
+ "model_metadata",
42
+ "lane_cohesion",
43
+ "other"
44
+ ]
45
+ },
46
+ "detail": {
47
+ "type": "string",
48
+ "minLength": 1,
49
+ "description": "The human explanation for this bead: what is wrong and what would make it pass."
50
+ }
51
+ }
52
+ }
53
+ },
17
54
  "taskAssignments": {
18
55
  "type": "array",
19
56
  "items": {
@@ -322,7 +322,7 @@ via `compose_permissions` using the same tag set before every dispatch. See
322
322
 
323
323
  When running via fleet, never pass raw secrets in `execute_prompt` prompts --
324
324
  reference the credential by name only (e.g. "authenticate using credential
325
- github_pat"). The member then uses `{{secure.github_pat}}` in its own
325
+ github_pat"). The member then uses `{{secret.github_pat}}` in its own
326
326
  `execute_command` calls. See `fleet-addendum.md` for the full reference.
327
327
 
328
328
  ## Provider awareness (fleet mode)
@@ -116,9 +116,6 @@ At sprint close, after the harvester runs:
116
116
  startedAt, taskAssignments, logEntries)` and write the result back to
117
117
  `sprint-logs/calibration.json`. Commit it. This blends the actual token counts
118
118
  into the historical averages so future quotes improve.
119
- 4. **Update fleet token memory**: Parse the `tuple_averages` from the updated
120
- calibration object into a flat array: `const tokenEstimates = { averages: Object.values(updatedCalibration.historical?.tuple_averages || {}) }`. Then write it to the beads persistent memory:
121
- `bd remember '<json_string>' --key token-estimates-json`
122
119
 
123
120
  ## Sprint log
124
121
 
@@ -107,8 +107,8 @@ Use member_detail -> llmProvider to determine the target filename:
107
107
 
108
108
  Never pass raw secrets in execute_prompt prompts -- reference the credential by
109
109
  name only (e.g. "authenticate using credential github_pat"). The member then
110
- uses {{secure.github_pat}} in its own execute_command calls. The
111
- {{secure.NAME}} token is substituted at launch time -- reference it bare in
110
+ uses {{secret.github_pat}} in its own execute_command calls. The
111
+ {{secret.NAME}} token is substituted at launch time -- reference it bare in
112
112
  execute_command, not inside your own quotes (it is already single-quote-escaped
113
113
  by the fleet).
114
114
 
@@ -18,6 +18,7 @@ import {
18
18
  import { beadsExtension } from '../fleet-sprint/viewer-extensions.mjs';
19
19
  import { validateIssueId, validateBranchName, checkMemberTopology, createMemberReservationClient, resyncReacquiredMember, commandResultToSoftGit } from '../fleet-sprint/runner.js';
20
20
  import { normalizeRole } from '../fleet-sprint/contracts.mjs';
21
+ import { BEADS_IDENTITY_PROBES, parseBeadsIdentity, formatBeadsIdentity, parseExpectedIdentity } from '../fleet-sprint/beads-identity.mjs';
21
22
 
22
23
  const __filename = fileURLToPath(import.meta.url);
23
24
  const __dirname = path.dirname(__filename);
@@ -155,10 +156,19 @@ export function buildOptionsSpec() {
155
156
  // a direct/standalone CLI launch (no supervisor) falls back to
156
157
  // --branch for this identity, exactly as before this flag existed.
157
158
  'run-id': { type: 'string' },
159
+ // The beads identity (JSON, serializeExpectedIdentity output) every
160
+ // member's bd must resolve to, injected by the supervisor's spawner;
161
+ // env fallback FLEET_SPRINT_EXPECT_BEADS. Omitted (direct launch):
162
+ // the runner takes the expectation from the orchestrator member.
163
+ 'expect-beads': { type: 'string' },
158
164
  budget: { type: 'string' },
159
165
  // Stabilization Issue 32: per-dispatch time budget in seconds
160
166
  // (timeout_s == max_total_s at every dispatch; integ ceiling 2x).
161
167
  'dispatch-timeout-s': { type: 'string' },
168
+ // apra-fleet-hzeb.4.2: the CLI-overridable usage-limit pause budgets.
169
+ // Both optional; omitted, the runner uses USAGE_LIMIT_BUDGET_DEFAULTS.
170
+ 'usage-limit-max-wait-s': { type: 'string' },
171
+ 'usage-limit-max-reprobes': { type: 'string' },
162
172
  // apra-fleet-eft.8.5: explicitly opt a multi-member run into synced
163
173
  // topology mode (orchestrator-bracketed git sync -- same-origin +
164
174
  // dolt-probe precondition, differing HEADs allowed). Omitted => legacy
@@ -193,12 +203,22 @@ Options:
193
203
  Normally set automatically to the supervisor's sprintId when this
194
204
  sprint is supervisor-spawned; omitted (direct/standalone launch)
195
205
  falls back to --branch, exactly as before this flag existed.
206
+ --expect-beads <json> Beads identity every member must resolve to, as JSON
207
+ ({"beadsDir","prefix","syncRemote","repoRemote"}). Normally injected by
208
+ the supervisor; env fallback FLEET_SPRINT_EXPECT_BEADS. Omitted: the
209
+ orchestrator member's own 'bd where' becomes the expectation and every
210
+ other member must match it. A mismatch aborts before any bd mutation.
196
211
  --budget <usd> USD ceiling for this run's total estimated spend. Optional;
197
212
  omitted (the default) means unlimited, identical to prior behavior.
198
213
  --dispatch-timeout-s <s> Per-dispatch time budget in seconds (default 3600). Applied as both
199
214
  the inactivity timeout and the hard ceiling on every agent dispatch
200
215
  (the integration-test dispatch ceiling is 2x). Lower it for small
201
216
  sprints so a hung dispatch costs minutes, not an hour. Minimum 60.
217
+ --usage-limit-max-wait-s <s> Total wall-clock seconds a dispatch may stay paused across all
218
+ usage-limit reprobes before giving up (typed sprint abort). Optional;
219
+ omitted uses the runner default. Minimum 60.
220
+ --usage-limit-max-reprobes <n> Max usage-limit reprobe attempts before giving up, independent
221
+ of elapsed wait. Optional; omitted uses the runner default. Minimum 1.
202
222
  --sync Use synced topology mode (orchestrator-bracketed git sync):
203
223
  members may sit on differing HEADs but must share the same
204
224
  origin URL and pass a 'bd dolt pull' probe. Omitted (default)
@@ -303,7 +323,7 @@ export async function resolveRoleMap(rawValue, deps = {}) {
303
323
  * }} opts
304
324
  * @returns {object}
305
325
  */
306
- export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goal, maxCycles, requirementsFile, roleMap, budget, dispatchTimeoutS, serviceUrl, runId }) {
326
+ export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goal, maxCycles, requirementsFile, roleMap, budget, dispatchTimeoutS, usageLimitMaxWaitS, usageLimitMaxReprobes, serviceUrl, runId, expectBeads }) {
307
327
  const args = {
308
328
  target_issues: targetIssues,
309
329
  members,
@@ -316,6 +336,11 @@ export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goa
316
336
  if (roleMap !== undefined) args.roleMap = roleMap;
317
337
  if (budget !== undefined) args.budget = budget;
318
338
  if (dispatchTimeoutS !== undefined) args.dispatch_timeout_s = dispatchTimeoutS;
339
+ // apra-fleet-hzeb.4.2: the CLI-overridable usage-limit pause budgets,
340
+ // forwarded to runner.js's validateArgs() when supplied (omitted keeps the
341
+ // runner's USAGE_LIMIT_BUDGET_DEFAULTS).
342
+ if (usageLimitMaxWaitS !== undefined) args.usage_limit_max_wait_s = usageLimitMaxWaitS;
343
+ if (usageLimitMaxReprobes !== undefined) args.usage_limit_max_reprobes = usageLimitMaxReprobes;
319
344
  // apra-fleet-f34.1: forwarded straight through to runner.js's validateArgs()
320
345
  // (args.serviceUrl), which is what actually switches it onto the
321
346
  // HTTP-backed dolt-mutex/id-allocator clients (fleet-sprint/runner.js
@@ -327,9 +352,66 @@ export function buildRunnerArgs({ targetIssues, members, branch, baseBranch, goa
327
352
  // dispatch so deploy.md's active-sprints gate can recognize this sprint's
328
353
  // OWN reservation instead of stopping on it.
329
354
  if (runId !== undefined) args.run_id = runId;
355
+ // The raw --expect-beads JSON, forwarded verbatim; runner.js's
356
+ // validateArgs() parses it (validateExpectBeads) and rejects bad JSON.
357
+ if (expectBeads !== undefined) args.expect_beads = expectBeads;
330
358
  return args;
331
359
  }
332
360
 
361
+ /**
362
+ * Resolves the `--expect-beads` value: the flag wins, else the
363
+ * FLEET_SPRINT_EXPECT_BEADS env var, else undefined (no expectation).
364
+ * @param {string|undefined} flagValue
365
+ * @param {NodeJS.ProcessEnv} env
366
+ * @returns {string|undefined}
367
+ */
368
+ export function resolveExpectBeads(flagValue, env = process.env) {
369
+ if (typeof flagValue === 'string' && flagValue.trim()) return flagValue;
370
+ const fromEnv = env.FLEET_SPRINT_EXPECT_BEADS;
371
+ if (typeof fromEnv === 'string' && fromEnv.trim()) return fromEnv;
372
+ return undefined;
373
+ }
374
+
375
+ /**
376
+ * Runs `bd where --json` on the ORCHESTRATOR MEMBER (never locally -- the
377
+ * sprint's bd commands run in that member's workFolder, see
378
+ * checkIssuesExistOnMember below) so the startup banner can show which
379
+ * .beads the sprint is about to mutate, and so a member with no beads
380
+ * database is reported plainly (as a WARNING with the fix -- the `bd show`
381
+ * precondition right after it is what actually fails a member whose bd
382
+ * cannot answer). The runner re-probes every member and does the hard
383
+ * expected-vs-actual comparison; this is display only.
384
+ * @param {{ member: string, runCommand: (cmd: string, member: string) => Promise<string> }} opts
385
+ * @returns {Promise<{ ok: boolean, identity: object|null, message: string }>}
386
+ */
387
+ export async function probeBeadsIdentityOnMember({ member, runCommand }) {
388
+ const raw = {};
389
+ const fix = `To fix: run 'bd where' in the member's workFolder; ensure bd is installed there and the folder contains the project's .beads.`;
390
+ for (const [key, cmd] of Object.entries(BEADS_IDENTITY_PROBES)) {
391
+ try {
392
+ raw[key] = await runCommand(cmd, member);
393
+ } catch (err) {
394
+ if (key === 'where') {
395
+ return {
396
+ ok: false,
397
+ identity: null,
398
+ message: `Warning: no beads database found at member '${member}'s workFolder ('${cmd}' failed: ${err && err.message ? err.message : String(err)}); the beads identity cannot be shown and is not verified for this member. ${fix}`,
399
+ };
400
+ }
401
+ raw[key] = '';
402
+ }
403
+ }
404
+ const identity = parseBeadsIdentity(raw);
405
+ if (!identity.beadsDir) {
406
+ return {
407
+ ok: false,
408
+ identity: null,
409
+ message: `Warning: no beads database found at member '${member}'s workFolder ('${BEADS_IDENTITY_PROBES.where}' returned no database path: ${String(raw.where || '').trim() || '(no output)'}); the beads identity cannot be shown and is not verified for this member. ${fix}`,
410
+ };
411
+ }
412
+ return { ok: true, identity, message: formatBeadsIdentity(identity, { label: `[Precondition] member '${member}'` }) };
413
+ }
414
+
333
415
  /**
334
416
  * Splits `--members` against the fleet's registered member names and decides
335
417
  * whether the sprint may proceed.
@@ -521,6 +603,18 @@ async function main() {
521
603
  // (unchanged pre-existing behavior in that case).
522
604
  const effectiveRunId = values['run-id'] || branchName;
523
605
  const dispatchTimeoutS = values['dispatch-timeout-s'] !== undefined ? Number(values['dispatch-timeout-s']) : undefined;
606
+ // apra-fleet-hzeb.4.2: the CLI-overridable usage-limit pause budgets.
607
+ const usageLimitMaxWaitS = values['usage-limit-max-wait-s'] !== undefined ? Number(values['usage-limit-max-wait-s']) : undefined;
608
+ const usageLimitMaxReprobes = values['usage-limit-max-reprobes'] !== undefined ? Number(values['usage-limit-max-reprobes']) : undefined;
609
+ // --expect-beads (flag, else FLEET_SPRINT_EXPECT_BEADS). Parsed here too
610
+ // so malformed JSON fails before any fleet connection; the runner's
611
+ // validateArgs() re-validates the raw string it is handed.
612
+ const expectBeads = resolveExpectBeads(values['expect-beads']);
613
+ const expectedBeads = expectBeads !== undefined ? parseExpectedIdentity(expectBeads) : null;
614
+ if (expectBeads !== undefined && !expectedBeads) {
615
+ console.error(`Error: --expect-beads is not valid JSON: ${expectBeads}`);
616
+ process.exit(1);
617
+ }
524
618
 
525
619
  // --- A7 defense-in-depth: reject shell-unsafe issue ids / branch names
526
620
  // BEFORE any bd/fleet dispatch happens. runner.js re-validates these
@@ -561,6 +655,18 @@ async function main() {
561
655
  process.exit(1);
562
656
  }
563
657
 
658
+ // apra-fleet-hzeb.4.2: same strict-parsing posture as --dispatch-timeout-s
659
+ // above; mirrors (does not replace) runner.js validateArgs's own checks.
660
+ if (usageLimitMaxWaitS !== undefined && (!Number.isInteger(usageLimitMaxWaitS) || usageLimitMaxWaitS < 60)) {
661
+ console.error(`Error: --usage-limit-max-wait-s must be an integer >= 60 (seconds), got "${values['usage-limit-max-wait-s']}".`);
662
+ process.exit(1);
663
+ }
664
+
665
+ if (usageLimitMaxReprobes !== undefined && (!Number.isInteger(usageLimitMaxReprobes) || usageLimitMaxReprobes < 1)) {
666
+ console.error(`Error: --usage-limit-max-reprobes must be an integer >= 1, got "${values['usage-limit-max-reprobes']}".`);
667
+ process.exit(1);
668
+ }
669
+
564
670
  if (budget !== undefined && (!Number.isFinite(budget) || budget < 0)) {
565
671
  console.error(`Error: --budget must be a non-negative finite number (USD ceiling), got "${values.budget}".`);
566
672
  process.exit(1);
@@ -648,6 +754,25 @@ async function main() {
648
754
  // N15 finding: that stray casing silently never matched a roleMap
649
755
  // author's natural lowercase key).
650
756
  const orchestratorMember = (roleMap && roleMap.orchestrator && roleMap.orchestrator[0]) || validMembers[0];
757
+ const runProbe = async (cmd, member) => {
758
+ const res = await fleetApi.executeCommand({ command: cmd, member_name: member });
759
+ const text = res && res.content && res.content[0] ? res.content[0].text : '';
760
+ if (res && res.isError) throw new Error(text || 'unknown error');
761
+ const exitCode = res && res.structuredContent && typeof res.structuredContent.exitCode === 'number' ? res.structuredContent.exitCode : 0;
762
+ if (exitCode !== 0) throw new Error(text || `exit code ${exitCode}`);
763
+ return res && res.structuredContent && typeof res.structuredContent.stdout === 'string' ? res.structuredContent.stdout : text;
764
+ };
765
+ // Which .beads the orchestrator member's bd resolves to -- probed BEFORE
766
+ // the `bd show` precondition below so a member with no beads database
767
+ // is reported plainly (a warning with the fix) ahead of the bare bd
768
+ // error that precondition would otherwise be the first to show, and
769
+ // shown in the banner. A failed probe is a warning, not an exit: the
770
+ // existing preconditions decide. The runner repeats this for every
771
+ // member and hard-fails only a mismatch against --expect-beads.
772
+ const beadsProbe = await probeBeadsIdentityOnMember({ member: orchestratorMember, runCommand: runProbe });
773
+ if (!beadsProbe.ok) {
774
+ console.warn(beadsProbe.message);
775
+ }
651
776
  const issueCheck = await checkIssuesExistOnMember({
652
777
  targetIssues,
653
778
  member: orchestratorMember,
@@ -729,6 +854,10 @@ async function main() {
729
854
  console.log(`Goal Constraint: ${goal}`);
730
855
  console.log(`Max Cycles: ${maxCycles}`);
731
856
  console.log(`Active Members (${validMembers.length}): ${validMembers.join(', ')}`);
857
+ console.log(`Beads: ${formatBeadsIdentity(beadsProbe.identity, { label: `orchestrator '${orchestratorMember}'` })}`);
858
+ if (expectedBeads) {
859
+ console.log(`Beads: ${formatBeadsIdentity(expectedBeads, { label: 'expected (--expect-beads)' })}`);
860
+ }
732
861
 
733
862
  const workflow = new FleetWorkflow(fleetApi);
734
863
  const engine = new WorkflowEngine(workflow);
@@ -896,8 +1025,11 @@ async function main() {
896
1025
  roleMap,
897
1026
  budget,
898
1027
  dispatchTimeoutS,
1028
+ usageLimitMaxWaitS,
1029
+ usageLimitMaxReprobes,
899
1030
  serviceUrl,
900
1031
  runId: effectiveRunId,
1032
+ expectBeads,
901
1033
  }),
902
1034
  // apra-fleet-eft.75.1: wires this already-connected mcpClient
903
1035
  // through to runner.js's createMemberSessionGuard (see its doc
@@ -952,6 +1084,22 @@ async function main() {
952
1084
 
953
1085
  function isMainModule() {
954
1086
  try {
1087
+ // Never self-execute when this module is loaded as a test file under a
1088
+ // Node test runner. `node --test <file>` sets NODE_TEST_CONTEXT in the
1089
+ // process that evaluates the file AND leaves process.argv[1] pointing at
1090
+ // that file, so the URL comparison below would otherwise treat the test
1091
+ // load as a direct CLI run and fire main() for real. The Phase-4
1092
+ // move-only probe (scripts/phase4-moveonly-probe.mjs) does exactly this:
1093
+ // it copies cli.mjs to a sibling `.phase4probe-cli.mjs` and runs
1094
+ // `node --test` on it, so without this guard main() runs, exits 1 on the
1095
+ // missing required flags, and the CURRENT revision fails to corroborate
1096
+ // as an ANCHOR_DESYNC -- turning the move-only gate red. NODE_TEST_CONTEXT
1097
+ // is stripped from the probe's spawn env, but `node --test` re-injects it
1098
+ // into the file's own process, so it is a reliable "loaded as a test"
1099
+ // signal. A production CLI launch (node bin/cli.mjs ...) and the workflow
1100
+ // import trampoline (src/cli/workflow.ts, which is not a node --test run)
1101
+ // never have it set, so both keep self-executing.
1102
+ if (process.env.NODE_TEST_CONTEXT) return false;
955
1103
  if (process.argv[1] === undefined) return false;
956
1104
  const invokedUrl = pathToFileURL(process.argv[1]).href;
957
1105
  const moduleUrl = import.meta.url;