@holmes-lab/holmes-kit 0.29.0 → 0.31.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 (169) hide show
  1. package/CHANGELOG.md +556 -0
  2. package/README.md +15 -5
  3. package/bin/holmes-hook-antigravity.js +4 -0
  4. package/bin/holmes-kit.js +4 -0
  5. package/bin/holmes-pre-push.js +3 -0
  6. package/bin/holmes-stop-antigravity.js +4 -0
  7. package/dist/.build-id +1 -1
  8. package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
  9. package/dist/holmes/cli/agents-guidance-history.js +11 -2
  10. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  11. package/dist/holmes/cli/agents-guidance.js +11 -8
  12. package/dist/holmes/cli/agents.d.ts +41 -0
  13. package/dist/holmes/cli/agents.js +382 -2
  14. package/dist/holmes/cli/attest.d.ts +2 -0
  15. package/dist/holmes/cli/attest.js +66 -15
  16. package/dist/holmes/cli/ci-gate.js +16 -1
  17. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  18. package/dist/holmes/cli/claude-switches.js +967 -0
  19. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  20. package/dist/holmes/cli/codex-hooks.js +802 -0
  21. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  22. package/dist/holmes/cli/codex-oracle.js +1245 -0
  23. package/dist/holmes/cli/codex-toml.d.ts +58 -1
  24. package/dist/holmes/cli/codex-toml.js +456 -40
  25. package/dist/holmes/cli/doctor.d.ts +108 -8
  26. package/dist/holmes/cli/doctor.js +1408 -98
  27. package/dist/holmes/cli/index.js +23 -11
  28. package/dist/holmes/cli/init.d.ts +13 -0
  29. package/dist/holmes/cli/init.js +749 -77
  30. package/dist/holmes/cli/interactive-prompt.js +2 -2
  31. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  32. package/dist/holmes/cli/mcp-launcher.js +189 -6
  33. package/dist/holmes/cli/mcp-version.js +13 -2
  34. package/dist/holmes/cli/settings-merge.js +8 -2
  35. package/dist/holmes/cli/upgrade.d.ts +13 -0
  36. package/dist/holmes/cli/upgrade.js +116 -23
  37. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  38. package/dist/holmes/cli/workspace-scope.js +375 -0
  39. package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
  40. package/dist/holmes/cli/worktree-readiness.js +17 -3
  41. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  42. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  43. package/dist/holmes/cpg/cycle-detect.js +2 -1
  44. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  45. package/dist/holmes/cpg/required-calls.js +8 -1
  46. package/dist/holmes/governance/autonomy.d.ts +9 -0
  47. package/dist/holmes/governance/autonomy.js +28 -1
  48. package/dist/holmes/governance/constitution-debt.js +3 -2
  49. package/dist/holmes/governance/constitution.js +15 -3
  50. package/dist/holmes/governance/provenance-chain.js +3 -2
  51. package/dist/holmes/governance/push-gate-runner.js +4 -3
  52. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  53. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  54. package/dist/holmes/guardrail/linear-match.js +256 -0
  55. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  56. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  57. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  58. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  59. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  60. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  61. package/dist/holmes/guardrail/shell-words.js +1720 -0
  62. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  63. package/dist/holmes/guardrail/write-target.js +2379 -87
  64. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  65. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  66. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  67. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  68. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  69. package/dist/holmes/hooks/rtm-refresh-child.js +102 -18
  70. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  71. package/dist/holmes/hooks/rtm-refresh.js +60 -15
  72. package/dist/holmes/hooks/session-start.d.ts +10 -0
  73. package/dist/holmes/hooks/session-start.js +31 -7
  74. package/dist/holmes/hooks/stop.d.ts +2 -1
  75. package/dist/holmes/hooks/stop.js +197 -91
  76. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  77. package/dist/holmes/mcp/approval-adapters.js +21 -0
  78. package/dist/holmes/mcp/approval-commit.d.ts +20 -0
  79. package/dist/holmes/mcp/approval-commit.js +108 -0
  80. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  81. package/dist/holmes/mcp/approval-intent.js +67 -0
  82. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  83. package/dist/holmes/mcp/approval-policy.js +18 -0
  84. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  85. package/dist/holmes/mcp/elicit-approval.js +8 -3
  86. package/dist/holmes/mcp/handlers/graph-operations.d.ts +17 -1
  87. package/dist/holmes/mcp/handlers/graph-operations.js +15 -6
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  89. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  90. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  91. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  92. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +26 -0
  93. package/dist/holmes/mcp/handlers/requirement-triage.js +48 -11
  94. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  95. package/dist/holmes/mcp/handlers/review-evidence.js +15 -5
  96. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +18 -0
  97. package/dist/holmes/mcp/handlers/slice-orchestration.js +122 -16
  98. package/dist/holmes/mcp/handlers/spec-approval.d.ts +35 -2
  99. package/dist/holmes/mcp/handlers/spec-approval.js +175 -57
  100. package/dist/holmes/mcp/handlers/spec-authoring.js +36 -3
  101. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  102. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  103. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  104. package/dist/holmes/mcp/handlers.d.ts +126 -8
  105. package/dist/holmes/mcp/handlers.js +109 -18
  106. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  107. package/dist/holmes/mcp/harness-attestation.js +179 -0
  108. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  109. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  110. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +72 -2
  111. package/dist/holmes/mcp/requirement-triage-evidence.js +227 -1
  112. package/dist/holmes/mcp/server.js +24 -3
  113. package/dist/holmes/mcp/supervisor.js +7 -3
  114. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  115. package/dist/holmes/mcp/tool-schemas.js +54 -7
  116. package/dist/holmes/mcp/validate-args.js +12 -0
  117. package/dist/holmes/project/bounded-io.d.ts +102 -0
  118. package/dist/holmes/project/bounded-io.js +212 -0
  119. package/dist/holmes/project/change-source.js +3 -1
  120. package/dist/holmes/project/ci-runs.js +3 -2
  121. package/dist/holmes/project/ignore.d.ts +31 -2
  122. package/dist/holmes/project/ignore.js +409 -50
  123. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  124. package/dist/holmes/project/regular-file-guard.js +149 -0
  125. package/dist/holmes/project/root.js +12 -3
  126. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  127. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  128. package/dist/holmes/reverse/anchor.js +4 -3
  129. package/dist/holmes/reverse/scan.js +6 -2
  130. package/dist/holmes/review/commit-text.js +3 -2
  131. package/dist/holmes/review/condition-hunk-replay.d.ts +12 -0
  132. package/dist/holmes/review/condition-hunk-replay.js +13 -2
  133. package/dist/holmes/review/condition-hunk-resolution.js +59 -8
  134. package/dist/holmes/review/failed-test-names.js +13 -10
  135. package/dist/holmes/review/findings.js +3 -1
  136. package/dist/holmes/review/kills-check.js +6 -1
  137. package/dist/holmes/review/point-in-time-replay.js +5 -4
  138. package/dist/holmes/review/replay-corpus.js +5 -4
  139. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  140. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  141. package/dist/holmes/review/run-replay.js +3 -2
  142. package/dist/holmes/review/scope.js +6 -1
  143. package/dist/holmes/review/temporal-prior.js +3 -2
  144. package/dist/holmes/review/test-evidence.js +3 -2
  145. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  146. package/dist/holmes/review/test-outcomes.js +92 -2
  147. package/dist/holmes/review/test-runner.d.ts +6 -0
  148. package/dist/holmes/review/test-runner.js +36 -15
  149. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  150. package/dist/holmes/rtm/anchor-ids.js +42 -2
  151. package/dist/holmes/rtm/file-anchors.js +4 -1
  152. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  153. package/dist/holmes/rtm/git-changes.js +3 -1
  154. package/dist/holmes/rtm/graph-store.js +3 -2
  155. package/dist/holmes/rtm/test-scope.js +9 -4
  156. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  157. package/dist/holmes/spec/compat-impact.js +682 -11
  158. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  159. package/dist/holmes/spec/entity-integration.js +3 -2
  160. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  161. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  162. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  163. package/dist/holmes/spec/renumber.js +25 -10
  164. package/dist/holmes/spec/spec-parser.js +9 -3
  165. package/dist/holmes/spec/yaml-scalar.js +2 -2
  166. package/dist/holmes/update/refresh.js +3 -1
  167. package/dist/holmes/update/update-notice.d.ts +6 -0
  168. package/dist/holmes/update/update-notice.js +18 -1
  169. package/package.json +11 -4
@@ -1 +1,22 @@
1
- export {};
1
+ import { FreshnessLane, FreshnessReceipt } from '../refresh/freshness-coordinator';
2
+ /** The detached worker must publish its own failure; the parent is intentionally non-blocking. */
3
+ export declare function recordRefreshFailure(root: string, generation: string, head: string | null, now: Date): FreshnessReceipt | null;
4
+ export interface RefreshChildDeps {
5
+ head: (root: string) => string | null;
6
+ refreshGraph: (root: string) => Promise<unknown>;
7
+ refreshSource: (root: string) => Promise<{
8
+ lane: FreshnessLane;
9
+ }>;
10
+ refreshRequirement: (root: string) => Promise<{
11
+ status: string;
12
+ }>;
13
+ }
14
+ /**
15
+ * One refresh run for one lease generation. Every phase that writes is preceded by a lease check,
16
+ * so a superseded worker, or one whose root was removed, stops without writing (A-SPEC-724). Any
17
+ * failure — synchronous module load included — is published as bounded retry for this generation
18
+ * rather than left as a `refreshing` lease that only expiry can clear (A-SPEC-719).
19
+ */
20
+ export declare function runRefreshChild(root: string, generation: string, deps: RefreshChildDeps): Promise<void>;
21
+ /** The production phases: the scan/build machinery, loaded only inside the detached child. */
22
+ export declare function defaultRefreshChildDeps(env?: NodeJS.ProcessEnv): RefreshChildDeps;
@@ -33,6 +33,10 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.recordRefreshFailure = recordRefreshFailure;
37
+ exports.runRefreshChild = runRefreshChild;
38
+ exports.defaultRefreshChildDeps = defaultRefreshChildDeps;
39
+ // @implements A-SPEC-719, A-SPEC-734
36
40
  // @implements A-SPEC-566.4
37
41
  /**
38
42
  * The detached refresh child — the ONLY place this slice touches the scan/build machinery. Spawned
@@ -42,26 +46,106 @@ Object.defineProperty(exports, "__esModule", { value: true });
42
46
  */
43
47
  const fs = __importStar(require("node:fs"));
44
48
  const path = __importStar(require("node:path"));
45
- if (require.main === module) {
49
+ const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
50
+ const currentHead = (root) => {
51
+ try {
52
+ const { headOf } = require('../mcp/handlers/graph-operations');
53
+ return headOf(root);
54
+ }
55
+ catch {
56
+ return null;
57
+ }
58
+ };
59
+ /** The detached worker must publish its own failure; the parent is intentionally non-blocking. */
60
+ function recordRefreshFailure(root, generation, head, now) {
61
+ return (0, freshness_coordinator_1.completeRefresh)(root, generation, {
62
+ graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head,
63
+ }, now);
64
+ }
65
+ /**
66
+ * One refresh run for one lease generation. Every phase that writes is preceded by a lease check,
67
+ * so a superseded worker, or one whose root was removed, stops without writing (A-SPEC-724). Any
68
+ * failure — synchronous module load included — is published as bounded retry for this generation
69
+ * rather than left as a `refreshing` lease that only expiry can clear (A-SPEC-719).
70
+ */
71
+ async function runRefreshChild(root, generation, deps) {
72
+ if (!fs.existsSync(path.join(root, '.ax')))
73
+ return;
74
+ if (!(0, freshness_coordinator_1.ownsLease)(root, generation))
75
+ return; // spawned late behind a newer lease: not even the graph
46
76
  try {
47
- const root = process.argv[2];
48
- if (root && fs.existsSync(path.join(root, '.ax'))) {
77
+ await deps.refreshGraph(root);
78
+ // @implements A-SPEC-683 — the vectors ride the channel that already refreshes the graph.
79
+ // Measured 2026-09-19: without this, coverage reached 0 of 602 in twelve days while the graph
80
+ // stayed current.
81
+ if (!(0, freshness_coordinator_1.ownsLease)(root, generation))
82
+ return;
83
+ const source = await deps.refreshSource(root);
84
+ if (!(0, freshness_coordinator_1.ownsLease)(root, generation))
85
+ return;
86
+ let requirement;
87
+ try {
88
+ requirement = await deps.refreshRequirement(root);
89
+ }
90
+ catch {
91
+ requirement = { status: 'unavailable' };
92
+ }
93
+ (0, freshness_coordinator_1.completeRefresh)(root, generation, {
94
+ graph: 'current',
95
+ sourceSemantic: source.lane,
96
+ requirementSemantic: requirement.status === 'discharged' ? 'current'
97
+ : requirement.status === 'not-applicable' ? 'not-adopted'
98
+ : requirement.status === 'suppressed' ? 'suppressed' : 'failed',
99
+ head: deps.head(root),
100
+ }, new Date());
101
+ }
102
+ catch {
103
+ try {
104
+ recordRefreshFailure(root, generation, deps.head(root), new Date());
105
+ }
106
+ catch { /* fail-soft */ }
107
+ }
108
+ }
109
+ /** The production phases: the scan/build machinery, loaded only inside the detached child. */
110
+ function defaultRefreshChildDeps(env = process.env) {
111
+ // @implements A-SPEC-719 — the owner's transfer switch covers requirement documents too: the
112
+ // background child must not embed them when it is set, whatever tier is configured.
113
+ const suppressed = typeof env.HOLMES_NO_SEMANTIC_WARM === 'string' && env.HOLMES_NO_SEMANTIC_WARM !== '';
114
+ return {
115
+ head: currentHead,
116
+ refreshGraph: async (root) => {
49
117
  const { makeHandlers } = require('../mcp/handlers');
50
118
  const { LocalMarkdownRepository } = require('../spec/spec-store');
51
119
  const h = makeHandlers(new LocalMarkdownRepository(path.join(root, '.ax', 'specs')));
52
- void h.rtm_impact({ root, changed: [] }).then(() => {
53
- // @implements A-SPEC-683 — the vectors ride the channel that already refreshes the graph.
54
- // Detached, TTL-gated and fail-soft are properties this child already has; warming inherits
55
- // all three rather than needing a schedule of its own. Measured 2026-09-19: without this,
56
- // coverage reached 0 of 602 in twelve days while the graph stayed current.
57
- const { refreshSemanticVectors } = require('../mcp/handlers/graph-operations');
58
- const { CpgScanner } = require('../cpg/cpg-scanner');
59
- const { ScanFileCache } = require('../cpg/scan-cache');
60
- const crypto = require('node:crypto');
61
- const dir = path.join(require('node:os').tmpdir(), 'holmes-cpg-cache-' + crypto.createHash('sha256').update(root).digest('hex').slice(0, 16));
62
- return refreshSemanticVectors(root, process.env, undefined, () => new CpgScanner(undefined, new ScanFileCache(dir)).scan(root, root));
63
- }).catch(() => undefined);
64
- }
65
- }
66
- catch { /* fail-soft: a failed refresh leaves the old graph, which the advisory tolerates */ }
120
+ return h.rtm_impact({ root, changed: [] });
121
+ },
122
+ refreshSource: async (root) => {
123
+ const { refreshSemanticVectors } = require('../mcp/handlers/graph-operations');
124
+ const { CpgScanner } = require('../cpg/cpg-scanner');
125
+ const { ScanFileCache } = require('../cpg/scan-cache');
126
+ const crypto = require('node:crypto');
127
+ const dir = path.join(require('node:os').tmpdir(), 'holmes-cpg-cache-' + crypto.createHash('sha256').update(root).digest('hex').slice(0, 16));
128
+ return refreshSemanticVectors(root, env, undefined, () => new CpgScanner(undefined, new ScanFileCache(dir)).scan(root, root));
129
+ },
130
+ refreshRequirement: async (root) => {
131
+ if (suppressed)
132
+ return { status: 'suppressed' };
133
+ return warmRequirements(root);
134
+ },
135
+ };
136
+ }
137
+ async function warmRequirements(root) {
138
+ const { LocalMarkdownRepository } = require('../spec/spec-store');
139
+ const graphOps = require('../mcp/handlers/graph-operations');
140
+ const specs = await new LocalMarkdownRepository(path.join(root, '.ax', 'specs')).list();
141
+ return graphOps.warmRequirementSemanticCache(root, specs);
142
+ }
143
+ if (require.main === module) {
144
+ // @implements A-SPEC-734 (round 13) — this process never blocks on a file that is not a regular file.
145
+ require('../project/regular-file-guard').installProcessGuards();
146
+ const root = process.argv[2];
147
+ const generation = process.argv[3];
148
+ // fail-soft: a failed refresh leaves the old graph, which the advisory tolerates
149
+ if (root && generation)
150
+ void runRefreshChild(root, generation, defaultRefreshChildDeps()).catch(() => undefined);
67
151
  }
@@ -1,3 +1,4 @@
1
+ /** @deprecated A compatibility observation interval; receipt leases are the source of truth. */
1
2
  export declare const RTM_REFRESH_TTL_MS: number;
2
3
  export declare const RTM_REFRESH_MARKER: string;
3
4
  export interface RtmRefreshOpts {
@@ -9,5 +10,23 @@ export interface RtmRefreshOpts {
9
10
  unref?: () => void;
10
11
  };
11
12
  ttlMs?: number;
13
+ head?: string | null;
12
14
  }
13
- export declare function maybeSpawnRtmRefresh(opts: RtmRefreshOpts): void;
15
+ export type FreshnessBridgeObservation = {
16
+ status: 'spawned';
17
+ generation: string;
18
+ } | {
19
+ status: 'coalesced';
20
+ generation: string;
21
+ } | {
22
+ status: 'failed';
23
+ };
24
+ /**
25
+ * Request a detached refresh without making the caller wait. A failed child
26
+ * launch is itself durable evidence: close the lease as retry-at so a later
27
+ * request can retry instead of treating a stranded `refreshing` marker as
28
+ * progress.
29
+ */
30
+ export declare function maybeSpawnRtmRefresh(opts: RtmRefreshOpts): FreshnessBridgeObservation;
31
+ /** The MCP-side bridge uses the same lease and child as the end-of-turn hook. */
32
+ export declare function requestBackgroundFreshness(root: string): FreshnessBridgeObservation;
@@ -35,7 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = void 0;
37
37
  exports.maybeSpawnRtmRefresh = maybeSpawnRtmRefresh;
38
- // @implements A-SPEC-566.4
38
+ exports.requestBackgroundFreshness = requestBackgroundFreshness;
39
+ // @implements A-SPEC-724, A-SPEC-723, A-SPEC-719, A-SPEC-734
39
40
  /**
40
41
  * Graph freshness, kept by the product itself. The impact advisory's quality factor was MEASURED to
41
42
  * be staleness (an 8-day-old graph found 7 advisories; a 1-second reindex found 17), so the Stop
@@ -45,32 +46,76 @@ exports.maybeSpawnRtmRefresh = maybeSpawnRtmRefresh;
45
46
  */
46
47
  const fs = __importStar(require("node:fs"));
47
48
  const path = __importStar(require("node:path"));
48
- exports.RTM_REFRESH_TTL_MS = 30 * 60 * 1000;
49
+ const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
50
+ const bounded_io_1 = require("../project/bounded-io");
51
+ /**
52
+ * Same resolution as the child's `headOf`: full commit id, or null outside a repository.
53
+ * @implements A-SPEC-734 (round 13) — through the per-kind memory: a root whose git already timed out is not asked.
54
+ */
55
+ function gitHead(root) {
56
+ try {
57
+ const r = (0, bounded_io_1.gitOnce)(root, ['-C', root, 'rev-parse', 'HEAD'], 'repo', { timeout: 2000 });
58
+ return r.status === 0 ? r.stdout.trim() || null : null;
59
+ }
60
+ catch {
61
+ return null;
62
+ } // bounded: a hung git must never hold the Stop hook
63
+ }
64
+ /** @deprecated A compatibility observation interval; receipt leases are the source of truth. */
65
+ exports.RTM_REFRESH_TTL_MS = freshness_coordinator_1.FRESHNESS_LEASE_MS;
49
66
  exports.RTM_REFRESH_MARKER = path.join('.ax', 'state', 'rtm-refresh-last');
67
+ /**
68
+ * Request a detached refresh without making the caller wait. A failed child
69
+ * launch is itself durable evidence: close the lease as retry-at so a later
70
+ * request can retry instead of treating a stranded `refreshing` marker as
71
+ * progress.
72
+ */
50
73
  function maybeSpawnRtmRefresh(opts) {
51
74
  try {
52
75
  if (!fs.existsSync(path.join(opts.root, '.ax')))
53
- return; // nothing to refresh
76
+ return { status: 'failed' }; // nothing to refresh
77
+ // The lease must name the HEAD the child completes against (A-SPEC-719): a null lease in a git
78
+ // workspace could only ever complete as stale, so intake would never see current evidence.
79
+ const decision = (0, freshness_coordinator_1.requestRefresh)(opts.root, {
80
+ workspaceId: (0, freshness_coordinator_1.workspaceIdFor)(opts.root), head: opts.head !== undefined ? opts.head : gitHead(opts.root), now: new Date(opts.now),
81
+ });
82
+ if (!decision.spawn)
83
+ return { status: 'coalesced', generation: decision.receipt.generation };
84
+ // Retained only for tools that still display the former marker. The receipt
85
+ // above is the authority for coalescing and retrying; this write is never read.
54
86
  const marker = path.join(opts.root, exports.RTM_REFRESH_MARKER);
55
- const ttl = opts.ttlMs ?? exports.RTM_REFRESH_TTL_MS;
56
- try {
57
- const age = opts.now - fs.statSync(marker).mtimeMs;
58
- if (age < ttl)
59
- return; // one refresh per window
60
- }
61
- catch { /* absent marker → refresh is due */ }
62
- // Touch BEFORE spawning: a burst of Stops inside one window must not stampede children.
63
87
  try {
64
88
  fs.mkdirSync(path.dirname(marker), { recursive: true });
65
89
  fs.writeFileSync(marker, String(opts.now));
66
90
  fs.utimesSync(marker, new Date(opts.now), new Date(opts.now));
67
91
  }
68
92
  catch { /* an unwritable marker is not a reason to skip the refresh itself */ }
69
- const child = opts.spawn(opts.execPath, [opts.scriptPath, opts.root], { detached: true, stdio: 'ignore' });
70
- child?.unref?.();
93
+ try {
94
+ const child = opts.spawn(opts.execPath, [opts.scriptPath, opts.root, decision.receipt.generation], { detached: true, stdio: 'ignore' });
95
+ child?.unref?.();
96
+ return { status: 'spawned', generation: decision.receipt.generation };
97
+ }
98
+ catch {
99
+ (0, freshness_coordinator_1.completeRefresh)(opts.root, decision.receipt.generation, {
100
+ graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head: decision.receipt.head,
101
+ }, new Date(opts.now));
102
+ return { status: 'failed' };
103
+ }
71
104
  }
72
- catch { /* freshness is maintenance, never a hook failure */ }
105
+ catch {
106
+ return { status: 'failed' };
107
+ } // freshness is maintenance, never a hook failure
108
+ }
109
+ /** The MCP-side bridge uses the same lease and child as the end-of-turn hook. */
110
+ function requestBackgroundFreshness(root) {
111
+ const cp = require('node:child_process');
112
+ return maybeSpawnRtmRefresh({
113
+ root, now: Date.now(), execPath: process.execPath,
114
+ scriptPath: path.resolve(__dirname, 'rtm-refresh-child.js'),
115
+ spawn: (cmd, args, opts) => cp.spawn(cmd, args, opts),
116
+ });
73
117
  }
74
118
  // The child lives in rtm-refresh-child.ts, NOT here: this module is required by the Stop hook, and
75
119
  // the gate path must never carry the AST substrate (A-SPEC-510.2 pinned it, and its static check
76
- // caught the first cut of this slice doing exactly that). The gate side is fs+path only.
120
+ // caught the first cut of this slice doing exactly that). The gate side is fs+path plus one lazy
121
+ // `git rev-parse HEAD` (child_process, no AST substrate) to bind the lease to its HEAD.
@@ -21,3 +21,13 @@ export declare function detectInstallMode(packageRoot: string): InstallMode;
21
21
  /** Pure: build the banner output and decide whether a refresh should fire. No I/O beyond the
22
22
  * injected readFile; the caller performs the detached spawn when shouldRefresh is true. */
23
23
  export declare function buildSessionStartOutput(input: SessionStartInput): SessionStartOutput;
24
+ /**
25
+ * @implements A-SPEC-543.3
26
+ * If this workspace's holmes pin is behind the installed package, return a one-line NUDGE to run
27
+ * `holmes-kit upgrade`; otherwise return ''. Detection is zero-config (automatic every session), but
28
+ * the re-pin WRITE is NOT done here: `runInit({force:true})` is gated by a governance-wiring approval,
29
+ * so a silent session-start write would bypass it. The write stays the user's explicit choice via
30
+ * `upgrade`/`init --force`. Forward-drift + opt-out judgment is the pure `repinDecision`; every
31
+ * failure returns '' (fail-open — a banner is never a gate).
32
+ */
33
+ export declare function driftNudge(cwd: string, installed: string, env: NodeJS.ProcessEnv): string;
@@ -35,7 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.detectInstallMode = detectInstallMode;
37
37
  exports.buildSessionStartOutput = buildSessionStartOutput;
38
- // @implements A-SPEC-531.2
38
+ exports.driftNudge = driftNudge;
39
+ // @implements A-SPEC-531.2, A-SPEC-734
39
40
  // The SessionStart banner hook. It emits the intro (+ optional update notice) as additionalContext,
40
41
  // which Claude Code delivers to BOTH the human transcript and the agent context — the "human and
41
42
  // agent" delivery REQ-531 asks for. The update refresh is a DETACHED, fire-and-forget child so the
@@ -97,15 +98,36 @@ function driftNudge(cwd, installed, env) {
97
98
  const entry = mcp.mcpServers?.['holmes-kit'];
98
99
  if (!entry || typeof entry.command !== 'string' || !Array.isArray(entry.args))
99
100
  return '';
100
- const pinned = mcpLaunchVersion({ command: entry.command, args: entry.args }, (dir) => { try {
101
- return String(JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).version);
101
+ // @implements A-SPEC-251.2 (confirmation round 24) — only holmes-kit's own package.json answers (an unrelated
102
+ // `tools/package.json` produced a false nudge), and the version reaches the model clipped (a 900 KB version went
103
+ // into every session's context — measured).
104
+ // @implements A-SPEC-251.2 (round 44) — a node launch is walked once and its package.json read only above the walked local path
105
+ // (a `/net/…` argument was read as spelled — measured).
106
+ let args = entry.args;
107
+ const { localRealpath } = require('../cli/codex-oracle');
108
+ if (entry.command === 'node' && typeof args[0] === 'string') {
109
+ const walked = localRealpath(path.resolve(cwd, args[0]));
110
+ if (walked.refused || walked.path === null)
111
+ return '';
112
+ args = [walked.path, ...args.slice(1)];
102
113
  }
103
- catch {
104
- return undefined;
105
- } });
114
+ const pinned = mcpLaunchVersion({ command: entry.command, args }, (dir) => {
115
+ // Round 45: each package.json is walked too, and read at its walked path (a committed `bin/package.json` link to `/net`
116
+ // was opened as spelled — measured).
117
+ const walkedPkg = localRealpath(path.join(dir, 'package.json'));
118
+ if (walkedPkg.refused || walkedPkg.path === null)
119
+ return undefined;
120
+ try {
121
+ const pkg = JSON.parse(fs.readFileSync(walkedPkg.path, 'utf8'));
122
+ return pkg?.name === '@holmes-lab/holmes-kit' && typeof pkg.version === 'string' ? pkg.version.slice(0, 40) : undefined;
123
+ }
124
+ catch {
125
+ return undefined;
126
+ }
127
+ });
106
128
  if (!repinDecision({ pinned, installed, env }).repin)
107
129
  return '';
108
- return `\n[Holmes-Kit] this workspace is pinned to ${pinned}, but ${installed} is installed — run \`${npxBin()} holmes-kit upgrade\` to re-pin.`;
130
+ return `\n[Holmes-Kit] this workspace is pinned to ${String(pinned).slice(0, 40)}, but ${installed} is installed — run \`${npxBin()} holmes-kit upgrade\` to re-pin.`;
109
131
  }
110
132
  catch {
111
133
  return '';
@@ -114,6 +136,8 @@ function driftNudge(cwd, installed, env) {
114
136
  // CLI entry: read the hook JSON on stdin (unused beyond triggering), emit the banner, and — when
115
137
  // allowed — fire the detached refresh. Wrapped so any failure is an empty output + exit 0.
116
138
  if (require.main === module) {
139
+ // @implements A-SPEC-734 (round 13) — this process never blocks on a file that is not a regular file.
140
+ require('../project/regular-file-guard').installProcessGuards();
117
141
  // @implements A-SPEC-547.1 — the detached `--refresh` child actually queries the registry and writes
118
142
  // the cache. Without this branch the spawn fell through to the banner path and wrote nothing, so the
119
143
  // update notice never appeared for any harness. Public dist-tags only, short timeout, fail-open.
@@ -1,4 +1,5 @@
1
1
  import { PendingRequest } from '../governance/approval-queue';
2
+ export declare const STOP_NOTICES: Set<string>;
2
3
  import { Spec } from '../spec/spec-parser';
3
4
  import type { TestOutcome } from '../review/test-runner';
4
5
  import { type KnownDefectJudgement } from '../rtm/known-defects';
@@ -6,7 +7,7 @@ import { type CiVerdict } from '../project/ci-runs';
6
7
  import { type DistVerdict } from '../project/dist-freshness';
7
8
  import { type AnalysisVerdict } from '../project/analysis-currency';
8
9
  import { judgeForbiddenEdges } from '../cpg/forbidden-edges';
9
- import type { ScannedFile } from '../cpg/cpg-scanner';
10
+ import { type ScannedFile } from '../cpg/cpg-scanner';
10
11
  /** @implements A-SPEC-693 */
11
12
  export type ForbiddenEdgeJudgement = ReturnType<typeof judgeForbiddenEdges>;
12
13
  export declare function collectKnownDefects(root: string, now: Date): KnownDefectJudgement | undefined;