@holmes-lab/holmes-kit 0.40.0 → 0.40.1

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 (56) hide show
  1. package/CHANGELOG.md +234 -0
  2. package/README.md +70 -4
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/index.js +25 -19
  5. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  6. package/dist/holmes/cli/interactive-prompt.js +98 -16
  7. package/dist/holmes/config/config.d.ts +17 -0
  8. package/dist/holmes/config/config.js +13 -1
  9. package/dist/holmes/governance/autonomy.d.ts +7 -0
  10. package/dist/holmes/governance/autonomy.js +36 -5
  11. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  12. package/dist/holmes/governance/push-gate-runner.js +40 -3
  13. package/dist/holmes/governance/push-gate.d.ts +13 -2
  14. package/dist/holmes/governance/push-gate.js +106 -14
  15. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  16. package/dist/holmes/guardrail/advisory-line.js +718 -0
  17. package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
  18. package/dist/holmes/guardrail/impact-gate.js +32 -5
  19. package/dist/holmes/hooks/pre-tool-use.d.ts +11 -0
  20. package/dist/holmes/hooks/pre-tool-use.js +44 -5
  21. package/dist/holmes/hooks/session-start.js +17 -1
  22. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  23. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  24. package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
  25. package/dist/holmes/mcp/handlers/test-execution.js +199 -21
  26. package/dist/holmes/mcp/handlers.d.ts +468 -3
  27. package/dist/holmes/mcp/handlers.js +5 -1
  28. package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
  29. package/dist/holmes/mcp/maintenance-analyze.js +4 -2
  30. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  31. package/dist/holmes/mcp/maintenance-evidence.js +4 -1
  32. package/dist/holmes/mcp/tool-schemas.js +13 -7
  33. package/dist/holmes/project/baseline.d.ts +15 -2
  34. package/dist/holmes/project/baseline.js +11 -6
  35. package/dist/holmes/project/bounded-io.d.ts +1 -0
  36. package/dist/holmes/project/bounded-io.js +4 -2
  37. package/dist/holmes/project/change-source.d.ts +4 -0
  38. package/dist/holmes/project/change-source.js +13 -5
  39. package/dist/holmes/project/root.js +3 -1
  40. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  41. package/dist/holmes/review/evidence-mode.js +33 -0
  42. package/dist/holmes/review/head-worktree.d.ts +55 -0
  43. package/dist/holmes/review/head-worktree.js +329 -0
  44. package/dist/holmes/review/mrp.js +13 -3
  45. package/dist/holmes/review/run-provenance.d.ts +45 -0
  46. package/dist/holmes/review/run-provenance.js +314 -0
  47. package/dist/holmes/review/test-evidence.d.ts +174 -0
  48. package/dist/holmes/review/test-evidence.js +330 -2
  49. package/dist/holmes/review/test-reports.d.ts +94 -0
  50. package/dist/holmes/review/test-reports.js +382 -0
  51. package/dist/holmes/review/test-runner.d.ts +176 -65
  52. package/dist/holmes/review/test-runner.js +531 -316
  53. package/dist/holmes/review/test-units.d.ts +159 -0
  54. package/dist/holmes/review/test-units.js +814 -0
  55. package/package.json +1 -1
  56. package/playbooks/publish/PLAYBOOK.md +2 -1
@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
4
4
  exports.isWireTool = isWireTool;
5
5
  exports.wireDispatch = wireDispatch;
6
- // @implements A-SPEC-743, A-SPEC-736, A-SPEC-735, A-SPEC-729, A-SPEC-719, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627, A-SPEC-713, A-SPEC-774.25, A-SPEC-255.1
6
+ // @implements A-SPEC-128.2, A-SPEC-128.4, A-SPEC-128.5, A-SPEC-128.7, A-SPEC-128.10, A-SPEC-743,A-SPEC-736,A-SPEC-735, A-SPEC-729, A-SPEC-719, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627, A-SPEC-713, A-SPEC-774.25, A-SPEC-255.1, A-SPEC-466.1, A-SPEC-466.2, A-SPEC-466.3, A-SPEC-466.4, A-SPEC-466.6
7
7
  // @implements A-SPEC-495 — the maintenance_analyze description carries the semantic-evidence
8
8
  // consumer contract (sem-verify / semCos / semanticAlternates) beside the anti-prediction warning.
9
9
  // @implements A-SPEC-642
@@ -444,18 +444,24 @@ exports.TOOL_SCHEMAS = {
444
444
  },
445
445
  },
446
446
  test_run: {
447
- description: 'Compute the intelligent regression scope, RUN the selected tier (jest or pytest), and record per-A-SPEC EXECUTION evidence. Scopes against a git range when given, otherwise against a baseline — so it works on a project with no version control. A passing run records the baseline the next run scopes against.',
447
+ description: 'Compute the intelligent regression scope, RUN the selected tier (jest or pytest), and record per-A-SPEC EXECUTION evidence. Scopes against a git range when given, otherwise against a baseline — so it works on a project with no version control. A passing FULL run records the baseline the next run scopes against, and the test evidence the push gate reads; a scoped run records only `.ax/ledger/scoped-evidence.json`.',
448
448
  inputSchema: {
449
449
  type: 'object',
450
450
  properties: {
451
451
  root: ROOT_ANY,
452
452
  base: str('Base rev (e.g. HEAD~1). Optional — omit to compare against a baseline.'),
453
453
  head: str('Head rev (e.g. HEAD). Optional — omit to compare against a baseline.'),
454
- since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing test_run). Works with or without version control.'),
455
- mark: str('Baseline label to record when the run passes (default `last-green`). Nothing is recorded for a red or skipped run.'),
454
+ since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing full test_run). Works with or without version control.'),
455
+ mark: str('Baseline label to record when a full run passes (default `last-green`). Nothing is recorded for a red, skipped or scoped run.'),
456
+ // @implements A-SPEC-128.4
457
+ full: bool('Run the whole suite, whatever changed — the run the push gate accepts as evidence. It runs every execution unit (the root, and each directory with its own build or runner configuration) in its own directory, over the files git sees minus ax.config.json testRun.excludeDirs (a slash makes an entry a root-relative path; without one it is a directory name). Afterwards every detected test must have run (notExecuted) and every build root with code must have an executed test (untestedCode). A refusal is fix-tests, collect, rerun or environment. The budget defaults to 120 minutes. Refused together with base/head or mutate.'),
456
458
  mutate: str('T-SPEC id (e.g. T-SPEC-129.1). When set, runs that spec’s declared `kills` mutations against the A-SPEC’s source and reports which SURVIVED — a discriminating-power gap. Selective, opt-in; the ordinary run is skipped.'),
459
+ workers: num('jest worker count, passed as `--maxWorkers`: an integer from 1 to 64; any other number is refused before the run, and null reads as omitted. Optional — omit to keep the project’s own setting. The answer’s `workers` is the count jest applied (null when none). Runners other than jest take no count; when a count was given and such a runner ran, the answer lists them in `workersIgnoredBy`; when nothing took it, `workersIgnored` says why (`mutate`, `no jest group`, `nothing ran`).'),
460
+ timeoutMinutes: num('The time budget in minutes for each runner child of the run (jest, the other adapters, a mutation’s jest run): an integer from 1 to 180; when omitted or null, 30, or 120 for a full: true run; any other number is refused before the run. A run with a child past it ends "not judged": it records no evidence, and a full run records a full attempt that the push gate refuses. The answer and the evidence carry the applied value.'),
457
461
  },
458
462
  required: ['root'],
463
+ // @implements A-SPEC-466.2 — an undeclared key (`maxWorkers`) is refused, never run with that key ignored
464
+ additionalProperties: false,
459
465
  },
460
466
  },
461
467
  issue_localize: {
@@ -571,7 +577,7 @@ exports.TOOL_SCHEMAS = {
571
577
  root: ROOT_ANY,
572
578
  base: str('Base git ref of the diff range. Optional — omit to compare against a baseline.'),
573
579
  head: str('Head git ref of the diff range. Optional — omit to compare against a baseline.'),
574
- since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing test_run). Works with or without version control.'),
580
+ since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing full test_run). Works with or without version control.'),
575
581
  },
576
582
  required: ['root'],
577
583
  },
@@ -592,7 +598,7 @@ exports.TOOL_SCHEMAS = {
592
598
  description: 'Compute the graph-scoped review scope for base..head (impacted specs/tests + unscanned changed files).',
593
599
  inputSchema: {
594
600
  type: 'object',
595
- properties: { root: ROOT_ANY, base: str('Base git ref. Optional — omit to compare against a baseline instead.'), head: str('Head git ref. Optional — omit to compare against a baseline instead.'), since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing test_run). Works with or without version control.'), },
601
+ properties: { root: ROOT_ANY, base: str('Base git ref. Optional — omit to compare against a baseline instead.'), head: str('Head git ref. Optional — omit to compare against a baseline instead.'), since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing full test_run). Works with or without version control.'), },
596
602
  required: ['root'],
597
603
  },
598
604
  },
@@ -604,7 +610,7 @@ exports.TOOL_SCHEMAS = {
604
610
  root: ROOT_ANY,
605
611
  base: str('Base git ref. Optional — omit to compare against a baseline instead.'),
606
612
  head: str('Head git ref. Optional — omit to compare against a baseline instead.'),
607
- since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing test_run). Works with or without version control.'),
613
+ since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing full test_run). Works with or without version control.'),
608
614
  budget: num('Optional token budget for the review package (default 4000).'),
609
615
  },
610
616
  required: ['root'],
@@ -1,3 +1,4 @@
1
+ import { type FullMode } from '../review/evidence-mode';
1
2
  /**
2
3
  * A NAMED reference point: "the tree as it was when this label was taken".
3
4
  *
@@ -20,6 +21,16 @@ export interface Baseline {
20
21
  takenAt: string;
21
22
  /** Project-relative POSIX path -> content hash. */
22
23
  files: Record<string, string>;
24
+ /** @implements A-SPEC-128.2 — the run that verified this tree; absent before 128.2. Informational: trust reads the anchor. */
25
+ tier?: string;
26
+ mode?: string;
27
+ ranFileCount?: number;
28
+ }
29
+ /** @implements A-SPEC-128.2 — what a passing run says about itself when it records a baseline. */
30
+ export interface BaselineMeta {
31
+ tier: string;
32
+ mode: FullMode;
33
+ ranFileCount: number;
23
34
  }
24
35
  /**
25
36
  * @implements A-SPEC-134
@@ -30,7 +41,7 @@ export interface Baseline {
30
41
  */
31
42
  export declare function baselineDigest(files: Record<string, string>): string;
32
43
  /** Write (or replace) a labelled baseline. One label holds exactly one reference point. */
33
- export declare function writeBaseline(root: string, label: string, files: Record<string, string>): Baseline;
44
+ export declare function writeBaseline(root: string, label: string, files: Record<string, string>, meta?: BaselineMeta): Baseline;
34
45
  /**
35
46
  * @implements A-SPEC-134
36
47
  * Is this baseline still the one that was recorded? Recompute its digest from the on-disk files and
@@ -38,7 +49,9 @@ export declare function writeBaseline(root: string, label: string, files: Record
38
49
  * digest and no entry matches → false. A missing baseline or missing/unreadable chain → false:
39
50
  * cannot-verify is not permission to narrow (the caller degrades to full scope).
40
51
  */
41
- export declare function isBaselineTrusted(root: string, label: string, ledgerFile: string): boolean;
52
+ export declare function isBaselineTrusted(root: string, label: string, ledgerFile: string, opts?: {
53
+ requireMode?: FullMode;
54
+ }): boolean;
42
55
  /**
43
56
  * Read a baseline, or null when there is none.
44
57
  *
@@ -40,11 +40,12 @@ exports.isBaselineTrusted = isBaselineTrusted;
40
40
  exports.readBaseline = readBaseline;
41
41
  exports.shouldRecordBaseline = shouldRecordBaseline;
42
42
  exports.listBaselines = listBaselines;
43
- // @implements A-SPEC-128, A-SPEC-222.10
43
+ // @implements A-SPEC-128, A-SPEC-222.10, A-SPEC-128.2, A-SPEC-128.4, A-SPEC-128.5
44
44
  const fs = __importStar(require("node:fs"));
45
45
  const path = __importStar(require("node:path"));
46
46
  const node_crypto_1 = require("node:crypto");
47
47
  const ledger_store_1 = require("../governance/ledger-store");
48
+ const evidence_mode_1 = require("../review/evidence-mode");
48
49
  /**
49
50
  * A NAMED reference point: "the tree as it was when this label was taken".
50
51
  *
@@ -87,14 +88,14 @@ function baselineDigest(files) {
87
88
  }
88
89
  const ledgerFor = (root) => path.join(root, '.ax', 'ledger', 'provenance.jsonl');
89
90
  /** Write (or replace) a labelled baseline. One label holds exactly one reference point. */
90
- function writeBaseline(root, label, files) {
91
+ function writeBaseline(root, label, files, meta) {
91
92
  assertLabel(label);
92
93
  // Keys sorted so the stored file is byte-stable for the same input; a diffable baseline is easier
93
94
  // to inspect, and instability here would show up as noise in any tooling that reads it.
94
95
  const sorted = {};
95
96
  for (const k of Object.keys(files).sort())
96
97
  sorted[k] = files[k];
97
- const baseline = { label, takenAt: new Date().toISOString(), files: sorted };
98
+ const baseline = { label, takenAt: new Date().toISOString(), files: sorted, ...(meta ?? {}) };
98
99
  fs.mkdirSync(path.dirname(fileFor(root, label)), { recursive: true });
99
100
  fs.writeFileSync(fileFor(root, label), `${JSON.stringify(baseline, null, 2)}\n`);
100
101
  // @implements A-SPEC-134
@@ -106,7 +107,9 @@ function writeBaseline(root, label, files) {
106
107
  new ledger_store_1.FileLedgerStore(path.dirname(ledgerFor(root))).append({
107
108
  ts: baseline.takenAt, actor: 'holmes-kit', kind: 'baseline-recorded',
108
109
  summary: `baseline ${label} recorded (${Object.keys(sorted).length} files)`,
109
- inputs: [label, baselineDigest(sorted)], rationale: '', authorization: '',
110
+ // @implements A-SPEC-128.2 — the run's mode rides on the chain, where a hand-edit of the file cannot reach it
111
+ // @implements A-SPEC-128.4 — the token comes from the one module that spells it
112
+ inputs: [label, baselineDigest(sorted), ...(meta ? [(0, evidence_mode_1.modeAnchor)(meta.mode)] : [])], rationale: '', authorization: '',
110
113
  });
111
114
  }
112
115
  catch { /* unanchored baseline degrades to untrusted on read, never throws the write */ }
@@ -119,7 +122,7 @@ function writeBaseline(root, label, files) {
119
122
  * digest and no entry matches → false. A missing baseline or missing/unreadable chain → false:
120
123
  * cannot-verify is not permission to narrow (the caller degrades to full scope).
121
124
  */
122
- function isBaselineTrusted(root, label, ledgerFile) {
125
+ function isBaselineTrusted(root, label, ledgerFile, opts = {}) {
123
126
  const baseline = readBaseline(root, label);
124
127
  if (!baseline)
125
128
  return false;
@@ -154,7 +157,9 @@ function isBaselineTrusted(root, label, ledgerFile) {
154
157
  }
155
158
  for (const evt of events) {
156
159
  if (evt.kind === 'baseline-recorded' && Array.isArray(evt.inputs)
157
- && evt.inputs.includes(label) && evt.inputs.includes(digest))
160
+ && evt.inputs.includes(label) && evt.inputs.includes(digest)
161
+ // @implements A-SPEC-128.2 — a reader that narrows trusts only a tree a full run verified
162
+ && (!opts.requireMode || evt.inputs.includes((0, evidence_mode_1.modeAnchor)(opts.requireMode))))
158
163
  return true;
159
164
  }
160
165
  return false;
@@ -48,6 +48,7 @@ export declare function gitOnce(root: string, args: string[], kind: GitKind, opt
48
48
  env?: NodeJS.ProcessEnv;
49
49
  pinned?: JudgmentPins;
50
50
  ignoreBlock?: boolean;
51
+ record?: boolean;
51
52
  }): SpawnSyncReturns<string>;
52
53
  /**
53
54
  * @implements A-SPEC-222.13 — gitOnce with stdout as bytes: a batch of blobs is cut at byte offsets, so its output must
@@ -50,7 +50,7 @@ exports.judgmentPins = judgmentPins;
50
50
  exports.inertDriverArgs = inertDriverArgs;
51
51
  exports.inertGitConfig = inertGitConfig;
52
52
  exports.gitUnanswered = gitUnanswered;
53
- // @implements A-SPEC-734, A-SPEC-222.13, A-SPEC-102.30, A-SPEC-102.31
53
+ // @implements A-SPEC-734, A-SPEC-222.13, A-SPEC-102.30, A-SPEC-102.31, A-SPEC-333.9
54
54
  /**
55
55
  * Bounded I/O shared by every caller on a hook, MCP or scan path (A-SPEC-734 round 12).
56
56
  *
@@ -119,7 +119,9 @@ function gitOnce(root, args, kind, opts = {}) {
119
119
  const env = { ...gitEnv(opts.env ?? process.env), ...pinnedOnly(opts.pinned) };
120
120
  const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: opts.cwd ?? root, input: opts.input, encoding: 'utf8', timeout: opts.timeout ?? exports.GIT_TIMEOUT_MS, killSignal: 'SIGKILL',
121
121
  maxBuffer: exports.GIT_MAX_BUFFER, windowsHide: true, env, stdio: [opts.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
122
- noteGitFailure(root, r, kind);
122
+ // @implements A-SPEC-333.9 — `record: false`: a timeout set by the caller's own deadline is not the root's slowness
123
+ if (opts.record !== false)
124
+ noteGitFailure(root, r, kind);
123
125
  return r;
124
126
  }
125
127
  /**
@@ -1,3 +1,4 @@
1
+ import type { FullMode } from '../review/evidence-mode';
1
2
  /**
2
3
  * "What changed since a reference point" — the one question that genuinely needed version control,
3
4
  * behind a port with two adapters so it does not need it any more.
@@ -62,9 +63,12 @@ export declare class SnapshotChangeSource implements ChangeSource {
62
63
  constructor(root: string, label: string, opts?: {
63
64
  isIgnored?: (relPath: string) => boolean;
64
65
  verify?: string;
66
+ requireMode?: FullMode;
65
67
  });
66
68
  /** Trusted iff a baseline exists AND (no verify requested OR its digest is anchored on the chain). */
67
69
  private trustedBaseline;
70
+ /** @implements A-SPEC-128.2 — anchored, but not as a full run's tree. */
71
+ private notFromFullRun;
68
72
  changes(): ChangeSet | null;
69
73
  describe(): ChangeSourceInfo;
70
74
  }
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.EMPTY_CHANGE_SET = exports.GitChangeSource = exports.SnapshotChangeSource = exports.hashOf = exports.isDerivedState = void 0;
37
37
  exports.hashTree = hashTree;
38
38
  exports.diffHashes = diffHashes;
39
- // @implements A-SPEC-128, A-SPEC-734, A-SPEC-794.58
39
+ // @implements A-SPEC-128, A-SPEC-734, A-SPEC-794.58, A-SPEC-128.2, A-SPEC-128.5
40
40
  const fs = __importStar(require("node:fs"));
41
41
  const path = __importStar(require("node:path"));
42
42
  const node_crypto_1 = require("node:crypto");
@@ -134,6 +134,8 @@ class SnapshotChangeSource {
134
134
  // @implements A-SPEC-134 — `verify` is the provenance ledger path. When set, a baseline whose
135
135
  // digest is not anchored on the chain (tampered, or written unanchored) is treated as ABSENT:
136
136
  // a forged narrowing must never be honored. Omitted (pure unit tests) → today's behavior.
137
+ // @implements A-SPEC-128.2 — `requireMode: 'full'` (with `verify`): only an anchor that says a full run verified the
138
+ // tree is trusted; a scoped green or a legacy anchor degrades to full scope.
137
139
  opts = {}) {
138
140
  this.root = root;
139
141
  this.label = label;
@@ -144,10 +146,14 @@ class SnapshotChangeSource {
144
146
  const baseline = (0, baseline_1.readBaseline)(this.root, this.label);
145
147
  if (!baseline)
146
148
  return null;
147
- if (this.opts.verify && !(0, baseline_1.isBaselineTrusted)(this.root, this.label, this.opts.verify))
149
+ if (this.opts.verify && !(0, baseline_1.isBaselineTrusted)(this.root, this.label, this.opts.verify, { requireMode: this.opts.requireMode }))
148
150
  return null;
149
151
  return baseline;
150
152
  }
153
+ /** @implements A-SPEC-128.2 — anchored, but not as a full run's tree. */
154
+ notFromFullRun() {
155
+ return !!this.opts.verify && !!this.opts.requireMode && (0, baseline_1.isBaselineTrusted)(this.root, this.label, this.opts.verify);
156
+ }
151
157
  changes() {
152
158
  const baseline = this.trustedBaseline();
153
159
  if (!baseline)
@@ -164,9 +170,11 @@ class SnapshotChangeSource {
164
170
  detectsRenames: false,
165
171
  available: trusted !== null,
166
172
  ...(trusted ? {} : {
167
- reason: tampered
168
- ? `baseline "${this.label}" failed its integrity check (not anchored on the provenance chain) — treating as absent, full scope`
169
- : `no baseline named "${this.label}" — run a passing test_run, or take one explicitly`,
173
+ reason: tampered && this.notFromFullRun()
174
+ ? `baseline "${this.label}" is not from a full run (its anchor does not say mode:full) — treating as absent, full scope`
175
+ : tampered
176
+ ? `baseline "${this.label}" failed its integrity check (not anchored on the provenance chain) — treating as absent, full scope`
177
+ : `no baseline named "${this.label}" — run a passing full test_run, or take one explicitly`,
170
178
  }),
171
179
  };
172
180
  }
@@ -106,7 +106,9 @@ function cleanSubprocessEnv(env = process.env) {
106
106
  // "Do nothing" is the one npm setting that contradicts what an evidence run is for. It is named, not
107
107
  // swept: a `/^npm_config_/` sweep would take the registry, the cache and the proxy with it, and a
108
108
  // suite behind a private registry would go red for a reason that has nothing to do with the tree.
109
- const TEST_SCRUB_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_GATE_BYPASS', 'HOLMES_MCP_AUTORELOAD', 'HOLMES_MCP_PROFILE', 'HOLMES_AUTONOMOUS_APPROVAL', 'NPM_CONFIG_DRY_RUN']);
109
+ // @implements A-SPEC-128.14 — V1: `PYTEST_ADDOPTS` narrowed a full run (`-k`, reviewer B M1); a test runner never takes it.
110
+ // @implements A-SPEC-128.15 — P3: nor `PYTEST_PLUGINS`, which loads a plugin the project did not declare.
111
+ const TEST_SCRUB_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_GATE_BYPASS', 'HOLMES_MCP_AUTORELOAD', 'HOLMES_MCP_PROFILE', 'HOLMES_AUTONOMOUS_APPROVAL', 'NPM_CONFIG_DRY_RUN', 'PYTEST_ADDOPTS', 'PYTEST_PLUGINS']);
110
112
  function cleanTestEnv(env = process.env) {
111
113
  const cleaned = cleanSubprocessEnv(env);
112
114
  for (const k of Object.keys(cleaned)) {
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The one place the full-run tokens live (A-SPEC-128.4 §5): the mode a full run records, the provenance input that says
3
+ * a baseline was verified by such a run, and the call a refusal names. The write side, the predicate, the trust check, the
4
+ * push gate and the merge-ready package all read these, so the spelling cannot drift between them.
5
+ */
6
+ export declare const FULL_MODE: "full";
7
+ /** @implements A-SPEC-128.5 — the mode a full record and a full anchor carry, as a type. */
8
+ export type FullMode = typeof FULL_MODE;
9
+ /** The provenance input a baseline anchor carries for the mode of the run that verified it. */
10
+ export declare function modeAnchor(mode: FullMode): string;
11
+ /** @implements A-SPEC-128.4 — the one call that clears a refusal: the refusal names it, and running it reaches allow. */
12
+ export declare const FULL_RUN_CALL = "test_run({root, full: true})";
13
+ /** @implements A-SPEC-128.5 — the default budget of a full run, and the ceiling a next call may ask for. */
14
+ export declare const FULL_RUN_DEFAULT_MINUTES = 120;
15
+ export declare const RUN_MINUTES_CEILING = 180;
16
+ /**
17
+ * @implements A-SPEC-128.8 — the one builder of what follows a stopped full run: the call with a doubled budget (up to the
18
+ * ceiling), keeping the worker count, or at the ceiling the sentence that says so. The test_run answer's `nextCall` and the
19
+ * push gate's stopped-attempt refusal both read it, so the two cannot drift (A L1, B M1).
20
+ */
21
+ export declare function nextFullCall(timeoutMinutes: number, workers?: number | null): string;
@@ -0,0 +1,33 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.RUN_MINUTES_CEILING = exports.FULL_RUN_DEFAULT_MINUTES = exports.FULL_RUN_CALL = exports.FULL_MODE = void 0;
4
+ exports.modeAnchor = modeAnchor;
5
+ exports.nextFullCall = nextFullCall;
6
+ // @implements A-SPEC-128.4, A-SPEC-128.5, A-SPEC-128.8, A-SPEC-128.9
7
+ /**
8
+ * The one place the full-run tokens live (A-SPEC-128.4 §5): the mode a full run records, the provenance input that says
9
+ * a baseline was verified by such a run, and the call a refusal names. The write side, the predicate, the trust check, the
10
+ * push gate and the merge-ready package all read these, so the spelling cannot drift between them.
11
+ */
12
+ exports.FULL_MODE = 'full';
13
+ /** The provenance input a baseline anchor carries for the mode of the run that verified it. */
14
+ function modeAnchor(mode) {
15
+ return `mode:${mode}`;
16
+ }
17
+ /** @implements A-SPEC-128.4 — the one call that clears a refusal: the refusal names it, and running it reaches allow. */
18
+ exports.FULL_RUN_CALL = 'test_run({root, full: true})';
19
+ /** @implements A-SPEC-128.5 — the default budget of a full run, and the ceiling a next call may ask for. */
20
+ exports.FULL_RUN_DEFAULT_MINUTES = 120;
21
+ exports.RUN_MINUTES_CEILING = 180;
22
+ /**
23
+ * @implements A-SPEC-128.8 — the one builder of what follows a stopped full run: the call with a doubled budget (up to the
24
+ * ceiling), keeping the worker count, or at the ceiling the sentence that says so. The test_run answer's `nextCall` and the
25
+ * push gate's stopped-attempt refusal both read it, so the two cannot drift (A L1, B M1).
26
+ */
27
+ function nextFullCall(timeoutMinutes, workers) {
28
+ if (timeoutMinutes >= exports.RUN_MINUTES_CEILING) {
29
+ // @implements A-SPEC-128.9 — E4: no exclusion is suggested (following one hid a red suite); split it or ask the owner
30
+ return `budget ceiling reached (${exports.RUN_MINUTES_CEILING} minutes) — the suite does not finish within it; split the suite or ask the owner how this repository is verified`;
31
+ }
32
+ return `test_run({root, full: true, timeoutMinutes: ${Math.min(exports.RUN_MINUTES_CEILING, timeoutMinutes * 2)}${typeof workers === 'number' ? `, workers: ${workers}` : ''}})`;
33
+ }
@@ -0,0 +1,55 @@
1
+ /** L1: `<pid>-<base36 time>-<base36 random>`; the pid is the owner, so ownership needs no record that can be forged. */
2
+ export declare const ID_RE: RegExp;
3
+ export interface HeadWorktree {
4
+ /** The worktree's absolute path: the run's root. */
5
+ dir: string;
6
+ createMs: number;
7
+ prepareMs: number;
8
+ /** Removes the worktree through git, by its exact path; null, or the reason git could not (A-SPEC-128.15 L5); never throws. */
9
+ close(): string | null;
10
+ }
11
+ export type OpenedWorktree = {
12
+ ok: true;
13
+ wt: HeadWorktree;
14
+ } | {
15
+ ok: false;
16
+ reason: string;
17
+ };
18
+ export interface WorktreeOptions {
19
+ /** ax.config.json testRun.prepare as read from HEAD (the worktree) — never guessed. */
20
+ prepareOf: (dir: string) => string[] | undefined;
21
+ /** Runs one prepare child within `budgetMs`; throws like execFileSync on a non-zero exit or the bound. */
22
+ run: (cmd: string, args: string[], cwd: string, budgetMs: number) => string;
23
+ /** L4: the run's own budget in milliseconds (the handler owns the budget), which bounds the prepare too. */
24
+ prepareBudgetMs: number;
25
+ /** A-SPEC-128.16 W1: ax.config.json testRun.linkWalk as read from HEAD (the worktree); the default when absent. */
26
+ walkBoundOf?: (dir: string) => {
27
+ entries: number;
28
+ seconds: number;
29
+ } | undefined;
30
+ }
31
+ /** L1: the per-user base and this repository's key directory (sha256 of git's common directory); null without git. */
32
+ export declare function runKeyDir(root: string, tmpdir?: string): string | null;
33
+ /**
34
+ * E1, A-SPEC-128.15 O2: every symbolic link at any depth of a linked node_modules (links are resolved, never followed).
35
+ * The first that lands inside the work tree outside every node_modules is a reason naming it; a walk past its bound is a
36
+ * reason too; otherwise null.
37
+ */
38
+ export declare const LINK_WALK: {
39
+ entries: number;
40
+ seconds: number;
41
+ };
42
+ export declare function workTreeLink(rootReal: string, nmReal: string, label: string, bound?: {
43
+ entries: number;
44
+ seconds: number;
45
+ }): string | null;
46
+ /**
47
+ * L4: a package-manager install would write the work tree's node_modules through the link. A heuristic (A-SPEC-128.15
48
+ * L6): flag values are skipped, npx and corepack are read through, and a shell's command string is split into commands.
49
+ */
50
+ export declare function installPrepare(argv: string[]): boolean;
51
+ /**
52
+ * W1, L1–L4: a detached worktree of `head` under this repository's key directory, prepared (node_modules linked,
53
+ * testRun.prepare run) and ready to run; or the reason it could not be made.
54
+ */
55
+ export declare function openHeadWorktree(root: string, head: string, opts: WorktreeOptions): OpenedWorktree;