@holmes-lab/holmes-kit 0.35.23 → 0.35.24

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.
@@ -62,7 +62,7 @@ exports.collectForbiddenEdgeJudgement = collectForbiddenEdgeJudgement;
62
62
  exports.stopSharedScan = stopSharedScan;
63
63
  exports.scanCodeCycles = scanCodeCycles;
64
64
  exports.writeGuardCount = writeGuardCount;
65
- // @implements A-SPEC-734
65
+ // @implements A-SPEC-734, A-SPEC-772.1
66
66
  // @implements A-SPEC-769.9, A-SPEC-769.10, A-SPEC-769.11
67
67
  const fs = __importStar(require("node:fs"));
68
68
  // @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
@@ -1393,6 +1393,8 @@ if (require.main === module) {
1393
1393
  // there is no project this hook has nothing to judge: no answer, no notice, no file.
1394
1394
  if (outsideAnyProject({ foundRoot: findProjectRoot(wired), specsDir, cwd: process.cwd() }))
1395
1395
  return;
1396
+ // @implements A-SPEC-772.1 — evidence that this harness's Stop gate ran here; off the decision path, never throws.
1397
+ require('./heartbeat').recordHookHeartbeat({ root: stopProjectRoot(), event: 'stop', input, env: process.env });
1396
1398
  const specs = (0, pre_tool_use_1.readSpecsSync)(specsDir);
1397
1399
  // H1 evidence: count EXECUTABLE test cases per anchored A-SPEC (countTestCases strips comments/
1398
1400
  // strings — sham-resistant). A scan FAILURE yields `undefined` (ART-4 skipped this turn, true
@@ -9,12 +9,27 @@ export interface RuntimeBindingToolContext {
9
9
  home?: string;
10
10
  installerPackageRoot?: string;
11
11
  }
12
+ type Routing = {
13
+ mode: 'release';
14
+ packageRoot: string;
15
+ buildId: string;
16
+ } | {
17
+ mode: 'unrouted';
18
+ } | {
19
+ mode: 'unroutable';
20
+ error: string;
21
+ };
12
22
  export declare function createRuntimeBindingToolHandlers(context: RuntimeBindingToolContext): {
13
23
  runtime_binding(a: {
14
24
  root: string;
15
25
  operation?: string;
16
26
  activate_hooks?: string[];
17
27
  }): Promise<{
28
+ ok: false;
29
+ applied: false;
30
+ routing: Routing;
31
+ reason: string;
32
+ } | {
18
33
  ok: boolean;
19
34
  applied: boolean;
20
35
  reason: string;
@@ -41,5 +56,18 @@ export declare function createRuntimeBindingToolHandlers(context: RuntimeBinding
41
56
  ok: boolean;
42
57
  applied: boolean;
43
58
  reason?: undefined;
59
+ } | {
60
+ planDigest: string;
61
+ conflicts: string[];
62
+ changes: {
63
+ path: string;
64
+ added: number;
65
+ removed: number;
66
+ }[];
67
+ request?: string | undefined;
68
+ ok: boolean;
69
+ applied: boolean;
70
+ reason: string;
44
71
  }>;
45
72
  };
73
+ export {};
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createRuntimeBindingToolHandlers = createRuntimeBindingToolHandlers;
37
- // @implements A-SPEC-752.10
37
+ // @implements A-SPEC-752.10, A-SPEC-772, A-SPEC-772.5
38
38
  /**
39
39
  * `runtime_binding` — re-apply the binding the operator registry ALREADY names for this workspace, from inside the
40
40
  * session, on the owner's explicit answer in the approval dialog.
@@ -53,6 +53,35 @@ const node_crypto_1 = require("node:crypto");
53
53
  const binding_1 = require("../../runtime/binding");
54
54
  const runtime_binding_1 = require("../../cli/runtime-binding");
55
55
  const HARNESSES = ['claude', 'codex', 'antigravity'];
56
+ const SETUP = '`holmes-kit runtime-binding setup` in a terminal';
57
+ /**
58
+ * @implements A-SPEC-772 — the answer for a workspace with no development binding names the routing that governs it.
59
+ * "Not registered" read as "not governed" (2026-10-17): the dispatcher routes such a workspace to the release build.
60
+ */
61
+ function unboundAnswer(registry, root, readError) {
62
+ let routing;
63
+ if (readError !== undefined)
64
+ routing = { mode: 'unroutable', error: readError };
65
+ else if (registry === null)
66
+ routing = { mode: 'unrouted' };
67
+ else {
68
+ try {
69
+ const s = (0, binding_1.selectRuntime)(registry, { cwd: root });
70
+ routing = { mode: 'release', packageRoot: s.packageRoot, buildId: s.buildId };
71
+ }
72
+ catch (e) {
73
+ routing = { mode: 'unroutable', error: e.message };
74
+ }
75
+ }
76
+ // @implements A-SPEC-772.5 — a registry file proves the routing of routed hooks, not that every harness is routed.
77
+ const which = 'Which applies to each harness: `holmes-kit runtime-binding status` and workspace_preflight with `harness`.';
78
+ const reason = routing.mode === 'release'
79
+ ? `runtime_binding: no development binding is registered for this workspace, so there is nothing to re-apply. Hooks routed through the operator runtime registry run the release build ${routing.buildId} (${routing.packageRoot}); hooks wired directly by \`holmes-kit init\` run the package their command names. ${which} Binding a development build is an operator act: ${SETUP}.`
80
+ : routing.mode === 'unrouted'
81
+ ? `runtime_binding: there is no operator runtime registry on this machine. Hooks wired by \`holmes-kit init\` run as wired; a hook still routed through the dispatcher refuses until the operator repairs the registry with ${SETUP}. ${which}`
82
+ : `runtime_binding: this workspace cannot be routed — ${routing.error} Hooks routed through the operator registry refuse until the operator repairs it with ${SETUP}.`;
83
+ return { ok: false, applied: false, routing, reason };
84
+ }
56
85
  /** How many lines a change adds and removes — what a reviewer needs from a tool answer; the contents stay on disk. */
57
86
  function lineCounts(change) {
58
87
  const before = (change.before ?? '').split('\n');
@@ -75,24 +104,28 @@ function createRuntimeBindingToolHandlers(context) {
75
104
  return { ok: false, applied: false, reason: `runtime_binding: activate_hooks takes only ${HARNESSES.join(', ')}` };
76
105
  }
77
106
  const registryPath = context.registryPath();
78
- const unregistered = { ok: false, applied: false,
79
- reason: 'runtime_binding: this workspace is not registered in the operator runtime registry. Registering a workspace, or choosing which build governs it, is done by the operator with `holmes-kit runtime-binding setup` in a terminal; this tool only re-applies a registered binding.' };
80
107
  let root;
81
108
  let binding;
82
109
  let releasePackageRoot;
110
+ let registry;
83
111
  try {
84
112
  root = fs.realpathSync.native(context.projectRootOf(a.root));
85
- if (!fs.existsSync(registryPath))
86
- return unregistered;
87
- const registry = (0, binding_1.readRuntimeRegistry)(registryPath);
88
- binding = registry.bindings.find((b) => b.workspaceRoot === root);
89
- releasePackageRoot = registry.releasePackageRoot;
90
113
  }
91
114
  catch (e) {
92
115
  return { ok: false, applied: false, reason: `runtime_binding: ${e.message}` };
93
116
  }
117
+ if (!fs.existsSync(registryPath))
118
+ return unboundAnswer(null, root);
119
+ try {
120
+ registry = (0, binding_1.readRuntimeRegistry)(registryPath);
121
+ }
122
+ catch (e) {
123
+ return unboundAnswer(null, root, e.message);
124
+ }
125
+ binding = registry.bindings.find((b) => b.workspaceRoot === root);
126
+ releasePackageRoot = registry.releasePackageRoot;
94
127
  if (binding === undefined)
95
- return unregistered;
128
+ return unboundAnswer(registry, root);
96
129
  const options = { operation: 'setup', workspace: root, packageRoot: binding.packageRoot, releasePackageRoot, registryPath,
97
130
  activateHooks: activate, ...(context.home !== undefined ? { home: context.home } : {}),
98
131
  ...(context.installerPackageRoot !== undefined ? { installerPackageRoot: context.installerPackageRoot } : {}) };
@@ -1,13 +1,13 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.createWorkspacePreflightHandlers = createWorkspacePreflightHandlers;
4
- // @implements A-SPEC-703
4
+ // @implements A-SPEC-703, A-SPEC-772.1
5
5
  const agents_1 = require("../../cli/agents");
6
6
  const workspace_preflight_1 = require("../../project/workspace-preflight");
7
7
  function createWorkspacePreflightHandlers(context) {
8
8
  return { async workspace_preflight(a) {
9
9
  if (a?.harness !== undefined && !agents_1.AGENTS.includes(a.harness))
10
10
  throw new Error('Unsupported harness.');
11
- return (0, workspace_preflight_1.inspectWorkspacePreflight)({ requestedRoot: a?.root, storeRoot: context.storeRoot });
11
+ return (0, workspace_preflight_1.inspectWorkspacePreflight)({ requestedRoot: a?.root, storeRoot: context.storeRoot, ...(a?.harness !== undefined ? { harness: a.harness } : {}) });
12
12
  } };
13
13
  }
@@ -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,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-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");
@@ -170,7 +170,8 @@ async function runDispatch(opts) {
170
170
  }
171
171
  const child = (0, node_child_process_1.spawn)(process.execPath, [path.join(selection.packageRoot, relative)], {
172
172
  cwd: selection.workspaceRoot,
173
- env: { ...process.env, HOLMES_SPECS: selection.specsRoot, CLAUDE_PROJECT_DIR: selection.workspaceRoot },
173
+ // @implements A-SPEC-772.1 — the hook records which harness and which routing it ran under.
174
+ env: { ...process.env, HOLMES_SPECS: selection.specsRoot, CLAUDE_PROJECT_DIR: selection.workspaceRoot, HOLMES_HOOK_HARNESS: opts.harness, HOLMES_HOOK_MODE: selection.mode },
174
175
  stdio: ['pipe', input ? 'pipe' : 'inherit', 'inherit'],
175
176
  detached: input !== undefined && process.platform !== 'win32', windowsHide: true,
176
177
  });
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.24",
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",