@apralabs/apra-fleet 0.3.3 → 0.3.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 (150) hide show
  1. package/README.md +8 -1
  2. package/dist/agents/_shared/GRAPH-SEMANTICS.md +47 -0
  3. package/dist/agents/ci-watcher.md +43 -0
  4. package/dist/agents/deployer.md +51 -28
  5. package/dist/agents/doer.md +160 -31
  6. package/dist/agents/harvester.md +81 -6
  7. package/dist/agents/integ-test-runner.md +147 -17
  8. package/dist/agents/plan-reviewer.md +76 -9
  9. package/dist/agents/planner.md +80 -15
  10. package/dist/agents/reviewer.md +90 -13
  11. package/dist/agents/schemas/ci-watcher-input.json +26 -0
  12. package/dist/agents/schemas/ci-watcher-output.json +18 -0
  13. package/dist/agents/schemas/deployer-input.json +19 -0
  14. package/dist/agents/schemas/deployer-output.json +17 -0
  15. package/dist/agents/schemas/doer-input.json +25 -0
  16. package/dist/agents/schemas/doer-output.json +22 -0
  17. package/dist/agents/schemas/harvester-input.json +31 -0
  18. package/dist/agents/schemas/harvester-output.json +18 -0
  19. package/dist/agents/schemas/integ-test-runner-input.json +20 -0
  20. package/dist/agents/schemas/integ-test-runner-output.json +27 -0
  21. package/dist/agents/schemas/plan-reviewer-input.json +15 -0
  22. package/dist/agents/schemas/plan-reviewer-output.json +30 -0
  23. package/dist/agents/schemas/reviewer-input.json +25 -0
  24. package/dist/agents/schemas/reviewer-output.json +34 -0
  25. package/dist/cli/config.d.ts +9 -3
  26. package/dist/cli/config.d.ts.map +1 -1
  27. package/dist/cli/config.js +21 -8
  28. package/dist/cli/config.js.map +1 -1
  29. package/dist/cli/install.d.ts +10 -0
  30. package/dist/cli/install.d.ts.map +1 -1
  31. package/dist/cli/install.js +74 -23
  32. package/dist/cli/install.js.map +1 -1
  33. package/dist/cli/uninstall.d.ts.map +1 -1
  34. package/dist/cli/uninstall.js +19 -0
  35. package/dist/cli/uninstall.js.map +1 -1
  36. package/dist/cli/watch.d.ts +8 -0
  37. package/dist/cli/watch.d.ts.map +1 -0
  38. package/dist/cli/watch.js +536 -0
  39. package/dist/cli/watch.js.map +1 -0
  40. package/dist/index.js +10 -4
  41. package/dist/index.js.map +1 -1
  42. package/dist/os/linux.d.ts +1 -0
  43. package/dist/os/linux.d.ts.map +1 -1
  44. package/dist/os/linux.js +4 -0
  45. package/dist/os/linux.js.map +1 -1
  46. package/dist/os/macos.d.ts +1 -0
  47. package/dist/os/macos.d.ts.map +1 -1
  48. package/dist/os/macos.js +5 -0
  49. package/dist/os/macos.js.map +1 -1
  50. package/dist/os/os-commands.d.ts +2 -0
  51. package/dist/os/os-commands.d.ts.map +1 -1
  52. package/dist/os/windows.d.ts +1 -0
  53. package/dist/os/windows.d.ts.map +1 -1
  54. package/dist/os/windows.js +7 -0
  55. package/dist/os/windows.js.map +1 -1
  56. package/dist/providers/claude.d.ts.map +1 -1
  57. package/dist/providers/claude.js +10 -6
  58. package/dist/providers/claude.js.map +1 -1
  59. package/dist/services/agent-provisioner.d.ts +39 -0
  60. package/dist/services/agent-provisioner.d.ts.map +1 -0
  61. package/dist/services/agent-provisioner.js +130 -0
  62. package/dist/services/agent-provisioner.js.map +1 -0
  63. package/dist/services/sftp.d.ts +15 -0
  64. package/dist/services/sftp.d.ts.map +1 -1
  65. package/dist/services/sftp.js +34 -0
  66. package/dist/services/sftp.js.map +1 -1
  67. package/dist/services/ssh.d.ts +13 -0
  68. package/dist/services/ssh.d.ts.map +1 -1
  69. package/dist/services/ssh.js +46 -0
  70. package/dist/services/ssh.js.map +1 -1
  71. package/dist/services/stall/log-path-resolver.d.ts +8 -0
  72. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  73. package/dist/services/stall/log-path-resolver.js +12 -4
  74. package/dist/services/stall/log-path-resolver.js.map +1 -1
  75. package/dist/services/statusline.d.ts.map +1 -1
  76. package/dist/services/statusline.js +16 -4
  77. package/dist/services/statusline.js.map +1 -1
  78. package/dist/services/user-config.d.ts +14 -0
  79. package/dist/services/user-config.d.ts.map +1 -1
  80. package/dist/services/user-config.js +22 -0
  81. package/dist/services/user-config.js.map +1 -1
  82. package/dist/services/watch/fleet-log.d.ts +34 -0
  83. package/dist/services/watch/fleet-log.d.ts.map +1 -0
  84. package/dist/services/watch/fleet-log.js +168 -0
  85. package/dist/services/watch/fleet-log.js.map +1 -0
  86. package/dist/services/watch/project-resolver.d.ts +51 -0
  87. package/dist/services/watch/project-resolver.d.ts.map +1 -0
  88. package/dist/services/watch/project-resolver.js +104 -0
  89. package/dist/services/watch/project-resolver.js.map +1 -0
  90. package/dist/services/watch/transcript-formatter.d.ts +26 -0
  91. package/dist/services/watch/transcript-formatter.d.ts.map +1 -0
  92. package/dist/services/watch/transcript-formatter.js +210 -0
  93. package/dist/services/watch/transcript-formatter.js.map +1 -0
  94. package/dist/skills/auto-sprint-args/SKILL.md +88 -0
  95. package/dist/skills/pm/SKILL.md +101 -42
  96. package/dist/skills/pm/beads.md +27 -22
  97. package/dist/skills/pm/cost.md +6 -4
  98. package/dist/skills/pm/doer-reviewer-loop.md +62 -62
  99. package/dist/skills/pm/fleet-addendum.md +11 -5
  100. package/dist/skills/pm/simple-sprint.md +6 -5
  101. package/dist/skills/pm/sprint.md +53 -37
  102. package/dist/tools/check-status.d.ts.map +1 -1
  103. package/dist/tools/check-status.js +47 -29
  104. package/dist/tools/check-status.js.map +1 -1
  105. package/dist/tools/cloud-control.d.ts +2 -2
  106. package/dist/tools/compose-permissions.d.ts +6 -3
  107. package/dist/tools/compose-permissions.d.ts.map +1 -1
  108. package/dist/tools/compose-permissions.js +63 -5
  109. package/dist/tools/compose-permissions.js.map +1 -1
  110. package/dist/tools/execute-command.d.ts.map +1 -1
  111. package/dist/tools/execute-command.js +18 -2
  112. package/dist/tools/execute-command.js.map +1 -1
  113. package/dist/tools/execute-prompt.d.ts +1 -0
  114. package/dist/tools/execute-prompt.d.ts.map +1 -1
  115. package/dist/tools/execute-prompt.js +38 -1
  116. package/dist/tools/execute-prompt.js.map +1 -1
  117. package/dist/tools/list-members.d.ts +3 -0
  118. package/dist/tools/list-members.d.ts.map +1 -1
  119. package/dist/tools/list-members.js +30 -15
  120. package/dist/tools/list-members.js.map +1 -1
  121. package/dist/tools/register-member.d.ts +15 -9
  122. package/dist/tools/register-member.d.ts.map +1 -1
  123. package/dist/tools/register-member.js +35 -0
  124. package/dist/tools/register-member.js.map +1 -1
  125. package/dist/tools/update-member.d.ts +15 -9
  126. package/dist/tools/update-member.d.ts.map +1 -1
  127. package/dist/tools/update-member.js +40 -0
  128. package/dist/tools/update-member.js.map +1 -1
  129. package/dist/types.d.ts +2 -0
  130. package/dist/types.d.ts.map +1 -1
  131. package/dist/utils/agent-helpers.d.ts +8 -0
  132. package/dist/utils/agent-helpers.d.ts.map +1 -1
  133. package/dist/utils/agent-helpers.js +21 -0
  134. package/dist/utils/agent-helpers.js.map +1 -1
  135. package/dist/utils/skill-matrix.d.ts +19 -0
  136. package/dist/utils/skill-matrix.d.ts.map +1 -0
  137. package/dist/utils/skill-matrix.js +47 -0
  138. package/dist/utils/skill-matrix.js.map +1 -0
  139. package/dist/workflows/auto-sprint.js +1213 -208
  140. package/package.json +3 -2
  141. package/skills/fleet/permissions.md +60 -5
  142. package/skills/fleet/profiles/tag-devops.json +4 -0
  143. package/skills/fleet/profiles/tag-gpu.json +4 -0
  144. package/skills/fleet/skill-matrix.md +15 -8
  145. package/version.json +1 -1
  146. package/dist/services/stall/log-path-resolver.test.d.ts +0 -2
  147. package/dist/services/stall/log-path-resolver.test.d.ts.map +0 -1
  148. package/dist/services/stall/log-path-resolver.test.js +0 -76
  149. package/dist/services/stall/log-path-resolver.test.js.map +0 -1
  150. package/dist/skills/pm/tpl-progress.json +0 -35
@@ -1,16 +1,6 @@
1
1
  export const meta = {
2
2
  name: 'auto-sprint',
3
- description: `Multi-cycle sprint workflow: plan -> develop -> test -> harvest.
4
-
5
- args must be a JSON object (not a string) with these fields:
6
- issues REQUIRED. Array of beads issue IDs (sprint roots), e.g. ["BD-1","BD-2"].
7
- branch REQUIRED. Sprint branch name, e.g. "feat/auth". Created if it does not exist.
8
- goal Optional. Exit when no open issues at or above this priority. "P1" | "P1/P2" | "P1/P2/P3". Default: "P1/P2".
9
- max_cycles Optional. Hard cycle ceiling. Default: 5.
10
- base_branch Optional. PR target branch. Default: "main".
11
- requirementsFile Optional. Path to an additional context file for the planner.
12
-
13
- Minimal invocation example: { "issues": ["BD-7"], "branch": "feat/my-feature" }`,
3
+ description: `Multi-cycle sprint workflow: plan -> develop -> test -> harvest. Pass args as a JSON object with required "issues" (array of beads IDs) and "branch"; invoke the auto-sprint-args skill for the full argument contract.`,
14
4
  phases: [
15
5
  { title: 'Plan' },
16
6
  { title: 'Develop' },
@@ -27,8 +17,9 @@ Minimal invocation example: { "issues": ["BD-7"], "branch": "feat/my-feature" }`
27
17
  // plan-reviewer -- validates DAG: coverage, task size, acceptance criteria
28
18
  // doer -- works bd-ready tasks (impl and test-dev), VERIFY checkpoint
29
19
  // reviewer -- reviews doer output, can reopen tasks
30
- // deployer -- follows deploy.md + integ-test-playbook.md (setup/reset/teardown)
31
- // integ-test-runner -- executes tests, closes features, files bugs/enhancements
20
+ // deployer -- follows deploy.md ONLY (deploy + smoke test); never the playbook
21
+ // integ-test-runner -- owns integ-test-playbook.md end to end (setup/reset/teardown),
22
+ // executes tests, closes features, files bugs/enhancements
32
23
  // ci-watcher -- polls CI; creates beads task if not configured
33
24
  // harvester -- docs, CHANGELOG, token summary, PR
34
25
  //
@@ -42,6 +33,7 @@ Minimal invocation example: { "issues": ["BD-7"], "branch": "feat/my-feature" }`
42
33
  // max_cycles -- hard ceiling on sprint cycles (default: 5)
43
34
  // requirementsFile -- optional context file for the planner (default: none)
44
35
  // base_branch -- PR target (default: "main")
36
+ // skip_dolt_push -- skip the Harvest "bd dolt push" when true (default: false)
45
37
 
46
38
  // NOTE: the arg-parsing block below is intentionally duplicated from lib/parse-sprint-args.mjs,
47
39
  // which exists only for unit testing (workflow scripts cannot import arbitrary files).
@@ -70,6 +62,16 @@ if (args) {
70
62
  }
71
63
  }
72
64
 
65
+ // PREFLIGHT (arg schema) -- validate the parsed opts against the invocation contract
66
+ // before doing any work. Fails loudly with the expected shape so a malformed launch
67
+ // (e.g. args passed as a JSON string, missing issues, bad goal) is caught immediately
68
+ // rather than surfacing as a confusing mid-run error. See docs/auto-sprint-ruggedization.md.
69
+ const _argCheck = validateSprintArgs(opts, args);
70
+ if (!_argCheck.ok) {
71
+ log(`ERROR: ${_argCheck.error} -- ${_argCheck.detail}`);
72
+ return { error: _argCheck.error };
73
+ }
74
+
73
75
  let branch = opts.branch || ''; // empty = auto-detect in setup; reassigned after setup resolves
74
76
  const rawIssues = opts.issues || [];
75
77
  const rootIds = Array.isArray(rawIssues) ? rawIssues : [rawIssues];
@@ -97,11 +99,13 @@ const TIER_CHEAP = 'cheap';
97
99
  const TIER_STANDARD = 'standard';
98
100
  const TIER_PREMIUM = 'premium';
99
101
 
100
- // Claude model IDs -- change here only, nowhere else in this file.
102
+ // Bare model-family aliases -- agent()/CLI dispatch resolves these to the
103
+ // current generation automatically, so this never goes stale as Anthropic
104
+ // ships new models. Do not pin to a dated model ID here.
101
105
  const TIER_TO_MODEL = {
102
- [TIER_CHEAP]: 'claude-haiku-4-5',
103
- [TIER_STANDARD]: 'claude-sonnet-4-6',
104
- [TIER_PREMIUM]: 'claude-opus-4-8',
106
+ [TIER_CHEAP]: 'haiku',
107
+ [TIER_STANDARD]: 'sonnet',
108
+ [TIER_PREMIUM]: 'opus',
105
109
  };
106
110
 
107
111
  // Legacy aliases kept so existing dispatch call-sites (model: MODEL_OPUS etc.) are unchanged.
@@ -110,33 +114,23 @@ const MODEL_SONNET = TIER_STANDARD;
110
114
  const MODEL_HAIKU = TIER_CHEAP;
111
115
 
112
116
  // ------------------------------------------------------------------ schemas
113
-
114
- const REVIEW_SCHEMA = {
115
- type: 'object', required: ['verdict', 'notes'],
116
- properties: {
117
- verdict: { type: 'string', enum: ['APPROVED', 'CHANGES NEEDED'] },
118
- notes: { type: 'string' },
119
- },
120
- };
121
-
122
- const PLAN_REVIEW_SCHEMA = {
123
- type: 'object', required: ['verdict', 'notes', 'taskAssignments'],
124
- properties: {
125
- verdict: { type: 'string', enum: ['APPROVED', 'CHANGES NEEDED'] },
126
- notes: { type: 'string' },
127
- taskAssignments: {
128
- type: 'array',
129
- items: {
130
- type: 'object', required: ['id', 'bucket', 'model'],
131
- properties: {
132
- id: { type: 'string' },
133
- bucket: { type: 'string', enum: ['S', 'M', 'L'] },
134
- model: { type: 'string' },
135
- },
136
- },
137
- },
138
- },
139
- };
117
+ //
118
+ // NOTE: REVIEW_SCHEMA, PLAN_REVIEW_SCHEMA, DOER_STATUS_SCHEMA,
119
+ // INTEG_RUN_SCHEMA, CI_SCHEMA, and HARVEST_SCHEMA (the role-contract schemas)
120
+ // are declared just below PURE_FUNCTIONS_END, not here -- they are loaded
121
+ // from agents/schemas/<role>.json via require()/fs.readFileSync(), which is
122
+ // I/O and therefore must NOT live inside the PURE_FUNCTIONS_BEGIN/END block
123
+ // (that block is extracted verbatim via `new Function(...)` by
124
+ // test/sprint-cost.test.mjs and by install.mjs's cost.js generation step,
125
+ // both of which require it to be self-contained pure data/functions with no
126
+ // require() and no filesystem access). See the role-schemas section right
127
+ // after the end-of-pure-functions marker below for the loader and the
128
+ // apra-fleet-unw.21 rationale.
129
+ //
130
+ // The schemas below (SHELL_OUTPUTS_SCHEMA, SETUP_SCHEMA,
131
+ // BEADS_BLOCKERS_SCHEMA, READY_STREAKS_SCHEMA) are workflow-private, not role
132
+ // contracts -- they are plain data literals with no I/O, so they safely stay
133
+ // inline here.
140
134
 
141
135
  const SHELL_OUTPUTS_SCHEMA = {
142
136
  type: 'object', required: ['outputs'],
@@ -145,22 +139,6 @@ const SHELL_OUTPUTS_SCHEMA = {
145
139
  },
146
140
  };
147
141
 
148
- const DOER_STATUS_SCHEMA = {
149
- type: 'object', required: ['status'],
150
- properties: {
151
- status: { type: 'string', enum: ['VERIFY'] },
152
- notes: { type: 'string' },
153
- },
154
- };
155
-
156
- const HARVEST_SCHEMA = {
157
- type: 'object', required: ['status'],
158
- properties: {
159
- status: { type: 'string', enum: ['OK', 'FAILED'] },
160
- notes: { type: 'string' },
161
- },
162
- };
163
-
164
142
  const SETUP_SCHEMA = {
165
143
  type: 'object', required: ['repo', 'branch', 'deployMdExists', 'playbookExists', 'startedAt'],
166
144
  properties: {
@@ -201,22 +179,8 @@ const READY_STREAKS_SCHEMA = {
201
179
  },
202
180
  };
203
181
 
204
- const CI_SCHEMA = {
205
- type: 'object', required: ['status'],
206
- properties: {
207
- status: { type: 'string', enum: ['green', 'red', 'not_configured', 'pending'] },
208
- notes: { type: 'string' },
209
- },
210
- };
211
-
212
- const INTEG_RUN_SCHEMA = {
213
- type: 'object', required: ['featuresClosed', 'issuesCreated', 'summary'],
214
- properties: {
215
- featuresClosed: { type: 'number' },
216
- issuesCreated: { type: 'number' },
217
- summary: { type: 'string' },
218
- },
219
- };
182
+ // CI_SCHEMA and INTEG_RUN_SCHEMA are role contracts and are declared, along
183
+ // with the other role-contract schemas, just below PURE_FUNCTIONS_END.
220
184
 
221
185
  // Returned by the resume-check agent at the top of every cycle.
222
186
  // planDone -- true if the sprint goal already has children AND every feature has at
@@ -314,6 +278,19 @@ const DEFAULT_CALIBRATION = {
314
278
  standard: 80000,
315
279
  premium: 150000,
316
280
  },
281
+ context_limits: {
282
+ _doc: 'Doer context-window budgeting. Used to predict whether a ready-task streak will fit in the model usable context before autocompact/session-limit truncation, and to split streaks proactively. Keyed by tier.',
283
+ model_context_tokens: { _doc: 'Total context window per tier (tokens).', cheap: 200000, standard: 200000, premium: 200000 },
284
+ autocompact_headroom_fraction: 0.72, // usable fraction of the window before autocompact/limit risk (observed doer failures at ~100K+ on Sonnet -> stay well under)
285
+ base_prompt_tokens: 9000, // fixed doer system+task prompt + repo orientation
286
+ per_task_input_overhead_tokens: 3500,// per-task prompt + accumulated tool-result growth
287
+ output_expansion_factor: 1.0, // multiplier on estimated output tokens counted against context
288
+ },
289
+ parallelism: {
290
+ _doc: 'Doer concurrency (EXPERIMENTAL -- default 1 = proven serial path). When max_doers>1, independent bd-ready tasks are fanned out into isolated git worktrees, worked by one doer each in parallel, then merged back into the sprint branch sequentially with a conflict->re-queue fallback. This path is NOT yet default: on s10 (win32) it hit cross-platform worktree fragility (worktree "already exists" leak on re-create, and worktree-branch merges landing nothing -> 0 commits). Until that is hardened and validated on all runner OSes, max_doers stays 1 so sprints use the pre-parallelism serial path (which commits doers directly on the sprint branch, no worktree/merge machinery). Set >1 to opt into the experimental parallel path. Width is also capped by the harness concurrency limit and the number of ready tasks. Project-agnostic: no assumptions about language, layout, or task shape.',
291
+ max_doers: 1,
292
+ worktree_root: '.auto-sprint/wt',
293
+ },
317
294
  historical: {
318
295
  _doc: 'Written by harvester after each sprint. Contains actual per-role output token averages from sprint-log JSONL files. Used by auto-sprint.js computeSprintQuote() to improve future estimates. Do not edit manually.',
319
296
  max_sprints_in_sample: 5,
@@ -601,17 +578,45 @@ function parseBlockers(outputs, rootCount, openListIdx, threshold, rootIds) {
601
578
  return { count: ids.length, ids };
602
579
  }
603
580
 
604
- // parseReadyStreaks: contract {totalCount, streaks[]} grouping ready tasks in the
605
- // subtree by model, ordered by min priority.
581
+ // parseReadyStreaks: contract {totalCount, streaks[], extractFailed} grouping ready
582
+ // tasks in the subtree by model, ordered by min priority.
606
583
  // readyListIdx is the explicit index of the ready-tasks JSON command in outputs[].
607
- function parseReadyStreaks(outputs, rootCount, readyListIdx, defaultModel) {
608
- if (!Array.isArray(outputs) || outputs.length < readyListIdx + 1) return { totalCount: 0, streaks: [] };
584
+ // rootIds (optional): sprint-root ids to exclude from dispatchable leaf work.
585
+ //
586
+ // extractFailed distinguishes "the extractor genuinely found zero ready tasks" from
587
+ // "the extraction itself failed" (JSON.parse threw, or the dispatch agent returned
588
+ // something that isn't the extracted array at all). Both used to collapse to the same
589
+ // {totalCount: 0}, which let a transient dispatch/parse hiccup masquerade as a
590
+ // confirmed deadlock and hard-abort the whole sprint (apra-fleet e2e s10, 2026-07-17,
591
+ // run 29605783512) -- see the caller in the Develop loop, which now retries once on
592
+ // extractFailed instead of trusting a single failed read as proof of zero ready work.
593
+ // The extractor emits the string 'null' (not '[]') on its own catch precisely so this
594
+ // function can tell the two cases apart; see getReadyStreaks/countBeadsBlockers.
595
+ function parseReadyStreaks(outputs, rootCount, readyListIdx, defaultModel, rootIds) {
596
+ if (!Array.isArray(outputs) || outputs.length < readyListIdx + 1) return { totalCount: 0, streaks: [], extractFailed: true };
609
597
  const subtree = collectSubtreeIds(outputs, rootCount);
610
598
  let readyTasks = [];
599
+ let extractFailed = false;
611
600
  try {
612
601
  const all = JSON.parse(outputs[readyListIdx]);
613
- readyTasks = Array.isArray(all) ? all.filter(t => subtree.has(t.id)) : [];
614
- } catch { readyTasks = []; }
602
+ if (Array.isArray(all)) {
603
+ readyTasks = all.filter(t => subtree.has(t.id));
604
+ } else {
605
+ readyTasks = [];
606
+ extractFailed = true; // valid JSON but not the expected array shape (e.g. the 'null' failure sentinel)
607
+ }
608
+ } catch { readyTasks = []; extractFailed = true; }
609
+
610
+ // Dispatch-time leaf filter (GRAPH-SEMANTICS.md): decomposed items are GROUPED via
611
+ // --parent, never dep-blocked by their own children, so a sprint root or a bead with
612
+ // children can itself show up as "ready". It must not be dispatched as leaf work --
613
+ // exclude the sprint roots and any bead that has dotted-ID descendants in the subtree
614
+ // (beads expresses parent->child as <parent>.<n> ids). This is the dispatch-time
615
+ // filter the canonical doc prescribes instead of parent->child blocks edges.
616
+ const rootSet = new Set(Array.isArray(rootIds) ? rootIds : []);
617
+ const subtreeArr = Array.from(subtree);
618
+ readyTasks = readyTasks.filter(t =>
619
+ !rootSet.has(t.id) && !subtreeArr.some(id => id.indexOf(t.id + '.') === 0));
615
620
 
616
621
  // Hoist the known-tiers set and reverse map outside the loop (constant across tasks).
617
622
  const KNOWN_TIERS = new Set([TIER_CHEAP, TIER_STANDARD, TIER_PREMIUM]);
@@ -644,7 +649,7 @@ function parseReadyStreaks(outputs, rootCount, readyListIdx, defaultModel) {
644
649
  _min: Math.min(...tasks.map(x => x.priority)),
645
650
  })).sort((a, b) => a._min - b._min).map(({ model, ids }) => ({ model, ids }));
646
651
 
647
- return { totalCount: readyTasks.length, streaks };
652
+ return { totalCount: readyTasks.length, streaks, extractFailed };
648
653
  }
649
654
 
650
655
  // parseCycleState: contract {planDone, inProgressIds}. planDone is true for a
@@ -950,8 +955,459 @@ function truncateStreakToCeiling(streakIds, bucketById, calibration, tier) {
950
955
  return kept;
951
956
  }
952
957
 
958
+ // validateSprintArgs: validates the parsed sprint opts. Returns { ok:true } or
959
+ // { ok:false, error, detail }. Pure -- no I/O. Enforces the invocation contract
960
+ // in meta.description.
961
+ function validateSprintArgs(opts, rawArgs) {
962
+ const expected = 'Expected a JSON OBJECT, e.g. {"issues":["BD-7"],"branch":"feat/x"}';
963
+ if (opts == null || typeof opts !== 'object' || Array.isArray(opts)) {
964
+ return { ok: false, error: 'invalid args: not an object', detail: `${expected}. Received: ${JSON.stringify(rawArgs)}` };
965
+ }
966
+ const issues = opts.issues;
967
+ if (!Array.isArray(issues) || issues.length === 0) {
968
+ return { ok: false, error: 'invalid args: issues', detail: `"issues" must be a non-empty array of beads IDs. ${expected}. Received: ${JSON.stringify(rawArgs)}` };
969
+ }
970
+ if (!issues.every(s => typeof s === 'string' && s.trim().length > 0)) {
971
+ return { ok: false, error: 'invalid args: issues entries', detail: 'every entry in "issues" must be a non-empty string beads ID' };
972
+ }
973
+ if (opts.branch != null && (typeof opts.branch !== 'string' || opts.branch.trim() === '')) {
974
+ return { ok: false, error: 'invalid args: branch', detail: '"branch" must be a non-empty string when provided' };
975
+ }
976
+ if (opts.goal != null && !['P1', 'P1/P2', 'P1/P2/P3'].includes(opts.goal)) {
977
+ return { ok: false, error: 'invalid args: goal', detail: '"goal" must be one of "P1" | "P1/P2" | "P1/P2/P3"' };
978
+ }
979
+ if (opts.max_cycles != null && !(Number.isInteger(Number(opts.max_cycles)) && Number(opts.max_cycles) > 0)) {
980
+ return { ok: false, error: 'invalid args: max_cycles', detail: '"max_cycles" must be a positive integer' };
981
+ }
982
+ if (opts.base_branch != null && (typeof opts.base_branch !== 'string' || opts.base_branch.trim() === '')) {
983
+ return { ok: false, error: 'invalid args: base_branch', detail: '"base_branch" must be a non-empty string when provided' };
984
+ }
985
+ if (opts.skip_dolt_push != null && typeof opts.skip_dolt_push !== 'boolean') {
986
+ return { ok: false, error: 'invalid args: skip_dolt_push', detail: '"skip_dolt_push" must be a boolean when provided' };
987
+ }
988
+ return { ok: true };
989
+ }
990
+
991
+ // assertCalibrationComplete: walks every numeric calibration path the cost/context
992
+ // arithmetic reads and heals any missing or NaN value from defaults. Operates on a
993
+ // deep-enough clone so neither the input calibration nor the defaults are mutated.
994
+ // Returns { calibration, healed } where healed is an array of human-readable strings
995
+ // describing each healed path (caller WARNs per entry).
996
+ function assertCalibrationComplete(calibration, defaults) {
997
+ const getPath = (obj, path) => path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
998
+ const setPath = (obj, path, val) => {
999
+ const keys = path.split('.');
1000
+ let cur = obj;
1001
+ for (let i = 0; i < keys.length - 1; i++) {
1002
+ const k = keys[i];
1003
+ // Clone-on-write so the caller's nested objects are never mutated.
1004
+ cur[k] = Object.assign({}, cur[k]);
1005
+ cur = cur[k];
1006
+ }
1007
+ cur[keys[keys.length - 1]] = val;
1008
+ };
1009
+ const requiredPaths = [
1010
+ 'model_prices_per_1m_output_tokens.cheap',
1011
+ 'model_prices_per_1m_output_tokens.standard',
1012
+ 'model_prices_per_1m_output_tokens.premium',
1013
+ 'complexity_buckets.S.doer_tokens',
1014
+ 'complexity_buckets.M.doer_tokens',
1015
+ 'complexity_buckets.L.doer_tokens',
1016
+ 'reviewer_ratio.value',
1017
+ 'cycle_assumptions.optimistic',
1018
+ 'cycle_assumptions.expected',
1019
+ 'cycle_assumptions.pessimistic',
1020
+ 'fixed_overhead_tokens.setup',
1021
+ 'fixed_overhead_tokens.planner',
1022
+ 'fixed_overhead_tokens.plan_reviewer',
1023
+ 'fixed_overhead_tokens.harvester',
1024
+ 'fixed_overhead_tokens.ci_watcher',
1025
+ 'fixed_overhead_tokens.log_flush_per_cycle',
1026
+ 'input_cost_multiplier.value',
1027
+ 'outlier_thresholds.notable_pct',
1028
+ 'outlier_thresholds.outlier_pct',
1029
+ 'outlier_thresholds.calibration_failure_pct',
1030
+ 'doer_token_ceiling.cheap',
1031
+ 'doer_token_ceiling.standard',
1032
+ 'doer_token_ceiling.premium',
1033
+ 'context_limits.model_context_tokens.cheap',
1034
+ 'context_limits.model_context_tokens.standard',
1035
+ 'context_limits.model_context_tokens.premium',
1036
+ 'context_limits.autocompact_headroom_fraction',
1037
+ 'context_limits.base_prompt_tokens',
1038
+ 'context_limits.per_task_input_overhead_tokens',
1039
+ 'parallelism.max_doers',
1040
+ ];
1041
+ const healed = [];
1042
+ const result = Object.assign({}, calibration);
1043
+ for (const path of requiredPaths) {
1044
+ const val = getPath(result, path);
1045
+ if (typeof val !== 'number' || Number.isNaN(val)) {
1046
+ const def = getPath(defaults, path);
1047
+ setPath(result, path, def);
1048
+ healed.push(`calibration field ${path} missing/invalid -- healed to ${def}`);
1049
+ }
1050
+ }
1051
+ return { calibration: result, healed };
1052
+ }
1053
+
1054
+ // checkModelAliasStaleness: returns "tier=id" strings for any TIER_TO_MODEL value
1055
+ // that looks like a dated pin (ends in -YYYYMMDD). Caller WARNs if non-empty.
1056
+ function checkModelAliasStaleness(tierToModel) {
1057
+ const stale = [];
1058
+ for (const [tier, id] of Object.entries(tierToModel || {})) {
1059
+ if (typeof id === 'string' && /-\d{8}$/.test(id)) stale.push(`${tier}=${id}`);
1060
+ }
1061
+ return stale; // caller WARNs if non-empty
1062
+ }
1063
+
1064
+ // fitStreakToContext: predicts whether an in-order streak fits the doer's usable
1065
+ // context and returns the longest prefix that does. Mirrors truncateStreakToCeiling's
1066
+ // per-task token estimate. Returns { fittedIds, estContext, available, wouldOverflow }.
1067
+ function fitStreakToContext(streakIds, bucketById, calibration, tier) {
1068
+ const cl = (calibration && calibration.context_limits) || {};
1069
+ const windowTokens = (cl.model_context_tokens || {})[tier];
1070
+ const frac = cl.autocompact_headroom_fraction;
1071
+ if (typeof windowTokens !== 'number' || typeof frac !== 'number' || windowTokens <= 0) {
1072
+ return { fittedIds: streakIds.slice(), estContext: 0, available: Infinity, wouldOverflow: false };
1073
+ }
1074
+ const available = windowTokens * frac;
1075
+ const base = cl.base_prompt_tokens || 0;
1076
+ const perTask = cl.per_task_input_overhead_tokens || 0;
1077
+ const outMul = cl.output_expansion_factor != null ? cl.output_expansion_factor : 1.0;
1078
+ // reuse the same output estimate as truncateStreakToCeiling
1079
+ const hist = (calibration && calibration.historical) || {};
1080
+ const buckets = (calibration && calibration.complexity_buckets) || {};
1081
+ const histToks = hist.bucket_avg_tokens || {};
1082
+ const estOut = id => {
1083
+ const b = bucketById ? bucketById[id] : undefined;
1084
+ const h = histToks[b];
1085
+ if (hist.sprints_sampled >= 1 && h != null) return Math.round(h);
1086
+ const def = buckets[b] || buckets.M || { doer_tokens: 0 };
1087
+ return def.doer_tokens || 0;
1088
+ };
1089
+ let sum = base, kept = [];
1090
+ for (const id of streakIds) {
1091
+ const cost = perTask + estOut(id) * outMul;
1092
+ if (kept.length > 0 && sum + cost > available) break; // always keep >=1
1093
+ kept.push(id); sum += cost;
1094
+ }
1095
+ return { fittedIds: kept, estContext: sum, available, wouldOverflow: kept.length < streakIds.length };
1096
+ }
1097
+
1098
+ // Build a per-phase wall-clock report from ordered epoch stamps captured at phase boundaries.
1099
+ // Each stamp is {name, epoch}; the elapsed time attributed to a phase is the delta from its
1100
+ // stamp to the NEXT stamp. Turns "the sprint is slow" into "develop was N of M seconds", which
1101
+ // is what proves the parallel-doer win with numbers. Pure -- no Date/clock access of its own.
1102
+ function buildPhaseTiming(stamps) {
1103
+ const clean = (stamps || []).filter(s => s && s.name && Number.isFinite(s.epoch));
1104
+ const rows = [];
1105
+ for (let i = 0; i < clean.length - 1; i++) {
1106
+ const seconds = Math.max(0, clean[i + 1].epoch - clean[i].epoch);
1107
+ rows.push({ phase: clean[i].name, seconds });
1108
+ }
1109
+ const totalSeconds = rows.reduce((a, r) => a + r.seconds, 0);
1110
+ const fmt = s => {
1111
+ const m = Math.floor(s / 60), sec = s % 60;
1112
+ return m > 0 ? `${m}m${sec.toString().padStart(2, '0')}s` : `${sec}s`;
1113
+ };
1114
+ const pct = s => (totalSeconds > 0 ? Math.round((s / totalSeconds) * 100) : 0);
1115
+ const text = rows.length
1116
+ ? rows.map(r => ` ${r.phase}: ${fmt(r.seconds)} (${pct(r.seconds)}%)`).join('\n') +
1117
+ `\n TOTAL: ${fmt(totalSeconds)}`
1118
+ : ' (no phase timing captured)';
1119
+ return { rows, totalSeconds, text };
1120
+ }
1121
+
1122
+ // Flatten ready streaks into a deterministic, de-duplicated task batch for parallel doers.
1123
+ // Each parallel doer works exactly ONE task in its own worktree, so the per-doer context is a
1124
+ // single task (no context-fit split needed here -- that split only matters when one doer chains
1125
+ // multiple tasks, which the parallel path does not do). We simply take up to `maxDoers` ready
1126
+ // tasks. Ordering is by task id so the later sequential merge is reproducible run-to-run.
1127
+ // Leftover ready tasks are returned as `deferred` and resurface on the next getReadyStreaks call.
1128
+ // Pure -- no I/O, no Date/Math.random.
1129
+ function computeDoerBatch(streaks, maxDoers) {
1130
+ const seen = {};
1131
+ const tasks = [];
1132
+ for (const s of (streaks || [])) {
1133
+ const model = s && s.model;
1134
+ for (const id of ((s && s.ids) || [])) {
1135
+ if (id != null && !seen[id]) { seen[id] = true; tasks.push({ id, model }); }
1136
+ }
1137
+ }
1138
+ tasks.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
1139
+ const cap = Math.max(1, maxDoers || 1);
1140
+ const width = Math.min(cap, tasks.length || 1);
1141
+ return { batch: tasks.slice(0, width), deferred: tasks.slice(width), width, readyCount: tasks.length };
1142
+ }
1143
+
1144
+ // Derive the filesystem-safe worktree path and temp branch name for a parallel doer's task.
1145
+ // The temp branch is namespaced by the sprint branch so concurrent sprints never collide.
1146
+ // Both are sanitized so arbitrary bd ids / branch names (any of hundreds of projects) are safe
1147
+ // as path and ref components. Pure.
1148
+ function worktreeNamesFor(sprintBranch, taskId, worktreeRoot) {
1149
+ const safeId = String(taskId).replace(/[^a-zA-Z0-9._-]/g, '-');
1150
+ const safeBranch = String(sprintBranch).replace(/[^a-zA-Z0-9._-]/g, '-');
1151
+ const root = (worktreeRoot || '.auto-sprint/wt').replace(/\/+$/g, '');
1152
+ return {
1153
+ path: `${root}/${safeId}`,
1154
+ branch: `auto-sprint/wt/${safeBranch}/${safeId}`,
1155
+ };
1156
+ }
1157
+
953
1158
  // PURE_FUNCTIONS_END
954
1159
 
1160
+ // ROLE_SCHEMAS_GENERATED_BEGIN -- do not hand-edit; run `node scripts/gen-auto-sprint-schemas.mjs` to regenerate from agents/schemas/*.json
1161
+ //
1162
+ // apra-fleet-unw.21 / apra-fleet e2e s10 (2026-07-17): the role-contract schemas
1163
+ // below are generated from vendor/apra-pm's own canonical, machine-readable role
1164
+ // contracts at agents/schemas/<role>-output.json, instead of being hand-copied
1165
+ // inline literals -- this closes the drift this file used to have from the
1166
+ // vendored agents/*.md prose and from packages/apra-fleet-se/auto-sprint/contracts.mjs.
1167
+ // The "version" key present in each source file is dropped: it is a non-standard
1168
+ // JSON-Schema keyword the agent tool's strict schema validator rejects.
1169
+ //
1170
+ // Inlined at BUILD TIME (not loaded via require('fs') at runtime) because this file
1171
+ // runs inside Claude's Workflow tool sandbox, which has no filesystem/require access
1172
+ // -- a prior runtime-load revision crashed on every invocation with "require is not
1173
+ // defined". See scripts/gen-auto-sprint-schemas.mjs, which generates this block.
1174
+ const REVIEW_SCHEMA = {
1175
+ "$schema": "http://json-schema.org/draft-07/schema#",
1176
+ "$id": "apra-pm/reviewer-output@1",
1177
+ "title": "reviewer output",
1178
+ "description": "Canonical machine-readable output contract for the reviewer role. See agents/reviewer.md Step 5 for the prose contract this mirrors.",
1179
+ "type": "object",
1180
+ "required": [
1181
+ "verdict",
1182
+ "notes",
1183
+ "reopenIds",
1184
+ "newTasks"
1185
+ ],
1186
+ "properties": {
1187
+ "verdict": {
1188
+ "type": "string",
1189
+ "enum": [
1190
+ "APPROVED",
1191
+ "CHANGES_NEEDED"
1192
+ ]
1193
+ },
1194
+ "notes": {
1195
+ "type": "string"
1196
+ },
1197
+ "reopenIds": {
1198
+ "type": "array",
1199
+ "items": {
1200
+ "type": "string"
1201
+ }
1202
+ },
1203
+ "newTasks": {
1204
+ "type": "array",
1205
+ "items": {
1206
+ "type": "object",
1207
+ "required": [
1208
+ "title",
1209
+ "description",
1210
+ "priority"
1211
+ ],
1212
+ "properties": {
1213
+ "title": {
1214
+ "type": "string"
1215
+ },
1216
+ "description": {
1217
+ "type": "string"
1218
+ },
1219
+ "priority": {
1220
+ "type": "string"
1221
+ }
1222
+ }
1223
+ }
1224
+ }
1225
+ }
1226
+ };
1227
+ const PLAN_REVIEW_SCHEMA = {
1228
+ "$schema": "http://json-schema.org/draft-07/schema#",
1229
+ "$id": "apra-pm/plan-reviewer-output@1",
1230
+ "title": "plan-reviewer output",
1231
+ "description": "Canonical machine-readable output contract for the plan-reviewer role. See agents/plan-reviewer.md Step 4 for the prose contract this mirrors.",
1232
+ "type": "object",
1233
+ "required": [
1234
+ "verdict",
1235
+ "notes",
1236
+ "taskAssignments"
1237
+ ],
1238
+ "properties": {
1239
+ "verdict": {
1240
+ "type": "string",
1241
+ "enum": [
1242
+ "APPROVED",
1243
+ "CHANGES_NEEDED"
1244
+ ]
1245
+ },
1246
+ "notes": {
1247
+ "type": "string"
1248
+ },
1249
+ "taskAssignments": {
1250
+ "type": "array",
1251
+ "items": {
1252
+ "type": "object",
1253
+ "required": [
1254
+ "id",
1255
+ "bucket",
1256
+ "model"
1257
+ ],
1258
+ "properties": {
1259
+ "id": {
1260
+ "type": "string"
1261
+ },
1262
+ "bucket": {
1263
+ "type": "string",
1264
+ "enum": [
1265
+ "S",
1266
+ "M",
1267
+ "L"
1268
+ ]
1269
+ },
1270
+ "model": {
1271
+ "type": "string"
1272
+ }
1273
+ }
1274
+ }
1275
+ }
1276
+ }
1277
+ };
1278
+ const DOER_STATUS_SCHEMA = {
1279
+ "$schema": "http://json-schema.org/draft-07/schema#",
1280
+ "$id": "apra-pm/doer-output@1",
1281
+ "title": "doer output",
1282
+ "description": "Canonical machine-readable output contract for the doer role. See agents/doer.md Step 3 (VERIFY checkpoint) and Branch and secrets rules (BLOCKED) for the prose contract this mirrors.",
1283
+ "type": "object",
1284
+ "required": [
1285
+ "status",
1286
+ "closedIds",
1287
+ "notes"
1288
+ ],
1289
+ "properties": {
1290
+ "status": {
1291
+ "type": "string",
1292
+ "enum": [
1293
+ "VERIFY",
1294
+ "BLOCKED"
1295
+ ]
1296
+ },
1297
+ "closedIds": {
1298
+ "type": "array",
1299
+ "items": {
1300
+ "type": "string"
1301
+ }
1302
+ },
1303
+ "notes": {
1304
+ "type": "string"
1305
+ }
1306
+ }
1307
+ };
1308
+ const DEPLOYER_SCHEMA = {
1309
+ "$schema": "http://json-schema.org/draft-07/schema#",
1310
+ "$id": "apra-pm/deployer-output@1",
1311
+ "title": "deployer output",
1312
+ "description": "Canonical machine-readable output contract for the deployer role. See agents/deployer.md Output schema for the prose contract this mirrors.",
1313
+ "type": "object",
1314
+ "required": [
1315
+ "deployed",
1316
+ "notes"
1317
+ ],
1318
+ "properties": {
1319
+ "deployed": {
1320
+ "type": "boolean"
1321
+ },
1322
+ "notes": {
1323
+ "type": "string"
1324
+ }
1325
+ }
1326
+ };
1327
+ const INTEG_RUN_SCHEMA = {
1328
+ "$schema": "http://json-schema.org/draft-07/schema#",
1329
+ "$id": "apra-pm/integ-test-runner-output@1",
1330
+ "title": "integ-test-runner output",
1331
+ "description": "Canonical machine-readable output contract for the integ-test-runner role. See agents/integ-test-runner.md Step 4 for the prose contract this mirrors.",
1332
+ "type": "object",
1333
+ "required": [
1334
+ "featuresClosed",
1335
+ "issuesCreated",
1336
+ "passed",
1337
+ "bugsFiled",
1338
+ "summary"
1339
+ ],
1340
+ "properties": {
1341
+ "featuresClosed": {
1342
+ "type": "number"
1343
+ },
1344
+ "issuesCreated": {
1345
+ "type": "number"
1346
+ },
1347
+ "passed": {
1348
+ "type": "boolean"
1349
+ },
1350
+ "bugsFiled": {
1351
+ "type": "array",
1352
+ "items": {
1353
+ "type": "string"
1354
+ }
1355
+ },
1356
+ "summary": {
1357
+ "type": "string"
1358
+ }
1359
+ }
1360
+ };
1361
+ const CI_SCHEMA = {
1362
+ "$schema": "http://json-schema.org/draft-07/schema#",
1363
+ "$id": "apra-pm/ci-watcher-output@1",
1364
+ "title": "ci-watcher output",
1365
+ "description": "Canonical machine-readable output contract for the ci-watcher role. See agents/ci-watcher.md Step 2 for the prose contract this mirrors.",
1366
+ "type": "object",
1367
+ "required": [
1368
+ "status",
1369
+ "notes"
1370
+ ],
1371
+ "properties": {
1372
+ "status": {
1373
+ "type": "string",
1374
+ "enum": [
1375
+ "green",
1376
+ "red",
1377
+ "not_configured",
1378
+ "pending"
1379
+ ]
1380
+ },
1381
+ "notes": {
1382
+ "type": "string"
1383
+ }
1384
+ }
1385
+ };
1386
+ const HARVEST_SCHEMA = {
1387
+ "$schema": "http://json-schema.org/draft-07/schema#",
1388
+ "$id": "apra-pm/harvester-output@1",
1389
+ "title": "harvester output",
1390
+ "description": "Canonical machine-readable output contract for the harvester role. See agents/harvester.md Step 7 for the prose contract this mirrors.",
1391
+ "type": "object",
1392
+ "required": [
1393
+ "status",
1394
+ "notes"
1395
+ ],
1396
+ "properties": {
1397
+ "status": {
1398
+ "type": "string",
1399
+ "enum": [
1400
+ "OK",
1401
+ "FAILED"
1402
+ ]
1403
+ },
1404
+ "notes": {
1405
+ "type": "string"
1406
+ }
1407
+ }
1408
+ };
1409
+ // ROLE_SCHEMAS_GENERATED_END
1410
+
955
1411
  function outputCostUsd(tier, tokens) {
956
1412
  const rate = OUTPUT_PRICE_PER_M[tier] || OUTPUT_PRICE_PER_M[TIER_STANDARD];
957
1413
  return (tokens / 1_000_000) * rate;
@@ -1045,10 +1501,52 @@ async function parallel(tasks) {
1045
1501
  return Promise.all(tasks);
1046
1502
  }
1047
1503
 
1504
+ // bd may prepend a `warning: ...` line to its --json stdout (notably bd 1.1.0's
1505
+ // "warning: beads.role not configured (GH#2950)"). In a normal terminal that goes to
1506
+ // stderr, but inside the workflow's sandboxed shell-dispatch subagents stderr merges
1507
+ // into the captured stdout, so the warning is glued in front of the JSON. Feeding that
1508
+ // straight into JSON.parse() throws; the surrounding catch then silently returns an empty
1509
+ // ready/blocker set, and Develop concludes "no ready tasks" (spurious deadlock / skipped
1510
+ // develop with zero doers -- the s10 win32 failure). BD_JSON extracts just the JSON span
1511
+ // (first '['/'{' to the last ']'/'}') so parsing tolerates leading/trailing non-JSON noise.
1512
+ // Deliberately backslash-free (indexOf/lastIndexOf on literal bracket chars) so it survives
1513
+ // the backtick -> shell(double-quote) -> node round-trip with no escaping. Interpolated as
1514
+ // `JSON.parse(${BD_JSON})` inside the node -e extractor strings below.
1515
+ const BD_JSON = `(()=>{const s=d.indexOf('['),o=d.indexOf('{');let a=s<0?o:(o<0?s:Math.min(s,o));const e=Math.max(d.lastIndexOf(']'),d.lastIndexOf('}'));return a>=0&&e>=a?d.slice(a,e+1):d;})()`;
1516
+
1517
+ // bdSubtreeSnippet: returns a JS snippet (embedded in a `node -e` extractor, AFTER
1518
+ // `const g = JSON.parse(...)`) that builds `subtree` = the STRICT sprint inventory for
1519
+ // `rootsArr`: the roots, their dotted-ID descendants (beads' <parent>.<n> hierarchy), and
1520
+ // anything transitively reachable from that set via DependsOn edges.
1521
+ //
1522
+ // Why: `bd graph --json <root>` returns the ENTIRE connected component -- including the
1523
+ // root's PARENT and therefore its SIBLINGS. The old extractors scraped every `.issues[].id`
1524
+ // out of that blob, so unrelated sibling tasks (e.g. gh-toy-4ef, a sibling of gh-toy-mi2
1525
+ // under a shared parent) leaked into the active sprint inventory, making getReadyStreaks
1526
+ // dispatch work outside the charter and the final reviewer hallucinate "missing" tasks.
1527
+ //
1528
+ // The ID-prefix pass is the wiring-independent core: beads always expresses parent->child
1529
+ // as `<parent>.<n>` IDs, so `id === r || id.startsWith(r + '.')` captures exactly a root's
1530
+ // descendants and never its siblings -- and it works even when DependsOn edges are absent
1531
+ // (verified: apra-pm's own DB has all-null DependsOn), so the subtree is never
1532
+ // under-inclusive (no false "no ready tasks" deadlock). The DependsOn BFS then additionally
1533
+ // pulls in explicitly-wired prerequisites. Backslash-free for the backtick->shell->node
1534
+ // round-trip. Reads `g` (the parsed graph) and `subtree` (a Set) from the enclosing scope.
1535
+ function bdSubtreeSnippet(rootsArr) {
1536
+ const rootsLit = (rootsArr || []).join(' ');
1537
+ return `const _roots='${rootsLit}'.split(' ').filter(Boolean);` +
1538
+ `const subtree=new Set(_roots);` +
1539
+ `const _nodes=(g.layout&&g.layout.Nodes)||{};` +
1540
+ `const _ids=new Set([...Object.keys(_nodes),...((g.issues||[]).map(i=>i.id))]);` +
1541
+ `for(const _id of _ids){for(const _r of _roots){if(_id===_r||_id.indexOf(_r+'.')===0){subtree.add(_id);break;}}}` +
1542
+ `const _q=Array.from(subtree);` +
1543
+ `while(_q.length>0){const _c=_q.shift();const _n=_nodes[_c];if(_n&&_n.DependsOn){for(const _dd of _n.DependsOn){if(!subtree.has(_dd)){subtree.add(_dd);_q.push(_dd);}}}}`;
1544
+ }
1545
+
1048
1546
  async function countBeadsBlockers(thr, roots) {
1049
1547
  // Extract only IDs from bd graph to keep output small (avoids $(cat ...) file-reference issue).
1050
- const idExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.parse(d).issues.map(i=>i.id).join(' '))}catch{}"`;
1051
- const openExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.stringify(JSON.parse(d).map(i=>({id:i.id,p:i.priority}))))}catch{console.log('[]')}"`;
1548
+ const idExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{const g=JSON.parse(${BD_JSON});${bdSubtreeSnippet(roots)}console.log(Array.from(subtree).join(' '))}catch{}"`;
1549
+ const openExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.stringify(JSON.parse(${BD_JSON}).map(i=>({id:i.id,p:i.priority}))))}catch{console.log('[]')}"`;
1052
1550
  const cmds = [
1053
1551
  ...roots.map(id => `bd graph --json ${id} | ${idExtract}`),
1054
1552
  `bd list --status=open --json | ${openExtract}`,
@@ -1059,14 +1557,18 @@ async function countBeadsBlockers(thr, roots) {
1059
1557
 
1060
1558
  async function getReadyStreaks(rootIds) {
1061
1559
  // Extract only IDs from bd graph to keep output small (avoids $(cat ...) file-reference issue).
1062
- const idExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.parse(d).issues.map(i=>i.id).join(' '))}catch{}"`;
1063
- const taskExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.stringify(JSON.parse(d).map(i=>({id:i.id,p:i.priority,m:(i.metadata||{}).model}))))}catch{console.log('[]')}"`;
1560
+ const idExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{const g=JSON.parse(${BD_JSON});${bdSubtreeSnippet(rootIds)}console.log(Array.from(subtree).join(' '))}catch{}"`;
1561
+ // Catch fallback emits 'null' (not '[]'): parseReadyStreaks must be able to tell
1562
+ // "extraction failed" apart from "genuinely zero ready tasks" -- see its extractFailed
1563
+ // contract note above. 'null' is valid JSON but not an array, so JSON.parse(...) still
1564
+ // succeeds while the array-shape check flags extractFailed.
1565
+ const taskExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.stringify(JSON.parse(${BD_JSON}).map(i=>({id:i.id,p:i.priority,m:(i.metadata||{}).model}))))}catch{console.log('null')}"`;
1064
1566
  const cmds = [
1065
1567
  ...rootIds.map(id => `bd graph --json ${id} | ${idExtract}`),
1066
1568
  `bd list --ready --type=task --json | ${taskExtract}`,
1067
1569
  ];
1068
1570
  const r = await dispatchShell(cmds, { model: MODEL_HAIKU, label: 'ready-streaks', phase: 'Develop' });
1069
- return parseReadyStreaks(r?.outputs, rootIds.length, rootIds.length, TIER_STANDARD);
1571
+ return parseReadyStreaks(r?.outputs, rootIds.length, rootIds.length, TIER_STANDARD, rootIds);
1070
1572
  }
1071
1573
 
1072
1574
  async function commitFeedback(repo, branch, notes, role, label, phase) {
@@ -1084,8 +1586,8 @@ async function commitFeedback(repo, branch, notes, role, label, phase) {
1084
1586
 
1085
1587
  async function checkCycleState(rootIds) {
1086
1588
  // Extract only the fields needed for planDone check to keep output small.
1087
- const graphExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{const issues=(JSON.parse(d).issues||[]);console.log(JSON.stringify(issues.map(i=>({id:i.id,t:i.issue_type,s:i.status,d:!!(i.description||'').trim()}))))}catch{console.log('[]')}"`;
1088
- const ipExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.parse(d).map(i=>i.id).join(' '))}catch{}"`;
1589
+ const graphExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{const g=JSON.parse(${BD_JSON});${bdSubtreeSnippet(rootIds)}const issues=(g.issues||[]).filter(i=>subtree.has(i.id));console.log(JSON.stringify(issues.map(i=>({id:i.id,t:i.issue_type,s:i.status,d:!!(i.description||'').trim()}))))}catch{console.log('[]')}"`;
1590
+ const ipExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.parse(${BD_JSON}).map(i=>i.id).join(' '))}catch{}"`;
1089
1591
  const cmds = [
1090
1592
  ...rootIds.map(id => `bd graph --json ${id} | ${graphExtract}`),
1091
1593
  `bd list --status=in_progress --type=task --json | ${ipExtract}`,
@@ -1094,6 +1596,70 @@ async function checkCycleState(rootIds) {
1094
1596
  return parseCycleState(r?.outputs, rootIds.length);
1095
1597
  }
1096
1598
 
1599
+ // getSprintOpenFeatures: the OPEN features that live in THIS sprint's subtree, as [{id,title}].
1600
+ // The integration tester must test/close only these -- NOT `bd list --type=feature --status=open`,
1601
+ // which returns every open feature in the whole beads DB (a populated DB has features from other
1602
+ // epics/sprints, so an unscoped list makes the tester test, close, or file bugs against unrelated
1603
+ // work). Uses the same strict bdSubtreeSnippet inventory as the develop-phase extractors, so
1604
+ // siblings/parents dragged in by `bd graph`'s connected component are excluded.
1605
+ async function getSprintOpenFeatures(rootIds) {
1606
+ const featExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{const g=JSON.parse(${BD_JSON});${bdSubtreeSnippet(rootIds)}const ff=(g.issues||[]).filter(i=>subtree.has(i.id)&&i.issue_type==='feature'&&i.status!=='closed');console.log(JSON.stringify(ff.map(i=>({id:i.id,title:(i.title||'').slice(0,120)}))))}catch{console.log('[]')}"`;
1607
+ const cmds = rootIds.map(id => `bd graph --json ${id} | ${featExtract}`);
1608
+ const r = await dispatchShell(cmds, { model: MODEL_HAIKU, label: 'integ-scope', phase: 'Test' });
1609
+ const byId = new Map();
1610
+ for (const out of (r?.outputs || [])) {
1611
+ try { for (const f of JSON.parse(out)) if (f && f.id) byId.set(f.id, f); } catch {}
1612
+ }
1613
+ return Array.from(byId.values());
1614
+ }
1615
+
1616
+ // ---- sprint state file: concurrency lock + phase checkpoint / resume ----
1617
+ // A branch-keyed JSON file under sprint-logs/.state/ records the last good phase and
1618
+ // cycle so a crashed run resumes forward instead of restarting. Its mtime doubles as a
1619
+ // liveness lock: a file touched within SPRINT_STATE_TTL_S means another run is active.
1620
+ // All time/mtime math is done inside node subprocesses (Date.now() is banned in the
1621
+ // workflow script body, but fine inside `node -e`). Cross-platform: pure node fs, no stat(1).
1622
+ const SPRINT_STATE_TTL_S = 3600;
1623
+ function sprintStateFileFor(branchName) {
1624
+ const safe = branchName.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-{2,}/g, '-').replace(/^-|-$/g, '') || 'default';
1625
+ return `sprint-logs/.state/${safe}.state.json`;
1626
+ }
1627
+ // Returns { exists, ageS, state }. ageS is the file's age in seconds (null when absent).
1628
+ async function readSprintState(stateFileRel, label) {
1629
+ const script =
1630
+ `node -e "` +
1631
+ `const fs=require('fs');const p='${stateFileRel}';` +
1632
+ `if(!fs.existsSync(p)){console.log(JSON.stringify({exists:false,ageS:null,state:null}));process.exit(0);}` +
1633
+ `const age=Math.floor((Date.now()-fs.statSync(p).mtimeMs)/1000);` +
1634
+ `let st=null;try{st=JSON.parse(fs.readFileSync(p,'utf8'));}catch(e){}` +
1635
+ `console.log(JSON.stringify({exists:true,ageS:age,state:st}));` +
1636
+ `"`;
1637
+ const r = await dispatchShell([script], { model: MODEL_HAIKU, label: label || 'state-read', phase: 'Plan' });
1638
+ try { return JSON.parse((r?.outputs?.[0] || '').trim()); } catch { return { exists: false, ageS: null, state: null }; }
1639
+ }
1640
+ // Writes the state object as JSON. The JSON is hex-encoded in the workflow body (which
1641
+ // has ONLY standard JS built-ins -- NOT Buffer/process/require) and decoded inside the
1642
+ // node subprocess (which has them). Hex is quote-safe so it embeds cleanly in the
1643
+ // double-quoted `node -e` string; charCodeAt/fromCharCode round-trip UTF-16 exactly.
1644
+ // Rewriting the file updates its mtime = lock heartbeat.
1645
+ async function writeSprintState(stateFileRel, stateObj, phaseName, label) {
1646
+ const json = JSON.stringify(stateObj);
1647
+ let hex = '';
1648
+ for (let i = 0; i < json.length; i++) hex += json.charCodeAt(i).toString(16).padStart(4, '0');
1649
+ const script =
1650
+ `node -e "` +
1651
+ `const fs=require('fs'),path=require('path');const p='${stateFileRel}';const h='${hex}';` +
1652
+ `let s='';for(let i=0;i<h.length;i+=4)s+=String.fromCharCode(parseInt(h.substr(i,4),16));` +
1653
+ `fs.mkdirSync(path.dirname(p),{recursive:true});` +
1654
+ `fs.writeFileSync(p,s);` +
1655
+ `console.log('WROTE');` +
1656
+ `"`;
1657
+ await dispatchShell([script], { model: MODEL_HAIKU, label: label || 'state-write', phase: phaseName || 'Plan' });
1658
+ }
1659
+ async function clearSprintState(stateFileRel, label) {
1660
+ await dispatchShell([`rm -f "${stateFileRel}"`], { model: MODEL_HAIKU, label: label || 'state-clear', phase: 'Harvest' });
1661
+ }
1662
+
1097
1663
  // ------------------------------------------------------------------ STATE
1098
1664
 
1099
1665
  let cycleCount = 0;
@@ -1109,22 +1675,67 @@ phase('Plan');
1109
1675
  // Phase 1: deterministic setup steps -- run via dispatchShell so each command
1110
1676
  // executes exactly once with a bounded turn cap (no LLM looping on simple checks).
1111
1677
  //
1112
- // Fixed output indices (always 6 elements regardless of branch/no-branch):
1678
+ // Fixed output indices (always 8 elements regardless of branch/no-branch):
1113
1679
  // 0: repo root (git rev-parse --show-toplevel)
1114
- // 1: branch checkout result (or "no-op" when branch was not specified)
1115
- // 2: confirmed branch name (git rev-parse --abbrev-ref HEAD)
1116
- // 3: startedAt timestamp (date +%Y%m%d_%H%M%S)
1117
- // 4: deploy.md exists (YES/NO)
1118
- // 5: integ-test-playbook.md exists (YES/NO)
1680
+ // 1: fetch result (FETCHED / FETCH_FAIL) -- run BEFORE checkout so a new sprint
1681
+ // branch is cut from the freshest origin/<base_branch> (guards stale-main branching).
1682
+ // Also (side effect, no stdout) registers the sprint scaffolding dirs in the repo's
1683
+ // local git exclude so the state file and any worktree roots never leak into a doer's
1684
+ // `git add -A` / the committed sprint-logs/ tree and pollute the PR diff.
1685
+ // 2: branch checkout result (or "no-op" when branch was not specified)
1686
+ // 3: confirmed branch name (git rev-parse --abbrev-ref HEAD)
1687
+ // 4: startedAt timestamp (date +%Y%m%d_%H%M%S)
1688
+ // 5: deploy.md exists (YES/NO)
1689
+ // 6: integ-test-playbook.md exists (YES/NO)
1690
+ // 7: newline-joined list of permission entries declared in deploy.md /
1691
+ // integ-test-playbook.md's "## Permissions" sections that are NOT yet
1692
+ // in .claude/settings.json's permissions.allow (empty string if none --
1693
+ // computed deterministically here so Step 5's prompt to the agent never
1694
+ // has to say "you may grant yourself permissions" when there's nothing
1695
+ // to grant).
1119
1696
  const setupShellCmds = [
1120
1697
  `git rev-parse --show-toplevel`,
1698
+ // Fetch first so branch creation below can base a NEW sprint branch on the freshest
1699
+ // origin/<base_branch> instead of a possibly-stale local HEAD (stale-main guard).
1700
+ // The `{ ... }` block writes only to a file (no stdout), so the slot's stdout stays
1701
+ // exactly FETCHED/FETCH_FAIL. Uses `git rev-parse --git-path` so it resolves correctly
1702
+ // in linked worktrees too; the trailing `;` guarantees the fetch runs regardless.
1703
+ `EXCL=$(git rev-parse --git-path info/exclude 2>/dev/null); ` +
1704
+ `if [ -n "$EXCL" ]; then mkdir -p "$(dirname "$EXCL")"; ` +
1705
+ `grep -qxF 'sprint-logs/.state/' "$EXCL" 2>/dev/null || ` +
1706
+ `printf 'sprint-logs/.state/\\n.auto-sprint/\\n' >> "$EXCL"; fi; ` +
1707
+ `git fetch origin --quiet && echo FETCHED || echo FETCH_FAIL`,
1121
1708
  branch
1122
- ? `git checkout "${branch}" 2>/dev/null || git checkout --track "origin/${branch}" 2>/dev/null || git checkout -b "${branch}"`
1709
+ // Prefer the freshest origin/<base_branch> as the new branch's base (stale-main guard), but if
1710
+ // that ref is absent (repo's default is e.g. master, or fetch failed) fall back to creating from
1711
+ // local HEAD -- never leave HEAD on the wrong branch, which would silently run the sprint there.
1712
+ ? `git checkout "${branch}" 2>/dev/null || git checkout --track "origin/${branch}" 2>/dev/null || git checkout -b "${branch}" "origin/${base_branch}" 2>/dev/null || git checkout -b "${branch}"`
1123
1713
  : `echo "no-op"`,
1124
1714
  `git rev-parse --abbrev-ref HEAD`,
1125
1715
  `date +%Y%m%d_%H%M%S`,
1126
1716
  `test -f deploy.md && echo YES || echo NO`,
1127
1717
  `test -f integ-test-playbook.md && echo YES || echo NO`,
1718
+ `node -e "` +
1719
+ `const fs=require('fs');` +
1720
+ `function permsFrom(file){` +
1721
+ `if(!fs.existsSync(file))return[];` +
1722
+ `const text=fs.readFileSync(file,'utf8');` +
1723
+ `const idx=text.indexOf('## Permissions');` +
1724
+ `if(idx<0)return[];` +
1725
+ `const rest=text.slice(idx);` +
1726
+ `const next=rest.indexOf('\\n## ',3);` +
1727
+ `const section=next>=0?rest.slice(0,next):rest;` +
1728
+ // Any Tool(...) entry (not just flush-left Bash): allow a leading bullet/indent and inner ')'.
1729
+ `return(section.match(/^[ \\t]*[-*]?[ \\t]*[A-Za-z_][A-Za-z0-9_]*\\([^\\n]*\\)[ \\t]*$/gm)||[])` +
1730
+ `.map(s=>s.replace(/^[ \\t]*[-*]?[ \\t]*/,'').trim());` +
1731
+ `}` +
1732
+ `const declared=[...new Set([...permsFrom('deploy.md'),...permsFrom('integ-test-playbook.md')])];` +
1733
+ `let existing=[];` +
1734
+ `try{existing=(JSON.parse(fs.readFileSync('.claude/settings.json','utf8')).permissions||{}).allow||[];}catch(e){}` +
1735
+ `const missing=declared.filter(p=>!existing.includes(p));` +
1736
+ // Newline-delimited, not comma: a permission pattern may contain commas, e.g. Bash(cmd --a=1,2).
1737
+ `console.log(missing.join(String.fromCharCode(10)));` +
1738
+ `"`,
1128
1739
  ];
1129
1740
  const setupShell = await dispatchShell(setupShellCmds, {
1130
1741
  model: MODEL_HAIKU, label: 'setup-shell', phase: 'Plan',
@@ -1132,18 +1743,36 @@ const setupShell = await dispatchShell(setupShellCmds, {
1132
1743
 
1133
1744
  const _outs = setupShell && Array.isArray(setupShell.outputs) ? setupShell.outputs : [];
1134
1745
  const _detectedRepo = (_outs[0] || '').trim();
1135
- const _detectedBranch = (_outs[2] || '').trim();
1136
- const _detectedTs = (_outs[3] || '').trim();
1137
- const _deployExists = (_outs[4] || '').trim() === 'YES';
1138
- const _playbookExists = (_outs[5] || '').trim() === 'YES';
1746
+ const _fetchResult = (_outs[1] || '').trim();
1747
+ const _detectedBranch = (_outs[3] || '').trim();
1748
+ const _detectedTs = (_outs[4] || '').trim();
1749
+ const _deployExists = (_outs[5] || '').trim() === 'YES';
1750
+ const _playbookExists = (_outs[6] || '').trim() === 'YES';
1751
+ const _missingPerms = (_outs[7] || '').trim().split(/\r?\n/).map(s => s.trim()).filter(Boolean);
1139
1752
 
1140
1753
  if (!_detectedRepo || !_detectedBranch) {
1141
1754
  log('ERROR: setup-shell failed -- could not detect repo root or branch');
1142
1755
  return { error: 'setup failed' };
1143
1756
  }
1144
1757
 
1758
+ // PREFLIGHT (latest HEAD) -- a failed fetch means we cannot guarantee the sprint branch
1759
+ // was cut from the latest origin/<base_branch>; there is no safe silent fallback. Hard-fail.
1760
+ if (_fetchResult === 'FETCH_FAIL') {
1761
+ log(`ERROR: preflight -- git fetch origin failed; cannot guarantee branch is off latest ${base_branch}. Check network/remote and retry.`);
1762
+ return { error: 'preflight: git fetch failed' };
1763
+ }
1764
+
1145
1765
  // Phase 2: free-form setup steps (permissions merge, calibration, transcript dir).
1146
1766
  // maxTurns: 20 backstop prevents a runaway agent from stalling indefinitely.
1767
+ const step5Block = _missingPerms.length > 0
1768
+ ? (
1769
+ `Step 5: Add these specific missing permission entries to .claude/settings.json's\n` +
1770
+ ` permissions.allow array (create the file/array if absent). Add ONLY these entries,\n` +
1771
+ ` nothing else, and do not remove or modify anything else in the file:\n` +
1772
+ _missingPerms.map(p => ` - ${p}`).join('\n') + `\n\n`
1773
+ )
1774
+ : `Step 5: Already satisfied -- every permission declared in deploy.md / integ-test-playbook.md\n` +
1775
+ ` is already present in .claude/settings.json. Do nothing for this step.\n\n`;
1147
1776
  const setup = await dispatch(
1148
1777
  `Sprint workspace setup (Phase 2 -- deterministic steps already done).\n\n` +
1149
1778
  `Pre-known values (do NOT re-run these commands):\n` +
@@ -1154,15 +1783,7 @@ const setup = await dispatch(
1154
1783
  ` playbookExists: ${_playbookExists}\n\n` +
1155
1784
  `Your job is only Steps 5-7 below. Return ALL fields in your schema response,\n` +
1156
1785
  `including the pre-known values above.\n\n` +
1157
- `Step 5: Merge deploy permissions into .claude/settings.json.\n` +
1158
- ` For each of deploy.md and integ-test-playbook.md that exists:\n` +
1159
- ` a. Read the file and extract lines under the "## Permissions" section\n` +
1160
- ` (stop at the next ## heading). Each non-empty line is a permission entry\n` +
1161
- ` such as "Bash(docker *)" or "Bash(npm run *)".\n` +
1162
- ` b. Read .claude/settings.json (create it as {} if absent).\n` +
1163
- ` c. For each extracted permission not already in permissions.allow, add it.\n` +
1164
- ` d. Write the updated .claude/settings.json back.\n` +
1165
- ` If neither file has a ## Permissions section, skip this step.\n\n` +
1786
+ step5Block +
1166
1787
  `Step 6: Load or bootstrap calibration data.\n` +
1167
1788
  ` If sprint-logs/calibration.json exists in the repo root:\n` +
1168
1789
  ` Run: cat sprint-logs/calibration.json\n` +
@@ -1198,12 +1819,55 @@ if (branch === 'main' || branch === 'master') {
1198
1819
  return { error: 'protected branch' };
1199
1820
  }
1200
1821
 
1822
+ // ---- CONCURRENCY LOCK + RESUME (branch-keyed state file) ----
1823
+ // Placed after setup so the confirmed branch name keys the state file. Every branch below
1824
+ // is a NO-OP when no state file exists -- a fresh run follows the exact prior code path.
1825
+ const stateFileRel = sprintStateFileFor(branch);
1826
+ const _priorState = await readSprintState(stateFileRel, 'state-read');
1827
+ let effectiveStartedAt = setup.startedAt;
1828
+ if (_priorState.exists && typeof _priorState.ageS === 'number' && _priorState.ageS < SPRINT_STATE_TTL_S) {
1829
+ log(`ERROR: preflight -- another auto-sprint run appears active on branch "${branch}" (state updated ${_priorState.ageS}s ago < ${SPRINT_STATE_TTL_S}s TTL). Refusing to start a second overlapping run (guards concurrent-checkout corruption). If the prior run truly crashed, wait out the TTL or delete ${repo}/${stateFileRel}.`);
1830
+ return { error: 'preflight: sprint already running' };
1831
+ }
1832
+ if (_priorState.exists && _priorState.state) {
1833
+ const _rc = Number(_priorState.state.cycle) || 0;
1834
+ if (_priorState.state.startedAt) effectiveStartedAt = _priorState.state.startedAt; // keep log-file continuity
1835
+ if (_rc > 0) cycleCount = _rc - 1; // re-enter the loop at the crashed cycle (loop increments first)
1836
+ log(`RESUME: stale state for "${branch}" (age ${_priorState.ageS}s, lastGoodPhase=${_priorState.state.phase || '?'}, cycle=${_rc}) -- resuming from cycle ${_rc} instead of restarting. Beads state (durable closed tasks, planDone detection, orphan reset) drives intra-cycle correctness; no junk issues are re-created.`);
1837
+ }
1838
+
1839
+ // ---- PREFLIGHT: beads schema gate (bd remote-migrate block, #4259) ----
1840
+ // If the repo's beads DB is remote-backed and its Dolt schema is BEHIND the installed bd, bd
1841
+ // refuses to auto-migrate the shared remote (independent migration forks the schema), and every
1842
+ // write the sprint makes -- planner `bd create`, doer `bd update --claim` / `bd close` -- is
1843
+ // blocked. Left undetected the sprint dies mid-run with a cryptic error and no PR. A read-only
1844
+ // `bd ready` still surfaces the gate as a warning, so probe for it up front and fail fast with
1845
+ // the exact fix. Signature strings are matched loosely so this survives minor bd wording changes;
1846
+ // a repo with no bd DB yet ("no beads database found") does NOT match, so there is no false abort.
1847
+ const _bdGate = await dispatchShell(
1848
+ [`bd ready 2>&1 | grep -iE "refusing to auto-apply|writes are blocked|remote-backed database|forks the schema|BD_ALLOW_REMOTE_MIGRATE" | head -3 || true`],
1849
+ { model: MODEL_HAIKU, label: 'preflight-bd-schema', phase: 'Plan' }
1850
+ );
1851
+ const _gateHit = ((_bdGate && _bdGate.outputs && _bdGate.outputs[0]) || '').trim();
1852
+ if (_gateHit) {
1853
+ log(
1854
+ `ERROR: preflight -- BEADS SCHEMA GATE. This repo's bd database is remote-backed and its Dolt ` +
1855
+ `schema is behind the installed bd, so bd is blocking all writes to avoid forking the shared ` +
1856
+ `remote (#4259). A sprint cannot claim/close/create issues in this state. Detected: ` +
1857
+ `"${_gateHit.slice(0, 180)}". FIX (single-owner DB, the common case): on the OLD bd run ` +
1858
+ `\`bd dolt push\`; install the new bd; then \`BD_ALLOW_REMOTE_MIGRATE=1 bd migrate && bd dolt push\`. ` +
1859
+ `Full runbook (incl. the multi-clone case): docs/beads-1.1.0-migration.md. Aborting before any ` +
1860
+ `work so no partial sprint or PR is produced.`
1861
+ );
1862
+ return { error: 'preflight: beads schema gate (remote-migrate block)' };
1863
+ }
1864
+
1201
1865
  // Parse calibration from the raw string the setup agent returned verbatim.
1202
1866
  // Deep-merge with DEFAULT_CALIBRATION so any missing/new field always has a valid value.
1203
1867
  // historical gets its own merge because it accumulates real sprint history on top of the zeros.
1204
1868
  let _parsedCalib = {};
1205
1869
  try { _parsedCalib = JSON.parse(setup.calibrationRaw || '{}'); } catch {}
1206
- const calibration = Object.assign({}, DEFAULT_CALIBRATION, _parsedCalib, {
1870
+ const _mergedCalibration = Object.assign({}, DEFAULT_CALIBRATION, _parsedCalib, {
1207
1871
  historical: Object.assign({}, DEFAULT_CALIBRATION.historical, _parsedCalib.historical || {}),
1208
1872
  complexity_buckets: _parsedCalib.complexity_buckets || DEFAULT_CALIBRATION.complexity_buckets,
1209
1873
  model_prices_per_1m_output_tokens: _parsedCalib.model_prices_per_1m_output_tokens || DEFAULT_CALIBRATION.model_prices_per_1m_output_tokens,
@@ -1214,7 +1878,17 @@ const calibration = Object.assign({}, DEFAULT_CALIBRATION, _parsedCalib, {
1214
1878
  input_cost_multiplier: _parsedCalib.input_cost_multiplier || DEFAULT_CALIBRATION.input_cost_multiplier,
1215
1879
  outlier_thresholds: _parsedCalib.outlier_thresholds || DEFAULT_CALIBRATION.outlier_thresholds,
1216
1880
  doer_token_ceiling: _parsedCalib.doer_token_ceiling || DEFAULT_CALIBRATION.doer_token_ceiling,
1881
+ context_limits: _parsedCalib.context_limits || DEFAULT_CALIBRATION.context_limits,
1217
1882
  });
1883
+ // PREFLIGHT (calibration completeness) -- heal any numeric field the cost/context
1884
+ // arithmetic reads that is missing or NaN on a stale on-disk calibration.json, filling
1885
+ // from DEFAULT_CALIBRATION so estimation never produces NaN. Auto-heal + WARN.
1886
+ const _calCheck = assertCalibrationComplete(_mergedCalibration, DEFAULT_CALIBRATION);
1887
+ const calibration = _calCheck.calibration;
1888
+ for (const h of _calCheck.healed) log(`WARN: ${h}`);
1889
+ // PREFLIGHT (model-alias staleness) -- warn if any tier maps to a dated model pin.
1890
+ const _staleAliases = checkModelAliasStaleness(TIER_TO_MODEL);
1891
+ if (_staleAliases.length) log(`WARN: TIER_TO_MODEL has dated-looking model IDs (prefer bare aliases): ${_staleAliases.join(', ')}`);
1218
1892
  // Sync output prices from loaded calibration so dispatchLedger uses correct rates.
1219
1893
  Object.assign(OUTPUT_PRICE_PER_M, calibration.model_prices_per_1m_output_tokens || {});
1220
1894
 
@@ -1231,12 +1905,26 @@ let taskAssignments = [];
1231
1905
  // Timestamp (yyyymmdd_hhmmss) is captured by the setup agent so it stays
1232
1906
  // stable across workflow resumes (Date.now() is banned in workflow scripts).
1233
1907
  const sprintLogBranch = branch.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-{2,}/g, '-').replace(/^-|-$/g, '') || 'default';
1234
- const sprintLogFile = `sprint-logs/${sprintLogBranch}-${setup.startedAt}.jsonl`;
1908
+ const sprintLogFile = `sprint-logs/${sprintLogBranch}-${effectiveStartedAt}.jsonl`;
1235
1909
  const integTestEnabled = setup.deployMdExists && setup.playbookExists;
1236
1910
  // startedAt "20260622_020952" -> ISO "2026-06-22T02:09:52Z" (pure string, no Date.now())
1237
- const sprintTs = setup.startedAt.replace(/^(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})$/, '$1-$2-$3T$4:$5:$6Z');
1911
+ const sprintTs = effectiveStartedAt.replace(/^(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})(\d{2})$/, '$1-$2-$3T$4:$5:$6Z');
1238
1912
  let flushedCount = 0; // how many dispatchLedger entries have been appended to sprintLogFile
1239
1913
 
1914
+ // Snapshot of the resolved setup, reused when writing phase checkpoints below.
1915
+ // NOTE: deliberately does NOT carry calibrationRaw. The checkpoint is hex-encoded onto a
1916
+ // `node -e` command line (writeSprintState); the full calibration JSON there pushed the
1917
+ // command length toward the Windows ~32KB limit for no benefit -- resume never reads it
1918
+ // (it re-derives calibration from the fresh Phase-2 setup, see _parsedCalib). Keep this
1919
+ // object small: every field here is embedded in every heartbeat write.
1920
+ const _stateBase = {
1921
+ schema_version: 1, branch, base_branch, rootIds,
1922
+ startedAt: effectiveStartedAt, repo, transcriptDir: setup.transcriptDir || '',
1923
+ integTestEnabled,
1924
+ };
1925
+ // Acquire the lock / record the initial checkpoint now that setup has resolved.
1926
+ await writeSprintState(stateFileRel, { ..._stateBase, cycle: cycleCount, phase: 'Plan', planApproved: false }, 'Plan', 'state-init');
1927
+
1240
1928
  // Appends only the NEW (not yet flushed) ledger entries to the sprint log file.
1241
1929
  // Fire-and-forget: does NOT await, and does NOT commit or push.
1242
1930
  // The next natural committer (doer/sprint-meta/beads-export-cleanup) picks the file
@@ -1278,7 +1966,7 @@ log(`Sprint goals: ${rootSummary} | Goal: ${goal} (P<=${threshold}) | Max cycles
1278
1966
  {
1279
1967
  const metaLine = JSON.stringify({
1280
1968
  ts: sprintTs, type: 'meta',
1281
- branch, startedAt: setup.startedAt,
1969
+ branch, startedAt: effectiveStartedAt,
1282
1970
  roots: rootIds, goal,
1283
1971
  transcriptDir: setup.transcriptDir || '',
1284
1972
  });
@@ -1291,7 +1979,7 @@ log(`Sprint goals: ${rootSummary} | Goal: ${goal} (P<=${threshold}) | Max cycles
1291
1979
  `Line:\n${metaLine}\n\n` +
1292
1980
  `Step 3: Commit and push:\n` +
1293
1981
  ` git -C "${repo}" add sprint-logs/\n` +
1294
- ` git -C "${repo}" -c user.name='pm' -c user.email='pm@pm.local' commit -m "chore: sprint-meta ${branch} ${setup.startedAt}"\n` +
1982
+ ` git -C "${repo}" -c user.name='pm' -c user.email='pm@pm.local' commit -m "chore: sprint-meta ${branch} ${effectiveStartedAt}"\n` +
1295
1983
  ` git -C "${repo}" push origin ${branch}\n` +
1296
1984
  `Do not modify any other file. Return "OK" when done.`,
1297
1985
  { model: MODEL_HAIKU, label: 'sprint-meta', phase: 'Plan' }
@@ -1300,6 +1988,27 @@ log(`Sprint goals: ${rootSummary} | Goal: ${goal} (P<=${threshold}) | Max cycles
1300
1988
 
1301
1989
  // ------------------------------------------------------------------ SPRINT LOOP
1302
1990
 
1991
+ // Per-phase wall-clock instrumentation. We cannot self-time (Date.now() is banned in the
1992
+ // workflow sandbox), so we capture a cheap `date +%s` epoch at each phase boundary and diff
1993
+ // them at the end (buildPhaseTiming). This is what turns "the sprint is slow" into a concrete
1994
+ // per-phase breakdown and lets the parallel-doer win be shown in numbers.
1995
+ const phaseTimeline = [];
1996
+ // Arrow (not `async function`) on purpose: appendNewEntries is asserted to be the LAST top-level
1997
+ // `async function` in this file by test/sprint-log-flush.test.mjs, which slices to the next one.
1998
+ const stamp = async (name) => {
1999
+ // Attribute the timing probe to the phase it actually marks (name prefix), not always 'Plan',
2000
+ // so the per-phase cost ledger buildPhaseTiming reports stays trustworthy.
2001
+ const _ph = /^plan/.test(name) ? 'Plan'
2002
+ : /^develop/.test(name) ? 'Develop'
2003
+ : /^test/.test(name) ? 'Test'
2004
+ : /^(harvest|end)/.test(name) ? 'Harvest'
2005
+ : 'Plan';
2006
+ const r = await dispatchShell(['date +%s'], { model: MODEL_HAIKU, label: `stamp-${name}`, phase: _ph });
2007
+ const epoch = parseInt(((r?.outputs?.[0]) || '').trim(), 10);
2008
+ if (Number.isFinite(epoch)) phaseTimeline.push({ name, epoch });
2009
+ };
2010
+ await stamp('setup');
2011
+
1303
2012
  while (cycleCount < maxCycles) {
1304
2013
  cycleCount++;
1305
2014
  cycleCostUsd = 0;
@@ -1308,6 +2017,7 @@ while (cycleCount < maxCycles) {
1308
2017
  // ---------------------------------------------------------------- RESUME CHECK + CYCLE CHECKPOINT
1309
2018
 
1310
2019
  phase('Plan');
2020
+ await stamp(`plan-c${cycleCount}`);
1311
2021
 
1312
2022
  // Write per-cycle checkpoint entry and check cycle state in parallel -- no data dependency.
1313
2023
  // The cycle-checkpoint uses type='cycle-start' (distinct from the one-time type='meta' above).
@@ -1327,6 +2037,10 @@ while (cycleCount < maxCycles) {
1327
2037
  ]);
1328
2038
  log(`Cycle state: planDone=${cycleState.planDone} inProgress=[${cycleState.inProgressIds.join(', ')}]`);
1329
2039
 
2040
+ // Phase checkpoint (heartbeat): record cycle + phase so a crash resumes here, and refresh
2041
+ // the state-file mtime so the concurrency lock stays live through this cycle.
2042
+ await writeSprintState(stateFileRel, { ..._stateBase, cycle: cycleCount, phase: 'Plan', planApproved: cycleState.planDone }, 'Plan', `state-c${cycleCount}-plan`);
2043
+
1330
2044
  // Reset any tasks orphaned in_progress from a previous crashed run.
1331
2045
  if (cycleState.inProgressIds.length > 0) {
1332
2046
  log(`Resetting ${cycleState.inProgressIds.length} orphaned in_progress task(s) to open`);
@@ -1366,28 +2080,30 @@ while (cycleCount < maxCycles) {
1366
2080
  ` - BEFORE creating any feature or task, run: bd search "<title>" --status all\n` +
1367
2081
  ` If a matching issue already exists, update it instead of creating a duplicate.\n` +
1368
2082
  `\n` +
1369
- `DEPENDENCY WIRING -- read this carefully. "bd dep add A B" means A CANNOT CLOSE until B is done.\n` +
1370
- `The correct wiring direction is: parents depend on children (children unblock first).\n` +
2083
+ `DEPENDENCY WIRING -- follow your runbook (agents/planner.md) and the canonical rules in\n` +
2084
+ `agents/_shared/GRAPH-SEMANTICS.md exactly: parent-child (via --parent) is for GROUPING\n` +
2085
+ `only; blocks (via "bd dep add A B", meaning A cannot close until B is done) is for\n` +
2086
+ `ORDERING between siblings only. NEVER add a blocks edge between a bead and its own\n` +
2087
+ `--parent ancestor/descendant, in either direction -- a --parent edge plus a blocks edge\n` +
2088
+ `between the same two beads deadlocks both, and "bd dep cycles" will NOT warn you.\n` +
1371
2089
  `\n` +
1372
- ` Step 1 -- wire sprint goal -> child (goal waits for children):\n` +
1373
- ` bd dep add <goal-id> <child-id>\n` +
1374
- ` After this: "bd ready" will NOT show the sprint goal (it's waiting). Children show as ready.\n` +
2090
+ ` Step 1 -- group: break each sprint goal into child issues with\n` +
2091
+ ` bd create --parent <goal-id> (type=feature for sub-goals, type=task for leaf work),\n` +
2092
+ ` and parent each feature's tasks with bd create --parent <feature-id>.\n` +
2093
+ ` A parent's "not done until its children close" status comes from its children --\n` +
2094
+ ` do NOT bd dep add <goal-id> <child-id> or bd dep add <feature-id> <task-id>.\n` +
1375
2095
  `\n` +
1376
- ` Step 2 -- wire feature -> tasks (feature waits for tasks):\n` +
1377
- ` bd dep add <feature-id> <impl-task-id>\n` +
1378
- ` bd dep add <feature-id> <test-task-id>\n` +
1379
- ` After this: "bd ready" will show impl-task (the leaf). Feature is now blocked.\n` +
2096
+ ` Step 2 -- order siblings: bd dep add <test-task-id> <impl-task-id> (test task blocked\n` +
2097
+ ` until the impl task closes -- correct: they are siblings). Same pattern for any\n` +
2098
+ ` later sibling task that depends on an earlier one.\n` +
1380
2099
  `\n` +
1381
- ` Step 3 -- wire test after impl:\n` +
1382
- ` bd dep add <test-task-id> <impl-task-id>\n` +
1383
- ` After this: "bd ready" shows only impl-task. test-task unblocks once impl-task closes.\n` +
1384
- `\n` +
1385
- ` VERIFY after wiring: run "bd ready" -- it must return impl tasks, NOT sprint goals or blocked parents.\n` +
1386
- ` If sprint goals appear in "bd ready" the deps are backwards -- fix them before continuing.\n` +
2100
+ ` VERIFY after wiring: run "bd list --parent <goal-id> --ready --json" for each sprint\n` +
2101
+ ` goal -- it must be non-empty while open work exists under that goal. If it is empty,\n` +
2102
+ ` there is a cycle: find the blocks edge pointing at a --parent ancestor/descendant\n` +
2103
+ ` and remove it with bd dep remove.\n` +
1387
2104
  `\n` +
1388
2105
  ` IMPORTANT: Each task belongs to exactly ONE feature. Never share a task across features.\n` +
1389
2106
  `\n` +
1390
- ` Break each sprint goal into child issues: bd create --parent <goal-id> (use type=feature for sub-goals, type=task for leaf work).\n` +
1391
2107
  ` Create type=task issues for each feature: implementation tasks AND integration\n` +
1392
2108
  ` test development tasks (prefix test tasks with "[test]" in the title)\n` +
1393
2109
  ` Features P1/P2; tasks one level below their parent feature (P1 feature -> P2 tasks, P2 feature -> P3 tasks)\n` +
@@ -1428,11 +2144,12 @@ while (cycleCount < maxCycles) {
1428
2144
  `Run: bd show <id> to inspect individual issues in depth.\n` +
1429
2145
  `Run: bd ready -- this is your FIRST correctness check.\n` +
1430
2146
  `Do NOT review or comment on issues outside these sprint goals.\n\n` +
1431
- `Follow your runbook (plan-reviewer.md) step by step:\n` +
2147
+ `Follow your runbook (agents/plan-reviewer.md) step by step:\n` +
1432
2148
  ` Steps 1-2: inspect the DAG and check all quality criteria.\n` +
1433
2149
  ` Step 3: classify each task -- assign complexity bucket (S/M/L) and read its model\n` +
1434
- ` from beads metadata. If a task has no model metadata, note it in your verdict\n` +
1435
- ` notes as a warning but do NOT return CHANGES NEEDED for it -- the workflow has a fallback.\n` +
2150
+ ` from beads metadata. If a task has no model metadata, flag it as a criterion-10\n` +
2151
+ ` CHANGES_NEEDED finding per your runbook, and use the standard-tier fallback only\n` +
2152
+ ` to finish classifying/reporting in the same pass.\n` +
1436
2153
  ` Step 4: return verdict, notes, and taskAssignments (id + bucket + model per task).\n\n` +
1437
2154
  `Notes must be specific: include issue IDs and exact "bd dep add" commands to fix\n` +
1438
2155
  `any dependency direction problems.`,
@@ -1490,20 +2207,86 @@ while (cycleCount < maxCycles) {
1490
2207
  // ---------------------------------------------------------------- DEVELOP
1491
2208
 
1492
2209
  phase('Develop');
2210
+ await stamp(`develop-c${cycleCount}`);
2211
+
2212
+ // Phase checkpoint (heartbeat): plan approved for this cycle, entering develop.
2213
+ await writeSprintState(stateFileRel, { ..._stateBase, cycle: cycleCount, phase: 'Develop', planApproved: true }, 'Develop', `state-c${cycleCount}-dev`);
1493
2214
 
1494
2215
  const MAX_DEV_ITER = 20;
1495
2216
  let devIter = 0;
1496
2217
  let devFeedback = '';
2218
+ // Parallel-doer config (per-cycle, read once from healed calibration).
2219
+ const _par = (calibration && calibration.parallelism) || {};
2220
+ const maxDoers = Math.max(1, _par.max_doers || 1);
2221
+ const worktreeRoot = _par.worktree_root || '.auto-sprint/wt';
2222
+ // If a parallel iteration makes zero progress (every doer failed or every merge conflicted),
2223
+ // force the NEXT iteration onto the serial path. Serial doers commit directly on the sprint
2224
+ // branch (no cross-branch merge -> no merge conflict), guaranteeing forward progress and
2225
+ // preventing a same-batch conflict loop. Cleared as soon as a serial iteration runs.
2226
+ let forceSerialIter = false;
1497
2227
 
1498
2228
  while (devIter < MAX_DEV_ITER) {
1499
- const streakResult = await getReadyStreaks(rootIds);
2229
+ // Lock heartbeat: refresh the state file's mtime every develop iteration. A single
2230
+ // develop iteration (a doer batch + review) can exceed SPRINT_STATE_TTL_S; without a
2231
+ // heartbeat here the lock would "expire" mid-run and a second invocation on the same
2232
+ // branch could start concurrently and corrupt the shared checkout. Cheap relative to
2233
+ // the per-iteration doer/review dispatches.
2234
+ await writeSprintState(
2235
+ stateFileRel,
2236
+ { ..._stateBase, cycle: cycleCount, phase: 'Develop', planApproved: true },
2237
+ 'Develop',
2238
+ `heartbeat-c${cycleCount}-i${devIter}`,
2239
+ );
2240
+ let streakResult = await getReadyStreaks(rootIds);
2241
+ if (streakResult.extractFailed) {
2242
+ // A single failed/garbled extraction must never look identical to a confirmed
2243
+ // zero-ready result -- that ambiguity is what let one transient dispatch/parse
2244
+ // hiccup hard-abort an entire sprint on cycle 1 (apra-fleet e2e s10, 2026-07-17,
2245
+ // run 29605783512: the workflow itself ran fine, but a bad read made it look like
2246
+ // a dependency deadlock). Retry once, bounded, before trusting the result at all.
2247
+ log(`WARN: ready-task extraction failed at c${cycleCount} i${devIter} -- retrying once before treating as zero-ready`);
2248
+ streakResult = await getReadyStreaks(rootIds);
2249
+ }
2250
+ if (streakResult.totalCount === 0 && streakResult.extractFailed) {
2251
+ // Both reads failed -- we genuinely cannot tell if there's ready work. Do NOT
2252
+ // hard-abort on unreliable data; log loudly and let the next iteration/cycle
2253
+ // (or exit-check) retry with a fresh read instead of losing the whole sprint.
2254
+ log(`WARN: ready-task extraction failed twice at c${cycleCount} i${devIter} -- treating as inconclusive, not a deadlock`);
2255
+ break;
2256
+ }
1500
2257
  if (streakResult.totalCount === 0) {
2258
+ // Distinguish genuine completion from a dependency DEADLOCK. If the sprint subtree
2259
+ // still has open issues at/above the goal threshold but NONE are ready on the FIRST
2260
+ // develop iteration, surface it loudly with the blocked leaves (the "'missing issues'
2261
+ // when all P1s are dependency-blocked" failure). We HARD-ABORT only on the very first
2262
+ // cycle -- when the initial plan produced no workable leaves at all -- because that is
2263
+ // the true unrecoverable case. In LATER cycles a ready==0 first iteration is usually
2264
+ // just "this cycle's leaves are done"; the multi-cycle re-plan / exit-check self-heals
2265
+ // it, so we log the diagnostic but fall through instead of aborting (aborting there
2266
+ // would skip harvest and lose the PR for work already completed).
2267
+ if (devIter === 0) {
2268
+ const _open = await countBeadsBlockers(threshold, rootIds);
2269
+ if (_open.count > 0) {
2270
+ const _diag = await dispatchShell(
2271
+ [`bd list --status=open --type=task --json | node -e "const d=require('fs').readFileSync(0,'utf8');try{const a=JSON.parse(${BD_JSON}).map(i=>({id:i.id,blocked_by:i.blocked_by||i.dependencies||[]}));process.stdout.write(JSON.stringify(a).slice(0,1200))}catch{process.stdout.write('[]')}"`],
2272
+ { model: MODEL_HAIKU, label: `deadlock-diag-c${cycleCount}`, phase: 'Develop' }
2273
+ );
2274
+ const _diagText = `${_open.count} open issue(s) at/above ${goal} in the sprint subtree but NONE are ready on the first develop iteration. The dependency DAG may be blocked (commonly backwards or parent-child edges; note 'bd dep cycles' MISSES parent-child deadlocks -- inspect blocked_by on leaf tasks). Open leaf tasks + blocked_by: ${(_diag?.outputs?.[0] || '[]').trim()}`;
2275
+ if (cycleCount === 1) {
2276
+ log(`ERROR: DEADLOCK (cycle 1 plan produced no workable leaves) -- ${_diagText}`);
2277
+ abortReason = 'deadlock: plan produced open issues but no ready leaves';
2278
+ break;
2279
+ }
2280
+ // Later cycle: diagnostic only -- let the normal exit-check / next-cycle re-plan decide.
2281
+ log(`WARN: no ready leaves at cycle ${cycleCount} start though open issues remain -- ${_diagText}`);
2282
+ }
2283
+ }
1501
2284
  log(`No ready tasks -- develop phase complete (${devIter} iterations)`);
1502
2285
  break;
1503
2286
  }
1504
2287
  log(`Dev iter ${devIter} c${cycleCount}: ${streakResult.totalCount} ready task(s) across ${streakResult.streaks.length} model streak(s)`);
1505
2288
 
1506
- // Dispatch one doer per model streak; collect all worked task IDs for the reviewer.
2289
+ // Dispatch doers; collect all worked task IDs for the reviewer.
1507
2290
  const workedIds = [];
1508
2291
  let streakAbort = false;
1509
2292
  let doerNullReset = false;
@@ -1512,13 +2295,142 @@ while (cycleCount < maxCycles) {
1512
2295
  // last approved plan-review's taskAssignments held at workflow scope.
1513
2296
  const bucketById = Object.fromEntries((taskAssignments || []).map(t => [t.id, t.bucket]));
1514
2297
 
1515
- for (const streak of streakResult.streaks) {
2298
+ // ---- PARALLEL DOERS (worktree fan-out) ---------------------------------
2299
+ // When more than one bd-ready task exists and calibration allows width>1, work independent
2300
+ // ready tasks CONCURRENTLY, each in its own git worktree + temp branch off the current sprint
2301
+ // HEAD, then merge back sequentially with a conflict->re-queue fallback. bd-ready tasks are
2302
+ // DAG-independent, so the only risk is physical file overlap, handled at merge time. All beads
2303
+ // state transitions stay centralized here (doers run NO bd) so concurrent worktrees never
2304
+ // diverge the .beads DB. Degrades to the serial path for width==1, all-worktree-create-fail,
2305
+ // or after a zero-progress parallel iteration (forceSerialIter). Never worse than serial.
2306
+ const _effMaxDoers = forceSerialIter ? 1 : maxDoers;
2307
+ forceSerialIter = false;
2308
+ const _plan = computeDoerBatch(streakResult.streaks, _effMaxDoers);
2309
+ let parallelHandled = false;
2310
+
2311
+ if (_plan.width > 1) {
2312
+ const wt = _plan.batch.map(t => ({ ...t, ...worktreeNamesFor(branch, t.id, worktreeRoot) }));
2313
+ log(`Parallel develop: ${_plan.width} doer(s) in worktrees (${labelTaskIds(wt.map(w => w.id))})${_plan.deferred.length ? `; ${_plan.deferred.length} task(s) deferred to next iter` : ''}`);
2314
+
2315
+ // Create one worktree + temp branch per task (idempotent: clear any leaked prior worktree/
2316
+ // branch first). Each command echoes OK/FAIL <id> so we only work tasks that isolated cleanly.
2317
+ const createRes = await dispatchShell(
2318
+ wt.map(w =>
2319
+ `git -C "${repo}" worktree remove --force "${repo}/${w.path}" 2>/dev/null; ` +
2320
+ `git -C "${repo}" branch -D "${w.branch}" 2>/dev/null; ` +
2321
+ `git -C "${repo}" worktree add -b "${w.branch}" "${repo}/${w.path}" "${branch}" >/dev/null 2>&1 && echo "OK ${w.id}" || echo "FAIL ${w.id}"`
2322
+ ),
2323
+ { model: MODEL_HAIKU, label: `wt-create-c${cycleCount}-i${devIter}`, phase: 'Develop', maxTurns: wt.length + 2 }
2324
+ );
2325
+ const createdOk = {};
2326
+ (createRes?.outputs || []).forEach((o, i) => { if (/\bOK\b/.test(o || '')) createdOk[wt[i].id] = true; });
2327
+ const okWt = wt.filter(w => createdOk[w.id]);
2328
+
2329
+ if (okWt.length === 0) {
2330
+ log(`All worktree creations failed -- falling back to serial for this iteration`);
2331
+ await dispatchShell(
2332
+ wt.flatMap(w => [
2333
+ `git -C "${repo}" worktree remove --force "${repo}/${w.path}" 2>/dev/null || true`,
2334
+ `git -C "${repo}" branch -D "${w.branch}" 2>/dev/null || true`,
2335
+ ]),
2336
+ { model: MODEL_HAIKU, label: `wt-cleanup-c${cycleCount}-i${devIter}`, phase: 'Develop' }
2337
+ );
2338
+ } else {
2339
+ parallelHandled = true;
2340
+ // Read each task's spec centrally (human-readable bd show) and INLINE it into the doer
2341
+ // prompt, so doers need no bd access inside their worktree (worktree .beads DB may be
2342
+ // stale or absent across the hundreds of projects this runs on).
2343
+ const specRes = await dispatchShell(
2344
+ okWt.map(w => `bd show ${w.id}`),
2345
+ { model: MODEL_HAIKU, label: `spec-c${cycleCount}-i${devIter}`, phase: 'Develop', maxTurns: okWt.length + 2 }
2346
+ );
2347
+ const specById = {};
2348
+ okWt.forEach((w, i) => { specById[w.id] = ((specRes?.outputs?.[i]) || '').trim().slice(0, 4000); });
2349
+
2350
+ // Claim the batch centrally (single source of truth), then fan out doers.
2351
+ await dispatchShell(okWt.map(w => `bd update ${w.id} --claim`),
2352
+ { model: MODEL_HAIKU, label: `claim-c${cycleCount}-i${devIter}`, phase: 'Develop', maxTurns: okWt.length + 2 });
2353
+
2354
+ const doerOutcomes = await parallel(okWt.map(w =>
2355
+ dispatch(
2356
+ `You are working in an ISOLATED git worktree -- other doers run concurrently in their own worktrees.\n` +
2357
+ `Worktree path: ${repo}/${w.path} (cd into it first; you are on temp branch ${w.branch})\n` +
2358
+ `Work ONLY task ${w.id}. Do NOT work any other task.\n\n` +
2359
+ (devFeedback
2360
+ ? `Reviewer feedback from the previous iteration (also in feedback.md at ${repo}):\n${devFeedback}\nAddress every relevant finding.\n\n`
2361
+ : '') +
2362
+ `Task ${w.id} specification:\n${specById[w.id] || '(spec unavailable; infer from the repo and task id)'}\n\n` +
2363
+ `Steps:\n` +
2364
+ ` - Implement the work for task ${w.id} INSIDE ${repo}/${w.path} ONLY (code, tests, config -- whatever it requires).\n` +
2365
+ ` - Commit in that worktree: git -C "${repo}/${w.path}" add -A && git -C "${repo}/${w.path}" -c user.name='doer' -c user.email='doer@pm.local' commit -m "impl ${w.id}"\n` +
2366
+ ` - Do NOT run ANY bd command. Do NOT touch the main checkout or the ${branch} branch. Do NOT push. Do NOT run git merge.\n` +
2367
+ `Return status "VERIFY" when done. Return status "BLOCKED" only for your runbook's blocked cases (missing secret) -- never any other status.`,
2368
+ { model: w.model, label: `doer-c${cycleCount}-i${devIter}-${w.id}`, phase: 'Develop', schema: DOER_STATUS_SCHEMA,
2369
+ agentType: 'doer', context: `task ${w.id} (worktree)` }
2370
+ ).then(r => ({ w, ok: !!r && r.status === 'VERIFY' })).catch(() => ({ w, ok: false }))
2371
+ ));
2372
+
2373
+ // Merge sequentially into the sprint branch (deterministic id order from computeDoerBatch).
2374
+ // Clean merge -> close centrally; conflict or doer failure -> re-queue centrally.
2375
+ for (const { w, ok } of doerOutcomes) {
2376
+ if (!ok) {
2377
+ await dispatchShell([`bd update ${w.id} --status=open`],
2378
+ { model: MODEL_HAIKU, label: `requeue-${w.id}-c${cycleCount}-i${devIter}`, phase: 'Develop' });
2379
+ log(`Doer failed for ${w.id} -- re-queued (will retry next iter)`);
2380
+ continue;
2381
+ }
2382
+ const mres = await dispatchShell(
2383
+ [`git -C "${repo}" merge --no-ff --no-edit "${w.branch}" >/dev/null 2>&1 && echo MERGE_OK || (git -C "${repo}" merge --abort >/dev/null 2>&1; echo MERGE_CONFLICT)`],
2384
+ { model: MODEL_HAIKU, label: `merge-${w.id}-c${cycleCount}-i${devIter}`, phase: 'Develop' }
2385
+ );
2386
+ if (/MERGE_OK/.test((mres?.outputs?.[0]) || '')) {
2387
+ await dispatchShell([`bd close ${w.id}`],
2388
+ { model: MODEL_HAIKU, label: `close-${w.id}-c${cycleCount}-i${devIter}`, phase: 'Develop' });
2389
+ workedIds.push(w.id);
2390
+ log(`Merged + closed ${w.id}`);
2391
+ } else {
2392
+ await dispatchShell([`bd update ${w.id} --status=open`],
2393
+ { model: MODEL_HAIKU, label: `conflict-${w.id}-c${cycleCount}-i${devIter}`, phase: 'Develop' });
2394
+ log(`Merge conflict for ${w.id} -- aborted, re-queued (degrades to serial as ready count drops)`);
2395
+ }
2396
+ }
2397
+
2398
+ // Always tear down every worktree + temp branch (even failed ones): a leak must never
2399
+ // block the next iteration's idempotent create.
2400
+ await dispatchShell(
2401
+ wt.flatMap(w => [
2402
+ `git -C "${repo}" worktree remove --force "${repo}/${w.path}" 2>/dev/null || true`,
2403
+ `git -C "${repo}" branch -D "${w.branch}" 2>/dev/null || true`,
2404
+ ]),
2405
+ { model: MODEL_HAIKU, label: `wt-cleanup-c${cycleCount}-i${devIter}`, phase: 'Develop', maxTurns: wt.length * 2 + 2 }
2406
+ );
2407
+
2408
+ // Zero progress this parallel iteration (all failed / all conflicted): force serial next
2409
+ // iteration so a same-batch conflict cannot loop forever.
2410
+ if (workedIds.length === 0) {
2411
+ forceSerialIter = true;
2412
+ log(`Parallel iteration closed 0 tasks -- forcing serial path next iteration to guarantee progress`);
2413
+ }
2414
+ }
2415
+ }
2416
+
2417
+ for (const streak of (parallelHandled ? [] : streakResult.streaks)) {
1516
2418
  // Truncate the streak to the longest prefix that fits the doer token ceiling for
1517
2419
  // this tier. Remaining IDs are left unworked and resurface on the next
1518
2420
  // getReadyStreaks iteration.
1519
- const fittedIds = truncateStreakToCeiling(streak.ids, bucketById, calibration, streak.model);
2421
+ // Fit the streak by BOTH the output-token ceiling AND the predicted context window,
2422
+ // taking the more restrictive prefix. The context predictor proactively splits a
2423
+ // streak that would exceed the doer's usable context (below the autocompact/session
2424
+ // limit) -- pre-empting the "doer exhausts context -> returns null -> work lost"
2425
+ // failure. Deferred tasks resurface on the next getReadyStreaks iteration (lossless).
2426
+ const _ceilFit = truncateStreakToCeiling(streak.ids, bucketById, calibration, streak.model);
2427
+ const _ctxFit = fitStreakToContext(streak.ids, bucketById, calibration, streak.model);
2428
+ const fittedIds = _ceilFit.length <= _ctxFit.fittedIds.length ? _ceilFit : _ctxFit.fittedIds;
1520
2429
  if (fittedIds.length < streak.ids.length) {
1521
- log(`Streak ${streak.model} truncated to token ceiling: working ${fittedIds.length}/${streak.ids.length} task(s) (${labelTaskIds(fittedIds)}); ${streak.ids.length - fittedIds.length} deferred`);
2430
+ const _reason = _ctxFit.fittedIds.length < _ceilFit.length
2431
+ ? `context-limited (est ${Math.round(_ctxFit.estContext)} tok > usable ${Math.round(_ctxFit.available)} tok)`
2432
+ : `token ceiling`;
2433
+ log(`Streak ${streak.model} split by ${_reason}: working ${fittedIds.length}/${streak.ids.length} task(s) (${labelTaskIds(fittedIds)}); ${streak.ids.length - fittedIds.length} deferred`);
1522
2434
  }
1523
2435
  const doerLabel = `doer-c${cycleCount}-i${devIter}: ${labelTaskIds(fittedIds)}`;
1524
2436
  const streakEstUsd = sprintQuote
@@ -1543,14 +2455,15 @@ while (cycleCount < maxCycles) {
1543
2455
  ` - Closed tasks are durable even if the doer crashes mid-streak\n` +
1544
2456
  ` - NEVER close a type=feature or type=bug issue -- only close type=task\n` +
1545
2457
  `Work all listed tasks then stop and return status "VERIFY".\n` +
1546
- `Always return VERIFY -- never return anything else.`,
2458
+ `Return status "BLOCKED" only for your runbook's blocked cases (agents/doer.md:\n` +
2459
+ `missing secret, unspecified branch) -- never any other status.`,
1547
2460
  { model: streak.model, label: doerLabel, phase: 'Develop', schema: DOER_STATUS_SCHEMA, agentType: 'doer',
1548
2461
  context: `tasks ${fittedIds.join(', ')}` }
1549
2462
  );
1550
2463
 
1551
2464
  if (!doerResult) {
1552
2465
  log(`Doer returned null (streak ${streak.model}) -- resetting orphaned in_progress tasks and retrying`);
1553
- const _ipExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.parse(d).map(i=>i.id).join(' '))}catch{}"`;
2466
+ const _ipExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.parse(${BD_JSON}).map(i=>i.id).join(' '))}catch{}"`;
1554
2467
  const ipResult = await dispatchShell(
1555
2468
  [`bd list --status=in_progress --type=task --json | ${_ipExtract}`],
1556
2469
  { model: MODEL_HAIKU, label: `reset-orphans-c${cycleCount}-i${devIter}`, phase: 'Develop' }
@@ -1566,8 +2479,17 @@ while (cycleCount < maxCycles) {
1566
2479
  }
1567
2480
 
1568
2481
  if (doerResult.status !== 'VERIFY') {
1569
- log(`Unexpected doer status "${doerResult.status}" -- aborting`);
1570
- abortReason = 'unexpected doer status';
2482
+ const _doerNotes = (doerResult.notes || '').slice(0, 200);
2483
+ if (doerResult.status === 'BLOCKED') {
2484
+ // Contract case (doer-output.json enum): the doer hit a runbook blocker
2485
+ // (missing secret/branch). Not a malfunction -- abort with the blocker so the
2486
+ // user can resolve it and re-run.
2487
+ log(`Doer BLOCKED (streak ${streak.model}): ${_doerNotes || 'no details'} -- aborting sprint`);
2488
+ abortReason = `doer blocked: ${_doerNotes || 'no details'}`;
2489
+ } else {
2490
+ log(`Unexpected doer status "${doerResult.status}" -- aborting`);
2491
+ abortReason = 'unexpected doer status';
2492
+ }
1571
2493
  streakAbort = true;
1572
2494
  break;
1573
2495
  }
@@ -1577,6 +2499,13 @@ while (cycleCount < maxCycles) {
1577
2499
  devIter++;
1578
2500
  if (doerNullReset) continue;
1579
2501
  if (streakAbort) break;
2502
+ if (workedIds.length === 0) {
2503
+ // No task merged this iteration (e.g. every parallel merge conflicted and re-queued).
2504
+ // Nothing to review; loop back -- getReadyStreaks re-derives work and forceSerialIter
2505
+ // (set above) guarantees the next iteration makes progress.
2506
+ log(`No tasks merged this iteration -- skipping reviewer, re-deriving ready work`);
2507
+ continue;
2508
+ }
1580
2509
 
1581
2510
  // Reviewer tier matches the highest tier used across all streaks:
1582
2511
  // any premium streak -> premium; otherwise standard (cheap work reviewed at standard minimum).
@@ -1593,8 +2522,10 @@ while (cycleCount < maxCycles) {
1593
2522
  `Run: git -C "${repo}" diff ${base_branch}...${branch} to see the changes.\n` +
1594
2523
  `Do NOT comment on code or issues outside the listed tasks.\n` +
1595
2524
  `Check: code correctness, test coverage, adherence to each task's acceptance criteria.\n` +
1596
- `If a task needs rework, reopen it: bd update <id> --status=open\n` +
1597
- `CHANGES NEEDED verdict must include specific actionable feedback tied to a task ID.\n` +
2525
+ `Follow your runbook (agents/reviewer.md): run NO bd mutations yourself. If a task\n` +
2526
+ `needs rework, list its id in reopenIds in your structured output -- the workflow\n` +
2527
+ `applies the reopen transitions for you.\n` +
2528
+ `CHANGES_NEEDED verdict must include specific actionable feedback tied to a task ID.\n` +
1598
2529
  `APPROVED means all committed work meets acceptance criteria.`,
1599
2530
  { model: reviewerModel, label: reviewerLabel, phase: 'Develop', schema: REVIEW_SCHEMA, agentType: 'reviewer',
1600
2531
  context: `reviewing tasks ${workedIds.join(', ')}` }
@@ -1604,6 +2535,34 @@ while (cycleCount < maxCycles) {
1604
2535
  if (!approved(review)) {
1605
2536
  devFeedback = (review && review.notes) || '';
1606
2537
  log(`Reviewer feedback: ${devFeedback.slice(0, 120)}`);
2538
+
2539
+ // Apply the reviewer's structured verdict. The reviewer is a pure reader of
2540
+ // beads (agents/reviewer.md: never bd update/close/create) -- the WORKFLOW owns
2541
+ // the reopen/create transitions, otherwise CHANGES_NEEDED tasks stay closed and
2542
+ // the next iteration exits Develop as if the review had passed.
2543
+ const _reopenAll = Array.isArray(review && review.reopenIds) ? review.reopenIds : [];
2544
+ const _reopenIds = _reopenAll.filter(id => workedIds.includes(id));
2545
+ if (_reopenAll.length > _reopenIds.length) {
2546
+ log(`Reviewer listed ${_reopenAll.length - _reopenIds.length} reopenId(s) outside this iteration's worked tasks -- ignored`);
2547
+ }
2548
+ const _newTasks = Array.isArray(review && review.newTasks) ? review.newTasks : [];
2549
+ const _shQuote = s => String(s || '').replace(/"/g, "'");
2550
+ const _prioNum = p => { const m = String(p || '').match(/[0-4]/); return m ? m[0] : '2'; };
2551
+ const applyCmds = [
2552
+ ..._reopenIds.map(id => `bd update ${id} --status=open`),
2553
+ ..._newTasks.map(t =>
2554
+ `bd create --title="${_shQuote(t.title || 'review follow-up').slice(0, 120)}" ` +
2555
+ `--description="${_shQuote(t.description).slice(0, 500)}" ` +
2556
+ `--type=task --priority=${_prioNum(t.priority)} --parent=${rootIds[0]}`
2557
+ ),
2558
+ ];
2559
+ if (applyCmds.length > 0) {
2560
+ await dispatchShell(applyCmds, {
2561
+ model: MODEL_HAIKU, label: `review-apply-c${cycleCount}-i${devIter}`, phase: 'Develop',
2562
+ maxTurns: applyCmds.length + 2,
2563
+ });
2564
+ log(`Applied review verdict: ${_reopenIds.length} task(s) reopened, ${_newTasks.length} follow-up task(s) created`);
2565
+ }
1607
2566
  // Fire-and-forget: write feedback.md to disk only -- next doer's 'git add -A' picks it up.
1608
2567
  // The plan-reviewer commitFeedback (below) MUST remain awaited and commit+push so the
1609
2568
  // planner can read it from remote. Dev-path feedback is local-only.
@@ -1642,69 +2601,74 @@ while (cycleCount < maxCycles) {
1642
2601
 
1643
2602
  if (integTestEnabled) {
1644
2603
  phase('Test');
2604
+ await stamp(`test-c${cycleCount}`);
1645
2605
 
1646
2606
  // -- Deploy --
2607
+ // Role split (agents/deployer.md, agents/integ-test-runner.md): the deployer follows
2608
+ // deploy.md ONLY (deploy + smoke test) -- the playbook's Setup/Reset/Teardown belong
2609
+ // to integ-test-runner, which owns integ-test-playbook.md end to end. The deployer
2610
+ // refuses playbook operations by contract, so never dispatch them to it.
1647
2611
  const deployLabel = `deployer-c${cycleCount}`;
1648
2612
  const deployResult = await dispatch(
1649
- `Repo: ${repo}\nBranch: ${branch}\nCycle: ${cycleCount}\n\n` +
1650
- `Follow the integration test playbook and deploy.md:\n` +
1651
- (cycleCount === 1
1652
- ? `1. Run the Setup section of integ-test-playbook.md to bring up the test environment.\n`
1653
- : `1. Run the Reset section of integ-test-playbook.md to restore pristine state.\n`) +
1654
- `2. Follow all steps in deploy.md to deploy the build.\n` +
1655
- `3. Run the smoke test defined in deploy.md.\n` +
1656
- `4. Return deployed: true if the smoke test passes, false otherwise.\n` +
2613
+ `Repo: ${repo}\nBranch: ${branch}\nCycle: ${cycleCount}\n` +
2614
+ `operation: deploy\n\n` +
2615
+ `Follow your runbook (agents/deployer.md) -- deploy.md ONLY; you do not touch\n` +
2616
+ `integ-test-playbook.md (its Setup/Reset/Teardown belong to integ-test-runner):\n` +
2617
+ `1. Read deploy.md (Deploy, Smoke test, and CI sections).\n` +
2618
+ `2. Execute every command in the '## Deploy' section in order.\n` +
2619
+ `3. Run the command in '## Smoke test'.\n` +
2620
+ `4. Return deployed: true if the smoke test exits 0, false otherwise.\n` +
1657
2621
  `5. If deployed is false, include the error output in notes.`,
1658
2622
  { model: MODEL_SONNET, label: deployLabel, phase: 'Test', agentType: 'deployer',
1659
- schema: { type: 'object', required: ['deployed'], properties: {
1660
- deployed: { type: 'boolean' }, notes: { type: 'string' } } } }
2623
+ schema: DEPLOYER_SCHEMA }
1661
2624
  );
1662
2625
 
1663
2626
  if (!deployResult || !deployResult.deployed) {
1664
2627
  const msg = (deployResult && deployResult.notes) || 'no details';
1665
2628
  log(`Deploy failed on cycle ${cycleCount}: ${msg.slice(0, 200)}`);
1666
- log('Skipping integration tests this cycle -- teardown and continue');
1667
- // Teardown before next cycle
1668
- await dispatch(
1669
- `Run the Teardown section of integ-test-playbook.md to clean up the test environment.`,
1670
- { model: MODEL_SONNET, label: `teardown-c${cycleCount}-fail`, phase: 'Test', agentType: 'deployer' }
1671
- );
2629
+ log('Skipping integration tests this cycle -- the test sandbox was never brought up (integ-test-runner owns it), nothing to tear down');
1672
2630
  } else {
1673
- // -- Integration test run --
2631
+ // -- Integration test run (scoped to THIS sprint's open features) --
2632
+ // Scope the tester to the sprint subtree's open features. Do NOT let it `bd list
2633
+ // --type=feature --status=open` (every open feature in the whole DB) -- that would
2634
+ // test/close/file-bugs against unrelated features from other epics/sprints.
2635
+ // An EMPTY feature list still dispatches the runner: the playbook's two parts are
2636
+ // the sprint's standing confidence check (integ-test-runner.md Step 1).
2637
+ const _sprintFeatures = await getSprintOpenFeatures(rootIds);
1674
2638
  const integLabel = `integ-runner-c${cycleCount}`;
2639
+ const _featList = _sprintFeatures.length > 0
2640
+ ? _sprintFeatures.map(f => ` ${f.id} -- ${f.title}`).join('\n')
2641
+ : ` (none -- zero open features this cycle; a normal outcome, run the playbook parts only)`;
2642
+ log(`Integration scope: ${_sprintFeatures.length} sprint feature(s)${_sprintFeatures.length ? ` [${labelTaskIds(_sprintFeatures.map(f => f.id))}]` : ''}`);
1675
2643
 
1676
2644
  const integResult = await dispatch(
1677
2645
  `Repo: ${repo}\nBranch: ${branch}\nCycle: ${cycleCount}\n` +
1678
2646
  `Sprint goals: ${rootSummary}\n\n` +
1679
- `Run: bd list --type=feature --status=open\n` +
1680
- `For each open feature, execute its integration tests.\n\n` +
1681
- `For each feature:\n` +
1682
- ` PASS: all tests pass -> bd close <feature-id>\n` +
1683
- ` FAIL: tests fail -> bd create --title="[integ] <description>" ` +
1684
- `--description="Feature: <id>\\nExpected: <what>\\nActual: <what>\\nTest: <which>" ` +
1685
- `--type=bug --priority=<1=core requirement unmet, 2=partial, 3=quality>\n` +
1686
- ` Keep feature open on failure or if inconclusive.\n\n` +
1687
- `Priority rules:\n` +
1688
- ` P0: system won't start or core path completely broken\n` +
1689
- ` P1: requirement from sprint goal explicitly not met\n` +
1690
- ` P2: requirement partially met, degraded behaviour\n` +
1691
- ` P3: quality, performance, or UX issue not blocking core function\n\n` +
1692
- `Before creating a new bug, check bd search "[integ]" -- update existing if duplicate.\n\n` +
1693
- `Return featuresClosed (count), issuesCreated (count), summary (one paragraph).`,
2647
+ `Follow your runbook (agents/integ-test-runner.md). You own integ-test-playbook.md\n` +
2648
+ `end to end: run part 1 (the real functional suite), bring the sandbox up with the\n` +
2649
+ `playbook's ${cycleCount === 1 ? '## Setup' : '## Reset'} section, run the smoke scenario and the per-feature\n` +
2650
+ `tests inside it, and ALWAYS run the playbook's ## Teardown before returning --\n` +
2651
+ `pass or fail. The product deploy (deploy.md) has already been done by the deployer.\n\n` +
2652
+ `Integration-test ONLY these open features from THIS sprint. Do NOT list, test, close, ` +
2653
+ `or file bugs against any beads issue that is not in this list (do NOT run ` +
2654
+ `"bd list --type=feature"):\n${_featList}\n\n` +
2655
+ `Per-feature testing (bd show -> run its tests -> bd close on pass, keep open on ` +
2656
+ `failure/inconclusive), [integ] bug filing, priority rules, and duplicate checks ` +
2657
+ `(bd search "[integ]") are all in your runbook -- follow it. Parent every new ` +
2658
+ `[integ] bug under sprint root ${rootIds[0]} (the scope for this dispatch).\n\n` +
2659
+ `Return the full contract: featuresClosed (count), issuesCreated (count), ` +
2660
+ `passed (boolean), bugsFiled (array of created bug ids, [] if none), ` +
2661
+ `summary (one paragraph, including the part 1 result line).`,
1694
2662
  { model: MODEL_SONNET, label: integLabel, phase: 'Test', schema: INTEG_RUN_SCHEMA, agentType: 'integ-test-runner' }
1695
2663
  );
1696
2664
  if (integResult) {
1697
- log(`Integration: ${integResult.featuresClosed} features closed, ${integResult.issuesCreated} issues created`);
2665
+ log(`Integration: ${integResult.featuresClosed} features closed, ${integResult.issuesCreated} issues created, passed=${integResult.passed}`);
1698
2666
  log(`Summary: ${integResult.summary}`);
1699
2667
  }
1700
2668
 
1701
- // -- Teardown --
1702
- await dispatch(
1703
- `Run the Teardown section of integ-test-playbook.md to fully clean up the test environment.`,
1704
- { model: MODEL_SONNET, label: `teardown-c${cycleCount}`, phase: 'Test', agentType: 'deployer' }
1705
- );
1706
-
1707
- // JIT flush: append test-phase entries (deployer, integ-runner, teardown) immediately.
2669
+ // JIT flush: append test-phase entries (deployer, integ-runner) immediately.
2670
+ // No separate teardown dispatch: the runner runs the playbook's Teardown itself,
2671
+ // always, before returning (agents/integ-test-runner.md Step 4).
1708
2672
  await appendNewEntries(`test-c${cycleCount}`, 'Test');
1709
2673
  }
1710
2674
  }
@@ -1719,9 +2683,9 @@ while (cycleCount < maxCycles) {
1719
2683
 
1720
2684
  let blockers;
1721
2685
  {
1722
- const _idExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.parse(d).issues.map(i=>i.id).join(' '))}catch{}"`;
1723
- const _openExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.stringify(JSON.parse(d).map(i=>({id:i.id,p:i.priority}))))}catch{console.log('[]')}"`;
1724
- const _taskExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.stringify(JSON.parse(d).map(i=>({id:i.id,p:i.priority,m:(i.metadata||{}).model}))))}catch{console.log('[]')}"`;
2686
+ const _idExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{const g=JSON.parse(${BD_JSON});${bdSubtreeSnippet(rootIds)}console.log(Array.from(subtree).join(' '))}catch{}"`;
2687
+ const _openExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.stringify(JSON.parse(${BD_JSON}).map(i=>({id:i.id,p:i.priority}))))}catch{console.log('[]')}"`;
2688
+ const _taskExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.stringify(JSON.parse(${BD_JSON}).map(i=>({id:i.id,p:i.priority,m:(i.metadata||{}).model}))))}catch{console.log('[]')}"`;
1725
2689
  const exitCmds = [
1726
2690
  ...rootIds.map(id => `bd graph --json ${id} | ${_idExtract}`),
1727
2691
  `bd list --status=open --json | ${_openExtract}`,
@@ -1732,7 +2696,7 @@ while (cycleCount < maxCycles) {
1732
2696
  blockers = parseBlockers(exitResult.outputs, rootIds.length, rootIds.length, threshold, rootIds);
1733
2697
  // Ready streaks prefetched but not used: develop loop already determined no ready tasks.
1734
2698
  // Parsed here to validate the merged output; result discarded at cycle end.
1735
- parseReadyStreaks(exitResult.outputs, rootIds.length, rootIds.length + 1, TIER_STANDARD);
2699
+ parseReadyStreaks(exitResult.outputs, rootIds.length, rootIds.length + 1, TIER_STANDARD, rootIds);
1736
2700
  } else {
1737
2701
  // Fallback: outputs too short (agent returned partial results) -- use separate dispatches.
1738
2702
  log('exit-check: outputs.length < rootCount+2 -- falling back to separate dispatches');
@@ -1772,6 +2736,25 @@ while (cycleCount < maxCycles) {
1772
2736
  // ------------------------------------------------------------------ FINAL REVIEW
1773
2737
 
1774
2738
  phase('Harvest');
2739
+ await stamp('harvest');
2740
+
2741
+ // Remove sprint process-scaffold files (feedback.md, requirements.md) BEFORE the final review.
2742
+ // These are written during plan/develop review iterations and can be swept into a commit by a
2743
+ // doer's `git add -A`. If they survive into the harvest diff, the final reviewer correctly
2744
+ // rejects the sprint ("stray file would pollute the PR"), which blocks PR creation AND the
2745
+ // downstream bd-export -- cascading into pr-exists / final-changeset-clean / beads-sprint-closed
2746
+ // failures even when the actual goal was met. The later beads-export-cleanup step also strips
2747
+ // them, but that runs only AFTER an APPROVED review, so the cleanup must also happen up front.
2748
+ await dispatchShell(
2749
+ [
2750
+ `git -C "${repo}" rm -f --ignore-unmatch feedback.md requirements.md 2>/dev/null; ` +
2751
+ `rm -f "${repo}/feedback.md" "${repo}/requirements.md" 2>/dev/null; ` +
2752
+ `if git -C "${repo}" diff --cached --quiet; then echo "no process files staged"; else ` +
2753
+ `git -C "${repo}" -c user.name='pm' -c user.email='pm@pm.local' commit -m "chore: remove sprint process files before harvest" && ` +
2754
+ `git -C "${repo}" push origin ${branch}; fi`,
2755
+ ],
2756
+ { model: MODEL_HAIKU, label: `harvest-clean-process-files-c${cycleCount}`, phase: 'Harvest', maxTurns: 4 }
2757
+ );
1775
2758
 
1776
2759
  const finalReviewLabel = 'final-reviewer';
1777
2760
  const finalReview = await dispatch(
@@ -1784,7 +2767,7 @@ const finalReview = await dispatch(
1784
2767
  ` - Are there obvious gaps or regressions?\n` +
1785
2768
  ` - Is the codebase in a releasable state for what was completed?\n` +
1786
2769
  `APPROVED means the work is ready to harvest and raise as a PR.\n` +
1787
- `CHANGES NEEDED means critical issues were found; include specific findings in notes.`,
2770
+ `CHANGES_NEEDED means critical issues were found; include specific findings in notes.`,
1788
2771
  { model: MODEL_OPUS, label: finalReviewLabel, phase: 'Harvest', schema: REVIEW_SCHEMA, agentType: 'reviewer' }
1789
2772
  );
1790
2773
  log(`Final review: ${finalReview && finalReview.verdict || 'null'}`);
@@ -1792,6 +2775,7 @@ log(`Final review: ${finalReview && finalReview.verdict || 'null'}`);
1792
2775
  if (!approved(finalReview)) {
1793
2776
  const notes = (finalReview && finalReview.notes) || '';
1794
2777
  log(`Final review not approved -- aborting before harvest. Notes: ${notes.slice(0, 300)}`);
2778
+ await clearSprintState(stateFileRel, 'state-clear-finalrejected');
1795
2779
  return { cycles: cycleCount, goalMet, goal, abortReason: abortReason || 'final review rejected', finalReviewNotes: notes };
1796
2780
  }
1797
2781
 
@@ -1809,15 +2793,15 @@ const tasksCompleted = goalMet
1809
2793
  : Math.max(0, (sprintQuote ? sprintQuote.tasks.length : 0) - prevOpenIds.length);
1810
2794
  const tasksOpen = goalMet ? 0 : prevOpenIds.length;
1811
2795
  const sprintSummary = buildSprintSummary(sprintAnalysis, sprintQuote, calibration, {
1812
- branch, goal, goalMet, cycleCount, tasksCompleted, tasksOpen, startedAt: setup.startedAt,
2796
+ branch, goal, goalMet, cycleCount, tasksCompleted, tasksOpen, startedAt: effectiveStartedAt,
1813
2797
  });
1814
2798
  // Append Sprint Execution Summary section -- emitted regardless of goalMet.
1815
2799
  const executionSummary = buildExecutionSummary(logEntries, {
1816
- cycleCount, goalMet, goal, tasksOpen, openIssueIds: prevOpenIds, startedAt: setup.startedAt,
2800
+ cycleCount, goalMet, goal, tasksOpen, openIssueIds: prevOpenIds, startedAt: effectiveStartedAt,
1817
2801
  });
1818
2802
  sprintSummary.summaryText += '\n' + executionSummary.summaryText;
1819
2803
  log('Sprint summary:\n' + sprintSummary.summaryText);
1820
- const analysisArtifactFile = `sprint-logs/${sprintLogBranch}-${setup.startedAt}.analysis.md`;
2804
+ const analysisArtifactFile = `sprint-logs/${sprintLogBranch}-${effectiveStartedAt}.analysis.md`;
1821
2805
 
1822
2806
  const harvestLabel = 'harvester';
1823
2807
  const harvestResult = await dispatch(
@@ -1849,11 +2833,12 @@ if (!harvestResult || harvestResult.status !== 'OK') {
1849
2833
  `mkdir -p "${repo}/sprint-logs"`,
1850
2834
  `printf '%s' '${safeContent}' > "${repo}/${analysisArtifactFile}"`,
1851
2835
  `git -C "${repo}" add "${analysisArtifactFile}"`,
1852
- `git -C "${repo}" -c user.name='pm' -c user.email='pm@pm.local' commit --allow-empty -m "chore: sprint-analysis fallback ${branch} ${setup.startedAt}"`,
2836
+ `git -C "${repo}" -c user.name='pm' -c user.email='pm@pm.local' commit --allow-empty -m "chore: sprint-analysis fallback ${branch} ${effectiveStartedAt}"`,
1853
2837
  ],
1854
2838
  { model: MODEL_HAIKU, label: 'harvest-analysis-fallback', phase: 'Harvest' }
1855
2839
  );
1856
2840
  log(`Analysis artifact written via fallback: ${analysisArtifactFile}`);
2841
+ await clearSprintState(stateFileRel, 'state-clear-harvestfailed');
1857
2842
  return { cycles: cycleCount, goalMet, goal, harvest: 'failed' };
1858
2843
  }
1859
2844
 
@@ -1863,7 +2848,7 @@ if (!harvestResult || harvestResult.status !== 'OK') {
1863
2848
  // The doer closes tasks; the original sprint-goal epics must be closed explicitly.
1864
2849
  // These have no data dependency between them, so run in parallel.
1865
2850
 
1866
- const updatedCalibration = computeUpdatedCalibration(calibration, sprintAnalysis, setup.startedAt, taskAssignments, logEntries);
2851
+ const updatedCalibration = computeUpdatedCalibration(calibration, sprintAnalysis, effectiveStartedAt, taskAssignments, logEntries);
1867
2852
  const calibrationJson = JSON.stringify(updatedCalibration, null, 2);
1868
2853
 
1869
2854
  await parallel([
@@ -1898,7 +2883,7 @@ await dispatch(
1898
2883
  `Persist beads state and clean sprint scaffolding from the PR diff.\n\n` +
1899
2884
  `Step 1 -- Stage sprint-logs and evict scaffold files from the working tree (unconditional):\n` +
1900
2885
  ` git -C "${repo}" add sprint-logs/\n` +
1901
- ` git -C "${repo}" rm -f feedback.md requirements.md 2>/dev/null || true\n` +
2886
+ ` git -C "${repo}" rm -f --ignore-unmatch feedback.md requirements.md 2>/dev/null || true\n` +
1902
2887
  ` rm -f "${repo}/feedback.md" "${repo}/requirements.md" 2>/dev/null || true\n\n` +
1903
2888
  `Step 2 -- Export beads state:\n` +
1904
2889
  ` bd export -o "${repo}/.beads/issues.jsonl"\n` +
@@ -1929,17 +2914,23 @@ await dispatch(
1929
2914
 
1930
2915
  // Sync beads Dolt remote so refs/dolt/data is up to date.
1931
2916
  // Non-fatal: a missing remote or network error must not abort harvest.
1932
- await dispatch(
1933
- `Sync beads state to the Dolt remote.\n\n` +
1934
- `Run:\n` +
1935
- ` bd dolt push\n\n` +
1936
- `Capture stdout and stderr. If the command exits 0, log "bd dolt push: OK".\n` +
1937
- `If the command exits non-zero (e.g. no dolt remote configured, network error), log a warning:\n` +
1938
- ` "bd dolt push failed (non-fatal): <reason>"\n` +
1939
- `and continue -- do NOT throw, return an error, or abort the workflow.\n\n` +
1940
- `Return "OK" when done (regardless of whether the push succeeded or failed).`,
1941
- { model: MODEL_HAIKU, label: 'dolt-push', phase: 'Harvest' }
1942
- );
2917
+ // Skippable via the optional skip_dolt_push arg (the e2e passes it so sprints never
2918
+ // write to a real Dolt remote on GitHub).
2919
+ if (!opts.skip_dolt_push) {
2920
+ await dispatch(
2921
+ `Sync beads state to the Dolt remote.\n\n` +
2922
+ `Run:\n` +
2923
+ ` bd dolt push\n\n` +
2924
+ `Capture stdout and stderr. If the command exits 0, log "bd dolt push: OK".\n` +
2925
+ `If the command exits non-zero (e.g. no dolt remote configured, network error), log a warning:\n` +
2926
+ ` "bd dolt push failed (non-fatal): <reason>"\n` +
2927
+ `and continue -- do NOT throw, return an error, or abort the workflow.\n\n` +
2928
+ `Return "OK" when done (regardless of whether the push succeeded or failed).`,
2929
+ { model: MODEL_HAIKU, label: 'dolt-push', phase: 'Harvest' }
2930
+ );
2931
+ } else {
2932
+ log('Skipping dolt push as requested by opts.skip_dolt_push.');
2933
+ }
1943
2934
 
1944
2935
  // ------------------------------------------------------------------ PR
1945
2936
 
@@ -1966,6 +2957,8 @@ let ciResult = null;
1966
2957
  if (prNumber) {
1967
2958
  ciResult = await dispatch(
1968
2959
  `Check CI status for PR #${prNumber} on branch ${branch}.\n` +
2960
+ `This is a PR-scoped dispatch (prNumber supplied -- see agents/ci-watcher.md Inputs);\n` +
2961
+ `the branch+expectedHeadSha form does not apply here.\n` +
1969
2962
  `Run: gh run list --pr ${prNumber} --limit 3 --json status,conclusion,databaseId\n` +
1970
2963
  `If runs exist and are in_progress: poll with gh run watch <id> (timeout 10 min).\n` +
1971
2964
  `If runs exist and conclusion is "success": return status "green".\n` +
@@ -2043,4 +3036,16 @@ log(` ${'TOTAL'.padEnd(20)} $${sprintTotal.toFixed(4).padStart(8)}`);
2043
3036
  log(` (input token cost not included -- see ${sprintLogFile} for per-dispatch detail)`);
2044
3037
  log('================================================\n');
2045
3038
 
2046
- return { cycles: cycleCount, goalMet, goal, harvest: 'ok', sprintCostUsd: parseFloat(sprintTotal.toFixed(4)) };
3039
+ // Final per-phase wall-clock stamp + report. Shows where the sprint's time actually went
3040
+ // (e.g. "develop was 70% of total") and is the evidence for the parallel-doer speedup.
3041
+ await stamp('end');
3042
+ const phaseTiming = buildPhaseTiming(phaseTimeline);
3043
+ log('=== Sprint wall-clock by phase ===');
3044
+ log(phaseTiming.text);
3045
+ log('==================================\n');
3046
+
3047
+ // Sprint completed cleanly -- release the concurrency lock so the next run starts fresh.
3048
+ // (An unclean crash skips this, leaving the state file for a resume.)
3049
+ await clearSprintState(stateFileRel, 'state-clear-done');
3050
+ return { cycles: cycleCount, goalMet, goal, harvest: 'ok', sprintCostUsd: parseFloat(sprintTotal.toFixed(4)),
3051
+ phaseTimingSeconds: phaseTiming.totalSeconds, phaseTiming: phaseTiming.rows };