@holmes-lab/holmes-kit 0.38.0 → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (308) hide show
  1. package/CHANGELOG.md +370 -6
  2. package/README.md +58 -40
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/admission/core/admission-policy.d.ts +37 -0
  5. package/dist/holmes/admission/core/admission-policy.js +147 -0
  6. package/dist/holmes/admission/core/bounded-reader.d.ts +56 -0
  7. package/dist/holmes/admission/core/bounded-reader.js +135 -0
  8. package/dist/holmes/admission/core/change-classifier.d.ts +34 -0
  9. package/dist/holmes/admission/core/change-classifier.js +278 -0
  10. package/dist/holmes/admission/core/config-loader.d.ts +30 -0
  11. package/dist/holmes/admission/core/config-loader.js +145 -0
  12. package/dist/holmes/admission/core/event-judgement.d.ts +37 -0
  13. package/dist/holmes/admission/core/event-judgement.js +251 -0
  14. package/dist/holmes/admission/core/path-rules.d.ts +35 -0
  15. package/dist/holmes/admission/core/path-rules.js +88 -0
  16. package/dist/holmes/admission/core/pin.d.ts +7 -0
  17. package/dist/holmes/admission/core/pin.js +29 -0
  18. package/dist/holmes/admission/core/ports.d.ts +48 -0
  19. package/dist/holmes/admission/core/ports.js +11 -0
  20. package/dist/holmes/admission/core/range-resolver.d.ts +32 -0
  21. package/dist/holmes/admission/core/range-resolver.js +51 -0
  22. package/dist/holmes/admission/core/self-containment.d.ts +1 -0
  23. package/dist/holmes/admission/core/self-containment.js +125 -0
  24. package/dist/holmes/admission/core/signature-source.d.ts +9 -0
  25. package/dist/holmes/admission/core/signature-source.js +4 -0
  26. package/dist/holmes/admission/core/transition-planner.d.ts +15 -0
  27. package/dist/holmes/admission/core/transition-planner.js +14 -0
  28. package/dist/holmes/admission/core/verdict.d.ts +38 -0
  29. package/dist/holmes/admission/core/verdict.js +17 -0
  30. package/dist/holmes/admission/core/wiring.d.ts +44 -0
  31. package/dist/holmes/admission/core/wiring.js +618 -0
  32. package/dist/holmes/admission/forge/git-object-port.d.ts +4 -0
  33. package/dist/holmes/admission/forge/git-object-port.js +132 -0
  34. package/dist/holmes/assoc/assoc-arm.d.ts +1 -1
  35. package/dist/holmes/assoc/assoc-arm.js +1 -1
  36. package/dist/holmes/cli/agents.d.ts +8 -0
  37. package/dist/holmes/cli/agents.js +9 -5
  38. package/dist/holmes/cli/approve-cli.d.ts +2 -0
  39. package/dist/holmes/cli/approve-cli.js +392 -0
  40. package/dist/holmes/cli/approve-ref.d.ts +13 -7
  41. package/dist/holmes/cli/approve-ref.js +30 -10
  42. package/dist/holmes/cli/approve-status.d.ts +26 -2
  43. package/dist/holmes/cli/approve-status.js +98 -18
  44. package/dist/holmes/cli/approve-watch.d.ts +5 -0
  45. package/dist/holmes/cli/approve-watch.js +10 -5
  46. package/dist/holmes/cli/approve.d.ts +50 -13
  47. package/dist/holmes/cli/approve.js +260 -67
  48. package/dist/holmes/cli/attest.js +2 -1
  49. package/dist/holmes/cli/autonomy.d.ts +4 -1
  50. package/dist/holmes/cli/autonomy.js +17 -10
  51. package/dist/holmes/cli/codex-oracle.d.ts +11 -0
  52. package/dist/holmes/cli/codex-oracle.js +5 -1
  53. package/dist/holmes/cli/codex-toml.d.ts +10 -0
  54. package/dist/holmes/cli/codex-toml.js +36 -2
  55. package/dist/holmes/cli/doctor-boundary.d.ts +76 -0
  56. package/dist/holmes/cli/doctor-boundary.js +308 -0
  57. package/dist/holmes/cli/doctor-locks.d.ts +15 -0
  58. package/dist/holmes/cli/doctor-locks.js +119 -0
  59. package/dist/holmes/cli/doctor.d.ts +2 -0
  60. package/dist/holmes/cli/doctor.js +45 -5
  61. package/dist/holmes/cli/flags.d.ts +23 -0
  62. package/dist/holmes/cli/flags.js +89 -0
  63. package/dist/holmes/cli/index.d.ts +5 -1
  64. package/dist/holmes/cli/index.js +206 -424
  65. package/dist/holmes/cli/init.js +33 -0
  66. package/dist/holmes/cli/lock-recover.d.ts +5 -0
  67. package/dist/holmes/cli/lock-recover.js +126 -0
  68. package/dist/holmes/cli/mcp-processes.d.ts +32 -0
  69. package/dist/holmes/cli/mcp-processes.js +132 -0
  70. package/dist/holmes/cli/release-docs.js +1 -1
  71. package/dist/holmes/cli/run-exec.d.ts +141 -0
  72. package/dist/holmes/cli/run-exec.js +1435 -0
  73. package/dist/holmes/cli/run-provision.d.ts +8 -0
  74. package/dist/holmes/cli/run-provision.js +325 -0
  75. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  76. package/dist/holmes/cli/run-wiring.js +270 -0
  77. package/dist/holmes/cli/run.d.ts +26 -0
  78. package/dist/holmes/cli/run.js +364 -83
  79. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  80. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  81. package/dist/holmes/cli/screen-safe.js +18 -756
  82. package/dist/holmes/config/config.d.ts +2 -0
  83. package/dist/holmes/config/config.js +5 -2
  84. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  85. package/dist/holmes/cpg/import-resolver.js +1 -1
  86. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  87. package/dist/holmes/governance/approval-decisions.js +29 -0
  88. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  89. package/dist/holmes/governance/approval-grants.js +612 -33
  90. package/dist/holmes/governance/approval-queue.d.ts +31 -0
  91. package/dist/holmes/governance/approval-queue.js +122 -11
  92. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  93. package/dist/holmes/governance/approval-spend.js +191 -0
  94. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  95. package/dist/holmes/governance/autonomous-shell.js +332 -0
  96. package/dist/holmes/governance/autonomy.d.ts +5 -0
  97. package/dist/holmes/governance/autonomy.js +16 -11
  98. package/dist/holmes/governance/constitution.d.ts +5 -0
  99. package/dist/holmes/governance/constitution.js +32 -12
  100. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  101. package/dist/holmes/governance/full-autonomy.js +103 -7
  102. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  103. package/dist/holmes/governance/harness-catalog.js +348 -0
  104. package/dist/holmes/governance/human-channel.d.ts +38 -0
  105. package/dist/holmes/governance/human-channel.js +49 -0
  106. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  107. package/dist/holmes/governance/install-manifest.js +160 -0
  108. package/dist/holmes/governance/ledger-rechain.js +2 -0
  109. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  110. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  111. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  112. package/dist/holmes/governance/ledger-store.js +186 -8
  113. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  114. package/dist/holmes/governance/provenance-chain.js +19 -4
  115. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  116. package/dist/holmes/governance/provenance-ledger.js +53 -18
  117. package/dist/holmes/governance/push-gate-runner.js +11 -7
  118. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  119. package/dist/holmes/governance/recorded-pairs.js +522 -0
  120. package/dist/holmes/governance/replica-id.d.ts +1 -1
  121. package/dist/holmes/governance/replica-id.js +1 -1
  122. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  123. package/dist/holmes/governance/spec-seam.js +587 -0
  124. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  125. package/dist/holmes/governance/spend-kinds.js +18 -0
  126. package/dist/holmes/governance/tool-actions.js +2 -0
  127. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  128. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  129. package/dist/holmes/guardrail/impact-gate.d.ts +1 -0
  130. package/dist/holmes/guardrail/impact-gate.js +1 -1
  131. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  132. package/dist/holmes/guardrail/line-continuation.js +39 -0
  133. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  134. package/dist/holmes/guardrail/operator-person.js +57 -11
  135. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  136. package/dist/holmes/guardrail/refusal-codes.js +70 -10
  137. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  138. package/dist/holmes/guardrail/risk-classifier.js +245 -15
  139. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  140. package/dist/holmes/guardrail/risk-gate.js +7 -34
  141. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  142. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  143. package/dist/holmes/guardrail/run-refusals.d.ts +6 -1
  144. package/dist/holmes/guardrail/run-refusals.js +36 -14
  145. package/dist/holmes/guardrail/run-stages.d.ts +10 -0
  146. package/dist/holmes/guardrail/run-stages.js +46 -6
  147. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  148. package/dist/holmes/guardrail/shell-words.js +24 -3
  149. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  150. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  151. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  152. package/dist/holmes/guardrail/write-target.js +26 -5
  153. package/dist/holmes/hooks/pre-tool-use.d.ts +105 -1
  154. package/dist/holmes/hooks/pre-tool-use.js +1167 -168
  155. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  156. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  157. package/dist/holmes/hooks/session-start.d.ts +5 -0
  158. package/dist/holmes/hooks/session-start.js +29 -1
  159. package/dist/holmes/hooks/stop.d.ts +23 -0
  160. package/dist/holmes/hooks/stop.js +88 -33
  161. package/dist/holmes/mcp/approval-adapters.js +3 -1
  162. package/dist/holmes/mcp/approval-commit.js +3 -2
  163. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  164. package/dist/holmes/mcp/approval-policy.js +3 -1
  165. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  166. package/dist/holmes/mcp/handlers/approval-ask.d.ts +14 -0
  167. package/dist/holmes/mcp/handlers/approval-ask.js +31 -6
  168. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  169. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  170. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  171. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  172. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  173. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  174. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  175. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  176. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  177. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  178. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  179. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  180. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  181. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  182. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  183. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  184. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  185. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  186. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  187. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  188. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  189. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  190. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  191. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  192. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  193. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  194. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  195. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  196. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  197. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  198. package/dist/holmes/mcp/handlers/test-execution.d.ts +1 -1
  199. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +5 -0
  200. package/dist/holmes/mcp/handlers/workspace-preflight.js +10 -2
  201. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  202. package/dist/holmes/mcp/handlers.d.ts +99 -79
  203. package/dist/holmes/mcp/handlers.js +93 -25
  204. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  205. package/dist/holmes/mcp/harness-attestation.js +325 -53
  206. package/dist/holmes/mcp/maintenance-analyze.d.ts +1 -1
  207. package/dist/holmes/mcp/maintenance-analyze.js +9 -9
  208. package/dist/holmes/mcp/maintenance-evidence.js +31 -2
  209. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  210. package/dist/holmes/mcp/server-staleness.d.ts +43 -0
  211. package/dist/holmes/mcp/server-staleness.js +158 -0
  212. package/dist/holmes/mcp/server.js +34 -9
  213. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  214. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  215. package/dist/holmes/mcp/tool-schemas.js +42 -2
  216. package/dist/holmes/project/act-root.d.ts +19 -0
  217. package/dist/holmes/project/act-root.js +100 -0
  218. package/dist/holmes/project/baseline.js +4 -3
  219. package/dist/holmes/project/bounded-group.d.ts +47 -0
  220. package/dist/holmes/project/bounded-group.js +140 -0
  221. package/dist/holmes/project/bounded-io.d.ts +50 -2
  222. package/dist/holmes/project/bounded-io.js +138 -6
  223. package/dist/holmes/project/change-source.js +2 -2
  224. package/dist/holmes/project/instance-id.d.ts +10 -0
  225. package/dist/holmes/project/instance-id.js +233 -0
  226. package/dist/holmes/project/machine-identity.d.ts +25 -0
  227. package/dist/holmes/project/machine-identity.js +133 -0
  228. package/dist/holmes/project/owned-lock.d.ts +84 -0
  229. package/dist/holmes/project/owned-lock.js +263 -0
  230. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  231. package/dist/holmes/project/plain-lock-fs.js +126 -0
  232. package/dist/holmes/project/request-lock.d.ts +85 -0
  233. package/dist/holmes/project/request-lock.js +459 -0
  234. package/dist/holmes/project/root.d.ts +12 -4
  235. package/dist/holmes/project/root.js +26 -7
  236. package/dist/holmes/project/run-records.d.ts +19 -0
  237. package/dist/holmes/project/run-records.js +94 -12
  238. package/dist/holmes/project/screen-text.d.ts +94 -0
  239. package/dist/holmes/project/screen-text.js +763 -0
  240. package/dist/holmes/project/spend-lock.d.ts +82 -0
  241. package/dist/holmes/project/spend-lock.js +413 -0
  242. package/dist/holmes/project/workspace-preflight.d.ts +5 -0
  243. package/dist/holmes/project/workspace-preflight.js +24 -1
  244. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  245. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  246. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  247. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  248. package/dist/holmes/review/confidence-calibration.js +1 -1
  249. package/dist/holmes/review/content-verify.js +1 -1
  250. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  251. package/dist/holmes/review/hop-ablation.js +5 -5
  252. package/dist/holmes/review/point-in-time-replay.js +12 -3
  253. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  254. package/dist/holmes/review/rank-diagnosis.js +1 -1
  255. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  256. package/dist/holmes/review/replay-corpus.js +25 -9
  257. package/dist/holmes/review/requirement-triage.js +2 -2
  258. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  259. package/dist/holmes/review/semantic-arm.js +3 -3
  260. package/dist/holmes/review/test-outcomes.js +3 -1
  261. package/dist/holmes/review/test-runner.d.ts +11 -0
  262. package/dist/holmes/review/test-runner.js +31 -10
  263. package/dist/holmes/review/test-selection-breadth.js +2 -2
  264. package/dist/holmes/review/verdicts.d.ts +109 -7
  265. package/dist/holmes/review/verdicts.js +653 -34
  266. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  267. package/dist/holmes/rtm/anchor-census.js +151 -0
  268. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  269. package/dist/holmes/rtm/anchor-ids.js +45 -2
  270. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  271. package/dist/holmes/rtm/comment-ranges.js +104 -0
  272. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  273. package/dist/holmes/rtm/counted-tests.js +63 -0
  274. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  275. package/dist/holmes/rtm/known-defects.js +1 -1
  276. package/dist/holmes/rtm/localize.js +1 -1
  277. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  278. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  279. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  280. package/dist/holmes/rtm/test-scope.js +166 -5
  281. package/dist/holmes/rtm/trace-gaps.js +1 -1
  282. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  283. package/dist/holmes/runtime/dispatch.js +12 -1
  284. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  285. package/dist/holmes/semantic/cloud-usage.js +1 -1
  286. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  287. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  288. package/dist/holmes/spec/approval-blockers.js +1 -1
  289. package/dist/holmes/spec/entity-store.d.ts +6 -1
  290. package/dist/holmes/spec/entity-store.js +16 -2
  291. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  292. package/dist/holmes/spec/entity-transaction.js +87 -170
  293. package/dist/holmes/spec/spec-store.d.ts +12 -6
  294. package/dist/holmes/spec/spec-store.js +4 -2
  295. package/dist/holmes/spec/spec-types.js +1 -1
  296. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  297. package/dist/holmes/spec/succession-guard.js +187 -0
  298. package/dist/holmes/spec/succession.d.ts +70 -0
  299. package/dist/holmes/spec/succession.js +171 -0
  300. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  301. package/docs/install-guide.md +9 -3
  302. package/docs/language-support.md +78 -0
  303. package/package.json +4 -3
  304. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  305. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  306. package/playbooks/publish/PLAYBOOK.md +45 -33
  307. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  308. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -0,0 +1,82 @@
1
+ export declare const SPEND_LOCK_PARENT = ".ax/state/spend-lock";
2
+ export declare const SPEND_LOCK_DIR = ".ax/state/spend-lock/held";
3
+ export declare const SPEND_CLAIMS_DIR = ".ax/state/spend-recovery-claims";
4
+ export declare const SPEND_RETIRED_DIR = ".ax/state/spend-retired-locks";
5
+ export declare const SPEND_LEAKS_FILE = ".ax/state/spend-lock-leaks.jsonl";
6
+ export interface SpendHolder {
7
+ kind: 'spend';
8
+ token: string;
9
+ pid: number;
10
+ host: string | null;
11
+ bootId: string | null;
12
+ acquiredAt: string;
13
+ boundMs: number;
14
+ nonces: string[];
15
+ }
16
+ export interface SpendIdentity {
17
+ host: string | null;
18
+ bootId: string | null;
19
+ }
20
+ export type SpendVerdict = {
21
+ dead: true;
22
+ case: 1 | 2;
23
+ } | {
24
+ dead: false;
25
+ reason: 'host' | 'boot-unknown' | 'case-1-off' | 'alive' | 'leak';
26
+ };
27
+ /**
28
+ * Whether a spend holder is certainly dead. Never across hosts or with a null identity; case 1 (another boot of this
29
+ * host) is off on darwin; case 2 (this boot) needs ESRCH. This process's pid is never dead (R1): this module's own
30
+ * token is a leak, any other is another thread or module copy.
31
+ */
32
+ export declare function spendVerdict(holder: {
33
+ pid: number;
34
+ host: string | null;
35
+ bootId: string | null;
36
+ token: string;
37
+ }, me: SpendIdentity, platform: NodeJS.Platform, probe?: (pid: number) => 'dead' | 'alive'): SpendVerdict;
38
+ /** A recovery claim older than this may be taken as dead by the operator (A-SPEC-245.11, W3). */
39
+ export declare const CLAIM_STALE_MS = 60000;
40
+ /** The spend lock's holder record, or null when no lock is held or it cannot be read. */
41
+ export declare function spendLockHolder(root: string): SpendHolder | null;
42
+ export interface SpendLockOptions {
43
+ budgetMs: number;
44
+ nonces?: string[];
45
+ /** The step bound of the commit kind held under the lock; doctor's alarm fires at 4x. */
46
+ boundMs?: number;
47
+ identity?: SpendIdentity;
48
+ platform?: NodeJS.Platform;
49
+ }
50
+ /**
51
+ * Take the workspace spend lock within `budgetMs`, recovering a certainly dead holder on the way. Busy past the budget
52
+ * is `lock-busy` — every pass that does not acquire checks the deadline and waits (R2); this module's own hold is
53
+ * `lock-leak`; a lock without a readable holder is `unknown-owner`.
54
+ */
55
+ export declare function acquireSpendLock(root: string, opts: SpendLockOptions): {
56
+ token: string;
57
+ release(): void;
58
+ };
59
+ export declare function withSpendLock<T>(root: string, opts: SpendLockOptions, act: () => T): T;
60
+ export type OperatorRecovery = {
61
+ recovered: SpendHolder;
62
+ reason: string;
63
+ } | {
64
+ refused: string;
65
+ } | {
66
+ nothing: true;
67
+ };
68
+ /**
69
+ * The operator's recovery of the spend lock. The caller judges the harness first.
70
+ * - A dead holder is recovered.
71
+ * - Another host, a null identity, or another boot on darwin needs `confirmHolderDead`.
72
+ * - An answering holder (alive, EPERM, or a reused pid) needs `confirmHolderDead` and a hold longer than 4x its bound
73
+ * (M-b); this process's own hold is refused.
74
+ * - Only the generation judged is retired (R3): a lock that changed hands meanwhile is refused.
75
+ */
76
+ export declare function recoverSpendLockAsOperator(root: string, opts: {
77
+ confirmHolderDead: boolean;
78
+ identity?: SpendIdentity;
79
+ platform?: NodeJS.Platform;
80
+ now?: () => number;
81
+ expectToken?: string | null;
82
+ }): OperatorRecovery;
@@ -0,0 +1,413 @@
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.CLAIM_STALE_MS = exports.SPEND_LEAKS_FILE = exports.SPEND_RETIRED_DIR = exports.SPEND_CLAIMS_DIR = exports.SPEND_LOCK_DIR = exports.SPEND_LOCK_PARENT = void 0;
37
+ exports.spendVerdict = spendVerdict;
38
+ exports.spendLockHolder = spendLockHolder;
39
+ exports.acquireSpendLock = acquireSpendLock;
40
+ exports.withSpendLock = withSpendLock;
41
+ exports.recoverSpendLockAsOperator = recoverSpendLockAsOperator;
42
+ // @implements A-SPEC-245.10, A-SPEC-245.11, A-SPEC-245.12
43
+ /**
44
+ * The workspace spend lock: one holder per workspace for spending single-use approvals (slice 1a of A-SPEC-245.7,
45
+ * moved here from owned-lock.ts by A-SPEC-245.10), on the owned-lock protocol.
46
+ *
47
+ * Recovery is automatic only when the holder is certainly dead: never across hosts or with a null host or boot id;
48
+ * case 1 (another boot of this host) off on darwin; case 2 (this boot, the pid answering ESRCH). A holder with this
49
+ * process's pid is never dead (R1): its token in this module's registry is a leak, otherwise it is another thread or
50
+ * another copy of this module, alive. Acquisition never runs past its budget (R2), and the operator retires only the
51
+ * generation it judged (R3).
52
+ *
53
+ * Limits: one host and a local file system; an earlier holder of this boot whose pid this process now has waits for
54
+ * the operator.
55
+ */
56
+ const fs = __importStar(require("node:fs"));
57
+ const path = __importStar(require("node:path"));
58
+ const node_crypto_1 = require("node:crypto");
59
+ const owned_lock_1 = require("./owned-lock");
60
+ exports.SPEND_LOCK_PARENT = '.ax/state/spend-lock';
61
+ exports.SPEND_LOCK_DIR = `${exports.SPEND_LOCK_PARENT}/held`;
62
+ exports.SPEND_CLAIMS_DIR = '.ax/state/spend-recovery-claims';
63
+ exports.SPEND_RETIRED_DIR = '.ax/state/spend-retired-locks';
64
+ exports.SPEND_LEAKS_FILE = '.ax/state/spend-lock-leaks.jsonl';
65
+ const SPEND_LAYOUT = { parent: exports.SPEND_LOCK_PARENT, name: 'held', claims: exports.SPEND_CLAIMS_DIR, retired: exports.SPEND_RETIRED_DIR };
66
+ const FINGERPRINT = /^nonce:[0-9a-f]{12}$/;
67
+ const TRANSIENT = /^\.lock-[0-9a-f-]{36}\.tmp$/;
68
+ /** Plain primitives under one root: no symlinked directories, regular files only, exclusive publication. */
69
+ function plainLockFs(root) {
70
+ const stat = (file) => {
71
+ try {
72
+ return fs.lstatSync(file);
73
+ }
74
+ catch (e) {
75
+ if (e.code === 'ENOENT')
76
+ return undefined;
77
+ throw e;
78
+ }
79
+ };
80
+ const directory = (relative, create = false) => {
81
+ let current = root;
82
+ for (const part of relative.replace(/\\/g, '/').split('/').filter((p) => p !== '' && p !== '.')) {
83
+ if (part === '..')
84
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock paths must be canonical relative locators.');
85
+ current = path.join(current, part);
86
+ if (create && !stat(current)) {
87
+ try {
88
+ fs.mkdirSync(current);
89
+ }
90
+ catch (e) {
91
+ if (e.code !== 'EEXIST')
92
+ throw e;
93
+ }
94
+ }
95
+ const s = stat(current);
96
+ if (s && (!s.isDirectory() || s.isSymbolicLink()))
97
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock directories must not be symlinks or non-directories.');
98
+ }
99
+ return current;
100
+ };
101
+ const readBytes = (file) => {
102
+ const s = stat(file);
103
+ if (!s)
104
+ return undefined;
105
+ if (!s.isFile())
106
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Lock records must be regular files.');
107
+ // an unreadable record (EACCES and the like) is preserved ownership, never a raw error (A-SPEC-245.12)
108
+ try {
109
+ return fs.readFileSync(file);
110
+ }
111
+ catch (e) {
112
+ if (e.code === 'ENOENT')
113
+ return undefined;
114
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', `A lock record that cannot be read (${e.code ?? 'error'}) is preserved for inspection.`);
115
+ }
116
+ };
117
+ return {
118
+ stat, directory, readBytes,
119
+ publish: (relative, bytes) => {
120
+ const dir = directory(path.dirname(relative), true);
121
+ const temp = path.join(dir, `.lock-${(0, node_crypto_1.randomUUID)()}.tmp`);
122
+ fs.writeFileSync(temp, bytes, { flag: 'wx', mode: 0o600 });
123
+ try {
124
+ fs.linkSync(temp, path.join(dir, path.basename(relative)));
125
+ }
126
+ finally {
127
+ fs.unlinkSync(temp);
128
+ }
129
+ },
130
+ rename: (from, to) => fs.renameSync(from, to),
131
+ renameNew: (from, to) => fs.renameSync(from, to),
132
+ appendLine: (file, line) => { directory(path.relative(root, path.dirname(file)), true); fs.appendFileSync(file, line + '\n'); },
133
+ replace: (relative, before, after) => {
134
+ const file = path.join(root, relative);
135
+ if (fs.readFileSync(file, 'utf8') !== before)
136
+ return;
137
+ const temp = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
138
+ fs.writeFileSync(temp, after, { flag: 'wx', mode: 0o600 });
139
+ fs.renameSync(temp, file);
140
+ },
141
+ list: (dir) => fs.readdirSync(dir),
142
+ makeDir: (dir) => fs.mkdirSync(dir),
143
+ writeNew: (file, bytes) => fs.writeFileSync(file, bytes, { flag: 'wx', mode: 0o600 }),
144
+ unlink: (file) => fs.unlinkSync(file),
145
+ removeDir: (dir) => fs.rmdirSync(dir),
146
+ removeTree: (dir) => fs.rmSync(dir, { recursive: true, force: true }),
147
+ isOwnTransient: (name) => TRANSIENT.test(name),
148
+ };
149
+ }
150
+ /** Tokens of spend locks this copy of the module holds, in this thread. */
151
+ const held = new Set();
152
+ function identityOf(given) {
153
+ if (given)
154
+ return given;
155
+ const m = require('./machine-identity');
156
+ return { host: m.hostId(), bootId: m.bootId() };
157
+ }
158
+ function validSpendHolder(r) {
159
+ if (typeof r !== 'object' || r === null)
160
+ return false;
161
+ const o = r;
162
+ const keys = ['kind', 'token', 'pid', 'host', 'bootId', 'acquiredAt', 'boundMs', 'nonces'];
163
+ return Object.keys(o).every((k) => keys.includes(k)) && o.kind === 'spend' && (0, owned_lock_1.isLockToken)(o.token)
164
+ && Number.isSafeInteger(o.pid) && o.pid > 0
165
+ && (o.host === null || typeof o.host === 'string') && (o.bootId === null || typeof o.bootId === 'string')
166
+ && typeof o.acquiredAt === 'string' && typeof o.boundMs === 'number' && o.boundMs > 0
167
+ && Array.isArray(o.nonces) && o.nonces.every((n) => typeof n === 'string' && FINGERPRINT.test(n));
168
+ }
169
+ function validSpendClaim(r) {
170
+ if (typeof r !== 'object' || r === null)
171
+ return false;
172
+ const o = r;
173
+ const keys = ['kind', 'token', 'pid', 'host', 'bootId', 'claimedAt', 'recovers', 'released'];
174
+ return Object.keys(o).every((k) => keys.includes(k)) && o.kind === 'spend-recovery' && (0, owned_lock_1.isLockToken)(o.token)
175
+ && Number.isSafeInteger(o.pid) && o.pid > 0
176
+ && (o.host === null || typeof o.host === 'string') && (o.bootId === null || typeof o.bootId === 'string')
177
+ && typeof o.claimedAt === 'string' && (0, owned_lock_1.isLockToken)(o.recovers) && (o.released === undefined || o.released === true);
178
+ }
179
+ /**
180
+ * Whether a spend holder is certainly dead. Never across hosts or with a null identity; case 1 (another boot of this
181
+ * host) is off on darwin; case 2 (this boot) needs ESRCH. This process's pid is never dead (R1): this module's own
182
+ * token is a leak, any other is another thread or module copy.
183
+ */
184
+ function spendVerdict(holder, me, platform, probe = probePid) {
185
+ if (holder.host === null || me.host === null || holder.host !== me.host)
186
+ return { dead: false, reason: 'host' };
187
+ if (holder.bootId === null || me.bootId === null)
188
+ return { dead: false, reason: 'boot-unknown' };
189
+ if (holder.bootId !== me.bootId)
190
+ return platform === 'darwin' ? { dead: false, reason: 'case-1-off' } : { dead: true, case: 1 };
191
+ if (holder.pid === process.pid)
192
+ return { dead: false, reason: held.has(holder.token) ? 'leak' : 'alive' };
193
+ return probe(holder.pid) === 'dead' ? { dead: true, case: 2 } : { dead: false, reason: 'alive' };
194
+ }
195
+ /** ESRCH is dead; an answer or EPERM is alive. */
196
+ function probePid(pid) {
197
+ try {
198
+ process.kill(pid, 0);
199
+ return 'alive';
200
+ }
201
+ catch (e) {
202
+ return e.code === 'ESRCH' ? 'dead' : 'alive';
203
+ }
204
+ }
205
+ /** A recovery claim older than this may be taken as dead by the operator (A-SPEC-245.11, W3). */
206
+ exports.CLAIM_STALE_MS = 60_000;
207
+ /** The spend policy; `force` makes the operator's judgement final for what it covers. */
208
+ function spendPolicy(me, platform, force) {
209
+ return {
210
+ kind: 'spend',
211
+ valid: (r, first) => (first ? validSpendHolder(r) : validSpendClaim(r)),
212
+ judgeDead: (r, first) => {
213
+ if (force !== undefined && first) {
214
+ if (r.token === force.token)
215
+ return;
216
+ throw new owned_lock_1.LockError('lock-busy', 'recover-live', 'The spend lock changed hands after it was judged; it is not recovered. Judge it again.');
217
+ }
218
+ const v = spendVerdict(r, me, platform);
219
+ if (v.dead)
220
+ return;
221
+ if (first)
222
+ throw new owned_lock_1.LockError('lock-busy', 'recover-live', busyMessage(r, v.reason));
223
+ // a successor claim: a recoverer that published it and may have died (W3)
224
+ const ageMs = (force?.now ?? Date.now()) - Date.parse(String(r.claimedAt));
225
+ if (force?.confirmClaims && ageMs > exports.CLAIM_STALE_MS)
226
+ return;
227
+ throw new owned_lock_1.LockError('lock-busy', 'recover-live', claimBusyMessage(r, v.reason, ageMs, force !== undefined));
228
+ },
229
+ claim: (recovers) => ({ kind: 'spend-recovery', token: (0, node_crypto_1.randomUUID)(), pid: process.pid, host: me.host, bootId: me.bootId, claimedAt: new Date().toISOString(), recovers }),
230
+ };
231
+ }
232
+ function busyMessage(h, reason) {
233
+ const why = {
234
+ host: 'it was taken on another host, or a host identity is unknown',
235
+ 'boot-unknown': 'a boot identifier is unknown',
236
+ 'case-1-off': 'it was taken on an earlier boot, and recovery across boots is off on this platform',
237
+ alive: 'its holder is running',
238
+ leak: 'this process holds it',
239
+ }[reason];
240
+ const route = reason === 'alive' || reason === 'leak' ? 'Retry when it is released.'
241
+ : 'If the holder is dead, the operator runs `holmes-kit lock recover spend --confirm-holder-dead` from a terminal.';
242
+ return `The spend lock is held by pid ${h.pid}; ${why}. ${route}`;
243
+ }
244
+ function claimBusyMessage(claim, reason, ageMs, operator) {
245
+ const age = `${Math.max(0, ageMs / 1000).toFixed(1)} s old`;
246
+ if (!operator)
247
+ return `A recovery claim by pid ${claim.pid} (${age}, ${reason}) blocks this recovery. If that recoverer is dead, the operator runs \`holmes-kit lock recover spend --confirm-holder-dead\` from a terminal once the claim is older than ${exports.CLAIM_STALE_MS / 1000} s.`;
248
+ return ageMs > exports.CLAIM_STALE_MS
249
+ ? `A recovery claim by pid ${claim.pid} (${age}, ${reason}) blocks the recovery; if that recoverer is dead, run again with --confirm-holder-dead.`
250
+ : `A recovery claim by pid ${claim.pid} (${age}, ${reason}) blocks the recovery; a claim younger than ${exports.CLAIM_STALE_MS / 1000} s may still be working — wait, then run again with --confirm-holder-dead if it is dead.`;
251
+ }
252
+ /**
253
+ * The holder record read through a LockFs, or null when no lock is held or it cannot be read. The lock directory is
254
+ * reached through `directory`, so a symlinked path reads as no holder (A-SPEC-245.12).
255
+ */
256
+ function holderThrough(lfs, root) {
257
+ try {
258
+ const bytes = lfs.readBytes(path.join(lfs.directory(exports.SPEND_LOCK_DIR), 'owner.json'));
259
+ const r = bytes ? JSON.parse(bytes.toString('utf8')) : null;
260
+ return validSpendHolder(r) ? r : null;
261
+ }
262
+ catch {
263
+ return null;
264
+ }
265
+ }
266
+ /** The spend lock's holder record, or null when no lock is held or it cannot be read. */
267
+ function spendLockHolder(root) { return holderThrough(plainLockFs(root), root); }
268
+ function recordLeak(lfs, root, holder) {
269
+ try {
270
+ lfs.appendLine(path.join(root, exports.SPEND_LEAKS_FILE), JSON.stringify({ at: new Date().toISOString(), pid: process.pid, acquiredAt: holder.acquiredAt, locator: exports.SPEND_LOCK_DIR }));
271
+ }
272
+ catch { /* the leak is reported by the throw either way */ }
273
+ }
274
+ const sleepSync = (ms) => { try {
275
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
276
+ }
277
+ catch { /* retry without waiting */ } };
278
+ const unwrapAct = (f) => { try {
279
+ return f();
280
+ }
281
+ catch (e) {
282
+ throw e instanceof owned_lock_1.ActError ? e.inner : e;
283
+ } };
284
+ /**
285
+ * Take the workspace spend lock within `budgetMs`, recovering a certainly dead holder on the way. Busy past the budget
286
+ * is `lock-busy` — every pass that does not acquire checks the deadline and waits (R2); this module's own hold is
287
+ * `lock-leak`; a lock without a readable holder is `unknown-owner`.
288
+ */
289
+ function acquireSpendLock(root, opts) {
290
+ const lfs = plainLockFs(root);
291
+ const me = identityOf(opts.identity);
292
+ const platform = opts.platform ?? process.platform;
293
+ const record = { kind: 'spend', token: (0, node_crypto_1.randomUUID)(), pid: process.pid, host: me.host, bootId: me.bootId,
294
+ acquiredAt: new Date().toISOString(), boundMs: opts.boundMs ?? 1000, nonces: (opts.nonces ?? []).filter((n) => FINGERPRINT.test(n)) };
295
+ const deadline = Date.now() + opts.budgetMs;
296
+ let lastBusy = `The spend lock (${exports.SPEND_LOCK_DIR}) is held.`;
297
+ for (;;) {
298
+ try {
299
+ const release = (0, owned_lock_1.acquireOwnedLock)(lfs, SPEND_LAYOUT, record);
300
+ held.add(record.token);
301
+ return { token: record.token, release: () => { try {
302
+ release();
303
+ }
304
+ finally {
305
+ held.delete(record.token);
306
+ } } };
307
+ }
308
+ catch (e) {
309
+ if (!(e instanceof owned_lock_1.LockError) || e.code !== 'lock-busy')
310
+ throw e;
311
+ }
312
+ // A-SPEC-245.11 (W7), 245.12: the holder is read through this lock's own filesystem and its checked directory
313
+ const dir = lfs.directory(exports.SPEND_LOCK_DIR);
314
+ let raw = undefined, vanished = false;
315
+ const bytes = lfs.readBytes(path.join(dir, 'owner.json'));
316
+ if (bytes === undefined) {
317
+ if (!lfs.stat(dir))
318
+ vanished = true; // released between the two reads
319
+ else
320
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'A spend lock without a holder record is preserved for inspection.');
321
+ }
322
+ else {
323
+ try {
324
+ raw = JSON.parse(bytes.toString('utf8'));
325
+ }
326
+ catch {
327
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Malformed lock ownership must be preserved.');
328
+ }
329
+ }
330
+ if (!vanished) {
331
+ if (!validSpendHolder(raw))
332
+ throw new owned_lock_1.LockError('unknown-owner', 'inspect', 'Invalid lock ownership must be preserved.');
333
+ const v = spendVerdict(raw, me, platform);
334
+ if (!v.dead && v.reason === 'leak') {
335
+ recordLeak(lfs, root, raw);
336
+ throw new owned_lock_1.LockError('lock-leak', 'acquire', `This process already holds the spend lock (${exports.SPEND_LOCK_DIR}); a second acquisition is a leak.`);
337
+ }
338
+ if (v.dead) {
339
+ try {
340
+ unwrapAct(() => (0, owned_lock_1.recoverOwnedLock)(lfs, SPEND_LAYOUT, spendPolicy(me, platform), () => undefined, () => () => undefined));
341
+ }
342
+ catch (e) {
343
+ if (!(e instanceof owned_lock_1.LockError) || e.code !== 'lock-busy')
344
+ throw e;
345
+ lastBusy = e.message;
346
+ }
347
+ }
348
+ else
349
+ lastBusy = busyMessage(raw, v.reason);
350
+ }
351
+ if (Date.now() >= deadline)
352
+ throw new owned_lock_1.LockError('lock-busy', 'acquire', lastBusy);
353
+ sleepSync(Math.min(15, Math.max(1, deadline - Date.now())));
354
+ }
355
+ }
356
+ function withSpendLock(root, opts, act) {
357
+ const h = acquireSpendLock(root, opts);
358
+ try {
359
+ return act();
360
+ }
361
+ finally {
362
+ h.release();
363
+ }
364
+ }
365
+ /**
366
+ * The operator's recovery of the spend lock. The caller judges the harness first.
367
+ * - A dead holder is recovered.
368
+ * - Another host, a null identity, or another boot on darwin needs `confirmHolderDead`.
369
+ * - An answering holder (alive, EPERM, or a reused pid) needs `confirmHolderDead` and a hold longer than 4x its bound
370
+ * (M-b); this process's own hold is refused.
371
+ * - Only the generation judged is retired (R3): a lock that changed hands meanwhile is refused.
372
+ */
373
+ function recoverSpendLockAsOperator(root, opts) {
374
+ const lfs = plainLockFs(root);
375
+ const holder = holderThrough(lfs, root);
376
+ if (!holder)
377
+ return lfs.stat(path.join(root, exports.SPEND_LOCK_DIR)) ? { refused: 'The spend lock has no readable holder record; it is preserved for inspection.' } : { nothing: true };
378
+ // A-SPEC-245.11, 245.12 (low): the caller recorded the holder it read — or that it read none (null); a lock that
379
+ // changed hands since is not this recovery's
380
+ if (opts.expectToken !== undefined && holder.token !== opts.expectToken)
381
+ return { refused: 'The spend lock changed hands after it was read; it is not recovered. Run again to judge the current holder.' };
382
+ const me = identityOf(opts.identity);
383
+ const platform = opts.platform ?? process.platform;
384
+ const v = spendVerdict(holder, me, platform);
385
+ let reason;
386
+ if (v.dead)
387
+ reason = `case ${v.case}: the holder is dead`;
388
+ else if (v.reason === 'leak')
389
+ return { refused: 'This process holds the spend lock; it is released when its act ends.' };
390
+ else if (v.reason === 'alive') {
391
+ const ageMs = (opts.now ?? Date.now)() - Date.parse(holder.acquiredAt);
392
+ if (!opts.confirmHolderDead)
393
+ return { refused: `The spend lock's holder, pid ${holder.pid}, answers on this host; if that pid is not the holder (reused) and the holder is dead, run again with --confirm-holder-dead once it has been held longer than 4x its bound.` };
394
+ if (!(ageMs > 4 * holder.boundMs))
395
+ return { refused: `The spend lock's holder, pid ${holder.pid}, answers and has been held ${(ageMs / 1000).toFixed(1)} s, not yet longer than 4x its bound of ${(holder.boundMs / 1000).toFixed(1)} s; it is not recovered.` };
396
+ reason = `confirmed dead by the operator: pid ${holder.pid} answers, held past 4x its bound`;
397
+ }
398
+ else {
399
+ if (!opts.confirmHolderDead)
400
+ return { refused: `The spend lock's holder, pid ${holder.pid}, cannot be judged dead here (${v.reason}); if it is dead, run again with --confirm-holder-dead.` };
401
+ reason = `confirmed dead by the operator (${v.reason})`;
402
+ }
403
+ const force = { token: holder.token, confirmClaims: opts.confirmHolderDead, now: (opts.now ?? Date.now)() };
404
+ try {
405
+ unwrapAct(() => (0, owned_lock_1.recoverOwnedLock)(lfs, SPEND_LAYOUT, spendPolicy(me, platform, force), () => undefined, () => () => undefined));
406
+ }
407
+ catch (e) {
408
+ if (e instanceof owned_lock_1.LockError && e.code === 'lock-busy')
409
+ return { refused: e.message };
410
+ throw e;
411
+ }
412
+ return { recovered: holder, reason };
413
+ }
@@ -1,6 +1,7 @@
1
1
  import { Agent } from '../cli/agents';
2
2
  import { WorkspaceIdentityStatus } from './workspace-identity';
3
3
  import { CheckoutInfo } from './workspace-checkout';
4
+ import type { InstallIdentity, StaleFact } from '../mcp/server-staleness';
4
5
  export type { CheckoutInfo } from './workspace-checkout';
5
6
  export type PreflightCheck = {
6
7
  id: string;
@@ -24,4 +25,8 @@ export declare function inspectWorkspacePreflight(input: {
24
25
  storeRoot?: string;
25
26
  harness?: Agent;
26
27
  now?: number;
28
+ server?: {
29
+ loaded: InstallIdentity;
30
+ stale: StaleFact | null;
31
+ };
27
32
  }): WorkspacePreflight;
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.inspectWorkspacePreflight = inspectWorkspacePreflight;
37
- // @implements A-SPEC-703, A-SPEC-772.1, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.10, A-SPEC-772.11
37
+ // @implements A-SPEC-703, A-SPEC-772.1, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-251.4
38
38
  const fs = __importStar(require("node:fs"));
39
39
  const path = __importStar(require("node:path"));
40
40
  const root_1 = require("./root");
@@ -77,6 +77,25 @@ function enforcementCheck(root, harness, now) {
77
77
  return { status: 'unknown', detail: `${harness} hooks were never observed in this workspace; live activation is unverified.${recorderOff()}`,
78
78
  actions: [`Run holmes-kit doctor --target ${root} and check the ${harness} hook wiring.`] };
79
79
  }
80
+ /**
81
+ * @implements A-SPEC-251.4 — the MCP server's loaded build against the install under it and the hook build observed
82
+ * for this harness. A different hook build means the session's tools and its gate come from different releases.
83
+ */
84
+ function mcpBuildCheck(root, server, harness, now) {
85
+ const loaded = `v${server.loaded.version} (build ${server.loaded.buildId})`;
86
+ if (server.stale !== null) {
87
+ return { status: 'blocked', detail: `This MCP server loaded ${loaded}, but its install is now v${server.stale.onDisk.version} (build ${server.stale.onDisk.buildId}).`,
88
+ actions: ['Restart the harness session (or its MCP server) so the server loads the installed build.'] };
89
+ }
90
+ if (harness !== undefined) {
91
+ const o = (0, heartbeat_1.observationOf)((0, heartbeat_1.readHookHeartbeats)(root, now), harness, now, undefined, 'pre-tool-use');
92
+ if (o.state === 'observed' && o.buildId !== server.loaded.buildId) {
93
+ return { status: 'blocked', detail: `This MCP server is ${loaded}, but the ${harness} hooks here ran build ${o.buildId} at ${o.at}.`,
94
+ actions: ['Align the MCP server and the hooks on one build: restart the session after upgrading, or rewire with holmes-kit init.'] };
95
+ }
96
+ }
97
+ return { status: 'pass', detail: `MCP server ${loaded} matches its install${harness !== undefined ? ' and the observed hooks' : ''}.`, actions: [] };
98
+ }
80
99
  function inspectWorkspacePreflight(input) {
81
100
  const out = { schema: 'holmes-workspace-preflight/1', requestedRoot: null,
82
101
  boundRoot: null, boundSpecsRoot: null, binding: 'invalid', identity: null, checkout: null, checks: [], nextActions: [] };
@@ -124,6 +143,10 @@ function inspectWorkspacePreflight(input) {
124
143
  const e = enforcementCheck(out.boundRoot, input.harness, input.now ?? Date.now());
125
144
  check('runtime-enforcement', e.status, e.detail, e.actions);
126
145
  }
146
+ if (input.server !== undefined) {
147
+ const m = mcpBuildCheck(out.boundRoot, input.server, input.harness, input.now ?? Date.now());
148
+ check('mcp-build', m.status, m.detail, m.actions);
149
+ }
127
150
  return out;
128
151
  }
129
152
  catch (e) {
@@ -40,7 +40,7 @@ export declare const FRESHNESS_LEASE_MS: number;
40
40
  /** A failed detached worker is visible immediately but retries only after this bounded pause. */
41
41
  export declare const FRESHNESS_RETRY_MS: number;
42
42
  /**
43
- * @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a jarvis refresh
43
+ * @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a consumer workspace's refresh
44
44
  * outlived the 2-minute lease, every later request spawned another child, and 13 ran at once (attempt 13, load
45
45
  * 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
46
46
  */
@@ -64,7 +64,7 @@ exports.FRESHNESS_LEASE_MS = 2 * 60 * 1000;
64
64
  /** A failed detached worker is visible immediately but retries only after this bounded pause. */
65
65
  exports.FRESHNESS_RETRY_MS = 30 * 1000;
66
66
  /**
67
- * @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a jarvis refresh
67
+ * @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a consumer workspace's refresh
68
68
  * outlived the 2-minute lease, every later request spawned another child, and 13 ran at once (attempt 13, load
69
69
  * 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
70
70
  */
@@ -42,6 +42,7 @@ const path = __importStar(require("node:path"));
42
42
  const language_parser_1 = require("../cpg/language-parser");
43
43
  const condition_hunk_resolution_1 = require("./condition-hunk-resolution");
44
44
  const bounded_io_1 = require("../project/bounded-io");
45
+ const root_1 = require("../project/root");
45
46
  const SAFE_COMMIT = /^[0-9a-f]{7,64}$/;
46
47
  const sourceLanguage = (file) => {
47
48
  if (/\.(ts|mts|cts)$/.test(file))
@@ -51,8 +52,9 @@ const sourceLanguage = (file) => {
51
52
  return null;
52
53
  };
53
54
  const safePath = (file) => file !== '' && !path.isAbsolute(file) && !file.split(/[\\/]/).includes('..');
55
+ // @implements A-SPEC-792.39 — the shared inert git environment; the diff runs no external diff or textconv.
54
56
  const git = (root, args) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], { timeout: bounded_io_1.GIT_LONG_TIMEOUT_MS,
55
- encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024,
57
+ encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024, env: (0, bounded_io_1.gitEnv)((0, root_1.cleanSubprocessEnv)()),
56
58
  });
57
59
  /** Replays caller-selected commits only; it never checks out, writes a cache, or inspects another repository. */
58
60
  async function replayConditionHunks(input) {
@@ -74,7 +76,7 @@ async function replayConditionHunks(input) {
74
76
  const baselineStart = Date.now();
75
77
  try {
76
78
  source = git(input.root, ['show', `${replayCase.commit}:${file}`]);
77
- diff = git(input.root, ['diff', '--unified=0', `${replayCase.commit}^`, replayCase.commit, '--', file]);
79
+ diff = git(input.root, ['diff', '--no-ext-diff', '--no-textconv', '--unified=0', `${replayCase.commit}^`, replayCase.commit, '--', file]);
78
80
  }
79
81
  catch {
80
82
  continue;
@@ -7,7 +7,7 @@
7
7
  * corpora, with the highest band the worst in each:
8
8
  *
9
9
  * holmes conf 0.25 → recall 0.751 conf 0.70 → 0.306 conf 0.85 → 0.542 r = −0.309
10
- * jarvis conf 0.25 → recall 0.669 conf 0.65 → 0.646 conf 0.85 → 0.000 r = −0.212
10
+ * consumer conf 0.25 → recall 0.669 conf 0.65 → 0.646 conf 0.85 → 0.000 r = −0.212
11
11
  *
12
12
  * A caller who trusts this field trusts the wrong answers most. On the second corpus the two cases
13
13
  * the harness was surest about returned nothing correct at all.
@@ -14,7 +14,7 @@ exports.CONFIDENCE_BY_CORPUS = [
14
14
  ],
15
15
  },
16
16
  {
17
- corpus: 'jarvis clean-30', cases: 30, correlationWithRecall: -0.212,
17
+ corpus: 'consumer clean-30', cases: 30, correlationWithRecall: -0.212,
18
18
  bands: [
19
19
  { confidence: 0.25, n: 12, meanRecall: 0.669, meanPrecision: 0.175 },
20
20
  { confidence: 0.65, n: 16, meanRecall: 0.646, meanPrecision: 0.119 },
@@ -43,7 +43,7 @@ function mentionNames(headPath, headSymbols) {
43
43
  // @implements A-SPEC-490 — the excerpt fix S-507 demanded: a 400-char excerpt of a Google-style
44
44
  // file is ALL license header, and a judge reading it learns nothing. Only blocks that actually
45
45
  // talk about licensing are dropped; an informative leading comment (a Korean docstring) is
46
- // exactly what made the JARVIS judgments strong and must survive.
46
+ // exactly what made the consumer corpus's judgments strong and must survive.
47
47
  const LICENSE_RE = /license|copyright|spdx/i;
48
48
  function skipLicenseHeader(text) {
49
49
  let rest = text;