@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
@@ -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,17 @@ 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;
50
51
  }): SpawnSyncReturns<string>;
52
+ /**
53
+ * @implements A-SPEC-222.13 — gitOnce with stdout as bytes: a batch of blobs is cut at byte offsets, so its output must
54
+ * not pass through a string first (invalid UTF-8 in one blob moved every later offset). Same memory and environment.
55
+ */
56
+ export declare function gitOnceBuffer(root: string, args: string[], kind: GitKind, opts?: {
57
+ input?: string;
58
+ pinned?: JudgmentPins;
59
+ }): SpawnSyncReturns<Buffer>;
51
60
  /** Test seam: forget every blocked root. */
52
61
  export declare function resetGitBlocked(): void;
53
62
  /**
@@ -56,6 +65,12 @@ export declare function resetGitBlocked(): void;
56
65
  * such as `/dev/zero` included). Throws like `readFileSync` does, so callers keep their error handling.
57
66
  */
58
67
  export declare function readRegularFileSync(p: string): Buffer;
68
+ /**
69
+ * @implements A-SPEC-102.30 (item 8) — a small regular file, judged on the descriptor that is read: opened non-blocking
70
+ * and without following a link (where the platform can), then fstat'ed for a regular file of at most `max` bytes, so
71
+ * nothing swaps the file between the check and the read. Throws (code EINVAL or EFBIG) otherwise.
72
+ */
73
+ export declare function readSmallRegularTextSync(p: string, max: number): string;
59
74
  /** `readRegularFileSync` as UTF-8 text. */
60
75
  export declare function readRegularTextSync(p: string): string;
61
76
  /**
@@ -93,8 +108,41 @@ export declare const REPO_LOCATING_GIT_VARS: readonly ["GIT_DIR", "GIT_WORK_TREE
93
108
  * a case-folding disk read clean (measured).
94
109
  */
95
110
  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;
111
+ export declare function gitEnv(env?: NodeJS.ProcessEnv, opts?: {
112
+ attributes?: boolean;
113
+ }): NodeJS.ProcessEnv;
114
+ /**
115
+ * @implements A-SPEC-792.43 — the judgment's own git values, applied after `gitEnv` (gitOnce's `pinned`): no replace
116
+ * objects, the platform's null device as the graft file, no terminal prompt.
117
+ */
118
+ export declare function judgmentPins(platform?: string): {
119
+ readonly GIT_NO_REPLACE_OBJECTS: "1";
120
+ readonly GIT_GRAFT_FILE: "NUL" | "/dev/null";
121
+ readonly GIT_TERMINAL_PROMPT: "0";
122
+ };
123
+ /** @implements A-SPEC-792.45 — the pins' type and key list come from `judgmentPins`, their one source. */
124
+ export type JudgmentPins = ReturnType<typeof judgmentPins>;
125
+ /**
126
+ * @implements A-SPEC-792.42 — the `-c` overrides for the filters and config-based hooks the configuration names, which
127
+ * no setting switches off: each filter's clean and smudge become `cat`, its process empty and required false; each
128
+ * hook's command becomes `true` (a config-based hook ran on Holmes's update-ref under core.hooksPath=/dev/null —
129
+ * measured). `filters` are the configured filter names. A name holding `=` is a named limit.
130
+ */
131
+ export declare function inertDriverArgs(cwd: string, env: NodeJS.ProcessEnv): {
132
+ args: string[];
133
+ filters: string[];
134
+ error?: string;
135
+ };
136
+ /**
137
+ * @implements A-SPEC-792.36 — the settings that make Holmes's own git children run no program the repository names
138
+ * and they can switch off: no fsmonitor hook (status ran an agent-set one), no hooks path, no attributes file, no
139
+ * untracked cache. Appended after any `GIT_CONFIG_COUNT` pairs the given environment holds; `gitEnv` passes none, and no
140
+ * GIT_CONFIG_PARAMETERS (which git reads after these pairs). A filter named in `.git/info/attributes` or a tracked
141
+ * `.gitattributes` is outside a setting's reach: `inertDriverArgs` overrides those drivers on Holmes's own writes.
142
+ */
143
+ export declare function inertGitConfig(env: NodeJS.ProcessEnv, platform?: string, opts?: {
144
+ attributes?: boolean;
145
+ }): NodeJS.ProcessEnv;
98
146
  /** Whether a failed git answer means "not judged" rather than "no repository" (round 15: a refusal is not judged too). */
99
147
  export declare function gitUnanswered(r: {
100
148
  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
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,12 +115,28 @@ 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'] });
116
122
  noteGitFailure(root, r, kind);
117
123
  return r;
118
124
  }
125
+ /**
126
+ * @implements A-SPEC-222.13 — gitOnce with stdout as bytes: a batch of blobs is cut at byte offsets, so its output must
127
+ * not pass through a string first (invalid UTF-8 in one blob moved every later offset). Same memory and environment.
128
+ */
129
+ function gitOnceBuffer(root, args, kind, opts = {}) {
130
+ if (gitRootBlocked(root, kind)) {
131
+ 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' });
132
+ return { pid: 0, output: [null, Buffer.alloc(0), Buffer.alloc(0)], stdout: Buffer.alloc(0), stderr: Buffer.alloc(0), status: null, signal: null, error };
133
+ }
134
+ const env = { ...gitEnv(process.env), ...pinnedOnly(opts.pinned) };
135
+ const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: root, input: opts.input, timeout: exports.GIT_TIMEOUT_MS, killSignal: 'SIGKILL',
136
+ maxBuffer: exports.GIT_MAX_BUFFER, windowsHide: true, env, stdio: [opts.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
137
+ noteGitFailure(root, r, kind);
138
+ return r;
139
+ }
119
140
  /** Test seam: forget every blocked root. */
120
141
  function resetGitBlocked() { BLOCKED.clear(); }
121
142
  /**
@@ -138,6 +159,41 @@ function readRegularFileSync(p) {
138
159
  fs.closeSync(fd);
139
160
  }
140
161
  }
162
+ /**
163
+ * @implements A-SPEC-102.30 (item 8) — a small regular file, judged on the descriptor that is read: opened non-blocking
164
+ * and without following a link (where the platform can), then fstat'ed for a regular file of at most `max` bytes, so
165
+ * nothing swaps the file between the check and the read. Throws (code EINVAL or EFBIG) otherwise.
166
+ */
167
+ function readSmallRegularTextSync(p, max) {
168
+ const c = fs.constants;
169
+ const flags = c.O_RDONLY | (typeof c.O_NONBLOCK === 'number' ? c.O_NONBLOCK : 0) | (typeof c.O_NOFOLLOW === 'number' ? c.O_NOFOLLOW : 0);
170
+ const fd = fs.openSync(p, flags);
171
+ try {
172
+ const st = fs.fstatSync(fd);
173
+ const tooBig = () => { const err = new Error(`larger than ${max} bytes: ${p}`); err.code = 'EFBIG'; throw err; };
174
+ if (!st.isFile()) {
175
+ const err = new Error(`not a regular file: ${p}`);
176
+ err.code = 'EINVAL';
177
+ throw err;
178
+ }
179
+ if (st.size > max)
180
+ tooBig();
181
+ // @implements A-SPEC-102.31 — at most max + 1 bytes: readFileSync(fd) sized the read again, so a file that grew after
182
+ // the fstat was read whole (A, judged); one byte past the bound refuses it
183
+ const buf = Buffer.alloc(max + 1);
184
+ let n = 0;
185
+ for (let r = -1; r !== 0 && n < buf.length;) {
186
+ r = fs.readSync(fd, buf, n, buf.length - n, null);
187
+ n += r;
188
+ }
189
+ if (n > max)
190
+ tooBig();
191
+ return buf.subarray(0, n).toString('utf8');
192
+ }
193
+ finally {
194
+ fs.closeSync(fd);
195
+ }
196
+ }
141
197
  /** `readRegularFileSync` as UTF-8 text. */
142
198
  function readRegularTextSync(p) {
143
199
  return readRegularFileSync(p).toString('utf8');
@@ -201,11 +257,87 @@ function underGitPrefix(full, prefix) {
201
257
  return null;
202
258
  return have.slice(want.length).join('/');
203
259
  }
204
- /** A git child's environment: the caller's, without the variables that relocate the repository (round 17). */
205
- function gitEnv(env = process.env) {
260
+ /**
261
+ * A git child's environment: the caller's, without the variables that relocate the repository (round 17).
262
+ * @implements A-SPEC-792.42 — and without any other inherited GIT_* variable but these two: the nine relocating ones
263
+ * left GIT_CONFIG_PARAMETERS (read after the GIT_CONFIG_COUNT pairs, so it beat the inert values — measured),
264
+ * GIT_CONFIG_GLOBAL/SYSTEM, GIT_EXEC_PATH, GIT_EXTERNAL_DIFF and GIT_ATTR_SOURCE to steer Holmes's git.
265
+ */
266
+ // @implements A-SPEC-792.43 — the two its sealed text names; the judgment's own values ride after it as `pinned`
267
+ // (judgmentPins), not through this list (a NUL graft file was kept on POSIX and read a top-level `NUL` — measured)
268
+ const GIT_ENV_KEPT = new Set(['GIT_TERMINAL_PROMPT', 'GIT_CONFIG_NOSYSTEM']);
269
+ function gitEnv(env = process.env, opts = {}) {
270
+ const out = {};
271
+ for (const [k, v] of Object.entries(env))
272
+ if (!/^GIT_/i.test(k) || GIT_ENV_KEPT.has(k.toUpperCase()))
273
+ out[k] = v;
274
+ return inertGitConfig(out, process.platform, opts);
275
+ }
276
+ /**
277
+ * @implements A-SPEC-792.43 — the judgment's own git values, applied after `gitEnv` (gitOnce's `pinned`): no replace
278
+ * objects, the platform's null device as the graft file, no terminal prompt.
279
+ */
280
+ function judgmentPins(platform = process.platform) {
281
+ return { GIT_NO_REPLACE_OBJECTS: '1', GIT_GRAFT_FILE: platform === 'win32' ? 'NUL' : '/dev/null', GIT_TERMINAL_PROMPT: '0' };
282
+ }
283
+ /** @implements A-SPEC-792.44 — the only keys `pinned` carries past the sanitising, whatever a caller hands over. */
284
+ const PIN_KEYS = Object.keys(judgmentPins());
285
+ function pinnedOnly(pinned) {
286
+ const out = {};
287
+ if (pinned)
288
+ for (const k of PIN_KEYS)
289
+ out[k] = pinned[k];
290
+ return out;
291
+ }
292
+ /**
293
+ * @implements A-SPEC-792.42 — the `-c` overrides for the filters and config-based hooks the configuration names, which
294
+ * no setting switches off: each filter's clean and smudge become `cat`, its process empty and required false; each
295
+ * hook's command becomes `true` (a config-based hook ran on Holmes's update-ref under core.hooksPath=/dev/null —
296
+ * measured). `filters` are the configured filter names. A name holding `=` is a named limit.
297
+ */
298
+ function inertDriverArgs(cwd, env) {
299
+ 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 });
300
+ // @implements A-SPEC-792.43 — a read that failed is not "none configured" (exit 1): the callers refuse rather than run
301
+ // without the overrides
302
+ if (r.error || (r.status !== 0 && r.status !== 1)) {
303
+ 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}`})` };
304
+ }
305
+ const filters = new Set();
306
+ const hooks = new Set();
307
+ for (const line of String(r.stdout ?? '').split('\n')) {
308
+ const m = /^(filter|hook)\.(.+)\.[^.]+$/i.exec(line.trim());
309
+ if (m)
310
+ (m[1].toLowerCase() === 'filter' ? filters : hooks).add(m[2]);
311
+ }
312
+ const args = [
313
+ ...[...filters].flatMap((n) => ['clean=cat', 'smudge=cat', 'process=', 'required=false'].flatMap((kv) => ['-c', `filter.${n}.${kv}`])),
314
+ ...[...hooks].flatMap((n) => ['-c', `hook.${n}.command=true`]),
315
+ ];
316
+ return { args, filters: [...filters] };
317
+ }
318
+ /**
319
+ * @implements A-SPEC-792.36 — the settings that make Holmes's own git children run no program the repository names
320
+ * and they can switch off: no fsmonitor hook (status ran an agent-set one), no hooks path, no attributes file, no
321
+ * untracked cache. Appended after any `GIT_CONFIG_COUNT` pairs the given environment holds; `gitEnv` passes none, and no
322
+ * GIT_CONFIG_PARAMETERS (which git reads after these pairs). A filter named in `.git/info/attributes` or a tracked
323
+ * `.gitattributes` is outside a setting's reach: `inertDriverArgs` overrides those drivers on Holmes's own writes.
324
+ */
325
+ function inertGitConfig(env, platform = process.platform, opts = {}) {
326
+ const nul = platform === 'win32' ? 'NUL' : '/dev/null';
206
327
  const out = { ...env };
207
- for (const k of exports.REPO_LOCATING_GIT_VARS)
208
- delete out[k];
328
+ const n = Number.parseInt(String(out.GIT_CONFIG_COUNT ?? '0'), 10);
329
+ let i = Number.isFinite(n) && n > 0 ? n : 0;
330
+ // @implements A-SPEC-792.43 — `attributes: true` leaves core.attributesFile as configured, for a check that runs no
331
+ // program (check-attr) and so must read every attributes source
332
+ const pairs = [['core.fsmonitor', 'false'], ['core.hooksPath', nul], ...(opts.attributes ? [] : [['core.attributesFile', nul]]), ['core.untrackedCache', 'false']];
333
+ for (const [k, v] of pairs) {
334
+ out[`GIT_CONFIG_KEY_${i}`] = k;
335
+ out[`GIT_CONFIG_VALUE_${i}`] = v;
336
+ i++;
337
+ }
338
+ out.GIT_CONFIG_COUNT = String(i);
339
+ // @implements A-SPEC-792.39 — no opportunistic index rewrite (and so no post-index-change) from a status.
340
+ out.GIT_OPTIONAL_LOCKS = '0';
209
341
  return out;
210
342
  }
211
343
  /** Whether a failed git answer means "not judged" rather than "no repository" (round 15: a refusal is not judged too). */
@@ -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
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");
@@ -195,7 +195,7 @@ class GitChangeSource {
195
195
  // (even one that walks up to the same `.ax`) would tag paths against the wrong base. Both sides
196
196
  // go through ONE canonicaliser: the old `fs.realpathSync(root)` here was the JS realpath, which
197
197
  // 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.
198
+ // same directory spelled `C:\WORKSP~1\…` threw as a mismatch.
199
199
  if (this.topLevel && (0, root_1.canonicalPath)(path.resolve(root)) !== this.topLevel) {
200
200
  throw new Error(`GitChangeSource: root must be the git top-level (got ${root}, top-level is ${this.topLevel})`);
201
201
  }
@@ -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;