@hone-ai/cli 1.31.0 → 1.33.0

package/lib/auto-verify.js

@@ -146,4 +146,42 @@ function alreadyVerified(attemptKey, verifiedAttempts) {
   return Boolean(verifiedAttempts && verifiedAttempts.has(attemptKey));
 }
 
-module.exports = { decideAutoVerify, announce, readVerificationAuto, shouldRepoll, alreadyVerified, VERIFIABLE_STEP };
+/**
+ * The line printed after a verdict is posted.
+ *
+ * HC-GF-070: this used to end in a hardcoded `(advisory)`. On the acceptance run for that
+ * story the gate was `enforce` and the verdict AUTO-APPROVED step_4 — the run advanced
+ * with no human involved — while the CLI told the operator the verdict was advisory. A
+ * constant cannot be wrong about the run it is describing, which is the same
+ * cannot-fail shape as a check that never fires, arriving in the output layer: it
+ * understates the one case where the verdict actually changed something.
+ */
+function verdictReportLine(verdict, gate) {
+  const mode = gate === 'enforce' ? 'enforce' : 'advisory';
+  const effect = mode === 'enforce'
+    ? 'enforce — a passing verdict approves this gate'
+    : 'advisory — records only, the gate still needs a human';
+  return `  → reported verdict '${verdict}' to the server (${effect})`;
+}
+
+/**
+ * HC-GF-008 — the line run-story prints after auto-verify's `verify-patch` exits, keyed by that exit code.
+ *
+ * It said "verification did not pass" for every non-zero exit. On TICK-002 (run 5f1a7f75) that line sat
+ * directly under `✗ step_4 produced no file changes to verify.` — nothing had run, because the build's
+ * output had been discarded (HC-GF-075). Only a failing or timed-out command is a verification that did
+ * not pass; every other exit is a verification that did not happen, and says which.
+ */
+function verifyOutcomeLine(status, gate) {
+  const { EXIT } = require('./verify-patch');
+  switch (status) {
+    case EXIT.PASS: return `  → verified and recorded (gate: ${gate}). The gate still needs you.`;
+    case EXIT.TESTS_FAILED: case EXIT.TIMEOUT: return '  → verification did not pass; the gate still needs you.';
+    case EXIT.UNRESOLVED: return '  → verification could not run (see above) — nothing is known about this build; the gate still needs you.';
+    case EXIT.NO_DIFF: return '  → nothing was verified: no diff to apply, or the step output could not be fetched (see above); the gate still needs you.';
+    case EXIT.DOES_NOT_APPLY: return '  → nothing was verified: the diff did not apply (see above); the gate still needs you.';
+    default: return `  → verify-patch exited ${status} without a verdict (see above); the gate still needs you.`;
+  }
+}
+
+module.exports = { decideAutoVerify, announce, readVerificationAuto, shouldRepoll, alreadyVerified, verdictReportLine, verifyOutcomeLine, VERIFIABLE_STEP };

package/lib/emit-pr.js

@@ -34,6 +34,7 @@ const EXIT = {
   TIMEOUT: 4,         // --verify test command timed out
   BRANCH_CONFLICT: 5, // local branch already exists (not overwritten)
   PUBLISH_FAILED: 6,  // push or gh pr create failed (no remote / no auth / rejected)
+  UNRESOLVED: 7,      // --verify could not start the test command (HC-GF-008) — no commit made
 };
 
 /**

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

@@ -0,0 +1,107 @@
+'use strict';
+/**
+ * poll-decision.js — HC-GF-070: what the poll loop should DO about one status payload.
+ *
+ * WHY THIS IS ITS OWN MODULE. The loop had exactly one entry point — the initial
+ * `run-story <storyId>` — and `--approve` returned without polling, so every automated
+ * flow exited blind after each gate. Making `--approve` poll means calling the same loop
+ * from a second place, and the only way to do that safely is for its DECISIONS to be a
+ * pure function of the payload rather than control flow tangled through 130 lines of
+ * printing, prompting and process.exit.
+ *
+ * The ordering of the branches is the load-bearing part, and each ordering below is a
+ * bug a hand-written driver actually shipped in this session:
+ *
+ *   terminal BEFORE gate      a killed run carrying a stale `awaitingApproval` offered a
+ *                             gate to a driver whose run was already dead
+ *   park BEFORE human gate    an editor-parked step is satisfied by the EDITOR; the
+ *                             server refuses `--approve` there, so a driver that read it
+ *                             as a human gate would approve into a rejection forever
+ *   awaitingApproval required a run can be `paused` while the server decides what is
+ *                             next; treating that as a gate approves a step nobody asked
+ *                             for, which is HC-GF-069 in miniature
+ *
+ * Everything unknown classifies as RUNNING. Inventing a terminal state for a status we
+ * have not seen would end a live run; polling one more tick costs an interval.
+ */
+
+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',
+});
+
+/** Exit codes are a CONTRACT with adopter CI: 2 = human gate, 3 = editor park. */
+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,
+});
+
+const decide = (outcome, extra = {}) => ({ outcome, exitCode: EXIT[outcome], ...extra });
+
+/**
+ * @param {object|null|undefined} status  a `GET /orchestrate/:runId` payload, straight
+ *                                        off the network and therefore not trusted to
+ *                                        have any particular shape
+ * @returns {{outcome:string, exitCode:number|null, stepKey?:string, agent?:string,
+ *            attemptKey?:string, totalTokens?:number, errorMessage?:string}}
+ */
+function classifyPollState(status) {
+  const s = (status && typeof status === 'object') ? status : {};
+  const steps = Array.isArray(s.steps) ? s.steps : [];
+
+  if (s.status === 'completed') {
+    return decide(POLL_OUTCOMES.COMPLETED, { totalTokens: s.totalTokens || 0 });
+  }
+  if (s.status === 'failed' || s.status === 'killed') {
+    return decide(POLL_OUTCOMES.TERMINAL_FAILURE, {
+      errorMessage: s.errorMessage || 'unknown', runStatus: s.status,
+    });
+  }
+
+  if (s.status === 'paused' && s.awaitingApproval) {
+    const step = steps.find((x) => x && x.stepKey === s.currentStep);
+    if (isEditorParked(s)) {
+      return decide(POLL_OUTCOMES.EDITOR_PARKED, {
+        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.
+    const attempt = (step && step.attempt) || 1;
+    return decide(POLL_OUTCOMES.HUMAN_GATE, {
+      stepKey: s.currentStep, agent: step && step.agent,
+      attemptKey: `${s.currentStep}#${attempt}`,
+    });
+  }
+
+  const running = steps.find((x) => x && x.status === 'running');
+  return decide(POLL_OUTCOMES.RUNNING, {
+    stepKey: running && running.stepKey, agent: running && running.agent,
+  });
+}
+
+module.exports = { classifyPollState, POLL_OUTCOMES, EXIT, EXHAUSTION_PREFIX };