@holmes-lab/holmes-kit 0.38.0 → 0.40.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 (308) hide show
  1. package/CHANGELOG.md +370 -6
  2. package/README.md +58 -40
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/admission/core/admission-policy.d.ts +37 -0
  5. package/dist/holmes/admission/core/admission-policy.js +147 -0
  6. package/dist/holmes/admission/core/bounded-reader.d.ts +56 -0
  7. package/dist/holmes/admission/core/bounded-reader.js +135 -0
  8. package/dist/holmes/admission/core/change-classifier.d.ts +34 -0
  9. package/dist/holmes/admission/core/change-classifier.js +278 -0
  10. package/dist/holmes/admission/core/config-loader.d.ts +30 -0
  11. package/dist/holmes/admission/core/config-loader.js +145 -0
  12. package/dist/holmes/admission/core/event-judgement.d.ts +37 -0
  13. package/dist/holmes/admission/core/event-judgement.js +251 -0
  14. package/dist/holmes/admission/core/path-rules.d.ts +35 -0
  15. package/dist/holmes/admission/core/path-rules.js +88 -0
  16. package/dist/holmes/admission/core/pin.d.ts +7 -0
  17. package/dist/holmes/admission/core/pin.js +29 -0
  18. package/dist/holmes/admission/core/ports.d.ts +48 -0
  19. package/dist/holmes/admission/core/ports.js +11 -0
  20. package/dist/holmes/admission/core/range-resolver.d.ts +32 -0
  21. package/dist/holmes/admission/core/range-resolver.js +51 -0
  22. package/dist/holmes/admission/core/self-containment.d.ts +1 -0
  23. package/dist/holmes/admission/core/self-containment.js +125 -0
  24. package/dist/holmes/admission/core/signature-source.d.ts +9 -0
  25. package/dist/holmes/admission/core/signature-source.js +4 -0
  26. package/dist/holmes/admission/core/transition-planner.d.ts +15 -0
  27. package/dist/holmes/admission/core/transition-planner.js +14 -0
  28. package/dist/holmes/admission/core/verdict.d.ts +38 -0
  29. package/dist/holmes/admission/core/verdict.js +17 -0
  30. package/dist/holmes/admission/core/wiring.d.ts +44 -0
  31. package/dist/holmes/admission/core/wiring.js +618 -0
  32. package/dist/holmes/admission/forge/git-object-port.d.ts +4 -0
  33. package/dist/holmes/admission/forge/git-object-port.js +132 -0
  34. package/dist/holmes/assoc/assoc-arm.d.ts +1 -1
  35. package/dist/holmes/assoc/assoc-arm.js +1 -1
  36. package/dist/holmes/cli/agents.d.ts +8 -0
  37. package/dist/holmes/cli/agents.js +9 -5
  38. package/dist/holmes/cli/approve-cli.d.ts +2 -0
  39. package/dist/holmes/cli/approve-cli.js +392 -0
  40. package/dist/holmes/cli/approve-ref.d.ts +13 -7
  41. package/dist/holmes/cli/approve-ref.js +30 -10
  42. package/dist/holmes/cli/approve-status.d.ts +26 -2
  43. package/dist/holmes/cli/approve-status.js +98 -18
  44. package/dist/holmes/cli/approve-watch.d.ts +5 -0
  45. package/dist/holmes/cli/approve-watch.js +10 -5
  46. package/dist/holmes/cli/approve.d.ts +50 -13
  47. package/dist/holmes/cli/approve.js +260 -67
  48. package/dist/holmes/cli/attest.js +2 -1
  49. package/dist/holmes/cli/autonomy.d.ts +4 -1
  50. package/dist/holmes/cli/autonomy.js +17 -10
  51. package/dist/holmes/cli/codex-oracle.d.ts +11 -0
  52. package/dist/holmes/cli/codex-oracle.js +5 -1
  53. package/dist/holmes/cli/codex-toml.d.ts +10 -0
  54. package/dist/holmes/cli/codex-toml.js +36 -2
  55. package/dist/holmes/cli/doctor-boundary.d.ts +76 -0
  56. package/dist/holmes/cli/doctor-boundary.js +308 -0
  57. package/dist/holmes/cli/doctor-locks.d.ts +15 -0
  58. package/dist/holmes/cli/doctor-locks.js +119 -0
  59. package/dist/holmes/cli/doctor.d.ts +2 -0
  60. package/dist/holmes/cli/doctor.js +45 -5
  61. package/dist/holmes/cli/flags.d.ts +23 -0
  62. package/dist/holmes/cli/flags.js +89 -0
  63. package/dist/holmes/cli/index.d.ts +5 -1
  64. package/dist/holmes/cli/index.js +206 -424
  65. package/dist/holmes/cli/init.js +33 -0
  66. package/dist/holmes/cli/lock-recover.d.ts +5 -0
  67. package/dist/holmes/cli/lock-recover.js +126 -0
  68. package/dist/holmes/cli/mcp-processes.d.ts +32 -0
  69. package/dist/holmes/cli/mcp-processes.js +132 -0
  70. package/dist/holmes/cli/release-docs.js +1 -1
  71. package/dist/holmes/cli/run-exec.d.ts +141 -0
  72. package/dist/holmes/cli/run-exec.js +1435 -0
  73. package/dist/holmes/cli/run-provision.d.ts +8 -0
  74. package/dist/holmes/cli/run-provision.js +325 -0
  75. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  76. package/dist/holmes/cli/run-wiring.js +270 -0
  77. package/dist/holmes/cli/run.d.ts +26 -0
  78. package/dist/holmes/cli/run.js +364 -83
  79. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  80. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  81. package/dist/holmes/cli/screen-safe.js +18 -756
  82. package/dist/holmes/config/config.d.ts +2 -0
  83. package/dist/holmes/config/config.js +5 -2
  84. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  85. package/dist/holmes/cpg/import-resolver.js +1 -1
  86. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  87. package/dist/holmes/governance/approval-decisions.js +29 -0
  88. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  89. package/dist/holmes/governance/approval-grants.js +612 -33
  90. package/dist/holmes/governance/approval-queue.d.ts +31 -0
  91. package/dist/holmes/governance/approval-queue.js +122 -11
  92. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  93. package/dist/holmes/governance/approval-spend.js +191 -0
  94. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  95. package/dist/holmes/governance/autonomous-shell.js +332 -0
  96. package/dist/holmes/governance/autonomy.d.ts +5 -0
  97. package/dist/holmes/governance/autonomy.js +16 -11
  98. package/dist/holmes/governance/constitution.d.ts +5 -0
  99. package/dist/holmes/governance/constitution.js +32 -12
  100. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  101. package/dist/holmes/governance/full-autonomy.js +103 -7
  102. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  103. package/dist/holmes/governance/harness-catalog.js +348 -0
  104. package/dist/holmes/governance/human-channel.d.ts +38 -0
  105. package/dist/holmes/governance/human-channel.js +49 -0
  106. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  107. package/dist/holmes/governance/install-manifest.js +160 -0
  108. package/dist/holmes/governance/ledger-rechain.js +2 -0
  109. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  110. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  111. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  112. package/dist/holmes/governance/ledger-store.js +186 -8
  113. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  114. package/dist/holmes/governance/provenance-chain.js +19 -4
  115. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  116. package/dist/holmes/governance/provenance-ledger.js +53 -18
  117. package/dist/holmes/governance/push-gate-runner.js +11 -7
  118. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  119. package/dist/holmes/governance/recorded-pairs.js +522 -0
  120. package/dist/holmes/governance/replica-id.d.ts +1 -1
  121. package/dist/holmes/governance/replica-id.js +1 -1
  122. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  123. package/dist/holmes/governance/spec-seam.js +587 -0
  124. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  125. package/dist/holmes/governance/spend-kinds.js +18 -0
  126. package/dist/holmes/governance/tool-actions.js +2 -0
  127. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  128. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  129. package/dist/holmes/guardrail/impact-gate.d.ts +1 -0
  130. package/dist/holmes/guardrail/impact-gate.js +1 -1
  131. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  132. package/dist/holmes/guardrail/line-continuation.js +39 -0
  133. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  134. package/dist/holmes/guardrail/operator-person.js +57 -11
  135. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  136. package/dist/holmes/guardrail/refusal-codes.js +70 -10
  137. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  138. package/dist/holmes/guardrail/risk-classifier.js +245 -15
  139. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  140. package/dist/holmes/guardrail/risk-gate.js +7 -34
  141. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  142. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  143. package/dist/holmes/guardrail/run-refusals.d.ts +6 -1
  144. package/dist/holmes/guardrail/run-refusals.js +36 -14
  145. package/dist/holmes/guardrail/run-stages.d.ts +10 -0
  146. package/dist/holmes/guardrail/run-stages.js +46 -6
  147. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  148. package/dist/holmes/guardrail/shell-words.js +24 -3
  149. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  150. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  151. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  152. package/dist/holmes/guardrail/write-target.js +26 -5
  153. package/dist/holmes/hooks/pre-tool-use.d.ts +105 -1
  154. package/dist/holmes/hooks/pre-tool-use.js +1167 -168
  155. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  156. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  157. package/dist/holmes/hooks/session-start.d.ts +5 -0
  158. package/dist/holmes/hooks/session-start.js +29 -1
  159. package/dist/holmes/hooks/stop.d.ts +23 -0
  160. package/dist/holmes/hooks/stop.js +88 -33
  161. package/dist/holmes/mcp/approval-adapters.js +3 -1
  162. package/dist/holmes/mcp/approval-commit.js +3 -2
  163. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  164. package/dist/holmes/mcp/approval-policy.js +3 -1
  165. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  166. package/dist/holmes/mcp/handlers/approval-ask.d.ts +14 -0
  167. package/dist/holmes/mcp/handlers/approval-ask.js +31 -6
  168. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  169. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  170. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  171. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  172. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  173. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  174. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  175. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  176. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  177. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  178. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  179. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  180. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  181. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  182. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  183. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  184. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  185. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  186. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  187. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  188. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  189. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  190. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  191. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  192. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  193. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  194. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  195. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  196. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  197. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  198. package/dist/holmes/mcp/handlers/test-execution.d.ts +1 -1
  199. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +5 -0
  200. package/dist/holmes/mcp/handlers/workspace-preflight.js +10 -2
  201. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  202. package/dist/holmes/mcp/handlers.d.ts +99 -79
  203. package/dist/holmes/mcp/handlers.js +93 -25
  204. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  205. package/dist/holmes/mcp/harness-attestation.js +325 -53
  206. package/dist/holmes/mcp/maintenance-analyze.d.ts +1 -1
  207. package/dist/holmes/mcp/maintenance-analyze.js +9 -9
  208. package/dist/holmes/mcp/maintenance-evidence.js +31 -2
  209. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  210. package/dist/holmes/mcp/server-staleness.d.ts +43 -0
  211. package/dist/holmes/mcp/server-staleness.js +158 -0
  212. package/dist/holmes/mcp/server.js +34 -9
  213. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  214. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  215. package/dist/holmes/mcp/tool-schemas.js +42 -2
  216. package/dist/holmes/project/act-root.d.ts +19 -0
  217. package/dist/holmes/project/act-root.js +100 -0
  218. package/dist/holmes/project/baseline.js +4 -3
  219. package/dist/holmes/project/bounded-group.d.ts +47 -0
  220. package/dist/holmes/project/bounded-group.js +140 -0
  221. package/dist/holmes/project/bounded-io.d.ts +50 -2
  222. package/dist/holmes/project/bounded-io.js +138 -6
  223. package/dist/holmes/project/change-source.js +2 -2
  224. package/dist/holmes/project/instance-id.d.ts +10 -0
  225. package/dist/holmes/project/instance-id.js +233 -0
  226. package/dist/holmes/project/machine-identity.d.ts +25 -0
  227. package/dist/holmes/project/machine-identity.js +133 -0
  228. package/dist/holmes/project/owned-lock.d.ts +84 -0
  229. package/dist/holmes/project/owned-lock.js +263 -0
  230. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  231. package/dist/holmes/project/plain-lock-fs.js +126 -0
  232. package/dist/holmes/project/request-lock.d.ts +85 -0
  233. package/dist/holmes/project/request-lock.js +459 -0
  234. package/dist/holmes/project/root.d.ts +12 -4
  235. package/dist/holmes/project/root.js +26 -7
  236. package/dist/holmes/project/run-records.d.ts +19 -0
  237. package/dist/holmes/project/run-records.js +94 -12
  238. package/dist/holmes/project/screen-text.d.ts +94 -0
  239. package/dist/holmes/project/screen-text.js +763 -0
  240. package/dist/holmes/project/spend-lock.d.ts +82 -0
  241. package/dist/holmes/project/spend-lock.js +413 -0
  242. package/dist/holmes/project/workspace-preflight.d.ts +5 -0
  243. package/dist/holmes/project/workspace-preflight.js +24 -1
  244. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  245. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  246. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  247. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  248. package/dist/holmes/review/confidence-calibration.js +1 -1
  249. package/dist/holmes/review/content-verify.js +1 -1
  250. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  251. package/dist/holmes/review/hop-ablation.js +5 -5
  252. package/dist/holmes/review/point-in-time-replay.js +12 -3
  253. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  254. package/dist/holmes/review/rank-diagnosis.js +1 -1
  255. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  256. package/dist/holmes/review/replay-corpus.js +25 -9
  257. package/dist/holmes/review/requirement-triage.js +2 -2
  258. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  259. package/dist/holmes/review/semantic-arm.js +3 -3
  260. package/dist/holmes/review/test-outcomes.js +3 -1
  261. package/dist/holmes/review/test-runner.d.ts +11 -0
  262. package/dist/holmes/review/test-runner.js +31 -10
  263. package/dist/holmes/review/test-selection-breadth.js +2 -2
  264. package/dist/holmes/review/verdicts.d.ts +109 -7
  265. package/dist/holmes/review/verdicts.js +653 -34
  266. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  267. package/dist/holmes/rtm/anchor-census.js +151 -0
  268. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  269. package/dist/holmes/rtm/anchor-ids.js +45 -2
  270. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  271. package/dist/holmes/rtm/comment-ranges.js +104 -0
  272. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  273. package/dist/holmes/rtm/counted-tests.js +63 -0
  274. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  275. package/dist/holmes/rtm/known-defects.js +1 -1
  276. package/dist/holmes/rtm/localize.js +1 -1
  277. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  278. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  279. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  280. package/dist/holmes/rtm/test-scope.js +166 -5
  281. package/dist/holmes/rtm/trace-gaps.js +1 -1
  282. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  283. package/dist/holmes/runtime/dispatch.js +12 -1
  284. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  285. package/dist/holmes/semantic/cloud-usage.js +1 -1
  286. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  287. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  288. package/dist/holmes/spec/approval-blockers.js +1 -1
  289. package/dist/holmes/spec/entity-store.d.ts +6 -1
  290. package/dist/holmes/spec/entity-store.js +16 -2
  291. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  292. package/dist/holmes/spec/entity-transaction.js +87 -170
  293. package/dist/holmes/spec/spec-store.d.ts +12 -6
  294. package/dist/holmes/spec/spec-store.js +4 -2
  295. package/dist/holmes/spec/spec-types.js +1 -1
  296. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  297. package/dist/holmes/spec/succession-guard.js +187 -0
  298. package/dist/holmes/spec/succession.d.ts +70 -0
  299. package/dist/holmes/spec/succession.js +171 -0
  300. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  301. package/docs/install-guide.md +9 -3
  302. package/docs/language-support.md +78 -0
  303. package/package.json +4 -3
  304. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  305. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  306. package/playbooks/publish/PLAYBOOK.md +45 -33
  307. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  308. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -37,7 +37,7 @@ exports.isBrokenPipe = void 0;
37
37
  exports.packageRoot = packageRoot;
38
38
  exports.main = main;
39
39
  exports.installPipeGuard = installPipeGuard;
40
- // @implements A-SPEC-704, A-SPEC-773, A-SPEC-770.11,A-SPEC-709, A-SPEC-734,A-SPEC-751, A-SPEC-752, A-SPEC-772.4, A-SPEC-779, A-SPEC-102.2, A-SPEC-774.20, A-SPEC-102.7, A-SPEC-779.2, A-SPEC-792.3
40
+ // @implements A-SPEC-794.59, A-SPEC-794.58, A-SPEC-794.55, A-SPEC-794.43, A-SPEC-794.42, A-SPEC-794.41, A-SPEC-794.36, A-SPEC-792.48, A-SPEC-792.49, A-SPEC-704, A-SPEC-773, A-SPEC-770.11,A-SPEC-709, A-SPEC-734,A-SPEC-751, A-SPEC-752, A-SPEC-772.4, A-SPEC-779, A-SPEC-102.2, A-SPEC-774.20, A-SPEC-102.7, A-SPEC-779.2, A-SPEC-792.3, A-SPEC-102.10, A-SPEC-102.12, A-SPEC-774.34, A-SPEC-794.30, A-SPEC-794.32, A-SPEC-794.33, A-SPEC-102.29, A-SPEC-102.30, A-SPEC-102.31
41
41
  // @implements A-SPEC-549.2
42
42
  // @implements A-SPEC-591, A-SPEC-626
43
43
  const cli_execution_1 = require("./cli-execution");
@@ -45,11 +45,12 @@ const cli_execution_1 = require("./cli-execution");
45
45
  // @implements A-SPEC-213
46
46
  // @implements A-SPEC-215
47
47
  const fs = __importStar(require("node:fs"));
48
- const os = __importStar(require("node:os"));
49
48
  const path = __importStar(require("node:path"));
50
49
  const init_1 = require("./init");
51
50
  const doctor_1 = require("./doctor");
51
+ const doctor_boundary_1 = require("./doctor-boundary");
52
52
  const colophon_1 = require("./colophon");
53
+ const human_channel_1 = require("../governance/human-channel");
53
54
  const bounded_io_1 = require("../project/bounded-io");
54
55
  /**
55
56
  * `holmes-kit` CLI entry — argv dispatch, hand-rolled (no new dependency).
@@ -87,14 +88,16 @@ const KNOWN_FLAGS = {
87
88
  attest: ['help', 'target', 'exclude', 'json', 'badge', 'readme'],
88
89
  // @implements A-SPEC-773 — the Holmes scratch root an agent may clean up on its own.
89
90
  scratch: ['help', 'new'],
91
+ // @implements A-SPEC-245.8 — the operator's recovery of the spend lock.
92
+ lock: ['help', 'target', 'confirm-holder-dead'],
90
93
  // @implements A-SPEC-774.10 — the role policy rewritten into the new vocabulary with equal verdicts.
91
94
  roles: ['help', 'target', 'dry-run'],
92
- run: ['help', 'target', 'worktree', 'engine', 'engine-arg', 'id', 'key', 'scope', 'to', 'why', 'accept-unknown-versions'], // @implements A-SPEC-774.17, A-SPEC-102.5, A-SPEC-781, A-SPEC-774.20
95
+ run: ['help', 'target', 'worktree', 'engine', 'engine-arg', 'id', 'key', 'scope', 'to', 'why', 'accept-unknown-versions', 'provision', 'open-network', 'review-rounds', 'strict-review', 'review-base'], // @implements A-SPEC-774.17, A-SPEC-102.5, A-SPEC-781, A-SPEC-774.20, A-SPEC-774.29, A-SPEC-102.10, A-SPEC-102.12
93
96
  review: ['help', 'target', 'base', 'head', 'verdict', 'finding', 'engine', 'model', 'session', 'strict', 'solid'], // @implements A-SPEC-102.2, A-SPEC-102.7
94
97
  skills: ['help', 'target'],
95
98
  ci: ['help', 'target', 'specs-dir', 'json'],
96
99
  serve: ['help', 'target', 'port'],
97
- approve: ['help', 'target', 'list', 'status', 'refusals', 'grant', 'deny', 'ask', 'revoke', 'withdraw', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms'], // A-SPEC-649: --revoke · A-SPEC-650: --status · A-SPEC-779.2: --withdraw
100
+ approve: ['help', 'target', 'list', 'status', 'refusals', 'grant', 'deny', 'ask', 'revoke', 'withdraw', 'reason', 'question', 'ttl', 'rationale', 'watch', 'poll-ms', 'all', 'stale-hours'], // A-SPEC-794.32: --all, --stale-hours (staleView read them; the table refused them) // A-SPEC-649: --revoke · A-SPEC-650: --status · A-SPEC-779.2: --withdraw
98
101
  ledger: ['help', 'target', 'ref', 'dry-run'],
99
102
  // @implements A-SPEC-477 — the human's opt-in act for the cloud semantic tier.
100
103
  'semantic-key': ['help'],
@@ -111,97 +114,9 @@ const KNOWN_FLAGS = {
111
114
  // the whole-CLI usage over it. This set is that exemption, kept declarative so a future self-help
112
115
  // command is one edit, not a dispatch-order gamble.
113
116
  const SELF_HELP_COMMANDS = new Set(['approve']);
114
- const APPROVE_USAGE = `holmes-kit approve — decide pending approval requests (HITL)
115
-
116
- interactive (TTY): per item [a] approve [e] approve with reason/duration [v] details [d] deny [q] ask [s] skip [A] approve all remaining
117
- --watch resident mode — decide as requests arrive, wait when the queue is empty (Ctrl-C to exit, --poll-ms <ms>)
118
- --list print the pending list only
119
- --status the whole picture: workspace, delegation, who asked and how risky, recent outcomes
120
- --grant <ref> issue a narrow grant for that request (--ttl <minutes>, --rationale <text>)
121
- ref = list number (1,2,…) | id | id prefix — no need to retype a long id
122
- --deny <id> --reason <text> deny — the reason rides the agent's next refusal
123
- --ask <id> --question <text> leave a question and hold — the agent relays it to the user
124
- --revoke <id> --reason <text> withdraw a live grant — the request must be decided again
125
- --withdraw <ref> --reason <text> the run that filed a request closes it (recorded as withdrawn, not denied)
126
- --target <dir> project root (default: current directory)
127
- `;
128
- class UnknownFlagError extends Error {
129
- }
130
- /**
131
- * Flags that take NO value. Declared, because the old parser stored the NEXT token as any flag's
132
- * value: `init --dry-run .` swallowed `.` into dry-run, the boolean read false, and the "show me
133
- * what you'd do" spelling performed a REAL write (round-3 HIGH; same class inverted --remove and
134
- * --force). A boolean flag must never consume a token.
135
- */
136
- // A-SPEC-251.1 (round 26): `yes` — `upgrade --yes` was refused as "--yes requires a value", so the non-interactive
137
- // upgrade its own guidance names could not run (measured).
138
- // A-SPEC-774.24: --accept-unknown-versions names its fields, so it is a value flag, not one of these.
139
- const BOOLEAN_FLAGS = new Set(['badge', 'readme', 'help', 'dry-run', 'no-mcp', 'remove', 'force', 'json', 'list', 'status', 'watch', 'autonomy', 'no-autonomy', 'yes', 'allow-push', 'allow-publish', 'no-architecture']); // `--revoke` stays a value flag: `approve --revoke <id>` // A-SPEC-650: --status
140
- /** @implements A-SPEC-770.11 — value flags whose value may be omitted; the handler supplies the default. */
141
- const OPTIONAL_VALUE_FLAGS = new Set(['refusals']);
142
- /** @implements A-SPEC-771.1 — value flags that may be given more than once. */
143
- const REPEATABLE_FLAGS = new Set(['limit', 'engine-arg', 'finding', 'scope']); // @implements A-SPEC-774.17 — one engine argument per flag; A-SPEC-102.2 — one finding id per flag
144
- function parseFlags(argv, known) {
145
- const flags = {};
146
- const positionals = [];
147
- for (let i = 0; i < argv.length; i++) {
148
- const a = argv[i];
149
- if (!a.startsWith('--')) {
150
- positionals.push(a);
151
- continue;
152
- }
153
- if (a === '--') {
154
- // The conventional options terminator. Naming it `unknown flag: --` was fail-closed but a
155
- // misdiagnosis (round-4) — this CLI takes no positionals that would need one.
156
- throw new UnknownFlagError("the '--' option terminator is not supported — this CLI takes flags only");
157
- }
158
- // GNU `--key=value` — refusing it as `unknown flag: --target=/path` was fail-closed but
159
- // misdiagnosed (round-3).
160
- let key = a.slice(2);
161
- let inline;
162
- const eq = key.indexOf('=');
163
- if (eq >= 0) {
164
- inline = key.slice(eq + 1);
165
- key = key.slice(0, eq);
166
- }
167
- if (known && !known.includes(key))
168
- throw new UnknownFlagError(`unknown flag: --${key}`);
169
- if (BOOLEAN_FLAGS.has(key)) {
170
- if (inline !== undefined)
171
- throw new UnknownFlagError(`--${key} takes no value`);
172
- flags[key] = true;
173
- continue;
174
- }
175
- // @implements A-SPEC-190 (round 7) — a repeated value flag silently took the LAST one:
176
- // `--target A --target B` acted on B while the operator was looking at A. 'Cannot decide is not
177
- // permission' applies to the operator's own contradiction too.
178
- if (Object.prototype.hasOwnProperty.call(flags, key)) {
179
- // @implements A-SPEC-771.1 — `--limit k=v` is the one flag that repeats by design (one limit per flag); the
180
- // values are joined with a newline, which no argv value carries, and split again by the autonomy command.
181
- if (REPEATABLE_FLAGS.has(key) && typeof flags[key] === 'string') {
182
- const more = inline !== undefined ? inline : (argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : undefined);
183
- if (more === undefined)
184
- throw new UnknownFlagError(`--${key} requires a value`);
185
- flags[key] = `${flags[key]}\n${more}`;
186
- continue;
187
- }
188
- throw new UnknownFlagError(`--${key} was given more than once — say it once, or the run acts on a directory you did not read`);
189
- }
190
- if (inline !== undefined) {
191
- flags[key] = inline;
192
- continue;
193
- }
194
- const next = argv[i + 1];
195
- if (next && !next.startsWith('--')) {
196
- flags[key] = next;
197
- i++;
198
- }
199
- else {
200
- flags[key] = true;
201
- }
202
- }
203
- return { flags, positionals };
204
- }
117
+ // @implements A-SPEC-245.18 — the flag reading lives in cli/flags.ts, which the gate's lock-recover judgement reads too
118
+ // @implements A-SPEC-190, A-SPEC-770.11, A-SPEC-771.1, A-SPEC-774.17 — this CLI's flags are read by those rules, through ./flags
119
+ const flags_1 = require("./flags");
205
120
  function readApproval() {
206
121
  const raw = process.env.HOLMES_APPROVAL;
207
122
  if (!raw)
@@ -229,7 +144,8 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
229
144
  --specs-dir <rel> spec directory (default: .ax/specs)
230
145
  --settings local|project which settings file to merge (default: local)
231
146
  --agent <list> also wire these harnesses (claude|antigravity|codex|all,
232
- comma-separated). Default: claude only.
147
+ comma-separated). Default: at a terminal, a menu with every harness
148
+ checked; otherwise claude and antigravity.
233
149
  --no-mcp skip .mcp.json / MCP server registration
234
150
  --matcher <str> override the PreToolUse matcher (escape hatch)
235
151
  --dry-run print the diff, write nothing
@@ -242,6 +158,8 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
242
158
  run init at a terminal WITHOUT --autonomy. Off is default;
243
159
  --no-autonomy keeps it off.
244
160
  --no-autonomy keep every spec approval human (default)
161
+ HOLMES_SKIP_MODEL_INSTALL=1 in the environment: skip the automatic BGE-M3 download init starts
162
+ (offline or CI); holmes-kit semantic-setup prepares it later
245
163
 
246
164
  holmes-kit ledger rechain re-chain forked ledger files against the committed mainline
247
165
  --target <dir> project to repair (default: cwd)
@@ -253,13 +171,18 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
253
171
  (no flags, TTY) interactive: [a]approve [e]approve-with-terms [v]details [d]deny [q]ask [s]skip [A]approve-all
254
172
  --list print the pending queue and exit
255
173
  --status workspace · delegation · per-request risk/run/subject · recent outcomes
256
- --grant <ref> [--ttl <min>] [--rationale <text>] mint the narrow grant for one request
257
- --deny <ref> --reason <text> record a denial the agent will see
258
- --ask <ref> --question <text> hold with a question the agent relays
259
- --revoke <id> --reason <text> withdraw a live grant (full id or unique prefix)
260
- --withdraw <ref> --reason <text> the filing run closes its own request (recorded withdrawn)
261
- <ref> list index (1,2,…), full id, or a unique id prefix
262
- --target <dir> project root (default: cwd)
174
+ --grant <id> [--ttl <min>] [--rationale <text>] mint the narrow grant for one request
175
+ --deny <id> --reason <text> record a denial the agent will see
176
+ --ask <id> --question <text> hold with a question the agent relays
177
+ --revoke <id> --reason <text> withdraw a live grant (live grants are listed by --status)
178
+ --withdraw <id> --reason <text> the filing run closes its own request (recorded withdrawn); a session's MCP server uses approval_withdraw
179
+ <id> the full id shown under a request, or a unique prefix of 8+ characters;
180
+ a list number names whatever row holds it when the command runs, so it is refused
181
+ --all | --stale-hours <h> show requests idle past 24 hours too | change that fold (0 turns it off);
182
+ every screen (--list, --status, --watch, the interactive one) folds alike;
183
+ the refusal log does not fold: its count keeps old refusals, which cannot be withdrawn;
184
+ --deny <id> closes one and lowers the --list footer's count
185
+ --target <dir> project root (default: the current directory's .ax project)
263
186
 
264
187
  holmes-kit run start|status|stop open, list and end an orchestrated run (JSON on stdout)
265
188
  start --worktree <dir> --engine claude|codex|agy [--engine-arg <a>]… [--scope <A-SPEC-id>]…
@@ -269,7 +192,10 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
269
192
  record, prints the headless command, HOLMES_RUN_ID and a one-time stop
270
193
  key; exit 3 if refused. --accept-unknown-versions hook,mcp starts
271
194
  despite those unreadable fields only, and records them; fields a
272
- harness cannot read by design (agy: hook, hook_build) are exempt
195
+ harness cannot read by design (agy: hook, hook_build) are exempt.
196
+ --open-network: the run's network is open (recorded and printed as
197
+ network open); without it run exec confines it to the engine's
198
+ service through its own proxy (network allowlist)
273
199
  stop --id <run_id> --key <stop_key> end the run (only the holder of the key can)
274
200
  transition --id <run_id> --to <stage> --key <stop_key> [--why <text>]
275
201
  move the run along its stage machine (ax.config.json stages);
@@ -283,7 +209,7 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
283
209
  and no open critical (with --strict, important) finding remains
284
210
  mrp --base <rev> --head <rev> the merge-ready package: spec chain, test evidence, verdict, missing
285
211
 
286
- holmes-kit autonomy status|on|off|delegate|revoke-delegation grant/end autonomous spec approval
212
+ holmes-kit autonomy status|on|off|delegate|revoke-delegation|full grant/end autonomous spec approval
287
213
  delegate --run <id> --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]
288
214
  run delegation for THIS workspace: hitl specs whose only reason is a
289
215
  listed grader rule seal on their own (never architecture-document,
@@ -292,7 +218,14 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
292
218
  on [--for 2h] self-drive low-risk specs this session (governance-critical still
293
219
  ask you); at a TTY it just asks, non-interactive needs HOLMES_APPROVAL
294
220
  off end it now (always free)
295
- --target <dir> project root (default: cwd)
221
+ --target <dir> project root (default: the current directory's .ax project)
222
+ holmes-kit autonomy full --scope <path> [--allow-push] [--allow-publish] [--no-architecture]
223
+ a user-level profile for every project under <path>: judgments it covers do not wait
224
+ for a person; spec staging still goes to a person's form, and push and publish are
225
+ refused unless their flag is given. Issued through the person's approval; issuing
226
+ again replaces every flag, so name each flag to keep
227
+ full --revoke [<scope>] end the profile (always free)
228
+ The hook is accident prevention: its forgery resistance is not verified.
296
229
 
297
230
  holmes-kit semantic-key set|unset|status manage the cloud semantic tier opt-in key
298
231
  holmes-kit semantic-setup install and verify the default local BGE-M3 model
@@ -301,11 +234,21 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
301
234
  Setting the key is consent to egress (spec prose, paths, symbol names sent externally).
302
235
 
303
236
  holmes-kit doctor [flags] diagnose the install
304
- holmes-kit report --message "<what happened>" [--harness <name>]
305
- write a redacted field report and print a prefilled issue link
306
237
  --target <dir> also verify that target's wiring points at this install
307
238
  --json machine-readable output
239
+ holmes-kit report --message "<what happened>" [--harness <name>]
240
+ write a redacted field report and print a prefilled issue link
241
+
242
+ holmes-kit ci [--target <dir>] [--specs-dir <rel>] [--json]
243
+ the headless governance gate for CI: lists violations, exit 1 when there is one
244
+ holmes-kit serve [--target <dir>] [--port <n>]
245
+ serve the local traceability dashboard
308
246
 
247
+ holmes-kit lock recover spend [--target <dir>] [--confirm-holder-dead]
248
+ the operator's recovery of the workspace spend lock: a live holder is refused; a holder
249
+ on another host or with an unknown boot needs --confirm-holder-dead; recorded in the ledger
250
+ holmes-kit lock recover request <req-id> [--target <dir>] [--confirm-holder-dead]
251
+ the same, for one approval request's lock
309
252
  holmes-kit scratch [--new <label>]
310
253
  print the Holmes scratch root, or make a fresh directory under it; the gate lets
311
254
  an agent rm -rf such a directory by its absolute path in every harness
@@ -331,20 +274,35 @@ const USAGE = `holmes-kit — deterministic ASE governance for a project
331
274
 
332
275
  holmes-kit --version | --help
333
276
  `;
334
- async function main(argv) {
277
+ async function main(argv, deps = {}) {
335
278
  installPipeGuard(); // @implements A-SPEC-262.1 — cover the shipped bin, not just direct entry (round-11)
336
279
  const cmd = argv[0];
337
280
  // @implements A-SPEC-190 (round 7) — `holmes-kit constructor` resolved through the prototype
338
281
  // chain to a truthy non-array and crashed with an unhandled TypeError instead of saying
339
282
  // 'unknown command' (same class the MCP boundary fixed in REQ-189).
340
283
  const knownFlagsFor = (c) => c !== undefined && Object.prototype.hasOwnProperty.call(KNOWN_FLAGS, c) ? KNOWN_FLAGS[c] : undefined;
284
+ // @implements A-SPEC-774.34 — `run exec` takes its engine command after `--`, the one place this CLI accepts it.
285
+ if (cmd === 'run' && argv[1] === 'exec') {
286
+ const dd = argv.indexOf('--');
287
+ let execFlags;
288
+ try {
289
+ ({ flags: execFlags } = (0, flags_1.parseFlags)(dd < 0 ? argv.slice(2) : argv.slice(2, dd), ['id', 'target', 'help']));
290
+ }
291
+ catch (e) {
292
+ process.stderr.write(`✗ ${e instanceof Error ? e.message : String(e)}\n`);
293
+ return 2;
294
+ }
295
+ const { runExec } = require('./run-exec');
296
+ const str = (k) => (typeof execFlags[k] === 'string' ? execFlags[k] : undefined);
297
+ return runExec({ id: str('id'), target: str('target') ? path.resolve(str('target')) : undefined, command: dd < 0 ? [] : argv.slice(dd + 1) }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
298
+ }
341
299
  let flags;
342
300
  let positionals;
343
301
  try {
344
- ({ flags, positionals } = parseFlags(argv.slice(1), knownFlagsFor(cmd)));
302
+ ({ flags, positionals } = (0, flags_1.parseFlags)(argv.slice(1), knownFlagsFor(cmd)));
345
303
  }
346
304
  catch (e) {
347
- if (e instanceof UnknownFlagError) {
305
+ if (e instanceof flags_1.UnknownFlagError) {
348
306
  // Named, because a typo is the thing the user has to fix and a nameless refusal sends them
349
307
  // nowhere (REQ-155).
350
308
  process.stderr.write(`${e.message}\n\n${USAGE}`);
@@ -360,9 +318,9 @@ async function main(argv) {
360
318
  // resolved to CWD and wired it silently (round-5 HIGH).
361
319
  // @implements A-SPEC-770.11 — an optional-value flag defaults where it is read (`--refusals` → 20 rows): the
362
320
  // `approve --refusals --target <root>` every refusal prints exited 2 here (measured 2026-10-17).
363
- if (OPTIONAL_VALUE_FLAGS.has(key) && v === true)
321
+ if (flags_1.OPTIONAL_VALUE_FLAGS.has(key) && v === true)
364
322
  continue;
365
- if (!BOOLEAN_FLAGS.has(key) && (v === true || (typeof v === 'string' && v.trim() === ''))) {
323
+ if (!flags_1.BOOLEAN_FLAGS.has(key) && (v === true || (typeof v === 'string' && v.trim() === ''))) {
366
324
  process.stderr.write(`--${key} requires a value\n\n${USAGE}`);
367
325
  return 2;
368
326
  }
@@ -373,8 +331,9 @@ async function main(argv) {
373
331
  : cmd === 'semantic-key' ? ['set', 'unset', 'status']
374
332
  : cmd === 'autonomy' ? ['status', 'on', 'off', 'delegate', 'revoke-delegation', 'full'] // @implements A-SPEC-771.1, A-SPEC-792.3
375
333
  : cmd === 'roles' ? ['migrate'] // @implements A-SPEC-774.10
376
- : cmd === 'run' ? ['start', 'status', 'stop', 'transition'] // @implements A-SPEC-774.17, A-SPEC-781
377
- : cmd === 'review' ? ['record', 'status', 'gate', 'mrp'] : []; // @implements A-SPEC-102.2, A-SPEC-102.6
334
+ : cmd === 'lock' ? ['recover', 'spend', 'request', ...positionals.filter((p) => /^req-[0-9a-f]{12}$/.test(p))] // @implements A-SPEC-245.8, A-SPEC-794.6
335
+ : cmd === 'run' ? ['start', 'status', 'stop', 'transition'] // @implements A-SPEC-774.17, A-SPEC-781
336
+ : cmd === 'review' ? ['record', 'status', 'gate', 'mrp'] : []; // @implements A-SPEC-102.2, A-SPEC-102.6
378
337
  const unexpected = positionals.filter((p) => !expected.includes(p));
379
338
  if (unexpected.length > 0) {
380
339
  const hint = fs.existsSync(unexpected[0]) ? ` — did you mean --target ${unexpected[0]}?` : '';
@@ -465,7 +424,13 @@ async function main(argv) {
465
424
  // path); the marker lives in the agent-write-protected .ax/state/, so a session cannot self-grant.
466
425
  if (cmd === 'autonomy') {
467
426
  const { runAutonomy, parseForMinutes, autonomyGrantGate } = await Promise.resolve().then(() => __importStar(require('./autonomy')));
468
- const root = path.resolve(typeof flags.target === 'string' ? flags.target : process.cwd());
427
+ const { actRoot, projectsUnder } = require('../project/act-root');
428
+ const root = actRoot(flags); // A-SPEC-102.30 — the one act root: the acts below and their guard take this value
429
+ // @implements A-SPEC-102.31 (low 9) — where a refused act files its request: the asking session's project (the working
430
+ // directory's, by actRoot), else the act's own; it was decided apart with resolveProjectRoot
431
+ const { isProjectDir } = require('../project/root');
432
+ const { printable } = require('../governance/harness-catalog');
433
+ const askingRoot = () => { const here = actRoot({}); return isProjectDir(here) ? here : root; };
469
434
  const forStr = typeof flags.for === 'string' ? flags.for : undefined;
470
435
  // @implements A-SPEC-771.1 — the delegation's own inputs ride through to the core; `--limit` may repeat.
471
436
  const str = (k) => (typeof flags[k] === 'string' ? flags[k] : undefined);
@@ -492,7 +457,7 @@ async function main(argv) {
492
457
  // `--revoke` alone, `--revoke <scope>` or `--revoke --scope <scope>` (it is a value flag shared with approve).
493
458
  if (flags.revoke !== undefined) {
494
459
  const revokeScope = typeof flags.revoke === 'string' ? flags.revoke.replace(/^~(?=$|\/)/, home) : scopeArg;
495
- const r = runAutonomyFull(home, { scope: revokeScope, revoke: true }, { now, actor: approval?.actor ?? 'operator' });
460
+ const r = runAutonomyFull(home, { scope: revokeScope, revoke: true }, { now, actor: (0, human_channel_1.ledgerActor)(approval?.actor ?? 'operator') }); // A-SPEC-792.26
496
461
  process[r.ok ? 'stdout' : 'stderr'].write(`${r.message}\n`);
497
462
  return r.exitCode;
498
463
  }
@@ -511,28 +476,70 @@ async function main(argv) {
511
476
  const fullFlags = { push: flags['allow-push'] === true, publish: flags['allow-publish'] === true, architecture: flags['no-architecture'] !== true };
512
477
  const { resolveApproval } = require('../governance/approval-grants');
513
478
  const { enqueueApprovalRequest } = require('../governance/approval-queue');
514
- const { resolveProjectRoot } = require('../project/root');
515
- let askRoot = root;
516
- try {
517
- const p = resolveProjectRoot(process.cwd());
518
- if (p.marker === '.ax')
519
- askRoot = p.root;
520
- }
521
- catch { /* the target's own project */ }
479
+ const askRoot = askingRoot(); // A-SPEC-102.31 — through actRoot, the one decision
522
480
  const v = fullProfileGate({ scope, askRoot, flags: fullFlags, now, envApproval: approval }, {
523
- guard: () => operatorActGuard('issuing a full autonomy profile'),
481
+ // A-SPEC-102.30 — the union of what the profile covers: the scope's project, the working directory's, every
482
+ // project under the scope (a scope above a project skipped its additions); a search it cannot finish refuses
483
+ guard: () => {
484
+ let roots;
485
+ try {
486
+ roots = [scope, root, actRoot({}), ...projectsUnder(scope)];
487
+ }
488
+ catch (e) {
489
+ // A-SPEC-102.31 (low 5) — the scope and the error are the file system's text: escaped
490
+ return `issuing a full autonomy profile is the operator's — the projects under ${printable(scope)} could not be searched (${printable(e.message)}), so their additions cannot be judged.`;
491
+ }
492
+ return operatorActGuard('issuing a full autonomy profile', roots);
493
+ },
524
494
  resolve: (r, env, action, n) => resolveApproval(r, env, action, n),
525
495
  enqueue: (r, req) => { enqueueApprovalRequest(r, req); },
526
496
  });
497
+ // @implements A-SPEC-245.25 (item 1) — each refusal line names its code: the message carries the agent's --scope
527
498
  if (!v.proceed) {
528
- process.stderr.write(`${withRefusalLine(v.message)}\n`);
499
+ process.stderr.write(`${withRefusalLine(v.message, 'grant.operator-only')}\n`);
500
+ return 2;
501
+ }
502
+ // @implements A-SPEC-245.4 — the act runs inside the grant's claim: committed when it succeeds, returned otherwise
503
+ const { claimGrant, spendGrantApprovals, GrantSpendRefusal } = require('../governance/approval-grants');
504
+ const fullClaim = v.spend !== undefined ? claimGrant(askRoot, v.spend) : undefined;
505
+ if (fullClaim === null) {
506
+ process.stderr.write(`${withRefusalLine('the approval grant for this full autonomy profile is in use by another act — nothing was issued; retry', 'grant.in-use')}\n`);
529
507
  return 2;
530
508
  }
531
- const r = runAutonomyFull(home, { scope, flags: fullFlags, revoke: false }, { now, actor: v.approval?.actor ?? 'operator' });
532
- if (r.ok && v.spend !== undefined) {
533
- const { consumeGrantFile } = require('../governance/approval-grants');
534
- consumeGrantFile(askRoot, v.spend);
509
+ // @implements A-SPEC-245.9 (1b-1) — the grant's row once across replicas, then the profile
510
+ let fullSpent = false; // A-SPEC-245.16 (item 3): once spent, the grant is committed whatever follows
511
+ const fullSpend = fullClaim && v.approval ? () => { spendGrantApprovals(askRoot, [v.approval], `autonomy full ${scope}`); fullSpent = true; } : undefined;
512
+ let r;
513
+ try {
514
+ r = runAutonomyFull(home, { scope, flags: fullFlags, revoke: false }, { now, actor: (0, human_channel_1.ledgerActor)(v.approval?.actor ?? 'operator'), beforeWrite: fullSpend });
515
+ } // A-SPEC-792.26
516
+ catch (e) {
517
+ if (fullSpent) {
518
+ try {
519
+ fullClaim?.commit();
520
+ }
521
+ catch (c) {
522
+ process.stderr.write(`[Holmes-Kit] ${c.message}\n`);
523
+ }
524
+ }
525
+ else
526
+ fullClaim?.release();
527
+ if (e instanceof GrantSpendRefusal) {
528
+ process.stderr.write(`${withRefusalLine(`full autonomy was not issued: ${e.message}`, 'approval.required')}\n`);
529
+ return 2;
530
+ }
531
+ throw e;
532
+ }
533
+ if (r.ok || fullSpent) {
534
+ try {
535
+ fullClaim?.commit();
536
+ }
537
+ catch (e) {
538
+ process.stderr.write(`[Holmes-Kit] ${e.message}\n`);
539
+ }
535
540
  }
541
+ else
542
+ fullClaim?.release();
536
543
  process[r.ok ? 'stdout' : 'stderr'].write(`${r.message}\n`);
537
544
  return r.exitCode;
538
545
  }
@@ -541,23 +548,16 @@ async function main(argv) {
541
548
  // request in the asking session's project (where approval_ask finds it), and the retry spends the grant.
542
549
  const { resolveApproval } = require('../governance/approval-grants');
543
550
  const { enqueueApprovalRequest } = require('../governance/approval-queue');
544
- const { resolveProjectRoot } = require('../project/root');
545
- let askRoot = root;
546
- try {
547
- const p = resolveProjectRoot(process.cwd());
548
- if (p.marker === '.ax')
549
- askRoot = p.root;
550
- }
551
- catch { /* the target's own project */ }
551
+ const askRoot = askingRoot(); // A-SPEC-102.31 — through actRoot, the one decision
552
552
  const v = autonomyGrantGate({ root, askRoot, mins: minutes, now, envApproval: approval }, {
553
- guard: () => operatorActGuard('enabling session autonomy'),
553
+ guard: () => operatorActGuard('enabling session autonomy', root), // A-SPEC-102.29 — the project the act enables
554
554
  resolve: (r, env, action, n) => resolveApproval(r, env, action, n),
555
555
  enqueue: (r, req) => { enqueueApprovalRequest(r, req); },
556
556
  });
557
557
  if (!v.proceed) {
558
- process.stderr.write(`${withRefusalLine(v.message)}\n`);
558
+ process.stderr.write(`${withRefusalLine(v.message, 'grant.operator-only')}\n`);
559
559
  return 2;
560
- }
560
+ } // A-SPEC-245.25
561
561
  effective = v.approval;
562
562
  if (v.spend !== undefined)
563
563
  spend = { root: askRoot, nonce: v.spend };
@@ -565,22 +565,59 @@ async function main(argv) {
565
565
  else if (sub === 'delegate') {
566
566
  const { approvalCovers } = require('../guardrail/risk-gate');
567
567
  if (!approvalCovers(approval, { kind: 'autonomy-grant', target: root }, now)) {
568
- const why = operatorActGuard('issuing a run delegation');
568
+ const why = operatorActGuard('issuing a run delegation', root); // A-SPEC-102.29 — the project it delegates
569
569
  if (why !== null) {
570
- process.stderr.write(`${withRefusalLine(why)}\n`);
570
+ process.stderr.write(`${withRefusalLine(why, 'grant.operator-only')}\n`);
571
571
  return 2;
572
+ } // A-SPEC-245.25
573
+ }
574
+ }
575
+ // @implements A-SPEC-245.4 — the act runs inside the grant's claim: committed when it succeeds, returned otherwise
576
+ const { claimGrant, spendGrantApprovals, GrantSpendRefusal } = require('../governance/approval-grants');
577
+ const onClaim = spend !== undefined ? claimGrant(spend.root, spend.nonce) : undefined;
578
+ if (onClaim === null) {
579
+ process.stderr.write(`${withRefusalLine('the approval grant for this autonomy grant is in use by another act — nothing was enabled; retry', 'grant.in-use')}\n`);
580
+ return 2;
581
+ }
582
+ // @implements A-SPEC-245.9 (1b-1) — the grant's row once across replicas, then the marker
583
+ let onSpent = false; // A-SPEC-245.16 (item 3)
584
+ const onSpend = onClaim && spend && effective ? () => { spendGrantApprovals(spend.root, [effective], `autonomy on ${root}`); onSpent = true; } : undefined;
585
+ let r;
586
+ try {
587
+ r = runAutonomy(root, sub, forStr, {
588
+ now,
589
+ isTTY: !!process.stdin.isTTY && !!process.stdout.isTTY,
590
+ approval: effective,
591
+ beforeWrite: onSpend,
592
+ }, extra);
593
+ }
594
+ catch (e) {
595
+ if (onSpent) {
596
+ try {
597
+ onClaim?.commit();
572
598
  }
599
+ catch (c) {
600
+ process.stderr.write(`[Holmes-Kit] ${c.message}\n`);
601
+ }
602
+ }
603
+ else
604
+ onClaim?.release();
605
+ if (e instanceof GrantSpendRefusal) {
606
+ process.stderr.write(`${withRefusalLine(`session autonomy was not enabled: ${e.message}`, 'approval.required')}\n`);
607
+ return 2;
573
608
  }
609
+ throw e;
574
610
  }
575
- const r = runAutonomy(root, sub, forStr, {
576
- now,
577
- isTTY: !!process.stdin.isTTY && !!process.stdout.isTTY,
578
- approval: effective,
579
- }, extra);
580
- if (r.ok && spend !== undefined) {
581
- const { consumeGrantFile } = require('../governance/approval-grants');
582
- consumeGrantFile(spend.root, spend.nonce);
611
+ if (r.ok || onSpent) {
612
+ try {
613
+ onClaim?.commit();
614
+ }
615
+ catch (e) {
616
+ process.stderr.write(`[Holmes-Kit] ${e.message}\n`);
617
+ }
583
618
  }
619
+ else
620
+ onClaim?.release();
584
621
  process[r.ok ? 'stdout' : 'stderr'].write(`${r.message}\n`);
585
622
  return r.exitCode;
586
623
  });
@@ -632,6 +669,12 @@ async function main(argv) {
632
669
  engineArgs: str('engine-arg')?.split('\n'), id: str('id'), key: str('key'), scope: str('scope')?.split('\n'), to: str('to'), why: str('why'),
633
670
  // @implements A-SPEC-774.20 — start despite unreadable versions; run start records which.
634
671
  ...(acceptParsed !== null ? { acceptUnknownVersions: acceptParsed.fields } : {}),
672
+ ...(flags.provision === true ? { provision: true } : {}), // @implements A-SPEC-774.29
673
+ ...(flags['open-network'] === true ? { openNetwork: true } : {}), // @implements A-SPEC-774.52
674
+ // @implements A-SPEC-102.10 — the run's review policy, validated by run start.
675
+ ...(str('review-rounds') !== undefined ? { reviewRounds: str('review-rounds') } : {}),
676
+ ...(flags['strict-review'] === true ? { strictReview: true } : {}),
677
+ ...(str('review-base') !== undefined ? { reviewBase: str('review-base') } : {}), // @implements A-SPEC-102.12
635
678
  }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
636
679
  }
637
680
  // @implements A-SPEC-102.2 — review verdicts for callers that are not MCP clients.
@@ -652,6 +695,11 @@ async function main(argv) {
652
695
  const { runRoles } = require('./roles');
653
696
  return runRoles(positionals[0], { target: typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd(), dryRun: flags['dry-run'] === true }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
654
697
  }
698
+ if (cmd === 'lock') {
699
+ // @implements A-SPEC-245.10 — the handler is cli/lock-recover.ts; this only dispatches
700
+ const { runLockRecover } = require('./lock-recover');
701
+ return runLockRecover(positionals, flags, { stdout: (s) => process.stdout.write(s), stderr: (s) => process.stderr.write(s) });
702
+ }
655
703
  if (cmd === 'scratch') {
656
704
  const { runScratch } = require('./scratch');
657
705
  return runScratch({ label: typeof flags.new === 'string' ? flags.new : undefined }, { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) });
@@ -682,7 +730,9 @@ async function main(argv) {
682
730
  return 2;
683
731
  }
684
732
  const checks = await (0, doctor_1.runDoctor)(packageRoot(), typeof flags.target === 'string' ? path.resolve(flags.target) : undefined, { agent: flags.agent,
685
- runtimeRegistryPath: typeof flags.registry === 'string' ? path.resolve(flags.registry) : undefined });
733
+ runtimeRegistryPath: typeof flags.registry === 'string' ? path.resolve(flags.registry) : undefined,
734
+ // @implements A-SPEC-792.48 (H3), A-SPEC-792.49 — only the doctor command reads the forge, and a caller can say null
735
+ forge: deps.forge === undefined ? doctor_boundary_1.realForgeDeps : deps.forge });
686
736
  process.stdout.write(flags.json ? (0, doctor_1.checksJson)(checks) + '\n' : (0, doctor_1.formatChecks)(checks) + '\n');
687
737
  return checks.some((c) => c.level === 'FAIL') ? 1 : 0;
688
738
  }
@@ -1096,277 +1146,9 @@ async function main(argv) {
1096
1146
  }
1097
1147
  return failed === 0 ? 0 : 1;
1098
1148
  }
1099
- // @implements A-SPEC-215
1100
- if (cmd === 'approve') {
1101
- // @implements A-SPEC-246 — the surface where a human decides. Interactive on a TTY with no
1102
- // decision flags; every interactive decision has a flag equivalent so a CI or remote operator
1103
- // is never locked out.
1104
- const { grantRequest, denyRequest, holdRequest, renderPending, renderNonTtyHint, runInteractive, decisionSubject, decisionDetail } = require('./approve');
1105
- const { readQueue } = require('../governance/approval-queue');
1106
- // @implements A-SPEC-262.1 — the flag path speaks the SAME grammar as the screen: an index, an
1107
- // exact id, or a unique prefix. A remote operator decides here, so an ambiguous reference must
1108
- // refuse by name here too — never resolve to "probably this one".
1109
- const { resolveRequestRef } = require('./approve-ref');
1110
- // The SUBJECT travels with the id: every decision line names what it acted on, so an index that
1111
- // resolved against a queue that shifted since `--list` is visible on the screen (round-1).
1112
- // The detail row travels with it: round-5 measured the one-line form at 81 columns, so the flag
1113
- // path prints the same two rows the screen does — subject read, id acted on.
1114
- const resolveRef = (ref) => {
1115
- // @implements A-SPEC-576.1 — the grammar decides which queue the reference is resolved against.
1116
- // A NUMBER is an index into the list the operator was just shown, so it must resolve against
1117
- // the same filtered list or `--grant 3` would act on a row nobody saw. An ID or prefix is the
1118
- // operator naming a specific request — including a `shell` refusal they approved out of band
1119
- // (A-SPEC-563.2), which the inbox filter hides from the list but must never make ungrantable.
1120
- // @implements A-SPEC-690 — `includeAllKinds` only unfilters KINDS inside the tracked queue;
1121
- // a shell refusal is not in that file at all (A-SPEC-563.1 routes it to this machine's
1122
- // refusal log). So the id/prefix path failed here, before approve.ts's refusal-log fallback
1123
- // could ever run — making the very id the refusal printed ungrantable, which the comment
1124
- // above says must never happen. The NUMBER path is untouched: an index must mean the row the
1125
- // operator was shown.
1126
- const byIndex = /^\d+$/.test(ref.trim());
1127
- const { grantableRequests } = require('../governance/approval-queue');
1128
- const r = resolveRequestRef(byIndex ? readQueue(root).pending : grantableRequests(root), ref);
1129
- return r.ok ? { id: r.entry.id, subject: (prefix) => decisionSubject(r.entry, prefix), detail: (tail) => decisionDetail(r.entry, tail) } : { refusal: r.reason };
1130
- };
1131
- const root = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();
1132
- const actor = (() => { try {
1133
- return os.userInfo().username || 'operator';
1134
- }
1135
- catch {
1136
- return 'operator';
1137
- } })();
1138
- // @implements A-SPEC-779.4 — the granting acts (a grant, the two screens that grant) are a person's, never an
1139
- // agent's own shell; a denial, a revocation, a question and the read-only views grant nothing and stay open.
1140
- const operatorRefusal = (act) => require('../guardrail/operator-person').operatorActGuard(act);
1141
- const refuseOperatorAct = (act) => {
1142
- const why = operatorRefusal(act);
1143
- if (why === null)
1144
- return false;
1145
- const { withRefusalLine } = require('../guardrail/refusal-codes');
1146
- process.stdout.write(`${withRefusalLine(`✗ ${why}`)}\n`);
1147
- return true;
1148
- };
1149
- if (flags.help) {
1150
- process.stdout.write(APPROVE_USAGE);
1151
- return 0;
1152
- }
1153
- return (0, cli_execution_1.runOperatorExecution)(root, async () => {
1154
- if (typeof flags.grant === 'string') {
1155
- const opts = { actor };
1156
- if (typeof flags.ttl === 'string')
1157
- opts.ttlMinutes = Number(flags.ttl);
1158
- if (typeof flags.rationale === 'string')
1159
- opts.rationale = flags.rationale;
1160
- const ref = resolveRef(flags.grant);
1161
- if ('refusal' in ref) {
1162
- process.stdout.write(`\u2717 ${ref.refusal}\n`);
1163
- return 1;
1164
- }
1165
- // @implements A-SPEC-779 \u2014 never from inside a run; a run's awaited request only from a terminal.
1166
- const { grantGuard } = require('../guardrail/run-refusals');
1167
- // @implements A-SPEC-779.4 \u2014 and never from a process an agent harness started.
1168
- const guarded = operatorRefusal(`a grant of ${ref.id}`)
1169
- ?? grantGuard(root, ref.id, { env: process.env, interactive: process.stdin.isTTY === true && process.stdout.isTTY === true });
1170
- if (guarded !== null) {
1171
- // @implements A-SPEC-779.1 \u2014 the refusal carries its envelope, so an orchestrator reads its class.
1172
- const { withRefusalLine } = require('../guardrail/refusal-codes');
1173
- process.stdout.write(`${withRefusalLine(`\u2717 ${guarded}`)}\n`);
1174
- return 1;
1175
- }
1176
- const r = grantRequest(root, ref.id, opts);
1177
- process.stdout.write(r.ok ? `✓ approved — ${ref.subject('✓ approved — ')}\n${ref.detail(`valid until ${r.expires}`)}\n` : `✗ ${r.reason}\n`);
1178
- return r.ok ? 0 : 1;
1179
- }
1180
- if (typeof flags.deny === 'string') {
1181
- const reason = typeof flags.reason === 'string' ? flags.reason.trim() : '';
1182
- if (reason === '') {
1183
- process.stderr.write('✗ --deny requires --reason — a denial with no reason is invisible to the agent\n');
1184
- return 1;
1185
- }
1186
- const ref = resolveRef(flags.deny);
1187
- if ('refusal' in ref) {
1188
- process.stdout.write(`\u2717 ${ref.refusal}\n`);
1189
- return 1;
1190
- }
1191
- const r = denyRequest(root, ref.id, reason, actor);
1192
- process.stdout.write(r.ok ? `✓ denied — ${ref.subject('✓ denied — ')}\n${ref.detail('the denial was recorded')}\n` : `✗ ${r.reason}\n`);
1193
- return r.ok ? 0 : 1;
1194
- }
1195
- // @implements A-SPEC-779.2 — the requester's own close: only the run that filed it, recorded as `withdrawn`.
1196
- if (typeof flags.withdraw === 'string') {
1197
- const reason = typeof flags.reason === 'string' ? flags.reason.trim() : '';
1198
- if (reason === '') {
1199
- process.stderr.write('✗ --withdraw requires --reason — it is what the operator reads in place of a decision\n');
1200
- return 1;
1201
- }
1202
- const { withdrawRequest } = require('./approve');
1203
- const ref = resolveRef(flags.withdraw);
1204
- if ('refusal' in ref) {
1205
- process.stdout.write(`✗ ${ref.refusal}\n`);
1206
- return 1;
1207
- }
1208
- const r = withdrawRequest(root, ref.id, reason, { env: process.env, cwd: process.cwd() });
1209
- process.stdout.write(r.ok ? `↩ withdrawn — ${ref.subject('↩ withdrawn — ')}\n${ref.detail('withdrawn by its run')}\n` : `✗ ${r.reason}\n`);
1210
- return r.ok ? 0 : 1;
1211
- }
1212
- // @implements A-SPEC-649 — the operator withdraws a live grant. A granted id is no longer
1213
- // pending, so it resolves against the DECIDED ids (full id or a unique prefix), never a list index.
1214
- if (typeof flags.revoke === 'string') {
1215
- const reason = typeof flags.reason === 'string' ? flags.reason.trim() : '';
1216
- if (reason === '') {
1217
- process.stderr.write('✗ --revoke requires --reason — a revocation with no reason is invisible to the agent\n');
1218
- return 1;
1219
- }
1220
- const { revokeGrant } = require('./approve');
1221
- const ref = String(flags.revoke).trim();
1222
- const granted = Object.entries(readQueue(root, { includeAllKinds: true }).decisions).filter(([, d]) => d.event === 'granted').map(([id]) => id);
1223
- const matches = granted.includes(ref) ? [ref] : granted.filter((id) => id.startsWith(ref));
1224
- if (matches.length !== 1) {
1225
- process.stdout.write(`\u2717 ${matches.length === 0 ? `no granted request matches ${ref}` : `${ref} matches ${matches.length} granted requests — use the full id`}\n`);
1226
- return 1;
1227
- }
1228
- const r = revokeGrant(root, matches[0], reason, actor);
1229
- process.stdout.write(r.ok ? `✓ revoked — ${matches[0]}\n the grant is withdrawn; the agent's next attempt is refused and re-filed\n` : `✗ ${r.reason}\n`);
1230
- return r.ok ? 0 : 1;
1231
- }
1232
- if (typeof flags.ask === 'string') {
1233
- const question = typeof flags.question === 'string' ? flags.question.trim() : '';
1234
- if (question === '') {
1235
- process.stderr.write('✗ --ask requires --question\n');
1236
- return 1;
1237
- }
1238
- const ref = resolveRef(flags.ask);
1239
- if ('refusal' in ref) {
1240
- process.stdout.write(`\u2717 ${ref.refusal}\n`);
1241
- return 1;
1242
- }
1243
- const r = holdRequest(root, ref.id, question, actor);
1244
- process.stdout.write(r.ok ? `✓ held — ${ref.subject('✓ held — ')}\n${ref.detail('the question rides the next refusal')}\n` : `✗ ${r.reason}\n`);
1245
- return r.ok ? 0 : 1;
1246
- }
1247
- // @implements A-SPEC-507.1 — stale folding is a LIST-VIEW judgment: the clock enters only
1248
- // here, never on gate-path folds. `--stale-hours 0` disables it; `--all` unfolds.
1249
- const { staleView } = require('./approve');
1250
- const stale = staleView(flags);
1251
- const queueOpts = stale ? { now: Date.now(), ttlMs: stale.ttlMs } : undefined;
1252
- const listView = stale ? { staleHours: stale.ttlMs / 3_600_000, showAll: stale.showAll } : undefined;
1253
- if (flags.list) {
1254
- // @implements A-SPEC-770 — the list ends with the count of refusals outside it.
1255
- const { refusalsOutsideInbox } = require('../governance/approval-queue');
1256
- process.stdout.write(renderPending(readQueue(root, queueOpts), listView, refusalsOutsideInbox(root), root) + '\n'); // @implements A-SPEC-770.2
1257
- return 0;
1258
- }
1259
- // @implements A-SPEC-650 — the whole picture, read-only; the list above stays script-clean.
1260
- if (flags.status) {
1261
- const { renderStatus, statusContext } = require('./approve-status');
1262
- process.stdout.write(renderStatus(readQueue(root), statusContext(root)) + '\n');
1263
- return 0;
1264
- }
1265
- // @implements A-SPEC-563.2 — the read-only refusal view (local log; raw targets stay on-screen).
1266
- if (flags.refusals !== undefined) {
1267
- const { renderRefusals } = require('./approve');
1268
- const { readRefusals } = require('../governance/approval-queue');
1269
- const limit = typeof flags.refusals === 'string' ? Number(flags.refusals) : 20;
1270
- if (!Number.isInteger(limit) || limit <= 0) {
1271
- process.stderr.write(`✗ --refusals expects a positive integer count — received: ${flags.refusals}\n`);
1272
- return 1;
1273
- }
1274
- process.stdout.write(renderRefusals(readRefusals(root), limit, root) + '\n'); // @implements A-SPEC-770.2
1275
- return 0;
1276
- }
1277
- // @implements A-SPEC-262.2 — the RESIDENT surface. Validate --poll-ms first (so a bad value is
1278
- // named even on a non-TTY), then refuse a non-TTY (a resident interactive loop needs a terminal),
1279
- // then run the loop. SIGINT and readline close both abort it — the operator leaving, either way,
1280
- // ends the watch at once and exit 0; pending items stay in the queue.
1281
- if (flags.watch === true) {
1282
- let pollMs;
1283
- if (typeof flags['poll-ms'] === 'string') {
1284
- pollMs = Number(flags['poll-ms']);
1285
- if (!Number.isInteger(pollMs) || pollMs <= 0) {
1286
- process.stderr.write(`✗ --poll-ms must be a positive integer (milliseconds) — received: ${flags['poll-ms']}\n`);
1287
- return 1;
1288
- }
1289
- }
1290
- if (!process.stdin.isTTY) {
1291
- process.stderr.write('✗ interactive resident mode (--watch) requires a TTY — use --list in scripts\n');
1292
- return 1;
1293
- }
1294
- if (refuseOperatorAct('the approval screen (--watch)'))
1295
- return 1; // @implements A-SPEC-779.4
1296
- // @implements A-SPEC-497.2 — the resident surface decides on ONE raw keypress (a/d/q/s, no
1297
- // Enter, no deadline) and pings the OS on each new arrival. Raw mode is restored on the way
1298
- // out whatever happens; Ctrl-C arrives as \x03 through decideByKey and ends the loop.
1299
- const { runWatch } = require('./approve-watch');
1300
- const { notifyQueueArrival } = require('./os-notify');
1301
- const ac = new AbortController();
1302
- const onSig = () => ac.abort();
1303
- process.once('SIGINT', onSig);
1304
- const stdin = process.stdin;
1305
- try {
1306
- stdin.setRawMode?.(true);
1307
- stdin.resume();
1308
- await runWatch(root, {
1309
- print: (t) => process.stdout.write(t + '\n'),
1310
- ask: async () => '', // unused on the key surface; kept for the ApproveIO shape
1311
- }, actor, {
1312
- signal: ac.signal,
1313
- keyStream: stdin,
1314
- notify: (p) => notifyQueueArrival(p),
1315
- // @implements A-SPEC-650 — the status header before each new-item pass.
1316
- status: () => { const { renderStatus, statusContext } = require('./approve-status'); return renderStatus(readQueue(root), statusContext(root)); },
1317
- ...(pollMs !== undefined ? { pollMs } : {}),
1318
- });
1319
- }
1320
- catch (e) {
1321
- if (e?.name !== 'AbortError')
1322
- throw e;
1323
- }
1324
- finally {
1325
- process.removeListener('SIGINT', onSig);
1326
- stdin.setRawMode?.(false);
1327
- stdin.pause();
1328
- }
1329
- return 0;
1330
- }
1331
- // @implements A-SPEC-260 — the implicit non-TTY fallback tells the operator the next command,
1332
- // with the real pending id filled in; the explicit --list above stays script-clean.
1333
- if (!process.stdin.isTTY) {
1334
- const state = readQueue(root, queueOpts);
1335
- const hint = renderNonTtyHint(state);
1336
- process.stdout.write(renderPending(state, listView) + (hint ? '\n\n' + hint : '') + '\n');
1337
- return 0;
1338
- }
1339
- if (refuseOperatorAct('the approval screen'))
1340
- return 1; // @implements A-SPEC-779.4
1341
- // @implements A-SPEC-262.1
1342
- // AWAITED, not fire-and-forget. Measured 2026-08-25 against the shipped bin with a real pty: the
1343
- // prompt printed and the session ended with zero grants, because `void runInteractive(...)`
1344
- // returned 0 immediately and bin/holmes-kit.js turns that into `process.exit(0)` — killing the
1345
- // loop before the first keypress. The decision surface REQ-246 shipped had never run for a real
1346
- // operator; every test called `runInteractive` directly and so never crossed this seam.
1347
- const rl = require('node:readline/promises').createInterface({ input: process.stdin, output: process.stdout });
1348
- // EOF is the operator LEAVING (Ctrl-D, a closed pipe). Node leaves a pending `question`
1349
- // unsettled when the interface closes, so without this the awaited loop would hang the command
1350
- // forever — measured 2026-08-25, a pty probe hung for five minutes. The abort ends the session
1351
- // the way the operator asked: quietly, exit 0, nothing decided that was not decided.
1352
- const ac = new AbortController();
1353
- rl.once('close', () => ac.abort());
1354
- try {
1355
- await runInteractive(root, {
1356
- print: (t) => process.stdout.write(t + '\n'),
1357
- ask: (q) => rl.question(q, { signal: ac.signal }),
1358
- }, actor);
1359
- }
1360
- catch (e) {
1361
- if (e?.name !== 'AbortError')
1362
- throw e;
1363
- }
1364
- finally {
1365
- rl.close();
1366
- }
1367
- return 0;
1368
- });
1369
- }
1149
+ // @implements A-SPEC-215, A-SPEC-262.2 — the approve dispatch lives in approve-cli.ts (A-SPEC-794.30: this file stays under its 1,500-line ceiling)
1150
+ if (cmd === 'approve')
1151
+ return require('./approve-cli').runApprove(flags);
1370
1152
  if (cmd === 'serve') {
1371
1153
  if (typeof flags.target === 'string') {
1372
1154
  const t = path.resolve(flags.target);