@apralabs/apra-fleet 0.3.5 → 0.4.0

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 (571) hide show
  1. package/README.md +245 -257
  2. package/dist/agents/backlog-groomer.md +287 -0
  3. package/dist/agents/deployer.md +52 -11
  4. package/dist/agents/doer.md +32 -7
  5. package/dist/agents/integ-test-runner.md +151 -61
  6. package/dist/agents/plan-reviewer.md +74 -17
  7. package/dist/agents/planner.md +94 -14
  8. package/dist/agents/regression-test-runner.md +216 -0
  9. package/dist/agents/reviewer.md +21 -6
  10. package/dist/agents/schemas/backlog-groomer-input.json +35 -0
  11. package/dist/agents/schemas/backlog-groomer-output.json +164 -0
  12. package/dist/agents/schemas/integ-test-runner-output.json +34 -0
  13. package/dist/agents/schemas/regression-test-runner-input.json +15 -0
  14. package/dist/agents/schemas/regression-test-runner-output.json +50 -0
  15. package/dist/agents/schemas/reviewer-output.json +4 -0
  16. package/dist/cli/agent-transform.d.ts +1 -0
  17. package/dist/cli/agent-transform.d.ts.map +1 -1
  18. package/dist/cli/agent-transform.js +77 -0
  19. package/dist/cli/agent-transform.js.map +1 -1
  20. package/dist/cli/auth.d.ts +3 -0
  21. package/dist/cli/auth.d.ts.map +1 -1
  22. package/dist/cli/auth.js +181 -5
  23. package/dist/cli/auth.js.map +1 -1
  24. package/dist/cli/config.d.ts +5 -1
  25. package/dist/cli/config.d.ts.map +1 -1
  26. package/dist/cli/config.js +7 -1
  27. package/dist/cli/config.js.map +1 -1
  28. package/dist/cli/dolt-install.d.ts +91 -0
  29. package/dist/cli/dolt-install.d.ts.map +1 -0
  30. package/dist/cli/dolt-install.js +334 -0
  31. package/dist/cli/dolt-install.js.map +1 -0
  32. package/dist/cli/install-guard.d.ts +29 -0
  33. package/dist/cli/install-guard.d.ts.map +1 -0
  34. package/dist/cli/install-guard.js +153 -0
  35. package/dist/cli/install-guard.js.map +1 -0
  36. package/dist/cli/install.d.ts +44 -3
  37. package/dist/cli/install.d.ts.map +1 -1
  38. package/dist/cli/install.js +604 -108
  39. package/dist/cli/install.js.map +1 -1
  40. package/dist/cli/join.d.ts +12 -0
  41. package/dist/cli/join.d.ts.map +1 -0
  42. package/dist/cli/join.js +87 -0
  43. package/dist/cli/join.js.map +1 -0
  44. package/dist/cli/register-member.d.ts +2 -0
  45. package/dist/cli/register-member.d.ts.map +1 -0
  46. package/dist/cli/register-member.js +193 -0
  47. package/dist/cli/register-member.js.map +1 -0
  48. package/dist/cli/restart.d.ts +2 -0
  49. package/dist/cli/restart.d.ts.map +1 -0
  50. package/dist/cli/restart.js +7 -0
  51. package/dist/cli/restart.js.map +1 -0
  52. package/dist/cli/secret.js +8 -2
  53. package/dist/cli/secret.js.map +1 -1
  54. package/dist/cli/spoke.d.ts +35 -0
  55. package/dist/cli/spoke.d.ts.map +1 -0
  56. package/dist/cli/spoke.js +212 -0
  57. package/dist/cli/spoke.js.map +1 -0
  58. package/dist/cli/start.d.ts +2 -0
  59. package/dist/cli/start.d.ts.map +1 -0
  60. package/dist/cli/start.js +92 -0
  61. package/dist/cli/start.js.map +1 -0
  62. package/dist/cli/status.d.ts +2 -0
  63. package/dist/cli/status.d.ts.map +1 -0
  64. package/dist/cli/status.js +83 -0
  65. package/dist/cli/status.js.map +1 -0
  66. package/dist/cli/stop.d.ts +2 -0
  67. package/dist/cli/stop.d.ts.map +1 -0
  68. package/dist/cli/stop.js +51 -0
  69. package/dist/cli/stop.js.map +1 -0
  70. package/dist/cli/uninstall.d.ts.map +1 -1
  71. package/dist/cli/uninstall.js +109 -9
  72. package/dist/cli/uninstall.js.map +1 -1
  73. package/dist/cli/update.d.ts.map +1 -1
  74. package/dist/cli/update.js +10 -1
  75. package/dist/cli/update.js.map +1 -1
  76. package/dist/cli/workflow-assets.d.ts +37 -0
  77. package/dist/cli/workflow-assets.d.ts.map +1 -0
  78. package/dist/cli/workflow-assets.js +144 -0
  79. package/dist/cli/workflow-assets.js.map +1 -0
  80. package/dist/cli/workflow.d.ts +75 -0
  81. package/dist/cli/workflow.d.ts.map +1 -0
  82. package/dist/cli/workflow.js +397 -0
  83. package/dist/cli/workflow.js.map +1 -0
  84. package/dist/hub-service/activity.d.ts +30 -0
  85. package/dist/hub-service/activity.d.ts.map +1 -0
  86. package/dist/hub-service/activity.js +20 -0
  87. package/dist/hub-service/activity.js.map +1 -0
  88. package/dist/hub-service/audit-log.d.ts +19 -0
  89. package/dist/hub-service/audit-log.d.ts.map +1 -0
  90. package/dist/hub-service/audit-log.js +13 -0
  91. package/dist/hub-service/audit-log.js.map +1 -0
  92. package/dist/hub-service/db/pool.d.ts +19 -0
  93. package/dist/hub-service/db/pool.d.ts.map +1 -0
  94. package/dist/hub-service/db/pool.js +53 -0
  95. package/dist/hub-service/db/pool.js.map +1 -0
  96. package/dist/hub-service/enrollment.d.ts +29 -0
  97. package/dist/hub-service/enrollment.d.ts.map +1 -0
  98. package/dist/hub-service/enrollment.js +48 -0
  99. package/dist/hub-service/enrollment.js.map +1 -0
  100. package/dist/hub-service/envelope-routes.d.ts +46 -0
  101. package/dist/hub-service/envelope-routes.d.ts.map +1 -0
  102. package/dist/hub-service/envelope-routes.js +94 -0
  103. package/dist/hub-service/envelope-routes.js.map +1 -0
  104. package/dist/hub-service/handlers/installers.d.ts +14 -0
  105. package/dist/hub-service/handlers/installers.d.ts.map +1 -0
  106. package/dist/hub-service/handlers/installers.js +8 -0
  107. package/dist/hub-service/handlers/installers.js.map +1 -0
  108. package/dist/hub-service/http-server.d.ts +31 -0
  109. package/dist/hub-service/http-server.d.ts.map +1 -0
  110. package/dist/hub-service/http-server.js +711 -0
  111. package/dist/hub-service/http-server.js.map +1 -0
  112. package/dist/hub-service/hub-jwt.d.ts +30 -0
  113. package/dist/hub-service/hub-jwt.d.ts.map +1 -0
  114. package/dist/hub-service/hub-jwt.js +105 -0
  115. package/dist/hub-service/hub-jwt.js.map +1 -0
  116. package/dist/hub-service/jwt-revocation.d.ts +20 -0
  117. package/dist/hub-service/jwt-revocation.d.ts.map +1 -0
  118. package/dist/hub-service/jwt-revocation.js +18 -0
  119. package/dist/hub-service/jwt-revocation.js.map +1 -0
  120. package/dist/hub-service/machines.d.ts +16 -0
  121. package/dist/hub-service/machines.d.ts.map +1 -0
  122. package/dist/hub-service/machines.js +14 -0
  123. package/dist/hub-service/machines.js.map +1 -0
  124. package/dist/hub-service/main.d.ts +3 -0
  125. package/dist/hub-service/main.d.ts.map +1 -0
  126. package/dist/hub-service/main.js +64 -0
  127. package/dist/hub-service/main.js.map +1 -0
  128. package/dist/hub-service/member-tokens.d.ts +11 -0
  129. package/dist/hub-service/member-tokens.d.ts.map +1 -0
  130. package/dist/hub-service/member-tokens.js +49 -0
  131. package/dist/hub-service/member-tokens.js.map +1 -0
  132. package/dist/hub-service/member-view.d.ts +20 -0
  133. package/dist/hub-service/member-view.d.ts.map +1 -0
  134. package/dist/hub-service/member-view.js +76 -0
  135. package/dist/hub-service/member-view.js.map +1 -0
  136. package/dist/hub-service/members.d.ts +44 -0
  137. package/dist/hub-service/members.d.ts.map +1 -0
  138. package/dist/hub-service/members.js +25 -0
  139. package/dist/hub-service/members.js.map +1 -0
  140. package/dist/hub-service/presence.d.ts +40 -0
  141. package/dist/hub-service/presence.d.ts.map +1 -0
  142. package/dist/hub-service/presence.js +44 -0
  143. package/dist/hub-service/presence.js.map +1 -0
  144. package/dist/hub-service/project-view.d.ts +12 -0
  145. package/dist/hub-service/project-view.d.ts.map +1 -0
  146. package/dist/hub-service/project-view.js +34 -0
  147. package/dist/hub-service/project-view.js.map +1 -0
  148. package/dist/hub-service/projects.d.ts +48 -0
  149. package/dist/hub-service/projects.d.ts.map +1 -0
  150. package/dist/hub-service/projects.js +80 -0
  151. package/dist/hub-service/projects.js.map +1 -0
  152. package/dist/hub-service/relay-queue.d.ts +115 -0
  153. package/dist/hub-service/relay-queue.d.ts.map +1 -0
  154. package/dist/hub-service/relay-queue.js +148 -0
  155. package/dist/hub-service/relay-queue.js.map +1 -0
  156. package/dist/hub-service/session-jwt.d.ts +10 -0
  157. package/dist/hub-service/session-jwt.d.ts.map +1 -0
  158. package/dist/hub-service/session-jwt.js +69 -0
  159. package/dist/hub-service/session-jwt.js.map +1 -0
  160. package/dist/hub-service/usage.d.ts +40 -0
  161. package/dist/hub-service/usage.d.ts.map +1 -0
  162. package/dist/hub-service/usage.js +25 -0
  163. package/dist/hub-service/usage.js.map +1 -0
  164. package/dist/hub-service/users.d.ts +56 -0
  165. package/dist/hub-service/users.d.ts.map +1 -0
  166. package/dist/hub-service/users.js +72 -0
  167. package/dist/hub-service/users.js.map +1 -0
  168. package/dist/hub-service/workspaces.d.ts +20 -0
  169. package/dist/hub-service/workspaces.d.ts.map +1 -0
  170. package/dist/hub-service/workspaces.js +10 -0
  171. package/dist/hub-service/workspaces.js.map +1 -0
  172. package/dist/index.js +179 -132
  173. package/dist/index.js.map +1 -1
  174. package/dist/os/linux.d.ts +13 -0
  175. package/dist/os/linux.d.ts.map +1 -1
  176. package/dist/os/linux.js +62 -3
  177. package/dist/os/linux.js.map +1 -1
  178. package/dist/os/os-commands.d.ts +10 -0
  179. package/dist/os/os-commands.d.ts.map +1 -1
  180. package/dist/os/windows.d.ts +1 -0
  181. package/dist/os/windows.d.ts.map +1 -1
  182. package/dist/os/windows.js +21 -1
  183. package/dist/os/windows.js.map +1 -1
  184. package/dist/paths.d.ts +23 -0
  185. package/dist/paths.d.ts.map +1 -1
  186. package/dist/paths.js +29 -0
  187. package/dist/paths.js.map +1 -1
  188. package/dist/providers/agy.d.ts +9 -2
  189. package/dist/providers/agy.d.ts.map +1 -1
  190. package/dist/providers/agy.js +127 -14
  191. package/dist/providers/agy.js.map +1 -1
  192. package/dist/providers/claude.d.ts +6 -2
  193. package/dist/providers/claude.d.ts.map +1 -1
  194. package/dist/providers/claude.js +248 -9
  195. package/dist/providers/claude.js.map +1 -1
  196. package/dist/providers/codex.d.ts +3 -2
  197. package/dist/providers/codex.d.ts.map +1 -1
  198. package/dist/providers/codex.js +7 -0
  199. package/dist/providers/codex.js.map +1 -1
  200. package/dist/providers/copilot.d.ts +3 -2
  201. package/dist/providers/copilot.d.ts.map +1 -1
  202. package/dist/providers/copilot.js +8 -1
  203. package/dist/providers/copilot.js.map +1 -1
  204. package/dist/providers/gemini.d.ts +3 -2
  205. package/dist/providers/gemini.d.ts.map +1 -1
  206. package/dist/providers/gemini.js +11 -1
  207. package/dist/providers/gemini.js.map +1 -1
  208. package/dist/providers/index.d.ts +1 -0
  209. package/dist/providers/index.d.ts.map +1 -1
  210. package/dist/providers/index.js +3 -0
  211. package/dist/providers/index.js.map +1 -1
  212. package/dist/providers/none.d.ts +51 -0
  213. package/dist/providers/none.d.ts.map +1 -0
  214. package/dist/providers/none.js +103 -0
  215. package/dist/providers/none.js.map +1 -0
  216. package/dist/providers/opencode.d.ts +4 -2
  217. package/dist/providers/opencode.d.ts.map +1 -1
  218. package/dist/providers/opencode.js +49 -0
  219. package/dist/providers/opencode.js.map +1 -1
  220. package/dist/providers/provider.d.ts +79 -1
  221. package/dist/providers/provider.d.ts.map +1 -1
  222. package/dist/providers/provider.js +10 -0
  223. package/dist/providers/provider.js.map +1 -1
  224. package/dist/services/agent-provisioner.d.ts +3 -3
  225. package/dist/services/agent-provisioner.d.ts.map +1 -1
  226. package/dist/services/agent-provisioner.js +12 -5
  227. package/dist/services/agent-provisioner.js.map +1 -1
  228. package/dist/services/auth-socket.d.ts.map +1 -1
  229. package/dist/services/auth-socket.js +2 -0
  230. package/dist/services/auth-socket.js.map +1 -1
  231. package/dist/services/budget-awareness.d.ts +130 -0
  232. package/dist/services/budget-awareness.d.ts.map +1 -0
  233. package/dist/services/budget-awareness.js +129 -0
  234. package/dist/services/budget-awareness.js.map +1 -0
  235. package/dist/services/cloud-sync.d.ts +35 -0
  236. package/dist/services/cloud-sync.d.ts.map +1 -0
  237. package/dist/services/cloud-sync.js +90 -0
  238. package/dist/services/cloud-sync.js.map +1 -0
  239. package/dist/services/context-admission.d.ts +82 -0
  240. package/dist/services/context-admission.d.ts.map +1 -0
  241. package/dist/services/context-admission.js +136 -0
  242. package/dist/services/context-admission.js.map +1 -0
  243. package/dist/services/event-bus.d.ts +27 -0
  244. package/dist/services/event-bus.d.ts.map +1 -0
  245. package/dist/services/event-bus.js +20 -0
  246. package/dist/services/event-bus.js.map +1 -0
  247. package/dist/services/file-chunker.d.ts +38 -0
  248. package/dist/services/file-chunker.d.ts.map +1 -0
  249. package/dist/services/file-chunker.js +63 -0
  250. package/dist/services/file-chunker.js.map +1 -0
  251. package/dist/services/file-transfer-relay.d.ts +55 -0
  252. package/dist/services/file-transfer-relay.d.ts.map +1 -0
  253. package/dist/services/file-transfer-relay.js +115 -0
  254. package/dist/services/file-transfer-relay.js.map +1 -0
  255. package/dist/services/github-app.d.ts.map +1 -1
  256. package/dist/services/github-app.js +1 -0
  257. package/dist/services/github-app.js.map +1 -1
  258. package/dist/services/http-transport.d.ts +25 -0
  259. package/dist/services/http-transport.d.ts.map +1 -0
  260. package/dist/services/http-transport.js +371 -0
  261. package/dist/services/http-transport.js.map +1 -0
  262. package/dist/services/hub-client.d.ts +69 -0
  263. package/dist/services/hub-client.d.ts.map +1 -0
  264. package/dist/services/hub-client.js +217 -0
  265. package/dist/services/hub-client.js.map +1 -0
  266. package/dist/services/jwt.d.ts +17 -0
  267. package/dist/services/jwt.d.ts.map +1 -0
  268. package/dist/services/jwt.js +70 -0
  269. package/dist/services/jwt.js.map +1 -0
  270. package/dist/services/known-sessions.d.ts +8 -0
  271. package/dist/services/known-sessions.d.ts.map +1 -0
  272. package/dist/services/known-sessions.js +40 -0
  273. package/dist/services/known-sessions.js.map +1 -0
  274. package/dist/services/model-pricing.d.ts +36 -0
  275. package/dist/services/model-pricing.d.ts.map +1 -0
  276. package/dist/services/model-pricing.js +108 -0
  277. package/dist/services/model-pricing.js.map +1 -0
  278. package/dist/services/orphan-recovery.d.ts +56 -0
  279. package/dist/services/orphan-recovery.d.ts.map +1 -0
  280. package/dist/services/orphan-recovery.js +111 -0
  281. package/dist/services/orphan-recovery.js.map +1 -0
  282. package/dist/services/pending-responses.d.ts +23 -0
  283. package/dist/services/pending-responses.d.ts.map +1 -0
  284. package/dist/services/pending-responses.js +52 -0
  285. package/dist/services/pending-responses.js.map +1 -0
  286. package/dist/services/registry.d.ts +4 -1
  287. package/dist/services/registry.d.ts.map +1 -1
  288. package/dist/services/registry.js +3 -0
  289. package/dist/services/registry.js.map +1 -1
  290. package/dist/services/relay-context.d.ts +23 -0
  291. package/dist/services/relay-context.d.ts.map +1 -0
  292. package/dist/services/relay-context.js +8 -0
  293. package/dist/services/relay-context.js.map +1 -0
  294. package/dist/services/relay-executor.d.ts +68 -0
  295. package/dist/services/relay-executor.d.ts.map +1 -0
  296. package/dist/services/relay-executor.js +70 -0
  297. package/dist/services/relay-executor.js.map +1 -0
  298. package/dist/services/relay-request.d.ts +65 -0
  299. package/dist/services/relay-request.d.ts.map +1 -0
  300. package/dist/services/relay-request.js +129 -0
  301. package/dist/services/relay-request.js.map +1 -0
  302. package/dist/services/relay-strategy.d.ts +19 -0
  303. package/dist/services/relay-strategy.d.ts.map +1 -0
  304. package/dist/services/relay-strategy.js +111 -0
  305. package/dist/services/relay-strategy.js.map +1 -0
  306. package/dist/services/service-manager/index.d.ts +5 -0
  307. package/dist/services/service-manager/index.d.ts.map +1 -0
  308. package/dist/services/service-manager/index.js +66 -0
  309. package/dist/services/service-manager/index.js.map +1 -0
  310. package/dist/services/service-manager/linux.d.ts +10 -0
  311. package/dist/services/service-manager/linux.d.ts.map +1 -0
  312. package/dist/services/service-manager/linux.js +97 -0
  313. package/dist/services/service-manager/linux.js.map +1 -0
  314. package/dist/services/service-manager/macos.d.ts +10 -0
  315. package/dist/services/service-manager/macos.d.ts.map +1 -0
  316. package/dist/services/service-manager/macos.js +94 -0
  317. package/dist/services/service-manager/macos.js.map +1 -0
  318. package/dist/services/service-manager/types.d.ts +18 -0
  319. package/dist/services/service-manager/types.d.ts.map +1 -0
  320. package/dist/services/service-manager/types.js +5 -0
  321. package/dist/services/service-manager/types.js.map +1 -0
  322. package/dist/services/service-manager/windows.d.ts +10 -0
  323. package/dist/services/service-manager/windows.d.ts.map +1 -0
  324. package/dist/services/service-manager/windows.js +73 -0
  325. package/dist/services/service-manager/windows.js.map +1 -0
  326. package/dist/services/session-registry.d.ts +70 -0
  327. package/dist/services/session-registry.d.ts.map +1 -0
  328. package/dist/services/session-registry.js +91 -0
  329. package/dist/services/session-registry.js.map +1 -0
  330. package/dist/services/singleton.d.ts +15 -0
  331. package/dist/services/singleton.d.ts.map +1 -0
  332. package/dist/services/singleton.js +98 -0
  333. package/dist/services/singleton.js.map +1 -0
  334. package/dist/services/sprint-coordination.d.ts +168 -0
  335. package/dist/services/sprint-coordination.d.ts.map +1 -0
  336. package/dist/services/sprint-coordination.js +564 -0
  337. package/dist/services/sprint-coordination.js.map +1 -0
  338. package/dist/services/ssh.d.ts.map +1 -1
  339. package/dist/services/ssh.js +70 -3
  340. package/dist/services/ssh.js.map +1 -1
  341. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  342. package/dist/services/stall/log-path-resolver.js +8 -1
  343. package/dist/services/stall/log-path-resolver.js.map +1 -1
  344. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  345. package/dist/services/stall/stall-detector.js +39 -7
  346. package/dist/services/stall/stall-detector.js.map +1 -1
  347. package/dist/services/stall/stall-poller.d.ts +16 -0
  348. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  349. package/dist/services/stall/stall-poller.js +136 -18
  350. package/dist/services/stall/stall-poller.js.map +1 -1
  351. package/dist/services/strategy.d.ts.map +1 -1
  352. package/dist/services/strategy.js +55 -5
  353. package/dist/services/strategy.js.map +1 -1
  354. package/dist/services/substitution-engine.d.ts +20 -0
  355. package/dist/services/substitution-engine.d.ts.map +1 -0
  356. package/dist/services/substitution-engine.js +92 -0
  357. package/dist/services/substitution-engine.js.map +1 -0
  358. package/dist/services/task-cleanup.d.ts.map +1 -1
  359. package/dist/services/task-cleanup.js +1 -9
  360. package/dist/services/task-cleanup.js.map +1 -1
  361. package/dist/services/token-issuer.d.ts +47 -0
  362. package/dist/services/token-issuer.d.ts.map +1 -0
  363. package/dist/services/token-issuer.js +63 -0
  364. package/dist/services/token-issuer.js.map +1 -0
  365. package/dist/services/tool-registry.d.ts +3 -0
  366. package/dist/services/tool-registry.d.ts.map +1 -0
  367. package/dist/services/tool-registry.js +139 -0
  368. package/dist/services/tool-registry.js.map +1 -0
  369. package/dist/services/user-config.d.ts +14 -0
  370. package/dist/services/user-config.d.ts.map +1 -1
  371. package/dist/services/user-config.js +55 -0
  372. package/dist/services/user-config.js.map +1 -1
  373. package/dist/services/vcs/types.d.ts +44 -0
  374. package/dist/services/vcs/types.d.ts.map +1 -1
  375. package/dist/skills/fleet-sprint-cli/SKILL.md +103 -0
  376. package/dist/skills/pm/cost.md +3 -0
  377. package/dist/skills/pm/doer-reviewer-loop.md +3 -0
  378. package/dist/tools/check-status.d.ts.map +1 -1
  379. package/dist/tools/check-status.js +8 -2
  380. package/dist/tools/check-status.js.map +1 -1
  381. package/dist/tools/child-id-allocator.d.ts +45 -0
  382. package/dist/tools/child-id-allocator.d.ts.map +1 -0
  383. package/dist/tools/child-id-allocator.js +62 -0
  384. package/dist/tools/child-id-allocator.js.map +1 -0
  385. package/dist/tools/cloud-control.d.ts +2 -2
  386. package/dist/tools/compose-permissions.d.ts +12 -4
  387. package/dist/tools/compose-permissions.d.ts.map +1 -1
  388. package/dist/tools/compose-permissions.js +55 -4
  389. package/dist/tools/compose-permissions.js.map +1 -1
  390. package/dist/tools/dolt-push-mutex.d.ts +44 -0
  391. package/dist/tools/dolt-push-mutex.d.ts.map +1 -0
  392. package/dist/tools/dolt-push-mutex.js +83 -0
  393. package/dist/tools/dolt-push-mutex.js.map +1 -0
  394. package/dist/tools/execute-command.d.ts +11 -1
  395. package/dist/tools/execute-command.d.ts.map +1 -1
  396. package/dist/tools/execute-command.js +22 -5
  397. package/dist/tools/execute-command.js.map +1 -1
  398. package/dist/tools/execute-prompt.d.ts +72 -12
  399. package/dist/tools/execute-prompt.d.ts.map +1 -1
  400. package/dist/tools/execute-prompt.js +962 -71
  401. package/dist/tools/execute-prompt.js.map +1 -1
  402. package/dist/tools/get-member-model-pricing.d.ts +21 -0
  403. package/dist/tools/get-member-model-pricing.d.ts.map +1 -0
  404. package/dist/tools/get-member-model-pricing.js +29 -0
  405. package/dist/tools/get-member-model-pricing.js.map +1 -0
  406. package/dist/tools/list-members.d.ts.map +1 -1
  407. package/dist/tools/list-members.js +39 -7
  408. package/dist/tools/list-members.js.map +1 -1
  409. package/dist/tools/member-detail.d.ts +1 -1
  410. package/dist/tools/member-detail.d.ts.map +1 -1
  411. package/dist/tools/member-detail.js +8 -2
  412. package/dist/tools/member-detail.js.map +1 -1
  413. package/dist/tools/member-reservation.d.ts +29 -0
  414. package/dist/tools/member-reservation.d.ts.map +1 -0
  415. package/dist/tools/member-reservation.js +71 -0
  416. package/dist/tools/member-reservation.js.map +1 -0
  417. package/dist/tools/provision-vcs-auth.d.ts +7 -7
  418. package/dist/tools/provision-vcs-auth.js +1 -1
  419. package/dist/tools/provision-vcs-auth.js.map +1 -1
  420. package/dist/tools/register-member.d.ts +17 -5
  421. package/dist/tools/register-member.d.ts.map +1 -1
  422. package/dist/tools/register-member.js +144 -5
  423. package/dist/tools/register-member.js.map +1 -1
  424. package/dist/tools/remove-member.d.ts +1 -1
  425. package/dist/tools/report-status.d.ts +33 -0
  426. package/dist/tools/report-status.d.ts.map +1 -0
  427. package/dist/tools/report-status.js +44 -0
  428. package/dist/tools/report-status.js.map +1 -0
  429. package/dist/tools/respond-to-message.d.ts +21 -0
  430. package/dist/tools/respond-to-message.d.ts.map +1 -0
  431. package/dist/tools/respond-to-message.js +23 -0
  432. package/dist/tools/respond-to-message.js.map +1 -0
  433. package/dist/tools/send-files.d.ts +3 -0
  434. package/dist/tools/send-files.d.ts.map +1 -1
  435. package/dist/tools/send-files.js +88 -8
  436. package/dist/tools/send-files.js.map +1 -1
  437. package/dist/tools/send-message.d.ts +27 -0
  438. package/dist/tools/send-message.d.ts.map +1 -0
  439. package/dist/tools/send-message.js +46 -0
  440. package/dist/tools/send-message.js.map +1 -0
  441. package/dist/tools/shutdown-server.d.ts +2 -0
  442. package/dist/tools/shutdown-server.d.ts.map +1 -1
  443. package/dist/tools/shutdown-server.js +19 -0
  444. package/dist/tools/shutdown-server.js.map +1 -1
  445. package/dist/tools/update-member.d.ts +8 -8
  446. package/dist/tools/update-member.d.ts.map +1 -1
  447. package/dist/tools/update-member.js +11 -1
  448. package/dist/tools/update-member.js.map +1 -1
  449. package/dist/types.d.ts +15 -3
  450. package/dist/types.d.ts.map +1 -1
  451. package/dist/utils/agent-helpers.d.ts +2 -1
  452. package/dist/utils/agent-helpers.d.ts.map +1 -1
  453. package/dist/utils/agent-helpers.js +7 -2
  454. package/dist/utils/agent-helpers.js.map +1 -1
  455. package/dist/utils/pid-helpers.d.ts +15 -0
  456. package/dist/utils/pid-helpers.d.ts.map +1 -1
  457. package/dist/utils/pid-helpers.js +23 -0
  458. package/dist/utils/pid-helpers.js.map +1 -1
  459. package/dist/utils/process-utils.d.ts +3 -0
  460. package/dist/utils/process-utils.d.ts.map +1 -0
  461. package/dist/utils/process-utils.js +42 -0
  462. package/dist/utils/process-utils.js.map +1 -0
  463. package/dist/utils/prompt-errors.d.ts +2 -1
  464. package/dist/utils/prompt-errors.d.ts.map +1 -1
  465. package/dist/utils/prompt-errors.js +13 -3
  466. package/dist/utils/prompt-errors.js.map +1 -1
  467. package/dist/utils/workspace-trust.d.ts +24 -0
  468. package/dist/utils/workspace-trust.d.ts.map +1 -0
  469. package/dist/utils/workspace-trust.js +35 -0
  470. package/dist/utils/workspace-trust.js.map +1 -0
  471. package/dist/workflows/auto-sprint.js +450 -87
  472. package/package.json +35 -7
  473. package/packages/apra-fleet-client/package.json +26 -0
  474. package/packages/apra-fleet-client/src/client/api.mjs +396 -0
  475. package/packages/apra-fleet-client/src/client/client.mjs +146 -0
  476. package/packages/apra-fleet-client/src/client/errors.mjs +71 -0
  477. package/packages/apra-fleet-client/src/client/factory.mjs +65 -0
  478. package/packages/apra-fleet-client/src/client/server-resolution.mjs +265 -0
  479. package/packages/apra-fleet-client/src/client/transport.mjs +327 -0
  480. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +287 -0
  481. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +89 -0
  482. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +139 -0
  483. package/packages/apra-fleet-se/apra-pm/agents/doer.md +225 -0
  484. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +169 -0
  485. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +316 -0
  486. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +188 -0
  487. package/packages/apra-fleet-se/apra-pm/agents/planner.md +239 -0
  488. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +216 -0
  489. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +174 -0
  490. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-input.json +35 -0
  491. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +164 -0
  492. package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-input.json +26 -0
  493. package/packages/apra-fleet-se/apra-pm/agents/schemas/ci-watcher-output.json +18 -0
  494. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-input.json +19 -0
  495. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +17 -0
  496. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-input.json +25 -0
  497. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +22 -0
  498. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +31 -0
  499. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-output.json +18 -0
  500. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-input.json +20 -0
  501. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +61 -0
  502. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-input.json +15 -0
  503. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +30 -0
  504. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-input.json +15 -0
  505. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +50 -0
  506. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-input.json +25 -0
  507. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +38 -0
  508. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +402 -0
  509. package/packages/apra-fleet-se/apra-pm/skills/pm/beads.md +142 -0
  510. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +157 -0
  511. package/packages/apra-fleet-se/apra-pm/skills/pm/doer-reviewer-loop.md +300 -0
  512. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +121 -0
  513. package/packages/apra-fleet-se/apra-pm/skills/pm/simple-sprint.md +65 -0
  514. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +327 -0
  515. package/packages/apra-fleet-se/apra-pm/skills/pm/worktrees.md +92 -0
  516. package/packages/apra-fleet-se/apra-pm/version.json +3 -0
  517. package/packages/apra-fleet-se/bin/cli.mjs +857 -0
  518. package/packages/apra-fleet-se/bin/serve.mjs +383 -0
  519. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +178 -0
  520. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +914 -0
  521. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +177 -0
  522. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +191 -0
  523. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +151 -0
  524. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-tier2-runbook.md +127 -0
  525. package/packages/apra-fleet-se/fleet-sprint/docs/fleet-sprint-diagram.md +94 -0
  526. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +1125 -0
  527. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +72 -0
  528. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-path-b.mjs +339 -0
  529. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery-tier2.mjs +360 -0
  530. package/packages/apra-fleet-se/fleet-sprint/dolt-recovery.mjs +363 -0
  531. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1244 -0
  532. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +572 -0
  533. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +118 -0
  534. package/packages/apra-fleet-se/fleet-sprint/runner.js +9447 -0
  535. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +103 -0
  536. package/packages/apra-fleet-se/fleet-sprint/sprint-lock.mjs +140 -0
  537. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +435 -0
  538. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +68 -0
  539. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +53 -0
  540. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +146 -0
  541. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/generic-git.mjs +176 -0
  542. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +222 -0
  543. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +218 -0
  544. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +882 -0
  545. package/packages/apra-fleet-se/package.json +28 -0
  546. package/packages/apra-fleet-se/workflow.json +1 -0
  547. package/packages/apra-fleet-workflow/package.json +30 -0
  548. package/packages/apra-fleet-workflow/src/viewer/command-output-cap.mjs +112 -0
  549. package/packages/apra-fleet-workflow/src/viewer/debounced-writer.mjs +153 -0
  550. package/packages/apra-fleet-workflow/src/viewer/html-utils.mjs +31 -0
  551. package/packages/apra-fleet-workflow/src/viewer/index.mjs +1325 -0
  552. package/packages/apra-fleet-workflow/src/viewer/lean-state.mjs +237 -0
  553. package/packages/apra-fleet-workflow/src/viewer/run-state-paths.mjs +130 -0
  554. package/packages/apra-fleet-workflow/src/viewer/sprint-state-paths.mjs +29 -0
  555. package/packages/apra-fleet-workflow/src/workflow/engine.mjs +200 -0
  556. package/packages/apra-fleet-workflow/src/workflow/errors.mjs +146 -0
  557. package/packages/apra-fleet-workflow/src/workflow/index.mjs +1723 -0
  558. package/packages/apra-fleet-workflow/src/workflow/journal.mjs +291 -0
  559. package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +99 -0
  560. package/packages/apra-fleet-workflow/src/workflow/vetting.mjs +111 -0
  561. package/scripts/agy-transcript-reader.js +1 -0
  562. package/scripts/fleet-statusline.sh +17 -13
  563. package/skills/fleet/SKILL.md +37 -2
  564. package/skills/fleet/beads.md +14 -7
  565. package/skills/fleet/permissions.md +50 -0
  566. package/skills/fleet/profiles/base-dev.json +1 -0
  567. package/skills/fleet/profiles/base-reviewer.json +1 -0
  568. package/skills/fleet/profiles/node.json +2 -2
  569. package/version.json +1 -1
  570. package/scripts/agy-settings-merge.js +0 -27
  571. /package/{dist → packages/apra-fleet-se/apra-pm}/agents/_shared/GRAPH-SEMANTICS.md +0 -0
@@ -0,0 +1,177 @@
1
+ import fs from 'fs';
2
+ import path from 'path';
3
+
4
+ // =============================================================================
5
+ // apra-fleet-eft.3.3 -- dispatch-safety guard checker, extracted so it is
6
+ // exported/parameterizable by path.
7
+ //
8
+ // This module holds the bracket-aware `command(`/`agent(` call-site parser
9
+ // originally written inline in dispatch-safety-guard.test.mjs
10
+ // (apra-fleet-eft.3.1). It is factored out here so the checker can be
11
+ // pointed at an arbitrary source file -- in particular a test fixture that
12
+ // deliberately violates the invariant -- WITHOUT mutating
13
+ // packages/apra-fleet-se/fleet-sprint/runner.js itself to manufacture a
14
+ // failure case. dispatch-safety-guard.test.mjs imports this module both for
15
+ // its real runner.js baseline assertion and for fixture-driven tests that
16
+ // prove the checker actually detects a violation rather than passing
17
+ // vacuously.
18
+ //
19
+ // Invariant under test (unchanged from eft.3.1): EVERY `command(` / `agent(`
20
+ // call site in a scanned source file must supply an explicit `member_name`
21
+ // (or `member_id`) in its options object.
22
+ // =============================================================================
23
+
24
+ /**
25
+ * Returns true if `col` (0-based index into `lineText`) sits inside an open
26
+ * `"..."` or `'...'` string that started earlier on the SAME line -- i.e. an
27
+ * odd number of unescaped quote characters of the currently-open type
28
+ * precede it. Deliberately scoped to a single line (not a whole-file quote
29
+ * scan): a whole-file scan misfires on stray apostrophes in prose comments
30
+ * (e.g. "doesn't", "it's"), which would otherwise be misread as opening a
31
+ * string and swallow everything up to the next quote -- including real
32
+ * command()/agent() call sites many lines later. Backticks are deliberately
33
+ * NOT tracked here: template literals legitimately span multiple lines (git
34
+ * command strings) and are not a source of the false positive this guards
35
+ * against (a real call site's own leading backtick is never itself inside a
36
+ * string).
37
+ */
38
+ export function isInsideSameLineString(lineText, col) {
39
+ let quote = null;
40
+ for (let i = 0; i < col; i++) {
41
+ const ch = lineText[i];
42
+ if (ch === '\\') { i++; continue; }
43
+ if (quote) {
44
+ if (ch === quote) quote = null;
45
+ } else if (ch === '"' || ch === "'") {
46
+ quote = ch;
47
+ }
48
+ }
49
+ return quote !== null;
50
+ }
51
+
52
+ /** Returns the index of the closing quote char matching the one at `start`. */
53
+ export function skipStringLiteral(src, start, quoteChar) {
54
+ let i = start + 1;
55
+ for (; i < src.length; i++) {
56
+ const ch = src[i];
57
+ if (ch === '\\') {
58
+ i++; // skip escaped char
59
+ continue;
60
+ }
61
+ if (ch === quoteChar) return i;
62
+ }
63
+ return i;
64
+ }
65
+
66
+ /**
67
+ * Given the index of an opening '(' in `src`, returns the full call-site
68
+ * text from that '(' through its matching ')', tracking paren depth and
69
+ * skipping over string/template-literal contents (so parens embedded in
70
+ * string/template content, e.g. `bd show ${ids.join(' ')}`, never disturb
71
+ * the depth count).
72
+ */
73
+ export function extractBalancedCall(src, openParenIdx) {
74
+ let depth = 0;
75
+ let i = openParenIdx;
76
+ for (; i < src.length; i++) {
77
+ const ch = src[i];
78
+ if (ch === '(') {
79
+ depth++;
80
+ } else if (ch === ')') {
81
+ depth--;
82
+ if (depth === 0) {
83
+ return src.slice(openParenIdx, i + 1);
84
+ }
85
+ } else if (ch === '"' || ch === "'" || ch === '`') {
86
+ i = skipStringLiteral(src, i, ch);
87
+ }
88
+ }
89
+ // Unbalanced -- should never happen against real, syntactically-valid
90
+ // source; return what we found so the caller's member_name check still
91
+ // has something to inspect rather than throwing mid-scan.
92
+ return src.slice(openParenIdx, i);
93
+ }
94
+
95
+ /**
96
+ * Scans `src` for `command(`/`agent(` call sites, skipping call-site tokens
97
+ * that only appear inside a full-line comment. Returns an array of
98
+ * { fnName, line, callText } for every real call site found.
99
+ */
100
+ export function findCallSites(src) {
101
+ const lines = src.split('\n');
102
+ // Byte offset of the start of each line, so a regex match index into
103
+ // the whole-file string can be mapped back to a 1-based line number.
104
+ const lineStarts = [];
105
+ let offset = 0;
106
+ for (const line of lines) {
107
+ lineStarts.push(offset);
108
+ offset += line.length + 1; // +1 for the '\n' stripped by split()
109
+ }
110
+ function lineNumberForIndex(idx) {
111
+ // Binary search would be overkill for a single source file; linear
112
+ // scan is fine here.
113
+ let ln = 0;
114
+ for (let i = 0; i < lineStarts.length; i++) {
115
+ if (lineStarts[i] > idx) break;
116
+ ln = i;
117
+ }
118
+ return ln + 1; // 1-based
119
+ }
120
+ function isCommentLine(ln) {
121
+ const text = lines[ln - 1] ? lines[ln - 1].trim() : '';
122
+ return text.startsWith('//') || text.startsWith('*') || text.startsWith('/*');
123
+ }
124
+
125
+ // Matches `command(` / `agent(` NOT preceded by a `.` or word character
126
+ // (so e.g. `dispatchCommand(` or `.command(` -- neither of which occurs
127
+ // for the fleet dispatch primitives, but this guards against false
128
+ // positives from unrelated identifiers ending in the same substring).
129
+ const callRe = /(?<![.\w])(command|agent)\(/g;
130
+ const sites = [];
131
+ let m;
132
+ while ((m = callRe.exec(src)) !== null) {
133
+ const fnName = m[1];
134
+ const openParenIdx = m.index + m[0].length - 1; // index of the '(' itself
135
+ const line = lineNumberForIndex(m.index);
136
+ if (isCommentLine(line)) continue;
137
+ // Reject matches where the literal text "command(" / "agent(" sits
138
+ // inside a same-line quoted string (e.g. a `throw new Error("...
139
+ // command() ...")` message) -- not a real dispatch call site.
140
+ const lineText = lines[line - 1] || '';
141
+ const col = m.index - lineStarts[line - 1];
142
+ if (isInsideSameLineString(lineText, col)) continue;
143
+ const callText = extractBalancedCall(src, openParenIdx);
144
+ sites.push({ fnName, line, callText });
145
+ }
146
+ return sites;
147
+ }
148
+
149
+ const MEMBER_RE = /\b(member_name|member_id)\b/;
150
+
151
+ /**
152
+ * Given an array of call sites (as returned by findCallSites), returns the
153
+ * subset lacking an explicit member_name/member_id, each formatted as a
154
+ * human-readable violation string naming `fileLabel` and the offending
155
+ * line -- e.g. "fixture.mjs:4 (command()) is missing member_name/member_id".
156
+ */
157
+ export function findViolations(sites, fileLabel) {
158
+ return sites
159
+ .filter((s) => !MEMBER_RE.test(s.callText))
160
+ .map((s) => `${fileLabel}:${s.line} (${s.fnName}()) is missing member_name/member_id`);
161
+ }
162
+
163
+ /**
164
+ * Reads and scans the source file at `filePath` for command()/agent() call
165
+ * sites, returning { sites, violations }. This is the checker's main
166
+ * path-parameterized entry point: callers -- real runner.js baseline
167
+ * assertions, or fixture-driven tests exercising a deliberately
168
+ * non-compliant call site -- pass whatever file path they want scanned,
169
+ * without needing to mutate runner.js to manufacture a failing case.
170
+ */
171
+ export function checkPath(filePath) {
172
+ const src = fs.readFileSync(filePath, 'utf8');
173
+ const sites = findCallSites(src);
174
+ const fileLabel = path.basename(filePath);
175
+ const violations = findViolations(sites, fileLabel);
176
+ return { sites, violations };
177
+ }
@@ -0,0 +1,191 @@
1
+ # Running fleet-sprint
2
+
3
+ `fleet-sprint` is this package's autonomous sprint engine. It drives a full
4
+ plan -> develop -> review -> deploy -> integ-test -> harvest cycle across one
5
+ or more registered fleet members, working a set of beads issues on a branch
6
+ and opening a PR at the end.
7
+
8
+ This doc covers the two ways to invoke it, the full argument contract, the
9
+ preconditions to check first, and the beads hierarchy rules that determine
10
+ what a sprint actually picks up as its scope.
11
+
12
+ ## Two ways to invoke it
13
+
14
+ Both forms run the exact same engine
15
+ (`packages/apra-fleet-se/fleet-sprint/runner.js`) with the same flags. They
16
+ differ only in how the entry point is resolved.
17
+
18
+ ### 1. Installed binary (normal use)
19
+
20
+ ```bash
21
+ apra-fleet workflow fleet-sprint \
22
+ --issue apra-fleet-eft \
23
+ --members fleet-rev \
24
+ --branch sprint/eft-service-fixes \
25
+ --base main \
26
+ --viewer-port 18300
27
+ ```
28
+
29
+ This is the ONE command for every install method -- git-clone dev checkout,
30
+ `npm install -g @apralabs/apra-fleet`, and the pre-built standalone binary
31
+ all resolve it identically; there is no separate npm-only invocation to
32
+ learn. The launcher resolves the workflow from
33
+ `~/.apra-fleet/workflows/fleet-sprint` (installed by `apra-fleet install`,
34
+ self-healed on demand). Everything after the workflow name is passed
35
+ through verbatim, so `apra-fleet workflow fleet-sprint --help` prints the
36
+ engine's own help.
37
+
38
+ ### 2. Directly from a source checkout (development only)
39
+
40
+ ```bash
41
+ node packages/apra-fleet-se/bin/cli.mjs \
42
+ --issue apra-fleet-eft \
43
+ --members fleet-rev \
44
+ --branch sprint/eft-service-fixes \
45
+ --base main \
46
+ --viewer-port 18300
47
+ ```
48
+
49
+ A development-only shortcut for when you are actively changing the engine
50
+ itself and want to run the working tree directly rather than the installed
51
+ copy. Not needed, and not documented as a supported path, for any other use
52
+ -- use mode 1 above.
53
+
54
+ ### Backgrounding
55
+
56
+ A sprint is a long-running process. Start it genuinely detached, not as a
57
+ child of a short-lived tool call whose process group can be killed out from
58
+ under it:
59
+
60
+ ```bash
61
+ # POSIX
62
+ nohup apra-fleet workflow fleet-sprint --issue <id> --members <m> \
63
+ --branch <branch> --base <base> > sprint.log 2>&1 &
64
+ disown
65
+ ```
66
+
67
+ ```powershell
68
+ # Windows
69
+ Start-Process -FilePath "apra-fleet" -ArgumentList "workflow","fleet-sprint", `
70
+ "--issue","<id>","--members","<m>","--branch","<branch>","--base","<base>" `
71
+ -RedirectStandardOutput "sprint.log" -RedirectStandardError "sprint.err.log" `
72
+ -WindowStyle Hidden -PassThru
73
+ ```
74
+
75
+ On start it prints the dashboard URL (`http://localhost:<viewer-port>`).
76
+ Watch progress there rather than tailing raw stdout.
77
+
78
+ ## Arguments
79
+
80
+ | Flag | Short | Required | Default | Description |
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. |
83
+ | `--members <ids>` | `-m` | yes | -- | Member IDs/names to use, comma separated. Members act as repo targets for parallelism. |
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
+ | `--base <name>` | `-B` | yes | -- | Base branch the sprint branch is created from, and the branch the eventual PR targets. |
86
+ | `--goal <goal>` | `-g` | no | `P1/P2` | Sprint goal constraint. One of `P1`, `P1/P2`, `P1/P2/P3`. |
87
+ | `--max-cycles <n>` | `-c` | no | `5` | Max plan/develop/review cycles. |
88
+ | `--allow-missing-members` | | no | off | Warn and continue if some `--members` are not registered with the fleet. Without it, any missing member aborts the sprint. |
89
+ | `--requirements-file <path>` | | no | -- | Path to a requirements file threaded into the planner's prompt. |
90
+ | `--role-map <json\|@file>` | | no | -- | JSON object mapping role -> member[], e.g. `'{"doer":["m1","m2"]}'`. Inline JSON or `@path/to/file.json`. |
91
+ | `--viewer-port <port>` | | no | `8080` | Port for the local dashboard viewer. |
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. |
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
+ | `--help` | `-h` | | | Show the engine's help. |
96
+
97
+ Unrecognized flags fail loudly rather than being silently ignored, so a typo
98
+ like `--max-cycle` aborts instead of quietly applying the default.
99
+
100
+ ## Preconditions worth checking first
101
+
102
+ - The target issue (e.g. `apra-fleet-7pm`) must exist and be open:
103
+ `bd show <issue>`.
104
+ - Every `--members` name must be registered with the fleet
105
+ (`list_members`); an unregistered member aborts the sprint unless
106
+ `--allow-missing-members` is passed.
107
+ - Multi-member sprints require all configured members to share the same
108
+ git HEAD (`checkMemberTopology`) unless `--sync` is passed -- see
109
+ `fleet-sprint-diagram.md` for the supported-topology notes. Stick to
110
+ single-member unless that is verified.
111
+ - If a member's LLM session is stale or unauthenticated (dispatch fails with
112
+ `empty_response`, or "member CLI likely died"), re-run `provision_llm_auth`
113
+ for that member before retrying.
114
+
115
+ ## How to make one bead represent a whole set (epics / manifest beads)
116
+
117
+ If you want a single bead to stand in for a group of other beads (an epic,
118
+ a "next sprint scope" manifest, etc.), the group members MUST be linked as
119
+ **parent-child**, not as **blocked-by**:
120
+
121
+ - Add each item as a child of the umbrella bead:
122
+ `bd create ... --parent <umbrella-id>` (new beads), or
123
+ `bd update <id> --parent <umbrella-id>` (existing beads).
124
+ - The umbrella bead itself must have **zero** blocking dependencies of its
125
+ own -- do not also add `blocks` edges from the umbrella bead to its own
126
+ children. It should only ever be the *target* of parent-child edges
127
+ (children point at it), never the source of a `blocks` edge pointing at
128
+ them.
129
+ - "All done" tracking (closing the umbrella bead once every child is
130
+ closed) is a manual/observational step based on child status
131
+ (`dependent_count`), not something enforced by a `blocks` edge.
132
+
133
+ Why this matters: `bd`'s ready-work engine treats a `blocks` edge as a real
134
+ blocker. If the umbrella bead both (a) is `blocked-by` its children (so it
135
+ can't close until they do) AND (b) is their `parent` (so they belong to it),
136
+ that is a 2-node cycle on every pair -- and `bd` marks every bead caught in
137
+ a cycle as **not ready**, deadlocking the umbrella bead and all of its
138
+ children simultaneously. This is exactly what "blocked-by" gets you wrong
139
+ and "parent-child" gets right: a successful epic (e.g. `apra-fleet-7pm`)
140
+ has `dependency_count: 0` (it depends on / is blocked by nothing) and a
141
+ nonzero `dependent_count` (its children point at it). A broken manifest
142
+ bead that used `blocks` instead had `dependency_count: 5` and, once
143
+ children were also parented under it, deadlocked completely.
144
+
145
+ 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.
150
+
151
+ ## Recovering a wedged member reservation (launched via the supervisor)
152
+
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
155
+ reservation ledger does **not** release that sprint's claim on its own during
156
+ normal runtime -- only a supervisor restart, or an explicit operator call,
157
+ clears it. Symptom: relaunching against the same member(s) is rejected with
158
+
159
+ ```
160
+ 409 member overlap rejects launch: sprint '<old-sprint-id>' already claims [<member>]
161
+ ```
162
+
163
+ and `POST /api/sprints/:id/stop` against that same old sprint id also fails
164
+ (`409 ... no reachable child (port unknown)`) because the child is already
165
+ dead -- there is nothing left to proxy a stop to.
166
+
167
+ Clear it directly, with no supervisor restart required:
168
+
169
+ ```bash
170
+ curl -X POST http://localhost:8787/api/reservations/<old-sprint-id>/force-release \
171
+ -H "Content-Type: application/json" \
172
+ -d '{"by": "<your name/reason>", "reason": "sprint child crashed, pid confirmed dead"}'
173
+ ```
174
+
175
+ This releases both of the supervisor ledger's axes (member set + issue-scope
176
+ root) for that sprint id in one call and records an auditable
177
+ `force-released` event in the supervisor's event history. It does **not**
178
+ restart anything and does not affect any other live sprint.
179
+
180
+ This is a *different* mechanism from the fleet server's own per-member
181
+ `reservedBy` field (enforced at dispatch time, independent of the
182
+ supervisor). If a relaunch still 409s after force-releasing the ledger side,
183
+ also clear that axis:
184
+
185
+ ```
186
+ mcp__apra-fleet__member_reservation action: "force_release" member_name: "<member>"
187
+ ```
188
+
189
+ A crashed sprint can leave either axis wedged independently of the other --
190
+ check both. See `packages/apra-fleet-se/docs/architecture.md` ("Supervisor:
191
+ process model" / "Manual force-release") for the full mechanism.
@@ -0,0 +1,151 @@
1
+ # Coach Role: Just-in-Time Error Resolution (design note)
2
+
3
+ Status: IN DESIGN (user idea 2026-07-20; scope and consent model refined
4
+ same day; explicitly NOT being operationalized yet -- "let's design more
5
+ before we operationalize"). Recorded here so the design survives context
6
+ loss. Update in place as design decisions land.
7
+
8
+ ## The idea (user's own framing)
9
+
10
+ Insert a "coach" role INSIDE the auto-sprint workflow -- an LLM agent that
11
+ knows the fleet -> workflow -> auto-sprint technology stack and can address
12
+ classes of errors that are UNFORESEEN by the deterministic engine, just in
13
+ time. Every time it intervenes it (a) collects the important aspects of the
14
+ sprint context and (b) produces a bug report describing the problem AND how
15
+ it was resolved -- feeding field telemetry, future releases, and giving
16
+ users a way to progress instead of wedging. It institutionalizes, inside
17
+ the workflow, the stabilization-observer role a human+agent pair played
18
+ from outside during the eft dogfood runs.
19
+
20
+ ## Scope (REFINED): any red state, not just sync failures
21
+
22
+ The coach's jurisdiction is ANY event that leaves the sprint in a red
23
+ state, strictly AFTER existing deterministic handling has been exhausted.
24
+ The error-handling hierarchy is three layers, in order:
25
+
26
+ 1. **Typed handlers and ladders (deterministic, free).** errors.mjs typed
27
+ errors, turn-exhaustion resume ladders, Tier-2 conflict resolution,
28
+ busy-lock retries. The coach NEVER preempts these.
29
+ 2. **Coach (JIT judgment, tokens).** Invoked only when layer 1 has no
30
+ match or its handling failed -- the unforeseen complement.
31
+ 3. **Fail loudly (existing behavior).** If the coach cannot resolve (or
32
+ its per-class/per-run caps are hit), the normal failure path proceeds
33
+ unchanged. The coach never suppresses a failure it could not fix.
34
+
35
+ Red-state interception points (initial taxonomy, extend as discovered):
36
+ - Streak failure after doer dispatch/resume ladder exhaustion
37
+ - Dispatch errors with unrecognized reason (api_error, empty_response,
38
+ transport failures) after existing retries
39
+ - Sync bracket failures (G-push/G-pull/D-push/D-pull) after Tier-2
40
+ - Phase-level failures: deploy failed, integ runner crashed, harvester
41
+ failed
42
+ - Reviewer/planner contract violations after their built-in retry
43
+ - Stall detection firing; state corruption detected; member unreachable;
44
+ auth expiry mid-run
45
+ - Workflow-level abort paths (as evidence collector even when
46
+ unresolvable)
47
+
48
+ ## Guardrails: coach.md carries them ALL (REFINED)
49
+
50
+ The contract file (agents/coach.md, upstream in apra-pm) is the single
51
+ home of every guardrail -- not scattered through engine code -- so the
52
+ guardrails ship with the role definition, version together, and appear in
53
+ every dispatch. Engine-side caps are enforcement backstops of the same
54
+ rules, never the only statement of them.
55
+
56
+ Guardrail set (all load-bearing):
57
+ - ACTION ALLOWLIST only: stash/commit WIP to a rescue branch, clear a
58
+ leaked lock, retry a push, restart a dead session, re-run an idempotent
59
+ step. Hard prohibitions: never force-push, never delete branches/files,
60
+ never mutate bead verdicts or close beads, never edit code content,
61
+ never act outside the member's working tree, never install software.
62
+ - SINGLE-SHOT: one intervention attempt per red event; then report and
63
+ fall back. The coach is never coached (no recursion).
64
+ - SAME-CLASS-TWICE POLICY: an error class (by fingerprint) may be coached
65
+ at most N times per run (N=2 initial); after that it must fail loudly
66
+ and demand an engine fix. Healing is a bridge, never a home.
67
+ - EVERY INTERVENTION FILES A REPORT -- no silent saves. Interventions are
68
+ first-class events in sprint state and appear in final-review evidence
69
+ (a PASS with 12 coach saves reads differently from a clean PASS).
70
+ - TARGET-AGNOSTIC: the coach knows the fleet/workflow/auto-sprint STACK,
71
+ never the target repo's specifics (product-vs-dogfood rule).
72
+ - TOKEN DISCIPLINE: invoked only at layer 2 (rare by construction);
73
+ per-run invocation cap; premium tier acceptable given rarity.
74
+ - REPRODUCIBILITY: interventions recorded in replayable form; mock/golden
75
+ tests stub coach outcomes deterministically.
76
+
77
+ ## Bug reports and consent (REFINED): sanitize, then ask -- or standing consent
78
+
79
+ The coach always produces a SANITIZED, ANONYMIZED report locally. Whether
80
+ it leaves the machine is a separate, consent-gated step:
81
+
82
+ - Modes (fleet config, e.g. coach.telemetry): "never" | "ask" (default) |
83
+ "always".
84
+ - **ask (default)**: report saved under sprint-logs/coach-reports/; the
85
+ user is asked to consent AFTER THE FACT -- at sprint end (PR body /
86
+ dashboard / CLI summary), with the exact sanitized text shown. The
87
+ zero-auth mechanism: a pre-filled GitHub new-issue URL
88
+ (github.com/Apra-Labs/apra-fleet/issues/new?title=...&body=...) -- one
89
+ click, human-in-the-loop by construction, nothing uploads silently,
90
+ no token handling at all.
91
+ - **always (standing consent, mainly internal/trusting users)**: approved
92
+ once and for all via explicit config; reports auto-filed via gh CLI
93
+ using the user's own gh auth, or a scoped token stored in the fleet
94
+ credential store (referenced as a {{secure.*}} handle, never plaintext).
95
+ Standing consent is per-install, revocable, and recorded in the report
96
+ footer ("filed under standing consent").
97
+ - **never**: local reports only; nothing asks, nothing uploads.
98
+
99
+ Sanitization spec (applies BEFORE the report is even saved locally):
100
+ - Absolute paths -> stable placeholders (<work-folder>/..., <home>/...)
101
+ - Hostnames, usernames, IPs, emails -> redacted tokens
102
+ - Anything matching secret patterns (keys, tokens, {{secure.*}} values,
103
+ env dumps) -> stripped outright, never placeholdered
104
+ - Target-repo identifiers (repo name, branch names, bead titles) ->
105
+ optional redaction tier: internal users may keep them; the default
106
+ anonymizes to <target-repo>, <sprint-branch>
107
+ - Code snippets: not included by default; error text is truncated to the
108
+ minimal reproducing lines
109
+ - A stable ANONYMOUS install id (random UUID, no derivation from machine
110
+ identity) enables cross-report dedup without identifying the user
111
+
112
+ Report content (schema sketch):
113
+ - fingerprint: normalized error-class hash (for dedup and the
114
+ same-class-twice cap)
115
+ - context: engine version, OS, provider, phase, role being dispatched
116
+ - narrative: what failed, diagnosis, actionsTaken[], resolved: bool,
117
+ time lost
118
+ - issueDraft: { title, redactedBody, labels: [coach-report, <class>] }
119
+ - Dedup behavior upstream: same fingerprint appends an occurrence
120
+ comment to the existing issue rather than opening a duplicate.
121
+
122
+ ## Implementation sketch (unchanged mechanics, wider trigger)
123
+
124
+ - Contract: agents/coach.md upstream in apra-pm (UPSTREAM DEPENDENCY like
125
+ eft.11: needs an apra-pm PR + submodule pointer bump). Inputs: error
126
+ text, phase, member, recent command history, sprint-state excerpt.
127
+ Tools: Read + tightly-scoped Bash. Output: the report schema above.
128
+ - Engine: a single coachOnRedState() boundary called from every red-state
129
+ interception point listed above (one choke point, not N copies), after
130
+ layer-1 handling. Interventions ledger in sprint state; caps enforced
131
+ engine-side as backstop; telemetry mode read from fleet config.
132
+ - Relation to the outside stabilization loop: coach handles in-run JIT
133
+ recovery; the outside loop remains for engine-level fixes; coach
134
+ reports feed both.
135
+
136
+ ## Open design questions (to resolve before operationalizing)
137
+
138
+ 1. Consent surface for "ask" mode: sprint-end CLI summary, PR body
139
+ section, dashboard card, or all three? (Recommend: PR body section +
140
+ dashboard card; the PR is where humans already look.)
141
+ 2. Does the coach run on the ORCHESTRATOR member or the affected member?
142
+ (Recommend: orchestrator-side dispatch that may execute allowlisted
143
+ commands ON the affected member -- keeps one contract, avoids
144
+ provisioning coach agents everywhere.)
145
+ 3. N values: per-class cap (initial 2) and per-run cap (initial 5) --
146
+ validate against real red-state frequency from run logs.
147
+ 4. Should coach reports also feed a LOCAL knowledge base consulted on
148
+ later invocations within the same install (self-priming), or is that
149
+ scope creep for v1? (Bias: v2.)
150
+ 5. Fingerprint algorithm: normalize paths/ids out of the error text, hash
151
+ the remainder -- needs a worked spec with collision examples.
@@ -0,0 +1,127 @@
1
+ # Dolt conflict recovery: Tier 2 runbook (apra-fleet-eft.9.6)
2
+
3
+ > **Wiring status (apra-fleet-vkc.1): LIVE.** The Path A -> Path B -> Tier 2
4
+ > recovery ladder described here is no longer test-only. `dolt-recovery-tier2.mjs`
5
+ > exports `buildDoltRecoveryLadder()`, which `dolt-sync.mjs`'s `doltPushAfter()`
6
+ > invokes at its divergence terminal and which `runner.js`'s post-dispatch sync
7
+ > bracket (`syncMemberAfterOrdered`) threads in, so a wedged clone at a real
8
+ > D-push attempts this ladder before surfacing `BEADS_SYNC_CONFLICT`. Path A's
9
+ > resolve-in-place step still requires an injected dolt sql-server runtime;
10
+ > until one is wired into `runner.js`, Path A is reached and cleanly self-defers
11
+ > to Path B (discard-and-re-bootstrap) in production.
12
+
13
+ This is the runbook a REAL agent receives when it is dispatched to resolve a
14
+ wedged beads (dolt) clone that the scripted recovery ladder could not close on
15
+ its own. It is the dolt counterpart of the git conflict ladder's Tier 2
16
+ runbook (`conflict-ladder.mjs`'s `buildConflictResolutionRunbookPrompt`) -- see
17
+ that module's header comment for the git version of the same posture.
18
+
19
+ ## When to use this runbook (vs the operator runbook)
20
+
21
+ Use **this** runbook when: a fleet MEMBER's clone is wedged during an automated
22
+ sprint, a human operator at a terminal cannot resolve it, and an agent has been
23
+ dispatched (by `dolt-recovery-tier2.mjs`) as the last-resort escalation after
24
+ the scripted Path A/Path B recovery ladder both failed.
25
+
26
+ Use [the operator runbook](../../../docs/dolt-operator-conflict-runbook.md)
27
+ instead when: you are a human operator with direct terminal/`dolt` CLI access
28
+ to your own local beads clone, and `bd dolt pull` reported a merge conflict.
29
+ That is a different actor (you at a terminal, not a dispatched agent), a
30
+ different clone (your own, not a fleet member's), and a different entry point
31
+ (manual resolution, not automated escalation).
32
+
33
+ See also: the operator runbook links back here for the "I am a dispatched agent,
34
+ not a human at a terminal" case.
35
+
36
+ ## Script-first posture: when this is (and is not) dispatched
37
+
38
+ The dolt sync discipline (Plan Part 3.3/3.4, apra-fleet-eft.9) is
39
+ script-first: two scripted recovery paths run with **zero** agent dispatch
40
+ before Tier 2 is ever considered:
41
+
42
+ 1. **Path A** (`dolt-recovery.mjs`, apra-fleet-eft.9.4) -- scripted,
43
+ resolve-in-place recovery for a plain single-row conflict in an
44
+ allowlisted table (`issues` by default), gated behind two deterministic
45
+ checks (conflicted table(s) all allowlisted; exactly one conflicted row).
46
+ 2. **Path B** (`dolt-recovery-path-b.mjs`, apra-fleet-eft.9.5) -- the
47
+ fallback for whatever Path A's gates reject (a multi-row conflict, a
48
+ conflict outside the allowlist, or a genuine operational failure that
49
+ makes resolve-in-place unsafe): discard the wedged clone's local dolt
50
+ state and re-bootstrap fresh from the shared remote, replaying back the
51
+ one pending mutation that mattered.
52
+
53
+ Tier 2 (this runbook, dispatched by `dolt-recovery-tier2.mjs`'s
54
+ `recoverDoltConflict()`) is the escalation of LAST resort: it is dispatched
55
+ **only** when
56
+
57
+ - Path A's deterministic gate rejected the conflict shape, **and**
58
+ - Path B was also attempted and itself failed (a scripted step -- most
59
+ commonly `bd bootstrap` or the mutation replay -- returned output that is
60
+ not one of the specific, already-classified recognized failure/gotcha
61
+ patterns).
62
+
63
+ The recovery procedure must never proceed blind past an output it does not
64
+ recognize. Every escalation records the wedged state (see below) before
65
+ dispatch -- there is no silent "try something and hope" step anywhere in this
66
+ ladder.
67
+
68
+ ## The wedged state you are handed
69
+
70
+ Every Tier 2 dispatch is armed with a recorded **wedged state** snapshot,
71
+ captured immediately before dispatch, with these fields:
72
+
73
+ - `member` -- which fleet member/clone is wedged.
74
+ - `clonePath` -- the local `.beads` embedded dolt data dir this recovery was
75
+ operating against (default `.beads/embeddeddolt`).
76
+ - `conflictShape` -- the last `assessConflictGates()` result Path A computed
77
+ (which table(s) conflicted, how many conflicting rows, which gate(s)
78
+ failed), or `null` if Path A never got far enough to compute one.
79
+ - `lastOutput` -- the raw error/output text of the last scripted step that
80
+ failed (Path B's failure if Path B ran, otherwise Path A's).
81
+ - `stage` -- which stage of the ladder produced this wedged state (e.g.
82
+ `path-b-exhausted`).
83
+ - `recordedAt` -- an ISO timestamp of when the state was captured.
84
+
85
+ Do not guess past what this snapshot tells you -- if it is incomplete or
86
+ ambiguous, say so in your report rather than inventing what you think the
87
+ conflict must have been.
88
+
89
+ ## Steps to follow, in order
90
+
91
+ 1. Read the wedged state above in full. Confirm you understand `clonePath`,
92
+ `conflictShape`, and `lastOutput` before touching anything.
93
+ 2. Run `bd dolt status` (or, if unavailable, inspect `.beads/metadata.json`
94
+ and the embedded dolt data dir directly) to confirm the clone's actual
95
+ current state matches what the wedged-state snapshot describes. If it does
96
+ not (e.g. someone already fixed it), say so and stop -- do not "helpfully"
97
+ redo work that already happened.
98
+ 3. If a merge is genuinely still open and conflicted, use `dolt sql-server`
99
+ against the SAME embedded data dir referenced by `clonePath` (see Path A's
100
+ own module doc for the exact server-start / `dolt_allow_commit_conflicts`
101
+ / `DOLT_MERGE` / `dolt_conflicts` sequence) to inspect every conflicting
102
+ row with real judgment -- not a blind `--ours`/`--theirs` rule. Understand
103
+ BOTH sides of each conflicting row before deciding how to resolve it.
104
+ 4. Resolve each conflicting row with `CALL DOLT_CONFLICTS_RESOLVE(...)`
105
+ (table-name arg required) and commit with `CALL DOLT_COMMIT(...)`. Verify
106
+ with `SELECT * FROM dolt_conflicts` that zero rows remain before moving on.
107
+ 5. Confirm zero data loss: `SELECT * FROM dolt_log` must show commits from
108
+ BOTH sides of the original conflict.
109
+ 6. Flip `.beads/metadata.json` back to `dolt_mode: "embedded"` and stop the
110
+ ephemeral sql-server -- exactly as Path A's own teardown does, and
111
+ regardless of whether you succeeded or not (reversibility always).
112
+ 7. `bd dolt pull` then `bd dolt push` to republish the reconciled clone.
113
+ Confirm the push actually succeeds -- your own belief that you fixed it is
114
+ never sufficient; a mechanical re-verification (a clean `bd dolt status`
115
+ and a genuinely successful push) is what decides success, the same
116
+ posture as the git ladder's Tier 2 re-verification in
117
+ `runner.js`'s `syncMemberAfter`.
118
+ 8. If, after this, the clone is still wedged or you are not confident the
119
+ conflict was resolved correctly, do **not** force a push or discard data
120
+ to make the error go away. Report exactly what you observed (the
121
+ conflicting row(s), what you tried, and why it did not resolve) so a
122
+ human can take over -- silently discarding real work to unblock a sprint
123
+ is worse than staying blocked.
124
+
125
+ Do not run any `bd` beads-content command unrelated to this recovery (no
126
+ closing/reopening beads) -- this is a pure dolt-clone-recovery dispatch, not a
127
+ development streak.