@hone-ai/cli 1.32.0 → 1.33.0

package/lib/materialize-diff.js

@@ -58,14 +58,26 @@ function blockBody(raw) {
  * lets git build the diff — so the count stays git's, exactly as for whole-file
  * blocks. See .github/pipeline/HC-019n-followup-27/architect.md.
  */
-const EDIT_BLOCK_RE = /```[ \t]*edit[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?\n([\s\S]*?)\r?\n```/gi;
+const EDIT_BLOCK_RE = new RegExp(
+  '^[ \\t]*```[ \\t]*edit[ \\t]*:[ \\t]*([^\\n`]+?)[ \\t]*\\r?\\n(' +
+    // HC-GF-109: a framed body ends at the fence after its `>>>>>>> NEW` line, so a NEW holding a fence line of its own
+    // (a docstring example, a Markdown file) is not cut short, and it never runs on into the next block.
+    '<{3,}[ \\t]*OLD[ \\t]*\\r?\\n(?:(?!^[ \\t]*```[ \\t]*(?:file|edit)[ \\t]*:)[\\s\\S])*?^>{3,}[ \\t]*NEW[ \\t]*\\r?\\n' +
+    // Anything else runs to the first fence line, and extractFileBlocks reports it as malformed.
+    '|(?:(?!^[ \\t]*```)[\\s\\S])*?' +
+  ')^[ \\t]*```[ \\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]*```[ \t]*edit[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?$/gim;
 
 /**
  * The OLD/NEW split inside an edit block. `<<<<<<< OLD` … `=======` … `>>>>>>> NEW`.
  * Whitespace after the marker word is tolerated; the bodies are captured verbatim
- * (indentation is part of the anchor).
+ * (indentation is part of the anchor). An empty NEW deletes the anchor (HC-GF-109) — it used to
+ * fail this split, and the block was skipped without a word.
  */
-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]*$/m;
+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 inside the ## Changed Files section. */
 const DELETE_RE = /^[ \t]*DELETE:[ \t]*(\S.*?)[ \t]*$/gim;
@@ -89,6 +101,8 @@ class MaterializeError extends Error {
  * @param {string} output  raw step_4 output
  * @returns {{
  *   files: Array<{ path: string, contents: string }>,
+ *   edits: Array<{ path: string, oldString: string, newString: string }>,  every edit block, in order (HC-GF-109)
+ *   malformed: Array<{ path: string, reason: string }>,  edit blocks that could not be read
  *   deletes: string[],
  *   noChanges: boolean,
  *   reason: string|null
@@ -96,7 +110,7 @@ class MaterializeError extends Error {
  */
 function extractFileBlocks(output) {
   const text = String(output || '');
-  const empty = { files: [], edits: [], deletes: [], noChanges: false, reason: null };
+  const empty = { files: [], edits: [], deletes: [], malformed: [], noChanges: false, reason: null };
 
   // Scope everything to the ## Changed Files section if present, so a code
   // sample elsewhere in the prose is never mistaken for an intended file.
@@ -105,8 +119,8 @@ function extractFileBlocks(output) {
 
   // Honest no-op, same shape as the followup-19 NO CHANGES escape. A NO CHANGES
   // declaration only counts when there is NO file AND NO edit block to apply.
-  const hasBlock = (FILE_BLOCK_RE.test(scope) || EDIT_BLOCK_RE.test(scope));
-  FILE_BLOCK_RE.lastIndex = 0; EDIT_BLOCK_RE.lastIndex = 0;
+  const hasBlock = (FILE_BLOCK_RE.test(scope) || EDIT_OPEN_RE.test(scope));
+  FILE_BLOCK_RE.lastIndex = 0; EDIT_OPEN_RE.lastIndex = 0;
   const noChange = scope.match(/NO CHANGES\b[ \t]*[—:-]?[ \t]*([^\n]*)/i);
   if (noChange && !hasBlock) {
     return { ...empty, noChanges: true, reason: (noChange[1] || '').trim() || null };
@@ -123,16 +137,33 @@ function extractFileBlocks(output) {
   }
 
   // HC-019n-followup-27: region edits for files too big to bundle whole.
+  // HC-GF-109: EVERY edit block for a path, in order. This loop used to keep the first and drop the rest ("first edit
+  // wins") while the code-builder prompt asks for `edit:` on a file changed in a few places, so 12 of 24 stored edit
+  // blocks never reached the patch, and verify-patch type-checked a settings.py missing four of its five edits.
   const edits = [];
-  const editSeen = new Set();
+  const malformed = [];
+  const editKeys = new Set();
+  const parsedAt = new Set();
   for (const m of scope.matchAll(EDIT_BLOCK_RE)) {
+    parsedAt.add(m.index);
     const rel = normalizeRepoPath(m[1]);
     if (!rel) continue;
-    if (seen.has(rel) || editSeen.has(rel)) continue; // a whole-file block wins; first edit wins
+    if (seen.has(rel)) continue;   // a whole-file block wins
     const split = EDIT_SPLIT_RE.exec(m[2]);
-    if (!split) continue;          // malformed edit block (no OLD/NEW markers) — skip
-    editSeen.add(rel);
-    edits.push({ path: rel, oldString: split[1], newString: split[2] });
+    if (!split) {                  // no OLD/NEW markers: reported, and buildDiff refuses the patch
+      malformed.push({ path: rel, reason: 'no <<<<<<< OLD / ======= / >>>>>>> NEW markers' });
+      continue;
+    }
+    const edit = { path: rel, oldString: split[1], newString: split[2] || '' };
+    const key = JSON.stringify([edit.path, edit.oldString, edit.newString]);
+    if (editKeys.has(key)) continue; // the same block emitted twice is one change, not two
+    editKeys.add(key);
+    edits.push(edit);
+  }
+  for (const m of scope.matchAll(EDIT_OPEN_RE)) {
+    if (parsedAt.has(m.index)) continue;
+    const rel = normalizeRepoPath(m[1]);
+    if (rel && !seen.has(rel)) malformed.push({ path: rel, reason: 'no closing fence' });
   }
 
   const deletes = [];
@@ -141,7 +172,7 @@ function extractFileBlocks(output) {
     if (rel && !deletes.includes(rel)) deletes.push(rel);
   }
 
-  return { files, edits, deletes, noChanges: false, reason: null };
+  return { files, edits, deletes, malformed, noChanges: false, reason: null };
 }
 
 /**
@@ -181,6 +212,30 @@ function applyEdit(fileContents, oldString, newString, repoPath) {
   return src.slice(0, idx) + String(newString) + src.slice(idx + anchor.length);
 }
 
+/**
+ * HC-GF-109 — apply every region edit for ONE file, as one change.
+ *
+ * The edits apply in the order the builder wrote them, each to the result of the ones before, and each OLD must occur
+ * exactly once at the moment it is applied — the single-edit rule, never a guess. Order is load-bearing in the stored
+ * builds: in run 1a8940af attempt 1 one edit's anchor was text the previous edit had inserted. Replayed over the 24
+ * stored edit blocks at each run's base commit, in-order application applies all of them, while finding every anchor
+ * in the original file rejects that build. An anchor an earlier edit changed fails as not found, and one an earlier NEW
+ * duplicated fails as ambiguous — both loud, and the message names the edit.
+ *
+ * @param {string} fileContents  real full file contents
+ * @param {Array<{oldString: string, newString: string}>} edits  in the order the builder wrote them
+ * @param {string} repoPath  for error messages
+ * @returns {string} the candidate file contents
+ * @throws {MaterializeError} code 'anchor_not_found' | 'anchor_ambiguous'
+ */
+function applyEdits(fileContents, edits, repoPath) {
+  let out = String(fileContents);
+  edits.forEach((e, i) => {
+    out = applyEdit(out, e.oldString, e.newString, edits.length > 1 ? `${repoPath} (edit ${i + 1} of ${edits.length})` : repoPath);
+  });
+  return out;
+}
+
 /** Non-overlapping occurrence count of `needle` in `hay` (literal, not regex). */
 function countOccurrences(hay, needle) {
   if (!needle) return 0;
@@ -211,6 +266,16 @@ function countOccurrences(hay, needle) {
 function buildDiff(blocks, { runGitDiff, readFile, exists, tmpFile }) {
   const parts = [];
 
+  // HC-GF-109: an edit block that could not be read is work that would otherwise vanish from the patch. Refuse the whole
+  // patch, as for a bad anchor: a partial patch passes verification and review as if it were the build.
+  const malformed = blocks.malformed || [];
+  if (malformed.length > 0) {
+    const more = malformed.length > 1 ? ` (and ${malformed.length - 1} more)` : '';
+    throw new MaterializeError('malformed_edit',
+      `${malformed[0].path}: edit block could not be read: ${malformed[0].reason}${more}. ` +
+      'Frame every region edit as <<<<<<< OLD, =======, >>>>>>> NEW lines inside its own fence.');
+  }
+
   // 1. Whole-file blocks (followup-23 Option A) — unchanged behaviour.
   for (const f of blocks.files) {
     const isNew = !exists(f.path);
@@ -225,18 +290,25 @@ function buildDiff(blocks, { runGitDiff, readFile, exists, tmpFile }) {
   }
 
   // 2. Region edits (followup-27) — apply OLD→NEW to the REAL file, git-diff it.
+  //    HC-GF-109: all of one file's edits together, one diff per file. Each edit used to be diffed against HEAD on its
+  //    own, and only the first edit per file ever reached this loop.
+  const editsByPath = new Map();
   for (const e of blocks.edits || []) {
-    const real = readFile(e.path);
+    if (!editsByPath.has(e.path)) editsByPath.set(e.path, []);
+    editsByPath.get(e.path).push(e);
+  }
+  for (const [repoPath, edits] of editsByPath) {
+    const real = readFile(repoPath);
     if (real == null) {
       throw new MaterializeError('file_not_found',
-        `${e.path}: cannot apply edit — file not found in the working tree`);
+        `${repoPath}: cannot apply edit — file not found in HEAD`);
     }
-    const candidate = applyEdit(real, e.oldString, e.newString, e.path); // throws typed on 0/many
+    const candidate = applyEdits(real, edits, repoPath); // throws typed on 0/many, naming the edit
     const t = tmpFile(candidate.endsWith('\n') ? candidate : candidate + '\n');
     try {
       const built = buildFileDiff({
-        repoPath: e.path, isNew: false,
-        runGitDiff: () => runGitDiff(e.path, t.path),
+        repoPath, isNew: false,
+        runGitDiff: () => runGitDiff(repoPath, t.path),
       });
       if (built.changed) parts.push(built.diff);
     } finally { t.cleanup(); }
@@ -372,6 +444,55 @@ function nodeMaterializeIO({ cwd = process.cwd() } = {}) {
   };
 }
 
+/**
+ * HC-GF-077 — the materialization IO for a diff that will be applied to HEAD.
+ *
+ * nodeMaterializeIO reads the working copy, and buildDiff hands git the original as a working-copy PATH.
+ * Every patch verb then applies the result to HEAD (verify-patch and emit-pr in a worktree cut from HEAD,
+ * check-patch now against an index read from HEAD). An editor leaves its edits in the working copy — the
+ * normal Path B flow — so the diff described a base it was never applied to. Measured on real runs: a
+ * byte-identical editor tree made verify-patch report "nothing to verify" with exit 0 for a failing suite,
+ * and a near-identical one made verify-patch and emit-pr report `does_not_apply` while check-patch said
+ * clean (6 of 6 runs).
+ *
+ * Same interface and the same temp-file/git-diff machinery as nodeMaterializeIO; only the three reads of
+ * the original change: existence (`git cat-file -e`), contents (`git show`), and the original handed to
+ * `git diff --no-index` (HEAD's blob in a temp file). Paths are repo-root-relative, as artifact paths are.
+ */
+function headMaterializeIO({ cwd = process.cwd(), rev = 'HEAD' } = {}) {
+  const { execFileSync } = require('node:child_process');
+  const { gitEnv } = require('./git-env');
+  const base = nodeMaterializeIO({ cwd });
+  const opts = { cwd, env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] };
+  const show = (rel) => {
+    try { return execFileSync('git', ['show', `${rev}:${rel}`], { ...opts, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }); }
+    catch { return null; }
+  };
+  return {
+    ...base,
+    exists: (rel) => { try { execFileSync('git', ['cat-file', '-e', `${rev}:${rel}`], opts); return true; } catch { return false; } },
+    readFile: show,
+    runGitDiff: (origArg, candPath) => {
+      if (origArg === '/dev/null') return base.runGitDiff(origArg, candPath);
+      const body = show(origArg);
+      if (body == null) return base.runGitDiff('/dev/null', candPath);
+      const t = base.tmpFile(body);
+      try { return base.runGitDiff(t.path, candPath); } finally { t.cleanup(); }
+    },
+  };
+}
+
+/**
+ * HC-GF-109 — whether parsed step output carries anything the patch verbs must materialize. One definition for
+ * check-patch, verify-patch and emit-pr, and it counts an edit block that failed to parse, so that output fails loudly
+ * in buildDiff instead of falling through to the legacy prose path.
+ */
+function hasMaterializableWork(blocks) {
+  if (!blocks) return false;
+  return blocks.files.length > 0 || (blocks.edits || []).length > 0 ||
+    (blocks.deletes || []).length > 0 || (blocks.malformed || []).length > 0;
+}
+
 module.exports = {
   extractFileBlocks,
   normalizeRepoPath,
@@ -379,7 +500,11 @@ module.exports = {
   buildFileDiff,
   buildDiff,
   nodeMaterializeIO,
+  headMaterializeIO,
   applyEdit,
+  applyEdits,
+  hasMaterializableWork,
+  EDIT_OPEN_RE,
   countOccurrences,
   ensureTrailingNewline,
   MaterializeError,

package/lib/mcp-tools.js

@@ -116,11 +116,20 @@ async function listWorkflows({ status, limit, cwd } = {}) {
   };
 }
 
+// HC-GF-106: `run-story <storyId> --kill|--approve` now resolves a story ID to that story's latest run.
+// Right for a person at a terminal; wrong behind a tool whose contract is an explicit run ID, where a
+// story ID is an agent's guess at a target. It used to fail only by accident (the server 404'd it), so
+// the tools that ACT on a run refuse anything that is not a run ID before shelling out.
+const { isRunId } = require('./run-target');
+const notARunId = (runId) =>
+  `runId must be a run ID (a UUID); ${JSON.stringify(String(runId))} is not. Get one from hone_run_story or hone_list_workflows.`;
+
 // hone_kill_workflow — kill ONE run by explicit id (DESTRUCTIVE, irreversible).
 // runId is schema-required: an agent must never guess a target for a kill —
 // explicit id or nothing (memo D3 refutation). Server 409s non-killable states.
 async function killWorkflow({ runId, cwd } = {}) {
   if (!runId) return { isError: true, detail: 'runId is required' };
+  if (!isRunId(String(runId))) return { isError: true, detail: notARunId(runId) };
   const r = await runHone(['run-story', String(runId), '--kill'], { cwd });
   if (r.error) return { isError: true, detail: r.error };
   return {
@@ -201,8 +210,10 @@ async function verifyPatch({ runId, report = false, cwd } = {}) {
   const r = await runHone(args, { cwd, timeoutMs: 600000 });
   if (r.error) return { isError: true, detail: r.error };
   const data = parseLastJson(r.stdout);
-  const verdict = data && (data.verdict || data.result) ? (data.verdict || data.result) : (r.ok ? 'pass' : 'fail');
-  return { isError: false, verdict, passed: r.ok, exitCode: r.exitCode, report: data, detail: (data && data.detail) || (r.ok ? 'tests passed' : 'tests failed') };
+  // HC-GF-077: `passed` is the verdict's, never the exit code's. verify-patch exited 0 for a run on which nothing
+  // executed, and this reported it to the editor agent as `passed: true, detail: 'tests passed'`.
+  const verdict = data && (data.verdict || data.result) ? (data.verdict || data.result) : 'unknown';
+  return { isError: false, verdict, passed: verdict === 'pass', exitCode: r.exitCode, report: data, detail: (data && data.detail) || (data ? `verdict: ${verdict}` : 'no verdict could be read from verify-patch') };
 }
 
 // hone_check_patch — does step_4's diff apply cleanly? (throwaway git apply --check)
@@ -235,8 +246,9 @@ async function verifyPr({ pr, report = false, workflowId, cwd } = {}) {
   const r = await runHone(args, { cwd, timeoutMs: 600000 });
   if (r.error) return { isError: true, detail: r.error };
   const data = parseLastJson(r.stdout);
-  const verdict = data && data.verdict ? data.verdict : (r.ok ? 'pass' : 'fail');
-  return { isError: false, verdict, passed: r.ok, exitCode: r.exitCode, report: data, detail: (data && data.detail) || (r.ok ? 'CI green' : 'CI red') };
+  // HC-GF-077: exit 0 includes `disabled` (ci.gate: none) — a gate nobody ran is not a green one.
+  const verdict = data && data.verdict ? data.verdict : 'unknown';
+  return { isError: false, verdict, passed: verdict === 'pass', exitCode: r.exitCode, report: data, detail: (data && data.detail) || (data ? `verdict: ${verdict}` : 'no verdict could be read from verify-pr') };
 }
 
 // hone_agent_eval — test the adopter's own agents (HC-COMM-011), optional report.
@@ -263,9 +275,15 @@ async function showStep({ runId, stepKey, cwd } = {}) {
 }
 
 // hone_approve — approve a paused human gate (run-story --approve).
-async function approve({ runId, stepKey, cwd } = {}) {
+async function approve({ runId, stepKey, acknowledgeAbort = false, acknowledgeFailedVerdict = false, cwd } = {}) {
   if (!runId || !stepKey) return { isError: true, detail: 'runId and stepKey are required' };
-  const r = await runHone(['run-story', String(runId), '--approve', String(stepKey)], { cwd });
+  if (!isRunId(String(runId))) return { isError: true, detail: notARunId(runId) }; // HC-GF-106: never approve a guessed run
+  // HC-GF-069 / HC-GF-074: an editor agent must be able to pass the same explicit acknowledgements a human can —
+  // and only when asked; the refusals exist because an unattended approver defeats a pause.
+  const args = ['run-story', String(runId), '--approve', String(stepKey)];
+  if (acknowledgeAbort === true) args.push('--acknowledge-abort');
+  if (acknowledgeFailedVerdict === true) args.push('--acknowledge-failed-verdict');
+  const r = await runHone(args, { cwd });
   if (r.error) return { isError: true, detail: r.error };
   return { isError: !r.ok, exitCode: r.exitCode, detail: (r.ok ? `approved ${stepKey}` : (r.stderr || r.stdout || 'approve failed')).slice(0, 500) };
 }
@@ -343,7 +361,10 @@ const TOOLS = [
     name: 'hone_approve',
     description: 'Approve a paused human gate on a run so it advances (e.g. stepKey "step_4").',
     readOnly: false,
-    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, stepKey: { type: 'string' } }, required: ['runId', 'stepKey'] },
+    inputSchema: { type: 'object', properties: { runId: { type: 'string' }, stepKey: { type: 'string' },
+      acknowledgeAbort: { type: 'boolean', default: false, description: 'Approve a step the agent aborted (read its reason first).' },
+      acknowledgeFailedVerdict: { type: 'boolean', default: false, description: 'Approve a step whose verification did not pass under enforce (read the failing gates first).' } },
+      required: ['runId', 'stepKey'] },
     handler: approve,
   },
   {

package/lib/poll-decision.js

@@ -27,11 +27,15 @@
 
 const { isEditorParked } = require('./editor-park');
 
+/** HC-GF-075: equal to server/src/services/validator-exhaustion.js EXHAUSTION_PREFIX (pinned by test). */
+const EXHAUSTION_PREFIX = 'GARBAGE_OUTPUT at ';
+
 const POLL_OUTCOMES = Object.freeze({
   COMPLETED: 'completed',
   TERMINAL_FAILURE: 'terminal_failure',
   EDITOR_PARKED: 'editor_parked',
   HUMAN_GATE: 'human_gate',
+  EXHAUSTED: 'exhausted',
   RUNNING: 'running',
 });
 
@@ -40,6 +44,8 @@ const EXIT = Object.freeze({
   [POLL_OUTCOMES.COMPLETED]: 0,
   [POLL_OUTCOMES.TERMINAL_FAILURE]: 1,
   [POLL_OUTCOMES.HUMAN_GATE]: 2,
+  // HC-GF-075: a human decision, so the same contract as a gate — adopter CI already handles 2.
+  [POLL_OUTCOMES.EXHAUSTED]: 2,
   [POLL_OUTCOMES.EDITOR_PARKED]: 3,
   [POLL_OUTCOMES.RUNNING]: null,
 });
@@ -73,6 +79,15 @@ function classifyPollState(status) {
         stepKey: s.currentStep, agent: step && step.agent,
       });
     }
+    // HC-GF-075: a step that used up its format retries is a decision, not a gate on an
+    // artifact — approving it starts another cycle of the step. Classified BEFORE the gate so
+    // the CLI does not auto-verify the rejected attempt and report a verdict as if it were the
+    // build. The prefix must equal the server's EXHAUSTION_PREFIX; a test pins the two.
+    if (String(s.errorMessage || '').startsWith(`${EXHAUSTION_PREFIX}${s.currentStep} `)) {
+      return decide(POLL_OUTCOMES.EXHAUSTED, {
+        stepKey: s.currentStep, agent: step && step.agent, errorMessage: s.errorMessage,
+      });
+    }
     // HC-GF-064 keys its at-most-once verification on the ATTEMPT: a retried step is a
     // new artifact and deserves a new verdict, while re-verifying the SAME attempt on
     // every tick is the unbounded advisory loop that story had to fix before merge.
@@ -89,4 +104,4 @@ function classifyPollState(status) {
   });
 }
 
-module.exports = { classifyPollState, POLL_OUTCOMES, EXIT };
+module.exports = { classifyPollState, POLL_OUTCOMES, EXIT, EXHAUSTION_PREFIX };

package/lib/run-report.js

@@ -19,6 +19,15 @@
 /** Gate verdicts the pipeline already speaks. Do not invent synonyms. */
 const ACTIONABLE_GATE_VERDICTS = ['fail', 'unavailable'];
 
+/**
+ * HC-GF-008: the verification verdicts that leave nothing outstanding. `disabled` is verify-pr's record of
+ * an explicit `ci.gate: none`. Everything else — including a value this file has never seen — is an item,
+ * so a renamed or added verdict becomes a visible line rather than silence.
+ */
+const CLEAR_VERIFICATION_VERDICTS = ['pass', 'disabled'];
+/** The ones that gate the script exit. `unresolved` gates because an absent command used to report `fail`. */
+const GATING_VERIFICATION_VERDICTS = ['fail', 'timeout', 'unresolved'];
+
 function pad(s, n) { return String(s).padEnd(n); }
 
 /**
@@ -38,6 +47,37 @@ function durationOf(startedAt, endedAt) {
  * @param {object} run  the GET /:runId projection
  * @param {{cost?: {metered:number, notional:number}}} [extra]
  */
+/**
+ * HC-GF-046(b): the error codes on which approving is REFUSED — and nothing else.
+ *
+ * This must equal exactly what `checkGuardrails` emits, because the report tells the
+ * operator "approving will be refused" for these. The first version was a hand-typed list
+ * written from memory, and one of its four entries was right: MAX_STEPS_EXCEEDED was the
+ * wrong string (the real code is MAX_TOTAL_STEPS_EXCEEDED), BUDGET_EXCEEDED could never
+ * match the prefixed TOKEN_/BATCH_BUDGET_EXCEEDED past the ^ anchor, and GARBAGE_OUTPUT is
+ * not a guardrail refusal at all — approveGate accepts it. It is not an ordinary gate either;
+ * see EXHAUSTED_RE below.
+ *
+ * Exported so a test pins it equal to the enforcer's own reason codes. The enforcer lives in
+ * the server package and this in the CLI package, so they cannot share a constant at
+ * runtime; the equality is asserted in CI instead, which is where drift would be caught.
+ */
+const BLOCKING_REASON_CODES = Object.freeze(['MAX_RETRIES_EXCEEDED', 'MAX_TOTAL_STEPS_EXCEEDED']);
+const BLOCKING_REASON_RE = new RegExp(`^(${BLOCKING_REASON_CODES.join('|')})[^\\n]*`);
+
+/**
+ * HC-GF-046(b), corrected in review: a step that used up its format retries.
+ *
+ * This first shipped as an ordinary gate ("a gate is waiting on your judgment"), on the claim
+ * that approving past it started a real attempt — a3, a4 and a5 on run 5f1a7f75. An independent
+ * review refuted that from the rows: a3 was the automatic retry, a4 and a5 were route-backs from
+ * step_5, and the one approval of that pause re-ran nothing. approveGate closes the step's
+ * in-flight rows and moves on, so later steps read the most recent EARLIER attempt — on
+ * 5f1a7f75, the build step_5 had already rejected. "Gate" invites exactly that. HC-GF-075 then
+ * changed what approving does — it retries the step — and this line says so.
+ */
+const EXHAUSTED_RE = /^GARBAGE_OUTPUT at (step_[0-9a-z]+)/;
+
 function buildReport(run, extra = {}) {
   const cfg = run.config || {};
   const steps = Array.isArray(run.steps) ? run.steps : [];
@@ -61,15 +101,29 @@ function buildReport(run, extra = {}) {
     // A resumable pause — a local rate-limit window, for instance — is not a refusal, and
     // silencing a real gate on those would be the over-reach that makes the surface
     // untrustworthy in the other direction.
-    const blocked = String(run.errorMessage || '')
-      .match(/^(MAX_RETRIES_EXCEEDED|MAX_STEPS_EXCEEDED|BUDGET_EXCEEDED|GARBAGE_OUTPUT)[^\n]*/);
-    if (blocked) {
+    const blocked = String(run.errorMessage || '').match(BLOCKING_REASON_RE);
+    const exhausted = String(run.errorMessage || '').match(EXHAUSTED_RE);
+    if (run.approvalRefusal) {
+      // HC-GF-074: rendered from the server's own decision, never re-derived from verdict records here.
+      needsYou.push({
+        what: `run CANNOT be approved at ${run.currentStep} as it stands — ${String(run.approvalRefusal.message).slice(0, 300)}`,
+        how: `fix and re-verify (hone verify-patch ${run.runId} --report), or hone run-story ${run.runId} --approve ${run.currentStep} --acknowledge-failed-verdict`,
+      });
+    } else if (blocked) {
       needsYou.push({
         what: `run CANNOT proceed at ${run.currentStep} — ${blocked[0].slice(0, 160)}. `
           + 'Approving will be refused by the guardrail, so this is a decision, not a gate',
         how: `hone run-story ${run.runId} --kill   (or raise guardrails.max_retries_per_step `
           + 'in .pipeline-config.yml and re-run the story)',
       });
+    } else if (exhausted) {
+      const s = exhausted[1];
+      needsYou.push({
+        what: `run is paused at ${s} — ${s} used up its format retries. Approving starts another cycle `
+          + `of ${s} with a fresh format budget; it does not accept an earlier attempt`,
+        how: `hone show step ${run.runId} ${s}   (then --approve ${s} to retry, or --kill; `
+          + 'guardrails.max_retries_per_step caps the cycles)',
+      });
     } else {
       needsYou.push({
         what: `run is paused at ${run.currentStep} — a gate is waiting on your judgment`,
@@ -169,6 +223,35 @@ function buildReport(run, extra = {}) {
     });
   }
 
+  // HC-GF-050: a cycle that changed nothing, and attempts escalating toward the ceiling. Computed by the server from every
+  // attempt (GET /:runId `convergence`) and rendered here, never re-derived. ADVISORY: a new signal reports before it gates
+  // (HC-026c), and a story that legitimately needs three cycles must not flip a script's exit status. When cycles were
+  // compared and none was flagged, say what was compared — absence must not read as not-checked.
+  const conv = run.convergence;
+  if (conv) {
+    for (const u of conv.unchanged || []) {
+      needsYou.push({
+        what: `a cycle changed nothing — ${u.detail}`,
+        how: `hone show step ${run.runId} step_4 --attempt ${u.attempts[u.attempts.length - 1]}`,
+        howLabel: 'inspect',
+        advisory: true,
+      });
+    }
+    if (conv.escalating) {
+      needsYou.push({
+        what: `each build attempt runs longer and produces more — ${conv.escalating.detail}`,
+        how: `hone show step ${run.runId} step_4 --attempt ${conv.escalating.attempts[conv.escalating.attempts.length - 1]}`,
+        howLabel: 'inspect',
+        advisory: true,
+      });
+    }
+    const ex = conv.examined || {};
+    if (!(conv.unchanged || []).length && !conv.escalating && (ex.reviewCycles || ex.repeatedFailurePairs)) {
+      worthKnowing.push(`convergence: compared ${ex.reviewCycles} review cycle(s) and ${ex.repeatedFailurePairs} repeated failure(s) `
+        + `across ${ex.builds} build attempt(s) — each rebuild changed materially (${ex.criteria})`);
+    }
+  }
+
   // 1d. HC-GF-041: two diagnostics the orchestrator has stamped since HC-019n-followup-41
   // and -43, which NOTHING has ever read on this path — the run payload carried only
   // token counts until the `diagnostics` projection was added. HC-GF-016's row specifies
@@ -191,6 +274,18 @@ function buildReport(run, extra = {}) {
       worthKnowing.push(
         `${s.stepKey} dropped composed guardrail section(s) on a retry and was accepted (budget spent): ${d.composed_missing.join(', ')}`);
     }
+    // HC-GF-059: this build contains files the attempt did not write. Advisory — they are the previous build's files,
+    // unchanged, and whoever approves should read them as that build's content.
+    if (d.carried_forward && Array.isArray(d.carried_forward.paths) && d.carried_forward.paths.length) {
+      needsYou.push({
+        what: `${s.stepKey} attempt ${s.attempt} did not re-emit ${d.carried_forward.paths.length} planned file(s); they were `
+          + `carried forward unchanged from attempt ${d.carried_forward.from_attempt} — review them as that build's content`,
+        detail: d.carried_forward.paths.map(String),
+        how: `hone show step ${run.runId} ${s.stepKey} --attempt ${s.attempt}`,
+        howLabel: 'inspect',
+        advisory: true,
+      });
+    }
   }
 
   // 2. The last verification is ONE event, so it becomes ONE item with sub-lines.
@@ -205,12 +300,15 @@ function buildReport(run, extra = {}) {
   const lastVerification = verifications[verifications.length - 1] || null;
   if (lastVerification) {
     const bad = (lastVerification.gates || []).filter(g => ACTIONABLE_GATE_VERDICTS.includes(g.verdict));
-    const failed = lastVerification.verdict === 'fail' || lastVerification.verdict === 'timeout';
+    // HC-GF-008: "not a pass" is the enforcer's rule (verification-refusal `failingVerdict`), so it is the
+    // report's. Listing the failing values instead left `does_not_apply`, `error` — and the new `unresolved`,
+    // which an absent command used to report as a gating `fail` — rendering "nothing outstanding".
+    const failed = !CLEAR_VERIFICATION_VERDICTS.includes(lastVerification.verdict);
     if (failed || bad.length) {
       const stepKey = lastVerification.stepKey || 'step_4';
       needsYou.push({
         what: failed
-          ? `verification ${lastVerification.verdict} on ${stepKey}`
+          ? `${lastVerification.verdict === 'unresolved' ? 'verification could not run' : `verification ${lastVerification.verdict}`} on ${stepKey}`
             + `${lastVerification.detail ? ` — ${lastVerification.detail}` : ''}`
           : `${bad.length} gate(s) not passing on ${stepKey}`,
         // Sub-lines carry the per-gate verdicts, so one glance separates
@@ -220,6 +318,10 @@ function buildReport(run, extra = {}) {
              + `${g.command ? `   [${g.command}]` : ''}`),
         how: `hone verify-patch ${run.runId} ${stepKey} --keep`,
         howLabel: 'reproduce',
+        // Report before gating (HC-026c): verdicts this report used to swallow are shown in full but do not flip
+        // the script exit yet. `unresolved` is not one of them — a report must not stop gating a run on which
+        // nothing was run.
+        ...(failed && !bad.length && !GATING_VERIFICATION_VERDICTS.includes(lastVerification.verdict) ? { advisory: true } : {}),
       });
     }
   }
@@ -302,6 +404,8 @@ function buildReport(run, extra = {}) {
     // HC-GF-065: what the exit code should count. Advisory items are shown but do not
     // gate, so a new signal cannot silently change the meaning of a script's exit status.
     gatingCount: needsYou.filter(i => !i.advisory).length,
+    // HC-GF-050: carried so the empty NEEDS YOU can name convergence among what was checked.
+    convergence: run.convergence || null,
   };
 }
 
@@ -344,6 +448,7 @@ function renderReport(r) {
       checked.push('verification');
       for (const g of last.gates || []) checked.push(g.name);
     }
+    if (r.convergence) checked.push('convergence');
     // HC-GF-065: the empty state is only reachable when something was actually CHECKED.
     // With no verdict there is nothing executed against the diff, so "nothing outstanding"
     // asserts knowledge the report does not have — the missing verification is now an
@@ -384,4 +489,4 @@ function renderReport(r) {
   return L.join('\n');
 }
 
-module.exports = { buildReport, renderReport, durationOf, ACTIONABLE_GATE_VERDICTS };
+module.exports = { BLOCKING_REASON_CODES, buildReport, renderReport, durationOf, ACTIONABLE_GATE_VERDICTS };