@apralabs/apra-fleet 0.4.0 → 0.4.2

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 (548) hide show
  1. package/README.md +159 -13
  2. package/dist/agents/backlog-groomer.md +31 -19
  3. package/dist/agents/ci-watcher.md +16 -1
  4. package/dist/agents/deployer.md +37 -47
  5. package/dist/agents/doer.md +147 -114
  6. package/dist/agents/harvester.md +41 -34
  7. package/dist/agents/integ-test-runner.md +98 -114
  8. package/dist/agents/kb-reconciler.md +205 -0
  9. package/dist/agents/plan-reviewer.md +45 -44
  10. package/dist/agents/planner.md +121 -50
  11. package/dist/agents/regression-test-runner.md +84 -81
  12. package/dist/agents/reviewer.md +118 -44
  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 +3 -3
  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/regression-test-runner-output.json +4 -17
  19. package/dist/agents/schemas/reviewer-output.json +105 -8
  20. package/dist/cli/auth.d.ts.map +1 -1
  21. package/dist/cli/auth.js +1 -2
  22. package/dist/cli/auth.js.map +1 -1
  23. package/dist/cli/config.d.ts +3 -3
  24. package/dist/cli/config.d.ts.map +1 -1
  25. package/dist/cli/config.js +4 -13
  26. package/dist/cli/config.js.map +1 -1
  27. package/dist/cli/install.d.ts +1 -0
  28. package/dist/cli/install.d.ts.map +1 -1
  29. package/dist/cli/install.js +141 -44
  30. package/dist/cli/install.js.map +1 -1
  31. package/dist/cli/join.js +1 -1
  32. package/dist/cli/join.js.map +1 -1
  33. package/dist/cli/kb-commit.d.ts +12 -0
  34. package/dist/cli/kb-commit.d.ts.map +1 -0
  35. package/dist/cli/kb-commit.js +53 -0
  36. package/dist/cli/kb-commit.js.map +1 -0
  37. package/dist/cli/kb-directives.d.ts +17 -0
  38. package/dist/cli/kb-directives.d.ts.map +1 -0
  39. package/dist/cli/kb-directives.js +146 -0
  40. package/dist/cli/kb-directives.js.map +1 -0
  41. package/dist/cli/kb-import.d.ts +13 -0
  42. package/dist/cli/kb-import.d.ts.map +1 -0
  43. package/dist/cli/kb-import.js +56 -0
  44. package/dist/cli/kb-import.js.map +1 -0
  45. package/dist/cli/register-member.js +1 -1
  46. package/dist/cli/start.d.ts.map +1 -1
  47. package/dist/cli/start.js +7 -0
  48. package/dist/cli/start.js.map +1 -1
  49. package/dist/cli/uninstall.d.ts.map +1 -1
  50. package/dist/cli/uninstall.js +16 -3
  51. package/dist/cli/uninstall.js.map +1 -1
  52. package/dist/cli/watch.d.ts +76 -4
  53. package/dist/cli/watch.d.ts.map +1 -1
  54. package/dist/cli/watch.js +150 -17
  55. package/dist/cli/watch.js.map +1 -1
  56. package/dist/commands/kb-server.d.ts +8 -0
  57. package/dist/commands/kb-server.d.ts.map +1 -0
  58. package/dist/commands/kb-server.js +221 -0
  59. package/dist/commands/kb-server.js.map +1 -0
  60. package/dist/index.js +77 -2
  61. package/dist/index.js.map +1 -1
  62. package/dist/os/git-bash-candidates.d.ts +35 -0
  63. package/dist/os/git-bash-candidates.d.ts.map +1 -0
  64. package/dist/os/git-bash-candidates.js +46 -0
  65. package/dist/os/git-bash-candidates.js.map +1 -0
  66. package/dist/os/index.d.ts +13 -4
  67. package/dist/os/index.d.ts.map +1 -1
  68. package/dist/os/index.js +17 -2
  69. package/dist/os/index.js.map +1 -1
  70. package/dist/os/linux.d.ts +1 -0
  71. package/dist/os/linux.d.ts.map +1 -1
  72. package/dist/os/linux.js +19 -2
  73. package/dist/os/linux.js.map +1 -1
  74. package/dist/os/os-commands.d.ts +12 -0
  75. package/dist/os/os-commands.d.ts.map +1 -1
  76. package/dist/os/os-commands.js.map +1 -1
  77. package/dist/os/windows-gitbash.d.ts +93 -0
  78. package/dist/os/windows-gitbash.d.ts.map +1 -0
  79. package/dist/os/windows-gitbash.js +244 -0
  80. package/dist/os/windows-gitbash.js.map +1 -0
  81. package/dist/os/windows.d.ts +35 -0
  82. package/dist/os/windows.d.ts.map +1 -1
  83. package/dist/os/windows.js +93 -35
  84. package/dist/os/windows.js.map +1 -1
  85. package/dist/providers/agy.d.ts +15 -3
  86. package/dist/providers/agy.d.ts.map +1 -1
  87. package/dist/providers/agy.js +145 -11
  88. package/dist/providers/agy.js.map +1 -1
  89. package/dist/providers/claude.d.ts +14 -3
  90. package/dist/providers/claude.d.ts.map +1 -1
  91. package/dist/providers/claude.js +69 -22
  92. package/dist/providers/claude.js.map +1 -1
  93. package/dist/providers/codex.d.ts +14 -3
  94. package/dist/providers/codex.d.ts.map +1 -1
  95. package/dist/providers/codex.js +34 -8
  96. package/dist/providers/codex.js.map +1 -1
  97. package/dist/providers/copilot.d.ts +14 -3
  98. package/dist/providers/copilot.d.ts.map +1 -1
  99. package/dist/providers/copilot.js +33 -8
  100. package/dist/providers/copilot.js.map +1 -1
  101. package/dist/providers/email/headers.d.ts +15 -0
  102. package/dist/providers/email/headers.d.ts.map +1 -0
  103. package/dist/providers/email/headers.js +42 -0
  104. package/dist/providers/email/headers.js.map +1 -0
  105. package/dist/providers/email/index.d.ts +18 -0
  106. package/dist/providers/email/index.d.ts.map +1 -0
  107. package/dist/providers/email/index.js +60 -0
  108. package/dist/providers/email/index.js.map +1 -0
  109. package/dist/providers/email/provider.d.ts +49 -0
  110. package/dist/providers/email/provider.d.ts.map +1 -0
  111. package/dist/providers/email/provider.js +2 -0
  112. package/dist/providers/email/provider.js.map +1 -0
  113. package/dist/providers/email/sendgrid.d.ts +12 -0
  114. package/dist/providers/email/sendgrid.d.ts.map +1 -0
  115. package/dist/providers/email/sendgrid.js +67 -0
  116. package/dist/providers/email/sendgrid.js.map +1 -0
  117. package/dist/providers/email/smtp.d.ts +65 -0
  118. package/dist/providers/email/smtp.d.ts.map +1 -0
  119. package/dist/providers/email/smtp.js +373 -0
  120. package/dist/providers/email/smtp.js.map +1 -0
  121. package/dist/providers/index.d.ts +0 -1
  122. package/dist/providers/index.d.ts.map +1 -1
  123. package/dist/providers/index.js +0 -3
  124. package/dist/providers/index.js.map +1 -1
  125. package/dist/providers/none.d.ts +14 -3
  126. package/dist/providers/none.d.ts.map +1 -1
  127. package/dist/providers/none.js +26 -2
  128. package/dist/providers/none.js.map +1 -1
  129. package/dist/providers/opencode.d.ts +14 -3
  130. package/dist/providers/opencode.d.ts.map +1 -1
  131. package/dist/providers/opencode.js +60 -6
  132. package/dist/providers/opencode.js.map +1 -1
  133. package/dist/providers/provider.d.ts +91 -5
  134. package/dist/providers/provider.d.ts.map +1 -1
  135. package/dist/providers/provider.js +45 -1
  136. package/dist/providers/provider.js.map +1 -1
  137. package/dist/services/agent-provisioner.d.ts.map +1 -1
  138. package/dist/services/agent-provisioner.js +5 -8
  139. package/dist/services/agent-provisioner.js.map +1 -1
  140. package/dist/services/cloud/activity.js +2 -2
  141. package/dist/services/cloud/activity.js.map +1 -1
  142. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  143. package/dist/services/cloud/lifecycle.js +3 -0
  144. package/dist/services/cloud/lifecycle.js.map +1 -1
  145. package/dist/services/cloud/task-wrapper.d.ts +18 -0
  146. package/dist/services/cloud/task-wrapper.d.ts.map +1 -1
  147. package/dist/services/cloud/task-wrapper.js +157 -0
  148. package/dist/services/cloud/task-wrapper.js.map +1 -1
  149. package/dist/services/context-admission.d.ts.map +1 -1
  150. package/dist/services/context-admission.js +9 -7
  151. package/dist/services/context-admission.js.map +1 -1
  152. package/dist/services/credential-cleanup.d.ts.map +1 -1
  153. package/dist/services/credential-cleanup.js +22 -3
  154. package/dist/services/credential-cleanup.js.map +1 -1
  155. package/dist/services/github-app.d.ts.map +1 -1
  156. package/dist/services/github-app.js +11 -2
  157. package/dist/services/github-app.js.map +1 -1
  158. package/dist/services/knowledge/audn.d.ts +37 -0
  159. package/dist/services/knowledge/audn.d.ts.map +1 -0
  160. package/dist/services/knowledge/audn.js +219 -0
  161. package/dist/services/knowledge/audn.js.map +1 -0
  162. package/dist/services/knowledge/file-hash.d.ts +11 -0
  163. package/dist/services/knowledge/file-hash.d.ts.map +1 -0
  164. package/dist/services/knowledge/file-hash.js +123 -0
  165. package/dist/services/knowledge/file-hash.js.map +1 -0
  166. package/dist/services/knowledge/http-provider.d.ts +46 -0
  167. package/dist/services/knowledge/http-provider.d.ts.map +1 -0
  168. package/dist/services/knowledge/http-provider.js +254 -0
  169. package/dist/services/knowledge/http-provider.js.map +1 -0
  170. package/dist/services/knowledge/kb-providers.d.ts +15 -0
  171. package/dist/services/knowledge/kb-providers.d.ts.map +1 -0
  172. package/dist/services/knowledge/kb-providers.js +92 -0
  173. package/dist/services/knowledge/kb-providers.js.map +1 -0
  174. package/dist/services/knowledge/kb-scope-input.d.ts +5 -0
  175. package/dist/services/knowledge/kb-scope-input.d.ts.map +1 -0
  176. package/dist/services/knowledge/kb-scope-input.js +11 -0
  177. package/dist/services/knowledge/kb-scope-input.js.map +1 -0
  178. package/dist/services/knowledge/kb-service.d.ts +3 -0
  179. package/dist/services/knowledge/kb-service.d.ts.map +1 -0
  180. package/dist/services/knowledge/kb-service.js +2 -0
  181. package/dist/services/knowledge/kb-service.js.map +1 -0
  182. package/dist/services/knowledge/path-validation.d.ts +2 -0
  183. package/dist/services/knowledge/path-validation.d.ts.map +1 -0
  184. package/dist/services/knowledge/path-validation.js +13 -0
  185. package/dist/services/knowledge/path-validation.js.map +1 -0
  186. package/dist/services/knowledge/pre-init.d.ts +14 -0
  187. package/dist/services/knowledge/pre-init.d.ts.map +1 -0
  188. package/dist/services/knowledge/pre-init.js +147 -0
  189. package/dist/services/knowledge/pre-init.js.map +1 -0
  190. package/dist/services/knowledge/project-slug.d.ts +2 -0
  191. package/dist/services/knowledge/project-slug.d.ts.map +1 -0
  192. package/dist/services/knowledge/project-slug.js +49 -0
  193. package/dist/services/knowledge/project-slug.js.map +1 -0
  194. package/dist/services/knowledge/sqlite-provider.d.ts +147 -0
  195. package/dist/services/knowledge/sqlite-provider.d.ts.map +1 -0
  196. package/dist/services/knowledge/sqlite-provider.js +1646 -0
  197. package/dist/services/knowledge/sqlite-provider.js.map +1 -0
  198. package/dist/services/knowledge/types.d.ts +163 -0
  199. package/dist/services/knowledge/types.d.ts.map +1 -0
  200. package/dist/services/knowledge/types.js +9 -0
  201. package/dist/services/knowledge/types.js.map +1 -0
  202. package/dist/services/member-home.d.ts +89 -0
  203. package/dist/services/member-home.d.ts.map +1 -0
  204. package/dist/services/member-home.js +259 -0
  205. package/dist/services/member-home.js.map +1 -0
  206. package/dist/services/member-remote-url.d.ts +34 -0
  207. package/dist/services/member-remote-url.d.ts.map +1 -0
  208. package/dist/services/member-remote-url.js +39 -0
  209. package/dist/services/member-remote-url.js.map +1 -0
  210. package/dist/services/model-pricing.d.ts.map +1 -1
  211. package/dist/services/model-pricing.js +0 -5
  212. package/dist/services/model-pricing.js.map +1 -1
  213. package/dist/services/orphan-recovery.d.ts +9 -3
  214. package/dist/services/orphan-recovery.d.ts.map +1 -1
  215. package/dist/services/orphan-recovery.js +22 -8
  216. package/dist/services/orphan-recovery.js.map +1 -1
  217. package/dist/services/preflight-check.d.ts +56 -0
  218. package/dist/services/preflight-check.d.ts.map +1 -0
  219. package/dist/services/preflight-check.js +277 -0
  220. package/dist/services/preflight-check.js.map +1 -0
  221. package/dist/services/shell-probe.d.ts +131 -0
  222. package/dist/services/shell-probe.d.ts.map +1 -0
  223. package/dist/services/shell-probe.js +210 -0
  224. package/dist/services/shell-probe.js.map +1 -0
  225. package/dist/services/singleton.d.ts +2 -0
  226. package/dist/services/singleton.d.ts.map +1 -1
  227. package/dist/services/singleton.js +1 -1
  228. package/dist/services/singleton.js.map +1 -1
  229. package/dist/services/ssh.js +2 -2
  230. package/dist/services/ssh.js.map +1 -1
  231. package/dist/services/stall/find-log-file.d.ts.map +1 -1
  232. package/dist/services/stall/find-log-file.js +22 -16
  233. package/dist/services/stall/find-log-file.js.map +1 -1
  234. package/dist/services/stall/log-path-resolver.d.ts +11 -8
  235. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  236. package/dist/services/stall/log-path-resolver.js +17 -40
  237. package/dist/services/stall/log-path-resolver.js.map +1 -1
  238. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  239. package/dist/services/stall/read-log-tail.js +6 -5
  240. package/dist/services/stall/read-log-tail.js.map +1 -1
  241. package/dist/services/stall/stall-detector.d.ts +32 -0
  242. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  243. package/dist/services/stall/stall-detector.js +149 -6
  244. package/dist/services/stall/stall-detector.js.map +1 -1
  245. package/dist/services/stall/stall-poller.d.ts +34 -0
  246. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  247. package/dist/services/stall/stall-poller.js +160 -35
  248. package/dist/services/stall/stall-poller.js.map +1 -1
  249. package/dist/services/strategy.d.ts +9 -0
  250. package/dist/services/strategy.d.ts.map +1 -1
  251. package/dist/services/strategy.js +41 -7
  252. package/dist/services/strategy.js.map +1 -1
  253. package/dist/services/tool-registry.d.ts.map +1 -1
  254. package/dist/services/tool-registry.js +87 -1
  255. package/dist/services/tool-registry.js.map +1 -1
  256. package/dist/services/user-config.js +1 -1
  257. package/dist/services/user-config.js.map +1 -1
  258. package/dist/services/vcs/azure-devops.d.ts +1 -1
  259. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  260. package/dist/services/vcs/azure-devops.js +105 -10
  261. package/dist/services/vcs/azure-devops.js.map +1 -1
  262. package/dist/services/vcs/bitbucket.d.ts.map +1 -1
  263. package/dist/services/vcs/bitbucket.js +16 -0
  264. package/dist/services/vcs/bitbucket.js.map +1 -1
  265. package/dist/services/vcs/github.d.ts.map +1 -1
  266. package/dist/services/vcs/github.js +56 -1
  267. package/dist/services/vcs/github.js.map +1 -1
  268. package/dist/services/vcs/types.d.ts +123 -2
  269. package/dist/services/vcs/types.d.ts.map +1 -1
  270. package/dist/services/version-check.d.ts +22 -0
  271. package/dist/services/version-check.d.ts.map +1 -0
  272. package/dist/services/version-check.js +103 -0
  273. package/dist/services/version-check.js.map +1 -0
  274. package/dist/skills/fleet-sprint-cli/SKILL.md +15 -3
  275. package/dist/skills/pm/SKILL.md +0 -1
  276. package/dist/skills/pm/beads.md +6 -0
  277. package/dist/skills/pm/cost.md +0 -1
  278. package/dist/skills/pm/fleet-addendum.md +6 -1
  279. package/dist/skills/pm/index.md +56 -0
  280. package/dist/skills/pm/kb-reconcile.md +132 -0
  281. package/dist/skills/pm/kb-review.md +109 -0
  282. package/dist/tools/check-status.d.ts +47 -0
  283. package/dist/tools/check-status.d.ts.map +1 -1
  284. package/dist/tools/check-status.js +245 -3
  285. package/dist/tools/check-status.js.map +1 -1
  286. package/dist/tools/child-id-allocator.d.ts +2 -2
  287. package/dist/tools/cloud-control.js +2 -2
  288. package/dist/tools/cloud-control.js.map +1 -1
  289. package/dist/tools/code-intelligence-codebase-memory.d.ts +11 -0
  290. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +1 -0
  291. package/dist/tools/code-intelligence-codebase-memory.js +270 -0
  292. package/dist/tools/code-intelligence-codebase-memory.js.map +1 -0
  293. package/dist/tools/code-intelligence-freshness.d.ts +2 -0
  294. package/dist/tools/code-intelligence-freshness.d.ts.map +1 -0
  295. package/dist/tools/code-intelligence-freshness.js +26 -0
  296. package/dist/tools/code-intelligence-freshness.js.map +1 -0
  297. package/dist/tools/code-intelligence-gitnexus.d.ts +14 -0
  298. package/dist/tools/code-intelligence-gitnexus.d.ts.map +1 -0
  299. package/dist/tools/code-intelligence-gitnexus.js +475 -0
  300. package/dist/tools/code-intelligence-gitnexus.js.map +1 -0
  301. package/dist/tools/code-intelligence-kb-enrich.d.ts +2 -0
  302. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +1 -0
  303. package/dist/tools/code-intelligence-kb-enrich.js +65 -0
  304. package/dist/tools/code-intelligence-kb-enrich.js.map +1 -0
  305. package/dist/tools/code-intelligence-reindex.d.ts +7 -0
  306. package/dist/tools/code-intelligence-reindex.d.ts.map +1 -0
  307. package/dist/tools/code-intelligence-reindex.js +106 -0
  308. package/dist/tools/code-intelligence-reindex.js.map +1 -0
  309. package/dist/tools/code-intelligence-telemetry.d.ts +5 -0
  310. package/dist/tools/code-intelligence-telemetry.d.ts.map +1 -0
  311. package/dist/tools/code-intelligence-telemetry.js +52 -0
  312. package/dist/tools/code-intelligence-telemetry.js.map +1 -0
  313. package/dist/tools/code-intelligence-tests.d.ts +2 -0
  314. package/dist/tools/code-intelligence-tests.d.ts.map +1 -0
  315. package/dist/tools/code-intelligence-tests.js +24 -0
  316. package/dist/tools/code-intelligence-tests.js.map +1 -0
  317. package/dist/tools/code-intelligence.d.ts +114 -0
  318. package/dist/tools/code-intelligence.d.ts.map +1 -0
  319. package/dist/tools/code-intelligence.js +124 -0
  320. package/dist/tools/code-intelligence.js.map +1 -0
  321. package/dist/tools/compose-permissions.d.ts +26 -0
  322. package/dist/tools/compose-permissions.d.ts.map +1 -1
  323. package/dist/tools/compose-permissions.js +257 -33
  324. package/dist/tools/compose-permissions.js.map +1 -1
  325. package/dist/tools/execute-command.d.ts +2 -0
  326. package/dist/tools/execute-command.d.ts.map +1 -1
  327. package/dist/tools/execute-command.js +114 -28
  328. package/dist/tools/execute-command.js.map +1 -1
  329. package/dist/tools/execute-prompt.d.ts +13 -1
  330. package/dist/tools/execute-prompt.d.ts.map +1 -1
  331. package/dist/tools/execute-prompt.js +310 -61
  332. package/dist/tools/execute-prompt.js.map +1 -1
  333. package/dist/tools/kb-capture.d.ts +53 -0
  334. package/dist/tools/kb-capture.d.ts.map +1 -0
  335. package/dist/tools/kb-capture.js +130 -0
  336. package/dist/tools/kb-capture.js.map +1 -0
  337. package/dist/tools/kb-context.d.ts +17 -0
  338. package/dist/tools/kb-context.d.ts.map +1 -0
  339. package/dist/tools/kb-context.js +29 -0
  340. package/dist/tools/kb-context.js.map +1 -0
  341. package/dist/tools/kb-export.d.ts +19 -0
  342. package/dist/tools/kb-export.d.ts.map +1 -0
  343. package/dist/tools/kb-export.js +344 -0
  344. package/dist/tools/kb-export.js.map +1 -0
  345. package/dist/tools/kb-feedback.d.ts +23 -0
  346. package/dist/tools/kb-feedback.d.ts.map +1 -0
  347. package/dist/tools/kb-feedback.js +43 -0
  348. package/dist/tools/kb-feedback.js.map +1 -0
  349. package/dist/tools/kb-freshness-sweep.d.ts +14 -0
  350. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -0
  351. package/dist/tools/kb-freshness-sweep.js +29 -0
  352. package/dist/tools/kb-freshness-sweep.js.map +1 -0
  353. package/dist/tools/kb-harvest.d.ts +20 -0
  354. package/dist/tools/kb-harvest.d.ts.map +1 -0
  355. package/dist/tools/kb-harvest.js +143 -0
  356. package/dist/tools/kb-harvest.js.map +1 -0
  357. package/dist/tools/kb-import.d.ts +44 -0
  358. package/dist/tools/kb-import.d.ts.map +1 -0
  359. package/dist/tools/kb-import.js +239 -0
  360. package/dist/tools/kb-import.js.map +1 -0
  361. package/dist/tools/kb-invalidate.d.ts +19 -0
  362. package/dist/tools/kb-invalidate.d.ts.map +1 -0
  363. package/dist/tools/kb-invalidate.js +34 -0
  364. package/dist/tools/kb-invalidate.js.map +1 -0
  365. package/dist/tools/kb-list.d.ts +32 -0
  366. package/dist/tools/kb-list.d.ts.map +1 -0
  367. package/dist/tools/kb-list.js +43 -0
  368. package/dist/tools/kb-list.js.map +1 -0
  369. package/dist/tools/kb-promote.d.ts +20 -0
  370. package/dist/tools/kb-promote.d.ts.map +1 -0
  371. package/dist/tools/kb-promote.js +20 -0
  372. package/dist/tools/kb-promote.js.map +1 -0
  373. package/dist/tools/kb-query.d.ts +35 -0
  374. package/dist/tools/kb-query.d.ts.map +1 -0
  375. package/dist/tools/kb-query.js +111 -0
  376. package/dist/tools/kb-query.js.map +1 -0
  377. package/dist/tools/kb-reconcile-prefilter.d.ts +14 -0
  378. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -0
  379. package/dist/tools/kb-reconcile-prefilter.js +26 -0
  380. package/dist/tools/kb-reconcile-prefilter.js.map +1 -0
  381. package/dist/tools/kb-resolve-contradiction.d.ts +23 -0
  382. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -0
  383. package/dist/tools/kb-resolve-contradiction.js +37 -0
  384. package/dist/tools/kb-resolve-contradiction.js.map +1 -0
  385. package/dist/tools/kb-session-prime.d.ts +26 -0
  386. package/dist/tools/kb-session-prime.d.ts.map +1 -0
  387. package/dist/tools/kb-session-prime.js +392 -0
  388. package/dist/tools/kb-session-prime.js.map +1 -0
  389. package/dist/tools/kb-setup.d.ts +20 -0
  390. package/dist/tools/kb-setup.d.ts.map +1 -0
  391. package/dist/tools/kb-setup.js +49 -0
  392. package/dist/tools/kb-setup.js.map +1 -0
  393. package/dist/tools/kb-stats.d.ts +20 -0
  394. package/dist/tools/kb-stats.d.ts.map +1 -0
  395. package/dist/tools/kb-stats.js +115 -0
  396. package/dist/tools/kb-stats.js.map +1 -0
  397. package/dist/tools/list-members.d.ts.map +1 -1
  398. package/dist/tools/list-members.js +6 -2
  399. package/dist/tools/list-members.js.map +1 -1
  400. package/dist/tools/member-detail.d.ts.map +1 -1
  401. package/dist/tools/member-detail.js +13 -3
  402. package/dist/tools/member-detail.js.map +1 -1
  403. package/dist/tools/member-reservation.d.ts.map +1 -1
  404. package/dist/tools/member-reservation.js +13 -1
  405. package/dist/tools/member-reservation.js.map +1 -1
  406. package/dist/tools/monitor-task.d.ts.map +1 -1
  407. package/dist/tools/monitor-task.js +38 -5
  408. package/dist/tools/monitor-task.js.map +1 -1
  409. package/dist/tools/provision-auth.d.ts.map +1 -1
  410. package/dist/tools/provision-auth.js +15 -8
  411. package/dist/tools/provision-auth.js.map +1 -1
  412. package/dist/tools/provision-vcs-auth.d.ts +5 -2
  413. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  414. package/dist/tools/provision-vcs-auth.js +58 -52
  415. package/dist/tools/provision-vcs-auth.js.map +1 -1
  416. package/dist/tools/register-member.d.ts +21 -12
  417. package/dist/tools/register-member.d.ts.map +1 -1
  418. package/dist/tools/register-member.js +70 -3
  419. package/dist/tools/register-member.js.map +1 -1
  420. package/dist/tools/remove-member.d.ts.map +1 -1
  421. package/dist/tools/remove-member.js +19 -5
  422. package/dist/tools/remove-member.js.map +1 -1
  423. package/dist/tools/report-status.d.ts.map +1 -1
  424. package/dist/tools/report-status.js +2 -1
  425. package/dist/tools/report-status.js.map +1 -1
  426. package/dist/tools/revoke-vcs-auth.js +2 -2
  427. package/dist/tools/revoke-vcs-auth.js.map +1 -1
  428. package/dist/tools/send-email.d.ts +69 -0
  429. package/dist/tools/send-email.d.ts.map +1 -0
  430. package/dist/tools/send-email.js +177 -0
  431. package/dist/tools/send-email.js.map +1 -0
  432. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  433. package/dist/tools/setup-ssh-key.js +4 -1
  434. package/dist/tools/setup-ssh-key.js.map +1 -1
  435. package/dist/tools/stop-prompt.js +2 -2
  436. package/dist/tools/stop-prompt.js.map +1 -1
  437. package/dist/tools/update-agent-cli.js +2 -2
  438. package/dist/tools/update-agent-cli.js.map +1 -1
  439. package/dist/tools/update-member.d.ts +21 -12
  440. package/dist/tools/update-member.d.ts.map +1 -1
  441. package/dist/tools/update-member.js +43 -2
  442. package/dist/tools/update-member.js.map +1 -1
  443. package/dist/types.d.ts +12 -1
  444. package/dist/types.d.ts.map +1 -1
  445. package/dist/utils/agent-helpers.d.ts +36 -0
  446. package/dist/utils/agent-helpers.d.ts.map +1 -1
  447. package/dist/utils/agent-helpers.js +39 -1
  448. package/dist/utils/agent-helpers.js.map +1 -1
  449. package/dist/utils/platform.d.ts +7 -0
  450. package/dist/utils/platform.d.ts.map +1 -1
  451. package/dist/utils/platform.js +11 -1
  452. package/dist/utils/platform.js.map +1 -1
  453. package/dist/utils/prompt-errors.js +1 -1
  454. package/dist/utils/prompt-errors.js.map +1 -1
  455. package/dist/utils/session-caller.d.ts +28 -0
  456. package/dist/utils/session-caller.d.ts.map +1 -0
  457. package/dist/utils/session-caller.js +24 -0
  458. package/dist/utils/session-caller.js.map +1 -0
  459. package/dist/utils/work-folder-validation.d.ts +39 -0
  460. package/dist/utils/work-folder-validation.d.ts.map +1 -0
  461. package/dist/utils/work-folder-validation.js +60 -0
  462. package/dist/utils/work-folder-validation.js.map +1 -0
  463. package/dist/utils/workspace-trust.d.ts.map +1 -1
  464. package/dist/utils/workspace-trust.js +5 -1
  465. package/dist/utils/workspace-trust.js.map +1 -1
  466. package/dist/workflows/auto-sprint.js +550 -23
  467. package/package.json +7 -4
  468. package/packages/apra-fleet-client/src/client/api.mjs +210 -7
  469. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +31 -19
  470. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +16 -1
  471. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +37 -47
  472. package/packages/apra-fleet-se/apra-pm/agents/doer.md +147 -114
  473. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +41 -34
  474. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +98 -114
  475. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +205 -0
  476. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +45 -44
  477. package/packages/apra-fleet-se/apra-pm/agents/planner.md +121 -50
  478. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +84 -81
  479. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +118 -44
  480. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +63 -3
  481. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +59 -2
  482. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +3 -3
  483. package/packages/apra-fleet-se/apra-pm/agents/schemas/kb-reconciler-output.json +87 -0
  484. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +65 -0
  485. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
  486. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +105 -8
  487. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +0 -1
  488. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +6 -0
  489. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -1
  490. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +6 -1
  491. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +56 -0
  492. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +132 -0
  493. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +109 -0
  494. package/packages/apra-fleet-se/bin/cli.mjs +139 -3
  495. package/packages/apra-fleet-se/bin/serve.mjs +49 -2
  496. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +182 -38
  497. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +23 -8
  498. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +258 -0
  499. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +1487 -0
  500. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +908 -0
  501. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +399 -0
  502. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
  503. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +1148 -0
  504. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +229 -112
  505. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +91 -6
  506. package/packages/apra-fleet-se/fleet-sprint/runner.js +2469 -238
  507. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
  508. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +154 -0
  509. package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
  510. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
  511. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +15 -3
  512. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +350 -0
  513. package/packages/apra-fleet-se/fleet-sprint/sprint-progress.mjs +101 -0
  514. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +51 -0
  515. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +657 -12
  516. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
  517. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +60 -30
  518. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +205 -2
  519. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +164 -0
  520. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +141 -26
  521. package/packages/apra-fleet-se/package.json +1 -0
  522. package/packages/apra-fleet-workflow/src/viewer/index.mjs +294 -14
  523. package/packages/apra-fleet-workflow/src/viewer/run-title.mjs +60 -0
  524. package/packages/apra-fleet-workflow/src/workflow/index.mjs +443 -35
  525. package/skills/fleet/SKILL.md +20 -9
  526. package/skills/fleet/auth-azdevops.md +44 -5
  527. package/skills/fleet/auth-bitbucket.md +3 -3
  528. package/skills/fleet/auth-github.md +2 -2
  529. package/skills/fleet/beads-conflict-resolution.md +141 -0
  530. package/skills/fleet/beads.md +16 -12
  531. package/skills/fleet/knowledge-agent.md +66 -0
  532. package/skills/fleet/onboarding.md +4 -4
  533. package/skills/fleet/permissions.md +32 -8
  534. package/skills/fleet/profiles/base-dev.json +10 -1
  535. package/skills/fleet/profiles/base-reviewer.json +8 -1
  536. package/skills/fleet/profiles/tag-kb-reconciler.json +20 -0
  537. package/skills/fleet/skill-matrix.md +1 -1
  538. package/skills/fleet/troubleshooting.md +2 -1
  539. package/version.json +1 -1
  540. package/dist/providers/gemini.d.ts +0 -42
  541. package/dist/providers/gemini.d.ts.map +0 -1
  542. package/dist/providers/gemini.js +0 -202
  543. package/dist/providers/gemini.js.map +0 -1
  544. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -151
  545. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +0 -127
  546. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +0 -339
  547. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +0 -360
  548. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +0 -363
@@ -94,31 +94,37 @@ export function validateRole(role) {
94
94
  // 2. Role-owned schema loader (apra-fleet-unw.22, packaging-safe per apra-fleet-bun)
95
95
  // ---------------------------------------------------------------------------
96
96
  //
97
- // Schema resolution is layout-aware and bundled-location-first (apra-fleet-
98
- // bun), because apra-fleet-se must resolve its apra-pm role schemas
99
- // correctly regardless of how it ended up on disk: a full monorepo git
100
- // clone (this repo, today), a standalone `npm install @apralabs/apra-fleet-
101
- // se`, or bundled into the root @apralabs/apra-fleet package's dist/auto-
102
- // sprint.mjs. `resolveSchemasDir()` below tries, in order:
97
+ // Schema resolution is layout-aware and freshness-first between the two
98
+ // bundled/local candidates (apra-fleet-ot2z.20), because apra-fleet-se must
99
+ // resolve its apra-pm role schemas correctly regardless of how it ended up
100
+ // on disk: a full monorepo git clone (this repo, today), a standalone `npm
101
+ // install @apralabs/apra-fleet-se`, or bundled into the root
102
+ // @apralabs/apra-fleet package's dist/auto-sprint.mjs. `resolveSchemasDir()`
103
+ // below tries, in order:
103
104
  //
104
105
  // 1. process.env.APRA_FLEET_SE_SCHEMAS_DIR, if set -- an explicit
105
- // override, used as-is with no further fallback. Tests use this to
106
- // point at a fixture directory; any deployment may also use it to pin
107
- // an exact schemas directory.
108
- // 2. <root>/dist/agents/schemas -- the sibling directory scripts/dist-
109
- // pm.mjs ALREADY populates at the root package's `prepublishOnly`
110
- // (cpSync of packages/apra-fleet-se/apra-pm/agents -> dist/agents, which includes its
111
- // schemas/ subdir). This is what a dist/fleet-sprint.mjs bundle
112
- // resolves once apra-fleet-3ns.2 ships it as a dist/ sibling -- no new
113
- // copy step needed, this artifact already exists today.
114
- // 3. packages/apra-fleet-se/apra-pm/agents/schemas -- the package-local apra-pm
115
- // directory. This is what a standalone install of @apralabs/apra-fleet-se
116
- // resolves, or a dev checkout.
106
+ // override, used as-is with no further fallback and no freshness
107
+ // lookup at all. Tests use this to point at a fixture directory; any
108
+ // deployment may also use it to pin an exact schemas directory.
109
+ // 2. If only one of <root>/dist/agents/schemas (the sibling directory
110
+ // scripts/dist-pm.mjs populates at the root package's
111
+ // `prepublishOnly`, cpSync of packages/apra-fleet-se/apra-pm/agents ->
112
+ // dist/agents, which includes its schemas/ subdir) or
113
+ // packages/apra-fleet-se/apra-pm/agents/schemas (the package-local
114
+ // apra-pm directory) exists, resolve that one. This is the path every
115
+ // real deployment (standalone install, dist bundle, clean CI checkout)
116
+ // takes.
117
+ // 3. If BOTH exist, resolve the NEWER one, where a directory's freshness
118
+ // is the MAXIMUM mtime over the .json files it contains, searched
119
+ // recursively (not the directory's own mtime, which only moves on
120
+ // entry create/delete/rename and would miss an in-place edit to an
121
+ // existing schema file). Ties resolve to dist, preserving the
122
+ // pre-apra-fleet-ot2z.20 behaviour.
117
123
  //
118
- // If none of 1-3 exist as a directory, `resolveSchemasDir()` returns `null`;
119
- // `loadVendorSchema` already treats a null/absent directory as the expected,
120
- // quiet graceful-degradation case (every schema falls back to its hand-
121
- // written literal in section 3) -- unchanged from before apra-fleet-bun.
124
+ // If neither candidate exists as a directory, `resolveSchemasDir()` returns
125
+ // `null`; `loadVendorSchema` already treats a null/absent directory as the
126
+ // expected, quiet graceful-degradation case (every schema falls back to its
127
+ // hand-written literal in section 3) -- unchanged from before apra-fleet-bun.
122
128
  const PACKAGE_ROOT = path.join(__dirname, '..');
123
129
  const REPO_ROOT = path.join(PACKAGE_ROOT, '..', '..');
124
130
  // Exported (not just module-local) so a drift guard test can compare the two
@@ -135,23 +141,65 @@ function isDirectory(candidate) {
135
141
  }
136
142
  }
137
143
 
144
+ /**
145
+ * Default freshness lookup for `resolveSchemasDir()`'s both-exist branch:
146
+ * the maximum mtime (ms) over every `.json` file found by a recursive walk
147
+ * of `dir`. Tolerates an unreadable or empty directory by treating it as
148
+ * freshness 0 rather than throwing -- a directory disappearing or being
149
+ * unreadable between the `exists()` check and this walk must not crash
150
+ * schema resolution.
151
+ * @param {string} dir
152
+ * @returns {number}
153
+ */
154
+ function newestJsonMtimeMs(dir) {
155
+ let newest = 0;
156
+ let entries;
157
+ try {
158
+ entries = fs.readdirSync(dir, { withFileTypes: true });
159
+ } catch {
160
+ return 0;
161
+ }
162
+ for (const entry of entries) {
163
+ const entryPath = path.join(dir, entry.name);
164
+ if (entry.isDirectory()) {
165
+ newest = Math.max(newest, newestJsonMtimeMs(entryPath));
166
+ } else if (entry.isFile() && entry.name.endsWith('.json')) {
167
+ try {
168
+ newest = Math.max(newest, fs.statSync(entryPath).mtimeMs);
169
+ } catch {
170
+ // Unreadable file between readdir and stat -- ignore it.
171
+ }
172
+ }
173
+ }
174
+ return newest;
175
+ }
176
+
138
177
  /**
139
178
  * Resolves the directory to load vendored role schemas from, per the
140
- * bundled-location-first precedence documented above. Exported (and
179
+ * freshness-first precedence documented above. Exported (and
141
180
  * side-effect-injectable via `deps`) so tests can exercise every branch in
142
181
  * isolation without needing real directories on disk for each case.
143
- * @param {{ env?: Record<string, string | undefined>, exists?: (candidate: string) => boolean }} [deps]
182
+ * @param {{ env?: Record<string, string | undefined>, exists?: (candidate: string) => boolean, newestJsonMtimeMs?: (dir: string) => number }} [deps]
144
183
  * @returns {string | null}
145
184
  */
146
185
  export function resolveSchemasDir(deps = {}) {
147
186
  const env = deps.env || process.env;
148
187
  const exists = deps.exists || isDirectory;
188
+ const freshnessOf = deps.newestJsonMtimeMs || newestJsonMtimeMs;
149
189
 
150
190
  const override = env.APRA_FLEET_SE_SCHEMAS_DIR;
151
191
  if (override) return override;
152
192
 
153
- if (exists(DIST_BUNDLED_SCHEMAS_DIR)) return DIST_BUNDLED_SCHEMAS_DIR;
154
- if (exists(PACKAGE_LOCAL_SCHEMAS_DIR)) return PACKAGE_LOCAL_SCHEMAS_DIR;
193
+ const distExists = exists(DIST_BUNDLED_SCHEMAS_DIR);
194
+ const localExists = exists(PACKAGE_LOCAL_SCHEMAS_DIR);
195
+
196
+ if (distExists && localExists) {
197
+ const localFreshness = freshnessOf(PACKAGE_LOCAL_SCHEMAS_DIR);
198
+ const distFreshness = freshnessOf(DIST_BUNDLED_SCHEMAS_DIR);
199
+ return localFreshness > distFreshness ? PACKAGE_LOCAL_SCHEMAS_DIR : DIST_BUNDLED_SCHEMAS_DIR;
200
+ }
201
+ if (distExists) return DIST_BUNDLED_SCHEMAS_DIR;
202
+ if (localExists) return PACKAGE_LOCAL_SCHEMAS_DIR;
155
203
 
156
204
  return null;
157
205
  }
@@ -265,11 +313,18 @@ export function assertVersionPin(role, schema, expectedMajor) {
265
313
  // signal for this second case.
266
314
  //
267
315
  // Roles allow-listed here are exempt because they legitimately have no
268
- // output schema file, by design (not by omission):
269
- // - "planner": per the layering proposal, the planner's "output" IS the
270
- // beads DAG it creates, not a structured verdict object -- there is no
271
- // corresponding agents/schemas/planner-output.json anywhere, ever.
272
- export const ROLES_WITHOUT_OUTPUT_SCHEMA = Object.freeze(new Set(['planner']));
316
+ // output schema file, by design (not by omission).
317
+ //
318
+ // EMPTY as of 2026-08-03. "planner" used to be listed here on the layering
319
+ // proposal's reasoning that the planner's output IS the beads DAG it creates,
320
+ // not a structured verdict object. The KB trust pipeline supersedes that: its
321
+ // Capture-roles decision accepts kb_captures from doer, reviewer, planner and
322
+ // harvester, and a role can only return a field the engine reads if it has an
323
+ // output contract to carry it. agents/schemas/planner-output.json now exists,
324
+ // so the planner is no longer schema-less and a MISSING planner-output.json is
325
+ // once again a real defect worth warning about.
326
+ // See docs/superpowers/specs/2026-08-03-kb-trust-pipeline-design.md, Phase 2.
327
+ export const ROLES_WITHOUT_OUTPUT_SCHEMA = Object.freeze(new Set([]));
273
328
 
274
329
  /**
275
330
  * Emits a loud console.warn when `resolveSchemasDir()`'s resolved directory
@@ -526,11 +581,7 @@ const FALLBACK_regressionReport = {
526
581
  summary: { type: 'string' },
527
582
  smokeEvidence: {
528
583
  type: 'object',
529
- properties: {
530
- versionStdout: { type: 'string' },
531
- canaryStatus: { type: 'string' },
532
- toyRepoHeadSha: { type: 'string' },
533
- },
584
+ additionalProperties: true,
534
585
  },
535
586
  },
536
587
  required: ['passed', 'suitePassed', 'smokePassed', 'bugsFiled', 'summary'],
@@ -614,6 +665,25 @@ export const finalVerdict = {
614
665
  required: ['id', 'reason'],
615
666
  },
616
667
  },
668
+ // apra-fleet-nx7: the Final Review may promote KB entries, exactly as a
669
+ // per-round review can. Without this field the final reviewer -- the one
670
+ // role that has read the whole diff and run the full suite, i.e. the
671
+ // strongest evidence any promoter ever holds -- had no way to return a
672
+ // promotion decision, so knowledge captured in a sprint's last round was
673
+ // stranded at INFERRED with nobody left to verify it. Same {id, reason}
674
+ // shape as reviewer-output.json's kb_promotions, executed by the same
675
+ // kbWork.apply path. Optional: promoting nothing is the common answer.
676
+ kb_promotions: {
677
+ type: 'array',
678
+ items: {
679
+ type: 'object',
680
+ properties: {
681
+ id: { type: 'string' },
682
+ reason: { type: 'string' },
683
+ },
684
+ required: ['id', 'reason'],
685
+ },
686
+ },
617
687
  },
618
688
  required: ['verdict', 'notes'],
619
689
  };
@@ -857,6 +927,50 @@ function longestBacktickRun(content) {
857
927
  return matches.reduce((max, run) => Math.max(max, run.length), 0);
858
928
  }
859
929
 
930
+ /**
931
+ * The pattern src/tools/execute-prompt.ts matches to reject a dispatch
932
+ * outright. Duplicated here as a literal rather than imported: this module
933
+ * deliberately has no dependency on the fleet server sources.
934
+ */
935
+ const SECURE_TOKEN_RE_G = /\{\{secure\.([a-zA-Z0-9_-]{1,64})\}\}/g;
936
+
937
+ const SECURE_REDACTION_NOTE = 'NOTE: secure-token braces were redacted from the block above '
938
+ + '(secure.NAME is shown without its surrounding double braces). Write the braced form when '
939
+ + 'you actually use the token in an execute_command call.';
940
+
941
+ /**
942
+ * Strips the surrounding double braces from any secure-token reference in
943
+ * untrusted content, keeping the token NAME so the text still reads.
944
+ *
945
+ * Why this must happen before the content reaches a prompt: execute_prompt
946
+ * rejects the ENTIRE dispatch -- no LLM call, an error string returned in
947
+ * place of a reply -- if the prompt matches that token pattern anywhere.
948
+ * The guard is right for caller-authored prompts, but injected content is
949
+ * not caller-authored: a knowledge-bank entry or an acceptance criterion
950
+ * that merely NAMES the token carries no secret, yet would silently fail
951
+ * every dispatch in a sprint. Redaction, not removal: the name is the part
952
+ * that makes the entry useful.
953
+ * @param {string} content
954
+ * @returns {{text: string, redacted: boolean}}
955
+ */
956
+ function redactSecureTokens(content) {
957
+ let text = content;
958
+ let redacted = false;
959
+ // Run to a fixed point rather than a single pass: replacing the inner
960
+ // token in `{{{{secure.A}}}}` leaves `{{secure.A}}`, so the surrounding
961
+ // braces close over the redacted name and rebuild exactly the pattern
962
+ // being removed. Untrusted content is attacker-influenced free-text, so
963
+ // one pass is not enough. Guaranteed to terminate -- every replacement
964
+ // removes four brace characters, so `text` strictly shrinks.
965
+ for (;;) {
966
+ const next = text.replace(SECURE_TOKEN_RE_G, (_match, name) => `secure.${name}`);
967
+ if (next === text) break;
968
+ text = next;
969
+ redacted = true;
970
+ }
971
+ return { text, redacted };
972
+ }
973
+
860
974
  /**
861
975
  * Wraps `content` in a clearly delimited fenced block labeled as untrusted
862
976
  * inter-agent output, per feedback.md finding A7. Pure function: no I/O,
@@ -882,14 +996,16 @@ export function wrapUntrustedBlock(sourceLabel, content) {
882
996
  if (typeof content !== 'string') {
883
997
  throw new TypeError('[contracts] wrapUntrustedBlock requires content to be a string');
884
998
  }
885
- const fenceLength = Math.max(MIN_FENCE_LENGTH, longestBacktickRun(content) + 1);
999
+ const { text: safeContent, redacted } = redactSecureTokens(content);
1000
+ const fenceLength = Math.max(MIN_FENCE_LENGTH, longestBacktickRun(safeContent) + 1);
886
1001
  const fence = '`'.repeat(fenceLength);
887
1002
  return [
888
1003
  UNTRUSTED_BLOCK_PREAMBLE,
889
1004
  `Source: ${sourceLabel}`,
890
1005
  `${fence}${UNTRUSTED_BLOCK_FENCE_LABEL}`,
891
- content,
1006
+ safeContent,
892
1007
  fence,
1008
+ ...(redacted ? [SECURE_REDACTION_NOTE] : []),
893
1009
  ].join('\n');
894
1010
  }
895
1011
 
@@ -912,3 +1028,31 @@ export function appendSchemaInstruction(prompt, schema) {
912
1028
  }
913
1029
  return `${prompt}\n\nOnly provide your response strictly as per this JSON schema:\n${JSON.stringify(schema, null, 2)}`;
914
1030
  }
1031
+
1032
+ // ---------------------------------------------------------------------------
1033
+ // 7. Credential-store name validation (apra-fleet-5co8.2.3)
1034
+ // ---------------------------------------------------------------------------
1035
+ //
1036
+ // Pattern for valid credential-store entry names, shared with src/tools/ (see
1037
+ // credential-store-set.ts). Used by the per-sprint Azure DevOps PAT secret
1038
+ // name override validation (runner.js's validateArgs).
1039
+
1040
+ const CREDENTIAL_STORE_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
1041
+
1042
+ /**
1043
+ * Validates a credential-store entry name against the pattern used by
1044
+ * credential_store_set (alphanumeric, underscores, hyphens, 1-64 chars).
1045
+ * Throws with a clear message on rejection.
1046
+ * @param {unknown} name
1047
+ * @param {string} label - human-readable arg name, used in the error message
1048
+ * @returns {string}
1049
+ */
1050
+ export function validateCredentialStoreName(name, label) {
1051
+ if (typeof name !== 'string' || name.length === 0 || !CREDENTIAL_STORE_NAME_PATTERN.test(name)) {
1052
+ throw new Error(
1053
+ `[Arg Contract] Invalid ${label} "${name}": must match ${CREDENTIAL_STORE_NAME_PATTERN} ` +
1054
+ `(alphanumeric, underscores, hyphens, 1-64 chars).`
1055
+ );
1056
+ }
1057
+ return name;
1058
+ }
@@ -79,7 +79,7 @@ Watch progress there rather than tailing raw stdout.
79
79
 
80
80
  | Flag | Short | Required | Default | Description |
81
81
  |---|---|---|---|---|
82
- | `--issue <ids>` | `-i` | yes | -- | Target issue ID(s), comma separated (e.g. `epic-1,epic-2`). Scope resolves via `bd list --parent <id>` -- see the epics section below. |
82
+ | `--issue <ids>` | `-i` | yes | -- | Target issue ID(s), comma separated (e.g. `epic-1,epic-2`). Scope resolves to each id's full descendant subtree -- see the epics section below. |
83
83
  | `--members <ids>` | `-m` | yes | -- | Member IDs/names to use, comma separated. Members act as repo targets for parallelism. |
84
84
  | `--branch <name>` | `-b` | yes | -- | Sprint branch to develop on. Created from `--base` if it does not exist; reused as-is if it does. |
85
85
  | `--base <name>` | `-B` | yes | -- | Base branch the sprint branch is created from, and the branch the eventual PR targets. |
@@ -90,13 +90,24 @@ Watch progress there rather than tailing raw stdout.
90
90
  | `--role-map <json\|@file>` | | no | -- | JSON object mapping role -> member[], e.g. `'{"doer":["m1","m2"]}'`. Inline JSON or `@path/to/file.json`. |
91
91
  | `--viewer-port <port>` | | no | `8080` | Port for the local dashboard viewer. |
92
92
  | `--budget <usd>` | | no | unlimited | USD ceiling for this run's total estimated spend. |
93
- | `--dispatch-timeout-s <s>` | | no | `3600` | Per-dispatch time budget in seconds, applied as both the inactivity timeout and the hard ceiling on every agent dispatch (integ-test dispatch ceiling is 2x). Minimum 60. Lower it for small sprints so a hung dispatch costs minutes, not an hour. |
93
+ | `--dispatch-timeout-s <s>` | | no | `9000` | Per-dispatch time budget in seconds, applied as both the inactivity timeout and the hard ceiling on every agent dispatch (integ-test dispatch ceiling is 2x, regression-test ceiling is 3x). Minimum 60. Lower it for small sprints so a hung dispatch costs minutes, not 2.5 hours. |
94
94
  | `--sync` | | no | off | Synced topology mode (orchestrator-bracketed git sync): members may sit on differing HEADs but must share the same origin URL and pass a `bd dolt pull` probe. Omitted uses shared-workspace mode (all members on the same HEAD). |
95
95
  | `--help` | `-h` | | | Show the engine's help. |
96
96
 
97
97
  Unrecognized flags fail loudly rather than being silently ignored, so a typo
98
98
  like `--max-cycle` aborts instead of quietly applying the default.
99
99
 
100
+ **A shared/`unreservable` orchestrator member goes in `--role-map` ONLY, never
101
+ in `--members`.** `--members` (and `--role-map` values for git-having roles
102
+ like doer/reviewer/harvester) still get git-identity/topology-checked and, on
103
+ resume, git-resynced. A member registered `unreservable: true` (e.g. a
104
+ beads-only orchestrator shared across concurrent sprints) is exempted from
105
+ those checks only when it appears exclusively via `roleMap.orchestrator` --
106
+ listing it in `--members` too is redundant and not required, and defeats the
107
+ exemption for anything outside the topology precondition (e.g. a paused/
108
+ resumed sprint's resync step still runs real git commands against every
109
+ `--members` entry, unreservable or not).
110
+
100
111
  ## Preconditions worth checking first
101
112
 
102
113
  - The target issue (e.g. `apra-fleet-7pm`) must exist and be open:
@@ -143,15 +154,19 @@ bead that used `blocks` instead had `dependency_count: 5` and, once
143
154
  children were also parented under it, deadlocked completely.
144
155
 
145
156
  This also matters for launching a sprint: `fleet-sprint`'s `--issue <id>`
146
- flag resolves the sprint's scope via `bd list --parent <id>` internally --
147
- it only ever understands the `parent-child` hierarchy. A `blocked-by`-only
148
- manifest bead is invisible to fleet-sprint's scope filter no matter what you
149
- pass to `--issue`; only true children are picked up.
157
+ flag resolves the sprint's scope by walking the `parent-child` tree down from
158
+ `<id>` -- `bdListScoped()` fetches the whole project's beads once and does
159
+ the descendant walk in memory, so every descendant at any depth is in scope
160
+ (not just direct children), but nothing outside the parent-child hierarchy
161
+ ever is. A `blocked-by`-only manifest bead is invisible to fleet-sprint's
162
+ scope filter no matter what you pass to `--issue`; only true children are
163
+ picked up. See `packages/apra-fleet-se/docs/fleet-sprint-cli-contract.md` for
164
+ the full algorithm and worked examples.
150
165
 
151
166
  ## Recovering a wedged member reservation (launched via the supervisor)
152
167
 
153
- If a sprint was launched through the supervisor (`fleet-se serve`, `POST
154
- /api/sprints`) and its child process crashes or is killed, the supervisor's
168
+ If a sprint was launched through the supervisor (`bin/serve.mjs`, installed
169
+ as `fleet-se-serve`; `POST /api/sprints`) and its child process crashes or is killed, the supervisor's
155
170
  reservation ledger does **not** release that sprint's claim on its own during
156
171
  normal runtime -- only a supervisor restart, or an explicit operator call,
157
172
  clears it. Symptom: relaunching against the same member(s) is rejected with
@@ -0,0 +1,258 @@
1
+ # Dolt manual recovery runbook (verified 2026-08-12, all steps live-tested on fleet-win-dev1)
2
+
3
+ This is the ground-truth procedure for standing up an ephemeral `dolt sql-server`
4
+ against a wedged embedded Dolt clone, querying/repairing it, and tearing it back
5
+ down -- verified end to end against a real clone on a real member, not written
6
+ from docs.
7
+
8
+ STATUS: this procedure is now AUTOMATED end to end by `settleDoltConflicts()`
9
+ (`packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs`), which is the
10
+ executable form of this document and runs at both sync divergence terminals --
11
+ fleet members self-heal without a human or an LLM. The old Path A / Path B /
12
+ Tier 2 ladder and its LLM runbook (`dolt-tier2-runbook.md`) were retired and
13
+ deleted; see `dolt-sync-redesign.md`.
14
+
15
+ This document remains the SPECIFICATION that code encodes, and the human
16
+ copy-paste fallback for driving a clone by hand. Every step here was
17
+ independently rediscovered by trial and error at least once already (see
18
+ apra-fleet-ga61, apra-fleet-5mqg) -- which is exactly why it is written down
19
+ and encoded once.
20
+
21
+ ## 0. Precondition: find the REAL data directory. Never hardcode it.
22
+
23
+ ```
24
+ bd dolt status
25
+ ```
26
+
27
+ Read the `Data:` line from the output (also mirrored in `.beads/metadata.json`'s
28
+ `dolt_mode` field). This is bd's own live, authoritative answer for THIS clone,
29
+ right now. Do not assume `.beads/embeddeddolt` -- that happens to be bd's
30
+ convention today, but a script that hardcodes it and finds a second/different
31
+ directory should treat that as orphaned residue from a prior failed recovery
32
+ (see apra-fleet-5mqg) and refuse to proceed blind, not silently pick one.
33
+
34
+ If `bd dolt status` reports `embedded (in-process, no server)`, there is no
35
+ live server to route through -- an ephemeral one must be started (step 2). If
36
+ it already reports a live server (host:port), skip straight to step 3 and
37
+ target that existing server/port instead of starting a second one.
38
+
39
+ ## 1. Ensure the PINNED `dolt` binary is present (never a package manager)
40
+
41
+ The embedded `bd` binary does NOT ship enough of the Dolt CLI to drive a
42
+ merge-conflict resolution over SQL -- that requires the real `dolt` binary and
43
+ a real `dolt sql-server` process, temporarily, against the SAME data directory.
44
+
45
+ **Never install it with an OS package manager** (`winget`, `apt`, `brew`).
46
+ Two independent reasons, both load-bearing (see `dolt-sync-redesign.md`
47
+ Part 5, Precondition V2):
48
+
49
+ - A package manager is a second, unpinned version channel. It will happily
50
+ deliver a build older than this repo's own version pin, and the landmines
51
+ this procedure works around are version-specific.
52
+ - A freshly package-manager-installed binary is invisible to processes that
53
+ started before the install -- which is every SSH-dispatched session, so the
54
+ install appears to succeed and the binary still cannot be found.
55
+
56
+ The fleet's ONE pinned channel is the same GitHub release asset
57
+ `src/cli/dolt-install.ts` uses (`DOLT_VERSION`, currently `v2.2.0`), landed at
58
+ the fleet-managed path -- always referenced as an absolute path, never system
59
+ PATH, and needing no admin rights:
60
+
61
+ - Windows: `%USERPROFILE%\.apra-fleet\bin\dolt.exe`
62
+ - POSIX: `$HOME/.apra-fleet/bin/dolt`
63
+
64
+ Probe it first -- existence is not enough, it must actually RUN and report the
65
+ pinned version:
66
+
67
+ ```bash
68
+ "$HOME/.apra-fleet/bin/dolt" version # POSIX
69
+ ```
70
+ ```powershell
71
+ & "$env:USERPROFILE\.apra-fleet\bin\dolt.exe" version # Windows
72
+ ```
73
+
74
+ If it is missing, broken, or the wrong version, install it from the pinned
75
+ asset. `settleDoltConflicts()` does exactly this itself (`ensurePinnedDolt()`
76
+ in `dolt-settle.mjs`, design doc Part 5.3) -- members never run
77
+ `apra-fleet install`, so nothing else on a member ever puts a pinned dolt
78
+ there. By hand, the same sequence is:
79
+
80
+ **Windows:**
81
+ ```powershell
82
+ New-Item -ItemType Directory -Force "$env:USERPROFILE\.apra-fleet\bin" | Out-Null
83
+ Invoke-WebRequest -Uri https://github.com/dolthub/dolt/releases/download/v2.2.0/dolt-windows-amd64.zip -OutFile "$env:TEMP\dolt-settle.zip" -TimeoutSec 300
84
+ Expand-Archive -Force "$env:TEMP\dolt-settle.zip" "$env:TEMP\dolt-settle"
85
+ Get-ChildItem -Recurse -Filter dolt.exe "$env:TEMP\dolt-settle" | Select-Object -First 1 |
86
+ Copy-Item -Force -Destination "$env:USERPROFILE\.apra-fleet\bin\dolt.exe"
87
+ ```
88
+
89
+ **Linux / macOS** (swap the asset for `dolt-linux-amd64.tar.gz`,
90
+ `dolt-darwin-amd64.tar.gz` or `dolt-darwin-arm64.tar.gz` to match the member):
91
+ ```bash
92
+ mkdir -p "$HOME/.apra-fleet/bin"
93
+ curl -fL --max-time 300 https://github.com/dolthub/dolt/releases/download/v2.2.0/dolt-linux-amd64.tar.gz -o /tmp/dolt-settle.tgz
94
+ mkdir -p /tmp/dolt-settle && tar -xzf /tmp/dolt-settle.tgz -C /tmp/dolt-settle
95
+ install -m 0755 "$(find /tmp/dolt-settle -type f -name dolt | head -1)" "$HOME/.apra-fleet/bin/dolt"
96
+ ```
97
+
98
+ Then re-probe: the freshly installed binary must report the pinned version
99
+ before you continue. On Windows a replace can fail because a stray `dolt`
100
+ process holds the file -- kill any process whose executable path IS this
101
+ fleet-managed path (nothing else ever launches a binary there) and retry once.
102
+
103
+ Every `dolt ...` invocation below means that absolute pinned path, not a bare
104
+ `dolt` from PATH.
105
+
106
+ ## 2. Start the ephemeral sql-server -- GENUINELY DETACHED
107
+
108
+ This is the step with real cross-platform divergence, and where most of the
109
+ danger lives (an interrupted/never-torn-down server is exactly what
110
+ apra-fleet-5mqg is about).
111
+
112
+ **Windows -- do NOT use `Start-Process` or `schtasks`:**
113
+
114
+ - `Start-Process -WindowStyle Hidden` looked detached but is NOT: it is still a
115
+ child of the invoking SSH/job-object session. Verified live: the sql-server
116
+ process (and its listening port) died the instant the launching
117
+ `execute_command` call's session ended, even with `-RedirectStandardOutput`/
118
+ `-RedirectStandardError` set and `-PassThru`.
119
+ - `schtasks`/`Register-ScheduledTask` + `Start-ScheduledTask` also failed:
120
+ verified live, `Get-ScheduledTaskInfo` reported `LastTaskResult 267011`
121
+ (`SCHED_S_TASK_QUEUED`) -- the task was queued but never actually ran,
122
+ because this is a non-interactive SSH session with no interactive logon
123
+ (the exact apra-fleet-i8qj failure mode, reproduced here independently).
124
+ - **What actually works, verified live:** spawn via WMI, which creates the
125
+ process under the WMI provider host's own session (session 0), fully
126
+ independent of the SSH session's job object:
127
+
128
+ ```powershell
129
+ $result = Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{
130
+ CommandLine = '"C:\Users\<you>\.apra-fleet\bin\dolt.exe" sql-server --host 127.0.0.1 --port 13399 --data-dir .beads/embeddeddolt'
131
+ CurrentDirectory = 'C:\akhil\git\apra-fleet'
132
+ }
133
+ $result.ProcessId # <-- record this PID for teardown (step 5)
134
+ ```
135
+ Verify it is actually up before proceeding: `Get-Process -Id <pid>` should
136
+ show it running under `SI` (session ID) `0`, and
137
+ `Test-NetConnection -ComputerName 127.0.0.1 -Port 13399` should report
138
+ `TcpTestSucceeded: True`.
139
+
140
+ **Linux / macOS (POSIX):** the SSH-session-job-object problem does not exist on
141
+ POSIX in the same way; the existing `nohup ... & disown` pattern (as used by
142
+ `task-wrapper.ts`'s bash wrapper for `long_running` commands elsewhere in this
143
+ codebase) is sufficient:
144
+
145
+ ```bash
146
+ nohup dolt sql-server --host 127.0.0.1 --port 13399 --data-dir .beads/embeddeddolt \
147
+ > /tmp/dolt-recovery.log 2>&1 &
148
+ echo "PID:$!"
149
+ disown
150
+ ```
151
+
152
+ ## 3. Connect and query -- the exact working flag set (verified live)
153
+
154
+ ```
155
+ dolt --no-tls --host=127.0.0.1 --port=13399 sql -q "USE beads; SELECT ...;"
156
+ ```
157
+
158
+ Two specific, non-obvious landmines, both reproduced live on this run:
159
+
160
+ 1. **`--no-tls` must come BEFORE `--host`/`--port`.** With `--host`/`--port`
161
+ given first and `--no-tls` after, the client still requested TLS and failed
162
+ with `TLS requested but server does not support TLS` -- Dolt's global-flag
163
+ parser is order-sensitive here. Always lead with `--no-tls`.
164
+ 2. **Do NOT pass `--user=root` or `--password` at all**, even though root with
165
+ an empty password is the documented default. Explicitly passing `--user=root`
166
+ switches the client into a credential-resolution path that issues an
167
+ interactive `Enter password:` prompt and then fails non-interactively with
168
+ `Failed to parse credentials: The handle is invalid` -- this is the EXACT
169
+ apra-fleet-ga61 symptom, reproduced live and now root-caused precisely: it
170
+ is triggered by explicitly specifying `--user`/`--password`, not by network
171
+ mode itself. Omitting both flags entirely lets the client silently
172
+ authenticate as root with the empty-password default with zero prompt.
173
+ (Separately, on Windows/PowerShell specifically: an empty-string argument
174
+ like `--password ''` can be silently dropped by PowerShell's native-argument
175
+ passing, shifting the NEXT flag into becoming its value -- another reason to
176
+ just omit the flag rather than try to pass an explicit empty value.)
177
+
178
+ Use `USE beads;` as the first statement of every query -- the target database
179
+ name is not implied by `--data-dir` alone once connected over SQL.
180
+
181
+ The actual recovery SQL (identical across all three OSes -- this part has no
182
+ platform variance):
183
+
184
+ ```sql
185
+ SET @@dolt_allow_commit_conflicts = 1;
186
+ CALL DOLT_MERGE('origin/main');
187
+ SELECT `table` FROM dolt_conflicts; -- enumerate EVERY conflicted table
188
+ CALL DOLT_CONFLICTS_RESOLVE('--theirs', 'issues'); -- table name is REQUIRED
189
+ CALL DOLT_COMMIT('-m', 'manual recovery: resolve conflict');
190
+ SELECT COUNT(*) FROM dolt_conflicts; -- MUST be 0 before you republish
191
+ ```
192
+ A bare `--theirs` is only correct when discarding our side's version of those
193
+ rows is genuinely acceptable. `settleDoltConflicts()` applies the full rulebook
194
+ instead -- per-field last-writer-wins by `updated_at` for `issues` and
195
+ `dependencies`, a real set-union INSERT for `labels`, generic
196
+ LWW-or-theirs for anything else (design doc Part 3.2 step 4). Resolving by hand
197
+ with real content on both sides, follow the same rules rather than clobbering
198
+ one side.
199
+
200
+ Then, outside the SQL session -- and ONLY AFTER the teardown in step 5 --
201
+ `bd dolt pull` (verify), `bd dolt push` (republish). The order matters; see
202
+ step 5.
203
+
204
+ ## 4. Verify before teardown
205
+
206
+ ```
207
+ dolt --no-tls --host=127.0.0.1 --port=13399 sql -q "USE beads; SELECT * FROM dolt_status;"
208
+ ```
209
+ Confirm no residual uncommitted/conflicted state before tearing the server down.
210
+
211
+ ## 5. Teardown -- ALWAYS, every path, even on failure, and BEFORE republishing
212
+
213
+ Ordering, corrected (design doc Part 7.2): tear the ephemeral server down
214
+ FIRST, then run `bd dolt pull` / `bd dolt push`. Embedded-mode `bd` must open
215
+ the same data dir the server still holds under Dolt's per-directory exclusive
216
+ lock, so republishing while the server is still up fails or falls back
217
+ read-only.
218
+
219
+ **Windows:**
220
+ ```powershell
221
+ Stop-Process -Id <pid> -Force -ErrorAction SilentlyContinue
222
+ ```
223
+ **POSIX:**
224
+ ```bash
225
+ kill <pid>
226
+ ```
227
+
228
+ Then, on every OS:
229
+ - Verify the port is actually closed (`Test-NetConnection` / `nc -z` /
230
+ `lsof -i:<port>`).
231
+ - Verify `bd dolt status` reports `embedded (in-process, no server)` again and
232
+ `.beads/metadata.json`'s `dolt_mode` is `"embedded"` -- if this recovery
233
+ procedure ever explicitly flips `dolt_mode` to `"server"` as part of routing
234
+ bd itself through the ephemeral server (this manual run did NOT do that --
235
+ it talked to the raw `dolt` CLI directly, bypassing bd entirely -- and
236
+ `settleDoltConflicts()` deliberately does the same, which is what makes its
237
+ teardown unconditionally safe), flipping it back is
238
+ MANDATORY and must happen in a `finally`/guaranteed-cleanup block, not as
239
+ the last step of a list that can be abandoned mid-way (exactly what went
240
+ wrong in the incident apra-fleet-5mqg documents).
241
+ - Remove any temp log files created for the ephemeral server's stdout/stderr.
242
+
243
+ ## Why this matters for the code fix (apra-fleet-5mqg, apra-fleet-ga61)
244
+
245
+ Every numbered landmine above (`--no-tls` ordering, omitting `--user`/
246
+ `--password`, WMI vs `Start-Process`/`schtasks` for real detachment on Windows,
247
+ never hardcoding the data directory) was independently rediscovered by trial
248
+ and error here, and was ALSO independently rediscovered by trial and error by
249
+ the Tier-2 LLM dispatch whose transcript motivated apra-fleet-5mqg. That was
250
+ strong evidence this entire procedure is mechanical and fully scriptable --
251
+ there was no judgment call anywhere in this runbook, only flag/ordering
252
+ trivia a fixed script encodes once and never has to rediscover again. That
253
+ script now exists: `fleet-sprint/dolt-settle.mjs`.
254
+
255
+ CAVEAT on the evidence: every landmine above was verified live against a
256
+ winget-installed dolt **1.86.3**, not against the pinned **v2.2.0** the fleet
257
+ now installs. Re-verifying them on the pinned binary, per OS, is Precondition
258
+ V0 of the design doc's Part 4 verification pass.