@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
@@ -0,0 +1,126 @@
1
+ // =============================================================================
2
+ // Pure helpers for the PRE-LAUNCH stale-claim reclaim (reclaimStaleInProgress
3
+ // in runner.js) and for naming what any reclaim unblocks.
4
+ //
5
+ // Nothing here issues a command: every function takes beads the caller
6
+ // already holds (the shared snapshot, a fresh `bd list`, or a fresh `bd show`)
7
+ // and returns plain data. runner.js owns every read and write.
8
+ //
9
+ // - isPreLaunchReclaimCandidate: the pre-launch rule itself -- in_progress,
10
+ // no unmet `blocks` dependency, claimed before this sprint launched (or
11
+ // with no parseable started_at), and not an id this run already took
12
+ // over (settledIds: reclaimed once already, or dispatched to a doer of
13
+ // this run -- from then on its claims belong to the in-run tracker).
14
+ // - confirmPreLaunchCandidates: the fresh-read gate. A candidate picked from
15
+ // the cached snapshot (which can lag a cycle behind agent-made closes) is
16
+ // only written to if a FRESH read still shows it in_progress under the
17
+ // same assignee. The snapshot pre-filters; it never authorizes a write.
18
+ // - downstreamDependentIds: the beads waiting on a reclaimed bead through a
19
+ // `blocks` edge, for the reclaim log line.
20
+ //
21
+ // WHY settledIds AND NOT started_at. bd stamps started_at on a bead's FIRST
22
+ // claim only; re-claiming a reopened bead keeps the old stamp. So once this
23
+ // run reclaims a pre-launch bead and a doer of this run claims it again, its
24
+ // started_at still predates the launch, and the pre-launch rule alone would
25
+ // treat this run's own claim as stale. Excluding every id this run has
26
+ // reclaimed or dispatched is the only reliable boundary.
27
+ //
28
+ // GUARD COVERAGE: registered in guarded-modules.mjs. No command() or agent()
29
+ // call site.
30
+ // =============================================================================
31
+
32
+ const isBlocksEdge = (d) => d && d.type === 'blocks' && typeof d.depends_on_id === 'string';
33
+
34
+ /**
35
+ * True when `startedAt` (an ISO string, or absent) predates `sprintLaunchTime`
36
+ * (epoch ms). A missing or unparseable value counts as predating the launch:
37
+ * `bd update --claim` always stamps started_at, so a claim with none can only
38
+ * be orphaned state from something else.
39
+ * @param {string|undefined|null} startedAt
40
+ * @param {number} sprintLaunchTime
41
+ */
42
+ export function claimPredatesLaunch(startedAt, sprintLaunchTime) {
43
+ const startedAtMs = startedAt ? Date.parse(startedAt) : NaN;
44
+ return Number.isNaN(startedAtMs) || startedAtMs < sprintLaunchTime;
45
+ }
46
+
47
+ /**
48
+ * The pre-launch reclaim rule for one bead.
49
+ * @param {object} bead
50
+ * @param {{ notDoneIds: Set<string>, sprintLaunchTime: number, settledIds?: Set<string> }} ctx
51
+ * notDoneIds: ids that still count as unmet blockers.
52
+ * settledIds: ids this run already reclaimed or dispatched; never candidates.
53
+ */
54
+ export function isPreLaunchReclaimCandidate(bead, { notDoneIds, sprintLaunchTime, settledIds = new Set() }) {
55
+ if (!bead || bead.status !== 'in_progress') return false;
56
+ if (settledIds.has(bead.id)) return false;
57
+ const hasUnmetBlocker = (bead.dependencies || [])
58
+ .some((d) => isBlocksEdge(d) && notDoneIds.has(d.depends_on_id));
59
+ if (hasUnmetBlocker) return false;
60
+ return claimPredatesLaunch(bead.started_at, sprintLaunchTime);
61
+ }
62
+
63
+ /**
64
+ * Splits snapshot-picked candidates by what a fresh read says now. Confirmed
65
+ * means the fresh bead is still in_progress AND still held by the assignee
66
+ * the snapshot showed. A bead that closed or reopened since the snapshot, or
67
+ * was claimed by a different actor in between (bd keeps the original
68
+ * started_at on a re-claim, so the assignee is the only visible signal), is
69
+ * rejected.
70
+ * @param {object[]} candidates beads picked from the snapshot
71
+ * @param {object[]} freshBeads the fresh `bd show` result for those ids
72
+ * @returns {{ confirmed: object[], rejected: Array<{ id: string, status: string|null, reason: string }> }}
73
+ * confirmed carries the FRESH bead objects, in candidate order. Each
74
+ * reason is a full clause ("the fresh read shows 'closed'").
75
+ */
76
+ export function confirmPreLaunchCandidates(candidates, freshBeads) {
77
+ const freshById = new Map((Array.isArray(freshBeads) ? freshBeads : [])
78
+ .filter((b) => b && typeof b.id === 'string')
79
+ .map((b) => [b.id, b]));
80
+ const assigneeOf = (b) => (b && typeof b.assignee === 'string' ? b.assignee : '');
81
+ const confirmed = [];
82
+ const rejected = [];
83
+ for (const c of candidates) {
84
+ const fresh = freshById.get(c.id);
85
+ if (!fresh) {
86
+ rejected.push({ id: c.id, status: null, reason: 'it is missing from the fresh read' });
87
+ continue;
88
+ }
89
+ if (fresh.status !== 'in_progress') {
90
+ rejected.push({ id: c.id, status: fresh.status || null, reason: `the fresh read shows '${fresh.status || 'unknown'}'` });
91
+ continue;
92
+ }
93
+ if (assigneeOf(fresh) !== assigneeOf(c)) {
94
+ rejected.push({ id: c.id, status: fresh.status, reason: `the fresh read shows it claimed by '${assigneeOf(fresh) || '(none)'}', not '${assigneeOf(c) || '(none)'}' as in the snapshot` });
95
+ continue;
96
+ }
97
+ confirmed.push(fresh);
98
+ }
99
+ return { confirmed, rejected };
100
+ }
101
+
102
+ /**
103
+ * Ids of the not-closed beads in `beads` that have a `blocks` dependency on
104
+ * `id` -- the beads a reclaim of `id` puts back on the path to ready.
105
+ * @param {object[]} beads
106
+ * @param {string} id
107
+ * @returns {string[]} in input order.
108
+ */
109
+ export function downstreamDependentIds(beads, id) {
110
+ return (beads || [])
111
+ .filter((b) => b && b.status !== 'closed')
112
+ .filter((b) => (b.dependencies || []).some((d) => isBlocksEdge(d) && d.depends_on_id === id))
113
+ .map((b) => b.id);
114
+ }
115
+
116
+ /**
117
+ * The log suffix naming what a reclaim of `id` unblocks.
118
+ * @param {object[]} beads
119
+ * @param {string} id
120
+ */
121
+ export function downstreamSuffix(beads, id) {
122
+ const downstream = downstreamDependentIds(beads, id);
123
+ return downstream.length > 0
124
+ ? ` Downstream bead(s) waiting on it: ${downstream.join(', ')}.`
125
+ : ' No downstream bead is waiting on it.';
126
+ }
@@ -352,6 +352,132 @@ function blocksPrereqIds(bead) {
352
352
  return out;
353
353
  }
354
354
 
355
+ // ---------------------------------------------------------------------------
356
+ // Prerequisites: blocks edges and lane order
357
+ // ---------------------------------------------------------------------------
358
+ //
359
+ // A bead's prerequisites are (1) its open 'blocks' dependencies and (2) its
360
+ // open lane-mates with a LOWER `streakOrder` (same `metadata.streak`): inside
361
+ // a lane the planner orders work by `streakOrder` only, never by an edge, so
362
+ // lane order is a real prerequisite too.
363
+
364
+ /** A bead's metadata as an object (bd may hand it back as a JSON string). */
365
+ function metadataOf(bead) {
366
+ const m = bead && bead.metadata;
367
+ if (!m) return {};
368
+ if (typeof m === 'string') {
369
+ try { const parsed = JSON.parse(m); return parsed && typeof parsed === 'object' ? parsed : {}; } catch { return {}; }
370
+ }
371
+ return typeof m === 'object' ? m : {};
372
+ }
373
+
374
+ /**
375
+ * A bead's lane position: `{ streak, order }` when it carries a non-empty
376
+ * `streak` and a finite numeric `streakOrder`, else null (not ordered).
377
+ * @param {object} bead
378
+ * @returns {{ streak: string, order: number }|null}
379
+ */
380
+ export function laneOf(bead) {
381
+ const m = metadataOf(bead);
382
+ const streak = m.streak;
383
+ if (typeof streak !== 'string' || streak.trim() === '') return null;
384
+ const raw = m.streakOrder;
385
+ const order = typeof raw === 'number' ? raw : Number.parseInt(raw, 10);
386
+ if (!Number.isFinite(order)) return null;
387
+ return { streak, order };
388
+ }
389
+
390
+ function indexById(beads) {
391
+ const byId = new Map();
392
+ for (const b of beads || []) {
393
+ if (b && b.id !== undefined && b.id !== null && !byId.has(String(b.id))) byId.set(String(b.id), b);
394
+ }
395
+ return byId;
396
+ }
397
+
398
+ /**
399
+ * A bead's UNMET prerequisites, mechanically, from the bead graph alone:
400
+ * - `inScope`: open in-scope 'blocks' dependencies plus open lower-order
401
+ * lane-mates;
402
+ * - `outOfScope`: open 'blocks' dependencies outside the sprint scope
403
+ * (known only when `allBeads` is given) -- they cannot close in this run.
404
+ *
405
+ * @param {object} bead
406
+ * @param {object} ctx
407
+ * @param {Array<object>} ctx.scopeBeads every in-scope bead, any status
408
+ * @param {Array<object>} [ctx.allBeads] every bead, any status (out-of-scope lookups)
409
+ * @returns {{ inScope: string[], outOfScope: string[] }}
410
+ */
411
+ export function unmetPrerequisites(bead, { scopeBeads, allBeads = null }) {
412
+ const scopeById = scopeBeads instanceof Map ? scopeBeads : indexById(scopeBeads);
413
+ const allById = allBeads instanceof Map ? allBeads : indexById(allBeads || []);
414
+ const inScope = [];
415
+ const outOfScope = [];
416
+ const id = String(bead && bead.id);
417
+ for (const pre of blocksPrereqIds(bead)) {
418
+ if (pre === id) continue;
419
+ const target = scopeById.get(pre);
420
+ if (target) {
421
+ if (target.status === 'closed') continue;
422
+ inScope.push(pre);
423
+ } else {
424
+ const outside = allById.get(pre);
425
+ if (outside && outside.status !== 'closed') outOfScope.push(pre);
426
+ }
427
+ }
428
+ const lane = laneOf(bead);
429
+ if (lane) {
430
+ const mates = [];
431
+ for (const m of scopeById.values()) {
432
+ if (!m || String(m.id) === id || m.status === 'closed') continue;
433
+ const ml = laneOf(m);
434
+ if (ml && ml.streak === lane.streak && ml.order < lane.order) mates.push(m);
435
+ }
436
+ mates.sort((a, b) => laneOf(a).order - laneOf(b).order || String(a.id).localeCompare(String(b.id)));
437
+ for (const m of mates) if (!inScope.includes(String(m.id))) inScope.push(String(m.id));
438
+ }
439
+ return { inScope, outOfScope };
440
+ }
441
+
442
+ /**
443
+ * Every OPEN (non-closed) bead in `scopeBeads` that depends on one of
444
+ * `rootIds` over 'blocks' edges, directly or transitively, mapped to the root
445
+ * id its chain leads back to (the first root reached, breadth-first). The
446
+ * roots themselves are not included. Parent-child edges are not followed.
447
+ *
448
+ * @param {Iterable<string>} rootIds
449
+ * @param {Array<object>} scopeBeads - in-scope beads, any status, with `dependencies`
450
+ * @returns {Map<string, string>} dependent id -> root id
451
+ */
452
+ export function openBlocksDependents(rootIds, scopeBeads) {
453
+ const scope = Array.isArray(scopeBeads) ? scopeBeads : [];
454
+ const roots = new Set([...rootIds].map(String));
455
+ // prerequisite id -> beads that list it as a 'blocks' prerequisite
456
+ const dependentsOf = new Map();
457
+ for (const b of scope) {
458
+ if (!b || b.id === undefined || b.id === null) continue;
459
+ for (const pre of blocksPrereqIds(b)) {
460
+ if (!dependentsOf.has(pre)) dependentsOf.set(pre, []);
461
+ dependentsOf.get(pre).push(b);
462
+ }
463
+ }
464
+ const out = new Map();
465
+ const queue = [...roots].map((id) => ({ id, root: id }));
466
+ const visited = new Set(roots);
467
+ while (queue.length > 0) {
468
+ const { id, root } = queue.shift();
469
+ for (const dep of dependentsOf.get(id) || []) {
470
+ const depId = String(dep.id);
471
+ if (visited.has(depId)) continue;
472
+ visited.add(depId);
473
+ if (dep.status === 'closed') continue;
474
+ out.set(depId, root);
475
+ queue.push({ id: depId, root });
476
+ }
477
+ }
478
+ return out;
479
+ }
480
+
355
481
  /**
356
482
  * Split ready leaf beads into those the develop loop may dispatch and the
357
483
  * below-goal ones it must not (see the block comment above).
@@ -383,14 +509,45 @@ export function partitionReadyByGoal(ready, scopeBeads, goal, opts = {}) {
383
509
  for (const b of byId.values()) {
384
510
  if (isOpen(b) && !isBelowGoal(b)) queue.push(String(b.id));
385
511
  }
512
+ // Lane order is a prerequisite too: a kept bead's open lower-order
513
+ // lane-mates are walked like 'blocks' prerequisites, transitively, so an
514
+ // [impl] task is kept whenever its [test] lane-mate is.
515
+ const openLaneMates = new Map(); // streak -> open laned beads
516
+ for (const b of byId.values()) {
517
+ const lane = laneOf(b);
518
+ if (!lane || !isOpen(b)) continue;
519
+ if (!openLaneMates.has(lane.streak)) openLaneMates.set(lane.streak, []);
520
+ openLaneMates.get(lane.streak).push(b);
521
+ }
522
+ const prereqsOf = (bead) => {
523
+ const out = blocksPrereqIds(bead);
524
+ const lane = laneOf(bead);
525
+ if (lane) {
526
+ for (const m of openLaneMates.get(lane.streak) || []) {
527
+ if (laneOf(m).order < lane.order) out.push(String(m.id));
528
+ }
529
+ }
530
+ return out;
531
+ };
386
532
  const visited = new Set(queue);
387
533
  while (queue.length > 0) {
388
534
  const id = queue.shift();
389
- for (const pre of blocksPrereqIds(byId.get(id))) {
535
+ for (const pre of prereqsOf(byId.get(id))) {
390
536
  servesInGoal.add(pre);
391
537
  if (!visited.has(pre)) { visited.add(pre); queue.push(pre); }
392
538
  }
393
539
  }
540
+ // A below-goal bead kept for another reason (already worked on) keeps its
541
+ // lower-order lane-mates too.
542
+ const keepQueue = [...list].filter((b) => b && workedOn.has(String(b.id))).map((b) => String(b.id));
543
+ while (keepQueue.length > 0) {
544
+ const id = keepQueue.shift();
545
+ for (const pre of prereqsOf(byId.get(id))) {
546
+ if (servesInGoal.has(pre)) continue;
547
+ servesInGoal.add(pre);
548
+ keepQueue.push(pre);
549
+ }
550
+ }
394
551
 
395
552
  const dispatchable = [];
396
553
  const excluded = [];
@@ -472,14 +472,51 @@ const FALLBACK_planReviewerVerdict = {
472
472
  required: ['verdict', 'notes', 'taskAssignments'],
473
473
  };
474
474
 
475
+ // The NEEDS-DECISION request a doer or reviewer returns (shared by both
476
+ // fallbacks below). Mirrors the `decision` property of doer-output.json and
477
+ // reviewer-output.json: a bead id, the full question, at least two options
478
+ // each with an id and its text, and a recommendation.
479
+ const FALLBACK_decisionRequest = {
480
+ type: 'object',
481
+ properties: {
482
+ beadId: { type: 'string', minLength: 1 },
483
+ question: { type: 'string', minLength: 1 },
484
+ options: {
485
+ type: 'array',
486
+ minItems: 2,
487
+ items: {
488
+ type: 'object',
489
+ properties: {
490
+ id: { type: 'string', minLength: 1 },
491
+ text: { type: 'string', minLength: 1 },
492
+ },
493
+ required: ['id', 'text'],
494
+ },
495
+ },
496
+ recommendation: { type: 'string', minLength: 1 },
497
+ },
498
+ required: ['beadId', 'question', 'options', 'recommendation'],
499
+ };
500
+
501
+ // `field` is NEEDS-DECISION -> `decision` is required.
502
+ function needsDecisionRequires(field) {
503
+ return {
504
+ if: { properties: { [field]: { const: 'NEEDS-DECISION' } }, required: [field] },
505
+ then: { required: ['decision'] },
506
+ };
507
+ }
508
+
475
509
  // Fallback for role "reviewer". Canonical source:
476
510
  // packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json.
477
511
  const FALLBACK_reviewerVerdict = {
478
512
  $id: 'reviewerVerdict',
479
513
  type: 'object',
480
514
  properties: {
481
- verdict: { type: 'string', enum: ['APPROVED', 'CHANGES_NEEDED'] },
515
+ verdict: { type: 'string', enum: ['APPROVED', 'CHANGES_NEEDED', 'NEEDS-DECISION'] },
482
516
  notes: { type: 'string' },
517
+ // Required when verdict is NEEDS-DECISION (allOf below). Mirrors
518
+ // reviewer-output.json.
519
+ decision: FALLBACK_decisionRequest,
483
520
  reopenIds: { type: 'array', items: { type: 'string' } },
484
521
  // apra-fleet-eft.67.2: optional, deliberately NOT in `required` below
485
522
  // -- mirrors packages/apra-fleet-se/apra-pm/agents/schemas/reviewer-output.json
@@ -509,6 +546,7 @@ const FALLBACK_reviewerVerdict = {
509
546
  },
510
547
  },
511
548
  required: ['verdict', 'notes', 'reopenIds', 'newTasks'],
549
+ allOf: [needsDecisionRequires('verdict')],
512
550
  };
513
551
 
514
552
  // Fallback for role "doer". Canonical source:
@@ -517,11 +555,16 @@ const FALLBACK_doerReport = {
517
555
  $id: 'doerReport',
518
556
  type: 'object',
519
557
  properties: {
520
- status: { type: 'string', enum: ['VERIFY', 'BLOCKED'] },
558
+ status: { type: 'string', enum: ['VERIFY', 'BLOCKED', 'NEEDS-DECISION'] },
521
559
  closedIds: { type: 'array', items: { type: 'string' } },
522
560
  notes: { type: 'string' },
561
+ // Required when status is NEEDS-DECISION (allOf below). Mirrors
562
+ // doer-output.json.
563
+ decision: FALLBACK_decisionRequest,
564
+ blockedIds: { type: 'array', items: { type: 'string' } },
523
565
  },
524
566
  required: ['status', 'closedIds', 'notes'],
567
+ allOf: [needsDecisionRequires('status')],
525
568
  };
526
569
 
527
570
  // NEW (apra-fleet-unw.16): no corresponding vendored agents/*.md file --
@@ -556,6 +599,7 @@ const FALLBACK_deployerReport = {
556
599
  properties: {
557
600
  deployed: { type: 'boolean' },
558
601
  notes: { type: 'string' },
602
+ failedStep: { type: 'string', enum: ['permissions'] },
559
603
  },
560
604
  required: ['deployed', 'notes'],
561
605
  };
@@ -787,6 +831,42 @@ export const finalVerdict = {
787
831
  required: ['id', 'reason'],
788
832
  },
789
833
  },
834
+ // The Final Review's DEMOTE judgement, mirroring reviewer-output.json's
835
+ // kb_demotions: same {id, reason, evidence_files} shape as kb_discards,
836
+ // executed by the same kbWork.apply path. Optional: demoting nothing is
837
+ // the common answer. CONFIRMED to INFERRED only, and only for ids
838
+ // actually offered to this review round -- the basis-unchanged case,
839
+ // not drifted-or-removed basis (freshness staling already handles
840
+ // that). The reason minLength is the engine's evidence bar (kb.mjs
841
+ // KB_MIN_PROMOTE_REASON, enforced in vetKbWork); kept as a literal so
842
+ // this schema module stays dependency-free, pinned equal by
843
+ // test/kb-review-judgements.test.mjs.
844
+ kb_demotions: {
845
+ type: 'array',
846
+ description: 'CONFIRMED entries a re-check during this review shows do not hold -- whether you are now less certain of the claim or have shown it wrong -- demoted back to INFERRED. Not for a drifted or removed basis. Same evidence bar as kb_promotions and kb_discards. An id may appear in only one of kb_promotions, kb_discards and kb_demotions -- the engine refuses it in every list it appears in. The engine makes the demotion calls.',
847
+ items: {
848
+ type: 'object',
849
+ properties: {
850
+ id: {
851
+ type: 'string',
852
+ description: "The entry id, copied verbatim from the 'KNOWLEDGE BANK -- demotion candidates' block in your dispatch prompt. Never invent one.",
853
+ minLength: 1,
854
+ },
855
+ reason: {
856
+ type: 'string',
857
+ description: 'What you re-checked this review that the claim does not hold up against.',
858
+ minLength: 20,
859
+ },
860
+ evidence_files: {
861
+ type: 'array',
862
+ description: 'The repo-relative files you re-checked -- at least one, each a real file in the repo.',
863
+ minItems: 1,
864
+ items: { type: 'string', minLength: 1 },
865
+ },
866
+ },
867
+ required: ['id', 'reason', 'evidence_files'],
868
+ },
869
+ },
790
870
  },
791
871
  required: ['verdict', 'notes'],
792
872
  };
@@ -33,9 +33,13 @@ import { MemberReservationResumeError } from './errors.mjs';
33
33
  * POST {serviceUrl}/api/dolt-push-mutex/{sprintId}/acquire body { pid }
34
34
  * POST {serviceUrl}/api/dolt-push-mutex/{sprintId}/release body { token }
35
35
  *
36
- * The acquire route long-polls -- it does not answer until this sprint
36
+ * The acquire route long-polls -- its body does not complete until this sprint
37
37
  * genuinely owns the mutex (FIFO after every earlier waiter) -- so a resolved
38
- * acquire() means this child holds it and no sibling sprint is pushing.
38
+ * acquire() means this child holds it and no sibling sprint is pushing. The
39
+ * route sends headers at once and heartbeat whitespace while queued, so fetch's
40
+ * 300s headers/body timeouts only fire if the supervisor truly stops answering.
41
+ * A failure during the wait arrives as { error } under a 200, so acquire()
42
+ * rejects on that, and on any payload without a token.
39
43
  *
40
44
  * Implemented INLINE rather than imported from src/supervisor/dolt-mutex.mjs
41
45
  * because runner.js is copied verbatim next to the bundle and loaded via
@@ -43,8 +47,8 @@ import { MemberReservationResumeError } from './errors.mjs';
43
47
  * not resolve in the shipped layout. The { acquire, release } surface is
44
48
  * exactly what doltPushAfter() calls.
45
49
  *
46
- * @param {{ serviceUrl: string, sprintId: string, fetch?: typeof fetch, log?: Function }} opts
47
- * @returns {{ acquire: (sprintId: string, o?: { pid?: number|null }) => Promise<{ token: string|null }>, release: (token: string|null) => Promise<boolean> }}
50
+ * @param {{ serviceUrl: string, sprintId: string, fetch?: typeof fetch, log?: Function, waitLogMs?: number }} opts
51
+ * @returns {{ acquire: (sprintId: string, o?: { pid?: number|null }) => Promise<{ token: string }>, release: (token: string|null) => Promise<boolean> }}
48
52
  */
49
53
  export function createHttpDoltPushMutexClient(opts = {}) {
50
54
  const base = String(opts.serviceUrl || '').replace(/\/+$/, '');
@@ -55,6 +59,7 @@ export function createHttpDoltPushMutexClient(opts = {}) {
55
59
  throw new Error('createHttpDoltPushMutexClient requires a fetch implementation (Node >=18 global fetch or an injected one)');
56
60
  }
57
61
  const log = opts.log ?? (() => {});
62
+ const waitLogMs = opts.waitLogMs > 0 ? opts.waitLogMs : 60_000;
58
63
  const routeFor = (sprintId, action) =>
59
64
  `${base}/api/dolt-push-mutex/${encodeURIComponent(sprintId)}/${action}`;
60
65
 
@@ -75,8 +80,20 @@ export function createHttpDoltPushMutexClient(opts = {}) {
75
80
  async acquire(sprintId, o = {}) {
76
81
  const id = sprintId || boundSprintId;
77
82
  if (!id) throw new Error('[dolt-mutex] acquire requires a sprintId');
78
- const payload = await postJson(routeFor(id, 'acquire'), { pid: o.pid ?? null });
79
- return { token: payload.token ?? null, sprintId: payload.sprintId, expiresAt: payload.expiresAt };
83
+ const startedAt = Date.now();
84
+ const waitLog = setInterval(() => {
85
+ log(`[dolt-mutex] '${id}' still waiting for the dolt push mutex after ${Math.round((Date.now() - startedAt) / 1000)}s`);
86
+ }, waitLogMs);
87
+ waitLog.unref?.();
88
+ let payload;
89
+ try {
90
+ payload = await postJson(routeFor(id, 'acquire'), { pid: o.pid ?? null });
91
+ } finally {
92
+ clearInterval(waitLog);
93
+ }
94
+ if (payload?.error) throw new Error(`[dolt-mutex] ${payload.error}`);
95
+ if (!payload?.token) throw new Error(`[dolt-mutex] acquire for '${id}' returned no token`);
96
+ return { token: payload.token, sprintId: payload.sprintId, expiresAt: payload.expiresAt };
80
97
  },
81
98
  async release(token) {
82
99
  if (token == null) return true;