@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
@@ -0,0 +1,47 @@
1
+ /**
2
+ * A bounded child that outlives no one. On POSIX the child is a small watch shim, spawned detached so it leads a new
3
+ * process group, and the shim runs the real command inside that group:
4
+ * - when the shim's parent goes (the caller was signalled, or died otherwise), the shim ends its whole group: a
5
+ * detached group no longer receives the caller's group signals, and no JavaScript handler runs while spawnSync waits;
6
+ * - when the shim itself is signalled, it ends its group the same way;
7
+ * - when the command exits, the shim exits the same way (its code, or its signal raised on itself).
8
+ * After the call returns, the caller ends the group on the bound, a buffer overflow or a signal, and after a normal exit
9
+ * only when a probe finds members left (they are ended and reported).
10
+ *
11
+ * The group id is the pid of the child this call spawned; ending it right after the call returns makes hitting another
12
+ * process unlikely, not impossible. A grandchild that leaves the group with setsid escapes (a named limit). Windows has
13
+ * no groups: the child alone is stopped there, as before. Node's own modules only, so a test can run it as built.
14
+ */
15
+ import { type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from 'node:child_process';
16
+ /** @implements A-SPEC-734.6 — how long the shim keeps relaying after its runner exits (late output a worker writes). */
17
+ export declare const SHIM_DRAIN_MS = 300;
18
+ /** @implements A-SPEC-734.6 — how often the shim compares its parent with the caller after the first line. */
19
+ export declare const SHIM_WATCH_MS = 100;
20
+ /**
21
+ * The shim's program (`node -e SHIM -- HEAD cmd ...args`, HEAD the JSON `{caller, nodeOptions, drainMs, watchMs}`). A spawn error's code is
22
+ * written to descriptor 3 and the shim exits 127.
23
+ * @implements A-SPEC-734.5 — the parent is compared with the caller's pid from the first line (a caller that died while
24
+ * the shim started left it re-parented and the runner unbounded); the runner's output is relayed through the shim's pipes
25
+ * with a short drain at its exit (a worker holding the inherited pipes kept the call until the bound); the shim runs
26
+ * without the caller's NODE_OPTIONS and hands it to the runner.
27
+ */
28
+ export declare const SHIM = "const { spawn } = require('child_process');\nconst fs = require('fs');\nconst [head, cmd, ...args] = process.argv.slice(1);\nconst { caller, nodeOptions, drainMs, watchMs } = JSON.parse(head);\nconst end = () => { try { process.kill(-process.pid, 'SIGKILL'); } catch { process.exit(137); } };\nif (process.ppid !== caller) end();\nconst sigs = ['SIGINT', 'SIGTERM', 'SIGHUP'];\nfor (const s of sigs) process.on(s, end);\nconst watch = setInterval(() => { if (process.ppid !== caller) end(); }, watchMs);\nconst env = { ...process.env };\nif (nodeOptions === null) delete env.NODE_OPTIONS; else env.NODE_OPTIONS = nodeOptions;\nconst c = spawn(cmd, args, { stdio: ['inherit', 'pipe', 'pipe'], env });\nc.stdout.pipe(process.stdout, { end: false });\nc.stderr.pipe(process.stderr, { end: false });\nc.on('error', (e) => {\n clearInterval(watch);\n try { fs.writeSync(3, String((e && e.code) || 'ERROR')); } catch {}\n process.stderr.write(String(e && e.message) + '\\n');\n process.exit(127);\n});\nlet open = 2, exited = null, finished = false;\nconst finish = () => {\n if (finished || exited === null || open > 0) return;\n finished = true;\n c.stdout.unpipe(); c.stderr.unpipe();\n let n = 2;\n const go = () => {\n if (--n > 0) return;\n const [code, sig] = exited;\n if (sig) { for (const s of sigs) process.removeAllListeners(s); process.kill(process.pid, sig); setTimeout(() => process.exit(128), 1000); }\n else process.exit(code === null ? 1 : code);\n };\n process.stdout.write('', go);\n process.stderr.write('', go);\n};\nc.stdout.on('end', () => { open--; finish(); });\nc.stderr.on('end', () => { open--; finish(); });\nc.on('exit', (code, sig) => {\n clearInterval(watch);\n exited = [code, sig];\n // a worker still holding the runner's pipes does not hold the call: a short drain, then out\n setTimeout(() => { open = 0; finish(); }, drainMs);\n finish();\n});\n";
29
+ export interface BoundedGroupResult {
30
+ result: SpawnSyncReturns<string>;
31
+ stopped: boolean;
32
+ leftovers: boolean;
33
+ }
34
+ export interface BoundedGroupDeps {
35
+ kill?: (pid: number, sig: NodeJS.Signals | 0) => void;
36
+ callerPid?: number;
37
+ /** @implements A-SPEC-734.7 — the shim's timing, through its head (DIP); defaults SHIM_DRAIN_MS and SHIM_WATCH_MS. */
38
+ drainMs?: number;
39
+ watchMs?: number;
40
+ }
41
+ /** @implements A-SPEC-734.7 — the shim's head, without the caller's NODE_OPTIONS (added by the caller). */
42
+ export declare function shimHead(deps: BoundedGroupDeps): {
43
+ caller: number;
44
+ drainMs: number;
45
+ watchMs: number;
46
+ };
47
+ export declare function boundedGroupSpawnSync(cmd: string, args: string[], opts: SpawnSyncOptionsWithStringEncoding, timeoutMs: number, deps?: BoundedGroupDeps): BoundedGroupResult;
@@ -0,0 +1,140 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.SHIM = exports.SHIM_WATCH_MS = exports.SHIM_DRAIN_MS = void 0;
4
+ exports.shimHead = shimHead;
5
+ exports.boundedGroupSpawnSync = boundedGroupSpawnSync;
6
+ // @implements A-SPEC-734.4, A-SPEC-734.5, A-SPEC-734.6, A-SPEC-734.7
7
+ /**
8
+ * A bounded child that outlives no one. On POSIX the child is a small watch shim, spawned detached so it leads a new
9
+ * process group, and the shim runs the real command inside that group:
10
+ * - when the shim's parent goes (the caller was signalled, or died otherwise), the shim ends its whole group: a
11
+ * detached group no longer receives the caller's group signals, and no JavaScript handler runs while spawnSync waits;
12
+ * - when the shim itself is signalled, it ends its group the same way;
13
+ * - when the command exits, the shim exits the same way (its code, or its signal raised on itself).
14
+ * After the call returns, the caller ends the group on the bound, a buffer overflow or a signal, and after a normal exit
15
+ * only when a probe finds members left (they are ended and reported).
16
+ *
17
+ * The group id is the pid of the child this call spawned; ending it right after the call returns makes hitting another
18
+ * process unlikely, not impossible. A grandchild that leaves the group with setsid escapes (a named limit). Windows has
19
+ * no groups: the child alone is stopped there, as before. Node's own modules only, so a test can run it as built.
20
+ */
21
+ const node_child_process_1 = require("node:child_process");
22
+ /** @implements A-SPEC-734.6 — how long the shim keeps relaying after its runner exits (late output a worker writes). */
23
+ exports.SHIM_DRAIN_MS = 300;
24
+ /** @implements A-SPEC-734.6 — how often the shim compares its parent with the caller after the first line. */
25
+ exports.SHIM_WATCH_MS = 100;
26
+ /**
27
+ * The shim's program (`node -e SHIM -- HEAD cmd ...args`, HEAD the JSON `{caller, nodeOptions, drainMs, watchMs}`). A spawn error's code is
28
+ * written to descriptor 3 and the shim exits 127.
29
+ * @implements A-SPEC-734.5 — the parent is compared with the caller's pid from the first line (a caller that died while
30
+ * the shim started left it re-parented and the runner unbounded); the runner's output is relayed through the shim's pipes
31
+ * with a short drain at its exit (a worker holding the inherited pipes kept the call until the bound); the shim runs
32
+ * without the caller's NODE_OPTIONS and hands it to the runner.
33
+ */
34
+ exports.SHIM = `const { spawn } = require('child_process');
35
+ const fs = require('fs');
36
+ const [head, cmd, ...args] = process.argv.slice(1);
37
+ const { caller, nodeOptions, drainMs, watchMs } = JSON.parse(head);
38
+ const end = () => { try { process.kill(-process.pid, 'SIGKILL'); } catch { process.exit(137); } };
39
+ if (process.ppid !== caller) end();
40
+ const sigs = ['SIGINT', 'SIGTERM', 'SIGHUP'];
41
+ for (const s of sigs) process.on(s, end);
42
+ const watch = setInterval(() => { if (process.ppid !== caller) end(); }, watchMs);
43
+ const env = { ...process.env };
44
+ if (nodeOptions === null) delete env.NODE_OPTIONS; else env.NODE_OPTIONS = nodeOptions;
45
+ const c = spawn(cmd, args, { stdio: ['inherit', 'pipe', 'pipe'], env });
46
+ c.stdout.pipe(process.stdout, { end: false });
47
+ c.stderr.pipe(process.stderr, { end: false });
48
+ c.on('error', (e) => {
49
+ clearInterval(watch);
50
+ try { fs.writeSync(3, String((e && e.code) || 'ERROR')); } catch {}
51
+ process.stderr.write(String(e && e.message) + '\\n');
52
+ process.exit(127);
53
+ });
54
+ let open = 2, exited = null, finished = false;
55
+ const finish = () => {
56
+ if (finished || exited === null || open > 0) return;
57
+ finished = true;
58
+ c.stdout.unpipe(); c.stderr.unpipe();
59
+ let n = 2;
60
+ const go = () => {
61
+ if (--n > 0) return;
62
+ const [code, sig] = exited;
63
+ if (sig) { for (const s of sigs) process.removeAllListeners(s); process.kill(process.pid, sig); setTimeout(() => process.exit(128), 1000); }
64
+ else process.exit(code === null ? 1 : code);
65
+ };
66
+ process.stdout.write('', go);
67
+ process.stderr.write('', go);
68
+ };
69
+ c.stdout.on('end', () => { open--; finish(); });
70
+ c.stderr.on('end', () => { open--; finish(); });
71
+ c.on('exit', (code, sig) => {
72
+ clearInterval(watch);
73
+ exited = [code, sig];
74
+ // a worker still holding the runner's pipes does not hold the call: a short drain, then out
75
+ setTimeout(() => { open = 0; finish(); }, drainMs);
76
+ finish();
77
+ });
78
+ `;
79
+ /** @implements A-SPEC-734.7 — the shim's head, without the caller's NODE_OPTIONS (added by the caller). */
80
+ function shimHead(deps) {
81
+ return { caller: deps.callerPid ?? process.pid, drainMs: deps.drainMs ?? exports.SHIM_DRAIN_MS, watchMs: deps.watchMs ?? exports.SHIM_WATCH_MS };
82
+ }
83
+ function boundedGroupSpawnSync(cmd, args, opts, timeoutMs, deps = {}) {
84
+ const kill = deps.kill ?? ((pid, sig) => { process.kill(pid, sig); });
85
+ if (process.platform === 'win32') {
86
+ const result = (0, node_child_process_1.spawnSync)(cmd, args, { ...opts, timeout: timeoutMs, killSignal: 'SIGKILL' });
87
+ return { result, stopped: result.error?.code === 'ETIMEDOUT', leftovers: false };
88
+ }
89
+ // `detached` is honoured by spawnSync (libuv's setsid) though its option type leaves it out
90
+ // A-SPEC-734.5: the caller's NODE_OPTIONS goes to the runner, not to the shim; descriptor 3 carries a spawn error's code
91
+ const env = { ...(opts.env ?? process.env) };
92
+ const nodeOptions = env.NODE_OPTIONS ?? null;
93
+ delete env.NODE_OPTIONS;
94
+ const given = opts.stdio;
95
+ const stdio = Array.isArray(given) ? [...given] : [given ?? 'pipe', given ?? 'pipe', given ?? 'pipe'];
96
+ while (stdio.length < 3)
97
+ stdio.push('pipe');
98
+ stdio.length = 3;
99
+ stdio.push('pipe');
100
+ const groupOpts = { ...opts, env, stdio, timeout: timeoutMs, killSignal: 'SIGKILL', detached: true };
101
+ const head = JSON.stringify({ ...shimHead(deps), nodeOptions });
102
+ const result = (0, node_child_process_1.spawnSync)(process.execPath, ['-e', exports.SHIM, '--', head, cmd, ...args], groupOpts);
103
+ const errno = String(result.output?.[3] ?? '').trim();
104
+ if (result.output)
105
+ result.output = result.output.slice(0, 3);
106
+ const code = result.error?.code;
107
+ const stopped = code === 'ETIMEDOUT';
108
+ let leftovers = false;
109
+ const pid = result.pid;
110
+ if (pid) {
111
+ if (result.error || result.signal !== null) {
112
+ try {
113
+ kill(-pid, 'SIGKILL');
114
+ }
115
+ catch { /* the group already ended */ }
116
+ }
117
+ else {
118
+ let members = false;
119
+ try {
120
+ kill(-pid, 0);
121
+ members = true;
122
+ }
123
+ catch {
124
+ members = false;
125
+ }
126
+ if (members) {
127
+ leftovers = true;
128
+ try {
129
+ kill(-pid, 'SIGKILL');
130
+ }
131
+ catch { /* ended meanwhile */ }
132
+ }
133
+ }
134
+ }
135
+ // a spawn error keeps execFileSync's shape and its own code (ENOENT, EACCES, …)
136
+ if (!result.error && result.status === 127 && /^E[A-Z0-9]+$/.test(errno)) {
137
+ result.error = Object.assign(new Error(`spawnSync ${cmd} ${errno}`), { code: errno, ...(errno === 'ENOENT' ? { errno: -2 } : {}), syscall: `spawnSync ${cmd}`, path: cmd });
138
+ }
139
+ return { result, stopped, leftovers };
140
+ }
@@ -46,8 +46,18 @@ export declare function gitOnce(root: string, args: string[], kind: GitKind, opt
46
46
  input?: string;
47
47
  timeout?: number;
48
48
  env?: NodeJS.ProcessEnv;
49
+ pinned?: JudgmentPins;
49
50
  ignoreBlock?: boolean;
51
+ record?: boolean;
50
52
  }): SpawnSyncReturns<string>;
53
+ /**
54
+ * @implements A-SPEC-222.13 — gitOnce with stdout as bytes: a batch of blobs is cut at byte offsets, so its output must
55
+ * not pass through a string first (invalid UTF-8 in one blob moved every later offset). Same memory and environment.
56
+ */
57
+ export declare function gitOnceBuffer(root: string, args: string[], kind: GitKind, opts?: {
58
+ input?: string;
59
+ pinned?: JudgmentPins;
60
+ }): SpawnSyncReturns<Buffer>;
51
61
  /** Test seam: forget every blocked root. */
52
62
  export declare function resetGitBlocked(): void;
53
63
  /**
@@ -56,6 +66,12 @@ export declare function resetGitBlocked(): void;
56
66
  * such as `/dev/zero` included). Throws like `readFileSync` does, so callers keep their error handling.
57
67
  */
58
68
  export declare function readRegularFileSync(p: string): Buffer;
69
+ /**
70
+ * @implements A-SPEC-102.30 (item 8) — a small regular file, judged on the descriptor that is read: opened non-blocking
71
+ * and without following a link (where the platform can), then fstat'ed for a regular file of at most `max` bytes, so
72
+ * nothing swaps the file between the check and the read. Throws (code EINVAL or EFBIG) otherwise.
73
+ */
74
+ export declare function readSmallRegularTextSync(p: string, max: number): string;
59
75
  /** `readRegularFileSync` as UTF-8 text. */
60
76
  export declare function readRegularTextSync(p: string): string;
61
77
  /**
@@ -93,8 +109,41 @@ export declare const REPO_LOCATING_GIT_VARS: readonly ["GIT_DIR", "GIT_WORK_TREE
93
109
  * a case-folding disk read clean (measured).
94
110
  */
95
111
  export declare function underGitPrefix(full: string, prefix: string): string | null;
96
- /** A git child's environment: the caller's, without the variables that relocate the repository (round 17). */
97
- export declare function gitEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
112
+ export declare function gitEnv(env?: NodeJS.ProcessEnv, opts?: {
113
+ attributes?: boolean;
114
+ }): NodeJS.ProcessEnv;
115
+ /**
116
+ * @implements A-SPEC-792.43 — the judgment's own git values, applied after `gitEnv` (gitOnce's `pinned`): no replace
117
+ * objects, the platform's null device as the graft file, no terminal prompt.
118
+ */
119
+ export declare function judgmentPins(platform?: string): {
120
+ readonly GIT_NO_REPLACE_OBJECTS: "1";
121
+ readonly GIT_GRAFT_FILE: "NUL" | "/dev/null";
122
+ readonly GIT_TERMINAL_PROMPT: "0";
123
+ };
124
+ /** @implements A-SPEC-792.45 — the pins' type and key list come from `judgmentPins`, their one source. */
125
+ export type JudgmentPins = ReturnType<typeof judgmentPins>;
126
+ /**
127
+ * @implements A-SPEC-792.42 — the `-c` overrides for the filters and config-based hooks the configuration names, which
128
+ * no setting switches off: each filter's clean and smudge become `cat`, its process empty and required false; each
129
+ * hook's command becomes `true` (a config-based hook ran on Holmes's update-ref under core.hooksPath=/dev/null —
130
+ * measured). `filters` are the configured filter names. A name holding `=` is a named limit.
131
+ */
132
+ export declare function inertDriverArgs(cwd: string, env: NodeJS.ProcessEnv): {
133
+ args: string[];
134
+ filters: string[];
135
+ error?: string;
136
+ };
137
+ /**
138
+ * @implements A-SPEC-792.36 — the settings that make Holmes's own git children run no program the repository names
139
+ * and they can switch off: no fsmonitor hook (status ran an agent-set one), no hooks path, no attributes file, no
140
+ * untracked cache. Appended after any `GIT_CONFIG_COUNT` pairs the given environment holds; `gitEnv` passes none, and no
141
+ * GIT_CONFIG_PARAMETERS (which git reads after these pairs). A filter named in `.git/info/attributes` or a tracked
142
+ * `.gitattributes` is outside a setting's reach: `inertDriverArgs` overrides those drivers on Holmes's own writes.
143
+ */
144
+ export declare function inertGitConfig(env: NodeJS.ProcessEnv, platform?: string, opts?: {
145
+ attributes?: boolean;
146
+ }): NodeJS.ProcessEnv;
98
147
  /** Whether a failed git answer means "not judged" rather than "no repository" (round 15: a refusal is not judged too). */
99
148
  export declare function gitUnanswered(r: {
100
149
  error?: unknown;
@@ -37,15 +37,20 @@ exports.REPO_LOCATING_GIT_VARS = exports.GIT_MAX_BUFFER = exports.GIT_LONG_TIMEO
37
37
  exports.gitRootBlocked = gitRootBlocked;
38
38
  exports.noteGitFailure = noteGitFailure;
39
39
  exports.gitOnce = gitOnce;
40
+ exports.gitOnceBuffer = gitOnceBuffer;
40
41
  exports.resetGitBlocked = resetGitBlocked;
41
42
  exports.readRegularFileSync = readRegularFileSync;
43
+ exports.readSmallRegularTextSync = readSmallRegularTextSync;
42
44
  exports.readRegularTextSync = readRegularTextSync;
43
45
  exports.gitAnswerOf = gitAnswerOf;
44
46
  exports.gitEntryAbove = gitEntryAbove;
45
47
  exports.underGitPrefix = underGitPrefix;
46
48
  exports.gitEnv = gitEnv;
49
+ exports.judgmentPins = judgmentPins;
50
+ exports.inertDriverArgs = inertDriverArgs;
51
+ exports.inertGitConfig = inertGitConfig;
47
52
  exports.gitUnanswered = gitUnanswered;
48
- // @implements A-SPEC-734
53
+ // @implements A-SPEC-734, A-SPEC-222.13, A-SPEC-102.30, A-SPEC-102.31, A-SPEC-333.9
49
54
  /**
50
55
  * Bounded I/O shared by every caller on a hook, MCP or scan path (A-SPEC-734 round 12).
51
56
  *
@@ -110,9 +115,27 @@ function gitOnce(root, args, kind, opts = {}) {
110
115
  const error = Object.assign(new Error(`git ${args[0] ?? ''}: not asked — a git child for this root timed out within the last minute`), { code: 'EBLOCKED' });
111
116
  return { pid: 0, output: [null, '', ''], stdout: '', stderr: '', status: null, signal: null, error };
112
117
  }
113
- const env = gitEnv(opts.env ?? process.env);
118
+ // @implements A-SPEC-792.43 — the caller's pinned values ride after the shared environment, never through it
119
+ const env = { ...gitEnv(opts.env ?? process.env), ...pinnedOnly(opts.pinned) };
114
120
  const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: opts.cwd ?? root, input: opts.input, encoding: 'utf8', timeout: opts.timeout ?? exports.GIT_TIMEOUT_MS, killSignal: 'SIGKILL',
115
121
  maxBuffer: exports.GIT_MAX_BUFFER, windowsHide: true, env, stdio: [opts.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
122
+ // @implements A-SPEC-333.9 — `record: false`: a timeout set by the caller's own deadline is not the root's slowness
123
+ if (opts.record !== false)
124
+ noteGitFailure(root, r, kind);
125
+ return r;
126
+ }
127
+ /**
128
+ * @implements A-SPEC-222.13 — gitOnce with stdout as bytes: a batch of blobs is cut at byte offsets, so its output must
129
+ * not pass through a string first (invalid UTF-8 in one blob moved every later offset). Same memory and environment.
130
+ */
131
+ function gitOnceBuffer(root, args, kind, opts = {}) {
132
+ if (gitRootBlocked(root, kind)) {
133
+ const error = Object.assign(new Error(`git ${args[0] ?? ''}: not asked — a git child for this root timed out within the last minute`), { code: 'EBLOCKED' });
134
+ return { pid: 0, output: [null, Buffer.alloc(0), Buffer.alloc(0)], stdout: Buffer.alloc(0), stderr: Buffer.alloc(0), status: null, signal: null, error };
135
+ }
136
+ const env = { ...gitEnv(process.env), ...pinnedOnly(opts.pinned) };
137
+ const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: root, input: opts.input, timeout: exports.GIT_TIMEOUT_MS, killSignal: 'SIGKILL',
138
+ maxBuffer: exports.GIT_MAX_BUFFER, windowsHide: true, env, stdio: [opts.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
116
139
  noteGitFailure(root, r, kind);
117
140
  return r;
118
141
  }
@@ -138,6 +161,41 @@ function readRegularFileSync(p) {
138
161
  fs.closeSync(fd);
139
162
  }
140
163
  }
164
+ /**
165
+ * @implements A-SPEC-102.30 (item 8) — a small regular file, judged on the descriptor that is read: opened non-blocking
166
+ * and without following a link (where the platform can), then fstat'ed for a regular file of at most `max` bytes, so
167
+ * nothing swaps the file between the check and the read. Throws (code EINVAL or EFBIG) otherwise.
168
+ */
169
+ function readSmallRegularTextSync(p, max) {
170
+ const c = fs.constants;
171
+ const flags = c.O_RDONLY | (typeof c.O_NONBLOCK === 'number' ? c.O_NONBLOCK : 0) | (typeof c.O_NOFOLLOW === 'number' ? c.O_NOFOLLOW : 0);
172
+ const fd = fs.openSync(p, flags);
173
+ try {
174
+ const st = fs.fstatSync(fd);
175
+ const tooBig = () => { const err = new Error(`larger than ${max} bytes: ${p}`); err.code = 'EFBIG'; throw err; };
176
+ if (!st.isFile()) {
177
+ const err = new Error(`not a regular file: ${p}`);
178
+ err.code = 'EINVAL';
179
+ throw err;
180
+ }
181
+ if (st.size > max)
182
+ tooBig();
183
+ // @implements A-SPEC-102.31 — at most max + 1 bytes: readFileSync(fd) sized the read again, so a file that grew after
184
+ // the fstat was read whole (A, judged); one byte past the bound refuses it
185
+ const buf = Buffer.alloc(max + 1);
186
+ let n = 0;
187
+ for (let r = -1; r !== 0 && n < buf.length;) {
188
+ r = fs.readSync(fd, buf, n, buf.length - n, null);
189
+ n += r;
190
+ }
191
+ if (n > max)
192
+ tooBig();
193
+ return buf.subarray(0, n).toString('utf8');
194
+ }
195
+ finally {
196
+ fs.closeSync(fd);
197
+ }
198
+ }
141
199
  /** `readRegularFileSync` as UTF-8 text. */
142
200
  function readRegularTextSync(p) {
143
201
  return readRegularFileSync(p).toString('utf8');
@@ -201,11 +259,87 @@ function underGitPrefix(full, prefix) {
201
259
  return null;
202
260
  return have.slice(want.length).join('/');
203
261
  }
204
- /** A git child's environment: the caller's, without the variables that relocate the repository (round 17). */
205
- function gitEnv(env = process.env) {
262
+ /**
263
+ * A git child's environment: the caller's, without the variables that relocate the repository (round 17).
264
+ * @implements A-SPEC-792.42 — and without any other inherited GIT_* variable but these two: the nine relocating ones
265
+ * left GIT_CONFIG_PARAMETERS (read after the GIT_CONFIG_COUNT pairs, so it beat the inert values — measured),
266
+ * GIT_CONFIG_GLOBAL/SYSTEM, GIT_EXEC_PATH, GIT_EXTERNAL_DIFF and GIT_ATTR_SOURCE to steer Holmes's git.
267
+ */
268
+ // @implements A-SPEC-792.43 — the two its sealed text names; the judgment's own values ride after it as `pinned`
269
+ // (judgmentPins), not through this list (a NUL graft file was kept on POSIX and read a top-level `NUL` — measured)
270
+ const GIT_ENV_KEPT = new Set(['GIT_TERMINAL_PROMPT', 'GIT_CONFIG_NOSYSTEM']);
271
+ function gitEnv(env = process.env, opts = {}) {
272
+ const out = {};
273
+ for (const [k, v] of Object.entries(env))
274
+ if (!/^GIT_/i.test(k) || GIT_ENV_KEPT.has(k.toUpperCase()))
275
+ out[k] = v;
276
+ return inertGitConfig(out, process.platform, opts);
277
+ }
278
+ /**
279
+ * @implements A-SPEC-792.43 — the judgment's own git values, applied after `gitEnv` (gitOnce's `pinned`): no replace
280
+ * objects, the platform's null device as the graft file, no terminal prompt.
281
+ */
282
+ function judgmentPins(platform = process.platform) {
283
+ return { GIT_NO_REPLACE_OBJECTS: '1', GIT_GRAFT_FILE: platform === 'win32' ? 'NUL' : '/dev/null', GIT_TERMINAL_PROMPT: '0' };
284
+ }
285
+ /** @implements A-SPEC-792.44 — the only keys `pinned` carries past the sanitising, whatever a caller hands over. */
286
+ const PIN_KEYS = Object.keys(judgmentPins());
287
+ function pinnedOnly(pinned) {
288
+ const out = {};
289
+ if (pinned)
290
+ for (const k of PIN_KEYS)
291
+ out[k] = pinned[k];
292
+ return out;
293
+ }
294
+ /**
295
+ * @implements A-SPEC-792.42 — the `-c` overrides for the filters and config-based hooks the configuration names, which
296
+ * no setting switches off: each filter's clean and smudge become `cat`, its process empty and required false; each
297
+ * hook's command becomes `true` (a config-based hook ran on Holmes's update-ref under core.hooksPath=/dev/null —
298
+ * measured). `filters` are the configured filter names. A name holding `=` is a named limit.
299
+ */
300
+ function inertDriverArgs(cwd, env) {
301
+ const r = (0, node_child_process_1.spawnSync)('git', ['config', '--name-only', '--get-regexp', '^(filter|hook)\\.'], { cwd, encoding: 'utf8', env, timeout: exports.GIT_TIMEOUT_MS, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: exports.GIT_MAX_BUFFER });
302
+ // @implements A-SPEC-792.43 — a read that failed is not "none configured" (exit 1): the callers refuse rather than run
303
+ // without the overrides
304
+ if (r.error || (r.status !== 0 && r.status !== 1)) {
305
+ return { args: [], filters: [], error: `the configured filter and hook names could not be read (${r.error ? r.error.code ?? r.error.message : `exit ${r.status ?? r.signal}`})` };
306
+ }
307
+ const filters = new Set();
308
+ const hooks = new Set();
309
+ for (const line of String(r.stdout ?? '').split('\n')) {
310
+ const m = /^(filter|hook)\.(.+)\.[^.]+$/i.exec(line.trim());
311
+ if (m)
312
+ (m[1].toLowerCase() === 'filter' ? filters : hooks).add(m[2]);
313
+ }
314
+ const args = [
315
+ ...[...filters].flatMap((n) => ['clean=cat', 'smudge=cat', 'process=', 'required=false'].flatMap((kv) => ['-c', `filter.${n}.${kv}`])),
316
+ ...[...hooks].flatMap((n) => ['-c', `hook.${n}.command=true`]),
317
+ ];
318
+ return { args, filters: [...filters] };
319
+ }
320
+ /**
321
+ * @implements A-SPEC-792.36 — the settings that make Holmes's own git children run no program the repository names
322
+ * and they can switch off: no fsmonitor hook (status ran an agent-set one), no hooks path, no attributes file, no
323
+ * untracked cache. Appended after any `GIT_CONFIG_COUNT` pairs the given environment holds; `gitEnv` passes none, and no
324
+ * GIT_CONFIG_PARAMETERS (which git reads after these pairs). A filter named in `.git/info/attributes` or a tracked
325
+ * `.gitattributes` is outside a setting's reach: `inertDriverArgs` overrides those drivers on Holmes's own writes.
326
+ */
327
+ function inertGitConfig(env, platform = process.platform, opts = {}) {
328
+ const nul = platform === 'win32' ? 'NUL' : '/dev/null';
206
329
  const out = { ...env };
207
- for (const k of exports.REPO_LOCATING_GIT_VARS)
208
- delete out[k];
330
+ const n = Number.parseInt(String(out.GIT_CONFIG_COUNT ?? '0'), 10);
331
+ let i = Number.isFinite(n) && n > 0 ? n : 0;
332
+ // @implements A-SPEC-792.43 — `attributes: true` leaves core.attributesFile as configured, for a check that runs no
333
+ // program (check-attr) and so must read every attributes source
334
+ const pairs = [['core.fsmonitor', 'false'], ['core.hooksPath', nul], ...(opts.attributes ? [] : [['core.attributesFile', nul]]), ['core.untrackedCache', 'false']];
335
+ for (const [k, v] of pairs) {
336
+ out[`GIT_CONFIG_KEY_${i}`] = k;
337
+ out[`GIT_CONFIG_VALUE_${i}`] = v;
338
+ i++;
339
+ }
340
+ out.GIT_CONFIG_COUNT = String(i);
341
+ // @implements A-SPEC-792.39 — no opportunistic index rewrite (and so no post-index-change) from a status.
342
+ out.GIT_OPTIONAL_LOCKS = '0';
209
343
  return out;
210
344
  }
211
345
  /** Whether a failed git answer means "not judged" rather than "no repository" (round 15: a refusal is not judged too). */
@@ -1,3 +1,4 @@
1
+ import type { FullMode } from '../review/evidence-mode';
1
2
  /**
2
3
  * "What changed since a reference point" — the one question that genuinely needed version control,
3
4
  * behind a port with two adapters so it does not need it any more.
@@ -62,9 +63,12 @@ export declare class SnapshotChangeSource implements ChangeSource {
62
63
  constructor(root: string, label: string, opts?: {
63
64
  isIgnored?: (relPath: string) => boolean;
64
65
  verify?: string;
66
+ requireMode?: FullMode;
65
67
  });
66
68
  /** Trusted iff a baseline exists AND (no verify requested OR its digest is anchored on the chain). */
67
69
  private trustedBaseline;
70
+ /** @implements A-SPEC-128.2 — anchored, but not as a full run's tree. */
71
+ private notFromFullRun;
68
72
  changes(): ChangeSet | null;
69
73
  describe(): ChangeSourceInfo;
70
74
  }
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.EMPTY_CHANGE_SET = exports.GitChangeSource = exports.SnapshotChangeSource = exports.hashOf = exports.isDerivedState = void 0;
37
37
  exports.hashTree = hashTree;
38
38
  exports.diffHashes = diffHashes;
39
- // @implements A-SPEC-128, A-SPEC-734
39
+ // @implements A-SPEC-128, A-SPEC-734, A-SPEC-794.58, A-SPEC-128.2, A-SPEC-128.5
40
40
  const fs = __importStar(require("node:fs"));
41
41
  const path = __importStar(require("node:path"));
42
42
  const node_crypto_1 = require("node:crypto");
@@ -134,6 +134,8 @@ class SnapshotChangeSource {
134
134
  // @implements A-SPEC-134 — `verify` is the provenance ledger path. When set, a baseline whose
135
135
  // digest is not anchored on the chain (tampered, or written unanchored) is treated as ABSENT:
136
136
  // a forged narrowing must never be honored. Omitted (pure unit tests) → today's behavior.
137
+ // @implements A-SPEC-128.2 — `requireMode: 'full'` (with `verify`): only an anchor that says a full run verified the
138
+ // tree is trusted; a scoped green or a legacy anchor degrades to full scope.
137
139
  opts = {}) {
138
140
  this.root = root;
139
141
  this.label = label;
@@ -144,10 +146,14 @@ class SnapshotChangeSource {
144
146
  const baseline = (0, baseline_1.readBaseline)(this.root, this.label);
145
147
  if (!baseline)
146
148
  return null;
147
- if (this.opts.verify && !(0, baseline_1.isBaselineTrusted)(this.root, this.label, this.opts.verify))
149
+ if (this.opts.verify && !(0, baseline_1.isBaselineTrusted)(this.root, this.label, this.opts.verify, { requireMode: this.opts.requireMode }))
148
150
  return null;
149
151
  return baseline;
150
152
  }
153
+ /** @implements A-SPEC-128.2 — anchored, but not as a full run's tree. */
154
+ notFromFullRun() {
155
+ return !!this.opts.verify && !!this.opts.requireMode && (0, baseline_1.isBaselineTrusted)(this.root, this.label, this.opts.verify);
156
+ }
151
157
  changes() {
152
158
  const baseline = this.trustedBaseline();
153
159
  if (!baseline)
@@ -164,9 +170,11 @@ class SnapshotChangeSource {
164
170
  detectsRenames: false,
165
171
  available: trusted !== null,
166
172
  ...(trusted ? {} : {
167
- reason: tampered
168
- ? `baseline "${this.label}" failed its integrity check (not anchored on the provenance chain) — treating as absent, full scope`
169
- : `no baseline named "${this.label}" — run a passing test_run, or take one explicitly`,
173
+ reason: tampered && this.notFromFullRun()
174
+ ? `baseline "${this.label}" is not from a full run (its anchor does not say mode:full) — treating as absent, full scope`
175
+ : tampered
176
+ ? `baseline "${this.label}" failed its integrity check (not anchored on the provenance chain) — treating as absent, full scope`
177
+ : `no baseline named "${this.label}" — run a passing full test_run, or take one explicitly`,
170
178
  }),
171
179
  };
172
180
  }
@@ -195,7 +203,7 @@ class GitChangeSource {
195
203
  // (even one that walks up to the same `.ax`) would tag paths against the wrong base. Both sides
196
204
  // go through ONE canonicaliser: the old `fs.realpathSync(root)` here was the JS realpath, which
197
205
  // keeps Windows 8.3 aliases the top-level side had already expanded — measured 2026-08-23, the
198
- // same directory spelled `C:\AI_PRO~1\…` threw as a mismatch.
206
+ // same directory spelled `C:\WORKSP~1\…` threw as a mismatch.
199
207
  if (this.topLevel && (0, root_1.canonicalPath)(path.resolve(root)) !== this.topLevel) {
200
208
  throw new Error(`GitChangeSource: root must be the git top-level (got ${root}, top-level is ${this.topLevel})`);
201
209
  }
@@ -0,0 +1,10 @@
1
+ export declare const INSTANCE_ID_RELPATH = ".ax/state/instance-id.json";
2
+ /** Points where a test pauses this creator while another runs. */
3
+ export interface InstanceIdHooks {
4
+ beforePublish?: () => void;
5
+ beforeAside?: () => void;
6
+ }
7
+ /** The instance id, or null when it is absent, malformed or another directory's. Never writes. */
8
+ export declare function readInstanceId(root: string): string | null;
9
+ /** This clone's instance id, created when absent or mismatched. Refuses without an existing `.ax`. */
10
+ export declare function ensureInstanceId(root: string, hooks?: InstanceIdHooks): string;