@hone-ai/cli 1.32.0 → 1.34.0

package/lib/materialize-diff.js

@@ -37,7 +37,18 @@ const path = require('node:path');
  * perfectly valid. Line-anchoring is also strictly better for a body that
  * contains an indented or info-tagged fence of its own.
  */
-const FILE_BLOCK_RE = /^[ \t]*```[ \t]*file[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*\r?$/gim;
+/**
+ * HC-GF-127: the fence is 3 OR MORE backticks, and the closer must MATCH the opener (backreference).
+ *
+ * It used to be exactly three, so a block closed on the first ``` line inside it: a README carrying
+ * a ```js sample ended AT the sample, the rest was lost, and `malformed` came back empty — the
+ * artifact looked valid and materialized to the wrong bytes. Widening the opener alone would not
+ * help; only a matching closer lets a wider fence carry content that contains a narrower one.
+ *
+ * 3-backtick blocks parse exactly as before: `\1` on a 3-backtick opener IS the old literal. Pinned
+ * against 48 artifacts captured from real runs.
+ */
+const FILE_BLOCK_RE = /^[ \t]*(`{3,})[ \t]*file[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?\n([\s\S]*?)^[ \t]*\1[ \t]*\r?$/gim;
 
 /**
  * The line-anchored closer necessarily absorbs the newline that terminates the
@@ -58,14 +69,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]*`{3,}[ \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 +112,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 +121,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 +130,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 };
@@ -115,24 +140,42 @@ function extractFileBlocks(output) {
   const files = [];
   const seen = new Set();
   for (const m of scope.matchAll(FILE_BLOCK_RE)) {
-    const rel = normalizeRepoPath(m[1]);
+    // HC-GF-127: m[1] is the fence itself now, so the path and body moved to m[2]/m[3].
+    const rel = normalizeRepoPath(m[2]);
     if (!rel) continue;            // rejected (traversal/absolute) — see below
     if (seen.has(rel)) continue;   // first block wins on a dup path
     seen.add(rel);
-    files.push({ path: rel, contents: blockBody(m[2]) });
+    files.push({ path: rel, contents: blockBody(m[3]) });
   }
 
   // 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 +184,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 +224,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 +278,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 +302,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 +456,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 +512,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 {
@@ -155,18 +164,39 @@ async function stepInstruction({ runId, cwd } = {}) {
 // hone_submit_step — submit editor-executed output (HC-COMM-010 B3). Output
 // travels via a temp file (1MB-class payloads must not ride argv); the file
 // is best-effort deleted after the shell-out.
-async function submitStep({ runId, stepKey, output, contractVersion = '1', cwd } = {}) {
+async function submitStep({ runId, stepKey, output, contractVersion = '1', fromTree = false, testReport, cwd } = {}) {
   if (!runId) return { isError: true, detail: 'runId is required' };
   if (!stepKey) return { isError: true, detail: 'stepKey is required' };
-  if (typeof output !== 'string' || output.trim() === '') {
-    return { isError: true, detail: 'output is required (the complete step output text)' };
+
+  // HC-GF-130: DELEGATE the from-tree render to the CLI rather than rendering here and submitting
+  // the result with `--file`. That is what shipped in HC-GF-091, and HC-GF-092's guard — which
+  // refuses `--contract 2` without `--from-tree` — turned the one caller that HAD built from the
+  // tree away. The guard reads the flag, not the provenance, so the adopter's primary path was
+  // blocked while the CLI fallback worked. Delegating also removes a second producer of the same
+  // artifact, which is the shape HC-GF-127 had to unpick across three parsers.
+  const hasOutput = typeof output === 'string' && output.trim() !== '';
+  if (fromTree && hasOutput) {
+    return { isError: true, detail: 'pass output OR fromTree, not both: they are two different claims about where the build is' };
   }
-  const tmp = path.join(os.tmpdir(), `hone-editor-output-${Date.now()}-${process.pid}.txt`);
-  try {
+  if (!fromTree && !hasOutput) {
+    return { isError: true, detail: 'output is required (the complete step output text), or set fromTree' };
+  }
+
+  const base = ['submit-step', String(runId), String(stepKey), '--contract', String(contractVersion), '--format', 'json'];
+  let tmp = null;
+  if (fromTree) {
+    base.push('--from-tree');
+    // Never invented: an absent report stays absent, the same rule the CLI and the prompt carry.
+    if (typeof testReport === 'string' && testReport.trim() !== '') base.push('--test-report', testReport);
+  } else {
+    // Output travels via a temp file — 1MB-class payloads must not ride argv.
+    tmp = path.join(os.tmpdir(), `hone-editor-output-${Date.now()}-${process.pid}.txt`);
     fsSync.writeFileSync(tmp, output, 'utf8');
-    const r = await runHone(
-      ['submit-step', String(runId), String(stepKey), '--file', tmp, '--contract', String(contractVersion), '--format', 'json'],
-      { cwd });
+    base.push('--file', tmp);
+  }
+
+  try {
+    const r = await module.exports._internal.runHone(base, { cwd });
     if (r.error) return { isError: true, detail: r.error };
     const data = parseLastJson(r.stdout);
     return {
@@ -179,7 +209,7 @@ async function submitStep({ runId, stepKey, output, contractVersion = '1', cwd }
         : (r.stderr || r.stdout || 'submission failed').slice(0, 500),
     };
   } finally {
-    try { fsSync.unlinkSync(tmp); } catch { /* best-effort cleanup */ }
+    if (tmp) { try { fsSync.unlinkSync(tmp); } catch { /* best-effort cleanup */ } }
   }
 }
 
@@ -201,8 +231,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 +267,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 +296,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 +382,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,
   },
   {
@@ -411,10 +453,12 @@ const TOOLS = [
       properties: {
         runId: { type: 'string' },
         stepKey: { type: 'string' },
-        output: { type: 'string' },
+        output: { type: 'string', description: 'The complete step output text. Omit when fromTree is true.' },
         contractVersion: { type: 'string', default: '1' },
+        fromTree: { type: 'boolean', default: false, description: 'HC-GF-091: render the artifact from the working tree against HEAD — write the files with your own tools first, then submit. Removes the single-response output ceiling.' },
+        testReport: { type: 'string', description: 'With fromTree: your test-run report, carried verbatim. Omit if you did not run them; it is never invented for you.' },
       },
-      required: ['runId', 'stepKey', 'output'],
+      required: ['runId', 'stepKey'],
     },
     handler: submitStep,
   },
@@ -434,4 +478,6 @@ module.exports = {
   killWorkflow,
   runStory, status, verifyPatch, checkPatch, showStep, approve, emitPr, verifyPr, agentEval, derive, sync, doctor,
   runHone, parseRunStarted, parseLastJson, honeBin, readHoneConfig, TOOLS,
+  // HC-GF-130: exposed so a test can observe the argv handed to the CLI without running it.
+  _internal: { runHone },
 };

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 };