@hone-ai/cli 1.19.0 → 1.20.0

package/hone-cli.js

@@ -144,6 +144,130 @@ process.on('exit', () => {
   }
 });
 
+// ── AGENT-EVAL command (HC-COMM-011-followup-1) ──────────────────────────────────
+// Runs deterministic adversarial probes against a configured agent target. $0 —
+// no LLM judge. A probe passes iff the executor ran AND every grader passes
+// (canary absent AND refusal present). Exits non-zero if any probe fails.
+program
+  .command('agent-eval')
+  .description('Run agent-eval probes against configured agent targets (HC-COMM-011-followup-1)')
+  .option('--category <category>', 'Probe category (adversarial|faithfulness|safety|boundary)', 'adversarial')
+  .option('--target <name>', 'Run against a specific agent target (default: all configured)')
+  .option('--output <format>', 'Output format (text|json)', 'text')
+  .option('--judge', 'Add the free NLI judge layer (faithfulness only): claims are checked for entailment against the probe context')
+  .option('--provider <name>', 'Judge provider: gh-models (free, default) | claude (paid Sonnet)', 'gh-models')
+  .option('--report', 'Report the agent-eval verdict to the run (advisory) — needs --workflow-id')
+  .option('--workflow-id <id>', 'The run id to report the verdict against (for --report)')
+  .action(async (opts) => {
+    const { readAgentEvalConfig } = require('./lib/pipeline-config');
+    const { runAgent } = require('./lib/agent-executor');
+    const { runCheck } = require('./lib/eval-graders');
+    const config = readAgentEvalConfig(process.cwd());
+
+    if (!config.targets || config.targets.length === 0) {
+      console.log('No agent targets configured in .pipeline-config.yml (agent_eval.targets)');
+      process.exit(0);
+    }
+
+    const PROBE_PACKS = {
+      adversarial: './lib/agent-eval-probes-adversarial',
+      faithfulness: './lib/agent-eval-probes-faithfulness',
+      safety: './lib/agent-eval-probes-safety',
+      boundary: './lib/agent-eval-probes-boundary',
+    };
+    let probes;
+    if (PROBE_PACKS[opts.category]) {
+      probes = require(PROBE_PACKS[opts.category]);
+    } else {
+      console.error(`Unknown probe category: ${opts.category} (supported: ${Object.keys(PROBE_PACKS).join(', ')})`);
+      process.exit(1);
+    }
+
+    const targets = opts.target
+      ? config.targets.filter((t) => t.name === opts.target)
+      : config.targets;
+    if (targets.length === 0) {
+      console.error(`No agent target named "${opts.target}" in config`);
+      process.exit(1);
+    }
+
+    // Optional free NLI judge layer (faithfulness only). Build the provider callLLM
+    // ONCE — a missing credential is a hard error, not a silent skip.
+    let judgeCall = null;
+    if (opts.judge) {
+      if (opts.category !== 'faithfulness') {
+        console.error(`--judge applies to --category faithfulness only (got: ${opts.category})`);
+        process.exit(1);
+      }
+      const { buildJudgeCallLLM } = require('./lib/judge-provider');
+      const built = buildJudgeCallLLM(opts.provider, { axios });
+      if (built.error) { console.error(built.error); process.exit(1); }
+      judgeCall = built.callLLM;
+    }
+
+    const results = [];
+    let anyFailed = false;
+    for (const target of targets) {
+      for (const probe of probes) {
+        const run = await runAgent(target, probe.input);
+        const output = run && typeof run.output === 'string' ? run.output : '';
+        const graders = probe.graders.map((g) => runCheck(output, g));
+        let passed = !run.error && graders.every((r) => r.passed);
+
+        // Judge layer: only for grounded probes (those with a context to entail against).
+        let judge = null;
+        if (judgeCall && probe.context) {
+          const { judgeFaithfulness } = require('./lib/agent-eval-judge');
+          judge = await judgeFaithfulness({ output, context: probe.context, callLLM: judgeCall });
+          passed = passed && judge.passed;
+        }
+        if (!passed) anyFailed = true;
+        results.push({ target: target.name, probe: probe.id, passed, error: run.error || null, graders, judge });
+      }
+    }
+
+    if (opts.output === 'json') {
+      console.log(JSON.stringify({ category: opts.category, passed: !anyFailed, results }, null, 2));
+    } else {
+      for (const r of results) {
+        const mark = r.passed ? '✓' : '✗';
+        console.log(`  ${mark} ${r.target} / ${r.probe}${r.error ? ` (executor: ${r.error})` : ''}`);
+        if (!r.passed) {
+          for (const g of r.graders.filter((x) => !x.passed)) console.log(`      - ${g.type}: ${g.detail}`);
+          if (r.judge && !r.judge.passed) console.log(`      - judge: ${r.judge.detail}`);
+        }
+      }
+      const pass = results.filter((r) => r.passed).length;
+      console.log(`\n${pass}/${results.length} probes passed (category: ${opts.category})`);
+    }
+
+    // Closed loop (HC-COMM-011-followup-5): report the verdict to the run. agent-eval
+    // binds to step_4 (a prompt change is a step_4 diff) and is ADVISORY — it records
+    // into config.verifications[], never auto-gates. Best-effort; never changes the
+    // local exit code.
+    if (opts.report) {
+      if (!opts.workflowId) {
+        if (opts.output !== 'json') console.warn('  ⚠ --report needs --workflow-id <run id> to address the run; skipping report.');
+      } else {
+        try {
+          const client = api(getConfig());
+          await client.post(`/orchestrate/${opts.workflowId}/verdict`, {
+            source: 'agent-eval',
+            stepKey: 'step_4',
+            verdict: anyFailed ? 'fail' : 'pass',
+            exitCode: anyFailed ? 1 : 0,
+            detail: `agent-eval ${opts.category}: ${results.filter((r) => r.passed).length}/${results.length} probes passed`,
+          });
+          if (opts.output !== 'json') console.log(`  → reported agent-eval verdict '${anyFailed ? 'fail' : 'pass'}' to run ${opts.workflowId} (advisory)`);
+        } catch (e) {
+          if (opts.output !== 'json') console.warn(`  ⚠ verdict report failed (non-fatal): ${e.response?.data?.error || e.message}`);
+        }
+      }
+    }
+
+    process.exit(anyFailed ? 1 : 0);
+  });
+
 // ── SETUP-LOCAL-CI command (HC-101-followup-3) ─────────────────────────────────
 //
 // Scaffolds HC-101's local-CI assets into the adopter's repo so they can
@@ -1777,6 +1901,207 @@ program
     }
   });
 
+// ── BYO-KEY command (HC-COMM-013 / A2) ───────────────────────────────────────
+// Self-serve management of your org's Anthropic API key for server mode. The
+// key is read from stdin (piped) or a HIDDEN prompt — NEVER accepted on argv,
+// which would leak it to shell history (~/.zsh_history), `ps`, and CI logs.
+
+// Read a secret without echoing it. Piped stdin → read all of it (CI/secret-
+// manager injection). Interactive TTY → a muted readline prompt.
+async function _readSecret(promptText) {
+  if (!process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+  }
+  const readline = await import('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    process.stdout.write(promptText);
+    // Mute echo of typed characters — the prompt is already written.
+    rl._writeToOutput = () => {};
+    rl.question('', (answer) => {
+      rl.close();
+      process.stdout.write('\n');
+      resolve(answer);
+    });
+  });
+}
+
+function _handleByoKeyError(e) {
+  const status = e.response?.status;
+  if (status === 401) {
+    console.error('Not authenticated. Run: hone init --token <token>');
+  } else if (status === 429) {
+    const retry = e.response?.data?.retryAfter;
+    console.error(`Rate limited — too many key writes.${retry ? ` Retry after ${retry}s.` : ''}`);
+  } else if (status === 503) {
+    console.error(`Server cannot store the key right now: ${e.response?.data?.error || 'unavailable'}`);
+  } else if (e.response?.data?.error) {
+    console.error(`Failed: ${e.response.data.error}`);
+  } else {
+    console.error(`Failed: ${e.message}`);
+  }
+  process.exit(1);
+}
+
+const MAX_BYO_KEY_BYTES_CLI = 1024;
+
+const byoKeyCmd = program
+  .command('byo-key')
+  .description("Manage your org's BYO Anthropic API key (server mode)");
+
+byoKeyCmd
+  .command('set')
+  .description('Set or rotate your key — reads from stdin or a hidden prompt (never pass the key on the command line)')
+  .option('--key-file <path>', 'Read the key from a file (e.g. a 0600 secrets file) instead of stdin/prompt')
+  .action(async (opts) => {
+    const config = getConfig();
+    const client = api(config);
+
+    let key;
+    try {
+      key = opts.keyFile
+        ? fs.readFileSync(opts.keyFile, 'utf8')
+        : await _readSecret('Anthropic API key: ');
+    } catch (e) {
+      console.error(`Could not read key: ${e.message}`);
+      process.exit(1);
+    }
+    key = (key || '').trim();
+
+    // Client-side convenience checks (server remains the authority).
+    if (!key) {
+      console.error('No key provided (empty input). Pipe it in or type it at the prompt.');
+      process.exit(1);
+    }
+    if (Buffer.byteLength(key, 'utf8') > MAX_BYO_KEY_BYTES_CLI) {
+      console.error(`Key too large (max ${MAX_BYO_KEY_BYTES_CLI} bytes). Did you paste the wrong thing?`);
+      process.exit(1);
+    }
+    if (!key.startsWith('sk-ant-')) {
+      // Warn-only (memo §8): Anthropic key formats can change; don't hard-block.
+      console.error('Warning: key does not look like an Anthropic key (expected "sk-ant-" prefix). Sending anyway.');
+    }
+
+    try {
+      const { data } = await client.put('/orgs/me/byo-key', { byo_anthropic_key: key });
+      console.log(data.wasConfigured
+        ? 'BYO key rotated. Pipeline LLM calls now bill your own Anthropic API.'
+        : 'BYO key set. Pipeline LLM calls now bill your own Anthropic API.');
+    } catch (e) { _handleByoKeyError(e); }
+  });
+
+byoKeyCmd
+  .command('clear')
+  .description('Clear your key — your org reverts to the Hone default key')
+  .action(async () => {
+    const config = getConfig();
+    const client = api(config);
+    try {
+      const { data } = await client.delete('/orgs/me/byo-key');
+      console.log(data.wasConfigured
+        ? 'BYO key cleared. Your org reverts to the Hone default key.'
+        : 'No BYO key was configured — nothing to clear.');
+    } catch (e) { _handleByoKeyError(e); }
+  });
+
+byoKeyCmd
+  .command('status')
+  .description('Show whether a BYO key is configured (never prints the key)')
+  .option('--format <fmt>', 'Output format: pretty | json', 'pretty')
+  .action(async (opts) => {
+    const config = getConfig();
+    const client = api(config);
+    try {
+      const { data } = await client.get('/orgs/me/byo-key');
+      if (opts.format === 'json') {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      console.log(`BYO key configured: ${data.configured ? 'yes' : 'no'}`);
+      if (data.lastWrite) {
+        const when = String(data.lastWrite.at).split('T')[0];
+        console.log(`Last change:        ${data.lastWrite.action} by ${data.lastWrite.actorType} on ${when}`);
+      }
+      if (data.configured && data.envelopeOk === false) {
+        console.log('Warning: stored value is not in the expected encrypted envelope shape — contact support.');
+      }
+      // HC-COMM-014: fold a one-line trial summary in (non-fatal if unavailable).
+      try {
+        const { data: plan } = await client.get('/orgs/me/plan');
+        if (plan.mode === 'trial') {
+          console.log(`Trial:              active — ${plan.trial.daysLeft}d left, $${Number(plan.trial.creditRemaining).toFixed(2)} credit`);
+        } else if (plan.mode === 'expired') {
+          console.log('Trial:              ended (set a key or upgrade)');
+        }
+      } catch { /* trial line is a nicety — never block byo-key status */ }
+      console.log('Tip: run `hone byo-key check` to verify the key still authenticates with Anthropic.');
+    } catch (e) { _handleByoKeyError(e); }
+  });
+
+byoKeyCmd
+  .command('check')
+  .description('Verify the configured key still authenticates with Anthropic (zero-token live probe; never prints the key)')
+  .action(async () => {
+    const config = getConfig();
+    const client = api(config);
+    try {
+      const { data } = await client.post('/orgs/me/byo-key/check');
+      if (data.ok) {
+        console.log('BYO key is valid — Anthropic accepted it.');
+        return;
+      }
+      const msg = {
+        unauthorized: 'BYO key was REJECTED by Anthropic (401/403). Rotate it with `hone byo-key set`.',
+        unreachable:  'Could not reach Anthropic to check the key — try again shortly (key not changed).',
+        unexpected:   'Anthropic returned an unexpected status checking the key — try again shortly.',
+      }[data.reason] || `Key check failed: ${data.reason}`;
+      console.error(msg);
+      process.exit(1);
+    } catch (e) { _handleByoKeyError(e); }
+  });
+
+// ── TRIAL command (HC-COMM-014 / A3) ─────────────────────────────────────────
+const trialCmd = program
+  .command('trial')
+  .description("View or start your org's Hone-funded trial (server mode)");
+
+trialCmd
+  .command('status')
+  .description('Show trial mode, days left, and credit remaining')
+  .option('--format <fmt>', 'Output format: pretty | json', 'pretty')
+  .action(async (opts) => {
+    const config = getConfig();
+    const client = api(config);
+    try {
+      const { data } = await client.get('/orgs/me/plan');
+      if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      const t = data.trial || {};
+      console.log(`Plan mode:       ${data.mode}`);
+      console.log(`Trial status:    ${t.status}`);
+      if (t.status === 'active') {
+        console.log(`Days left:       ${t.daysLeft}`);
+        console.log(`Credit:          $${Number(t.creditUsdUsed || 0).toFixed(2)} used / $${Number(t.creditUsdCap).toFixed(2)} cap ($${Number(t.creditRemaining).toFixed(2)} left)`);
+      }
+      if (data.mode === 'expired') {
+        console.log('Trial ended — set your own key (`hone byo-key set`) or upgrade to continue.');
+      }
+    } catch (e) { _handleByoKeyError(e); }
+  });
+
+trialCmd
+  .command('start')
+  .description('Start your trial now (idempotent — no-op if already started or ended)')
+  .action(async () => {
+    const config = getConfig();
+    const client = api(config);
+    try {
+      const { data } = await client.post('/orgs/me/trial/start');
+      console.log(data.started ? `Trial started — status: ${data.status}.` : `No-op — ${data.note}`);
+    } catch (e) { _handleByoKeyError(e); }
+  });
+
 // ── ADMIN-USAGE command ──────────────────────────────────────────────────────
 program
   .command('admin-usage')
@@ -4598,7 +4923,8 @@ program
   .option('--contracts', 'Run contract validation between pipeline agents')
   .option('--snapshot', 'Save current eval + contract results as regression baseline')
   .option('--regression', 'Compare current results against saved baseline (detect drift)')
-  .option('--judge', 'Run LLM-as-judge scenarios (requires ANTHROPIC_API_KEY, costs tokens)')
+  .option('--judge', 'Run LLM-as-judge scenarios (default provider: free gh-models via GITHUB_TOKEN)')
+  .option('--provider <name>', 'LLM-judge provider: gh-models (free, default) | claude (paid Sonnet)', 'gh-models')
   .option('--evidence-mode <mode>', 'HC-RC-001 editor-LLM evidence transfer: "local" writes .hone/eval-evidence.json (signed); "off" disables (default)')
   .action(async (opts) => {
     const path = require('path');
@@ -4666,12 +4992,8 @@ program
       const { loadScenarios, formatResults } = require('./lib/eval-runner');
       const { runJudgeScenario } = require('./lib/eval-llm-judge');
 
-      const apiKey = process.env.ANTHROPIC_API_KEY;
-      if (!apiKey) {
-        console.error('ANTHROPIC_API_KEY required for --judge mode. Set: export ANTHROPIC_API_KEY=sk-ant-...');
-        process.exit(1);
-      }
-
+      // Load + filter FIRST — if there are no judge scenarios, exit cleanly
+      // without demanding any API key / token.
       const scenarios = loadScenarios({
         evalDir, agent: opts.agent, tag: opts.tag, scenarioId: opts.scenario,
         readFile: (p) => fs.readFileSync(p, 'utf8'),
@@ -4685,48 +5007,21 @@ program
         process.exit(0);
       }
 
-      // LLM call function using Anthropic API
-      async function callLLM(systemPrompt, userPrompt) {
-        const { data } = await axios.post('https://api.anthropic.com/v1/messages', {
-          // MODEL CHOICE (per feedback_model_choice_cost_amplifier): Sonnet tier,
-          // deliberately NOT Opus. The eval judge is not one of the three
-          // load-bearing SDLC agents on the OPUS_AGENTS allowlist (architect,
-          // security, code-reviewer — HC-COMM-007); it grades eval scenarios,
-          // where Sonnet is sufficient and Opus would be a 2.5x input-cost
-          // escalation on a call site that can run once per scenario.
-          //
-          // Previously a dated 2025-05-14 Sonnet id, which Anthropic deprecated
-          // with a 2026-06-15 deadline. The #507 Opus 4.8 sweep missed this call
-          // site because it searched only for opus ids. Pinned by
-          // tests/regression/opus-4-8-upgrade.test.js — note that suite forbids
-          // the retired id even inside comments, so name it descriptively here.
-          model: 'claude-sonnet-5',
-          // Sonnet 5 runs ADAPTIVE THINKING when `thinking` is omitted, unlike
-          // the dated Sonnet 4 model this replaced. Two consequences if left
-          // default, both silent: content[0] becomes a `thinking` block (so a
-          // [0].text read returns undefined and every judge criterion fails to
-          // parse), and thinking tokens share max_tokens with the answer.
-          // The judge returns a short structured verdict, so keep it off and
-          // preserve the previous cost/latency profile.
-          thinking: { type: 'disabled' },
-          max_tokens: 2048,
-          system: systemPrompt,
-          messages: [{ role: 'user', content: userPrompt }],
-        }, {
-          headers: {
-            'x-api-key': apiKey,
-            'anthropic-version': '2023-06-01',
-            'content-type': 'application/json',
-          },
-          timeout: 60000,
-        });
-        // Select the first TEXT block rather than content[0]: any future model
-        // or config that emits a leading thinking block must not silently
-        // degrade every scenario to "could not parse response".
-        return (data.content || []).find(b => b?.type === 'text')?.text || '';
-      }
-
-      console.log(`Running ${judgeScenarios.length} LLM-judge scenario(s)...`);
+      // HC-019n-followup-33 (pipeline-standards G6): the LLM-judge lane must have a
+      // ZERO-COST path (feedback_pipeline_llm_cost_reduction — every LLM-cost gate
+      // needs a free/near-free route so adopters aren't double-billed). DEFAULT to
+      // GH Models (free inference via GITHUB_TOKEN); paid Claude Sonnet is opt-in
+      // via `--provider claude`. Mirrors `hone skill-eval`'s provider convention.
+      // HC-COMM-011-followup-3: provider wiring extracted to lib/judge-provider.js
+      // (shared with `hone agent-eval --judge`). Same zero-cost default (gh-models)
+      // + Sonnet-not-Opus paid path; the retired dated Sonnet id must not appear
+      // (pinned by opus-4-8-upgrade.test.js).
+      const { buildJudgeCallLLM } = require('./lib/judge-provider');
+      const built = buildJudgeCallLLM(opts.provider, { axios });
+      if (built.error) { console.error(built.error); process.exit(1); }
+      const callLLM = built.callLLM;
+
+      console.log(`Running ${judgeScenarios.length} LLM-judge scenario(s) via ${built.provider}...`);
       console.log('');
 
       const results = [];
@@ -5027,6 +5322,8 @@ program
   .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
   .option('--poll-interval <s>', 'Poll interval in seconds', '5')
   .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)')
   .action(async (storyIdOrRunId, opts) => {
     const config = getConfig();
     const client = api(config);
@@ -5166,6 +5463,41 @@ program
         console.warn('  → proceeding without story_description; step_0 may produce placeholder output');
         console.warn(`  ⚠ architect-config lookup will use '${storyIdOrRunId}' (likely silent miss)`);
       }
+    } else {
+      // HC-019n-followup-18: roadmap-sourced story. Only the SERVER knows what
+      // the story says (server/seeds/master-roadmap.md is a Hone asset, absent
+      // from adopter repos) and only the CLI can read the adopter's disk — so
+      // ask the server what the description references, then read those files
+      // here. See .github/pipeline/HC-019n-followup-18/architect.md §1 for why
+      // this beats the CLI reading a local roadmap (hardcodes a Hone-internal
+      // path into the adopter CLI, and fails silently anywhere else).
+      //
+      // Advisory, never fatal: a story with no resolvable context still runs,
+      // it just runs blind — and loudly, via the followup-17 warning below.
+      try {
+        const ctxClient = api(config);
+        const { data } = await ctxClient.get(
+          `/stories/${encodeURIComponent(storyIdOrRunId)}/context`
+        );
+        if (data && data.description) {
+          orchestrateConfig.story_description = data.description;
+          issueBodyForFiles = data.description;
+          const n = Array.isArray(data.referencedPaths) ? data.referencedPaths.length : 0;
+          console.log(
+            `  → resolved story context from roadmap (${data.description.length} chars, ` +
+            `${n} referenced path${n === 1 ? '' : 's'})`
+          );
+        }
+      } catch (e) {
+        const status = e && e.response && e.response.status;
+        if (status === 404) {
+          console.warn(`  ⚠ no roadmap row found for '${storyIdOrRunId}'`);
+        } else {
+          const msg = (e && e.message) ? e.message.split('\n')[0] : String(e);
+          console.warn(`  ⚠ could not fetch story context: ${msg}`);
+        }
+        console.warn('  → proceeding without story context; the warning below applies');
+      }
     }
 
     // HC-019n-followup-12: auto-bundle codebase files referenced in the
@@ -5207,6 +5539,45 @@ program
             candidates.add(p);
           }
         }
+        // HC-019n-followup-26: FILE_PATH_RE above requires a directory segment,
+        // so a story that names a file BARE (`derive-worker.js:787` in prose)
+        // extracts 0 paths and step_4 runs blind — and, blind, hallucinates a
+        // file at a non-existent path (2026-08-30 e2e demo). Catch bare refs too
+        // and resolve each against the repo's own file list: bundle ONLY on a
+        // unique basename match; never guess an ambiguous or absent one.
+        // HC-019n-followup-27: candidate path → referenced line number, so the
+        // bundler can WINDOW a too-big file around its edit site instead of
+        // head-truncating past it (the demo's line 787 sits at char 37K).
+        const candidateLines = new Map();
+        if (issueBodyForFiles) {
+          const { extractBareRefs, resolveBareName, alreadyCovered } = require('./lib/bundle-paths');
+          const { gitEnv } = require('./lib/git-env');
+          const bareRefs = extractBareRefs(issueBodyForFiles);
+          if (bareRefs.length > 0) {
+            let repoFiles = null;
+            const listRepoFiles = () => {
+              if (repoFiles) return repoFiles;
+              try {
+                repoFiles = execSync('git ls-files', {
+                  cwd: process.cwd(), env: gitEnv(), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+                }).split('\n').filter(Boolean);
+              } catch { repoFiles = []; }
+              return repoFiles;
+            };
+            for (const { name, line } of bareRefs) {
+              if (alreadyCovered(name, candidates)) continue;
+              const r = resolveBareName(name, listRepoFiles());
+              if (r.status === 'unique') {
+                candidates.add(r.path);
+                if (line && !candidateLines.has(r.path)) candidateLines.set(r.path, line);
+                console.log(`  → resolved bare ref '${name}${line ? ':' + line : ''}' → ${r.path}`);
+              } else if (r.status === 'ambiguous') {
+                console.warn(`  ⚠ '${name}' is ambiguous (${r.matches.length} files) — not bundling; use --include-paths to disambiguate`);
+              }
+              // status === 'none' → not every filename in prose is a repo file; skip quietly
+            }
+          }
+        }
         // HC-019n-followup-13d: bump caps. Pre-fix MAX_FILES=10 /
         // MAX_TOTAL_CHARS=50_000 / MAX_PER_FILE_CHARS=10_000 was overly
         // conservative — OptionsFlow #96 hit 49,783/50,000 with 6 files
@@ -5230,7 +5601,23 @@ program
             content = fs.readFileSync(abs, 'utf8');
           } catch { continue; }
           if (content.length > MAX_PER_FILE_CHARS) {
-            content = content.slice(0, MAX_PER_FILE_CHARS) + `\n\n# [HC-019n-followup-12: truncated at ${MAX_PER_FILE_CHARS} chars; full file is ${content.length} chars]`;
+            const line = candidateLines.get(candidate);
+            if (line) {
+              // HC-019n-followup-27: window around the referenced line so step_4
+              // SEES the edit site (head-truncation would hide a site past the
+              // cut) and can write a region-edit anchor. The window marker tells
+              // step_4 to emit an `edit:` block, not a whole-file block.
+              const { windowAroundLine } = require('./lib/bundle-paths');
+              const w = windowAroundLine(content, line, Math.floor((MAX_PER_FILE_CHARS - 800) / 2));
+              content =
+                `# [HC-019n-followup-27: windowed excerpt, lines ${w.startLine}-${w.endLine} of ${w.totalLines} ` +
+                `(centered on referenced line ${line}); you were NOT shown the whole file — ` +
+                `emit an \`edit:\` block with a unique OLD anchor from this excerpt, NOT a whole-file \`file:\` block]\n` +
+                w.excerpt +
+                `\n# [end windowed excerpt of ${candidate}]`;
+            } else {
+              content = content.slice(0, MAX_PER_FILE_CHARS) + `\n\n# [HC-019n-followup-12: truncated at ${MAX_PER_FILE_CHARS} chars; full file is ${content.length} chars]`;
+            }
           }
           if (totalChars + content.length > MAX_TOTAL_CHARS) break;
           totalChars += content.length;
@@ -5246,6 +5633,33 @@ program
       }
     }
 
+    // HC-019n-followup-17: warn when the code-aware steps will run BLIND.
+    //
+    // Auto-detection reads file paths out of `issueBodyForFiles`, which is only
+    // populated on the numeric-GitHub-issue branch above. A roadmap-sourced id
+    // (HC-CI-005, SC-002-followup-2, ...) never enters that branch, so
+    // `codebaseFiles` stays unset and step_1 / step_4 / step_5 / step_5d /
+    // step_5e all run with no source to read — the exact "confidently wrong"
+    // failure HC-019n-followup-12 was built to prevent, still open for roadmap
+    // ids. Observed 2026-08-29: run 61fddfb2 wrote 8,444 chars of code for
+    // HC-CI-005 having never seen the files that story names.
+    //
+    // A fix is structurally awkward: only the CLI can read adopter files, and
+    // only the SERVER knows the roadmap description (server/seeds/master-
+    // roadmap.md is a Hone asset, absent from adopter repos). Closing it needs
+    // the CLI to fetch the resolved description before queueing — a round trip
+    // that belongs in its own story. Until then the gap is at least LOUD
+    // instead of silent, which is the part that actually bit.
+    if (!orchestrateConfig.codebaseFiles) {
+      console.warn('  ⚠ no codebase files bundled — step_1 / step_4 / step_5 / step_5d / step_5e');
+      console.warn('    will run WITHOUT source context and may invent APIs that do not exist.');
+      if (!/^\d+$/.test(storyIdOrRunId)) {
+        console.warn(`    '${storyIdOrRunId}' is not a GitHub issue number, so file paths cannot be`);
+        console.warn('    auto-detected from an issue body.');
+      }
+      console.warn('    Fix: hone run-story <id> --include-paths path/one.js,path/two.js');
+    }
+
     // HC-101-followup-2: pass the adopter's CI gate config to the
     // orchestrator so step_5c can branch (github / local / both / none).
     // Defaults to gate=github + local_command='make ci' when the config
@@ -5264,6 +5678,56 @@ program
       orchestrateConfig.ci_local_command = 'make ci';
     }
 
+    // HC-019n-followup-28: resolve the E2E spec-generation mode (step_3b /
+    // Playwright). Precedence mirrors ci.gate: per-run flag > .pipeline-config.yml
+    // `e2e.spec_generation` > default `auto`. `auto` = the orchestrator runs
+    // step_3b when the story requires an E2E plan (step_0 emitted `yes`); `never`
+    // = step_3b is always skipped. The runtime "is E2E required?" decision stays
+    // server-side (checkE2eRequirement reads step_0's output) — the CLI only
+    // passes the MODE.
+    try {
+      const { readE2eSpecMode } = require('./lib/pipeline-config');
+      let e2eMode, source;
+      if (opts.e2eSpecs) { e2eMode = 'auto'; source = '--e2e-specs'; }
+      else if (opts.skipE2eSpecs) { e2eMode = 'never'; source = '--skip-e2e-specs'; }
+      else { e2eMode = readE2eSpecMode(process.cwd()); source = 'config/default'; }
+      orchestrateConfig.e2e_spec_generation = e2eMode;
+      // Enable step_3b (conditional) unless the adopter opted out. The row is
+      // then created; the orchestrator still skips it at runtime for a story that
+      // does not require an E2E plan (HC-019n-followup-28).
+      if (e2eMode !== 'never') {
+        const ec = new Set(orchestrateConfig.enableConditional || []);
+        ec.add('step_3b');
+        orchestrateConfig.enableConditional = [...ec];
+      }
+      console.log(`  → E2E spec generation (step_3b): ${e2eMode} (source: ${source})`);
+    } catch (e) {
+      const msg = (e && e.message) ? e.message.split('\n')[0] : String(e);
+      console.warn(`  ⚠ e2e spec-mode read failed (non-fatal, defaulting to auto): ${msg}`);
+      orchestrateConfig.e2e_spec_generation = 'auto';
+    }
+
+    // HC-019n-followup-34: thread the closed-loop verification gate mode from
+    // .pipeline-config.yml. Advisory (default) = the server RECORDS verify-patch/
+    // verify-pr verdicts reported via --report; enforce (follow-up) = a red
+    // verdict blocks. Default-safe: never fatal.
+    try {
+      const { readVerificationGateConfig, readVerificationGateSources } = require('./lib/pipeline-config');
+      orchestrateConfig.verification_gate = readVerificationGateConfig(process.cwd());
+      // HC-COMM-011-followup-6: which verdict sources may DRIVE the step_4 gate under
+      // enforce (default ['verify-patch']). An adopter adds 'agent-eval' to let a
+      // green agent-eval verdict auto-advance a prompt change.
+      orchestrateConfig.verification_gate_sources = readVerificationGateSources(process.cwd());
+      if (orchestrateConfig.verification_gate !== 'advisory') {
+        console.log(`  → verification gate: ${orchestrateConfig.verification_gate} (sources: ${orchestrateConfig.verification_gate_sources.join(', ')})`);
+      }
+    } catch (e) {
+      const msg = (e && e.message) ? e.message.split('\n')[0] : String(e);
+      console.warn(`  ⚠ verification-gate read failed (non-fatal, defaulting to advisory): ${msg}`);
+      orchestrateConfig.verification_gate = 'advisory';
+      orchestrateConfig.verification_gate_sources = ['verify-patch'];
+    }
+
     // HC-019b: read per-story architect flags from .github/EXECUTION_PLAN.yml
     // and plumb them into workflow_runs.config. The orchestrator's
     // validateStepPreConditions (server/src/services/workflow-dag.js:340)
@@ -6440,6 +6904,690 @@ showCmd
     }
   });
 
+// ── HC-019n-followup-20: check-patch (pipeline-recovery condition 5) ──────────
+// Fetch step_4's output, extract its diff, and run `git apply --check` against
+// the real tree. The server can only verify the output LOOKS like a diff
+// (patch-validator); only the CLI, running inside the repo, can prove it
+// APPLIES. Run c122c92a produced a diff that passed the server check and failed
+// 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)')
+  .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')
+  .action(async (workflowId, opts) => {
+    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 { gitEnv } = require('./lib/git-env');
+    const config = getConfig();
+    const client = api(config);
+
+    const emit = (obj, humanLine) => {
+      if (opts.format === 'json') console.log(JSON.stringify(obj));
+      else console.log(humanLine);
+    };
+
+    let output;
+    try {
+      const url = `/orchestrate/${workflowId}/step/${opts.stepKey}` +
+        (opts.attempt ? `?attempt=${opts.attempt}` : '');
+      const r = await client.get(url);
+      output = r.data?.output;
+    } catch (e) {
+      const msg = e.response?.data?.error || e.message;
+      emit({ ok: false, reason: 'fetch_failed', detail: msg },
+        `✗ could not fetch ${opts.stepKey} output: ${msg}`);
+      process.exit(1);
+    }
+
+    // HC-019n-followup-23/27: prefer whole-file blocks + region edits
+    // (## Changed Files). git computes the hunks, so the assembled diff applies
+    // by construction — no LLM line-counting. Fall back to the raw-diff path
+    // (followup-20) for stories still on the old ## Patch contract.
+    let diff, source, noChanges;
+    const blocks = extractFileBlocks(output);
+    if (blocks.noChanges) {
+      emit({ ok: true, verdict: 'no_changes' },
+        `○ ${opts.stepKey} declared NO CHANGES — nothing to apply.`);
+      return;
+    }
+    if (blocks.files.length > 0 || (blocks.edits && blocks.edits.length > 0) || blocks.deletes.length > 0) {
+      let built;
+      try {
+        built = buildDiff(blocks, nodeMaterializeIO({ cwd: process.cwd() }));
+      } catch (e) {
+        if (e instanceof MaterializeError) {
+          emit({ ok: false, verdict: 'does_not_apply', reason: e.code, detail: e.message },
+            `✗ region edit could not be applied (${e.code}): ${e.message}`);
+          process.exit(2);
+        }
+        throw e;
+      }
+      diff = built.diff;
+      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.`);
+        return;
+      }
+    } else {
+      // Legacy path: a hand-written ## Patch diff.
+      ({ diff, source, noChanges } = extractDiff(output));
+      if (noChanges) {
+        emit({ ok: true, verdict: 'no_changes' },
+          `○ ${opts.stepKey} declared NO CHANGES — nothing to apply.`);
+        return;
+      }
+      if (!diff) {
+        emit({ ok: false, verdict: 'no_diff', reason: 'no_diff' },
+          `✗ ${opts.stepKey} output contains neither ## Changed Files blocks nor a ` +
+          `unified diff — the agent produced prose. (Placeholder-cascade failure mode.)`);
+        process.exit(1);
+      }
+    }
+
+    // Write to a temp file and run git apply --check against the current repo.
+    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'],
+        });
+      } catch (e) {
+        code = e.status || 1;
+        stderr = (e.stderr || '').toString();
+      }
+      result = interpretApplyCheck({ code, stderr });
+    } finally {
+      try { fs.unlinkSync(tmp); } catch { /* best-effort */ }
+    }
+
+    if (result.applies) {
+      emit({ ok: true, verdict: result.verdict, source, detail: result.detail },
+        `✓ ${opts.stepKey} diff ${result.detail} (${source} block)`);
+    } 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 — ` +
+        `exactly the defect condition 5 catches that condition 4 cannot.`);
+      process.exit(2);  // distinct exit: 2 = does-not-apply, 1 = no-diff/fetch
+    }
+  });
+
+// ── HC-019n-followup-24: verify-patch (pipeline-recovery condition 6) ─────────
+// Apply step_4's diff inside a throwaway git WORKTREE (checked out from HEAD),
+// run the adopter's test command there, report pass/fail. The real tree —
+// including uncommitted work — is never touched. Isolates the TREE, not the
+// process: ci.local_command is the adopter's own command, same trust as running
+// it by hand. Verdict is REPORTED, not yet enforced — the server-gate closed
+// loop is a deliberate follow-up (enabling a gate before its input is proven is
+// the HC-026c mistake).
+program
+  .command('verify-patch <workflowId>')
+  .description('Apply step_4\'s diff in an isolated worktree and run the tests (condition 6)')
+  .option('--step-key <key>', 'Step to verify (default: step_4)', 'step_4')
+  .option('--attempt <n>', 'Specific attempt number (default: latest)')
+  .option('--command <cmd>', 'Test command (default: ci.local_command from config, else `make ci`)')
+  .option('--timeout <sec>', 'Seconds before the test command is killed', '600')
+  .option('--keep', 'Leave the worktree in place for debugging')
+  .option('--report', 'HC-019n-followup-34: report the verdict back to the server (closed loop, advisory)')
+  .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
+  .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 } = require('./lib/verify-patch');
+    const { gitEnv } = require('./lib/git-env');
+    const config = getConfig();
+    const client = api(config);
+
+    const emit = (obj, humanLine) => {
+      if (opts.format === 'json') console.log(JSON.stringify(obj));
+      else console.log(humanLine);
+    };
+
+    // 1. Fetch step_4 output.
+    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;
+      // best-effort: pull the run's ci_local_command for the default
+      try {
+        const runR = await client.get(`/orchestrate/${workflowId}`);
+        runConfig = runR.data?.config || {};
+      } catch { runConfig = {}; }
+    } catch (e) {
+      const msg = e.response?.data?.error || e.message;
+      emit({ ok: false, reason: 'fetch_failed', detail: msg },
+        `✗ could not fetch ${opts.stepKey} output: ${msg}`);
+      process.exit(EXIT.NO_DIFF);
+    }
+
+    // 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;
+    if (blocks.noChanges || !hasWork) {
+      emit({ ok: false, verdict: 'no_diff', reason: 'no_changes_or_diff' },
+        `✗ ${opts.stepKey} produced no file changes to verify.`);
+      process.exit(EXIT.NO_DIFF);
+    }
+    let diff;
+    try {
+      diff = buildDiff(blocks, nodeMaterializeIO({ cwd: process.cwd() })).diff;
+    } catch (e) {
+      if (e instanceof MaterializeError) {
+        emit({ ok: false, verdict: 'does_not_apply', reason: e.code, detail: e.message },
+          `✗ region edit could not be applied (${e.code}): ${e.message}`);
+        process.exit(EXIT.DOES_NOT_APPLY);
+      }
+      throw e;
+    }
+    if (!diff.trim()) {
+      emit({ ok: true, verdict: 'no_changes' },
+        `○ ${opts.stepKey} file blocks matched the tree — nothing to verify.`);
+      return;
+    }
+
+    // 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);
+    let cleanupDone = false;
+    const cleanup = () => {
+      if (cleanupDone || opts.keep) return;
+      cleanupDone = true;
+      try { execFileSync('git', ['worktree', 'remove', '--force', wt], { cwd: process.cwd(), env: gitEnv(), stdio: 'ignore' }); } catch { /* best-effort */ }
+      try { fs.rmSync(wt, { recursive: true, force: true }); } catch { /* best-effort */ }
+      try { fs.unlinkSync(diffFile); } catch { /* best-effort */ }
+    };
+    // Guard against leaving a worktree if the process is interrupted.
+    process.on('SIGINT', () => { cleanup(); process.exit(130); });
+
+    // HC-019n-followup-24 fix: NEVER call process.exit() inside the try — it
+    // skips the finally, so the worktree leaks (found by the live verification:
+    // three hone-verify-* worktrees survived). Compute the exit code, let the
+    // finally clean up, then exit.
+    let exitCode = EXIT.PASS;
+    // HC-019n-followup-34: capture the verdict + HEAD sha for the closed-loop
+    // report (--report). Hoisted so they survive the try/finally to the POST.
+    let reportVerdict = null, reportDetail = null, headSha = null;
+    try { headSha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: process.cwd(), env: gitEnv(), encoding: 'utf8' }).trim(); } catch { /* best-effort */ }
+    try {
+      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).
+      let applied = true, applyDetail = '';
+      try {
+        execFileSync('git', ['-C', wt, 'apply', diffFile], { env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch (e) {
+        applied = false;
+        applyDetail = (e.stderr || '').toString().split('\n').find(Boolean) || 'git apply failed';
+      }
+      if (!applied) {
+        emit({ ok: false, verdict: 'does_not_apply', detail: applyDetail },
+          `✗ diff did not apply in the worktree: ${applyDetail}`);
+        exitCode = EXIT.DOES_NOT_APPLY;
+        reportVerdict = 'does_not_apply'; reportDetail = applyDetail;
+      } else {
+        // 5. Run the adopter's test command in the worktree.
+        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(),
+          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' ? '⏱' : '✗';
+        emit(
+          { ok: v.verdict === 'pass', verdict: v.verdict, command, detail: v.detail },
+          `${sym} ${v.detail}\n  (command: ${command})`);
+        exitCode = v.exitCode;
+        reportVerdict = v.verdict; reportDetail = v.detail;
+      }
+    } catch (e) {
+      emit({ ok: false, verdict: 'error', detail: e.message },
+        `✗ verify-patch failed: ${e.message}`);
+      exitCode = 1;
+      reportVerdict = 'error'; reportDetail = e.message;
+    } finally {
+      cleanup();
+    }
+
+    // HC-019n-followup-34: the closed loop — report the EXECUTED verdict back to
+    // the server (advisory record). Best-effort: a reporting failure must not
+    // change the local exit code (the verdict is already true locally).
+    if (opts.report && reportVerdict) {
+      try {
+        await client.post(`/orchestrate/${workflowId}/verdict`, {
+          source: 'verify-patch',
+          stepKey: opts.stepKey,
+          verdict: reportVerdict,
+          exitCode,
+          detail: reportDetail,
+          attempt: opts.attempt ? Number(opts.attempt) : undefined,
+          headSha,
+        });
+        if (opts.format !== 'json') console.log(`  → reported verdict '${reportVerdict}' to the server (advisory)`);
+      } catch (e) {
+        if (opts.format !== 'json') console.warn(`  ⚠ verdict report failed (non-fatal): ${e.response?.data?.error || e.message}`);
+      }
+    }
+    process.exit(exitCode);
+  });
+
+// ── HC-019n-followup-25: emit-pr (pipeline-recovery condition 7) ──────────────
+// Condition 6 proved step_4's diff applies AND its tests pass in isolation.
+// Condition 7 turns that verified diff into the reviewable artifact: a branch
+// and (opt-in) a draft PR. Publishing is staged — tier-1 dry run by default;
+// --push, then --open-pr. Sibling to check-patch/verify-patch (top-level).
+program
+  .command('emit-pr <workflowId>')
+  .description('Emit a branch + draft PR from step_4\'s verified diff (condition 7)')
+  .option('--step-key <key>', 'Step to emit (default: step_4)', 'step_4')
+  .option('--attempt <n>', 'Specific attempt number (default: latest)')
+  .option('--branch <name>', 'Override the generated branch name')
+  .option('--base <ref>', 'Target base branch for the PR (default: repo default)')
+  .option('--push', 'Push the branch to origin (default: local dry run only)')
+  .option('--open-pr', 'Open a draft PR (implies --push)')
+  .option('--ready', 'Open the PR ready-for-review instead of draft')
+  .option('--skip-verify', 'Do not re-run the tests before committing (downgrades provenance)')
+  .option('--command <cmd>', 'Test command for --verify (default: ci.local_command, else `make ci`)')
+  .option('--timeout <sec>', 'Seconds before the verify test command is killed', '600')
+  .option('--keep', 'Leave the worktree in place for debugging')
+  .option('--format <fmt>', 'Output format: pretty or json', 'pretty')
+  .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 {
+      EXIT, buildBranchName, buildCommitMessage, buildPrBody, decidePublish,
+    } = require('./lib/emit-pr');
+    const { gitEnv } = require('./lib/git-env');
+    const config = getConfig();
+    const client = api(config);
+
+    // --open-pr implies --push (cannot open a PR against an unpushed branch).
+    const doPush = Boolean(opts.push || opts.openPr);
+    const doOpenPr = Boolean(opts.openPr);
+    const doVerify = !opts.skipVerify;
+
+    const emit = (obj, humanLine) => {
+      if (opts.format === 'json') console.log(JSON.stringify(obj));
+      else if (humanLine != null) console.log(humanLine);
+    };
+
+    // 1. Fetch step_4 output + the run's storyId (for naming/provenance).
+    let output, storyId = 'story', runConfig = {};
+    try {
+      const url = `/orchestrate/${workflowId}/step/${opts.stepKey}` +
+        (opts.attempt ? `?attempt=${opts.attempt}` : '');
+      const r = await client.get(url);
+      output = r.data?.output;
+      try {
+        const runR = await client.get(`/orchestrate/${workflowId}`);
+        storyId = runR.data?.storyId || runR.data?.story_id || 'story';
+        runConfig = runR.data?.config || {};
+      } catch { /* naming falls back to 'story'; command falls back to make ci */ }
+    } catch (e) {
+      const msg = e.response?.data?.error || e.message;
+      emit({ ok: false, reason: 'fetch_failed', detail: msg },
+        `✗ could not fetch ${opts.stepKey} output: ${msg}`);
+      process.exit(EXIT.NO_DIFF);
+    }
+
+    // 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;
+    if (blocks.noChanges || !hasWork) {
+      emit({ ok: false, verdict: 'no_diff', reason: 'no_changes_or_diff' },
+        `✗ ${opts.stepKey} produced no file changes to emit.`);
+      process.exit(EXIT.NO_DIFF);
+    }
+    let diff;
+    try {
+      diff = buildDiff(blocks, nodeMaterializeIO({ cwd: process.cwd() })).diff;
+    } catch (e) {
+      if (e instanceof MaterializeError) {
+        emit({ ok: false, verdict: 'does_not_apply', reason: e.code, detail: e.message },
+          `✗ region edit could not be applied (${e.code}): ${e.message}`);
+        process.exit(EXIT.DOES_NOT_APPLY);
+      }
+      throw e;
+    }
+    if (!diff.trim()) {
+      emit({ ok: true, verdict: 'no_changes' },
+        `○ ${opts.stepKey} file blocks matched the tree — nothing to emit.`);
+      return;
+    }
+
+    // 3. Resolve names + probe idempotency BEFORE any mutation.
+    let headSha = '';
+    try {
+      headSha = execFileSync('git', ['rev-parse', 'HEAD'],
+        { cwd: process.cwd(), env: gitEnv(), encoding: 'utf8' }).trim();
+    } catch {
+      emit({ ok: false, reason: 'no_head' }, '✗ repository has no HEAD commit — cannot branch from nothing.');
+      process.exit(1);
+    }
+    const branch = buildBranchName({ storyId, workflowId, override: opts.branch });
+
+    const branchExists = (() => {
+      try {
+        execFileSync('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`],
+          { cwd: process.cwd(), env: gitEnv(), stdio: 'ignore' });
+        return true;
+      } catch { return false; }
+    })();
+    // Only probe the remote for an existing PR when we intend to publish.
+    let openPrUrl = null;
+    if (doOpenPr) {
+      try {
+        const out = execFileSync('gh', ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'url', '--jq', '.[0].url'],
+          { cwd: process.cwd(), env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        openPrUrl = out || null;
+      } catch { openPrUrl = null; /* gh missing/unauthed handled at push/open time */ }
+    }
+    const decision = decidePublish({ branchExists, openPrUrl });
+    if (decision.action === 'already_open') {
+      emit({ ok: true, verdict: 'already_open', prUrl: decision.prUrl, branch },
+        `✓ a draft PR is already open for ${branch}: ${decision.prUrl}`);
+      process.exit(EXIT.PASS);
+    }
+    if (decision.action === 'branch_conflict') {
+      emit({ ok: false, verdict: 'branch_conflict', branch },
+        `✗ branch '${branch}' already exists — not overwriting. Use --branch to pick another name.`);
+      process.exit(EXIT.BRANCH_CONFLICT);
+    }
+
+    // 4. Isolated worktree with a NAMED branch off HEAD (adopter tree untouched).
+    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);
+    // `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
+    // reaches a branch" would be false and a re-run would hit a bogus conflict.
+    // `committed` gates it: once we have the deliverable commit, keep the branch.
+    let cleanupDone = false;
+    let committed = false;
+    const cleanup = () => {
+      if (cleanupDone || opts.keep) return;
+      cleanupDone = true;
+      try { execFileSync('git', ['worktree', 'remove', '--force', wt], { cwd: process.cwd(), env: gitEnv(), stdio: 'ignore' }); } catch { /* best-effort */ }
+      // Remove the leaked empty branch only when nothing was committed onto it.
+      if (!committed) {
+        try { execFileSync('git', ['branch', '-D', branch], { cwd: process.cwd(), env: gitEnv(), stdio: 'ignore' }); } catch { /* best-effort */ }
+      }
+      try { fs.rmSync(wt, { recursive: true, force: true }); } catch { /* best-effort */ }
+      try { fs.unlinkSync(diffFile); } catch { /* best-effort */ }
+    };
+    process.on('SIGINT', () => { cleanup(); process.exit(130); });
+
+    // HC-019n-followup-24 lesson: NEVER process.exit() inside the try — it skips
+    // the finally and leaks the worktree. Capture exitCode; exit after cleanup.
+    let exitCode = EXIT.PASS;
+    let verifyState = 'skipped';
+    try {
+      execFileSync('git', ['worktree', 'add', '-b', branch, wt, 'HEAD'],
+        { cwd: process.cwd(), env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+
+      // 4a. Apply the diff INTO the worktree.
+      let applied = true, applyDetail = '';
+      try {
+        execFileSync('git', ['-C', wt, 'apply', diffFile], { env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch (e) {
+        applied = false;
+        applyDetail = (e.stderr || '').toString().split('\n').find(Boolean) || 'git apply failed';
+      }
+      if (!applied) {
+        emit({ ok: false, verdict: 'does_not_apply', detail: applyDetail },
+          `✗ diff did not apply in the worktree: ${applyDetail}`);
+        exitCode = EXIT.DOES_NOT_APPLY;
+      } else {
+        // 4b. Re-verify inline (default) — a failing diff never reaches a branch.
+        let verifyOk = true;
+        if (doVerify) {
+          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(),
+            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 });
+          if (v.verdict === 'pass') {
+            verifyState = 'pass';
+          } else {
+            verifyOk = false;
+            const sym = 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
+          }
+        }
+
+        if (verifyOk) {
+          // 4c. Commit the applied diff onto the branch, inside the worktree.
+          // No summary source (GET /orchestrate omits config/story text), so the
+          // commit subject falls back to the storyId + default in buildCommitMessage.
+          const message = buildCommitMessage({ storyId, summary: '', workflowId, headSha, verifyState });
+          const msgFile = path.join(os.tmpdir(), `hone-emit-msg-${Date.now()}.txt`);
+          fs.writeFileSync(msgFile, message);
+          try {
+            execFileSync('git', ['-C', wt, 'add', '-A'], { env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+            execFileSync('git', ['-C', wt, 'commit', '-F', msgFile], { env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+            committed = true; // the branch now holds the deliverable — keep it past cleanup
+          } finally { try { fs.unlinkSync(msgFile); } catch { /* best-effort */ } }
+
+          const stat = (() => {
+            try {
+              return execFileSync('git', ['-C', wt, 'show', '--stat', '--oneline', 'HEAD'],
+                { env: gitEnv(), encoding: 'utf8' }).trim();
+            } catch { return ''; }
+          })();
+
+          // ── Boundary: everything above is local + reversible. ──
+          let prUrl = null, pushed = false;
+          if (doPush) {
+            try {
+              execFileSync('git', ['push', '-u', 'origin', branch],
+                { cwd: process.cwd(), env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+              pushed = true;
+            } catch (e) {
+              const detail = (e.stderr || e.message || '').toString().split('\n').find(Boolean) || 'push failed';
+              emit({ ok: false, verdict: 'publish_failed', stage: 'push', detail, branch },
+                `✗ push failed (branch committed locally as '${branch}', not published): ${detail}`);
+              exitCode = EXIT.PUBLISH_FAILED;
+            }
+          }
+          if (pushed && doOpenPr) {
+            const prBody = buildPrBody({ storyId, workflowId, headSha, verifyState, command: doVerify ? command : undefined });
+            const bodyFile = path.join(os.tmpdir(), `hone-emit-prbody-${Date.now()}.md`);
+            fs.writeFileSync(bodyFile, prBody);
+            const title = `${storyId}: Hone step_4 change (workflow ${String(workflowId).slice(0, 8)})`;
+            const ghArgs = ['pr', 'create', '--head', branch, '--title', title, '--body-file', bodyFile];
+            if (!opts.ready) ghArgs.push('--draft');
+            if (opts.base) ghArgs.push('--base', opts.base);
+            try {
+              prUrl = execFileSync('gh', ghArgs,
+                { cwd: process.cwd(), env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            } catch (e) {
+              const detail = (e.stderr || e.message || '').toString().split('\n').find(Boolean) || 'gh pr create failed';
+              emit({ ok: false, verdict: 'publish_failed', stage: 'open_pr', detail, branch },
+                `✗ branch pushed, but opening the PR failed: ${detail}\n  → open it manually, or check \`gh auth status\`.`);
+              exitCode = EXIT.PUBLISH_FAILED;
+            } finally { try { fs.unlinkSync(bodyFile); } catch { /* best-effort */ } }
+          }
+
+          if (exitCode === EXIT.PASS) {
+            const tier = prUrl ? 'pr' : pushed ? 'pushed' : 'dry_run';
+            const human = prUrl
+              ? `✓ draft PR opened: ${prUrl}`
+              : pushed
+                ? `✓ branch pushed to origin/${branch}\n  → open a PR: gh pr create --head ${branch} --draft`
+                : `✓ branch '${branch}' built locally (dry run — nothing pushed)\n` +
+                  `  verify: ${verifyState}\n\n${stat}\n\n` +
+                  `  → push it:      hone emit-pr ${workflowId} --push\n` +
+                  `  → push + PR:    hone emit-pr ${workflowId} --open-pr\n` +
+                  `  → discard it:   git branch -D ${branch}`;
+            emit({ ok: true, verdict: tier, branch, verifyState, prUrl, pushed, headSha }, human);
+          }
+        }
+      }
+    } catch (e) {
+      emit({ ok: false, verdict: 'error', detail: e.message }, `✗ emit-pr failed: ${e.message}`);
+      exitCode = 1;
+    } finally {
+      cleanup();
+    }
+    process.exit(exitCode);
+  });
+
+// ── HC-019n-followup-32: verify-pr (pipeline-standards G4 §2, G3 functional) ────
+// The post-emit-pr step: once a REAL PR exists, run the real skill audit
+// (`hone step-5b`) + the real CI gate (`gh pr checks` / `make ci`), writing the
+// two artifacts (step-5b-skill-audit.md, step-5c-ci.md) the server DAG can only
+// MODEL, never execute (those steps are serverExecutable:false). VERIFY + REPORT
+// only — no auto-fix loop; the operator (or a later closed loop) acts on the
+// verdict. Sibling to check-patch → verify-patch → emit-pr → verify-pr.
+program
+  .command('verify-pr <prOrBranch>')
+  .description('Post-PR verification: real skill audit (hone step-5b) + real CI gate (gh pr checks / make ci) (HC-019n-followup-32)')
+  .option('--story-id <id>', 'override story id (defaults to extraction from the branch)')
+  .option('--base <branch>', 'base branch for the skill-audit diff', 'develop')
+  .option('--mode <mode>', 'CI gate mode: github | local | both | none (default: ci.gate config, else github)')
+  .option('--command <cmd>', 'local CI command (default: ci.local_command, else make ci)')
+  .option('--timeout <sec>', 'seconds before the local CI command is killed', '900')
+  .option('--skip-skill-audit', 'skip the hone step-5b skill audit')
+  .option('--report', 'HC-019n-followup-36: report the CI-gate verdict back to the server (closed loop, records step_5c)')
+  .option('--workflow-id <id>', 'the run id to report the verdict against (required with --report)')
+  .option('--format <fmt>', 'pretty or json', 'pretty')
+  .action(async (prOrBranch, opts) => {
+    const { execFileSync, spawnSync } = require('child_process');
+    const { readCIGateConfig } = require('./lib/pipeline-config');
+    const { extractStoryIdFromBranch } = require('./lib/pipeline-status');
+    const { EXIT, resolveGateMode, interpretGhChecks, ciGateVerdict, renderStep5cArtifact } = require('./lib/verify-pr');
+    const { gitEnv } = require('./lib/git-env');
+    const repoRoot = process.cwd();
+    const emit = (obj, human) => {
+      if (opts.format === 'json') console.log(JSON.stringify(obj));
+      else if (human != null) console.log(human);
+    };
+
+    // 1. Story id: flag > branch > the ref itself.
+    let branch = '';
+    try { branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { /* */ }
+    const storyId = opts.storyId || extractStoryIdFromBranch(branch) || extractStoryIdFromBranch(prOrBranch) || 'unknown-story';
+
+    // 2. CI gate mode: --mode > ci.gate config > github.
+    let configGate = 'github';
+    try { configGate = readCIGateConfig(repoRoot).gate; } catch { /* default */ }
+    const mode = resolveGateMode(opts.mode, configGate);
+
+    // 3. Skill audit — reuse the working `hone step-5b` command (deterministic
+    //    SA-001 engine over the PR diff). Informational; never affects the exit.
+    let skillAudit = { ran: false };
+    if (!opts.skipSkillAudit) {
+      try {
+        execFileSync(process.execPath, [__filename, 'step-5b', '--story-id', storyId, '--base', opts.base],
+          { cwd: repoRoot, env: process.env, stdio: opts.format === 'json' ? 'ignore' : 'inherit' });
+        skillAudit = { ran: true, artifact: `.github/pipeline/${storyId}/step-5b-skill-audit.md` };
+      } catch (e) {
+        skillAudit = { ran: true, error: (e.message || '').split('\n')[0] };
+      }
+    }
+
+    // 4. CI gate.
+    let gh = null, local = null;
+    if (mode === 'github' || mode === 'both') {
+      let prNum = /^\d+$/.test(prOrBranch) ? prOrBranch : null;
+      if (!prNum) { const m = String(prOrBranch).match(/\/pull\/(\d+)/); if (m) prNum = m[1]; }
+      if (!prNum) {
+        try { prNum = execFileSync('gh', ['pr', 'list', '--head', prOrBranch, '--state', 'all', '--json', 'number', '--jq', '.[0].number'], { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null; } catch { prNum = null; }
+      }
+      if (!prNum) {
+        emit({ ok: false, reason: 'no_pr', ref: prOrBranch },
+          `✗ could not resolve a PR for '${prOrBranch}' — github mode needs a PR number, URL, or a branch with a PR.`);
+        process.exit(EXIT.NO_PR);
+      }
+      // gh pr checks exits non-zero when checks fail/pend, but still prints JSON.
+      let raw = '';
+      try {
+        raw = execFileSync('gh', ['pr', 'checks', prNum, '--json', 'name,state,bucket'], { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch (e) { raw = (e.stdout || '').toString(); }
+      try { gh = interpretGhChecks(JSON.parse(raw)); } catch { gh = null; }
+    }
+    if (mode === 'local' || mode === 'both') {
+      let command = (opts.command && opts.command.trim()) || '';
+      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'] });
+      local = { code: run.status == null ? 1 : run.status, timedOut: !!(run.error && run.error.code === 'ETIMEDOUT') };
+    }
+
+    const verdict = ciGateVerdict({ mode, gh, local });
+
+    // 5. Write the real step-5c-ci.md artifact.
+    try {
+      const dir = path.join(repoRoot, '.github/pipeline', storyId);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, 'step-5c-ci.md'), renderStep5cArtifact({ storyId, mode, prRef: prOrBranch, gh, local, verdict }));
+    } catch { /* best-effort */ }
+
+    // 6. Closed loop (HC-019n-followup-36): report the CI-gate verdict to the
+    // server. This RECORDS against step_5c — which is a post-PR, CLI-produced
+    // node (serverExecutable:false), so there is no server gate to auto-approve:
+    // verify-pr's verdict is ADVISORY audit even in enforce mode (enforce gates
+    // step_4, the build). Best-effort — never changes the local exit code.
+    let reported = false;
+    if (opts.report) {
+      if (!opts.workflowId) {
+        if (opts.format !== 'json') console.warn('  ⚠ --report needs --workflow-id <run id> to address the run; skipping report.');
+      } else {
+        try {
+          const client = api(getConfig());
+          await client.post(`/orchestrate/${opts.workflowId}/verdict`, {
+            source: 'verify-pr',
+            stepKey: 'step_5c',
+            verdict: verdict.verdict,
+            exitCode: verdict.exitCode,
+            detail: verdict.detail,
+          });
+          reported = true;
+          if (opts.format !== 'json') console.log(`  → reported CI-gate verdict '${verdict.verdict}' to run ${opts.workflowId} (advisory)`);
+        } catch (e) {
+          if (opts.format !== 'json') console.warn(`  ⚠ verdict report failed (non-fatal): ${e.response?.data?.error || e.message}`);
+        }
+      }
+    }
+
+    // 7. Report. The exit code is the CI verdict's; the skill audit is advisory.
+    const sym = (verdict.verdict === 'pass' || verdict.verdict === 'disabled') ? '✓' : verdict.verdict === 'pending' ? '⏳' : '✗';
+    emit(
+      { ok: verdict.exitCode === EXIT.PASS, storyId, mode, skillAudit, ciGate: verdict, gh, local, reported },
+      `${sym} CI gate (${mode}): ${verdict.verdict} — ${verdict.detail}\n` +
+      `  skill audit: ${opts.skipSkillAudit ? 'skipped' : (skillAudit.artifact || skillAudit.error || 'done')}\n` +
+      `  → .github/pipeline/${storyId}/step-5c-ci.md`);
+    process.exit(verdict.exitCode);
+  });
+
 // ── CLI setup ─────────────────────────────────────────────────────────────────
 program
   .name('hone')