@holmes-lab/holmes-kit 0.35.25 → 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 (125) hide show
  1. package/CHANGELOG.md +298 -0
  2. package/README.md +3 -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 +31 -1
  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 +25 -1
  13. package/dist/holmes/cli/doctor.js +153 -7
  14. package/dist/holmes/cli/index.js +99 -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.d.ts +30 -0
  27. package/dist/holmes/cli/runtime-binding.js +96 -7
  28. package/dist/holmes/cli/test-platform.d.ts +16 -0
  29. package/dist/holmes/cli/test-platform.js +31 -1
  30. package/dist/holmes/config/config.d.ts +49 -0
  31. package/dist/holmes/config/config.js +146 -3
  32. package/dist/holmes/config/project-caps.d.ts +21 -0
  33. package/dist/holmes/config/project-caps.js +114 -0
  34. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  35. package/dist/holmes/governance/approval-queue.js +48 -6
  36. package/dist/holmes/governance/autonomy.d.ts +6 -0
  37. package/dist/holmes/governance/autonomy.js +21 -0
  38. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  39. package/dist/holmes/governance/push-gate-runner.js +49 -1
  40. package/dist/holmes/governance/replica-id.d.ts +9 -0
  41. package/dist/holmes/governance/replica-id.js +44 -7
  42. package/dist/holmes/governance/role-policy.d.ts +41 -1
  43. package/dist/holmes/governance/role-policy.js +137 -20
  44. package/dist/holmes/governance/run-mode.d.ts +14 -0
  45. package/dist/holmes/governance/run-mode.js +120 -0
  46. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  47. package/dist/holmes/governance/tool-actions.js +121 -0
  48. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  49. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  50. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  51. package/dist/holmes/guardrail/classification-mode.js +135 -0
  52. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  53. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  54. package/dist/holmes/guardrail/phase.d.ts +2 -1
  55. package/dist/holmes/guardrail/phase.js +22 -8
  56. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  57. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  58. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  59. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  60. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  61. package/dist/holmes/guardrail/risk-classifier.js +242 -26
  62. package/dist/holmes/guardrail/risk-types.d.ts +15 -0
  63. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  64. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  65. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  66. package/dist/holmes/guardrail/run-refusals.js +348 -0
  67. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  68. package/dist/holmes/guardrail/run-stages.js +188 -0
  69. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  70. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  71. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  72. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  73. package/dist/holmes/guardrail/shell-words.js +7 -7
  74. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  75. package/dist/holmes/guardrail/write-target.js +118 -16
  76. package/dist/holmes/hooks/pre-tool-use.d.ts +35 -1
  77. package/dist/holmes/hooks/pre-tool-use.js +702 -81
  78. package/dist/holmes/hooks/session-start.js +5 -3
  79. package/dist/holmes/hooks/stop.d.ts +32 -0
  80. package/dist/holmes/hooks/stop.js +129 -4
  81. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  82. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  83. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  84. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  85. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  86. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  87. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  88. package/dist/holmes/mcp/handlers/spec-approval.js +54 -8
  89. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  90. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  91. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  92. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  93. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  94. package/dist/holmes/mcp/handlers.d.ts +2 -3
  95. package/dist/holmes/mcp/handlers.js +22 -2
  96. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  97. package/dist/holmes/mcp/harness-attestation.js +3 -1
  98. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  99. package/dist/holmes/mcp/operator-recovery.js +4 -3
  100. package/dist/holmes/mcp/server.js +9 -0
  101. package/dist/holmes/mcp/tool-schemas.js +6 -3
  102. package/dist/holmes/project/root.js +6 -1
  103. package/dist/holmes/project/run-records.d.ts +17 -0
  104. package/dist/holmes/project/run-records.js +126 -0
  105. package/dist/holmes/review/mrp.d.ts +35 -0
  106. package/dist/holmes/review/mrp.js +119 -0
  107. package/dist/holmes/review/verdicts.d.ts +117 -0
  108. package/dist/holmes/review/verdicts.js +345 -0
  109. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  110. package/dist/holmes/semantic/cloud-usage.js +106 -0
  111. package/dist/holmes/semantic/embedder.d.ts +15 -6
  112. package/dist/holmes/semantic/embedder.js +84 -3
  113. package/dist/holmes/semantic/local-model.d.ts +21 -2
  114. package/dist/holmes/semantic/local-model.js +14 -3
  115. package/dist/holmes/semantic/tier.d.ts +25 -0
  116. package/dist/holmes/semantic/tier.js +86 -1
  117. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  118. package/dist/holmes/semantic/vector-cache.js +4 -1
  119. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  120. package/dist/holmes/spec/approval-blockers.js +70 -2
  121. package/dist/holmes/spec/renumber.d.ts +1 -1
  122. package/dist/holmes/spec/renumber.js +5 -2
  123. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  124. package/dist/holmes/spec/transition-policy.js +17 -2
  125. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,304 @@ 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
+
10
308
  ## [0.35.25] - 2026-10-17
11
309
 
12
310
  Upgrading:
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
- **444/446** source files (99.5%) trace to an approved spec · **835/900** approved A-SPECs (92.7%) are anchored from code.
13
- Measured at `a36f0d1b502f` (specs `sha256:d41ff5dd491a`) — 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,6 +22,7 @@ Measured at `a36f0d1b502f` (specs `sha256:d41ff5dd491a`) — 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
 
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.
27
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.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- e7fd416c-mvcf1aig
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, A-SPEC-770.3, A-SPEC-770.6
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");
@@ -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);
@@ -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
@@ -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
@@ -40,6 +40,7 @@ exports.readCodexConfigBytes = readCodexConfigBytes;
40
40
  exports.codexConfigLoadProblem = codexConfigLoadProblem;
41
41
  exports.codexConfigWriteProblem = codexConfigWriteProblem;
42
42
  exports.defaultCodexConfigPath = defaultCodexConfigPath;
43
+ exports.tomlStr = tomlStr;
43
44
  exports.codexMcpBlock = codexMcpBlock;
44
45
  exports.mergeCodexToml = mergeCodexToml;
45
46
  exports.removeCodexToml = removeCodexToml;
@@ -49,7 +50,7 @@ exports.mentionsHolmes = mentionsHolmes;
49
50
  exports.unownedHolmesShape = unownedHolmesShape;
50
51
  exports.readCodexFixedSpecs = readCodexFixedSpecs;
51
52
  exports.invalidTomlEscape = invalidTomlEscape;
52
- // @implements A-SPEC-733, A-SPEC-731, A-SPEC-721
53
+ // @implements A-SPEC-733, A-SPEC-731, A-SPEC-721, A-SPEC-769.22
53
54
  // @implements A-SPEC-266
54
55
  // Codex reads default MCP servers from `$CODEX_HOME/config.toml` (normally
55
56
  // `~/.codex/config.toml`), not from a repository-local `.codex/config.toml`. This module owns only
@@ -210,6 +210,17 @@ export declare function wiringSpawnCheck(command: string, args: string[], timeou
210
210
  * over as it was, the server's supervisor (`HOLMES_MCP_AUTORELOAD=1`) started the `node` the workspace had put on PATH.
211
211
  */
212
212
  export declare function mcpProbeEnv(env: NodeJS.ProcessEnv, target: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
213
+ /**
214
+ * @implements A-SPEC-182.3 — approved specs whose ancestor chain (direct parents included) holds a spec that is not
215
+ * approved: a WARN with the count and the ancestors that hold most of them, or null on a clean store. Measured here on
216
+ * 2026-10-18: 28 (REQ-102 13, REQ-125 11, H-SPEC-100 4).
217
+ */
218
+ export declare function sealedUnderUnsealedAncestorCheck(target: string): Check | null;
219
+ /**
220
+ * @implements A-SPEC-781.2 — how the run stage machine in `ax.config.json` was read: a WARN naming the fallback or the
221
+ * deny entries filled in, or null when it was read as written (no line, so a clean project's doctor is unchanged).
222
+ */
223
+ export declare function stageMachineCheck(target: string): Check | null;
213
224
  /**
214
225
  * Push-gate presence, diagnosed only where it applies: a repo that opted into governance (.ax)
215
226
  * AND has git. Absence or a hook without our signature is a WARN carrying the install command —
@@ -306,6 +317,15 @@ export declare function formatChecks(checks: Check[]): string;
306
317
  * target is told that the shared file lacks a Holmes entry.
307
318
  */
308
319
  export declare function codexWiredTarget(target: string): boolean;
320
+ /** The Holmes wirings of the three harnesses, read the way the handshake reads them (nothing is started). */
321
+ export declare function holmesWirings(target: string, codexConfigPath: string): Array<{
322
+ label: string;
323
+ file: string;
324
+ entry: {
325
+ command: string;
326
+ args: string[];
327
+ } | null;
328
+ }>;
309
329
  /**
310
330
  * @implements A-SPEC-251.2 (0.31.0) — each harness whose Holmes wiring runs npx gets a WARN: npx runs npm in every
311
331
  * session workspace, and that workspace's .npmrc (node-options, registry) and node_modules replaced the server
@@ -373,8 +393,12 @@ export declare function wiringHandshakeChecks(target: string, codexConfigPath?:
373
393
  * user decides the trade with numbers rather than adjectives.
374
394
  */
375
395
  export declare function semanticCoverageCheck(root: string, tier: SemanticTier): Check | null;
396
+ /**
397
+ * @implements A-SPEC-476.1 — the tier row names the project's cap: a key it withheld (by source, never the value) and the
398
+ * cap that applied; a cap that could not be read is FAIL, because the tier is none until it is fixed.
399
+ */
376
400
  export declare function semanticTierVerdict(t: SemanticTier): {
377
- level: 'PASS' | 'WARN';
401
+ level: 'PASS' | 'WARN' | 'FAIL';
378
402
  detail: string;
379
403
  fix?: string;
380
404
  };