@intentius/chant 0.124.88 → 0.124.90

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 (377) hide show
  1. package/dist/actor.d.ts +36 -1
  2. package/dist/actor.d.ts.map +1 -1
  3. package/dist/actor.js +39 -1
  4. package/dist/chant-install.d.ts.map +1 -1
  5. package/dist/chant-install.js +1 -2
  6. package/dist/ci-base.d.ts +30 -0
  7. package/dist/ci-base.d.ts.map +1 -0
  8. package/dist/ci-base.js +33 -0
  9. package/dist/ci-comment-commands.d.ts +193 -0
  10. package/dist/ci-comment-commands.d.ts.map +1 -0
  11. package/dist/ci-comment-commands.js +353 -0
  12. package/dist/ci-comment-replies.d.ts +40 -0
  13. package/dist/ci-comment-replies.d.ts.map +1 -0
  14. package/dist/ci-comment-replies.js +59 -0
  15. package/dist/ci-evidence-from-job.d.ts +25 -0
  16. package/dist/ci-evidence-from-job.d.ts.map +1 -1
  17. package/dist/ci-evidence-from-job.js +43 -2
  18. package/dist/ci-evidence-jobs.d.ts +30 -1
  19. package/dist/ci-evidence-jobs.d.ts.map +1 -1
  20. package/dist/ci-evidence-jobs.js +46 -3
  21. package/dist/ci-image.d.ts +21 -4
  22. package/dist/ci-image.d.ts.map +1 -1
  23. package/dist/ci-image.js +62 -10
  24. package/dist/ci-job-guard.d.ts +42 -45
  25. package/dist/ci-job-guard.d.ts.map +1 -1
  26. package/dist/ci-job-guard.js +206 -3
  27. package/dist/ci-note-commands.d.ts +104 -4
  28. package/dist/ci-note-commands.d.ts.map +1 -1
  29. package/dist/ci-note-commands.js +131 -38
  30. package/dist/ci-product-words.d.ts +42 -0
  31. package/dist/ci-product-words.d.ts.map +1 -1
  32. package/dist/ci-product-words.js +25 -0
  33. package/dist/ci-product.d.ts +72 -1
  34. package/dist/ci-product.d.ts.map +1 -1
  35. package/dist/ci-product.js +73 -6
  36. package/dist/cli/commands/build.d.ts.map +1 -1
  37. package/dist/cli/commands/build.js +29 -2
  38. package/dist/cli/handlers/approve.d.ts.map +1 -1
  39. package/dist/cli/handlers/approve.js +2 -1
  40. package/dist/cli/handlers/ci-check.d.ts +1 -1
  41. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  42. package/dist/cli/handlers/ci-check.js +17 -7
  43. package/dist/cli/handlers/ci-evidence.d.ts.map +1 -1
  44. package/dist/cli/handlers/ci-evidence.js +33 -7
  45. package/dist/cli/handlers/components.d.ts.map +1 -1
  46. package/dist/cli/handlers/components.js +3 -1
  47. package/dist/cli/handlers/generated-check.d.ts +8 -0
  48. package/dist/cli/handlers/generated-check.d.ts.map +1 -1
  49. package/dist/cli/handlers/generated-check.js +31 -1
  50. package/dist/cli/handlers/lock.d.ts.map +1 -1
  51. package/dist/cli/handlers/lock.js +121 -4
  52. package/dist/cli/handlers/pr-comment.d.ts +33 -0
  53. package/dist/cli/handlers/pr-comment.d.ts.map +1 -0
  54. package/dist/cli/handlers/pr-comment.js +201 -0
  55. package/dist/cli/handlers/pr-env.d.ts.map +1 -1
  56. package/dist/cli/handlers/pr-env.js +6 -3
  57. package/dist/cli/handlers/pr-notes.d.ts.map +1 -1
  58. package/dist/cli/handlers/pr-notes.js +23 -1
  59. package/dist/cli/handlers/pr.d.ts +23 -1
  60. package/dist/cli/handlers/pr.d.ts.map +1 -1
  61. package/dist/cli/handlers/pr.js +71 -23
  62. package/dist/cli/handlers/promote.d.ts.map +1 -1
  63. package/dist/cli/handlers/promote.js +2 -1
  64. package/dist/cli/handlers/release.d.ts.map +1 -1
  65. package/dist/cli/handlers/release.js +11 -2
  66. package/dist/cli/handlers/run-wave.d.ts.map +1 -1
  67. package/dist/cli/handlers/run-wave.js +180 -4
  68. package/dist/cli/handlers/run.d.ts.map +1 -1
  69. package/dist/cli/handlers/run.js +2 -1
  70. package/dist/cli/main.d.ts.map +1 -1
  71. package/dist/cli/main.js +41 -2
  72. package/dist/cli/parse-args.d.ts.map +1 -1
  73. package/dist/cli/parse-args.js +31 -0
  74. package/dist/cli/registry.d.ts +19 -1
  75. package/dist/cli/registry.d.ts.map +1 -1
  76. package/dist/components/auto-release.d.ts.map +1 -1
  77. package/dist/components/auto-release.js +2 -1
  78. package/dist/components/pr-checks.d.ts +97 -6
  79. package/dist/components/pr-checks.d.ts.map +1 -1
  80. package/dist/components/pr-checks.js +107 -13
  81. package/dist/components/pr-pipeline.d.ts +19 -14
  82. package/dist/components/pr-pipeline.d.ts.map +1 -1
  83. package/dist/components/pr-pipeline.js +7 -13
  84. package/dist/components/product-pipeline.d.ts +96 -3
  85. package/dist/components/product-pipeline.d.ts.map +1 -1
  86. package/dist/components/product-pipeline.js +120 -14
  87. package/dist/components/product-plan.d.ts +203 -6
  88. package/dist/components/product-plan.d.ts.map +1 -1
  89. package/dist/components/product-plan.js +250 -43
  90. package/dist/drift-record.d.ts +7 -0
  91. package/dist/drift-record.d.ts.map +1 -1
  92. package/dist/drift-record.js +19 -0
  93. package/dist/floor-table.data.d.ts.map +1 -1
  94. package/dist/floor-table.data.js +63 -31
  95. package/dist/forge-check/contract.d.ts +11 -1
  96. package/dist/forge-check/contract.d.ts.map +1 -1
  97. package/dist/forge-check/contract.js +4 -1
  98. package/dist/forge-check/index.d.ts +2 -0
  99. package/dist/forge-check/index.d.ts.map +1 -1
  100. package/dist/forge-check/index.js +2 -0
  101. package/dist/gate-resume-run.d.ts +9 -1
  102. package/dist/gate-resume-run.d.ts.map +1 -1
  103. package/dist/gate-resume-run.js +26 -3
  104. package/dist/generated-check.d.ts +18 -4
  105. package/dist/generated-check.d.ts.map +1 -1
  106. package/dist/generated-check.js +37 -5
  107. package/dist/image-pins.d.ts +26 -0
  108. package/dist/image-pins.d.ts.map +1 -0
  109. package/dist/image-pins.js +19 -0
  110. package/dist/lexicon.d.ts +93 -4
  111. package/dist/lexicon.d.ts.map +1 -1
  112. package/dist/lifecycle/gate-applied.d.ts +9 -0
  113. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  114. package/dist/lifecycle/git.d.ts +11 -0
  115. package/dist/lifecycle/git.d.ts.map +1 -1
  116. package/dist/lifecycle/git.js +30 -3
  117. package/dist/lifecycle/publish-npm.d.ts +11 -0
  118. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  119. package/dist/lifecycle/publish-npm.js +27 -1
  120. package/dist/lifecycle/reach-locks.d.ts +131 -0
  121. package/dist/lifecycle/reach-locks.d.ts.map +1 -0
  122. package/dist/lifecycle/reach-locks.js +118 -0
  123. package/dist/lifecycle/release-cut.d.ts +3 -1
  124. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  125. package/dist/lifecycle/release-cut.js +15 -0
  126. package/dist/lifecycle/release-images.d.ts.map +1 -1
  127. package/dist/lifecycle/release-images.js +1 -2
  128. package/dist/notify-product.d.ts +12 -3
  129. package/dist/notify-product.d.ts.map +1 -1
  130. package/dist/notify-product.js +10 -6
  131. package/dist/op/activities/source-release.d.ts.map +1 -1
  132. package/dist/op/activities/source-release.js +2 -1
  133. package/dist/op/activities/source-rollback.d.ts.map +1 -1
  134. package/dist/op/activities/source-rollback.js +2 -1
  135. package/dist/op/apply-status.d.ts +84 -0
  136. package/dist/op/apply-status.d.ts.map +1 -0
  137. package/dist/op/apply-status.js +106 -0
  138. package/dist/op/before-merge-decide.d.ts +102 -0
  139. package/dist/op/before-merge-decide.d.ts.map +1 -0
  140. package/dist/op/before-merge-decide.js +142 -0
  141. package/dist/op/before-merge-done.d.ts +56 -0
  142. package/dist/op/before-merge-done.d.ts.map +1 -0
  143. package/dist/op/before-merge-done.js +69 -0
  144. package/dist/op/before-merge-store.d.ts +20 -0
  145. package/dist/op/before-merge-store.d.ts.map +1 -0
  146. package/dist/op/before-merge-store.js +48 -0
  147. package/dist/op/before-merge.d.ts +150 -0
  148. package/dist/op/before-merge.d.ts.map +1 -0
  149. package/dist/op/before-merge.js +207 -0
  150. package/dist/op/follow-on-run.d.ts +117 -0
  151. package/dist/op/follow-on-run.d.ts.map +1 -0
  152. package/dist/op/follow-on-run.js +154 -0
  153. package/dist/op/follow-on-store.d.ts +17 -0
  154. package/dist/op/follow-on-store.d.ts.map +1 -0
  155. package/dist/op/follow-on-store.js +54 -0
  156. package/dist/op/gate.d.ts +6 -0
  157. package/dist/op/gate.d.ts.map +1 -1
  158. package/dist/op/gate.js +10 -1
  159. package/dist/op/index.d.ts +5 -1
  160. package/dist/op/index.d.ts.map +1 -1
  161. package/dist/op/index.js +2 -0
  162. package/dist/op/op-waves-after-plan.d.ts +13 -0
  163. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  164. package/dist/op/op-waves-evidence-jobs.d.ts +10 -2
  165. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  166. package/dist/op/op-waves-evidence-jobs.js +19 -5
  167. package/dist/op/op-waves-follow-on.d.ts +162 -0
  168. package/dist/op/op-waves-follow-on.d.ts.map +1 -0
  169. package/dist/op/op-waves-follow-on.js +355 -0
  170. package/dist/op/op-waves-render-spec.d.ts +100 -0
  171. package/dist/op/op-waves-render-spec.d.ts.map +1 -0
  172. package/dist/op/op-waves-render-spec.js +162 -0
  173. package/dist/op/op-waves-run.d.ts +148 -6
  174. package/dist/op/op-waves-run.d.ts.map +1 -1
  175. package/dist/op/op-waves-run.js +873 -100
  176. package/dist/op/op-waves-split.d.ts +122 -0
  177. package/dist/op/op-waves-split.d.ts.map +1 -0
  178. package/dist/op/op-waves-split.js +166 -0
  179. package/dist/op/op-waves.d.ts +24 -0
  180. package/dist/op/op-waves.d.ts.map +1 -1
  181. package/dist/op/op-waves.js +18 -1
  182. package/dist/op/schedule-overdue.d.ts +15 -1
  183. package/dist/op/schedule-overdue.d.ts.map +1 -1
  184. package/dist/op/schedule-overdue.js +77 -5
  185. package/dist/op/stage-hooks.d.ts +36 -1
  186. package/dist/op/stage-hooks.d.ts.map +1 -1
  187. package/dist/op/stage-hooks.js +17 -3
  188. package/dist/op/wave-stop.d.ts +67 -0
  189. package/dist/op/wave-stop.d.ts.map +1 -0
  190. package/dist/op/wave-stop.js +129 -0
  191. package/dist/planned-files.d.ts +76 -0
  192. package/dist/planned-files.d.ts.map +1 -0
  193. package/dist/planned-files.js +108 -0
  194. package/dist/pr-forge-job.d.ts +22 -0
  195. package/dist/pr-forge-job.d.ts.map +1 -0
  196. package/dist/pr-forge-job.js +46 -0
  197. package/dist/pr-loop.d.ts +3 -6
  198. package/dist/pr-loop.d.ts.map +1 -1
  199. package/dist/pr-loop.js +4 -81
  200. package/dist/pr-plan-note.d.ts +97 -0
  201. package/dist/pr-plan-note.d.ts.map +1 -1
  202. package/dist/pr-plan-note.js +94 -1
  203. package/dist/pr-post.d.ts +28 -3
  204. package/dist/pr-post.d.ts.map +1 -1
  205. package/dist/pr-post.js +146 -13
  206. package/dist/pr-status.d.ts +16 -0
  207. package/dist/pr-status.d.ts.map +1 -0
  208. package/dist/pr-status.js +90 -0
  209. package/dist/ref-gate-init.d.ts +16 -2
  210. package/dist/ref-gate-init.d.ts.map +1 -1
  211. package/dist/ref-gate-init.js +24 -13
  212. package/dist/release-floors.d.ts +39 -1
  213. package/dist/release-floors.d.ts.map +1 -1
  214. package/dist/release-floors.js +63 -25
  215. package/dist/render-module.d.ts +15 -0
  216. package/dist/render-module.d.ts.map +1 -0
  217. package/dist/render-module.js +73 -0
  218. package/dist/state-migration.d.ts.map +1 -1
  219. package/dist/state-migration.js +1 -2
  220. package/dist/wave-blocked.d.ts +7 -1
  221. package/dist/wave-blocked.d.ts.map +1 -1
  222. package/dist/wave-blocked.js +7 -2
  223. package/dist/wave-runtime.mjs +366 -350
  224. package/dist/workspace/ci-green-cli.d.ts.map +1 -1
  225. package/dist/workspace/ci-green-cli.js +3 -2
  226. package/dist/workspace/release-train.d.ts.map +1 -1
  227. package/dist/workspace/release-train.js +2 -1
  228. package/dist/workspace/release-workflow.d.ts +4 -3
  229. package/dist/workspace/release-workflow.d.ts.map +1 -1
  230. package/dist/workspace/release-workflow.js +10 -7
  231. package/dist/workspace/trust/check-evidence-report.d.ts +7 -2
  232. package/dist/workspace/trust/check-evidence-report.d.ts.map +1 -1
  233. package/dist/workspace/trust/check-evidence-report.js +15 -8
  234. package/dist/workspace/trust/ref-gate-cli.d.ts +10 -1
  235. package/dist/workspace/trust/ref-gate-cli.d.ts.map +1 -1
  236. package/dist/workspace/trust/ref-gate-cli.js +30 -10
  237. package/dist/workspace/workspace-run.d.ts.map +1 -1
  238. package/dist/workspace/workspace-run.js +2 -1
  239. package/package.json +1 -1
  240. package/src/actor.test.ts +68 -2
  241. package/src/actor.ts +61 -1
  242. package/src/chant-install.test.ts +2 -3
  243. package/src/chant-install.ts +1 -2
  244. package/src/ci-base.test.ts +41 -0
  245. package/src/ci-base.ts +43 -0
  246. package/src/ci-comment-commands.test.ts +439 -0
  247. package/src/ci-comment-commands.ts +428 -0
  248. package/src/ci-comment-replies.ts +78 -0
  249. package/src/ci-commit.test.ts +2 -3
  250. package/src/ci-evidence-from-job.test.ts +18 -0
  251. package/src/ci-evidence-from-job.ts +58 -2
  252. package/src/ci-evidence-jobs.ts +50 -5
  253. package/src/ci-image.test.ts +130 -10
  254. package/src/ci-image.ts +85 -12
  255. package/src/ci-job-guard.before-merge.test.ts +148 -0
  256. package/src/ci-job-guard.follow-on-record.test.ts +137 -0
  257. package/src/ci-job-guard.follow-on.test.ts +144 -0
  258. package/src/ci-job-guard.ts +221 -3
  259. package/src/ci-note-commands.test.ts +76 -1
  260. package/src/ci-note-commands.ts +198 -46
  261. package/src/ci-product-words.ts +59 -0
  262. package/src/ci-product.ts +90 -6
  263. package/src/cli/commands/build.test.ts +41 -0
  264. package/src/cli/commands/build.ts +27 -2
  265. package/src/cli/handlers/approve.ts +2 -1
  266. package/src/cli/handlers/ci-check.ts +19 -7
  267. package/src/cli/handlers/ci-evidence.ts +29 -8
  268. package/src/cli/handlers/components.ts +3 -1
  269. package/src/cli/handlers/generated-check.ts +31 -1
  270. package/src/cli/handlers/lock-reach.test.ts +103 -0
  271. package/src/cli/handlers/lock.ts +100 -4
  272. package/src/cli/handlers/pr-comment.ts +187 -0
  273. package/src/cli/handlers/pr-env.ts +6 -3
  274. package/src/cli/handlers/pr-notes.ts +30 -6
  275. package/src/cli/handlers/pr-record.test.ts +1 -1
  276. package/src/cli/handlers/pr.ts +64 -21
  277. package/src/cli/handlers/promote.ts +2 -1
  278. package/src/cli/handlers/release.e2e.test.ts +35 -0
  279. package/src/cli/handlers/release.ts +14 -2
  280. package/src/cli/handlers/run-wave.ts +170 -4
  281. package/src/cli/handlers/run.ts +2 -1
  282. package/src/cli/main.ts +41 -2
  283. package/src/cli/parse-args.ts +23 -0
  284. package/src/cli/registry.ts +19 -1
  285. package/src/components/auto-release.ts +2 -1
  286. package/src/components/pr-checks.ts +165 -17
  287. package/src/components/pr-pipeline.ts +22 -18
  288. package/src/components/product-pipeline.apply-status.test.ts +50 -0
  289. package/src/components/product-pipeline.ts +204 -17
  290. package/src/components/product-plan.test.ts +60 -4
  291. package/src/components/product-plan.ts +367 -50
  292. package/src/drift-record.test.ts +20 -0
  293. package/src/drift-record.ts +16 -0
  294. package/src/floor-table.data.ts +63 -31
  295. package/src/forge-check/contract.ts +12 -1
  296. package/src/forge-check/forge-check.test.ts +17 -0
  297. package/src/forge-check/index.ts +2 -0
  298. package/src/gate-resume-run.ts +27 -3
  299. package/src/generated-check.e2e.test.ts +21 -1
  300. package/src/generated-check.test.ts +66 -0
  301. package/src/generated-check.ts +51 -10
  302. package/src/image-pins.ts +31 -0
  303. package/src/lexicon.ts +89 -1
  304. package/src/lifecycle/gate-applied.ts +7 -0
  305. package/src/lifecycle/git.test.ts +48 -0
  306. package/src/lifecycle/git.ts +27 -4
  307. package/src/lifecycle/publish-npm.ts +31 -1
  308. package/src/lifecycle/reach-locks.test.ts +87 -0
  309. package/src/lifecycle/reach-locks.ts +169 -0
  310. package/src/lifecycle/release-cut.ts +17 -1
  311. package/src/lifecycle/release-images.test.ts +56 -0
  312. package/src/lifecycle/release-images.ts +1 -2
  313. package/src/notify-product.ts +19 -8
  314. package/src/op/activities/source-release.ts +2 -1
  315. package/src/op/activities/source-rollback.ts +2 -1
  316. package/src/op/apply-status.test.ts +83 -0
  317. package/src/op/apply-status.ts +132 -0
  318. package/src/op/before-merge-decide.ts +190 -0
  319. package/src/op/before-merge-done.ts +99 -0
  320. package/src/op/before-merge-store.ts +44 -0
  321. package/src/op/before-merge.test.ts +201 -0
  322. package/src/op/before-merge.ts +266 -0
  323. package/src/op/follow-on-run.ts +206 -0
  324. package/src/op/follow-on-store.ts +54 -0
  325. package/src/op/gate-resume.test.ts +27 -0
  326. package/src/op/gate.ts +16 -1
  327. package/src/op/index.ts +15 -0
  328. package/src/op/op-waves-after-plan.ts +13 -0
  329. package/src/op/op-waves-evidence-jobs.ts +21 -7
  330. package/src/op/op-waves-follow-on-record.test.ts +152 -0
  331. package/src/op/op-waves-follow-on.test.ts +247 -0
  332. package/src/op/op-waves-follow-on.ts +385 -0
  333. package/src/op/op-waves-notify-words.test.ts +18 -0
  334. package/src/op/op-waves-render-spec.test.ts +159 -0
  335. package/src/op/op-waves-render-spec.ts +171 -0
  336. package/src/op/op-waves-run.ts +973 -94
  337. package/src/op/op-waves-split-product.test.ts +288 -0
  338. package/src/op/op-waves-split-step.test.ts +298 -0
  339. package/src/op/op-waves-split.test.ts +196 -0
  340. package/src/op/op-waves-split.ts +189 -0
  341. package/src/op/op-waves.ts +31 -3
  342. package/src/op/schedule-overdue.test.ts +72 -1
  343. package/src/op/schedule-overdue.ts +84 -6
  344. package/src/op/stage-hooks.ts +52 -4
  345. package/src/op/wave-stop.test.ts +72 -0
  346. package/src/op/wave-stop.ts +139 -0
  347. package/src/planned-files.test.ts +80 -0
  348. package/src/planned-files.ts +134 -0
  349. package/src/pr-forge-job.test.ts +53 -0
  350. package/src/pr-forge-job.ts +46 -0
  351. package/src/pr-loop-narrowed.test.ts +2 -1
  352. package/src/pr-loop-words.test.ts +2 -1
  353. package/src/pr-loop.test.ts +1 -2
  354. package/src/pr-loop.ts +4 -80
  355. package/src/pr-plan-note.ts +155 -3
  356. package/src/pr-post-replan.test.ts +144 -0
  357. package/src/pr-post-subject.test.ts +230 -0
  358. package/src/pr-post.test.ts +2 -1
  359. package/src/pr-post.ts +151 -15
  360. package/src/pr-status.ts +91 -0
  361. package/src/ref-gate-init.ts +30 -11
  362. package/src/release-floors.ts +81 -25
  363. package/src/render-module.ts +73 -0
  364. package/src/state-migration-record.test.ts +2 -3
  365. package/src/state-migration.ts +1 -2
  366. package/src/wave-blocked.ts +9 -4
  367. package/src/workspace/ci-green-cli.ts +3 -2
  368. package/src/workspace/ci-green-workflow.test.ts +32 -1
  369. package/src/workspace/release-train.ts +2 -1
  370. package/src/workspace/release-workflow.test.ts +36 -5
  371. package/src/workspace/release-workflow.ts +10 -7
  372. package/src/workspace/trust/check-evidence-report.ts +15 -8
  373. package/src/workspace/trust/check-evidence.test.ts +5 -0
  374. package/src/workspace/trust/ref-gate-cli.ts +30 -8
  375. package/src/workspace/trust/ref-gate-pieces.test.ts +46 -1
  376. package/src/workspace/trust/ref-gate.test.ts +10 -0
  377. package/src/workspace/workspace-run.ts +2 -1
@@ -51,8 +51,9 @@
51
51
 
52
52
  import { execFileSync, spawnSync } from "node:child_process";
53
53
  import { createHash } from "node:crypto";
54
- import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
54
+ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
55
55
  import { dirname, isAbsolute, join, posix } from "node:path";
56
+ import { OP_WAVE_PHASES, OP_WAVE_RUN_RECORD_FILE, opWaveRunRecordFileName, opWaveSavedPlanPath, type OpWavePhase } from "./op-waves-split";
56
57
  import { CHANT_EXIT } from "../exit-codes";
57
58
  import type { ResolvedGatePolicySource } from "../policy-source";
58
59
  import {
@@ -76,11 +77,11 @@ import {
76
77
  writeWaveOutcomeFile,
77
78
  type WaveMemberOutcome,
78
79
  } from "../wave-blocked";
79
- import { approveCommand, evaluateGate, gitGateLedgerPort, type GateCheck, type GateDigestMismatch, type GateLedgerPort } from "./gate";
80
+ import { approveCommand, evaluateGate, gitGateLedgerPort, type GateCheck, type GateCheckInput, type GateDigestMismatch, type GateLedgerPort } from "./gate";
80
81
  import type { GateAnswerRef, PendingGateInput, PendingGateRecord } from "../lifecycle/gate-ledger";
81
82
  import type { GatePointAsker } from "../point-decision";
82
83
  import type { WaitingPoint } from "./steward-points";
83
- import { isApprovalSpent, type AppliedGateRecord, type FinishedGateRecord } from "../lifecycle/gate-applied";
84
+ import { finishedApply, isApprovalSpent, type AppliedGateRecord, type FinishedGateRecord } from "../lifecycle/gate-applied";
84
85
  import { samePlanDigest } from "../lifecycle/plan-digest";
85
86
  import { movedSincePreview } from "./op-waves-preview";
86
87
  import { isLifecycleLocalNote } from "../lifecycle/local-note";
@@ -106,7 +107,7 @@ import type { RunEventResource } from "../run-event";
106
107
  import { opWaveReleaseNames, type OpWaveReleaseOutcome, type OpWaveReleasePort, type OpWaveReleaseRequest } from "./op-waves-release";
107
108
  import { gitOpWaveReleasePort } from "./op-waves-release-port";
108
109
  import type { LockGrain } from "../lifecycle/lock-rows";
109
- import type { LockLiveness } from "../lifecycle/resource-lock";
110
+ import type { LockLiveness, LockRowsLease } from "../lifecycle/resource-lock";
110
111
  import type { GatePolicyExec } from "../gate-policy";
111
112
  import { gitOpWaveNewerCommit, opWaveStandDownReason, tipAppliesTargets, type OpWaveNewerCommitPort } from "./op-waves-stand-down";
112
113
  import { keyedSerial, mapLimited, type SerialSection } from "../parallelism";
@@ -141,6 +142,7 @@ import {
141
142
  assertOpWaveHooks,
142
143
  assertOpWavesSpec,
143
144
  opWaveApplyHooksRunBy,
145
+ opWaveAt,
144
146
  opWaveGateName,
145
147
  opWaveHooksAt,
146
148
  opWaveHookRuns,
@@ -173,6 +175,7 @@ import {
173
175
  holdFinishedPath,
174
176
  readHoldFinished,
175
177
  readHoldRequest,
178
+ inProcessHookOf,
176
179
  runHookList,
177
180
  runHookListAsync,
178
181
  runStageHooks,
@@ -186,6 +189,8 @@ import {
186
189
  type OpWaveHoldRequest,
187
190
  type OpWaveHookOutcome,
188
191
  type OpWaveHookRun,
192
+ type OpWaveInProcessHook,
193
+ type OpWaveInProcessHookCall,
189
194
  type OtherGateHold,
190
195
  type RunStageHooksAsyncOptions,
191
196
  type RunStageHooksOptions,
@@ -193,7 +198,7 @@ import {
193
198
  } from "./stage-hooks";
194
199
 
195
200
  export { OP_WAVE_PENDING_RESERVED, opWaveArgv, runStageHooks, runStageHooksAsync, spawnExecAsync };
196
- export type { OpWaveAsyncExec, OpWaveExec, OpWaveHoldFinished, OpWaveHoldRequest, OpWaveHookOutcome, OpWaveHookRun, RunStageHooksAsyncOptions, RunStageHooksOptions, StageHooksRun };
201
+ export type { OpWaveAsyncExec, OpWaveExec, OpWaveHoldFinished, OpWaveHoldRequest, OpWaveHookOutcome, OpWaveHookRun, OpWaveInProcessHook, OpWaveInProcessHookCall, RunStageHooksAsyncOptions, RunStageHooksOptions, StageHooksRun };
197
202
 
198
203
  /** What a run's plan command writes to `{plan}`. */
199
204
  export interface OpWavePlanFile {
@@ -421,6 +426,12 @@ export interface OpWaveDecision {
421
426
  * workspace at base, or no policy ran.
422
427
  */
423
428
  ciPolicySource?: ResolvedGatePolicySource;
429
+ /**
430
+ * A split wave with a `step` (#4992): the rows its gate job leased for
431
+ * the applying jobs, held with no heartbeat until its record job lets go
432
+ * of them, or the forge says the run is gone.
433
+ */
434
+ lease?: OpWaveSplitLease;
424
435
  }
425
436
 
426
437
  /**
@@ -489,6 +500,27 @@ export interface OpWaveHeldOn {
489
500
  * approved, oldest first (#3847): its approved re-runs asked for this one.
490
501
  */
491
502
  after?: OpWaveHeldOnApproval[];
503
+ /**
504
+ * Set by a split wave's plan or apply job (#4992), which holds no write
505
+ * token: the pending fact it read the gate for and did not record, and
506
+ * the file the request carries. The gate job (for a plan job's hold) or
507
+ * the record job (for an apply job's) records them and drops this.
508
+ *
509
+ * `spend` (#4994): the gate is approved and the hold asks chant to
510
+ * `record` it, so its approval is spent before the hook runs again. The
511
+ * plan job cannot spend it; the gate job checks the approval again under
512
+ * its own rules and spends it for a re-run of the hook at `head`, and the
513
+ * wave waits until it runs again from its plan job.
514
+ */
515
+ deferred?: { input: GateCheckInput; mode: GateApprovalSource; base: string; attachment?: string; spend?: { approvedBy: string; approvedAt: string; head?: string } };
516
+ /**
517
+ * Set by a split wave's plan job (#4994): the applied line the gate job of
518
+ * an earlier run of the same head wrote for this hold, with no finished
519
+ * line yet. The hook runs again under it, and the next gate job writes the
520
+ * finished line. On a decision it says the approval was spent for that
521
+ * re-run and the wave waits for it.
522
+ */
523
+ spentForRerun?: AppliedGateRecord;
492
524
  }
493
525
 
494
526
  /** An approved hold on another gate (#3847), as `CHANT_HOLD_APPROVED` and `CHANT_HOLDS_APPROVED` carry it. */
@@ -578,7 +610,8 @@ export interface OpWaveApplyHooksRun {
578
610
  /** Reads one file at one commit, or null when the commit has no such file. Injected for tests. */
579
611
  export type OpWaveShowAtBase = (base: string, path: string, cwd: string) => { sha: string; text: string | null };
580
612
 
581
- const gitShowAtBase: OpWaveShowAtBase = (base, path, cwd) => {
613
+ /** {@link OpWaveShowAtBase} through git: `git show <base>:<path>`. A run-time spec (#4982, `./op-waves-render-spec.ts`) reads every other file through it. */
614
+ export const gitShowAtBase: OpWaveShowAtBase = (base, path, cwd) => {
582
615
  let sha: string;
583
616
  try {
584
617
  sha = execFileSync("git", ["rev-parse", "--verify", `${base}^{commit}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
@@ -796,6 +829,17 @@ export interface RunOpWaveOptions {
796
829
  * {@link opWaveChecksDir} and no outcome file or run record.
797
830
  */
798
831
  policyOnly?: boolean;
832
+ /**
833
+ * One of the four jobs of a split wave before merge (#4987,
834
+ * `./op-waves-split.ts`). `plan`: plan the wave and save the plan
835
+ * ({@link OpWaveSavedPlan}), writing nothing to `chant/lifecycle`. `gate`:
836
+ * read the rules at base, check the saved plan against its plan files,
837
+ * and decide the gate on it as a deciding job does. `apply`: apply the
838
+ * saved plan files whose digest the decision holds, as a share job does,
839
+ * and leave the run record in a file. `record`: write those run records
840
+ * to the run ledger. A `step` spec cannot run in phases.
841
+ */
842
+ phase?: OpWavePhase;
799
843
  /** Apply this 1-based share of a decided wave, or with `group`, of that job group. */
800
844
  share?: number;
801
845
  /**
@@ -926,6 +970,16 @@ export interface RunOpWaveOptions {
926
970
  * while a hook does. Default: `exec`, which waits with `spawnSync`.
927
971
  */
928
972
  hookExec?: OpWaveAsyncExec;
973
+ /**
974
+ * Hooks served in the job's own process (#4994), by the spec hook's
975
+ * `name`: a hook the spec names (read at base) whose name this holds is
976
+ * called with its command's argv and variables in place of running the
977
+ * command, at every moment and in every job that runs it, a split wave's
978
+ * plan, gate and applying jobs included. Its exit code counts as the
979
+ * command's, and its approved re-run after a hold on another gate calls it
980
+ * again. See {@link OpWaveInProcessHook}.
981
+ */
982
+ inProcessHooks?: Readonly<Record<string, OpWaveInProcessHook>>;
929
983
  }
930
984
 
931
985
  /** Where an op wave job's run record goes (#4551). */
@@ -982,6 +1036,8 @@ export interface RunOpWaveResult {
982
1036
  plans?: Record<string, OpRunWavePlan>;
983
1037
  /** With `policyOnly` (#4926): the `ci.policy` rows the wave's policy hold gave, in run order. Empty when no policy ran. */
984
1038
  policyRows?: OpRunPolicyRow[];
1039
+ /** A split wave's applying job (#4992): what its record job writes with the token, beside the run record. */
1040
+ handoff?: OpWaveSplitHandoff;
985
1041
  }
986
1042
 
987
1043
  /** What one wave job works with. */
@@ -1345,7 +1401,8 @@ async function leaseWaveRows(
1345
1401
  options: RunOpWaveOptions,
1346
1402
  ctx: WaveContext,
1347
1403
  runs: readonly OpWaveRun[],
1348
- ): Promise<{ release(): Promise<boolean> } | OpWaveApplyOutcome | { failed: string } | undefined> {
1404
+ opts: { noBeat?: boolean } = {},
1405
+ ): Promise<{ release(): Promise<boolean>; held: OpWaveSplitLease[] } | OpWaveApplyOutcome | { failed: string } | undefined> {
1349
1406
  const locks = runs.flatMap((r) => {
1350
1407
  const plan = ctx.steps?.get(r.target);
1351
1408
  return plan?.lock && !plan.empty ? [plan.lock] : [];
@@ -1360,7 +1417,7 @@ async function leaseWaveRows(
1360
1417
  const gate = options.lockGate ?? PR_APPLY_GATE;
1361
1418
  const label = `wave ${ctx.k} (${ctx.wave.name})`;
1362
1419
  const alive = options.lockLiveness ? { alive: options.lockLiveness } : {};
1363
- const held: Array<{ release(): Promise<boolean> }> = [];
1420
+ const held: LockRowsLease[] = [];
1364
1421
  const releaseAll = async () => {
1365
1422
  let ok = true;
1366
1423
  for (const l of held.reverse()) ok = (await l.release()) && ok;
@@ -1380,7 +1437,9 @@ async function leaseWaveRows(
1380
1437
  },
1381
1438
  }
1382
1439
  : {};
1383
- leased = await leaseLockRows(gate, wanted, { cwd: ctx.cwd, ...alive, ...waitFor });
1440
+ // #4992: a split wave's gate job ends before its rows are applied, so its hold carries no heartbeat of its process:
1441
+ // the forge's run, the same in its applying and record jobs, keeps it, as a hold from before #4660 is kept.
1442
+ leased = await leaseLockRows(gate, wanted, { cwd: ctx.cwd, ...alive, ...waitFor, ...(opts.noBeat ? { beat: () => () => {} } : {}) });
1384
1443
  } catch (err) {
1385
1444
  return { failed: `${label}: could not hold the rows its runs change in ${gate}, so nothing was applied: ${err instanceof Error ? err.message : String(err)}` };
1386
1445
  }
@@ -1402,7 +1461,41 @@ async function leaseWaveRows(
1402
1461
  return stop;
1403
1462
  }
1404
1463
  }
1405
- return { release: releaseAll };
1464
+ return { release: releaseAll, held: held.map((l) => ({ gate: l.gate, run: l.holder.run, keys: [...l.keys] })) };
1465
+ }
1466
+
1467
+ /**
1468
+ * The lease of a split wave with a `step` (#4992), in its gate job: the
1469
+ * rows its runs wait for and change, taken as {@link leaseWaveRows} takes
1470
+ * them before an apply, with no heartbeat, since this job ends before the
1471
+ * applying jobs start. The decision names the lease, and the record job
1472
+ * lets go of it. A held row ends the wave here with the `held` outcome,
1473
+ * exit 5, before the approval is spent.
1474
+ */
1475
+ async function leaseSplitRows(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision, recordPath: string): Promise<{ end: RunOpWaveResult } | { release(): Promise<boolean> } | undefined> {
1476
+ const lease = await leaseWaveRows(options, ctx, ctx.wave.runs, { noBeat: true });
1477
+ if (!lease) return undefined;
1478
+ if ("failed" in lease) return { end: failed(ctx, lease.failed) };
1479
+ if ("outcome" in lease) {
1480
+ ctx.log(`wave ${ctx.k} (${ctx.wave.name}): applied nothing: ${lease.reason}`);
1481
+ ctx.result.outcome = lease;
1482
+ ctx.result.exitCode = CHANT_EXIT.held;
1483
+ writeRecord(recordPath, decision, ctx.result);
1484
+ return { end: ctx.result };
1485
+ }
1486
+ const first = lease.held[0];
1487
+ if (first) {
1488
+ decision.lease = { gate: first.gate, run: first.run, keys: [...new Set(lease.held.flatMap((h) => h.keys))].sort() };
1489
+ ctx.log(`wave ${ctx.k} (${ctx.wave.name}): holds ${decision.lease.keys.length} row${decision.lease.keys.length === 1 ? "" : "s"} of ${first.gate} for its applying jobs, until its record job lets go of them`);
1490
+ }
1491
+ return lease;
1492
+ }
1493
+
1494
+ /** Let go of the rows a split wave's gate job leased (#4992), as the holder the decision names. */
1495
+ async function releaseSplitLease(cwd: string, lease: OpWaveSplitLease, k: number, log: (line: string) => void): Promise<void> {
1496
+ const { releaseLockRows } = await import("../lifecycle/resource-lock");
1497
+ if (await releaseLockRows(lease.gate, lease.keys, lease.run, { cwd })) log(`wave ${k}: let go of the ${lease.keys.length} row${lease.keys.length === 1 ? "" : "s"} of ${lease.gate} its gate job held`);
1498
+ else log(`wave ${k}: could not let go of the rows its gate job held on ${lease.gate}; the next apply takes them over once this run is gone`);
1406
1499
  }
1407
1500
 
1408
1501
  function inGitWorkTree(cwd: string): boolean {
@@ -1663,9 +1756,11 @@ async function runHooks(
1663
1756
  ): Promise<HooksOutcome> {
1664
1757
  if (!hooks || hooks.length === 0) return { holds: [] };
1665
1758
  const runsPath = writeRunsFile(ctx, runs, members, digest);
1666
- const hookExec = ctx.options.hookExec;
1759
+ const own = ctx.options.inProcessHooks;
1760
+ // #4994: a hook the job's process serves runs in it; the other hooks run as before, through hookExec or exec.
1761
+ const hookExec = ctx.options.hookExec ?? (own ? (argv: string[], cwd: string, env?: Record<string, string>) => Promise.resolve(ctx.exec(argv, cwd, env)) : undefined);
1667
1762
  const out = hookExec
1668
- ? await runHookListAsync({ ...placeOf(ctx), exec: hookExec }, moment, hooks, hookRuns(ctx, runs, members), runsPath, extraEnv)
1763
+ ? await runHookListAsync({ ...placeOf(ctx), exec: hookExec, ...(own ? { inProcess: own } : {}) }, moment, hooks, hookRuns(ctx, runs, members), runsPath, extraEnv)
1669
1764
  : runHookList(placeOf(ctx), moment, hooks, hookRuns(ctx, runs, members), runsPath, extraEnv);
1670
1765
  ctx.result.hooks.push(...out.outcomes);
1671
1766
  const back: HooksOutcome = { holds: out.holds, ...(out.failed ? { failed: out.failed } : {}) };
@@ -1695,7 +1790,22 @@ async function runHooks(
1695
1790
  // #4623: a hold that asks chant to record its gate is spent here, before the re-run acts under the approval.
1696
1791
  let spent: AppliedGateRecord | undefined;
1697
1792
  let finishedAt: string | undefined;
1698
- if (hold.request.record) {
1793
+ // #4994: the gate job of an earlier run of this head spent the approval for this re-run; the gate job after this
1794
+ // plan job writes the finished line, from what the re-run leaves at CHANT_HOLD_FINISHED.
1795
+ const spentEarlier = hold.request.record && ctx.options.phase === "plan" ? held.spentForRerun : undefined;
1796
+ if (spentEarlier) {
1797
+ spent = spentEarlier;
1798
+ const finishedRel = holdFinishedPath(hold.env.CHANT_HOLD!);
1799
+ finishedAt = join(ctx.cwd, finishedRel);
1800
+ rmSync(finishedAt, { force: true });
1801
+ approvedEnv.CHANT_HOLD_FINISHED = finishedRel;
1802
+ } else if (hold.request.record && noTokenPhase(ctx.options)) {
1803
+ // #4992: the approval is spent before the re-run acts under it, and a job with no write token cannot spend it.
1804
+ ctx.result.hooks.push({ moment, name: hold.name, ...target, exit: 1, outcome: "failed" });
1805
+ back.failed = `${hold.label}: ${held.approvedBy} approved ${held.op} / ${held.gate}, and the hold asks chant to record the gate, which spends the approval before the hook runs again; this ${ctx.options.phase} job of a split wave holds no write token, so it cannot spend it and the hook did not run again`;
1806
+ ctx.log(back.failed);
1807
+ return back;
1808
+ } else if (hold.request.record) {
1699
1809
  const got = await spendHeldGate(ctx, hold, now);
1700
1810
  if ("failed" in got) {
1701
1811
  ctx.result.hooks.push({ moment, name: hold.name, ...target, exit: 1, outcome: "failed" });
@@ -1711,12 +1821,17 @@ async function runHooks(
1711
1821
  }
1712
1822
  let code: number;
1713
1823
  try {
1714
- code = hookExec ? await hookExec(hold.argv, ctx.cwd, approvedEnv) : ctx.exec(hold.argv, ctx.cwd, approvedEnv);
1824
+ // #4994: an in-process hook runs again in this process, as it ran the first time.
1825
+ const again = inProcessHookOf(own, hold.name);
1826
+ code = again
1827
+ ? await again({ name: hold.name, moment: hold.moment, ...(hold.target ? { target: hold.target } : {}), argv: hold.argv, cwd: ctx.cwd, env: approvedEnv })
1828
+ : hookExec ? await hookExec(hold.argv, ctx.cwd, approvedEnv) : ctx.exec(hold.argv, ctx.cwd, approvedEnv);
1715
1829
  } catch (err) {
1716
1830
  ctx.log(`${hold.label} did not run: ${err instanceof Error ? err.message : String(err)}`);
1717
1831
  code = 127;
1718
1832
  }
1719
- if (spent && finishedAt) await finishHeldGate(ctx, hold, spent, readHoldFinished(finishedAt, ctx.log, hold.label), code);
1833
+ if (spent && finishedAt && spentEarlier) handHoldFinished(ctx, hold, spent, readHoldFinished(finishedAt, ctx.log, hold.label), code);
1834
+ else if (spent && finishedAt) await finishHeldGate(ctx, hold, spent, readHoldFinished(finishedAt, ctx.log, hold.label), code);
1720
1835
  if (code === 0) {
1721
1836
  ctx.result.hooks.push({ moment, name: hold.name, ...target, exit: code, outcome: "passed" });
1722
1837
  ctx.log(`${hold.label}: ${held.approvedBy} approved ${held.op} / ${held.gate} at ${held.digest}, and the hook ran again and passed`);
@@ -1869,18 +1984,14 @@ async function settleOtherGate(ctx: WaveContext, hold: OtherGateHold, runs: read
1869
1984
  const { port } = await gatePort(ctx.options, ctx.cwd, hold.request.gate, mode, rules.base);
1870
1985
  const neverOverMcp = rules.neverOverMcp;
1871
1986
  const now = ctx.options.now ?? new Date().toISOString();
1987
+ // #4992: a split wave's plan and apply jobs hold no write token. They read the other gate and, while it waits, leave its
1988
+ // pending fact and the file the request carries to the gate or record job, which records them (recordDeferredHold).
1989
+ const deferring = noTokenPhase(ctx.options);
1872
1990
  // #4623: the file the request carries, stored once before the pending fact, which names its SHA-256.
1873
1991
  const attachment = hold.request.attachment;
1874
- if (attachment !== undefined) {
1875
- try {
1876
- if (!port.storeRequestAttachment) throw new Error("this gate ledger keeps no request files");
1877
- await port.storeRequestAttachment(op, hold.request.digest, attachment);
1878
- } catch (err) {
1879
- log(`${op} / ${hold.request.gate}: the file ${hold.label} attached was not stored beside the pending fact: ${err instanceof Error ? err.message : String(err)}`);
1880
- }
1881
- }
1992
+ if (attachment !== undefined && !deferring) await storeHoldAttachment(port, op, hold.request.digest, attachment, `${op} / ${hold.request.gate}: the file ${hold.label} attached`, log);
1882
1993
  const proof = attachment !== undefined ? { proof: `sha256:${createHash("sha256").update(attachment).digest("hex")}` } : {};
1883
- const check = await evaluateGate(port, {
1994
+ const input: GateCheckInput = {
1884
1995
  op,
1885
1996
  gate: hold.request.gate,
1886
1997
  planDigest: hold.request.digest,
@@ -1889,14 +2000,40 @@ async function settleOtherGate(ctx: WaveContext, hold: OtherGateHold, runs: read
1889
2000
  // #3839: the wave a hold belongs to, as a field, whatever the hook's own description says.
1890
2001
  fields: { ...hold.request.pending, ...proof, approvalMode: rules.approval, wave: { number: k, name: wave.name, op: spec.name }, heldBy: { hook: hold.name, moment: hold.moment, ...(hold.target ? { target: hold.target } : {}) } },
1891
2002
  ...(neverOverMcp ? { neverOverMcp: true } : {}),
1892
- });
2003
+ };
2004
+ const check = await evaluateGate(deferring ? readOnlyGatePort(port) : port, input);
1893
2005
  const base = { op, gate: hold.request.gate, digest: hold.request.digest, hook: hold.label };
1894
2006
  logRefused(log, `${op} / ${hold.request.gate}`, check);
1895
- if (check.satisfied) return { ...base, status: "approved", approvedBy: check.resolution.resolvedBy, approvedAt: check.resolution.timestamp };
1896
2007
  // #4574: a per-run hook's hold names its run; else the wave's target, as the wave's own gate does.
1897
2008
  const target = hold.target ?? waveApproveTarget(wave.name, runs.map((r) => r.target));
1898
2009
  const approve = approveCommand(op, hold.request.gate, undefined, hold.request.digest, mode === "sealed", target);
2010
+ // #4994: a split wave's plan job cannot spend the approval a `record` hold needs spent before its hook runs again.
2011
+ const spendLater = deferring && hold.request.record === true && ctx.options.phase === "plan";
2012
+ if (spendLater) {
2013
+ // The gate job of an earlier run of this commit spent the approval for this very re-run, and no finished line names it yet.
2014
+ const spent = await spentForRerun(port, op, hold.request.gate, hold.request.digest, waveHeadOf(ctx.options, ctx.cwd));
2015
+ if (spent) {
2016
+ log(`${hold.label}: the approval by ${spent.approvedBy} of ${op} / ${hold.request.gate} at ${hold.request.digest} was spent at ${spent.timestamp} for this re-run of the hook, so it runs again under it`);
2017
+ return { ...base, status: "approved", approvedBy: spent.approvedBy, approvedAt: spent.approvedAt, spentForRerun: spent };
2018
+ }
2019
+ }
2020
+ if (check.satisfied && spendLater) {
2021
+ const head = waveHeadOf(ctx.options, ctx.cwd);
2022
+ log(`wave ${k} (${wave.name}): ${check.resolution.resolvedBy} approved ${op} / ${hold.request.gate} at ${hold.request.digest}, and ${hold.label} asks chant to record the gate, which spends the approval before the hook runs again; this plan job holds no write token, so the gate job spends it and the wave waits until it runs again from its plan job, where the hook runs again under it`);
2023
+ return {
2024
+ ...base,
2025
+ status: "waiting",
2026
+ approve,
2027
+ recorded: false,
2028
+ deferred: { input, mode, base: rules.base, ...(attachment !== undefined ? { attachment } : {}), spend: { approvedBy: check.resolution.resolvedBy, approvedAt: check.resolution.timestamp, ...(head ? { head } : {}) } },
2029
+ };
2030
+ }
2031
+ if (check.satisfied) return { ...base, status: "approved", approvedBy: check.resolution.resolvedBy, approvedAt: check.resolution.timestamp };
1899
2032
  log(`wave ${k} (${wave.name}) waits on ${op} / ${hold.request.gate}, which ${hold.label} holds it on: nobody approved ${hold.request.digest}. Approve: ${approve}`);
2033
+ if (deferring) {
2034
+ log(`wave ${k} (${wave.name}): this job holds no write token, so the ${ctx.options.phase === "plan" ? "gate" : "record"} job records the pending fact of ${op} / ${hold.request.gate}`);
2035
+ return { ...base, status: "waiting", approve, recorded: false, deferred: { input, mode, base: rules.base, ...(attachment !== undefined ? { attachment } : {}) }, ...(check.mismatch ? { mismatch: check.mismatch } : {}) };
2036
+ }
1900
2037
  return {
1901
2038
  ...base,
1902
2039
  status: "waiting",
@@ -1907,6 +2044,225 @@ async function settleOtherGate(ctx: WaveContext, hold: OtherGateHold, runs: read
1907
2044
  };
1908
2045
  }
1909
2046
 
2047
+ /** The commit a wave job runs (#4994): `options.head`, a split wave's decided head, else the checkout's HEAD; undefined outside a git checkout. */
2048
+ function waveHeadOf(options: Pick<RunOpWaveOptions, "head">, cwd: string): string | undefined {
2049
+ if (options.head) return options.head;
2050
+ try {
2051
+ return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
2052
+ } catch {
2053
+ return undefined;
2054
+ }
2055
+ }
2056
+
2057
+ /**
2058
+ * The applied line a split wave's gate job wrote for a re-run of a held
2059
+ * hook at `head` (#4994), when no finished line names it yet; else
2060
+ * undefined. A port that cannot read finished lines gives none, so no
2061
+ * approval is used twice.
2062
+ */
2063
+ async function spentForRerun(port: GateLedgerPort, op: string, gate: string, digest: string, head: string | undefined): Promise<AppliedGateRecord | undefined> {
2064
+ if (!head || !port.readApplied || !port.readFinished) return undefined;
2065
+ const line = (await port.readApplied(op)).filter((a) => a.gate === gate && samePlanDigest(a.planDigest, digest)).at(-1);
2066
+ if (!line || line.rerun?.head !== head) return undefined;
2067
+ return finishedApply(await port.readFinished(op), line) ? undefined : line;
2068
+ }
2069
+
2070
+ /** The finished lines a split wave's plan job leaves its gate job to write (#4994), by the job's options. */
2071
+ const handedFinished = new WeakMap<RunOpWaveOptions, OpWaveHandedFinished[]>();
2072
+
2073
+ /**
2074
+ * A held hook's re-run in a split wave's plan job under an approval an
2075
+ * earlier gate job spent (#4994): how it ended, which the gate job after
2076
+ * this plan job writes as the finished line.
2077
+ */
2078
+ export interface OpWaveHandedFinished {
2079
+ hook: string;
2080
+ /** The applied line the re-run ran under. */
2081
+ applied: Pick<AppliedGateRecord, "op" | "gate" | "planDigest" | "timestamp" | "rerun">;
2082
+ result: "applied" | "failed";
2083
+ detail?: Record<string, string | number | boolean>;
2084
+ }
2085
+
2086
+ /** Keep a re-run's end for the gate job (#4994), in the saved plan. */
2087
+ function handHoldFinished(ctx: WaveContext, hold: OtherGateHold, spent: AppliedGateRecord, wrote: OpWaveHoldFinished | undefined, code: number): void {
2088
+ const list = handedFinished.get(ctx.options) ?? [];
2089
+ list.push({
2090
+ hook: hold.label,
2091
+ applied: { op: spent.op, gate: spent.gate, planDigest: spent.planDigest, timestamp: spent.timestamp, ...(spent.rerun ? { rerun: spent.rerun } : {}) },
2092
+ result: wrote?.result ?? (code === 0 ? "applied" : "failed"),
2093
+ ...(wrote?.detail ? { detail: wrote.detail } : {}),
2094
+ });
2095
+ handedFinished.set(ctx.options, list);
2096
+ }
2097
+
2098
+ /**
2099
+ * Write the finished lines a split wave's plan job handed on (#4994), with
2100
+ * the token: each for an applied line the ledger holds, spent for a re-run
2101
+ * at this job's head and not finished yet. The plan job ran the change's
2102
+ * code, so a line it names that is not one of those is left out.
2103
+ */
2104
+ async function writeHandedFinished(options: RunOpWaveOptions, cwd: string, handed: readonly OpWaveHandedFinished[] | undefined, log: (line: string) => void): Promise<void> {
2105
+ if (!handed?.length) return;
2106
+ const port = options.gates ?? gitGateLedgerPort({ cwd });
2107
+ const head = waveHeadOf(options, cwd);
2108
+ for (const h of handed) {
2109
+ const where = `${h.applied.op} / ${h.applied.gate}`;
2110
+ try {
2111
+ if (!port.appendFinished || !port.readApplied || !port.readFinished) throw new Error("this gate ledger keeps no finished lines");
2112
+ const line = (await port.readApplied(h.applied.op)).find((a) => a.gate === h.applied.gate && samePlanDigest(a.planDigest, h.applied.planDigest) && a.timestamp === h.applied.timestamp);
2113
+ if (!line || !head || line.rerun?.head !== head) {
2114
+ log(`${h.hook}: the plan job says it ran again under ${where} applied at ${h.applied.timestamp}, which the ledger holds no re-run of this commit for, so no finished line is written`);
2115
+ continue;
2116
+ }
2117
+ if (finishedApply(await port.readFinished(h.applied.op), line)) continue;
2118
+ const record: FinishedGateRecord = {
2119
+ version: 1,
2120
+ kind: "finished",
2121
+ op: line.op,
2122
+ gate: line.gate,
2123
+ planDigest: line.planDigest,
2124
+ applied: line.timestamp,
2125
+ result: h.result,
2126
+ timestamp: options.now ?? new Date().toISOString(),
2127
+ ...(h.detail ? { detail: h.detail } : {}),
2128
+ };
2129
+ const pushed = await port.appendFinished(record);
2130
+ if (!pushed.pushed && pushed.pushWarning && !isLifecycleLocalNote(pushed.pushWarning)) log(`${h.hook}: the finished line of ${where} was written and not pushed: ${pushed.pushWarning}`);
2131
+ log(`${h.hook}: wrote the finished line of ${where} (${h.result}) for the plan job's re-run`);
2132
+ } catch (err) {
2133
+ log(`${h.hook}: the finished line of ${where} was not written: ${err instanceof Error ? err.message : String(err)}`);
2134
+ }
2135
+ }
2136
+ }
2137
+
2138
+ /**
2139
+ * Spend the approval a split wave's plan job found for a `record` hold
2140
+ * (#4994), with the token, under this job's rules at base: the gate is read
2141
+ * again, and still approved, an applied line bound to this job's head is
2142
+ * written for the hook's re-run in the next run's plan job. Not approved
2143
+ * any more, the hold is recorded as waiting (`recordDeferredHold`). A digest
2144
+ * already applied under the gate is not spent again.
2145
+ */
2146
+ async function spendDeferredHold(
2147
+ options: RunOpWaveOptions,
2148
+ ctx: WaveContext,
2149
+ heldOn: OpWaveHeldOn,
2150
+ log: (line: string) => void,
2151
+ ): Promise<{ heldOn: OpWaveHeldOn } | { failed: string }> {
2152
+ const deferred = heldOn.deferred!;
2153
+ const rule = ctx.gateRule;
2154
+ const mode: GateApprovalSource = rule.approval === "sealed" ? "sealed" : "ledger";
2155
+ const { port } = await gatePort(options, ctx.cwd, deferred.input.gate, mode, rule.base);
2156
+ const where = `${deferred.input.op} / ${deferred.input.gate}`;
2157
+ const digest = deferred.input.planDigest!;
2158
+ // A re-run this commit's earlier gate job spent the approval for, which the plan job did not take up: the wave waits for it.
2159
+ const pending = await spentForRerun(port, deferred.input.op, deferred.input.gate, digest, waveHeadOf(options, ctx.cwd));
2160
+ if (pending) {
2161
+ log(`${heldOn.hook}: the approval of ${where} at ${digest} is already spent for a re-run of the hook; the wave waits until it runs again from its plan job`);
2162
+ const { deferred: _d, ...rest } = heldOn;
2163
+ return { heldOn: { ...rest, approvedBy: pending.approvedBy, approvedAt: pending.approvedAt, spentForRerun: pending } };
2164
+ }
2165
+ const check = await evaluateGate(readOnlyGatePort(port), { ...deferred.input, now: options.now ?? new Date().toISOString(), ...(rule.neverOverMcp || deferred.input.neverOverMcp ? { neverOverMcp: true } : {}) });
2166
+ if (!check.satisfied) {
2167
+ log(`${heldOn.hook}: ${where} is not approved under this job's rules, so its approval is not spent`);
2168
+ const { spend: _s, ...waiting } = deferred;
2169
+ return { heldOn: await recordDeferredHold(options, ctx.cwd, { ...heldOn, deferred: waiting }, rule, log) };
2170
+ }
2171
+ const head = waveHeadOf(options, ctx.cwd);
2172
+ if (!head) return { failed: `${heldOn.hook}: this job cannot tell which commit the wave runs, so it does not spend the approval of ${where} for the hook's re-run` };
2173
+ if (deferred.spend?.head && deferred.spend.head !== head) return { failed: `${heldOn.hook}: the plan job ran at ${deferred.spend.head.slice(0, 12)} and this job at ${head.slice(0, 12)}, so the approval of ${where} is not spent` };
2174
+ try {
2175
+ if (!port.appendApplied || !port.readApplied) throw new Error("this gate ledger cannot record an applied approval");
2176
+ const prior = (await port.readApplied(deferred.input.op)).filter((a) => a.gate === deferred.input.gate && samePlanDigest(a.planDigest, digest)).at(-1);
2177
+ if (prior) return { failed: `${heldOn.hook}: ${where} at ${digest} applied already under the approval by ${prior.approvedBy} (${prior.timestamp}); a held request applies once, so it is not spent again` };
2178
+ const commit = typeof deferred.input.fields?.commit === "string" ? deferred.input.fields.commit : undefined;
2179
+ const runId = ciRunIdFromEnv();
2180
+ const record: AppliedGateRecord = {
2181
+ version: 1,
2182
+ kind: "applied",
2183
+ op: deferred.input.op,
2184
+ gate: deferred.input.gate,
2185
+ planDigest: digest,
2186
+ approvedAt: check.resolution.timestamp,
2187
+ approvedBy: check.resolution.resolvedBy,
2188
+ timestamp: options.now ?? new Date().toISOString(),
2189
+ wave: { number: ctx.k, name: ctx.wave.name },
2190
+ ...(runId ? { runId } : {}),
2191
+ ...(commit ? { commit } : {}),
2192
+ rerun: { head },
2193
+ };
2194
+ requireSpendPushed(await port.appendApplied(record));
2195
+ log(`${heldOn.hook}: ${where} applies under the approval by ${record.approvedBy} at ${record.approvedAt}, which is now spent for the hook's re-run at ${head.slice(0, 12)}; run the wave again, and its plan job runs the hook again under it`);
2196
+ const { deferred: _d, ...rest } = heldOn;
2197
+ return { heldOn: { ...rest, approvedBy: record.approvedBy, approvedAt: record.approvedAt, spentForRerun: record } };
2198
+ } catch (err) {
2199
+ return { failed: `${heldOn.hook}: could not record that ${where} applies under the approval by ${check.resolution.resolvedBy}: ${err instanceof Error ? err.message : String(err)}` };
2200
+ }
2201
+ }
2202
+
2203
+ /** Whether a split wave's job holds no write token (#4992): its plan and applying jobs run the change's code. */
2204
+ function noTokenPhase(options: Pick<RunOpWaveOptions, "phase">): boolean {
2205
+ return options.phase === "plan" || options.phase === "apply";
2206
+ }
2207
+
2208
+ /** Store the file a held request carries (#4623). A file not stored is logged; the pending fact still names its SHA-256. */
2209
+ async function storeHoldAttachment(port: GateLedgerPort, op: string, digest: string, attachment: string, what: string, log: (line: string) => void): Promise<void> {
2210
+ try {
2211
+ if (!port.storeRequestAttachment) throw new Error("this gate ledger keeps no request files");
2212
+ await port.storeRequestAttachment(op, digest, attachment);
2213
+ } catch (err) {
2214
+ log(`${what} was not stored beside the pending fact: ${err instanceof Error ? err.message : String(err)}`);
2215
+ }
2216
+ }
2217
+
2218
+ /**
2219
+ * The gate ledger as a job with no write token reads it (#4992): every read
2220
+ * the port has, and a pending fact that is never written. `evaluateGate`
2221
+ * then says whether the gate is approved, and the fact it would have
2222
+ * recorded goes to a job that can write it.
2223
+ */
2224
+ function readOnlyGatePort(port: GateLedgerPort): GateLedgerPort {
2225
+ const { appendResolution: _r, appendApplied: _a, appendFinished: _f, storeRequestAttachment: _s, writeCheckpoint: _c, ...reads } = port;
2226
+ return {
2227
+ ...reads,
2228
+ async appendPending(input) {
2229
+ return { record: { version: 1, kind: "pending", ...input } as PendingGateRecord, pushed: false, pushWarning: "not recorded: this job holds no write token" };
2230
+ },
2231
+ };
2232
+ }
2233
+
2234
+ /**
2235
+ * Record a hold on another gate that a split wave's plan or apply job left
2236
+ * (#4992): the file its request carries and the gate's pending fact, with
2237
+ * the token, as that job would have without the split. Returns the hold as
2238
+ * the decision records it. A gate approved since the plan or apply job read
2239
+ * it is said so: the wave waits all the same, and running it again from its
2240
+ * plan job goes on under the approval.
2241
+ */
2242
+ async function recordDeferredHold(
2243
+ options: RunOpWaveOptions,
2244
+ cwd: string,
2245
+ heldOn: OpWaveHeldOn,
2246
+ rule: { approval: GateApprovalSource; base: string; neverOverMcp: boolean },
2247
+ log: (line: string) => void,
2248
+ ): Promise<OpWaveHeldOn> {
2249
+ const deferred = heldOn.deferred;
2250
+ if (!deferred) return heldOn;
2251
+ const { deferred: _d, ...rest } = heldOn;
2252
+ // The approval mode, the base and neverOverMcp are this job's own, read at base, whatever the job that left the hold said.
2253
+ const mode: GateApprovalSource = rule.approval === "sealed" ? "sealed" : "ledger";
2254
+ const { port } = await gatePort(options, cwd, deferred.input.gate, mode, rule.base);
2255
+ const where = `${deferred.input.op} / ${deferred.input.gate}`;
2256
+ if (deferred.attachment !== undefined) await storeHoldAttachment(port, deferred.input.op, deferred.input.planDigest!, deferred.attachment, `${where}: the file ${heldOn.hook} attached`, log);
2257
+ const check = await evaluateGate(port, { ...deferred.input, now: options.now ?? new Date().toISOString(), ...(rule.neverOverMcp || deferred.input.neverOverMcp ? { neverOverMcp: true } : {}) });
2258
+ if (check.satisfied) {
2259
+ log(`${where} was approved by ${check.resolution.resolvedBy} after the job that ${heldOn.hook} ran in read it; the wave waits all the same, and goes on when it runs again from its plan job`);
2260
+ return rest;
2261
+ }
2262
+ log(`${where}: ${check.recorded ? "recorded the pending fact" : "the pending fact stands"} that ${heldOn.hook} holds wave ${options.wave} on`);
2263
+ return { ...rest, waitingSince: check.pending.timestamp, recorded: check.recorded };
2264
+ }
2265
+
1910
2266
  /**
1911
2267
  * Read the hooks file chant hands an apply command (#3804): the one at
1912
2268
  * `path`, by default `CHANT_HOOKS`. Null when there is none, as for an apply
@@ -2054,6 +2410,13 @@ function noteHooksAtBase(ctx: WaveContext, rules: OpWaveBaseRules): void {
2054
2410
  */
2055
2411
  export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveResult> {
2056
2412
  assertOpWavesSpec(options.spec);
2413
+ if (options.phase !== undefined) {
2414
+ // #4987: a split wave's plan and gate jobs are its deciding job, in two; the record job writes the applying jobs' records.
2415
+ const wrong = opWavePhaseProblem(options);
2416
+ if (wrong) throw new Error(`Op waves "${options.spec.name}": ${wrong}`);
2417
+ if (options.phase === "record") return runOpWaveRecordPhase(options);
2418
+ if (options.phase === "plan" || options.phase === "gate") options = { ...options, decide: true };
2419
+ }
2057
2420
  const afterPlanWrong = opWaveAfterPlanProblems(options.afterPlan);
2058
2421
  if (afterPlanWrong.length > 0) throw new Error(`Op waves "${options.spec.name}": ${afterPlanWrong.join("; ")}`);
2059
2422
  const runHooksWrong = opWaveRunHooksProblems(options.runHooks);
@@ -2208,7 +2571,7 @@ export function opWaveRunRecord(
2208
2571
  const wave: OpRunWave = {
2209
2572
  spec: spec.name,
2210
2573
  number: options.wave,
2211
- name: spec.waves[options.wave - 1]?.name ?? `wave-${options.wave}`,
2574
+ name: opWaveAt(spec, options.wave)?.name ?? `wave-${options.wave}`,
2212
2575
  job: options.decide ? "decide" : options.group !== undefined ? "group" : options.share !== undefined ? "share" : "wave",
2213
2576
  ...(options.share !== undefined ? { share: options.share } : {}),
2214
2577
  ...(options.group !== undefined ? { group: options.group } : {}),
@@ -2250,7 +2613,8 @@ export function opWaveRunRecord(
2250
2613
  */
2251
2614
  async function recordOpWaveRun(options: RunOpWaveOptions, started: string, outcome: { result: RunOpWaveResult } | { error: unknown }): Promise<OpRunRecordInput & { lost?: string }> {
2252
2615
  const cwd = options.cwd ?? process.cwd();
2253
- const port = options.runs ?? (options.gates ? undefined : gitOpWaveRunPort({ cwd }));
2616
+ // #4987: a split wave's plan job records nothing (its gate job records the decision), and an applying job leaves its record for the record job.
2617
+ const port = options.phase === "plan" ? undefined : options.phase === "apply" ? fileOpWaveRunPort(options, "result" in outcome ? outcome.result.handoff : undefined) : options.runs ?? (options.gates ? undefined : gitOpWaveRunPort({ cwd }));
2254
2618
  const log = options.log ?? ((line: string) => console.error(line));
2255
2619
  let gitSha = options.head;
2256
2620
  if (gitSha === undefined) {
@@ -2301,6 +2665,8 @@ async function runOpWaveJob(options: RunOpWaveOptions): Promise<RunOpWaveResult>
2301
2665
  const cwd = options.cwd ?? process.cwd();
2302
2666
  const outcomeDir = options.outcomeDir ?? opWaveOutcomeDir(spec);
2303
2667
  const dir = isAbsolute(outcomeDir) ? outcomeDir : join(cwd, outcomeDir);
2668
+ // #4987: the gate job of a split wave reads what the plan job saved, not the outcome files again.
2669
+ if (options.phase === "gate") return runOpWaveGatePhase(options, dir);
2304
2670
  // #4322: what the earlier jobs' outcome files say: an earlier wave that stopped stops this one, and a failure blocks its dependents.
2305
2671
  const before = opWaveBefore(options, dir);
2306
2672
  const blocked = before.blocked;
@@ -2308,6 +2674,7 @@ async function runOpWaveJob(options: RunOpWaveOptions): Promise<RunOpWaveResult>
2308
2674
  log(before.stop.line);
2309
2675
  const stopped: RunOpWaveResult = { exitCode: before.stop.exitCode, applied: [], failed: [], moved: [], hooks: [], ...(blocked.size > 0 ? { blocked: Object.fromEntries(blocked) } : {}) };
2310
2676
  writeOpWaveOutcome(options, dir, stopped, before.stop.members);
2677
+ if (options.phase === "plan") saveOpWavePlan(options, { end: stopped });
2311
2678
  return stopped;
2312
2679
  }
2313
2680
  if (blocked.size > 0) log(`wave ${options.wave}: ${blockedWords(blocked)}, so not planned or applied`);
@@ -2316,8 +2683,10 @@ async function runOpWaveJob(options: RunOpWaveOptions): Promise<RunOpWaveResult>
2316
2683
  // Every run of this job is blocked: nothing to plan, decide or apply.
2317
2684
  const none: RunOpWaveResult = { exitCode: options.decide ? 0 : 1, applied: [], failed: [], moved: [], hooks: [], blocked: Object.fromEntries(blocked) };
2318
2685
  writeOpWaveOutcome(options, dir, none);
2686
+ if (options.phase === "plan") saveOpWavePlan(options, { end: none });
2319
2687
  return none;
2320
2688
  }
2689
+ if (options.phase === "plan") return runOpWavePlanPhase(options, dir, blocked);
2321
2690
  let result: RunOpWaveResult;
2322
2691
  const applied: string[] = [];
2323
2692
  try {
@@ -2326,6 +2695,12 @@ async function runOpWaveJob(options: RunOpWaveOptions): Promise<RunOpWaveResult>
2326
2695
  writeOpWaveOutcome(options, dir, { exitCode: 1, applied, failed: [], moved: [], hooks: [], ...(blocked.size > 0 ? { blocked: Object.fromEntries(blocked) } : {}) });
2327
2696
  throw err;
2328
2697
  }
2698
+ if (options.phase === "apply" && result.replan) {
2699
+ // #4987: the plan job plans; an applying job that would plan again stops, and the wave runs again from its plan job.
2700
+ log(`wave ${options.wave}: the apply applied nothing and asks to plan again${result.replan.reason ? ` (${result.replan.reason})` : ""}; before merge the plan job plans, so run the wave again`);
2701
+ delete result.replan;
2702
+ result.exitCode = CHANT_EXIT.failed;
2703
+ }
2329
2704
  const all = { ...Object.fromEntries(blocked), ...(result.blocked ?? {}) };
2330
2705
  if (Object.keys(all).length > 0) {
2331
2706
  result.blocked = all;
@@ -2374,6 +2749,421 @@ async function runOpWavePolicyOnly(options: RunOpWaveOptions): Promise<RunOpWave
2374
2749
  return end(CHANT_EXIT.done, rows, `wave ${options.wave} (${wave.name}): ci.policy ran over its ${rows.length} plans and denied none`);
2375
2750
  }
2376
2751
 
2752
+ /**
2753
+ * What a split wave's plan job saves for its gate and applying jobs
2754
+ * (#4987), at {@link opWaveSavedPlanPath} beside the run plan files: the
2755
+ * plans and their set digest, what the holds and hooks said of them, and
2756
+ * the runs a failure blocked. `end` instead: the plan job ended the wave,
2757
+ * with that result, and the gate job records it.
2758
+ */
2759
+ export interface OpWaveSavedPlan {
2760
+ version: 1;
2761
+ op: string;
2762
+ wave: number;
2763
+ name: string;
2764
+ end?: RunOpWaveResult;
2765
+ digest?: string;
2766
+ members?: OpWaveMember[];
2767
+ extras?: WaveMember[];
2768
+ pending?: Record<string, unknown>;
2769
+ overriders?: string[];
2770
+ overridersSource?: string;
2771
+ changeSet?: ChangeSetDocument;
2772
+ /** The holds of the rules at base, the wave's holds and the in-process after-plan hooks. */
2773
+ holds?: string[];
2774
+ /** The holds of the before-plan hooks. */
2775
+ before?: string[];
2776
+ blocked?: Record<string, string>;
2777
+ report?: string;
2778
+ answerApprovals?: OpWaveAnswerApproval[];
2779
+ ciPolicySource?: ResolvedGatePolicySource;
2780
+ discovered?: { waves?: number };
2781
+ hooks?: OpWaveHookOutcome[];
2782
+ plans?: Record<string, OpRunWavePlan>;
2783
+ /**
2784
+ * With a `step` (#4992): each run's plan through it, without the engine's
2785
+ * artifact, its change-set part or the wave's group plan. The gate job
2786
+ * leases the rows these name; the applying job plans its runs again
2787
+ * through the step and applies each whose plan digest the decision holds.
2788
+ */
2789
+ steps?: OpWaveSavedStep[];
2790
+ /**
2791
+ * The held hooks the plan job ran again under an approval an earlier gate
2792
+ * job spent for them (#4994), and how each ended: the gate job writes
2793
+ * their finished lines, whatever else the plan job came to.
2794
+ */
2795
+ holdsFinished?: OpWaveHandedFinished[];
2796
+ }
2797
+
2798
+ /** A run's step plan as a split wave's plan job saves it (#4992). */
2799
+ export type OpWaveSavedStep = Omit<OpWaveStepPlan, "artifact" | "part" | "group">;
2800
+
2801
+ /**
2802
+ * What a split wave's applying job hands its record job beside its run
2803
+ * record (#4992): the release records of the runs it applied through the
2804
+ * step, and a hold on another gate its hooks found waiting, which the
2805
+ * record job writes with the token.
2806
+ */
2807
+ export interface OpWaveSplitHandoff {
2808
+ releases?: OpWaveReleaseRequest[];
2809
+ heldOn?: OpWaveHeldOn;
2810
+ }
2811
+
2812
+ /** The lease a split wave's gate job takes for the wave's rows (#4992), which its record job lets go of. */
2813
+ export interface OpWaveSplitLease {
2814
+ gate: string;
2815
+ /** The holder the rows name: the forge's run, the same in every job of it. */
2816
+ run: string;
2817
+ keys: string[];
2818
+ }
2819
+
2820
+ /** Why `options` cannot run its phase (#4987), or undefined. */
2821
+ function opWavePhaseProblem(options: RunOpWaveOptions): string | undefined {
2822
+ const { phase } = options;
2823
+ if (!OP_WAVE_PHASES.includes(phase!)) return `the phase is one of ${OP_WAVE_PHASES.join(", ")}, not ${JSON.stringify(phase)}`;
2824
+ if (options.decide) return "a phase takes the deciding job's place; pass --decide or --phase, not both";
2825
+ if (options.policyOnly && phase !== "plan") return "--policy-only runs in a split wave's plan job alone";
2826
+ if ((options.share !== undefined || options.group !== undefined) && phase !== "apply") return `--${options.share !== undefined ? "share" : "group"} names an applying job; the ${phase} job covers the whole wave`;
2827
+ return undefined;
2828
+ }
2829
+
2830
+ /** Write the plan job's saved plan (#4987). */
2831
+ function saveOpWavePlan(options: RunOpWaveOptions, plan: Omit<OpWaveSavedPlan, "version" | "op" | "wave" | "name">): void {
2832
+ const path = join(options.cwd ?? process.cwd(), opWaveSavedPlanPath(options.spec, options.wave));
2833
+ mkdirSync(dirname(path), { recursive: true });
2834
+ const name = opWaveAt(options.spec, options.wave)?.name ?? `wave-${options.wave}`;
2835
+ // #4994: the re-runs under an approval an earlier gate job spent, whose finished lines the gate job writes.
2836
+ const finished = handedFinished.get(options);
2837
+ const saved: OpWaveSavedPlan = { version: 1, op: options.spec.name, wave: options.wave, name, ...plan, ...(finished?.length ? { holdsFinished: finished } : {}) };
2838
+ writeFileSync(path, JSON.stringify(saved, null, 2) + "\n");
2839
+ }
2840
+
2841
+ /** Read the saved plan the gate job decides on (#4987); throws when the plan job left none. */
2842
+ function readSavedOpWavePlan(options: RunOpWaveOptions): OpWaveSavedPlan {
2843
+ const { spec, wave: k } = options;
2844
+ const rel = opWaveSavedPlanPath(spec, k);
2845
+ let doc: Partial<OpWaveSavedPlan> | null;
2846
+ try {
2847
+ doc = JSON.parse(readFileSync(join(options.cwd ?? process.cwd(), rel), "utf-8")) as Partial<OpWaveSavedPlan> | null;
2848
+ } catch {
2849
+ throw new Error(`wave ${k} found no saved plan at ${rel}: its plan job did not finish, so nothing is decided`);
2850
+ }
2851
+ if (doc?.version !== 1 || doc.op !== spec.name || doc.wave !== k) throw new Error(`${rel} is not the saved plan of wave ${k} of ${spec.name}`);
2852
+ if (doc.end === undefined && (!Array.isArray(doc.members) || typeof doc.digest !== "string")) throw new Error(`${rel} holds neither the plans of wave ${k} nor how its plan job ended`);
2853
+ return doc as OpWaveSavedPlan;
2854
+ }
2855
+
2856
+ /**
2857
+ * The plan job of a split wave (#4987): plan the wave as its deciding job
2858
+ * would, then save the plan for the gate job and stop. It writes nothing to
2859
+ * `chant/lifecycle` and keeps no run record. A wave its plan ends (a hook
2860
+ * failed, a plan failed, the rules at base refuse it) writes its outcome
2861
+ * here, and the saved plan says how it ended.
2862
+ */
2863
+ async function runOpWavePlanPhase(options: RunOpWaveOptions, dir: string, blocked: ReadonlyMap<string, string>): Promise<RunOpWaveResult> {
2864
+ const { spec, wave: k } = options;
2865
+ const log = options.log ?? ((line: string) => console.error(line));
2866
+ const ended = (r: RunOpWaveResult): RunOpWaveResult => {
2867
+ const all = { ...Object.fromEntries(blocked), ...(r.blocked ?? {}) };
2868
+ if (Object.keys(all).length > 0) r.blocked = all;
2869
+ writeOpWaveOutcome(options, dir, r);
2870
+ saveOpWavePlan(options, { end: r });
2871
+ return r;
2872
+ };
2873
+ let step: WaveStep<OpWavePlanned, RunOpWaveResult>;
2874
+ try {
2875
+ step = await planOpWave(options, { k, pass: 0 }, blocked);
2876
+ } catch (err) {
2877
+ ended({ exitCode: CHANT_EXIT.failed, applied: [], failed: [], moved: [], hooks: [] });
2878
+ throw err;
2879
+ }
2880
+ if ("end" in step) return ended(step.end);
2881
+ const p = step.go;
2882
+ if (p.kind !== "decide") throw new Error(`wave ${k}'s plan job planned as a share; it plans the whole wave`);
2883
+ const digest = opWaveSetDigest(spec, p.members, p.extras);
2884
+ saveOpWavePlan(options, {
2885
+ digest,
2886
+ members: p.members,
2887
+ ...(p.extras ? { extras: p.extras } : {}),
2888
+ ...(p.pending ? { pending: p.pending } : {}),
2889
+ ...(p.overriders ? { overriders: p.overriders } : {}),
2890
+ ...(p.overridersSource ? { overridersSource: p.overridersSource } : {}),
2891
+ ...(p.changeSet ? { changeSet: p.changeSet } : {}),
2892
+ holds: p.holds,
2893
+ before: p.before,
2894
+ ...(blocked.size > 0 ? { blocked: Object.fromEntries(blocked) } : {}),
2895
+ ...(p.ctx.report !== undefined ? { report: p.ctx.report } : {}),
2896
+ ...(p.ctx.answerApprovals?.length ? { answerApprovals: p.ctx.answerApprovals } : {}),
2897
+ ...(p.decision.ciPolicySource ? { ciPolicySource: p.decision.ciPolicySource } : {}),
2898
+ ...(p.decision.discovered ? { discovered: p.decision.discovered } : {}),
2899
+ ...(p.ctx.result.hooks.length > 0 ? { hooks: p.ctx.result.hooks } : {}),
2900
+ ...(p.ctx.result.plans ? { plans: p.ctx.result.plans } : {}),
2901
+ // #4992: the step plans, for the gate job's lease.
2902
+ ...(p.ctx.steps?.size ? { steps: [...p.ctx.steps.values()].map(({ artifact: _a, part: _p, group: _g, ...s }) => s) } : {}),
2903
+ });
2904
+ log(`wave ${k} (${p.ctx.wave.name}): planned ${p.members.length} run${p.members.length === 1 ? "" : "s"} to digest ${digest}; the plan is saved at ${opWaveSavedPlanPath(spec, k)} for the gate job`);
2905
+ return { exitCode: CHANT_EXIT.done, applied: [], failed: [], moved: [], hooks: [...p.ctx.result.hooks], ...(blocked.size > 0 ? { blocked: Object.fromEntries(blocked) } : {}) };
2906
+ }
2907
+
2908
+ /** The runs whose plan file no longer gives the digest the saved plan names (#4987). */
2909
+ function savedPlansMoved(ctx: WaveContext, members: readonly OpWaveMember[]): string[] {
2910
+ return members.filter((m) => readPlanFileField(join(ctx.cwd, opWavePlanPath(ctx.spec, ctx.k, m.member)), "planDigest") !== m.planDigest).map((m) => m.member);
2911
+ }
2912
+
2913
+ /** An applying job's plans of `runs` (#4987), read from the plan files its plan job saved. */
2914
+ function savedRunPlans(ctx: WaveContext, runs: readonly OpWaveRun[]): { planned: Map<string, OpWaveMember> } | { failed: string } {
2915
+ const planned = new Map<string, OpWaveMember>();
2916
+ for (const run of runs) {
2917
+ const path = opWavePlanPath(ctx.spec, ctx.k, run.target);
2918
+ try {
2919
+ const file = JSON.parse(readFileSync(join(ctx.cwd, path), "utf-8")) as OpWavePlanFile;
2920
+ if (typeof file.planDigest !== "string" || file.planDigest === "") throw new Error("it has no planDigest");
2921
+ planned.set(run.target, member(run.target, run.op ?? ctx.spec.op, file));
2922
+ } catch (err) {
2923
+ return { failed: `${shareLabel(ctx.options)} of wave ${ctx.k} (${ctx.wave.name}) found no saved plan of ${run.target} at ${path} (${err instanceof Error ? err.message : String(err)}), so nothing in it was applied` };
2924
+ }
2925
+ }
2926
+ return { planned };
2927
+ }
2928
+
2929
+ /**
2930
+ * The gate job of a split wave (#4987), at the default branch's code with
2931
+ * the token: read the rules at base, take the plan its plan job saved,
2932
+ * refuse it (exit 4) when its set digest is not the one its plan files
2933
+ * give, then decide the gate on it as a wide wave's deciding job does:
2934
+ * write the pending fact, spend the approval and the overrides, keep the
2935
+ * decision record and the outcome. A wave its plan job ended is not
2936
+ * decided again; that end is this job's result, which its run record keeps.
2937
+ */
2938
+ async function runOpWaveGatePhase(options: RunOpWaveOptions, dir: string): Promise<RunOpWaveResult> {
2939
+ const { spec, wave: k } = options;
2940
+ const cwd = options.cwd ?? process.cwd();
2941
+ const log = options.log ?? ((line: string) => console.error(line));
2942
+ const saved = readSavedOpWavePlan(options);
2943
+ // #4994: the plan job ran a held hook again under an approval an earlier gate job spent; this job writes how it ended.
2944
+ await writeHandedFinished(options, cwd, saved.holdsFinished, log);
2945
+ // #4992: a follow-on run's wave past the spec's is the rest wave's.
2946
+ const at = opWaveAt(spec, k);
2947
+ // #4992: a hook in the plan job held the wave on another gate it could not record; this job records it.
2948
+ const heldOn = saved.end?.exitCode === CHANT_EXIT.waiting ? saved.end.decision?.heldOn : undefined;
2949
+ if (saved.end && !(heldOn?.deferred && at)) {
2950
+ log(`wave ${k}: its plan job ended the wave with exit ${saved.end.exitCode}, so there is nothing to decide`);
2951
+ return saved.end;
2952
+ }
2953
+ if (!at) throw new Error(`Op waves "${spec.name}" has ${spec.waves.length} waves; there is no wave ${k}.`);
2954
+ const members = saved.members ?? [];
2955
+ // The runs the plan job planned, which a discovering wave found and the spec at the default branch may not list.
2956
+ const wave: OpWave = saved.end ? at : { ...at, runs: members.map((m) => ({ target: m.member, ...(m.op !== spec.op ? { op: m.op } : {}) })) };
2957
+ const blocked = saved.blocked ?? {};
2958
+ const result: RunOpWaveResult = { exitCode: 0, applied: [], failed: [], moved: [], hooks: [...(saved.end?.hooks ?? saved.hooks ?? [])], ...(saved.plans ? { plans: saved.plans } : {}) };
2959
+ const ctx: WaveContext = { spec, k, wave, cwd, exec: options.exec ?? spawnExec, log, result, options, gateRule: { approval: "ledger", base: "HEAD", neverOverMcp: spec.neverOverMcp === true } };
2960
+ // #4992: the rows a step's runs lease, as the plan job planned them.
2961
+ if (saved.steps?.length) ctx.steps = new Map(saved.steps.map((s) => [s.target, s]));
2962
+ const end = (r: RunOpWaveResult): RunOpWaveResult => {
2963
+ if (Object.keys(blocked).length > 0) r.blocked = { ...blocked, ...(r.blocked ?? {}) };
2964
+ writeOpWaveOutcome(options, dir, r);
2965
+ return r;
2966
+ };
2967
+ if (heldOn?.deferred) {
2968
+ // The decision is this job's own, from the rules at base: of the plan job's end it takes only the hold.
2969
+ const opened = await openWaveDecision(options, ctx, { evidence: false });
2970
+ if ("end" in opened) return end(opened.end);
2971
+ // #4994: an approved `record` hold, whose approval this job spends for the hook's re-run in the next run's plan job.
2972
+ if (heldOn.deferred.spend) {
2973
+ const spent = await spendDeferredHold(options, ctx, heldOn, log);
2974
+ if ("failed" in spent) return end(failed(ctx, `wave ${k} (${at.name}): ${spent.failed}`));
2975
+ return end(await decided(ctx, opened.go.decision, join(cwd, opWaveRecordPath(spec, k)), spent.heldOn));
2976
+ }
2977
+ const recorded = await recordDeferredHold(options, cwd, heldOn, ctx.gateRule, log);
2978
+ return end(await decided(ctx, opened.go.decision, join(cwd, opWaveRecordPath(spec, k)), recorded));
2979
+ }
2980
+ const opened = await openWaveDecision(options, ctx, { evidence: true });
2981
+ if ("end" in opened) return end(opened.end);
2982
+ const { rules, holds, decision } = opened.go;
2983
+ const digest = opWaveSetDigest(spec, members, saved.extras);
2984
+ const moved = savedPlansMoved(ctx, members);
2985
+ if (digest !== saved.digest || moved.length > 0) {
2986
+ log(
2987
+ `wave ${k} (${wave.name}): ` +
2988
+ (moved.length > 0 ? `the saved plan names plans its plan files do not hold (${moved.join(", ")})` : `the saved plan says digest ${saved.digest}, and its plans give ${digest}`) +
2989
+ ", so nothing is decided or applied; run the wave again",
2990
+ );
2991
+ return end({ ...result, exitCode: CHANT_EXIT.moved, moved: moved.length > 0 ? moved : members.map((m) => m.member) });
2992
+ }
2993
+ if (saved.discovered) decision.discovered = saved.discovered;
2994
+ if (saved.ciPolicySource) decision.ciPolicySource = saved.ciPolicySource;
2995
+ if (saved.report !== undefined) ctx.report = saved.report;
2996
+ if (saved.answerApprovals?.length) ctx.answerApprovals = saved.answerApprovals;
2997
+ const planned: Extract<OpWavePlanned, { kind: "decide" }> = {
2998
+ kind: "decide",
2999
+ ctx,
3000
+ recordPath: join(cwd, opWaveRecordPath(spec, k)),
3001
+ rules,
3002
+ decision,
3003
+ holds: [...new Set([...holds, ...(saved.holds ?? [])])],
3004
+ before: saved.before ?? [],
3005
+ members,
3006
+ planned: new Map(members.map((m) => [m.member, m])),
3007
+ ...(saved.pending ? { pending: saved.pending } : {}),
3008
+ ...(saved.overriders ? { overriders: saved.overriders } : {}),
3009
+ ...(saved.overridersSource ? { overridersSource: saved.overridersSource } : {}),
3010
+ ...(saved.extras ? { extras: saved.extras } : {}),
3011
+ ...(saved.changeSet ? { changeSet: saved.changeSet } : {}),
3012
+ };
3013
+ const step = await decideOpWave(options, { k, pass: 0 }, planned, digest);
3014
+ return end("end" in step ? step.end : result);
3015
+ }
3016
+
3017
+ /**
3018
+ * An applying job's run record port (#4987): a file in the outcome
3019
+ * directory, for the record job, in place of the ledger. #4992: with what
3020
+ * the job hands its record job under `handoff`, which the record job takes
3021
+ * off before it writes the record.
3022
+ */
3023
+ function fileOpWaveRunPort(options: RunOpWaveOptions, handoff?: OpWaveSplitHandoff): OpWaveRunPort {
3024
+ const cwd = options.cwd ?? process.cwd();
3025
+ const outcomeDir = options.outcomeDir ?? opWaveOutcomeDir(options.spec);
3026
+ const dir = isAbsolute(outcomeDir) ? outcomeDir : join(cwd, outcomeDir);
3027
+ const part = { ...(options.group !== undefined ? { group: options.group } : {}), ...(options.share !== undefined ? { share: options.share } : {}) };
3028
+ return {
3029
+ async append(record) {
3030
+ mkdirSync(dir, { recursive: true });
3031
+ const file: OpWaveRunRecordFile = { ...record, ...(handoff && (handoff.releases?.length || handoff.heldOn) ? { handoff } : {}) };
3032
+ writeFileSync(join(dir, opWaveRunRecordFileName(options.wave, part)), JSON.stringify(file, null, 2) + "\n");
3033
+ },
3034
+ };
3035
+ }
3036
+
3037
+ /** A run record file an applying job leaves (#4987), with its hand-off to the record job (#4992). */
3038
+ type OpWaveRunRecordFile = OpRunRecordInput & { handoff?: OpWaveSplitHandoff };
3039
+
3040
+ /** The run records wave `k`'s applying jobs left under `dir` (#4987), at any depth up to four, the newest of each name, by name. */
3041
+ function waveRunRecordFiles(dir: string, k: number, log: (line: string) => void): Array<{ name: string; record: OpWaveRunRecordFile }> {
3042
+ const newest = new Map<string, OpWaveRunRecordFile>();
3043
+ const walk = (at: string, depth: number): void => {
3044
+ let names: string[];
3045
+ try {
3046
+ names = readdirSync(at);
3047
+ } catch {
3048
+ return;
3049
+ }
3050
+ for (const name of names) {
3051
+ const abs = join(at, name);
3052
+ let isDir = false;
3053
+ try {
3054
+ isDir = statSync(abs).isDirectory();
3055
+ } catch {
3056
+ continue;
3057
+ }
3058
+ if (isDir) {
3059
+ if (depth < 4) walk(abs, depth + 1);
3060
+ continue;
3061
+ }
3062
+ if (OP_WAVE_RUN_RECORD_FILE.exec(name)?.[1] !== String(k)) continue;
3063
+ let record: OpWaveRunRecordFile;
3064
+ try {
3065
+ record = JSON.parse(readFileSync(abs, "utf-8")) as OpWaveRunRecordFile;
3066
+ } catch (err) {
3067
+ log(`wave ${k}: the run record ${abs} does not parse, so it is not written: ${err instanceof Error ? err.message : String(err)}`);
3068
+ continue;
3069
+ }
3070
+ const had = newest.get(name);
3071
+ if (!had || had.ended <= record.ended) newest.set(name, record);
3072
+ }
3073
+ };
3074
+ walk(dir, 0);
3075
+ return [...newest].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([name, record]) => ({ name, record }));
3076
+ }
3077
+
3078
+ /**
3079
+ * The record job of a split wave (#4987), at the default branch's code with
3080
+ * the token: write each run record the wave's applying jobs left to the run
3081
+ * ledger, and end as they did: 0 when each applied, else the first exit that
3082
+ * was not a failed run (a moved plan, a held or stood-down apply), else 1.
3083
+ * A record whose push never landed fails the job, as it fails a wave job.
3084
+ *
3085
+ * #4992: it also writes what the applying jobs handed it: the release
3086
+ * records of the runs they applied through the step, and the pending fact
3087
+ * of another gate a hook held the wave on (the wave then waits, exit 3).
3088
+ * Last it lets go of the rows the gate job leased, which the decision names.
3089
+ */
3090
+ async function runOpWaveRecordPhase(options: RunOpWaveOptions): Promise<RunOpWaveResult> {
3091
+ const { spec, wave: k } = options;
3092
+ const cwd = options.cwd ?? process.cwd();
3093
+ const log = options.log ?? ((line: string) => console.error(line));
3094
+ const outcomeDir = options.outcomeDir ?? opWaveOutcomeDir(spec);
3095
+ const dir = isAbsolute(outcomeDir) ? outcomeDir : join(cwd, outcomeDir);
3096
+ const result: RunOpWaveResult = { exitCode: CHANT_EXIT.done, applied: [], failed: [], moved: [], hooks: [] };
3097
+ // The gate job's decision: the lease it took, and the rules a hold on another gate is recorded under.
3098
+ let decision: OpWaveDecision | undefined;
3099
+ try {
3100
+ decision = JSON.parse(readFileSync(join(cwd, opWaveRecordPath(spec, k)), "utf-8")) as OpWaveDecision;
3101
+ } catch {
3102
+ decision = undefined;
3103
+ }
3104
+ try {
3105
+ return await writeOpWaveRecords(options, { cwd, dir, log, result, decision });
3106
+ } finally {
3107
+ if (decision?.lease?.keys.length) await releaseSplitLease(cwd, decision.lease, k, log);
3108
+ }
3109
+ }
3110
+
3111
+ /** {@link runOpWaveRecordPhase}'s writes, before it lets go of the lease. */
3112
+ async function writeOpWaveRecords(
3113
+ options: RunOpWaveOptions,
3114
+ at: { cwd: string; dir: string; log: (line: string) => void; result: RunOpWaveResult; decision?: OpWaveDecision },
3115
+ ): Promise<RunOpWaveResult> {
3116
+ const { wave: k } = options;
3117
+ const { cwd, dir, log, result, decision } = at;
3118
+ const records = waveRunRecordFiles(dir, k, log);
3119
+ if (records.length === 0) {
3120
+ log(`wave ${k}: no applying job of it left a run record under ${relativeTo(cwd, dir)}, so there is none to write`);
3121
+ return { ...result, exitCode: CHANT_EXIT.failed };
3122
+ }
3123
+ const port = options.runs ?? (options.gates ? undefined : gitOpWaveRunPort({ cwd }));
3124
+ const codes: number[] = [];
3125
+ const releases: OpWaveReleaseRequest[] = [];
3126
+ const holds: OpWaveHeldOn[] = [];
3127
+ let lost = false;
3128
+ for (const { name, record: file } of records) {
3129
+ const { handoff, ...record } = file;
3130
+ releases.push(...(handoff?.releases ?? []));
3131
+ if (handoff?.heldOn?.deferred) holds.push(handoff.heldOn);
3132
+ const w = record.wave;
3133
+ codes.push(w?.exitCode ?? CHANT_EXIT.failed);
3134
+ result.applied.push(...(w?.applied ?? []));
3135
+ result.failed.push(...(w?.failed ?? []));
3136
+ result.moved.push(...(w?.moved ?? []));
3137
+ if (w?.blocked) result.blocked = { ...result.blocked, ...w.blocked };
3138
+ if (!port) continue;
3139
+ try {
3140
+ const wrote = await port.append(record);
3141
+ if (wrote && wrote.pushWarning) log(`wave ${k}: the run record ${name} was written and not pushed: ${wrote.pushWarning}`);
3142
+ } catch (err) {
3143
+ const message = err instanceof Error ? err.message : String(err);
3144
+ const never = err instanceof LifecyclePushLostError;
3145
+ if (never) lost = true;
3146
+ log(`wave ${k}: ${never ? `LifecyclePushLostError: the run record ${name} never reached the remote, so the job fails` : `could not record ${name} on the run ledger`}: ${message}`);
3147
+ }
3148
+ }
3149
+ // #4992: the release records of the runs the applying jobs applied through the step.
3150
+ const releasePort = options.releases === false ? undefined : (options.releases ?? (options.gates ? undefined : gitOpWaveReleasePort({ cwd })));
3151
+ if (releasePort && releases.length > 0) {
3152
+ const missed = await submitStepReleases(releasePort, releases, `wave ${k}`, log);
3153
+ for (const line of missed) log(line);
3154
+ if (missed.length > 0) lost = true;
3155
+ }
3156
+ // #4992: a hold on another gate an applying job's hook found waiting, recorded under the gate job's rules.
3157
+ for (const held of holds) {
3158
+ const rule = { approval: decision?.approval ?? "ledger", base: decision?.base ?? options.base ?? "HEAD", neverOverMcp: decision?.neverOverMcp === true || options.spec.neverOverMcp === true };
3159
+ await recordDeferredHold(options, cwd, held, rule, log);
3160
+ }
3161
+ result.exitCode = codes.every((c) => c === CHANT_EXIT.done) ? CHANT_EXIT.done : (codes.find((c) => c !== CHANT_EXIT.done && c !== CHANT_EXIT.failed) ?? CHANT_EXIT.failed);
3162
+ if (lost && result.exitCode === CHANT_EXIT.done) result.exitCode = CHANT_EXIT.failed;
3163
+ log(`wave ${k}: wrote the run record${records.length === 1 ? "" : "s"} of ${records.length} applying job${records.length === 1 ? "" : "s"}; the wave ends with exit ${result.exitCode}`);
3164
+ return result;
3165
+ }
3166
+
2377
3167
  /** The wave engine's loop over this module's steps, from `options.wave` on, with the runs in `skip` left out of that wave. */
2378
3168
  async function runOpWaveLoop(options: RunOpWaveOptions, log: (line: string) => void, applied: string[], skip: ReadonlyMap<string, string>): Promise<RunOpWaveResult> {
2379
3169
  const { spec } = options;
@@ -2388,7 +3178,8 @@ async function runOpWaveLoop(options: RunOpWaveOptions, log: (line: string) => v
2388
3178
  digest: (_at, planned) => (planned.kind === "share" ? planned.decision.digest : opWaveSetDigest(spec, planned.members, planned.extras)),
2389
3179
  decide: (at, planned, digest) => (planned.kind === "share" ? shareUnmoved(planned) : decideOpWave(options, at, planned, digest)),
2390
3180
  apply: (_at, planned, decided) => applyOpWave(options, planned, decided),
2391
- replan: (_at, outcome) => outcome.replan !== undefined,
3181
+ // #4987: an applying job of a split wave has no plan of its own to make again.
3182
+ replan: (_at, outcome) => outcome.replan !== undefined && options.phase !== "apply",
2392
3183
  maxPasses: OP_WAVE_MAX_REPLANS,
2393
3184
  passesSpent({ k }, outcome) {
2394
3185
  log(`wave ${k}: its apply asked to plan again ${OP_WAVE_MAX_REPLANS} times, so the wave stops here`);
@@ -2403,7 +3194,7 @@ async function runOpWaveLoop(options: RunOpWaveOptions, log: (line: string) => v
2403
3194
  Object.assign(targets, outcome.targets ?? {});
2404
3195
  // #3821: a `rest` wave goes on through the waves its plan command found.
2405
3196
  const found = outcome.decision?.discovered?.waves;
2406
- const onward = k >= spec.waves.length && last.rest === true && options.share === undefined && options.group === undefined && !options.decide && outcome.exitCode === 0 && found !== undefined && k < found;
3197
+ const onward = k >= spec.waves.length && last.rest === true && options.share === undefined && options.group === undefined && !options.decide && options.phase === undefined && outcome.exitCode === 0 && found !== undefined && k < found;
2407
3198
  if (rest.length > 0 || onward) rest.push({ wave: k, exitCode: outcome.exitCode, ...(outcome.decision ? { digest: outcome.decision.digest } : {}) });
2408
3199
  if (onward) log(`wave ${k} applied; the plan found ${found} waves, so this job goes on to wave ${k + 1}`);
2409
3200
  return onward;
@@ -2436,9 +3227,10 @@ interface OpWaveBefore {
2436
3227
  */
2437
3228
  function opWaveBefore(options: RunOpWaveOptions, dir: string): OpWaveBefore {
2438
3229
  const { spec, wave: k } = options;
2439
- const wave = spec.waves[k - 1];
3230
+ const wave = opWaveAt(spec, k);
2440
3231
  if (!wave) return { blocked: new Map() };
2441
- if (options.share !== undefined || options.group !== undefined) {
3232
+ // #4987: a split wave's applying job reads its gate job's outcome, as a share reads its deciding job's.
3233
+ if (options.share !== undefined || options.group !== undefined || options.phase === "apply") {
2442
3234
  const decided = readWaveOutcomeFile([dir], waveOutcomeFileName(k));
2443
3235
  if (!decided) return { blocked: new Map() };
2444
3236
  const blocked = new Map<string, string>();
@@ -2481,7 +3273,7 @@ function opWaveBefore(options: RunOpWaveOptions, dir: string): OpWaveBefore {
2481
3273
 
2482
3274
  /** The runs of wave `options.wave` this job holds (#4322): its slice for a share job, every run otherwise. Empty for a discovering wave. */
2483
3275
  function jobRuns(options: RunOpWaveOptions, runs?: readonly OpWaveRun[]): string[] {
2484
- const wave = options.spec.waves[options.wave - 1];
3276
+ const wave = opWaveAt(options.spec, options.wave);
2485
3277
  if (!wave) return [];
2486
3278
  const all = runs ?? (wave.discover ? [] : wave.runs);
2487
3279
  if (options.share === undefined && options.group === undefined) return all.map((r) => r.target);
@@ -2498,7 +3290,8 @@ function jobRuns(options: RunOpWaveOptions, runs?: readonly OpWaveRun[]): string
2498
3290
  function writeOpWaveOutcome(options: RunOpWaveOptions, dir: string, result: RunOpWaveResult, members?: Record<string, WaveMemberOutcome>): void {
2499
3291
  const out: Record<string, WaveMemberOutcome> = { ...(members ?? {}) };
2500
3292
  if (!members) {
2501
- const found = result.decision?.discovered !== undefined ? result.decision.members.map((m) => ({ target: m.member })) : undefined;
3293
+ // #4987: a split wave's gate job decides the runs its plan job planned, which the spec at the default branch may not list.
3294
+ const found = result.decision?.discovered !== undefined || (options.phase === "gate" && result.decision) ? result.decision.members.map((m) => ({ target: m.member })) : undefined;
2502
3295
  const targets = new Set([...jobRuns(options, found), ...result.applied, ...result.failed, ...result.moved, ...Object.keys(result.blocked ?? {})]);
2503
3296
  const applied = new Set(result.applied);
2504
3297
  const failed = new Set(result.failed);
@@ -2514,7 +3307,7 @@ function writeOpWaveOutcome(options: RunOpWaveOptions, dir: string, result: RunO
2514
3307
  out[t] = by !== undefined ? { status: "blocked", by } : applied.has(t) ? { status: "applied" } : failed.has(t) ? { status: "failed" } : moved.has(t) && result.decision?.refused?.reason !== "moved" ? { status: "not-applied" } : { status: otherwise };
2515
3308
  }
2516
3309
  }
2517
- const part = { ...(options.group !== undefined ? { group: options.group } : {}), ...(options.share !== undefined ? { share: options.share } : {}) };
3310
+ const part = { ...(options.group !== undefined ? { group: options.group } : {}), ...(options.share !== undefined ? { share: options.share } : {}), ...(options.phase === "apply" ? { apply: true } : {}) };
2518
3311
  try {
2519
3312
  mkdirSync(dir, { recursive: true });
2520
3313
  writeWaveOutcomeFile(dir, options.wave, part, out, options.now ?? new Date().toISOString());
@@ -2525,6 +3318,8 @@ function writeOpWaveOutcome(options: RunOpWaveOptions, dir: string, result: RunO
2525
3318
 
2526
3319
  /** What a share or job group's job calls itself in the log: `share 2`, `job group "prod"`, `share 2 of job group "prod"`. */
2527
3320
  function shareLabel(options: Pick<RunOpWaveOptions, "share" | "group">): string {
3321
+ // #4987: a split wave's own applying job is neither a share nor a group's.
3322
+ if (options.group === undefined && options.share === undefined) return "the applying job";
2528
3323
  if (options.group === undefined) return `share ${options.share}`;
2529
3324
  return `${options.share !== undefined ? `share ${options.share} of ` : ""}job group "${options.group}"`;
2530
3325
  }
@@ -2574,6 +3369,71 @@ interface OpWaveDecided {
2574
3369
  recordPath?: string;
2575
3370
  }
2576
3371
 
3372
+ /**
3373
+ * Read wave `k`'s rules at base and open its decision: the policy, the
3374
+ * approval mode, the hooks and the points, checked as the wave plans
3375
+ * (#3836, #4290, #4870), with the holds the rules give. Ends the wave when
3376
+ * the rules cannot be read or refuse it. The plan job and the gate job of a
3377
+ * split wave both read them (#4987); `evidence: false` leaves the evidence
3378
+ * the commit needs to the gate job.
3379
+ */
3380
+ async function openWaveDecision(
3381
+ options: RunOpWaveOptions,
3382
+ ctx: WaveContext,
3383
+ opts: { evidence: boolean },
3384
+ ): Promise<WaveStep<{ rules: OpWaveBaseRules; holds: string[]; decision: OpWaveDecision }, RunOpWaveResult>> {
3385
+ const { spec, k, wave, cwd, log } = ctx;
3386
+ const rules = readOpWavePolicy(options.specFile, wave.name, options.base ?? spec.base ?? "HEAD^1", cwd, options.show);
3387
+ const { policy, approval, source, base } = rules;
3388
+ const neverOverMcp = rules.neverOverMcp || spec.neverOverMcp === true;
3389
+ ctx.gateRule = { approval, base, neverOverMcp };
3390
+ noteHooksAtBase(ctx, rules);
3391
+ // #3836: a point at base that cannot be asked fails the wave; the ledger never stands in for it.
3392
+ if (rules.pointRefused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.pointRefused}, so nothing in it was planned or applied`) };
3393
+ // #4290: rules at base that cannot be read fail the wave; fewer approvers never stand in for them.
3394
+ if (rules.quorumRefused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.quorumRefused}, so nothing in it was planned or applied`) };
3395
+ if (rules.quorum && rules.point) return { end: failed(ctx, `wave ${k} (${wave.name}): approvals.quorum and a decision point are both set at ${base.slice(0, 12)}; a gate that asks a point takes its deciders from the point, so nothing in it was planned or applied`) };
3396
+ // #4870: the checks whose evidence the commit needs, read at base, before anything is planned.
3397
+ if (rules.evidenceRefused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.evidenceRefused}, so nothing in it was planned or applied`) };
3398
+ if (rules.evidenceRequires && opts.evidence) {
3399
+ const refused = await opWaveEvidenceRefusal(cwd, options.head ?? "HEAD", base, rules.evidenceRequires);
3400
+ if (refused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${refused}, so nothing in it was planned or applied`) };
3401
+ }
3402
+ if (JSON.stringify(spec.approvals?.quorum ?? null) !== JSON.stringify(rules.quorum ?? null)) {
3403
+ log(`wave ${k} (${wave.name}): its approval rules are read at ${base.slice(0, 12)}, and this change's differ; the ones at base hold`);
3404
+ }
3405
+ const own = opWavePointAt(spec, wave.name);
3406
+ if (JSON.stringify(own) !== JSON.stringify(rules.point)) {
3407
+ log(`wave ${k} (${wave.name}): its gate's decision point is read at ${base.slice(0, 12)} (${rules.point?.name ?? "none"}), and this change's differs (${own?.name ?? "none"}); the one at base holds`);
3408
+ }
3409
+ const holds: string[] = [];
3410
+ if (rules.hooksRefused) {
3411
+ holds.push(rules.hooksRefused);
3412
+ log(`wave ${k} (${wave.name}): ${rules.hooksRefused}, so none run and the wave waits for an approval`);
3413
+ }
3414
+ const hooks = Object.fromEntries(Object.entries(rules.hooks).filter(([, list]) => list.length > 0));
3415
+ const decision: OpWaveDecision = {
3416
+ wave: k,
3417
+ name: wave.name,
3418
+ op: spec.name,
3419
+ gate: opWaveGateName(spec, k),
3420
+ policy,
3421
+ approval,
3422
+ policySource: source,
3423
+ base,
3424
+ digest: "",
3425
+ members: [],
3426
+ status: "not-required",
3427
+ ...(Object.keys(hooks).length > 0 ? { hooks } : {}),
3428
+ ...(rules.spend ? { spend: "base" as const } : spec.approvals?.spend === true ? { spend: "change" as const } : {}),
3429
+ ...(rules.applyHooksRunBy === "apply" ? { applyHooksRunBy: "apply" as const } : {}),
3430
+ ...(spec.digest?.over === "changing" ? { digestOver: "changing" as const } : {}),
3431
+ ...(neverOverMcp ? { neverOverMcp: true as const } : {}),
3432
+ ...(rules.point ? { point: { ...rules.point } } : {}),
3433
+ };
3434
+ return { go: { rules, holds, decision } };
3435
+ }
3436
+
2577
3437
  /**
2578
3438
  * Plan wave `k`: read its rules at base and run the before-plan hooks
2579
3439
  * around planning its runs, or for a share job, read the deciding job's
@@ -2609,7 +3469,8 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
2609
3469
  const ctx: WaveContext = { spec, k, wave, cwd, exec, log, result, options, gateRule: { approval: "ledger", base: "HEAD", neverOverMcp: spec.neverOverMcp === true } };
2610
3470
  if (pass > 0) log(`wave ${k} (${wave.name}): plan ${pass + 1}`);
2611
3471
 
2612
- if (options.share !== undefined || group !== undefined) {
3472
+ // #4987: a split wave's applying job applies under its gate job's decision, as a share does.
3473
+ if (options.share !== undefined || group !== undefined || options.phase === "apply") {
2613
3474
  let decision: OpWaveDecision;
2614
3475
  try {
2615
3476
  decision = JSON.parse(readFileSync(recordPath, "utf-8")) as OpWaveDecision;
@@ -2636,6 +3497,21 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
2636
3497
  // #4322: the runs its deciding job blocked are neither planned nor applied here.
2637
3498
  const slice = whole.filter((r) => !skip?.has(r.target));
2638
3499
  if (slice.length === 0) return { end: result };
3500
+ // #4987: an applying job of a split wave plans nothing and runs no plan hooks (its plan and gate jobs did): it takes
3501
+ // the plan files the plan job saved, and shareUnmoved applies those whose digest the decision holds.
3502
+ if (options.phase === "apply" && spec.step) {
3503
+ // #4992: a step's plan lives in the process that made it (the engine's saved plan, the artifact it hands its
3504
+ // apply), so the applying job plans its runs again through the step, as a share does, and shareUnmoved applies
3505
+ // each whose plan digest the decision holds. Its hooks ran in the plan and gate jobs.
3506
+ ctx.steps = new Map();
3507
+ const { members } = await planWaveRuns(ctx, slice);
3508
+ return { go: { kind: "share", ctx, decision, slice, planned: new Map(members.map((m) => [m.member, m])), holds: [] } };
3509
+ }
3510
+ if (options.phase === "apply") {
3511
+ const saved = savedRunPlans(ctx, slice);
3512
+ if ("failed" in saved) return { end: failed(ctx, saved.failed) };
3513
+ return { go: { kind: "share", ctx, decision, slice, planned: saved.planned, holds: [] } };
3514
+ }
2639
3515
  const before = await runBeforePlanHooks(ctx, decision.hooks, slice);
2640
3516
  if (before.failed) return { end: failed(ctx, `a hook before the plan failed, so nothing in ${part} of wave ${k} was planned or applied`) };
2641
3517
  if (before.waitingOn) return { end: await waitOnOther(ctx, decision, before.waitingOn) };
@@ -2652,55 +3528,11 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
2652
3528
  }
2653
3529
 
2654
3530
  // The policy, the approval mode and the hooks, read at base before anything runs.
2655
- const rules = readOpWavePolicy(options.specFile, wave.name, options.base ?? spec.base ?? "HEAD^1", cwd, options.show);
2656
- const { policy, approval, source, base } = rules;
2657
- const neverOverMcp = rules.neverOverMcp || spec.neverOverMcp === true;
2658
- ctx.gateRule = { approval, base, neverOverMcp };
2659
- noteHooksAtBase(ctx, rules);
2660
- // #3836: a point at base that cannot be asked fails the wave; the ledger never stands in for it.
2661
- if (rules.pointRefused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.pointRefused}, so nothing in it was planned or applied`) };
2662
- // #4290: rules at base that cannot be read fail the wave; fewer approvers never stand in for them.
2663
- if (rules.quorumRefused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.quorumRefused}, so nothing in it was planned or applied`) };
2664
- if (rules.quorum && rules.point) return { end: failed(ctx, `wave ${k} (${wave.name}): approvals.quorum and a decision point are both set at ${base.slice(0, 12)}; a gate that asks a point takes its deciders from the point, so nothing in it was planned or applied`) };
2665
- // #4870: the checks whose evidence the commit needs, read at base, before anything is planned.
2666
- if (rules.evidenceRefused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.evidenceRefused}, so nothing in it was planned or applied`) };
2667
- if (rules.evidenceRequires) {
2668
- const refused = await opWaveEvidenceRefusal(cwd, options.head ?? "HEAD", base, rules.evidenceRequires);
2669
- if (refused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${refused}, so nothing in it was planned or applied`) };
2670
- }
2671
- if (JSON.stringify(spec.approvals?.quorum ?? null) !== JSON.stringify(rules.quorum ?? null)) {
2672
- log(`wave ${k} (${wave.name}): its approval rules are read at ${base.slice(0, 12)}, and this change's differ; the ones at base hold`);
2673
- }
2674
- const own = opWavePointAt(spec, wave.name);
2675
- if (JSON.stringify(own) !== JSON.stringify(rules.point)) {
2676
- log(`wave ${k} (${wave.name}): its gate's decision point is read at ${base.slice(0, 12)} (${rules.point?.name ?? "none"}), and this change's differs (${own?.name ?? "none"}); the one at base holds`);
2677
- }
2678
- const holds: string[] = [];
2679
- if (rules.hooksRefused) {
2680
- holds.push(rules.hooksRefused);
2681
- log(`wave ${k} (${wave.name}): ${rules.hooksRefused}, so none run and the wave waits for an approval`);
2682
- }
2683
- const gate = opWaveGateName(spec, k);
2684
- const hooks = Object.fromEntries(Object.entries(rules.hooks).filter(([, list]) => list.length > 0));
2685
- const decision: OpWaveDecision = {
2686
- wave: k,
2687
- name: wave.name,
2688
- op: spec.name,
2689
- gate,
2690
- policy,
2691
- approval,
2692
- policySource: source,
2693
- base,
2694
- digest: "",
2695
- members: [],
2696
- status: "not-required",
2697
- ...(Object.keys(hooks).length > 0 ? { hooks } : {}),
2698
- ...(rules.spend ? { spend: "base" as const } : spec.approvals?.spend === true ? { spend: "change" as const } : {}),
2699
- ...(rules.applyHooksRunBy === "apply" ? { applyHooksRunBy: "apply" as const } : {}),
2700
- ...(spec.digest?.over === "changing" ? { digestOver: "changing" as const } : {}),
2701
- ...(neverOverMcp ? { neverOverMcp: true as const } : {}),
2702
- ...(rules.point ? { point: { ...rules.point } } : {}),
2703
- };
3531
+ // #4987: a split wave's plan job leaves the evidence its commit needs to the gate job, which can fetch the notes.
3532
+ const opened = await openWaveDecision(options, ctx, { evidence: options.phase !== "plan" });
3533
+ if ("end" in opened) return opened;
3534
+ const { rules, holds, decision } = opened.go;
3535
+ const { base } = rules;
2704
3536
  if (skip?.size && !wave.discover) {
2705
3537
  // #4322: a run a failure blocked is neither planned nor in the set digest.
2706
3538
  wave = { ...wave, runs: wave.runs.filter((r) => !skip.has(r.target)) };
@@ -2710,6 +3542,11 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
2710
3542
  if (before.failed) return { end: failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`) };
2711
3543
  // #4926: the policy step records no decision; the wave's own step does.
2712
3544
  if (before.waitingOn && options.policyOnly) return { end: failed(ctx, `wave ${k} (${wave.name}): a hook before the plan waits on ${before.waitingOn}, so its policy did not run`) };
3545
+ if (before.waitingOn && options.phase === "plan") {
3546
+ // #4992: the plan job ends the wave waiting on the other gate; its gate job records that gate's pending fact and the decision.
3547
+ markHeldOn(decision, before.waitingOn);
3548
+ return { end: { ...result, decision, exitCode: CHANT_EXIT.waiting } };
3549
+ }
2713
3550
  if (before.waitingOn) return { end: await decided(ctx, decision, recordPath, before.waitingOn) };
2714
3551
  if (spec.step) ctx.steps = new Map();
2715
3552
  const { members, pending: planPending, overriders: planOverriders, overridersSource: planOverridersSource, extras: planExtras, waves: found, changeSet, parts } = await planWaveRuns(ctx, wave.runs, wave.discover === true);
@@ -2886,8 +3723,15 @@ async function decideOpWave(
2886
3723
  );
2887
3724
  // A wide wave's shares apply under the deciding job's approval and overrides, so they are spent here, once.
2888
3725
  if (options.decide) {
2889
- if (!(await spendApproval(options, ctx, decision)) || !(await spendOverrides(ctx, decision))) return { end: ctx.result };
2890
- if (decision.spentAt || decision.overridesSpentAt) writeRecord(recordPath, decision, result);
3726
+ // #4992: a split wave's gate job holds the rows its step's runs change for the applying jobs, before it spends the approval.
3727
+ const lease = options.phase === "gate" && ctx.spec.step ? await leaseSplitRows(options, ctx, decision, recordPath) : undefined;
3728
+ if (lease && "end" in lease) return lease;
3729
+ if (!(await spendApproval(options, ctx, decision)) || !(await spendOverrides(ctx, decision))) {
3730
+ if (lease && !(await lease.release())) log(`wave ${k} (${wave.name}): could not let go of the rows it held; the next apply takes them over once this run is gone`);
3731
+ if (lease) delete decision.lease;
3732
+ return { end: ctx.result };
3733
+ }
3734
+ if (decision.spentAt || decision.overridesSpentAt || decision.lease) writeRecord(recordPath, decision, result);
2891
3735
  return { end: result };
2892
3736
  }
2893
3737
  return { go: { runs: wave.runs, earlierHolds: [], recordPath } };
@@ -3043,6 +3887,11 @@ async function decided(ctx: WaveContext, decision: OpWaveDecision, recordPath: s
3043
3887
  log(`The pull request's review does not approve wave ${k}: ${decision.review.reason}`);
3044
3888
  }
3045
3889
  const hook = await runGateHooks(ctx, decision, recordPath);
3890
+ if (decision.status === "waiting" && decision.heldOn?.spentForRerun) {
3891
+ // #4994: the approval is spent for the held hook's re-run; nobody needs to approve anything more.
3892
+ log(`Nothing in wave ${k} or after it ran. The approval of ${decision.heldOn.op} / ${decision.heldOn.gate} by ${decision.heldOn.spentForRerun.approvedBy} is spent for ${decision.heldOn.hook} to run again; run the wave again from its plan job`);
3893
+ return { ...result, exitCode: CHANT_EXIT.waiting };
3894
+ }
3046
3895
  if (decision.status === "waiting") {
3047
3896
  log(`Nothing in wave ${k} or after it ran. ${decision.heldOn ? `It waits on ${decision.heldOn.op} / ${decision.heldOn.gate}.` : "Read the plans, then"} approve: ${decision.approve} (with --resume, the approval also starts this job again)`);
3048
3897
  return { ...result, exitCode: CHANT_EXIT.waiting };
@@ -3820,6 +4669,8 @@ async function applyStage(
3820
4669
  }
3821
4670
  if (before.waitingOn) {
3822
4671
  markHeldOn(decision, before.waitingOn);
4672
+ // #4992: an applying job's hold goes to its record job, which records the other gate's pending fact.
4673
+ if (before.waitingOn.deferred) result.handoff = { ...result.handoff, heldOn: before.waitingOn };
3823
4674
  if (recordPath) {
3824
4675
  writeRecord(recordPath, decision, result);
3825
4676
  await runGateHooks(ctx, decision, recordPath);
@@ -3832,7 +4683,8 @@ async function applyStage(
3832
4683
  }
3833
4684
  if (!(await settleHolds(options, ctx, decision, holds, recordPath))) return;
3834
4685
  // #4552: on the resource grain the wave holds the rows its runs change, before its approval is spent.
3835
- const lease = spec.step ? await leaseWaveRows(options, ctx, runs) : undefined;
4686
+ // #4992: a split wave's gate job holds them for its applying jobs, which hold no write token.
4687
+ const lease = spec.step && options.phase !== "apply" ? await leaseWaveRows(options, ctx, runs) : undefined;
3836
4688
  if (lease && "failed" in lease) {
3837
4689
  failed(ctx, lease.failed);
3838
4690
  return;
@@ -4157,10 +5009,21 @@ async function applyStepRunsAtOnce(options: RunOpWaveOptions, ctx: WaveContext,
4157
5009
  * 9), which fails the wave by name.
4158
5010
  */
4159
5011
  async function recordStepReleases(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision, runs: readonly OpWaveRun[]): Promise<void> {
4160
- const { spec, k, wave, log, result } = ctx;
4161
5012
  if (options.releases === false) return;
5013
+ // #4992: a split wave's applying job holds no write token; its record job writes the releases.
5014
+ if (options.phase === "apply") {
5015
+ const requests = stepReleaseRequests(options, ctx, decision, runs);
5016
+ if (requests.length > 0) ctx.result.handoff = { ...ctx.result.handoff, releases: requests };
5017
+ return;
5018
+ }
4162
5019
  const port = options.releases ?? (options.gates ? undefined : gitOpWaveReleasePort({ cwd: ctx.cwd }));
4163
5020
  if (!port) return;
5021
+ await writeStepReleases(port, ctx, stepReleaseRequests(options, ctx, decision, runs));
5022
+ }
5023
+
5024
+ /** The release requests of the runs this wave applied through its step (#4615). */
5025
+ function stepReleaseRequests(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision, runs: readonly OpWaveRun[]): OpWaveReleaseRequest[] {
5026
+ const { spec, wave, result } = ctx;
4164
5027
  const applied = new Set(result.applied);
4165
5028
  let gitSha = options.head;
4166
5029
  const requests: OpWaveReleaseRequest[] = [];
@@ -4178,20 +5041,36 @@ async function recordStepReleases(options: RunOpWaveOptions, ctx: WaveContext, d
4178
5041
  }
4179
5042
  requests.push({ ...names, target: run.target, planDigest: plan.planDigest, ...(gitSha ? { gitSha } : {}), ...(decision.approvedBy ? { approver: decision.approvedBy } : {}) });
4180
5043
  }
4181
- if (requests.length === 0) return;
5044
+ return requests;
5045
+ }
5046
+
5047
+ /** Write release requests (#4615), failing the wave through `ctx` when one never reached the remote. */
5048
+ async function writeStepReleases(port: OpWaveReleasePort, ctx: WaveContext, requests: readonly OpWaveReleaseRequest[]): Promise<void> {
5049
+ for (const lost of await submitStepReleases(port, requests, `wave ${ctx.k} (${ctx.wave.name})`, ctx.log)) failed(ctx, lost);
5050
+ }
5051
+
5052
+ /**
5053
+ * Write release requests on their release ledgers (#4615): a line per run
5054
+ * recorded or not. Returns a failure for each one written that never
5055
+ * reached the remote (plywood#22 finding 9), which fails the wave.
5056
+ */
5057
+ async function submitStepReleases(port: OpWaveReleasePort, requests: readonly OpWaveReleaseRequest[], label: string, log: (line: string) => void): Promise<string[]> {
5058
+ if (requests.length === 0) return [];
4182
5059
  let outcomes: OpWaveReleaseOutcome[];
4183
5060
  try {
4184
- outcomes = await port.record(requests);
5061
+ outcomes = await port.record([...requests]);
4185
5062
  } catch (err) {
4186
- log(`wave ${k} (${wave.name}): applied, and no release record was written: ${err instanceof Error ? err.message : String(err)}`);
4187
- return;
5063
+ log(`${label}: applied, and no release record was written: ${err instanceof Error ? err.message : String(err)}`);
5064
+ return [];
4188
5065
  }
5066
+ const lost: string[] = [];
4189
5067
  for (const [i, req] of requests.entries()) {
4190
5068
  const got = outcomes[i];
4191
5069
  if (got?.recorded) log(`${req.target}: recorded on the "${got.env}" release ledger as ${got.component} ${got.digest}${got.releaseDigest ? ` under release ${got.releaseDigest}` : ""}`);
4192
- else if (got && !got.recorded && got.lost) failed(ctx, `${req.target}: applied, and LifecyclePushLostError: the release record for ${req.component} in "${req.env}" was written and never reached the remote, so the wave fails: ${got.reason}`);
5070
+ else if (got && !got.recorded && got.lost) lost.push(`${req.target}: applied, and LifecyclePushLostError: the release record for ${req.component} in "${req.env}" was written and never reached the remote, so the wave fails: ${got.reason}`);
4193
5071
  else log(`${req.target}: applied, and no release record was written for ${req.component} in "${req.env}": ${got?.reason ?? "the port gave no answer"}`);
4194
5072
  }
5073
+ return lost;
4195
5074
  }
4196
5075
 
4197
5076
  /**