@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
@@ -36,18 +36,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.FULL_PROFILE_SCHEMA = exports.FULL_PROFILE_FILE = void 0;
37
37
  exports.readFullProfile = readFullProfile;
38
38
  exports.fullSealVerdict = fullSealVerdict;
39
+ exports.onlyStagesSpecs = onlyStagesSpecs;
39
40
  exports.fullModeShellVerdict = fullModeShellVerdict;
41
+ exports.fullModeOutwardRefusal = fullModeOutwardRefusal;
40
42
  exports.fullModeRefusalTail = fullModeRefusalTail;
41
43
  exports.writeRecoveryRef = writeRecoveryRef;
42
44
  exports.addFullProfileEntry = addFullProfileEntry;
43
45
  exports.removeFullProfileEntry = removeFullProfileEntry;
44
- // @implements A-SPEC-792.3, A-SPEC-792.4, A-SPEC-792.5
46
+ // @implements A-SPEC-794.57, A-SPEC-794.55, A-SPEC-792.3, A-SPEC-792.4, A-SPEC-792.5, A-SPEC-794.49, A-SPEC-794.50, A-SPEC-794.51
45
47
  // The full autonomy profile (REQ-792) — the fifth envelope. The owner names, once, the scopes (a workspace or a root of
46
48
  // workspaces) where no judgment may wait for a person. It lives at user level because a benchmark copies its arm for
47
49
  // every run and a workspace-bound document (the run delegation, A-SPEC-771) does not follow the copy. The CLI writes it
48
50
  // under operator proof; the gate protects it as user config (A-SPEC-728); anything malformed covers nothing.
49
51
  const fs = __importStar(require("node:fs"));
50
52
  const path = __importStar(require("node:path"));
53
+ const bounded_io_1 = require("../project/bounded-io");
54
+ const root_1 = require("../project/root");
51
55
  exports.FULL_PROFILE_FILE = ['.holmes', 'full-autonomy.json'];
52
56
  exports.FULL_PROFILE_SCHEMA = 'full-autonomy/1';
53
57
  const ENTRY_KEYS = new Set(['scope', 'flags', 'issuedAt', 'issuedBy']);
@@ -161,6 +165,50 @@ function fullSealVerdict(rule, flags) {
161
165
  return { outcome: 'seal', mark: '' };
162
166
  }
163
167
  }
168
+ /** @implements A-SPEC-794.50, A-SPEC-794.51 — what to do about an outward act the profile leaves to the owner. Issuing again replaces every flag. */
169
+ const OUTWARD_ROUTE = {
170
+ push: 'ask the owner to push, or to issue the profile again with the push flag, naming every flag it should keep',
171
+ publish: 'ask the owner to publish, or to issue the profile again with the publish flag, naming every flag it should keep',
172
+ };
173
+ /** @implements A-SPEC-792.10 — the classifier's two verdicts on staging the spec store (risk-classifier.ts). */
174
+ const STAGING_REACHES_SPECS = /^staging command reaches changed files in the protected \.ax spec store/;
175
+ const OPAQUE_AX = /^shell command over a protected \.ax governance path is not recognisably read-only/;
176
+ /**
177
+ * @implements A-SPEC-794.55, A-SPEC-794.57 — the next step after a refused sweep staging, in the order that works: a
178
+ * product-installed path staged by name stays refused, so the sweep is repeated after the person staged the specs.
179
+ */
180
+ const SWEEP_ROUTE = 'stage the spec files by their paths in a command of their own (git add <each spec path>), which goes to the person\'s approval form; once a person has staged them, the same sweep no longer reaches them';
181
+ /**
182
+ * @implements A-SPEC-792.10, A-SPEC-792.11 — whether every clause of `command` is `git add` or `git stage` whose
183
+ * pathspecs are each a literal path inside the spec store. A pipe, a glob, a quote, an option, pathspec magic (a word
184
+ * starting with `:`), a directory above the store, `git commit` or any other clause makes it not spec staging.
185
+ */
186
+ function onlyStagesSpecs(command, cwd, workspace) {
187
+ // @implements A-SPEC-792.12 — a whitelisted grammar only: plain path words joined by && or ; (a background &, a
188
+ // subshell, a comment, a substitution, a quote or a glob is never read as staging)
189
+ if (/[^A-Za-z0-9\s;\-_./+,=@]/.test(command.replace(/&&/g, ' ')))
190
+ return false;
191
+ if (/\||[<>]/.test(command))
192
+ return false;
193
+ const store = path.join(realOrNull(workspace) ?? workspace, '.ax', 'specs');
194
+ const clauses = command.split(/&&|[;\n]/).map((c) => c.trim()).filter(Boolean);
195
+ if (clauses.length === 0)
196
+ return false;
197
+ return clauses.every((clause) => {
198
+ const words = clause.split(/\s+/);
199
+ if (words[0] !== 'git')
200
+ return false;
201
+ if (words[1] !== 'add' && words[1] !== 'stage')
202
+ return false;
203
+ const specs = words.slice(2).filter((w) => w !== '--');
204
+ return specs.length > 0 && specs.every((w) => {
205
+ if (w.startsWith('-') || w.startsWith(':') || UNPROVABLE.test(w) || /["']/.test(w))
206
+ return false;
207
+ const real = entryReal(cwd, w);
208
+ return real !== null && covers(store, real);
209
+ });
210
+ });
211
+ }
164
212
  /** Reasons a full scope may approve, by the classifier's own words (risk-classifier.ts), with whether a ref is needed. */
165
213
  const WORKSPACE_GIT_ACTS = [/^git reset --hard\b/, /^git clean -f\b/, /^git restore\/checkout \./, /^git branch -D\b/];
166
214
  const RM_ACTS = [/^recursive rm of a catastrophic/, /^rm -rf of an unverified target/];
@@ -208,11 +256,21 @@ function fullModeShellVerdict(input) {
208
256
  if (ELSEWHERE.test(command)) {
209
257
  return { outcome: 'refuse', route: 'the command changes directory or names another work tree, so where it lands cannot be proven — run the act from the workspace without cd, pushd or git -C' };
210
258
  }
259
+ // @implements A-SPEC-792.10 — owner decision 2026-10-23 10:59: staging changed spec files goes to the person's
260
+ // approval form, as without a profile — never approved here, never refused for good.
261
+ if (reasons.length > 0 && reasons.every((r) => STAGING_REACHES_SPECS.test(r) || OPAQUE_AX.test(r))
262
+ && onlyStagesSpecs(command, input.cwd, input.workspace)) {
263
+ return { outcome: 'ask' };
264
+ }
265
+ // @implements A-SPEC-794.55 — a staging that sweeps changed spec files (`git add -A`, `git add .`) is the first thing
266
+ // a session does after init; its refusal says how to get the same staging done
267
+ if (reasons.length > 0 && reasons.every((r) => STAGING_REACHES_SPECS.test(r)))
268
+ return { outcome: 'refuse', route: SWEEP_ROUTE };
211
269
  let recovery = false;
212
270
  for (const reason of reasons) {
213
271
  if (/^git push --force/.test(reason)) {
214
272
  if (!entry.flags.push)
215
- return { outcome: 'refuse', route: 'this full profile keeps force pushes with the owner (issued without --allow-push)' };
273
+ return { outcome: 'refuse', route: OUTWARD_ROUTE.push };
216
274
  continue;
217
275
  }
218
276
  if (WORKSPACE_GIT_ACTS.some((re) => re.test(reason))) {
@@ -241,6 +299,14 @@ function fullModeShellVerdict(input) {
241
299
  }
242
300
  return { outcome: 'approve', recovery };
243
301
  }
302
+ /** @implements A-SPEC-794.49, A-SPEC-794.50 — REQ-792's flags: what to do about the first outward act this profile leaves to the owner, or null. */
303
+ function fullModeOutwardRefusal(acts, entry) {
304
+ if (acts.includes('push') && !entry.flags.push)
305
+ return OUTWARD_ROUTE.push;
306
+ if (acts.includes('publish') && !entry.flags.publish)
307
+ return OUTWARD_ROUTE.publish;
308
+ return null;
309
+ }
244
310
  /** The tail a full-scope refusal carries instead of a queued request (config, secrets, approvals, code under debt). */
245
311
  function fullModeRefusalTail(kind, route) {
246
312
  const why = route ?? (kind === 'code-write'
@@ -256,20 +322,50 @@ function fullModeRefusalTail(kind, route) {
256
322
  function writeRecoveryRef(workspace, now) {
257
323
  const { execFileSync } = require('node:child_process');
258
324
  const os = require('node:os');
259
- const run = (args, env) => execFileSync('git', args, {
260
- cwd: workspace, encoding: 'utf8', timeout: 20_000, maxBuffer: 4 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
261
- env: { ...process.env, ...env, GIT_TERMINAL_PROMPT: '0' },
262
- }).trim();
325
+ // @implements A-SPEC-792.39, A-SPEC-792.42 — the shared inert environment (no inherited GIT_* variable, no fsmonitor,
326
+ // hooks path or attributes file), only the temporary index added; the filters and config-based hooks the
327
+ // configuration names are overridden on every call (write-tree re-hashes a racily clean entry through the clean
328
+ // filter too, and a config-based reference-transaction hook ran on update-ref — both measured).
329
+ const base = (0, bounded_io_1.gitEnv)((0, root_1.cleanSubprocessEnv)());
330
+ const drivers = (0, bounded_io_1.inertDriverArgs)(workspace, base);
331
+ // @implements A-SPEC-792.43 — a driver list that could not be read is no recovery point (it ran without overrides)
332
+ if (drivers.error)
333
+ return { error: `the recovery point was not written: ${drivers.error}` };
334
+ const { args: inert, filters } = drivers;
335
+ const raw = (args, env, input, whole) => execFileSync('git', [...inert, ...args], {
336
+ cwd: workspace, encoding: 'utf8', timeout: 20_000, maxBuffer: 64 * 1024 * 1024, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
337
+ env: { ...(whole ?? base), ...env, GIT_TERMINAL_PROMPT: '0' }, ...(input === undefined ? {} : { input }),
338
+ });
339
+ const run = (args, env) => raw(args, env).trim();
263
340
  let step = 'git rev-parse HEAD';
264
341
  const index = path.join(os.tmpdir(), `holmes-full-${process.pid}-${Date.now()}.index`);
265
342
  try {
266
343
  const head = run(['rev-parse', '--verify', 'HEAD']);
344
+ // @implements A-SPEC-792.42 — the snapshot hashes every file of the tree with the filters overridden, so a path
345
+ // that selects a configured filter would be stored unfiltered (a git-crypt file as plaintext, an LFS file whole):
346
+ // no recovery point is written then, and the error names the paths
347
+ if (filters.length > 0) {
348
+ step = 'git check-attr filter';
349
+ // @implements A-SPEC-792.43 — untrimmed (a trim cut a first path's leading space and failed open), and check-attr
350
+ // reads every attributes source: it runs no program, and core.attributesFile or $XDG_CONFIG_HOME/git/attributes
351
+ // selected a filter the nulled setting hid (measured)
352
+ const paths = raw(['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
353
+ const attrs = paths === '' ? [] : raw(['check-attr', '-z', '--stdin', 'filter'], undefined, paths, (0, bounded_io_1.gitEnv)((0, root_1.cleanSubprocessEnv)(), { attributes: true })).split('\0');
354
+ const selected = [];
355
+ for (let i = 0; i + 2 < attrs.length; i += 3)
356
+ if (filters.includes(attrs[i + 2]))
357
+ selected.push(attrs[i]);
358
+ if (selected.length > 0) {
359
+ const shown = selected.slice(0, 5).join(', ') + (selected.length > 5 ? `, … (${selected.length} in all)` : '');
360
+ return { error: `the recovery point was not written: ${selected.length} path(s) select a configured filter (${filters.join(', ')}), and a snapshot would store their bytes unfiltered (for git-crypt, plaintext): ${shown}` };
361
+ }
362
+ }
267
363
  step = 'git add -A (temporary index)';
268
364
  run(['add', '-A'], { GIT_INDEX_FILE: index });
269
365
  step = 'git write-tree';
270
366
  const tree = run(['write-tree'], { GIT_INDEX_FILE: index });
271
367
  step = 'git commit-tree';
272
- const commit = run(['commit-tree', tree, '-p', head, '-m', `holmes full-autonomy recovery point ${now}`], { GIT_AUTHOR_NAME: 'holmes-kit', GIT_AUTHOR_EMAIL: 'holmes-kit@localhost', GIT_COMMITTER_NAME: 'holmes-kit', GIT_COMMITTER_EMAIL: 'holmes-kit@localhost' });
368
+ const commit = run(['commit-tree', '--no-gpg-sign', tree, '-p', head, '-m', `holmes full-autonomy recovery point ${now}`], { GIT_AUTHOR_NAME: 'holmes-kit', GIT_AUTHOR_EMAIL: 'holmes-kit@localhost', GIT_COMMITTER_NAME: 'holmes-kit', GIT_COMMITTER_EMAIL: 'holmes-kit@localhost' });
273
369
  step = 'git update-ref';
274
370
  const ref = `refs/holmes/full/${now.replace(/[^0-9TZ]/g, '')}-${commit.slice(0, 8)}`;
275
371
  run(['update-ref', ref, commit]);
@@ -0,0 +1,103 @@
1
+ export interface HarnessCatalog {
2
+ /** Environment variables an agent's tools set; one set and non-empty marks an agent's process. */
3
+ readonly markers: readonly string[];
4
+ /** Prefixes of such variables (agy: which one its shell tool sets was not measured). */
5
+ readonly markerPrefixes: readonly string[];
6
+ /** Executable names (lowercase, `.exe` dropped) of agent processes among the parents. */
7
+ readonly ancestors: readonly string[];
8
+ /** Path segments (`a/b`) that, in a process's arguments, name an agent's installed layout. */
9
+ readonly ancestorPaths: readonly string[];
10
+ /**
11
+ * @implements A-SPEC-102.28, A-SPEC-102.29 — the files each added marker, prefix or name came from, per category and in
12
+ * maps with no prototype (absent for the defaults; one name keyed across categories gave a built-in harness a file).
13
+ * @implements A-SPEC-102.30 — every file that added it, in reading order (the user's file alone hid the project's)
14
+ */
15
+ readonly sources?: Readonly<Record<SourceCategory, Readonly<Record<string, readonly string[]>>>>;
16
+ }
17
+ export type SourceCategory = 'markers' | 'markerPrefixes' | 'ancestors';
18
+ /**
19
+ * @implements A-SPEC-102.30 — the project an act works on, or an act that names none, said so explicitly: an optional
20
+ * root let "no root" pass silently, the path the high finding of 06:06 came through.
21
+ */
22
+ export type ActRoot = string | {
23
+ readonly root: null;
24
+ readonly reason: string;
25
+ };
26
+ /** @implements A-SPEC-102.30 — a given root whose project or main checkout cannot be resolved: the act is refused. */
27
+ export declare class CatalogRootError extends Error {
28
+ }
29
+ /** @implements A-SPEC-102.31 (low 8) — how such a refusal begins, so the guard words it apart from an agent harness */
30
+ export declare const CATALOG_ROOT_FAILURE = "the act's project could not be resolved";
31
+ /** @implements A-SPEC-102.31 — the one remedy, in the refusal and in doctor's row */
32
+ export declare const CATALOG_ROOT_FIX = "Make the checkout's .git a readable worktree pointer whose entry points back (or the repository's own .git directory), or act on the main checkout.";
33
+ /** @implements A-SPEC-102.29 — a file path or key as a text shows it: control characters escaped, so a file in reach of an
34
+ * agent cannot clear a person's screen or print a false PASS in doctor or a refusal. @implements A-SPEC-102.30 — and the
35
+ * bidi controls, zero-width marks and line separators, which reorder or break a line without being control characters. */
36
+ export declare function printable(s: string): string;
37
+ /** The package's catalog. */
38
+ export declare function defaultCatalog(): HarnessCatalog;
39
+ /**
40
+ * The defaults with the additions of the user's and the project's files. A file that is absent adds nothing; one that
41
+ * cannot be read or tries more than adding is refused whole, and its reason is returned.
42
+ */
43
+ export declare function loadHarnessCatalog(where: {
44
+ home?: string | readonly string[];
45
+ root?: string | readonly string[];
46
+ }): {
47
+ catalog: HarnessCatalog;
48
+ refused: Array<{
49
+ file: string;
50
+ reason: string;
51
+ }>;
52
+ };
53
+ /**
54
+ * @implements A-SPEC-102.31 — the directories whose `.ax/harness-catalog.json` hold a root's project files (below).
55
+ * @implements A-SPEC-102.30 (items 2, 5) — the directory whose `.ax/harness-catalog.json` holds a root's project file: the
56
+ * root's `.ax` project, mapped to the same place under the main checkout of the checkout holding it, so a nested project
57
+ * (`pkg/.ax`) is read, in a worktree too. A root that cannot be resolved throws CatalogRootError, naming the path: an
58
+ * unreadable worktree pointer dropped the project's additions with no signal, and doctor said PASS (B).
59
+ */
60
+ export declare function projectCatalogRoots(root: string): string[];
61
+ /**
62
+ * @implements A-SPEC-102.30 (item 4) — the account's homes: `$HOME` (os.homedir) and the passwd entry's (os.userInfo),
63
+ * each resolved on its own. The agent chooses `$HOME`, so `HOME=/tmp/x holmes approve --grant` stepped around the user
64
+ * file (A); a home that cannot be read drops only itself, never the project.
65
+ */
66
+ export declare function catalogHomes(): string[];
67
+ /**
68
+ * @implements A-SPEC-102.29 — the one root decision; no judgement reads the working directory. @implements A-SPEC-102.30
69
+ * — the root is required: an act's root, a list (autonomy full's union), or a rootless act named so; a given root that
70
+ * cannot be resolved throws CatalogRootError.
71
+ */
72
+ export declare function catalogWhere(roots: ActRoot | readonly string[]): {
73
+ home: string[];
74
+ root: string[];
75
+ };
76
+ /** The catalog a judgement of an act on `roots` uses: the defaults, this account's additions and the projects'. */
77
+ export declare function liveHarnessCatalog(roots: ActRoot | readonly string[]): HarnessCatalog;
78
+ /**
79
+ * @implements A-SPEC-102.28 — doctor's row: a refused file is shown with its reason (it was discarded), so an operator
80
+ * learns that an addition they made is not in force. @implements A-SPEC-102.29 — given the directory doctor diagnoses,
81
+ * through the one root decision, the whole computation inside the try, and the texts escaped.
82
+ */
83
+ export declare function harnessCatalogCheck(dir: string): {
84
+ name: string;
85
+ level: 'PASS' | 'WARN';
86
+ detail: string;
87
+ fix?: string;
88
+ };
89
+ /**
90
+ * @implements A-SPEC-102.28, A-SPEC-102.29 — the files that added a marker (or the prefixes it matched).
91
+ * @implements A-SPEC-102.30 (item 7) — none for a default marker or one under a default prefix: `CLAUDECODE` under an
92
+ * added `CLAUDE` was shown as the file's, though removing the file leaves the lock.
93
+ */
94
+ export declare function markerSource(marker: string, catalog: HarnessCatalog): readonly string[];
95
+ /** @implements A-SPEC-102.29, A-SPEC-102.30 — the files that added an ancestor name (a default is never recorded as one). */
96
+ export declare function ancestorSource(name: string, catalog: HarnessCatalog): readonly string[];
97
+ /** A name as a refusal shows it: an addition names its files; @implements A-SPEC-102.30 — the name escaped too (an env
98
+ * name under a default prefix is the environment's text). */
99
+ export declare function withSource(name: string, files: string | readonly string[] | undefined): string;
100
+ /** The first marker of `catalog` set and non-empty in `env`, or null. */
101
+ export declare function markerOf(env: NodeJS.ProcessEnv, catalog: HarnessCatalog): string | null;
102
+ /** The catalog's agent a process row names (its argv0, its executable, or an installed layout in its arguments), or null. */
103
+ export declare function ancestorOf(args: string, exe: string | undefined, catalog: HarnessCatalog): string | null;
@@ -0,0 +1,348 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.CATALOG_ROOT_FIX = exports.CATALOG_ROOT_FAILURE = exports.CatalogRootError = void 0;
37
+ exports.printable = printable;
38
+ exports.defaultCatalog = defaultCatalog;
39
+ exports.loadHarnessCatalog = loadHarnessCatalog;
40
+ exports.projectCatalogRoots = projectCatalogRoots;
41
+ exports.catalogHomes = catalogHomes;
42
+ exports.catalogWhere = catalogWhere;
43
+ exports.liveHarnessCatalog = liveHarnessCatalog;
44
+ exports.harnessCatalogCheck = harnessCatalogCheck;
45
+ exports.markerSource = markerSource;
46
+ exports.ancestorSource = ancestorSource;
47
+ exports.withSource = withSource;
48
+ exports.markerOf = markerOf;
49
+ exports.ancestorOf = ancestorOf;
50
+ // @implements A-SPEC-102.27, A-SPEC-102.28, A-SPEC-102.29, A-SPEC-102.30, A-SPEC-102.31, A-SPEC-102.32
51
+ /**
52
+ * The harness catalog of the operator judgement: the environment markers an agent's tools set and the names of agent
53
+ * processes among a process's parents. The package holds the defaults; a user (`<home>/.holmes/harness-catalog.json`) or
54
+ * a project (`<root>/.ax/harness-catalog.json`) may only add. An addition can only refuse more, never admit more, so a
55
+ * file in reach of an agent is no way around the judgement; a file that tries to remove or replace is refused whole.
56
+ *
57
+ * Sources (version-pinned, documentary — not measured on an install):
58
+ * - cursor-agent 2026.10.22-27dcf5f (downloads.cursor.com/lab/2026.10.22-27dcf5f/…/agent-cli-package.tar.gz, index.js):
59
+ * `CURSOR_AGENT: "1"` in its shell executor; `exec -a "$0" <dir>/node <dir>/index.js` under
60
+ * `~/.local/share/cursor-agent/versions/<version>/`.
61
+ * - opencode (github.com/anomalyco/opencode, dev at 822594b9, packages/core/src/tool/plugin/shell.ts): `OPENCODE=1`,
62
+ * `AI_AGENT=opencode` (when unset), `AGENT=1`; a binary named `opencode`.
63
+ */
64
+ const fs = __importStar(require("node:fs"));
65
+ const os = __importStar(require("node:os"));
66
+ const path = __importStar(require("node:path"));
67
+ const root_1 = require("../project/root");
68
+ const run_records_1 = require("../project/run-records");
69
+ const bounded_io_1 = require("../project/bounded-io");
70
+ /** @implements A-SPEC-102.30 — a given root whose project or main checkout cannot be resolved: the act is refused. */
71
+ class CatalogRootError extends Error {
72
+ }
73
+ exports.CatalogRootError = CatalogRootError;
74
+ /** @implements A-SPEC-102.31 (low 8) — how such a refusal begins, so the guard words it apart from an agent harness */
75
+ exports.CATALOG_ROOT_FAILURE = "the act's project could not be resolved";
76
+ /** @implements A-SPEC-102.31 — the one remedy, in the refusal and in doctor's row */
77
+ exports.CATALOG_ROOT_FIX = 'Make the checkout\'s .git a readable worktree pointer whose entry points back (or the repository\'s own .git directory), or act on the main checkout.';
78
+ /** @implements A-SPEC-102.29 — a file path or key as a text shows it: control characters escaped, so a file in reach of an
79
+ * agent cannot clear a person's screen or print a false PASS in doctor or a refusal. @implements A-SPEC-102.30 — and the
80
+ * bidi controls, zero-width marks and line separators, which reorder or break a line without being control characters. */
81
+ function printable(s) {
82
+ return s.replace(UNPRINTABLE, (c) => {
83
+ const cp = c.codePointAt(0) ?? 0;
84
+ return cp > 0xffff ? `\\u{${cp.toString(16)}}` : `\\u${cp.toString(16).padStart(4, '0')}`;
85
+ });
86
+ }
87
+ // @implements A-SPEC-102.31 (low 6) — by Unicode category: control, format (bidi, zero-width, soft hyphen, BOM, tags),
88
+ // line and paragraph separators, and lone surrogates; a list of ranges missed U+061C, U+FEFF, U+00AD and the tags (A)
89
+ const UNPRINTABLE = new RegExp('[\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\\p{Cs}]', 'gu');
90
+ /**
91
+ * The package's harnesses. claude, codex and agy are also named by the walk's own `harnessOf`; their markers are here.
92
+ * `AGENT` is no marker: other tools set it, and a person's terminal that inherits it would be refused every grant.
93
+ */
94
+ const DEFAULT_HARNESSES = [
95
+ { harness: 'claude', markers: ['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT'] },
96
+ { harness: 'codex', markers: ['CODEX_SANDBOX', 'CODEX_SANDBOX_NETWORK_DISABLED'] },
97
+ { harness: 'agy', markerPrefixes: ['ANTIGRAVITY_'] },
98
+ { harness: 'cursor-agent', markers: ['CURSOR_AGENT'], ancestors: ['cursor-agent'], ancestorPaths: ['cursor-agent/versions'] },
99
+ // @implements A-SPEC-102.28 — OPENCODE_SESSION_ID too (the supervisor's decision of 03:1x)
100
+ { harness: 'opencode', markers: ['OPENCODE', 'OPENCODE_SESSION_ID', 'AI_AGENT'], ancestors: ['opencode'] },
101
+ ];
102
+ const union = (key) => [...new Set(DEFAULT_HARNESSES.flatMap((h) => h[key] ?? []))];
103
+ const DEFAULT_CATALOG = Object.freeze({
104
+ markers: Object.freeze(union('markers')), markerPrefixes: Object.freeze(union('markerPrefixes')),
105
+ ancestors: Object.freeze(union('ancestors')), ancestorPaths: Object.freeze(union('ancestorPaths')),
106
+ });
107
+ const DEFAULT_SETS = {
108
+ markers: new Set(DEFAULT_CATALOG.markers), markerPrefixes: new Set(DEFAULT_CATALOG.markerPrefixes), ancestors: new Set(DEFAULT_CATALOG.ancestors),
109
+ };
110
+ /** The package's catalog. */
111
+ function defaultCatalog() { return DEFAULT_CATALOG; }
112
+ /** What an addition file may add, and the shape each name must have. */
113
+ const ADDABLE = {
114
+ markers: /^[A-Za-z_][A-Za-z0-9_]*$/,
115
+ markerPrefixes: /^[A-Za-z_][A-Za-z0-9_]*$/,
116
+ ancestors: /^[a-z0-9][a-z0-9._+-]*$/,
117
+ };
118
+ /** The additions a file holds, or why the whole file is refused. Never a removal or a replacement. */
119
+ function additionsOf(text) {
120
+ let parsed;
121
+ try {
122
+ parsed = JSON.parse(text);
123
+ }
124
+ catch {
125
+ return { reason: 'not JSON' };
126
+ }
127
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
128
+ return { reason: 'not an object' };
129
+ const keys = Object.keys(parsed);
130
+ if (keys.length !== 1 || keys[0] !== 'add')
131
+ return { reason: `only "add" is allowed (found ${keys.map((k) => JSON.stringify(k)).join(', ') || 'nothing'}): the defaults cannot be removed or replaced` };
132
+ const add = parsed.add;
133
+ if (!add || typeof add !== 'object' || Array.isArray(add))
134
+ return { reason: '"add" is not an object' };
135
+ const out = {};
136
+ for (const [key, value] of Object.entries(add)) {
137
+ const shape = Object.prototype.hasOwnProperty.call(ADDABLE, key) ? ADDABLE[key] : undefined;
138
+ // @implements A-SPEC-102.29 — the key quoted and escaped: it is the file's text
139
+ const shown = printable(JSON.stringify(`add.${key}`));
140
+ if (shape === undefined)
141
+ return { reason: `${shown} cannot be added to` };
142
+ if (!Array.isArray(value))
143
+ return { reason: `${shown} is not a list` };
144
+ for (const name of value)
145
+ if (typeof name !== 'string' || !shape.test(name))
146
+ return { reason: `${shown} holds ${printable(JSON.stringify(name) ?? String(name))}, which is not a name` };
147
+ out[key] = value;
148
+ }
149
+ return { add: out };
150
+ }
151
+ /**
152
+ * The defaults with the additions of the user's and the project's files. A file that is absent adds nothing; one that
153
+ * cannot be read or tries more than adding is refused whole, and its reason is returned.
154
+ */
155
+ function loadHarnessCatalog(where) {
156
+ const list = (v) => (v === undefined ? [] : typeof v === 'string' ? [v] : v);
157
+ const files = [...new Set([
158
+ ...list(where.home).filter((h) => h !== '').map((h) => path.join(h, '.holmes', 'harness-catalog.json')),
159
+ ...list(where.root).filter((r) => r !== '').map((r) => path.join(r, '.ax', 'harness-catalog.json')),
160
+ ])];
161
+ const sets = { markers: new Set(DEFAULT_CATALOG.markers), markerPrefixes: new Set(DEFAULT_CATALOG.markerPrefixes),
162
+ ancestors: new Set(DEFAULT_CATALOG.ancestors), ancestorPaths: new Set(DEFAULT_CATALOG.ancestorPaths) };
163
+ const refused = [];
164
+ const sources = {
165
+ markers: Object.create(null), markerPrefixes: Object.create(null),
166
+ ancestors: Object.create(null),
167
+ };
168
+ for (const file of files) {
169
+ let text;
170
+ // @implements A-SPEC-102.30 (item 8) — judged and read on one descriptor: no link, no FIFO, at most 64 KiB
171
+ try {
172
+ text = (0, bounded_io_1.readSmallRegularTextSync)(file, 64 * 1024);
173
+ }
174
+ catch (e) {
175
+ const code = e.code;
176
+ if (code === 'ENOENT')
177
+ continue;
178
+ refused.push({ file, reason: code === 'EFBIG' || code === 'EINVAL' || code === 'ELOOP' ? 'not a regular file of at most 64 KiB' : `unreadable (${code ?? 'error'})` });
179
+ continue;
180
+ }
181
+ const r = additionsOf(text);
182
+ if ('reason' in r) {
183
+ refused.push({ file, reason: r.reason });
184
+ continue;
185
+ }
186
+ for (const [key, names] of Object.entries(r.add)) {
187
+ // a default is never anyone's addition; every file that adds a name is listed (A-SPEC-102.30)
188
+ for (const n of names) {
189
+ if (!DEFAULT_SETS[key].has(n)) {
190
+ const had = Object.prototype.hasOwnProperty.call(sources[key], n) ? sources[key][n] : [];
191
+ if (!had.includes(file))
192
+ sources[key][n] = [...had, file];
193
+ }
194
+ sets[key].add(n);
195
+ }
196
+ }
197
+ }
198
+ const unchanged = Object.keys(sets).every((k) => sets[k].size === DEFAULT_CATALOG[k].length);
199
+ return {
200
+ catalog: unchanged ? DEFAULT_CATALOG
201
+ : { markers: [...sets.markers], markerPrefixes: [...sets.markerPrefixes], ancestors: [...sets.ancestors], ancestorPaths: [...sets.ancestorPaths], sources },
202
+ refused,
203
+ };
204
+ }
205
+ /**
206
+ * @implements A-SPEC-102.31 — the directories whose `.ax/harness-catalog.json` hold a root's project files (below).
207
+ * @implements A-SPEC-102.30 (items 2, 5) — the directory whose `.ax/harness-catalog.json` holds a root's project file: the
208
+ * root's `.ax` project, mapped to the same place under the main checkout of the checkout holding it, so a nested project
209
+ * (`pkg/.ax`) is read, in a worktree too. A root that cannot be resolved throws CatalogRootError, naming the path: an
210
+ * unreadable worktree pointer dropped the project's additions with no signal, and doctor said PASS (B).
211
+ */
212
+ function projectCatalogRoots(root) {
213
+ try {
214
+ const dir = fs.realpathSync(path.resolve(root));
215
+ if (!fs.statSync(dir).isDirectory())
216
+ throw new Error('not a directory');
217
+ const { top, main } = (0, run_records_1.checkoutOf)(dir, { strict: true });
218
+ const checkout = fs.existsSync(path.join(top, '.git'));
219
+ // @implements A-SPEC-102.31 (medium 2) — every project from the root up to the checkout top (to `/` with none), each
220
+ // read where it is and at the same place under the main checkout: the nearest `.ax` alone let `cd pkg/` step around
221
+ // the outer project's additions (A, a regression from 102.29). A path inside a `.ax` is never a project.
222
+ const inAx = (p) => p.split(path.sep).some((s) => s.toLowerCase() === root_1.MARKER.toLowerCase());
223
+ const out = [];
224
+ for (let cur = dir;; cur = path.dirname(cur)) {
225
+ if (!inAx(cur)) {
226
+ // the level where it is, and the same level under the main checkout: either side may hold the project (a
227
+ // worktree carries none of the main checkout's uncommitted `.ax`)
228
+ const rel = path.relative(top, cur);
229
+ const there = checkout && !rel.startsWith('..') && !path.isAbsolute(rel) ? (rel === '' ? main : path.join(main, rel)) : null;
230
+ for (const d of [cur, there])
231
+ if (d !== null && (0, root_1.isProjectDir)(d, { strict: true }))
232
+ out.push(d); // A-SPEC-102.32
233
+ }
234
+ if ((checkout && cur === top) || path.dirname(cur) === cur)
235
+ break;
236
+ }
237
+ return [...new Set(out)];
238
+ }
239
+ catch (e) {
240
+ throw new CatalogRootError(`${exports.CATALOG_ROOT_FAILURE} (${printable(root)}: ${printable(e.message)})`);
241
+ }
242
+ }
243
+ /**
244
+ * @implements A-SPEC-102.30 (item 4) — the account's homes: `$HOME` (os.homedir) and the passwd entry's (os.userInfo),
245
+ * each resolved on its own. The agent chooses `$HOME`, so `HOME=/tmp/x holmes approve --grant` stepped around the user
246
+ * file (A); a home that cannot be read drops only itself, never the project.
247
+ */
248
+ function catalogHomes() {
249
+ const homes = [];
250
+ try {
251
+ homes.push(os.homedir());
252
+ }
253
+ catch { /* this one cannot be read */ }
254
+ try {
255
+ homes.push(os.userInfo().homedir);
256
+ }
257
+ catch { /* nor this one */ }
258
+ return [...new Set(homes.filter((h) => typeof h === 'string' && h !== ''))];
259
+ }
260
+ /**
261
+ * @implements A-SPEC-102.29 — the one root decision; no judgement reads the working directory. @implements A-SPEC-102.30
262
+ * — the root is required: an act's root, a list (autonomy full's union), or a rootless act named so; a given root that
263
+ * cannot be resolved throws CatalogRootError.
264
+ */
265
+ function catalogWhere(roots) {
266
+ const given = typeof roots === 'string' ? [roots] : Array.isArray(roots) ? roots : [];
267
+ return { home: catalogHomes(), root: [...new Set(given.flatMap(projectCatalogRoots))] };
268
+ }
269
+ /** The catalog a judgement of an act on `roots` uses: the defaults, this account's additions and the projects'. */
270
+ function liveHarnessCatalog(roots) {
271
+ // A-SPEC-102.30 — a root that cannot be resolved refuses: it is not caught here. Loading throws nothing (every read is
272
+ // inside its own refusal), so the catch that answered the defaults is gone (M6 survived it as dead code)
273
+ return loadHarnessCatalog(catalogWhere(roots)).catalog;
274
+ }
275
+ /**
276
+ * @implements A-SPEC-102.28 — doctor's row: a refused file is shown with its reason (it was discarded), so an operator
277
+ * learns that an addition they made is not in force. @implements A-SPEC-102.29 — given the directory doctor diagnoses,
278
+ * through the one root decision, the whole computation inside the try, and the texts escaped.
279
+ */
280
+ function harnessCatalogCheck(dir) {
281
+ let refused;
282
+ try {
283
+ refused = loadHarnessCatalog(catalogWhere(dir)).refused;
284
+ }
285
+ catch (e) {
286
+ // @implements A-SPEC-102.30 — a project that cannot be resolved is WARN, never PASS: its acts are refused
287
+ if (e instanceof CatalogRootError) {
288
+ return { name: 'harness catalog', level: 'WARN', detail: `${e.message}; every operator act on it is refused`,
289
+ fix: exports.CATALOG_ROOT_FIX }; // A-SPEC-102.31 — the refusal's own remedy
290
+ }
291
+ refused = [{ file: '(catalog)', reason: e.message }];
292
+ }
293
+ if (refused.length === 0)
294
+ return { name: 'harness catalog', level: 'PASS', detail: 'the package\'s agent markers and names, with any additions in force' };
295
+ return {
296
+ name: 'harness catalog', level: 'WARN',
297
+ detail: `refused, so none of its additions apply: ${refused.map((r) => `${printable(r.file)} — ${printable(r.reason)}`).join('; ')}`,
298
+ fix: 'Write the file as {"add": {"markers": [...], "markerPrefixes": [...], "ancestors": [...]}}; the defaults cannot be removed.',
299
+ };
300
+ }
301
+ const own = (m, k) => m !== undefined && Object.prototype.hasOwnProperty.call(m, k) ? m[k] : [];
302
+ /**
303
+ * @implements A-SPEC-102.28, A-SPEC-102.29 — the files that added a marker (or the prefixes it matched).
304
+ * @implements A-SPEC-102.30 (item 7) — none for a default marker or one under a default prefix: `CLAUDECODE` under an
305
+ * added `CLAUDE` was shown as the file's, though removing the file leaves the lock.
306
+ */
307
+ function markerSource(marker, catalog) {
308
+ if (DEFAULT_SETS.markers.has(marker) || DEFAULT_CATALOG.markerPrefixes.some((p) => marker.startsWith(p)))
309
+ return [];
310
+ return [...new Set([...own(catalog.sources?.markers, marker),
311
+ ...catalog.markerPrefixes.filter((p) => marker.startsWith(p)).flatMap((p) => own(catalog.sources?.markerPrefixes, p))])];
312
+ }
313
+ /** @implements A-SPEC-102.29, A-SPEC-102.30 — the files that added an ancestor name (a default is never recorded as one). */
314
+ function ancestorSource(name, catalog) {
315
+ return own(catalog.sources?.ancestors, name);
316
+ }
317
+ /** A name as a refusal shows it: an addition names its files; @implements A-SPEC-102.30 — the name escaped too (an env
318
+ * name under a default prefix is the environment's text). */
319
+ function withSource(name, files) {
320
+ const list = files === undefined ? [] : typeof files === 'string' ? [files] : files;
321
+ return list.length > 0 ? `${printable(name)} (added by ${list.map(printable).join(', ')})` : printable(name);
322
+ }
323
+ /** The first marker of `catalog` set and non-empty in `env`, or null. */
324
+ function markerOf(env, catalog) {
325
+ const set = (k) => typeof env[k] === 'string' && env[k] !== '';
326
+ return catalog.markers.find(set)
327
+ ?? Object.keys(env).filter((k) => catalog.markerPrefixes.some((p) => k.startsWith(p)) && set(k)).sort()[0]
328
+ ?? null;
329
+ }
330
+ const baseName = (p) => path.win32.basename(path.posix.basename(p)).toLowerCase().replace(/\.exe$/, '');
331
+ /** The catalog's agent a process row names (its argv0, its executable, or an installed layout in its arguments), or null. */
332
+ function ancestorOf(args, exe, catalog) {
333
+ const words = args.trim().split(/\s+/);
334
+ const named = [words[0] ?? '', exe ?? ''].map(baseName).find((n) => n !== '' && catalog.ancestors.includes(n));
335
+ if (named !== undefined)
336
+ return named;
337
+ for (const word of words) {
338
+ const segments = word.split(/[\\/]/);
339
+ for (const layout of catalog.ancestorPaths) {
340
+ const want = layout.split('/');
341
+ for (let i = 0; i + want.length <= segments.length; i++) {
342
+ if (want.every((w, j) => segments[i + j] === w))
343
+ return want[0];
344
+ }
345
+ }
346
+ }
347
+ return null;
348
+ }