@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
@@ -18,6 +18,15 @@ export interface RunOptions {
18
18
  why?: string;
19
19
  /** @implements A-SPEC-774.20, A-SPEC-774.24 — the unreadable version fields to start despite, by name; recorded. */
20
20
  acceptUnknownVersions?: string[];
21
+ /** @implements A-SPEC-774.29 — write git-ignored worktree-local wiring pinned to this CLI's build before the checks. */
22
+ provision?: boolean;
23
+ /** @implements A-SPEC-102.10 — the review policy: a cap on failing review rounds (1–20), and strict review. */
24
+ reviewRounds?: string;
25
+ strictReview?: boolean;
26
+ /** @implements A-SPEC-102.12 — the task's base, an ancestor of the worktree HEAD, that every review gate of the run judges from. */
27
+ reviewBase?: string;
28
+ /** @implements A-SPEC-774.52 — the starter's opt-in to an open network for an engine whose own sandbox is turned off. */
29
+ openNetwork?: boolean;
21
30
  }
22
31
  export interface RunDeps {
23
32
  home?: string;
@@ -28,6 +37,12 @@ export interface RunDeps {
28
37
  cliVersion?: string;
29
38
  cliBuild?: string | null;
30
39
  codexConfigPath?: string;
40
+ /** @implements A-SPEC-774.30 — the package run start provisions from and pins; this CLI's own unless a test injects one. */
41
+ packageRoot?: string;
42
+ /** @implements A-SPEC-774.37 — a test seam between the worktree check and provisioning, where a racing swap lands. */
43
+ beforeProvision?: () => void;
44
+ /** @implements A-SPEC-774.54 — how long run stop waits for a live run exec of the run (10 s unless a test shortens it). */
45
+ execWaitMs?: number;
31
46
  }
32
47
  /** @implements A-SPEC-780 — `hook_build`: the dist build id of the package the hook command runs from. */
33
48
  export interface RunVersions {
@@ -37,6 +52,12 @@ export interface RunVersions {
37
52
  hook: string | null;
38
53
  hook_build: string | null;
39
54
  }
55
+ /**
56
+ * @implements A-SPEC-102.14 — the environment of run start's git calls: no inherited `GIT_DIR`, `GIT_WORK_TREE`,
57
+ * `GIT_INDEX_FILE` or `GIT_COMMON_DIR` (each points git at another repository), and no replace objects (a
58
+ * `git replace --graft` fakes ancestry) — review L1, L3.
59
+ */
60
+ export declare function runGitEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
40
61
  /** @implements A-SPEC-774.18 — the versions that would govern this run. Unknown is null, never a guess. */
41
62
  export declare function runVersions(worktree: string, engine: Engine, deps: RunDeps): RunVersions;
42
63
  /** @implements A-SPEC-774.24 — the version fields, in the order a refusal names them. */
@@ -61,5 +82,10 @@ type Io = {
61
82
  stdout: (t: string) => void;
62
83
  stderr: (t: string) => void;
63
84
  };
85
+ /**
86
+ * @implements A-SPEC-774.48 — under run exec the engine's own sandbox is off: run exec is the sandbox, and a nested
87
+ * sandbox-exec cannot apply inside it (measured). Holmes owns these arguments; they go into sandboxed_command only.
88
+ */
89
+ export declare const ENGINE_SANDBOX_OFF: Record<Engine, string[]>;
64
90
  export declare function runRun(sub: string | undefined, opts: RunOptions, io: Io, deps?: RunDeps): number;
65
91
  export {};
@@ -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
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(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,59 +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,...>] [--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;
197
325
  try {
198
- wtMain = fs.statSync(worktree).isDirectory() ? (0, run_records_1.mainCheckoutOf)(worktree) : null;
326
+ if (!fs.statSync(worktree).isDirectory())
327
+ return fail('is not a directory');
328
+ real = fs.realpathSync(worktree);
329
+ mainReal = fs.realpathSync(main);
199
330
  }
200
331
  catch {
201
- wtMain = null;
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));
202
340
  }
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}` });
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;
358
+ try {
359
+ common = fs.realpathSync(dirs[1]);
360
+ }
361
+ catch {
362
+ return fail('has a common git dir that cannot be resolved');
363
+ }
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
- const hooked = namesHolmes(readText(path.join(worktree, '.claude', 'settings.json'))) || namesHolmes(readText(path.join(home, '.claude', 'settings.json')));
216
- out.push(hooked ? { name: 'gate', status: 'pass', detail: 'a Holmes hook is wired in the project or user Claude settings' }
217
- : { name: 'gate', status: 'fail', detail: 'no Holmes hook in <worktree>/.claude/settings.json or ~/.claude/settings.json — the Claude gate would not load' });
218
- }
219
- else if (engine === 'codex') {
220
- const codexHome = deps.codexHome ?? process.env.CODEX_HOME ?? path.join(home, '.codex');
221
- out.push(namesHolmes(readText(path.join(codexHome, 'hooks.json')))
222
- ? { name: 'gate', status: 'pass', detail: 'a Holmes hook is wired in $CODEX_HOME/hooks.json' }
223
- : { 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})` : ''}` });
224
383
  }
225
384
  else {
226
- 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` });
227
387
  }
228
- 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(' '));
229
416
  out.push(off === null ? { name: 'engine-args', status: 'pass', detail: 'no engine argument switches the gate off' }
230
- : { 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})` });
231
418
  return out;
232
419
  }
233
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
234
423
  const main = (0, run_records_1.mainCheckoutOf)(opts.target ?? process.cwd());
235
424
  const random = deps.random ?? ((n) => crypto.randomBytes(n).toString('hex'));
236
425
  if (sub === 'status') {
@@ -258,8 +447,29 @@ function runRun(sub, opts, io, deps = {}) {
258
447
  io.stderr(USAGE);
259
448
  return 2;
260
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);
261
464
  const result = (0, run_records_1.removeRun)(main, opts.id, opts.key);
262
- 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`);
263
473
  return result === 'removed' ? 0 : result === 'bad-key' ? 3 : 4;
264
474
  }
265
475
  if (sub !== 'start' || !opts.worktree || !['claude', 'codex', 'agy'].includes(opts.engine ?? '')) {
@@ -269,12 +479,54 @@ function runRun(sub, opts, io, deps = {}) {
269
479
  const engine = opts.engine;
270
480
  const worktree = path.resolve(opts.worktree);
271
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);
484
+ // @implements A-SPEC-102.10 — the review policy is the orchestrator's, set once here and recorded.
485
+ let reviewRounds;
486
+ if (opts.reviewRounds !== undefined) {
487
+ const n = Number(opts.reviewRounds);
488
+ if (!/^\d+$/.test(opts.reviewRounds.trim()) || !Number.isInteger(n) || n < 1 || n > 20) {
489
+ io.stderr(`--review-rounds must be an integer from 1 to 20 (got ${JSON.stringify(opts.reviewRounds).slice(0, 40)})\n${USAGE}`);
490
+ return 2;
491
+ }
492
+ reviewRounds = n;
493
+ }
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;
500
+ // @implements A-SPEC-774.29 — provisioning runs before the checks, so they judge the worktree as provisioned.
501
+ let provisioned = [];
502
+ let provisionRefusal = null;
503
+ if (opts.provision) {
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
+ }
517
+ }
272
518
  const found = checks(main, worktree, engine, args, deps);
519
+ if (opts.provision) {
520
+ found.unshift(provisionRefusal !== null ? { name: 'provision', status: 'fail', detail: provisionRefusal }
521
+ : { name: 'provision', status: 'pass', detail: provisioned.length > 0 ? `wrote ${provisioned.join(', ')} (git-ignored, pinned to this CLI)` : 'the worktree already carries Holmes wiring' });
522
+ }
273
523
  // @implements A-SPEC-774.18 — the builds that would govern the run, pinned before anything is written.
274
524
  const versions = runVersions(worktree, engine, deps);
275
525
  found.push(versionsCheck(versions, engine, opts.acceptUnknownVersions ?? []));
526
+ if (reviewBaseCheck)
527
+ found.push({ name: 'review-base', status: reviewBaseCheck.status, detail: reviewBaseCheck.detail });
276
528
  if (found.some((c) => c.status === 'fail')) {
277
- io.stdout(`${JSON.stringify({ ok: false, refused: 'a check failed — the run would not be governed', checks: found, versions }, null, 2)}\n`);
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`);
278
530
  return 3;
279
531
  }
280
532
  const now = (deps.now ?? (() => new Date()))();
@@ -283,11 +535,35 @@ function runRun(sub, opts, io, deps = {}) {
283
535
  // The record keeps the fields runMode validates; `versions` rides along (A-SPEC-774.18).
284
536
  // @implements A-SPEC-102.3 — and `base`, the worktree's HEAD now: the start of the range the run's review covers.
285
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
+ }
286
551
  // @implements A-SPEC-774.24 — only the named fields are accepted; the table's exemptions are recorded beside them.
287
552
  const { accepted, exempt } = sortUnreadable(versions, engine, opts.acceptUnknownVersions ?? []);
288
553
  const rec = {
289
554
  run_id: runId, worktree: fs.realpathSync(worktree), sessions: [], engine, started: now.toISOString(), stop_key_sha256: (0, run_records_1.keyHash)(stopKey),
290
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',
565
+ ...(provisioned.length > 0 ? { provisioned } : {}), // @implements A-SPEC-774.29
566
+ ...(review ? { review } : {}), // @implements A-SPEC-102.10
291
567
  ...(opts.scope && opts.scope.length > 0 ? { scope: [...opts.scope] } : {}),
292
568
  ...(accepted.length > 0 ? { accepted_unknown_versions: accepted } : {}),
293
569
  ...(exempt.length > 0 ? { exempt_unknown_versions: exempt } : {}),
@@ -302,6 +578,11 @@ function runRun(sub, opts, io, deps = {}) {
302
578
  (0, run_refusals_1.appendRunEvent)(main, runId, { ts: now.toISOString(), event: 'stages_interpreted', notes: stageNotes });
303
579
  io.stdout(`${JSON.stringify({
304
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
585
+ ...(provisioned.length > 0 ? { provisioned } : {}),
305
586
  stop_key: stopKey, versions, checks: found, ...(stageNotes.length > 0 ? { stage_notes: stageNotes } : {}),
306
587
  }, null, 2)}\n`);
307
588
  return 0;