@cbartens/bkit 6.1.0 → 6.2.0

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 (317) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +43 -33
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -15,6 +15,7 @@
15
15
  // step's own commit (if any). Forensic only — points to the commit that preceded
16
16
  // this step's work, not the commit that resulted from it.
17
17
 
18
+ import { spawnSync } from "node:child_process";
18
19
  import { createHash } from "node:crypto";
19
20
  import * as fs from "node:fs";
20
21
  import * as path from "node:path";
@@ -38,6 +39,10 @@ export type CiSelection =
38
39
  headSha: string;
39
40
  conclusion: "failure" | "timed_out" | "startup_failure";
40
41
  redTiers: CiTier[];
42
+ /** Failed jobs of the selected run, the capstone left out (1 when only it failed). */
43
+ failedJobCount?: number;
44
+ /** Names of the selected run's failed jobs, sorted, the capstone left out (`[]` when only it failed). */
45
+ failedJobs?: string[];
41
46
  via: string;
42
47
  };
43
48
 
@@ -76,6 +81,11 @@ export function validateCiSelection(value: unknown): value is CiSelection {
76
81
  ["failure", "timed_out", "startup_failure"].includes(stringField("conclusion")) &&
77
82
  Array.isArray(v.redTiers) &&
78
83
  v.redTiers.every((tier) => CI_TIERS.some((known) => known === tier)) &&
84
+ (v.failedJobCount === undefined ||
85
+ (Number.isSafeInteger(v.failedJobCount) && Number(v.failedJobCount) > 0)) &&
86
+ (v.failedJobs === undefined ||
87
+ (Array.isArray(v.failedJobs) &&
88
+ v.failedJobs.every((name) => typeof name === "string" && name.length > 0))) &&
79
89
  typeof v.via === "string" &&
80
90
  v.via.trim().length > 0
81
91
  );
@@ -98,6 +108,172 @@ export function ciSelectionIdentity(selection: CiSelection): string {
98
108
  );
99
109
  }
100
110
 
111
+ export const CI_HANDOFF_RESULTS = [
112
+ "none",
113
+ "pending",
114
+ "success",
115
+ "failure",
116
+ "provider-error",
117
+ ] as const;
118
+ export type CiHandoffResult = (typeof CI_HANDOFF_RESULTS)[number];
119
+ export const CI_RETRIGGER_STATES = [
120
+ "intended",
121
+ "commit-created",
122
+ "push-completed",
123
+ "receipt-completed",
124
+ ] as const;
125
+ export type CiRetriggerState = (typeof CI_RETRIGGER_STATES)[number];
126
+ export type CiHandoffTarget = {
127
+ provider: "github";
128
+ repo: string;
129
+ pr: string | null;
130
+ head: string;
131
+ branch: string;
132
+ };
133
+ export type CiHandoffRetrigger = {
134
+ state: CiRetriggerState;
135
+ original: string;
136
+ commit?: string;
137
+ /** Shared branch: the copy of `commit` made for the remote tip, persisted before it is pushed. */
138
+ copy?: string;
139
+ ref?: string;
140
+ remote?: string;
141
+ receipt?: string;
142
+ };
143
+ /** One persisted CI wait observation (cumulative counts) with its target identity and retrigger checkpoint. */
144
+ export type CiHandoffEvent = {
145
+ type: "ci-handoff";
146
+ workflow: string;
147
+ at: string;
148
+ phase: "poll" | "repoll";
149
+ target: CiHandoffTarget;
150
+ observation: { result: CiHandoffResult; attempts: number; errors: number };
151
+ retrigger?: CiHandoffRetrigger;
152
+ };
153
+ export type CiHandoffState = {
154
+ phase: "poll" | "repoll";
155
+ attempts: number;
156
+ errors: number;
157
+ last: { result: CiHandoffResult; at: string } | null;
158
+ retrigger: CiHandoffRetrigger | null;
159
+ /** The cumulative counts when the retrigger first appeared: the re-poll counts from here. */
160
+ retriggerBase: { attempts: number; errors: number } | null;
161
+ /** Events for another target (repo, PR, head or branch). */
162
+ stale: number;
163
+ /** Events refused because a cumulative count went backwards. */
164
+ invalid: number;
165
+ };
166
+
167
+ const SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
168
+ const REPO_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/;
169
+ const isRecord = (v: unknown): v is Record<string, unknown> =>
170
+ v !== null && typeof v === "object" && !Array.isArray(v);
171
+ const isCount = (v: unknown): v is number => Number.isSafeInteger(v) && Number(v) >= 0;
172
+ const nonEmpty = (v: unknown): v is string => typeof v === "string" && v.trim().length > 0;
173
+
174
+ function validHandoffTarget(value: unknown): value is CiHandoffTarget {
175
+ if (!isRecord(value)) return false;
176
+ return (
177
+ value.provider === "github" &&
178
+ typeof value.repo === "string" &&
179
+ REPO_RE.test(value.repo) &&
180
+ (value.pr === null || (typeof value.pr === "string" && /^[1-9][0-9]*$/.test(value.pr))) &&
181
+ typeof value.head === "string" &&
182
+ SHA_RE.test(value.head) &&
183
+ nonEmpty(value.branch)
184
+ );
185
+ }
186
+
187
+ function validRetrigger(value: unknown): value is CiHandoffRetrigger {
188
+ if (!isRecord(value)) return false;
189
+ const state = CI_RETRIGGER_STATES.find((s) => s === value.state);
190
+ if (state === undefined) return false;
191
+ if (typeof value.original !== "string" || !SHA_RE.test(value.original)) return false;
192
+ const sha = (k: string) => typeof value[k] === "string" && SHA_RE.test(value[k]);
193
+ if (value.copy !== undefined && !sha("copy")) return false;
194
+ if (state === "intended") return true;
195
+ if (!sha("commit")) return false;
196
+ if (state === "commit-created") return true;
197
+ if (!nonEmpty(value.ref) || !sha("remote")) return false;
198
+ if (state === "push-completed") return true;
199
+ return nonEmpty(value.receipt);
200
+ }
201
+
202
+ /** Validate one `ci-handoff` row before any reader treats it as evidence. */
203
+ export function validateCiHandoffEvent(value: unknown): value is CiHandoffEvent {
204
+ if (!isRecord(value) || value.type !== "ci-handoff") return false;
205
+ if (!nonEmpty(value.workflow) || !nonEmpty(value.at)) return false;
206
+ if (value.phase !== "poll" && value.phase !== "repoll") return false;
207
+ if (!validHandoffTarget(value.target)) return false;
208
+ const o = value.observation;
209
+ if (!isRecord(o)) return false;
210
+ if (!CI_HANDOFF_RESULTS.some((r) => r === o.result)) return false;
211
+ if (!isCount(o.attempts) || !isCount(o.errors) || o.errors > o.attempts) return false;
212
+ if (value.retrigger !== undefined && !validRetrigger(value.retrigger)) return false;
213
+ return value.phase !== "repoll" || value.retrigger !== undefined;
214
+ }
215
+
216
+ /** Wording and transport do not change which target a handoff row is about. */
217
+ export function ciHandoffIdentity(target: CiHandoffTarget): string {
218
+ return JSON.stringify([
219
+ target.provider,
220
+ target.repo.toLowerCase(),
221
+ target.pr,
222
+ target.head,
223
+ target.branch,
224
+ ]);
225
+ }
226
+
227
+ /**
228
+ * The cumulative handoff state of one target: de-dupes, orders by `at`, counts rows for other
229
+ * targets as `stale` and rows whose cumulative counts go backwards as `invalid`.
230
+ */
231
+ export function foldCiHandoff(rows: readonly object[], target: CiHandoffTarget): CiHandoffState {
232
+ const seen = new Set<string>();
233
+ const events: CiHandoffEvent[] = [];
234
+ for (const row of rows) {
235
+ if (!validateCiHandoffEvent(row)) continue;
236
+ const key = JSON.stringify(row);
237
+ if (seen.has(key)) continue;
238
+ seen.add(key);
239
+ events.push(row);
240
+ }
241
+ const ordered = events
242
+ .map((e, i) => ({ e, i }))
243
+ .sort((a, b) => (a.e.at < b.e.at ? -1 : a.e.at > b.e.at ? 1 : a.i - b.i))
244
+ .map((x) => x.e);
245
+ const want = ciHandoffIdentity(target);
246
+ const state: CiHandoffState = {
247
+ phase: "poll",
248
+ attempts: 0,
249
+ errors: 0,
250
+ last: null,
251
+ retrigger: null,
252
+ retriggerBase: null,
253
+ stale: 0,
254
+ invalid: 0,
255
+ };
256
+ for (const e of ordered) {
257
+ if (ciHandoffIdentity(e.target) !== want) {
258
+ state.stale += 1;
259
+ continue;
260
+ }
261
+ if (e.observation.attempts < state.attempts || e.observation.errors < state.errors) {
262
+ state.invalid += 1;
263
+ continue;
264
+ }
265
+ state.attempts = e.observation.attempts;
266
+ state.errors = e.observation.errors;
267
+ state.phase = e.phase;
268
+ state.last = { result: e.observation.result, at: e.at };
269
+ if (e.retrigger !== undefined) {
270
+ state.retriggerBase ??= { attempts: e.observation.attempts, errors: e.observation.errors };
271
+ state.retrigger = e.retrigger;
272
+ }
273
+ }
274
+ return state;
275
+ }
276
+
101
277
  export type Step = {
102
278
  step: string;
103
279
  status: "DONE" | "FAILED";
@@ -115,6 +291,8 @@ export type Step = {
115
291
  scope?: string;
116
292
  ciGeneration?: number;
117
293
  reproduced?: string;
294
+ /** Where a debug-run-tests verdict came from: `local` (a gate ran) or `ci` (selected CI evidence). */
295
+ source?: string;
118
296
  };
119
297
 
120
298
  /** Validate the bounded CI evidence variant without relaxing local exit codes. */
@@ -122,13 +300,22 @@ export function testRunProblem(value: unknown): string | null {
122
300
  if (!value || typeof value !== "object") return "test-run must be an object";
123
301
  const r = value as Record<string, unknown>;
124
302
  const positive = (v: unknown) => Number.isSafeInteger(v) && Number(v) > 0;
303
+ if (
304
+ r.failedTests !== undefined &&
305
+ (!Array.isArray(r.failedTests) ||
306
+ !r.failedTests.every((name) => typeof name === "string" && name !== ""))
307
+ )
308
+ return "failedTests must be an array of non-empty strings";
309
+ if (r.failedTestsTruncated !== undefined && typeof r.failedTestsTruncated !== "boolean")
310
+ return "failedTestsTruncated must be a boolean";
125
311
  if (r.source === "ci") {
312
+ if (r.tested !== undefined) return "a CI evidence round records no tested snapshot";
126
313
  if (
127
314
  r.workflow !== "debug" ||
128
315
  r.step !== "debug-run-tests" ||
129
316
  r.verdict !== "FAIL" ||
130
317
  r.exitCode !== null ||
131
- r.failures !== null ||
318
+ (r.failures !== null && !positive(r.failures)) ||
132
319
  r.gate !== null ||
133
320
  !positive(r.ciGeneration) ||
134
321
  !positive(r.runAttempt) ||
@@ -155,6 +342,8 @@ export function testRunProblem(value: unknown): string | null {
155
342
  return "local exitCode must be a non-negative integer";
156
343
  if (r.failures !== null && (!Number.isSafeInteger(r.failures) || Number(r.failures) < 0))
157
344
  return "invalid failure count";
345
+ if (r.tested !== undefined && !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(String(r.tested)))
346
+ return "tested must be a full commit sha";
158
347
  return null;
159
348
  }
160
349
 
@@ -279,8 +468,50 @@ export function fold(events: StatusEvent[]): WorkflowRun[] {
279
468
  // rows it skips (runtime-resolved, transport-fallback, close-transport, ...).
280
469
  export type StatusRow = { type: string } & Record<string, unknown>;
281
470
 
471
+ /**
472
+ * The `invocation` row a run's `status.jsonl` carries for one engine-issued workflow-mode
473
+ * invocation: the durable authority the outbox receipt is rebuilt from. The fold skips it.
474
+ */
475
+ export type InvocationEvent = {
476
+ type: "invocation";
477
+ workflow: string;
478
+ at: string;
479
+ id: string;
480
+ step: string;
481
+ number: number;
482
+ title: string;
483
+ run: number;
484
+ statusPath: string;
485
+ bookRoot: string;
486
+ group: string | null;
487
+ attempt: string | null;
488
+ agent: string | null;
489
+ host: string | null;
490
+ configuredModel: string | null;
491
+ observedModel: string | null;
492
+ worktree: string;
493
+ };
494
+
495
+ /** True for a parsed `status.jsonl` row that is a complete `invocation` event. */
496
+ export function isInvocationEvent(value: unknown): value is InvocationEvent {
497
+ if (value === null || typeof value !== "object") return false;
498
+ const v = value as Record<string, unknown>;
499
+ return (
500
+ v["type"] === "invocation" &&
501
+ typeof v["id"] === "string" &&
502
+ typeof v["workflow"] === "string" &&
503
+ typeof v["step"] === "string" &&
504
+ typeof v["number"] === "number" &&
505
+ typeof v["title"] === "string" &&
506
+ typeof v["run"] === "number" &&
507
+ typeof v["statusPath"] === "string" &&
508
+ typeof v["bookRoot"] === "string" &&
509
+ typeof v["worktree"] === "string"
510
+ );
511
+ }
512
+
282
513
  // Serialize one event to the NDJSON line appended to `status.jsonl`, newline included.
283
- export function appendLine(event: StatusEvent | StatusRow): string {
514
+ export function appendLine(event: StatusEvent | StatusRow | InvocationEvent): string {
284
515
  return `${JSON.stringify(event)}\n`;
285
516
  }
286
517
 
@@ -288,8 +519,8 @@ export function appendLine(event: StatusEvent | StatusRow): string {
288
519
  // Queries — the reads routing and counters make. Two opposite scopings: attempt
289
520
  // counts and verdict/failures/mode reads look at the ACTIVE
290
521
  // run only, so a resumed run never inherits a finished run's spent budget;
291
- // strategy reads ALL runs, so a resumed run keeps its place on the
292
- // STANDARD -> PIVOT -> FINAL ladder instead of restarting it.
522
+ // strategy reads ALL runs, so a test that also failed in an earlier run's
523
+ // attempt still counts toward the fix round's STANDARD / PIVOT / FINAL label.
293
524
  // ---------------------------------------------------------------------------
294
525
 
295
526
  /** `status.jsonl` timestamp: UTC, whole seconds (`date -u +%FT%TZ`). */
@@ -319,6 +550,38 @@ export function activeDoneSteps(runs: WorkflowRun[], workflow: string, f: StepFi
319
550
  return run.steps.filter((s) => matches(s, f));
320
551
  }
321
552
 
553
+ /** A check round that found no problems: verdict PASS, or CONCERNS with 0 failures. */
554
+ export const cleanRound = (s: Step) =>
555
+ s.status === "DONE" && (s.verdict === "PASS" || (s.verdict === "CONCERNS" && s.failures === 0));
556
+
557
+ /** The active run's last clean round of `step` (`isClean`, by default `cleanRound`); undefined when none ran. */
558
+ export function lastCleanRound(
559
+ runs: WorkflowRun[],
560
+ workflow: string,
561
+ step: string,
562
+ isClean: (s: Step) => boolean = cleanRound,
563
+ ) {
564
+ return lastRun(runs, workflow)
565
+ ?.steps.filter((s) => s.step === step && isClean(s))
566
+ .at(-1);
567
+ }
568
+
569
+ /** `activeDoneSteps` after `clean`'s last clean round (`isClean`): the rounds of the loop still open. */
570
+ export function activeDoneStepsSinceClean(
571
+ runs: WorkflowRun[],
572
+ workflow: string,
573
+ f: StepFilter,
574
+ clean: string,
575
+ isClean: (s: Step) => boolean = cleanRound,
576
+ ): Step[] {
577
+ const run = lastRun(runs, workflow);
578
+ if (!run) return [];
579
+ const last = lastCleanRound(runs, workflow, clean, isClean);
580
+ return run.steps
581
+ .slice(last === undefined ? 0 : run.steps.indexOf(last) + 1)
582
+ .filter((s) => matches(s, f));
583
+ }
584
+
322
585
  /** DONE rows for the step across ALL runs of `workflow`: debug's limits span every run. */
323
586
  export function allRunsDoneSteps(runs: WorkflowRun[], workflow: string, f: StepFilter): Step[] {
324
587
  return runs
@@ -432,10 +695,343 @@ export function recordAction(
432
695
  return row;
433
696
  }
434
697
 
698
+ // ---------------------------------------------------------------------------
699
+ // Ledger operations — a bookkeeping write that must survive a lost response. One
700
+ // operation id names one request (its hash): the same id and hash replays the
701
+ // original receipt, the same id with another hash is refused, and a new id on the
702
+ // same ledger key is a deliberate later update. This is stricter than the generic
703
+ // action policy above, where the same key with a changed hash acts again.
704
+ // ---------------------------------------------------------------------------
705
+
706
+ /**
707
+ * The operations store of one book root: `<git common dir>/bkit-outbox/ledger-operations/<root hash>.jsonl`.
708
+ * It holds prepared row bytes, so it stays private (0700 dirs, 0600 file) and outside every committed
709
+ * or unioned path. One file per book root keeps a linked worktree's offsets apart from the main
710
+ * checkout's. Null outside a git repository.
711
+ */
712
+ export function ledgerOperationsFile(root: string, prepare = false): string | null {
713
+ // Not `commands/lib.ts`: that module imports this one.
714
+ const res = spawnSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
715
+ cwd: root,
716
+ encoding: "utf-8",
717
+ });
718
+ const common = res.status === 0 ? res.stdout.trim() : "";
719
+ if (common === "") return null;
720
+ const outbox = path.join(common, "bkit-outbox");
721
+ const id = createHash("sha256").update(fs.realpathSync(root)).digest("hex").slice(0, 16);
722
+ const file = path.join(outbox, "ledger-operations", `${id}.jsonl`);
723
+ if (prepare) privateDir(file);
724
+ return file;
725
+ }
726
+
727
+ /** Create the private directory chain of `file`'s parent (0700). */
728
+ function privateDir(file: string): void {
729
+ fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
730
+ }
731
+
732
+ /** Intents on `target` of this root with no receipt; none when there is no store. */
733
+ export function pendingLedgerIntentsFor(root: string, target: string): LedgerIntent[] {
734
+ const ops = ledgerOperationsFile(root);
735
+ return ops === null ? [] : pendingLedgerIntents(ops, target);
736
+ }
737
+
738
+ const ledgerOpKey = (operation: string) => actionKey("ledger-op", operation);
739
+
740
+ export type LedgerOperationState =
741
+ { state: "new" } | { state: "replay" | "conflict"; row: EngineActionRow };
742
+
743
+ /** The status rows of one bounded correction: a guaranteed no-write rejection, a corrected retry, its success. */
744
+ export const CORRECTION_REJECTED_ROW = "correction-rejected";
745
+ export const CORRECTION_CANDIDATE_ROW = "correction-candidate";
746
+ export const CORRECTION_SUCCEEDED_ROW = "correction-succeeded";
747
+
748
+ /**
749
+ * The stable scope one rejected sub-step's corrected retries share: derived from the run, step,
750
+ * task group and attempt, the ledger and the sub-step, never from an invocation or operation id,
751
+ * so a new tool call, helper or resume spends from the same budget.
752
+ */
753
+ export function correctionScope(o: {
754
+ workflow: string;
755
+ run: number | null;
756
+ step: string;
757
+ group: string | null;
758
+ attempt: string | null;
759
+ ledger: string;
760
+ substep: string;
761
+ }): string {
762
+ return [
763
+ "ledgers-append",
764
+ o.ledger,
765
+ o.substep,
766
+ o.workflow,
767
+ `run${o.run ?? 0}`,
768
+ o.step,
769
+ ...(o.group === null ? [] : [`group${o.group}`]),
770
+ ...(o.attempt === null ? [] : [`attempt${o.attempt}`]),
771
+ ].join(":");
772
+ }
773
+
774
+ /** Where `operation` stands in `file`: unseen, done with this request, or used for another. */
775
+ export function ledgerOperation(
776
+ file: string,
777
+ operation: string,
778
+ hash: string,
779
+ ): LedgerOperationState {
780
+ const known = engineActions(file)
781
+ .filter((r) => r.key === ledgerOpKey(operation))
782
+ .at(0);
783
+ if (known === undefined) return { state: "new" };
784
+ return { state: known.hash === hash ? "replay" : "conflict", row: known };
785
+ }
786
+
787
+ /**
788
+ * Record the receipt of a finished ledger operation. A known operation with the same
789
+ * hash returns its original row unchanged; one with another hash throws and writes nothing.
790
+ * `detail` rides on the row so a replay can return the original effect.
791
+ */
792
+ export function recordLedgerOperation(
793
+ file: string,
794
+ a: { operation: string; hash: string; ref: string | null; detail?: Record<string, unknown> },
795
+ ): EngineActionRow {
796
+ const known = ledgerOperation(file, a.operation, a.hash);
797
+ if (known.state === "conflict")
798
+ throw new Error(`ledger operation ${a.operation} was already used for a different request`);
799
+ if (known.state === "replay") return known.row;
800
+ const row = {
801
+ ...recordRow({
802
+ action: "ledger-append",
803
+ key: ledgerOpKey(a.operation),
804
+ hash: a.hash,
805
+ ref: a.ref,
806
+ }),
807
+ ...(a.detail === undefined ? {} : { detail: a.detail }),
808
+ };
809
+ privateDir(file);
810
+ fs.appendFileSync(file, appendLine(row), { mode: 0o600 });
811
+ return row;
812
+ }
813
+
814
+ const recordRow = (a: {
815
+ action: string;
816
+ key: string;
817
+ hash: string;
818
+ ref: string | null;
819
+ }): EngineActionRow => ({ type: ENGINE_ACTION, ...a, at: statusTimestamp() });
820
+
821
+ /** The exact bytes an operation prepared, written before the target is touched. */
822
+ export type LedgerIntent = {
823
+ type: "ledger-intent";
824
+ operation: string;
825
+ hash: string;
826
+ /** Target path relative to the book root. */
827
+ file: string;
828
+ offset: number;
829
+ bytes: number;
830
+ block: string;
831
+ at: string;
832
+ };
833
+
834
+ function intentRows(file: string): LedgerIntent[] {
835
+ if (!fs.existsSync(file)) return [];
836
+ const out: LedgerIntent[] = [];
837
+ for (const line of fs.readFileSync(file, "utf-8").split("\n")) {
838
+ if (line.trim() === "") continue;
839
+ const parsed = parseJson(line);
840
+ if (!parsed.ok) continue;
841
+ const r = parsed.value as Partial<LedgerIntent> | null;
842
+ if (r?.type === "ledger-intent" && typeof r.operation === "string") out.push(r as LedgerIntent);
843
+ }
844
+ return out;
845
+ }
846
+
847
+ /** Record the prepared bytes of an operation before writing them. */
848
+ export function recordLedgerIntent(file: string, intent: Omit<LedgerIntent, "type" | "at">): void {
849
+ privateDir(file);
850
+ const row: LedgerIntent = { type: "ledger-intent", ...intent, at: statusTimestamp() };
851
+ fs.appendFileSync(file, `${JSON.stringify(row)}\n`, { mode: 0o600 });
852
+ }
853
+
854
+ /** The latest prepared intent of `operation`, or undefined. */
855
+ export function ledgerIntent(file: string, operation: string): LedgerIntent | undefined {
856
+ return intentRows(file)
857
+ .filter((i) => i.operation === operation)
858
+ .at(-1);
859
+ }
860
+
861
+ /** Intents on `target` (relative path) whose operation has no receipt: effects not yet confirmed. */
862
+ export function pendingLedgerIntents(file: string, target: string): LedgerIntent[] {
863
+ const receipted = new Set(engineActions(file).map((r) => r.key));
864
+ const latest = new Map<string, LedgerIntent>();
865
+ for (const i of intentRows(file)) latest.set(i.operation, i);
866
+ return [...latest.values()].filter(
867
+ (i) => i.file === target && !receipted.has(ledgerOpKey(i.operation)),
868
+ );
869
+ }
870
+
871
+ /** Create `file` holding `content` only if absent; false when it exists. Other errors throw. */
872
+ export function createExclusive(file: string, content: string): boolean {
873
+ let fd: number;
874
+ try {
875
+ fd = fs.openSync(file, "wx");
876
+ } catch (err) {
877
+ // EEXIST is the expected "someone holds it" answer; anything else is a real error.
878
+ if ((err as NodeJS.ErrnoException).code === "EEXIST") return false;
879
+ throw err;
880
+ }
881
+ try {
882
+ fs.writeSync(fd, content);
883
+ } finally {
884
+ fs.closeSync(fd);
885
+ }
886
+ return true;
887
+ }
888
+
889
+ const sleepSync = (ms: number) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
890
+
891
+ /** How long a writer waits for another writer's lock on a ledger before refusing. */
892
+ export const TARGET_LOCK_WAIT_MS = 10_000;
893
+
894
+ /**
895
+ * Run `fn` holding the exclusive lock on `target` (`<target>.bkit-lock`). A holder that
896
+ * does not release in time is never reclaimed: the call throws, naming the lock file.
897
+ */
898
+ export function withTargetLock<T>(target: string, fn: () => T, waitMs = TARGET_LOCK_WAIT_MS): T {
899
+ const lock = `${target}.bkit-lock`;
900
+ const token = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
901
+ fs.mkdirSync(path.dirname(lock), { recursive: true });
902
+ const body = JSON.stringify({ pid: process.pid, at: statusTimestamp(), token });
903
+ const deadline = Date.now() + waitMs;
904
+ while (!createExclusive(lock, body)) {
905
+ if (Date.now() >= deadline) {
906
+ const holder = fs.existsSync(lock) ? fs.readFileSync(lock, "utf-8").trim() : "unknown";
907
+ throw new Error(
908
+ `ledger target ${target} is locked by another writer (${holder}); if that process is gone, remove ${lock}`,
909
+ );
910
+ }
911
+ sleepSync(20);
912
+ }
913
+ try {
914
+ return fn();
915
+ } finally {
916
+ const held = fs.existsSync(lock) ? fs.readFileSync(lock, "utf-8") : "";
917
+ if (held === body) fs.rmSync(lock, { force: true });
918
+ }
919
+ }
920
+
921
+ /** Append `block` to `target` at exactly `offset`, flush it and read it back; throws on any mismatch. */
922
+ export function writePrepared(target: string, block: string, offset: number): void {
923
+ const size = fs.existsSync(target) ? fs.statSync(target).size : 0;
924
+ if (size !== offset)
925
+ throw new Error(
926
+ `ledger ${target} changed since the append was prepared (${size} != ${offset})`,
927
+ );
928
+ fs.mkdirSync(path.dirname(target), { recursive: true });
929
+ const fd = fs.openSync(target, "a");
930
+ try {
931
+ fs.writeSync(fd, block);
932
+ fs.fsyncSync(fd);
933
+ } finally {
934
+ fs.closeSync(fd);
935
+ }
936
+ const bytes = Buffer.byteLength(block);
937
+ const back = Buffer.alloc(bytes);
938
+ const rd = fs.openSync(target, "r");
939
+ try {
940
+ fs.readSync(rd, back, 0, bytes, offset);
941
+ } finally {
942
+ fs.closeSync(rd);
943
+ }
944
+ if (back.toString("utf-8") !== block)
945
+ throw new Error(`ledger ${target} read-back disagrees with the bytes just written`);
946
+ }
947
+
948
+ export type AppendCheckpoint = (name: "prepared" | "written" | "receipted") => void;
949
+
950
+ export type AppendHooks = {
951
+ prepared?: (p: { offset: number; block: string }) => void;
952
+ written?: (p: { offset: number; bytes: number; block: string }) => void;
953
+ checkpoint?: AppendCheckpoint;
954
+ };
955
+
956
+ /**
957
+ * The one lock-and-confirm append: under the target lock, read the current text, let
958
+ * `prepare` build the rows to add, write them (a missing final newline is closed first)
959
+ * and flush and read them back. Returns where the bytes landed.
960
+ */
961
+ export function appendLocked(
962
+ target: string,
963
+ prepare: (current: string) => string,
964
+ hooks: AppendHooks = {},
965
+ ): { offset: number; bytes: number; block: string } {
966
+ return withTargetLock(target, () => appendHeld(target, prepare, hooks));
967
+ }
968
+
969
+ /** {@link appendLocked} for a caller that already holds the target lock. */
970
+ export function appendHeld(
971
+ target: string,
972
+ prepare: (current: string) => string,
973
+ hooks: AppendHooks = {},
974
+ ): { offset: number; bytes: number; block: string } {
975
+ {
976
+ const current = fs.existsSync(target) ? fs.readFileSync(target, "utf-8") : "";
977
+ const body = prepare(current);
978
+ const block = `${current !== "" && !current.endsWith("\n") ? "\n" : ""}${body}`;
979
+ const offset = Buffer.byteLength(current);
980
+ hooks.prepared?.({ offset, block });
981
+ hooks.checkpoint?.("prepared");
982
+ writePrepared(target, block, offset);
983
+ const bytes = Buffer.byteLength(block);
984
+ hooks.checkpoint?.("written");
985
+ hooks.written?.({ offset, bytes, block });
986
+ hooks.checkpoint?.("receipted");
987
+ return { offset, bytes, block };
988
+ }
989
+ }
990
+
435
991
  export type Strategy = NonNullable<Step["strategy"]>;
436
992
 
437
- /** Next rung: none -> STANDARD -> PIVOT -> FINAL, and FINAL stays FINAL. */
438
- export function nextStrategy(prior: Strategy | undefined): Strategy {
439
- if (prior === undefined) return "STANDARD";
440
- return prior === "STANDARD" ? "PIVOT" : "FINAL";
993
+ /**
994
+ * The next fix round's label, from the tests failing now. Reads the `test-run` rows of one
995
+ * test step across every run of the workflow; the latest row's `failedTests` are the tests
996
+ * failing now. For each, it counts the distinct earlier attempts (run and attempt) whose rows
997
+ * list it; re-runs under one attempt count once, and a row without `failedTests` lists none.
998
+ * Rows with no `attempt` share one key per run, so they count as one attempt.
999
+ * The highest count gives the label: 0 `STANDARD`, 1 `PIVOT`, 2 or more `FINAL`.
1000
+ * `repeatTests` holds the tests with a count of 1 or more, in the latest row's order.
1001
+ *
1002
+ * `current` is the attempt the fix round follows, for a test step that does not run on every
1003
+ * round (a group gate runs only after a passing verify). A latest row from an older run or
1004
+ * another attempt says nothing about the tests failing now: `STANDARD`, no `repeatTests`.
1005
+ */
1006
+ export function repeatStrategy(
1007
+ rows: readonly StatusRow[],
1008
+ workflow: string,
1009
+ step: string,
1010
+ current?: number,
1011
+ ): { strategy: Strategy; repeatTests: string[] } {
1012
+ let run = 0;
1013
+ const attempts: { key: string; run: number; attempt: unknown; tests: readonly string[] }[] = [];
1014
+ for (const r of rows) {
1015
+ if (r.type === "workflow-started" && r.workflow === workflow) run += 1;
1016
+ if (r.type !== "test-run" || r.step !== step) continue;
1017
+ if (r.workflow !== undefined && r.workflow !== workflow) continue;
1018
+ const tests = Array.isArray(r.failedTests)
1019
+ ? r.failedTests.filter((t): t is string => typeof t === "string")
1020
+ : [];
1021
+ attempts.push({ key: `${run}:${String(r.attempt)}`, run, attempt: r.attempt, tests });
1022
+ }
1023
+ const latest = attempts.at(-1);
1024
+ if (latest === undefined) return { strategy: "STANDARD", repeatTests: [] };
1025
+ if (current !== undefined && (latest.run !== run || Number(latest.attempt) !== current))
1026
+ return { strategy: "STANDARD", repeatTests: [] };
1027
+ const earlier = attempts.filter((a) => a.key !== latest.key);
1028
+ let highest = 0;
1029
+ const repeatTests: string[] = [];
1030
+ for (const name of new Set(latest.tests)) {
1031
+ const count = new Set(earlier.filter((a) => a.tests.includes(name)).map((a) => a.key)).size;
1032
+ if (count > 0) repeatTests.push(name);
1033
+ highest = Math.max(highest, count);
1034
+ }
1035
+ const strategy = highest === 0 ? "STANDARD" : highest === 1 ? "PIVOT" : "FINAL";
1036
+ return { strategy, repeatTests };
441
1037
  }