@hone-ai/cli 1.34.0 → 1.35.1

package/lib/bundle-paths.js

@@ -32,7 +32,36 @@
  * Extensions mirror FILE_PATH_RE exactly. The trailing `\b` mirrors the
  * followup-13c fix so `.jsonl` is not truncated to `.js`.
  */
-const BARE_FILE_RE = /(?<![\w/.-])([a-zA-Z_][\w-]*\.(?:py|js|ts|jsx|tsx|go|rs|java|rb|sh|sql))\b(?::(\d+))?/g;
+// ── HC-GF-202: what counts as a file reference ───────────────────────────────
+// Widening this is deliberate and load-bearing: it decides what EVERY run
+// bundles. It was measured, not guessed — three live runs of a story whose whole
+// deliverable was a `Makefile` recipe bundled the Makefile zero times, because
+// every pattern here required an extension from CODE_EXT.
+//
+// CONFIG_EXT and EXTENSIONLESS are the files a build story actually names.
+// DOTFILES are listed explicitly rather than by a leading-dot rule, which would
+// match `.env` and every other secret-shaped name.
+// Markdown is deliberately absent: docs are not the source context an agent
+// needs to write code, and every story mentions a `.md` file.
+const CODE_EXT = 'py|js|ts|jsx|tsx|go|rs|java|rb|sh|sql';
+// `yml`, `yaml` and `json` are deliberately ABSENT. HC-019n-followup-12 excluded
+// them with a stated reason — bundling prose blows the context window — and a
+// regression pins `ops/vals.yml` as not-detected. HC-GF-202's row asks for YAML
+// config to be visible; that collides with a decision made for a measured cost,
+// and the row's own acceptance is the EXTENSIONLESS half. `json` is excluded on
+// the same logic plus a second: lockfiles are the largest files in most repos.
+// A story that genuinely needs one names it with --include-paths, which HC-GF-202
+// also repairs. Revisit only with a measurement of what it costs.
+const CONFIG_EXT = 'toml|cfg|ini|conf|mk';
+const FILE_EXT = `${CODE_EXT}|${CONFIG_EXT}`;
+// Case-sensitive on purpose: `Makefile` is a filename, `makefile approach` is prose.
+const EXTENSIONLESS = 'Makefile|Dockerfile|Containerfile|Gemfile|Rakefile|Procfile|Jenkinsfile|Vagrantfile|Justfile|Brewfile';
+const DOTFILES = '\\.(?:gitignore|dockerignore|gitattributes|gitmodules|editorconfig|npmrc|nvmrc)';
+
+const BARE_FILE_RE = new RegExp(
+  `(?<![\\w/.-])((?:[a-zA-Z_][\\w-]*\\.(?:${FILE_EXT})|(?:${EXTENSIONLESS})|(?:${DOTFILES})))\\b(?::(\\d+))?`,
+  'g',
+);
 
 /**
  * Extract bare filename references (no directory segment) with an optional
@@ -102,6 +131,60 @@ function windowAroundLine(content, line, radiusChars) {
   return { excerpt, startLine, endLine, totalLines: total };
 }
 
+/**
+ * A window over explicit line bounds, for merging two that intersect.
+ * `windowAroundLine` centres on a line with a CHAR radius; a merge needs the
+ * union of two LINE ranges instead. HC-GF-206.
+ */
+function windowBetweenLines(content, startLine, endLine) {
+  const all = String(content).split('\n');
+  const total = all.length;
+  const s = Math.max(1, Math.min(total, Number(startLine) || 1));
+  const e = Math.max(s, Math.min(total, Number(endLine) || s));
+  const excerpt = all.slice(s - 1, e).join('\n');
+  return { excerpt, startLine: s, endLine: e, totalLines: total };
+}
+
+/**
+ * Collapse candidate windows whose LINE RANGES intersect into their union.
+ *
+ * HC-GF-206: the near-duplicate collapse upstream compares ANCHOR distance
+ * (< 40 lines), but window width is set by `radius`, far larger at a realistic
+ * cap — so two anchors 50 lines apart pass that check and produce windows that
+ * overlap almost entirely. The budget then buys the same bytes twice while
+ * distant regions are dropped for want of room, which is the exact failure
+ * HC-GF-204 was written to prevent. Cap-dependent and perverse: radius grows
+ * with the budget, so a larger cap wastes proportionally more of it.
+ *
+ * Merge rather than drop: the second window usually extends past the first, so
+ * discarding it would lose real ground. The union keeps both and costs less
+ * than the two separately.
+ *
+ * The while-loop matters. Merging A and B can produce a range that now
+ * intersects C, accepted earlier; a single pass would leave that pair behind.
+ */
+function mergeIntersectingWindows(content, entries) {
+  const out = [];
+  for (const entry of entries) {
+    let cur = entry;
+    let i;
+    while ((i = out.findIndex((o) =>
+      cur.w.startLine <= o.w.endLine && o.w.startLine <= cur.w.endLine)) !== -1) {
+      const o = out.splice(i, 1)[0];
+      cur = {
+        w: windowBetweenLines(content,
+          Math.min(o.w.startLine, cur.w.startLine),
+          Math.max(o.w.endLine, cur.w.endLine)),
+        // Keep the earlier-listed (better-ranked) anchor as the region's label.
+        anchor: o.anchor != null ? o.anchor : cur.anchor,
+        line: o.line,
+      };
+    }
+    out.push(cur);
+  }
+  return out;
+}
+
 /**
  * Resolve a bare filename against the repo's tracked file list.
  *
@@ -136,6 +219,620 @@ function alreadyCovered(candidate, existing) {
   return false;
 }
 
+
+/**
+ * Full paths WITH an optional `:line` — HC-GF-188.
+ *
+ * The CLI's own FILE_PATH_RE ends at the extension, so a story writing
+ * `server/src/routes/_all.js:712` had its `:712` discarded and the windowing
+ * HC-019n-followup-27 built could never fire for it. A bare ref already carried its line
+ * (BARE_FILE_RE above captures one); a full path did not, and full paths are what stories
+ * normally write — so the capability fired on the rarer shape and never on the usual one.
+ *
+ * The path half of the pattern is UNCHANGED from the CLI's regex, deliberately. This decides
+ * what every run bundles, and widening it silently changes the context every agent receives.
+ * Only the optional `(?::(\d+))?` tail is new.
+ *
+ * @param {string} text
+ * @returns {Array<{path: string, line: number|null}>} order-preserving, de-duplicated by path
+ */
+// HC-GF-202: the first segment may now start with a dot (`.github/...`) and the
+// last may be extensionless (`scripts/Makefile`). `.github/.pipeline-config.yml`
+// drives every run and was invisible to this pattern.
+const PATH_REF_RE = new RegExp(
+  `(?<![\\w/])(\\.?[a-zA-Z_][\\w-]*\\/(?:[\\w.-]+\\/)*(?:[\\w.-]+\\.(?:${FILE_EXT})|(?:${EXTENSIONLESS})))\\b(?::(\\d+))?`,
+  'g',
+);
+
+function extractPathRefs(text) {
+  if (!text || typeof text !== 'string') return [];
+  const seen = new Set();
+  const out = [];
+  for (const m of text.matchAll(PATH_REF_RE)) {
+    if (seen.has(m[1])) continue;
+    seen.add(m[1]);
+    out.push({ path: m[1], line: m[2] ? Number(m[2]) : null });
+  }
+  return out;
+}
+
+/** Backticked spans in a story, longest first — the longest is the most specific anchor. */
+const BACKTICKED_RE = /`([^`\n]{3,200})`/g;
+
+/**
+ * The line of the first thing the STORY quoted that actually occurs in this file — HC-GF-188.
+ *
+ * A story names its target in two ways. `path:line` states it outright; more often the story
+ * quotes the code, as HC-GF-126 does — "`server/src/routes/_all.js` reports
+ * `Math.ceil((expiresMs - Date.now()) / 86400000)`". Both name the same region, and only the
+ * first was usable.
+ *
+ * RETURNS null RATHER THAN A DEFAULT. Falling back to line 1 would produce a confident window
+ * around the wrong region, which reads to every downstream agent exactly like a correct one —
+ * and the operator would be told the file was anchored. "Could not anchor" has to stay
+ * distinguishable from "anchored here".
+ *
+ * Candidates are tried longest-first: a quoted expression is a far stronger locator than a
+ * quoted identifier that may appear in a hundred places. Path-shaped and whitespace-only spans
+ * are skipped — a story always quotes the file's own path, and matching that would anchor on
+ * whatever line happened to mention it.
+ *
+ * @param {string} content  full file contents
+ * @param {string} storyText
+ * @returns {{line: number, anchor: string}|null}
+ */
+function anchorLineForStory(content, storyText) {
+  const text = String(content || '');
+  const story = String(storyText || '');
+  if (!text || !story) return null;
+
+  const candidates = [...story.matchAll(BACKTICKED_RE)]
+    .map((m) => m[1].trim())
+    .filter((c) => c.length >= 3
+      && !new RegExp(`^[\\w.\\-/]+\\.(?:${FILE_EXT})$`).test(c)
+      && !new RegExp(`^(?:${EXTENSIONLESS})$`).test(c))
+    .sort((a, b) => b.length - a.length);
+
+  for (const anchor of candidates) {
+    const at = definitionIndexOf(text, anchor);
+    if (at === -1) continue;
+    return { line: text.slice(0, at).split('\n').length, anchor };
+  }
+  return null;
+}
+
+/**
+ * Where a term is DEFINED, falling back to where it is first mentioned — HC-GF-203.
+ *
+ * `indexOf` alone was the whole bug. A term that names something appears once at its
+ * definition and many times in prose, comments and call sites, so the first occurrence is
+ * the least likely of those to be the one a story means — and the gap grows with the file.
+ * Measured 2026-09-20: `verify-patch` occurs 22 times in `cli/hone-cli.js`; the first is a
+ * comment at line 5744, the `.command(…)` definition is at 7849, and the 400-line window
+ * around the comment carried neither the command nor the call site the story named. The
+ * planner refused, correctly, and no flag could fix it.
+ *
+ * The fallback is the OLD behaviour on purpose: a term that is only ever mentioned still
+ * gets the operator a window near it, which beats none.
+ */
+function anchorSitesForStory(content, storyText, max = 6) {
+  // HC-GF-204: every region a story's terms point at, best-first. `anchorLineForStory`
+  // answers "where does this live"; a story also needs "where is it USED", and on run
+  // ad4a561f the planner had the definition and refused for want of the call sites.
+  const text = String(content || '');
+  const story = String(storyText || '');
+  if (!text || !story) return [];
+  const candidates = [...story.matchAll(BACKTICKED_RE)]
+    .map((m) => m[1].trim())
+    .filter((c) => c.length >= 3
+      && !new RegExp(`^[\\w.\\-/]+\\.(?:${FILE_EXT})$`).test(c)
+      && !new RegExp(`^(?:${EXTENSIONLESS})$`).test(c))
+    .sort((a, b) => b.length - a.length);
+
+  const seenLine = new Set();
+  const sites = [];
+  for (const anchor of candidates) {
+    const def = definitionIndexOf(text, anchor);
+    if (def === -1) continue;
+    const t = anchor.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const offsets = [def];
+    for (const m of text.matchAll(new RegExp(`(?<![\\w$])${t}(?![\\w$])`, 'g'))) offsets.push(m.index);
+    for (const off of offsets) {
+      const line = text.slice(0, off).split('\n').length;
+      // Collapse near-duplicates: two hits 20 lines apart share one window.
+      if ([...seenLine].some((l) => Math.abs(l - line) < 40)) continue;
+      seenLine.add(line);
+      sites.push({ line, anchor });
+      if (sites.length >= max) return sites;
+    }
+  }
+  return sites;
+}
+
+function definitionIndexOf(text, term) {
+  const t = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Ordered by how strongly each shape asserts "this is where it lives".
+  const DEFINITION_FORMS = [
+    `\\.command\\(\\s*['"\`]${t}\\b`,           // CLI command registration
+    `(?:async\\s+)?function\\s+${t}\\b`,        // function declaration
+    `class\\s+${t}\\b`,                           // class declaration
+    `(?:const|let|var)\\s+${t}\\s*=`,             // binding
+    `exports\\.${t}\\s*=`,                        // named export
+    `${t}\\s*[:=]\\s*(?:async\\s*)?(?:function|\\()`, // property holding a function
+  ];
+  for (const form of DEFINITION_FORMS) {
+    const m = new RegExp(form).exec(text);
+    if (m) return m.index;
+  }
+  return text.indexOf(term);
+}
+
+/**
+ * Decide what a bundled file should actually contain — HC-GF-188.
+ *
+ * One function so the DECISION is testable and mutable. Inline in the bundler it was three
+ * branches nobody could reach from a test, which is how the blind head-slice survived.
+ *
+ * `notice` is the operator's half and is the point of this story as much as the excerpt is. The
+ * run that exposed this printed `bundled 4 codebase file(s) … (35383 chars)` and nothing else,
+ * while the payload carried a truncation marker that only the AGENT could read. All three agents
+ * diagnosed the cut correctly and refused; the person watching had no idea it had happened.
+ *
+ * HC-GF-288: `lines` carries EVERY stated line for the file, best-first; `line` is the
+ * one-line form and is appended to it. One line per file could not express the operator's
+ * `--include-paths f.js:N` for a file the story had already cited as `f.js:M` — the CLI kept
+ * M, discarded N, and printed nothing. Each stated line is a floor, and one this cannot
+ * honour comes back in `unhonoured` so the caller can say which, and why.
+ *
+ * @param {{content: string, cap: number, line?: number|null, lines?: number[], storyText?: string, path?: string}} input
+ * @returns {{mode: 'full'|'window'|'truncate', content: string, notice: string|null, anchor?: string,
+ *   unhonoured: Array<{line: number, reason: 'past-eof'|'budget', totalLines: number}>}}
+ */
+function planFileExcerpt({ content, cap, line = null, lines = null, storyText = '', path: filePath = 'file' } = {}) {
+  const text = String(content || '');
+  const limit = Number(cap);
+  const totalLines = text.split('\n').length;
+  const requested = [...new Set([...(Array.isArray(lines) ? lines : []), line]
+    .map(Number).filter((n) => Number.isInteger(n) && n > 0))];
+  // A line past the end is not clamped to the last line: `windowAroundLine` would do exactly
+  // that, and a window at EOF presented as "centered on referenced line 9000" is a confident
+  // wrong region. It is dropped and reported instead.
+  const stated = requested.filter((n) => n <= totalLines);
+  const unhonoured = requested.filter((n) => n > totalLines)
+    .map((n) => ({ line: n, reason: 'past-eof', totalLines }));
+  if (text.length <= limit) return { mode: 'full', content: text, notice: null, unhonoured };
+
+  // An explicit line wins: the author stated it, the anchor is inferred from prose.
+  const hit = stated.length ? { line: stated[0], anchor: null } : anchorLineForStory(text, storyText);
+
+  if (hit) {
+    // The 800 is headroom for the marker text. Clamped: `cap` is a parameter now, and the
+    // inherited formula goes NEGATIVE below 800, which collapses the window to nothing — an
+    // empty excerpt presented as a successful anchor. A window that slightly overruns a very
+    // small cap is strictly better than one that shows nothing at the site it claims to show.
+    // HC-GF-204: a story's code sits in SEVERAL regions of a large file, so inferred
+    // anchors spread the budget across every region found — "one window that is merely
+    // the BEST region still leaves the planner refusing for want of the others".
+    //
+    // HC-GF-216: that sentence is true of an EXPLICIT line too, and treating "stated"
+    // as "sufficient" is what made `line` exclusive. Measured 2026-09-20 on run
+    // de47094f, server/src/services/orchestrator.js (218,011 chars, cap 25,000): with
+    // the explicit line, ONE window [1,281] carrying the declaration and NEITHER
+    // consumer; without it, FIVE windows [13,95] [3876,3938] [576,648] [1606,1735]
+    // [3768,3852] carrying the declaration at 64, the `EDITOR_SIDE_STEPS.includes`
+    // consumer at 1701 and the export at 3923. step_1 then refused for call sites the
+    // UN-hinted bundle would have supplied — naming the line made the bundle strictly
+    // worse, and the shortfall notice below is what tells operators to name it.
+    //
+    // So the stated line SEEDS the site list rather than replacing it: it is at index 0,
+    // hence budgeted first, and `mergeIntersectingWindows` unions it with any inferred
+    // window it overlaps. No sort, no priority field — array order already says it.
+    // HC-GF-288: every stated line seeds it, in the caller's order.
+    const inferred = anchorSitesForStory(text, storyText);
+    const sites = [...stated.map((l) => ({ line: l, anchor: null })), ...inferred];
+    const chosen = sites.length ? sites : [hit];
+    const why = (a, l) => (a ? `anchored on \`${a}\`` : `centered on referenced line ${l}`);
+    const header = (w, a, l) =>
+      `# [HC-019n-followup-27: windowed excerpt, lines ${w.startLine}-${w.endLine} of ${w.totalLines} `
+      + `(${why(a, l)}); you were NOT shown the whole file — emit an \`edit:\` block `
+      + `with a unique OLD anchor from this excerpt, NOT a whole-file \`file:\` block]\n`;
+    const footer = `\n# [end windowed excerpt of ${filePath}]`;
+    // Budget the MARKER too. Each window carries a header and a footer, and counting only
+    // the excerpt overran a 25,000 cap by 1,647 chars across six regions — measured. The cap
+    // is a promise to the caller about total size.
+    // HC-GF-288 review: at its REAL length. A flat 280 undercounted it — the header alone is
+    // 232 chars for `centered on referenced line N`, more for a long anchor, and the footer
+    // carries the path — so six windows of server/src/services/orchestrator.js came to
+    // 25,039 chars against a 25,000 cap once the radius stopped leaving slack to hide it.
+    // The +1 is the newline that joins windows.
+    const costOf = (e) => header(e.w, e.anchor, e.line).length + e.w.excerpt.length + footer.length + 1;
+    // The radius is sized before any window exists, so it prices the marker at its widest:
+    // the longest label among the sites, with line numbers at the file's own width.
+    const widest = { startLine: totalLines, endLine: totalLines, totalLines };
+    const markerCost = Math.max(...chosen.map((s) => header(widest, s.anchor, totalLines).length))
+      + footer.length + 1;
+    // HC-GF-288: the 800 covers ONE window's marker, and every further window brings its
+    // own. Sized from `limit - 800` alone, n windows overran the cap from n = 3 — so the
+    // LAST region was always dropped however much room the rest left. Measured on
+    // cli/hone-cli.js at cap 25,000 with stated lines [6180, 2000, 6580] and no inferred
+    // sites: 16,836 chars spent and 6580 dropped. `(n - 1)` keeps the single-window size
+    // exactly what it was.
+    let radius = Math.max(200,
+      Math.floor((limit - 800 - (chosen.length - 1) * markerCost) / (2 * chosen.length)));
+
+    const windows = [];
+    // HC-GF-216 review: a STATED line is a FLOOR, not a preference.
+    //
+    // Seeding it at index 0 was not enough — `mergeIntersectingWindows` returns its
+    // own order, so index 0 never reached the budget loop. Measured at cap 900 with
+    // line 7: 476 chars of 900 spent and the stated region dropped anyway, failing
+    // HC-GF-203 (`cli/lib/bundle-anchor.test.js:109`).
+    //
+    // Floor over preference because the two failures are not symmetric. A dropped
+    // INFERRED region surfaces as a planner refusal the operator can act on. A dropped
+    // STATED region is silent: the bundle is well-formed, the notice says a region was
+    // dropped, and nothing says the dropped one is the one that was asked for. That is
+    // HC-GF-205's lesson — the silence was the expensive part.
+    //
+    // No conflict with HC-GF-203's other pin (`:117`, a definition beats a mention):
+    // that ranks INFERRED sites against each other. This governs stated vs inferred.
+    // Different layers, so both hold.
+    //
+    // Bounded by construction: `radius` already shrinks with site count and floors at
+    // 200 chars, so the reserved window takes its share plus its marker, never the cap.
+    // Identify a stated entry by the RANGE it covers, not its anchor: mergeIntersectingWindows
+    // unions an overlapping inferred window into it and the merged entry inherits the
+    // OTHER site's anchor label, so `anchor === null` no longer finds it. Measured:
+    // candidate {line:7, anchor:null, 1-15} merges with {line:1, "thing", 1-10} and
+    // comes back as {line:7, anchor:"thing", 1-15}. HC-GF-288: by range, because with
+    // several stated lines a merge can also carry one stated line under ANOTHER's `line`.
+    const covers = (w, l) => w.startLine <= l && l <= w.endLine;
+    const rankOf = (c) => stated.findIndex((l) => covers(c.w, l));
+    // Restore the stated identity the merge erased. `anchor: null` is what makes the
+    // notice read "centered on referenced line N" rather than "anchored on `term`"
+    // (see `why` below), and an operator who named a line needs to see it was honoured.
+    // Reporting someone else's anchor for the window they asked for is the silence
+    // HC-GF-205 was filed about. Stated entries go first, in the caller's order; the
+    // rest keep merge order.
+    const layout = (r) => {
+      // HC-GF-206: merge intersecting windows BEFORE budgeting. The old dedupe was
+      // `usedLines.has(w.startLine)` — an exact start-line match, which two windows
+      // overlapping by all but a few lines never trigger.
+      const candidates = chosen.map((site) => ({
+        w: windowAroundLine(text, site.line, r),
+        anchor: site.anchor,
+        line: site.line,
+      }));
+      return mergeIntersectingWindows(text, candidates)
+        .map((c, i) => {
+          const k = rankOf(c);
+          return k === -1 ? { c, k: Infinity, i } : { c: { ...c, anchor: null, line: stated[k] }, k, i };
+        })
+        .sort((a, b) => (a.k - b.k) || (a.i - b.i))
+        .map(({ c, k }) => ({ ...c, stated: k !== Infinity }));
+    };
+    // Spend the budget in priority order. Stated entries come first, so a stated region is
+    // only ever dropped when the stated regions alone exceed the cap.
+    const budget = (ord) => {
+      const kept = [];
+      let spent = 0;
+      let skipped = 0;
+      for (const site of ord) {
+        const cost = costOf(site);
+        if (spent + cost > limit) {
+          // A dropped stated region is reported by LINE below, not counted here: the
+          // advice attached to this count — "name them as path:<line>" — is advice the
+          // operator has already followed for those.
+          if (!site.stated) skipped += 1;
+          continue;
+        }
+        spent += cost;
+        kept.push({ w: site.w, anchor: site.anchor, line: site.line });
+      }
+      return { kept, skipped };
+    };
+    // HC-GF-288 review: the radius is an ESTIMATE. Each window also snaps outward to whole
+    // lines — 50-180 chars per window on ordinary source, up to 10K on a file of long lines
+    // — which is not known until the window exists. Measured: six stated lines of
+    // cli/hone-cli.js left 4,192 chars unspent and still dropped one whose window needed
+    // 4,203. A stated line is a floor, so when the estimate loses one, search for the WIDEST
+    // radius that keeps them all.
+    //
+    // Of the layouts tried, keep the one that honours more stated lines — never "the last
+    // one tried". When even the narrowest windows cannot hold every stated line, narrowing
+    // frees room that an earlier window can take, and it lost 5 stated lines where the
+    // estimate lost 2 (a review probe, cap 12,000, seven lines of a file with 10K-char
+    // lines). A fixed number of shrink passes was also too few there: it stopped short and
+    // the fallback below overran a 25,000 cap by 409 chars. Only the estimate and the
+    // minimum are compared in that case; a radius between them can occasionally keep one
+    // more, which a scan would find at the cost of more layouts.
+    //
+    // On a tie, a layout that kept ANY window beats one that kept none, before width is
+    // considered: a layout with no window sends the result to the fallback, which overruns
+    // the cap by construction. Third review: preferring width alone discarded a 1,066-char
+    // layout for a 33,002-char fallback at cap 12,000.
+    let best = null;
+    const better = (a, b) => (a.honoured - b.honoured)
+      || (Number(a.plan.kept.length > 0) - Number(b.plan.kept.length > 0))
+      || (a.r - b.r);
+    const tryRadius = (r) => {
+      const plan = budget(layout(r));
+      const honoured = stated.filter((l) => plan.kept.some(({ w }) => covers(w, l))).length;
+      const cand = { r, plan, honoured };
+      if (!best || better(cand, best) > 0) best = cand;
+      return honoured === stated.length;
+    };
+    if (!tryRadius(radius) && radius > 200 && tryRadius(200)) {
+      // All stated lines fit at 200 but not at the estimate: binary-search between them.
+      // Bounded by log2(radius) layouts — measured at most 12 layouts and 228 ms on a
+      // 1.6 MB file of long lines, a few ms on ordinary source.
+      let lo = 200;
+      let hi = radius - 1;
+      while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (tryRadius(mid)) lo = mid; else hi = mid - 1;
+      }
+    }
+    radius = best.r;
+    windows.push(...best.plan.kept);
+    const dropped = best.plan.skipped;
+    if (!windows.length) {
+      // Nothing fits at any radius tried — one line alone is longer than the cap. Build the
+      // window at the MINIMUM radius, so the overrun is that line and no more: at the
+      // estimate, a 30,000-char line at cap 25,000 came back as 42,380 chars.
+      const w = windowAroundLine(text, chosen[0].line, 200);
+      windows.push({ w, anchor: chosen[0].anchor, line: chosen[0].line });
+    }
+    // HC-GF-288: which stated lines no kept window contains. Only the budget can do that
+    // here — every stated line seeded a window, and a merge never shrinks one.
+    const lost = stated.filter((l) => !windows.some(({ w }) => covers(w, l)));
+    for (const l of lost) unhonoured.push({ line: l, reason: 'budget', totalLines });
+
+    const ranges = windows.map(({ w }) => `${w.startLine}-${w.endLine}`).join(', ');
+    const because = why(windows[0].anchor, windows[0].line);
+    // HC-CI-016: a partial result reported as complete is the defect. If the budget
+    // could not cover every region found, the operator is TOLD how many were left out.
+    const shortfall = (dropped > 0
+      // HC-GF-216: "to bundle one directly" described the pre-fix behaviour and was the
+      // mechanism that taught operators to narrow their own bundles. A stated line now
+      // ANCHORS the spread, so the advice says so.
+      ? ` — ${dropped} further region(s) DROPPED for budget; name them as ${filePath}:<line> to anchor a region directly`
+      : '')
+      + (lost.length > 0
+        ? ` — stated line(s) ${lost.join(', ')} DROPPED for budget; name fewer regions in ${filePath}`
+        : '');
+
+    return {
+      mode: 'window',
+      unhonoured,
+      anchor: windows[0].anchor || null,
+      content: windows.map(({ w, anchor, line: siteLine }) =>
+        header(w, anchor, siteLine) + w.excerpt + footer).join('\n'),
+      notice: `  ⚠ ${filePath} is ${text.length} chars (cap ${limit}) — bundled lines `
+        + `${ranges} of ${windows[0].w.totalLines}, ${because}${shortfall}`,
+    };
+  }
+
+  const dropped = text.length - limit;
+  return {
+    mode: 'truncate',
+    unhonoured,
+    content: text.slice(0, limit)
+      + `\n\n# [HC-019n-followup-12: truncated at ${limit} chars; full file is ${text.length} chars]`,
+    notice: `  ⚠ ${filePath} is ${text.length} chars (cap ${limit}) — head-truncated, ${dropped} chars `
+      + `DROPPED and nothing in the story text matched inside the file, so the region you care about `
+      + `may not be in the bundle. Name it as ${filePath}:<line>, or quote the code, to anchor it.`,
+  };
+}
+
+// ── HC-GF-229: is a path a story CITES, or one it intends to CHANGE? ─────────
+//
+// DELIBERATE SECOND COPY. The identical block lives in
+// server/src/services/story-context.js. The CLI cannot read the roadmap and the
+// server cannot read the adopter's disk, and there is no shared lib between the
+// two packages — so the classification is duplicated on purpose, exactly as the
+// extraction layer beneath it (HC-GF-247) already is. The agreement pin in
+// tests/regression/HC-019n-followup-18-story-context-and-patch.test.js is what
+// keeps them equal: widening one side alone turns it red.
+//
+// THE RULE IS DECLARATION, NOT POSITION. A row may name its change targets
+// outright with a `**Targets:**` label; everything else the row names is
+// evidence. Absent a declaration the answer is byte-identical to today's
+// behaviour, and that is what makes the lost-file class structurally
+// impossible: a row that declares nothing cannot lose anything.
+//
+// Classifying by POSITION — a path appearing only inside the `**Premise:**`
+// span is evidence — was built, measured and REJECTED: 28 losing rows and 32
+// lost files over 261 completed rows, including cli/lib/bundle-paths.js for
+// HC-GF-203/204/206, the file all three exist to edit, while 5,000 regression
+// tests passed over it. See docs/architecture/HC-GF-229-classifier-design.md.
+// Do not re-attempt it.
+
+/**
+ * Inline bold labels. WIDENED on purpose: the rejected build matched the exact
+ * literal `**Premise:**` and missed 11 of 144 labels in use
+ * (`**Premise (measured 2026-09-18):**`, `**Premise for the correction:**`).
+ * The leading `[A-Z]` is deliberate — `**targets:**` in lowercase prose is a
+ * mention, not a declaration, and loosening case widens the false-positive
+ * surface onto every bold span in the corpus.
+ */
+const LABEL_RE = /\*\*([A-Z][^*\n]{0,80}?):\*\*/g;
+
+/**
+ * Blank out inline `code` spans and fenced blocks, PRESERVING OFFSETS.
+ *
+ * The known trap for this story, and this story's own row is the instance: it
+ * contains `` `**Targets:**` `` inside a code span while documenting the
+ * convention, and a naive detector reads that as a real declaration — the
+ * defect this story exists to fix, reproduced one level up on labels instead
+ * of paths.
+ *
+ * MASKING RATHER THAN DELETING IS LOAD-BEARING. Every non-newline character is
+ * replaced by a space, so `maskCodeSpans(t).length === t.length` and every
+ * index computed on the masked text addresses the same character of the
+ * original. That is what lets span bounds and token occurrences share one
+ * coordinate system with no second index map. Newlines survive so paragraph
+ * structure — which ends a span, below — is unchanged.
+ *
+ * Fences are masked FIRST so a backtick inside a fence cannot pair with one
+ * outside it.
+ *
+ * @param {string} text
+ * @returns {string} same length as the input
+ */
+function maskCodeSpans(text) {
+  const src = String(text || '');
+  const blank = (s) => s.replace(/[^\n]/g, ' ');
+  return src.replace(/```[\s\S]*?```/g, blank).replace(/`[^`\n]*`/g, blank);
+}
+
+/** Index of the blank line that ends the paragraph starting at `from`. */
+function paragraphEnd(text, from) {
+  const m = /\n[ \t]*\n/.exec(text.slice(from));
+  return m ? from + m.index : text.length;
+}
+
+/**
+ * Spans of text governed by a label whose name satisfies `namePredicate`.
+ *
+ * A span ends at the NEXT label or at the next BLANK LINE, whichever comes
+ * first. The next-label half is inherited from the replay harness; the blank
+ * line half is the correction. A roadmap row is one line, so the two rules are
+ * identical over the corpus — but a story BODY is not, and a declaration that
+ * ran to end-of-text because no second label followed would silently
+ * re-classify the next paragraph's prose citations as change targets, which is
+ * the widening this story exists to stop.
+ *
+ * @param {string} masked  output of maskCodeSpans — offsets match the original
+ * @param {(name: string) => boolean} namePredicate
+ * @returns {Array<[number, number]>} half-open [start, end) ranges
+ */
+function labelSpans(masked, namePredicate) {
+  const labels = [...masked.matchAll(new RegExp(LABEL_RE.source, 'g'))];
+  const spans = [];
+  labels.forEach((lab, i) => {
+    if (!namePredicate(lab[1])) return;
+    const nextLabel = i + 1 < labels.length ? labels[i + 1].index : masked.length;
+    const para = paragraphEnd(masked, lab.index + lab[0].length);
+    spans.push([lab.index, Math.min(nextLabel, para)]);
+  });
+  return spans;
+}
+
+/** The `**Targets…:**` spans of a story, code spans already excluded. */
+function targetSpans(text) {
+  return labelSpans(maskCodeSpans(String(text || '')), (n) => /^Targets\b/.test(n));
+}
+
+/** Every index at which `token` literally occurs. */
+function occurrencesOf(text, token) {
+  const at = [];
+  if (!token) return at;
+  let i = text.indexOf(token);
+  while (i !== -1) { at.push(i); i = text.indexOf(token, i + 1); }
+  return at;
+}
+
+function indexInSpans(i, spans) {
+  return spans.some(([a, b]) => i >= a && i < b);
+}
+
+/**
+ * The literal the ROW wrote, not the path it resolved to.
+ *
+ * Load-bearing for bare references. `resolveBareName` turns `orchestrator.js`
+ * into `server/src/services/orchestrator.js`, and that resolved path occurs
+ * nowhere in the row text — so matching on it would find zero occurrences and
+ * silently make every bare-ref citation evidence regardless of what the row
+ * declared.
+ */
+function tokenOf(entry) {
+  if (typeof entry === 'string') return entry;
+  if (!entry || typeof entry !== 'object') return '';
+  return String(entry.token || entry.path || '');
+}
+
+/**
+ * Partition the paths a story names into change targets and evidence.
+ *
+ * ADDITIVE. This wraps extraction rather than replacing it: extractPathRefs /
+ * extractBareRefs return exactly what they returned before, so every existing
+ * consumer of the shared chokepoint is untouched by construction. A caller
+ * that never calls this function behaves exactly as today.
+ *
+ * `named` carries whatever the caller resolved — `{path, token}` entries, or
+ * plain path strings. Entries are returned BY IDENTITY, so the caller keeps
+ * any fields (`line`, `via`) it attached.
+ *
+ * THREE OUTCOMES:
+ *
+ *   no declaration        targets = named, declared false. Today's behaviour,
+ *                         byte for byte. This is the structural guarantee.
+ *   declaration resolves  targets = the declared paths, evidence = the rest.
+ *                         One in-span occurrence is enough, so a path named in
+ *                         both the declaration and the premise is a TARGET.
+ *   declaration resolves
+ *   to nothing            targets = named, declared false, plus a diagnostic.
+ *                         Returning [] here would hand back an empty Scope —
+ *                         the HC-GF-073 blind-bundle failure, and the one
+ *                         outcome the acceptance forbids outright. A malformed
+ *                         declaration is an AUTHORING error, and the costs are
+ *                         asymmetric: degrading to the status quo loses
+ *                         nothing, bundling nothing loses everything. The
+ *                         diagnostic exists so that degradation is not silent —
+ *                         callers should surface it.
+ *
+ * Pure and I/O-free.
+ *
+ * @param {string} text  the story/row text, as written
+ * @param {Array<{path: string, token?: string}|string>} named
+ * @returns {{targets: Array, evidence: Array, declared: boolean, diagnostic: string|null}}
+ */
+function classifyStoryPaths(text, named) {
+  const list = Array.isArray(named) ? named.slice() : [];
+  const raw = String(text || '');
+  const masked = maskCodeSpans(raw);
+  const spans = labelSpans(masked, (n) => /^Targets\b/.test(n));
+  if (!spans.length) return { targets: list, evidence: [], declared: false, diagnostic: null };
+
+  const targets = [];
+  const evidence = [];
+  for (const entry of list) {
+    // SPANS FROM THE MASKED TEXT, OCCURRENCES FROM THE ORIGINAL. This is the whole
+    // reason maskCodeSpans preserves offsets, and getting it wrong made the feature
+    // inert on the corpus's actual writing convention: roadmap rows write paths
+    // inside backticks, masking blanks those to spaces, so every declared path
+    // scored ZERO occurrences, fell to evidence, and the declared-but-empty branch
+    // handed back `named` with declared:false. A row declaring
+    // `**Targets:** \`cli/lib/bundle-paths.js\`` bundled exactly what it bundles
+    // today — a sanitizer applied one layer too wide, silently disabling the
+    // capability it was protecting.
+    //
+    // The mask exists to stop a LABEL inside a code span reading as a declaration.
+    // It was never meant to hide PATHS. Residual, and accepted: a path written
+    // inside a code span that sits INSIDE a real Targets span now counts as a
+    // target, which is what the author meant by writing it there.
+    const hit = occurrencesOf(raw, tokenOf(entry)).some((i) => indexInSpans(i, spans));
+    (hit ? targets : evidence).push(entry);
+  }
+  if (!targets.length) {
+    return {
+      targets: list,
+      evidence: [],
+      declared: false,
+      diagnostic: list.length
+        ? `row declares Targets but none of its ${list.length} named path(s) resolved inside the `
+          + 'declaration — bundling all of them (status quo)'
+        : 'row declares Targets and names no paths',
+    };
+  }
+  return { targets, evidence, declared: true, diagnostic: null };
+}
+
 module.exports = {
   BARE_FILE_RE, extractBareNames, extractBareRefs, resolveBareName, alreadyCovered, windowAroundLine,
+  PATH_REF_RE, extractPathRefs, anchorLineForStory, planFileExcerpt, definitionIndexOf, anchorSitesForStory,
+  windowBetweenLines, mergeIntersectingWindows,
+  // HC-GF-229 — classification. Pinned byte-for-byte against the server copy.
+  LABEL_RE, maskCodeSpans, targetSpans, classifyStoryPaths,
 };