@hone-ai/cli 1.35.1 → 1.37.0

package/hone-cli.js

@@ -42,6 +42,14 @@ const { collectIncludePaths } = require('./lib/include-paths');
 const { runArgsError, orchestratePath } = require('./lib/run-target'); // HC-GF-270-followup-1
 const program = new Command();
 
+// HC-GF-331: spawnSync's default stdout/stderr buffer is 1 MiB. A verification suite over that
+// (this repo's own `make ci`) overflowed it, spawnSync returned status: null with error.code
+// ENOBUFS, and verdictFromRun/classifyGateRun read that null status as a plain test failure —
+// not as "the output could not be captured." Generous relative to any suite measured so far
+// (`make ci` prints low hundreds of KB; 64 MiB is two orders of magnitude of headroom) without
+// holding an unbounded amount of memory for a runaway command.
+const VERIFY_MAX_BUFFER = 64 * 1024 * 1024;
+
 // ── Config resolution ─────────────────────────────────────────────────────────
 const RC_PATH = path.join(os.homedir(), '.honerc');
 
@@ -377,7 +385,7 @@ program
             verdict: anyFailed ? 'fail' : 'pass',
             exitCode: anyFailed ? 1 : 0,
             detail: `agent-eval ${opts.category}: ${results.filter((r) => r.passed).length}/${results.length} probes passed`,
-          });
+          }, require('./lib/fresh-connection').freshConnection());
           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}`);
@@ -928,6 +936,9 @@ program
     if (ciGateChoice.source !== 'auto-detect') {
       setupEnv.CI_GATE = ciGateChoice.mode;
     }
+    // HC-GF-321: --stack was declared and never read. The script applies it
+    // after detection (apply_stack_override) and refuses an unsupported value.
+    if (opts.stack) setupEnv.HONE_STACK_OVERRIDE = String(opts.stack).toLowerCase();
     try {
       execSync(`bash "${scriptPath}" ${flags}`, {
         stdio: 'inherit',
@@ -939,6 +950,25 @@ program
       process.exit(1);
     }
 
+    // HC-GF-320: every phase below writes (CLAUDE.md, config grounding, test
+    // packages, GitHub branch protection). A dry run stops here and says what
+    // they would do.
+    if (opts.dryRun) {
+      const { postScriptDryRunPlan } = require('./lib/setup-dry-run');
+      const plan = postScriptDryRunPlan({
+        claudeMdTemplate: fs.existsSync(path.join(tmpDir, 'CLAUDE.md')),
+        claudeMdExists: fs.existsSync(path.join(process.cwd(), 'CLAUDE.md')),
+        configExists: fs.existsSync(path.join(process.cwd(), '.github', '.pipeline-config.yml')),
+        installTests: !!opts.installTests,
+        skipBranchProtection: opts.branchProtection === false ||
+          /^(1|true|yes)$/i.test(process.env.HONE_SKIP_BRANCH_PROTECTION || ''),
+      });
+      for (const line of plan) console.log(`  DRY-RUN: ${line}`);
+      console.log('  Dry run complete: nothing was written.');
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+      return;
+    }
+
     // HC-RC-004: if the adopter chose `local`, run the setup-local-ci
     // scaffold inline so they end the setup command with a working
     // local-CI stack (Makefile + compose) instead of having to know
@@ -1564,6 +1594,10 @@ async function createTestEnv(repoRoot, opts) {
 function recommendTestFramework(repoRoot) {
   const detected = detectExistingTestFramework(repoRoot);
   if (detected.testFw) return; // Already has tests — no recommendation needed
+  // HC-GF-321: every recommendation below is an npm package. Without a root
+  // package.json the stack is not Node (or lives in subdirectories), and a
+  // pytest repository was told to install vitest.
+  if (detected.stack === 'unknown') return;
 
   const pkgs = getInstallPackages(detected.stack);
   const installCmd = detected.pkgMgr === 'yarn' ? 'yarn add -D' : detected.pkgMgr === 'pnpm' ? 'pnpm add -D' : 'npm install -D';
@@ -6139,6 +6173,8 @@ program
   .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) 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('--reject <step>', 'HC-GF-323: send a paused gate BACK for a re-run instead of approving it or killing the whole run (e.g., --reject step_4). Requires --reason. Steps before it are left approved; only this step re-runs, with the reason in its context.')
+  .option('--reason <text>', 'With --reject: why this attempt is being sent back. Required, and reaches the re-run as feedback the same way a code-reviewer\'s FAIL verdict does.')
   .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')
@@ -6167,12 +6203,7 @@ program
     // the 2026-09-08 editor test nearly meaningless; here it costs money rather than time.
     try {
       const h = await client.get('/health').then(r => r.data).catch(() => null);
-      const llm = (h && h.llm) || null;
-      if (llm && llm.local) {
-        console.log(`LOCAL  ${config.apiUrl} · provider claude_cli · no paid fallback · this run costs $0.00`);
-      } else {
-        console.log(`PROD   ${config.apiUrl} · provider ${llm ? llm.primary : 'unknown'} · THIS RUN COSTS MONEY`);
-      }
+      console.log(require('./lib/server-banner').serverBanner(config.apiUrl, h));
     } catch { /* never block a run on a banner */ }
 
     const { resolveRunTarget, isRunId } = require('./lib/run-target');
@@ -6458,6 +6489,7 @@ program
           console.log('');
           console.log(`Awaiting approval at ${data.currentStep}.`);
           console.log(`Approve: hone run-story ${data.runId} --approve ${data.currentStep}`);
+          console.log(`Reject:  hone run-story ${data.runId} --reject ${data.currentStep} --reason "<why>"`);
         }
         console.log('');
         // HC-GF-016: at a TERMINAL state, print the report unasked. The whole
@@ -6527,6 +6559,37 @@ program
       return;
     }
 
+    // Reject mode (HC-GF-323)
+    if (opts.reject) {
+      if (!opts.reason || !String(opts.reason).trim()) {
+        console.error('--reject requires --reason <text>');
+        process.exit(1);
+      }
+      let rejectId;
+      try {
+        rejectId = await existingRunId(`--reject ${opts.reject}`);
+        await client.post(orchestratePath([rejectId, 'reject']),
+          { stepKey: opts.reject, reason: opts.reason });
+        console.log(`Gate ${opts.reject} rejected. Re-running with the reason. Workflow resuming.`);
+      } catch (e) {
+        console.error(`Failed: ${e.response?.data?.error || e.message}`);
+        process.exit(1);
+      }
+      // HC-GF-070: same FOLLOW behaviour as --approve — a caller told to poll does not.
+      if (opts.follow === false) {
+        console.log(`Poll: hone run-story ${rejectId} --status`);
+        return;
+      }
+      try {
+        await pollUntilDecision(rejectId);
+      } catch (e) {
+        console.error(`Rejected, but following the run failed: ${e.message}`);
+        console.error(`Poll: hone run-story ${rejectId} --status`);
+        process.exit(1);
+      }
+      return;
+    }
+
     // Start workflow (storyId required, runId not accepted for starting)
     if (isUuid) {
       console.error('Cannot start workflow with a runId. Use a story ID like HC-042.');
@@ -7860,7 +7923,11 @@ program
       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(orchestratePath([workflowId]));
+        // HC-GF-302-followup-1: on a connection of its own. This GET follows the step GET at once, and
+        // on the socket that one pooled a server closing it idle resets the request - a failed config
+        // read, so the provenance gate below refused a trusted run (exit 9). Nothing is retried: a read
+        // that fails on its own connection still refuses.
+        const runR = await client.get(orchestratePath([workflowId]), require('./lib/fresh-connection').freshConnection());
         // HC-GF-270 (security review BLOCKER-1): the id is ENCODED above, so a crafted
         // `<uuid>/step/step_4?` cannot turn this into a fetch of some other endpoint that answers
         // 200 with no config. And a body that is not THIS run is not this run's config.
@@ -8164,9 +8231,10 @@ program
           cwd: wt, shell: true, encoding: 'utf8',
           timeout: timeoutMs, env: verifyCommandEnv(gitEnv()),
           stdio: ['ignore', 'pipe', 'pipe'],
+          maxBuffer: VERIFY_MAX_BUFFER, // HC-GF-331: a >1 MiB suite (this repo's own `make ci`) must not ENOBUFS
         });
         const timedOut = run.error && run.error.code === 'ETIMEDOUT';
-        const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr, command, source: commandSource, replaced: commandReplaced }, provAll);
+        const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr, command, source: commandSource, replaced: commandReplaced, error: run.error }, provAll);
         // 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 === 'pass_narrowed' ? '⚠' : v.verdict === 'timeout' ? '⏱' : v.verdict === 'unresolved' ? '○' : '✗';
@@ -8222,6 +8290,7 @@ program
               cwd: wt, shell: true, encoding: 'utf8',
               timeout: timeoutMs, env: verifyCommandEnv(gitEnv()),
               stdio: ['ignore', 'pipe', 'pipe'],
+              maxBuffer: VERIFY_MAX_BUFFER, // HC-GF-331: shares the shape at :8184 — same fix
             });
             const c = classifyGateRun({
               code: gr.status, error: gr.error,
@@ -8286,7 +8355,7 @@ program
           attempt: opts.attempt ? Number(opts.attempt) : verifiedAttempt,
           headSha,
           gates: reportGates.length ? reportGates : undefined,
-        });
+        }, require('./lib/fresh-connection').freshConnection());
         if (opts.format !== 'json') {
           // HC-GF-070: name the gate that is actually configured. This said "(advisory)"
           // unconditionally, and printed it on a run where `enforce` was auto-approving
@@ -8451,12 +8520,26 @@ program
     const { resolveCommandDetailed, verdictFromRun, verifyCommandEnv } = require('./lib/verify-patch');
     const { verifyStateFor } = require('./lib/emit-pr');
     const {
-      EXIT, buildBranchName, buildCommitMessage, buildPrBody, decidePublish,
+      EXIT, buildBranchName, buildCommitMessage, buildPrBody, decidePublish, recordPr,
     } = require('./lib/emit-pr');
     const { gitEnv } = require('./lib/git-env');
     const config = getConfig();
     const client = api(config);
     const sameRun = (id) => String(id).toLowerCase() === String(workflowId).toLowerCase();
+    // HC-GF-302: record the PR on the run. The POST goes out after the verify, push and `gh` steps,
+    // which block the event loop for minutes, and a keep-alive socket the server closed meanwhile
+    // fails `write EPIPE` when reused (HC-GF-326). A fresh connection per record avoids that.
+    //
+    // F3 (review): baseSha and attempt are the CALLER's to supply, not this closure's defaults —
+    // the two call sites below have different bases for trusting each one (see their own
+    // comments). recordPr itself stays pure; this only wires up the transport.
+    const recordPrOnRun = ({ prUrl, branch: prBranch, baseSha: recBaseSha = null, attempt: recAttempt }) => recordPr({
+      post: (p, body) => client.post(p, body, require('./lib/fresh-connection').freshConnection()),
+      path: orchestratePath([workflowId, 'pr-record']),
+      prUrl, branch: prBranch, baseSha: recBaseSha, attempt: recAttempt,
+    });
+    const recordWarning = (rec) => (rec.recorded || opts.format === 'json'
+      ? '' : `\n  ⚠ the run's PR record was not saved (non-fatal; the morning report may miss this link): ${rec.reason}`);
 
     // --open-pr implies --push (cannot open a PR against an unpushed branch).
     const doPush = Boolean(opts.push || opts.openPr);
@@ -8477,14 +8560,19 @@ program
     // branch naming, and 'story' is not all digits — so assessing it would trust a run whose id
     // never arrived.
     let runStoryId = null;
+    // HC-GF-302: the attempt the server resolved (the latest one unless --attempt named it), which
+    // orders this run's PR records. Not opts.attempt: that is absent in the default case.
+    let stepAttempt = null;
     try {
       const url = orchestratePath([workflowId, 'step', opts.stepKey], { attempt: opts.attempt });
       const r = await client.get(url);
       // The step output must be THIS run's: nothing else ties the patch to the config assessed below.
       if (r.data?.runId && !sameRun(r.data.runId)) throw new Error(`the server returned ${opts.stepKey} for a different run`);
       output = r.data?.output;
+      stepAttempt = Number.isInteger(r.data?.attempt) ? r.data.attempt : null;
       try {
-        const runR = await client.get(orchestratePath([workflowId]));
+        // HC-GF-302-followup-1: its own connection, as verify-patch's (see there).
+        const runR = await client.get(orchestratePath([workflowId]), require('./lib/fresh-connection').freshConnection());
         // HC-GF-270 (security review BLOCKER-1): see verify-patch — encoded id, and a body that
         // is not THIS run does not count as its config.
         if (runR.data?.runId && !sameRun(runR.data.runId)) throw new Error('run id mismatch');
@@ -8587,8 +8675,24 @@ program
     }
     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}`);
+      // HC-GF-302 (review F3): record here too — hone follow-batch sends a completed run's emit
+      // to the branch its draft already opened, so this is the path that retries a record the
+      // draft failed to save. But this path never verified anything against a specific attempt:
+      // it found an already-open PR without running check-patch/verify-patch here, so it has no
+      // basis to claim `headSha` is this attempt's base — baseSha is always null on this path.
+      // And `stepAttempt` above is whichever attempt the server considers LATEST, which is not
+      // necessarily the attempt the open PR's branch was built from — so this only records when
+      // the caller named the attempt explicitly with --attempt. `hone follow-batch` always does
+      // (cli/lib/batch-follow.js buildArgs pushes `--attempt N` for every emit-pr call it makes);
+      // a bare `hone emit-pr --open-pr` with no --attempt has no basis to order a record either,
+      // so it records nothing rather than guessing.
+      const explicitAttempt = opts.attempt !== undefined ? Number(opts.attempt) : null;
+      const rec = explicitAttempt != null
+        ? await recordPrOnRun({ prUrl: decision.prUrl, branch, baseSha: null, attempt: explicitAttempt })
+        : { recorded: false, reason: 'the open PR\'s attempt is unknown; pass --attempt' };
+      emit({ ok: true, verdict: 'already_open', prUrl: decision.prUrl, branch, recorded: rec.recorded,
+        ...(rec.recorded ? {} : { recordError: rec.reason }) },
+        `✓ a draft PR is already open for ${branch}: ${decision.prUrl}${recordWarning(rec)}`);
       process.exit(EXIT.PASS);
     }
     if (decision.action === 'branch_conflict') {
@@ -8683,9 +8787,10 @@ program
             cwd: wt, shell: true, encoding: 'utf8',
             timeout: timeoutMs, env: verifyCommandEnv(gitEnv()),
             stdio: ['ignore', 'pipe', 'pipe'],
+            maxBuffer: VERIFY_MAX_BUFFER, // HC-GF-331: emit-pr's verify shares verify-patch's spawnSync shape
           });
           const timedOut = run.error && run.error.code === 'ETIMEDOUT';
-          const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr, command, source: commandSource, replaced: commandReplaced }, provAll);
+          const v = verdictFromRun({ code: run.status, timedOut, stdout: run.stdout, stderr: run.stderr, command, source: commandSource, replaced: commandReplaced, error: run.error }, provAll);
           // HC-GF-223: the mapping lives in cli/lib/emit-pr.js so it is testable. Before it, a
           // narrowed verdict fell into the else below, which printed "verify failed, no branch
           // emitted" and then exited with that verdict's own exit code — zero. A failure path that
@@ -8761,8 +8866,13 @@ program
 
           if (exitCode === EXIT.PASS) {
             const tier = prUrl ? 'pr' : pushed ? 'pushed' : 'dry_run';
+            // HC-GF-302: only a PR is recorded; a pushed or local branch has no link to show. This
+            // is the path that just verified the diff and committed it: headSha is the commit the
+            // patch was verified against, so it is a true baseSha here (unlike the already_open
+            // path above, which never ran that verification and always records baseSha: null).
+            const rec = prUrl ? await recordPrOnRun({ prUrl, branch, baseSha: headSha || null, attempt: stepAttempt }) : null;
             const human = prUrl
-              ? `✓ draft PR opened: ${prUrl}`
+              ? `✓ draft PR opened: ${prUrl}${recordWarning(rec)}`
               : 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` +
@@ -8770,7 +8880,11 @@ program
                   `  → 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);
+            // F8 (review): --format json previously dropped the failure reason entirely once
+            // `recorded` was false — a reader had no way to tell why without re-running in
+            // --format pretty. Same object, one extra field, omitted once recorded:true.
+            emit({ ok: true, verdict: tier, branch, verifyState, prUrl, pushed, headSha,
+              ...(rec ? { recorded: rec.recorded, ...(rec.recorded ? {} : { recordError: rec.reason }) } : {}) }, human);
           }
         }
       }
@@ -8912,7 +9026,7 @@ program
             verdict: verdict.verdict,
             exitCode: verdict.exitCode,
             detail: verdict.detail,
-          });
+          }, require('./lib/fresh-connection').freshConnection());
           reported = true;
           if (opts.format !== 'json') console.log(`  → reported CI-gate verdict '${verdict.verdict}' to run ${opts.workflowId} (advisory)`);
         } catch (e) {

package/lib/bundle-mount-follow.js

@@ -0,0 +1,118 @@
+'use strict';
+/**
+ * bundle-mount-follow.js — HC-GF-325.
+ *
+ * `cli/lib/bundle-paths.js` bundles only paths the story NAMES — it has no mount, prefix or
+ * import following. step_2 (API test writer) then has no way to know a router file's routes are
+ * served under a prefix, because nothing in the bundle says so. Measured live: step_2 wrote 7
+ * tests against `/properties` for an app that mounts every router under `/api/v1`
+ * (`app.include_router(properties.router, prefix=settings.api_prefix)`); all 7 failed on a 404.
+ *
+ * This module answers one question given a bundled file's path and content: "if this file
+ * defines routes, which OTHER tracked file mounts it, and which existing test already exercises
+ * a router mounted the same way?" Both answers are returned as extra paths for the caller to
+ * bundle alongside the file the story named — it does not read the filesystem itself, so it stays
+ * as pure/testable as the rest of `cli/lib`.
+ */
+
+const path = require('path');
+
+// A file DEFINES routes when it either builds a router object (FastAPI's `APIRouter()`, Express's
+// `Router()`) or decorates/registers at least one HTTP verb against one (`@router.get(...)`,
+// `router.get(...)`) — the object alone (an empty router) is not enough to justify following it.
+const DEFINES_ROUTER_OBJECT = /\bAPIRouter\s*\(|\b(?:express\.)?Router\s*\(\s*\)/;
+const REGISTERS_A_ROUTE = /@\w+\.(get|post|put|delete|patch)\s*\(|\b\w+\.(get|post|put|delete|patch)\s*\(\s*['"`]/i;
+
+function definesRoutes(content) {
+  const text = String(content || '');
+  return DEFINES_ROUTER_OBJECT.test(text) && REGISTERS_A_ROUTE.test(text);
+}
+
+// Where an app typically registers its routers/routes — bounded, so following a mount never
+// means reading every tracked file's content. FastAPI/Flask/Express conventions only; a repo
+// using neither simply gets no mount file, same as today.
+const ENTRYPOINT_NAME_RE = /(^|\/)(main|app|asgi|wsgi|server|index|__init__)\.(py|js|mjs|cjs|ts)$/i;
+
+// `app.include_router(...)` (FastAPI/Starlette) or `app.use(...)` (Express) — the call that
+// registers a router built elsewhere. Requires the SAME file to also reference the router
+// file's module name, so a coincidental `app.use(` for an unrelated router does not match.
+const MOUNT_CALL_RE = /\b\w+\.include_router\s*\(|\b\w+\.use\s*\(/;
+
+function baseModuleName(filePath) {
+  return path.posix.basename(String(filePath || ''), path.posix.extname(String(filePath || '')));
+}
+
+function mentionsModule(content, moduleName) {
+  if (!moduleName) return false;
+  const re = new RegExp(`\\b${moduleName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+  return re.test(String(content || ''));
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.routeFilePath   the bundled file being checked
+ * @param {string} o.routeFileContent
+ * @param {string[]} o.repoFiles     every tracked path (the caller's git ls-files list)
+ * @param {(p:string)=>string} o.readFile  reads a candidate mount file; the caller's disk I/O
+ * @returns {string|null} the path of the file that mounts routeFilePath's router, or null
+ */
+function findMountFile({ routeFilePath, routeFileContent, repoFiles, readFile }) {
+  if (!definesRoutes(routeFileContent)) return null;
+  const moduleName = baseModuleName(routeFilePath);
+  const candidates = (Array.isArray(repoFiles) ? repoFiles : [])
+    .filter((p) => p !== routeFilePath && ENTRYPOINT_NAME_RE.test(p));
+  for (const candidate of candidates) {
+    let content;
+    try { content = readFile(candidate); } catch { continue; }
+    if (MOUNT_CALL_RE.test(content) && mentionsModule(content, moduleName)) return candidate;
+  }
+  return null;
+}
+
+// The same directory-prefix + name convention `cli/lib/layout-detect.js` uses for a test root —
+// kept independent (not imported) because this module's job is narrower: ONE existing file to
+// show the test writer the mounted-prefix convention, not a directory computation.
+const TEST_PATH_RE = /(^|\/)(tests?|__tests__|spec|specs|e2e)(\/|$)|\.(test|spec)\.[a-z]+$/i;
+// A test that actually drives an HTTP client — the convention worth copying — over one that
+// merely lives in a test directory (a fixtures or conftest file, say).
+const API_TEST_SIGNAL_RE = /\bTestClient\s*\(|\bsupertest\s*\(|\brequest\s*\(\s*app\s*\)|\bclient\.(get|post|put|delete|patch)\s*\(/;
+
+function topLevelDir(filePath) {
+  const norm = String(filePath || '').replace(/^\.\//, '');
+  return norm.includes('/') ? norm.split('/')[0] : '';
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.routeFilePath
+ * @param {string[]} o.repoFiles
+ * @param {(p:string)=>string} o.readFile
+ * @returns {string|null} an existing test file demonstrating the same kind of route testing
+ */
+function findExistingApiTest({ routeFilePath, repoFiles, readFile }) {
+  const dir = topLevelDir(routeFilePath);
+  const candidates = (Array.isArray(repoFiles) ? repoFiles : [])
+    .filter((p) => p !== routeFilePath && (!dir || p.startsWith(dir + '/')) && TEST_PATH_RE.test(p));
+  for (const candidate of candidates) {
+    let content;
+    try { content = readFile(candidate); } catch { continue; }
+    if (API_TEST_SIGNAL_RE.test(content)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * The one entry point `run-context.js` calls per already-bundled ("present") file.
+ * @returns {string[]} zero, one or two extra paths to bundle (mount file, existing API test)
+ */
+function followRouterMount({ routeFilePath, routeFileContent, repoFiles, readFile }) {
+  if (!definesRoutes(routeFileContent)) return [];
+  const extra = [];
+  const mountFile = findMountFile({ routeFilePath, routeFileContent, repoFiles, readFile });
+  if (mountFile) extra.push(mountFile);
+  const testFile = findExistingApiTest({ routeFilePath, repoFiles, readFile });
+  if (testFile) extra.push(testFile);
+  return extra;
+}
+
+module.exports = { definesRoutes, findMountFile, findExistingApiTest, followRouterMount };

package/lib/bundle-paths.js

@@ -315,13 +315,25 @@ function anchorLineForStory(content, storyText) {
  * The fallback is the OLD behaviour on purpose: a term that is only ever mentioned still
  * gets the operator a window near it, which beats none.
  */
+/**
+ * HC-GF-206-followup-1: a collapsed hit is a real site — the collapse only means it EXPECTS to
+ * share its neighbour's window, not that it is covered. The final window's radius is chosen
+ * later (as low as 200 chars, `planFileExcerpt`) and can land under the 40-line threshold that
+ * collapsed it, so a hit collapsed at 36 lines from its neighbour can fall outside the window
+ * that was supposed to carry it, with nothing reporting the loss. `collapsed` returns each
+ * dropped hit with `near`, the kept site's line it was folded into, so the caller can extend
+ * that site's window to actually reach it.
+ *
+ * @returns {{sites: Array<{line: number, anchor: string}>,
+ *            collapsed: Array<{line: number, anchor: string, near: number}>}}
+ */
 function anchorSitesForStory(content, storyText, max = 6) {
   // HC-GF-204: every region a story's terms point at, best-first. `anchorLineForStory`
   // answers "where does this live"; a story also needs "where is it USED", and on run
   // ad4a561f the planner had the definition and refused for want of the call sites.
   const text = String(content || '');
   const story = String(storyText || '');
-  if (!text || !story) return [];
+  if (!text || !story) return { sites: [], collapsed: [] };
   const candidates = [...story.matchAll(BACKTICKED_RE)]
     .map((m) => m[1].trim())
     .filter((c) => c.length >= 3
@@ -331,6 +343,7 @@ function anchorSitesForStory(content, storyText, max = 6) {
 
   const seenLine = new Set();
   const sites = [];
+  const collapsed = [];
   for (const anchor of candidates) {
     const def = definitionIndexOf(text, anchor);
     if (def === -1) continue;
@@ -339,14 +352,16 @@ function anchorSitesForStory(content, storyText, max = 6) {
     for (const m of text.matchAll(new RegExp(`(?<![\\w$])${t}(?![\\w$])`, 'g'))) offsets.push(m.index);
     for (const off of offsets) {
       const line = text.slice(0, off).split('\n').length;
-      // Collapse near-duplicates: two hits 20 lines apart share one window.
-      if ([...seenLine].some((l) => Math.abs(l - line) < 40)) continue;
+      // Collapse near-duplicates: two hits 20 lines apart share one window. `near` records
+      // WHICH kept site it shares with, so a caller can pull it back in later.
+      const near = [...seenLine].find((l) => Math.abs(l - line) < 40);
+      if (near !== undefined) { collapsed.push({ line, anchor, near }); continue; }
       seenLine.add(line);
       sites.push({ line, anchor });
-      if (sites.length >= max) return sites;
+      if (sites.length >= max) return { sites, collapsed };
     }
   }
-  return sites;
+  return { sites, collapsed };
 }
 
 function definitionIndexOf(text, term) {
@@ -428,7 +443,7 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     // hence budgeted first, and `mergeIntersectingWindows` unions it with any inferred
     // window it overlaps. No sort, no priority field — array order already says it.
     // HC-GF-288: every stated line seeds it, in the caller's order.
-    const inferred = anchorSitesForStory(text, storyText);
+    const { sites: inferred, collapsed } = anchorSitesForStory(text, storyText);
     const sites = [...stated.map((l) => ({ line: l, anchor: null })), ...inferred];
     const chosen = sites.length ? sites : [hit];
     const why = (a, l) => (a ? `anchored on \`${a}\`` : `centered on referenced line ${l}`);
@@ -449,8 +464,19 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     // The radius is sized before any window exists, so it prices the marker at its widest:
     // the longest label among the sites, with line numbers at the file's own width.
     const widest = { startLine: totalLines, endLine: totalLines, totalLines };
+    // HC-GF-334: the footer repeats `filePath` in EVERY kept window (see `footer` above), so
+    // sizing `radius` off its real length made window boundaries — and therefore which sites
+    // and collapsed hits are reachable — depend on how long the file's path happens to be.
+    // Measured: with real files and roadmap rows, a fake path fixed at length 80 or 90 dropped
+    // a hit that lengths 10-70 and 100-200 all kept, for the SAME content and story — a path a
+    // few characters different flips whether a window's char-radius snaps past a line boundary.
+    // Reserve a fixed, generous footer cost for SIZING the radius instead of the real one, so
+    // the estimate — and the windows it produces — no longer shift with path length. `costOf`
+    // and `budget()` below still charge the REAL footer length, so the cap is still never
+    // exceeded even for a path longer than this reserve; it only stops falling short of it.
+    const FOOTER_SIZING_RESERVE_CHARS = 300;
     const markerCost = Math.max(...chosen.map((s) => header(widest, s.anchor, totalLines).length))
-      + footer.length + 1;
+      + Math.max(footer.length, FOOTER_SIZING_RESERVE_CHARS) + 1;
     // HC-GF-288: the 800 covers ONE window's marker, and every further window brings its
     // own. Sized from `limit - 800` alone, n windows overran the cap from n = 3 — so the
     // LAST region was always dropped however much room the rest left. Measured on
@@ -515,15 +541,15 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     // only ever dropped when the stated regions alone exceed the cap.
     const budget = (ord) => {
       const kept = [];
+      const skipped = [];
       let spent = 0;
-      let skipped = 0;
       for (const site of ord) {
         const cost = costOf(site);
         if (spent + cost > limit) {
           // A dropped stated region is reported by LINE below, not counted here: the
           // advice attached to this count — "name them as path:<line>" — is advice the
           // operator has already followed for those.
-          if (!site.stated) skipped += 1;
+          if (!site.stated) skipped.push(site);
           continue;
         }
         spent += cost;
@@ -551,6 +577,12 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     // considered: a layout with no window sends the result to the fallback, which overruns
     // the cap by construction. Third review: preferring width alone discarded a 1,066-char
     // layout for a 33,002-char fallback at cap 12,000.
+    //
+    // HC-GF-188-followup-1: so a layout that kept nothing has not succeeded, stated lines or
+    // not. With none stated, "honours every stated line" was vacuously true at the estimate,
+    // the narrower retry never ran, and the fallback returned 30,502 chars at cap 12,000 —
+    // the first inferred anchor's long line — while the second anchor's window, 411 chars at
+    // radius 200, was never tried. With a stated line, honouring it already means a window.
     let best = null;
     const better = (a, b) => (a.honoured - b.honoured)
       || (Number(a.plan.kept.length > 0) - Number(b.plan.kept.length > 0))
@@ -560,10 +592,10 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
       const honoured = stated.filter((l) => plan.kept.some(({ w }) => covers(w, l))).length;
       const cand = { r, plan, honoured };
       if (!best || better(cand, best) > 0) best = cand;
-      return honoured === stated.length;
+      return honoured === stated.length && plan.kept.length > 0;
     };
     if (!tryRadius(radius) && radius > 200 && tryRadius(200)) {
-      // All stated lines fit at 200 but not at the estimate: binary-search between them.
+      // It fits at 200 but not at the estimate: binary-search between them.
       // Bounded by log2(radius) layouts — measured at most 12 layouts and 228 ms on a
       // 1.6 MB file of long lines, a few ms on ordinary source.
       let lo = 200;
@@ -575,7 +607,6 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     }
     radius = best.r;
     windows.push(...best.plan.kept);
-    const dropped = best.plan.skipped;
     if (!windows.length) {
       // Nothing fits at any radius tried — one line alone is longer than the cap. Build the
       // window at the MINIMUM radius, so the overrun is that line and no more: at the
@@ -583,6 +614,66 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
       const w = windowAroundLine(text, chosen[0].line, 200);
       windows.push({ w, anchor: chosen[0].anchor, line: chosen[0].line });
     }
+    // HC-GF-188-followup-1: a region is dropped when NOTHING bundled reaches it — counted
+    // against what is returned, not what the budget skipped. The fallback above returns one
+    // region the budget had skipped, and the notice still called it dropped: "2 further
+    // region(s) DROPPED" with one missing. Every window grows with the radius around the
+    // same line, so the fallback's window lies inside that region's; and the layout's
+    // regions are disjoint once merged, so no other skipped region intersects a kept one.
+    const dropped = best.plan.skipped.filter((s) =>
+      !windows.some(({ w }) => w.startLine <= s.w.endLine && s.w.startLine <= w.endLine)).length;
+
+    // HC-GF-206-followup-1: a collapsed hit shares its neighbour's window in EXPECTATION only.
+    // `radius` was chosen for the whole layout and can end up under the 40-line threshold that
+    // collapsed the hit in the first place, cutting it out of the window that was supposed to
+    // carry it. Pull each missed hit back in by widening its neighbour's window to reach it,
+    // then re-merge — widening can make two previously-separate kept windows intersect.
+    let unreached = 0;
+    if (collapsed.length) {
+      for (const hit of collapsed) {
+        if (windows.some(({ w }) => covers(w, hit.line))) continue; // already inside some window
+        // The neighbour is the kept window whose site.line this hit collapsed into — falling
+        // back to nearest-by-distance when that site's own window was dropped for budget.
+        let target = windows.find(({ line: siteLine }) => siteLine === hit.near);
+        if (!target) {
+          let bestDist = Infinity;
+          for (const entry of windows) {
+            const dist = hit.line < entry.w.startLine ? entry.w.startLine - hit.line
+              : hit.line > entry.w.endLine ? hit.line - entry.w.endLine : 0;
+            if (dist < bestDist) { bestDist = dist; target = entry; }
+          }
+        }
+        if (!target) continue; // no window exists at all — reported as unreached below
+        // THE BUDGET PROMISE STILL HOLDS: widen, re-merge (an overlap with another kept window
+        // is a real possibility once widened), price the result, and roll back rather than
+        // overrun the cap. A hit that cannot be reached within budget is unreached, not free.
+        const before = windows.map((e) => ({ ...e }));
+        target.w = windowBetweenLines(text,
+          Math.min(target.w.startLine, hit.line), Math.max(target.w.endLine, hit.line));
+        const merged = mergeIntersectingWindows(text, windows);
+        const cost = merged.reduce((s, e) => s + costOf(e), 0);
+        if (cost > limit) {
+          windows.length = 0;
+          windows.push(...before);
+          continue;
+        }
+        windows.length = 0;
+        windows.push(...merged);
+      }
+      // Re-sort stated windows back to the front — merging can reorder when a widened window
+      // now overlaps one processed earlier, and `windows[0]` below is read as THE region (its
+      // anchor and line drive `because`). Mirrors `layout()`'s own sort exactly: `rankOf` returns
+      // -1 for a non-stated window, and sorting on that raw value would put it AHEAD of a stated
+      // one (found-index 0) rather than behind every stated window — map it to Infinity first.
+      const resorted = windows
+        .map((c, i) => { const k = rankOf(c); return { c, k: k === -1 ? Infinity : k, i }; })
+        .sort((a, b) => (a.k - b.k) || (a.i - b.i))
+        .map(({ c }) => c);
+      windows.length = 0;
+      windows.push(...resorted);
+      unreached = collapsed.filter((hit) => !windows.some(({ w }) => covers(w, hit.line))).length;
+    }
+
     // HC-GF-288: which stated lines no kept window contains. Only the budget can do that
     // here — every stated line seeded a window, and a merge never shrinks one.
     const lost = stated.filter((l) => !windows.some(({ w }) => covers(w, l)));
@@ -600,6 +691,11 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
       : '')
       + (lost.length > 0
         ? ` — stated line(s) ${lost.join(', ')} DROPPED for budget; name fewer regions in ${filePath}`
+        : '')
+      // HC-GF-206-followup-1: a hit collapsed into a neighbour whose final window still missed
+      // it — counted rather than silent, the same shape as `dropped` and `lost` above.
+      + (unreached > 0
+        ? ` — ${unreached} near-duplicate hit(s) collapsed into a window that did not reach them`
         : '');
 
     return {
@@ -613,12 +709,16 @@ function planFileExcerpt({ content, cap, line = null, lines = null, storyText =
     };
   }
 
-  const dropped = text.length - limit;
+  // HC-GF-188-followup-1: the marker is inside the cap, as a window's header and footer are.
+  // Appended after `limit` chars, it took cli/hone-cli.js to 8,077 chars at cap 8,000. It
+  // names the chars KEPT, which is at most `limit`, so its own length can only shrink.
+  const marker = (n) => `\n\n# [HC-019n-followup-12: truncated at ${n} chars; full file is ${text.length} chars]`;
+  const keep = Math.max(0, limit - marker(limit).length);
+  const dropped = text.length - keep;
   return {
     mode: 'truncate',
     unhonoured,
-    content: text.slice(0, limit)
-      + `\n\n# [HC-019n-followup-12: truncated at ${limit} chars; full file is ${text.length} chars]`,
+    content: text.slice(0, keep) + marker(keep),
     notice: `  ⚠ ${filePath} is ${text.length} chars (cap ${limit}) — head-truncated, ${dropped} chars `
       + `DROPPED and nothing in the story text matched inside the file, so the region you care about `
       + `may not be in the bundle. Name it as ${filePath}:<line>, or quote the code, to anchor it.`,

package/lib/emit-pr.js

@@ -188,7 +188,35 @@ function decidePublish({ branchExists, openPrUrl }) {
   return { action: 'proceed', exitCode: EXIT.PASS };
 }
 
+/**
+ * HC-GF-302: tell the server which PR this emit opened or found already open, so the batch's
+ * morning report links it instead of hoping an agent wrote the URL into its output.
+ *
+ * Best-effort, and the caller never changes its exit code on the result: the PR exists either way.
+ * It only reports whether the server now knows about it. No PR URL (a dry run, or a push without
+ * --open-pr) records nothing: the report has no link to show for a branch. The attempt is the one
+ * the step GET resolved; without it the server cannot order records, so nothing is sent.
+ *
+ * @param {{ post: (path: string, body: object) => Promise<unknown>, path: string, prUrl?: string|null,
+ *   branch: string, baseSha?: string|null, attempt?: number|null }} args
+ * @returns {Promise<{ recorded: boolean, reason?: string }>}
+ */
+async function recordPr({ post, path, prUrl, branch, baseSha, attempt }) {
+  if (!prUrl) return { recorded: false, reason: 'no PR URL to record' };
+  if (!Number.isInteger(attempt) || attempt < 1) {
+    return { recorded: false, reason: 'the server did not say which step_4 attempt this is' };
+  }
+  try {
+    await post(path, { branch, prUrl, baseSha: baseSha || null, attempt });
+    return { recorded: true };
+  } catch (e) {
+    const detail = (e && e.response && e.response.data && e.response.data.error) || (e && (e.code || e.message)) || String(e);
+    return { recorded: false, reason: e && e.response ? `HTTP ${e.response.status}: ${detail}` : detail };
+  }
+}
+
 module.exports = {
+  recordPr,
   verifyStateFor,
   EXIT,
   HONEST_LIMIT,

package/lib/fresh-connection.js

@@ -0,0 +1,27 @@
+'use strict';
+
+/**
+ * HC-GF-326: request options that open a NEW connection for one request.
+ *
+ * Node's default agent keeps sockets alive. verify-patch GETs the run, then runs the
+ * test suite with spawnSync, which blocks the event loop for minutes — far past the
+ * server's keep-alive timeout (5 s by default). The server closes the idle socket, the
+ * blocked client never processes the close, and the verdict POST is written to the dead
+ * pooled socket: `read ECONNRESET`, 5 reports out of 5, each labelled non-fatal. Every
+ * verdict a verify produced was lost to the server.
+ *
+ * Pass these to the one request that follows a long synchronous block. What makes the
+ * connection fresh is the new agent: its pool is empty, so the request opens a socket.
+ * `keepAlive: false` only stops that socket being pooled afterwards.
+ */
+const http = require('http');
+const https = require('https');
+
+function freshConnection() {
+  return {
+    httpAgent: new http.Agent({ keepAlive: false }),
+    httpsAgent: new https.Agent({ keepAlive: false }),
+  };
+}
+
+module.exports = { freshConnection };

package/lib/layout-detect.js

@@ -20,6 +20,14 @@ const EXCLUDE = /(^|\/)(node_modules|dist|build|coverage|\.git|\.next|vendor|__p
 const SOURCE_EXT = /\.(js|mjs|cjs|jsx|ts|tsx|py|java|kt|rb|go|rs|php|cs|scala|swift|cls|trigger|apex)$/i;
 const TEST_HINT = /(^|\/)(tests?|__tests__|spec|specs|e2e)(\/|$)|\.(test|spec)\.[a-z]+$/i;
 
+// HC-GF-020-followup-1: a documentation directory routinely carries a handful of genuinely
+// source-extension files (Sphinx's conf.py, a docs-site build script) that clear MIN_FILES on
+// extension count alone — measured live: a docs/ of mostly .html/.svg pages qualified as a
+// source dir because it also held two .py files. Extension MIX, not source-extension COUNT, is
+// what tells a docs directory apart from a package: if a top-level dir's tracked files are more
+// documentation than source, it is documentation, however many stray source-ext files it holds.
+const DOC_EXT = /\.(md|mdx|rst|adoc|txt|html?|svg|png|jpe?g|gif|ico|pdf)$/i;
+
 // Directories whose NAME means "this is where the code is". A repo that puts code directly at the
 // root of a package still gets that package dir, via the manifest-dir fallback below.
 const SOURCE_DIR_NAMES = /^(src|lib|app|source|server|client|api|packages|apps|core)$/i;
@@ -61,6 +69,27 @@ function detectLayout({ root, trackedPaths, minFiles = 2 } = {}) {
   const srcFiles = paths.filter(p => SOURCE_EXT.test(p) && !TEST_HINT.test(p));
   const testFiles = paths.filter(p => SOURCE_EXT.test(p) && TEST_HINT.test(p));
 
+  // Extension mix per top-level dir, over EVERY tracked path (not just the source-ext-filtered
+  // srcFiles/testFiles) — a docs/ directory's defining feature is the files roll() never looks
+  // at otherwise (its .html/.svg pages), so the doc-vs-source comparison needs the full list.
+  const extCountsByTop = new Map();
+  for (const p of paths) {
+    const top = p.includes('/') ? p.split('/')[0] : '.';
+    if (!extCountsByTop.has(top)) extCountsByTop.set(top, { doc: 0, src: 0 });
+    const c = extCountsByTop.get(top);
+    if (DOC_EXT.test(p)) c.doc += 1;
+    else if (SOURCE_EXT.test(p)) c.src += 1;
+  }
+  function isDocumentationOnly(top) {
+    // A dotdir (.github, .storybook, .devcontainer, ...) is tooling/config by convention, never
+    // a published-docs directory, even when it holds far more Markdown records (pipeline history,
+    // learnings) than source-ext scripts — hone-server's OWN .github/scripts/ is real code that
+    // must stay visible (HC-DF-005) alongside .github/pipeline/'s hundreds of Markdown records.
+    if (top.startsWith('.')) return false;
+    const c = extCountsByTop.get(top);
+    return !!c && c.doc > c.src;
+  }
+
   function roll(files, nameRe = SOURCE_DIR_NAMES) {
     const byTop = new Map();
     for (const f of files) {
@@ -71,6 +100,7 @@ function detectLayout({ root, trackedPaths, minFiles = 2 } = {}) {
     const out = [];
     for (const [top, list] of byTop) {
       if (top === '.') continue; // root-level scripts are not a source ROOT
+      if (isDocumentationOnly(top)) continue; // docs/ with a stray conf.py is still docs/
       const qualifies = nameRe.test(top) || manifestDirs.has(top) || list.length >= minFiles;
       if (!qualifies) continue;
       // Descend one level when this is a container of packages, or when a conventional source
@@ -83,14 +113,23 @@ function detectLayout({ root, trackedPaths, minFiles = 2 } = {}) {
       // Files sitting DIRECTLY in this dir (cli/hone-cli.js). If any exist, the dir itself is
       // the source root — descending would silently drop them, which is how an early cut of this
       // rule emitted `cli/lib` and lost cli/hone-cli.js (5.8k lines, the whole CLI surface).
-      // Descend ONLY into a package container (packages/, apps/). Anywhere else, prefer the
-      // PARENT: a wider scope is the safe error for grounding, a narrower one hides real files.
-      // An earlier rule descended into conventional children and emitted `server/src`, which
-      // dropped `server/scripts/` — the exact residual the followup-42 dogfood run hit, where the
-      // planner could not see the agent prompts and proposed inventing them elsewhere.
       const direct = list.filter(f => f.split('/').length === 2).length;
       const container = /^(packages|apps|services|modules)$/i.test(top);
-      if (container && kids.size > 0 && direct === 0) { out.push(...[...kids.keys()]); continue; }
+      // HC-GF-020-followup-1: TEST dirs alone also descend into a sole, unambiguous child (a repo's
+      // real test dir was reported as `backend` because every test sat under `backend/tests`, a name
+      // this rule never recognized). Deliberately NOT extended to source dirs: an earlier rule
+      // descended into ANY conventional child regardless of ambiguity and emitted `server/src`,
+      // which dropped `server/scripts/` — the exact residual the followup-42 dogfood run hit, where
+      // the planner could not see the agent prompts and proposed inventing them elsewhere. `server/`
+      // has both `server/src` and `server/scripts` (2 kids) so it is unaffected either way, but a
+      // repo where `server/` holds ONLY `server/src` must still stay at `server` for source dirs —
+      // measured by this file's own regression pins — so the single-kid case is test-dirs-only.
+      // ...and only when `top` itself is NOT already a conventionally-named test root: a `tests/`
+      // dir with a single `tests/integration` child is intentionally left at `tests` — descending
+      // would report a narrower, equally-arbitrary name in place of the convention that already
+      // says exactly what this directory is.
+      const soleUnambiguousTestChild = nameRe === TEST_DIR_NAMES && !nameRe.test(top) && kids.size === 1 && direct === 0;
+      if ((container || soleUnambiguousTestChild) && kids.size > 0 && direct === 0) { out.push(...[...kids.keys()]); continue; }
       out.push(top);
     }
     return [...new Set(out)].sort();

package/lib/run-context.js

@@ -30,6 +30,7 @@ const {
   extractPathRefs, extractBareRefs, resolveBareName, alreadyCovered, planFileExcerpt,
 } = require('./bundle-paths');
 const { selectBundle, auditLines } = require('./bundle-context');
+const { followRouterMount } = require('./bundle-mount-follow');
 const { parseIncludePaths, partitionIncludeTargets, statedAnchorsFor, anchorWarnings } = require('./include-paths');
 const { buildRepoTree, allDirs, MAX_TRANSPORT_PATHS, MAX_TRANSPORT_DIRS } = require('./repo-tree');
 const { classifyStory } = require('./story-classifier');
@@ -497,7 +498,24 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
       // HC-GF-073: what exists, what is pending, plus repo-level signal files and existing
       // neighbours of the pending paths. Order is priority order: the char cap cuts from the end.
       const selection = selectBundle({ named: [...candidates], repoFiles: repoCtx.repoFiles, exists: io.exists });
-      const ordered = [...selection.present, ...selection.signal, ...selection.siblings];
+      // HC-GF-325: a present file that DEFINES routes says nothing about where they are MOUNTED —
+      // step_2 wrote 7 tests against `/properties` for an app that serves every router under
+      // `/api/v1`. Right after `present`, so a mount file and an existing API test of the same
+      // kind get priority over signal files and siblings within the char budget, same as a path
+      // the story named directly would.
+      const alreadySelected = new Set([...selection.present, ...selection.signal, ...selection.siblings]);
+      const mountFollowed = [];
+      for (const p of selection.present) {
+        let content;
+        try { content = io.readFile(p); } catch { continue; }
+        for (const extra of followRouterMount({ routeFilePath: p, routeFileContent: content, repoFiles: repoCtx.repoFiles, readFile: io.readFile })) {
+          if (alreadySelected.has(extra)) continue;
+          alreadySelected.add(extra);
+          mountFollowed.push(extra);
+          pre.push(info(`  → bundled ${extra} — mounts/tests the router in ${p} (HC-GF-325)`));
+        }
+      }
+      const ordered = [...selection.present, ...mountFollowed, ...selection.signal, ...selection.siblings];
       const codebaseFiles = [];
       let totalChars = 0;
       let budgetSpent = false; // HC-GF-288: so a not-bundled warning can say WHY

package/lib/server-banner.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * HC-LC-004 banner, with a third state (HC-GF-328).
+ *
+ * `health` is the parsed `/health` body, or null when the server did not answer. The
+ * banner used to print PROD / THIS RUN COSTS MONEY for null, so an unreachable
+ * 127.0.0.1 was announced as a paid production run, and the run then failed with
+ * ECONNREFUSED. A server that did not answer is named as such: nothing about its cost
+ * or provider is known, so the line keeps HC-LC-004's safe default: assume it costs money.
+ */
+function serverBanner(apiUrl, health) {
+  if (!health) return `UNREACHABLE ${apiUrl} · /health did not answer · provider unknown · if this run starts, assume it COSTS MONEY`;
+  const llm = health.llm || null;
+  if (llm && llm.local) return `LOCAL  ${apiUrl} · provider claude_cli · no paid fallback · this run costs $0.00`;
+  return `PROD   ${apiUrl} · provider ${llm ? llm.primary : 'unknown'} · THIS RUN COSTS MONEY`;
+}
+
+module.exports = { serverBanner };

package/lib/setup-dry-run.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * HC-GF-320: what `hone setup --dry-run` would do AFTER the setup script.
+ *
+ * The script honours --dry-run itself; the CLI phases that follow it did not.
+ * A dry run installed CLAUDE.md, rewrote an existing .pipeline-config.yml
+ * (platform grounding), installed test packages (--install-tests) and PUT
+ * branch protection on the default branch through the GitHub API. The CLI
+ * now stops after the script on a dry run and prints these lines instead.
+ *
+ * Pure: every fact is passed in, so the plan is testable without a server.
+ */
+function postScriptDryRunPlan({ claudeMdTemplate, claudeMdExists, configExists, installTests, skipBranchProtection }) {
+  const lines = [];
+  if (claudeMdTemplate) {
+    lines.push(claudeMdExists
+      ? 'CLAUDE.md already exists — would skip it'
+      : 'Would install CLAUDE.md (Claude Code pipeline context)');
+  }
+  if (configExists) lines.push('Would re-run platform grounding on .github/.pipeline-config.yml');
+  if (installTests) lines.push('Would install a unit test framework (--install-tests)');
+  lines.push(skipBranchProtection
+    ? 'Would skip branch protection (opted out)'
+    : 'Would install GitHub branch protection on the default branch (pass --no-branch-protection to skip)');
+  return lines;
+}
+
+module.exports = { postScriptDryRunPlan };

package/lib/verify-patch.js

@@ -196,7 +196,7 @@ function verifyCommandEnv(base = process.env) {
  * Pass the `command` that ran and the resolver's `source` for it: without them an absent command is
  * indistinguishable from a failing one (HC-GF-008), and the CLI's two executors both do.
  *
- * @param {{ code: number|null, timedOut: boolean, stdout?: string, stderr?: string, command?: string, source?: string }} run
+ * @param {{ code: number|null, timedOut: boolean, stdout?: string, stderr?: string, command?: string, source?: string, error?: { code?: string } }} run
  * @returns {{ verdict: 'pass'|'fail'|'timeout'|'unresolved', exitCode: number, detail: string }}
  */
 function verdictFromRun(run, provisioning = null) {
@@ -216,6 +216,18 @@ function verdictFromRun(run, provisioning = null) {
   if (run.timedOut) {
     return { verdict: 'timeout', exitCode: EXIT.TIMEOUT, detail: 'test command exceeded the timeout' };
   }
+  // HC-GF-331: spawnSync kills the child and reports status: null with error.code ENOBUFS when
+  // its stdout/stderr exceed maxBuffer. A null status otherwise falls through to the generic
+  // "tests failed (exit null)" path below — the suite may have passed; nothing conclusive was
+  // observed about it either way, so this is its own outcome, never a reported failure.
+  if (run.error && run.error.code === 'ENOBUFS') {
+    return {
+      verdict: 'unresolved',
+      exitCode: EXIT.UNRESOLVED,
+      detail: 'test output exceeded the capture buffer (ENOBUFS) — nothing conclusive was observed '
+        + 'about this change; raise maxBuffer or have the command print less',
+    };
+  }
   if (run.code === 0) {
     // HC-GF-223: a pass under an operator-supplied command is evidence about a SUBSET. Measured on
     // run `437246a7`: `--command "node --test <3 files>"` reported `pass` to the server and the same
@@ -401,6 +413,11 @@ function classifyGateRun(run) {
     return { verdict: 'unavailable', detail: 'command not found — gate NOT run' };
   }
   if (run.timedOut) return { verdict: 'unavailable', detail: 'timed out — gate NOT run to completion' };
+  // HC-GF-331: shares verdictFromRun's shape — a null status from an ENOBUFS overflow is not a
+  // finding, it is the gate not having run to a readable conclusion.
+  if (run.error && run.error.code === 'ENOBUFS') {
+    return { verdict: 'unavailable', detail: 'output exceeded the capture buffer (ENOBUFS) — gate NOT run to completion' };
+  }
   if (run.code === 0) return { verdict: 'pass', detail: 'clean' };
   const sum = summarizeFailure(run, { maxLines: 6 });
   // A linter prints its findings from the TOP, so unlike a test runner the most

package/package.json

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