@holmes-lab/holmes-kit 0.35.20 → 0.35.22

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.
@@ -39,13 +39,15 @@ exports.recordRefreshFailure = recordRefreshFailure;
39
39
  exports.armWorkerDeadline = armWorkerDeadline;
40
40
  exports.lowerOwnPriority = lowerOwnPriority;
41
41
  exports.armSupersedeWatch = armSupersedeWatch;
42
+ exports.armRefreshWorkerTimers = armRefreshWorkerTimers;
42
43
  exports.runRefreshChild = runRefreshChild;
43
44
  exports.defaultRefreshChildDeps = defaultRefreshChildDeps;
44
- // @implements A-SPEC-719, A-SPEC-734
45
+ // @implements A-SPEC-719, A-SPEC-734, A-SPEC-719.7
45
46
  // @implements A-SPEC-566.4
46
47
  // @implements A-SPEC-768.4
47
48
  // @implements A-SPEC-719.1
48
49
  // @implements A-SPEC-719.2
50
+ // @implements A-SPEC-719.6
49
51
  // @implements A-SPEC-769.9
50
52
  /**
51
53
  * The detached refresh child — the ONLY place this slice touches the scan/build machinery. Spawned
@@ -57,15 +59,30 @@ const fs = __importStar(require("node:fs"));
57
59
  const os = __importStar(require("node:os"));
58
60
  const path = __importStar(require("node:path"));
59
61
  const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
60
- const currentHead = (root) => {
62
+ const probeHead = (root) => {
61
63
  try {
62
- const { headOf } = require('../mcp/handlers/graph-operations');
63
- return headOf(root);
64
+ const { headProbe } = require('./rtm-refresh');
65
+ const { GIT_TIMEOUT_MS } = require('../project/bounded-io');
66
+ // @implements A-SPEC-719.6 — the worker's own scan may have timed out a git call on this root: ask anyway, with
67
+ // the ordinary 5 s bound, rather than be skipped by the memory and publish every finished refresh `retry-at`.
68
+ return headProbe(root, { timeoutMs: GIT_TIMEOUT_MS, ignoreBlock: true });
64
69
  }
65
70
  catch {
66
- return null;
71
+ return { head: null, unanswered: true };
67
72
  }
68
73
  };
74
+ const currentHead = (root) => probeHead(root).head;
75
+ /**
76
+ * @implements A-SPEC-719.5 — the head a completion is written against. When git did not answer, the lease's own head:
77
+ * a mismatch would publish `stale` (no retry pause) and throw a finished refresh away; `retry-at` paces the retry.
78
+ */
79
+ function completionHead(root, generation, probe) {
80
+ const p = probe(root);
81
+ if (!p.unanswered)
82
+ return p;
83
+ const leased = (0, freshness_coordinator_1.leaseHead)(root, generation);
84
+ return { head: leased === undefined ? null : leased, unanswered: true };
85
+ }
69
86
  // @implements A-SPEC-768.4
70
87
  /** The error as a bounded reason: its message (never a stack), at most REFRESH_FAILURE_REASON_MAX characters. */
71
88
  function failureReason(error) {
@@ -87,7 +104,7 @@ function recordRefreshFailure(root, generation, head, now, failure) {
87
104
  function armWorkerDeadline(root, generation, opts) {
88
105
  const timer = setTimeout(() => {
89
106
  try {
90
- recordRefreshFailure(root, generation, currentHead(root), (opts.now ?? (() => new Date()))(), { stage: 'child', reason: `worker exceeded ${opts.ms} ms` });
107
+ recordRefreshFailure(root, generation, completionHead(root, generation, probeHead).head, (opts.now ?? (() => new Date()))(), { stage: 'child', reason: `worker exceeded ${opts.ms} ms` });
91
108
  }
92
109
  catch { /* fail-soft: ending is what matters */ }
93
110
  opts.exit();
@@ -115,7 +132,9 @@ function lowerOwnPriority(setPriority = (p) => os.setPriority(p)) {
115
132
  * 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
116
133
  */
117
134
  function armSupersedeWatch(root, generation, opts) {
118
- const owns = opts.owns ?? freshness_coordinator_1.ownsLease;
135
+ // @implements A-SPEC-719.4 — by default only a readable newer lease or a removed workspace ends the worker:
136
+ // `ownsLease` read a missing or unreadable receipt as "not owned" and ended live workers on a transient read.
137
+ const owns = opts.owns ?? ((r, g) => !(0, freshness_coordinator_1.leaseSuperseded)(r, g));
119
138
  const timer = setInterval(() => {
120
139
  let current = true;
121
140
  try {
@@ -123,7 +142,7 @@ function armSupersedeWatch(root, generation, opts) {
123
142
  }
124
143
  catch {
125
144
  current = true;
126
- } // an unreadable receipt is not a supersession
145
+ } // a throwing check is not a supersession
127
146
  if (current)
128
147
  return;
129
148
  clearInterval(timer);
@@ -131,6 +150,15 @@ function armSupersedeWatch(root, generation, opts) {
131
150
  }, opts.intervalMs);
132
151
  timer.unref?.();
133
152
  }
153
+ /**
154
+ * @implements A-SPEC-719.5 — the worker's two timers, armed as one tested unit: the deadline inside the lease cap
155
+ * (A-SPEC-719.1/719.4) and the supersede watch (A-SPEC-719.2). The main block calls only this.
156
+ */
157
+ function armRefreshWorkerTimers(root, generation, deps = {}) {
158
+ const exit = deps.exit ?? (() => process.exit(0));
159
+ (deps.deadline ?? armWorkerDeadline)(root, generation, { ms: freshness_coordinator_1.FRESHNESS_WORKER_DEADLINE_MS, exit });
160
+ (deps.watch ?? armSupersedeWatch)(root, generation, { intervalMs: exports.REFRESH_SUPERSEDE_POLL_MS, exit });
161
+ }
134
162
  /**
135
163
  * One refresh run for one lease generation. Every phase that writes is preceded by a lease check,
136
164
  * so a superseded worker, or one whose root was removed, stops without writing (A-SPEC-724). Any
@@ -171,19 +199,28 @@ async function runRefreshChild(root, generation, deps) {
171
199
  requirement = { status: 'unavailable' };
172
200
  failure ??= { stage: 'requirement', reason: failureReason(error) };
173
201
  }
202
+ const final = completionHead(root, generation, deps.headProbe ?? ((r) => ({ head: deps.head(r), unanswered: false })));
203
+ // A-SPEC-719.5 — retry after the pause rather than publish `stale`; A-SPEC-719.7 — only when the lease named a commit:
204
+ // a lease taken under a git that refused completes under null as 0.35.20 did (a git that refuses for good would
205
+ // otherwise keep intake refused and re-run the whole refresh every pause).
206
+ if (final.unanswered && final.head !== null) {
207
+ recordRefreshFailure(root, generation, final.head, new Date(), { stage: 'child', reason: 'git did not answer for HEAD at completion' });
208
+ return;
209
+ }
174
210
  (0, freshness_coordinator_1.completeRefresh)(root, generation, {
175
211
  graph: 'current',
176
212
  sourceSemantic: source.lane,
177
213
  requirementSemantic: requirement.status === 'discharged' ? 'current'
178
214
  : requirement.status === 'not-applicable' ? 'not-adopted'
179
215
  : requirement.status === 'suppressed' ? 'suppressed' : 'failed',
180
- head: deps.head(root),
216
+ head: final.head,
181
217
  ...(failure ? { failure } : {}),
182
218
  }, new Date());
183
219
  }
184
220
  catch (error) {
185
221
  try {
186
- recordRefreshFailure(root, generation, deps.head(root), new Date(), { stage, reason: failureReason(error) });
222
+ const head = completionHead(root, generation, deps.headProbe ?? ((r) => ({ head: deps.head(r), unanswered: false }))).head;
223
+ recordRefreshFailure(root, generation, head, new Date(), { stage, reason: failureReason(error) });
187
224
  }
188
225
  catch { /* fail-soft */ }
189
226
  }
@@ -195,6 +232,7 @@ function defaultRefreshChildDeps(env = process.env) {
195
232
  const suppressed = typeof env.HOLMES_NO_SEMANTIC_WARM === 'string' && env.HOLMES_NO_SEMANTIC_WARM !== '';
196
233
  return {
197
234
  head: currentHead,
235
+ headProbe: probeHead,
198
236
  refreshGraph: async (root) => {
199
237
  const { makeHandlers } = require('../mcp/handlers');
200
238
  const { LocalMarkdownRepository } = require('../spec/spec-store');
@@ -227,12 +265,8 @@ if (require.main === module) {
227
265
  const root = process.argv[2];
228
266
  const generation = process.argv[3];
229
267
  lowerOwnPriority(); // A-SPEC-719.2 — background work yields to foreground sessions
230
- // @implements A-SPEC-719.1 — never outlive the lease cap
231
- if (root && generation)
232
- armWorkerDeadline(root, generation, { ms: freshness_coordinator_1.FRESHNESS_WORKER_MAX_MS, exit: () => process.exit(0) });
233
- // @implements A-SPEC-719.2 — end promptly once superseded
234
268
  if (root && generation)
235
- armSupersedeWatch(root, generation, { intervalMs: exports.REFRESH_SUPERSEDE_POLL_MS, exit: () => process.exit(0) });
269
+ armRefreshWorkerTimers(root, generation);
236
270
  // fail-soft: a failed refresh leaves the old graph, which the advisory tolerates
237
271
  if (root && generation)
238
272
  void runRefreshChild(root, generation, defaultRefreshChildDeps()).catch(() => undefined);
@@ -1,3 +1,18 @@
1
+ /** @implements A-SPEC-719.9 — 0.35.20's lease probe bound: an answer slower than this is remembered as a timeout. */
2
+ export declare const LEASE_SLOW_GIT_MS = 2000;
3
+ /** Test seam: forget every remembered slow-read head. */
4
+ export declare function forgetSlowLeaseHeads(): void;
5
+ /**
6
+ * Same resolution as the child's `headOf`: full commit id, or null outside a repository.
7
+ * @implements A-SPEC-734 (round 13) — through the per-kind memory: a root whose git already timed out is not asked.
8
+ */
9
+ export declare function headProbe(root: string, opts?: {
10
+ timeoutMs?: number;
11
+ ignoreBlock?: boolean;
12
+ }): {
13
+ head: string | null;
14
+ unanswered: boolean;
15
+ };
1
16
  /** @deprecated A compatibility observation interval; receipt leases are the source of truth. */
2
17
  export declare const RTM_REFRESH_TTL_MS: number;
3
18
  export declare const RTM_REFRESH_MARKER: string;
@@ -12,6 +27,13 @@ export interface RtmRefreshOpts {
12
27
  };
13
28
  ttlMs?: number;
14
29
  head?: string | null;
30
+ /** @implements A-SPEC-719.4 — test seam for the HEAD probe used when `head` is not given. */
31
+ headProbe?: (root: string, opts?: {
32
+ ignoreBlock?: boolean;
33
+ }) => {
34
+ head: string | null;
35
+ unanswered: boolean;
36
+ };
15
37
  }
16
38
  export type FreshnessBridgeObservation = {
17
39
  status: 'spawned';
@@ -33,11 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = void 0;
36
+ exports.RTM_REFRESH_MARKER = exports.RTM_REFRESH_TTL_MS = exports.LEASE_SLOW_GIT_MS = void 0;
37
+ exports.forgetSlowLeaseHeads = forgetSlowLeaseHeads;
38
+ exports.headProbe = headProbe;
37
39
  exports.maybeSpawnRtmRefresh = maybeSpawnRtmRefresh;
38
40
  exports.requestBackgroundFreshness = requestBackgroundFreshness;
39
41
  // @implements A-SPEC-724, A-SPEC-723, A-SPEC-719, A-SPEC-734
40
- // @implements A-SPEC-719.1
42
+ // @implements A-SPEC-719.1, A-SPEC-719.4, A-SPEC-719.5, A-SPEC-719.6, A-SPEC-719.8, A-SPEC-719.9, A-SPEC-719.10, A-SPEC-719.11, A-SPEC-719.12, A-SPEC-719.13
41
43
  /**
42
44
  * Graph freshness, kept by the product itself. The impact advisory's quality factor was MEASURED to
43
45
  * be staleness (an 8-day-old graph found 7 advisories; a 1-second reindex found 17), so the Stop
@@ -49,17 +51,51 @@ const fs = __importStar(require("node:fs"));
49
51
  const path = __importStar(require("node:path"));
50
52
  const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
51
53
  const bounded_io_1 = require("../project/bounded-io");
54
+ /** @implements A-SPEC-719.9 — 0.35.20's lease probe bound: an answer slower than this is remembered as a timeout. */
55
+ exports.LEASE_SLOW_GIT_MS = 2000;
56
+ /**
57
+ * @implements A-SPEC-719.10 — the head a slow lease read answered, per root, for as long as that read keeps the
58
+ * root's repo git blocked: the MCP bridge's next request finds its probe skipped and would lease null — a new
59
+ * refresh against a receipt already current at the commit, each time the previous one ended (0.35.20's storm).
60
+ */
61
+ const SLOW_LEASE_HEADS = new Map();
62
+ const SLOW_LEASE_HEAD_MS = 60_000;
63
+ /** Test seam: forget every remembered slow-read head. */
64
+ function forgetSlowLeaseHeads() { SLOW_LEASE_HEADS.clear(); }
65
+ /** @implements A-SPEC-719.11 — the key bounded-io's git-timeout memory uses: an alias resolves to the same entry. */
66
+ const slowLeaseKey = (root) => {
67
+ try {
68
+ return fs.realpathSync.native(root);
69
+ }
70
+ catch {
71
+ return path.resolve(root);
72
+ }
73
+ };
52
74
  /**
53
75
  * Same resolution as the child's `headOf`: full commit id, or null outside a repository.
54
76
  * @implements A-SPEC-734 (round 13) — through the per-kind memory: a root whose git already timed out is not asked.
55
77
  */
56
- function gitHead(root) {
78
+ function headProbe(root, opts = {}) {
57
79
  try {
58
- const r = (0, bounded_io_1.gitOnce)(root, ['-C', root, 'rev-parse', 'HEAD'], 'repo', { timeout: 2000 });
59
- return r.status === 0 ? r.stdout.trim() || null : null;
80
+ // @implements A-SPEC-719.5 — `--verify -q` exits 1 silently for an unborn HEAD, so a refusal (128: dubious
81
+ // ownership, an unknown extension, a broken gitdir) is told apart from a repository with no commit yet.
82
+ // @implements A-SPEC-719.8 — the lease waits as long as the worker and intake do (5 s): at 2 s a git answering in
83
+ // 2–5 s leased a null head, the worker completed against the commit as `stale`, and every request spawned anew.
84
+ const r = (0, bounded_io_1.gitOnce)(root, ['-C', root, 'rev-parse', '--verify', '-q', 'HEAD'], 'repo', { timeout: opts.timeoutMs ?? bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: opts.ignoreBlock });
85
+ if (r.status === 0 && r.error === undefined)
86
+ return { head: r.stdout.trim() || null, unanswered: false };
87
+ // @implements A-SPEC-719.4 — no exit status (timed out, killed, or skipped by the per-kind memory) is not "no
88
+ // repository": a null head would lease a generation the live worker's HEAD never matches, every request.
89
+ if (r.error?.code === 'ENOENT')
90
+ return { head: null, unanswered: false };
91
+ if (!(0, bounded_io_1.gitEntryAbove)(root))
92
+ return { head: null, unanswered: false }; // the tree says: no repository
93
+ if (r.status === 1)
94
+ return { head: null, unanswered: false }; // a repository with an unborn HEAD
95
+ return { head: null, unanswered: true };
60
96
  }
61
97
  catch {
62
- return null;
98
+ return { head: null, unanswered: true };
63
99
  } // bounded: a hung git must never hold the Stop hook
64
100
  }
65
101
  /** @deprecated A compatibility observation interval; receipt leases are the source of truth. */
@@ -77,9 +113,68 @@ function maybeSpawnRtmRefresh(opts) {
77
113
  return { status: 'failed' }; // nothing to refresh
78
114
  // The lease must name the HEAD the child completes against (A-SPEC-719): a null lease in a git
79
115
  // workspace could only ever complete as stale, so intake would never see current evidence.
80
- const decision = (0, freshness_coordinator_1.requestRefresh)(opts.root, {
81
- workspaceId: (0, freshness_coordinator_1.workspaceIdFor)(opts.root), head: opts.head !== undefined ? opts.head : gitHead(opts.root), now: new Date(opts.now),
82
- });
116
+ let head;
117
+ // @implements A-SPEC-719.11 — the lease time follows the probe: stamped before a probe that waits for git, a refresh
118
+ // completing meanwhile looked "completed in the future" and every such request spawned again (also in 0.35.20).
119
+ const started = Date.now();
120
+ let now = opts.now;
121
+ const workspaceId = (0, freshness_coordinator_1.workspaceIdFor)(opts.root);
122
+ if (opts.head !== undefined)
123
+ head = opts.head;
124
+ else {
125
+ const read = opts.headProbe ?? headProbe;
126
+ // @implements A-SPEC-719.11 — keyed as the git-timeout memory is, so an alias spelling finds the remembered head.
127
+ const key = slowLeaseKey(opts.root);
128
+ // @implements A-SPEC-719.9 — a read that answered only past 0.35.20's 2 s bound is remembered as that timeout
129
+ // was, so the caller's later git reads (the Stop hook's evaluation) skip instead of each waiting for this git.
130
+ const remember = (probe, from) => {
131
+ if (probe.unanswered)
132
+ return;
133
+ if (Date.now() - from >= exports.LEASE_SLOW_GIT_MS) {
134
+ (0, bounded_io_1.noteGitFailure)(opts.root, { code: 'ETIMEDOUT' }, 'repo');
135
+ SLOW_LEASE_HEADS.set(key, { head: probe.head, at: Date.now() });
136
+ // @implements A-SPEC-719.13 — while the root's git is still blocked, later probes are skipped: keep the head
137
+ // this fast answer gave (forgetting it leased null, and the worker completed stale, for the rest of the minute).
138
+ }
139
+ else if ((0, bounded_io_1.gitRootBlocked)(opts.root, 'repo'))
140
+ SLOW_LEASE_HEADS.set(key, { head: probe.head, at: Date.now() });
141
+ else
142
+ SLOW_LEASE_HEADS.delete(key);
143
+ };
144
+ const probe = read(opts.root);
145
+ remember(probe, started);
146
+ head = probe.head;
147
+ if (probe.unanswered) {
148
+ // @implements A-SPEC-719.6 — join a live lease rather than supersede it (the 719.4 defect); with none, lease a
149
+ // null head as 0.35.20 did, so a git that refuses for good still refreshes.
150
+ const live = (0, freshness_coordinator_1.leaseLive)(opts.root, new Date(now));
151
+ if (live !== null)
152
+ return { status: 'coalesced', generation: live.generation };
153
+ // @implements A-SPEC-719.10 — within the minute, the head this process's slow read answered.
154
+ const remembered = SLOW_LEASE_HEADS.get(key);
155
+ const age = remembered === undefined ? NaN : Date.now() - remembered.at;
156
+ head = remembered !== undefined && age >= 0 && age < SLOW_LEASE_HEAD_MS ? remembered.head : null;
157
+ // @implements A-SPEC-719.11 — a receipt the worker wrote `stale` at the remembered head says HEAD moved: leased
158
+ // again, that head re-spawned the refresh on every request of the minute. Read once more past the memory.
159
+ if (remembered !== undefined && head === remembered.head
160
+ && (0, freshness_coordinator_1.readFreshnessReceipt)(opts.root, { workspaceId, head, now: new Date(now) })?.state === 'stale') {
161
+ SLOW_LEASE_HEADS.delete(key);
162
+ const again = Date.now();
163
+ const fresh = read(opts.root, { ignoreBlock: true });
164
+ remember(fresh, again);
165
+ head = fresh.unanswered ? null : fresh.head;
166
+ }
167
+ }
168
+ // @implements A-SPEC-719.12 — only a completion stamped inside this request's own wait moves its time; the
169
+ // caller's clock stands otherwise (719.11 added the whole wait, and an exact TTL boundary drifted by the probe).
170
+ const waited = Date.now() - started;
171
+ if (waited > 0) {
172
+ const done = Date.parse((0, freshness_coordinator_1.readFreshnessReceipt)(opts.root, { workspaceId, head, now: new Date(opts.now) })?.completedAt ?? '');
173
+ if (Number.isFinite(done) && done > opts.now && done <= opts.now + waited)
174
+ now = opts.now + waited;
175
+ }
176
+ }
177
+ const decision = (0, freshness_coordinator_1.requestRefresh)(opts.root, { workspaceId, head, now: new Date(now) });
83
178
  if (!decision.spawn)
84
179
  return { status: 'coalesced', generation: decision.receipt.generation };
85
180
  // Retained only for tools that still display the former marker. The receipt
@@ -87,12 +182,21 @@ function maybeSpawnRtmRefresh(opts) {
87
182
  const marker = path.join(opts.root, exports.RTM_REFRESH_MARKER);
88
183
  try {
89
184
  fs.mkdirSync(path.dirname(marker), { recursive: true });
90
- fs.writeFileSync(marker, String(opts.now));
91
- fs.utimesSync(marker, new Date(opts.now), new Date(opts.now));
185
+ fs.writeFileSync(marker, String(now));
186
+ fs.utimesSync(marker, new Date(now), new Date(now));
92
187
  }
93
188
  catch { /* an unwritable marker is not a reason to skip the refresh itself */ }
94
189
  try {
95
- const child = opts.spawn(opts.execPath, [opts.scriptPath, opts.root, decision.receipt.generation], { detached: true, stdio: 'ignore' });
190
+ const fail = () => (0, freshness_coordinator_1.completeRefresh)(opts.root, decision.receipt.generation, {
191
+ graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head: decision.receipt.head,
192
+ }, new Date(now));
193
+ const child = opts.spawn(opts.execPath, [opts.scriptPath, opts.root, decision.receipt.generation], { detached: true, stdio: 'ignore', windowsHide: true });
194
+ // @implements A-SPEC-719.4 — ENOENT/EAGAIN arrive as an 'error' event on the next tick, not a throw: unheard,
195
+ // it ended the MCP server or the Stop hook and left a pid-less `refreshing` lease.
196
+ child?.on?.('error', () => { try {
197
+ fail();
198
+ }
199
+ catch { /* fail-soft */ } });
96
200
  child?.unref?.();
97
201
  // @implements A-SPEC-719.1 — the lease names its worker, so a live refresh is not taken for a crashed one.
98
202
  if (typeof child?.pid === 'number') {
@@ -106,7 +210,7 @@ function maybeSpawnRtmRefresh(opts) {
106
210
  catch {
107
211
  (0, freshness_coordinator_1.completeRefresh)(opts.root, decision.receipt.generation, {
108
212
  graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head: decision.receipt.head,
109
- }, new Date(opts.now));
213
+ }, new Date(now));
110
214
  return { status: 'failed' };
111
215
  }
112
216
  }
@@ -39,13 +39,14 @@ exports.warmRequirementSemanticCache = warmRequirementSemanticCache;
39
39
  exports.headOf = headOf;
40
40
  exports.refreshSemanticVectors = refreshSemanticVectors;
41
41
  exports.createGraphOperationsHandlers = createGraphOperationsHandlers;
42
- // @implements A-SPEC-719, A-SPEC-734, A-SPEC-741.1, A-SPEC-758.1, A-SPEC-688.1
42
+ // @implements A-SPEC-719, A-SPEC-734, A-SPEC-741.1, A-SPEC-758.1, A-SPEC-688.1, A-SPEC-719.5, A-SPEC-719.8
43
43
  // @implements A-SPEC-614, A-SPEC-613, A-SPEC-100.2, A-SPEC-121.2, A-SPEC-128, A-SPEC-139, A-SPEC-189, A-SPEC-280, A-SPEC-282, A-SPEC-283, A-SPEC-419, A-SPEC-433, A-SPEC-469, A-SPEC-478, A-SPEC-568.1, A-SPEC-568.2, A-SPEC-569.1, A-SPEC-569.2, A-SPEC-569.3, A-SPEC-589
44
44
  // @implements A-SPEC-632
45
45
  const fs = __importStar(require("node:fs"));
46
46
  const path = __importStar(require("node:path"));
47
47
  const hash_cache_1 = require("../../cpg/hash-cache");
48
48
  const root_1 = require("../../project/root");
49
+ const bounded_io_1 = require("../../project/bounded-io");
49
50
  const rtm_builder_1 = require("../../rtm/rtm-builder");
50
51
  const graph_store_1 = require("../../rtm/graph-store");
51
52
  const assoc_arm_1 = require("../../assoc/assoc-arm");
@@ -55,7 +56,6 @@ const tier_1 = require("../../semantic/tier");
55
56
  const vector_cache_1 = require("../../semantic/vector-cache");
56
57
  const embedder_1 = require("../../semantic/embedder");
57
58
  const unreadable_paths_1 = require("../../semantic/unreadable-paths");
58
- const bounded_io_1 = require("../../project/bounded-io");
59
59
  const vector_coverage_1 = require("../../semantic/vector-coverage");
60
60
  // @implements A-SPEC-283 — bumped whenever the graph's node/edge shape changes, so a store written
61
61
  // by an older build is rebuilt rather than read with new assumptions.
@@ -140,9 +140,12 @@ async function warmRequirementSemanticCache(root, specs) {
140
140
  }
141
141
  /** The commit the verdict describes. null when this is not a Git tree — never a fabricated value. */
142
142
  function headOf(root) {
143
+ // @implements A-SPEC-719.5 — the lease, the worker and triage read HEAD through one probe (scrubbed env, bounded):
144
+ // an exported GIT_DIR made this raw call read another repository than the lease, and every completion `stale`.
143
145
  try {
144
- const { execFileSync } = require('node:child_process');
145
- return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
146
+ // @implements A-SPEC-719.8 — with 0.35.20's 5 s bound and past the timeout memory, as its raw read was.
147
+ const { headProbe } = require('../../hooks/rtm-refresh');
148
+ return headProbe(root, { timeoutMs: bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: true }).head;
146
149
  }
147
150
  catch {
148
151
  return null;
@@ -39,7 +39,6 @@ exports.createRequirementTriageHandlers = createRequirementTriageHandlers;
39
39
  // @implements A-SPEC-743, A-SPEC-742, A-SPEC-729, A-SPEC-723, A-SPEC-719, A-SPEC-734, A-SPEC-723.1
40
40
  // @implements A-SPEC-713
41
41
  /** Read-only MCP projection of the pure requirement lifecycle triage model. */
42
- const node_child_process_1 = require("node:child_process");
43
42
  const crypto = __importStar(require("node:crypto"));
44
43
  const path = __importStar(require("node:path"));
45
44
  const test_evidence_1 = require("../../review/test-evidence");
@@ -94,9 +93,14 @@ function lineageOf(id, byId) {
94
93
  }
95
94
  return null;
96
95
  }
96
+ /**
97
+ * @implements A-SPEC-719.6 — through the lease's scrubbed probe (an exported GIT_DIR named another repository).
98
+ * @implements A-SPEC-719.7 — past the process's git-timeout memory, as the raw read of 0.35.20 was.
99
+ */
97
100
  function headOf(root) {
98
101
  try {
99
- return (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
102
+ const { headProbe } = require('../../hooks/rtm-refresh');
103
+ return headProbe(root, { timeoutMs: bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: true }).head ?? '';
100
104
  }
101
105
  catch {
102
106
  return '';
@@ -72,6 +72,13 @@ export declare function validateTriageArtifact(root: string, digest: string, exp
72
72
  * freshness receipt is the current one for this workspace and HEAD. Callers run their own
73
73
  * deterministic refusals first and call this immediately before their first write.
74
74
  */
75
+ /**
76
+ * @implements A-SPEC-719.6 — the HEAD intake judges evidence against, read through the same scrubbed probe as the lease
77
+ * and the worker: the raw `rev-parse HEAD` followed an exported GIT_DIR to another repository and never matched.
78
+ * @implements A-SPEC-719.7 — past the process's git-timeout memory: another call timing out on this root must not
79
+ * leave intake judging against no HEAD for the memory's whole window.
80
+ */
81
+ export declare function intakeHead(root: string): string | null;
75
82
  export declare function validateRequirementIntake(root: string, triageEvidence: unknown): {
76
83
  ok: true;
77
84
  } | {
@@ -40,14 +40,14 @@ exports.consumeRequirementTriageEvidence = consumeRequirementTriageEvidence;
40
40
  exports.hasRequirementIntakeRecord = hasRequirementIntakeRecord;
41
41
  exports.everSealedInLedger = everSealedInLedger;
42
42
  exports.validateTriageArtifact = validateTriageArtifact;
43
+ exports.intakeHead = intakeHead;
43
44
  exports.validateRequirementIntake = validateRequirementIntake;
44
- // @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734
45
+ // @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734, A-SPEC-719.6
45
46
  // @implements A-SPEC-713
46
47
  /** Content-addressed, isolated persistence for advisory requirement triage results. */
47
48
  const crypto = __importStar(require("node:crypto"));
48
49
  const fs = __importStar(require("node:fs"));
49
50
  const path = __importStar(require("node:path"));
50
- const node_child_process_1 = require("node:child_process");
51
51
  const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
52
52
  const ledger_store_1 = require("../governance/ledger-store");
53
53
  const provenance_chain_1 = require("../governance/provenance-chain");
@@ -229,16 +229,27 @@ function validateTriageArtifact(root, digest, expected) {
229
229
  * freshness receipt is the current one for this workspace and HEAD. Callers run their own
230
230
  * deterministic refusals first and call this immediately before their first write.
231
231
  */
232
+ /**
233
+ * @implements A-SPEC-719.6 — the HEAD intake judges evidence against, read through the same scrubbed probe as the lease
234
+ * and the worker: the raw `rev-parse HEAD` followed an exported GIT_DIR to another repository and never matched.
235
+ * @implements A-SPEC-719.7 — past the process's git-timeout memory: another call timing out on this root must not
236
+ * leave intake judging against no HEAD for the memory's whole window.
237
+ */
238
+ function intakeHead(root) {
239
+ try {
240
+ const { headProbe } = require('../hooks/rtm-refresh');
241
+ return headProbe(root, { timeoutMs: bounded_io_1.GIT_TIMEOUT_MS, ignoreBlock: true }).head;
242
+ }
243
+ catch {
244
+ return null;
245
+ } // non-git root is null
246
+ }
232
247
  function validateRequirementIntake(root, triageEvidence) {
233
248
  const evidence = triageEvidence;
234
249
  if (!evidence || typeof evidence.digest !== 'string' || typeof evidence.promptDigest !== 'string') {
235
250
  return { ok: false, reason: '새 REQ에는 requirement_triage가 발급한 현재 triage_evidence {digest,promptDigest}가 필요합니다. 같은 prompt로 requirement_triage(persist:true)를 실행한 뒤 다시 시도하십시오.' };
236
251
  }
237
- let head = null;
238
- try {
239
- head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { timeout: bounded_io_1.GIT_TIMEOUT_MS, maxBuffer: bounded_io_1.GIT_MAX_BUFFER, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
240
- }
241
- catch { /* non-git root is null */ }
252
+ const head = intakeHead(root);
242
253
  const workspaceId = (0, freshness_coordinator_1.workspaceIdFor)(root);
243
254
  const artifact = validateTriageArtifact(root, evidence.digest, { promptDigest: evidence.promptDigest, workspaceId, head });
244
255
  if (!artifact.ok)
@@ -46,6 +46,7 @@ export declare function gitOnce(root: string, args: string[], kind: GitKind, opt
46
46
  input?: string;
47
47
  timeout?: number;
48
48
  env?: NodeJS.ProcessEnv;
49
+ ignoreBlock?: boolean;
49
50
  }): SpawnSyncReturns<string>;
50
51
  /** Test seam: forget every blocked root. */
51
52
  export declare function resetGitBlocked(): void;
@@ -104,7 +104,9 @@ function noteGitFailure(root, err, kind = 'worktree') {
104
104
  * 27–32 s — measured).
105
105
  */
106
106
  function gitOnce(root, args, kind, opts = {}) {
107
- if (gitRootBlocked(root, kind)) {
107
+ // @implements A-SPEC-719.6 — `ignoreBlock` asks anyway (its own timeout is still recorded): the refresh worker's final
108
+ // HEAD read was skipped because the worker's own scan had timed out a git call, and every refresh ended `retry-at`.
109
+ if (!opts.ignoreBlock && gitRootBlocked(root, kind)) {
108
110
  const error = Object.assign(new Error(`git ${args[0] ?? ''}: not asked — a git child for this root timed out within the last minute`), { code: 'EBLOCKED' });
109
111
  return { pid: 0, output: [null, '', ''], stdout: '', stderr: '', status: null, signal: null, error };
110
112
  }
@@ -45,6 +45,11 @@ export declare const FRESHNESS_RETRY_MS: number;
45
45
  * 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
46
46
  */
47
47
  export declare const FRESHNESS_WORKER_MAX_MS: number;
48
+ /**
49
+ * @implements A-SPEC-719.4 — the worker ends itself this long after it starts: two minutes inside the cap, which counts
50
+ * from the earlier `startedAt`, so the lease never expires while its worker may still run.
51
+ */
52
+ export declare const FRESHNESS_WORKER_DEADLINE_MS: number;
48
53
  /**
49
54
  * A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
50
55
  * someone edits, so without an interval the graph would never refresh between commits — the former
@@ -68,12 +73,22 @@ export declare function requestRefresh(root: string, input: RefreshRequest): {
68
73
  spawn: boolean;
69
74
  receipt: FreshnessReceipt;
70
75
  };
76
+ /** @implements A-SPEC-719.5 — the head `generation`'s lease was taken for; undefined when that lease is not current. */
77
+ export declare function leaseHead(root: string, generation: string): string | null | undefined;
78
+ /** @implements A-SPEC-719.6 — the stored lease while it is `refreshing` and not expired at `now`, else null. */
79
+ export declare function leaseLive(root: string, now: Date): FreshnessReceipt | null;
71
80
  /**
72
81
  * True only while `generation` still holds the live lease in an existing root. A worker asks this
73
82
  * before each phase that writes, so a superseded or orphaned child stops instead of recreating
74
83
  * `.ax` under a root that was removed (A-SPEC-724).
75
84
  */
76
85
  export declare function ownsLease(root: string, generation: string): boolean;
86
+ /**
87
+ * @implements A-SPEC-719.4 — whether a worker for `generation` should end: its workspace is gone, or a READABLE receipt
88
+ * names another generation or a finished state. A missing or unreadable receipt is not an answer (a reader can meet
89
+ * another process's rename on Windows) — the caller asks again at its next poll, and the worker deadline still bounds it.
90
+ */
91
+ export declare function leaseSuperseded(root: string, generation: string): boolean;
77
92
  /**
78
93
  * @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
79
94
  * crashed one. Writes only while that generation still holds the `refreshing` lease.
@@ -33,17 +33,20 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.FRESHNESS_REREFRESH_MS = exports.FRESHNESS_WORKER_MAX_MS = exports.FRESHNESS_RETRY_MS = exports.FRESHNESS_LEASE_MS = exports.FRESHNESS_RECEIPT_FILE = exports.REFRESH_FAILURE_REASON_MAX = void 0;
36
+ exports.FRESHNESS_REREFRESH_MS = exports.FRESHNESS_WORKER_DEADLINE_MS = exports.FRESHNESS_WORKER_MAX_MS = exports.FRESHNESS_RETRY_MS = exports.FRESHNESS_LEASE_MS = exports.FRESHNESS_RECEIPT_FILE = exports.REFRESH_FAILURE_REASON_MAX = void 0;
37
37
  exports.intakeUsable = intakeUsable;
38
38
  exports.lexicalOnly = lexicalOnly;
39
39
  exports.readFreshnessReceipt = readFreshnessReceipt;
40
40
  exports.requestRefresh = requestRefresh;
41
+ exports.leaseHead = leaseHead;
42
+ exports.leaseLive = leaseLive;
41
43
  exports.ownsLease = ownsLease;
44
+ exports.leaseSuperseded = leaseSuperseded;
42
45
  exports.recordLeaseWorker = recordLeaseWorker;
43
46
  exports.completeRefresh = completeRefresh;
44
47
  exports.workspaceIdFor = workspaceIdFor;
45
48
  // @implements A-SPEC-719, A-SPEC-768.4
46
- // @implements A-SPEC-719.1
49
+ // @implements A-SPEC-719.1, A-SPEC-719.4, A-SPEC-719.5, A-SPEC-719.6
47
50
  /**
48
51
  * The durable source of truth for refresh work. A receipt names the workspace and
49
52
  * commit it describes, so an old detached worker cannot make a newer tree look
@@ -66,6 +69,11 @@ exports.FRESHNESS_RETRY_MS = 30 * 1000;
66
69
  * 300–433). A live worker now keeps the lease up to this cap, and ends itself when it reaches it.
67
70
  */
68
71
  exports.FRESHNESS_WORKER_MAX_MS = 30 * 60 * 1000;
72
+ /**
73
+ * @implements A-SPEC-719.4 — the worker ends itself this long after it starts: two minutes inside the cap, which counts
74
+ * from the earlier `startedAt`, so the lease never expires while its worker may still run.
75
+ */
76
+ exports.FRESHNESS_WORKER_DEADLINE_MS = exports.FRESHNESS_WORKER_MAX_MS - 2 * 60 * 1000;
69
77
  /**
70
78
  * A usable terminal receipt coalesces for its HEAD only this long. HEAD alone does not move while
71
79
  * someone edits, so without an interval the graph would never refresh between commits — the former
@@ -159,11 +167,18 @@ function expired(receipt, now) {
159
167
  if (!Number.isFinite(started))
160
168
  return true;
161
169
  const age = now.getTime() - started;
162
- if (age >= exports.FRESHNESS_WORKER_MAX_MS)
170
+ // @implements A-SPEC-719.5 — capped both ways: a lease stamped 30 minutes ahead (clock skew, a foreign pid from a
171
+ // shared VM) is as spent as one 30 minutes old, whatever its pid says.
172
+ if (Math.abs(age) >= exports.FRESHNESS_WORKER_MAX_MS)
163
173
  return true;
164
174
  // @implements A-SPEC-719.1 — a running worker keeps its lease; a crashed one frees it after the short lease.
165
175
  if (receipt.pid !== undefined && processAlive(receipt.pid))
166
176
  return false;
177
+ // @implements A-SPEC-719.4 — a lease stamped in the future (a clock step, a workspace shared with a VM) never ages;
178
+ // once its named worker is gone, more than one short lease ahead is as dead as one short lease behind. Without a
179
+ // pid nothing says the worker is gone, so the former rule stands.
180
+ if (receipt.pid !== undefined && age <= -exports.FRESHNESS_LEASE_MS)
181
+ return true;
167
182
  return age >= exports.FRESHNESS_LEASE_MS;
168
183
  }
169
184
  function stale(receipt) {
@@ -204,6 +219,16 @@ function requestRefresh(root, input) {
204
219
  writeReceipt(root, receipt);
205
220
  return { spawn: true, receipt };
206
221
  }
222
+ /** @implements A-SPEC-719.5 — the head `generation`'s lease was taken for; undefined when that lease is not current. */
223
+ function leaseHead(root, generation) {
224
+ const receipt = storedReceipt(root);
225
+ return receipt !== null && receipt.generation === generation && receipt.state === 'refreshing' ? receipt.head : undefined;
226
+ }
227
+ /** @implements A-SPEC-719.6 — the stored lease while it is `refreshing` and not expired at `now`, else null. */
228
+ function leaseLive(root, now) {
229
+ const receipt = storedReceipt(root);
230
+ return receipt !== null && receipt.state === 'refreshing' && !expired(receipt, now) ? receipt : null;
231
+ }
207
232
  /**
208
233
  * True only while `generation` still holds the live lease in an existing root. A worker asks this
209
234
  * before each phase that writes, so a superseded or orphaned child stops instead of recreating
@@ -213,6 +238,24 @@ function ownsLease(root, generation) {
213
238
  const receipt = storedReceipt(root);
214
239
  return receipt !== null && receipt.generation === generation && receipt.state === 'refreshing';
215
240
  }
241
+ /**
242
+ * @implements A-SPEC-719.4 — whether a worker for `generation` should end: its workspace is gone, or a READABLE receipt
243
+ * names another generation or a finished state. A missing or unreadable receipt is not an answer (a reader can meet
244
+ * another process's rename on Windows) — the caller asks again at its next poll, and the worker deadline still bounds it.
245
+ */
246
+ function leaseSuperseded(root, generation) {
247
+ try {
248
+ if (!fs.statSync(path.join(root, '.ax')).isDirectory())
249
+ return true;
250
+ }
251
+ catch {
252
+ return true;
253
+ }
254
+ const receipt = storedReceipt(root);
255
+ if (receipt === null)
256
+ return false;
257
+ return receipt.generation !== generation || receipt.state !== 'refreshing';
258
+ }
216
259
  /**
217
260
  * @implements A-SPEC-719.1 — name the worker that holds `generation`'s lease, so a live worker is not taken for a
218
261
  * crashed one. Writes only while that generation still holds the `refreshing` lease.