@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
@@ -13,9 +13,18 @@
13
13
  * always sends this field explicitly, defaulting it to `false` for workflow-authored
14
14
  * prompts (see AgentOptions.resume there and apra-fleet-unw.3 / F10) -- so workflow
15
15
  * callers effectively opt out of this client-level default unless they ask for resume.
16
+ * CALLER OBLIGATION: anything reaching executePrompt() WITHOUT going through that
17
+ * workflow layer must set this field explicitly. Omitting it is never neutral -- the
18
+ * server resumes the member's stored last session, so a one-off instruction silently
19
+ * lands in whatever unrelated (and possibly very large) conversation that member last
20
+ * ran. This client deliberately does NOT inject a default of its own: doing so would
21
+ * change the documented tool contract for every existing caller. State the intent at
22
+ * the call site: `true` to continue that member's prior session, a session-id string
23
+ * to continue a specific one, `false` for a self-contained dispatch.
16
24
  * @property {string} [session_id] - Optional explicit session ID to resume (shorthand alias for resume: "<sessionId>")
25
+ * @property {boolean|string} [fork] - Branch a NEW session seeded from an existing one instead of continuing it in place. true = fork from the member's stored last session. A session-id STRING = fork from exactly that session. Mutually exclusive with resume (any non-default value) and with session_id.
17
26
  * @property {Record<string, string>} [substitutions] - Optional map of token name to replacement value
18
- * @property {number} [timeout_s] - Inactivity timeout in seconds (default: 300)
27
+ * @property {number} [timeout_s] - Inactivity timeout in seconds -- always drives the stall detector's per-dispatch baseline threshold, measured against the member's own session transcript activity (default: 300). Per-provider, it ALSO arms the exec-level rolling timer against this dispatch's stdout/stderr channel for Codex and Copilot, which have no pollable transcript; Claude and AGY take that exec-channel ceiling from max_total_s instead; and OpenCode keeps BOTH signals armed at once (this exec-channel timer plus coarse log-directory-mtime polling, combined with OR semantics -- either advancing counts as not-stalled), since its transcript signal is directory-level only, not a per-turn file (see ProviderAdapter.execTimeoutSource() server-side)
19
28
  * @property {number} [expected_context_tokens] - Optional estimate of how many
20
29
  * tokens this dispatch will add to the target session's context. When set (or context_size is
21
30
  * set), the server compares it against the session's remaining context-window headroom BEFORE
@@ -38,6 +47,68 @@
38
47
  * cannot cancel a job already accepted by the remote fleet-server (see client.mjs).
39
48
  */
40
49
 
50
+ /**
51
+ * apra-fleet-hzeb.2: a provider-agnostic "this dispatch cannot make progress until
52
+ * `resumeAt`" signal, mirroring src/providers/provider.ts's UsageLimitSignal exactly.
53
+ * @typedef {Object} UsageLimitSignal
54
+ * @property {'usage_limit'} type
55
+ * @property {string} resumeAt - ISO-8601 UTC instant at which work may resume. Never null:
56
+ * when the provider CLI exposes a real reset time it is parsed (resumeAtSource: 'parsed');
57
+ * otherwise it falls back to a guessed window (resumeAtSource: 'guessed').
58
+ * @property {'parsed'|'guessed'} resumeAtSource
59
+ * @property {string} message - The raw provider message/output that identified this as a
60
+ * usage/quota limit (for logging).
61
+ */
62
+
63
+ /**
64
+ * One tool call the member CLI refused, mirroring src/providers/provider.ts's PermissionDenialItem.
65
+ * @typedef {Object} PermissionDenialItem
66
+ * @property {string} action - Provider permission action, e.g. 'command', 'read_file', 'mcp'.
67
+ * @property {string} [target] - The concrete target when the CLI named it, e.g. 'git status --short --branch'.
68
+ */
69
+
70
+ /**
71
+ * execute_prompt's `permissionDenied` block, mirroring src/providers/provider.ts's PermissionDenial.
72
+ * @typedef {Object} PermissionDenied
73
+ * @property {string[]} actions - Unique denied actions, in first-seen order.
74
+ * @property {PermissionDenialItem[]} denials - Each refused call, with its target when known.
75
+ * @property {string[]} suggestedGrants - compose_permissions `grant` values that would allow the
76
+ * denied calls, primary first (for an agy command or unsandboxed denial, on any OS, a
77
+ * `Bash(<cmd>:*)` prefix grant, then the exact command as the narrow alternative); empty when no
78
+ * canonical mapping exists.
79
+ * @property {string} hint - One-line remediation.
80
+ * @property {Array<'result_json'|'stderr'|'transcript'>} signals - Which CLI signals reported it.
81
+ */
82
+
83
+ /**
84
+ * Result-side shape of execute_prompt's `structuredContent` -- the single place callers
85
+ * should read the outcome of a dispatch rather than re-parsing the display text. This is
86
+ * NOT exhaustive of every `reason` value (see src/tools/execute-prompt.ts's
87
+ * ExecutePromptStructured for the full union); it documents the fields most callers key off.
88
+ * @typedef {Object} ExecutePromptStructured
89
+ * @property {boolean} [isError] - true on any failure path; absent/false on success.
90
+ * @property {string} [reason] - Machine-readable failure/status classification, e.g.
91
+ * 'busy' | 'nonzero_exit' | 'max_turns_exhausted' | 'empty_response' | 'overloaded' |
92
+ * 'usage_limit' | 'workspace_not_trusted' | 'session_not_found' | 'permission_denied' | ...
93
+ * @property {PermissionDenied} [permissionDenied] - Present when `reason === 'permission_denied'`:
94
+ * the member CLI refused tool calls for lack of a grant (AGY headless mode auto-denies them
95
+ * and exits 0, which used to surface as 'empty_response'). Pass `suggestedGrants` to
96
+ * compose_permissions `grant` to heal it; read it with {@link permissionDenialOf}. Any partial
97
+ * reply is in `response`.
98
+ * @property {UsageLimitSignal} [usageLimit] - Present when `reason === 'usage_limit'`
99
+ * (apra-fleet-hzeb.2): the provider's detectUsageLimit() signal verbatim -- a 429/quota
100
+ * exhaustion that a fresh session cannot cure, so execute_prompt returns this INSTEAD of
101
+ * retrying via the stale-session or server-overloaded (529, reason: 'overloaded') retry
102
+ * paths. Read `usageLimit.resumeAt`/`resumeAtSource` to schedule a resume rather than
103
+ * re-parsing the failure text; `packages/apra-fleet-workflow` forwards this unchanged onto
104
+ * `AgentDispatchError.details.usageLimit`.
105
+ * @property {string} [response] - The LLM's actual reply text on success.
106
+ * @property {string} [sessionId] - The session id this dispatch landed on, when known --
107
+ * present on success AND on a 'usage_limit'/'max_turns_exhausted' failure so the SAME
108
+ * session can be resumed later instead of losing context to a fresh one.
109
+ * @property {{input_tokens:number, output_tokens:number, total_tokens:number}} [usage]
110
+ */
111
+
41
112
  /**
42
113
  * @typedef {Object} ExecuteCommandOptions
43
114
  * @property {string} command - The shell command to execute
@@ -102,6 +173,7 @@
102
173
  * @property {string} [key_path] - Path to SSH private key
103
174
  * @property {"read" | "push" | "admin" | "issues" | "full"} [git_access] - Git access level for this member
104
175
  * @property {string[]} [git_repos] - Git repositories this member can access (e.g. ["Apra-Labs/ApraPipes"])
176
+ * @property {"github" | "bitbucket" | "azure-devops" | "none"} [vcs_provider] - VCS provider this member pushes to and opens pull requests against. Omit to auto-detect it from the member's git "origin" remote; "none" declares the member deliberately has no VCS provider.
105
177
  * @property {"aws"} [cloud_provider] - Cloud provider. When set, cloud_instance_id and key_path are required.
106
178
  * @property {string} [cloud_instance_id] - EC2 instance ID (e.g. "i-0abc123def456789a"). Required when cloud_provider is set.
107
179
  * @property {string} [cloud_region] - AWS region (default: "us-east-1")
@@ -109,9 +181,9 @@
109
181
  * @property {number} [cloud_idle_timeout_min] - Minutes of inactivity before auto-stop (default: 30)
110
182
  * @property {string} [cloud_activity_command] - Custom shell command for workload detection. Must output "busy" or "idle" on stdout.
111
183
  * @property {"claude" | "codex" | "copilot" | "agy" | "opencode" | "none"} [llm_provider] - LLM provider for this member (default: "claude")
112
- * @property {"gpt-oss-120b" | "gpt-120" | "gemini-3.5-flash-lite" | "haiku" | "gpt-5.4-mini"} [model_cheap] - Custom cheap model choice from a curated list
113
- * @property {"gemini-3.5-flash" | "gpt-oss-120b" | "gpt-120" | "sonnet" | "gpt-5.4"} [model_standard] - Custom standard model choice from a curated list
114
- * @property {"sonnet" | "opus" | "gpt-oss-120b"} [model_premium] - Custom premium model choice from a curated list
184
+ * @property {"gpt-oss-120b" | "gpt-120" | "gemini-3.8-flash-low" | "haiku" | "gpt-5.4-mini"} [model_cheap] - Custom cheap model choice from a curated list
185
+ * @property {"gemini-3.8-flash-high" | "gemini-3.8-flash-medium" | "gemini-3.1-pro-low" | "gpt-oss-120b" | "gpt-120" | "sonnet" | "gpt-5.4"} [model_standard] - Custom standard model choice from a curated list
186
+ * @property {"sonnet" | "opus" | "gemini-3.1-pro-high" | "claude-opus-4-6-thinking" | "gpt-oss-120b"} [model_premium] - Custom premium model choice from a curated list
115
187
  * @property {{cheap?: string, standard?: string, premium?: string}} [model_tiers] - Per-member model tier map. A single model fills all tiers.
116
188
  * @property {"codebase-memory" | "gitnexus" | "none"} [code_intel_provider] - Code-intelligence provider for this member (default: fleet-wide config)
117
189
  * @property {string} [category] - Optional group label
@@ -132,7 +204,7 @@
132
204
  * @property {number} [port] - New SSH port
133
205
  * @property {"password" | "key"} [auth_type] - New auth method
134
206
  * @property {string} [password] - New SSH password
135
- * @property {boolean} [rotate_password] - Trigger secure out-of-band password re-entry for a member already using password auth. Ignored if auth_type is not password.
207
+ * @property {boolean} [rotate_password] - Trigger out-of-band password re-entry for a member already using password auth. Ignored if auth_type is not password.
136
208
  * @property {string} [key_path] - New SSH private key path
137
209
  * @property {"read" | "push" | "admin" | "issues" | "full"} [git_access] - Git access level for this member
138
210
  * @property {string[]} [git_repos] - Git repositories this member can access (e.g. ["Apra-Labs/ApraPipes"])
@@ -142,9 +214,9 @@
142
214
  * @property {number} [cloud_idle_timeout_min] - Minutes of inactivity before auto-stop
143
215
  * @property {string} [cloud_activity_command] - Custom shell command for workload detection. Must output "busy" or "idle". Pass empty string to clear.
144
216
  * @property {"claude" | "codex" | "copilot" | "agy" | "opencode"} [llm_provider] - Change the LLM provider
145
- * @property {"gpt-oss-120b" | "gpt-120" | "gemini-3.5-flash-lite" | "haiku" | "gpt-5.4-mini"} [model_cheap] - Change custom cheap model
146
- * @property {"gemini-3.5-flash" | "gpt-oss-120b" | "gpt-120" | "sonnet" | "gpt-5.4"} [model_standard] - Change custom standard model
147
- * @property {"sonnet" | "opus" | "gpt-oss-120b"} [model_premium] - Change custom premium model
217
+ * @property {"gpt-oss-120b" | "gpt-120" | "gemini-3.8-flash-low" | "haiku" | "gpt-5.4-mini"} [model_cheap] - Change custom cheap model
218
+ * @property {"gemini-3.8-flash-high" | "gemini-3.8-flash-medium" | "gemini-3.1-pro-low" | "gpt-oss-120b" | "gpt-120" | "sonnet" | "gpt-5.4"} [model_standard] - Change custom standard model
219
+ * @property {"sonnet" | "opus" | "gemini-3.1-pro-high" | "claude-opus-4-6-thinking" | "gpt-oss-120b"} [model_premium] - Change custom premium model
148
220
  * @property {{cheap?: string, standard?: string, premium?: string}} [model_tiers] - Per-member model tier map with free-form model IDs. A single model fills all tiers.
149
221
  * @property {"codebase-memory" | "gitnexus" | "none"} [code_intel_provider] - Change the code-intelligence provider for this member
150
222
  * @property {string} [category] - Group label
@@ -152,6 +224,7 @@
152
224
  * @property {"false" | "auto" | "dangerous"} [unattended] - Permission mode
153
225
  * @property {boolean} [unreservable] - Mark/unmark this member as shared/never exclusively reservable
154
226
  * @property {"gitbash" | "pwsh7" | "powershell5"} [shell] - Override the probed Windows shell for this member. Windows members only -- ignored for non-windows members.
227
+ * @property {"github" | "bitbucket" | "azure-devops" | "none"} [vcs_provider] - Directly set (override) this member's VCS provider. An explicit operator value, never auto-detected -- use this to correct a wrong auto-detect from register_member, or to set the provider without provisioning credentials. "none" clears it.
155
228
  */
156
229
 
157
230
  /**
@@ -171,9 +244,18 @@
171
244
  * @property {string} folder - Working directory on the target machine
172
245
  * @property {string} [repo_remote_url] - Origin URL of the git repo in `folder`, when known
173
246
  * @property {string} [vcsProvider] - VCS provider configured for this member
247
+ * @property {"read" | "push" | "push+pr" | "admin" | "issues" | "full"} [gitAccess] - Git access level
248
+ * this member's VCS credentials are minted at (register_member/update_member's git_access). Absent
249
+ * when the member was registered without an explicit level. Consumers that need to know whether a
250
+ * minted token carries a given permission (e.g. GitHub's 'workflows', required to push any
251
+ * .github/workflows/** change) must read THIS, not their own provisioning default -- the two differ
252
+ * exactly for the members at risk.
174
253
  * @property {Object} connectivity - Connectivity check result (status, latencyMs, auth, keyPath, or error)
175
254
  * @property {boolean} [offline] - Set when the member could not be reached
176
255
  * @property {string} llmProvider - LLM provider for this member (default: "claude")
256
+ * @property {string|null} [agyProjectId] - agy members only: id of the member's own agy project
257
+ * (~/.gemini/config/projects/<id>.json), passed as `--project <id>` on every dispatch; null until
258
+ * provisioned (compose_permissions/execute_prompt provision it on first use)
177
259
  * @property {Object} [llm_cli] - LLM CLI info: { version, auth }
178
260
  * @property {Object|string} [tokenUsage] - Cumulative token usage, or "compute only" for llmProvider "none"
179
261
  * @property {Object} [session] - Session info: { id, lastActivity, lastLlmActivityAt, status, idleSecs }
@@ -189,15 +271,142 @@
189
271
  * @property {boolean} [force] - Remove even if the member is currently busy
190
272
  */
191
273
 
274
+ /**
275
+ * @typedef {Object} MemberReservationOptions
276
+ * @property {string} [member_id] - UUID of the member
277
+ * @property {string} [member_name] - Friendly name of the member
278
+ * @property {"reserve" | "release" | "force_release"} action - "reserve" claims the member for
279
+ * sprint_id (fails if already reserved by someone else); "release" clears it only if sprint_id
280
+ * matches the current holder; "force_release" clears it regardless of owner.
281
+ * @property {string} [sprint_id] - Sprint/session id claiming or releasing the reservation.
282
+ * Required for "reserve" and "release", ignored for "force_release".
283
+ */
284
+
285
+ /**
286
+ * @typedef {Object} MemberReservationStructured
287
+ * @property {"reserved" | "reservation_refreshed" | "released" | "force_released" |
288
+ * "already_reserved_by_other" | "not_reserved" | "unreservable" | "invalid_input" |
289
+ * "member_not_found" | "failed"} outcome - Machine-readable outcome discriminator. Branch on
290
+ * this field; never string-match the human-readable summary text.
291
+ * @property {boolean} ok - True when the requested operation took effect (or was already true).
292
+ * @property {"reserve" | "release" | "force_release"} action - The action that was requested.
293
+ * @property {string|null} memberId - Registry id of the resolved member, null when none resolved.
294
+ * @property {string|null} memberName - Friendly name of the resolved member, null when none resolved.
295
+ * @property {string|null} sprintId - The sprint id supplied by the caller, null when none.
296
+ * @property {string|null} ownerSprintId - The sprint that held the reservation when the call
297
+ * arrived, null when the member was unreserved. On "already_reserved_by_other" this is the
298
+ * blocking owner.
299
+ *
300
+ * Mirrors src/tools/member-reservation.ts's MemberReservationStructured field-for-field
301
+ * (apra-fleet-3swo.7.1). The tool still returns the same human-readable summary in
302
+ * `content[0].text`; this shape is the machine-readable half of the same response.
303
+ */
304
+
192
305
  /**
193
306
  * @typedef {Object} ProvisionLlmAuthOptions
194
307
  * @property {string} [member_id] - UUID of the member
195
308
  * @property {string} [member_name] - Friendly name of the member
196
309
  * @property {string} [api_key] - AI provider API key. If omitted, the local OAuth
197
- * session is copied to the member instead. Supports {{secure.NAME}} token --
310
+ * session is copied to the member instead. Supports {{secret.NAME}} token --
198
311
  * resolved from the credential store server-side before use.
199
312
  */
200
313
 
314
+ /**
315
+ * @typedef {Object} VcsCredentialExecOptions
316
+ * @property {string} [member_id] - UUID of the member
317
+ * @property {string} [member_name] - Friendly name of the member
318
+ * @property {string} command - The credential-requiring command to run on the member. MUST
319
+ * contain at least one of two placeholders where the credential belongs (both may appear in
320
+ * the same command): {{vcs_token}}, referenced BARE (never inside your own quotes) -- the
321
+ * server substitutes it with the value ALREADY escaped AND quoted for that member's shell, so
322
+ * wrapping it in your own quotes double-escapes it and surfaces as a false 401; or
323
+ * {{vcs_token_inline}}, referenced INSIDE your own single quotes -- the server substitutes it
324
+ * with the value escaped for the interior of a single-quoted string, with no quotes of its
325
+ * own, for interpolating the token into a larger already-quoted value (e.g. an Authorization
326
+ * header) where a bare, self-quoting substitution cannot compose.
327
+ * @property {string} [label] - Credential label provision_vcs_auth deployed the helper under
328
+ * (it defaults to the provider name there, e.g. "github" or "azure-devops"). Omit for the
329
+ * unlabelled helper.
330
+ * @property {number} [timeout_s] - Timeout in seconds for the command (default: 120).
331
+ */
332
+
333
+ /**
334
+ * @typedef {Object} VcsCredentialExecStructured
335
+ * @property {boolean} ok - True when the credential-requiring command was dispatched. Read
336
+ * exitCode for the command's own outcome.
337
+ * @property {"ok" | "member_not_found" | "placeholder_missing" | "unsupported_member_os" |
338
+ * "credential_read_failed" | "credential_empty" | "dispatch_failed"} reason - Machine-readable
339
+ * outcome code. Branch on this, never on the text.
340
+ * @property {number|null} exitCode - Exit code of the dispatched command, null if it never ran.
341
+ * @property {string} stdout - Command stdout, with every occurrence of the credential redacted.
342
+ * @property {string} stderr - Command stderr, with every occurrence of the credential redacted.
343
+ * @property {number} tokenRedactions - How many times the credential had to be redacted out of
344
+ * stdout+stderr. Normally 0; nonzero means the command echoed its own credential back.
345
+ * @property {string|null} credentialLabel - Credential label used, or null for the unlabelled helper.
346
+ * @property {string|null} memberId - Registry id of the resolved member, or null.
347
+ * @property {string|null} memberName - Friendly name of the resolved member, or null.
348
+ *
349
+ * Mirrors src/tools/vcs-credential-exec.ts's VcsCredentialExecStructured field-for-field
350
+ * (apra-fleet-3swo.7.3). The plaintext credential appears in NO field of this payload.
351
+ */
352
+
353
+ /**
354
+ * @typedef {Object} ProvisionAuthStructured
355
+ * @property {boolean} ok - True when credentials were deployed (verified or not).
356
+ * @property {"ok" | "deployed_unverified" | "deployed_with_errors" | "skipped_local_member" |
357
+ * "member_not_found" | "member_offline" | "secret_variable_not_found" |
358
+ * "secret_variable_denied" | "secret_variable_expired" | "oauth_not_supported" |
359
+ * "oauth_token_expired_no_refresh" | "oauth_credential_file_missing" |
360
+ * "oauth_credential_write_failed" | "oauth_settings_merge_failed" | "oauth_copy_failed" |
361
+ * "oob_cancelled"} reason - Machine-readable outcome code. Branch on this, never on the text.
362
+ * @property {string|null} provider - The resolved ProviderAdapter's own name (claude, codex,
363
+ * copilot, agy, opencode or none -- there is no gemini adapter), null when unresolved.
364
+ * @property {string|null} credentialLabel - What was deployed, never the secret: the env var
365
+ * name for the API-key flow (e.g. ANTHROPIC_API_KEY) or "oauth" for the file-copy flow.
366
+ * @property {string|null} expiresAt - Credential expiry as an ISO timestamp, or null meaning
367
+ * "no expiry tracked -> OK".
368
+ * @property {boolean} verified - True when the post-deploy auth check confirmed working auth.
369
+ * @property {string|null} memberId - Registry id of the resolved member, or null.
370
+ * @property {string|null} memberName - Friendly name of the resolved member, or null.
371
+ *
372
+ * Mirrors src/tools/provision-auth.ts's ProvisionAuthStructured field-for-field
373
+ * (apra-fleet-3swo.7.2). Carries no plaintext credential of any kind.
374
+ */
375
+
376
+ /**
377
+ * @typedef {Object} ProvisionVcsAuthStructured
378
+ * @property {boolean} ok - True when the credential was actually deployed onto the member.
379
+ * @property {"ok" | "deployed_unverified" | "deployed_verification_skipped" |
380
+ * "member_not_found" | "member_offline" | "secret_variable_not_found" |
381
+ * "secret_variable_denied" | "secret_variable_expired" | "oob_cancelled" |
382
+ * "credential_assembly_unsupported" | "credential_assembly_failed" | "deploy_threw" |
383
+ * "deploy_failed"} reason - Machine-readable outcome code. Branch on this, never on the text.
384
+ * @property {string} provider - The VCS provider requested.
385
+ * @property {string} credentialLabel - Credential label the helper was deployed under
386
+ * (defaults to the provider name).
387
+ * @property {string|null} scopeUrl - Git credential scope URL the helper was registered for.
388
+ * @property {string|null} expiresAt - Token expiry as an ISO timestamp, or null meaning "no
389
+ * expiry tracked -> OK" (the reading checkVcsTokenExpiry applies server-side). Read this
390
+ * instead of scraping an "expiresAt:" line out of the summary text.
391
+ * @property {boolean} verified - True only when testConnectivity() actually ran AND succeeded.
392
+ * @property {boolean} verificationSkipped - True when the connectivity check was not performed.
393
+ * @property {Record<string, string>|null} metadata - The provider's own deploy metadata,
394
+ * filtered through a server-side key allowlist before it reaches this field (an unrecognised
395
+ * key is dropped, never passed through). Providers additionally mask the token value here to
396
+ * its first four characters plus asterisks, so this never carries the plaintext token.
397
+ * @property {string|null} expiryWarning - Near-expiry warning text when one applies, else null.
398
+ * @property {string|null} memberId - Registry id of the resolved member, or null.
399
+ * @property {string|null} memberName - Friendly name of the resolved member, or null.
400
+ * @property {string|null} message - Human-readable cause of a non-ok outcome (e.g. "No repos
401
+ * specified and none on agent config."), or null when ok is true. Previously this text only
402
+ * reached the caller inside the tool's `text` content, so a caller reading only
403
+ * structuredContent saw nothing but the bare `reason` code. Read this instead of parsing the
404
+ * `[FAIL] ...` prefix out of `text`.
405
+ *
406
+ * Mirrors src/tools/provision-vcs-auth.ts's ProvisionVcsAuthStructured field-for-field
407
+ * (apra-fleet-3swo.7.2).
408
+ */
409
+
201
410
  /**
202
411
  * @typedef {Object} ProvisionVcsAuthOptions
203
412
  * @property {string} [member_id] - UUID of the member
@@ -205,26 +414,29 @@
205
414
  * @property {"github" | "bitbucket" | "azure-devops"} provider - VCS provider to configure
206
415
  * @property {string} [label] - Credential label (slug, e.g. "work-github"). Defaults to provider name.
207
416
  * @property {string} [scope_url] - Git credential scope URL (e.g. "https://github.com/my-org").
208
- * Defaults to "https://<host>".
417
+ * Defaults to "https://<host>". For an Azure DevOps repo on the legacy host, pass
418
+ * "https://ORG.visualstudio.com" so the PAT is bound to the host the member pushes to.
209
419
  * @property {"github-app" | "pat"} [github_mode] - GitHub auth mode: github-app (mint via
210
420
  * configured app) or pat (personal access token)
211
421
  * @property {string} [token] - Personal access token (GitHub PAT or Azure DevOps PAT).
212
- * Supports {{secure.NAME}} token -- resolved from the credential store server-side before use.
422
+ * Supports {{secret.NAME}} token -- resolved from the credential store server-side before use.
213
423
  * @property {"read" | "push" | "push+pr" | "admin" | "issues" | "full"} [git_access] - GitHub App access
214
424
  * level override
215
425
  * @property {string[]} [repos] - GitHub App repository list override
216
426
  * @property {string} [email] - Bitbucket account email
217
- * @property {string} [api_token] - Bitbucket API token. Supports {{secure.NAME}} token --
427
+ * @property {string} [api_token] - Bitbucket API token. Supports {{secret.NAME}} token --
218
428
  * resolved from the credential store server-side before use.
219
429
  * @property {string} [workspace] - Bitbucket workspace slug
220
- * @property {string} [org_url] - Azure DevOps organization URL (e.g. https://dev.azure.com/myorg)
221
- * @property {string} [pat] - Azure DevOps personal access token. Supports {{secure.NAME}}
430
+ * @property {string} [org_url] - Azure DevOps organization URL (e.g. https://dev.azure.com/myorg,
431
+ * or the legacy https://myorg.visualstudio.com)
432
+ * @property {string} [pat] - Azure DevOps personal access token. Supports {{secret.NAME}}
222
433
  * token -- resolved from the credential store server-side before use.
223
434
  * @property {string} [pat_expires_at] - ISO 8601 date/time the Azure DevOps PAT expires, as
224
435
  * chosen when creating the token. Propagated to the member registry so provisioning can
225
436
  * warn when the PAT is nearing expiry. Must be parseable by Date.parse -- the server
226
437
  * REJECTS an unparseable value rather than storing it, because a NaN expiry silences the
227
- * warning and makes the credential-cleanup timer fall back to its 55-minute default.
438
+ * warning entirely (the credential-cleanup timer skips auto-revoke scheduling when no
439
+ * real expiry is known, rather than falling back to any default TTL).
228
440
  */
229
441
 
230
442
  /**
@@ -316,8 +528,14 @@ const TIMEOUT_GRACE_MS = 30 * 1000;
316
528
 
317
529
  /**
318
530
  * Derives a client-side McpClient.request() timeout (ms) from a payload's
319
- * own timeout hints. Prefers max_total_s (a hard ceiling) over timeout_s
320
- * (an inactivity timeout) when both are present, then adds a grace margin.
531
+ * own timeout hints. Intentionally prefers max_total_s (a hard ceiling) over
532
+ * timeout_s (the stall-detector inactivity baseline) when both are present.
533
+ * This reflects the post-apra-fleet-25yl.2 contract: max_total_s is the
534
+ * primary exec deadline for Claude/AGY, while timeout_s drives only the stall
535
+ * detector's per-dispatch baseline (other providers have different exec-timer
536
+ * mappings per their own adapters). The client's own deadline thus uses the
537
+ * appropriate upper bound for the dispatch. Adds a grace margin to account
538
+ * for server-side retry overhead.
321
539
  * Returns undefined when neither hint is present, letting McpClient fall
322
540
  * back to its own conservative default (never infinite).
323
541
  *
@@ -357,6 +575,32 @@ export function parseToolJson(result) {
357
575
  throw new Error('No JSON payload in tool result');
358
576
  }
359
577
 
578
+ const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
579
+
580
+ /**
581
+ * Typed read of an execute_prompt permission denial. Accepts the raw executePrompt()
582
+ * result or its `structuredContent`; returns the {@link PermissionDenied} block when
583
+ * `reason === 'permission_denied'` and the block is well-formed, else null.
584
+ *
585
+ * @param {{structuredContent?: ExecutePromptStructured} | ExecutePromptStructured | null | undefined} result
586
+ * @returns {PermissionDenied | null}
587
+ */
588
+ export function permissionDenialOf(result) {
589
+ const sc = result && typeof result === 'object' && 'structuredContent' in result ? result.structuredContent : result;
590
+ if (!sc || sc.reason !== 'permission_denied') return null;
591
+ const d = sc.permissionDenied;
592
+ if (!d || typeof d !== 'object') return null;
593
+ if (!isStringArray(d.actions) || !isStringArray(d.suggestedGrants) || typeof d.hint !== 'string') return null;
594
+ if (!Array.isArray(d.denials) || !d.denials.every((x) => x && typeof x.action === 'string' && (x.target === undefined || typeof x.target === 'string'))) return null;
595
+ return {
596
+ actions: [...d.actions],
597
+ denials: d.denials.map((x) => (x.target === undefined ? { action: x.action } : { action: x.action, target: x.target })),
598
+ suggestedGrants: [...d.suggestedGrants],
599
+ hint: d.hint,
600
+ signals: isStringArray(d.signals) ? [...d.signals] : [],
601
+ };
602
+ }
603
+
360
604
  export class ApraFleet {
361
605
  /**
362
606
  * @param {{ callTool: (name: string, args: Record<string, any>, opts?: { timeoutMs?: number, signal?: AbortSignal }) => Promise<any> }} mcpClient
@@ -368,6 +612,9 @@ export class ApraFleet {
368
612
  /**
369
613
  * Run an AI prompt on a member.
370
614
  * @param {ExecutePromptOptions} options
615
+ * @returns {Promise<{content?: {type: string, text: string}[], structuredContent?: ExecutePromptStructured}>}
616
+ * the raw callTool() result -- see the {@link ExecutePromptStructured} typedef above
617
+ * for the structuredContent shape (reason, usageLimit, sessionId, usage, ...).
371
618
  */
372
619
  async executePrompt(options) {
373
620
  const { timeoutMs, signal, ...payload } = options;
@@ -464,9 +711,35 @@ export class ApraFleet {
464
711
  return this.mcpClient.callTool('remove_member', options);
465
712
  }
466
713
 
714
+ /**
715
+ * Reserve, release or force-release exclusive ownership of a member for a
716
+ * sprint (src/tools/member-reservation.ts).
717
+ *
718
+ * The MCP result carries BOTH halves: `content[0].text` is the unchanged
719
+ * human-readable summary, and `structuredContent` is a
720
+ * MemberReservationStructured. Programmatic callers must branch on
721
+ * `structuredContent.outcome` -- string-matching the prose is exactly what
722
+ * apra-fleet-3swo.7.1 removed the need for.
723
+ *
724
+ * @param {MemberReservationOptions} options
725
+ * @returns {Promise<{ content: Array<{type: string, text: string}>,
726
+ * structuredContent: MemberReservationStructured }>}
727
+ */
728
+ async memberReservation(options) {
729
+ return this.mcpClient.callTool('member_reservation', options);
730
+ }
731
+
467
732
  /**
468
733
  * Provision LLM auth (OAuth session copy or API key) onto a member.
734
+ *
735
+ * The MCP result carries both halves: `content[0].text` is the
736
+ * human-readable summary (ASCII markers -- [OK]/[WARN]/[FAIL]/[SKIP], no
737
+ * emoji) and `structuredContent` is a ProvisionAuthStructured. Branch on
738
+ * `structuredContent.ok` / `.reason`, never on the summary text.
739
+ *
469
740
  * @param {ProvisionLlmAuthOptions} options
741
+ * @returns {Promise<{ content: Array<{type: string, text: string}>,
742
+ * structuredContent: ProvisionAuthStructured }>}
470
743
  */
471
744
  async provisionLlmAuth(options) {
472
745
  return this.mcpClient.callTool('provision_llm_auth', options);
@@ -475,12 +748,41 @@ export class ApraFleet {
475
748
  /**
476
749
  * Provision VCS (git host) auth -- GitHub App token / PAT, Bitbucket API
477
750
  * token, or Azure DevOps PAT -- onto a member.
751
+ *
752
+ * Same two-halves result shape as provisionLlmAuth: read
753
+ * `structuredContent.ok`/`.reason` for the outcome and
754
+ * `structuredContent.expiresAt` for the token expiry, instead of parsing
755
+ * an "expiresAt:" line out of the prose.
756
+ *
478
757
  * @param {ProvisionVcsAuthOptions} options
758
+ * @returns {Promise<{ content: Array<{type: string, text: string}>,
759
+ * structuredContent: ProvisionVcsAuthStructured }>}
479
760
  */
480
761
  async provisionVcsAuth(options) {
481
762
  return this.mcpClient.callTool('provision_vcs_auth', options);
482
763
  }
483
764
 
765
+ /**
766
+ * Run a credential-requiring git/VCS command on a member WITHOUT the
767
+ * caller ever learning the credential (src/tools/vcs-credential-exec.ts).
768
+ *
769
+ * This is the server-side replacement for reading a token back out of the
770
+ * deployed git-credential-helper: the server reads the credential
771
+ * in-process, substitutes whichever placeholder(s) the command contains
772
+ * -- {{vcs_token}} (bare, already quoted for the member's shell) and/or
773
+ * {{vcs_token_inline}} (for use inside the caller's own single quotes,
774
+ * escaped for that interior with no quotes of its own) -- dispatches the
775
+ * command, and redacts the value from the returned stdout/stderr. The
776
+ * plaintext appears in no field of the result.
777
+ *
778
+ * @param {VcsCredentialExecOptions} options
779
+ * @returns {Promise<{ content: Array<{type: string, text: string}>,
780
+ * structuredContent: VcsCredentialExecStructured }>}
781
+ */
782
+ async vcsCredentialExec(options) {
783
+ return this.mcpClient.callTool('vcs_credential_exec', options);
784
+ }
785
+
484
786
  /**
485
787
  * Compose and deliver a scoped permission profile to a member.
486
788
  * @param {ComposePermissionsOptions} options
@@ -61,8 +61,12 @@ export class AbortError extends ClientError {
61
61
  * to branch on, add a typed error class HERE (transport/request-level
62
62
  * failures) or a `reason` code on the workflow layer's AgentDispatchError
63
63
  * (dispatch-level failures reported via structuredContent.isError, e.g.
64
- * 'busy', 'empty_response', 'max_turns_exhausted') -- never a bare Error
65
- * with only a message string to sniff.
64
+ * 'busy', 'empty_response', 'max_turns_exhausted', 'usage_limit') -- never a
65
+ * bare Error with only a message string to sniff. 'usage_limit'
66
+ * (apra-fleet-hzeb.2) additionally carries a `usageLimit` block ({type,
67
+ * resumeAt, resumeAtSource, message} -- see api.mjs's ExecutePromptStructured
68
+ * typedef) on AgentDispatchError.details, since a plan/quota exhaustion needs
69
+ * a resumeAt to schedule a resume, not just a reason string.
66
70
  */
67
71
  export class TransportClosedError extends ClientError {
68
72
  constructor(message, opts = {}) {
@@ -12,8 +12,16 @@ a `parent-child` ancestor/descendant and remove it.
12
12
 
13
13
  **How to wire a decomposed item correctly:**
14
14
  - Parent the subtasks under the item being decomposed: `bd create ... --parent <item-id>`.
15
- - Order subtasks relative to EACH OTHER with `blocks` (e.g. "test task blocked by impl
16
- task" -- they're siblings, this is fine): `bd dep add <test-task> <impl-task>`.
15
+ - Order subtasks relative to EACH OTHER with `blocks` ONLY when they are in DIFFERENT
16
+ streak lanes (different `metadata.streak` ids) -- e.g. "lane B blocked by lane A's last
17
+ task": `bd dep add <B-task> <A-last-task>`. A bead with no `streak` metadata at all is
18
+ its own lane, so a `blocks` edge involving it (either side unlaned, or both) is always a
19
+ cross-lane edge and is fine. Inside one lane, order comes from `streakOrder` alone; a
20
+ `blocks` edge between two tasks that share a `streak` id is a bug, not a convenience --
21
+ the dispatch engine only ever streaks together tasks that are simultaneously unblocked,
22
+ so an intra-lane edge silently splits the lane into separate review rounds instead of
23
+ ordering it. Lanes are the review unit: `streakOrder` orders WITHIN a lane, `blocks`
24
+ orders BETWEEN lanes.
17
25
  - Never `bd dep add <item-id> <subtask-id>` or `bd dep add <subtask-id> <item-id>` -- the
18
26
  item's "not done until subtasks close" status comes from inspecting its children
19
27
  (`dependent_count`, `bd epic status <id>` for epic-typed parents), never from a `blocks`
@@ -12,7 +12,13 @@ analyze AND mutate beads directly -- but you never touch code beyond reading it.
12
12
 
13
13
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any grooming decision)
14
14
 
15
+ <!-- if-tool: ToolSearch -->
15
16
  1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime,mcp__apra-fleet__kb_capture"`
17
+ <!-- else-tool: ToolSearch -->
18
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
19
+ tool it wants directly. Confirm your environment exposes those tools, then call
20
+ them as written.
21
+ <!-- end-tool: ToolSearch -->
16
22
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo whose backlog
17
23
  you are grooming, and `hint_modules` naming the subsystems the assigned beads touch.
18
24
  Trust CONFIRMED entries fully. Use INFERRED entries as hints, not facts. This matters
@@ -22,7 +28,12 @@ analyze AND mutate beads directly -- but you never touch code beyond reading it.
22
28
  items land unactionable -- call `mcp__apra-fleet__kb_capture` with type "knowledge".
23
29
  Do not capture per-sprint churn; capture what stays true.
24
30
 
31
+ <!-- if-tool: ToolSearch -->
25
32
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
33
+ <!-- else-tool: ToolSearch -->
34
+ If those KB tools are not available in your environment (MCP server not running), skip
35
+ these steps and proceed.
36
+ <!-- end-tool: ToolSearch -->
26
37
 
27
38
  ## Usage modes
28
39
 
@@ -189,6 +200,20 @@ Cross `priority`/urgency-language against content quality for every in-scope bea
189
200
  - **Priority x age**: compare `created_at`/`updated_at` to now, always jointly with
190
201
  priority. Old+low = noise; old+high = an explicit "still worth pursuing or stale?" call.
191
202
 
203
+ ## Step 6a -- Hygiene sweep (every time)
204
+
205
+ Same identity scope as everything else: beads assigned to other people are never touched.
206
+
207
+ - **Follow-ups under closed parents**: an open bead whose parent (epic or otherwise) is
208
+ closed is a leftover. Groom it -- close with evidence if landed or duplicate; otherwise
209
+ append the parent's context to its notes (parent title, goal, relevant decisions, key
210
+ files, originating branch/PR) so it stands alone, then detach it
211
+ (`bd update <id> --parent ""`) and label it `from-epic:<parent-id>`.
212
+ - **Fully closed epics** (epic and every descendant closed): list them as deletion
213
+ candidates with descendant counts. Never `bd delete` without operator confirmation.
214
+ - **No token-estimate memories**: never write per-bead or aggregate token/cost estimates
215
+ with `bd remember`; flag any found for `bd forget`.
216
+
192
217
  ## Step 7 -- Cohesive sprint-set proposal (1b)
193
218
 
194
219
  From the ready, verified, well-formed, non-duplicate subset only:
@@ -24,7 +24,13 @@ Your dispatch prompt must supply ONE of the two scoping forms:
24
24
 
25
25
  ## Step 0 -- Knowledge Bank (required -- do this BEFORE any other work)
26
26
 
27
+ <!-- if-tool: ToolSearch -->
27
28
  1. Run ToolSearch with query `"select:mcp__apra-fleet__kb_session_prime"`
29
+ <!-- else-tool: ToolSearch -->
30
+ 1. No tool-discovery step is needed on this provider: every step below names the KB
31
+ tool it wants directly. Confirm your environment exposes those tools, then call
32
+ them as written.
33
+ <!-- end-tool: ToolSearch -->
28
34
  2. Call `mcp__apra-fleet__kb_session_prime` with `repo_path` set to the repo whose CI you
29
35
  are checking, and `hint_modules` naming its CI workflow files. Trust CONFIRMED entries
30
36
  fully. Use INFERRED entries as hints, not facts. Known-flaky tests and known CI failure
@@ -32,7 +38,12 @@ Your dispatch prompt must supply ONE of the two scoping forms:
32
38
  3. Do NOT capture. You poll a status API; you verify no claim about this repository, so you
33
39
  have no basis to write one down.
34
40
 
41
+ <!-- if-tool: ToolSearch -->
35
42
  If ToolSearch returns no KB tools (MCP server not running), skip these steps and proceed.
43
+ <!-- else-tool: ToolSearch -->
44
+ If those KB tools are not available in your environment (MCP server not running), skip
45
+ these steps and proceed.
46
+ <!-- end-tool: ToolSearch -->
36
47
 
37
48
  ## Step 1 -- List recent CI runs
38
49