@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,454 @@
1
+ // CLI -> runner argument contract for fleet-sprint: the shell-injection-safe
2
+ // id/branch validators and the validated shape of `args`
3
+ // (apra-fleet-3swo.3.3). Moved verbatim out of runner.js -- runner.js
4
+ // re-exports every symbol this region previously exported, so existing
5
+ // importers of fleet-sprint/runner.js (including bin/cli.mjs) resolve
6
+ // unchanged. This is a move-only extraction: behaviour, validation order and
7
+ // error message text are all deliberately unchanged from the pre-move code.
8
+ import { normalizeRole, validateCredentialStoreName } from './contracts.mjs';
9
+ import { parseExpectedIdentity } from './beads-identity.mjs';
10
+
11
+ // ---------------------------------------------------------------------------
12
+ // CLI -> runner argument contract
13
+ // ---------------------------------------------------------------------------
14
+ //
15
+ // The canonical, validated shape of `args` (the `context.args` object
16
+ // WorkflowEngine.executeFile()/runWithContext() hands to main()). bin/cli.mjs
17
+ // must produce args matching this contract; unknown keys and missing required
18
+ // keys are both rejected loudly here so CLI/runner drift (a flag added on one
19
+ // side and forgotten on the other) fails fast instead of silently no-oping.
20
+ //
21
+ // Defense in depth: `target_issues`/`target_issue`, `branch`, and
22
+ // `base_branch` are validated against deliberately restrictive
23
+ // shell-injection-safe patterns here as well as in bin/cli.mjs (which imports
24
+ // validateIssueId/validateBranchName from this module -- single source of
25
+ // truth), so a malicious id or branch name can never reach a command()
26
+ // interpolation even if the CLI layer is bypassed. Validation runs before ANY
27
+ // agent()/command() dispatch, so a rejected arg produces zero fleet
28
+ // dispatches.
29
+
30
+ const ISSUE_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
31
+ const BRANCH_NAME_PATTERN = /^[A-Za-z0-9._/-]+$/;
32
+ const GOAL_PATTERN = /^P[1-3](\/P[1-3]){0,2}$/;
33
+
34
+ const KNOWN_ARG_KEYS = new Set([
35
+ 'target_issues', 'target_issue', 'members', 'branch', 'base_branch',
36
+ 'goal', 'max_cycles', 'requirementsFile', 'roleMap', 'budget',
37
+ // Per-dispatch time budget (timeout_s == max_total_s at every dispatch
38
+ // site; integ ceiling = 2x), bounding the cost of a hung dispatch.
39
+ 'dispatch_timeout_s',
40
+ // apra-fleet-hzeb.4.2: usage-limit pause/resume budgets. The one
41
+ // CLI-overridable pair for the usage-limit controller (fleet-sprint/
42
+ // usage-limit-controller.mjs); both default from
43
+ // role-policies.mjs's USAGE_LIMIT_BUDGET_DEFAULTS when omitted.
44
+ // `usage_limit_max_wait_s` bounds total wall-clock a single dispatch may
45
+ // stay paused across all reprobes before giving up
46
+ // (UsageLimitWaitExhaustedError); `usage_limit_max_reprobes` bounds the
47
+ // reprobe count independently of elapsed wait.
48
+ 'usage_limit_max_wait_s',
49
+ 'usage_limit_max_reprobes',
50
+ // The always-on supervisor's base HTTP URL (e.g. http://127.0.0.1:8787).
51
+ // Set by bin/cli.mjs from the FLEET_SE_SERVICE_URL env var the supervisor's
52
+ // spawner injects into each detached child; absent for supervisor-less
53
+ // (single-process/dev/test) runs. When present it enables the cross-sprint
54
+ // coordination layers: the global dolt push mutex, the child-id allocator,
55
+ // and per-bead work-claiming. All three are no-ops without it -- a lone
56
+ // sprint has no sibling to coordinate with.
57
+ 'serviceUrl',
58
+ // apra-fleet-5co8.37: this launch's incarnation-unique run identity -- the
59
+ // SAME string the supervisor's reservation ledger keys this sprint by
60
+ // (bin/cli.mjs forwards the supervisor's --run-id, falling back to the
61
+ // branch name for a direct/standalone launch, which is also what cli.mjs
62
+ // reserves members under). Threaded to the deployer so its active-sprints
63
+ // gate can tell this sprint's OWN reservation from a foreign one.
64
+ 'run_id',
65
+ // The assignee identity this sprint claims beads as and filters ready work
66
+ // by (`bd update --claim` / `bd ready --assignee`). No CLI flag sets this
67
+ // today (bin/cli.mjs's buildRunnerArgs() does not accept it, and no
68
+ // apra-pm workflow under packages/apra-fleet-se/apra-pm sets it either --
69
+ // both verified by repo-wide search, apra-fleet-3swo.7.13); bead selection
70
+ // falls back to the unassigned `bd list --ready`.
71
+ //
72
+ // PRODUCTIZE-OR-PRUNE DECISION (apra-fleet-3swo.7.13): PRODUCTIZED, not
73
+ // pruned. This is NOT dead code -- it is a fully wired, load-bearing
74
+ // engine capability with no CLI surfacing yet: fleet-sprint/beads-
75
+ // scope.mjs actively rewrites its shared `bd list` query to
76
+ // `--assignee <id>` when this is set (so two sprints working the same
77
+ // beads project never select the same bead), and the doer's develop-phase
78
+ // claiming branch (fleet-sprint/phases/develop.mjs) batches a real
79
+ // `bd update <ids...> --claim --json` and narrows the streak to whatever
80
+ // it actually won. Both are exercised directly against the real functions
81
+ // by test/beads-scope-extraction.test.mjs ("--assignee narrows a filtered
82
+ // read...") and test/claim-beads-batched.test.mjs -- this is the "at
83
+ // least one test exercising it" bar, against the real
84
+ // beadsScopeConfig()/claimBeadsBatched() functions the engine itself
85
+ // calls, not a re-derivation of their logic. Documented in
86
+ // docs/cli-reference.md and docs/fleet-sprint-cli-contract.md. Left
87
+ // without a CLI flag deliberately: it exists for a multi-sprint-on-one-
88
+ // project deployment (the supervisor's own future coordination surface,
89
+ // or a direct WorkflowEngine.executeFile() caller), which is a real
90
+ // invocation path today even with no `--assignee` flag on `fleet-sprint`
91
+ // itself -- see docs/fleet-sprint-cli-contract.md's "Dormant argument
92
+ // audit" section for the full record.
93
+ 'assignee',
94
+ // Multi-streak worklist dispatch mode when a develop round has more ready
95
+ // streaks than doers. 'resume' (default): per-streak dispatches that resume
96
+ // the SAME doer session by explicit session id (warm-context carryover,
97
+ // every engine checkpoint kept between streaks). 'batch' (config-gated,
98
+ // overhead-dominated scenarios): one dispatch carries a doer's whole
99
+ // ordered worklist, which REQUIRES a tier-homogeneous worklist.
100
+ // No CLI flag sets this today; only test/programmatic callers pass it.
101
+ //
102
+ // PRODUCTIZE-OR-PRUNE DECISION (apra-fleet-3swo.7.13): PRODUCTIZED. Fully
103
+ // wired (validated here, consumed by fleet-sprint/worklists.mjs's
104
+ // resolveWorklistTierPolicy and the develop-phase worklist packer) and
105
+ // exercised end-to-end through the real WorkflowEngine.executeFile()
106
+ // invocation path by test/mock-sprint-worklist-batch.test.mjs. Documented
107
+ // in docs/cli-reference.md and docs/fleet-sprint-cli-contract.md. See
108
+ // docs/fleet-sprint-cli-contract.md's "Dormant argument audit" section.
109
+ 'doer_worklist_mode',
110
+ // Capability opt-in: the doer pool's provider supports changing model on a
111
+ // RESUMED session. Only then may a resumed-sequence worklist carry mixed
112
+ // tiers, each streak dispatching at its own tier; default false falls back
113
+ // to tier-homogeneous grouping. See resolveWorklistTierPolicy() for the
114
+ // capability-check seam.
115
+ // No CLI flag sets this today; only test/programmatic callers pass it.
116
+ //
117
+ // PRODUCTIZE-OR-PRUNE DECISION (apra-fleet-3swo.7.13): PRODUCTIZED. Fully
118
+ // wired and exercised end-to-end through the real
119
+ // WorkflowEngine.executeFile() invocation path by
120
+ // test/mock-sprint-worklist-resume.test.mjs and unit-tested against the
121
+ // real resolveWorklistTierPolicy() by test/worklist-assignment.test.mjs.
122
+ // Documented in docs/cli-reference.md and docs/fleet-sprint-cli-contract.md.
123
+ // See docs/fleet-sprint-cli-contract.md's "Dormant argument audit" section.
124
+ 'resume_model_switch',
125
+ // Per-doer effort-point budget for worklist packing (planner.md effort
126
+ // formula units). Default DEFAULT_EFFORT_THRESHOLD.
127
+ // No CLI flag sets this today; only test/programmatic callers pass it.
128
+ 'worklist_effort_budget',
129
+ // An optional live `(name, args) => Promise<any>` MCP tool-call function,
130
+ // wired by bin/cli.mjs from its already-connected `mcpClient.callTool`.
131
+ // Consumed by createMemberSessionGuard() to call the fleet's own
132
+ // `stop_prompt` tool before a resume re-dispatch. This is a live function
133
+ // reference, not a JSON-serializable value -- safe only because
134
+ // WorkflowEngine.executeFile() runs runner.js in-process (dynamic
135
+ // `import()`, never across a subprocess boundary). Absent for direct
136
+ // runSprintCycle()/main() test calls, where the guard is a no-op.
137
+ 'callTool',
138
+ // Per-sprint override for the Azure DevOps PAT secret name. When provided, this
139
+ // credential store entry name is used instead of the documented default
140
+ // (azdevops_pat). No CLI flag sets this today; only test/programmatic callers
141
+ // pass it.
142
+ 'azdevops_pat_secret_name',
143
+ // The beads identity every member must resolve to (JSON string from
144
+ // `--expect-beads`, env fallback FLEET_SPRINT_EXPECT_BEADS, or an already
145
+ // parsed record from a programmatic caller). Consumed by the
146
+ // verifyBeadsIdentity precondition (beads-identity-check.mjs); absent, the
147
+ // orchestrator member's own probed identity becomes the expectation.
148
+ 'expect_beads',
149
+ ]);
150
+
151
+ /**
152
+ * Validates the raw `--expect-beads` value: a JSON string (the supervisor's
153
+ * serializeExpectedIdentity output) or a plain record. Malformed JSON is a
154
+ * hard arg error; undefined/empty means "no expectation".
155
+ * @param {unknown} raw
156
+ * @returns {object|undefined}
157
+ */
158
+ export function validateExpectBeads(raw) {
159
+ if (raw === undefined || raw === null || raw === '') return undefined;
160
+ if (typeof raw !== 'string' && (typeof raw !== 'object' || Array.isArray(raw))) {
161
+ throw new Error('[Arg Contract] Invalid expect_beads: must be a JSON string or an object ({ beadsDir, prefix, syncRemote, repoRemote }).');
162
+ }
163
+ const parsed = parseExpectedIdentity(raw);
164
+ if (!parsed) {
165
+ throw new Error(`[Arg Contract] Invalid expect_beads: not valid JSON (${JSON.stringify(String(raw)).slice(0, 200)}).`);
166
+ }
167
+ if (!parsed.prefix && !parsed.syncRemote && !parsed.repoRemote) {
168
+ throw new Error('[Arg Contract] Invalid expect_beads: must carry at least one of prefix, syncRemote, repoRemote.');
169
+ }
170
+ return parsed;
171
+ }
172
+
173
+ /**
174
+ * Validates a single issue id against the shell-injection-safe pattern.
175
+ * Throws with a clear message on rejection.
176
+ * @param {unknown} id
177
+ * @returns {string}
178
+ */
179
+ export function validateIssueId(id) {
180
+ if (typeof id !== 'string' || id.length === 0 || !ISSUE_ID_PATTERN.test(id)) {
181
+ throw new Error(`[Arg Contract] Invalid issue id "${id}": must match ${ISSUE_ID_PATTERN} (letters, digits, '.', '_', '-' only).`);
182
+ }
183
+ return id;
184
+ }
185
+
186
+ /**
187
+ * Validates a git branch name (sprint `branch` / `base_branch`) against a
188
+ * shell-injection-safe pattern before it is ever interpolated into a
189
+ * git/gh command() string.
190
+ * @param {unknown} name
191
+ * @param {string} label - human-readable arg name, used in the error message
192
+ * @returns {string}
193
+ */
194
+ export function validateBranchName(name, label) {
195
+ if (typeof name !== 'string' || name.length === 0 || !BRANCH_NAME_PATTERN.test(name)) {
196
+ throw new Error(`[Arg Contract] Invalid ${label} "${name}": must match ${BRANCH_NAME_PATTERN} (letters, digits, '.', '_', '-', '/' only).`);
197
+ }
198
+ return name;
199
+ }
200
+
201
+ /**
202
+ * Validates and normalizes the args object passed into main(context).
203
+ * Rejects unknown keys and missing/malformed required keys loudly.
204
+ *
205
+ * @param {any} args
206
+ * @returns {{
207
+ * targetIssues: string[], members: string[], branch: string,
208
+ * baseBranch: string, goal: string, maxCycles: number,
209
+ * requirementsFile: string|undefined, roleMap: object|undefined,
210
+ * budget: number|undefined
211
+ * }}
212
+ */
213
+ export function validateArgs(args) {
214
+ if (!args || typeof args !== 'object' || Array.isArray(args)) {
215
+ throw new Error('[Arg Contract] args must be an object.');
216
+ }
217
+
218
+ const unknown = Object.keys(args).filter((k) => !KNOWN_ARG_KEYS.has(k));
219
+ if (unknown.length > 0) {
220
+ throw new Error(`[Arg Contract] Unknown arg(s): ${unknown.join(', ')}. Known args: ${[...KNOWN_ARG_KEYS].join(', ')}.`);
221
+ }
222
+
223
+ // --- target issues: target_issues[] (preferred) or legacy single target_issue ---
224
+ let targetIssues;
225
+ if (Array.isArray(args.target_issues)) {
226
+ targetIssues = args.target_issues;
227
+ } else if (typeof args.target_issue === 'string') {
228
+ targetIssues = [args.target_issue];
229
+ } else {
230
+ throw new Error('[Arg Contract] Missing required arg: target_issues (non-empty array) or target_issue (string).');
231
+ }
232
+ if (targetIssues.length === 0) {
233
+ throw new Error('[Arg Contract] target_issues must be a non-empty array.');
234
+ }
235
+ targetIssues.forEach(validateIssueId);
236
+
237
+ // --- members ---
238
+ if (!Array.isArray(args.members) || args.members.length === 0) {
239
+ throw new Error('[Arg Contract] Missing required arg: members (non-empty array of member ids/names).');
240
+ }
241
+ args.members.forEach((m) => {
242
+ if (typeof m !== 'string' || m.length === 0) {
243
+ throw new Error(`[Arg Contract] Invalid member entry "${m}": must be a non-empty string.`);
244
+ }
245
+ });
246
+
247
+ // --- branch / base_branch (required; also the git/PR target) ---
248
+ if (typeof args.branch !== 'string' || args.branch.length === 0) {
249
+ throw new Error('[Arg Contract] Missing required arg: branch (sprint branch name).');
250
+ }
251
+ validateBranchName(args.branch, 'branch');
252
+
253
+ if (typeof args.base_branch !== 'string' || args.base_branch.length === 0) {
254
+ throw new Error('[Arg Contract] Missing required arg: base_branch (branch the sprint branch is created from and the PR targets).');
255
+ }
256
+ validateBranchName(args.base_branch, 'base_branch');
257
+
258
+ // --- goal (optional, default 'P1/P2'; the priority band this sprint aims
259
+ // to clear, consumed by the exit-condition logic) ---
260
+ const goal = args.goal === undefined ? 'P1/P2' : args.goal;
261
+ if (typeof goal !== 'string' || !GOAL_PATTERN.test(goal)) {
262
+ throw new Error(`[Arg Contract] Invalid goal "${goal}": must match ${GOAL_PATTERN} (e.g. 'P1', 'P1/P2', 'P1/P2/P3').`);
263
+ }
264
+
265
+ // --- max_cycles (optional, default 5) ---
266
+ const maxCycles = args.max_cycles === undefined ? 5 : args.max_cycles;
267
+ if (typeof maxCycles !== 'number' || !Number.isInteger(maxCycles) || maxCycles < 1) {
268
+ throw new Error(`[Arg Contract] Invalid max_cycles "${maxCycles}": must be a positive integer.`);
269
+ }
270
+
271
+ // --- requirementsFile (optional) ---
272
+ if (args.requirementsFile !== undefined && (typeof args.requirementsFile !== 'string' || args.requirementsFile.length === 0)) {
273
+ throw new Error('[Arg Contract] Invalid requirementsFile: must be a non-empty string path.');
274
+ }
275
+
276
+ // --- roleMap (optional; consumed by getMemberForRole/getMembersForRole below) ---
277
+ if (args.roleMap !== undefined && (typeof args.roleMap !== 'object' || args.roleMap === null || Array.isArray(args.roleMap))) {
278
+ throw new Error('[Arg Contract] Invalid roleMap: must be an object mapping role -> member[].');
279
+ }
280
+ // This is the SINGLE normalization point for roleMap keys: every key is
281
+ // put through normalizeRole() (trim + lowercase) here, so any casing or
282
+ // whitespace variant resolves to its canonical form and downstream readers
283
+ // (getMemberForRole/getMembersForRole) may assume normalized keys and must
284
+ // never re-read `args.roleMap` directly. Two differently-cased input keys
285
+ // that normalize to the same key are rejected loudly (ambiguous authorial
286
+ // intent) rather than one silently clobbering the other.
287
+ let normalizedRoleMap;
288
+ if (args.roleMap !== undefined) {
289
+ normalizedRoleMap = {};
290
+ for (const [rawKey, value] of Object.entries(args.roleMap)) {
291
+ const key = normalizeRole(rawKey);
292
+ if (Object.prototype.hasOwnProperty.call(normalizedRoleMap, key)) {
293
+ throw new Error(
294
+ `[Arg Contract] Invalid roleMap: key "${rawKey}" normalizes to "${key}", which collides with ` +
295
+ `another key already present in roleMap. Use a single casing/whitespace variant per role.`
296
+ );
297
+ }
298
+ normalizedRoleMap[key] = value;
299
+ }
300
+ }
301
+
302
+ // --- budget (optional) -----------------------------------------------
303
+ // A USD ceiling for this run's total estimated spend. When provided,
304
+ // main() sets `context.budget.total` to this value BEFORE any dispatch, so
305
+ // `agent()`'s budget-exceeded check can actually fire. Omitted,
306
+ // `context.budget.total` stays `null` (unlimited).
307
+ if (args.budget !== undefined && (typeof args.budget !== 'number' || !Number.isFinite(args.budget) || args.budget < 0)) {
308
+ throw new Error(`[Arg Contract] Invalid budget "${args.budget}": must be a non-negative finite number (USD ceiling).`);
309
+ }
310
+
311
+ // --- run_id (optional) -------------------------------------------------
312
+ // Free-form supervisor-generated identity; only its shape is checked here.
313
+ if (args.run_id !== undefined && (typeof args.run_id !== 'string' || args.run_id.length === 0)) {
314
+ throw new Error('[Arg Contract] Invalid run_id: must be a non-empty string.');
315
+ }
316
+
317
+ // --- serviceUrl (optional) --------------------------------------------
318
+ // The always-on supervisor's base HTTP URL. Validated as an http(s) URL so
319
+ // a malformed value fails fast rather than silently disabling the
320
+ // cross-sprint coordination layers or, worse, being interpolated somewhere
321
+ // unsafe. Omitted (single-process/dev/test): the coordination layers stay
322
+ // dormant (a lone sprint has no sibling to serialize against).
323
+ if (args.serviceUrl !== undefined) {
324
+ if (typeof args.serviceUrl !== 'string' || args.serviceUrl.length === 0) {
325
+ throw new Error('[Arg Contract] Invalid serviceUrl: must be a non-empty http(s) URL string.');
326
+ }
327
+ let parsed;
328
+ try {
329
+ parsed = new URL(args.serviceUrl);
330
+ } catch {
331
+ throw new Error(`[Arg Contract] Invalid serviceUrl "${args.serviceUrl}": must be a valid http(s) URL.`);
332
+ }
333
+ if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
334
+ throw new Error(`[Arg Contract] Invalid serviceUrl "${args.serviceUrl}": must use the http: or https: scheme.`);
335
+ }
336
+ }
337
+
338
+ // --- assignee (optional) ----------------------------------------------
339
+ // The work-claiming identity. Constrained to a shell-injection-safe pattern
340
+ // because it is interpolated into `bd update --claim` / `bd ready
341
+ // --assignee` command strings, matching the same defense-in-depth posture
342
+ // as issue ids and branch names above.
343
+ if (args.assignee !== undefined) {
344
+ if (typeof args.assignee !== 'string' || args.assignee.length === 0 || !ISSUE_ID_PATTERN.test(args.assignee)) {
345
+ throw new Error(`[Arg Contract] Invalid assignee "${args.assignee}": must match ${ISSUE_ID_PATTERN} (letters, digits, '.', '_', '-' only).`);
346
+ }
347
+ }
348
+
349
+ // --- dispatch_timeout_s (optional, default 9000 = 150min/2.5h) ---------
350
+ // Per-dispatch time budget in seconds. This value is used to derive two
351
+ // distinct dispatched parameters sent to execute_prompt: timeout_s (the
352
+ // inactivity detector baseline, clamped to a maximum to prevent one run's
353
+ // budget from disabling stall detection entirely) and max_total_s (the full
354
+ // dispatch timeout, unclamped). These two are no longer equal: timeout_s
355
+ // drives the StallDetector's per-dispatch threshold for every provider; it
356
+ // ALSO drives the exec-channel rolling timer for Codex, Copilot, and
357
+ // OpenCode. Claude and AGY instead take their exec-level ceiling from
358
+ // max_total_s (falling back to a never-binds constant if max_total_s is
359
+ // absent), so they do not falsely kill a dispatch while a long silent tool
360
+ // call is legitimately being processed. Raised from the earlier 3600s
361
+ // default: an hour was tight enough to misclassify a slow-but-alive turn
362
+ // (a large diff, a chatty tool loop) as a stall, which is a false positive,
363
+ // not the genuine-hang protection this timer exists for. Lowering it still
364
+ // bounds the cost of a live-but-silent member hang, which no timer can
365
+ // otherwise distinguish from work. Floor 60: below that even healthy
366
+ // dispatches cannot complete a single turn. The integ-test dispatch
367
+ // ceiling is 2x this value and the regression-test ceiling is 3x, since
368
+ // those suites legitimately run past one budget.
369
+ const dispatchTimeoutS = args.dispatch_timeout_s === undefined ? 9000 : args.dispatch_timeout_s;
370
+ if (typeof dispatchTimeoutS !== 'number' || !Number.isInteger(dispatchTimeoutS) || dispatchTimeoutS < 60) {
371
+ throw new Error(`[Arg Contract] Invalid dispatch_timeout_s "${dispatchTimeoutS}": must be an integer >= 60 (seconds).`);
372
+ }
373
+
374
+ // --- doer_worklist_mode (optional, default 'resume') -------------------
375
+ // 'resume' walks a doer's worklist as a resumed sequence of dispatches;
376
+ // 'batch' hands the whole ordered worklist over in a single dispatch.
377
+ const doerWorklistMode = args.doer_worklist_mode === undefined ? 'resume' : args.doer_worklist_mode;
378
+ if (doerWorklistMode !== 'resume' && doerWorklistMode !== 'batch') {
379
+ throw new Error(`[Arg Contract] Invalid doer_worklist_mode "${doerWorklistMode}": must be 'resume' (default) or 'batch'.`);
380
+ }
381
+
382
+ // --- resume_model_switch (optional, default false) ---------------------
383
+ const resumeModelSwitch = args.resume_model_switch === undefined ? false : args.resume_model_switch;
384
+ if (typeof resumeModelSwitch !== 'boolean') {
385
+ throw new Error(`[Arg Contract] Invalid resume_model_switch "${resumeModelSwitch}": must be a boolean.`);
386
+ }
387
+
388
+ // --- worklist_effort_budget (optional) ---------------------------------
389
+ if (args.worklist_effort_budget !== undefined
390
+ && (typeof args.worklist_effort_budget !== 'number'
391
+ || !Number.isFinite(args.worklist_effort_budget)
392
+ || args.worklist_effort_budget <= 0)) {
393
+ throw new Error(`[Arg Contract] Invalid worklist_effort_budget "${args.worklist_effort_budget}": must be a positive finite number (effort points).`);
394
+ }
395
+
396
+ // --- usage_limit_max_wait_s (optional) ---------------------------------
397
+ // Total wall-clock seconds a single dispatch may stay paused across all
398
+ // usage-limit reprobes before the controller gives up
399
+ // (UsageLimitWaitExhaustedError -> typed sprint abort). Omitted, the
400
+ // controller uses role-policies.mjs's USAGE_LIMIT_BUDGET_DEFAULTS. Floor
401
+ // 60: a usage-limit window shorter than the minimum single wait is not a
402
+ // meaningful budget.
403
+ if (args.usage_limit_max_wait_s !== undefined
404
+ && (typeof args.usage_limit_max_wait_s !== 'number'
405
+ || !Number.isInteger(args.usage_limit_max_wait_s)
406
+ || args.usage_limit_max_wait_s < 60)) {
407
+ throw new Error(`[Arg Contract] Invalid usage_limit_max_wait_s "${args.usage_limit_max_wait_s}": must be an integer >= 60 (seconds).`);
408
+ }
409
+
410
+ // --- usage_limit_max_reprobes (optional) -------------------------------
411
+ // Maximum reprobe attempts before the controller gives up, independent of
412
+ // elapsed wait. Omitted, the controller uses USAGE_LIMIT_BUDGET_DEFAULTS.
413
+ if (args.usage_limit_max_reprobes !== undefined
414
+ && (typeof args.usage_limit_max_reprobes !== 'number'
415
+ || !Number.isInteger(args.usage_limit_max_reprobes)
416
+ || args.usage_limit_max_reprobes < 1)) {
417
+ throw new Error(`[Arg Contract] Invalid usage_limit_max_reprobes "${args.usage_limit_max_reprobes}": must be an integer >= 1.`);
418
+ }
419
+
420
+ // --- azdevops_pat_secret_name (optional) --------------------------------
421
+ // Override for the default Azure DevOps PAT secret name. When provided, this
422
+ // credential store entry name is used instead of the documented default
423
+ // (azdevops_pat). Validated as a credential-store name at contract-validation
424
+ // time, not mid-sprint, so invalid values fail fast and clearly.
425
+ if (args.azdevops_pat_secret_name !== undefined) {
426
+ validateCredentialStoreName(args.azdevops_pat_secret_name, 'azdevops_pat_secret_name');
427
+ }
428
+
429
+ // --- expect_beads (optional) ------------------------------------------
430
+ const expectBeads = validateExpectBeads(args.expect_beads);
431
+
432
+ return {
433
+ targetIssues,
434
+ members: args.members,
435
+ branch: args.branch,
436
+ baseBranch: args.base_branch,
437
+ goal,
438
+ maxCycles,
439
+ requirementsFile: args.requirementsFile,
440
+ roleMap: normalizedRoleMap,
441
+ budget: args.budget,
442
+ serviceUrl: args.serviceUrl,
443
+ runId: args.run_id,
444
+ assignee: args.assignee,
445
+ dispatchTimeoutS,
446
+ azdevopsPatSecretName: args.azdevops_pat_secret_name,
447
+ doerWorklistMode,
448
+ resumeModelSwitch,
449
+ worklistEffortBudget: args.worklist_effort_budget,
450
+ usageLimitMaxWaitS: args.usage_limit_max_wait_s,
451
+ usageLimitMaxReprobes: args.usage_limit_max_reprobes,
452
+ expectBeads,
453
+ };
454
+ }