@apralabs/apra-fleet 0.4.0 → 0.4.1

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 (427) hide show
  1. package/README.md +145 -7
  2. package/dist/agents/backlog-groomer.md +17 -1
  3. package/dist/agents/ci-watcher.md +13 -1
  4. package/dist/agents/deployer.md +15 -3
  5. package/dist/agents/doer.md +35 -1
  6. package/dist/agents/harvester.md +22 -3
  7. package/dist/agents/integ-test-runner.md +18 -2
  8. package/dist/agents/kb-reconciler.md +216 -0
  9. package/dist/agents/plan-reviewer.md +14 -1
  10. package/dist/agents/planner.md +88 -5
  11. package/dist/agents/regression-test-runner.md +19 -1
  12. package/dist/agents/reviewer.md +104 -3
  13. package/dist/agents/schemas/doer-output.json +63 -3
  14. package/dist/agents/schemas/harvester-output.json +59 -2
  15. package/dist/agents/schemas/integ-test-runner-output.json +2 -2
  16. package/dist/agents/schemas/kb-reconciler-output.json +87 -0
  17. package/dist/agents/schemas/planner-output.json +65 -0
  18. package/dist/agents/schemas/reviewer-output.json +105 -8
  19. package/dist/cli/install.d.ts +1 -0
  20. package/dist/cli/install.d.ts.map +1 -1
  21. package/dist/cli/install.js +136 -5
  22. package/dist/cli/install.js.map +1 -1
  23. package/dist/cli/join.js +1 -1
  24. package/dist/cli/join.js.map +1 -1
  25. package/dist/cli/kb-commit.d.ts +12 -0
  26. package/dist/cli/kb-commit.d.ts.map +1 -0
  27. package/dist/cli/kb-commit.js +53 -0
  28. package/dist/cli/kb-commit.js.map +1 -0
  29. package/dist/cli/kb-directives.d.ts +17 -0
  30. package/dist/cli/kb-directives.d.ts.map +1 -0
  31. package/dist/cli/kb-directives.js +146 -0
  32. package/dist/cli/kb-directives.js.map +1 -0
  33. package/dist/cli/kb-import.d.ts +13 -0
  34. package/dist/cli/kb-import.d.ts.map +1 -0
  35. package/dist/cli/kb-import.js +56 -0
  36. package/dist/cli/kb-import.js.map +1 -0
  37. package/dist/cli/uninstall.d.ts.map +1 -1
  38. package/dist/cli/uninstall.js +11 -0
  39. package/dist/cli/uninstall.js.map +1 -1
  40. package/dist/cli/watch.d.ts +53 -4
  41. package/dist/cli/watch.d.ts.map +1 -1
  42. package/dist/cli/watch.js +118 -17
  43. package/dist/cli/watch.js.map +1 -1
  44. package/dist/commands/kb-server.d.ts +8 -0
  45. package/dist/commands/kb-server.d.ts.map +1 -0
  46. package/dist/commands/kb-server.js +221 -0
  47. package/dist/commands/kb-server.js.map +1 -0
  48. package/dist/index.js +77 -2
  49. package/dist/index.js.map +1 -1
  50. package/dist/os/linux.d.ts +1 -0
  51. package/dist/os/linux.d.ts.map +1 -1
  52. package/dist/os/linux.js +18 -1
  53. package/dist/os/linux.js.map +1 -1
  54. package/dist/os/os-commands.d.ts +5 -0
  55. package/dist/os/os-commands.d.ts.map +1 -1
  56. package/dist/os/windows.d.ts +35 -0
  57. package/dist/os/windows.d.ts.map +1 -1
  58. package/dist/os/windows.js +67 -31
  59. package/dist/os/windows.js.map +1 -1
  60. package/dist/providers/agy.d.ts +12 -1
  61. package/dist/providers/agy.d.ts.map +1 -1
  62. package/dist/providers/agy.js +134 -9
  63. package/dist/providers/agy.js.map +1 -1
  64. package/dist/providers/claude.d.ts +11 -1
  65. package/dist/providers/claude.d.ts.map +1 -1
  66. package/dist/providers/claude.js +47 -19
  67. package/dist/providers/claude.js.map +1 -1
  68. package/dist/providers/codex.d.ts +11 -1
  69. package/dist/providers/codex.d.ts.map +1 -1
  70. package/dist/providers/codex.js +29 -6
  71. package/dist/providers/codex.js.map +1 -1
  72. package/dist/providers/copilot.d.ts +11 -1
  73. package/dist/providers/copilot.d.ts.map +1 -1
  74. package/dist/providers/copilot.js +26 -6
  75. package/dist/providers/copilot.js.map +1 -1
  76. package/dist/providers/email/headers.d.ts +15 -0
  77. package/dist/providers/email/headers.d.ts.map +1 -0
  78. package/dist/providers/email/headers.js +42 -0
  79. package/dist/providers/email/headers.js.map +1 -0
  80. package/dist/providers/email/index.d.ts +18 -0
  81. package/dist/providers/email/index.d.ts.map +1 -0
  82. package/dist/providers/email/index.js +60 -0
  83. package/dist/providers/email/index.js.map +1 -0
  84. package/dist/providers/email/provider.d.ts +49 -0
  85. package/dist/providers/email/provider.d.ts.map +1 -0
  86. package/dist/providers/email/provider.js +2 -0
  87. package/dist/providers/email/provider.js.map +1 -0
  88. package/dist/providers/email/sendgrid.d.ts +12 -0
  89. package/dist/providers/email/sendgrid.d.ts.map +1 -0
  90. package/dist/providers/email/sendgrid.js +67 -0
  91. package/dist/providers/email/sendgrid.js.map +1 -0
  92. package/dist/providers/email/smtp.d.ts +65 -0
  93. package/dist/providers/email/smtp.d.ts.map +1 -0
  94. package/dist/providers/email/smtp.js +373 -0
  95. package/dist/providers/email/smtp.js.map +1 -0
  96. package/dist/providers/gemini.d.ts +11 -1
  97. package/dist/providers/gemini.d.ts.map +1 -1
  98. package/dist/providers/gemini.js +38 -4
  99. package/dist/providers/gemini.js.map +1 -1
  100. package/dist/providers/none.d.ts +11 -1
  101. package/dist/providers/none.d.ts.map +1 -1
  102. package/dist/providers/none.js +21 -0
  103. package/dist/providers/none.js.map +1 -1
  104. package/dist/providers/opencode.d.ts +11 -1
  105. package/dist/providers/opencode.d.ts.map +1 -1
  106. package/dist/providers/opencode.js +55 -4
  107. package/dist/providers/opencode.js.map +1 -1
  108. package/dist/providers/provider.d.ts +77 -0
  109. package/dist/providers/provider.d.ts.map +1 -1
  110. package/dist/providers/provider.js +44 -0
  111. package/dist/providers/provider.js.map +1 -1
  112. package/dist/services/agent-provisioner.d.ts.map +1 -1
  113. package/dist/services/agent-provisioner.js +3 -6
  114. package/dist/services/agent-provisioner.js.map +1 -1
  115. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  116. package/dist/services/cloud/lifecycle.js +3 -0
  117. package/dist/services/cloud/lifecycle.js.map +1 -1
  118. package/dist/services/cloud/task-wrapper.d.ts +18 -0
  119. package/dist/services/cloud/task-wrapper.d.ts.map +1 -1
  120. package/dist/services/cloud/task-wrapper.js +157 -0
  121. package/dist/services/cloud/task-wrapper.js.map +1 -1
  122. package/dist/services/github-app.d.ts.map +1 -1
  123. package/dist/services/github-app.js +11 -2
  124. package/dist/services/github-app.js.map +1 -1
  125. package/dist/services/knowledge/audn.d.ts +37 -0
  126. package/dist/services/knowledge/audn.d.ts.map +1 -0
  127. package/dist/services/knowledge/audn.js +219 -0
  128. package/dist/services/knowledge/audn.js.map +1 -0
  129. package/dist/services/knowledge/file-hash.d.ts +11 -0
  130. package/dist/services/knowledge/file-hash.d.ts.map +1 -0
  131. package/dist/services/knowledge/file-hash.js +123 -0
  132. package/dist/services/knowledge/file-hash.js.map +1 -0
  133. package/dist/services/knowledge/http-provider.d.ts +46 -0
  134. package/dist/services/knowledge/http-provider.d.ts.map +1 -0
  135. package/dist/services/knowledge/http-provider.js +254 -0
  136. package/dist/services/knowledge/http-provider.js.map +1 -0
  137. package/dist/services/knowledge/kb-providers.d.ts +15 -0
  138. package/dist/services/knowledge/kb-providers.d.ts.map +1 -0
  139. package/dist/services/knowledge/kb-providers.js +92 -0
  140. package/dist/services/knowledge/kb-providers.js.map +1 -0
  141. package/dist/services/knowledge/kb-scope-input.d.ts +5 -0
  142. package/dist/services/knowledge/kb-scope-input.d.ts.map +1 -0
  143. package/dist/services/knowledge/kb-scope-input.js +11 -0
  144. package/dist/services/knowledge/kb-scope-input.js.map +1 -0
  145. package/dist/services/knowledge/kb-service.d.ts +3 -0
  146. package/dist/services/knowledge/kb-service.d.ts.map +1 -0
  147. package/dist/services/knowledge/kb-service.js +2 -0
  148. package/dist/services/knowledge/kb-service.js.map +1 -0
  149. package/dist/services/knowledge/path-validation.d.ts +2 -0
  150. package/dist/services/knowledge/path-validation.d.ts.map +1 -0
  151. package/dist/services/knowledge/path-validation.js +13 -0
  152. package/dist/services/knowledge/path-validation.js.map +1 -0
  153. package/dist/services/knowledge/pre-init.d.ts +14 -0
  154. package/dist/services/knowledge/pre-init.d.ts.map +1 -0
  155. package/dist/services/knowledge/pre-init.js +147 -0
  156. package/dist/services/knowledge/pre-init.js.map +1 -0
  157. package/dist/services/knowledge/project-slug.d.ts +2 -0
  158. package/dist/services/knowledge/project-slug.d.ts.map +1 -0
  159. package/dist/services/knowledge/project-slug.js +49 -0
  160. package/dist/services/knowledge/project-slug.js.map +1 -0
  161. package/dist/services/knowledge/sqlite-provider.d.ts +147 -0
  162. package/dist/services/knowledge/sqlite-provider.d.ts.map +1 -0
  163. package/dist/services/knowledge/sqlite-provider.js +1646 -0
  164. package/dist/services/knowledge/sqlite-provider.js.map +1 -0
  165. package/dist/services/knowledge/types.d.ts +163 -0
  166. package/dist/services/knowledge/types.d.ts.map +1 -0
  167. package/dist/services/knowledge/types.js +9 -0
  168. package/dist/services/knowledge/types.js.map +1 -0
  169. package/dist/services/member-home.d.ts +89 -0
  170. package/dist/services/member-home.d.ts.map +1 -0
  171. package/dist/services/member-home.js +256 -0
  172. package/dist/services/member-home.js.map +1 -0
  173. package/dist/services/member-remote-url.d.ts +34 -0
  174. package/dist/services/member-remote-url.d.ts.map +1 -0
  175. package/dist/services/member-remote-url.js +39 -0
  176. package/dist/services/member-remote-url.js.map +1 -0
  177. package/dist/services/orphan-recovery.d.ts +5 -2
  178. package/dist/services/orphan-recovery.d.ts.map +1 -1
  179. package/dist/services/orphan-recovery.js +19 -8
  180. package/dist/services/orphan-recovery.js.map +1 -1
  181. package/dist/services/preflight-check.d.ts +56 -0
  182. package/dist/services/preflight-check.d.ts.map +1 -0
  183. package/dist/services/preflight-check.js +277 -0
  184. package/dist/services/preflight-check.js.map +1 -0
  185. package/dist/services/stall/log-path-resolver.d.ts +11 -8
  186. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  187. package/dist/services/stall/log-path-resolver.js +17 -40
  188. package/dist/services/stall/log-path-resolver.js.map +1 -1
  189. package/dist/services/stall/stall-detector.d.ts +32 -0
  190. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  191. package/dist/services/stall/stall-detector.js +149 -6
  192. package/dist/services/stall/stall-detector.js.map +1 -1
  193. package/dist/services/stall/stall-poller.d.ts +34 -0
  194. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  195. package/dist/services/stall/stall-poller.js +134 -2
  196. package/dist/services/stall/stall-poller.js.map +1 -1
  197. package/dist/services/strategy.d.ts.map +1 -1
  198. package/dist/services/strategy.js +2 -2
  199. package/dist/services/strategy.js.map +1 -1
  200. package/dist/services/tool-registry.d.ts.map +1 -1
  201. package/dist/services/tool-registry.js +87 -1
  202. package/dist/services/tool-registry.js.map +1 -1
  203. package/dist/services/vcs/github.d.ts.map +1 -1
  204. package/dist/services/vcs/github.js +32 -1
  205. package/dist/services/vcs/github.js.map +1 -1
  206. package/dist/services/version-check.d.ts +22 -0
  207. package/dist/services/version-check.d.ts.map +1 -0
  208. package/dist/services/version-check.js +103 -0
  209. package/dist/services/version-check.js.map +1 -0
  210. package/dist/skills/fleet-sprint-cli/SKILL.md +13 -2
  211. package/dist/skills/pm/beads.md +6 -0
  212. package/dist/skills/pm/fleet-addendum.md +6 -0
  213. package/dist/skills/pm/index.md +56 -0
  214. package/dist/skills/pm/kb-reconcile.md +132 -0
  215. package/dist/skills/pm/kb-review.md +109 -0
  216. package/dist/tools/check-status.d.ts +47 -0
  217. package/dist/tools/check-status.d.ts.map +1 -1
  218. package/dist/tools/check-status.js +242 -0
  219. package/dist/tools/check-status.js.map +1 -1
  220. package/dist/tools/child-id-allocator.d.ts +2 -2
  221. package/dist/tools/code-intelligence-codebase-memory.d.ts +11 -0
  222. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +1 -0
  223. package/dist/tools/code-intelligence-codebase-memory.js +270 -0
  224. package/dist/tools/code-intelligence-codebase-memory.js.map +1 -0
  225. package/dist/tools/code-intelligence-freshness.d.ts +2 -0
  226. package/dist/tools/code-intelligence-freshness.d.ts.map +1 -0
  227. package/dist/tools/code-intelligence-freshness.js +26 -0
  228. package/dist/tools/code-intelligence-freshness.js.map +1 -0
  229. package/dist/tools/code-intelligence-gitnexus.d.ts +14 -0
  230. package/dist/tools/code-intelligence-gitnexus.d.ts.map +1 -0
  231. package/dist/tools/code-intelligence-gitnexus.js +475 -0
  232. package/dist/tools/code-intelligence-gitnexus.js.map +1 -0
  233. package/dist/tools/code-intelligence-kb-enrich.d.ts +2 -0
  234. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +1 -0
  235. package/dist/tools/code-intelligence-kb-enrich.js +65 -0
  236. package/dist/tools/code-intelligence-kb-enrich.js.map +1 -0
  237. package/dist/tools/code-intelligence-reindex.d.ts +7 -0
  238. package/dist/tools/code-intelligence-reindex.d.ts.map +1 -0
  239. package/dist/tools/code-intelligence-reindex.js +106 -0
  240. package/dist/tools/code-intelligence-reindex.js.map +1 -0
  241. package/dist/tools/code-intelligence-telemetry.d.ts +5 -0
  242. package/dist/tools/code-intelligence-telemetry.d.ts.map +1 -0
  243. package/dist/tools/code-intelligence-telemetry.js +52 -0
  244. package/dist/tools/code-intelligence-telemetry.js.map +1 -0
  245. package/dist/tools/code-intelligence-tests.d.ts +2 -0
  246. package/dist/tools/code-intelligence-tests.d.ts.map +1 -0
  247. package/dist/tools/code-intelligence-tests.js +24 -0
  248. package/dist/tools/code-intelligence-tests.js.map +1 -0
  249. package/dist/tools/code-intelligence.d.ts +114 -0
  250. package/dist/tools/code-intelligence.d.ts.map +1 -0
  251. package/dist/tools/code-intelligence.js +124 -0
  252. package/dist/tools/code-intelligence.js.map +1 -0
  253. package/dist/tools/compose-permissions.d.ts +26 -0
  254. package/dist/tools/compose-permissions.d.ts.map +1 -1
  255. package/dist/tools/compose-permissions.js +244 -33
  256. package/dist/tools/compose-permissions.js.map +1 -1
  257. package/dist/tools/execute-command.d.ts +2 -0
  258. package/dist/tools/execute-command.d.ts.map +1 -1
  259. package/dist/tools/execute-command.js +86 -16
  260. package/dist/tools/execute-command.js.map +1 -1
  261. package/dist/tools/execute-prompt.d.ts +13 -1
  262. package/dist/tools/execute-prompt.d.ts.map +1 -1
  263. package/dist/tools/execute-prompt.js +257 -45
  264. package/dist/tools/execute-prompt.js.map +1 -1
  265. package/dist/tools/kb-capture.d.ts +53 -0
  266. package/dist/tools/kb-capture.d.ts.map +1 -0
  267. package/dist/tools/kb-capture.js +130 -0
  268. package/dist/tools/kb-capture.js.map +1 -0
  269. package/dist/tools/kb-context.d.ts +17 -0
  270. package/dist/tools/kb-context.d.ts.map +1 -0
  271. package/dist/tools/kb-context.js +29 -0
  272. package/dist/tools/kb-context.js.map +1 -0
  273. package/dist/tools/kb-export.d.ts +19 -0
  274. package/dist/tools/kb-export.d.ts.map +1 -0
  275. package/dist/tools/kb-export.js +344 -0
  276. package/dist/tools/kb-export.js.map +1 -0
  277. package/dist/tools/kb-feedback.d.ts +23 -0
  278. package/dist/tools/kb-feedback.d.ts.map +1 -0
  279. package/dist/tools/kb-feedback.js +43 -0
  280. package/dist/tools/kb-feedback.js.map +1 -0
  281. package/dist/tools/kb-freshness-sweep.d.ts +14 -0
  282. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -0
  283. package/dist/tools/kb-freshness-sweep.js +29 -0
  284. package/dist/tools/kb-freshness-sweep.js.map +1 -0
  285. package/dist/tools/kb-harvest.d.ts +20 -0
  286. package/dist/tools/kb-harvest.d.ts.map +1 -0
  287. package/dist/tools/kb-harvest.js +143 -0
  288. package/dist/tools/kb-harvest.js.map +1 -0
  289. package/dist/tools/kb-import.d.ts +44 -0
  290. package/dist/tools/kb-import.d.ts.map +1 -0
  291. package/dist/tools/kb-import.js +239 -0
  292. package/dist/tools/kb-import.js.map +1 -0
  293. package/dist/tools/kb-invalidate.d.ts +19 -0
  294. package/dist/tools/kb-invalidate.d.ts.map +1 -0
  295. package/dist/tools/kb-invalidate.js +34 -0
  296. package/dist/tools/kb-invalidate.js.map +1 -0
  297. package/dist/tools/kb-list.d.ts +32 -0
  298. package/dist/tools/kb-list.d.ts.map +1 -0
  299. package/dist/tools/kb-list.js +43 -0
  300. package/dist/tools/kb-list.js.map +1 -0
  301. package/dist/tools/kb-promote.d.ts +20 -0
  302. package/dist/tools/kb-promote.d.ts.map +1 -0
  303. package/dist/tools/kb-promote.js +20 -0
  304. package/dist/tools/kb-promote.js.map +1 -0
  305. package/dist/tools/kb-query.d.ts +35 -0
  306. package/dist/tools/kb-query.d.ts.map +1 -0
  307. package/dist/tools/kb-query.js +111 -0
  308. package/dist/tools/kb-query.js.map +1 -0
  309. package/dist/tools/kb-reconcile-prefilter.d.ts +14 -0
  310. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -0
  311. package/dist/tools/kb-reconcile-prefilter.js +26 -0
  312. package/dist/tools/kb-reconcile-prefilter.js.map +1 -0
  313. package/dist/tools/kb-resolve-contradiction.d.ts +23 -0
  314. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -0
  315. package/dist/tools/kb-resolve-contradiction.js +37 -0
  316. package/dist/tools/kb-resolve-contradiction.js.map +1 -0
  317. package/dist/tools/kb-session-prime.d.ts +26 -0
  318. package/dist/tools/kb-session-prime.d.ts.map +1 -0
  319. package/dist/tools/kb-session-prime.js +392 -0
  320. package/dist/tools/kb-session-prime.js.map +1 -0
  321. package/dist/tools/kb-setup.d.ts +20 -0
  322. package/dist/tools/kb-setup.d.ts.map +1 -0
  323. package/dist/tools/kb-setup.js +49 -0
  324. package/dist/tools/kb-setup.js.map +1 -0
  325. package/dist/tools/kb-stats.d.ts +20 -0
  326. package/dist/tools/kb-stats.d.ts.map +1 -0
  327. package/dist/tools/kb-stats.js +115 -0
  328. package/dist/tools/kb-stats.js.map +1 -0
  329. package/dist/tools/member-detail.d.ts.map +1 -1
  330. package/dist/tools/member-detail.js +8 -0
  331. package/dist/tools/member-detail.js.map +1 -1
  332. package/dist/tools/monitor-task.d.ts.map +1 -1
  333. package/dist/tools/monitor-task.js +21 -3
  334. package/dist/tools/monitor-task.js.map +1 -1
  335. package/dist/tools/provision-auth.d.ts.map +1 -1
  336. package/dist/tools/provision-auth.js +10 -3
  337. package/dist/tools/provision-auth.js.map +1 -1
  338. package/dist/tools/register-member.d.ts +3 -0
  339. package/dist/tools/register-member.d.ts.map +1 -1
  340. package/dist/tools/register-member.js +30 -1
  341. package/dist/tools/register-member.js.map +1 -1
  342. package/dist/tools/remove-member.d.ts.map +1 -1
  343. package/dist/tools/remove-member.js +17 -3
  344. package/dist/tools/remove-member.js.map +1 -1
  345. package/dist/tools/report-status.d.ts.map +1 -1
  346. package/dist/tools/report-status.js +2 -1
  347. package/dist/tools/report-status.js.map +1 -1
  348. package/dist/tools/send-email.d.ts +69 -0
  349. package/dist/tools/send-email.d.ts.map +1 -0
  350. package/dist/tools/send-email.js +177 -0
  351. package/dist/tools/send-email.js.map +1 -0
  352. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  353. package/dist/tools/setup-ssh-key.js +2 -0
  354. package/dist/tools/setup-ssh-key.js.map +1 -1
  355. package/dist/tools/update-member.d.ts +3 -0
  356. package/dist/tools/update-member.d.ts.map +1 -1
  357. package/dist/tools/update-member.js +25 -1
  358. package/dist/tools/update-member.js.map +1 -1
  359. package/dist/types.d.ts +1 -0
  360. package/dist/types.d.ts.map +1 -1
  361. package/dist/utils/prompt-errors.js +1 -1
  362. package/dist/utils/prompt-errors.js.map +1 -1
  363. package/dist/utils/session-caller.d.ts +28 -0
  364. package/dist/utils/session-caller.d.ts.map +1 -0
  365. package/dist/utils/session-caller.js +24 -0
  366. package/dist/utils/session-caller.js.map +1 -0
  367. package/dist/utils/work-folder-validation.d.ts +39 -0
  368. package/dist/utils/work-folder-validation.d.ts.map +1 -0
  369. package/dist/utils/work-folder-validation.js +60 -0
  370. package/dist/utils/work-folder-validation.js.map +1 -0
  371. package/dist/workflows/auto-sprint.js +546 -6
  372. package/package.json +7 -4
  373. package/packages/apra-fleet-client/src/client/api.mjs +118 -4
  374. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +17 -1
  375. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +13 -1
  376. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +15 -3
  377. package/packages/apra-fleet-se/apra-pm/agents/doer.md +35 -1
  378. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +22 -3
  379. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +18 -2
  380. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +216 -0
  381. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +14 -1
  382. package/packages/apra-fleet-se/apra-pm/agents/planner.md +88 -5
  383. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +19 -1
  384. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +104 -3
  385. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +63 -3
  386. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +59 -2
  387. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +2 -2
  388. package/packages/apra-fleet-se/apra-pm/agents/schemas/kb-reconciler-output.json +87 -0
  389. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +65 -0
  390. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +105 -8
  391. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +6 -0
  392. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +6 -0
  393. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +56 -0
  394. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +132 -0
  395. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +109 -0
  396. package/packages/apra-fleet-se/bin/cli.mjs +7 -0
  397. package/packages/apra-fleet-se/bin/serve.mjs +14 -2
  398. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +31 -5
  399. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +1 -1
  400. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +23 -151
  401. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +256 -0
  402. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +1482 -0
  403. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +908 -0
  404. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +399 -0
  405. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +972 -0
  406. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +167 -101
  407. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +50 -6
  408. package/packages/apra-fleet-se/fleet-sprint/runner.js +1416 -116
  409. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +13 -2
  410. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +350 -0
  411. package/packages/apra-fleet-se/fleet-sprint/sprint-progress.mjs +101 -0
  412. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +30 -17
  413. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +62 -2
  414. package/packages/apra-fleet-se/package.json +1 -0
  415. package/packages/apra-fleet-workflow/src/viewer/index.mjs +127 -13
  416. package/packages/apra-fleet-workflow/src/viewer/run-title.mjs +60 -0
  417. package/packages/apra-fleet-workflow/src/workflow/index.mjs +8 -4
  418. package/skills/fleet/knowledge-agent.md +66 -0
  419. package/skills/fleet/permissions.md +28 -4
  420. package/skills/fleet/profiles/base-dev.json +10 -1
  421. package/skills/fleet/profiles/base-reviewer.json +8 -1
  422. package/skills/fleet/profiles/tag-kb-reconciler.json +20 -0
  423. package/version.json +1 -1
  424. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +0 -127
  425. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +0 -339
  426. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +0 -360
  427. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +0 -363
@@ -0,0 +1,109 @@
1
+ # /pm kb-review
2
+
3
+ Surface all contradiction-flagged KB entries and resolve them interactively.
4
+
5
+ Note: `/pm kb-review` also surfaces pending `user-directive` proposals (via
6
+ `kb_query({ flagged_only: true })`) and instructs the human to run
7
+ `apra-fleet kb approve-directive <id>` or `reject-directive <id>` -- these are
8
+ CLI-only resolutions, never `kb_promote`.
9
+
10
+ ## When to run
11
+
12
+ - After any sprint completes, as part of KB hygiene.
13
+ - When an agent reports a `flagged` audn_decision from `kb_capture`.
14
+ - Periodically, to keep the KB free of unresolved contradictions.
15
+
16
+ ## Steps
17
+
18
+ ### Step 1: Fetch flagged entries
19
+
20
+ Call `kb_query(flagged_only=true)`.
21
+
22
+ - If the response says "No flagged contradictions found -- KB is clean.", report that to the user and stop.
23
+ - Otherwise, collect all returned entries.
24
+
25
+ ### Step 2: Group into contradiction pairs
26
+
27
+ For each entry with `contradiction_of` set, pair it with the entry whose `id` matches `contradiction_of`.
28
+ Entries with `flagged_for_review=true` and no `contradiction_of` are the original (challenged) entries.
29
+
30
+ Group: `{ original: entry_A, challenger: entry_B }` where `entry_B.contradiction_of = entry_A.id`.
31
+
32
+ ### Step 3: Present each pair to the user
33
+
34
+ For each pair, show:
35
+
36
+ ```
37
+ Contradiction pair (N of M):
38
+
39
+ [ORIGINAL] id: <id> confidence: <confidence> created: <created_at>
40
+ Title: <title>
41
+ Summary: <summary>
42
+ Content: <content>
43
+
44
+ [CHALLENGER] id: <id> confidence: <confidence> created: <created_at>
45
+ Title: <title>
46
+ Summary: <summary>
47
+ Content: <content>
48
+
49
+ Resolution options:
50
+ A - Keep original, discard challenger
51
+ B - Keep challenger, discard original
52
+ M - Merge both into a new entry (you provide merged content)
53
+ D - Delete both (neither is correct)
54
+ S - Skip (defer to later)
55
+ ```
56
+
57
+ Wait for the user's response before proceeding to the next pair.
58
+
59
+ ### Step 4: Apply resolution
60
+
61
+ Supersede is OPT-IN: you must name the entry you are retiring via
62
+ `supersedes=<id>`. It is honored only when AUDN independently matches that same
63
+ entry (same type, overlapping symbols and source_files), so the corrective
64
+ capture must still carry the SAME title/symbols/source_files as its target --
65
+ otherwise nothing is retired and you get a second live entry instead. A capture
66
+ without `supersedes` never retires anything.
67
+
68
+ **A -- Keep original:**
69
+ - `kb_promote(original.id, reason="contradiction resolved: original kept")` -- upgrades its confidence.
70
+ - `kb_capture` a new entry with the SAME title/symbols/source_files as the challenger, corrected content that carries no contradiction keyword or polarity word (or AUDN will flag it again instead of updating), `confidence=UNVERIFIED`, and `supersedes=<challenger.id>`. That retires the challenger.
71
+
72
+ **B -- Keep challenger:**
73
+ - `kb_promote(challenger.id, reason="contradiction resolved: challenger kept")`.
74
+ - `kb_capture` a corrected entry with the SAME title/symbols/source_files as the original, corrected content free of contradiction/polarity words, and `supersedes=<original.id>`. That retires the original.
75
+
76
+ **M -- Merge:**
77
+ - Ask the user to provide the merged content.
78
+ - `kb_capture` a new entry with merged content and `supersedes=<id of whichever entry it replaces>`. Repeat for the second entry if both must be retired -- `supersedes` names ONE entry, so retiring both takes two captures.
79
+ - `kb_promote` the newly captured entry id.
80
+
81
+ **D -- Delete both:**
82
+ - `kb_capture` a retraction entry: `title=<original title>`, `content="Retracted: neither entry describes current behavior."` (no contradiction keyword or polarity word, or AUDN will flag it again instead of updating), `confidence=UNVERIFIED`, `supersedes=<original.id>`.
83
+ - `kb_capture` same for the challenger, with `supersedes=<challenger.id>`.
84
+
85
+ **S -- Skip:**
86
+ - No action. Note it in the session summary.
87
+
88
+ **Verified actual behavior (T3.7, F11 e2e proof) -- read this before reporting "resolved":**
89
+ - Superseding an entry (via the corrective `kb_capture` above with `supersedes` set, AUDN decision `update`) sets its `superseded_at` and `stale=1`. That entry then drops out of every future `kb_query({flagged_only:true})` listing -- the tool always excludes superseded entries.
90
+ - `kb_promote` does **NOT** clear `flagged_for_review` and does **NOT** clear `contradiction_of`. This means the entry you KEPT (promoted, not superseded) stays visible in `kb_query({flagged_only:true})` forever -- it is not automatically delisted just because it was resolved. Do not expect the pair to fully disappear from the flagged list; expect only the superseded side to disappear. Recognize an already-resolved pair by its counterpart's absence (or by checking `promoted_at`/`confidence` on the id you kept), not by the pair vanishing entirely.
91
+ - A `kb_feedback`-downvoted entry (`stale=1` + `flagged_for_review=1`, never superseded) stays listed under `flagged_only` until it is separately resolved the same way -- superseded via a corrective capture, or otherwise retired. Simply promoting a *different* entry never clears it.
92
+
93
+ ### Step 5: Report
94
+
95
+ After all pairs are processed, report:
96
+
97
+ ```
98
+ KB Review complete.
99
+ - Pairs resolved: N
100
+ - Pairs skipped: M
101
+ - Total flagged entries cleared: K
102
+ ```
103
+
104
+ "Cleared" here means the SUPERSEDED side of each resolved pair (the one whose
105
+ `superseded_at` got set) -- per the verified behavior in Step 4, the kept/
106
+ promoted side of a resolved pair remains in `kb_query({flagged_only:true})`
107
+ indefinitely, so K is normally N, not 2N. Do not report a pair as fully gone
108
+ from the flagged list; report it as resolved (one side superseded, the other
109
+ promoted).
@@ -690,6 +690,13 @@ async function main() {
690
690
  // explicitly rather than picking up the new core defaults.
691
691
  stateSnapshotDir: 'sprint-logs',
692
692
  stateSnapshotPrefix: 'sprint_',
693
+ // apra-fleet-dm5.2: publish the fields buildRunTitle() (apra-fleet-
694
+ // dm5.1) reads off state.args so the viewer header shows
695
+ // "<members> working <targetIssues> (<goal>)" instead of just the
696
+ // workflow name for a fleet-sprint run. Purely additive -- the core
697
+ // viewer's state.args stays optional/null for any other workflow
698
+ // that doesn't pass launchArgs, and no existing state key changes.
699
+ launchArgs: { members: validMembers, targetIssues, goal },
693
700
  });
694
701
 
695
702
  // apra-fleet-unw2.16, N14 (e): the viewer port was hardcoded with no
@@ -46,7 +46,8 @@ import { createBacklog, registerBacklogRoutes } from '../src/supervisor/backlog.
46
46
  import { createDashboard, registerDashboardRoutes } from '../src/supervisor/dashboard.mjs';
47
47
  import { createSprintController, registerSprintRoutes, defaultMemberOverlapGuard, ApiError } from '../src/supervisor/api.mjs';
48
48
  import { createScopeGuard, formatScopeConflict } from '../src/supervisor/scope-overlap.mjs';
49
- import { listFleetMembers } from '../src/supervisor/fleet-members.mjs';
49
+ import { listFleetMembers, executeFleetCommand } from '../src/supervisor/fleet-members.mjs';
50
+ import { createDoltOrphanSweep } from '../src/supervisor/dolt-orphan-sweep.mjs';
50
51
  import { resolveFleetServerConnection } from './cli.mjs';
51
52
 
52
53
  const SERVE_USAGE = `
@@ -252,7 +253,18 @@ export async function serveMain(argv = process.argv.slice(2)) {
252
253
  // above for why no separate launch-form seam is constructed here).
253
254
  const dashboard = createDashboard({ ledger, watchdog, backlog });
254
255
 
255
- const supervisor = createSupervisor({ port, ledger, spawner, watchdog, dashboard, idAllocator, doltMutex });
256
+ // docs/dolt-sync-redesign.md Part 3.3: kill any orphaned ephemeral
257
+ // `dolt sql-server` a mid-settle orchestrator death left behind on a
258
+ // member (settle's own finally covers every other path). Both
259
+ // collaborators use the same short-lived-MCP-connection pattern as
260
+ // listFleetMembers -- the supervisor never holds a standing fleet
261
+ // transport.
262
+ const doltOrphanSweep = createDoltOrphanSweep({
263
+ listMembers: () => listFleetMembers({ resolveConnection: resolveFleetServerConnection }),
264
+ execCommand: ({ member, command }) => executeFleetCommand({ member, command, resolveConnection: resolveFleetServerConnection }),
265
+ });
266
+
267
+ const supervisor = createSupervisor({ port, ledger, spawner, watchdog, dashboard, idAllocator, doltMutex, doltOrphanSweep });
256
268
  registerIdAllocatorRoutes(supervisor, idAllocator, { readJsonBody, sendJson });
257
269
  registerDoltMutexRoutes(supervisor, doltMutex, { readJsonBody, sendJson });
258
270
 
@@ -265,11 +265,18 @@ export function assertVersionPin(role, schema, expectedMajor) {
265
265
  // signal for this second case.
266
266
  //
267
267
  // Roles allow-listed here are exempt because they legitimately have no
268
- // output schema file, by design (not by omission):
269
- // - "planner": per the layering proposal, the planner's "output" IS the
270
- // beads DAG it creates, not a structured verdict object -- there is no
271
- // corresponding agents/schemas/planner-output.json anywhere, ever.
272
- export const ROLES_WITHOUT_OUTPUT_SCHEMA = Object.freeze(new Set(['planner']));
268
+ // output schema file, by design (not by omission).
269
+ //
270
+ // EMPTY as of 2026-08-03. "planner" used to be listed here on the layering
271
+ // proposal's reasoning that the planner's output IS the beads DAG it creates,
272
+ // not a structured verdict object. The KB trust pipeline supersedes that: its
273
+ // Capture-roles decision accepts kb_captures from doer, reviewer, planner and
274
+ // harvester, and a role can only return a field the engine reads if it has an
275
+ // output contract to carry it. agents/schemas/planner-output.json now exists,
276
+ // so the planner is no longer schema-less and a MISSING planner-output.json is
277
+ // once again a real defect worth warning about.
278
+ // See docs/superpowers/specs/2026-08-03-kb-trust-pipeline-design.md, Phase 2.
279
+ export const ROLES_WITHOUT_OUTPUT_SCHEMA = Object.freeze(new Set([]));
273
280
 
274
281
  /**
275
282
  * Emits a loud console.warn when `resolveSchemasDir()`'s resolved directory
@@ -614,6 +621,25 @@ export const finalVerdict = {
614
621
  required: ['id', 'reason'],
615
622
  },
616
623
  },
624
+ // apra-fleet-nx7: the Final Review may promote KB entries, exactly as a
625
+ // per-round review can. Without this field the final reviewer -- the one
626
+ // role that has read the whole diff and run the full suite, i.e. the
627
+ // strongest evidence any promoter ever holds -- had no way to return a
628
+ // promotion decision, so knowledge captured in a sprint's last round was
629
+ // stranded at INFERRED with nobody left to verify it. Same {id, reason}
630
+ // shape as reviewer-output.json's kb_promotions, executed by the same
631
+ // kbWork.apply path. Optional: promoting nothing is the common answer.
632
+ kb_promotions: {
633
+ type: 'array',
634
+ items: {
635
+ type: 'object',
636
+ properties: {
637
+ id: { type: 'string' },
638
+ reason: { type: 'string' },
639
+ },
640
+ required: ['id', 'reason'],
641
+ },
642
+ },
617
643
  },
618
644
  required: ['verdict', 'notes'],
619
645
  };
@@ -90,7 +90,7 @@ Watch progress there rather than tailing raw stdout.
90
90
  | `--role-map <json\|@file>` | | no | -- | JSON object mapping role -> member[], e.g. `'{"doer":["m1","m2"]}'`. Inline JSON or `@path/to/file.json`. |
91
91
  | `--viewer-port <port>` | | no | `8080` | Port for the local dashboard viewer. |
92
92
  | `--budget <usd>` | | no | unlimited | USD ceiling for this run's total estimated spend. |
93
- | `--dispatch-timeout-s <s>` | | no | `3600` | Per-dispatch time budget in seconds, applied as both the inactivity timeout and the hard ceiling on every agent dispatch (integ-test dispatch ceiling is 2x). Minimum 60. Lower it for small sprints so a hung dispatch costs minutes, not an hour. |
93
+ | `--dispatch-timeout-s <s>` | | no | `9000` | Per-dispatch time budget in seconds, applied as both the inactivity timeout and the hard ceiling on every agent dispatch (integ-test dispatch ceiling is 2x, regression-test ceiling is 3x). Minimum 60. Lower it for small sprints so a hung dispatch costs minutes, not 2.5 hours. |
94
94
  | `--sync` | | no | off | Synced topology mode (orchestrator-bracketed git sync): members may sit on differing HEADs but must share the same origin URL and pass a `bd dolt pull` probe. Omitted uses shared-workspace mode (all members on the same HEAD). |
95
95
  | `--help` | `-h` | | | Show the engine's help. |
96
96
 
@@ -1,151 +1,23 @@
1
- # Coach Role: Just-in-Time Error Resolution (design note)
2
-
3
- Status: IN DESIGN (user idea 2026-07-20; scope and consent model refined
4
- same day; explicitly NOT being operationalized yet -- "let's design more
5
- before we operationalize"). Recorded here so the design survives context
6
- loss. Update in place as design decisions land.
7
-
8
- ## The idea (user's own framing)
9
-
10
- Insert a "coach" role INSIDE the auto-sprint workflow -- an LLM agent that
11
- knows the fleet -> workflow -> auto-sprint technology stack and can address
12
- classes of errors that are UNFORESEEN by the deterministic engine, just in
13
- time. Every time it intervenes it (a) collects the important aspects of the
14
- sprint context and (b) produces a bug report describing the problem AND how
15
- it was resolved -- feeding field telemetry, future releases, and giving
16
- users a way to progress instead of wedging. It institutionalizes, inside
17
- the workflow, the stabilization-observer role a human+agent pair played
18
- from outside during the eft dogfood runs.
19
-
20
- ## Scope (REFINED): any red state, not just sync failures
21
-
22
- The coach's jurisdiction is ANY event that leaves the sprint in a red
23
- state, strictly AFTER existing deterministic handling has been exhausted.
24
- The error-handling hierarchy is three layers, in order:
25
-
26
- 1. **Typed handlers and ladders (deterministic, free).** errors.mjs typed
27
- errors, turn-exhaustion resume ladders, Tier-2 conflict resolution,
28
- busy-lock retries. The coach NEVER preempts these.
29
- 2. **Coach (JIT judgment, tokens).** Invoked only when layer 1 has no
30
- match or its handling failed -- the unforeseen complement.
31
- 3. **Fail loudly (existing behavior).** If the coach cannot resolve (or
32
- its per-class/per-run caps are hit), the normal failure path proceeds
33
- unchanged. The coach never suppresses a failure it could not fix.
34
-
35
- Red-state interception points (initial taxonomy, extend as discovered):
36
- - Streak failure after doer dispatch/resume ladder exhaustion
37
- - Dispatch errors with unrecognized reason (api_error, empty_response,
38
- transport failures) after existing retries
39
- - Sync bracket failures (G-push/G-pull/D-push/D-pull) after Tier-2
40
- - Phase-level failures: deploy failed, integ runner crashed, harvester
41
- failed
42
- - Reviewer/planner contract violations after their built-in retry
43
- - Stall detection firing; state corruption detected; member unreachable;
44
- auth expiry mid-run
45
- - Workflow-level abort paths (as evidence collector even when
46
- unresolvable)
47
-
48
- ## Guardrails: coach.md carries them ALL (REFINED)
49
-
50
- The contract file (agents/coach.md, upstream in apra-pm) is the single
51
- home of every guardrail -- not scattered through engine code -- so the
52
- guardrails ship with the role definition, version together, and appear in
53
- every dispatch. Engine-side caps are enforcement backstops of the same
54
- rules, never the only statement of them.
55
-
56
- Guardrail set (all load-bearing):
57
- - ACTION ALLOWLIST only: stash/commit WIP to a rescue branch, clear a
58
- leaked lock, retry a push, restart a dead session, re-run an idempotent
59
- step. Hard prohibitions: never force-push, never delete branches/files,
60
- never mutate bead verdicts or close beads, never edit code content,
61
- never act outside the member's working tree, never install software.
62
- - SINGLE-SHOT: one intervention attempt per red event; then report and
63
- fall back. The coach is never coached (no recursion).
64
- - SAME-CLASS-TWICE POLICY: an error class (by fingerprint) may be coached
65
- at most N times per run (N=2 initial); after that it must fail loudly
66
- and demand an engine fix. Healing is a bridge, never a home.
67
- - EVERY INTERVENTION FILES A REPORT -- no silent saves. Interventions are
68
- first-class events in sprint state and appear in final-review evidence
69
- (a PASS with 12 coach saves reads differently from a clean PASS).
70
- - TARGET-AGNOSTIC: the coach knows the fleet/workflow/auto-sprint STACK,
71
- never the target repo's specifics (product-vs-dogfood rule).
72
- - TOKEN DISCIPLINE: invoked only at layer 2 (rare by construction);
73
- per-run invocation cap; premium tier acceptable given rarity.
74
- - REPRODUCIBILITY: interventions recorded in replayable form; mock/golden
75
- tests stub coach outcomes deterministically.
76
-
77
- ## Bug reports and consent (REFINED): sanitize, then ask -- or standing consent
78
-
79
- The coach always produces a SANITIZED, ANONYMIZED report locally. Whether
80
- it leaves the machine is a separate, consent-gated step:
81
-
82
- - Modes (fleet config, e.g. coach.telemetry): "never" | "ask" (default) |
83
- "always".
84
- - **ask (default)**: report saved under sprint-logs/coach-reports/; the
85
- user is asked to consent AFTER THE FACT -- at sprint end (PR body /
86
- dashboard / CLI summary), with the exact sanitized text shown. The
87
- zero-auth mechanism: a pre-filled GitHub new-issue URL
88
- (github.com/Apra-Labs/apra-fleet/issues/new?title=...&body=...) -- one
89
- click, human-in-the-loop by construction, nothing uploads silently,
90
- no token handling at all.
91
- - **always (standing consent, mainly internal/trusting users)**: approved
92
- once and for all via explicit config; reports auto-filed via gh CLI
93
- using the user's own gh auth, or a scoped token stored in the fleet
94
- credential store (referenced as a {{secure.*}} handle, never plaintext).
95
- Standing consent is per-install, revocable, and recorded in the report
96
- footer ("filed under standing consent").
97
- - **never**: local reports only; nothing asks, nothing uploads.
98
-
99
- Sanitization spec (applies BEFORE the report is even saved locally):
100
- - Absolute paths -> stable placeholders (<work-folder>/..., <home>/...)
101
- - Hostnames, usernames, IPs, emails -> redacted tokens
102
- - Anything matching secret patterns (keys, tokens, {{secure.*}} values,
103
- env dumps) -> stripped outright, never placeholdered
104
- - Target-repo identifiers (repo name, branch names, bead titles) ->
105
- optional redaction tier: internal users may keep them; the default
106
- anonymizes to <target-repo>, <sprint-branch>
107
- - Code snippets: not included by default; error text is truncated to the
108
- minimal reproducing lines
109
- - A stable ANONYMOUS install id (random UUID, no derivation from machine
110
- identity) enables cross-report dedup without identifying the user
111
-
112
- Report content (schema sketch):
113
- - fingerprint: normalized error-class hash (for dedup and the
114
- same-class-twice cap)
115
- - context: engine version, OS, provider, phase, role being dispatched
116
- - narrative: what failed, diagnosis, actionsTaken[], resolved: bool,
117
- time lost
118
- - issueDraft: { title, redactedBody, labels: [coach-report, <class>] }
119
- - Dedup behavior upstream: same fingerprint appends an occurrence
120
- comment to the existing issue rather than opening a duplicate.
121
-
122
- ## Implementation sketch (unchanged mechanics, wider trigger)
123
-
124
- - Contract: agents/coach.md upstream in apra-pm (UPSTREAM DEPENDENCY like
125
- eft.11: needs an apra-pm PR + submodule pointer bump). Inputs: error
126
- text, phase, member, recent command history, sprint-state excerpt.
127
- Tools: Read + tightly-scoped Bash. Output: the report schema above.
128
- - Engine: a single coachOnRedState() boundary called from every red-state
129
- interception point listed above (one choke point, not N copies), after
130
- layer-1 handling. Interventions ledger in sprint state; caps enforced
131
- engine-side as backstop; telemetry mode read from fleet config.
132
- - Relation to the outside stabilization loop: coach handles in-run JIT
133
- recovery; the outside loop remains for engine-level fixes; coach
134
- reports feed both.
135
-
136
- ## Open design questions (to resolve before operationalizing)
137
-
138
- 1. Consent surface for "ask" mode: sprint-end CLI summary, PR body
139
- section, dashboard card, or all three? (Recommend: PR body section +
140
- dashboard card; the PR is where humans already look.)
141
- 2. Does the coach run on the ORCHESTRATOR member or the affected member?
142
- (Recommend: orchestrator-side dispatch that may execute allowlisted
143
- commands ON the affected member -- keeps one contract, avoids
144
- provisioning coach agents everywhere.)
145
- 3. N values: per-class cap (initial 2) and per-run cap (initial 5) --
146
- validate against real red-state frequency from run logs.
147
- 4. Should coach reports also feed a LOCAL knowledge base consulted on
148
- later invocations within the same install (self-priming), or is that
149
- scope creep for v1? (Bias: v2.)
150
- 5. Fingerprint algorithm: normalize paths/ids out of the error text, hash
151
- the remainder -- needs a worked spec with collision examples.
1
+ # Coach Role (superseded -- see escalate-to-llm-design.md)
2
+
3
+ Status: SUPERSEDED 2026-08-10 by the sprint-doctor design in
4
+ [`escalate-to-llm-design.md`](escalate-to-llm-design.md). Kept as a pointer so
5
+ links and history resolve; the full original text is in git history
6
+ (this file, prior to this commit).
7
+
8
+ The coach idea (2026-07-20): an in-workflow LLM role for error classes the
9
+ deterministic engine did not foresee -- invoked strictly after typed
10
+ handlers/ladders, single-shot, capped per error class, filing a sanitized
11
+ bug report for every intervention, failing loudly when it cannot fix.
12
+
13
+ sprint-doctor is that idea carried forward under a new name, with a stricter
14
+ decision/action split (zero-tool consult; the runner executes a bounded
15
+ action enum), an explicit environment-vs-engine-vs-task-shape triage, a
16
+ data-driven symptom/remedy registry, stagnation triggers on top of coach's
17
+ red-state events, and a generic engine-level pause/resume for human
18
+ hand-off. Every load-bearing coach idea was folded in and is credited
19
+ inline in the doctor doc: the three-layer error-handling hierarchy and
20
+ red-state taxonomy (its section 1), same-class-twice fingerprint cap,
21
+ no-recursion, interventions-as-review-evidence and deterministic test
22
+ stubbing (section 6), rescue-WIP-to-branch salvage (section 2.5), and the
23
+ consent-gated sanitized telemetry flow (section 4.4).
@@ -0,0 +1,256 @@
1
+ # Dolt manual recovery runbook (verified 2026-08-12, all steps live-tested on fleet-win-dev1)
2
+
3
+ This is the ground-truth procedure for standing up an ephemeral `dolt sql-server`
4
+ against a wedged embedded Dolt clone, querying/repairing it, and tearing it back
5
+ down -- verified end to end against a real clone on a real member, not written
6
+ from docs.
7
+
8
+ STATUS: this procedure is now AUTOMATED end to end by `settleDoltConflicts()`
9
+ (`packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs`), which is the
10
+ executable form of this document and runs at both sync divergence terminals --
11
+ fleet members self-heal without a human or an LLM. The old Path A / Path B /
12
+ Tier 2 ladder and its LLM runbook (`dolt-tier2-runbook.md`) were retired and
13
+ deleted; see `dolt-sync-redesign.md`.
14
+
15
+ This document remains the SPECIFICATION that code encodes, and the human
16
+ copy-paste fallback for driving a clone by hand. Every step here was
17
+ independently rediscovered by trial and error at least once already (see
18
+ apra-fleet-ga61, apra-fleet-5mqg) -- which is exactly why it is written down
19
+ and encoded once.
20
+
21
+ ## 0. Precondition: find the REAL data directory. Never hardcode it.
22
+
23
+ ```
24
+ bd dolt status
25
+ ```
26
+
27
+ Read the `Data:` line from the output (also mirrored in `.beads/metadata.json`'s
28
+ `dolt_mode` field). This is bd's own live, authoritative answer for THIS clone,
29
+ right now. Do not assume `.beads/embeddeddolt` -- that happens to be bd's
30
+ convention today, but a script that hardcodes it and finds a second/different
31
+ directory should treat that as orphaned residue from a prior failed recovery
32
+ (see apra-fleet-5mqg) and refuse to proceed blind, not silently pick one.
33
+
34
+ If `bd dolt status` reports `embedded (in-process, no server)`, there is no
35
+ live server to route through -- an ephemeral one must be started (step 2). If
36
+ it already reports a live server (host:port), skip straight to step 3 and
37
+ target that existing server/port instead of starting a second one.
38
+
39
+ ## 1. Ensure the PINNED `dolt` binary is present (never a package manager)
40
+
41
+ The embedded `bd` binary does NOT ship enough of the Dolt CLI to drive a
42
+ merge-conflict resolution over SQL -- that requires the real `dolt` binary and
43
+ a real `dolt sql-server` process, temporarily, against the SAME data directory.
44
+
45
+ CORRECTED 2026-08-13 (`dolt-sync-redesign.md` Part 5, Precondition V2). This
46
+ step previously said `winget install --id DoltHub.Dolt` on Windows, plus
47
+ `apt`/`brew` on POSIX. That was a genuine mistake and must not be repeated:
48
+ winget delivered a STALE 1.86.3 build while this repo carries its own version
49
+ pin, so an OS package manager is a second, unpinned version channel -- banned
50
+ from every code path and runbook this design owns. It also created a PATH
51
+ problem of its own: a winget-installed binary is invisible to processes that
52
+ started before the install, which is every SSH-dispatched session.
53
+
54
+ The fleet's ONE pinned channel is the same GitHub release asset
55
+ `src/cli/dolt-install.ts` uses (`DOLT_VERSION`, currently `v2.2.0`), landed at
56
+ the fleet-managed path -- always referenced as an absolute path, never system
57
+ PATH, and needing no admin rights:
58
+
59
+ - Windows: `%USERPROFILE%\.apra-fleet\bin\dolt.exe`
60
+ - POSIX: `$HOME/.apra-fleet/bin/dolt`
61
+
62
+ Probe it first -- existence is not enough, it must actually RUN and report the
63
+ pinned version:
64
+
65
+ ```bash
66
+ "$HOME/.apra-fleet/bin/dolt" version # POSIX
67
+ ```
68
+ ```powershell
69
+ & "$env:USERPROFILE\.apra-fleet\bin\dolt.exe" version # Windows
70
+ ```
71
+
72
+ If it is missing, broken, or the wrong version, install it from the pinned
73
+ asset. `settleDoltConflicts()` does exactly this itself (`ensurePinnedDolt()`
74
+ in `dolt-settle.mjs`, design doc Part 5.3) -- members never run
75
+ `apra-fleet install`, so nothing else on a member ever puts a pinned dolt
76
+ there. By hand, the same sequence is:
77
+
78
+ **Windows:**
79
+ ```powershell
80
+ New-Item -ItemType Directory -Force "$env:USERPROFILE\.apra-fleet\bin" | Out-Null
81
+ Invoke-WebRequest -Uri https://github.com/dolthub/dolt/releases/download/v2.2.0/dolt-windows-amd64.zip -OutFile "$env:TEMP\dolt-settle.zip" -TimeoutSec 300
82
+ Expand-Archive -Force "$env:TEMP\dolt-settle.zip" "$env:TEMP\dolt-settle"
83
+ Get-ChildItem -Recurse -Filter dolt.exe "$env:TEMP\dolt-settle" | Select-Object -First 1 |
84
+ Copy-Item -Force -Destination "$env:USERPROFILE\.apra-fleet\bin\dolt.exe"
85
+ ```
86
+
87
+ **Linux / macOS** (swap the asset for `dolt-linux-amd64.tar.gz`,
88
+ `dolt-darwin-amd64.tar.gz` or `dolt-darwin-arm64.tar.gz` to match the member):
89
+ ```bash
90
+ mkdir -p "$HOME/.apra-fleet/bin"
91
+ curl -fL --max-time 300 https://github.com/dolthub/dolt/releases/download/v2.2.0/dolt-linux-amd64.tar.gz -o /tmp/dolt-settle.tgz
92
+ mkdir -p /tmp/dolt-settle && tar -xzf /tmp/dolt-settle.tgz -C /tmp/dolt-settle
93
+ install -m 0755 "$(find /tmp/dolt-settle -type f -name dolt | head -1)" "$HOME/.apra-fleet/bin/dolt"
94
+ ```
95
+
96
+ Then re-probe: the freshly installed binary must report the pinned version
97
+ before you continue. On Windows a replace can fail because a stray `dolt`
98
+ process holds the file -- kill any process whose executable path IS this
99
+ fleet-managed path (nothing else ever launches a binary there) and retry once.
100
+
101
+ Every `dolt ...` invocation below means that absolute pinned path, not a bare
102
+ `dolt` from PATH.
103
+
104
+ ## 2. Start the ephemeral sql-server -- GENUINELY DETACHED
105
+
106
+ This is the step with real cross-platform divergence, and where most of the
107
+ danger lives (an interrupted/never-torn-down server is exactly what
108
+ apra-fleet-5mqg is about).
109
+
110
+ **Windows -- do NOT use `Start-Process` or `schtasks`:**
111
+
112
+ - `Start-Process -WindowStyle Hidden` looked detached but is NOT: it is still a
113
+ child of the invoking SSH/job-object session. Verified live: the sql-server
114
+ process (and its listening port) died the instant the launching
115
+ `execute_command` call's session ended, even with `-RedirectStandardOutput`/
116
+ `-RedirectStandardError` set and `-PassThru`.
117
+ - `schtasks`/`Register-ScheduledTask` + `Start-ScheduledTask` also failed:
118
+ verified live, `Get-ScheduledTaskInfo` reported `LastTaskResult 267011`
119
+ (`SCHED_S_TASK_QUEUED`) -- the task was queued but never actually ran,
120
+ because this is a non-interactive SSH session with no interactive logon
121
+ (the exact apra-fleet-i8qj failure mode, reproduced here independently).
122
+ - **What actually works, verified live:** spawn via WMI, which creates the
123
+ process under the WMI provider host's own session (session 0), fully
124
+ independent of the SSH session's job object:
125
+
126
+ ```powershell
127
+ $result = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{
128
+ CommandLine = '"C:\Users\<you>\.apra-fleet\bin\dolt.exe" sql-server --host 127.0.0.1 --port 13399 --data-dir .beads/embeddeddolt'
129
+ CurrentDirectory = 'C:\akhil\git\apra-fleet'
130
+ }
131
+ $result.ProcessId # <-- record this PID for teardown (step 5)
132
+ ```
133
+ Verify it is actually up before proceeding: `Get-Process -Id <pid>` should
134
+ show it running under `SI` (session ID) `0`, and
135
+ `Test-NetConnection -ComputerName 127.0.0.1 -Port 13399` should report
136
+ `TcpTestSucceeded: True`.
137
+
138
+ **Linux / macOS (POSIX):** the SSH-session-job-object problem does not exist on
139
+ POSIX in the same way; the existing `nohup ... & disown` pattern (as used by
140
+ `task-wrapper.ts`'s bash wrapper for `long_running` commands elsewhere in this
141
+ codebase) is sufficient:
142
+
143
+ ```bash
144
+ nohup dolt sql-server --host 127.0.0.1 --port 13399 --data-dir .beads/embeddeddolt \
145
+ > /tmp/dolt-recovery.log 2>&1 &
146
+ echo "PID:$!"
147
+ disown
148
+ ```
149
+
150
+ ## 3. Connect and query -- the exact working flag set (verified live)
151
+
152
+ ```
153
+ dolt --no-tls --host=127.0.0.1 --port=13399 sql -q "USE beads; SELECT ...;"
154
+ ```
155
+
156
+ Two specific, non-obvious landmines, both reproduced live on this run:
157
+
158
+ 1. **`--no-tls` must come BEFORE `--host`/`--port`.** With `--host`/`--port`
159
+ given first and `--no-tls` after, the client still requested TLS and failed
160
+ with `TLS requested but server does not support TLS` -- Dolt's global-flag
161
+ parser is order-sensitive here. Always lead with `--no-tls`.
162
+ 2. **Do NOT pass `--user=root` or `--password` at all**, even though root with
163
+ an empty password is the documented default. Explicitly passing `--user=root`
164
+ switches the client into a credential-resolution path that issues an
165
+ interactive `Enter password:` prompt and then fails non-interactively with
166
+ `Failed to parse credentials: The handle is invalid` -- this is the EXACT
167
+ apra-fleet-ga61 symptom, reproduced live and now root-caused precisely: it
168
+ is triggered by explicitly specifying `--user`/`--password`, not by network
169
+ mode itself. Omitting both flags entirely lets the client silently
170
+ authenticate as root with the empty-password default with zero prompt.
171
+ (Separately, on Windows/PowerShell specifically: an empty-string argument
172
+ like `--password ''` can be silently dropped by PowerShell's native-argument
173
+ passing, shifting the NEXT flag into becoming its value -- another reason to
174
+ just omit the flag rather than try to pass an explicit empty value.)
175
+
176
+ Use `USE beads;` as the first statement of every query -- the target database
177
+ name is not implied by `--data-dir` alone once connected over SQL.
178
+
179
+ The actual recovery SQL (identical across all three OSes -- this part has no
180
+ platform variance):
181
+
182
+ ```sql
183
+ SET @@dolt_allow_commit_conflicts = 1;
184
+ CALL DOLT_MERGE('origin/main');
185
+ SELECT `table` FROM dolt_conflicts; -- enumerate EVERY conflicted table
186
+ CALL DOLT_CONFLICTS_RESOLVE('--theirs', 'issues'); -- table name is REQUIRED
187
+ CALL DOLT_COMMIT('-m', 'manual recovery: resolve conflict');
188
+ SELECT COUNT(*) FROM dolt_conflicts; -- MUST be 0 before you republish
189
+ ```
190
+ A bare `--theirs` is only correct when discarding our side's version of those
191
+ rows is genuinely acceptable. `settleDoltConflicts()` applies the full rulebook
192
+ instead -- per-field last-writer-wins by `updated_at` for `issues` and
193
+ `dependencies`, a real set-union INSERT for `labels`, generic
194
+ LWW-or-theirs for anything else (design doc Part 3.2 step 4). Resolving by hand
195
+ with real content on both sides, follow the same rules rather than clobbering
196
+ one side.
197
+
198
+ Then, outside the SQL session -- and ONLY AFTER the teardown in step 5 --
199
+ `bd dolt pull` (verify), `bd dolt push` (republish). The order matters; see
200
+ step 5.
201
+
202
+ ## 4. Verify before teardown
203
+
204
+ ```
205
+ dolt --no-tls --host=127.0.0.1 --port=13399 sql -q "USE beads; SELECT * FROM dolt_status;"
206
+ ```
207
+ Confirm no residual uncommitted/conflicted state before tearing the server down.
208
+
209
+ ## 5. Teardown -- ALWAYS, every path, even on failure, and BEFORE republishing
210
+
211
+ Ordering, corrected (design doc Part 7.2): tear the ephemeral server down
212
+ FIRST, then run `bd dolt pull` / `bd dolt push`. Embedded-mode `bd` must open
213
+ the same data dir the server still holds under Dolt's per-directory exclusive
214
+ lock, so republishing while the server is still up fails or falls back
215
+ read-only.
216
+
217
+ **Windows:**
218
+ ```powershell
219
+ Stop-Process -Id <pid> -Force -ErrorAction SilentlyContinue
220
+ ```
221
+ **POSIX:**
222
+ ```bash
223
+ kill <pid>
224
+ ```
225
+
226
+ Then, on every OS:
227
+ - Verify the port is actually closed (`Test-NetConnection` / `nc -z` /
228
+ `lsof -i:<port>`).
229
+ - Verify `bd dolt status` reports `embedded (in-process, no server)` again and
230
+ `.beads/metadata.json`'s `dolt_mode` is `"embedded"` -- if this recovery
231
+ procedure ever explicitly flips `dolt_mode` to `"server"` as part of routing
232
+ bd itself through the ephemeral server (this manual run did NOT do that --
233
+ it talked to the raw `dolt` CLI directly, bypassing bd entirely -- and
234
+ `settleDoltConflicts()` deliberately does the same, which is what makes its
235
+ teardown unconditionally safe), flipping it back is
236
+ MANDATORY and must happen in a `finally`/guaranteed-cleanup block, not as
237
+ the last step of a list that can be abandoned mid-way (exactly what went
238
+ wrong in the incident apra-fleet-5mqg documents).
239
+ - Remove any temp log files created for the ephemeral server's stdout/stderr.
240
+
241
+ ## Why this matters for the code fix (apra-fleet-5mqg, apra-fleet-ga61)
242
+
243
+ Every numbered landmine above (`--no-tls` ordering, omitting `--user`/
244
+ `--password`, WMI vs `Start-Process`/`schtasks` for real detachment on Windows,
245
+ never hardcoding the data directory) was independently rediscovered by trial
246
+ and error here, and was ALSO independently rediscovered by trial and error by
247
+ the Tier-2 LLM dispatch whose transcript motivated apra-fleet-5mqg. That was
248
+ strong evidence this entire procedure is mechanical and fully scriptable --
249
+ there was no judgment call anywhere in this runbook, only flag/ordering
250
+ trivia a fixed script encodes once and never has to rediscover again. That
251
+ script now exists: `fleet-sprint/dolt-settle.mjs`.
252
+
253
+ CAVEAT on the evidence: every landmine above was verified live against a
254
+ winget-installed dolt **1.86.3**, not against the pinned **v2.2.0** the fleet
255
+ now installs. Re-verifying them on the pinned binary, per OS, is Precondition
256
+ V0 of the design doc's Part 4 verification pass.