@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
@@ -45,6 +45,7 @@ See sub-documents for detailed usage:
45
45
  - `skill-matrix.md` - skill installation matrix by project + VCS + role
46
46
  - `auth-github.md`, `auth-bitbucket.md`, `auth-azdevops.md` - VCS auth provisioning per provider
47
47
  - `beads.md` - Beads persistent task DB: commands, backlog ops, session recovery patterns
48
+ - `beads-conflict-resolution.md` - manual dolt SQL recovery when `bd dolt pull`/`push` reports a real merge conflict
48
49
 
49
50
  ## Beads - Persistent Task Tracking
50
51
 
@@ -54,13 +55,13 @@ Beads (`bd` CLI) is installed automatically by `apra-fleet install`. It gives fl
54
55
 
55
56
  See `beads.md` for the full command reference and workflow examples.
56
57
 
57
- ## Secure Credentials
58
+ ## Secret variables
58
59
 
59
- The `{{secure.NAME}}` pattern lets you reference stored secrets in any command without ever exposing plaintext to the LLM or logs.
60
+ The `{{secret.NAME}}` pattern lets you reference stored secrets in any command without ever exposing plaintext to the LLM or logs.
60
61
 
61
62
  **How it works:**
62
63
  1. Store a secret with `credential_store_set` - Fleet opens an OOB terminal prompt, so the value never appears in chat
63
- 2. Reference it as `{{secure.NAME}}` anywhere in a command string passed to `execute_command`, `register_member`, `update_member`, `provision_vcs_auth`, or `provision_auth`
64
+ 2. Reference it as `{{secret.NAME}}` anywhere in a command string passed to `execute_command`, `register_member`, `update_member`, `provision_vcs_auth`, `provision_llm_auth`, or `setup_git_app`
64
65
  3. Fleet resolves the token server-side before execution; LLM does not see the secret.
65
66
 
66
67
  **When to use:**
@@ -68,7 +69,7 @@ The `{{secure.NAME}}` pattern lets you reference stored secrets in any command w
68
69
  - Rotating credentials: `credential_store_delete` then `credential_store_set` - no re-provisioning required
69
70
  - Pre-loading secrets before a dispatch so members can authenticate in commands autonomously
70
71
 
71
- NOTE: **`{{secure.NAME}}` only resolves in specific credential fields** (listed above). Using it in any other parameter (e.g. a prompt, a path field in a non-credential tool, or any other unsupported parameter) will pass the token string through literally - the secret will NOT be injected, and the raw handle name will be visible in logs. Only use `{{secure.NAME}}` in the fields documented above.
72
+ NOTE: **`{{secret.NAME}}` only resolves in specific credential fields** (listed above). Using it in any other parameter (e.g. a prompt, a path field in a non-credential tool, or any other unsupported parameter) will pass the token string through literally - the secret will NOT be injected, and the raw handle name will be visible in logs. Only use `{{secret.NAME}}` in the fields documented above.
72
73
 
73
74
  **Access control (scoping):** Credentials can be scoped to specific members.
74
75
  - `members="*"` (default) - all members can access the credential
@@ -168,9 +169,9 @@ execute_prompt(
168
169
  - If `substitutions` is omitted and file/prompt content contains `{{token}}` patterns, a warning is returned (call still succeeds).
169
170
 
170
171
  **[SECURE] Secrets boundary -- never use substitutions for secrets:**
171
- - Substitution keys with dots (e.g. `secure.github_pat`) are rejected outright.
172
- - `{{secure.NAME}}` patterns in file/prompt content pass through verbatim - they are resolved later only by `execute_command` via the credential store, not here.
173
- - Substitution values are never logged. But callers must not put plaintext secrets in substitution values; use `{{secure.NAME}}` in `execute_command` for secrets.
172
+ - Substitution keys with dots (e.g. `secret.github_pat`) are rejected outright.
173
+ - `{{secret.NAME}}` patterns in file/prompt content pass through verbatim - they are resolved later only by `execute_command` via the credential store, not here.
174
+ - Substitution values are never logged. But callers must not put plaintext secrets in substitution values; use `{{secret.NAME}}` in `execute_command` for secrets.
174
175
 
175
176
  ## Permissions
176
177
 
@@ -204,15 +205,25 @@ The `resume` parameter controls whether a prior session is continued:
204
205
 
205
206
  | Value | Behaviour |
206
207
  |-------|-----------|
207
- | `true` (default) | If a session ID is stored for this member, continues it. If none exists, starts fresh. |
208
+ | `true` (default) | Best-effort resume of the member's STORED LAST session. If a session ID is stored for this member, continues it; if none exists, starts fresh. |
208
209
  | `false` | Always starts a fresh session - ignores any stored session ID. |
210
+ | `"<session-id>"` (string) | EXPLICIT resume of exactly that session, preferred over the member's stored session. Terminal on an unknown/expired id: the call returns structured `{ isError: true, reason: "session_not_found" }`, makes NO LLM call, and does NOT fall back to a fresh session. |
209
211
 
210
- `resume` is boolean only. There is no way to target a specific session ID by value.
211
- The tool always resumes the most recently stored session for that member.
212
+ `resume` accepts a boolean OR a session-ID string, so a caller CAN target a specific
213
+ session by value. The `session_id` parameter is a shorthand for the string form
214
+ (`session_id: "X"` is equivalent to `resume: "X"`, and takes precedence over `resume`).
215
+
216
+ Prefer the string form whenever the prompt depends on one specific session's prior
217
+ context. `true` resolves to the member's single globally-stored last session, which is
218
+ shared across every role and has no task scoping - under `true`, a retry can silently
219
+ land in an unrelated role's session and answer with the wrong shape. The string form
220
+ trades that silent-wrong-context failure for a loud, pre-LLM `session_not_found` that the
221
+ caller can handle (typically: re-dispatch once with `resume: false`).
212
222
 
213
223
  **Automatic stale-session recovery:** If `resume=true` and the stored session has expired
214
224
  or the provider returns an error, `execute_prompt` retries once automatically with a fresh
215
- session. This recovery is transparent - no caller intervention required.
225
+ session. This recovery is transparent - no caller intervention required. It applies ONLY
226
+ to `resume: true`; an explicit session-ID string never falls back this way (see the table).
216
227
 
217
228
  **Provider support:**
218
229
 
@@ -220,9 +231,9 @@ session. This recovery is transparent - no caller intervention required.
220
231
  |----------|---------------|-------|
221
232
  | Claude | Full | `claude --resume <sessionId>` |
222
233
  | Antigravity (agy) | Full | `agy --conversation <sessionId>` |
234
+ | OpenCode | Full | `opencode run --session <sessionId>` (`--continue` when no id is stored) |
223
235
  | Codex | Partial | `resume` command supported |
224
236
  | Copilot | None | Always starts fresh regardless of `resume` value |
225
- | Gemini | Full | Native session support |
226
237
 
227
238
  Session IDs are parsed from `execute_prompt` output and stored server-side per member.
228
239
  The output footer contains: `session: <sessionId>` when the provider supports it.
@@ -242,10 +253,10 @@ Per-provider flag behaviour:
242
253
  | Provider | `'auto'` flag | `'dangerous'` flag |
243
254
  |----------|--------------|-------------------|
244
255
  | Claude | `--permission-mode auto` | `--dangerously-skip-permissions` |
245
- | Antigravity (agy) | None (config-file only via `compose_permissions`) | `--dangerously-skip-permissions` |
256
+ | Antigravity (agy) | `--mode accept-edits` (same as default; grants come from `compose_permissions`) | `--dangerously-skip-permissions` |
257
+ | OpenCode | `--auto` | `--dangerously-skip-permissions` |
246
258
  | Codex | `--ask-for-approval auto-edit` | `--sandbox danger-full-access --ask-for-approval never` |
247
259
  | Copilot | Not supported - warns and runs interactively | Not supported |
248
- | Gemini | None (config-file only via `compose_permissions`) | `--yolo` |
249
260
 
250
261
  Auto-approval is delivered via config files written by `compose_permissions` - call it before every dispatch.
251
262
 
@@ -282,9 +293,9 @@ When you see this notice, surface it to the user verbatim before the rest of the
282
293
 
283
294
  | Concern | How to handle |
284
295
  |---------|---------------|
285
- | **Agent context file** | Use `member_detail` -> `llmProvider` to determine filename: CLAUDE.md (Claude), AGY.md (Antigravity), GEMINI.md (Gemini), AGENTS.md (Codex), COPILOT.md (Copilot) |
296
+ | **Agent context file** | Use `member_detail` -> `llmProvider` to determine filename: CLAUDE.md (Claude), AGY.md (Antigravity), AGENTS.md (Codex and OpenCode), COPILOT.md (Copilot) |
286
297
  | **Attribution config** | Claude-only (Step 2 in onboarding.md) - skip for all other providers |
287
- | **Timeouts** | Antigravity/Gemini members are slower -> use 2-3x timeout multiplier for `execute_prompt` dispatches to those members. Minimum `timeout_s: 900` for any non-trivial task. |
298
+ | **Timeouts** | Antigravity members are slower -> use 2-3x timeout multiplier for `execute_prompt` dispatches to those members. Minimum `timeout_s: 900` for any non-trivial task. |
288
299
 
289
300
  ## Fleet Logs
290
301
 
@@ -9,15 +9,41 @@ Personal Access Tokens (PATs) with configurable scopes and expiration. Auth: emp
9
9
  3. Set descriptive name (e.g., "fleet-{name}")
10
10
  4. Select required scopes (see below)
11
11
  5. Set expiration (recommend: 90 days)
12
- 6. Copy token — shown only once
12
+ 6. Copy token - shown only once
13
13
  7. Provide token and org URL when prompted
14
14
 
15
+ ### Expiry Capture (Optional)
16
+
17
+ When first registering a PAT, you can optionally capture its expiration date by passing `pat_expires_at` (ISO 8601, e.g. `2027-08-20T00:00:00Z`) to `provision_vcs_auth`. Azure DevOps exposes no API to read a PAT's expiry back, so this value must come from the operator -- the date chosen in the "Set expiration" step above. It is validated at the schema boundary and rejected if unparseable. The fleet stores this expiry date and checks it against two separate thresholds (see `src/utils/agent-helpers.ts`):
18
+
19
+ - **Minute-scale warning** (`EXPIRY_WARNING_MS`, 10 minutes): fires for any provider once the credential is within 10 minutes of expiry. This threshold was sized for GitHub App tokens (~1hr lifetime).
20
+ - **Day-scale warning** (`DAY_SCALE_WARNING_MS`, 7 days): fires only for providers listed in `DAY_SCALE_WARNING_PROVIDERS`, which currently includes `azure-devops`. Because Azure DevOps PATs run weeks to months (see "Set expiration" above), this gives a heads-up long before the minute-scale check would ever fire.
21
+
22
+ Either warning causes the fleet to request a fresh provisioning before the sprint dispatch rather than failing mid-sprint when the credential becomes invalid.
23
+
24
+ This step is optional; PATs function normally even without expiry tracking. However, recording expiry dates helps prevent surprise authentication failures and reduces retry cycles.
25
+
15
26
  ## Deploy
16
27
 
17
28
  ```
18
- provision_vcs_auth(member_id, provider: 'azure-devops', org_url: 'https://dev.azure.com/myorg', pat: '...')
29
+ provision_vcs_auth(member_id, provider: 'azure-devops', org_url: 'https://dev.azure.com/myorg', pat: '...', pat_expires_at: '2027-08-20T00:00:00Z')
19
30
  ```
20
31
 
32
+ ## Secret-Name Convention
33
+
34
+ The Azure DevOps PAT is stored in the fleet's credential store under a configurable name. **Default:** `azdevops_pat`
35
+
36
+ The credential is entered via the out-of-band prompt during `provision_vcs_auth` and is stored as a secure placeholder. When used in `execute_command` calls, the fleet resolves the placeholder on the server side - the plaintext token never appears in logs, prompts, or LLM transcripts.
37
+
38
+ **Store or reference the default credential:**
39
+
40
+ ```
41
+ credential_store_set name=azdevops_pat
42
+ execute_command command="curl -sf -u :{{secret.azdevops_pat}} 'https://dev.azure.com/{org}/_apis/projects?api-version=7.1'"
43
+ ```
44
+
45
+ **Per-sprint override:** To use a different credential name for a specific sprint (for example, when working with a different Azure DevOps organization or test repo), pass the `azdevops_pat_secret_name` argument to the sprint invocation (threaded through `packages/apra-fleet-se/fleet-sprint/runner.js`). It must name a credential already stored via `credential_store_set`; the runner validates it as a credential-store name at contract-validation time and uses it instead of the default `azdevops_pat` entry for provisioning, self-heal, and preflight checks on that sprint.
46
+
21
47
  ## Scopes
22
48
 
23
49
  | Role | PAT Scopes |
@@ -37,18 +63,41 @@ curl -sf -u :pat "https://dev.azure.com/{org}/_apis/projects?api-version=7.1&\$t
37
63
  git ls-remote https://dev.azure.com/{org}/{project}/_git/{repo} HEAD
38
64
  ```
39
65
 
66
+ ## Legacy `<org>.visualstudio.com` remotes
67
+
68
+ git looks credentials up by the remote's own hostname, so a PAT bound to
69
+ `dev.azure.com` is never offered for a push to `https://<org>.visualstudio.com/...`.
70
+ Pass `scope_url="https://<org>.visualstudio.com"` to `provision_vcs_auth`
71
+ (fleet-sprint does this automatically from the member's remote). `org_url`
72
+ stays `https://dev.azure.com/<org>` -- the REST API serves every org there.
73
+ An ssh remote (`vs-ssh.visualstudio.com` / `ssh.dev.azure.com`) cannot take a
74
+ PAT at all: push uses the member's SSH key; the PAT serves only REST calls.
75
+
40
76
  ## Troubleshooting
41
77
 
42
78
  | Symptom | Fix |
43
79
  |---------|-----|
44
80
  | 401 Unauthorized | Create new PAT and re-deploy |
81
+ | push to `<org>.visualstudio.com` prompts / 401 while REST works | Re-provision with `scope_url="https://<org>.visualstudio.com"` |
45
82
  | 403 Forbidden | Create PAT with broader scopes |
46
83
  | TF400813: Resource not available | Verify org URL matches `https://dev.azure.com/{org}` |
47
84
  | Clone prompts for password | Re-run `provision_vcs_auth` |
48
85
 
86
+ ## PAT Lifetime and Expiry
87
+
88
+ A fleet provisioning Azure DevOps credentials **cannot self-extend or auto-renew a PAT**. The Azure DevOps PAT lifecycle management API requires an Entra (Azure AD) OAuth token with admin consent, which the fleet does not hold. This is a fundamental design constraint: the fleet stores only the PAT itself, never the credentials needed to mint a fresh PAT or extend an existing one.
89
+
90
+ **Implications:**
91
+
92
+ - PATs must be renewed manually before expiry by re-running `provision_vcs_auth` and providing a fresh token.
93
+ - The optional expiry capture (see Setup section above) enables day-scale preflight warnings so the sprint can request a fresh provisioning before the credential becomes invalid.
94
+ - If a PAT expires mid-sprint, the sprint will fail with auth errors until `provision_vcs_auth` is re-run with a valid token.
95
+
96
+ To avoid disruption, set a calendar reminder to renew PATs well before their expiry date, or use the optional expiry-capture feature to let the fleet warn you in advance.
97
+
49
98
  ## Storing tokens for reuse
50
99
 
51
- After provisioning VCS auth, you can store the Azure DevOps PAT in the credential store for direct use in `execute_command` — for example, calling the Azure DevOps REST API or authenticating git operations manually.
100
+ After provisioning VCS auth, you can store the Azure DevOps PAT in the credential store (see Secret-Name Convention section above) for direct use in `execute_command` - for example, calling the Azure DevOps REST API or authenticating git operations manually.
52
101
 
53
102
  **Store an Azure DevOps PAT for reuse:**
54
103
 
@@ -59,14 +108,15 @@ credential_store_set name=azdevops_pat
59
108
  **Use it in a command on a member:**
60
109
 
61
110
  ```
62
- execute_command command="curl -sf -u :{{secure.azdevops_pat}} 'https://dev.azure.com/{org}/_apis/projects?api-version=7.1'"
63
- execute_command command="git remote set-url origin https://token:{{secure.azdevops_pat}}@dev.azure.com/{org}/{project}/_git/{repo}"
111
+ execute_command command="curl -sf -u :{{secret.azdevops_pat}} 'https://dev.azure.com/{org}/_apis/projects?api-version=7.1'"
112
+ execute_command command="git remote set-url origin https://token:{{secret.azdevops_pat}}@dev.azure.com/{org}/{project}/_git/{repo}"
64
113
  ```
65
114
 
66
- The token is resolved server-side and redacted in output (`[REDACTED:azdevops_pat]`) — it never appears in the LLM conversation or command logs.
115
+ The token is resolved server-side and redacted in output (`[REDACTED:azdevops_pat]`) - it never appears in the LLM conversation or command logs.
67
116
 
68
117
  ## Notes
69
118
 
70
119
  - PAT expiration: default 30 days, max 1 year
71
- - Azure DevOps does not support app-based tokens — PATs are the standard
120
+ - Azure DevOps does not support app-based tokens - PATs are the standard
72
121
  - Org URL must be base URL without trailing path
122
+ - To learn what scopes are required for your role, see the Scopes table above
@@ -7,7 +7,7 @@ API tokens (app passwords) tied to a user account. Long-lived, no auto-expire.
7
7
  1. Go to `https://id.atlassian.com/manage-profile/security/api-tokens`
8
8
  (or Bitbucket: Settings > Personal Bitbucket settings > App passwords)
9
9
  2. Create app password with required scopes (see below)
10
- 3. Copy token — shown only once
10
+ 3. Copy token - shown only once
11
11
  4. Provide token, email, and workspace slug when prompted
12
12
 
13
13
  ## Deploy
@@ -38,7 +38,7 @@ git ls-remote https://bitbucket.org/{workspace}/{repo}.git HEAD
38
38
 
39
39
  ## Storing tokens for reuse
40
40
 
41
- After provisioning VCS auth, you can store the Bitbucket API token in the credential store for direct use in `execute_command` — for example, calling the Bitbucket REST API or authenticating git operations manually.
41
+ After provisioning VCS auth, you can store the Bitbucket API token in the credential store for direct use in `execute_command` - for example, calling the Bitbucket REST API or authenticating git operations manually.
42
42
 
43
43
  **Store a Bitbucket token for reuse:**
44
44
 
@@ -49,11 +49,11 @@ credential_store_set name=bitbucket_token
49
49
  **Use it in a command on a member:**
50
50
 
51
51
  ```
52
- execute_command command="curl -sf -u me@example.com:{{secure.bitbucket_token}} https://api.bitbucket.org/2.0/user"
53
- execute_command command="git remote set-url origin https://me@example.com:{{secure.bitbucket_token}}@bitbucket.org/workspace/repo.git"
52
+ execute_command command="curl -sf -u me@example.com:{{secret.bitbucket_token}} https://api.bitbucket.org/2.0/user"
53
+ execute_command command="git remote set-url origin https://me@example.com:{{secret.bitbucket_token}}@bitbucket.org/workspace/repo.git"
54
54
  ```
55
55
 
56
- The token is resolved server-side and redacted in output (`[REDACTED:bitbucket_token]`) — it never appears in the LLM conversation or command logs.
56
+ The token is resolved server-side and redacted in output (`[REDACTED:bitbucket_token]`) - it never appears in the LLM conversation or command logs.
57
57
 
58
58
  ## Troubleshooting
59
59
 
@@ -10,14 +10,14 @@ When to use: Org repos where you have admin access to install a GitHub App.
10
10
 
11
11
  Setup:
12
12
  1. Create GitHub App at `https://github.com/organizations/{org}/settings/apps`
13
- 2. Grant permissions (Contents, Pull Requests, Actions, etc.)
13
+ 2. Grant the Repository permissions every `git_access` level you will use needs -- exact table in `docs/github-app-setup.md` (fleet-sprint minimum = `push+pr`: Metadata R, Contents RW, Workflows RW, Pull requests RW, Actions RW). Missing any -> mint fails (no downgrade); after changing them an org owner must accept the new permissions on the installation.
14
14
  3. Install on your organization
15
15
  4. Download private key (.pem file)
16
16
  5. Run `setup_git_app` with App ID, private key path, installation ID
17
17
 
18
18
  Deploy:
19
19
  ```
20
- provision_vcs_auth(member_id, provider: 'github')
20
+ provision_vcs_auth(member_id, provider: 'github') # needs git_access + git_repos on the member
21
21
  provision_vcs_auth(member_id, provider: 'github', git_access: 'push', repos: ['Org/Repo'])
22
22
  ```
23
23
 
@@ -59,7 +59,7 @@ gh api /user
59
59
 
60
60
  ## Storing tokens for reuse
61
61
 
62
- After provisioning VCS auth, you can also store the token in the credential store so members can use it directly in `execute_command` calls — for example, when calling the GitHub REST API or authenticating git operations that bypass the configured remote URL.
62
+ After provisioning VCS auth, you can also store the token in the credential store so members can use it directly in `execute_command` calls - for example, when calling the GitHub REST API or authenticating git operations that bypass the configured remote URL.
63
63
 
64
64
  **Store a GitHub PAT for reuse:**
65
65
 
@@ -70,17 +70,18 @@ credential_store_set name=github_pat
70
70
  **Use it in a command on a member:**
71
71
 
72
72
  ```
73
- execute_command command="curl -H 'Authorization: Bearer {{secure.github_pat}}' https://api.github.com/user"
74
- execute_command command="git remote set-url origin https://token:{{secure.github_pat}}@github.com/Org/Repo.git"
73
+ execute_command command="curl -H 'Authorization: Bearer {{secret.github_pat}}' https://api.github.com/user"
74
+ execute_command command="git remote set-url origin https://token:{{secret.github_pat}}@github.com/Org/Repo.git"
75
75
  ```
76
76
 
77
- The token is resolved server-side and redacted in output (`[REDACTED:github_pat]`) — it never appears in the LLM conversation or command logs.
77
+ The token is resolved server-side and redacted in output (`[REDACTED:github_pat]`) - it never appears in the LLM conversation or command logs.
78
78
 
79
79
  ## Troubleshooting
80
80
 
81
81
  | Symptom | Fix |
82
82
  |---------|-----|
83
83
  | 401 Bad credentials | Re-mint via `provision_vcs_auth` |
84
+ | `is not granted one or more of the requested permissions` | App lacks a permission for that level; re-minting won't fix it. Add it + accept on the installation -- see `docs/github-app-setup.md` |
84
85
  | 403 Resource not accessible | Check App permissions or PAT scopes |
85
86
  | Repository not found | Add repo to GitHub App installation |
86
87
  | gh: command not found | Install via `brew install gh` or `apt install gh` |
@@ -0,0 +1,141 @@
1
+ # Beads Conflict Resolution -- Dolt SQL Playbook
2
+
3
+ `bd dolt pull` / `bd dolt push` can fail with a genuine, non-fast-forward divergence:
4
+
5
+ ```
6
+ Error: merge origin/main: merge conflicts in issues require operator resolution;
7
+ merge aborted and working set restored
8
+ ```
9
+
10
+ This is not corruption and the working set is untouched -- `bd` already aborted the
11
+ merge safely. Resolve it by driving the real `dolt` binary against the same data
12
+ directory over SQL, ephemerally, then pull/push again through `bd` as normal.
13
+
14
+ **Do not `bd init`, `bd init --from-jsonl`, or delete `.beads/` to "fix" this** --
15
+ that discards local issue state. See `beads.md`.
16
+
17
+ For the fully automated version of this same procedure (used by fleet-sprint
18
+ itself at every sync point), see `settleDoltConflicts()` in
19
+ `packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs`, which applies a
20
+ deterministic per-field last-writer-wins rulebook instead of a human picking a
21
+ side. This playbook is the manual fallback -- use it when you need to see the
22
+ actual conflicting content before deciding, or when settle isn't wired for the
23
+ context you're in (e.g. resolving conflicts in the orchestrator's own local
24
+ checkout rather than against a registered fleet member).
25
+
26
+ ## 0. Find the real data directory -- never hardcode it
27
+
28
+ ```bash
29
+ bd dolt status
30
+ ```
31
+
32
+ Read the `Data:` line. **On a machine with multiple worktrees, `bd` resolves to
33
+ one shared `.beads` directory for the whole repo (typically the main checkout's),
34
+ not a per-worktree copy** -- always use the absolute path this command reports,
35
+ never a path you assume from cwd.
36
+
37
+ If it reports `embedded (in-process, no server)`, there's no live server to
38
+ route through -- start an ephemeral one (step 2). If it already reports a live
39
+ server (`host:port`), target that instead of starting a second one.
40
+
41
+ ## 1. Ensure the pinned `dolt` binary is present
42
+
43
+ ```powershell
44
+ & "$env:USERPROFILE\.apra-fleet\bin\dolt.exe" version # Windows
45
+ ```
46
+ ```bash
47
+ "$HOME/.apra-fleet/bin/dolt" version # POSIX
48
+ ```
49
+
50
+ Never install via a package manager (`winget`/`apt`/`brew`) -- it delivers an
51
+ unpinned version that drifts from the repo's pin and can be invisible to
52
+ already-running sessions' PATH. If missing, fetch the pinned release asset
53
+ (`DOLT_VERSION` in `src/cli/dolt-install.ts`) to that exact path.
54
+
55
+ ## 2. Start an ephemeral sql-server against that data dir
56
+
57
+ **Windows -- `Start-Process` does NOT actually detach** (dies with the SSH/job
58
+ session). Use WMI:
59
+
60
+ ```powershell
61
+ $result = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{
62
+ CommandLine = 'cmd /c ""C:\Users\<you>\.apra-fleet\bin\dolt.exe" sql-server --host 127.0.0.1 --port 13401 --data-dir "<ABSOLUTE data dir from step 0>" > "%TEMP%\dolt-settle-local.log" 2>&1"'
63
+ CurrentDirectory = '<absolute path to your repo checkout>'
64
+ }
65
+ $result.ProcessId # record for teardown -- this is cmd.exe's PID, not dolt's (see step 5)
66
+ ```
67
+
68
+ Wrapping in `cmd /c ... > log 2>&1` is required to capture startup errors (a bad
69
+ `--data-dir` fails silently otherwise). Verify before proceeding:
70
+
71
+ ```powershell
72
+ Test-NetConnection -ComputerName 127.0.0.1 -Port 13401 # expect TcpTestSucceeded: True
73
+ Get-Content "$env:TEMP\dolt-settle-local.log" # expect "Server ready. Accepting connections."
74
+ ```
75
+
76
+ **POSIX:** `nohup dolt sql-server --host 127.0.0.1 --port 13401 --data-dir <dir> > /tmp/dolt-recovery.log 2>&1 & disown`
77
+
78
+ ## 3. Inspect the conflict before resolving -- do not guess a side
79
+
80
+ ```bash
81
+ dolt --no-tls --host=127.0.0.1 --port=13401 sql -q "
82
+ USE beads;
83
+ SET @@dolt_allow_commit_conflicts = 1;
84
+ CALL DOLT_MERGE('origin/main');
85
+ SELECT \`table\` FROM dolt_conflicts;"
86
+ ```
87
+
88
+ Two non-obvious flag landmines: `--no-tls` must come *before* `--host`/`--port`
89
+ (order-sensitive), and never pass `--user=root` or `--password` explicitly --
90
+ that switches the client into an interactive credential prompt that then fails
91
+ non-interactively. Omit both and it authenticates as root/empty-password
92
+ silently.
93
+
94
+ For each conflicted table, see which rows and which side is newer:
95
+
96
+ ```sql
97
+ SELECT base_id, our_id, their_id, our_updated_at, their_updated_at
98
+ FROM dolt_conflicts_issues; -- table name is `dolt_conflicts_<table>`
99
+ ```
100
+
101
+ ## 4. Resolve -- per-field last-writer-wins, not a blanket side
102
+
103
+ ```sql
104
+ CALL DOLT_CONFLICTS_RESOLVE('--ours', 'issues'); -- our_updated_at newer
105
+ -- or '--theirs' if their_updated_at is newer
106
+ CALL DOLT_COMMIT('-m', 'manual recovery: resolve <issue-id> conflict, <ours|theirs> newer');
107
+ SELECT COUNT(*) FROM dolt_conflicts; -- MUST be 0 before continuing
108
+ ```
109
+
110
+ A bare `--ours`/`--theirs` picks the whole row. Only safe when one side is
111
+ strictly newer (verify via `updated_at` from step 3) or you've confirmed the
112
+ older side's content is already fully contained in the newer side -- never
113
+ pick a side just to make the error go away.
114
+
115
+ ## 5. Teardown BEFORE republishing -- order matters
116
+
117
+ Embedded-mode `bd` needs Dolt's per-directory exclusive lock; republishing
118
+ while the ephemeral server still holds it fails or silently falls back
119
+ read-only.
120
+
121
+ ```powershell
122
+ Get-Process | Where-Object { $_.ProcessName -eq 'dolt' } | Stop-Process -Force
123
+ # the WMI-created PID from step 2 is cmd.exe, not dolt.exe -- find dolt.exe by name, not by that PID
124
+ Test-NetConnection -ComputerName 127.0.0.1 -Port 13401 # expect False
125
+ ```
126
+
127
+ Then, only after the port is confirmed closed:
128
+
129
+ ```bash
130
+ bd dolt pull # verify
131
+ bd dolt push # republish
132
+ ```
133
+
134
+ ## Full reference
135
+
136
+ `packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md` --
137
+ the original live-verified spec this playbook condenses, including the
138
+ `settleDoltConflicts()` rulebook for tables other than `issues` (union for
139
+ `labels`, plain theirs for machine-local/append-only tables) and the
140
+ `dolt_mode` cleanup guarantee if a recovery ever routes `bd` itself through a
141
+ server.
@@ -1,8 +1,8 @@
1
- # Beads — Persistent Task DB for Fleet Users
1
+ # Beads - Persistent Task DB for Fleet Users
2
2
 
3
3
  Beads (`bd`) is a lightweight, dependency-aware task database installed automatically by `apra-fleet install`.
4
4
 
5
- **`bd` runs on the orchestrator via `Bash` — never expose `bd` commands to the user and never run `bd` via `execute_command` on a member.**
5
+ **`bd` runs on the orchestrator via `Bash` - never expose `bd` commands to the user and never run `bd` via `execute_command` on a member.**
6
6
 
7
7
  ---
8
8
 
@@ -24,11 +24,15 @@ bd list --assignee <member> # tasks for a specific member
24
24
  bd search "text" --status all --json # find existing issues by title (use for dedup)
25
25
  ```
26
26
 
27
- **Never run `bd init` on a repo that already has a `.beads/` directory** — it pulls from
27
+ **Never run `bd init` on a repo that already has a `.beads/` directory** - it pulls from
28
28
  remote and recreates the database, discarding local issue state. It is NOT idempotent.
29
29
  Only run it once, on a repo with no `.beads/` yet. For a fresh clone or recovering a
30
30
  missing/corrupt DB, prefer `bd bootstrap` (non-destructive) over `bd init`.
31
31
 
32
+ If `bd dolt pull`/`push` instead fails with a real merge conflict ("merge conflicts in
33
+ issues require operator resolution"), see `beads-conflict-resolution.md` - do not
34
+ `bd init` your way out of it.
35
+
32
36
  ---
33
37
 
34
38
  ## When to Use Beads
@@ -37,7 +41,7 @@ missing/corrupt DB, prefer `bd bootstrap` (non-destructive) over `bd init`.
37
41
  |----------|-----------|
38
42
  | Tracking work across multiple fleet sessions | `bd create` a task per work item; `bd update --assignee <member> --status in_progress` on dispatch |
39
43
  | Expressing dependencies between tasks | `bd dep add <blocked-id> <blocker-id>` |
40
- | Session restart — instant orientation | `bd ready` — shows all in-flight tasks without reading files |
44
+ | Session restart - instant orientation | `bd ready` - shows all in-flight tasks without reading files |
41
45
  | Linking a PR to a task | `bd note <id> "PR: <url>"` |
42
46
 
43
47
  ---
@@ -46,10 +50,10 @@ missing/corrupt DB, prefer `bd bootstrap` (non-destructive) over `bd init`.
46
50
 
47
51
  | Priority | Meaning |
48
52
  |----------|---------|
49
- | `0` | Critical — must fix now |
50
- | `1` | High — next up |
51
- | `2` | Medium — current sprint (default if `-p` omitted) |
52
- | `3` | Low — backlog / deferred |
53
+ | `0` | Critical - must fix now |
54
+ | `1` | High - next up |
55
+ | `2` | Medium - current sprint (default if `-p` omitted) |
56
+ | `3` | Low - backlog / deferred |
53
57
  | `4` | Trivial |
54
58
 
55
59
  ---
@@ -61,11 +65,11 @@ missing/corrupt DB, prefer `bd bootstrap` (non-destructive) over `bd init`.
61
65
  bd init
62
66
 
63
67
  # Create a top-level epic for your current effort
64
- bd create "feat: add SFTP transport" -p 1 # → epic-id
68
+ bd create "feat: add SFTP transport" -p 1 # -> epic-id
65
69
 
66
70
  # Break it into tasks
67
- bd create "T1: implement connection" -p 1 --parent <epic-id> # → t1-id
68
- bd create "T2: add retry logic" -p 2 --parent <epic-id> # → t2-id
71
+ bd create "T1: implement connection" -p 1 --parent <epic-id> # -> t1-id
72
+ bd create "T2: add retry logic" -p 2 --parent <epic-id> # -> t2-id
69
73
  bd dep add <t2-id> <t1-id> # T2 blocked until T1 is done
70
74
 
71
75
  # Dispatch a member to T1
@@ -75,7 +79,7 @@ bd update <t1-id> --assignee <member> --status in_progress
75
79
  bd close <t1-id>
76
80
  bd ready # confirms T2 is now unblocked
77
81
 
78
- # At completion — link PR
82
+ # At completion - link PR
79
83
  bd close <epic-id>
80
84
  bd note <epic-id> "PR: https://github.com/org/repo/pull/42"
81
85
  ```
@@ -14,7 +14,7 @@ Use `member_detail` to determine `llmProvider` and `os`. Run `execute_command` w
14
14
  - **Antigravity:** `agy --version 2>&1`
15
15
  - **Codex:** `codex --version`
16
16
  - **Copilot:** `copilot --version`
17
- - **Gemini:** `gemini --version`
17
+ - **OpenCode:** `opencode --version 2>&1`
18
18
 
19
19
  If the LLM CLI is not installed or the command fails, use `update_llm_cli` to install it before proceeding. Do not attempt any prompt dispatch until the CLI is confirmed.
20
20
 
@@ -26,7 +26,7 @@ Call `provision_llm_auth`. Skip for local members - they inherit auth from the P
26
26
 
27
27
  **Claude only.** Write `{"attribution":{"commit":"","pr":""}}` to `.claude/settings.json` in the member's work folder via `execute_command`. Merge if file already exists.
28
28
 
29
- Antigravity, Codex, Copilot, and Gemini do not support attribution config - skip this step for those providers.
29
+ Antigravity, Codex, Copilot, and OpenCode do not support attribution config - skip this step for those providers.
30
30
 
31
31
  ## Step 3: Detect VCS Provider
32
32
 
@@ -60,7 +60,7 @@ Add to the member's status file:
60
60
 
61
61
  ```
62
62
  ## Member Profile
63
- - LLM Provider: Claude (or agy, gemini, etc.)
63
+ - LLM Provider: Claude (or agy, codex, etc.)
64
64
  - VCS: Bitbucket (kumaakh/apra-lic-mgr)
65
65
  - Roles: development, code-review
66
66
  - Auth: Bitbucket API token (verified)
@@ -75,8 +75,8 @@ If the task you are about to dispatch requires an API key, token, or password (e
75
75
 
76
76
  **Steps:**
77
77
  1. Call `credential_store_set` with a descriptive name (e.g., `github_pat`, `npm_token`, `openai_key`) - Fleet opens an OOB terminal prompt for the value
78
- 2. Pass the `sec://NAME` handle in the task prompt - reference by name only (e.g. `"authenticate using credential github_pat"`). The secret value is only injected server-side when `{{secure.NAME}}` appears in an `execute_command` call - never in AI prompt text.
79
- 3. The member uses `{{secure.NAME}}` in `execute_command` - Fleet resolves the value server-side and redacts it from output before the LLM sees it
78
+ 2. Reference the credential by NAME only in the task prompt (e.g. `"authenticate using credential github_pat"`) - never paste the raw `sec://NAME` handle into a prompt or command; `execute_command` rejects any command containing one. The secret value is only injected server-side when `{{secret.NAME}}` appears in an `execute_command` call - never in AI prompt text.
79
+ 3. The member uses `{{secret.NAME}}` in `execute_command` - Fleet resolves the value server-side and redacts it from output before the LLM sees it
80
80
 
81
81
  **Example - dispatching a member that needs to push code to GitHub:**
82
82
 
@@ -88,5 +88,5 @@ credential_store_set name=github_pat
88
88
  "When pushing code to GitHub, authenticate using credential github_pat."
89
89
 
90
90
  # Member uses it in a command transparently
91
- execute_command command="git remote set-url origin https://token:{{secure.github_pat}}@github.com/Org/Repo.git"
91
+ execute_command command="git remote set-url origin https://token:{{secret.github_pat}}@github.com/Org/Repo.git"
92
92
  ```
@@ -41,7 +41,7 @@ Tags determine the primary mode and grant additional tool scopes:
41
41
  3. Load **custom tag profiles**: for each non-mode tag, load tag-<name>.json and merge its permissions for the primary mode
42
42
  4. Load **ledger grants**: merge any permissions previously granted in project_folder/permissions.json
43
43
 
44
- All merges are additive (Set-based) - order is independent, duplicates discarded. The final allow list is delivered to the member's provider (Claude, Gemini, etc.) in the provider's native config format.
44
+ All merges are additive (Set-based) - order is independent, duplicates discarded. The final allow list is delivered to the member's provider (Claude, Codex, etc.) in the provider's native config format.
45
45
 
46
46
  ### Example
47
47
 
@@ -67,6 +67,9 @@ When `execute_prompt` output contains a permission denial, call `compose_permiss
67
67
 
68
68
  > "Grant Bash(docker:*) to build-server, reason: integration tests, project folder ./my-project"
69
69
 
70
+ For an agy member the failure is structured: `reason: "permission_denied"` with
71
+ `permissionDenied.suggestedGrants` (primary grant first) - review them and pass them as `grant`.
72
+
70
73
  The tool validates (wildcard-matched denylist -- blocks sudo/env, `bash -c`, catch-alls and shell chaining; see [Never auto-granted](#never-auto-granted)), expands co-occurrences (docker -> docker-compose), delivers the updated config, and appends to the project ledger for future use.
71
74
 
72
75
  ## Role switch
@@ -140,13 +143,14 @@ setting `projects[<work_folder>].hasTrustDialogAccepted = true` scoped **strictl
140
143
  that exact work folder (never a parent directory, never blanket) - delivered over the
141
144
  same channel `compose_permissions` already uses, so it works uniformly for local and
142
145
  remote (SSH) members. It logs distinctly whether it just seeded trust or found it
143
- already present. Other providers no-op: Gemini and OpenCode have their own trust gates
144
- but already bypass them per-dispatch (`--skip-trust`, `--dangerously-skip-permissions`);
145
- AGY has no per-project trust concept (machine-global config); Codex/Copilot have no
146
+ already present. Other providers no-op: OpenCode has its own trust gate
147
+ but already bypasses it per-dispatch (`--dangerously-skip-permissions`);
148
+ AGY needs no trust seeding (its grants bind through the member's own agy project,
149
+ `--project` on every dispatch); Codex/Copilot have no
146
150
  known equivalent gate.
147
151
 
148
152
  If `execute_prompt` fails with a `workspace_not_trusted` structured error, the CLI's own
149
153
  stderr will contain a `"...this workspace has not been trusted"` message - seed trust
150
- via `ensureWorkspaceTrusted(workFolder)` (invoked automatically at
151
- register_member/update_member, and on every `compose_permissions` call once that
152
- wiring lands), then retry.
154
+ via `ensureWorkspaceTrusted(workFolder)` -- invoked automatically at
155
+ `register_member`/`update_member`, on every `compose_permissions` call, and as a
156
+ one-shot self-heal inside `execute_prompt` itself -- then retry.
@@ -1,4 +1,4 @@
1
1
  {
2
2
  "dev": ["Bash(npm:*)", "Bash(npx:*)", "Bash(node:*)", "Bash(yarn:*)", "Bash(pnpm:*)", "Bash(tsx:*)", "Bash(npm test*)", "Bash(npm run *)", "Bash(npx vitest *)"],
3
- "reviewer": ["Bash(npm test:*)", "Bash(npm run test:*)", "Bash(npm run lint:*)", "Bash(npx:*)", "Bash(npm test*)", "Bash(npm run *)", "Bash(npx vitest *)"]
3
+ "reviewer": ["Bash(npm test:*)", "Bash(npm run test:*)", "Bash(npm run lint:*)", "Bash(npx:*)", "Bash(node:*)", "Bash(npm test*)", "Bash(npm run *)", "Bash(npx vitest *)"]
4
4
  }
@@ -38,4 +38,4 @@ stored in the member's `tags` array.
38
38
  3. GitHub members rarely need extra skills -- gh CLI covers most operations
39
39
  4. Bitbucket/Azure DevOps members need provider-specific skills for devops/code-review tags (LLMs lack native API knowledge without skills)
40
40
  5. Project-specific skills layer on top of VCS skills
41
- 6. Skills are independent of the member's LLM provider -- a Gemini member needs the same project skills as a Claude member. Skill selection is driven by VCS provider, project, and tags, not LLM provider.
41
+ 6. Skills are independent of the member's LLM provider -- a Codex member needs the same project skills as a Claude member. Skill selection is driven by VCS provider, project, and tags, not LLM provider.
@@ -5,9 +5,10 @@
5
5
  | Empty response | Check auth token expiry -> re-provision via `provision_vcs_auth` |
6
6
  | Timeout (inactivity) | `timeout_s`: fires when no stdout/stderr output arrives for N seconds (default 300s / 5 min). Applies to all members and all providers - transport-level, not provider-specific. Common cause: test runners and build tools that buffer output (npm test, vitest, cargo build) producing no output for long stretches even while active. Fix: increase `timeout_s` to 600-1200 for build/test dispatches. |
7
7
  | Timeout (total) | `max_total_s`: fires after N seconds of total elapsed time regardless of output activity. Provider-agnostic. Use for hard ceilings on long-running jobs. Set alongside `timeout_s` when you need both a silence guard and a wall-clock cap. |
8
- | Permission denied | Run `compose_permissions` for the member - it produces provider-native config. Claude: check `.claude/settings.local.json`. Agy: check `~/.gemini/config/hooks.json` and `mcp_config.json`. Codex: check `.codex/config.toml` approval mode. Copilot: check `.github/copilot/settings.local.json`. Gemini: check `.gemini/policies/`. |
8
+ | Permission denied | Run `compose_permissions` for the member - it produces provider-native config. Claude: check `.claude/settings.local.json`. Agy: `execute_prompt` returns `reason: "permission_denied"` with `permissionDenied.suggestedGrants` - pass them to `compose_permissions` `grant`; grants live in `~/.gemini/config/projects/<agyProjectId>.json` on the member (`agyProjectId` from `member_detail`). Codex: check `.codex/config.toml` approval mode. Copilot: check `.github/copilot/settings.local.json`. |
9
9
  | Stuck after reset | Escalate model (cheap->standard->premium). Still stuck? Flag to user |
10
10
  | Auth error (401/403) | GitHub App: re-mint via `provision_vcs_auth`. Bitbucket/Azure DevOps: ask user for fresh token, provision, retry. See auth-*.md |
11
- | Token/password appears in command output | Use `credential_store_set` to store the secret, then reference it as `{{secure.NAME}}` in `execute_command` - Fleet redacts it to `[REDACTED:NAME]` before the LLM sees the output |
12
- | Need to rotate a credential without re-provisioning | Run `credential_store_delete name=<NAME>` then `credential_store_set name=<NAME>` - the new value is picked up immediately on the next `execute_command` that references `{{secure.NAME}}` |
11
+ | Token/password appears in command output | Use `credential_store_set` to store the secret, then reference it as `{{secret.NAME}}` in `execute_command` - Fleet redacts it to `[REDACTED:NAME]` before the LLM sees the output |
12
+ | Need to rotate a credential without re-provisioning | Run `credential_store_delete name=<NAME>` then `credential_store_set name=<NAME>` - the new value is picked up immediately on the next `execute_command` that references `{{secret.NAME}}` |
13
13
  | Tool execution issue (unexpected behavior, missing output, silent failure) | Check `APRA_FLEET_DATA_DIR/logs/fleet-<pid>.log` for detailed execution traces. Filter by member with `jq 'select(.member_id == "<uuid>")'` or by tool with `jq 'select(.tag == "<tool>")'`. See the **Fleet Logs** section in SKILL.md for full field reference and `jq` examples. |
14
+ | `bd dolt pull`/`push` fails with "merge conflicts in issues require operator resolution" | Real divergence, not corruption -- do NOT `bd init`/`bd init --from-jsonl`/delete `.beads/`. See `beads-conflict-resolution.md` for the manual dolt SQL recovery playbook. |