@holmes-lab/holmes-kit 0.39.0 → 0.40.1

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 (325) hide show
  1. package/CHANGELOG.md +578 -6
  2. package/README.md +120 -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 +226 -442
  65. package/dist/holmes/cli/init.js +33 -0
  66. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  67. package/dist/holmes/cli/interactive-prompt.js +98 -16
  68. package/dist/holmes/cli/lock-recover.d.ts +5 -0
  69. package/dist/holmes/cli/lock-recover.js +126 -0
  70. package/dist/holmes/cli/mcp-processes.js +1 -1
  71. package/dist/holmes/cli/release-docs.js +1 -1
  72. package/dist/holmes/cli/run-exec.d.ts +141 -0
  73. package/dist/holmes/cli/run-exec.js +1435 -0
  74. package/dist/holmes/cli/run-provision.d.ts +3 -1
  75. package/dist/holmes/cli/run-provision.js +255 -44
  76. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  77. package/dist/holmes/cli/run-wiring.js +270 -0
  78. package/dist/holmes/cli/run.d.ts +21 -0
  79. package/dist/holmes/cli/run.js +341 -92
  80. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  81. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  82. package/dist/holmes/cli/screen-safe.js +18 -756
  83. package/dist/holmes/config/config.d.ts +19 -0
  84. package/dist/holmes/config/config.js +18 -3
  85. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  86. package/dist/holmes/cpg/import-resolver.js +1 -1
  87. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  88. package/dist/holmes/governance/approval-decisions.js +29 -0
  89. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  90. package/dist/holmes/governance/approval-grants.js +612 -33
  91. package/dist/holmes/governance/approval-queue.d.ts +26 -0
  92. package/dist/holmes/governance/approval-queue.js +109 -11
  93. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  94. package/dist/holmes/governance/approval-spend.js +191 -0
  95. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  96. package/dist/holmes/governance/autonomous-shell.js +332 -0
  97. package/dist/holmes/governance/autonomy.d.ts +12 -0
  98. package/dist/holmes/governance/autonomy.js +51 -15
  99. package/dist/holmes/governance/constitution.d.ts +5 -0
  100. package/dist/holmes/governance/constitution.js +32 -12
  101. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  102. package/dist/holmes/governance/full-autonomy.js +103 -7
  103. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  104. package/dist/holmes/governance/harness-catalog.js +348 -0
  105. package/dist/holmes/governance/human-channel.d.ts +38 -0
  106. package/dist/holmes/governance/human-channel.js +49 -0
  107. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  108. package/dist/holmes/governance/install-manifest.js +160 -0
  109. package/dist/holmes/governance/ledger-rechain.js +2 -0
  110. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  111. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  112. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  113. package/dist/holmes/governance/ledger-store.js +186 -8
  114. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  115. package/dist/holmes/governance/provenance-chain.js +19 -4
  116. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  117. package/dist/holmes/governance/provenance-ledger.js +53 -18
  118. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  119. package/dist/holmes/governance/push-gate-runner.js +50 -9
  120. package/dist/holmes/governance/push-gate.d.ts +13 -2
  121. package/dist/holmes/governance/push-gate.js +106 -14
  122. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  123. package/dist/holmes/governance/recorded-pairs.js +522 -0
  124. package/dist/holmes/governance/replica-id.d.ts +1 -1
  125. package/dist/holmes/governance/replica-id.js +1 -1
  126. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  127. package/dist/holmes/governance/spec-seam.js +587 -0
  128. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  129. package/dist/holmes/governance/spend-kinds.js +18 -0
  130. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  131. package/dist/holmes/guardrail/advisory-line.js +718 -0
  132. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  133. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  134. package/dist/holmes/guardrail/impact-gate.d.ts +7 -0
  135. package/dist/holmes/guardrail/impact-gate.js +33 -6
  136. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  137. package/dist/holmes/guardrail/line-continuation.js +39 -0
  138. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  139. package/dist/holmes/guardrail/operator-person.js +57 -11
  140. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  141. package/dist/holmes/guardrail/refusal-codes.js +64 -10
  142. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  143. package/dist/holmes/guardrail/risk-classifier.js +228 -16
  144. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  145. package/dist/holmes/guardrail/risk-gate.js +7 -34
  146. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  147. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  148. package/dist/holmes/guardrail/run-refusals.js +24 -8
  149. package/dist/holmes/guardrail/run-stages.d.ts +5 -0
  150. package/dist/holmes/guardrail/run-stages.js +25 -5
  151. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  152. package/dist/holmes/guardrail/shell-words.js +24 -3
  153. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  154. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  155. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  156. package/dist/holmes/guardrail/write-target.js +26 -5
  157. package/dist/holmes/hooks/pre-tool-use.d.ts +116 -1
  158. package/dist/holmes/hooks/pre-tool-use.js +1176 -170
  159. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  160. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  161. package/dist/holmes/hooks/session-start.js +17 -1
  162. package/dist/holmes/hooks/stop.d.ts +23 -0
  163. package/dist/holmes/hooks/stop.js +86 -33
  164. package/dist/holmes/mcp/approval-adapters.js +3 -1
  165. package/dist/holmes/mcp/approval-commit.js +3 -2
  166. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  167. package/dist/holmes/mcp/approval-policy.js +3 -1
  168. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  169. package/dist/holmes/mcp/handlers/approval-ask.d.ts +3 -0
  170. package/dist/holmes/mcp/handlers/approval-ask.js +18 -7
  171. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  172. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  173. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  174. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  175. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  176. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  177. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  178. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  179. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  180. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  181. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  182. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  183. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  184. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  185. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  186. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  187. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  188. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  189. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  190. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  191. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  192. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  193. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  194. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  195. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  196. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  197. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  198. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  199. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  200. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  201. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  202. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  203. package/dist/holmes/mcp/handlers/test-execution.d.ts +471 -4
  204. package/dist/holmes/mcp/handlers/test-execution.js +199 -21
  205. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  206. package/dist/holmes/mcp/handlers.d.ts +557 -82
  207. package/dist/holmes/mcp/handlers.js +74 -23
  208. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  209. package/dist/holmes/mcp/harness-attestation.js +325 -53
  210. package/dist/holmes/mcp/maintenance-analyze.d.ts +6 -1
  211. package/dist/holmes/mcp/maintenance-analyze.js +13 -11
  212. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  213. package/dist/holmes/mcp/maintenance-evidence.js +35 -3
  214. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  215. package/dist/holmes/mcp/server-staleness.js +1 -1
  216. package/dist/holmes/mcp/server.js +9 -8
  217. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  218. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  219. package/dist/holmes/mcp/tool-schemas.js +42 -9
  220. package/dist/holmes/project/act-root.d.ts +19 -0
  221. package/dist/holmes/project/act-root.js +100 -0
  222. package/dist/holmes/project/baseline.d.ts +15 -2
  223. package/dist/holmes/project/baseline.js +14 -8
  224. package/dist/holmes/project/bounded-group.d.ts +47 -0
  225. package/dist/holmes/project/bounded-group.js +140 -0
  226. package/dist/holmes/project/bounded-io.d.ts +51 -2
  227. package/dist/holmes/project/bounded-io.js +140 -6
  228. package/dist/holmes/project/change-source.d.ts +4 -0
  229. package/dist/holmes/project/change-source.js +14 -6
  230. package/dist/holmes/project/instance-id.d.ts +10 -0
  231. package/dist/holmes/project/instance-id.js +233 -0
  232. package/dist/holmes/project/machine-identity.d.ts +25 -0
  233. package/dist/holmes/project/machine-identity.js +133 -0
  234. package/dist/holmes/project/owned-lock.d.ts +84 -0
  235. package/dist/holmes/project/owned-lock.js +263 -0
  236. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  237. package/dist/holmes/project/plain-lock-fs.js +126 -0
  238. package/dist/holmes/project/request-lock.d.ts +85 -0
  239. package/dist/holmes/project/request-lock.js +459 -0
  240. package/dist/holmes/project/root.d.ts +12 -4
  241. package/dist/holmes/project/root.js +29 -8
  242. package/dist/holmes/project/run-records.d.ts +19 -0
  243. package/dist/holmes/project/run-records.js +94 -12
  244. package/dist/holmes/project/screen-text.d.ts +94 -0
  245. package/dist/holmes/project/screen-text.js +763 -0
  246. package/dist/holmes/project/spend-lock.d.ts +82 -0
  247. package/dist/holmes/project/spend-lock.js +413 -0
  248. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  249. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  250. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  251. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  252. package/dist/holmes/review/confidence-calibration.js +1 -1
  253. package/dist/holmes/review/content-verify.js +1 -1
  254. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  255. package/dist/holmes/review/evidence-mode.js +33 -0
  256. package/dist/holmes/review/head-worktree.d.ts +55 -0
  257. package/dist/holmes/review/head-worktree.js +329 -0
  258. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  259. package/dist/holmes/review/hop-ablation.js +5 -5
  260. package/dist/holmes/review/mrp.js +13 -3
  261. package/dist/holmes/review/point-in-time-replay.js +12 -3
  262. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  263. package/dist/holmes/review/rank-diagnosis.js +1 -1
  264. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  265. package/dist/holmes/review/replay-corpus.js +25 -9
  266. package/dist/holmes/review/requirement-triage.js +2 -2
  267. package/dist/holmes/review/run-provenance.d.ts +45 -0
  268. package/dist/holmes/review/run-provenance.js +314 -0
  269. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  270. package/dist/holmes/review/semantic-arm.js +3 -3
  271. package/dist/holmes/review/test-evidence.d.ts +174 -0
  272. package/dist/holmes/review/test-evidence.js +330 -2
  273. package/dist/holmes/review/test-outcomes.js +3 -1
  274. package/dist/holmes/review/test-reports.d.ts +94 -0
  275. package/dist/holmes/review/test-reports.js +382 -0
  276. package/dist/holmes/review/test-runner.d.ts +180 -58
  277. package/dist/holmes/review/test-runner.js +560 -324
  278. package/dist/holmes/review/test-selection-breadth.js +2 -2
  279. package/dist/holmes/review/test-units.d.ts +159 -0
  280. package/dist/holmes/review/test-units.js +814 -0
  281. package/dist/holmes/review/verdicts.d.ts +105 -8
  282. package/dist/holmes/review/verdicts.js +640 -36
  283. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  284. package/dist/holmes/rtm/anchor-census.js +151 -0
  285. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  286. package/dist/holmes/rtm/anchor-ids.js +45 -2
  287. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  288. package/dist/holmes/rtm/comment-ranges.js +104 -0
  289. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  290. package/dist/holmes/rtm/counted-tests.js +63 -0
  291. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  292. package/dist/holmes/rtm/known-defects.js +1 -1
  293. package/dist/holmes/rtm/localize.js +1 -1
  294. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  295. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  296. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  297. package/dist/holmes/rtm/test-scope.js +166 -5
  298. package/dist/holmes/rtm/trace-gaps.js +1 -1
  299. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  300. package/dist/holmes/runtime/dispatch.js +12 -1
  301. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  302. package/dist/holmes/semantic/cloud-usage.js +1 -1
  303. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  304. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  305. package/dist/holmes/spec/approval-blockers.js +1 -1
  306. package/dist/holmes/spec/entity-store.d.ts +6 -1
  307. package/dist/holmes/spec/entity-store.js +16 -2
  308. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  309. package/dist/holmes/spec/entity-transaction.js +87 -170
  310. package/dist/holmes/spec/spec-store.d.ts +12 -6
  311. package/dist/holmes/spec/spec-store.js +4 -2
  312. package/dist/holmes/spec/spec-types.js +1 -1
  313. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  314. package/dist/holmes/spec/succession-guard.js +187 -0
  315. package/dist/holmes/spec/succession.d.ts +70 -0
  316. package/dist/holmes/spec/succession.js +171 -0
  317. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  318. package/docs/install-guide.md +9 -3
  319. package/docs/language-support.md +78 -0
  320. package/package.json +4 -3
  321. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  322. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  323. package/playbooks/publish/PLAYBOOK.md +47 -34
  324. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  325. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -4,24 +4,30 @@ import { PendingRequest } from '../governance/approval-queue';
4
4
  *
5
5
  * REQ-262 measured the harm: a human retyping `--grant req-f5bae240c` into another window truncated
6
6
  * the id and the decision died. Git's short hashes are the lesson — people type the least the screen
7
- * already shows. Three grammars, non-overlapping by construction:
7
+ * already shows. Two grammars, non-overlapping by construction:
8
8
  *
9
- * - a bare number is the 1-BASED INDEX of the printed list (`[1] …`),
10
9
  * - an exact id is itself,
11
- * - anything else is a PREFIX, and it must be unique.
10
+ * - anything else is a PREFIX, and it must be unique among every id the queue has seen.
12
11
  *
13
- * The number and the prefix cannot collide: queue ids are `req-<12hex>` (approvalRequestId), so no
14
- * id can start with a digit. A numeric miss is therefore NOT retried as a prefix — that fallback
15
- * would manufacture the very ambiguity this grammar exists to avoid.
12
+ * A bare number was the 1-BASED INDEX of the printed list until A-SPEC-794.33: it is refused now,
13
+ * because a number names whatever row holds it when the command runs, and the agent can move rows.
14
+ * Queue ids are `req-<12hex>` (approvalRequestId), so no id starts with a digit and a number is
15
+ * never retried as a prefix.
16
16
  *
17
17
  * An ambiguous prefix is REFUSED BY NAME (every candidate listed): on a decision surface "probably
18
18
  * this one" is not a decision (REQ-262 Constraints). PURE — no I/O, no clock.
19
19
  */
20
+ /** @implements A-SPEC-794.34 — why a reference resolved to nothing; callers read this, never the reason's words. */
21
+ export type RefMiss = 'empty' | 'number' | 'short' | 'none' | 'ambiguous';
20
22
  export type RefResolution = {
21
23
  ok: true;
22
24
  entry: PendingRequest;
23
25
  } | {
24
26
  ok: false;
25
27
  reason: string;
28
+ kind: RefMiss;
26
29
  };
27
- export declare function resolveRequestRef(pending: PendingRequest[], ref: string): RefResolution;
30
+ export declare function resolveRequestRef(pending: PendingRequest[], ref: string, opts?: {
31
+ listed?: PendingRequest[];
32
+ known?: readonly string[];
33
+ }): RefResolution;
@@ -2,32 +2,52 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.resolveRequestRef = resolveRequestRef;
4
4
  const screen_safe_1 = require("./screen-safe");
5
- function resolveRequestRef(pending, ref) {
5
+ /** @implements A-SPEC-794.34 — a prefix that is not an exact id names `req-` and four hex digits at least (A-M2). */
6
+ const MIN_PREFIX = 8;
7
+ function resolveRequestRef(pending, ref, opts) {
6
8
  const r = ref.trim();
7
9
  if (r === '')
8
- return { ok: false, reason: 'the reference is empty — give a list number or an id prefix' };
9
- if (pending.length === 0)
10
- return { ok: false, reason: 'no requests awaiting approval' };
10
+ return { ok: false, kind: 'empty', reason: 'the reference is empty — give the id shown under the request' };
11
+ // @implements A-SPEC-794.33 — a list number is refused (A-H1): it names whatever row holds it when the command runs.
12
+ // Read [1] A, [2] B; C is filed; A is closed by the agent's own shell — `--grant 2` granted C, which no one read. No
13
+ // order fixes that. The refusal names the row at that number now, subject first, so the id is copied after reading.
11
14
  if (/^\d+$/.test(r)) {
12
- const n = Number(r);
13
- if (n < 1 || n > pending.length) {
14
- return { ok: false, reason: `number ${(0, screen_safe_1.rowField)(r, 20)} is out of the list — the valid range is 1..${pending.length}` };
15
- }
16
- return { ok: true, entry: pending[n - 1] };
15
+ const at = opts?.listed?.[Number(r) - 1];
16
+ return {
17
+ ok: false,
18
+ kind: 'number',
19
+ // two rows: a refusal keeps the 80-column screen rule (approve-corpus)
20
+ reason: ['a list number is not accepted — it names whatever row holds it when the',
21
+ ' command runs; give the id shown under the request (approve --list)',
22
+ ...(at ? [` [${(0, screen_safe_1.rowField)(r, 6)}] is now ${(0, screen_safe_1.rowField)(at.kind, 20)} ${(0, screen_safe_1.rowField)(at.target, 40)}`, ` id: ${(0, screen_safe_1.rowField)(at.id, 40)}`] : [])].join('\n'),
23
+ };
17
24
  }
18
25
  // Exact BEFORE prefix: when one id is a prefix of another, the exact spelling is not ambiguous —
19
26
  // it is the most precise thing the human could have typed.
20
27
  const exact = pending.find((p) => p.id === r);
21
28
  if (exact)
22
29
  return { ok: true, entry: exact };
30
+ // @implements A-SPEC-794.34 — `r` or `req-` named whichever request happened to be alone (A-M2)
31
+ if (r.length < MIN_PREFIX)
32
+ return { ok: false, kind: 'short', reason: `reference '${(0, screen_safe_1.rowField)(r, 20)}' is too short — give eight or more characters of the id` };
33
+ if (pending.length === 0)
34
+ return { ok: false, kind: 'none', reason: 'no requests awaiting approval' };
23
35
  const matches = pending.filter((p) => p.id.startsWith(r));
36
+ // @implements A-SPEC-794.33 — a prefix is unique among every id the queue has seen, not only the open ones: a prefix the
37
+ // operator typed for a request that has since closed must not slide onto a newer request that shares it
38
+ const others = [...new Set(opts?.known ?? [])].filter((id) => id.startsWith(r) && !matches.some((m) => m.id === id));
39
+ if (matches.length === 1 && others.length > 0) {
40
+ return { ok: false, kind: 'ambiguous', reason: [`reference '${(0, screen_safe_1.rowField)(r, 30)}' matches ${1 + others.length} requests, decided or filed elsewhere included — give the full id:`,
41
+ ...[matches[0].id, ...others].map((id) => ` ${(0, screen_safe_1.rowField)(id, 60)}`)].join('\n') };
42
+ }
24
43
  if (matches.length === 1)
25
44
  return { ok: true, entry: matches[0] };
26
45
  if (matches.length === 0) {
27
- return { ok: false, reason: `no pending request matches reference '${(0, screen_safe_1.rowField)(r, 60)}' — check a list number or an id prefix` };
46
+ return { ok: false, kind: 'none', reason: `no pending request matches reference '${(0, screen_safe_1.rowField)(r, 60)}' — check the id with approve --list` };
28
47
  }
29
48
  return {
30
49
  ok: false,
50
+ kind: 'ambiguous',
31
51
  // The ids are AGENT-CHOSEN text (round-2): this refusal is printed on the operator's terminal.
32
52
  // Round-5: the candidates rode on the refusal's own line, so enough of them (or one forged wide
33
53
  // id) wrapped it past a row and pushed the question off the top of the screen. The refusal keeps
@@ -13,15 +13,39 @@ export interface StatusContext {
13
13
  run?: string;
14
14
  covers?: string[];
15
15
  };
16
- /** Nonces that still have a grant file — a granted decision is LIVE only while its file exists. */
16
+ /** @implements A-SPEC-794.55, A-SPEC-794.59 — the full autonomy profile covering this workspace: its scope and flags. */
17
+ full?: {
18
+ scope: string;
19
+ flags: string;
20
+ };
21
+ /**
22
+ * Granted request ids whose act a grant covers now — A-SPEC-794.35: `requestGrantState` (what `resolveApproval` says),
23
+ * not the files' nonces.
24
+ */
17
25
  liveGrants: ReadonlySet<string>;
26
+ /** @implements A-SPEC-794.35 — granted request ids whose grant an act holds claimed now. */
27
+ claimedGrants?: ReadonlySet<string>;
28
+ /** @implements A-SPEC-794.35 — the covering grant, for a request covered by a grant other than its own. */
29
+ coveredBy?: ReadonlyMap<string, string>;
30
+ /** @implements A-SPEC-794.37 — granted request ids whose grant only a dead process's claim still holds. */
31
+ staleClaims?: ReadonlySet<string>;
32
+ /** @implements A-SPEC-794.35, A-SPEC-794.37 — grant files that are no request's own exact grant, with what they hold. */
33
+ otherGrantFiles?: ReadonlyArray<{
34
+ name: string;
35
+ covers: boolean;
36
+ scope?: string;
37
+ }>;
18
38
  }
19
39
  /** What the screen needs from disk: identity (status only, never initializing), delegation, live grant files. */
20
- export declare function statusContext(root: string, now?: string): StatusContext;
40
+ export declare function statusContext(root: string, now?: string, home?: string): StatusContext;
21
41
  /**
22
42
  * The whole picture, template-owned: every agent-controlled field goes through the same screen-safe
23
43
  * cells the list uses (A-SPEC-262.1 — a target must never own a line).
24
44
  */
25
45
  export declare function renderStatus(state: QueueState, ctx: StatusContext, opts?: {
26
46
  recent?: number;
47
+ view?: {
48
+ staleHours: number;
49
+ showAll: boolean;
50
+ };
27
51
  }): string;
@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.statusContext = statusContext;
37
37
  exports.renderStatus = renderStatus;
38
- // @implements A-SPEC-650, A-SPEC-779.2
38
+ // @implements A-SPEC-794.59, A-SPEC-794.58, A-SPEC-794.57, A-SPEC-794.55, A-SPEC-650, A-SPEC-779.2, A-SPEC-245.17, A-SPEC-794.32, A-SPEC-794.33, A-SPEC-794.35, A-SPEC-794.37, A-SPEC-794.41, A-SPEC-794.42
39
39
  //
40
40
  // The DECISION PICTURE (GOAL §3-A) on the operator's existing terminal surface, chosen by the owner
41
41
  // 2026-09-14 over a browser page or harness-only dialogs. Measured on the shipped dist before this
@@ -45,14 +45,17 @@ exports.renderStatus = renderStatus;
45
45
  // still go through grantRequest/denyRequest/holdRequest/revokeGrant, and no pinned line of the list,
46
46
  // the interactive loop or the key surface changes.
47
47
  const fs = __importStar(require("node:fs"));
48
+ const os = __importStar(require("node:os"));
48
49
  const path = __importStar(require("node:path"));
50
+ const approval_queue_1 = require("../governance/approval-queue");
49
51
  const approval_grants_1 = require("../governance/approval-grants");
50
52
  const workspace_identity_1 = require("../project/workspace-identity");
51
53
  const autonomy_1 = require("../governance/autonomy");
54
+ const full_autonomy_1 = require("../governance/full-autonomy");
52
55
  const approve_1 = require("./approve");
53
56
  const screen_safe_1 = require("./screen-safe");
54
57
  /** What the screen needs from disk: identity (status only, never initializing), delegation, live grant files. */
55
- function statusContext(root, now = new Date().toISOString()) {
58
+ function statusContext(root, now = new Date().toISOString(), home) {
56
59
  let workspace = { state: 'legacy' };
57
60
  try {
58
61
  const id = (0, workspace_identity_1.workspaceIdentity)(root, 'status');
@@ -86,35 +89,78 @@ function statusContext(root, now = new Date().toISOString()) {
86
89
  catch {
87
90
  delegation = { mode: 'off' };
88
91
  }
92
+ // @implements A-SPEC-794.35 — one judgement: a granted request is live when `resolveApproval` would authorise its act now,
93
+ // claimed when an act holds its grant. @implements A-SPEC-792.2 — a re-grant's `<id>.r<n>` is the request's own grant.
89
94
  const liveGrants = new Set();
90
- // @implements A-SPEC-792.2 — a re-grant's nonce is `<id>.r<n>`; it is live for request `<id>`.
95
+ const claimedGrants = new Set();
96
+ const staleClaims = new Set();
97
+ const coveredBy = new Map();
98
+ let subjects;
99
+ let granted = [];
91
100
  try {
92
- for (const g of (0, approval_grants_1.readGrants)(root).grants)
93
- if (typeof g.nonce === 'string')
94
- liveGrants.add(g.nonce.replace(/\.r\d+$/, ''));
101
+ const q = (0, approval_queue_1.readQueue)(root, { includeAllKinds: true });
102
+ subjects = q.subjects;
103
+ granted = Object.entries(q.decisions).filter(([, d]) => d.event === 'granted').map(([id]) => id);
104
+ for (const id of granted) {
105
+ const s = (0, approval_grants_1.requestGrantState)(root, id, q.subjects?.[id], now);
106
+ if (s.state === 'covers') {
107
+ liveGrants.add(id);
108
+ if (s.grant !== `${id}.json`)
109
+ coveredBy.set(id, s.grant.replace(/\.json$/, ''));
110
+ }
111
+ else if (s.state === 'claimed')
112
+ claimedGrants.add(id);
113
+ else if (s.staleClaim)
114
+ staleClaims.add(id);
115
+ }
116
+ }
117
+ catch { /* an unreadable queue lists no grant */ }
118
+ // @implements A-SPEC-794.37 — every file but a granted request's own exact grant is shown, with what it holds (A-M2, A-M3)
119
+ const otherGrantFiles = (0, approval_grants_1.grantFileFacts)(root, now).filter((f) => {
120
+ const id = f.file.slice(0, -'.json'.length);
121
+ const act = subjects?.[id];
122
+ return !(granted.includes(id) && act && f.exact && f.kind === act.kind && f.pattern === act.target);
123
+ }).map((f) => ({ name: f.file.slice(0, -'.json'.length), covers: f.covers, scope: f.kind === '' ? '(no readable scope)' : `${f.kind} ${f.pattern}` }));
124
+ let full;
125
+ try {
126
+ const p = (0, full_autonomy_1.readFullProfile)(home ?? os.homedir(), root);
127
+ if (p.active) {
128
+ const onOff = (b) => (b ? 'on' : 'off');
129
+ full = { scope: p.entry.scope, flags: `push ${onOff(p.entry.flags.push)}, publish ${onOff(p.entry.flags.publish)}, architecture ${onOff(p.entry.flags.architecture)}` };
130
+ }
131
+ }
132
+ catch {
133
+ full = undefined;
95
134
  }
96
- catch { /* no grants dir */ }
97
- return { now, workspace, delegation, liveGrants };
135
+ return { now, workspace, delegation, ...(full !== undefined ? { full } : {}), liveGrants, claimedGrants, staleClaims, coveredBy, otherGrantFiles };
98
136
  }
99
137
  const short = (s, n) => (typeof s === 'string' && s !== '' ? (0, screen_safe_1.rowField)(s.slice(0, n), n) : '');
100
138
  const digest12 = (subject) => (typeof subject === 'string' && /^sha256:[0-9a-f]{64}$/.test(subject) ? subject.slice(7, 19) : 'none');
101
139
  function askedBy(p) {
102
140
  if (p.execution)
103
141
  return `run ${short(p.execution.runId, 8)} \u00b7 replica ${short(p.execution.replicaId, 8)} \u00b7 workspace ${short(p.execution.workspaceId, 8)}`;
142
+ // @implements A-SPEC-794.41 \u2014 the filing server is on the row (D3)
143
+ if (p.requesterServer)
144
+ return `MCP server ${(0, screen_safe_1.rowField)(p.requesterServer, 40)}`; // A-SPEC-794.42 — its start time tells two servers apart
104
145
  return `no run recorded${p.replica && p.replica !== 'unknown' ? ` (replica ${(0, screen_safe_1.rowField)(p.replica, 24)})` : ''}`;
105
146
  }
106
147
  /** The outcome of a granted decision, judged from the fold and the live grant files. Pure. */
107
148
  function grantedOutcome(id, d, ctx) {
108
- if (d.consumedTs)
109
- return `consumed ${(0, screen_safe_1.rowField)(d.consumedTs, 28)}`;
110
- const exp = d.expires ? Date.parse(d.expires) : NaN;
111
- const nowMs = Date.parse(ctx.now);
112
- const expired = Number.isFinite(exp) && Number.isFinite(nowMs) && nowMs > exp;
113
- if (ctx.liveGrants.has(id) && !expired)
114
- return `live until ${(0, screen_safe_1.rowField)(d.expires ?? '(no expiry)', 28)}`;
115
- if (expired)
149
+ // @implements A-SPEC-794.33, A-SPEC-245.18 (5c), A-SPEC-794.37 — the one order: `grantedStateOf`
150
+ const state = (0, approval_grants_1.grantedStateOf)({ covers: ctx.liveGrants.has(id), claimed: ctx.claimedGrants?.has(id) ?? false, ...(d.consumedTs ? { consumedTs: d.consumedTs } : {}), ...(d.expires !== undefined ? { expires: d.expires } : {}) }, Date.parse(ctx.now));
151
+ // @implements A-SPEC-792.20 — a grant without a time limit is single use; its sentinel is never shown as a date.
152
+ // @implements A-SPEC-245.17 (item 2) — a timed grant is single use too (A-SPEC-245.9 item 8): the use count and the
153
+ // expiry, never a bare window; this supersedes A-SPEC-792.20's `live until <time>` for a timed grant.
154
+ const by = ctx.coveredBy?.get(id);
155
+ if (state === 'live')
156
+ return `${d.expires === approval_grants_1.GRANT_NO_EXPIRY || d.expires === undefined ? 'live (single use)' : `live (single use, until ${(0, screen_safe_1.rowField)(d.expires, 28)})`}${by ? ` · by grant ${(0, screen_safe_1.rowField)(by, 24)}` : ''}`;
157
+ if (state === 'claimed')
158
+ return 'claimed — an act holds this grant now';
159
+ if (state === 'consumed')
160
+ return `consumed ${(0, screen_safe_1.rowField)(d.consumedTs ?? '', 28)}`;
161
+ if (state === 'expired')
116
162
  return `expired ${(0, screen_safe_1.rowField)(d.expires ?? '', 28)}`;
117
- return 'spent (no consumption record)';
163
+ return ctx.staleClaims?.has(id) ? 'unusable — a process that ended left its claim; holmes-kit doctor names it' : 'unusable — no grant covers this act now';
118
164
  }
119
165
  /**
120
166
  * The whole picture, template-owned: every agent-controlled field goes through the same screen-safe
@@ -135,8 +181,20 @@ function renderStatus(state, ctx, opts) {
135
181
  // @implements A-SPEC-771 \u2014 the run delegation names its run, expiry and covered rules; end early with revoke-delegation.
136
182
  else if (ctx.delegation.mode === 'run')
137
183
  lines.push(`\u25c6 delegation: run ${(0, screen_safe_1.rowField)(ctx.delegation.run ?? '?', 24)} until ${(0, screen_safe_1.rowField)(ctx.delegation.until ?? '?', 28)} \u2014 covers ${(ctx.delegation.covers ?? []).join(', ')} \u2014 end early: holmes-kit autonomy revoke-delegation`);
184
+ // @implements A-SPEC-794.35 \u2014 no unconditional "a person decides": a grant file is not proof a person made it (A-M4)
185
+ // A-SPEC-794.57 \u2014 under a full profile the profile decides seals in its scope, so OFF does not mean each waits
186
+ else if (ctx.full !== undefined)
187
+ lines.push('\u25c6 delegation: autonomous spec approval OFF \u2014 the full profile below decides spec seals in its scope');
138
188
  else
139
- lines.push('\u25c6 delegation: autonomous spec approval OFF \u2014 every spec approval is human');
189
+ lines.push('\u25c6 delegation: autonomous spec approval OFF \u2014 no spec approval is self-driven; each waits for a grant');
190
+ // A-SPEC-794.58 \u2014 the row's screen-safe field (A-SPEC-262.1 \u00a713), with its em dashes written as hyphens so they read as text
191
+ // A-SPEC-794.59 \u2014 the meaning first, so a long scope cuts nothing of it; a scope of plain path characters prints as it
192
+ // is (rowField doubles a backslash), anything else goes through the screen-safe field
193
+ if (ctx.full !== undefined) {
194
+ lines.push(`\u25c6 full autonomy: ON - ${autonomy_1.FULL_PROFILE_MEANING.replace(/\u2014/g, '-')}`);
195
+ const scope = /^[A-Za-z0-9 _.,:~@+=\\/-]+$/.test(ctx.full.scope) ? ctx.full.scope : (0, screen_safe_1.rowField)(ctx.full.scope, 400);
196
+ lines.push(` scope: ${scope}; ${ctx.full.flags}`);
197
+ }
140
198
  lines.push('');
141
199
  if (state.pending.length === 0)
142
200
  lines.push('No requests awaiting approval.');
@@ -155,6 +213,15 @@ function renderStatus(state, ctx, opts) {
155
213
  lines.push(` question: ${(0, screen_safe_1.rowField)(p.question ?? '(no question)', screen_safe_1.ROW_COLS)}`);
156
214
  lines.push(` id: ${(0, screen_safe_1.rowField)(p.id, 40)}`);
157
215
  });
216
+ // @implements A-SPEC-794.33 — the status folds as --list does, and says how many it folded (A-H2)
217
+ if (opts?.view && state.expired.length > 0) {
218
+ lines.push('');
219
+ if (!opts.view.showAll)
220
+ lines.push(`⏳ ${state.expired.length} folded as idle (no activity for over ${opts.view.staleHours}h, still pending) — show with --all`); // A-SPEC-794.41 (D10)
221
+ else
222
+ for (const p of state.expired)
223
+ lines.push(`[idle] ${(0, approve_1.subjectCells)('[idle] ', p)}`, ` last activity: ${(0, screen_safe_1.rowField)(p.lastTs, 28)} · id: ${(0, screen_safe_1.rowField)(p.id, 40)}`);
224
+ }
158
225
  const decided = Object.entries(state.decisions).sort((a, b) => (Date.parse(b[1].ts) || 0) - (Date.parse(a[1].ts) || 0)).slice(0, opts?.recent ?? 10);
159
226
  if (decided.length > 0) {
160
227
  lines.push('');
@@ -174,7 +241,20 @@ function renderStatus(state, ctx, opts) {
174
241
  lines.push(` id: ${(0, screen_safe_1.rowField)(id, 40)}${d.actor ? ` \u00b7 by ${(0, screen_safe_1.rowField)(d.actor, 24)}` : ''}`);
175
242
  }
176
243
  }
244
+ // @implements A-SPEC-794.35 \u2014 every grant file the store reads is shown, a hand-written one included (A-M1)
245
+ const others = ctx.otherGrantFiles ?? [];
246
+ if (others.length > 0) {
247
+ lines.push('');
248
+ lines.push(`\u25c6 ${others.length} grant file(s) beyond a request's own exact grant`);
249
+ // the word stays unclipped and last: it is what is pasted back
250
+ for (const f of others)
251
+ lines.push(` ${(0, screen_safe_1.rowField)(f.name, 40)} ${(0, screen_safe_1.rowField)(f.scope ?? '', 40)} ${f.covers ? 'covers an act now' : 'covers nothing now'} ${(0, approve_1.revokeWord)(f.name)} --reason <text>`);
252
+ }
177
253
  if (state.malformedLines > 0)
178
254
  lines.push(`(${state.malformedLines} unreadable line(s) in the queue \u2014 check for corruption)`);
255
+ // @implements A-SPEC-794.32 \u2014 the status (and the --watch header it is) names development-build requests too
256
+ const dev = (0, approval_queue_1.devFiledNote)(state);
257
+ if (dev !== null)
258
+ lines.push(dev);
179
259
  return lines.join('\n');
180
260
  }
@@ -30,6 +30,11 @@ export declare const DEFAULT_POLL_MS = 500;
30
30
  export interface WatchOpts {
31
31
  /** Idle poll cadence in ms. */
32
32
  pollMs?: number;
33
+ /** @implements A-SPEC-794.33 — the stale window --list folds with; the watch presents what the list would list (A-H2). */
34
+ stale?: {
35
+ ttlMs: number;
36
+ showAll: boolean;
37
+ } | null;
33
38
  /** Ends the resident loop and any in-flight idle wait / keypress wait. */
34
39
  signal?: AbortSignal;
35
40
  /**
@@ -5,7 +5,7 @@ exports.decideByKey = decideByKey;
5
5
  exports.presentByKey = presentByKey;
6
6
  exports.defaultWaitIdle = defaultWaitIdle;
7
7
  exports.runWatch = runWatch;
8
- // @implements A-SPEC-262.2, A-SPEC-497.4, A-SPEC-770.12
8
+ // @implements A-SPEC-262.2, A-SPEC-497.4, A-SPEC-770.12, A-SPEC-245.17, A-SPEC-794.33, A-SPEC-794.34, A-SPEC-794.35, A-SPEC-794.41
9
9
  //
10
10
  // The RESIDENCE of the decision surface. S-262.1 made the surface's CONTENT (transcript-zero
11
11
  // references, context, one-key/batch); this is a thin polling loop over that content, so a request
@@ -104,7 +104,8 @@ async function presentByKey(root, io, actor, stream, state) {
104
104
  const d = await decideByKey(stream, p, details);
105
105
  if (d === 'granted') {
106
106
  const r = (0, approve_1.grantRequest)(root, p.id, { actor });
107
- io.print(r.ok ? `✓ approved — ${(0, approve_1.subjectCells)('✓ approved — ', p)}` : `✗ ${r.reason}`);
107
+ // A-SPEC-245.17 (item 3) — the watch's approval line names the use count and the expiry, like every producer
108
+ io.print(r.ok ? `✓ approved — ${(0, approve_1.subjectCells)('✓ approved — ', p)}\n ${(0, approve_1.grantValidityText)(r.expires)}` : `✗ ${r.reason}`);
108
109
  }
109
110
  else if (d === 'denied') {
110
111
  const r = (0, approve_1.denyRequest)(root, p.id, 'denied by the operator with a single key in watch (no immediate reason)', actor);
@@ -152,7 +153,8 @@ async function runWatch(root, io, actor, opts = {}) {
152
153
  // skipped items wait, silently, until they change or a new request joins them.
153
154
  let lastPresented = new Set();
154
155
  while (!signal?.aborted) {
155
- const state = (0, approval_queue_1.readQueue)(root);
156
+ const fold = opts.stale ? { now: Date.now(), ttlMs: opts.stale.ttlMs } : undefined; // A-SPEC-794.33
157
+ const state = (0, approval_queue_1.readQueue)(root, fold);
156
158
  // Prune ids that are no longer pending BEFORE deciding what is new (round-1 F1). Without this,
157
159
  // `lastPresented` kept the id of an item that was decided and removed, so when that id came
158
160
  // BACK — the agent retrying a denied action, which is the very thing a resident operator watches
@@ -186,7 +188,7 @@ async function runWatch(root, io, actor, opts = {}) {
186
188
  if (opts.keyStream)
187
189
  await presentByKey(root, io, actor, opts.keyStream, state);
188
190
  else
189
- await (0, approve_1.runInteractive)(root, io, actor);
191
+ await (0, approve_1.runInteractive)(root, io, actor, opts.stale);
190
192
  }
191
193
  catch (e) {
192
194
  // The operator leaving mid-decision (Ctrl-C / EOF) surfaces as AbortError through the
@@ -200,13 +202,16 @@ async function runWatch(root, io, actor, opts = {}) {
200
202
  // its id returns (a retry after denial) it reads as new and is re-presented (round-1 F1). A
201
203
  // request that arrived DURING the pass is not in `shown`, so it too is new next pass — one
202
204
  // cycle late, not lost. Skipped items are in both sets, so they are not re-flooded.
203
- const afterIds = new Set((0, approval_queue_1.readQueue)(root).pending.map((p) => p.id));
205
+ const afterIds = new Set((0, approval_queue_1.readQueue)(root, fold).pending.map((p) => p.id));
204
206
  lastPresented = new Set([...shown].filter((id) => afterIds.has(id)));
205
207
  }
206
208
  else if (state.pending.length === 0) {
207
209
  if (!idleAnnounced) {
208
210
  io.print(exports.WATCH_IDLE);
209
211
  idleAnnounced = true;
212
+ // @implements A-SPEC-794.34 — idle with only stale requests: say how many the window folded (B-4)
213
+ if (opts.stale && state.expired.length > 0)
214
+ io.print(`⏳ ${state.expired.length} folded as idle (no activity for over ${opts.stale.ttlMs / 3_600_000}h, still pending) — approve --list --all shows them`);
210
215
  // @implements A-SPEC-770 — once per idle announcement: the refusals this surface does not list, by count.
211
216
  const footer = (0, approve_1.outsideInboxFooter)((0, approval_queue_1.refusalsOutsideInbox)(root), root); // @implements A-SPEC-770.2
212
217
  if (footer !== null)
@@ -1,4 +1,5 @@
1
1
  import { QueueState, PendingRequest } from '../governance/approval-queue';
2
+ import { LedgerActor } from '../governance/human-channel';
2
3
  /**
3
4
  * `holmes-kit approve` — the surface where a human decides.
4
5
  *
@@ -20,25 +21,35 @@ export declare const DEFAULT_TTL_MINUTES = 30;
20
21
  export type DecisionResult = {
21
22
  ok: true;
22
23
  expires?: string;
24
+ note?: string;
23
25
  } | {
24
26
  ok: false;
25
27
  reason: string;
26
28
  };
29
+ /**
30
+ * @implements A-SPEC-792.17 — what a decision line says about a grant's life: a grant without a time limit is spent by
31
+ * its first use (A-SPEC-532.5, 792.2), so it never shows the GRANT_NO_EXPIRY date as a validity period.
32
+ */
33
+ export declare function grantValidityText(expires: string | undefined): string;
27
34
  export declare function grantRequest(root: string, id: string, opts: {
28
- actor: string;
35
+ actor: LedgerActor;
29
36
  ttlMinutes?: number;
30
37
  rationale?: string;
31
38
  }): DecisionResult;
32
39
  /**
33
- * @implements A-SPEC-649
34
- * Withdraw a live grant. The operator changed their mind, or the request's subject moved on: the
35
- * file goes, and the queue says so — a `revoked` decision the fold reads like a denial. Refuses
36
- * an empty reason (a revocation the agent cannot read is invisible) and an id that was never
37
- * granted here (nothing to withdraw). A grant already spent has no file; revoking it records the
38
- * intent for the audit trail but cannot un-seal — the ledger is the record of what happened.
40
+ * @implements A-SPEC-794.33 — what `--revoke` resolves against: the granted decisions and the ids the grant directory names,
41
+ * its claimed copies included (a grant whose row is torn, or whose file an act holds, still covers its act: A-1, A-2).
42
+ * A queue row's id counts only as a request id (a forged row's id is never a candidate: A-4). A-SPEC-794.35 — every grant
43
+ * file the store reads counts by its own name (`grantFileNames`), so a grant that covers its act is always revocable (A-M1).
39
44
  */
45
+ export declare function revokeCandidates(root: string): string[];
40
46
  export declare function revokeGrant(root: string, id: string, reason: string, actor: string): DecisionResult;
41
- export declare function denyRequest(root: string, id: string, reason: string, actor: string): DecisionResult;
47
+ /**
48
+ * @implements A-SPEC-794.37 — the `--revoke=` word for a grant file's name, safe to paste into a POSIX shell: plain as it
49
+ * is, single-quoted otherwise, and with a control character through `printf` so that none reaches the screen raw.
50
+ */
51
+ export declare function revokeWord(name: string): string;
52
+ export declare function denyRequest(root: string, id: string, reason: string, actor: LedgerActor): DecisionResult;
42
53
  /**
43
54
  * @implements A-SPEC-779.2 — the run that filed a request closes it. Recorded as `withdrawn`, never `denied`: a denial
44
55
  * is the operator's decision, and a requester using it to tidy up writes a decision nobody made. Only the filing run
@@ -51,7 +62,7 @@ export declare function withdrawRequest(root: string, id: string, reason: string
51
62
  server?: string;
52
63
  }): DecisionResult;
53
64
  /** Hold with a question — approve/deny later. The agent carries the question to the user. */
54
- export declare function holdRequest(root: string, id: string, question: string, actor: string): DecisionResult;
65
+ export declare function holdRequest(root: string, id: string, question: string, actor: LedgerActor): DecisionResult;
55
66
  /**
56
67
  * The review screen. Pure.
57
68
  *
@@ -67,7 +78,16 @@ export declare function holdRequest(root: string, id: string, question: string,
67
78
  export declare function staleView(flags: Record<string, unknown>): {
68
79
  ttlMs: number;
69
80
  showAll: boolean;
70
- } | null;
81
+ } | null | {
82
+ refusal: string;
83
+ };
84
+ /**
85
+ * @implements A-SPEC-794.33 — the one spelling of `--target <root>` on a line made to be pasted (A-M5). Measured: a root
86
+ * named `/tmp/a;touch PWN1` ran `touch` in /bin/sh, because only white space was quoted. A root of plain path characters
87
+ * is printed bare; any other is POSIX single-quoted (PowerShell-literal on win32), so no byte of it is shell syntax. A
88
+ * root holding a control character is not printed: flattened, it would name another directory.
89
+ */
90
+ export declare function targetArg(root: string | undefined, platform?: string): string;
71
91
  /**
72
92
  * @implements A-SPEC-770 — the one line an inbox screen ends with when this machine's refusal log holds open requests
73
93
  * the screen does not list (A-SPEC-563.1 keeps gate refusals out of the inbox; A-SPEC-563.2 / A-SPEC-690 let
@@ -75,6 +95,17 @@ export declare function staleView(flags: Record<string, unknown>): {
75
95
  * @implements A-SPEC-770.1 — the grant command is spelled with its flag: a positional id is refused by the CLI.
76
96
  */
77
97
  export declare function outsideInboxFooter(outside: number | undefined, root?: string): string | null;
98
+ /**
99
+ * @implements A-SPEC-507.1 — the LIST VIEW folds stale entries (C4: 51 rows, mostly week-old residue, buried the one live
100
+ * approval at [32]); the fold is the caller's `readQueue(root, { now, ttlMs })`.
101
+ * @implements A-SPEC-794.30 (the repair 794.10 made, re-ported) — the one order of the list and of a list number.
102
+ * @implements A-SPEC-794.32 — that order is the filing order, the view or not: newest activity first let a request filed
103
+ * after the list take [1], and `--grant 1` granted what no one had read (P2). A new filing is appended at the end.
104
+ */
105
+ export declare function listedRequests(state: QueueState, _view?: {
106
+ staleHours: number;
107
+ showAll: boolean;
108
+ }): PendingRequest[];
78
109
  export declare function renderPending(state: QueueState, view?: {
79
110
  staleHours: number;
80
111
  showAll: boolean;
@@ -118,6 +149,8 @@ export declare function decisionSubject(p: PendingRequest, prefix?: string): str
118
149
  * grant is keyed by.
119
150
  */
120
151
  export declare function decisionDetail(p: PendingRequest, tail?: string): string;
152
+ /** @implements A-SPEC-794.34 \u2014 the 12 hex digits a screen shows of a request's subject digest, or '' when it has none. */
153
+ export declare function subjectDigest(p: PendingRequest): string;
121
154
  /**
122
155
  * The non-TTY fallback's next-command hint. Pure.
123
156
  *
@@ -141,8 +174,8 @@ export declare function renderRefusals(refusals: Array<{
141
174
  target: string;
142
175
  why: string;
143
176
  ts: string;
144
- }>, limit?: number, root?: string): string;
145
- export declare function renderNonTtyHint(state: QueueState): string;
177
+ }>, limit?: number, root?: string, open?: number): string;
178
+ export declare function renderNonTtyHint(state: QueueState, root?: string): string;
146
179
  export interface ApproveIO {
147
180
  print: (s: string) => void;
148
181
  /** Ask one question, resolve with the raw answer. Injected so tests script the conversation. */
@@ -162,4 +195,7 @@ export interface ApproveIO {
162
195
  * (REQ-262 Constraints: nothing is approved unseen). `[d]` still demands a reason, because an
163
196
  * unreasoned denial is invisible to the agent; `[q]` holds with a question; `[s]` leaves it.
164
197
  */
165
- export declare function runInteractive(root: string, io: ApproveIO, actor: string): Promise<void>;
198
+ export declare function runInteractive(root: string, io: ApproveIO, actor: string, stale?: {
199
+ ttlMs: number;
200
+ showAll: boolean;
201
+ } | null): Promise<void>;