@holmes-lab/holmes-kit 0.35.20 → 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 +59 -0
- package/README.md +2 -2
- package/dist/.build-id +1 -1
- package/dist/holmes/cli/doctor.d.ts +12 -0
- package/dist/holmes/cli/doctor.js +194 -1
- 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 +1 -0
- package/dist/holmes/cpg/scan-cache.js +11 -0
- package/dist/holmes/hooks/rtm-refresh-child.d.ts +16 -0
- package/dist/holmes/hooks/rtm-refresh-child.js +49 -15
- package/dist/holmes/hooks/rtm-refresh.d.ts +22 -0
- package/dist/holmes/hooks/rtm-refresh.js +117 -13
- 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 +15 -0
- package/dist/holmes/refresh/freshness-coordinator.js +46 -3
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
<!-- @implements A-SPEC-209 -->
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.35.21] - 2026-10-16
|
|
11
|
+
|
|
12
|
+
Upgrading: restart every session and MCP server (the MCP freshness bridge keeps its slow-git memory per process), and
|
|
13
|
+
run `holmes-kit runtime-binding setup` again so the hooks run this build. Then run `holmes-kit doctor`: a `stop hook
|
|
14
|
+
timeout` WARN naming a Codex plugin snapshot means that snapshot still carries a 30 s Stop.
|
|
15
|
+
|
|
16
|
+
### Fixed
|
|
17
|
+
|
|
18
|
+
- **The background refresh survives a slow git, a failed spawn and a stepped clock** (A-SPEC-719.4, review rounds 1
|
|
19
|
+
and 2 of 719.1–719.3). A `git rev-parse` that did not answer within its bound no longer leases a null-HEAD generation
|
|
20
|
+
(which superseded the live worker and could never complete current): such a request joins the live lease, and
|
|
21
|
+
only with no live lease does it lease a null head as before (A-SPEC-719.6 — a git that refuses for good still
|
|
22
|
+
refreshes). A worker now ends from its 15-second watch only when its workspace is gone or a readable receipt names a newer
|
|
23
|
+
generation or a finished state — a momentarily unreadable receipt is read again. The detached spawn listens for
|
|
24
|
+
`'error'` (ENOENT after a Node upgrade under a long-running MCP server, EAGAIN at the process limit): such a failure
|
|
25
|
+
used to end the MCP server or the Stop hook with an unhandled error and leave a pid-less `refreshing` lease; it now
|
|
26
|
+
closes the lease as failed. The worker's own deadline is 28 minutes, inside the 30-minute lease cap, so a lease never
|
|
27
|
+
expires while its worker may still run; a lease stamped more than two minutes in the future whose recorded worker is
|
|
28
|
+
gone is replaced; the spawn passes `windowsHide`.
|
|
29
|
+
- **doctor names a Stop hook the harness would kill early** (A-SPEC-769.12, 769.13; review rounds 2–3 of
|
|
30
|
+
769.9–769.11). A new `stop hook timeout` row is WARN when a Holmes Stop route that runs has a timeout below 75 s,
|
|
31
|
+
naming each file and the repair. It reads Claude's user and project settings, the Codex user and project hooks
|
|
32
|
+
files (an entry Codex switched off in `hooks.state` is not counted; the key is matched by realpath, as Codex writes
|
|
33
|
+
it) and the Antigravity user and project hooks files (a `holmes-kit` block with `enabled: false` is not counted).
|
|
34
|
+
Only Holmes's own routes count, and a hook without `timeout` runs under the harness default (600 s) and is not
|
|
35
|
+
short. Claude's `init` now writes the Stop hook with `timeout: 75`. A scan-cache save never creates a `.ax`.
|
|
36
|
+
- **One HEAD probe for the lease, the worker and triage** (A-SPEC-719.5, review round 3). The probe runs `rev-parse
|
|
37
|
+
--verify -q HEAD` through the bounded, scrubbed git: an unborn HEAD answers "no head", while a git that refuses
|
|
38
|
+
inside a repository (dubious ownership under another HOME, a broken gitdir) is "not answered" — it no longer leased
|
|
39
|
+
a null head in one harness against the real one in another. The worker and REQ intake/triage read HEAD the same way
|
|
40
|
+
(an exported `GIT_DIR` made every completion `stale` and kept triage `ambiguous`); the worker's final read is not
|
|
41
|
+
skipped by the per-process git-timeout memory its own scan may have set (A-SPEC-719.6), and a final read that still
|
|
42
|
+
does not answer publishes `retry-at` against the lease's own head instead of throwing the refresh away — only when
|
|
43
|
+
the lease named a commit (A-SPEC-719.7): a lease taken while git refused completes under no head, as in 0.35.20, so
|
|
44
|
+
a workspace whose git refuses for good (an unknown repository extension, dubious ownership) is intake-usable after
|
|
45
|
+
one refresh instead of retrying every 30 s. Intake and triage read HEAD past the per-process git-timeout memory, as
|
|
46
|
+
0.35.20 did. A lease more than 30 minutes old or 30 minutes in the future is expired whatever its pid.
|
|
47
|
+
- **A slow git no longer re-spawns the refresh on every request** (A-SPEC-719.8, review round 6; present in 0.35.20
|
|
48
|
+
too). The lease read HEAD with a 2 s bound while the worker and intake waited 5 s: a git answering in 2–5 s (a
|
|
49
|
+
network drive, an antivirus scan) leased no head, the worker completed against the commit as `stale`, and every
|
|
50
|
+
request spawned a new refresh. The lease now waits 5 s too. The semantic-coverage HEAD reads with 0.35.20's bound.
|
|
51
|
+
A lease read that answers only after 2 s is remembered as 0.35.20's 2 s timeout was (A-SPEC-719.9, review round
|
|
52
|
+
7), so the Stop hook's later git reads skip instead of each waiting for the slow git (waiting 5 s had made the Stop
|
|
53
|
+
10–16 s slower on such a git); for that minute a long-running MCP server leases the head the slow read answered
|
|
54
|
+
rather than none (A-SPEC-719.10), so its next request coalesces onto the current refresh. That remembered head is
|
|
55
|
+
keyed by the real path, as the timeout memory is, and when a worker reports that HEAD moved past it, HEAD is read
|
|
56
|
+
again instead of re-leasing the old commit for the rest of the minute (A-SPEC-719.11). A refresh that completes
|
|
57
|
+
while a request waits on its HEAD read no longer looks "completed in the future" to that request and makes it spawn
|
|
58
|
+
another (A-SPEC-719.12; present in 0.35.20 too). A git that is slow once and fast afterwards (a cold first read) no
|
|
59
|
+
longer re-spawns the refresh on every request for the rest of the minute after a commit (A-SPEC-719.13; present in
|
|
60
|
+
0.35.20 too).
|
|
61
|
+
- **doctor reads the installed Codex plugin's Stop hook** (A-SPEC-769.14). A Holmes plugin snapshot under the Codex
|
|
62
|
+
plugins cache whose Stop allows less than 75 s — init before 0.35.20 wrote it at 30 s, as a flat list — makes the
|
|
63
|
+
`stop hook timeout` row WARN instead of PASS; a plugin the Codex config switches off is not counted, nor is a plugin
|
|
64
|
+
Stop hook switched off on its own in `hooks.state`, and a symlinked snapshot is followed (A-SPEC-769.15). A
|
|
65
|
+
snapshot directory or `hooks.json` doctor cannot read is named as unknown instead of passing as clean, and plugin
|
|
66
|
+
switches match case-insensitively on Windows (A-SPEC-769.16) — only where a Holmes plugin keeps its hooks file,
|
|
67
|
+
and never for a plugin switched off (A-SPEC-769.17), including the version's `hooks/` folder (A-SPEC-769.18).
|
|
68
|
+
|
|
10
69
|
## [0.35.20] - 2026-10-15
|
|
11
70
|
|
|
12
71
|
Upgrading: restart every session and MCP server, run `holmes-kit runtime-binding setup` again (the hook dispatcher runs
|
package/README.md
CHANGED
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
<!-- holmes-kit:attest:begin -->
|
|
10
10
|

|
|
11
11
|
|
|
12
|
-
**440/442** source files (99.5%) trace to an approved spec · **
|
|
13
|
-
Measured at `
|
|
12
|
+
**440/442** source files (99.5%) trace to an approved spec · **797/860** approved A-SPECs (92.6%) are anchored from code.
|
|
13
|
+
Measured at `6d468ae1591a` (specs `sha256:a0c4f70f8d10`) — reproduce with `holmes-kit attest`.
|
|
14
14
|
<!-- holmes-kit:attest:end -->
|
|
15
15
|
|
|
16
16
|
---
|
package/dist/.build-id
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
e064e7aa-mvafty6m
|
|
@@ -216,6 +216,18 @@ export declare function mcpProbeEnv(env: NodeJS.ProcessEnv, target: string, plat
|
|
|
216
216
|
* the same honest-diagnosis lineage as the codex-wiring WARN (never a gate).
|
|
217
217
|
*/
|
|
218
218
|
export declare function pushGateCheck(target: string): Check | null;
|
|
219
|
+
/**
|
|
220
|
+
* Holmes Stop hooks whose harness timeout is below the Stop deadline (A-SPEC-769.10: 60 s budget, timeout 75). An
|
|
221
|
+
* install wired before 0.35.20 keeps timeout 30, and the harness then kills a 30–60 s Stop before the dispatcher's own
|
|
222
|
+
* deadline answers. Every file that can route a Holmes Stop for this workspace is read; a Codex entry Codex has
|
|
223
|
+
* switched off in `hooks.state` does not run and is not counted.
|
|
224
|
+
*/
|
|
225
|
+
export declare function stopHookTimeoutCheck(target: string, opts?: {
|
|
226
|
+
home?: string;
|
|
227
|
+
codexConfigPath?: string;
|
|
228
|
+
claudeUserSettings?: string | null;
|
|
229
|
+
agyUserHooks?: string;
|
|
230
|
+
}): Check | null;
|
|
219
231
|
export declare function ciMatrixCheck(target: string): Check | null;
|
|
220
232
|
/**
|
|
221
233
|
* @implements A-SPEC-251.2 (round 43) — no control character from a file reaches the terminal (an `env` key holding ESC and BEL
|
|
@@ -52,6 +52,7 @@ exports.wiringSpawnShared = wiringSpawnShared;
|
|
|
52
52
|
exports.wiringSpawnCheck = wiringSpawnCheck;
|
|
53
53
|
exports.mcpProbeEnv = mcpProbeEnv;
|
|
54
54
|
exports.pushGateCheck = pushGateCheck;
|
|
55
|
+
exports.stopHookTimeoutCheck = stopHookTimeoutCheck;
|
|
55
56
|
exports.ciMatrixCheck = ciMatrixCheck;
|
|
56
57
|
exports.checksJson = checksJson;
|
|
57
58
|
exports.formatChecks = formatChecks;
|
|
@@ -68,7 +69,7 @@ exports.semanticCoverageCheck = semanticCoverageCheck;
|
|
|
68
69
|
exports.semanticTierVerdict = semanticTierVerdict;
|
|
69
70
|
exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
|
|
70
71
|
// @implements A-SPEC-751.4, A-SPEC-733, A-SPEC-727, A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2
|
|
71
|
-
// @implements A-SPEC-704, A-SPEC-710, A-SPEC-712
|
|
72
|
+
// @implements A-SPEC-704, A-SPEC-710, A-SPEC-712, A-SPEC-769.14, A-SPEC-769.16, A-SPEC-769.17, A-SPEC-769.18
|
|
72
73
|
const doctor_guidance_1 = require("./doctor-guidance");
|
|
73
74
|
// @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
|
|
74
75
|
// @implements A-SPEC-594
|
|
@@ -2355,6 +2356,9 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
|
|
|
2355
2356
|
const ci = ciMatrixCheck(target ?? process.cwd()); // @implements A-SPEC-664
|
|
2356
2357
|
if (ci)
|
|
2357
2358
|
checks.push(ci);
|
|
2359
|
+
const st = stopHookTimeoutCheck(target ?? process.cwd(), { ...(opts?.codexConfigPath ? { codexConfigPath: opts.codexConfigPath } : {}) }); // @implements A-SPEC-769.12, A-SPEC-769.13
|
|
2360
|
+
if (st)
|
|
2361
|
+
checks.push(st);
|
|
2358
2362
|
}
|
|
2359
2363
|
checks.push(...(0, worktree_readiness_1.worktreeReadinessChecks)(packageRoot, target ?? process.cwd(), { agent: opts?.agent, codexConfigPath: opts?.codexConfigPath }));
|
|
2360
2364
|
if (extraChecks) {
|
|
@@ -2683,6 +2687,195 @@ function pushGateCheck(target) {
|
|
|
2683
2687
|
return null;
|
|
2684
2688
|
} // diagnosis must never crash doctor
|
|
2685
2689
|
}
|
|
2690
|
+
// @implements A-SPEC-769.12, A-SPEC-769.13
|
|
2691
|
+
/**
|
|
2692
|
+
* Holmes Stop hooks whose harness timeout is below the Stop deadline (A-SPEC-769.10: 60 s budget, timeout 75). An
|
|
2693
|
+
* install wired before 0.35.20 keeps timeout 30, and the harness then kills a 30–60 s Stop before the dispatcher's own
|
|
2694
|
+
* deadline answers. Every file that can route a Holmes Stop for this workspace is read; a Codex entry Codex has
|
|
2695
|
+
* switched off in `hooks.state` does not run and is not counted.
|
|
2696
|
+
*/
|
|
2697
|
+
function stopHookTimeoutCheck(target, opts = {}) {
|
|
2698
|
+
try {
|
|
2699
|
+
if (!fs.existsSync(path.join(target, '.ax')))
|
|
2700
|
+
return null;
|
|
2701
|
+
const { STOP_HOOK_TIMEOUT_SECONDS } = require('../runtime/hook-process');
|
|
2702
|
+
// @implements A-SPEC-769.13 — only Holmes's own Stop routes count: the kernel, the Antigravity bin, or a runtime
|
|
2703
|
+
// router under `.holmes/runtime`. A user's own `stop.js` is not ours (and setup refuses to rewrite it).
|
|
2704
|
+
const isHolmesStop = (cmd) => typeof cmd === 'string'
|
|
2705
|
+
&& /dist[/\\]holmes[/\\]hooks[/\\]stop\.js|holmes-stop-antigravity\.js|[/\\]\.holmes[/\\]runtime[/\\](?:claude|codex|antigravity)-stop\.js/.test(cmd);
|
|
2706
|
+
const json = (file) => { try {
|
|
2707
|
+
return JSON.parse(fs.readFileSync(file, 'utf8'));
|
|
2708
|
+
}
|
|
2709
|
+
catch {
|
|
2710
|
+
return null;
|
|
2711
|
+
} };
|
|
2712
|
+
// @implements A-SPEC-769.13 — no timeout is the harness default (600 s on Claude and Codex), not a short one.
|
|
2713
|
+
const short = (t) => typeof t === 'number' && t < STOP_HOOK_TIMEOUT_SECONDS;
|
|
2714
|
+
const stale = [];
|
|
2715
|
+
// Claude: user settings (CLAUDE_CONFIG_DIR or ~/.claude) and the project files.
|
|
2716
|
+
const claudeUser = opts.claudeUserSettings !== undefined ? opts.claudeUserSettings : (0, claude_switches_1.claudeUserSettingsPath)((0, claude_switches_1.claudeSwitchEnv)());
|
|
2717
|
+
for (const file of [claudeUser, path.join(target, '.claude', 'settings.json'), path.join(target, '.claude', 'settings.local.json')]) {
|
|
2718
|
+
if (file === null)
|
|
2719
|
+
continue;
|
|
2720
|
+
const groups = json(file)?.hooks?.Stop;
|
|
2721
|
+
if (Array.isArray(groups) && groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => isHolmesStop(h?.command) && short(h?.timeout))))
|
|
2722
|
+
stale.push({ file, harness: 'claude' });
|
|
2723
|
+
}
|
|
2724
|
+
// Codex: switched-off entries are keyed by the path Codex resolved — compare the path as given, its realpath and
|
|
2725
|
+
// native realpath, lowercased on Windows (as runtime-binding and codex-oracle do).
|
|
2726
|
+
const codexConfig = opts.codexConfigPath ?? (opts.home !== undefined ? path.join(opts.home, '.codex', 'config.toml') : (0, codex_toml_1.defaultCodexConfigPath)());
|
|
2727
|
+
const norm = (s) => process.platform === 'win32' ? s.toLowerCase() : s;
|
|
2728
|
+
const off = new Set();
|
|
2729
|
+
for (const config of [codexConfig, path.join(target, '.codex', 'config.toml')]) {
|
|
2730
|
+
let raw;
|
|
2731
|
+
try {
|
|
2732
|
+
raw = fs.readFileSync(config, 'utf8');
|
|
2733
|
+
}
|
|
2734
|
+
catch {
|
|
2735
|
+
continue;
|
|
2736
|
+
}
|
|
2737
|
+
const parsed = (0, codex_toml_1.parseCodexConfig)(raw);
|
|
2738
|
+
if (!parsed.ok)
|
|
2739
|
+
continue;
|
|
2740
|
+
const state = (parsed.doc.hooks?.state ?? {});
|
|
2741
|
+
for (const [key, value] of Object.entries(state))
|
|
2742
|
+
if (value && value.enabled === false)
|
|
2743
|
+
off.add(norm(key));
|
|
2744
|
+
}
|
|
2745
|
+
const aliases = (file) => {
|
|
2746
|
+
const out = new Set([file]);
|
|
2747
|
+
try {
|
|
2748
|
+
out.add(fs.realpathSync(file));
|
|
2749
|
+
out.add(fs.realpathSync.native(file));
|
|
2750
|
+
}
|
|
2751
|
+
catch { /* not there */ }
|
|
2752
|
+
return [...out];
|
|
2753
|
+
};
|
|
2754
|
+
for (const file of [path.join(path.dirname(codexConfig), 'hooks.json'), path.join(target, '.codex', 'hooks.json')]) {
|
|
2755
|
+
const groups = json(file)?.hooks?.Stop;
|
|
2756
|
+
if (!Array.isArray(groups))
|
|
2757
|
+
continue;
|
|
2758
|
+
const names = aliases(file);
|
|
2759
|
+
const runs = groups.some((g, i) => Array.isArray(g?.hooks) && g.hooks.some((h, j) => isHolmesStop(h?.command) && short(h?.timeout) && !names.some((n) => off.has(norm(`${n}:stop:${i}:${j}`)))));
|
|
2760
|
+
if (runs)
|
|
2761
|
+
stale.push({ file, harness: 'codex' });
|
|
2762
|
+
}
|
|
2763
|
+
// @implements A-SPEC-769.14 — Codex runs the plugin snapshot it installed, not the workspace copy: read each
|
|
2764
|
+
// `hooks.json` within three levels of a holmes vendor in the plugins cache (the walk runtime-binding makes). Init
|
|
2765
|
+
// before 0.35.20 wrote the plugin's Stop as a flat list of handlers, so both shapes count. A plugin the Codex
|
|
2766
|
+
// config switches off (`[plugins."<name>@<vendor>"] enabled = false`) does not run.
|
|
2767
|
+
const pluginsOff = new Set();
|
|
2768
|
+
for (const config of [codexConfig, path.join(target, '.codex', 'config.toml')]) {
|
|
2769
|
+
let raw;
|
|
2770
|
+
try {
|
|
2771
|
+
raw = fs.readFileSync(config, 'utf8');
|
|
2772
|
+
}
|
|
2773
|
+
catch {
|
|
2774
|
+
continue;
|
|
2775
|
+
}
|
|
2776
|
+
const parsed = (0, codex_toml_1.parseCodexConfig)(raw);
|
|
2777
|
+
if (!parsed.ok)
|
|
2778
|
+
continue;
|
|
2779
|
+
for (const [key, value] of Object.entries((parsed.doc.plugins ?? {})))
|
|
2780
|
+
if (value && value.enabled === false)
|
|
2781
|
+
pluginsOff.add(norm(key));
|
|
2782
|
+
}
|
|
2783
|
+
const cache = path.join(path.dirname(codexConfig), 'plugins', 'cache');
|
|
2784
|
+
const handlers = (entry) => Array.isArray(entry?.hooks) ? entry.hooks : [entry];
|
|
2785
|
+
// @implements A-SPEC-769.15 — entries are typed by stat (a symlinked snapshot is followed; the depth bound ends a
|
|
2786
|
+
// link loop), and a Stop handler switched off per hook in hooks.state — keyed by Codex as
|
|
2787
|
+
// `<plugin>@<vendor>:<file in the plugin version>:stop:<i>:<j>` — does not run.
|
|
2788
|
+
const isDir = (f) => { try {
|
|
2789
|
+
return fs.statSync(f).isDirectory();
|
|
2790
|
+
}
|
|
2791
|
+
catch {
|
|
2792
|
+
return false;
|
|
2793
|
+
} };
|
|
2794
|
+
const isFile = (f) => { try {
|
|
2795
|
+
return fs.statSync(f).isFile();
|
|
2796
|
+
}
|
|
2797
|
+
catch {
|
|
2798
|
+
return false;
|
|
2799
|
+
} };
|
|
2800
|
+
// @implements A-SPEC-769.16 — a Holmes snapshot doctor cannot list or parse is named, not passed as clean; plugin
|
|
2801
|
+
// switch keys fold case on Windows as the per-hook keys do.
|
|
2802
|
+
// @implements A-SPEC-769.17 — only where a Holmes plugin keeps its hooks file: the vendor, plugin and version
|
|
2803
|
+
// levels, and `hooks.json` / `hooks/hooks.json` of the version; a plugin switched off is not walked at all.
|
|
2804
|
+
const unreadable = [];
|
|
2805
|
+
const holmesPlugin = (plugin) => plugin === null || /holmes/i.test(plugin);
|
|
2806
|
+
const visit = (at, depth, vendor, plugin, base) => {
|
|
2807
|
+
let names;
|
|
2808
|
+
// @implements A-SPEC-769.18 — the version's `hooks/` folder holds `hooks/hooks.json`, so it counts as well.
|
|
2809
|
+
const hooksFolder = depth === 3 && base !== null && path.relative(base, at) === 'hooks';
|
|
2810
|
+
try {
|
|
2811
|
+
names = fs.readdirSync(at);
|
|
2812
|
+
}
|
|
2813
|
+
catch {
|
|
2814
|
+
if ((depth <= 2 || hooksFolder) && holmesPlugin(plugin))
|
|
2815
|
+
unreadable.push(at);
|
|
2816
|
+
return;
|
|
2817
|
+
}
|
|
2818
|
+
for (const name of names) {
|
|
2819
|
+
const f = path.join(at, name);
|
|
2820
|
+
if (plugin === null && pluginsOff.has(norm(`${name}@${vendor}`)))
|
|
2821
|
+
continue;
|
|
2822
|
+
if (depth < 3 && isDir(f))
|
|
2823
|
+
visit(f, depth + 1, vendor, plugin ?? name, plugin === null ? null : base ?? f);
|
|
2824
|
+
else if (name === 'hooks.json' && plugin !== null && isFile(f)) {
|
|
2825
|
+
const doc = json(f);
|
|
2826
|
+
if (doc === null) {
|
|
2827
|
+
const rel = path.relative(base ?? at, f).split(path.sep).join('/');
|
|
2828
|
+
if (holmesPlugin(plugin) && (rel === 'hooks.json' || rel === 'hooks/hooks.json'))
|
|
2829
|
+
unreadable.push(f);
|
|
2830
|
+
continue;
|
|
2831
|
+
}
|
|
2832
|
+
const stops = doc?.hooks?.Stop;
|
|
2833
|
+
if (!Array.isArray(stops))
|
|
2834
|
+
continue;
|
|
2835
|
+
const prefix = `${plugin}@${vendor}:${path.relative(base ?? at, f).split(path.sep).join('/')}:stop:`;
|
|
2836
|
+
const runs = stops.some((g, i) => handlers(g).some((h, j) => isHolmesStop(h?.command) && short(h?.timeout)
|
|
2837
|
+
&& !off.has(norm(`${prefix}${i}:${j}`)) && !(Array.isArray(g?.hooks) ? false : off.has(norm(`${prefix}${i}`)))));
|
|
2838
|
+
if (runs)
|
|
2839
|
+
stale.push({ file: f, harness: 'codex-plugin' });
|
|
2840
|
+
}
|
|
2841
|
+
}
|
|
2842
|
+
};
|
|
2843
|
+
let vendors = [];
|
|
2844
|
+
try {
|
|
2845
|
+
vendors = fs.readdirSync(cache).filter((name) => /holmes/i.test(name) && isDir(path.join(cache, name)));
|
|
2846
|
+
}
|
|
2847
|
+
catch { /* no cache */ }
|
|
2848
|
+
for (const vendor of vendors)
|
|
2849
|
+
visit(path.join(cache, vendor), 0, vendor, null, null);
|
|
2850
|
+
// Antigravity: the user hooks file and the project file; a holmes-kit block switched off does not run.
|
|
2851
|
+
for (const file of [opts.agyUserHooks ?? (0, agents_1.agyUserHooksPath)(), path.join(target, '.agents', 'hooks.json')]) {
|
|
2852
|
+
const block = json(file)?.['holmes-kit'];
|
|
2853
|
+
if (!block || block.enabled === false || !Array.isArray(block.Stop))
|
|
2854
|
+
continue;
|
|
2855
|
+
if (block.Stop.some((h) => isHolmesStop(h?.command) && short(h?.timeout)))
|
|
2856
|
+
stale.push({ file, harness: 'antigravity' });
|
|
2857
|
+
}
|
|
2858
|
+
const unread = unreadable.length === 0 ? ''
|
|
2859
|
+
: `Codex plugin snapshot could not be read, so its Stop timeout is unknown: ${unreadable.join(', ')}`;
|
|
2860
|
+
if (stale.length === 0 && unread === '')
|
|
2861
|
+
return { name: 'stop hook timeout', level: 'PASS', detail: `Every Holmes Stop hook that runs allows at least ${STOP_HOOK_TIMEOUT_SECONDS} s` };
|
|
2862
|
+
if (stale.length === 0)
|
|
2863
|
+
return {
|
|
2864
|
+
name: 'stop hook timeout', level: 'WARN', detail: unread,
|
|
2865
|
+
fix: 'Make the snapshot readable by this user, or uninstall that Holmes plugin in Codex and reinstall it from the current workspace',
|
|
2866
|
+
};
|
|
2867
|
+
return {
|
|
2868
|
+
name: 'stop hook timeout', level: 'WARN',
|
|
2869
|
+
detail: `Holmes Stop hook with a timeout below ${STOP_HOOK_TIMEOUT_SECONDS} s (the harness kills a Stop before its 60 s deadline answers): ${stale.map((s) => s.file).join(', ')}${unread === '' ? '' : `; ${unread}`}`,
|
|
2870
|
+
fix: 'Run holmes-kit runtime-binding setup again (operator), or holmes-kit init for a workspace init wired'
|
|
2871
|
+
+ (stale.some((s) => s.harness === 'codex') ? '; then trust the rewritten Codex Stop hook once with /hooks' : '')
|
|
2872
|
+
+ (stale.some((s) => s.harness === 'codex-plugin') ? '; an installed Codex plugin snapshot is not rewritten by setup — uninstall that Holmes plugin in Codex, or reinstall it from the current workspace' : ''),
|
|
2873
|
+
};
|
|
2874
|
+
}
|
|
2875
|
+
catch {
|
|
2876
|
+
return null;
|
|
2877
|
+
} // diagnosis must never crash doctor
|
|
2878
|
+
}
|
|
2686
2879
|
// @implements A-SPEC-664
|
|
2687
2880
|
// The CI matrix as doctor sees it: PASS only for a green row at HEAD; everything else is a WARN that
|
|
2688
2881
|
// says exactly what the ledger says — "not run" when there is no row, the failed suites when red,
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
-
// @implements A-SPEC-100.2
|
|
3
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
4
3
|
exports.AUTONOMY_MCP_ENV = exports.HOLMES_OWNED_MCP_ENV = void 0;
|
|
5
4
|
exports.isHolmesCommand = isHolmesCommand;
|
|
@@ -10,6 +9,9 @@ exports.enableMcpServer = enableMcpServer;
|
|
|
10
9
|
exports.disableMcpServer = disableMcpServer;
|
|
11
10
|
exports.mergeMcpServers = mergeMcpServers;
|
|
12
11
|
exports.removeMcpServer = removeMcpServer;
|
|
12
|
+
// @implements A-SPEC-100.2
|
|
13
|
+
// @implements A-SPEC-769.12
|
|
14
|
+
const hook_process_1 = require("../runtime/hook-process");
|
|
13
15
|
/** A hook entry belongs to holmes-kit iff its command references our hook scripts. */
|
|
14
16
|
function isHolmesCommand(command) {
|
|
15
17
|
return /dist[/\\]holmes[/\\]hooks[/\\](pre-tool-use|stop|session-start)\.js/.test(command) || /\bholmes-(kit|mcp|pre-tool-use|stop)\b/.test(command);
|
|
@@ -42,7 +44,9 @@ function mergeHooks(existing, plan) {
|
|
|
42
44
|
hooks[event] = groups;
|
|
43
45
|
};
|
|
44
46
|
upsert('PreToolUse', { matcher: plan.preToolUseMatcher, hooks: [{ type: 'command', command: plan.preToolUseCommand }] });
|
|
45
|
-
|
|
47
|
+
// Stop takes NO matcher. @implements A-SPEC-769.12 — and carries the Stop timeout: without one Claude applied its own
|
|
48
|
+
// default, unrelated to the dispatcher's 60 s Stop budget.
|
|
49
|
+
upsert('Stop', { hooks: [{ type: 'command', command: plan.stopCommand, timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS }] });
|
|
46
50
|
// @implements A-SPEC-531.2 — the banner hook, wired like Stop (no matcher). Guarded so an older
|
|
47
51
|
// caller that builds a plan without it is unchanged (no empty SessionStart group appears).
|
|
48
52
|
if (plan.sessionStartCommand) {
|
|
@@ -39,6 +39,7 @@ exports.scanCacheDirFor = scanCacheDirFor;
|
|
|
39
39
|
// @implements A-SPEC-113.1
|
|
40
40
|
// @implements A-SPEC-769.9
|
|
41
41
|
// @implements A-SPEC-769.11
|
|
42
|
+
// @implements A-SPEC-769.12
|
|
42
43
|
const fs = __importStar(require("node:fs"));
|
|
43
44
|
const os = __importStar(require("node:os"));
|
|
44
45
|
const path = __importStar(require("node:path"));
|
|
@@ -88,6 +89,7 @@ class ScanFileCache {
|
|
|
88
89
|
dir;
|
|
89
90
|
file;
|
|
90
91
|
tempSuffix;
|
|
92
|
+
axDir;
|
|
91
93
|
entries;
|
|
92
94
|
seen = new Set();
|
|
93
95
|
dirty = false;
|
|
@@ -96,6 +98,10 @@ class ScanFileCache {
|
|
|
96
98
|
constructor(dir, opts = {}) {
|
|
97
99
|
this.dir = dir;
|
|
98
100
|
this.tempSuffix = opts.tempSuffix ?? (() => (0, node_crypto_1.randomBytes)(6).toString('hex'));
|
|
101
|
+
// @implements A-SPEC-769.12, A-SPEC-769.13 — the `.ax` this cache lives under: a save never brings it back.
|
|
102
|
+
const parts = path.resolve(dir).split(path.sep);
|
|
103
|
+
const ax = parts.map((p) => p.toLowerCase()).lastIndexOf('.ax'); // case-insensitive volumes spell it `.AX` too
|
|
104
|
+
this.axDir = ax > 0 ? parts.slice(0, ax + 1).join(path.sep) : null;
|
|
99
105
|
this.file = path.join(dir, 'scan-cache.json');
|
|
100
106
|
try {
|
|
101
107
|
const raw = JSON.parse(fs.readFileSync(this.file, 'utf8'));
|
|
@@ -157,6 +163,11 @@ class ScanFileCache {
|
|
|
157
163
|
}
|
|
158
164
|
try {
|
|
159
165
|
if (this.dirty) {
|
|
166
|
+
// @implements A-SPEC-769.12 — never create a `.ax`: a recursive create recreated one that was removed while the scan
|
|
167
|
+
// ran (init --remove, a deleted workspace), resurrecting the governed marker. Other parents are created as before.
|
|
168
|
+
// @implements A-SPEC-769.13 — whether `.ax` vanished before or after construction: never create it here.
|
|
169
|
+
if (this.axDir !== null && !fs.existsSync(this.axDir))
|
|
170
|
+
throw new Error('the workspace .ax is gone');
|
|
160
171
|
fs.mkdirSync(this.dir, { recursive: true });
|
|
161
172
|
// @implements A-SPEC-769.9 — the Stop hook and the refresh child share this file: a reader in the other
|
|
162
173
|
// process sees the old or the new content, never a partly written one.
|
|
@@ -1,4 +1,8 @@
|
|
|
1
1
|
import { FreshnessLane, FreshnessReceipt, RefreshFailure } from '../refresh/freshness-coordinator';
|
|
2
|
+
type HeadProbe = (root: string) => {
|
|
3
|
+
head: string | null;
|
|
4
|
+
unanswered: boolean;
|
|
5
|
+
};
|
|
2
6
|
/** The error as a bounded reason: its message (never a stack), at most REFRESH_FAILURE_REASON_MAX characters. */
|
|
3
7
|
export declare function failureReason(error: unknown): string;
|
|
4
8
|
/** The detached worker must publish its own failure; the parent is intentionally non-blocking. */
|
|
@@ -30,8 +34,19 @@ export declare function armSupersedeWatch(root: string, generation: string, opts
|
|
|
30
34
|
exit: () => void;
|
|
31
35
|
owns?: (root: string, generation: string) => boolean;
|
|
32
36
|
}): void;
|
|
37
|
+
/**
|
|
38
|
+
* @implements A-SPEC-719.5 — the worker's two timers, armed as one tested unit: the deadline inside the lease cap
|
|
39
|
+
* (A-SPEC-719.1/719.4) and the supersede watch (A-SPEC-719.2). The main block calls only this.
|
|
40
|
+
*/
|
|
41
|
+
export declare function armRefreshWorkerTimers(root: string, generation: string, deps?: {
|
|
42
|
+
deadline?: typeof armWorkerDeadline;
|
|
43
|
+
watch?: typeof armSupersedeWatch;
|
|
44
|
+
exit?: () => void;
|
|
45
|
+
}): void;
|
|
33
46
|
export interface RefreshChildDeps {
|
|
34
47
|
head: (root: string) => string | null;
|
|
48
|
+
/** @implements A-SPEC-719.5 — the classified probe; when absent, `head` is taken as an answered probe. */
|
|
49
|
+
headProbe?: HeadProbe;
|
|
35
50
|
refreshGraph: (root: string) => Promise<unknown>;
|
|
36
51
|
/** @implements A-SPEC-768.4 — a failed lane may carry `detail` (the embedder's message) beside its reason. */
|
|
37
52
|
refreshSource: (root: string) => Promise<{
|
|
@@ -57,3 +72,4 @@ export interface RefreshChildDeps {
|
|
|
57
72
|
export declare function runRefreshChild(root: string, generation: string, deps: RefreshChildDeps): Promise<void>;
|
|
58
73
|
/** The production phases: the scan/build machinery, loaded only inside the detached child. */
|
|
59
74
|
export declare function defaultRefreshChildDeps(env?: NodeJS.ProcessEnv): RefreshChildDeps;
|
|
75
|
+
export {};
|
|
@@ -39,13 +39,15 @@ exports.recordRefreshFailure = recordRefreshFailure;
|
|
|
39
39
|
exports.armWorkerDeadline = armWorkerDeadline;
|
|
40
40
|
exports.lowerOwnPriority = lowerOwnPriority;
|
|
41
41
|
exports.armSupersedeWatch = armSupersedeWatch;
|
|
42
|
+
exports.armRefreshWorkerTimers = armRefreshWorkerTimers;
|
|
42
43
|
exports.runRefreshChild = runRefreshChild;
|
|
43
44
|
exports.defaultRefreshChildDeps = defaultRefreshChildDeps;
|
|
44
|
-
// @implements A-SPEC-719, A-SPEC-734
|
|
45
|
+
// @implements A-SPEC-719, A-SPEC-734, A-SPEC-719.7
|
|
45
46
|
// @implements A-SPEC-566.4
|
|
46
47
|
// @implements A-SPEC-768.4
|
|
47
48
|
// @implements A-SPEC-719.1
|
|
48
49
|
// @implements A-SPEC-719.2
|
|
50
|
+
// @implements A-SPEC-719.6
|
|
49
51
|
// @implements A-SPEC-769.9
|
|
50
52
|
/**
|
|
51
53
|
* The detached refresh child — the ONLY place this slice touches the scan/build machinery. Spawned
|
|
@@ -57,15 +59,30 @@ const fs = __importStar(require("node:fs"));
|
|
|
57
59
|
const os = __importStar(require("node:os"));
|
|
58
60
|
const path = __importStar(require("node:path"));
|
|
59
61
|
const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
|
|
60
|
-
const
|
|
62
|
+
const probeHead = (root) => {
|
|
61
63
|
try {
|
|
62
|
-
const {
|
|
63
|
-
|
|
64
|
+
const { headProbe } = require('./rtm-refresh');
|
|
65
|
+
const { GIT_TIMEOUT_MS } = require('../project/bounded-io');
|
|
66
|
+
// @implements A-SPEC-719.6 — the worker's own scan may have timed out a git call on this root: ask anyway, with
|
|
67
|
+
// the ordinary 5 s bound, rather than be skipped by the memory and publish every finished refresh `retry-at`.
|
|
68
|
+
return headProbe(root, { timeoutMs: GIT_TIMEOUT_MS, ignoreBlock: true });
|
|
64
69
|
}
|
|
65
70
|
catch {
|
|
66
|
-
return null;
|
|
71
|
+
return { head: null, unanswered: true };
|
|
67
72
|
}
|
|
68
73
|
};
|
|
74
|
+
const currentHead = (root) => probeHead(root).head;
|
|
75
|
+
/**
|
|
76
|
+
* @implements A-SPEC-719.5 — the head a completion is written against. When git did not answer, the lease's own head:
|
|
77
|
+
* a mismatch would publish `stale` (no retry pause) and throw a finished refresh away; `retry-at` paces the retry.
|
|
78
|
+
*/
|
|
79
|
+
function completionHead(root, generation, probe) {
|
|
80
|
+
const p = probe(root);
|
|
81
|
+
if (!p.unanswered)
|
|
82
|
+
return p;
|
|
83
|
+
const leased = (0, freshness_coordinator_1.leaseHead)(root, generation);
|
|
84
|
+
return { head: leased === undefined ? null : leased, unanswered: true };
|
|
85
|
+
}
|
|
69
86
|
// @implements A-SPEC-768.4
|
|
70
87
|
/** The error as a bounded reason: its message (never a stack), at most REFRESH_FAILURE_REASON_MAX characters. */
|
|
71
88
|
function failureReason(error) {
|
|
@@ -87,7 +104,7 @@ function recordRefreshFailure(root, generation, head, now, failure) {
|
|
|
87
104
|
function armWorkerDeadline(root, generation, opts) {
|
|
88
105
|
const timer = setTimeout(() => {
|
|
89
106
|
try {
|
|
90
|
-
recordRefreshFailure(root, generation,
|
|
107
|
+
recordRefreshFailure(root, generation, completionHead(root, generation, probeHead).head, (opts.now ?? (() => new Date()))(), { stage: 'child', reason: `worker exceeded ${opts.ms} ms` });
|
|
91
108
|
}
|
|
92
109
|
catch { /* fail-soft: ending is what matters */ }
|
|
93
110
|
opts.exit();
|
|
@@ -115,7 +132,9 @@ function lowerOwnPriority(setPriority = (p) => os.setPriority(p)) {
|
|
|
115
132
|
* 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
|
|
116
133
|
*/
|
|
117
134
|
function armSupersedeWatch(root, generation, opts) {
|
|
118
|
-
|
|
135
|
+
// @implements A-SPEC-719.4 — by default only a readable newer lease or a removed workspace ends the worker:
|
|
136
|
+
// `ownsLease` read a missing or unreadable receipt as "not owned" and ended live workers on a transient read.
|
|
137
|
+
const owns = opts.owns ?? ((r, g) => !(0, freshness_coordinator_1.leaseSuperseded)(r, g));
|
|
119
138
|
const timer = setInterval(() => {
|
|
120
139
|
let current = true;
|
|
121
140
|
try {
|
|
@@ -123,7 +142,7 @@ function armSupersedeWatch(root, generation, opts) {
|
|
|
123
142
|
}
|
|
124
143
|
catch {
|
|
125
144
|
current = true;
|
|
126
|
-
} //
|
|
145
|
+
} // a throwing check is not a supersession
|
|
127
146
|
if (current)
|
|
128
147
|
return;
|
|
129
148
|
clearInterval(timer);
|
|
@@ -131,6 +150,15 @@ function armSupersedeWatch(root, generation, opts) {
|
|
|
131
150
|
}, opts.intervalMs);
|
|
132
151
|
timer.unref?.();
|
|
133
152
|
}
|
|
153
|
+
/**
|
|
154
|
+
* @implements A-SPEC-719.5 — the worker's two timers, armed as one tested unit: the deadline inside the lease cap
|
|
155
|
+
* (A-SPEC-719.1/719.4) and the supersede watch (A-SPEC-719.2). The main block calls only this.
|
|
156
|
+
*/
|
|
157
|
+
function armRefreshWorkerTimers(root, generation, deps = {}) {
|
|
158
|
+
const exit = deps.exit ?? (() => process.exit(0));
|
|
159
|
+
(deps.deadline ?? armWorkerDeadline)(root, generation, { ms: freshness_coordinator_1.FRESHNESS_WORKER_DEADLINE_MS, exit });
|
|
160
|
+
(deps.watch ?? armSupersedeWatch)(root, generation, { intervalMs: exports.REFRESH_SUPERSEDE_POLL_MS, exit });
|
|
161
|
+
}
|
|
134
162
|
/**
|
|
135
163
|
* One refresh run for one lease generation. Every phase that writes is preceded by a lease check,
|
|
136
164
|
* so a superseded worker, or one whose root was removed, stops without writing (A-SPEC-724). Any
|
|
@@ -171,19 +199,28 @@ async function runRefreshChild(root, generation, deps) {
|
|
|
171
199
|
requirement = { status: 'unavailable' };
|
|
172
200
|
failure ??= { stage: 'requirement', reason: failureReason(error) };
|
|
173
201
|
}
|
|
202
|
+
const final = completionHead(root, generation, deps.headProbe ?? ((r) => ({ head: deps.head(r), unanswered: false })));
|
|
203
|
+
// A-SPEC-719.5 — retry after the pause rather than publish `stale`; A-SPEC-719.7 — only when the lease named a commit:
|
|
204
|
+
// a lease taken under a git that refused completes under null as 0.35.20 did (a git that refuses for good would
|
|
205
|
+
// otherwise keep intake refused and re-run the whole refresh every pause).
|
|
206
|
+
if (final.unanswered && final.head !== null) {
|
|
207
|
+
recordRefreshFailure(root, generation, final.head, new Date(), { stage: 'child', reason: 'git did not answer for HEAD at completion' });
|
|
208
|
+
return;
|
|
209
|
+
}
|
|
174
210
|
(0, freshness_coordinator_1.completeRefresh)(root, generation, {
|
|
175
211
|
graph: 'current',
|
|
176
212
|
sourceSemantic: source.lane,
|
|
177
213
|
requirementSemantic: requirement.status === 'discharged' ? 'current'
|
|
178
214
|
: requirement.status === 'not-applicable' ? 'not-adopted'
|
|
179
215
|
: requirement.status === 'suppressed' ? 'suppressed' : 'failed',
|
|
180
|
-
head:
|
|
216
|
+
head: final.head,
|
|
181
217
|
...(failure ? { failure } : {}),
|
|
182
218
|
}, new Date());
|
|
183
219
|
}
|
|
184
220
|
catch (error) {
|
|
185
221
|
try {
|
|
186
|
-
|
|
222
|
+
const head = completionHead(root, generation, deps.headProbe ?? ((r) => ({ head: deps.head(r), unanswered: false }))).head;
|
|
223
|
+
recordRefreshFailure(root, generation, head, new Date(), { stage, reason: failureReason(error) });
|
|
187
224
|
}
|
|
188
225
|
catch { /* fail-soft */ }
|
|
189
226
|
}
|
|
@@ -195,6 +232,7 @@ function defaultRefreshChildDeps(env = process.env) {
|
|
|
195
232
|
const suppressed = typeof env.HOLMES_NO_SEMANTIC_WARM === 'string' && env.HOLMES_NO_SEMANTIC_WARM !== '';
|
|
196
233
|
return {
|
|
197
234
|
head: currentHead,
|
|
235
|
+
headProbe: probeHead,
|
|
198
236
|
refreshGraph: async (root) => {
|
|
199
237
|
const { makeHandlers } = require('../mcp/handlers');
|
|
200
238
|
const { LocalMarkdownRepository } = require('../spec/spec-store');
|
|
@@ -227,12 +265,8 @@ if (require.main === module) {
|
|
|
227
265
|
const root = process.argv[2];
|
|
228
266
|
const generation = process.argv[3];
|
|
229
267
|
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
268
|
if (root && generation)
|
|
235
|
-
|
|
269
|
+
armRefreshWorkerTimers(root, generation);
|
|
236
270
|
// fail-soft: a failed refresh leaves the old graph, which the advisory tolerates
|
|
237
271
|
if (root && generation)
|
|
238
272
|
void runRefreshChild(root, generation, defaultRefreshChildDeps()).catch(() => undefined);
|
|
@@ -1,3 +1,18 @@
|
|
|
1
|
+
/** @implements A-SPEC-719.9 — 0.35.20's lease probe bound: an answer slower than this is remembered as a timeout. */
|
|
2
|
+
export declare const LEASE_SLOW_GIT_MS = 2000;
|
|
3
|
+
/** Test seam: forget every remembered slow-read head. */
|
|
4
|
+
export declare function forgetSlowLeaseHeads(): void;
|
|
5
|
+
/**
|
|
6
|
+
* Same resolution as the child's `headOf`: full commit id, or null outside a repository.
|
|
7
|
+
* @implements A-SPEC-734 (round 13) — through the per-kind memory: a root whose git already timed out is not asked.
|
|
8
|
+
*/
|
|
9
|
+
export declare function headProbe(root: string, opts?: {
|
|
10
|
+
timeoutMs?: number;
|
|
11
|
+
ignoreBlock?: boolean;
|
|
12
|
+
}): {
|
|
13
|
+
head: string | null;
|
|
14
|
+
unanswered: boolean;
|
|
15
|
+
};
|
|
1
16
|
/** @deprecated A compatibility observation interval; receipt leases are the source of truth. */
|
|
2
17
|
export declare const RTM_REFRESH_TTL_MS: number;
|
|
3
18
|
export declare const RTM_REFRESH_MARKER: string;
|
|
@@ -12,6 +27,13 @@ export interface RtmRefreshOpts {
|
|
|
12
27
|
};
|
|
13
28
|
ttlMs?: number;
|
|
14
29
|
head?: string | null;
|
|
30
|
+
/** @implements A-SPEC-719.4 — test seam for the HEAD probe used when `head` is not given. */
|
|
31
|
+
headProbe?: (root: string, opts?: {
|
|
32
|
+
ignoreBlock?: boolean;
|
|
33
|
+
}) => {
|
|
34
|
+
head: string | null;
|
|
35
|
+
unanswered: boolean;
|
|
36
|
+
};
|
|
15
37
|
}
|
|
16
38
|
export type FreshnessBridgeObservation = {
|
|
17
39
|
status: 'spawned';
|
|
@@ -33,11 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
-
exports.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = void 0;
|
|
36
|
+
exports.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = exports.LEASE_SLOW_GIT_MS = void 0;
|
|
37
|
+
exports.forgetSlowLeaseHeads = forgetSlowLeaseHeads;
|
|
38
|
+
exports.headProbe = headProbe;
|
|
37
39
|
exports.maybeSpawnRtmRefresh = maybeSpawnRtmRefresh;
|
|
38
40
|
exports.requestBackgroundFreshness = requestBackgroundFreshness;
|
|
39
41
|
// @implements A-SPEC-724, A-SPEC-723, A-SPEC-719, A-SPEC-734
|
|
40
|
-
// @implements A-SPEC-719.1
|
|
42
|
+
// @implements A-SPEC-719.1, A-SPEC-719.4, A-SPEC-719.5, A-SPEC-719.6, A-SPEC-719.8, A-SPEC-719.9, A-SPEC-719.10, A-SPEC-719.11, A-SPEC-719.12, A-SPEC-719.13
|
|
41
43
|
/**
|
|
42
44
|
* Graph freshness, kept by the product itself. The impact advisory's quality factor was MEASURED to
|
|
43
45
|
* be staleness (an 8-day-old graph found 7 advisories; a 1-second reindex found 17), so the Stop
|
|
@@ -49,17 +51,51 @@ const fs = __importStar(require("node:fs"));
|
|
|
49
51
|
const path = __importStar(require("node:path"));
|
|
50
52
|
const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
|
|
51
53
|
const bounded_io_1 = require("../project/bounded-io");
|
|
54
|
+
/** @implements A-SPEC-719.9 — 0.35.20's lease probe bound: an answer slower than this is remembered as a timeout. */
|
|
55
|
+
exports.LEASE_SLOW_GIT_MS = 2000;
|
|
56
|
+
/**
|
|
57
|
+
* @implements A-SPEC-719.10 — the head a slow lease read answered, per root, for as long as that read keeps the
|
|
58
|
+
* root's repo git blocked: the MCP bridge's next request finds its probe skipped and would lease null — a new
|
|
59
|
+
* refresh against a receipt already current at the commit, each time the previous one ended (0.35.20's storm).
|
|
60
|
+
*/
|
|
61
|
+
const SLOW_LEASE_HEADS = new Map();
|
|
62
|
+
const SLOW_LEASE_HEAD_MS = 60_000;
|
|
63
|
+
/** Test seam: forget every remembered slow-read head. */
|
|
64
|
+
function forgetSlowLeaseHeads() { SLOW_LEASE_HEADS.clear(); }
|
|
65
|
+
/** @implements A-SPEC-719.11 — the key bounded-io's git-timeout memory uses: an alias resolves to the same entry. */
|
|
66
|
+
const slowLeaseKey = (root) => {
|
|
67
|
+
try {
|
|
68
|
+
return fs.realpathSync.native(root);
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
return path.resolve(root);
|
|
72
|
+
}
|
|
73
|
+
};
|
|
52
74
|
/**
|
|
53
75
|
* Same resolution as the child's `headOf`: full commit id, or null outside a repository.
|
|
54
76
|
* @implements A-SPEC-734 (round 13) — through the per-kind memory: a root whose git already timed out is not asked.
|
|
55
77
|
*/
|
|
56
|
-
function
|
|
78
|
+
function headProbe(root, opts = {}) {
|
|
57
79
|
try {
|
|
58
|
-
|
|
59
|
-
|
|
80
|
+
// @implements A-SPEC-719.5 — `--verify -q` exits 1 silently for an unborn HEAD, so a refusal (128: dubious
|
|
81
|
+
// ownership, an unknown extension, a broken gitdir) is told apart from a repository with no commit yet.
|
|
82
|
+
// @implements A-SPEC-719.8 — the lease waits as long as the worker and intake do (5 s): at 2 s a git answering in
|
|
83
|
+
// 2–5 s leased a null head, the worker completed against the commit as `stale`, and every request spawned anew.
|
|
84
|
+
const r = (0, bounded_io_1.gitOnce)(root, ['-C', root, 'rev-parse', '--verify', '-q', 'HEAD'], 'repo', { timeout: opts.timeoutMs ?? bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: opts.ignoreBlock });
|
|
85
|
+
if (r.status === 0 && r.error === undefined)
|
|
86
|
+
return { head: r.stdout.trim() || null, unanswered: false };
|
|
87
|
+
// @implements A-SPEC-719.4 — no exit status (timed out, killed, or skipped by the per-kind memory) is not "no
|
|
88
|
+
// repository": a null head would lease a generation the live worker's HEAD never matches, every request.
|
|
89
|
+
if (r.error?.code === 'ENOENT')
|
|
90
|
+
return { head: null, unanswered: false };
|
|
91
|
+
if (!(0, bounded_io_1.gitEntryAbove)(root))
|
|
92
|
+
return { head: null, unanswered: false }; // the tree says: no repository
|
|
93
|
+
if (r.status === 1)
|
|
94
|
+
return { head: null, unanswered: false }; // a repository with an unborn HEAD
|
|
95
|
+
return { head: null, unanswered: true };
|
|
60
96
|
}
|
|
61
97
|
catch {
|
|
62
|
-
return null;
|
|
98
|
+
return { head: null, unanswered: true };
|
|
63
99
|
} // bounded: a hung git must never hold the Stop hook
|
|
64
100
|
}
|
|
65
101
|
/** @deprecated A compatibility observation interval; receipt leases are the source of truth. */
|
|
@@ -77,9 +113,68 @@ function maybeSpawnRtmRefresh(opts) {
|
|
|
77
113
|
return { status: 'failed' }; // nothing to refresh
|
|
78
114
|
// The lease must name the HEAD the child completes against (A-SPEC-719): a null lease in a git
|
|
79
115
|
// workspace could only ever complete as stale, so intake would never see current evidence.
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
116
|
+
let head;
|
|
117
|
+
// @implements A-SPEC-719.11 — the lease time follows the probe: stamped before a probe that waits for git, a refresh
|
|
118
|
+
// completing meanwhile looked "completed in the future" and every such request spawned again (also in 0.35.20).
|
|
119
|
+
const started = Date.now();
|
|
120
|
+
let now = opts.now;
|
|
121
|
+
const workspaceId = (0, freshness_coordinator_1.workspaceIdFor)(opts.root);
|
|
122
|
+
if (opts.head !== undefined)
|
|
123
|
+
head = opts.head;
|
|
124
|
+
else {
|
|
125
|
+
const read = opts.headProbe ?? headProbe;
|
|
126
|
+
// @implements A-SPEC-719.11 — keyed as the git-timeout memory is, so an alias spelling finds the remembered head.
|
|
127
|
+
const key = slowLeaseKey(opts.root);
|
|
128
|
+
// @implements A-SPEC-719.9 — a read that answered only past 0.35.20's 2 s bound is remembered as that timeout
|
|
129
|
+
// was, so the caller's later git reads (the Stop hook's evaluation) skip instead of each waiting for this git.
|
|
130
|
+
const remember = (probe, from) => {
|
|
131
|
+
if (probe.unanswered)
|
|
132
|
+
return;
|
|
133
|
+
if (Date.now() - from >= exports.LEASE_SLOW_GIT_MS) {
|
|
134
|
+
(0, bounded_io_1.noteGitFailure)(opts.root, { code: 'ETIMEDOUT' }, 'repo');
|
|
135
|
+
SLOW_LEASE_HEADS.set(key, { head: probe.head, at: Date.now() });
|
|
136
|
+
// @implements A-SPEC-719.13 — while the root's git is still blocked, later probes are skipped: keep the head
|
|
137
|
+
// this fast answer gave (forgetting it leased null, and the worker completed stale, for the rest of the minute).
|
|
138
|
+
}
|
|
139
|
+
else if ((0, bounded_io_1.gitRootBlocked)(opts.root, 'repo'))
|
|
140
|
+
SLOW_LEASE_HEADS.set(key, { head: probe.head, at: Date.now() });
|
|
141
|
+
else
|
|
142
|
+
SLOW_LEASE_HEADS.delete(key);
|
|
143
|
+
};
|
|
144
|
+
const probe = read(opts.root);
|
|
145
|
+
remember(probe, started);
|
|
146
|
+
head = probe.head;
|
|
147
|
+
if (probe.unanswered) {
|
|
148
|
+
// @implements A-SPEC-719.6 — join a live lease rather than supersede it (the 719.4 defect); with none, lease a
|
|
149
|
+
// null head as 0.35.20 did, so a git that refuses for good still refreshes.
|
|
150
|
+
const live = (0, freshness_coordinator_1.leaseLive)(opts.root, new Date(now));
|
|
151
|
+
if (live !== null)
|
|
152
|
+
return { status: 'coalesced', generation: live.generation };
|
|
153
|
+
// @implements A-SPEC-719.10 — within the minute, the head this process's slow read answered.
|
|
154
|
+
const remembered = SLOW_LEASE_HEADS.get(key);
|
|
155
|
+
const age = remembered === undefined ? NaN : Date.now() - remembered.at;
|
|
156
|
+
head = remembered !== undefined && age >= 0 && age < SLOW_LEASE_HEAD_MS ? remembered.head : null;
|
|
157
|
+
// @implements A-SPEC-719.11 — a receipt the worker wrote `stale` at the remembered head says HEAD moved: leased
|
|
158
|
+
// again, that head re-spawned the refresh on every request of the minute. Read once more past the memory.
|
|
159
|
+
if (remembered !== undefined && head === remembered.head
|
|
160
|
+
&& (0, freshness_coordinator_1.readFreshnessReceipt)(opts.root, { workspaceId, head, now: new Date(now) })?.state === 'stale') {
|
|
161
|
+
SLOW_LEASE_HEADS.delete(key);
|
|
162
|
+
const again = Date.now();
|
|
163
|
+
const fresh = read(opts.root, { ignoreBlock: true });
|
|
164
|
+
remember(fresh, again);
|
|
165
|
+
head = fresh.unanswered ? null : fresh.head;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
// @implements A-SPEC-719.12 — only a completion stamped inside this request's own wait moves its time; the
|
|
169
|
+
// caller's clock stands otherwise (719.11 added the whole wait, and an exact TTL boundary drifted by the probe).
|
|
170
|
+
const waited = Date.now() - started;
|
|
171
|
+
if (waited > 0) {
|
|
172
|
+
const done = Date.parse((0, freshness_coordinator_1.readFreshnessReceipt)(opts.root, { workspaceId, head, now: new Date(opts.now) })?.completedAt ?? '');
|
|
173
|
+
if (Number.isFinite(done) && done > opts.now && done <= opts.now + waited)
|
|
174
|
+
now = opts.now + waited;
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
const decision = (0, freshness_coordinator_1.requestRefresh)(opts.root, { workspaceId, head, now: new Date(now) });
|
|
83
178
|
if (!decision.spawn)
|
|
84
179
|
return { status: 'coalesced', generation: decision.receipt.generation };
|
|
85
180
|
// Retained only for tools that still display the former marker. The receipt
|
|
@@ -87,12 +182,21 @@ function maybeSpawnRtmRefresh(opts) {
|
|
|
87
182
|
const marker = path.join(opts.root, exports.RTM_REFRESH_MARKER);
|
|
88
183
|
try {
|
|
89
184
|
fs.mkdirSync(path.dirname(marker), { recursive: true });
|
|
90
|
-
fs.writeFileSync(marker, String(
|
|
91
|
-
fs.utimesSync(marker, new Date(
|
|
185
|
+
fs.writeFileSync(marker, String(now));
|
|
186
|
+
fs.utimesSync(marker, new Date(now), new Date(now));
|
|
92
187
|
}
|
|
93
188
|
catch { /* an unwritable marker is not a reason to skip the refresh itself */ }
|
|
94
189
|
try {
|
|
95
|
-
const
|
|
190
|
+
const fail = () => (0, freshness_coordinator_1.completeRefresh)(opts.root, decision.receipt.generation, {
|
|
191
|
+
graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head: decision.receipt.head,
|
|
192
|
+
}, new Date(now));
|
|
193
|
+
const child = opts.spawn(opts.execPath, [opts.scriptPath, opts.root, decision.receipt.generation], { detached: true, stdio: 'ignore', windowsHide: true });
|
|
194
|
+
// @implements A-SPEC-719.4 — ENOENT/EAGAIN arrive as an 'error' event on the next tick, not a throw: unheard,
|
|
195
|
+
// it ended the MCP server or the Stop hook and left a pid-less `refreshing` lease.
|
|
196
|
+
child?.on?.('error', () => { try {
|
|
197
|
+
fail();
|
|
198
|
+
}
|
|
199
|
+
catch { /* fail-soft */ } });
|
|
96
200
|
child?.unref?.();
|
|
97
201
|
// @implements A-SPEC-719.1 — the lease names its worker, so a live refresh is not taken for a crashed one.
|
|
98
202
|
if (typeof child?.pid === 'number') {
|
|
@@ -106,7 +210,7 @@ function maybeSpawnRtmRefresh(opts) {
|
|
|
106
210
|
catch {
|
|
107
211
|
(0, freshness_coordinator_1.completeRefresh)(opts.root, decision.receipt.generation, {
|
|
108
212
|
graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head: decision.receipt.head,
|
|
109
|
-
}, new Date(
|
|
213
|
+
}, new Date(now));
|
|
110
214
|
return { status: 'failed' };
|
|
111
215
|
}
|
|
112
216
|
}
|
|
@@ -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
|
}
|
|
@@ -45,6 +45,11 @@ export declare const FRESHNESS_RETRY_MS: number;
|
|
|
45
45
|
* 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
|
|
46
46
|
*/
|
|
47
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;
|
|
48
53
|
/**
|
|
49
54
|
* A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
|
|
50
55
|
* someone edits, so without an interval the graph would never refresh between commits — the former
|
|
@@ -68,12 +73,22 @@ export declare function requestRefresh(root: string, input: RefreshRequest): {
|
|
|
68
73
|
spawn: boolean;
|
|
69
74
|
receipt: FreshnessReceipt;
|
|
70
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;
|
|
71
80
|
/**
|
|
72
81
|
* True only while `generation` still holds the live lease in an existing root. A worker asks this
|
|
73
82
|
* before each phase that writes, so a superseded or orphaned child stops instead of recreating
|
|
74
83
|
* `.ax` under a root that was removed (A-SPEC-724).
|
|
75
84
|
*/
|
|
76
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;
|
|
77
92
|
/**
|
|
78
93
|
* @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
|
|
79
94
|
* crashed one. Writes only while that generation still holds the `refreshing` lease.
|
|
@@ -33,17 +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_WORKER_MAX_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;
|
|
42
45
|
exports.recordLeaseWorker = recordLeaseWorker;
|
|
43
46
|
exports.completeRefresh = completeRefresh;
|
|
44
47
|
exports.workspaceIdFor = workspaceIdFor;
|
|
45
48
|
// @implements A-SPEC-719, A-SPEC-768.4
|
|
46
|
-
// @implements A-SPEC-719.1
|
|
49
|
+
// @implements A-SPEC-719.1, A-SPEC-719.4, A-SPEC-719.5, A-SPEC-719.6
|
|
47
50
|
/**
|
|
48
51
|
* The durable source of truth for refresh work. A receipt names the workspace and
|
|
49
52
|
* commit it describes, so an old detached worker cannot make a newer tree look
|
|
@@ -66,6 +69,11 @@ exports.FRESHNESS_RETRY_MS = 30 * 1000;
|
|
|
66
69
|
* 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
|
|
67
70
|
*/
|
|
68
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;
|
|
69
77
|
/**
|
|
70
78
|
* A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
|
|
71
79
|
* someone edits, so without an interval the graph would never refresh between commits — the former
|
|
@@ -159,11 +167,18 @@ function expired(receipt, now) {
|
|
|
159
167
|
if (!Number.isFinite(started))
|
|
160
168
|
return true;
|
|
161
169
|
const age = now.getTime() - started;
|
|
162
|
-
|
|
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)
|
|
163
173
|
return true;
|
|
164
174
|
// @implements A-SPEC-719.1 — a running worker keeps its lease; a crashed one frees it after the short lease.
|
|
165
175
|
if (receipt.pid !== undefined && processAlive(receipt.pid))
|
|
166
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;
|
|
167
182
|
return age >= exports.FRESHNESS_LEASE_MS;
|
|
168
183
|
}
|
|
169
184
|
function stale(receipt) {
|
|
@@ -204,6 +219,16 @@ function requestRefresh(root, input) {
|
|
|
204
219
|
writeReceipt(root, receipt);
|
|
205
220
|
return { spawn: true, receipt };
|
|
206
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
|
+
}
|
|
207
232
|
/**
|
|
208
233
|
* True only while `generation` still holds the live lease in an existing root. A worker asks this
|
|
209
234
|
* before each phase that writes, so a superseded or orphaned child stops instead of recreating
|
|
@@ -213,6 +238,24 @@ function ownsLease(root, generation) {
|
|
|
213
238
|
const receipt = storedReceipt(root);
|
|
214
239
|
return receipt !== null && receipt.generation === generation && receipt.state === 'refreshing';
|
|
215
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
|
+
}
|
|
216
259
|
/**
|
|
217
260
|
* @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
|
|
218
261
|
* crashed one. Writes only while that generation still holds the `refreshing` lease.
|
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",
|