@holmes-lab/holmes-kit 0.35.19 → 0.35.21

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 (35) hide show
  1. package/CHANGELOG.md +103 -0
  2. package/README.md +2 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents.js +13 -7
  5. package/dist/holmes/cli/codex-hooks.js +3 -1
  6. package/dist/holmes/cli/doctor.d.ts +12 -0
  7. package/dist/holmes/cli/doctor.js +194 -1
  8. package/dist/holmes/cli/init.js +2 -1
  9. package/dist/holmes/cli/runtime-binding.js +4 -3
  10. package/dist/holmes/cli/settings-merge.d.ts +1 -0
  11. package/dist/holmes/cli/settings-merge.js +6 -2
  12. package/dist/holmes/cpg/scan-cache.d.ts +12 -1
  13. package/dist/holmes/cpg/scan-cache.js +83 -2
  14. package/dist/holmes/hooks/adapters/antigravity.d.ts +2 -0
  15. package/dist/holmes/hooks/adapters/antigravity.js +8 -1
  16. package/dist/holmes/hooks/rtm-refresh-child.d.ts +43 -0
  17. package/dist/holmes/hooks/rtm-refresh-child.js +110 -10
  18. package/dist/holmes/hooks/rtm-refresh.d.ts +23 -0
  19. package/dist/holmes/hooks/rtm-refresh.js +124 -12
  20. package/dist/holmes/hooks/stop.d.ts +8 -0
  21. package/dist/holmes/hooks/stop.js +20 -5
  22. package/dist/holmes/mcp/handlers/graph-operations.js +7 -4
  23. package/dist/holmes/mcp/handlers/requirement-triage.js +6 -2
  24. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +7 -0
  25. package/dist/holmes/mcp/requirement-triage-evidence.js +18 -7
  26. package/dist/holmes/project/bounded-io.d.ts +1 -0
  27. package/dist/holmes/project/bounded-io.js +3 -1
  28. package/dist/holmes/refresh/freshness-coordinator.d.ts +28 -0
  29. package/dist/holmes/refresh/freshness-coordinator.js +85 -2
  30. package/dist/holmes/runtime/dispatch.js +5 -3
  31. package/dist/holmes/runtime/hook-process.d.ts +8 -0
  32. package/dist/holmes/runtime/hook-process.js +13 -1
  33. package/dist/holmes/semantic/embedder.d.ts +6 -0
  34. package/dist/holmes/semantic/embedder.js +10 -0
  35. package/package.json +1 -1
@@ -34,9 +34,14 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.ScanFileCache = exports.SCAN_CACHE_VERSION = void 0;
37
+ exports.scanCacheDirFor = scanCacheDirFor;
37
38
  // @implements A-SPEC-208
38
39
  // @implements A-SPEC-113.1
40
+ // @implements A-SPEC-769.9
41
+ // @implements A-SPEC-769.11
42
+ // @implements A-SPEC-769.12
39
43
  const fs = __importStar(require("node:fs"));
44
+ const os = __importStar(require("node:os"));
40
45
  const path = __importStar(require("node:path"));
41
46
  const node_crypto_1 = require("node:crypto");
42
47
  function cloneExpr(e) {
@@ -62,16 +67,41 @@ function cloneDataFlow(df) {
62
67
  // version-3 entry has none, and serving it would put every anchor back on the file for as long as
63
68
  // the file's content did not change.
64
69
  exports.SCAN_CACHE_VERSION = 4;
70
+ /**
71
+ * @implements A-SPEC-769.9 — the one cache directory per workspace root, shared by the refresh child and the Stop
72
+ * hook. Measured 2026-10-15: the Stop hook's uncached scan took 23.0 s of its budget; served from here, 0.48 s.
73
+ */
74
+ function scanCacheDirFor(root, tmp = os.tmpdir()) {
75
+ // @implements A-SPEC-769.11 — a governed workspace keeps the cache in its own .ax (the directory the MCP server
76
+ // uses): the Stop GATE reads it, and a name anyone can compute in the shared /tmp let another local user plant it.
77
+ try {
78
+ if (fs.statSync(path.join(root, '.ax')).isDirectory())
79
+ return path.join(root, '.ax', 'cpg_cache');
80
+ }
81
+ catch { /* not governed */ }
82
+ return path.join(tmp, 'holmes-cpg-cache-' + (0, node_crypto_1.createHash)('sha256').update(root).digest('hex').slice(0, 16));
83
+ }
84
+ // @implements A-SPEC-769.11 — temporary files are `scan-cache.json.<suffix>.tmp`; one older than this is left over
85
+ // from a writer that died between create and rename.
86
+ const TEMP_SWEEP_MS = 10 * 60_000;
87
+ const TEMP_NAME = /^scan-cache\.json\.[0-9a-z.]+\.tmp$/; // the dots admit the former `<pid>.<ms>` names
65
88
  class ScanFileCache {
66
89
  dir;
67
90
  file;
91
+ tempSuffix;
92
+ axDir;
68
93
  entries;
69
94
  seen = new Set();
70
95
  dirty = false;
71
96
  hits = 0;
72
97
  misses = 0;
73
- constructor(dir) {
98
+ constructor(dir, opts = {}) {
74
99
  this.dir = dir;
100
+ this.tempSuffix = opts.tempSuffix ?? (() => (0, node_crypto_1.randomBytes)(6).toString('hex'));
101
+ // @implements A-SPEC-769.12, A-SPEC-769.13 — the `.ax` this cache lives under: a save never brings it back.
102
+ const parts = path.resolve(dir).split(path.sep);
103
+ const ax = parts.map((p) => p.toLowerCase()).lastIndexOf('.ax'); // case-insensitive volumes spell it `.AX` too
104
+ this.axDir = ax > 0 ? parts.slice(0, ax + 1).join(path.sep) : null;
75
105
  this.file = path.join(dir, 'scan-cache.json');
76
106
  try {
77
107
  const raw = JSON.parse(fs.readFileSync(this.file, 'utf8'));
@@ -133,13 +163,64 @@ class ScanFileCache {
133
163
  }
134
164
  try {
135
165
  if (this.dirty) {
166
+ // @implements A-SPEC-769.12 — never create a `.ax`: a recursive create recreated one that was removed while the scan
167
+ // ran (init --remove, a deleted workspace), resurrecting the governed marker. Other parents are created as before.
168
+ // @implements A-SPEC-769.13 — whether `.ax` vanished before or after construction: never create it here.
169
+ if (this.axDir !== null && !fs.existsSync(this.axDir))
170
+ throw new Error('the workspace .ax is gone');
136
171
  fs.mkdirSync(this.dir, { recursive: true });
137
- fs.writeFileSync(this.file, JSON.stringify({ v: exports.SCAN_CACHE_VERSION, entries: this.entries }), 'utf8');
172
+ // @implements A-SPEC-769.9 — the Stop hook and the refresh child share this file: a reader in the other
173
+ // process sees the old or the new content, never a partly written one.
174
+ // @implements A-SPEC-769.11 — an unpredictable name created exclusively: a file or link already at that name
175
+ // fails the create (another name is tried) and is never written through.
176
+ const body = JSON.stringify({ v: exports.SCAN_CACHE_VERSION, entries: this.entries });
177
+ let tmp;
178
+ for (let attempt = 0; attempt < 3 && tmp === undefined; attempt++) {
179
+ const candidate = `${this.file}.${this.tempSuffix()}.tmp`;
180
+ try {
181
+ fs.writeFileSync(candidate, body, { encoding: 'utf8', flag: 'wx' });
182
+ tmp = candidate;
183
+ }
184
+ catch (error) {
185
+ if (error.code !== 'EEXIST')
186
+ throw error;
187
+ }
188
+ }
189
+ if (tmp === undefined)
190
+ throw new Error('no free temporary name');
191
+ try {
192
+ fs.renameSync(tmp, this.file);
193
+ }
194
+ catch (error) {
195
+ try {
196
+ fs.rmSync(tmp, { force: true });
197
+ }
198
+ catch { /* nothing more to undo */ }
199
+ throw error;
200
+ }
138
201
  this.dirty = false;
202
+ this.sweepTemporaries();
139
203
  }
140
204
  }
141
205
  catch { /* cache persistence is best-effort — next scan just runs colder */ }
142
206
  this.seen.clear();
143
207
  }
208
+ /** @implements A-SPEC-769.11 — removes temporary files of this cache's shape older than ten minutes. */
209
+ sweepTemporaries() {
210
+ try {
211
+ const cutoff = Date.now() - TEMP_SWEEP_MS;
212
+ for (const name of fs.readdirSync(this.dir)) {
213
+ if (!TEMP_NAME.test(name))
214
+ continue;
215
+ const p = path.join(this.dir, name);
216
+ try {
217
+ if (fs.lstatSync(p).mtimeMs < cutoff)
218
+ fs.rmSync(p, { force: true });
219
+ }
220
+ catch { /* raced with its writer */ }
221
+ }
222
+ }
223
+ catch { /* best-effort */ }
224
+ }
144
225
  }
145
226
  exports.ScanFileCache = ScanFileCache;
@@ -26,6 +26,8 @@ export declare const TOOL_MAP: Record<string, {
26
26
  }>;
27
27
  /** 훅을 실행해 그 표준 출력을 돌려준다. 실행 자체가 실패하면 `null`(호출자가 닫는 쪽으로 받는다). */
28
28
  export type HookRunner = (hookPath: string, payload: string, cwd: string) => Record<string, unknown> | null;
29
+ /** @implements A-SPEC-769.10, A-SPEC-769.11 — stop.js gets the Stop budget; the other hooks keep 30 s. */
30
+ export declare function shippedHookTimeoutMs(hookPath: string): number;
29
31
  /**
30
32
  * PreToolUse: Antigravity 의 말 → 게이트 → Antigravity 의 말.
31
33
  *
@@ -34,13 +34,16 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.TOOL_MAP = void 0;
37
+ exports.shippedHookTimeoutMs = shippedHookTimeoutMs;
37
38
  exports.adaptPreToolUse = adaptPreToolUse;
38
39
  exports.adaptStop = adaptStop;
39
40
  // @implements A-SPEC-193
40
41
  // @implements A-SPEC-734
42
+ // @implements A-SPEC-769.10, A-SPEC-769.11
41
43
  const fs = __importStar(require("node:fs"));
42
44
  const path = __importStar(require("node:path"));
43
45
  const node_child_process_1 = require("node:child_process");
46
+ const hook_process_1 = require("../../runtime/hook-process");
44
47
  const bounded_io_1 = require("../../project/bounded-io");
45
48
  /**
46
49
  * 실측한 도구만 등재한다.
@@ -63,9 +66,13 @@ exports.TOOL_MAP = {
63
66
  const str = (v) => (typeof v === 'string' ? v : undefined);
64
67
  /** 출하된 훅 프로그램의 자리 — 이 파일에서 패키지 뿌리로 올라간다. */
65
68
  const shippedHook = (name) => path.resolve(__dirname, '..', '..', '..', '..', 'dist', 'holmes', 'hooks', name);
69
+ /** @implements A-SPEC-769.10, A-SPEC-769.11 — stop.js gets the Stop budget; the other hooks keep 30 s. */
70
+ function shippedHookTimeoutMs(hookPath) {
71
+ return path.basename(hookPath) === 'stop.js' ? hook_process_1.STOP_HOOK_BUDGET_MS : 30_000;
72
+ }
66
73
  const runShippedHook = (hookPath, payload, cwd) => {
67
74
  const r = (0, node_child_process_1.spawnSync)(process.execPath, [hookPath], {
68
- cwd, input: payload, encoding: 'utf8', timeout: 30_000,
75
+ cwd, input: payload, encoding: 'utf8', timeout: shippedHookTimeoutMs(hookPath),
69
76
  env: { ...process.env },
70
77
  });
71
78
  // @implements A-SPEC-734 (round 16) — three-harness parity: the hook's "not judged" notices reach the harness as
@@ -1,10 +1,52 @@
1
1
  import { FreshnessLane, FreshnessReceipt, RefreshFailure } from '../refresh/freshness-coordinator';
2
+ type HeadProbe = (root: string) => {
3
+ head: string | null;
4
+ unanswered: boolean;
5
+ };
2
6
  /** The error as a bounded reason: its message (never a stack), at most REFRESH_FAILURE_REASON_MAX characters. */
3
7
  export declare function failureReason(error: unknown): string;
4
8
  /** The detached worker must publish its own failure; the parent is intentionally non-blocking. */
5
9
  export declare function recordRefreshFailure(root: string, generation: string, head: string | null, now: Date, failure?: RefreshFailure): FreshnessReceipt | null;
10
+ /**
11
+ * @implements A-SPEC-719.1 — the worker's own deadline. A live worker keeps its lease up to FRESHNESS_WORKER_MAX_MS;
12
+ * at that point it publishes `retry-at` (a no-op when a newer lease superseded it) and ends, so the next request
13
+ * spawns exactly one replacement instead of a worker running beside it.
14
+ */
15
+ export declare function armWorkerDeadline(root: string, generation: string, opts: {
16
+ ms: number;
17
+ exit: () => void;
18
+ now?: () => Date;
19
+ }): void;
20
+ /**
21
+ * @implements A-SPEC-719.2 — the worker yields the machine. Measured 2026-10-15: each child ran at default priority with
22
+ * 16 ONNX threads (260–335 % CPU), so two of them kept the load above 330 and other sessions' Stop hooks over budget.
23
+ */
24
+ export declare const REFRESH_CHILD_PRIORITY: number;
25
+ export declare const REFRESH_SUPERSEDE_POLL_MS = 15000;
26
+ /** Lowers the CURRENT process to the lowest scheduling priority; false when the OS refuses. */
27
+ export declare function lowerOwnPriority(setPriority?: (priority: number) => void): boolean;
28
+ /**
29
+ * @implements A-SPEC-719.2 — a superseded worker ends within one poll instead of finishing its phase. Measured
30
+ * 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
31
+ */
32
+ export declare function armSupersedeWatch(root: string, generation: string, opts: {
33
+ intervalMs: number;
34
+ exit: () => void;
35
+ owns?: (root: string, generation: string) => boolean;
36
+ }): void;
37
+ /**
38
+ * @implements A-SPEC-719.5 — the worker's two timers, armed as one tested unit: the deadline inside the lease cap
39
+ * (A-SPEC-719.1/719.4) and the supersede watch (A-SPEC-719.2). The main block calls only this.
40
+ */
41
+ export declare function armRefreshWorkerTimers(root: string, generation: string, deps?: {
42
+ deadline?: typeof armWorkerDeadline;
43
+ watch?: typeof armSupersedeWatch;
44
+ exit?: () => void;
45
+ }): void;
6
46
  export interface RefreshChildDeps {
7
47
  head: (root: string) => string | null;
48
+ /** @implements A-SPEC-719.5 — the classified probe; when absent, `head` is taken as an answered probe. */
49
+ headProbe?: HeadProbe;
8
50
  refreshGraph: (root: string) => Promise<unknown>;
9
51
  /** @implements A-SPEC-768.4 — a failed lane may carry `detail` (the embedder's message) beside its reason. */
10
52
  refreshSource: (root: string) => Promise<{
@@ -30,3 +72,4 @@ export interface RefreshChildDeps {
30
72
  export declare function runRefreshChild(root: string, generation: string, deps: RefreshChildDeps): Promise<void>;
31
73
  /** The production phases: the scan/build machinery, loaded only inside the detached child. */
32
74
  export declare function defaultRefreshChildDeps(env?: NodeJS.ProcessEnv): RefreshChildDeps;
75
+ export {};
@@ -33,13 +33,22 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.REFRESH_SUPERSEDE_POLL_MS = exports.REFRESH_CHILD_PRIORITY = void 0;
36
37
  exports.failureReason = failureReason;
37
38
  exports.recordRefreshFailure = recordRefreshFailure;
39
+ exports.armWorkerDeadline = armWorkerDeadline;
40
+ exports.lowerOwnPriority = lowerOwnPriority;
41
+ exports.armSupersedeWatch = armSupersedeWatch;
42
+ exports.armRefreshWorkerTimers = armRefreshWorkerTimers;
38
43
  exports.runRefreshChild = runRefreshChild;
39
44
  exports.defaultRefreshChildDeps = defaultRefreshChildDeps;
40
- // @implements A-SPEC-719, A-SPEC-734
45
+ // @implements A-SPEC-719, A-SPEC-734, A-SPEC-719.7
41
46
  // @implements A-SPEC-566.4
42
47
  // @implements A-SPEC-768.4
48
+ // @implements A-SPEC-719.1
49
+ // @implements A-SPEC-719.2
50
+ // @implements A-SPEC-719.6
51
+ // @implements A-SPEC-769.9
43
52
  /**
44
53
  * The detached refresh child — the ONLY place this slice touches the scan/build machinery. Spawned
45
54
  * by `maybeSpawnRtmRefresh` (rtm-refresh.ts) outside any turn; nothing in the hook path imports
@@ -47,17 +56,33 @@ exports.defaultRefreshChildDeps = defaultRefreshChildDeps;
47
56
  * rtm_impact's warm path IS the refresh: hash-cached scan, reusable-graph rebuild when stale.
48
57
  */
49
58
  const fs = __importStar(require("node:fs"));
59
+ const os = __importStar(require("node:os"));
50
60
  const path = __importStar(require("node:path"));
51
61
  const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
52
- const currentHead = (root) => {
62
+ const probeHead = (root) => {
53
63
  try {
54
- const { headOf } = require('../mcp/handlers/graph-operations');
55
- return headOf(root);
64
+ const { headProbe } = require('./rtm-refresh');
65
+ const { GIT_TIMEOUT_MS } = require('../project/bounded-io');
66
+ // @implements A-SPEC-719.6 — the worker's own scan may have timed out a git call on this root: ask anyway, with
67
+ // the ordinary 5 s bound, rather than be skipped by the memory and publish every finished refresh `retry-at`.
68
+ return headProbe(root, { timeoutMs: GIT_TIMEOUT_MS, ignoreBlock: true });
56
69
  }
57
70
  catch {
58
- return null;
71
+ return { head: null, unanswered: true };
59
72
  }
60
73
  };
74
+ const currentHead = (root) => probeHead(root).head;
75
+ /**
76
+ * @implements A-SPEC-719.5 — the head a completion is written against. When git did not answer, the lease's own head:
77
+ * a mismatch would publish `stale` (no retry pause) and throw a finished refresh away; `retry-at` paces the retry.
78
+ */
79
+ function completionHead(root, generation, probe) {
80
+ const p = probe(root);
81
+ if (!p.unanswered)
82
+ return p;
83
+ const leased = (0, freshness_coordinator_1.leaseHead)(root, generation);
84
+ return { head: leased === undefined ? null : leased, unanswered: true };
85
+ }
61
86
  // @implements A-SPEC-768.4
62
87
  /** The error as a bounded reason: its message (never a stack), at most REFRESH_FAILURE_REASON_MAX characters. */
63
88
  function failureReason(error) {
@@ -71,6 +96,69 @@ function recordRefreshFailure(root, generation, head, now, failure) {
71
96
  ...(failure ? { failure } : {}), // A-SPEC-768.4
72
97
  }, now);
73
98
  }
99
+ /**
100
+ * @implements A-SPEC-719.1 — the worker's own deadline. A live worker keeps its lease up to FRESHNESS_WORKER_MAX_MS;
101
+ * at that point it publishes `retry-at` (a no-op when a newer lease superseded it) and ends, so the next request
102
+ * spawns exactly one replacement instead of a worker running beside it.
103
+ */
104
+ function armWorkerDeadline(root, generation, opts) {
105
+ const timer = setTimeout(() => {
106
+ try {
107
+ recordRefreshFailure(root, generation, completionHead(root, generation, probeHead).head, (opts.now ?? (() => new Date()))(), { stage: 'child', reason: `worker exceeded ${opts.ms} ms` });
108
+ }
109
+ catch { /* fail-soft: ending is what matters */ }
110
+ opts.exit();
111
+ }, opts.ms);
112
+ timer.unref?.();
113
+ }
114
+ /**
115
+ * @implements A-SPEC-719.2 — the worker yields the machine. Measured 2026-10-15: each child ran at default priority with
116
+ * 16 ONNX threads (260–335 % CPU), so two of them kept the load above 330 and other sessions' Stop hooks over budget.
117
+ */
118
+ exports.REFRESH_CHILD_PRIORITY = os.constants.priority.PRIORITY_LOW;
119
+ exports.REFRESH_SUPERSEDE_POLL_MS = 15_000;
120
+ /** Lowers the CURRENT process to the lowest scheduling priority; false when the OS refuses. */
121
+ function lowerOwnPriority(setPriority = (p) => os.setPriority(p)) {
122
+ try {
123
+ setPriority(exports.REFRESH_CHILD_PRIORITY);
124
+ return true;
125
+ }
126
+ catch {
127
+ return false;
128
+ }
129
+ }
130
+ /**
131
+ * @implements A-SPEC-719.2 — a superseded worker ends within one poll instead of finishing its phase. Measured
132
+ * 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
133
+ */
134
+ function armSupersedeWatch(root, generation, opts) {
135
+ // @implements A-SPEC-719.4 — by default only a readable newer lease or a removed workspace ends the worker:
136
+ // `ownsLease` read a missing or unreadable receipt as "not owned" and ended live workers on a transient read.
137
+ const owns = opts.owns ?? ((r, g) => !(0, freshness_coordinator_1.leaseSuperseded)(r, g));
138
+ const timer = setInterval(() => {
139
+ let current = true;
140
+ try {
141
+ current = owns(root, generation);
142
+ }
143
+ catch {
144
+ current = true;
145
+ } // a throwing check is not a supersession
146
+ if (current)
147
+ return;
148
+ clearInterval(timer);
149
+ opts.exit();
150
+ }, opts.intervalMs);
151
+ timer.unref?.();
152
+ }
153
+ /**
154
+ * @implements A-SPEC-719.5 — the worker's two timers, armed as one tested unit: the deadline inside the lease cap
155
+ * (A-SPEC-719.1/719.4) and the supersede watch (A-SPEC-719.2). The main block calls only this.
156
+ */
157
+ function armRefreshWorkerTimers(root, generation, deps = {}) {
158
+ const exit = deps.exit ?? (() => process.exit(0));
159
+ (deps.deadline ?? armWorkerDeadline)(root, generation, { ms: freshness_coordinator_1.FRESHNESS_WORKER_DEADLINE_MS, exit });
160
+ (deps.watch ?? armSupersedeWatch)(root, generation, { intervalMs: exports.REFRESH_SUPERSEDE_POLL_MS, exit });
161
+ }
74
162
  /**
75
163
  * One refresh run for one lease generation. Every phase that writes is preceded by a lease check,
76
164
  * so a superseded worker, or one whose root was removed, stops without writing (A-SPEC-724). Any
@@ -111,19 +199,28 @@ async function runRefreshChild(root, generation, deps) {
111
199
  requirement = { status: 'unavailable' };
112
200
  failure ??= { stage: 'requirement', reason: failureReason(error) };
113
201
  }
202
+ const final = completionHead(root, generation, deps.headProbe ?? ((r) => ({ head: deps.head(r), unanswered: false })));
203
+ // A-SPEC-719.5 — retry after the pause rather than publish `stale`; A-SPEC-719.7 — only when the lease named a commit:
204
+ // a lease taken under a git that refused completes under null as 0.35.20 did (a git that refuses for good would
205
+ // otherwise keep intake refused and re-run the whole refresh every pause).
206
+ if (final.unanswered && final.head !== null) {
207
+ recordRefreshFailure(root, generation, final.head, new Date(), { stage: 'child', reason: 'git did not answer for HEAD at completion' });
208
+ return;
209
+ }
114
210
  (0, freshness_coordinator_1.completeRefresh)(root, generation, {
115
211
  graph: 'current',
116
212
  sourceSemantic: source.lane,
117
213
  requirementSemantic: requirement.status === 'discharged' ? 'current'
118
214
  : requirement.status === 'not-applicable' ? 'not-adopted'
119
215
  : requirement.status === 'suppressed' ? 'suppressed' : 'failed',
120
- head: deps.head(root),
216
+ head: final.head,
121
217
  ...(failure ? { failure } : {}),
122
218
  }, new Date());
123
219
  }
124
220
  catch (error) {
125
221
  try {
126
- recordRefreshFailure(root, generation, deps.head(root), new Date(), { stage, reason: failureReason(error) });
222
+ const head = completionHead(root, generation, deps.headProbe ?? ((r) => ({ head: deps.head(r), unanswered: false }))).head;
223
+ recordRefreshFailure(root, generation, head, new Date(), { stage, reason: failureReason(error) });
127
224
  }
128
225
  catch { /* fail-soft */ }
129
226
  }
@@ -135,6 +232,7 @@ function defaultRefreshChildDeps(env = process.env) {
135
232
  const suppressed = typeof env.HOLMES_NO_SEMANTIC_WARM === 'string' && env.HOLMES_NO_SEMANTIC_WARM !== '';
136
233
  return {
137
234
  head: currentHead,
235
+ headProbe: probeHead,
138
236
  refreshGraph: async (root) => {
139
237
  const { makeHandlers } = require('../mcp/handlers');
140
238
  const { LocalMarkdownRepository } = require('../spec/spec-store');
@@ -144,9 +242,8 @@ function defaultRefreshChildDeps(env = process.env) {
144
242
  refreshSource: async (root) => {
145
243
  const { refreshSemanticVectors } = require('../mcp/handlers/graph-operations');
146
244
  const { CpgScanner } = require('../cpg/cpg-scanner');
147
- const { ScanFileCache } = require('../cpg/scan-cache');
148
- const crypto = require('node:crypto');
149
- const dir = path.join(require('node:os').tmpdir(), 'holmes-cpg-cache-' + crypto.createHash('sha256').update(root).digest('hex').slice(0, 16));
245
+ const { ScanFileCache, scanCacheDirFor } = require('../cpg/scan-cache');
246
+ const dir = scanCacheDirFor(root); // A-SPEC-769.9 — the directory the Stop hook's scan shares
150
247
  return refreshSemanticVectors(root, env, undefined, () => new CpgScanner(undefined, new ScanFileCache(dir)).scan(root, root));
151
248
  },
152
249
  refreshRequirement: async (root) => {
@@ -167,6 +264,9 @@ if (require.main === module) {
167
264
  require('../project/regular-file-guard').installProcessGuards();
168
265
  const root = process.argv[2];
169
266
  const generation = process.argv[3];
267
+ lowerOwnPriority(); // A-SPEC-719.2 — background work yields to foreground sessions
268
+ if (root && generation)
269
+ armRefreshWorkerTimers(root, generation);
170
270
  // fail-soft: a failed refresh leaves the old graph, which the advisory tolerates
171
271
  if (root && generation)
172
272
  void runRefreshChild(root, generation, defaultRefreshChildDeps()).catch(() => undefined);
@@ -1,3 +1,18 @@
1
+ /** @implements A-SPEC-719.9 — 0.35.20's lease probe bound: an answer slower than this is remembered as a timeout. */
2
+ export declare const LEASE_SLOW_GIT_MS = 2000;
3
+ /** Test seam: forget every remembered slow-read head. */
4
+ export declare function forgetSlowLeaseHeads(): void;
5
+ /**
6
+ * Same resolution as the child's `headOf`: full commit id, or null outside a repository.
7
+ * @implements A-SPEC-734 (round 13) — through the per-kind memory: a root whose git already timed out is not asked.
8
+ */
9
+ export declare function headProbe(root: string, opts?: {
10
+ timeoutMs?: number;
11
+ ignoreBlock?: boolean;
12
+ }): {
13
+ head: string | null;
14
+ unanswered: boolean;
15
+ };
1
16
  /** @deprecated A compatibility observation interval; receipt leases are the source of truth. */
2
17
  export declare const RTM_REFRESH_TTL_MS: number;
3
18
  export declare const RTM_REFRESH_MARKER: string;
@@ -8,9 +23,17 @@ export interface RtmRefreshOpts {
8
23
  scriptPath: string;
9
24
  spawn: (cmd: string, args: string[], opts: object) => {
10
25
  unref?: () => void;
26
+ pid?: number;
11
27
  };
12
28
  ttlMs?: number;
13
29
  head?: string | null;
30
+ /** @implements A-SPEC-719.4 — test seam for the HEAD probe used when `head` is not given. */
31
+ headProbe?: (root: string, opts?: {
32
+ ignoreBlock?: boolean;
33
+ }) => {
34
+ head: string | null;
35
+ unanswered: boolean;
36
+ };
14
37
  }
15
38
  export type FreshnessBridgeObservation = {
16
39
  status: 'spawned';
@@ -33,10 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = void 0;
36
+ exports.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = exports.LEASE_SLOW_GIT_MS = void 0;
37
+ exports.forgetSlowLeaseHeads = forgetSlowLeaseHeads;
38
+ exports.headProbe = headProbe;
37
39
  exports.maybeSpawnRtmRefresh = maybeSpawnRtmRefresh;
38
40
  exports.requestBackgroundFreshness = requestBackgroundFreshness;
39
41
  // @implements A-SPEC-724, A-SPEC-723, A-SPEC-719, A-SPEC-734
42
+ // @implements A-SPEC-719.1, A-SPEC-719.4, A-SPEC-719.5, A-SPEC-719.6, A-SPEC-719.8, A-SPEC-719.9, A-SPEC-719.10, A-SPEC-719.11, A-SPEC-719.12, A-SPEC-719.13
40
43
  /**
41
44
  * Graph freshness, kept by the product itself. The impact advisory's quality factor was MEASURED to
42
45
  * be staleness (an 8-day-old graph found 7 advisories; a 1-second reindex found 17), so the Stop
@@ -48,17 +51,51 @@ const fs = __importStar(require("node:fs"));
48
51
  const path = __importStar(require("node:path"));
49
52
  const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
50
53
  const bounded_io_1 = require("../project/bounded-io");
54
+ /** @implements A-SPEC-719.9 — 0.35.20's lease probe bound: an answer slower than this is remembered as a timeout. */
55
+ exports.LEASE_SLOW_GIT_MS = 2000;
56
+ /**
57
+ * @implements A-SPEC-719.10 — the head a slow lease read answered, per root, for as long as that read keeps the
58
+ * root's repo git blocked: the MCP bridge's next request finds its probe skipped and would lease null — a new
59
+ * refresh against a receipt already current at the commit, each time the previous one ended (0.35.20's storm).
60
+ */
61
+ const SLOW_LEASE_HEADS = new Map();
62
+ const SLOW_LEASE_HEAD_MS = 60_000;
63
+ /** Test seam: forget every remembered slow-read head. */
64
+ function forgetSlowLeaseHeads() { SLOW_LEASE_HEADS.clear(); }
65
+ /** @implements A-SPEC-719.11 — the key bounded-io's git-timeout memory uses: an alias resolves to the same entry. */
66
+ const slowLeaseKey = (root) => {
67
+ try {
68
+ return fs.realpathSync.native(root);
69
+ }
70
+ catch {
71
+ return path.resolve(root);
72
+ }
73
+ };
51
74
  /**
52
75
  * Same resolution as the child's `headOf`: full commit id, or null outside a repository.
53
76
  * @implements A-SPEC-734 (round 13) — through the per-kind memory: a root whose git already timed out is not asked.
54
77
  */
55
- function gitHead(root) {
78
+ function headProbe(root, opts = {}) {
56
79
  try {
57
- const r = (0, bounded_io_1.gitOnce)(root, ['-C', root, 'rev-parse', 'HEAD'], 'repo', { timeout: 2000 });
58
- return r.status === 0 ? r.stdout.trim() || null : null;
80
+ // @implements A-SPEC-719.5 — `--verify -q` exits 1 silently for an unborn HEAD, so a refusal (128: dubious
81
+ // ownership, an unknown extension, a broken gitdir) is told apart from a repository with no commit yet.
82
+ // @implements A-SPEC-719.8 — the lease waits as long as the worker and intake do (5 s): at 2 s a git answering in
83
+ // 2–5 s leased a null head, the worker completed against the commit as `stale`, and every request spawned anew.
84
+ const r = (0, bounded_io_1.gitOnce)(root, ['-C', root, 'rev-parse', '--verify', '-q', 'HEAD'], 'repo', { timeout: opts.timeoutMs ?? bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: opts.ignoreBlock });
85
+ if (r.status === 0 && r.error === undefined)
86
+ return { head: r.stdout.trim() || null, unanswered: false };
87
+ // @implements A-SPEC-719.4 — no exit status (timed out, killed, or skipped by the per-kind memory) is not "no
88
+ // repository": a null head would lease a generation the live worker's HEAD never matches, every request.
89
+ if (r.error?.code === 'ENOENT')
90
+ return { head: null, unanswered: false };
91
+ if (!(0, bounded_io_1.gitEntryAbove)(root))
92
+ return { head: null, unanswered: false }; // the tree says: no repository
93
+ if (r.status === 1)
94
+ return { head: null, unanswered: false }; // a repository with an unborn HEAD
95
+ return { head: null, unanswered: true };
59
96
  }
60
97
  catch {
61
- return null;
98
+ return { head: null, unanswered: true };
62
99
  } // bounded: a hung git must never hold the Stop hook
63
100
  }
64
101
  /** @deprecated A compatibility observation interval; receipt leases are the source of truth. */
@@ -76,9 +113,68 @@ function maybeSpawnRtmRefresh(opts) {
76
113
  return { status: 'failed' }; // nothing to refresh
77
114
  // The lease must name the HEAD the child completes against (A-SPEC-719): a null lease in a git
78
115
  // workspace could only ever complete as stale, so intake would never see current evidence.
79
- const decision = (0, freshness_coordinator_1.requestRefresh)(opts.root, {
80
- workspaceId: (0, freshness_coordinator_1.workspaceIdFor)(opts.root), head: opts.head !== undefined ? opts.head : gitHead(opts.root), now: new Date(opts.now),
81
- });
116
+ let head;
117
+ // @implements A-SPEC-719.11 — the lease time follows the probe: stamped before a probe that waits for git, a refresh
118
+ // completing meanwhile looked "completed in the future" and every such request spawned again (also in 0.35.20).
119
+ const started = Date.now();
120
+ let now = opts.now;
121
+ const workspaceId = (0, freshness_coordinator_1.workspaceIdFor)(opts.root);
122
+ if (opts.head !== undefined)
123
+ head = opts.head;
124
+ else {
125
+ const read = opts.headProbe ?? headProbe;
126
+ // @implements A-SPEC-719.11 — keyed as the git-timeout memory is, so an alias spelling finds the remembered head.
127
+ const key = slowLeaseKey(opts.root);
128
+ // @implements A-SPEC-719.9 — a read that answered only past 0.35.20's 2 s bound is remembered as that timeout
129
+ // was, so the caller's later git reads (the Stop hook's evaluation) skip instead of each waiting for this git.
130
+ const remember = (probe, from) => {
131
+ if (probe.unanswered)
132
+ return;
133
+ if (Date.now() - from >= exports.LEASE_SLOW_GIT_MS) {
134
+ (0, bounded_io_1.noteGitFailure)(opts.root, { code: 'ETIMEDOUT' }, 'repo');
135
+ SLOW_LEASE_HEADS.set(key, { head: probe.head, at: Date.now() });
136
+ // @implements A-SPEC-719.13 — while the root's git is still blocked, later probes are skipped: keep the head
137
+ // this fast answer gave (forgetting it leased null, and the worker completed stale, for the rest of the minute).
138
+ }
139
+ else if ((0, bounded_io_1.gitRootBlocked)(opts.root, 'repo'))
140
+ SLOW_LEASE_HEADS.set(key, { head: probe.head, at: Date.now() });
141
+ else
142
+ SLOW_LEASE_HEADS.delete(key);
143
+ };
144
+ const probe = read(opts.root);
145
+ remember(probe, started);
146
+ head = probe.head;
147
+ if (probe.unanswered) {
148
+ // @implements A-SPEC-719.6 — join a live lease rather than supersede it (the 719.4 defect); with none, lease a
149
+ // null head as 0.35.20 did, so a git that refuses for good still refreshes.
150
+ const live = (0, freshness_coordinator_1.leaseLive)(opts.root, new Date(now));
151
+ if (live !== null)
152
+ return { status: 'coalesced', generation: live.generation };
153
+ // @implements A-SPEC-719.10 — within the minute, the head this process's slow read answered.
154
+ const remembered = SLOW_LEASE_HEADS.get(key);
155
+ const age = remembered === undefined ? NaN : Date.now() - remembered.at;
156
+ head = remembered !== undefined && age >= 0 && age < SLOW_LEASE_HEAD_MS ? remembered.head : null;
157
+ // @implements A-SPEC-719.11 — a receipt the worker wrote `stale` at the remembered head says HEAD moved: leased
158
+ // again, that head re-spawned the refresh on every request of the minute. Read once more past the memory.
159
+ if (remembered !== undefined && head === remembered.head
160
+ && (0, freshness_coordinator_1.readFreshnessReceipt)(opts.root, { workspaceId, head, now: new Date(now) })?.state === 'stale') {
161
+ SLOW_LEASE_HEADS.delete(key);
162
+ const again = Date.now();
163
+ const fresh = read(opts.root, { ignoreBlock: true });
164
+ remember(fresh, again);
165
+ head = fresh.unanswered ? null : fresh.head;
166
+ }
167
+ }
168
+ // @implements A-SPEC-719.12 — only a completion stamped inside this request's own wait moves its time; the
169
+ // caller's clock stands otherwise (719.11 added the whole wait, and an exact TTL boundary drifted by the probe).
170
+ const waited = Date.now() - started;
171
+ if (waited > 0) {
172
+ const done = Date.parse((0, freshness_coordinator_1.readFreshnessReceipt)(opts.root, { workspaceId, head, now: new Date(opts.now) })?.completedAt ?? '');
173
+ if (Number.isFinite(done) && done > opts.now && done <= opts.now + waited)
174
+ now = opts.now + waited;
175
+ }
176
+ }
177
+ const decision = (0, freshness_coordinator_1.requestRefresh)(opts.root, { workspaceId, head, now: new Date(now) });
82
178
  if (!decision.spawn)
83
179
  return { status: 'coalesced', generation: decision.receipt.generation };
84
180
  // Retained only for tools that still display the former marker. The receipt
@@ -86,19 +182,35 @@ function maybeSpawnRtmRefresh(opts) {
86
182
  const marker = path.join(opts.root, exports.RTM_REFRESH_MARKER);
87
183
  try {
88
184
  fs.mkdirSync(path.dirname(marker), { recursive: true });
89
- fs.writeFileSync(marker, String(opts.now));
90
- fs.utimesSync(marker, new Date(opts.now), new Date(opts.now));
185
+ fs.writeFileSync(marker, String(now));
186
+ fs.utimesSync(marker, new Date(now), new Date(now));
91
187
  }
92
188
  catch { /* an unwritable marker is not a reason to skip the refresh itself */ }
93
189
  try {
94
- const child = opts.spawn(opts.execPath, [opts.scriptPath, opts.root, decision.receipt.generation], { detached: true, stdio: 'ignore' });
190
+ const fail = () => (0, freshness_coordinator_1.completeRefresh)(opts.root, decision.receipt.generation, {
191
+ graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head: decision.receipt.head,
192
+ }, new Date(now));
193
+ const child = opts.spawn(opts.execPath, [opts.scriptPath, opts.root, decision.receipt.generation], { detached: true, stdio: 'ignore', windowsHide: true });
194
+ // @implements A-SPEC-719.4 — ENOENT/EAGAIN arrive as an 'error' event on the next tick, not a throw: unheard,
195
+ // it ended the MCP server or the Stop hook and left a pid-less `refreshing` lease.
196
+ child?.on?.('error', () => { try {
197
+ fail();
198
+ }
199
+ catch { /* fail-soft */ } });
95
200
  child?.unref?.();
201
+ // @implements A-SPEC-719.1 — the lease names its worker, so a live refresh is not taken for a crashed one.
202
+ if (typeof child?.pid === 'number') {
203
+ try {
204
+ (0, freshness_coordinator_1.recordLeaseWorker)(opts.root, decision.receipt.generation, child.pid);
205
+ }
206
+ catch { /* fail-soft: the 2-minute lease still bounds it */ }
207
+ }
96
208
  return { status: 'spawned', generation: decision.receipt.generation };
97
209
  }
98
210
  catch {
99
211
  (0, freshness_coordinator_1.completeRefresh)(opts.root, decision.receipt.generation, {
100
212
  graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head: decision.receipt.head,
101
- }, new Date(opts.now));
213
+ }, new Date(now));
102
214
  return { status: 'failed' };
103
215
  }
104
216
  }