@holmes-lab/holmes-kit 0.35.23 → 0.35.25

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 (44) hide show
  1. package/CHANGELOG.md +115 -0
  2. package/README.md +5 -3
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agent-registry.d.ts +7 -0
  5. package/dist/holmes/cli/agent-registry.js +10 -0
  6. package/dist/holmes/cli/agents.d.ts +2 -2
  7. package/dist/holmes/cli/agents.js +196 -6
  8. package/dist/holmes/cli/approve.js +4 -4
  9. package/dist/holmes/cli/doctor.d.ts +22 -0
  10. package/dist/holmes/cli/doctor.js +160 -11
  11. package/dist/holmes/cli/index.js +23 -1
  12. package/dist/holmes/cli/init.d.ts +24 -0
  13. package/dist/holmes/cli/init.js +55 -3
  14. package/dist/holmes/cli/runtime-binding-approval.js +3 -2
  15. package/dist/holmes/cli/runtime-binding.d.ts +10 -1
  16. package/dist/holmes/cli/runtime-binding.js +139 -2
  17. package/dist/holmes/cli/scratch.d.ts +12 -0
  18. package/dist/holmes/cli/scratch.js +20 -0
  19. package/dist/holmes/governance/approval-queue.js +4 -3
  20. package/dist/holmes/guardrail/impact-gate.d.ts +2 -0
  21. package/dist/holmes/guardrail/impact-gate.js +34 -11
  22. package/dist/holmes/guardrail/risk-classifier.js +14 -2
  23. package/dist/holmes/guardrail/risk-types.d.ts +1 -0
  24. package/dist/holmes/hooks/adapters/antigravity.js +3 -2
  25. package/dist/holmes/hooks/heartbeat.d.ts +47 -0
  26. package/dist/holmes/hooks/heartbeat.js +247 -0
  27. package/dist/holmes/hooks/pre-tool-use.d.ts +1 -1
  28. package/dist/holmes/hooks/pre-tool-use.js +46 -3
  29. package/dist/holmes/hooks/stop.d.ts +3 -1
  30. package/dist/holmes/hooks/stop.js +16 -4
  31. package/dist/holmes/mcp/elicit-approval.js +4 -4
  32. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +28 -0
  33. package/dist/holmes/mcp/handlers/runtime-binding-tool.js +42 -9
  34. package/dist/holmes/mcp/handlers/spec-approval.js +3 -2
  35. package/dist/holmes/mcp/handlers/workspace-preflight.js +2 -2
  36. package/dist/holmes/mcp/handlers.d.ts +27 -1
  37. package/dist/holmes/project/npx-bin.d.ts +26 -0
  38. package/dist/holmes/project/npx-bin.js +272 -2
  39. package/dist/holmes/project/scratch-root.d.ts +12 -0
  40. package/dist/holmes/project/scratch-root.js +132 -0
  41. package/dist/holmes/project/workspace-preflight.d.ts +3 -0
  42. package/dist/holmes/project/workspace-preflight.js +42 -2
  43. package/dist/holmes/runtime/dispatch.js +8 -4
  44. package/package.json +1 -1
@@ -665,6 +665,20 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
665
665
  operation?: string;
666
666
  activate_hooks?: string[];
667
667
  }): Promise<{
668
+ ok: false;
669
+ applied: false;
670
+ routing: {
671
+ mode: "release";
672
+ packageRoot: string;
673
+ buildId: string;
674
+ } | {
675
+ mode: "unrouted";
676
+ } | {
677
+ mode: "unroutable";
678
+ error: string;
679
+ };
680
+ reason: string;
681
+ } | {
668
682
  ok: boolean;
669
683
  applied: boolean;
670
684
  reason: string;
@@ -691,10 +705,22 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
691
705
  ok: boolean;
692
706
  applied: boolean;
693
707
  reason?: undefined;
708
+ } | {
709
+ planDigest: string;
710
+ conflicts: string[];
711
+ changes: {
712
+ path: string;
713
+ added: number;
714
+ removed: number;
715
+ }[];
716
+ request?: string | undefined;
717
+ ok: boolean;
718
+ applied: boolean;
719
+ reason: string;
694
720
  }>;
695
721
  workspace_preflight(a: {
696
722
  root: string;
697
- harness?: import("../cli/agents").Agent;
723
+ harness?: import("../cli/agent-registry").Agent;
698
724
  }): Promise<import("../project/workspace-preflight").WorkspacePreflight>;
699
725
  requirement_triage: (a: {
700
726
  root: string;
@@ -1,3 +1,29 @@
1
+ /** @implements A-SPEC-770.6 — the running package's CLI (src/holmes/project and dist/holmes/project share a depth). */
2
+ export declare function runningCli(): string;
3
+ export interface ShadowCopy {
4
+ link: string;
5
+ packageDir: string | null;
6
+ version: string;
7
+ }
8
+ /**
9
+ * @implements A-SPEC-770.7 — the holmes-kit npx would run from `dir`, when it is not this install; null otherwise.
10
+ * npx walks every ancestor `node_modules/.bin` and takes the first entry that `stat` says is a FILE (a dangling link or
11
+ * a directory is skipped). Round 2 measured npm-on-Windows and pnpm `.bin` entries as shim files, not links: the
12
+ * package is therefore found as `node_modules/{@holmes-lab/holmes-kit,holmes-kit}` beside the `.bin`, and only for a
13
+ * link with neither beside it through the link's target — never past a node_modules boundary (that read the consumer
14
+ * project's own package.json). Not memoized: a copy installed later is seen (the MCP server lives long).
15
+ */
16
+ export declare function binEntryNames(platform?: string): string[];
17
+ export declare function shadowCopy(dir: string, platform?: string): ShadowCopy | null;
18
+ /** @implements A-SPEC-770.7 — a PowerShell single-quoted literal: PowerShell also treats U+2018–U+201B as quotes. */
19
+ export declare function powershellLiteral(value: string): string;
20
+ export declare function posixLiteral(value: string): string;
21
+ /**
22
+ * @implements A-SPEC-770.3
23
+ * The holmes-kit command an approval hint names, so that the install that issued it is the one that answers. Field
24
+ * incident 2026-10-17: ~/node_modules 0.19.3 answered a 0.35.23 hint with "no pending request matches".
25
+ */
26
+ export declare function holmesKitCommand(root?: string, platform?: string, home?: string): string;
1
27
  /**
2
28
  * @implements A-SPEC-542.1
3
29
  * The npx binary an OPERATOR can actually run on the platform this process runs on — which is the
@@ -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
@@ -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
+ }
@@ -1,3 +1,4 @@
1
+ import { Agent } from '../cli/agents';
1
2
  import { WorkspaceIdentityStatus } from './workspace-identity';
2
3
  import { CheckoutInfo } from './workspace-checkout';
3
4
  export type { CheckoutInfo } from './workspace-checkout';
@@ -21,4 +22,6 @@ export type WorkspacePreflight = {
21
22
  export declare function inspectWorkspacePreflight(input: {
22
23
  requestedRoot: string;
23
24
  storeRoot?: string;
25
+ harness?: Agent;
26
+ now?: number;
24
27
  }): WorkspacePreflight;
@@ -34,12 +34,49 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.inspectWorkspacePreflight = inspectWorkspacePreflight;
37
- // @implements A-SPEC-703
37
+ // @implements A-SPEC-703, A-SPEC-772.1, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.10, A-SPEC-772.11
38
38
  const fs = __importStar(require("node:fs"));
39
39
  const path = __importStar(require("node:path"));
40
40
  const root_1 = require("./root");
41
+ const agents_1 = require("../cli/agents");
42
+ const heartbeat_1 = require("../hooks/heartbeat");
41
43
  const workspace_identity_1 = require("./workspace-identity");
42
44
  const workspace_checkout_1 = require("./workspace-checkout");
45
+ /**
46
+ * @implements A-SPEC-772.1 — what the hook heartbeat says about a harness here. It reports an observation, never
47
+ * enforcement: a record proves the hook ran, not that every later call will be judged.
48
+ */
49
+ /** @implements A-SPEC-772.10 — an inherited switch-off would otherwise look like a wiring fault. */
50
+ const recorderOff = () => process.env.HOLMES_HEARTBEAT === 'off' ? ' (heartbeat recording is off in this environment: HOLMES_HEARTBEAT=off)' : '';
51
+ function enforcementCheck(root, harness, now) {
52
+ const beats = (0, heartbeat_1.readHookHeartbeats)(root, now);
53
+ if (harness === undefined) {
54
+ const seen = agents_1.AGENTS.filter((a) => (0, heartbeat_1.observationOf)(beats, a, now, (0, heartbeat_1.hookWiringFiles)(root, a), 'pre-tool-use').state === 'observed');
55
+ return { status: 'unknown', detail: `Hook execution observed in this workspace within 24 h for: ${seen.length ? seen.join(', ') : 'no harness'}.${recorderOff()}`,
56
+ actions: ['Pass harness to workspace_preflight to check the harness this session runs in.'] };
57
+ }
58
+ // @implements A-SPEC-772.6 — an observation older than the harness's wiring is stale.
59
+ // @implements A-SPEC-772.8 — pass means the PreToolUse GATE ran here; a Stop alone is not that (Codex trusts and
60
+ // switches each handler separately).
61
+ const wiring = (0, heartbeat_1.hookWiringFiles)(root, harness);
62
+ const gate = (0, heartbeat_1.observationOf)(beats, harness, now, wiring, 'pre-tool-use');
63
+ if (gate.state === 'observed')
64
+ return { status: 'pass', detail: `Hook execution observed ${harness} ${gate.event} at ${gate.at} (build ${gate.buildId}, ${gate.mode === 'unknown' ? 'routing unknown' : gate.mode}).`, actions: [] };
65
+ const o = (0, heartbeat_1.observationOf)(beats, harness, now, wiring);
66
+ // @implements A-SPEC-772.10 — say what was not observed, no more.
67
+ const notSeen = gate.state === 'stale' && gate.reason ? 'not observed since its wiring changed' : 'not observed within 24 h';
68
+ if (o.state === 'observed')
69
+ return { status: 'unknown', detail: `${harness}: only the Stop hook was observed; the PreToolUse gate was ${notSeen} (last Stop at ${o.at}).${recorderOff()}`,
70
+ actions: [`Check that the ${harness} PreToolUse hook is wired and trusted (holmes-kit doctor --target ${root}).`] };
71
+ // @implements A-SPEC-772.11 — every non-pass branch names a switched-off recorder; the wiring-changed sentence says
72
+ // what refreshes it (the hook writes at most once a minute, so it may have run again already).
73
+ if (o.state === 'stale')
74
+ return { status: 'unknown', detail: (o.reason
75
+ ? `${harness} hooks were last observed at ${o.at}, before their wiring changed; a newer record is written at the next hook run after the one-per-minute limit.`
76
+ : `${harness} hooks were last observed ${(0, heartbeat_1.ageText)(o.ageMs)} ago (${o.event}, build ${o.buildId}); live activation is unverified.`) + recorderOff(), actions: [] };
77
+ return { status: 'unknown', detail: `${harness} hooks were never observed in this workspace; live activation is unverified.${recorderOff()}`,
78
+ actions: [`Run holmes-kit doctor --target ${root} and check the ${harness} hook wiring.`] };
79
+ }
43
80
  function inspectWorkspacePreflight(input) {
44
81
  const out = { schema: 'holmes-workspace-preflight/1', requestedRoot: null,
45
82
  boundRoot: null, boundSpecsRoot: null, binding: 'invalid', identity: null, checkout: null, checks: [], nextActions: [] };
@@ -83,7 +120,10 @@ function inspectWorkspacePreflight(input) {
83
120
  else
84
121
  check('identity', 'pass', `Workspace identity is ${out.identity.state}.`);
85
122
  check('checkout', out.checkout.kind === 'unknown' ? 'unknown' : 'pass', `Checkout kind: ${out.checkout.kind}.`);
86
- check('runtime-enforcement', 'unknown', 'Binding and disk inspection do not prove current client hook enforcement.');
123
+ {
124
+ const e = enforcementCheck(out.boundRoot, input.harness, input.now ?? Date.now());
125
+ check('runtime-enforcement', e.status, e.detail, e.actions);
126
+ }
87
127
  return out;
88
128
  }
89
129
  catch (e) {
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.runDispatch = runDispatch;
37
- // @implements A-SPEC-751, A-SPEC-751.1, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-754, A-SPEC-769.10
37
+ // @implements A-SPEC-751, A-SPEC-751.1, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751.7, A-SPEC-754, A-SPEC-769.10, A-SPEC-772.1
38
38
  const path = __importStar(require("node:path"));
39
39
  const node_child_process_1 = require("node:child_process");
40
40
  const binding_1 = require("./binding");
@@ -99,7 +99,7 @@ async function runDispatch(opts) {
99
99
  const budget = (0, hook_process_1.boundedHookBudget)(opts.hookBudgetMs, hook_process_1.HOOK_BUDGET_MS);
100
100
  const input = await hookInput(budget);
101
101
  const hints = hintsFromInput(input);
102
- if (process.env.CLAUDE_PROJECT_DIR)
102
+ if (process.env.CLAUDE_PROJECT_DIR && opts.harness === 'claude')
103
103
  hints.push(process.env.CLAUDE_PROJECT_DIR);
104
104
  const selection = (0, binding_1.selectRuntime)((0, binding_1.readRuntimeRegistry)(opts.registryPath), { cwd: process.cwd(), workspaceHints: hints, specsHint: process.env.HOLMES_SPECS });
105
105
  const child = (0, node_child_process_1.spawn)(process.execPath, [path.join(selection.packageRoot, 'dist/holmes/hooks/session-start.js')], {
@@ -145,7 +145,10 @@ async function runDispatch(opts) {
145
145
  }
146
146
  }
147
147
  const hints = input ? hintsFromInput(input) : [];
148
- if (process.env.CLAUDE_PROJECT_DIR)
148
+ // @implements A-SPEC-751.7 — CLAUDE_PROJECT_DIR is Claude Code's variable. Every process Claude launches passes it
149
+ // on, so a Codex or Antigravity session under one of them inherits a value naming ANOTHER workspace (measured
150
+ // 2026-10-17: every Codex tool call denied as "Conflicting runtime workspace hints").
151
+ if (process.env.CLAUDE_PROJECT_DIR && opts.harness === 'claude')
149
152
  hints.push(process.env.CLAUDE_PROJECT_DIR);
150
153
  const selection = (0, binding_1.selectRuntime)((0, binding_1.readRuntimeRegistry)(opts.registryPath), { cwd: process.cwd(), workspaceHints: hints, specsHint: process.env.HOLMES_SPECS });
151
154
  phaseSelection = Math.round(performance.now() - started) - (phaseInput ?? 0);
@@ -170,7 +173,8 @@ async function runDispatch(opts) {
170
173
  }
171
174
  const child = (0, node_child_process_1.spawn)(process.execPath, [path.join(selection.packageRoot, relative)], {
172
175
  cwd: selection.workspaceRoot,
173
- env: { ...process.env, HOLMES_SPECS: selection.specsRoot, CLAUDE_PROJECT_DIR: selection.workspaceRoot },
176
+ // @implements A-SPEC-772.1 — the hook records which harness and which routing it ran under.
177
+ env: { ...process.env, HOLMES_SPECS: selection.specsRoot, CLAUDE_PROJECT_DIR: selection.workspaceRoot, HOLMES_HOOK_HARNESS: opts.harness, HOLMES_HOOK_MODE: selection.mode },
174
178
  stdio: ['pipe', input ? 'pipe' : 'inherit', 'inherit'],
175
179
  detached: input !== undefined && process.platform !== 'win32', windowsHide: true,
176
180
  });
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.35.23",
4
+ "version": "0.35.25",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",