@hone-ai/cli 1.34.0 → 1.35.1

package/lib/batch-follow.js

@@ -0,0 +1,333 @@
+'use strict';
+/**
+ * batch-follow.js — HC-GF-098: `hone follow-batch <batchId>`, the loop that runs a queued batch's tests.
+ *
+ * The server cannot execute; the trust boundary is the authenticated CLI. So a batch queued overnight
+ * reached step_4 with no verdict: check-patch, verify-patch and emit-pr ran only when a person typed them.
+ * This module decides, tick by tick, what the loop does. `cli/hone-cli.js` supplies every piece of I/O.
+ *
+ * Design (architect review of 2026-09-25, recorded on the PR):
+ *  - The three verbs run as CHILD PROCESSES of the same CLI, one at a time. They call `process.exit`, install
+ *    signal handlers and read `process.cwd()`, and a child runs exactly the code a person runs. Their exit
+ *    codes are the contract. One at a time, because verify-patch seeds and tears down the adopter's live
+ *    datastore from the real tree, and two at once would destroy each other's rows.
+ *  - The loop never approves and never posts a verdict (`verify-patch --report` does). It never passes
+ *    `--trust-source`, `--skip-verify`, `--ready` or `--acknowledge-*`: an untrusted story stays paused for a
+ *    person (HC-GF-270), and so does one whose repository never consented to running its tests (HC-GF-064).
+ *  - It stops BEFORE acting when a breaker has fired. A terminal batch ends the loop after one last emit-pr pass.
+ *  - It is idempotent across restarts: an attempt that already has a verify-patch verdict on the server is not
+ *    verified again, and emit-pr's BRANCH_CONFLICT (5) means the branch was already emitted.
+ */
+
+const { classifyPollState, POLL_OUTCOMES } = require('./poll-decision');
+
+/** follow-batch's own exit codes. */
+const EXIT = Object.freeze({ DONE: 0, FATAL: 1, NEEDS_YOU: 2, DEADLINE: 3 });
+
+/** Flags the loop must never pass, whatever it is asked to do. The unit test checks every argv buildArgs can build. */
+const FORBIDDEN_FLAGS = Object.freeze(['--trust-source', '--skip-verify', '--ready', '--acknowledge-failed-verdict',
+  '--acknowledge-abort', '--approve']);
+
+/**
+ * Pause reasons that mean a child is NOT at a gate waiting for its step_4 output to be judged. `GET /:runId`
+ * sets `awaitingApproval` on ANY paused run with a current step, so without this a child paused by a breaker,
+ * a budget, an agent's hard pause or a guardrail would look like a gate, and the loop would run its patch.
+ * Sources: orchestrator.js (BATCH_*), orchestrator-guardrails.js GUARDRAIL_REFUSAL_CODES, the hard-pause scan.
+ */
+const NOT_A_GATE = /^(BATCH_FAILURE_THRESHOLD_EXCEEDED:|BATCH_BUDGET_EXCEEDED:|MAX_RETRIES_EXCEEDED:|MAX_TOTAL_STEPS_EXCEEDED:|hard_pause at )/;
+
+/** What each child exit code means, for the action line. verify-patch.js and emit-pr.js EXIT maps. */
+const CHECK_EXIT = { 0: 'applies', 1: 'no diff', 2: 'does not apply' };
+const VERIFY_EXIT = { 0: 'pass', 1: 'no diff', 2: 'does not apply', 3: 'tests failed', 4: 'timed out',
+  7: 'test command could not start', 8: 'not run: environment incomplete', 9: 'refused: untrusted story source' };
+const EMIT_EXIT = { 0: 'emitted', 1: 'no diff', 2: 'does not apply', 3: 'tests failed', 4: 'timed out',
+  5: 'already emitted (branch exists)', 6: 'publish failed', 7: 'test command could not start',
+  9: 'refused: untrusted story source' };
+
+const firstLine = (s) => String(s || '').split('\n')[0];
+
+/**
+ * Should the loop stop before acting on anything? A breaker pauses the batch's LATER CHILDREN rather than the
+ * batch: `GET /orchestrate/batch/:id` reports `failurePauseTriggered` (HC-051, null threshold = disabled) and
+ * `budgetExceeded` (HC-050), and the child it paused carries the reason as its `errorMessage` prefix.
+ *
+ * @param {object} batch  a `GET /orchestrate/batch/:id` payload (untrusted shape)
+ * @returns {string|null} why the loop stops, in words an operator can act on, or null to carry on
+ */
+function breakerStop(batch) {
+  const b = (batch && typeof batch === 'object') ? batch : {};
+  const runs = Array.isArray(b.runs) ? b.runs : [];
+  // A child the breaker paused is evidence the breaker fired, even when the batch-level flag has not caught up.
+  const pausedBy = (prefix) => runs.find((r) => r && typeof r.errorMessage === 'string' && r.errorMessage.startsWith(prefix));
+  const failed = pausedBy('BATCH_FAILURE_THRESHOLD_EXCEEDED:');
+  if (b.failurePauseTriggered === true || failed) {
+    const n = Number.isFinite(b.failureCount) && Number.isFinite(b.failureThreshold)
+      ? ` (${b.failureCount} failed, threshold ${b.failureThreshold})` : '';
+    return `the batch's failure breaker fired${n}${failed ? `: ${failed.storyId} ${firstLine(failed.errorMessage)}` : ''}`;
+  }
+  const spent = pausedBy('BATCH_BUDGET_EXCEEDED:');
+  if (b.budgetExceeded === true || spent) {
+    const pct = Number.isFinite(b.budgetPct) ? ` (${b.budgetPct}% used)` : '';
+    return `the batch's token budget is spent${pct}${spent ? `: ${spent.storyId} ${firstLine(spent.errorMessage)}` : ''}`;
+  }
+  return null;
+}
+
+/** True once the server has stored a terminal status for the batch (it does so on the same GET). */
+function isTerminal(batch) {
+  return !!(batch && batch.status && batch.status !== 'active');
+}
+
+/** The verify-patch verdict the server already holds for this run's step_4 attempt, or null. */
+function priorVerdict(run, attempt) {
+  const list = Array.isArray(run && run.verifications) ? run.verifications : [];
+  return list.find((v) => v && v.source === 'verify-patch' && v.stepKey === 'step_4' && Number(v.attempt) === attempt) || null;
+}
+
+/**
+ * Is this paused run a step_4 gate whose patch the loop should check and verify now?
+ * @param {object} run  a `GET /orchestrate/:runId` payload
+ * @returns {{actionable: true, attempt: number} | {actionable: false, reason?: string}}
+ */
+function step4Action(run) {
+  const c = classifyPollState(run);
+  // Not a step_4 gate: not this loop's business, and nothing to say about it.
+  if (c.outcome !== POLL_OUTCOMES.HUMAN_GATE || c.stepKey !== 'step_4') return { actionable: false };
+  const why = String((run && run.errorMessage) || '');
+  if (NOT_A_GATE.test(why)) return { actionable: false, reason: `paused, not at a gate: ${firstLine(why)}` };
+  if (run.approvalRefusal) return { actionable: false, reason: 'the server refuses approval of this attempt' };
+  const attempt = Number(String(c.attemptKey || '').split('#')[1]) || 1;
+  const prior = priorVerdict(run, attempt);
+  if (prior) {
+    const id = run.runId || '<runId>';
+    // Under the advisory gate a failing verdict does not refuse approval, so this line is all that stands between
+    // the operator and approving a patch whose tests failed. Only a pass is offered the approve command.
+    return { actionable: false, reason: prior.verdict === 'pass'
+      ? `attempt ${attempt} passed verify-patch; approve it with hone run-story ${id} --approve step_4`
+      : `attempt ${attempt}'s verify-patch verdict is ${prior.verdict}; read it with hone run-report ${id}` };
+  }
+  return { actionable: true, attempt };
+}
+
+/**
+ * The argv for one child verb. Exit codes are the contract; `--format json` only carries detail.
+ * @param {'check-patch'|'verify-patch'|'emit-pr'} verb
+ */
+function buildArgs(verb, runId, { attempt, openPr = false, branch } = {}) {
+  const args = [verb, runId];
+  if (verb !== 'emit-pr' && attempt) args.push('--step-key', 'step_4', '--attempt', String(attempt));
+  if (verb === 'verify-patch') args.push('--report');
+  if (verb === 'emit-pr' && attempt) args.push('--attempt', String(attempt));
+  if (verb === 'emit-pr' && branch) args.push('--branch', branch);
+  if (verb === 'emit-pr' && openPr) args.push('--push', '--open-pr');
+  args.push('--format', 'json');
+  return args;
+}
+
+/** The step_4 attempt a run is on now: the highest step_4 attempt in its steps, or null. */
+function currentStep4Attempt(run) {
+  const steps = Array.isArray(run && run.steps) ? run.steps : [];
+  const attempts = steps.filter((st) => st && st.stepKey === 'step_4').map((st) => Number(st.attempt) || 1);
+  return attempts.length ? Math.max(...attempts) : null;
+}
+
+/** The current step_4 attempt, when the server holds a `pass` verify-patch verdict for it; else null. */
+function verifiedStep4Attempt(run) {
+  const attempt = currentStep4Attempt(run);
+  const v = attempt && priorVerdict(run, attempt);
+  return v && v.verdict === 'pass' ? attempt : null;
+}
+
+/**
+ * HC-GF-301: one branch, so one draft PR, per step_4 attempt. emit-pr's own name has no attempt in it, and for a
+ * branch with an open PR it reports "already open" and pushes nothing — so after a step_5 route-back the PR would go
+ * on showing the older attempt's code while the command said it succeeded. emit-pr slugifies the name.
+ */
+function draftBranch(storyId, runId, attempt) {
+  return `hone/${storyId || 'story'}-${String(runId).slice(0, 8)}-a${attempt}`;
+}
+
+/**
+ * One tick's decisions, from the batch and the details of its paused runs. Pure.
+ * @param {object} batch     `GET /orchestrate/batch/:id`
+ * @param {Record<string, object>} details  runId → `GET /orchestrate/:runId`, for paused runs and runs to emit
+ * @param {{emitted: Set<string>}} memory   runs whose emit-pr already ran in this process
+ * @param {{repoName?: string|null}} [ctx]  this checkout, so a run for another repository is not touched
+ * @returns {{stop: {exitCode: number, reason: string}|null, actions: object[], notes: string[]}}
+ */
+function planTick(batch, details, memory, ctx = {}) {
+  const b = (batch && typeof batch === 'object') ? batch : {};
+  const halt = breakerStop(b);
+  if (halt) return { stop: { exitCode: EXIT.NEEDS_YOU, reason: halt }, actions: [], notes: [] };
+
+  const actions = [];
+  const notes = [];
+  for (const r of Array.isArray(b.runs) ? b.runs : []) {
+    if (!r || !r.runId) continue;
+    if (ctx.repoName && r.repoName && r.repoName !== ctx.repoName) {
+      notes.push(`${r.storyId} ${r.runId} belongs to ${r.repoName}, not this checkout (${ctx.repoName}): skipped`);
+      continue;
+    }
+    if (r.status === 'completed') {
+      if (!memory.emitted.has(r.runId)) {
+        // Opening PRs, the completed run's emit goes to its step_4 attempt's branch, so a draft opened for that
+        // attempt is found open and nothing is opened twice.
+        const attempt = ctx.openPr ? currentStep4Attempt(details[r.runId]) : null;
+        actions.push({ kind: 'emit', runId: r.runId, storyId: r.storyId, run: details[r.runId],
+          ...(attempt ? { attempt, branch: draftBranch(r.storyId, r.runId, attempt) } : {}) });
+      }
+      continue;
+    }
+    if (r.status !== 'paused' || !details[r.runId]) continue;
+    // HC-GF-301: opening PRs, a step_4 attempt that passed verify-patch gets its draft now, while step_5 and its
+    // gate are still ahead, instead of when the whole run completes.
+    const verified = ctx.openPr ? verifiedStep4Attempt(details[r.runId]) : null;
+    if (verified && !(memory.drafted && memory.drafted.has(`${r.runId}#${verified}`))) {
+      actions.push({ kind: 'draft', runId: r.runId, storyId: r.storyId, attempt: verified, run: details[r.runId],
+        branch: draftBranch(r.storyId, r.runId, verified) });
+      const vs = Array.isArray(details[r.runId].verifications) ? details[r.runId].verifications : [];
+      const earlier = vs.filter((v) => v && v.source === 'verify-patch' && v.stepKey === 'step_4' && v.verdict === 'pass'
+        && Number(v.attempt) < verified).map((v) => Number(v.attempt));
+      if (earlier.length) {
+        const m = Math.max(...earlier);
+        notes.push(`${r.storyId} ${r.runId}: the draft for attempt ${verified} supersedes the one on ${draftBranch(r.storyId, r.runId, m)}; close that one when you are ready`);
+      }
+    }
+    const a = step4Action(details[r.runId]);
+    // verify-patch's verdict POST is best-effort: an attempt this process already ran is not re-run every tick.
+    if (a.actionable && memory.tried && memory.tried.has(`${r.runId}#${a.attempt}`)) {
+      notes.push(`${r.storyId} ${r.runId} needs you: attempt ${a.attempt} was verified here but no verdict reached the server`);
+      continue;
+    }
+    if (a.actionable) {
+      actions.push({ kind: 'verify', runId: r.runId, storyId: r.storyId, attempt: a.attempt, run: details[r.runId] });
+    } else if (a.reason) {
+      notes.push(`${r.storyId} ${r.runId} needs you: ${a.reason}`);
+    }
+  }
+
+  if (!isTerminal(b)) return { stop: null, actions, notes };
+  const unfinished = (b.counts && ((b.counts.failed || 0) + (b.counts.killed || 0) + (b.counts.stalled || 0))) || 0;
+  return {
+    stop: unfinished
+      ? { exitCode: EXIT.NEEDS_YOU, reason: `batch ${b.status}: ${unfinished} run(s) did not complete` }
+      : { exitCode: EXIT.DONE, reason: `batch ${b.status}` },
+    actions,
+    notes,
+  };
+}
+
+/**
+ * Run one action's child verbs, in order, and describe what happened. Nothing that executes the adopter's tests
+ * (verify-patch, or emit-pr, which re-verifies) starts unless the repository's consent and the story's provenance
+ * allow it; verify-patch also waits for check-patch to exit 0.
+ * @param {object} action  from planTick
+ * @param {{runVerb: (argv: string[]) => Promise<{code: number|null}>,
+ *          verifyDecision: (run: object) => {run: boolean, reason: string}}} io
+ * @param {{openPr?: boolean}} [opts]
+ * @returns {Promise<{lines: string[], needsYou: boolean}>}
+ */
+async function runTask(action, io, opts = {}) {
+  const tag = `[follow-batch] ${action.storyId} ${action.runId}`;
+  if (action.kind === 'emit' || action.kind === 'draft') {
+    // emit-pr re-runs the tests before it commits, even as a local dry run, so it needs the same consent and
+    // provenance verify-patch does. Without this, a repository that never set ci.local_command gets `make ci`.
+    const what = action.kind === 'draft' ? `draft PR (attempt ${action.attempt})` : 'emit-pr';
+    const allowed = io.verifyDecision(action.run || {});
+    if (!allowed || !allowed.run) {
+      return { lines: [`${tag} ${what} not run: ${(allowed && allowed.reason) || 'not allowed'}; emit it yourself with hone emit-pr ${action.runId}`], needsYou: true };
+    }
+    const r = await io.runVerb(buildArgs('emit-pr', action.runId,
+      { openPr: action.kind === 'draft' || !!opts.openPr, attempt: action.attempt, branch: action.branch }));
+    const meaning = EMIT_EXIT[r.code] || `exit ${r.code}`;
+    return { lines: [`${tag} ${what} → ${meaning}${action.branch ? ` (${action.branch})` : ''}`], needsYou: r.code !== 0 && r.code !== 5 };
+  }
+  const check = await io.runVerb(buildArgs('check-patch', action.runId, { attempt: action.attempt }));
+  const lines = [`${tag} check-patch (attempt ${action.attempt}) → ${CHECK_EXIT[check.code] || `exit ${check.code}`}`];
+  if (check.code !== 0) return { lines, needsYou: true };
+  const decision = io.verifyDecision(action.run || {});
+  if (!decision || !decision.run) {
+    lines.push(`${tag} verify-patch not run: ${(decision && decision.reason) || 'not allowed'}; left paused for you`);
+    return { lines, needsYou: true };
+  }
+  const v = await io.runVerb(buildArgs('verify-patch', action.runId, { attempt: action.attempt }));
+  lines.push(`${tag} verify-patch (attempt ${action.attempt}) → ${VERIFY_EXIT[v.code] || `exit ${v.code}`}`);
+  return { lines, needsYou: v.code !== 0 };
+}
+
+/**
+ * The loop. Every effect is injected, so a test drives it with a stub server and a recording runVerb.
+ * @param {string} batchId
+ * @param {{fetchBatch: Function, fetchRun: Function, runVerb: Function, verifyDecision: Function,
+ *          sleep: (ms: number) => Promise<void>, now: () => number, log: (line: string) => void}} io
+ * @param {{pollMs?: number, deadlineMs?: number|null, maxOfflineMs?: number, openPr?: boolean,
+ *          repoName?: string|null}} [opts]
+ * @returns {Promise<{exitCode: number, reason: string}>}
+ */
+async function followBatch(batchId, io, opts = {}) {
+  const pollMs = opts.pollMs || 30_000;
+  const maxOfflineMs = opts.maxOfflineMs || 15 * 60_000;
+  // owed: runs whose emit-pr needed a person. A completed batch with one of these is not DONE (HC-GF-207's shape:
+  // a failure path that exits 0).
+  const memory = { emitted: new Set(), tried: new Set(), drafted: new Set(), said: new Set(), owed: new Map() };
+  const start = io.now();
+  let offlineSince = null;
+  const say = (line) => { if (!memory.said.has(line)) { memory.said.add(line); io.log(line); } };
+
+  for (;;) {
+    if (opts.deadlineMs && io.now() - start >= opts.deadlineMs) {
+      return { exitCode: EXIT.DEADLINE, reason: `deadline reached after ${Math.round(opts.deadlineMs / 60_000)} min` };
+    }
+    // A tick reads everything or acts on nothing: a run that could not be read is the server being unreachable,
+    // not a run with no details (which would skip its gate, or emit it with no provenance to assess).
+    let batch;
+    const details = {};
+    try {
+      batch = await io.fetchBatch(batchId);
+      for (const r of Array.isArray(batch && batch.runs) ? batch.runs : []) {
+        const wanted = r && r.runId && (r.status === 'paused' || (r.status === 'completed' && !memory.emitted.has(r.runId)));
+        if (wanted) details[r.runId] = await io.fetchRun(r.runId);
+      }
+      offlineSince = null;
+    } catch (e) {
+      const status = e && e.response && e.response.status;
+      if (status === 401 || status === 403 || status === 404) {
+        return { exitCode: EXIT.FATAL, reason: `the server answered ${status} while reading batch ${batchId}` };
+      }
+      if (offlineSince === null) offlineSince = io.now();
+      if (io.now() - offlineSince >= maxOfflineMs) {
+        return { exitCode: EXIT.FATAL, reason: `the server has been unreachable for ${Math.round(maxOfflineMs / 60_000)} min: ${firstLine(e && e.message)}` };
+      }
+      await io.sleep(pollMs);
+      continue;
+    }
+
+    const plan = planTick(batch, details, memory, { repoName: opts.repoName || null, openPr: !!opts.openPr });
+    for (const n of plan.notes) say(`[follow-batch] ${n}`);
+    for (const action of plan.actions) {
+      const out = await runTask(action, io, { openPr: opts.openPr });
+      if (action.kind === 'emit' || action.kind === 'draft') {
+        if (action.kind === 'emit') memory.emitted.add(action.runId);
+        else memory.drafted.add(`${action.runId}#${action.attempt}`);
+        // A run is owed until an emit for it succeeds: a draft that failed is retried by the completed-run emit.
+        if (out.needsYou) memory.owed.set(action.runId, `${action.storyId} ${action.runId}`);
+        else if (action.kind === 'emit') memory.owed.delete(action.runId);
+      } else {
+        memory.tried.add(`${action.runId}#${action.attempt}`);
+      }
+      for (const line of out.lines) io.log(line);
+    }
+    if (plan.stop && plan.stop.exitCode === EXIT.DONE && memory.owed.size) {
+      return { exitCode: EXIT.NEEDS_YOU,
+        reason: `${plan.stop.reason}, but ${memory.owed.size} run(s) were not emitted: ${[...memory.owed.values()].join(', ')}` };
+    }
+    if (plan.stop) return plan.stop;
+    await io.sleep(pollMs);
+  }
+}
+
+module.exports = {
+  EXIT, FORBIDDEN_FLAGS, NOT_A_GATE,
+  breakerStop, isTerminal, priorVerdict, step4Action, buildArgs, planTick, runTask, followBatch,
+  currentStep4Attempt, verifiedStep4Attempt, draftBranch,
+};

package/lib/block-grammar.js

@@ -0,0 +1,126 @@
+'use strict';
+/**
+ * block-grammar.js — HC-GF-290: the ONE definition of a fenced block in a step_4 build artifact.
+ *
+ * A fence is a line that starts (after blanks) with THREE OR MORE backticks. The block it opens ends
+ * at the first later line made of backticks alone, AT LEAST AS MANY as the opener's (blanks around
+ * them allowed). That is CommonMark's rule, and it is how a block carries content that itself holds
+ * ``` lines: open it with four.
+ *
+ * The rule used to be a literal in each parser, and it changed in one parser at a time. HC-GF-127
+ * taught the `file:` regex in materialize-diff and carry-forward the longer fence; the `edit:` regex
+ * beside it and generation.js's block scanner kept three. On run 0e4cd053 step_4 attempt 1 — a
+ * finished 51,793-char build, stop_reason end_turn — one ````edit: block was an unnamed code block
+ * to the scanner, closed at the next ``` line, and shifted every later pairing by one. The final
+ * Self-Check fence then read as an opener, `generation.complete` came back false, and the
+ * orchestrator regenerated the whole build as output_incomplete. For the same block the CLI
+ * reported `no closing fence` and refused the patch.
+ *
+ * This file exists twice, byte for byte: `server/src/services/block-grammar.js` and
+ * `cli/lib/block-grammar.js`. The server cannot require the CLI package (Railway installs server/
+ * only), and the published CLI carries no server code. A difference between the two is a red test
+ * (tests/regression/HC-GF-290-longer-fences.test.js).
+ *
+ * Pure. No I/O.
+ */
+
+/** A line that opens a fenced block. Group 1 is the fence. */
+const FENCE_OPEN_RE = /^[ \t]*(`{3,})/;
+/** A line that can close one: backticks alone. Group 1 is the fence. */
+const FENCE_CLOSE_RE = /^[ \t]*(`{3,})[ \t]*\r?$/;
+/** The opener of a `file:` or `edit:` block. Group 1 is the kind, group 2 the path. */
+const DIRECTIVE_RE = /^[ \t]*`{3,}[ \t]*(file|edit)[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?$/i;
+
+/** How wide a fence `line` opens, or 0 when it opens none. */
+function fenceWidth(line) {
+  const m = FENCE_OPEN_RE.exec(line);
+  return m ? m[1].length : 0;
+}
+
+/** Whether `line` closes a block whose fence is `width` backticks wide. */
+function closesFence(line, width) {
+  const m = FENCE_CLOSE_RE.exec(line);
+  return m !== null && m[1].length >= width;
+}
+
+/**
+ * Every fenced block of `text`, walked line by line, so a block's own fence decides what closes it.
+ *
+ * Offsets address `text`. [start, end) runs from the opener line to the end of the closer line (its
+ * newline excluded); [bodyStart, bodyEnd) is everything between the two lines. `open` is a block
+ * the text never closed.
+ *
+ * @returns {{ blocks: Array<{start:number, end:number, bodyStart:number, bodyEnd:number, width:number, opener:string}>,
+ *             open: {start:number, bodyStart:number, width:number, opener:string}|null }}
+ */
+function fencedSpans(text) {
+  const src = String(text == null ? '' : text);
+  const blocks = [];
+  let cur = null;
+  for (let i = 0; ;) {
+    const nl = src.indexOf('\n', i);
+    const end = nl === -1 ? src.length : nl;
+    const line = src.slice(i, end);
+    if (!cur) {
+      const width = fenceWidth(line);
+      if (width) cur = { start: i, bodyStart: nl === -1 ? src.length : nl + 1, width, opener: line };
+    } else if (closesFence(line, cur.width)) {
+      blocks.push({ ...cur, end, bodyEnd: i });
+      cur = null;
+    }
+    if (nl === -1) break;
+    i = nl + 1;
+  }
+  return { blocks, open: cur };
+}
+
+/**
+ * A `file:` block as one regex: group 1 the fence, 2 the path, 3 the body.
+ *
+ * HC-GF-022: the closer is anchored to its OWN line, so an empty block (every Python package's
+ * `__init__.py`) cannot swallow its closer and eat the next block. HC-GF-127: the fence is three OR
+ * MORE backticks and the closer backreferences it, so a file whose content holds a ```js sample is
+ * not cut at the sample. HC-GF-290: the closer is the opener's fence or wider, as for every block.
+ */
+const FILE_BLOCK_RE = /^[ \t]*(`{3,})[ \t]*file[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?\n([\s\S]*?)^[ \t]*\1`*[ \t]*\r?$/gim;
+
+/**
+ * An `edit:` block (HC-019n-followup-27) as one regex: group 1 the fence, 2 the path, 3 the body.
+ *
+ * HC-GF-109: a body framed by `<<<<<<< OLD` … `>>>>>>> NEW` ends at the closer right after its NEW
+ * line, so a NEW holding a fence line of its own is not cut short, and it never runs on into the next
+ * block. Anything else runs to the first line that starts with the block's own fence, and the
+ * parser reports it as malformed. HC-GF-290: the fence is three or more backticks and the closer is
+ * that fence or wider — a ````edit: block was invisible to this regex, so the CLI called it
+ * unterminated and refused the whole patch.
+ */
+const EDIT_BLOCK_RE = new RegExp(
+  '^[ \\t]*(`{3,})[ \\t]*edit[ \\t]*:[ \\t]*([^\\n`]+?)[ \\t]*\\r?\\n(' +
+    '<{3,}[ \\t]*OLD[ \\t]*\\r?\\n(?:(?!^[ \\t]*`{3,}[ \\t]*(?:file|edit)[ \\t]*:)[\\s\\S])*?^>{3,}[ \\t]*NEW[ \\t]*\\r?\\n' +
+    '|(?:(?!^[ \\t]*\\1)[\\s\\S])*?' +
+  ')^[ \\t]*\\1`*[ \\t]*\\r?$',
+  'gim');
+
+/** HC-GF-109: the opening line of an edit block, whether or not the block parses — compared, so none is lost. */
+const EDIT_OPEN_RE = /^[ \t]*`{3,}[ \t]*edit[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?$/gim;
+
+/**
+ * The OLD/NEW split inside an edit block: `<<<<<<< OLD` … `=======` … `>>>>>>> NEW`. The bodies are
+ * verbatim (indentation is part of the anchor); an empty NEW deletes the anchor (HC-GF-109).
+ */
+const EDIT_SPLIT_RE = /^<{3,}[ \t]*OLD[ \t]*\r?\n([\s\S]*?)\r?\n={3,}[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?>{3,}[ \t]*NEW[ \t]*\r?$/m;
+
+/** A `DELETE: <path>` line. */
+const DELETE_RE = /^[ \t]*DELETE:[ \t]*(\S.*?)[ \t]*$/gim;
+
+module.exports = {
+  fenceWidth,
+  closesFence,
+  fencedSpans,
+  DIRECTIVE_RE,
+  FILE_BLOCK_RE,
+  EDIT_BLOCK_RE,
+  EDIT_OPEN_RE,
+  EDIT_SPLIT_RE,
+  DELETE_RE,
+};

package/lib/bundle-context.js

@@ -64,6 +64,40 @@ function isSecretPath(p) {
   return SECRET_BASENAMES.some((re) => re.test(base));
 }
 
+/**
+ * Generated or lock files: real, tracked, and useless as source context.
+ *
+ * HC-GF-206: run `c92d8cdc` pulled `cli/package-lock.json` and `cli/CHANGELOG.md`
+ * in as siblings and spent 125,897 chars on files no story mentions. A lockfile
+ * windowed on `node_modules` is noise at any cap, and a generated CHANGELOG
+ * teaches nothing about the conventions a new file must match — which is the
+ * whole reason siblings are bundled.
+ *
+ * Deliberately narrow: only files a tool writes and a human does not edit. A
+ * `.json` config an adopter maintains by hand is NOT generated and stays
+ * eligible.
+ */
+const GENERATED_BASENAMES = [
+  /^package-lock\.json$/i,
+  /^npm-shrinkwrap\.json$/i,
+  /^yarn\.lock$/i,
+  /^pnpm-lock\.yaml$/i,
+  /^Gemfile\.lock$/i,
+  /^poetry\.lock$/i,
+  /^Cargo\.lock$/i,
+  /^composer\.lock$/i,
+  /^go\.sum$/i,
+  /^CHANGELOG\.md$/i,
+  /\.min\.(?:js|css)$/i,
+  /\.map$/i,
+];
+
+function isGeneratedPath(p) {
+  const base = path.posix.basename(String(p || '').replace(/\\/g, '/'));
+  return GENERATED_BASENAMES.some((re) => re.test(base));
+}
+
+
 /** Directory of a repo-relative path, '' at the root. */
 const dirOf = (p) => {
   const d = path.posix.dirname(String(p).replace(/\\/g, '/'));
@@ -86,11 +120,16 @@ function directChildren(dir, repoFiles) {
  * return the entire repo.
  */
 function nearestPopulatedAncestor(pendingPath, repoFiles) {
+  // HC-GF-206: `dir` used to be returned alongside `kids` and the single caller
+  // destructures only `kids`, so it was a handoff that never arrived anywhere.
+  // It stays the loop variable; it is no longer offered as a result. Same call
+  // as the `warning` field on the A and B parse paths: a value handed on but
+  // never consumed reads like a carried result and is not one.
   let dir = dirOf(pendingPath);
   for (;;) {
     const kids = directChildren(dir, repoFiles);
-    if (kids.length > 0) return { dir, kids };
-    if (dir === '') return { dir: '', kids: [] };
+    if (kids.length > 0) return { kids };
+    if (dir === '') return { kids: [] };
     dir = dirOf(dir);
   }
 }
@@ -129,7 +168,7 @@ function selectBundle({ named = [], repoFiles = [], exists = () => false, maxSib
       (path.posix.extname(b) === ext) - (path.posix.extname(a) === ext));
     for (const k of ranked) {
       if (siblings.length >= maxSiblings) break;
-      if (taken.has(k) || isSecretPath(k)) continue;
+      if (taken.has(k) || isSecretPath(k) || isGeneratedPath(k)) continue;
       taken.add(k); siblings.push(k);
     }
   }
@@ -179,4 +218,4 @@ function auditLines(sel) {
   return out;
 }
 
-module.exports = { selectBundle, auditLines, isSecretPath, SIGNAL_FILES };
+module.exports = { selectBundle, auditLines, isSecretPath, isGeneratedPath, SIGNAL_FILES };