@holmes-lab/holmes-kit 0.35.18 → 0.35.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +83 -0
  2. package/README.md +3 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents.js +13 -7
  5. package/dist/holmes/cli/approve-status.d.ts +4 -1
  6. package/dist/holmes/cli/approve-status.js +10 -0
  7. package/dist/holmes/cli/approve-watch.js +1 -1
  8. package/dist/holmes/cli/approve.d.ts +3 -3
  9. package/dist/holmes/cli/approve.js +12 -7
  10. package/dist/holmes/cli/autonomy.d.ts +13 -6
  11. package/dist/holmes/cli/autonomy.js +105 -16
  12. package/dist/holmes/cli/codex-hooks.js +3 -1
  13. package/dist/holmes/cli/doctor.js +7 -1
  14. package/dist/holmes/cli/index.js +25 -6
  15. package/dist/holmes/cli/init.js +2 -1
  16. package/dist/holmes/cli/runtime-binding.d.ts +18 -1
  17. package/dist/holmes/cli/runtime-binding.js +80 -5
  18. package/dist/holmes/cpg/scan-cache.d.ts +11 -1
  19. package/dist/holmes/cpg/scan-cache.js +72 -2
  20. package/dist/holmes/governance/approval-queue.d.ts +1 -1
  21. package/dist/holmes/governance/approval-queue.js +10 -4
  22. package/dist/holmes/governance/autonomy.d.ts +0 -2
  23. package/dist/holmes/governance/autonomy.js +14 -4
  24. package/dist/holmes/governance/delegation.d.ts +40 -0
  25. package/dist/holmes/governance/delegation.js +151 -0
  26. package/dist/holmes/guardrail/write-target.d.ts +10 -0
  27. package/dist/holmes/guardrail/write-target.js +82 -0
  28. package/dist/holmes/hooks/adapters/antigravity.d.ts +2 -0
  29. package/dist/holmes/hooks/adapters/antigravity.js +8 -1
  30. package/dist/holmes/hooks/pre-tool-use.d.ts +3 -1
  31. package/dist/holmes/hooks/pre-tool-use.js +22 -4
  32. package/dist/holmes/hooks/rtm-refresh-child.d.ts +27 -0
  33. package/dist/holmes/hooks/rtm-refresh-child.js +69 -3
  34. package/dist/holmes/hooks/rtm-refresh.d.ts +1 -0
  35. package/dist/holmes/hooks/rtm-refresh.js +8 -0
  36. package/dist/holmes/hooks/stop.d.ts +8 -0
  37. package/dist/holmes/hooks/stop.js +20 -5
  38. package/dist/holmes/mcp/handlers/spec-approval.d.ts +1 -1
  39. package/dist/holmes/mcp/handlers/spec-approval.js +21 -2
  40. package/dist/holmes/mcp/handlers.d.ts +5 -5
  41. package/dist/holmes/refresh/freshness-coordinator.d.ts +13 -0
  42. package/dist/holmes/refresh/freshness-coordinator.js +42 -2
  43. package/dist/holmes/runtime/dispatch.js +5 -3
  44. package/dist/holmes/runtime/hook-process.d.ts +8 -0
  45. package/dist/holmes/runtime/hook-process.js +13 -1
  46. package/dist/holmes/semantic/embedder.d.ts +6 -0
  47. package/dist/holmes/semantic/embedder.js +10 -0
  48. package/package.json +1 -1
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.MAX_CONSECUTIVE_BLOCKS = exports.STOP_NOTICES = void 0;
36
+ exports.MAX_CONSECUTIVE_BLOCKS = exports.STOP_NOTICES = exports.STOP_TIMING_REPORT_MS = void 0;
37
37
  exports.collectKnownDefects = collectKnownDefects;
38
38
  exports.collectSemanticCoverage = collectSemanticCoverage;
39
39
  exports.collectAnalysisCurrency = collectAnalysisCurrency;
@@ -59,9 +59,11 @@ exports.__setWiredSpecsForTest = __setWiredSpecsForTest;
59
59
  exports.guardCountOrZero = guardCountOrZero;
60
60
  exports.readGuardCount = readGuardCount;
61
61
  exports.collectForbiddenEdgeJudgement = collectForbiddenEdgeJudgement;
62
+ exports.stopSharedScan = stopSharedScan;
62
63
  exports.scanCodeCycles = scanCodeCycles;
63
64
  exports.writeGuardCount = writeGuardCount;
64
65
  // @implements A-SPEC-734
66
+ // @implements A-SPEC-769.9, A-SPEC-769.10, A-SPEC-769.11
65
67
  const fs = __importStar(require("node:fs"));
66
68
  // @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
67
69
  // calls into this file.
@@ -76,7 +78,10 @@ const json_state_1 = require("../project/json-state");
76
78
  const node_child_process_1 = require("node:child_process");
77
79
  // @implements A-SPEC-769.2 — the stage clock and the budget it is measured against.
78
80
  const stop_timing_1 = require("./stop-timing");
81
+ // @implements A-SPEC-769.10 — the Stop hook is measured against its own (60 s) budget.
79
82
  const hook_process_1 = require("../runtime/hook-process");
83
+ /** @implements A-SPEC-769.11 — the stage line prints from 9 s: the 18–29 s range of the 2026-10-15 incident stays visible. */
84
+ exports.STOP_TIMING_REPORT_MS = 9_000;
80
85
  /**
81
86
  * @implements A-SPEC-734 (round 11) — every git child of the Stop hook runs under a timeout, and a timeout or
82
87
  * failure is "no signal": a FIFO `.gitignore` (or a FIFO in place of a tracked file) kept `git status` blocked
@@ -1242,6 +1247,17 @@ function collectForbiddenEdgeJudgement(specs, scanned, now) {
1242
1247
  * @implements A-SPEC-693 — `shared` is a scan the caller already made. When given it is BELIEVED
1243
1248
  * and no second scan runs, so one turn pays for one scan however many judgements read it.
1244
1249
  */
1250
+ /**
1251
+ * @implements A-SPEC-769.9 — the turn's ONE shared scan (A-SPEC-693), served from the content-hash scan cache the
1252
+ * refresh child already keeps. Measured 2026-10-15 at load ~300: uncached 23.0 s against an 18 s budget, refusing every
1253
+ * Stop; through the cache 0.48 s warm. Only unchanged files are served from it.
1254
+ */
1255
+ function stopSharedScan(root, cache) {
1256
+ const { CpgScanner } = require('../cpg/cpg-scanner');
1257
+ const { ScanFileCache, scanCacheDirFor } = require('../cpg/scan-cache');
1258
+ // @implements A-SPEC-769.11 — no compiler pass: it adds only `resolvedCalls`, which neither Stop judgement reads.
1259
+ return new CpgScanner(undefined, cache ?? new ScanFileCache(scanCacheDirFor(root)), { compilerCalls: false }).scan(root, root);
1260
+ }
1245
1261
  function scanCodeCycles(root, shared) {
1246
1262
  try {
1247
1263
  const { CpgScanner } = require('../cpg/cpg-scanner');
@@ -1454,9 +1470,8 @@ if (require.main === module) {
1454
1470
  // run leaves both silent; neither judgement scans again on its own.
1455
1471
  let sharedScan;
1456
1472
  try {
1457
- const { CpgScanner } = require('../cpg/cpg-scanner');
1458
- sharedScan = new CpgScanner().scan(stopProjectRoot(), stopProjectRoot());
1459
- }
1473
+ sharedScan = stopSharedScan(stopProjectRoot());
1474
+ } // A-SPEC-769.9
1460
1475
  catch {
1461
1476
  sharedScan = undefined;
1462
1477
  }
@@ -1696,7 +1711,7 @@ if (require.main === module) {
1696
1711
  // clock fault is swallowed, because an observation never touches the verdict.
1697
1712
  clock.mark('evaluate');
1698
1713
  try {
1699
- const timing = clock.line(hook_process_1.HOOK_BUDGET_MS);
1714
+ const timing = clock.line(hook_process_1.STOP_HOOK_BUDGET_MS, exports.STOP_TIMING_REPORT_MS / hook_process_1.STOP_HOOK_BUDGET_MS);
1700
1715
  if (timing !== null)
1701
1716
  process.stderr.write(`${timing}\n`);
1702
1717
  }
@@ -97,7 +97,7 @@ export declare function createSpecApprovalHandlers(context: SpecApprovalContext)
97
97
  advisoryIds?: Partial<Record<string, string>> | undefined;
98
98
  killsAdvisory?: import("../../review/kills-check").KillsAdvisory | undefined;
99
99
  fttFulfilment?: import("../../rtm/ftt-fulfilment").FttFulfilment | undefined;
100
- impactAdvisoryUnavailable?: "empty" | "unreadable" | undefined;
100
+ impactAdvisoryUnavailable?: "unreadable" | "empty" | undefined;
101
101
  impactGraph?: {
102
102
  status: "current" | "stale" | "unverified";
103
103
  sourceCommit: string | null;
@@ -46,6 +46,7 @@ const validator_1 = require("../../spec/validator");
46
46
  const elicit_approval_1 = require("../elicit-approval");
47
47
  const autonomy_1 = require("../../governance/autonomy");
48
48
  const write_target_1 = require("../../guardrail/write-target");
49
+ const delegation_1 = require("../../governance/delegation"); // @implements A-SPEC-771
49
50
  const approval_grants_1 = require("../../governance/approval-grants");
50
51
  const spec_digest_1 = require("../../spec/spec-digest");
51
52
  const version_conflict_1 = require("../../spec/version-conflict");
@@ -189,10 +190,28 @@ function createSpecApprovalHandlers(context) {
189
190
  risk = 'hitl';
190
191
  if (autonomyOn && risk === 'hitl') {
191
192
  const rule = noIntake ? 'requirement-without-intake' : (0, autonomy_1.specApprovalAutonomyReason)(target.spec, resolver([target.spec]), below);
192
- if (rule !== null)
193
+ if (rule !== null) {
193
194
  autonomyNote = `\n[autonomy: this seal is the operator's — ${rule} (${(0, autonomy_1.autonomyRuleMeaning)(rule)})]`;
195
+ // @implements A-SPEC-771 — the operator's run delegation may cover this very rule: then the seal proceeds
196
+ // as a DELEGATED grant (actor `delegated:<client>`, the run and the rule in the ledger) and no person is
197
+ // asked; otherwise the refusal names which limit of the delegation applied. The grader's verdict above
198
+ // is unchanged — only its consumer learned a third envelope (A-SPEC-552.1 project default, A-SPEC-553.1
199
+ // session marker, and this).
200
+ const delegation = autonomyRoot === undefined ? { active: false, why: 'none' } : (0, delegation_1.readDelegation)(autonomyRoot, new Date().toISOString());
201
+ if (delegation.active && (0, delegation_1.delegationCovers)(delegation.delegation, rule)) {
202
+ const base = autonomousApproval(below?.map((s) => s.id));
203
+ approveResolved = { approval: { ...base, actor: base.actor.replace(/^autonomous:/, 'delegated:'), rationale: `delegated grant (run ${delegation.delegation.run}, rule ${rule})` }, source: 'delegated' };
204
+ decidedSubject = targetSubject;
205
+ }
206
+ else {
207
+ autonomyNote += (0, delegation_1.delegationNote)(delegation, rule);
208
+ }
209
+ }
210
+ }
211
+ if (approveResolved !== undefined) {
212
+ // @implements A-SPEC-771 — delegated above: the existing seal path owns validation and audit from here.
194
213
  }
195
- if (autonomyOn && risk === 'auto') {
214
+ else if (autonomyOn && risk === 'auto') {
196
215
  approveResolved = { approval: autonomousApproval(below?.map((s) => s.id)), source: 'autonomous' };
197
216
  decidedSubject = targetSubject;
198
217
  const direction = (0, autonomy_1.declaredGateDirection)(target.spec);
@@ -735,7 +735,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
735
735
  };
736
736
  }[];
737
737
  graph: {
738
- status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
738
+ status: "current" | "unreadable" | "empty" | "absent" | "stale" | "unverified";
739
739
  sourceCommit: string | null;
740
740
  graphAsOf: string | null;
741
741
  resolutionLimits: string[];
@@ -795,7 +795,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
795
795
  };
796
796
  }[];
797
797
  graph: {
798
- status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
798
+ status: "current" | "unreadable" | "empty" | "absent" | "stale" | "unverified";
799
799
  sourceCommit: string | null;
800
800
  graphAsOf: string | null;
801
801
  resolutionLimits: string[];
@@ -877,7 +877,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
877
877
  };
878
878
  }[];
879
879
  graph: {
880
- status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
880
+ status: "current" | "unreadable" | "empty" | "absent" | "stale" | "unverified";
881
881
  sourceCommit: string | null;
882
882
  graphAsOf: string | null;
883
883
  resolutionLimits: string[];
@@ -943,7 +943,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
943
943
  };
944
944
  }[];
945
945
  graph: {
946
- status: "current" | "empty" | "absent" | "unreadable" | "stale" | "unverified";
946
+ status: "current" | "unreadable" | "empty" | "absent" | "stale" | "unverified";
947
947
  sourceCommit: string | null;
948
948
  graphAsOf: string | null;
949
949
  resolutionLimits: string[];
@@ -1307,7 +1307,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1307
1307
  advisoryIds?: Partial<Record<string, string>> | undefined;
1308
1308
  killsAdvisory?: import("../review/kills-check").KillsAdvisory | undefined;
1309
1309
  fttFulfilment?: import("../rtm/ftt-fulfilment").FttFulfilment | undefined;
1310
- impactAdvisoryUnavailable?: "empty" | "unreadable" | undefined;
1310
+ impactAdvisoryUnavailable?: "unreadable" | "empty" | undefined;
1311
1311
  impactGraph?: {
1312
1312
  status: "current" | "stale" | "unverified";
1313
1313
  sourceCommit: string | null;
@@ -20,6 +20,8 @@ export interface FreshnessReceipt {
20
20
  requirementSemantic: FreshnessLane;
21
21
  /** @implements A-SPEC-768.4 — present only on a completion that failed; never carried into the next lease. */
22
22
  failure?: RefreshFailure;
23
+ /** @implements A-SPEC-719.1 — the detached worker holding this lease; absent on older receipts. */
24
+ pid?: number;
23
25
  }
24
26
  export interface RefreshRequest {
25
27
  workspaceId: string;
@@ -37,6 +39,12 @@ export declare const FRESHNESS_RECEIPT_FILE: string;
37
39
  export declare const FRESHNESS_LEASE_MS: number;
38
40
  /** A failed detached worker is visible immediately but retries only after this bounded pause. */
39
41
  export declare const FRESHNESS_RETRY_MS: number;
42
+ /**
43
+ * @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a jarvis refresh
44
+ * outlived the 2-minute lease, every later request spawned another child, and 13 ran at once (attempt 13, load
45
+ * 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
46
+ */
47
+ export declare const FRESHNESS_WORKER_MAX_MS: number;
40
48
  /**
41
49
  * A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
42
50
  * someone edits, so without an interval the graph would never refresh between commits — the former
@@ -66,6 +74,11 @@ export declare function requestRefresh(root: string, input: RefreshRequest): {
66
74
  * `.ax` under a root that was removed (A-SPEC-724).
67
75
  */
68
76
  export declare function ownsLease(root: string, generation: string): boolean;
77
+ /**
78
+ * @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
79
+ * crashed one. Writes only while that generation still holds the `refreshing` lease.
80
+ */
81
+ export declare function recordLeaseWorker(root: string, generation: string, pid: number): boolean;
69
82
  /** Publish only the lease owner’s terminal observation; a superseded worker cannot overwrite a newer lease. */
70
83
  export declare function completeRefresh(root: string, generation: string, completion: RefreshCompletion, now: Date): FreshnessReceipt | null;
71
84
  /**
@@ -33,15 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.FRESHNESS_REREFRESH_MS = exports.FRESHNESS_RETRY_MS = exports.FRESHNESS_LEASE_MS = exports.FRESHNESS_RECEIPT_FILE = exports.REFRESH_FAILURE_REASON_MAX = void 0;
36
+ exports.FRESHNESS_REREFRESH_MS = exports.FRESHNESS_WORKER_MAX_MS = exports.FRESHNESS_RETRY_MS = exports.FRESHNESS_LEASE_MS = exports.FRESHNESS_RECEIPT_FILE = exports.REFRESH_FAILURE_REASON_MAX = void 0;
37
37
  exports.intakeUsable = intakeUsable;
38
38
  exports.lexicalOnly = lexicalOnly;
39
39
  exports.readFreshnessReceipt = readFreshnessReceipt;
40
40
  exports.requestRefresh = requestRefresh;
41
41
  exports.ownsLease = ownsLease;
42
+ exports.recordLeaseWorker = recordLeaseWorker;
42
43
  exports.completeRefresh = completeRefresh;
43
44
  exports.workspaceIdFor = workspaceIdFor;
44
45
  // @implements A-SPEC-719, A-SPEC-768.4
46
+ // @implements A-SPEC-719.1
45
47
  /**
46
48
  * The durable source of truth for refresh work. A receipt names the workspace and
47
49
  * commit it describes, so an old detached worker cannot make a newer tree look
@@ -58,6 +60,12 @@ exports.FRESHNESS_RECEIPT_FILE = path.join('.ax', 'state', 'fresh-evidence.json'
58
60
  exports.FRESHNESS_LEASE_MS = 2 * 60 * 1000;
59
61
  /** A failed detached worker is visible immediately but retries only after this bounded pause. */
60
62
  exports.FRESHNESS_RETRY_MS = 30 * 1000;
63
+ /**
64
+ * @implements A-SPEC-719.1 — the longest a live worker may hold its lease. Measured 2026-10-15: a jarvis refresh
65
+ * outlived the 2-minute lease, every later request spawned another child, and 13 ran at once (attempt 13, load
66
+ * 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
67
+ */
68
+ exports.FRESHNESS_WORKER_MAX_MS = 30 * 60 * 1000;
61
69
  /**
62
70
  * A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
63
71
  * someone edits, so without an interval the graph would never refresh between commits — the former
@@ -95,6 +103,7 @@ function isReceipt(value) {
95
103
  && (r.startedAt === undefined || typeof r.startedAt === 'string')
96
104
  && (r.completedAt === undefined || typeof r.completedAt === 'string')
97
105
  && (r.retryAt === undefined || typeof r.retryAt === 'string')
106
+ && (r.pid === undefined || (Number.isInteger(r.pid) && r.pid > 0))
98
107
  // @implements A-SPEC-768.4 — a receipt without the field is still a receipt (older builds wrote none).
99
108
  && (r.failure === undefined || (!!r.failure && typeof r.failure === 'object' && typeof r.failure.stage === 'string' && typeof r.failure.reason === 'string'));
100
109
  }
@@ -133,11 +142,29 @@ function writeReceipt(root, receipt) {
133
142
  }
134
143
  }
135
144
  }
145
+ /** @implements A-SPEC-719.1 — signal 0 probes existence only; EPERM means the process exists under another user. */
146
+ function processAlive(pid) {
147
+ try {
148
+ process.kill(pid, 0);
149
+ return true;
150
+ }
151
+ catch (error) {
152
+ return error.code === 'EPERM';
153
+ }
154
+ }
136
155
  function expired(receipt, now) {
137
156
  if (receipt.state !== 'refreshing' || !receipt.startedAt)
138
157
  return false;
139
158
  const started = Date.parse(receipt.startedAt);
140
- return !Number.isFinite(started) || now.getTime() - started >= exports.FRESHNESS_LEASE_MS;
159
+ if (!Number.isFinite(started))
160
+ return true;
161
+ const age = now.getTime() - started;
162
+ if (age >= exports.FRESHNESS_WORKER_MAX_MS)
163
+ return true;
164
+ // @implements A-SPEC-719.1 — a running worker keeps its lease; a crashed one frees it after the short lease.
165
+ if (receipt.pid !== undefined && processAlive(receipt.pid))
166
+ return false;
167
+ return age >= exports.FRESHNESS_LEASE_MS;
141
168
  }
142
169
  function stale(receipt) {
143
170
  return { ...receipt, state: 'stale', graph: 'stale', sourceSemantic: 'stale', requirementSemantic: 'stale' };
@@ -186,6 +213,19 @@ function ownsLease(root, generation) {
186
213
  const receipt = storedReceipt(root);
187
214
  return receipt !== null && receipt.generation === generation && receipt.state === 'refreshing';
188
215
  }
216
+ /**
217
+ * @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
218
+ * crashed one. Writes only while that generation still holds the `refreshing` lease.
219
+ */
220
+ function recordLeaseWorker(root, generation, pid) {
221
+ const previous = storedReceipt(root);
222
+ if (!previous || previous.generation !== generation || previous.state !== 'refreshing')
223
+ return false;
224
+ if (!Number.isInteger(pid) || pid <= 0)
225
+ return false;
226
+ writeReceipt(root, { ...previous, pid });
227
+ return true;
228
+ }
189
229
  /** Publish only the lease owner’s terminal observation; a superseded worker cannot overwrite a newer lease. */
190
230
  function completeRefresh(root, generation, completion, now) {
191
231
  const previous = storedReceipt(root);
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.runDispatch = runDispatch;
37
- // @implements A-SPEC-751, A-SPEC-751.1, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-754
37
+ // @implements A-SPEC-751, A-SPEC-751.1, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-754, A-SPEC-769.10
38
38
  const path = __importStar(require("node:path"));
39
39
  const node_child_process_1 = require("node:child_process");
40
40
  const binding_1 = require("./binding");
@@ -127,11 +127,13 @@ async function runDispatch(opts) {
127
127
  let phaseInput;
128
128
  let phaseSelection;
129
129
  let phaseChild;
130
- const budgetText = String(opts.hookBudgetMs ?? hook_process_1.HOOK_BUDGET_MS);
130
+ // @implements A-SPEC-769.10 — the Stop entry has its own (60 s) budget; every other hook entry keeps 18 s.
131
+ const entryBudget = (0, hook_process_1.hookBudgetFor)(opts.entry);
132
+ const budgetText = String(opts.hookBudgetMs ?? entryBudget);
131
133
  try {
132
134
  if (!['claude', 'codex', 'antigravity'].includes(opts.harness) || !['mcp', 'pre-tool-use', 'stop'].includes(opts.entry))
133
135
  throw new Error('Invalid runtime dispatcher entry or harness');
134
- const hookBudget = (0, hook_process_1.boundedHookBudget)(opts.hookBudgetMs, hook_process_1.HOOK_BUDGET_MS);
136
+ const hookBudget = (0, hook_process_1.boundedHookBudget)(opts.hookBudgetMs, entryBudget);
135
137
  const cleanupBudget = (0, hook_process_1.boundedHookBudget)(opts.cleanupBudgetMs, hook_process_1.HOOK_CLEANUP_MS);
136
138
  let input;
137
139
  if (opts.entry !== 'mcp') {
@@ -1,6 +1,14 @@
1
1
  import { type ChildProcess } from 'node:child_process';
2
2
  export declare const HOOK_BUDGET_MS = 18000;
3
3
  export declare const HOOK_CLEANUP_MS = 8000;
4
+ /**
5
+ * @implements A-SPEC-769.10 — owner decision 2026-10-15: the Stop hook, which runs once at the end of a turn and is
6
+ * fail-open, gets one minute; PreToolUse, which runs before every tool call, keeps 18 s. The harness timeout written
7
+ * for Stop entries leaves the cleanup budget and a margin so the harness never ends the dispatcher first.
8
+ */
9
+ export declare const STOP_HOOK_BUDGET_MS = 60000;
10
+ export declare const STOP_HOOK_TIMEOUT_SECONDS = 75;
11
+ export declare function hookBudgetFor(entry: string): number;
4
12
  export declare function boundedHookBudget(value: number | undefined, maximum: number): number;
5
13
  export interface HookChildResult {
6
14
  bytes: Buffer;
@@ -1,12 +1,24 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.HOOK_CLEANUP_MS = exports.HOOK_BUDGET_MS = void 0;
3
+ exports.STOP_HOOK_TIMEOUT_SECONDS = exports.STOP_HOOK_BUDGET_MS = exports.HOOK_CLEANUP_MS = exports.HOOK_BUDGET_MS = void 0;
4
+ exports.hookBudgetFor = hookBudgetFor;
4
5
  exports.boundedHookBudget = boundedHookBudget;
5
6
  exports.runHookChild = runHookChild;
6
7
  // @implements A-SPEC-751.1
8
+ // @implements A-SPEC-769.10
7
9
  const node_child_process_1 = require("node:child_process");
8
10
  exports.HOOK_BUDGET_MS = 18_000;
9
11
  exports.HOOK_CLEANUP_MS = 8_000;
12
+ /**
13
+ * @implements A-SPEC-769.10 — owner decision 2026-10-15: the Stop hook, which runs once at the end of a turn and is
14
+ * fail-open, gets one minute; PreToolUse, which runs before every tool call, keeps 18 s. The harness timeout written
15
+ * for Stop entries leaves the cleanup budget and a margin so the harness never ends the dispatcher first.
16
+ */
17
+ exports.STOP_HOOK_BUDGET_MS = 60_000;
18
+ exports.STOP_HOOK_TIMEOUT_SECONDS = 75;
19
+ function hookBudgetFor(entry) {
20
+ return entry === 'stop' ? exports.STOP_HOOK_BUDGET_MS : exports.HOOK_BUDGET_MS;
21
+ }
10
22
  function boundedHookBudget(value, maximum) {
11
23
  if (value === undefined)
12
24
  return maximum;
@@ -41,4 +41,10 @@ export interface EmbedderOpts {
41
41
  sleep?: (ms: number) => Promise<void>;
42
42
  log?: (line: string) => void;
43
43
  }
44
+ /**
45
+ * @implements A-SPEC-719.3 — the local warm publishes a segment after this many new vectors, as the cloud warm does
46
+ * per batch. Measured 2026-10-15: a single end-of-warm flush let 13 refresh workers each embed the same 3,083
47
+ * documents for up to 1 h 53 min, and any worker ended before its last text landed nothing.
48
+ */
49
+ export declare const LOCAL_WARM_CHECKPOINT = 25;
44
50
  export declare function makeTierEmbedder(tier: SemanticTier, cache: VectorCache, opts?: EmbedderOpts): SemanticRuntime | null;
@@ -1,7 +1,9 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.LOCAL_WARM_CHECKPOINT = void 0;
3
4
  exports.makeTierEmbedder = makeTierEmbedder;
4
5
  // @implements A-SPEC-591
6
+ // @implements A-SPEC-719.3
5
7
  // @implements A-SPEC-478
6
8
  /**
7
9
  * The tier adapters — the productized form of exactly what the measurement scripts proved:
@@ -24,6 +26,12 @@ const tier_1 = require("./tier");
24
26
  const credentials_1 = require("./credentials");
25
27
  const local_model_1 = require("./local-model");
26
28
  const CLOUD_BATCH = 25;
29
+ /**
30
+ * @implements A-SPEC-719.3 — the local warm publishes a segment after this many new vectors, as the cloud warm does
31
+ * per batch. Measured 2026-10-15: a single end-of-warm flush let 13 refresh workers each embed the same 3,083
32
+ * documents for up to 1 h 53 min, and any worker ended before its last text landed nothing.
33
+ */
34
+ exports.LOCAL_WARM_CHECKPOINT = 25;
27
35
  const CLOUD_BACKOFF_MS = 30_000;
28
36
  function makeTierEmbedder(tier, cache, opts = {}) {
29
37
  if (tier.tier === 'none' || tier.model === undefined)
@@ -75,6 +83,8 @@ function makeTierEmbedder(tier, cache, opts = {}) {
75
83
  if (v) {
76
84
  cache.put(t, tag, 'doc', v);
77
85
  computed++;
86
+ if (computed % exports.LOCAL_WARM_CHECKPOINT === 0)
87
+ cache.flush(); // A-SPEC-719.3 — an ended worker keeps this much
78
88
  }
79
89
  }
80
90
  cache.flush();
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.35.18",
4
+ "version": "0.35.20",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",