@holmes-lab/holmes-kit 0.35.24 → 0.36.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 (136) hide show
  1. package/CHANGELOG.md +363 -0
  2. package/README.md +4 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +4 -1
  5. package/dist/holmes/cli/approve-watch.js +3 -1
  6. package/dist/holmes/cli/approve.d.ts +10 -0
  7. package/dist/holmes/cli/approve.js +34 -4
  8. package/dist/holmes/cli/claude-switches.d.ts +7 -1
  9. package/dist/holmes/cli/claude-switches.js +11 -7
  10. package/dist/holmes/cli/codex-toml.d.ts +3 -0
  11. package/dist/holmes/cli/codex-toml.js +2 -1
  12. package/dist/holmes/cli/doctor.d.ts +31 -1
  13. package/dist/holmes/cli/doctor.js +204 -7
  14. package/dist/holmes/cli/index.js +115 -4
  15. package/dist/holmes/cli/init.js +4 -3
  16. package/dist/holmes/cli/os-notify.d.ts +3 -1
  17. package/dist/holmes/cli/os-notify.js +10 -4
  18. package/dist/holmes/cli/review.d.ts +25 -0
  19. package/dist/holmes/cli/review.js +111 -0
  20. package/dist/holmes/cli/roles-readme.d.ts +11 -0
  21. package/dist/holmes/cli/roles-readme.js +38 -16
  22. package/dist/holmes/cli/roles.d.ts +12 -0
  23. package/dist/holmes/cli/roles.js +86 -0
  24. package/dist/holmes/cli/run.d.ts +65 -0
  25. package/dist/holmes/cli/run.js +308 -0
  26. package/dist/holmes/cli/runtime-binding-approval.js +3 -2
  27. package/dist/holmes/cli/runtime-binding.d.ts +30 -0
  28. package/dist/holmes/cli/runtime-binding.js +116 -11
  29. package/dist/holmes/cli/scratch.d.ts +12 -0
  30. package/dist/holmes/cli/scratch.js +20 -0
  31. package/dist/holmes/cli/test-platform.d.ts +16 -0
  32. package/dist/holmes/cli/test-platform.js +31 -1
  33. package/dist/holmes/config/config.d.ts +49 -0
  34. package/dist/holmes/config/config.js +146 -3
  35. package/dist/holmes/config/project-caps.d.ts +21 -0
  36. package/dist/holmes/config/project-caps.js +114 -0
  37. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  38. package/dist/holmes/governance/approval-queue.js +51 -8
  39. package/dist/holmes/governance/autonomy.d.ts +6 -0
  40. package/dist/holmes/governance/autonomy.js +21 -0
  41. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  42. package/dist/holmes/governance/push-gate-runner.js +49 -1
  43. package/dist/holmes/governance/replica-id.d.ts +9 -0
  44. package/dist/holmes/governance/replica-id.js +44 -7
  45. package/dist/holmes/governance/role-policy.d.ts +41 -1
  46. package/dist/holmes/governance/role-policy.js +137 -20
  47. package/dist/holmes/governance/run-mode.d.ts +14 -0
  48. package/dist/holmes/governance/run-mode.js +120 -0
  49. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  50. package/dist/holmes/governance/tool-actions.js +121 -0
  51. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  52. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  53. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  54. package/dist/holmes/guardrail/classification-mode.js +135 -0
  55. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  56. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  57. package/dist/holmes/guardrail/impact-gate.d.ts +2 -0
  58. package/dist/holmes/guardrail/impact-gate.js +34 -11
  59. package/dist/holmes/guardrail/phase.d.ts +2 -1
  60. package/dist/holmes/guardrail/phase.js +22 -8
  61. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  62. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  63. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  64. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  65. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  66. package/dist/holmes/guardrail/risk-classifier.js +255 -27
  67. package/dist/holmes/guardrail/risk-types.d.ts +16 -0
  68. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  69. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  70. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  71. package/dist/holmes/guardrail/run-refusals.js +348 -0
  72. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  73. package/dist/holmes/guardrail/run-stages.js +188 -0
  74. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  75. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  76. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  77. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  78. package/dist/holmes/guardrail/shell-words.js +7 -7
  79. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  80. package/dist/holmes/guardrail/write-target.js +118 -16
  81. package/dist/holmes/hooks/pre-tool-use.d.ts +36 -2
  82. package/dist/holmes/hooks/pre-tool-use.js +740 -81
  83. package/dist/holmes/hooks/session-start.js +5 -3
  84. package/dist/holmes/hooks/stop.d.ts +35 -1
  85. package/dist/holmes/hooks/stop.js +142 -7
  86. package/dist/holmes/mcp/elicit-approval.js +4 -4
  87. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  89. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  90. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  91. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  92. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  93. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  94. package/dist/holmes/mcp/handlers/spec-approval.js +56 -9
  95. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  96. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  97. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  98. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  99. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  100. package/dist/holmes/mcp/handlers.d.ts +2 -3
  101. package/dist/holmes/mcp/handlers.js +22 -2
  102. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  103. package/dist/holmes/mcp/harness-attestation.js +3 -1
  104. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  105. package/dist/holmes/mcp/operator-recovery.js +4 -3
  106. package/dist/holmes/mcp/server.js +9 -0
  107. package/dist/holmes/mcp/tool-schemas.js +6 -3
  108. package/dist/holmes/project/npx-bin.d.ts +26 -0
  109. package/dist/holmes/project/npx-bin.js +272 -2
  110. package/dist/holmes/project/root.js +6 -1
  111. package/dist/holmes/project/run-records.d.ts +17 -0
  112. package/dist/holmes/project/run-records.js +126 -0
  113. package/dist/holmes/project/scratch-root.d.ts +12 -0
  114. package/dist/holmes/project/scratch-root.js +132 -0
  115. package/dist/holmes/review/mrp.d.ts +35 -0
  116. package/dist/holmes/review/mrp.js +119 -0
  117. package/dist/holmes/review/verdicts.d.ts +117 -0
  118. package/dist/holmes/review/verdicts.js +345 -0
  119. package/dist/holmes/runtime/dispatch.js +6 -3
  120. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  121. package/dist/holmes/semantic/cloud-usage.js +106 -0
  122. package/dist/holmes/semantic/embedder.d.ts +15 -6
  123. package/dist/holmes/semantic/embedder.js +84 -3
  124. package/dist/holmes/semantic/local-model.d.ts +21 -2
  125. package/dist/holmes/semantic/local-model.js +14 -3
  126. package/dist/holmes/semantic/tier.d.ts +25 -0
  127. package/dist/holmes/semantic/tier.js +86 -1
  128. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  129. package/dist/holmes/semantic/vector-cache.js +4 -1
  130. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  131. package/dist/holmes/spec/approval-blockers.js +70 -2
  132. package/dist/holmes/spec/renumber.d.ts +1 -1
  133. package/dist/holmes/spec/renumber.js +5 -2
  134. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  135. package/dist/holmes/spec/transition-policy.js +17 -2
  136. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,369 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
  <!-- @implements A-SPEC-209 -->
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.36.0] - 2026-10-20
11
+
12
+ This is an interim hardening release of the role/phase goal (`docs/goals/GOAL-role-phase-sdlc-hardening-2026-10-17.md`).
13
+ It ships the run mode an orchestrator opens with `holmes-kit run start`, review verdicts that act as gates, run stages,
14
+ and the closing of gate holes found by adversarial reading, a 29-form write census, a 28-form staging census and the
15
+ Windows merge. The G7 acceptance scenario has **not** been run yet: a reference ACP orchestrator taking one task from
16
+ engine choice to merge gate, and the same scenario on a copy of a real Python repository. Interactive (human) use has no
17
+ deliberate breaking change versus 0.35.25. The new controls act only in a run or behind an opt-in setting. The new
18
+ refusals an interactive session can meet are the ones listed under Fixed, each a hole where the same act was already
19
+ refused on another path. The interactive no-regression matrix (G7.1) has not yet been run as a whole. Each Fixed entry
20
+ cites its own before/after measurement.
21
+
22
+ Upgrading: nothing is required. A role policy written for 0.35.25 keeps its verdicts outside a run.
23
+ `holmes-kit roles migrate [--dry-run]` rewrites it into the new vocabulary explicitly. Every PreToolUse deny reason now
24
+ ends with one `[holmes-refusal]` JSON line, so a tool that matches deny text exactly sees one more line.
25
+
26
+ ### Added
27
+
28
+ - **`holmes-kit run start|status|transition|stop`, a governed run for a worktree** (A-SPEC-774.17, A-SPEC-774.18,
29
+ A-SPEC-780).
30
+ - `run start --worktree <dir> --engine claude|codex|agy [--engine-arg <a>]… [--scope <A-SPEC-id>]…` checks that the
31
+ worktree would be governed. It must be a working tree of the target with specs present, the engine's MCP wiring
32
+ must name holmes-kit, the gate hook must be wired, and no engine argument may carry a gate-off marker. Any failed
33
+ check exits 3 and writes nothing.
34
+ - On success it writes the run record in the main checkout and prints the headless command (`claude -p`,
35
+ `codex exec`, `agy -p`), `HOLMES_RUN_ID` and a one-time stop key. Only the key's sha256 is stored.
36
+ - `run stop` removes the record only with that key, so an agent inside the run cannot end it and fall back to
37
+ interactive mode. `run status` lists runs, their state and their stage, without keys.
38
+ - Run start pins `{cli, cli_build, mcp, hook, hook_build}`. It refuses a mixed set (measured need: a session ran MCP
39
+ 0.35.19 with hooks 0.35.24). The contract starts in `docs/contracts/run.md` (A-SPEC-774.24).
40
+ - **`holmes-kit review record|status|gate|mrp`** (A-SPEC-102.2, A-SPEC-102.6, A-SPEC-102.7, A-SPEC-102.8).
41
+ - Verdicts are bound to the resolved base and head commits and go to an append-only ledger in the main checkout, so a
42
+ review recorded in a worktree outlives it.
43
+ - `record` refuses a self-review and a role without `RECORD_REVIEW`. It takes a SOLID checklist
44
+ (`--solid <S|O|L|I|D>=<compliant|violation|n-a>:<evidence>`): an incomplete checklist is refused, and so is a pass
45
+ that marks a violation. It also records the A-SPEC ids the commit messages state against the anchors the range
46
+ adds.
47
+ - Outside a run, a reviewer counts as an independent person only from a TTY with no agent-harness marker and no
48
+ claude, codex or agy/antigravity ancestor process. Measured: an agent that removed both Claude variables was still
49
+ identified, in 91 ms.
50
+ - `gate` exits 0 only when the latest independent verdict for exactly that range is pass and no open critical finding
51
+ remains (important ones too with `--strict`).
52
+ - `mrp` prints one JSON merge-ready package: changed files, the spec chain of every claimed A-SPEC, test evidence at
53
+ head, the review gate and `missing[]`. Only line-1 and added-line anchors count: the hook file went from 116 specs
54
+ to 26.
55
+ - **Run stages** (A-SPEC-781, A-SPEC-781.1, A-SPEC-774.19).
56
+ - `ax.config.json` `stages` declares `{order, transitions, reviewed, deny}`. The default is analysis → design →
57
+ implement → review → test → done, with review and test able to return to implement.
58
+ - `run transition --id --to --key [--why]` moves a run only with its stop key and only along a declared edge. A move
59
+ into a reviewed stage (default `test` and `done`) needs an independent passing review of base..HEAD.
60
+ - A role in a role policy may declare `stages`. `roleCheck` then judges action, role and stage together.
61
+ - **Every PreToolUse deny ends with a `[holmes-refusal]` line** (A-SPEC-777, A-SPEC-777.1, A-SPEC-790.3). The line
62
+ carries a stable code, a class (retryable / needs a person / needs a plan change) and remediation steps.
63
+ It is never added to an allow. A census test requires all 35 refusal heads to map to a code other than
64
+ `gate.unclassified`. No verdict and no prose changed.
65
+ - **A project caps its semantic tier: `semantic.maxTier` in `ax.config.json`** (A-SPEC-476.1, A-SPEC-476.2).
66
+ - The values are `cloud`, `local` and `none`. The cap only lowers the tier; consent to cloud egress stays with the
67
+ user-level key. An unreadable cap reads as `none`, and doctor shows FAIL.
68
+ - All ten semantic call sites read the capped tier, and a test holds that nothing else calls the uncapped resolver.
69
+ - doctor names the withheld key, e.g. `key present (macOS keychain), project cap local`.
70
+ - Measured need: one keychain key gave every repository on the machine the cloud tier.
71
+ - **doctor `cloud embedding usage` row** (A-SPEC-476.5, A-SPEC-476.6). Every cloud embedding HTTP attempt, retries
72
+ included, is counted per project and local day in git-ignored state. The row shows requests, texts and failures for
73
+ today and the last 7 days, on every tier, and never records the key or a text.
74
+ - **`autonomy.ceiling` in `ax.config.json`** (A-SPEC-532.6). The values are `off`, `tests`, `no-gate` and `default`.
75
+ It only narrows automatic and delegated seals; a seal above it goes to the operator with a note naming the ceiling.
76
+ doctor shows the ceiling in force.
77
+ - **`classification.strict` and `classification.testDirs` (opt-in)** (A-SPEC-775.1). With `strict: true` an
78
+ interactive project gets the run-mode classification: a nested `test/` folder is code unless declared, and an
79
+ unclassified write outside the safe list (documents, assets, lock files, licences, test data, the store) is
80
+ `WRITE_CODE`. Folders declared in `testDirs` are tests in every mode.
81
+ - **`holmes-kit approve --withdraw <ref> --reason <text>`** (A-SPEC-779.2, A-SPEC-779.3). Before this, an orchestrator
82
+ could close a request it abandoned only with `--deny`, which records an operator decision nobody made.
83
+ - Only the run that filed the request may withdraw it, and the event is recorded as `withdrawn`.
84
+ - `approve --status` shows "withdrawn … by run <id>", and `approval_status` reports `withdrawn` with a next action.
85
+ - A request filed outside a run cannot be withdrawn; the operator denies it.
86
+ - **Approval requests carry the spec title** (A-SPEC-770.12). The refusal bracket, the inbox, the watch screen and the
87
+ OS notification show it, so the owner no longer sees only a `req-…` hash. Without a title the bytes are unchanged.
88
+ - **`holmes-kit roles migrate [--dry-run]`** (A-SPEC-774.10). It rewrites a role policy into `vocabulary: 2` with
89
+ equal verdicts for every defined role outside a run (equivalence test). The shipped roles guide now uses only
90
+ actions the gate judges and defaults to a role that grants nothing (A-SPEC-774.16).
91
+ - **Interactive warnings that do not block**:
92
+ - a seal whose body is still a `spec_slice_init` scaffold (A-SPEC-182.1, A-SPEC-182.2; census: 421 approved specs
93
+ here carry one);
94
+ - a seal under an unapproved or missing ancestor, with a new doctor row `sealed under unsealed ancestor`
95
+ (A-SPEC-182.3, A-SPEC-182.4);
96
+ - an edit that adds another spec's anchor after a scope refusal on that file (A-SPEC-166.2);
97
+ - a changed source whose anchor names an unapproved spec, as a tracked Stop line (A-SPEC-166.3);
98
+ - a role policy whose default allows more than every role allows, as a doctor WARN (A-SPEC-774.8);
99
+ - an agent launch that inherits authority variables. The warning names them (never their values) and gives the
100
+ operator's `env -u … <command>` (A-SPEC-774.13).
101
+ - **`spec_list` names the store it answered from** (`store { projectRoot, specsRoot }`) (A-SPEC-774.25).
102
+
103
+ ### Fixed
104
+
105
+ - **A role-restricted session wrote specs, ran spec tools and wrote code through side paths** (A-SPEC-774,
106
+ A-SPEC-774.5, A-SPEC-774.6, A-SPEC-774.15). These apply only where a role policy exists.
107
+ - A reviewer allowed only `WRITE_TEST` wrote A/T-SPEC files. The spec-store branch now asks the role first, and a
108
+ spec-write approval does not lift a role refusal.
109
+ - The same role ran `spec_create`, `spec_remediate` and NotebookEdit unchecked. The MCP server now asks the role from
110
+ a census-checked table, including the bound project's policy.
111
+ - A project with a role policy and no specs skipped the role. A policy file that failed to load (anything but
112
+ ENOENT) switched roles off; it now grants nothing. `.json` policies are read.
113
+ - **Shell writes of executable files passed** (A-SPEC-774, A-SPEC-775). `deploy.sh`, `Makefile`, `Dockerfile`, a CI
114
+ workflow and `.c` files written from the shell passed, although Write refused them. Every path in write position is
115
+ now classified. A file that executes is code before it is a test, so `deploy.test.sh` and `ci.test.yml` are no
116
+ longer `WRITE_TEST`.
117
+ - **Authority variables were set through other spellings** (A-SPEC-774, A-SPEC-774.9). `printf -v`, `read`, indirect
118
+ `export` and a backslash-split name set `HOLMES_ROLE`-class variables unrefused. A name is now matched anywhere after
119
+ shell quoting is removed; read-only searches stay free. `HOLMES_RUN_ID` joins the list. `cleanSubprocessEnv` also
120
+ scrubs the gate bypass and the autonomy switch.
121
+ - **Agent launches that change what the child loads are refused, in shell and interpreter spawns alike** (A-SPEC-774.5,
122
+ A-SPEC-774.11, A-SPEC-774.12, A-SPEC-774.26).
123
+ - Refused: `--settings`, `--setting-sources`, `--mcp-config`, `--strict-mcp-config`, `--safe-mode`,
124
+ `disableAllHooks`, config-directory variables and `HOME`, codex `-c` keys off the list (hooks and
125
+ `projects.*.trust_level` included), `--profile` and `--yolo`.
126
+ - Launches through `tmux`, `script`, `watch`, `screen`, `osascript`, `parallel`, `find -exec` and `rebase -x` are
127
+ recognised.
128
+ - `spawnSync('codex', ['exec', '-c', 'approval_policy=never'])` passed while the shell form was refused. Both are now
129
+ judged on one marker list.
130
+ - **Path-less staging reached spec changes with no approval** (A-SPEC-226.3).
131
+ - `git add .ax/specs` asked for an approval. `git add -A`, `git add .`, `git add .ax`, `git add :/`, a glob,
132
+ `git add -u|--all|--`, `git stage -A` and `git commit -a|-am` staged the same changes with none: 28 forms, identical
133
+ on 0.35.25. This session committed four spec slices that way.
134
+ - The hook now runs one `git status --porcelain -z` of the spec store, for staging verbs only and never with the
135
+ command's options. A covering clause over a changed store gets the named form's verdict.
136
+ - With a clean spec tree all 28 forms keep the 0.35.25 verdict.
137
+ - **Shell writes with a computed target or command passed** (A-SPEC-747.4, A-SPEC-747.7, A-SPEC-747.8).
138
+ - A 29-form census found 19 code writes allowed:
139
+ - `xargs` and `parallel` running cp, sed -i, tee and touch (9);
140
+ - `find -exec`, `-execdir` and `-ok` (5);
141
+ - a variable or an IFS join as the destination or the command word (5).
142
+ - `find src -name '*.ts' | xargs sed -i …` rewrote every code file. All 19 are now refused with the code-write
143
+ reason.
144
+ - Session corpus (15,819 distinct commands, previous build against this one): 8 allow → deny, each a real code write
145
+ through a variable or loop. 0 deny → allow.
146
+ - A variable assigned two different values, or only as an argument, places no write (A-SPEC-747.10):
147
+ `F=src/x.ts; cp /dev/null "$F"; F=/tmp/x.ts` passed on 0.35.25 and before release; it is refused.
148
+ - **A cap in `ax.config.json` could be lifted by the agent it narrows** (A-SPEC-476.3, A-SPEC-476.4).
149
+ - Edit, Write, `echo >`, `rm` and `sed -i` were all allowed. Raising or removing `semantic.maxTier` or
150
+ `autonomy.ceiling` now needs a config-write approval; lowering a cap and unrelated edits pass.
151
+ - A shell write, whose content cannot be read, asks only while the disk sets a cap.
152
+ - A broken `ax.config.json` read the widest autonomy ceiling; it now reads `off`.
153
+ - Measured: with no cap all 10 acts keep the 0.35.25 verdict.
154
+ - An allowed cap write no longer hides a later wiring act in the same command (A-SPEC-476.7): the independent review
155
+ found `printf '{}' > ax.config.json; unlink .claude/settings.local.json` allowed before release; it is refused, as on
156
+ 0.35.25.
157
+ - **An Edit or MultiEdit could add a draft spec's anchor** (A-SPEC-166.1). Write already refused it. The edit locked
158
+ the file to every later edit. Edits are now judged on the file they leave, and an existing file the gate cannot read
159
+ is refused rather than judged by its payload.
160
+ - **A foreign MCP tool wrote code the gate never saw** (A-SPEC-776). `write_file{path}`, `edit_file{path}`,
161
+ `write{filePath}`, `save{uri}`, `create{target}` and `move{destination}` are now judged as a Write of every path they
162
+ name. A non-file URI is refused.
163
+ - **Claude Code's PowerShell tool had no gate on Windows** (A-SPEC-790, A-SPEC-790.1, A-SPEC-790.3, A-SPEC-790.4).
164
+ - `Remove-Item -Recurse -Force .ax/specs`, `Set-Content src/….ts` and `git push --force` got no decision; their Bash
165
+ twins were denied.
166
+ - PowerShell text is now translated with PowerShell syntax into the shell acts it performs, and the existing rules
167
+ decide. An encoded or unterminated command is refused as `gate.unjudgeable`.
168
+ - `(Get-Item .ax/…).Delete()` is refused. `(Get-Content .ax/x).Count` and an everyday `Get-ChildItem … |
169
+ Select-Object` stay reads.
170
+ - A writer, Remove-Item or Rename-Item whose target comes through the pipeline (`Get-Item src/x.ts | Set-Content
171
+ -Value r`) is unjudgeable and refused (A-SPEC-790.5); a `-WhatIf` preview reads its paths instead of being refused
172
+ as the act it previews (A-SPEC-790.6).
173
+ - **On Windows, store rewrites under a spaced project root escaped the gate** (A-SPEC-728.3). Under
174
+ `C:\Users\First Last`, `echo .* && sh -c 'cat "$0"'` and a spec edit through a junction were allowed. The spliced
175
+ base is now spelled with `/`.
176
+ - **Read-only commands were refused for spellings inside them** (A-SPEC-747.3, A-SPEC-747.5, A-SPEC-747.6,
177
+ A-SPEC-747.9).
178
+ - A `\|` inside a quoted grep pattern, `ps -Ao etime,command`, and a write verb inside quoted text or a path no
179
+ longer make a read a write.
180
+ - `git -C "<root>" log -- .ax/specs` and `cd "<root>" && git status` under a root whose path holds a space are reads
181
+ again: 24 deny → allow in the session corpus, all reads, and 0 allow → deny.
182
+ - Against 0.35.25 over 40 write and environment shapes, no refused command became allowed. Three that 0.35.25
183
+ allowed are now refused, `ps -E` and `ps axe` among them. A clause holding a lone `&` is no longer a read
184
+ (`grep NAME f & node -e …` passed on 0.35.25).
185
+ - **A fresh linked worktree and a run shared the main checkout's ledger chain** (A-SPEC-643.1). Each now gets its own
186
+ replica id (`<host>-wt-<name>`, `<host>-run-<id>`), so merging their branches no longer forks one hash chain.
187
+ Existing checkouts keep their id.
188
+ - **`spec_renumber` left the moved REQ's approval unrecorded** (A-SPEC-255.1). Following the plan left every Stop
189
+ blocked with ART-5. The plan now re-approves each moved, still-sealed spec, REQ first.
190
+ - **`spec_list` answered for whichever store the server was bound to** (A-SPEC-774.25). A root naming another project
191
+ is now refused, as `review_status` and `test_run` already did.
192
+ - **On Windows, a root `.claude/settings.local.json` with `disableAllHooks` was never read** (A-SPEC-251.3). Windows
193
+ has no uid, so init and doctor said the gate was enforced. Only the owner check now needs a uid.
194
+ - **A native Windows path in a patch header was unreadable** (A-SPEC-163.8). Every `apply_patch` naming `src\x.ts` was
195
+ denied, even outside the project.
196
+ - **A second `runtime-binding setup` on Windows refused Holmes's own Antigravity entry** (A-SPEC-751.8,
197
+ A-SPEC-751.9). Windows 8.3 names change once the file exists. doctor's antigravity row FAILed for the same reason.
198
+ - **The Codex duplicate-route fix line wrote a `config.toml` Codex could not load on Windows** (A-SPEC-769.22). The
199
+ `hooks.state` key is now a TOML string.
200
+ - **The local embedding refresh starved the machine** (A-SPEC-719.14, A-SPEC-719.15). Measured on Windows:
201
+ - Six refresh children ran at once because their deadline timers could not fire. The warm loop now yields after
202
+ each inference.
203
+ - A requirement text of up to 28,946 tokens drove BGE-M3 past 6.9 GB in 6 s. Input is now capped at 2,048 tokens
204
+ and longer texts are pooled from chunks: peak 3.74 GB, median cosine 1.000 against full-length vectors.
205
+ - Texts within the cap embed exactly as before.
206
+
207
+ ### Run mode only
208
+
209
+ These controls act only inside a run: `HOLMES_RUN_ID`, or a run record binding the session's cwd or session id. A
210
+ session in a git worktree reads the main checkout's run records through the `.git` pointer (A-SPEC-774.11). A
211
+ session cannot set the marker, because `HOLMES_RUN_ID` is an authority name. An unreadable record counts as a run.
212
+ Every judgement in a run fails closed and names what it could not read. Child agents start through
213
+ `holmes-kit run start` (the adapter path, A-SPEC-774.28).
214
+
215
+ - **Every agent launch from inside a run is refused** (A-SPEC-774.9). The engine's autonomy arguments are passed to
216
+ `run start --engine-arg`, judged on the same marker list: `--dangerously-skip-permissions` starts a run, while
217
+ `--settings` exits 3 (A-SPEC-774.27).
218
+ - **Versions** (A-SPEC-774.20, A-SPEC-774.24, A-SPEC-780, A-SPEC-780.1).
219
+ - A version field run start cannot read blocks unless `--accept-unknown-versions <field,…>` names it. agy's `hook`
220
+ and `hook_build` are exempt by table.
221
+ - A change of the governing install mid-run, or a build that becomes unreadable, logs `install_changed`. Every later
222
+ call is refused `run.stopped`, even after the install is changed back.
223
+ - **Refusal log and repeat stop** (A-SPEC-778, A-SPEC-778.1, A-SPEC-778.2).
224
+ - Each refusal is appended to a protected per-run log. One code repeated `run.refusalRepeatLimit` times (1–1000,
225
+ default 5) stops the run.
226
+ - A Stop the gate keeps blocking ends the run as `stalled`. Every later call is then refused until the operator ends
227
+ the run.
228
+ - **Approval wait** (A-SPEC-779, A-SPEC-779.1).
229
+ - A refusal that files a request pauses the run (`run.awaiting-approval`, not counted toward the repeat stop) until
230
+ the request is decided.
231
+ - A wait past `run.approvalWaitMinutes` (1–10080, default 60) stops the run.
232
+ - `approve --grant` refuses a process carrying `HOLMES_RUN_ID`, and refuses a non-terminal grant of a request a run
233
+ awaits. Denials are never blocked.
234
+ - **Stages** (A-SPEC-781.1, A-SPEC-781.2, A-SPEC-774.19, A-SPEC-774.22).
235
+ - The default machine denies `WRITE_CODE` and `WRITE_TEST` in analysis, design, review and done, and `WRITE_CODE` in
236
+ test. A violation is refused as `stage.refused`.
237
+ - A declared stage without a deny entry denies. A malformed role `stages` is refused in every stage.
238
+ - A condition with no checker refuses. `design-section` is recorded as unchecked until G5.7.
239
+ - **Review gates** (A-SPEC-102.3, A-SPEC-102.4, A-SPEC-774.21). The Stop hook blocks with ART-7, and the pre-push gate
240
+ refuses, while the run's commits since start lack an independent passing review. A missing record or base, an
241
+ unresolvable range or an error blocks.
242
+ - **Plan scope** (A-SPEC-102.5, A-SPEC-774.23). A run started with `--scope` writes only inside its plan specs' Files
243
+ to Touch, through file tools and shell writes alike, whatever review text asks. A plan that cannot be read refuses
244
+ every write.
245
+ - **Classification and roles** (A-SPEC-775.1, A-SPEC-774.8, A-SPEC-774.10, A-SPEC-774.15).
246
+ - The strict classification applies.
247
+ - A policy whose default is broader than every role grants nothing.
248
+ - The new action vocabulary is read strictly, and a duplicated role grants nothing.
249
+ - Only a `role-override` approval lifts a role refusal.
250
+ - **Seals and anchors** (A-SPEC-182.1, A-SPEC-182.3, A-SPEC-182.4, A-SPEC-166.2, A-SPEC-166.3). These are refused, as
251
+ they also are under `classification.strict`:
252
+ - a scaffold body at a seal;
253
+ - a seal under an unapproved or missing ancestor;
254
+ - an anchor swapped in after a scope refusal;
255
+ - a changed source anchored to an unapproved spec at Stop.
256
+ - **Caps** (A-SPEC-476.3, A-SPEC-476.4). A run cannot change a cap in `ax.config.json` in either direction, and has no
257
+ approval path (`cap.run-fixed`).
258
+
259
+ ### Changed
260
+
261
+ - **Interactive agent launches pass a per-harness allowlist** (A-SPEC-774.11, A-SPEC-774.26, A-SPEC-774.27,
262
+ A-SPEC-774.28).
263
+ - Owner decision 2026-10-18: options that only skip the child harness's own prompts are allowed:
264
+ - claude `--dangerously-skip-permissions` and `--permission-mode bypassPermissions`;
265
+ - codex `--dangerously-bypass-approvals-and-sandbox`, `-a never`, `-s danger-full-access` and
266
+ `-c approval_policy|sandbox_mode`;
267
+ - agy `--dangerously-skip-permissions` and `--mode auto`.
268
+ - Each was measured to keep the child's Holmes PreToolUse gate: a canary code write was refused and no file was
269
+ created.
270
+ - Quoted prompt text is no longer read as options. The refusal names the autonomy options.
271
+ - **The deny-reason key folds interpolated paths and approval-hint commands** (A-SPEC-578.10). The live corpus went
272
+ from 97 keys back to 91, under the cap of 96.
273
+ - **The unjudgeable PowerShell refusal names REQ-790** (A-SPEC-790). The family was renumbered from REQ-774 because of
274
+ an id collision.
275
+
276
+ ### Known issues
277
+
278
+ - **G7 and G6 are not done.** The acceptance scenario and its record (run ledger, MRP, refusal log) do not exist yet,
279
+ nor does the integration guide `docs/integration/jarvis-role-phase.md`. No commit in this release implements the run
280
+ token (G2.4), the event stream (G9.17), the ACP extension (G2.7) or design-principle blocking (G5).
281
+ - **Codex and Antigravity shell text on Windows** (A-SPEC-790.2, draft). Both harnesses send shell commands under a Bash
282
+ name. Which shell runs that text on Windows is unmeasured. If it is PowerShell, it is judged with Bash rules today.
283
+ - **PowerShell limit** (A-SPEC-790.3). `$f = Get-Item .ax/x; $f.Delete()` carries no path and is not refused.
284
+ - **Specs rewritten from content the gate cannot see** (A-SPEC-226.3). `git apply`, `git am`,
285
+ `git stash pop|apply`, `git read-tree -u` and `git checkout-index -f` were allowed on 0.35.25 and still are.
286
+ Path-less staging of the ledgers and the approval queue is not judged either.
287
+ - **Text runners** (A-SPEC-747.4). A write verb reached only through `sh -c "$CMD"` or `bash script.sh` is left to
288
+ A-SPEC-747's interpreter rule.
289
+ - **A-SPEC-100 prose false positive** (A-SPEC-747.8).
290
+ - An Edit to the code-write block of `pre-tool-use.ts` was refused three times as "A-SPEC-100 is not approved". The
291
+ file's only bare `A-SPEC-100` is a prose example.
292
+ - The cause is not investigated. As a result, a direct `sed -i … $S/x.ts` operand is still refused, as in 0.35.25.
293
+ - **Windows residuals.** Six timing bounds remain red on Windows: harness-config-protection rounds 41, 43 and 44,
294
+ mcp-version `:1187` and `:1807`, and nested-worktree round 8. The Windows verification ran 41 Windows-relevant suites
295
+ (1,440 tests, no new red), not the full suite. A-SPEC-747.9 was measured on macOS with a spaced root, not yet on
296
+ Windows.
297
+ - **Unmeasured launch options.** agy `--project` and `--add-dir` may change where agy loads hooks. Which
298
+ `ANTIGRAVITY_*` variable agy's shell sets is also unmeasured, so an agy reviewer is recognised only by its ancestor
299
+ process (A-SPEC-774.28, A-SPEC-102.8).
300
+ - **Interactive agent launches are an allowlist** (A-SPEC-774.11, A-SPEC-774.26). An option that is on no per-harness
301
+ list is refused, and the refusal names it (agy `--remote-control`, for example). A harmless option refused this way
302
+ is a defect to report.
303
+ - **Shell writes to a capped config ask every time** (A-SPEC-476.3). A shell write's content cannot be read, so once a
304
+ cap is set every shell write of `ax.config.json` asks for an approval. Lowering a cap through Edit stays free.
305
+ - **The embedding repairs were measured on Windows only** (A-SPEC-719.14, A-SPEC-719.15). The code applies on every
306
+ platform.
307
+
308
+ ## [0.35.25] - 2026-10-17
309
+
310
+ Upgrading:
311
+ - Where another holmes-kit copy sits in an ancestor `node_modules` of the workspace, approval hints now name the
312
+ running install's own path (`'<node>' '<…>/bin/holmes-kit.js' approve …`). Elsewhere they stay `npx holmes-kit approve
313
+ …`.
314
+ - doctor's new `npx resolution` row names such a copy.
315
+
316
+ ### Added
317
+
318
+ - **`holmes-kit scratch [--new <label>]`** (REQ-773, A-SPEC-773): a per-user Holmes scratch root,
319
+ `os.tmpdir()/holmes-scratch-<uid>`, mode 0700.
320
+ - On macOS and Linux, an agent in Claude Code, Codex or Antigravity can remove an existing subdirectory of it
321
+ without an operator act, using one plain `rm -r[f]` of absolute paths, at most 64 of them.
322
+ - The gate checks on each call that the root is still this user's own, not a link, with no group/other bits. It
323
+ judges each target by its real path.
324
+ - These keep today's refusal:
325
+ - the root itself, the rest of the temporary directory, links out of the root, `..` and globs;
326
+ - tracked source;
327
+ - any command that is not a single plain `rm`: pipes into `xargs`/`parallel`, aliases, and a link or move earlier
328
+ in the same command (adversarial review, round 1).
329
+ - On Windows the directory is made, but the gate does not relax.
330
+ - The refusal of an out-of-project recursive `rm` now names `holmes-kit scratch --new <label>`.
331
+ - Known limits:
332
+ - `mv` is not gated, so data moved into the root by an earlier command can then be removed. The same two steps
333
+ were already possible with `rm -r` without `-f`.
334
+ - The window between the gate's judgement and the command's execution is not closed.
335
+ - The Codex and Antigravity hook `TMPDIR` has not been measured live. Where it differs from the agent's shell, the
336
+ gate simply does not relax.
337
+ - Owner decision, 2026-10-17: agents could not clean up review probes and had to ask.
338
+
339
+ ### Fixed
340
+
341
+ - **Approval hints reach the install that issued them** (A-SPEC-770.3–770.6).
342
+ - The incident: under a home directory holding `~/node_modules/@holmes-lab/holmes-kit` 0.19.3, a 0.35.23 refusal's
343
+ own `npx holmes-kit approve --grant <id>` ran 0.19.3 and answered "no pending request matches".
344
+ - The hint now walks the ancestors of the workspace and of the home directory, as npx does. It looks for a
345
+ `node_modules/.bin/holmes-kit` file entry that belongs to another install. Shim files (npm on Windows, pnpm) are
346
+ identified through the package directory beside them.
347
+ - When it finds one, the hint names the running install's quoted absolute path. That form needs no network, no npm
348
+ cache and no published version. On Windows it is PowerShell syntax.
349
+ - The emitters are the refusals, the Stop block, the dialog notices, the approve screens, the governance-wiring
350
+ message, the decline reason and the stale-grant hint.
351
+ - A version-pinned `npx -p …@<version>` was tried and withdrawn before release (review round 1). On a cold cache it
352
+ was a 703 MB download behind a prompt, and it failed for an unpublished version.
353
+ - The hint also treats as a shadow a project whose own `package.json` declares a `holmes-kit` bin. npx runs that bin
354
+ first, so this covers a holmes-kit checkout or fork.
355
+ - doctor WARNs on such a copy and names it.
356
+ - Known limit: a workspace member under a root that declares the bin is not detected yet.
357
+ - **`holmes-kit approve --refusals --target <root>` runs** (A-SPEC-770.11). Every refusal outside the inbox prints
358
+ this command. It exited with "--refusals requires a value" because the count was mandatory. The count is now optional
359
+ and defaults to 20.
360
+ - **A Codex or Antigravity hook that inherited `CLAUDE_PROJECT_DIR` is no longer denied** (A-SPEC-751.7). Claude Code
361
+ passes the variable to every process it launches. Through the runtime dispatcher, a Codex session under one of them
362
+ had every tool call denied as "Conflicting runtime workspace hints". The variable is now a hint for the Claude harness
363
+ only.
364
+ - **The pre-edit evidence warning no longer says "no-analysis" when an analysis exists** (A-SPEC-278.4, A-SPEC-278.5).
365
+ - With no digest (every Edit or Write), an analysis persisted at this HEAD that did not predict the file was skipped.
366
+ The warning then claimed no analysis at all.
367
+ - It now gives that analysis's own verdict, `target-out-of-scope`, naming its digest. The remediation no longer asks
368
+ for a digest retry the session cannot make.
369
+ - **`runtime-binding status` reads the heartbeat where the kernel writes it** (A-SPEC-772.12).
370
+ - In a nested checkout without `.ax`, status said `unverified` while doctor said observed.
371
+ - `observedUnrouted` now names each unrouted event, PreToolUse first, as `observedOther` does.
372
+
10
373
  ## [0.35.24] - 2026-10-17
11
374
 
12
375
  Upgrading: run `holmes-kit runtime-binding setup` again with this build, so the deployed dispatcher passes the routing
package/README.md CHANGED
@@ -9,8 +9,8 @@
9
9
  <!-- holmes-kit:attest:begin -->
10
10
  ![traced files](.ax/badges/traced.svg)
11
11
 
12
- **442/444** source files (99.5%) trace to an approved spec · **819/882** approved A-SPECs (92.8%) are anchored from code.
13
- Measured at `20e40719f1f2` (specs `sha256:0263ca8394c8`) — reproduce with `holmes-kit attest`.
12
+ **473/481** source files (98.3%) trace to an approved spec · **921/998** approved A-SPECs (92.2%) are anchored from code.
13
+ Measured at `69c1139fe1fd` (specs `sha256:ca25d287a2af`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
@@ -22,7 +22,9 @@ Measured at `20e40719f1f2` (specs `sha256:0263ca8394c8`) — reproduce with `hol
22
22
  ---
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
+ - **An orchestrator can run governed agents, and reviews become gates** *(new in 0.36.0)*: `holmes-kit run start --worktree <dir> --engine claude|codex|agy [--scope <A-SPEC>]…` opens a run that pins the CLI, MCP and hook builds, prints the headless command and a stop key, and ends only with that key (`run status`, `run transition`, `run stop`). Inside a run every judgement fails closed: agent launches are refused, refusals are logged with a repeat stop, an approval pauses the run until the operator decides it in a terminal, a declared stage machine (analysis → design → implement → review → test → done) denies writes per stage, and Stop and push wait for an independent passing review. `holmes-kit review record|status|gate|mrp` records verdicts bound to a commit range, refuses self-review (an agent-harness ancestor process included), and assembles the merge-ready package. Every deny ends with a `[holmes-refusal]` line carrying a stable code. A project can cap its semantic tier (`semantic.maxTier`) and its automatic approval (`autonomy.ceiling`) in `ax.config.json`, and only an approval can raise either. doctor counts cloud embedding requests. `approve --withdraw` lets a run close its own request. Interactive sessions keep 0.35.25 verdicts, except for the gate holes this release closes: path-less spec staging, computed shell writes, executable files and side paths under a role policy, and Claude Code's PowerShell tool on Windows. Interactive agent launches may carry the autonomy options measured to keep the child's Holmes gate. This is an interim release of the role/phase goal: the acceptance scenario with a reference orchestrator has not been run yet.
25
26
 
27
+ - **Agents clean up their own temporary work** *(new in 0.35.25)*: `holmes-kit scratch --new <label>` makes a directory under a per-user Holmes scratch root (`os.tmpdir()/holmes-scratch-<uid>`, mode 0700), and on macOS and Linux the gate lets an agent in Claude Code, Codex or Antigravity remove it with one plain `rm -rf <absolute path>` without an operator act; the root itself, tracked source, every other path and any compound command keep their verdict. Where another holmes-kit install sits in an ancestor `node_modules` of the workspace or the home directory (npm, Windows shims and pnpm alike), approval hints name the running install's own path so that copy cannot answer them (a PowerShell form on Windows), and doctor's `npx resolution` row names it.
26
28
  - **You can tell whether a harness's gate actually ran here** *(new in 0.35.24)*: the PreToolUse and Stop hooks of Claude Code, Codex and Antigravity leave a git-ignored per-harness record (`.ax/state/hook-heartbeat/`, at most one write a minute, never part of a decision). `workspace_preflight` with `harness` passes `runtime-enforcement` only after that harness's PreToolUse gate was observed within 24 h and since its wiring last changed; doctor shows one `hook observed (<harness>)` row each; `runtime-binding status` reports `activation` for this selection's gate and names every other observation and an outdated deployed dispatcher. `runtime_binding` answers an unbound workspace with its routing instead of "not registered", init states a Codex verdict for registry-owned Codex files, and doctor FAILs a running Stop hook under 75 s. Measured need: a Codex session in a release-routed workspace concluded it was ungoverned.
27
29
  - **A benchmark run the operator pre-approved finishes with zero human waits — the run delegation** *(new in 0.35.19)*: `holmes-kit autonomy delegate --run <id> --allow <rule[,rule]> [--for 2h] [--limit k=v]… [--rationale <text>]` (same human proof as `autonomy on`) writes a run-scoped, workspace-bound (realpath), expiring delegation that covers a closed set of autonomy-grader rules — root-only or gate-file Files to Touch, an undirected gate-behavior grade, an upstream without A-SPEC; never architecture documents, un-admitted requirements, undeclared or unknown grades. A hitl spec whose only reason is a covered rule seals on its own with `source: 'delegated'` and a ledger row naming the run and the rule; an uncovered case refuses with the named limit (`does not cover`, `expired`, `for <workspace>, not this root`, `invalid document`). `autonomy status`, `approve --status` and the session-start banner show it; `revoke-delegation` or `off` ends it. The host's own approval layer is named as not covered. Measured need: X1 (2026-10-12) stopped a pre-approved fixture on `files-to-touch-root-only`. Every operator hint now also names the workspace (`--target <root>`), a context-only Codex patch is refused as a no-op by name, and `runtime-binding status`/`doctor` report a Codex lifecycle routed to Holmes from both the user-level and the workspace hooks file.
28
30
  - **A refusal you cannot see in the inbox is still answerable from its own hint** *(new in 0.35.18)*: six repairs measured in a Codex X1 runtime session and a field report. Every refusal line written to the refusal log ends with `run: holmes-kit approve --grant <id> --target <root>` carrying the actual id, the inbox (`approve --list` / `--watch`) prints a footer counting requests outside the inbox, and the `--refusals` closing line spells the same command (the positional `approve <id>` the first repair wrote is refused by the CLI, so it was measured and rewritten). An autonomy refusal on a parent spec names the child rule that forces the human decision (`upstream-has-human-aspec: <id> — <rule>`). A runtime deadline refusal ends with the per-phase millisecond split, and the Stop hook prints how much of its 18 s budget it used once it passes half. `runtime-binding status` separates `drift` (operator-config / stale-workspace) from `conflicts` and reports whether the router is intact. The `--autonomy` usage, the `init` refusal and the interactive prompt now say the same thing.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- ba30504b-mvc1xwsd
1
+ 2e56a603-mvfhey8f
@@ -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
38
+ // @implements A-SPEC-650, A-SPEC-779.2
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
@@ -165,6 +165,9 @@ function renderStatus(state, ctx, opts) {
165
165
  lines.push(` \u2713 granted ${cells} ${grantedOutcome(id, d, ctx)}`);
166
166
  else if (d.event === 'revoked')
167
167
  lines.push(` \u2717 revoked ${cells} ${(0, screen_safe_1.rowField)(d.reason ?? '(no reason)', screen_safe_1.ROW_COLS)}`);
168
+ // @implements A-SPEC-779.2 \u2014 the requester closed it; not an operator decision.
169
+ else if (d.event === 'withdrawn')
170
+ lines.push(` \u21a9 withdrawn ${cells} ${(0, screen_safe_1.rowField)(d.reason ?? '(no reason)', screen_safe_1.ROW_COLS)}${d.run ? ` \u00b7 by run ${(0, screen_safe_1.rowField)(d.run, 40)}` : ''}`);
168
171
  else
169
172
  lines.push(` \u2717 denied ${cells} ${(0, screen_safe_1.rowField)(d.reason ?? '(no reason)', screen_safe_1.ROW_COLS)}`);
170
173
  lines.push(` id: ${(0, screen_safe_1.rowField)(id, 40)}${d.actor ? ` \u00b7 by ${(0, screen_safe_1.rowField)(d.actor, 24)}` : ''}`);
@@ -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
8
+ // @implements A-SPEC-262.2, A-SPEC-497.4, A-SPEC-770.12
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
@@ -92,6 +92,8 @@ function decideByKey(stream, _item, onView) {
92
92
  async function presentByKey(root, io, actor, stream, state) {
93
93
  for (const p of state.pending) {
94
94
  io.print(`\n─ ${(0, approve_1.subjectCells)('─ ', p)}`);
95
+ if (p.title)
96
+ io.print(` title: ${(0, screen_safe_1.flattenField)(p.title, 80)}`); // @implements A-SPEC-770.12
95
97
  // @implements A-SPEC-497.4 — owner report 2026-10-05: the row ended in a notice that 258 characters were cut, and one key approved it. A
96
98
  // clipped subject is a subject the operator did not see, so it is shown in full before any key is offered; `v`
97
99
  // shows the details of any item. The renderer is the line-based screen's own `[v]` — nothing is rendered here.
@@ -39,6 +39,16 @@ export declare function grantRequest(root: string, id: string, opts: {
39
39
  */
40
40
  export declare function revokeGrant(root: string, id: string, reason: string, actor: string): DecisionResult;
41
41
  export declare function denyRequest(root: string, id: string, reason: string, actor: string): DecisionResult;
42
+ /**
43
+ * @implements A-SPEC-779.2 — the run that filed a request closes it. Recorded as `withdrawn`, never `denied`: a denial
44
+ * is the operator's decision, and a requester using it to tidy up writes a decision nobody made. Only the filing run
45
+ * may withdraw; a request filed outside a run has no requester key (the CLI cannot see a harness session id), so the
46
+ * operator denies it.
47
+ */
48
+ export declare function withdrawRequest(root: string, id: string, reason: string, ctx: {
49
+ env: NodeJS.ProcessEnv;
50
+ cwd: string;
51
+ }): DecisionResult;
42
52
  /** Hold with a question — approve/deny later. The agent carries the question to the user. */
43
53
  export declare function holdRequest(root: string, id: string, question: string, actor: string): DecisionResult;
44
54
  /**
@@ -37,6 +37,7 @@ exports.DEFAULT_TTL_MINUTES = void 0;
37
37
  exports.grantRequest = grantRequest;
38
38
  exports.revokeGrant = revokeGrant;
39
39
  exports.denyRequest = denyRequest;
40
+ exports.withdrawRequest = withdrawRequest;
40
41
  exports.holdRequest = holdRequest;
41
42
  exports.staleView = staleView;
42
43
  exports.outsideInboxFooter = outsideInboxFooter;
@@ -48,7 +49,7 @@ exports.decisionDetail = decisionDetail;
48
49
  exports.renderRefusals = renderRefusals;
49
50
  exports.renderNonTtyHint = renderNonTtyHint;
50
51
  exports.runInteractive = runInteractive;
51
- // @implements A-SPEC-246, A-SPEC-626, A-SPEC-532.5
52
+ // @implements A-SPEC-246, A-SPEC-626, A-SPEC-532.5, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.12, A-SPEC-779.2
52
53
  // @implements A-SPEC-549.4 — renderPending and renderNonTtyHint in this file are the English CLI
53
54
  // surface the Hangul-absence guard reads.
54
55
  const execution_context_1 = require("../project/execution-context");
@@ -182,7 +183,7 @@ function grantRequest(root, id, opts) {
182
183
  // a subject keeps the default, because there the clock is all that stands between the decision and a changed act.
183
184
  const untilUsed = opts.ttlMinutes === undefined && typeof entry?.subject === 'string' && entry.subject !== '';
184
185
  if (!entry)
185
- return { ok: false, reason: `no pending request ${(0, screen_safe_1.rowField)(id, 40)} — check with ${(0, npx_bin_1.npxBin)()} holmes-kit approve --list` };
186
+ return { ok: false, reason: `no pending request ${(0, screen_safe_1.rowField)(id, 40)} — check with ${(0, npx_bin_1.holmesKitCommand)(root)} approve --list` };
186
187
  if (!recordIsSelfConsistent(entry))
187
188
  return { ok: false, reason: TAMPERED };
188
189
  // A "does this match what the operator saw" parameter was written here too and then removed: the
@@ -312,6 +313,33 @@ function denyRequest(root, id, reason, actor) {
312
313
  }
313
314
  return { ok: true };
314
315
  }
316
+ /**
317
+ * @implements A-SPEC-779.2 — the run that filed a request closes it. Recorded as `withdrawn`, never `denied`: a denial
318
+ * is the operator's decision, and a requester using it to tidy up writes a decision nobody made. Only the filing run
319
+ * may withdraw; a request filed outside a run has no requester key (the CLI cannot see a harness session id), so the
320
+ * operator denies it.
321
+ */
322
+ function withdrawRequest(root, id, reason, ctx) {
323
+ if (reason.trim() === '')
324
+ return { ok: false, reason: 'a withdrawal needs --reason — it is what the operator reads in place of a decision' };
325
+ const { entry } = findPending(root, id);
326
+ if (!entry)
327
+ return { ok: false, reason: `no pending request ${(0, screen_safe_1.rowField)(id, 40)}` };
328
+ if (!recordIsSelfConsistent(entry))
329
+ return { ok: false, reason: TAMPERED };
330
+ const { runMode } = require('../governance/run-mode');
331
+ const here = runMode(ctx.env, root, ctx.cwd).id;
332
+ if (entry.requesterRun === undefined) {
333
+ return { ok: false, reason: `${(0, screen_safe_1.rowField)(id, 40)} was filed outside a run, so no requester can withdraw it — the operator denies it` };
334
+ }
335
+ if (here !== entry.requesterRun) {
336
+ return { ok: false, reason: `only the run that filed ${(0, screen_safe_1.rowField)(id, 40)} withdraws it: filed by run ${(0, screen_safe_1.rowField)(entry.requesterRun, 60)}; this is ${here ? `run ${(0, screen_safe_1.rowField)(here, 60)}` : 'not a run'}` };
337
+ }
338
+ if (!appendEvent(root, { event: 'withdrawn', id, reason: reason.trim(), run: here, covered: entry.count })) {
339
+ return { ok: false, reason: 'could not write the withdrawal record (queue event) — check write permission on .ax/approvals. Nothing was recorded' };
340
+ }
341
+ return { ok: true };
342
+ }
315
343
  /** Hold with a question — approve/deny later. The agent carries the question to the user. */
316
344
  function holdRequest(root, id, question, actor) {
317
345
  const { entry } = findPending(root, id);
@@ -360,7 +388,7 @@ function outsideInboxFooter(outside, root) {
360
388
  const target = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
361
389
  // `◆` rather than the `◇` the spec sketched: §13 (approve-corpus) admits only the template's own glyphs on a decision
362
390
  // row, and U+25C7 is of ambiguous width while U+25C6 is already furniture of this screen.
363
- return `◆ ${outside} refusal(s) on this machine are outside this inbox (shell/gate refusals) — list them: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --refusals${target} · grant one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --grant <id>${target}`;
391
+ return `◆ ${outside} refusal(s) on this machine are outside this inbox (shell/gate refusals) — list them: ${(0, npx_bin_1.holmesKitCommand)(root)} approve --refusals${target} · grant one: ${(0, npx_bin_1.holmesKitCommand)(root)} approve --grant <id>${target}`;
364
392
  }
365
393
  function renderPending(state, view, outside, root) {
366
394
  const withFooter = (lines) => {
@@ -390,6 +418,8 @@ function renderPending(state, view, outside, root) {
390
418
  // was blocked on). Round-1 forged two extra rows and hid the real ones behind an ANSI conceal,
391
419
  // and the operator granted a `curl … | sh` they never saw. The template owns the line structure.
392
420
  lines.push(`[${i + 1}] ${subjectCells(`[${i + 1}] `, p)}`);
421
+ if (p.title)
422
+ lines.push(` title: ${(0, screen_safe_1.rowField)(p.title, screen_safe_1.ROW_COLS)}`); // @implements A-SPEC-770.12
393
423
  lines.push(` reason: ${(0, screen_safe_1.rowField)(p.why, screen_safe_1.ROW_COLS)}`);
394
424
  // Round-6: this row composed THREE separately-budgeted fields plus twenty columns of template,
395
425
  // and round-5's whole-line accounting only covered the line PREFIXES. Measured at 117 columns
@@ -500,7 +530,7 @@ function renderRefusals(refusals, limit = 20, root) {
500
530
  // @implements A-SPEC-770.1 — `--grant <id>`: the positional form this line named since 2026-09-06 is refused.
501
531
  // @implements A-SPEC-770.2 — and the workspace whose log this screen read, when the caller knows it.
502
532
  const target = root === undefined ? '' : ` --target ${/\s/.test(root) ? `"${root}"` : root}`;
503
- lines.push('', `decide one: ${(0, npx_bin_1.npxBin)()} holmes-kit approve --grant <id>${target}`);
533
+ lines.push('', `decide one: ${(0, npx_bin_1.holmesKitCommand)(root)} approve --grant <id>${target}`);
504
534
  return lines.join('\n');
505
535
  }
506
536
  function renderNonTtyHint(state) {
@@ -40,8 +40,14 @@ export declare function isClaudeEvent(name: string): boolean;
40
40
  * root — the nearest `.git` directory's checkout, or a `.git` file's main checkout (its `commondir` named `.git`) — when it is
41
41
  * neither the target nor the home directory and, on POSIX, it, its `.git` and its `.claude` (if any) belong to this user. A
42
42
  * root's `disableAllHooks` read PASS from a monorepo package and a linked worktree (measured). Network paths are not followed.
43
+ *
44
+ * @implements A-SPEC-251.3 — the owner check is POSIX's only: with no uid (win32 has no `geteuid`/`getuid`) the root is still
45
+ * read. Returning null there left a root `disableAllHooks` unread on Windows and doctor read PASS (measured 2026-10-18).
46
+ * `opts.uid` injects either host's answer; null is a host with no owner model.
43
47
  */
44
- export declare function canonicalLocalSettingsPath(target: string, home: string): string | null;
48
+ export declare function canonicalLocalSettingsPath(target: string, home: string, opts?: {
49
+ uid?: number | null;
50
+ }): string | null;
45
51
  /**
46
52
  * Why Claude Code applies NOTHING from this settings file, or null.
47
53
  *
@@ -46,7 +46,7 @@ exports.isAbsoluteScript = isAbsoluteScript;
46
46
  exports.printable = printable;
47
47
  exports.claudeSwitches = claudeSwitches;
48
48
  exports.claudeHookSwitchesCheck = claudeHookSwitchesCheck;
49
- // @implements A-SPEC-251.2
49
+ // @implements A-SPEC-251.2, A-SPEC-251.3
50
50
  // @implements A-SPEC-251.1
51
51
  /**
52
52
  * The settings that switch Claude Code's hooks, or Holmes's tools, off (A-SPEC-251.2 round 30).
@@ -382,11 +382,14 @@ function asClaudeCleans(v) {
382
382
  * root — the nearest `.git` directory's checkout, or a `.git` file's main checkout (its `commondir` named `.git`) — when it is
383
383
  * neither the target nor the home directory and, on POSIX, it, its `.git` and its `.claude` (if any) belong to this user. A
384
384
  * root's `disableAllHooks` read PASS from a monorepo package and a linked worktree (measured). Network paths are not followed.
385
+ *
386
+ * @implements A-SPEC-251.3 — the owner check is POSIX's only: with no uid (win32 has no `geteuid`/`getuid`) the root is still
387
+ * read. Returning null there left a root `disableAllHooks` unread on Windows and doctor read PASS (measured 2026-10-18).
388
+ * `opts.uid` injects either host's answer; null is a host with no owner model.
385
389
  */
386
- function canonicalLocalSettingsPath(target, home) {
387
- const uid = typeof process.geteuid === 'function' ? process.geteuid() : typeof process.getuid === 'function' ? process.getuid() : null;
388
- if (uid === null)
389
- return null;
390
+ function canonicalLocalSettingsPath(target, home, opts = {}) {
391
+ const uid = opts.uid !== undefined ? opts.uid
392
+ : typeof process.geteuid === 'function' ? process.geteuid() : typeof process.getuid === 'function' ? process.getuid() : null;
390
393
  const cwd = localPhysicalRealpath(path.resolve(target)).path;
391
394
  if (cwd === null)
392
395
  return null;
@@ -397,10 +400,11 @@ function canonicalLocalSettingsPath(target, home) {
397
400
  if (rootReal === null || rootReal === cwd || rootReal === (localPhysicalRealpath(home).path ?? home))
398
401
  return null;
399
402
  try {
400
- if (fs.statSync(rootReal).uid !== uid || fs.lstatSync(path.join(rootReal, '.git')).uid !== uid)
403
+ const rootSt = fs.statSync(rootReal), gitSt = fs.lstatSync(path.join(rootReal, '.git'));
404
+ if (uid !== null && (rootSt.uid !== uid || gitSt.uid !== uid))
401
405
  return null;
402
406
  try {
403
- if (fs.lstatSync(path.join(rootReal, '.claude')).uid !== uid)
407
+ if (uid !== null && fs.lstatSync(path.join(rootReal, '.claude')).uid !== uid)
404
408
  return null;
405
409
  }
406
410
  catch (e) {
@@ -41,6 +41,9 @@ export declare const CODEX_TABLE = "mcp_servers.holmes-kit";
41
41
  * Injectable values keep this platform-sensitive path rule deterministic in tests.
42
42
  */
43
43
  export declare function defaultCodexConfigPath(env?: NodeJS.ProcessEnv, home?: string): string;
44
+ /** TOML basic-string escape — backslash and quote, the named whitespace escapes, then any remaining
45
+ * C0 control character as \uXXXX. Built by code point so no literal control byte lives in the source. */
46
+ export declare function tomlStr(s: string): string;
44
47
  /**
45
48
  * Serialize the `[mcp_servers.holmes-kit]` table. `env` is an inline table so the whole entry is ONE
46
49
  * contiguous region (no `[mcp_servers.holmes-kit.env]` child header) — that keeps the merge boundary