@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
@@ -48,45 +48,46 @@
48
48
  * purpose-based API incrementally; they are IMPLEMENTATION DETAIL of the three
49
49
  * entry points above, not a second supported surface.
50
50
  *
51
- * RECOVERY-LADDER DISPOSITION (apra-fleet-417.2.1 AC3; EXECUTED by
52
- * apra-fleet-vkc.1)
51
+ * CONFLICT-RECOVERY DISPOSITION (docs/dolt-sync-redesign.md Parts 2.2/2.4)
53
52
  * -------------------------------------------------------------------------
54
- * Decision: WIRE, not decommission -- and, as of apra-fleet-vkc.1, DONE.
55
- * dolt-recovery.mjs (Path A: gated allowlist resolve-in-place),
56
- * dolt-recovery-path-b.mjs (Path B: discard-and-re-bootstrap from the shared
57
- * remote) and dolt-recovery-tier2.mjs (Tier 2: agent escalation against
58
- * docs/dolt-tier2-runbook.md) were previously imported only by their own
59
- * tests -- doltPushAfter()'s diverged path threw DoltDivergedError with no
60
- * recovery attempt. They are NOT decommissioned because the failure they
61
- * handle is real and was sprint-fatal: a wedged beads clone stops the whole
62
- * sprint, and the ladder is the only written-down remedy for it.
63
- *
64
- * How it is wired (apra-fleet-vkc.1): dolt-recovery-tier2.mjs now exports
65
- * buildDoltRecoveryLadder(member, opts), the ONE place the three paths are
66
- * composed into a single zero-argument callback. doltPushAfter() accepts that
67
- * callback as `opts.recover` and invokes it at its divergence terminal -- the
68
- * single place a divergence outlives the bounded first-successful-pusher-wins
69
- * reconcile -- logging each tier's outcome and surfacing the DoltDivergedError
70
- * (-> BEADS_SYNC_CONFLICT) only if the whole ladder fails. runner.js's
71
- * post-dispatch sync bracket (syncMemberAfterOrdered) builds the callback and
72
- * threads it through DoltSync.syncAfter(), so every one of runner.js's D-push
73
- * call sites inherits recovery without opting in. DoltSync.repair() runs the
74
- * same ladder (capabilities().supportsRepair is now true).
75
- *
76
- * Kept unchanged on purpose: with NO `recover` callback wired, doltPushAfter()
77
- * behaves exactly as before (DoltDivergedError propagates immediately), so the
53
+ * The old 3-tier ladder (dolt-recovery.mjs Path A, dolt-recovery-path-b.mjs
54
+ * Path B, dolt-recovery-tier2.mjs Tier 2 + docs/dolt-tier2-runbook.md) is
55
+ * RETIRED, not merely rewired. In production it could never resolve anything:
56
+ * Path A threw its precondition guard on every invocation (no sql runtime was
57
+ * ever injected at its call site), Path B was hard-disabled for a correct
58
+ * reason, and Tier 2 only DISPATCHED an LLM -- it never verified, so
59
+ * recoverDoltConflict() returned `ok: false` by construction, 100% of the
60
+ * time. Worse, its teardown was an instruction step an agent could abandon
61
+ * mid-procedure (apra-fleet-5mqg).
62
+ *
63
+ * It is replaced by ONE deterministic function: settleDoltConflicts()
64
+ * (fleet-sprint/dolt-settle.mjs), total over every row-level conflict shape
65
+ * this data model can produce -- no gates, no allowlist, no escalation, no
66
+ * LLM -- with a real `finally` teardown. This module holds it as
67
+ * `opts.settle`: a zero-argument callback (buildSettleCallback(), same file)
68
+ * that RESOLVES on a verified recovery, because settle itself republishes and
69
+ * verifies before returning.
70
+ *
71
+ * Where it is wired -- BOTH divergence terminals, not just the push side:
72
+ * - doltPushAfter()'s terminal, where a divergence outlives the bounded
73
+ * first-successful-pusher-wins reconcile (where the ladder used to sit).
74
+ * - doltPullBefore()'s diverged terminal, which had NO recovery at all: a
75
+ * clone wedged by an earlier failed reconcile used to hard-abort the next
76
+ * sprint at the readiness gate (preflightBeadsHealthGate delegates here,
77
+ * so it inherits the same self-heal).
78
+ * - repair(), the operator/tool entry point -- same one implementation.
79
+ *
80
+ * Kept unchanged on purpose: with NO `settle` callback wired, both brackets
81
+ * behave exactly as before (the typed error propagates immediately), so the
78
82
  * degraded-by-default path (apra-fleet-417.3.1) and every existing call site
79
- * keep their pre-vkc.1 semantics. Path A additionally requires an injected
80
- * sql()/spawnSqlServer() runtime; runner.js does not yet supply one, so in
81
- * production Path A is reached and cleanly self-defers to Path B (no silent
82
- * dead module) until such a runtime is injected -- see buildDoltRecoveryLadder.
83
+ * keep their prior semantics.
83
84
  *
84
85
  * ASCII only.
85
86
  */
86
87
 
87
88
  import { DoltDivergedError, DoltSyncError } from './errors.mjs';
88
89
  import { classifyFailure, toDoltVerdict } from './vcs-module.mjs';
89
- import { buildDoltRecoveryLadder } from './dolt-recovery-tier2.mjs';
90
+ import { buildSettleCallback } from './dolt-settle.mjs';
90
91
 
91
92
  // ---------------------------------------------------------------------------
92
93
  // Dolt sync brackets: D-pull / D-push
@@ -238,6 +239,13 @@ const DOLT_BACKOFF_MAX_MS = 8000;
238
239
  * @param {number} [maxMs]
239
240
  * @returns {number}
240
241
  */
242
+ /** How often the push mutex's lease is renewed while this bracket holds it.
243
+ * Well under the supervisor mutex's 60s lease (src/supervisor/dolt-mutex.mjs
244
+ * DEFAULT_LEASE_MS), so a legitimately long hold -- push + reconcile +
245
+ * settle -- never loses mutual exclusion to reclaimExpired(). Design doc
246
+ * Part 3.4. */
247
+ export const DOLT_MUTEX_RENEW_INTERVAL_MS = 20_000;
248
+
241
249
  export function doltBackoffDelayMs(attempt, baseMs = DOLT_BACKOFF_BASE_MS, maxMs = DOLT_BACKOFF_MAX_MS) {
242
250
  const n = Math.max(1, Number(attempt) || 1);
243
251
  return Math.min(maxMs, baseMs * Math.pow(2, n - 1));
@@ -339,8 +347,42 @@ async function runDoltStep({ command, member, cmd, label, log, maxTransientRetri
339
347
  * @param {{ command: Function, log?: Function, maxTransientRetries?: number, checkSyncRemoteConfigured?: Function, skipPull?: boolean, onAuthFailure?: Function }} opts
340
348
  * @returns {Promise<{ ok: true, member: string, skipped?: true, reason?: 'no-remote'|'empty-remote'|'already-fresh' }>}
341
349
  */
350
+ /**
351
+ * Invoke the injected settle callback at a divergence terminal, if one is
352
+ * wired. Returns the settle result on a verified recovery, or null when there
353
+ * is no callback / settle itself failed -- in which case the caller surfaces
354
+ * its typed error exactly as it did before settle existed.
355
+ *
356
+ * A settle failure is an OPERATIONAL failure (no usable dolt binary, server
357
+ * would not start, a SQL statement errored), never "this conflict is
358
+ * unresolvable" -- there is no such outcome. It is logged and folded into the
359
+ * existing divergence terminal rather than being escalated anywhere.
360
+ *
361
+ * @param {{ settle?: Function, member: string, operation: string, error: Error, log: Function }} ctx
362
+ * @returns {Promise<object|null>}
363
+ */
364
+ async function attemptSettle({ settle, member, operation, error, log }) {
365
+ if (typeof settle !== 'function') return null;
366
+ log(`[Dolt] ${operation} for member '${member}' diverged; running settleDoltConflicts() (deterministic, no escalation) before surfacing BEADS_SYNC_CONFLICT.`);
367
+ let result = null;
368
+ try {
369
+ result = await settle({ operation, error });
370
+ } catch (settleErr) {
371
+ log(`[Dolt] settle itself failed operationally for member '${member}' (treated as unrecovered; this is an infra failure, NOT an unresolvable conflict): ${(settleErr && settleErr.message) || settleErr}`);
372
+ return null;
373
+ }
374
+ if (result && result.ok) {
375
+ const tables = (result.resolvedTables || []).join(', ') || 'none';
376
+ log(`[Dolt] settle RESOLVED the divergence for member '${member}' (tables: ${tables}) and republished; ${operation} reconciled.`);
377
+ for (const warning of result.warnings || []) log(`[Dolt] settle warning for member '${member}': ${warning}`);
378
+ return result;
379
+ }
380
+ log(`[Dolt] settle returned no verified recovery for member '${member}'; surfacing the divergence.`);
381
+ return null;
382
+ }
383
+
342
384
  export async function doltPullBefore(member, opts = {}) {
343
- const { command, log = () => {}, maxTransientRetries = 1, checkSyncRemoteConfigured, skipPull = false, onAuthFailure, sleep, backoffBaseMs } = opts;
385
+ const { command, log = () => {}, maxTransientRetries = 1, checkSyncRemoteConfigured, skipPull = false, onAuthFailure, sleep, backoffBaseMs, settle } = opts;
344
386
  if (typeof command !== 'function') {
345
387
  throw new Error("doltPullBefore requires an injected command() in opts");
346
388
  }
@@ -379,10 +421,22 @@ export async function doltPullBefore(member, opts = {}) {
379
421
  return { ok: true, member, skipped: true, reason: 'empty-remote' };
380
422
  }
381
423
  if (pull.kind === 'diverged') {
382
- throw new DoltDivergedError(
424
+ // The pull-side divergence terminal. Before this was wired
425
+ // (docs/dolt-sync-redesign.md Part 2.3), a clone wedged by an
426
+ // earlier failed reconcile had NO recovery seam here at all and
427
+ // hard-aborted the next sprint at its readiness gate.
428
+ const diverged = new DoltDivergedError(
383
429
  `[Dolt] D-pull for member '${member}' hit an unmergeable beads conflict and must not be auto-resolved by judgment: ${pull.error}`,
384
430
  { member, doltOutput: pull.error, operation: 'pull' },
385
431
  );
432
+ const settled = await attemptSettle({ settle, member, operation: 'D-pull', error: diverged, log });
433
+ if (settled) {
434
+ // settle ends with its own `bd dolt pull` + `bd dolt push`, so
435
+ // a resolved settle means this clone is already current --
436
+ // there is nothing left for this bracket to pull.
437
+ return { ok: true, member, recovered: true, settledTables: settled.resolvedTables || [] };
438
+ }
439
+ throw diverged;
386
440
  }
387
441
  if (pull.kind === 'auth') {
388
442
  // apra-fleet-spp: a credential failure is its own class. It is NOT
@@ -531,18 +585,18 @@ export async function preflightBeadsHealthGate(member, opts = {}) {
531
585
  * (including the reconcile/re-push) -- see runDoltStep's AUTH SELF-HEAL
532
586
  * CONTRACT.
533
587
  *
534
- * `opts.recover` (apra-fleet-vkc.1) is the optional Path A -> Path B -> Tier 2
535
- * recovery ladder callback (buildDoltRecoveryLadder, dolt-recovery-tier2.mjs).
536
- * When present, a divergence that outlives the bounded reconcile attempts the
537
- * ladder before the DoltDivergedError is surfaced as BEADS_SYNC_CONFLICT; when
538
- * absent the divergence propagates immediately (pre-vkc.1 behavior).
588
+ * `opts.settle` is the optional deterministic conflict-settlement callback
589
+ * (buildSettleCallback, dolt-settle.mjs). When present, a divergence that
590
+ * outlives the bounded reconcile runs settle before the DoltDivergedError is
591
+ * surfaced as BEADS_SYNC_CONFLICT; when absent the divergence propagates
592
+ * immediately (pre-settle behavior).
539
593
  *
540
594
  * @param {string} member
541
- * @param {{ command: Function, pushBeads?: boolean, log?: Function, maxTransientRetries?: number, mutex?: { acquire: Function, release: Function }, sprintId?: string, checkSyncRemoteConfigured?: Function, onAuthFailure?: Function, recover?: () => Promise<{ ok: boolean, tier: string }> }} opts
542
- * @returns {Promise<{ ok: true, member: string, pushed: boolean, reconciled: boolean, skipped?: true, reason?: 'no-remote', recovered?: true, recoveryTier?: string }>}
595
+ * @param {{ command: Function, pushBeads?: boolean, log?: Function, maxTransientRetries?: number, mutex?: { acquire: Function, release: Function }, sprintId?: string, checkSyncRemoteConfigured?: Function, onAuthFailure?: Function, settle?: () => Promise<{ ok: boolean, resolvedTables?: string[] }> }} opts
596
+ * @returns {Promise<{ ok: true, member: string, pushed: boolean, reconciled: boolean, skipped?: true, reason?: 'no-remote', recovered?: true, settledTables?: string[] }>}
543
597
  */
544
598
  export async function doltPushAfter(member, opts = {}) {
545
- const { command, pushBeads = true, log = () => {}, maxTransientRetries = 1, mutex, sprintId, checkSyncRemoteConfigured, onAuthFailure, sleep, backoffBaseMs, recover } = opts;
599
+ const { command, pushBeads = true, log = () => {}, maxTransientRetries = 1, mutex, sprintId, checkSyncRemoteConfigured, onAuthFailure, sleep, backoffBaseMs, settle, renewIntervalMs = DOLT_MUTEX_RENEW_INTERVAL_MS } = opts;
546
600
  if (typeof command !== 'function') {
547
601
  throw new Error("doltPushAfter requires an injected command() in opts");
548
602
  }
@@ -566,13 +620,38 @@ export async function doltPushAfter(member, opts = {}) {
566
620
 
567
621
  // Serialize this push behind the global mutex: acquire (waiting our FIFO
568
622
  // turn) before touching the remote; release on every exit.
623
+ //
624
+ // LEASE RENEWAL (docs/dolt-sync-redesign.md Part 3.4): the mutex lease is
625
+ // 60s and reclaimExpired() force-evicts at expiry EVEN IF the holder is
626
+ // alive. This bracket can legitimately outlive that -- a push, a reconcile
627
+ // pull, and now a full settle (ephemeral server spawn + merge + resolve +
628
+ // republish) -- so acquiring once and never renewing silently loses mutual
629
+ // exclusion mid-operation. Renew on an interval well under the lease while
630
+ // we hold it, and stop renewing in the same `finally` that releases.
569
631
  let grant = null;
570
632
  if (mutex && typeof mutex.acquire === 'function') {
571
633
  grant = await mutex.acquire(sprintId || member, { pid: process.pid });
572
634
  }
635
+ let renewTimer = null;
636
+ if (grant && mutex && typeof mutex.renew === 'function') {
637
+ renewTimer = setInterval(() => {
638
+ Promise.resolve()
639
+ .then(() => mutex.renew(grant.token))
640
+ .then((renewed) => {
641
+ if (renewed === false) {
642
+ log(`[Dolt] mutex lease renewal for member '${member}' was REFUSED (the lease was already reclaimed) -- another sprint may now hold the push mutex.`);
643
+ }
644
+ })
645
+ .catch((renewErr) => {
646
+ log(`[Dolt] mutex lease renewal for member '${member}' failed (non-fatal; the lease may expire): ${(renewErr && renewErr.message) || renewErr}`);
647
+ });
648
+ }, renewIntervalMs);
649
+ if (typeof renewTimer.unref === 'function') renewTimer.unref();
650
+ }
573
651
  try {
574
652
  return await doltPushGuarded();
575
653
  } finally {
654
+ if (renewTimer) clearInterval(renewTimer);
576
655
  if (grant && mutex && typeof mutex.release === 'function') {
577
656
  try {
578
657
  await mutex.release(grant.token);
@@ -582,35 +661,21 @@ export async function doltPushAfter(member, opts = {}) {
582
661
  }
583
662
  }
584
663
 
585
- // apra-fleet-vkc.1: the recovery ladder terminal. A divergence that
586
- // outlives the bounded first-successful-pusher-wins reconcile is exactly
587
- // the wedged-clone failure the Path A -> Path B -> Tier 2 ladder exists
588
- // for. When an `opts.recover` ladder callback is wired (runner.js builds it
589
- // via buildDoltRecoveryLadder and threads it through DoltSync.syncAfter),
590
- // the diverged terminal attempts it -- logging each outcome -- and only
591
- // surfaces the DoltDivergedError (which runner.js classifies as the
592
- // terminal BEADS_SYNC_CONFLICT) if the whole ladder fails to close the
593
- // clone. With no recover callback wired the behavior is unchanged: the
594
- // DoltDivergedError propagates immediately, so every existing call site and
595
- // the degraded-by-default path keep their pre-vkc.1 semantics.
664
+ // The push-side divergence terminal. A divergence that outlives the
665
+ // bounded first-successful-pusher-wins reconcile is exactly the
666
+ // wedged-clone failure settleDoltConflicts() exists for. When an
667
+ // `opts.settle` callback is wired (runner.js builds it via
668
+ // buildSettleCallback and threads it through DoltSync.syncAfter), this
669
+ // terminal runs it, and only surfaces the DoltDivergedError (which
670
+ // runner.js classifies as the terminal BEADS_SYNC_CONFLICT) if settle
671
+ // itself failed operationally. Unlike the retired Tier 2, a settle that
672
+ // resolves IS a verified recovery: it republishes and verifies the push
673
+ // before returning. With no settle callback wired the behavior is
674
+ // unchanged: the DoltDivergedError propagates immediately.
596
675
  async function surfaceDivergence(divergedError, operation) {
597
- if (typeof recover === 'function') {
598
- log(`[Dolt] D-push for member '${member}' diverged (${operation}); attempting the recovery ladder (Path A -> Path B -> Tier 2) before surfacing BEADS_SYNC_CONFLICT.`);
599
- let ladder = null;
600
- try {
601
- ladder = await recover({ operation, error: divergedError });
602
- } catch (recErr) {
603
- log(`[Dolt] recovery ladder itself threw for member '${member}' (treated as unrecovered): ${(recErr && recErr.message) || recErr}`);
604
- }
605
- if (ladder && ladder.ok) {
606
- log(`[Dolt] recovery ladder RESOLVED the divergence for member '${member}' at tier '${ladder.tier}' -- D-push reconciled.`);
607
- return { ok: true, member, pushed: true, reconciled: true, recovered: true, recoveryTier: ladder.tier };
608
- }
609
- log(
610
- `[Dolt] recovery ladder did NOT resolve the divergence for member '${member}'` +
611
- `${ladder ? ` (last tier '${ladder.tier}'${ladder.escalated ? ', escalated to Tier 2' : ''})` : ' (no ladder result)'}; ` +
612
- 'surfacing DoltDivergedError -> BEADS_SYNC_CONFLICT.',
613
- );
676
+ const settled = await attemptSettle({ settle, member, operation: `D-push (${operation})`, error: divergedError, log });
677
+ if (settled) {
678
+ return { ok: true, member, pushed: true, reconciled: true, recovered: true, settledTables: settled.resolvedTables || [] };
614
679
  }
615
680
  throw divergedError;
616
681
  }
@@ -882,10 +947,10 @@ export function toNeutralDegradedKind(kind) {
882
947
  * adapter: declares which neutral degraded.kind values this backend can ever
883
948
  * produce, plus the booleans callers use instead of assuming Dolt semantics.
884
949
  *
885
- * `supportsRepair: true` (apra-fleet-vkc.1) reflects that `repair()` below now
886
- * runs the real Path A -> Path B -> Tier 2 recovery ladder
887
- * (buildDoltRecoveryLadder, dolt-recovery-tier2.mjs) rather than being a named
888
- * seam only -- see the RECOVERY-LADDER DISPOSITION note in this file's header.
950
+ * `supportsRepair: true` reflects that `repair()` below runs the real
951
+ * deterministic settle (settleDoltConflicts, dolt-settle.mjs) rather than
952
+ * being a named seam only -- see the CONFLICT-RECOVERY DISPOSITION note in
953
+ * this file's header.
889
954
  *
890
955
  * @returns {{ wholeStatePublish: boolean, supportsRepair: boolean, supportsCoordinationLock: boolean, kinds: string[] }}
891
956
  */
@@ -1070,10 +1135,9 @@ export async function syncBefore(member, opts = {}) {
1070
1135
  * `fatal: true` at a call site that must still hard-abort (the post-dispatch
1071
1136
  * sync bracket does, so an unreachable close can never be advertised).
1072
1137
  *
1073
- * This is the seam the recovery ladder is wired behind (apra-fleet-vkc.1): an
1074
- * `opts.recover` ladder callback is passed straight through to doltPushAfter(),
1075
- * whose divergence terminal invokes it -- see the RECOVERY-LADDER DISPOSITION
1076
- * note in the module header.
1138
+ * This is the seam settle is wired behind: an `opts.settle` callback is passed
1139
+ * straight through to doltPushAfter(), whose divergence terminal invokes it --
1140
+ * see the CONFLICT-RECOVERY DISPOSITION note in the module header.
1077
1141
  *
1078
1142
  * `opts.mutatedItemIds` (ADR Decision 2/3, apra-fleet-417.5) is accepted per
1079
1143
  * the TaskDBModule contract but INTENTIONALLY NOT CONSUMED by this adapter:
@@ -1194,38 +1258,40 @@ export function flush(filter = {}) {
1194
1258
  * credential re-provisioning. Called by operators/tools and by ensureReady();
1195
1259
  * never inline from a per-operation sync path."
1196
1260
  *
1197
- * WIRED (apra-fleet-vkc.1): runs the real Path A -> Path B -> Tier 2 recovery
1198
- * ladder (buildDoltRecoveryLadder, dolt-recovery-tier2.mjs) against a wedged
1199
- * beads clone and reports whether it was repaired. This is the operator/tool
1200
- * entry point onto the SAME ladder doltPushAfter()'s divergence terminal
1201
- * invokes -- one composed implementation, two callers -- so a manual repair
1202
- * and an automatic one behave identically. `command` is required (every
1203
- * recovery path issues `bd dolt` commands through it); the Path A sql runtime
1204
- * and the Tier 2 `agent` are optional (see buildDoltRecoveryLadder for how
1205
- * each path degrades when its dependency is absent).
1261
+ * WIRED: runs the real deterministic settle (settleDoltConflicts,
1262
+ * dolt-settle.mjs) against a wedged beads clone and reports whether it was
1263
+ * repaired. This is the operator/tool entry point onto the SAME function both
1264
+ * divergence terminals invoke -- one implementation, three callers -- so a
1265
+ * manual repair and an automatic one behave identically. `command` is
1266
+ * required (settle issues every `bd dolt`/`dolt` command through it);
1267
+ * `platform`/`arch` are optional and probed from the member when absent.
1268
+ * `opts.settle` may be supplied to override the callback (tests do this).
1206
1269
  *
1207
1270
  * @param {string} member
1208
- * @param {{ command?: Function, log?: Function, agent?: Function, [key: string]: any }} [opts]
1209
- * @returns {Promise<{ repaired: boolean, tier?: string, escalation?: string, result?: object }>}
1271
+ * @param {{ command?: Function, log?: Function, platform?: string, arch?: string, settle?: Function, [key: string]: any }} [opts]
1272
+ * @returns {Promise<{ repaired: boolean, escalation?: string, result?: object }>}
1210
1273
  */
1211
1274
  export async function repair(member, opts = {}) {
1212
- const { command, log = () => {} } = opts;
1275
+ const { command, log = () => {}, platform, arch } = opts;
1213
1276
  if (typeof command !== 'function') {
1214
- return { repaired: false, escalation: 'not-configured: repair() requires an injected command() to run the recovery ladder' };
1277
+ return { repaired: false, escalation: 'not-configured: repair() requires an injected command() to run settle' };
1278
+ }
1279
+ const settle = typeof opts.settle === 'function'
1280
+ ? opts.settle
1281
+ : buildSettleCallback(member, { command, log, platform, arch });
1282
+ let result = null;
1283
+ try {
1284
+ result = await settle({ operation: 'repair' });
1285
+ } catch (err) {
1286
+ log(`[Dolt] repair() failed operationally for member '${member}' (an infra failure, NOT an unresolvable conflict): ${(err && err.message) || err}`);
1287
+ return { repaired: false, escalation: 'settle-operational-failure', result: { error: (err && err.message) || String(err) } };
1215
1288
  }
1216
- const ladder = buildDoltRecoveryLadder(member, opts);
1217
- const result = await ladder();
1218
1289
  if (result && result.ok) {
1219
- log(`[Dolt] repair() resolved member '${member}' via the recovery ladder at tier '${result.tier}'.`);
1220
- return { repaired: true, tier: result.tier, result };
1290
+ log(`[Dolt] repair() settled member '${member}' (tables: ${(result.resolvedTables || []).join(', ') || 'none'}).`);
1291
+ return { repaired: true, result };
1221
1292
  }
1222
- log(`[Dolt] repair() did NOT resolve member '${member}' (tier '${result && result.tier}'${result && result.escalated ? ', escalated to Tier 2' : ''}).`);
1223
- return {
1224
- repaired: false,
1225
- tier: result && result.tier,
1226
- escalation: result && result.escalated ? 'tier-2-dispatched' : 'unrecovered',
1227
- result,
1228
- };
1293
+ log(`[Dolt] repair() did NOT settle member '${member}'.`);
1294
+ return { repaired: false, escalation: 'unrecovered', result };
1229
1295
  }
1230
1296
 
1231
1297
  export const DoltSync = {
@@ -135,23 +135,27 @@ export class SprintPlanRejectedError extends WorkflowError {
135
135
  * @property {string[]} [thrashIds] - N9: bead ids reopened more than the
136
136
  * reopen-thrash threshold this sprint, i.e. the beads most likely
137
137
  * responsible for a close/reopen oscillation stall
138
+ * @property {string[]} [blockerIds] - apra-fleet-mjo: the bead ids still open
139
+ * at/above goal priority when the stall was declared, i.e. exactly what an
140
+ * operator must clear. Counts alone cannot answer "blocked on what?".
138
141
  */
139
142
  export class StalledSprintError extends WorkflowError {
140
143
  /**
141
144
  * @param {string} message
142
- * @param {{ staleCycles?: number, closedCountHistory?: number[], highWaterClosedCount?: number, thrashIds?: string[], cycle?: number, details?: object, cause?: unknown }} [opts]
145
+ * @param {{ staleCycles?: number, closedCountHistory?: number[], highWaterClosedCount?: number, thrashIds?: string[], blockerIds?: string[], cycle?: number, details?: object, cause?: unknown }} [opts]
143
146
  */
144
147
  constructor(message, opts = {}) {
145
- const { staleCycles = null, closedCountHistory = [], highWaterClosedCount = null, thrashIds = [], cycle, details, cause } = opts;
148
+ const { staleCycles = null, closedCountHistory = [], highWaterClosedCount = null, thrashIds = [], blockerIds = [], cycle, details, cause } = opts;
146
149
  super(message, {
147
150
  code: 'SPRINT_STALLED',
148
- details: { staleCycles, closedCountHistory, highWaterClosedCount, thrashIds, cycle, ...details },
151
+ details: { staleCycles, closedCountHistory, highWaterClosedCount, thrashIds, blockerIds, cycle, ...details },
149
152
  cause,
150
153
  });
151
154
  this.staleCycles = staleCycles;
152
155
  this.closedCountHistory = closedCountHistory;
153
156
  this.highWaterClosedCount = highWaterClosedCount;
154
157
  this.thrashIds = thrashIds;
158
+ this.blockerIds = blockerIds;
155
159
  }
156
160
  }
157
161
 
@@ -342,6 +346,44 @@ export class DoltSyncError extends WorkflowError {
342
346
  }
343
347
  }
344
348
 
349
+ /**
350
+ * apra-fleet dolt-settle redesign (see fleet-sprint/docs/dolt-sync-redesign.md
351
+ * Part 5) -- thrown by settleDoltConflicts() when a member has no usable,
352
+ * correctly-pinned `dolt` binary and settle's own install/repair ladder
353
+ * (probe -> install -> kill-blocking-process-and-retry -> warn-and-fall-back-
354
+ * to-a-functionally-probed-alternative) could not produce one. This is an
355
+ * ordinary operational/infra failure under the existing degraded/fatal
356
+ * taxonomy -- NOT an escalation tier, exactly the same posture as
357
+ * DoltSyncError for "server wouldn't start". It is deliberately NOT thrown
358
+ * for the "wrong version but a functional fallback was found and passed its
359
+ * preflight" case (Part 5.6) -- that path proceeds with a warning instead;
360
+ * this error is reserved for "no runnable dolt at all" or "unsupported
361
+ * platform/arch with nothing usable already present".
362
+ *
363
+ * @property {string|null} member - the member with no usable dolt binary
364
+ * @property {string|null} probedPath - the path settle probed/attempted to install to
365
+ * @property {string|null} probeOutput - the raw probe/install failure output
366
+ * @property {string|null} repairCommand - the exact manual command an operator can run to fix this
367
+ */
368
+ export class DoltBinaryUnavailableError extends WorkflowError {
369
+ /**
370
+ * @param {string} message
371
+ * @param {{ member?: string|null, probedPath?: string|null, probeOutput?: string|null, repairCommand?: string|null, details?: object, cause?: unknown }} [opts]
372
+ */
373
+ constructor(message, opts = {}) {
374
+ const { member = null, probedPath = null, probeOutput = null, repairCommand = null, details, cause } = opts;
375
+ super(message, {
376
+ code: 'DOLT_BINARY_UNAVAILABLE',
377
+ details: { member, probedPath, probeOutput, repairCommand, ...details },
378
+ cause,
379
+ });
380
+ this.member = member;
381
+ this.probedPath = probedPath;
382
+ this.probeOutput = probeOutput;
383
+ this.repairCommand = repairCommand;
384
+ }
385
+ }
386
+
345
387
  // ---------------------------------------------------------------------------
346
388
  // Non-retryable dispatch failures (stabilization Issue 43 / smoke rehearsal)
347
389
  // ---------------------------------------------------------------------------
@@ -371,7 +413,8 @@ const NON_RETRYABLE_DISPATCH_RE = /authentication failed|not logged in|workspace
371
413
  */
372
414
  export function isNonRetryableDispatchError(err) {
373
415
  const reason = err?.details?.reason;
374
- if (reason === 'auth' || reason === 'workspace_not_trusted') return true;
416
+ if (reason === 'auth' || reason === 'workspace_not_trusted'
417
+ || reason === 'preflight_auth_missing' || reason === 'preflight_auth_expired') return true;
375
418
  return NON_RETRYABLE_DISPATCH_RE.test(String(err?.message ?? ''));
376
419
  }
377
420
 
@@ -389,7 +432,8 @@ const AUTH_DISPATCH_RE = /authentication failed|not logged in/i;
389
432
  * @returns {boolean}
390
433
  */
391
434
  export function isAuthDispatchError(err) {
392
- if (err?.details?.reason === 'auth') return true;
435
+ const reason = err?.details?.reason;
436
+ if (reason === 'auth' || reason === 'preflight_auth_missing' || reason === 'preflight_auth_expired') return true;
393
437
  return AUTH_DISPATCH_RE.test(String(err?.message ?? ''));
394
438
  }
395
439
 
@@ -424,7 +468,7 @@ export function isAuthDispatchError(err) {
424
468
  // check on an infra fault. Callers use this classifier to (a) retry once via a
425
469
  // session resume and (b) failing that, record the cycle as INCONCLUSIVE rather
426
470
  // than a test FAIL -- exactly as the part-2 stale-evidence path already does.
427
- const INFRA_DISPATCH_REASONS = new Set(['empty_response', 'dispatch_failed', 'orphan_recovery_timeout', 'stalled']);
471
+ const INFRA_DISPATCH_REASONS = new Set(['empty_response', 'dispatch_failed', 'orphan_recovery_timeout', 'stalled', 'preflight_offline']);
428
472
 
429
473
  /**
430
474
  * True when a dispatch error is an INFRASTRUCTURE failure (the member CLI never