@apralabs/apra-fleet 0.4.4 → 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 (268) hide show
  1. package/README.md +49 -4
  2. package/dist/agents/backlog-groomer.md +5 -0
  3. package/dist/agents/ci-watcher.md +5 -0
  4. package/dist/agents/deployer.md +20 -2
  5. package/dist/agents/doer.md +38 -2
  6. package/dist/agents/harvester.md +12 -9
  7. package/dist/agents/integ-test-runner.md +5 -0
  8. package/dist/agents/kb-reconciler.md +6 -0
  9. package/dist/agents/plan-reviewer.md +5 -0
  10. package/dist/agents/planner.md +5 -0
  11. package/dist/agents/regression-test-runner.md +5 -0
  12. package/dist/agents/reviewer.md +67 -15
  13. package/dist/agents/schemas/deployer-output.json +5 -0
  14. package/dist/agents/schemas/doer-output.json +78 -2
  15. package/dist/agents/schemas/reviewer-output.json +104 -2
  16. package/dist/cli/auth.js +5 -1
  17. package/dist/cli/beads-pin.js +6 -7
  18. package/dist/cli/claude-mod.d.ts +75 -0
  19. package/dist/cli/claude-mod.js +288 -0
  20. package/dist/cli/dolt-install.d.ts +1 -1
  21. package/dist/cli/dolt-install.js +5 -1
  22. package/dist/cli/fleet-se-guard.d.ts +8 -0
  23. package/dist/cli/fleet-se-guard.js +19 -3
  24. package/dist/cli/install-guard.d.ts +9 -0
  25. package/dist/cli/install-guard.js +24 -0
  26. package/dist/cli/install.d.ts +12 -0
  27. package/dist/cli/install.js +180 -20
  28. package/dist/cli/kb-profile.d.ts +16 -0
  29. package/dist/cli/kb-profile.js +81 -0
  30. package/dist/cli/start.js +3 -0
  31. package/dist/cli/uninstall.js +13 -3
  32. package/dist/cli/update.d.ts +4 -0
  33. package/dist/cli/update.js +19 -3
  34. package/dist/commands/kb-server.d.ts +10 -1
  35. package/dist/commands/kb-server.js +285 -11
  36. package/dist/index.js +22 -1
  37. package/dist/os/git-executable.d.ts +57 -0
  38. package/dist/os/git-executable.js +85 -0
  39. package/dist/os/go-concurrency.d.ts +44 -0
  40. package/dist/os/go-concurrency.js +53 -0
  41. package/dist/os/index.d.ts +1 -0
  42. package/dist/os/index.js +1 -0
  43. package/dist/os/linux.d.ts +2 -0
  44. package/dist/os/linux.js +10 -1
  45. package/dist/os/os-commands.d.ts +25 -0
  46. package/dist/os/os-commands.js +2 -0
  47. package/dist/os/windows-executable.d.ts +53 -0
  48. package/dist/os/windows-executable.js +185 -0
  49. package/dist/os/windows-gitbash.d.ts +23 -14
  50. package/dist/os/windows-gitbash.js +40 -16
  51. package/dist/os/windows.d.ts +2 -0
  52. package/dist/os/windows.js +37 -6
  53. package/dist/paths.d.ts +10 -1
  54. package/dist/paths.js +19 -2
  55. package/dist/services/agy-project.d.ts +7 -1
  56. package/dist/services/agy-project.js +7 -2
  57. package/dist/services/auth-socket.d.ts +18 -0
  58. package/dist/services/auth-socket.js +30 -4
  59. package/dist/services/credential-store.d.ts +33 -0
  60. package/dist/services/credential-store.js +79 -2
  61. package/dist/services/http-transport.d.ts +29 -0
  62. package/dist/services/http-transport.js +166 -37
  63. package/dist/services/kb-tool-profile.d.ts +36 -0
  64. package/dist/services/kb-tool-profile.js +88 -0
  65. package/dist/services/knowledge/bible-blob-id.js +10 -1
  66. package/dist/services/knowledge/bible-import.d.ts +108 -0
  67. package/dist/services/knowledge/bible-import.js +137 -4
  68. package/dist/services/knowledge/file-hash.js +6 -5
  69. package/dist/services/knowledge/http-provider.d.ts +303 -20
  70. package/dist/services/knowledge/http-provider.js +795 -125
  71. package/dist/services/knowledge/kb-config.d.ts +65 -1
  72. package/dist/services/knowledge/kb-config.js +143 -3
  73. package/dist/services/knowledge/kb-http-auth-state.d.ts +26 -0
  74. package/dist/services/knowledge/kb-http-auth-state.js +40 -0
  75. package/dist/services/knowledge/kb-providers.d.ts +9 -2
  76. package/dist/services/knowledge/kb-providers.js +67 -37
  77. package/dist/services/knowledge/kb-removed-scope-keys.js +1 -1
  78. package/dist/services/knowledge/kb-self.d.ts +122 -9
  79. package/dist/services/knowledge/kb-self.js +196 -36
  80. package/dist/services/knowledge/member-bible-view.js +16 -3
  81. package/dist/services/knowledge/path-validation.d.ts +7 -0
  82. package/dist/services/knowledge/path-validation.js +11 -0
  83. package/dist/services/knowledge/project-slug.js +3 -2
  84. package/dist/services/knowledge/repository-header.d.ts +77 -0
  85. package/dist/services/knowledge/repository-header.js +233 -0
  86. package/dist/services/knowledge/require-sqlite-project.d.ts +1 -1
  87. package/dist/services/knowledge/require-sqlite-project.js +1 -1
  88. package/dist/services/knowledge/sqlite-provider.d.ts +169 -0
  89. package/dist/services/knowledge/sqlite-provider.js +416 -4
  90. package/dist/services/knowledge/types.d.ts +15 -2
  91. package/dist/services/member-busy.d.ts +12 -0
  92. package/dist/services/member-busy.js +20 -0
  93. package/dist/services/member-config-io.d.ts +3 -2
  94. package/dist/services/member-config-io.js +7 -4
  95. package/dist/services/member-fleet-install.js +1 -0
  96. package/dist/services/member-tool-allowlist.d.ts +1 -1
  97. package/dist/services/member-tool-allowlist.js +8 -4
  98. package/dist/services/port-holder.js +2 -1
  99. package/dist/services/service-manager/types.d.ts +17 -1
  100. package/dist/services/service-manager/windows.d.ts +7 -2
  101. package/dist/services/service-manager/windows.js +28 -11
  102. package/dist/services/service-notice.d.ts +7 -0
  103. package/dist/services/service-notice.js +19 -0
  104. package/dist/services/session-registry.d.ts +13 -0
  105. package/dist/services/session-registry.js +13 -0
  106. package/dist/services/session-roots.d.ts +67 -0
  107. package/dist/services/session-roots.js +126 -0
  108. package/dist/services/statusline.d.ts +21 -0
  109. package/dist/services/statusline.js +97 -1
  110. package/dist/services/supervisor-service-cleanup.js +2 -1
  111. package/dist/services/tool-registry.js +108 -20
  112. package/dist/services/tool-scope.d.ts +34 -1
  113. package/dist/services/tool-scope.js +27 -2
  114. package/dist/services/vcs/azure-devops.js +10 -0
  115. package/dist/services/vcs/bitbucket.d.ts +22 -1
  116. package/dist/services/vcs/bitbucket.js +163 -17
  117. package/dist/services/vcs/types.d.ts +25 -2
  118. package/dist/services/watch/project-resolver.js +2 -1
  119. package/dist/skills/pm/cost.md +5 -1
  120. package/dist/skills/pm/index.md +9 -9
  121. package/dist/skills/pm/sprint.md +2 -1
  122. package/dist/tools/check-status.d.ts +51 -0
  123. package/dist/tools/check-status.js +124 -12
  124. package/dist/tools/code-intelligence-freshness.js +1 -1
  125. package/dist/tools/code-intelligence-gitnexus.d.ts +19 -0
  126. package/dist/tools/code-intelligence-gitnexus.js +166 -9
  127. package/dist/tools/code-intelligence-readiness.d.ts +58 -1
  128. package/dist/tools/code-intelligence-readiness.js +93 -8
  129. package/dist/tools/code-intelligence-reindex.d.ts +25 -1
  130. package/dist/tools/code-intelligence-reindex.js +76 -4
  131. package/dist/tools/code-intelligence.d.ts +1 -1
  132. package/dist/tools/code-intelligence.js +1 -1
  133. package/dist/tools/execute-command.js +14 -8
  134. package/dist/tools/execute-prompt.js +6 -2
  135. package/dist/tools/fleet-snapshot.d.ts +21 -0
  136. package/dist/tools/fleet-snapshot.js +78 -0
  137. package/dist/tools/kb-bible-commit.d.ts +25 -11
  138. package/dist/tools/kb-bible-commit.js +142 -33
  139. package/dist/tools/kb-capture.d.ts +2 -2
  140. package/dist/tools/kb-context.js +47 -27
  141. package/dist/tools/kb-demote.d.ts +27 -0
  142. package/dist/tools/kb-demote.js +37 -0
  143. package/dist/tools/kb-export.d.ts +35 -3
  144. package/dist/tools/kb-export.js +56 -13
  145. package/dist/tools/kb-feedback.d.ts +2 -0
  146. package/dist/tools/kb-feedback.js +17 -7
  147. package/dist/tools/kb-harvest.js +28 -9
  148. package/dist/tools/kb-import.d.ts +18 -2
  149. package/dist/tools/kb-import.js +24 -9
  150. package/dist/tools/kb-invalidate.d.ts +11 -3
  151. package/dist/tools/kb-invalidate.js +80 -7
  152. package/dist/tools/kb-list.js +38 -10
  153. package/dist/tools/kb-promote.js +6 -4
  154. package/dist/tools/kb-query.d.ts +3 -0
  155. package/dist/tools/kb-query.js +181 -37
  156. package/dist/tools/kb-session-prime.d.ts +4 -4
  157. package/dist/tools/kb-session-prime.js +89 -9
  158. package/dist/tools/kb-setup.d.ts +20 -0
  159. package/dist/tools/kb-setup.js +149 -11
  160. package/dist/tools/list-members.js +1 -1
  161. package/dist/tools/member-detail.js +7 -3
  162. package/dist/tools/provision-vcs-auth.d.ts +28 -3
  163. package/dist/tools/provision-vcs-auth.js +53 -7
  164. package/dist/tools/receive-files.js +7 -4
  165. package/dist/tools/send-files.js +5 -4
  166. package/dist/tools/send-message.d.ts +3 -0
  167. package/dist/tools/send-message.js +15 -2
  168. package/dist/tools/stop-prompt.js +3 -1
  169. package/dist/tools/vcs-credential-exec.d.ts +45 -3
  170. package/dist/tools/vcs-credential-exec.js +90 -11
  171. package/dist/utils/process-utils.js +5 -1
  172. package/dist/utils/redact-known-secrets.d.ts +17 -0
  173. package/dist/utils/redact-known-secrets.js +70 -0
  174. package/dist/utils/skill-matrix.js +1 -1
  175. package/dist/utils/vcs-provider-detect.js +2 -2
  176. package/dist/workflows/auto-sprint.js +245 -9
  177. package/package.json +10 -7
  178. package/packages/apra-fleet-client/package.json +1 -1
  179. package/packages/apra-fleet-client/src/client/api.mjs +172 -19
  180. package/packages/apra-fleet-client/src/client/reconnecting-transport.mjs +35 -2
  181. package/packages/apra-fleet-client/src/client/transport.mjs +6 -0
  182. package/packages/apra-fleet-se/apra-pm/agents/backlog-groomer.md +5 -0
  183. package/packages/apra-fleet-se/apra-pm/agents/ci-watcher.md +5 -0
  184. package/packages/apra-fleet-se/apra-pm/agents/deployer.md +20 -2
  185. package/packages/apra-fleet-se/apra-pm/agents/doer.md +38 -2
  186. package/packages/apra-fleet-se/apra-pm/agents/harvester.md +12 -9
  187. package/packages/apra-fleet-se/apra-pm/agents/integ-test-runner.md +5 -0
  188. package/packages/apra-fleet-se/apra-pm/agents/kb-reconciler.md +6 -0
  189. package/packages/apra-fleet-se/apra-pm/agents/plan-reviewer.md +5 -0
  190. package/packages/apra-fleet-se/apra-pm/agents/planner.md +5 -0
  191. package/packages/apra-fleet-se/apra-pm/agents/regression-test-runner.md +5 -0
  192. package/packages/apra-fleet-se/apra-pm/agents/reviewer.md +67 -15
  193. package/packages/apra-fleet-se/apra-pm/agents/schemas/deployer-output.json +5 -0
  194. package/packages/apra-fleet-se/apra-pm/agents/schemas/doer-output.json +78 -2
  195. package/packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json +104 -2
  196. package/packages/apra-fleet-se/apra-pm/skills/pm/cost.md +5 -1
  197. package/packages/apra-fleet-se/apra-pm/skills/pm/index.md +9 -9
  198. package/packages/apra-fleet-se/apra-pm/skills/pm/sprint.md +2 -1
  199. package/packages/apra-fleet-se/bin/cli.mjs +104 -31
  200. package/packages/apra-fleet-se/bin/serve.mjs +46 -8
  201. package/packages/apra-fleet-se/fleet-sprint/abort.mjs +184 -32
  202. package/packages/apra-fleet-se/fleet-sprint/bd-sync-command.mjs +69 -0
  203. package/packages/apra-fleet-se/fleet-sprint/beads-children.mjs +21 -0
  204. package/packages/apra-fleet-se/fleet-sprint/beads-lock-probe.mjs +176 -0
  205. package/packages/apra-fleet-se/fleet-sprint/beads-reachability.mjs +126 -0
  206. package/packages/apra-fleet-se/fleet-sprint/beads-scope.mjs +158 -1
  207. package/packages/apra-fleet-se/fleet-sprint/contracts.mjs +82 -2
  208. package/packages/apra-fleet-se/fleet-sprint/coordination.mjs +23 -6
  209. package/packages/apra-fleet-se/fleet-sprint/decision-notify.mjs +338 -0
  210. package/packages/apra-fleet-se/fleet-sprint/decision-wait.mjs +731 -0
  211. package/packages/apra-fleet-se/fleet-sprint/decisions.mjs +372 -0
  212. package/packages/apra-fleet-se/fleet-sprint/dispatch-role.mjs +44 -11
  213. package/packages/apra-fleet-se/fleet-sprint/docs/README.md +4 -1
  214. package/packages/apra-fleet-se/fleet-sprint/dolt-settle.mjs +9 -3
  215. package/packages/apra-fleet-se/fleet-sprint/dolt-sync.mjs +314 -19
  216. package/packages/apra-fleet-se/fleet-sprint/errors.mjs +72 -4
  217. package/packages/apra-fleet-se/fleet-sprint/git-sync.mjs +7 -1
  218. package/packages/apra-fleet-se/fleet-sprint/git-topology.mjs +112 -1
  219. package/packages/apra-fleet-se/fleet-sprint/guarded-modules.mjs +36 -2
  220. package/packages/apra-fleet-se/fleet-sprint/kb.mjs +736 -101
  221. package/packages/apra-fleet-se/fleet-sprint/member-init-probe.mjs +1 -1
  222. package/packages/apra-fleet-se/fleet-sprint/member-provisioning.mjs +7 -1
  223. package/packages/apra-fleet-se/fleet-sprint/phases/deploy.mjs +49 -2
  224. package/packages/apra-fleet-se/fleet-sprint/phases/develop.mjs +206 -3
  225. package/packages/apra-fleet-se/fleet-sprint/phases/final-review.mjs +61 -3
  226. package/packages/apra-fleet-se/fleet-sprint/phases/harvest.mjs +81 -31
  227. package/packages/apra-fleet-se/fleet-sprint/phases/plan.mjs +7 -3
  228. package/packages/apra-fleet-se/fleet-sprint/phases/publish-pr.mjs +39 -14
  229. package/packages/apra-fleet-se/fleet-sprint/phases/re-review.mjs +17 -1
  230. package/packages/apra-fleet-se/fleet-sprint/phases/review.mjs +18 -3
  231. package/packages/apra-fleet-se/fleet-sprint/pr-body.mjs +14 -1
  232. package/packages/apra-fleet-se/fleet-sprint/prompts.mjs +32 -5
  233. package/packages/apra-fleet-se/fleet-sprint/runner.js +824 -98
  234. package/packages/apra-fleet-se/fleet-sprint/se-os-commands.mjs +4 -2
  235. package/packages/apra-fleet-se/fleet-sprint/se-posix.mjs +54 -1
  236. package/packages/apra-fleet-se/fleet-sprint/se-windows.mjs +29 -2
  237. package/packages/apra-fleet-se/fleet-sprint/set-aside.mjs +288 -0
  238. package/packages/apra-fleet-se/fleet-sprint/skills/fleet-supervisor/SKILL.md +3 -2
  239. package/packages/apra-fleet-se/fleet-sprint/sprint-args.mjs +20 -0
  240. package/packages/apra-fleet-se/fleet-sprint/sprint-report.mjs +21 -0
  241. package/packages/apra-fleet-se/fleet-sprint/sprint-state.mjs +9 -0
  242. package/packages/apra-fleet-se/fleet-sprint/vcs-auth.mjs +605 -32
  243. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/bitbucket.mjs +811 -17
  244. package/packages/apra-fleet-se/fleet-sprint/vcs-providers/index.mjs +89 -1
  245. package/packages/apra-fleet-se/fleet-sprint/viewer-extensions.mjs +225 -2
  246. package/packages/apra-fleet-se/fleet-sprint/worklists.mjs +59 -3
  247. package/packages/apra-fleet-se/src/supervisor/api.mjs +148 -8
  248. package/packages/apra-fleet-se/src/supervisor/dashboard.mjs +6 -3
  249. package/packages/apra-fleet-se/src/supervisor/dolt-mutex.mjs +30 -10
  250. package/packages/apra-fleet-se/src/supervisor/fleet-members.mjs +17 -4
  251. package/packages/apra-fleet-se/src/supervisor/history.mjs +8 -1
  252. package/packages/apra-fleet-se/src/supervisor/id-allocator.mjs +92 -2
  253. package/packages/apra-fleet-se/src/supervisor/proxy.mjs +26 -1
  254. package/packages/apra-fleet-se/src/supervisor/server.mjs +151 -8
  255. package/packages/apra-fleet-se/src/supervisor/spawner.mjs +11 -9
  256. package/packages/apra-fleet-se/src/supervisor/watchdog.mjs +7 -1
  257. package/packages/apra-fleet-workflow/package.json +2 -1
  258. package/packages/apra-fleet-workflow/src/viewer/index.mjs +86 -5
  259. package/packages/apra-fleet-workflow/src/viewer/request-guard.mjs +222 -0
  260. package/packages/apra-fleet-workflow/src/workflow/index.mjs +34 -2
  261. package/plugins/claude-code/fleet-status/.claude-plugin/plugin.json +7 -0
  262. package/plugins/claude-code/fleet-status/hooks/hooks.json +1 -0
  263. package/plugins/claude-code/fleet-status/hooks/register.tsx +906 -0
  264. package/plugins/claude-code/fleet-status/types/index.d.ts +88 -0
  265. package/skills/fleet/auth-bitbucket.md +47 -20
  266. package/skills/fleet/onboarding.md +1 -1
  267. package/skills/fleet/skill-matrix.md +3 -3
  268. package/version.json +1 -1
@@ -1,3 +1,20 @@
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
@@ -269,6 +286,23 @@
269
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.
270
287
  */
271
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}}
304
+ */
305
+
272
306
  /**
273
307
  * @typedef {Object} SendFilesOptions
274
308
  * @property {string[]} local_paths - Array of local file paths to upload
@@ -502,6 +536,18 @@
502
536
  * with the value escaped for the interior of a single-quoted string, with no quotes of its
503
537
  * own, for interpolating the token into a larger already-quoted value (e.g. an Authorization
504
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.
505
551
  * @property {string} [label] - Credential label provision_vcs_auth deployed the helper under
506
552
  * (it defaults to the provider name there, e.g. "github" or "azure-devops"). Omit for the
507
553
  * unlabelled helper.
@@ -515,13 +561,15 @@
515
561
  * @property {boolean} ok - True when the credential-requiring command was dispatched. Read
516
562
  * exitCode for the command's own outcome.
517
563
  * @property {"ok" | "member_not_found" | "placeholder_missing" | "unsupported_member_os" |
518
- * "credential_read_failed" | "credential_empty" | "dispatch_failed"} reason - Machine-readable
564
+ * "credential_read_failed" | "credential_empty" | "username_empty" |
565
+ * "dispatch_failed"} reason - Machine-readable
519
566
  * outcome code. Branch on this, never on the text.
520
567
  * @property {number|null} exitCode - Exit code of the dispatched command, null if it never ran.
521
568
  * @property {string} stdout - Command stdout, with every occurrence of the credential redacted.
522
569
  * @property {string} stderr - Command stderr, with every occurrence of the credential redacted.
523
- * @property {number} tokenRedactions - How many times the credential had to be redacted out of
524
- * 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.
525
573
  * @property {string|null} credentialLabel - Credential label used, or null for the unlabelled helper.
526
574
  * @property {string|null} memberId - Registry id of the resolved member, or null.
527
575
  * @property {string|null} memberName - Friendly name of the resolved member, or null.
@@ -563,8 +611,10 @@
563
611
  * @property {"ok" | "deployed_unverified" | "deployed_verification_skipped" |
564
612
  * "member_not_found" | "member_offline" | "secret_variable_not_found" |
565
613
  * "secret_variable_denied" | "secret_variable_expired" | "oob_cancelled" |
566
- * "credential_assembly_unsupported" | "credential_assembly_failed" | "deploy_threw" |
567
- * "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).
568
618
  * @property {string} provider - The VCS provider requested.
569
619
  * @property {string} credentialLabel - Credential label the helper was deployed under
570
620
  * (defaults to the provider name).
@@ -574,6 +624,10 @@
574
624
  * instead of scraping an "expiresAt:" line out of the summary text.
575
625
  * @property {boolean} verified - True only when testConnectivity() actually ran AND succeeded.
576
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.
577
631
  * @property {Record<string, string>|null} metadata - The provider's own deploy metadata,
578
632
  * filtered through a server-side key allowlist before it reaches this field (an unrecognised
579
633
  * key is dropped, never passed through). Providers additionally mask the token value here to
@@ -597,6 +651,9 @@
597
651
  * @property {string} [member_name] - Friendly name of the member
598
652
  * @property {"github" | "bitbucket" | "azure-devops"} provider - VCS provider to configure
599
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.
600
657
  * @property {string} [scope_url] - Git credential scope URL (e.g. "https://github.com/my-org").
601
658
  * Defaults to "https://<host>". For an Azure DevOps repo on the legacy host, pass
602
659
  * "https://ORG.visualstudio.com" so the PAT is bound to the host the member pushes to.
@@ -604,13 +661,18 @@
604
661
  * configured app) or pat (personal access token)
605
662
  * @property {string} [token] - Personal access token (GitHub PAT or Azure DevOps PAT).
606
663
  * Supports {{secret.NAME}} token -- resolved from the credential store server-side before use.
607
- * @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
608
667
  * level override
609
668
  * @property {string[]} [repos] - GitHub App repository list override
610
- * @property {string} [email] - Bitbucket account email
611
- * @property {string} [api_token] - Bitbucket API token. Supports {{secret.NAME}} token --
612
- * resolved from the credential store server-side before use.
613
- * @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).
614
676
  * @property {string} [org_url] - Azure DevOps organization URL (e.g. https://dev.azure.com/myorg,
615
677
  * or the legacy https://myorg.visualstudio.com)
616
678
  * @property {string} [pat] - Azure DevOps personal access token. Supports {{secret.NAME}}
@@ -699,6 +761,27 @@
699
761
  * @property {string} baseBranch - The target base branch, written to provenance.branch.
700
762
  * @property {string} baseCommit - The base commit the entries were verified against,
701
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.
702
785
  */
703
786
 
704
787
  /**
@@ -863,7 +946,7 @@ export function assertNoRemovedKbScopeKeys(tool, options) {
863
946
  const err = new Error(
864
947
  `E-SCOPE-KEY-REMOVED: ${tool} no longer accepts ${present.map((k) => `'${k}'`).join(', ')} ` +
865
948
  '(removed in the KB redesign); the call was not sent. Remediation: drop it -- every kb_* call acts on the ' +
866
- "calling session's own KB (a member session's registered work folder; a FULL session's fleet server working folder).",
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).",
867
950
  );
868
951
  err.code = 'E-SCOPE-KEY-REMOVED';
869
952
  throw err;
@@ -1035,13 +1118,26 @@ export class ApraFleet {
1035
1118
  }
1036
1119
 
1037
1120
  /**
1038
- * 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.
1039
1125
  * @param {FleetStatusOptions} [options]
1040
1126
  */
1041
1127
  async fleetStatus(options = {}) {
1042
1128
  return this.mcpClient.callTool('fleet_status', options);
1043
1129
  }
1044
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
+
1045
1141
  /**
1046
1142
  * Get detailed status for one member: connectivity, session, work folder, provider, registered shell (Windows).
1047
1143
  * @param {{ member_id?: string, member_name?: string, format?: 'compact'|'json', refresh?: boolean }} options
@@ -1174,6 +1270,13 @@ export class ApraFleet {
1174
1270
  * command, and redacts the value from the returned stdout/stderr. The
1175
1271
  * plaintext appears in no field of the result.
1176
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
+ *
1177
1280
  * @param {VcsCredentialExecOptions} options
1178
1281
  * @returns {Promise<{ content: Array<{type: string, text: string}>,
1179
1282
  * structuredContent: VcsCredentialExecStructured }>}
@@ -1223,15 +1326,16 @@ export class ApraFleet {
1223
1326
  * provenance, and make a local commit scoped to the bible path whose message
1224
1327
  * lists each removal. Never pushes; re-running with the
1225
1328
  * same ids after resetting to a newer HEAD re-merges, so a rejected push can
1226
- * be retried. Result JSON: {path, merged, skipped, removed, entry_count,
1227
- * backfilled, committed}; extract with parseToolJson(). backfilled counts the
1329
+ * be retried. Result JSON: {path, merged, demoted, skipped, removed,
1330
+ * entry_count, backfilled, committed}; extract with parseToolJson(). backfilled counts the
1228
1331
  * existing bible entries with no source_file_hashes (carried over from a
1229
1332
  * v1/v2 bible) that gained this KB's stored basis for the same id, because
1230
1333
  * it passes the same basis rule at HEAD and cites the same files (legacy
1231
1334
  * backfill; only that field changes, nothing is dropped); a backfill alone
1232
- * makes a commit. Each skipped item is {id, reason}
1233
- * with reason not_confirmed_or_unknown, no_source_files (a CONFIRMED id
1234
- * citing no source file) or basis_mismatch. Each removed item is {id, reason}
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}
1235
1339
  * with reason superseded or invalidated. A member session without the
1236
1340
  * kb_maintainer grant cannot retire a CONFIRMED entry through the kb_* tools:
1237
1341
  * kb_invalidate leaves CONFIRMED entries untouched, and kb_capture with
@@ -1241,8 +1345,15 @@ export class ApraFleet {
1241
1345
  * a routing guard for agent sessions, not a boundary against a local process
1242
1346
  * that can open a FULL session or write the KB directly.
1243
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.
1244
1350
  * The removed scope keys (repo_path, repo, repo_remote_url) are refused
1245
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.
1246
1357
  * @param {KbBibleCommitOptions} options
1247
1358
  */
1248
1359
  async kbBibleCommit(options) {
@@ -1250,6 +1361,22 @@ export class ApraFleet {
1250
1361
  return this.mcpClient.callTool('kb_bible_commit', options);
1251
1362
  }
1252
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
+
1253
1380
  /**
1254
1381
  * Convert a remote member from password to SSH key authentication.
1255
1382
  * @param {SetupSshKeyOptions} options
@@ -1258,6 +1385,29 @@ export class ApraFleet {
1258
1385
  return this.mcpClient.callTool('setup_ssh_key', options);
1259
1386
  }
1260
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
+
1261
1411
  /**
1262
1412
  * Send an email. Pass provider config inline (provider, from, and for
1263
1413
  * SMTP: host, port, user, secure). Secrets resolve from the credential
@@ -1281,8 +1431,11 @@ export class ApraFleet {
1281
1431
 
1282
1432
  /**
1283
1433
  * code_reindex -- rebuild the code index of the calling session's own repo
1284
- * (a member session's work folder, otherwise the fleet server's folder;
1285
- * there is no repo argument). Starts gitnexus analyze detached with its
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
1286
1439
  * output captured to <data>/code-index/<slug>/analyze.log and returns
1287
1440
  * after the first tick. Extract the JSON with parseToolJson(): `outcome`
1288
1441
  * is 'started' | 'up-to-date' | 'starting' | 'already-running' |
@@ -78,7 +78,8 @@ export class ReconnectingHttpTransport extends EventEmitter {
78
78
  await t.start();
79
79
  t.off('error', onInitError);
80
80
  if (initError || !t.sessionId) {
81
- try { t.stop(); } catch { /* ignore */ }
81
+ // close() also releases a session the server already issued.
82
+ releaseTransport(t);
82
83
  throw initError || new Error(`Could not open an MCP session at ${url}`);
83
84
  }
84
85
  const old = this.inner;
@@ -96,7 +97,10 @@ export class ReconnectingHttpTransport extends EventEmitter {
96
97
  this.stale = true;
97
98
  this.emit('close');
98
99
  });
99
- if (old) { try { old.stop(); } catch { /* ignore */ } }
100
+ // Release the replaced session on the server too (HTTP DELETE, best
101
+ // effort): stop() alone would leave it open there for good when the
102
+ // old connection died while the server stayed up.
103
+ if (old) releaseTransport(old);
100
104
  }
101
105
 
102
106
  /** Serialised: concurrent senders share one re-probe/reconnect. */
@@ -125,6 +129,10 @@ export class ReconnectingHttpTransport extends EventEmitter {
125
129
  }
126
130
  }
127
131
 
132
+ /**
133
+ * Local-only teardown: aborts the streams but leaves the server session
134
+ * open until the server evicts it. Use close() when done with the transport.
135
+ */
128
136
  stop() {
129
137
  this.stopped = true;
130
138
  if (this.inner) {
@@ -134,4 +142,29 @@ export class ReconnectingHttpTransport extends EventEmitter {
134
142
  t.stop();
135
143
  }
136
144
  }
145
+
146
+ /** Release the server session (HTTP DELETE, best effort), then stop. */
147
+ async close() {
148
+ this.stopped = true;
149
+ if (this.reconnecting) {
150
+ try { await this.reconnecting; } catch { /* nothing to release */ }
151
+ }
152
+ if (this.inner) {
153
+ const t = this.inner;
154
+ t.once('close', () => this.emit('close'));
155
+ if (typeof t.close === 'function') await t.close();
156
+ else t.stop();
157
+ }
158
+ }
159
+ }
160
+
161
+ /** Fire-and-forget release of a replaced inner transport. */
162
+ function releaseTransport(t) {
163
+ try {
164
+ if (typeof t.close === 'function') {
165
+ Promise.resolve(t.close()).catch(() => { /* best effort */ });
166
+ } else {
167
+ t.stop();
168
+ }
169
+ } catch { /* ignore */ }
137
170
  }
@@ -101,6 +101,12 @@ export class StdioTransport extends EventEmitter {
101
101
  this.process = null;
102
102
  }
103
103
  }
104
+
105
+ /** Same as stop(): a stdio server lives and dies with its process. Lets
106
+ * every caller end any transport with close(). */
107
+ async close() {
108
+ this.stop();
109
+ }
104
110
  }
105
111
 
106
112
  export class StreamableHttpTransport extends EventEmitter {
@@ -25,6 +25,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
25
25
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
26
26
  your tool-loading tool first, before concluding they are unavailable.
27
27
 
28
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
29
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
30
+ not help), retry that call ONCE, and if it still fails fall back to text search and
31
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
32
+
28
33
  1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
29
34
  subsystems the assigned beads touch. KB knowledge matters most for duplicate
30
35
  detection and sprint-set grouping.
@@ -37,6 +37,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
37
37
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
38
38
  your tool-loading tool first, before concluding they are unavailable.
39
39
 
40
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
41
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
42
+ not help), retry that call ONCE, and if it still fails fall back to text search and
43
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
44
+
40
45
  1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
41
46
  repo's CI workflow files. Known-flaky tests and known CI failure modes are the point
42
47
  here -- they change how you read a red run.
@@ -80,8 +80,11 @@ console.log(JSON.stringify([...allow], null, 2));
80
80
 
81
81
  Check every required prefix against this one merged list. If any prefix has
82
82
  no covering entry, STOP immediately and return `deployed: false`, listing
83
- every missing entry in `notes` and asking the orchestrator/operator to run
84
- `compose_permissions` with the missing grant(s), then re-trigger the sprint.
83
+ every missing entry in `notes`, and set `failedStep: "permissions"`, asking the
84
+ orchestrator/operator to run `compose_permissions` with the missing grant(s), then
85
+ re-trigger the sprint. `failedStep` is how the orchestrator knows no deploy command
86
+ ran -- set it only for this Step 0a stop, never for a failure after a deploy command
87
+ ran.
85
88
  NEVER add permissions yourself: `.claude/settings.json` changes require a
86
89
  team PR, and `.claude/settings.local.json` must be provisioned via the
87
90
  `compose_permissions` MCP tool (the provider-agnostic delivery mechanism
@@ -103,6 +106,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
103
106
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
104
107
  your tool-loading tool first, before concluding they are unavailable.
105
108
 
109
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
110
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
111
+ not help), retry that call ONCE, and if it still fails fall back to text search and
112
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
113
+
106
114
  1. When the tools are present, call `kb_session_prime` with `hint_modules` naming the
107
115
  deploy targets in `deploy.md`.
108
116
  2. Any judgment that depends on what the KB does or does not record is made from the
@@ -161,6 +169,16 @@ placeholder):
161
169
  }
162
170
  ```
163
171
 
172
+ A Step 0a stop (missing permissions, no deploy command ran):
173
+
174
+ ```json
175
+ {
176
+ "deployed": false,
177
+ "failedStep": "permissions",
178
+ "notes": "Missing permission grant(s): <entries>. Run compose_permissions with them, then re-trigger the sprint."
179
+ }
180
+ ```
181
+
164
182
  **Precedence**: If your dispatch prompt includes a JSON schema instruction, that schema is
165
183
  authoritative -- respond with exactly that JSON and nothing else. It is expected to match
166
184
  this contract; if it differs, follow the dispatch prompt.
@@ -51,6 +51,23 @@ your final `notes`, naming the bead id and the defect. This is a legitimate skip
51
51
  exception (see Step 3 and Rules); it lets the reviewer route the bead to re-planning in
52
52
  the same round.
53
53
 
54
+ **Needs an operator decision**: when a bead cannot go on until a human chooses between
55
+ real alternatives -- for example the criteria can only be met by upgrading a dependency,
56
+ patching it, or accepting a weaker check, and nothing in the bead, its parent or the code
57
+ says which -- do not guess and do not keep retrying. Leave the bead open and return
58
+ `status: "NEEDS-DECISION"` with a `decision` object: `beadId` (that one open bead),
59
+ `question` (self-contained: what you found, why it blocks the bead, what must be
60
+ decided), `options` (at least two, each `{ "id": "a", "text": "..." }` with what it
61
+ means and costs) and `recommendation` (the option id you recommend, and why). The
62
+ orchestrator files the question for an operator verbatim, sets the bead aside for the
63
+ rest of the run without re-dispatching it, and keeps working other beads; the answer
64
+ reaches a later dispatch through the bead's notes. Use it instead of the
65
+ criteria-defect escape hatch only when the fix is a choice an operator must make, not a
66
+ criteria rewrite a planner can make. Use BLOCKED, not NEEDS-DECISION, for a missing
67
+ secret, missing access, or an unmet prerequisite: those have one fix, not a choice. The
68
+ same-lane stop rule (Step 1) applies to a NEEDS-DECISION bead exactly as to any other
69
+ bead left open.
70
+
54
71
  **CI is not yours**: never trigger, wait for or poll a CI run. A criterion that can only
55
72
  be met by a CI run is a criteria defect: do the locally checkable work and report the CI
56
73
  part under "criteria defects" (see above).
@@ -80,6 +97,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
80
97
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
81
98
  your tool-loading tool first, before concluding they are unavailable.
82
99
 
100
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
101
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
102
+ not help), retry that call ONCE, and if it still fails fall back to text search and
103
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
104
+
83
105
  The `kb_query` and `code_impact` calls below are EXPECTED, not optional, whenever the
84
106
  tools are present. If a tool is genuinely not present (or the KB or code index is not set
85
107
  up for this repo), record that in `toolUse` (Output schema) and continue -- never skip
@@ -105,7 +127,8 @@ silently.
105
127
  fixture-only files are exempt. Prefer these over grep for symbol lookups, call-chain
106
128
  tracing, and impact analysis. If they are absent, fail, or report the repo is not
107
129
  indexed, fall back to grep and record it in `toolUse`; do not try to build an index
108
- yourself.
130
+ yourself. On `E-CODE-INDEX-NOT-READY`, wait once for its `retry_after_ms`, retry
131
+ once, then fall back to grep -- never poll `code_status` in a loop.
109
132
  5. Report in `toolUse`: `kb` and `code` are each `used`, `unavailable` or `not_needed`;
110
133
  `note` says why for anything not `used`. `used` means the expected call was made
111
134
  (`kb_query` for kb -- `kb_session_prime` alone is not `used`; `code_impact`/
@@ -262,6 +285,18 @@ stop and return:
262
285
  orchestrator can verify your closes against beads instead of trusting the summary alone.
263
286
  Do NOT continue past VERIFY.
264
287
 
288
+ Whenever you return `status: "BLOCKED"`, also return `blockedIds`: the assigned bead ids
289
+ you left open BECAUSE of the block. Leave out ids you merely did not reach (for example
290
+ lane-mates skipped under the same-lane stop rule) -- the orchestrator sets each
291
+ `blockedIds` bead and everything depending on it aside for the rest of the run, and
292
+ re-dispatches the unreached ones. Example:
293
+ `{ "status": "BLOCKED", "closedIds": ["<id-1>"], "blockedIds": ["<id-2>"], "notes": "..." }`.
294
+
295
+ When a bead needs an operator decision (see "Needs an operator decision" above), stop
296
+ there and return `status: "NEEDS-DECISION"` with its `decision` object, listing in
297
+ `closedIds` whatever you closed before it. Example:
298
+ `{ "status": "NEEDS-DECISION", "closedIds": ["<id-1>"], "notes": "...", "decision": { "beadId": "<id-2>", "question": "...", "options": [{ "id": "a", "text": "..." }, { "id": "b", "text": "..." }], "recommendation": "a, because ..." } }`.
299
+
265
300
 
266
301
  ## Branch and secrets rules
267
302
 
@@ -303,7 +338,8 @@ or as prose if you are answering a human directly.
303
338
  - NEVER skip an assigned bead id for convenience -- work them in dependency order. The
304
339
  only skip exceptions: has open children, the same-lane stop rule (Step 1) after an
305
340
  earlier lane-mate was left open, an unresolved wrap-up ambiguity, missing acceptance
306
- criteria/context, or a recorded criteria defect (escape hatch above). A missing secret
341
+ criteria/context, a recorded criteria defect (escape hatch above), or a bead that needs
342
+ an operator decision (returned as NEEDS-DECISION). A missing secret
307
343
  is NOT a skip -- close with a blocked reason per Branch and secrets rules.
308
344
  - Tests for the changed area must pass before each commit (Step 2.5)
309
345
  - No PLAN.md, no progress.json -- beads is the only work tracker
@@ -18,7 +18,7 @@ wired and queried; do not restate or improvise those rules here.
18
18
  Your dispatch prompt must supply:
19
19
 
20
20
  - `analysisArtifactFile` (required) -- relative path (under the repo) to write the sprint
21
- analysis artifact to, e.g. `sprint-logs/<branch>-<startedAt>.md`.
21
+ analysis artifact to, e.g. `docs/sprint-analysis-<slug>.md`. Written, never committed.
22
22
  - `analysisText` (required) -- the exact, pre-formatted analysis content to write verbatim.
23
23
  - `base-branch` (required) -- for `git log`/`git diff` in Step 2.
24
24
  - `branch` (required) -- the sprint branch being harvested.
@@ -44,6 +44,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
44
44
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
45
45
  your tool-loading tool first, before concluding they are unavailable.
46
46
 
47
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
48
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
49
+ not help), retry that call ONCE, and if it still fails fall back to text search and
50
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
51
+
47
52
  1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
48
53
  relevant to the modules touched during the sprint.
49
54
  2. When you extract durable knowledge during harvest -- anything non-obvious that future
@@ -70,17 +75,15 @@ search also matches value text, so apply only entries whose KEY contains `+all+`
70
75
 
71
76
  Your task context includes an `analysisArtifactFile` path and an `analysisText` block.
72
77
 
73
- Write the `analysisText` verbatim to the file at `<repo>/<analysisArtifactFile>` (overwrite if it exists):
74
-
75
- ```bash
76
- mkdir -p "<repo>/sprint-logs"
77
- # Write analysisText content to <repo>/<analysisArtifactFile>
78
- git -C "<repo>" add "<repo>/<analysisArtifactFile>"
79
- git -C "<repo>" -c user.name='pm' -c user.email='pm@pm.local' commit -m "chore: sprint-analysis <branch> <startedAt>"
80
- ```
78
+ Write the `analysisText` verbatim to the file at `<repo>/<analysisArtifactFile>` (overwrite
79
+ if it exists; create its parent directory if missing).
81
80
 
82
81
  Do NOT reformat or modify the analysisText -- write it exactly as provided.
83
82
 
83
+ **Do NOT `git add` or commit this file.** It is a local record that stays untracked in the
84
+ working tree; the orchestrator keeps it out of `git status` and out of every commit. Never
85
+ force-add it (`git add -f`), and do not stage it in any later step.
86
+
84
87
  ## Step 2 -- Read sprint context
85
88
 
86
89
  Read the following to understand what was built:
@@ -76,6 +76,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
76
76
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
77
77
  your tool-loading tool first, before concluding they are unavailable.
78
78
 
79
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
80
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
81
+ not help), retry that call ONCE, and if it still fails fall back to text search and
82
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
83
+
79
84
  1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
80
85
  relevant to the features you were handed.
81
86
  2. Any judgment that depends on what the KB does or does not record (e.g. whether a test
@@ -105,6 +105,12 @@ code_impact({ target: "<symbol>", direction: "upstream" | "downstream" })
105
105
  code_query({ query: "<concept or pattern>" })
106
106
  ```
107
107
 
108
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
109
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
110
+ not help), retry that call ONCE, and if it still fails fall back to reading the cited
111
+ files directly and say so in the evidence note. Never poll `code_status` in a loop
112
+ waiting for the index.
113
+
108
114
  Decide which entry's claim the CURRENT merged code actually supports. Note the exact
109
115
  file + symbol you read that settled it.
110
116
 
@@ -63,6 +63,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
63
63
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
64
64
  your tool-loading tool first, before concluding they are unavailable.
65
65
 
66
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
67
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
68
+ not help), retry that call ONCE, and if it still fails fall back to text search and
69
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
70
+
66
71
  1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
67
72
  relevant to the features in the DAG under review.
68
73
  2. Any judgment that depends on KB coverage (e.g. whether a task touches unexplored code
@@ -43,6 +43,11 @@ trust CONFIRMED entries fully and use INFERRED entries as hints, not facts.
43
43
  If the `kb_*`/`code_*` tools are listed only as deferred tools, load them by name with
44
44
  your tool-loading tool first, before concluding they are unavailable.
45
45
 
46
+ If a `code_*` call fails with `E-CODE-INDEX-NOT-READY`, wait ONCE for the
47
+ `retry_after_ms` its error result carries (skip the wait when it is 0: retrying will
48
+ not help), retry that call ONCE, and if it still fails fall back to text search and
49
+ record the fallback. Never poll `code_status` in a loop waiting for the index.
50
+
46
51
  1. When the tools are present, call `kb_session_prime` with `hint_symbols`/`hint_modules`
47
52
  derived from the sprint goals / requirements you are about to decompose.
48
53
  2. From whichever source you have (a live `kb_session_prime` result, the injected