@apralabs/apra-fleet 0.4.1 → 0.4.3

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 (476) hide show
  1. package/README.md +53 -12
  2. package/dist/agents/backlog-groomer.md +42 -21
  3. package/dist/agents/ci-watcher.md +14 -0
  4. package/dist/agents/deployer.md +59 -46
  5. package/dist/agents/doer.md +157 -134
  6. package/dist/agents/harvester.md +31 -32
  7. package/dist/agents/integ-test-runner.md +92 -113
  8. package/dist/agents/kb-reconciler.md +40 -42
  9. package/dist/agents/plan-reviewer.md +139 -63
  10. package/dist/agents/planner.md +176 -100
  11. package/dist/agents/regression-test-runner.md +77 -81
  12. package/dist/agents/reviewer.md +69 -85
  13. package/dist/agents/schemas/integ-test-runner-output.json +1 -1
  14. package/dist/agents/schemas/plan-reviewer-output.json +37 -0
  15. package/dist/agents/schemas/regression-test-runner-output.json +4 -17
  16. package/dist/cli/agent-transform.d.ts +83 -2
  17. package/dist/cli/agent-transform.d.ts.map +1 -1
  18. package/dist/cli/agent-transform.js +266 -21
  19. package/dist/cli/agent-transform.js.map +1 -1
  20. package/dist/cli/auth.d.ts.map +1 -1
  21. package/dist/cli/auth.js +29 -11
  22. package/dist/cli/auth.js.map +1 -1
  23. package/dist/cli/config.d.ts +7 -5
  24. package/dist/cli/config.d.ts.map +1 -1
  25. package/dist/cli/config.js +44 -43
  26. package/dist/cli/config.js.map +1 -1
  27. package/dist/cli/install.d.ts +33 -0
  28. package/dist/cli/install.d.ts.map +1 -1
  29. package/dist/cli/install.js +294 -61
  30. package/dist/cli/install.js.map +1 -1
  31. package/dist/cli/kb-directives.d.ts.map +1 -1
  32. package/dist/cli/kb-directives.js +2 -1
  33. package/dist/cli/kb-directives.js.map +1 -1
  34. package/dist/cli/register-member.d.ts.map +1 -1
  35. package/dist/cli/register-member.js +7 -3
  36. package/dist/cli/register-member.js.map +1 -1
  37. package/dist/cli/start.d.ts.map +1 -1
  38. package/dist/cli/start.js +7 -0
  39. package/dist/cli/start.js.map +1 -1
  40. package/dist/cli/uninstall.d.ts.map +1 -1
  41. package/dist/cli/uninstall.js +5 -3
  42. package/dist/cli/uninstall.js.map +1 -1
  43. package/dist/cli/watch.d.ts +26 -3
  44. package/dist/cli/watch.d.ts.map +1 -1
  45. package/dist/cli/watch.js +41 -9
  46. package/dist/cli/watch.js.map +1 -1
  47. package/dist/commands/kb-server.d.ts +3 -0
  48. package/dist/commands/kb-server.d.ts.map +1 -1
  49. package/dist/commands/kb-server.js +43 -3
  50. package/dist/commands/kb-server.js.map +1 -1
  51. package/dist/index.js +3 -3
  52. package/dist/os/git-bash-candidates.d.ts +35 -0
  53. package/dist/os/git-bash-candidates.d.ts.map +1 -0
  54. package/dist/os/git-bash-candidates.js +46 -0
  55. package/dist/os/git-bash-candidates.js.map +1 -0
  56. package/dist/os/index.d.ts +13 -4
  57. package/dist/os/index.d.ts.map +1 -1
  58. package/dist/os/index.js +17 -2
  59. package/dist/os/index.js.map +1 -1
  60. package/dist/os/linux.d.ts +6 -0
  61. package/dist/os/linux.d.ts.map +1 -1
  62. package/dist/os/linux.js +36 -3
  63. package/dist/os/linux.js.map +1 -1
  64. package/dist/os/os-commands.d.ts +68 -2
  65. package/dist/os/os-commands.d.ts.map +1 -1
  66. package/dist/os/os-commands.js.map +1 -1
  67. package/dist/os/windows-gitbash.d.ts +98 -0
  68. package/dist/os/windows-gitbash.d.ts.map +1 -0
  69. package/dist/os/windows-gitbash.js +259 -0
  70. package/dist/os/windows-gitbash.js.map +1 -0
  71. package/dist/os/windows.d.ts +6 -0
  72. package/dist/os/windows.d.ts.map +1 -1
  73. package/dist/os/windows.js +73 -8
  74. package/dist/os/windows.js.map +1 -1
  75. package/dist/providers/agy.d.ts +118 -8
  76. package/dist/providers/agy.d.ts.map +1 -1
  77. package/dist/providers/agy.js +580 -55
  78. package/dist/providers/agy.js.map +1 -1
  79. package/dist/providers/claude.d.ts +83 -4
  80. package/dist/providers/claude.d.ts.map +1 -1
  81. package/dist/providers/claude.js +365 -12
  82. package/dist/providers/claude.js.map +1 -1
  83. package/dist/providers/codex.d.ts +7 -4
  84. package/dist/providers/codex.d.ts.map +1 -1
  85. package/dist/providers/codex.js +24 -4
  86. package/dist/providers/codex.js.map +1 -1
  87. package/dist/providers/copilot.d.ts +7 -4
  88. package/dist/providers/copilot.d.ts.map +1 -1
  89. package/dist/providers/copilot.js +27 -4
  90. package/dist/providers/copilot.js.map +1 -1
  91. package/dist/providers/index.d.ts +0 -1
  92. package/dist/providers/index.d.ts.map +1 -1
  93. package/dist/providers/index.js +0 -3
  94. package/dist/providers/index.js.map +1 -1
  95. package/dist/providers/none.d.ts +7 -4
  96. package/dist/providers/none.d.ts.map +1 -1
  97. package/dist/providers/none.js +22 -4
  98. package/dist/providers/none.js.map +1 -1
  99. package/dist/providers/opencode.d.ts +6 -3
  100. package/dist/providers/opencode.d.ts.map +1 -1
  101. package/dist/providers/opencode.js +27 -4
  102. package/dist/providers/opencode.js.map +1 -1
  103. package/dist/providers/provider.d.ts +215 -11
  104. package/dist/providers/provider.d.ts.map +1 -1
  105. package/dist/providers/provider.js +58 -2
  106. package/dist/providers/provider.js.map +1 -1
  107. package/dist/services/agent-provisioner.js +2 -2
  108. package/dist/services/agent-provisioner.js.map +1 -1
  109. package/dist/services/agy-project.d.ts +102 -0
  110. package/dist/services/agy-project.d.ts.map +1 -0
  111. package/dist/services/agy-project.js +356 -0
  112. package/dist/services/agy-project.js.map +1 -0
  113. package/dist/services/auth-socket.js +4 -4
  114. package/dist/services/auth-web.js +1 -1
  115. package/dist/services/cloud/activity.js +2 -2
  116. package/dist/services/cloud/activity.js.map +1 -1
  117. package/dist/services/cloud/lifecycle.d.ts.map +1 -1
  118. package/dist/services/cloud/lifecycle.js +33 -4
  119. package/dist/services/cloud/lifecycle.js.map +1 -1
  120. package/dist/services/context-admission.d.ts.map +1 -1
  121. package/dist/services/context-admission.js +9 -7
  122. package/dist/services/context-admission.js.map +1 -1
  123. package/dist/services/credential-cleanup.d.ts.map +1 -1
  124. package/dist/services/credential-cleanup.js +47 -10
  125. package/dist/services/credential-cleanup.js.map +1 -1
  126. package/dist/services/exit-drain.d.ts +44 -0
  127. package/dist/services/exit-drain.d.ts.map +1 -0
  128. package/dist/services/exit-drain.js +52 -0
  129. package/dist/services/exit-drain.js.map +1 -0
  130. package/dist/services/github-app.d.ts.map +1 -1
  131. package/dist/services/github-app.js +32 -4
  132. package/dist/services/github-app.js.map +1 -1
  133. package/dist/services/http-transport.d.ts +1 -0
  134. package/dist/services/http-transport.d.ts.map +1 -1
  135. package/dist/services/http-transport.js +48 -1
  136. package/dist/services/http-transport.js.map +1 -1
  137. package/dist/services/knowledge/kb-config.d.ts +42 -0
  138. package/dist/services/knowledge/kb-config.d.ts.map +1 -0
  139. package/dist/services/knowledge/kb-config.js +54 -0
  140. package/dist/services/knowledge/kb-config.js.map +1 -0
  141. package/dist/services/knowledge/kb-providers.d.ts +7 -1
  142. package/dist/services/knowledge/kb-providers.d.ts.map +1 -1
  143. package/dist/services/knowledge/kb-providers.js +191 -17
  144. package/dist/services/knowledge/kb-providers.js.map +1 -1
  145. package/dist/services/knowledge/require-sqlite-project.d.ts +32 -0
  146. package/dist/services/knowledge/require-sqlite-project.d.ts.map +1 -0
  147. package/dist/services/knowledge/require-sqlite-project.js +38 -0
  148. package/dist/services/knowledge/require-sqlite-project.js.map +1 -0
  149. package/dist/services/member-home.d.ts +1 -1
  150. package/dist/services/member-home.d.ts.map +1 -1
  151. package/dist/services/member-home.js +15 -12
  152. package/dist/services/member-home.js.map +1 -1
  153. package/dist/services/model-pricing.d.ts.map +1 -1
  154. package/dist/services/model-pricing.js +7 -8
  155. package/dist/services/model-pricing.js.map +1 -1
  156. package/dist/services/orphan-recovery.d.ts +6 -3
  157. package/dist/services/orphan-recovery.d.ts.map +1 -1
  158. package/dist/services/orphan-recovery.js +17 -14
  159. package/dist/services/orphan-recovery.js.map +1 -1
  160. package/dist/services/preflight-check.js +2 -2
  161. package/dist/services/preflight-check.js.map +1 -1
  162. package/dist/services/secret-token.d.ts +38 -0
  163. package/dist/services/secret-token.d.ts.map +1 -0
  164. package/dist/services/secret-token.js +51 -0
  165. package/dist/services/secret-token.js.map +1 -0
  166. package/dist/services/service-manager/types.d.ts +3 -1
  167. package/dist/services/service-manager/types.d.ts.map +1 -1
  168. package/dist/services/service-manager/windows.d.ts +14 -2
  169. package/dist/services/service-manager/windows.d.ts.map +1 -1
  170. package/dist/services/service-manager/windows.js +65 -7
  171. package/dist/services/service-manager/windows.js.map +1 -1
  172. package/dist/services/shell-probe.d.ts +131 -0
  173. package/dist/services/shell-probe.d.ts.map +1 -0
  174. package/dist/services/shell-probe.js +210 -0
  175. package/dist/services/shell-probe.js.map +1 -0
  176. package/dist/services/singleton.d.ts +2 -0
  177. package/dist/services/singleton.d.ts.map +1 -1
  178. package/dist/services/singleton.js +1 -1
  179. package/dist/services/singleton.js.map +1 -1
  180. package/dist/services/ssh.d.ts.map +1 -1
  181. package/dist/services/ssh.js +60 -4
  182. package/dist/services/ssh.js.map +1 -1
  183. package/dist/services/stall/find-log-file.d.ts.map +1 -1
  184. package/dist/services/stall/find-log-file.js +22 -16
  185. package/dist/services/stall/find-log-file.js.map +1 -1
  186. package/dist/services/stall/read-log-tail.d.ts.map +1 -1
  187. package/dist/services/stall/read-log-tail.js +26 -15
  188. package/dist/services/stall/read-log-tail.js.map +1 -1
  189. package/dist/services/stall/stall-detector.d.ts +53 -4
  190. package/dist/services/stall/stall-detector.d.ts.map +1 -1
  191. package/dist/services/stall/stall-detector.js +212 -34
  192. package/dist/services/stall/stall-detector.js.map +1 -1
  193. package/dist/services/stall/stall-poller.d.ts.map +1 -1
  194. package/dist/services/stall/stall-poller.js +35 -42
  195. package/dist/services/stall/stall-poller.js.map +1 -1
  196. package/dist/services/strategy.d.ts +9 -0
  197. package/dist/services/strategy.d.ts.map +1 -1
  198. package/dist/services/strategy.js +119 -8
  199. package/dist/services/strategy.js.map +1 -1
  200. package/dist/services/substitution-engine.js +2 -2
  201. package/dist/services/substitution-engine.js.map +1 -1
  202. package/dist/services/tool-registry.d.ts.map +1 -1
  203. package/dist/services/tool-registry.js +5 -3
  204. package/dist/services/tool-registry.js.map +1 -1
  205. package/dist/services/user-config.js +1 -1
  206. package/dist/services/user-config.js.map +1 -1
  207. package/dist/services/vcs/azure-devops.d.ts +67 -2
  208. package/dist/services/vcs/azure-devops.d.ts.map +1 -1
  209. package/dist/services/vcs/azure-devops.js +281 -15
  210. package/dist/services/vcs/azure-devops.js.map +1 -1
  211. package/dist/services/vcs/bitbucket.d.ts.map +1 -1
  212. package/dist/services/vcs/bitbucket.js +16 -0
  213. package/dist/services/vcs/bitbucket.js.map +1 -1
  214. package/dist/services/vcs/github.d.ts.map +1 -1
  215. package/dist/services/vcs/github.js +24 -0
  216. package/dist/services/vcs/github.js.map +1 -1
  217. package/dist/services/vcs/types.d.ts +123 -2
  218. package/dist/services/vcs/types.d.ts.map +1 -1
  219. package/dist/skills/fleet-sprint-cli/SKILL.md +20 -1
  220. package/dist/skills/pm/SKILL.md +1 -2
  221. package/dist/skills/pm/cost.md +0 -4
  222. package/dist/skills/pm/fleet-addendum.md +2 -3
  223. package/dist/tools/check-status.d.ts +7 -4
  224. package/dist/tools/check-status.d.ts.map +1 -1
  225. package/dist/tools/check-status.js +5 -3
  226. package/dist/tools/check-status.js.map +1 -1
  227. package/dist/tools/cloud-control.js +2 -2
  228. package/dist/tools/cloud-control.js.map +1 -1
  229. package/dist/tools/compose-permissions.d.ts +6 -0
  230. package/dist/tools/compose-permissions.d.ts.map +1 -1
  231. package/dist/tools/compose-permissions.js +211 -50
  232. package/dist/tools/compose-permissions.js.map +1 -1
  233. package/dist/tools/credential-store-set.js +1 -1
  234. package/dist/tools/execute-command.d.ts.map +1 -1
  235. package/dist/tools/execute-command.js +56 -29
  236. package/dist/tools/execute-command.js.map +1 -1
  237. package/dist/tools/execute-prompt.d.ts +15 -2
  238. package/dist/tools/execute-prompt.d.ts.map +1 -1
  239. package/dist/tools/execute-prompt.js +1214 -873
  240. package/dist/tools/execute-prompt.js.map +1 -1
  241. package/dist/tools/kb-capture.d.ts +2 -2
  242. package/dist/tools/kb-capture.d.ts.map +1 -1
  243. package/dist/tools/kb-capture.js +29 -5
  244. package/dist/tools/kb-capture.js.map +1 -1
  245. package/dist/tools/kb-export.d.ts +2 -2
  246. package/dist/tools/kb-export.d.ts.map +1 -1
  247. package/dist/tools/kb-export.js +3 -28
  248. package/dist/tools/kb-export.js.map +1 -1
  249. package/dist/tools/kb-feedback.d.ts.map +1 -1
  250. package/dist/tools/kb-feedback.js +3 -1
  251. package/dist/tools/kb-feedback.js.map +1 -1
  252. package/dist/tools/kb-freshness-sweep.d.ts.map +1 -1
  253. package/dist/tools/kb-freshness-sweep.js +3 -1
  254. package/dist/tools/kb-freshness-sweep.js.map +1 -1
  255. package/dist/tools/kb-import.d.ts.map +1 -1
  256. package/dist/tools/kb-import.js +2 -1
  257. package/dist/tools/kb-import.js.map +1 -1
  258. package/dist/tools/kb-list.d.ts.map +1 -1
  259. package/dist/tools/kb-list.js +3 -1
  260. package/dist/tools/kb-list.js.map +1 -1
  261. package/dist/tools/kb-query.d.ts +2 -2
  262. package/dist/tools/kb-reconcile-prefilter.d.ts.map +1 -1
  263. package/dist/tools/kb-reconcile-prefilter.js +3 -1
  264. package/dist/tools/kb-reconcile-prefilter.js.map +1 -1
  265. package/dist/tools/kb-resolve-contradiction.d.ts.map +1 -1
  266. package/dist/tools/kb-resolve-contradiction.js +3 -1
  267. package/dist/tools/kb-resolve-contradiction.js.map +1 -1
  268. package/dist/tools/kb-setup.d.ts.map +1 -1
  269. package/dist/tools/kb-setup.js +125 -20
  270. package/dist/tools/kb-setup.js.map +1 -1
  271. package/dist/tools/kb-stats.d.ts.map +1 -1
  272. package/dist/tools/kb-stats.js +64 -43
  273. package/dist/tools/kb-stats.js.map +1 -1
  274. package/dist/tools/list-members.d.ts +2 -2
  275. package/dist/tools/list-members.d.ts.map +1 -1
  276. package/dist/tools/list-members.js +7 -2
  277. package/dist/tools/list-members.js.map +1 -1
  278. package/dist/tools/member-detail.d.ts +2 -2
  279. package/dist/tools/member-detail.d.ts.map +1 -1
  280. package/dist/tools/member-detail.js +22 -3
  281. package/dist/tools/member-detail.js.map +1 -1
  282. package/dist/tools/member-reservation.d.ts +58 -1
  283. package/dist/tools/member-reservation.d.ts.map +1 -1
  284. package/dist/tools/member-reservation.js +71 -18
  285. package/dist/tools/member-reservation.js.map +1 -1
  286. package/dist/tools/monitor-task.d.ts.map +1 -1
  287. package/dist/tools/monitor-task.js +17 -2
  288. package/dist/tools/monitor-task.js.map +1 -1
  289. package/dist/tools/provision-auth.d.ts +80 -1
  290. package/dist/tools/provision-auth.d.ts.map +1 -1
  291. package/dist/tools/provision-auth.js +147 -59
  292. package/dist/tools/provision-auth.js.map +1 -1
  293. package/dist/tools/provision-vcs-auth.d.ts +96 -3
  294. package/dist/tools/provision-vcs-auth.d.ts.map +1 -1
  295. package/dist/tools/provision-vcs-auth.js +254 -88
  296. package/dist/tools/provision-vcs-auth.js.map +1 -1
  297. package/dist/tools/register-member.d.ts +21 -12
  298. package/dist/tools/register-member.d.ts.map +1 -1
  299. package/dist/tools/register-member.js +141 -16
  300. package/dist/tools/register-member.js.map +1 -1
  301. package/dist/tools/remove-member.d.ts.map +1 -1
  302. package/dist/tools/remove-member.js +29 -4
  303. package/dist/tools/remove-member.js.map +1 -1
  304. package/dist/tools/revoke-vcs-auth.js +2 -2
  305. package/dist/tools/revoke-vcs-auth.js.map +1 -1
  306. package/dist/tools/send-email.d.ts +2 -2
  307. package/dist/tools/setup-git-app.d.ts.map +1 -1
  308. package/dist/tools/setup-git-app.js +11 -7
  309. package/dist/tools/setup-git-app.js.map +1 -1
  310. package/dist/tools/setup-ssh-key.d.ts.map +1 -1
  311. package/dist/tools/setup-ssh-key.js +2 -1
  312. package/dist/tools/setup-ssh-key.js.map +1 -1
  313. package/dist/tools/shutdown-server.d.ts +2 -0
  314. package/dist/tools/shutdown-server.d.ts.map +1 -1
  315. package/dist/tools/shutdown-server.js +23 -1
  316. package/dist/tools/shutdown-server.js.map +1 -1
  317. package/dist/tools/stop-prompt.js +2 -2
  318. package/dist/tools/stop-prompt.js.map +1 -1
  319. package/dist/tools/update-agent-cli.js +2 -2
  320. package/dist/tools/update-agent-cli.js.map +1 -1
  321. package/dist/tools/update-member.d.ts +21 -12
  322. package/dist/tools/update-member.d.ts.map +1 -1
  323. package/dist/tools/update-member.js +61 -12
  324. package/dist/tools/update-member.js.map +1 -1
  325. package/dist/tools/vcs-credential-exec.d.ts +127 -0
  326. package/dist/tools/vcs-credential-exec.d.ts.map +1 -0
  327. package/dist/tools/vcs-credential-exec.js +197 -0
  328. package/dist/tools/vcs-credential-exec.js.map +1 -0
  329. package/dist/types.d.ts +24 -1
  330. package/dist/types.d.ts.map +1 -1
  331. package/dist/utils/agent-helpers.d.ts +36 -0
  332. package/dist/utils/agent-helpers.d.ts.map +1 -1
  333. package/dist/utils/agent-helpers.js +39 -1
  334. package/dist/utils/agent-helpers.js.map +1 -1
  335. package/dist/utils/log-helpers.d.ts.map +1 -1
  336. package/dist/utils/log-helpers.js +2 -2
  337. package/dist/utils/log-helpers.js.map +1 -1
  338. package/dist/utils/platform.d.ts +7 -0
  339. package/dist/utils/platform.d.ts.map +1 -1
  340. package/dist/utils/platform.js +11 -1
  341. package/dist/utils/platform.js.map +1 -1
  342. package/dist/utils/prompt-errors.d.ts.map +1 -1
  343. package/dist/utils/prompt-errors.js +7 -1
  344. package/dist/utils/prompt-errors.js.map +1 -1
  345. package/dist/utils/shell-escape.d.ts +16 -0
  346. package/dist/utils/shell-escape.d.ts.map +1 -1
  347. package/dist/utils/shell-escape.js +22 -2
  348. package/dist/utils/shell-escape.js.map +1 -1
  349. package/dist/utils/vcs-provider-detect.d.ts +65 -0
  350. package/dist/utils/vcs-provider-detect.d.ts.map +1 -0
  351. package/dist/utils/vcs-provider-detect.js +109 -0
  352. package/dist/utils/vcs-provider-detect.js.map +1 -0
  353. package/dist/utils/workspace-trust.d.ts +20 -17
  354. package/dist/utils/workspace-trust.d.ts.map +1 -1
  355. package/dist/utils/workspace-trust.js +91 -1
  356. package/dist/utils/workspace-trust.js.map +1 -1
  357. package/dist/workflows/auto-sprint.js +180 -32
  358. package/package.json +7 -5
  359. package/packages/apra-fleet-client/src/client/api.mjs +403 -12
  360. package/packages/apra-fleet-client/src/client/errors.mjs +6 -2
  361. package/packages/apra-fleet-se/apra-pm/agents/_shared/GRAPH-SEMANTICS.md +10 -2
  362. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +42 -21
  363. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +14 -0
  364. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +59 -46
  365. package/packages/apra-fleet-se/apra-pm/agents/doer.md +157 -134
  366. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +31 -32
  367. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +92 -113
  368. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +40 -42
  369. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +139 -63
  370. package/packages/apra-fleet-se/apra-pm/agents/planner.md +176 -100
  371. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +77 -81
  372. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +69 -85
  373. package/packages/apra-fleet-se/apra-pm/agents/schemas/integ-test-runner-output.json +1 -1
  374. package/packages/apra-fleet-se/apra-pm/agents/schemas/plan-reviewer-output.json +37 -0
  375. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +4 -17
  376. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +1 -2
  377. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +0 -4
  378. package/packages/apra-fleet-se/apra-pm/skills/pm/fleet-addendum.md +2 -3
  379. package/packages/apra-fleet-se/bin/cli.mjs +280 -3
  380. package/packages/apra-fleet-se/bin/serve.mjs +114 -5
  381. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +481 -0
  382. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +491 -0
  383. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +282 -0
  384. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +208 -0
  385. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +638 -0
  386. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +301 -0
  387. package/packages/apra-fleet-se/fleet-sprint/branch-ensure.mjs +96 -0
  388. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +8 -0
  389. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +199 -34
  390. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +516 -0
  391. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +184 -0
  392. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +1121 -0
  393. package/packages/apra-fleet-se/fleet-sprint/dispatch-safety-guard.mjs +216 -4
  394. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +23 -8
  395. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-manual-recovery-verified.md +10 -8
  396. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +285 -4
  397. package/packages/apra-fleet-se/fleet-sprint/docs/escalate-to-llm-design.md +3 -3
  398. package/packages/apra-fleet-se/fleet-sprint/docs/run-sprint-cycle-prelude-decision.md +215 -0
  399. package/packages/apra-fleet-se/fleet-sprint/docs/shared-orchestrator-reservation-design.md +12 -12
  400. package/packages/apra-fleet-se/fleet-sprint/docs/stabilization-log.md +14 -4
  401. package/packages/apra-fleet-se/fleet-sprint/dolt-literal-guard.mjs +56 -1
  402. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +275 -99
  403. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +1054 -39
  404. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +308 -0
  405. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +501 -0
  406. package/packages/apra-fleet-se/fleet-sprint/fatal-diagnostics.mjs +134 -0
  407. package/packages/apra-fleet-se/fleet-sprint/full-db-fetch-guard.mjs +102 -0
  408. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +556 -0
  409. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +495 -0
  410. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +564 -0
  411. package/packages/apra-fleet-se/fleet-sprint/inline-ladder-guard.mjs +216 -0
  412. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +728 -0
  413. package/packages/apra-fleet-se/fleet-sprint/mcp-result.mjs +75 -0
  414. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +252 -0
  415. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +581 -0
  416. package/packages/apra-fleet-se/fleet-sprint/member-target.mjs +93 -0
  417. package/packages/apra-fleet-se/fleet-sprint/newtask-text.mjs +266 -0
  418. package/packages/apra-fleet-se/fleet-sprint/parent-notes-staleness.mjs +201 -0
  419. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +136 -0
  420. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +822 -0
  421. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +294 -0
  422. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +403 -0
  423. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +180 -0
  424. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +358 -0
  425. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +390 -0
  426. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +323 -0
  427. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +232 -0
  428. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +174 -0
  429. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +197 -0
  430. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +305 -0
  431. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +559 -0
  432. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +1416 -0
  433. package/packages/apra-fleet-se/fleet-sprint/round-session.mjs +100 -0
  434. package/packages/apra-fleet-se/fleet-sprint/runner.js +1672 -9072
  435. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +134 -0
  436. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +159 -0
  437. package/packages/apra-fleet-se/fleet-sprint/se-windows-gitbash.mjs +97 -0
  438. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +143 -0
  439. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +304 -0
  440. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +20 -1
  441. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +21 -2
  442. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +454 -0
  443. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +239 -0
  444. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +163 -0
  445. package/packages/apra-fleet-se/fleet-sprint/unbracketed-push-guard.mjs +234 -0
  446. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +211 -0
  447. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +1279 -0
  448. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +204 -19
  449. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +707 -12
  450. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +28 -0
  451. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/dolt.mjs +33 -4
  452. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +191 -43
  453. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +333 -6
  454. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +165 -0
  455. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +167 -37
  456. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +559 -0
  457. package/packages/apra-fleet-se/package.json +1 -1
  458. package/packages/apra-fleet-workflow/src/viewer/index.mjs +178 -1
  459. package/packages/apra-fleet-workflow/src/workflow/index.mjs +478 -32
  460. package/skills/fleet/SKILL.md +27 -16
  461. package/skills/fleet/auth-azdevops.md +57 -7
  462. package/skills/fleet/auth-bitbucket.md +5 -5
  463. package/skills/fleet/auth-github.md +7 -6
  464. package/skills/fleet/beads-conflict-resolution.md +141 -0
  465. package/skills/fleet/beads.md +16 -12
  466. package/skills/fleet/onboarding.md +6 -6
  467. package/skills/fleet/permissions.md +11 -7
  468. package/skills/fleet/profiles/node.json +1 -1
  469. package/skills/fleet/skill-matrix.md +1 -1
  470. package/skills/fleet/troubleshooting.md +4 -3
  471. package/version.json +1 -1
  472. package/dist/providers/gemini.d.ts +0 -52
  473. package/dist/providers/gemini.d.ts.map +0 -1
  474. package/dist/providers/gemini.js +0 -236
  475. package/dist/providers/gemini.js.map +0 -1
  476. package/packages/apra-fleet-se/fleet-sprint/docs/coach-role-design.md +0 -23
@@ -7,7 +7,7 @@ import { knownRepoRemoteUrl } from '../services/member-remote-url.js';
7
7
  import { getStrategy } from '../services/strategy.js';
8
8
  import { getOsCommands } from '../os/index.js';
9
9
  import { getProvider } from '../providers/index.js';
10
- import { getAgentOS, touchAgent, getStoredPid } from '../utils/agent-helpers.js';
10
+ import { getAgentOS, getAgentShell, touchAgent, getStoredPid, isPosixShellMember } from '../utils/agent-helpers.js';
11
11
  import { updateAgent } from '../services/registry.js';
12
12
  import { memberIdentifier, resolveMember } from '../utils/resolve-member.js';
13
13
  import { isRetryable, authErrorAdvice, workspaceNotTrustedAdvice } from '../utils/prompt-errors.js';
@@ -23,6 +23,7 @@ import { resolveTilde } from './execute-command.js';
23
23
  import { clearStoredPid } from '../utils/agent-helpers.js';
24
24
  import { tryKillPid, isPidAlive } from '../utils/pid-helpers.js';
25
25
  import { recoverOrphanedDispatch, isRemoteProcessAlive } from '../services/orphan-recovery.js';
26
+ import { hasSecretToken } from '../services/secret-token.js';
26
27
  import { seedWorkspaceTrust } from '../utils/workspace-trust.js';
27
28
  import { durableOutputPath } from '../os/linux.js';
28
29
  import { LogScope, logLine, logWarn, maskSecrets, truncateForLog } from '../utils/log-helpers.js';
@@ -37,6 +38,7 @@ import { sendMessage } from './send-message.js';
37
38
  import { registerPending } from '../services/pending-responses.js';
38
39
  import { isMaxTurnsResponse } from '../providers/provider.js';
39
40
  import { preflightCheck } from '../services/preflight-check.js';
41
+ import { ensureAgyProject } from '../services/agy-project.js';
40
42
  export const executePromptSchema = z.object({
41
43
  ...memberIdentifier,
42
44
  prompt: z.string().describe('The prompt to send to the LLM on the remote member'),
@@ -46,7 +48,16 @@ export const executePromptSchema = z.object({
46
48
  'false = always start a fresh session. ' +
47
49
  'A session-id STRING = EXPLICIT resume of exactly that session, preferred over the member\'s stored session -- the caller asserts this prompt depends on that session\'s prior context, so an unknown/expired id is a TERMINAL error ' +
48
50
  '(structured {isError, reason: "session_not_found"}, NO LLM call, and NO fresh-session fallback) rather than a silent wrong-context dispatch.'),
49
- timeout_s: z.number().default(300).describe('Inactivity timeout in seconds -- the command is killed after this many seconds without any stdout/stderr output (default: 300s / 5 minutes)'),
51
+ fork: z.union([z.boolean(), z.string()]).optional().describe('Branch a NEW session from an existing one instead of continuing it in place. ' +
52
+ 'Mirrors resume\'s shape, but BRANCHES rather than continues: it mints a distinct new ' +
53
+ 'session id seeded from the source session\'s context, leaving the source session itself ' +
54
+ 'untouched. true = fork from the member\'s stored last session. A session-id STRING = fork ' +
55
+ 'from exactly that session. Mutually exclusive with resume (any non-default value, i.e. ' +
56
+ 'false or a session-id string) and with session_id (a resume shorthand) -- specifying fork ' +
57
+ 'together with either is rejected as a validation error before any member resolution or LLM ' +
58
+ 'call. NOTE: this field only covers the schema + the mutual-exclusivity guard; actual fork ' +
59
+ 'MODE RESOLUTION (minting/wiring the forked session) is implemented separately.'),
60
+ timeout_s: z.number().default(300).describe('Inactivity timeout in seconds -- always drives the stall detector\'s per-dispatch baseline threshold, measured against the member\'s own session transcript activity (default: 300s / 5 minutes). Omitting it yields a 300s baseline, a deliberate change from the previously silent 150s stall-detector default. Per-provider, it ALSO arms the exec-level rolling timer against this dispatch\'s stdout/stderr channel for Codex and Copilot, which have no pollable transcript; Claude and AGY take that exec-channel ceiling from max_total_s instead; and OpenCode keeps BOTH signals armed at once (this exec-channel timer plus coarse log-directory-mtime polling, combined with OR semantics -- either advancing counts as not-stalled), since its transcript signal is directory-level only, not a per-turn file (see ProviderAdapter.execTimeoutSource()).'),
50
61
  max_total_s: z.number().optional().describe('Hard ceiling in seconds -- the command is killed after this total elapsed time regardless of activity. If omitted, there is no total time limit.'),
51
62
  max_turns: z.number().min(1).max(500).optional().describe('Max turns for claude -p (default: 50)'),
52
63
  model: z.string().optional().describe('Model tier ("cheap", "standard", "premium") or a specific model ID for power users. Prefer tier names -- the server resolves them to the correct model per provider. If omitted, defaults to the standard tier. Applies to both new and resumed sessions.'),
@@ -56,12 +67,9 @@ export const executePromptSchema = z.object({
56
67
  'Extra keys are silently ignored. Values are never logged.'),
57
68
  agent: z.string().optional().describe('Optional agent name to activate. ' +
58
69
  'For Claude: invokes claude --agent <name>. ' +
59
- 'For Gemini: prepends @<name> to the prompt on every dispatch. ' +
60
- 'For AGY: prepends @<name> to the prompt on every dispatch (same as Gemini). ' +
61
- 'Substitution runs before the @<name> prepend. ' +
70
+ 'For AGY: invokes agy --agent <name>. ' +
62
71
  'Agent file must exist at the provider-specific path on the member: ' +
63
72
  'Claude: <workFolder>/.claude/agents/<name>.md or ~/.claude/agents/<name>.md; ' +
64
- 'Gemini: <workFolder>/.gemini/agents/<name>.md or ~/.gemini/agents/<name>.md; ' +
65
73
  'AGY: <workFolder>/.gemini/antigravity-cli/agents/<name>.md or ~/.gemini/antigravity-cli/agents/<name>.md; ' +
66
74
  'OpenCode: <workFolder>/.opencode/agents/<name>.md or ~/.config/opencode/agents/<name>.md -- ' +
67
75
  'the call is rejected with a clear error if neither is present.'),
@@ -102,6 +110,16 @@ ${output}`;
102
110
  : `[FAIL] Prompt failed on "${agentName}":
103
111
  ${output}`;
104
112
  }
113
+ // apra-fleet-25yl.2.1: the exec-level rolling deadline used for a provider
114
+ // whose ExecTimeoutSource is 'total_ceiling' when the caller supplied NO
115
+ // max_total_s -- i.e. there is no ceiling to mirror. 24h: large enough that it
116
+ // can never bind before any realistic dispatch or client-side deadline, and
117
+ // small enough to stay inside the int32 range setTimeout accepts (Infinity or
118
+ // MAX_SAFE_INTEGER overflow to "fire immediately", which would invert the
119
+ // decoupling into an instant kill). The alternative -- falling back to
120
+ // timeout_s -- is deliberately NOT taken: that is the exact coupling this
121
+ // removes, and for these providers timeout_s belongs to the StallDetector.
122
+ const EXEC_TIMER_NEVER_BINDS_MS = 86_400_000;
105
123
  const SERVER_RETRY_DELAY_MS = 5000;
106
124
  // A prompt written whole into a single remote exec command line can exceed
107
125
  // the SSH exec channel's / Windows CreateProcess's command-line ceiling once
@@ -129,11 +147,20 @@ async function writePromptFile(agent, strategy, promptFilePath, content) {
129
147
  fs.writeFileSync(promptFilePath, content, 'utf-8');
130
148
  return;
131
149
  }
132
- const agentOs = getAgentOS(agent);
133
150
  const promptFileName = path.basename(promptFilePath);
134
151
  const remoteDir = path.dirname(promptFilePath);
135
152
  const chunks = chunkContent(content);
136
- if (agentOs === 'windows') {
153
+ // apra-fleet-7dir.5.4: the PowerShell branch below is shell-INDEPENDENT as a
154
+ // string (a single base64 `powershell -EncodedCommand` invocation, safe to
155
+ // run from bash too), so a gitbash member would survive it. It is routed to
156
+ // the POSIX branch anyway, so that one member class speaks exactly one shell
157
+ // end to end: the sibling deletePromptFile's PowerShell branch cannot clean
158
+ // up the durable stdout mirror (a POSIX /tmp path only bash resolves), and
159
+ // splitting write/delete across two shells for one member would be the
160
+ // harder invariant to keep true. The `cd "<folder>"` this branch emits is
161
+ // the same POSIX form LinuxCommands.buildAgentPromptCommand already uses for
162
+ // every gitbash dispatch, so it adds no new path-quoting exposure.
163
+ if (!isPosixShellMember(agent)) {
137
164
  const escapedFolder = escapeWindowsArg(remoteDir);
138
165
  for (let i = 0; i < chunks.length; i++) {
139
166
  const setup = i === 0 ? `New-Item -Path '${escapedFolder}' -ItemType Directory -Force | Out-Null; ` : '';
@@ -169,10 +196,13 @@ async function deletePromptFile(agent, strategy, promptFilePath, extraPaths = []
169
196
  }
170
197
  return;
171
198
  }
172
- const agentOs = getAgentOS(agent);
173
199
  const promptFileName = path.basename(promptFilePath);
174
200
  const remoteDir = path.dirname(promptFilePath);
175
- if (agentOs === 'windows') {
201
+ // apra-fleet-7dir.5.4: gitbash members take the POSIX branch, matching
202
+ // writePromptFile above -- and only that branch deletes `extraPaths` (the
203
+ // durable stdout mirror), which lives at a POSIX /tmp path PowerShell would
204
+ // resolve to a different directory entirely.
205
+ if (!isPosixShellMember(agent)) {
176
206
  const escapedFolder = escapeWindowsArg(remoteDir);
177
207
  const psScript = `Set-Location "${escapedFolder}"; Remove-Item "${promptFileName}" -Force -ErrorAction SilentlyContinue`;
178
208
  const encoded = Buffer.from(psScript, 'utf16le').toString('base64');
@@ -202,7 +232,6 @@ export function resolveModelForTier(agent, tier, provider) {
202
232
  * shared with member_detail (the fleet-sprint engine's only source for it).
203
233
  */
204
234
  export { knownRepoRemoteUrl };
205
- const SECURE_TOKEN_RE = /\{\{secure\.[a-zA-Z0-9_-]{1,64}\}\}/;
206
235
  /**
207
236
  * The sprint id this server process dispatches on behalf of, or undefined when
208
237
  * run outside a sprint (e.g. a manual cli.mjs invocation). Sourced from
@@ -311,7 +340,7 @@ async function findDeadLockPid(agent, workspaceId) {
311
340
  if (subprocessPid !== undefined) {
312
341
  const alive = agent.agentType === 'local'
313
342
  ? isPidAlive(subprocessPid)
314
- : await isRemoteProcessAlive(getStrategy(agent), subprocessPid, getAgentOS(agent));
343
+ : await isRemoteProcessAlive(getStrategy(agent), subprocessPid, getAgentOS(agent), getAgentShell(agent));
315
344
  if (!alive)
316
345
  return subprocessPid;
317
346
  }
@@ -423,8 +452,44 @@ async function executePromptInteractive(agent, renderedPrompt, input, workspaceI
423
452
  }
424
453
  }
425
454
  export async function executePrompt(input, extra) {
426
- if (SECURE_TOKEN_RE.test(input.prompt)) {
427
- return 'error: execute_prompt prompt contains {{secure.NAME}} token. Secrets must never be passed to LLM prompts. Use execute_command with {{secure.NAME}} instead.';
455
+ if (hasSecretToken(input.prompt)) {
456
+ return 'error: execute_prompt prompt contains {{secret.NAME}} token. Secrets must never be passed to LLM prompts. Use execute_command with {{secret.NAME}} instead.';
457
+ }
458
+ // apra-fleet-3swo.42: normalise `fork` ONCE, here, before any predicate is
459
+ // derived from it. Previously `forkRequested` (below) checked
460
+ // input.fork.length > 0 (untrimmed) while `explicitForkId` (further down)
461
+ // checked input.fork.trim().length > 0 -- for a whitespace-only fork id the
462
+ // two disagreed (forkRequested true, explicitForkId undefined), which
463
+ // silently routed a caller's explicit-but-invalid fork id into the
464
+ // fork===true best-effort path and could hand back a plain FRESH session
465
+ // with no error. Both forkRequested and explicitForkId are now derived from
466
+ // this single normalised value, so an all-whitespace or empty string can
467
+ // never disagree with itself. Trimming a boolean/undefined value is a
468
+ // no-op -- the ternary passes it through unchanged.
469
+ const forkArg = typeof input.fork === 'string' ? input.fork.trim() : input.fork;
470
+ // fork/resume mutual-exclusivity guard (apra-fleet-lmtg.4): fork branches a
471
+ // NEW session from an existing one, resume continues IN PLACE -- the two
472
+ // are semantically incompatible, so a call requesting both is rejected here,
473
+ // before any member resolution or LLM invocation, rather than silently
474
+ // preferring one. session_id is documented as pure resume shorthand, so its
475
+ // mere presence also conflicts with fork even when the `resume` field
476
+ // itself still holds its default. "Non-default resume" means any value
477
+ // other than the schema default `true` (i.e. `false`, or an explicit
478
+ // session-id string) -- default-true resume is left alone since fork mode
479
+ // resolution (next task) supersedes it.
480
+ // Deliberately NOT `forkArg.length > 0`: any STRING value of fork (including
481
+ // '' and whitespace-only, once trimmed to '') is a fork REQUEST -- just one
482
+ // whose explicit id turns out to be invalid (see explicitForkId below),
483
+ // rejected with a terminal session_not_found rather than silently treated
484
+ // as "no fork requested at all".
485
+ const forkRequested = forkArg === true || typeof forkArg === 'string';
486
+ if (forkRequested) {
487
+ if (input.session_id !== undefined) {
488
+ return 'error: execute_prompt cannot set both "fork" and "session_id" -- session_id is resume shorthand, and fork branches a new session instead of resuming. Specify only one.';
489
+ }
490
+ if (input.resume !== true) {
491
+ return 'error: execute_prompt cannot set both "fork" and a non-default "resume" -- fork branches a new session instead of resuming. Specify only one.';
492
+ }
428
493
  }
429
494
  // Validate substitution keys before any I/O or member resolution.
430
495
  if (input.substitutions !== undefined) {
@@ -527,938 +592,1214 @@ export async function executePrompt(input, extra) {
527
592
  // return immediately following) must release this lock explicitly, since
528
593
  // it now returns AFTER the lock is claimed instead of before.
529
594
  inFlightAgents.add(agent.id);
530
- // Peek at session state early so the preflight check can skip interactive
531
- // members whose dispatch routes through a live MCP push channel, not SSH.
532
- const earlyWorkspaceId = getTokenIssuer().workspaceId();
533
- const earlySession = sessionRegistry.get(earlyWorkspaceId, agent.id);
534
- const isChannelCapable = !!earlySession?.channelCapable;
535
- // Pre-dispatch readiness check (apra-fleet preflight-check): verify
536
- // connectivity and LLM auth BEFORE the expensive prompt dispatch
537
- // (writePromptFile + CLI invocation). Catches expired OAuth, missing
538
- // credentials, and offline members in <1s instead of burning a full
539
- // round trip. Local members and interactive sessions are excluded
540
- // (local shares this machine's credentials; interactive sessions have
541
- // their own liveness probes). The check is cached for 60s so
542
- // back-to-back dispatches do not add latency.
543
- if (agent.agentType !== 'local' && !isChannelCapable) {
544
- let preflight;
545
- try {
546
- preflight = await preflightCheck(agent);
547
- }
548
- catch (err) {
549
- // preflightCheck's own synchronous prologue (getStrategy/getProvider)
550
- // and its internal exec calls are not fully guarded -- if it throws
551
- // instead of resolving {ok: false}, the lock claimed above would
552
- // otherwise leak forever (no pid captured yet for findDeadLockPid's
553
- // stale-lock self-heal to recognize). Release and propagate unchanged
554
- // -- this preserves the exact same exception the caller would have
555
- // seen before the lock was claimed this early.
556
- inFlightAgents.delete(agent.id);
557
- throw err;
558
- }
559
- if (!preflight.ok) {
560
- // R2-F5: use preflight-specific reason codes so fleet-sprint can
561
- // distinguish pre-dispatch failures from in-dispatch ones and avoid
562
- // inappropriate self-heal loops (e.g. re-provisioning auth when the
563
- // member is simply offline).
564
- const preflightReason = preflight.code === 'offline' ? 'preflight_offline'
565
- : preflight.code === 'auth_expired' ? 'preflight_auth_expired'
566
- : preflight.code === 'auth_missing' ? 'preflight_auth_missing'
567
- : 'dispatch_failed';
568
- // Release the lock claimed above -- this return happens before the
569
- // interactive/subprocess split's own add+finally cleanup ever runs.
570
- inFlightAgents.delete(agent.id);
571
- return {
572
- text: `[FAIL] Pre-dispatch check failed for "${agent.friendlyName}": ${preflight.reason}`,
573
- structuredContent: {
574
- isError: true,
575
- reason: preflightReason,
576
- },
577
- };
595
+ // apra-fleet-c98q: if anything between this claim and a try/finally that
596
+ // owns the release throws (e.g. an SSH drop in writePromptFile), release
597
+ // the lock and stall entry here and rethrow. Body deliberately not
598
+ // reindented to keep this release fix minimal.
599
+ let claimGuardActive = true;
600
+ try {
601
+ // Peek at session state early so the preflight check can skip interactive
602
+ // members whose dispatch routes through a live MCP push channel, not SSH.
603
+ const earlyWorkspaceId = getTokenIssuer().workspaceId();
604
+ const earlySession = sessionRegistry.get(earlyWorkspaceId, agent.id);
605
+ const isChannelCapable = !!earlySession?.channelCapable;
606
+ // Pre-dispatch readiness check (apra-fleet preflight-check): verify
607
+ // connectivity and LLM auth BEFORE the expensive prompt dispatch
608
+ // (writePromptFile + CLI invocation). Catches expired OAuth, missing
609
+ // credentials, and offline members in <1s instead of burning a full
610
+ // round trip. Local members and interactive sessions are excluded
611
+ // (local shares this machine's credentials; interactive sessions have
612
+ // their own liveness probes). The check is cached for 60s so
613
+ // back-to-back dispatches do not add latency.
614
+ if (agent.agentType !== 'local' && !isChannelCapable) {
615
+ let preflight;
616
+ try {
617
+ preflight = await preflightCheck(agent);
618
+ }
619
+ catch (err) {
620
+ // preflightCheck's own synchronous prologue (getStrategy/getProvider)
621
+ // and its internal exec calls are not fully guarded -- if it throws
622
+ // instead of resolving {ok: false}, the lock claimed above would
623
+ // otherwise leak forever (no pid captured yet for findDeadLockPid's
624
+ // stale-lock self-heal to recognize). Release and propagate unchanged
625
+ // -- this preserves the exact same exception the caller would have
626
+ // seen before the lock was claimed this early.
627
+ inFlightAgents.delete(agent.id);
628
+ throw err;
629
+ }
630
+ if (!preflight.ok) {
631
+ // R2-F5: use preflight-specific reason codes so fleet-sprint can
632
+ // distinguish pre-dispatch failures from in-dispatch ones and avoid
633
+ // inappropriate self-heal loops (e.g. re-provisioning auth when the
634
+ // member is simply offline).
635
+ const preflightReason = preflight.code === 'offline' ? 'preflight_offline'
636
+ : preflight.code === 'auth_expired' ? 'preflight_auth_expired'
637
+ : preflight.code === 'auth_missing' ? 'preflight_auth_missing'
638
+ : 'dispatch_failed';
639
+ // Release the lock claimed above -- this return happens before the
640
+ // interactive/subprocess split's own add+finally cleanup ever runs.
641
+ inFlightAgents.delete(agent.id);
642
+ return {
643
+ text: `[FAIL] Pre-dispatch check failed for "${agent.friendlyName}": ${preflight.reason}`,
644
+ structuredContent: {
645
+ isError: true,
646
+ reason: preflightReason,
647
+ },
648
+ };
649
+ }
578
650
  }
579
- }
580
- // Interactive routing (apra-fleet-2xs.8/us9.8, docs/cloud-fleet-architecture.md
581
- // section 6): if this member has a live MCP session connected right now,
582
- // route via send_message + wait-for-response instead of spawning a
583
- // subprocess. Decided tier-2-locally against THIS machine's session
584
- // registry only (never caller/hub-side state, per apra-fleet-2xs.8's own
585
- // scope note) -- so behavior is unaffected by whether execute_prompt is
586
- // invoked directly (Phase 1) or relayed through a future hub. Falls
587
- // through to the unchanged subprocess/SSH path below for every member
588
- // without a live session (the common case today, and always for members
589
- // that never opt into an interactive session).
590
- //
591
- // Gated by capability, not provider name (apra-fleet-cqa, eft.74 follow-up):
592
- // mode (b) -- server-push mid-session prompt injection -- was POC-proven on
593
- // Claude via the provider-branded `notifications/claude/channel` capability
594
- // (apra-fleet-us9.9's survey, docs/interactive-injection-provider-survey.md),
595
- // but the routing decision itself must be provider-agnostic: whatever the
596
- // provider, a session is only an interactive-routing candidate if it
597
- // actually declared that capability at MCP initialize time (recorded as
598
- // SessionState.channelCapable below). Gemini/Codex are confirmed [FAIL]
599
- // today (no equivalent push mechanism) and so never end up channelCapable in
600
- // practice, but that is a fact about what each provider adapter currently
601
- // advertises, not a name-based pre-filter here -- any provider that
602
- // implements the same MCP channel capability is picked up automatically. A
603
- // member CAN still have a live sessionRegistry entry (registerMcpEndpoint
604
- // gives it basic MCP tool access, apra-fleet-fnz.1-3) without that meaning
605
- // it can receive or act on this push -- routing to it anyway would silently
606
- // spend the full timeout_s waiting for a response that can never arrive.
607
- // R2-F3: re-query session registry after the preflight await (10-20s) so
608
- // interactive routing sees sessions that became channelCapable during that
609
- // window, rather than using the stale pre-preflight snapshot.
610
- const workspaceId = getTokenIssuer().workspaceId();
611
- const rawSession = sessionRegistry.get(workspaceId, agent.id);
612
- // apra-fleet-eft.74.1: interactive routing requires the EXPLICIT channel
613
- // opt-in handshake, not mere JWT registration. A plain subprocess
614
- // connect-back (a Doer that opened an MCP tool-access session with a member
615
- // JWT but never declared the `claude/channel` capability) registers a live
616
- // `server` here, yet can never receive the `notifications/claude/channel`
617
- // push -- routing to it would enqueue a message nothing reads and burn the
618
- // full timeout_s on every later dispatch (the eft.74 wedge). Only a
619
- // channel-capable session is an interactive-routing candidate; anything else
620
- // (including that Doer's live tool session, which must be left untouched)
621
- // falls through to the unchanged subprocess path below.
622
- let interactiveSession = rawSession?.channelCapable ? rawSession : undefined;
623
- // apra-fleet-eft.50.1: resolve the pid to test FRESH on every dispatch
624
- // (never cached from a prior attempt) and fall back to the durable
625
- // launch-pid anchor when this reused session lost its own pid on a
626
- // reconnect. This is what re-arms the dead-session guard on a retry attempt
627
- // 2+ exactly as on attempt 1: the specific eft.50 ordering (attempt 1 fails
628
- // clean, attempt 2 targets a now-dead reconnected session) used to slip
629
- // through here because the reconnected SessionState had pid=undefined, so the
630
- // check below was skipped and the caller hung on the dead channel.
631
- const interactivePid = interactiveSession?.pid
632
- ?? sessionRegistry.lastKnownPid(workspaceId, agent.id);
633
- if (interactiveSession?.server && interactivePid !== undefined && !isPidAlive(interactivePid)) {
634
- // apra-fleet-eft.28.1/eft.28.5: never reuse a persistent interactive
635
- // session whose underlying member claude process has already died. Before
636
- // eft.28.1, a dead launch-time process (e.g. it crashed before ever
637
- // producing a plan) left a `server` entry in sessionRegistry that looked
638
- // reusable -- send_message would happily enqueue to it, but nothing would
639
- // ever call respond_to_message, so the caller silently burned the full
640
- // timeout_s (observed up to 3600s in apra-fleet-eft.28) with zero
641
- // fleet-server log output and no watchdog coverage.
642
- //
643
- // eft.28.5 changes what happens once the death is detected: instead of
644
- // surfacing a terminal dispatch_failed error that forces a manual
645
- // register_member, EVICT the dead session and FALL THROUGH to a fresh
646
- // non-interactive (subprocess) dispatch below -- i.e. re-dispatch fresh
647
- // instead of blocking on waitForInteractiveResponse. The bug in
648
- // apra-fleet-eft.28 was precisely that a dead session was reused "rather
649
- // than detecting its death and spawning a fresh dispatch"; this does the
650
- // spawning. If the fresh subprocess dispatch itself cannot start it
651
- // returns its own terminal error, so nothing ever hangs.
652
- //
653
- // The liveness check now fires for connect-back interactive sessions too:
654
- // http-transport carries the launch-time pid forward across re-registration
655
- // (eft.28.5), so `pid` is no longer undefined for a member that registered
656
- // via register_member and then connected back -- the exact real-fleet
657
- // repro that evaded eft.28.1.
651
+ // Interactive routing (apra-fleet-2xs.8/us9.8, docs/cloud-fleet-architecture.md
652
+ // section 6): if this member has a live MCP session connected right now,
653
+ // route via send_message + wait-for-response instead of spawning a
654
+ // subprocess. Decided tier-2-locally against THIS machine's session
655
+ // registry only (never caller/hub-side state, per apra-fleet-2xs.8's own
656
+ // scope note) -- so behavior is unaffected by whether execute_prompt is
657
+ // invoked directly (Phase 1) or relayed through a future hub. Falls
658
+ // through to the unchanged subprocess/SSH path below for every member
659
+ // without a live session (the common case today, and always for members
660
+ // that never opt into an interactive session).
658
661
  //
659
- // apra-fleet-eft.50.1: eft.28.5's carry-forward still lost the pid when a
660
- // reconnect happened AFTER the prior SessionState was already unregistered
661
- // (priorPid lookup found nothing), so a retry attempt 2+ reused a
662
- // pid=undefined session and hung. `interactivePid` above now back-stops
663
- // that with sessionRegistry.lastKnownPid, the durable per-member launch-pid
664
- // anchor, so this guard re-arms on EVERY dispatch attempt that reuses an
665
- // interactive session, not just the first. It stays undefined only for
666
- // sessions that never had a captured PID at all (e.g. tests, or a provider
667
- // that never went through register_member's local spawn path); those are
668
- // left to the pre-existing interactive behavior, unchanged.
669
- const deadScope = new LogScope('execute_prompt', `[interactive] session liveness check pid=${interactivePid}`, agent);
670
- sessionRegistry.unregister(workspaceId, agent.id);
671
- deadScope.info(`member claude process (pid ${interactivePid}) for "${agent.friendlyName}" is dead -- evicting the stale interactive session and re-dispatching fresh (non-interactive)`);
672
- interactiveSession = undefined;
673
- }
674
- if (interactiveSession?.server) {
675
- // Lock already claimed above, before the preflight await -- do not
676
- // re-add here (Set.add would be a harmless no-op, but keeping a second
677
- // add site invites the lock and its release to drift out of sync).
678
- writeStatusline(new Map([[agent.id, 'busy']]));
679
- try {
680
- return await executePromptInteractive(agent, renderedPrompt, input, workspaceId, heuristicWarningSuffix);
662
+ // Gated by capability, not provider name (apra-fleet-cqa, eft.74 follow-up):
663
+ // mode (b) -- server-push mid-session prompt injection -- was POC-proven on
664
+ // Claude via the provider-branded `notifications/claude/channel` capability
665
+ // (apra-fleet-us9.9's survey, docs/interactive-injection-provider-survey.md),
666
+ // but the routing decision itself must be provider-agnostic: whatever the
667
+ // provider, a session is only an interactive-routing candidate if it
668
+ // actually declared that capability at MCP initialize time (recorded as
669
+ // SessionState.channelCapable below). Codex is confirmed [FAIL]
670
+ // today (no equivalent push mechanism) and so never ends up channelCapable in
671
+ // practice, but that is a fact about what each provider adapter currently
672
+ // advertises, not a name-based pre-filter here -- any provider that
673
+ // implements the same MCP channel capability is picked up automatically. A
674
+ // member CAN still have a live sessionRegistry entry (registerMcpEndpoint
675
+ // gives it basic MCP tool access, apra-fleet-fnz.1-3) without that meaning
676
+ // it can receive or act on this push -- routing to it anyway would silently
677
+ // spend the full timeout_s waiting for a response that can never arrive.
678
+ // R2-F3: re-query session registry after the preflight await (10-20s) so
679
+ // interactive routing sees sessions that became channelCapable during that
680
+ // window, rather than using the stale pre-preflight snapshot.
681
+ const workspaceId = getTokenIssuer().workspaceId();
682
+ const rawSession = sessionRegistry.get(workspaceId, agent.id);
683
+ // apra-fleet-eft.74.1: interactive routing requires the EXPLICIT channel
684
+ // opt-in handshake, not mere JWT registration. A plain subprocess
685
+ // connect-back (a Doer that opened an MCP tool-access session with a member
686
+ // JWT but never declared the `claude/channel` capability) registers a live
687
+ // `server` here, yet can never receive the `notifications/claude/channel`
688
+ // push -- routing to it would enqueue a message nothing reads and burn the
689
+ // full timeout_s on every later dispatch (the eft.74 wedge). Only a
690
+ // channel-capable session is an interactive-routing candidate; anything else
691
+ // (including that Doer's live tool session, which must be left untouched)
692
+ // falls through to the unchanged subprocess path below.
693
+ let interactiveSession = rawSession?.channelCapable ? rawSession : undefined;
694
+ // apra-fleet-eft.50.1: resolve the pid to test FRESH on every dispatch
695
+ // (never cached from a prior attempt) and fall back to the durable
696
+ // launch-pid anchor when this reused session lost its own pid on a
697
+ // reconnect. This is what re-arms the dead-session guard on a retry attempt
698
+ // 2+ exactly as on attempt 1: the specific eft.50 ordering (attempt 1 fails
699
+ // clean, attempt 2 targets a now-dead reconnected session) used to slip
700
+ // through here because the reconnected SessionState had pid=undefined, so the
701
+ // check below was skipped and the caller hung on the dead channel.
702
+ const interactivePid = interactiveSession?.pid
703
+ ?? sessionRegistry.lastKnownPid(workspaceId, agent.id);
704
+ if (interactiveSession?.server && interactivePid !== undefined && !isPidAlive(interactivePid)) {
705
+ // apra-fleet-eft.28.1/eft.28.5: never reuse a persistent interactive
706
+ // session whose underlying member claude process has already died. Before
707
+ // eft.28.1, a dead launch-time process (e.g. it crashed before ever
708
+ // producing a plan) left a `server` entry in sessionRegistry that looked
709
+ // reusable -- send_message would happily enqueue to it, but nothing would
710
+ // ever call respond_to_message, so the caller silently burned the full
711
+ // timeout_s (observed up to 3600s in apra-fleet-eft.28) with zero
712
+ // fleet-server log output and no watchdog coverage.
713
+ //
714
+ // eft.28.5 changes what happens once the death is detected: instead of
715
+ // surfacing a terminal dispatch_failed error that forces a manual
716
+ // register_member, EVICT the dead session and FALL THROUGH to a fresh
717
+ // non-interactive (subprocess) dispatch below -- i.e. re-dispatch fresh
718
+ // instead of blocking on waitForInteractiveResponse. The bug in
719
+ // apra-fleet-eft.28 was precisely that a dead session was reused "rather
720
+ // than detecting its death and spawning a fresh dispatch"; this does the
721
+ // spawning. If the fresh subprocess dispatch itself cannot start it
722
+ // returns its own terminal error, so nothing ever hangs.
723
+ //
724
+ // The liveness check now fires for connect-back interactive sessions too:
725
+ // http-transport carries the launch-time pid forward across re-registration
726
+ // (eft.28.5), so `pid` is no longer undefined for a member that registered
727
+ // via register_member and then connected back -- the exact real-fleet
728
+ // repro that evaded eft.28.1.
729
+ //
730
+ // apra-fleet-eft.50.1: eft.28.5's carry-forward still lost the pid when a
731
+ // reconnect happened AFTER the prior SessionState was already unregistered
732
+ // (priorPid lookup found nothing), so a retry attempt 2+ reused a
733
+ // pid=undefined session and hung. `interactivePid` above now back-stops
734
+ // that with sessionRegistry.lastKnownPid, the durable per-member launch-pid
735
+ // anchor, so this guard re-arms on EVERY dispatch attempt that reuses an
736
+ // interactive session, not just the first. It stays undefined only for
737
+ // sessions that never had a captured PID at all (e.g. tests, or a provider
738
+ // that never went through register_member's local spawn path); those are
739
+ // left to the pre-existing interactive behavior, unchanged.
740
+ const deadScope = new LogScope('execute_prompt', `[interactive] session liveness check pid=${interactivePid}`, agent);
741
+ sessionRegistry.unregister(workspaceId, agent.id);
742
+ deadScope.info(`member claude process (pid ${interactivePid}) for "${agent.friendlyName}" is dead -- evicting the stale interactive session and re-dispatching fresh (non-interactive)`);
743
+ interactiveSession = undefined;
681
744
  }
682
- finally {
683
- inFlightAgents.delete(agent.id);
684
- writeStatusline(new Map([[agent.id, 'idle']]));
745
+ if (interactiveSession?.server) {
746
+ // Lock already claimed above, before the preflight await -- do not
747
+ // re-add here (Set.add would be a harmless no-op, but keeping a second
748
+ // add site invites the lock and its release to drift out of sync).
749
+ writeStatusline(new Map([[agent.id, 'busy']]));
750
+ claimGuardActive = false;
751
+ try {
752
+ return await executePromptInteractive(agent, renderedPrompt, input, workspaceId, heuristicWarningSuffix);
753
+ }
754
+ finally {
755
+ inFlightAgents.delete(agent.id);
756
+ writeStatusline(new Map([[agent.id, 'idle']]));
757
+ }
685
758
  }
686
- }
687
- // Lock already claimed above, before the preflight await.
688
- await ensureAgentFilesProvisioned(agent);
689
- const stallDetector = getStallDetector();
690
- let clearedByStall = false;
691
- // apra-fleet-3c9.1: a CONFIRMED stall must not only kill the remote pid but
692
- // also cancel the in-flight strategy.execCommand() promise. Before this, the
693
- // client kept waiting out its full deriveTimeoutMs deadline after the
694
- // server-side work had already died (the 60.5-min hung dispatch in
695
- // apra-fleet-3c9). onStall aborts this controller; its signal is merged into
696
- // the signal handed to every execCommand below (see dispatchSignal), so a
697
- // confirmed stall settles the pending dispatch immediately and surfaces a
698
- // typed 'stalled' error instead of hanging.
699
- const stallAbortController = new AbortController();
700
- stallDetector.add(agent.id, {
701
- sessionId: null,
702
- logFilePath: null,
703
- lastActivityAt: Date.now(),
704
- consecutiveIdleCycles: 0,
705
- consecutiveReadFailures: 0,
706
- memberId: agent.id,
707
- memberName: agent.friendlyName,
708
- provisional: true,
709
- stallReported: false,
710
- onStall: () => {
711
- // Stall detector already wrote 'unknown' to the statusline before calling here.
712
- // Our job: clear in-process state so the member can accept new calls.
713
- // clearedByStall prevents the eventually-resolving finally block from clobbering
714
- // a new execute_prompt that may have already claimed the member.
715
- inFlightAgents.delete(agent.id);
716
- clearedByStall = true;
717
- // apra-fleet-6z8.2: a CONFIRMED stall means the remote turn made no
718
- // progress of any kind for the whole threshold. Clearing bookkeeping
719
- // alone left that wedged process running indefinitely on the member --
720
- // burning its LLM session, holding its work folder, and colliding with
721
- // whatever dispatch takes the member next. Kill the tracked pid too.
722
- // Best-effort and never awaited: onStall is a fire-and-forget callback
723
- // from the poll loop, and tryKillPid already swallows its own errors.
724
- void tryKillPid(agent, strategy, cmds).catch(() => { });
725
- // apra-fleet-3c9.1: killing the remote pid alone left the pending
726
- // execCommand promise still awaiting its full deadline. Abort it now so
727
- // the dispatch settles promptly and returns a typed 'stalled' error.
759
+ // Lock already claimed above, before the preflight await.
760
+ // AGY: every dispatch is bound to the member's own agy project with
761
+ // --project; without it agy silently runs under the machine-wide
762
+ // default-cli-project. A member without a verified project (registered
763
+ // before project binding, or whose project file is gone/corrupt) gets one
764
+ // here. Failure is terminal -- never a dispatch without --project.
765
+ let agyProjectId;
766
+ if (agent.llmProvider === 'agy') {
728
767
  try {
729
- stallAbortController.abort();
768
+ agyProjectId = (await ensureAgyProject(agent)).projectId;
769
+ }
770
+ catch (e) {
771
+ inFlightAgents.delete(agent.id);
772
+ writeStatusline(new Map([[agent.id, 'idle']]));
773
+ return {
774
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}" rejected -- the member's agy project could not be provisioned: ${e?.message ?? String(e)}. No LLM call was made.`,
775
+ structuredContent: { isError: true, reason: 'dispatch_failed' },
776
+ };
730
777
  }
731
- catch { /* best-effort */ }
732
- },
733
- });
734
- const tmpDir = agent.agentType === 'local' ? os.tmpdir() : '/tmp';
735
- const resolvedWorkFolder = agent.agentType === 'local' ? resolveTilde(agent.workFolder) : agent.workFolder;
736
- const promptFilePath = agent.agentType === 'local'
737
- ? path.join(resolvedWorkFolder, promptFileName)
738
- : `${resolvedWorkFolder}/${promptFileName}`;
739
- const strategy = getStrategy(agent);
740
- const cmds = getOsCommands(getAgentOS(agent));
741
- const provider = getProvider(agent.llmProvider);
742
- const authPrefix = buildAuthEnvPrefix(agent, getAgentOS(agent));
743
- const tiers = provider.modelTiers();
744
- let resolvedModel = input.model || 'standard';
745
- let resolvedTier;
746
- if (resolvedModel === 'cheap') {
747
- resolvedTier = 'cheap';
748
- resolvedModel = agent.modelTiers
749
- ? resolveModelForTier(agent, 'cheap', provider)
750
- : agent.modelCheap || getModelOverride(provider.name, 'cheap') || tiers.cheap;
751
- }
752
- else if (resolvedModel === 'standard') {
753
- resolvedTier = 'standard';
754
- resolvedModel = agent.modelTiers
755
- ? resolveModelForTier(agent, 'standard', provider)
756
- : agent.modelStandard || getModelOverride(provider.name, 'standard') || tiers.standard;
757
- }
758
- else if (resolvedModel === 'premium') {
759
- resolvedTier = 'premium';
760
- resolvedModel = agent.modelTiers
761
- ? resolveModelForTier(agent, 'premium', provider)
762
- : agent.modelPremium || getModelOverride(provider.name, 'premium') || tiers.premium;
763
- }
764
- else {
765
- resolvedModel = tiers[resolvedModel] ?? resolvedModel;
766
- }
767
- const scope = new LogScope('execute_prompt', `[${resolvedModel}] resume=${input.resume} timeout=${input.timeout_s ?? 300}s ${truncateForLog(maskSecrets(input.prompt), getLogPreviewChars())}`, agent);
768
- // Resume semantics (apra-fleet-eft.78.1). `resume` is boolean | string:
769
- // - true -> best-effort resume of the member's stored last session; a
770
- // stale/unknown stored session transparently retries fresh.
771
- // - false -> always a fresh session.
772
- // - string -> EXPLICIT session-id resume: resume exactly this id, preferring
773
- // it over agent.sessionId. The caller asserts the prompt depends
774
- // on that session's context, so an unknown/expired id is a
775
- // TERMINAL session_not_found (handled just below) and NO
776
- // fresh-session fallback is ever applied (see the retry paths).
777
- const explicitResumeId = (typeof input.session_id === 'string' && input.session_id.trim().length > 0)
778
- ? input.session_id.trim()
779
- : (typeof input.resume === 'string' && input.resume.length > 0 ? input.resume : undefined);
780
- const resumeRequested = input.resume === true || explicitResumeId !== undefined;
781
- const resumeTargetId = explicitResumeId ?? agent.sessionId;
782
- // An explicit-id resume must never silently degrade to a fresh session: that
783
- // is exactly the wrong-context dispatch this feature forbids. resume=true and
784
- // resume=false keep their pre-existing transparent recovery.
785
- const allowFreshSessionFallback = explicitResumeId === undefined;
786
- const resuming = !!(resumeRequested && resumeTargetId && provider.supportsResume());
787
- const isCallerMinted = provider.sessionIdStrategy().type === 'caller-minted';
788
- const mintedId = isCallerMinted
789
- ? (resuming ? resumeTargetId : uuid())
790
- : (resuming ? resumeTargetId : undefined);
791
- // Terminal session-not-found gate for explicit-id resumes (apra-fleet-eft.78.1).
792
- // Checked BEFORE any spawn (writePromptFile / the LLM invocation): if the
793
- // caller named a session the server has never issued for this member -- and it
794
- // is not the member's currently-stored session -- there is no context to
795
- // resume. Reject with a structured session_not_found and make NO LLM call,
796
- // so an orchestrator can rebuild a self-contained prompt and re-dispatch fresh
797
- // deliberately, rather than getting a silent blank-session response.
798
- if (explicitResumeId !== undefined) {
799
- const resumable = provider.supportsResume()
800
- && (isKnownSession(agent.id, explicitResumeId) || explicitResumeId === agent.sessionId);
801
- if (!resumable) {
802
- scope.abort(`explicit resume rejected -- session "${explicitResumeId}" is unknown/expired (no LLM call)`);
803
- inFlightAgents.delete(agent.id);
804
- stallDetector.remove(agent.id);
805
- writeStatusline(new Map([[agent.id, 'idle']]));
806
- return {
807
- text: `[FAIL] execute_prompt on "${agent.friendlyName}" rejected -- session "${explicitResumeId}" cannot be resumed (unknown or expired). No LLM call was made. Rebuild the context and re-dispatch with a full, self-contained prompt (resume=false), or resume=true for best-effort recovery.`,
808
- structuredContent: { isError: true, reason: 'session_not_found', sessionId: explicitResumeId },
809
- };
810
778
  }
811
- }
812
- const promptOpts = {
813
- folder: resolvedWorkFolder,
814
- promptFile: promptFileName,
815
- sessionId: mintedId,
816
- resuming,
817
- unattended: agent.unattended,
818
- model: resolvedModel,
819
- tier: resolvedTier,
820
- maxTurns: input.max_turns,
821
- inv: scope.getInv(),
822
- agentName: input.agent,
823
- };
824
- // apra-fleet issue #390: session log paths live on the MEMBER's machine, under
825
- // the MEMBER's home directory, joined with the MEMBER's OS convention. Before
826
- // this, every remote member got a HUB-home path (os.homedir()) joined with the
827
- // HUB's path convention -- a path that can never exist on the member, which
828
- // silently disabled stall detection for Claude/Gemini and manufactured
829
- // false-positive stall kills for AGY/OpenCode.
830
- //
831
- // This resolution is deliberately SYNCHRONOUS (cached probe result, else the
832
- // member's known login username's default home): the dispatch path must not
833
- // add a remote round trip, and a wrong guess here can only cost detection
834
- // fidelity, never cause a kill. The kill-capable directory poll in
835
- // stall-poller.ts uses the probe-backed async resolver instead.
836
- const memberPathCtx = getCachedMemberPathContext(agent);
837
- const activePreSpawnSid = resuming ? resumeTargetId : (isCallerMinted ? mintedId : undefined);
838
- let resolvedLogPath = null;
839
- if (activePreSpawnSid) {
840
- try {
841
- resolvedLogPath = resolveSessionLogPath(agent.llmProvider ?? 'claude', activePreSpawnSid, resolvedWorkFolder, memberPathCtx.homeDir, memberPathCtx.targetOs);
779
+ await ensureAgentFilesProvisioned(agent);
780
+ const stallDetector = getStallDetector();
781
+ let clearedByStall = false;
782
+ // apra-fleet-3c9.1: a CONFIRMED stall must not only kill the remote pid but
783
+ // also cancel the in-flight strategy.execCommand() promise. Before this, the
784
+ // client kept waiting out its full deriveTimeoutMs deadline after the
785
+ // server-side work had already died (the 60.5-min hung dispatch in
786
+ // apra-fleet-3c9). onStall aborts this controller; its signal is merged into
787
+ // the signal handed to every execCommand below (see dispatchSignal), so a
788
+ // confirmed stall settles the pending dispatch immediately and surfaces a
789
+ // typed 'stalled' error instead of hanging.
790
+ const stallAbortController = new AbortController();
791
+ // apra-fleet-25yl.1.2: input.timeout_s is the real per-dispatch stall
792
+ // baseline now, not merely an inactivity kill on stdout/stderr -- see the
793
+ // schema description on `timeout_s` above. A caller that omits timeout_s
794
+ // gets a 300s baseline (the schema default), a deliberate change from the
795
+ // previously silent 150s DEFAULT_STALL_THRESHOLD_MS fallback.
796
+ const stallThresholdMs = (input.timeout_s ?? 300) * 1000;
797
+ stallDetector.add(agent.id, {
798
+ sessionId: null,
799
+ logFilePath: null,
800
+ lastActivityAt: Date.now(),
801
+ consecutiveIdleCycles: 0,
802
+ consecutiveReadFailures: 0,
803
+ memberId: agent.id,
804
+ memberName: agent.friendlyName,
805
+ provisional: true,
806
+ stallReported: false,
807
+ thresholdMs: stallThresholdMs,
808
+ onStall: () => {
809
+ // Stall detector already wrote 'unknown' to the statusline before calling here.
810
+ // Our job: clear in-process state so the member can accept new calls.
811
+ // clearedByStall prevents the eventually-resolving finally block from clobbering
812
+ // a new execute_prompt that may have already claimed the member.
813
+ inFlightAgents.delete(agent.id);
814
+ clearedByStall = true;
815
+ claimGuardActive = false;
816
+ // apra-fleet-6z8.2: a CONFIRMED stall means the remote turn made no
817
+ // progress of any kind for the whole threshold. Clearing bookkeeping
818
+ // alone left that wedged process running indefinitely on the member --
819
+ // burning its LLM session, holding its work folder, and colliding with
820
+ // whatever dispatch takes the member next. Kill the tracked pid too.
821
+ // Best-effort and never awaited: onStall is a fire-and-forget callback
822
+ // from the poll loop, and tryKillPid already swallows its own errors.
823
+ void tryKillPid(agent, strategy, cmds).catch(() => { });
824
+ // apra-fleet-3c9.1: killing the remote pid alone left the pending
825
+ // execCommand promise still awaiting its full deadline. Abort it now so
826
+ // the dispatch settles promptly and returns a typed 'stalled' error.
827
+ try {
828
+ stallAbortController.abort();
829
+ }
830
+ catch { /* best-effort */ }
831
+ },
832
+ });
833
+ const tmpDir = agent.agentType === 'local' ? os.tmpdir() : '/tmp';
834
+ const resolvedWorkFolder = agent.agentType === 'local' ? resolveTilde(agent.workFolder) : agent.workFolder;
835
+ const promptFilePath = agent.agentType === 'local'
836
+ ? path.join(resolvedWorkFolder, promptFileName)
837
+ : `${resolvedWorkFolder}/${promptFileName}`;
838
+ const strategy = getStrategy(agent);
839
+ const cmds = getOsCommands(getAgentOS(agent), getAgentShell(agent));
840
+ const provider = getProvider(agent.llmProvider);
841
+ const authPrefix = buildAuthEnvPrefix(agent, getAgentOS(agent));
842
+ const tiers = provider.modelTiers();
843
+ let resolvedModel = input.model || 'standard';
844
+ let resolvedTier;
845
+ if (resolvedModel === 'cheap') {
846
+ resolvedTier = 'cheap';
847
+ resolvedModel = agent.modelTiers
848
+ ? resolveModelForTier(agent, 'cheap', provider)
849
+ : agent.modelCheap || getModelOverride(provider.name, 'cheap') || tiers.cheap;
842
850
  }
843
- catch {
844
- resolvedLogPath = null;
851
+ else if (resolvedModel === 'standard') {
852
+ resolvedTier = 'standard';
853
+ resolvedModel = agent.modelTiers
854
+ ? resolveModelForTier(agent, 'standard', provider)
855
+ : agent.modelStandard || getModelOverride(provider.name, 'standard') || tiers.standard;
845
856
  }
846
- }
847
- stallDetector.update(agent.id, {
848
- sessionId: activePreSpawnSid,
849
- logFilePath: resolvedLogPath,
850
- provisional: !resolvedLogPath,
851
- });
852
- const claudeCmd = authPrefix + cmds.buildAgentPromptCommand(provider, promptOpts);
853
- // apra-fleet-6z8.1: the per-invocation durable stdout mirror the unix prompt
854
- // wrapper tees to (see durableOutputPath / buildAgentPromptCommand). Windows
855
- // members have no such companion tee, so recovery is skipped for them.
856
- const durablePath = getAgentOS(agent) === 'windows' ? undefined : durableOutputPath(scope.getInv());
857
- const dispatchStartedAt = Date.now();
858
- const timeoutMs = (input.timeout_s ?? 300) * 1000;
859
- const maxTotalMs = input.max_total_s !== undefined ? input.max_total_s * 1000 : undefined;
860
- // apra-fleet-y8q.1: every retry below (dispatch-exception, stale-session,
861
- // server-overloaded) re-dispatches with a FRESH session but used to reuse the
862
- // SAME full timeoutMs/maxTotalMs as the original attempt -- so a single
863
- // dispatch could burn up to ~2x max_total_s server-side (original attempt +
864
- // one full-budget retry), well past what the client's deriveTimeoutMs()
865
- // (packages/apra-fleet-client/src/client/api.mjs) budgets for the whole
866
- // tools/call (max_total_s*1000 + a fixed grace margin). That let the
867
- // client's hard timeout fire before the server's own retry-and-report path
868
- // ever got a chance, hiding a clean typed server error behind a raw client
869
- // transport timeout. Share ONE deadline budget across the original attempt
870
- // and any single retry: cap a retry's maxTotalMs (and its inactivity
871
- // timeoutMs, so it can't independently outlast the shared ceiling) to
872
- // whatever remains of max_total_s since dispatchStartedAt, and skip the
873
- // retry entirely once that budget is exhausted -- so total wall-clock time
874
- // for this call never exceeds max_total_s, which is exactly what the client
875
- // is prepared to wait for. When max_total_s is absent there is no hard
876
- // ceiling to share, so retries keep their full timeout_s (unchanged,
877
- // pre-existing behavior).
878
- function retryBudget() {
879
- if (maxTotalMs === undefined)
880
- return { timeoutMs, maxTotalMs: undefined, exhausted: false };
881
- const remaining = Math.max(0, maxTotalMs - (Date.now() - dispatchStartedAt));
882
- return { timeoutMs: Math.min(timeoutMs, remaining), maxTotalMs: remaining, exhausted: remaining <= 0 };
883
- }
884
- // Agent file validation -- verify named agent exists before any CLI invocation
885
- if (input.agent) {
886
- const dirs = provider.agentDirectories(input.agent);
887
- let agentFound = false;
888
- if (agent.agentType === 'local') {
889
- const projPath = path.join(resolvedWorkFolder, dirs.project);
890
- const userPath = path.join(os.homedir(), dirs.home);
891
- agentFound = fs.existsSync(projPath) || fs.existsSync(userPath);
892
- if (!agentFound) {
857
+ else if (resolvedModel === 'premium') {
858
+ resolvedTier = 'premium';
859
+ resolvedModel = agent.modelTiers
860
+ ? resolveModelForTier(agent, 'premium', provider)
861
+ : agent.modelPremium || getModelOverride(provider.name, 'premium') || tiers.premium;
862
+ }
863
+ else {
864
+ resolvedModel = tiers[resolvedModel] ?? resolvedModel;
865
+ }
866
+ const scope = new LogScope('execute_prompt', `[${resolvedModel}] resume=${input.resume} fork=${input.fork} timeout=${input.timeout_s ?? 300}s ${truncateForLog(maskSecrets(input.prompt), getLogPreviewChars())}`, agent);
867
+ // Resume semantics (apra-fleet-eft.78.1). `resume` is boolean | string:
868
+ // - true -> best-effort resume of the member's stored last session; a
869
+ // stale/unknown stored session transparently retries fresh.
870
+ // - false -> always a fresh session.
871
+ // - string -> EXPLICIT session-id resume: resume exactly this id, preferring
872
+ // it over agent.sessionId. The caller asserts the prompt depends
873
+ // on that session's context, so an unknown/expired id is a
874
+ // TERMINAL session_not_found (handled just below) and NO
875
+ // fresh-session fallback is ever applied (see the retry paths).
876
+ const explicitResumeId = (typeof input.session_id === 'string' && input.session_id.trim().length > 0)
877
+ ? input.session_id.trim()
878
+ : (typeof input.resume === 'string' && input.resume.length > 0 ? input.resume : undefined);
879
+ // Fork semantics (apra-fleet-lmtg.5) mirror resume's SHAPE but BRANCH instead
880
+ // of continuing in place. `fork` is boolean | string:
881
+ // - true -> best-effort fork of the member's stored last session; a
882
+ // stale/unknown stored session logs a warning and falls back to a
883
+ // plain FRESH session (analogous to resume=true), never a hard error.
884
+ // - string -> EXPLICIT fork of exactly that source id -- an unknown/expired
885
+ // source is a TERMINAL session_not_found (like an explicit resume).
886
+ // The mutual-exclusivity guard above only lets fork through with resume at its
887
+ // DEFAULT (true), so fork must SUPERSEDE that default resume here: a fork
888
+ // request forces resuming off so the dispatch mints a fresh distinct output
889
+ // session id instead of continuing the stored one in place.
890
+ // apra-fleet-3swo.42: derived from the SAME normalised forkArg the top-of-
891
+ // function mutual-exclusivity guard computed forkRequested from (no second,
892
+ // independently-trimmed copy of the rule). Deliberately NOT gated on
893
+ // `.length > 0`: an explicit fork string that trims to '' (fork: '' or
894
+ // fork: ' ') must still be an EXPLICIT id -- just an invalid one -- so it
895
+ // takes the explicit-id branch below (terminal session_not_found, no LLM
896
+ // call) instead of being mistaken for the fork===true best-effort path.
897
+ const explicitForkId = typeof forkArg === 'string' ? forkArg : undefined;
898
+ // forkRequested is already computed at the top of executePrompt for the
899
+ // fork/resume mutual-exclusivity guard (apra-fleet-lmtg.4) -- reuse it here.
900
+ const resumeRequested = (input.resume === true || explicitResumeId !== undefined) && !forkRequested;
901
+ const resumeTargetId = explicitResumeId ?? agent.sessionId;
902
+ // An explicit-id resume OR an explicit-id fork must never silently degrade to a
903
+ // fresh session: that is exactly the wrong-context dispatch this feature
904
+ // forbids. resume=true/false and fork=true keep their transparent recovery.
905
+ const allowFreshSessionFallback = explicitResumeId === undefined && explicitForkId === undefined;
906
+ const resuming = !!(resumeRequested && resumeTargetId && provider.supportsResume());
907
+ const isCallerMinted = provider.sessionIdStrategy().type === 'caller-minted';
908
+ const mintedId = isCallerMinted
909
+ ? (resuming ? resumeTargetId : uuid())
910
+ : (resuming ? resumeTargetId : undefined);
911
+ // Terminal session-not-found gate for explicit-id resumes (apra-fleet-eft.78.1).
912
+ // Checked BEFORE any spawn (writePromptFile / the LLM invocation): if the
913
+ // caller named a session the server has never issued for this member -- and it
914
+ // is not the member's currently-stored session -- there is no context to
915
+ // resume. Reject with a structured session_not_found and make NO LLM call,
916
+ // so an orchestrator can rebuild a self-contained prompt and re-dispatch fresh
917
+ // deliberately, rather than getting a silent blank-session response.
918
+ if (explicitResumeId !== undefined) {
919
+ const resumable = provider.supportsResume()
920
+ && (isKnownSession(agent.id, explicitResumeId) || explicitResumeId === agent.sessionId);
921
+ if (!resumable) {
922
+ scope.abort(`explicit resume rejected -- session "${explicitResumeId}" is unknown/expired (no LLM call)`);
893
923
  inFlightAgents.delete(agent.id);
894
924
  stallDetector.remove(agent.id);
895
925
  writeStatusline(new Map([[agent.id, 'idle']]));
896
- return `execute_prompt: agent "${input.agent}" not found.\n\nExpected at:\n ${projPath.replace(/\\/g, '/')}\n ${userPath.replace(/\\/g, '/')}`;
926
+ return {
927
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}" rejected -- session "${explicitResumeId}" cannot be resumed (unknown or expired). No LLM call was made. Rebuild the context and re-dispatch with a full, self-contained prompt (resume=false), or resume=true for best-effort recovery.`,
928
+ structuredContent: { isError: true, reason: 'session_not_found', sessionId: explicitResumeId },
929
+ };
897
930
  }
898
931
  }
899
- else {
900
- // Canonical PM role agents (planner/doer/reviewer/plan-reviewer/...) are
901
- // already guaranteed present in ~/dirs.home by
902
- // ensureAgentFilesProvisioned() above (ln ~576, which ran provisionAgents()
903
- // for this exact member earlier in this same call) -- trust that instead
904
- // of re-probing the remote here. This also SIDESTEPS the bug this check
905
- // used to have: the old code hand-rolled a POSIX-only
906
- // `test -f ... || test -f ...` command run via strategy.execCommand(),
907
- // which throws a PowerShell parser error (not a POSIX shell) on every
908
- // Windows remote -- a nonzero exit that this check misread as "agent not
909
- // found" even when the file genuinely existed (apra-fleet P0 bug, fleet-
910
- // sprint via a Windows remote member always failed plan-review with
911
- // "agent 'plan-reviewer' not found").
912
- const canonicalRelPath = `${input.agent}.md`;
913
- agentFound = remoteAgentsDir(provider.name) !== null
914
- && loadCanonicalAgentSet(provider.name).some((f) => f.relPath === canonicalRelPath);
915
- if (!agentFound) {
916
- // Not part of the canonical PM set (e.g. a project-local custom
917
- // agent) -- fall back to a REAL existence probe, built platform-aware
918
- // via this repo's own getOsCommands() abstraction (src/os/*.ts,
919
- // already used the same way by list-members.ts/member-detail.ts for
920
- // credential-file checks) instead of a single hardcoded shell dialect.
921
- const cmds = getOsCommands(getAgentOS(agent));
922
- const projPath = `${resolvedWorkFolder}/${dirs.project}`;
923
- const userPath = `~/${dirs.home}`;
924
- const [projResult, userResult] = await Promise.all([
925
- strategy.execCommand(cmds.credentialFileCheck(projPath), 10000),
926
- strategy.execCommand(cmds.credentialFileCheck(userPath), 10000),
927
- ]);
928
- agentFound = projResult.stdout.includes('found') || userResult.stdout.includes('found');
929
- }
930
- if (!agentFound) {
932
+ // Fork mode resolution (apra-fleet-lmtg.5). Resolved AFTER the resume gate
933
+ // (the two are mutually exclusive, guarded before member resolution). Fork
934
+ // requires a fork-capable provider; when active it produces a ForkDescriptor
935
+ // that buildAgentPromptCommand (fork-prov lane, apra-fleet-lmtg.2) turns into
936
+ // the provider's own source-seeded, new-session-id fork invocation.
937
+ let forkActive = false;
938
+ let forkSourceId;
939
+ if (forkRequested) {
940
+ // fork requires provider.supportsFork(): a fork request against a provider
941
+ // whose CLI cannot fork is surfaced as a clear TERMINAL error, never
942
+ // silently downgraded to a plain fresh/resume dispatch (the wrong behavior).
943
+ if (!provider.supportsFork?.()) {
944
+ scope.abort(`fork rejected -- provider "${provider.name}" does not support fork-mode dispatch (no LLM call)`);
931
945
  inFlightAgents.delete(agent.id);
932
946
  stallDetector.remove(agent.id);
933
947
  writeStatusline(new Map([[agent.id, 'idle']]));
934
- return `execute_prompt: agent "${input.agent}" not found on "${agent.friendlyName}".\n\nExpected at:\n ${resolvedWorkFolder}/${dirs.project}\n ~/${dirs.home}`;
948
+ return {
949
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}" rejected -- provider "${provider.name}" does not support fork-mode dispatch. No LLM call was made. Re-dispatch without fork (resume=true/false), or use a fork-capable provider.`,
950
+ structuredContent: { isError: true, reason: 'fork_unsupported' },
951
+ };
952
+ }
953
+ if (explicitForkId !== undefined) {
954
+ // Terminal source-not-found gate, mirroring the explicit-resume gate: an
955
+ // unknown/expired source id has no context to branch from, so reject
956
+ // BEFORE any spawn with a structured session_not_found and NO LLM call.
957
+ const forkable = isKnownSession(agent.id, explicitForkId) || explicitForkId === agent.sessionId;
958
+ if (!forkable) {
959
+ scope.abort(`explicit fork rejected -- source session "${explicitForkId}" is unknown/expired (no LLM call)`);
960
+ inFlightAgents.delete(agent.id);
961
+ stallDetector.remove(agent.id);
962
+ writeStatusline(new Map([[agent.id, 'idle']]));
963
+ return {
964
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}" rejected -- source session "${explicitForkId}" cannot be forked (unknown or expired). No LLM call was made. Rebuild the context and re-dispatch with a full, self-contained prompt (fork=false/resume=false), or fork=true for best-effort branching from the member's stored session.`,
965
+ structuredContent: { isError: true, reason: 'session_not_found', sessionId: explicitForkId },
966
+ };
967
+ }
968
+ forkSourceId = explicitForkId;
969
+ forkActive = true;
970
+ }
971
+ else {
972
+ // fork === true: best-effort branch from the member's stored last session.
973
+ // A stale/unknown stored session (or none at all) is NOT a hard error --
974
+ // log a warning and fall through to a plain FRESH session, mirroring
975
+ // resume=true's transparent recovery.
976
+ const stored = agent.sessionId;
977
+ if (stored && isKnownSession(agent.id, stored)) {
978
+ forkSourceId = stored;
979
+ forkActive = true;
980
+ }
981
+ else {
982
+ scope.info(`fork=true: stored session ${stored ? `"${stored}" is stale/unknown` : 'is absent'} -- falling back to a fresh session`);
983
+ forkActive = false;
984
+ }
935
985
  }
936
986
  }
937
- }
938
- // Context-headroom admission control (apra-fleet-eft.81.1): a declared
939
- // demand is checked against this session's remaining headroom BEFORE any
940
- // CLI is spawned. No declared demand (both fields omitted) means this
941
- // block is skipped entirely -- pre-existing behavior is unchanged.
942
- const contextDemand = resolveExpectedDemand(input.expected_context_tokens, input.context_size);
943
- let contextWarning;
944
- if (contextDemand !== undefined) {
945
- const admission = checkContextAdmission({
946
- provider: provider.name,
947
- resolvedModel,
987
+ // Mint a fresh distinct output session id for the forked conversation (never
988
+ // reuse the source id): mintedId is already a freshly minted uuid here because
989
+ // fork forced resuming off above (see resumeRequested). It IS emitted as an
990
+ // explicit `--session-id` CLI flag in fork mode (see ForkDescriptor.newSessionId
991
+ // and provider.forkFlag) -- the CLI honors a caller-supplied session id even
992
+ // when forking, so we pre-mint and pass it rather than scraping the CLI's own
993
+ // minted id back out of the response afterward. The same id also drives
994
+ // recordKnownSession, the stall-detector log path, and the post-dispatch
995
+ // session bookkeeping below.
996
+ const forkDescriptor = forkActive && forkSourceId
997
+ ? { sourceSessionId: forkSourceId, newSessionId: mintedId ?? uuid() }
998
+ : undefined;
999
+ const promptOpts = {
1000
+ folder: resolvedWorkFolder,
1001
+ promptFile: promptFileName,
948
1002
  sessionId: mintedId,
949
- demand: contextDemand,
950
- });
951
- if (!admission.allowed) {
952
- scope.abort(`insufficient context headroom: demand=${admission.detail.demand} headroom=${admission.detail.headroom} window=${admission.detail.window}`);
953
- inFlightAgents.delete(agent.id);
954
- stallDetector.remove(agent.id);
955
- writeStatusline(new Map([[agent.id, 'idle']]));
956
- return {
957
- text: `[FAIL] execute_prompt on "${agent.friendlyName}" rejected -- insufficient context headroom (demand=${admission.detail.demand}, headroom=${admission.detail.headroom}, window=${admission.detail.window}). Start a fresh session, shrink the task, or split it.`,
958
- structuredContent: { isError: true, reason: 'insufficient_context_headroom', detail: admission.detail },
959
- };
960
- }
961
- if (admission.warning) {
962
- contextWarning = { message: admission.warning, detail: admission.detail };
963
- }
964
- }
965
- // Usage/budget admission (apra-fleet-eft.80.2): when a budget is configured
966
- // for this member (or its workspace), a hard-threshold crossing rejects the
967
- // NEW dispatch BEFORE any LLM is spawned -- never killing an in-flight call.
968
- // No configured budget (the common case) means resolveBudgetScope returns
969
- // undefined and this block is skipped entirely -- behavior is unchanged.
970
- const budgetScope = resolveBudgetScope([agent.id, workspaceId]);
971
- if (budgetScope) {
972
- const preBudget = await evaluateBudget({ scope: budgetScope, agent, provider });
973
- if (preBudget?.exhausted) {
974
- scope.abort(`budget exhausted: scope=${budgetScope} spent=${preBudget.block.spent} budget=${preBudget.block.budget} source=${preBudget.block.source}`);
975
- inFlightAgents.delete(agent.id);
976
- stallDetector.remove(agent.id);
977
- writeStatusline(new Map([[agent.id, 'idle']]));
978
- return {
979
- text: `[FAIL] execute_prompt on "${agent.friendlyName}" rejected -- budget exhausted (scope=${budgetScope}, spent=${preBudget.block.spent}, budget=${preBudget.block.budget} ${preBudget.block.unit}, source=${preBudget.block.source}). No LLM call was made; raise or reset the budget to resume.`,
980
- structuredContent: { isError: true, reason: 'budget_exhausted', budgetUsage: preBudget.block },
981
- };
982
- }
983
- }
984
- // Kill any leftover session from a previous (possibly zombie) execute_prompt call
985
- await tryKillPid(agent, strategy, cmds);
986
- // Write the rendered prompt (with substitutions applied) to the prompt file before execution
987
- await writePromptFile(agent, strategy, promptFilePath, renderedPrompt);
988
- // apra-fleet-6z8.1: remembered for the lease-of-life gate below -- the pid
989
- // outlives the SSH channel that reported it, and is the only way to tell a
990
- // fabricated "exit 0 / empty" close apart from a real one.
991
- let capturedPid;
992
- const onPidCaptured = (pid) => {
993
- capturedPid = pid;
994
- scope.info(`pid=${pid}`);
995
- if (mintedId) {
996
- let logPath = null;
1003
+ resuming,
1004
+ unattended: agent.unattended,
1005
+ model: resolvedModel,
1006
+ tier: resolvedTier,
1007
+ maxTurns: input.max_turns,
1008
+ inv: scope.getInv(),
1009
+ agentName: input.agent,
1010
+ fork: forkDescriptor,
1011
+ projectId: agyProjectId,
1012
+ };
1013
+ // apra-fleet issue #390: session log paths live on the MEMBER's machine, under
1014
+ // the MEMBER's home directory, joined with the MEMBER's OS convention. Before
1015
+ // this, every remote member got a HUB-home path (os.homedir()) joined with the
1016
+ // HUB's path convention -- a path that can never exist on the member, which
1017
+ // silently disabled stall detection for Claude and manufactured
1018
+ // false-positive stall kills for AGY/OpenCode.
1019
+ //
1020
+ // This resolution is deliberately SYNCHRONOUS (cached probe result, else the
1021
+ // member's known login username's default home): the dispatch path must not
1022
+ // add a remote round trip, and a wrong guess here can only cost detection
1023
+ // fidelity, never cause a kill. The kill-capable directory poll in
1024
+ // stall-poller.ts uses the probe-backed async resolver instead.
1025
+ const memberPathCtx = getCachedMemberPathContext(agent);
1026
+ const activePreSpawnSid = resuming ? resumeTargetId : (isCallerMinted ? mintedId : undefined);
1027
+ let resolvedLogPath = null;
1028
+ if (activePreSpawnSid) {
997
1029
  try {
998
- logPath = resolveSessionLogPath(agent.llmProvider ?? 'claude', mintedId, resolvedWorkFolder, memberPathCtx.homeDir, memberPathCtx.targetOs);
1030
+ resolvedLogPath = resolveSessionLogPath(agent.llmProvider ?? 'claude', activePreSpawnSid, resolvedWorkFolder, memberPathCtx.homeDir, memberPathCtx.targetOs);
999
1031
  }
1000
1032
  catch {
1001
- logPath = null;
1033
+ resolvedLogPath = null;
1002
1034
  }
1003
- stallDetector.update(agent.id, {
1004
- sessionId: mintedId,
1005
- logFilePath: logPath,
1006
- provisional: !logPath,
1007
- });
1008
1035
  }
1009
- };
1010
- const abortHandler = () => {
1011
- scope.abort('cancelled by MCP client');
1012
- tryKillPid(agent, strategy, cmds).catch(() => { });
1013
- };
1014
- extra?.signal?.addEventListener('abort', abortHandler);
1015
- // apra-fleet-3c9.1: the signal handed to execCommand fires on EITHER the MCP
1016
- // client's cancellation OR a confirmed stall (stallAbortController). Merging
1017
- // them means a stall aborts the pending dispatch exactly as a client cancel
1018
- // would, while a live (non-stalled) dispatch -- whose controller is never
1019
- // aborted -- is left completely untouched.
1020
- const dispatchSignal = extra?.signal
1021
- ? AbortSignal.any([extra.signal, stallAbortController.signal])
1022
- : stallAbortController.signal;
1023
- // Mark agent as busy in statusline
1024
- writeStatusline(new Map([[agent.id, 'busy']]));
1025
- let _epExitCode = 'error';
1026
- let _epError;
1027
- let _epUsage;
1028
- let _epOffline = false;
1029
- // apra-fleet-6a7.1: gates the exit-0/empty-stdout workspace_not_trusted
1030
- // self-heal-and-retry below to exactly one attempt per call, mirroring
1031
- // runGitStep's authHealAttempted shape (fleet-sprint/runner.js:616) -- a
1032
- // repeat trust failure after the heal is terminal, never looped.
1033
- let trustHealAttempted = false;
1034
- try {
1035
- let result;
1036
- try {
1037
- result = await strategy.execCommand(claudeCmd, timeoutMs, maxTotalMs, onPidCaptured, dispatchSignal);
1038
- }
1039
- catch (dispatchErr) {
1040
- // apra-fleet-02s.1: a genuine command-execution exception (e.g. an
1041
- // inactivity timeout, or any other error strategy.execCommand throws)
1042
- // used to be unconditionally unretried here -- it bypasses both retry
1043
- // mechanisms below, since those only fire on a non-throwing nonzero
1044
- // exit, never on a thrown exception. Retry once with a fresh session
1045
- // before giving up, mirroring the stale-session/server-overloaded
1046
- // retries' bounded, single-attempt shape. Skip the retry if the client
1047
- // itself cancelled the request -- there is nothing to recover from a
1048
- // deliberate cancellation.
1049
- if (extra?.signal?.aborted)
1050
- throw dispatchErr;
1051
- // apra-fleet-3c9.1: a stall-triggered abort is terminal. onStall already
1052
- // killed the remote process and its session is gone, so retrying in a
1053
- // fresh session would just re-dispatch onto a member we just tore down.
1054
- // Let the exception surface to the outer catch, which classifies it as a
1055
- // typed 'stalled' error instead of retrying or hanging.
1056
- if (stallAbortController.signal.aborted)
1057
- throw dispatchErr;
1058
- // apra-fleet-eft.78.1: an explicit-id resume must NOT retry in a fresh
1059
- // session (that would run a context-dependent delta prompt with no
1060
- // context). Let the exception surface as dispatch_failed instead.
1061
- if (!allowFreshSessionFallback)
1062
- throw dispatchErr;
1063
- // apra-fleet-y8q.1: no budget left to share with a retry (the original
1064
- // attempt already consumed the whole max_total_s) -- retrying here would
1065
- // just re-burn a fresh full budget past what the client is waiting for.
1066
- // Let the original exception surface instead of retrying blind.
1067
- const budget = retryBudget();
1068
- if (budget.exhausted)
1069
- throw dispatchErr;
1070
- scope.info(`[${resolvedModel}] retrying -- dispatch exception: ${dispatchErr.message}`);
1071
- await tryKillPid(agent, strategy, cmds);
1072
- const freshOpts = { ...promptOpts, sessionId: isCallerMinted ? uuid() : undefined, resuming: false };
1073
- const retryCmd = authPrefix + cmds.buildAgentPromptCommand(provider, freshOpts);
1074
- result = await strategy.execCommand(retryCmd, budget.timeoutMs, budget.maxTotalMs, onPidCaptured, dispatchSignal);
1036
+ stallDetector.update(agent.id, {
1037
+ sessionId: activePreSpawnSid,
1038
+ logFilePath: resolvedLogPath,
1039
+ provisional: !resolvedLogPath,
1040
+ thresholdMs: stallThresholdMs,
1041
+ });
1042
+ const claudeCmd = authPrefix + cmds.buildAgentPromptCommand(provider, promptOpts);
1043
+ // apra-fleet-6z8.1: the per-invocation durable stdout mirror the unix prompt
1044
+ // wrapper tees to (see durableOutputPath / buildAgentPromptCommand). A
1045
+ // PowerShell Windows member has no such companion tee, so recovery is
1046
+ // skipped for it.
1047
+ //
1048
+ // apra-fleet-7dir.5.4: a Windows member registered as gitbash runs
1049
+ // WindowsGitBashCommands, which INHERITS LinuxCommands.buildAgentPromptCommand
1050
+ // -- so it has already been teeing its stdout to /tmp/.fleet-out-<inv>.json
1051
+ // on every dispatch, with nothing reading it and (because extraPaths was
1052
+ // empty) nothing deleting it. Enabling the mirror for gitbash both turns
1053
+ // recovery on for that member class and makes the file get cleaned up.
1054
+ // This gate and the `unsupported` flag passed to recoverOrphanedDispatch
1055
+ // below are ONE decision: recoverOrphanedDispatch short-circuits on
1056
+ // `unsupported || !durablePath`, so they must always agree -- hence the
1057
+ // single shared predicate.
1058
+ //
1059
+ // LOCAL agents are deliberately excluded from the flip: orphan recovery
1060
+ // exists for a torn-down SSH channel, which a local spawn does not have, and
1061
+ // deletePromptFile's local branch would fs.unlinkSync('/tmp/...') through
1062
+ // Node on Windows (resolving to C:\tmp), not the MSYS /tmp bash teed to.
1063
+ // Non-Windows members (local or remote) keep today's behaviour verbatim.
1064
+ const durableMirrorSupported = getAgentOS(agent) !== 'windows'
1065
+ || (getAgentShell(agent) === 'gitbash' && agent.agentType !== 'local');
1066
+ const durablePath = durableMirrorSupported ? durableOutputPath(scope.getInv()) : undefined;
1067
+ const dispatchStartedAt = Date.now();
1068
+ const maxTotalMs = input.max_total_s !== undefined ? input.max_total_s * 1000 : undefined;
1069
+ // apra-fleet-25yl.2.1: the exec-level ROLLING (inactivity) deadline handed to
1070
+ // strategy.execCommand() is no longer provider-blind. It used to be
1071
+ // `timeout_s` for everyone, which is a false kill for the batch-only
1072
+ // providers (they emit nothing on this channel until the turn ends) and the
1073
+ // only working stall signal for the providers with no pollable transcript.
1074
+ // The per-provider answer lives in ONE named place -- ProviderAdapter
1075
+ // .execTimeoutSource() -- so a newly added provider must state its own
1076
+ // (a compile error if it does not) instead of inheriting a default branch.
1077
+ //
1078
+ // NOTE: input.timeout_s still reaches the StallDetector as thresholdMs for
1079
+ // EVERY provider (see stallThresholdMs above). This decision governs the
1080
+ // exec-channel timer only; it must not be used to skip that threading.
1081
+ const execTimeoutSource = provider.execTimeoutSource();
1082
+ const timeoutMs = execTimeoutSource === 'inactivity_timeout'
1083
+ ? (input.timeout_s ?? 300) * 1000
1084
+ // 'total_ceiling': mirror max_total_s, which can never bind before the
1085
+ // caller's own hard ceiling does (a rolling inactivity window of
1086
+ // max_total_s starts at dispatch start and only ever resets later).
1087
+ // max_total_s ABSENT: there is no ceiling to mirror, so use a documented
1088
+ // never-binds-first constant rather than silently falling back to
1089
+ // timeout_s (which is exactly the coupling this change removes). It is
1090
+ // deliberately a finite value well inside the int32 range setTimeout
1091
+ // accepts -- Infinity or Number.MAX_SAFE_INTEGER would overflow and fire
1092
+ // on the next tick, inverting this fix into an instant kill.
1093
+ : (maxTotalMs ?? EXEC_TIMER_NEVER_BINDS_MS);
1094
+ // apra-fleet-y8q.1: every retry below (dispatch-exception, stale-session,
1095
+ // server-overloaded) re-dispatches with a FRESH session but used to reuse the
1096
+ // SAME full timeoutMs/maxTotalMs as the original attempt -- so a single
1097
+ // dispatch could burn up to ~2x max_total_s server-side (original attempt +
1098
+ // one full-budget retry), well past what the client's deriveTimeoutMs()
1099
+ // (packages/apra-fleet-client/src/client/api.mjs) budgets for the whole
1100
+ // tools/call (max_total_s*1000 + a fixed grace margin). That let the
1101
+ // client's hard timeout fire before the server's own retry-and-report path
1102
+ // ever got a chance, hiding a clean typed server error behind a raw client
1103
+ // transport timeout. Share ONE deadline budget across the original attempt
1104
+ // and any single retry: cap a retry's maxTotalMs (and its inactivity
1105
+ // timeoutMs, so it can't independently outlast the shared ceiling) to
1106
+ // whatever remains of max_total_s since dispatchStartedAt, and skip the
1107
+ // retry entirely once that budget is exhausted -- so total wall-clock time
1108
+ // for this call never exceeds max_total_s, which is exactly what the client
1109
+ // is prepared to wait for. When max_total_s is absent there is no hard
1110
+ // ceiling to share, so retries keep their full timeout_s (unchanged,
1111
+ // pre-existing behavior).
1112
+ function retryBudget() {
1113
+ if (maxTotalMs === undefined)
1114
+ return { timeoutMs, maxTotalMs: undefined, exhausted: false };
1115
+ const remaining = Math.max(0, maxTotalMs - (Date.now() - dispatchStartedAt));
1116
+ return { timeoutMs: Math.min(timeoutMs, remaining), maxTotalMs: remaining, exhausted: remaining <= 0 };
1075
1117
  }
1076
- let parsed = provider.parseResponse(result);
1077
- if (parsed.usage)
1078
- _epUsage = parsed.usage;
1079
- // apra-fleet-eft.40.3: workspace-not-trusted degrades composed permissions
1080
- // (project-scoped allow entries silently dropped) without killing the CLI process --
1081
- // from there, unattended -p cannot auto-approve or prompt, so tools get denied and
1082
- // the turn eventually fails. Blindly falling through to the stale-session /
1083
- // server-overloaded retries below just repeats the same degraded dispatch against a
1084
- // workspace that is still untrusted, and can walk into eft.28's dead-session hang.
1085
- // Classify and fail fast here, before either retry path, naming
1086
- // ensureWorkspaceTrusted (apra-fleet-eft.40.1/40.2) as the remediation.
1087
- if (result.code !== 0 && provider.classifyError(result.stderr || result.stdout) === 'workspace_not_trusted') {
1088
- return {
1089
- text: `[FAIL] ${workspaceNotTrustedAdvice(agent.friendlyName)}\n${result.stderr || result.stdout}`,
1090
- structuredContent: { isError: true, reason: 'workspace_not_trusted' },
1091
- };
1118
+ // Agent file validation -- verify named agent exists before any CLI invocation
1119
+ if (input.agent) {
1120
+ const dirs = provider.agentDirectories(input.agent);
1121
+ let agentFound = false;
1122
+ if (agent.agentType === 'local') {
1123
+ const projPath = path.join(resolvedWorkFolder, dirs.project);
1124
+ const userPath = path.join(os.homedir(), dirs.home);
1125
+ agentFound = fs.existsSync(projPath) || fs.existsSync(userPath);
1126
+ if (!agentFound) {
1127
+ inFlightAgents.delete(agent.id);
1128
+ stallDetector.remove(agent.id);
1129
+ writeStatusline(new Map([[agent.id, 'idle']]));
1130
+ return `execute_prompt: agent "${input.agent}" not found.\n\nExpected at:\n ${projPath.replace(/\\/g, '/')}\n ${userPath.replace(/\\/g, '/')}`;
1131
+ }
1132
+ }
1133
+ else {
1134
+ // Canonical PM role agents (planner/doer/reviewer/plan-reviewer/...) are
1135
+ // already guaranteed present in ~/dirs.home by
1136
+ // ensureAgentFilesProvisioned() above (ln ~576, which ran provisionAgents()
1137
+ // for this exact member earlier in this same call) -- trust that instead
1138
+ // of re-probing the remote here. This also SIDESTEPS the bug this check
1139
+ // used to have: the old code hand-rolled a POSIX-only
1140
+ // `test -f ... || test -f ...` command run via strategy.execCommand(),
1141
+ // which throws a PowerShell parser error (not a POSIX shell) on every
1142
+ // Windows remote -- a nonzero exit that this check misread as "agent not
1143
+ // found" even when the file genuinely existed (apra-fleet P0 bug, fleet-
1144
+ // sprint via a Windows remote member always failed plan-review with
1145
+ // "agent 'plan-reviewer' not found").
1146
+ const canonicalRelPath = `${input.agent}.md`;
1147
+ agentFound = remoteAgentsDir(provider.name) !== null
1148
+ && loadCanonicalAgentSet(provider.name).some((f) => f.relPath === canonicalRelPath);
1149
+ if (!agentFound) {
1150
+ // Not part of the canonical PM set (e.g. a project-local custom
1151
+ // agent) -- fall back to a REAL existence probe, built platform-aware
1152
+ // via this repo's own getOsCommands() abstraction (src/os/*.ts,
1153
+ // already used the same way by list-members.ts/member-detail.ts for
1154
+ // credential-file checks) instead of a single hardcoded shell dialect.
1155
+ const cmds = getOsCommands(getAgentOS(agent), getAgentShell(agent));
1156
+ const projPath = `${resolvedWorkFolder}/${dirs.project}`;
1157
+ const userPath = `~/${dirs.home}`;
1158
+ const [projResult, userResult] = await Promise.all([
1159
+ strategy.execCommand(cmds.credentialFileCheck(projPath), 10000),
1160
+ strategy.execCommand(cmds.credentialFileCheck(userPath), 10000),
1161
+ ]);
1162
+ agentFound = projResult.stdout.includes('found') || userResult.stdout.includes('found');
1163
+ }
1164
+ if (!agentFound) {
1165
+ inFlightAgents.delete(agent.id);
1166
+ stallDetector.remove(agent.id);
1167
+ writeStatusline(new Map([[agent.id, 'idle']]));
1168
+ return `execute_prompt: agent "${input.agent}" not found on "${agent.friendlyName}".\n\nExpected at:\n ${resolvedWorkFolder}/${dirs.project}\n ~/${dirs.home}`;
1169
+ }
1170
+ }
1092
1171
  }
1093
- // Stale session retry -- fresh session ID, no resume. apra-fleet-eft.78.1:
1094
- // ONLY the best-effort resume=true mode gets this transparent retry-fresh
1095
- // recovery. An explicit session-id resume (string) deliberately does NOT --
1096
- // its caller asserted context dependence, so a not-found id is terminal.
1097
- if (result.code !== 0 && input.resume === true && agent.sessionId) {
1098
- // apra-fleet-y8q.1: share the remaining max_total_s budget with this
1099
- // retry too -- skip it outright once exhausted (see retryBudget above).
1100
- const staleBudget = retryBudget();
1101
- if (!staleBudget.exhausted) {
1102
- scope.info(`[${resolvedModel}] retrying -- stale session`);
1103
- await tryKillPid(agent, strategy, cmds);
1104
- const freshOpts = { ...promptOpts, sessionId: isCallerMinted ? uuid() : undefined, resuming: false };
1105
- const retryCmd = authPrefix + cmds.buildAgentPromptCommand(provider, freshOpts);
1106
- result = await strategy.execCommand(retryCmd, staleBudget.timeoutMs, staleBudget.maxTotalMs, onPidCaptured, dispatchSignal);
1107
- parsed = provider.parseResponse(result);
1108
- if (parsed.usage)
1109
- _epUsage = parsed.usage;
1172
+ // Context-headroom admission control (apra-fleet-eft.81.1): a declared
1173
+ // demand is checked against this session's remaining headroom BEFORE any
1174
+ // CLI is spawned. No declared demand (both fields omitted) means this
1175
+ // block is skipped entirely -- pre-existing behavior is unchanged.
1176
+ const contextDemand = resolveExpectedDemand(input.expected_context_tokens, input.context_size);
1177
+ let contextWarning;
1178
+ if (contextDemand !== undefined) {
1179
+ const admission = checkContextAdmission({
1180
+ provider: provider.name,
1181
+ resolvedModel,
1182
+ sessionId: mintedId,
1183
+ demand: contextDemand,
1184
+ });
1185
+ if (!admission.allowed) {
1186
+ scope.abort(`insufficient context headroom: demand=${admission.detail.demand} headroom=${admission.detail.headroom} window=${admission.detail.window}`);
1187
+ inFlightAgents.delete(agent.id);
1188
+ stallDetector.remove(agent.id);
1189
+ writeStatusline(new Map([[agent.id, 'idle']]));
1190
+ return {
1191
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}" rejected -- insufficient context headroom (demand=${admission.detail.demand}, headroom=${admission.detail.headroom}, window=${admission.detail.window}). Start a fresh session, shrink the task, or split it.`,
1192
+ structuredContent: { isError: true, reason: 'insufficient_context_headroom', detail: admission.detail },
1193
+ };
1194
+ }
1195
+ if (admission.warning) {
1196
+ contextWarning = { message: admission.warning, detail: admission.detail };
1110
1197
  }
1111
1198
  }
1112
- // Server/overloaded error retry -- single attempt after delay. Skipped for
1113
- // an explicit-id resume (apra-fleet-eft.78.1): the retry starts a fresh
1114
- // session, which would discard the exact context the caller asked to resume.
1115
- if (result.code !== 0 && allowFreshSessionFallback && isRetryable(provider.classifyError(result.stderr || result.stdout))) {
1116
- // apra-fleet-y8q.1: share the remaining max_total_s budget with this
1117
- // retry too -- skip it outright once exhausted (see retryBudget above).
1118
- const overloadBudget = retryBudget();
1119
- if (!overloadBudget.exhausted) {
1120
- scope.info(`[${resolvedModel}] retrying -- server overloaded`);
1121
- await tryKillPid(agent, strategy, cmds);
1122
- await new Promise(r => setTimeout(r, SERVER_RETRY_DELAY_MS));
1123
- const freshOpts = { ...promptOpts, sessionId: isCallerMinted ? uuid() : undefined, resuming: false };
1124
- const retryCmd = authPrefix + cmds.buildAgentPromptCommand(provider, freshOpts);
1125
- result = await strategy.execCommand(retryCmd, overloadBudget.timeoutMs, overloadBudget.maxTotalMs, onPidCaptured, dispatchSignal);
1126
- parsed = provider.parseResponse(result);
1127
- if (parsed.usage)
1128
- _epUsage = parsed.usage;
1199
+ // Usage/budget admission (apra-fleet-eft.80.2): when a budget is configured
1200
+ // for this member (or its workspace), a hard-threshold crossing rejects the
1201
+ // NEW dispatch BEFORE any LLM is spawned -- never killing an in-flight call.
1202
+ // No configured budget (the common case) means resolveBudgetScope returns
1203
+ // undefined and this block is skipped entirely -- behavior is unchanged.
1204
+ const budgetScope = resolveBudgetScope([agent.id, workspaceId]);
1205
+ if (budgetScope) {
1206
+ const preBudget = await evaluateBudget({ scope: budgetScope, agent, provider });
1207
+ if (preBudget?.exhausted) {
1208
+ scope.abort(`budget exhausted: scope=${budgetScope} spent=${preBudget.block.spent} budget=${preBudget.block.budget} source=${preBudget.block.source}`);
1209
+ inFlightAgents.delete(agent.id);
1210
+ stallDetector.remove(agent.id);
1211
+ writeStatusline(new Map([[agent.id, 'idle']]));
1212
+ return {
1213
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}" rejected -- budget exhausted (scope=${budgetScope}, spent=${preBudget.block.spent}, budget=${preBudget.block.budget} ${preBudget.block.unit}, source=${preBudget.block.source}). No LLM call was made; raise or reset the budget to resume.`,
1214
+ structuredContent: { isError: true, reason: 'budget_exhausted', budgetUsage: preBudget.block },
1215
+ };
1129
1216
  }
1130
1217
  }
1131
- _epExitCode = result.code;
1132
- if (result.code !== 0) {
1133
- // apra-fleet-391: surface an auth failure as a STRUCTURED reason (not
1134
- // just prose in `text`) so callers -- notably fleet-sprint's
1135
- // isAuthDispatchError -- can key off it directly instead of regexing
1136
- // the message string. Overloading 'nonzero_exit' for this case was
1137
- // what made auth self-heal impossible to wire reliably upstream.
1138
- const failureCategory = isMaxTurnsResponse(parsed)
1139
- ? 'max_turns'
1140
- : provider.classifyError(result.stderr || result.stdout);
1218
+ // Kill any leftover session from a previous (possibly zombie) execute_prompt call
1219
+ await tryKillPid(agent, strategy, cmds);
1220
+ // Write the rendered prompt (with substitutions applied) to the prompt file before execution
1221
+ await writePromptFile(agent, strategy, promptFilePath, renderedPrompt);
1222
+ // apra-fleet-6z8.1: remembered for the lease-of-life gate below -- the pid
1223
+ // outlives the SSH channel that reported it, and is the only way to tell a
1224
+ // fabricated "exit 0 / empty" close apart from a real one.
1225
+ let capturedPid;
1226
+ const onPidCaptured = (pid) => {
1227
+ capturedPid = pid;
1228
+ scope.info(`pid=${pid}`);
1229
+ if (mintedId) {
1230
+ let logPath = null;
1231
+ try {
1232
+ logPath = resolveSessionLogPath(agent.llmProvider ?? 'claude', mintedId, resolvedWorkFolder, memberPathCtx.homeDir, memberPathCtx.targetOs);
1233
+ }
1234
+ catch {
1235
+ logPath = null;
1236
+ }
1237
+ stallDetector.update(agent.id, {
1238
+ sessionId: mintedId,
1239
+ logFilePath: logPath,
1240
+ provisional: !logPath,
1241
+ thresholdMs: stallThresholdMs,
1242
+ });
1243
+ }
1244
+ };
1245
+ const abortHandler = () => {
1246
+ scope.abort('cancelled by MCP client');
1247
+ tryKillPid(agent, strategy, cmds).catch(() => { });
1248
+ };
1249
+ extra?.signal?.addEventListener('abort', abortHandler);
1250
+ // apra-fleet-3c9.1: the signal handed to execCommand fires on EITHER the MCP
1251
+ // client's cancellation OR a confirmed stall (stallAbortController). Merging
1252
+ // them means a stall aborts the pending dispatch exactly as a client cancel
1253
+ // would, while a live (non-stalled) dispatch -- whose controller is never
1254
+ // aborted -- is left completely untouched.
1255
+ const dispatchSignal = extra?.signal
1256
+ ? AbortSignal.any([extra.signal, stallAbortController.signal])
1257
+ : stallAbortController.signal;
1258
+ // Mark agent as busy in statusline
1259
+ writeStatusline(new Map([[agent.id, 'busy']]));
1260
+ let _epExitCode = 'error';
1261
+ let _epError;
1262
+ let _epUsage;
1263
+ let _epOffline = false;
1264
+ // apra-fleet-6a7.1: gates the exit-0/empty-stdout workspace_not_trusted
1265
+ // self-heal-and-retry below to exactly one attempt per call, mirroring
1266
+ // runGitStep's authHealAttempted shape (fleet-sprint/runner.js:616) -- a
1267
+ // repeat trust failure after the heal is terminal, never looped.
1268
+ let trustHealAttempted = false;
1269
+ // apra-fleet-hzeb.2: a provider usage/quota limit (e.g. Claude's 429) can
1270
+ // never be cured by a fresh session, so it must short-circuit the
1271
+ // stale-session and server-overloaded retries below rather than burning the
1272
+ // shared retryBudget() waiting out a window that is already known. Checked
1273
+ // immediately after EVERY provider.parseResponse(result) call in the
1274
+ // dispatch path (initial dispatch, stale-session retry, overloaded retry,
1275
+ // orphan recovery, trust-heal retry) -- and regardless of result.code,
1276
+ // since a 0-exit result event whose text carries the limit message must not
1277
+ // be returned as a success response either.
1278
+ // The member's OS reaches the parser (agy's permission-denial hint differs on Windows).
1279
+ const parseCtx = { agentOs: agent.os };
1280
+ const checkUsageLimit = (r, p) => {
1281
+ const signal = provider.detectUsageLimit(r, p);
1282
+ if (!signal)
1283
+ return null;
1284
+ // Accurate finally-block exit logging (scope.fail, not scope.abort) even
1285
+ // when this fires on the very first parse, before the shared
1286
+ // `_epExitCode = result.code` assignment below would otherwise run.
1287
+ _epExitCode = r.code;
1288
+ scope.info(`usage limit detected -- resumes ~${signal.resumeAt} (${signal.resumeAtSource})`);
1289
+ // Session bookkeeping mirrors the max_turns path: record/touch the
1290
+ // session id when present so fleet-sprint can resume the SAME session
1291
+ // after the pause instead of starting a fresh one that has lost context.
1292
+ if (p.sessionId) {
1293
+ recordKnownSession(agent.id, p.sessionId);
1294
+ touchAgent(agent.id, p.sessionId);
1295
+ }
1141
1296
  return {
1142
- text: buildFailureMessage(agent.friendlyName, result, provider, parsed),
1297
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}" hit a provider usage limit (resumes ~${signal.resumeAt}, ${signal.resumeAtSource}): ${signal.message}`,
1143
1298
  structuredContent: {
1144
1299
  isError: true,
1145
- reason: failureCategory === 'max_turns'
1146
- ? 'max_turns_exhausted'
1147
- : failureCategory === 'auth'
1148
- ? 'auth'
1149
- : failureCategory === 'server'
1150
- ? 'server'
1151
- : failureCategory === 'overloaded'
1152
- ? 'overloaded'
1153
- : failureCategory === 'workspace_not_trusted'
1154
- ? 'workspace_not_trusted'
1155
- : 'nonzero_exit',
1156
- // apra-fleet-63x.1: a nonzero exit -- most commonly max_turns_exhausted,
1157
- // where the CLI ran real turns and burned real tokens before hitting its
1158
- // ceiling -- still has a REAL parsed usage figure sitting in _epUsage
1159
- // (captured just above from `parsed.usage` regardless of exit code).
1160
- // This branch used to return no `usage` field at all on any failure,
1161
- // so FleetWorkflow.agent() (packages/apra-fleet-workflow/src/workflow/
1162
- // index.mjs, apra-fleet-202.3) saw hasRealUsage=false and never priced
1163
- // it, silently under-counting a sprint's tracked spend (observed: a
1164
- // 10-hour run with dozens of max_turns exhaustions reporting
1165
- // stats.totalCost of $0). Attach it here whenever it's available so
1166
- // the caller can record the real partial cost instead of nothing.
1167
- ...(_epUsage ? { usage: { input_tokens: _epUsage.input_tokens, output_tokens: _epUsage.output_tokens, total_tokens: _epUsage.input_tokens + _epUsage.output_tokens } } : {}),
1300
+ reason: 'usage_limit',
1301
+ usageLimit: signal,
1302
+ ...(p.sessionId ? { sessionId: p.sessionId } : {}),
1303
+ ...(p.usage ? { usage: { input_tokens: p.usage.input_tokens, output_tokens: p.usage.output_tokens, total_tokens: p.usage.input_tokens + p.usage.output_tokens } } : {}),
1168
1304
  },
1169
1305
  };
1170
- }
1171
- // Exit 0 but the provider parser extracted NOTHING (no result text)
1172
- // -- observed live (apra-fleet-eft.14, 2026-07-19 stabilization loop):
1173
- // the claude CLI can die silently mid-turn (member-side session
1174
- // transcript stops at a tool_result with no final assistant message)
1175
- // and still exit 0 with EMPTY stdout, so parseResponse falls through
1176
- // to its plain-text fallback with result: ''. Returning that as a
1177
- // success used to hand callers a display wrapper with nothing inside,
1178
- // which schema-extraction layers then misreported as "LLM returned
1179
- // invalid JSON". Classify it at the source as a typed dispatch error
1180
- // instead, with stderr's tail attached for diagnosis.
1181
- //
1182
- // apra-fleet-6z8.1 (lease-of-life gate): before declaring that, cross-check
1183
- // whether the captured pid is STILL ALIVE via a fresh short exec. ssh.ts
1184
- // substitutes code 0 when the channel closes without ever receiving an
1185
- // 'exit' event, so "exit 0 + empty" is ALSO exactly what a torn-down
1186
- // channel over a perfectly healthy, still-running turn looks like (live
1187
- // evidence: pid 89858 running 2+ minutes past the close). Declaring
1188
- // empty_response there orphans the CLI and invites a duplicate concurrent
1189
- // dispatch of the same scope. A confirmed-dead pid keeps today's behavior
1190
- // verbatim.
1191
- if (!parsed.result || parsed.result.trim() === '') {
1192
- const recovery = await recoverOrphanedDispatch({
1193
- strategy,
1194
- cmds,
1195
- pid: capturedPid,
1196
- durablePath,
1197
- unsupported: getAgentOS(agent) === 'windows',
1198
- os: getAgentOS(agent),
1199
- maxWaitMs: maxTotalMs !== undefined ? Math.max(maxTotalMs - (Date.now() - dispatchStartedAt), 0) : undefined,
1200
- scope,
1201
- });
1202
- if (recovery.status === 'timeout') {
1203
- scope.info(`orphan recovery timed out after ${Math.round((recovery.waitedMs ?? 0) / 1000)}s -- pid killed`);
1306
+ };
1307
+ claimGuardActive = false;
1308
+ try {
1309
+ let result;
1310
+ try {
1311
+ result = await strategy.execCommand(claudeCmd, timeoutMs, maxTotalMs, onPidCaptured, dispatchSignal);
1312
+ }
1313
+ catch (dispatchErr) {
1314
+ // apra-fleet-02s.1: a genuine command-execution exception (e.g. an
1315
+ // inactivity timeout, or any other error strategy.execCommand throws)
1316
+ // used to be unconditionally unretried here -- it bypasses both retry
1317
+ // mechanisms below, since those only fire on a non-throwing nonzero
1318
+ // exit, never on a thrown exception. Retry once with a fresh session
1319
+ // before giving up, mirroring the stale-session/server-overloaded
1320
+ // retries' bounded, single-attempt shape. Skip the retry if the client
1321
+ // itself cancelled the request -- there is nothing to recover from a
1322
+ // deliberate cancellation.
1323
+ if (extra?.signal?.aborted)
1324
+ throw dispatchErr;
1325
+ // apra-fleet-3c9.1: a stall-triggered abort is terminal. onStall already
1326
+ // killed the remote process and its session is gone, so retrying in a
1327
+ // fresh session would just re-dispatch onto a member we just tore down.
1328
+ // Let the exception surface to the outer catch, which classifies it as a
1329
+ // typed 'stalled' error instead of retrying or hanging.
1330
+ if (stallAbortController.signal.aborted)
1331
+ throw dispatchErr;
1332
+ // apra-fleet-eft.78.1: an explicit-id resume must NOT retry in a fresh
1333
+ // session (that would run a context-dependent delta prompt with no
1334
+ // context). Let the exception surface as dispatch_failed instead.
1335
+ if (!allowFreshSessionFallback)
1336
+ throw dispatchErr;
1337
+ // apra-fleet-y8q.1: no budget left to share with a retry (the original
1338
+ // attempt already consumed the whole max_total_s) -- retrying here would
1339
+ // just re-burn a fresh full budget past what the client is waiting for.
1340
+ // Let the original exception surface instead of retrying blind.
1341
+ const budget = retryBudget();
1342
+ if (budget.exhausted)
1343
+ throw dispatchErr;
1344
+ scope.info(`[${resolvedModel}] retrying -- dispatch exception: ${dispatchErr.message}`);
1345
+ await tryKillPid(agent, strategy, cmds);
1346
+ const freshOpts = { ...promptOpts, sessionId: isCallerMinted ? uuid() : undefined, resuming: false, fork: undefined };
1347
+ const retryCmd = authPrefix + cmds.buildAgentPromptCommand(provider, freshOpts);
1348
+ result = await strategy.execCommand(retryCmd, budget.timeoutMs, budget.maxTotalMs, onPidCaptured, dispatchSignal);
1349
+ }
1350
+ let parsed = provider.parseResponse(result, parseCtx);
1351
+ if (parsed.usage)
1352
+ _epUsage = parsed.usage;
1353
+ {
1354
+ const usageLimitResult = checkUsageLimit(result, parsed);
1355
+ if (usageLimitResult)
1356
+ return usageLimitResult;
1357
+ }
1358
+ // apra-fleet-eft.40.3: workspace-not-trusted degrades composed permissions
1359
+ // (project-scoped allow entries silently dropped) without killing the CLI process --
1360
+ // from there, unattended -p cannot auto-approve or prompt, so tools get denied and
1361
+ // the turn eventually fails. Blindly falling through to the stale-session /
1362
+ // server-overloaded retries below just repeats the same degraded dispatch against a
1363
+ // workspace that is still untrusted, and can walk into eft.28's dead-session hang.
1364
+ // Classify and fail fast here, before either retry path, naming
1365
+ // ensureWorkspaceTrusted (apra-fleet-eft.40.1/40.2) as the remediation.
1366
+ if (result.code !== 0 && provider.classifyError(result.stderr || result.stdout) === 'workspace_not_trusted') {
1204
1367
  return {
1205
- text: `[FAIL] execute_prompt on "${agent.friendlyName}" lost its SSH channel while the member CLI (pid ${capturedPid}) was still running, and that process was still alive after the recovery window (${Math.round((recovery.waitedMs ?? 0) / 1000)}s). The process has been killed; no result was recovered. This is NOT an empty response -- do not treat it as a failed turn without checking the member's session transcript first.`,
1206
- structuredContent: { isError: true, reason: 'orphan_recovery_timeout' },
1368
+ text: `[FAIL] ${workspaceNotTrustedAdvice(agent.friendlyName)}\n${result.stderr || result.stdout}`,
1369
+ structuredContent: { isError: true, reason: 'workspace_not_trusted' },
1207
1370
  };
1208
1371
  }
1209
- if (recovery.status === 'recovered' && recovery.stdout) {
1210
- // Feed the durable output through the normal provider parse path,
1211
- // exactly as if it had arrived on the original channel.
1212
- const recoveredParsed = provider.parseResponse({ stdout: recovery.stdout, stderr: result.stderr ?? '', code: 0 });
1213
- if (recoveredParsed.result && recoveredParsed.result.trim() !== '') {
1214
- scope.info(`recovered the real result from the durable output file after a false-alarm empty_response (waited ${Math.round((recovery.waitedMs ?? 0) / 1000)}s)`);
1215
- parsed = recoveredParsed;
1372
+ // Stale session retry -- fresh session ID, no resume. apra-fleet-eft.78.1:
1373
+ // ONLY the best-effort resume=true mode gets this transparent retry-fresh
1374
+ // recovery. An explicit session-id resume (string) deliberately does NOT --
1375
+ // its caller asserted context dependence, so a not-found id is terminal.
1376
+ // apra-fleet-lmtg.5: gate on allowFreshSessionFallback too, so an explicit
1377
+ // fork (fork="<id>") never degrades here. The mutual-exclusivity guard keeps
1378
+ // input.resume at its default true for ANY fork request, so `input.resume
1379
+ // === true` alone would also fire for an explicit fork -- a silent
1380
+ // wrong-context fresh dispatch the explicit-fork gate exists to prevent.
1381
+ // allowFreshSessionFallback is false only for explicit resume/fork; it stays
1382
+ // true for resume=true and fork=true, which the AC permits to degrade.
1383
+ if (result.code !== 0 && allowFreshSessionFallback && input.resume === true && agent.sessionId) {
1384
+ // apra-fleet-y8q.1: share the remaining max_total_s budget with this
1385
+ // retry too -- skip it outright once exhausted (see retryBudget above).
1386
+ const staleBudget = retryBudget();
1387
+ if (!staleBudget.exhausted) {
1388
+ scope.info(`[${resolvedModel}] retrying -- stale session`);
1389
+ await tryKillPid(agent, strategy, cmds);
1390
+ const freshOpts = { ...promptOpts, sessionId: isCallerMinted ? uuid() : undefined, resuming: false, fork: undefined };
1391
+ const retryCmd = authPrefix + cmds.buildAgentPromptCommand(provider, freshOpts);
1392
+ result = await strategy.execCommand(retryCmd, staleBudget.timeoutMs, staleBudget.maxTotalMs, onPidCaptured, dispatchSignal);
1393
+ parsed = provider.parseResponse(result, parseCtx);
1216
1394
  if (parsed.usage)
1217
1395
  _epUsage = parsed.usage;
1396
+ const usageLimitResult = checkUsageLimit(result, parsed);
1397
+ if (usageLimitResult)
1398
+ return usageLimitResult;
1218
1399
  }
1219
1400
  }
1220
- // apra-fleet-6a7.1: the code!==0 workspace_not_trusted classification
1221
- // above (~line 1048) never sees this branch -- exit 0 + empty stdout is
1222
- // a SEPARATE path, but live evidence (apra-fleet-2g2, fleet-win-dev1,
1223
- // 2026-08-02) showed it can be caused by the exact same trust-gate
1224
- // failure: exited 0, empty stdout, and the stderr tail contained the
1225
- // exact matched phrase, so the code!==0 classifier never ran. Classify
1226
- // it here too and -- unlike that path, which only advises a manual fix
1227
- // -- self-heal via the same seedWorkspaceTrust/ensureWorkspaceTrusted
1228
- // path compose_permissions already uses, then retry the dispatch
1229
- // exactly once (gated by trustHealAttempted, mirroring runGitStep's
1230
- // onAuthFailure shape: a repeat failure after the heal is terminal, not
1231
- // looped).
1232
- if ((!parsed.result || parsed.result.trim() === '')
1233
- && allowFreshSessionFallback
1234
- && provider.classifyError(result.stderr || result.stdout) === 'workspace_not_trusted'
1235
- && !trustHealAttempted) {
1236
- trustHealAttempted = true;
1237
- scope.info(`[${resolvedModel}] exit-0/empty-stdout classified as workspace_not_trusted -- self-healing (seedWorkspaceTrust) once, then retrying the dispatch`);
1238
- await seedWorkspaceTrust(agent, strategy, 'execute_prompt');
1239
- const healBudget = retryBudget();
1240
- if (!healBudget.exhausted) {
1401
+ // Server/overloaded error retry -- single attempt after delay. Skipped for
1402
+ // an explicit-id resume (apra-fleet-eft.78.1): the retry starts a fresh
1403
+ // session, which would discard the exact context the caller asked to resume.
1404
+ if (result.code !== 0 && allowFreshSessionFallback && isRetryable(provider.classifyError(result.stderr || result.stdout))) {
1405
+ // apra-fleet-y8q.1: share the remaining max_total_s budget with this
1406
+ // retry too -- skip it outright once exhausted (see retryBudget above).
1407
+ const overloadBudget = retryBudget();
1408
+ if (!overloadBudget.exhausted) {
1409
+ scope.info(`[${resolvedModel}] retrying -- server overloaded`);
1241
1410
  await tryKillPid(agent, strategy, cmds);
1242
- const freshOpts = { ...promptOpts, sessionId: isCallerMinted ? uuid() : undefined, resuming: false };
1411
+ await new Promise(r => setTimeout(r, SERVER_RETRY_DELAY_MS));
1412
+ const freshOpts = { ...promptOpts, sessionId: isCallerMinted ? uuid() : undefined, resuming: false, fork: undefined };
1243
1413
  const retryCmd = authPrefix + cmds.buildAgentPromptCommand(provider, freshOpts);
1244
- result = await strategy.execCommand(retryCmd, healBudget.timeoutMs, healBudget.maxTotalMs, onPidCaptured, dispatchSignal);
1245
- parsed = provider.parseResponse(result);
1414
+ result = await strategy.execCommand(retryCmd, overloadBudget.timeoutMs, overloadBudget.maxTotalMs, onPidCaptured, dispatchSignal);
1415
+ parsed = provider.parseResponse(result, parseCtx);
1246
1416
  if (parsed.usage)
1247
1417
  _epUsage = parsed.usage;
1418
+ const usageLimitResult = checkUsageLimit(result, parsed);
1419
+ if (usageLimitResult)
1420
+ return usageLimitResult;
1248
1421
  }
1249
1422
  }
1250
- if (!parsed.result || parsed.result.trim() === '') {
1251
- const stderrTail = (result.stderr || '').trim().slice(-500);
1252
- const trustClassified = provider.classifyError(result.stderr || result.stdout) === 'workspace_not_trusted';
1423
+ _epExitCode = result.code;
1424
+ // The member CLI refused tool calls for lack of a grant (AGY headless mode
1425
+ // auto-denies them and still exits 0 with status SUCCESS). Report that as
1426
+ // a permission failure the caller can heal via compose_permissions, not
1427
+ // as an empty response. Only providers whose parser sets
1428
+ // permissionDenial reach this; any partial reply is kept.
1429
+ if (parsed.permissionDenial) {
1430
+ const denial = parsed.permissionDenial;
1431
+ const partial = parsed.result?.trim() ? parsed.result.trim() : undefined;
1253
1432
  return {
1254
- text: trustClassified
1255
- ? `[FAIL] ${workspaceNotTrustedAdvice(agent.friendlyName)}\n${stderrTail}`
1256
- : `[FAIL] execute_prompt on "${agent.friendlyName}" exited 0 but produced no parseable output (empty result -- the member CLI likely died mid-turn without printing its result envelope).${stderrTail ? `\n[stderr tail]\n${stderrTail}` : ''}`,
1257
- structuredContent: { isError: true, reason: trustClassified ? 'workspace_not_trusted' : 'empty_response' },
1433
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}": permission denied -- ${denial.hint}${partial ? `\n[partial response]\n${partial}` : ''}`,
1434
+ structuredContent: {
1435
+ isError: true,
1436
+ reason: 'permission_denied',
1437
+ permissionDenied: denial,
1438
+ ...(partial ? { response: partial } : {}),
1439
+ ...(parsed.sessionId ? { sessionId: parsed.sessionId } : {}),
1440
+ ...(_epUsage ? { usage: { input_tokens: _epUsage.input_tokens, output_tokens: _epUsage.output_tokens, total_tokens: _epUsage.input_tokens + _epUsage.output_tokens } } : {}),
1441
+ },
1258
1442
  };
1259
1443
  }
1260
- }
1261
- // Session-id assertion: returned id must match the one we minted/resumed
1262
- const expectedSid = resuming ? resumeTargetId : (isCallerMinted ? mintedId : undefined);
1263
- const isMismatch = expectedSid && parsed.sessionId && parsed.sessionId !== expectedSid;
1264
- if (isMismatch) {
1265
- scope.info(`session-id mismatch: expected=${expectedSid} got=${parsed.sessionId} -- not persisting`);
1266
- if (!allowFreshSessionFallback && explicitResumeId !== undefined) {
1267
- inFlightAgents.delete(agent.id);
1268
- stallDetector.remove(agent.id);
1269
- writeStatusline(new Map([[agent.id, 'idle']]));
1270
- clearStoredPid(agent.id);
1271
- if (parsed.sessionId) {
1272
- recordKnownSession(agent.id, parsed.sessionId);
1273
- }
1274
- if (parsed.usage) {
1275
- const prev = agent.tokenUsage ?? { input: 0, output: 0 };
1276
- updateAgent(agent.id, {
1277
- tokenUsage: {
1278
- input: prev.input + parsed.usage.input_tokens,
1279
- output: prev.output + parsed.usage.output_tokens,
1280
- },
1281
- });
1282
- recordSessionUsage(parsed.sessionId ?? expectedSid, parsed.usage);
1283
- if (budgetScope) {
1284
- await recordAndEvaluate({ scope: budgetScope, agent, provider, tier: resolvedTier, usage: parsed.usage });
1285
- }
1286
- }
1444
+ if (result.code !== 0) {
1445
+ // apra-fleet-391: surface an auth failure as a STRUCTURED reason (not
1446
+ // just prose in `text`) so callers -- notably fleet-sprint's
1447
+ // isAuthDispatchError -- can key off it directly instead of regexing
1448
+ // the message string. Overloading 'nonzero_exit' for this case was
1449
+ // what made auth self-heal impossible to wire reliably upstream.
1450
+ const failureCategory = isMaxTurnsResponse(parsed)
1451
+ ? 'max_turns'
1452
+ : provider.classifyError(result.stderr || result.stdout);
1287
1453
  return {
1288
- text: `[FAIL] execute_prompt on "${agent.friendlyName}" failed -- resumed session mismatch. Expected session "${expectedSid}", but provider returned "${parsed.sessionId}".`,
1454
+ text: buildFailureMessage(agent.friendlyName, result, provider, parsed),
1289
1455
  structuredContent: {
1290
1456
  isError: true,
1291
- reason: 'session_not_found',
1292
- sessionId: expectedSid,
1293
- returnedSessionId: parsed.sessionId,
1294
- ...(parsed.usage ? { usage: { ...parsed.usage, total_tokens: parsed.usage.input_tokens + parsed.usage.output_tokens } } : {}),
1457
+ reason: failureCategory === 'max_turns'
1458
+ ? 'max_turns_exhausted'
1459
+ : failureCategory === 'auth'
1460
+ ? 'auth'
1461
+ : failureCategory === 'server'
1462
+ ? 'server'
1463
+ : failureCategory === 'overloaded'
1464
+ ? 'overloaded'
1465
+ : failureCategory === 'workspace_not_trusted'
1466
+ ? 'workspace_not_trusted'
1467
+ : 'nonzero_exit',
1468
+ // apra-fleet-63x.1: a nonzero exit -- most commonly max_turns_exhausted,
1469
+ // where the CLI ran real turns and burned real tokens before hitting its
1470
+ // ceiling -- still has a REAL parsed usage figure sitting in _epUsage
1471
+ // (captured just above from `parsed.usage` regardless of exit code).
1472
+ // This branch used to return no `usage` field at all on any failure,
1473
+ // so FleetWorkflow.agent() (packages/apra-fleet-workflow/src/workflow/
1474
+ // index.mjs, apra-fleet-202.3) saw hasRealUsage=false and never priced
1475
+ // it, silently under-counting a sprint's tracked spend (observed: a
1476
+ // 10-hour run with dozens of max_turns exhaustions reporting
1477
+ // stats.totalCost of $0). Attach it here whenever it's available so
1478
+ // the caller can record the real partial cost instead of nothing.
1479
+ ...(_epUsage ? { usage: { input_tokens: _epUsage.input_tokens, output_tokens: _epUsage.output_tokens, total_tokens: _epUsage.input_tokens + _epUsage.output_tokens } } : {}),
1295
1480
  },
1296
1481
  };
1297
1482
  }
1298
- touchAgent(agent.id, undefined);
1299
- }
1300
- else {
1301
- touchAgent(agent.id, parsed.sessionId ?? expectedSid);
1302
- }
1303
- // apra-fleet-eft.78.1: mark the session this dispatch actually landed on as
1304
- // known/resumable for this member, so a later explicit-id resume of it
1305
- // passes the terminal session_not_found gate above instead of being
1306
- // rejected as unknown.
1307
- const finalSid = parsed.sessionId ?? expectedSid;
1308
- if (finalSid) {
1309
- recordKnownSession(agent.id, finalSid);
1310
- let postLogPath = null;
1311
- try {
1312
- postLogPath = resolveSessionLogPath(agent.llmProvider ?? 'claude', finalSid, resolvedWorkFolder, memberPathCtx.homeDir, memberPathCtx.targetOs);
1483
+ // Exit 0 but the provider parser extracted NOTHING (no result text)
1484
+ // -- observed live (apra-fleet-eft.14, 2026-07-19 stabilization loop):
1485
+ // the claude CLI can die silently mid-turn (member-side session
1486
+ // transcript stops at a tool_result with no final assistant message)
1487
+ // and still exit 0 with EMPTY stdout, so parseResponse falls through
1488
+ // to its plain-text fallback with result: ''. Returning that as a
1489
+ // success used to hand callers a display wrapper with nothing inside,
1490
+ // which schema-extraction layers then misreported as "LLM returned
1491
+ // invalid JSON". Classify it at the source as a typed dispatch error
1492
+ // instead, with stderr's tail attached for diagnosis.
1493
+ //
1494
+ // apra-fleet-6z8.1 (lease-of-life gate): before declaring that, cross-check
1495
+ // whether the captured pid is STILL ALIVE via a fresh short exec. ssh.ts
1496
+ // substitutes code 0 when the channel closes without ever receiving an
1497
+ // 'exit' event, so "exit 0 + empty" is ALSO exactly what a torn-down
1498
+ // channel over a perfectly healthy, still-running turn looks like (live
1499
+ // evidence: pid 89858 running 2+ minutes past the close). Declaring
1500
+ // empty_response there orphans the CLI and invites a duplicate concurrent
1501
+ // dispatch of the same scope. A confirmed-dead pid keeps today's behavior
1502
+ // verbatim.
1503
+ if (!parsed.result || parsed.result.trim() === '') {
1504
+ const recovery = await recoverOrphanedDispatch({
1505
+ strategy,
1506
+ cmds,
1507
+ pid: capturedPid,
1508
+ durablePath,
1509
+ // apra-fleet-7dir.5.4: the SAME predicate that decides `durablePath`
1510
+ // above -- the mirror and recovery are one decision, and enabling
1511
+ // either alone is inert (no file to read / a file nothing reads).
1512
+ unsupported: !durableMirrorSupported,
1513
+ os: getAgentOS(agent),
1514
+ // Live for gitbash members now that `unsupported` no longer
1515
+ // short-circuits every Windows member: it selects the POSIX
1516
+ // `kill -0` / `cat` probes over the PowerShell ones (apra-fleet-7dir.2.4).
1517
+ shell: getAgentShell(agent),
1518
+ maxWaitMs: maxTotalMs !== undefined ? Math.max(maxTotalMs - (Date.now() - dispatchStartedAt), 0) : undefined,
1519
+ scope,
1520
+ });
1521
+ if (recovery.status === 'timeout') {
1522
+ scope.info(`orphan recovery timed out after ${Math.round((recovery.waitedMs ?? 0) / 1000)}s -- pid killed`);
1523
+ return {
1524
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}" lost its SSH channel while the member CLI (pid ${capturedPid}) was still running, and that process was still alive after the recovery window (${Math.round((recovery.waitedMs ?? 0) / 1000)}s). The process has been killed; no result was recovered. This is NOT an empty response -- do not treat it as a failed turn without checking the member's session transcript first.`,
1525
+ structuredContent: { isError: true, reason: 'orphan_recovery_timeout' },
1526
+ };
1527
+ }
1528
+ if (recovery.status === 'recovered' && recovery.stdout) {
1529
+ // Feed the durable output through the normal provider parse path,
1530
+ // exactly as if it had arrived on the original channel.
1531
+ const recoveredResult = { stdout: recovery.stdout, stderr: result.stderr ?? '', code: 0 };
1532
+ const recoveredParsed = provider.parseResponse(recoveredResult, parseCtx);
1533
+ if (recoveredParsed.result && recoveredParsed.result.trim() !== '') {
1534
+ scope.info(`recovered the real result from the durable output file after a false-alarm empty_response (waited ${Math.round((recovery.waitedMs ?? 0) / 1000)}s)`);
1535
+ parsed = recoveredParsed;
1536
+ if (parsed.usage)
1537
+ _epUsage = parsed.usage;
1538
+ const usageLimitResult = checkUsageLimit(recoveredResult, recoveredParsed);
1539
+ if (usageLimitResult)
1540
+ return usageLimitResult;
1541
+ }
1542
+ }
1543
+ // apra-fleet-6a7.1: the code!==0 workspace_not_trusted classification
1544
+ // above (~line 1048) never sees this branch -- exit 0 + empty stdout is
1545
+ // a SEPARATE path, but live evidence (apra-fleet-2g2, fleet-win-dev1,
1546
+ // 2026-08-02) showed it can be caused by the exact same trust-gate
1547
+ // failure: exited 0, empty stdout, and the stderr tail contained the
1548
+ // exact matched phrase, so the code!==0 classifier never ran. Classify
1549
+ // it here too and -- unlike that path, which only advises a manual fix
1550
+ // -- self-heal via the same seedWorkspaceTrust/ensureWorkspaceTrusted
1551
+ // path compose_permissions already uses, then retry the dispatch
1552
+ // exactly once (gated by trustHealAttempted, mirroring runGitStep's
1553
+ // onAuthFailure shape: a repeat failure after the heal is terminal, not
1554
+ // looped).
1555
+ if ((!parsed.result || parsed.result.trim() === '')
1556
+ && allowFreshSessionFallback
1557
+ && provider.classifyError(result.stderr || result.stdout) === 'workspace_not_trusted'
1558
+ && !trustHealAttempted) {
1559
+ trustHealAttempted = true;
1560
+ scope.info(`[${resolvedModel}] exit-0/empty-stdout classified as workspace_not_trusted -- self-healing (seedWorkspaceTrust) once, then retrying the dispatch`);
1561
+ await seedWorkspaceTrust(agent, strategy, 'execute_prompt');
1562
+ const healBudget = retryBudget();
1563
+ if (!healBudget.exhausted) {
1564
+ await tryKillPid(agent, strategy, cmds);
1565
+ const freshOpts = { ...promptOpts, sessionId: isCallerMinted ? uuid() : undefined, resuming: false, fork: undefined };
1566
+ const retryCmd = authPrefix + cmds.buildAgentPromptCommand(provider, freshOpts);
1567
+ result = await strategy.execCommand(retryCmd, healBudget.timeoutMs, healBudget.maxTotalMs, onPidCaptured, dispatchSignal);
1568
+ parsed = provider.parseResponse(result, parseCtx);
1569
+ if (parsed.usage)
1570
+ _epUsage = parsed.usage;
1571
+ const usageLimitResult = checkUsageLimit(result, parsed);
1572
+ if (usageLimitResult)
1573
+ return usageLimitResult;
1574
+ }
1575
+ }
1576
+ if (!parsed.result || parsed.result.trim() === '') {
1577
+ const stderrTail = (result.stderr || '').trim().slice(-500);
1578
+ const trustClassified = provider.classifyError(result.stderr || result.stdout) === 'workspace_not_trusted';
1579
+ return {
1580
+ text: trustClassified
1581
+ ? `[FAIL] ${workspaceNotTrustedAdvice(agent.friendlyName)}\n${stderrTail}`
1582
+ : `[FAIL] execute_prompt on "${agent.friendlyName}" exited 0 but produced no parseable output (empty result -- the member CLI likely died mid-turn without printing its result envelope).${stderrTail ? `\n[stderr tail]\n${stderrTail}` : ''}`,
1583
+ structuredContent: { isError: true, reason: trustClassified ? 'workspace_not_trusted' : 'empty_response' },
1584
+ };
1585
+ }
1313
1586
  }
1314
- catch {
1315
- postLogPath = null;
1587
+ // Session-id assertion: returned id must match the one we minted/resumed.
1588
+ // apra-fleet-lmtg.5: a fork now gets the SAME assertion as any other
1589
+ // caller-minted session. mintedId is explicitly passed to the CLI as
1590
+ // --session-id even in fork mode (provider.forkFlag/buildForkFlag), and the
1591
+ // CLI honors it -- so it is no longer a placeholder the CLI silently
1592
+ // discards, and a genuine mismatch here is a real signal worth catching
1593
+ // rather than something to exempt.
1594
+ const expectedSid = resuming ? resumeTargetId : (isCallerMinted ? mintedId : undefined);
1595
+ const isMismatch = expectedSid && parsed.sessionId && parsed.sessionId !== expectedSid;
1596
+ if (isMismatch) {
1597
+ scope.info(`session-id mismatch: expected=${expectedSid} got=${parsed.sessionId} -- not persisting`);
1598
+ if (!allowFreshSessionFallback && (explicitResumeId !== undefined || explicitForkId !== undefined)) {
1599
+ inFlightAgents.delete(agent.id);
1600
+ stallDetector.remove(agent.id);
1601
+ writeStatusline(new Map([[agent.id, 'idle']]));
1602
+ clearStoredPid(agent.id);
1603
+ if (parsed.sessionId) {
1604
+ recordKnownSession(agent.id, parsed.sessionId);
1605
+ }
1606
+ if (parsed.usage) {
1607
+ const prev = agent.tokenUsage ?? { input: 0, output: 0 };
1608
+ updateAgent(agent.id, {
1609
+ tokenUsage: {
1610
+ input: prev.input + parsed.usage.input_tokens,
1611
+ output: prev.output + parsed.usage.output_tokens,
1612
+ },
1613
+ });
1614
+ recordSessionUsage(parsed.sessionId ?? expectedSid, parsed.usage);
1615
+ if (budgetScope) {
1616
+ await recordAndEvaluate({ scope: budgetScope, agent, provider, tier: resolvedTier, usage: parsed.usage });
1617
+ }
1618
+ }
1619
+ return {
1620
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}" failed -- resumed session mismatch. Expected session "${expectedSid}", but provider returned "${parsed.sessionId}".`,
1621
+ structuredContent: {
1622
+ isError: true,
1623
+ reason: 'session_not_found',
1624
+ sessionId: expectedSid,
1625
+ returnedSessionId: parsed.sessionId,
1626
+ ...(parsed.usage ? { usage: { ...parsed.usage, total_tokens: parsed.usage.input_tokens + parsed.usage.output_tokens } } : {}),
1627
+ },
1628
+ };
1629
+ }
1630
+ touchAgent(agent.id, undefined);
1316
1631
  }
1317
- stallDetector.update(agent.id, {
1318
- sessionId: finalSid,
1319
- logFilePath: postLogPath,
1320
- provisional: !postLogPath,
1321
- });
1322
- }
1323
- clearStoredPid(agent.id);
1324
- if (parsed.usage) {
1325
- const prev = agent.tokenUsage ?? { input: 0, output: 0 };
1326
- updateAgent(agent.id, {
1327
- tokenUsage: {
1328
- input: prev.input + parsed.usage.input_tokens,
1329
- output: prev.output + parsed.usage.output_tokens,
1330
- },
1331
- });
1332
- // Per-session cumulative tracking for context-headroom admission
1333
- // (apra-fleet-eft.81.1) -- separate from the per-member lifetime total
1334
- // just above. Keyed by whichever session id this dispatch actually
1335
- // landed on (the returned id, falling back to the minted/resumed one),
1336
- // so the NEXT admission check on this same session sees this dispatch's
1337
- // usage already accounted for.
1338
- recordSessionUsage(parsed.sessionId ?? mintedId, parsed.usage);
1339
- }
1340
- // Usage/budget accounting (apra-fleet-eft.80.2): account this dispatch's
1341
- // token usage against the scope's budget (self-metered only when the
1342
- // provider has no native getUsage()), then attach the usage block to the
1343
- // result when the warning band is crossed. Nothing is attached below the
1344
- // band, and nothing happens at all when no budget is configured.
1345
- let budgetUsage;
1346
- if (budgetScope && parsed.usage) {
1347
- const postBudget = await recordAndEvaluate({ scope: budgetScope, agent, provider, tier: resolvedTier, usage: parsed.usage });
1348
- if (postBudget?.warned)
1349
- budgetUsage = postBudget.block;
1350
- }
1351
- let output = `[RESULT] Response from ${agent.friendlyName}:
1632
+ else {
1633
+ touchAgent(agent.id, parsed.sessionId ?? expectedSid);
1634
+ }
1635
+ // apra-fleet-eft.78.1: mark the session this dispatch actually landed on as
1636
+ // known/resumable for this member, so a later explicit-id resume of it
1637
+ // passes the terminal session_not_found gate above instead of being
1638
+ // rejected as unknown.
1639
+ const finalSid = parsed.sessionId ?? expectedSid;
1640
+ if (finalSid) {
1641
+ recordKnownSession(agent.id, finalSid);
1642
+ let postLogPath = null;
1643
+ try {
1644
+ postLogPath = resolveSessionLogPath(agent.llmProvider ?? 'claude', finalSid, resolvedWorkFolder, memberPathCtx.homeDir, memberPathCtx.targetOs);
1645
+ }
1646
+ catch {
1647
+ postLogPath = null;
1648
+ }
1649
+ stallDetector.update(agent.id, {
1650
+ sessionId: finalSid,
1651
+ logFilePath: postLogPath,
1652
+ provisional: !postLogPath,
1653
+ thresholdMs: stallThresholdMs,
1654
+ });
1655
+ }
1656
+ clearStoredPid(agent.id);
1657
+ if (parsed.usage) {
1658
+ const prev = agent.tokenUsage ?? { input: 0, output: 0 };
1659
+ updateAgent(agent.id, {
1660
+ tokenUsage: {
1661
+ input: prev.input + parsed.usage.input_tokens,
1662
+ output: prev.output + parsed.usage.output_tokens,
1663
+ },
1664
+ });
1665
+ // Per-session cumulative tracking for context-headroom admission
1666
+ // (apra-fleet-eft.81.1) -- separate from the per-member lifetime total
1667
+ // just above. Keyed by whichever session id this dispatch actually
1668
+ // landed on (the returned id, falling back to the minted/resumed one),
1669
+ // so the NEXT admission check on this same session sees this dispatch's
1670
+ // usage already accounted for.
1671
+ recordSessionUsage(parsed.sessionId ?? mintedId, parsed.usage);
1672
+ }
1673
+ // Usage/budget accounting (apra-fleet-eft.80.2): account this dispatch's
1674
+ // token usage against the scope's budget (self-metered only when the
1675
+ // provider has no native getUsage()), then attach the usage block to the
1676
+ // result when the warning band is crossed. Nothing is attached below the
1677
+ // band, and nothing happens at all when no budget is configured.
1678
+ let budgetUsage;
1679
+ if (budgetScope && parsed.usage) {
1680
+ const postBudget = await recordAndEvaluate({ scope: budgetScope, agent, provider, tier: resolvedTier, usage: parsed.usage });
1681
+ if (postBudget?.warned)
1682
+ budgetUsage = postBudget.block;
1683
+ }
1684
+ let output = `[RESULT] Response from ${agent.friendlyName}:
1352
1685
 
1353
1686
  ${parsed.result}`;
1354
- if (parsed.sessionId)
1355
- output += `
1687
+ if (parsed.sessionId)
1688
+ output += `
1356
1689
 
1357
1690
  ---
1358
1691
  session: ${parsed.sessionId}`;
1359
- // Auto-harvest learnings from session output (fire-and-forget)
1360
- if (parsed.result) {
1361
- // apra-fleet-tm7.2: always pass resolvedWorkFolder, local or remote.
1362
- // getKbProviders(undefined) falls back to slugFor(process.cwd()) --
1363
- // the FLEET SERVER's own cwd, not any generic 'default' -- so omitting
1364
- // repo_path for remote members would silently route their harvested
1365
- // learnings into the server's own repo KB (the exact defect apra-fleet-tm7
1366
- // describes).
1367
- //
1368
- // apra-fleet-b4g.6: repo_remote_url (apra-fleet-b4g.1) is how a REMOTE
1369
- // member's call reaches the SAME shared project KB a local clone would --
1370
- // without it, resolvedWorkFolder is a path on the remote host that will
1371
- // almost never exist on this (fleet server) machine, resolveProjectSlug's
1372
- // git calls on it fail with ENOENT, and it falls through to the literal
1373
- // 'default' slug, pooling every such member's harvest into one shared,
1374
- // useless bucket (no cross-repo contamination, but no real routing
1375
- // either). knownRepoRemoteUrl() forwards it whenever the member's own
1376
- // registration record already carries a genuine URL. It deliberately does
1377
- // NOT construct one from agent.gitRepos' bare "owner/repo" access-list
1378
- // entries (see src/services/vcs/github.ts's own
1379
- // https://github.com/${repo}.git construction for a DIFFERENT, narrower
1380
- // purpose -- connectivity testing) or shell out to the member host to
1381
- // discover it: guessing a URL that turns out wrong would route the
1382
- // harvest into a KB slug that does not match the repo's real local-clone
1383
- // slug, which is worse than today's honest 'default' degradation. When no
1384
- // genuine URL is known, behaviour is unchanged from before this fix.
1385
- // KB-TRUST PHASE 1 (apra-fleet-4wz.8): report the harvest counters. This is
1386
- // the highest-volume KB writer and its result was previously discarded
1387
- // entirely, so entries_rejected -- the fail-closed signal -- was invisible
1388
- // on the one path that produces most of it. Rejections are EXPECTED to
1389
- // dominate here: harvest's regex extraction frequently yields no file
1390
- // paths at all, and an entry with no basis is refused by design. A high
1391
- // rejected count is the invariant working, not a regression to tune away.
1392
- void import('./kb-harvest.js')
1393
- .then(({ kbHarvest }) => kbHarvest({
1394
- repo_path: resolvedWorkFolder,
1395
- repo_remote_url: knownRepoRemoteUrl(agent),
1396
- session_transcript: parsed.result,
1397
- session_id: parsed.sessionId,
1398
- }))
1399
- .then((raw) => {
1400
- try {
1401
- const r = JSON.parse(raw);
1402
- if (r.entries_captured || r.entries_updated || r.entries_skipped || r.entries_rejected) {
1403
- logLine('kb_harvest', `auto-harvest: captured=${r.entries_captured} updated=${r.entries_updated} skipped=${r.entries_skipped} rejected=${r.entries_rejected}`);
1692
+ // Auto-harvest learnings from session output (fire-and-forget)
1693
+ if (parsed.result) {
1694
+ // apra-fleet-tm7.2: always pass resolvedWorkFolder, local or remote.
1695
+ // getKbProviders(undefined) falls back to slugFor(process.cwd()) --
1696
+ // the FLEET SERVER's own cwd, not any generic 'default' -- so omitting
1697
+ // repo_path for remote members would silently route their harvested
1698
+ // learnings into the server's own repo KB (the exact defect apra-fleet-tm7
1699
+ // describes).
1700
+ //
1701
+ // apra-fleet-b4g.6: repo_remote_url (apra-fleet-b4g.1) is how a REMOTE
1702
+ // member's call reaches the SAME shared project KB a local clone would --
1703
+ // without it, resolvedWorkFolder is a path on the remote host that will
1704
+ // almost never exist on this (fleet server) machine, resolveProjectSlug's
1705
+ // git calls on it fail with ENOENT, and it falls through to the literal
1706
+ // 'default' slug, pooling every such member's harvest into one shared,
1707
+ // useless bucket (no cross-repo contamination, but no real routing
1708
+ // either). knownRepoRemoteUrl() forwards it whenever the member's own
1709
+ // registration record already carries a genuine URL. It deliberately does
1710
+ // NOT construct one from agent.gitRepos' bare "owner/repo" access-list
1711
+ // entries (see src/services/vcs/github.ts's own
1712
+ // https://github.com/${repo}.git construction for a DIFFERENT, narrower
1713
+ // purpose -- connectivity testing) or shell out to the member host to
1714
+ // discover it: guessing a URL that turns out wrong would route the
1715
+ // harvest into a KB slug that does not match the repo's real local-clone
1716
+ // slug, which is worse than today's honest 'default' degradation. When no
1717
+ // genuine URL is known, behaviour is unchanged from before this fix.
1718
+ // KB-TRUST PHASE 1 (apra-fleet-4wz.8): report the harvest counters. This is
1719
+ // the highest-volume KB writer and its result was previously discarded
1720
+ // entirely, so entries_rejected -- the fail-closed signal -- was invisible
1721
+ // on the one path that produces most of it. Rejections are EXPECTED to
1722
+ // dominate here: harvest's regex extraction frequently yields no file
1723
+ // paths at all, and an entry with no basis is refused by design. A high
1724
+ // rejected count is the invariant working, not a regression to tune away.
1725
+ void import('./kb-harvest.js')
1726
+ .then(({ kbHarvest }) => kbHarvest({
1727
+ repo_path: resolvedWorkFolder,
1728
+ repo_remote_url: knownRepoRemoteUrl(agent),
1729
+ session_transcript: parsed.result,
1730
+ session_id: parsed.sessionId,
1731
+ }))
1732
+ .then((raw) => {
1733
+ try {
1734
+ const r = JSON.parse(raw);
1735
+ if (r.entries_captured || r.entries_updated || r.entries_skipped || r.entries_rejected) {
1736
+ logLine('kb_harvest', `auto-harvest: captured=${r.entries_captured} updated=${r.entries_updated} skipped=${r.entries_skipped} rejected=${r.entries_rejected}`);
1737
+ }
1404
1738
  }
1405
- }
1406
- catch {
1407
- // A non-JSON payload is not worth failing a fire-and-forget harvest over.
1408
- }
1409
- })
1410
- .catch((err) => logWarn('kb_harvest', `auto-harvest failed: ${err.message}`));
1739
+ catch {
1740
+ // A non-JSON payload is not worth failing a fire-and-forget harvest over.
1741
+ }
1742
+ })
1743
+ .catch((err) => logWarn('kb_harvest', `auto-harvest failed: ${err.message}`));
1744
+ }
1745
+ if (heuristicWarningSuffix)
1746
+ output += heuristicWarningSuffix;
1747
+ return {
1748
+ text: output,
1749
+ structuredContent: {
1750
+ response: parsed.result,
1751
+ ...(_epUsage ? { usage: { input_tokens: _epUsage.input_tokens, output_tokens: _epUsage.output_tokens, total_tokens: _epUsage.input_tokens + _epUsage.output_tokens } } : {}),
1752
+ ...(parsed.sessionId ? { sessionId: parsed.sessionId } : {}),
1753
+ ...(contextWarning ? { contextWarning } : {}),
1754
+ ...(budgetUsage ? { budgetUsage } : {}),
1755
+ },
1756
+ };
1411
1757
  }
1412
- if (heuristicWarningSuffix)
1413
- output += heuristicWarningSuffix;
1414
- return {
1415
- text: output,
1416
- structuredContent: {
1417
- response: parsed.result,
1418
- ...(_epUsage ? { usage: { input_tokens: _epUsage.input_tokens, output_tokens: _epUsage.output_tokens, total_tokens: _epUsage.input_tokens + _epUsage.output_tokens } } : {}),
1419
- ...(parsed.sessionId ? { sessionId: parsed.sessionId } : {}),
1420
- ...(contextWarning ? { contextWarning } : {}),
1421
- ...(budgetUsage ? { budgetUsage } : {}),
1422
- },
1423
- };
1424
- }
1425
- catch (err) {
1426
- // apra-fleet-3c9.1: a confirmed stall aborted the in-flight execCommand (and
1427
- // NOT the MCP client). Surface it as a typed 'stalled' error so the dispatch
1428
- // settles here -- well under the client hard timeout -- instead of being
1429
- // mislabeled dispatch_failed or waiting out the full deadline.
1430
- if (stallAbortController.signal.aborted && !extra?.signal?.aborted) {
1431
- _epError = 'dispatch aborted by confirmed stall';
1758
+ catch (err) {
1759
+ // apra-fleet-3c9.1: a confirmed stall aborted the in-flight execCommand (and
1760
+ // NOT the MCP client). Surface it as a typed 'stalled' error so the dispatch
1761
+ // settles here -- well under the client hard timeout -- instead of being
1762
+ // mislabeled dispatch_failed or waiting out the full deadline.
1763
+ if (stallAbortController.signal.aborted && !extra?.signal?.aborted) {
1764
+ _epError = 'dispatch aborted by confirmed stall';
1765
+ return {
1766
+ text: `[FAIL] execute_prompt on "${agent.friendlyName}" was aborted after a confirmed stall -- the remote turn made no progress for the stall threshold, its process was killed, and the in-flight dispatch was cancelled immediately rather than waiting out the client timeout.`,
1767
+ structuredContent: { isError: true, reason: 'stalled' },
1768
+ };
1769
+ }
1770
+ // Only mark offline for genuine SSH/network connection failures, not for cancellations
1771
+ _epOffline = !!(err.message && /ssh|network|econnrefused|ehostunreach|connection timed out/i.test(err.message));
1772
+ _epError = err.message;
1432
1773
  return {
1433
- text: `[FAIL] execute_prompt on "${agent.friendlyName}" was aborted after a confirmed stall -- the remote turn made no progress for the stall threshold, its process was killed, and the in-flight dispatch was cancelled immediately rather than waiting out the client timeout.`,
1434
- structuredContent: { isError: true, reason: 'stalled' },
1774
+ text: `[FAIL] Failed to execute prompt on "${agent.friendlyName}": ${err.message}`,
1775
+ structuredContent: { isError: true, reason: 'dispatch_failed' },
1435
1776
  };
1436
1777
  }
1437
- // Only mark offline for genuine SSH/network connection failures, not for cancellations
1438
- _epOffline = !!(err.message && /ssh|network|econnrefused|ehostunreach|connection timed out/i.test(err.message));
1439
- _epError = err.message;
1440
- return {
1441
- text: `[FAIL] Failed to execute prompt on "${agent.friendlyName}": ${err.message}`,
1442
- structuredContent: { isError: true, reason: 'dispatch_failed' },
1443
- };
1778
+ finally {
1779
+ extra?.signal?.removeEventListener('abort', abortHandler);
1780
+ const _epTok = _epUsage ? ` in=${_epUsage.input_tokens} out=${_epUsage.output_tokens}` : '';
1781
+ if (_epExitCode === 'error')
1782
+ scope.abort(`${_epError ?? 'exception'}${_epTok}`);
1783
+ else if (_epExitCode !== 0)
1784
+ scope.fail(`exit=${_epExitCode}${_epTok}`);
1785
+ else
1786
+ scope.ok(`exit=0${_epTok}`);
1787
+ // Skip if stall detector already cleared state -- a new execute_prompt may have
1788
+ // claimed inFlightAgents and set busy again; clobbering it here would be wrong.
1789
+ if (!clearedByStall) {
1790
+ writeStatusline(new Map([[agent.id, _epOffline ? 'offline' : 'idle']]));
1791
+ inFlightAgents.delete(agent.id);
1792
+ }
1793
+ stallDetector.remove(agent.id);
1794
+ await deletePromptFile(agent, strategy, promptFilePath, durablePath ? [durablePath] : []);
1795
+ }
1444
1796
  }
1445
- finally {
1446
- extra?.signal?.removeEventListener('abort', abortHandler);
1447
- const _epTok = _epUsage ? ` in=${_epUsage.input_tokens} out=${_epUsage.output_tokens}` : '';
1448
- if (_epExitCode === 'error')
1449
- scope.abort(`${_epError ?? 'exception'}${_epTok}`);
1450
- else if (_epExitCode !== 0)
1451
- scope.fail(`exit=${_epExitCode}${_epTok}`);
1452
- else
1453
- scope.ok(`exit=0${_epTok}`);
1454
- // Skip if stall detector already cleared state -- a new execute_prompt may have
1455
- // claimed inFlightAgents and set busy again; clobbering it here would be wrong.
1456
- if (!clearedByStall) {
1457
- writeStatusline(new Map([[agent.id, _epOffline ? 'offline' : 'idle']]));
1797
+ catch (err) {
1798
+ if (claimGuardActive) {
1458
1799
  inFlightAgents.delete(agent.id);
1800
+ getStallDetector().remove(agent.id);
1459
1801
  }
1460
- stallDetector.remove(agent.id);
1461
- await deletePromptFile(agent, strategy, promptFilePath, durablePath ? [durablePath] : []);
1802
+ throw err;
1462
1803
  }
1463
1804
  }
1464
1805
  //# sourceMappingURL=execute-prompt.js.map