@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
@@ -0,0 +1,308 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.HARNESS_UNREADABLE_VERSIONS = exports.VERSION_FIELDS = void 0;
37
+ exports.runVersions = runVersions;
38
+ exports.unreadableVersions = unreadableVersions;
39
+ exports.parseAcceptedVersions = parseAcceptedVersions;
40
+ exports.versionsCheck = versionsCheck;
41
+ exports.runRun = runRun;
42
+ // @implements A-SPEC-774.17, A-SPEC-779, A-SPEC-780, A-SPEC-102.3, A-SPEC-102.5, A-SPEC-781, A-SPEC-774.20, A-SPEC-781.2
43
+ const node_child_process_1 = require("node:child_process");
44
+ const crypto = __importStar(require("node:crypto"));
45
+ const config_1 = require("../config/config");
46
+ const run_refusals_1 = require("../guardrail/run-refusals");
47
+ const run_stages_1 = require("../guardrail/run-stages");
48
+ const fs = __importStar(require("node:fs"));
49
+ const os = __importStar(require("node:os"));
50
+ const path = __importStar(require("node:path"));
51
+ const agent_launch_policy_1 = require("../guardrail/agent-launch-policy");
52
+ const run_records_1 = require("../project/run-records");
53
+ /** @implements A-SPEC-774.18 — the version of the holmes-kit package that holds `file`, walking up to its package.json. */
54
+ function holmesPackageVersionAbove(file) {
55
+ return (0, run_refusals_1.holmesPackageAbove)(file)?.version ?? null;
56
+ }
57
+ /** @implements A-SPEC-774.18 — the holmes-kit version a hook command runs: its first word that names a holmes `.js` path. */
58
+ function hookCommandPackage(command) {
59
+ const words = command.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
60
+ for (const w of words) {
61
+ const word = w.replace(/^["']|["']$/g, '');
62
+ if (/holmes/i.test(word) && /\.js$/.test(word) && path.isAbsolute(word))
63
+ return (0, run_refusals_1.holmesPackageAbove)(word);
64
+ }
65
+ return null;
66
+ }
67
+ /** @implements A-SPEC-102.3 — the worktree's HEAD commit, or null when git cannot say. */
68
+ function worktreeHead(worktree) {
69
+ const { GIT_MAX_BUFFER, GIT_TIMEOUT_MS } = require('../project/bounded-io');
70
+ try {
71
+ const out = (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--verify', '--quiet', 'HEAD'], { cwd: worktree, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: GIT_MAX_BUFFER }).trim();
72
+ return /^[0-9a-f]{40,64}$/.test(out) ? out : null;
73
+ }
74
+ catch {
75
+ return null;
76
+ }
77
+ }
78
+ function hookCommandsIn(text) {
79
+ if (text === null)
80
+ return [];
81
+ const out = [];
82
+ const walk = (v) => {
83
+ if (Array.isArray(v)) {
84
+ v.forEach(walk);
85
+ return;
86
+ }
87
+ if (v && typeof v === 'object') {
88
+ const o = v;
89
+ if (typeof o.command === 'string' && /holmes/i.test(o.command))
90
+ out.push(o.command);
91
+ Object.values(o).forEach(walk);
92
+ }
93
+ };
94
+ try {
95
+ walk(JSON.parse(text));
96
+ }
97
+ catch { /* not JSON: no commands */ }
98
+ return out;
99
+ }
100
+ /** @implements A-SPEC-774.18 — the versions that would govern this run. Unknown is null, never a guess. */
101
+ function runVersions(worktree, engine, deps) {
102
+ const packageRoot = path.resolve(__dirname, '..', '..', '..');
103
+ const { readPackageVersion } = require('./mcp-launcher');
104
+ const { distBuildId } = require('../project/dist-freshness');
105
+ const { holmesWirings } = require('./doctor');
106
+ const { mcpLaunchVersion } = require('./mcp-version');
107
+ const { defaultCodexConfigPath } = require('./codex-toml');
108
+ const home = deps.home ?? os.homedir();
109
+ const label = engine === 'agy' ? 'antigravity' : engine;
110
+ let mcp = null;
111
+ try {
112
+ const wiring = holmesWirings(worktree, deps.codexConfigPath ?? defaultCodexConfigPath()).find((w) => w.label === label);
113
+ if (wiring?.entry) {
114
+ const args = wiring.entry.command === 'node' && wiring.entry.args.length > 0 && !path.isAbsolute(wiring.entry.args[0])
115
+ ? [path.resolve(worktree, wiring.entry.args[0]), ...wiring.entry.args.slice(1)] : wiring.entry.args;
116
+ mcp = mcpLaunchVersion({ command: path.basename(wiring.entry.command), args }, (dir) => holmesPackageVersionAbove(path.join(dir, 'package.json')) ?? undefined);
117
+ }
118
+ }
119
+ catch {
120
+ mcp = null;
121
+ }
122
+ const hookFiles = engine === 'claude'
123
+ ? [path.join(worktree, '.claude', 'settings.json'), path.join(home, '.claude', 'settings.json')]
124
+ : engine === 'codex' ? [path.join(deps.codexHome ?? process.env.CODEX_HOME ?? path.join(home, '.codex'), 'hooks.json')] : [];
125
+ const hookPkg = hookFiles.flatMap((f) => hookCommandsIn(readText(f))).map(hookCommandPackage).find((v) => v !== null) ?? null;
126
+ return {
127
+ cli: deps.cliVersion ?? readPackageVersion(packageRoot) ?? 'unknown',
128
+ cli_build: deps.cliBuild !== undefined ? deps.cliBuild : distBuildId(packageRoot),
129
+ mcp, hook: hookPkg?.version ?? null,
130
+ // @implements A-SPEC-780 — the hook's own build, which the hook compares itself with during the run.
131
+ hook_build: hookPkg ? distBuildId(hookPkg.root) : null,
132
+ };
133
+ }
134
+ /** @implements A-SPEC-774.24 — the version fields, in the order a refusal names them. */
135
+ exports.VERSION_FIELDS = ['cli', 'cli_build', 'mcp', 'hook', 'hook_build'];
136
+ /**
137
+ * @implements A-SPEC-774.24 — the capability table: the version fields run start cannot read for a harness by design.
138
+ * They are exempt without a flag and recorded as exempt; every other unreadable field must be named to be accepted.
139
+ * agy: run start reads no agy hook wiring, so its hook version and build are never known here.
140
+ */
141
+ exports.HARNESS_UNREADABLE_VERSIONS = { claude: [], codex: [], agy: ['hook', 'hook_build'] };
142
+ /** @implements A-SPEC-774.20 — the version fields run start could not read, in a fixed order. */
143
+ function unreadableVersions(v) {
144
+ return [
145
+ ...(v.cli === 'unknown' ? ['cli'] : []),
146
+ ...['cli_build', 'mcp', 'hook', 'hook_build'].filter((k) => v[k] === null),
147
+ ];
148
+ }
149
+ /** @implements A-SPEC-774.24 — `--accept-unknown-versions` names its fields; none, or a name that is no field, is refused. */
150
+ function parseAcceptedVersions(text) {
151
+ const names = text.split(',').map((s) => s.trim()).filter((s) => s !== '');
152
+ if (names.length === 0)
153
+ return { refusal: `--accept-unknown-versions must name the fields it accepts (${exports.VERSION_FIELDS.join(', ')})` };
154
+ const bad = names.filter((n) => !exports.VERSION_FIELDS.includes(n));
155
+ if (bad.length > 0)
156
+ return { refusal: `--accept-unknown-versions: ${bad.join(', ')} is not a version field (${exports.VERSION_FIELDS.join(', ')})` };
157
+ return { fields: [...new Set(names)] };
158
+ }
159
+ /** @implements A-SPEC-774.24 — each unreadable field is exempt by the table, accepted by name, or failing. */
160
+ function sortUnreadable(v, engine, accepted) {
161
+ const unread = unreadableVersions(v);
162
+ const exempt = unread.filter((k) => exports.HARNESS_UNREADABLE_VERSIONS[engine].includes(k));
163
+ const rest = unread.filter((k) => !exempt.includes(k));
164
+ return { exempt, accepted: rest.filter((k) => accepted.includes(k)), failing: rest.filter((k) => !accepted.includes(k)) };
165
+ }
166
+ function versionsCheck(v, engine, accepted) {
167
+ const drift = ['mcp', 'hook'].filter((k) => v[k] !== null && v[k] !== v.cli).map((k) => `${k} ${v[k]}`);
168
+ if (drift.length > 0)
169
+ return { name: 'versions', status: 'fail', detail: `${drift.join(', ')} differ from this CLI ${v.cli} — one build must govern a run; rewire or reinstall` };
170
+ // @implements A-SPEC-774.20 — in run mode an unreadable version blocks and is named; accepting it is on record.
171
+ const s = sortUnreadable(v, engine, accepted);
172
+ const exemptNote = s.exempt.length > 0 ? `; ${s.exempt.join(', ')} exempt for ${engine} by the capability table (recorded)` : '';
173
+ if (s.failing.length > 0) {
174
+ return { name: 'versions', status: 'fail', detail: `cannot read ${s.failing.join(', ')} — a run must pin the builds that govern it; fix the wiring or pass --accept-unknown-versions=${s.failing.join(',')}${exemptNote}` };
175
+ }
176
+ if (s.accepted.length > 0)
177
+ return { name: 'versions', status: 'accepted', detail: `unreadable ${s.accepted.join(', ')} accepted by --accept-unknown-versions (recorded)${exemptNote}` };
178
+ return { name: 'versions', status: 'pass', detail: `the MCP and hook versions equal this CLI ${v.cli}, and every ${s.exempt.length > 0 ? 'other ' : ''}build id was read${exemptNote}` };
179
+ }
180
+ const HEADLESS = { claude: ['claude', '-p'], codex: ['codex', 'exec'], agy: ['agy', '-p'] };
181
+ const USAGE = 'usage: holmes-kit run start --worktree <dir> --engine claude|codex|agy [--engine-arg <a>]... [--accept-unknown-versions <field,...>] [--target <dir>]\n'
182
+ + ' holmes-kit run status [--target <dir>]\n'
183
+ + ' holmes-kit run transition --id <run_id> --to <stage> --key <stop_key> [--why <text>] [--target <dir>]\n'
184
+ + ' holmes-kit run stop --id <run_id> --key <stop_key> [--target <dir>]\n';
185
+ const readText = (f) => { try {
186
+ return fs.readFileSync(f, 'utf8');
187
+ }
188
+ catch {
189
+ return null;
190
+ } };
191
+ const namesHolmes = (t) => t !== null && /holmes/i.test(t);
192
+ /** Whether the engine's wiring in this worktree (and the user's home) would load the Holmes gate. */
193
+ function checks(main, worktree, engine, args, deps) {
194
+ const home = deps.home ?? os.homedir();
195
+ const out = [];
196
+ let wtMain = null;
197
+ try {
198
+ wtMain = fs.statSync(worktree).isDirectory() ? (0, run_records_1.mainCheckoutOf)(worktree) : null;
199
+ }
200
+ catch {
201
+ wtMain = null;
202
+ }
203
+ out.push(wtMain !== null && fs.realpathSync(wtMain) === fs.realpathSync(main)
204
+ ? { name: 'worktree', status: 'pass', detail: `${worktree} is a working tree of ${main}` }
205
+ : { name: 'worktree', status: 'fail', detail: `${worktree} is not a working tree of ${main}` });
206
+ out.push(fs.existsSync(path.join(worktree, '.ax', 'specs'))
207
+ ? { name: 'specs', status: 'pass', detail: '.ax/specs is present' }
208
+ : { name: 'specs', status: 'fail', detail: '.ax/specs is missing in the worktree — the gate would judge an ungoverned tree' });
209
+ const mcp = engine === 'codex' ? namesHolmes(readText(path.join(worktree, '.codex', 'config.toml')))
210
+ : engine === 'claude' ? namesHolmes(readText(path.join(worktree, '.mcp.json')))
211
+ : namesHolmes(readText(path.join(worktree, '.mcp.json'))) || fs.existsSync(path.join(worktree, '.agents'));
212
+ out.push(mcp ? { name: 'mcp', status: 'pass', detail: `the ${engine} MCP wiring in the worktree names holmes-kit` }
213
+ : { name: 'mcp', status: 'fail', detail: `the worktree carries no ${engine} MCP wiring that names holmes-kit` });
214
+ if (engine === 'claude') {
215
+ const hooked = namesHolmes(readText(path.join(worktree, '.claude', 'settings.json'))) || namesHolmes(readText(path.join(home, '.claude', 'settings.json')));
216
+ out.push(hooked ? { name: 'gate', status: 'pass', detail: 'a Holmes hook is wired in the project or user Claude settings' }
217
+ : { name: 'gate', status: 'fail', detail: 'no Holmes hook in <worktree>/.claude/settings.json or ~/.claude/settings.json — the Claude gate would not load' });
218
+ }
219
+ else if (engine === 'codex') {
220
+ const codexHome = deps.codexHome ?? process.env.CODEX_HOME ?? path.join(home, '.codex');
221
+ out.push(namesHolmes(readText(path.join(codexHome, 'hooks.json')))
222
+ ? { name: 'gate', status: 'pass', detail: 'a Holmes hook is wired in $CODEX_HOME/hooks.json' }
223
+ : { name: 'gate', status: 'fail', detail: 'no Holmes hook in $CODEX_HOME/hooks.json — the Codex gate would not load' });
224
+ }
225
+ else {
226
+ out.push({ name: 'gate', status: 'unknown', detail: 'agy hook loading cannot be read from a file here — run holmes-kit doctor --agent agy' });
227
+ }
228
+ const off = args.map((a) => (0, agent_launch_policy_1.gateOffMarker)(a)).find((m) => m !== null) ?? (0, agent_launch_policy_1.gateOffMarker)(args.join(' '));
229
+ out.push(off === null ? { name: 'engine-args', status: 'pass', detail: 'no engine argument switches the gate off' }
230
+ : { name: 'engine-args', status: 'fail', detail: `an engine argument switches the gate off (${off})` });
231
+ return out;
232
+ }
233
+ function runRun(sub, opts, io, deps = {}) {
234
+ const main = (0, run_records_1.mainCheckoutOf)(opts.target ?? process.cwd());
235
+ const random = deps.random ?? ((n) => crypto.randomBytes(n).toString('hex'));
236
+ if (sub === 'status') {
237
+ // @implements A-SPEC-779 — each run's state from its event log: running, awaiting_approval or stopped.
238
+ const cfg = (0, config_1.loadConfig)(main).run;
239
+ io.stdout(`${JSON.stringify({ runs: (0, run_records_1.listRuns)(main).map((r) => ({ run_id: r.run_id, worktree: r.worktree, engine: r.engine, started: r.started,
240
+ versions: r.versions ?? null,
241
+ ...(0, run_refusals_1.runState)(main, r.run_id, { limit: cfg.refusalRepeatLimit, waitMinutes: cfg.approvalWaitMinutes, ...(deps.now ? { now: deps.now } : {}) }),
242
+ // @implements A-SPEC-781 — where the run is in its stage machine.
243
+ stage: (0, run_stages_1.currentStage)(main, r.run_id, (0, config_1.loadConfig)(main).stages) })) }, null, 2)}\n`);
244
+ return 0;
245
+ }
246
+ // @implements A-SPEC-781 — only the holder of the stop key moves a run's stage.
247
+ if (sub === 'transition') {
248
+ if (!opts.id || !opts.to || !opts.key) {
249
+ io.stderr(USAGE);
250
+ return 2;
251
+ }
252
+ const r = (0, run_stages_1.transitionRun)(main, opts.id, opts.to, { key: opts.key, ...(opts.why ? { why: opts.why } : {}), ...(deps.now ? { now: deps.now } : {}) });
253
+ io.stdout(`${JSON.stringify({ run_id: opts.id, ...r })}\n`);
254
+ return r.ok ? 0 : 3;
255
+ }
256
+ if (sub === 'stop') {
257
+ if (!opts.id) {
258
+ io.stderr(USAGE);
259
+ return 2;
260
+ }
261
+ const result = (0, run_records_1.removeRun)(main, opts.id, opts.key);
262
+ io.stdout(`${JSON.stringify({ ok: result === 'removed', run_id: opts.id, result })}\n`);
263
+ return result === 'removed' ? 0 : result === 'bad-key' ? 3 : 4;
264
+ }
265
+ if (sub !== 'start' || !opts.worktree || !['claude', 'codex', 'agy'].includes(opts.engine ?? '')) {
266
+ io.stderr(USAGE);
267
+ return 2;
268
+ }
269
+ const engine = opts.engine;
270
+ const worktree = path.resolve(opts.worktree);
271
+ const args = opts.engineArgs ?? [];
272
+ const found = checks(main, worktree, engine, args, deps);
273
+ // @implements A-SPEC-774.18 — the builds that would govern the run, pinned before anything is written.
274
+ const versions = runVersions(worktree, engine, deps);
275
+ found.push(versionsCheck(versions, engine, opts.acceptUnknownVersions ?? []));
276
+ if (found.some((c) => c.status === 'fail')) {
277
+ io.stdout(`${JSON.stringify({ ok: false, refused: 'a check failed — the run would not be governed', checks: found, versions }, null, 2)}\n`);
278
+ return 3;
279
+ }
280
+ const now = (deps.now ?? (() => new Date()))();
281
+ const runId = (0, run_records_1.newRunId)(now, () => random(4));
282
+ const stopKey = random(16);
283
+ // The record keeps the fields runMode validates; `versions` rides along (A-SPEC-774.18).
284
+ // @implements A-SPEC-102.3 — and `base`, the worktree's HEAD now: the start of the range the run's review covers.
285
+ const base = worktreeHead(worktree);
286
+ // @implements A-SPEC-774.24 — only the named fields are accepted; the table's exemptions are recorded beside them.
287
+ const { accepted, exempt } = sortUnreadable(versions, engine, opts.acceptUnknownVersions ?? []);
288
+ const rec = {
289
+ run_id: runId, worktree: fs.realpathSync(worktree), sessions: [], engine, started: now.toISOString(), stop_key_sha256: (0, run_records_1.keyHash)(stopKey),
290
+ versions, ...(base ? { base } : {}),
291
+ ...(opts.scope && opts.scope.length > 0 ? { scope: [...opts.scope] } : {}),
292
+ ...(accepted.length > 0 ? { accepted_unknown_versions: accepted } : {}),
293
+ ...(exempt.length > 0 ? { exempt_unknown_versions: exempt } : {}),
294
+ };
295
+ const record = (0, run_records_1.writeRun)(main, rec);
296
+ // @implements A-SPEC-774.20 — the acceptance is in the run's log too, beside every later event of the run.
297
+ if (accepted.length > 0)
298
+ (0, run_refusals_1.appendRunEvent)(main, runId, { ts: now.toISOString(), event: 'versions_accepted', fields: accepted });
299
+ // @implements A-SPEC-781.2 — how this run's stage machine was read, when it was not read as written.
300
+ const stageNotes = (0, config_1.loadConfig)(main).stages.notes;
301
+ if (stageNotes.length > 0)
302
+ (0, run_refusals_1.appendRunEvent)(main, runId, { ts: now.toISOString(), event: 'stages_interpreted', notes: stageNotes });
303
+ io.stdout(`${JSON.stringify({
304
+ ok: true, run_id: runId, worktree, record, env: { HOLMES_RUN_ID: runId }, command: [...HEADLESS[engine], ...args],
305
+ stop_key: stopKey, versions, checks: found, ...(stageNotes.length > 0 ? { stage_notes: stageNotes } : {}),
306
+ }, null, 2)}\n`);
307
+ return 0;
308
+ }
@@ -35,8 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.runtimePlanDigest = runtimePlanDigest;
37
37
  exports.applyApprovedRuntimePlan = applyApprovedRuntimePlan;
38
- // @implements A-SPEC-752, A-SPEC-752.14
38
+ // @implements A-SPEC-752, A-SPEC-752.14, A-SPEC-770.3, A-SPEC-770.6
39
39
  const path = __importStar(require("node:path"));
40
+ const npx_bin_1 = require("../project/npx-bin");
40
41
  const node_crypto_1 = require("node:crypto");
41
42
  const risk_gate_1 = require("../guardrail/risk-gate");
42
43
  const approval_grants_1 = require("../governance/approval-grants");
@@ -82,7 +83,7 @@ function applyApprovedRuntimePlan(root, subject, envApproval, check, apply, appr
82
83
  const id = (0, approval_queue_1.approvalRequestId)(action.kind, target);
83
84
  if (result.reason !== 'written' && result.reason !== 'duplicate')
84
85
  throw new Error(`Cannot queue governance-wiring approval: ${result.reason}; nothing installed`);
85
- throw new Error(`governance-wiring approval required for plan ${subject}; request ${id}. In ${approvalRoot === root ? 'this workspace' : `the workspace ${approvalRoot}`} run holmes-kit approve --list, then holmes-kit approve --grant ${id} and retry the same runtime-binding command. If an old decision remains, revoke it and retry to request the current plan.`);
86
+ throw new Error(`governance-wiring approval required for plan ${subject}; request ${id}. In ${approvalRoot === root ? 'this workspace' : `the workspace ${approvalRoot}`} run ${(0, npx_bin_1.holmesKitCommand)(approvalRoot)} approve --list, then ${(0, npx_bin_1.holmesKitCommand)(approvalRoot)} approve --grant ${id} and retry the same runtime-binding command. If an old decision remains, revoke it and retry to request the current plan.`);
86
87
  };
87
88
  check();
88
89
  if (!resolve())
@@ -1,3 +1,4 @@
1
+ import * as path from 'node:path';
1
2
  import type { RuntimeHarness, RuntimeEntry, RuntimeSelection } from '../runtime/binding';
2
3
  import type { Approval } from '../guardrail/risk-gate';
3
4
  export declare const defaultRuntimeRegistry: () => string;
@@ -17,6 +18,35 @@ export interface RuntimeBindingOptions {
17
18
  /** @implements A-SPEC-752.14 — where the operator runs remove (CLI: cwd); holds the approval of a workspace without `.ax`. */
18
19
  approvalRoot?: string;
19
20
  }
21
+ /**
22
+ * Whether one Antigravity hook command is Holmes's own direct wrapper.
23
+ *
24
+ * @implements A-SPEC-751.8
25
+ * The shape and a literal script name decide exactly as the inline test did before. Only on a win32 host, and only
26
+ * when the literal name does not, the token is read back to its long name: init writes a spaced install root as its
27
+ * 8.3 form, and `%~sI` shortens the file name too (`HOLMES~4.JS`, measured 2026-10-17), so the literal test refused
28
+ * Holmes's own entry and setup wrote nothing. A token a shell would not take literally, or one the resolver cannot
29
+ * read, is not a match — the entry stays a conflict (A-SPEC-751 rule 5). Host and resolver are injectable so either
30
+ * host can assert the other's answers.
31
+ */
32
+ export declare function holmesAgyWrapper(cmd: unknown, opts?: {
33
+ host?: path.PlatformPath;
34
+ realpath?: (p: string) => string;
35
+ }): boolean;
36
+ /**
37
+ * Whether an existing Antigravity command is the canonical dispatcher command `runtimeHookCommand` computes now.
38
+ *
39
+ * @implements A-SPEC-751.9
40
+ * Identical strings always are. On a win32 host only, two space-free two-token commands are also the same when each
41
+ * token resolves to the same long path: `shortPathIfSpaced` shortens only components that exist, so the command a first
42
+ * setup wrote (`…\operator\antigravity-stop.js`, the file not yet made) is not the string the next one computes
43
+ * (`…\operator\ANTIGR~1.JS`, measured 2026-10-18) — and setup refused its own entry while doctor counted none. A token a
44
+ * shell would not take literally, or one the resolver cannot read, makes them different (A-SPEC-751 rule 5 still holds).
45
+ */
46
+ export declare function sameAgyCommand(written: unknown, canonical: string, opts?: {
47
+ host?: path.PlatformPath;
48
+ realpath?: (p: string) => string;
49
+ }): boolean;
20
50
  export declare function runtimeHookCommand(registryPath: string, harness: RuntimeHarness, entry: RuntimeEntry): string;
21
51
  /**
22
52
  * @implements A-SPEC-752.5 — what the receipt records about a file. Claude Code rewrites its own settings file (measured
@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.defaultRuntimeRegistry = void 0;
37
+ exports.holmesAgyWrapper = holmesAgyWrapper;
38
+ exports.sameAgyCommand = sameAgyCommand;
37
39
  exports.runtimeHookCommand = runtimeHookCommand;
38
40
  exports.wiringViewOf = wiringViewOf;
39
41
  exports.codexProjectUntrusted = codexProjectUntrusted;
@@ -43,7 +45,7 @@ exports.codexDuplicateRoutes = codexDuplicateRoutes;
43
45
  exports.runtimeBindingStatus = runtimeBindingStatus;
44
46
  exports.runRuntimeBinding = runRuntimeBinding;
45
47
  exports.trackedWorkspacePaths = trackedWorkspacePaths;
46
- // @implements A-SPEC-769.10, A-SPEC-752.11, A-SPEC-752.12, A-SPEC-752.13, A-SPEC-752.14, A-SPEC-752.15, A-SPEC-752.16, A-SPEC-752.17, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8, A-SPEC-772.1, A-SPEC-772.2, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11
48
+ // @implements A-SPEC-751.8, A-SPEC-751.9, A-SPEC-769.22,A-SPEC-769.10,A-SPEC-752.11,A-SPEC-752.12, A-SPEC-752.13, A-SPEC-752.14, A-SPEC-752.15, A-SPEC-752.16, A-SPEC-752.17, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8, A-SPEC-772.1, A-SPEC-772.2, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-772.12
47
49
  const fs = __importStar(require("node:fs"));
48
50
  const os = __importStar(require("node:os"));
49
51
  const path = __importStar(require("node:path"));
@@ -55,8 +57,10 @@ const hook_process_1 = require("../runtime/hook-process");
55
57
  const runtime_binding_approval_1 = require("./runtime-binding-approval");
56
58
  const codex_toml_1 = require("./codex-toml");
57
59
  const codex_hooks_1 = require("./codex-hooks");
60
+ const write_target_1 = require("../guardrail/write-target");
58
61
  const agents_1 = require("./agents");
59
62
  const heartbeat_1 = require("../hooks/heartbeat");
63
+ const root_1 = require("../project/root");
60
64
  const defaultRuntimeRegistry = () => path.join(os.homedir(), '.holmes', 'runtime', 'bindings.json');
61
65
  exports.defaultRuntimeRegistry = defaultRuntimeRegistry;
62
66
  const digest = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
@@ -98,6 +102,76 @@ function quote(word) {
98
102
  }
99
103
  return `'${word.replace(/'/g, `'\\''`)}'`;
100
104
  }
105
+ /** Holmes's direct Antigravity wrapper as written: one space-free script token after node (A-SPEC-586). */
106
+ const AGY_DIRECT = /^(?:node|[^\s]+[/\\]node(?:\.exe)?) ([^\s]+)$/;
107
+ const AGY_SCRIPT_LITERAL = /^[^\s]+[/\\]bin[/\\]holmes-(?:hook|stop)-antigravity\.js$/;
108
+ const AGY_SCRIPTS = new Set(['holmes-hook-antigravity.js', 'holmes-stop-antigravity.js']);
109
+ /** A token a shell would not run as one literal path. */
110
+ const AGY_TOKEN_UNSAFE = /["'`$;&|<>()]/;
111
+ /**
112
+ * Whether one Antigravity hook command is Holmes's own direct wrapper.
113
+ *
114
+ * @implements A-SPEC-751.8
115
+ * The shape and a literal script name decide exactly as the inline test did before. Only on a win32 host, and only
116
+ * when the literal name does not, the token is read back to its long name: init writes a spaced install root as its
117
+ * 8.3 form, and `%~sI` shortens the file name too (`HOLMES~4.JS`, measured 2026-10-17), so the literal test refused
118
+ * Holmes's own entry and setup wrote nothing. A token a shell would not take literally, or one the resolver cannot
119
+ * read, is not a match — the entry stays a conflict (A-SPEC-751 rule 5). Host and resolver are injectable so either
120
+ * host can assert the other's answers.
121
+ */
122
+ function holmesAgyWrapper(cmd, opts = {}) {
123
+ if (typeof cmd !== 'string')
124
+ return false;
125
+ const m = AGY_DIRECT.exec(cmd);
126
+ if (m === null)
127
+ return false;
128
+ if (AGY_SCRIPT_LITERAL.test(m[1]))
129
+ return true;
130
+ if ((opts.host ?? (0, write_target_1.hostFlavor)()).sep !== '\\' || AGY_TOKEN_UNSAFE.test(m[1]))
131
+ return false;
132
+ let long;
133
+ try {
134
+ long = (opts.realpath ?? fs.realpathSync.native)(m[1]);
135
+ }
136
+ catch {
137
+ return false;
138
+ }
139
+ return path.win32.basename(path.win32.dirname(long)).toLowerCase() === 'bin'
140
+ && AGY_SCRIPTS.has(path.win32.basename(long).toLowerCase());
141
+ }
142
+ const AGY_TWO_TOKENS = /^([^\s]+) ([^\s]+)$/;
143
+ /**
144
+ * Whether an existing Antigravity command is the canonical dispatcher command `runtimeHookCommand` computes now.
145
+ *
146
+ * @implements A-SPEC-751.9
147
+ * Identical strings always are. On a win32 host only, two space-free two-token commands are also the same when each
148
+ * token resolves to the same long path: `shortPathIfSpaced` shortens only components that exist, so the command a first
149
+ * setup wrote (`…\operator\antigravity-stop.js`, the file not yet made) is not the string the next one computes
150
+ * (`…\operator\ANTIGR~1.JS`, measured 2026-10-18) — and setup refused its own entry while doctor counted none. A token a
151
+ * shell would not take literally, or one the resolver cannot read, makes them different (A-SPEC-751 rule 5 still holds).
152
+ */
153
+ function sameAgyCommand(written, canonical, opts = {}) {
154
+ if (typeof written !== 'string')
155
+ return false;
156
+ if (written === canonical)
157
+ return true;
158
+ if ((opts.host ?? (0, write_target_1.hostFlavor)()).sep !== '\\')
159
+ return false;
160
+ const a = AGY_TWO_TOKENS.exec(written);
161
+ const b = AGY_TWO_TOKENS.exec(canonical);
162
+ if (a === null || b === null)
163
+ return false;
164
+ if ([a[1], a[2], b[1], b[2]].some((t) => AGY_TOKEN_UNSAFE.test(t)))
165
+ return false;
166
+ const real = opts.realpath ?? fs.realpathSync.native;
167
+ try {
168
+ const long = (t) => path.win32.normalize(real(t)).toLowerCase();
169
+ return long(a[1]) === long(b[1]) && long(a[2]) === long(b[2]);
170
+ }
171
+ catch {
172
+ return false;
173
+ }
174
+ }
101
175
  function runtimeHookCommand(registryPath, harness, entry) {
102
176
  const file = path.join(path.dirname(registryPath), `${harness}-${entry}.js`);
103
177
  if (harness !== 'antigravity')
@@ -306,7 +380,9 @@ function codexDuplicateRoutes(codexHome, workspace) {
306
380
  if (object(entry) && entry.enabled === false)
307
381
  continue;
308
382
  out.push({ harness: 'codex', event: stateKey, files: [userHooks, wsHooks],
309
- fix: `set enabled = false under [hooks.state."${key}"] in ${configPath} (or remove the ${stateKey} entry from one file) — Holmes runs once per lifecycle` });
383
+ // @implements A-SPEC-769.22 — the key as a TOML basic string: a Windows path's `\U…` raw is a unicode escape, and
384
+ // following the line wrote a config.toml Codex cannot load. Byte-identical for a key with no backslash or quote.
385
+ fix: `set enabled = false under [hooks.state.${(0, codex_toml_1.tomlStr)(key)}] in ${configPath} (or remove the ${stateKey} entry from one file) — Holmes runs once per lifecycle` });
310
386
  }
311
387
  return out;
312
388
  }
@@ -370,14 +446,25 @@ function runtimeBindingStatus(registryPath, workspace, opts) {
370
446
  // @implements A-SPEC-769.8 — reported beside the receipt verdicts; it changes neither `conflicts` nor `router`.
371
447
  const duplicateRoutes = codexDuplicateRoutes(opts?.codexHome ?? path.join(os.homedir(), '.codex'), workspace);
372
448
  // @implements A-SPEC-772.1 — a hook observed running in the selected workspace is reported, per harness.
373
- const beats = (0, heartbeat_1.readHookHeartbeats)(selection.workspaceRoot);
449
+ // @implements A-SPEC-772.12 — read where the kernel writes: the directory holding `.ax`. The selection stops at a
450
+ // nested `.git` (round 8, L1: doctor said observed while status said unverified for the same run).
451
+ const governedRoot = (() => {
452
+ try {
453
+ const r = (0, root_1.resolveProjectRoot)(selection.workspaceRoot, { includeGit: false }).root;
454
+ return fs.existsSync(path.join(r, '.ax')) ? r : selection.workspaceRoot;
455
+ }
456
+ catch {
457
+ return selection.workspaceRoot;
458
+ }
459
+ })();
460
+ const beats = (0, heartbeat_1.readHookHeartbeats)(governedRoot);
374
461
  const observed = {};
375
462
  const observedUnrouted = {};
376
463
  const observedOther = {};
377
464
  const wiringEnv = { ...process.env, ...(opts?.codexHome ? { CODEX_HOME: opts.codexHome } : {}) };
378
465
  const now = Date.now();
379
466
  for (const harness of agents_1.AGENTS) {
380
- const wiring = (0, heartbeat_1.hookWiringFiles)(selection.workspaceRoot, harness, wiringEnv);
467
+ const wiring = (0, heartbeat_1.hookWiringFiles)(governedRoot, harness, wiringEnv);
381
468
  // @implements A-SPEC-772.7 — each event on its own: a routed PreToolUse is not hidden by a later Stop of another mode.
382
469
  for (const event of ['pre-tool-use', 'stop']) {
383
470
  const beat = beats[harness][event];
@@ -395,8 +482,12 @@ function runtimeBindingStatus(registryPath, workspace, opts) {
395
482
  if (event === 'pre-tool-use' && o.mode === selection.mode && o.buildId === selection.buildId)
396
483
  latest(observed);
397
484
  // @implements A-SPEC-772.7 — a run without routing evidence is reported apart from activation.
398
- else if (o.mode === 'unknown')
399
- latest(observedUnrouted);
485
+ // @implements A-SPEC-772.12 — each such event by name, PreToolUse first (round 8, L2: the latest time alone hid
486
+ // whether the gate itself ran unrouted).
487
+ else if (o.mode === 'unknown') {
488
+ const entry = `${event} at ${o.at} (build ${o.buildId})`;
489
+ observedUnrouted[harness] = observedUnrouted[harness] ? `${observedUnrouted[harness]}; ${entry}` : entry;
490
+ }
400
491
  // @implements A-SPEC-772.10 — every other observation (a Stop of this selection, another build or mode) is named.
401
492
  // @implements A-SPEC-772.11 — each uncounted event, PreToolUse first (events loop in that order); the latest
402
493
  // alone hid an other-build PreToolUse behind the turn-end Stop (round 7).
@@ -696,23 +787,37 @@ function runRuntimeBinding(opts) {
696
787
  throw new Error(`Invalid Antigravity hook group: ${file}`);
697
788
  for (const h of entries) {
698
789
  const cmd = h?.command;
699
- const direct = typeof cmd === 'string' && /^(?:node|[^\s]+[/\\]node(?:\.exe)?) [^\s]+[/\\]bin[/\\]holmes-(?:hook|stop)-antigravity\.js$/.test(cmd);
700
- if (!direct && cmd !== command('antigravity', event === 'PreToolUse' ? 'pre-tool-use' : 'stop'))
701
- throw new Error(`Unknown Antigravity wrapper requires explicit migration: ${file}`);
790
+ const direct = holmesAgyWrapper(cmd); // A-SPEC-751.8
791
+ if (!direct && !sameAgyCommand(cmd, command('antigravity', event === 'PreToolUse' ? 'pre-tool-use' : 'stop')))
792
+ throw new Error(`Unknown Antigravity wrapper requires explicit migration: ${file}`); // A-SPEC-751.9
702
793
  }
703
794
  }
704
795
  }
796
+ // @implements A-SPEC-751.9 — an entry that already names the canonical dispatcher keeps its spelling: a Windows short
797
+ // path is spelled differently once the file exists while it still names the same file, and rewriting it to today's
798
+ // spelling made every second setup plan a change.
799
+ const spelled = (event, entry) => {
800
+ const canonical = command('antigravity', entry);
801
+ for (const group of Array.isArray(old?.[event]) ? old[event] : []) {
802
+ for (const h of event === 'PreToolUse' ? (Array.isArray(group?.hooks) ? group.hooks : []) : [group]) {
803
+ const written = h?.command;
804
+ if (typeof written === 'string' && written !== canonical && sameAgyCommand(written, canonical))
805
+ return written;
806
+ }
807
+ }
808
+ return canonical;
809
+ };
705
810
  // Preserve the native enable switch and fields other than our lifecycle entries.
706
811
  const ours = { ...old };
707
812
  if (activate.has('antigravity') && primary.size)
708
813
  ours.enabled = true;
709
814
  if (primary.has('PreToolUse')) {
710
- ours.PreToolUse = !activate.has('antigravity') && Array.isArray(old?.PreToolUse) && old.PreToolUse.length === 0 ? [] : [{ matcher: '*', hooks: [{ command: command('antigravity', 'pre-tool-use') }] }];
815
+ ours.PreToolUse = !activate.has('antigravity') && Array.isArray(old?.PreToolUse) && old.PreToolUse.length === 0 ? [] : [{ matcher: '*', hooks: [{ command: spelled('PreToolUse', 'pre-tool-use') }] }];
711
816
  }
712
817
  else if (!(Array.isArray(old?.PreToolUse) && old.PreToolUse.length === 0))
713
818
  delete ours.PreToolUse;
714
819
  if (primary.has('Stop'))
715
- ours.Stop = !activate.has('antigravity') && Array.isArray(old?.Stop) && old.Stop.length === 0 ? [] : [{ command: command('antigravity', 'stop'), timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS }]; // A-SPEC-769.10
820
+ ours.Stop = !activate.has('antigravity') && Array.isArray(old?.Stop) && old.Stop.length === 0 ? [] : [{ command: spelled('Stop', 'stop'), timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS }]; // A-SPEC-769.10
716
821
  else if (!(Array.isArray(old?.Stop) && old.Stop.length === 0))
717
822
  delete ours.Stop;
718
823
  add(file, json({ ...doc, 'holmes-kit': ours }));
@@ -0,0 +1,12 @@
1
+ /**
2
+ * @implements A-SPEC-773 — `holmes-kit scratch [--new <label>]`: print the Holmes scratch root, or make a fresh
3
+ * subdirectory under it and print that. A subdirectory is the agent's own temporary work: the gate lets a recursive
4
+ * rm of it through, in every harness. Exit 1 with the reason when the root is not this user's own 0700 directory.
5
+ */
6
+ export declare function runScratch(opts: {
7
+ label?: string;
8
+ tmpdir?: string;
9
+ }, io: {
10
+ stdout: (t: string) => void;
11
+ stderr: (t: string) => void;
12
+ }): number;
@@ -0,0 +1,20 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.runScratch = runScratch;
4
+ // @implements A-SPEC-773
5
+ const scratch_root_1 = require("../project/scratch-root");
6
+ /**
7
+ * @implements A-SPEC-773 — `holmes-kit scratch [--new <label>]`: print the Holmes scratch root, or make a fresh
8
+ * subdirectory under it and print that. A subdirectory is the agent's own temporary work: the gate lets a recursive
9
+ * rm of it through, in every harness. Exit 1 with the reason when the root is not this user's own 0700 directory.
10
+ */
11
+ function runScratch(opts, io) {
12
+ try {
13
+ io.stdout(`${opts.label === undefined ? (0, scratch_root_1.ensureScratchRoot)(opts.tmpdir) : (0, scratch_root_1.newScratchDir)(opts.label, opts.tmpdir)}\n`);
14
+ return 0;
15
+ }
16
+ catch (e) {
17
+ io.stderr(`holmes-kit scratch: ${e.message}\n`);
18
+ return 1;
19
+ }
20
+ }
@@ -49,6 +49,22 @@ export declare function foldsCase(dir: string): boolean;
49
49
  * the platform and the uid, so it belongs in the same choice.
50
50
  */
51
51
  export declare function posixOnlyWithCommand(reason: string, command: string, platform?: string, uid?: number | undefined, lookup?: (command: string) => boolean): typeof it | typeof it.skip;
52
+ /**
53
+ * @implements A-SPEC-220.4
54
+ * A path as ONE Bash word. A Windows temp path holds backslashes (Bash escapes) and may hold a space (a word break), so
55
+ * a fixture that interpolates it unquoted is read, correctly, as other words; single quotes keep the native spelling.
56
+ */
57
+ export declare function bashWord(p: string): string;
58
+ /**
59
+ * @implements A-SPEC-220.4
60
+ * Remove a directory a child process ran in. Windows holds such a directory for a moment after the process has gone;
61
+ * `fs.rmSync`'s own `maxRetries` did not cover it and a retry of the whole call did (A-SPEC-698, measured 2026-09-20).
62
+ * Bounded: past `ms` the last error is thrown, so a genuine failure is not swallowed.
63
+ */
64
+ export declare function removeWhenReleased(dir: string, ms?: number, remove?: (dir: string, opts: {
65
+ recursive: true;
66
+ force: true;
67
+ }) => void): Promise<void>;
52
68
  /**
53
69
  * @implements A-SPEC-255
54
70
  * The mirror of `posixOnly`: a test whose SUBJECT only exists on Windows.