@apralabs/apra-fleet 0.3.4 → 0.3.6

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 (149) 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 +6 -0
  26. package/dist/cli/config.d.ts.map +1 -1
  27. package/dist/cli/config.js +11 -0
  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/secret.js +8 -2
  34. package/dist/cli/secret.js.map +1 -1
  35. package/dist/cli/uninstall.d.ts.map +1 -1
  36. package/dist/cli/uninstall.js +19 -0
  37. package/dist/cli/uninstall.js.map +1 -1
  38. package/dist/cli/watch.d.ts +8 -0
  39. package/dist/cli/watch.d.ts.map +1 -0
  40. package/dist/cli/watch.js +536 -0
  41. package/dist/cli/watch.js.map +1 -0
  42. package/dist/index.js +10 -4
  43. package/dist/index.js.map +1 -1
  44. package/dist/os/linux.d.ts +1 -0
  45. package/dist/os/linux.d.ts.map +1 -1
  46. package/dist/os/linux.js +4 -0
  47. package/dist/os/linux.js.map +1 -1
  48. package/dist/os/macos.d.ts +1 -0
  49. package/dist/os/macos.d.ts.map +1 -1
  50. package/dist/os/macos.js +5 -0
  51. package/dist/os/macos.js.map +1 -1
  52. package/dist/os/os-commands.d.ts +2 -0
  53. package/dist/os/os-commands.d.ts.map +1 -1
  54. package/dist/os/windows.d.ts +1 -0
  55. package/dist/os/windows.d.ts.map +1 -1
  56. package/dist/os/windows.js +7 -0
  57. package/dist/os/windows.js.map +1 -1
  58. package/dist/services/agent-provisioner.d.ts +39 -0
  59. package/dist/services/agent-provisioner.d.ts.map +1 -0
  60. package/dist/services/agent-provisioner.js +130 -0
  61. package/dist/services/agent-provisioner.js.map +1 -0
  62. package/dist/services/sftp.d.ts +15 -0
  63. package/dist/services/sftp.d.ts.map +1 -1
  64. package/dist/services/sftp.js +34 -0
  65. package/dist/services/sftp.js.map +1 -1
  66. package/dist/services/ssh.d.ts +13 -0
  67. package/dist/services/ssh.d.ts.map +1 -1
  68. package/dist/services/ssh.js +46 -0
  69. package/dist/services/ssh.js.map +1 -1
  70. package/dist/services/stall/log-path-resolver.d.ts +8 -0
  71. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  72. package/dist/services/stall/log-path-resolver.js +12 -4
  73. package/dist/services/stall/log-path-resolver.js.map +1 -1
  74. package/dist/services/statusline.d.ts.map +1 -1
  75. package/dist/services/statusline.js +16 -4
  76. package/dist/services/statusline.js.map +1 -1
  77. package/dist/services/user-config.d.ts +14 -0
  78. package/dist/services/user-config.d.ts.map +1 -1
  79. package/dist/services/user-config.js +22 -0
  80. package/dist/services/user-config.js.map +1 -1
  81. package/dist/services/watch/fleet-log.d.ts +34 -0
  82. package/dist/services/watch/fleet-log.d.ts.map +1 -0
  83. package/dist/services/watch/fleet-log.js +168 -0
  84. package/dist/services/watch/fleet-log.js.map +1 -0
  85. package/dist/services/watch/project-resolver.d.ts +51 -0
  86. package/dist/services/watch/project-resolver.d.ts.map +1 -0
  87. package/dist/services/watch/project-resolver.js +104 -0
  88. package/dist/services/watch/project-resolver.js.map +1 -0
  89. package/dist/services/watch/transcript-formatter.d.ts +26 -0
  90. package/dist/services/watch/transcript-formatter.d.ts.map +1 -0
  91. package/dist/services/watch/transcript-formatter.js +210 -0
  92. package/dist/services/watch/transcript-formatter.js.map +1 -0
  93. package/dist/skills/auto-sprint-args/SKILL.md +88 -0
  94. package/dist/skills/pm/SKILL.md +101 -42
  95. package/dist/skills/pm/beads.md +27 -22
  96. package/dist/skills/pm/cost.md +6 -4
  97. package/dist/skills/pm/doer-reviewer-loop.md +62 -62
  98. package/dist/skills/pm/fleet-addendum.md +11 -5
  99. package/dist/skills/pm/simple-sprint.md +6 -5
  100. package/dist/skills/pm/sprint.md +53 -37
  101. package/dist/tools/check-status.d.ts.map +1 -1
  102. package/dist/tools/check-status.js +47 -29
  103. package/dist/tools/check-status.js.map +1 -1
  104. package/dist/tools/cloud-control.d.ts +2 -2
  105. package/dist/tools/compose-permissions.d.ts +6 -3
  106. package/dist/tools/compose-permissions.d.ts.map +1 -1
  107. package/dist/tools/compose-permissions.js +63 -5
  108. package/dist/tools/compose-permissions.js.map +1 -1
  109. package/dist/tools/execute-command.d.ts.map +1 -1
  110. package/dist/tools/execute-command.js +18 -2
  111. package/dist/tools/execute-command.js.map +1 -1
  112. package/dist/tools/execute-prompt.d.ts +1 -0
  113. package/dist/tools/execute-prompt.d.ts.map +1 -1
  114. package/dist/tools/execute-prompt.js +38 -1
  115. package/dist/tools/execute-prompt.js.map +1 -1
  116. package/dist/tools/list-members.d.ts +3 -0
  117. package/dist/tools/list-members.d.ts.map +1 -1
  118. package/dist/tools/list-members.js +30 -15
  119. package/dist/tools/list-members.js.map +1 -1
  120. package/dist/tools/register-member.d.ts +6 -0
  121. package/dist/tools/register-member.d.ts.map +1 -1
  122. package/dist/tools/register-member.js +35 -0
  123. package/dist/tools/register-member.js.map +1 -1
  124. package/dist/tools/update-member.d.ts +6 -0
  125. package/dist/tools/update-member.d.ts.map +1 -1
  126. package/dist/tools/update-member.js +40 -0
  127. package/dist/tools/update-member.js.map +1 -1
  128. package/dist/types.d.ts +2 -0
  129. package/dist/types.d.ts.map +1 -1
  130. package/dist/utils/agent-helpers.d.ts +8 -0
  131. package/dist/utils/agent-helpers.d.ts.map +1 -1
  132. package/dist/utils/agent-helpers.js +21 -0
  133. package/dist/utils/agent-helpers.js.map +1 -1
  134. package/dist/utils/skill-matrix.d.ts +19 -0
  135. package/dist/utils/skill-matrix.d.ts.map +1 -0
  136. package/dist/utils/skill-matrix.js +47 -0
  137. package/dist/utils/skill-matrix.js.map +1 -0
  138. package/dist/workflows/auto-sprint.js +1207 -204
  139. package/package.json +3 -2
  140. package/skills/fleet/permissions.md +60 -5
  141. package/skills/fleet/profiles/tag-devops.json +4 -0
  142. package/skills/fleet/profiles/tag-gpu.json +4 -0
  143. package/skills/fleet/skill-matrix.md +15 -8
  144. package/version.json +1 -1
  145. package/dist/services/stall/log-path-resolver.test.d.ts +0 -2
  146. package/dist/services/stall/log-path-resolver.test.d.ts.map +0 -1
  147. package/dist/services/stall/log-path-resolver.test.js +0 -76
  148. package/dist/services/stall/log-path-resolver.test.js.map +0 -1
  149. 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];
@@ -112,33 +114,23 @@ const MODEL_SONNET = TIER_STANDARD;
112
114
  const MODEL_HAIKU = TIER_CHEAP;
113
115
 
114
116
  // ------------------------------------------------------------------ schemas
115
-
116
- const REVIEW_SCHEMA = {
117
- type: 'object', required: ['verdict', 'notes'],
118
- properties: {
119
- verdict: { type: 'string', enum: ['APPROVED', 'CHANGES NEEDED'] },
120
- notes: { type: 'string' },
121
- },
122
- };
123
-
124
- const PLAN_REVIEW_SCHEMA = {
125
- type: 'object', required: ['verdict', 'notes', 'taskAssignments'],
126
- properties: {
127
- verdict: { type: 'string', enum: ['APPROVED', 'CHANGES NEEDED'] },
128
- notes: { type: 'string' },
129
- taskAssignments: {
130
- type: 'array',
131
- items: {
132
- type: 'object', required: ['id', 'bucket', 'model'],
133
- properties: {
134
- id: { type: 'string' },
135
- bucket: { type: 'string', enum: ['S', 'M', 'L'] },
136
- model: { type: 'string' },
137
- },
138
- },
139
- },
140
- },
141
- };
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.
142
134
 
143
135
  const SHELL_OUTPUTS_SCHEMA = {
144
136
  type: 'object', required: ['outputs'],
@@ -147,22 +139,6 @@ const SHELL_OUTPUTS_SCHEMA = {
147
139
  },
148
140
  };
149
141
 
150
- const DOER_STATUS_SCHEMA = {
151
- type: 'object', required: ['status'],
152
- properties: {
153
- status: { type: 'string', enum: ['VERIFY'] },
154
- notes: { type: 'string' },
155
- },
156
- };
157
-
158
- const HARVEST_SCHEMA = {
159
- type: 'object', required: ['status'],
160
- properties: {
161
- status: { type: 'string', enum: ['OK', 'FAILED'] },
162
- notes: { type: 'string' },
163
- },
164
- };
165
-
166
142
  const SETUP_SCHEMA = {
167
143
  type: 'object', required: ['repo', 'branch', 'deployMdExists', 'playbookExists', 'startedAt'],
168
144
  properties: {
@@ -203,22 +179,8 @@ const READY_STREAKS_SCHEMA = {
203
179
  },
204
180
  };
205
181
 
206
- const CI_SCHEMA = {
207
- type: 'object', required: ['status'],
208
- properties: {
209
- status: { type: 'string', enum: ['green', 'red', 'not_configured', 'pending'] },
210
- notes: { type: 'string' },
211
- },
212
- };
213
-
214
- const INTEG_RUN_SCHEMA = {
215
- type: 'object', required: ['featuresClosed', 'issuesCreated', 'summary'],
216
- properties: {
217
- featuresClosed: { type: 'number' },
218
- issuesCreated: { type: 'number' },
219
- summary: { type: 'string' },
220
- },
221
- };
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.
222
184
 
223
185
  // Returned by the resume-check agent at the top of every cycle.
224
186
  // planDone -- true if the sprint goal already has children AND every feature has at
@@ -316,6 +278,19 @@ const DEFAULT_CALIBRATION = {
316
278
  standard: 80000,
317
279
  premium: 150000,
318
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
+ },
319
294
  historical: {
320
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.',
321
296
  max_sprints_in_sample: 5,
@@ -603,17 +578,45 @@ function parseBlockers(outputs, rootCount, openListIdx, threshold, rootIds) {
603
578
  return { count: ids.length, ids };
604
579
  }
605
580
 
606
- // parseReadyStreaks: contract {totalCount, streaks[]} grouping ready tasks in the
607
- // 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.
608
583
  // readyListIdx is the explicit index of the ready-tasks JSON command in outputs[].
609
- function parseReadyStreaks(outputs, rootCount, readyListIdx, defaultModel) {
610
- 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 };
611
597
  const subtree = collectSubtreeIds(outputs, rootCount);
612
598
  let readyTasks = [];
599
+ let extractFailed = false;
613
600
  try {
614
601
  const all = JSON.parse(outputs[readyListIdx]);
615
- readyTasks = Array.isArray(all) ? all.filter(t => subtree.has(t.id)) : [];
616
- } 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));
617
620
 
618
621
  // Hoist the known-tiers set and reverse map outside the loop (constant across tasks).
619
622
  const KNOWN_TIERS = new Set([TIER_CHEAP, TIER_STANDARD, TIER_PREMIUM]);
@@ -646,7 +649,7 @@ function parseReadyStreaks(outputs, rootCount, readyListIdx, defaultModel) {
646
649
  _min: Math.min(...tasks.map(x => x.priority)),
647
650
  })).sort((a, b) => a._min - b._min).map(({ model, ids }) => ({ model, ids }));
648
651
 
649
- return { totalCount: readyTasks.length, streaks };
652
+ return { totalCount: readyTasks.length, streaks, extractFailed };
650
653
  }
651
654
 
652
655
  // parseCycleState: contract {planDone, inProgressIds}. planDone is true for a
@@ -952,8 +955,459 @@ function truncateStreakToCeiling(streakIds, bucketById, calibration, tier) {
952
955
  return kept;
953
956
  }
954
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
+
955
1158
  // PURE_FUNCTIONS_END
956
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
+
957
1411
  function outputCostUsd(tier, tokens) {
958
1412
  const rate = OUTPUT_PRICE_PER_M[tier] || OUTPUT_PRICE_PER_M[TIER_STANDARD];
959
1413
  return (tokens / 1_000_000) * rate;
@@ -1047,10 +1501,52 @@ async function parallel(tasks) {
1047
1501
  return Promise.all(tasks);
1048
1502
  }
1049
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
+
1050
1546
  async function countBeadsBlockers(thr, roots) {
1051
1547
  // Extract only IDs from bd graph to keep output small (avoids $(cat ...) file-reference issue).
1052
- const idExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.parse(d).issues.map(i=>i.id).join(' '))}catch{}"`;
1053
- 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('[]')}"`;
1054
1550
  const cmds = [
1055
1551
  ...roots.map(id => `bd graph --json ${id} | ${idExtract}`),
1056
1552
  `bd list --status=open --json | ${openExtract}`,
@@ -1061,14 +1557,18 @@ async function countBeadsBlockers(thr, roots) {
1061
1557
 
1062
1558
  async function getReadyStreaks(rootIds) {
1063
1559
  // Extract only IDs from bd graph to keep output small (avoids $(cat ...) file-reference issue).
1064
- const idExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.parse(d).issues.map(i=>i.id).join(' '))}catch{}"`;
1065
- 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')}"`;
1066
1566
  const cmds = [
1067
1567
  ...rootIds.map(id => `bd graph --json ${id} | ${idExtract}`),
1068
1568
  `bd list --ready --type=task --json | ${taskExtract}`,
1069
1569
  ];
1070
1570
  const r = await dispatchShell(cmds, { model: MODEL_HAIKU, label: 'ready-streaks', phase: 'Develop' });
1071
- return parseReadyStreaks(r?.outputs, rootIds.length, rootIds.length, TIER_STANDARD);
1571
+ return parseReadyStreaks(r?.outputs, rootIds.length, rootIds.length, TIER_STANDARD, rootIds);
1072
1572
  }
1073
1573
 
1074
1574
  async function commitFeedback(repo, branch, notes, role, label, phase) {
@@ -1086,8 +1586,8 @@ async function commitFeedback(repo, branch, notes, role, label, phase) {
1086
1586
 
1087
1587
  async function checkCycleState(rootIds) {
1088
1588
  // Extract only the fields needed for planDone check to keep output small.
1089
- 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('[]')}"`;
1090
- 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{}"`;
1091
1591
  const cmds = [
1092
1592
  ...rootIds.map(id => `bd graph --json ${id} | ${graphExtract}`),
1093
1593
  `bd list --status=in_progress --type=task --json | ${ipExtract}`,
@@ -1096,6 +1596,70 @@ async function checkCycleState(rootIds) {
1096
1596
  return parseCycleState(r?.outputs, rootIds.length);
1097
1597
  }
1098
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
+
1099
1663
  // ------------------------------------------------------------------ STATE
1100
1664
 
1101
1665
  let cycleCount = 0;
@@ -1111,22 +1675,67 @@ phase('Plan');
1111
1675
  // Phase 1: deterministic setup steps -- run via dispatchShell so each command
1112
1676
  // executes exactly once with a bounded turn cap (no LLM looping on simple checks).
1113
1677
  //
1114
- // Fixed output indices (always 6 elements regardless of branch/no-branch):
1678
+ // Fixed output indices (always 8 elements regardless of branch/no-branch):
1115
1679
  // 0: repo root (git rev-parse --show-toplevel)
1116
- // 1: branch checkout result (or "no-op" when branch was not specified)
1117
- // 2: confirmed branch name (git rev-parse --abbrev-ref HEAD)
1118
- // 3: startedAt timestamp (date +%Y%m%d_%H%M%S)
1119
- // 4: deploy.md exists (YES/NO)
1120
- // 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).
1121
1696
  const setupShellCmds = [
1122
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`,
1123
1708
  branch
1124
- ? `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}"`
1125
1713
  : `echo "no-op"`,
1126
1714
  `git rev-parse --abbrev-ref HEAD`,
1127
1715
  `date +%Y%m%d_%H%M%S`,
1128
1716
  `test -f deploy.md && echo YES || echo NO`,
1129
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
+ `"`,
1130
1739
  ];
1131
1740
  const setupShell = await dispatchShell(setupShellCmds, {
1132
1741
  model: MODEL_HAIKU, label: 'setup-shell', phase: 'Plan',
@@ -1134,18 +1743,36 @@ const setupShell = await dispatchShell(setupShellCmds, {
1134
1743
 
1135
1744
  const _outs = setupShell && Array.isArray(setupShell.outputs) ? setupShell.outputs : [];
1136
1745
  const _detectedRepo = (_outs[0] || '').trim();
1137
- const _detectedBranch = (_outs[2] || '').trim();
1138
- const _detectedTs = (_outs[3] || '').trim();
1139
- const _deployExists = (_outs[4] || '').trim() === 'YES';
1140
- 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);
1141
1752
 
1142
1753
  if (!_detectedRepo || !_detectedBranch) {
1143
1754
  log('ERROR: setup-shell failed -- could not detect repo root or branch');
1144
1755
  return { error: 'setup failed' };
1145
1756
  }
1146
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
+
1147
1765
  // Phase 2: free-form setup steps (permissions merge, calibration, transcript dir).
1148
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`;
1149
1776
  const setup = await dispatch(
1150
1777
  `Sprint workspace setup (Phase 2 -- deterministic steps already done).\n\n` +
1151
1778
  `Pre-known values (do NOT re-run these commands):\n` +
@@ -1156,15 +1783,7 @@ const setup = await dispatch(
1156
1783
  ` playbookExists: ${_playbookExists}\n\n` +
1157
1784
  `Your job is only Steps 5-7 below. Return ALL fields in your schema response,\n` +
1158
1785
  `including the pre-known values above.\n\n` +
1159
- `Step 5: Merge deploy permissions into .claude/settings.json.\n` +
1160
- ` For each of deploy.md and integ-test-playbook.md that exists:\n` +
1161
- ` a. Read the file and extract lines under the "## Permissions" section\n` +
1162
- ` (stop at the next ## heading). Each non-empty line is a permission entry\n` +
1163
- ` such as "Bash(docker *)" or "Bash(npm run *)".\n` +
1164
- ` b. Read .claude/settings.json (create it as {} if absent).\n` +
1165
- ` c. For each extracted permission not already in permissions.allow, add it.\n` +
1166
- ` d. Write the updated .claude/settings.json back.\n` +
1167
- ` If neither file has a ## Permissions section, skip this step.\n\n` +
1786
+ step5Block +
1168
1787
  `Step 6: Load or bootstrap calibration data.\n` +
1169
1788
  ` If sprint-logs/calibration.json exists in the repo root:\n` +
1170
1789
  ` Run: cat sprint-logs/calibration.json\n` +
@@ -1200,12 +1819,55 @@ if (branch === 'main' || branch === 'master') {
1200
1819
  return { error: 'protected branch' };
1201
1820
  }
1202
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
+
1203
1865
  // Parse calibration from the raw string the setup agent returned verbatim.
1204
1866
  // Deep-merge with DEFAULT_CALIBRATION so any missing/new field always has a valid value.
1205
1867
  // historical gets its own merge because it accumulates real sprint history on top of the zeros.
1206
1868
  let _parsedCalib = {};
1207
1869
  try { _parsedCalib = JSON.parse(setup.calibrationRaw || '{}'); } catch {}
1208
- const calibration = Object.assign({}, DEFAULT_CALIBRATION, _parsedCalib, {
1870
+ const _mergedCalibration = Object.assign({}, DEFAULT_CALIBRATION, _parsedCalib, {
1209
1871
  historical: Object.assign({}, DEFAULT_CALIBRATION.historical, _parsedCalib.historical || {}),
1210
1872
  complexity_buckets: _parsedCalib.complexity_buckets || DEFAULT_CALIBRATION.complexity_buckets,
1211
1873
  model_prices_per_1m_output_tokens: _parsedCalib.model_prices_per_1m_output_tokens || DEFAULT_CALIBRATION.model_prices_per_1m_output_tokens,
@@ -1216,7 +1878,17 @@ const calibration = Object.assign({}, DEFAULT_CALIBRATION, _parsedCalib, {
1216
1878
  input_cost_multiplier: _parsedCalib.input_cost_multiplier || DEFAULT_CALIBRATION.input_cost_multiplier,
1217
1879
  outlier_thresholds: _parsedCalib.outlier_thresholds || DEFAULT_CALIBRATION.outlier_thresholds,
1218
1880
  doer_token_ceiling: _parsedCalib.doer_token_ceiling || DEFAULT_CALIBRATION.doer_token_ceiling,
1881
+ context_limits: _parsedCalib.context_limits || DEFAULT_CALIBRATION.context_limits,
1219
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(', ')}`);
1220
1892
  // Sync output prices from loaded calibration so dispatchLedger uses correct rates.
1221
1893
  Object.assign(OUTPUT_PRICE_PER_M, calibration.model_prices_per_1m_output_tokens || {});
1222
1894
 
@@ -1233,12 +1905,26 @@ let taskAssignments = [];
1233
1905
  // Timestamp (yyyymmdd_hhmmss) is captured by the setup agent so it stays
1234
1906
  // stable across workflow resumes (Date.now() is banned in workflow scripts).
1235
1907
  const sprintLogBranch = branch.replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-{2,}/g, '-').replace(/^-|-$/g, '') || 'default';
1236
- const sprintLogFile = `sprint-logs/${sprintLogBranch}-${setup.startedAt}.jsonl`;
1908
+ const sprintLogFile = `sprint-logs/${sprintLogBranch}-${effectiveStartedAt}.jsonl`;
1237
1909
  const integTestEnabled = setup.deployMdExists && setup.playbookExists;
1238
1910
  // startedAt "20260622_020952" -> ISO "2026-06-22T02:09:52Z" (pure string, no Date.now())
1239
- 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');
1240
1912
  let flushedCount = 0; // how many dispatchLedger entries have been appended to sprintLogFile
1241
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
+
1242
1928
  // Appends only the NEW (not yet flushed) ledger entries to the sprint log file.
1243
1929
  // Fire-and-forget: does NOT await, and does NOT commit or push.
1244
1930
  // The next natural committer (doer/sprint-meta/beads-export-cleanup) picks the file
@@ -1280,7 +1966,7 @@ log(`Sprint goals: ${rootSummary} | Goal: ${goal} (P<=${threshold}) | Max cycles
1280
1966
  {
1281
1967
  const metaLine = JSON.stringify({
1282
1968
  ts: sprintTs, type: 'meta',
1283
- branch, startedAt: setup.startedAt,
1969
+ branch, startedAt: effectiveStartedAt,
1284
1970
  roots: rootIds, goal,
1285
1971
  transcriptDir: setup.transcriptDir || '',
1286
1972
  });
@@ -1293,7 +1979,7 @@ log(`Sprint goals: ${rootSummary} | Goal: ${goal} (P<=${threshold}) | Max cycles
1293
1979
  `Line:\n${metaLine}\n\n` +
1294
1980
  `Step 3: Commit and push:\n` +
1295
1981
  ` git -C "${repo}" add sprint-logs/\n` +
1296
- ` 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` +
1297
1983
  ` git -C "${repo}" push origin ${branch}\n` +
1298
1984
  `Do not modify any other file. Return "OK" when done.`,
1299
1985
  { model: MODEL_HAIKU, label: 'sprint-meta', phase: 'Plan' }
@@ -1302,6 +1988,27 @@ log(`Sprint goals: ${rootSummary} | Goal: ${goal} (P<=${threshold}) | Max cycles
1302
1988
 
1303
1989
  // ------------------------------------------------------------------ SPRINT LOOP
1304
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
+
1305
2012
  while (cycleCount < maxCycles) {
1306
2013
  cycleCount++;
1307
2014
  cycleCostUsd = 0;
@@ -1310,6 +2017,7 @@ while (cycleCount < maxCycles) {
1310
2017
  // ---------------------------------------------------------------- RESUME CHECK + CYCLE CHECKPOINT
1311
2018
 
1312
2019
  phase('Plan');
2020
+ await stamp(`plan-c${cycleCount}`);
1313
2021
 
1314
2022
  // Write per-cycle checkpoint entry and check cycle state in parallel -- no data dependency.
1315
2023
  // The cycle-checkpoint uses type='cycle-start' (distinct from the one-time type='meta' above).
@@ -1329,6 +2037,10 @@ while (cycleCount < maxCycles) {
1329
2037
  ]);
1330
2038
  log(`Cycle state: planDone=${cycleState.planDone} inProgress=[${cycleState.inProgressIds.join(', ')}]`);
1331
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
+
1332
2044
  // Reset any tasks orphaned in_progress from a previous crashed run.
1333
2045
  if (cycleState.inProgressIds.length > 0) {
1334
2046
  log(`Resetting ${cycleState.inProgressIds.length} orphaned in_progress task(s) to open`);
@@ -1368,28 +2080,30 @@ while (cycleCount < maxCycles) {
1368
2080
  ` - BEFORE creating any feature or task, run: bd search "<title>" --status all\n` +
1369
2081
  ` If a matching issue already exists, update it instead of creating a duplicate.\n` +
1370
2082
  `\n` +
1371
- `DEPENDENCY WIRING -- read this carefully. "bd dep add A B" means A CANNOT CLOSE until B is done.\n` +
1372
- `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` +
1373
2089
  `\n` +
1374
- ` Step 1 -- wire sprint goal -> child (goal waits for children):\n` +
1375
- ` bd dep add <goal-id> <child-id>\n` +
1376
- ` 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` +
1377
2095
  `\n` +
1378
- ` Step 2 -- wire feature -> tasks (feature waits for tasks):\n` +
1379
- ` bd dep add <feature-id> <impl-task-id>\n` +
1380
- ` bd dep add <feature-id> <test-task-id>\n` +
1381
- ` 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` +
1382
2099
  `\n` +
1383
- ` Step 3 -- wire test after impl:\n` +
1384
- ` bd dep add <test-task-id> <impl-task-id>\n` +
1385
- ` After this: "bd ready" shows only impl-task. test-task unblocks once impl-task closes.\n` +
1386
- `\n` +
1387
- ` VERIFY after wiring: run "bd ready" -- it must return impl tasks, NOT sprint goals or blocked parents.\n` +
1388
- ` 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` +
1389
2104
  `\n` +
1390
2105
  ` IMPORTANT: Each task belongs to exactly ONE feature. Never share a task across features.\n` +
1391
2106
  `\n` +
1392
- ` Break each sprint goal into child issues: bd create --parent <goal-id> (use type=feature for sub-goals, type=task for leaf work).\n` +
1393
2107
  ` Create type=task issues for each feature: implementation tasks AND integration\n` +
1394
2108
  ` test development tasks (prefix test tasks with "[test]" in the title)\n` +
1395
2109
  ` Features P1/P2; tasks one level below their parent feature (P1 feature -> P2 tasks, P2 feature -> P3 tasks)\n` +
@@ -1430,11 +2144,12 @@ while (cycleCount < maxCycles) {
1430
2144
  `Run: bd show <id> to inspect individual issues in depth.\n` +
1431
2145
  `Run: bd ready -- this is your FIRST correctness check.\n` +
1432
2146
  `Do NOT review or comment on issues outside these sprint goals.\n\n` +
1433
- `Follow your runbook (plan-reviewer.md) step by step:\n` +
2147
+ `Follow your runbook (agents/plan-reviewer.md) step by step:\n` +
1434
2148
  ` Steps 1-2: inspect the DAG and check all quality criteria.\n` +
1435
2149
  ` Step 3: classify each task -- assign complexity bucket (S/M/L) and read its model\n` +
1436
- ` from beads metadata. If a task has no model metadata, note it in your verdict\n` +
1437
- ` 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` +
1438
2153
  ` Step 4: return verdict, notes, and taskAssignments (id + bucket + model per task).\n\n` +
1439
2154
  `Notes must be specific: include issue IDs and exact "bd dep add" commands to fix\n` +
1440
2155
  `any dependency direction problems.`,
@@ -1492,20 +2207,86 @@ while (cycleCount < maxCycles) {
1492
2207
  // ---------------------------------------------------------------- DEVELOP
1493
2208
 
1494
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`);
1495
2214
 
1496
2215
  const MAX_DEV_ITER = 20;
1497
2216
  let devIter = 0;
1498
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;
1499
2227
 
1500
2228
  while (devIter < MAX_DEV_ITER) {
1501
- 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
+ }
1502
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
+ }
1503
2284
  log(`No ready tasks -- develop phase complete (${devIter} iterations)`);
1504
2285
  break;
1505
2286
  }
1506
2287
  log(`Dev iter ${devIter} c${cycleCount}: ${streakResult.totalCount} ready task(s) across ${streakResult.streaks.length} model streak(s)`);
1507
2288
 
1508
- // 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.
1509
2290
  const workedIds = [];
1510
2291
  let streakAbort = false;
1511
2292
  let doerNullReset = false;
@@ -1514,13 +2295,142 @@ while (cycleCount < maxCycles) {
1514
2295
  // last approved plan-review's taskAssignments held at workflow scope.
1515
2296
  const bucketById = Object.fromEntries((taskAssignments || []).map(t => [t.id, t.bucket]));
1516
2297
 
1517
- 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)) {
1518
2418
  // Truncate the streak to the longest prefix that fits the doer token ceiling for
1519
2419
  // this tier. Remaining IDs are left unworked and resurface on the next
1520
2420
  // getReadyStreaks iteration.
1521
- 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;
1522
2429
  if (fittedIds.length < streak.ids.length) {
1523
- 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`);
1524
2434
  }
1525
2435
  const doerLabel = `doer-c${cycleCount}-i${devIter}: ${labelTaskIds(fittedIds)}`;
1526
2436
  const streakEstUsd = sprintQuote
@@ -1545,14 +2455,15 @@ while (cycleCount < maxCycles) {
1545
2455
  ` - Closed tasks are durable even if the doer crashes mid-streak\n` +
1546
2456
  ` - NEVER close a type=feature or type=bug issue -- only close type=task\n` +
1547
2457
  `Work all listed tasks then stop and return status "VERIFY".\n` +
1548
- `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.`,
1549
2460
  { model: streak.model, label: doerLabel, phase: 'Develop', schema: DOER_STATUS_SCHEMA, agentType: 'doer',
1550
2461
  context: `tasks ${fittedIds.join(', ')}` }
1551
2462
  );
1552
2463
 
1553
2464
  if (!doerResult) {
1554
2465
  log(`Doer returned null (streak ${streak.model}) -- resetting orphaned in_progress tasks and retrying`);
1555
- 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{}"`;
1556
2467
  const ipResult = await dispatchShell(
1557
2468
  [`bd list --status=in_progress --type=task --json | ${_ipExtract}`],
1558
2469
  { model: MODEL_HAIKU, label: `reset-orphans-c${cycleCount}-i${devIter}`, phase: 'Develop' }
@@ -1568,8 +2479,17 @@ while (cycleCount < maxCycles) {
1568
2479
  }
1569
2480
 
1570
2481
  if (doerResult.status !== 'VERIFY') {
1571
- log(`Unexpected doer status "${doerResult.status}" -- aborting`);
1572
- 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
+ }
1573
2493
  streakAbort = true;
1574
2494
  break;
1575
2495
  }
@@ -1579,6 +2499,13 @@ while (cycleCount < maxCycles) {
1579
2499
  devIter++;
1580
2500
  if (doerNullReset) continue;
1581
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
+ }
1582
2509
 
1583
2510
  // Reviewer tier matches the highest tier used across all streaks:
1584
2511
  // any premium streak -> premium; otherwise standard (cheap work reviewed at standard minimum).
@@ -1595,8 +2522,10 @@ while (cycleCount < maxCycles) {
1595
2522
  `Run: git -C "${repo}" diff ${base_branch}...${branch} to see the changes.\n` +
1596
2523
  `Do NOT comment on code or issues outside the listed tasks.\n` +
1597
2524
  `Check: code correctness, test coverage, adherence to each task's acceptance criteria.\n` +
1598
- `If a task needs rework, reopen it: bd update <id> --status=open\n` +
1599
- `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` +
1600
2529
  `APPROVED means all committed work meets acceptance criteria.`,
1601
2530
  { model: reviewerModel, label: reviewerLabel, phase: 'Develop', schema: REVIEW_SCHEMA, agentType: 'reviewer',
1602
2531
  context: `reviewing tasks ${workedIds.join(', ')}` }
@@ -1606,6 +2535,34 @@ while (cycleCount < maxCycles) {
1606
2535
  if (!approved(review)) {
1607
2536
  devFeedback = (review && review.notes) || '';
1608
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
+ }
1609
2566
  // Fire-and-forget: write feedback.md to disk only -- next doer's 'git add -A' picks it up.
1610
2567
  // The plan-reviewer commitFeedback (below) MUST remain awaited and commit+push so the
1611
2568
  // planner can read it from remote. Dev-path feedback is local-only.
@@ -1644,69 +2601,74 @@ while (cycleCount < maxCycles) {
1644
2601
 
1645
2602
  if (integTestEnabled) {
1646
2603
  phase('Test');
2604
+ await stamp(`test-c${cycleCount}`);
1647
2605
 
1648
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.
1649
2611
  const deployLabel = `deployer-c${cycleCount}`;
1650
2612
  const deployResult = await dispatch(
1651
- `Repo: ${repo}\nBranch: ${branch}\nCycle: ${cycleCount}\n\n` +
1652
- `Follow the integration test playbook and deploy.md:\n` +
1653
- (cycleCount === 1
1654
- ? `1. Run the Setup section of integ-test-playbook.md to bring up the test environment.\n`
1655
- : `1. Run the Reset section of integ-test-playbook.md to restore pristine state.\n`) +
1656
- `2. Follow all steps in deploy.md to deploy the build.\n` +
1657
- `3. Run the smoke test defined in deploy.md.\n` +
1658
- `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` +
1659
2621
  `5. If deployed is false, include the error output in notes.`,
1660
2622
  { model: MODEL_SONNET, label: deployLabel, phase: 'Test', agentType: 'deployer',
1661
- schema: { type: 'object', required: ['deployed'], properties: {
1662
- deployed: { type: 'boolean' }, notes: { type: 'string' } } } }
2623
+ schema: DEPLOYER_SCHEMA }
1663
2624
  );
1664
2625
 
1665
2626
  if (!deployResult || !deployResult.deployed) {
1666
2627
  const msg = (deployResult && deployResult.notes) || 'no details';
1667
2628
  log(`Deploy failed on cycle ${cycleCount}: ${msg.slice(0, 200)}`);
1668
- log('Skipping integration tests this cycle -- teardown and continue');
1669
- // Teardown before next cycle
1670
- await dispatch(
1671
- `Run the Teardown section of integ-test-playbook.md to clean up the test environment.`,
1672
- { model: MODEL_SONNET, label: `teardown-c${cycleCount}-fail`, phase: 'Test', agentType: 'deployer' }
1673
- );
2629
+ log('Skipping integration tests this cycle -- the test sandbox was never brought up (integ-test-runner owns it), nothing to tear down');
1674
2630
  } else {
1675
- // -- 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);
1676
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))}]` : ''}`);
1677
2643
 
1678
2644
  const integResult = await dispatch(
1679
2645
  `Repo: ${repo}\nBranch: ${branch}\nCycle: ${cycleCount}\n` +
1680
2646
  `Sprint goals: ${rootSummary}\n\n` +
1681
- `Run: bd list --type=feature --status=open\n` +
1682
- `For each open feature, execute its integration tests.\n\n` +
1683
- `For each feature:\n` +
1684
- ` PASS: all tests pass -> bd close <feature-id>\n` +
1685
- ` FAIL: tests fail -> bd create --title="[integ] <description>" ` +
1686
- `--description="Feature: <id>\\nExpected: <what>\\nActual: <what>\\nTest: <which>" ` +
1687
- `--type=bug --priority=<1=core requirement unmet, 2=partial, 3=quality>\n` +
1688
- ` Keep feature open on failure or if inconclusive.\n\n` +
1689
- `Priority rules:\n` +
1690
- ` P0: system won't start or core path completely broken\n` +
1691
- ` P1: requirement from sprint goal explicitly not met\n` +
1692
- ` P2: requirement partially met, degraded behaviour\n` +
1693
- ` P3: quality, performance, or UX issue not blocking core function\n\n` +
1694
- `Before creating a new bug, check bd search "[integ]" -- update existing if duplicate.\n\n` +
1695
- `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).`,
1696
2662
  { model: MODEL_SONNET, label: integLabel, phase: 'Test', schema: INTEG_RUN_SCHEMA, agentType: 'integ-test-runner' }
1697
2663
  );
1698
2664
  if (integResult) {
1699
- log(`Integration: ${integResult.featuresClosed} features closed, ${integResult.issuesCreated} issues created`);
2665
+ log(`Integration: ${integResult.featuresClosed} features closed, ${integResult.issuesCreated} issues created, passed=${integResult.passed}`);
1700
2666
  log(`Summary: ${integResult.summary}`);
1701
2667
  }
1702
2668
 
1703
- // -- Teardown --
1704
- await dispatch(
1705
- `Run the Teardown section of integ-test-playbook.md to fully clean up the test environment.`,
1706
- { model: MODEL_SONNET, label: `teardown-c${cycleCount}`, phase: 'Test', agentType: 'deployer' }
1707
- );
1708
-
1709
- // 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).
1710
2672
  await appendNewEntries(`test-c${cycleCount}`, 'Test');
1711
2673
  }
1712
2674
  }
@@ -1721,9 +2683,9 @@ while (cycleCount < maxCycles) {
1721
2683
 
1722
2684
  let blockers;
1723
2685
  {
1724
- const _idExtract = `node -e "const d=require('fs').readFileSync(0,'utf8');try{console.log(JSON.parse(d).issues.map(i=>i.id).join(' '))}catch{}"`;
1725
- 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('[]')}"`;
1726
- 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('[]')}"`;
1727
2689
  const exitCmds = [
1728
2690
  ...rootIds.map(id => `bd graph --json ${id} | ${_idExtract}`),
1729
2691
  `bd list --status=open --json | ${_openExtract}`,
@@ -1734,7 +2696,7 @@ while (cycleCount < maxCycles) {
1734
2696
  blockers = parseBlockers(exitResult.outputs, rootIds.length, rootIds.length, threshold, rootIds);
1735
2697
  // Ready streaks prefetched but not used: develop loop already determined no ready tasks.
1736
2698
  // Parsed here to validate the merged output; result discarded at cycle end.
1737
- parseReadyStreaks(exitResult.outputs, rootIds.length, rootIds.length + 1, TIER_STANDARD);
2699
+ parseReadyStreaks(exitResult.outputs, rootIds.length, rootIds.length + 1, TIER_STANDARD, rootIds);
1738
2700
  } else {
1739
2701
  // Fallback: outputs too short (agent returned partial results) -- use separate dispatches.
1740
2702
  log('exit-check: outputs.length < rootCount+2 -- falling back to separate dispatches');
@@ -1774,6 +2736,25 @@ while (cycleCount < maxCycles) {
1774
2736
  // ------------------------------------------------------------------ FINAL REVIEW
1775
2737
 
1776
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
+ );
1777
2758
 
1778
2759
  const finalReviewLabel = 'final-reviewer';
1779
2760
  const finalReview = await dispatch(
@@ -1786,7 +2767,7 @@ const finalReview = await dispatch(
1786
2767
  ` - Are there obvious gaps or regressions?\n` +
1787
2768
  ` - Is the codebase in a releasable state for what was completed?\n` +
1788
2769
  `APPROVED means the work is ready to harvest and raise as a PR.\n` +
1789
- `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.`,
1790
2771
  { model: MODEL_OPUS, label: finalReviewLabel, phase: 'Harvest', schema: REVIEW_SCHEMA, agentType: 'reviewer' }
1791
2772
  );
1792
2773
  log(`Final review: ${finalReview && finalReview.verdict || 'null'}`);
@@ -1794,6 +2775,7 @@ log(`Final review: ${finalReview && finalReview.verdict || 'null'}`);
1794
2775
  if (!approved(finalReview)) {
1795
2776
  const notes = (finalReview && finalReview.notes) || '';
1796
2777
  log(`Final review not approved -- aborting before harvest. Notes: ${notes.slice(0, 300)}`);
2778
+ await clearSprintState(stateFileRel, 'state-clear-finalrejected');
1797
2779
  return { cycles: cycleCount, goalMet, goal, abortReason: abortReason || 'final review rejected', finalReviewNotes: notes };
1798
2780
  }
1799
2781
 
@@ -1811,15 +2793,15 @@ const tasksCompleted = goalMet
1811
2793
  : Math.max(0, (sprintQuote ? sprintQuote.tasks.length : 0) - prevOpenIds.length);
1812
2794
  const tasksOpen = goalMet ? 0 : prevOpenIds.length;
1813
2795
  const sprintSummary = buildSprintSummary(sprintAnalysis, sprintQuote, calibration, {
1814
- branch, goal, goalMet, cycleCount, tasksCompleted, tasksOpen, startedAt: setup.startedAt,
2796
+ branch, goal, goalMet, cycleCount, tasksCompleted, tasksOpen, startedAt: effectiveStartedAt,
1815
2797
  });
1816
2798
  // Append Sprint Execution Summary section -- emitted regardless of goalMet.
1817
2799
  const executionSummary = buildExecutionSummary(logEntries, {
1818
- cycleCount, goalMet, goal, tasksOpen, openIssueIds: prevOpenIds, startedAt: setup.startedAt,
2800
+ cycleCount, goalMet, goal, tasksOpen, openIssueIds: prevOpenIds, startedAt: effectiveStartedAt,
1819
2801
  });
1820
2802
  sprintSummary.summaryText += '\n' + executionSummary.summaryText;
1821
2803
  log('Sprint summary:\n' + sprintSummary.summaryText);
1822
- const analysisArtifactFile = `sprint-logs/${sprintLogBranch}-${setup.startedAt}.analysis.md`;
2804
+ const analysisArtifactFile = `sprint-logs/${sprintLogBranch}-${effectiveStartedAt}.analysis.md`;
1823
2805
 
1824
2806
  const harvestLabel = 'harvester';
1825
2807
  const harvestResult = await dispatch(
@@ -1851,11 +2833,12 @@ if (!harvestResult || harvestResult.status !== 'OK') {
1851
2833
  `mkdir -p "${repo}/sprint-logs"`,
1852
2834
  `printf '%s' '${safeContent}' > "${repo}/${analysisArtifactFile}"`,
1853
2835
  `git -C "${repo}" add "${analysisArtifactFile}"`,
1854
- `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}"`,
1855
2837
  ],
1856
2838
  { model: MODEL_HAIKU, label: 'harvest-analysis-fallback', phase: 'Harvest' }
1857
2839
  );
1858
2840
  log(`Analysis artifact written via fallback: ${analysisArtifactFile}`);
2841
+ await clearSprintState(stateFileRel, 'state-clear-harvestfailed');
1859
2842
  return { cycles: cycleCount, goalMet, goal, harvest: 'failed' };
1860
2843
  }
1861
2844
 
@@ -1865,7 +2848,7 @@ if (!harvestResult || harvestResult.status !== 'OK') {
1865
2848
  // The doer closes tasks; the original sprint-goal epics must be closed explicitly.
1866
2849
  // These have no data dependency between them, so run in parallel.
1867
2850
 
1868
- const updatedCalibration = computeUpdatedCalibration(calibration, sprintAnalysis, setup.startedAt, taskAssignments, logEntries);
2851
+ const updatedCalibration = computeUpdatedCalibration(calibration, sprintAnalysis, effectiveStartedAt, taskAssignments, logEntries);
1869
2852
  const calibrationJson = JSON.stringify(updatedCalibration, null, 2);
1870
2853
 
1871
2854
  await parallel([
@@ -1900,7 +2883,7 @@ await dispatch(
1900
2883
  `Persist beads state and clean sprint scaffolding from the PR diff.\n\n` +
1901
2884
  `Step 1 -- Stage sprint-logs and evict scaffold files from the working tree (unconditional):\n` +
1902
2885
  ` git -C "${repo}" add sprint-logs/\n` +
1903
- ` 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` +
1904
2887
  ` rm -f "${repo}/feedback.md" "${repo}/requirements.md" 2>/dev/null || true\n\n` +
1905
2888
  `Step 2 -- Export beads state:\n` +
1906
2889
  ` bd export -o "${repo}/.beads/issues.jsonl"\n` +
@@ -1931,17 +2914,23 @@ await dispatch(
1931
2914
 
1932
2915
  // Sync beads Dolt remote so refs/dolt/data is up to date.
1933
2916
  // Non-fatal: a missing remote or network error must not abort harvest.
1934
- await dispatch(
1935
- `Sync beads state to the Dolt remote.\n\n` +
1936
- `Run:\n` +
1937
- ` bd dolt push\n\n` +
1938
- `Capture stdout and stderr. If the command exits 0, log "bd dolt push: OK".\n` +
1939
- `If the command exits non-zero (e.g. no dolt remote configured, network error), log a warning:\n` +
1940
- ` "bd dolt push failed (non-fatal): <reason>"\n` +
1941
- `and continue -- do NOT throw, return an error, or abort the workflow.\n\n` +
1942
- `Return "OK" when done (regardless of whether the push succeeded or failed).`,
1943
- { model: MODEL_HAIKU, label: 'dolt-push', phase: 'Harvest' }
1944
- );
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
+ }
1945
2934
 
1946
2935
  // ------------------------------------------------------------------ PR
1947
2936
 
@@ -1968,6 +2957,8 @@ let ciResult = null;
1968
2957
  if (prNumber) {
1969
2958
  ciResult = await dispatch(
1970
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` +
1971
2962
  `Run: gh run list --pr ${prNumber} --limit 3 --json status,conclusion,databaseId\n` +
1972
2963
  `If runs exist and are in_progress: poll with gh run watch <id> (timeout 10 min).\n` +
1973
2964
  `If runs exist and conclusion is "success": return status "green".\n` +
@@ -2045,4 +3036,16 @@ log(` ${'TOTAL'.padEnd(20)} $${sprintTotal.toFixed(4).padStart(8)}`);
2045
3036
  log(` (input token cost not included -- see ${sprintLogFile} for per-dispatch detail)`);
2046
3037
  log('================================================\n');
2047
3038
 
2048
- 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 };