@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
@@ -24,11 +24,13 @@ const POST_DISPATCH_SYNC_RETRY_DELAYS_MS = [0, 5000, 15000];
24
24
  const mockInstantRetryBackoff = () => process.env.APRA_FLEET_MOCK_INSTANT_RETRY_BACKOFF === '1';
25
25
  import { ApraFleet } from '@apralabs/apra-fleet-client';
26
26
  import { parseUnmergedPaths, detectAndAbortRebaseConflict, dispatchConflictResolutionAgent } from './conflict-ladder.mjs';
27
- // apra-fleet-vkc.1: the dolt conflict recovery ladder (Path A -> Path B ->
28
- // Tier 2). syncMemberAfterOrdered() builds it and threads it through
29
- // DoltSync.syncAfter() so a wedged beads clone at the post-dispatch D-push
30
- // terminal attempts recovery before surfacing BEADS_SYNC_CONFLICT.
31
- import { buildDoltRecoveryLadder } from './dolt-recovery-tier2.mjs';
27
+ // The deterministic dolt conflict settlement callback (docs/dolt-sync-
28
+ // redesign.md). It REPLACES the retired Path A -> Path B -> Tier 2 ladder at
29
+ // BOTH divergence terminals: the post-dispatch D-push bracket
30
+ // (syncMemberAfterOrdered) and the pre-dispatch D-pull / readiness gate, so a
31
+ // wedged beads clone self-heals instead of surfacing BEADS_SYNC_CONFLICT or
32
+ // hard-aborting the run at its readiness gate.
33
+ import { buildSettleCallback } from './dolt-settle.mjs';
32
34
  import { acquireSprintLock } from './sprint-lock.mjs';
33
35
  import { buildCreatePrCommand, resolveProvider, capabilities as vcsCapabilities, classifyFailure, toGitVerdict } from './vcs-module.mjs';
34
36
 
@@ -1114,33 +1116,22 @@ export async function syncMemberAfterOrdered(member, opts = {}) {
1114
1116
  // ordering above exists to prevent, and would erase the
1115
1117
  // BEADS_SYNC_CONFLICT terminal reason the dashboard reports.
1116
1118
  //
1117
- // apra-fleet-vkc.1: before that fatal divergence surfaces, attempt the
1118
- // Path A -> Tier 2 recovery ladder (Path B deliberately disabled here --
1119
- // see below). Path A's resolve-in-place sql runtime is not injected here
1120
- // (runner.js has no live dolt sql-server client), so in production Path A
1121
- // is reached and cleanly self-defers; Tier 2 dispatches through `agent`
1122
- // when one is available. The ladder only fails the streak
1123
- // (DoltDivergedError -> BEADS_SYNC_CONFLICT) if every enabled tier fails
1124
- // to close the clone.
1119
+ // Before that fatal divergence surfaces, run the deterministic settle
1120
+ // (settleDoltConflicts, dolt-settle.mjs). It is TOTAL over row-level
1121
+ // conflicts -- no gates, no allowlist, no LLM escalation -- and a resolved
1122
+ // settle is a VERIFIED recovery, because settle republishes (bd dolt pull
1123
+ // + push) and checks the push actually landed before returning. The streak
1124
+ // only fails (DoltDivergedError -> BEADS_SYNC_CONFLICT) when settle itself
1125
+ // hits an operational failure (no usable dolt binary, the ephemeral server
1126
+ // would not start, a SQL statement errored).
1125
1127
  //
1126
- // Path B (discard-and-re-bootstrap) is explicitly disabled
1127
- // (enablePathB: false) at THIS call site -- post-review fix, apra-fleet-
1128
- // vkc.1. syncMemberAfterOrdered() wraps an arbitrary, possibly
1129
- // multi-command agent dispatch (a doer/reviewer/planner streak), so there
1130
- // is no single well-defined `pendingMutation` this bracket could capture
1131
- // and replay. Without one, Path B's "replay the one pending mutation"
1132
- // step (dolt-recovery-path-b.mjs step 6) is a no-op, so firing it here
1133
- // would discard whatever bead mutations the dispatch just made on
1134
- // `member` and still report the D-push as recovered -- silent data loss
1135
- // masquerading as success. Path A (safe, gated, zero data loss when it
1136
- // fires) and Tier 2 (records + escalates, never discards) remain wired;
1137
- // only the unsafe fallback is turned off. See buildDoltRecoveryLadder's
1138
- // own doc comment (dolt-recovery-tier2.mjs) for the general hazard this
1139
- // guards against, and DoltSync.repair() for an explicit, operator-driven
1140
- // entry point where a real pendingMutation and member-scoped
1141
- // readConfig/removePath/listLocalState CAN be supplied deliberately.
1142
- const recover = buildDoltRecoveryLadder(member, { command, agent, log, model: resolveConflictModel, enablePathB: false });
1143
- const dPush = await DoltSync.syncAfter(member, { command, pushBeads, log, mutex, sprintId, onAuthFailure, fatal: true, recover });
1128
+ // Notably, the data-loss hazard that forced the old ladder's Path B to be
1129
+ // disabled at THIS call site does not exist for settle: it never discards
1130
+ // and re-bootstraps a clone, so an arbitrary multi-command dispatch's bead
1131
+ // mutations cannot be silently thrown away here. There is no pendingMutation
1132
+ // to capture and replay because nothing is ever dropped.
1133
+ const settle = buildSettleCallback(member, { command, log });
1134
+ const dPush = await DoltSync.syncAfter(member, { command, pushBeads, log, mutex, sprintId, onAuthFailure, fatal: true, settle });
1144
1135
  return { ok: true, member, gPush, dPush };
1145
1136
  }
1146
1137
 
@@ -1213,6 +1204,22 @@ export function createHttpDoltPushMutexClient(opts = {}) {
1213
1204
  return false;
1214
1205
  }
1215
1206
  },
1207
+ // Lease renewal (docs/dolt-sync-redesign.md Part 3.4): doltPushAfter()
1208
+ // renews on an interval while it holds the mutex, so a legitimately
1209
+ // long hold (push + reconcile + settle) is never force-evicted by the
1210
+ // supervisor's 60s lease expiry while this sprint is still pushing.
1211
+ async renew(token) {
1212
+ if (token == null) return false;
1213
+ const id = boundSprintId;
1214
+ if (!id) throw new Error('[dolt-mutex] renew requires a bound sprintId');
1215
+ try {
1216
+ const payload = await postJson(routeFor(id, 'renew'), { token });
1217
+ return Boolean(payload.renewed);
1218
+ } catch (err) {
1219
+ log(`[dolt-mutex] renew failed (non-fatal; the lease may expire): ${err.message}`);
1220
+ return false;
1221
+ }
1222
+ },
1216
1223
  };
1217
1224
  }
1218
1225
 
@@ -1382,6 +1389,18 @@ export function createMcpDoltPushMutexClient(opts = {}) {
1382
1389
  return false;
1383
1390
  }
1384
1391
  },
1392
+ // Same lease-renewal contract as the HTTP client above (design doc
1393
+ // Part 3.4); the fleet tool exposes action 'renew'.
1394
+ async renew(token) {
1395
+ if (token == null) return false;
1396
+ try {
1397
+ const payload = await call({ action: 'renew', token });
1398
+ return Boolean(payload.renewed);
1399
+ } catch (err) {
1400
+ log(`[dolt-mutex/mcp] renew failed (non-fatal; the lease may expire): ${err.message}`);
1401
+ return false;
1402
+ }
1403
+ },
1385
1404
  };
1386
1405
  }
1387
1406
 
@@ -1467,6 +1486,554 @@ export function createMcpChildIdAllocatorClient(opts = {}) {
1467
1486
  * @param {{ callTool: (name: string, args: object) => Promise<any>, members?: string[], sprintId?: string, log?: Function }} opts
1468
1487
  * @returns {{ reserveAll: () => Promise<void>, releaseAll: () => Promise<void> }}
1469
1488
  */
1489
+ /**
1490
+ * apra-fleet-e28 / KB trust pipeline Phase 2: KB priming for the fleet-sprint
1491
+ * engine, which had none -- it lived only in the Claude workflow copy.
1492
+ *
1493
+ * `callTool` is injected exactly like `createMemberReservationClient`'s, so this
1494
+ * stays transport-agnostic and unit-testable without a live fleet server.
1495
+ *
1496
+ * WHY PER MEMBER, NOT PER SPRINT: this engine has no repo path of its own. It
1497
+ * coordinates members by name and branch; the repo lives on each member's side,
1498
+ * possibly on a different host at a different path. `kb_session_prime` selects
1499
+ * WHICH project KB is read from its `repo_path`, and omitting that argument
1500
+ * falls back to the fleet server's own cwd -- collapsing every member's
1501
+ * knowledge into whichever repo the server happens to sit in, which is exactly
1502
+ * the apra-fleet-tm7 / apra-fleet-3zl repo-blindness defect. So the work folder
1503
+ * is resolved per member via `member_detail` (which reports it as `folder`) and
1504
+ * each member is primed against its own repo.
1505
+ *
1506
+ * Best-effort throughout, matching the reservation client's precedent: a member
1507
+ * whose folder cannot be resolved, or whose prime call fails, is logged and
1508
+ * skipped. A sprint must not fail because the KB is cold -- priming is an
1509
+ * optimisation, and every role contract's Step 0 already degrades gracefully
1510
+ * when the KB tools are unavailable.
1511
+ *
1512
+ * @param {{ callTool?: (name: string, args: object) => Promise<any>, members?: string[], log?: Function }} opts
1513
+ * @returns {{ primeAll: () => Promise<{primed: number, skipped: number}> }}
1514
+ */
1515
+ /**
1516
+ * Cap on primed entries carried into a dispatch prompt. kb_session_prime can
1517
+ * return up to ~28 (10 direct FTS hits + 3 global + 5 graph-neighbour + 5
1518
+ * project-bible + 5 global-bible); a dispatch prompt is not a place to spend
1519
+ * that much budget on context the role may not need, and the entries are
1520
+ * already returned in relevance order.
1521
+ */
1522
+ export const KB_MAX_KNOWLEDGE_ENTRIES = 12;
1523
+
1524
+ /**
1525
+ * The URL-based KB scope selector, spread into a kb_* call's arguments.
1526
+ *
1527
+ * repo_path alone is only sufficient for a LOCAL member: resolveProjectSlug
1528
+ * (src/services/knowledge/project-slug.ts) runs git in that directory to derive
1529
+ * the project slug. A remote member's work folder is a path on another host, so
1530
+ * both git probes fail and the slug degrades to 'default' -- collapsing every
1531
+ * remote member's knowledge into one shared KB. repo_remote_url selects the DB
1532
+ * directly (apra-fleet-b4g.1) and is what makes a sprint's kb_* calls land in
1533
+ * the member's own project KB.
1534
+ *
1535
+ * Absent when no URL is known: an omitted scope is the honest pre-existing
1536
+ * degradation, while a fabricated one routes writes into a slug that does not
1537
+ * match the repo's real local-clone slug. The engine never derives a URL -- it
1538
+ * forwards only what member_detail reports (knownRepoRemoteUrl's rule).
1539
+ */
1540
+ function kbScope(remoteUrl) {
1541
+ return (typeof remoteUrl === 'string' && remoteUrl.length > 0) ? { repo_remote_url: remoteUrl } : {};
1542
+ }
1543
+
1544
+ export function createKbPrimingClient(opts = {}) {
1545
+ const { callTool, members = [], log = () => {} } = opts;
1546
+ const active = typeof callTool === 'function' && members.length > 0;
1547
+
1548
+ function parseResult(result) {
1549
+ if (result && typeof result === 'string') { try { return JSON.parse(result); } catch { return null; } }
1550
+ if (result && Array.isArray(result.content) && result.content[0] && typeof result.content[0].text === 'string') {
1551
+ try { return JSON.parse(result.content[0].text); } catch { return null; }
1552
+ }
1553
+ return (result && typeof result === 'object') ? result : null;
1554
+ }
1555
+
1556
+ async function scopeFor(member) {
1557
+ // apra-fleet-n78: format:'json' is REQUIRED. member_detail defaults to
1558
+ // 'compact', whose renderer emits no folder at all -- `folder` is set only
1559
+ // on the json path (src/tools/member-detail.ts). Omitting it made this
1560
+ // return null for every member, so the KB was never primed for anyone.
1561
+ const detail = parseResult(await callTool('member_detail', { member_name: member, format: 'json' }));
1562
+ // member_detail reports the work folder as `folder` and the repo origin
1563
+ // URL as `repo_remote_url` (src/tools/member-detail.ts). The URL is
1564
+ // reported only when the member's registration record proves it, so an
1565
+ // absent one is normal and must stay absent rather than be derived here.
1566
+ const folder = detail && (detail.folder || (detail.member && detail.member.folder));
1567
+ const url = detail && (detail.repo_remote_url || (detail.member && detail.member.repo_remote_url));
1568
+ return {
1569
+ folder: (typeof folder === 'string' && folder.length > 0) ? folder : null,
1570
+ remoteUrl: (typeof url === 'string' && url.length > 0) ? url : null,
1571
+ };
1572
+ }
1573
+
1574
+ // member -> work folder, populated by primeAll(). createKbWorkClient reads
1575
+ // it so a capture lands in the repo the member actually worked in, rather
1576
+ // than being resolved against the fleet server's cwd.
1577
+ const folders = new Map();
1578
+
1579
+ // member -> the repo origin URL member_detail reported for it, when it
1580
+ // reported one. This is what scopes a REMOTE member's kb_* calls to its own
1581
+ // project KB instead of the shared 'default' one (see kbScope).
1582
+ const remoteUrls = new Map();
1583
+
1584
+ // work folder -> that folder's origin URL, or CONFLICTING_URL when two
1585
+ // members claim the same path string for DIFFERENT repos. The work client
1586
+ // resolves its scope through this map rather than taking the URL as an
1587
+ // extra argument at each of its nine call sites: threading the repo path is
1588
+ // then the same act as threading the scope, so a site cannot forget one
1589
+ // while remembering the other.
1590
+ const urlByFolder = new Map();
1591
+ const CONFLICTING_URL = Symbol('conflicting-remote-url');
1592
+
1593
+ // member -> the entries kb_session_prime returned for that member.
1594
+ //
1595
+ // KB audit 2026-08-11: primeAll() used to `await callTool(...)` and throw
1596
+ // the result away, on the assumption that priming "warms" something the
1597
+ // role's own Step 0 would later read. It does not: prime is a pure read,
1598
+ // and the role CANNOT repeat it -- a member-dispatched subagent has the
1599
+ // fleet MCP server disabled (src/providers/claude.ts
1600
+ // composePermissionConfig), so every contract's Step 0 kb_session_prime is
1601
+ // unreachable there. Nothing consumed the knowledge and nothing could, which
1602
+ // is why six sprints retrieved zero entries. Retaining the result is what
1603
+ // lets kbKnowledgeBlock() hand it to the role in its dispatch prompt --
1604
+ // the same shape of fix that made kb_promotions reachable.
1605
+ const knowledge = new Map();
1606
+
1607
+ return {
1608
+ folderOf(member) {
1609
+ return folders.get(member) || null;
1610
+ },
1611
+ remoteUrlOf(member) {
1612
+ return remoteUrls.get(member) || null;
1613
+ },
1614
+ /**
1615
+ * The URL scoping kb_* calls made against `repoPath`, or null.
1616
+ *
1617
+ * Null for an unknown path, for a local member (no URL was reported),
1618
+ * and for a path two members claim with different URLs. Members on
1619
+ * different hosts can share a work-folder path string while being
1620
+ * clones of different repos; picking either URL there would route one
1621
+ * member's captures into the other's KB, which is strictly worse than
1622
+ * the 'default' degradation this scoping exists to remove. Refusing
1623
+ * leaves that case exactly as it was before.
1624
+ */
1625
+ remoteUrlForPath(repoPath) {
1626
+ if (typeof repoPath !== 'string' || repoPath.length === 0) return null;
1627
+ const url = urlByFolder.get(repoPath);
1628
+ return (typeof url === 'string') ? url : null;
1629
+ },
1630
+ knowledgeOf(member) {
1631
+ return knowledge.get(member) || [];
1632
+ },
1633
+ async primeAll() {
1634
+ if (!active) return { primed: 0, skipped: members.length };
1635
+ let primed = 0;
1636
+ let skipped = 0;
1637
+ for (const member of members) {
1638
+ try {
1639
+ const { folder: repoPath, remoteUrl } = await scopeFor(member);
1640
+ if (repoPath) folders.set(member, repoPath);
1641
+ if (remoteUrl) remoteUrls.set(member, remoteUrl);
1642
+ if (repoPath && remoteUrl) {
1643
+ const known = urlByFolder.get(repoPath);
1644
+ if (known !== undefined && known !== remoteUrl) {
1645
+ urlByFolder.set(repoPath, CONFLICTING_URL);
1646
+ log(`[kb-prime] work folder ${repoPath} is claimed by two different repos -- KB calls for it stay unscoped`);
1647
+ } else {
1648
+ urlByFolder.set(repoPath, remoteUrl);
1649
+ }
1650
+ }
1651
+ if (!repoPath) {
1652
+ // No folder means no repo to scope the KB to. Priming without
1653
+ // one would read the fleet server's own KB, so skip instead.
1654
+ log(`[kb-prime] no work folder for member '${member}' -- skipping (KB stays cold)`);
1655
+ skipped++;
1656
+ continue;
1657
+ }
1658
+ // Land the committed bible in the WARM KB before priming.
1659
+ //
1660
+ // Without this the bible is reachable only through
1661
+ // kb_session_prime's cold-seed, which reads it as a FILE
1662
+ // and caps at 5 entries -- apra-fleet's own bible holds 17,
1663
+ // so a sprint could see at most 5 arbitrary ones and FTS
1664
+ // could rank none of them, because they were never rows.
1665
+ // Importing first is what gives the per-dispatch kb_query
1666
+ // (see relevantKnowledge) anything to match against.
1667
+ // Idempotent by id, and best-effort: a repo with no bible,
1668
+ // or an import that rejects every entry, must not stop the
1669
+ // prime it was meant to feed.
1670
+ //
1671
+ // skip_sweep IS LOAD-BEARING (audit 2026-08-12, caught by a
1672
+ // live sprint). kb_import's post-import freshnessSweep
1673
+ // re-judges the ENTIRE KB against this member's worktree. At
1674
+ // sprint start that staled 16 of 17 CONFIRMED entries purely
1675
+ // because the repo had moved on since capture, and the
1676
+ // damage cascaded: retrieval fell to one matchable entry,
1677
+ // kb_export attempted a 17 -> 9 bible truncation, and
1678
+ // kb_list (stale=0) returned an EMPTY promotion candidate
1679
+ // list -- reinstating apra-fleet-0ef, "kb_promote can never
1680
+ // fire". This import exists to WARM the KB, never to audit
1681
+ // it; prime()'s own bounded checkFreshness still guards each
1682
+ // entry it actually returns.
1683
+ try {
1684
+ const imported = parseResult(await callTool('kb_import', { repo_path: repoPath, ...kbScope(remoteUrl), skip_sweep: true }));
1685
+ if (imported && typeof imported.imported === 'number' && imported.imported > 0) {
1686
+ log(`[kb-prime] imported ${imported.imported} bible entr(ies) into the warm KB for ${repoPath}`);
1687
+ }
1688
+ } catch (err) {
1689
+ log(`[kb-prime] kb_import skipped for ${repoPath} (non-fatal): ${err.message}`);
1690
+ }
1691
+
1692
+ const primeResult = parseResult(await callTool('kb_session_prime', { repo_path: repoPath, ...kbScope(remoteUrl) }));
1693
+ const entries = (primeResult && Array.isArray(primeResult.top_entries))
1694
+ ? primeResult.top_entries.filter((e) => e && typeof e.id === 'string')
1695
+ : [];
1696
+ if (entries.length > 0) knowledge.set(member, entries.slice(0, KB_MAX_KNOWLEDGE_ENTRIES));
1697
+ primed++;
1698
+ } catch (err) {
1699
+ log(`[kb-prime] failed for member '${member}' (non-fatal): ${err.message}`);
1700
+ skipped++;
1701
+ }
1702
+ }
1703
+ if (primed > 0) log(`[kb-prime] primed ${primed} member repo(s)`);
1704
+ return { primed, skipped };
1705
+ },
1706
+ };
1707
+ }
1708
+
1709
+ /**
1710
+ * KB trust pipeline Phase 2, execution half for this engine.
1711
+ *
1712
+ * The role output schemas are SHARED with apra-pm (contracts.mjs loads them from
1713
+ * apra-pm/agents/schemas), so every role dispatched here is now asked for
1714
+ * kb_captures, and the reviewer for kb_promotions. Without a consumer those
1715
+ * fields would be silently dropped -- the knowledge would be gathered and
1716
+ * thrown away. This is that consumer.
1717
+ *
1718
+ * Unlike apra-pm's auto-sprint.js -- a Claude Workflow script with no tool
1719
+ * access, which must hand its vetted payload to an executor subagent -- this
1720
+ * engine runs in-process with an injected callTool, so it makes the kb_capture
1721
+ * and kb_promote calls DIRECTLY. Judgment still belongs to the role; execution
1722
+ * belongs here.
1723
+ *
1724
+ * Validation mirrors lib/vet-kb-work.mjs in apra-pm and the provider invariants
1725
+ * it reflects: a capture must cite at least one source file (SqliteProvider
1726
+ * rejects an entry the freshness sweep can never stale), a promotion needs a
1727
+ * recorded evidence string, and kb_promotions is refused from any role other
1728
+ * than reviewer -- widening capture to four roles must not widen promotion.
1729
+ *
1730
+ * @param {{ callTool?: (name: string, args: object) => Promise<any>, log?: Function }} opts
1731
+ * @returns {{ apply: (role: string, repoPath: string, result: any) => Promise<{captured: number, promoted: number, refused: number}> }}
1732
+ */
1733
+ export const KB_PROMOTER_ROLES = Object.freeze(new Set([ROLE_REVIEWER]));
1734
+ export const KB_MIN_PROMOTE_REASON = 20;
1735
+ export const KB_CAPTURE_TYPES = Object.freeze(['knowledge', 'learning', 'runbook']);
1736
+
1737
+ /**
1738
+ * True when an MCP tool result represents a tool-level failure. The MCP client
1739
+ * resolves such results instead of throwing (apra-fleet-23c), so callers that
1740
+ * only catch exceptions silently treat failures as successes.
1741
+ */
1742
+ function isToolError(res) {
1743
+ return !!(res && typeof res === 'object' && res.isError === true);
1744
+ }
1745
+
1746
+ /** Best-effort human-readable text out of an MCP error result, for logging. */
1747
+ function toolErrorText(res) {
1748
+ const first = res && Array.isArray(res.content) ? res.content[0] : null;
1749
+ return (first && typeof first.text === 'string' && first.text) || 'no error text returned';
1750
+ }
1751
+
1752
+ export function vetKbWork(role, result) {
1753
+ const captures = [];
1754
+ const promotions = [];
1755
+ const refused = [];
1756
+
1757
+ const rawCaptures = (result && Array.isArray(result.kb_captures)) ? result.kb_captures : [];
1758
+ for (const c of rawCaptures) {
1759
+ if (!c || typeof c.title !== 'string' || typeof c.summary !== 'string') {
1760
+ refused.push(`${role}: capture missing title/summary`);
1761
+ continue;
1762
+ }
1763
+ if (!Array.isArray(c.source_files) || c.source_files.length === 0) {
1764
+ refused.push(`${role}: capture "${c.title}" cites no source files`);
1765
+ continue;
1766
+ }
1767
+ if (!KB_CAPTURE_TYPES.includes(c.type)) {
1768
+ refused.push(`${role}: capture "${c.title}" has unsupported type ${String(c.type)}`);
1769
+ continue;
1770
+ }
1771
+ // apra-fleet-23c: kbCaptureSchema requires content (z.string().min(1)).
1772
+ // Omitting it here meant every kb_capture the engine sent failed zod
1773
+ // validation at the MCP boundary and persisted nothing.
1774
+ if (typeof c.content !== 'string' || c.content.trim().length === 0) {
1775
+ refused.push(`${role}: capture "${c.title}" has no content`);
1776
+ continue;
1777
+ }
1778
+ captures.push({
1779
+ type: c.type,
1780
+ title: c.title,
1781
+ summary: c.summary,
1782
+ content: c.content,
1783
+ source_files: c.source_files,
1784
+ symbols: Array.isArray(c.symbols) ? c.symbols : [],
1785
+ });
1786
+ }
1787
+
1788
+ const rawPromotions = (result && Array.isArray(result.kb_promotions)) ? result.kb_promotions : [];
1789
+ if (rawPromotions.length > 0 && !KB_PROMOTER_ROLES.has(role)) {
1790
+ refused.push(`${role}: kb_promotions refused -- promotion is reviewer-only`);
1791
+ } else {
1792
+ for (const p of rawPromotions) {
1793
+ if (!p || typeof p.id !== 'string' || p.id.length === 0) {
1794
+ refused.push(`${role}: promotion missing id`);
1795
+ continue;
1796
+ }
1797
+ if (typeof p.reason !== 'string' || p.reason.trim().length < KB_MIN_PROMOTE_REASON) {
1798
+ refused.push(`${role}: promotion ${p.id} has no recorded evidence`);
1799
+ continue;
1800
+ }
1801
+ promotions.push({ id: p.id, reason: p.reason.trim() });
1802
+ }
1803
+ }
1804
+
1805
+ return { captures, promotions, refused };
1806
+ }
1807
+
1808
+ /** Max promotion candidates offered to one reviewer, so the prompt stays bounded. */
1809
+ export const KB_MAX_PROMOTION_CANDIDATES = 40;
1810
+
1811
+ export function createKbWorkClient(opts = {}) {
1812
+ const { callTool, log = () => {}, remoteUrlFor } = opts;
1813
+ const active = typeof callTool === 'function';
1814
+
1815
+ /**
1816
+ * The URL-based KB scope for a repo path, resolved through the injected
1817
+ * lookup (createKbPrimingClient's remoteUrlForPath). Deliberately NOT an
1818
+ * extra parameter on the methods below: they are called from nine places
1819
+ * across runSprintCycle/finalReview/harvest, and an omitted argument is
1820
+ * indistinguishable from "no URL known" -- it would silently reinstate the
1821
+ * repo-blindness this exists to fix. With no lookup injected (every
1822
+ * construction site predating this, and direct unit calls) the scope is
1823
+ * absent and behaviour is exactly as before.
1824
+ */
1825
+ function scopeOf(repoPath) {
1826
+ return kbScope(typeof remoteUrlFor === 'function' ? remoteUrlFor(repoPath) : null);
1827
+ }
1828
+
1829
+ /** Best-effort JSON out of an MCP result (string, content-block, or plain object). */
1830
+ function parseResult(result) {
1831
+ if (typeof result === 'string') { try { return JSON.parse(result); } catch { return null; } }
1832
+ if (result && Array.isArray(result.content) && result.content[0] && typeof result.content[0].text === 'string') {
1833
+ try { return JSON.parse(result.content[0].text); } catch { return null; }
1834
+ }
1835
+ return (result && typeof result === 'object') ? result : null;
1836
+ }
1837
+
1838
+ return {
1839
+ /**
1840
+ * apra-fleet-0ef: the INFERRED entries this reviewer may promote.
1841
+ *
1842
+ * The engine's contract is "judgment belongs to the role, execution
1843
+ * belongs here" -- the reviewer returns `kb_promotions:[{id, reason}]`
1844
+ * and `apply()` calls kb_promote. But an entry id exists only inside
1845
+ * the KB, and the reviewer subagent has no apra-fleet MCP tools to
1846
+ * look one up, so it could never name an id: `kb_promotions` was
1847
+ * structurally always empty and nothing was ever promoted. (kb_captures
1848
+ * worked only because a capture needs no pre-existing id.) This is the
1849
+ * missing input: the engine reads the candidates and hands them to the
1850
+ * reviewer in its prompt.
1851
+ *
1852
+ * Best-effort by design -- a cold or unreachable KB must degrade to
1853
+ * "nothing to promote", never fail the review dispatch.
1854
+ */
1855
+ async promotionCandidates(repoPath) {
1856
+ // Without a repo path kb_list would resolve against the fleet
1857
+ // server's cwd and offer entries from an unrelated project's KB
1858
+ // (the apra-fleet-tm7 repo-blindness class). Refuse rather than guess.
1859
+ if (!active || !repoPath) return [];
1860
+ try {
1861
+ const parsed = parseResult(await callTool('kb_list', {
1862
+ repo_path: repoPath,
1863
+ ...scopeOf(repoPath),
1864
+ confidence: 'INFERRED',
1865
+ limit: KB_MAX_PROMOTION_CANDIDATES,
1866
+ }));
1867
+ const results = parsed && Array.isArray(parsed.results) ? parsed.results : [];
1868
+ return results
1869
+ // promote() refuses type='user-directive' outright (activation
1870
+ // is human-terminal, CLI-only), so offering one as a candidate
1871
+ // can only produce a guaranteed refusal.
1872
+ .filter((e) => e && typeof e.id === 'string' && e.type !== 'user-directive')
1873
+ .slice(0, KB_MAX_PROMOTION_CANDIDATES);
1874
+ } catch (err) {
1875
+ log(`[kb-work] could not list promotion candidates for ${repoPath} (non-fatal): ${err.message}`);
1876
+ return [];
1877
+ }
1878
+ },
1879
+ /**
1880
+ * KB audit follow-up: the per-dispatch, relevance-ranked read.
1881
+ *
1882
+ * primeAll() runs ONCE per member at sprint start with no hints, so
1883
+ * every role received the same handful of entries no matter what it was
1884
+ * about to work on -- and kb_query went unused by this engine entirely.
1885
+ * This asks the KB what it knows about THIS dispatch, using the terms
1886
+ * the engine already holds (bead ids and their titles).
1887
+ *
1888
+ * `expand_related` is what finally reads the KB's own graph. The KB has
1889
+ * been writing `refines` and `contradiction_of` edges since AUDN
1890
+ * shipped and traversing none of them: 554 edges, 0 reads. A role about
1891
+ * to act on an entry is precisely who needs to know that entry has a
1892
+ * newer framing or a standing dispute -- especially since confidence
1893
+ * tier does NOT track correctness across a contradiction chain (the
1894
+ * warehouse chain-A shape, where the incorrect entry outranks both of
1895
+ * its corrections).
1896
+ *
1897
+ * Best-effort, like every other KB read here: no repo path, no terms, a
1898
+ * cold KB or an unreachable one all degrade to "no knowledge", never to
1899
+ * a failed dispatch.
1900
+ */
1901
+ async relevantKnowledge(repoPath, terms) {
1902
+ if (!active || !repoPath || !Array.isArray(terms) || terms.length === 0) return [];
1903
+ const query = terms.filter((t) => typeof t === 'string' && t.trim()).join(' ');
1904
+ if (!query) return [];
1905
+ try {
1906
+ const parsed = parseResult(await callTool('kb_query', {
1907
+ repo_path: repoPath,
1908
+ ...scopeOf(repoPath),
1909
+ query,
1910
+ limit: KB_MAX_KNOWLEDGE_ENTRIES,
1911
+ expand_related: true,
1912
+ }));
1913
+ if (!parsed) return [];
1914
+ const hits = Array.isArray(parsed.l1_results) ? parsed.l1_results : [];
1915
+ const related = Array.isArray(parsed.related_claims) ? parsed.related_claims : [];
1916
+ const seen = new Set();
1917
+ const out = [];
1918
+ for (const e of hits) {
1919
+ if (!e || typeof e.id !== 'string' || seen.has(e.id)) continue;
1920
+ seen.add(e.id);
1921
+ out.push(e);
1922
+ }
1923
+ // Related claims sit BELOW every direct hit and carry a marker,
1924
+ // so a role can tell "the KB matched this" from "the KB says
1925
+ // something about what it matched".
1926
+ for (const e of related) {
1927
+ if (!e || typeof e.id !== 'string' || seen.has(e.id)) continue;
1928
+ seen.add(e.id);
1929
+ out.push({ ...e, via: 'kb-graph' });
1930
+ }
1931
+ return out.slice(0, KB_MAX_KNOWLEDGE_ENTRIES);
1932
+ } catch (err) {
1933
+ log(`[kb-work] kb_query failed for ${repoPath} (non-fatal): ${err.message}`);
1934
+ return [];
1935
+ }
1936
+ },
1937
+ async apply(role, repoPath, result) {
1938
+ const { captures, promotions, refused } = vetKbWork(role, result);
1939
+
1940
+ for (const r of refused) log(`[kb-work] refused -- ${r}`);
1941
+ // Log every promotion with its stated evidence BEFORE attempting it.
1942
+ // This log is the audit trail the bible never had.
1943
+ for (const p of promotions) log(`[kb-work] promote ${p.id} (${role}): ${p.reason}`);
1944
+
1945
+ // Without a repo path a capture would land in whichever KB the fleet
1946
+ // server's cwd resolves to -- the tm7 defect. Refuse rather than guess.
1947
+ if (!active || !repoPath) {
1948
+ if ((captures.length || promotions.length) && !repoPath) {
1949
+ log(`[kb-work] no repo path for ${role} -- ${captures.length} capture(s) and ${promotions.length} promotion(s) dropped`);
1950
+ }
1951
+ return { captured: 0, promoted: 0, refused: refused.length };
1952
+ }
1953
+
1954
+ let captured = 0;
1955
+ let promoted = 0;
1956
+ for (const c of captures) {
1957
+ try {
1958
+ const res = await callTool('kb_capture', { ...c, repo_path: repoPath, ...scopeOf(repoPath) });
1959
+ // apra-fleet-23c: an MCP client RESOLVES with {isError:true} on a
1960
+ // tool-level failure rather than throwing, so counting every
1961
+ // non-throwing call as a success reported captures that never
1962
+ // persisted ("captured 3" against a KB that stayed empty).
1963
+ if (isToolError(res)) {
1964
+ log(`[kb-work] kb_capture rejected for "${c.title}" (non-fatal): ${toolErrorText(res)}`);
1965
+ continue;
1966
+ }
1967
+ captured++;
1968
+ } catch (err) {
1969
+ log(`[kb-work] kb_capture failed for "${c.title}" (non-fatal): ${err.message}`);
1970
+ }
1971
+ }
1972
+ for (const p of promotions) {
1973
+ try {
1974
+ // apra-fleet-0ef: repo_path is REQUIRED here, exactly as on
1975
+ // the kb_capture call above. Omitting it resolved the
1976
+ // promotion against the fleet server's cwd -- a different
1977
+ // project's KB, where the id does not exist -- so every
1978
+ // promotion would have failed "Entry not found" (the
1979
+ // apra-fleet-tm7 repo-blindness class, fixed for capture
1980
+ // but missed here).
1981
+ const res = await callTool('kb_promote', { id: p.id, reason: p.reason, repo_path: repoPath, ...scopeOf(repoPath) });
1982
+ if (isToolError(res)) {
1983
+ log(`[kb-work] kb_promote rejected for ${p.id} (non-fatal): ${toolErrorText(res)}`);
1984
+ continue;
1985
+ }
1986
+ promoted++;
1987
+ } catch (err) {
1988
+ log(`[kb-work] kb_promote failed for ${p.id} (non-fatal): ${err.message}`);
1989
+ }
1990
+ }
1991
+ if (captured || promoted) log(`[kb-work] ${role}: captured ${captured}, promoted ${promoted}`);
1992
+ return { captured, promoted, refused: refused.length };
1993
+ },
1994
+
1995
+ /**
1996
+ * KB audit 2026-08-11: publish this repo's CONFIRMED set to its
1997
+ * canonical bible (<repo>/.fleet/kb-canonical.json).
1998
+ *
1999
+ * Nothing in the pipeline had ever called kb_export, so a bible existed
2000
+ * only where an operator had run the tool by hand -- 1 of 17 repos on
2001
+ * the audited machine. Promotion therefore ended at the local sqlite
2002
+ * store: a teammate, a fresh clone, or a member on another host saw
2003
+ * none of it, and kb_session_prime's cold-seed (which reads exactly
2004
+ * this file) had nothing to fall back on. Promotion is the sprint's
2005
+ * work; publishing it is the step that makes the work leave the
2006
+ * machine.
2007
+ *
2008
+ * Called once, AFTER the final review's promotions have been applied,
2009
+ * so the bible reflects everything this sprint confirmed. Best-effort
2010
+ * like every other KB call here: a sprint must never fail over an
2011
+ * export, and the tool itself is a no-op when the entry set is
2012
+ * unchanged. Committing/pushing the file stays a separate, opt-in
2013
+ * decision (kb_export's own autoCommit config) -- this does not widen
2014
+ * the engine's git authority.
2015
+ */
2016
+ async exportBible(repoPath) {
2017
+ // Same repo-blindness guard as every other call here: without a
2018
+ // path kb_export would resolve against the fleet server's cwd and
2019
+ // write an unrelated project's bible.
2020
+ if (!active || !repoPath) return false;
2021
+ try {
2022
+ const res = await callTool('kb_export', { repo_path: repoPath, ...scopeOf(repoPath) });
2023
+ if (isToolError(res)) {
2024
+ log(`[kb-work] kb_export rejected for ${repoPath} (non-fatal): ${toolErrorText(res)}`);
2025
+ return false;
2026
+ }
2027
+ log(`[kb-work] exported the canonical bible for ${repoPath}`);
2028
+ return true;
2029
+ } catch (err) {
2030
+ log(`[kb-work] kb_export failed for ${repoPath} (non-fatal): ${err.message}`);
2031
+ return false;
2032
+ }
2033
+ },
2034
+ };
2035
+ }
2036
+
1470
2037
  export function createMemberReservationClient(opts = {}) {
1471
2038
  const { callTool, members = [], sprintId, log = () => {} } = opts;
1472
2039
  const active = typeof callTool === 'function' && typeof sprintId === 'string' && sprintId.length > 0 && members.length > 0;
@@ -1681,7 +2248,10 @@ async function provisionPrCapableAuthForMember({ fleetApi, command, member, log
1681
2248
  // `label` is passed (src/tools/provision-vcs-auth.ts: `label = input.label ??
1682
2249
  // input.provider`) -- the PR-raising call sites never pass a label either, so
1683
2250
  // the deployed git-credential-helper file is always
1684
- // $HOME/.fleet-git-credential-github for the 'github' provider.
2251
+ // $HOME/.fleet-git-credential-github for the 'github' provider on POSIX
2252
+ // (src/os/linux.ts gitCredentialHelperWrite), and
2253
+ // $env:USERPROFILE\.fleet-git-credential-github.bat on Windows
2254
+ // (src/os/windows.ts:279-294).
1685
2255
  const GITHUB_VCS_CREDENTIAL_LABEL = 'github';
1686
2256
 
1687
2257
  // Typed marker returned by finalizeAbort() (and logged by the Publish PR step)
@@ -1692,9 +2262,165 @@ const GITHUB_VCS_CREDENTIAL_LABEL = 'github';
1692
2262
  // this exact reason string. See apra-fleet-tfx.8.1.
1693
2263
  const PR_SKIPPED_NO_MCP_CLIENT = 'pr-skipped-no-mcp-client';
1694
2264
 
2265
+ // memberName -> resolved target OS ('windows' | 'linux' | 'darwin' | ...),
2266
+ // cached for the lifetime of the runner process: a member's OS never changes
2267
+ // mid-sprint, and member_detail performs a live connectivity check, so this
2268
+ // must not be re-dispatched per credential read (raiseVcsPrForMember can call
2269
+ // it twice on the auth-retry path alone).
2270
+ const memberOsCache = new Map();
2271
+
2272
+ // Test seam: the OS cache is process-lifetime state, so a test exercising two
2273
+ // different member OSes for the same member name must be able to clear it.
2274
+ export function clearMemberOsCache() {
2275
+ memberOsCache.clear();
2276
+ }
2277
+
2278
+ // Resolves `member`'s OS from the fleet member registry via
2279
+ // fleetApi.memberDetail() ('member_detail' is the only MCP surface exposing
2280
+ // Agent.os -- src/tools/member-detail.ts:40; it does NOT expose a homeDir).
2281
+ // Mirrors VCSModule.resolveProvider()'s member_detail JSON-parsing shape.
2282
+ //
2283
+ // Unlike resolveProvider, an unresolvable OS is NOT a hard error here: the
2284
+ // ONLY behavioral difference it drives is which shell string the credential
2285
+ // read is built as, and the historical (POSIX) string must stay byte-identical
2286
+ // for every non-Windows member and for any caller that has no memberDetail
2287
+ // wired. So a missing/unparseable/absent-`os` response degrades to 'linux'
2288
+ // (the pre-existing behavior) and is logged, never thrown.
2289
+ // @param {{ fleetApi?: object, member: string, log?: Function }} opts
2290
+ // @returns {Promise<string>}
2291
+ export async function resolveMemberOs({ fleetApi, member, log = () => {} }) {
2292
+ if (memberOsCache.has(member)) return memberOsCache.get(member);
2293
+ try {
2294
+ if (!fleetApi || typeof fleetApi.memberDetail !== 'function') {
2295
+ throw new Error('no fleetApi.memberDetail() injected');
2296
+ }
2297
+ const res = await fleetApi.memberDetail({ member_name: member, format: 'json' });
2298
+ const text = typeof res === 'string'
2299
+ ? res
2300
+ : (res && Array.isArray(res.content) && res.content[0] && typeof res.content[0].text === 'string')
2301
+ ? res.content[0].text
2302
+ : '';
2303
+ const parsed = JSON.parse(text);
2304
+ if (parsed && typeof parsed.os === 'string' && parsed.os.trim()) {
2305
+ const os = parsed.os.trim().toLowerCase();
2306
+ // Only a genuine member_detail-derived OS is cached. Caching the
2307
+ // 'linux' fallback below would permanently pin a member that hit a
2308
+ // transient failure (asleep, flaky SSH, MCP hiccup) to POSIX
2309
+ // command construction for the rest of the runner process --
2310
+ // including the auth-retry credential read at raiseVcsPrForMember,
2311
+ // whose entire purpose is to recover from exactly this kind of
2312
+ // transient failure. See apra-fleet-ot2z.13.
2313
+ memberOsCache.set(member, os);
2314
+ return os;
2315
+ }
2316
+ throw new Error('member_detail response carried no "os" field');
2317
+ } catch (err) {
2318
+ log(`Could not resolve OS for member '${member}' from member_detail (${err && err.message ? err.message : err}); assuming POSIX ('linux') for member-bound command construction.`);
2319
+ return 'linux';
2320
+ }
2321
+ }
2322
+
2323
+ // Wraps a PowerShell script the same way src/os/windows.ts
2324
+ // wrapPowerShellEncoded() does: the guard clause makes a non-terminating
2325
+ // PowerShell failure surface as a non-zero exit (apra-fleet-ot2z.9's fix),
2326
+ // -EncodedCommand (base64 UTF-16LE) removes every quoting question about
2327
+ // which shell the transport hands the string to, and the $LASTEXITCODE check
2328
+ // before the trailing `exit 0` preserves a native command's exit code (e.g.
2329
+ // this file's own credential-read `& "<helper>.bat"` invocation below) that
2330
+ // would otherwise be masked -- without it, a broken credential-helper .bat
2331
+ // silently reports success with no `password=` line. runner.js is a separate
2332
+ // package and cannot import src/os/windows.ts, so the shape is mirrored
2333
+ // here, not reused.
2334
+ // @param {string} psScript
2335
+ // @returns {string}
2336
+ function wrapPowerShellEncodedForMember(psScript) {
2337
+ const guarded = `$ErrorActionPreference = 'Stop'; try { ${psScript}; if ($LASTEXITCODE -ne $null -and $LASTEXITCODE -ne 0) { exit $LASTEXITCODE }; exit 0 } catch { Write-Error $_; exit 1 }`;
2338
+ return `powershell -EncodedCommand ${Buffer.from(guarded, 'utf16le').toString('base64')}`;
2339
+ }
2340
+
2341
+ // Builds the member-bound command that RUNS the deployed git-credential-helper
2342
+ // and the human-readable descriptor used in this function's error messages
2343
+ // (the descriptor must stay readable -- the Windows command itself is an
2344
+ // opaque base64 blob).
2345
+ //
2346
+ // SHELL CONTRACT (confirmed, not assumed -- apra-fleet-ot2z.1):
2347
+ // execute_command hands the caller's string to
2348
+ // cmds.wrapPidCapture(cmds.wrapInWorkFolder(folder, cmd)) and then straight
2349
+ // to the strategy's execCommand (src/tools/execute-command.ts:273 ->
2350
+ // src/services/ssh.ts execCommand, which does NO shell branching of its
2351
+ // own). wrapInWorkFolder/wrapPidCapture (src/os/windows.ts:328-335) still
2352
+ // emit RAW PowerShell text (`Set-Location "<folder>"; ...`,
2353
+ // `Write-Output "FLEET_PID:$pid"; ...`), NOT shell-normalized/encoded --
2354
+ // they are NOT wrapped with -EncodedCommand, so on a Windows member whose
2355
+ // sshd default shell is cmd.exe (not PowerShell) that outer wrapping is
2356
+ // still garbage regardless of what this function returns. This function's
2357
+ // own return value (the inner payload wrapPidCapture/wrapInWorkFolder wrap
2358
+ // around) IS explicitly -EncodedCommand and is valid to launch from either
2359
+ // PowerShell or cmd.exe on its own -- but that only protects the inner
2360
+ // payload, not the outer Set-Location/Write-Output wrapper the codebase
2361
+ // composes around it. Correctness end-to-end still depends on the target
2362
+ // member's default shell being PowerShell.
2363
+ // TODO: normalize wrapInWorkFolder/wrapPidCapture (and
2364
+ // gitCredentialHelperWrite/gitCredentialHelperRemove/deploySSHPublicKey,
2365
+ // which have the same raw-PowerShell issue on the write side) through a
2366
+ // single shell-detecting wrapper so the whole composite string -- not just
2367
+ // this function's inner payload -- is shell-agnostic.
2368
+ //
2369
+ // WHY $env:USERPROFILE AND NOT A JS-RESOLVED HOME PATH: the WRITE side
2370
+ // (src/os/windows.ts:289 gitCredentialHelperWrite) writes the helper to
2371
+ // `"$env:USERPROFILE\.fleet-git-credential-<label>.bat"` -- expanded ON THE
2372
+ // MEMBER at write time. The read must resolve the home directory the same way
2373
+ // the write did, or an independently-probed home could point somewhere the
2374
+ // file was never written. This mirrors member-home.ts probeCommandFor(), which
2375
+ // likewise resolves the OS in JS and interpolates a shell-appropriate string
2376
+ // that still contains $env:USERPROFILE.
2377
+ // RUNNER-WIDE POSIX-EXPANSION SWEEP (apra-fleet-ot2z.1, WORK item 2): every
2378
+ // runner.js string passed to command()/execute_command was audited for `$VAR`,
2379
+ // `~/`, backticks, `$( )` and POSIX-only shell plumbing (`&&`/`||` chains,
2380
+ // `2>/dev/null`, `test -f`, pipes). Result: the credential read below was the
2381
+ // ONLY member-bound string carrying a shell expansion. The surviving `$`
2382
+ // occurrences in this file are all justified in place --
2383
+ // - NOT_DONE_STATUSES (~line 278): quoting note about PowerShell's $OFS, a
2384
+ // comment, not an expansion in the dispatched string;
2385
+ // - wrapPowerShellEncodedForMember (~line 1761) and the Windows branch
2386
+ // below: deliberately PowerShell, base64-encoded so no host shell ever
2387
+ // re-parses them;
2388
+ // - the POSIX branch below: `$HOME` expanded by the POSIX member's own
2389
+ // shell, matching what src/os/linux.ts wrote.
2390
+ // Everything else dispatched to a member is plain `git`/`bd`/`node -e`
2391
+ // argv-shaped text (see stageCommandBodyMemberSide ~line 2195 and the
2392
+ // two-sequential-calls note at ~line 5685, which already document why they
2393
+ // avoid `&&` and `$`), inert across POSIX, PowerShell and cmd.exe.
2394
+ // @param {string} os
2395
+ // @param {string} label
2396
+ // @returns {{ command: string, descriptor: string }}
2397
+ export function buildCredentialReadCommand(os, label) {
2398
+ if (os === 'windows') {
2399
+ // The label is interpolated into a PowerShell double-quoted string and
2400
+ // a filename; the POSIX branch below is unvalidated for byte-identical
2401
+ // back-compat, but there is no reason to admit shell metacharacters on
2402
+ // the branch being introduced here.
2403
+ if (!/^[A-Za-z0-9._-]+$/.test(String(label))) {
2404
+ throw new Error(`Refusing to build a Windows credential-read command for unsafe VCS credential label '${label}' (allowed: letters, digits, '.', '_', '-').`);
2405
+ }
2406
+ const descriptor = `$env:USERPROFILE\\.fleet-git-credential-${label}.bat`;
2407
+ // `& "<path>"` -- the call operator, so PowerShell EXECUTES the batch
2408
+ // file (and its "password=<token>" line reaches stdout) instead of
2409
+ // echoing the path as a string.
2410
+ return { command: wrapPowerShellEncodedForMember(`& "$env:USERPROFILE\\.fleet-git-credential-${label}.bat"`), descriptor };
2411
+ }
2412
+ // POSIX (linux/darwin): byte-identical to the pre-apra-fleet-ot2z.1
2413
+ // string. $HOME (not `~`) matches what src/os/linux.ts
2414
+ // gitCredentialHelperWrite() wrote and chmod +x'd.
2415
+ const credFile = `$HOME/.fleet-git-credential-${label}`;
2416
+ return { command: credFile, descriptor: credFile };
2417
+ }
2418
+
1695
2419
  // Reads the raw token back out of the git-credential-helper script
1696
2420
  // provision_vcs_auth just deployed onto `member`'s filesystem
1697
- // ($HOME/.fleet-git-credential-<label>, an executable script that PRINTS
2421
+ // ($HOME/.fleet-git-credential-<label> on POSIX, or
2422
+ // $env:USERPROFILE\.fleet-git-credential-<label>.bat on Windows -- see
2423
+ // buildCredentialReadCommand above; an executable script that PRINTS
1698
2424
  // "protocol=...\nhost=...\nusername=...\npassword=<token>\n" when run -- see
1699
2425
  // src/os/linux.ts gitCredentialHelperWrite()/src/os/windows.ts). This is the
1700
2426
  // ONLY way an orchestrator-side caller (VCSModule's runner.js callers) can
@@ -1706,11 +2432,14 @@ const PR_SKIPPED_NO_MCP_CLIENT = 'pr-skipped-no-mcp-client';
1706
2432
  // itself is never logged/echoed anywhere (the token value briefly transits
1707
2433
  // this one command's captured stdout, held only in-process, and is used
1708
2434
  // immediately to build the VCSModule command).
1709
- // @param {{ command: Function, member: string, label?: string }} opts
2435
+ // Both the POSIX helper script and the Windows .bat print the same
2436
+ // "password=<token>" line, so the extraction regex below is OS-independent.
2437
+ // @param {{ command: Function, member: string, label?: string, fleetApi?: object, log?: Function }} opts
1710
2438
  // @returns {Promise<string>}
1711
- async function readMemberVcsCredentialToken({ command, member, label = GITHUB_VCS_CREDENTIAL_LABEL }) {
1712
- const credFile = `$HOME/.fleet-git-credential-${label}`;
1713
- const res = await command(`${credFile}`, {
2439
+ async function readMemberVcsCredentialToken({ command, member, label = GITHUB_VCS_CREDENTIAL_LABEL, fleetApi, log = () => {} }) {
2440
+ const os = await resolveMemberOs({ fleetApi, member, log });
2441
+ const { command: credCommand, descriptor: credFile } = buildCredentialReadCommand(os, label);
2442
+ const res = await command(credCommand, {
1714
2443
  member_name: member,
1715
2444
  silent: true,
1716
2445
  failSoft: true,
@@ -1792,12 +2521,13 @@ async function raiseVcsPrForMember({ fleetApi, command, member, base, head, titl
1792
2521
  if (!repo) {
1793
2522
  throw new Error(`Could not derive an owner/repo from member '${member}' git remote -- cannot build a VCSModule create-pull-request command without one.`);
1794
2523
  }
1795
- let token = await readMemberVcsCredentialToken({ command, member });
2524
+ let token = await readMemberVcsCredentialToken({ command, member, fleetApi, log });
2525
+ const os = await resolveMemberOs({ fleetApi, member, log });
1796
2526
 
1797
2527
  let authHealAttempted = false;
1798
2528
  // eslint-disable-next-line no-constant-condition
1799
2529
  while (true) {
1800
- const built = buildCreatePrCommand({ provider: 'github', repo, base, head, title, body, token });
2530
+ const built = buildCreatePrCommand({ provider: 'github', repo, base, head, title, body, token, os });
1801
2531
 
1802
2532
  const res = await command(built.command, {
1803
2533
  member_name: member,
@@ -1837,7 +2567,7 @@ async function raiseVcsPrForMember({ fleetApi, command, member, base, head, titl
1837
2567
  try {
1838
2568
  const reprov = await provisionPrCapableAuthForMember({ fleetApi, command, member, log, logPrefix });
1839
2569
  if (reprov.repo) repo = reprov.repo;
1840
- token = await readMemberVcsCredentialToken({ command, member });
2570
+ token = await readMemberVcsCredentialToken({ command, member, fleetApi, log });
1841
2571
  } catch (healErr) {
1842
2572
  log(`${logPrefix}: PR auth self-heal failed for member '${member}'; not retrying further: ${healErr.message}`);
1843
2573
  return { ok: false, alreadyExists: false, prUrl: null, error: `HTTP ${status ?? '(unknown)'}: ${errorText}`, authFailure: true };
@@ -1908,6 +2638,126 @@ export function createMemberVcsProviderResolver(opts = {}) {
1908
2638
  };
1909
2639
  }
1910
2640
 
2641
+ /**
2642
+ * Best-effort provisions a member for unattended execution (`unattended:
2643
+ * 'auto'`) before dispatching it as deployer, integ-test-runner, or
2644
+ * regression-test-runner -- roles that run real deploy commands and test
2645
+ * suites via a runbook and must never stall on an interactive permission
2646
+ * prompt. Provisioning is a one-way member-registration change and is
2647
+ * deliberately NOT reverted after the dispatch: `unattended` lives on the
2648
+ * member (update_member), not on the dispatch, so there is nothing to revert
2649
+ * to without also clobbering whatever the user set intentionally. In a
2650
+ * single-member sprint the same member also plays doer/reviewer/etc, so it
2651
+ * ends up unattended='auto' too -- accepted, not a bug.
2652
+ *
2653
+ * Cached per member for the lifetime of the returned function, so a sprint
2654
+ * with many deploy/integ/regression dispatches across cycles calls
2655
+ * update_member at most once per member. A failure (fleet unreachable,
2656
+ * member not found) is logged and swallowed -- exactly like
2657
+ * createMemberVcsProviderResolver above -- so a provisioning hiccup degrades
2658
+ * to whatever permission mode the member already had, rather than aborting
2659
+ * the phase.
2660
+ *
2661
+ * `callTool` is injected (the caller's MCP client), so this stays
2662
+ * transport-agnostic and unit-testable without a live fleet server.
2663
+ *
2664
+ * @param {{ callTool: (name: string, args: object) => Promise<any>, log?: Function }} opts
2665
+ * @returns {(member: string) => Promise<void>}
2666
+ */
2667
+ export function createUnattendedAutoProvisioner(opts = {}) {
2668
+ const { callTool, log = () => {} } = opts;
2669
+ const fleetApi = new ApraFleet({ callTool });
2670
+ /** @type {Set<string>} members already confirmed unattended='auto' this run. */
2671
+ const provisioned = new Set();
2672
+
2673
+ return async function ensureUnattendedAuto(member) {
2674
+ if (provisioned.has(member)) return;
2675
+ try {
2676
+ await fleetApi.updateMember({ member_name: member, unattended: 'auto' });
2677
+ provisioned.add(member);
2678
+ log(`[unattended] member '${member}' set to unattended='auto' for this dispatch.`);
2679
+ } catch (err) {
2680
+ log(`[unattended] could not set unattended='auto' on member '${member}' (continuing with its existing permission mode): ${err.message}`);
2681
+ }
2682
+ };
2683
+ }
2684
+
2685
+ /**
2686
+ * Best-effort, self-heals the "Missing permission" class of deploy/integ/
2687
+ * regression-test failure BEFORE it happens: reads deploy.md's own
2688
+ * `## Permissions` section -- the exact list the deployer/integ-test-runner/
2689
+ * regression-test-runner agent prompts already cross-check at their own
2690
+ * Step 0a/0 -- and proactively grants every listed prefix to the target
2691
+ * member via compose_permissions. Without this, a runbook permissions
2692
+ * change (e.g. the `apra-fleet start` -> `apra-fleet run` swap, #395) only
2693
+ * gets noticed when a dispatch fails, and only gets fixed once an operator
2694
+ * greps deploy.md by hand and runs compose_permissions manually -- exactly
2695
+ * the failure mode this closes the loop on.
2696
+ *
2697
+ * Reads deploy.md via `command()` against the ORCHESTRATOR member (its own
2698
+ * checkout is the source of truth for what is about to be dispatched) and
2699
+ * caches the parsed prefix list for the lifetime of the returned function --
2700
+ * one read per sprint run, since deploy.md does not change mid-run on a
2701
+ * healthy pipeline. Also caches per TARGET member, like
2702
+ * createUnattendedAutoProvisioner above, so repeat cycles don't re-grant.
2703
+ *
2704
+ * Failure at any step (probe fails, deploy.md missing/unparseable,
2705
+ * compose_permissions unreachable, a listed prefix hitting the
2706
+ * NEVER_AUTO_GRANT denylist) is logged and swallowed. This is pure
2707
+ * best-effort acceleration -- the deployer's own Step 0a check remains the
2708
+ * authoritative, fail-closed backstop regardless of whether this succeeds.
2709
+ *
2710
+ * @param {{ callTool: (name: string, args: object) => Promise<any>, command: Function, orchestratorMember: string, log?: Function }} opts
2711
+ * @returns {(member: string) => Promise<void>}
2712
+ */
2713
+ export function createDeployPermissionsProvisioner(opts = {}) {
2714
+ const { callTool, command, orchestratorMember, log = () => {} } = opts;
2715
+ const fleetApi = new ApraFleet({ callTool });
2716
+ /** @type {Set<string>} members already granted deploy.md's permissions this run. */
2717
+ const provisioned = new Set();
2718
+ /** @type {string[] | null | undefined} undefined = not yet attempted. */
2719
+ let cachedPrefixes;
2720
+
2721
+ async function loadRequiredPrefixes() {
2722
+ if (cachedPrefixes !== undefined) return cachedPrefixes;
2723
+ try {
2724
+ const res = await command(
2725
+ `node -e "const fs=require('fs'); if(fs.existsSync('deploy.md')) process.stdout.write(fs.readFileSync('deploy.md','utf8'))"`,
2726
+ { member_name: orchestratorMember, silent: true, label: `Read deploy.md permissions`, failSoft: true },
2727
+ );
2728
+ if (!res.ok || !res.output) {
2729
+ cachedPrefixes = null;
2730
+ } else {
2731
+ const section = res.output.split(/^## Permissions/m)[1]?.split(/^## /m)[0] ?? '';
2732
+ const prefixes = [...section.matchAll(/^-\s*`([^`]+)`/gm)].map(m => m[1]);
2733
+ cachedPrefixes = prefixes.length ? prefixes : null;
2734
+ }
2735
+ } catch (err) {
2736
+ log(`[deploy-permissions] could not read deploy.md's Permissions section (continuing without auto-provisioning): ${err.message}`);
2737
+ cachedPrefixes = null;
2738
+ }
2739
+ return cachedPrefixes;
2740
+ }
2741
+
2742
+ return async function ensureDeployPermissions(member) {
2743
+ if (!member || provisioned.has(member)) return;
2744
+ const prefixes = await loadRequiredPrefixes();
2745
+ if (!prefixes) return;
2746
+ try {
2747
+ const result = await fleetApi.composePermissions({
2748
+ member_name: member,
2749
+ role: 'doer',
2750
+ grant: prefixes,
2751
+ grant_reason: "deploy.md's declared Permissions section, auto-provisioned before dispatch",
2752
+ });
2753
+ provisioned.add(member);
2754
+ log(`[deploy-permissions] ensured deploy.md's required permissions on '${member}': ${result}`);
2755
+ } catch (err) {
2756
+ log(`[deploy-permissions] could not auto-provision deploy.md permissions on '${member}' (continuing -- the deployer's own Step 0a check remains the backstop): ${err.message}`);
2757
+ }
2758
+ };
2759
+ }
2760
+
1911
2761
  /**
1912
2762
  * Builds the REACTIVE `onAuthFailure` self-heal callback runGitStep and
1913
2763
  * runDoltStep invoke on an 'auth' classification: re-provisions the failing
@@ -2244,7 +3094,7 @@ export async function verifyDoerStreakClosed({ command, orchestratorMember, bead
2244
3094
  // closes. Routed through the single dolt-sync module's purpose-based BEFORE
2245
3095
  // bracket (apra-fleet-417.2.1); behavior is identical to the previous
2246
3096
  // direct doltPullBefore() call.
2247
- await DoltSync.syncBefore(orchestratorMember, { command, log, fatal: true });
3097
+ await DoltSync.syncBefore(orchestratorMember, { command, log, fatal: true, settle: buildSettleCallback(orchestratorMember, { command, log }) });
2248
3098
  const label = `bd show ${beadIds.join(' ')} --json`;
2249
3099
  const showRes = await command(label, { member_name: orchestratorMember, silent: true });
2250
3100
  const showBeads = parseBdJson(showRes, label);
@@ -2394,16 +3244,20 @@ export function validateArgs(args) {
2394
3244
  }
2395
3245
  }
2396
3246
 
2397
- // --- dispatch_timeout_s (optional, default 3600) -----------------------
3247
+ // --- dispatch_timeout_s (optional, default 9000 = 150min/2.5h) ---------
2398
3248
  // Per-dispatch time budget in seconds, applied as BOTH timeout_s and
2399
3249
  // max_total_s on every agent dispatch: `claude -p` emits nothing until the
2400
3250
  // turn completes, so inactivity equals total runtime and the two timers
2401
3251
  // must be equal for the ceiling to be reachable. The integ-test dispatch
2402
- // ceiling is 2x this value, since its suites legitimately run past one
2403
- // budget. Lowering it bounds the cost of a live-but-silent member hang,
2404
- // which no timer can otherwise distinguish from work. Floor 60: below that
2405
- // even healthy dispatches cannot complete a single turn.
2406
- const dispatchTimeoutS = args.dispatch_timeout_s === undefined ? 3600 : args.dispatch_timeout_s;
3252
+ // ceiling is 2x this value and the regression-test ceiling is 3x, since
3253
+ // those suites legitimately run past one budget. Raised from the earlier
3254
+ // 3600s default: an hour was tight enough to misclassify a slow-but-alive
3255
+ // turn (a large diff, a chatty tool loop) as a stall, which is a false
3256
+ // positive, not the genuine-hang protection this timer exists for.
3257
+ // Lowering it still bounds the cost of a live-but-silent member hang,
3258
+ // which no timer can otherwise distinguish from work. Floor 60: below
3259
+ // that even healthy dispatches cannot complete a single turn.
3260
+ const dispatchTimeoutS = args.dispatch_timeout_s === undefined ? 9000 : args.dispatch_timeout_s;
2407
3261
  if (typeof dispatchTimeoutS !== 'number' || !Number.isInteger(dispatchTimeoutS) || dispatchTimeoutS < 60) {
2408
3262
  throw new Error(`[Arg Contract] Invalid dispatch_timeout_s "${dispatchTimeoutS}": must be an integer >= 60 (seconds).`);
2409
3263
  }
@@ -3460,10 +4314,13 @@ export function assignDoerWorklists(streaks, doerCount, opts = {}) {
3460
4314
  * sprint track branch and is always spelled out: doer.md requires it, and a
3461
4315
  * doer dispatched without one must return "BLOCKED" rather than guess whatever
3462
4316
  * branch happens to be checked out.
3463
- * @param {{ beadIds: string[], branch: string, feedback: string|null }} opts
4317
+ * `kbKnowledge` carries the entries kb_session_prime returned for this member
4318
+ * (see kbKnowledgeBlock): the doer cannot read the KB itself on a member
4319
+ * dispatch, so this prompt is its only route to prior knowledge.
4320
+ * @param {{ beadIds: string[], branch: string, feedback: string|null, kbKnowledge?: object[] }} opts
3464
4321
  * @returns {string}
3465
4322
  */
3466
- export function buildDoerPrompt({ beadIds, branch, feedback }) {
4323
+ export function buildDoerPrompt({ beadIds, branch, feedback, kbKnowledge }) {
3467
4324
  const lines = [
3468
4325
  `Sprint track branch to work on: ${branch}. Work on this branch only; do not push to the base branch.`,
3469
4326
  `Assigned bead ids (comma-separated): ${beadIds.join(', ')}`,
@@ -3480,6 +4337,7 @@ export function buildDoerPrompt({ beadIds, branch, feedback }) {
3480
4337
  'workaround whose purpose is to bypass the block, even for a brand-new file and ' +
3481
4338
  'even if you judge the underlying operation safe. This matches this repo\'s ' +
3482
4339
  'CLAUDE.md permission-block policy.',
4340
+ ...kbKnowledgeBlock(kbKnowledge),
3483
4341
  ];
3484
4342
  if (feedback) {
3485
4343
  lines.push(
@@ -3497,29 +4355,204 @@ export function buildDoerPrompt({ beadIds, branch, feedback }) {
3497
4355
  * ids just worked, their full `bd show` detail (acceptance criteria), the diff
3498
4356
  * range, and the sprint goal priority are all spelled out rather than assumed.
3499
4357
  *
3500
- * The prohibition on the reviewer mutating beads itself is stated here as well
3501
- * as in reviewer.md: nothing but the prompt stops the reviewer from shelling
3502
- * out `bd` commands on the member side, so it is repeated as defense in depth.
3503
- * @param {{ beadIds: string[], acceptanceCriteriaJson: string, baseBranch: string, branch: string, goal?: string }} opts
4358
+ * CRITICAL: explicitly, redundantly forbids the reviewer from mutating
4359
+ * beads itself. agents/reviewer.md's own prose (Step 5, Rules) already
4360
+ * states this same prohibition -- prose and dispatch prompt agree today --
4361
+ * but the schema alone doesn't stop the reviewer from shelling out `bd`
4362
+ * commands on the member side regardless of what either document says, so
4363
+ * the prohibition is stated here too as defense in depth, not because of
4364
+ * any known prose/code divergence.
4365
+ * apra-fleet-s6d: `beadIds` may legitimately be EMPTY. The Cycle Evaluation
4366
+ * re-review asks a scope-wide question ("no goal-priority beads are open --
4367
+ * is the sprint actually done?"), so it has no bead ids to name. Rendering
4368
+ * the per-bead framing anyway produced the literal dangling sentence
4369
+ * "...for the following bead id(s): ." plus a SPRINT SCOPE block ordering the
4370
+ * reviewer to judge "ONLY against the named bead id(s) above" -- against an
4371
+ * empty set. The reviewer answered honestly (CHANGES_NEEDED with nothing to
4372
+ * reopen and nothing to create), which is exactly what
4373
+ * isReviewerContractViolation flags; the retry re-sent the identical
4374
+ * incoherent prompt, so the sprint aborted on ReviewerContractViolationError.
4375
+ * The empty case therefore gets its own coherent scope-wide framing.
4376
+ *
4377
+ * @param {{ beadIds: string[], acceptanceCriteriaJson: string, baseBranch: string, branch: string, goal?: string, kbCandidates?: object[] }} opts
3504
4378
  * @returns {string}
3505
4379
  */
3506
- export function buildReviewerPrompt({ beadIds, acceptanceCriteriaJson, baseBranch, branch, goal }) {
4380
+ /**
4381
+ * apra-fleet-0ef / apra-fleet-nx7: the "KNOWLEDGE BANK -- promotion candidates"
4382
+ * block, shared verbatim by the per-round reviewer prompt and the Final Review
4383
+ * prompt.
4384
+ *
4385
+ * It lives in one function because the two prompts must state the SAME evidence
4386
+ * bar. Duplicating the text invites them to drift, and a drifted bar is
4387
+ * invisible: both sides would still "work", just to different standards, and the
4388
+ * only symptom would be inconsistent CONFIRMED quality months later.
4389
+ *
4390
+ * Returns a single-element array (or an empty one) so callers can spread it into
4391
+ * their prompt-section list.
4392
+ *
4393
+ * @param {object[]|undefined} kbCandidates
4394
+ * @returns {string[]}
4395
+ */
4396
+ /**
4397
+ * KB audit 2026-08-11: the "KNOWLEDGE BANK -- what this repo already knows"
4398
+ * block, shared by the doer and reviewer dispatch prompts.
4399
+ *
4400
+ * WHY THIS EXISTS AT ALL. Every role contract's Step 0 tells the role to call
4401
+ * kb_session_prime itself. On a fleet-member dispatch it cannot: the member's
4402
+ * composed permission config disables the apra-fleet MCP server outright
4403
+ * (src/providers/claude.ts composePermissionConfig), so the tool is not merely
4404
+ * unlisted, it is unreachable. That is the same wall kb_promotions hit, and
4405
+ * this is the same fix -- the engine performs the read and hands the result
4406
+ * over as prompt content. Step 0 stays correct for the OTHER execution path
4407
+ * (an apra-pm orchestrator session running these contracts as local subagents,
4408
+ * where the MCP server is present), so both paths now get knowledge.
4409
+ *
4410
+ * The trust ladder is restated here rather than assumed: these entries are
4411
+ * agent-authored claims from earlier sprints, and CONFIRMED means a reviewer
4412
+ * verified the claim, not that it is currently true of this branch's tree.
4413
+ *
4414
+ * Returns a single-element array (or an empty one) so callers can spread it
4415
+ * into their prompt-section list, matching kbPromotionBlock.
4416
+ *
4417
+ * @param {object[]|undefined} entries
4418
+ * @returns {string[]}
4419
+ */
4420
+ /**
4421
+ * Roles whose prompt BUILDER places the knowledge block itself, at a position
4422
+ * that carries meaning. Everything else receives it from the agent() wrapper.
4423
+ * Listing them here (rather than inside the wrapper) keeps the two halves of
4424
+ * that split visible from the block's own definition -- a role added to one
4425
+ * side and forgotten on the other either gets the block twice or never.
4426
+ */
4427
+ export const KB_SELF_INJECTING_ROLES = Object.freeze(new Set([ROLE_DOER, ROLE_REVIEWER]));
4428
+
4429
+ /**
4430
+ * FTS terms for a dispatch's kb_query, drawn from what the engine already
4431
+ * holds: the beads being worked and their ids.
4432
+ *
4433
+ * Bead TITLES are the useful half -- they are prose about the change ("stop
4434
+ * collapsing unknown_zone into unbound_roi"), which is what matches an entry's
4435
+ * title/summary/content. Ids are included because a bead id occasionally
4436
+ * appears verbatim in a captured entry, and query() OR-joins its terms, so a
4437
+ * term that matches nothing costs a little ranking noise rather than filtering
4438
+ * the result to empty. Non-string and blank values are dropped so a partially
4439
+ * populated bead cannot produce a malformed query.
4440
+ *
4441
+ * @param {Array<{id?: string, title?: string}>} beads
4442
+ * @param {string[]} beadIds
4443
+ * @returns {string[]}
4444
+ */
4445
+ export function kbQueryTerms(beads, beadIds) {
4446
+ const terms = [];
4447
+ for (const b of Array.isArray(beads) ? beads : []) {
4448
+ if (b && typeof b.title === 'string' && b.title.trim()) terms.push(b.title.trim());
4449
+ }
4450
+ for (const id of Array.isArray(beadIds) ? beadIds : []) {
4451
+ if (typeof id === 'string' && id.trim()) terms.push(id.trim());
4452
+ }
4453
+ return terms;
4454
+ }
4455
+
4456
+ export function kbKnowledgeBlock(entries) {
4457
+ if (!Array.isArray(entries) || entries.length === 0) return [];
4458
+ return [
4459
+ 'KNOWLEDGE BANK -- what this repo already knows. These entries were captured and '
4460
+ + 'verified during earlier work on this repository, and are provided so you do not '
4461
+ + 'rediscover them the hard way. Read them BEFORE you start.\n'
4462
+ + 'CONFIRMED entries were independently verified by a reviewer: trust them. INFERRED '
4463
+ + 'entries are unverified hints: treat them as leads to check, not as facts. An entry '
4464
+ + 'describes the tree it was captured against, so if one contradicts what you actually '
4465
+ + 'observe in the code right now, the code wins -- say so in your notes rather than '
4466
+ + 'bending your work to fit the entry.\n'
4467
+ + 'You do not need to call any kb_* tool to read these. If you discover something '
4468
+ + 'non-obvious and durable while working, report it in the `kb_captures` field of your '
4469
+ + 'structured output and the orchestrator will record it.\n'
4470
+ + wrapUntrustedBlock('kb_session_prime --top_entries', JSON.stringify(
4471
+ entries.map((e) => ({
4472
+ confidence: e.confidence,
4473
+ title: e.title,
4474
+ summary: e.summary,
4475
+ source_files: e.source_files,
4476
+ })),
4477
+ null,
4478
+ 2
4479
+ )),
4480
+ ];
4481
+ }
4482
+
4483
+ export function kbPromotionBlock(kbCandidates) {
4484
+ if (!Array.isArray(kbCandidates) || kbCandidates.length === 0) return [];
4485
+ return [
4486
+ 'KNOWLEDGE BANK -- promotion candidates. These entries were captured during this '
4487
+ + 'sprint and sit at INFERRED. You are the only role that can promote them to '
4488
+ + 'CONFIRMED. Do NOT call any kb_* tool yourself: return your decisions in the '
4489
+ + '`kb_promotions` field of your structured output as [{id, reason}] and the '
4490
+ + 'orchestrator executes them.\n'
4491
+ + 'Promote ONLY entries whose claim you independently verified during THIS review '
4492
+ + '-- by reading the diff, running the tests, or checking the cited files yourself. '
4493
+ + 'The `reason` must state that evidence (at least 20 characters, e.g. "verified '
4494
+ + 'against server/transit.js:88 and the reopen test"). Evidence, not plausibility: '
4495
+ + 'if an entry merely looks correct, leave it INFERRED -- that is a perfectly good '
4496
+ + 'resting state, and a wrong CONFIRMED entry is worse than no entry. Never '
4497
+ + 'blanket-promote, and never promote by module, tag or timestamp. Promoting '
4498
+ + 'nothing is a valid outcome; return [] in that case.\n'
4499
+ + wrapUntrustedBlock('kb_list --confidence INFERRED', JSON.stringify(
4500
+ kbCandidates.map((e) => ({
4501
+ id: e.id,
4502
+ title: e.title,
4503
+ summary: e.summary,
4504
+ source_files: e.source_files,
4505
+ })),
4506
+ null,
4507
+ 2
4508
+ )),
4509
+ ];
4510
+ }
4511
+
4512
+ export function buildReviewerPrompt({ beadIds, acceptanceCriteriaJson, baseBranch, branch, goal, kbCandidates, kbKnowledge }) {
4513
+ const ids = Array.isArray(beadIds) ? beadIds : [];
4514
+ const scopeWide = ids.length === 0;
4515
+ // Scope-wide re-reviews are fed `bd list --json` (the whole remaining
4516
+ // scope); per-bead reviews are fed `bd show --json`. Label the untrusted
4517
+ // block with the command that actually produced it.
4518
+ const scopeCommand = scopeWide ? 'bd list --json' : 'bd show --json';
3507
4519
  return [
3508
- `Review the work just done for the following bead id(s): ${beadIds.join(', ')}.`,
3509
- 'Full task detail (including acceptance criteria), from `bd show --json`:',
3510
- wrapUntrustedBlock('bd show --json', acceptanceCriteriaJson),
4520
+ scopeWide
4521
+ ? 'Re-review the CURRENT state of the entire sprint scope. No bead ids are named '
4522
+ + 'because no goal-priority beads remain open -- that is precisely the question you '
4523
+ + 'are being asked to settle: judge the delivered work as a whole and decide whether '
4524
+ + 'this sprint is genuinely complete.'
4525
+ : `Review the work just done for the following bead id(s): ${ids.join(', ')}.`,
4526
+ scopeWide
4527
+ ? 'The full sprint scope, from `bd list --json`:'
4528
+ : 'Full task detail (including acceptance criteria), from `bd show --json`:',
4529
+ wrapUntrustedBlock(scopeCommand, acceptanceCriteriaJson),
3511
4530
  `Diff range to review: ${baseBranch}..${branch} (base_branch..branch).`,
3512
4531
  // Without an explicit scope clause a reviewer can withhold APPROVED
3513
4532
  // over below-goal work the sprint deliberately defers, which starves
3514
4533
  // the completion gate (zero open goal beads AND an APPROVED verdict).
3515
4534
  ...(goal ? [
3516
4535
  `SPRINT SCOPE: this sprint's goal priority is ${goal}. Judge your verdict ` +
3517
- `ONLY against the named bead id(s) above and other work at or above that ` +
3518
- `goal priority. Features/beads BELOW the goal priority (e.g. P3 when the ` +
4536
+ (scopeWide
4537
+ ? `ONLY against work at or above that goal priority. `
4538
+ : `ONLY against the named bead id(s) above and other work at or above that `
4539
+ + `goal priority. `) +
4540
+ `Features/beads BELOW the goal priority (e.g. P3 when the ` +
3519
4541
  `goal is P1/P2) are DEFERRED BY DESIGN to a later sprint: their absence ` +
3520
4542
  `from the diff is correct, must not block APPROVED, must not appear in ` +
3521
4543
  `reopenIds, and may be mentioned in notes only.`,
3522
4544
  ] : []),
4545
+ // apra-fleet-0ef: the reviewer is the ONLY role permitted to mint
4546
+ // CONFIRMED, but a KB entry id can only come from the KB, and the
4547
+ // reviewer subagent has no apra-fleet MCP tools to look one up. Without
4548
+ // this block it could never name an id, so `kb_promotions` came back
4549
+ // empty on every round and nothing was ever promoted. The engine reads
4550
+ // the candidates and executes; the judgment stays with the reviewer.
4551
+ // Prior knowledge FIRST, then the promotion candidates: the reviewer
4552
+ // judges the work against what the repo already knows before it decides
4553
+ // which of this sprint's captures earned CONFIRMED.
4554
+ ...kbKnowledgeBlock(kbKnowledge),
4555
+ ...kbPromotionBlock(kbCandidates),
3523
4556
  'Do NOT run any `bd` command yourself and do NOT mutate beads directly in any way ' +
3524
4557
  '(no bd update, bd close, bd create, etc.) -- the orchestrator applies your ' +
3525
4558
  '`reopenIds` via `bd update <id> --status=open` and creates your `newTasks` via ' +
@@ -3594,29 +4627,34 @@ export function extractContestedBeadIds(verdict) {
3594
4627
  // diff/commit could try to steer it into emitting text crafted to break out of
3595
4628
  // a shell command.
3596
4629
  //
3597
- // SAFE_TEXT_RE is the shell-safety boundary for `title`, which
3598
- // createChildBeadWithAllocatedId() interpolates inline into a double-quoted
3599
- // `bd create "..."` command. Sprint members run mixed POSIX and Windows
3600
- // shells, and no single escaping scheme is reliably safe across all of them,
3601
- // so title is validated against an allowlist instead of escaped: anything
3602
- // outside it is rejected before reaching `command()`.
4630
+ // SAFE_TEXT_RE (title only) deliberately excludes: backtick, `$`,
4631
+ // double-quote (the command's own quoting delimiter -- allowing it back in
4632
+ // would let a title close the quote early regardless of any other
4633
+ // restriction), and backslash (blocks a trailing-backslash "escape the
4634
+ // closing quote" trick as well as any other backslash-based escape
4635
+ // sequence). The allowed punctuation (`.,:;!?()'-_/+[]` plus space) covers
4636
+ // realistic task titles while remaining inert as shell syntax in both POSIX
4637
+ // and Windows member shells.
3603
4638
  //
3604
- // SAFE_TEXT_RE admits letters, digits, space, and the punctuation
3605
- // `. , : ; ! ? ( ) ' _ / [ ] -` and nothing else. In particular it excludes
3606
- // backtick and `$` (command substitution survives inside POSIX double
3607
- // quotes), the double-quote itself (a title could otherwise close the
3608
- // command's quoting early), and backslash (which could escape the closing
3609
- // quote or start any other escape sequence). What remains covers realistic
3610
- // task titles while staying inert as shell syntax in both shell families.
4639
+ // apra-fleet-v75: `[`, `]` and `+` are allowed. The title is interpolated as
4640
+ // `bd create "${title}"` -- inside double quotes, brackets never glob and `+`
4641
+ // has no meaning, in POSIX shells or PowerShell. Excluding them rejected this
4642
+ // project's own bead-title convention ([bug]/[epic]/[test] prefixes), which
4643
+ // `bd create` itself accepts; a real reviewer follow-up was dropped mid-sprint
4644
+ // on exactly that. The characters that ARE live inside double quotes --
4645
+ // `"`, `\`, backtick, `$` -- remain excluded, which is what this guard is for.
3611
4646
  //
3612
- // `description` carries no such risk: createChildBeadWithAllocatedId() stages
3613
- // it to a member-local temp file and passes that path to `bd create
3614
- // --body-file`, never interpolating it into a command string. So
3615
- // SAFE_DESCRIPTION_RE enforces only non-emptiness and the repo's ASCII
3616
- // convention -- tab, newline, carriage return, and printable ASCII -- which
3617
- // admits technical characters that SAFE_TEXT_RE rejects ('=', '&', '+', '"',
3618
- // '%', '#', '$', backtick and backslash as text).
3619
- const SAFE_TEXT_RE = /^[A-Za-z0-9 .,:;!?()'_/\[\]-]+$/;
4647
+ // `description` no longer reaches this shell-interpolation risk at all
4648
+ // (apra-fleet-eft.56.1, transport hardened in eft.73.1):
4649
+ // createChildBeadWithAllocatedId() stages it to a member-local temp file
4650
+ // (base64-carried, member-side) and hands that path to `bd create
4651
+ // --body-file`, never interpolating it into a command string. That removed
4652
+ // the injection
4653
+ // surface SAFE_TEXT_RE existed to close for descriptions, so
4654
+ // SAFE_DESCRIPTION_RE only enforces the repo's own ASCII-only convention
4655
+ // (plus non-empty) -- legitimate technical characters ('=', '&', '+', '"',
4656
+ // backticks-as-text, '%', '#', '[', ']', etc.) are allowed again.
4657
+ const SAFE_TEXT_RE = /^[A-Za-z0-9 .,:;!?()'_/+[\]-]+$/;
3620
4658
  const SAFE_DESCRIPTION_RE = /^[\t\n\r\x20-\x7E]+$/;
3621
4659
  const SAFE_PRIORITY_RE = /^P[0-4]$/;
3622
4660
 
@@ -3646,8 +4684,8 @@ export function normalizeTierToken(raw) {
3646
4684
  * validation, so a description is not rejected wholesale over characters that
3647
4685
  * lose no meaning when normalized. This is a fixed substitution table, not a
3648
4686
  * general Unicode stripper: anything still outside the allowlist afterwards is
3649
- * still a hard rejection. Deliberately scoped to description only -- title
3650
- * stays on the tighter SAFE_TEXT_RE shell-safety allowlist.
4687
+ * still a hard rejection. See sanitizeNewTaskTitle() below for title's own,
4688
+ * stricter table.
3651
4689
  * @param {string} description
3652
4690
  * @returns {string}
3653
4691
  */
@@ -3659,6 +4697,38 @@ export function sanitizeNewTaskDescription(description) {
3659
4697
  .replace(/\u2026/g, '...'); // horizontal ellipsis (\u2026)
3660
4698
  }
3661
4699
 
4700
+ /**
4701
+ * Same idea as sanitizeNewTaskDescription() above, for title -- but with a
4702
+ * STRICTER substitution table, since title still has to pass the tighter
4703
+ * SAFE_TEXT_RE shell-safety allowlist afterwards (it is interpolated inline
4704
+ * into a `bd create "..."` command; description is not). Every substitution
4705
+ * here maps to a character SAFE_TEXT_RE already admits, so this never
4706
+ * reopens the injection surface that allowlist exists to close -- it only
4707
+ * rescues titles that would otherwise be needlessly rejected over benign,
4708
+ * common LLM punctuation choices. Observed live (apra-fleet-vk0a's sibling
4709
+ * finding): a reviewer wrote a title referencing a CLI command in backticks
4710
+ * (`` `apra-fleet status` ``, ordinary Markdown inline-code style), which
4711
+ * SAFE_TEXT_RE rejects outright (backtick is excluded as a POSIX
4712
+ * command-substitution risk) -- the finding was then silently demoted to a
4713
+ * freetext note on the parent bead instead of becoming its own actionable
4714
+ * task. Backtick has no special meaning in a bd title (bd has no
4715
+ * code-formatting concept), so it is rewritten to a single quote here rather
4716
+ * than dropped or preserved. A literal `"`/`$`/backslash in a title is NOT
4717
+ * rewritten (there is no safe ASCII stand-in that preserves meaning without
4718
+ * reopening the injection question) -- those still hard-reject via
4719
+ * SAFE_TEXT_RE below, exactly as before this function existed.
4720
+ * @param {string} title
4721
+ * @returns {string}
4722
+ */
4723
+ export function sanitizeNewTaskTitle(title) {
4724
+ return String(title ?? '')
4725
+ .replace(/[\u2014\u2013]/g, '--') // em dash (\u2014), en dash (\u2013)
4726
+ .replace(/[\u2018\u2019]/g, "'") // curly single quotes (\u2018 \u2019)
4727
+ .replace(/[\u201C\u201D]/g, "'") // curly double quotes -> single quote (a literal `"` stays disallowed in title, unlike description)
4728
+ .replace(/\u2026/g, '...') // horizontal ellipsis (\u2026)
4729
+ .replace(/`/g, "'"); // backtick (Markdown inline-code marker) -> single quote
4730
+ }
4731
+
3662
4732
  /**
3663
4733
  * Validates one reviewer-authored newTask entry. `title` is checked against
3664
4734
  * SAFE_TEXT_RE because it is interpolated inline into a `bd create` command
@@ -3676,7 +4746,7 @@ export function validateNewTask(newTask) {
3676
4746
  if (!SAFE_PRIORITY_RE.test(priority)) {
3677
4747
  return { ok: false, reason: `priority '${priority}' does not match required pattern ${SAFE_PRIORITY_RE}` };
3678
4748
  }
3679
- const title = String(newTask && newTask.title);
4749
+ const title = sanitizeNewTaskTitle(newTask && newTask.title);
3680
4750
  if (!title || !SAFE_TEXT_RE.test(title)) {
3681
4751
  return { ok: false, reason: `title fails safe-character allowlist ${SAFE_TEXT_RE} (or is empty): ${JSON.stringify(title)}` };
3682
4752
  }
@@ -3888,7 +4958,7 @@ export function sanitizePrText(text) {
3888
4958
  * }} opts
3889
4959
  * @returns {string}
3890
4960
  */
3891
- export function buildFinalVerdictPrompt({ targetIssues, branch, baseBranch, goal, cyclesRun, closedCount, openAtGoalCount, deployFailures, integFailures, rejectedNewTasks = [], unclosedVerifyIds = [] }) {
4961
+ export function buildFinalVerdictPrompt({ targetIssues, branch, baseBranch, goal, cyclesRun, closedCount, openAtGoalCount, deployFailures, integFailures, rejectedNewTasks = [], unclosedVerifyIds = [], kbCandidates, kbKnowledge }) {
3892
4962
  const lines = [
3893
4963
  `Final review for sprint scope issue id(s): ${targetIssues.join(', ')}.`,
3894
4964
  `Branch: ${branch} (base: ${baseBranch}). Goal priority: ${goal}. The sprint ran ${cyclesRun} cycle(s).`,
@@ -3955,6 +5025,15 @@ export function buildFinalVerdictPrompt({ targetIssues, branch, baseBranch, goal
3955
5025
  'NEVER touch beads yourself (no bd create/update/reopen) -- the orchestrator applies your ' +
3956
5026
  'newTasks and reopenIds.'
3957
5027
  );
5028
+ // apra-fleet-nx7: the Final Review is the best-positioned promoter in the
5029
+ // whole run -- it has read the entire diff, run the full suite and judged the
5030
+ // sprint as a whole, which is exactly the evidence standard reviewer.md
5031
+ // demands before minting CONFIRMED. It used to receive no candidate block at
5032
+ // all (0ef wired kbCandidates through buildReviewerPrompt only), so anything
5033
+ // captured in a sprint's LAST round reached this reviewer and nobody else,
5034
+ // and was stranded at INFERRED forever.
5035
+ lines.push(...kbKnowledgeBlock(kbKnowledge));
5036
+ lines.push(...kbPromotionBlock(kbCandidates));
3958
5037
  return lines.join('\n\n');
3959
5038
  }
3960
5039
 
@@ -4682,7 +5761,27 @@ async function runSprintCycle(context) {
4682
5761
  // shared fleet HTTP singleton with no per-sprint identity of its own. One
4683
5762
  // wrapper covers every call site in this file; an explicit `sprint_id` in an
4684
5763
  // individual call's opts wins via the spread order.
4685
- const agent = (prompt, opts = {}) => agentRaw(prompt, { sprint_id: sprintMutexId, ...opts });
5764
+ //
5765
+ // KB audit follow-up: this wrapper is also where the KNOWLEDGE BANK block
5766
+ // reaches the roles whose prompt builders do not place it themselves.
5767
+ //
5768
+ // Every one of the ten role contracts carries a Step 0 telling it to call
5769
+ // kb_session_prime, and on a member dispatch NONE of them can (the fleet MCP
5770
+ // server is disabled there) -- so the engine has to hand the knowledge over
5771
+ // as prompt text. buildDoerPrompt / buildReviewerPrompt / buildFinalVerdict-
5772
+ // Prompt already do that at a position that matters (the reviewer's block
5773
+ // must precede its promotion candidates), so those roles are excluded here
5774
+ // and handled there. Everyone else -- planner, plan-reviewer, deployer, the
5775
+ // two test runners, harvester -- got nothing at all until now, which is
5776
+ // exactly the population most likely to benefit from a `runbook` entry.
5777
+ const agent = (prompt, opts = {}) => {
5778
+ let finalPrompt = prompt;
5779
+ if (opts.agentType && !KB_SELF_INJECTING_ROLES.has(opts.agentType) && opts.member_name) {
5780
+ const [block] = kbKnowledgeBlock(kbPriming.knowledgeOf(opts.member_name));
5781
+ if (block) finalPrompt = prompt + '\n\n' + block;
5782
+ }
5783
+ return agentRaw(finalPrompt, { sprint_id: sprintMutexId, ...opts });
5784
+ };
4686
5785
 
4687
5786
  // The global dolt push mutex client. Every D-push below serializes through
4688
5787
  // it so two sprints never push at the same time. Four sources, in
@@ -4849,6 +5948,24 @@ async function runSprintCycle(context) {
4849
5948
  : undefined
4850
5949
  );
4851
5950
 
5951
+ // Provisions a member unattended='auto' right before its deployer /
5952
+ // integ-test-runner / regression-test-runner dispatch, so those
5953
+ // real-command/real-suite roles never stall on an interactive permission
5954
+ // prompt. See createUnattendedAutoProvisioner's doc comment for why this
5955
+ // is one-way (never reverted) and safe in a single-member sprint.
5956
+ // 1. `context.ensureUnattendedAuto` -- an explicitly-injected function
5957
+ // (tests wire an in-process one to prove the call site fires
5958
+ // without a live fleet server).
5959
+ // 2. `args.callTool` -- the real update_member call via
5960
+ // createUnattendedAutoProvisioner (this file).
5961
+ // 3. neither -- a no-op: no provisioning call is made and the member
5962
+ // dispatches under whatever permission mode it already has.
5963
+ const ensureUnattendedAuto = context.ensureUnattendedAuto ?? (
5964
+ (args && typeof args.callTool === 'function')
5965
+ ? createUnattendedAutoProvisioner({ callTool: args.callTool, log })
5966
+ : async () => {}
5967
+ );
5968
+
4852
5969
  // Validate BEFORE any agent()/command() dispatch: a rejected/malformed arg
4853
5970
  // must result in zero fleet dispatches.
4854
5971
  const validated = validateArgs(args);
@@ -4887,6 +6004,35 @@ async function runSprintCycle(context) {
4887
6004
  // Member mapping resolution
4888
6005
  const physicalMembers = validated.members;
4889
6006
 
6007
+ // apra-fleet-e28: prime each member's own project KB before any dispatch, so
6008
+ // the Step 0 Knowledge Bank block in every role contract has something warm
6009
+ // to read. This engine had no KB priming at all -- it lived only in the
6010
+ // Claude workflow copy. Best-effort: a cold KB never fails a sprint.
6011
+ const kbPriming = context.kbPriming ?? createKbPrimingClient({
6012
+ callTool: (args && typeof args.callTool === 'function') ? args.callTool : undefined,
6013
+ members: physicalMembers,
6014
+ log,
6015
+ });
6016
+ await kbPriming.primeAll();
6017
+
6018
+ // The role output schemas are shared with apra-pm, so every role dispatched
6019
+ // below is now asked for kb_captures (and the reviewer for kb_promotions).
6020
+ // This is the consumer: without it those fields would be gathered and
6021
+ // silently dropped. Unlike apra-pm's workflow script, this engine has a real
6022
+ // callTool, so the kb_capture/kb_promote calls are made directly.
6023
+ const kbWork = context.kbWork ?? createKbWorkClient({
6024
+ callTool: (args && typeof args.callTool === 'function') ? args.callTool : undefined,
6025
+ log,
6026
+ // Scope every kb_* call below to the member's OWN project KB. The repo
6027
+ // path each call site already threads is a path on the MEMBER's host,
6028
+ // so the server cannot derive a slug from it -- without this lookup a
6029
+ // remote member's reads and writes all land in the shared 'default' KB
6030
+ // (apra-fleet-b4g.15). Resolved through the path rather than passed
6031
+ // per call site so no site can thread the path and forget the scope.
6032
+ // context.kbPriming above is an injection seam; a stub that predates
6033
+ // remoteUrlForPath degrades to no scope rather than crashing a sprint.
6034
+ remoteUrlFor: (repoPath) => (typeof kbPriming.remoteUrlForPath === 'function' ? kbPriming.remoteUrlForPath(repoPath) : null),
6035
+ });
4890
6036
  // A member named in ANY roleMap value is a "specialist" for whatever
4891
6037
  // role(s) named it -- e.g. a member pinned to roleMap.reviewer has been
4892
6038
  // deliberately reserved for review. Without this, a role the caller left
@@ -4937,6 +6083,19 @@ async function runSprintCycle(context) {
4937
6083
  // deliberately outside contracts.ROLES.
4938
6084
  const orchestratorMember = getMemberForRole(ROLE_ORCHESTRATOR);
4939
6085
 
6086
+ // Self-heals deploy.md's declared Permissions onto the deployer /
6087
+ // integ-test-runner / regression-test-runner member before each of
6088
+ // those dispatches -- see createDeployPermissionsProvisioner's doc
6089
+ // comment. Same three-way precedence shape as ensureUnattendedAuto
6090
+ // above: an explicitly-injected `context.ensureDeployPermissions` (for
6091
+ // tests), else the real compose_permissions-backed provisioner built
6092
+ // from `args.callTool`, else a no-op when neither is available.
6093
+ const ensureDeployPermissions = context.ensureDeployPermissions ?? (
6094
+ (args && typeof args.callTool === 'function')
6095
+ ? createDeployPermissionsProvisioner({ callTool: args.callTool, command, orchestratorMember, log })
6096
+ : async () => {}
6097
+ );
6098
+
4940
6099
  // ONE shared bracket wrapping EVERY role-identified agent() dispatch below
4941
6100
  // -- planner, plan-reviewer, doer, reviewer, deployer, integ-test-runner,
4942
6101
  // harvester. No phase-based exemptions: a deployer or integ-test-runner
@@ -5023,7 +6182,7 @@ async function runSprintCycle(context) {
5023
6182
  // EXPLICITLY FATAL (apra-fleet-417.3.1): a pre-dispatch D-pull that
5024
6183
  // silently degraded would hand the agent a STALE beads clone and
5025
6184
  // let it act on it -- worse than not dispatching at all.
5026
- await DoltSync.syncBefore(member, { command, log, skipRefresh: skipPreDispatchDoltPull, onAuthFailure, fatal: true });
6185
+ await DoltSync.syncBefore(member, { command, log, skipRefresh: skipPreDispatchDoltPull, onAuthFailure, fatal: true, settle: buildSettleCallback(member, { command, log }) });
5027
6186
  }
5028
6187
  // The teardown is deliberately NOT a `finally`. A throw out of a
5029
6188
  // `finally` replaces the (successful) dispatch result and is
@@ -5335,13 +6494,32 @@ async function runSprintCycle(context) {
5335
6494
  */
5336
6495
  async function dispatchReview({ beadIds, acceptanceCriteriaJson }) {
5337
6496
  const reviewerPool = getMembersForRole(ROLE_REVIEWER);
6497
+ // apra-fleet-0ef: fetch the INFERRED entries this reviewer may promote
6498
+ // and hand them to it in the prompt. The reviewer has no MCP kb_* tools
6499
+ // of its own, so without this it can never name an entry id and
6500
+ // `kb_promotions` comes back empty every round -- which is exactly why
6501
+ // kb_promote had never once fired. Scoped to the reviewer's OWN work
6502
+ // folder (same source kbWork.apply uses to route the writes), and
6503
+ // best-effort: a cold KB must not fail the review.
6504
+ const reviewerRepoPath = kbPriming.folderOf(reviewerPool[0]);
6505
+ const kbCandidates = await kbWork.promotionCandidates(reviewerRepoPath);
6506
+ if (kbCandidates.length > 0) {
6507
+ log(`[kb-work] offering ${kbCandidates.length} INFERRED entr(ies) to the reviewer for promotion.`);
6508
+ }
6509
+ // What the KB knows about the beads UNDER REVIEW, not just whatever the
6510
+ // sprint-start prime happened to surface. Falls back to the primed set
6511
+ // when the query returns nothing (a KB with no matching rows yet).
6512
+ const reviewerQueried = await kbWork.relevantKnowledge(reviewerRepoPath, kbQueryTerms([], beadIds));
6513
+ const reviewerKnowledge = reviewerQueried.length > 0
6514
+ ? reviewerQueried
6515
+ : kbPriming.knowledgeOf(reviewerPool[0]);
5338
6516
  // A full-cycle review can genuinely exhaust the fleet's default turn
5339
6517
  // budget, and a fresh retry deterministically hits the same wall. Make
5340
6518
  // the budget explicit and, on max_turns exhaustion, RESUME the same
5341
6519
  // session at a doubled budget: the session already holds the full
5342
6520
  // review context, so a continue-nudge finishes the job instead of
5343
6521
  // restarting it.
5344
- const BASE_REVIEWER_MAX_TURNS = 60;
6522
+ const BASE_REVIEWER_MAX_TURNS = 500;
5345
6523
  const reviewerDispatchOpts = {
5346
6524
  member_name: reviewerPool[0],
5347
6525
  agentType: 'reviewer',
@@ -5369,6 +6547,8 @@ async function runSprintCycle(context) {
5369
6547
  baseBranch: validated.baseBranch,
5370
6548
  branch: validated.branch,
5371
6549
  goal: validated.goal,
6550
+ kbCandidates,
6551
+ kbKnowledge: reviewerKnowledge,
5372
6552
  }),
5373
6553
  // member_name is repeated literally here -- not only via the
5374
6554
  // shared opts object -- so the source-level call-site parse in
@@ -5379,7 +6559,14 @@ async function runSprintCycle(context) {
5379
6559
  // Restate the review scope: a resumed dispatch replaces the
5380
6560
  // delivered prompt artifact, so the scope must be repeated inline.
5381
6561
  'Continue your review exactly where you left off in this same session -- do not restart or re-read the diff from scratch. ' +
5382
- `Your scope, restated so a resumed dispatch never loses it: bead id(s) under review ${beadIds.join(', ')} on branch ${validated.branch} against base ${validated.baseBranch}. ` +
6562
+ // apra-fleet-s6d: same empty-beadIds case as buildReviewerPrompt --
6563
+ // a scope-wide re-review has no ids to restate, and "bead id(s)
6564
+ // under review on branch..." reads as a dropped value.
6565
+ `Your scope, restated so a resumed dispatch never loses it: `
6566
+ + (Array.isArray(beadIds) && beadIds.length > 0
6567
+ ? `bead id(s) under review ${beadIds.join(', ')} `
6568
+ : `the entire sprint scope (no individual bead ids -- you are judging whether the sprint as a whole is complete) `)
6569
+ + `on branch ${validated.branch} against base ${validated.baseBranch}. ` +
5383
6570
  'Finish evaluating the remaining acceptance criteria and return your final verdict now.',
5384
6571
  {
5385
6572
  ...reviewerDispatchOpts,
@@ -5501,10 +6688,29 @@ async function runSprintCycle(context) {
5501
6688
  }
5502
6689
 
5503
6690
  // The sprint branch must be git-ensured on EVERY member that will operate
5504
- // on it, not just the orchestrator: doers round-robin across the doer pool
5505
- // and the reviewer runs from the reviewer pool, and on a real multi-member
5506
- // fleet each has its own checkout. Ensure on the UNION of the orchestrator,
5507
- // doer, and reviewer pools before the first doer round.
6691
+ // on it, not just the orchestrator: doers round-robin across the doer pool,
6692
+ // the reviewer runs from the reviewer pool, and every other role dispatched
6693
+ // through withGitSync's shared bracket (planner, plan-reviewer, deployer,
6694
+ // integ-test-runner, regression-test-runner, harvester -- see that bracket's
6695
+ // own doc comment a few hundred lines up) gets a pre-dispatch G-pull that
6696
+ // ASSUMES the correct branch is already checked out. On a real multi-member
6697
+ // fleet each role can resolve to its own independent checkout, so ensure on
6698
+ // the union of every role's member pool before the first doer round -- not
6699
+ // just doer/reviewer.
6700
+ //
6701
+ // Without this, a role pinned via roleMap to a member that was never
6702
+ // branch-ensured (e.g. deployer isolated onto its own machine, per the
6703
+ // fleet-supervisor skill's own recommended layout) can pass its G-pull's
6704
+ // `git merge --ff-only origin/<branch>` silently: a fast-forward merge does
6705
+ // not care what branch HEAD is currently on, only that HEAD is an ancestor
6706
+ // of the fetched tip. If that member happens to be sitting on a branch
6707
+ // (e.g. main) that is still fast-forward-compatible with the sprint branch,
6708
+ // the merge succeeds and silently advances THAT branch's pointer instead of
6709
+ // checking out/creating a correctly-named local branch -- the deploy/test
6710
+ // dispatch still gets the right code, but the member's local branch bookkeeping
6711
+ // ends up mislabeled. See apra-fleet-ivxi/u1qw/69pp sprint run
6712
+ // (fleet-sprint/ivxi-u1qw-69pp), where fleet-win-deploy's local `main`
6713
+ // silently absorbed the sprint branch's commits this way.
5508
6714
  //
5509
6715
  // SUPPORTED-TOPOLOGY NOTE: there is no cross-member bd/git sync layer here.
5510
6716
  // Every `bd` command below runs against the orchestrator member's beads DB
@@ -5518,6 +6724,12 @@ async function runSprintCycle(context) {
5518
6724
  orchestratorMember,
5519
6725
  ...getMembersForRole(ROLE_DOER),
5520
6726
  ...getMembersForRole(ROLE_REVIEWER),
6727
+ ...getMembersForRole('planner'),
6728
+ ...getMembersForRole('plan-reviewer'),
6729
+ ...getMembersForRole('deployer'),
6730
+ ...getMembersForRole('integ-test-runner'),
6731
+ ...getMembersForRole('regression-test-runner'),
6732
+ ...getMembersForRole('harvester'),
5521
6733
  ])];
5522
6734
 
5523
6735
  // Read the requirementsFile (if any) once, up front, so its content can
@@ -5542,7 +6754,7 @@ async function runSprintCycle(context) {
5542
6754
  // Routed through the single dolt-sync module (apra-fleet-417.2.1):
5543
6755
  // readinessGate (apra-fleet-417.5 rename of healthGate) selects the
5544
6756
  // pre-flight variant of the BEFORE bracket.
5545
- await DoltSync.syncBefore(orchestratorMember, { command, log, readinessGate: true });
6757
+ await DoltSync.syncBefore(orchestratorMember, { command, log, readinessGate: true, settle: buildSettleCallback(orchestratorMember, { command, log }) });
5546
6758
 
5547
6759
  // =======================
5548
6760
  // 0. Git Setup: ensure the sprint branch exists off base_branch
@@ -5807,6 +7019,23 @@ async function runSprintCycle(context) {
5807
7019
  const { sprintTasks: sprintPlaced, backlogTasks } = partitionByGoalMembership(sprintTasks, validated.goal);
5808
7020
  const payload = { sprintTasks: sprintPlaced };
5809
7021
  if (backlogTasks.length > 0) payload.backlogTasks = backlogTasks;
7022
+ // apra-fleet-x8r.4: plumbs the SAME two axes runner.js's own
7023
+ // completion gate (~line 8134: bdListScoped(--priority-max=
7024
+ // goalMax) MINUS decomposedParentIds()) filters on, so the
7025
+ // viewer's computeSprintProgress() required/closed counts match
7026
+ // what actually gates sprint exit -- never re-derived
7027
+ // client-side. Not `const goalMax` from the outer closure: this
7028
+ // function's FIRST call happens before that `const` initializes
7029
+ // (TDZ), so the numeric max is derived fresh here instead, from
7030
+ // the same pure goalPriorityMax() helper.
7031
+ payload.goalMax = Number(goalPriorityMax(validated.goal).slice(1));
7032
+ // sprintTasks is already this cycle's `bdListScoped('')` result
7033
+ // (any status, full scope) -- decomposedParentIds() re-derives
7034
+ // from that same no-args query, so building the set directly off
7035
+ // sprintTasks here is identical output with no extra `bd` call.
7036
+ payload.decomposedParentIds = [...new Set(
7037
+ sprintTasks.filter((b) => b && b.parent).map((b) => b.parent)
7038
+ )];
5810
7039
  publishState('beads', payload);
5811
7040
  }
5812
7041
  }
@@ -5833,7 +7062,7 @@ async function runSprintCycle(context) {
5833
7062
  // doer's work, so pull again immediately before the verification read.
5834
7063
  // DoltSync.syncBefore() is a benign no-op when the clone is current and
5835
7064
  // when no dolt remote is configured at all.
5836
- await DoltSync.syncBefore(orchestratorMember, { command, log, fatal: true });
7065
+ await DoltSync.syncBefore(orchestratorMember, { command, log, fatal: true, settle: buildSettleCallback(orchestratorMember, { command, log }) });
5837
7066
 
5838
7067
  await updateDashboard();
5839
7068
 
@@ -6149,7 +7378,7 @@ async function runSprintCycle(context) {
6149
7378
  // meaningful gap. Like every dispatch site, max_turns exhaustion is
6150
7379
  // answered with a same-session resume at doubled turns; the planner
6151
7380
  // gets a doer-sized base because it builds the whole epic DAG.
6152
- const PLANNER_MAX_TURNS = 100;
7381
+ const PLANNER_MAX_TURNS = 500;
6153
7382
  const plannerDispatchOpts = {
6154
7383
  member_name: getMemberForRole('planner'),
6155
7384
  agentType: 'planner',
@@ -6323,7 +7552,7 @@ async function runSprintCycle(context) {
6323
7552
  let verdict;
6324
7553
  // Reviewer-sized turn base, with the same same-session
6325
7554
  // turn-exhaustion resume every dispatch site uses.
6326
- const PLAN_REVIEWER_MAX_TURNS = 60;
7555
+ const PLAN_REVIEWER_MAX_TURNS = 500;
6327
7556
  const planReviewerDispatchOpts = {
6328
7557
  member_name: getMemberForRole('plan-reviewer'),
6329
7558
  agentType: 'plan-reviewer',
@@ -6670,7 +7899,7 @@ async function runSprintCycle(context) {
6670
7899
  for (const id of replanScopeIds) replannedThisCycle.add(id);
6671
7900
 
6672
7901
  // --- Scoped planner pass ---
6673
- const SCOPED_REPLAN_PLANNER_MAX_TURNS = 100;
7902
+ const SCOPED_REPLAN_PLANNER_MAX_TURNS = 500;
6674
7903
  let scopedPlannerOk = true;
6675
7904
  try {
6676
7905
  const scopedPlannerRes = await withGitSync(getMemberForRole('planner'), false, () => withDispatchWatchdog(
@@ -6716,7 +7945,7 @@ async function runSprintCycle(context) {
6716
7945
  // --- Scoped plan-review pass ---
6717
7946
  let scopedReplanApproved = false;
6718
7947
  if (scopedPlannerOk) {
6719
- const SCOPED_REPLAN_REVIEWER_MAX_TURNS = 60;
7948
+ const SCOPED_REPLAN_REVIEWER_MAX_TURNS = 500;
6720
7949
  try {
6721
7950
  const scopedVerdict = await withGitSync(getMemberForRole('plan-reviewer'), false, () => agent(
6722
7951
  buildPlanReviewerPrompt({ targetIssues, goal: validated.goal, replanScope: replanScopeIds, verifyExcluded: verifySetThisCycle }),
@@ -6996,7 +8225,7 @@ async function runSprintCycle(context) {
6996
8225
  // default) so the max-turns-exhaustion resume path below has a
6997
8226
  // known baseline to escalate from. Sized so a typical streak
6998
8227
  // finishes in one dispatch and resume stays the exception.
6999
- const BASE_DOER_MAX_TURNS = 100;
8228
+ const BASE_DOER_MAX_TURNS = 500;
7000
8229
  // Bounded resume-and-continue attempts after a max_turns
7001
8230
  // exhaustion, each doubling the turn budget. An identical retry
7002
8231
  // is pointless (the doer would deterministically run out of
@@ -7123,7 +8352,22 @@ async function runSprintCycle(context) {
7123
8352
  );
7124
8353
  }
7125
8354
 
7126
- const basePrompt = buildDoerPrompt({ beadIds: actualBeadIds, branch: validated.branch, feedback: feedbackForStreak || null });
8355
+ // The doer cannot read the KB itself (the member's composed
8356
+ // permission config disables the fleet MCP server), so the
8357
+ // entries primed for THIS member travel in its prompt.
8358
+ // Relevance-ranked read for THESE beads, falling back to the
8359
+ // sprint-start primed set when the query returns nothing.
8360
+ // The query terms are the bead ids and titles the engine
8361
+ // already holds; expand_related on that call is what
8362
+ // traverses the refines/contradiction_of edges.
8363
+ const doerRepoPath = kbPriming.folderOf(doerMember);
8364
+ const doerKnowledge = await kbWork.relevantKnowledge(doerRepoPath, kbQueryTerms(streak, actualBeadIds));
8365
+ const basePrompt = buildDoerPrompt({
8366
+ beadIds: actualBeadIds,
8367
+ branch: validated.branch,
8368
+ feedback: feedbackForStreak || null,
8369
+ kbKnowledge: doerKnowledge.length > 0 ? doerKnowledge : kbPriming.knowledgeOf(doerMember),
8370
+ });
7127
8371
  let doerPrompt = basePrompt;
7128
8372
  if (batchStreaks) {
7129
8373
  // Mode (i) BATCH: one dispatch carries the whole ordered
@@ -7397,11 +8641,18 @@ async function runSprintCycle(context) {
7397
8641
  });
7398
8642
  const closedIds = actualBeadIds.filter((id) => !unclosedIds.includes(id));
7399
8643
 
7400
- // Per-bead attribution is emitted always (not only when something
7401
- // failed) so every streak leaves an audit trail of exactly which
7402
- // beads closed vs which stayed open. Closed beads stay closed
7403
- // regardless of a sibling bead in the same streak being refused;
7404
- // only the still-open ones are eligible for re-laning next round
8644
+ // KB trust pipeline Phase 2: the doer decides what to capture,
8645
+ // the engine executes it against the repo THAT doer worked in.
8646
+ // Captures are honoured regardless of the streak outcome -- a
8647
+ // gotcha found on the way to a failed streak is still true.
8648
+ await kbWork.apply(ROLE_DOER, kbPriming.folderOf(doerMember), report);
8649
+
8650
+ // apra-fleet-eft.76.4: per-bead failure attribution -- always
8651
+ // emitted (not only when something failed) so every streak's
8652
+ // report leaves an audit trail of exactly which beads closed
8653
+ // vs which stayed open. Closed beads stay closed regardless
8654
+ // of a sibling bead in the same streak being refused; only
8655
+ // the still-open ones are eligible for re-laning next round
7405
8656
  // (the next dev round's `currentReady` query naturally omits
7406
8657
  // whatever already closed here).
7407
8658
  log(`Doer streak attribution [${actualBeadIds.join(', ')}]: closed=[${closedIds.join(', ')}] failed=[${unclosedIds.join(', ')}].`);
@@ -7530,7 +8781,10 @@ async function runSprintCycle(context) {
7530
8781
  // both reopenIds and newTasks empty is self-contradictory and must
7531
8782
  // never be treated as an ordinary "more work needed" round.
7532
8783
  const verdict = await dispatchReview({ beadIds: assignedBeadIds, acceptanceCriteriaJson });
7533
- // The last reviewer verdict seen THIS cycle feeds the Cycle
8784
+ // KB trust pipeline Phase 2: the reviewer decides, the engine executes.
8785
+ // Reviewer is the ONLY role whose kb_promotions are honoured.
8786
+ await kbWork.apply(ROLE_REVIEWER, kbPriming.folderOf(getMembersForRole(ROLE_REVIEWER)[0]), verdict);
8787
+ // A5: the last reviewer verdict seen THIS cycle feeds the Cycle
7534
8788
  // Evaluation section's completion check below -- goal-priority
7535
8789
  // completion requires this to be exactly 'APPROVED', not just
7536
8790
  // an empty ready-bead list.
@@ -7731,11 +8985,13 @@ async function runSprintCycle(context) {
7731
8985
 
7732
8986
  if (hasDeploy) {
7733
8987
  phase(`Deploy C${cycle}`);
8988
+ await ensureUnattendedAuto(getMemberForRole('deployer'));
8989
+ await ensureDeployPermissions(getMemberForRole('deployer'));
7734
8990
  let deployResult;
7735
8991
  // Turn budget for the deployer, with the same-session
7736
8992
  // turn-exhaustion resume below: a source-build fallback deploy runs
7737
8993
  // npm ci plus two builds, comfortably beyond a small default budget.
7738
- const DEPLOYER_MAX_TURNS = 60;
8994
+ const DEPLOYER_MAX_TURNS = 500;
7739
8995
  const deployerDispatchOpts = {
7740
8996
  member_name: getMemberForRole('deployer'),
7741
8997
  agentType: 'deployer',
@@ -7813,6 +9069,8 @@ async function runSprintCycle(context) {
7813
9069
  let verifySetForIntegTest = [];
7814
9070
  if (hasPlaybook && deployedThisCycle) {
7815
9071
  phase(`Integ Test C${cycle}`);
9072
+ await ensureUnattendedAuto(getMemberForRole('integ-test-runner'));
9073
+ await ensureDeployPermissions(getMemberForRole('integ-test-runner'));
7816
9074
  // apra-fleet-nwh.1: snapshot the running total BEFORE this
7817
9075
  // cycle's Integ Test dispatch(es) so the delta after (below) is
7818
9076
  // this phase's own spend, not the whole run's. budget.spent()
@@ -7925,7 +9183,7 @@ async function runSprintCycle(context) {
7925
9183
  // re-runs, respect the poll cadence) a normal cycle needs far
7926
9184
  // fewer than 300 turns. The resume ladder below still doubles from
7927
9185
  // here (to 600) when a run legitimately needs more.
7928
- const INTEG_TEST_MAX_TURNS = 300;
9186
+ const INTEG_TEST_MAX_TURNS = 500;
7929
9187
  const integDispatchOpts = {
7930
9188
  member_name: getMemberForRole('integ-test-runner'),
7931
9189
  agentType: 'integ-test-runner',
@@ -8079,7 +9337,7 @@ async function runSprintCycle(context) {
8079
9337
  if (gapCount > VERIFY_GAP_LIMIT) {
8080
9338
  log(`Verify-route bounce cap: ${parentId} has failed verification ${gapCount} time(s) this sprint (limit ${VERIFY_GAP_LIMIT}) -- deferring rather than bouncing again.`);
8081
9339
  await command(
8082
- `bd update ${parentId} --status=deferred --append-notes "Deferred by apra-fleet-jfo's verify-route bounce cap: failed integration-test verification ${gapCount} times this sprint (limit ${VERIFY_GAP_LIMIT}). Latest gap: ${bugId}."`,
9340
+ `bd update ${parentId} --status=deferred --append-notes "Deferred by the verify-route bounce cap: failed integration-test verification ${gapCount} times this sprint (limit ${VERIFY_GAP_LIMIT}). Latest gap: ${bugId}."`,
8083
9341
  { member_name: orchestratorMember, silent: true }
8084
9342
  );
8085
9343
  } else {
@@ -8121,7 +9379,7 @@ async function runSprintCycle(context) {
8121
9379
  // counts so the completion/stall math reads the current cross-member
8122
9380
  // beads state (every member's D-pushed closes) rather than the
8123
9381
  // orchestrator's stale local copy.
8124
- await DoltSync.syncBefore(orchestratorMember, { command, log, fatal: true });
9382
+ await DoltSync.syncBefore(orchestratorMember, { command, log, fatal: true, settle: buildSettleCallback(orchestratorMember, { command, log }) });
8125
9383
  // A decomposed parent (any bead that is itself someone's --parent,
8126
9384
  // including a childful --issue target) is excluded here the same way
8127
9385
  // readyLeafBeads() excludes it from dispatch: its own "done" status
@@ -8191,6 +9449,13 @@ async function runSprintCycle(context) {
8191
9449
 
8192
9450
  if (staleCycles >= STALL_CYCLE_LIMIT) {
8193
9451
  const thrashIds = thrashingBeadIds();
9452
+ // apra-fleet-mjo: counts alone ("history: [9, 14, 14, 14]") do not
9453
+ // tell an operator WHAT is holding the sprint open, which is
9454
+ // precisely what they need to intervene. Name the blocking beads.
9455
+ const blockerIds = openAtGoal.map((b) => b.id);
9456
+ const blockerSuffix = blockerIds.length > 0
9457
+ ? ` Still open at/above goal priority ${goalMax}: [${blockerIds.join(', ')}].`
9458
+ : ' No beads remain open at/above goal priority -- the stall is in closing out the sprint, not in the work itself.';
8194
9459
  const thrashSuffix = thrashIds.length > 0
8195
9460
  ? ` Reopen-thrash detected on bead(s) [${thrashIds.join(', ')}] (reopened more than ${REOPEN_THRASH_LIMIT} times) -- ` +
8196
9461
  `likely cause of the oscillation.`
@@ -8220,9 +9485,9 @@ async function runSprintCycle(context) {
8220
9485
  `Sprint stalled: ${staleCycles} consecutive cycle(s) made no new high-water-mark progress ` +
8221
9486
  `(closed beads + verify-routed beads) in scope '${sprintFilter}'. Closed-count history: ` +
8222
9487
  `[${closedCountHistory.join(', ')}] (high-water mark on progress score: ${highWaterClosedCount}).` +
8223
- thrashSuffix + verifySuffix +
9488
+ blockerSuffix + thrashSuffix + verifySuffix +
8224
9489
  ` Aborting rather than burning the remaining cycles.`,
8225
- { staleCycles, closedCountHistory, highWaterClosedCount, thrashIds, reopenCounts: Object.fromEntries(reopenCounts), verifyEverIds: [...verifyEverIds], cycle }
9490
+ { staleCycles, closedCountHistory, highWaterClosedCount, blockerIds, thrashIds, reopenCounts: Object.fromEntries(reopenCounts), verifyEverIds: [...verifyEverIds], cycle }
8226
9491
  );
8227
9492
  }
8228
9493
 
@@ -8270,6 +9535,7 @@ async function runSprintCycle(context) {
8270
9535
  // verdict in; acceptanceCriteriaJson still carries the full scope
8271
9536
  // for context.
8272
9537
  const reReviewVerdict = await dispatchReview({ beadIds: targetIssues, acceptanceCriteriaJson: JSON.stringify(reReviewScope) });
9538
+ await kbWork.apply(ROLE_REVIEWER, kbPriming.folderOf(getMembersForRole(ROLE_REVIEWER)[0]), reReviewVerdict);
8273
9539
  lastReviewVerdict = reReviewVerdict.verdict;
8274
9540
  reviewedThisCycle = true;
8275
9541
 
@@ -8401,7 +9667,7 @@ async function runSprintCycle(context) {
8401
9667
  // the sprint's closing evidence (finalOpenAtGoal / finalClosedCount)
8402
9668
  // reflects every member's D-pushed beads state, not the orchestrator's
8403
9669
  // stale local copy.
8404
- await DoltSync.syncBefore(orchestratorMember, { command, log, fatal: true });
9670
+ await DoltSync.syncBefore(orchestratorMember, { command, log, fatal: true, settle: buildSettleCallback(orchestratorMember, { command, log }) });
8405
9671
  const [finalOpenAtGoalRaw, finalOpenAtGoalParentIds, finalClosedBeads] = await Promise.all([
8406
9672
  bdListScoped(`--status=${NOT_DONE_STATUSES} --priority-max=${goalMax} --json`),
8407
9673
  decomposedParentIds(),
@@ -8433,7 +9699,7 @@ async function runSprintCycle(context) {
8433
9699
  // reviewer. Without it a large sprint's final review dies at the default
8434
9700
  // turn limit and flips the whole sprint to a FAIL whose notes carry no
8435
9701
  // findings at all.
8436
- const FINAL_REVIEW_MAX_TURNS = 60;
9702
+ const FINAL_REVIEW_MAX_TURNS = 500;
8437
9703
  // Final Review is the same 'reviewer' role as dispatchReview above
8438
9704
  // (read-side, pushCode: false) -- G-pull before, no-op G-push after every
8439
9705
  // attempt (including the retry below).
@@ -8450,6 +9716,15 @@ async function runSprintCycle(context) {
8450
9716
  max_total_s: DISPATCH_TIMEOUT_S,
8451
9717
  max_turns: FINAL_REVIEW_MAX_TURNS,
8452
9718
  };
9719
+ // apra-fleet-nx7: offer the final reviewer the same INFERRED candidates a
9720
+ // per-round reviewer gets. Fetched once, before the dispatch, so the retry
9721
+ // and resume paths below reuse the identical block rather than re-querying a
9722
+ // KB that its own earlier promotions may have already changed.
9723
+ const finalReviewRepoPath = kbPriming.folderOf(getMemberForRole('reviewer'));
9724
+ const finalKbCandidates = await kbWork.promotionCandidates(finalReviewRepoPath);
9725
+ if (finalKbCandidates.length > 0) {
9726
+ log(`[kb-work] offering ${finalKbCandidates.length} INFERRED entr(ies) to the final reviewer for promotion.`);
9727
+ }
8453
9728
  const dispatchFinalReview = () => withGitSync(getMemberForRole('reviewer'), false, () => agent(
8454
9729
  buildFinalVerdictPrompt({
8455
9730
  targetIssues,
@@ -8463,6 +9738,8 @@ async function runSprintCycle(context) {
8463
9738
  integFailures,
8464
9739
  rejectedNewTasks,
8465
9740
  unclosedVerifyIds: finalUnclosedVerifyIds,
9741
+ kbCandidates: finalKbCandidates,
9742
+ kbKnowledge: kbPriming.knowledgeOf(getMemberForRole('reviewer')),
8466
9743
  }),
8467
9744
  // member_name is repeated literally here -- not only via the
8468
9745
  // shared opts object -- so the source-level call-site parse in
@@ -8568,6 +9845,20 @@ async function runSprintCycle(context) {
8568
9845
  // see src/viewer/index.mjs), a second independent reason a raw JSON
8569
9846
  // re-print here would be redundant.
8570
9847
 
9848
+ // apra-fleet-nx7: execute the final reviewer's KB decisions through the same
9849
+ // path every per-round review uses. Deliberately NOT gated on the verdict --
9850
+ // a fact can be verified even when the sprint as a whole fails, and reviewer
9851
+ // contract already says as much ("Not tied to the verdict"). Placed before
9852
+ // the beads/PR work below and kept non-fatal by kbWork.apply itself, so a KB
9853
+ // problem can never change a sprint's outcome.
9854
+ await kbWork.apply(ROLE_REVIEWER, finalReviewRepoPath, finalVerdictResult);
9855
+
9856
+ // Publish what this sprint confirmed. Immediately after the LAST promotion
9857
+ // of the run, so the bible carries every CONFIRMED entry including the ones
9858
+ // minted a line above. Without this the sprint's knowledge never left the
9859
+ // member's local sqlite store -- see createKbWorkClient.exportBible.
9860
+ await kbWork.exportBible(finalReviewRepoPath);
9861
+
8571
9862
  // Persist the Final Review's actionable findings to BEADS -- the only
8572
9863
  // artifact the next sprint's planner reads (notes reach only the PR body
8573
9864
  // and the analysis doc). NOT gated to FAIL: a PASS can still surface real
@@ -8724,11 +10015,13 @@ async function runSprintCycle(context) {
8724
10015
  const hasRegressionPlaybook = await probeFileExists('regression-test-playbook.md');
8725
10016
  if (hasRegressionPlaybook) {
8726
10017
  phase(`Regression Test C${finalCycleLabel}`);
10018
+ await ensureUnattendedAuto(getMemberForRole('regression-test-runner'));
10019
+ await ensureDeployPermissions(getMemberForRole('regression-test-runner'));
8727
10020
  // The real functional suite alone spends roughly one turn per liveness
8728
10021
  // poll for the better part of an hour, and this single dispatch carries
8729
10022
  // both it and the sandbox smoke sprint -- hence the large turn budget
8730
10023
  // and the wider hard ceiling.
8731
- const REGRESSION_TEST_MAX_TURNS = 200;
10024
+ const REGRESSION_TEST_MAX_TURNS = 500;
8732
10025
  const REGRESSION_TEST_MAX_TOTAL_S = DISPATCH_TIMEOUT_S * 3;
8733
10026
  const regressionPrompt =
8734
10027
  `Run the full regression pass using regression-test-playbook.md at the repo root: part 1 ` +
@@ -8897,7 +10190,7 @@ async function runSprintCycle(context) {
8897
10190
  let harvesterResult = null;
8898
10191
  // Turn budget for the harvester, with the same-session turn-exhaustion
8899
10192
  // resume below: it writes docs/changelog across the whole epic.
8900
- const HARVESTER_MAX_TURNS = 60;
10193
+ const HARVESTER_MAX_TURNS = 500;
8901
10194
  const harvesterDispatchOpts = {
8902
10195
  member_name: getMemberForRole('harvester'),
8903
10196
  agentType: 'harvester',
@@ -8943,6 +10236,13 @@ async function runSprintCycle(context) {
8943
10236
  // path itself IS worth a line: it is the durable, committed record of
8944
10237
  // the Final Review verdict (and everything else in analysisText) --
8945
10238
  // unlike the verdict object, it survives after this process exits.
10239
+ // harvester-output.json declares kb_captures, and until now nothing
10240
+ // consumed it: the harvester filled the field and the engine dropped it
10241
+ // -- the same "gathered and thrown away" shape kbWork was built to fix
10242
+ // for the doer and reviewer. The harvester is a good capturer precisely
10243
+ // because it has just read the whole sprint's evidence. Capture only:
10244
+ // vetKbWork refuses kb_promotions from any role but the reviewer.
10245
+ await kbWork.apply('harvester', kbPriming.folderOf(getMemberForRole('harvester')), harvesterResult);
8946
10246
  if (harvesterResult.status !== 'OK') {
8947
10247
  log(`Harvester reported FAILED: ${harvesterResult.notes}`);
8948
10248
  } else {