@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
@@ -1,9 +1,279 @@
1
1
  "use strict";
2
- // @implements A-SPEC-542.1
3
- // @implements A-SPEC-580
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
+ })();
4
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.runningCli = runningCli;
37
+ exports.binEntryNames = binEntryNames;
38
+ exports.shadowCopy = shadowCopy;
39
+ exports.powershellLiteral = powershellLiteral;
40
+ exports.posixLiteral = posixLiteral;
41
+ exports.holmesKitCommand = holmesKitCommand;
5
42
  exports.npxBin = npxBin;
6
43
  exports.npmBin = npmBin;
44
+ // @implements A-SPEC-542.1
45
+ // @implements A-SPEC-580
46
+ // @implements A-SPEC-770.3, A-SPEC-770.4, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.8, A-SPEC-770.9, A-SPEC-770.10
47
+ const fs = __importStar(require("node:fs"));
48
+ const os = __importStar(require("node:os"));
49
+ const path = __importStar(require("node:path"));
50
+ /** @implements A-SPEC-770.6 — the running package's CLI (src/holmes/project and dist/holmes/project share a depth). */
51
+ function runningCli() {
52
+ const cli = path.resolve(__dirname, '../../..', 'bin', 'holmes-kit.js');
53
+ try {
54
+ return fs.realpathSync.native(cli);
55
+ }
56
+ catch {
57
+ return cli;
58
+ }
59
+ }
60
+ function runningPackageRoot() {
61
+ const root = path.resolve(__dirname, '../../..');
62
+ try {
63
+ return fs.realpathSync.native(root);
64
+ }
65
+ catch {
66
+ return root;
67
+ }
68
+ }
69
+ const realOrNull = (p) => { try {
70
+ return fs.realpathSync.native(p);
71
+ }
72
+ catch {
73
+ return null;
74
+ } };
75
+ /** The package directory that holds `file`: the nearest ancestor with a package.json, never climbing past node_modules. */
76
+ function packageOf(file, real = false) {
77
+ for (let up = path.dirname(file);; up = path.dirname(up)) {
78
+ if (path.basename(up) === 'node_modules' || path.dirname(up) === up)
79
+ return null;
80
+ if (fs.existsSync(path.join(up, 'package.json')))
81
+ return real ? realOrNull(up) : up;
82
+ }
83
+ }
84
+ /**
85
+ * @implements A-SPEC-770.7 — the holmes-kit npx would run from `dir`, when it is not this install; null otherwise.
86
+ * npx walks every ancestor `node_modules/.bin` and takes the first entry that `stat` says is a FILE (a dangling link or
87
+ * a directory is skipped). Round 2 measured npm-on-Windows and pnpm `.bin` entries as shim files, not links: the
88
+ * package is therefore found as `node_modules/{@holmes-lab/holmes-kit,holmes-kit}` beside the `.bin`, and only for a
89
+ * link with neither beside it through the link's target — never past a node_modules boundary (that read the consumer
90
+ * project's own package.json). Not memoized: a copy installed later is seen (the MCP server lives long).
91
+ */
92
+ function binEntryNames(platform = process.platform) {
93
+ // @implements A-SPEC-770.8 — npx runs `.cmd` only on Windows (round 3: a lone .cmd shadowed on POSIX).
94
+ return platform === 'win32' ? ['holmes-kit', 'holmes-kit.cmd'] : ['holmes-kit'];
95
+ }
96
+ /**
97
+ * @implements A-SPEC-770.9 — npx first runs the localPrefix package's OWN bin (npm 11.17 libnpmexec `hasPkgBin`, before
98
+ * the .bin walk): the nearest ancestor holding package.json or node_modules. Round 4: a holmes-kit checkout or fork
99
+ * answered every bare hint issued by the global install.
100
+ */
101
+ /** @implements A-SPEC-770.10 — npx derives localPrefix from the physical cwd (round 5: a symlinked cwd into a fork). */
102
+ const physical = (dir) => realOrNull(path.resolve(dir)) ?? path.resolve(dir);
103
+ const isDir = (p) => { try {
104
+ return fs.statSync(p).isDirectory();
105
+ }
106
+ catch {
107
+ return false;
108
+ } };
109
+ function ownPackageBin(dir, own) {
110
+ for (let at = physical(dir);; at = path.dirname(at)) {
111
+ const pj = path.join(at, 'package.json');
112
+ // @implements A-SPEC-770.10 — npm counts node_modules as a localPrefix marker only when it is a directory.
113
+ if (fs.existsSync(pj) || isDir(path.join(at, 'node_modules'))) {
114
+ let pkg = {};
115
+ // @implements A-SPEC-770.10 — read as pacote normalises it: a BOM, a scoped string-bin name, a `./name` key.
116
+ try {
117
+ pkg = JSON.parse(fs.readFileSync(pj, 'utf8').replace(/^/, ''));
118
+ }
119
+ catch {
120
+ return undefined;
121
+ }
122
+ const declares = (typeof pkg.bin === 'object' && pkg.bin !== null
123
+ && Object.entries(pkg.bin).some(([k, v]) => path.posix.basename(k.replace(/\\/g, '/')) === 'holmes-kit' && typeof v === 'string'))
124
+ || (typeof pkg.bin === 'string' && typeof pkg.name === 'string' && pkg.name.split('/').pop() === 'holmes-kit');
125
+ if (!declares)
126
+ return undefined;
127
+ if (realOrNull(at) === own)
128
+ return null;
129
+ return { link: UNSAFE_DISPLAY.test(pj) ? '(unprintable path)' : pj, packageDir: null, version: safe(String(pkg.version ?? '')) };
130
+ }
131
+ if (path.dirname(at) === at)
132
+ return undefined;
133
+ }
134
+ }
135
+ const safe = (v) => (UNSAFE_DISPLAY.test(v) ? '' : v);
136
+ function shadowCopy(dir, platform = process.platform) {
137
+ const own = runningPackageRoot();
138
+ const first = ownPackageBin(dir, own);
139
+ if (first !== undefined)
140
+ return first;
141
+ const names = binEntryNames(platform);
142
+ for (let at = physical(dir);; at = path.dirname(at)) {
143
+ const nm = path.join(at, 'node_modules');
144
+ for (const name of names) {
145
+ const link = path.join(nm, '.bin', name);
146
+ let isFile = false;
147
+ try {
148
+ isFile = fs.statSync(link).isFile();
149
+ }
150
+ catch {
151
+ isFile = false;
152
+ }
153
+ if (!isFile)
154
+ continue;
155
+ // @implements A-SPEC-770.8 — the ENTRY decides which package runs (round 3: the package beside .bin decided, and a
156
+ // scoped link to this install hid the unscoped 0.1.0 npx actually ran). `lexical` is where the entry points under
157
+ // node_modules; identity compares real paths only.
158
+ let lexical = null;
159
+ let identity = null;
160
+ let isLink = false;
161
+ try {
162
+ isLink = fs.lstatSync(link).isSymbolicLink();
163
+ }
164
+ catch {
165
+ isLink = false;
166
+ }
167
+ if (isLink) {
168
+ let text = '';
169
+ try {
170
+ text = fs.readlinkSync(link);
171
+ lexical = path.resolve(path.dirname(link), text);
172
+ }
173
+ catch {
174
+ lexical = null;
175
+ }
176
+ // @implements A-SPEC-770.9 — `..` after the first segment can cross an intermediate link the lexical fold hides.
177
+ if (text.split(/[\\/]/).slice(1).includes('..'))
178
+ lexical = null;
179
+ const real = realOrNull(link);
180
+ identity = real ? packageOf(real, true) : null;
181
+ }
182
+ else {
183
+ let text = '';
184
+ try {
185
+ const fd = fs.openSync(link, 'r');
186
+ try {
187
+ const buf = Buffer.alloc(4096);
188
+ text = buf.subarray(0, fs.readSync(fd, buf, 0, 4096, 0)).toString('utf8');
189
+ }
190
+ finally {
191
+ fs.closeSync(fd);
192
+ }
193
+ }
194
+ catch {
195
+ text = '';
196
+ }
197
+ // @implements A-SPEC-770.9 — only a path to the package's bin/holmes-kit.js decides (round 4: a comment line,
198
+ // `..` and `.pnpm` captures named other packages); the capture must exist.
199
+ const m = /(?:\$basedir|%~?dp0%?)[\\/]\.\.[\\/]((?:@[^\\/\s"']+[\\/])?[^\\/\s"']+)[\\/]bin[\\/]holmes-kit\.js/.exec(text);
200
+ const captured = m && !['.', '..', '.pnpm'].includes(m[1].split(/[\\/]/)[0]) && !UNSAFE_DISPLAY.test(m[1])
201
+ ? path.join(nm, ...m[1].split(/[\\/]/)) : null;
202
+ if (m && captured === null)
203
+ lexical = null;
204
+ else if (captured !== null)
205
+ lexical = fs.existsSync(captured) ? captured : null;
206
+ else {
207
+ const beside = ['@holmes-lab/holmes-kit', 'holmes-kit'].map((p) => path.join(nm, ...p.split('/'))).filter((p) => fs.existsSync(p));
208
+ lexical = beside.length === 1 ? beside[0] : null;
209
+ }
210
+ identity = lexical ? realOrNull(lexical) : null;
211
+ }
212
+ if (identity !== null && identity === own)
213
+ return null;
214
+ // @implements A-SPEC-770.9 — nothing with a control or bidi character reaches the doctor text.
215
+ const entry = lexical ? nodeModulesEntry(nm, lexical) : null;
216
+ const packageDir = entry !== null && !UNSAFE_DISPLAY.test(entry) ? entry : null;
217
+ let version = '';
218
+ const versionFrom = identity ?? packageDir;
219
+ if (versionFrom) {
220
+ try {
221
+ version = String(JSON.parse(fs.readFileSync(path.join(versionFrom, 'package.json'), 'utf8')).version ?? '');
222
+ }
223
+ catch {
224
+ version = '';
225
+ }
226
+ }
227
+ // @implements A-SPEC-770.10 — the link text is filtered too (A-SPEC-770.9 Behavior 5).
228
+ return { link: UNSAFE_DISPLAY.test(link) ? '(unprintable path)' : link, packageDir, version: safe(version) };
229
+ }
230
+ if (path.dirname(at) === at)
231
+ return null;
232
+ }
233
+ }
234
+ /**
235
+ * @implements A-SPEC-770.8 — the package entry `node_modules/<name>` or `node_modules/@scope/<name>` that `target` lies
236
+ * in, lexically; null outside `nm`, or for `.bin`/`.pnpm` (removing those breaks other packages).
237
+ */
238
+ function nodeModulesEntry(nm, target) {
239
+ const rel = path.relative(nm, target);
240
+ if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
241
+ return null;
242
+ const segs = rel.split(path.sep);
243
+ if (segs[0] === '.bin' || segs[0] === '.pnpm')
244
+ return null;
245
+ if (segs[0].startsWith('@'))
246
+ return segs.length >= 2 ? path.join(nm, segs[0], segs[1]) : null;
247
+ return path.join(nm, segs[0]);
248
+ }
249
+ /** @implements A-SPEC-770.7 — a PowerShell single-quoted literal: PowerShell also treats U+2018–U+201B as quotes. */
250
+ function powershellLiteral(value) {
251
+ return `'${value.replace(/['‘’‚‛]/g, (q) => q + q)}'`;
252
+ }
253
+ function posixLiteral(value) {
254
+ return `'${value.replace(/'/g, `'\\''`)}'`;
255
+ }
256
+ /**
257
+ * @implements A-SPEC-770.3
258
+ * The holmes-kit command an approval hint names, so that the install that issued it is the one that answers. Field
259
+ * incident 2026-10-17: ~/node_modules 0.19.3 answered a 0.35.23 hint with "no pending request matches".
260
+ */
261
+ function holmesKitCommand(root, platform = process.platform, home = os.homedir()) {
262
+ // @implements A-SPEC-770.6 — the bare command where nothing shadows it: it reaches a global or local install with no
263
+ // network. The pinned `npx -p …@<version>` of 770.3/770.4 skipped the global install (round 1: ENOTCACHED offline,
264
+ // 703 MB and a y/n prompt on a cold cache, ETARGET for an unpublished version). Where a shadow sits on the path, the
265
+ // running install itself, quoted as A-SPEC-754's operator-recovery line is.
266
+ // @implements A-SPEC-770.7 — the home directory is checked too: an operator often pastes from `~`.
267
+ const bare = `${npxBin(platform)} holmes-kit`;
268
+ if (shadowCopy(root ?? process.cwd(), platform) === null && shadowCopy(home, platform) === null)
269
+ return bare;
270
+ const exe = process.execPath;
271
+ const cli = runningCli();
272
+ if (![exe, cli].every((v) => v.length > 0 && v.length <= 2048 && !UNSAFE_DISPLAY.test(v)))
273
+ return bare;
274
+ return platform === 'win32' ? `& ${powershellLiteral(exe)} ${powershellLiteral(cli)}` : `${posixLiteral(exe)} ${posixLiteral(cli)}`;
275
+ }
276
+ const UNSAFE_DISPLAY = /[\u0000-\u001f\u007f-\u009f‪-‮⁦-⁩]/;
7
277
  /**
8
278
  * @implements A-SPEC-542.1
9
279
  * The npx binary an OPERATOR can actually run on the platform this process runs on — which is the
@@ -51,7 +51,12 @@ function cleanSubprocessEnv(env = process.env) {
51
51
  const cleaned = { ...env };
52
52
  // @implements A-SPEC-477 — the semantic key is egress consent; a child process that inherits
53
53
  // it could exfiltrate without the gate ever seeing a command mention the name.
54
- const SCRUB_KEYS = new Set(['HOLMES_APPROVAL', 'HOLMES_LEDGER_KEY', 'HOLMES_ROLE', 'HOLMES_ENV_CHANNEL', 'HOLMES_SEMANTIC_API_KEY', 'GEMINI_API_KEY', 'GOOGLE_API_KEY']);
54
+ // @implements A-SPEC-774.2 — the gate bypass and the autonomy switch are authority too: a child that
55
+ // inherits them runs ungated or self-approving. Only cleanTestEnv removed them; every other child kept them.
56
+ const SCRUB_KEYS = new Set(['HOLMES_APPROVAL', 'HOLMES_LEDGER_KEY', 'HOLMES_ROLE', 'HOLMES_ENV_CHANNEL', 'HOLMES_SEMANTIC_API_KEY', 'GEMINI_API_KEY', 'GOOGLE_API_KEY',
57
+ 'HOLMES_GATE_BYPASS', 'HOLMES_AUTONOMOUS_APPROVAL',
58
+ // @implements A-SPEC-774.9 §4 — a child never inherits run mode by accident; the orchestrator's adapter sets it.
59
+ 'HOLMES_RUN_ID']);
55
60
  for (const k of Object.keys(cleaned)) {
56
61
  if (SCRUB_KEYS.has(k.toUpperCase())) {
57
62
  delete cleaned[k];
@@ -0,0 +1,17 @@
1
+ export interface RunRecord {
2
+ run_id: string;
3
+ worktree: string;
4
+ sessions: string[];
5
+ engine: string;
6
+ started: string;
7
+ stop_key_sha256: string;
8
+ }
9
+ export declare const runsDir: (main: string) => string;
10
+ /** The main checkout behind `dir`: a linked worktree's `.git` pointer leads to the common git directory's parent. */
11
+ export declare function mainCheckoutOf(dir: string): string;
12
+ export declare const newRunId: (now: Date, rand: () => string) => string;
13
+ export declare const keyHash: (key: string) => string;
14
+ export declare function writeRun(main: string, rec: RunRecord): string;
15
+ export declare function listRuns(main: string): RunRecord[];
16
+ /** Removes the named run's own record file, and only when the key hashes to what start stored. */
17
+ export declare function removeRun(main: string, id: string, key: string | undefined): 'removed' | 'no-run' | 'bad-key';
@@ -0,0 +1,126 @@
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.keyHash = exports.newRunId = exports.runsDir = void 0;
37
+ exports.mainCheckoutOf = mainCheckoutOf;
38
+ exports.writeRun = writeRun;
39
+ exports.listRuns = listRuns;
40
+ exports.removeRun = removeRun;
41
+ // @implements A-SPEC-774.17
42
+ // The run records A-SPEC-774.9's runMode reads: `.ax/state/runs/<run_id>.json` in the main checkout. Written by
43
+ // `holmes-kit run start`, removed by `run stop` with the stop key — a session inside the run never sees the key.
44
+ const crypto = __importStar(require("node:crypto"));
45
+ const fs = __importStar(require("node:fs"));
46
+ const path = __importStar(require("node:path"));
47
+ const RUN_ID_RE = /^run-\d{14}-[0-9a-f]{8}$/;
48
+ const runsDir = (main) => path.join(main, '.ax', 'state', 'runs');
49
+ exports.runsDir = runsDir;
50
+ /** The main checkout behind `dir`: a linked worktree's `.git` pointer leads to the common git directory's parent. */
51
+ function mainCheckoutOf(dir) {
52
+ let cur = path.resolve(dir);
53
+ for (;;) {
54
+ const dotGit = path.join(cur, '.git');
55
+ let st = null;
56
+ try {
57
+ st = fs.statSync(dotGit);
58
+ }
59
+ catch {
60
+ st = null;
61
+ }
62
+ if (st?.isDirectory())
63
+ return cur;
64
+ if (st?.isFile()) {
65
+ const m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotGit, 'utf8'));
66
+ if (!m)
67
+ return cur;
68
+ const gitdir = path.resolve(cur, m[1].trim());
69
+ let common = gitdir;
70
+ try {
71
+ common = path.resolve(gitdir, fs.readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim());
72
+ }
73
+ catch { /* not a worktree gitdir */ }
74
+ return path.basename(common) === '.git' ? path.dirname(common) : cur;
75
+ }
76
+ const up = path.dirname(cur);
77
+ if (up === cur)
78
+ return path.resolve(dir);
79
+ cur = up;
80
+ }
81
+ }
82
+ const newRunId = (now, rand) => `run-${now.toISOString().replace(/[-:T]/g, '').slice(0, 14)}-${rand().slice(0, 8)}`;
83
+ exports.newRunId = newRunId;
84
+ const keyHash = (key) => crypto.createHash('sha256').update(key).digest('hex');
85
+ exports.keyHash = keyHash;
86
+ function writeRun(main, rec) {
87
+ const file = path.join((0, exports.runsDir)(main), `${rec.run_id}.json`);
88
+ fs.mkdirSync(path.dirname(file), { recursive: true });
89
+ fs.writeFileSync(file, `${JSON.stringify(rec, null, 2)}\n`, { flag: 'wx' });
90
+ return file;
91
+ }
92
+ function readRun(file) {
93
+ try {
94
+ const r = JSON.parse(fs.readFileSync(file, 'utf8'));
95
+ if (typeof r.run_id !== 'string' || !RUN_ID_RE.test(r.run_id) || typeof r.worktree !== 'string')
96
+ return null;
97
+ return r;
98
+ }
99
+ catch {
100
+ return null;
101
+ }
102
+ }
103
+ function listRuns(main) {
104
+ let names;
105
+ try {
106
+ names = fs.readdirSync((0, exports.runsDir)(main)).filter((n) => n.endsWith('.json')).sort();
107
+ }
108
+ catch {
109
+ return [];
110
+ }
111
+ return names.map((n) => readRun(path.join((0, exports.runsDir)(main), n))).filter((r) => r !== null);
112
+ }
113
+ /** Removes the named run's own record file, and only when the key hashes to what start stored. */
114
+ function removeRun(main, id, key) {
115
+ if (!RUN_ID_RE.test(id))
116
+ return 'no-run';
117
+ const file = path.join((0, exports.runsDir)(main), `${id}.json`);
118
+ const rec = readRun(file);
119
+ if (rec === null || rec.run_id !== id)
120
+ return 'no-run';
121
+ if (typeof key !== 'string' || typeof rec.stop_key_sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(rec.stop_key_sha256)
122
+ || !crypto.timingSafeEqual(Buffer.from((0, exports.keyHash)(key)), Buffer.from(rec.stop_key_sha256)))
123
+ return 'bad-key';
124
+ fs.rmSync(file);
125
+ return 'removed';
126
+ }
@@ -0,0 +1,12 @@
1
+ import * as fs from 'node:fs';
2
+ export declare function scratchRootPath(tmpdir?: string): string;
3
+ type Lstat = (p: string) => fs.Stats;
4
+ /** The root's real path when it is this user's own directory, not a link, with no group or other bits; else null. */
5
+ export declare function trustedScratchRoot(tmpdir?: string, lstat?: Lstat, platform?: string): string | null;
6
+ /** Makes the root (0700) when missing and returns its real path; throws when an existing root is not trusted. */
7
+ export declare function ensureScratchRoot(tmpdir?: string): string;
8
+ /** A fresh subdirectory `<root>/<label>-XXXXXX`. */
9
+ export declare function newScratchDir(label?: string, tmpdir?: string): string;
10
+ /** True when the target exists and its real path lies strictly under `root` (a real path). */
11
+ export declare function isUnderScratchRoot(target: string, root: string): boolean;
12
+ export {};
@@ -0,0 +1,132 @@
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.scratchRootPath = scratchRootPath;
37
+ exports.trustedScratchRoot = trustedScratchRoot;
38
+ exports.ensureScratchRoot = ensureScratchRoot;
39
+ exports.newScratchDir = newScratchDir;
40
+ exports.isUnderScratchRoot = isUnderScratchRoot;
41
+ // @implements A-SPEC-773, A-SPEC-773.2, A-SPEC-773.3
42
+ const fs = __importStar(require("node:fs"));
43
+ const os = __importStar(require("node:os"));
44
+ const path = __importStar(require("node:path"));
45
+ /**
46
+ * @implements A-SPEC-773 — one Holmes-owned scratch root per user under the OS temporary directory. Agents make their
47
+ * temporary directories under it (`holmes-kit scratch --new <label>`), and the shared gate lets a recursive rm of a
48
+ * subdirectory through when the root is still this user's own 0700 directory (owner decision 2026-10-17). Per user,
49
+ * because a shared /tmp let another user pre-create the codex-oracle root (review, round 3 of that slice).
50
+ */
51
+ function who() {
52
+ if (typeof process.getuid === 'function')
53
+ return String(process.getuid());
54
+ try {
55
+ return os.userInfo().username.replace(/[^\w.-]/g, '_');
56
+ }
57
+ catch {
58
+ return 'user';
59
+ }
60
+ }
61
+ function scratchRootPath(tmpdir = os.tmpdir()) {
62
+ return path.join(tmpdir, `holmes-scratch-${who()}`);
63
+ }
64
+ /** The root's real path when it is this user's own directory, not a link, with no group or other bits; else null. */
65
+ function trustedScratchRoot(tmpdir = os.tmpdir(), lstat = fs.lstatSync, platform = process.platform) {
66
+ // @implements A-SPEC-773.2 — POSIX only: Windows has no getuid or mode bits to read, so nothing proves the root is this
67
+ // user's own; drive-letter targets were never admitted by the gate's shape filter either (round 1, quality).
68
+ if (platform === 'win32')
69
+ return null;
70
+ const root = scratchRootPath(tmpdir);
71
+ try {
72
+ const st = lstat(root);
73
+ if (!st.isDirectory() || st.isSymbolicLink())
74
+ return null;
75
+ if (typeof process.getuid === 'function' && st.uid !== process.getuid())
76
+ return null;
77
+ if ((st.mode & 0o077) !== 0)
78
+ return null;
79
+ return fs.realpathSync.native(root);
80
+ }
81
+ catch {
82
+ return null;
83
+ }
84
+ }
85
+ /** Makes the root (0700) when missing and returns its real path; throws when an existing root is not trusted. */
86
+ function ensureScratchRoot(tmpdir = os.tmpdir()) {
87
+ const root = scratchRootPath(tmpdir);
88
+ try {
89
+ fs.mkdirSync(root, { mode: 0o700 });
90
+ }
91
+ catch (e) {
92
+ if (e.code !== 'EEXIST')
93
+ throw e;
94
+ }
95
+ const trusted = trustedScratchRoot(tmpdir);
96
+ if (trusted !== null)
97
+ return trusted;
98
+ // @implements A-SPEC-773.2 — on Windows the directory is made and printed, but the gate never relaxes for it.
99
+ if (process.platform === 'win32')
100
+ return fs.realpathSync.native(root);
101
+ throw new Error(`${root} is not a directory of this user with mode 0700 (a link, another owner, or group/other bits) — remove it if it is yours, or point TMPDIR at a directory of your own when another user owns it, and retry`);
102
+ }
103
+ const LABEL = /^[A-Za-z0-9._-]{1,40}$/;
104
+ /** A fresh subdirectory `<root>/<label>-XXXXXX`. */
105
+ function newScratchDir(label = 'work', tmpdir = os.tmpdir()) {
106
+ if (!LABEL.test(label) || label === '.' || label === '..')
107
+ throw new Error(`invalid scratch label ${JSON.stringify(label)}: use 1–40 of A-Z a-z 0-9 . _ -`);
108
+ return fs.mkdtempSync(path.join(ensureScratchRoot(tmpdir), `${label}-`));
109
+ }
110
+ /** True when the target exists and its real path lies strictly under `root` (a real path). */
111
+ function isUnderScratchRoot(target, root) {
112
+ // @implements A-SPEC-773.2 — one realpath, no parent fallback: a missing target needs no removal and gets no signal
113
+ // (round 1, quality: 2,000 missing targets under a deep chain took 11 s).
114
+ // @implements A-SPEC-773.3 — judged as rm acts: rm removes a final link itself, so only the parent is resolved; with a
115
+ // trailing slash (or a final `/.`) rm acts through the link, so the whole path is (round 2: `rm -rf <outside>/outlink`
116
+ // was let through because the link's target was judged).
117
+ let resolved;
118
+ try {
119
+ if (/\/\.?$/.test(target))
120
+ resolved = fs.realpathSync.native(path.resolve(target));
121
+ else {
122
+ const abs = path.resolve(target);
123
+ fs.lstatSync(abs);
124
+ resolved = path.join(fs.realpathSync.native(path.dirname(abs)), path.basename(abs));
125
+ }
126
+ }
127
+ catch {
128
+ return false;
129
+ }
130
+ const rel = path.relative(root, resolved);
131
+ return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
132
+ }
@@ -0,0 +1,35 @@
1
+ type Link = {
2
+ id: string;
3
+ status: string;
4
+ } | null;
5
+ export interface ChainEntry {
6
+ aspec: string;
7
+ status: string;
8
+ tspec: Link;
9
+ hspec: Link;
10
+ req: Link;
11
+ }
12
+ export interface Mrp {
13
+ base: string;
14
+ head: string;
15
+ files: string[];
16
+ chain: ChainEntry[];
17
+ evidence: {
18
+ head?: string;
19
+ fresh: boolean;
20
+ passed?: boolean;
21
+ executed?: number;
22
+ };
23
+ review: {
24
+ ok: boolean;
25
+ reasons: string[];
26
+ };
27
+ coverage: 'unmeasured';
28
+ mutation: 'unmeasured';
29
+ ready: boolean;
30
+ missing: string[];
31
+ }
32
+ export declare function buildMrp(root: string, base: string, head: string): Mrp | {
33
+ error: string;
34
+ };
35
+ export {};