@holmes-lab/holmes-kit 0.39.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 (298) hide show
  1. package/CHANGELOG.md +344 -6
  2. package/README.md +54 -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 +202 -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.js +1 -1
  69. package/dist/holmes/cli/release-docs.js +1 -1
  70. package/dist/holmes/cli/run-exec.d.ts +141 -0
  71. package/dist/holmes/cli/run-exec.js +1435 -0
  72. package/dist/holmes/cli/run-provision.d.ts +3 -1
  73. package/dist/holmes/cli/run-provision.js +255 -44
  74. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  75. package/dist/holmes/cli/run-wiring.js +270 -0
  76. package/dist/holmes/cli/run.d.ts +21 -0
  77. package/dist/holmes/cli/run.js +341 -92
  78. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  79. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  80. package/dist/holmes/cli/screen-safe.js +18 -756
  81. package/dist/holmes/config/config.d.ts +2 -0
  82. package/dist/holmes/config/config.js +5 -2
  83. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  84. package/dist/holmes/cpg/import-resolver.js +1 -1
  85. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  86. package/dist/holmes/governance/approval-decisions.js +29 -0
  87. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  88. package/dist/holmes/governance/approval-grants.js +612 -33
  89. package/dist/holmes/governance/approval-queue.d.ts +26 -0
  90. package/dist/holmes/governance/approval-queue.js +109 -11
  91. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  92. package/dist/holmes/governance/approval-spend.js +191 -0
  93. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  94. package/dist/holmes/governance/autonomous-shell.js +332 -0
  95. package/dist/holmes/governance/autonomy.d.ts +5 -0
  96. package/dist/holmes/governance/autonomy.js +16 -11
  97. package/dist/holmes/governance/constitution.d.ts +5 -0
  98. package/dist/holmes/governance/constitution.js +32 -12
  99. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  100. package/dist/holmes/governance/full-autonomy.js +103 -7
  101. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  102. package/dist/holmes/governance/harness-catalog.js +348 -0
  103. package/dist/holmes/governance/human-channel.d.ts +38 -0
  104. package/dist/holmes/governance/human-channel.js +49 -0
  105. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  106. package/dist/holmes/governance/install-manifest.js +160 -0
  107. package/dist/holmes/governance/ledger-rechain.js +2 -0
  108. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  109. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  110. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  111. package/dist/holmes/governance/ledger-store.js +186 -8
  112. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  113. package/dist/holmes/governance/provenance-chain.js +19 -4
  114. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  115. package/dist/holmes/governance/provenance-ledger.js +53 -18
  116. package/dist/holmes/governance/push-gate-runner.js +11 -7
  117. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  118. package/dist/holmes/governance/recorded-pairs.js +522 -0
  119. package/dist/holmes/governance/replica-id.d.ts +1 -1
  120. package/dist/holmes/governance/replica-id.js +1 -1
  121. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  122. package/dist/holmes/governance/spec-seam.js +587 -0
  123. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  124. package/dist/holmes/governance/spend-kinds.js +18 -0
  125. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  126. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  127. package/dist/holmes/guardrail/impact-gate.d.ts +1 -0
  128. package/dist/holmes/guardrail/impact-gate.js +1 -1
  129. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  130. package/dist/holmes/guardrail/line-continuation.js +39 -0
  131. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  132. package/dist/holmes/guardrail/operator-person.js +57 -11
  133. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  134. package/dist/holmes/guardrail/refusal-codes.js +64 -10
  135. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  136. package/dist/holmes/guardrail/risk-classifier.js +228 -16
  137. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  138. package/dist/holmes/guardrail/risk-gate.js +7 -34
  139. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  140. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  141. package/dist/holmes/guardrail/run-refusals.js +24 -8
  142. package/dist/holmes/guardrail/run-stages.d.ts +5 -0
  143. package/dist/holmes/guardrail/run-stages.js +25 -5
  144. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  145. package/dist/holmes/guardrail/shell-words.js +24 -3
  146. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  147. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  148. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  149. package/dist/holmes/guardrail/write-target.js +26 -5
  150. package/dist/holmes/hooks/pre-tool-use.d.ts +105 -1
  151. package/dist/holmes/hooks/pre-tool-use.js +1134 -167
  152. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  153. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  154. package/dist/holmes/hooks/stop.d.ts +23 -0
  155. package/dist/holmes/hooks/stop.js +86 -33
  156. package/dist/holmes/mcp/approval-adapters.js +3 -1
  157. package/dist/holmes/mcp/approval-commit.js +3 -2
  158. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  159. package/dist/holmes/mcp/approval-policy.js +3 -1
  160. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  161. package/dist/holmes/mcp/handlers/approval-ask.d.ts +3 -0
  162. package/dist/holmes/mcp/handlers/approval-ask.js +18 -7
  163. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  164. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  165. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  166. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  167. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  168. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  169. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  170. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  171. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  172. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  173. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  174. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  175. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  176. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  177. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  178. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  179. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  180. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  181. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  182. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  183. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  184. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  185. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  186. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  187. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  188. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  189. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  190. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  191. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  192. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  193. package/dist/holmes/mcp/handlers/test-execution.d.ts +1 -1
  194. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  195. package/dist/holmes/mcp/handlers.d.ts +89 -79
  196. package/dist/holmes/mcp/handlers.js +69 -22
  197. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  198. package/dist/holmes/mcp/harness-attestation.js +325 -53
  199. package/dist/holmes/mcp/maintenance-analyze.d.ts +1 -1
  200. package/dist/holmes/mcp/maintenance-analyze.js +9 -9
  201. package/dist/holmes/mcp/maintenance-evidence.js +31 -2
  202. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  203. package/dist/holmes/mcp/server-staleness.js +1 -1
  204. package/dist/holmes/mcp/server.js +9 -8
  205. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  206. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  207. package/dist/holmes/mcp/tool-schemas.js +29 -2
  208. package/dist/holmes/project/act-root.d.ts +19 -0
  209. package/dist/holmes/project/act-root.js +100 -0
  210. package/dist/holmes/project/baseline.js +4 -3
  211. package/dist/holmes/project/bounded-group.d.ts +47 -0
  212. package/dist/holmes/project/bounded-group.js +140 -0
  213. package/dist/holmes/project/bounded-io.d.ts +50 -2
  214. package/dist/holmes/project/bounded-io.js +138 -6
  215. package/dist/holmes/project/change-source.js +2 -2
  216. package/dist/holmes/project/instance-id.d.ts +10 -0
  217. package/dist/holmes/project/instance-id.js +233 -0
  218. package/dist/holmes/project/machine-identity.d.ts +25 -0
  219. package/dist/holmes/project/machine-identity.js +133 -0
  220. package/dist/holmes/project/owned-lock.d.ts +84 -0
  221. package/dist/holmes/project/owned-lock.js +263 -0
  222. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  223. package/dist/holmes/project/plain-lock-fs.js +126 -0
  224. package/dist/holmes/project/request-lock.d.ts +85 -0
  225. package/dist/holmes/project/request-lock.js +459 -0
  226. package/dist/holmes/project/root.d.ts +12 -4
  227. package/dist/holmes/project/root.js +26 -7
  228. package/dist/holmes/project/run-records.d.ts +19 -0
  229. package/dist/holmes/project/run-records.js +94 -12
  230. package/dist/holmes/project/screen-text.d.ts +94 -0
  231. package/dist/holmes/project/screen-text.js +763 -0
  232. package/dist/holmes/project/spend-lock.d.ts +82 -0
  233. package/dist/holmes/project/spend-lock.js +413 -0
  234. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  235. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  236. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  237. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  238. package/dist/holmes/review/confidence-calibration.js +1 -1
  239. package/dist/holmes/review/content-verify.js +1 -1
  240. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  241. package/dist/holmes/review/hop-ablation.js +5 -5
  242. package/dist/holmes/review/point-in-time-replay.js +12 -3
  243. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  244. package/dist/holmes/review/rank-diagnosis.js +1 -1
  245. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  246. package/dist/holmes/review/replay-corpus.js +25 -9
  247. package/dist/holmes/review/requirement-triage.js +2 -2
  248. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  249. package/dist/holmes/review/semantic-arm.js +3 -3
  250. package/dist/holmes/review/test-outcomes.js +3 -1
  251. package/dist/holmes/review/test-runner.d.ts +11 -0
  252. package/dist/holmes/review/test-runner.js +31 -10
  253. package/dist/holmes/review/test-selection-breadth.js +2 -2
  254. package/dist/holmes/review/verdicts.d.ts +105 -8
  255. package/dist/holmes/review/verdicts.js +640 -36
  256. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  257. package/dist/holmes/rtm/anchor-census.js +151 -0
  258. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  259. package/dist/holmes/rtm/anchor-ids.js +45 -2
  260. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  261. package/dist/holmes/rtm/comment-ranges.js +104 -0
  262. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  263. package/dist/holmes/rtm/counted-tests.js +63 -0
  264. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  265. package/dist/holmes/rtm/known-defects.js +1 -1
  266. package/dist/holmes/rtm/localize.js +1 -1
  267. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  268. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  269. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  270. package/dist/holmes/rtm/test-scope.js +166 -5
  271. package/dist/holmes/rtm/trace-gaps.js +1 -1
  272. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  273. package/dist/holmes/runtime/dispatch.js +12 -1
  274. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  275. package/dist/holmes/semantic/cloud-usage.js +1 -1
  276. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  277. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  278. package/dist/holmes/spec/approval-blockers.js +1 -1
  279. package/dist/holmes/spec/entity-store.d.ts +6 -1
  280. package/dist/holmes/spec/entity-store.js +16 -2
  281. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  282. package/dist/holmes/spec/entity-transaction.js +87 -170
  283. package/dist/holmes/spec/spec-store.d.ts +12 -6
  284. package/dist/holmes/spec/spec-store.js +4 -2
  285. package/dist/holmes/spec/spec-types.js +1 -1
  286. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  287. package/dist/holmes/spec/succession-guard.js +187 -0
  288. package/dist/holmes/spec/succession.d.ts +70 -0
  289. package/dist/holmes/spec/succession.js +171 -0
  290. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  291. package/docs/install-guide.md +9 -3
  292. package/docs/language-support.md +78 -0
  293. package/package.json +4 -3
  294. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  295. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  296. package/playbooks/publish/PLAYBOOK.md +45 -33
  297. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  298. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -9,6 +9,25 @@ export interface RunRecord {
9
9
  export declare const runsDir: (main: string) => string;
10
10
  /** The main checkout behind `dir`: a linked worktree's `.git` pointer leads to the common git directory's parent. */
11
11
  export declare function mainCheckoutOf(dir: string): string;
12
+ /**
13
+ * The checkout holding `dir` (`top`, the first directory upward with a `.git` entry; `dir` itself when none) and its
14
+ * main checkout. @implements A-SPEC-102.29 — the commondir is read only as a regular file of at most 4 KiB (a FIFO held
15
+ * the read open). @implements A-SPEC-102.30 (item 8) — the `.git` pointer and the commondir are each read on one
16
+ * descriptor, non-blocking and checked by fstat. `strict` (the harness catalog's root): a pointer or a commondir that
17
+ * exists but cannot be read so throws, naming the path. @implements A-SPEC-102.32 — non-strict (the runs' reading) is
18
+ * that of before 102.30, and it is not "not a worktree" in every case: a pointer it cannot open throws (EACCES), a
19
+ * pointer it reads but cannot follow, or a commondir it cannot read (a link), answers the worktree as its own main.
20
+ * Neither reading tells a forged checkout from a real one (the Limits of A-SPEC-102.32 name eight forms).
21
+ * @implements A-SPEC-102.33 — and a pointer `gitdir: <any directory>/.git` with no commondir makes that directory, the
22
+ * one the agent chose, the main checkout: its runs, config and ledgers are read and written (the reading of before
23
+ * 102.30; the fix waits for the owner's decision 1-c).
24
+ */
25
+ export declare function checkoutOf(dir: string, opts?: {
26
+ strict?: boolean;
27
+ }): {
28
+ top: string;
29
+ main: string;
30
+ };
12
31
  export declare const newRunId: (now: Date, rand: () => string) => string;
13
32
  export declare const keyHash: (key: string) => string;
14
33
  export declare function writeRun(main: string, rec: RunRecord): string;
@@ -35,20 +35,43 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.keyHash = exports.newRunId = exports.runsDir = void 0;
37
37
  exports.mainCheckoutOf = mainCheckoutOf;
38
+ exports.checkoutOf = checkoutOf;
38
39
  exports.writeRun = writeRun;
39
40
  exports.listRuns = listRuns;
40
41
  exports.removeRun = removeRun;
41
- // @implements A-SPEC-774.17
42
+ // @implements A-SPEC-774.17, A-SPEC-102.29, A-SPEC-102.30, A-SPEC-102.31, A-SPEC-102.32, A-SPEC-102.33
42
43
  // The run records A-SPEC-774.9's runMode reads: `.ax/state/runs/<run_id>.json` in the main checkout. Written by
43
44
  // `holmes-kit run start`, removed by `run stop` with the stop key — a session inside the run never sees the key.
44
45
  const crypto = __importStar(require("node:crypto"));
45
46
  const fs = __importStar(require("node:fs"));
46
47
  const path = __importStar(require("node:path"));
48
+ const bounded_io_1 = require("./bounded-io");
47
49
  const RUN_ID_RE = /^run-\d{14}-[0-9a-f]{8}$/;
48
50
  const runsDir = (main) => path.join(main, '.ax', 'state', 'runs');
49
51
  exports.runsDir = runsDir;
50
52
  /** The main checkout behind `dir`: a linked worktree's `.git` pointer leads to the common git directory's parent. */
51
53
  function mainCheckoutOf(dir) {
54
+ return checkoutOf(dir).main;
55
+ }
56
+ /**
57
+ * The checkout holding `dir` (`top`, the first directory upward with a `.git` entry; `dir` itself when none) and its
58
+ * main checkout. @implements A-SPEC-102.29 — the commondir is read only as a regular file of at most 4 KiB (a FIFO held
59
+ * the read open). @implements A-SPEC-102.30 (item 8) — the `.git` pointer and the commondir are each read on one
60
+ * descriptor, non-blocking and checked by fstat. `strict` (the harness catalog's root): a pointer or a commondir that
61
+ * exists but cannot be read so throws, naming the path. @implements A-SPEC-102.32 — non-strict (the runs' reading) is
62
+ * that of before 102.30, and it is not "not a worktree" in every case: a pointer it cannot open throws (EACCES), a
63
+ * pointer it reads but cannot follow, or a commondir it cannot read (a link), answers the worktree as its own main.
64
+ * Neither reading tells a forged checkout from a real one (the Limits of A-SPEC-102.32 name eight forms).
65
+ * @implements A-SPEC-102.33 — and a pointer `gitdir: <any directory>/.git` with no commondir makes that directory, the
66
+ * one the agent chose, the main checkout: its runs, config and ledgers are read and written (the reading of before
67
+ * 102.30; the fix waits for the owner's decision 1-c).
68
+ */
69
+ function checkoutOf(dir, opts = {}) {
70
+ const strict = opts.strict === true;
71
+ // @implements A-SPEC-102.31 — strict: what cannot be a checkout's .git throws, naming the path; non-strict (the runs'
72
+ // callers: run-exec, run, run-stages, run-refusals, run-plan-scope, stop, verdicts, push-gate-runner; each says what a
73
+ // forged or unreadable pointer does there, A-SPEC-102.32) keeps its reading of before 102.30
74
+ const refuse = (where, why) => { throw new Error(`${where}: ${why}`); };
52
75
  let cur = path.resolve(dir);
53
76
  for (;;) {
54
77
  const dotGit = path.join(cur, '.git');
@@ -59,26 +82,85 @@ function mainCheckoutOf(dir) {
59
82
  catch {
60
83
  st = null;
61
84
  }
62
- if (st?.isDirectory())
63
- return cur;
64
- if (st?.isFile()) {
65
- const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotGit, 'utf8'));
66
- if (!m)
67
- return cur;
85
+ if (st?.isDirectory()) {
86
+ // an empty directory in place of a worktree pointer read as a main checkout (A, B)
87
+ if (strict && !fs.existsSync(path.join(dotGit, 'HEAD')))
88
+ refuse(dotGit, 'a .git directory with no HEAD');
89
+ return { top: cur, main: cur };
90
+ }
91
+ if (st !== null && !st.isFile()) {
92
+ if (strict)
93
+ refuse(dotGit, 'neither a directory nor a regular file'); // a FIFO, a socket, a device
94
+ }
95
+ else if (st?.isFile()) {
96
+ // non-strict reads the pointer as before 102.30 (a link followed, no bound): its callers took no throw from it
97
+ const text = strict ? (0, bounded_io_1.readSmallRegularTextSync)(dotGit, 4096) : fs.readFileSync(dotGit, 'utf8');
98
+ const m = /^gitdir:\s*(.+)$/m.exec(text);
99
+ if (!m) {
100
+ if (strict)
101
+ refuse(dotGit, 'no gitdir line');
102
+ return { top: cur, main: cur };
103
+ }
68
104
  const gitdir = path.resolve(cur, m[1].trim());
69
- let common = gitdir;
105
+ if (strict) {
106
+ let ok = false;
107
+ try {
108
+ ok = fs.statSync(gitdir).isDirectory();
109
+ }
110
+ catch {
111
+ ok = false;
112
+ }
113
+ if (!ok)
114
+ refuse(dotGit, `its gitdir ${gitdir} is not a directory`);
115
+ }
116
+ let common = null;
117
+ const cd = path.join(gitdir, 'commondir');
70
118
  try {
71
- common = path.resolve(gitdir, fs.readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim());
119
+ common = path.resolve(gitdir, (0, bounded_io_1.readSmallRegularTextSync)(cd, 4096).trim());
120
+ }
121
+ catch (e) {
122
+ // no commondir: a submodule's gitdir, not a worktree; anything else is a commondir that cannot be trusted
123
+ if (strict && e.code !== 'ENOENT')
124
+ refuse(cd, e.message);
72
125
  }
73
- catch { /* not a worktree gitdir */ }
74
- return path.basename(common) === '.git' ? path.dirname(common) : cur;
126
+ // @implements A-SPEC-102.32 — no commondir: the gitdir is its own common, as before 102.31, so a pointer naming the
127
+ // main checkout's `.git` reads that checkout (102.31 read the worktree as its own main: B, a regression). The back
128
+ // reference is an entry's, so only a commondir asks for it
129
+ if (common !== null && strict)
130
+ backReference(dotGit, gitdir, common);
131
+ const own = common ?? gitdir;
132
+ return { top: cur, main: path.basename(own) === '.git' ? path.dirname(own) : cur };
75
133
  }
76
134
  const up = path.dirname(cur);
77
135
  if (up === cur)
78
- return path.resolve(dir);
136
+ return { top: path.resolve(dir), main: path.resolve(dir) };
79
137
  cur = up;
80
138
  }
81
139
  }
140
+ /**
141
+ * @implements A-SPEC-102.31 — a worktree's entry points back at it: the gitdir is `<common>/worktrees/<id>` and its
142
+ * `gitdir` file names this `.git`. A redirect to a fake gitdir passed as "not a worktree" (A, B). A whole repository
143
+ * forged with a matching entry still passes: named in the Limits.
144
+ */
145
+ function backReference(dotGit, gitdir, common) {
146
+ const same = (a, b) => { try {
147
+ return fs.realpathSync(a) === fs.realpathSync(b);
148
+ }
149
+ catch {
150
+ return false;
151
+ } };
152
+ if (!same(path.dirname(gitdir), path.join(common, 'worktrees')))
153
+ throw new Error(`${dotGit}: its gitdir ${gitdir} is not an entry of ${path.join(common, 'worktrees')}`);
154
+ let named;
155
+ try {
156
+ named = (0, bounded_io_1.readSmallRegularTextSync)(path.join(gitdir, 'gitdir'), 4096).trim();
157
+ }
158
+ catch (e) {
159
+ throw new Error(`${path.join(gitdir, 'gitdir')}: ${e.message}`);
160
+ }
161
+ if (!same(path.resolve(gitdir, named), dotGit))
162
+ throw new Error(`${dotGit}: its worktree entry points at ${named}`);
163
+ }
82
164
  const newRunId = (now, rand) => `run-${now.toISOString().replace(/[-:T]/g, '').slice(0, 14)}-${rand().slice(0, 8)}`;
83
165
  exports.newRunId = newRunId;
84
166
  const keyHash = (key) => crypto.createHash('sha256').update(key).digest('hex');
@@ -0,0 +1,94 @@
1
+ /**
2
+ * One terminal row's worth of SUBJECT, with the template's own cells already subtracted: an 80
3
+ * column row, minus the widest template prefix on this screen (`\u2713 \uc2b9\uc778 \u2014 `, nine columns)
4
+ * and the kind cell (16) and its space, leaves 52. Every line the decision surface prints is bounded by it, so a queue of any size stays a
5
+ * screen the operator can read top to bottom — the property the batch confirmation depends on
6
+ * (round-5: the field was bounded and the LINE was not, so a bounded field still wrapped).
7
+ */
8
+ /** The terminal this screen promises to fit. The floor no terminal goes below. */
9
+ export declare const ROW_MAX = 80;
10
+ export declare const ROW_COLS = 50;
11
+ /**
12
+ * The `kind` cell. Round-7: at 16 the truncation NOTICE (`… (200자 잘림)`, fifteen columns) consumed
13
+ * the entire budget, so a non-ASCII kind rendered ZERO columns of the operator's text — the category
14
+ * of authority being granted, unreadable, in the list AND the item header AND the confirmation AND
15
+ * every decision echo. That is the round-5 lesson ("a bound met by showing nothing is the
16
+ * concealment this module exists to prevent") reached through a budget nobody re-checked. Twenty
17
+ * columns plus the short notice form below leaves real text on the line.
18
+ */
19
+ export declare const KIND_COLS = 20;
20
+ /**
21
+ * Did rendering this value into `max` columns hide any of it?
22
+ *
23
+ * Round-8: this used to be a REGEX OVER THE RENDERED TEXT, and the data can end with any string it
24
+ * likes — a target ending `… (5자 잘림)` was reported as clipped when nothing had been clipped, so
25
+ * `[A]` refused to batch it and told the operator, falsely, that it did not fit on a row. An agent
26
+ * could disable batch approval for a whole session by choosing its own suffix. The renderer knows
27
+ * the answer; nobody should have to parse it back out of the output.
28
+ */
29
+ export declare function isClipped(value: string, max?: number): boolean;
30
+ /**
31
+ * How many terminal COLUMNS a string occupies. Round-5 measured why a code-point budget is not a
32
+ * screen budget: a 200-code-point line of markers rendered 302 columns — four wrapped rows at 80 —
33
+ * because `⟪`, `⟫` and every Hangul character in `자 제거` are East Asian WIDE (two columns each).
34
+ * The budget exists to bound SCREEN SPACE, so it must be counted in the unit the screen uses.
35
+ */
36
+ export declare function displayWidth(s: string): number;
37
+ /**
38
+ * One line, no control bytes, bounded in terminal COLUMNS — for a field the template puts on a line
39
+ * of its own. `max` is a column budget, not a character count (round-5): the caller is buying screen
40
+ * space, and on this screen a character can cost one column or two.
41
+ *
42
+ * The budget is spent on the OPERATOR'S text: the source is clipped first so escape spam cannot
43
+ * evict the real command (round-3), and the sanitised result is clipped again so markers cannot
44
+ * inflate the output (round-4). The truncation notice is appended AFTER sanitising, so no sequence
45
+ * sitting at the clip boundary can swallow it (round-4).
46
+ */
47
+ export declare function flattenField(s: string, max?: number): string;
48
+ /**
49
+ * A-SPEC-262.1 §13 —
50
+ * The form agent-controlled text takes on a DECISION ROW: only characters whose width is fixed by
51
+ * the standard, everything else as an ASCII escape.
52
+ *
53
+ * Eight adversarial rounds found the same shape of defect eight times — a character whose width the
54
+ * code guessed (Ambiguous, combining, zero-width), or whose cursor effect it did not model (TAB,
55
+ * ESC), or whose position let the data choose a line boundary (alignment, folding). None of them can
56
+ * occur here, because none of those characters survive to the row: a control byte is not stripped
57
+ * and counted, it is SHOWN as `\u001b`. Nothing is removed, so nothing is hidden — which also
58
+ * retires the removal marker, its forgery guard and its size accounting from this path entirely.
59
+ *
60
+ * What passes through: printable ASCII (one column each) and East_Asian_Width W or F (two columns
61
+ * each, fixed by the standard). Korean and CJK commands therefore stay readable on the screen the
62
+ * operator decides from — the requirement that made this a hybrid rather than a full escaping.
63
+ * A backslash is doubled first, so data can never spell an escape the renderer did not write.
64
+ */
65
+ export declare function rowLiteral(s: string): string;
66
+ /**
67
+ * A-SPEC-262.1 §13 —
68
+ * A decision row's field: the row literal, cut to `max` columns, with what it could not show stated.
69
+ */
70
+ export declare function rowField(value: string, max?: number): string;
71
+ export declare function wrapColumns(s: string, cols?: number, indent?: string): string;
72
+ export declare function stripControl(s: string): string;
73
+ /**
74
+ * Clip on a CODE POINT boundary. Round-1: slicing UTF-16 units cut a surrogate pair in half and the
75
+ * last visible character of a clipped command rendered as a replacement glyph — on a screen whose
76
+ * whole job is showing the subject verbatim.
77
+ */
78
+ export declare function clipCodePoints(s: string, max: number): string;
79
+ /**
80
+ * Quote a value that is about to appear inside a COPY-PASTEABLE command line.
81
+ *
82
+ * Round-2: the non-TTY hint (A-SPEC-260) fills the real queue id into three `holmes-kit approve …`
83
+ * lines whose whole purpose is being pasted into a shell — and the id is agent-controlled. Flattening
84
+ * stops it forging lines, but a flattened `… | sh` still PIPES when pasted. POSIX single quotes make
85
+ * any byte inert; a literal quote is closed, escaped and reopened.
86
+ */
87
+ export declare function shellQuote(s: string): string;
88
+ /**
89
+ * A reference for a pasteable command line: left ALONE when it is already inert (the shape a real
90
+ * queue id has), quoted only when it is not. Round-2 wanted every pasted byte harmless; quoting
91
+ * unconditionally would also have rewritten the A-SPEC-260 hint that ships today, so the blast
92
+ * radius is kept to the case that needs it — a normal session's screen is byte-for-byte unchanged.
93
+ */
94
+ export declare function safeRef(s: string): string;