@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
@@ -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
  }
@@ -39,13 +39,14 @@ exports.warmRequirementSemanticCache = warmRequirementSemanticCache;
39
39
  exports.headOf = headOf;
40
40
  exports.refreshSemanticVectors = refreshSemanticVectors;
41
41
  exports.createGraphOperationsHandlers = createGraphOperationsHandlers;
42
- // @implements A-SPEC-719, A-SPEC-734, A-SPEC-741.1, A-SPEC-758.1, A-SPEC-688.1
42
+ // @implements A-SPEC-719, A-SPEC-734, A-SPEC-741.1, A-SPEC-758.1, A-SPEC-688.1, A-SPEC-719.5, A-SPEC-719.8
43
43
  // @implements A-SPEC-614, A-SPEC-613, A-SPEC-100.2, A-SPEC-121.2, A-SPEC-128, A-SPEC-139, A-SPEC-189, A-SPEC-280, A-SPEC-282, A-SPEC-283, A-SPEC-419, A-SPEC-433, A-SPEC-469, A-SPEC-478, A-SPEC-568.1, A-SPEC-568.2, A-SPEC-569.1, A-SPEC-569.2, A-SPEC-569.3, A-SPEC-589
44
44
  // @implements A-SPEC-632
45
45
  const fs = __importStar(require("node:fs"));
46
46
  const path = __importStar(require("node:path"));
47
47
  const hash_cache_1 = require("../../cpg/hash-cache");
48
48
  const root_1 = require("../../project/root");
49
+ const bounded_io_1 = require("../../project/bounded-io");
49
50
  const rtm_builder_1 = require("../../rtm/rtm-builder");
50
51
  const graph_store_1 = require("../../rtm/graph-store");
51
52
  const assoc_arm_1 = require("../../assoc/assoc-arm");
@@ -55,7 +56,6 @@ const tier_1 = require("../../semantic/tier");
55
56
  const vector_cache_1 = require("../../semantic/vector-cache");
56
57
  const embedder_1 = require("../../semantic/embedder");
57
58
  const unreadable_paths_1 = require("../../semantic/unreadable-paths");
58
- const bounded_io_1 = require("../../project/bounded-io");
59
59
  const vector_coverage_1 = require("../../semantic/vector-coverage");
60
60
  // @implements A-SPEC-283 — bumped whenever the graph's node/edge shape changes, so a store written
61
61
  // by an older build is rebuilt rather than read with new assumptions.
@@ -140,9 +140,12 @@ async function warmRequirementSemanticCache(root, specs) {
140
140
  }
141
141
  /** The commit the verdict describes. null when this is not a Git tree — never a fabricated value. */
142
142
  function headOf(root) {
143
+ // @implements A-SPEC-719.5 — the lease, the worker and triage read HEAD through one probe (scrubbed env, bounded):
144
+ // an exported GIT_DIR made this raw call read another repository than the lease, and every completion `stale`.
143
145
  try {
144
- const { execFileSync } = require('node:child_process');
145
- return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
146
+ // @implements A-SPEC-719.8 — with 0.35.20's 5 s bound and past the timeout memory, as its raw read was.
147
+ const { headProbe } = require('../../hooks/rtm-refresh');
148
+ return headProbe(root, { timeoutMs: bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: true }).head;
146
149
  }
147
150
  catch {
148
151
  return null;
@@ -39,7 +39,6 @@ exports.createRequirementTriageHandlers = createRequirementTriageHandlers;
39
39
  // @implements A-SPEC-743, A-SPEC-742, A-SPEC-729, A-SPEC-723, A-SPEC-719, A-SPEC-734, A-SPEC-723.1
40
40
  // @implements A-SPEC-713
41
41
  /** Read-only MCP projection of the pure requirement lifecycle triage model. */
42
- const node_child_process_1 = require("node:child_process");
43
42
  const crypto = __importStar(require("node:crypto"));
44
43
  const path = __importStar(require("node:path"));
45
44
  const test_evidence_1 = require("../../review/test-evidence");
@@ -94,9 +93,14 @@ function lineageOf(id, byId) {
94
93
  }
95
94
  return null;
96
95
  }
96
+ /**
97
+ * @implements A-SPEC-719.6 — through the lease's scrubbed probe (an exported GIT_DIR named another repository).
98
+ * @implements A-SPEC-719.7 — past the process's git-timeout memory, as the raw read of 0.35.20 was.
99
+ */
97
100
  function headOf(root) {
98
101
  try {
99
- return (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
102
+ const { headProbe } = require('../../hooks/rtm-refresh');
103
+ return headProbe(root, { timeoutMs: bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: true }).head ?? '';
100
104
  }
101
105
  catch {
102
106
  return '';
@@ -72,6 +72,13 @@ export declare function validateTriageArtifact(root: string, digest: string, exp
72
72
  * freshness receipt is the current one for this workspace and HEAD. Callers run their own
73
73
  * deterministic refusals first and call this immediately before their first write.
74
74
  */
75
+ /**
76
+ * @implements A-SPEC-719.6 — the HEAD intake judges evidence against, read through the same scrubbed probe as the lease
77
+ * and the worker: the raw `rev-parse HEAD` followed an exported GIT_DIR to another repository and never matched.
78
+ * @implements A-SPEC-719.7 — past the process's git-timeout memory: another call timing out on this root must not
79
+ * leave intake judging against no HEAD for the memory's whole window.
80
+ */
81
+ export declare function intakeHead(root: string): string | null;
75
82
  export declare function validateRequirementIntake(root: string, triageEvidence: unknown): {
76
83
  ok: true;
77
84
  } | {
@@ -40,14 +40,14 @@ exports.consumeRequirementTriageEvidence = consumeRequirementTriageEvidence;
40
40
  exports.hasRequirementIntakeRecord = hasRequirementIntakeRecord;
41
41
  exports.everSealedInLedger = everSealedInLedger;
42
42
  exports.validateTriageArtifact = validateTriageArtifact;
43
+ exports.intakeHead = intakeHead;
43
44
  exports.validateRequirementIntake = validateRequirementIntake;
44
- // @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734
45
+ // @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734, A-SPEC-719.6
45
46
  // @implements A-SPEC-713
46
47
  /** Content-addressed, isolated persistence for advisory requirement triage results. */
47
48
  const crypto = __importStar(require("node:crypto"));
48
49
  const fs = __importStar(require("node:fs"));
49
50
  const path = __importStar(require("node:path"));
50
- const node_child_process_1 = require("node:child_process");
51
51
  const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
52
52
  const ledger_store_1 = require("../governance/ledger-store");
53
53
  const provenance_chain_1 = require("../governance/provenance-chain");
@@ -229,16 +229,27 @@ function validateTriageArtifact(root, digest, expected) {
229
229
  * freshness receipt is the current one for this workspace and HEAD. Callers run their own
230
230
  * deterministic refusals first and call this immediately before their first write.
231
231
  */
232
+ /**
233
+ * @implements A-SPEC-719.6 — the HEAD intake judges evidence against, read through the same scrubbed probe as the lease
234
+ * and the worker: the raw `rev-parse HEAD` followed an exported GIT_DIR to another repository and never matched.
235
+ * @implements A-SPEC-719.7 — past the process's git-timeout memory: another call timing out on this root must not
236
+ * leave intake judging against no HEAD for the memory's whole window.
237
+ */
238
+ function intakeHead(root) {
239
+ try {
240
+ const { headProbe } = require('../hooks/rtm-refresh');
241
+ return headProbe(root, { timeoutMs: bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: true }).head;
242
+ }
243
+ catch {
244
+ return null;
245
+ } // non-git root is null
246
+ }
232
247
  function validateRequirementIntake(root, triageEvidence) {
233
248
  const evidence = triageEvidence;
234
249
  if (!evidence || typeof evidence.digest !== 'string' || typeof evidence.promptDigest !== 'string') {
235
250
  return { ok: false, reason: '새 REQ에는 requirement_triage가 발급한 현재 triage_evidence {digest,promptDigest}가 필요합니다. 같은 prompt로 requirement_triage(persist:true)를 실행한 뒤 다시 시도하십시오.' };
236
251
  }
237
- let head = null;
238
- try {
239
- head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
240
- }
241
- catch { /* non-git root is null */ }
252
+ const head = intakeHead(root);
242
253
  const workspaceId = (0, freshness_coordinator_1.workspaceIdFor)(root);
243
254
  const artifact = validateTriageArtifact(root, evidence.digest, { promptDigest: evidence.promptDigest, workspaceId, head });
244
255
  if (!artifact.ok)
@@ -46,6 +46,7 @@ export declare function gitOnce(root: string, args: string[], kind: GitKind, opt
46
46
  input?: string;
47
47
  timeout?: number;
48
48
  env?: NodeJS.ProcessEnv;
49
+ ignoreBlock?: boolean;
49
50
  }): SpawnSyncReturns<string>;
50
51
  /** Test seam: forget every blocked root. */
51
52
  export declare function resetGitBlocked(): void;
@@ -104,7 +104,9 @@ function noteGitFailure(root, err, kind = 'worktree') {
104
104
  * 27–32 s — measured).
105
105
  */
106
106
  function gitOnce(root, args, kind, opts = {}) {
107
- if (gitRootBlocked(root, kind)) {
107
+ // @implements A-SPEC-719.6 — `ignoreBlock` asks anyway (its own timeout is still recorded): the refresh worker's final
108
+ // HEAD read was skipped because the worker's own scan had timed out a git call, and every refresh ended `retry-at`.
109
+ if (!opts.ignoreBlock && gitRootBlocked(root, kind)) {
108
110
  const error = Object.assign(new Error(`git ${args[0] ?? ''}: not asked — a git child for this root timed out within the last minute`), { code: 'EBLOCKED' });
109
111
  return { pid: 0, output: [null, '', ''], stdout: '', stderr: '', status: null, signal: null, error };
110
112
  }
@@ -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,17 @@ 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;
48
+ /**
49
+ * @implements A-SPEC-719.4 — the worker ends itself this long after it starts: two minutes inside the cap, which counts
50
+ * from the earlier `startedAt`, so the lease never expires while its worker may still run.
51
+ */
52
+ export declare const FRESHNESS_WORKER_DEADLINE_MS: number;
40
53
  /**
41
54
  * A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
42
55
  * someone edits, so without an interval the graph would never refresh between commits — the former
@@ -60,12 +73,27 @@ export declare function requestRefresh(root: string, input: RefreshRequest): {
60
73
  spawn: boolean;
61
74
  receipt: FreshnessReceipt;
62
75
  };
76
+ /** @implements A-SPEC-719.5 — the head `generation`'s lease was taken for; undefined when that lease is not current. */
77
+ export declare function leaseHead(root: string, generation: string): string | null | undefined;
78
+ /** @implements A-SPEC-719.6 — the stored lease while it is `refreshing` and not expired at `now`, else null. */
79
+ export declare function leaseLive(root: string, now: Date): FreshnessReceipt | null;
63
80
  /**
64
81
  * True only while `generation` still holds the live lease in an existing root. A worker asks this
65
82
  * before each phase that writes, so a superseded or orphaned child stops instead of recreating
66
83
  * `.ax` under a root that was removed (A-SPEC-724).
67
84
  */
68
85
  export declare function ownsLease(root: string, generation: string): boolean;
86
+ /**
87
+ * @implements A-SPEC-719.4 — whether a worker for `generation` should end: its workspace is gone, or a READABLE receipt
88
+ * names another generation or a finished state. A missing or unreadable receipt is not an answer (a reader can meet
89
+ * another process's rename on Windows) — the caller asks again at its next poll, and the worker deadline still bounds it.
90
+ */
91
+ export declare function leaseSuperseded(root: string, generation: string): boolean;
92
+ /**
93
+ * @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
94
+ * crashed one. Writes only while that generation still holds the `refreshing` lease.
95
+ */
96
+ export declare function recordLeaseWorker(root: string, generation: string, pid: number): boolean;
69
97
  /** Publish only the lease owner’s terminal observation; a superseded worker cannot overwrite a newer lease. */
70
98
  export declare function completeRefresh(root: string, generation: string, completion: RefreshCompletion, now: Date): FreshnessReceipt | null;
71
99
  /**
@@ -33,15 +33,20 @@ 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_DEADLINE_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
+ exports.leaseHead = leaseHead;
42
+ exports.leaseLive = leaseLive;
41
43
  exports.ownsLease = ownsLease;
44
+ exports.leaseSuperseded = leaseSuperseded;
45
+ exports.recordLeaseWorker = recordLeaseWorker;
42
46
  exports.completeRefresh = completeRefresh;
43
47
  exports.workspaceIdFor = workspaceIdFor;
44
48
  // @implements A-SPEC-719, A-SPEC-768.4
49
+ // @implements A-SPEC-719.1, A-SPEC-719.4, A-SPEC-719.5, A-SPEC-719.6
45
50
  /**
46
51
  * The durable source of truth for refresh work. A receipt names the workspace and
47
52
  * commit it describes, so an old detached worker cannot make a newer tree look
@@ -58,6 +63,17 @@ exports.FRESHNESS_RECEIPT_FILE = path.join('.ax', 'state', 'fresh-evidence.json'
58
63
  exports.FRESHNESS_LEASE_MS = 2 * 60 * 1000;
59
64
  /** A failed detached worker is visible immediately but retries only after this bounded pause. */
60
65
  exports.FRESHNESS_RETRY_MS = 30 * 1000;
66
+ /**
67
+ * @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a jarvis refresh
68
+ * outlived the 2-minute lease, every later request spawned another child, and 13 ran at once (attempt 13, load
69
+ * 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
70
+ */
71
+ exports.FRESHNESS_WORKER_MAX_MS = 30 * 60 * 1000;
72
+ /**
73
+ * @implements A-SPEC-719.4 — the worker ends itself this long after it starts: two minutes inside the cap, which counts
74
+ * from the earlier `startedAt`, so the lease never expires while its worker may still run.
75
+ */
76
+ exports.FRESHNESS_WORKER_DEADLINE_MS = exports.FRESHNESS_WORKER_MAX_MS - 2 * 60 * 1000;
61
77
  /**
62
78
  * A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
63
79
  * someone edits, so without an interval the graph would never refresh between commits — the former
@@ -95,6 +111,7 @@ function isReceipt(value) {
95
111
  && (r.startedAt === undefined || typeof r.startedAt === 'string')
96
112
  && (r.completedAt === undefined || typeof r.completedAt === 'string')
97
113
  && (r.retryAt === undefined || typeof r.retryAt === 'string')
114
+ && (r.pid === undefined || (Number.isInteger(r.pid) && r.pid > 0))
98
115
  // @implements A-SPEC-768.4 — a receipt without the field is still a receipt (older builds wrote none).
99
116
  && (r.failure === undefined || (!!r.failure && typeof r.failure === 'object' && typeof r.failure.stage === 'string' && typeof r.failure.reason === 'string'));
100
117
  }
@@ -133,11 +150,36 @@ function writeReceipt(root, receipt) {
133
150
  }
134
151
  }
135
152
  }
153
+ /** @implements A-SPEC-719.1 — signal 0 probes existence only; EPERM means the process exists under another user. */
154
+ function processAlive(pid) {
155
+ try {
156
+ process.kill(pid, 0);
157
+ return true;
158
+ }
159
+ catch (error) {
160
+ return error.code === 'EPERM';
161
+ }
162
+ }
136
163
  function expired(receipt, now) {
137
164
  if (receipt.state !== 'refreshing' || !receipt.startedAt)
138
165
  return false;
139
166
  const started = Date.parse(receipt.startedAt);
140
- return !Number.isFinite(started) || now.getTime() - started >= exports.FRESHNESS_LEASE_MS;
167
+ if (!Number.isFinite(started))
168
+ return true;
169
+ const age = now.getTime() - started;
170
+ // @implements A-SPEC-719.5 — capped both ways: a lease stamped 30 minutes ahead (clock skew, a foreign pid from a
171
+ // shared VM) is as spent as one 30 minutes old, whatever its pid says.
172
+ if (Math.abs(age) >= exports.FRESHNESS_WORKER_MAX_MS)
173
+ return true;
174
+ // @implements A-SPEC-719.1 — a running worker keeps its lease; a crashed one frees it after the short lease.
175
+ if (receipt.pid !== undefined && processAlive(receipt.pid))
176
+ return false;
177
+ // @implements A-SPEC-719.4 — a lease stamped in the future (a clock step, a workspace shared with a VM) never ages;
178
+ // once its named worker is gone, more than one short lease ahead is as dead as one short lease behind. Without a
179
+ // pid nothing says the worker is gone, so the former rule stands.
180
+ if (receipt.pid !== undefined && age <= -exports.FRESHNESS_LEASE_MS)
181
+ return true;
182
+ return age >= exports.FRESHNESS_LEASE_MS;
141
183
  }
142
184
  function stale(receipt) {
143
185
  return { ...receipt, state: 'stale', graph: 'stale', sourceSemantic: 'stale', requirementSemantic: 'stale' };
@@ -177,6 +219,16 @@ function requestRefresh(root, input) {
177
219
  writeReceipt(root, receipt);
178
220
  return { spawn: true, receipt };
179
221
  }
222
+ /** @implements A-SPEC-719.5 — the head `generation`'s lease was taken for; undefined when that lease is not current. */
223
+ function leaseHead(root, generation) {
224
+ const receipt = storedReceipt(root);
225
+ return receipt !== null && receipt.generation === generation && receipt.state === 'refreshing' ? receipt.head : undefined;
226
+ }
227
+ /** @implements A-SPEC-719.6 — the stored lease while it is `refreshing` and not expired at `now`, else null. */
228
+ function leaseLive(root, now) {
229
+ const receipt = storedReceipt(root);
230
+ return receipt !== null && receipt.state === 'refreshing' && !expired(receipt, now) ? receipt : null;
231
+ }
180
232
  /**
181
233
  * True only while `generation` still holds the live lease in an existing root. A worker asks this
182
234
  * before each phase that writes, so a superseded or orphaned child stops instead of recreating
@@ -186,6 +238,37 @@ function ownsLease(root, generation) {
186
238
  const receipt = storedReceipt(root);
187
239
  return receipt !== null && receipt.generation === generation && receipt.state === 'refreshing';
188
240
  }
241
+ /**
242
+ * @implements A-SPEC-719.4 — whether a worker for `generation` should end: its workspace is gone, or a READABLE receipt
243
+ * names another generation or a finished state. A missing or unreadable receipt is not an answer (a reader can meet
244
+ * another process's rename on Windows) — the caller asks again at its next poll, and the worker deadline still bounds it.
245
+ */
246
+ function leaseSuperseded(root, generation) {
247
+ try {
248
+ if (!fs.statSync(path.join(root, '.ax')).isDirectory())
249
+ return true;
250
+ }
251
+ catch {
252
+ return true;
253
+ }
254
+ const receipt = storedReceipt(root);
255
+ if (receipt === null)
256
+ return false;
257
+ return receipt.generation !== generation || receipt.state !== 'refreshing';
258
+ }
259
+ /**
260
+ * @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
261
+ * crashed one. Writes only while that generation still holds the `refreshing` lease.
262
+ */
263
+ function recordLeaseWorker(root, generation, pid) {
264
+ const previous = storedReceipt(root);
265
+ if (!previous || previous.generation !== generation || previous.state !== 'refreshing')
266
+ return false;
267
+ if (!Number.isInteger(pid) || pid <= 0)
268
+ return false;
269
+ writeReceipt(root, { ...previous, pid });
270
+ return true;
271
+ }
189
272
  /** Publish only the lease owner’s terminal observation; a superseded worker cannot overwrite a newer lease. */
190
273
  function completeRefresh(root, generation, completion, now) {
191
274
  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.21",
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",