@holmes-lab/holmes-kit 0.35.19 → 0.35.20

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.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,50 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [Unreleased]
9
+
10
+ ## [0.35.20] - 2026-10-15
11
+
12
+ Upgrading: restart every session and MCP server, run `holmes-kit runtime-binding setup` again (the hook dispatcher runs
13
+ from the copy it installs), and trust the rewritten Codex Stop hook once with `/hooks`.
14
+
15
+ ### Fixed
16
+
17
+ - **One workspace runs one detached refresh at a time** (A-SPEC-719.1). Measured 2026-10-15 on a 3,083-document
18
+ workspace: the freshness lease expired two minutes after `startedAt`, so a refresh that needed longer lost its lease
19
+ while still running, every later Stop hook or `requirement_triage` spawned another `rtm-refresh-child`, and 13–16
20
+ ran at once (receipt `attempt: 13`, load average 300–520, Stop hooks of unrelated sessions over their 18 s budget).
21
+ The receipt now names its worker's `pid`; a lease whose worker is alive is not expired (up to 30 minutes, then it
22
+ is), a crashed worker still frees it after two minutes, and the worker ends itself at 30 minutes leaving `retry-at`
23
+ with `failure.stage: 'child'`. Receipts without `pid` keep the former rule.
24
+ - **A superseded refresh worker ends within 15 seconds, at background priority** (A-SPEC-719.2). The worker asked
25
+ whether it still held its lease only between phases, so nine superseded workers kept embedding for 2–4 hours after a
26
+ newer generation had already completed; each also ran at default priority with 16 ONNX threads. The child now lowers
27
+ itself to the lowest scheduling priority (nice 19; `PRIORITY_LOW` on Windows) and checks its lease every
28
+ `REFRESH_SUPERSEDE_POLL_MS` (15 s), exiting at the first answer that it no longer holds it. It still never writes a
29
+ receipt for a generation it does not own.
30
+ - **The Stop hook no longer re-parses the whole workspace every turn** (A-SPEC-769.9). Measured 2026-10-15 at load
31
+ ~300: the Stop hook's shared scan parsed all 463 files with no cache in 23.0 s, against an 18 s budget, so every Stop
32
+ of every session was refused with `Selected hook runtime deadline exceeded`. It now reads the content-hash scan cache
33
+ the background refresh already keeps (`scanCacheDirFor(root)`): 0.48 s once warm. The cache file is now replaced
34
+ atomically, since two processes share it.
35
+ - **The Stop scan cache lives in the workspace and skips the compiler pass** (A-SPEC-769.11, review round 1 of
36
+ 769.9/769.10). In a governed workspace the cache is `<root>/.ax/cpg_cache` — the directory the MCP server already
37
+ uses — instead of a computable name in the shared temp directory, where another local user on Linux could plant
38
+ entries the Stop gate then believed. The temporary file is created exclusively under a random name (a planted file or
39
+ link there is never written through), and leftovers older than ten minutes are swept. The Stop scan no longer runs the
40
+ whole-program TypeScript pass, which neither Stop judgement reads. The Stop stage-timing line prints from 9 s, and
41
+ `init`'s Codex trust-change refusal names the changed Stop timeout among its causes.
42
+ - **The Stop hook's deadline is 60 seconds** (A-SPEC-769.10). PreToolUse keeps 18 s. The runtime dispatcher gives the
43
+ Stop entry `STOP_HOOK_BUDGET_MS` (60 s), and Holmes Stop entries are written with `timeout: 75` on Claude, Codex and
44
+ Antigravity (budget, 8 s cleanup and a margin). The dispatcher runs from the copy `runtime-binding setup` installs
45
+ under `~/.holmes/runtime`, and harness wiring keeps its old `timeout: 30` until it is rewritten: after upgrading, run
46
+ `holmes-kit runtime-binding setup` (operator) or `holmes-kit init` again. Codex hashes a hook's timeout into its trust
47
+ identity, so the rewritten Codex Stop hook must be trusted again once with `/hooks`.
48
+ - **The local embedder keeps its progress** (A-SPEC-719.3). The local (BGE-M3) `warm()` flushed the vector cache once,
49
+ after its last text, so a refresh worker ended before then landed nothing and the next one started from zero. It
50
+ now publishes a segment after every 25 new vectors (`LOCAL_WARM_CHECKPOINT`), as the cloud warm does per batch.
51
+
8
52
  ## [0.35.19] - 2026-10-13
9
53
 
10
54
  ### Added
package/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
  ![traced files](.ax/badges/traced.svg)
11
11
 
12
12
  **440/442** source files (99.5%) trace to an approved spec · **774/837** approved A-SPECs (92.4%) are anchored from code.
13
- Measured at `11a1b841c813` (specs `sha256:2e7481e061f1`) — reproduce with `holmes-kit attest`.
13
+ Measured at `80944935ee8a` (specs `sha256:2e7481e061f1`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- fdff132e-mv6ac9v3
1
+ c8cb7cb6-mv91ezzh
@@ -54,6 +54,7 @@ exports.agyCanonicalFile = agyCanonicalFile;
54
54
  // @implements A-SPEC-708, A-SPEC-707, A-SPEC-202, A-SPEC-250, A-SPEC-341
55
55
  // @implements A-SPEC-442
56
56
  // @implements A-SPEC-193
57
+ // @implements A-SPEC-769.10
57
58
  const agents_guidance_plan_1 = require("./agents-guidance-plan");
58
59
  const agents_guidance_1 = require("./agents-guidance");
59
60
  const fs = __importStar(require("node:fs"));
@@ -61,6 +62,7 @@ const os = __importStar(require("node:os"));
61
62
  const path = __importStar(require("node:path"));
62
63
  const node_child_process_1 = require("node:child_process");
63
64
  const mcp_launcher_1 = require("./mcp-launcher");
65
+ const hook_process_1 = require("../runtime/hook-process");
64
66
  /**
65
67
  * 하네스별 배선물.
66
68
  *
@@ -190,11 +192,14 @@ function antigravityHookWarnings(packageRoot) {
190
192
  }
191
193
  return out;
192
194
  }
193
- const antigravityHookEntry = (packageRoot, script) => ({
195
+ // @implements A-SPEC-769.10 — the Stop handler carries the Stop deadline; PreToolUse keeps 30 s.
196
+ const antigravityHookEntry = (packageRoot, script, timeout = 30) => ({
194
197
  type: 'command',
195
198
  command: antigravityHookCommand(shortPathIfSpaced(path.join(packageRoot, 'bin', script))),
196
- timeout: 30,
199
+ timeout,
197
200
  });
201
+ /** Stop handler timeouts a canonical file may carry: the current one and the one init wrote before A-SPEC-769.10. */
202
+ const AGY_STOP_TIMEOUTS = [hook_process_1.STOP_HOOK_TIMEOUT_SECONDS, 30];
198
203
  /**
199
204
  * @implements A-SPEC-442
200
205
  * Codex 훅이 부를 것: **Claude 와 같은 정책 커널**.
@@ -212,7 +217,7 @@ const hooksJson = (packageRoot) => `${JSON.stringify({
212
217
  matcher: '*',
213
218
  hooks: [antigravityHookEntry(packageRoot, 'holmes-hook-antigravity.js')],
214
219
  }],
215
- Stop: [antigravityHookEntry(packageRoot, 'holmes-stop-antigravity.js')],
220
+ Stop: [antigravityHookEntry(packageRoot, 'holmes-stop-antigravity.js', hook_process_1.STOP_HOOK_TIMEOUT_SECONDS)],
216
221
  },
217
222
  }, null, 2)}\n`;
218
223
  const AGENTS_MD = (_enforced) => (0, agents_guidance_1.renderCommonGuidance)();
@@ -609,7 +614,7 @@ function agentFiles(agent, opts) {
609
614
  Stop: [{
610
615
  type: 'command',
611
616
  command: kernelCommand(packageRoot, 'stop.js'),
612
- timeout: 30,
617
+ timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS, // A-SPEC-769.10
613
618
  }],
614
619
  },
615
620
  }, null, 2)}\n`,
@@ -774,8 +779,9 @@ function agyCanonicalFile(parsed, raw) {
774
779
  return false;
775
780
  const keysAre = (o, keys) => plainObject(o) && Object.keys(o).length === keys.length && keys.every((k) => Object.prototype.hasOwnProperty.call(o, k));
776
781
  const template = antigravityHookEntry('/x', 'x.js');
777
- const handler = (h) => keysAre(h, Object.keys(template))
778
- && Object.entries(template).every(([k, v]) => (k === 'command' ? typeof h[k] === 'string' && /^node \S+$/.test(h[k]) : h[k] === v));
782
+ const handler = (h, timeouts = [template.timeout]) => keysAre(h, Object.keys(template))
783
+ && Object.entries(template).every(([k, v]) => (k === 'command' ? typeof h[k] === 'string' && /^node \S+$/.test(h[k])
784
+ : k === 'timeout' ? timeouts.includes(h[k]) : h[k] === v));
779
785
  if (!keysAre(parsed, [HOLMES]))
780
786
  return false;
781
787
  const spec = parsed[HOLMES];
@@ -789,5 +795,5 @@ function agyCanonicalFile(parsed, raw) {
789
795
  if (!keysAre(group, ['matcher', 'hooks']) || group.matcher !== '*')
790
796
  return false;
791
797
  const hooks = group.hooks;
792
- return Array.isArray(hooks) && hooks.length === 1 && handler(hooks[0]) && handler(stop[0]);
798
+ return Array.isArray(hooks) && hooks.length === 1 && handler(hooks[0]) && handler(stop[0], AGY_STOP_TIMEOUTS);
793
799
  }
@@ -45,12 +45,14 @@ exports.hasHolmesCodexHooks = hasHolmesCodexHooks;
45
45
  exports.inspectCodexUserHooks = inspectCodexUserHooks;
46
46
  exports.codexKernelScripts = codexKernelScripts;
47
47
  // @implements A-SPEC-727
48
+ // @implements A-SPEC-769.10
48
49
  // codex-cli 0.155 removed plugin hooks (`plugin_hooks: removed`, measured 2026-09-23), so the Holmes
49
50
  // gate reaches Codex only through a hooks file Codex loads for every workspace: the user-level
50
51
  // `$CODEX_HOME/hooks.json`. Codex runs a non-managed hook only after the user trusts its exact
51
52
  // definition (`/hooks`); Holmes never writes that trust — it wires the file and says so.
52
53
  const os = __importStar(require("node:os"));
53
54
  const path = __importStar(require("node:path"));
55
+ const hook_process_1 = require("../runtime/hook-process");
54
56
  /** `$CODEX_HOME/hooks.json`, else `<home>/.codex/hooks.json`. Injectable for deterministic tests. */
55
57
  function defaultCodexHooksPath(env = process.env, home = os.homedir()) {
56
58
  return path.join(env.CODEX_HOME || path.join(home, '.codex'), 'hooks.json');
@@ -636,7 +638,7 @@ function withoutHolmes(hooks) {
636
638
  const render = (doc) => `${JSON.stringify(doc, null, 2)}\n`;
637
639
  const shippedGroup = (event, packageRoot) => event === 'PreToolUse'
638
640
  ? { matcher: '.*', hooks: [{ type: 'command', command: kernelCommand(packageRoot, 'pre-tool-use.js'), timeout: 30 }] }
639
- : { hooks: [{ type: 'command', command: kernelCommand(packageRoot, 'stop.js'), timeout: 30 }] };
641
+ : { hooks: [{ type: 'command', command: kernelCommand(packageRoot, 'stop.js'), timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS }] }; // A-SPEC-769.10
640
642
  /**
641
643
  * One Holmes PreToolUse and one Holmes Stop group, IN PLACE. Codex keys trust by (file, event, group
642
644
  * index, hook index) plus a hash of the definition, so the first Holmes-only group of an event is
@@ -38,6 +38,7 @@ exports.buildHookPlan = buildHookPlan;
38
38
  exports.runInit = runInit;
39
39
  // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8
40
40
  // @implements A-SPEC-709
41
+ // @implements A-SPEC-769.11
41
42
  // @implements A-SPEC-340
42
43
  // @implements A-SPEC-100.2
43
44
  const fs = __importStar(require("node:fs"));
@@ -557,7 +558,7 @@ function runInitUnguarded(opts) {
557
558
  opts.remove
558
559
  ? 'Stripping governance wiring is also changing the wiring — an out-of-band approval is required (self-disarm prevention).'
559
560
  : codexHooksRepoint && !opts.force
560
- ? `Re-wiring the Codex user hooks would change hooks Codex already trusts (another holmes-kit install, a changed matcher, or a moved group); Codex would treat them as new, untrusted hooks — off in every workspace until trusted again with /hooks — so an out-of-band approval is required.`
561
+ ? `Re-wiring the Codex user hooks would change hooks Codex already trusts (another holmes-kit install, a changed matcher, a changed Stop timeout (75 s since A-SPEC-769.10), or a moved group); Codex would treat them as new, untrusted hooks — off in every workspace until trusted again with /hooks — so an out-of-band approval is required.`
561
562
  : '--force changes existing governance wiring and requires an out-of-band approval that covers it.',
562
563
  `Set HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why>"}' (scoped approvals need kind "governance-wiring") and re-run.`,
563
564
  ] };
@@ -42,7 +42,7 @@ exports.codexDuplicateRoutes = codexDuplicateRoutes;
42
42
  exports.runtimeBindingStatus = runtimeBindingStatus;
43
43
  exports.runRuntimeBinding = runRuntimeBinding;
44
44
  exports.trackedWorkspacePaths = trackedWorkspacePaths;
45
- // @implements 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
45
+ // @implements A-SPEC-769.10, 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
46
  const fs = __importStar(require("node:fs"));
47
47
  const os = __importStar(require("node:os"));
48
48
  const path = __importStar(require("node:path"));
@@ -50,6 +50,7 @@ const node_crypto_1 = require("node:crypto");
50
50
  const bounded_io_1 = require("../project/bounded-io");
51
51
  const smol_toml_1 = require("smol-toml");
52
52
  const binding_1 = require("../runtime/binding");
53
+ const hook_process_1 = require("../runtime/hook-process");
53
54
  const runtime_binding_approval_1 = require("./runtime-binding-approval");
54
55
  const codex_toml_1 = require("./codex-toml");
55
56
  const codex_hooks_1 = require("./codex-hooks");
@@ -451,7 +452,7 @@ function runRuntimeBinding(opts) {
451
452
  }
452
453
  const explicitlyEmpty = Array.isArray(hooks[event]) && hooks[event].length === 0;
453
454
  if ((!explicitlyEmpty || activate.has(harness)) && (typeof primary === 'boolean' ? primary : primary.has(event)))
454
- groups.push({ ...(event === 'PreToolUse' ? { matcher: '.*' } : {}), hooks: [{ type: 'command', command: command(harness, event === 'PreToolUse' ? 'pre-tool-use' : 'stop'), timeout: 30 }] });
455
+ groups.push({ ...(event === 'PreToolUse' ? { matcher: '.*' } : {}), hooks: [{ type: 'command', command: command(harness, event === 'PreToolUse' ? 'pre-tool-use' : 'stop'), timeout: event === 'Stop' ? hook_process_1.STOP_HOOK_TIMEOUT_SECONDS : 30 }] }); // A-SPEC-769.10
455
456
  if (groups.length || hooks[event] !== undefined)
456
457
  hooks[event] = groups;
457
458
  }
@@ -551,7 +552,7 @@ function runRuntimeBinding(opts) {
551
552
  else if (!(Array.isArray(old?.PreToolUse) && old.PreToolUse.length === 0))
552
553
  delete ours.PreToolUse;
553
554
  if (primary.has('Stop'))
554
- ours.Stop = !activate.has('antigravity') && Array.isArray(old?.Stop) && old.Stop.length === 0 ? [] : [{ command: command('antigravity', 'stop') }];
555
+ ours.Stop = !activate.has('antigravity') && Array.isArray(old?.Stop) && old.Stop.length === 0 ? [] : [{ command: command('antigravity', 'stop'), timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS }]; // A-SPEC-769.10
555
556
  else if (!(Array.isArray(old?.Stop) && old.Stop.length === 0))
556
557
  delete ours.Stop;
557
558
  add(file, json({ ...doc, 'holmes-kit': ours }));
@@ -1,14 +1,22 @@
1
1
  import type { ScannedFile } from './scanned-file';
2
2
  export declare const SCAN_CACHE_VERSION = 4;
3
+ /**
4
+ * @implements A-SPEC-769.9 — the one cache directory per workspace root, shared by the refresh child and the Stop
5
+ * hook. Measured 2026-10-15: the Stop hook's uncached scan took 23.0 s of its budget; served from here, 0.48 s.
6
+ */
7
+ export declare function scanCacheDirFor(root: string, tmp?: string): string;
3
8
  export declare class ScanFileCache {
4
9
  private readonly dir;
5
10
  private readonly file;
11
+ private readonly tempSuffix;
6
12
  private entries;
7
13
  private seen;
8
14
  private dirty;
9
15
  hits: number;
10
16
  misses: number;
11
- constructor(dir: string);
17
+ constructor(dir: string, opts?: {
18
+ tempSuffix?: () => string;
19
+ });
12
20
  static hashOf(content: string): string;
13
21
  /** Cached scan result iff the stored hash matches this content. Marks the path as seen. */
14
22
  get(sourcePath: string, contentHash: string): Omit<ScannedFile, 'path'> | undefined;
@@ -18,4 +26,6 @@ export declare class ScanFileCache {
18
26
  * deleted/renamed files — pruned so the cache cannot grow unboundedly. No-op when nothing changed.
19
27
  */
20
28
  save(scannedScopeDir?: string): void;
29
+ /** @implements A-SPEC-769.11 — removes temporary files of this cache's shape older than ten minutes. */
30
+ private sweepTemporaries;
21
31
  }
@@ -34,9 +34,13 @@ 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
39
42
  const fs = __importStar(require("node:fs"));
43
+ const os = __importStar(require("node:os"));
40
44
  const path = __importStar(require("node:path"));
41
45
  const node_crypto_1 = require("node:crypto");
42
46
  function cloneExpr(e) {
@@ -62,16 +66,36 @@ function cloneDataFlow(df) {
62
66
  // version-3 entry has none, and serving it would put every anchor back on the file for as long as
63
67
  // the file's content did not change.
64
68
  exports.SCAN_CACHE_VERSION = 4;
69
+ /**
70
+ * @implements A-SPEC-769.9 — the one cache directory per workspace root, shared by the refresh child and the Stop
71
+ * hook. Measured 2026-10-15: the Stop hook's uncached scan took 23.0 s of its budget; served from here, 0.48 s.
72
+ */
73
+ function scanCacheDirFor(root, tmp = os.tmpdir()) {
74
+ // @implements A-SPEC-769.11 — a governed workspace keeps the cache in its own .ax (the directory the MCP server
75
+ // uses): the Stop GATE reads it, and a name anyone can compute in the shared /tmp let another local user plant it.
76
+ try {
77
+ if (fs.statSync(path.join(root, '.ax')).isDirectory())
78
+ return path.join(root, '.ax', 'cpg_cache');
79
+ }
80
+ catch { /* not governed */ }
81
+ return path.join(tmp, 'holmes-cpg-cache-' + (0, node_crypto_1.createHash)('sha256').update(root).digest('hex').slice(0, 16));
82
+ }
83
+ // @implements A-SPEC-769.11 — temporary files are `scan-cache.json.<suffix>.tmp`; one older than this is left over
84
+ // from a writer that died between create and rename.
85
+ const TEMP_SWEEP_MS = 10 * 60_000;
86
+ const TEMP_NAME = /^scan-cache\.json\.[0-9a-z.]+\.tmp$/; // the dots admit the former `<pid>.<ms>` names
65
87
  class ScanFileCache {
66
88
  dir;
67
89
  file;
90
+ tempSuffix;
68
91
  entries;
69
92
  seen = new Set();
70
93
  dirty = false;
71
94
  hits = 0;
72
95
  misses = 0;
73
- constructor(dir) {
96
+ constructor(dir, opts = {}) {
74
97
  this.dir = dir;
98
+ this.tempSuffix = opts.tempSuffix ?? (() => (0, node_crypto_1.randomBytes)(6).toString('hex'));
75
99
  this.file = path.join(dir, 'scan-cache.json');
76
100
  try {
77
101
  const raw = JSON.parse(fs.readFileSync(this.file, 'utf8'));
@@ -134,12 +158,58 @@ class ScanFileCache {
134
158
  try {
135
159
  if (this.dirty) {
136
160
  fs.mkdirSync(this.dir, { recursive: true });
137
- fs.writeFileSync(this.file, JSON.stringify({ v: exports.SCAN_CACHE_VERSION, entries: this.entries }), 'utf8');
161
+ // @implements A-SPEC-769.9 — the Stop hook and the refresh child share this file: a reader in the other
162
+ // process sees the old or the new content, never a partly written one.
163
+ // @implements A-SPEC-769.11 — an unpredictable name created exclusively: a file or link already at that name
164
+ // fails the create (another name is tried) and is never written through.
165
+ const body = JSON.stringify({ v: exports.SCAN_CACHE_VERSION, entries: this.entries });
166
+ let tmp;
167
+ for (let attempt = 0; attempt < 3 && tmp === undefined; attempt++) {
168
+ const candidate = `${this.file}.${this.tempSuffix()}.tmp`;
169
+ try {
170
+ fs.writeFileSync(candidate, body, { encoding: 'utf8', flag: 'wx' });
171
+ tmp = candidate;
172
+ }
173
+ catch (error) {
174
+ if (error.code !== 'EEXIST')
175
+ throw error;
176
+ }
177
+ }
178
+ if (tmp === undefined)
179
+ throw new Error('no free temporary name');
180
+ try {
181
+ fs.renameSync(tmp, this.file);
182
+ }
183
+ catch (error) {
184
+ try {
185
+ fs.rmSync(tmp, { force: true });
186
+ }
187
+ catch { /* nothing more to undo */ }
188
+ throw error;
189
+ }
138
190
  this.dirty = false;
191
+ this.sweepTemporaries();
139
192
  }
140
193
  }
141
194
  catch { /* cache persistence is best-effort — next scan just runs colder */ }
142
195
  this.seen.clear();
143
196
  }
197
+ /** @implements A-SPEC-769.11 — removes temporary files of this cache's shape older than ten minutes. */
198
+ sweepTemporaries() {
199
+ try {
200
+ const cutoff = Date.now() - TEMP_SWEEP_MS;
201
+ for (const name of fs.readdirSync(this.dir)) {
202
+ if (!TEMP_NAME.test(name))
203
+ continue;
204
+ const p = path.join(this.dir, name);
205
+ try {
206
+ if (fs.lstatSync(p).mtimeMs < cutoff)
207
+ fs.rmSync(p, { force: true });
208
+ }
209
+ catch { /* raced with its writer */ }
210
+ }
211
+ }
212
+ catch { /* best-effort */ }
213
+ }
144
214
  }
145
215
  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
@@ -3,6 +3,33 @@ import { FreshnessLane, FreshnessReceipt, RefreshFailure } from '../refresh/fres
3
3
  export declare function failureReason(error: unknown): string;
4
4
  /** The detached worker must publish its own failure; the parent is intentionally non-blocking. */
5
5
  export declare function recordRefreshFailure(root: string, generation: string, head: string | null, now: Date, failure?: RefreshFailure): FreshnessReceipt | null;
6
+ /**
7
+ * @implements A-SPEC-719.1 — the worker's own deadline. A live worker keeps its lease up to FRESHNESS_WORKER_MAX_MS;
8
+ * at that point it publishes `retry-at` (a no-op when a newer lease superseded it) and ends, so the next request
9
+ * spawns exactly one replacement instead of a worker running beside it.
10
+ */
11
+ export declare function armWorkerDeadline(root: string, generation: string, opts: {
12
+ ms: number;
13
+ exit: () => void;
14
+ now?: () => Date;
15
+ }): void;
16
+ /**
17
+ * @implements A-SPEC-719.2 — the worker yields the machine. Measured 2026-10-15: each child ran at default priority with
18
+ * 16 ONNX threads (260–335 % CPU), so two of them kept the load above 330 and other sessions' Stop hooks over budget.
19
+ */
20
+ export declare const REFRESH_CHILD_PRIORITY: number;
21
+ export declare const REFRESH_SUPERSEDE_POLL_MS = 15000;
22
+ /** Lowers the CURRENT process to the lowest scheduling priority; false when the OS refuses. */
23
+ export declare function lowerOwnPriority(setPriority?: (priority: number) => void): boolean;
24
+ /**
25
+ * @implements A-SPEC-719.2 — a superseded worker ends within one poll instead of finishing its phase. Measured
26
+ * 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
27
+ */
28
+ export declare function armSupersedeWatch(root: string, generation: string, opts: {
29
+ intervalMs: number;
30
+ exit: () => void;
31
+ owns?: (root: string, generation: string) => boolean;
32
+ }): void;
6
33
  export interface RefreshChildDeps {
7
34
  head: (root: string) => string | null;
8
35
  refreshGraph: (root: string) => Promise<unknown>;
@@ -33,13 +33,20 @@ 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;
38
42
  exports.runRefreshChild = runRefreshChild;
39
43
  exports.defaultRefreshChildDeps = defaultRefreshChildDeps;
40
44
  // @implements A-SPEC-719, A-SPEC-734
41
45
  // @implements A-SPEC-566.4
42
46
  // @implements A-SPEC-768.4
47
+ // @implements A-SPEC-719.1
48
+ // @implements A-SPEC-719.2
49
+ // @implements A-SPEC-769.9
43
50
  /**
44
51
  * The detached refresh child — the ONLY place this slice touches the scan/build machinery. Spawned
45
52
  * by `maybeSpawnRtmRefresh` (rtm-refresh.ts) outside any turn; nothing in the hook path imports
@@ -47,6 +54,7 @@ exports.defaultRefreshChildDeps = defaultRefreshChildDeps;
47
54
  * rtm_impact's warm path IS the refresh: hash-cached scan, reusable-graph rebuild when stale.
48
55
  */
49
56
  const fs = __importStar(require("node:fs"));
57
+ const os = __importStar(require("node:os"));
50
58
  const path = __importStar(require("node:path"));
51
59
  const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
52
60
  const currentHead = (root) => {
@@ -71,6 +79,58 @@ function recordRefreshFailure(root, generation, head, now, failure) {
71
79
  ...(failure ? { failure } : {}), // A-SPEC-768.4
72
80
  }, now);
73
81
  }
82
+ /**
83
+ * @implements A-SPEC-719.1 — the worker's own deadline. A live worker keeps its lease up to FRESHNESS_WORKER_MAX_MS;
84
+ * at that point it publishes `retry-at` (a no-op when a newer lease superseded it) and ends, so the next request
85
+ * spawns exactly one replacement instead of a worker running beside it.
86
+ */
87
+ function armWorkerDeadline(root, generation, opts) {
88
+ const timer = setTimeout(() => {
89
+ try {
90
+ recordRefreshFailure(root, generation, currentHead(root), (opts.now ?? (() => new Date()))(), { stage: 'child', reason: `worker exceeded ${opts.ms} ms` });
91
+ }
92
+ catch { /* fail-soft: ending is what matters */ }
93
+ opts.exit();
94
+ }, opts.ms);
95
+ timer.unref?.();
96
+ }
97
+ /**
98
+ * @implements A-SPEC-719.2 — the worker yields the machine. Measured 2026-10-15: each child ran at default priority with
99
+ * 16 ONNX threads (260–335 % CPU), so two of them kept the load above 330 and other sessions' Stop hooks over budget.
100
+ */
101
+ exports.REFRESH_CHILD_PRIORITY = os.constants.priority.PRIORITY_LOW;
102
+ exports.REFRESH_SUPERSEDE_POLL_MS = 15_000;
103
+ /** Lowers the CURRENT process to the lowest scheduling priority; false when the OS refuses. */
104
+ function lowerOwnPriority(setPriority = (p) => os.setPriority(p)) {
105
+ try {
106
+ setPriority(exports.REFRESH_CHILD_PRIORITY);
107
+ return true;
108
+ }
109
+ catch {
110
+ return false;
111
+ }
112
+ }
113
+ /**
114
+ * @implements A-SPEC-719.2 — a superseded worker ends within one poll instead of finishing its phase. Measured
115
+ * 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
116
+ */
117
+ function armSupersedeWatch(root, generation, opts) {
118
+ const owns = opts.owns ?? freshness_coordinator_1.ownsLease;
119
+ const timer = setInterval(() => {
120
+ let current = true;
121
+ try {
122
+ current = owns(root, generation);
123
+ }
124
+ catch {
125
+ current = true;
126
+ } // an unreadable receipt is not a supersession
127
+ if (current)
128
+ return;
129
+ clearInterval(timer);
130
+ opts.exit();
131
+ }, opts.intervalMs);
132
+ timer.unref?.();
133
+ }
74
134
  /**
75
135
  * One refresh run for one lease generation. Every phase that writes is preceded by a lease check,
76
136
  * so a superseded worker, or one whose root was removed, stops without writing (A-SPEC-724). Any
@@ -144,9 +204,8 @@ function defaultRefreshChildDeps(env = process.env) {
144
204
  refreshSource: async (root) => {
145
205
  const { refreshSemanticVectors } = require('../mcp/handlers/graph-operations');
146
206
  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));
207
+ const { ScanFileCache, scanCacheDirFor } = require('../cpg/scan-cache');
208
+ const dir = scanCacheDirFor(root); // A-SPEC-769.9 — the directory the Stop hook's scan shares
150
209
  return refreshSemanticVectors(root, env, undefined, () => new CpgScanner(undefined, new ScanFileCache(dir)).scan(root, root));
151
210
  },
152
211
  refreshRequirement: async (root) => {
@@ -167,6 +226,13 @@ if (require.main === module) {
167
226
  require('../project/regular-file-guard').installProcessGuards();
168
227
  const root = process.argv[2];
169
228
  const generation = process.argv[3];
229
+ lowerOwnPriority(); // A-SPEC-719.2 — background work yields to foreground sessions
230
+ // @implements A-SPEC-719.1 — never outlive the lease cap
231
+ if (root && generation)
232
+ armWorkerDeadline(root, generation, { ms: freshness_coordinator_1.FRESHNESS_WORKER_MAX_MS, exit: () => process.exit(0) });
233
+ // @implements A-SPEC-719.2 — end promptly once superseded
234
+ if (root && generation)
235
+ armSupersedeWatch(root, generation, { intervalMs: exports.REFRESH_SUPERSEDE_POLL_MS, exit: () => process.exit(0) });
170
236
  // fail-soft: a failed refresh leaves the old graph, which the advisory tolerates
171
237
  if (root && generation)
172
238
  void runRefreshChild(root, generation, defaultRefreshChildDeps()).catch(() => undefined);
@@ -8,6 +8,7 @@ export interface RtmRefreshOpts {
8
8
  scriptPath: string;
9
9
  spawn: (cmd: string, args: string[], opts: object) => {
10
10
  unref?: () => void;
11
+ pid?: number;
11
12
  };
12
13
  ttlMs?: number;
13
14
  head?: string | null;
@@ -37,6 +37,7 @@ exports.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = void 0;
37
37
  exports.maybeSpawnRtmRefresh = maybeSpawnRtmRefresh;
38
38
  exports.requestBackgroundFreshness = requestBackgroundFreshness;
39
39
  // @implements A-SPEC-724, A-SPEC-723, A-SPEC-719, A-SPEC-734
40
+ // @implements A-SPEC-719.1
40
41
  /**
41
42
  * Graph freshness, kept by the product itself. The impact advisory's quality factor was MEASURED to
42
43
  * be staleness (an 8-day-old graph found 7 advisories; a 1-second reindex found 17), so the Stop
@@ -93,6 +94,13 @@ function maybeSpawnRtmRefresh(opts) {
93
94
  try {
94
95
  const child = opts.spawn(opts.execPath, [opts.scriptPath, opts.root, decision.receipt.generation], { detached: true, stdio: 'ignore' });
95
96
  child?.unref?.();
97
+ // @implements A-SPEC-719.1 — the lease names its worker, so a live refresh is not taken for a crashed one.
98
+ if (typeof child?.pid === 'number') {
99
+ try {
100
+ (0, freshness_coordinator_1.recordLeaseWorker)(opts.root, decision.receipt.generation, child.pid);
101
+ }
102
+ catch { /* fail-soft: the 2-minute lease still bounds it */ }
103
+ }
96
104
  return { status: 'spawned', generation: decision.receipt.generation };
97
105
  }
98
106
  catch {
@@ -1,4 +1,6 @@
1
1
  import { PendingRequest } from '../governance/approval-queue';
2
+ /** @implements A-SPEC-769.11 — the stage line prints from 9 s: the 18–29 s range of the 2026-10-15 incident stays visible. */
3
+ export declare const STOP_TIMING_REPORT_MS = 9000;
2
4
  export declare const STOP_NOTICES: Set<string>;
3
5
  import { Spec } from '../spec/spec-parser';
4
6
  import type { TestOutcome } from '../review/test-runner';
@@ -393,6 +395,12 @@ export declare function collectForbiddenEdgeJudgement(specs: readonly Spec[], sc
393
395
  * @implements A-SPEC-693 — `shared` is a scan the caller already made. When given it is BELIEVED
394
396
  * and no second scan runs, so one turn pays for one scan however many judgements read it.
395
397
  */
398
+ /**
399
+ * @implements A-SPEC-769.9 — the turn's ONE shared scan (A-SPEC-693), served from the content-hash scan cache the
400
+ * refresh child already keeps. Measured 2026-10-15 at load ~300: uncached 23.0 s against an 18 s budget, refusing every
401
+ * Stop; through the cache 0.48 s warm. Only unchanged files are served from it.
402
+ */
403
+ export declare function stopSharedScan(root: string, cache?: import('../cpg/scan-cache').ScanFileCache): ScannedFile[];
396
404
  export declare function scanCodeCycles(root: string, shared?: ScannedFile[]): {
397
405
  current: import('../cpg/cycle-detect').Cycle[];
398
406
  allowed: string[];
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.MAX_CONSECUTIVE_BLOCKS = exports.STOP_NOTICES = void 0;
36
+ exports.MAX_CONSECUTIVE_BLOCKS = exports.STOP_NOTICES = exports.STOP_TIMING_REPORT_MS = void 0;
37
37
  exports.collectKnownDefects = collectKnownDefects;
38
38
  exports.collectSemanticCoverage = collectSemanticCoverage;
39
39
  exports.collectAnalysisCurrency = collectAnalysisCurrency;
@@ -59,9 +59,11 @@ exports.__setWiredSpecsForTest = __setWiredSpecsForTest;
59
59
  exports.guardCountOrZero = guardCountOrZero;
60
60
  exports.readGuardCount = readGuardCount;
61
61
  exports.collectForbiddenEdgeJudgement = collectForbiddenEdgeJudgement;
62
+ exports.stopSharedScan = stopSharedScan;
62
63
  exports.scanCodeCycles = scanCodeCycles;
63
64
  exports.writeGuardCount = writeGuardCount;
64
65
  // @implements A-SPEC-734
66
+ // @implements A-SPEC-769.9, A-SPEC-769.10, A-SPEC-769.11
65
67
  const fs = __importStar(require("node:fs"));
66
68
  // @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
67
69
  // calls into this file.
@@ -76,7 +78,10 @@ const json_state_1 = require("../project/json-state");
76
78
  const node_child_process_1 = require("node:child_process");
77
79
  // @implements A-SPEC-769.2 — the stage clock and the budget it is measured against.
78
80
  const stop_timing_1 = require("./stop-timing");
81
+ // @implements A-SPEC-769.10 — the Stop hook is measured against its own (60 s) budget.
79
82
  const hook_process_1 = require("../runtime/hook-process");
83
+ /** @implements A-SPEC-769.11 — the stage line prints from 9 s: the 18–29 s range of the 2026-10-15 incident stays visible. */
84
+ exports.STOP_TIMING_REPORT_MS = 9_000;
80
85
  /**
81
86
  * @implements A-SPEC-734 (round 11) — every git child of the Stop hook runs under a timeout, and a timeout or
82
87
  * failure is "no signal": a FIFO `.gitignore` (or a FIFO in place of a tracked file) kept `git status` blocked
@@ -1242,6 +1247,17 @@ function collectForbiddenEdgeJudgement(specs, scanned, now) {
1242
1247
  * @implements A-SPEC-693 — `shared` is a scan the caller already made. When given it is BELIEVED
1243
1248
  * and no second scan runs, so one turn pays for one scan however many judgements read it.
1244
1249
  */
1250
+ /**
1251
+ * @implements A-SPEC-769.9 — the turn's ONE shared scan (A-SPEC-693), served from the content-hash scan cache the
1252
+ * refresh child already keeps. Measured 2026-10-15 at load ~300: uncached 23.0 s against an 18 s budget, refusing every
1253
+ * Stop; through the cache 0.48 s warm. Only unchanged files are served from it.
1254
+ */
1255
+ function stopSharedScan(root, cache) {
1256
+ const { CpgScanner } = require('../cpg/cpg-scanner');
1257
+ const { ScanFileCache, scanCacheDirFor } = require('../cpg/scan-cache');
1258
+ // @implements A-SPEC-769.11 — no compiler pass: it adds only `resolvedCalls`, which neither Stop judgement reads.
1259
+ return new CpgScanner(undefined, cache ?? new ScanFileCache(scanCacheDirFor(root)), { compilerCalls: false }).scan(root, root);
1260
+ }
1245
1261
  function scanCodeCycles(root, shared) {
1246
1262
  try {
1247
1263
  const { CpgScanner } = require('../cpg/cpg-scanner');
@@ -1454,9 +1470,8 @@ if (require.main === module) {
1454
1470
  // run leaves both silent; neither judgement scans again on its own.
1455
1471
  let sharedScan;
1456
1472
  try {
1457
- const { CpgScanner } = require('../cpg/cpg-scanner');
1458
- sharedScan = new CpgScanner().scan(stopProjectRoot(), stopProjectRoot());
1459
- }
1473
+ sharedScan = stopSharedScan(stopProjectRoot());
1474
+ } // A-SPEC-769.9
1460
1475
  catch {
1461
1476
  sharedScan = undefined;
1462
1477
  }
@@ -1696,7 +1711,7 @@ if (require.main === module) {
1696
1711
  // clock fault is swallowed, because an observation never touches the verdict.
1697
1712
  clock.mark('evaluate');
1698
1713
  try {
1699
- const timing = clock.line(hook_process_1.HOOK_BUDGET_MS);
1714
+ const timing = clock.line(hook_process_1.STOP_HOOK_BUDGET_MS, exports.STOP_TIMING_REPORT_MS / hook_process_1.STOP_HOOK_BUDGET_MS);
1700
1715
  if (timing !== null)
1701
1716
  process.stderr.write(`${timing}\n`);
1702
1717
  }
@@ -20,6 +20,8 @@ export interface FreshnessReceipt {
20
20
  requirementSemantic: FreshnessLane;
21
21
  /** @implements A-SPEC-768.4 — present only on a completion that failed; never carried into the next lease. */
22
22
  failure?: RefreshFailure;
23
+ /** @implements A-SPEC-719.1 — the detached worker holding this lease; absent on older receipts. */
24
+ pid?: number;
23
25
  }
24
26
  export interface RefreshRequest {
25
27
  workspaceId: string;
@@ -37,6 +39,12 @@ export declare const FRESHNESS_RECEIPT_FILE: string;
37
39
  export declare const FRESHNESS_LEASE_MS: number;
38
40
  /** A failed detached worker is visible immediately but retries only after this bounded pause. */
39
41
  export declare const FRESHNESS_RETRY_MS: number;
42
+ /**
43
+ * @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a jarvis refresh
44
+ * outlived the 2-minute lease, every later request spawned another child, and 13 ran at once (attempt 13, load
45
+ * 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
46
+ */
47
+ export declare const FRESHNESS_WORKER_MAX_MS: number;
40
48
  /**
41
49
  * A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
42
50
  * someone edits, so without an interval the graph would never refresh between commits — the former
@@ -66,6 +74,11 @@ export declare function requestRefresh(root: string, input: RefreshRequest): {
66
74
  * `.ax` under a root that was removed (A-SPEC-724).
67
75
  */
68
76
  export declare function ownsLease(root: string, generation: string): boolean;
77
+ /**
78
+ * @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
79
+ * crashed one. Writes only while that generation still holds the `refreshing` lease.
80
+ */
81
+ export declare function recordLeaseWorker(root: string, generation: string, pid: number): boolean;
69
82
  /** Publish only the lease owner’s terminal observation; a superseded worker cannot overwrite a newer lease. */
70
83
  export declare function completeRefresh(root: string, generation: string, completion: RefreshCompletion, now: Date): FreshnessReceipt | null;
71
84
  /**
@@ -33,15 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.FRESHNESS_REREFRESH_MS = exports.FRESHNESS_RETRY_MS = exports.FRESHNESS_LEASE_MS = exports.FRESHNESS_RECEIPT_FILE = exports.REFRESH_FAILURE_REASON_MAX = void 0;
36
+ exports.FRESHNESS_REREFRESH_MS = exports.FRESHNESS_WORKER_MAX_MS = exports.FRESHNESS_RETRY_MS = exports.FRESHNESS_LEASE_MS = exports.FRESHNESS_RECEIPT_FILE = exports.REFRESH_FAILURE_REASON_MAX = void 0;
37
37
  exports.intakeUsable = intakeUsable;
38
38
  exports.lexicalOnly = lexicalOnly;
39
39
  exports.readFreshnessReceipt = readFreshnessReceipt;
40
40
  exports.requestRefresh = requestRefresh;
41
41
  exports.ownsLease = ownsLease;
42
+ exports.recordLeaseWorker = recordLeaseWorker;
42
43
  exports.completeRefresh = completeRefresh;
43
44
  exports.workspaceIdFor = workspaceIdFor;
44
45
  // @implements A-SPEC-719, A-SPEC-768.4
46
+ // @implements A-SPEC-719.1
45
47
  /**
46
48
  * The durable source of truth for refresh work. A receipt names the workspace and
47
49
  * commit it describes, so an old detached worker cannot make a newer tree look
@@ -58,6 +60,12 @@ exports.FRESHNESS_RECEIPT_FILE = path.join('.ax', 'state', 'fresh-evidence.json'
58
60
  exports.FRESHNESS_LEASE_MS = 2 * 60 * 1000;
59
61
  /** A failed detached worker is visible immediately but retries only after this bounded pause. */
60
62
  exports.FRESHNESS_RETRY_MS = 30 * 1000;
63
+ /**
64
+ * @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a jarvis refresh
65
+ * outlived the 2-minute lease, every later request spawned another child, and 13 ran at once (attempt 13, load
66
+ * 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
67
+ */
68
+ exports.FRESHNESS_WORKER_MAX_MS = 30 * 60 * 1000;
61
69
  /**
62
70
  * A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
63
71
  * someone edits, so without an interval the graph would never refresh between commits — the former
@@ -95,6 +103,7 @@ function isReceipt(value) {
95
103
  && (r.startedAt === undefined || typeof r.startedAt === 'string')
96
104
  && (r.completedAt === undefined || typeof r.completedAt === 'string')
97
105
  && (r.retryAt === undefined || typeof r.retryAt === 'string')
106
+ && (r.pid === undefined || (Number.isInteger(r.pid) && r.pid > 0))
98
107
  // @implements A-SPEC-768.4 — a receipt without the field is still a receipt (older builds wrote none).
99
108
  && (r.failure === undefined || (!!r.failure && typeof r.failure === 'object' && typeof r.failure.stage === 'string' && typeof r.failure.reason === 'string'));
100
109
  }
@@ -133,11 +142,29 @@ function writeReceipt(root, receipt) {
133
142
  }
134
143
  }
135
144
  }
145
+ /** @implements A-SPEC-719.1 — signal 0 probes existence only; EPERM means the process exists under another user. */
146
+ function processAlive(pid) {
147
+ try {
148
+ process.kill(pid, 0);
149
+ return true;
150
+ }
151
+ catch (error) {
152
+ return error.code === 'EPERM';
153
+ }
154
+ }
136
155
  function expired(receipt, now) {
137
156
  if (receipt.state !== 'refreshing' || !receipt.startedAt)
138
157
  return false;
139
158
  const started = Date.parse(receipt.startedAt);
140
- return !Number.isFinite(started) || now.getTime() - started >= exports.FRESHNESS_LEASE_MS;
159
+ if (!Number.isFinite(started))
160
+ return true;
161
+ const age = now.getTime() - started;
162
+ if (age >= exports.FRESHNESS_WORKER_MAX_MS)
163
+ return true;
164
+ // @implements A-SPEC-719.1 — a running worker keeps its lease; a crashed one frees it after the short lease.
165
+ if (receipt.pid !== undefined && processAlive(receipt.pid))
166
+ return false;
167
+ return age >= exports.FRESHNESS_LEASE_MS;
141
168
  }
142
169
  function stale(receipt) {
143
170
  return { ...receipt, state: 'stale', graph: 'stale', sourceSemantic: 'stale', requirementSemantic: 'stale' };
@@ -186,6 +213,19 @@ function ownsLease(root, generation) {
186
213
  const receipt = storedReceipt(root);
187
214
  return receipt !== null && receipt.generation === generation && receipt.state === 'refreshing';
188
215
  }
216
+ /**
217
+ * @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
218
+ * crashed one. Writes only while that generation still holds the `refreshing` lease.
219
+ */
220
+ function recordLeaseWorker(root, generation, pid) {
221
+ const previous = storedReceipt(root);
222
+ if (!previous || previous.generation !== generation || previous.state !== 'refreshing')
223
+ return false;
224
+ if (!Number.isInteger(pid) || pid <= 0)
225
+ return false;
226
+ writeReceipt(root, { ...previous, pid });
227
+ return true;
228
+ }
189
229
  /** Publish only the lease owner’s terminal observation; a superseded worker cannot overwrite a newer lease. */
190
230
  function completeRefresh(root, generation, completion, now) {
191
231
  const previous = storedReceipt(root);
@@ -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
37
+ // @implements A-SPEC-751, A-SPEC-751.1, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-754, A-SPEC-769.10
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");
@@ -127,11 +127,13 @@ async function runDispatch(opts) {
127
127
  let phaseInput;
128
128
  let phaseSelection;
129
129
  let phaseChild;
130
- const budgetText = String(opts.hookBudgetMs ?? hook_process_1.HOOK_BUDGET_MS);
130
+ // @implements A-SPEC-769.10 — the Stop entry has its own (60 s) budget; every other hook entry keeps 18 s.
131
+ const entryBudget = (0, hook_process_1.hookBudgetFor)(opts.entry);
132
+ const budgetText = String(opts.hookBudgetMs ?? entryBudget);
131
133
  try {
132
134
  if (!['claude', 'codex', 'antigravity'].includes(opts.harness) || !['mcp', 'pre-tool-use', 'stop'].includes(opts.entry))
133
135
  throw new Error('Invalid runtime dispatcher entry or harness');
134
- const hookBudget = (0, hook_process_1.boundedHookBudget)(opts.hookBudgetMs, hook_process_1.HOOK_BUDGET_MS);
136
+ const hookBudget = (0, hook_process_1.boundedHookBudget)(opts.hookBudgetMs, entryBudget);
135
137
  const cleanupBudget = (0, hook_process_1.boundedHookBudget)(opts.cleanupBudgetMs, hook_process_1.HOOK_CLEANUP_MS);
136
138
  let input;
137
139
  if (opts.entry !== 'mcp') {
@@ -1,6 +1,14 @@
1
1
  import { type ChildProcess } from 'node:child_process';
2
2
  export declare const HOOK_BUDGET_MS = 18000;
3
3
  export declare const HOOK_CLEANUP_MS = 8000;
4
+ /**
5
+ * @implements A-SPEC-769.10 — owner decision 2026-10-15: the Stop hook, which runs once at the end of a turn and is
6
+ * fail-open, gets one minute; PreToolUse, which runs before every tool call, keeps 18 s. The harness timeout written
7
+ * for Stop entries leaves the cleanup budget and a margin so the harness never ends the dispatcher first.
8
+ */
9
+ export declare const STOP_HOOK_BUDGET_MS = 60000;
10
+ export declare const STOP_HOOK_TIMEOUT_SECONDS = 75;
11
+ export declare function hookBudgetFor(entry: string): number;
4
12
  export declare function boundedHookBudget(value: number | undefined, maximum: number): number;
5
13
  export interface HookChildResult {
6
14
  bytes: Buffer;
@@ -1,12 +1,24 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.HOOK_CLEANUP_MS = exports.HOOK_BUDGET_MS = void 0;
3
+ exports.STOP_HOOK_TIMEOUT_SECONDS = exports.STOP_HOOK_BUDGET_MS = exports.HOOK_CLEANUP_MS = exports.HOOK_BUDGET_MS = void 0;
4
+ exports.hookBudgetFor = hookBudgetFor;
4
5
  exports.boundedHookBudget = boundedHookBudget;
5
6
  exports.runHookChild = runHookChild;
6
7
  // @implements A-SPEC-751.1
8
+ // @implements A-SPEC-769.10
7
9
  const node_child_process_1 = require("node:child_process");
8
10
  exports.HOOK_BUDGET_MS = 18_000;
9
11
  exports.HOOK_CLEANUP_MS = 8_000;
12
+ /**
13
+ * @implements A-SPEC-769.10 — owner decision 2026-10-15: the Stop hook, which runs once at the end of a turn and is
14
+ * fail-open, gets one minute; PreToolUse, which runs before every tool call, keeps 18 s. The harness timeout written
15
+ * for Stop entries leaves the cleanup budget and a margin so the harness never ends the dispatcher first.
16
+ */
17
+ exports.STOP_HOOK_BUDGET_MS = 60_000;
18
+ exports.STOP_HOOK_TIMEOUT_SECONDS = 75;
19
+ function hookBudgetFor(entry) {
20
+ return entry === 'stop' ? exports.STOP_HOOK_BUDGET_MS : exports.HOOK_BUDGET_MS;
21
+ }
10
22
  function boundedHookBudget(value, maximum) {
11
23
  if (value === undefined)
12
24
  return maximum;
@@ -41,4 +41,10 @@ export interface EmbedderOpts {
41
41
  sleep?: (ms: number) => Promise<void>;
42
42
  log?: (line: string) => void;
43
43
  }
44
+ /**
45
+ * @implements A-SPEC-719.3 — the local warm publishes a segment after this many new vectors, as the cloud warm does
46
+ * per batch. Measured 2026-10-15: a single end-of-warm flush let 13 refresh workers each embed the same 3,083
47
+ * documents for up to 1 h 53 min, and any worker ended before its last text landed nothing.
48
+ */
49
+ export declare const LOCAL_WARM_CHECKPOINT = 25;
44
50
  export declare function makeTierEmbedder(tier: SemanticTier, cache: VectorCache, opts?: EmbedderOpts): SemanticRuntime | null;
@@ -1,7 +1,9 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.LOCAL_WARM_CHECKPOINT = void 0;
3
4
  exports.makeTierEmbedder = makeTierEmbedder;
4
5
  // @implements A-SPEC-591
6
+ // @implements A-SPEC-719.3
5
7
  // @implements A-SPEC-478
6
8
  /**
7
9
  * The tier adapters — the productized form of exactly what the measurement scripts proved:
@@ -24,6 +26,12 @@ const tier_1 = require("./tier");
24
26
  const credentials_1 = require("./credentials");
25
27
  const local_model_1 = require("./local-model");
26
28
  const CLOUD_BATCH = 25;
29
+ /**
30
+ * @implements A-SPEC-719.3 — the local warm publishes a segment after this many new vectors, as the cloud warm does
31
+ * per batch. Measured 2026-10-15: a single end-of-warm flush let 13 refresh workers each embed the same 3,083
32
+ * documents for up to 1 h 53 min, and any worker ended before its last text landed nothing.
33
+ */
34
+ exports.LOCAL_WARM_CHECKPOINT = 25;
27
35
  const CLOUD_BACKOFF_MS = 30_000;
28
36
  function makeTierEmbedder(tier, cache, opts = {}) {
29
37
  if (tier.tier === 'none' || tier.model === undefined)
@@ -75,6 +83,8 @@ function makeTierEmbedder(tier, cache, opts = {}) {
75
83
  if (v) {
76
84
  cache.put(t, tag, 'doc', v);
77
85
  computed++;
86
+ if (computed % exports.LOCAL_WARM_CHECKPOINT === 0)
87
+ cache.flush(); // A-SPEC-719.3 — an ended worker keeps this much
78
88
  }
79
89
  }
80
90
  cache.flush();
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.19",
4
+ "version": "0.35.20",
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",