@holmes-lab/holmes-kit 0.35.15 → 0.35.17

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 (33) hide show
  1. package/CHANGELOG.md +50 -0
  2. package/README.md +4 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/guardrail/write-target.d.ts +18 -0
  5. package/dist/holmes/guardrail/write-target.js +136 -35
  6. package/dist/holmes/hooks/pre-tool-use.js +15 -10
  7. package/dist/holmes/hooks/rtm-refresh-child.d.ts +12 -2
  8. package/dist/holmes/hooks/rtm-refresh-child.js +26 -4
  9. package/dist/holmes/mcp/handlers/graph-operations.d.ts +1 -0
  10. package/dist/holmes/mcp/handlers/graph-operations.js +4 -4
  11. package/dist/holmes/mcp/handlers/maintenance-analysis.js +39 -17
  12. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +25 -0
  13. package/dist/holmes/mcp/handlers/operator-inspection.js +60 -1
  14. package/dist/holmes/mcp/handlers/test-execution.d.ts +7 -0
  15. package/dist/holmes/mcp/handlers/test-execution.js +9 -2
  16. package/dist/holmes/mcp/handlers.d.ts +9 -0
  17. package/dist/holmes/mcp/maintenance-analyze.d.ts +21 -0
  18. package/dist/holmes/mcp/maintenance-analyze.js +1 -0
  19. package/dist/holmes/mcp/operator-recovery.js +5 -2
  20. package/dist/holmes/refresh/freshness-coordinator.d.ts +9 -0
  21. package/dist/holmes/refresh/freshness-coordinator.js +14 -4
  22. package/dist/holmes/review/missing-imports.d.ts +2 -0
  23. package/dist/holmes/review/missing-imports.js +2 -0
  24. package/dist/holmes/review/removed-names.d.ts +32 -0
  25. package/dist/holmes/review/removed-names.js +110 -0
  26. package/dist/holmes/rtm/anchor-ids.d.ts +15 -0
  27. package/dist/holmes/rtm/anchor-ids.js +45 -0
  28. package/dist/holmes/rtm/test-scope.d.ts +12 -0
  29. package/dist/holmes/rtm/test-scope.js +29 -4
  30. package/package.json +1 -1
  31. package/playbooks/publish/PLAYBOOK.md +29 -6
  32. package/dist/holmes/guardrail/write-verb-word.d.ts +0 -13
  33. package/dist/holmes/guardrail/write-verb-word.js +0 -55
package/CHANGELOG.md CHANGED
@@ -5,6 +5,56 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [0.35.17] - 2026-10-11
9
+
10
+ ### Fixed
11
+
12
+ - **`approval_status` says what to do next and relays the operator's latest hold question** (A-SPEC-768). Measured
13
+ 2026-10-11 in the SWE-bench Sphinx 11510 comparison: a Codex worker read 58 `sealed: true` answers as "pending"
14
+ because the response carried no next action, and never saw the second question of a twice-held request because the
15
+ response reported the spec's seal only. The response now carries `request { id, state, question?, reason?, ts? }`
16
+ (pending / held / granted / consumed / denied / revoked, from the approval queue) and one `nextAction` sentence; the
17
+ pending-approval hint ends with one `Agent:` line beside the unchanged operator lines.
18
+ - **An `@implements` list joined by `;`, `|`, `&`, `/` or `and` is diagnosed, not silently truncated** (A-SPEC-768.1).
19
+ `test_run` returns `anchorDiagnostics [{ file, line, separator, dropped, hint }]` for test files whose anchor list the
20
+ comma grammar does not read; attribution itself is unchanged.
21
+ - **A Codex `apply_patch` update is applied chunk by chunk in file order, as the tool applies it** (A-SPEC-768.2). A
22
+ context line that recurs earlier in the file (`def run(self)`, eight times in the measured case) no longer makes the
23
+ patch "unreadable"; each chunk is sought at or after the previous one (exact, then white-space-loose), `@@ ctx`
24
+ headers are sought first, and a patch that genuinely does not apply is refused by a sentence naming the file and the
25
+ chunk instead of "file_path missing". Supersedes A-SPEC-163.3 rule 4.
26
+ - **A quoted or escaped glob character is not a spelling of the `.ax` store** (A-SPEC-768.3). `rg "… .* …" | … |
27
+ xargs sh -c '… "$0"'` was refused as a protected-path write because the `.*` of a quoted regex counted as a glob that
28
+ could expand to `.ax`; a shell never expands a quoted or escaped glob. `echo .* && sh -c …` stays refused.
29
+ - **The publish playbook proves the GitHub README and badge sync in the release report.** Measured 2026-10-11:
30
+ step 6 had said "sync the badge too" since 0.35.13, yet the GitHub `.ax/badges/traced.svg` still showed v0.27.0's
31
+ figure and the GitHub README stopped at v0.35.10 for six releases — a sentence nobody had to prove. The step now
32
+ requires three lines in the release report (remote sha before → after and re-read match for README and badge, or
33
+ the exact SKIP reason) and carries the one-loop command for both files.
34
+ - **The background refresh child publishes why a lane failed** (A-SPEC-768.4). The freshness receipt gains
35
+ `failure { stage, reason }` (reason bounded to 300 characters) and `refreshSemanticVectors` carries the embedder's
36
+ message as `detail`; a successful run writes no `failure`.
37
+
38
+ ## [0.35.16] - 2026-10-08
39
+
40
+ ### Added
41
+
42
+ - **`maintenance_analyze` names the unchanged files a change has broken** (A-SPEC-759.2). When `changedFiles` is
43
+ given and a changed TypeScript/JavaScript or Python file no longer defines a top-level name it defined at HEAD —
44
+ removed or renamed, and not written anywhere in the file any more — every unchanged file that imports the changed
45
+ file and still has that name as a word is reported under `impacts.removedNameUsers` as `{ file, imports, name }`.
46
+ A changed TypeScript/JavaScript file that was deleted names the files whose relative imports pointed at it.
47
+ Measured through the product function against every path each commit touched: 22 files named on a public
48
+ TypeScript repository and 21 on a public Python repository, all of them files the commit did change (precision
49
+ 1.000 on both), 8 of 8 on a third window. It fires rarely and unevenly: it recovers 7.4% of the files an
50
+ incomplete change set was missing on the Python repository and 2–2.5% on the TypeScript ones. The evidence is
51
+ deliberately coarse — imports the file, has the name as a word. In the same measurement following resolved call
52
+ edges from the removed symbol scored 0.46–1.00, removed member names 0.26–0.86 and any changed declaration head
53
+ 0.19–0.62; none of those is built. **What this does not do:** member names and changed signatures are not read;
54
+ a deleted Python module is not followed; a change already committed shows nothing; outside version control
55
+ nothing is named; a type checker reports the same breakage in TypeScript once it is run (Python has none).
56
+ Rankings, classification and every gate are unchanged.
57
+
8
58
  ## [0.35.15] - 2026-10-08
9
59
 
10
60
  ### Added
package/README.md CHANGED
@@ -9,8 +9,8 @@
9
9
  <!-- holmes-kit:attest:begin -->
10
10
  ![traced files](.ax/badges/traced.svg)
11
11
 
12
- **447/453** source files (98.6%) trace to an approved spec · **754/817** approved A-SPECs (92.2%) are anchored from code.
13
- Measured at `843876d688fe` (specs `sha256:5f2dfff7ced0`) — reproduce with `holmes-kit attest`.
12
+ **438/440** source files (99.5%) trace to an approved spec · **761/824** approved A-SPECs (92.3%) are anchored from code.
13
+ Measured at `70dcb37ccf6b` (specs `sha256:675042379d48`) — reproduce with `holmes-kit attest`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
@@ -23,6 +23,8 @@ Measured at `843876d688fe` (specs `sha256:5f2dfff7ced0`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - **An agent is told what to do after an approval, and a patch is judged the way the tool applies it** *(new in 0.35.17)*: five repairs measured on a Codex worker in a SWE-bench comparison. `approval_status` now carries `request { id, state, question?, reason?, ts? }` (pending / held / granted / consumed / denied / revoked, read from the approval queue, with the operator's LATEST hold question) and one `nextAction` sentence — a sealed spec says "stop polling", a held request relays the question; the pending-approval hint ends with an `Agent:` line beside the unchanged operator lines. `test_run` reports `anchorDiagnostics` for an `@implements` list joined by `;`, `|`, `&`, `/` or `and` (the comma grammar does not read them; attribution is unchanged, the omission is named). A Codex `apply_patch` update is applied chunk by chunk from the previous chunk's position, as the tool does, so a context line that recurs earlier in the file no longer makes it "unreadable", and a patch that does not apply is refused by a sentence naming the file and the chunk. A quoted or escaped glob (`rg ".*"`) is no longer read as a spelling of the `.ax` store (an unquoted `.*` still is). The background refresh child records `failure { stage, reason }` on its freshness receipt instead of failing silently.
27
+ - **The analysis names the unchanged files a change has broken** *(new in 0.35.16)*: with `changedFiles` given, `maintenance_analyze` reports under `impacts.removedNameUsers` every unchanged file that imports a changed file and still uses a top-level name that file no longer defines (removed or renamed), and the files still importing a deleted TypeScript/JavaScript file. Deterministic and read-only; TypeScript/JavaScript and Python. Measured on public repositories: every file named was one the commit did change (22 of 22, 21 of 21). It fires rarely — 2–7% of the files an incomplete change set was missing. Member names and changed signatures are not read.
26
28
  - **The analysis names the file a change still has to create** *(new in 0.35.15)*: with `changedFiles` given, `maintenance_analyze` reports under `impacts.missingNewFiles` every relative import a changed TypeScript/JavaScript file newly introduces that resolves to nothing — the importing file, the specifier and the candidate paths. Deterministic and read-only. On two unseen windows of a public TypeScript monorepo every naming was a file the change did create (precision 1.000), covering 78–86% of the not-yet-existing files an incomplete change set was missing. Only uncommitted changes in a git repository; other languages, bare package names and path aliases are not read.
27
29
  - **ES-module TypeScript projects get their import graph** *(new in 0.35.14 — fix)*: a specifier written `./x.js` for a `x.ts` source (the ESM convention) now resolves, where it used to emit no edge at all — on a public TypeScript monorepo the graph went from 3 import edges to 4,628 of 6,854 import relations. Extensionless projects are unchanged. The cycle ratchet sees the same edges. Workspace package names are still unresolved, and the graded impact list does not yet use import edges.
28
30
  - **The impact list also knows where work is concentrating, and a release cannot ship a stale badge** *(new in 0.35.13)*: for a named change, `impacts.rankedImpact` is fused once more with each file's recency-weighted change frequency (same single `git log`; rows may carry `changeFrequency`). On 703 replayed changes neither corpus had been measured on before, recall among the ten rose 0.485 → 0.545 and 0.378 → 0.540 on a second, Python repository (both above the minimum detectable effect) and 0.521 → 0.551 / 0.419 → 0.477 here; precision rose detectably on all four windows. Stated plainly: against the modelled human engineer this project aims at (`docs/NORTH-STAR.md` — recall 0.67–0.78, precision ≈ 0.9) recall is still below the band and precision about a sixth. Separately, `npm publish` now refuses when the README shows the attest badge and `.ax/badges/traced.svg` was not re-measured since the previous release.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- f167b18a-muypcwqp
1
+ e14712a6-mv3zqox3
@@ -105,6 +105,24 @@ export declare function patchTargetsOf(text: string): PatchTarget[];
105
105
  * rule (below): its one place in the file, or no result.
106
106
  */
107
107
  export declare function applyPatchUpdate(original: string, hunk: string): string | null;
108
+ /**
109
+ * @implements A-SPEC-768.2
110
+ * The same application, with the reason when there is no result. Measured 2026-10-11 (SWE-bench Sphinx 11510, H0
111
+ * arm): a four-chunk Codex patch — two chunks context-only, one context line (`def run(self) -> list[Node]:`) occurring
112
+ * eight times earlier in the file — got no result under rule 4's "exactly once in the whole file", and the refusal
113
+ * said a file path was missing. The tool applies each chunk from where the previous one ended; so does this now:
114
+ * exact first, then white-space-loose, the FIRST match at or after the previous chunk. A `@@ ctx` header first seeks
115
+ * `ctx` the same way; an add-only chunk under such a header inserts directly after it. A kept line stays as the file
116
+ * has it. Supersedes A-SPEC-163.3 rule 4.
117
+ *
118
+ * @implements A-SPEC-163.3 (rules 1-3, 5-7: chunk grammar, ops, end-of-file, size), A-SPEC-163.4 — their rule 4 (one
119
+ * place in the whole file) is the part A-SPEC-768.2 replaces; everything else they pin still holds here.
120
+ */
121
+ export declare function applyPatchUpdateDetailed(original: string, hunk: string): {
122
+ result: string;
123
+ } | {
124
+ failure: string;
125
+ };
108
126
  /**
109
127
  * The file a raw path actually names.
110
128
  *
@@ -43,6 +43,7 @@ exports.patchAmbiguous = patchAmbiguous;
43
43
  exports.canonicalPatch = canonicalPatch;
44
44
  exports.patchTargetsOf = patchTargetsOf;
45
45
  exports.applyPatchUpdate = applyPatchUpdate;
46
+ exports.applyPatchUpdateDetailed = applyPatchUpdateDetailed;
46
47
  exports.pathFlavorFor = pathFlavorFor;
47
48
  exports.resolveTarget = resolveTarget;
48
49
  exports.isProtectedTarget = isProtectedTarget;
@@ -66,7 +67,7 @@ exports.joinShellText = joinShellText;
66
67
  exports.commandBases = commandBases;
67
68
  exports.shellSegments = shellSegments;
68
69
  exports.resolvesInside = resolvesInside;
69
- // @implements A-SPEC-728, A-SPEC-733, A-SPEC-163, A-SPEC-627
70
+ // @implements A-SPEC-728, A-SPEC-733, A-SPEC-163, A-SPEC-627, A-SPEC-768.2, A-SPEC-768.3
70
71
  const fs = __importStar(require("node:fs"));
71
72
  const path = __importStar(require("node:path"));
72
73
  const os = __importStar(require("node:os"));
@@ -367,6 +368,23 @@ function patchTargetsOf(text) {
367
368
  * rule (below): its one place in the file, or no result.
368
369
  */
369
370
  function applyPatchUpdate(original, hunk) {
371
+ const r = applyPatchUpdateDetailed(original, hunk);
372
+ return 'result' in r ? r.result : null;
373
+ }
374
+ /**
375
+ * @implements A-SPEC-768.2
376
+ * The same application, with the reason when there is no result. Measured 2026-10-11 (SWE-bench Sphinx 11510, H0
377
+ * arm): a four-chunk Codex patch — two chunks context-only, one context line (`def run(self) -> list[Node]:`) occurring
378
+ * eight times earlier in the file — got no result under rule 4's "exactly once in the whole file", and the refusal
379
+ * said a file path was missing. The tool applies each chunk from where the previous one ended; so does this now:
380
+ * exact first, then white-space-loose, the FIRST match at or after the previous chunk. A `@@ ctx` header first seeks
381
+ * `ctx` the same way; an add-only chunk under such a header inserts directly after it. A kept line stays as the file
382
+ * has it. Supersedes A-SPEC-163.3 rule 4.
383
+ *
384
+ * @implements A-SPEC-163.3 (rules 1-3, 5-7: chunk grammar, ops, end-of-file, size), A-SPEC-163.4 — their rule 4 (one
385
+ * place in the whole file) is the part A-SPEC-768.2 replaces; everything else they pin still holds here.
386
+ */
387
+ function applyPatchUpdateDetailed(original, hunk) {
370
388
  const endsWithNewline = original.endsWith('\n');
371
389
  const lines = original.split('\n');
372
390
  if (endsWithNewline)
@@ -396,17 +414,38 @@ function applyPatchUpdate(original, hunk) {
396
414
  else if (head === ' ' || head === '-' || head === '+')
397
415
  current.ops.push({ kind: head, text: line.slice(1) });
398
416
  else
399
- return null;
417
+ return { failure: `chunk ${chunks.length}: a line is not a patch line` };
400
418
  }
401
- // @implements A-SPEC-163.3 (rule 4) — a chunk is applied only where its old text is found exactly once in the whole
402
- // file, compared with surrounding white space ignored (the loosest comparison any parser uses), and in file order.
403
- // Then exact-first, `@@` seeking and end-of-file anchoring all choose the same place, so the result does not depend
404
- // on which parser applies it. No old text (an add-only chunk), none found, or two found: no one result.
405
419
  // The loose reading of each file line is computed once and spliced beside `lines`: per chunk it would be
406
420
  // chunks x lines regex passes inside a hook with a deadline.
407
421
  const loose = lines.map(patchLoose);
422
+ // The first index at or after `from` where `exact` matches the file, else where `looseOld` matches, else -1.
423
+ const seekFrom = (from, exact, looseOld) => {
424
+ for (const [source, want] of [[lines, exact], [loose, looseOld]]) {
425
+ for (let i = from; i + want.length <= source.length; i++) {
426
+ let ok = true;
427
+ for (let j = 0; j < want.length; j++)
428
+ if (source[i + j] !== want[j]) {
429
+ ok = false;
430
+ break;
431
+ }
432
+ if (ok)
433
+ return i;
434
+ }
435
+ }
436
+ return -1;
437
+ };
408
438
  let pos = 0;
409
- for (const chunk of chunks) {
439
+ for (const [index, chunk] of chunks.entries()) {
440
+ const n = index + 1;
441
+ let from = pos;
442
+ if (chunk.seek !== null) {
443
+ const at = seekFrom(pos, [chunk.seek], [patchLoose(chunk.seek)]);
444
+ if (at === -1)
445
+ return { failure: `chunk ${n}: the @@ context line was not found at or after the previous chunk` };
446
+ from = at + 1;
447
+ pos = from;
448
+ }
410
449
  const blank = (o) => o.empty === true;
411
450
  const ops = chunk.ops.slice();
412
451
  while (ops.length > 0 && blank(ops[0]))
@@ -416,30 +455,18 @@ function applyPatchUpdate(original, hunk) {
416
455
  if (ops.length === 0)
417
456
  continue;
418
457
  const oldExact = ops.filter((o) => o.kind !== '+').map((o) => o.text);
419
- if (oldExact.length === 0)
420
- return null;
421
- const old = oldExact.map(patchLoose);
422
- let at = -1;
423
- for (let i = 0; i + old.length <= lines.length; i++) {
424
- let ok = true;
425
- for (let j = 0; j < old.length; j++)
426
- if (loose[i + j] !== old[j]) {
427
- ok = false;
428
- break;
429
- }
430
- if (!ok)
431
- continue;
432
- if (at !== -1)
433
- return null;
434
- at = i;
435
- }
436
- if (at === -1 || at < pos)
437
- return null;
438
- // @implements A-SPEC-163.4 (rule 4) — the one loose place must also be an exact one: then the lines the patch
439
- // keeps are the same text in the file and in the patch, whichever of the two a tool writes back.
440
- for (let j = 0; j < oldExact.length; j++)
441
- if (lines[at + j] !== oldExact[j])
442
- return null;
458
+ if (oldExact.length === 0) {
459
+ if (chunk.seek === null)
460
+ return { failure: `chunk ${n}: adds lines with no place to add them` };
461
+ const added = ops.map((o) => o.text);
462
+ lines.splice(from, 0, ...added);
463
+ loose.splice(from, 0, ...added.map(patchLoose));
464
+ pos = from + added.length;
465
+ continue;
466
+ }
467
+ const at = seekFrom(from, oldExact, oldExact.map(patchLoose));
468
+ if (at === -1)
469
+ return { failure: `chunk ${n}: its old lines were not found at or after the previous chunk` };
443
470
  const replacement = [];
444
471
  let k = at;
445
472
  for (const op of ops) {
@@ -450,11 +477,11 @@ function applyPatchUpdate(original, hunk) {
450
477
  else
451
478
  replacement.push(op.text);
452
479
  }
453
- lines.splice(at, old.length, ...replacement);
454
- loose.splice(at, old.length, ...replacement.map(patchLoose));
480
+ lines.splice(at, oldExact.length, ...replacement);
481
+ loose.splice(at, oldExact.length, ...replacement.map(patchLoose));
455
482
  pos = at + replacement.length;
456
483
  }
457
- return lines.join('\n') + (endsWithNewline ? '\n' : '');
484
+ return { result: lines.join('\n') + (endsWithNewline ? '\n' : '') };
458
485
  }
459
486
  /**
460
487
  * The file a raw path actually names.
@@ -2105,8 +2132,82 @@ function mentionsAxSpelling(command) {
2105
2132
  axSpellingMemo = { command, answer };
2106
2133
  return answer;
2107
2134
  }
2135
+ /**
2136
+ * @implements A-SPEC-768.3
2137
+ * The command with every glob character the shell would NOT expand replaced by a literal placeholder: inside single
2138
+ * quotes (`$'…'` included), inside double quotes outside any `$(…)`/backtick substitution, or directly after an
2139
+ * unescaped backslash. Measured 2026-10-11 (SWE-bench Sphinx 11510, HG arm): the `.*` of a quoted regex was read as a
2140
+ * glob that could spell `.ax`, and with an uncertain base every segment of a read-only command was judged under the
2141
+ * store. A shell never globs a quoted or escaped character, so such a character cannot spell the store. An unterminated
2142
+ * quote leaves the text as written (conservative: the glob still counts).
2143
+ */
2144
+ function literalGlobsNeutralized(command) {
2145
+ const GLOB = /[*?[]/;
2146
+ let out = '';
2147
+ let quote = null;
2148
+ let subDepth = 0;
2149
+ let tick = false;
2150
+ for (let i = 0; i < command.length; i++) {
2151
+ const c = command[i];
2152
+ if (quote === "'") {
2153
+ out += c === "'" ? c : GLOB.test(c) ? '_' : c;
2154
+ if (c === "'")
2155
+ quote = null;
2156
+ continue;
2157
+ }
2158
+ if (c === '\\' && i + 1 < command.length) {
2159
+ const n = command[i + 1];
2160
+ out += quote === null && GLOB.test(n) ? '\\_' : c + n;
2161
+ i++;
2162
+ continue;
2163
+ }
2164
+ if (quote === '"') {
2165
+ if (c === '"' && subDepth === 0 && !tick) {
2166
+ quote = null;
2167
+ out += c;
2168
+ continue;
2169
+ }
2170
+ if (c === '$' && command[i + 1] === '(') {
2171
+ subDepth++;
2172
+ out += '$(';
2173
+ i++;
2174
+ continue;
2175
+ }
2176
+ if (c === ')' && subDepth > 0) {
2177
+ subDepth--;
2178
+ out += c;
2179
+ continue;
2180
+ }
2181
+ if (c === '`') {
2182
+ tick = !tick;
2183
+ out += c;
2184
+ continue;
2185
+ }
2186
+ out += subDepth === 0 && !tick && GLOB.test(c) ? '_' : c;
2187
+ continue;
2188
+ }
2189
+ if (c === "'") {
2190
+ quote = "'";
2191
+ out += c;
2192
+ continue;
2193
+ }
2194
+ if (c === '$' && command[i + 1] === "'") {
2195
+ quote = "'";
2196
+ out += "$'";
2197
+ i++;
2198
+ continue;
2199
+ }
2200
+ if (c === '"') {
2201
+ quote = '"';
2202
+ out += c;
2203
+ continue;
2204
+ }
2205
+ out += c;
2206
+ }
2207
+ return quote === null ? out : command;
2208
+ }
2108
2209
  function mentionsAxSpellingUncached(command) {
2109
- const decoded = command
2210
+ const decoded = literalGlobsNeutralized(command)
2110
2211
  .replace(/\\\n/g, '')
2111
2212
  .replace(/\\(?:x([0-9A-Fa-f]{1,2})|u([0-9A-Fa-f]{1,4})|U([0-9A-Fa-f]{1,8})|([0-7]{1,3}))/g, (_w, x, u, U, o) => {
2112
2213
  const cp = x !== undefined ? parseInt(x, 16) : u !== undefined ? parseInt(u, 16) : U !== undefined ? parseInt(U, 16) : parseInt(o ?? '0', 8);
@@ -48,7 +48,7 @@ exports.gateErrorDecision = gateErrorDecision;
48
48
  exports.wiredSpecsDir = wiredSpecsDir;
49
49
  exports.evaluateHook = evaluateHook;
50
50
  exports.readSpecsSync = readSpecsSync;
51
- // @implements A-SPEC-753.3, A-SPEC-134.2, A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753, A-SPEC-163.7
51
+ // @implements A-SPEC-753.3, A-SPEC-134.2, A-SPEC-278, A-SPEC-733, A-SPEC-734, A-SPEC-747, A-SPEC-477.1, A-SPEC-753, A-SPEC-163.7, A-SPEC-768.2
52
52
  const shell_argument_roles_1 = require("../guardrail/shell-argument-roles");
53
53
  // @implements A-SPEC-549.3 — the hook's deny reasons are English here; hooks-english.test.ts drives
54
54
  // evaluateHook in this file to prove it.
@@ -952,6 +952,9 @@ const PATCH_STRINGS_MAX = 256;
952
952
  /** A file an update hunk is applied to; a larger one is not judged by its result. */
953
953
  const PATCH_UPDATE_BYTES_MAX = 8 * 1024 * 1024;
954
954
  const PATCH_UNREADABLE_REASON = '[Holmes-Kit] cannot read the edit target path, so it cannot be judged (file_path missing or not a string)';
955
+ // @implements A-SPEC-768.2 — a patch the tool could not apply is told so, by file and chunk; measured 2026-10-11 (H0 arm)
956
+ // the path-missing sentence above was returned for a readable file whose patch simply did not apply.
957
+ const patchNotAppliedReason = (file, why) => `[Holmes-Kit] the patch does not apply to ${file} as it stands (${why}), so the result cannot be judged`;
955
958
  // @implements A-SPEC-163.7 — the refusal of A-SPEC-163.6 rule 3 in its own words (each refusal names its channel, A-SPEC-737).
956
959
  const SHELL_MARKED_REASON = '[Holmes-Kit] this shell command mentions the patch tool or a patch marker and is not one plain read, so it is not judged — '
957
960
  + 'search with the harness\'s own search tool, or run one plain grep, egrep, fgrep, rg, cat, head, tail, wc or ls with literal words (no pipe, redirect or substitution)';
@@ -1244,18 +1247,20 @@ function evaluateHook(input, specsDir, opts) {
1244
1247
  const workdir = isShell ? input.tool_input.workdir : undefined;
1245
1248
  const base = workdir === undefined ? outer : (path.isAbsolute(workdir) ? workdir : outer.replace(/\/+$/, '') + '/' + workdir);
1246
1249
  const at = (p) => (path.isAbsolute(p) ? p : base.replace(/\/+$/, '') + '/' + p);
1250
+ // @implements A-SPEC-768.2 — null: the file cannot be read (unreadable target); `failure`: readable, patch not applicable.
1247
1251
  const resultOf = (source, hunk) => {
1248
1252
  try {
1249
1253
  // @implements A-SPEC-163.3 (rule 7) — only a regular file is read: a FIFO or a device would hold the hook.
1250
1254
  const stat = fs.statSync(source);
1251
1255
  if (!stat.isFile() || stat.size > PATCH_UPDATE_BYTES_MAX)
1252
1256
  return null;
1253
- return (0, write_target_1.applyPatchUpdate)(fs.readFileSync(source, 'utf8'), hunk);
1257
+ return (0, write_target_1.applyPatchUpdateDetailed)(fs.readFileSync(source, 'utf8'), hunk);
1254
1258
  }
1255
1259
  catch {
1256
1260
  return null;
1257
1261
  }
1258
1262
  };
1263
+ const judged = (file, r) => r === null ? { deny: PATCH_UNREADABLE_REASON } : 'failure' in r ? { deny: patchNotAppliedReason(file, r.failure) } : { content: r.result };
1259
1264
  // @implements A-SPEC-163.3 (rule 1), A-SPEC-163.4 (rule 5) — two targets on one file have no one result: the tool
1260
1265
  // applies them in sequence, the gate reads the disk once. One file is one key whatever link or letter case names it.
1261
1266
  // (What a shell could rewrite is settled before this point: only the one quoted-heredoc form reaches here.)
@@ -1271,16 +1276,16 @@ function evaluateHook(input, specsDir, opts) {
1271
1276
  if (t.kind === 'add')
1272
1277
  content = t.content;
1273
1278
  else if (t.kind === 'update' && t.movedTo === undefined) {
1274
- const result = resultOf(at(t.path), t.hunk ?? '');
1275
- if (result === null)
1276
- return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
1277
- content = result;
1279
+ const j = judged(at(t.path), resultOf(at(t.path), t.hunk ?? ''));
1280
+ if ('deny' in j)
1281
+ return { permissionDecision: 'deny', permissionDecisionReason: j.deny };
1282
+ content = j.content;
1278
1283
  }
1279
1284
  else if (t.kind === 'move') {
1280
- const result = t.from === undefined ? null : resultOf(at(t.from), t.hunk ?? '');
1281
- if (result === null)
1282
- return { permissionDecision: 'deny', permissionDecisionReason: PATCH_UNREADABLE_REASON };
1283
- content = result;
1285
+ const j = judged(at(t.from ?? t.path), t.from === undefined ? null : resultOf(at(t.from), t.hunk ?? ''));
1286
+ if ('deny' in j)
1287
+ return { permissionDecision: 'deny', permissionDecisionReason: j.deny };
1288
+ content = j.content;
1284
1289
  }
1285
1290
  // Judged as a patch tool's write whichever tool carried the patch, so the shell branch below is not re-entered.
1286
1291
  const verdict = evaluateHook({ tool_name: 'apply_patch', tool_input: { file_path: at(t.path), ...(content === undefined ? {} : { content }) },
@@ -1,11 +1,16 @@
1
- import { FreshnessLane, FreshnessReceipt } from '../refresh/freshness-coordinator';
1
+ import { FreshnessLane, FreshnessReceipt, RefreshFailure } from '../refresh/freshness-coordinator';
2
+ /** The error as a bounded reason: its message (never a stack), at most REFRESH_FAILURE_REASON_MAX characters. */
3
+ export declare function failureReason(error: unknown): string;
2
4
  /** 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;
5
+ export declare function recordRefreshFailure(root: string, generation: string, head: string | null, now: Date, failure?: RefreshFailure): FreshnessReceipt | null;
4
6
  export interface RefreshChildDeps {
5
7
  head: (root: string) => string | null;
6
8
  refreshGraph: (root: string) => Promise<unknown>;
9
+ /** @implements A-SPEC-768.4 — a failed lane may carry `detail` (the embedder's message) beside its reason. */
7
10
  refreshSource: (root: string) => Promise<{
8
11
  lane: FreshnessLane;
12
+ reason?: string;
13
+ detail?: string;
9
14
  }>;
10
15
  refreshRequirement: (root: string) => Promise<{
11
16
  status: string;
@@ -16,6 +21,11 @@ export interface RefreshChildDeps {
16
21
  * so a superseded worker, or one whose root was removed, stops without writing (A-SPEC-724). Any
17
22
  * failure — synchronous module load included — is published as bounded retry for this generation
18
23
  * rather than left as a `refreshing` lease that only expiry can clear (A-SPEC-719).
24
+ *
25
+ * @implements A-SPEC-768.4 — and the receipt says WHY. Measured 2026-10-11 (SWE-bench Sphinx 11510, HG arm):
26
+ * generation 77968db7 recorded both semantic lanes `failed` while direct probes of the same endpoint returned HTTP
27
+ * 200; every error was swallowed here, so the cause was unknowable. The stage that threw and the error's message
28
+ * now ride the receipt; a source lane that returns `failed` carries the embedder's detail.
19
29
  */
20
30
  export declare function runRefreshChild(root: string, generation: string, deps: RefreshChildDeps): Promise<void>;
21
31
  /** The production phases: the scan/build machinery, loaded only inside the detached child. */
@@ -33,11 +33,13 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.failureReason = failureReason;
36
37
  exports.recordRefreshFailure = recordRefreshFailure;
37
38
  exports.runRefreshChild = runRefreshChild;
38
39
  exports.defaultRefreshChildDeps = defaultRefreshChildDeps;
39
40
  // @implements A-SPEC-719, A-SPEC-734
40
41
  // @implements A-SPEC-566.4
42
+ // @implements A-SPEC-768.4
41
43
  /**
42
44
  * The detached refresh child — the ONLY place this slice touches the scan/build machinery. Spawned
43
45
  * by `maybeSpawnRtmRefresh` (rtm-refresh.ts) outside any turn; nothing in the hook path imports
@@ -56,10 +58,17 @@ const currentHead = (root) => {
56
58
  return null;
57
59
  }
58
60
  };
61
+ // @implements A-SPEC-768.4
62
+ /** The error as a bounded reason: its message (never a stack), at most REFRESH_FAILURE_REASON_MAX characters. */
63
+ function failureReason(error) {
64
+ const message = error instanceof Error ? error.message : String(error);
65
+ return message.slice(0, freshness_coordinator_1.REFRESH_FAILURE_REASON_MAX);
66
+ }
59
67
  /** The detached worker must publish its own failure; the parent is intentionally non-blocking. */
60
- function recordRefreshFailure(root, generation, head, now) {
68
+ function recordRefreshFailure(root, generation, head, now, failure) {
61
69
  return (0, freshness_coordinator_1.completeRefresh)(root, generation, {
62
70
  graph: 'failed', sourceSemantic: 'failed', requirementSemantic: 'failed', head,
71
+ ...(failure ? { failure } : {}), // A-SPEC-768.4
63
72
  }, now);
64
73
  }
65
74
  /**
@@ -67,12 +76,18 @@ function recordRefreshFailure(root, generation, head, now) {
67
76
  * so a superseded worker, or one whose root was removed, stops without writing (A-SPEC-724). Any
68
77
  * failure — synchronous module load included — is published as bounded retry for this generation
69
78
  * rather than left as a `refreshing` lease that only expiry can clear (A-SPEC-719).
79
+ *
80
+ * @implements A-SPEC-768.4 — and the receipt says WHY. Measured 2026-10-11 (SWE-bench Sphinx 11510, HG arm):
81
+ * generation 77968db7 recorded both semantic lanes `failed` while direct probes of the same endpoint returned HTTP
82
+ * 200; every error was swallowed here, so the cause was unknowable. The stage that threw and the error's message
83
+ * now ride the receipt; a source lane that returns `failed` carries the embedder's detail.
70
84
  */
71
85
  async function runRefreshChild(root, generation, deps) {
72
86
  if (!fs.existsSync(path.join(root, '.ax')))
73
87
  return;
74
88
  if (!(0, freshness_coordinator_1.ownsLease)(root, generation))
75
89
  return; // spawned late behind a newer lease: not even the graph
90
+ let stage = 'graph';
76
91
  try {
77
92
  await deps.refreshGraph(root);
78
93
  // @implements A-SPEC-683 — the vectors ride the channel that already refreshes the graph.
@@ -80,15 +95,21 @@ async function runRefreshChild(root, generation, deps) {
80
95
  // stayed current.
81
96
  if (!(0, freshness_coordinator_1.ownsLease)(root, generation))
82
97
  return;
98
+ stage = 'source';
83
99
  const source = await deps.refreshSource(root);
84
100
  if (!(0, freshness_coordinator_1.ownsLease)(root, generation))
85
101
  return;
102
+ let failure;
103
+ if (source.lane === 'failed')
104
+ failure = { stage: 'source', reason: (source.detail ?? source.reason ?? 'failed').slice(0, freshness_coordinator_1.REFRESH_FAILURE_REASON_MAX) };
105
+ stage = 'requirement';
86
106
  let requirement;
87
107
  try {
88
108
  requirement = await deps.refreshRequirement(root);
89
109
  }
90
- catch {
110
+ catch (error) {
91
111
  requirement = { status: 'unavailable' };
112
+ failure ??= { stage: 'requirement', reason: failureReason(error) };
92
113
  }
93
114
  (0, freshness_coordinator_1.completeRefresh)(root, generation, {
94
115
  graph: 'current',
@@ -97,11 +118,12 @@ async function runRefreshChild(root, generation, deps) {
97
118
  : requirement.status === 'not-applicable' ? 'not-adopted'
98
119
  : requirement.status === 'suppressed' ? 'suppressed' : 'failed',
99
120
  head: deps.head(root),
121
+ ...(failure ? { failure } : {}),
100
122
  }, new Date());
101
123
  }
102
- catch {
124
+ catch (error) {
103
125
  try {
104
- recordRefreshFailure(root, generation, deps.head(root), new Date());
126
+ recordRefreshFailure(root, generation, deps.head(root), new Date(), { stage, reason: failureReason(error) });
105
127
  }
106
128
  catch { /* fail-soft */ }
107
129
  }
@@ -55,6 +55,7 @@ export type SourceSemanticRefreshOutcome = {
55
55
  } | {
56
56
  lane: 'failed';
57
57
  reason: 'unavailable' | 'failed';
58
+ detail?: string;
58
59
  };
59
60
  /**
60
61
  * @implements A-SPEC-478 — the semantic cache WARMING lives in explicit heavy operations, so the
@@ -184,11 +184,11 @@ async function refreshSemanticVectors(root, env = process.env, warm = warmSemant
184
184
  try {
185
185
  outcome = await warm(root, scanned);
186
186
  }
187
- catch {
188
- return { lane: 'failed', reason: 'failed' };
189
- }
187
+ catch (error) {
188
+ return { lane: 'failed', reason: 'failed', detail: error instanceof Error ? error.message : String(error) };
189
+ } // A-SPEC-768.4
190
190
  if (outcome.status !== 'discharged')
191
- return { lane: 'failed', reason: 'unavailable' };
191
+ return { lane: 'failed', reason: 'unavailable', detail: `warm status: ${outcome.status}` };
192
192
  // What LANDED, not what was attempted. Measured 2026-09-19 the warm answered `computed: 603`
193
193
  // while 26 vectors were never stored; a count of attempts reported as a success is the same
194
194
  // class of dishonesty as a tier that says PASS while covering nothing.
@@ -49,6 +49,7 @@ const test_evidence_1 = require("../../review/test-evidence");
49
49
  const temporal_prior_1 = require("../../review/temporal-prior");
50
50
  const co_change_1 = require("../../review/co-change");
51
51
  const missing_imports_1 = require("../../review/missing-imports");
52
+ const removed_names_1 = require("../../review/removed-names");
52
53
  const test_files_1 = require("../../cpg/test-files");
53
54
  const commit_text_1 = require("../../review/commit-text");
54
55
  const bundler_1 = require("../../context/bundler");
@@ -238,29 +239,49 @@ function createMaintenanceAnalysisHandlers(context) {
238
239
  // @implements A-SPEC-759 — the file the change still has to create: a relative import a changed
239
240
  // file newly introduces that resolves nowhere. The earlier text is HEAD's; a path absent at
240
241
  // HEAD is a new file (null), any other failure is unknown (undefined) and names nothing.
242
+ // @implements A-SPEC-759.2 — and the unchanged files the change has broken: they import a
243
+ // changed file and still use a top-level name it no longer defines. Both findings read each
244
+ // changed file's HEAD text at most once, through one memo and one bound.
241
245
  let missing = [];
246
+ let broken = [];
242
247
  if (head !== '' && (a.changedFiles?.length ?? 0) > 0) {
243
- try {
244
- const git = (args) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], { maxBuffer: bounded_io_1.GIT_MAX_BUFFER, timeout: 5000, encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] });
245
- let reads = 0;
246
- missing = (0, missing_imports_1.missingNewFiles)({
247
- scanned,
248
- changedFiles: a.changedFiles.filter((file) => typeof file === 'string'),
249
- priorText: (file) => {
250
- if (reads++ >= MISSING_NEW_FILES_PRIOR_READS)
251
- return undefined;
252
- try {
253
- return git(['show', `HEAD:${file}`]);
254
- }
255
- catch { /* absent at HEAD, or unreadable — told apart below */ }
248
+ const changed = a.changedFiles.filter((file) => typeof file === 'string');
249
+ const git = (args) => (0, node_child_process_1.execFileSync)('git', ['-C', root, ...args], { maxBuffer: bounded_io_1.GIT_MAX_BUFFER, timeout: 5000, encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] });
250
+ const priorMemo = new Map();
251
+ const priorText = (file) => {
252
+ if (priorMemo.has(file))
253
+ return priorMemo.get(file);
254
+ let text;
255
+ if (priorMemo.size < MISSING_NEW_FILES_PRIOR_READS) {
256
+ try {
257
+ text = git(['show', `HEAD:${file}`]);
258
+ }
259
+ catch {
260
+ // absent at HEAD (a new file), or unreadable — told apart here
256
261
  try {
257
- return git(['ls-tree', '--name-only', 'HEAD', '--', file]).trim() === '' ? null : undefined;
262
+ text = git(['ls-tree', '--name-only', 'HEAD', '--', file]).trim() === '' ? null : undefined;
258
263
  }
259
264
  catch {
260
- return undefined;
265
+ text = undefined;
261
266
  }
262
- },
263
- exists: (repoPath) => fs.existsSync(path.join(root, repoPath)),
267
+ }
268
+ }
269
+ priorMemo.set(file, text);
270
+ return text;
271
+ };
272
+ try {
273
+ missing = (0, missing_imports_1.missingNewFiles)({ scanned, changedFiles: changed, priorText, exists: (repoPath) => fs.existsSync(path.join(root, repoPath)) });
274
+ }
275
+ catch { /* no finding */ }
276
+ try {
277
+ broken = (0, removed_names_1.removedNameUsers)({
278
+ scanned, changedFiles: changed, priorText,
279
+ currentText: (file) => { try {
280
+ return fs.readFileSync(path.join(root, file), 'utf8');
281
+ }
282
+ catch {
283
+ return null;
284
+ } },
264
285
  });
265
286
  }
266
287
  catch { /* no finding */ }
@@ -271,6 +292,7 @@ function createMaintenanceAnalysisHandlers(context) {
271
292
  ...(coChange !== undefined ? { coChange } : {}),
272
293
  ...(changeFrequency !== undefined ? { changeFrequency } : {}),
273
294
  ...(missing.length > 0 ? { missingNewFiles: missing } : {}),
295
+ ...(broken.length > 0 ? { removedNameUsers: broken } : {}),
274
296
  coverage: { ...common.coverage, historyStatus },
275
297
  history,
276
298
  changePrior,