@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
@@ -1364,6 +1364,39 @@ function runInitUnguarded(opts) {
1364
1364
  }
1365
1365
  catch { /* the wiring is the point; the invitation is not */
1366
1366
  }
1367
+ // @implements A-SPEC-792.16 — what the product installed, by path and digest: the record that keeps product files out
1368
+ // of any self-approval. Every file written inside the target, the skills and the roles guidance; removed with the wiring.
1369
+ if (!opts.dryRun) {
1370
+ const manifest = require('../governance/install-manifest');
1371
+ try {
1372
+ if (opts.remove)
1373
+ manifest.removeInstallManifest(opts.target);
1374
+ else {
1375
+ const filesUnder = (p) => {
1376
+ let st;
1377
+ try {
1378
+ st = fs.statSync(p);
1379
+ }
1380
+ catch {
1381
+ return [];
1382
+ }
1383
+ if (st.isFile())
1384
+ return [p];
1385
+ if (!st.isDirectory())
1386
+ return [];
1387
+ return fs.readdirSync(p).flatMap((n) => filesUnder(path.join(p, n)));
1388
+ };
1389
+ manifest.writeInstallManifest(opts.target, [
1390
+ ...changes.filter((c) => c.after !== null).map((c) => c.path),
1391
+ ...skillStates.flatMap((x) => filesUnder(path.dirname((0, playbook_skills_1.skillPathFor)(opts.target, x.name)))),
1392
+ path.join(opts.target, '.ax', 'roles', 'README.md'),
1393
+ ].flatMap(filesUnder), (0, mcp_launcher_1.readPackageVersion)(opts.packageRoot) ?? 'unknown');
1394
+ }
1395
+ }
1396
+ catch (e) {
1397
+ messages.push(`could not write the install manifest: ${(e instanceof Error ? e.message : String(e)).slice(0, 200)}`);
1398
+ }
1399
+ }
1367
1400
  return { ok: true, exitCode: 0, messages, changes, removals };
1368
1401
  }
1369
1402
  /**
@@ -0,0 +1,5 @@
1
+ export interface LockRecoverIo {
2
+ stdout: (s: string) => void;
3
+ stderr: (s: string) => void;
4
+ }
5
+ export declare function runLockRecover(positionals: string[], flags: Record<string, string | boolean>, io: LockRecoverIo): number;
@@ -0,0 +1,126 @@
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.runLockRecover = runLockRecover;
37
+ // @implements A-SPEC-245.10, A-SPEC-245.11, A-SPEC-245.12, A-SPEC-245.19, A-SPEC-794.6, A-SPEC-102.29, A-SPEC-102.30, A-SPEC-102.31, A-SPEC-102.32
38
+ /**
39
+ * `holmes-kit lock recover spend` (A-SPEC-245.8 item 8, moved out of cli/index.ts by A-SPEC-245.10).
40
+ *
41
+ * - The harness is judged before any flag, so --confirm-holder-dead never turns a harness refusal into a recovery.
42
+ * - A-SPEC-245.19: this judgement is the authority boundary — operatorActGuard, the guard approve --grant uses, refuses
43
+ * when the inherited harness marker or the process ancestry points at an agent, whatever shell syntax started the
44
+ * process. The gate's lockRecoverAct only refuses the direct forms early. Named limit: a process that removes every
45
+ * marker and is reparented away from the harness is not told apart from the operator.
46
+ * - The ledger records `lock-recovery` before the retirement and `lock-recovered` after it; a failed retirement
47
+ * records `lock-recovery-failed`. Host and boot identifiers appear only inside inputs, as HMAC under a subkey of
48
+ * the ledger key (omitted without a key), because a top-level field outside KNOWN_FIELDS fails verifyChain.
49
+ */
50
+ const path = __importStar(require("node:path"));
51
+ const node_crypto_1 = require("node:crypto");
52
+ function runLockRecover(positionals, flags, io) {
53
+ const { operatorActVerdict } = require('../guardrail/operator-person');
54
+ // @implements A-SPEC-794.6 — `lock recover request <id>` is a sibling kind under the same operator judgement
55
+ const act = positionals[1] === 'request' ? 'holmes-kit lock recover request' : 'holmes-kit lock recover spend';
56
+ // @implements A-SPEC-102.29 — judged with the catalog of the project the act recovers
57
+ // @implements A-SPEC-102.30 — that project is actRoot's, --target or the working directory's, the one it recovers in
58
+ const root = require('../project/act-root').actRoot(flags);
59
+ const refused = operatorActVerdict(act, root);
60
+ if (refused !== null) {
61
+ // @implements A-SPEC-102.31 (low 8) — a refusal that is not about a harness (a project that cannot be resolved) is
62
+ // printed as the guard words it, never as "runs under an agent harness". @implements A-SPEC-102.32 — the guard says
63
+ // which: its sentence is not parsed, so a path's text cannot name a harness (A, low 7)
64
+ io.stderr(refused.harness === undefined ? `${refused.text}\n` : `${act} is the operator's act, run from a terminal the operator opened — this process runs under an agent harness (${refused.harness}).\n`);
65
+ return 1;
66
+ }
67
+ const isRequest = positionals.length === 3 && positionals[0] === 'recover' && positionals[1] === 'request' && /^req-[0-9a-f]{12}$/.test(positionals[2]);
68
+ if (positionals.join(' ') !== 'recover spend' && !isRequest) {
69
+ io.stderr('usage: holmes-kit lock recover spend [--target <dir>] [--confirm-holder-dead]\n holmes-kit lock recover request <req-id> [--target <dir>] [--confirm-holder-dead]\n');
70
+ return 2;
71
+ }
72
+ const { FileLedgerStore } = require('../governance/ledger-store');
73
+ const ledger = new FileLedgerStore(path.join(root, '.ax', 'ledger'));
74
+ const confirmHolderDead = flags['confirm-holder-dead'] === true;
75
+ let what, locator, holder, recoverAs;
76
+ if (isRequest) {
77
+ const id = positionals[2];
78
+ const lock = require('../project/request-lock');
79
+ what = `the request lock of ${id}`;
80
+ locator = `${lock.REQUEST_LOCKS_DIR}/${id}`;
81
+ holder = lock.requestLockHolders(root).find((h) => h.id === id) ?? null;
82
+ recoverAs = (expectToken) => lock.recoverRequestLockAsOperator(root, id, { confirmHolderDead, expectToken });
83
+ }
84
+ else {
85
+ const lock = require('../project/spend-lock');
86
+ what = 'the spend lock';
87
+ locator = lock.SPEND_LOCK_DIR;
88
+ holder = lock.spendLockHolder(root);
89
+ recoverAs = (expectToken) => lock.recoverSpendLockAsOperator(root, { confirmHolderDead, expectToken });
90
+ }
91
+ const key = process.env.HOLMES_LEDGER_KEY;
92
+ const subkey = key ? (0, node_crypto_1.createHmac)('sha256', key).update('holmes-lock-identity').digest() : null;
93
+ const mac = (label, v) => (subkey && v !== null ? [`${label}-hmac:${(0, node_crypto_1.createHmac)('sha256', subkey).update(v).digest('hex')}`] : []);
94
+ const ageOf = (acquiredAt) => Math.max(0, (Date.now() - Date.parse(acquiredAt)) / 1000).toFixed(1);
95
+ const inputsOf = (h) => [locator, ...mac('host', h.host), ...mac('boot', h.bootId)];
96
+ const append = (kind, summary, h, why) => ledger.append({ ts: new Date().toISOString(), actor: 'holmes-kit', kind, summary, inputs: inputsOf(h),
97
+ rationale: `locator ${locator}; holder pid ${h.pid}, age ${ageOf(h.acquiredAt)} s; ${why}` });
98
+ if (holder)
99
+ append('lock-recovery', `recovering ${what} held by pid ${holder.pid}`, holder, `the operator ran ${act.replace(/^holmes-kit /, '')}`);
100
+ let outcome;
101
+ // A-SPEC-245.11 (low): the recovery acts on the holder this command recorded, or refuses
102
+ // A-SPEC-245.12 (low): having read no holder is a fact the recovery holds to as well, so the audit rows stay paired
103
+ try {
104
+ outcome = recoverAs(holder ? holder.token : null);
105
+ }
106
+ catch (e) {
107
+ if (holder)
108
+ append('lock-recovery-failed', `${what} held by pid ${holder.pid} was not recovered`, holder, e.message);
109
+ io.stderr(`${what} was not recovered: ${e.message}\n`);
110
+ return 1;
111
+ }
112
+ if ('nothing' in outcome) {
113
+ io.stdout(`no ${what.replace(/^the /, '')} is held\n`);
114
+ return 0;
115
+ }
116
+ if ('refused' in outcome) {
117
+ if (holder)
118
+ append('lock-recovery-failed', `${what} held by pid ${holder.pid} was not recovered`, holder, outcome.refused);
119
+ io.stderr(`${outcome.refused}\n`);
120
+ return 1;
121
+ }
122
+ const h = outcome.recovered;
123
+ append('lock-recovered', `recovered ${what} held by pid ${h.pid} (age ${ageOf(h.acquiredAt)} s)`, h, outcome.reason);
124
+ io.stdout(`recovered ${what} held by pid ${h.pid} (${outcome.reason})\n`);
125
+ return 0;
126
+ }
@@ -43,7 +43,7 @@ exports.mcpProcessBannerLine = mcpProcessBannerLine;
43
43
  /**
44
44
  * Running holmes-kit MCP servers that started before their install was upgraded.
45
45
  *
46
- * Measured 2026-10-23 (D1): the jarvis session's server served v0.36.0 under a 0.38.0 global install — two such
46
+ * Measured 2026-10-23 (D1): an orchestrator session's server served v0.36.0 under a 0.38.0 global install — two such
47
47
  * processes had been alive a day and a half. A server older than A-SPEC-251.4 cannot say so itself; from outside, its
48
48
  * process started before its package.json was written. Read-only: nothing here signals a process.
49
49
  */
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  // @implements A-SPEC-575.1
3
3
  // Publishing reaches surfaces the release procedure never knew about. This repository has NO GitHub
4
- // remote — origin is a local gitea — so three releases went out while the README that npm's
4
+ // remote — origin is a local repository server — so three releases went out while the README that npm's
5
5
  // `homepage` points at stayed frozen at 2026-08-31, and the org profile still said the project was
6
6
  // a walking skeleton under construction.
7
7
  //
@@ -0,0 +1,141 @@
1
+ type Io = {
2
+ stdout: (t: string) => void;
3
+ stderr: (t: string) => void;
4
+ };
5
+ export interface RunExecOptions {
6
+ id?: string;
7
+ target?: string;
8
+ command: string[];
9
+ }
10
+ export interface RunExecDeps {
11
+ home?: string;
12
+ env?: NodeJS.ProcessEnv;
13
+ codexHome?: string;
14
+ tmpdir?: string;
15
+ }
16
+ /**
17
+ * @implements A-SPEC-774.35 — the name Claude Code gives a working directory under `/tmp/claude-<uid>`: its real path
18
+ * with every character outside [A-Za-z0-9] replaced by `-` (the naming measured in `~/.claude/projects`).
19
+ */
20
+ export declare const claudeTmpName: (p: string) => string;
21
+ type Fsx = {
22
+ realpath: (p: string) => string;
23
+ lstat: (p: string) => {
24
+ dev: number;
25
+ ino: number;
26
+ };
27
+ stat: (p: string) => {
28
+ dev: number;
29
+ ino: number;
30
+ };
31
+ };
32
+ /**
33
+ * @implements A-SPEC-774.82 — the one input seam (owner decision 2026-10-25: accept only canonical spellings). Seatbelt
34
+ * judges an access by its real path and a rule as written, so a rule in any other spelling is dead; four rounds of
35
+ * folding spellings (H1.4–H1.7) each left the next one open (/.nofollow, /.vol, /home, lower-case Data). A path is
36
+ * admitted only when it is absolute, carries no virtual prefix, is its own realpath.native, and stats to that file.
37
+ */
38
+ export declare function canonicalOrRefuse(p: string, fsx?: Fsx): {
39
+ path: string;
40
+ } | {
41
+ refused: string;
42
+ };
43
+ /**
44
+ * @implements A-SPEC-774.34, A-SPEC-774.35, A-SPEC-774.36 — the profile: deny every write, then allow exactly what the
45
+ * run's engine needs. Its engine state lives in its own home inside the run temp dir (774.36: nothing reaches the
46
+ * owner's ~/.claude* or ~/.codex); a claude run also gets Claude Code's temp directory for its worktree (774.35).
47
+ */
48
+ export declare function sandboxProfile(p: {
49
+ worktree: string;
50
+ gitDir: string;
51
+ common: string;
52
+ branch: string | null;
53
+ tmp: string;
54
+ engine: string;
55
+ home: string;
56
+ engineHome?: string;
57
+ ownerCodexHome?: string;
58
+ guard?: string;
59
+ readAllow?: string[];
60
+ readAllowNamed?: string[];
61
+ proxyPort?: number;
62
+ shellStartup?: boolean;
63
+ denyRead?: Array<{
64
+ path: string;
65
+ dir: boolean;
66
+ }>;
67
+ tmpRoots?: string[];
68
+ }): string;
69
+ /** @implements A-SPEC-774.34 — git runs no hook and no fsmonitor, reads no system config, and never gcs into the common dir. */
70
+ export declare function sandboxEnv(base: NodeJS.ProcessEnv, run: {
71
+ id: string;
72
+ tmp: string;
73
+ marker: string;
74
+ }): NodeJS.ProcessEnv;
75
+ type ProcRow = {
76
+ ppid: number;
77
+ pgid: number;
78
+ uid: number;
79
+ start: number;
80
+ };
81
+ /**
82
+ * @implements A-SPEC-774.53 — the run's two canaries in a guard directory its profile denies: the engine may write the
83
+ * allow-canary's data, and can neither unlink, rename nor replace either one, nor create anything beside them.
84
+ */
85
+ export type Canary = {
86
+ guard: string;
87
+ allow: string;
88
+ deny: string;
89
+ token: string;
90
+ ids: string[];
91
+ tmp?: string;
92
+ tmpId?: string;
93
+ };
94
+ export declare function makeCanary(tmp: string): Canary;
95
+ /** @implements A-SPEC-774.53 — null when both canaries are still the regular files run exec made, holding its token. */
96
+ export declare function canaryProblem(c: Canary): string | null;
97
+ /**
98
+ * @implements A-SPEC-774.50, A-SPEC-774.53 — the pids, among `pids`, inside THIS run's sandbox: under `uid`, and
99
+ * `sandbox_check` answers 1 (in a sandbox), 0 for writing the allow-canary and 1 for writing the deny-canary — only the
100
+ * run's own profile gives that pair (an allow-default neighbor, or one allowing the temp dir, is allowed both).
101
+ * `/usr/bin/python3 -I` with ctypes (JXA cannot pass the variadic path on arm64, measured), only when the
102
+ * CommandLineTools exist (else the stub opens an install dialog), with a fixed environment and a 3-second timeout.
103
+ * Null when it cannot answer: the caller then taints the run.
104
+ */
105
+ export declare function sandboxDetect(pids: number[], canary: Canary, python: string | null, uid: number, known?: Record<string, ProcRow>): number[] | null;
106
+ /**
107
+ * @implements A-SPEC-774.61 — the sandbox is empty only after three consecutive passes with none of the run's and none
108
+ * unjudgeable; past the budget without them the run is tainted; otherwise one more pass.
109
+ */
110
+ export declare function sweepVerdict(passes: Array<{
111
+ ours: number;
112
+ unjudgeable: number;
113
+ }>, elapsedMs: number, budgetMs: number): 'empty' | 'again' | 'taint';
114
+ /**
115
+ * @implements A-SPEC-774.61 — enumerate, check and kill in one detector process, pass after pass: every pid of
116
+ * `proc_listallpids` under `uid`, started since `since` and not a zombie, is asked `sandbox_check` (boxed, allow- and
117
+ * deny-canary, as A-SPEC-774.53) and SIGKILLed at once when it is the run's; an error answer counts it unjudgeable.
118
+ * The detector stops after three clean passes or past the budget; each pass is printed as "ours unjudgeable elapsedMs".
119
+ * Same preconditions as sandboxDetect. Null when it cannot answer: the caller then taints the run.
120
+ */
121
+ export declare function sandboxSweep(canary: Canary, python: string | null, uid: number, since: number, budgetMs: number): {
122
+ passes: Array<{
123
+ ours: number;
124
+ unjudgeable: number;
125
+ }>;
126
+ elapsedMs: number;
127
+ } | null;
128
+ /** @implements A-SPEC-774.58 — removes the run temp dir; a link found in its place is removed, never followed. */
129
+ export declare function removeRunTmp(p: string): void;
130
+ /**
131
+ * @implements A-SPEC-774.54 — the run's exec entries whose run exec or watchdog is alive, after the orphans are swept:
132
+ * while one remains its teardown may still write the run's taint.
133
+ */
134
+ export declare function liveExecEntries(main: string, runId: string): string[];
135
+ /**
136
+ * @implements A-SPEC-774.41 — engines and run homes a killed run exec (and its killed watchdog) left: swept by the next
137
+ * run exec or run start for the same main checkout. Returns the entries swept.
138
+ */
139
+ export declare function sweepOrphanExecs(main: string): number;
140
+ export declare function runExec(opts: RunExecOptions, io: Io, deps?: RunExecDeps): Promise<number>;
141
+ export {};