@hone-ai/cli 1.31.0 → 1.32.0

package/hone-cli.js

@@ -5609,6 +5609,8 @@ program
   .option('--poll-interval <s>', 'Poll interval in seconds', '5')
   .option('--story-file <path>', 'HC-GF-010: read the story text from a local file. Skips the GitHub-issue and Hone-roadmap lookups entirely, so a repo with neither can still run the pipeline.')
   .option('--description <text>', 'HC-GF-010: the story text, inline. Same effect as --story-file.')
+  .option('--acknowledge-abort', 'Approve a step the agent ABORTED (HC-GF-069). An abort means the agent found nothing it could review or build, so approving advances past a step that produced no usable result — read the reason first. Exists so a human can override, which is why the refusal is not simply a hard block.')
+  .option('--no-follow', 'With --approve: post the approval and exit immediately instead of following the run to its next decision point (HC-GF-070). The default FOLLOWS, because a caller told to poll does not — which is why HC-GF-064 auto-verify never fired outside a TTY.')
   .option('--include-paths <paths>', 'Comma-separated list of source file paths to bundle into the codebase context (HC-019n-followup-12). Augments auto-detected paths from the issue body.')
   .option('--e2e-specs', 'HC-019n-followup-28: force step_3b (Playwright spec generation) ON for this run (overrides e2e.spec_generation config)')
   .option('--skip-e2e-specs', 'HC-019n-followup-28: force step_3b (Playwright spec generation) OFF for this run (overrides e2e.spec_generation config)')
@@ -5639,6 +5641,132 @@ program
     const storyId = isUuid ? null : storyIdOrRunId;
     const runId = isUuid ? storyIdOrRunId : null;
 
+    // HC-GF-070: ONE poll loop, reachable from BOTH entry points.
+    //
+    // It used to be reachable from exactly one — the initial `run-story <storyId>` — so
+    // `--approve` posted, printed "Poll: ...", and returned. The caller was told to poll
+    // and, exactly as with the verify-patch nag that motivated HC-GF-064 (5 of 22 runs),
+    // nobody did. Every driver written against this re-implemented the loop and each had
+    // a different bug: a paused gate treated as terminal; a no-op approval hot-looping
+    // nine times; a gate advertised by a run whose driver had already exited. Not three
+    // driver bugs — one missing behaviour, three times.
+    //
+    // Its DECISIONS live in cli/lib/poll-decision.js as a pure function, because calling
+    // the same loop from a second place is only safe if what it decides is pinned.
+    const pollUntilDecision = async (pollRunId) => {
+      const { classifyPollState, POLL_OUTCOMES } = require('./lib/poll-decision');
+      const interval = parseInt(opts.pollInterval, 10) * 1000;
+      // HC-GF-064: at most ONE verification per attempt per process. Without this the
+      // advisory path re-verifies on every poll tick, because advisory never advances
+      // the run and the pause it re-observes is the same pause.
+      const _verifiedAttempts = new Set();
+
+      for (;;) {
+        await new Promise(r => setTimeout(r, interval));
+
+        let status;
+        try {
+          const { data: pollData } = await client.get(`/orchestrate/${pollRunId}`);
+          status = pollData;
+        } catch (e) {
+          console.error(`Poll error: ${e.message}`);
+          continue;
+        }
+
+        const d = classifyPollState(status);
+
+        if (d.outcome === POLL_OUTCOMES.COMPLETED) {
+          console.log(`✓ Workflow completed! Total tokens: ${(d.totalTokens || 0).toLocaleString()}`);
+          process.exit(d.exitCode);
+        }
+        if (d.outcome === POLL_OUTCOMES.TERMINAL_FAILURE) {
+          console.error(`✗ Workflow ${d.runStatus}: ${d.errorMessage}`);
+          process.exit(d.exitCode);
+        }
+        if (d.outcome === POLL_OUTCOMES.EDITOR_PARKED) {
+          console.log(editorParkedGuidance(pollRunId, d.stepKey, d.agent));
+          process.exit(d.exitCode);
+        }
+
+        if (d.outcome === POLL_OUTCOMES.HUMAN_GATE) {
+          console.log(`⏳ Step ${d.stepKey} (${d.agent || 'unknown'}) — awaiting approval`);
+
+          // HC-GF-064: verify BEFORE asking anyone to approve. The gate this feeds had
+          // existed since HC-019n-followup-34/35 and never fired, because nothing ever
+          // ran the executing step. Consent is DERIVED: `ci.local_command` being
+          // explicitly set is the adopter's own statement of how to test this repo (see
+          // cli/lib/auto-verify.js and docs/architecture/adr-verification-invocation.md).
+          // Never throws — a failure here must leave the operator exactly where they
+          // were, which is being asked to approve.
+          try {
+            const { decideAutoVerify, announce, shouldRepoll, alreadyVerified } = require('./lib/auto-verify');
+            const decision = decideAutoVerify({
+              stepKey: d.stepKey,
+              repoRoot: process.cwd(),
+              noVerifyFlag: opts.verify === false,
+            });
+            if (decision.run && !alreadyVerified(d.attemptKey, _verifiedAttempts)) {
+              _verifiedAttempts.add(d.attemptKey);
+              console.log(announce(decision, pollRunId));
+              const { spawnSync } = require('child_process');
+              const r = spawnSync(process.execPath,
+                [process.argv[1], 'verify-patch', pollRunId, '--report'],
+                { stdio: 'inherit', env: process.env });
+              // A green verdict under `enforce` AUTO-APPROVES this gate, so the run may
+              // already have moved on. Re-poll rather than prompting for an approval that
+              // is no longer wanted — asking a human to approve something already approved
+              // is how an operator learns to distrust the output.
+              if (shouldRepoll({ gate: decision.gate, verdictOk: r.status === 0,
+                                 attemptKey: d.attemptKey, verifiedAttempts: null })) {
+                console.log('  → verified; enforce may have advanced the run. Re-checking...');
+                continue;
+              }
+              console.log(r.status === 0
+                ? `  → verified and recorded (gate: ${decision.gate}). The gate still needs you.`
+                : '  → verification did not pass; the gate still needs you.');
+            }
+          } catch (e) {
+            console.log(`  (auto-verify skipped: ${e.message})`);
+          }
+
+          if (process.stdin.isTTY) {
+            const readline = require('readline');
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            const answer = await new Promise(resolve => rl.question('  Approve? [y/n/kill] ', resolve));
+            rl.close();
+
+            if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
+              try {
+                await client.post(`/orchestrate/${pollRunId}/approve`, { stepKey: d.stepKey });
+                console.log('  Approved — workflow resuming...');
+              } catch (e) {
+                console.error(`  Approve failed: ${e.response?.data?.error || e.message}`);
+              }
+            } else if (answer.toLowerCase() === 'kill') {
+              try {
+                await client.post(`/orchestrate/${pollRunId}/kill`, { reason: 'CLI kill' });
+                console.log('  Workflow killed.');
+                process.exit(0);
+              } catch (e) {
+                console.error(`  Kill failed: ${e.message}`);
+              }
+            } else {
+              console.log(`  Skipped. Resume later: hone run-story ${pollRunId} --status`);
+              process.exit(0);
+            }
+          } else {
+            // Non-interactive (CI): exit 2 (paused, needs approval) — the contract
+            // adopter pipelines already branch on.
+            console.log(`  Non-interactive mode. Approve with: hone run-story ${pollRunId} --approve ${d.stepKey}`);
+            process.exit(d.exitCode);
+          }
+          continue;
+        }
+
+        if (d.stepKey) process.stdout.write(`  Running: ${d.stepKey} (${d.agent})...\r`);
+      }
+    };
+
     // Status mode
     if (opts.status) {
       const statusId = runId || storyIdOrRunId;
@@ -5706,13 +5834,33 @@ program
     if (opts.approve) {
       const approveId = runId || storyIdOrRunId;
       try {
-        const { data } = await client.post(`/orchestrate/${approveId}/approve`, { stepKey: opts.approve });
+        await client.post(`/orchestrate/${approveId}/approve`,
+          { stepKey: opts.approve, acknowledgeAbort: opts.acknowledgeAbort === true });
         console.log(`Gate ${opts.approve} approved. Workflow resuming.`);
-        console.log(`Poll: hone run-story ${approveId} --status`);
       } catch (e) {
         console.error(`Failed: ${e.response?.data?.error || e.message}`);
         process.exit(1);
       }
+      // HC-GF-070: FOLLOW the run to its next decision point instead of returning here.
+      // Returning is what made every automated flow exit blind after each gate, and is
+      // the direct reason HC-GF-064's auto-verify — which lives at the step_4 pause —
+      // never fired outside an interactive terminal. Exit codes are unchanged: 0 done,
+      // 1 failed, 2 next human gate, 3 editor park.
+      if (opts.follow === false) {
+        console.log(`Poll: hone run-story ${approveId} --status`);
+        return;
+      }
+      // The initial invocation runs this inside the start-workflow try/catch; the
+      // approve path has none, and an unhandled rejection here would surface as a bare
+      // stack trace after a successful approval — the approval landed, so the exit code
+      // must say what happened to the RUN, not look like the approve failed.
+      try {
+        await pollUntilDecision(approveId);
+      } catch (e) {
+        console.error(`Approved, but following the run failed: ${e.message}`);
+        console.error(`Poll: hone run-story ${approveId} --status`);
+        process.exit(1);
+      }
       return;
     }
 
@@ -6263,130 +6411,7 @@ program
       console.log(`Poll: ${data.pollUrl}`);
       console.log('');
 
-      // Poll loop
-      const interval = parseInt(opts.pollInterval, 10) * 1000;
-      // HC-GF-064: at most ONE verification per attempt per process. Without this the
-      // advisory path re-verifies on every poll tick, because advisory never advances
-      // the run and the pause it re-observes is the same pause.
-      const _verifiedAttempts = new Set();
-      while (true) {
-        await new Promise(r => setTimeout(r, interval));
-
-        let status;
-        try {
-          const { data: pollData } = await client.get(`/orchestrate/${data.runId}`);
-          status = pollData;
-        } catch (e) {
-          console.error(`Poll error: ${e.message}`);
-          continue;
-        }
-
-        if (status.status === 'completed') {
-          console.log(`✓ Workflow completed! Total tokens: ${(status.totalTokens || 0).toLocaleString()}`);
-          process.exit(0);
-        }
-
-        if (status.status === 'failed' || status.status === 'killed') {
-          console.error(`✗ Workflow ${status.status}: ${status.errorMessage || 'unknown'}`);
-          process.exit(1);
-        }
-
-        if (status.status === 'paused' && status.awaitingApproval) {
-          const step = status.steps.find(s => s.stepKey === status.currentStep);
-          // HC-COMM-010-followup-1: an editor-parked run is a gate the EDITOR
-          // satisfies, not a human — never offer --approve here (B4 refuses it).
-          if (isEditorParked(status)) {
-            console.log(editorParkedGuidance(data.runId, status.currentStep, step?.agent));
-            process.exit(EDITOR_PARKED_EXIT_CODE);
-          }
-          console.log(`⏳ Step ${status.currentStep} (${step?.agent || 'unknown'}) — awaiting approval`);
-
-          // HC-GF-064: verify BEFORE asking anyone to approve.
-          //
-          // The gate this feeds has existed since HC-019n-followup-34/35 and had never
-          // fired — 22 of 22 runs advisory, 5 of 22 with any verdict at all — because
-          // nothing ever ran the executing step. The only prompt was a run-report line,
-          // and 5-of-22 is what that nag was worth.
-          //
-          // Consent is DERIVED: `ci.local_command` being explicitly set is the adopter's
-          // own statement of how to test this repo (see cli/lib/auto-verify.js and
-          // docs/architecture/adr-verification-invocation.md). Never throws — a failure
-          // here must leave the operator exactly where they were, which is being asked
-          // to approve.
-          try {
-            const { decideAutoVerify, announce, shouldRepoll, alreadyVerified } = require('./lib/auto-verify');
-            const attemptKey = `${status.currentStep}#${step?.attempt ?? 1}`;
-            const decision = decideAutoVerify({
-              stepKey: status.currentStep,
-              repoRoot: process.cwd(),
-              noVerifyFlag: opts.verify === false,
-            });
-            if (decision.run && !alreadyVerified(attemptKey, _verifiedAttempts)) {
-              _verifiedAttempts.add(attemptKey);
-              console.log(announce(decision, data.runId));
-              const { spawnSync } = require('child_process');
-              const r = spawnSync(process.execPath,
-                [process.argv[1], 'verify-patch', data.runId, '--report'],
-                { stdio: 'inherit', env: process.env });
-              // A green verdict under `enforce` AUTO-APPROVES this gate, so the run may
-              // already have moved on. Re-poll rather than prompting for an approval that
-              // is no longer wanted — asking a human to approve something already approved
-              // is how an operator learns to distrust the output.
-              if (shouldRepoll({ gate: decision.gate, verdictOk: r.status === 0,
-                                 attemptKey, verifiedAttempts: null })) {
-                console.log('  → verified; enforce may have advanced the run. Re-checking...');
-                continue;
-              }
-              console.log(r.status === 0
-                ? `  → verified and recorded (gate: ${decision.gate}). The gate still needs you.`
-                : '  → verification did not pass; the gate still needs you.');
-            }
-          } catch (e) {
-            console.log(`  (auto-verify skipped: ${e.message})`);
-          }
-
-          // Interactive prompt
-          if (process.stdin.isTTY) {
-            const readline = require('readline');
-            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-            const answer = await new Promise(resolve => {
-              rl.question('  Approve? [y/n/kill] ', resolve);
-            });
-            rl.close();
-
-            if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
-              try {
-                await client.post(`/orchestrate/${data.runId}/approve`, { stepKey: status.currentStep });
-                console.log('  Approved — workflow resuming...');
-              } catch (e) {
-                console.error(`  Approve failed: ${e.response?.data?.error || e.message}`);
-              }
-            } else if (answer.toLowerCase() === 'kill') {
-              try {
-                await client.post(`/orchestrate/${data.runId}/kill`, { reason: 'CLI kill' });
-                console.log('  Workflow killed.');
-                process.exit(0);
-              } catch (e) {
-                console.error(`  Kill failed: ${e.message}`);
-              }
-            } else {
-              console.log(`  Skipped. Resume later: hone run-story ${data.runId} --status`);
-              process.exit(0);
-            }
-          } else {
-            // Non-interactive (CI): exit with code 2 (paused, needs approval)
-            console.log(`  Non-interactive mode. Approve with: hone run-story ${data.runId} --approve ${status.currentStep}`);
-            process.exit(2);
-          }
-          continue;
-        }
-
-        // Still running
-        const currentStep = status.steps.find(s => s.status === 'running');
-        if (currentStep) {
-          process.stdout.write(`  Running: ${currentStep.stepKey} (${currentStep.agent})...\r`);
-        }
-      }
+      await pollUntilDecision(data.runId);
     } catch (e) {
       if (e.response?.status === 429) {
         console.error(`Max concurrent workflows reached. ${e.response.data.error}`);
@@ -7826,7 +7851,16 @@ program
           headSha,
           gates: reportGates.length ? reportGates : undefined,
         });
-        if (opts.format !== 'json') console.log(`  → reported verdict '${reportVerdict}' to the server (advisory)`);
+        if (opts.format !== 'json') {
+          // HC-GF-070: name the gate that is actually configured. This said "(advisory)"
+          // unconditionally, and printed it on a run where `enforce` was auto-approving
+          // step_4 on the strength of that very verdict.
+          const { verdictReportLine } = require('./lib/auto-verify');
+          const { readVerificationGateConfig } = require('./lib/pipeline-config');
+          let gate = 'advisory';
+          try { gate = readVerificationGateConfig(process.cwd()) || 'advisory'; } catch { /* label only */ }
+          console.log(verdictReportLine(reportVerdict, gate));
+        }
       } catch (e) {
         if (opts.format !== 'json') console.warn(`  ⚠ verdict report failed (non-fatal): ${e.response?.data?.error || e.message}`);
       }
@@ -7851,7 +7885,12 @@ program
       else console.log(renderReport(report));
       // Exit non-zero when the operator has something to do, so `hone run-report`
       // is usable as a gate in a script and not merely as prose.
-      process.exit(report.needsYou.length ? 1 : 0);
+      //
+      // HC-GF-065: count the GATING items, not every item. An advisory — currently
+      // "verification never ran" — is shown in full but must not flip this exit code:
+      // it fires on every unverified terminal run, and gating on it would turn a
+      // passing adopter CI red the day they upgrade. HC-026c: report before you gate.
+      process.exit((report.gatingCount ?? report.needsYou.length) ? 1 : 0);
     } catch (e) {
       console.error(`run-report failed: ${e.response?.data?.error || e.message}`);
       process.exit(1);

package/lib/auto-verify.js

@@ -146,4 +146,22 @@ 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})`;
+}
+
+module.exports = { decideAutoVerify, announce, readVerificationAuto, shouldRepoll, alreadyVerified, verdictReportLine, VERIFIABLE_STEP };

package/lib/poll-decision.js

@@ -0,0 +1,92 @@
+'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');
+
+const POLL_OUTCOMES = Object.freeze({
+  COMPLETED: 'completed',
+  TERMINAL_FAILURE: 'terminal_failure',
+  EDITOR_PARKED: 'editor_parked',
+  HUMAN_GATE: 'human_gate',
+  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,
+  [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-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 };

package/lib/run-report.js

@@ -48,10 +48,34 @@ function buildReport(run, extra = {}) {
   // ── NEEDS YOU ──────────────────────────────────────────────────────────────
   // 1. The run itself is not finished.
   if (run.status === 'paused' && run.currentStep) {
-    needsYou.push({
-      what: `run is paused at ${run.currentStep} — a gate is waiting on your judgment`,
-      how: `hone run-story ${run.runId} --approve ${run.currentStep}`,
-    });
+    // HC-GF-046: a paused run is not always a gate.
+    //
+    // Run 3dbde316 sat `paused` at step_4 with `MAX_RETRIES_EXCEEDED: step_4 retried 2
+    // times (max 2)`. That LOOKS like an available approval — paused, with a pending gate
+    // — but `checkGuardrails` refuses step_4 before the LLM call, so approving can never
+    // move the run. The line described the run's SHAPE and not its CAUSE, and so invited
+    // the one action the orchestrator had already decided to refuse. A driver looped on
+    // it; a human tried once and had to read the database.
+    //
+    // Matched on the specific messages the guardrail acts on, NOT on "any error_message".
+    // 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) {
+      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 {
+      needsYou.push({
+        what: `run is paused at ${run.currentStep} — a gate is waiting on your judgment`,
+        how: `hone run-story ${run.runId} --approve ${run.currentStep}`,
+      });
+    }
   }
   if (run.status === 'failed') {
     needsYou.push({
@@ -59,6 +83,19 @@ function buildReport(run, extra = {}) {
       how: `hone show step ${run.runId} ${run.currentStep || '<stepKey>'}`,
     });
   }
+  // HC-GF-065: a KILLED run needs you too.
+  //
+  // The predicate above is `status === 'failed'`, which `killed` does not match — so nine
+  // terminated runs in the corpus printed `NEEDS YOU (0)` and "nothing outstanding". A run
+  // somebody stopped mid-flight has work outstanding by definition, and the digest told
+  // the operator it did not. This is HC-GF-044's defect one field over, and its own lesson
+  // states the rule: a well-formed "nothing" is only as true as the predicate behind it.
+  if (run.status === 'killed') {
+    needsYou.push({
+      what: `run was KILLED before it finished${run.errorMessage ? `: ${String(run.errorMessage).slice(0, 160)}` : ''}`,
+      how: `hone run-story ${run.runId} --status   (re-run the story, or read the last step)`,
+    });
+  }
 
   // 1b. HC-GF-044: a STEP can be failed while the RUN says completed.
   //
@@ -187,6 +224,32 @@ function buildReport(run, extra = {}) {
     }
   }
 
+  // HC-GF-065: NO verdict at all is itself an item, not a footnote under a zero.
+  //
+  // Measured over the corpus with this very function: 10 of 21 terminal runs printed
+  // "nothing outstanding", and the sentence is false in every one of them. Nothing was
+  // executed against the diff, so the report cannot know whether anything is outstanding
+  // — the two reviewing steps READ, they do not run anything, which is exactly why
+  // HC-GF-064's verdict exists.
+  //
+  // Scoped to terminal runs on purpose. A run still in flight has not reached the point
+  // where a verdict is expected, and flagging it would make the section noise on every
+  // poll — which is how the old nag reached 5-of-22 and got ignored.
+  if (['completed', 'failed', 'killed'].includes(run.status) && !lastVerification) {
+    needsYou.push({
+      what: 'verification never ran for this run — no test, lint or typecheck result was '
+        + 'reported, so nothing here is known to build',
+      how: `hone verify-patch ${run.runId} step_4 --report`,
+      // HC-GF-065: ADVISORY. `hone run-report` exits 1 when needsYou is non-empty, and
+      // the comment at that exit says why — "so run-report is usable as a GATE in a
+      // script". This item fires on every unverified terminal run (15 of 21 in the
+      // corpus, most of them otherwise healthy), so gating on it would turn an adopter's
+      // passing CI red overnight. HC-026c is precisely this rule: a new signal REPORTS
+      // before it GATES. Visible in the report, absent from the exit code.
+      advisory: true,
+    });
+  }
+
   // ── WORTH KNOWING ──────────────────────────────────────────────────────────
   // Retries: the step ran more than once. HC-GF-041(c): this used to append "(its
   // first output was rejected)", which the report never checked and which is often
@@ -236,6 +299,9 @@ function buildReport(run, extra = {}) {
     worthKnowing,
     steps,
     verifications,
+    // 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,
   };
 }
 
@@ -278,11 +344,13 @@ function renderReport(r) {
       checked.push('verification');
       for (const g of last.gates || []) checked.push(g.name);
     }
+    // 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
+    // ITEM above rather than a footnote under a zero, and this branch is unreachable in
+    // that case. Kept as a genuine all-clear for a run that WAS verified.
     L.push('NEEDS YOU (0)');
-    L.push(checked.length
-      ? `  nothing — ${checked.join(', ')} all reported and none is failing or unavailable`
-      : '  nothing outstanding, but NO verification was reported for this run — '
-        + 'run `hone verify-patch <runId> step_4 --report` before trusting that');
+    L.push(`  nothing — ${checked.join(', ')} all reported and none is failing or unavailable`);
   }
   L.push('');
 

package/package.json

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