@holmes-lab/holmes-kit 0.35.24 → 0.36.0

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 (136) hide show
  1. package/CHANGELOG.md +363 -0
  2. package/README.md +4 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +4 -1
  5. package/dist/holmes/cli/approve-watch.js +3 -1
  6. package/dist/holmes/cli/approve.d.ts +10 -0
  7. package/dist/holmes/cli/approve.js +34 -4
  8. package/dist/holmes/cli/claude-switches.d.ts +7 -1
  9. package/dist/holmes/cli/claude-switches.js +11 -7
  10. package/dist/holmes/cli/codex-toml.d.ts +3 -0
  11. package/dist/holmes/cli/codex-toml.js +2 -1
  12. package/dist/holmes/cli/doctor.d.ts +31 -1
  13. package/dist/holmes/cli/doctor.js +204 -7
  14. package/dist/holmes/cli/index.js +115 -4
  15. package/dist/holmes/cli/init.js +4 -3
  16. package/dist/holmes/cli/os-notify.d.ts +3 -1
  17. package/dist/holmes/cli/os-notify.js +10 -4
  18. package/dist/holmes/cli/review.d.ts +25 -0
  19. package/dist/holmes/cli/review.js +111 -0
  20. package/dist/holmes/cli/roles-readme.d.ts +11 -0
  21. package/dist/holmes/cli/roles-readme.js +38 -16
  22. package/dist/holmes/cli/roles.d.ts +12 -0
  23. package/dist/holmes/cli/roles.js +86 -0
  24. package/dist/holmes/cli/run.d.ts +65 -0
  25. package/dist/holmes/cli/run.js +308 -0
  26. package/dist/holmes/cli/runtime-binding-approval.js +3 -2
  27. package/dist/holmes/cli/runtime-binding.d.ts +30 -0
  28. package/dist/holmes/cli/runtime-binding.js +116 -11
  29. package/dist/holmes/cli/scratch.d.ts +12 -0
  30. package/dist/holmes/cli/scratch.js +20 -0
  31. package/dist/holmes/cli/test-platform.d.ts +16 -0
  32. package/dist/holmes/cli/test-platform.js +31 -1
  33. package/dist/holmes/config/config.d.ts +49 -0
  34. package/dist/holmes/config/config.js +146 -3
  35. package/dist/holmes/config/project-caps.d.ts +21 -0
  36. package/dist/holmes/config/project-caps.js +114 -0
  37. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  38. package/dist/holmes/governance/approval-queue.js +51 -8
  39. package/dist/holmes/governance/autonomy.d.ts +6 -0
  40. package/dist/holmes/governance/autonomy.js +21 -0
  41. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  42. package/dist/holmes/governance/push-gate-runner.js +49 -1
  43. package/dist/holmes/governance/replica-id.d.ts +9 -0
  44. package/dist/holmes/governance/replica-id.js +44 -7
  45. package/dist/holmes/governance/role-policy.d.ts +41 -1
  46. package/dist/holmes/governance/role-policy.js +137 -20
  47. package/dist/holmes/governance/run-mode.d.ts +14 -0
  48. package/dist/holmes/governance/run-mode.js +120 -0
  49. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  50. package/dist/holmes/governance/tool-actions.js +121 -0
  51. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  52. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  53. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  54. package/dist/holmes/guardrail/classification-mode.js +135 -0
  55. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  56. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  57. package/dist/holmes/guardrail/impact-gate.d.ts +2 -0
  58. package/dist/holmes/guardrail/impact-gate.js +34 -11
  59. package/dist/holmes/guardrail/phase.d.ts +2 -1
  60. package/dist/holmes/guardrail/phase.js +22 -8
  61. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  62. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  63. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  64. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  65. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  66. package/dist/holmes/guardrail/risk-classifier.js +255 -27
  67. package/dist/holmes/guardrail/risk-types.d.ts +16 -0
  68. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  69. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  70. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  71. package/dist/holmes/guardrail/run-refusals.js +348 -0
  72. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  73. package/dist/holmes/guardrail/run-stages.js +188 -0
  74. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  75. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  76. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  77. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  78. package/dist/holmes/guardrail/shell-words.js +7 -7
  79. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  80. package/dist/holmes/guardrail/write-target.js +118 -16
  81. package/dist/holmes/hooks/pre-tool-use.d.ts +36 -2
  82. package/dist/holmes/hooks/pre-tool-use.js +740 -81
  83. package/dist/holmes/hooks/session-start.js +5 -3
  84. package/dist/holmes/hooks/stop.d.ts +35 -1
  85. package/dist/holmes/hooks/stop.js +142 -7
  86. package/dist/holmes/mcp/elicit-approval.js +4 -4
  87. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  89. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  90. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  91. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  92. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  93. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  94. package/dist/holmes/mcp/handlers/spec-approval.js +56 -9
  95. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  96. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  97. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  98. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  99. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  100. package/dist/holmes/mcp/handlers.d.ts +2 -3
  101. package/dist/holmes/mcp/handlers.js +22 -2
  102. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  103. package/dist/holmes/mcp/harness-attestation.js +3 -1
  104. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  105. package/dist/holmes/mcp/operator-recovery.js +4 -3
  106. package/dist/holmes/mcp/server.js +9 -0
  107. package/dist/holmes/mcp/tool-schemas.js +6 -3
  108. package/dist/holmes/project/npx-bin.d.ts +26 -0
  109. package/dist/holmes/project/npx-bin.js +272 -2
  110. package/dist/holmes/project/root.js +6 -1
  111. package/dist/holmes/project/run-records.d.ts +17 -0
  112. package/dist/holmes/project/run-records.js +126 -0
  113. package/dist/holmes/project/scratch-root.d.ts +12 -0
  114. package/dist/holmes/project/scratch-root.js +132 -0
  115. package/dist/holmes/review/mrp.d.ts +35 -0
  116. package/dist/holmes/review/mrp.js +119 -0
  117. package/dist/holmes/review/verdicts.d.ts +117 -0
  118. package/dist/holmes/review/verdicts.js +345 -0
  119. package/dist/holmes/runtime/dispatch.js +6 -3
  120. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  121. package/dist/holmes/semantic/cloud-usage.js +106 -0
  122. package/dist/holmes/semantic/embedder.d.ts +15 -6
  123. package/dist/holmes/semantic/embedder.js +84 -3
  124. package/dist/holmes/semantic/local-model.d.ts +21 -2
  125. package/dist/holmes/semantic/local-model.js +14 -3
  126. package/dist/holmes/semantic/tier.d.ts +25 -0
  127. package/dist/holmes/semantic/tier.js +86 -1
  128. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  129. package/dist/holmes/semantic/vector-cache.js +4 -1
  130. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  131. package/dist/holmes/spec/approval-blockers.js +70 -2
  132. package/dist/holmes/spec/renumber.d.ts +1 -1
  133. package/dist/holmes/spec/renumber.js +5 -2
  134. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  135. package/dist/holmes/spec/transition-policy.js +17 -2
  136. package/package.json +1 -1
@@ -0,0 +1,119 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.buildMrp = buildMrp;
37
+ // @implements A-SPEC-102.6, A-SPEC-102.7
38
+ /**
39
+ * @implements A-SPEC-102.6 — the merge-ready package: one artefact a person reads before approving a merge. It names
40
+ * the spec chain behind the changed files, the test evidence for the head, the review verdict, and — explicitly —
41
+ * what is missing. Coverage and mutation are not measured per range yet; they say so instead of guessing.
42
+ */
43
+ const fs = __importStar(require("node:fs"));
44
+ const path = __importStar(require("node:path"));
45
+ const spec_parser_1 = require("../spec/spec-parser");
46
+ const test_evidence_1 = require("./test-evidence");
47
+ const verdicts_1 = require("./verdicts");
48
+ function loadSpecs(dir, out = new Map(), depth = 0) {
49
+ if (depth > 6)
50
+ return out;
51
+ let entries;
52
+ try {
53
+ entries = fs.readdirSync(dir, { withFileTypes: true });
54
+ }
55
+ catch {
56
+ return out;
57
+ }
58
+ for (const e of entries) {
59
+ const p = path.join(dir, e.name);
60
+ if (e.isDirectory())
61
+ loadSpecs(p, out, depth + 1);
62
+ else if (e.isFile() && e.name.endsWith('.md')) {
63
+ try {
64
+ const s = (0, spec_parser_1.parseSpec)(fs.readFileSync(p, 'utf8'));
65
+ if (s.id)
66
+ out.set(s.id, s);
67
+ }
68
+ catch { /* an unreadable spec is simply absent */ }
69
+ }
70
+ }
71
+ return out;
72
+ }
73
+ function buildMrp(root, base, head) {
74
+ const range = (0, verdicts_1.resolveRange)(root, base, head);
75
+ if ('error' in range)
76
+ return range;
77
+ const touched = (0, verdicts_1.rangeAnchors)(root, range.base, range.head);
78
+ if ('error' in touched)
79
+ return touched;
80
+ const files = touched.files;
81
+ const specs = loadSpecs(path.join(root, '.ax', 'specs'));
82
+ const aspecs = new Set(touched.aspecs);
83
+ const link = (id) => (id ? { id, status: specs.get(id)?.status ?? 'missing' } : null);
84
+ const chain = [...aspecs].sort().map((id) => {
85
+ const a = specs.get(id);
86
+ const tspec = [...specs.values()].find((s) => s.type === 'T-SPEC' && (s.dependsOn ?? []).includes(id));
87
+ const hId = a?.dependsOn?.find((d) => d.startsWith('H-SPEC-'));
88
+ const reqId = hId ? specs.get(hId)?.dependsOn?.find((d) => d.startsWith('REQ-')) : undefined;
89
+ return { aspec: id, status: a?.status ?? 'missing', tspec: tspec ? { id: tspec.id, status: tspec.status } : null, hspec: link(hId), req: link(reqId) };
90
+ });
91
+ const ev = (0, test_evidence_1.readTestEvidence)(root);
92
+ const evidence = ev
93
+ ? { head: ev.head, fresh: ev.head === range.head, passed: ev.passed,
94
+ executed: [...aspecs].reduce((n, id) => n + (ev.executedByAspec[id] ?? 0), 0) }
95
+ : { fresh: false };
96
+ const review = (0, verdicts_1.gateRange)(root, range.base, range.head, {});
97
+ const missing = [];
98
+ for (const c of chain) {
99
+ if (c.status !== 'approved')
100
+ missing.push(`${c.aspec} is ${c.status}`);
101
+ if (!c.tspec)
102
+ missing.push(`${c.aspec} has no T-SPEC`);
103
+ else if (c.tspec.status !== 'approved')
104
+ missing.push(`${c.tspec.id} is ${c.tspec.status}`);
105
+ if (!c.hspec)
106
+ missing.push(`${c.aspec} has no H-SPEC parent`);
107
+ else if (c.hspec.status !== 'approved')
108
+ missing.push(`${c.hspec.id} is ${c.hspec.status}`);
109
+ if (!c.req)
110
+ missing.push(`${c.aspec} has no REQ ancestor`);
111
+ else if (c.req.status !== 'approved')
112
+ missing.push(`${c.req.id} is ${c.req.status}`);
113
+ }
114
+ if (!evidence.fresh || evidence.passed !== true)
115
+ missing.push(`test evidence is not fresh or not green for ${range.head}`);
116
+ missing.push(...review.reasons);
117
+ const unique = [...new Set(missing)];
118
+ return { base: range.base, head: range.head, files, chain, evidence, review, coverage: 'unmeasured', mutation: 'unmeasured', ready: unique.length === 0, missing: unique };
119
+ }
@@ -0,0 +1,117 @@
1
+ import { type ProcLookup } from '../mcp/harness-attestation';
2
+ /** @implements A-SPEC-102.7 — the S·O·L·I·D checklist: each item compliant, violation or n-a, with its evidence. */
3
+ export type SolidItem = 'S' | 'O' | 'L' | 'I' | 'D';
4
+ export type SolidChecklist = Record<SolidItem, {
5
+ status: 'compliant' | 'violation' | 'n-a';
6
+ evidence: string;
7
+ }>;
8
+ /** @implements A-SPEC-102.7 — the specs the commits name against the anchors the diff carries. */
9
+ export interface SpecAnchors {
10
+ stated: string[];
11
+ anchored: string[];
12
+ statedOnly: string[];
13
+ anchoredOnly: string[];
14
+ }
15
+ export interface VerdictRecord {
16
+ ts: string;
17
+ base: string;
18
+ head: string;
19
+ verdict: 'pass' | 'fail';
20
+ findings: string[];
21
+ /** `harness`: a marker variable, or `process:<name>` for an ancestor (A-SPEC-102.8); `ancestry`: why the process table could not be read. */
22
+ reviewer: {
23
+ run?: string;
24
+ session?: string;
25
+ engine?: string;
26
+ model?: string;
27
+ person: boolean;
28
+ harness?: string;
29
+ ancestry?: string;
30
+ };
31
+ authors: string[];
32
+ independent: boolean;
33
+ /** @implements A-SPEC-102.7 — null when the reviewer gave none. Records written before 102.7 lack both fields. */
34
+ solid?: SolidChecklist | null;
35
+ specAnchors?: SpecAnchors;
36
+ }
37
+ export interface VerdictInput {
38
+ base: string;
39
+ head: string;
40
+ verdict: 'pass' | 'fail';
41
+ findings?: string[];
42
+ engine?: string;
43
+ model?: string;
44
+ session?: string;
45
+ solid?: SolidChecklist;
46
+ }
47
+ export declare function agentHarnessMarker(env: NodeJS.ProcessEnv): string | null;
48
+ /**
49
+ * @implements A-SPEC-102.8 — whether an agent harness is among the ancestors of `pid`. Variables are what the agent
50
+ * controls (`env -u CLAUDECODE …`); the process tree above the CLI is not. A name match is enough here: a false match
51
+ * only withholds independence (the image check of A-SPEC-732 guards the opposite direction).
52
+ */
53
+ export type HarnessAncestry = {
54
+ kind: 'none';
55
+ } | {
56
+ kind: 'harness';
57
+ harness: string;
58
+ chain: string[];
59
+ } | {
60
+ kind: 'unreadable';
61
+ reason: string;
62
+ };
63
+ export declare function harnessAncestor(pid: number, lookup: ProcLookup, maxDepth?: number): HarnessAncestry;
64
+ /**
65
+ * @implements A-SPEC-102.7 — the files a resolved range changes and the A-SPEC anchors that speak for it: each changed
66
+ * file's line-1 claim and the claims on the lines the range adds. A file's every inline anchor would make one hub file
67
+ * (measured: 100+ anchors in the hook) name half the store. Shared with the MRP, which imports it from here.
68
+ */
69
+ export declare function rangeAnchors(root: string, base: string, head: string): {
70
+ files: string[];
71
+ aspecs: string[];
72
+ } | {
73
+ error: string;
74
+ };
75
+ /** `ancestry` defaults to walking this process's parents in the live process table (A-SPEC-102.8). */
76
+ export interface VerdictContext {
77
+ env: NodeJS.ProcessEnv;
78
+ cwd?: string;
79
+ interactive: boolean;
80
+ now?: () => Date;
81
+ ancestry?: () => HarnessAncestry;
82
+ }
83
+ export declare const verdictsFile: (main: string) => string;
84
+ /** Both revisions as full commit ids, or the one that does not resolve. */
85
+ export declare function resolveRange(root: string, base: string, head: string): {
86
+ base: string;
87
+ head: string;
88
+ } | {
89
+ error: string;
90
+ };
91
+ /** The runs whose worktree holds `headSha` as its HEAD: the head's authors. */
92
+ export declare function authorRuns(main: string, headSha: string): string[];
93
+ export declare function readVerdicts(main: string): VerdictRecord[];
94
+ export declare function recordVerdict(root: string, input: VerdictInput, ctx: VerdictContext): {
95
+ ok: true;
96
+ record: VerdictRecord;
97
+ } | {
98
+ ok: false;
99
+ reason: string;
100
+ };
101
+ export declare function gateRange(root: string, base: string, head: string, opts: {
102
+ strict?: boolean;
103
+ }): {
104
+ ok: boolean;
105
+ reasons: string[];
106
+ };
107
+ export declare function rangeStatus(root: string, base: string, head: string): {
108
+ base: string;
109
+ head: string;
110
+ verdicts: VerdictRecord[];
111
+ open: {
112
+ critical: number;
113
+ important: number;
114
+ };
115
+ } | {
116
+ error: string;
117
+ };
@@ -0,0 +1,345 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.verdictsFile = void 0;
37
+ exports.agentHarnessMarker = agentHarnessMarker;
38
+ exports.harnessAncestor = harnessAncestor;
39
+ exports.rangeAnchors = rangeAnchors;
40
+ exports.resolveRange = resolveRange;
41
+ exports.authorRuns = authorRuns;
42
+ exports.readVerdicts = readVerdicts;
43
+ exports.recordVerdict = recordVerdict;
44
+ exports.gateRange = gateRange;
45
+ exports.rangeStatus = rangeStatus;
46
+ // @implements A-SPEC-102.2, A-SPEC-102.7, A-SPEC-102.8
47
+ /**
48
+ * @implements A-SPEC-102.2 — a review is a verdict that names who reviewed which commits. The ledger lives in the main
49
+ * checkout (`.ax/reviews/verdicts.jsonl`, append-only), so a review recorded in a worktree outlives the worktree. A
50
+ * run never reviews its own head, and only an independent pass for exactly the range, with no open critical finding,
51
+ * passes the gate.
52
+ */
53
+ const node_child_process_1 = require("node:child_process");
54
+ const fs = __importStar(require("node:fs"));
55
+ const path = __importStar(require("node:path"));
56
+ const anchors_1 = require("../guardrail/anchors");
57
+ const identity_1 = require("../governance/identity");
58
+ const role_policy_1 = require("../governance/role-policy");
59
+ const run_mode_1 = require("../governance/run-mode");
60
+ const bounded_io_1 = require("../project/bounded-io");
61
+ const run_records_1 = require("../project/run-records");
62
+ const harness_attestation_1 = require("../mcp/harness-attestation");
63
+ const SOLID_ITEMS = ['S', 'O', 'L', 'I', 'D'];
64
+ /**
65
+ * @implements A-SPEC-102.7 — the environment marker of an agent tool call: Claude Code and Codex set these in the
66
+ * processes their tools start. No agy marker is known; a tool call there has no terminal, which the TTY check catches.
67
+ */
68
+ const HARNESS_MARKERS = ['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT', 'CODEX_SANDBOX', 'CODEX_SANDBOX_NETWORK_DISABLED'];
69
+ function agentHarnessMarker(env) {
70
+ const set = (k) => typeof env[k] === 'string' && env[k] !== '';
71
+ // @implements A-SPEC-102.8 — agy: any ANTIGRAVITY_* variable (which one its shell tool sets was not measured).
72
+ return HARNESS_MARKERS.find(set) ?? Object.keys(env).filter((k) => k.startsWith('ANTIGRAVITY_') && set(k)).sort()[0] ?? null;
73
+ }
74
+ function harnessAncestor(pid, lookup, maxDepth = 64) {
75
+ const chain = [];
76
+ const seen = new Set();
77
+ let cur = pid;
78
+ for (let depth = 0; depth < maxDepth; depth++) {
79
+ if (cur <= 1 || seen.has(cur))
80
+ return { kind: 'none' };
81
+ seen.add(cur);
82
+ const row = lookup(cur);
83
+ if (row === null)
84
+ return { kind: 'unreadable', reason: `process ${cur} could not be read` };
85
+ const harness = (0, harness_attestation_1.harnessOf)(row.args, row.exe);
86
+ chain.push(harness ?? row.args.split(/\s+/)[0] ?? '?');
87
+ if (harness !== null)
88
+ return { kind: 'harness', harness, chain };
89
+ if (row.ppid === cur)
90
+ return { kind: 'none' };
91
+ cur = row.ppid;
92
+ }
93
+ return { kind: 'none' };
94
+ }
95
+ /** A complete checklist, or the reason it is not one. */
96
+ function solidIssue(solid, verdict) {
97
+ if (solid === null || typeof solid !== 'object')
98
+ return 'the SOLID checklist is not an object of S, O, L, I and D';
99
+ for (const k of SOLID_ITEMS) {
100
+ const item = solid[k];
101
+ if (!item || !['compliant', 'violation', 'n-a'].includes(String(item.status)))
102
+ return `SOLID item ${k} needs a status of compliant, violation or n-a`;
103
+ if (typeof item.evidence !== 'string' || item.evidence.trim() === '')
104
+ return `SOLID item ${k} needs its evidence`;
105
+ if (verdict === 'pass' && item.status === 'violation')
106
+ return `SOLID item ${k} is a violation — a violation is a finding, so the verdict cannot be pass`;
107
+ }
108
+ return null;
109
+ }
110
+ /**
111
+ * @implements A-SPEC-102.7 — the files a resolved range changes and the A-SPEC anchors that speak for it: each changed
112
+ * file's line-1 claim and the claims on the lines the range adds. A file's every inline anchor would make one hub file
113
+ * (measured: 100+ anchors in the hook) name half the store. Shared with the MRP, which imports it from here.
114
+ */
115
+ function rangeAnchors(root, base, head) {
116
+ const git = (args) => (0, node_child_process_1.execFileSync)('git', args, { cwd: root, encoding: 'utf8', env: gitEnv(), stdio: ['ignore', 'pipe', 'ignore'], timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER });
117
+ let files;
118
+ try {
119
+ files = git(['diff', '--name-only', base, head]).split('\n').filter(Boolean);
120
+ }
121
+ catch {
122
+ return { error: 'git diff failed for the range' };
123
+ }
124
+ const aspecs = new Set();
125
+ const real = (id) => /^A-SPEC-\d{3}(?:\.\d+)*$/.test(id);
126
+ for (const f of files) {
127
+ let content = '';
128
+ try {
129
+ content = git(['show', `${head}:${f}`]);
130
+ }
131
+ catch {
132
+ continue;
133
+ } // deleted at head
134
+ for (const id of (0, anchors_1.claimedAnchors)(content.split('\n')[0] ?? ''))
135
+ if (real(id))
136
+ aspecs.add(id);
137
+ let diff = '';
138
+ try {
139
+ diff = git(['diff', '-U0', base, head, '--', f]);
140
+ }
141
+ catch {
142
+ diff = '';
143
+ }
144
+ const added = diff.split('\n').filter((l) => l.startsWith('+') && !l.startsWith('+++')).map((l) => l.slice(1)).join('\n');
145
+ for (const id of (0, anchors_1.claimedAnchors)(added))
146
+ if (real(id))
147
+ aspecs.add(id);
148
+ }
149
+ return { files, aspecs: [...aspecs].sort() };
150
+ }
151
+ /** The A-SPEC ids named in the commit messages of base..head. */
152
+ function statedSpecs(root, base, head) {
153
+ try {
154
+ const log = (0, node_child_process_1.execFileSync)('git', ['log', '--format=%B', `${base}..${head}`], { cwd: root, encoding: 'utf8', env: gitEnv(), stdio: ['ignore', 'pipe', 'ignore'], timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER });
155
+ return [...new Set(log.match(/A-SPEC-\d{3}(?:\.\d+)*/g) ?? [])].sort();
156
+ }
157
+ catch {
158
+ return [];
159
+ }
160
+ }
161
+ const verdictsFile = (main) => path.join(main, '.ax', 'reviews', 'verdicts.jsonl');
162
+ exports.verdictsFile = verdictsFile;
163
+ const gitEnv = () => {
164
+ const env = { ...process.env };
165
+ for (const k of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR'])
166
+ delete env[k];
167
+ return env;
168
+ };
169
+ function revParse(cwd, rev) {
170
+ try {
171
+ return (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--verify', '--quiet', `${rev}^{commit}`], { cwd, encoding: 'utf8', env: gitEnv(), stdio: ['ignore', 'pipe', 'ignore'], timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER }).trim() || null;
172
+ }
173
+ catch {
174
+ return null;
175
+ }
176
+ }
177
+ /** Both revisions as full commit ids, or the one that does not resolve. */
178
+ function resolveRange(root, base, head) {
179
+ const b = revParse(root, base);
180
+ if (!b)
181
+ return { error: `base ${base} does not resolve to a commit in ${root}` };
182
+ const h = revParse(root, head);
183
+ if (!h)
184
+ return { error: `head ${head} does not resolve to a commit in ${root}` };
185
+ return { base: b, head: h };
186
+ }
187
+ /** The runs whose worktree holds `headSha` as its HEAD: the head's authors. */
188
+ function authorRuns(main, headSha) {
189
+ return (0, run_records_1.listRuns)(main).filter((r) => revParse(r.worktree, 'HEAD') === headSha).map((r) => r.run_id);
190
+ }
191
+ function readVerdicts(main) {
192
+ let text;
193
+ try {
194
+ text = fs.readFileSync((0, exports.verdictsFile)(main), 'utf8');
195
+ }
196
+ catch (e) {
197
+ if (e.code === 'ENOENT')
198
+ return [];
199
+ throw e;
200
+ }
201
+ const out = [];
202
+ for (const line of text.split('\n')) {
203
+ if (line.trim() === '')
204
+ continue;
205
+ try {
206
+ const v = JSON.parse(line);
207
+ if (v && typeof v.base === 'string' && typeof v.head === 'string' && (v.verdict === 'pass' || v.verdict === 'fail'))
208
+ out.push(v);
209
+ }
210
+ catch { /* a torn line is skipped */ }
211
+ }
212
+ return out;
213
+ }
214
+ function recordVerdict(root, input, ctx) {
215
+ const range = resolveRange(root, input.base, input.head);
216
+ if ('error' in range)
217
+ return { ok: false, reason: range.error };
218
+ const mode = (0, run_mode_1.runMode)(ctx.env, root, ctx.cwd);
219
+ const roleIssue = (0, role_policy_1.roleCheck)('RECORD_REVIEW', new identity_1.EnvIdentityProvider(ctx.env).current(), (0, role_policy_1.loadRolePolicy)(root), { run: mode.run });
220
+ if (roleIssue)
221
+ return { ok: false, reason: roleIssue };
222
+ const main = (0, run_records_1.mainCheckoutOf)(root);
223
+ const authors = authorRuns(main, range.head);
224
+ const run = mode.run ? mode.id : undefined;
225
+ if (run && authors.includes(run))
226
+ return { ok: false, reason: `self-review: run ${run} wrote ${range.head}; a review is recorded by another run or a person` };
227
+ // @implements A-SPEC-102.7 — a checklist, when given, is complete and agrees with the verdict.
228
+ if (input.solid !== undefined) {
229
+ const issue = solidIssue(input.solid, input.verdict);
230
+ if (issue)
231
+ return { ok: false, reason: issue };
232
+ }
233
+ // @implements A-SPEC-102.7 — a person is a terminal outside an agent harness: an agent session's own review is not one.
234
+ const marker = agentHarnessMarker(ctx.env);
235
+ // @implements A-SPEC-102.8 — the walk runs only when the cheaper conditions already hold.
236
+ const ancestry = !mode.run && ctx.interactive && marker === null
237
+ ? (ctx.ancestry ?? (() => harnessAncestor(process.ppid, (0, harness_attestation_1.systemProcLookup)())))()
238
+ : { kind: 'none' };
239
+ const harness = marker ?? (ancestry.kind === 'harness' ? `process:${ancestry.harness}` : null);
240
+ const person = !mode.run && ctx.interactive && harness === null && ancestry.kind === 'none';
241
+ const touched = rangeAnchors(root, range.base, range.head);
242
+ const anchored = 'error' in touched ? [] : touched.aspecs;
243
+ const stated = statedSpecs(root, range.base, range.head);
244
+ const specAnchors = {
245
+ stated, anchored, statedOnly: stated.filter((s) => !anchored.includes(s)), anchoredOnly: anchored.filter((a) => !stated.includes(a)),
246
+ };
247
+ const record = {
248
+ ts: (ctx.now ? ctx.now() : new Date()).toISOString(),
249
+ base: range.base, head: range.head, verdict: input.verdict, findings: [...(input.findings ?? [])],
250
+ reviewer: {
251
+ ...(run ? { run } : {}),
252
+ ...(input.session ? { session: input.session } : {}),
253
+ ...(input.engine ? { engine: input.engine } : {}),
254
+ ...(input.model ? { model: input.model } : {}),
255
+ person,
256
+ ...(harness ? { harness } : {}),
257
+ ...(ancestry.kind === 'unreadable' ? { ancestry: ancestry.reason } : {}),
258
+ },
259
+ authors,
260
+ independent: run !== undefined ? !authors.includes(run) : person,
261
+ solid: input.solid ?? null,
262
+ specAnchors,
263
+ };
264
+ const file = (0, exports.verdictsFile)(main);
265
+ fs.mkdirSync(path.dirname(file), { recursive: true });
266
+ fs.appendFileSync(file, `${JSON.stringify(record)}\n`);
267
+ return { ok: true, record };
268
+ }
269
+ /** Open findings, last line per id winning, from the main checkout's and the root's findings ledgers. */
270
+ function openFindings(root) {
271
+ const main = (0, run_records_1.mainCheckoutOf)(root);
272
+ const files = [...new Set([main, path.resolve(root)].map((d) => path.join(d, '.ax', 'ledger', 'findings.jsonl')))];
273
+ const last = new Map();
274
+ const unreadable = [];
275
+ for (const f of files) {
276
+ let text;
277
+ try {
278
+ text = fs.readFileSync(f, 'utf8');
279
+ }
280
+ catch (e) {
281
+ if (e.code !== 'ENOENT')
282
+ unreadable.push(f);
283
+ continue;
284
+ }
285
+ for (const line of text.split('\n')) {
286
+ if (line.trim() === '')
287
+ continue;
288
+ try {
289
+ const x = JSON.parse(line);
290
+ if (x && typeof x.id === 'string')
291
+ last.set(x.id, x);
292
+ }
293
+ catch { /* a torn line is skipped */ }
294
+ }
295
+ }
296
+ let critical = 0;
297
+ let important = 0;
298
+ for (const x of last.values()) {
299
+ if (x.status !== 'open')
300
+ continue;
301
+ if (x.severity === 'critical')
302
+ critical++;
303
+ else if (x.severity === 'important')
304
+ important++;
305
+ }
306
+ return { critical, important, unreadable };
307
+ }
308
+ function gateRange(root, base, head, opts) {
309
+ const range = resolveRange(root, base, head);
310
+ if ('error' in range)
311
+ return { ok: false, reasons: [range.error] };
312
+ const reasons = [];
313
+ let verdicts;
314
+ try {
315
+ verdicts = readVerdicts((0, run_records_1.mainCheckoutOf)(root));
316
+ }
317
+ catch {
318
+ return { ok: false, reasons: ['the verdict ledger cannot be read'] };
319
+ }
320
+ const covering = verdicts.filter((v) => v.independent && v.base === range.base && v.head === range.head);
321
+ const latest = covering[covering.length - 1];
322
+ if (!latest)
323
+ reasons.push(`no independent verdict covers ${range.base}..${range.head}`);
324
+ else if (latest.verdict !== 'pass')
325
+ reasons.push(`the latest independent verdict is fail (${latest.ts})`);
326
+ const open = openFindings(root);
327
+ for (const f of open.unreadable)
328
+ reasons.push(`the findings ledger ${f} cannot be read`);
329
+ if (open.critical > 0)
330
+ reasons.push(`${open.critical} open critical finding(s)`);
331
+ if (opts.strict && open.important > 0)
332
+ reasons.push(`${open.important} open important finding(s)`);
333
+ return { ok: reasons.length === 0, reasons };
334
+ }
335
+ function rangeStatus(root, base, head) {
336
+ const range = resolveRange(root, base, head);
337
+ if ('error' in range)
338
+ return range;
339
+ const open = openFindings(root);
340
+ return {
341
+ ...range,
342
+ verdicts: readVerdicts((0, run_records_1.mainCheckoutOf)(root)).filter((v) => v.base === range.base && v.head === range.head),
343
+ open: { critical: open.critical, important: open.important },
344
+ };
345
+ }
@@ -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, A-SPEC-769.10, A-SPEC-772.1
37
+ // @implements A-SPEC-751, A-SPEC-751.1, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751.7, A-SPEC-754, A-SPEC-769.10, A-SPEC-772.1
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");
@@ -99,7 +99,7 @@ async function runDispatch(opts) {
99
99
  const budget = (0, hook_process_1.boundedHookBudget)(opts.hookBudgetMs, hook_process_1.HOOK_BUDGET_MS);
100
100
  const input = await hookInput(budget);
101
101
  const hints = hintsFromInput(input);
102
- if (process.env.CLAUDE_PROJECT_DIR)
102
+ if (process.env.CLAUDE_PROJECT_DIR && opts.harness === 'claude')
103
103
  hints.push(process.env.CLAUDE_PROJECT_DIR);
104
104
  const selection = (0, binding_1.selectRuntime)((0, binding_1.readRuntimeRegistry)(opts.registryPath), { cwd: process.cwd(), workspaceHints: hints, specsHint: process.env.HOLMES_SPECS });
105
105
  const child = (0, node_child_process_1.spawn)(process.execPath, [path.join(selection.packageRoot, 'dist/holmes/hooks/session-start.js')], {
@@ -145,7 +145,10 @@ async function runDispatch(opts) {
145
145
  }
146
146
  }
147
147
  const hints = input ? hintsFromInput(input) : [];
148
- if (process.env.CLAUDE_PROJECT_DIR)
148
+ // @implements A-SPEC-751.7 — CLAUDE_PROJECT_DIR is Claude Code's variable. Every process Claude launches passes it
149
+ // on, so a Codex or Antigravity session under one of them inherits a value naming ANOTHER workspace (measured
150
+ // 2026-10-17: every Codex tool call denied as "Conflicting runtime workspace hints").
151
+ if (process.env.CLAUDE_PROJECT_DIR && opts.harness === 'claude')
149
152
  hints.push(process.env.CLAUDE_PROJECT_DIR);
150
153
  const selection = (0, binding_1.selectRuntime)((0, binding_1.readRuntimeRegistry)(opts.registryPath), { cwd: process.cwd(), workspaceHints: hints, specsHint: process.env.HOLMES_SPECS });
151
154
  phaseSelection = Math.round(performance.now() - started) - (phaseInput ?? 0);
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Cloud embedding egress, counted where it leaves: one JSON line per HTTP request the cloud embedder sends (retries
3
+ * included), per project, by local calendar day. Supervisor 2026-10-19 00:20 (b): the jarvis ledger counts only its
4
+ * Python processes, so holmes-kit's own requests were invisible. The record is advisory — it never fails an embedding,
5
+ * and it holds neither the key nor any text.
6
+ */
7
+ export declare const USAGE_RELPATH: string;
8
+ export interface UsageCount {
9
+ requests: number;
10
+ texts: number;
11
+ failed: number;
12
+ }
13
+ export interface CloudUsageSummary {
14
+ today: UsageCount;
15
+ last7: UsageCount;
16
+ }
17
+ export declare function recordCloudRequest(root: string, texts: number, outcome: string, now?: Date): void;
18
+ export declare function cloudUsageSummary(root: string, now?: Date): CloudUsageSummary;
19
+ /** The doctor row text. */
20
+ export declare function cloudUsageLine(s: CloudUsageSummary): string;