@holmes-lab/holmes-kit 0.35.22 → 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.
@@ -0,0 +1,247 @@
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.OBSERVED_WITHIN_MS = exports.HEARTBEAT_DIR = void 0;
37
+ exports.hookHarnessOf = hookHarnessOf;
38
+ exports.recordHookHeartbeat = recordHookHeartbeat;
39
+ exports.readHookHeartbeats = readHookHeartbeats;
40
+ exports.observationOf = observationOf;
41
+ exports.hookWiringFiles = hookWiringFiles;
42
+ exports.ageText = ageText;
43
+ // @implements A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9
44
+ /**
45
+ * Evidence that a harness's hooks actually ran in a workspace.
46
+ *
47
+ * Measured 2026-10-17: a Codex session in holmes-lab could not tell it was governed — the dispatcher routed it to the
48
+ * release build and its Stop hook had run, but nothing recorded either, so `workspace_preflight` and
49
+ * `runtime-binding status` could only say "unknown"/"unverified".
50
+ *
51
+ * The harness is told from the hook INPUT, never from the environment: a Codex hook launched from a Claude Code
52
+ * terminal received `CLAUDECODE=1`. Claude sends `prompt_id` and no `turn_id`; Codex sends `turn_id` and no
53
+ * `prompt_id`. Holmes's own launchers (the runtime dispatcher, the Antigravity adapter) name the harness explicitly in
54
+ * `HOLMES_HOOK_HARNESS`; when that and the shape both speak they must agree.
55
+ *
56
+ * Recording is off the decision path: one stat per call, at most one small write per harness and event per minute,
57
+ * and every failure is swallowed.
58
+ *
59
+ * @implements A-SPEC-772.5 — an observation is INFORMATION ONLY. Anyone who can run a hook program can produce one, so
60
+ * no gate, approval or seal may read it as authority.
61
+ */
62
+ const fs = __importStar(require("node:fs"));
63
+ const os = __importStar(require("node:os"));
64
+ const path = __importStar(require("node:path"));
65
+ // @implements A-SPEC-772.6 — the import-free registry: this module runs inside every hook call.
66
+ const agent_registry_1 = require("../cli/agent-registry");
67
+ exports.HEARTBEAT_DIR = path.join('.ax', 'state', 'hook-heartbeat');
68
+ const EVENTS = ['pre-tool-use', 'stop'];
69
+ const SCHEMA = 'holmes-hook-heartbeat/1';
70
+ const WRITE_EVERY_MS = 60_000;
71
+ exports.OBSERVED_WITHIN_MS = 24 * 3600_000;
72
+ const MAX_RECORD_BYTES = 4096;
73
+ const FUTURE_TOLERANCE_MS = 5 * 60_000;
74
+ const validBuildId = (id) => typeof id === 'string' && id.length > 0 && id.length <= 200 && !/[\x00-\x1f\x7f]/.test(id);
75
+ const isLink = (p) => { try {
76
+ return fs.lstatSync(p).isSymbolicLink();
77
+ }
78
+ catch {
79
+ return false;
80
+ } };
81
+ const isAgent = (v) => typeof v === 'string' && agent_registry_1.AGENTS.includes(v);
82
+ /** The harness a hook call belongs to, or null when the evidence is absent or contradicts itself. */
83
+ function hookHarnessOf(input, env) {
84
+ const o = input !== null && typeof input === 'object' ? input : {};
85
+ const hasPrompt = typeof o.prompt_id === 'string' && o.prompt_id !== '';
86
+ const hasTurn = typeof o.turn_id === 'string' && o.turn_id !== '';
87
+ const shape = hasPrompt && !hasTurn ? 'claude' : hasTurn && !hasPrompt ? 'codex' : null;
88
+ const named = env.HOLMES_HOOK_HARNESS;
89
+ if (named !== undefined && named !== '') {
90
+ if (!isAgent(named))
91
+ return null;
92
+ if (shape !== null && shape !== named)
93
+ return null;
94
+ return named;
95
+ }
96
+ return shape;
97
+ }
98
+ /** The running package's build id (dist/.build-id next to this compiled file), or 'unknown'. */
99
+ function runningBuildId() {
100
+ try {
101
+ const id = fs.readFileSync(path.resolve(__dirname, '..', '..', '.build-id'), 'utf8').trim();
102
+ return id && id.length <= 200 && !/[\x00-\x1f\x7f]/.test(id) ? id : 'unknown';
103
+ }
104
+ catch {
105
+ return 'unknown';
106
+ }
107
+ }
108
+ function recordHookHeartbeat(opts) {
109
+ try {
110
+ if (typeof opts.root !== 'string' || !EVENTS.includes(opts.event))
111
+ return;
112
+ // @implements A-SPEC-772.9 — a test that spawns the real kernel inside the repository turns recording off; an
113
+ // observation is information only, so the switch changes no decision.
114
+ if (opts.env.HOLMES_HEARTBEAT === 'off')
115
+ return;
116
+ if (!fs.existsSync(path.join(opts.root, '.ax')))
117
+ return;
118
+ const harness = hookHarnessOf(opts.input, opts.env);
119
+ if (harness === null)
120
+ return;
121
+ const now = opts.now ?? Date.now();
122
+ const dir = path.join(opts.root, exports.HEARTBEAT_DIR);
123
+ // @implements A-SPEC-772.5 — never write through a link out of the workspace.
124
+ if (isLink(path.join(opts.root, '.ax', 'state')) || isLink(dir))
125
+ return;
126
+ const file = path.join(dir, `${harness}.${opts.event}.json`);
127
+ // @implements A-SPEC-772.5 — a record "modified in the future" (clock stepped back, restored file) does not block.
128
+ try {
129
+ const age = now - fs.statSync(file).mtimeMs;
130
+ if (age >= 0 && age < WRITE_EVERY_MS)
131
+ return;
132
+ }
133
+ catch { /* no record yet */ }
134
+ const mode = opts.env.HOLMES_HOOK_MODE === 'development' || opts.env.HOLMES_HOOK_MODE === 'release' ? opts.env.HOLMES_HOOK_MODE : 'unknown';
135
+ const beat = { schema: SCHEMA, harness, event: opts.event, at: new Date(now).toISOString(), buildId: opts.buildId ?? runningBuildId(), mode };
136
+ fs.mkdirSync(dir, { recursive: true });
137
+ const tmp = path.join(dir, `.${harness}.${opts.event}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
138
+ fs.writeFileSync(tmp, JSON.stringify(beat), { flag: 'wx' });
139
+ try {
140
+ fs.renameSync(tmp, file);
141
+ }
142
+ catch {
143
+ try {
144
+ fs.rmSync(tmp, { force: true });
145
+ }
146
+ catch { /* ignore */ }
147
+ }
148
+ // The rate limit reads the record's mtime: make it the observation time, so an injected clock is honoured too.
149
+ try {
150
+ const t = new Date(now);
151
+ fs.utimesSync(file, t, t);
152
+ }
153
+ catch { /* ignore */ }
154
+ }
155
+ catch { /* recording never affects a hook */ }
156
+ }
157
+ function readBeat(file, harness, event, now) {
158
+ try {
159
+ const st = fs.lstatSync(file);
160
+ if (!st.isFile() || st.size > MAX_RECORD_BYTES)
161
+ return undefined;
162
+ const b = JSON.parse(fs.readFileSync(file, 'utf8'));
163
+ if (b?.schema !== SCHEMA || b.harness !== harness || b.event !== event)
164
+ return undefined;
165
+ // @implements A-SPEC-772.5 — a record from the future, or a build id the writer would refuse, is not evidence.
166
+ if (typeof b.at !== 'string' || !Number.isFinite(Date.parse(b.at)) || Date.parse(b.at) > now + FUTURE_TOLERANCE_MS || !validBuildId(b.buildId))
167
+ return undefined;
168
+ // @implements A-SPEC-772.7 — a record written as `direct` (before this repair) carried no routing evidence either.
169
+ if (b.mode === 'direct')
170
+ b.mode = 'unknown';
171
+ if (!['development', 'release', 'unknown'].includes(b.mode))
172
+ return undefined;
173
+ return b;
174
+ }
175
+ catch {
176
+ return undefined;
177
+ }
178
+ }
179
+ function readHookHeartbeats(root, now = Date.now()) {
180
+ const out = Object.fromEntries(agent_registry_1.AGENTS.map((a) => [a, {}]));
181
+ for (const harness of agent_registry_1.AGENTS) {
182
+ for (const event of EVENTS) {
183
+ const b = readBeat(path.join(root, exports.HEARTBEAT_DIR, `${harness}.${event}.json`), harness, event, now);
184
+ if (b)
185
+ out[harness][event] = b;
186
+ }
187
+ }
188
+ return out;
189
+ }
190
+ /** The latest PreToolUse or Stop record of a harness: observed within 24 h, stale beyond, never without one. */
191
+ function observationOf(beats, harness, now = Date.now(), wiringFiles, event) {
192
+ // @implements A-SPEC-772.8 — `event` narrows to one hook (the PreToolUse gate is what pass means).
193
+ const latest = EVENTS.filter((e) => event === undefined || e === event).map((e) => beats[harness]?.[e]).filter((b) => b !== undefined)
194
+ .sort((a, b) => Date.parse(b.at) - Date.parse(a.at))[0];
195
+ if (!latest)
196
+ return { state: 'never' };
197
+ const ageMs = now - Date.parse(latest.at);
198
+ const base = { event: latest.event, at: latest.at, buildId: latest.buildId, mode: latest.mode, ageMs };
199
+ // @implements A-SPEC-772.6 — a hook observed before its wiring changed proves nothing about the wiring now (setup
200
+ // rewrites hooks Codex must re-trust; /hooks can switch one off).
201
+ if (wiringFiles && Date.parse(latest.at) < latestMtime(wiringFiles, now))
202
+ return { state: 'stale', ...base, reason: 'wiring changed since' };
203
+ return { state: ageMs <= exports.OBSERVED_WITHIN_MS ? 'observed' : 'stale', ...base };
204
+ }
205
+ function latestMtime(files, now = Date.now()) {
206
+ let max = -Infinity;
207
+ // @implements A-SPEC-772.7 — a wiring file "modified in the future" (restored, clock skew) would make every record stale forever.
208
+ for (const f of files) {
209
+ try {
210
+ const m = fs.statSync(f).mtimeMs;
211
+ if (m <= now + FUTURE_TOLERANCE_MS)
212
+ max = Math.max(max, m);
213
+ }
214
+ catch { /* absent */ }
215
+ }
216
+ return max;
217
+ }
218
+ /**
219
+ * @implements A-SPEC-772.6 — the files whose change can stop a harness running its Holmes hooks in `root`: what Claude,
220
+ * Codex and Antigravity read their hooks from (Codex's workspace trust too; its user-level trust file is excluded).
221
+ */
222
+ function hookWiringFiles(root, harness, env = process.env) {
223
+ // @implements A-SPEC-772.7 — the home other readers use (os.homedir()) unless the caller names one.
224
+ const home = (process.platform === 'win32' ? env.USERPROFILE : env.HOME) || os.homedir();
225
+ if (harness === 'claude') {
226
+ const user = env.CLAUDE_CONFIG_DIR ? path.resolve(env.CLAUDE_CONFIG_DIR) : path.join(home, '.claude');
227
+ return [path.join(user, 'settings.json'), path.join(root, '.claude', 'settings.json'), path.join(root, '.claude', 'settings.local.json')];
228
+ }
229
+ if (harness === 'codex') {
230
+ // @implements A-SPEC-772.7 — the user-level config.toml is machine-shared: Codex and its desktop app rewrite it for
231
+ // other repositories and plugin syncs (measured), which flipped every workspace's observation.
232
+ // @implements A-SPEC-772.8 — the workspace's own Codex files are in. Known limit: a user-level `/hooks` switch-off
233
+ // or plugin disable lives in that shared file and is not detected here.
234
+ const codex = env.CODEX_HOME ? path.resolve(env.CODEX_HOME) : path.join(home, '.codex');
235
+ return [path.join(codex, 'hooks.json'), path.join(root, '.codex', 'hooks.json'), path.join(root, '.codex', 'config.toml'),
236
+ path.join(root, '.holmes', 'codex-plugin', 'holmes-kit', 'hooks.json')];
237
+ }
238
+ return [path.join(home, '.gemini', 'config', 'hooks.json'), path.join(root, '.agents', 'hooks.json')];
239
+ }
240
+ /** "3 min", "5 h", "2 d" — for a stale observation's detail. */
241
+ function ageText(ms) {
242
+ if (ms < 3600_000)
243
+ return `${Math.max(1, Math.round(ms / 60_000))} min`;
244
+ if (ms < 48 * 3600_000)
245
+ return `${Math.round(ms / 3600_000)} h`;
246
+ return `${Math.round(ms / 86_400_000)} d`;
247
+ }
@@ -48,7 +48,7 @@ exports.gateErrorDecision = gateErrorDecision;
48
48
  exports.wiredSpecsDir = wiredSpecsDir;
49
49
  exports.evaluateHook = evaluateHook;
50
50
  exports.readSpecsSync = readSpecsSync;
51
- // @implements A-SPEC-753.3, A-SPEC-134.2, A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753, A-SPEC-163.7, A-SPEC-768.2
51
+ // @implements A-SPEC-753.3, A-SPEC-134.2, A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753, A-SPEC-163.7, A-SPEC-768.2, A-SPEC-772.1
52
52
  const shell_argument_roles_1 = require("../guardrail/shell-argument-roles");
53
53
  // @implements A-SPEC-549.3 — the hook's deny reasons are English here; hooks-english.test.ts drives
54
54
  // evaluateHook in this file to prove it.
@@ -2797,7 +2797,8 @@ if (require.main === module) {
2797
2797
  try {
2798
2798
  // @implements A-SPEC-144 — normalize BEFORE deciding: most of the measured bypasses were a
2799
2799
  // wrong type reaching code that assumed a string, not an interesting failure of the gate.
2800
- const input = normalizeHookInput(JSON.parse(buf || '{}'));
2800
+ const rawHookInput = JSON.parse(buf || '{}');
2801
+ const input = normalizeHookInput(rawHookInput);
2801
2802
  // @implements A-SPEC-149
2802
2803
  // The ONE place process context is read. `evaluateHook` no longer reaches for `process.cwd()`
2803
2804
  // or `process.env` on its own, so a caller always states which project it is judging and under
@@ -2837,6 +2838,10 @@ if (require.main === module) {
2837
2838
  return { root: process.cwd(), anchored: false };
2838
2839
  })();
2839
2840
  const hookProjectRoot = hookRoot.root;
2841
+ // @implements A-SPEC-772.1 — evidence that this harness's gate ran here; off the decision path, never throws.
2842
+ if (hookRoot.anchored) {
2843
+ require('./heartbeat').recordHookHeartbeat({ root: hookProjectRoot, event: 'pre-tool-use', input: rawHookInput, env: process.env });
2844
+ }
2840
2845
  // @implements A-SPEC-191 §17 (round 11) — and the SPECS the gate judges against come from the
2841
2846
  // same tree. Round-10 moved the project root here and left this path relative, so a session
2842
2847
  // opened in a subdirectory looked for `<sub>/.ax/specs`, found nothing, and `isGovernedProject`
@@ -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.22",
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",