@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
@@ -0,0 +1,495 @@
1
+ // =============================================================================
2
+ // GIT TOPOLOGY -- the fleet's git-side preconditions and primitives
3
+ // (apra-fleet-3swo.6.3)
4
+ // =============================================================================
5
+ //
6
+ // Moved VERBATIM out of runner.js. This module owns the three layers the
7
+ // orchestrator's git sync sits ON TOP of, none of which are sync brackets
8
+ // themselves:
9
+ //
10
+ // 1. checkMemberTopology() -- the multi-member topology precondition
11
+ // bin/cli.mjs runs BEFORE a sprint starts. Nothing here has run yet when
12
+ // it is called; it decides whether a sprint may start at all.
13
+ // 2. classifyGitFailure() / runGitStep() / resolveGitProviderForClassification()
14
+ // -- the ONE git-failure classifier (a thin adapter over
15
+ // VCSModule.classifyFailure()), the single retrying git-command primitive
16
+ // every bracket issues its commands through, and the fail-closed provider
17
+ // lookup that threads a member's own VCS provider into the classifier.
18
+ // 3. commandResultToSoftGit() -- the exit-code-based `execute_command` ->
19
+ // soft-git-result adapter the resume-path resync consumes.
20
+ //
21
+ // WHAT DELIBERATELY STAYED IN runner.js: the sync BRACKETS themselves
22
+ // (syncMemberBefore / syncMemberAfter / syncMemberAfterOrdered /
23
+ // resyncReacquiredMember). They are this layer's callers, not part of it, and
24
+ // they import runGitStep/resolveGitProviderForClassification from here.
25
+ //
26
+ // resolveGitProviderForClassification is exported ONLY because the brackets
27
+ // that still live in runner.js call it. It was module-private before the move
28
+ // and is NOT re-exported by runner.js's facade -- it stays reachable only
29
+ // through this module.
30
+ //
31
+ // Dependency-injection stance is unchanged: nothing here does I/O of its own.
32
+ // Every git command is issued via an injected command() with an explicit
33
+ // `member_name`, and every probe (getIdentity/getOriginUrl/doltProbe) is
34
+ // supplied by the caller, so unit tests drive all of it with no live fleet.
35
+ // =============================================================================
36
+
37
+ // classifyGitFailure() delegates to VCSModule -- the ONE place VCS stderr is
38
+ // parsed (vcs-module.mjs's own header comment). These two names were imported
39
+ // by runner.js for exactly this call before the move.
40
+ import { classifyFailure, toGitVerdict } from './vcs-module.mjs';
41
+ import { VCS_FAILURE_KINDS } from './errors.mjs';
42
+
43
+ // ---------------------------------------------------------------------------
44
+ // Multi-member topology precondition
45
+ // ---------------------------------------------------------------------------
46
+ //
47
+ // A sprint stands up under one of two topology contracts, and this function is
48
+ // the gate that refuses to start when the fleet does not satisfy the one the
49
+ // caller named. Mode selection is EXPLICIT (`opts.mode`), never inferred: an
50
+ // unknown mode is a hard refusal, not a silent fallback.
51
+ //
52
+ // LEGACY (shared-workspace): there is no cross-member sync layer, so every
53
+ // member must resolve to the same checkout/DB. The orchestrator's `bd`
54
+ // commands run against ITS member's beads DB while each doer's `bd close`
55
+ // runs against its own, and the sprint git branch is only meaningful if all
56
+ // members share working state. Enforced by comparing an identity signal
57
+ // (cli.mjs wires it to `git rev-parse HEAD`) across members. Matching HEADs
58
+ // at start is a best-effort heuristic, not a guarantee of ongoing shared
59
+ // state: two independent checkouts sitting on the same commit would pass.
60
+ //
61
+ // SYNCED: the orchestrator-bracketed G-pull/G-push layer reconciles members by
62
+ // fast-forward pull/push, so differing HEADs between brackets are EXPECTED and
63
+ // a shared workspace is not required. The precondition instead becomes: every
64
+ // member reports the SAME `git remote get-url origin` (they push/pull the same
65
+ // remote branch) AND passes a `bd dolt pull` probe (their beads DB can sync).
66
+ //
67
+ // Inject-driven, with no direct I/O of its own, so cli.mjs can wire the probes
68
+ // to live fleet commands while tests supply per-member signals directly. A
69
+ // single member trivially passes. For 2+ members, a member whose signal cannot
70
+ // be obtained is a REFUSAL: shared state cannot be proven, so the sprint must
71
+ // not silently continue.
72
+ /**
73
+ * @param {{
74
+ * members: string[],
75
+ * getIdentity?: (member: string) => Promise<string>,
76
+ * mode?: 'legacy'|'synced',
77
+ * getOriginUrl?: (member: string) => Promise<string>,
78
+ * doltProbe?: (member: string) => Promise<unknown>,
79
+ * }} opts
80
+ * @returns {Promise<{ ok: boolean, singleMember: boolean, mode: string, identities?: Array<object>, probes?: Array<object>, message: string }>}
81
+ */
82
+ export async function checkMemberTopology({ members, getIdentity, mode = 'legacy', getOriginUrl, doltProbe }) {
83
+ if (!Array.isArray(members) || members.length === 0) {
84
+ return { ok: false, singleMember: false, mode, identities: [], message: '[Topology] Refusing to start: no members configured.' };
85
+ }
86
+
87
+ if (mode !== 'legacy' && mode !== 'synced') {
88
+ return {
89
+ ok: false,
90
+ singleMember: members.length === 1,
91
+ mode,
92
+ message: `[Topology] Refusing to start: unknown topology mode '${mode}'. Mode must be selected explicitly as 'legacy' (shared-workspace, same-HEAD) or 'synced' (orchestrator-bracketed git sync, same-origin + dolt probe).`,
93
+ };
94
+ }
95
+
96
+ if (members.length === 1) {
97
+ return {
98
+ ok: true,
99
+ singleMember: true,
100
+ mode,
101
+ identities: [{ member: members[0], signal: null, error: null }],
102
+ message: `[Topology] Single-member ${mode} sprint ('${members[0]}') -- shared-state precondition trivially satisfied (nothing to compare).`,
103
+ };
104
+ }
105
+
106
+ // -----------------------------------------------------------------------
107
+ // SYNCED mode: same-origin + dolt-probe precondition. HEADs are ALLOWED to
108
+ // differ -- reconciliation is the sync layer's job.
109
+ // -----------------------------------------------------------------------
110
+ if (mode === 'synced') {
111
+ if (typeof getOriginUrl !== 'function' || typeof doltProbe !== 'function') {
112
+ return {
113
+ ok: false,
114
+ singleMember: false,
115
+ mode,
116
+ message: '[Topology] Refusing to start the synced-mode sprint: getOriginUrl and doltProbe must both be provided so the same-origin and dolt-pull preconditions can be checked.',
117
+ };
118
+ }
119
+
120
+ const probes = [];
121
+ for (const member of members) {
122
+ let originUrl = null;
123
+ let originError = null;
124
+ let doltOk = false;
125
+ let doltError = null;
126
+ try {
127
+ const raw = await getOriginUrl(member);
128
+ const url = (typeof raw === 'string' ? raw : String(raw)).trim();
129
+ if (url) originUrl = url; else originError = 'empty origin URL';
130
+ } catch (err) {
131
+ originError = (err && err.message) ? err.message : String(err);
132
+ }
133
+ try {
134
+ await doltProbe(member);
135
+ doltOk = true;
136
+ } catch (err) {
137
+ doltError = (err && err.message) ? err.message : String(err);
138
+ }
139
+ probes.push({ member, originUrl, originError, doltOk, doltError });
140
+ }
141
+
142
+ // A member that failed EITHER precondition (origin URL unavailable, or
143
+ // a failing dolt probe) is rejected, naming the member and which
144
+ // precondition failed.
145
+ const failedPrecondition = probes.filter((p) => p.originError !== null || !p.doltOk);
146
+ if (failedPrecondition.length > 0) {
147
+ const detail = failedPrecondition.map((p) => {
148
+ const reasons = [];
149
+ if (p.originError !== null) reasons.push(`origin URL unavailable (${p.originError})`);
150
+ // "dolt pull probe" (not "bd dolt pull") deliberately -- this is
151
+ // prose describing what doltProbe() checks, not a literal
152
+ // command; keeping the exact 'bd dolt pull'/'bd dolt push' tokens
153
+ // out of message text keeps this file clean for the
154
+ // dolt-literal-guard.mjs mechanical scan (apra-fleet-417.2.3),
155
+ // which flags any such literal outside a comment/import as a
156
+ // reintroduced direct dolt command.
157
+ if (!p.doltOk) reasons.push(`dolt pull probe failed (${p.doltError})`);
158
+ return `${p.member}: ${reasons.join('; ')}`;
159
+ }).join(', ');
160
+ return {
161
+ ok: false,
162
+ singleMember: false,
163
+ mode,
164
+ probes,
165
+ message:
166
+ '[Topology] Refusing to start the synced-mode sprint: one or more members failed a sync precondition -- ' +
167
+ detail +
168
+ '. In synced mode every member must report the same origin URL AND pass a dolt-pull sync probe. ' +
169
+ 'See docs/architecture.md "Multi-member topology (fleet-sprint)".',
170
+ };
171
+ }
172
+
173
+ // All members pass the dolt probe -- now they must share ONE origin.
174
+ const distinctOrigins = [...new Set(probes.map((p) => p.originUrl))];
175
+ if (distinctOrigins.length > 1) {
176
+ return {
177
+ ok: false,
178
+ singleMember: false,
179
+ mode,
180
+ probes,
181
+ message:
182
+ '[Topology] Refusing to start the synced-mode sprint: the configured members report DIVERGENT origin URLs, so ' +
183
+ 'they do not push/pull the same remote branch and the git sync layer cannot reconcile them. Per-member origins: ' +
184
+ probes.map((p) => `${p.member}=${p.originUrl}`).join(', ') +
185
+ '. Every member must report the same `git remote get-url origin`. ' +
186
+ 'See docs/architecture.md "Multi-member topology (fleet-sprint)".',
187
+ };
188
+ }
189
+
190
+ return {
191
+ ok: true,
192
+ singleMember: false,
193
+ mode,
194
+ probes,
195
+ message: `[Topology] Synced mode: all ${members.length} configured members share origin '${distinctOrigins[0]}' and passed the dolt-pull probe -- differing HEADs are reconciled by the git sync layer.`,
196
+ };
197
+ }
198
+
199
+ // -----------------------------------------------------------------------
200
+ // LEGACY mode: shared-workspace same-HEAD identity check.
201
+ // -----------------------------------------------------------------------
202
+ if (typeof getIdentity !== 'function') {
203
+ return {
204
+ ok: false,
205
+ singleMember: false,
206
+ mode,
207
+ message: '[Topology] Refusing to start the legacy-mode sprint: getIdentity must be provided so the same-HEAD precondition can be checked.',
208
+ };
209
+ }
210
+
211
+ const identities = [];
212
+ for (const member of members) {
213
+ try {
214
+ const raw = await getIdentity(member);
215
+ const signal = (typeof raw === 'string' ? raw : String(raw)).trim();
216
+ identities.push({ member, signal: signal || null, error: signal ? null : 'empty identity signal' });
217
+ } catch (err) {
218
+ identities.push({ member, signal: null, error: (err && err.message) ? err.message : String(err) });
219
+ }
220
+ }
221
+
222
+ const unresolved = identities.filter((i) => i.error !== null);
223
+ if (unresolved.length > 0) {
224
+ return {
225
+ ok: false,
226
+ singleMember: false,
227
+ mode,
228
+ identities,
229
+ message:
230
+ '[Topology] Refusing to start the multi-member sprint: could not obtain an identity signal from every ' +
231
+ 'configured member, so a shared-workspace setup cannot be verified. Per-member results: ' +
232
+ identities.map((i) => `${i.member}=${i.error ? `ERROR(${i.error})` : i.signal}`).join(', ') +
233
+ '. The only supported multi-member mode is a verified shared workspace (all members resolve to the same ' +
234
+ 'checkout/DB); otherwise run single-member. See docs/architecture.md "Multi-member topology (fleet-sprint)".',
235
+ };
236
+ }
237
+
238
+ const distinct = [...new Set(identities.map((i) => i.signal))];
239
+ if (distinct.length > 1) {
240
+ return {
241
+ ok: false,
242
+ singleMember: false,
243
+ mode,
244
+ identities,
245
+ message:
246
+ '[Topology] Refusing to start the multi-member sprint in legacy mode: the configured members disagree on ' +
247
+ 'their identity signals (are on differing HEADs). Re-run with --sync to enable cross-member sync mode, which ' +
248
+ 'tolerates differing HEADs and uses orchestrator-bracketed git sync to reconcile them. Per-member signals: ' +
249
+ identities.map((i) => `${i.member}=${i.signal}`).join(', ') +
250
+ '. See docs/architecture.md "Multi-member topology (fleet-sprint)" for details.',
251
+ };
252
+ }
253
+
254
+ return {
255
+ ok: true,
256
+ singleMember: false,
257
+ mode,
258
+ identities,
259
+ message: `[Topology] All ${members.length} configured members share the same identity signal (${distinct[0]}) -- shared-state precondition satisfied.`,
260
+ };
261
+ }
262
+
263
+ // apra-fleet-647.1.3.2: the git stderr/stdout pattern lists that used to live
264
+ // here (GIT_DIVERGED_PATTERNS, GIT_AUTH_PATTERNS, GIT_TRANSIENT_PATTERNS) are
265
+ // GONE -- classifyGitFailure() below delegates to VCSModule.classifyFailure(),
266
+ // the ONE place VCS stderr is parsed (vcs-module.mjs's own header comment).
267
+ // The default 'github' provider chain (GitHubVCS -> GenericGitVCS, see
268
+ // ./vcs-providers/github.mjs and ./generic-git.mjs) reproduces every pattern
269
+ // that lived in the three deleted lists verbatim -- built for exactly this
270
+ // migration in apra-fleet-647.1.3.1 -- so this is a delegation, not a
271
+ // behavior change.
272
+
273
+ /**
274
+ * Classify a failed git command's output into the failure classes the sync
275
+ * brackets route differently. Thin adapter over VCSModule.classifyFailure()
276
+ * + toGitVerdict(), mapping the neutral kind taxonomy onto this module's
277
+ * legacy verdict vocabulary with NO verdict change from the deleted
278
+ * pattern-list classifier.
279
+ *
280
+ * apra-fleet-417.7: `provider` is optional and, when supplied, selects the
281
+ * member's own resolved VCS provider chain (e.g. 'azure-devops',
282
+ * 'bitbucket') instead of the default 'github' chain -- this is what makes
283
+ * azure-devops.mjs's TF401019 and bitbucket.mjs's app-password rules
284
+ * reachable at runtime; they are NOT inherited by the default chain (see
285
+ * vcs-nongithub-auth-selfheal.test.mjs). Omitting it (every call site that
286
+ * cannot resolve a provider) reproduces the prior provider-agnostic default
287
+ * exactly -- NO verdict change for GitHub members or any caller that does
288
+ * not pass one.
289
+ *
290
+ * @param {string} output - the raw git stderr/stdout of the failed command
291
+ * @param {string} [provider] - the member's resolved VCS provider; falls back
292
+ * to VCSModule's default ('github') chain when omitted/falsy.
293
+ * @returns {'diverged'|'auth'|'transient'|'unknown'}
294
+ */
295
+ export function classifyGitFailure(output, provider) {
296
+ return toGitVerdict(classifyFailure(output, provider ? { provider } : undefined).kind);
297
+ }
298
+
299
+ /**
300
+ * Run a single git command via the injected command() with failSoft, retrying
301
+ * ONLY transient failures up to `maxTransientRetries` times. A diverged (or
302
+ * unknown) failure is returned immediately, never retried.
303
+ *
304
+ * An optional injected `onAuthFailure` async callback adds a DISTINCT, bounded
305
+ * one-shot self-heal path, deliberately NOT folded into the
306
+ * `maxTransientRetries` loop. When a command fails with an 'auth'
307
+ * classification (see classifyGitFailure) and `onAuthFailure` is provided, it
308
+ * is called EXACTLY ONCE (never in a loop, even if the retry fails with 'auth'
309
+ * again); if it resolves without throwing, the SAME command is retried exactly
310
+ * once more. If `onAuthFailure` throws, or is omitted, the failed result is
311
+ * returned as-is for the caller to turn into its typed
312
+ * GitSyncError/GitDivergedError.
313
+ *
314
+ * apra-fleet-647.1.3.3: an 'unknown' classification (any provider auth/failure
315
+ * text classifyGitFailure could not otherwise recognize) gets the SAME bounded
316
+ * one-shot self-heal + single retry as 'auth', rather than failing immediately
317
+ * -- an unrecognized provider auth string is far more likely to be a stale
318
+ * credential than a genuinely fatal condition, and one bounded self-heal
319
+ * attempt is cheap. This shares the single `authHealAttempted` latch with the
320
+ * 'auth' path, so the self-heal still fires AT MOST ONCE per runGitStep call
321
+ * regardless of whether it was triggered by 'auth' or 'unknown'. A 'diverged'
322
+ * classification is excluded from this and is still returned immediately,
323
+ * never retried -- see the module header's SINGLE-WRITER TOKEN PASSING stance.
324
+ *
325
+ * apra-fleet-417.7: an optional `provider` (the member's own resolved VCS
326
+ * provider, e.g. from VCSModule.resolveProvider()) is threaded straight into
327
+ * classifyGitFailure() so a vendor-specific AUTH rule (azure-devops.mjs's
328
+ * TF401019, bitbucket.mjs's app-password literal) is reachable here, not just
329
+ * from a caller that names the provider directly against classifyFailure().
330
+ * Omitting it (unresolvable/absent provider) falls back to today's default
331
+ * 'github' chain -- no throw, no new failure mode, no verdict change for
332
+ * GitHub members.
333
+ *
334
+ * PERMISSION-SCOPE REFUSALS ARE NEVER SELF-HEALED AND NEVER RETRIED (the
335
+ * AUTH_DENIED/AUTH_EXPIRED split at the self-heal gate). classifyFailure()
336
+ * reports `permissionScope: true` when a provider's own permission-scope rule
337
+ * matched -- the identity was understood and the PRINCIPAL was never granted
338
+ * the permission (GitHub's workflow-file refusal is the motivating case; see
339
+ * vcs-providers/github.mjs). provision_vcs_auth re-mints a credential for the
340
+ * SAME principal with the SAME permission set, so a self-heal there is
341
+ * guaranteed to fail and the retry after it is guaranteed to be refused
342
+ * identically -- every cycle, forever. Such a failure is returned IMMEDIATELY,
343
+ * exactly the way 'diverged' is, with the provider's operator referral
344
+ * appended to `error` so the caller's typed GitSyncError names the member, the
345
+ * refused command (hence its remote/branch), the refused resource and the
346
+ * missing permission.
347
+ *
348
+ * The gate reads the NEUTRAL classification (kind + permissionScope), never a
349
+ * regex over stderr here -- classification stays the single place VCS stderr
350
+ * is interpreted (vcs-module.mjs's header).
351
+ *
352
+ * WHY THE GATE IS "AUTH_DENIED + permissionScope" AND NOT "AUTH_DENIED"
353
+ * ALONE -- a census of every AUTH_DENIED producer in the tree, so this stays
354
+ * a no-regression change rather than a silent verdict flip for the others:
355
+ * - vcs-providers/github.mjs, the workflow-file refusal: permission-scope.
356
+ * NEW behavior, and the point of this gate -- no self-heal, no retry.
357
+ * - vcs-providers/generic-git.mjs, /Permission denied \(publickey\)/ and
358
+ * /HTTP Basic:\s*Access denied/: UNCHANGED (still self-healed). Both are
359
+ * reached in practice with git's generic "Authentication failed" tail in
360
+ * the same stderr, which AUTH_EXPIRED outranks, so the observable path for
361
+ * them is AUTH_EXPIRED anyway; and a publickey refusal after a credential
362
+ * was mis-deployed IS sometimes fixed by re-provisioning. Flipping them
363
+ * would be an unrelated behavior change.
364
+ * - vcs-providers/azure-devops.mjs, TF401019 and a REST 403: UNCHANGED
365
+ * (still self-healed). The self-heal is also that provider's ONLY vehicle
366
+ * for printing its `authRemedy` hint to the operator
367
+ * (vcs-auth.mjs's createVcsAuthSelfHealCallback), and re-deploying a
368
+ * stored PAT that simply never reached the member does fix it. Pinned by
369
+ * test/vcs-nongithub-auth-selfheal.test.mjs and
370
+ * test/mock-sprint-vcs-selfheal-remedy.test.mjs.
371
+ * No existing AUTH_DENIED producer changes verdict or self-heal treatment;
372
+ * only a provider that OPTS IN via `permissionScope` does.
373
+ *
374
+ * @returns {Promise<{ ok: boolean, output: string, error: string|null, kind?: 'diverged'|'auth'|'transient'|'unknown', permissionScope?: boolean }>}
375
+ */
376
+ export async function runGitStep({ command, member, cmd, label, log, maxTransientRetries, onAuthFailure, provider }) {
377
+ let attempt = 0;
378
+ let authHealAttempted = false;
379
+ // eslint-disable-next-line no-constant-condition
380
+ while (true) {
381
+ const res = await command(cmd, { member_name: member, silent: true, failSoft: true, label });
382
+ if (res && res.ok) return res;
383
+ const error = res ? res.error : 'unknown command failure';
384
+ // ONE classification per attempt, read both ways: the neutral kind
385
+ // (for the permission-scope gate) and this module's legacy verdict
386
+ // (for the transient/auth routing below). classifyGitFailure() is
387
+ // exactly toGitVerdict(classifyFailure(...).kind), so the two readings
388
+ // can never disagree -- see that function's own doc comment.
389
+ const classified = classifyFailure(error, provider ? { provider } : undefined);
390
+ const kind = toGitVerdict(classified.kind);
391
+ if (classified.kind === VCS_FAILURE_KINDS.AUTH_DENIED && classified.permissionScope) {
392
+ const referral =
393
+ `[Sync] permission-scope git failure for member '${member}' (${label}): the command "${cmd}" was refused because the ` +
394
+ "member's VCS credential lacks a required permission. Not self-healing and not retrying -- re-provisioning mints the same " +
395
+ `permission set. ${classified.operatorReferral || 'An operator must grant the missing permission before this command can succeed.'}`;
396
+ log(referral);
397
+ return {
398
+ ok: false,
399
+ output: res ? res.output : '',
400
+ error: `${error}\n${referral}`,
401
+ kind,
402
+ permissionScope: true,
403
+ };
404
+ }
405
+ if (kind === 'transient' && attempt < maxTransientRetries) {
406
+ attempt += 1;
407
+ log(`[Sync] transient git failure for member '${member}' (${label}); retry ${attempt}/${maxTransientRetries}: ${error}`);
408
+ continue;
409
+ }
410
+ if ((kind === 'auth' || kind === 'unknown') && typeof onAuthFailure === 'function' && !authHealAttempted) {
411
+ authHealAttempted = true;
412
+ log(`[Sync] ${kind} git failure for member '${member}' (${label}); invoking self-heal (provision_vcs_auth) once before a single bounded retry: ${error}`);
413
+ try {
414
+ await onAuthFailure({ member, label, cmd, error, kind: 'git' });
415
+ } catch (healErr) {
416
+ log(`[Sync] self-heal for member '${member}' (${label}) failed; not retrying further: ${healErr.message}`);
417
+ return { ok: false, output: res ? res.output : '', error, kind };
418
+ }
419
+ log(`[Sync] self-heal for member '${member}' (${label}) completed; retrying the failed git command once.`);
420
+ continue;
421
+ }
422
+ return { ok: false, output: res ? res.output : '', error, kind };
423
+ }
424
+ }
425
+
426
+ /**
427
+ * Resolve `member`'s VCS provider via an injected `resolveMemberProvider`
428
+ * (see createMemberVcsProviderResolver below) for threading into
429
+ * classifyGitFailure(), failing CLOSED to `undefined` (today's default
430
+ * 'github' chain) on any error or when no resolver was injected -- this must
431
+ * never throw, since a provider-resolution hiccup must never abort a sync
432
+ * bracket that would otherwise succeed on the default chain.
433
+ *
434
+ * @param {((member: string) => Promise<string|undefined>)|undefined} resolveMemberProvider
435
+ * @param {string} member
436
+ * @param {Function} log
437
+ * @returns {Promise<string|undefined>}
438
+ */
439
+ export async function resolveGitProviderForClassification(resolveMemberProvider, member, log) {
440
+ if (typeof resolveMemberProvider !== 'function') return undefined;
441
+ try {
442
+ return await resolveMemberProvider(member);
443
+ } catch (err) {
444
+ log(`[Sync] could not resolve member '${member}'s VCS provider for git-failure classification (falling back to the default provider chain, no verdict change for GitHub members): ${err.message}`);
445
+ return undefined;
446
+ }
447
+ }
448
+
449
+ /**
450
+ * (apra-fleet-p2to.4.2) Map an `execute_command` tool result to the SOFT git
451
+ * runner contract resyncReacquiredMember() consumes:
452
+ * { ok: boolean, stdout?: string, error?: string }
453
+ *
454
+ * `ok` MUST be derived from the command's real EXIT CODE, never from an
455
+ * `isError` flag: the fleet server's `execute_command` tool does NOT set
456
+ * `isError` on a non-zero exit (see src/services/tool-registry.ts wrapTool() --
457
+ * it returns `{ content, structuredContent: { exitCode } }` with no isError,
458
+ * and src/tools/execute-command.ts formats the text as `Exit code: N\n...`).
459
+ * Reading `isError` here would make EVERY git command look successful, which is
460
+ * catastrophic for `git merge-base --is-ancestor` where the whole point is that
461
+ * a NON-zero exit (1 = "not an ancestor") is the meaningful signal: misreading
462
+ * it as ok=true collapses 'ahead'/'diverged' into 'behind-or-equal' and lets
463
+ * resyncReacquiredMember() run `git checkout -B <branch> origin/<branch>`,
464
+ * resetting away committed-but-unpushed work. So: prefer the structured
465
+ * `exitCode`, else parse the `Exit code: N` line out of the text, and only as a
466
+ * last resort (no exit code recoverable at all -- e.g. a transport-level string
467
+ * failure from the tool) fall back to the `isError` flag.
468
+ *
469
+ * @param {any} res - an `execute_command` MCP result (`{ content, structuredContent }`),
470
+ * a plain string, or `{ isError, ... }`.
471
+ * @returns {{ ok: boolean, stdout: string, error: string|undefined }}
472
+ */
473
+ export function commandResultToSoftGit(res) {
474
+ let text = '';
475
+ if (typeof res === 'string') {
476
+ text = res;
477
+ } else if (res && Array.isArray(res.content)) {
478
+ text = res.content
479
+ .map((c) => (c && typeof c.text === 'string' ? c.text : ''))
480
+ .join('\n');
481
+ } else if (res && typeof res.text === 'string') {
482
+ text = res.text;
483
+ }
484
+
485
+ let exitCode;
486
+ if (res && res.structuredContent && typeof res.structuredContent.exitCode === 'number') {
487
+ exitCode = res.structuredContent.exitCode;
488
+ } else {
489
+ const m = /Exit code:\s*(-?\d+)/.exec(text);
490
+ if (m) exitCode = Number(m[1]);
491
+ }
492
+
493
+ const ok = exitCode !== undefined ? exitCode === 0 : !(res && res.isError);
494
+ return { ok, stdout: text, error: ok ? undefined : (text || 'unknown error') };
495
+ }