@holmes-lab/holmes-kit 0.35.25 → 0.36.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/CHANGELOG.md +346 -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 +141 -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/adapters/antigravity.d.ts +1 -1
  77. package/dist/holmes/hooks/adapters/antigravity.js +6 -2
  78. package/dist/holmes/hooks/pre-tool-use.d.ts +55 -2
  79. package/dist/holmes/hooks/pre-tool-use.js +749 -89
  80. package/dist/holmes/hooks/session-start.js +5 -3
  81. package/dist/holmes/hooks/stop.d.ts +32 -0
  82. package/dist/holmes/hooks/stop.js +129 -4
  83. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  84. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  85. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  86. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  87. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  88. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  89. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  90. package/dist/holmes/mcp/handlers/spec-approval.js +54 -8
  91. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  92. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  93. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  94. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  95. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  96. package/dist/holmes/mcp/handlers.d.ts +2 -3
  97. package/dist/holmes/mcp/handlers.js +22 -2
  98. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  99. package/dist/holmes/mcp/harness-attestation.js +3 -1
  100. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  101. package/dist/holmes/mcp/operator-recovery.js +4 -3
  102. package/dist/holmes/mcp/server.js +9 -0
  103. package/dist/holmes/mcp/tool-schemas.js +6 -3
  104. package/dist/holmes/project/root.js +6 -1
  105. package/dist/holmes/project/run-records.d.ts +17 -0
  106. package/dist/holmes/project/run-records.js +126 -0
  107. package/dist/holmes/review/mrp.d.ts +35 -0
  108. package/dist/holmes/review/mrp.js +119 -0
  109. package/dist/holmes/review/verdicts.d.ts +117 -0
  110. package/dist/holmes/review/verdicts.js +345 -0
  111. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  112. package/dist/holmes/semantic/cloud-usage.js +106 -0
  113. package/dist/holmes/semantic/embedder.d.ts +15 -6
  114. package/dist/holmes/semantic/embedder.js +84 -3
  115. package/dist/holmes/semantic/local-model.d.ts +21 -2
  116. package/dist/holmes/semantic/local-model.js +14 -3
  117. package/dist/holmes/semantic/tier.d.ts +25 -0
  118. package/dist/holmes/semantic/tier.js +86 -1
  119. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  120. package/dist/holmes/semantic/vector-cache.js +4 -1
  121. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  122. package/dist/holmes/spec/approval-blockers.js +70 -2
  123. package/dist/holmes/spec/renumber.d.ts +1 -1
  124. package/dist/holmes/spec/renumber.js +5 -2
  125. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  126. package/dist/holmes/spec/transition-policy.js +17 -2
  127. 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
+ }
@@ -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, A-SPEC-772.12
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,6 +57,7 @@ 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");
60
63
  const root_1 = require("../project/root");
@@ -99,6 +102,76 @@ function quote(word) {
99
102
  }
100
103
  return `'${word.replace(/'/g, `'\\''`)}'`;
101
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
+ }
102
175
  function runtimeHookCommand(registryPath, harness, entry) {
103
176
  const file = path.join(path.dirname(registryPath), `${harness}-${entry}.js`);
104
177
  if (harness !== 'antigravity')
@@ -307,7 +380,9 @@ function codexDuplicateRoutes(codexHome, workspace) {
307
380
  if (object(entry) && entry.enabled === false)
308
381
  continue;
309
382
  out.push({ harness: 'codex', event: stateKey, files: [userHooks, wsHooks],
310
- 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` });
311
386
  }
312
387
  return out;
313
388
  }
@@ -712,23 +787,37 @@ function runRuntimeBinding(opts) {
712
787
  throw new Error(`Invalid Antigravity hook group: ${file}`);
713
788
  for (const h of entries) {
714
789
  const cmd = h?.command;
715
- const direct = typeof cmd === 'string' && /^(?:node|[^\s]+[/\\]node(?:\.exe)?) [^\s]+[/\\]bin[/\\]holmes-(?:hook|stop)-antigravity\.js$/.test(cmd);
716
- if (!direct && cmd !== command('antigravity', event === 'PreToolUse' ? 'pre-tool-use' : 'stop'))
717
- 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
718
793
  }
719
794
  }
720
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
+ };
721
810
  // Preserve the native enable switch and fields other than our lifecycle entries.
722
811
  const ours = { ...old };
723
812
  if (activate.has('antigravity') && primary.size)
724
813
  ours.enabled = true;
725
814
  if (primary.has('PreToolUse')) {
726
- 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') }] }];
727
816
  }
728
817
  else if (!(Array.isArray(old?.PreToolUse) && old.PreToolUse.length === 0))
729
818
  delete ours.PreToolUse;
730
819
  if (primary.has('Stop'))
731
- 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
732
821
  else if (!(Array.isArray(old?.Stop) && old.Stop.length === 0))
733
822
  delete ours.Stop;
734
823
  add(file, json({ ...doc, 'holmes-kit': ours }));
@@ -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.
@@ -37,11 +37,13 @@ exports.posixOnly = posixOnly;
37
37
  exports.posixOnlyNonRoot = posixOnlyNonRoot;
38
38
  exports.foldsCase = foldsCase;
39
39
  exports.posixOnlyWithCommand = posixOnlyWithCommand;
40
+ exports.bashWord = bashWord;
41
+ exports.removeWhenReleased = removeWhenReleased;
40
42
  exports.win32Only = win32Only;
41
43
  const fs = __importStar(require("node:fs"));
42
44
  const path = __importStar(require("node:path"));
43
45
  const node_crypto_1 = require("node:crypto");
44
- // @implements A-SPEC-220.3
46
+ // @implements A-SPEC-220.3, A-SPEC-220.4
45
47
  // @implements A-SPEC-597
46
48
  /**
47
49
  * A test that cannot run here says so, instead of returning early and being counted as a pass.
@@ -145,6 +147,34 @@ function posixOnlyWithCommand(reason, command, platform = process.platform, uid
145
147
  const base = posixOnlyNonRoot(reason, platform, uid); // reason is validated here, before anything else
146
148
  return lookup(command) ? base : it.skip;
147
149
  }
150
+ /**
151
+ * @implements A-SPEC-220.4
152
+ * A path as ONE Bash word. A Windows temp path holds backslashes (Bash escapes) and may hold a space (a word break), so
153
+ * a fixture that interpolates it unquoted is read, correctly, as other words; single quotes keep the native spelling.
154
+ */
155
+ function bashWord(p) {
156
+ return `'${p.replace(/'/g, `'\\''`)}'`;
157
+ }
158
+ /**
159
+ * @implements A-SPEC-220.4
160
+ * Remove a directory a child process ran in. Windows holds such a directory for a moment after the process has gone;
161
+ * `fs.rmSync`'s own `maxRetries` did not cover it and a retry of the whole call did (A-SPEC-698, measured 2026-09-20).
162
+ * Bounded: past `ms` the last error is thrown, so a genuine failure is not swallowed.
163
+ */
164
+ async function removeWhenReleased(dir, ms = 10000, remove = fs.rmSync) {
165
+ const t0 = Date.now();
166
+ for (;;) {
167
+ try {
168
+ remove(dir, { recursive: true, force: true });
169
+ return;
170
+ }
171
+ catch (e) {
172
+ if (Date.now() - t0 > ms)
173
+ throw e;
174
+ await new Promise((res) => setTimeout(res, 100));
175
+ }
176
+ }
177
+ }
148
178
  /**
149
179
  * @implements A-SPEC-255
150
180
  * The mirror of `posixOnly`: a test whose SUBJECT only exists on Windows.
@@ -36,6 +36,55 @@ export interface AxConfig {
36
36
  */
37
37
  cycleIgnore: string[];
38
38
  };
39
+ /**
40
+ * @implements A-SPEC-775.1
41
+ * `strict` is the owner's opt-in to the run-mode classification outside a run (the supervisor's
42
+ * `strict_classification`): nested test folders narrow and unclassified writes off the safe list are code.
43
+ * `testDirs` are folders the owner declares as test folders, in every mode.
44
+ */
45
+ classification: {
46
+ strict: boolean;
47
+ testDirs: string[];
48
+ };
49
+ /**
50
+ * @implements A-SPEC-532.6
51
+ * The owner's ceiling on automatic approval (autonomous and delegated seals). It only narrows the grader; `default`
52
+ * when absent, `off` when malformed — a ceiling must never fail toward wider.
53
+ */
54
+ autonomy: {
55
+ ceiling: AutonomyCeiling;
56
+ };
57
+ /**
58
+ * @implements A-SPEC-778
59
+ * In a run, a refusal code repeated this many times stops the run. An integer from 1 to 1000; anything else is 5.
60
+ */
61
+ run: {
62
+ refusalRepeatLimit: number;
63
+ approvalWaitMinutes: number;
64
+ };
65
+ /** @implements A-SPEC-781 — a run's stage machine: the stages, the allowed edges, and the stages that need review. */
66
+ stages: StageMachine;
67
+ }
68
+ /** @implements A-SPEC-781 */
69
+ /** @implements A-SPEC-781.1 — `deny`: per stage, the classifier actions the gate refuses in a run at that stage. */
70
+ /**
71
+ * @implements A-SPEC-781.2 — `conditions`: per edge `from->to`, the checks a transition must pass; `notes`: how the
72
+ * declaration was read (a fallback, a filled-in deny), for the run log and doctor.
73
+ */
74
+ export interface StageMachine {
75
+ order: string[];
76
+ transitions: Record<string, string[]>;
77
+ reviewed: string[];
78
+ deny: Record<string, string[]>;
79
+ conditions: Record<string, string[]>;
80
+ notes: string[];
39
81
  }
82
+ export declare const DEFAULT_STAGES: StageMachine;
83
+ /** @implements A-SPEC-778 */
84
+ export declare const RUN_REFUSAL_LIMIT_DEFAULT = 5;
85
+ /** @implements A-SPEC-779 — how long a run may wait for an operator's decision before it stops. */
86
+ export declare const RUN_APPROVAL_WAIT_DEFAULT = 60;
87
+ /** @implements A-SPEC-532.6 — narrowest first. */
88
+ export type AutonomyCeiling = 'off' | 'tests' | 'no-gate' | 'default';
40
89
  export declare const DEFAULT_CONFIG: AxConfig;
41
90
  export declare function loadConfig(root: string): AxConfig;