@holmes-lab/holmes-kit 0.39.0 → 0.40.1

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 (325) hide show
  1. package/CHANGELOG.md +578 -6
  2. package/README.md +120 -41
  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 +49 -13
  47. package/dist/holmes/cli/approve.js +249 -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 +34 -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 +226 -442
  65. package/dist/holmes/cli/init.js +33 -0
  66. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  67. package/dist/holmes/cli/interactive-prompt.js +98 -16
  68. package/dist/holmes/cli/lock-recover.d.ts +5 -0
  69. package/dist/holmes/cli/lock-recover.js +126 -0
  70. package/dist/holmes/cli/mcp-processes.js +1 -1
  71. package/dist/holmes/cli/release-docs.js +1 -1
  72. package/dist/holmes/cli/run-exec.d.ts +141 -0
  73. package/dist/holmes/cli/run-exec.js +1435 -0
  74. package/dist/holmes/cli/run-provision.d.ts +3 -1
  75. package/dist/holmes/cli/run-provision.js +255 -44
  76. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  77. package/dist/holmes/cli/run-wiring.js +270 -0
  78. package/dist/holmes/cli/run.d.ts +21 -0
  79. package/dist/holmes/cli/run.js +341 -92
  80. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  81. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  82. package/dist/holmes/cli/screen-safe.js +18 -756
  83. package/dist/holmes/config/config.d.ts +19 -0
  84. package/dist/holmes/config/config.js +18 -3
  85. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  86. package/dist/holmes/cpg/import-resolver.js +1 -1
  87. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  88. package/dist/holmes/governance/approval-decisions.js +29 -0
  89. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  90. package/dist/holmes/governance/approval-grants.js +612 -33
  91. package/dist/holmes/governance/approval-queue.d.ts +26 -0
  92. package/dist/holmes/governance/approval-queue.js +109 -11
  93. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  94. package/dist/holmes/governance/approval-spend.js +191 -0
  95. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  96. package/dist/holmes/governance/autonomous-shell.js +332 -0
  97. package/dist/holmes/governance/autonomy.d.ts +12 -0
  98. package/dist/holmes/governance/autonomy.js +51 -15
  99. package/dist/holmes/governance/constitution.d.ts +5 -0
  100. package/dist/holmes/governance/constitution.js +32 -12
  101. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  102. package/dist/holmes/governance/full-autonomy.js +103 -7
  103. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  104. package/dist/holmes/governance/harness-catalog.js +348 -0
  105. package/dist/holmes/governance/human-channel.d.ts +38 -0
  106. package/dist/holmes/governance/human-channel.js +49 -0
  107. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  108. package/dist/holmes/governance/install-manifest.js +160 -0
  109. package/dist/holmes/governance/ledger-rechain.js +2 -0
  110. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  111. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  112. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  113. package/dist/holmes/governance/ledger-store.js +186 -8
  114. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  115. package/dist/holmes/governance/provenance-chain.js +19 -4
  116. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  117. package/dist/holmes/governance/provenance-ledger.js +53 -18
  118. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  119. package/dist/holmes/governance/push-gate-runner.js +50 -9
  120. package/dist/holmes/governance/push-gate.d.ts +13 -2
  121. package/dist/holmes/governance/push-gate.js +106 -14
  122. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  123. package/dist/holmes/governance/recorded-pairs.js +522 -0
  124. package/dist/holmes/governance/replica-id.d.ts +1 -1
  125. package/dist/holmes/governance/replica-id.js +1 -1
  126. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  127. package/dist/holmes/governance/spec-seam.js +587 -0
  128. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  129. package/dist/holmes/governance/spend-kinds.js +18 -0
  130. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  131. package/dist/holmes/guardrail/advisory-line.js +718 -0
  132. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  133. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  134. package/dist/holmes/guardrail/impact-gate.d.ts +7 -0
  135. package/dist/holmes/guardrail/impact-gate.js +33 -6
  136. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  137. package/dist/holmes/guardrail/line-continuation.js +39 -0
  138. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  139. package/dist/holmes/guardrail/operator-person.js +57 -11
  140. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  141. package/dist/holmes/guardrail/refusal-codes.js +64 -10
  142. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  143. package/dist/holmes/guardrail/risk-classifier.js +228 -16
  144. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  145. package/dist/holmes/guardrail/risk-gate.js +7 -34
  146. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  147. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  148. package/dist/holmes/guardrail/run-refusals.js +24 -8
  149. package/dist/holmes/guardrail/run-stages.d.ts +5 -0
  150. package/dist/holmes/guardrail/run-stages.js +25 -5
  151. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  152. package/dist/holmes/guardrail/shell-words.js +24 -3
  153. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  154. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  155. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  156. package/dist/holmes/guardrail/write-target.js +26 -5
  157. package/dist/holmes/hooks/pre-tool-use.d.ts +116 -1
  158. package/dist/holmes/hooks/pre-tool-use.js +1176 -170
  159. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  160. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  161. package/dist/holmes/hooks/session-start.js +17 -1
  162. package/dist/holmes/hooks/stop.d.ts +23 -0
  163. package/dist/holmes/hooks/stop.js +86 -33
  164. package/dist/holmes/mcp/approval-adapters.js +3 -1
  165. package/dist/holmes/mcp/approval-commit.js +3 -2
  166. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  167. package/dist/holmes/mcp/approval-policy.js +3 -1
  168. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  169. package/dist/holmes/mcp/handlers/approval-ask.d.ts +3 -0
  170. package/dist/holmes/mcp/handlers/approval-ask.js +18 -7
  171. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  172. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  173. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  174. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  175. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  176. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  177. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  178. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  179. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  180. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  181. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  182. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  183. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  184. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  185. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  186. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  187. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  188. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  189. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  190. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  191. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  192. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  193. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  194. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  195. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  196. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  197. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  198. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  199. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  200. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  201. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  202. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  203. package/dist/holmes/mcp/handlers/test-execution.d.ts +471 -4
  204. package/dist/holmes/mcp/handlers/test-execution.js +199 -21
  205. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  206. package/dist/holmes/mcp/handlers.d.ts +557 -82
  207. package/dist/holmes/mcp/handlers.js +74 -23
  208. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  209. package/dist/holmes/mcp/harness-attestation.js +325 -53
  210. package/dist/holmes/mcp/maintenance-analyze.d.ts +6 -1
  211. package/dist/holmes/mcp/maintenance-analyze.js +13 -11
  212. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  213. package/dist/holmes/mcp/maintenance-evidence.js +35 -3
  214. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  215. package/dist/holmes/mcp/server-staleness.js +1 -1
  216. package/dist/holmes/mcp/server.js +9 -8
  217. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  218. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  219. package/dist/holmes/mcp/tool-schemas.js +42 -9
  220. package/dist/holmes/project/act-root.d.ts +19 -0
  221. package/dist/holmes/project/act-root.js +100 -0
  222. package/dist/holmes/project/baseline.d.ts +15 -2
  223. package/dist/holmes/project/baseline.js +14 -8
  224. package/dist/holmes/project/bounded-group.d.ts +47 -0
  225. package/dist/holmes/project/bounded-group.js +140 -0
  226. package/dist/holmes/project/bounded-io.d.ts +51 -2
  227. package/dist/holmes/project/bounded-io.js +140 -6
  228. package/dist/holmes/project/change-source.d.ts +4 -0
  229. package/dist/holmes/project/change-source.js +14 -6
  230. package/dist/holmes/project/instance-id.d.ts +10 -0
  231. package/dist/holmes/project/instance-id.js +233 -0
  232. package/dist/holmes/project/machine-identity.d.ts +25 -0
  233. package/dist/holmes/project/machine-identity.js +133 -0
  234. package/dist/holmes/project/owned-lock.d.ts +84 -0
  235. package/dist/holmes/project/owned-lock.js +263 -0
  236. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  237. package/dist/holmes/project/plain-lock-fs.js +126 -0
  238. package/dist/holmes/project/request-lock.d.ts +85 -0
  239. package/dist/holmes/project/request-lock.js +459 -0
  240. package/dist/holmes/project/root.d.ts +12 -4
  241. package/dist/holmes/project/root.js +29 -8
  242. package/dist/holmes/project/run-records.d.ts +19 -0
  243. package/dist/holmes/project/run-records.js +94 -12
  244. package/dist/holmes/project/screen-text.d.ts +94 -0
  245. package/dist/holmes/project/screen-text.js +763 -0
  246. package/dist/holmes/project/spend-lock.d.ts +82 -0
  247. package/dist/holmes/project/spend-lock.js +413 -0
  248. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  249. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  250. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  251. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  252. package/dist/holmes/review/confidence-calibration.js +1 -1
  253. package/dist/holmes/review/content-verify.js +1 -1
  254. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  255. package/dist/holmes/review/evidence-mode.js +33 -0
  256. package/dist/holmes/review/head-worktree.d.ts +55 -0
  257. package/dist/holmes/review/head-worktree.js +329 -0
  258. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  259. package/dist/holmes/review/hop-ablation.js +5 -5
  260. package/dist/holmes/review/mrp.js +13 -3
  261. package/dist/holmes/review/point-in-time-replay.js +12 -3
  262. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  263. package/dist/holmes/review/rank-diagnosis.js +1 -1
  264. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  265. package/dist/holmes/review/replay-corpus.js +25 -9
  266. package/dist/holmes/review/requirement-triage.js +2 -2
  267. package/dist/holmes/review/run-provenance.d.ts +45 -0
  268. package/dist/holmes/review/run-provenance.js +314 -0
  269. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  270. package/dist/holmes/review/semantic-arm.js +3 -3
  271. package/dist/holmes/review/test-evidence.d.ts +174 -0
  272. package/dist/holmes/review/test-evidence.js +330 -2
  273. package/dist/holmes/review/test-outcomes.js +3 -1
  274. package/dist/holmes/review/test-reports.d.ts +94 -0
  275. package/dist/holmes/review/test-reports.js +382 -0
  276. package/dist/holmes/review/test-runner.d.ts +180 -58
  277. package/dist/holmes/review/test-runner.js +560 -324
  278. package/dist/holmes/review/test-selection-breadth.js +2 -2
  279. package/dist/holmes/review/test-units.d.ts +159 -0
  280. package/dist/holmes/review/test-units.js +814 -0
  281. package/dist/holmes/review/verdicts.d.ts +105 -8
  282. package/dist/holmes/review/verdicts.js +640 -36
  283. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  284. package/dist/holmes/rtm/anchor-census.js +151 -0
  285. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  286. package/dist/holmes/rtm/anchor-ids.js +45 -2
  287. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  288. package/dist/holmes/rtm/comment-ranges.js +104 -0
  289. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  290. package/dist/holmes/rtm/counted-tests.js +63 -0
  291. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  292. package/dist/holmes/rtm/known-defects.js +1 -1
  293. package/dist/holmes/rtm/localize.js +1 -1
  294. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  295. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  296. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  297. package/dist/holmes/rtm/test-scope.js +166 -5
  298. package/dist/holmes/rtm/trace-gaps.js +1 -1
  299. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  300. package/dist/holmes/runtime/dispatch.js +12 -1
  301. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  302. package/dist/holmes/semantic/cloud-usage.js +1 -1
  303. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  304. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  305. package/dist/holmes/spec/approval-blockers.js +1 -1
  306. package/dist/holmes/spec/entity-store.d.ts +6 -1
  307. package/dist/holmes/spec/entity-store.js +16 -2
  308. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  309. package/dist/holmes/spec/entity-transaction.js +87 -170
  310. package/dist/holmes/spec/spec-store.d.ts +12 -6
  311. package/dist/holmes/spec/spec-store.js +4 -2
  312. package/dist/holmes/spec/spec-types.js +1 -1
  313. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  314. package/dist/holmes/spec/succession-guard.js +187 -0
  315. package/dist/holmes/spec/succession.d.ts +70 -0
  316. package/dist/holmes/spec/succession.js +171 -0
  317. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  318. package/docs/install-guide.md +9 -3
  319. package/docs/language-support.md +78 -0
  320. package/package.json +4 -3
  321. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  322. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  323. package/playbooks/publish/PLAYBOOK.md +47 -34
  324. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  325. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -33,13 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.HARNESS_UNREADABLE_VERSIONS = exports.VERSION_FIELDS = void 0;
36
+ exports.ENGINE_SANDBOX_OFF = exports.HARNESS_UNREADABLE_VERSIONS = exports.VERSION_FIELDS = void 0;
37
+ exports.runGitEnv = runGitEnv;
37
38
  exports.runVersions = runVersions;
38
39
  exports.unreadableVersions = unreadableVersions;
39
40
  exports.parseAcceptedVersions = parseAcceptedVersions;
40
41
  exports.versionsCheck = versionsCheck;
41
42
  exports.runRun = runRun;
42
- // @implements A-SPEC-774.17, A-SPEC-779, A-SPEC-780, A-SPEC-102.3, A-SPEC-102.5, A-SPEC-781, A-SPEC-774.20, A-SPEC-781.2, A-SPEC-774.29, A-SPEC-102.10
43
+ // @implements A-SPEC-774.17, A-SPEC-779, A-SPEC-780, A-SPEC-102.3, A-SPEC-102.5, A-SPEC-781, A-SPEC-774.20, A-SPEC-781.2, A-SPEC-774.29, A-SPEC-102.10, A-SPEC-102.11, A-SPEC-102.12, A-SPEC-774.30, A-SPEC-774.31, A-SPEC-774.32, A-SPEC-774.33, A-SPEC-102.14, A-SPEC-774.34, A-SPEC-102.15, A-SPEC-774.37
43
44
  const node_child_process_1 = require("node:child_process");
44
45
  const crypto = __importStar(require("node:crypto"));
45
46
  const config_1 = require("../config/config");
@@ -50,81 +51,93 @@ const os = __importStar(require("node:os"));
50
51
  const path = __importStar(require("node:path"));
51
52
  const agent_launch_policy_1 = require("../guardrail/agent-launch-policy");
52
53
  const run_records_1 = require("../project/run-records");
53
- /** @implements A-SPEC-774.18 — the version of the holmes-kit package that holds `file`, walking up to its package.json. */
54
- function holmesPackageVersionAbove(file) {
55
- return (0, run_refusals_1.holmesPackageAbove)(file)?.version ?? null;
54
+ /**
55
+ * @implements A-SPEC-102.14 — the environment of run start's git calls: no inherited `GIT_DIR`, `GIT_WORK_TREE`,
56
+ * `GIT_INDEX_FILE` or `GIT_COMMON_DIR` (each points git at another repository), and no replace objects (a
57
+ * `git replace --graft` fakes ancestry) — review L1, L3.
58
+ */
59
+ function runGitEnv(env = process.env) {
60
+ // @implements A-SPEC-102.22, A-SPEC-102.26 — the judgments' allowlist: no inherited GIT_*, no replace objects or grafts
61
+ return require('../review/verdicts').judgmentGitEnv(env);
56
62
  }
57
- /** @implements A-SPEC-774.18 — the holmes-kit version a hook command runs: its first word that names a holmes `.js` path. */
58
- function hookCommandPackage(command) {
59
- const words = command.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
60
- for (const w of words) {
61
- const word = w.replace(/^["']|["']$/g, '');
62
- if (/holmes/i.test(word) && /\.js$/.test(word) && path.isAbsolute(word))
63
- return (0, run_refusals_1.holmesPackageAbove)(word);
63
+ /** @implements A-SPEC-102.12 — `rev` resolved in the worktree, passing only when it is an ancestor of (or is) its HEAD. */
64
+ function reviewBaseOfWorktree(worktree, rev) {
65
+ const { GIT_MAX_BUFFER, GIT_TIMEOUT_MS } = require('../project/bounded-io');
66
+ // @implements A-SPEC-102.14 — a full commit id only, never a rev expression (review L1).
67
+ if (!/^[0-9a-f]{40}$|^[0-9a-f]{64}$/.test(rev))
68
+ return { status: 'fail', detail: `--review-base takes a full commit id (40 or 64 hex), not ${JSON.stringify(rev).slice(0, 60)}` };
69
+ let sha;
70
+ try {
71
+ sha = (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--verify', '--quiet', `${rev}^{commit}`], { cwd: worktree, encoding: 'utf8', env: runGitEnv(), stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER }).trim();
64
72
  }
65
- return null;
73
+ catch {
74
+ sha = '';
75
+ }
76
+ if (sha !== rev)
77
+ return { status: 'fail', detail: `--review-base ${rev} is not a commit in the worktree` };
78
+ try {
79
+ (0, node_child_process_1.execFileSync)('git', ['merge-base', '--is-ancestor', sha, 'HEAD'], { cwd: worktree, encoding: 'utf8', env: runGitEnv(), stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER });
80
+ }
81
+ catch {
82
+ return { status: 'fail', detail: `--review-base ${rev} (${sha.slice(0, 12)}) is not an ancestor of the worktree's HEAD — a run is reviewed only from a base it descends from` };
83
+ }
84
+ return { status: 'pass', sha, detail: `reviewed from ${sha.slice(0, 12)}` };
66
85
  }
67
86
  /** @implements A-SPEC-102.3 — the worktree's HEAD commit, or null when git cannot say. */
68
87
  function worktreeHead(worktree) {
69
88
  const { GIT_MAX_BUFFER, GIT_TIMEOUT_MS } = require('../project/bounded-io');
70
89
  try {
71
- const out = (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], { cwd: worktree, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER }).trim();
90
+ const out = (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], { cwd: worktree, encoding: 'utf8', env: runGitEnv(), stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER }).trim();
72
91
  return /^[0-9a-f]{40,64}$/.test(out) ? out : null;
73
92
  }
74
93
  catch {
75
94
  return null;
76
95
  }
77
96
  }
78
- function hookCommandsIn(text) {
79
- if (text === null)
80
- return [];
81
- const out = [];
82
- const walk = (v) => {
83
- if (Array.isArray(v)) {
84
- v.forEach(walk);
85
- return;
86
- }
87
- if (v && typeof v === 'object') {
88
- const o = v;
89
- if (typeof o.command === 'string' && /holmes/i.test(o.command))
90
- out.push(o.command);
91
- Object.values(o).forEach(walk);
92
- }
93
- };
97
+ /** @implements A-SPEC-102.16 — the worktree's own git dir, through which the run's authorship is read later. */
98
+ function worktreeGitDir(worktree) {
99
+ const { GIT_MAX_BUFFER, GIT_TIMEOUT_MS } = require('../project/bounded-io');
94
100
  try {
95
- walk(JSON.parse(text));
101
+ const out = (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--absolute-git-dir'], { cwd: worktree, encoding: 'utf8', env: runGitEnv(), stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER }).trim();
102
+ return out !== '' && path.isAbsolute(out) ? out : null;
103
+ }
104
+ catch {
105
+ return null;
106
+ }
107
+ }
108
+ /** @implements A-SPEC-102.20 — the branch the worktree has checked out (`refs/heads/…`), or null when detached. */
109
+ function worktreeBranch(worktree) {
110
+ const { GIT_MAX_BUFFER, GIT_TIMEOUT_MS } = require('../project/bounded-io');
111
+ try {
112
+ const out = (0, node_child_process_1.execFileSync)('git', ['symbolic-ref', '--quiet', 'HEAD'], { cwd: worktree, encoding: 'utf8', env: runGitEnv(), stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER }).trim();
113
+ return /^refs\/heads\/[^\s:]+$/.test(out) ? out : null;
114
+ }
115
+ catch {
116
+ return null;
96
117
  }
97
- catch { /* not JSON: no commands */ }
98
- return out;
99
118
  }
100
119
  /** @implements A-SPEC-774.18 — the versions that would govern this run. Unknown is null, never a guess. */
101
120
  function runVersions(worktree, engine, deps) {
102
- const packageRoot = path.resolve(__dirname, '..', '..', '..');
121
+ const packageRoot = deps.packageRoot ?? path.resolve(__dirname, '..', '..', '..');
103
122
  const { readPackageVersion } = require('./mcp-launcher');
104
123
  const { distBuildId } = require('../project/dist-freshness');
105
- const { holmesWirings } = require('./doctor');
106
- const { mcpLaunchVersion } = require('./mcp-version');
107
- const { defaultCodexConfigPath } = require('./codex-toml');
108
- const home = deps.home ?? os.homedir();
109
- const label = engine === 'agy' ? 'antigravity' : engine;
124
+ // @implements A-SPEC-774.30 — the versions of what the verified wiring launches, from the layer the checks used.
110
125
  let mcp = null;
126
+ let hookPkg = null;
111
127
  try {
112
- const wiring = holmesWirings(worktree, deps.codexConfigPath ?? defaultCodexConfigPath()).find((w) => w.label === label);
113
- if (wiring?.entry) {
114
- const args = wiring.entry.command === 'node' && wiring.entry.args.length > 0 && !path.isAbsolute(wiring.entry.args[0])
115
- ? [path.resolve(worktree, wiring.entry.args[0]), ...wiring.entry.args.slice(1)] : wiring.entry.args;
116
- mcp = mcpLaunchVersion({ command: path.basename(wiring.entry.command), args }, (dir) => holmesPackageVersionAbove(path.join(dir, 'package.json')) ?? undefined);
117
- }
128
+ // A-SPEC-102.32 — non-strict: a forged pointer reads the wiring with the worktree as main; a throw is caught below
129
+ // and the versions are unknown
130
+ const w = engineWiring((0, run_records_1.mainCheckoutOf)(worktree), worktree, engine, deps);
131
+ mcp = w.launchedMcp.ok ? w.launchedMcp.pkg.version : null;
132
+ hookPkg = w.launchedGate.ok && w.launchedGate.pkg.root !== null && w.launchedGate.pkg.version !== null
133
+ ? { root: w.launchedGate.pkg.root, version: w.launchedGate.pkg.version } : null;
118
134
  }
119
135
  catch {
120
136
  mcp = null;
137
+ hookPkg = null;
121
138
  }
122
- const hookFiles = engine === 'claude'
123
- ? [path.join(worktree, '.claude', 'settings.json'), path.join(worktree, '.claude', 'settings.local.json'), path.join(home, '.claude', 'settings.json')]
124
- : engine === 'codex' ? [path.join(deps.codexHome ?? process.env.CODEX_HOME ?? path.join(home, '.codex'), 'hooks.json')] : [];
125
- const hookPkg = hookFiles.flatMap((f) => hookCommandsIn(readText(f))).map(hookCommandPackage).find((v) => v !== null) ?? null;
126
139
  return {
127
- cli: deps.cliVersion ?? readPackageVersion(packageRoot) ?? 'unknown',
140
+ cli: deps.cliVersion ?? readPackageVersion(packageRoot) ?? 'unknown', // the package run start provisions from
128
141
  cli_build: deps.cliBuild !== undefined ? deps.cliBuild : distBuildId(packageRoot),
129
142
  mcp, hook: hookPkg?.version ?? null,
130
143
  // @implements A-SPEC-780 — the hook's own build, which the hook compares itself with during the run.
@@ -138,7 +151,8 @@ exports.VERSION_FIELDS = ['cli', 'cli_build', 'mcp', 'hook', 'hook_build'];
138
151
  * They are exempt without a flag and recorded as exempt; every other unreadable field must be named to be accepted.
139
152
  * agy: run start reads no agy hook wiring, so its hook version and build are never known here.
140
153
  */
141
- exports.HARNESS_UNREADABLE_VERSIONS = { claude: [], codex: [], agy: ['hook', 'hook_build'] };
154
+ // @implements A-SPEC-774.30 — agy's hook version is now read from .agents/hooks.json, so no field is exempt.
155
+ exports.HARNESS_UNREADABLE_VERSIONS = { claude: [], codex: [], agy: [] };
142
156
  /** @implements A-SPEC-774.20 — the version fields run start could not read, in a fixed order. */
143
157
  function unreadableVersions(v) {
144
158
  return [
@@ -178,61 +192,234 @@ function versionsCheck(v, engine, accepted) {
178
192
  return { name: 'versions', status: 'pass', detail: `the MCP and hook versions equal this CLI ${v.cli}, and every ${s.exempt.length > 0 ? 'other ' : ''}build id was read${exemptNote}` };
179
193
  }
180
194
  const HEADLESS = { claude: ['claude', '-p'], codex: ['codex', 'exec'], agy: ['agy', '-p'] };
181
- const USAGE = 'usage: holmes-kit run start --worktree <dir> --engine claude|codex|agy [--engine-arg <a>]... [--accept-unknown-versions <field,...>] [--provision] [--review-rounds <1-20>] [--strict-review] [--target <dir>]\n'
195
+ /**
196
+ * @implements A-SPEC-774.48 — under run exec the engine's own sandbox is off: run exec is the sandbox, and a nested
197
+ * sandbox-exec cannot apply inside it (measured). Holmes owns these arguments; they go into sandboxed_command only.
198
+ */
199
+ exports.ENGINE_SANDBOX_OFF = {
200
+ codex: ['--dangerously-bypass-approvals-and-sandbox'], // codex's help: for externally sandboxed environments
201
+ claude: ['--settings', '{"sandbox":{"enabled":false}}'],
202
+ agy: [],
203
+ };
204
+ const USAGE = 'usage: holmes-kit run start --worktree <dir> --engine claude|codex|agy [--engine-arg <a>]... [--accept-unknown-versions <field,...>] [--provision] [--open-network] [--review-rounds <1-20>] [--strict-review] [--review-base <rev>] [--target <dir>]\n'
182
205
  + ' holmes-kit run status [--target <dir>]\n'
183
206
  + ' holmes-kit run transition --id <run_id> --to <stage> --key <stop_key> [--why <text>] [--target <dir>]\n'
184
- + ' holmes-kit run stop --id <run_id> --key <stop_key> [--target <dir>]\n';
207
+ + ' holmes-kit run stop --id <run_id> --key <stop_key> [--target <dir>]\n'
208
+ + ' holmes-kit run exec --id <run_id> [--target <dir>] -- <engine command> [args...] (macOS: write sandbox)\n';
185
209
  const readText = (f) => { try {
186
210
  return fs.readFileSync(f, 'utf8');
187
211
  }
188
212
  catch {
189
213
  return null;
190
214
  } };
191
- const namesHolmes = (t) => t !== null && /holmes/i.test(t);
192
- /** Whether the engine's wiring in this worktree (and the user's home) would load the Holmes gate. */
193
- function checks(main, worktree, engine, args, deps) {
215
+ function engineWiring(main, worktree, engine, deps) {
216
+ const { holmesGate, holmesMcpEntry, codexTrusts, expectedWiring, exactMcp, exactGate, packageInside } = require('./run-wiring');
194
217
  const home = deps.home ?? os.homedir();
195
- const out = [];
196
- let wtMain = null;
218
+ const pkg = deps.packageRoot ?? path.resolve(__dirname, '..', '..', '..');
219
+ const want = expectedWiring(pkg);
220
+ const { readPackageVersion } = require('./mcp-launcher');
221
+ const pkgVersion = readPackageVersion(pkg) ?? null;
222
+ const serverOf = (file) => {
223
+ try {
224
+ return JSON.parse(fs.readFileSync(file, 'utf8')).mcpServers?.['holmes-kit'];
225
+ }
226
+ catch {
227
+ return undefined;
228
+ }
229
+ };
230
+ // @implements A-SPEC-774.32 — a package the engine could rewrite governs nothing.
231
+ const inside = packageInside(pkg, worktree) ? { ok: false, detail: `the holmes-kit package ${pkg} lies inside the worktree, where the engine could rewrite it` } : null;
232
+ if (engine === 'claude') {
233
+ const files = [path.join(worktree, '.claude', 'settings.json'), path.join(worktree, '.claude', 'settings.local.json'), path.join(home, '.claude', 'settings.json')];
234
+ const docs = files.map((f) => ({ file: f, text: readText(f) }));
235
+ const server = serverOf(path.join(worktree, '.mcp.json'));
236
+ // @implements A-SPEC-774.32 — a switch that turns every hook or Holmes's tools off (review H2, measured).
237
+ const { claudeSwitches, managedSettingsDirs } = require('./claude-switches');
238
+ let sw = { hooksOff: [], toolsOff: [] };
239
+ try {
240
+ sw = claudeSwitches(worktree, { home, managedDirs: managedSettingsDirs() });
241
+ }
242
+ catch {
243
+ sw = { hooksOff: ['the Claude settings could not be read'], toolsOff: [] };
244
+ }
245
+ const mcp = inside ?? (sw.toolsOff.length > 0 ? { ok: false, detail: `a switch turns Holmes's MCP tools off: ${sw.toolsOff.join(', ')}` } : exactMcp(server, want.claudeMcp, pkgVersion));
246
+ const gate = inside ?? (sw.hooksOff.length > 0 ? { ok: false, detail: `a switch turns every hook off: ${sw.hooksOff.join(', ')}` } : exactGate(docs, want.claudeHooks));
247
+ return { mcp, gate, mcpFile: '.mcp.json', launchedMcp: holmesMcpEntry(server), launchedGate: holmesGate(docs) };
248
+ }
249
+ if (engine === 'agy') {
250
+ const hooks = path.join(worktree, '.agents', 'hooks.json');
251
+ const launchedMcp = holmesMcpEntry(serverOf(path.join(worktree, '.agents', 'mcp_config.json')));
252
+ const launchedGate = holmesGate([{ file: hooks, text: readText(hooks) }]);
253
+ return { mcp: launchedMcp, gate: launchedGate, mcpFile: path.join('.agents', 'mcp_config.json'), launchedMcp, launchedGate };
254
+ }
255
+ const { readCodexHolmesEntry, defaultCodexConfigPath, codexHolmesDisabled, parseCodexConfig, codexHooksFeatureOff, mergedHolmesTable } = require('./codex-toml');
256
+ const { holmesPreToolDisabled, projectLayers } = require('./codex-oracle');
257
+ const codexHome = deps.codexHome ?? process.env.CODEX_HOME ?? path.join(home, '.codex');
258
+ const userConfig = deps.codexConfigPath ?? (deps.codexHome ? path.join(codexHome, 'config.toml') : defaultCodexConfigPath());
259
+ const userText = readText(userConfig);
260
+ // @implements A-SPEC-774.38 — every layer Codex merges: the user file and each .codex/config.toml from the worktree up.
261
+ const userReal = (() => { try {
262
+ return fs.realpathSync.native(userConfig);
263
+ }
264
+ catch {
265
+ return null;
266
+ } })();
267
+ const walked = projectLayers(worktree, userReal);
268
+ const layers = [{ file: userConfig, text: userText }, ...walked.docs.map((d) => ({ file: d.file, text: readText(d.file) }))];
269
+ const unjudgeable = walked.bad ?? (userText !== null && !parseCodexConfig(userText).ok ? userConfig : null)
270
+ ?? layers.find((l) => l.text === null && l.file !== userConfig)?.file ?? null;
271
+ const parsedOf = (text) => { if (text === null)
272
+ return null; const p = parseCodexConfig(text); return p.ok ? p.doc : null; };
273
+ // @implements A-SPEC-774.46 — the canonical `features.hooks` and its old name `codex_hooks`, through doctor's helper.
274
+ const hooksOffIn = layers.find((l) => codexHooksFeatureOff(parsedOf(l.text)))?.file;
275
+ // @implements A-SPEC-774.56 — the profile the layers select (the last top-level `profile` in Codex's merge order: the
276
+ // user layer, then the project layers from the root down) lays its features over the base ones.
277
+ const mergeOrder = [{ file: userConfig, doc: parsedOf(userText) }, ...walked.docs.slice().reverse().map((d) => ({ file: d.file, doc: d.doc }))];
278
+ let profile;
279
+ for (const l of mergeOrder) {
280
+ const p = l.doc?.profile;
281
+ if (typeof p === 'string')
282
+ profile = p;
283
+ }
284
+ const profileOffIn = profile === undefined ? undefined : mergeOrder.find((l) => {
285
+ const features = (l.doc?.profiles?.[profile])?.features;
286
+ return features !== undefined && codexHooksFeatureOff({ features });
287
+ })?.file;
288
+ const serverOffIn = layers.find((l) => l.text !== null && codexHolmesDisabled(l.text))?.file;
289
+ const projectText = readText(path.join(worktree, '.codex', 'config.toml'));
290
+ const project = projectText === null ? null : readCodexHolmesEntry(projectText);
291
+ const fromProject = project !== null;
292
+ // @implements A-SPEC-774.46 — the table Codex assembles: the user layer, then the project layers from the root down
293
+ // (`walked` lists them from the worktree up), every key of it compared.
294
+ const table = mergedHolmesTable([parsedOf(userText), ...walked.docs.slice().reverse().map((d) => d.doc)]);
295
+ // what this CLI writes, as Codex reads it (the block carries more than {command, args}, e.g. its env)
296
+ const { codexMcpBlock } = require('./codex-toml');
297
+ const wantTable = mergedHolmesTable([parsedOf(codexMcpBlock(want.codexMcp))]);
298
+ const unjudged = unjudgeable === null ? null : { ok: false, detail: `${unjudgeable} is a Codex configuration layer that cannot be read or parsed, so whether it turns Holmes off cannot be judged` };
299
+ const mcp = inside ?? unjudged ?? (serverOffIn !== undefined
300
+ ? { ok: false, detail: `[mcp_servers.holmes-kit] sets enabled = false in ${serverOffIn}` }
301
+ : exactMcp(table, wantTable, pkgVersion));
302
+ const hooks = path.join(codexHome, 'hooks.json');
303
+ const hooksText = readText(hooks);
304
+ const stateOffIn = layers.find((l) => holmesPreToolDisabled(l.text, hooksText, hooks))?.file;
305
+ const gate = inside ?? unjudged ?? (hooksOffIn !== undefined ? { ok: false, detail: `${hooksOffIn} sets [features] hooks (or its old name codex_hooks) = false — Codex runs no hook` }
306
+ : profileOffIn !== undefined ? { ok: false, detail: `the selected profile ${profile} has [profiles.${profile}.features] hooks (or codex_hooks) = false in ${profileOffIn} — Codex runs no hook` }
307
+ : stateOffIn !== undefined ? { ok: false, detail: `${stateOffIn} [hooks.state] disables the Holmes PreToolUse hook of ${hooks}` }
308
+ : exactGate([{ file: hooks, text: hooksText }], want.codexHooks));
309
+ const trusted = codexTrusts(userText, [main, worktree]);
310
+ const trust = fromProject
311
+ ? (trusted ? { name: 'codex-trust', status: 'pass', detail: `${userConfig} trusts the main checkout or the worktree, so Codex loads the worktree's .codex/config.toml` }
312
+ : { name: 'codex-trust', status: 'fail', detail: `Codex loads a project .codex/config.toml only for a trusted project, and ${userConfig} trusts neither ${main} nor ${worktree} — trust the project once in Codex (holmes-kit never writes the user file)` })
313
+ : undefined;
314
+ return { mcp, gate, mcpFile: fromProject ? path.join('.codex', 'config.toml') : userConfig, ...(trust ? { trust } : {}),
315
+ launchedMcp: holmesMcpEntry(table), launchedGate: holmesGate([{ file: hooks, text: hooksText }]) };
316
+ }
317
+ /**
318
+ * @implements A-SPEC-774.33 — a linked working tree of `main`, judged on real paths: not the main checkout itself (its
319
+ * git dir would equal its common dir), and not a worktree of another repository (review M2).
320
+ */
321
+ function worktreeCheck(main, worktree) {
322
+ const fail = (why) => ({ name: 'worktree', status: 'fail', detail: `${worktree} ${why}` });
323
+ let real;
324
+ let mainReal;
325
+ try {
326
+ if (!fs.statSync(worktree).isDirectory())
327
+ return fail('is not a directory');
328
+ real = fs.realpathSync(worktree);
329
+ mainReal = fs.realpathSync(main);
330
+ }
331
+ catch {
332
+ return fail('cannot be resolved');
333
+ }
334
+ if (real === mainReal)
335
+ return fail(`is the main checkout ${main}, not a linked working tree`);
336
+ let wtMain;
337
+ // A-SPEC-102.32 — non-strict: a forged or unreadable pointer is refused here, as not a working tree of main
338
+ try {
339
+ wtMain = fs.realpathSync((0, run_records_1.mainCheckoutOf)(real));
340
+ }
341
+ catch {
342
+ return fail(`is not a working tree of ${main}`);
343
+ }
344
+ if (wtMain !== mainReal)
345
+ return fail(`is not a working tree of ${main}`);
346
+ const { GIT_MAX_BUFFER, GIT_TIMEOUT_MS } = require('../project/bounded-io');
347
+ let dirs;
348
+ try {
349
+ dirs = (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir'], { cwd: real, encoding: 'utf8', env: runGitEnv(), stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER }).trim().split('\n');
350
+ }
351
+ catch {
352
+ return fail('has no git directory git can read');
353
+ }
354
+ if (dirs.length !== 2 || dirs[0] === dirs[1])
355
+ return fail('is a main checkout (its git dir is its common dir), not a linked working tree');
356
+ // @implements A-SPEC-774.37 — the judged real path and common dir travel to provisioning, which resolves nothing again.
357
+ let common;
197
358
  try {
198
- wtMain = fs.statSync(worktree).isDirectory() ? (0, run_records_1.mainCheckoutOf)(worktree) : null;
359
+ common = fs.realpathSync(dirs[1]);
199
360
  }
200
361
  catch {
201
- wtMain = null;
362
+ return fail('has a common git dir that cannot be resolved');
202
363
  }
203
- out.push(wtMain !== null && fs.realpathSync(wtMain) === fs.realpathSync(main)
204
- ? { name: 'worktree', status: 'pass', detail: `${worktree} is a working tree of ${main}` }
205
- : { name: 'worktree', status: 'fail', detail: `${worktree} is not a working tree of ${main}` });
364
+ return { name: 'worktree', status: 'pass', detail: `${worktree} is a working tree of ${main}`, real, common };
365
+ }
366
+ /** Whether the engine's wiring in this worktree (and the user's home) would load the Holmes gate. */
367
+ function checks(main, worktree, engine, args, deps) {
368
+ const home = deps.home ?? os.homedir();
369
+ const out = [];
370
+ out.push(worktreeCheck(main, worktree));
206
371
  out.push(fs.existsSync(path.join(worktree, '.ax', 'specs'))
207
372
  ? { name: 'specs', status: 'pass', detail: '.ax/specs is present' }
208
373
  : { name: 'specs', status: 'fail', detail: '.ax/specs is missing in the worktree — the gate would judge an ungoverned tree' });
209
- const mcp = engine === 'codex' ? namesHolmes(readText(path.join(worktree, '.codex', 'config.toml')))
210
- : engine === 'claude' ? namesHolmes(readText(path.join(worktree, '.mcp.json')))
211
- : namesHolmes(readText(path.join(worktree, '.mcp.json'))) || fs.existsSync(path.join(worktree, '.agents'));
212
- out.push(mcp ? { name: 'mcp', status: 'pass', detail: `the ${engine} MCP wiring in the worktree names holmes-kit` }
213
- : { name: 'mcp', status: 'fail', detail: `the worktree carries no ${engine} MCP wiring that names holmes-kit` });
214
- if (engine === 'claude') {
215
- // @implements A-SPEC-774.29 — settings.local.json too: Claude loads it, and init writes the hooks there.
216
- const hooked = namesHolmes(readText(path.join(worktree, '.claude', 'settings.json'))) || namesHolmes(readText(path.join(worktree, '.claude', 'settings.local.json')))
217
- || namesHolmes(readText(path.join(home, '.claude', 'settings.json')));
218
- out.push(hooked ? { name: 'gate', status: 'pass', detail: 'a Holmes hook is wired in the project or user Claude settings' }
219
- : { name: 'gate', status: 'fail', detail: 'no Holmes hook in <worktree>/.claude/settings.json, <worktree>/.claude/settings.local.json or ~/.claude/settings.json — the Claude gate would not load' });
220
- }
221
- else if (engine === 'codex') {
222
- const codexHome = deps.codexHome ?? process.env.CODEX_HOME ?? path.join(home, '.codex');
223
- out.push(namesHolmes(readText(path.join(codexHome, 'hooks.json')))
224
- ? { name: 'gate', status: 'pass', detail: 'a Holmes hook is wired in $CODEX_HOME/hooks.json' }
225
- : { name: 'gate', status: 'fail', detail: 'no Holmes hook in $CODEX_HOME/hooks.json — the Codex gate would not load' });
374
+ // @implements A-SPEC-774.30 — what the wiring launches, not whether it names holmes.
375
+ const w = engineWiring(main, worktree, engine, deps);
376
+ out.push(w.mcp.ok ? { name: 'mcp', status: 'pass', detail: `${w.mcpFile}: ${w.mcp.detail}` }
377
+ : { name: 'mcp', status: 'fail', detail: `${w.mcpFile}: ${w.mcp.detail}` });
378
+ if (w.trust)
379
+ out.push(w.trust);
380
+ // @implements A-SPEC-774.31 — agy fails closed: nobody has measured that agy loads a linked worktree's .agents.
381
+ if (engine === 'agy') {
382
+ out.push({ name: 'gate', status: 'fail', detail: `refused for agy: whether agy loads a linked worktree's .agents is unmeasured, so no gate can be claimed${w.gate.ok ? ` (${w.gate.detail})` : ''}` });
226
383
  }
227
384
  else {
228
- out.push({ name: 'gate', status: 'unknown', detail: 'agy hook loading cannot be read from a file here — run holmes-kit doctor --agent agy' });
385
+ out.push(w.gate.ok ? { name: 'gate', status: 'pass', detail: w.gate.detail }
386
+ : { name: 'gate', status: 'fail', detail: `${w.gate.detail} — the ${engine} gate would not load` });
229
387
  }
230
- const off = args.map((a) => (0, agent_launch_policy_1.gateOffMarker)(a)).find((m) => m !== null) ?? (0, agent_launch_policy_1.gateOffMarker)(args.join(' '));
388
+ // @implements A-SPEC-774.49 — an allowlist, not a deny list: the launch policy's per-engine options, with every
389
+ // configuration override refused for a run (the policy lets a person's interactive launch set a few -c keys).
390
+ const { interactiveLaunchIssue } = require('../guardrail/agent-launch-policy');
391
+ const CONFIG_OVERRIDE = { codex: /^(?:-c|--config|-p|--profile|--enable|--disable)(?:=|$)/, claude: /^$/, agy: /^$/ };
392
+ const override = args.find((a) => CONFIG_OVERRIDE[engine].test(a));
393
+ // @implements A-SPEC-774.51, A-SPEC-774.55 — the engine's own sandbox and permission checks are Holmes's to turn off
394
+ // (sandbox_args, in sandboxed_command only), never the caller's: a run is not a person's interactive launch.
395
+ const valueOf = (i, name) => args[i] === name ? args[i + 1] : args[i].startsWith(`${name}=`) ? args[i].slice(name.length + 1) : undefined;
396
+ const sandboxOff = args.find((a, i) => engine === 'codex'
397
+ ? a === '--dangerously-bypass-approvals-and-sandbox' || ['-s', '--sandbox'].some((n) => valueOf(i, n) === 'danger-full-access')
398
+ : engine === 'claude' ? a === '--dangerously-skip-permissions' || valueOf(i, '--permission-mode') === 'bypassPermissions'
399
+ : a === '--dangerously-skip-permissions');
400
+ // @implements A-SPEC-774.55 — nor are Holmes's own tools disallowed: claude's --disallowedTools takes words up to the
401
+ // next option, each a comma- or space-separated list.
402
+ const toolsOff = engine !== 'claude' ? undefined : (() => {
403
+ const at = args.findIndex((a) => /^--disallowed(?:Tools|-tools)(?:=|$)/.test(a));
404
+ if (at < 0)
405
+ return undefined;
406
+ const end = args.findIndex((a, i) => i > at && a.startsWith('-'));
407
+ const listed = [args[at].includes('=') ? args[at].slice(args[at].indexOf('=') + 1) : '', ...args.slice(at + 1, end < 0 ? args.length : end)];
408
+ return listed.flatMap((w) => w.split(/[\s,]+/)).filter(Boolean).find((w) => /holmes/i.test(w) || /^(?:mcp|mcp__|mcp__\*|\*)$/.test(w));
409
+ })();
410
+ const off = (override !== undefined ? `configuration override ${override}` : null)
411
+ ?? (sandboxOff !== undefined ? `${sandboxOff} — the engine's own sandbox and permission checks are turned off only by Holmes, in sandboxed_command` : null)
412
+ ?? (toolsOff !== undefined ? `--disallowedTools ${toolsOff} — Holmes's own tools stay available to a run` : null)
413
+ // agy's headless -p takes a value: the first engine argument is checked as an option, not as that value
414
+ ?? interactiveLaunchIssue([...HEADLESS[engine], ...(engine === 'agy' ? ['run prompt'] : []), ...args])
415
+ ?? args.map((a) => (0, agent_launch_policy_1.gateOffMarker)(a)).find((m) => m !== null) ?? (0, agent_launch_policy_1.gateOffMarker)(args.join(' '));
231
416
  out.push(off === null ? { name: 'engine-args', status: 'pass', detail: 'no engine argument switches the gate off' }
232
- : { name: 'engine-args', status: 'fail', detail: `an engine argument switches the gate off (${off})` });
417
+ : { name: 'engine-args', status: 'fail', detail: `an engine argument is not on the engine's allowlist or could switch the gate off (${off})` });
233
418
  return out;
234
419
  }
235
420
  function runRun(sub, opts, io, deps = {}) {
421
+ // A-SPEC-102.32 — non-strict: a forged pointer makes the target its own main, so the run subcommands read and write its
422
+ // `.ax`; a pointer that cannot be opened throws out of the command
236
423
  const main = (0, run_records_1.mainCheckoutOf)(opts.target ?? process.cwd());
237
424
  const random = deps.random ?? ((n) => crypto.randomBytes(n).toString('hex'));
238
425
  if (sub === 'status') {
@@ -260,8 +447,29 @@ function runRun(sub, opts, io, deps = {}) {
260
447
  io.stderr(USAGE);
261
448
  return 2;
262
449
  }
450
+ // @implements A-SPEC-774.54 — never record a run while its run exec or watchdog may still write its taint.
451
+ const { liveExecEntries } = require('./run-exec');
452
+ const waitUntil = Date.now() + (deps.execWaitMs ?? 10_000);
453
+ let live = liveExecEntries(main, opts.id);
454
+ while (live.length > 0 && Date.now() < waitUntil) {
455
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
456
+ live = liveExecEntries(main, opts.id);
457
+ }
458
+ if (live.length > 0) {
459
+ io.stdout(`${JSON.stringify({ ok: false, run_id: opts.id, result: 'exec-running', detail: 'a run exec of this run (or its watchdog) is still running — stop it first; its teardown may still taint the run' })}\n`);
460
+ return 3;
461
+ }
462
+ // @implements A-SPEC-102.11 — the stopped run's authored commits outlive its record, while its worktree still exists.
463
+ const stopping = (0, run_records_1.listRuns)(main).find((r) => r.run_id === opts.id);
263
464
  const result = (0, run_records_1.removeRun)(main, opts.id, opts.key);
264
- io.stdout(`${JSON.stringify({ ok: result === 'removed', run_id: opts.id, result })}\n`);
465
+ const verdicts = require('../review/verdicts');
466
+ const authorship = result === 'removed' && stopping
467
+ ? verdicts.recordRunAuthorship(main, stopping, deps.now ?? (() => new Date()))
468
+ : undefined;
469
+ // @implements A-SPEC-102.19 — the snapshot served its run; the ledger line now carries what the run made.
470
+ if (result === 'removed')
471
+ fs.rmSync(verdicts.commitSnapshotFile(main, opts.id), { force: true });
472
+ io.stdout(`${JSON.stringify({ ok: result === 'removed', run_id: opts.id, result, ...(authorship !== undefined ? { authorship } : {}) })}\n`);
265
473
  return result === 'removed' ? 0 : result === 'bad-key' ? 3 : 4;
266
474
  }
267
475
  if (sub !== 'start' || !opts.worktree || !['claude', 'codex', 'agy'].includes(opts.engine ?? '')) {
@@ -271,6 +479,8 @@ function runRun(sub, opts, io, deps = {}) {
271
479
  const engine = opts.engine;
272
480
  const worktree = path.resolve(opts.worktree);
273
481
  const args = opts.engineArgs ?? [];
482
+ // @implements A-SPEC-774.41 — engines and run homes a killed run exec left are swept before anything else.
483
+ require('./run-exec').sweepOrphanExecs(main);
274
484
  // @implements A-SPEC-102.10 — the review policy is the orchestrator's, set once here and recorded.
275
485
  let reviewRounds;
276
486
  if (opts.reviewRounds !== undefined) {
@@ -281,18 +491,29 @@ function runRun(sub, opts, io, deps = {}) {
281
491
  }
282
492
  reviewRounds = n;
283
493
  }
284
- const review = reviewRounds !== undefined || opts.strictReview
285
- ? { ...(reviewRounds !== undefined ? { rounds: reviewRounds } : {}), ...(opts.strictReview ? { strict: true } : {}) } : undefined;
494
+ // @implements A-SPEC-102.12 — the task's review base: a commit that is an ancestor of (or is) the worktree's HEAD.
495
+ const reviewBaseCheck = opts.reviewBase !== undefined ? reviewBaseOfWorktree(worktree, opts.reviewBase) : undefined;
496
+ const reviewBase = reviewBaseCheck && reviewBaseCheck.status === 'pass' ? reviewBaseCheck.sha : undefined;
497
+ const review = reviewRounds !== undefined || opts.strictReview || reviewBase !== undefined
498
+ ? { ...(reviewRounds !== undefined ? { rounds: reviewRounds } : {}), ...(opts.strictReview ? { strict: true } : {}),
499
+ ...(reviewBase !== undefined ? { base: reviewBase } : {}) } : undefined;
286
500
  // @implements A-SPEC-774.29 — provisioning runs before the checks, so they judge the worktree as provisioned.
287
501
  let provisioned = [];
288
502
  let provisionRefusal = null;
289
503
  if (opts.provision) {
290
- const { provisionWorktree } = require('./run-provision');
291
- const p = provisionWorktree(worktree, engine, path.resolve(__dirname, '..', '..', '..'));
292
- if ('refused' in p)
293
- provisionRefusal = p.refused;
294
- else
295
- provisioned = p.written;
504
+ // @implements A-SPEC-774.33 — the worktree is judged before anything is written into it (review M2).
505
+ const wtCheck = worktreeCheck(main, worktree);
506
+ if (wtCheck.status !== 'pass')
507
+ provisionRefusal = `not provisioned: ${wtCheck.detail}`;
508
+ else {
509
+ deps.beforeProvision?.();
510
+ const { provisionWorktree } = require('./run-provision');
511
+ const p = provisionWorktree(wtCheck.real ?? worktree, engine, deps.packageRoot ?? path.resolve(__dirname, '..', '..', '..'), wtCheck.common);
512
+ if ('refused' in p)
513
+ provisionRefusal = p.refused;
514
+ else
515
+ provisioned = p.written;
516
+ }
296
517
  }
297
518
  const found = checks(main, worktree, engine, args, deps);
298
519
  if (opts.provision) {
@@ -302,6 +523,8 @@ function runRun(sub, opts, io, deps = {}) {
302
523
  // @implements A-SPEC-774.18 — the builds that would govern the run, pinned before anything is written.
303
524
  const versions = runVersions(worktree, engine, deps);
304
525
  found.push(versionsCheck(versions, engine, opts.acceptUnknownVersions ?? []));
526
+ if (reviewBaseCheck)
527
+ found.push({ name: 'review-base', status: reviewBaseCheck.status, detail: reviewBaseCheck.detail });
305
528
  if (found.some((c) => c.status === 'fail')) {
306
529
  io.stdout(`${JSON.stringify({ ok: false, refused: 'a check failed — the run would not be governed', checks: found, versions, ...(provisioned.length > 0 ? { provisioned } : {}) }, null, 2)}\n`);
307
530
  return 3;
@@ -312,11 +535,33 @@ function runRun(sub, opts, io, deps = {}) {
312
535
  // The record keeps the fields runMode validates; `versions` rides along (A-SPEC-774.18).
313
536
  // @implements A-SPEC-102.3 — and `base`, the worktree's HEAD now: the start of the range the run's review covers.
314
537
  const base = worktreeHead(worktree);
538
+ const gitDir = worktreeGitDir(worktree);
539
+ const branch = worktreeBranch(worktree);
540
+ // @implements A-SPEC-102.19 — the store's commit objects now: what appears later is this run's.
541
+ if (!require('../review/verdicts').snapshotRunCommits(main, runId)) {
542
+ io.stdout(`${JSON.stringify({ ok: false, refused: 'the commit objects of the store could not be snapshotted — the run\'s authorship could not be proven', checks: found, versions }, null, 2)}\n`);
543
+ return 3;
544
+ }
545
+ // @implements A-SPEC-102.22 — the shallow and grafts files now: a review run's ranges hold only while they stay put.
546
+ const historyFiles = require('../review/verdicts').historyFiles(main);
547
+ if (historyFiles === null) {
548
+ io.stdout(`${JSON.stringify({ ok: false, refused: 'the repository\'s shallow and grafts files could not be read — the run\'s review ranges could not be pinned', checks: found, versions }, null, 2)}\n`);
549
+ return 3;
550
+ }
315
551
  // @implements A-SPEC-774.24 — only the named fields are accepted; the table's exemptions are recorded beside them.
316
552
  const { accepted, exempt } = sortUnreadable(versions, engine, opts.acceptUnknownVersions ?? []);
317
553
  const rec = {
318
554
  run_id: runId, worktree: fs.realpathSync(worktree), sessions: [], engine, started: now.toISOString(), stop_key_sha256: (0, run_records_1.keyHash)(stopKey),
319
555
  versions, ...(base ? { base } : {}),
556
+ // @implements A-SPEC-102.15 — the worktree reflog's length now: the entries added after it are this run's own.
557
+ reflog_entries: require('../review/verdicts').reflogLength(worktree),
558
+ ...(gitDir ? { git_dir: gitDir } : {}), // @implements A-SPEC-102.16
559
+ ...(branch ? { branch } : {}), // @implements A-SPEC-102.20 — the snapshot delta counts what this branch reaches
560
+ commit_snapshot: true, // @implements A-SPEC-102.19
561
+ history_files: historyFiles, // @implements A-SPEC-102.22
562
+ // @implements A-SPEC-774.52, A-SPEC-774.60 — open only when the starter said so, on record; otherwise run exec's
563
+ // allowlisting proxy is the run's only way out.
564
+ network: opts.openNetwork === true ? 'open' : 'allowlist',
320
565
  ...(provisioned.length > 0 ? { provisioned } : {}), // @implements A-SPEC-774.29
321
566
  ...(review ? { review } : {}), // @implements A-SPEC-102.10
322
567
  ...(opts.scope && opts.scope.length > 0 ? { scope: [...opts.scope] } : {}),
@@ -333,6 +578,10 @@ function runRun(sub, opts, io, deps = {}) {
333
578
  (0, run_refusals_1.appendRunEvent)(main, runId, { ts: now.toISOString(), event: 'stages_interpreted', notes: stageNotes });
334
579
  io.stdout(`${JSON.stringify({
335
580
  ok: true, run_id: runId, worktree, record, env: { HOLMES_RUN_ID: runId }, command: [...HEADLESS[engine], ...args],
581
+ // @implements A-SPEC-774.34 — the same command inside the run's write sandbox, with every descendant ended at exit.
582
+ sandboxed_command: ['holmes-kit', 'run', 'exec', '--id', runId, '--target', main, '--', ...HEADLESS[engine], ...exports.ENGINE_SANDBOX_OFF[engine], ...args],
583
+ sandbox_args: exports.ENGINE_SANDBOX_OFF[engine], // @implements A-SPEC-774.48
584
+ network: rec.network, // @implements A-SPEC-774.52
336
585
  ...(provisioned.length > 0 ? { provisioned } : {}),
337
586
  stop_key: stopKey, versions, checks: found, ...(stageNotes.length > 0 ? { stage_notes: stageNotes } : {}),
338
587
  }, null, 2)}\n`);