@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
@@ -9,6 +9,7 @@
9
9
  // that spec, so the help text cannot drift from what the command accepts.
10
10
 
11
11
  import { spawnSync } from "node:child_process";
12
+ import { createHash, randomUUID } from "node:crypto";
12
13
  import * as fs from "node:fs";
13
14
  import * as os from "node:os";
14
15
  import * as path from "node:path";
@@ -23,7 +24,7 @@ import {
23
24
  rebasePaused,
24
25
  shouldRecordFriction,
25
26
  } from "../ledgers/journal.js";
26
- import { fold, type StatusEvent } from "../ledgers/status.js";
27
+ import { fold, isInvocationEvent, type StatusEvent } from "../ledgers/status.js";
27
28
  import { gitEnv, resolveGitSha } from "../ledgers/telemetry.js";
28
29
  import { parseJson } from "../shared/json.js";
29
30
  import { renderText } from "../shared/text.js";
@@ -70,6 +71,63 @@ export class CommandError extends Error {
70
71
  }
71
72
  }
72
73
 
74
+ /**
75
+ * A refusal the receiving handler declares as pre-effect validation: nothing was written,
76
+ * so a corrected retry of the same sub-step is permitted within its correction budget.
77
+ * Only this class (never a generic `CommandError`) carries that permission.
78
+ */
79
+ export class NoWriteRejection extends CommandError {
80
+ constructor(
81
+ code: number,
82
+ message: string,
83
+ readonly detail: { scope: string; substep: string },
84
+ ) {
85
+ super(code, message);
86
+ }
87
+ }
88
+
89
+ /** A failure after an effect may have begun: the state must be reconciled, never auto-retried. */
90
+ export class UncertainEffect extends CommandError {}
91
+
92
+ /** The correction budget of `scope` is spent: nothing was written and no further retry is allowed. */
93
+ export class CorrectionExhausted extends CommandError {
94
+ constructor(
95
+ code: number,
96
+ message: string,
97
+ readonly scope: string,
98
+ ) {
99
+ super(code, message);
100
+ }
101
+ }
102
+
103
+ /** The structured `--json` error for the declared classes; every other error prints none. */
104
+ function structuredError(err: CommandError): Record<string, unknown> | null {
105
+ if (err instanceof CorrectionExhausted) {
106
+ return {
107
+ code: err.code,
108
+ message: err.message,
109
+ effects: "none",
110
+ correctable: false,
111
+ exhausted: true,
112
+ scope: err.scope,
113
+ };
114
+ }
115
+ if (err instanceof NoWriteRejection) {
116
+ return {
117
+ code: err.code,
118
+ message: err.message,
119
+ effects: "none",
120
+ correctable: true,
121
+ scope: err.detail.scope,
122
+ substep: err.detail.substep,
123
+ };
124
+ }
125
+ if (err instanceof UncertainEffect) {
126
+ return { code: err.code, message: err.message, effects: "uncertain", correctable: false };
127
+ }
128
+ return null;
129
+ }
130
+
73
131
  // ---------------------------------------------------------------------------
74
132
  // Specs
75
133
  // ---------------------------------------------------------------------------
@@ -87,6 +145,13 @@ export interface FlagSpec {
87
145
  * cannot rewrite.
88
146
  */
89
147
  positional?: boolean;
148
+ /**
149
+ * For `--invocation` only: the verb compares the id itself, so the dispatcher does not
150
+ * resolve it as an issued invocation (it may name one this checkout never issued).
151
+ */
152
+ unresolved?: boolean;
153
+ /** Exit code when the value still carries a `{UPPER}` placeholder (default: usage, exit 2). */
154
+ placeholderExit?: number;
90
155
  help: string;
91
156
  }
92
157
 
@@ -102,38 +167,70 @@ export const wholeNumber = (v: FlagValue, flag: string, fallback: number, min =
102
167
  return Number(s);
103
168
  };
104
169
 
105
- /** The holder named by this run when its tests-lock wait gave up. */
106
- export function testsLockHolder(log: string, who: string): string | null {
107
- const prefix = `[machine-lock] ❌ ${who} gave up after `;
108
- for (const line of log.split(/\r?\n/)) {
109
- if (!line.startsWith(prefix)) continue;
110
- const holder = /^\d+s waiting for tests, in use by (.+)$/.exec(line.slice(prefix.length));
111
- if (holder) return holder[1]!;
170
+ /** The env var naming the file the machine-lock `run` wrapper writes its give-up or refusal to. */
171
+ export const LOCK_STATUS_FILE_ENV = "LOCAL_STACK_LOCK_STATUS_FILE";
172
+
173
+ /** What the machine-lock `run` wrapper wrote to its status file on exit 75, 73 or 124. */
174
+ export interface LockStatus {
175
+ /** The lock the wrapper was asked for (`tests` for the tests lock). */
176
+ lock: string;
177
+ /** `gave-up` (exit 75), `refused` (exit 73) or `held-too-long` (exit 124, stopped at the hold limit). */
178
+ outcome: string;
179
+ /** Each holder's `who — checkout (pid N, since HH:MM:SS)` note, joined by `; `. */
180
+ holder: string;
181
+ }
182
+
183
+ /** A fresh status file path for one gate run, in the OS temp folder; the file is not created. */
184
+ export function lockStatusFile(): string {
185
+ return path.join(os.tmpdir(), `bkit-lock-status-${process.pid}-${randomUUID()}`);
186
+ }
187
+
188
+ /**
189
+ * Read and delete a status file. Null when it is absent, empty, not a regular file or
190
+ * unreadable: the wrapper took its lock, or it never wrote the file.
191
+ */
192
+ export function readLockStatus(file: string): LockStatus | null {
193
+ const stat = fs.statSync(file, { throwIfNoEntry: false });
194
+ if (stat === undefined || !stat.isFile()) return null;
195
+ let text: string;
196
+ try {
197
+ text = fs.readFileSync(file, "utf-8");
198
+ } catch (err) {
199
+ const code = (err as NodeJS.ErrnoException).code;
200
+ if (code !== "EACCES" && code !== "EPERM") throw err;
201
+ return null;
202
+ } finally {
203
+ fs.rmSync(file, { force: true });
112
204
  }
113
- return null;
205
+ const fields = new Map<string, string>();
206
+ for (const line of text.split("\n")) {
207
+ const eq = line.indexOf("=");
208
+ if (eq > 0) fields.set(line.slice(0, eq), line.slice(eq + 1));
209
+ }
210
+ const lock = fields.get("lock");
211
+ const outcome = fields.get("outcome");
212
+ if (lock === undefined || outcome === undefined) return null;
213
+ return { lock, outcome, holder: fields.get("holder") ?? "" };
114
214
  }
115
215
 
116
- /** Classify only a tests-lock outcome, leaving gate and nested-lock failures intact. */
117
- export function classifyLockExit({
118
- exitCode,
119
- log,
120
- who,
121
- }: {
122
- exitCode: number;
123
- log: string;
124
- who: string;
125
- }): "gate" | "lock-wait" | "could-not-run" {
126
- const lines = log.split(/\r?\n/);
127
- if (exitCode === 75 && testsLockHolder(log, who) !== null) return "lock-wait";
128
- if (
129
- exitCode === 73 &&
130
- lines.some((line) =>
131
- /^\[machine-lock\] ❌ (?:could not take the lock for tests:|cannot take tests while holding )/.test(
132
- line,
133
- ),
134
- )
135
- )
136
- return "could-not-run";
216
+ /** `gate` the gate's own result, `lock-wait` the wait gave up, `could-not-run` the lock refused or stopped the run. */
217
+ export type LockOutcome = "gate" | "lock-wait" | "could-not-run";
218
+
219
+ /**
220
+ * Classify a wrapped gate's result from its exit code and the status file only. `exitCode`
221
+ * is null when a caller in between (git running a pre-push hook) collapsed the status, so
222
+ * the file alone decides. Anything but a tests-lock give-up, refusal or hold-limit stop is
223
+ * the gate's own.
224
+ */
225
+ export function classifyLockOutcome(
226
+ exitCode: number | null,
227
+ status: LockStatus | null,
228
+ ): LockOutcome {
229
+ if (status === null || status.lock !== "tests") return "gate";
230
+ const matches = (code: number) => exitCode === null || exitCode === code;
231
+ if (status.outcome === "gave-up" && matches(75)) return "lock-wait";
232
+ if (status.outcome === "refused" && matches(73)) return "could-not-run";
233
+ if (status.outcome === "held-too-long" && matches(124)) return "could-not-run";
137
234
  return "gate";
138
235
  }
139
236
 
@@ -141,6 +238,10 @@ export interface RunContext {
141
238
  /** Parsed flags, keyed by camelCase name. */
142
239
  flags: Record<string, FlagValue>;
143
240
  cwd: string;
241
+ /** Explicit publishing ownership; never inferred from another active run. */
242
+ publication?: { invocation: string; workflow: string };
243
+ /** The engine-issued invocation `--invocation` resolved and validated; absent without the flag. */
244
+ invocation?: Invocation;
144
245
  /** The global `--json` flag was given. Taken by every verb, never declared in a verb's spec. */
145
246
  json: boolean;
146
247
  /** Human-readable line on stderr, tagged `[bkit-<noun>]`. */
@@ -196,12 +297,12 @@ const camel = (kebab: string) => kebab.replace(/-([a-z0-9])/g, (_, c: string) =>
196
297
  const PLACEHOLDER = /\{[A-Z][A-Z0-9_]*\}/;
197
298
 
198
299
  /** Refuse a flag value still carrying a literal `{UPPER}` placeholder. */
199
- function refuseUnsubstituted(flag: string, value: string): void {
300
+ function refuseUnsubstituted(spec: FlagSpec, value: string): void {
200
301
  const hit = PLACEHOLDER.exec(value);
201
302
  if (hit) {
202
303
  throw new CommandError(
203
- EXIT.USAGE,
204
- `--${flag} carries the unsubstituted placeholder ${hit[0]} — substitute it before running`,
304
+ spec.placeholderExit ?? EXIT.USAGE,
305
+ `--${spec.name} carries the unsubstituted placeholder ${hit[0]} — substitute it before running`,
205
306
  );
206
307
  }
207
308
  }
@@ -210,7 +311,7 @@ function refuseUnsubstituted(flag: string, value: string): void {
210
311
  * Parse `--flag=value` / `--flag value` / `--bool` against the verb's spec. Keys
211
312
  * are filled in argv order, so a verb may render repeated or free-form flags in
212
313
  * the order the caller gave them. A value holding a literal `{UPPER}` placeholder
213
- * is refused (exit 2): the workflow passed it through unsubstituted.
314
+ * is refused (exit 2, or the flag's `placeholderExit`): the workflow passed it through unsubstituted.
214
315
  */
215
316
  export function parseFlags(argv: string[], specs: FlagSpec[]): Record<string, FlagValue> {
216
317
  const byName = new Map(specs.map((s) => [s.name, s]));
@@ -226,7 +327,7 @@ export function parseFlags(argv: string[], specs: FlagSpec[]): Record<string, Fl
226
327
  `unexpected argument "${arg}" — commands take flags only`,
227
328
  );
228
329
  }
229
- refuseUnsubstituted(positional.name, arg);
330
+ refuseUnsubstituted(positional, arg);
230
331
  out[key] = arg;
231
332
  continue;
232
333
  }
@@ -248,7 +349,7 @@ export function parseFlags(argv: string[], specs: FlagSpec[]): Record<string, Fl
248
349
  value = next;
249
350
  i++;
250
351
  }
251
- if (typeof value === "string") refuseUnsubstituted(name, value);
352
+ if (typeof value === "string") refuseUnsubstituted(spec, value);
252
353
  const key = camel(name);
253
354
  if (spec.repeatable) {
254
355
  const prior = out[key];
@@ -501,6 +602,220 @@ export function resolveActiveRun(opts: {
501
602
  return found.length === 1 ? found[0] : undefined;
502
603
  }
503
604
 
605
+ // ---------------------------------------------------------------------------
606
+ // Invocation context
607
+ // ---------------------------------------------------------------------------
608
+
609
+ /**
610
+ * The engine-issued identity of one workflow step or agent call. `bkit status invocation`
611
+ * issues it into the repository's private outbox; a verb that declares `INVOCATION_FLAG`
612
+ * receives it validated as `ctx.invocation`. Never inferred from the most recent run.
613
+ */
614
+ export interface Invocation {
615
+ id: string;
616
+ version: 1;
617
+ /** `run`: bound to one workflow run and its `status.jsonl`; `outbox`: a runless audit or utility call. */
618
+ scope: "run" | "outbox";
619
+ workflow: string | null;
620
+ step: string | null;
621
+ number: number | null;
622
+ title: string | null;
623
+ /** The workflow's run number at issuance; null for `outbox` scope. */
624
+ run: number | null;
625
+ statusPath: string | null;
626
+ bookRoot: string | null;
627
+ /** The task group a group-scoped step runs for (build); null otherwise. */
628
+ group: string | null;
629
+ /** The attempt of that group or of a remediation round; null otherwise. */
630
+ attempt: string | null;
631
+ agent: string | null;
632
+ host: string | null;
633
+ /** The pin the agent was launched with; never the model it ran on. */
634
+ configuredModel: string | null;
635
+ /** The model the host reported, or `unavailable`; null when none was asserted. */
636
+ observedModel: string | null;
637
+ /** `audit` or `utility` for an `outbox` scope call. */
638
+ standalone: string | null;
639
+ name: string | null;
640
+ /** `<standalone>:<name>` for an `outbox` call: the one step it declared; null for a run. */
641
+ declaredStep: string | null;
642
+ /** The only agent an `outbox` call may write as; null when it declared none. */
643
+ allowedAgent: string | null;
644
+ /** Git toplevel of the checkout that issued it; resolution is refused anywhere else. */
645
+ worktree: string;
646
+ issuedAt: string;
647
+ }
648
+
649
+ export const INVOCATION_FLAG: FlagSpec = {
650
+ name: "invocation",
651
+ type: "string",
652
+ help: "invocation id from `bkit status invocation`; must be issued by this checkout, and any --workflow, --step, --agent or --file given must agree with it",
653
+ };
654
+
655
+ const INVOCATION_ID = /^inv-[0-9a-f]{32}$/;
656
+
657
+ /** `<git common dir>/bkit-outbox/invocation-context`: one receipt per issued invocation. */
658
+ export function invocationDir(cwd: string): string | null {
659
+ const root = outboxRoot(cwd);
660
+ return root === null ? null : path.join(root, "invocation-context");
661
+ }
662
+
663
+ /** Persist an issued invocation; returns its receipt path. */
664
+ export function writeInvocation(cwd: string, inv: Invocation): string {
665
+ const dir = invocationDir(cwd);
666
+ if (dir === null) throw new CommandError(EXIT.USAGE, `not inside a git repository: ${cwd}`);
667
+ fs.mkdirSync(dir, { recursive: true });
668
+ const file = path.join(dir, `${inv.id}.json`);
669
+ fs.writeFileSync(file, `${JSON.stringify(inv)}\n`, { mode: 0o600, flag: "wx" });
670
+ return file;
671
+ }
672
+
673
+ /** A one-way fingerprint of a checkout's top: the committed `invocation` event never holds its path. */
674
+ export function worktreeFingerprint(top: string): string {
675
+ return createHash("sha256").update(top).digest("hex").slice(0, 16);
676
+ }
677
+
678
+ /**
679
+ * Whether `file` resolves, symlinks included, to a path inside the checkout `top` and not in
680
+ * a worktree nested under it. A file that does not exist yet resolves through its parent.
681
+ */
682
+ function resolvesInside(top: string, file: string): boolean {
683
+ try {
684
+ const realTop = fs.realpathSync(top);
685
+ let real: string;
686
+ if (fs.existsSync(file) || fs.lstatSync(file, { throwIfNoEntry: false }) !== undefined) {
687
+ real = fs.realpathSync(file);
688
+ } else {
689
+ real = path.join(fs.realpathSync(path.dirname(file)), path.basename(file));
690
+ }
691
+ if (real !== realTop && !real.startsWith(realTop + path.sep)) return false;
692
+ const owner = git(path.dirname(real), ["rev-parse", "--show-toplevel"]);
693
+ return owner === null || fs.realpathSync(owner) === realTop;
694
+ } catch {
695
+ return false;
696
+ }
697
+ }
698
+
699
+ /**
700
+ * Rebuild the outbox receipt of run-scoped invocation `id` from its `invocation` event in a
701
+ * `status.jsonl` under this checkout. Reads only this checkout's books, so another
702
+ * worktree's run is never found. Returns whether a receipt now exists.
703
+ */
704
+ function rebuildInvocation(cwd: string, id: string): boolean {
705
+ const top = git(cwd, ["rev-parse", "--show-toplevel"]);
706
+ if (top === null) return false;
707
+ let read = 0;
708
+ for (const month of subdirs(path.join(top, "docs", "plans"))) {
709
+ for (const fid of subdirs(path.join(top, "docs", "plans", month, "logs"))) {
710
+ if (++read > ACTIVE_RUN_SCAN_CAP) return false;
711
+ const statusPath = path.join(top, statusRelPath(month, fid));
712
+ if (!fs.existsSync(statusPath)) continue;
713
+ // A status file symlinked out of the checkout is not this checkout's book.
714
+ if (!resolvesInside(top, statusPath)) continue;
715
+ for (const line of fs.readFileSync(statusPath, "utf-8").split("\n")) {
716
+ if (!line.includes(id)) continue;
717
+ const row = parseJson(line);
718
+ if (!row.ok || !isInvocationEvent(row.value) || row.value.id !== id) continue;
719
+ const e = row.value;
720
+ // The event holds checkout-relative paths; they resolve against this top only.
721
+ if (e.worktree !== worktreeFingerprint(top) || path.join(top, e.statusPath) !== statusPath)
722
+ return false;
723
+ try {
724
+ writeInvocation(cwd, {
725
+ id,
726
+ version: 1,
727
+ scope: "run",
728
+ workflow: e.workflow,
729
+ step: e.step,
730
+ number: e.number,
731
+ title: e.title,
732
+ run: e.run,
733
+ statusPath,
734
+ bookRoot: path.join(top, e.bookRoot),
735
+ group: e.group,
736
+ attempt: e.attempt,
737
+ agent: e.agent,
738
+ host: e.host,
739
+ configuredModel: e.configuredModel,
740
+ observedModel: e.observedModel,
741
+ standalone: null,
742
+ name: null,
743
+ declaredStep: null,
744
+ allowedAgent: null,
745
+ worktree: top,
746
+ issuedAt: e.at,
747
+ });
748
+ } catch {
749
+ // A concurrent rebuild may already have written the receipt; report whether one exists.
750
+ const dir = invocationDir(cwd);
751
+ return dir !== null && fs.existsSync(path.join(dir, `${id}.json`));
752
+ }
753
+ return true;
754
+ }
755
+ }
756
+ }
757
+ return false;
758
+ }
759
+
760
+ /**
761
+ * Resolve `--invocation` against the outbox and refuse (exit 2) a forged, unissued,
762
+ * other-checkout or stale id, and any asserted `--workflow`, `--step`, `--agent` or
763
+ * `--file` that disagrees with it. A run-scoped id is stale once a newer run of its
764
+ * workflow has started.
765
+ */
766
+ export function resolveInvocation(
767
+ cwd: string,
768
+ id: string,
769
+ flags: Record<string, FlagValue>,
770
+ ): Invocation {
771
+ const refuse = (why: string): never => {
772
+ throw new CommandError(EXIT.USAGE, `invocation ${id}: ${why}`);
773
+ };
774
+ if (!INVOCATION_ID.test(id)) return refuse("not an id issued by `bkit status invocation`");
775
+ const dir = invocationDir(cwd);
776
+ const file = dir === null ? null : path.join(dir, `${id}.json`);
777
+ if (file === null) return refuse("not issued in this repository");
778
+ // The run's status log is the authority; a missing receipt is rebuilt from its event.
779
+ if (!fs.existsSync(file) && !rebuildInvocation(cwd, id))
780
+ return refuse("not issued in this repository");
781
+ const parsed = parseJson(fs.readFileSync(file, "utf-8"));
782
+ const inv = parsed.ok ? (parsed.value as Invocation | null) : null;
783
+ if (inv === null || typeof inv !== "object" || inv.id !== id || inv.version !== 1)
784
+ return refuse("receipt is unreadable");
785
+ const top = git(cwd, ["rev-parse", "--show-toplevel"]);
786
+ if (top === null || top !== inv.worktree)
787
+ return refuse(`issued in another checkout (${inv.worktree})`);
788
+ if (inv.scope === "run") {
789
+ if (inv.statusPath === null || inv.workflow === null || inv.run === null)
790
+ return refuse("run receipt lacks its status file");
791
+ if (!fs.existsSync(inv.statusPath)) return refuse(`stale: ${inv.statusPath} is gone`);
792
+ if (!resolvesInside(top, inv.statusPath))
793
+ return refuse(`${inv.statusPath} resolves outside this checkout`);
794
+ const events: StatusEvent[] = [];
795
+ for (const line of fs.readFileSync(inv.statusPath, "utf-8").split("\n")) {
796
+ const row = line.trim() === "" ? null : parseJson(line);
797
+ if (row?.ok && row.value !== null && typeof row.value === "object") {
798
+ const type = (row.value as { type?: unknown }).type;
799
+ if (typeof type === "string" && FOLD_TYPES.has(type)) events.push(row.value as StatusEvent);
800
+ }
801
+ }
802
+ const started = fold(events).filter((r) => r.workflow === inv.workflow).length;
803
+ if (started > inv.run) return refuse(`stale: a newer ${inv.workflow} run has started`);
804
+ if (started < inv.run - 1) return refuse("stale: its run is gone");
805
+ }
806
+ const text = (v: FlagValue) => (typeof v === "string" ? v : undefined);
807
+ const conflict = (flag: string, given: string, bound: string | null) =>
808
+ refuse(`conflict: --${flag}=${given} disagrees with the invocation (${bound ?? "none"})`);
809
+ for (const flag of ["workflow", "step", "agent"] as const) {
810
+ const given = text(flags[flag]);
811
+ if (given !== undefined && given !== inv[flag]) conflict(flag, given, inv[flag]);
812
+ }
813
+ const file2 = text(flags["file"]);
814
+ if (file2 !== undefined && path.resolve(cwd, file2) !== inv.statusPath)
815
+ conflict("file", file2, inv.statusPath);
816
+ return inv;
817
+ }
818
+
504
819
  /** The journal `runCommand` uses unless a caller injects one: writes into the active run's own books. */
505
820
  function engineJournal(): Journal {
506
821
  let resolved = false;
@@ -583,6 +898,24 @@ export async function runCommand(
583
898
  }
584
899
  const rest = argv.slice(2);
585
900
  if (rest.some(isHelp)) {
901
+ if (rest.includes("--json")) {
902
+ const s = cmd.verbs[verb]!;
903
+ io.stdout(
904
+ `${JSON.stringify({
905
+ noun: cmd.noun,
906
+ verb,
907
+ summary: s.summary,
908
+ flags: s.flags.map((f) => ({
909
+ name: f.name,
910
+ type: f.type,
911
+ required: f.required === true,
912
+ })),
913
+ output: s.output,
914
+ exitCodes: s.exitCodes ?? {},
915
+ })}\n`,
916
+ );
917
+ return EXIT.OK;
918
+ }
586
919
  io.stdout(verbHelp(cmd, verb));
587
920
  return EXIT.OK;
588
921
  }
@@ -626,9 +959,25 @@ export async function runCommand(
626
959
  }
627
960
  ctx.json = own.length !== rest.length;
628
961
  ctx.flags = parseFlags(own, spec.flags);
962
+ const invocationId = ctx.flags["invocation"];
963
+ if (
964
+ typeof invocationId === "string" &&
965
+ spec.flags.some((f) => f.name === INVOCATION_FLAG.name && f.unresolved !== true)
966
+ ) {
967
+ ctx.invocation = resolveInvocation(ctx.cwd, invocationId, ctx.flags);
968
+ }
629
969
  input = { noun: cmd.noun, verb, argv: rest, flags: ctx.flags, cwd: ctx.cwd };
630
970
  const entered = input;
631
- guarded(() => journal.call(entered));
971
+ // An invocation-bound call writes its engine-call row into the issuing run's own status
972
+ // log (never another worktree's); a runless call has no run to write to.
973
+ // `status invocation` records itself as the run's `invocation` event, so it adds no second row.
974
+ const bound = ctx.invocation;
975
+ const selfRecorded = cmd.noun === "status" && verb === "invocation";
976
+ if (bound === undefined && !selfRecorded) guarded(() => journal.call(entered));
977
+ else if (bound?.scope === "run" && bound.statusPath !== null) {
978
+ const own = { ...entered, flags: { ...entered.flags, file: bound.statusPath } };
979
+ guarded(() => journal.call(own));
980
+ }
632
981
  outcome = null;
633
982
  const code = await spec.run(ctx);
634
983
  outcome = code;
@@ -636,6 +985,8 @@ export async function runCommand(
636
985
  } catch (err) {
637
986
  if (!(err instanceof CommandError)) throw err;
638
987
  io.stderr(`${tag} ${err.message}\n`);
988
+ const structured = ctx.json ? structuredError(err) : null;
989
+ if (structured !== null) io.stdout(`${JSON.stringify({ error: structured })}\n`);
639
990
  outcome = err.code;
640
991
  return err.code;
641
992
  } finally {
@@ -723,7 +1074,7 @@ export function runTool(
723
1074
  cmd: string,
724
1075
  args: string[],
725
1076
  cwd: string,
726
- opts: { input?: string; env?: Record<string, string> } = {},
1077
+ opts: { input?: string; env?: Record<string, string>; timeoutMs?: number } = {},
727
1078
  ): ToolResult {
728
1079
  const res = spawnSync(cmd, args, {
729
1080
  cwd,
@@ -731,6 +1082,9 @@ export function runTool(
731
1082
  env: { ...gitEnv(), ...opts.env },
732
1083
  input: opts.input,
733
1084
  maxBuffer: OUTPUT_LIMIT,
1085
+ ...(opts.timeoutMs === undefined
1086
+ ? {}
1087
+ : { timeout: Math.max(1, Math.ceil(opts.timeoutMs)), killSignal: "SIGKILL" }),
734
1088
  });
735
1089
  if (res.error && res.pid === 0) {
736
1090
  return { found: false, status: 127, stdout: "", stderr: `${cmd} not found on PATH` };
@@ -766,8 +1120,9 @@ export function runGh(
766
1120
  args: string[],
767
1121
  input?: string,
768
1122
  env?: Record<string, string>,
1123
+ opts: { timeoutMs?: number } = {},
769
1124
  ): GhResult {
770
- const res = runTool("gh", args, cwd, { input, env });
1125
+ const res = runTool("gh", args, cwd, { input, env, ...opts });
771
1126
  return {
772
1127
  ok: res.found && res.status === 0,
773
1128
  stdout: res.stdout.trim(),
@@ -33,7 +33,7 @@ import { testsCommand } from "./workflow/tests.js";
33
33
  import { workflowsCommand } from "./workflow/workflows.js";
34
34
  import { worktreesCommand } from "./workflow/worktrees.js";
35
35
 
36
- export const COMMANDS: readonly CommandSpec[] = [
36
+ export const COMMANDS: CommandSpec[] = [
37
37
  statusCommand,
38
38
  countersCommand,
39
39
  stepsCommand,