@hone-ai/cli 1.32.0 → 1.34.0

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
@@ -179,6 +262,42 @@ function buildReport(run, extra = {}) {
   // "none" would be a claim the report cannot support for a run that never ran the check.
   for (const s of steps) {
     const d = s.diagnostics || {};
+    // HC-GF-089: how close this step came to its limits. worthKnowing, never needsYou — approaching
+    // a limit is not an action item, and an advisory that reads like one trains operators to ignore
+    // it. Absent when the server projected no headroom fields, which means "nothing to judge".
+    //
+    // Computed inline rather than imported: this module is deliberately dependency-free (see the
+    // header), and the numbers come from stored data like every other line here. cli/lib/headroom.js
+    // owns the same thresholds for the status surface, and HC-GF-089's tests pin the two agree.
+    const hr = d.headroom;
+    if (hr && typeof hr === 'object') {
+      const el = Number(hr.elapsed_ms);
+      const to = Number(hr.timeout_ms);
+      const toks = (Array.isArray(hr.output_tokens) ? hr.output_tokens : [])
+        .map(Number).filter((n) => Number.isFinite(n) && n >= 0);
+      const busiest = toks.length ? Math.max(...toks) : null;
+      const near = [];
+      if (Number.isFinite(el) && Number.isFinite(to) && to > 0 && el / to >= 0.75) {
+        near.push(`time ${Math.round((el / to) * 100)}% (${Math.round(el / 1000)}s of ${Math.round(to / 1000)}s)`);
+      }
+      if (busiest !== null && busiest / 128000 >= 0.75) {
+        near.push(`tokens ${Math.round((busiest / 128000) * 100)}% (${busiest} of 128000 in one message)`);
+      }
+      // HC-GF-129: `>= 0.75` has no upper bound, so this said "not over it" about a call that had
+      // gone over and died (run 692b0c29: 550,017ms of a 550,000ms ceiling, cut off). The wording
+      // and the PLACEMENT are wrong together — worthKnowing is right for a near miss, and wrong
+      // for a call that actually hit its limit, which is exactly what an operator needs to see.
+      const overTime = Number.isFinite(el) && Number.isFinite(to) && to > 0 && el >= to;
+      const overTokens = busiest !== null && busiest >= 128000;
+      if (near.length && (overTime || overTokens)) {
+        needsYou.push({
+          what: `${s.stepKey} headroom: ${near.join(', ')} — the limit was REACHED: that call was cut off`,
+          how: `hone show step ${run.runId} ${s.stepKey}`,
+        });
+      } else if (near.length) {
+        worthKnowing.push(`${s.stepKey} headroom: ${near.join(', ')} — close to the limit, not over it`);
+      }
+    }
     if (Array.isArray(d.invented_paths) && d.invented_paths.length) {
       needsYou.push({
         what: `${s.stepKey} named ${d.invented_paths.length} path(s) that do not exist in the repo, and was accepted anyway`,
@@ -191,6 +310,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 +336,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 +354,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 +440,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 +484,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 +525,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 };

package/lib/run-target.js

@@ -0,0 +1,97 @@
+'use strict';
+/**
+ * HC-GF-106 — the ONE place a `run-story` verb turns its argument into the run it acts on.
+ *
+ * `--status`, `--kill` and `--approve` each forwarded the argument verbatim (`runId || storyIdOrRunId`),
+ * so a story ID reached the server as a run ID and the route's UUID check answered `Run not found` —
+ * while `--help` promised "the latest workflow run for this story". Observed 2026-09-11:
+ * `hone run-story TICK-002 --kill` printed `Failed: Run not found` and left the paused run untouched.
+ * Every verb that acts on an existing run resolves here, so no two of them can disagree about which
+ * run that is, and none can fall back to sending the story ID.
+ *
+ * HC-GF-108 — the lookup asks the server for the story in the repository (`storyId`, `repoName`)
+ * instead of reading the org's 100 most recent runs, which reported "not found" for a story whose runs
+ * were all older than that. It still filters every row itself: a server that predates the filters
+ * ignores them and returns the org's most recent runs, and whatever this returns is posted to.
+ *
+ * I/O is the injected `client` (the CLI's axios instance). No console, no exit — the caller renders
+ * `error` and decides the exit code.
+ */
+
+const RUN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// GET /orchestrate clamps `limit` to 1..100, lists newest first, and is scoped to the caller's org.
+// Filtered, its first row IS the story's latest run in the repository. From a server that ignores the
+// filters, the first match in the widest window is the latest run whenever that run is in the window —
+// and when it is not, the lookup says "not found" rather than picking an older one.
+const LOOKUP_LIMIT = 100;
+
+const isRunId = (s) => typeof s === 'string' && RUN_ID.test(s);
+
+/**
+ * One GET /orchestrate. `filtered` is true only when the server echoed every filter sent: a server
+ * that predates the filters echoes none of them and lists the org's most recent runs instead.
+ */
+async function listRuns(client, filters) {
+  const qs = new URLSearchParams({ limit: String(LOOKUP_LIMIT), ...filters });
+  const { data } = await client.get(`/orchestrate?${qs}`);
+  const runs = Array.isArray(data && data.runs) ? data.runs : [];
+  const filtered = Object.entries(filters).every(([k, v]) => Boolean(data) && data[k] === v);
+  return { runs, filtered };
+}
+
+/**
+ * @param {object} p
+ * @param {{ get(path: string): Promise<{ data: any }> }} p.client
+ * @param {string} p.idOrStory  what the operator typed: a run ID or a story ID
+ * @param {string} p.repoName   the repository a story ID is scoped to — the name the start path records
+ * @param {string} p.flag       the verb as typed (e.g. `--kill`, `--approve step_0`), for the hint
+ * @returns {Promise<{ runId: string, run: object|null, source: 'run-id'|'story' } | { error: string }>}
+ *          Rejects only when the lookup request itself fails.
+ */
+async function resolveRunTarget({ client, idOrStory, repoName, flag }) {
+  if (isRunId(idOrStory)) return { runId: idOrStory, run: null, source: 'run-id' };
+
+  const byRunId = `pass a run ID instead: hone run-story <runId> ${flag}`;
+  // Nothing to look up: an empty story ID, or a checkout at `/`, whose directory name is empty. Said here,
+  // rather than as the server's 400 for an empty filter, which names a query parameter nobody typed.
+  if (!idOrStory || !repoName) {
+    return {
+      error: `Cannot look up a run without a story ID and a repository name (story ${JSON.stringify(idOrStory || '')}, repository ${JSON.stringify(repoName || '')}).\n`
+        + `  Name the repository with --repo <name>, or ${byRunId}`,
+    };
+  }
+
+  // A row for another story, or whose id is not a run ID, is never a target — whichever server answered.
+  const forStory = (runs) => runs.filter(r => r && r.story_id === idOrStory && isRunId(r.id));
+
+  const here = await listRuns(client, { storyId: idOrStory, repoName });
+  const run = forStory(here.runs).find(r => r.repo_name === repoName);
+  if (run) return { runId: run.id, run, source: 'story' };
+
+  // Not in this repository — so where does the story have runs? A filtering server needs a story-only
+  // lookup to say; one that ignored the filters already returned everything this lookup can see. The
+  // answer is "not found" either way, so a failed hint lookup costs the hint, never the answer.
+  const wide = here.filtered
+    ? await listRuns(client, { storyId: idOrStory }).catch(() => ({ runs: [] }))
+    : here;
+
+  const elsewhere = [...new Set(forStory(wide.runs).map(r => r.repo_name))];
+  if (elsewhere.length) {
+    return {
+      error: `No workflow run for story ${idOrStory} in repository ${repoName}; it has runs in: ${elsewhere.join(', ')}.\n`
+        + `  Target that repository with --repo ${elsewhere[0]}, or ${byRunId}`,
+    };
+  }
+  const searched = here.filtered
+    ? "searched all of your org's runs"
+    : here.runs.length < LOOKUP_LIMIT
+      ? `searched all ${here.runs.length} runs in your org`
+      : `searched your org's ${here.runs.length} most recent runs`;
+  return {
+    error: `No workflow run found for story ${idOrStory} in repository ${repoName} (${searched}).\n`
+      + `  To act on a run by its ID, ${byRunId}   (run IDs: hone workflows)`,
+  };
+}
+
+module.exports = { resolveRunTarget, isRunId, LOOKUP_LIMIT };

package/lib/tree-artifact.js

@@ -0,0 +1,166 @@
+'use strict';
+/**
+ * tree-artifact.js — HC-GF-091: render a step_4 artifact from the WORKING TREE.
+ *
+ * Editor mode had the same single-response ceiling as the server: `hone submit-step` read one
+ * file and `hone_submit_step` took a string, so the editor model still re-typed every changed
+ * file into a single response under its own output cap. The agent has already written those
+ * files with its own tools; this renders the artifact from what is on disk instead.
+ *
+ * The output is consumed by `cli/lib/materialize-diff.js`. Its exit modes, enumerated before a
+ * line was written (HC-GF-117), and what this module does about each:
+ *
+ *   files[]     whole-file blocks   — HANDLED: created + modified files
+ *   deletes[]   `DELETE: <path>`    — HANDLED: deleted files
+ *   edits[]     region edits        — DELIBERATELY NOT: from-tree always sends whole files. The
+ *                                     tree is the truth; an anchor-based edit would reintroduce
+ *                                     exactly the drift this removes.
+ *   malformed[] unparsable block    — DELIBERATELY NOT REACHABLE: every fence we emit is longer
+ *                                     than any fence run inside the file it wraps (see below).
+ *   noChanges   the honest no-op    — HANDLED: a clean tree says NO CHANGES rather than nothing.
+ *
+ * Dependency-free by intent, like `cli/lib/headroom.js`: `git`, `fs` and `path` only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { gitEnv } = require('./git-env');
+
+/** Bytes above which we do not attempt to inline a file at all. */
+const MAX_FILE_BYTES = 1_000_000;
+
+/**
+ * SC-002-followup-2: git exports GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE to the processes it
+ * spawns, and those BEAT `cwd`. Without gitEnv() this renders a different repository's tree when
+ * it runs under a git hook — and it would look like a perfectly normal build.
+ */
+function gitOut(repoRoot, args) {
+  return execFileSync('git', args, { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+}
+
+/**
+ * A fence wide enough to carry this content.
+ *
+ * HC-GF-127: the block closes on a line matching its OWN fence, so a file holding a ```js sample
+ * needs at least four backticks. Before that fix the format could not carry such a file at all and
+ * this module refused it by name; the parsers now take 3-or-more with a matching closer.
+ */
+function fenceFor(content) {
+  let longest = 2;
+  for (const line of String(content).split('\n')) {
+    const m = /^[ \t]*(`{3,})/.exec(line);
+    if (m && m[1].length > longest) longest = m[1].length;
+  }
+  return '`'.repeat(longest + 1);
+}
+
+/** NUL in the first 8000 bytes is git's own binary heuristic. */
+function looksBinary(buf) {
+  const n = Math.min(buf.length, 8000);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+/**
+ * Paths changed against HEAD, plus untracked files.
+ *
+ * `git diff --name-status HEAD` alone does NOT see untracked files, so the obvious one-command
+ * implementation ships a build missing every file the agent created — the first named mutation
+ * target. `ls-files --others --exclude-standard` is the other half, and it is what honours
+ * .gitignore: a node_modules SYMLINK is a file to a naive directory walk
+ * (HC-COMM-010-followup-8), and git excludes it because the adopter said so.
+ */
+function collectPaths(repoRoot) {
+  const changed = [];
+  const deleted = [];
+  let hasHead = true;
+  try { gitOut(repoRoot, ['rev-parse', '--verify', 'HEAD']); } catch { hasHead = false; }
+
+  if (hasHead) {
+    const out = gitOut(repoRoot, ['diff', '--name-status', '--no-renames', 'HEAD']);
+    for (const line of out.split('\n')) {
+      if (!line.trim()) continue;
+      const tab = line.indexOf('\t');
+      if (tab === -1) continue;
+      const status = line.slice(0, tab).trim();
+      const rel = line.slice(tab + 1).trim();
+      if (!rel) continue;
+      if (status.startsWith('D')) deleted.push(rel);
+      else changed.push(rel);
+    }
+  }
+  const others = gitOut(repoRoot, ['ls-files', '--others', '--exclude-standard']);
+  for (const rel of others.split('\n')) if (rel.trim()) changed.push(rel.trim());
+
+  return {
+    changed: [...new Set(changed)].sort(),
+    deleted: [...new Set(deleted)].sort(),
+  };
+}
+
+/**
+ * Render the artifact.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.repoRoot    repository to read
+ * @param {string} [opts.testReport] the agent's own test-run report, carried verbatim. NEVER
+ *                                   invented: an absent report stays absent, because a fabricated
+ *                                   "N passing" is the anti-fabrication failure the step_4
+ *                                   validator already exists to catch.
+ * @returns {{ text: string, files: string[], deletes: string[], skipped: Array<{path,reason}> }}
+ */
+function renderFromTree({ repoRoot, testReport } = {}) {
+  if (!repoRoot) throw new Error('renderFromTree: repoRoot is required');
+  const { changed, deleted } = collectPaths(repoRoot);
+
+  const blocks = [];
+  const included = [];
+  const skipped = [];
+
+  for (const rel of changed) {
+    const abs = path.join(repoRoot, rel);
+    let st;
+    try { st = fs.lstatSync(abs); } catch { skipped.push({ path: rel, reason: 'unreadable' }); continue; }
+    // Structural, and deliberately silent: a symlink is not file content. materialize-diff would
+    // write a REGULAR file holding the link's target bytes, converting it without saying so. Naming
+    // every one of these would also put `node_modules` in the artifact of any repo whose .gitignore
+    // says `node_modules/` — a directory pattern that does not match the symlink (HC-COMM-010-followup-8).
+    if (st.isSymbolicLink() || !st.isFile()) continue;
+    if (st.size > MAX_FILE_BYTES) { skipped.push({ path: rel, reason: `larger than ${MAX_FILE_BYTES} bytes` }); continue; }
+
+    const buf = fs.readFileSync(abs);
+    if (looksBinary(buf)) { skipped.push({ path: rel, reason: 'binary' }); continue; }
+
+    const content = buf.toString('utf8');
+    const fence = fenceFor(content);
+    const body = content.endsWith('\n') ? content.slice(0, -1) : content;
+    blocks.push(`${fence}file: ${rel}\n${body}\n${fence}`);
+    included.push(rel);
+  }
+
+  const lines = ['## Changed Files', ''];
+
+  if (!included.length && !deleted.length) {
+    // The honest no-op, in the shape the validator and the materialiser both already accept.
+    lines.push('NO CHANGES — the working tree matches HEAD.');
+  } else {
+    for (const b of blocks) { lines.push(b, ''); }
+    for (const rel of deleted) lines.push(`DELETE: ${rel}`);
+    if (deleted.length) lines.push('');
+  }
+
+  if (skipped.length) {
+    // Named, not silent: a file that is in the tree and not in the artifact must be visible as a
+    // decision. Kept out of the Changed Files blocks so it can never parse as one.
+    lines.push('### Not included', '');
+    for (const s of skipped) lines.push(`- \`${s.path}\` — ${s.reason}`);
+    lines.push('');
+  }
+
+  if (testReport) lines.push('### Test run', '', String(testReport).trim(), '');
+
+  return { text: lines.join('\n'), files: included, deletes: deleted, skipped };
+}
+
+module.exports = { renderFromTree, _internal: { fenceFor, looksBinary, collectPaths, MAX_FILE_BYTES } };

package/lib/verify-patch.js

@@ -25,6 +25,9 @@ const EXIT = {
   DOES_NOT_APPLY: 2, // diff did not apply
   TESTS_FAILED: 3,  // diff applied, tests failed
   TIMEOUT: 4,       // the command exceeded --timeout
+  // HC-GF-008: the command itself could not start, so nothing about the patch is known. Not 5 or 6:
+  // emit-pr re-exits with these codes, and those two are its BRANCH_CONFLICT and PUBLISH_FAILED.
+  UNRESOLVED: 7,
 };
 
 /**
@@ -83,11 +86,81 @@ function resolveCommandDetailed(explicit, configured, opts = {}) {
 }
 function resolveCommand(explicit, configured, opts) { return resolveCommandDetailed(explicit, configured, opts).command; }
 
+/**
+ * HC-GF-008 — did the resolved command itself fail to START?
+ *
+ * The resolver's last tier is a guess (`make ci`), and a guess that names nothing came back as
+ * `tests failed (exit 2)`: the builder blamed for a command that does not exist, on every
+ * greenfield repo and every `npm init` manifest. Measured before building, on real processes —
+ * GNU make 4.3 + dash and make 3.81 + bash differ only in quote characters.
+ *
+ * Absence is the RUNNER's own words about a name the command contains:
+ *   - the shell exits 127 saying it cannot find a program the command names
+ *     (`sh: uv: command not found`, dash `sh: 7: uv: not found`, `sh: ./ci.sh: No such file or directory`);
+ *   - top-level make says a goal the command names has no rule (`No rule to make target 'ci'.  Stop.`),
+ *     or that there is no makefile at all.
+ * Deliberately NOT absence, because something started and the patch is a plausible cause: a missing
+ * prerequisite (`No rule to make target 'test', needed by 'ci'` names `test`, which the command does not),
+ * `make[1]:` (a sub-make a recipe ran), a tool missing inside a recipe or an npm script, and a 127 whose
+ * not-found line names nothing in the command. The command's own words are the discriminator throughout.
+ * Every residual lands on `fail`, which blocks exactly as before — the safe side.
+ *
+ * @returns {{ missing: string, reason: string } | null}
+ */
+const SHELL_NOT_FOUND_RE = /^[^\s:]*sh(?::\s*line\s+\d+)?:\s*(?:\d+:\s*)?(\S+):\s*(?:command not found|not found|No such file or directory)\s*$/gm;
+const MAKE_NO_RULE_RE = /^make: \*\*\* No rule to make target [`'\u2018]([^`'\u2019]+)['\u2019]/gm;
+const MAKE_NO_MAKEFILE_RE = /^make: \*\*\* No targets specified and no makefile found\./m;
+
+function commandAbsence(command, { code, stdout = '', stderr = '' } = {}) {
+  const cmd = String(command || '').trim();
+  if (!cmd) return null;
+  const words = new Set(cmd.split(/[\s;&|()<>]+/).filter(Boolean));
+  const out = `${stdout || ''}\n${stderr || ''}`;
+  if (code === 127) {
+    // `shell: true` runs /bin/sh, so these are sh's own words — bash-as-sh or dash.
+    for (const m of out.matchAll(SHELL_NOT_FOUND_RE)) {
+      if (words.has(m[1])) return { missing: m[1], reason: `\`${m[1]}\` is not installed or not on PATH` };
+    }
+    return null;
+  }
+  if (words.has('make')) {
+    for (const m of out.matchAll(MAKE_NO_RULE_RE)) {
+      if (words.has(m[1])) return { missing: m[1], reason: `no Makefile target \`${m[1]}\`` };
+    }
+    if (MAKE_NO_MAKEFILE_RE.test(out)) return { missing: 'Makefile', reason: 'no Makefile' };
+  }
+  return null;
+}
+
+/**
+ * HC-GF-008 — the environment an adopter's verification command runs in.
+ *
+ * make exports its recursion state to every recipe, so a `hone` verb run from a make target — or from
+ * `make ci` itself — hands that state to the command it verifies. Measured on GNU make 3.81 and 4.3:
+ *   - MAKELEVEL=1 turns the verified make's own `make: *** No rule to make target` into `make[1]: …`,
+ *     the prefix of a sub-make a recipe ran, so the absent-command check went inert (it passed alone and
+ *     failed under `make ci`);
+ *   - MAKEFLAGS=i (ignore errors) and MAKEFLAGS=n (dry run) make a failing `make ci` exit 0, and
+ *     GNUMAKEFLAGS=i does the same on make 4 — a pass for tests that failed or never ran, which under
+ *     enforce approves the gate.
+ * The verified command is the adopter's own top-level invocation: level 0, no inherited flags. Returns a
+ * copy; the caller's environment is untouched.
+ */
+const INHERITED_MAKE_VARS = ['MAKELEVEL', 'MAKEFLAGS', 'GNUMAKEFLAGS'];
+function verifyCommandEnv(base = process.env) {
+  const env = { ...base };
+  for (const key of INHERITED_MAKE_VARS) delete env[key];
+  return env;
+}
+
 /**
  * Interpret a completed command run into a condition-6 verdict.
  *
- * @param {{ code: number|null, timedOut: boolean, stdout?: string, stderr?: string }} run
- * @returns {{ verdict: 'pass'|'fail'|'timeout', exitCode: number, detail: string }}
+ * Pass the `command` that ran and the resolver's `source` for it: without them an absent command is
+ * indistinguishable from a failing one (HC-GF-008), and the CLI's two executors both do.
+ *
+ * @param {{ code: number|null, timedOut: boolean, stdout?: string, stderr?: string, command?: string, source?: string }} run
+ * @returns {{ verdict: 'pass'|'fail'|'timeout'|'unresolved', exitCode: number, detail: string }}
  */
 function verdictFromRun(run) {
   if (run.timedOut) {
@@ -96,6 +169,18 @@ function verdictFromRun(run) {
   if (run.code === 0) {
     return { verdict: 'pass', exitCode: EXIT.PASS, detail: 'tests passed on the applied diff' };
   }
+  const absent = commandAbsence(run.command, run);
+  if (absent) {
+    return {
+      verdict: 'unresolved',
+      exitCode: EXIT.UNRESOLVED,
+      detail: `tests never ran: ${absent.reason}`
+        + (run.source === 'default'
+          ? ` — no test command is configured or detected, so \`${run.command}\` was a guess; set ci.local_command in .pipeline-config.yml`
+          : ''),
+      missing: absent.missing,
+    };
+  }
   const sum = summarizeFailure(run);
   // HC-GF-023: lead with HOW MANY. "1 of 8 named" and "the only failure" are
   // different situations that this line used to render identically.
@@ -265,5 +350,5 @@ function classifyGateRun(run) {
 module.exports = {
   EXIT, resolveCommand, resolveCommandDetailed, DEFAULT_COMMAND,
   AUX_GATES, AUX_DETECT, resolveAuxGates, classifyGateRun,
-  verdictFromRun, lastMeaningfulLine, summarizeFailure, FAILURE_LINE_RE,
+  verdictFromRun, commandAbsence, verifyCommandEnv, lastMeaningfulLine, summarizeFailure, FAILURE_LINE_RE,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hone-ai/cli",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "description": "Hone AI — Enterprise SDLC Pipeline CLI",
   "main": "hone-cli.js",
   "bin": {