@apralabs/apra-fleet 0.4.1 → 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 (476) hide show
  1. package/README.md +53 -12
  2. package/dist/agents/backlog-groomer.md +42 -21
  3. package/dist/agents/ci-watcher.md +14 -0
  4. package/dist/agents/deployer.md +59 -46
  5. package/dist/agents/doer.md +157 -134
  6. package/dist/agents/harvester.md +31 -32
  7. package/dist/agents/integ-test-runner.md +92 -113
  8. package/dist/agents/kb-reconciler.md +40 -42
  9. package/dist/agents/plan-reviewer.md +139 -63
  10. package/dist/agents/planner.md +176 -100
  11. package/dist/agents/regression-test-runner.md +77 -81
  12. package/dist/agents/reviewer.md +69 -85
  13. package/dist/agents/schemas/integ-test-runner-output.json +1 -1
  14. package/dist/agents/schemas/plan-reviewer-output.json +37 -0
  15. package/dist/agents/schemas/regression-test-runner-output.json +4 -17
  16. package/dist/cli/agent-transform.d.ts +83 -2
  17. package/dist/cli/agent-transform.d.ts.map +1 -1
  18. package/dist/cli/agent-transform.js +266 -21
  19. package/dist/cli/agent-transform.js.map +1 -1
  20. package/dist/cli/auth.d.ts.map +1 -1
  21. package/dist/cli/auth.js +29 -11
  22. package/dist/cli/auth.js.map +1 -1
  23. package/dist/cli/config.d.ts +7 -5
  24. package/dist/cli/config.d.ts.map +1 -1
  25. package/dist/cli/config.js +44 -43
  26. package/dist/cli/config.js.map +1 -1
  27. package/dist/cli/install.d.ts +33 -0
  28. package/dist/cli/install.d.ts.map +1 -1
  29. package/dist/cli/install.js +294 -61
  30. package/dist/cli/install.js.map +1 -1
  31. package/dist/cli/kb-directives.d.ts.map +1 -1
  32. package/dist/cli/kb-directives.js +2 -1
  33. package/dist/cli/kb-directives.js.map +1 -1
  34. package/dist/cli/register-member.d.ts.map +1 -1
  35. package/dist/cli/register-member.js +7 -3
  36. package/dist/cli/register-member.js.map +1 -1
  37. package/dist/cli/start.d.ts.map +1 -1
  38. package/dist/cli/start.js +7 -0
  39. package/dist/cli/start.js.map +1 -1
  40. package/dist/cli/uninstall.d.ts.map +1 -1
  41. package/dist/cli/uninstall.js +5 -3
  42. package/dist/cli/uninstall.js.map +1 -1
  43. package/dist/cli/watch.d.ts +26 -3
  44. package/dist/cli/watch.d.ts.map +1 -1
  45. package/dist/cli/watch.js +41 -9
  46. package/dist/cli/watch.js.map +1 -1
  47. package/dist/commands/kb-server.d.ts +3 -0
  48. package/dist/commands/kb-server.d.ts.map +1 -1
  49. package/dist/commands/kb-server.js +43 -3
  50. package/dist/commands/kb-server.js.map +1 -1
  51. package/dist/index.js +3 -3
  52. package/dist/os/git-bash-candidates.d.ts +35 -0
  53. package/dist/os/git-bash-candidates.d.ts.map +1 -0
  54. package/dist/os/git-bash-candidates.js +46 -0
  55. package/dist/os/git-bash-candidates.js.map +1 -0
  56. package/dist/os/index.d.ts +13 -4
  57. package/dist/os/index.d.ts.map +1 -1
  58. package/dist/os/index.js +17 -2
  59. package/dist/os/index.js.map +1 -1
  60. package/dist/os/linux.d.ts +6 -0
  61. package/dist/os/linux.d.ts.map +1 -1
  62. package/dist/os/linux.js +36 -3
  63. package/dist/os/linux.js.map +1 -1
  64. package/dist/os/os-commands.d.ts +68 -2
  65. package/dist/os/os-commands.d.ts.map +1 -1
  66. package/dist/os/os-commands.js.map +1 -1
  67. package/dist/os/windows-gitbash.d.ts +98 -0
  68. package/dist/os/windows-gitbash.d.ts.map +1 -0
  69. package/dist/os/windows-gitbash.js +259 -0
  70. package/dist/os/windows-gitbash.js.map +1 -0
  71. package/dist/os/windows.d.ts +6 -0
  72. package/dist/os/windows.d.ts.map +1 -1
  73. package/dist/os/windows.js +73 -8
  74. package/dist/os/windows.js.map +1 -1
  75. package/dist/providers/agy.d.ts +118 -8
  76. package/dist/providers/agy.d.ts.map +1 -1
  77. package/dist/providers/agy.js +580 -55
  78. package/dist/providers/agy.js.map +1 -1
  79. package/dist/providers/claude.d.ts +83 -4
  80. package/dist/providers/claude.d.ts.map +1 -1
  81. package/dist/providers/claude.js +365 -12
  82. package/dist/providers/claude.js.map +1 -1
  83. package/dist/providers/codex.d.ts +7 -4
  84. package/dist/providers/codex.d.ts.map +1 -1
  85. package/dist/providers/codex.js +24 -4
  86. package/dist/providers/codex.js.map +1 -1
  87. package/dist/providers/copilot.d.ts +7 -4
  88. package/dist/providers/copilot.d.ts.map +1 -1
  89. package/dist/providers/copilot.js +27 -4
  90. package/dist/providers/copilot.js.map +1 -1
  91. package/dist/providers/index.d.ts +0 -1
  92. package/dist/providers/index.d.ts.map +1 -1
  93. package/dist/providers/index.js +0 -3
  94. package/dist/providers/index.js.map +1 -1
  95. package/dist/providers/none.d.ts +7 -4
  96. package/dist/providers/none.d.ts.map +1 -1
  97. package/dist/providers/none.js +22 -4
  98. package/dist/providers/none.js.map +1 -1
  99. package/dist/providers/opencode.d.ts +6 -3
  100. package/dist/providers/opencode.d.ts.map +1 -1
  101. package/dist/providers/opencode.js +27 -4
  102. package/dist/providers/opencode.js.map +1 -1
  103. package/dist/providers/provider.d.ts +215 -11
  104. package/dist/providers/provider.d.ts.map +1 -1
  105. package/dist/providers/provider.js +58 -2
  106. package/dist/providers/provider.js.map +1 -1
  107. package/dist/services/agent-provisioner.js +2 -2
  108. package/dist/services/agent-provisioner.js.map +1 -1
  109. package/dist/services/agy-project.d.ts +102 -0
  110. package/dist/services/agy-project.d.ts.map +1 -0
  111. package/dist/services/agy-project.js +356 -0
  112. package/dist/services/agy-project.js.map +1 -0
  113. package/dist/services/auth-socket.js +4 -4
  114. package/dist/services/auth-web.js +1 -1
  115. package/dist/services/cloud/activity.js +2 -2
  116. package/dist/services/cloud/activity.js.map +1 -1
  117. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  118. package/dist/services/cloud/lifecycle.js +33 -4
  119. package/dist/services/cloud/lifecycle.js.map +1 -1
  120. package/dist/services/context-admission.d.ts.map +1 -1
  121. package/dist/services/context-admission.js +9 -7
  122. package/dist/services/context-admission.js.map +1 -1
  123. package/dist/services/credential-cleanup.d.ts.map +1 -1
  124. package/dist/services/credential-cleanup.js +47 -10
  125. package/dist/services/credential-cleanup.js.map +1 -1
  126. package/dist/services/exit-drain.d.ts +44 -0
  127. package/dist/services/exit-drain.d.ts.map +1 -0
  128. package/dist/services/exit-drain.js +52 -0
  129. package/dist/services/exit-drain.js.map +1 -0
  130. package/dist/services/github-app.d.ts.map +1 -1
  131. package/dist/services/github-app.js +32 -4
  132. package/dist/services/github-app.js.map +1 -1
  133. package/dist/services/http-transport.d.ts +1 -0
  134. package/dist/services/http-transport.d.ts.map +1 -1
  135. package/dist/services/http-transport.js +48 -1
  136. package/dist/services/http-transport.js.map +1 -1
  137. package/dist/services/knowledge/kb-config.d.ts +42 -0
  138. package/dist/services/knowledge/kb-config.d.ts.map +1 -0
  139. package/dist/services/knowledge/kb-config.js +54 -0
  140. package/dist/services/knowledge/kb-config.js.map +1 -0
  141. package/dist/services/knowledge/kb-providers.d.ts +7 -1
  142. package/dist/services/knowledge/kb-providers.d.ts.map +1 -1
  143. package/dist/services/knowledge/kb-providers.js +191 -17
  144. package/dist/services/knowledge/kb-providers.js.map +1 -1
  145. package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
  146. package/dist/services/knowledge/require-sqlite-project.d.ts.map +1 -0
  147. package/dist/services/knowledge/require-sqlite-project.js +38 -0
  148. package/dist/services/knowledge/require-sqlite-project.js.map +1 -0
  149. package/dist/services/member-home.d.ts +1 -1
  150. package/dist/services/member-home.d.ts.map +1 -1
  151. package/dist/services/member-home.js +15 -12
  152. package/dist/services/member-home.js.map +1 -1
  153. package/dist/services/model-pricing.d.ts.map +1 -1
  154. package/dist/services/model-pricing.js +7 -8
  155. package/dist/services/model-pricing.js.map +1 -1
  156. package/dist/services/orphan-recovery.d.ts +6 -3
  157. package/dist/services/orphan-recovery.d.ts.map +1 -1
  158. package/dist/services/orphan-recovery.js +17 -14
  159. package/dist/services/orphan-recovery.js.map +1 -1
  160. package/dist/services/preflight-check.js +2 -2
  161. package/dist/services/preflight-check.js.map +1 -1
  162. package/dist/services/secret-token.d.ts +38 -0
  163. package/dist/services/secret-token.d.ts.map +1 -0
  164. package/dist/services/secret-token.js +51 -0
  165. package/dist/services/secret-token.js.map +1 -0
  166. package/dist/services/service-manager/types.d.ts +3 -1
  167. package/dist/services/service-manager/types.d.ts.map +1 -1
  168. package/dist/services/service-manager/windows.d.ts +14 -2
  169. package/dist/services/service-manager/windows.d.ts.map +1 -1
  170. package/dist/services/service-manager/windows.js +65 -7
  171. package/dist/services/service-manager/windows.js.map +1 -1
  172. package/dist/services/shell-probe.d.ts +131 -0
  173. package/dist/services/shell-probe.d.ts.map +1 -0
  174. package/dist/services/shell-probe.js +210 -0
  175. package/dist/services/shell-probe.js.map +1 -0
  176. package/dist/services/singleton.d.ts +2 -0
  177. package/dist/services/singleton.d.ts.map +1 -1
  178. package/dist/services/singleton.js +1 -1
  179. package/dist/services/singleton.js.map +1 -1
  180. package/dist/services/ssh.d.ts.map +1 -1
  181. package/dist/services/ssh.js +60 -4
  182. package/dist/services/ssh.js.map +1 -1
  183. package/dist/services/stall/find-log-file.d.ts.map +1 -1
  184. package/dist/services/stall/find-log-file.js +22 -16
  185. package/dist/services/stall/find-log-file.js.map +1 -1
  186. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  187. package/dist/services/stall/read-log-tail.js +26 -15
  188. package/dist/services/stall/read-log-tail.js.map +1 -1
  189. package/dist/services/stall/stall-detector.d.ts +53 -4
  190. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  191. package/dist/services/stall/stall-detector.js +212 -34
  192. package/dist/services/stall/stall-detector.js.map +1 -1
  193. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  194. package/dist/services/stall/stall-poller.js +35 -42
  195. package/dist/services/stall/stall-poller.js.map +1 -1
  196. package/dist/services/strategy.d.ts +9 -0
  197. package/dist/services/strategy.d.ts.map +1 -1
  198. package/dist/services/strategy.js +119 -8
  199. package/dist/services/strategy.js.map +1 -1
  200. package/dist/services/substitution-engine.js +2 -2
  201. package/dist/services/substitution-engine.js.map +1 -1
  202. package/dist/services/tool-registry.d.ts.map +1 -1
  203. package/dist/services/tool-registry.js +5 -3
  204. package/dist/services/tool-registry.js.map +1 -1
  205. package/dist/services/user-config.js +1 -1
  206. package/dist/services/user-config.js.map +1 -1
  207. package/dist/services/vcs/azure-devops.d.ts +67 -2
  208. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  209. package/dist/services/vcs/azure-devops.js +281 -15
  210. package/dist/services/vcs/azure-devops.js.map +1 -1
  211. package/dist/services/vcs/bitbucket.d.ts.map +1 -1
  212. package/dist/services/vcs/bitbucket.js +16 -0
  213. package/dist/services/vcs/bitbucket.js.map +1 -1
  214. package/dist/services/vcs/github.d.ts.map +1 -1
  215. package/dist/services/vcs/github.js +24 -0
  216. package/dist/services/vcs/github.js.map +1 -1
  217. package/dist/services/vcs/types.d.ts +123 -2
  218. package/dist/services/vcs/types.d.ts.map +1 -1
  219. package/dist/skills/fleet-sprint-cli/SKILL.md +20 -1
  220. package/dist/skills/pm/SKILL.md +1 -2
  221. package/dist/skills/pm/cost.md +0 -4
  222. package/dist/skills/pm/fleet-addendum.md +2 -3
  223. package/dist/tools/check-status.d.ts +7 -4
  224. package/dist/tools/check-status.d.ts.map +1 -1
  225. package/dist/tools/check-status.js +5 -3
  226. package/dist/tools/check-status.js.map +1 -1
  227. package/dist/tools/cloud-control.js +2 -2
  228. package/dist/tools/cloud-control.js.map +1 -1
  229. package/dist/tools/compose-permissions.d.ts +6 -0
  230. package/dist/tools/compose-permissions.d.ts.map +1 -1
  231. package/dist/tools/compose-permissions.js +211 -50
  232. package/dist/tools/compose-permissions.js.map +1 -1
  233. package/dist/tools/credential-store-set.js +1 -1
  234. package/dist/tools/execute-command.d.ts.map +1 -1
  235. package/dist/tools/execute-command.js +56 -29
  236. package/dist/tools/execute-command.js.map +1 -1
  237. package/dist/tools/execute-prompt.d.ts +15 -2
  238. package/dist/tools/execute-prompt.d.ts.map +1 -1
  239. package/dist/tools/execute-prompt.js +1214 -873
  240. package/dist/tools/execute-prompt.js.map +1 -1
  241. package/dist/tools/kb-capture.d.ts +2 -2
  242. package/dist/tools/kb-capture.d.ts.map +1 -1
  243. package/dist/tools/kb-capture.js +29 -5
  244. package/dist/tools/kb-capture.js.map +1 -1
  245. package/dist/tools/kb-export.d.ts +2 -2
  246. package/dist/tools/kb-export.d.ts.map +1 -1
  247. package/dist/tools/kb-export.js +3 -28
  248. package/dist/tools/kb-export.js.map +1 -1
  249. package/dist/tools/kb-feedback.d.ts.map +1 -1
  250. package/dist/tools/kb-feedback.js +3 -1
  251. package/dist/tools/kb-feedback.js.map +1 -1
  252. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -1
  253. package/dist/tools/kb-freshness-sweep.js +3 -1
  254. package/dist/tools/kb-freshness-sweep.js.map +1 -1
  255. package/dist/tools/kb-import.d.ts.map +1 -1
  256. package/dist/tools/kb-import.js +2 -1
  257. package/dist/tools/kb-import.js.map +1 -1
  258. package/dist/tools/kb-list.d.ts.map +1 -1
  259. package/dist/tools/kb-list.js +3 -1
  260. package/dist/tools/kb-list.js.map +1 -1
  261. package/dist/tools/kb-query.d.ts +2 -2
  262. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -1
  263. package/dist/tools/kb-reconcile-prefilter.js +3 -1
  264. package/dist/tools/kb-reconcile-prefilter.js.map +1 -1
  265. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -1
  266. package/dist/tools/kb-resolve-contradiction.js +3 -1
  267. package/dist/tools/kb-resolve-contradiction.js.map +1 -1
  268. package/dist/tools/kb-setup.d.ts.map +1 -1
  269. package/dist/tools/kb-setup.js +125 -20
  270. package/dist/tools/kb-setup.js.map +1 -1
  271. package/dist/tools/kb-stats.d.ts.map +1 -1
  272. package/dist/tools/kb-stats.js +64 -43
  273. package/dist/tools/kb-stats.js.map +1 -1
  274. package/dist/tools/list-members.d.ts +2 -2
  275. package/dist/tools/list-members.d.ts.map +1 -1
  276. package/dist/tools/list-members.js +7 -2
  277. package/dist/tools/list-members.js.map +1 -1
  278. package/dist/tools/member-detail.d.ts +2 -2
  279. package/dist/tools/member-detail.d.ts.map +1 -1
  280. package/dist/tools/member-detail.js +22 -3
  281. package/dist/tools/member-detail.js.map +1 -1
  282. package/dist/tools/member-reservation.d.ts +58 -1
  283. package/dist/tools/member-reservation.d.ts.map +1 -1
  284. package/dist/tools/member-reservation.js +71 -18
  285. package/dist/tools/member-reservation.js.map +1 -1
  286. package/dist/tools/monitor-task.d.ts.map +1 -1
  287. package/dist/tools/monitor-task.js +17 -2
  288. package/dist/tools/monitor-task.js.map +1 -1
  289. package/dist/tools/provision-auth.d.ts +80 -1
  290. package/dist/tools/provision-auth.d.ts.map +1 -1
  291. package/dist/tools/provision-auth.js +147 -59
  292. package/dist/tools/provision-auth.js.map +1 -1
  293. package/dist/tools/provision-vcs-auth.d.ts +96 -3
  294. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  295. package/dist/tools/provision-vcs-auth.js +254 -88
  296. package/dist/tools/provision-vcs-auth.js.map +1 -1
  297. package/dist/tools/register-member.d.ts +21 -12
  298. package/dist/tools/register-member.d.ts.map +1 -1
  299. package/dist/tools/register-member.js +141 -16
  300. package/dist/tools/register-member.js.map +1 -1
  301. package/dist/tools/remove-member.d.ts.map +1 -1
  302. package/dist/tools/remove-member.js +29 -4
  303. package/dist/tools/remove-member.js.map +1 -1
  304. package/dist/tools/revoke-vcs-auth.js +2 -2
  305. package/dist/tools/revoke-vcs-auth.js.map +1 -1
  306. package/dist/tools/send-email.d.ts +2 -2
  307. package/dist/tools/setup-git-app.d.ts.map +1 -1
  308. package/dist/tools/setup-git-app.js +11 -7
  309. package/dist/tools/setup-git-app.js.map +1 -1
  310. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  311. package/dist/tools/setup-ssh-key.js +2 -1
  312. package/dist/tools/setup-ssh-key.js.map +1 -1
  313. package/dist/tools/shutdown-server.d.ts +2 -0
  314. package/dist/tools/shutdown-server.d.ts.map +1 -1
  315. package/dist/tools/shutdown-server.js +23 -1
  316. package/dist/tools/shutdown-server.js.map +1 -1
  317. package/dist/tools/stop-prompt.js +2 -2
  318. package/dist/tools/stop-prompt.js.map +1 -1
  319. package/dist/tools/update-agent-cli.js +2 -2
  320. package/dist/tools/update-agent-cli.js.map +1 -1
  321. package/dist/tools/update-member.d.ts +21 -12
  322. package/dist/tools/update-member.d.ts.map +1 -1
  323. package/dist/tools/update-member.js +61 -12
  324. package/dist/tools/update-member.js.map +1 -1
  325. package/dist/tools/vcs-credential-exec.d.ts +127 -0
  326. package/dist/tools/vcs-credential-exec.d.ts.map +1 -0
  327. package/dist/tools/vcs-credential-exec.js +197 -0
  328. package/dist/tools/vcs-credential-exec.js.map +1 -0
  329. package/dist/types.d.ts +24 -1
  330. package/dist/types.d.ts.map +1 -1
  331. package/dist/utils/agent-helpers.d.ts +36 -0
  332. package/dist/utils/agent-helpers.d.ts.map +1 -1
  333. package/dist/utils/agent-helpers.js +39 -1
  334. package/dist/utils/agent-helpers.js.map +1 -1
  335. package/dist/utils/log-helpers.d.ts.map +1 -1
  336. package/dist/utils/log-helpers.js +2 -2
  337. package/dist/utils/log-helpers.js.map +1 -1
  338. package/dist/utils/platform.d.ts +7 -0
  339. package/dist/utils/platform.d.ts.map +1 -1
  340. package/dist/utils/platform.js +11 -1
  341. package/dist/utils/platform.js.map +1 -1
  342. package/dist/utils/prompt-errors.d.ts.map +1 -1
  343. package/dist/utils/prompt-errors.js +7 -1
  344. package/dist/utils/prompt-errors.js.map +1 -1
  345. package/dist/utils/shell-escape.d.ts +16 -0
  346. package/dist/utils/shell-escape.d.ts.map +1 -1
  347. package/dist/utils/shell-escape.js +22 -2
  348. package/dist/utils/shell-escape.js.map +1 -1
  349. package/dist/utils/vcs-provider-detect.d.ts +65 -0
  350. package/dist/utils/vcs-provider-detect.d.ts.map +1 -0
  351. package/dist/utils/vcs-provider-detect.js +109 -0
  352. package/dist/utils/vcs-provider-detect.js.map +1 -0
  353. package/dist/utils/workspace-trust.d.ts +20 -17
  354. package/dist/utils/workspace-trust.d.ts.map +1 -1
  355. package/dist/utils/workspace-trust.js +91 -1
  356. package/dist/utils/workspace-trust.js.map +1 -1
  357. package/dist/workflows/auto-sprint.js +180 -32
  358. package/package.json +7 -5
  359. package/packages/apra-fleet-client/src/client/api.mjs +403 -12
  360. package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
  361. package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
  362. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +42 -21
  363. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +14 -0
  364. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +59 -46
  365. package/packages/apra-fleet-se/apra-pm/agents/doer.md +157 -134
  366. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +31 -32
  367. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +92 -113
  368. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +40 -42
  369. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +139 -63
  370. package/packages/apra-fleet-se/apra-pm/agents/planner.md +176 -100
  371. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +77 -81
  372. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +69 -85
  373. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +1 -1
  374. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
  375. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
  376. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +1 -2
  377. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -4
  378. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -3
  379. package/packages/apra-fleet-se/bin/cli.mjs +280 -3
  380. package/packages/apra-fleet-se/bin/serve.mjs +114 -5
  381. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +481 -0
  382. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +491 -0
  383. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +282 -0
  384. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +208 -0
  385. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +638 -0
  386. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +301 -0
  387. package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
  388. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +8 -0
  389. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +199 -34
  390. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +516 -0
  391. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +184 -0
  392. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1121 -0
  393. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
  394. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +23 -8
  395. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +10 -8
  396. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +285 -4
  397. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +3 -3
  398. package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
  399. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +12 -12
  400. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
  401. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
  402. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +275 -99
  403. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1054 -39
  404. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +308 -0
  405. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
  406. package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
  407. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
  408. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +556 -0
  409. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +495 -0
  410. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +564 -0
  411. package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
  412. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +728 -0
  413. package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
  414. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +252 -0
  415. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +581 -0
  416. package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
  417. package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
  418. package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
  419. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +136 -0
  420. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +822 -0
  421. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +294 -0
  422. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +403 -0
  423. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +180 -0
  424. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
  425. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +390 -0
  426. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +323 -0
  427. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +232 -0
  428. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +174 -0
  429. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +197 -0
  430. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +305 -0
  431. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +559 -0
  432. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1416 -0
  433. package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
  434. package/packages/apra-fleet-se/fleet-sprint/runner.js +1672 -9072
  435. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
  436. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +159 -0
  437. package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
  438. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
  439. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +304 -0
  440. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +20 -1
  441. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +21 -2
  442. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +454 -0
  443. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +239 -0
  444. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +163 -0
  445. package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
  446. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +211 -0
  447. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1279 -0
  448. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +204 -19
  449. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +707 -12
  450. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
  451. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
  452. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +191 -43
  453. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +333 -6
  454. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +165 -0
  455. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +167 -37
  456. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
  457. package/packages/apra-fleet-se/package.json +1 -1
  458. package/packages/apra-fleet-workflow/src/viewer/index.mjs +178 -1
  459. package/packages/apra-fleet-workflow/src/workflow/index.mjs +478 -32
  460. package/skills/fleet/SKILL.md +27 -16
  461. package/skills/fleet/auth-azdevops.md +57 -7
  462. package/skills/fleet/auth-bitbucket.md +5 -5
  463. package/skills/fleet/auth-github.md +7 -6
  464. package/skills/fleet/beads-conflict-resolution.md +141 -0
  465. package/skills/fleet/beads.md +16 -12
  466. package/skills/fleet/onboarding.md +6 -6
  467. package/skills/fleet/permissions.md +11 -7
  468. package/skills/fleet/profiles/node.json +1 -1
  469. package/skills/fleet/skill-matrix.md +1 -1
  470. package/skills/fleet/troubleshooting.md +4 -3
  471. package/version.json +1 -1
  472. package/dist/providers/gemini.d.ts +0 -52
  473. package/dist/providers/gemini.d.ts.map +0 -1
  474. package/dist/providers/gemini.js +0 -236
  475. package/dist/providers/gemini.js.map +0 -1
  476. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -23
@@ -246,20 +246,48 @@ function summarizeExtractionAttempts(attempts) {
246
246
  }
247
247
 
248
248
  /**
249
- * Builds the lean repair re-ask prompt sent to the SAME member after an
250
- * invalid structured-output attempt. apra-fleet-02s.3: repair re-asks now
251
- * force `resume: true` (see the payload construction below), so the member's
252
- * session already has the original prompt/schema and its own invalid
253
- * output in context -- re-embedding all of that here would just re-spend
254
- * tokens re-sending what the resumed session already has. Only the
255
- * validation errors plus a short corrected-JSON instruction are needed.
256
- * @param {string} errorsText
249
+ * Builds the repair re-ask prompt sent to the SAME member after an invalid
250
+ * structured-output attempt.
251
+ *
252
+ * HISTORY -- this deliberately REVERSES apra-fleet-02s.3, which shrank this
253
+ * to a lean reminder (validation errors only) on the theory that the forced
254
+ * `resume: true` on repair (see the payload construction below) guarantees
255
+ * the member's session still holds the original prompt and schema.
256
+ * apra-fleet-dnri: that assumption does not always hold. Observed live on
257
+ * 2026-08-20, a reviewer dispatch that failed schema validation twice was
258
+ * re-asked with only the validator text; the resumed session did not carry
259
+ * the task inputs, so the agent had no base branch, no branch and no work
260
+ * ids, correctly refused to guess, and its refusal was read as a real
261
+ * verdict -- aborting the whole sprint. Resume is an optimization, not a
262
+ * guarantee, so the re-ask must be self-contained on its own.
263
+ *
264
+ * BOUNDED ON PURPOSE (the original token-cost decision still stands): only
265
+ * `initialPrompt` is reattached -- the caller's original prompt plus the same
266
+ * schema instruction the initial dispatch appended. The invalid response
267
+ * text, the session transcript and any per-attempt accumulated history are
268
+ * NOT re-embedded, and callers must always pass the ORIGINAL `initialPrompt`
269
+ * (never the previous round's repair prompt), so the reattached portion is
270
+ * byte-identical on every repair round and the prompt does not grow.
271
+ *
272
+ * The reattachment is framed as REFERENCE material, not as a fresh order:
273
+ * when the repair re-ask resumes the failed attempt's own session (see the
274
+ * resume disposition at the dispatch payload below) the member may have
275
+ * already done the underlying work, and a prompt that restates the task can
276
+ * read as an instruction to redo it.
277
+ *
278
+ * @param {string} errorsText - Summary of every failed extraction attempt.
279
+ * @param {string} initialPrompt - The fully-resolved original dispatch prompt
280
+ * (caller prompt + appended schema instruction), unchanged.
257
281
  */
258
- function buildRepairPrompt(errorsText) {
282
+ function buildRepairPrompt(errorsText, initialPrompt) {
259
283
  return `Your previous response could not be used.\n\n` +
260
284
  `Validation errors:\n${errorsText}\n\n` +
261
- `Please respond again with corrected JSON only, strictly conforming to the schema from your previous instructions. ` +
262
- `Do not include any commentary, explanation, or text outside the JSON.`;
285
+ `For reference, the original request and the required JSON schema were:\n` +
286
+ `--- BEGIN ORIGINAL REQUEST ---\n${initialPrompt}\n--- END ORIGINAL REQUEST ---\n\n` +
287
+ `Do NOT redo any work you have already completed for this request -- report the ` +
288
+ `result you already determined. Respond again with corrected JSON only, strictly ` +
289
+ `conforming to the schema above. Do not include any commentary, explanation, or ` +
290
+ `text outside the JSON.`;
263
291
  }
264
292
 
265
293
  /**
@@ -329,10 +357,13 @@ function buildRepairPrompt(errorsText) {
329
357
  * @property {number} [schemaRetries] - Only meaningful when `schema` is set. Bounded number
330
358
  * of repair re-asks to the SAME member after a parse/validation failure, before giving up
331
359
  * and throwing AgentOutputError. Defaults to 2 (so up to 3 total dispatches: 1 original +
332
- * 2 repairs). Each repair re-ask FORCES `resume: true` (apra-fleet-02s.3) so the member's
333
- * session already has the original prompt/schema and its own invalid output in context --
334
- * the re-ask itself is a lean reminder containing only the ajv validation/parse errors
335
- * plus a corrected-JSON instruction, not a re-embedding of the full original prompt/output.
360
+ * 2 repairs). Each repair re-ask FORCES `resume: true` (apra-fleet-02s.3) so any real work
361
+ * the member already performed for this request is preserved rather than redone -- but the
362
+ * re-ask is SELF-CONTAINED and does not depend on that resume carrying context
363
+ * (apra-fleet-dnri): it reattaches the original prompt plus the schema instruction as
364
+ * reference, alongside the ajv validation/parse errors and a corrected-JSON instruction.
365
+ * The reattached portion is identical on every repair round (the invalid output, the
366
+ * session transcript and per-attempt history are never embedded), so repairs do not grow.
336
367
  * Each attempt emits its own activity:start/activity:end pair and is cost-accounted
337
368
  * individually. (apra-fleet-unw.8)
338
369
  * @property {number} [busyWaitMs] - How long (ms) to keep waiting-and-retrying when the
@@ -424,6 +455,50 @@ export class FleetWorkflow extends EventEmitter {
424
455
  // controller.signal (via _currentSignal()) when the caller doesn't
425
456
  // pass its own opts.signal. See runWithContext()/requestStop() below.
426
457
  this._activeControllers = new Map();
458
+
459
+ // (apra-fleet-p2to.1) Cooperative pause/resume gate. This is the
460
+ // GENERIC engine primitive -- a soft, deferred barrier at every
461
+ // agent()/command() entry -- NOT a journaled interrupt(). See
462
+ // requestPause()/requestResume()/setPauseGuard() and _pauseGate()
463
+ // below for the full semantics. All state is instance-level (like
464
+ // requestStop()'s _activeControllers), so a single pause quiesces
465
+ // every run sharing this FleetWorkflow instance.
466
+ //
467
+ // _pauseRequested : a pause has been asked for but has not yet
468
+ // "taken effect" (still draining in-flight work
469
+ // and/or waiting on the pause guard).
470
+ // _paused : the pause has taken effect at a clean-state
471
+ // boundary -- zero in-flight activities and the
472
+ // guard (if any) permitted it. New agent()/
473
+ // command() calls block at the gate while true.
474
+ // _pauseGuard : optional predicate (set via setPauseGuard) that
475
+ // defers a requested pause until it returns truthy
476
+ // -- i.e. lets the workflow script declare where a
477
+ // clean-state boundary actually is. Null means
478
+ // "any zero-in-flight point is a boundary".
479
+ // _inFlight : count of agent()/command() dispatches that have
480
+ // passed the gate and not yet completed. 'paused'
481
+ // is only declared when this reaches zero.
482
+ // _pauseWaiters : { resolve, reject } for every call currently
483
+ // blocked at the gate. requestResume() resolves
484
+ // them (they re-check and proceed); requestStop()
485
+ // rejects them with a CancelledError so a paused
486
+ // run tears down instead of hanging.
487
+ // _preResumeHook : optional async hook (set via setPreResumeHook)
488
+ // that requestResume() awaits as a HARD BARRIER
489
+ // before it clears pause state, releases any gate
490
+ // waiter, or emits 'resumed' -- so a caller's
491
+ // re-reserve/resync completes strictly ahead of the
492
+ // first post-resume dispatch. A hook rejection
493
+ // rejects requestResume() (the run stays paused)
494
+ // rather than being swallowed. Null means no
495
+ // barrier -- resume proceeds immediately.
496
+ this._pauseRequested = false;
497
+ this._paused = false;
498
+ this._pauseGuard = null;
499
+ this._preResumeHook = null;
500
+ this._inFlight = 0;
501
+ this._pauseWaiters = [];
427
502
  }
428
503
 
429
504
  // Returns the active per-run store (see runStorage above), or
@@ -501,11 +576,240 @@ export class FleetWorkflow extends EventEmitter {
501
576
  * @param {string} [reason]
502
577
  */
503
578
  requestStop(reason = 'Workflow run cancelled via requestStop()') {
579
+ // (apra-fleet-p2to.1) A stop supersedes any pause: reject every call
580
+ // blocked at the pause gate with a CancelledError so a paused run
581
+ // unwinds instead of hanging forever, and clear the pause state so a
582
+ // late-arriving activity doesn't re-block. The gate promise rejecting
583
+ // is what makes "requestStop() while paused tears down" work -- the
584
+ // blocked agent()/command() re-throws the CancelledError, which
585
+ // unwinds the run exactly like an aborted in-flight dispatch does.
586
+ this._pauseRequested = false;
587
+ this._paused = false;
588
+ const waiters = this._pauseWaiters;
589
+ this._pauseWaiters = [];
590
+ for (const waiter of waiters) {
591
+ waiter.reject(new CancelledError(`[Workflow Error] ${reason}`));
592
+ }
504
593
  for (const controller of this._activeControllers.values()) {
505
594
  controller.abort(new CancelledError(`[Workflow Error] ${reason}`));
506
595
  }
507
596
  }
508
597
 
598
+ /**
599
+ * (apra-fleet-p2to.1) Registers (or clears, with `null`) the pause guard:
600
+ * a predicate consulted whenever a requested-but-not-yet-engaged pause is
601
+ * about to take effect. A pause only engages -- transitions to `_paused`
602
+ * and fires 'paused' -- when in-flight work has drained to zero AND this
603
+ * guard returns truthy. That lets a workflow script defer a mid-run pause
604
+ * to a boundary IT considers clean (e.g. "between phases", "not inside a
605
+ * transaction") rather than the mere between-activities gaps the engine
606
+ * can see on its own. A null guard (the default) treats every
607
+ * zero-in-flight point as an acceptable boundary. The guard is called with
608
+ * no arguments; a throwing guard is treated as "not at a boundary yet"
609
+ * (fail-closed: keep deferring rather than pause at a point the script
610
+ * couldn't vouch for) and logged.
611
+ *
612
+ * Generic engine hook only -- it carries no fleet-sprint (or any other
613
+ * caller's) semantics; the meaning of "clean" is entirely the guard's.
614
+ *
615
+ * @param {(() => boolean) | null} fn
616
+ */
617
+ setPauseGuard(fn) {
618
+ if (fn !== null && typeof fn !== 'function') {
619
+ throw new TypeError('[Workflow Error] setPauseGuard() requires a function or null');
620
+ }
621
+ this._pauseGuard = fn;
622
+ // Setting the guard at what the script now considers a clean boundary
623
+ // may be exactly the moment a deferred pause can finally engage.
624
+ this._maybeEngagePause();
625
+ }
626
+
627
+ /**
628
+ * (apra-fleet-p2to.1.3) Registers (or clears, with null) an async
629
+ * pre-resume hook that requestResume() awaits as a HARD BARRIER before it
630
+ * clears pause state, releases any gate waiter, or emits 'resumed'. This is
631
+ * the point at which a caller re-grabs/re-syncs whatever it released at
632
+ * pause (fleet-sprint's member re-reserve/resync) with the guarantee that
633
+ * the work completes strictly BEFORE the first post-resume agent()/
634
+ * command() dispatch -- no race with the resumed sprint loop.
635
+ *
636
+ * The hook is awaited; if it rejects, requestResume() rejects too and the
637
+ * run stays paused (pause state is never cleared on the reject path), so a
638
+ * failure surfaces to the caller instead of being silently swallowed --
639
+ * consistent with reReserveOnResume()'s rethrow contract.
640
+ *
641
+ * Generic engine hook only -- it carries no caller-specific semantics.
642
+ *
643
+ * @param {((reason: string) => (void | Promise<void>)) | null} fn
644
+ */
645
+ setPreResumeHook(fn) {
646
+ if (fn !== null && typeof fn !== 'function') {
647
+ throw new TypeError('[Workflow Error] setPreResumeHook() requires a function or null');
648
+ }
649
+ this._preResumeHook = fn;
650
+ }
651
+
652
+ /**
653
+ * (apra-fleet-p2to.1) Requests a cooperative pause of every run sharing
654
+ * this instance. Fires 'pause:requested' immediately, but the pause is
655
+ * DEFERRED: it only takes effect ('paused' fires, new dispatches block) at
656
+ * a clean-state boundary -- zero in-flight activities and, if a pause
657
+ * guard is set, that guard returning truthy. Calling it while already
658
+ * paused or pause-requested is a no-op.
659
+ *
660
+ * (apra-fleet-hzeb.3) Also exposed on the script context (see
661
+ * _bindPrimitives), so a running workflow script can initiate a pause
662
+ * for a condition only IT can detect (e.g. a provider usage/rate limit
663
+ * signal) -- not just the dashboard/operator via requestStop()'s sibling
664
+ * instance-level API. A script-initiated pause is indistinguishable from
665
+ * an operator-initiated one downstream: it fires the exact same
666
+ * 'pause:requested'/'paused'/'resumed' events, so any existing listener
667
+ * (the dashboard viewer's state.pause wiring, fleet-sprint's
668
+ * cli.mjs `on('paused', releaseForPause)` /
669
+ * `setPreResumeHook(reReserveForResume)`) engages for it unchanged.
670
+ *
671
+ * @param {string} [reason]
672
+ * @param {{ resumeAt?: string, source?: string }} [opts] - Optional
673
+ * metadata carried on the 'pause:requested' payload (apra-fleet-hzeb.3):
674
+ * `resumeAt` is an ISO-8601 timestamp (or any caller-defined string) the
675
+ * caller expects the condition to clear by -- e.g. a provider's
676
+ * usage-limit reset time -- surfaced by the dashboard viewer in the
677
+ * paused banner. `source` identifies what requested the pause (e.g.
678
+ * `'usage_limit'`) for the same display purpose. Both are purely
679
+ * informational to the engine, which does not interpret or act on
680
+ * them. Omitting `opts` is fully backwards compatible with existing
681
+ * single-arg callers.
682
+ */
683
+ requestPause(reason = 'Workflow run paused via requestPause()', opts = {}) {
684
+ if (this._paused || this._pauseRequested) return;
685
+ this._pauseRequested = true;
686
+ this.emit('pause:requested', this._pauseEventPayload({
687
+ reason,
688
+ resumeAt: opts.resumeAt ?? null,
689
+ source: opts.source ?? null
690
+ }));
691
+ // If we're already quiescent (nothing in flight, guard permits), the
692
+ // pause engages right now; otherwise it engages later as in-flight
693
+ // work drains (_exitActivity) or the guard opens (setPauseGuard).
694
+ this._maybeEngagePause();
695
+ }
696
+
697
+ /**
698
+ * (apra-fleet-p2to.1) Resumes a paused (or merely pause-requested) run.
699
+ * Clears the pause state and releases every call blocked at the gate so
700
+ * they proceed. Fires 'resumed'. No-op if not paused/pause-requested.
701
+ *
702
+ * (apra-fleet-p2to.1.3) When a pre-resume hook is registered (see
703
+ * setPreResumeHook), it is awaited as a HARD BARRIER FIRST -- while the run
704
+ * is still paused, so no gate waiter is released and no new dispatch slips
705
+ * through -- and only once it resolves are the waiters released and
706
+ * 'resumed' emitted. This guarantees the caller's re-reserve/resync
707
+ * completes strictly ahead of the first post-resume dispatch. A hook
708
+ * rejection propagates out of requestResume() with the pause state left
709
+ * intact (run stays paused), rather than being swallowed.
710
+ *
711
+ * @param {string} [reason]
712
+ * @returns {Promise<void>}
713
+ */
714
+ async requestResume(reason = 'Workflow run resumed via requestResume()') {
715
+ if (!this._paused && !this._pauseRequested) return;
716
+ // Barrier: drain the pre-resume hook BEFORE touching pause state. The
717
+ // run is still paused here, so waiters remain blocked and any fresh
718
+ // agent()/command() dispatch blocks at the gate -- the hook's work
719
+ // (e.g. member re-reserve/resync) cannot race the resumed loop. A
720
+ // rejection here surfaces to the caller with pause state untouched, so
721
+ // the run stays parked instead of resuming on a half-restored state.
722
+ if (this._preResumeHook) {
723
+ await this._preResumeHook(reason);
724
+ }
725
+ this._paused = false;
726
+ this._pauseRequested = false;
727
+ const waiters = this._pauseWaiters;
728
+ this._pauseWaiters = [];
729
+ for (const waiter of waiters) {
730
+ waiter.resolve();
731
+ }
732
+ this.emit('resumed', this._pauseEventPayload({ reason }));
733
+ }
734
+
735
+ // (apra-fleet-p2to.1) Phase/group (and runId) labels for pause lifecycle
736
+ // events, read from the active run store when there is one (falling back
737
+ // to the legacy instance-level fields), so subscribers can attribute a
738
+ // pause to where the run actually was -- exactly like log()/phase() do.
739
+ _pauseEventPayload(extra = {}) {
740
+ return {
741
+ phase: this._currentPhase(),
742
+ group: this._currentGroup(),
743
+ runId: this._currentRunId(),
744
+ ...extra
745
+ };
746
+ }
747
+
748
+ // (apra-fleet-p2to.1) True when a requested pause is allowed to take
749
+ // effect right now: null guard means "any zero-in-flight point is clean";
750
+ // otherwise the script's guard decides. A throwing guard fails closed
751
+ // (keep deferring) rather than pausing at an unvouched-for point.
752
+ _guardPermitsPause() {
753
+ if (!this._pauseGuard) return true;
754
+ try {
755
+ return !!this._pauseGuard();
756
+ } catch (err) {
757
+ console.error(`[Workflow] pause guard threw (deferring pause): ${err && err.message ? err.message : err}`);
758
+ return false;
759
+ }
760
+ }
761
+
762
+ // (apra-fleet-p2to.1) Engage a requested pause iff we're at a clean-state
763
+ // boundary: pause requested, not already paused, zero in-flight activities
764
+ // and the guard permits. Idempotent and cheap -- called from every point
765
+ // that can move us toward quiescence (requestPause, _exitActivity when the
766
+ // last activity drains, setPauseGuard opening the boundary, and the gate
767
+ // itself). This is the ONLY place 'paused' is emitted, which guarantees
768
+ // 'paused' can never fire while activities are still in flight.
769
+ _maybeEngagePause() {
770
+ if (!this._pauseRequested || this._paused) return;
771
+ if (this._inFlight > 0) return;
772
+ if (!this._guardPermitsPause()) return;
773
+ this._paused = true;
774
+ this.emit('paused', this._pauseEventPayload());
775
+ }
776
+
777
+ // (apra-fleet-p2to.1) The pause gate, awaited at the very start of every
778
+ // agent()/command() call (before it becomes in-flight). If a pause is
779
+ // engaged the call blocks here until requestResume() releases it (the
780
+ // awaited promise resolves) or requestStop() tears it down (the promise
781
+ // rejects with a CancelledError, which propagates out of agent()/command()
782
+ // and unwinds the run). A requested-but-not-yet-engaged pause is given a
783
+ // chance to engage first (this arrival at a gate is itself a between-
784
+ // activities boundary), so a pause requested while the run is idle takes
785
+ // effect on the next dispatch rather than slipping one through.
786
+ async _pauseGate() {
787
+ this._maybeEngagePause();
788
+ while (this._paused) {
789
+ await new Promise((resolve, reject) => {
790
+ this._pauseWaiters.push({ resolve, reject });
791
+ });
792
+ // Released by requestResume(); re-check in case another pause was
793
+ // requested in the meantime before we fall through to dispatch.
794
+ this._maybeEngagePause();
795
+ }
796
+ }
797
+
798
+ // (apra-fleet-p2to.1) In-flight bookkeeping bracketing the actual dispatch
799
+ // in agent()/command(). A call is "in flight" from the moment it clears
800
+ // the gate until it fully settles; 'paused' is withheld until this count
801
+ // returns to zero (see _maybeEngagePause), which is what "paused only at
802
+ // zero in-flight activities" means.
803
+ _enterActivity() {
804
+ this._inFlight += 1;
805
+ }
806
+
807
+ _exitActivity() {
808
+ this._inFlight = Math.max(0, this._inFlight - 1);
809
+ // Draining the last in-flight activity may complete a deferred pause.
810
+ this._maybeEngagePause();
811
+ }
812
+
509
813
  log(msg) {
510
814
  console.log(`${this.logPrefix}[Workflow Log] ${msg}`);
511
815
  this.emit('log', { phase: this._currentPhase(), msg, runId: this._currentRunId() });
@@ -628,11 +932,25 @@ export class FleetWorkflow extends EventEmitter {
628
932
  * @param {string} prompt
629
933
  * @param {AgentOptions} [opts]
630
934
  */
935
+ // (apra-fleet-p2to.1) Public entry: passes through the cooperative pause
936
+ // gate, then brackets the real dispatch with in-flight bookkeeping so a
937
+ // pause only declares 'paused' once every such dispatch has settled. The
938
+ // try/finally guarantees the in-flight count is balanced on every exit
939
+ // path (success, throw, or a gate-rejecting requestStop()).
631
940
  async agent(prompt, opts = {}) {
632
941
  if (!opts.member_name && !opts.member_id) {
633
942
  throw new Error(`[Workflow Error] agent() requires either member_name or member_id`);
634
943
  }
944
+ await this._pauseGate();
945
+ this._enterActivity();
946
+ try {
947
+ return await this._agentDispatch(prompt, opts);
948
+ } finally {
949
+ this._exitActivity();
950
+ }
951
+ }
635
952
 
953
+ async _agentDispatch(prompt, opts = {}) {
636
954
  const effectivePhase = opts.phase || this._currentPhase();
637
955
  const runId = this._currentRunId();
638
956
  if (effectivePhase) {
@@ -669,6 +987,14 @@ export class FleetWorkflow extends EventEmitter {
669
987
 
670
988
  let currentPrompt = initialPrompt;
671
989
  let lastActivityMeta = null;
990
+ // apra-fleet-dnri: the session id reported by the attempt that just
991
+ // failed, used as an EXPLICIT resume target by the repair dispatch of
992
+ // the NEXT iteration (see the resume disposition comment on the
993
+ // payload below). Declared outside the loop because the capture site
994
+ // sits after the payload is built within the same iteration. It is
995
+ // re-assigned (or cleared) on every turn, so a repair round never
996
+ // reuses an older round's id.
997
+ let failedAttemptSessionId = null;
672
998
  const budget = this._currentBudget();
673
999
 
674
1000
  // (apra-fleet-unw.11, F6) Journal replay. `replayKey` is computed
@@ -785,6 +1111,47 @@ export class FleetWorkflow extends EventEmitter {
785
1111
  lastActivityMeta = activityMeta;
786
1112
  this.emit('activity:start', activityMeta);
787
1113
 
1114
+ // apra-fleet-dnri -- RESUME DISPOSITION for a schema-repair
1115
+ // re-ask, corrected after a live reproduction:
1116
+ //
1117
+ // A repair dispatch SHOULD continue the session that produced the
1118
+ // invalid output -- by repair time the member may already have
1119
+ // done real, side-effecting work for this request (files edited,
1120
+ // commits made, tracker items claimed), and a fresh session with
1121
+ // the task restated invites it to redo that work. But the naive
1122
+ // way of asking for that -- a bare boolean `true` -- does NOT
1123
+ // mean "the session that just failed". execute_prompt resolves
1124
+ // `resume: true` to `explicitResumeId ?? agent.sessionId`, i.e.
1125
+ // the member's single globally-stored LAST session, shared across
1126
+ // every role with no task scoping. Observed live: a doer's repair
1127
+ // retry landed in the immediately-prior plan-reviewer session and
1128
+ // came back with reviewer-shaped output carrying a field that is
1129
+ // not in the doer schema at all.
1130
+ //
1131
+ // So the repair dispatch names the session EXPLICITLY, by id
1132
+ // (execute_prompt's resume accepts a session-id string for
1133
+ // exactly this). When no id was reported for the failed attempt
1134
+ // (a provider without resume support, or a dispatch that returned
1135
+ // none), we degrade LOUDLY to a fresh, self-contained session and
1136
+ // pass the boolean `false` EXPLICITLY -- never `undefined`, since
1137
+ // execute_prompt's schema declares `.default(true)` on this field
1138
+ // and an omitted key would silently restore the exact
1139
+ // wrong-session bug above.
1140
+ //
1141
+ // Correctness does not depend on the resume landing: the repair
1142
+ // prompt reattaches the original prompt and schema itself (see
1143
+ // buildRepairPrompt), so the re-ask works whether or not the
1144
+ // resumed session still carries the original context.
1145
+ let repairResume = false;
1146
+ if (isRepair) {
1147
+ if (typeof failedAttemptSessionId === 'string' && failedAttemptSessionId) {
1148
+ repairResume = failedAttemptSessionId;
1149
+ } else {
1150
+ console.error(`[Agent Schema Repair] DEGRADED: no session id was reported for the attempt that just failed on member '${opts.member_name || opts.member_id}', so this repair re-ask CANNOT target that session and is being dispatched in a FRESH session (resume: false). Any side-effecting work the member already did for this request is not visible to it; the repair prompt is self-contained, so the re-ask is still answerable.`);
1151
+ repairResume = false;
1152
+ }
1153
+ }
1154
+
788
1155
  const payload = {
789
1156
  prompt: currentPrompt,
790
1157
  model: opts.model,
@@ -800,15 +1167,10 @@ export class FleetWorkflow extends EventEmitter {
800
1167
  sprint_id: opts.sprint_id,
801
1168
  // F10: default to a self-contained (non-resumed) session for
802
1169
  // the INITIAL dispatch of a workflow-authored prompt. See
803
- // AgentOptions.resume above and apra-fleet-unw.3.
804
- // apra-fleet-02s.3: a schema-repair re-ask (isRepair===true)
805
- // is a different case -- it now FORCES resume:true,
806
- // regardless of opts.resume, so the member's session already
807
- // has the original prompt/schema and its own invalid output
808
- // in context; buildRepairPrompt() was shrunk accordingly to a
809
- // lean reminder (validation errors only), since re-sending
810
- // that context fresh every repair round would waste tokens.
811
- resume: isRepair ? true : (opts.resume ?? false),
1170
+ // AgentOptions.resume above and apra-fleet-unw.3. The
1171
+ // non-repair value is unchanged; the repair value is resolved
1172
+ // above (apra-fleet-dnri).
1173
+ resume: isRepair ? repairResume : (opts.resume ?? false),
812
1174
  // apra-fleet-unw.5: opts pass-through only, no control-flow change here.
813
1175
  timeoutMs: opts.timeoutMs,
814
1176
  // apra-fleet-unw.10: defaults to the active run's cooperative
@@ -842,6 +1204,31 @@ export class FleetWorkflow extends EventEmitter {
842
1204
  }
843
1205
  }
844
1206
 
1207
+ // apra-fleet-dnri: naming the failed attempt's session id
1208
+ // explicitly (above) converts one previously self-healing
1209
+ // case into a hard failure. execute_prompt rejects an
1210
+ // unknown/expired EXPLICIT id up front with
1211
+ // {isError, reason: 'session_not_found'}, making no LLM call,
1212
+ // and its transparent retry-in-a-fresh-session recovery is
1213
+ // gated on `resume === true`, so it does not apply here. Left
1214
+ // alone, the dispatch-error branch below would turn that into
1215
+ // an AgentDispatchError and abort the whole step -- worse
1216
+ // than the boolean behaviour this replaced.
1217
+ // Scope is deliberately narrow: for REPAIR dispatches only,
1218
+ // for that ONE reason, re-dispatch exactly once with the SAME
1219
+ // repair prompt in a fresh self-contained session, inside the
1220
+ // existing maxRepairs budget. No new retry framework, no new
1221
+ // budget, no broader error taxonomy.
1222
+ if (
1223
+ isRepair
1224
+ && result && result.structuredContent && result.structuredContent.isError
1225
+ && result.structuredContent.reason === 'session_not_found'
1226
+ ) {
1227
+ console.error(`[Agent Schema Repair] the session targeted by this repair re-ask (${payload.resume}) is gone or expired on member '${opts.member_name || opts.member_id}'; re-dispatching the same repair prompt once in a fresh self-contained session (resume: false).`);
1228
+ payload.resume = false;
1229
+ result = await this.fleetApi.executePrompt(payload);
1230
+ }
1231
+
845
1232
  // execute_prompt's dispatch-level structuredContent (added
846
1233
  // alongside the display text -- see src/tools/execute-prompt.ts)
847
1234
  // reports real per-call token usage AND classifies dispatch
@@ -895,7 +1282,15 @@ export class FleetWorkflow extends EventEmitter {
895
1282
  // result.usage is null and cost is null -- the viewer then
896
1283
  // tallies it as an unknown-cost activity rather than fiction.
897
1284
  this.emit('activity:end', { ...activityMeta, error: text, duration, usage: result.usage, cost, success: false });
898
- throw new AgentDispatchError(`[Workflow Error] Agent dispatch failed (${structured.reason || 'unknown'}): ${text}`, { details: { text, reason: structured.reason, member: opts.member_name || opts.member_id } });
1285
+ // apra-fleet-hzeb.2: pure pass-through, no policy decisions here --
1286
+ // when execute_prompt relayed a provider usage-limit signal
1287
+ // (reason: 'usage_limit'), forward its usageLimit block and the
1288
+ // in-flight sessionId onto AgentDispatchError.details unchanged, so
1289
+ // the fleet-sprint pause/resume policy can read
1290
+ // err.details.usageLimit.resumeAt / err.details.sessionId directly
1291
+ // instead of re-parsing the failure text. A permission_denied
1292
+ // result forwards its permissionDenied block the same way.
1293
+ throw new AgentDispatchError(`[Workflow Error] Agent dispatch failed (${structured.reason || 'unknown'}): ${text}`, { details: { text, reason: structured.reason, member: opts.member_name || opts.member_id, ...(structured.usageLimit ? { usageLimit: structured.usageLimit } : {}), ...(structured.permissionDenied ? { permissionDenied: structured.permissionDenied } : {}), ...(structured.sessionId ? { sessionId: structured.sessionId } : {}) } });
899
1294
  }
900
1295
 
901
1296
  // apra-fleet-eft.78.3: surface the resumable session id
@@ -911,6 +1306,21 @@ export class FleetWorkflow extends EventEmitter {
911
1306
  // engine falls back to a fresh session (a capability signal, not
912
1307
  // a provider-name check). Best-effort: a throwing callback must
913
1308
  // never break the dispatch.
1309
+ // apra-fleet-dnri: record THIS attempt's session id so that,
1310
+ // if its output turns out to be schema-invalid, the repair
1311
+ // dispatch of the next iteration can resume exactly this
1312
+ // session by id rather than whatever session the member
1313
+ // happens to have stored last. Assigned unconditionally (to
1314
+ // null when the provider reported none) so a later round can
1315
+ // never silently reuse an earlier round's id -- a provider may
1316
+ // mint a new id per turn. Deliberately NOT nested inside the
1317
+ // opts.onSessionId gate below: most callers pass no callback,
1318
+ // and gating the capture on it would mean the explicit-id
1319
+ // path never runs for them.
1320
+ failedAttemptSessionId = (structured && typeof structured.sessionId === 'string' && structured.sessionId)
1321
+ ? structured.sessionId
1322
+ : null;
1323
+
914
1324
  if (
915
1325
  structured
916
1326
  && typeof structured.sessionId === 'string'
@@ -996,8 +1406,9 @@ export class FleetWorkflow extends EventEmitter {
996
1406
 
997
1407
  if (attempt < maxRepairs) {
998
1408
  // Bounded repair: re-dispatch to the SAME member with
999
- // a fresh, self-contained prompt (original prompt +
1000
- // invalid output + ajv errors). This attempt is still
1409
+ // a self-contained prompt (ajv errors + the original
1410
+ // prompt/schema reattached as reference, but NOT the
1411
+ // invalid output). This attempt is still
1001
1412
  // recorded as its own activity:end (success: false)
1002
1413
  // so the journal/dashboard show it as a distinct step
1003
1414
  // before the repair attempt that follows.
@@ -1015,7 +1426,11 @@ export class FleetWorkflow extends EventEmitter {
1015
1426
  // dashboard's structured activity data.
1016
1427
  console.error(`[Agent API Error]`, repairMsg);
1017
1428
  this.emit('activity:end', { ...activityMeta, error: repairMsg, output: text, duration, usage: result.usage, cost, success: false });
1018
- currentPrompt = buildRepairPrompt(errorsText);
1429
+ // apra-fleet-dnri: always re-derive from
1430
+ // `initialPrompt`, never from `currentPrompt` --
1431
+ // otherwise repair round 2 would nest round 1's
1432
+ // prompt and the re-ask would grow per attempt.
1433
+ currentPrompt = buildRepairPrompt(errorsText, initialPrompt);
1019
1434
  continue;
1020
1435
  }
1021
1436
 
@@ -1087,7 +1502,23 @@ export class FleetWorkflow extends EventEmitter {
1087
1502
  * @param {string} cmd
1088
1503
  * @param {CommandOptions} [opts]
1089
1504
  */
1505
+ // (apra-fleet-p2to.1) Public entry: same pause-gate + in-flight bracketing
1506
+ // as agent() above. The member-argument guard runs before the gate so a
1507
+ // malformed call fails fast rather than blocking on a pause.
1090
1508
  async command(cmd, opts = {}) {
1509
+ if (!opts.member_name && !opts.member_id) {
1510
+ throw new Error(`[Workflow Error] command() requires either member_name or member_id`);
1511
+ }
1512
+ await this._pauseGate();
1513
+ this._enterActivity();
1514
+ try {
1515
+ return await this._commandDispatch(cmd, opts);
1516
+ } finally {
1517
+ this._exitActivity();
1518
+ }
1519
+ }
1520
+
1521
+ async _commandDispatch(cmd, opts = {}) {
1091
1522
  // (apra-fleet-unw.17, A4) `opts.failSoft`: when set, a command
1092
1523
  // failure that would otherwise throw (a well-formed `isError`
1093
1524
  // result -> CommandError, a "Member not found" text sniff ->
@@ -1110,9 +1541,9 @@ export class FleetWorkflow extends EventEmitter {
1110
1541
  if (!failSoft) throw err;
1111
1542
  return { ok: false, output: '', error: err.message };
1112
1543
  };
1113
- if (!opts.member_name && !opts.member_id) {
1114
- throw new Error(`[Workflow Error] command() requires either member_name or member_id`);
1115
- }
1544
+ // (apra-fleet-p2to.2.3) The member-argument guard lives solely in the
1545
+ // public command() entrypoint above; _commandDispatch() is only ever
1546
+ // reached through it, so a second copy here was dead code. Removed.
1116
1547
 
1117
1548
  const effectivePhase = opts.phase || this._currentPhase();
1118
1549
  const runId = this._currentRunId();
@@ -1587,7 +2018,22 @@ export class FleetWorkflow extends EventEmitter {
1587
2018
  publishState: this.publishState.bind(this),
1588
2019
  workflow: this.workflow.bind(this),
1589
2020
  group: this.group.bind(this),
1590
- endGroup: this.endGroup.bind(this)
2021
+ endGroup: this.endGroup.bind(this),
2022
+ // (apra-fleet-p2to.1) Script-facing: lets the workflow declare
2023
+ // where a clean-state boundary is so a deferred pause engages
2024
+ // there.
2025
+ setPauseGuard: this.setPauseGuard.bind(this),
2026
+ // (apra-fleet-hzeb.3) Script-facing pause/resume: a running
2027
+ // script may PARK ITSELF on a condition only it can detect (a
2028
+ // provider usage/rate limit, an external gate) by calling these
2029
+ // directly -- they are the exact same requestPause()/
2030
+ // requestResume() the dashboard/operator use, so a
2031
+ // script-initiated pause fires the identical 'pause:requested'/
2032
+ // 'paused'/'resumed' lifecycle events as an operator-initiated
2033
+ // one. requestStop() remains instance-only/operator-only -- a
2034
+ // script has no business tearing down its own run.
2035
+ requestPause: this.requestPause.bind(this),
2036
+ requestResume: this.requestResume.bind(this)
1591
2037
  };
1592
2038
  }
1593
2039