@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
@@ -27,7 +27,7 @@ export declare const REFRESH_SUPERSEDE_POLL_MS = 15000;
27
27
  export declare function lowerOwnPriority(setPriority?: (priority: number) => void): boolean;
28
28
  /**
29
29
  * @implements A-SPEC-719.2 — a superseded worker ends within one poll instead of finishing its phase. Measured
30
- * 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
30
+ * 2026-10-15: nine superseded consumer-workspace workers kept embedding for 2–4 h because the lease was asked only between phases.
31
31
  */
32
32
  export declare function armSupersedeWatch(root: string, generation: string, opts: {
33
33
  intervalMs: number;
@@ -129,7 +129,7 @@ function lowerOwnPriority(setPriority = (p) => os.setPriority(p)) {
129
129
  }
130
130
  /**
131
131
  * @implements A-SPEC-719.2 — a superseded worker ends within one poll instead of finishing its phase. Measured
132
- * 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
132
+ * 2026-10-15: nine superseded consumer-workspace workers kept embedding for 2–4 h because the lease was asked only between phases.
133
133
  */
134
134
  function armSupersedeWatch(root, generation, opts) {
135
135
  // @implements A-SPEC-719.4 — by default only a readable newer lease or a removed workspace ends the worker:
@@ -30,4 +30,9 @@ export declare function buildSessionStartOutput(input: SessionStartInput): Sessi
30
30
  * `upgrade`/`init --force`. Forward-drift + opt-out judgment is the pure `repinDecision`; every
31
31
  * failure returns '' (fail-open — a banner is never a gate).
32
32
  */
33
+ /**
34
+ * @implements A-SPEC-251.5 — one line when a holmes-kit MCP server running from this workspace's wired node install
35
+ * started before that install was upgraded. Fail-open: '' on any failure, never a gate.
36
+ */
37
+ export declare function staleWiredServerLine(cwd: string): string;
33
38
  export declare function driftNudge(cwd: string, installed: string, env: NodeJS.ProcessEnv): string;
@@ -35,8 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.detectInstallMode = detectInstallMode;
37
37
  exports.buildSessionStartOutput = buildSessionStartOutput;
38
+ exports.staleWiredServerLine = staleWiredServerLine;
38
39
  exports.driftNudge = driftNudge;
39
- // @implements A-SPEC-531.2, A-SPEC-734, A-SPEC-476.1
40
+ // @implements A-SPEC-531.2, A-SPEC-734, A-SPEC-476.1, A-SPEC-251.5
40
41
  // The SessionStart banner hook. It emits the intro (+ optional update notice) as additionalContext,
41
42
  // which Claude Code delivers to BOTH the human transcript and the agent context — the "human and
42
43
  // agent" delivery REQ-531 asks for. The update refresh is a DETACHED, fire-and-forget child so the
@@ -86,6 +87,26 @@ function pkgVersion() {
86
87
  * `upgrade`/`init --force`. Forward-drift + opt-out judgment is the pure `repinDecision`; every
87
88
  * failure returns '' (fail-open — a banner is never a gate).
88
89
  */
90
+ /**
91
+ * @implements A-SPEC-251.5 — one line when a holmes-kit MCP server running from this workspace's wired node install
92
+ * started before that install was upgraded. Fail-open: '' on any failure, never a gate.
93
+ */
94
+ function staleWiredServerLine(cwd) {
95
+ try {
96
+ const mcp = JSON.parse(fs.readFileSync(path.join(cwd, '.mcp.json'), 'utf8'));
97
+ const entry = mcp.mcpServers?.['holmes-kit'];
98
+ const bin = entry?.command === 'node' && typeof entry.args?.[0] === 'string' ? entry.args[0] : null;
99
+ if (bin === null || !/[\\/]bin[\\/]holmes-mcp\.js$/.test(bin))
100
+ return '';
101
+ const wiredRoot = path.dirname(path.dirname(path.resolve(cwd, bin)));
102
+ const { listProcessRows, staleMcpServers, readPackageInstall, mcpProcessBannerLine } = require('../cli/mcp-processes');
103
+ const rows = listProcessRows();
104
+ return rows === null ? '' : mcpProcessBannerLine(staleMcpServers(rows, readPackageInstall), wiredRoot);
105
+ }
106
+ catch {
107
+ return '';
108
+ }
109
+ }
89
110
  function driftNudge(cwd, installed, env) {
90
111
  try {
91
112
  const { mcpLaunchVersion } = require('../cli/mcp-version');
@@ -182,6 +203,13 @@ if (require.main === module) {
182
203
  out.hookSpecificOutput.additionalContext += notice;
183
204
  }
184
205
  catch { /* the banner is never a gate */ }
206
+ // @implements A-SPEC-251.5 — the wiring can match while a server from the wired install still runs older code.
207
+ try {
208
+ const line = staleWiredServerLine(process.cwd());
209
+ if (line)
210
+ out.hookSpecificOutput.additionalContext += '\n' + line;
211
+ }
212
+ catch { /* the banner is never a gate */ }
185
213
  // @implements A-SPEC-554.1 — remind the human of the current autonomy posture (surface only, the
186
214
  // headless hook never decides), and clean up an expired/invalid session marker. Fail-open.
187
215
  try {
@@ -2,6 +2,14 @@ import { PendingRequest } from '../governance/approval-queue';
2
2
  /** @implements A-SPEC-769.11 — the stage line prints from 9 s: the 18–29 s range of the 2026-10-15 incident stays visible. */
3
3
  export declare const STOP_TIMING_REPORT_MS = 9000;
4
4
  export declare const STOP_NOTICES: Set<string>;
5
+ /**
6
+ * @implements A-SPEC-734 (round 17) — the changed paths of THIS project, relative to its root, as git names them
7
+ * (`-z`: no quoting, so a name holding `"`, ` -> `, a newline or — with quotepath on — a non-ASCII character is read
8
+ * as itself; each was read as another path and skipped). Limited to the project (`-- .`) and made relative to it:
9
+ * porcelain paths are from the REPOSITORY root, and a monorepo package's ART-1/5/8 returned nothing while a root
10
+ * `src/a.ts` change was read from the package's own file (measured). A rename or copy names its destination.
11
+ */
12
+ export declare function workTreePaths(root: string): string[] | null;
5
13
  import { Spec } from '../spec/spec-parser';
6
14
  import type { TestOutcome } from '../review/test-runner';
7
15
  import { type KnownDefectJudgement } from '../rtm/known-defects';
@@ -48,6 +56,11 @@ export interface StopEvidence {
48
56
  launcher?: string;
49
57
  /** A-SPEC id -> number of real test cases (`it(`/`test(`) found in test files anchored to it. */
50
58
  testCasesByAspec?: Record<string, number>;
59
+ /** @implements A-SPEC-750.2 — A-SPEC id -> the anchored files that counted zero, and why (ART-4's detail). */
60
+ zeroCountCauses?: Record<string, Array<{
61
+ file: string;
62
+ reason: string;
63
+ }>>;
51
64
  /**
52
65
  * @implements A-SPEC-660
53
66
  * `@known-defect` markers found in the workspace's test files, judged against the clock by the
@@ -150,6 +163,16 @@ export interface StopEvidence {
150
163
  * catches it already existed inside `rechainLedger` and ran from the CLI only.
151
164
  */
152
165
  rolledBackLedgers?: string[];
166
+ /**
167
+ * @implements A-SPEC-792.13 — spec-store changes in the index or in new commits that no granted staging act recorded
168
+ * (spec-seam.ts): staging judged by its result, whatever form the shell act took.
169
+ */
170
+ unexplainedSpecChanges?: Array<{
171
+ where: 'index' | 'commit' | 'scan';
172
+ path?: string;
173
+ commit?: string;
174
+ detail?: string;
175
+ }>;
153
176
  /**
154
177
  * @implements A-SPEC-534.4
155
178
  * ART-8 RED-first evidence. `changedAspecs` are the A-SPECs whose source is dirty this turn;
@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.MAX_CONSECUTIVE_BLOCKS = exports.STOP_NOTICES = exports.STOP_TIMING_REPORT_MS = void 0;
37
+ exports.workTreePaths = workTreePaths;
37
38
  exports.collectKnownDefects = collectKnownDefects;
38
39
  exports.collectSemanticCoverage = collectSemanticCoverage;
39
40
  exports.collectAnalysisCurrency = collectAnalysisCurrency;
@@ -65,7 +66,7 @@ exports.collectForbiddenEdgeJudgement = collectForbiddenEdgeJudgement;
65
66
  exports.stopSharedScan = stopSharedScan;
66
67
  exports.scanCodeCycles = scanCodeCycles;
67
68
  exports.writeGuardCount = writeGuardCount;
68
- // @implements A-SPEC-734, A-SPEC-772.1, A-SPEC-770.3, A-SPEC-770.7, A-SPEC-774.21, A-SPEC-778.1, A-SPEC-476.1, A-SPEC-792.1
69
+ // @implements A-SPEC-734, A-SPEC-772.1, A-SPEC-770.3, A-SPEC-770.7, A-SPEC-774.21, A-SPEC-778.1, A-SPEC-476.1, A-SPEC-792.1, A-SPEC-102.10, A-SPEC-102.12, A-SPEC-222.10, A-SPEC-222.12, A-SPEC-222.13
69
70
  // @implements A-SPEC-769.9, A-SPEC-769.10, A-SPEC-769.11
70
71
  const fs = __importStar(require("node:fs"));
71
72
  // @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
@@ -134,7 +135,8 @@ function workTreePaths(root) {
134
135
  // whole-repository status of a 200k-file monorepo cost 20–25× the package's (measured); `underGitPrefix` still folds.
135
136
  const limit = prefix !== '' && /^[\x20-\x7e]+$/.test(prefix) ? ['--', `:(top,icase,literal)${prefix}`] : [];
136
137
  const raw = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-z', '-uall', '--ignore-submodules=all', ...limit], { maxBuffer: bounded_io_1.GIT_MAX_BUFFER,
137
- cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: (0, root_1.cleanSubprocessEnv)(), timeout: bounded_io_1.GIT_TIMEOUT_MS, killSignal: 'SIGKILL',
138
+ // @implements A-SPEC-792.36 — the shared git environment: no fsmonitor hook or other switchable program runs
139
+ cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: (0, bounded_io_1.gitEnv)((0, root_1.cleanSubprocessEnv)()), timeout: bounded_io_1.GIT_TIMEOUT_MS, killSignal: 'SIGKILL',
138
140
  });
139
141
  out = [];
140
142
  const entries = raw.split('\0');
@@ -457,18 +459,23 @@ function runReviewGate(root, env, cwd, sessionId) {
457
459
  if (!mode.id)
458
460
  return cannot('the run has no id');
459
461
  const { listRuns, mainCheckoutOf } = require('../project/run-records');
462
+ // A-SPEC-102.32 — non-strict: a forged pointer finds no run record and an unreadable one throws; both block, named
460
463
  const rec = listRuns(mainCheckoutOf(root)).find((r) => r.run_id === mode.id);
461
464
  if (!rec)
462
465
  return cannot(`no run record for ${mode.id}`);
463
- if (typeof rec.base !== 'string' || rec.base === '')
466
+ // @implements A-SPEC-102.12 — from the task's review base when the run declared one.
467
+ const { reviewBaseOf, reviewPolicyOf } = require('../guardrail/run-stages');
468
+ const reviewBase = reviewBaseOf(rec);
469
+ if (reviewBase === null)
464
470
  return cannot('run record carries no base');
465
471
  const { gateRange, resolveRange } = require('../review/verdicts');
466
- const range = resolveRange(rec.worktree, rec.base, 'HEAD');
472
+ const range = resolveRange(rec.worktree, reviewBase, 'HEAD');
467
473
  if ('error' in range)
468
- return cannot(`the range ${rec.base}..HEAD does not resolve (${range.error})`, rec.base);
474
+ return cannot(`the range ${reviewBase}..HEAD does not resolve (${range.error})`, reviewBase);
469
475
  if (range.head === range.base)
470
476
  return undefined;
471
- const g = gateRange(rec.worktree, range.base, range.head, {});
477
+ // @implements A-SPEC-102.10 — a strict run is judged strictly at Stop too.
478
+ const g = gateRange(rec.worktree, range.base, range.head, { strict: reviewPolicyOf(rec).strict });
472
479
  return g.ok ? undefined : { base: range.base, head: range.head, reasons: g.reasons };
473
480
  }
474
481
  catch (e) {
@@ -663,27 +670,24 @@ function unrecordedApprovals(root) {
663
670
  // a wave of false accusations.
664
671
  const recorded = new Set();
665
672
  const dir = path.join(root, '.ax', 'ledger');
666
- let files;
673
+ if (!fs.existsSync(dir))
674
+ return undefined;
675
+ // @implements A-SPEC-222.12 — N3: the approving acts come from trusted spec-approved rows only (a chainless line in a
676
+ // `junk.jsonl` hid a hand-approved spec); a row that names the id anywhere still records it, as before, so approvals
677
+ // named inside another approval's row (78 legacy ones here) stay recorded
678
+ let rows;
667
679
  try {
668
- files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
680
+ const { TrustedLedgerStore } = require('../governance/recorded-pairs');
681
+ rows = new TrustedLedgerStore(dir).loadAll();
669
682
  }
670
683
  catch {
671
684
  return undefined;
672
685
  }
673
- for (const f of files) {
674
- let text;
675
- try {
676
- text = fs.readFileSync(path.join(dir, f), 'utf8');
677
- }
678
- catch {
686
+ for (const e of rows) {
687
+ if (e.kind !== 'spec-approved')
679
688
  continue;
680
- }
681
- for (const line of text.split('\n')) {
682
- if (!line.includes('"spec-approved"'))
683
- continue;
684
- for (const m of line.matchAll(/\b(?:REQ|H-SPEC|A-SPEC|C-SPEC|T-SPEC)-[0-9.]+/g))
685
- recorded.add(m[0]);
686
- }
689
+ for (const m of JSON.stringify(e).matchAll(/\b(?:REQ|H-SPEC|A-SPEC|C-SPEC|T-SPEC)-[0-9.]+/g))
690
+ recorded.add(m[0]);
687
691
  }
688
692
  return approvedIds.filter((id) => !recorded.has(id));
689
693
  }
@@ -719,15 +723,23 @@ function rolledBackLedgers(root) {
719
723
  .filter((e) => e !== null);
720
724
  const { mainlineIsPrefix } = require('../governance/ledger-rechain');
721
725
  const out = [];
726
+ // @implements A-SPEC-222.12 (M1) — every tracked chain's HEAD blob in one read, shared with the trusted-events port
727
+ // (one git child per commit, not one per replica); a file HEAD does not hold is new, not rolled back
728
+ const { committedLedgerTexts } = require('../governance/recorded-pairs');
729
+ let heads;
730
+ // @implements A-SPEC-222.13 — a HEAD that could not be read is not "nothing committed": every tracked chain is
731
+ // reported (fail-closed), never skipped
732
+ try {
733
+ heads = committedLedgerTexts(root, tracked);
734
+ }
735
+ catch {
736
+ exports.STOP_NOTICES.add('the ledger rollback check (ART-2) could not read HEAD — every tracked chain is reported until it can');
737
+ return tracked;
738
+ }
722
739
  for (const rel of tracked) {
723
- let committed;
724
- // Round 17: `HEAD:./` — `ls-files` names paths from the project, `HEAD:` from the repository root (measured).
725
- try {
726
- committed = git(['show', `HEAD:./${rel}`]);
727
- }
728
- catch {
740
+ const committed = heads.get(rel);
741
+ if (committed === null || committed === undefined)
729
742
  continue;
730
- } // no HEAD, or newly added
731
743
  let working;
732
744
  try {
733
745
  working = readRegularText(path.join(root, rel));
@@ -818,7 +830,7 @@ function evaluateStop(specs, evidence) {
818
830
  // @implements A-SPEC-534.4 — ART-8 evidence rides through to the constitution, which emits a
819
831
  // BLOCKING ART-8 violation only in `strict` mode. `track`/`off` produce none here.
820
832
  const violations = (0, constitution_1.verifyConstitution)({
821
- specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings,
833
+ specs, testCasesByAspec: evidence?.testCasesByAspec, zeroCountCauses: evidence?.zeroCountCauses, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings,
822
834
  redFirstMode: evidence?.redFirstMode, changedAspecs: evidence?.changedAspecs, outcomesByAspec: evidence?.outcomesByAspec,
823
835
  cycles: evidence?.cycles,
824
836
  // @implements A-SPEC-660 — only the expired and unreadable markers are the constitution's business.
@@ -955,6 +967,23 @@ function evaluateStop(specs, evidence) {
955
967
  problems.push(`[ART-2] ${detail}`);
956
968
  structured.push({ article: 'ART-2', detail });
957
969
  }
970
+ // @implements A-SPEC-792.13 — a spec change reached the index or a commit without a person's grant
971
+ // @implements A-SPEC-222.15 (item 5) — a scan finding is its own reason, with no unstage or reset advice: the seam
972
+ // could not judge, so nothing is known to undo (the advice told a retry or a false refusal to move the branch back)
973
+ const seamAll = evidence?.unexplainedSpecChanges ?? [];
974
+ for (const u of seamAll.filter((x) => x.where === 'scan')) {
975
+ const detail = `the spec seam could not judge the spec store: ${u.detail ?? 'the scan could not finish'}`;
976
+ problems.push(`[ART-5] ${detail}`);
977
+ structured.push({ article: 'ART-5', detail });
978
+ }
979
+ const seam = seamAll.filter((x) => x.where !== 'scan');
980
+ if (seam.length > 0) {
981
+ const named = seam.slice(0, 5).map((u) => u.where === 'index' ? `staged ${u.path}` : `commit ${(u.commit ?? '').slice(0, 12)} changes ${u.path}`).join('; ');
982
+ const detail = `spec-store changes entered the index or a commit with no granted staging act (${named}${seam.length > 5 ? `; ${seam.length - 5} more` : ''}) — `
983
+ + 'unstage them (git restore --staged -- <paths>), move a branch back past the commit (git reset --soft <commit>^), or stage them again with the plain git add the gate files for approval_ask';
984
+ problems.push(`[ART-5] ${detail}`);
985
+ structured.push({ article: 'ART-5', detail });
986
+ }
958
987
  if (problems.length === 0)
959
988
  return { block: false, ...(tracked ? { tracked } : {}) };
960
989
  // @implements A-SPEC-134 — the distinct articles feed the constitution-debt state on a cap-yield.
@@ -965,7 +994,8 @@ function evaluateStop(specs, evidence) {
965
994
  .concat(evidence?.anchorStrict && (evidence?.unapprovedChangedAnchors ?? []).length > 0 ? ['ART-1'] : [])
966
995
  .concat(evidence?.reviewGate ? ['ART-7'] : [])
967
996
  .concat((evidence?.unrecordedApprovals ?? []).length > 0 ? ['ART-5'] : [])
968
- .concat((evidence?.rolledBackLedgers ?? []).length > 0 ? ['ART-2'] : []))];
997
+ .concat((evidence?.rolledBackLedgers ?? []).length > 0 ? ['ART-2'] : [])
998
+ .concat((evidence?.unexplainedSpecChanges ?? []).length > 0 ? ['ART-5'] : []))];
969
999
  return {
970
1000
  block: true,
971
1001
  articles,
@@ -1507,6 +1537,7 @@ if (require.main === module) {
1507
1537
  // fail-open); a SUCCESSFUL scan that finds nothing yields `{}` and DOES enforce — all evidence
1508
1538
  // vanishing while approved T-SPECs exist is a genuine violation state, not a hiccup.
1509
1539
  let testCasesByAspec;
1540
+ const zeroCountCauses = {};
1510
1541
  try {
1511
1542
  testCasesByAspec = {};
1512
1543
  const testRoot = stopProjectRoot();
@@ -1521,12 +1552,19 @@ if (require.main === module) {
1521
1552
  // every non-JS suite counts zero and ART-4 reports "no tests" for a project that has them.
1522
1553
  // Round 17: read from the project root, not the process directory (a Stop run from `src/` raised a false
1523
1554
  // ART-4 — measured).
1555
+ let reason = null;
1524
1556
  try {
1525
- n = (0, test_scope_1.countTestCases)(fs.readFileSync(abs, 'utf8'), file);
1557
+ const d = (0, test_scope_1.testCountDetail)(fs.readFileSync(abs, 'utf8'), file);
1558
+ n = d.cases;
1559
+ if (n === 0)
1560
+ reason = (0, test_scope_1.zeroCountReason)(d); // @implements A-SPEC-750.2, A-SPEC-750.4
1526
1561
  }
1527
1562
  catch { /* unreadable file: skip */ }
1528
1563
  for (const id of ids)
1529
1564
  testCasesByAspec[id] = (testCasesByAspec[id] ?? 0) + n;
1565
+ if (reason !== null)
1566
+ for (const id of ids)
1567
+ (zeroCountCauses[id] ??= []).push({ file, reason });
1530
1568
  }
1531
1569
  }
1532
1570
  catch {
@@ -1558,7 +1596,8 @@ if (require.main === module) {
1558
1596
  changedAspecs = changedAnchoredAspecs(stopProjectRoot());
1559
1597
  // @implements A-SPEC-645 — a renumbered A-SPEC keeps its red-first evidence: records are
1560
1598
  // grouped under the display id the entity carries now, per the ledger's rename records.
1561
- const { FileLedgerStore: LedgerForAliases } = require('../governance/ledger-store');
1599
+ // @implements A-SPEC-222.10 — H-C: trusted renames only (a forged one would lend another spec's red evidence)
1600
+ const { TrustedLedgerStore: LedgerForAliases } = require('../governance/recorded-pairs');
1562
1601
  const canonical = (0, display_id_aliases_1.displayIdCanonicalizer)(new LedgerForAliases(path.join(stopProjectRoot(), '.ax', 'ledger')).loadAll());
1563
1602
  outcomesByAspec = (0, test_outcomes_1.groupOutcomesByAspec)((0, test_outcomes_1.readOutcomes)(stopProjectRoot()), head, canonical);
1564
1603
  }
@@ -1676,6 +1715,22 @@ if (require.main === module) {
1676
1715
  const unrecorded = unrecordedApprovals(stopProjectRoot());
1677
1716
  // @implements A-SPEC-455
1678
1717
  const rolledBack = rolledBackLedgers(stopProjectRoot());
1718
+ // @implements A-SPEC-792.13 — the spec seam; a clean one advances to the tips now
1719
+ let unexplainedSpecs = [];
1720
+ try {
1721
+ const seamMod = require('../governance/spec-seam');
1722
+ unexplainedSpecs = seamMod.unexplainedSpecChanges(stopProjectRoot(), specsDir);
1723
+ // advancing is best effort: a seam left behind only re-checks what was already explained
1724
+ if (unexplainedSpecs.length === 0) {
1725
+ try {
1726
+ seamMod.advanceSpecSeam(stopProjectRoot(), specsDir);
1727
+ }
1728
+ catch { /* kept */ }
1729
+ }
1730
+ }
1731
+ catch (e) {
1732
+ unexplainedSpecs = [{ where: 'scan', detail: `the spec seam failed (${String(e.message ?? e).slice(0, 120)})` }];
1733
+ }
1679
1734
  clock.mark('ledgers');
1680
1735
  // @implements A-SPEC-564.2 — the Claude usage enrichment: numbers out of transcript_path into
1681
1736
  // the session-context ledger, once per session. Capability-declared: Codex/AGY pass no
@@ -1789,7 +1844,7 @@ if (require.main === module) {
1789
1844
  pendingRequests = require('../governance/approval-queue').readQueue(stopProjectRoot()).pending;
1790
1845
  }
1791
1846
  catch { /* text only */ }
1792
- let out = evaluateStop(specs, { pendingRequests, testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, ...(unapprovedAnchors ? { unapprovedChangedAnchors: unapprovedAnchors, anchorStrict } : {}), ...(reviewGate ? { reviewGate } : {}), unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}), ...(forbiddenEdges ? { forbiddenEdges } : {}), ...(cycles ? { cycles } : {}) });
1847
+ let out = evaluateStop(specs, { pendingRequests, testCasesByAspec, zeroCountCauses, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, ...(unapprovedAnchors ? { unapprovedChangedAnchors: unapprovedAnchors, anchorStrict } : {}), ...(reviewGate ? { reviewGate } : {}), unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, unexplainedSpecChanges: unexplainedSpecs, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}), ...(forbiddenEdges ? { forbiddenEdges } : {}), ...(cycles ? { cycles } : {}) });
1793
1848
  // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
1794
1849
  // the operator observes RED-first gaps before an owner promotes the posture to strict.
1795
1850
  // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty
@@ -2,7 +2,9 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.supportsFormElicitation = supportsFormElicitation;
4
4
  exports.selectApprovalAdapter = selectApprovalAdapter;
5
- const HOST_GATED_HARNESSES = new Set(['claude', 'codex', 'antigravity']);
5
+ // @implements A-SPEC-792.25 — formGate admits only an attested claude harness (A-SPEC-792.23/24), so codex and
6
+ // antigravity can never reach this choice; listing them only suggested a route that does not exist
7
+ const HOST_GATED_HARNESSES = new Set(['claude']);
6
8
  const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
7
9
  /** A generic or URL-only elicitation declaration cannot receive an MCP form. */
8
10
  function supportsFormElicitation(capabilities) {
@@ -37,6 +37,7 @@ exports.ApprovalContinuationStore = void 0;
37
37
  // @implements A-SPEC-718, A-SPEC-732
38
38
  const crypto = __importStar(require("node:crypto"));
39
39
  const approval_intent_1 = require("./approval-intent");
40
+ const human_channel_1 = require("../governance/human-channel");
40
41
  /**
41
42
  * Memory-only continuations deliberately die with the MCP session. A rejected or malformed
42
43
  * commit never burns a valid pending intent; only an exact, live host-gated commit can be consumed
@@ -82,7 +83,7 @@ class ApprovalContinuationStore {
82
83
  return undefined;
83
84
  this.committed.delete(candidate.id);
84
85
  return {
85
- actor: `host-gated:${committed.harness}`,
86
+ actor: (0, human_channel_1.humanChannelActor)('host-gated', committed.harness), // @implements A-SPEC-792.25
86
87
  token: crypto.randomUUID(),
87
88
  rationale: `host-gated in-session approval for ${committed.kind} ${committed.target}`,
88
89
  };
@@ -97,7 +98,7 @@ class ApprovalContinuationStore {
97
98
  continue;
98
99
  this.committed.delete(intent.id);
99
100
  return {
100
- actor: `host-gated:${intent.harness}`,
101
+ actor: (0, human_channel_1.humanChannelActor)('host-gated', intent.harness), // @implements A-SPEC-792.25
101
102
  token: crypto.randomUUID(),
102
103
  rationale: `host-gated in-session approval for ${intent.kind} ${intent.target}`,
103
104
  };
@@ -1,7 +1,8 @@
1
1
  import { ApprovalPresentationResult } from './approval-intent';
2
+ import { HumanChannelActor } from '../governance/human-channel';
2
3
  export type ApprovalPolicyDecision = {
3
4
  kind: 'approved';
4
- actor: string;
5
+ actor: HumanChannelActor;
5
6
  reason?: string;
6
7
  } | {
7
8
  kind: 'hold';
@@ -1,6 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.resolveApprovalPresentation = resolveApprovalPresentation;
4
+ const human_channel_1 = require("../governance/human-channel");
4
5
  /**
5
6
  * The sole response transition table; timeout is never a synonym for cancel or deny.
6
7
  * A-SPEC-718.1: it is not a synonym for approve either — an unanswered prompt is held in every mode.
@@ -8,7 +9,8 @@ exports.resolveApprovalPresentation = resolveApprovalPresentation;
8
9
  function resolveApprovalPresentation(result, options) {
9
10
  const harness = options.harness.trim() || 'unknown';
10
11
  switch (result.kind) {
11
- case 'approve': return { kind: 'approved', actor: `elicitation:${harness}`, ...(result.reason ? { reason: result.reason } : {}) };
12
+ // @implements A-SPEC-792.25 — minted in one place, from the harness the caller attested
13
+ case 'approve': return { kind: 'approved', actor: (0, human_channel_1.humanChannelActor)('elicitation', harness), ...(result.reason ? { reason: result.reason } : {}) };
12
14
  case 'timeout': return { kind: 'hold', reason: 'approval prompt timed out' };
13
15
  case 'deny': return { kind: 'hold', reason: result.reason ? `denied: ${result.reason}` : 'denied' };
14
16
  case 'question': return { kind: 'hold', reason: `question: ${result.reason}` };
@@ -107,7 +107,7 @@ export declare function createAdoptionHandlers(context: AdoptionContext): {
107
107
  reason: string;
108
108
  findings?: unknown[];
109
109
  }[];
110
- reason?: undefined;
110
+ readonly reason?: undefined;
111
111
  availableClusters?: undefined;
112
112
  }>;
113
113
  /**
@@ -6,8 +6,13 @@ export interface ApprovalAskContext {
6
6
  attestation: () => {
7
7
  attested: boolean;
8
8
  reason?: string;
9
+ harness?: string;
9
10
  };
11
+ /** @implements A-SPEC-792.22 — the one form gate (makeRawHandlers): a refusal reason, or null when a form may be shown. */
12
+ formGate: () => string | null;
10
13
  env: () => NodeJS.ProcessEnv;
14
+ /** @implements A-SPEC-779.7 — this server's instance id, the requester key approval_withdraw checks. */
15
+ serverInstance?: () => string | undefined;
11
16
  }
12
17
  /** Clients whose form waits for the person in every mode measured (claude-code: forms expired unanswered, 2026-10-19). */
13
18
  export declare const FORM_WAITS_FOR_PERSON: ReadonlySet<string>;
@@ -16,4 +21,13 @@ export declare function createApprovalAskHandlers(context: ApprovalAskContext):
16
21
  root?: string;
17
22
  id: string;
18
23
  }): Promise<Record<string, unknown>>;
24
+ /**
25
+ * @implements A-SPEC-779.7 — the session withdraws a request its own MCP server filed: recorded as `withdrawn`, gone
26
+ * from the operator's inbox, never granted. Another session's request, and one filed by a hook or the CLI, is refused.
27
+ */
28
+ approval_withdraw(a: {
29
+ root?: string;
30
+ id: string;
31
+ reason: string;
32
+ }): Promise<Record<string, unknown>>;
19
33
  };
@@ -2,7 +2,7 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.FORM_WAITS_FOR_PERSON = void 0;
4
4
  exports.createApprovalAskHandlers = createApprovalAskHandlers;
5
- // @implements A-SPEC-718.4, A-SPEC-792.1
5
+ // @implements A-SPEC-718.4, A-SPEC-792.1, A-SPEC-779.7, A-SPEC-245.9, A-SPEC-794.31, A-SPEC-794.33,A-SPEC-794.32
6
6
  /**
7
7
  * approval_ask — the person decides a pending request in the session's approval form, so no approval needs a typed
8
8
  * command (owner audit 2026-10-20). Since A-SPEC-779.4 neither the agent's shell nor the session's `!` can run
@@ -15,11 +15,12 @@ exports.createApprovalAskHandlers = createApprovalAskHandlers;
15
15
  const elicit_approval_1 = require("../elicit-approval");
16
16
  const approval_queue_1 = require("../../governance/approval-queue");
17
17
  const approve_1 = require("../../cli/approve");
18
- const screen_safe_1 = require("../../cli/screen-safe");
18
+ const screen_text_1 = require("../../project/screen-text"); // A-SPEC-794.5: from the project layer, as governance does
19
+ const human_channel_1 = require("../../governance/human-channel");
19
20
  /** Clients whose form waits for the person in every mode measured (claude-code: forms expired unanswered, 2026-10-19). */
20
21
  exports.FORM_WAITS_FOR_PERSON = new Set(['claude-code']);
21
22
  /** The one line the form shows for a request's field: the screen-safe flattening the approval screens use. */
22
- const oneLine = (s, max) => (0, screen_safe_1.flattenField)(s, max);
23
+ const oneLine = (s, max) => (0, screen_text_1.flattenField)(s, max);
23
24
  /** interpretElicitResult's reasons: a client's automatic decline is not a person's denial, and a question holds. */
24
25
  const AUTOMATIC_DECLINE = 'the session client declined the approval form';
25
26
  const QUESTION = '질문: ';
@@ -40,8 +41,11 @@ function createApprovalAskHandlers(context) {
40
41
  return refuse('a run\'s own server does not ask; the session that started the run asks the person');
41
42
  }
42
43
  const request = (0, approval_queue_1.grantableRequests)(root).find((p) => p.id === id);
44
+ // @implements A-SPEC-794.31, A-SPEC-794.32 — when no request is found, a development-build one is named in words,
45
+ // and no form is shown; a decidable request is never refused for it (the answer of a lookup that failed)
46
+ // A-SPEC-794.33 — on the exact id only: approval_ask names a request by its whole id (B-2)
43
47
  if (!request)
44
- return { ok: false, id, reason: `no pending request ${oneLine(id, 40)} in the approval inbox or this machine's refusal log` };
48
+ return { ok: false, id, reason: (0, approval_queue_1.devFiledRefusal)((0, approval_queue_1.readQueue)(root), id, true) ?? `no pending request ${oneLine(id, 40)} in the approval inbox or this machine's refusal log` };
45
49
  const client = context.clientName();
46
50
  const attestation = context.attestation();
47
51
  if ((0, elicit_approval_1.elicitationDisabled)(context.env()))
@@ -50,6 +54,10 @@ function createApprovalAskHandlers(context) {
50
54
  return refuse(`this session cannot show an approval form (${attestation.reason ?? 'not launched by a harness'})`);
51
55
  if (!context.elicit)
52
56
  return refuse('this session cannot show an approval form (the client did not advertise forms)');
57
+ // @implements A-SPEC-792.22 — every kind passes the one gate first; ELICITABLE_KINDS skipped it for any client
58
+ const gated = context.formGate();
59
+ if (gated !== null)
60
+ return refuse(gated);
53
61
  if (!elicit_approval_1.ELICITABLE_KINDS.has(request.kind) && !exports.FORM_WAITS_FOR_PERSON.has(client)) {
54
62
  return refuse(`a ${request.kind} approval in the form is not yet measured for ${client} (it might answer forms by itself)`);
55
63
  }
@@ -59,7 +67,7 @@ function createApprovalAskHandlers(context) {
59
67
  target: oneLine(request.target, 400),
60
68
  summary: `${id}${title} — ${oneLine(request.why, 120)}`,
61
69
  });
62
- const actor = `elicitation:${client}`;
70
+ const actor = (0, human_channel_1.humanChannelActor)('elicitation', attestation.harness ?? 'unattested'); // @implements A-SPEC-792.25
63
71
  const base = { ok: true, id, kind: request.kind };
64
72
  if (outcome.kind !== 'answered') {
65
73
  return { ...base, decision: 'undecided', nextAction: 'Nobody answered the form; the request is still pending. Ask again when the person is there.' };
@@ -69,7 +77,9 @@ function createApprovalAskHandlers(context) {
69
77
  const r = (0, approve_1.grantRequest)(root, id, { actor, rationale: reason ?? `approved in the session form (${client})` });
70
78
  if (!r.ok)
71
79
  return { ok: false, id, reason: r.reason };
72
- return { ...base, decision: 'granted', nextAction: 'Retry the refused act once; the grant covers it.' };
80
+ // @implements A-SPEC-245.9 (1b-6) — the result says the grant is single use and when it ends
81
+ const validity = (0, approve_1.grantValidityText)(r.expires);
82
+ return { ...base, decision: 'granted', validity, nextAction: `Retry the refused act once; the grant covers it (${validity}).` };
73
83
  }
74
84
  if (typeof reason === 'string' && reason.startsWith(AUTOMATIC_DECLINE)) {
75
85
  return { ...base, decision: 'undecided', nextAction: `The client declined the form without a person. ${fallback}` };
@@ -86,5 +96,20 @@ function createApprovalAskHandlers(context) {
86
96
  return { ok: false, id, reason: r.reason };
87
97
  return { ...base, decision: 'denied', reason: why, nextAction: 'Do not retry the act; the person denied it.' };
88
98
  },
99
+ /**
100
+ * @implements A-SPEC-779.7 — the session withdraws a request its own MCP server filed: recorded as `withdrawn`, gone
101
+ * from the operator's inbox, never granted. Another session's request, and one filed by a hook or the CLI, is refused.
102
+ */
103
+ async approval_withdraw(a) {
104
+ const root = context.rootOf(a.root);
105
+ const id = typeof a.id === 'string' ? a.id.trim() : '';
106
+ const reason = typeof a.reason === 'string' ? a.reason : '';
107
+ const server = context.serverInstance?.();
108
+ const r = (0, approve_1.withdrawRequest)(root, id, reason, { env: context.env(), cwd: root, ...(server ? { server } : {}) });
109
+ // A-SPEC-794.31, A-SPEC-794.32 — the answer of a withdrawal that found nothing
110
+ if (!r.ok)
111
+ return { ok: false, id, reason: (0, approval_queue_1.devFiledRefusal)((0, approval_queue_1.readQueue)(root), id, true) ?? r.reason }; // A-SPEC-794.33 — exact id (B-2)
112
+ return { ok: true, id, decision: 'withdrawn', nextAction: 'The request is closed; the operator will not see it. Do not retry the act it was filed for.' };
113
+ },
89
114
  };
90
115
  }
@@ -69,7 +69,7 @@ export declare function createEntityIntegrationHandlers(context: {
69
69
  target?: undefined;
70
70
  executable?: undefined;
71
71
  code?: undefined;
72
- reason?: undefined;
72
+ readonly reason?: undefined;
73
73
  } | {
74
74
  ok: boolean;
75
75
  plan: import("../../spec/entity-integration-transaction").EntityIntegrationRecoveryInspection;
@@ -77,7 +77,7 @@ export declare function createEntityIntegrationHandlers(context: {
77
77
  executable: boolean;
78
78
  obligations?: undefined;
79
79
  code?: undefined;
80
- reason?: undefined;
80
+ readonly reason?: undefined;
81
81
  } | {
82
82
  blockers: string[];
83
83
  target?: string | undefined;
@@ -87,7 +87,7 @@ export declare function createEntityIntegrationHandlers(context: {
87
87
  executable: boolean;
88
88
  obligations?: undefined;
89
89
  code?: undefined;
90
- reason?: undefined;
90
+ readonly reason?: undefined;
91
91
  } | {
92
92
  ok: boolean;
93
93
  code: string;