@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
@@ -64,8 +64,10 @@
64
64
  // <base64 utf16le>` string; SePosixCommands throws
65
65
  // (a true POSIX member has no PowerShell to hand
66
66
  // the script to at all).
67
- // ensureGitExcluded member-call.mjs runRemote's args-file cleanup and
68
- // beads-identity-check.mjs member beads set-up:
67
+ // ensureGitExcluded member-call.mjs runRemote's args-file cleanup,
68
+ // beads-identity-check.mjs member beads set-up and
69
+ // phases/harvest.mjs (the never-committed
70
+ // docs/sprint-analysis-*.md; the only glob entry):
69
71
  // idempotently lists the args dir (.apra-call/) or
70
72
  // a new untracked beads path in
71
73
  // the member repo's git exclude file (resolved via
@@ -42,6 +42,25 @@ export function assertSafeRelativePath(relPath, what = 'path') {
42
42
  return p;
43
43
  }
44
44
 
45
+ /**
46
+ * Validate a git-exclude entry before it is interpolated into a member-bound
47
+ * command string: the same rules as assertSafeRelativePath plus the glob '*'
48
+ * (e.g. 'docs/sprint-analysis-*.md'). '*' is inert in every dialect's use of
49
+ * the entry -- always single-quoted, matched as a fixed string (grep -qxF /
50
+ * PowerShell -notcontains) and appended literally -- so it is allowed here
51
+ * only, never in the file-path primitives.
52
+ * @param {string} entry
53
+ * @param {string} what caller-facing name for the error message
54
+ * @returns {string} the validated entry
55
+ */
56
+ export function assertSafeExcludePattern(entry, what = 'git-exclude entry') {
57
+ const e = String(entry ?? '');
58
+ if (!/^[A-Za-z0-9._/*-]+$/.test(e) || e.startsWith('/') || e.startsWith('-') || e.split('/').includes('..')) {
59
+ throw new Error(`Refusing to build a member command for unsafe ${what} '${entry}' (allowed: work-folder-relative, letters, digits, '.', '_', '-', '/', '*'; no '..' segment, no leading '/' or '-').`);
60
+ }
61
+ return e;
62
+ }
63
+
45
64
  /** Markers printed by every dialect's fileExistsProbe(). */
46
65
  export const FILE_PROBE_PRESENT = 'present';
47
66
  export const FILE_PROBE_ABSENT = 'absent';
@@ -157,6 +176,25 @@ export class SePosixCommands {
157
176
  return { command: this.wrapForMember(this.invoke(descriptor)), descriptor };
158
177
  }
159
178
 
179
+ /**
180
+ * Run the same credential helper but let ONLY its `username=` line leave
181
+ * the member: the filter runs member-side, so the `password=` (token) line
182
+ * never reaches the orchestrator's output. Used by the VCS preflight to
183
+ * check which git username the fleet helper actually carries. The label is
184
+ * validated (unlike readCredentialHelper's back-compat POSIX form): this is
185
+ * a new surface with no byte-identical history to keep. grep exits 1 when
186
+ * there is no username= line; the caller treats that as "no username".
187
+ * @param {string} label
188
+ * @returns {{ command: string, descriptor: string }}
189
+ */
190
+ readCredentialHelperUsername(label) {
191
+ if (!/^[A-Za-z0-9._-]+$/.test(String(label))) {
192
+ throw new Error(`Refusing to build a credential username-read command for unsafe VCS credential label '${label}' (allowed: letters, digits, '.', '_', '-').`);
193
+ }
194
+ const descriptor = this.credentialHelperPath(label);
195
+ return { command: this.wrapForMember(`${this.invoke(descriptor)} | grep '^username='`), descriptor };
196
+ }
197
+
160
198
  /**
161
199
  * Escape a SQL string so it survives as ONE double-quoted argument in the
162
200
  * member's shell. Backticks and `$` are the dangerous characters: bash
@@ -196,7 +234,7 @@ export class SePosixCommands {
196
234
  * @returns {string}
197
235
  */
198
236
  ensureGitExcluded(entry) {
199
- const e = assertSafeRelativePath(entry, 'git-exclude entry');
237
+ const e = assertSafeExcludePattern(entry, 'git-exclude entry');
200
238
  const script = `if excl=$(git rev-parse --git-path info/exclude 2>/dev/null) && [ -n "$excl" ]; then `
201
239
  + `mkdir -p "$(dirname "$excl")" && `
202
240
  + `{ grep -qxF -- '${e}' "$excl" 2>/dev/null || { `
@@ -229,6 +267,21 @@ export class SePosixCommands {
229
267
  return this.wrapForMember(`if [ -e '${p}' ]; then echo ${FILE_PROBE_PRESENT}; else echo ${FILE_PROBE_ABSENT}; fi`);
230
268
  }
231
269
 
270
+ /**
271
+ * Non-interactive read-only probe of the credential ALREADY in place for
272
+ * the member's `origin` remote: `git ls-remote origin HEAD` with
273
+ * GIT_TERMINAL_PROMPT=0 (git never asks on a terminal) and
274
+ * GCM_INTERACTIVE=never (Git Credential Manager never opens a dialog). No
275
+ * credential.helper override -- the point is to test whatever helper the
276
+ * member already uses. Exit 0 = the remote answered with that credential.
277
+ * Env is set as a per-command prefix, so nothing leaks into later commands.
278
+ * Caller: vcs-auth.mjs createVcsAuthPreflightCallback (probe-first branch).
279
+ * @returns {string}
280
+ */
281
+ gitLsRemoteProbe() {
282
+ return this.wrapForMember('GIT_TERMINAL_PROMPT=0 GCM_INTERACTIVE=never git ls-remote origin HEAD');
283
+ }
284
+
232
285
  /**
233
286
  * Create a work-folder-relative file (and its parent directory) when it is
234
287
  * absent; an existing file is never truncated or modified. Idempotent.
@@ -11,7 +11,7 @@
11
11
  // core's src/os/windows.ts wrapPowerShellEncoded(), not a reuse of it: this
12
12
  // package cannot import core.
13
13
 
14
- import { assertSafeRelativePath, assertSafeFileLine, FILE_PROBE_PRESENT, FILE_PROBE_ABSENT } from './se-posix.mjs';
14
+ import { assertSafeRelativePath, assertSafeExcludePattern, assertSafeFileLine, FILE_PROBE_PRESENT, FILE_PROBE_ABSENT } from './se-posix.mjs';
15
15
 
16
16
  /**
17
17
  * PowerShell command primitives for a Windows member.
@@ -110,6 +110,21 @@ export class SeWindowsCommands {
110
110
  return { command: this.wrapForMember(this.invoke(descriptor)), descriptor };
111
111
  }
112
112
 
113
+ /**
114
+ * PowerShell twin of SePosixCommands.readCredentialHelperUsername: runs the
115
+ * helper and passes ONLY its `username=` line through, member-side, so the
116
+ * `password=` (token) line never leaves the member.
117
+ * @param {string} label
118
+ * @returns {{ command: string, descriptor: string }}
119
+ */
120
+ readCredentialHelperUsername(label) {
121
+ if (!/^[A-Za-z0-9._-]+$/.test(String(label))) {
122
+ throw new Error(`Refusing to build a credential username-read command for unsafe VCS credential label '${label}' (allowed: letters, digits, '.', '_', '-').`);
123
+ }
124
+ const descriptor = this.credentialHelperPath(label);
125
+ return { command: this.wrapForMember(`${this.invoke(descriptor)} | Where-Object { $_ -like 'username=*' }`), descriptor };
126
+ }
127
+
113
128
  /**
114
129
  * Escape a SQL string so it survives as ONE double-quoted argument in
115
130
  * PowerShell. A backtick is PowerShell's escape character: a literal
@@ -152,7 +167,7 @@ export class SeWindowsCommands {
152
167
  * @returns {string}
153
168
  */
154
169
  ensureGitExcluded(entry) {
155
- const e = assertSafeRelativePath(entry, 'git-exclude entry');
170
+ const e = assertSafeExcludePattern(entry, 'git-exclude entry');
156
171
  const script = [
157
172
  `$excl = $null`,
158
173
  `try { $out = @(git rev-parse --git-path info/exclude 2>$null); if ($LASTEXITCODE -eq 0 -and $out.Count -gt 0) { $excl = [string]$out[0] } } catch { $excl = $null }`,
@@ -192,6 +207,18 @@ export class SeWindowsCommands {
192
207
  return this.wrapForMember(`if (Test-Path -LiteralPath '${p}') { Write-Output '${FILE_PROBE_PRESENT}' } else { Write-Output '${FILE_PROBE_ABSENT}' }`);
193
208
  }
194
209
 
210
+ /**
211
+ * PowerShell twin of SePosixCommands.gitLsRemoteProbe: sets
212
+ * GIT_TERMINAL_PROMPT=0 and GCM_INTERACTIVE=never in this one-shot
213
+ * process's environment (the envelope is a fresh powershell, so nothing
214
+ * persists), then `git ls-remote origin HEAD` with no credential.helper
215
+ * override. The envelope's $LASTEXITCODE check surfaces git's exit code.
216
+ * @returns {string}
217
+ */
218
+ gitLsRemoteProbe() {
219
+ return this.wrapForMember("$env:GIT_TERMINAL_PROMPT='0'; $env:GCM_INTERACTIVE='never'; git ls-remote origin HEAD");
220
+ }
221
+
195
222
  /**
196
223
  * PowerShell twin of SePosixCommands.ensureFile: create the file (and its
197
224
  * parent directory) when absent; an existing file is never truncated.
@@ -0,0 +1,288 @@
1
+ // Run-scoped "set aside" bookkeeping: the immediate-stall decision and the
2
+ // "Set aside this run" report section.
3
+ //
4
+ // Two things can be set aside for the rest of a sprint run, both recorded on
5
+ // the per-sprint `sprintState`:
6
+ // - beads a doer reported BLOCKED, plus their open 'blocks' dependents:
7
+ // `sprintState.doctorBlockedIds`, a Map id -> { kind, blockedBy, reason,
8
+ // cycle, round } (written by phases/develop.mjs);
9
+ // - beads a doer or reviewer returned NEEDS-DECISION on, plus their open
10
+ // 'blocks' dependents: the same Map, kind 'needs-decision' (the dependents
11
+ // kind 'dependent'), with the decision's ids and the FULL question as the
12
+ // reason (written by decisions.mjs recordPendingDecision);
13
+ // - the deploy itself, when it failed at the deploy.md Permissions pre-step:
14
+ // `sprintState.deploySetAside` = { reason, notes, cycle } (written by
15
+ // phases/deploy.mjs).
16
+ //
17
+ // When nothing is ready and every open in-scope bead is set aside -- or can
18
+ // only close through Integration Test while the deploy is set aside -- no
19
+ // further round or cycle can make progress, so the cycle loop throws the
20
+ // existing StalledSprintError at once instead of after STALL_CYCLE_LIMIT
21
+ // empty cycles. Everything here is pure; runner.js gathers the inputs.
22
+ //
23
+ // A bead a doer reported BLOCKED while it still had an open prerequisite in
24
+ // the sprint is not set aside: it WAITS (`sprintState.waitingIds`, a Map id
25
+ // -> { on, cycle, round }, written by phases/develop.mjs). A waiting bead --
26
+ // or any open bead held behind a prerequisite -- counts as stuck for the
27
+ // stall decision only when one of its prerequisites cannot close in this run
28
+ // (set aside, itself stuck, or, for a waiting bead, outside the sprint
29
+ // scope); while they can still close it keeps the run going. Waits are
30
+ // reported on their own line ("Waited this run"), never as set-asides.
31
+
32
+ import { unmetPrerequisites } from './beads-scope.mjs';
33
+
34
+ /** The pseudo-id naming the set-aside deploy in blockerIds/blockerReasons. */
35
+ export const DEPLOY_SET_ASIDE_ID = 'deploy';
36
+
37
+ /**
38
+ * Every set-aside record of this run, beads first (ordered by first seen,
39
+ * then id), then the deploy. Empty when nothing was set aside.
40
+ *
41
+ * @param {{ doctorBlockedIds?: Map<string, object>, deploySetAside?: object|null }|null|undefined} sprintState
42
+ * @returns {{ id: string, kind: string, blockedBy?: string, reason: string, cycle: number|null, round: number|null, decisionId?: string, decisionBeadId?: string }[]}
43
+ */
44
+ export function collectSetAsideEntries(sprintState) {
45
+ const out = [];
46
+ const blocked = sprintState && sprintState.doctorBlockedIds instanceof Map ? sprintState.doctorBlockedIds : new Map();
47
+ for (const [id, e] of blocked) {
48
+ out.push({
49
+ id,
50
+ kind: e.kind || 'blocked',
51
+ blockedBy: e.blockedBy || id,
52
+ reason: e.reason || 'set aside',
53
+ cycle: Number.isInteger(e.cycle) ? e.cycle : null,
54
+ round: Number.isInteger(e.round) ? e.round : null,
55
+ ...(e.decisionId ? { decisionId: e.decisionId } : {}),
56
+ ...(e.decisionBeadId ? { decisionBeadId: e.decisionBeadId } : {}),
57
+ });
58
+ }
59
+ const kindRank = (k) => (k === 'dependent' ? 1 : 0);
60
+ out.sort((a, b) => (a.cycle ?? 0) - (b.cycle ?? 0) || (a.round ?? 0) - (b.round ?? 0)
61
+ || kindRank(a.kind) - kindRank(b.kind) || a.id.localeCompare(b.id));
62
+ const deploy = sprintState ? sprintState.deploySetAside : null;
63
+ if (deploy) {
64
+ out.push({
65
+ id: DEPLOY_SET_ASIDE_ID,
66
+ kind: 'deploy',
67
+ reason: deploy.notes ? `${deploy.reason} (${deploy.notes})` : String(deploy.reason || 'deploy set aside'),
68
+ cycle: Number.isInteger(deploy.cycle) ? deploy.cycle : null,
69
+ round: null,
70
+ });
71
+ }
72
+ return out;
73
+ }
74
+
75
+ /**
76
+ * "C1 R2" / "C1" / "unknown" for an entry's first-seen point.
77
+ * @param {{ cycle: number|null, round: number|null }} entry
78
+ * @returns {string}
79
+ */
80
+ export function formatFirstSeen(entry) {
81
+ if (!entry || entry.cycle === null || entry.cycle === undefined) return 'unknown';
82
+ return entry.round === null || entry.round === undefined ? `C${entry.cycle}` : `C${entry.cycle} R${entry.round}`;
83
+ }
84
+
85
+ /**
86
+ * The "Set aside this run" report lines (one list item per entry: bead,
87
+ * reason, first seen; a needs-decision entry is marked as such and carries
88
+ * the whole question). Empty array when nothing was set aside, so callers
89
+ * omit the section entirely.
90
+ *
91
+ * @param {ReturnType<typeof collectSetAsideEntries>} entries
92
+ * @returns {string[]}
93
+ */
94
+ export function formatSetAsideItems(entries) {
95
+ return (entries || []).map((e) => `${e.id}: ${e.kind === 'needs-decision' ? '[needs-decision] ' : ''}${e.reason} (first seen ${formatFirstSeen(e)})`);
96
+ }
97
+
98
+ /**
99
+ * The immediate-stall decision. Returns null unless EVERY open in-scope bead
100
+ * at goal priority is set aside: in doctorBlockedIds, stuck behind a
101
+ * prerequisite that cannot close in this run (stuckIds), or -- while the deploy
102
+ * is set aside -- bound to Integration Test (verify-routed, or blocked only by
103
+ * verify-routed beads). With nothing open at all this returns null (that is
104
+ * completion, not a stall; the deploy-failure verdict gate handles it).
105
+ *
106
+ * @param {object} opts
107
+ * @param {string[]} opts.openIds open, non-deferred leaf beads at goal priority
108
+ * @param {string[]} [opts.integBoundIds] open verify-routed beads (close only through Integration Test)
109
+ * @param {string[]} [opts.verifyBlockedIds] open beads whose only unmet blockers are verify-routed
110
+ * @param {Map<string, object>} [opts.doctorBlockedIds]
111
+ * @param {object|null} [opts.deploySetAside]
112
+ * @param {Map<string, string>} [opts.stuckIds] open beads that are not set aside but wait on a
113
+ * prerequisite that cannot close in this run (stuckBehindSetAside), id -> reason
114
+ * @returns {null | { blockerIds: string[], blockerReasons: Record<string, string>, entries: ReturnType<typeof collectSetAsideEntries> }}
115
+ */
116
+ export function evaluateSetAsideStall({ openIds, integBoundIds = [], verifyBlockedIds = [], doctorBlockedIds = new Map(), deploySetAside = null, stuckIds = new Map() }) {
117
+ const integBound = new Set(integBoundIds);
118
+ const verifyBlocked = new Set(verifyBlockedIds);
119
+ const candidates = [...new Set([...(openIds || []), ...integBound])];
120
+ if (candidates.length === 0) return null;
121
+ const blocked = doctorBlockedIds instanceof Map ? doctorBlockedIds : new Map();
122
+ const stuck = stuckIds instanceof Map ? stuckIds : new Map();
123
+ const covered = (id) => blocked.has(id) || stuck.has(id)
124
+ || (!!deploySetAside && (integBound.has(id) || verifyBlocked.has(id)));
125
+ if (!candidates.every(covered)) return null;
126
+
127
+ const entries = collectSetAsideEntries({ doctorBlockedIds: blocked, deploySetAside });
128
+ const blockerReasons = {};
129
+ for (const e of entries) blockerReasons[e.id] = `${e.reason} (first seen ${formatFirstSeen(e)})`;
130
+ for (const id of candidates) {
131
+ if (blockerReasons[id]) continue;
132
+ if (stuck.has(id) && !integBound.has(id)) { blockerReasons[id] = stuck.get(id); continue; }
133
+ blockerReasons[id] = integBound.has(id)
134
+ ? `can only close through Integration Test, which cannot run while the deploy is set aside`
135
+ : `blocked only by bead(s) that can only close through Integration Test, which cannot run while the deploy is set aside`;
136
+ }
137
+ // Set-aside beads first (first-seen order), then the remaining open
138
+ // candidates, then the deploy pseudo-id last.
139
+ const blockerIds = [
140
+ ...entries.filter((e) => e.id !== DEPLOY_SET_ASIDE_ID).map((e) => e.id),
141
+ ...candidates.filter((id) => !blocked.has(id)).sort(),
142
+ ];
143
+ const unique = [...new Set(blockerIds)];
144
+ if (deploySetAside) unique.push(DEPLOY_SET_ASIDE_ID);
145
+ return { blockerIds: unique, blockerReasons, entries };
146
+ }
147
+
148
+ /**
149
+ * The StalledSprintError message for an immediate set-aside stall.
150
+ *
151
+ * @param {{ blockerIds: string[], blockerReasons: Record<string, string> }} stall
152
+ * @param {{ where: string, scope: string }} ctx
153
+ * @returns {string}
154
+ */
155
+ export function formatSetAsideStallMessage(stall, { where, scope }) {
156
+ const blockers = stall.blockerIds.map((id) => `${id} -- ${stall.blockerReasons[id]}`).join('; ');
157
+ return `Sprint stalled (${where}): nothing is ready and every open in-scope bead in scope '${scope}' is set aside ` +
158
+ `for this run, so no further round or cycle can make progress. Set aside: ${blockers}. ` +
159
+ 'Fix these blockers and re-run the sprint. Aborting now rather than burning the remaining cycles.';
160
+ }
161
+
162
+ /**
163
+ * Open beads that are not set aside but cannot run in this sprint because a
164
+ * prerequisite of theirs cannot close: an unmet in-scope prerequisite (an
165
+ * open 'blocks' dependency or an open lower-order lane-mate) that is set
166
+ * aside or itself stuck, transitively; or, for a bead that is WAITING after a
167
+ * BLOCKED report, an open prerequisite outside the sprint scope. A bead
168
+ * whose prerequisites can all still close is not stuck: it keeps the run
169
+ * going.
170
+ *
171
+ * @param {object} opts
172
+ * @param {Array<object>} opts.scopeBeads every in-scope bead, any status
173
+ * @param {Array<object>} [opts.allBeads] every bead, any status
174
+ * @param {Map<string, object>} [opts.doctorBlockedIds]
175
+ * @param {Map<string, object>} [opts.waitingIds]
176
+ * @returns {Map<string, string>} stuck id -> reason
177
+ */
178
+ export function stuckBehindSetAside({ scopeBeads, allBeads = [], doctorBlockedIds = new Map(), waitingIds = new Map() }) {
179
+ const blocked = doctorBlockedIds instanceof Map ? doctorBlockedIds : new Map();
180
+ const waiting = waitingIds instanceof Map ? waitingIds : new Map();
181
+ const out = new Map();
182
+ if (blocked.size === 0 && waiting.size === 0) return out;
183
+ const open = (Array.isArray(scopeBeads) ? scopeBeads : [])
184
+ .filter((b) => b && b.status !== 'closed' && !blocked.has(String(b.id)));
185
+ const pre = new Map(open.map((b) => [String(b.id), unmetPrerequisites(b, { scopeBeads, allBeads })]));
186
+ let changed = true;
187
+ while (changed) {
188
+ changed = false;
189
+ for (const b of open) {
190
+ const id = String(b.id);
191
+ if (out.has(id)) continue;
192
+ const p = pre.get(id);
193
+ const stuckOn = p.inScope.filter((x) => blocked.has(x) || out.has(x));
194
+ if (stuckOn.length > 0) {
195
+ out.set(id, `${waiting.has(id) ? 'waiting' : 'held'} on ${stuckOn.join(', ')}, which cannot close in this run (set aside, or itself waiting on a set-aside bead)`);
196
+ changed = true;
197
+ } else if (waiting.has(id) && p.outOfScope.length > 0) {
198
+ out.set(id, `waiting on ${p.outOfScope.join(', ')}, outside this sprint's scope, which cannot close in this run`);
199
+ changed = true;
200
+ }
201
+ }
202
+ }
203
+ return out;
204
+ }
205
+
206
+ /**
207
+ * Every bead that waited this run (a BLOCKED report while it still had an
208
+ * open in-sprint prerequisite), with the prerequisites it waited on, in
209
+ * first-seen order then id.
210
+ *
211
+ * @param {{ waitingIds?: Map<string, object> }|null|undefined} sprintState
212
+ * @returns {{ id: string, on: string[], cycle: number|null, round: number|null }[]}
213
+ */
214
+ export function collectWaitEntries(sprintState) {
215
+ const waiting = sprintState && sprintState.waitingIds instanceof Map ? sprintState.waitingIds : new Map();
216
+ const out = [];
217
+ for (const [id, e] of waiting) {
218
+ out.push({
219
+ id,
220
+ on: Array.isArray(e.on) ? e.on.map(String) : [],
221
+ cycle: Number.isInteger(e.cycle) ? e.cycle : null,
222
+ round: Number.isInteger(e.round) ? e.round : null,
223
+ });
224
+ }
225
+ out.sort((a, b) => (a.cycle ?? 0) - (b.cycle ?? 0) || (a.round ?? 0) - (b.round ?? 0) || a.id.localeCompare(b.id));
226
+ return out;
227
+ }
228
+
229
+ /**
230
+ * The one-line "Waited this run" summary, or null when nothing waited. Waits
231
+ * are ordering, not blocking, so they never appear under "Set aside this run".
232
+ *
233
+ * @param {ReturnType<typeof collectWaitEntries>} entries
234
+ * @returns {string|null}
235
+ */
236
+ export function formatWaitedLine(entries) {
237
+ const list = entries || [];
238
+ if (list.length === 0) return null;
239
+ return `Waited this run: ${list.map((e) => `${e.id} on ${e.on.join(', ') || '(unknown)'}`).join('; ')}`;
240
+ }
241
+
242
+ /**
243
+ * Wait vs set-aside for the beads a doer reported BLOCKED, decided
244
+ * mechanically from the bead graph (never from the report's notes):
245
+ * - an open prerequisite OUTSIDE the sprint scope -> set aside, naming it
246
+ * (it cannot close in this run);
247
+ * - an open in-scope prerequisite (an open 'blocks' dependency or an open
248
+ * lower-order lane-mate) and no earlier wait -> WAIT on those ids;
249
+ * - otherwise -> set aside (a genuine blocker); a bead that already waited
250
+ * once is set aside now, which bounds the retry to one extra dispatch.
251
+ * Beads already set aside are skipped. `suffix` is appended to the doer's
252
+ * reason when set aside.
253
+ *
254
+ * @param {object} opts
255
+ * @param {string[]} opts.blockedIds
256
+ * @param {Array<object>} opts.scopeBeads every in-scope bead, any status
257
+ * @param {Array<object>} [opts.allBeads] every bead, any status
258
+ * @param {Map<string, object>} [opts.doctorBlockedIds]
259
+ * @param {Map<string, object>} [opts.waitingIds]
260
+ * @returns {{ wait: Array<{ id: string, on: string[] }>, setAside: Array<{ id: string, suffix: string }> }}
261
+ */
262
+ export function classifyBlockedReport({ blockedIds, scopeBeads, allBeads = [], doctorBlockedIds = new Map(), waitingIds = new Map() }) {
263
+ const blocked = doctorBlockedIds instanceof Map ? doctorBlockedIds : new Map();
264
+ const waiting = waitingIds instanceof Map ? waitingIds : new Map();
265
+ const scopeById = new Map((scopeBeads || []).filter(Boolean).map((b) => [String(b.id), b]));
266
+ const wait = [];
267
+ const setAside = [];
268
+ for (const raw of blockedIds || []) {
269
+ const id = String(raw);
270
+ if (blocked.has(id)) continue;
271
+ const bead = scopeById.get(id);
272
+ const pre = bead
273
+ ? unmetPrerequisites(bead, { scopeBeads, allBeads })
274
+ : { inScope: [], outOfScope: [] };
275
+ const priorWait = waiting.get(id);
276
+ if (pre.outOfScope.length > 0) {
277
+ setAside.push({ id, suffix: ` -- open prerequisite(s) outside this sprint's scope, which cannot close in this run: ${pre.outOfScope.join(', ')}` });
278
+ } else if (pre.inScope.length > 0 && !priorWait) {
279
+ wait.push({ id, on: [...pre.inScope] });
280
+ } else {
281
+ setAside.push({
282
+ id,
283
+ suffix: priorWait ? ` (reported BLOCKED again after waiting on ${(priorWait.on || []).join(', ')})` : '',
284
+ });
285
+ }
286
+ }
287
+ return { wait, setAside };
288
+ }
@@ -83,7 +83,7 @@ members run PowerShell, not POSIX.
83
83
  ### Graceful (preferred)
84
84
 
85
85
  ```bash
86
- curl -s -X POST http://localhost:8787/api/shutdown
86
+ curl -s -X POST http://localhost:8787/api/shutdown -H "Content-Type: application/json"
87
87
  ```
88
88
  Returns `{"status":"shutting-down"}` immediately; the process then finishes
89
89
  tearing down every seam (ledger, watchdog, dashboard, etc) and exits on its
@@ -348,6 +348,7 @@ Field names, exactly as the API expects them:
348
348
  | `roleMap` | no | `{"doer":["m1","m2"], "reviewer":["m3"]}`. Leave out `backlog`: the supervisor injects its own backlog member; naming any other member there is a 400. `orchestrator` is the deprecated alias of `backlog` (removed in v0.5). |
349
349
  | `budget` | no | USD cap. |
350
350
  | `phases` | no | `{"regression": "skip"}` skips the regression pass (`"run"` is the default). Any other key or value is a 400. |
351
+ | `kbDemotionLoop` | no | `"on"` (default) or `"off"`: the reviewer KB demotion loop switch, forwarded as `--kb-demotion-loop`. Any other value is a 400. |
351
352
  | `overrideRelaunchGate` | no | bool. See below. |
352
353
 
353
354
  Response has `sprintId`, `pid`, `port` (its own dashboard), `logPath`, and
@@ -379,7 +380,7 @@ Sprint-scoped dashboard (per-role activity, bead DAG, cost, PR link):
379
380
  ## 4. Kill a sprint
380
381
 
381
382
  ```bash
382
- curl -s -X POST http://localhost:8787/api/sprints/<sprintId>/stop
383
+ curl -s -X POST http://localhost:8787/api/sprints/<sprintId>/stop -H "Content-Type: application/json"
383
384
  ```
384
385
 
385
386
  ## Relaunch gate
@@ -9,6 +9,7 @@ import { normalizeRole, validateCredentialStoreName } from './contracts.mjs';
9
9
  import { ROLE_KB_MAINTAINER } from './kb-maintainer.mjs';
10
10
  import { parseExpectedIdentity } from './beads-identity.mjs';
11
11
  import { resolveBacklogRoleAlias } from './backlog-role.mjs';
12
+ import { validateDecisionNotify } from './decision-notify.mjs';
12
13
 
13
14
  // ---------------------------------------------------------------------------
14
15
  // CLI -> runner argument contract
@@ -98,6 +99,10 @@ const KNOWN_ARG_KEYS = new Set([
98
99
  // Never silent: the engine logs it and the sprint report and PR body say
99
100
  // "skipped by launch option". The integration-test phase is unaffected.
100
101
  'skip_regression',
102
+ // Reviewer KB demotion loop switch: 'on' (default when absent) or 'off'.
103
+ // Off: the reviewer is offered no demotion candidates and no kb_demote is
104
+ // issued. Any other value is rejected loudly (never a silent fallback).
105
+ 'kb_demotion_loop',
101
106
  // Multi-streak worklist dispatch mode when a develop round has more ready
102
107
  // streaks than doers. 'resume' (default): per-streak dispatches that resume
103
108
  // the SAME doer session by explicit session id (warm-context carryover,
@@ -162,6 +167,11 @@ const KNOWN_ARG_KEYS = new Set([
162
167
  // verifyBeadsIdentity precondition (beads-identity-check.mjs); absent, the
163
168
  // backlog member's own probed identity becomes the expectation.
164
169
  'expect_beads',
170
+ // Explicit operator-notification config for a pending NEEDS-DECISION
171
+ // (decision-notify.mjs): JSON string or object { message_member, email,
172
+ // dashboard_url, timeout_s }. Absent: each decision logs a loud
173
+ // 'no channel configured' notification failure; the sprint is unaffected.
174
+ 'decision_notify',
165
175
  ]);
166
176
 
167
177
  /**
@@ -502,6 +512,12 @@ export function validateArgs(args) {
502
512
  throw new Error(`[Arg Contract] Invalid doer_worklist_mode "${doerWorklistMode}": must be 'resume' (default) or 'batch'.`);
503
513
  }
504
514
 
515
+ // --- kb_demotion_loop (optional, default 'on') ---------------------------
516
+ const kbDemotionLoop = args.kb_demotion_loop === undefined ? 'on' : args.kb_demotion_loop;
517
+ if (kbDemotionLoop !== 'on' && kbDemotionLoop !== 'off') {
518
+ throw new Error(`[Arg Contract] Invalid kb_demotion_loop ${JSON.stringify(kbDemotionLoop)}: must be 'on' (default) or 'off'.`);
519
+ }
520
+
505
521
  // --- skip_regression (optional, default false) -------------------------
506
522
  const skipRegression = args.skip_regression === undefined ? false : args.skip_regression;
507
523
  if (typeof skipRegression !== 'boolean') {
@@ -558,6 +574,8 @@ export function validateArgs(args) {
558
574
  // --- expect_beads (optional) ------------------------------------------
559
575
  const expectBeads = validateExpectBeads(args.expect_beads);
560
576
 
577
+ const decisionNotify = validateDecisionNotify(args.decision_notify);
578
+
561
579
  // --- ci_gate: NOT WIRED (see the KNOWN_ARG_KEYS note; apra-fleet-dv8i) ---
562
580
  // const ciGate = validateCiGate(args.ci_gate);
563
581
  const ciGate = undefined;
@@ -581,10 +599,12 @@ export function validateArgs(args) {
581
599
  doerWorklistMode,
582
600
  resumeModelSwitch,
583
601
  skipRegression,
602
+ kbDemotionLoop,
584
603
  worklistEffortBudget: args.worklist_effort_budget,
585
604
  usageLimitMaxWaitS: args.usage_limit_max_wait_s,
586
605
  usageLimitMaxReprobes: args.usage_limit_max_reprobes,
587
606
  expectBeads,
607
+ decisionNotify,
588
608
  ciGate,
589
609
  };
590
610
  }
@@ -24,6 +24,7 @@
24
24
  import { createHash } from 'crypto';
25
25
  import { SAFE_TEXT_RE } from './newtask-text.mjs';
26
26
  import { formatDispatchToolCalls } from './dispatch-accounting.mjs';
27
+ import { formatSetAsideItems, formatWaitedLine } from './set-aside.mjs';
27
28
 
28
29
  // ---------------------------------------------------------------------------
29
30
  // PR body/title text sanitization. The final reviewer's verdict notes are LLM
@@ -153,6 +154,12 @@ export function buildAnalysisText({
153
154
  // still not in a pushed bible commit. Rendered as a loud section only
154
155
  // when any are, so a sprint whose bible was published reads as before.
155
156
  kbBibleUnpublished = null,
157
+ // The run's set-aside records (./set-aside.mjs collectSetAsideEntries):
158
+ // rendered as a "Set aside this run" section, omitted when empty.
159
+ setAside = [],
160
+ // The run's wait records (./set-aside.mjs collectWaitEntries): one
161
+ // "Waited this run" line, omitted when nothing waited.
162
+ waited = [],
156
163
  }) {
157
164
  // The once-per-sprint Regression Test phase runs after the final verdict
158
165
  // and never gates it. Its failures are filed as parent-less carry-over
@@ -196,6 +203,8 @@ export function buildAnalysisText({
196
203
  ? `Integration test failures (${integFailures.length}): ` + integFailures.map((f) => `C${f.cycle}: ${f.notes} (bugs filed: ${(f.bugsFiled || []).join(', ') || 'none'})`).join(' | ')
197
204
  : 'No integration test failures recorded this sprint.',
198
205
  '',
206
+ ...setAsideSectionLines(setAside),
207
+ ...(formatWaitedLine(waited) ? [formatWaitedLine(waited), ''] : []),
199
208
  '## Reviewer-proposed newTask rejections',
200
209
  '',
201
210
  rejectedNewTasks.length > 0
@@ -224,6 +233,18 @@ export function buildAnalysisText({
224
233
  return lines.join('\n');
225
234
  }
226
235
 
236
+ /**
237
+ * The "Set aside this run" analysis section (bead, reason, first seen), each
238
+ * line followed by a blank separator; empty when nothing was set aside.
239
+ * @param {object[]} setAside
240
+ * @returns {string[]}
241
+ */
242
+ function setAsideSectionLines(setAside) {
243
+ const items = formatSetAsideItems(setAside);
244
+ if (items.length === 0) return [];
245
+ return ['## Set aside this run', '', ...items.map((i) => `- ${i}`), ''];
246
+ }
247
+
227
248
  /**
228
249
  * The analysis section for KB confirmations that never reached a pushed bible
229
250
  * commit (the push kept failing, the maintainer stayed busy or unreachable, or
@@ -151,6 +151,15 @@ export async function resolveSettleShellWith({ fleetApi, member, log = () => {}
151
151
  * (member-init-probe.mjs MemberInitRecord): verified status, fleetMcp, tool
152
152
  * presence, CONFIRMED count and code index state. Filled once at sprint init
153
153
  * and read by the KNOWLEDGE BANK injection and the viewer.
154
+ *
155
+ * `pendingDecisions` holds every NEEDS-DECISION request a doer or reviewer
156
+ * raised this run and that is still unanswered: Map decisionId -> {
157
+ * decisionId, beadId, question, options: [{ id, text }], recommendation,
158
+ * decisionBeadId, raisedBy, cycle, round, notification: {} }, all text kept
159
+ * whole. Attached lazily by decisions.mjs recordPendingDecision (the same
160
+ * lazily-attached, sprint-lifetime pattern as `doctorBlockedIds`; this module
161
+ * deliberately constructs no Map), which also sets the bead aside on
162
+ * `doctorBlockedIds` (kind 'needs-decision').
154
163
  */
155
164
  export function createSprintState({ callTool, log = () => {}, createFleetApi } = {}) {
156
165
  const active = typeof callTool === 'function';