@apralabs/apra-fleet 0.4.3 → 0.4.5

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 (1027) hide show
  1. package/README.md +114 -33
  2. package/dist/agents/backlog-groomer.md +80 -27
  3. package/dist/agents/ci-watcher.md +42 -22
  4. package/dist/agents/deployer.md +59 -24
  5. package/dist/agents/doer.md +111 -41
  6. package/dist/agents/harvester.md +60 -48
  7. package/dist/agents/integ-test-runner.md +45 -23
  8. package/dist/agents/kb-reconciler.md +34 -7
  9. package/dist/agents/plan-reviewer.md +54 -24
  10. package/dist/agents/planner.md +71 -43
  11. package/dist/agents/regression-test-runner.md +106 -78
  12. package/dist/agents/reviewer.md +170 -57
  13. package/dist/agents/schemas/backlog-groomer-output.json +1 -1
  14. package/dist/agents/schemas/deployer-output.json +5 -0
  15. package/dist/agents/schemas/doer-output.json +110 -2
  16. package/dist/agents/schemas/harvester-input.json +1 -5
  17. package/dist/agents/schemas/planner-output.json +1 -1
  18. package/dist/agents/schemas/regression-test-runner-output.json +41 -7
  19. package/dist/agents/schemas/reviewer-output.json +166 -5
  20. package/dist/cli/agent-transform.d.ts +7 -0
  21. package/dist/cli/agent-transform.js +46 -1
  22. package/dist/cli/auth.d.ts +1 -0
  23. package/dist/cli/auth.js +42 -8
  24. package/dist/cli/beads-install.d.ts +35 -0
  25. package/dist/cli/beads-install.js +125 -0
  26. package/dist/cli/beads-pin.d.ts +5 -0
  27. package/dist/cli/beads-pin.js +26 -0
  28. package/dist/cli/call.d.ts +27 -0
  29. package/dist/cli/call.js +177 -0
  30. package/dist/cli/claude-mod.d.ts +75 -0
  31. package/dist/cli/claude-mod.js +288 -0
  32. package/dist/cli/config.d.ts +24 -1
  33. package/dist/cli/config.js +69 -2
  34. package/dist/cli/dolt-install.d.ts +19 -3
  35. package/dist/cli/dolt-install.js +51 -16
  36. package/dist/cli/fleet-se-guard.d.ts +59 -0
  37. package/dist/cli/fleet-se-guard.js +231 -0
  38. package/dist/cli/install-guard.d.ts +63 -0
  39. package/dist/cli/install-guard.js +156 -4
  40. package/dist/cli/install.d.ts +89 -21
  41. package/dist/cli/install.js +778 -160
  42. package/dist/cli/kb-commit.d.ts +2 -1
  43. package/dist/cli/kb-commit.js +1 -1
  44. package/dist/cli/kb-import.d.ts +2 -1
  45. package/dist/cli/kb-import.js +1 -1
  46. package/dist/cli/kb-profile.d.ts +16 -0
  47. package/dist/cli/kb-profile.js +81 -0
  48. package/dist/cli/register-member.js +20 -3
  49. package/dist/cli/remove-member.d.ts +4 -0
  50. package/dist/cli/remove-member.js +63 -0
  51. package/dist/cli/secret.js +9 -0
  52. package/dist/cli/start.js +62 -4
  53. package/dist/cli/status.d.ts +3 -0
  54. package/dist/cli/status.js +45 -12
  55. package/dist/cli/stop.js +64 -9
  56. package/dist/cli/uninstall.js +112 -16
  57. package/dist/cli/update.d.ts +4 -0
  58. package/dist/cli/update.js +52 -5
  59. package/dist/cli/watch.js +1 -1
  60. package/dist/cli/workflow.js +3 -2
  61. package/dist/commands/kb-server.d.ts +10 -1
  62. package/dist/commands/kb-server.js +292 -11
  63. package/dist/hub-service/http-server.d.ts +5 -1
  64. package/dist/hub-service/http-server.js +55 -5
  65. package/dist/index.js +177 -9
  66. package/dist/os/child-env-bound.d.ts +77 -0
  67. package/dist/os/child-env-bound.js +171 -0
  68. package/dist/os/git-executable.d.ts +57 -0
  69. package/dist/os/git-executable.js +85 -0
  70. package/dist/os/go-concurrency.d.ts +44 -0
  71. package/dist/os/go-concurrency.js +53 -0
  72. package/dist/os/index.d.ts +1 -0
  73. package/dist/os/index.js +1 -0
  74. package/dist/os/linux.d.ts +9 -2
  75. package/dist/os/linux.js +50 -15
  76. package/dist/os/macos.d.ts +1 -1
  77. package/dist/os/macos.js +2 -11
  78. package/dist/os/os-commands.d.ts +42 -2
  79. package/dist/os/os-commands.js +2 -0
  80. package/dist/os/windows-executable.d.ts +53 -0
  81. package/dist/os/windows-executable.js +185 -0
  82. package/dist/os/windows-gitbash.d.ts +24 -14
  83. package/dist/os/windows-gitbash.js +56 -18
  84. package/dist/os/windows-wrapper.d.ts +0 -4
  85. package/dist/os/windows-wrapper.js +2 -1
  86. package/dist/os/windows.d.ts +7 -2
  87. package/dist/os/windows.js +109 -32
  88. package/dist/paths.d.ts +30 -0
  89. package/dist/paths.js +52 -0
  90. package/dist/providers/agy.d.ts +6 -2
  91. package/dist/providers/agy.js +245 -106
  92. package/dist/providers/claude-permission-denial.d.ts +7 -0
  93. package/dist/providers/claude-permission-denial.js +137 -0
  94. package/dist/providers/claude.d.ts +86 -38
  95. package/dist/providers/claude.js +426 -164
  96. package/dist/providers/codex.js +5 -1
  97. package/dist/providers/copilot.js +5 -1
  98. package/dist/providers/opencode.d.ts +10 -2
  99. package/dist/providers/opencode.js +114 -53
  100. package/dist/providers/provider.d.ts +171 -33
  101. package/dist/providers/provider.js +164 -3
  102. package/dist/services/agent-provisioner.d.ts +29 -0
  103. package/dist/services/agent-provisioner.js +107 -0
  104. package/dist/services/agent-shadow.d.ts +96 -0
  105. package/dist/services/agent-shadow.js +479 -0
  106. package/dist/services/agy-project.d.ts +9 -2
  107. package/dist/services/agy-project.js +22 -19
  108. package/dist/services/auth-socket.d.ts +43 -0
  109. package/dist/services/auth-socket.js +97 -26
  110. package/dist/services/auth-web.js +1 -1
  111. package/dist/services/budget-awareness.d.ts +11 -11
  112. package/dist/services/budget-awareness.js +15 -3
  113. package/dist/services/claude-local-scope-mcp.d.ts +19 -0
  114. package/dist/services/claude-local-scope-mcp.js +91 -0
  115. package/dist/services/cloud/aws.js +2 -1
  116. package/dist/services/cloud/lifecycle.js +19 -2
  117. package/dist/services/cloud/task-wrapper.d.ts +0 -9
  118. package/dist/services/cloud/task-wrapper.js +15 -6
  119. package/dist/services/credential-store.d.ts +33 -0
  120. package/dist/services/credential-store.js +79 -2
  121. package/dist/services/event-loop-watchdog.d.ts +32 -0
  122. package/dist/services/event-loop-watchdog.js +140 -0
  123. package/dist/services/http-transport.d.ts +78 -1
  124. package/dist/services/http-transport.js +347 -52
  125. package/dist/services/in-flight-agents.d.ts +2 -0
  126. package/dist/services/in-flight-agents.js +4 -0
  127. package/dist/services/kb-tool-profile.d.ts +36 -0
  128. package/dist/services/kb-tool-profile.js +88 -0
  129. package/dist/services/knowledge/bible-basis-filter.d.ts +53 -0
  130. package/dist/services/knowledge/bible-basis-filter.js +134 -0
  131. package/dist/services/knowledge/bible-blob-id.d.ts +44 -0
  132. package/dist/services/knowledge/bible-blob-id.js +122 -0
  133. package/dist/services/knowledge/bible-import.d.ts +173 -0
  134. package/dist/services/knowledge/bible-import.js +344 -0
  135. package/dist/services/knowledge/file-hash.d.ts +31 -0
  136. package/dist/services/knowledge/file-hash.js +155 -24
  137. package/dist/services/knowledge/http-provider.d.ts +305 -21
  138. package/dist/services/knowledge/http-provider.js +801 -119
  139. package/dist/services/knowledge/kb-config.d.ts +65 -1
  140. package/dist/services/knowledge/kb-config.js +143 -3
  141. package/dist/services/knowledge/kb-http-auth-state.d.ts +26 -0
  142. package/dist/services/knowledge/kb-http-auth-state.js +40 -0
  143. package/dist/services/knowledge/kb-maintainer-grant.d.ts +15 -0
  144. package/dist/services/knowledge/kb-maintainer-grant.js +34 -0
  145. package/dist/services/knowledge/kb-providers.d.ts +13 -2
  146. package/dist/services/knowledge/kb-providers.js +75 -37
  147. package/dist/services/knowledge/kb-removed-scope-keys.d.ts +28 -0
  148. package/dist/services/knowledge/kb-removed-scope-keys.js +59 -0
  149. package/dist/services/knowledge/kb-scopes.d.ts +14 -0
  150. package/dist/services/knowledge/kb-scopes.js +47 -0
  151. package/dist/services/knowledge/kb-self.d.ts +204 -0
  152. package/dist/services/knowledge/kb-self.js +358 -0
  153. package/dist/services/knowledge/member-bible-view.d.ts +21 -0
  154. package/dist/services/knowledge/member-bible-view.js +207 -0
  155. package/dist/services/knowledge/path-validation.d.ts +7 -0
  156. package/dist/services/knowledge/path-validation.js +11 -0
  157. package/dist/services/knowledge/pre-init.js +1 -0
  158. package/dist/services/knowledge/project-slug.js +5 -4
  159. package/dist/services/knowledge/repository-header.d.ts +77 -0
  160. package/dist/services/knowledge/repository-header.js +233 -0
  161. package/dist/services/knowledge/require-sqlite-project.d.ts +1 -1
  162. package/dist/services/knowledge/require-sqlite-project.js +1 -1
  163. package/dist/services/knowledge/sqlite-provider.d.ts +233 -11
  164. package/dist/services/knowledge/sqlite-provider.js +719 -45
  165. package/dist/services/knowledge/types.d.ts +59 -3
  166. package/dist/services/member-access-secret.d.ts +70 -0
  167. package/dist/services/member-access-secret.js +195 -0
  168. package/dist/services/member-busy.d.ts +12 -0
  169. package/dist/services/member-busy.js +20 -0
  170. package/dist/services/member-call-counts.d.ts +24 -0
  171. package/dist/services/member-call-counts.js +58 -0
  172. package/dist/services/member-config-io.d.ts +193 -0
  173. package/dist/services/member-config-io.js +446 -0
  174. package/dist/services/member-fleet-install.d.ts +710 -0
  175. package/dist/services/member-fleet-install.js +1896 -0
  176. package/dist/services/member-secret-env.d.ts +42 -0
  177. package/dist/services/member-secret-env.js +68 -0
  178. package/dist/services/member-tool-allowlist.d.ts +49 -0
  179. package/dist/services/member-tool-allowlist.js +115 -0
  180. package/dist/services/model-pricing.d.ts +19 -0
  181. package/dist/services/model-pricing.js +54 -8
  182. package/dist/services/port-holder.d.ts +86 -0
  183. package/dist/services/port-holder.js +352 -0
  184. package/dist/services/preflight-check.js +2 -0
  185. package/dist/services/registry.d.ts +13 -2
  186. package/dist/services/registry.js +27 -1
  187. package/dist/services/relay-strategy.d.ts +2 -0
  188. package/dist/services/relay-strategy.js +8 -0
  189. package/dist/services/server-lifecycle.d.ts +26 -0
  190. package/dist/services/server-lifecycle.js +85 -0
  191. package/dist/services/service-manager/index.d.ts +7 -1
  192. package/dist/services/service-manager/index.js +17 -4
  193. package/dist/services/service-manager/linux.d.ts +1 -1
  194. package/dist/services/service-manager/linux.js +15 -7
  195. package/dist/services/service-manager/macos.d.ts +11 -1
  196. package/dist/services/service-manager/macos.js +45 -7
  197. package/dist/services/service-manager/service-path.d.ts +24 -0
  198. package/dist/services/service-manager/service-path.js +55 -0
  199. package/dist/services/service-manager/types.d.ts +54 -3
  200. package/dist/services/service-manager/types.js +29 -0
  201. package/dist/services/service-manager/windows.d.ts +187 -3
  202. package/dist/services/service-manager/windows.js +684 -50
  203. package/dist/services/service-notice.d.ts +21 -0
  204. package/dist/services/service-notice.js +81 -0
  205. package/dist/services/service-start-guard.d.ts +20 -0
  206. package/dist/services/service-start-guard.js +86 -0
  207. package/dist/services/session-cost.d.ts +24 -0
  208. package/dist/services/session-cost.js +105 -0
  209. package/dist/services/session-mcp-config.d.ts +83 -0
  210. package/dist/services/session-mcp-config.js +211 -0
  211. package/dist/services/session-registry.d.ts +13 -0
  212. package/dist/services/session-registry.js +13 -0
  213. package/dist/services/session-roots.d.ts +67 -0
  214. package/dist/services/session-roots.js +126 -0
  215. package/dist/services/sftp.d.ts +34 -0
  216. package/dist/services/sftp.js +304 -76
  217. package/dist/services/shell-probe.d.ts +0 -24
  218. package/dist/services/shell-probe.js +28 -3
  219. package/dist/services/singleton.d.ts +68 -2
  220. package/dist/services/singleton.js +168 -11
  221. package/dist/services/sprint-coordination.js +9 -3
  222. package/dist/services/ssh.d.ts +27 -0
  223. package/dist/services/ssh.js +229 -38
  224. package/dist/services/stall/find-log-file.js +12 -5
  225. package/dist/services/stall/index.d.ts +1 -1
  226. package/dist/services/stall/read-log-tail.d.ts +23 -0
  227. package/dist/services/stall/read-log-tail.js +33 -2
  228. package/dist/services/stall/stall-detector.d.ts +25 -1
  229. package/dist/services/stall/stall-detector.js +85 -6
  230. package/dist/services/stall/stall-poller.d.ts +16 -0
  231. package/dist/services/stall/stall-poller.js +50 -6
  232. package/dist/services/statusline.d.ts +21 -0
  233. package/dist/services/statusline.js +97 -1
  234. package/dist/services/stopped-marker.d.ts +16 -0
  235. package/dist/services/stopped-marker.js +55 -0
  236. package/dist/services/strategy.d.ts +33 -1
  237. package/dist/services/strategy.js +86 -17
  238. package/dist/services/supervisor-service-cleanup.d.ts +52 -0
  239. package/dist/services/supervisor-service-cleanup.js +333 -0
  240. package/dist/services/tool-registry.d.ts +8 -1
  241. package/dist/services/tool-registry.js +251 -62
  242. package/dist/services/tool-scope.d.ts +91 -0
  243. package/dist/services/tool-scope.js +124 -0
  244. package/dist/services/vcs/azure-devops.js +10 -0
  245. package/dist/services/vcs/bitbucket.d.ts +22 -1
  246. package/dist/services/vcs/bitbucket.js +163 -17
  247. package/dist/services/vcs/types.d.ts +25 -2
  248. package/dist/services/watch/project-resolver.js +3 -1
  249. package/dist/skills/auto-sprint-args/SKILL.md +2 -2
  250. package/dist/skills/fleet-sprint-cli/SKILL.md +39 -15
  251. package/dist/skills/pm/SKILL.md +3 -3
  252. package/dist/skills/pm/cost.md +5 -1
  253. package/dist/skills/pm/index.md +11 -9
  254. package/dist/skills/pm/kb-reconcile.md +29 -14
  255. package/dist/skills/pm/kb-review.md +1 -0
  256. package/dist/skills/pm/sprint.md +7 -6
  257. package/dist/tools/check-status.d.ts +104 -5
  258. package/dist/tools/check-status.js +326 -57
  259. package/dist/tools/child-id-allocator.d.ts +2 -2
  260. package/dist/tools/child-id-allocator.js +1 -1
  261. package/dist/tools/code-index-heal.d.ts +8 -0
  262. package/dist/tools/code-index-heal.js +21 -0
  263. package/dist/tools/code-index-state.d.ts +45 -0
  264. package/dist/tools/code-index-state.js +115 -0
  265. package/dist/tools/code-intelligence-codebase-memory.js +6 -33
  266. package/dist/tools/code-intelligence-freshness.js +1 -1
  267. package/dist/tools/code-intelligence-gitnexus.d.ts +49 -0
  268. package/dist/tools/code-intelligence-gitnexus.js +488 -55
  269. package/dist/tools/code-intelligence-kb-enrich.js +7 -6
  270. package/dist/tools/code-intelligence-readiness.d.ts +156 -0
  271. package/dist/tools/code-intelligence-readiness.js +291 -0
  272. package/dist/tools/code-intelligence-reindex.d.ts +219 -0
  273. package/dist/tools/code-intelligence-reindex.js +602 -50
  274. package/dist/tools/code-intelligence-telemetry.d.ts +6 -1
  275. package/dist/tools/code-intelligence-telemetry.js +12 -3
  276. package/dist/tools/code-intelligence.d.ts +81 -31
  277. package/dist/tools/code-intelligence.js +156 -52
  278. package/dist/tools/compose-permissions.d.ts +57 -2
  279. package/dist/tools/compose-permissions.js +497 -44
  280. package/dist/tools/execute-command.d.ts +11 -0
  281. package/dist/tools/execute-command.js +92 -18
  282. package/dist/tools/execute-prompt.d.ts +59 -15
  283. package/dist/tools/execute-prompt.js +550 -135
  284. package/dist/tools/fleet-snapshot.d.ts +21 -0
  285. package/dist/tools/fleet-snapshot.js +78 -0
  286. package/dist/tools/kb-bible-commit.d.ts +79 -0
  287. package/dist/tools/kb-bible-commit.js +348 -0
  288. package/dist/tools/kb-capture.d.ts +15 -11
  289. package/dist/tools/kb-capture.js +42 -11
  290. package/dist/tools/kb-context.d.ts +27 -7
  291. package/dist/tools/kb-context.js +85 -14
  292. package/dist/tools/kb-demote.d.ts +27 -0
  293. package/dist/tools/kb-demote.js +37 -0
  294. package/dist/tools/kb-export.d.ts +128 -7
  295. package/dist/tools/kb-export.js +273 -67
  296. package/dist/tools/kb-feedback.d.ts +15 -9
  297. package/dist/tools/kb-feedback.js +27 -11
  298. package/dist/tools/kb-freshness-sweep.d.ts +11 -7
  299. package/dist/tools/kb-freshness-sweep.js +7 -7
  300. package/dist/tools/kb-harvest.d.ts +11 -7
  301. package/dist/tools/kb-harvest.js +35 -16
  302. package/dist/tools/kb-import.d.ts +42 -10
  303. package/dist/tools/kb-import.js +185 -160
  304. package/dist/tools/kb-invalidate.d.ts +26 -11
  305. package/dist/tools/kb-invalidate.js +118 -12
  306. package/dist/tools/kb-list.d.ts +14 -10
  307. package/dist/tools/kb-list.js +61 -13
  308. package/dist/tools/kb-promote.d.ts +11 -7
  309. package/dist/tools/kb-promote.js +16 -8
  310. package/dist/tools/kb-query.d.ts +24 -11
  311. package/dist/tools/kb-query.js +230 -23
  312. package/dist/tools/kb-reconcile-prefilter.d.ts +11 -7
  313. package/dist/tools/kb-reconcile-prefilter.js +10 -8
  314. package/dist/tools/kb-resolve-contradiction.d.ts +11 -7
  315. package/dist/tools/kb-resolve-contradiction.js +7 -7
  316. package/dist/tools/kb-session-prime.d.ts +14 -7
  317. package/dist/tools/kb-session-prime.js +127 -47
  318. package/dist/tools/kb-setup.d.ts +31 -4
  319. package/dist/tools/kb-setup.js +172 -20
  320. package/dist/tools/kb-stats.d.ts +11 -10
  321. package/dist/tools/kb-stats.js +22 -41
  322. package/dist/tools/list-members.js +6 -3
  323. package/dist/tools/member-detail.d.ts +3 -0
  324. package/dist/tools/member-detail.js +95 -20
  325. package/dist/tools/member-reservation.d.ts +2 -2
  326. package/dist/tools/provision-auth.d.ts +39 -1
  327. package/dist/tools/provision-auth.js +269 -47
  328. package/dist/tools/provision-vcs-auth.d.ts +30 -5
  329. package/dist/tools/provision-vcs-auth.js +53 -7
  330. package/dist/tools/receive-files.js +8 -3
  331. package/dist/tools/register-member.d.ts +34 -8
  332. package/dist/tools/register-member.js +76 -58
  333. package/dist/tools/remove-member.js +110 -32
  334. package/dist/tools/send-email.d.ts +2 -2
  335. package/dist/tools/send-files.js +9 -6
  336. package/dist/tools/send-message.d.ts +3 -0
  337. package/dist/tools/send-message.js +15 -2
  338. package/dist/tools/session-stats.d.ts +17 -0
  339. package/dist/tools/session-stats.js +27 -0
  340. package/dist/tools/shutdown-server.js +5 -0
  341. package/dist/tools/stop-prompt.js +3 -1
  342. package/dist/tools/update-agent-cli.d.ts +19 -0
  343. package/dist/tools/update-agent-cli.js +59 -2
  344. package/dist/tools/update-member.d.ts +13 -10
  345. package/dist/tools/update-member.js +138 -7
  346. package/dist/tools/vcs-credential-exec.d.ts +45 -3
  347. package/dist/tools/vcs-credential-exec.js +98 -13
  348. package/dist/types.d.ts +98 -1
  349. package/dist/utils/agent-helpers.js +2 -0
  350. package/dist/utils/auth-env.d.ts +15 -4
  351. package/dist/utils/auth-env.js +52 -23
  352. package/dist/utils/find-on-path.d.ts +37 -0
  353. package/dist/utils/find-on-path.js +85 -0
  354. package/dist/utils/log-helpers.d.ts +37 -0
  355. package/dist/utils/log-helpers.js +106 -20
  356. package/dist/utils/owner-only-fs.d.ts +56 -0
  357. package/dist/utils/owner-only-fs.js +98 -0
  358. package/dist/utils/process-utils.d.ts +28 -0
  359. package/dist/utils/process-utils.js +72 -0
  360. package/dist/utils/prompt-errors.js +4 -1
  361. package/dist/utils/redact-known-secrets.d.ts +17 -0
  362. package/dist/utils/redact-known-secrets.js +70 -0
  363. package/dist/utils/session-caller.d.ts +4 -2
  364. package/dist/utils/session-caller.js +3 -2
  365. package/dist/utils/shell-escape.d.ts +42 -3
  366. package/dist/utils/shell-escape.js +70 -4
  367. package/dist/utils/skill-matrix.js +1 -1
  368. package/dist/utils/ssh-error-messages.js +3 -0
  369. package/dist/utils/vcs-provider-detect.js +2 -2
  370. package/dist/utils/workspace-trust.d.ts +24 -1
  371. package/dist/utils/workspace-trust.js +21 -17
  372. package/dist/workflows/auto-sprint.js +468 -52
  373. package/package.json +15 -9
  374. package/packages/apra-fleet-client/package.json +2 -2
  375. package/packages/apra-fleet-client/src/client/api.mjs +722 -38
  376. package/packages/apra-fleet-client/src/client/auto-start.mjs +434 -0
  377. package/packages/apra-fleet-client/src/client/client.mjs +9 -0
  378. package/packages/apra-fleet-client/src/client/factory.mjs +23 -4
  379. package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +170 -0
  380. package/packages/apra-fleet-client/src/client/server-resolution.mjs +267 -30
  381. package/packages/apra-fleet-client/src/client/transport.mjs +43 -3
  382. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +80 -27
  383. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +42 -22
  384. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +59 -24
  385. package/packages/apra-fleet-se/apra-pm/agents/doer.md +111 -41
  386. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +60 -48
  387. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +45 -23
  388. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +34 -7
  389. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +54 -24
  390. package/packages/apra-fleet-se/apra-pm/agents/planner.md +71 -43
  391. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +106 -78
  392. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +170 -57
  393. package/packages/apra-fleet-se/apra-pm/agents/schemas/backlog-groomer-output.json +1 -1
  394. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +5 -0
  395. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +110 -2
  396. package/packages/apra-fleet-se/apra-pm/agents/schemas/harvester-input.json +1 -5
  397. package/packages/apra-fleet-se/apra-pm/agents/schemas/planner-output.json +1 -1
  398. package/packages/apra-fleet-se/apra-pm/agents/schemas/regression-test-runner-output.json +41 -7
  399. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +166 -5
  400. package/packages/apra-fleet-se/apra-pm/skills/pm/SKILL.md +3 -3
  401. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +5 -1
  402. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +11 -9
  403. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-reconcile.md +29 -14
  404. package/packages/apra-fleet-se/apra-pm/skills/pm/kb-review.md +1 -0
  405. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +7 -6
  406. package/packages/apra-fleet-se/bin/cli.mjs +282 -79
  407. package/packages/apra-fleet-se/bin/serve.mjs +186 -15
  408. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +234 -46
  409. package/packages/apra-fleet-se/fleet-sprint/backlog-role.mjs +93 -0
  410. package/packages/apra-fleet-se/fleet-sprint/bd-sync-command.mjs +69 -0
  411. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +229 -53
  412. package/packages/apra-fleet-se/fleet-sprint/beads-identity-check.mjs +576 -33
  413. package/packages/apra-fleet-se/fleet-sprint/beads-identity.mjs +9 -0
  414. package/packages/apra-fleet-se/fleet-sprint/beads-lock-probe.mjs +176 -0
  415. package/packages/apra-fleet-se/fleet-sprint/beads-memory-hygiene.mjs +201 -0
  416. package/packages/apra-fleet-se/fleet-sprint/beads-reachability.mjs +126 -0
  417. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +271 -7
  418. package/packages/apra-fleet-se/fleet-sprint/beads-transitions.mjs +154 -8
  419. package/packages/apra-fleet-se/fleet-sprint/ci-gate.mjs +353 -0
  420. package/packages/apra-fleet-se/fleet-sprint/conflict-ladder.mjs +12 -0
  421. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +142 -3
  422. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +48 -8
  423. package/packages/apra-fleet-se/fleet-sprint/decision-notify.mjs +338 -0
  424. package/packages/apra-fleet-se/fleet-sprint/decision-wait.mjs +731 -0
  425. package/packages/apra-fleet-se/fleet-sprint/decisions.mjs +372 -0
  426. package/packages/apra-fleet-se/fleet-sprint/dispatch-accounting.mjs +270 -0
  427. package/packages/apra-fleet-se/fleet-sprint/dispatch-failure.mjs +22 -2
  428. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +244 -22
  429. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +56 -15
  430. package/packages/apra-fleet-se/fleet-sprint/docs/dolt-sync-redesign.md +6 -1
  431. package/packages/apra-fleet-se/fleet-sprint/docs/fleet-sprint-diagram.md +3 -3
  432. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +9 -3
  433. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +651 -37
  434. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +282 -15
  435. package/packages/apra-fleet-se/fleet-sprint/explicit-id-create-guard.mjs +4 -4
  436. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +207 -10
  437. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +169 -10
  438. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +88 -5
  439. package/packages/apra-fleet-se/fleet-sprint/kb-hints.mjs +181 -0
  440. package/packages/apra-fleet-se/fleet-sprint/kb-injection.mjs +64 -0
  441. package/packages/apra-fleet-se/fleet-sprint/kb-maintainer.mjs +298 -0
  442. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +1896 -305
  443. package/packages/apra-fleet-se/fleet-sprint/lower-quality.mjs +39 -0
  444. package/packages/apra-fleet-se/fleet-sprint/member-align.mjs +391 -0
  445. package/packages/apra-fleet-se/fleet-sprint/member-call.mjs +374 -0
  446. package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +644 -0
  447. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +454 -1
  448. package/packages/apra-fleet-se/fleet-sprint/member-sync.mjs +250 -29
  449. package/packages/apra-fleet-se/fleet-sprint/orphan-reclaim.mjs +153 -0
  450. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +129 -0
  451. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +302 -52
  452. package/packages/apra-fleet-se/fleet-sprint/phases/ensure-sprint-branch.mjs +1 -0
  453. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +142 -21
  454. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +118 -36
  455. package/packages/apra-fleet-se/fleet-sprint/phases/integ-test.mjs +6 -6
  456. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +27 -18
  457. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +99 -52
  458. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +58 -10
  459. package/packages/apra-fleet-se/fleet-sprint/phases/regression-test.mjs +16 -11
  460. package/packages/apra-fleet-se/fleet-sprint/phases/replan.mjs +36 -3
  461. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +90 -15
  462. package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +272 -0
  463. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +113 -28
  464. package/packages/apra-fleet-se/fleet-sprint/role-policies.mjs +19 -1
  465. package/packages/apra-fleet-se/fleet-sprint/runner.js +1631 -213
  466. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +26 -0
  467. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +183 -0
  468. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +138 -0
  469. package/packages/apra-fleet-se/fleet-sprint/set-aside.mjs +288 -0
  470. package/packages/apra-fleet-se/fleet-sprint/shell-command-guard.mjs +44 -1
  471. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-sprint-cli/SKILL.md +39 -15
  472. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +87 -32
  473. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +158 -2
  474. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +132 -11
  475. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +31 -0
  476. package/packages/apra-fleet-se/fleet-sprint/usage-limit-controller.mjs +7 -0
  477. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +774 -35
  478. package/packages/apra-fleet-se/fleet-sprint/vcs-module.mjs +134 -7
  479. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/azure-devops.mjs +99 -0
  480. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +811 -17
  481. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/github.mjs +223 -0
  482. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +138 -1
  483. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/shell-helpers.mjs +8 -4
  484. package/packages/apra-fleet-se/fleet-sprint/verify-block.mjs +152 -0
  485. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +460 -23
  486. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +59 -3
  487. package/packages/apra-fleet-se/package.json +2 -2
  488. package/packages/apra-fleet-se/src/supervisor/api.mjs +1059 -0
  489. package/packages/apra-fleet-se/src/supervisor/backlog-member.mjs +332 -0
  490. package/packages/apra-fleet-se/src/supervisor/backlog.mjs +982 -0
  491. package/packages/apra-fleet-se/src/supervisor/beads-identity.mjs +246 -0
  492. package/packages/apra-fleet-se/src/supervisor/beads-view.mjs +438 -0
  493. package/packages/apra-fleet-se/src/supervisor/child-port.mjs +36 -0
  494. package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +1662 -0
  495. package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +370 -0
  496. package/packages/apra-fleet-se/src/supervisor/dolt-orphan-sweep.mjs +338 -0
  497. package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +292 -0
  498. package/packages/apra-fleet-se/src/supervisor/history-view.mjs +276 -0
  499. package/packages/apra-fleet-se/src/supervisor/history.mjs +335 -0
  500. package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +611 -0
  501. package/packages/apra-fleet-se/src/supervisor/launch-form.mjs +444 -0
  502. package/packages/apra-fleet-se/src/supervisor/ledger.mjs +629 -0
  503. package/packages/apra-fleet-se/src/supervisor/lib/exec-bd.mjs +303 -0
  504. package/packages/apra-fleet-se/src/supervisor/log-timestamp.mjs +51 -0
  505. package/packages/apra-fleet-se/src/supervisor/log-view.mjs +159 -0
  506. package/packages/apra-fleet-se/src/supervisor/proxy.mjs +499 -0
  507. package/packages/apra-fleet-se/src/supervisor/readopt.mjs +136 -0
  508. package/packages/apra-fleet-se/src/supervisor/reconcile.mjs +263 -0
  509. package/packages/apra-fleet-se/src/supervisor/rename-with-retry.mjs +87 -0
  510. package/packages/apra-fleet-se/src/supervisor/scope-overlap.mjs +327 -0
  511. package/packages/apra-fleet-se/src/supervisor/self-log.mjs +133 -0
  512. package/packages/apra-fleet-se/src/supervisor/server.mjs +542 -0
  513. package/packages/apra-fleet-se/src/supervisor/spawner.mjs +544 -0
  514. package/packages/apra-fleet-se/src/supervisor/sprint-identity.mjs +96 -0
  515. package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +993 -0
  516. package/packages/apra-fleet-workflow/package.json +3 -2
  517. package/packages/apra-fleet-workflow/src/viewer/index.mjs +150 -14
  518. package/packages/apra-fleet-workflow/src/viewer/request-guard.mjs +222 -0
  519. package/packages/apra-fleet-workflow/src/viewer/run-summary.mjs +127 -0
  520. package/packages/apra-fleet-workflow/src/workflow/index.mjs +105 -7
  521. package/packages/apra-fleet-workflow/src/workflow/pricing.mjs +75 -25
  522. package/plugins/claude-code/fleet-status/.claude-plugin/plugin.json +7 -0
  523. package/plugins/claude-code/fleet-status/hooks/hooks.json +1 -0
  524. package/plugins/claude-code/fleet-status/hooks/register.tsx +906 -0
  525. package/plugins/claude-code/fleet-status/types/index.d.ts +88 -0
  526. package/skills/fleet/auth-bitbucket.md +47 -20
  527. package/skills/fleet/onboarding.md +1 -1
  528. package/skills/fleet/permissions.md +9 -0
  529. package/skills/fleet/profiles/tag-kb-reconciler.json +2 -6
  530. package/skills/fleet/skill-matrix.md +3 -3
  531. package/version.json +1 -1
  532. package/dist/cli/agent-transform.d.ts.map +0 -1
  533. package/dist/cli/agent-transform.js.map +0 -1
  534. package/dist/cli/auth.d.ts.map +0 -1
  535. package/dist/cli/auth.js.map +0 -1
  536. package/dist/cli/config.d.ts.map +0 -1
  537. package/dist/cli/config.js.map +0 -1
  538. package/dist/cli/dolt-install.d.ts.map +0 -1
  539. package/dist/cli/dolt-install.js.map +0 -1
  540. package/dist/cli/install-guard.d.ts.map +0 -1
  541. package/dist/cli/install-guard.js.map +0 -1
  542. package/dist/cli/install.d.ts.map +0 -1
  543. package/dist/cli/install.js.map +0 -1
  544. package/dist/cli/join.d.ts.map +0 -1
  545. package/dist/cli/join.js.map +0 -1
  546. package/dist/cli/kb-commit.d.ts.map +0 -1
  547. package/dist/cli/kb-commit.js.map +0 -1
  548. package/dist/cli/kb-directives.d.ts.map +0 -1
  549. package/dist/cli/kb-directives.js.map +0 -1
  550. package/dist/cli/kb-import.d.ts.map +0 -1
  551. package/dist/cli/kb-import.js.map +0 -1
  552. package/dist/cli/register-member.d.ts.map +0 -1
  553. package/dist/cli/register-member.js.map +0 -1
  554. package/dist/cli/restart.d.ts.map +0 -1
  555. package/dist/cli/restart.js.map +0 -1
  556. package/dist/cli/secret.d.ts.map +0 -1
  557. package/dist/cli/secret.js.map +0 -1
  558. package/dist/cli/spoke.d.ts.map +0 -1
  559. package/dist/cli/spoke.js.map +0 -1
  560. package/dist/cli/start.d.ts.map +0 -1
  561. package/dist/cli/start.js.map +0 -1
  562. package/dist/cli/status.d.ts.map +0 -1
  563. package/dist/cli/status.js.map +0 -1
  564. package/dist/cli/stop.d.ts.map +0 -1
  565. package/dist/cli/stop.js.map +0 -1
  566. package/dist/cli/uninstall.d.ts.map +0 -1
  567. package/dist/cli/uninstall.js.map +0 -1
  568. package/dist/cli/update.d.ts.map +0 -1
  569. package/dist/cli/update.js.map +0 -1
  570. package/dist/cli/watch.d.ts.map +0 -1
  571. package/dist/cli/watch.js.map +0 -1
  572. package/dist/cli/workflow-assets.d.ts.map +0 -1
  573. package/dist/cli/workflow-assets.js.map +0 -1
  574. package/dist/cli/workflow.d.ts.map +0 -1
  575. package/dist/cli/workflow.js.map +0 -1
  576. package/dist/commands/kb-server.d.ts.map +0 -1
  577. package/dist/commands/kb-server.js.map +0 -1
  578. package/dist/delivery-mode.d.ts.map +0 -1
  579. package/dist/delivery-mode.js.map +0 -1
  580. package/dist/hub-service/activity.d.ts.map +0 -1
  581. package/dist/hub-service/activity.js.map +0 -1
  582. package/dist/hub-service/audit-log.d.ts.map +0 -1
  583. package/dist/hub-service/audit-log.js.map +0 -1
  584. package/dist/hub-service/db/pool.d.ts.map +0 -1
  585. package/dist/hub-service/db/pool.js.map +0 -1
  586. package/dist/hub-service/enrollment.d.ts.map +0 -1
  587. package/dist/hub-service/enrollment.js.map +0 -1
  588. package/dist/hub-service/envelope-routes.d.ts.map +0 -1
  589. package/dist/hub-service/envelope-routes.js.map +0 -1
  590. package/dist/hub-service/handlers/installers.d.ts.map +0 -1
  591. package/dist/hub-service/handlers/installers.js.map +0 -1
  592. package/dist/hub-service/http-server.d.ts.map +0 -1
  593. package/dist/hub-service/http-server.js.map +0 -1
  594. package/dist/hub-service/hub-jwt.d.ts.map +0 -1
  595. package/dist/hub-service/hub-jwt.js.map +0 -1
  596. package/dist/hub-service/jwt-revocation.d.ts.map +0 -1
  597. package/dist/hub-service/jwt-revocation.js.map +0 -1
  598. package/dist/hub-service/machines.d.ts.map +0 -1
  599. package/dist/hub-service/machines.js.map +0 -1
  600. package/dist/hub-service/main.d.ts.map +0 -1
  601. package/dist/hub-service/main.js.map +0 -1
  602. package/dist/hub-service/member-tokens.d.ts.map +0 -1
  603. package/dist/hub-service/member-tokens.js.map +0 -1
  604. package/dist/hub-service/member-view.d.ts.map +0 -1
  605. package/dist/hub-service/member-view.js.map +0 -1
  606. package/dist/hub-service/members.d.ts.map +0 -1
  607. package/dist/hub-service/members.js.map +0 -1
  608. package/dist/hub-service/presence.d.ts.map +0 -1
  609. package/dist/hub-service/presence.js.map +0 -1
  610. package/dist/hub-service/project-view.d.ts.map +0 -1
  611. package/dist/hub-service/project-view.js.map +0 -1
  612. package/dist/hub-service/projects.d.ts.map +0 -1
  613. package/dist/hub-service/projects.js.map +0 -1
  614. package/dist/hub-service/relay-queue.d.ts.map +0 -1
  615. package/dist/hub-service/relay-queue.js.map +0 -1
  616. package/dist/hub-service/session-jwt.d.ts.map +0 -1
  617. package/dist/hub-service/session-jwt.js.map +0 -1
  618. package/dist/hub-service/usage.d.ts.map +0 -1
  619. package/dist/hub-service/usage.js.map +0 -1
  620. package/dist/hub-service/users.d.ts.map +0 -1
  621. package/dist/hub-service/users.js.map +0 -1
  622. package/dist/hub-service/workspaces.d.ts.map +0 -1
  623. package/dist/hub-service/workspaces.js.map +0 -1
  624. package/dist/index.d.ts.map +0 -1
  625. package/dist/index.js.map +0 -1
  626. package/dist/onboarding/text.d.ts.map +0 -1
  627. package/dist/onboarding/text.js.map +0 -1
  628. package/dist/os/git-bash-candidates.d.ts.map +0 -1
  629. package/dist/os/git-bash-candidates.js.map +0 -1
  630. package/dist/os/index.d.ts.map +0 -1
  631. package/dist/os/index.js.map +0 -1
  632. package/dist/os/linux.d.ts.map +0 -1
  633. package/dist/os/linux.js.map +0 -1
  634. package/dist/os/macos.d.ts.map +0 -1
  635. package/dist/os/macos.js.map +0 -1
  636. package/dist/os/os-commands.d.ts.map +0 -1
  637. package/dist/os/os-commands.js.map +0 -1
  638. package/dist/os/windows-gitbash.d.ts.map +0 -1
  639. package/dist/os/windows-gitbash.js.map +0 -1
  640. package/dist/os/windows-wrapper.d.ts.map +0 -1
  641. package/dist/os/windows-wrapper.js.map +0 -1
  642. package/dist/os/windows.d.ts.map +0 -1
  643. package/dist/os/windows.js.map +0 -1
  644. package/dist/paths.d.ts.map +0 -1
  645. package/dist/paths.js.map +0 -1
  646. package/dist/providers/agy.d.ts.map +0 -1
  647. package/dist/providers/agy.js.map +0 -1
  648. package/dist/providers/claude.d.ts.map +0 -1
  649. package/dist/providers/claude.js.map +0 -1
  650. package/dist/providers/codex.d.ts.map +0 -1
  651. package/dist/providers/codex.js.map +0 -1
  652. package/dist/providers/copilot.d.ts.map +0 -1
  653. package/dist/providers/copilot.js.map +0 -1
  654. package/dist/providers/email/headers.d.ts.map +0 -1
  655. package/dist/providers/email/headers.js.map +0 -1
  656. package/dist/providers/email/index.d.ts.map +0 -1
  657. package/dist/providers/email/index.js.map +0 -1
  658. package/dist/providers/email/provider.d.ts.map +0 -1
  659. package/dist/providers/email/provider.js.map +0 -1
  660. package/dist/providers/email/sendgrid.d.ts.map +0 -1
  661. package/dist/providers/email/sendgrid.js.map +0 -1
  662. package/dist/providers/email/smtp.d.ts.map +0 -1
  663. package/dist/providers/email/smtp.js.map +0 -1
  664. package/dist/providers/index.d.ts.map +0 -1
  665. package/dist/providers/index.js.map +0 -1
  666. package/dist/providers/none.d.ts.map +0 -1
  667. package/dist/providers/none.js.map +0 -1
  668. package/dist/providers/opencode.d.ts.map +0 -1
  669. package/dist/providers/opencode.js.map +0 -1
  670. package/dist/providers/provider.d.ts.map +0 -1
  671. package/dist/providers/provider.js.map +0 -1
  672. package/dist/services/agent-provisioner.d.ts.map +0 -1
  673. package/dist/services/agent-provisioner.js.map +0 -1
  674. package/dist/services/agy-project.d.ts.map +0 -1
  675. package/dist/services/agy-project.js.map +0 -1
  676. package/dist/services/auth-socket.d.ts.map +0 -1
  677. package/dist/services/auth-socket.js.map +0 -1
  678. package/dist/services/auth-web.d.ts.map +0 -1
  679. package/dist/services/auth-web.js.map +0 -1
  680. package/dist/services/budget-awareness.d.ts.map +0 -1
  681. package/dist/services/budget-awareness.js.map +0 -1
  682. package/dist/services/cloud/activity.d.ts.map +0 -1
  683. package/dist/services/cloud/activity.js.map +0 -1
  684. package/dist/services/cloud/aws.d.ts.map +0 -1
  685. package/dist/services/cloud/aws.js.map +0 -1
  686. package/dist/services/cloud/cost.d.ts.map +0 -1
  687. package/dist/services/cloud/cost.js.map +0 -1
  688. package/dist/services/cloud/idle-manager.d.ts.map +0 -1
  689. package/dist/services/cloud/idle-manager.js.map +0 -1
  690. package/dist/services/cloud/lifecycle.d.ts.map +0 -1
  691. package/dist/services/cloud/lifecycle.js.map +0 -1
  692. package/dist/services/cloud/task-wrapper.d.ts.map +0 -1
  693. package/dist/services/cloud/task-wrapper.js.map +0 -1
  694. package/dist/services/cloud/types.d.ts.map +0 -1
  695. package/dist/services/cloud/types.js.map +0 -1
  696. package/dist/services/cloud-sync.d.ts.map +0 -1
  697. package/dist/services/cloud-sync.js.map +0 -1
  698. package/dist/services/context-admission.d.ts.map +0 -1
  699. package/dist/services/context-admission.js.map +0 -1
  700. package/dist/services/credential-cleanup.d.ts.map +0 -1
  701. package/dist/services/credential-cleanup.js.map +0 -1
  702. package/dist/services/credential-store.d.ts.map +0 -1
  703. package/dist/services/credential-store.js.map +0 -1
  704. package/dist/services/event-bus.d.ts.map +0 -1
  705. package/dist/services/event-bus.js.map +0 -1
  706. package/dist/services/exit-drain.d.ts.map +0 -1
  707. package/dist/services/exit-drain.js.map +0 -1
  708. package/dist/services/file-chunker.d.ts.map +0 -1
  709. package/dist/services/file-chunker.js.map +0 -1
  710. package/dist/services/file-transfer-relay.d.ts.map +0 -1
  711. package/dist/services/file-transfer-relay.js.map +0 -1
  712. package/dist/services/file-transfer.d.ts.map +0 -1
  713. package/dist/services/file-transfer.js.map +0 -1
  714. package/dist/services/git-config.d.ts.map +0 -1
  715. package/dist/services/git-config.js.map +0 -1
  716. package/dist/services/github-app.d.ts.map +0 -1
  717. package/dist/services/github-app.js.map +0 -1
  718. package/dist/services/http-transport.d.ts.map +0 -1
  719. package/dist/services/http-transport.js.map +0 -1
  720. package/dist/services/hub-client.d.ts.map +0 -1
  721. package/dist/services/hub-client.js.map +0 -1
  722. package/dist/services/icons.d.ts.map +0 -1
  723. package/dist/services/icons.js.map +0 -1
  724. package/dist/services/jwt.d.ts.map +0 -1
  725. package/dist/services/jwt.js.map +0 -1
  726. package/dist/services/knowledge/audn.d.ts.map +0 -1
  727. package/dist/services/knowledge/audn.js.map +0 -1
  728. package/dist/services/knowledge/file-hash.d.ts.map +0 -1
  729. package/dist/services/knowledge/file-hash.js.map +0 -1
  730. package/dist/services/knowledge/http-provider.d.ts.map +0 -1
  731. package/dist/services/knowledge/http-provider.js.map +0 -1
  732. package/dist/services/knowledge/kb-config.d.ts.map +0 -1
  733. package/dist/services/knowledge/kb-config.js.map +0 -1
  734. package/dist/services/knowledge/kb-providers.d.ts.map +0 -1
  735. package/dist/services/knowledge/kb-providers.js.map +0 -1
  736. package/dist/services/knowledge/kb-scope-input.d.ts +0 -5
  737. package/dist/services/knowledge/kb-scope-input.d.ts.map +0 -1
  738. package/dist/services/knowledge/kb-scope-input.js +0 -11
  739. package/dist/services/knowledge/kb-scope-input.js.map +0 -1
  740. package/dist/services/knowledge/kb-service.d.ts.map +0 -1
  741. package/dist/services/knowledge/kb-service.js.map +0 -1
  742. package/dist/services/knowledge/path-validation.d.ts.map +0 -1
  743. package/dist/services/knowledge/path-validation.js.map +0 -1
  744. package/dist/services/knowledge/pre-init.d.ts.map +0 -1
  745. package/dist/services/knowledge/pre-init.js.map +0 -1
  746. package/dist/services/knowledge/project-slug.d.ts.map +0 -1
  747. package/dist/services/knowledge/project-slug.js.map +0 -1
  748. package/dist/services/knowledge/require-sqlite-project.d.ts.map +0 -1
  749. package/dist/services/knowledge/require-sqlite-project.js.map +0 -1
  750. package/dist/services/knowledge/sqlite-provider.d.ts.map +0 -1
  751. package/dist/services/knowledge/sqlite-provider.js.map +0 -1
  752. package/dist/services/knowledge/types.d.ts.map +0 -1
  753. package/dist/services/knowledge/types.js.map +0 -1
  754. package/dist/services/known-hosts.d.ts.map +0 -1
  755. package/dist/services/known-hosts.js.map +0 -1
  756. package/dist/services/known-sessions.d.ts.map +0 -1
  757. package/dist/services/known-sessions.js.map +0 -1
  758. package/dist/services/member-home.d.ts.map +0 -1
  759. package/dist/services/member-home.js.map +0 -1
  760. package/dist/services/member-remote-url.d.ts.map +0 -1
  761. package/dist/services/member-remote-url.js.map +0 -1
  762. package/dist/services/model-pricing.d.ts.map +0 -1
  763. package/dist/services/model-pricing.js.map +0 -1
  764. package/dist/services/onboarding.d.ts.map +0 -1
  765. package/dist/services/onboarding.js.map +0 -1
  766. package/dist/services/orphan-recovery.d.ts.map +0 -1
  767. package/dist/services/orphan-recovery.js.map +0 -1
  768. package/dist/services/pending-responses.d.ts.map +0 -1
  769. package/dist/services/pending-responses.js.map +0 -1
  770. package/dist/services/preflight-check.d.ts.map +0 -1
  771. package/dist/services/preflight-check.js.map +0 -1
  772. package/dist/services/registry.d.ts.map +0 -1
  773. package/dist/services/registry.js.map +0 -1
  774. package/dist/services/relay-context.d.ts.map +0 -1
  775. package/dist/services/relay-context.js.map +0 -1
  776. package/dist/services/relay-executor.d.ts.map +0 -1
  777. package/dist/services/relay-executor.js.map +0 -1
  778. package/dist/services/relay-request.d.ts.map +0 -1
  779. package/dist/services/relay-request.js.map +0 -1
  780. package/dist/services/relay-strategy.d.ts.map +0 -1
  781. package/dist/services/relay-strategy.js.map +0 -1
  782. package/dist/services/secret-token.d.ts.map +0 -1
  783. package/dist/services/secret-token.js.map +0 -1
  784. package/dist/services/service-manager/index.d.ts.map +0 -1
  785. package/dist/services/service-manager/index.js.map +0 -1
  786. package/dist/services/service-manager/linux.d.ts.map +0 -1
  787. package/dist/services/service-manager/linux.js.map +0 -1
  788. package/dist/services/service-manager/macos.d.ts.map +0 -1
  789. package/dist/services/service-manager/macos.js.map +0 -1
  790. package/dist/services/service-manager/types.d.ts.map +0 -1
  791. package/dist/services/service-manager/types.js.map +0 -1
  792. package/dist/services/service-manager/windows.d.ts.map +0 -1
  793. package/dist/services/service-manager/windows.js.map +0 -1
  794. package/dist/services/session-registry.d.ts.map +0 -1
  795. package/dist/services/session-registry.js.map +0 -1
  796. package/dist/services/sftp.d.ts.map +0 -1
  797. package/dist/services/sftp.js.map +0 -1
  798. package/dist/services/shell-probe.d.ts.map +0 -1
  799. package/dist/services/shell-probe.js.map +0 -1
  800. package/dist/services/singleton.d.ts.map +0 -1
  801. package/dist/services/singleton.js.map +0 -1
  802. package/dist/services/sprint-coordination.d.ts.map +0 -1
  803. package/dist/services/sprint-coordination.js.map +0 -1
  804. package/dist/services/ssh.d.ts.map +0 -1
  805. package/dist/services/ssh.js.map +0 -1
  806. package/dist/services/stall/find-log-file.d.ts.map +0 -1
  807. package/dist/services/stall/find-log-file.js.map +0 -1
  808. package/dist/services/stall/index.d.ts.map +0 -1
  809. package/dist/services/stall/index.js.map +0 -1
  810. package/dist/services/stall/log-path-resolver.d.ts.map +0 -1
  811. package/dist/services/stall/log-path-resolver.js.map +0 -1
  812. package/dist/services/stall/read-log-tail.d.ts.map +0 -1
  813. package/dist/services/stall/read-log-tail.js.map +0 -1
  814. package/dist/services/stall/stall-detector.d.ts.map +0 -1
  815. package/dist/services/stall/stall-detector.js.map +0 -1
  816. package/dist/services/stall/stall-poller.d.ts.map +0 -1
  817. package/dist/services/stall/stall-poller.js.map +0 -1
  818. package/dist/services/stall/time-utils.d.ts.map +0 -1
  819. package/dist/services/stall/time-utils.js.map +0 -1
  820. package/dist/services/statusline.d.ts.map +0 -1
  821. package/dist/services/statusline.js.map +0 -1
  822. package/dist/services/strategy.d.ts.map +0 -1
  823. package/dist/services/strategy.js.map +0 -1
  824. package/dist/services/substitution-engine.d.ts.map +0 -1
  825. package/dist/services/substitution-engine.js.map +0 -1
  826. package/dist/services/task-cleanup.d.ts.map +0 -1
  827. package/dist/services/task-cleanup.js.map +0 -1
  828. package/dist/services/token-issuer.d.ts.map +0 -1
  829. package/dist/services/token-issuer.js.map +0 -1
  830. package/dist/services/tool-registry.d.ts.map +0 -1
  831. package/dist/services/tool-registry.js.map +0 -1
  832. package/dist/services/update-check.d.ts.map +0 -1
  833. package/dist/services/update-check.js.map +0 -1
  834. package/dist/services/user-config.d.ts.map +0 -1
  835. package/dist/services/user-config.js.map +0 -1
  836. package/dist/services/vcs/azure-devops.d.ts.map +0 -1
  837. package/dist/services/vcs/azure-devops.js.map +0 -1
  838. package/dist/services/vcs/bitbucket.d.ts.map +0 -1
  839. package/dist/services/vcs/bitbucket.js.map +0 -1
  840. package/dist/services/vcs/constants.d.ts.map +0 -1
  841. package/dist/services/vcs/constants.js.map +0 -1
  842. package/dist/services/vcs/github.d.ts.map +0 -1
  843. package/dist/services/vcs/github.js.map +0 -1
  844. package/dist/services/vcs/types.d.ts.map +0 -1
  845. package/dist/services/vcs/types.js.map +0 -1
  846. package/dist/services/version-check.d.ts.map +0 -1
  847. package/dist/services/version-check.js.map +0 -1
  848. package/dist/services/watch/fleet-log.d.ts.map +0 -1
  849. package/dist/services/watch/fleet-log.js.map +0 -1
  850. package/dist/services/watch/project-resolver.d.ts.map +0 -1
  851. package/dist/services/watch/project-resolver.js.map +0 -1
  852. package/dist/services/watch/transcript-formatter.d.ts.map +0 -1
  853. package/dist/services/watch/transcript-formatter.js.map +0 -1
  854. package/dist/smoke-test.d.ts.map +0 -1
  855. package/dist/smoke-test.js.map +0 -1
  856. package/dist/tools/check-status.d.ts.map +0 -1
  857. package/dist/tools/check-status.js.map +0 -1
  858. package/dist/tools/child-id-allocator.d.ts.map +0 -1
  859. package/dist/tools/child-id-allocator.js.map +0 -1
  860. package/dist/tools/cloud-control.d.ts.map +0 -1
  861. package/dist/tools/cloud-control.js.map +0 -1
  862. package/dist/tools/code-intelligence-codebase-memory.d.ts.map +0 -1
  863. package/dist/tools/code-intelligence-codebase-memory.js.map +0 -1
  864. package/dist/tools/code-intelligence-freshness.d.ts.map +0 -1
  865. package/dist/tools/code-intelligence-freshness.js.map +0 -1
  866. package/dist/tools/code-intelligence-gitnexus.d.ts.map +0 -1
  867. package/dist/tools/code-intelligence-gitnexus.js.map +0 -1
  868. package/dist/tools/code-intelligence-kb-enrich.d.ts.map +0 -1
  869. package/dist/tools/code-intelligence-kb-enrich.js.map +0 -1
  870. package/dist/tools/code-intelligence-reindex.d.ts.map +0 -1
  871. package/dist/tools/code-intelligence-reindex.js.map +0 -1
  872. package/dist/tools/code-intelligence-telemetry.d.ts.map +0 -1
  873. package/dist/tools/code-intelligence-telemetry.js.map +0 -1
  874. package/dist/tools/code-intelligence-tests.d.ts.map +0 -1
  875. package/dist/tools/code-intelligence-tests.js.map +0 -1
  876. package/dist/tools/code-intelligence.d.ts.map +0 -1
  877. package/dist/tools/code-intelligence.js.map +0 -1
  878. package/dist/tools/compose-permissions.d.ts.map +0 -1
  879. package/dist/tools/compose-permissions.js.map +0 -1
  880. package/dist/tools/credential-store-delete.d.ts.map +0 -1
  881. package/dist/tools/credential-store-delete.js.map +0 -1
  882. package/dist/tools/credential-store-list.d.ts.map +0 -1
  883. package/dist/tools/credential-store-list.js.map +0 -1
  884. package/dist/tools/credential-store-set.d.ts.map +0 -1
  885. package/dist/tools/credential-store-set.js.map +0 -1
  886. package/dist/tools/credential-store-update.d.ts.map +0 -1
  887. package/dist/tools/credential-store-update.js.map +0 -1
  888. package/dist/tools/dolt-push-mutex.d.ts.map +0 -1
  889. package/dist/tools/dolt-push-mutex.js.map +0 -1
  890. package/dist/tools/execute-command.d.ts.map +0 -1
  891. package/dist/tools/execute-command.js.map +0 -1
  892. package/dist/tools/execute-prompt.d.ts.map +0 -1
  893. package/dist/tools/execute-prompt.js.map +0 -1
  894. package/dist/tools/get-member-model-pricing.d.ts.map +0 -1
  895. package/dist/tools/get-member-model-pricing.js.map +0 -1
  896. package/dist/tools/kb-capture.d.ts.map +0 -1
  897. package/dist/tools/kb-capture.js.map +0 -1
  898. package/dist/tools/kb-context.d.ts.map +0 -1
  899. package/dist/tools/kb-context.js.map +0 -1
  900. package/dist/tools/kb-export.d.ts.map +0 -1
  901. package/dist/tools/kb-export.js.map +0 -1
  902. package/dist/tools/kb-feedback.d.ts.map +0 -1
  903. package/dist/tools/kb-feedback.js.map +0 -1
  904. package/dist/tools/kb-freshness-sweep.d.ts.map +0 -1
  905. package/dist/tools/kb-freshness-sweep.js.map +0 -1
  906. package/dist/tools/kb-harvest.d.ts.map +0 -1
  907. package/dist/tools/kb-harvest.js.map +0 -1
  908. package/dist/tools/kb-import.d.ts.map +0 -1
  909. package/dist/tools/kb-import.js.map +0 -1
  910. package/dist/tools/kb-invalidate.d.ts.map +0 -1
  911. package/dist/tools/kb-invalidate.js.map +0 -1
  912. package/dist/tools/kb-list.d.ts.map +0 -1
  913. package/dist/tools/kb-list.js.map +0 -1
  914. package/dist/tools/kb-promote.d.ts.map +0 -1
  915. package/dist/tools/kb-promote.js.map +0 -1
  916. package/dist/tools/kb-query.d.ts.map +0 -1
  917. package/dist/tools/kb-query.js.map +0 -1
  918. package/dist/tools/kb-reconcile-prefilter.d.ts.map +0 -1
  919. package/dist/tools/kb-reconcile-prefilter.js.map +0 -1
  920. package/dist/tools/kb-resolve-contradiction.d.ts.map +0 -1
  921. package/dist/tools/kb-resolve-contradiction.js.map +0 -1
  922. package/dist/tools/kb-session-prime.d.ts.map +0 -1
  923. package/dist/tools/kb-session-prime.js.map +0 -1
  924. package/dist/tools/kb-setup.d.ts.map +0 -1
  925. package/dist/tools/kb-setup.js.map +0 -1
  926. package/dist/tools/kb-stats.d.ts.map +0 -1
  927. package/dist/tools/kb-stats.js.map +0 -1
  928. package/dist/tools/list-members.d.ts.map +0 -1
  929. package/dist/tools/list-members.js.map +0 -1
  930. package/dist/tools/member-detail.d.ts.map +0 -1
  931. package/dist/tools/member-detail.js.map +0 -1
  932. package/dist/tools/member-reservation.d.ts.map +0 -1
  933. package/dist/tools/member-reservation.js.map +0 -1
  934. package/dist/tools/monitor-task.d.ts.map +0 -1
  935. package/dist/tools/monitor-task.js.map +0 -1
  936. package/dist/tools/provision-auth.d.ts.map +0 -1
  937. package/dist/tools/provision-auth.js.map +0 -1
  938. package/dist/tools/provision-vcs-auth.d.ts.map +0 -1
  939. package/dist/tools/provision-vcs-auth.js.map +0 -1
  940. package/dist/tools/receive-files.d.ts.map +0 -1
  941. package/dist/tools/receive-files.js.map +0 -1
  942. package/dist/tools/register-member.d.ts.map +0 -1
  943. package/dist/tools/register-member.js.map +0 -1
  944. package/dist/tools/remove-member.d.ts.map +0 -1
  945. package/dist/tools/remove-member.js.map +0 -1
  946. package/dist/tools/report-status.d.ts.map +0 -1
  947. package/dist/tools/report-status.js.map +0 -1
  948. package/dist/tools/respond-to-message.d.ts.map +0 -1
  949. package/dist/tools/respond-to-message.js.map +0 -1
  950. package/dist/tools/revoke-vcs-auth.d.ts.map +0 -1
  951. package/dist/tools/revoke-vcs-auth.js.map +0 -1
  952. package/dist/tools/send-email.d.ts.map +0 -1
  953. package/dist/tools/send-email.js.map +0 -1
  954. package/dist/tools/send-files.d.ts.map +0 -1
  955. package/dist/tools/send-files.js.map +0 -1
  956. package/dist/tools/send-message.d.ts.map +0 -1
  957. package/dist/tools/send-message.js.map +0 -1
  958. package/dist/tools/setup-git-app.d.ts.map +0 -1
  959. package/dist/tools/setup-git-app.js.map +0 -1
  960. package/dist/tools/setup-ssh-key.d.ts.map +0 -1
  961. package/dist/tools/setup-ssh-key.js.map +0 -1
  962. package/dist/tools/shutdown-server.d.ts.map +0 -1
  963. package/dist/tools/shutdown-server.js.map +0 -1
  964. package/dist/tools/stop-prompt.d.ts.map +0 -1
  965. package/dist/tools/stop-prompt.js.map +0 -1
  966. package/dist/tools/update-agent-cli.d.ts.map +0 -1
  967. package/dist/tools/update-agent-cli.js.map +0 -1
  968. package/dist/tools/update-member.d.ts.map +0 -1
  969. package/dist/tools/update-member.js.map +0 -1
  970. package/dist/tools/vcs-credential-exec.d.ts.map +0 -1
  971. package/dist/tools/vcs-credential-exec.js.map +0 -1
  972. package/dist/tools/version.d.ts.map +0 -1
  973. package/dist/tools/version.js.map +0 -1
  974. package/dist/types.d.ts.map +0 -1
  975. package/dist/types.js.map +0 -1
  976. package/dist/utils/agent-helpers.d.ts.map +0 -1
  977. package/dist/utils/agent-helpers.js.map +0 -1
  978. package/dist/utils/ansi.d.ts.map +0 -1
  979. package/dist/utils/ansi.js.map +0 -1
  980. package/dist/utils/auth-env.d.ts.map +0 -1
  981. package/dist/utils/auth-env.js.map +0 -1
  982. package/dist/utils/collect-secret.d.ts.map +0 -1
  983. package/dist/utils/collect-secret.js.map +0 -1
  984. package/dist/utils/credential-validation.d.ts.map +0 -1
  985. package/dist/utils/credential-validation.js.map +0 -1
  986. package/dist/utils/crypto.d.ts.map +0 -1
  987. package/dist/utils/crypto.js.map +0 -1
  988. package/dist/utils/deep-merge.d.ts.map +0 -1
  989. package/dist/utils/deep-merge.js.map +0 -1
  990. package/dist/utils/file-permissions.d.ts.map +0 -1
  991. package/dist/utils/file-permissions.js.map +0 -1
  992. package/dist/utils/gpu-parser.d.ts.map +0 -1
  993. package/dist/utils/gpu-parser.js.map +0 -1
  994. package/dist/utils/log-helpers.d.ts.map +0 -1
  995. package/dist/utils/log-helpers.js.map +0 -1
  996. package/dist/utils/oob-timeout.d.ts.map +0 -1
  997. package/dist/utils/oob-timeout.js.map +0 -1
  998. package/dist/utils/opencode-model-validation.d.ts.map +0 -1
  999. package/dist/utils/opencode-model-validation.js.map +0 -1
  1000. package/dist/utils/pid-helpers.d.ts.map +0 -1
  1001. package/dist/utils/pid-helpers.js.map +0 -1
  1002. package/dist/utils/platform.d.ts.map +0 -1
  1003. package/dist/utils/platform.js.map +0 -1
  1004. package/dist/utils/process-utils.d.ts.map +0 -1
  1005. package/dist/utils/process-utils.js.map +0 -1
  1006. package/dist/utils/prompt-errors.d.ts.map +0 -1
  1007. package/dist/utils/prompt-errors.js.map +0 -1
  1008. package/dist/utils/resolve-member.d.ts.map +0 -1
  1009. package/dist/utils/resolve-member.js.map +0 -1
  1010. package/dist/utils/secure-input.d.ts.map +0 -1
  1011. package/dist/utils/secure-input.js.map +0 -1
  1012. package/dist/utils/session-caller.d.ts.map +0 -1
  1013. package/dist/utils/session-caller.js.map +0 -1
  1014. package/dist/utils/shell-escape.d.ts.map +0 -1
  1015. package/dist/utils/shell-escape.js.map +0 -1
  1016. package/dist/utils/skill-matrix.d.ts.map +0 -1
  1017. package/dist/utils/skill-matrix.js.map +0 -1
  1018. package/dist/utils/ssh-error-messages.d.ts.map +0 -1
  1019. package/dist/utils/ssh-error-messages.js.map +0 -1
  1020. package/dist/utils/vcs-provider-detect.d.ts.map +0 -1
  1021. package/dist/utils/vcs-provider-detect.js.map +0 -1
  1022. package/dist/utils/work-folder-validation.d.ts.map +0 -1
  1023. package/dist/utils/work-folder-validation.js.map +0 -1
  1024. package/dist/utils/workspace-trust.d.ts.map +0 -1
  1025. package/dist/utils/workspace-trust.js.map +0 -1
  1026. package/dist/version.d.ts.map +0 -1
  1027. package/dist/version.js.map +0 -1
@@ -1,13 +1,38 @@
1
+ /**
2
+ * @typedef {Object} FleetSnapshotMember
3
+ * @property {string} id
4
+ * @property {string} name
5
+ * @property {string} icon
6
+ * @property {string|null} category
7
+ * @property {'busy'|'idle'|'offline'|'unknown'} status
8
+ * @property {number} [quietForS] While busy: seconds since the task last showed activity.
9
+ * @property {string} [reservedBy] Holder of the member reservation, when held.
10
+ */
11
+
12
+ /**
13
+ * @typedef {Object} FleetSnapshot
14
+ * @property {string} version Server version.
15
+ * @property {FleetSnapshotMember[]} members
16
+ */
17
+
1
18
  /**
2
19
  * @typedef {Object} ExecutePromptOptions
3
20
  * @property {string} prompt - The prompt to send to the LLM on the remote member
4
21
  * @property {string} [agent] - Optional agent name to activate
5
- * @property {number} [max_total_s] - Hard ceiling in seconds
22
+ * @property {number} [max_total_s] - Hard ceiling in seconds, measured from when the server
23
+ * receives the call (setup counts); exceeding it returns reason 'max_total_time'
6
24
  * @property {number} [max_turns] - Max turns for claude -p (default: 50)
25
+ * @property {boolean} [fail_on_permission_denial] - Strict permission handling (default false).
26
+ * true: a refused tool call fails with reason 'permission_denied' (except a healable:false
27
+ * Claude refusal on a complete reply, which is a permissionWarning). Omitted/false: a complete
28
+ * Claude reply succeeds with the refusals in permissionWarning; AGY refusals still fail.
29
+ * A max_turns/auth/server/overloaded result keeps its own reason either way, with the
30
+ * refusals attached as permissionDenied.
7
31
  * @property {string} [member_id] - UUID of the member
8
32
  * @property {string} [member_name] - Friendly name of the member
9
33
  * @property {string} [model] - Model tier ("cheap", "standard", "premium") or a specific model ID
10
- * @property {boolean|string} [resume] - Resume the previous session if one exists. Defaults to
34
+ * @property {boolean|string} [resume] - Resume the previous session if one exists (`true` starts
35
+ * fresh instead when the stored session was recorded by a different server build). Defaults to
11
36
  * true at this client/transport layer when the field is omitted entirely. NOTE: the
12
37
  * FleetWorkflow.agent() workflow layer (packages/apra-fleet-workflow/src/workflow/index.mjs)
13
38
  * always sends this field explicitly, defaulting it to `false` for workflow-authored
@@ -65,6 +90,8 @@
65
90
  * @typedef {Object} PermissionDenialItem
66
91
  * @property {string} action - Provider permission action, e.g. 'command', 'read_file', 'mcp'.
67
92
  * @property {string} [target] - The concrete target when the CLI named it, e.g. 'git status --short --branch'.
93
+ * @property {string[]} [suggestedGrants] - compose_permissions grants that would allow this one
94
+ * call, primary first (empty when no grant maps to it).
68
95
  */
69
96
 
70
97
  /**
@@ -75,9 +102,18 @@
75
102
  * @property {string[]} suggestedGrants - compose_permissions `grant` values that would allow the
76
103
  * denied calls, primary first (for an agy command or unsandboxed denial, on any OS, a
77
104
  * `Bash(<cmd>:*)` prefix grant, then the exact command as the narrow alternative); empty when no
78
- * canonical mapping exists.
105
+ * canonical mapping exists, and always empty when `healable` is false (never grant those).
79
106
  * @property {string} hint - One-line remediation.
80
107
  * @property {Array<'result_json'|'stderr'|'transcript'>} signals - Which CLI signals reported it.
108
+ * @property {string} [permissionMode] - The permission mode the session ran in, when the
109
+ * provider knows it (Claude: 'auto' | 'acceptEdits' | 'bypassPermissions').
110
+ * @property {boolean} [healable] - false when no grant may ever be added for these denials
111
+ * (Claude auto/bypass mode: the safety classifier or a deny rule refused the call, not a
112
+ * missing allow rule; or, in any mode, a fleet tool outside the member allowlist was refused
113
+ * -- see `cause`). Absent = a grant may heal it.
114
+ * @property {'policy_deny'} [cause] - 'policy_deny' when at least one refused call was a fleet
115
+ * tool outside the member allowlist, denied by the member's own permission config on purpose.
116
+ * Always comes with `healable: false`; never grant it.
81
117
  */
82
118
 
83
119
  /**
@@ -89,12 +125,28 @@
89
125
  * @property {boolean} [isError] - true on any failure path; absent/false on success.
90
126
  * @property {string} [reason] - Machine-readable failure/status classification, e.g.
91
127
  * 'busy' | 'nonzero_exit' | 'max_turns_exhausted' | 'empty_response' | 'overloaded' |
92
- * 'usage_limit' | 'workspace_not_trusted' | 'session_not_found' | 'permission_denied' | ...
128
+ * 'usage_limit' | 'workspace_not_trusted' | 'session_not_found' | 'permission_denied' |
129
+ * 'stalled' (transcript froze past the stall threshold) |
130
+ * 'agent_never_started' (session log never appeared at its authoritative path within
131
+ * timeout_s; the process was killed) |
132
+ * 'max_total_time' (max_total_s, measured from the call including setup, ran out) |
133
+ * 'secret_delivery_unavailable' (the member's stored credentials cannot be delivered
134
+ * without a command line -- relay member or SFTP disabled; deterministic, do not retry;
135
+ * no LLM call was made) | ...
93
136
  * @property {PermissionDenied} [permissionDenied] - Present when `reason === 'permission_denied'`:
94
- * the member CLI refused tool calls for lack of a grant (AGY headless mode auto-denies them
95
- * and exits 0, which used to surface as 'empty_response'). Pass `suggestedGrants` to
96
- * compose_permissions `grant` to heal it; read it with {@link permissionDenialOf}. Any partial
97
- * reply is in `response`.
137
+ * the member CLI refused tool calls (AGY headless mode auto-denies them and exits 0; Claude
138
+ * reports them in its result event's non-empty `permission_denials`). For Claude this needs the
139
+ * caller's `fail_on_permission_denial: true`; AGY fails this way either way. Pass
140
+ * `suggestedGrants` to compose_permissions `grant` to heal it; read it with
141
+ * {@link permissionDenialOf}. Any partial reply is in `response`. A healable:false Claude
142
+ * refusal (auto/bypass mode) on a complete reply is a `permissionWarning`, not this failure;
143
+ * on an incomplete one it fails here with `healable: false` and no suggested grants. Also
144
+ * present as an EXTRA field on a typed failure (max_turns_exhausted, auth, server,
145
+ * overloaded, ...) or a non-strict Claude failure whose turn carried refusals: the typed
146
+ * reason wins.
147
+ * @property {PermissionDenied} [permissionWarning] - Present on a SUCCESSFUL dispatch whose
148
+ * session refused tool calls without failing it: a healable:false refusal (never grant it),
149
+ * or any Claude refusal when `fail_on_permission_denial` was not set. A logged warning.
98
150
  * @property {UsageLimitSignal} [usageLimit] - Present when `reason === 'usage_limit'`
99
151
  * (apra-fleet-hzeb.2): the provider's detectUsageLimit() signal verbatim -- a 429/quota
100
152
  * exhaustion that a fresh session cannot cure, so execute_prompt returns this INSTEAD of
@@ -102,16 +154,62 @@
102
154
  * paths. Read `usageLimit.resumeAt`/`resumeAtSource` to schedule a resume rather than
103
155
  * re-parsing the failure text; `packages/apra-fleet-workflow` forwards this unchanged onto
104
156
  * `AgentDispatchError.details.usageLimit`.
157
+ * @property {false} [dispatched] - false when nothing was sent to the member: a
158
+ * 'max_total_time' failure whose budget ran out during setup (cloud start, before the first
159
+ * attempt). No agent ran, so there is no partial work to publish. Absent on every other
160
+ * result (including a 'max_total_time' that stopped a running dispatch);
161
+ * `packages/apra-fleet-workflow` forwards it onto `AgentDispatchError.details.dispatched`.
105
162
  * @property {string} [response] - The LLM's actual reply text on success.
106
163
  * @property {string} [sessionId] - The session id this dispatch landed on, when known --
107
- * present on success AND on a 'usage_limit'/'max_turns_exhausted' failure so the SAME
108
- * session can be resumed later instead of losing context to a fresh one.
109
- * @property {{input_tokens:number, output_tokens:number, total_tokens:number}} [usage]
164
+ * present on success AND on a 'usage_limit' or typed-failure result ('max_turns_exhausted',
165
+ * 'empty_response', 'dispatch_failed', 'nonzero_exit', 'auth', 'server', 'overloaded') whenever
166
+ * the provider parsed one, so the SAME session can be resumed by explicit id later instead of
167
+ * losing context to a fresh one. The server also records it as a known session. Absent when
168
+ * the provider supplied none.
169
+ * @property {ExecutePromptUsage} [usage]
170
+ */
171
+
172
+ /**
173
+ * @typedef {Object} ExecutePromptUsage
174
+ * @property {number} input_tokens - Uncached prompt tokens.
175
+ * @property {number} output_tokens - Completion tokens.
176
+ * @property {number} cache_read_input_tokens - Prompt tokens served from the provider's
177
+ * prompt cache; billed, and NOT included in input_tokens (0 when the provider reports none).
178
+ * @property {number} cache_creation_input_tokens - Prompt tokens written to the provider's
179
+ * prompt cache; billed, and NOT included in input_tokens (0 when the provider reports none).
180
+ * @property {number} total_tokens - input_tokens + output_tokens only (the context-window
181
+ * figure context admission reads); it deliberately EXCLUDES the cache counts, so a cost
182
+ * figure must price all four counts rather than total_tokens.
183
+ * @property {number} [cost_usd] - USD this dispatch cost as the provider CLI reported it
184
+ * (Claude: the per-dispatch share of the cumulative total_cost_usd). Use it as-is when
185
+ * present; price the token counts only when it is absent.
186
+ */
187
+
188
+ /**
189
+ * @typedef {Object} ModelPrice
190
+ * @property {string} model - Concrete model the tier resolves to.
191
+ * @property {number} promptPrice - $/1M input_tokens.
192
+ * @property {number} completionPrice - $/1M output_tokens.
193
+ * @property {number} cacheReadPrice - $/1M cache_read_input_tokens (the model's own cache-hit rate).
194
+ * @property {number} cacheWritePrice - $/1M cache_creation_input_tokens (Claude: the 1-hour
195
+ * cache-write rate, 2x input, which the Claude Code CLI uses).
196
+ */
197
+
198
+ /**
199
+ * @typedef {Object} MemberModelPricingResult
200
+ * @property {string} member_id
201
+ * @property {string} member_name
202
+ * @property {string} llm_provider
203
+ * @property {{cheap: ModelPrice|null, standard: ModelPrice|null, premium: ModelPrice|null}} pricing
204
+ * - null for a tier whose resolved model has no known price.
110
205
  */
111
206
 
112
207
  /**
113
208
  * @typedef {Object} ExecuteCommandOptions
114
- * @property {string} command - The shell command to execute
209
+ * @property {string} command - The shell command to execute. Multi-line commands and heredocs
210
+ * are supported. On POSIX members (linux, macos, windows Git Bash) the server passes it to its
211
+ * wrapper as data (`eval '<command>'`), so the work-folder `cd` covers the whole command and a
212
+ * syntax error in it surfaces on stderr as `eval: line N: ...` (not `-c: line N: ...`).
115
213
  * @property {boolean} [long_running] - Run as background task. Supported on linux and windows
116
214
  * members. Windows launches the task detached via `Invoke-CimMethod Win32_Process.Create`
117
215
  * (WMI provider host / session 0), independent of the SSH session's job object, since a plain
@@ -132,6 +230,50 @@
132
230
  * cannot cancel a job already accepted by the remote fleet-server (see client.mjs).
133
231
  */
134
232
 
233
+ /**
234
+ * @typedef {Object} SessionStatsOptions
235
+ * @property {string} [member_id] - Member uuid to read; omit on a member session (the calling member is used), required on a non-member session
236
+ */
237
+
238
+ /**
239
+ * @typedef {Object} SessionStatsResult
240
+ * @property {string} member_id - Member uuid the counts belong to
241
+ * @property {string} since - ISO time counting started (server start); a change between two snapshots means the server restarted
242
+ * @property {number} kb - kb_* calls counted
243
+ * @property {number} code - code_* calls counted
244
+ * @property {number} total - kb + code
245
+ * @property {Object<string, number>} tools - Per-tool counts (tools called at least once)
246
+ */
247
+
248
+ /**
249
+ * Result-side shape of execute_command's `structuredContent`. Mirrors
250
+ * src/tools/execute-command.ts's ExecuteCommandStructured. A command that ran
251
+ * reports its real `exitCode` (isError absent). A command that never produced an
252
+ * exit code -- the exec timed out, the transport failed, a cloud member could
253
+ * not be started, or the pre-dispatch check failed -- reports `isError: true`,
254
+ * a `reason`, and `exitCode: -1` (never a fake 0). Read it with
255
+ * {@link commandFailureOf}.
256
+ * @typedef {Object} ExecuteCommandStructured
257
+ * @property {number} exitCode - Exit code of the command; -1 when it never produced one.
258
+ * @property {string} stdout - Command stdout (credential values redacted).
259
+ * @property {string} stderr - Command stderr, or the failure detail when isError is true.
260
+ * @property {boolean} [isError] - true when the command did not run to an exit code.
261
+ * @property {string} [reason] - Present with isError: 'timeout' (inactivity timeout) |
262
+ * 'max_total_time' (hard total-time cap) | 'transport_error' (connection/channel failure) |
263
+ * 'cloud_start_failed' | 'preflight_offline' | 'preflight_auth_expired' |
264
+ * 'preflight_auth_missing'.
265
+ * @property {'secret_delivery_unavailable'} [storedEnvNotDelivered] - Present when the
266
+ * command ran WITHOUT the member's stored credential env vars because no
267
+ * owner-only file channel exists to deliver them (SFTP disabled, relay member).
268
+ */
269
+
270
+ /**
271
+ * @typedef {Object} ExecuteCommandFailure
272
+ * @property {string} reason - The structured reason, or 'unflagged_failure' for a failure
273
+ * recognized only from the text of an older server that sent no structuredContent.
274
+ * @property {string} message - Human-readable failure text.
275
+ */
276
+
135
277
  /**
136
278
  * @typedef {Object} ListMembersOptions
137
279
  * @property {"compact" | "json"} [format] - Output format
@@ -141,6 +283,24 @@
141
283
  /**
142
284
  * @typedef {Object} FleetStatusOptions
143
285
  * @property {"compact" | "json"} [format] - Output format
286
+ * @property {string} [repo_path] - Absolute path to a repo checkout; adds that repo's code-intelligence index health and its KB scope's bible drift. The server's own cwd is never used. KB health itself always covers every project KB scope plus the global KB.
287
+ */
288
+
289
+ /**
290
+ * Remote KB credential health, `kbHealth.credential` in fleet_status json
291
+ * output (one compact `kb credential:` line in compact output). Present only
292
+ * when the KB config selects the http provider; this host only. Never carries
293
+ * the token value, nor any JWT claim other than exp.
294
+ * @typedef {Object} FleetStatusKbCredential
295
+ * @property {"secret" | "literal"} kind - "secret": token_ref names a fleet secret looked up per request; "literal": a stored literal token
296
+ * @property {string} url - Remote KB URL
297
+ * @property {string} [secretName] - kind "secret": the fleet secret's name
298
+ * @property {"ok" | "missing" | "expired" | "unreadable"} [resolves] - kind "secret": metadata lookup result (an expired record is kept); "unreadable" when the credential store cannot be read or the value cannot be decrypted
299
+ * @property {string | null} [lastWritten] - kind "secret": the secret record's created_at; null when missing or the store is unreadable
300
+ * @property {string | null} [tokenExpiry] - kind "secret": JWT exp decoded locally (ISO time); null for a non-JWT or unresolved value
301
+ * @property {string | null} lastSuccessfulCall - Last KB call accepted by the remote server in this server process; null when none yet
302
+ * @property {string | null} lastRejectedCall - Last KB call rejected with HTTP 401 in this server process; null when none yet
303
+ * @property {string} [hint] - kind "literal": the token cannot be refreshed; how to switch to {{secret.NAME}}
144
304
  */
145
305
 
146
306
  /**
@@ -163,7 +323,7 @@
163
323
  /**
164
324
  * @typedef {Object} RegisterMemberOptions
165
325
  * @property {string} friendly_name - Human-friendly name for this member (required)
166
- * @property {string} work_folder - Working directory on the target machine (required). For remote members, must be a fully-qualified/absolute path -- "~" and relative paths are rejected.
326
+ * @property {string} work_folder - Working directory on the target machine (required). For remote members, must be a fully-qualified/absolute path -- "~" and relative paths are rejected. A folder may hold at most one LLM member and one LLM-less (llm_provider none) member.
167
327
  * @property {"local" | "remote"} [member_type] - Member type (default: "remote")
168
328
  * @property {string} [host] - IP address or hostname of the remote machine
169
329
  * @property {string} [username] - SSH username
@@ -189,7 +349,9 @@
189
349
  * @property {string} [category] - Optional group label
190
350
  * @property {string[]} [tags] - Optional list of free-form labels
191
351
  * @property {"false" | "auto" | "dangerous"} [unattended] - Permission mode for unattended execution
192
- * @property {boolean} [unreservable] - Mark this member as never exclusively reservable, so it can be shared by more than one sprint at once (e.g. fleet-sprint's shared "orchestrator" role)
352
+ * ("auto" on a Claude model without auto-mode support, such as Haiku, runs acceptEdits)
353
+ * @property {boolean} [unreservable] - Mark this member as never exclusively reservable, so it can be shared by more than one sprint at once (e.g. fleet-sprint's shared "backlog" role)
354
+ * @property {"auto" | "skip" | "replace-full"} [fleet_install] - Whether registration installs/updates apra-fleet on the member, writes its per-folder apra-fleet MCP entry and verifies it (default "auto"; local members only get the MEMBER-session probe; a full install without the member-install marker is never touched). "replace-full": also explicitly opts in to replacing such a full install with a member install (backup of data and fleet.key, uninstall, member install, self-register). "skip" performs no install and reports the probe result only. Registration succeeds either way; the result reports fleetMcp, plus a WARNING (consequence, exact reason, OS-correct manual install steps; also fleetMcp.manualInstall) when a requested install/upgrade did not happen.
193
355
  * @property {"gitbash" | "pwsh7" | "powershell5"} [shell] - Override the probed Windows shell for this member. Windows members only -- ignored for non-windows members.
194
356
  */
195
357
 
@@ -197,8 +359,9 @@
197
359
  * @typedef {Object} UpdateMemberOptions
198
360
  * @property {string} [member_id] - UUID of the member
199
361
  * @property {string} [member_name] - Friendly name of the member
362
+ * @property {"auto" | "skip" | "replace-full"} [fleet_install] - "auto": for a remote member, install/upgrade the member's own apra-fleet when missing or older (build-aware), self-register, write its per-folder apra-fleet MCP entry and verify, even when nothing else changed; an install/upgrade that ran (or an install that only now became available) also adds the member apra-fleet tool rules to a claude member's permission allow-list through compose_permissions grant mode, keeping its role and grants (a NOTICE says so; a failure is a WARNING); a full install without the member-install marker is never touched. "replace-full": "auto" plus an explicit opt-in to replace such a full install with a member install (backup of data and fleet.key, uninstall, member install, self-register). "skip": never install. Omit: install only on a provider change. A requested install/upgrade that cannot happen never fails the update: the result adds a WARNING (consequence, exact reason, OS-correct manual install steps; also fleetMcp.manualInstall). Unknown input keys are rejected by the server.
200
363
  * @property {string} [friendly_name] - New friendly name
201
- * @property {string} [work_folder] - New working directory. For non-local (remote/relay) members, must be a fully-qualified/absolute path -- "~" and relative paths are rejected.
364
+ * @property {string} [work_folder] - New working directory. For non-local (remote/relay) members, must be a fully-qualified/absolute path -- "~" and relative paths are rejected. A folder may hold at most one LLM member and one LLM-less (llm_provider none) member.
202
365
  * @property {string} [host] - New host
203
366
  * @property {string} [username] - New SSH username
204
367
  * @property {number} [port] - New SSH port
@@ -221,12 +384,41 @@
221
384
  * @property {"codebase-memory" | "gitnexus" | "none"} [code_intel_provider] - Change the code-intelligence provider for this member
222
385
  * @property {string} [category] - Group label
223
386
  * @property {string[]} [tags] - Free-form labels
224
- * @property {"false" | "auto" | "dangerous"} [unattended] - Permission mode
387
+ * @property {"false" | "auto" | "dangerous"} [unattended] - Permission mode ("auto" on a
388
+ * Claude model without auto-mode support, such as Haiku, runs acceptEdits)
225
389
  * @property {boolean} [unreservable] - Mark/unmark this member as shared/never exclusively reservable
226
390
  * @property {"gitbash" | "pwsh7" | "powershell5"} [shell] - Override the probed Windows shell for this member. Windows members only -- ignored for non-windows members.
227
391
  * @property {"github" | "bitbucket" | "azure-devops" | "none"} [vcs_provider] - Directly set (override) this member's VCS provider. An explicit operator value, never auto-detected -- use this to correct a wrong auto-detect from register_member, or to set the provider without provisioning credentials. "none" clears it.
228
392
  */
229
393
 
394
+ /**
395
+ * A member's own apra-fleet MCP observation (src/types.ts FleetMcpStatus).
396
+ * @typedef {Object} FleetMcpStatus
397
+ * @property {"available" | "unavailable"} state
398
+ * @property {string} [reason] - Machine-readable cause when unavailable (e.g. install-too-old, E-FOLDER-TAKEN, mcp-entry-missing, role-agents-hide-member-tools, no-per-project-mcp)
399
+ * @property {string} [version] - apra-fleet version the member's own install reports
400
+ * @property {string} checkedAt - ISO 8601 time of the probe
401
+ * @property {string} [detail] - Human-readable diagnostic
402
+ * @property {boolean} [unverified] - KB/code tools could not be verified (e.g. agy)
403
+ * @property {string} [fleetInstalledAt] - ISO 8601 time this fleet's own install run last succeeded on the member; carried across later probes; absent when the fleet never installed it (a refusal or observation-only probe never sets it)
404
+ * @property {{reason: string, detail?: string}} [installFailure] - A requested apra-fleet upgrade that failed before the member was touched while the older install stayed in use; present on available and unavailable statuses, also named in detail
405
+ * @property {{state: "missing" | "broken", detail: string, fix: string}} [beads] - Present only when the beads CLI (bd) is not usable on a remote member (not on its PATH nor in <home>/.apra-fleet/bin); independent of state; absent when bd works or could not be probed
406
+ * @property {number} [port] - Remote members: the port of the member's own apra-fleet install, resolved from its member-install marker; the member MCP URL (per-folder entry and per-session config) uses it
407
+ * @property {"marker" | "default"} [portSource] - Where port came from: the member-install marker, or the built-in default because the install recorded no port (detail says so)
408
+ * @property {{previousVersion: string, removed: string[], backupPath: string}} [replacedFullInstall] - Set by the probe that replaced a full install with a member install (fleet_install "replace-full"): replaced version, what was removed or moved, and the timestamped backup directory on the member
409
+ * @property {string} [manualInstall] - Set when a requested apra-fleet install/upgrade on the member did not happen (any install reason, e.g. no-matching-release, checksum-unavailable, download-failed): OS-correct manual steps to install the orchestrator build on the member by hand (anonymous release download URL, SHA-256 check, member-mode install, then update_member); register_member/update_member print them in a WARNING and still succeed
410
+ * @property {{tag: string, wantedBuild: string, why: string}} [sameCoreFallback] - Set when no release carries the orchestrator's exact build and the member had no apra-fleet or an older core, so the signed stable release of the same core (tag) was installed instead of wantedBuild; register_member/update_member print a NOTICE
411
+ */
412
+
413
+ /**
414
+ * Code intelligence availability reported by member_detail.
415
+ * @typedef {Object} CodeIntelStatus
416
+ * @property {string|null} provider - 'gitnexus' | 'codebase-memory' | 'none' (null when it could not be resolved)
417
+ * @property {boolean} available
418
+ * @property {string} [cause] - Why it is unavailable; absent when available
419
+ * @property {string} [remedy] - What to do about the cause; absent when available
420
+ */
421
+
230
422
  /**
231
423
  * Structured result returned by memberDetail() when called with format: 'json'
232
424
  * (src/tools/member-detail.ts). When format is 'compact' (the default), memberDetail()
@@ -250,12 +442,23 @@
250
442
  * minted token carries a given permission (e.g. GitHub's 'workflows', required to push any
251
443
  * .github/workflows/** change) must read THIS, not their own provisioning default -- the two differ
252
444
  * exactly for the members at risk.
445
+ * @property {string[]} [permissionConfigPaths] - The member's provider permission config file(s)
446
+ * that compose_permissions writes (work-folder-relative, or home-anchored "~/..."), e.g.
447
+ * ['.claude/settings.local.json'] for Claude. [] when the provider cannot name them yet (agy before
448
+ * its project is provisioned). Reported even for an offline member. Absent on older servers.
253
449
  * @property {Object} connectivity - Connectivity check result (status, latencyMs, auth, keyPath, or error)
254
450
  * @property {boolean} [offline] - Set when the member could not be reached
255
451
  * @property {string} llmProvider - LLM provider for this member (default: "claude")
256
452
  * @property {string|null} [agyProjectId] - agy members only: id of the member's own agy project
257
453
  * (~/.gemini/config/projects/<id>.json), passed as `--project <id>` on every dispatch; null until
258
454
  * provisioned (compose_permissions/execute_prompt provision it on first use)
455
+ * @property {FleetMcpStatus|null} fleetMcp - Last recorded state of the member's own apra-fleet MCP
456
+ * server (null when never probed). Recoverable: `member_detail { refresh: true }` re-probes and records.
457
+ * @property {string|null} [fleetMcpFix] - One-line operator fix for `fleetMcp` when the member's KB/code tools are
458
+ * not usable (state "unavailable" or `unverified`); null when available and verified
459
+ * @property {CodeIntelStatus|null} [codeIntel] - Whether code intelligence (code_* tools) can run for this member,
460
+ * with the cause and remedy when it cannot (e.g. npx/node missing from the apra-fleet service PATH). null for
461
+ * remote members: their code tools run on the member host, not on this server.
259
462
  * @property {Object} [llm_cli] - LLM CLI info: { version, auth }
260
463
  * @property {Object|string} [tokenUsage] - Cumulative token usage, or "compute only" for llmProvider "none"
261
464
  * @property {Object} [session] - Session info: { id, lastActivity, lastLlmActivityAt, status, idleSecs }
@@ -306,9 +509,18 @@
306
509
  * @typedef {Object} ProvisionLlmAuthOptions
307
510
  * @property {string} [member_id] - UUID of the member
308
511
  * @property {string} [member_name] - Friendly name of the member
309
- * @property {string} [api_key] - AI provider API key. If omitted, the local OAuth
310
- * session is copied to the member instead. Supports {{secret.NAME}} token --
311
- * resolved from the credential store server-side before use.
512
+ * @property {string} [api_key] - AI provider API key or Claude Code OAuth token
513
+ * (sk-ant-oat..., from `claude setup-token`; routed to CLAUDE_CODE_OAUTH_TOKEN). If
514
+ * omitted, a credential already stored for the member is re-deployed, else the local
515
+ * OAuth session is copied to the member. Supports {{secret.NAME}} token -- resolved
516
+ * from the credential store server-side before use.
517
+ * @property {boolean} [force_oauth_copy] - Only without api_key: copy the local OAuth
518
+ * session even when the member has a stored env credential, and clear that credential
519
+ * (ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN) so the copied login applies.
520
+ * @property {boolean} [clear_stored_credentials] - Remove ALL credential env vars stored for
521
+ * the member in the fleet registry and do nothing else (registry only; works for relay,
522
+ * offline and local members). The recovery for reason secret_delivery_unavailable.
523
+ * Cannot be combined with api_key or force_oauth_copy.
312
524
  */
313
525
 
314
526
  /**
@@ -324,10 +536,24 @@
324
536
  * with the value escaped for the interior of a single-quoted string, with no quotes of its
325
537
  * own, for interpolating the token into a larger already-quoted value (e.g. an Authorization
326
538
  * header) where a bare, self-quoting substitution cannot compose.
539
+ * Bitbucket REST uses the token as a Bearer value
540
+ * (-H 'Authorization: Bearer {{vcs_token_inline}}'), with no username and no email.
541
+ * Two further OPTIONAL placeholders substitute the credential helper's git username under
542
+ * exactly the same two dialects (for Bitbucket always x-bitbucket-api-token-auth, a git-only
543
+ * username, never a REST login): {{vcs_username}}, referenced BARE -- already escaped AND
544
+ * quoted for that member's shell; and {{vcs_username_inline}}, referenced INSIDE your own
545
+ * single quotes -- escaped for the interior of a single-quoted string, with no quotes of its
546
+ * own. A username placeholder may not appear on
547
+ * its own: a token placeholder is still required, or the call is refused with
548
+ * reason "placeholder_missing". If the command references a username placeholder and the
549
+ * helper prints no username= line, the call fails with reason "username_empty" and dispatches
550
+ * nothing.
327
551
  * @property {string} [label] - Credential label provision_vcs_auth deployed the helper under
328
552
  * (it defaults to the provider name there, e.g. "github" or "azure-devops"). Omit for the
329
553
  * unlabelled helper.
330
- * @property {number} [timeout_s] - Timeout in seconds for the command (default: 120).
554
+ * @property {number} [timeout_s] - Inactivity timeout in seconds for the command (default: 120).
555
+ * On expiry the command's remote process tree is killed and the result is reason
556
+ * 'dispatch_failed' with a "Command timed out" message.
331
557
  */
332
558
 
333
559
  /**
@@ -335,13 +561,15 @@
335
561
  * @property {boolean} ok - True when the credential-requiring command was dispatched. Read
336
562
  * exitCode for the command's own outcome.
337
563
  * @property {"ok" | "member_not_found" | "placeholder_missing" | "unsupported_member_os" |
338
- * "credential_read_failed" | "credential_empty" | "dispatch_failed"} reason - Machine-readable
564
+ * "credential_read_failed" | "credential_empty" | "username_empty" |
565
+ * "dispatch_failed"} reason - Machine-readable
339
566
  * outcome code. Branch on this, never on the text.
340
567
  * @property {number|null} exitCode - Exit code of the dispatched command, null if it never ran.
341
568
  * @property {string} stdout - Command stdout, with every occurrence of the credential redacted.
342
569
  * @property {string} stderr - Command stderr, with every occurrence of the credential redacted.
343
- * @property {number} tokenRedactions - How many times the credential had to be redacted out of
344
- * stdout+stderr. Normally 0; nonzero means the command echoed its own credential back.
570
+ * @property {number} tokenRedactions - How many times credential material had to be redacted out
571
+ * of stdout+stderr -- the token, plus the helper git username when the command substituted one.
572
+ * Normally 0; nonzero means the command echoed its own credential back.
345
573
  * @property {string|null} credentialLabel - Credential label used, or null for the unlabelled helper.
346
574
  * @property {string|null} memberId - Registry id of the resolved member, or null.
347
575
  * @property {string|null} memberName - Friendly name of the resolved member, or null.
@@ -358,7 +586,11 @@
358
586
  * "secret_variable_denied" | "secret_variable_expired" | "oauth_not_supported" |
359
587
  * "oauth_token_expired_no_refresh" | "oauth_credential_file_missing" |
360
588
  * "oauth_credential_write_failed" | "oauth_settings_merge_failed" | "oauth_copy_failed" |
361
- * "oob_cancelled"} reason - Machine-readable outcome code. Branch on this, never on the text.
589
+ * "oob_cancelled" | "secret_delivery_unavailable" | "stored_credentials_cleared" |
590
+ * "invalid_arguments"} reason - Machine-readable outcome code.
591
+ * Branch on this, never on the text. secret_delivery_unavailable: the member has no channel
592
+ * that delivers the key without a command line (relay member, SFTP unavailable).
593
+ * stored_credentials_cleared: clear_stored_credentials removed the stored env vars (ok=true).
362
594
  * @property {string|null} provider - The resolved ProviderAdapter's own name (claude, codex,
363
595
  * copilot, agy, opencode or none -- there is no gemini adapter), null when unresolved.
364
596
  * @property {string|null} credentialLabel - What was deployed, never the secret: the env var
@@ -379,8 +611,10 @@
379
611
  * @property {"ok" | "deployed_unverified" | "deployed_verification_skipped" |
380
612
  * "member_not_found" | "member_offline" | "secret_variable_not_found" |
381
613
  * "secret_variable_denied" | "secret_variable_expired" | "oob_cancelled" |
382
- * "credential_assembly_unsupported" | "credential_assembly_failed" | "deploy_threw" |
383
- * "deploy_failed"} reason - Machine-readable outcome code. Branch on this, never on the text.
614
+ * "credential_missing" | "credential_assembly_unsupported" | "credential_assembly_failed" |
615
+ * "deploy_threw" | "deploy_failed"} reason - Machine-readable outcome code. Branch on this,
616
+ * never on the text. "credential_missing": non_interactive was set and the secret field is
617
+ * absent (message names it; nothing was prompted).
384
618
  * @property {string} provider - The VCS provider requested.
385
619
  * @property {string} credentialLabel - Credential label the helper was deployed under
386
620
  * (defaults to the provider name).
@@ -390,6 +624,10 @@
390
624
  * instead of scraping an "expiresAt:" line out of the summary text.
391
625
  * @property {boolean} verified - True only when testConnectivity() actually ran AND succeeded.
392
626
  * @property {boolean} verificationSkipped - True when the connectivity check was not performed.
627
+ * @property {string|null} verificationReason - The provider's machine-readable verification
628
+ * cause naming which channel failed, when it reports one (Bitbucket: "ok",
629
+ * "rest_unauthorized", "rest_failed", "git_auth_failed", "git_failed"); null when the
630
+ * provider reports none or the check was skipped.
393
631
  * @property {Record<string, string>|null} metadata - The provider's own deploy metadata,
394
632
  * filtered through a server-side key allowlist before it reaches this field (an unrecognised
395
633
  * key is dropped, never passed through). Providers additionally mask the token value here to
@@ -413,6 +651,9 @@
413
651
  * @property {string} [member_name] - Friendly name of the member
414
652
  * @property {"github" | "bitbucket" | "azure-devops"} provider - VCS provider to configure
415
653
  * @property {string} [label] - Credential label (slug, e.g. "work-github"). Defaults to provider name.
654
+ * @property {boolean} [non_interactive] - When true, never prompt out of band: a missing secret
655
+ * field (api_token / pat / token) returns ok=false with reason "credential_missing" naming the
656
+ * field. Required non-secret fields are validated before any prompt in both modes. Default false.
416
657
  * @property {string} [scope_url] - Git credential scope URL (e.g. "https://github.com/my-org").
417
658
  * Defaults to "https://<host>". For an Azure DevOps repo on the legacy host, pass
418
659
  * "https://ORG.visualstudio.com" so the PAT is bound to the host the member pushes to.
@@ -420,13 +661,18 @@
420
661
  * configured app) or pat (personal access token)
421
662
  * @property {string} [token] - Personal access token (GitHub PAT or Azure DevOps PAT).
422
663
  * Supports {{secret.NAME}} token -- resolved from the credential store server-side before use.
423
- * @property {"read" | "push" | "push+pr" | "admin" | "issues" | "full"} [git_access] - GitHub App access
664
+ * @property {"read" | "push" | "push+pr" | "admin" | "issues" | "full"} [git_access] - GitHub App mode
665
+ * only: what the token may do. Use "push+pr" to create pull requests and dispatch workflows (see
666
+ * docs/api-reference.md for every level). GitHub App access
424
667
  * level override
425
668
  * @property {string[]} [repos] - GitHub App repository list override
426
- * @property {string} [email] - Bitbucket account email
427
- * @property {string} [api_token] - Bitbucket API token. Supports {{secret.NAME}} token --
428
- * resolved from the credential store server-side before use.
429
- * @property {string} [workspace] - Bitbucket workspace slug
669
+ * @property {string} [email] - OPTIONAL Bitbucket account email. Ignored for authentication
670
+ * (git uses the fixed token username x-bitbucket-api-token-auth, REST uses a Bearer token);
671
+ * kept only as metadata if given.
672
+ * @property {string} [api_token] - Bitbucket API token (required for bitbucket). Store it as the
673
+ * fleet secret bitbucket_api_token and pass {{secret.bitbucket_api_token}} -- resolved from
674
+ * the credential store server-side before use.
675
+ * @property {string} [workspace] - Bitbucket workspace slug (required for bitbucket).
430
676
  * @property {string} [org_url] - Azure DevOps organization URL (e.g. https://dev.azure.com/myorg,
431
677
  * or the legacy https://myorg.visualstudio.com)
432
678
  * @property {string} [pat] - Azure DevOps personal access token. Supports {{secret.NAME}}
@@ -480,6 +726,107 @@
480
726
  * shell-chaining metacharacter (| ; && backtick $() are rejected outright,
481
727
  * for every caller.
482
728
  * @property {string} [grant_reason] - Reason for the grant (stored in ledger)
729
+ * @property {boolean} [dry_run] - Compose only: return the allow list the role/tags
730
+ * (plus detected stacks, plus the ledger when project_folder is given) would deliver, as
731
+ * JSON text `{"dry_run":true,"mode","stacks","allow"}`, without writing anything to the
732
+ * member. Ignored with `grant`. Use it to check whether a grant is within the member's
733
+ * composed policy.
734
+ */
735
+
736
+ /**
737
+ * @typedef {Object} KbExportOptions
738
+ * No scope key: the KB is the calling session's own. The removed repo_path, repo and
739
+ * repo_remote_url are refused with E-SCOPE-KEY-REMOVED (client-side and by the server).
740
+ * @property {"project" | "global"} [scope] - project (default): export the project KB to
741
+ * .fleet/kb-canonical.json. global: export the GLOBAL KB to .fleet/kb-canonical-global.json.
742
+ * @property {string} [baseBranch] - The target base branch (the branch the entries merge
743
+ * into), written to provenance.branch. Omitted: the export folder HEAD branch.
744
+ * @property {string} [baseCommit] - The base commit the entries were verified against,
745
+ * written to provenance.commit. Omitted: the export folder HEAD commit.
746
+ */
747
+
748
+ /**
749
+ * @typedef {Object} KbBibleCommitOptions
750
+ * @property {string[]} ids - Ids of the entries confirmed this round. Ids that are not
751
+ * live CONFIRMED entries are skipped (reason not_confirmed_or_unknown); a CONFIRMED id
752
+ * whose cited files at the repo's HEAD commit no longer match its recorded basis (the
753
+ * same rule kb_export applies; uncommitted edits never change the verdict) is skipped
754
+ * with reason basis_mismatch, and a CONFIRMED id citing no source file is skipped with
755
+ * reason no_source_files. Skips are reported in the result's skipped list.
756
+ * Independently of ids, bible entries the KB holds as superseded or invalidated are
757
+ * removed and reported in the result's removed list, and existing bible entries with
758
+ * no source_file_hashes gain the KB's stored basis for the same id when it passes the
759
+ * same rule (counted in the result's backfilled); an empty list with nothing to remove
760
+ * or backfill makes no commit.
761
+ * @property {string} baseBranch - The target base branch, written to provenance.branch.
762
+ * @property {string} baseCommit - The base commit the entries were verified against,
763
+ * written to provenance.commit.
764
+ * @property {string[]} [demoted_ids] - Ids demoted this round (kb_demote). An id whose
765
+ * local row carries a demoted_at and is now below CONFIRMED is REMOVED from entries and
766
+ * recorded as an explicit tombstone {id, at, reason} in the bible's optional top-level
767
+ * demotions array; any other id is skipped with reason not_demoted_or_unknown. Existing
768
+ * tombstones are preserved, and re-committing a tombstoned id through ids (a
769
+ * re-promotion) restores its entry and clears its tombstone.
770
+ */
771
+
772
+ /**
773
+ * @typedef {Object} KbDemoteOptions
774
+ * @property {string} id - ID of the KB entry to demote.
775
+ * @property {string} reason - Why trust is being withdrawn -- at least 20 characters
776
+ * after newlines are collapsed to spaces and the result trimmed. Appended to the
777
+ * entry content as the audit trail; a reason made only of whitespace or newlines
778
+ * is refused.
779
+ * @property {string[]} evidence_files - At least one repo-relative file backing the
780
+ * demotion; an absent or empty list is refused by input validation before the
781
+ * tool runs. A path that is ABSOLUTE or contains a ".." segment is refused with
782
+ * E-DEMOTE-EVIDENCE-UNRESOLVED and nothing is written. Over a local SQLite KB each
783
+ * must also resolve to a real file (not a directory) inside the calling session's
784
+ * repo; over a remote (http) KB the KB server validates the rest of the evidence.
785
+ */
786
+
787
+ /**
788
+ * One entry of the bible file (.fleet/kb-canonical.json) kb_export and
789
+ * kb_bible_commit write and kb_import reads -- bible format v3, described by
790
+ * memory-contract/v1/bible/kb-canonical.schema.json. The file itself is
791
+ * {version: 3, provenance: {commit, branch, entry_count}, entries: KbBibleEntry[]};
792
+ * readers also accept v2 (same envelope, no hashes) and v1 (a bare entry array).
793
+ * @typedef {Object} KbBibleEntry
794
+ * @property {string} id - Entry id (unique within the bible; writers refuse a duplicate id).
795
+ * @property {string} type - Content type (knowledge, learning, runbook, context-cache, user-directive).
796
+ * @property {string} title - Entry title.
797
+ * @property {string} summary - Entry summary.
798
+ * @property {string[]} symbols - Symbols the entry is about.
799
+ * @property {string[]} source_files - Repo-relative files the entry cites.
800
+ * @property {string} confidence - CONFIRMED, INFERRED or UNVERIFIED.
801
+ * @property {string} updated_at - Promotion (or creation) timestamp.
802
+ * @property {Object<string, string>} [source_file_hashes] - v3: the per-file hash basis
803
+ * (repo-relative path -> hash) the entry was admitted against, copied from the
804
+ * exporting KB's stored basis. kb_import stores it as the entry's basis exactly
805
+ * (never re-hashing local files); an entry without it gets a local
806
+ * freshness-only basis (it can go stale) that is never exported, so it is not
807
+ * re-published until recaptured.
808
+ * Because kb_import keeps an entry's bible confidence and carried basis, an
809
+ * import from an explicit `path` is equivalent to kb_promote: a member session
810
+ * without the kb_maintainer grant is refused one (E-KB-MAINTAINER-REQUIRED,
811
+ * nothing imported) unless the path is its own .fleet/kb-canonical.json. Even
812
+ * then (and without path) such a session imports its own bible only as
813
+ * committed at HEAD, never the work-tree file; the result adds
814
+ * bible_source "HEAD" and worktree_ignored, and with no committed copy the
815
+ * import fails with E-KB-MAINTAINER-REQUIRED. A committed copy is trusted
816
+ * only when the maintainer side recorded its git blob id in the hub-side KB
817
+ * (kb_bible_commit, or kb_import from the kb_maintainer or a FULL session,
818
+ * records every bible it writes or imports); a bible committed only in the
819
+ * member's own checkout fails with E-KB-MAINTAINER-REQUIRED (the message
820
+ * names the unrecorded blob id) and nothing is imported. The blob's bytes
821
+ * are hashed in-process and must equal the trusted id (a replace ref or
822
+ * overwritten object in the member's .git is refused).
823
+ * kb_import also takes an optional `ref` (a plain git ref name, e.g.
824
+ * "refs/remotes/origin/main"): the bible is then read as committed at that
825
+ * ref (hash-verified) instead of from disk, in any session; the result's
826
+ * bible_source is the ref, a ref without the bible fails with
827
+ * E-BIBLE-NOT-FOUND, and a kb_maintainer or FULL session records that
828
+ * verified blob as trusted. The engine's sprint-start priming seeds trust
829
+ * this way from the base branch, never from the maintainer's work tree.
483
830
  */
484
831
 
485
832
  /**
@@ -577,6 +924,34 @@ export function parseToolJson(result) {
577
924
 
578
925
  const isStringArray = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
579
926
 
927
+ /**
928
+ * The pre-redesign kb_* scope keys. Every kb_* tool acts on the calling
929
+ * session's own KB, so the server refuses a call carrying any of these with
930
+ * E-SCOPE-KEY-REMOVED (src/services/knowledge/kb-removed-scope-keys.ts). The
931
+ * kb_* wrappers below refuse them client-side with the same code, so a stale
932
+ * caller fails fast and identically whichever side catches it.
933
+ */
934
+ export const KB_REMOVED_SCOPE_KEYS = Object.freeze(['repo_path', 'repo', 'repo_remote_url']);
935
+
936
+ /**
937
+ * Throw E-SCOPE-KEY-REMOVED when `options` carries a removed kb_* scope key
938
+ * (any value other than undefined).
939
+ * @param {string} tool - the kb_* tool name, for the message
940
+ * @param {Record<string, unknown>} [options]
941
+ */
942
+ export function assertNoRemovedKbScopeKeys(tool, options) {
943
+ if (!options || typeof options !== 'object') return;
944
+ const present = KB_REMOVED_SCOPE_KEYS.filter((k) => options[k] !== undefined);
945
+ if (present.length === 0) return;
946
+ const err = new Error(
947
+ `E-SCOPE-KEY-REMOVED: ${tool} no longer accepts ${present.map((k) => `'${k}'`).join(', ')} ` +
948
+ '(removed in the KB redesign); the call was not sent. Remediation: drop it -- every kb_* call acts on the ' +
949
+ "calling session's own KB (a member session's registered work folder; a FULL session's first MCP client root inside a git repository with an origin remote, or the fleet server working folder when the client offers no roots).",
950
+ );
951
+ err.code = 'E-SCOPE-KEY-REMOVED';
952
+ throw err;
953
+ }
954
+
580
955
  /**
581
956
  * Typed read of an execute_prompt permission denial. Accepts the raw executePrompt()
582
957
  * result or its `structuredContent`; returns the {@link PermissionDenied} block when
@@ -594,13 +969,106 @@ export function permissionDenialOf(result) {
594
969
  if (!Array.isArray(d.denials) || !d.denials.every((x) => x && typeof x.action === 'string' && (x.target === undefined || typeof x.target === 'string'))) return null;
595
970
  return {
596
971
  actions: [...d.actions],
597
- denials: d.denials.map((x) => (x.target === undefined ? { action: x.action } : { action: x.action, target: x.target })),
972
+ denials: d.denials.map((x) => ({
973
+ action: x.action,
974
+ ...(x.target === undefined ? {} : { target: x.target }),
975
+ ...(isStringArray(x.suggestedGrants) ? { suggestedGrants: [...x.suggestedGrants] } : {}),
976
+ })),
598
977
  suggestedGrants: [...d.suggestedGrants],
599
978
  hint: d.hint,
600
979
  signals: isStringArray(d.signals) ? [...d.signals] : [],
980
+ ...(typeof d.permissionMode === 'string' ? { permissionMode: d.permissionMode } : {}),
981
+ ...(typeof d.healable === 'boolean' ? { healable: d.healable } : {}),
982
+ ...(d.cause === 'policy_deny' ? { cause: 'policy_deny' } : {}),
601
983
  };
602
984
  }
603
985
 
986
+ /**
987
+ * Anchored text shapes of a fleet tool failure that reached the caller WITHOUT
988
+ * a structured error flag (an older server, or a plain-string tool result).
989
+ * Each pattern matches only at the START of the result text, so a genuine
990
+ * LLM reply that merely mentions "connection refused" mid-body never matches
991
+ * (a successful execute_prompt reply is display-wrapped or carried in
992
+ * structuredContent.response, never bare).
993
+ */
994
+ const FLEET_TOOL_FAILURE_TEXT_RES = Object.freeze([
995
+ /^\s*(?:\[FAIL\]\s*)?Failed to execute (?:command|prompt) on "/,
996
+ /^\s*\(SSH\)\s/,
997
+ /^\s*(?:Error:\s*)?(?:connect\s+)?(?:ECONNREFUSED|ECONNRESET|EHOSTUNREACH|ENETUNREACH|ETIMEDOUT|EPIPE)\b/,
998
+ /^\s*(?:Error:\s*)?(?:Timed out while waiting for handshake|Connection lost before handshake|All configured authentication methods failed|Not connected)\b/,
999
+ ]);
1000
+
1001
+ /**
1002
+ * Typed read of a fleet TOOL/TRANSPORT failure on a raw callTool() result --
1003
+ * as opposed to a successful tool call whose payload is the member's (or the
1004
+ * LLM's) answer. Returns null for a successful result.
1005
+ *
1006
+ * Signals, strongest first:
1007
+ * - 'isError': the MCP-level `result.isError === true` flag. This is what the
1008
+ * MCP server returns when a tool handler THROWS (e.g. an SSH channel that
1009
+ * could not be opened): `{ content: [{ text: err.message }], isError: true }`
1010
+ * with no structuredContent, so the text is the bare transport error.
1011
+ * - 'text': fallback for a result carrying no structured flag and no
1012
+ * `structuredContent.response`, whose text starts with a recognisable
1013
+ * fleet failure shape (FLEET_TOOL_FAILURE_TEXT_RES).
1014
+ *
1015
+ * A result whose `structuredContent.isError` is set is NOT reported here:
1016
+ * that is the tool's own classified failure (it carries a `reason`), which
1017
+ * callers already read directly.
1018
+ *
1019
+ * @param {{ isError?: boolean, content?: { text?: string }[], structuredContent?: Record<string, any> } | null | undefined} result
1020
+ * @returns {{ source: 'isError' | 'text', text: string } | null}
1021
+ */
1022
+ export function fleetToolFailureOf(result) {
1023
+ if (!result || typeof result !== 'object') return null;
1024
+ const sc = result.structuredContent;
1025
+ if (sc && sc.isError) return null;
1026
+ const text = Array.isArray(result.content)
1027
+ ? result.content.map((c) => (c && typeof c.text === 'string' ? c.text : '')).filter(Boolean).join('\n')
1028
+ : '';
1029
+ if (result.isError === true) return { source: 'isError', text };
1030
+ if (sc && typeof sc.response === 'string') return null;
1031
+ if (FLEET_TOOL_FAILURE_TEXT_RES.some((re) => re.test(text))) return { source: 'text', text };
1032
+ return null;
1033
+ }
1034
+
1035
+ // Older servers (before execute_command carried isError on its failure
1036
+ // paths) returned a bare text with no structuredContent for a command that
1037
+ // never ran. These are that text's two shapes.
1038
+ const UNFLAGGED_COMMAND_FAILURE_RE = /^Failed to (execute command|launch task) on "/;
1039
+
1040
+ /**
1041
+ * Typed read of an execute_command failure that never produced an exit code.
1042
+ * Accepts the raw executeCommand() result. Returns `{ reason, message }` when the
1043
+ * result is an isError failure (structuredContent.isError, or the MCP-level
1044
+ * isError flag), or when an older server sent the bare "Failed to execute
1045
+ * command on ..." / "Failed to launch task on ..." text with no
1046
+ * structuredContent. Returns null for a command that ran (any exit code --
1047
+ * callers check a non-zero exitCode separately).
1048
+ *
1049
+ * @param {{content?: {text?: string}[], structuredContent?: ExecuteCommandStructured, isError?: boolean} | null | undefined} result
1050
+ * @returns {ExecuteCommandFailure | null}
1051
+ */
1052
+ export function commandFailureOf(result) {
1053
+ if (!result || typeof result !== 'object') return null;
1054
+ const text = Array.isArray(result.content) && result.content.length > 0 && typeof result.content[0]?.text === 'string'
1055
+ ? result.content[0].text
1056
+ : '';
1057
+ const sc = result.structuredContent;
1058
+ if (sc && typeof sc === 'object' && sc.isError) {
1059
+ const reason = typeof sc.reason === 'string' && sc.reason ? sc.reason : 'unknown';
1060
+ const detail = typeof sc.stderr === 'string' ? sc.stderr : '';
1061
+ return { reason, message: text || detail || `execute_command failed (${reason})` };
1062
+ }
1063
+ if (result.isError) {
1064
+ return { reason: 'unknown', message: text || 'execute_command failed' };
1065
+ }
1066
+ if (!sc && UNFLAGGED_COMMAND_FAILURE_RE.test(text)) {
1067
+ return { reason: 'unflagged_failure', message: text };
1068
+ }
1069
+ return null;
1070
+ }
1071
+
604
1072
  export class ApraFleet {
605
1073
  /**
606
1074
  * @param {{ callTool: (name: string, args: Record<string, any>, opts?: { timeoutMs?: number, signal?: AbortSignal }) => Promise<any> }} mcpClient
@@ -610,7 +1078,9 @@ export class ApraFleet {
610
1078
  }
611
1079
 
612
1080
  /**
613
- * Run an AI prompt on a member.
1081
+ * Run an AI prompt on a member. A claude member's session gets the
1082
+ * member-scoped `apra-fleet` server per session (`--mcp-config`); see
1083
+ * docs/api-reference.md.
614
1084
  * @param {ExecutePromptOptions} options
615
1085
  * @returns {Promise<{content?: {type: string, text: string}[], structuredContent?: ExecutePromptStructured}>}
616
1086
  * the raw callTool() result -- see the {@link ExecutePromptStructured} typedef above
@@ -627,6 +1097,9 @@ export class ApraFleet {
627
1097
  /**
628
1098
  * Run a shell command on a member.
629
1099
  * @param {ExecuteCommandOptions} options
1100
+ * @returns {Promise<{content?: {type: string, text: string}[], structuredContent?: ExecuteCommandStructured}>}
1101
+ * the raw callTool() result. A command that never produced an exit code carries
1102
+ * `structuredContent.isError` and `reason` -- read it with {@link commandFailureOf}.
630
1103
  */
631
1104
  async executeCommand(options) {
632
1105
  const { timeoutMs, signal, ...payload } = options;
@@ -645,16 +1118,29 @@ export class ApraFleet {
645
1118
  }
646
1119
 
647
1120
  /**
648
- * Get status of all fleet members.
1121
+ * Get status of all fleet members. With format "json" the result's
1122
+ * kbHealth.credential is a {@link FleetStatusKbCredential} when the KB
1123
+ * config selects the http provider, and kbHealth.toolProfileWarning is a
1124
+ * string when the configured KB tool profile is invalid.
649
1125
  * @param {FleetStatusOptions} [options]
650
1126
  */
651
1127
  async fleetStatus(options = {}) {
652
1128
  return this.mcpClient.callTool('fleet_status', options);
653
1129
  }
654
1130
 
1131
+ /**
1132
+ * Cheap read-only fleet view for status displays (the Claude Code
1133
+ * fleet-status mod polls it). The result text is the JSON of a
1134
+ * {@link FleetSnapshot}: every member's last-known status from local
1135
+ * state only -- no SSH probes, no writes. Use fleetStatus for a live check.
1136
+ */
1137
+ async fleetSnapshot() {
1138
+ return this.mcpClient.callTool('fleet_snapshot', {});
1139
+ }
1140
+
655
1141
  /**
656
1142
  * Get detailed status for one member: connectivity, session, work folder, provider, registered shell (Windows).
657
- * @param {{ member_id?: string, member_name?: string, format?: 'compact'|'json' }} options
1143
+ * @param {{ member_id?: string, member_name?: string, format?: 'compact'|'json', refresh?: boolean }} options
658
1144
  * @returns {Promise<string|MemberDetailResult>} A compact text summary when format is
659
1145
  * "compact" (default), or the structured MemberDetailResult object when format is "json".
660
1146
  */
@@ -665,6 +1151,7 @@ export class ApraFleet {
665
1151
  /**
666
1152
  * Get a member's cheap/standard/premium tier resolved to a concrete
667
1153
  * model and its real per-1M-token price (apra-fleet-dv5.5/dv5.6).
1154
+ * The tool result text is the JSON of a {@link MemberModelPricingResult}.
668
1155
  * @param {{ member_id?: string, member_name?: string }} options
669
1156
  */
670
1157
  async getMemberModelPricing(options) {
@@ -696,7 +1183,10 @@ export class ApraFleet {
696
1183
  }
697
1184
 
698
1185
  /**
699
- * Change a member's settings.
1186
+ * Change a member's settings. Changing `llm_provider` or `work_folder`
1187
+ * removes the composed permission/MCP config written for the old
1188
+ * provider/folder and re-composes for the member as updated (see
1189
+ * docs/api-reference.md).
700
1190
  * @param {UpdateMemberOptions} options
701
1191
  */
702
1192
  async updateMember(options) {
@@ -704,7 +1194,12 @@ export class ApraFleet {
704
1194
  }
705
1195
 
706
1196
  /**
707
- * Remove a member from the fleet.
1197
+ * Remove a member from the fleet. Member-side composed config (the
1198
+ * per-folder `apra-fleet` MCP entry, permission keys) is removed first;
1199
+ * what could not be removed is reported as a warning. The member-side registration on the
1200
+ * member's own apra-fleet install is removed only when that install carries the
1201
+ * member-install marker; otherwise (unmarked, or the marker probe failed) it is
1202
+ * skipped and the output says so and why.
708
1203
  * @param {RemoveMemberOptions} options
709
1204
  */
710
1205
  async removeMember(options) {
@@ -775,6 +1270,13 @@ export class ApraFleet {
775
1270
  * command, and redacts the value from the returned stdout/stderr. The
776
1271
  * plaintext appears in no field of the result.
777
1272
  *
1273
+ * Bitbucket REST takes the token as a Bearer value (no username, no
1274
+ * email). The optional {{vcs_username}} / {{vcs_username_inline}} pair
1275
+ * substitutes the credential helper's git username (for Bitbucket always
1276
+ * x-bitbucket-api-token-auth) under the same two dialects, and is
1277
+ * redacted on the same footing as the token. A username placeholder
1278
+ * never stands alone -- the command must still carry a token one.
1279
+ *
778
1280
  * @param {VcsCredentialExecOptions} options
779
1281
  * @returns {Promise<{ content: Array<{type: string, text: string}>,
780
1282
  * structuredContent: VcsCredentialExecStructured }>}
@@ -784,13 +1286,97 @@ export class ApraFleet {
784
1286
  }
785
1287
 
786
1288
  /**
787
- * Compose and deliver a scoped permission profile to a member.
1289
+ * Compose and deliver a scoped permission profile to a member. Also writes
1290
+ * the member's per-folder `apra-fleet` MCP entry (`?member=<uuid>`) through
1291
+ * the member provider's own per-project config (not for a local claude
1292
+ * member, whose dispatches get it per session: an entry an older compose
1293
+ * wrote for it is removed instead), with deny rules for every
1294
+ * fleet tool outside the member allowlist (claude, agy), merged by union
1295
+ * with any existing deny rules. The result states why a member config was
1296
+ * not edited (tracked by git, not strict JSON, unreadable) and when a stale
1297
+ * fleetMcp unavailable status was cleared; see docs/api-reference.md.
788
1298
  * @param {ComposePermissionsOptions} options
789
1299
  */
790
1300
  async composePermissions(options) {
791
1301
  return this.mcpClient.callTool('compose_permissions', options);
792
1302
  }
793
1303
 
1304
+ /**
1305
+ * Export the calling session's CONFIRMED KB entries to the canonical bible
1306
+ * file and auto-commit it locally (never pushed). Pass baseBranch/baseCommit
1307
+ * to record the target base branch and base commit in provenance. Writes
1308
+ * bible format v3: each added project entry is a KbBibleEntry carrying its
1309
+ * source_file_hashes basis; a bible holding a duplicate id is refused.
1310
+ * Result JSON: {exported, path, scope, committed}; extract with parseToolJson().
1311
+ * The removed scope keys (repo_path, repo, repo_remote_url) are refused
1312
+ * with E-SCOPE-KEY-REMOVED before anything is sent.
1313
+ * @param {KbExportOptions} [options]
1314
+ */
1315
+ async kbExport(options = {}) {
1316
+ assertNoRemovedKbScopeKeys('kb_export', options);
1317
+ return this.mcpClient.callTool('kb_export', options);
1318
+ }
1319
+
1320
+ /**
1321
+ * Merge exactly the given confirmed entry ids into the bible at entry level
1322
+ * (existing entries kept unless this KB holds them as superseded or
1323
+ * invalidated -- those are removed, also when ids is empty; each merged
1324
+ * entry is a v3 KbBibleEntry carrying its source_file_hashes basis; a bible
1325
+ * holding a duplicate id is refused), write baseBranch/baseCommit
1326
+ * provenance, and make a local commit scoped to the bible path whose message
1327
+ * lists each removal. Never pushes; re-running with the
1328
+ * same ids after resetting to a newer HEAD re-merges, so a rejected push can
1329
+ * be retried. Result JSON: {path, merged, demoted, skipped, removed,
1330
+ * entry_count, backfilled, committed}; extract with parseToolJson(). backfilled counts the
1331
+ * existing bible entries with no source_file_hashes (carried over from a
1332
+ * v1/v2 bible) that gained this KB's stored basis for the same id, because
1333
+ * it passes the same basis rule at HEAD and cites the same files (legacy
1334
+ * backfill; only that field changes, nothing is dropped); a backfill alone
1335
+ * makes a commit. Each skipped item is
1336
+ * {id, reason} with reason not_confirmed_or_unknown, no_source_files (a
1337
+ * CONFIRMED id citing no source file), basis_mismatch or
1338
+ * not_demoted_or_unknown (a demoted_ids id). Each removed item is {id, reason}
1339
+ * with reason superseded or invalidated. A member session without the
1340
+ * kb_maintainer grant cannot retire a CONFIRMED entry through the kb_* tools:
1341
+ * kb_invalidate leaves CONFIRMED entries untouched, and kb_capture with
1342
+ * supersedes links to a CONFIRMED target (refines, both live) instead of
1343
+ * retiring it; both list such ids in their response's refused list. The
1344
+ * kb_maintainer session and FULL sessions are not limited, and the grant is
1345
+ * a routing guard for agent sessions, not a boundary against a local process
1346
+ * that can open a FULL session or write the KB directly.
1347
+ * A CONFIRMED id is admitted only if it passes the same basis rule as kb_export.
1348
+ * demoted_ids records EXPLICIT demotion tombstones: an admitted id is removed from
1349
+ * entries and tombstoned as {id, at, reason}; entry_count counts entries only.
1350
+ * The removed scope keys (repo_path, repo, repo_remote_url) are refused
1351
+ * with E-SCOPE-KEY-REMOVED before anything is sent.
1352
+ * Under an http KB provider the call is skipped, never an error: the result
1353
+ * is {path, merged: [], skipped: [], removed: [], entry_count: <entries in the
1354
+ * existing parseable bible, else 0>, backfilled: 0, committed: false,
1355
+ * bible_skipped: true, reason}; the KB is not read and nothing is written or
1356
+ * committed.
1357
+ * @param {KbBibleCommitOptions} options
1358
+ */
1359
+ async kbBibleCommit(options) {
1360
+ assertNoRemovedKbScopeKeys('kb_bible_commit', options);
1361
+ return this.mcpClient.callTool('kb_bible_commit', options);
1362
+ }
1363
+
1364
+ /**
1365
+ * Withdraw trust from a CONFIRMED entry, lowering it to INFERRED (the
1366
+ * inverse of kb_promote). Not a ladder: an INFERRED/UNVERIFIED target is
1367
+ * REFUSED with E-DEMOTE-NOT-CONFIRMED rather than returned as a no-op.
1368
+ * Appends the reason and the required evidence files as an audit note; promoted_at
1369
+ * and source are left untouched. Result JSON:
1370
+ * {id, previous_confidence, new_confidence}; extract with parseToolJson().
1371
+ * The removed scope keys (repo_path, repo, repo_remote_url) are refused
1372
+ * with E-SCOPE-KEY-REMOVED before anything is sent.
1373
+ * @param {KbDemoteOptions} options
1374
+ */
1375
+ async kbDemote(options) {
1376
+ assertNoRemovedKbScopeKeys('kb_demote', options);
1377
+ return this.mcpClient.callTool('kb_demote', options);
1378
+ }
1379
+
794
1380
  /**
795
1381
  * Convert a remote member from password to SSH key authentication.
796
1382
  * @param {SetupSshKeyOptions} options
@@ -799,6 +1385,29 @@ export class ApraFleet {
799
1385
  return this.mcpClient.callTool('setup_ssh_key', options);
800
1386
  }
801
1387
 
1388
+ /**
1389
+ * Send a message to a connected member session. member_id is a member
1390
+ * UUID, or "orchestrator" for the operator's own channel-capable
1391
+ * orchestrating session (operator notifications). With probe: true the
1392
+ * server sends nothing and only reports whether a session holds the
1393
+ * target ({ probe: true, member_id, connected, channel_capable }).
1394
+ * @param {{ member_id: string, content: string, reply_to?: string, probe?: boolean }} options
1395
+ */
1396
+ async sendMessage(options) {
1397
+ return this.mcpClient.callTool('send_message', options);
1398
+ }
1399
+
1400
+ /**
1401
+ * Read-only check of a message target: send_message with probe: true.
1402
+ * Sends nothing. The result text is JSON
1403
+ * { probe: true, member_id, connected, channel_capable }; only a
1404
+ * channel_capable session can receive a message.
1405
+ * @param {string} memberId a member UUID or "orchestrator"
1406
+ */
1407
+ async probeMessageTarget(memberId) {
1408
+ return this.mcpClient.callTool('send_message', { member_id: memberId, content: '', probe: true });
1409
+ }
1410
+
802
1411
  /**
803
1412
  * Send an email. Pass provider config inline (provider, from, and for
804
1413
  * SMTP: host, port, user, secure). Secrets resolve from the credential
@@ -820,6 +1429,78 @@ export class ApraFleet {
820
1429
  return this.mcpClient.callTool('credential_store_set', options);
821
1430
  }
822
1431
 
1432
+ /**
1433
+ * code_reindex -- rebuild the code index of the calling session's own repo
1434
+ * (a member session's work folder, otherwise
1435
+ * the first MCP client root (roots/list) inside a git repository with an origin remote, or the server working folder when the client offers no roots;
1436
+ * there is no repo argument). Starts gitnexus analyze detached, always as
1437
+ * a full rebuild (--force; an incremental analyze can corrupt unchanged
1438
+ * symbol rows), with its
1439
+ * output captured to <data>/code-index/<slug>/analyze.log and returns
1440
+ * after the first tick. Extract the JSON with parseToolJson(): `outcome`
1441
+ * is 'started' | 'up-to-date' | 'starting' | 'already-running' |
1442
+ * 'not-started'; a not-started result carries a typed `reason`
1443
+ * ('npx-not-found' | 'gitnexus-not-found' | 'analyze-failed' |
1444
+ * 'spawn-failed' | 'remote-member' | 'gitnexus-too-old' |
1445
+ * 'provider-not-supported'); 'gitnexus-too-old' means the installed
1446
+ * gitnexus rejects --index-only and its `detail` names the upgrade fix.
1447
+ * Every result also carries `injectedBlockFiles` (repo-relative agent docs
1448
+ * still holding a gitnexus block injected by an earlier plain analyze run;
1449
+ * detection only, the work tree is never edited). Only the
1450
+ * gitnexus provider is supported: provider 'none' makes the tool fail with
1451
+ * E-CODE-INTEL-DISABLED, and any other provider (e.g. codebase-memory)
1452
+ * yields { outcome: 'not-started', reason: 'provider-not-supported',
1453
+ * provider, indexedCommit: null, detail }. Every result carries
1454
+ * `indexedCommit` (the commit the index is built at, or null when there
1455
+ * is no index or the folder is remote). Poll codeStatus() for completion.
1456
+ */
1457
+ async codeReindex() {
1458
+ return this.mcpClient.callTool('code_reindex', {});
1459
+ }
1460
+
1461
+ /**
1462
+ * code_status -- the calling session's own code index state: the last
1463
+ * analyze run (`analyze`: phase, result 'indexed' | 'up-to-date' |
1464
+ * 'incomplete' | 'failed', lastLine, ...), live `readiness`
1465
+ * ('ready' | 'building' | 'interrupted' | 'inconsistent' | 'missing';
1466
+ * 'building' also covers an analyze rewriting an existing index, which is
1467
+ * never served meanwhile; 'interrupted' = an analyze died mid-write and
1468
+ * none is running; 'inconsistent' = the gitnexus registry or the fleet
1469
+ * record of its last build names a different commit than meta.json, with
1470
+ * the reason in `inconsistency` (null otherwise) -- for both, the next
1471
+ * code_* call starts a rebuild), `indexedCommit`, `lockHeld`, and `logPath` (null
1472
+ * when no analyze log exists yet), and `autoReindexPaused` (null, or the
1473
+ * { result, lastLine, logPath, finished } of a failed automatic run --
1474
+ * automatic rebuilds stay paused until codeReindex() or a server
1475
+ * restart), `injectedBlockFiles` / `injectedBlockWarning` (agent docs still
1476
+ * holding a previously injected gitnexus block, and the one-line WARN with
1477
+ * the fix; [] / null when clean), and on a failed run
1478
+ * `analyze.failureCause` ('gitnexus-too-old' when gitnexus rejected
1479
+ * --index-only). A remote work folder returns { remote: true, repo,
1480
+ * indexedCommit: null, detail }. Same provider gate as codeReindex():
1481
+ * provider 'none' fails with E-CODE-INTEL-DISABLED; a non-gitnexus
1482
+ * provider returns the not-supported shape { outcome: 'not-started',
1483
+ * reason: 'provider-not-supported', provider, indexedCommit: null,
1484
+ * detail } rather than gitnexus readiness. Extract the JSON with
1485
+ * parseToolJson().
1486
+ */
1487
+ async codeStatus() {
1488
+ return this.mcpClient.callTool('code_status', {});
1489
+ }
1490
+
1491
+ /**
1492
+ * session_stats -- a member's kb_* / code_* tool call counts on this
1493
+ * server, aggregated across that member's sessions (engine-origin
1494
+ * sessions excluded). On a member session the calling member is reported
1495
+ * and `member_id` may be omitted; a non-member session must pass it.
1496
+ * Extract the JSON with parseToolJson(): a SessionStatsResult.
1497
+ *
1498
+ * @param {SessionStatsOptions} [options]
1499
+ */
1500
+ async sessionStats(options = {}) {
1501
+ return this.mcpClient.callTool('session_stats', options);
1502
+ }
1503
+
823
1504
  /**
824
1505
  * List stored credentials (names and metadata only -- no values).
825
1506
  * The result payload is a JSON array of { name, scope, ... } entries;
@@ -871,6 +1552,9 @@ export class ApraFleet {
871
1552
  * src/tools/child-id-allocator.ts). Mints globally-distinct child ids under
872
1553
  * a shared parent for sprints launched WITHOUT a supervisor, so two sprints
873
1554
  * creating children under the same parent never derive the same id.
1555
+ * `floor` (allocate) is the parent's highest existing child seq: the
1556
+ * counter is never below it and released ids at or below it are dropped
1557
+ * from the reuse pool on every allocate.
874
1558
  *
875
1559
  * @param {{ action: 'allocate'|'confirm'|'release'|'status',
876
1560
  * parent_id?: string, token?: string, sprint_id?: string,