@hone-ai/cli 1.32.0 → 1.34.0

package/hone-cli.js

@@ -5522,11 +5522,16 @@ program
         const m = Math.floor((Date.now() - new Date(ts).getTime()) / 60000);
         return m < 60 ? `${m}m` : m < 1440 ? `${Math.floor(m / 60)}h` : `${Math.floor(m / 1440)}d`;
       };
-      console.log('RUN ID    STORY                 STATUS     STEP       AGE');
+      // A story ID cut to fit is marked as cut: pasted into `run-story <storyId>`, a bare prefix could name another story.
+      // ASCII on purpose: U+2026 is ambiguous-width, and a terminal that draws it double-width shifts the row.
+      const clip = (s, w) => (s.length > w ? `${s.slice(0, w - 3)}...` : s);
+      // HC-GF-108: the FULL run ID. The footer says `hone run-story <runId> --kill`, and an 8-character
+      // prefix is not a run ID; nor is one accepted as a target, since `12345678` is also a valid story ID.
+      console.log(['RUN ID'.padEnd(36), 'STORY'.padEnd(22), 'STATUS'.padEnd(10), 'STEP'.padEnd(10), 'AGE'].join(' '));
       for (const r of data.runs) {
         console.log([
-          String(r.id).slice(0, 8).padEnd(9),
-          String(r.story_id || '-').slice(0, 21).padEnd(22),
+          String(r.id).padEnd(36),
+          clip(String(r.story_id || '-'), 21).padEnd(22),
           String(r.status).padEnd(10),
           String(r.current_step || '-').padEnd(10),
           age(r.created_at),
@@ -5547,7 +5552,9 @@ program
     const config = getConfig();
     const client = api(config);
     try {
-      const { data } = await client.get(`/orchestrate/${encodeURIComponent(runId)}/step-instruction`);
+      // HC-GF-092: advertise what this CLI can honour. The server serves the highest it also
+      // knows, so an older CLI — which sends nothing — keeps being served contract 1.
+      const { data } = await client.get(`/orchestrate/${encodeURIComponent(runId)}/step-instruction?contracts=1,2`);
       if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       console.log(`Step:      ${data.stepKey} (${data.agent})`);
       console.log(`Contract:  ${data.contractVersion}`);
@@ -5568,15 +5575,36 @@ program
   .command('submit-step <runId> <stepKey>')
   .description('Submit editor-executed output for an awaiting_editor step (HC-COMM-010 B3)')
   .option('--file <path>', 'Read the step output from this file')
+  .option('--from-tree', 'HC-GF-091: render the artifact from the working tree against HEAD instead of reading one file — the agent writes files with its own tools, so no single model response has to hold the whole build')
+  .option('--test-report <text>', 'With --from-tree: the test-run report to carry verbatim. Never invented when absent.')
   .option('--contract <version>', 'Instruction contract version (from step-instruction)', '1')
   .option('--format <fmt>', 'Output format: pretty | json', 'pretty')
   .action(async (runId, stepKey, opts) => {
     const config = getConfig();
     const client = api(config);
     try {
-      if (!opts.file) { console.error('Provide the output via --file <path> (the text your editor produced).'); process.exit(1); }
+      if (opts.file && opts.fromTree) { console.error('Use --file OR --from-tree, not both: they are two different claims about where the build is.'); process.exit(1); }
+      // HC-GF-092: under contract 2 the instruction told the agent to WRITE the files with its own
+      // tools. A hand-assembled --file artifact means the instruction and the submission disagree
+      // about where the build is, and the server cannot see that — only this side can.
+      if (String(opts.contract) === '2' && !opts.fromTree) {
+        console.error('Contract 2 is the from-tree contract: the instruction told the agent to write the files with its own tools. Re-run with --from-tree, or fetch a contract 1 instruction if you really did assemble the output by hand.');
+        process.exit(1);
+      }
+      if (!opts.file && !opts.fromTree) { console.error('Provide the output via --file <path> (the text your editor produced), or --from-tree to render it from the working tree.'); process.exit(1); }
       const fs = require('fs');
-      const output = fs.readFileSync(opts.file, 'utf8');
+      let output;
+      if (opts.fromTree) {
+        const { renderFromTree } = require('./lib/tree-artifact');
+        const rendered = renderFromTree({ repoRoot: process.cwd(), testReport: opts.testReport });
+        output = rendered.text;
+        // Say what was left out BEFORE the submission, not after: a file the tree has and the
+        // artifact does not is a decision the operator has to be able to see.
+        for (const s2 of rendered.skipped) console.error(`not included: ${s2.path} — ${s2.reason}`);
+        console.error(`from-tree: ${rendered.files.length} file(s), ${rendered.deletes.length} deletion(s), ${rendered.skipped.length} skipped`);
+      } else {
+        output = fs.readFileSync(opts.file, 'utf8');
+      }
       const { data } = await client.post(
         `/orchestrate/${encodeURIComponent(runId)}/step/${encodeURIComponent(stepKey)}/editor-output`,
         { contractVersion: opts.contract, output }
@@ -5598,17 +5626,18 @@ program
   .command('run-story <storyId>')
   .description('Run the SDLC pipeline for a story via the orchestrator')
   .option('--mode <mode>', 'Execution mode: interactive or batch', 'interactive')
-  .option('--repo <name>', 'Repository name override (default: directory name)')
+  .option('--repo <name>', 'Repository name override (default: directory name). Also the repository a story ID is looked up in for --status, --kill and --approve')
   .option('--branch <name>', 'Git branch (default: current)')
-  .option('--status', 'Show status of the latest workflow run for this story')
-  .option('--kill', 'Kill the latest workflow run for this story')
+  .option('--status', 'Show status of a run: pass a run ID, or a story ID for that story\'s latest run in this repository')
+  .option('--kill', 'Kill a run: pass a run ID, or a story ID for that story\'s latest run in this repository')
   .option('--axes <axes>', 'Comma-separated classifier axes for this run (e.g. shared-chokepoint) — composition input (HC-COMM-010 C0)')
-  .option('--approve <step>', 'Approve a paused gate (e.g., --approve step_0). Exit codes: 2 = paused at a human gate, 3 = parked for your editor (execution.mode: editor)')
+  .option('--approve <step>', 'Approve a paused gate (e.g., --approve step_0) on a run ID, or on a story ID\'s latest run in this repository. Exit codes: 2 = paused at a human gate, 3 = parked for your editor (execution.mode: editor)')
   .option('--no-verify', 'HC-GF-064: do not run verify-patch automatically when the run pauses at step_4')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .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-failed-verdict', 'Approve a step whose verification did NOT pass under verification.gate: enforce (HC-GF-074). The server refuses that approval by default and names the failing gates; this is for a human who has read them and still wants to proceed.')
   .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.')
@@ -5635,11 +5664,25 @@ program
       }
     } catch { /* never block a run on a banner */ }
 
-    // Resolve: if it looks like a UUID, use as runId directly.
-    // Otherwise treat as storyId — will be used for POST /orchestrate body.
-    const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(storyIdOrRunId);
-    const storyId = isUuid ? null : storyIdOrRunId;
-    const runId = isUuid ? storyIdOrRunId : null;
+    const { resolveRunTarget, isRunId } = require('./lib/run-target');
+    const isUuid = isRunId(storyIdOrRunId);
+    const repoName = opts.repo || path.basename(process.cwd());
+
+    // HC-GF-106: --status, --kill and --approve act on an EXISTING run, and all three resolve their
+    // argument here. Each used to forward it verbatim (`runId || storyIdOrRunId`), so a story ID was
+    // posted as a run ID and answered `Run not found` — while --help promised the story's latest run.
+    // A story is scoped to `repoName`, the name the start path below records, so it resolves to a run
+    // this checkout started. Never falls back to the argument: no run found means exit 1.
+    const existingRunId = async (flag) => {
+      const t = await resolveRunTarget({ client, idOrStory: storyIdOrRunId, repoName, flag });
+      if (t.error) { console.error(t.error); process.exit(1); }
+      if (t.source === 'story') {
+        // stderr: stdout is what a `--status --format json` caller parses, so the note stays out of it.
+        const at = t.run.current_step ? ` at ${t.run.current_step}` : '';
+        console.error(`→ ${storyIdOrRunId}: latest run in ${repoName} is ${t.runId} (${t.run.status}${at})`);
+      }
+      return t.runId;
+    };
 
     // HC-GF-070: ONE poll loop, reachable from BOTH entry points.
     //
@@ -5688,8 +5731,20 @@ program
           process.exit(d.exitCode);
         }
 
-        if (d.outcome === POLL_OUTCOMES.HUMAN_GATE) {
-          console.log(`⏳ Step ${d.stepKey} (${d.agent || 'unknown'}) — awaiting approval`);
+        if (d.outcome === POLL_OUTCOMES.HUMAN_GATE || d.outcome === POLL_OUTCOMES.EXHAUSTED) {
+          // HC-GF-075: an exhausted step is a decision, not a gate on an artifact. Say what approving
+          // does, and do NOT auto-verify — the attempt on record is the one the validator rejected,
+          // and a verdict on it would read as a verdict on the build.
+          const exhausted = d.outcome === POLL_OUTCOMES.EXHAUSTED;
+          if (exhausted) {
+            console.log(`⏸  Step ${d.stepKey} (${d.agent || 'unknown'}) used up its format retries and paused.`);
+            console.log(`  ${String(d.errorMessage || '').slice(0, 240)}`);
+            console.log(`  Inspect: hone show step ${pollRunId} ${d.stepKey}`);
+            console.log(`  Approving starts another cycle of ${d.stepKey} with a fresh format budget; it does not `
+              + 'accept an earlier attempt. guardrails.max_retries_per_step caps the cycles.');
+          } else {
+            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
@@ -5698,8 +5753,8 @@ program
           // 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');
+          if (!exhausted) try {
+            const { decideAutoVerify, announce, shouldRepoll, alreadyVerified, verifyOutcomeLine } = require('./lib/auto-verify');
             const decision = decideAutoVerify({
               stepKey: d.stepKey,
               repoRoot: process.cwd(),
@@ -5721,9 +5776,8 @@ program
                 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.');
+              // HC-GF-008: keyed by verify-patch's exit code — "did not pass" only when a command ran and failed.
+              console.log(verifyOutcomeLine(r.status, decision.gate));
             }
           } catch (e) {
             console.log(`  (auto-verify skipped: ${e.message})`);
@@ -5732,7 +5786,7 @@ program
           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));
+            const answer = await new Promise(resolve => rl.question(exhausted ? `  Retry ${d.stepKey} with a fresh format budget? [y/n/kill] ` : '  Approve? [y/n/kill] ', resolve));
             rl.close();
 
             if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
@@ -5757,7 +5811,9 @@ program
           } 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}`);
+            console.log(exhausted
+              ? `  Non-interactive mode. Retry with: hone run-story ${pollRunId} --approve ${d.stepKey}   (or --kill)`
+              : `  Non-interactive mode. Approve with: hone run-story ${pollRunId} --approve ${d.stepKey}`);
             process.exit(d.exitCode);
           }
           continue;
@@ -5769,8 +5825,8 @@ program
 
     // Status mode
     if (opts.status) {
-      const statusId = runId || storyIdOrRunId;
       try {
+        const statusId = await existingRunId('--status');
         const { data } = await client.get(`/orchestrate/${statusId}`);
         if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
         console.log('');
@@ -5819,8 +5875,8 @@ program
 
     // Kill mode
     if (opts.kill) {
-      const killId = runId || storyIdOrRunId;
       try {
+        const killId = await existingRunId('--kill');
         const { data } = await client.post(`/orchestrate/${killId}/kill`, { reason: 'CLI kill' });
         console.log(`Workflow ${data.runId} killed.`);
       } catch (e) {
@@ -5832,10 +5888,12 @@ program
 
     // Approve mode
     if (opts.approve) {
-      const approveId = runId || storyIdOrRunId;
+      let approveId;
       try {
+        approveId = await existingRunId(`--approve ${opts.approve}`);
         await client.post(`/orchestrate/${approveId}/approve`,
-          { stepKey: opts.approve, acknowledgeAbort: opts.acknowledgeAbort === true });
+          { stepKey: opts.approve, acknowledgeAbort: opts.acknowledgeAbort === true,
+            acknowledgeFailedVerdict: opts.acknowledgeFailedVerdict === true });
         console.log(`Gate ${opts.approve} approved. Workflow resuming.`);
       } catch (e) {
         console.error(`Failed: ${e.response?.data?.error || e.message}`);
@@ -5871,7 +5929,6 @@ program
       process.exit(1);
     }
 
-    const repoName = opts.repo || path.basename(process.cwd());
     let branch = opts.branch;
     if (!branch) {
       try { branch = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8' }).trim(); } catch { branch = null; }
@@ -7509,7 +7566,7 @@ showCmd
 // to apply — structure is not applicability.
 program
   .command('check-patch <workflowId>')
-  .description('Verify step_4\'s diff applies to the current working tree (condition 5)')
+  .description('Verify step_4\'s diff applies to HEAD — the tree verify-patch and emit-pr apply it to (condition 5)')
   .option('--step-key <key>', 'Step to check (default: step_4)', 'step_4')
   .option('--attempt <n>', 'Specific attempt number (default: latest)')
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
@@ -7517,7 +7574,7 @@ program
     const { execFileSync } = require('child_process');
     const os = require('os');
     const { extractDiff, interpretApplyCheck } = require('./lib/patch-apply');
-    const { extractFileBlocks, buildDiff, nodeMaterializeIO, MaterializeError } = require('./lib/materialize-diff');
+    const { extractFileBlocks, buildDiff, headMaterializeIO, MaterializeError, hasMaterializableWork } = require('./lib/materialize-diff');
     const { gitEnv } = require('./lib/git-env');
     const config = getConfig();
     const client = api(config);
@@ -7551,10 +7608,10 @@ program
         `○ ${opts.stepKey} declared NO CHANGES — nothing to apply.`);
       return;
     }
-    if (blocks.files.length > 0 || (blocks.edits && blocks.edits.length > 0) || blocks.deletes.length > 0) {
+    if (hasMaterializableWork(blocks)) {
       let built;
       try {
-        built = buildDiff(blocks, nodeMaterializeIO({ cwd: process.cwd() }));
+        built = buildDiff(blocks, headMaterializeIO({ cwd: process.cwd() }));
       } catch (e) {
         if (e instanceof MaterializeError) {
           emit({ ok: false, verdict: 'does_not_apply', reason: e.code, detail: e.message },
@@ -7567,8 +7624,9 @@ program
       source = 'file-blocks';
       noChanges = built.partCount === 0;
       if (noChanges) {
-        emit({ ok: true, verdict: 'no_changes' },
-          `○ ${opts.stepKey} file blocks were identical to the tree — nothing to apply.`);
+        // HC-GF-077: identical to HEAD, not to the working copy — the editor's uncommitted edits are not HEAD.
+        emit({ ok: true, verdict: 'already_in_head', source: 'file-blocks', detail: `HEAD already contains ${opts.stepKey}'s files` },
+          `○ HEAD already contains ${opts.stepKey}'s files — nothing to apply.`);
         return;
       }
     } else {
@@ -7587,16 +7645,25 @@ program
       }
     }
 
-    // Write to a temp file and run git apply --check against the current repo.
+    // Write to a temp file and run git apply --check against HEAD. HC-GF-077: against an index read from HEAD,
+    // not the working copy — an editor's uncommitted edits are exactly what emit-pr's branch will NOT contain.
     const tmp = path.join(os.tmpdir(), `hone-check-patch-${Date.now()}.diff`);
     let result;
     try {
       fs.writeFileSync(tmp, diff);
       let code = 0, stderr = '';
       try {
-        execFileSync('git', ['apply', '--check', tmp], {
-          cwd: process.cwd(), env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
-        });
+        const index = path.join(os.tmpdir(), `hone-check-index-${process.pid}-${Date.now()}`);
+        try {
+          try {
+            execFileSync('git', ['read-tree', `--index-output=${index}`, 'HEAD'], { cwd: process.cwd(), env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+          } catch { // no commit yet: every path is new, so check against the empty tree
+            execFileSync('git', ['read-tree', '--empty', `--index-output=${index}`], { cwd: process.cwd(), env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+          }
+          execFileSync('git', ['apply', '--check', '--cached', tmp], {
+            cwd: process.cwd(), env: gitEnv({ GIT_INDEX_FILE: index }), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+          });
+        } finally { try { fs.unlinkSync(index); } catch { /* best-effort */ } }
       } catch (e) {
         code = e.status || 1;
         stderr = (e.stderr || '').toString();
@@ -7612,7 +7679,7 @@ program
     } else {
       emit({ ok: false, verdict: 'failed', source, detail: result.detail },
         `✗ ${opts.stepKey} diff does NOT apply: ${result.detail}\n` +
-        `  The output is a well-formed diff but does not match the working tree — ` +
+        `  The output is a well-formed diff but does not match HEAD — ` +
         `exactly the defect condition 5 catches that condition 4 cannot.`);
       process.exit(2);  // distinct exit: 2 = does-not-apply, 1 = no-diff/fetch
     }
@@ -7640,8 +7707,8 @@ program
   .action(async (workflowId, opts) => {
     const { execFileSync, spawnSync } = require('child_process');
     const os = require('os');
-    const { extractFileBlocks, buildDiff, nodeMaterializeIO, MaterializeError } = require('./lib/materialize-diff');
-    const { resolveCommand, verdictFromRun, EXIT, resolveAuxGates, classifyGateRun } = require('./lib/verify-patch');
+    const { extractFileBlocks, buildDiff, headMaterializeIO, MaterializeError, hasMaterializableWork } = require('./lib/materialize-diff');
+    const { resolveCommandDetailed, verdictFromRun, verifyCommandEnv, EXIT, resolveAuxGates, classifyGateRun } = require('./lib/verify-patch');
     const { gitEnv } = require('./lib/git-env');
     const config = getConfig();
     const client = api(config);
@@ -7652,12 +7719,17 @@ program
     };
 
     // 1. Fetch step_4 output.
+    // HC-GF-074: the attempt this run verified — reported with the verdict below.
+    let verifiedAttempt;
     let output, runConfig;
     try {
       const url = `/orchestrate/${workflowId}/step/${opts.stepKey}` +
         (opts.attempt ? `?attempt=${opts.attempt}` : '');
       const r = await client.get(url);
       output = r.data?.output;
+      // HC-GF-074: remember WHICH attempt this is. Without --attempt the server returns the latest, and the verdict
+      // used to be reported with `attempt: null` — so no verdict on record could say which build it judged.
+      verifiedAttempt = r.data?.attempt != null ? Number(r.data.attempt) : undefined;
       // best-effort: pull the run's ci_local_command for the default
       try {
         const runR = await client.get(`/orchestrate/${workflowId}`);
@@ -7673,7 +7745,7 @@ program
     // 2. Materialize the diff (shared with check-patch/emit-pr, followup-23/27).
     // Condition 6 presupposes 5.
     const blocks = extractFileBlocks(output);
-    const hasWork = blocks.files.length > 0 || (blocks.edits && blocks.edits.length > 0) || blocks.deletes.length > 0;
+    const hasWork = hasMaterializableWork(blocks);
     if (blocks.noChanges || !hasWork) {
       emit({ ok: false, verdict: 'no_diff', reason: 'no_changes_or_diff' },
         `✗ ${opts.stepKey} produced no file changes to verify.`);
@@ -7681,7 +7753,7 @@ program
     }
     let diff;
     try {
-      diff = buildDiff(blocks, nodeMaterializeIO({ cwd: process.cwd() })).diff;
+      diff = buildDiff(blocks, headMaterializeIO({ cwd: process.cwd() })).diff;
     } catch (e) {
       if (e instanceof MaterializeError) {
         emit({ ok: false, verdict: 'does_not_apply', reason: e.code, detail: e.message },
@@ -7690,17 +7762,17 @@ program
       }
       throw e;
     }
-    if (!diff.trim()) {
-      emit({ ok: true, verdict: 'no_changes' },
-        `○ ${opts.stepKey} file blocks matched the tree — nothing to verify.`);
-      return;
-    }
+    // HC-GF-077: an empty diff against HEAD means HEAD already contains the step's files. That is nothing to
+    // APPLY, not nothing to VERIFY — the command still runs, on HEAD as it is. The old early return exited 0
+    // without running anything, and auto-verify called that "verified and recorded".
+    const alreadyInHead = !diff.trim();
+    if (alreadyInHead && opts.format !== 'json') console.log(`  ○ HEAD already contains ${opts.stepKey}'s files — verifying HEAD as it is`);
 
     // 3. Isolated worktree from HEAD.
     const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'hone-verify-'));
     const diffFile = path.join(os.tmpdir(), `hone-verify-${Date.now()}.diff`);
     fs.writeFileSync(diffFile, diff);
-    const command = resolveCommand(opts.command, runConfig?.ci_local_command, { cwd: process.cwd() }) // followup-7: file re-read + Makefile/npm-aware default;
+    const { command, source: commandSource } = resolveCommandDetailed(opts.command, runConfig?.ci_local_command, { cwd: process.cwd() }); // followup-7 tiers; HC-GF-008: the source says whether `make ci` was a guess
     let cleanupDone = false;
     const cleanup = () => {
       if (cleanupDone || opts.keep) return;
@@ -7729,9 +7801,9 @@ program
       execFileSync('git', ['worktree', 'add', '--detach', wt, 'HEAD'],
         { cwd: process.cwd(), env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
 
-      // 4. Apply the diff INTO the worktree (real apply, isolated).
+      // 4. Apply the diff INTO the worktree (real apply, isolated) — unless HEAD already holds it.
       let applied = true, applyDetail = '';
-      try {
+      if (!alreadyInHead) try {
         execFileSync('git', ['-C', wt, 'apply', diffFile], { env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
       } catch (e) {
         applied = false;
@@ -7757,12 +7829,14 @@ program
         if (opts.format !== 'json') console.log(`  running: ${command}  (in isolated worktree, timeout ${opts.timeout}s)`);
         const run = spawnSync(command, {
           cwd: wt, shell: true, encoding: 'utf8',
-          timeout: Number(opts.timeout) * 1000, env: gitEnv(),
+          timeout: Number(opts.timeout) * 1000, env: verifyCommandEnv(gitEnv()),
           stdio: ['ignore', 'pipe', 'pipe'],
         });
         const timedOut = run.error && run.error.code === 'ETIMEDOUT';
-        const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr });
-        const sym = v.verdict === 'pass' ? '✓' : v.verdict === 'timeout' ? '⏱' : '✗';
+        const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr, command, source: commandSource });
+        // HC-GF-077: nothing was applied when HEAD already held the step — say what the command actually ran on.
+        if (alreadyInHead && v.verdict === 'pass') v.detail = "tests passed on HEAD, which already contains the step's files";
+        const sym = v.verdict === 'pass' ? '✓' : v.verdict === 'timeout' ? '⏱' : v.verdict === 'unresolved' ? '○' : '✗';
 
         // HC-GF-023: on a failure the operator needs the OUTPUT, not a quote from it.
         // The full log is written OUTSIDE the worktree (cleanup removes the worktree)
@@ -7807,7 +7881,7 @@ program
           for (const gate of resolveAuxGates({ configured: ciCfg, cwd: process.cwd() })) {
             const gr = spawnSync(gate.command, {
               cwd: wt, shell: true, encoding: 'utf8',
-              timeout: Number(opts.timeout) * 1000, env: gitEnv(),
+              timeout: Number(opts.timeout) * 1000, env: verifyCommandEnv(gitEnv()),
               stdio: ['ignore', 'pipe', 'pipe'],
             });
             const c = classifyGateRun({
@@ -7847,7 +7921,7 @@ program
           verdict: reportVerdict,
           exitCode,
           detail: reportDetail,
-          attempt: opts.attempt ? Number(opts.attempt) : undefined,
+          attempt: opts.attempt ? Number(opts.attempt) : verifiedAttempt,
           headSha,
           gates: reportGates.length ? reportGates : undefined,
         });
@@ -7921,8 +7995,8 @@ program
   .action(async (workflowId, opts) => {
     const { execFileSync, spawnSync } = require('child_process');
     const os = require('os');
-    const { extractFileBlocks, buildDiff, nodeMaterializeIO, MaterializeError } = require('./lib/materialize-diff');
-    const { resolveCommand, verdictFromRun } = require('./lib/verify-patch');
+    const { extractFileBlocks, buildDiff, headMaterializeIO, MaterializeError, hasMaterializableWork } = require('./lib/materialize-diff');
+    const { resolveCommandDetailed, verdictFromRun, verifyCommandEnv } = require('./lib/verify-patch');
     const {
       EXIT, buildBranchName, buildCommitMessage, buildPrBody, decidePublish,
     } = require('./lib/emit-pr');
@@ -7962,7 +8036,7 @@ program
     // 2. Materialize the diff (shared with check-patch/verify-patch,
     // followup-23/27). Condition 7 presupposes 5.
     const blocks = extractFileBlocks(output);
-    const hasWork = blocks.files.length > 0 || (blocks.edits && blocks.edits.length > 0) || blocks.deletes.length > 0;
+    const hasWork = hasMaterializableWork(blocks);
     if (blocks.noChanges || !hasWork) {
       emit({ ok: false, verdict: 'no_diff', reason: 'no_changes_or_diff' },
         `✗ ${opts.stepKey} produced no file changes to emit.`);
@@ -7970,7 +8044,7 @@ program
     }
     let diff;
     try {
-      diff = buildDiff(blocks, nodeMaterializeIO({ cwd: process.cwd() })).diff;
+      diff = buildDiff(blocks, headMaterializeIO({ cwd: process.cwd() })).diff;
     } catch (e) {
       if (e instanceof MaterializeError) {
         emit({ ok: false, verdict: 'does_not_apply', reason: e.code, detail: e.message },
@@ -7980,8 +8054,9 @@ program
       throw e;
     }
     if (!diff.trim()) {
-      emit({ ok: true, verdict: 'no_changes' },
-        `○ ${opts.stepKey} file blocks matched the tree — nothing to emit.`);
+      // HC-GF-077: empty against HEAD — the base branch already holds the change, so there is nothing to emit.
+      emit({ ok: true, verdict: 'already_in_head', detail: `HEAD already contains ${opts.stepKey}'s files` },
+        `○ HEAD already contains ${opts.stepKey}'s files — nothing to emit.`);
       return;
     }
 
@@ -8028,7 +8103,7 @@ program
     const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'hone-emit-'));
     const diffFile = path.join(os.tmpdir(), `hone-emit-${Date.now()}.diff`);
     fs.writeFileSync(diffFile, diff);
-    const command = resolveCommand(opts.command, runConfig?.ci_local_command, { cwd: process.cwd() }) // followup-7: file re-read + Makefile/npm-aware default;
+    const { command, source: commandSource } = resolveCommandDetailed(opts.command, runConfig?.ci_local_command, { cwd: process.cwd() }); // followup-7 tiers; HC-GF-008: the source says whether `make ci` was a guess
     // `worktree add -b` creates the branch ref BEFORE apply/verify. If we bail
     // before a successful commit (apply fails, verify fails), that empty branch
     // (pointing at HEAD) must be torn down too — else "a failing diff never
@@ -8086,19 +8161,21 @@ program
           if (opts.format !== 'json') console.log(`  verifying: ${command}  (in isolated worktree, timeout ${opts.timeout}s)`);
           const run = spawnSync(command, {
             cwd: wt, shell: true, encoding: 'utf8',
-            timeout: Number(opts.timeout) * 1000, env: gitEnv(),
+            timeout: Number(opts.timeout) * 1000, env: verifyCommandEnv(gitEnv()),
             stdio: ['ignore', 'pipe', 'pipe'],
           });
           const timedOut = run.error && run.error.code === 'ETIMEDOUT';
-          const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr });
+          const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr, command, source: commandSource });
           if (v.verdict === 'pass') {
             verifyState = 'pass';
           } else {
             verifyOk = false;
-            const sym = v.verdict === 'timeout' ? '⏱' : '✗';
+            // HC-GF-008: a command that never started is not a failed verify.
+            const unresolved = v.verdict === 'unresolved';
+            const sym = unresolved ? '○' : v.verdict === 'timeout' ? '⏱' : '✗';
             emit({ ok: false, verdict: v.verdict, command, detail: v.detail },
-              `${sym} verify failed, no branch emitted: ${v.detail}\n  (command: ${command})`);
-            exitCode = v.exitCode; // 3 tests-failed or 4 timeout
+              `${sym} ${unresolved ? 'verify could not run, no branch emitted' : 'verify failed, no branch emitted'}: ${v.detail}\n  (command: ${command})`);
+            exitCode = v.exitCode; // 3 tests-failed, 4 timeout, 7 unresolved
           }
         }
 
@@ -8258,7 +8335,9 @@ program
       if (!command) { try { command = readCIGateConfig(repoRoot).local_command; } catch { command = 'make ci'; } }
       command = command || 'make ci';
       if (opts.format !== 'json') console.log(`  running local CI: ${command} (timeout ${opts.timeout}s)`);
-      const run = spawnSync(command, { cwd: repoRoot, shell: true, encoding: 'utf8', timeout: Number(opts.timeout) * 1000, stdio: ['ignore', 'inherit', 'inherit'] });
+      // HC-GF-008: the adopter's own command, without make state inherited from whoever ran hone.
+      const { verifyCommandEnv } = require('./lib/verify-patch');
+      const run = spawnSync(command, { cwd: repoRoot, shell: true, encoding: 'utf8', timeout: Number(opts.timeout) * 1000, stdio: ['ignore', 'inherit', 'inherit'], env: verifyCommandEnv(gitEnv()) });
       local = { code: run.status == null ? 1 : run.status, timedOut: !!(run.error && run.error.code === 'ETIMEDOUT') };
     }
 

package/lib/auto-verify.js

@@ -164,4 +164,24 @@ function verdictReportLine(verdict, gate) {
   return `  → reported verdict '${verdict}' to the server (${effect})`;
 }
 
-module.exports = { decideAutoVerify, announce, readVerificationAuto, shouldRepoll, alreadyVerified, verdictReportLine, VERIFIABLE_STEP };
+/**
+ * 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/headroom.js

@@ -0,0 +1,63 @@
+'use strict';
+/**
+ * HC-GF-089 — how close a step came to its limits, said before it hits one.
+ *
+ * The largest local build used 793s of its 900s limit and nothing said so. Until now the only way to
+ * learn where a limit bites was to hit it: HC-GF-114 exists because the cut-off path had never fired
+ * in the entire run history, and reaching it took lowering a cap by hand. A run one slow story away
+ * from a timeout should say so while it still completes.
+ *
+ * ADVISORY by construction. This never blocks, never routes back and never changes a verdict — it
+ * prints. A signal that could fail a run would need a far higher bar than "approaching a limit", and
+ * a warning that reads like a rejection trains operators to ignore it.
+ */
+
+/** HC-GF-080's per-message output cap — what the CLI child actually runs with. */
+const TOKEN_CAP_PER_MESSAGE = 128_000;
+
+/** Three quarters. Low enough to give a story's worth of warning, high enough not to fire routinely. */
+const THRESHOLD = 0.75;
+
+/** A ratio, or null when there is nothing to judge — a missing limit is not a limit of zero. */
+function ratio(used, limit) {
+  const u = Number(used);
+  const l = Number(limit);
+  if (!Number.isFinite(u) || !Number.isFinite(l) || l <= 0 || u < 0) return null;
+  return u / l;
+}
+
+/**
+ * One line when a step passed THRESHOLD of its time or per-message token budget, else null.
+ * @param {object} generation HC-GF-079's generation report, as stored on the step row.
+ */
+function headroomLine(generation) {
+  const g = generation && typeof generation === 'object' ? generation : {};
+
+  const timeRatio = ratio(g.elapsed_ms, g.timeout_ms);
+  // The BUSIEST message decides: a build whose last message nearly filled the cap is at risk even
+  // when the earlier ones were small, and an average would hide exactly that.
+  const counts = (Array.isArray(g.output_tokens) ? g.output_tokens : [])
+    .map(Number).filter((n) => Number.isFinite(n) && n >= 0);
+  const busiest = counts.length ? Math.max(...counts) : null;
+  const tokenRatio = busiest === null ? null : ratio(busiest, TOKEN_CAP_PER_MESSAGE);
+
+  const parts = [];
+  if (timeRatio !== null && timeRatio >= THRESHOLD) {
+    parts.push(`time ${Math.round(timeRatio * 100)}% `
+      + `(${Math.round(Number(g.elapsed_ms) / 1000)}s of ${Math.round(Number(g.timeout_ms) / 1000)}s)`);
+  }
+  if (tokenRatio !== null && tokenRatio >= THRESHOLD) {
+    parts.push(`tokens ${Math.round(tokenRatio * 100)}% `
+      + `(${busiest} of ${TOKEN_CAP_PER_MESSAGE} in one message)`);
+  }
+  if (!parts.length) return null;
+  // HC-GF-129: the threshold has no upper bound, so every ratio from 75% to infinity used to get
+  // the same reassurance. On run 692b0c29 a call that ran 550,017ms against a 550,000ms ceiling —
+  // it TIMED OUT, `complete: false`, the build was cut off — was reported as "not over it".
+  // At or past 1.0 the limit was reached, and saying otherwise is simply false.
+  const over = (timeRatio !== null && timeRatio >= 1) || (tokenRatio !== null && tokenRatio >= 1);
+  return `headroom: ${parts.join(', ')} — `
+    + (over ? 'the limit was REACHED: this call was cut off' : 'close to the limit, not over it');
+}
+
+module.exports = { headroomLine, TOKEN_CAP_PER_MESSAGE, THRESHOLD };