@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.
- package/CHANGELOG.md +103 -0
- package/README.md +2 -2
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/agents.js +13 -7
- package/dist/holmes/cli/codex-hooks.js +3 -1
- package/dist/holmes/cli/doctor.d.ts +12 -0
- package/dist/holmes/cli/doctor.js +194 -1
- package/dist/holmes/cli/init.js +2 -1
- package/dist/holmes/cli/runtime-binding.js +4 -3
- package/dist/holmes/cli/settings-merge.d.ts +1 -0
- package/dist/holmes/cli/settings-merge.js +6 -2
- package/dist/holmes/cpg/scan-cache.d.ts +12 -1
- package/dist/holmes/cpg/scan-cache.js +83 -2
- package/dist/holmes/hooks/adapters/antigravity.d.ts +2 -0
- package/dist/holmes/hooks/adapters/antigravity.js +8 -1
- package/dist/holmes/hooks/rtm-refresh-child.d.ts +43 -0
- package/dist/holmes/hooks/rtm-refresh-child.js +110 -10
- package/dist/holmes/hooks/rtm-refresh.d.ts +23 -0
- package/dist/holmes/hooks/rtm-refresh.js +124 -12
- package/dist/holmes/hooks/stop.d.ts +8 -0
- package/dist/holmes/hooks/stop.js +20 -5
- package/dist/holmes/mcp/handlers/graph-operations.js +7 -4
- package/dist/holmes/mcp/handlers/requirement-triage.js +6 -2
- package/dist/holmes/mcp/requirement-triage-evidence.d.ts +7 -0
- package/dist/holmes/mcp/requirement-triage-evidence.js +18 -7
- package/dist/holmes/project/bounded-io.d.ts +1 -0
- package/dist/holmes/project/bounded-io.js +3 -1
- package/dist/holmes/refresh/freshness-coordinator.d.ts +28 -0
- package/dist/holmes/refresh/freshness-coordinator.js +85 -2
- package/dist/holmes/runtime/dispatch.js +5 -3
- package/dist/holmes/runtime/hook-process.d.ts +8 -0
- package/dist/holmes/runtime/hook-process.js +13 -1
- package/dist/holmes/semantic/embedder.d.ts +6 -0
- package/dist/holmes/semantic/embedder.js +10 -0
- 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
|
-
|
|
1458
|
-
|
|
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.
|
|
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
|
-
|
|
145
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
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.
|
|
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",
|