@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
@@ -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;
@@ -0,0 +1,233 @@
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.INSTANCE_ID_RELPATH = void 0;
37
+ exports.readInstanceId = readInstanceId;
38
+ exports.ensureInstanceId = ensureInstanceId;
39
+ // @implements A-SPEC-794.2, A-SPEC-794.6
40
+ /**
41
+ * This clone's instance id (design draft 4 §1.1): what "issued by this replica" means for approval cycles. The S1
42
+ * cycles that read it were reverted for 0.40.0 (A-SPEC-794.30); the id stays, as the S2 skeleton made it. It is a local fact in `.ax/state/instance-id.json`, never the HOLMES_REPLICA_ID environment
43
+ * value, which a process can set.
44
+ *
45
+ * - The file is `{ v: 1, id, realpath, dev, ino }`, the last three being those of `.ax/state`. A file whose dev and
46
+ * ino do not match was copied or moved with its directory and names another instance: it reads as none. realpath is
47
+ * kept for a reader and not compared, so letter case or a mount path does not change the id (A-SPEC-794.6).
48
+ * - A read never creates it. A missing file is published by a no-clobber link, so two creators agree on one id.
49
+ * - A mismatched file is repaired only under the repair lock `instance-id.lock` (exclusive create; one older than 30 s
50
+ * is taken over by inode). Under the lock the file is judged again through one fd (bytes and fstat), moved aside
51
+ * only while that inode is still at the path, and a moved file that is not the judged one is linked back.
52
+ * - Nothing is created without an existing `.ax`.
53
+ *
54
+ * Limits: a repairer paused past the 30 s takeover can race a new one; the inode checks keep a just-published file,
55
+ * but two ids can then be returned. A file system whose device number changes across mounts renews the id.
56
+ */
57
+ const fs = __importStar(require("node:fs"));
58
+ const path = __importStar(require("node:path"));
59
+ const node_crypto_1 = require("node:crypto");
60
+ exports.INSTANCE_ID_RELPATH = '.ax/state/instance-id.json';
61
+ const LOCK_RELPATH = '.ax/state/instance-id.lock';
62
+ const LOCK_STALE_MS = 30_000;
63
+ const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
64
+ const lstat = (p) => { try {
65
+ return fs.lstatSync(p);
66
+ }
67
+ catch {
68
+ return undefined;
69
+ } };
70
+ function stateFingerprint(root) {
71
+ const state = path.join(root, '.ax', 'state');
72
+ const s = lstat(state);
73
+ if (!s?.isDirectory())
74
+ return null;
75
+ try {
76
+ return { realpath: fs.realpathSync(state), dev: s.dev, ino: s.ino };
77
+ }
78
+ catch {
79
+ return null;
80
+ }
81
+ }
82
+ /** The file as one fd sees it: its id when it matches (or null), and the inode that was judged. Absent: undefined. */
83
+ function judge(root) {
84
+ const fp = stateFingerprint(root);
85
+ let fd;
86
+ try {
87
+ fd = fs.openSync(path.join(root, exports.INSTANCE_ID_RELPATH), fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
88
+ }
89
+ catch {
90
+ return undefined;
91
+ }
92
+ try {
93
+ const st = fs.fstatSync(fd);
94
+ let r = null;
95
+ try {
96
+ r = JSON.parse(fs.readFileSync(fd, 'utf8'));
97
+ }
98
+ catch {
99
+ r = null;
100
+ }
101
+ const o = (typeof r === 'object' && r !== null ? r : {});
102
+ const ok = fp !== null && o.v === 1 && typeof o.id === 'string' && UUID_V4.test(o.id) && o.dev === fp.dev && o.ino === fp.ino;
103
+ return { id: ok ? o.id : null, ino: st.ino, dev: st.dev };
104
+ }
105
+ finally {
106
+ fs.closeSync(fd);
107
+ }
108
+ }
109
+ /** The instance id, or null when it is absent, malformed or another directory's. Never writes. */
110
+ function readInstanceId(root) {
111
+ return judge(root)?.id ?? null;
112
+ }
113
+ /** Publish a new id by link; true when it is in place, false when another file took the name first. */
114
+ function publish(root, hooks) {
115
+ const fp = stateFingerprint(root);
116
+ if (!fp)
117
+ throw new Error('.ax/state is not a directory; no instance id is created.');
118
+ const temp = path.join(root, '.ax', 'state', `.instance-id.${(0, node_crypto_1.randomUUID)()}.tmp`);
119
+ fs.writeFileSync(temp, JSON.stringify({ v: 1, id: (0, node_crypto_1.randomUUID)(), ...fp }), { flag: 'wx', mode: 0o600 });
120
+ try {
121
+ hooks.beforePublish?.();
122
+ fs.linkSync(temp, path.join(root, exports.INSTANCE_ID_RELPATH));
123
+ return true;
124
+ }
125
+ catch (e) {
126
+ if (e.code === 'EEXIST')
127
+ return false;
128
+ throw e;
129
+ }
130
+ finally {
131
+ try {
132
+ fs.unlinkSync(temp);
133
+ }
134
+ catch { /* removed already */ }
135
+ }
136
+ }
137
+ /** Run `fn` under the repair lock, or answer null when another repairer holds it. */
138
+ function underRepairLock(root, fn) {
139
+ const lock = path.join(root, LOCK_RELPATH);
140
+ let fd;
141
+ try {
142
+ fd = fs.openSync(lock, 'wx', 0o600);
143
+ }
144
+ catch (e) {
145
+ if (e.code !== 'EEXIST')
146
+ throw e;
147
+ const s = lstat(lock);
148
+ if (s && Date.now() - s.mtimeMs > LOCK_STALE_MS) {
149
+ // take over an abandoned lock: only the inode judged stale is removed
150
+ const again = lstat(lock);
151
+ if (again && again.ino === s.ino && again.dev === s.dev) {
152
+ try {
153
+ fs.unlinkSync(lock);
154
+ }
155
+ catch { /* raced */ }
156
+ }
157
+ }
158
+ return null;
159
+ }
160
+ fs.closeSync(fd);
161
+ const mine = lstat(lock);
162
+ try {
163
+ return fn();
164
+ }
165
+ finally {
166
+ const now = lstat(lock);
167
+ if (now && mine && now.ino === mine.ino && now.dev === mine.dev) {
168
+ try {
169
+ fs.unlinkSync(lock);
170
+ }
171
+ catch { /* gone */ }
172
+ }
173
+ }
174
+ }
175
+ /** Move the judged inode aside; a file that is not the judged one is linked back. */
176
+ function setAside(root, judged) {
177
+ const file = path.join(root, exports.INSTANCE_ID_RELPATH);
178
+ const aside = `${file}.stale-${(0, node_crypto_1.randomUUID)()}`;
179
+ try {
180
+ fs.renameSync(file, aside);
181
+ }
182
+ catch {
183
+ return;
184
+ }
185
+ const moved = lstat(aside);
186
+ if (moved && (moved.dev !== judged.dev || moved.ino !== judged.ino)) {
187
+ try {
188
+ fs.linkSync(aside, file);
189
+ fs.unlinkSync(aside);
190
+ }
191
+ catch { /* a newer file is in place; this one stays aside */ }
192
+ }
193
+ }
194
+ /** This clone's instance id, created when absent or mismatched. Refuses without an existing `.ax`. */
195
+ function ensureInstanceId(root, hooks = {}) {
196
+ if (!lstat(path.join(root, '.ax'))?.isDirectory())
197
+ throw new Error('An instance id is created only inside an existing .ax directory.');
198
+ const state = path.join(root, '.ax', 'state');
199
+ if (!lstat(state)) {
200
+ try {
201
+ fs.mkdirSync(state);
202
+ }
203
+ catch (e) {
204
+ if (e.code !== 'EEXIST')
205
+ throw e;
206
+ }
207
+ }
208
+ for (let attempt = 0; attempt < 200; attempt++) {
209
+ const seen = judge(root);
210
+ if (seen?.id)
211
+ return seen.id;
212
+ if (seen === undefined) {
213
+ publish(root, hooks);
214
+ continue;
215
+ }
216
+ underRepairLock(root, () => {
217
+ const now = judge(root);
218
+ if (now === undefined || now.id !== null)
219
+ return;
220
+ hooks.beforeAside?.();
221
+ setAside(root, now);
222
+ if (judge(root) === undefined)
223
+ publish(root, hooks);
224
+ });
225
+ if (attempt > 0) {
226
+ try {
227
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
228
+ }
229
+ catch { /* retry */ }
230
+ }
231
+ }
232
+ throw new Error('The instance id kept changing under this process; no id is returned.');
233
+ }
@@ -0,0 +1,25 @@
1
+ export declare const IDENTITY_TIMEOUT_MS = 1000;
2
+ export interface IdentityDeps {
3
+ platform: NodeJS.Platform;
4
+ exec: (file: string, args: string[], opts: {
5
+ timeout: number;
6
+ env: Record<string, string>;
7
+ encoding: 'utf8';
8
+ stdio: ['ignore', 'pipe', 'ignore'];
9
+ }) => string;
10
+ readFile: (p: string) => string;
11
+ statIno: (p: string) => number;
12
+ /** Windows only: where reg.exe lives. */
13
+ systemRoot?: string;
14
+ /** The clock a null value's retry is timed on. */
15
+ now?: () => number;
16
+ }
17
+ /** A-SPEC-245.10 (low): a null is kept this long, not for the process's life — a read that timed out under load retries. */
18
+ export declare const IDENTITY_NULL_RETRY_MS = 60000;
19
+ export interface IdentityReader {
20
+ bootId(): string | null;
21
+ hostId(): string | null;
22
+ }
23
+ export declare function createIdentityReader(deps: IdentityDeps): IdentityReader;
24
+ export declare function bootId(): string | null;
25
+ export declare function hostId(): string | null;