@hone-ai/cli 1.40.0 → 1.41.0

package/hone-cli.js

@@ -6038,6 +6038,8 @@ program
       if (!opts.file && !opts.fromTree) { console.error('Provide the output via --file <path> (the text your editor produced), or --from-tree to render it from the working tree.'); process.exit(1); }
       const fs = require('fs');
       let output;
+      let reviewDiff = null;
+      let warned = false;
       if (opts.fromTree) {
         const { renderFromTree } = require('./lib/tree-artifact');
         const rendered = renderFromTree({ repoRoot: process.cwd(), testReport: opts.testReport });
@@ -6046,15 +6048,32 @@ program
         // artifact does not is a decision the operator has to be able to see.
         for (const s2 of rendered.skipped) console.error(`not included: ${s2.path} — ${s2.reason}`);
         console.error(`from-tree: ${rendered.files.length} file(s), ${rendered.deletes.length} deletion(s), ${rendered.skipped.length} skipped`);
+        // HC-GF-390: for a build, the base diff of each file emitted whole whose original the reviewers saw only in
+        // windows. Sent beside the artifact, stored apart from it, and never a reason this submit fails.
+        if (stepKey === 'step_4') {
+          try {
+            const { computeReviewDiff } = require('./lib/review-diff');
+            reviewDiff = computeReviewDiff({ repoRoot: process.cwd(), rendered,
+              warn: (line) => { warned = true; console.error(line); } });
+          } catch (e) { reviewDiff = null; warned = true; console.error(`review diff not sent: ${e.message}`); }
+          if (reviewDiff) {
+            console.error(`review diff: ${reviewDiff.stats.files} file(s), ${reviewDiff.notes.length} note(s), against ${reviewDiff.headSha.slice(0, 12)}`);
+            for (const n of reviewDiff.notes) console.error(`  review diff note: ${n}`);
+          } else {
+            console.error(warned ? 'review diff: none (see above)' : 'review diff: none (no modified file over the bundle cap)');
+          }
+        }
       } else {
         output = fs.readFileSync(opts.file, 'utf8');
       }
       const { data } = await client.post(
         orchestratePath([runId, 'step', stepKey, 'editor-output']),
-        { contractVersion: opts.contract, output }
+        { contractVersion: opts.contract, output,
+          ...(reviewDiff ? { reviewDiff: require('./lib/review-diff').toWire(reviewDiff) } : {}) }
       );
       if (opts.format === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       console.log(`Step ${data.stepKey} completed (executed_by: ${data.executedBy}); gate: ${data.gateResult}.`);
+      if (data.reviewDiffIgnored) console.error(`review diff not stored: ${data.reviewDiffIgnored} (the reviewers see the files unverified, as before)`);
       console.log(`Approve when reviewed: hone run-story ${runId} --approve ${data.stepKey}`);
       console.log('Verification is unchanged — check-patch/verify-patch judge this output, not trust.');
     } catch (e) {
@@ -6107,10 +6126,6 @@ function runContextIo(apiConfig) {
     e2eSpecMode: () => pc.readE2eSpecMode(cwd),
     verificationGate: () => pc.readVerificationGateConfig(cwd),
     verificationGateSources: () => pc.readVerificationGateSources(cwd),
-    readPlanText: () => {
-      const planPath = path.join(cwd, '.github', 'EXECUTION_PLAN.yml');
-      return fs.existsSync(planPath) ? fs.readFileSync(planPath, 'utf8') : '';
-    },
     exists: (rel) => { const abs = inRepo(rel); return !!abs && fs.existsSync(abs); },
     isDirectory: (rel) => { const abs = inRepo(rel); try { return !!abs && fs.statSync(abs).isDirectory(); } catch { return false; } },
     readFile: (rel) => {
@@ -6200,6 +6215,7 @@ program
   .option('--include-paths <paths>', 'Source file paths to bundle into the codebase context (HC-019n-followup-12). Comma-separated, and the flag may be repeated; both forms accumulate. Augments auto-detected paths from the issue body.', collectIncludePaths, [])
   .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)')
+  .option('--consult-architect', 'HC-GF-397: run the architect consult (step_0b) even when the groomer says architect_engaged: false. It can only add the consult, never skip it.')
   .action(async (storyIdOrRunId, opts) => {
     const config = getConfig();
     const client = api(config);
@@ -6678,6 +6694,7 @@ program
       explicitSource: opts.storyFile ? { kind: 'file', label: path.basename(String(opts.storyFile)) } : { kind: 'description' },
       includePaths: opts.includePaths,
       axes: opts.axes,
+      consultArchitect: opts.consultArchitect,
     });
     printRunContextNotes(storyCtx.notes.pre);
     printRunContextNotes(repoCtx.notes);

package/lib/architect-config.js

@@ -20,6 +20,11 @@
  *
  * Pure helper — caller wraps fs.readFileSync + path resolution so the
  * helper is unit-testable with stubs.
+ *
+ * HC-GF-030: NO PRODUCTION CODE CALLS THIS ANY MORE. `architect_consulted` and `checklist_b_completed`
+ * are server-owned (workflow-store.js SERVER_OWNED_CONFIG_KEYS; run-context.js SERVER_OWNED_KEYS): the
+ * server writes them when its step_0b consult is approved, and a plan file's claim is not evidence that
+ * a consult ran on THIS story. The module stays as the documented reader of the plan's shape.
  */
 
 const path = require('node:path');

package/lib/batch-follow.js

@@ -59,9 +59,11 @@ const FORBIDDEN_FLAGS = Object.freeze(['--trust-source', '--skip-verify', '--rea
  * Pause reasons that mean a child is NOT at a gate waiting for its step_4 output to be judged. `GET /:runId`
  * sets `awaitingApproval` on ANY paused run with a current step, so without this a child paused by a breaker,
  * a budget, an agent's hard pause or a guardrail would look like a gate, and the loop would run its patch.
- * Sources: orchestrator.js (BATCH_*), orchestrator-guardrails.js GUARDRAIL_REFUSAL_CODES, the hard-pause scan.
+ * Sources: orchestrator.js (BATCH_*), orchestrator-guardrails.js GUARDRAIL_REFUSAL_CODES, the hard-pause scan, and
+ * architect-consult.js CONSULT_REQUIRED_CODE (HC-GF-030): a run the consult guard refused at a step it had no
+ * consult for. Its attempt is `pending` and has no output, and approving it is refused by the server.
  */
-const NOT_A_GATE = /^(BATCH_FAILURE_THRESHOLD_EXCEEDED:|BATCH_BUDGET_EXCEEDED:|MAX_RETRIES_EXCEEDED:|MAX_TOTAL_STEPS_EXCEEDED:|hard_pause at )/;
+const NOT_A_GATE = /^(BATCH_FAILURE_THRESHOLD_EXCEEDED:|BATCH_BUDGET_EXCEEDED:|MAX_RETRIES_EXCEEDED:|MAX_TOTAL_STEPS_EXCEEDED:|ARCHITECT_CONSULT_REQUIRED:|hard_pause at )/;
 
 /** What each child exit code means, for the action line. verify-patch.js and emit-pr.js EXIT maps. */
 const CHECK_EXIT = { 0: 'applies', 1: 'no diff', 2: 'does not apply' };
@@ -393,6 +395,9 @@ function priorWhy(prior, runId) {
   if (prior.state === 'adopted') {
     return `a newer run of this story already exists${b ? ` (batch ${b})` : ''}, queued by an earlier re-serve or by you, so it is not re-served again`;
   }
+  if (prior.state === 'inherited') {
+    return `this run is already the re-serve of ${prior.fromRunId ? `run ${prior.fromRunId}` : 'an earlier run'}${b ? ` (it is in batch ${b})` : ''}, so it is not re-served a second time`;
+  }
   if (prior.state === 'queue-failed') return 're-serving it failed earlier in this run; nothing more is tried';
   return `it names files again after being re-served as batch ${b}; a second re-serve is not tried`;
 }
@@ -450,7 +455,7 @@ function stuckReason(waiting) {
  * @param {Record<string, object>} details  runId → `GET /orchestrate/:runId`, for paused runs and runs to emit
  * @param {{emitted: Set<string>, reserved?: Map<string, {batchId: string|null, state: string}>}} memory  `emitted`: runs
  *   whose emit-pr already ran in this process; `reserved`: story → what became of its re-serve (`state`: served,
- *   kill-failed, queue-failed or adopted)
+ *   kill-failed, queue-failed, adopted or inherited)
  * @param {{repoName?: string|null, openPr?: boolean, tracked?: Set<string>|null, trackedRetry?: string|null,
  *          realPath?: ((file: string) => string|null)|null}} [ctx]  this checkout, so a run for another repository is
  *   not touched; `tracked`: the regular files git tracks here, which a request is checked against (`trackedRetry`:
@@ -594,7 +599,7 @@ function planTick(batch, details, memory, ctx = {}) {
  * crash between the queue and the kill, leaves no marker, and only a newer run of the same story shows it happened.
  * @returns {Promise<{lines: string[], needsYou: boolean, batchId: string|null, state: string|null, retry?: boolean}>}
  *   `batchId`: the batch the story was queued as, set whenever it was, even when the kill then failed; `state`: what
- *   became of the re-serve (served, kill-failed, queue-failed, adopted); `retry`: nothing was decided, ask again
+ *   became of the re-serve (served, kill-failed, queue-failed, adopted = a newer run exists, inherited = this run is itself the re-serve); `retry`: nothing was decided, ask again
  */
 async function reserve(action, io, tag) {
   if (io.priorServe) {
@@ -606,12 +611,16 @@ async function reserve(action, io, tag) {
         needsYou: false, batchId: null, state: null, retry: true };
     }
     if (prior && prior.kind === 'unknown') {
-      return { lines: [`${tag} not re-served: could not tell whether the story was served already; the paused run was left alone`],
+      return { lines: [`${tag} not re-served: could not tell whether the story was served already${prior.why ? ` (${prior.why})` : ''}; the paused run was left alone`],
         needsYou: true, batchId: null, state: 'queue-failed' };
     }
+    if (prior && prior.kind === 'earlier') {
+      return { lines: [`${tag} not re-served: this run is already the re-serve of run ${prior.runId} (it is in batch ${prior.batchId}), so it is not re-served a second time`],
+        needsYou: true, batchId: prior.batchId || null, state: 'inherited', fromRunId: prior.runId };
+    }
     if (prior) {
       const where = prior.batchId ? ` in batch ${prior.batchId}` : '';
-      return { lines: [`${tag} not re-served: run ${prior.runId}${where} is this story's ${prior.kind === 'later' ? 'newer' : 'earlier, re-served'} run; following it`],
+      return { lines: [`${tag} not re-served: a newer run of this story exists (run ${prior.runId}${where})${prior.batchId ? '; following it' : '; its batch was not found, so it is not followed'}`],
         needsYou: true, batchId: prior.batchId || null, state: 'adopted' };
     }
   }
@@ -695,6 +704,13 @@ async function autoReject(action, io, tag) {
     const status = statusOf(e);
     const f = fatal(e, `rejecting ${where}`);
     if (f) return { lines: [], needsYou: false, state: 'retry', fatal: f };
+    // HC-GF-323-followup-2: the server caps rejects at step_4's max_retries_per_step, counting a person's rejects too, so
+    // its refusal can come before this client's own bound. That 409 is not "the run moved on": the run is still paused
+    // at the failed attempt, and only a person can approve, kill or raise the guardrail.
+    if (status === 409 && e.response.data && e.response.data.code === 'REJECT_RETRIES_EXHAUSTED') {
+      const note = `${where} failed verification and the server refused the reject: ${oneLine(e.response.data.error, 160)}`;
+      return { lines: [`${tag} ${note}`], needsYou: true, state: 'stuck', note };
+    }
     if (status === 409) return { lines: [`${tag} ${where} was not rejected: the run moved on (409); this does not count`], needsYou: false, state: 'moved' };
     if (status === 400) {
       const note = `${where} failed verification and the server refused the reject (400: ${oneLine(e.response.data && e.response.data.error, 120)})`;
@@ -889,7 +905,7 @@ async function followBatch(batchId, io, opts = {}) {
         }
         if (action.kind === 'reserve') {
           if (!out.retry) {
-            memory.reserved.set(action.storyId, { batchId: out.batchId, state: out.state });
+            memory.reserved.set(action.storyId, { batchId: out.batchId, state: out.state, fromRunId: out.fromRunId });
             if (out.batchId && !followed.includes(out.batchId)) { followed.push(out.batchId); grew = true; }
           }
         } else if (action.kind === 'emit' || action.kind === 'draft') {

package/lib/bundle-limits.js

@@ -0,0 +1,10 @@
+'use strict';
+/**
+ * HC-GF-390: the leaf home of the bundle's per-file cap. run-context.js windows a file whose text is
+ * longer than this (bundle-paths.js `planFileExcerpt`: `text.length <= limit` is sent whole), and
+ * review-diff.js diffs exactly the files a reviewer saw only windows of, so both read it from here.
+ * run-context.js re-exports it under the same name for the tests that import it from there.
+ */
+const BUNDLE_MAX_PER_FILE_CHARS = 25_000;
+
+module.exports = { BUNDLE_MAX_PER_FILE_CHARS };

package/lib/call-sites.js

@@ -73,9 +73,22 @@ const SCOPE = 'tracked-repo';
 
 // The caps. server/src/services/call-sites.js accepts at least these (pinned by a cross-package test): a server
 // that took less would quietly turn a complete list into an incomplete one.
-const MAX_SYMBOLS = 6;
-/** Secret-looking names are reported, not searched; they take no slot of the 6 but are reported up to this many. */
+// HC-GF-385: 16, up from 6. Six slots spent on string keys (`step_0b`, `config`) left the functions a story changes
+// NOT SEARCHED and hard-stopped step_1 four times on one story. The wire budget is held by MAX_TOTAL_HITS, not by
+// the symbol count: a symbol past it is sent as its per-file list (FILES ONLY), so 16 costs what 6 did.
+const MAX_SYMBOLS = 16;
+/** Secret-looking names are reported, not searched; they take no slot of the 16 but are reported up to this many. */
 const MAX_REFUSED = 2;
+/**
+ * HC-GF-385: the hit lines ALL symbols together may send, spent in rank order: today's 6 x 40, so the 448 KiB
+ * per-story wire budget (server/src/lib/batch-body-limit.js) and its test keep their meaning. A symbol reached after
+ * it is spent sends `hits: []` plus its per-file list.
+ */
+const MAX_TOTAL_HITS = 240;
+/** HC-GF-385: the definition probe ranks at most this many candidates, best-ranked first. */
+const MAX_PROBE_CANDIDATES = 32;
+/** HC-GF-385: the probe's own share of TOTAL_BUDGET_MS; past it the story's own order is kept, and said. */
+const PROBE_TIMEOUT_MS = 8_000;
 /** Past MAX_HITS_PER_SYMBOL a symbol also carries a per-file list (path + hit count), up to this many files... */
 const MAX_FILE_LIST_FILES = 300;
 /** ...and all the symbols' file lists together stay under this many bytes of JSON (server/src/lib/batch-body-limit.js budgets it). */
@@ -97,7 +110,38 @@ const PROSE_EXTENSIONS = Object.freeze(['md', 'mdx', 'markdown', 'rst', 'adoc',
 
 // ── Choosing the symbols ────────────────────────────────────────────────────────────────────────
 
-const BACKTICKED = /`([^`\n]{2,200})`/g;
+// Backticked spans are PAIRED first, by the CommonMark rule, and the 2-to-200 rule is applied to each paired span afterwards.
+// A bound INSIDE a regex decides which backticks pair: at `x`, and `foo` the opening backtick of `x` cannot start a 2-character
+// match, so its closing one does, the "span" is `, and`, and `foo` is lost (measured 2026-10-10 over the roadmap rows: 68 of 939
+// extracted a wrong span set). A plain /`([^`\n]*)`/ fixed that and made the next one: after a run of TWO OR MORE backticks
+// (a ``double`` span, an inline ```fence) the pairing never recovered for the rest of the line, and 7 rows lost symbols the old
+// pattern found. The rule that has no such failure is the one Markdown itself uses: a run of N backticks opens a span that the
+// next run of EXACTLY N backticks closes, and a run with no such closer is literal text. Per line (a span does not cross a
+// newline here, as before). Linear: the next run of the same length is computed once per run, not searched for.
+// The same defect as BACKTICKED_RE in bundle-paths.js (HC-GF-188-followup-2), which has the first fix only.
+function backtickedSpans(text) {
+  const spans = [];
+  for (const line of String(text || '').split('\n')) {
+    if (!line.includes('`')) continue;
+    const runs = [];
+    for (const m of line.matchAll(/`+/g)) runs.push({ at: m.index, len: m[0].length });
+    const nextSame = new Array(runs.length).fill(-1);
+    const lastOfLen = new Map();
+    for (let i = runs.length - 1; i >= 0; i--) {
+      nextSame[i] = lastOfLen.has(runs[i].len) ? lastOfLen.get(runs[i].len) : -1;
+      lastOfLen.set(runs[i].len, i);
+    }
+    for (let i = 0; i < runs.length; i++) {
+      const j = nextSame[i];
+      if (j < 0) continue; // no closer of this length: the run is literal text
+      let span = line.slice(runs[i].at + runs[i].len, runs[j].at);
+      if (span.length > 2 && span.startsWith(' ') && span.endsWith(' ') && /[^ ]/.test(span)) span = span.slice(1, -1); // CommonMark: one space each side
+      spans.push(span);
+      i = j; // resume after the closer; the runs between are inside the span
+    }
+  }
+  return spans;
+}
 // One identifier, optionally qualified (`a.b`, `A::b`, `a->b`, `A#b`) and optionally called (`f()`, `f(x)`). The LAST
 // segment is the symbol: `this.ensureConnected` is a reference to `ensureConnected` wherever it is called from.
 // Group 1 is the qualifier (empty when there is none), 2 the name, 3 the call's parentheses (undefined when not called).
@@ -158,25 +202,129 @@ function symbolOfSpan(span) {
  * @returns {{symbols: string[], omitted: string[], omittedTotal: number, refused: string[]}}
  */
 function pickSymbols(storyText, { max = MAX_SYMBOLS } = {}) {
+  const { ranked, refusedAll } = rankCandidates(storyText);
+  return sliceRanked(ranked.map((c) => c.name), refusedAll, max);
+}
+
+/**
+ * Every candidate the story names, in the story's order (explicitly written first, then by how often it is named,
+ * ties in the order first named), with the facts that order was made from. Secret-looking names are split off.
+ * Synchronous and text-only: `pickSymbols` keeps that contract for callers this file cannot see (HC-GF-385).
+ * @returns {{ranked: Array<{name: string, explicit: boolean, count: number}>, refusedAll: string[]}}
+ */
+function rankCandidates(storyText) {
   const counts = new Map();
   const explicitNames = new Set();
-  for (const m of String(storyText || '').matchAll(BACKTICKED)) {
-    const sym = symbolOfSpan(m[1]);
+  for (const span of backtickedSpans(storyText)) {
+    if (span.length < 2 || span.length > 200) continue; // the length rule, after pairing
+    const sym = symbolOfSpan(span);
     if (!sym) continue;
     counts.set(sym.name, (counts.get(sym.name) || 0) + 1);
     if (sym.explicit) explicitNames.add(sym.name);
   }
   // Array.prototype.sort is stable (ES2019), and a Map iterates in insertion order: ties keep the order the story first names them.
   const all = [...counts.keys()].sort((a, b) => (explicitNames.has(b) - explicitNames.has(a)) || (counts.get(b) - counts.get(a)));
-  const refusedAll = all.filter((n) => SECRET_NAME.test(n));
-  const ranked = all.filter((n) => !SECRET_NAME.test(n));
-  const refused = refusedAll.slice(0, MAX_REFUSED);
-  const beyond = [...ranked.slice(max), ...refusedAll.slice(MAX_REFUSED)];
   return {
-    symbols: ranked.slice(0, max),
+    ranked: all.filter((n) => !SECRET_NAME.test(n)).map((name) => ({ name, explicit: explicitNames.has(name), count: counts.get(name) })),
+    refusedAll: all.filter((n) => SECRET_NAME.test(n)),
+  };
+}
+
+/** The first `max` names are searched; the rest, and the refused names past MAX_REFUSED, are reported as omitted. */
+function sliceRanked(names, refusedAll, max) {
+  const beyond = [...names.slice(max), ...refusedAll.slice(MAX_REFUSED)];
+  return {
+    symbols: names.slice(0, max),
     omitted: beyond.slice(0, MAX_OMITTED_NAMES),
     omittedTotal: beyond.length,
-    refused,
+    refused: refusedAll.slice(0, MAX_REFUSED),
+  };
+}
+
+// ── Ranking by definition (HC-GF-385) ───────────────────────────────────────────────────────────
+
+/** Files whose matches never define code: documentation, and data formats (an object or YAML key is not a symbol). */
+const DATA_EXTENSIONS = Object.freeze(['json', 'jsonc', 'json5', 'yaml', 'yml', 'toml', 'lock', 'csv', 'tsv', 'xml', 'ini', 'env', 'properties']);
+/** A word before `name(` that makes it a call or an expression, never a C-family definition. */
+const NOT_A_RETURN_TYPE = new Set(['return', 'await', 'new', 'throw', 'yield', 'else', 'case', 'typeof', 'delete', 'void', 'in', 'of', 'do',
+  'if', 'while', 'for', 'switch', 'catch', 'and', 'or', 'not', 'is', 'as', 'echo', 'print', 'puts', 'go', 'defer', 'export', 'default']);
+
+/**
+ * How strongly one line defines `name`: 2 for a function, method, class or type; 1 for a top-level or exported
+ * constant or variable; 0 for anything else (a call, a key, a mention). Language-neutral patterns, covering
+ * JavaScript and TypeScript, Python, Go, Ruby, Java and the C family, and `fn`/`fun`/`func` (Rust, Kotlin, Swift).
+ * `name` is an identifier ([A-Za-z0-9_]), so it is safe inside a RegExp.
+ * @param {string} line
+ * @param {string} name
+ * @returns {0|1|2}
+ */
+function definitionTier(line, name) {
+  const n = `${name}(?![A-Za-z0-9_$])`;
+  const t = String(line);
+  // A keyword that introduces a definition: `function f`, `class C`, `def f`, `def self.f`, `func (r *T) f`, `fn f`, `fun f`.
+  if (new RegExp(`(?:^|[^A-Za-z0-9_$.])(?:function\\*?|class|def|func|fn|fun|interface|enum|struct|trait|type|module|record|protocol)\\s+(?:self\\.)?(?:\\([^)]*\\)\\s*)?${n}`).test(t)) return 2;
+  // A function value bound at top level or exported: `export const f = async (a) =>`, `const f = function`.
+  if (new RegExp(`^(?:export\\s+)?(?:const|let|var)\\s+${n}\\s*=\\s*(?:async\\b\\s*)?(?:function\\b|\\([^)]*\\)\\s*=>|[A-Za-z_$][A-Za-z0-9_$]*\\s*=>)`).test(t)) return 2;
+  // A method, in a class body or an object literal: `  async f(a, b) {`, `  static get f() {`.
+  if (new RegExp(`^\\s*(?:(?:static|async|get|set|public|private|protected|readonly|override|abstract|final)\\s+)*${n}\\s*\\([^)]*\\)\\s*(?::\\s*[^={;]+)?\\{`).test(t)) return 2;
+  // A C-family signature: one or more type words, then `name(`, and no `;` (a prototype or a call statement).
+  const sig = new RegExp(`^\\s*((?:[A-Za-z_][A-Za-z0-9_<>\\[\\],:*&?]*\\s+)+)\\*?${n}\\s*\\([^;]*$`).exec(t);
+  if (sig) {
+    const words = sig[1].trim().split(/\s+/);
+    if (!NOT_A_RETURN_TYPE.has(words[words.length - 1])) return 2;
+  }
+  // A top-level or exported binding of anything else: `const f =`, `export let f`, `module.exports.f =`, Go `var f`.
+  if (new RegExp(`^(?:export\\s+)?(?:const|let|var|val)\\s+${n}`).test(t)) return 1;
+  if (new RegExp(`^(?:module\\.)?exports\\.${n}\\s*=`).test(t)) return 1;
+  // Python and Ruby top-level assignment: `f = ...` at column 0, not `f == x`.
+  if (new RegExp(`^${n}\\s*=(?!=)`).test(t)) return 1;
+  return 0;
+}
+
+/**
+ * Rank candidates by whether the repository defines them, with ONE batched `git grep -F -w` over all of them.
+ * Functions, methods, classes and types come first, then top-level or exported constants, then names with no
+ * definition (string keys, config fields, words). Within a tier the story's own order holds. Any failure, timeout
+ * or output this cannot read keeps the story's order, and the note says so: a probe never empties the search.
+ * @param {Array<{name: string}>} ranked  the story's order
+ * @returns {Promise<{ranked: Array<{name: string}>, fallback: string|null, undefinedNames: string[]}>}
+ */
+async function rankByDefinition(ranked, { run, realPath }) {
+  if (ranked.length === 0) return { ranked, fallback: null, undefinedNames: [] };
+  const probed = ranked.slice(0, MAX_PROBE_CANDIDATES);
+  const argv = ['grep', '-n', '-z', '-w', '-F', '-I', '--no-color', '--no-recurse-submodules'];
+  for (const c of probed) argv.push('-e', c.name);
+  let r;
+  try { r = await run(argv, { timeoutMs: PROBE_TIMEOUT_MS }); } catch { r = { failure: 'the probe could not be run' }; }
+  const problem = grepProblem(r || {});
+  if (problem) return { ranked, fallback: `the definition probe gave no answer (${problem}), so the story's own order was used`, undefinedNames: [] };
+  const lines = r.status === 1 ? [] : parseGrepOutput(r.stdout);
+  if (lines === null) return { ranked, fallback: 'the definition probe printed output that could not be read, so the story\'s own order was used', undefinedNames: [] };
+
+  const tier = new Map(probed.map((c) => [c.name, 0]));
+  const kinds = new Map();
+  const wordRe = /[A-Za-z_$][A-Za-z0-9_$]*/g;
+  for (const hit of lines) {
+    let kind = kinds.get(hit.path);
+    if (kind === undefined) {
+      const ext = path.posix.extname(hit.path).slice(1).toLowerCase();
+      kind = DATA_EXTENSIONS.includes(ext) ? 'data' : classifyPath(hit.path, realPath);
+      kinds.set(hit.path, kind);
+    }
+    if (kind !== 'ok') continue; // documentation, data and withheld paths define nothing here
+    for (const w of new Set(String(hit.text).match(wordRe) || [])) {
+      if (!tier.has(w) || tier.get(w) === 2) continue;
+      const d = definitionTier(hit.text, w);
+      if (d > tier.get(w)) tier.set(w, d);
+    }
+  }
+  // Stable: within a tier the story's order is kept. Candidates past the probe cap keep their place after the probed.
+  const order = probed.map((c, i) => ({ c, i, t: tier.get(c.name) }))
+    .sort((a, b) => (b.t - a.t) || (a.i - b.i)).map((x) => x.c);
+  return {
+    ranked: [...order, ...ranked.slice(MAX_PROBE_CANDIDATES)],
+    fallback: null,
+    undefinedNames: probed.filter((c) => tier.get(c.name) === 0).map((c) => c.name),
   };
 }
 
@@ -288,7 +436,7 @@ function parseFileList(out) {
  *  - 'not_searched': no answer, and `reason` says why. Never to be read as "no callers".
  * `binary` is how many files match only when git's binary-file skip (-I) is off; they cannot be listed.
  */
-async function searchSymbol(symbol, { run, realPath }) {
+async function searchSymbol(symbol, { run, realPath, maxHits = MAX_HITS_PER_SYMBOL }) {
   // Defence in depth: pickSymbols only yields identifiers, but this is exported, and the symbol reaches an argv and a RegExp.
   if (typeof symbol !== 'string' || !/^[A-Za-z0-9_]+$/.test(symbol)) {
     return { symbol: String(symbol).slice(0, 80), status: 'not_searched', reason: 'not an identifier' };
@@ -323,7 +471,9 @@ async function searchSymbol(symbol, { run, realPath }) {
     else sendable.push(hit);
   }
   const total = sendable.length + withheld;
-  const hits = sendable.slice(0, MAX_HITS_PER_SYMBOL).map((h) => ({ path: h.path, line: h.line, text: lineText(h.text, symbol) }));
+  // HC-GF-385: `maxHits` is what is left of the story's MAX_TOTAL_HITS (0 once it is spent), never more than the per-symbol cap.
+  const cap = Math.max(0, Math.min(MAX_HITS_PER_SYMBOL, Number.isSafeInteger(maxHits) ? maxHits : MAX_HITS_PER_SYMBOL));
+  const hits = sendable.slice(0, cap).map((h) => ({ path: h.path, line: h.line, text: lineText(h.text, symbol) }));
   const perFile = new Map();
   for (const h of sendable) perFile.set(h.path, (perFile.get(h.path) || 0) + 1);
   const entry = {
@@ -336,7 +486,10 @@ async function searchSymbol(symbol, { run, realPath }) {
     binary,
     hits,
   };
-  if (sendable.length > MAX_HITS_PER_SYMBOL) {
+  // HC-GF-385: every searched symbol with a sendable hit carries its per-file list, not only one past the hit cap.
+  // A symbol cut by the total-hit budget needs it to be FILES ONLY, and a whole symbol whose hit lines the server's
+  // render budget drops needs it to stay an enumeration at file level.
+  if (sendable.length > 0) {
     const all = [...perFile].map(([p, n]) => ({ path: p, hits: n }));
     entry.file_list = all.slice(0, MAX_FILE_LIST_FILES);
     entry.file_list_complete = all.length <= MAX_FILE_LIST_FILES;
@@ -344,11 +497,17 @@ async function searchSymbol(symbol, { run, realPath }) {
   return entry;
 }
 
-/** Keep the symbols' file lists inside MAX_FILE_LIST_BYTES together; a list that is cut says so. */
+/**
+ * Keep the symbols' file lists inside MAX_FILE_LIST_BYTES together; a list that is cut says so.
+ * HC-GF-385: the bytes go first to the symbols whose hit lines were cut (by the per-symbol cap or the total-hit
+ * budget), in rank order, because for them the list IS the enumeration; then to the rest, in rank order. Spent
+ * in plain rank order, whole symbols at the top starved the FILES ONLY ones below them into INCOMPLETE.
+ */
 function fitFileLists(symbols) {
   let room = MAX_FILE_LIST_BYTES;
-  for (const s of symbols) {
-    if (!s.file_list) continue;
+  const cut = (s) => Array.isArray(s.hits) && Number.isSafeInteger(s.total) && s.hits.length < s.total - (s.withheld || 0);
+  const ordered = [...symbols.filter((s) => s.file_list && cut(s)), ...symbols.filter((s) => s.file_list && !cut(s))];
+  for (const s of ordered) {
     const kept = [];
     for (const f of s.file_list) {
       const size = Buffer.byteLength(JSON.stringify(f), 'utf8') + 1;
@@ -379,8 +538,9 @@ const warn = (text) => ({ level: 'warn', text });
  */
 async function collectCallSites({ cwd, storyText, run, realPath, now = Date.now, maxSymbols = MAX_SYMBOLS }) {
   const notes = [];
-  const picked = pickSymbols(storyText, { max: maxSymbols });
-  if (picked.symbols.length === 0 && picked.refused.length === 0) return { callSites: null, notes };
+  const { ranked: storyOrder, refusedAll } = rankCandidates(storyText);
+  // The early return comes BEFORE the probe: a story that names nothing searchable runs no git at all.
+  if (storyOrder.length === 0 && refusedAll.length === 0) return { callSites: null, notes };
 
   // From the repository's top level, wherever `hone` ran: `git grep` from a subdirectory searches only that subtree.
   let root = cwd;
@@ -389,17 +549,24 @@ async function collectCallSites({ cwd, storyText, run, realPath, now = Date.now,
     const dir = top.failure || top.status !== 0 ? '' : top.stdout.trim();
     if (dir) root = dir;
   }
-  const git = run || ((argv) => runGit(argv, { cwd: root }));
+  const git = run || ((argv, opts = {}) => runGit(argv, { cwd: root, ...opts }));
   const real = realPath || ((rel) => repoRealPath(root, rel));
   const commit = await headCommit(git);
-  const symbols = [];
+  // HC-GF-385: the clock starts before the probe, so the probe's time comes out of the same TOTAL_BUDGET_MS.
   const started = now();
+  // Rank BEFORE the slice and compute what was omitted AFTER it, or the functions never reach the slice.
+  const probe = await rankByDefinition(storyOrder, { run: git, realPath: real });
+  const picked = sliceRanked(probe.ranked.map((c) => c.name), refusedAll, maxSymbols);
+  const symbols = [];
+  let hitsLeft = MAX_TOTAL_HITS;
   for (const symbol of picked.symbols) {
     if (now() - started > TOTAL_BUDGET_MS) {
       symbols.push({ symbol, status: 'not_searched', reason: `the ${TOTAL_BUDGET_MS / 1000}s search budget for this story was spent on earlier symbols` });
       continue;
     }
-    symbols.push(await searchSymbol(symbol, { run: git, realPath: real }));
+    const entry = await searchSymbol(symbol, { run: git, realPath: real, maxHits: hitsLeft });
+    if (Array.isArray(entry.hits)) hitsLeft = Math.max(0, hitsLeft - entry.hits.length);
+    symbols.push(entry);
   }
   for (const symbol of picked.refused) symbols.push({ symbol, status: 'not_searched', reason: SECRET_REASON });
   fitFileLists(symbols);
@@ -413,12 +580,17 @@ async function collectCallSites({ cwd, storyText, run, realPath, now = Date.now,
     omitted: picked.omitted,
     omitted_total: picked.omittedTotal,
   };
-  notes.push(...describeCallSites(callSites));
+  if (probe.fallback) notes.push(warn(`  ⚠ call sites: ${probe.fallback}`));
+  const searchedUndefined = probe.undefinedNames.filter((n) => picked.symbols.includes(n));
+  if (!probe.fallback && searchedUndefined.length > 0) {
+    notes.push(info(`     no definition found for ${searchedUndefined.join(', ')} (ranked after defined code; it may be a key, a field, or one this story creates)`));
+  }
+  notes.push(...describeCallSites(callSites, { maxSymbols }));
   return { callSites, notes };
 }
 
 /** The operator's lines for a result: one info line per symbol that is whole, a warning for each that is not. */
-function describeCallSites(callSites) {
+function describeCallSites(callSites, { maxSymbols = MAX_SYMBOLS } = {}) {
   const notes = [];
   const where = callSites.commit ? `tracked files at ${callSites.commit.slice(0, 12)}` : 'tracked files (commit unknown)';
   notes.push(info(`  → call sites: searched ${callSites.symbols.length} symbol(s) the story names, in ${where}`));
@@ -437,7 +609,10 @@ function describeCallSites(callSites) {
       binary ? `${binary} binary file${binary === 1 ? '' : 's'} match and cannot be listed` : '',
     ].filter(Boolean).join('; ');
     const fileLevel = s.status === 'incomplete' && binary === 0 && s.file_list_complete === true && Array.isArray(s.file_list);
-    if (s.status === 'incomplete' && fileLevel) {
+    if (s.status === 'incomplete' && fileLevel && s.hits.length === 0) {
+      // HC-GF-385: reached after the total-hit budget was spent. The server renders it FILES ONLY.
+      notes.push(info(`     ${s.symbol}: FILES ONLY — ${listable} hits in ${s.files} file${s.files === 1 ? '' : 's'}; every file with a hit is named with its count, individual lines not sent (the ${MAX_TOTAL_HITS}-hit budget was spent on higher-ranked symbols)${s.withheld ? `; EXCEPT ${s.withheld} hit${s.withheld === 1 ? '' : 's'} in withheld paths the planner cannot see` : ''}${s.prose ? `; ${s.prose} more in documentation` : ''}`));
+    } else if (s.status === 'incomplete' && fileLevel) {
       notes.push(info(`     ${s.symbol}: COMPLETE AT FILE LEVEL — ${listable} hits in ${s.files} file${s.files === 1 ? '' : 's'}; the first ${s.hits.length} are listed and every file with a hit is named with its count${s.withheld ? `; EXCEPT ${s.withheld} hit${s.withheld === 1 ? '' : 's'} in withheld paths the planner cannot see` : ''}${s.prose ? `; ${s.prose} more in documentation` : ''}`));
     } else if (s.status === 'incomplete') {
       notes.push(warn(`  ⚠ call sites for ${s.symbol}: INCOMPLETE — ${s.hits.length} of ${listable} hits listed (cap ${MAX_HITS_PER_SYMBOL}${s.file_list ? `, ${s.file_list.length} of ${s.files} files named` : ''}); the planner cannot claim an enumeration${extra ? ` (${extra})` : ''}`));
@@ -454,16 +629,21 @@ function describeCallSites(callSites) {
   const omittedTotal = callSites.omitted_total || 0;
   if (omittedTotal > 0) {
     const shown = callSites.omitted.join(', ') + (omittedTotal > callSites.omitted.length ? ', …' : '');
-    notes.push(warn(`  ⚠ call sites: the story names ${omittedTotal} more compound identifier(s) beyond the ${MAX_SYMBOLS}-symbol cap — NOT SEARCHED: ${shown}`));
+    notes.push(warn(`  ⚠ call sites: the story names ${omittedTotal} more compound identifier(s) beyond the ${maxSymbols}-symbol cap — NOT SEARCHED: ${shown}`));
   }
   return notes;
 }
 
 module.exports = {
+  backtickedSpans,
   CALL_SITES_VERSION,
   SCOPE,
   MAX_SYMBOLS,
   MAX_REFUSED,
+  MAX_TOTAL_HITS,
+  MAX_PROBE_CANDIDATES,
+  PROBE_TIMEOUT_MS,
+  DATA_EXTENSIONS,
   MAX_FILE_LIST_FILES,
   MAX_FILE_LIST_BYTES,
   SECRET_NAME,
@@ -478,6 +658,9 @@ module.exports = {
   MAX_OUTPUT_BYTES,
   isCompoundIdentifier,
   pickSymbols,
+  rankCandidates,
+  definitionTier,
+  rankByDefinition,
   fitFileLists,
   runGit,
   parseGrepOutput,

package/lib/context-reserve.js

@@ -208,21 +208,24 @@ function batchIdFromQueueOutput(stdout) {
  * status, created_at, error_message), newest first.
  *  - `later`: a run of the story in this repository, created AFTER the paused one and not killed. A re-serve that
  *    queued but whose kill failed, or that died between the two, leaves exactly this and no marker.
- *  - `earlier`: a run of the story killed with `re-served as batch <id>` BEFORE this one, so this run is that
- *    re-serve (the loop was started on the new batch alone) and a second pause here is the second.
- *  - `unknown`: the paused run's creation time is not a date, so neither can be told.
- * @returns {{kind: 'later'|'earlier'|'unknown', runId?: string, batchId?: string}|null}
+ *  - `earlier`: a run of the story, older than this one, killed with `re-served as batch <id>` where <id> is the batch
+ *    THIS run is in (`batchId`): this run is that re-serve (the loop was started on the new batch alone), and a second
+ *    pause here is the second. A story re-served into some OTHER batch, however long ago, is history and not this
+ *    run's lineage: it neither blocks nor justifies anything (HC-GF-351-followup-1).
+ *  - `unknown`: the paused run's creation time is not a date or its batch id is not one, so neither can be told.
+ * @returns {{kind: 'later'|'earlier'|'unknown', runId?: string, batchId?: string, why?: string}|null}
  */
-function serveHistory(rows, { runId, storyId, repoName, since }) {
+function serveHistory(rows, { runId, storyId, repoName, since, batchId: ownBatch }) {
   const t0 = Date.parse(since);
-  if (!Number.isFinite(t0)) return { kind: 'unknown' };
+  if (!Number.isFinite(t0)) return { kind: 'unknown', why: 'its creation time is not known' };
+  if (!isBatchId(ownBatch)) return { kind: 'unknown', why: 'the batch it is in is not known' };
   for (const row of Array.isArray(rows) ? rows : []) {
     if (!row || row.id === runId || row.story_id !== storyId || row.repo_name !== repoName) continue;
     const t = Date.parse(row.created_at);
     if (!Number.isFinite(t)) continue;
     if (t > t0 && row.status !== 'killed') return { kind: 'later', runId: row.id };
-    const batchId = t < t0 ? reservedBatchOf({ status: row.status, errorMessage: row.error_message }) : null;
-    if (batchId) return { kind: 'earlier', runId: row.id, batchId };
+    const reserved = t < t0 ? reservedBatchOf({ status: row.status, errorMessage: row.error_message }) : null;
+    if (reserved && reserved === ownBatch) return { kind: 'earlier', runId: row.id, batchId: reserved };
   }
   return null;
 }

package/lib/operator-question.js

@@ -27,10 +27,15 @@
 // U+061C ARABIC LETTER MARK is the third bidi mark beside LRM/RLM (review round 3 F3). Written as
 // \u escapes: a literal bidi character in this source would reorder how THIS file reads.
 // eslint-disable-next-line no-control-regex -- the whole point is to match control chars.
-const TERMINAL_UNSAFE_RE = /[\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
-
+const TERMINAL_UNSAFE_RE = /[\x00-\x1f\x7f-\x9f\u00ad\u061c\u180e\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff\u{e0000}-\u{e007f}]/gu;
+// A line break or tab is a space, so two words do not join; the characters above draw nothing yet change what a reader sees
+// (zero-width, soft hyphen, BOM, the Unicode tag block); a lone surrogate is not a character a terminal or JSON can carry.
+// Mirrors server/src/services/architect-consult.js scrubForTerminal: the two packages cannot share code, and a test pins them equal.
 function scrub(text) {
-  return String(text == null ? '' : text).replace(TERMINAL_UNSAFE_RE, '');
+  return String(text == null ? '' : text)
+    .replace(/[\t\n\v\f\r\u0085\u2028\u2029]+/g, ' ')
+    .replace(TERMINAL_UNSAFE_RE, '')
+    .replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, '\ufffd');
 }
 
 /**
@@ -91,4 +96,4 @@ function gateQuestionLines(status, stepKey) {
   ];
 }
 
-module.exports = { normalizeQuestion, questionLines, gateQuestionLines, countPhrase };
+module.exports = { normalizeQuestion, questionLines, gateQuestionLines, countPhrase, scrub };

package/lib/review-diff.js

@@ -0,0 +1,188 @@
+'use strict';
+/**
+ * review-diff.js — HC-GF-390: the base diff a reviewer needs beside a whole emitted file.
+ *
+ * In editor mode step_4's artifact carries every changed file whole (tree-artifact.js), while the
+ * reviewers (step_5, 5d, 5e) see the ORIGINAL only through the bundle, which windows a file longer
+ * than BUNDLE_MAX_PER_FILE_CHARS. A change outside those windows was compared with nothing. This
+ * computes, for step_4 only, `git diff HEAD` of each file the render emitted whole whose HEAD version
+ * is over that cap. It is sent beside the artifact as `reviewDiff` and stored apart from it: the
+ * artifact itself is never touched.
+ *
+ * It never fails a submit. Every git call has a timeout; anything it cannot do becomes a one-line
+ * note, and a note means "unverified", exactly as an absent diff did before.
+ *
+ * Exit modes of what it consumes (HC-GF-117):
+ *   rendered.files            HANDLED: the only candidates. A created, deleted, renamed, binary-at-render
+ *                             or over-1 MB file is never in it, so it is never diffed.
+ *   git rev-parse fails       HANDLED: no HEAD → null, nothing sent.
+ *   git diff --name-status    HANDLED: a throw → one note, nothing diffed.
+ *   per-file git calls        HANDLED: a throw (timeout, ENOBUFS, spawn, non-zero) → a note, next file.
+ *   "Binary files … differ"   HANDLED: a note (a text file .gitattributes marks binary).
+ *   empty diff                HANDLED: a note (the file no longer differs from HEAD).
+ *   post-image ≠ rendered     HANDLED: a note. The diff must describe the bytes the reviewer was sent.
+ */
+
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const { gitEnv } = require('./git-env');
+const { BUNDLE_MAX_PER_FILE_CHARS } = require('./bundle-limits');
+const { isSecretPath } = require('./bundle-context');
+const { FILE_BLOCK_RE } = require('./block-grammar');
+
+const REVIEW_DIFF_MAX_CHARS = 60_000;      // diff text, summed over the files included
+const PER_CALL_MS = 15_000;
+const DEADLINE_MS = 60_000;                // every per-file call gets min(PER_CALL_MS, what is left)
+const MAX_NOTES = 100;
+const MAX_NOTE_CHARS = 300;
+// Kept equal to server/src/services/review-diff.js REVIEW_DIFF_MAX_BYTES (pinned by the HC-GF-390 tests).
+const REVIEW_DIFF_MAX_BYTES = 256 * 1024;
+
+const SHA_RE = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+
+/** The bundle windows a file whose text is longer than the cap (bundle-paths.js `text.length <= limit` is whole). */
+const overCap = (length) => length > BUNDLE_MAX_PER_FILE_CHARS;
+
+/**
+ * The pinned diff. Every option a user's git config could change is given on the command line, as a
+ * flag the `diff` subcommand takes (not a leading `-c`, so a caller can still recognise the call).
+ */
+function diffArgs(headSha, rel) {
+  return ['diff', '--no-color', '--no-ext-diff', '--no-textconv', '--no-renames', '--full-index',
+    '--diff-algorithm=myers', '--no-relative', '--inter-hunk-context=0', '-U3',
+    '--src-prefix=a/', '--dst-prefix=b/', headSha, '--', rel];
+}
+
+function defaultRunGit(repoRoot) {
+  return (args, timeoutMs) => execFileSync('git', args, {
+    cwd: repoRoot, env: gitEnv(), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+    timeout: Math.max(1, Math.floor(timeoutMs)), stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * The contents of the first `file:` block for `rel` in a rendered artifact, as the server's
+ * carry-forward `blocksOf` reads it (same grammar, same scope, same one-newline strip), or null.
+ */
+function blockContents(text, rel) {
+  const t = String(text || '');
+  const sec = t.search(/^##\s+Changed Files/im);
+  const scope = t.slice(sec === -1 ? 0 : sec);
+  for (const m of scope.matchAll(FILE_BLOCK_RE)) {
+    if (m[2].trim() === rel) return m[3].replace(/\r?\n$/, '');
+  }
+  return null;
+}
+
+/** git's object id of a blob holding `str` as UTF-8, computed in memory (never `hash-object -w`). */
+function gitBlobId(str, algo = 'sha1') {
+  const bytes = Buffer.from(String(str), 'utf8');
+  return crypto.createHash(algo).update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+}
+
+/** One line, no control characters, at most `max` chars. */
+function oneLine(s, max) {
+  const flat = String(s == null ? '' : s).replace(/[\x00-\x1f\x7f]+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/**
+ * @param {object}   opts
+ * @param {string}   opts.repoRoot
+ * @param {{text: string, files: string[]}} opts.rendered  renderFromTree()'s result
+ * @param {(args: string[], timeoutMs: number) => string} [opts.runGit]
+ * @param {() => number} [opts.now]
+ * @param {(line: string) => void} [opts.warn]  why nothing is sent when that is not "no candidate"
+ * @returns {null | { headSha: string, diff: string, notes: string[], stats: object }}
+ *   null when there is nothing to send: no HEAD, no candidate, or a payload over its byte cap.
+ */
+function computeReviewDiff({ repoRoot, rendered, runGit, now = Date.now, warn = () => {} } = {}) {
+  try {
+    const git = runGit || defaultRunGit(repoRoot);
+    const emitted = new Set(rendered && Array.isArray(rendered.files) ? rendered.files : []);
+    if (!emitted.size) return null;
+
+    const deadline = now() + DEADLINE_MS;
+    let headSha;
+    try { headSha = String(git(['rev-parse', '--verify', 'HEAD^{commit}'], PER_CALL_MS)).trim(); } catch { return null; }
+    if (!SHA_RE.test(headSha)) return null;
+    const algo = headSha.length === 64 ? 'sha256' : 'sha1';
+
+    const notes = [];
+    const sections = [];
+    let used = 0;
+    const note = (rel, reason) => notes.push(oneLine(`${JSON.stringify(rel)}: ${reason}`, MAX_NOTE_CHARS));
+
+    let candidates = [];
+    try {
+      const tokens = String(git(['diff', '--name-status', '-z', '--no-renames', headSha], PER_CALL_MS)).split('\0');
+      for (let i = 0; i + 1 < tokens.length; i += 2) {
+        const status = tokens[i]; const rel = tokens[i + 1];
+        if ((status === 'M' || status === 'T') && emitted.has(rel)) candidates.push(rel);
+      }
+      candidates = [...new Set(candidates)].sort();
+    } catch (e) {
+      notes.push(oneLine(`(all files): git failed listing changes against HEAD: ${e && e.message}`, MAX_NOTE_CHARS));
+    }
+
+    for (let i = 0; i < candidates.length; i++) {
+      const rel = candidates[i];
+      const left = () => Math.min(PER_CALL_MS, deadline - now());
+      let t = left();
+      if (t <= 0) { notes.push(`deadline reached; ${candidates.length - i} file(s) not diffed`); break; }
+      try {
+        // The size first: it reads no content, and a file at or under the cap was bundled whole.
+        // UTF-8 bytes >= UTF-16 length, so a size at or under the cap cannot be a length over it.
+        const size = Number(String(git(['cat-file', '-s', `${headSha}:${rel}`], t)).trim());
+        if (!Number.isFinite(size) || !overCap(size)) continue;
+        if (isSecretPath(rel)) { note(rel, 'secret path; not diffed'); continue; }
+        t = left();
+        if (t <= 0) { notes.push(`deadline reached; ${candidates.length - i} file(s) not diffed`); break; }
+        const head = String(git(['cat-file', 'blob', `${headSha}:${rel}`], t));
+        if (!overCap(head.length)) continue;
+        t = left();
+        if (t <= 0) { notes.push(`deadline reached; ${candidates.length - i} file(s) not diffed`); break; }
+        const out = String(git(diffArgs(headSha, rel), t));
+        if (!out.trim()) { note(rel, 'no longer differs from HEAD; not diffed'); continue; }
+        if (/^Binary files .* differ$/m.test(out) || /^GIT binary patch$/m.test(out)) { note(rel, 'binary to git; not diffed'); continue; }
+        if ((out.match(/^diff --git /gm) || []).length !== 1) { note(rel, 'unexpected diff shape; not included'); continue; }
+        const post = /^index [0-9a-f]+\.\.([0-9a-f]+)(?: [0-7]+)?$/m.exec(out);
+        const contents = blockContents(rendered.text, rel);
+        if (!post || contents === null || post[1] !== gitBlobId(`${contents}\n`, algo)) {
+          note(rel, 'post-image differs from the rendered bytes (an eol or clean filter, no final newline, '
+            + 'non-UTF-8 content, or a change after render); not included');
+          continue;
+        }
+        const section = out.endsWith('\n') ? out : `${out}\n`;
+        if (used + section.length > REVIEW_DIFF_MAX_CHARS) {
+          note(rel, `over the ${REVIEW_DIFF_MAX_CHARS.toLocaleString('en-US')}-char review-diff budget; not included`);
+          continue;
+        }
+        sections.push(section);
+        used += section.length;
+      } catch (e) {
+        note(rel, `git failed: ${oneLine(String((e && e.message) || e).split('\n')[0], 120)}`);
+      }
+    }
+
+    const kept = notes.length > MAX_NOTES
+      ? [...notes.slice(0, MAX_NOTES - 1), `${notes.length - (MAX_NOTES - 1)} more note(s) omitted`]
+      : notes;
+    if (!sections.length && !kept.length) return null;
+    const payload = { headSha, diff: sections.join(''), notes: kept };
+    const bytes = Buffer.byteLength(JSON.stringify(payload), 'utf8');
+    if (bytes > REVIEW_DIFF_MAX_BYTES) { warn(`review diff not sent: ${bytes} bytes is over the ${REVIEW_DIFF_MAX_BYTES}-byte limit`); return null; }
+    return { ...payload, stats: { candidates: candidates.length, files: sections.length, chars: used } };
+  } catch (e) {
+    warn(`review diff not sent: ${oneLine((e && e.message) || e, 200)}`);
+    return null;
+  }
+}
+
+/** Exactly what `hone submit-step` posts as `reviewDiff`: the stats stay CLI-side. One mapper, so a test can post what the CLI posts. */
+function toWire(r) { return { headSha: r.headSha, diff: r.diff, notes: r.notes }; }
+
+module.exports = {
+  computeReviewDiff, blockContents, gitBlobId, toWire,
+  _internal: { overCap, diffArgs, REVIEW_DIFF_MAX_CHARS, PER_CALL_MS, DEADLINE_MS, MAX_NOTES, MAX_NOTE_CHARS, REVIEW_DIFF_MAX_BYTES },
+};

package/lib/run-context.js

@@ -25,7 +25,6 @@
  */
 
 const { composeStoryDescription } = require('./story-compose');
-const { extractStoryIdFromBranch } = require('./pipeline-status');
 const {
   extractPathRefs, extractBareRefs, resolveBareName, alreadyCovered, planFileExcerpt,
 } = require('./bundle-paths');
@@ -37,7 +36,6 @@ const { classifyStory } = require('./story-classifier');
 const {
   extractType, extractSecurityImplications, extractCrossRepoDependency,
 } = require('./story-classifier-extract');
-const { readArchitectConfigFromText } = require('./architect-config');
 const path = require('path');
 
 /**
@@ -49,13 +47,16 @@ const path = require('path');
  */
 const SERVER_OWNED_KEYS = Object.freeze([
   'batchTokenBudget', 'batchFailureThreshold', 'dependsOnRunIds', 'monthlyTokenBudget', 'overnight',
+  // HC-GF-030: whether a story was consulted is what the server's step_0b recorded, never what a
+  // client says. A client that could send these true would skip the consult.
+  'architect_consulted', 'checklist_b_completed', 'architect_consult',
 ]);
 
 // HC-019n-followup-13d: the bundle caps. OptionsFlow #96 hit 49,783 of the old 50,000 with six
 // files, so the next slightly larger story silently dropped one. 30 / 150K / 25K.
 const BUNDLE_MAX_FILES = 30;
 const BUNDLE_MAX_TOTAL_CHARS = 150_000;
-const BUNDLE_MAX_PER_FILE_CHARS = 25_000;
+const { BUNDLE_MAX_PER_FILE_CHARS } = require('./bundle-limits'); // HC-GF-390: shared with review-diff.js
 
 const info = (text) => ({ level: 'info', text });
 const warn = (text) => ({ level: 'warn', text });
@@ -158,7 +159,6 @@ async function issueStorySource(io, issueNumber, issue) {
  * @param {() => string} io.e2eSpecMode
  * @param {() => string} io.verificationGate
  * @param {() => string[]} io.verificationGateSources
- * @param {() => string} io.readPlanText                 EXECUTION_PLAN.yml text, '' when absent
  * @param {{ e2eSpecs?: boolean, skipE2eSpecs?: boolean, treeByteCap?: number }} [opts]  run-story's per-run
  *   flags; `treeByteCap` is queue-stories' byte cap on the tree's path lists (none for run-story)
  */
@@ -295,13 +295,7 @@ function resolveRepoContext(io, opts = {}) {
     config.verification_gate_sources = ['verify-patch'];
   }
 
-  // HC-019b: EXECUTION_PLAN.yml, read once. Each story's architect flags come from it below.
-  let planText = '';
-  try { planText = io.readPlanText() || ''; } catch (e) {
-    notes.push(warn(`  ⚠ EXECUTION_PLAN.yml read failed (non-fatal, architect flags default to {false, false}): ${firstLine(e)}`));
-  }
-
-  return { config, notes, repoFiles, defaultIncludePaths, planText, execution };
+  return { config, notes, repoFiles, defaultIncludePaths, execution };
 }
 
 /**
@@ -324,8 +318,8 @@ function resolveRepoContext(io, opts = {}) {
  * @param {object} repoCtx   resolveRepoContext's result
  * @param {string} storyId   the id as the operator typed it — sent as `storyId`
  * @param {{ explicitText?: string|null, explicitLabel?: string, explicitSource?: {kind: 'file'|'description', label?: string},
- *   includePaths?: string[], axes?: string }} [opts]
- * @returns {Promise<{ storyId: string, resolvedStoryId: string, rawText: string,
+ *   includePaths?: string[], axes?: string, consultArchitect?: boolean }} [opts]
+ * @returns {Promise<{ storyId: string, rawText: string,
  *   textSource: 'explicit'|'issue'|'roadmap'|null, textFailure: {kind:string, detail?:string}|null,
  *   config: object, bundle: {files:number, chars:number}, notes: {pre: object[], post: object[]} }>}
  */
@@ -336,7 +330,6 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
   let rawText = '';
   let textSource = null;
   let textFailure = null;
-  let resolvedStoryId = storyId; // canonical id for the architect-config lookup
 
   // ── Story text: explicit → GitHub issue → Hone roadmap ────────────────────────────────────
   // HC-GF-010: an EXPLICIT story source short-circuits both lookups, so the operator can never
@@ -369,17 +362,6 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
       const prov = await issueStorySource(io, storyId, issue);
       config.story_source = prov.source;
       pre.push(...prov.notes);
-      // HC-019b-followup-1 F1: the canonical story id from the issue title, or the architect
-      // lookup keys on '104' and silently misses every EXECUTION_PLAN.yml entry.
-      try {
-        const titleId = extractStoryIdFromBranch(issue.title);
-        if (titleId) {
-          resolvedStoryId = titleId;
-          pre.push(info(`  → resolved issue #${storyId} → canonical story id '${titleId}' for architect-config lookup`));
-        } else {
-          pre.push(warn(`  ⚠ could not extract canonical story id from issue title '${issue.title}' — architect-config lookup will use '${storyId}' (likely silent miss)`));
-        }
-      } catch { /* extractor throws → fall back to the numeric id */ }
     } catch (e) {
       textFailure = { kind: 'issue-error', detail: firstLine(e) };
       // HC-GF-270: stated rather than left absent, so the later pause is readable. Classified, not
@@ -392,7 +374,6 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
       };
       pre.push(warn(`  ⚠ could not fetch GitHub issue context: ${firstLine(e)}`));
       pre.push(warn('  → proceeding without story_description; step_0 may produce placeholder output'));
-      pre.push(warn(`  ⚠ architect-config lookup will use '${storyId}' (likely silent miss)`));
     }
   } else {
     // HC-019n-followup-18: a roadmap-sourced story. Only the SERVER knows what it says; only the
@@ -540,11 +521,14 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
           path: candidate,
         });
         content = excerpt.content;
-        if (excerpt.notice) pre.push(warn(excerpt.notice));
-        for (const w of anchorWarnings(anchors, excerpt.unhonoured)) pre.push(warn(w));
         if (totalChars + content.length > BUNDLE_MAX_TOTAL_CHARS) { budgetSpent = true; break; }
         totalChars += content.length;
         codebaseFiles.push({ path: candidate, content });
+        // Only a file that made the bundle gets the "bundled lines A-B" notice: announced before the
+        // budget check, a dropped file printed it AND the NOT-bundled line below, and the operator
+        // read the first one (seen 2026-10-16 on server/scripts/seed-agent-prompts.js).
+        if (excerpt.notice) pre.push(warn(excerpt.notice));
+        for (const w of anchorWarnings(anchors, excerpt.unhonoured)) pre.push(warn(w));
       }
       // HC-GF-288: an operator-named entry whose file never reached the bundle (the budget ran
       // out first, or it names a directory) vanished as silently as the anchor did. A refused
@@ -597,6 +581,11 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
     }
   }
 
+  // ── Architect consult on request (HC-GF-397) ─────────────────────────────────────────────
+  // --consult-architect: the server runs step_0b even on a `not_engaged` grooming. Sent only as `true`; the server reads
+  // nothing else as a request, and no value of it can skip a consult.
+  if (opts.consultArchitect === true) config.consult_architect = true;
+
   // ── Classifier axes (HC-COMM-010) ─────────────────────────────────────────────────────────
   // Explicit --axes wins. Otherwise the DETERMINISTIC axes from the extractors; judgment axes
   // come from the groomer at step_0 and are harvested server-side. Fail-open.
@@ -621,19 +610,7 @@ async function resolveStoryContext(io, repoCtx, storyId, opts = {}) {
     }
   }
 
-  // ── Architect flags (HC-019b) ─────────────────────────────────────────────────────────────
-  // workflow-dag.js's validateStepPreConditions BLOCKS step_1 when architect_consulted is true
-  // and checklist_b_completed is not; without these flags every architect-engaged story
-  // deadlocks. Keyed on the RESOLVED id (HC-019b-followup-1 F1).
-  const arch = readArchitectConfigFromText(repoCtx.planText || '', resolvedStoryId);
-  config.architect_consulted = arch.architect_consulted;
-  config.checklist_b_completed = arch.checklist_b_completed;
-  if (arch.diagnostic) post.push(warn(`  ⚠ ${arch.diagnostic}`));
-  if (arch.architect_consulted) {
-    post.push(info(`  → architect_consulted: true, checklist_b_completed: ${arch.checklist_b_completed}`));
-  }
-
-  return { storyId, resolvedStoryId, rawText, textSource, textFailure, config, bundle, notes: { pre, post } };
+  return { storyId, rawText, textSource, textFailure, config, bundle, notes: { pre, post } };
 }
 
 /**

package/lib/run-report.js

@@ -18,7 +18,7 @@
 
 // HC-GF-234: the one wording for a step's unanswered question, shared with `--status`, `show
 // step` and the human-gate prompt. A pure leaf module, so this file stays pure.
-const { normalizeQuestion, questionLines, countPhrase } = require('./operator-question');
+const { normalizeQuestion, questionLines, countPhrase, scrub } = require('./operator-question');
 
 /** Gate verdicts the pipeline already speaks. Do not invent synonyms. */
 const ACTIONABLE_GATE_VERDICTS = ['fail', 'unavailable'];
@@ -69,6 +69,25 @@ function durationOf(startedAt, endedAt) {
 const BLOCKING_REASON_CODES = Object.freeze(['MAX_RETRIES_EXCEEDED', 'MAX_TOTAL_STEPS_EXCEEDED']);
 const BLOCKING_REASON_RE = new RegExp(`^(${BLOCKING_REASON_CODES.join('|')})[^\\n]*`);
 
+/**
+ * HC-GF-030: the pause the architect-consult guard takes. NOT in BLOCKING_REASON_CODES, which is pinned equal to
+ * what orchestrator-guardrails.js emits (HC-GF-046b); this one is emitted by workflow-dag.js's
+ * validateStepPreConditions. Approving is refused for it too — by the route and by approveGate — so it is a decision
+ * and not a gate. The server package and this one cannot share a constant, so
+ * tests/regression/HC-GF-030-run-report.test.js pins this string equal to architect-consult.js CONSULT_REQUIRED_CODE.
+ */
+const CONSULT_REQUIRED_CODE = 'ARCHITECT_CONSULT_REQUIRED';
+const CONSULT_REQUIRED_RE = new RegExp(`^${CONSULT_REQUIRED_CODE}:[^\\n]*`);
+/** The start of the message a batch run pauses with when its consult failed the mechanical check (orchestrator.js). */
+const CONSULT_NEEDS_PERSON_RE = /^architect consult needs a person to read it[^\n]*/;
+/**
+ * The pause a consult whose OWN verdict is `checklist_b_completed: false` takes (workflow-dag.js FAILURE_ROUTING_TABLE.step_0b.step_0b_abort).
+ * Approving it is refused (an `_abort` needs an acknowledgement, and even then nothing records a false verdict), so offering
+ * `--approve` here is HC-GF-046 again: the line invites the one action the server has already decided to refuse.
+ * tests/regression/HC-GF-030-run-report.test.js pins this prefix to the server's message.
+ */
+const CONSULT_ABORT_RE = /^step_0b: the architect consult did not complete Checklist B[^\n]*/;
+
 /**
  * HC-GF-046(b), corrected in review: a step that used up its format retries.
  *
@@ -107,7 +126,28 @@ function buildReport(run, extra = {}) {
     // untrustworthy in the other direction.
     const blocked = String(run.errorMessage || '').match(BLOCKING_REASON_RE);
     const exhausted = String(run.errorMessage || '').match(EXHAUSTED_RE);
-    if (run.approvalRefusal) {
+    const consultRequired = String(run.errorMessage || '').match(CONSULT_REQUIRED_RE);
+    const consultNeedsPerson = String(run.errorMessage || '').match(CONSULT_NEEDS_PERSON_RE);
+    const consultAbort = String(run.errorMessage || '').match(CONSULT_ABORT_RE);
+    if (consultRequired) {
+      needsYou.push({
+        what: `run CANNOT proceed at ${run.currentStep} — ${scrub(consultRequired[0].slice(0, 400))}. There is no waiver and `
+          + 'approving is refused, so this is a decision, not a gate',
+        how: `hone run-story ${run.runId} --kill   (then re-run the story: step_0 is cached, so it costs one consult)`,
+      });
+    } else if (consultNeedsPerson) {
+      needsYou.push({
+        what: `the architect consult is waiting for a person to read it — ${scrub(consultNeedsPerson[0].slice(0, 400))}`,
+        how: `hone show step ${run.runId} step_0b   (then hone run-story ${run.runId} --approve step_0b once you have read it)`,
+      });
+    } else if (consultAbort) {
+      needsYou.push({
+        what: `the architect consult did not pass at ${run.currentStep} — ${scrub(consultAbort[0].slice(0, 400))}. Approving is refused, `
+          + 'so this is a decision, not a gate',
+        how: `hone show step ${run.runId} step_0b   (read what it flagged, change the story to answer it, `
+          + `then hone run-story ${run.runId} --kill and run the story again)`,
+      });
+    } else if (run.approvalRefusal) {
       // HC-GF-074: rendered from the server's own decision, never re-derived from verdict records here.
       needsYou.push({
         what: `run CANNOT be approved at ${run.currentStep} as it stands — ${String(run.approvalRefusal.message).slice(0, 300)}`,
@@ -430,6 +470,26 @@ function buildReport(run, extra = {}) {
       worthKnowing.push(`${s.stepKey} ran ${s.attempts} times`);
     }
   }
+  // HC-GF-030: a run that finished with an architect classified as needed and no consult recorded. The consult
+  // guard makes this unreachable for a run the server drove; it is said here because "no run records
+  // `architect_engaged: true` with no consult" is the acceptance, and a report is where that gets checked.
+  const arch = run.architect && typeof run.architect === 'object' ? run.architect : null;
+  // HC-GF-397-followup-1: `hone run-story --consult-architect` asks for a consult on a `not_engaged` grooming. Read the way
+  // the server reads it — the boolean `true` only — so a requested consult that is not approved is never "not needed".
+  const consultRequested = cfg.consult_architect === true;
+  if (arch && (arch.verdict !== 'not_engaged' || consultRequested) && !arch.consulted && run.status === 'completed') {
+    const why = arch.verdict === 'engaged' ? 'the architect classified as needed'
+      : arch.verdict === 'not_engaged' ? 'an architect consult REQUESTED with --consult-architect'
+      : 'the architect verdict unreadable';
+    needsYou.push({
+      what: `run COMPLETED with ${why} and NO approved consult`,
+      how: `hone show step ${run.runId} step_0b`,
+      // HC-026c: a new signal must not turn every run that finished BEFORE the consult step existed into a failing exit
+      // code (about 27 of 28 completed runs on the local server were engaged). Shown in full, counted in `needsYou`, and
+      // not gating: the consult guard is what stops a new run, and this line is for reading a run that predates it.
+      advisory: true,
+    });
+  }
   // The two "blind run" tells, both from HC-GF-006's preflight reasoning.
   const descChars = typeof cfg.story_description === 'string' ? cfg.story_description.length : 0;
   if (descChars === 0) {
@@ -459,9 +519,21 @@ function buildReport(run, extra = {}) {
     duration: durationOf(run.startedAt, run.completedAt),
     cost: extra.cost || null,
     architectConsulted: cfg.architect_consulted === true,
+    // HC-GF-030: derived server-side from the step rows, never from config. null on a server that predates it.
+    architect: arch ? {
+      verdict: arch.verdict, consulted: arch.consulted === true, requested: consultRequested,
+      // A number or nothing: this is printed, and it came off the network.
+      consultAttempt: Number.isFinite(Number(arch.consultAttempt)) && Number(arch.consultAttempt) > 0 ? Math.trunc(Number(arch.consultAttempt)) : null,
+      blockers: Number(arch.blockers) || 0,
+      // Agent-written text going to a terminal: the server scrubs it, and this CLI may be talking to an older or different
+      // server, so it scrubs again where it is stored for printing (the rule cli/lib/operator-question.js already keeps).
+      findings: (Array.isArray(arch.findings) ? arch.findings : []).map(f => scrub(String(f).slice(0, 400))),
+      callSiteGaps: (Array.isArray(arch.callSiteGaps) ? arch.callSiteGaps : []).map(g => scrub(String(g).slice(0, 400))),
+    } : null,
     storyDescriptionChars: descChars,
     bundledFiles: bundled,
-    classifierAxes: Array.isArray(cfg.classifier_axes) ? cfg.classifier_axes : [],
+    // The groomer's own words (the server harvests them from step_0's output), printed on a terminal: scrubbed, and strings only.
+    classifierAxes: Array.isArray(cfg.classifier_axes) ? cfg.classifier_axes.map(a => scrub(String(a).slice(0, 80))) : [],
     needsYou,
     worthKnowing,
     steps,
@@ -530,6 +602,21 @@ function renderReport(r) {
     L.push('');
   }
 
+  if (r.architect) {
+    const a = r.architect;
+    L.push('ARCHITECT');
+    L.push(`  ${a.verdict === 'engaged' ? 'engaged' : a.verdict === 'not_engaged' ? 'not engaged (step_0 said so, readably)' : 'verdict unreadable (the consult runs)'}`
+      + `${r.classifierAxes.length ? ` · axes: ${r.classifierAxes.join(', ')}` : ''}`
+      // HC-GF-397-followup-1: the request is named only where it changed the outcome — an engaged or unreadable verdict
+      // runs the consult anyway, so its line stays as it was.
+      + `${a.requested && a.verdict === 'not_engaged' ? ' · consult requested (--consult-architect)' : ''}`
+      + ` · consult ${a.consulted ? `approved${a.consultAttempt ? ` (step_0b attempt ${a.consultAttempt})` : ''}` : a.verdict === 'not_engaged' && !a.requested ? 'not needed' : 'NOT approved'}`);
+    if (a.blockers > 0) L.push(`  ${a.blockers} finding(s) marked BLOCKER`);
+    for (const f of a.findings) L.push(`  · ${f}`);
+    for (const g of a.callSiteGaps) L.push(`  ⚠ call sites the consult could not see: ${g}`);
+    L.push('');
+  }
+
   L.push('STEPS');
   for (const s of r.steps) {
     const mark = s.status === 'completed' ? '✓' : s.status === 'skipped' ? '○' : '·';
@@ -540,8 +627,11 @@ function renderReport(r) {
   L.push('');
 
   L.push('RUN FACTS');
+  // HC-GF-030: the consult state comes from the server's step rows when it reports them (`architect`); the config flag is
+  // only a mirror, cleared by a new grooming, and is what an older server still reports.
+  const consultedFact = r.architect ? r.architect.consulted : r.architectConsulted;
   L.push(`  mode ${r.mode || 'unknown'} · story text ${r.storyDescriptionChars} chars · `
-         + `${r.bundledFiles} file(s) bundled · architect_consulted ${r.architectConsulted}`);
+         + `${r.bundledFiles} file(s) bundled · architect_consulted ${consultedFact}`);
   if (r.classifierAxes.length) L.push(`  axes: ${r.classifierAxes.join(', ')}`);
   if (r.verifications.length) {
     for (const v of r.verifications) {

package/lib/tree-artifact.js

@@ -18,14 +18,34 @@
  *   malformed[] unparsable block    — DELIBERATELY NOT REACHABLE: every fence we emit is longer
  *                                     than any fence run inside the file it wraps (see below).
  *   noChanges   the honest no-op    — HANDLED: a clean tree says NO CHANGES rather than nothing.
+ *                                     HC-GF-395: it says "matches HEAD" only when git reported no
+ *                                     change at all (`!changed.length`). When git reported changes
+ *                                     but none could be sent (`!included.length`), it says "NO
+ *                                     CHANGES — the working tree differs from HEAD, but no changed
+ *                                     file could be sent as content (N skipped; see ### Not
+ *                                     included)", N counting named skips only (symlinks are silent).
  *
- * Dependency-free by intent, like `cli/lib/headroom.js`: `git`, `fs` and `path` only.
+ * Dependency-free by intent, like `cli/lib/headroom.js`: `git`, `fs` and `path`, plus the one
+ * classifier the bundler already uses — `isSecretPath` from `./bundle-context`, which itself
+ * requires only `path`.
+ *
+ * HC-GF-393: a path `isSecretPath()` classifies (`.env*`, `*.pem`, `id_rsa`-style keys, …) is
+ * never read. It is named under `### Not included`, so it is absent from the patch and the PR
+ * on purpose and visibly, not silently. A deleted one still renders as `DELETE:` (no content).
+ *
+ * HC-GF-394: a file that cannot be read is named under `### Not included` as `unreadable`. It used
+ * to throw, and the whole submission failed with it — every readable change included.
+ *
+ * HC-GF-390: for step_4 the submit also computes a review-only base diff of the over-cap files this
+ * render emitted whole (`cli/lib/review-diff.js`). It is sent as a separate `reviewDiff` field and
+ * stored apart; it is never part of this artifact, and nothing here changes because of it.
  */
 
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { gitEnv } = require('./git-env');
+const { isSecretPath } = require('./bundle-context');
 
 /** Bytes above which we do not attempt to inline a file at all. */
 const MAX_FILE_BYTES = 1_000_000;
@@ -119,6 +139,9 @@ function renderFromTree({ repoRoot, testReport } = {}) {
   const skipped = [];
 
   for (const rel of changed) {
+    // First, before lstat or read: the bytes of a secret path never enter this process. The name
+    // is the signal, so a symlink or an oversized file with a secret name is listed as a secret.
+    if (isSecretPath(rel)) { skipped.push({ path: rel, reason: 'secret path — not sent' }); continue; }
     const abs = path.join(repoRoot, rel);
     let st;
     try { st = fs.lstatSync(abs); } catch { skipped.push({ path: rel, reason: 'unreadable' }); continue; }
@@ -129,7 +152,8 @@ function renderFromTree({ repoRoot, testReport } = {}) {
     if (st.isSymbolicLink() || !st.isFile()) continue;
     if (st.size > MAX_FILE_BYTES) { skipped.push({ path: rel, reason: `larger than ${MAX_FILE_BYTES} bytes` }); continue; }
 
-    const buf = fs.readFileSync(abs);
+    let buf;
+    try { buf = fs.readFileSync(abs); } catch { skipped.push({ path: rel, reason: 'unreadable' }); continue; }
     if (looksBinary(buf)) { skipped.push({ path: rel, reason: 'binary' }); continue; }
 
     const content = buf.toString('utf8');
@@ -141,9 +165,18 @@ function renderFromTree({ repoRoot, testReport } = {}) {
 
   const lines = ['## Changed Files', ''];
 
-  if (!included.length && !deleted.length) {
+  if (!changed.length && !deleted.length) {
     // The honest no-op, in the shape the validator and the materialiser both already accept.
     lines.push('NO CHANGES — the working tree matches HEAD.');
+  } else if (!included.length && !deleted.length) {
+    // HC-GF-395: still a no-op, but not a clean tree. One line with the same `NO CHANGES —` prefix,
+    // which every parser keys on; the rest of the line is the reason stored in the artifact (the
+    // CLI's own no-op messages are fixed text). Only a
+    // named skip has a list to point at; a symlink or non-regular file is skipped silently.
+    const why = skipped.length
+      ? `${skipped.length} skipped; see ### Not included`
+      : 'symlinks and non-regular files are not sent';
+    lines.push(`NO CHANGES — the working tree differs from HEAD, but no changed file could be sent as content (${why}).`);
   } else {
     for (const b of blocks) { lines.push(b, ''); }
     for (const rel of deleted) lines.push(`DELETE: ${rel}`);

package/package.json

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