@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
@@ -36,13 +36,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.defaultRuntimeRegistry = void 0;
37
37
  exports.runtimeHookCommand = runtimeHookCommand;
38
38
  exports.wiringViewOf = wiringViewOf;
39
+ exports.codexProjectUntrusted = codexProjectUntrusted;
39
40
  exports.registryWiringOwnership = registryWiringOwnership;
40
41
  exports.registryOwnedWiring = registryOwnedWiring;
41
42
  exports.codexDuplicateRoutes = codexDuplicateRoutes;
42
43
  exports.runtimeBindingStatus = runtimeBindingStatus;
43
44
  exports.runRuntimeBinding = runRuntimeBinding;
44
45
  exports.trackedWorkspacePaths = trackedWorkspacePaths;
45
- // @implements A-SPEC-769.10, A-SPEC-752.11, A-SPEC-752.12, A-SPEC-752.13, A-SPEC-752.14, A-SPEC-752.15, A-SPEC-752.16, A-SPEC-752.17, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8
46
+ // @implements A-SPEC-769.10, A-SPEC-752.11, A-SPEC-752.12, A-SPEC-752.13, A-SPEC-752.14, A-SPEC-752.15, A-SPEC-752.16, A-SPEC-752.17, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8, A-SPEC-772.1, A-SPEC-772.2, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-772.12
46
47
  const fs = __importStar(require("node:fs"));
47
48
  const os = __importStar(require("node:os"));
48
49
  const path = __importStar(require("node:path"));
@@ -55,6 +56,8 @@ const runtime_binding_approval_1 = require("./runtime-binding-approval");
55
56
  const codex_toml_1 = require("./codex-toml");
56
57
  const codex_hooks_1 = require("./codex-hooks");
57
58
  const agents_1 = require("./agents");
59
+ const heartbeat_1 = require("../hooks/heartbeat");
60
+ const root_1 = require("../project/root");
58
61
  const defaultRuntimeRegistry = () => path.join(os.homedir(), '.holmes', 'runtime', 'bindings.json');
59
62
  exports.defaultRuntimeRegistry = defaultRuntimeRegistry;
60
63
  const digest = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
@@ -116,6 +119,9 @@ function runtimeHookCommand(registryPath, harness, entry) {
116
119
  */
117
120
  function wiringViewOf(file, content) {
118
121
  const name = path.basename(file);
122
+ // @implements A-SPEC-772.5 — every config.toml Holmes wires is Codex's, wherever CODEX_HOME puts it.
123
+ if (name === 'config.toml')
124
+ return codexConfigView(content);
119
125
  if ((name !== 'settings.json' && name !== 'settings.local.json') || path.basename(path.dirname(file)) !== '.claude')
120
126
  return content;
121
127
  let doc;
@@ -131,6 +137,77 @@ function wiringViewOf(file, content) {
131
137
  const { model: _model, ...rest } = doc;
132
138
  return JSON.stringify(rest);
133
139
  }
140
+ /**
141
+ * @implements A-SPEC-772.2 — Codex writes its own trust records (`hooks.state.*.trusted_hash`), project trust
142
+ * (`projects`) and notices (`tui`) into `~/.codex/config.toml` (measured 2026-10-17), so a whole-file digest disagreed
143
+ * with the receipt forever. The view drops exactly those; an `enabled` switch, which can turn Holmes off, stays.
144
+ */
145
+ function codexConfigView(content) {
146
+ const parsed = (0, codex_toml_1.parseCodexConfig)(content);
147
+ if (!parsed.ok)
148
+ return content;
149
+ const doc = JSON.parse(JSON.stringify(parsed.doc));
150
+ delete doc.tui;
151
+ // @implements A-SPEC-772.6 — `projects` is Codex's own per-repository trust, shared by every repository on the machine:
152
+ // one "No" anywhere made the receipt disagree forever (round 2). An untrusted governed workspace is named instead by
153
+ // `codexProjectUntrusted`.
154
+ delete doc.projects;
155
+ const hooks = doc.hooks;
156
+ if (object(hooks) && object(hooks.state)) {
157
+ const state = hooks.state;
158
+ for (const [key, entry] of Object.entries(state)) {
159
+ if (!object(entry))
160
+ continue;
161
+ delete entry.trusted_hash;
162
+ // @implements A-SPEC-772.5 — Codex's own re-enabling is not a change of wiring; a switch-off is.
163
+ if (entry.enabled === true)
164
+ delete entry.enabled;
165
+ if (Object.keys(entry).length === 0)
166
+ delete state[key];
167
+ }
168
+ if (Object.keys(state).length === 0)
169
+ delete hooks.state;
170
+ if (Object.keys(hooks).length === 0)
171
+ delete doc.hooks;
172
+ }
173
+ const sorted = (v) => Array.isArray(v) ? v.map(sorted)
174
+ : object(v) ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sorted(v[k])])) : v;
175
+ return JSON.stringify(sorted(doc));
176
+ }
177
+ /**
178
+ * @implements A-SPEC-772.6 — the `projects` key that marks `target` (or a directory above it) untrusted in a Codex
179
+ * config, or null. Codex does not load an untrusted project's hooks.
180
+ */
181
+ function codexProjectUntrusted(target, configPath) {
182
+ const raw = readOptional(configPath);
183
+ if (raw === null)
184
+ return null;
185
+ const parsed = (0, codex_toml_1.parseCodexConfig)(raw);
186
+ if (!parsed.ok)
187
+ return null;
188
+ const projects = parsed.doc.projects;
189
+ if (!object(projects))
190
+ return null;
191
+ let real = target;
192
+ try {
193
+ real = fs.realpathSync.native(target);
194
+ }
195
+ catch { /* as given */ }
196
+ // @implements A-SPEC-772.7 — the most specific key that contains the target decides (Codex looks up the exact project
197
+ // first): a trusted workspace under an untrusted parent is trusted.
198
+ let best = null;
199
+ for (const [key, entry] of Object.entries(projects)) {
200
+ if (!object(entry) || !path.isAbsolute(key))
201
+ continue;
202
+ const k = path.resolve(key);
203
+ if (![target, real].some((t) => (0, binding_1.inside)(k, t)))
204
+ continue;
205
+ const depth = k.split(path.sep).length;
206
+ if (best === null || depth > best.depth)
207
+ best = { key, depth, untrusted: entry.trust_level === 'untrusted' };
208
+ }
209
+ return best !== null && best.untrusted ? best.key : null;
210
+ }
134
211
  /**
135
212
  * @implements A-SPEC-752.8 — whether the installation receipt beside the operator registry lists `file`, and whether the
136
213
  * file still matches it. Measured 2026-10-04: init rewrote the user-level Codex files a setup plan had written, because
@@ -293,7 +370,67 @@ function runtimeBindingStatus(registryPath, workspace, opts) {
293
370
  }
294
371
  // @implements A-SPEC-769.8 — reported beside the receipt verdicts; it changes neither `conflicts` nor `router`.
295
372
  const duplicateRoutes = codexDuplicateRoutes(opts?.codexHome ?? path.join(os.homedir(), '.codex'), workspace);
296
- return { selection, conflicts, drift, duplicateRoutes, router: routerChanged ? 'changed' : 'intact', activation: 'unverified' };
373
+ // @implements A-SPEC-772.1 — a hook observed running in the selected workspace is reported, per harness.
374
+ // @implements A-SPEC-772.12 — read where the kernel writes: the directory holding `.ax`. The selection stops at a
375
+ // nested `.git` (round 8, L1: doctor said observed while status said unverified for the same run).
376
+ const governedRoot = (() => {
377
+ try {
378
+ const r = (0, root_1.resolveProjectRoot)(selection.workspaceRoot, { includeGit: false }).root;
379
+ return fs.existsSync(path.join(r, '.ax')) ? r : selection.workspaceRoot;
380
+ }
381
+ catch {
382
+ return selection.workspaceRoot;
383
+ }
384
+ })();
385
+ const beats = (0, heartbeat_1.readHookHeartbeats)(governedRoot);
386
+ const observed = {};
387
+ const observedUnrouted = {};
388
+ const observedOther = {};
389
+ const wiringEnv = { ...process.env, ...(opts?.codexHome ? { CODEX_HOME: opts.codexHome } : {}) };
390
+ const now = Date.now();
391
+ for (const harness of agents_1.AGENTS) {
392
+ const wiring = (0, heartbeat_1.hookWiringFiles)(governedRoot, harness, wiringEnv);
393
+ // @implements A-SPEC-772.7 — each event on its own: a routed PreToolUse is not hidden by a later Stop of another mode.
394
+ for (const event of ['pre-tool-use', 'stop']) {
395
+ const beat = beats[harness][event];
396
+ if (beat === undefined)
397
+ continue;
398
+ const one = { ...beats, [harness]: { [event]: beat } };
399
+ // @implements A-SPEC-772.5 — only a hook that ran under THIS selection (its mode and build) is its activation.
400
+ // @implements A-SPEC-772.6 — not when the harness's wiring changed after it.
401
+ const o = (0, heartbeat_1.observationOf)(one, harness, now, wiring);
402
+ if (o.state !== 'observed')
403
+ continue;
404
+ const latest = (rec) => { if (!rec[harness] || rec[harness] < o.at)
405
+ rec[harness] = o.at; };
406
+ // @implements A-SPEC-772.9 — activation is the PreToolUse GATE of this selection; a Stop alone does not count.
407
+ if (event === 'pre-tool-use' && o.mode === selection.mode && o.buildId === selection.buildId)
408
+ latest(observed);
409
+ // @implements A-SPEC-772.7 — a run without routing evidence is reported apart from activation.
410
+ // @implements A-SPEC-772.12 — each such event by name, PreToolUse first (round 8, L2: the latest time alone hid
411
+ // whether the gate itself ran unrouted).
412
+ else if (o.mode === 'unknown') {
413
+ const entry = `${event} at ${o.at} (build ${o.buildId})`;
414
+ observedUnrouted[harness] = observedUnrouted[harness] ? `${observedUnrouted[harness]}; ${entry}` : entry;
415
+ }
416
+ // @implements A-SPEC-772.10 — every other observation (a Stop of this selection, another build or mode) is named.
417
+ // @implements A-SPEC-772.11 — each uncounted event, PreToolUse first (events loop in that order); the latest
418
+ // alone hid an other-build PreToolUse behind the turn-end Stop (round 7).
419
+ else {
420
+ const entry = `${event} at ${o.at} (build ${o.buildId}, ${o.mode})`;
421
+ observedOther[harness] = observedOther[harness] ? `${observedOther[harness]}; ${entry}` : entry;
422
+ }
423
+ }
424
+ }
425
+ const activation = Object.keys(observed).length > 0 ? 'observed' : 'unverified';
426
+ // @implements A-SPEC-772.7 — the deployed dispatcher of 2026-10-15 did not pass HOLMES_HOOK_MODE while `router` said
427
+ // intact (round 3). @implements A-SPEC-772.8 — judged by that capability, not by bytes: one machine-wide copy serves
428
+ // every binding, so comparing it with the selected package was outdated forever for a development binding (round 4).
429
+ const routerOutdated = [];
430
+ const deployedDispatch = readOptional(path.join(path.dirname(registryPath), 'dispatch.js'));
431
+ if (deployedDispatch !== null && !deployedDispatch.includes('HOLMES_HOOK_MODE'))
432
+ routerOutdated.push('dispatch.js');
433
+ return { selection, conflicts, drift, duplicateRoutes, router: routerChanged ? 'changed' : 'intact', routerOutdated, activation, observed, observedUnrouted, observedOther };
297
434
  }
298
435
  function runRuntimeBinding(opts) {
299
436
  if (opts.activateHooks !== undefined && (!Array.isArray(opts.activateHooks)
@@ -0,0 +1,12 @@
1
+ /**
2
+ * @implements A-SPEC-773 — `holmes-kit scratch [--new <label>]`: print the Holmes scratch root, or make a fresh
3
+ * subdirectory under it and print that. A subdirectory is the agent's own temporary work: the gate lets a recursive
4
+ * rm of it through, in every harness. Exit 1 with the reason when the root is not this user's own 0700 directory.
5
+ */
6
+ export declare function runScratch(opts: {
7
+ label?: string;
8
+ tmpdir?: string;
9
+ }, io: {
10
+ stdout: (t: string) => void;
11
+ stderr: (t: string) => void;
12
+ }): number;
@@ -0,0 +1,20 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.runScratch = runScratch;
4
+ // @implements A-SPEC-773
5
+ const scratch_root_1 = require("../project/scratch-root");
6
+ /**
7
+ * @implements A-SPEC-773 — `holmes-kit scratch [--new <label>]`: print the Holmes scratch root, or make a fresh
8
+ * subdirectory under it and print that. A subdirectory is the agent's own temporary work: the gate lets a recursive
9
+ * rm of it through, in every harness. Exit 1 with the reason when the root is not this user's own 0700 directory.
10
+ */
11
+ function runScratch(opts, io) {
12
+ try {
13
+ io.stdout(`${opts.label === undefined ? (0, scratch_root_1.ensureScratchRoot)(opts.tmpdir) : (0, scratch_root_1.newScratchDir)(opts.label, opts.tmpdir)}\n`);
14
+ return 0;
15
+ }
16
+ catch (e) {
17
+ io.stderr(`holmes-kit scratch: ${e.message}\n`);
18
+ return 1;
19
+ }
20
+ }
@@ -49,7 +49,7 @@ exports.refusalsOutsideInbox = refusalsOutsideInbox;
49
49
  exports.grantableRequests = grantableRequests;
50
50
  exports.openOccurrences = openOccurrences;
51
51
  exports.asPendingRequest = asPendingRequest;
52
- // @implements A-SPEC-134.2, A-SPEC-244, A-SPEC-626, A-SPEC-752, A-SPEC-754
52
+ // @implements A-SPEC-134.2, A-SPEC-244, A-SPEC-626, A-SPEC-752, A-SPEC-754, A-SPEC-770.3, A-SPEC-770.6
53
53
  const execution_context_1 = require("../project/execution-context");
54
54
  const root_1 = require("../project/root");
55
55
  const node_crypto_1 = require("node:crypto");
@@ -98,7 +98,8 @@ exports.DECISION_KINDS = new Set([
98
98
  * @implements A-SPEC-134.2 — one wording for a request just filed and for one that was already pending.
99
99
  */
100
100
  function pendingRequestLine(id, kind, root) {
101
- const command = `${(0, npx_bin_1.npxBin)()} holmes-kit approve`;
101
+ // @implements A-SPEC-770.3 — the version that issued the hint, past any older copy the bare npx command resolves first.
102
+ const command = `${(0, npx_bin_1.holmesKitCommand)(root)} approve`; // A-SPEC-770.6 — the root the request is stored in
102
103
  // @implements A-SPEC-770.2 — the request lives in the refusal log / queue of the workspace whose hook refused, not in
103
104
  // the shell's cwd (measured 2026-10-12: a command run under a worktree filed its request in the development root;
104
105
  // 2026-10-13, Codex X1: the hint carried no `--target` at all). With a root, every command names it; a root with
@@ -527,7 +528,7 @@ function queueHint(root, req, opts) {
527
528
  + `\n운영자 검토: ${opts.reviewCommand}`;
528
529
  }
529
530
  return (0, screen_safe_1.wrapColumns)(question
530
- + ` 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 ${(0, npx_bin_1.npxBin)()} holmes-kit approve 에서 내립니다.`, 76, ' \u2502 ');
531
+ + ` 이 질문에 대한 답을 사용자에게 보고하십시오. 결정은 운영자가 ${(0, npx_bin_1.holmesKitCommand)(root)} approve 에서 내립니다.`, 76, ' \u2502 ');
531
532
  }
532
533
  const decided = state.decisions[id];
533
534
  const denialLine = decided?.event === 'denied'
@@ -39,6 +39,8 @@ export interface EditEvidenceInput {
39
39
  id: string;
40
40
  file: string;
41
41
  }>;
42
+ /** @implements A-SPEC-278.4 — the digest the artifact is stored under, so a verdict can name the analysis it read. */
43
+ artifactDigest?: string | null;
42
44
  }
43
45
  export interface EditEvidenceVerdict {
44
46
  decision: EditDecision;
@@ -37,7 +37,7 @@ exports.isLowRiskTarget = isLowRiskTarget;
37
37
  exports.evaluateEditEvidence = evaluateEditEvidence;
38
38
  exports.preEditEvidenceDecision = preEditEvidenceDecision;
39
39
  exports.loadEditEvidence = loadEditEvidence;
40
- // @implements A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3
40
+ // @implements A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3, A-SPEC-278.4, A-SPEC-278.6
41
41
  // @implements A-SPEC-278
42
42
  // @implements A-SPEC-277
43
43
  // @implements A-SPEC-276
@@ -69,7 +69,8 @@ function isLowRiskTarget(target) {
69
69
  return true;
70
70
  }
71
71
  const REMEDIATION = {
72
- 'no-analysis': 'Run maintenance_analyze({ root, request, persist: true }) for this change and retry with the digest it returns.',
72
+ // @implements A-SPEC-278.4 — an Edit or Write call carries no digest, so "retry with the digest" could not be followed.
73
+ 'no-analysis': 'Run maintenance_analyze({ root, request, persist: true }) for this change; the gate finds an analysis persisted at this HEAD by itself (impact_gate_check also accepts its digest).',
73
74
  'basis-drift': 'HEAD moved after the analysis was taken — re-run maintenance_analyze so the evidence is computed on the current commit.',
74
75
  // A separate code because it needs a separate sentence: dogfooding 2026-08-28 showed a file-drift
75
76
  // refusal explaining itself as "HEAD moved", which was simply false. Same lesson as A-SPEC-269.
@@ -156,7 +157,7 @@ function evaluateEditEvidence(inputArgs) {
156
157
  code: 'target-out-of-scope',
157
158
  detail: affectedOnly
158
159
  ? `${target} appears only as an impacted file, which is not the same as having been analysed as an edit candidate.`
159
- : `${target} is not among the files this analysis predicted.`,
160
+ : `${target} is not among the files this analysis${inputArgs.artifactDigest ? ` (${inputArgs.artifactDigest})` : ''} predicted.`,
160
161
  });
161
162
  escalate('widen');
162
163
  }
@@ -275,6 +276,11 @@ function newestPersistedAnalysis(projectRoot, target, currentHead) {
275
276
  }
276
277
  const newer = (a, b) => b === null || String(a.recordedAt ?? '') > String(b.recordedAt ?? '');
277
278
  let best = null;
279
+ let bestDigest = '';
280
+ // @implements A-SPEC-278.4 — the newest analysis at HEAD whether or not it covers the target: when nothing covers it,
281
+ // this analysis's own verdict (target-out-of-scope) is the truth, not "no analysis" (measured 2026-10-17).
282
+ let atHead = null;
283
+ let atHeadDigest = '';
278
284
  const older = [];
279
285
  let targetIsNew;
280
286
  const isNew = () => (targetIsNew ??= !gitOk(projectRoot, ['cat-file', '-e', `${currentHead}:${target}`]));
@@ -288,22 +294,32 @@ function newestPersistedAnalysis(projectRoot, target, currentHead) {
288
294
  }
289
295
  if (!Array.isArray(candidate?.predicted?.files) || typeof candidate?.graphBasis?.head !== 'string')
290
296
  continue;
297
+ // @implements A-SPEC-278.6 — an older-shape or corrupt artifact made the verdict throw for every target (round 1).
298
+ if (!Array.isArray(candidate?.uncertainty?.impactedFiles) || !Array.isArray(candidate?.uncertainty?.unknowns))
299
+ continue;
300
+ const digest = `sha256:${path.basename(file, '.json')}`;
291
301
  if (candidate.graphBasis.head !== currentHead) {
292
- older.push(candidate);
302
+ older.push({ artifact: candidate, digest });
293
303
  continue;
294
304
  }
305
+ if (newer(candidate, atHead)) {
306
+ atHead = candidate;
307
+ atHeadDigest = digest;
308
+ }
295
309
  if (!coversTarget(candidate, target, isNew))
296
310
  continue;
297
- if (newer(candidate, best))
311
+ if (newer(candidate, best)) {
298
312
  best = candidate;
313
+ bestDigest = digest;
314
+ }
299
315
  }
300
316
  if (best)
301
- return best;
317
+ return { artifact: best, digest: bestDigest };
302
318
  // @implements A-SPEC-278.2 (rule 2) — an analysis at an ancestor ≤ 20 commits back still describes this tree when every
303
319
  // file changed since it was predicted or named by its request (the RED commit adds only the request-named test). The
304
320
  // copy carries the current head so the basis is not reported as drifted; the target's own digest still is.
305
321
  const lineage = new Map();
306
- for (const candidate of older.sort((a, b) => String(b.recordedAt ?? '').localeCompare(String(a.recordedAt ?? '')))) {
322
+ for (const { artifact: candidate, digest } of older.sort((a, b) => String(b.artifact.recordedAt ?? '').localeCompare(String(a.artifact.recordedAt ?? '')))) {
307
323
  const a = candidate.graphBasis.head;
308
324
  if (!coversTarget(candidate, target, isNew))
309
325
  continue;
@@ -313,9 +329,12 @@ function newestPersistedAnalysis(projectRoot, target, currentHead) {
313
329
  lineage.set(a, unchangedOutside(projectRoot, a, currentHead, candidate));
314
330
  }
315
331
  if (lineage.get(a))
316
- return { ...candidate, graphBasis: { ...candidate.graphBasis, head: currentHead } };
332
+ return { artifact: { ...candidate, graphBasis: { ...candidate.graphBasis, head: currentHead } }, digest };
317
333
  }
318
- return null;
334
+ // @implements A-SPEC-278.4 — this replaces A-SPEC-278.1 #3 for an analysis AT HEAD that does not name the target.
335
+ // @implements A-SPEC-278.6 — not for a low-risk target: its exemption holds only with no artifact, and an unrelated
336
+ // analysis made block mode deny package.json (round 1).
337
+ return atHead && !isLowRiskTarget(target) ? { artifact: atHead, digest: atHeadDigest } : null;
319
338
  }
320
339
  /** @implements A-SPEC-278.2 — distinct ancestor heads examined per judgement (each costs three bounded git calls). */
321
340
  const LINEAGE_HEADS_MAX = 8;
@@ -387,12 +406,14 @@ function gitText(cwd, args) {
387
406
  function loadEditEvidence(projectRoot, target, digest, currentHead) {
388
407
  const rel = target.replace(/\\/g, '/');
389
408
  let artifact = null;
409
+ let artifactDigest = null;
390
410
  if (digest) {
391
411
  const bare = digest.startsWith('sha256:') ? digest.slice(7) : digest;
392
412
  if (/^[a-f0-9]{64}$/.test(bare)) {
393
413
  const file = path.join(projectRoot, '.ax', 'evidence', 'maintenance', `${bare}.json`);
394
414
  try {
395
415
  artifact = JSON.parse(fs.readFileSync(file, 'utf8'));
416
+ artifactDigest = `sha256:${bare}`;
396
417
  }
397
418
  catch {
398
419
  artifact = null;
@@ -400,7 +421,9 @@ function loadEditEvidence(projectRoot, target, digest, currentHead) {
400
421
  }
401
422
  }
402
423
  else {
403
- artifact = newestPersistedAnalysis(projectRoot, rel, currentHead);
424
+ const found = newestPersistedAnalysis(projectRoot, rel, currentHead);
425
+ artifact = found?.artifact ?? null;
426
+ artifactDigest = found?.digest ?? null;
404
427
  }
405
428
  let currentTargetDigest = null;
406
429
  try {
@@ -412,5 +435,5 @@ function loadEditEvidence(projectRoot, target, digest, currentHead) {
412
435
  catch {
413
436
  currentTargetDigest = null;
414
437
  }
415
- return { target: rel, artifact, currentHead, currentTargetDigest };
438
+ return { target: rel, artifact, currentHead, currentTargetDigest, artifactDigest };
416
439
  }
@@ -44,7 +44,7 @@ exports.classifyArchitectureReversal = classifyArchitectureReversal;
44
44
  exports.classifySecret = classifySecret;
45
45
  exports.classifyBlastRadius = classifyBlastRadius;
46
46
  exports.assessRisk = assessRisk;
47
- // @implements A-SPEC-125.1, A-SPEC-627, A-SPEC-728, A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2
47
+ // @implements A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2
48
48
  const fs = __importStar(require("node:fs"));
49
49
  const path = __importStar(require("node:path"));
50
50
  const shell_argument_roles_1 = require("./shell-argument-roles");
@@ -193,6 +193,14 @@ function isCatastrophicRmFloor(raw) {
193
193
  function rmTargetSafety(raw, sig) {
194
194
  if (isCatastrophicRmFloor(raw))
195
195
  return 'dangerous';
196
+ // @implements A-SPEC-773.1 — tracked source is dangerous even under the scratch root (round 1: a repository inside
197
+ // the root, cwd in it, `rm -rf src` was let through).
198
+ if (sig?.tracked)
199
+ return 'dangerous';
200
+ // @implements A-SPEC-773 — a subdirectory of the trusted Holmes scratch root is the agent's own temporary work
201
+ // (owner decision 2026-10-17). After the floor and the tracked veto, before the out-of-project veto.
202
+ if (sig?.scratch)
203
+ return 'safe';
196
204
  if (sig) {
197
205
  if (sig.tracked)
198
206
  return 'dangerous'; // git-tracked source under VCS
@@ -246,7 +254,11 @@ function rmDangerReason(cmd, signals) {
246
254
  const targets = rmTargets(seg);
247
255
  const safeties = targets.map((t) => rmTargetSafety(t, signals?.[t]));
248
256
  if (safeties.some((s) => s === 'dangerous')) {
249
- return 'recursive rm of a catastrophic / version-controlled / out-of-project / system target — whole-tree destruction';
257
+ // @implements A-SPEC-773.2 — an absolute target is where an agent's temporary work usually is: name the place
258
+ // whose directories it may remove (round 1, quality: nothing told an agent the scratch root exists).
259
+ const hint = targets.some((t) => t.replace(/^["']/, '').startsWith('/'))
260
+ ? '; agent temporary work belongs under `holmes-kit scratch --new <label>` (POSIX), whose directories an agent may remove' : '';
261
+ return `recursive rm of a catastrophic / version-controlled / out-of-project / system target — whole-tree destruction${hint}`;
250
262
  }
251
263
  if (targets.length > 0 && safeties.every((s) => s === 'safe'))
252
264
  continue; // all proven regenerable
@@ -10,6 +10,7 @@ export interface RmSignal {
10
10
  gitIgnored?: boolean;
11
11
  tracked?: boolean;
12
12
  inProject?: boolean;
13
+ scratch?: boolean;
13
14
  }
14
15
  export interface RiskAction {
15
16
  kind: string;
@@ -37,7 +37,7 @@ exports.TOOL_MAP = void 0;
37
37
  exports.shippedHookTimeoutMs = shippedHookTimeoutMs;
38
38
  exports.adaptPreToolUse = adaptPreToolUse;
39
39
  exports.adaptStop = adaptStop;
40
- // @implements A-SPEC-193
40
+ // @implements A-SPEC-193, A-SPEC-772.1
41
41
  // @implements A-SPEC-734
42
42
  // @implements A-SPEC-769.10, A-SPEC-769.11
43
43
  const fs = __importStar(require("node:fs"));
@@ -73,7 +73,8 @@ function shippedHookTimeoutMs(hookPath) {
73
73
  const runShippedHook = (hookPath, payload, cwd) => {
74
74
  const r = (0, node_child_process_1.spawnSync)(process.execPath, [hookPath], {
75
75
  cwd, input: payload, encoding: 'utf8', timeout: shippedHookTimeoutMs(hookPath),
76
- env: { ...process.env },
76
+ // @implements A-SPEC-772.1 — the kernel cannot tell an Antigravity call from its translated input; name it.
77
+ env: { ...process.env, HOLMES_HOOK_HARNESS: 'antigravity' },
77
78
  });
78
79
  // @implements A-SPEC-734 (round 16) — three-harness parity: the hook's "not judged" notices reach the harness as
79
80
  // they do for Claude and Codex (the adapter dropped every one — measured).
@@ -0,0 +1,47 @@
1
+ import { Agent } from '../cli/agent-registry';
2
+ export declare const HEARTBEAT_DIR: string;
3
+ export type HookEvent = 'pre-tool-use' | 'stop';
4
+ declare const SCHEMA = "holmes-hook-heartbeat/1";
5
+ export declare const OBSERVED_WITHIN_MS: number;
6
+ /** @implements A-SPEC-772.7 — `unknown`: no routing evidence (a direct-wired kernel and an older deployed dispatcher look alike). */
7
+ export interface HookBeat {
8
+ schema: typeof SCHEMA;
9
+ harness: Agent;
10
+ event: HookEvent;
11
+ at: string;
12
+ buildId: string;
13
+ mode: 'development' | 'release' | 'unknown';
14
+ }
15
+ export type HookBeats = Record<Agent, Partial<Record<HookEvent, HookBeat>>>;
16
+ export type HookObservation = {
17
+ state: 'observed' | 'stale';
18
+ event: HookEvent;
19
+ at: string;
20
+ buildId: string;
21
+ mode: HookBeat['mode'];
22
+ ageMs: number;
23
+ reason?: 'wiring changed since';
24
+ } | {
25
+ state: 'never';
26
+ };
27
+ /** The harness a hook call belongs to, or null when the evidence is absent or contradicts itself. */
28
+ export declare function hookHarnessOf(input: unknown, env: Record<string, string | undefined>): Agent | null;
29
+ export declare function recordHookHeartbeat(opts: {
30
+ root: string;
31
+ event: HookEvent;
32
+ input: unknown;
33
+ env: Record<string, string | undefined>;
34
+ now?: number;
35
+ buildId?: string;
36
+ }): void;
37
+ export declare function readHookHeartbeats(root: string, now?: number): HookBeats;
38
+ /** The latest PreToolUse or Stop record of a harness: observed within 24 h, stale beyond, never without one. */
39
+ export declare function observationOf(beats: HookBeats, harness: Agent, now?: number, wiringFiles?: readonly string[], event?: HookEvent): HookObservation;
40
+ /**
41
+ * @implements A-SPEC-772.6 — the files whose change can stop a harness running its Holmes hooks in `root`: what Claude,
42
+ * Codex and Antigravity read their hooks from (Codex's workspace trust too; its user-level trust file is excluded).
43
+ */
44
+ export declare function hookWiringFiles(root: string, harness: Agent, env?: Record<string, string | undefined>): string[];
45
+ /** "3 min", "5 h", "2 d" — for a stale observation's detail. */
46
+ export declare function ageText(ms: number): string;
47
+ export {};