@holmes-lab/holmes-kit 0.35.0 → 0.35.2

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 (50) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +7 -0
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve.js +9 -2
  5. package/dist/holmes/cli/codex-oracle.js +36 -2
  6. package/dist/holmes/cli/doctor.d.ts +14 -1
  7. package/dist/holmes/cli/doctor.js +355 -72
  8. package/dist/holmes/cli/index.d.ts +1 -1
  9. package/dist/holmes/cli/index.js +38 -5
  10. package/dist/holmes/cli/init.d.ts +2 -0
  11. package/dist/holmes/cli/init.js +37 -1
  12. package/dist/holmes/cli/runtime-binding-approval.d.ts +7 -0
  13. package/dist/holmes/cli/runtime-binding-approval.js +102 -0
  14. package/dist/holmes/cli/runtime-binding.d.ts +45 -0
  15. package/dist/holmes/cli/runtime-binding.js +630 -0
  16. package/dist/holmes/governance/approval-grants.d.ts +7 -0
  17. package/dist/holmes/governance/approval-grants.js +8 -2
  18. package/dist/holmes/governance/approval-queue.d.ts +2 -0
  19. package/dist/holmes/governance/approval-queue.js +11 -4
  20. package/dist/holmes/governance/autonomy.d.ts +9 -0
  21. package/dist/holmes/governance/autonomy.js +65 -13
  22. package/dist/holmes/guardrail/risk-classifier.js +76 -26
  23. package/dist/holmes/guardrail/shell-argument-roles.d.ts +15 -0
  24. package/dist/holmes/guardrail/shell-argument-roles.js +209 -0
  25. package/dist/holmes/guardrail/shell-syntax.d.ts +20 -0
  26. package/dist/holmes/guardrail/shell-syntax.js +489 -0
  27. package/dist/holmes/guardrail/shell-words.d.ts +2 -18
  28. package/dist/holmes/guardrail/shell-words.js +15 -441
  29. package/dist/holmes/guardrail/write-target.d.ts +54 -0
  30. package/dist/holmes/guardrail/write-target.js +327 -1
  31. package/dist/holmes/guardrail/write-verb-word.d.ts +13 -0
  32. package/dist/holmes/guardrail/write-verb-word.js +55 -0
  33. package/dist/holmes/hooks/pre-tool-use.d.ts +14 -0
  34. package/dist/holmes/hooks/pre-tool-use.js +391 -66
  35. package/dist/holmes/mcp/handlers/spec-approval.js +14 -2
  36. package/dist/holmes/mcp/handlers.d.ts +9 -1
  37. package/dist/holmes/mcp/handlers.js +6 -4
  38. package/dist/holmes/mcp/harness-attestation.d.ts +10 -1
  39. package/dist/holmes/mcp/harness-attestation.js +70 -3
  40. package/dist/holmes/mcp/operator-recovery.d.ts +9 -0
  41. package/dist/holmes/mcp/operator-recovery.js +66 -0
  42. package/dist/holmes/mcp/server.js +6 -3
  43. package/dist/holmes/runtime/binding.d.ts +30 -0
  44. package/dist/holmes/runtime/binding.js +164 -0
  45. package/dist/holmes/runtime/dispatch.d.ts +9 -0
  46. package/dist/holmes/runtime/dispatch.js +169 -0
  47. package/dist/holmes/runtime/hook-process.d.ts +11 -0
  48. package/dist/holmes/runtime/hook-process.js +130 -0
  49. package/docs/install-guide.md +65 -0
  50. package/package.json +1 -1
@@ -0,0 +1,11 @@
1
+ import { type ChildProcess } from 'node:child_process';
2
+ export declare const HOOK_BUDGET_MS = 18000;
3
+ export declare const HOOK_CLEANUP_MS = 8000;
4
+ export declare function boundedHookBudget(value: number | undefined, maximum: number): number;
5
+ export interface HookChildResult {
6
+ bytes: Buffer;
7
+ code: number | null;
8
+ signal: NodeJS.Signals | null;
9
+ }
10
+ /** Bounded hook transport only. Persistent MCP transports do not call this function. */
11
+ export declare function runHookChild(child: ChildProcess, input: Buffer, remainingMs: number, cleanupMs: number): Promise<HookChildResult>;
@@ -0,0 +1,130 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.HOOK_CLEANUP_MS = exports.HOOK_BUDGET_MS = void 0;
4
+ exports.boundedHookBudget = boundedHookBudget;
5
+ exports.runHookChild = runHookChild;
6
+ // @implements A-SPEC-751.1
7
+ const node_child_process_1 = require("node:child_process");
8
+ exports.HOOK_BUDGET_MS = 18_000;
9
+ exports.HOOK_CLEANUP_MS = 8_000;
10
+ function boundedHookBudget(value, maximum) {
11
+ if (value === undefined)
12
+ return maximum;
13
+ if (!Number.isInteger(value) || value <= 0 || value > maximum)
14
+ throw new Error('Invalid hook deadline budget');
15
+ return value;
16
+ }
17
+ const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
18
+ /** Only a child spawned by this dispatcher may be supplied. Never enumerate unrelated PIDs. */
19
+ async function stopOwnedChild(child, closed, budget) {
20
+ const until = performance.now() + budget;
21
+ let failure;
22
+ try {
23
+ if (child.pid && process.platform === 'win32' && !closed()) {
24
+ failure = await new Promise(resolve => {
25
+ const killer = (0, node_child_process_1.spawn)('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
26
+ let settled = false;
27
+ const finish = (reason) => {
28
+ if (settled)
29
+ return;
30
+ settled = true;
31
+ clearTimeout(timer);
32
+ resolve(reason);
33
+ };
34
+ const timer = setTimeout(() => { killer.kill('SIGKILL'); killer.unref(); finish('process tree cleanup timed out'); }, Math.max(1, until - performance.now()));
35
+ killer.once('error', () => finish('process tree cleanup could not start'));
36
+ killer.once('close', code => finish(code === 0 ? undefined : `process tree cleanup exited ${code}`));
37
+ });
38
+ }
39
+ else if (child.pid && process.platform !== 'win32') {
40
+ const kill = (signal) => {
41
+ try {
42
+ process.kill(-child.pid, signal);
43
+ }
44
+ catch (error) {
45
+ if (error.code !== 'ESRCH')
46
+ throw error;
47
+ }
48
+ };
49
+ kill('SIGTERM');
50
+ await delay(Math.min(100, budget / 4));
51
+ // A wrapper can exit first while its descendant keeps a pipe open or ignores SIGTERM.
52
+ kill('SIGKILL');
53
+ }
54
+ }
55
+ catch {
56
+ failure = 'owned process tree cleanup failed';
57
+ }
58
+ child.stdin?.destroy();
59
+ child.stdout?.destroy();
60
+ child.stderr?.destroy();
61
+ while (!closed() && performance.now() < until)
62
+ await delay(Math.min(20, Math.max(1, until - performance.now())));
63
+ if (!closed()) {
64
+ child.unref();
65
+ return failure ?? 'child closure could not be confirmed before cleanup deadline';
66
+ }
67
+ return failure;
68
+ }
69
+ /** Bounded hook transport only. Persistent MCP transports do not call this function. */
70
+ function runHookChild(child, input, remainingMs, cleanupMs) {
71
+ return new Promise((resolve, reject) => {
72
+ const output = [];
73
+ let bytes = 0;
74
+ let closed = false;
75
+ let finishing = false;
76
+ let externalSignal;
77
+ const signals = ['SIGTERM', 'SIGINT', 'SIGHUP'];
78
+ const handlers = signals.map(signal => () => {
79
+ externalSignal ??= signal;
80
+ void finish(undefined, { bytes: Buffer.alloc(0), code: null, signal: externalSignal }, true);
81
+ });
82
+ const timer = setTimeout(() => { void finish(new Error('Selected hook runtime deadline exceeded'), undefined, true); }, Math.max(1, remainingMs));
83
+ const finish = async (error, result, stop = false) => {
84
+ if (finishing)
85
+ return;
86
+ finishing = true;
87
+ clearTimeout(timer);
88
+ let cleanupFailure;
89
+ if (stop)
90
+ cleanupFailure = await stopOwnedChild(child, () => closed, cleanupMs);
91
+ if (externalSignal) {
92
+ error = undefined;
93
+ result = { bytes: Buffer.alloc(0), code: null, signal: externalSignal };
94
+ }
95
+ signals.forEach((signal, i) => process.removeListener(signal, handlers[i]));
96
+ child.stdout?.removeListener('data', onData);
97
+ child.stdin?.removeListener('error', onInputError);
98
+ if (cleanupFailure) {
99
+ if (result?.signal)
100
+ process.stderr.write(`[Holmes-Kit] ${cleanupFailure}\n`);
101
+ else
102
+ error = new Error(`${error?.message ?? 'Hook transport failed'}; cleanup unconfirmed: ${cleanupFailure}`);
103
+ }
104
+ if (error)
105
+ reject(error);
106
+ else
107
+ resolve(result);
108
+ };
109
+ const onData = (chunk) => {
110
+ if (finishing)
111
+ return;
112
+ bytes += chunk.length;
113
+ if (bytes > 2 * 1024 * 1024)
114
+ void finish(new Error('Hook output exceeds 2 MiB'), undefined, true);
115
+ else
116
+ output.push(chunk);
117
+ };
118
+ const onInputError = (error) => { if (error.code !== 'EPIPE')
119
+ void finish(new Error('Hook input delivery failed'), undefined, true); };
120
+ child.stdout.on('data', onData);
121
+ child.stdin.on('error', onInputError);
122
+ child.once('error', error => { void finish(error, undefined, true); });
123
+ child.once('close', (code, signal) => {
124
+ closed = true;
125
+ void finish(undefined, { bytes: Buffer.concat(output), code, signal }, signal !== null);
126
+ });
127
+ signals.forEach((signal, i) => process.on(signal, handlers[i]));
128
+ child.stdin.end(input);
129
+ });
130
+ }
@@ -17,6 +17,71 @@ worked on the first try. Find your row, run its one command.
17
17
  The local install is the path verified end to end, on macOS and Windows, against the public
18
18
  registry. The wiring `init` writes uses absolute paths, so nothing needs to be on `PATH`.
19
19
 
20
+ ## Development and consumer runtime binding
21
+
22
+ Maintainers can register a built development package without replacing the release used by consumer
23
+ projects. This explicit installation is separate from ordinary `init`. It applies to Claude Code, Codex
24
+ and Antigravity through a shared resolver; successful setup is not proof that a native session loaded or
25
+ trusted its hooks.
26
+
27
+ Choose three absolute paths: the development workspace, its complete built Holmes-Kit package, and the
28
+ installed release package. The built package must contain its CLI, MCP entry, compiled hooks and build ID.
29
+ Use the built package's CLI to preview the installation (replace the example paths):
30
+
31
+ ```sh
32
+ node "/absolute/development-package/bin/holmes-kit.js" runtime-binding setup --workspace "/absolute/workspace" --package "/absolute/development-package" --release-package "/absolute/release-package" --dry-run
33
+ ```
34
+
35
+ The default registry is `~/.holmes/runtime/bindings.json`. An explicit `--registry` selects another
36
+ operator-controlled destination; keep that same path on setup, status and doctor calls. A repository marker
37
+ cannot register executable code. Linked worktrees and independent nested workspaces require their own
38
+ binding; missing development builds never silently fall back to the release.
39
+
40
+ Review the exact changed files and resolve every conflict. Then run the same setup without `--dry-run`
41
+ from the operator terminal. If it prints an approval request, that invocation has not applied the plan.
42
+ Review and grant only that current request through the same built CLI:
43
+
44
+ ```sh
45
+ node "/absolute/development-package/bin/holmes-kit.js" approve --target "/absolute/workspace" --grant "<request-id>"
46
+ ```
47
+
48
+ Retry the unchanged setup after successful approval. If the plan changed, review its new request instead
49
+ of reusing an old grant. A fully validated zero-change setup needs no additional approval; replacing a build
50
+ at the same path or migrating an old installation receipt is still a real change.
51
+
52
+ Ordinary setup preserves disabled lifecycle entries and native trust. To restore selected Holmes hook
53
+ entries, include `--activate-hooks claude,codex,antigravity` (or a subset) in the preview and apply commands.
54
+ Native trust and global disable switches remain native review steps. Do not manufacture trust records or
55
+ assume a new project hook suppresses another user/plugin hook.
56
+
57
+ After installation, inspect selection and diagnosis:
58
+
59
+ ```sh
60
+ node "/absolute/development-package/bin/holmes-kit.js" runtime-binding status --workspace "/absolute/workspace"
61
+ node "/absolute/development-package/bin/holmes-kit.js" doctor --target "/absolute/workspace"
62
+ ```
63
+
64
+ For a custom registry, add its `--registry` argument to both commands. Reconnect the MCP server if it still
65
+ reports the old build. In a fresh native session, compare MCP and hook package/build/workspace/spec store,
66
+ then observe permission, refusal, official recovery, original task resumption and normal Stop. Repeat in
67
+ each harness and in an unregistered consumer workspace. `binding: matched`, doctor output and generated
68
+ configuration alone do not establish live enforcement.
69
+
70
+ **Approval recovery:** the dedicated MCP dispatcher loads the validated package entry in the same process,
71
+ preserving its genuine native parent. The entry retains its opt-in autoreload supervisor; that chain or
72
+ another host may still be unable to attest. Such routes use the official operator queue without relaxing
73
+ native identity checks. Follow the displayed command: it names the running package's CLI, bound workspace
74
+ and recorded request ID. Do not keep retrying the same refused action without a new decision. Retry the
75
+ original MCP operation after the grant is recognized. Held questions and denial reasons must first be
76
+ addressed; expired, wrong-scope or consumed authority needs an official decision. A chat acknowledgement
77
+ is not a grant. Validate the actual newly installed session before claiming that recovery works there.
78
+
79
+ Routed hooks bound input/selection/execution to 18 seconds and owned-process cleanup to another 8 seconds.
80
+ On timeout or malformed output they return native refusal guidance with status/doctor commands. Repair the
81
+ selected package through a reviewed installation, then retry the original operation. Cleanup uncertainty
82
+ and pending findings remain visible. These bounds do not guarantee that every native host or operating-system
83
+ failure is recoverable without operator action. MCP itself has no hook lifetime deadline.
84
+
20
85
  ## Before `npm install -g`: check your prefix
21
86
 
22
87
  ```
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.0",
4
+ "version": "0.35.2",
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",