@hone-ai/cli 1.39.0 → 1.41.0

package/lib/call-sites.js

@@ -73,9 +73,22 @@ const SCOPE = 'tracked-repo';
 
 // The caps. server/src/services/call-sites.js accepts at least these (pinned by a cross-package test): a server
 // that took less would quietly turn a complete list into an incomplete one.
-const MAX_SYMBOLS = 6;
-/** Secret-looking names are reported, not searched; they take no slot of the 6 but are reported up to this many. */
+// HC-GF-385: 16, up from 6. Six slots spent on string keys (`step_0b`, `config`) left the functions a story changes
+// NOT SEARCHED and hard-stopped step_1 four times on one story. The wire budget is held by MAX_TOTAL_HITS, not by
+// the symbol count: a symbol past it is sent as its per-file list (FILES ONLY), so 16 costs what 6 did.
+const MAX_SYMBOLS = 16;
+/** Secret-looking names are reported, not searched; they take no slot of the 16 but are reported up to this many. */
 const MAX_REFUSED = 2;
+/**
+ * HC-GF-385: the hit lines ALL symbols together may send, spent in rank order: today's 6 x 40, so the 448 KiB
+ * per-story wire budget (server/src/lib/batch-body-limit.js) and its test keep their meaning. A symbol reached after
+ * it is spent sends `hits: []` plus its per-file list.
+ */
+const MAX_TOTAL_HITS = 240;
+/** HC-GF-385: the definition probe ranks at most this many candidates, best-ranked first. */
+const MAX_PROBE_CANDIDATES = 32;
+/** HC-GF-385: the probe's own share of TOTAL_BUDGET_MS; past it the story's own order is kept, and said. */
+const PROBE_TIMEOUT_MS = 8_000;
 /** Past MAX_HITS_PER_SYMBOL a symbol also carries a per-file list (path + hit count), up to this many files... */
 const MAX_FILE_LIST_FILES = 300;
 /** ...and all the symbols' file lists together stay under this many bytes of JSON (server/src/lib/batch-body-limit.js budgets it). */
@@ -97,7 +110,38 @@ const PROSE_EXTENSIONS = Object.freeze(['md', 'mdx', 'markdown', 'rst', 'adoc',
 
 // ── Choosing the symbols ────────────────────────────────────────────────────────────────────────
 
-const BACKTICKED = /`([^`\n]{2,200})`/g;
+// Backticked spans are PAIRED first, by the CommonMark rule, and the 2-to-200 rule is applied to each paired span afterwards.
+// A bound INSIDE a regex decides which backticks pair: at `x`, and `foo` the opening backtick of `x` cannot start a 2-character
+// match, so its closing one does, the "span" is `, and`, and `foo` is lost (measured 2026-10-10 over the roadmap rows: 68 of 939
+// extracted a wrong span set). A plain /`([^`\n]*)`/ fixed that and made the next one: after a run of TWO OR MORE backticks
+// (a ``double`` span, an inline ```fence) the pairing never recovered for the rest of the line, and 7 rows lost symbols the old
+// pattern found. The rule that has no such failure is the one Markdown itself uses: a run of N backticks opens a span that the
+// next run of EXACTLY N backticks closes, and a run with no such closer is literal text. Per line (a span does not cross a
+// newline here, as before). Linear: the next run of the same length is computed once per run, not searched for.
+// The same defect as BACKTICKED_RE in bundle-paths.js (HC-GF-188-followup-2), which has the first fix only.
+function backtickedSpans(text) {
+  const spans = [];
+  for (const line of String(text || '').split('\n')) {
+    if (!line.includes('`')) continue;
+    const runs = [];
+    for (const m of line.matchAll(/`+/g)) runs.push({ at: m.index, len: m[0].length });
+    const nextSame = new Array(runs.length).fill(-1);
+    const lastOfLen = new Map();
+    for (let i = runs.length - 1; i >= 0; i--) {
+      nextSame[i] = lastOfLen.has(runs[i].len) ? lastOfLen.get(runs[i].len) : -1;
+      lastOfLen.set(runs[i].len, i);
+    }
+    for (let i = 0; i < runs.length; i++) {
+      const j = nextSame[i];
+      if (j < 0) continue; // no closer of this length: the run is literal text
+      let span = line.slice(runs[i].at + runs[i].len, runs[j].at);
+      if (span.length > 2 && span.startsWith(' ') && span.endsWith(' ') && /[^ ]/.test(span)) span = span.slice(1, -1); // CommonMark: one space each side
+      spans.push(span);
+      i = j; // resume after the closer; the runs between are inside the span
+    }
+  }
+  return spans;
+}
 // One identifier, optionally qualified (`a.b`, `A::b`, `a->b`, `A#b`) and optionally called (`f()`, `f(x)`). The LAST
 // segment is the symbol: `this.ensureConnected` is a reference to `ensureConnected` wherever it is called from.
 // Group 1 is the qualifier (empty when there is none), 2 the name, 3 the call's parentheses (undefined when not called).
@@ -158,25 +202,129 @@ function symbolOfSpan(span) {
  * @returns {{symbols: string[], omitted: string[], omittedTotal: number, refused: string[]}}
  */
 function pickSymbols(storyText, { max = MAX_SYMBOLS } = {}) {
+  const { ranked, refusedAll } = rankCandidates(storyText);
+  return sliceRanked(ranked.map((c) => c.name), refusedAll, max);
+}
+
+/**
+ * Every candidate the story names, in the story's order (explicitly written first, then by how often it is named,
+ * ties in the order first named), with the facts that order was made from. Secret-looking names are split off.
+ * Synchronous and text-only: `pickSymbols` keeps that contract for callers this file cannot see (HC-GF-385).
+ * @returns {{ranked: Array<{name: string, explicit: boolean, count: number}>, refusedAll: string[]}}
+ */
+function rankCandidates(storyText) {
   const counts = new Map();
   const explicitNames = new Set();
-  for (const m of String(storyText || '').matchAll(BACKTICKED)) {
-    const sym = symbolOfSpan(m[1]);
+  for (const span of backtickedSpans(storyText)) {
+    if (span.length < 2 || span.length > 200) continue; // the length rule, after pairing
+    const sym = symbolOfSpan(span);
     if (!sym) continue;
     counts.set(sym.name, (counts.get(sym.name) || 0) + 1);
     if (sym.explicit) explicitNames.add(sym.name);
   }
   // Array.prototype.sort is stable (ES2019), and a Map iterates in insertion order: ties keep the order the story first names them.
   const all = [...counts.keys()].sort((a, b) => (explicitNames.has(b) - explicitNames.has(a)) || (counts.get(b) - counts.get(a)));
-  const refusedAll = all.filter((n) => SECRET_NAME.test(n));
-  const ranked = all.filter((n) => !SECRET_NAME.test(n));
-  const refused = refusedAll.slice(0, MAX_REFUSED);
-  const beyond = [...ranked.slice(max), ...refusedAll.slice(MAX_REFUSED)];
   return {
-    symbols: ranked.slice(0, max),
+    ranked: all.filter((n) => !SECRET_NAME.test(n)).map((name) => ({ name, explicit: explicitNames.has(name), count: counts.get(name) })),
+    refusedAll: all.filter((n) => SECRET_NAME.test(n)),
+  };
+}
+
+/** The first `max` names are searched; the rest, and the refused names past MAX_REFUSED, are reported as omitted. */
+function sliceRanked(names, refusedAll, max) {
+  const beyond = [...names.slice(max), ...refusedAll.slice(MAX_REFUSED)];
+  return {
+    symbols: names.slice(0, max),
     omitted: beyond.slice(0, MAX_OMITTED_NAMES),
     omittedTotal: beyond.length,
-    refused,
+    refused: refusedAll.slice(0, MAX_REFUSED),
+  };
+}
+
+// ── Ranking by definition (HC-GF-385) ───────────────────────────────────────────────────────────
+
+/** Files whose matches never define code: documentation, and data formats (an object or YAML key is not a symbol). */
+const DATA_EXTENSIONS = Object.freeze(['json', 'jsonc', 'json5', 'yaml', 'yml', 'toml', 'lock', 'csv', 'tsv', 'xml', 'ini', 'env', 'properties']);
+/** A word before `name(` that makes it a call or an expression, never a C-family definition. */
+const NOT_A_RETURN_TYPE = new Set(['return', 'await', 'new', 'throw', 'yield', 'else', 'case', 'typeof', 'delete', 'void', 'in', 'of', 'do',
+  'if', 'while', 'for', 'switch', 'catch', 'and', 'or', 'not', 'is', 'as', 'echo', 'print', 'puts', 'go', 'defer', 'export', 'default']);
+
+/**
+ * How strongly one line defines `name`: 2 for a function, method, class or type; 1 for a top-level or exported
+ * constant or variable; 0 for anything else (a call, a key, a mention). Language-neutral patterns, covering
+ * JavaScript and TypeScript, Python, Go, Ruby, Java and the C family, and `fn`/`fun`/`func` (Rust, Kotlin, Swift).
+ * `name` is an identifier ([A-Za-z0-9_]), so it is safe inside a RegExp.
+ * @param {string} line
+ * @param {string} name
+ * @returns {0|1|2}
+ */
+function definitionTier(line, name) {
+  const n = `${name}(?![A-Za-z0-9_$])`;
+  const t = String(line);
+  // A keyword that introduces a definition: `function f`, `class C`, `def f`, `def self.f`, `func (r *T) f`, `fn f`, `fun f`.
+  if (new RegExp(`(?:^|[^A-Za-z0-9_$.])(?:function\\*?|class|def|func|fn|fun|interface|enum|struct|trait|type|module|record|protocol)\\s+(?:self\\.)?(?:\\([^)]*\\)\\s*)?${n}`).test(t)) return 2;
+  // A function value bound at top level or exported: `export const f = async (a) =>`, `const f = function`.
+  if (new RegExp(`^(?:export\\s+)?(?:const|let|var)\\s+${n}\\s*=\\s*(?:async\\b\\s*)?(?:function\\b|\\([^)]*\\)\\s*=>|[A-Za-z_$][A-Za-z0-9_$]*\\s*=>)`).test(t)) return 2;
+  // A method, in a class body or an object literal: `  async f(a, b) {`, `  static get f() {`.
+  if (new RegExp(`^\\s*(?:(?:static|async|get|set|public|private|protected|readonly|override|abstract|final)\\s+)*${n}\\s*\\([^)]*\\)\\s*(?::\\s*[^={;]+)?\\{`).test(t)) return 2;
+  // A C-family signature: one or more type words, then `name(`, and no `;` (a prototype or a call statement).
+  const sig = new RegExp(`^\\s*((?:[A-Za-z_][A-Za-z0-9_<>\\[\\],:*&?]*\\s+)+)\\*?${n}\\s*\\([^;]*$`).exec(t);
+  if (sig) {
+    const words = sig[1].trim().split(/\s+/);
+    if (!NOT_A_RETURN_TYPE.has(words[words.length - 1])) return 2;
+  }
+  // A top-level or exported binding of anything else: `const f =`, `export let f`, `module.exports.f =`, Go `var f`.
+  if (new RegExp(`^(?:export\\s+)?(?:const|let|var|val)\\s+${n}`).test(t)) return 1;
+  if (new RegExp(`^(?:module\\.)?exports\\.${n}\\s*=`).test(t)) return 1;
+  // Python and Ruby top-level assignment: `f = ...` at column 0, not `f == x`.
+  if (new RegExp(`^${n}\\s*=(?!=)`).test(t)) return 1;
+  return 0;
+}
+
+/**
+ * Rank candidates by whether the repository defines them, with ONE batched `git grep -F -w` over all of them.
+ * Functions, methods, classes and types come first, then top-level or exported constants, then names with no
+ * definition (string keys, config fields, words). Within a tier the story's own order holds. Any failure, timeout
+ * or output this cannot read keeps the story's order, and the note says so: a probe never empties the search.
+ * @param {Array<{name: string}>} ranked  the story's order
+ * @returns {Promise<{ranked: Array<{name: string}>, fallback: string|null, undefinedNames: string[]}>}
+ */
+async function rankByDefinition(ranked, { run, realPath }) {
+  if (ranked.length === 0) return { ranked, fallback: null, undefinedNames: [] };
+  const probed = ranked.slice(0, MAX_PROBE_CANDIDATES);
+  const argv = ['grep', '-n', '-z', '-w', '-F', '-I', '--no-color', '--no-recurse-submodules'];
+  for (const c of probed) argv.push('-e', c.name);
+  let r;
+  try { r = await run(argv, { timeoutMs: PROBE_TIMEOUT_MS }); } catch { r = { failure: 'the probe could not be run' }; }
+  const problem = grepProblem(r || {});
+  if (problem) return { ranked, fallback: `the definition probe gave no answer (${problem}), so the story's own order was used`, undefinedNames: [] };
+  const lines = r.status === 1 ? [] : parseGrepOutput(r.stdout);
+  if (lines === null) return { ranked, fallback: 'the definition probe printed output that could not be read, so the story\'s own order was used', undefinedNames: [] };
+
+  const tier = new Map(probed.map((c) => [c.name, 0]));
+  const kinds = new Map();
+  const wordRe = /[A-Za-z_$][A-Za-z0-9_$]*/g;
+  for (const hit of lines) {
+    let kind = kinds.get(hit.path);
+    if (kind === undefined) {
+      const ext = path.posix.extname(hit.path).slice(1).toLowerCase();
+      kind = DATA_EXTENSIONS.includes(ext) ? 'data' : classifyPath(hit.path, realPath);
+      kinds.set(hit.path, kind);
+    }
+    if (kind !== 'ok') continue; // documentation, data and withheld paths define nothing here
+    for (const w of new Set(String(hit.text).match(wordRe) || [])) {
+      if (!tier.has(w) || tier.get(w) === 2) continue;
+      const d = definitionTier(hit.text, w);
+      if (d > tier.get(w)) tier.set(w, d);
+    }
+  }
+  // Stable: within a tier the story's order is kept. Candidates past the probe cap keep their place after the probed.
+  const order = probed.map((c, i) => ({ c, i, t: tier.get(c.name) }))
+    .sort((a, b) => (b.t - a.t) || (a.i - b.i)).map((x) => x.c);
+  return {
+    ranked: [...order, ...ranked.slice(MAX_PROBE_CANDIDATES)],
+    fallback: null,
+    undefinedNames: probed.filter((c) => tier.get(c.name) === 0).map((c) => c.name),
   };
 }
 
@@ -288,7 +436,7 @@ function parseFileList(out) {
  *  - 'not_searched': no answer, and `reason` says why. Never to be read as "no callers".
  * `binary` is how many files match only when git's binary-file skip (-I) is off; they cannot be listed.
  */
-async function searchSymbol(symbol, { run, realPath }) {
+async function searchSymbol(symbol, { run, realPath, maxHits = MAX_HITS_PER_SYMBOL }) {
   // Defence in depth: pickSymbols only yields identifiers, but this is exported, and the symbol reaches an argv and a RegExp.
   if (typeof symbol !== 'string' || !/^[A-Za-z0-9_]+$/.test(symbol)) {
     return { symbol: String(symbol).slice(0, 80), status: 'not_searched', reason: 'not an identifier' };
@@ -323,7 +471,9 @@ async function searchSymbol(symbol, { run, realPath }) {
     else sendable.push(hit);
   }
   const total = sendable.length + withheld;
-  const hits = sendable.slice(0, MAX_HITS_PER_SYMBOL).map((h) => ({ path: h.path, line: h.line, text: lineText(h.text, symbol) }));
+  // HC-GF-385: `maxHits` is what is left of the story's MAX_TOTAL_HITS (0 once it is spent), never more than the per-symbol cap.
+  const cap = Math.max(0, Math.min(MAX_HITS_PER_SYMBOL, Number.isSafeInteger(maxHits) ? maxHits : MAX_HITS_PER_SYMBOL));
+  const hits = sendable.slice(0, cap).map((h) => ({ path: h.path, line: h.line, text: lineText(h.text, symbol) }));
   const perFile = new Map();
   for (const h of sendable) perFile.set(h.path, (perFile.get(h.path) || 0) + 1);
   const entry = {
@@ -336,7 +486,10 @@ async function searchSymbol(symbol, { run, realPath }) {
     binary,
     hits,
   };
-  if (sendable.length > MAX_HITS_PER_SYMBOL) {
+  // HC-GF-385: every searched symbol with a sendable hit carries its per-file list, not only one past the hit cap.
+  // A symbol cut by the total-hit budget needs it to be FILES ONLY, and a whole symbol whose hit lines the server's
+  // render budget drops needs it to stay an enumeration at file level.
+  if (sendable.length > 0) {
     const all = [...perFile].map(([p, n]) => ({ path: p, hits: n }));
     entry.file_list = all.slice(0, MAX_FILE_LIST_FILES);
     entry.file_list_complete = all.length <= MAX_FILE_LIST_FILES;
@@ -344,11 +497,17 @@ async function searchSymbol(symbol, { run, realPath }) {
   return entry;
 }
 
-/** Keep the symbols' file lists inside MAX_FILE_LIST_BYTES together; a list that is cut says so. */
+/**
+ * Keep the symbols' file lists inside MAX_FILE_LIST_BYTES together; a list that is cut says so.
+ * HC-GF-385: the bytes go first to the symbols whose hit lines were cut (by the per-symbol cap or the total-hit
+ * budget), in rank order, because for them the list IS the enumeration; then to the rest, in rank order. Spent
+ * in plain rank order, whole symbols at the top starved the FILES ONLY ones below them into INCOMPLETE.
+ */
 function fitFileLists(symbols) {
   let room = MAX_FILE_LIST_BYTES;
-  for (const s of symbols) {
-    if (!s.file_list) continue;
+  const cut = (s) => Array.isArray(s.hits) && Number.isSafeInteger(s.total) && s.hits.length < s.total - (s.withheld || 0);
+  const ordered = [...symbols.filter((s) => s.file_list && cut(s)), ...symbols.filter((s) => s.file_list && !cut(s))];
+  for (const s of ordered) {
     const kept = [];
     for (const f of s.file_list) {
       const size = Buffer.byteLength(JSON.stringify(f), 'utf8') + 1;
@@ -379,8 +538,9 @@ const warn = (text) => ({ level: 'warn', text });
  */
 async function collectCallSites({ cwd, storyText, run, realPath, now = Date.now, maxSymbols = MAX_SYMBOLS }) {
   const notes = [];
-  const picked = pickSymbols(storyText, { max: maxSymbols });
-  if (picked.symbols.length === 0 && picked.refused.length === 0) return { callSites: null, notes };
+  const { ranked: storyOrder, refusedAll } = rankCandidates(storyText);
+  // The early return comes BEFORE the probe: a story that names nothing searchable runs no git at all.
+  if (storyOrder.length === 0 && refusedAll.length === 0) return { callSites: null, notes };
 
   // From the repository's top level, wherever `hone` ran: `git grep` from a subdirectory searches only that subtree.
   let root = cwd;
@@ -389,17 +549,24 @@ async function collectCallSites({ cwd, storyText, run, realPath, now = Date.now,
     const dir = top.failure || top.status !== 0 ? '' : top.stdout.trim();
     if (dir) root = dir;
   }
-  const git = run || ((argv) => runGit(argv, { cwd: root }));
+  const git = run || ((argv, opts = {}) => runGit(argv, { cwd: root, ...opts }));
   const real = realPath || ((rel) => repoRealPath(root, rel));
   const commit = await headCommit(git);
-  const symbols = [];
+  // HC-GF-385: the clock starts before the probe, so the probe's time comes out of the same TOTAL_BUDGET_MS.
   const started = now();
+  // Rank BEFORE the slice and compute what was omitted AFTER it, or the functions never reach the slice.
+  const probe = await rankByDefinition(storyOrder, { run: git, realPath: real });
+  const picked = sliceRanked(probe.ranked.map((c) => c.name), refusedAll, maxSymbols);
+  const symbols = [];
+  let hitsLeft = MAX_TOTAL_HITS;
   for (const symbol of picked.symbols) {
     if (now() - started > TOTAL_BUDGET_MS) {
       symbols.push({ symbol, status: 'not_searched', reason: `the ${TOTAL_BUDGET_MS / 1000}s search budget for this story was spent on earlier symbols` });
       continue;
     }
-    symbols.push(await searchSymbol(symbol, { run: git, realPath: real }));
+    const entry = await searchSymbol(symbol, { run: git, realPath: real, maxHits: hitsLeft });
+    if (Array.isArray(entry.hits)) hitsLeft = Math.max(0, hitsLeft - entry.hits.length);
+    symbols.push(entry);
   }
   for (const symbol of picked.refused) symbols.push({ symbol, status: 'not_searched', reason: SECRET_REASON });
   fitFileLists(symbols);
@@ -413,12 +580,17 @@ async function collectCallSites({ cwd, storyText, run, realPath, now = Date.now,
     omitted: picked.omitted,
     omitted_total: picked.omittedTotal,
   };
-  notes.push(...describeCallSites(callSites));
+  if (probe.fallback) notes.push(warn(`  ⚠ call sites: ${probe.fallback}`));
+  const searchedUndefined = probe.undefinedNames.filter((n) => picked.symbols.includes(n));
+  if (!probe.fallback && searchedUndefined.length > 0) {
+    notes.push(info(`     no definition found for ${searchedUndefined.join(', ')} (ranked after defined code; it may be a key, a field, or one this story creates)`));
+  }
+  notes.push(...describeCallSites(callSites, { maxSymbols }));
   return { callSites, notes };
 }
 
 /** The operator's lines for a result: one info line per symbol that is whole, a warning for each that is not. */
-function describeCallSites(callSites) {
+function describeCallSites(callSites, { maxSymbols = MAX_SYMBOLS } = {}) {
   const notes = [];
   const where = callSites.commit ? `tracked files at ${callSites.commit.slice(0, 12)}` : 'tracked files (commit unknown)';
   notes.push(info(`  → call sites: searched ${callSites.symbols.length} symbol(s) the story names, in ${where}`));
@@ -437,7 +609,10 @@ function describeCallSites(callSites) {
       binary ? `${binary} binary file${binary === 1 ? '' : 's'} match and cannot be listed` : '',
     ].filter(Boolean).join('; ');
     const fileLevel = s.status === 'incomplete' && binary === 0 && s.file_list_complete === true && Array.isArray(s.file_list);
-    if (s.status === 'incomplete' && fileLevel) {
+    if (s.status === 'incomplete' && fileLevel && s.hits.length === 0) {
+      // HC-GF-385: reached after the total-hit budget was spent. The server renders it FILES ONLY.
+      notes.push(info(`     ${s.symbol}: FILES ONLY — ${listable} hits in ${s.files} file${s.files === 1 ? '' : 's'}; every file with a hit is named with its count, individual lines not sent (the ${MAX_TOTAL_HITS}-hit budget was spent on higher-ranked symbols)${s.withheld ? `; EXCEPT ${s.withheld} hit${s.withheld === 1 ? '' : 's'} in withheld paths the planner cannot see` : ''}${s.prose ? `; ${s.prose} more in documentation` : ''}`));
+    } else if (s.status === 'incomplete' && fileLevel) {
       notes.push(info(`     ${s.symbol}: COMPLETE AT FILE LEVEL — ${listable} hits in ${s.files} file${s.files === 1 ? '' : 's'}; the first ${s.hits.length} are listed and every file with a hit is named with its count${s.withheld ? `; EXCEPT ${s.withheld} hit${s.withheld === 1 ? '' : 's'} in withheld paths the planner cannot see` : ''}${s.prose ? `; ${s.prose} more in documentation` : ''}`));
     } else if (s.status === 'incomplete') {
       notes.push(warn(`  ⚠ call sites for ${s.symbol}: INCOMPLETE — ${s.hits.length} of ${listable} hits listed (cap ${MAX_HITS_PER_SYMBOL}${s.file_list ? `, ${s.file_list.length} of ${s.files} files named` : ''}); the planner cannot claim an enumeration${extra ? ` (${extra})` : ''}`));
@@ -454,16 +629,21 @@ function describeCallSites(callSites) {
   const omittedTotal = callSites.omitted_total || 0;
   if (omittedTotal > 0) {
     const shown = callSites.omitted.join(', ') + (omittedTotal > callSites.omitted.length ? ', …' : '');
-    notes.push(warn(`  ⚠ call sites: the story names ${omittedTotal} more compound identifier(s) beyond the ${MAX_SYMBOLS}-symbol cap — NOT SEARCHED: ${shown}`));
+    notes.push(warn(`  ⚠ call sites: the story names ${omittedTotal} more compound identifier(s) beyond the ${maxSymbols}-symbol cap — NOT SEARCHED: ${shown}`));
   }
   return notes;
 }
 
 module.exports = {
+  backtickedSpans,
   CALL_SITES_VERSION,
   SCOPE,
   MAX_SYMBOLS,
   MAX_REFUSED,
+  MAX_TOTAL_HITS,
+  MAX_PROBE_CANDIDATES,
+  PROBE_TIMEOUT_MS,
+  DATA_EXTENSIONS,
   MAX_FILE_LIST_FILES,
   MAX_FILE_LIST_BYTES,
   SECRET_NAME,
@@ -478,6 +658,9 @@ module.exports = {
   MAX_OUTPUT_BYTES,
   isCompoundIdentifier,
   pickSymbols,
+  rankCandidates,
+  definitionTier,
+  rankByDefinition,
   fitFileLists,
   runGit,
   parseGrepOutput,

package/lib/context-reserve.js

@@ -208,21 +208,24 @@ function batchIdFromQueueOutput(stdout) {
  * status, created_at, error_message), newest first.
  *  - `later`: a run of the story in this repository, created AFTER the paused one and not killed. A re-serve that
  *    queued but whose kill failed, or that died between the two, leaves exactly this and no marker.
- *  - `earlier`: a run of the story killed with `re-served as batch <id>` BEFORE this one, so this run is that
- *    re-serve (the loop was started on the new batch alone) and a second pause here is the second.
- *  - `unknown`: the paused run's creation time is not a date, so neither can be told.
- * @returns {{kind: 'later'|'earlier'|'unknown', runId?: string, batchId?: string}|null}
+ *  - `earlier`: a run of the story, older than this one, killed with `re-served as batch <id>` where <id> is the batch
+ *    THIS run is in (`batchId`): this run is that re-serve (the loop was started on the new batch alone), and a second
+ *    pause here is the second. A story re-served into some OTHER batch, however long ago, is history and not this
+ *    run's lineage: it neither blocks nor justifies anything (HC-GF-351-followup-1).
+ *  - `unknown`: the paused run's creation time is not a date or its batch id is not one, so neither can be told.
+ * @returns {{kind: 'later'|'earlier'|'unknown', runId?: string, batchId?: string, why?: string}|null}
  */
-function serveHistory(rows, { runId, storyId, repoName, since }) {
+function serveHistory(rows, { runId, storyId, repoName, since, batchId: ownBatch }) {
   const t0 = Date.parse(since);
-  if (!Number.isFinite(t0)) return { kind: 'unknown' };
+  if (!Number.isFinite(t0)) return { kind: 'unknown', why: 'its creation time is not known' };
+  if (!isBatchId(ownBatch)) return { kind: 'unknown', why: 'the batch it is in is not known' };
   for (const row of Array.isArray(rows) ? rows : []) {
     if (!row || row.id === runId || row.story_id !== storyId || row.repo_name !== repoName) continue;
     const t = Date.parse(row.created_at);
     if (!Number.isFinite(t)) continue;
     if (t > t0 && row.status !== 'killed') return { kind: 'later', runId: row.id };
-    const batchId = t < t0 ? reservedBatchOf({ status: row.status, errorMessage: row.error_message }) : null;
-    if (batchId) return { kind: 'earlier', runId: row.id, batchId };
+    const reserved = t < t0 ? reservedBatchOf({ status: row.status, errorMessage: row.error_message }) : null;
+    if (reserved && reserved === ownBatch) return { kind: 'earlier', runId: row.id, batchId: reserved };
   }
   return null;
 }

package/lib/judge-provider.js

@@ -16,6 +16,8 @@
  * the unshipped `scripts/` tree.
  */
 
+const { readAnthropicText } = require('./anthropic-response');
+
 /** Said by every command that used to default to GitHub Models, so the cause is one sentence. */
 const GH_MODELS_RETIRED =
   'GitHub Models (--provider gh-models), the free default, was retired by GitHub on 2026-07-30: '
@@ -38,25 +40,32 @@ function buildJudgeCallLLM(provider, { axios }) {
       return { error: 'ANTHROPIC_API_KEY required for --provider claude. Set it: export ANTHROPIC_API_KEY=sk-ant-...' };
     }
     // MODEL CHOICE (feedback_model_choice_cost_amplifier): the judge is NOT on the
-    // OPUS_AGENTS allowlist — paid mode uses Sonnet (`claude-sonnet-5`), never Opus.
+    // OPUS_AGENTS allowlist — paid mode uses Sonnet (`claude-sonnet-5-5`), never Opus.
+    //
+    // HC-GF-337f: Sonnet 5.5 answers HTTP 400 to `thinking: {type: 'disabled'}`. Thinking and effort are
+    // TWO sibling fields, never one: `thinking: {type: 'adaptive'}` and `output_config: {effort: 'low'}`
+    // (a `thinking` object with an `effort` key is wrong). Effort is sent because its default is `high`
+    // and a judge wants `low`. Thinking tokens share `max_tokens`, hence 8192. No `temperature`, `top_p`,
+    // `top_k` or `tool_choice` is sent, and that is load-bearing now: a non-default sampling value or a
+    // forced tool choice is a 400 on this model.
     const callLLM = async (systemPrompt, userPrompt) => {
       const { data } = await axios.post('https://api.anthropic.com/v1/messages', {
-        model: 'claude-sonnet-5',
-        thinking: { type: 'disabled' },
-        max_tokens: 2048,
+        model: 'claude-sonnet-5-5',
+        thinking: { type: 'adaptive' },
+        output_config: { effort: 'low' },
+        max_tokens: 8192,
         system: systemPrompt,
         messages: [{ role: 'user', content: userPrompt }],
       }, {
         headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
-        timeout: 60000,
+        timeout: 120000,
       });
-      const text = (data.content || []).find((b) => b?.type === 'text')?.text;
       // A provider that answered with nothing is a provider failure, not a failed criterion:
-      // returning '' here made every criterion read "could not parse response".
-      if (typeof text !== 'string' || !text.trim()) {
-        throw new Error(`the claude provider returned no text (stop_reason: ${data.stop_reason || 'unknown'})`);
-      }
-      return text;
+      // returning '' here made every criterion read "could not parse response". A refusal (HTTP 200,
+      // stop_reason "refusal") names its category so it is not read as a quota or parse problem.
+      const r = readAnthropicText(data, { label: 'the claude provider', allowPartial: true }); // a verdict cut off defaults to NO
+      if (!r.ok) throw new Error(r.message);
+      return r.text;
     };
     return { callLLM, provider: 'claude', paid: true };
   }

package/lib/operator-question.js

@@ -27,10 +27,15 @@
 // U+061C ARABIC LETTER MARK is the third bidi mark beside LRM/RLM (review round 3 F3). Written as
 // \u escapes: a literal bidi character in this source would reorder how THIS file reads.
 // eslint-disable-next-line no-control-regex -- the whole point is to match control chars.
-const TERMINAL_UNSAFE_RE = /[\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
-
+const TERMINAL_UNSAFE_RE = /[\x00-\x1f\x7f-\x9f\u00ad\u061c\u180e\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff\u{e0000}-\u{e007f}]/gu;
+// A line break or tab is a space, so two words do not join; the characters above draw nothing yet change what a reader sees
+// (zero-width, soft hyphen, BOM, the Unicode tag block); a lone surrogate is not a character a terminal or JSON can carry.
+// Mirrors server/src/services/architect-consult.js scrubForTerminal: the two packages cannot share code, and a test pins them equal.
 function scrub(text) {
-  return String(text == null ? '' : text).replace(TERMINAL_UNSAFE_RE, '');
+  return String(text == null ? '' : text)
+    .replace(/[\t\n\v\f\r\u0085\u2028\u2029]+/g, ' ')
+    .replace(TERMINAL_UNSAFE_RE, '')
+    .replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '\ufffd');
 }
 
 /**
@@ -91,4 +96,4 @@ function gateQuestionLines(status, stepKey) {
   ];
 }
 
-module.exports = { normalizeQuestion, questionLines, gateQuestionLines, countPhrase };
+module.exports = { normalizeQuestion, questionLines, gateQuestionLines, countPhrase, scrub };

package/lib/release-review-config.js

@@ -67,8 +67,9 @@ function resolveBaseRef(base) {
  * documentation later confirms the cap is TOTAL (input + output) instead
  * of input-only, drop this number AND `max_tokens` together.
  *
- * Anthropic Opus `claude-opus-4-8`: 1M context window (upgraded from
- * the legacy 4-20250514's 200K). The 100K char cap is well below the
+ * Anthropic Opus `claude-opus-5-5`: 1M context window (upgraded from
+ * the legacy 4-20250514's 200K; HC-GF-337f moved the id from claude-opus-4-8; the 1M figure is the
+ * Anthropic models table's context window for claude-opus-5-5, read 2026-10-10). The 100K char cap is well below the
  * model's headroom but kept conservative — the prompt + diff together
  * comfortably fit, and bumping the cap is a separate decision.
  *