@hone-ai/cli 1.41.0 → 1.42.0

package/lib/tree-artifact.js

@@ -12,9 +12,13 @@
  *
  *   files[]     whole-file blocks   — HANDLED: created + modified files
  *   deletes[]   `DELETE: <path>`    — HANDLED: deleted files
- *   edits[]     region edits        — DELIBERATELY NOT: from-tree always sends whole files. The
- *                                     tree is the truth; an anchor-based edit would reintroduce
- *                                     exactly the drift this removes.
+ *   edits[]     region edits        — HANDLED under editor contract 3, for step_4 only (HC-GF-399): a
+ *                                     modified file whose HEAD blob is over BUNDLE_MAX_PER_FILE_CHARS
+ *                                     is sent as region edits only after the rendered text, parsed back
+ *                                     by extractFileBlocks(), rebuilds the exact tree bytes from HEAD
+ *                                     with applyEdits(), and no OLD survives in the tree. The tree is
+ *                                     still the truth: an edit is sent only once it is proven to
+ *                                     reproduce it. Under contracts 1 and 2 every file goes whole.
  *   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.
@@ -25,11 +29,19 @@
  *                                     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`, plus the one
- * classifier the bundler already uses — `isSecretPath` from `./bundle-context`, which itself
- * requires only `path`.
+ * Small dependencies by intent: `git`, `fs` and `path`, the one classifier the bundler already uses
+ * (`pathRefusal` from `./path-refusal` in egress mode, which itself requires only `path`), the cap from the leaf
+ * `./bundle-limits`, and — for HC-GF-399's proof — the consumers' own parser and applier
+ * (`./materialize-diff`) and fence walker (`./block-grammar`). The proof must use the code every patch
+ * verb applies the artifact with, or it proves nothing about them.
  *
- * HC-GF-393: a path `isSecretPath()` classifies (`.env*`, `*.pem`, `id_rsa`-style keys, …) is
+ * HC-GF-399: under contract 3 the artifact also starts with one `<!-- hone-base: <sha> -->` line, the
+ * commit every edit is anchored on, and HEAD is resolved to that sha once per render. The route refuses
+ * a contract-3 step_4 output without exactly one, and stores it as sent: no composeRebuild, because a
+ * HEAD-anchored edit applied over a previous attempt's file would hit the wrong text.
+ *
+ * HC-GF-393: a path egress mode refuses (`.env*`, `*.pem`, `id_rsa`-style keys, and since HC-GF-398
+ * `*.key`, `*.pfx`, `*.jks`, `*.keystore`, `*.p8`) 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).
  *
@@ -45,18 +57,77 @@ 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');
+const { pathRefusal } = require('./path-refusal');
+const { BUNDLE_MAX_PER_FILE_CHARS } = require('./bundle-limits');
+const { extractFileBlocks, applyEdits, countOccurrences } = require('./materialize-diff');
+const { fencedSpans } = require('./block-grammar');
 
 /** Bytes above which we do not attempt to inline a file at all. */
 const MAX_FILE_BYTES = 1_000_000;
 
+/** HC-GF-399: every git call has a deadline. A listing call that misses it fails the render. */
+const GIT_LIST_TIMEOUT_MS = 30_000;
+/** Per-file calls (`git show`, `git diff -U0`) that miss it send that file whole. */
+const GIT_FILE_TIMEOUT_MS = 10_000;
+/** The per-render CPU budget for edit work. collectPaths() runs outside it; past it, files go whole. */
+const RENDER_BUDGET_MS = 30_000;
+/** Context lines either side of a hunk are doubled from 1 up to this, then the file goes whole. */
+const MAX_CONTEXT = 512;
+/** k doubles from 1 to MAX_CONTEXT in 10 rounds; the loop is bounded by this whatever the widening does. */
+const MAX_ROUNDS = 11;
+/** Keep in sync with server/src/routes/orchestrate.js HONE_BASE_STAMP_RE (pinned by HC-GF-399's contract test). */
+const HONE_BASE_STAMP_RE = /^<!-- hone-base: (?:[0-9a-f]{40}|[0-9a-f]{64}) -->$/;
+/** The three EDIT_SPLIT_RE delimiters (cli/lib/block-grammar.js). An OLD/NEW line like one cannot be carried. */
+const EDIT_DELIMITER_RE = /^(?:<{3,}[ \t]*OLD|={3,}|>{3,}[ \t]*NEW)[ \t]*$/;
+
 /**
  * SC-002-followup-2: git exports GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE to the processes it
  * spawns, and those BEAT `cwd`. Without gitEnv() this renders a different repository's tree when
  * it runs under a git hook — and it would look like a perfectly normal build.
  */
-function gitOut(repoRoot, args) {
-  return execFileSync('git', args, { cwd: repoRoot, env: gitEnv(), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+function gitOut(repoRoot, args, { encoding = 'utf8', timeout = GIT_LIST_TIMEOUT_MS } = {}) {
+  return execFileSync('git', args, {
+    cwd: repoRoot, env: gitEnv(), encoding, timeout, maxBuffer: 64 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/** HC-GF-399: execFileSync reports a missed deadline as ETIMEDOUT, or a SIGTERM with no exit status. */
+function isGitTimeout(e) {
+  return Boolean(e && (e.code === 'ETIMEDOUT' || (e.signal === 'SIGTERM' && e.status == null)));
+}
+
+/**
+ * HC-GF-399: the commit HEAD names, or null when there is none.
+ *
+ * null ONLY for a numeric non-zero git exit that is not a timeout — an unborn repository, or a directory
+ * that is not a repository (128). A timeout throws: read as "no HEAD", it would render the build as if
+ * every tracked file were new and drop every modification without a word.
+ */
+function resolveHead(repoRoot, runGit) {
+  const git = runGit || ((args, opts) => gitOut(repoRoot, args, opts));
+  let out;
+  try {
+    out = git(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], { timeout: GIT_LIST_TIMEOUT_MS });
+  } catch (e) {
+    if (isGitTimeout(e)) {
+      throw new Error(`git rev-parse HEAD hit its ${GIT_LIST_TIMEOUT_MS} ms timeout — not read as "no HEAD", `
+        + 'which would drop every modified file');
+    }
+    if (e && typeof e.status === 'number' && e.status !== 0) return null;
+    throw e;
+  }
+  const sha = String(out).trim();
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha)) throw new Error(`git rev-parse HEAD printed ${JSON.stringify(sha.slice(0, 80))}, not a sha`);
+  return sha;
+}
+
+/**
+ * HC-GF-399: the editor contracts this checkout can honour, for `step-instruction` to advertise.
+ * Contract 3 anchors edits on HEAD, so a repository with no commit advertises 1,2 and is served 2.
+ */
+function editorContractsFor(repoRoot, { runGit } = {}) {
+  return resolveHead(repoRoot, runGit) ? '1,2,3' : '1,2';
 }
 
 /**
@@ -91,14 +162,15 @@ function looksBinary(buf) {
  * .gitignore: a node_modules SYMLINK is a file to a naive directory walk
  * (HC-COMM-010-followup-8), and git excludes it because the adopter said so.
  */
-function collectPaths(repoRoot) {
+function listPaths(repoRoot, { runGit, sha } = {}) {
   const changed = [];
   const deleted = [];
-  let hasHead = true;
-  try { gitOut(repoRoot, ['rev-parse', '--verify', 'HEAD']); } catch { hasHead = false; }
+  const modified = [];
+  // HC-GF-399: one sha per render, so a commit landing mid-render cannot mix two bases.
+  const headSha = sha !== undefined ? sha : resolveHead(repoRoot, runGit);
 
-  if (hasHead) {
-    const out = gitOut(repoRoot, ['diff', '--name-status', '--no-renames', 'HEAD']);
+  if (headSha) {
+    const out = gitOut(repoRoot, ['diff', '--name-status', '--no-renames', headSha]);
     for (const line of out.split('\n')) {
       if (!line.trim()) continue;
       const tab = line.indexOf('\t');
@@ -108,6 +180,7 @@ function collectPaths(repoRoot) {
       if (!rel) continue;
       if (status.startsWith('D')) deleted.push(rel);
       else changed.push(rel);
+      if (status.startsWith('M')) modified.push(rel);
     }
   }
   const others = gitOut(repoRoot, ['ls-files', '--others', '--exclude-standard']);
@@ -116,9 +189,154 @@ function collectPaths(repoRoot) {
   return {
     changed: [...new Set(changed)].sort(),
     deleted: [...new Set(deleted)].sort(),
+    modified: [...new Set(modified)].sort(),
+    headSha,
   };
 }
 
+/** The `{changed, deleted}` the HC-GF-394/395 suites assert, unchanged in shape (HC-GF-399 adds listPaths beside it). */
+function collectPaths(repoRoot, opts) {
+  const { changed, deleted } = listPaths(repoRoot, opts);
+  return { changed, deleted };
+}
+
+/** `@@ -a[,b] +c[,d] @@` headers of a `git diff -U0`; an omitted count is 1. Nothing else is read from git's text. */
+function parseHunkHeaders(diffText) {
+  const hunks = [];
+  for (const line of String(diffText).split('\n')) {
+    const m = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
+    if (!m) continue;
+    hunks.push({ a: Number(m[1]), b: m[2] === undefined ? 1 : Number(m[2]), c: Number(m[3]), d: m[4] === undefined ? 1 : Number(m[4]) });
+  }
+  return hunks;
+}
+
+/**
+ * HC-GF-399: the region edits that turn `headText` into `treeText`, or the reason there are none.
+ *
+ * Each hunk becomes a region of whole lines with k lines of context either side (k = 1, 2, 4, … up to
+ * MAX_CONTEXT); regions whose widened ranges touch merge. A region is good when, applied in order to a
+ * running copy, its OLD occurs EXACTLY ONCE there (what applyEdit requires) and ZERO times in the tree
+ * (so the edit cannot re-apply once the build is committed: a pure insertion at line 1 or at EOF has
+ * context on one side only, its NEW contains its OLD, and widening cannot help — it goes whole). OLD and
+ * NEW are the lines joined by '\n' with no final newline, exactly what EDIT_SPLIT_RE hands the parser.
+ *
+ * @returns {{edits: Array<{oldString:string,newString:string}>}|{reason:string}}
+ */
+function buildEdits(headText, treeText, hunks, overBudget = () => false) {
+  const H = headText.split('\n'); H.pop();   // both end in '\n' (checked by the caller): drop the final ''
+  const T = treeText.split('\n'); T.pop();
+  const base = hunks.map((h) => {
+    const hs = h.b === 0 ? h.a : h.a - 1;
+    const ts = h.d === 0 ? h.c : h.c - 1;
+    return { hs, he: hs + h.b, ts, te: ts + h.d, k: 1 };
+  });
+  let lastReason = 'ambiguous';
+  for (let round = 0; round < MAX_ROUNDS; round++) {
+    // Checked every widening round, not once per file: one file with many hunks in repetitive text can otherwise
+    // run its rounds well past the budget the caller relies on.
+    if (overBudget()) return { reason: 'budget' };
+    const regions = [];
+    for (const h of base) {
+      let r = { hlo: Math.max(0, h.hs - h.k), hhi: Math.min(H.length, h.he + h.k), members: [h] };
+      // Members can widen by different k, so a later region may reach back over several earlier ones: merge them all.
+      while (regions.length && r.hlo <= regions[regions.length - 1].hhi) {
+        const prev = regions.pop();
+        r = { hlo: Math.min(prev.hlo, r.hlo), hhi: Math.max(prev.hhi, r.hhi), members: prev.members.concat(r.members) };
+      }
+      regions.push(r);
+    }
+    // Lines outside a region's hunks are unchanged, so they map by the offset in force there: the first member's
+    // before it, the last member's after it. (Taking each member's own end would cut NEW short, or overshoot, when
+    // a wider member reaches past a later one that inserted or removed lines.)
+    for (const r of regions) {
+      const first = r.members[0];
+      const last = r.members[r.members.length - 1];
+      r.tlo = r.hlo + (first.ts - first.hs);
+      r.thi = r.hhi + (last.te - last.he);
+    }
+    let running = headText;
+    const edits = [];
+    const bad = [];
+    for (const r of regions) {
+      const oldLines = H.slice(r.hlo, r.hhi);
+      const newLines = T.slice(r.tlo, r.thi);
+      if (oldLines.some((l) => EDIT_DELIMITER_RE.test(l)) || newLines.some((l) => EDIT_DELIMITER_RE.test(l))) return { reason: 'delimiter' };
+      const oldString = oldLines.join('\n');
+      const newString = newLines.join('\n');
+      if (!oldString) { bad.push({ r, reason: 'ambiguous' }); continue; }
+      if (countOccurrences(running, oldString) !== 1) { bad.push({ r, reason: 'ambiguous' }); continue; }
+      if (countOccurrences(treeText, oldString) !== 0) { bad.push({ r, reason: 'reapplicable' }); continue; }
+      const at = running.indexOf(oldString);
+      running = running.slice(0, at) + newString + running.slice(at + oldString.length);
+      edits.push({ oldString, newString });
+    }
+    if (!bad.length) return { edits };
+    for (const { r, reason } of bad) {
+      const whole = r.hlo === 0 && r.hhi === H.length;
+      if (whole || r.members.every((h) => h.k >= MAX_CONTEXT)) return { reason };
+      for (const h of r.members) h.k = Math.min(MAX_CONTEXT, h.k * 2);
+      lastReason = reason;
+    }
+  }
+  return { reason: lastReason };   // not reached by the doubling above; a hard bound, not a guess
+}
+
+function wholeBlock(rel, content) {
+  const fence = fenceFor(content);
+  const body = content.endsWith('\n') ? content.slice(0, -1) : content;
+  return `${fence}file: ${rel}\n${body}\n${fence}`;
+}
+
+function renderEditBlock(rel, e) {
+  const body = `<<<<<<< OLD\n${e.oldString}\n=======\n${e.newString}\n>>>>>>> NEW`;
+  const fence = fenceFor(body);
+  return `${fence}edit: ${rel}\n${body}\n${fence}`;
+}
+
+/**
+ * HC-GF-399: the proof, on the TEXT that is sent — parsed back by the consumers' own parser and applied with
+ * their own applier. Proving the edit objects would not prove the fence, the OLD/NEW split or the newline
+ * stripping. True only when the blocks parse to exactly these edits for `rel`, rebuild `treeText` from
+ * `headText`, and leave no OLD in the tree.
+ */
+function proveEdits(rel, blocks, headText, treeText) {
+  try {
+    const p = extractFileBlocks(`## Changed Files\n\n${blocks.join('\n\n')}`);
+    if (p.files.length || p.deletes.length || p.malformed.length || p.noChanges) return false;
+    if (p.edits.length !== blocks.length || p.edits.some((e) => e.path !== rel)) return false;
+    if (applyEdits(headText, p.edits, rel) !== treeText) return false;
+    return p.edits.every((e) => countOccurrences(treeText, e.oldString) === 0);
+  } catch {
+    return false;
+  }
+}
+
+/** `a.txt, not b.txt`: what the render sent that the parse did not read, and the reverse. */
+function listDiff(sent, read) {
+  const missing = sent.filter((x) => !read.includes(x));
+  const extra = read.filter((x) => !sent.includes(x));
+  return [missing.length ? `${missing.slice(0, 3).join(', ')}, read back without it` : '', extra.length ? `read back with ${extra.slice(0, 3).join(', ')}` : '']
+    .filter(Boolean).join('; ') || 'the same paths in another order';
+}
+
+/** Stamp lines outside every fenced block (an unclosed fence runs to the end). Mirrors the route's countBaseStamps. */
+function countStampsOutsideFences(text) {
+  const { blocks, open } = fencedSpans(text);
+  let n = 0;
+  let b = 0;
+  for (let i = 0; i <= text.length;) {
+    const nl = text.indexOf('\n', i);
+    const end = nl === -1 ? text.length : nl;
+    while (b < blocks.length && blocks[b].end < i) b++;
+    const inside = (b < blocks.length && blocks[b].start <= i && i <= blocks[b].end) || (open && i >= open.start);
+    if (!inside && HONE_BASE_STAMP_RE.test(text.slice(i, end))) n++;
+    if (nl === -1) break;
+    i = nl + 1;
+  }
+  return n;
+}
+
 /**
  * Render the artifact.
  *
@@ -128,72 +346,206 @@ function collectPaths(repoRoot) {
  *                                   invented: an absent report stays absent, because a fabricated
  *                                   "N passing" is the anti-fabrication failure the step_4
  *                                   validator already exists to catch.
- * @returns {{ text: string, files: string[], deletes: string[], skipped: Array<{path,reason}> }}
+ * @param {string} [opts.contract]   HC-GF-399: the editor contract the submit uses. Only '3' changes the
+ *                                   render; with it absent the output is byte-identical to before.
+ * @param {string} [opts.stepKey]    edits are sent only for step_4
+ * @param {Function} [opts.runGit]   test seam for the per-file git calls: (args, {encoding, timeout}) → output
+ * @param {Function} [opts.now]      test seam for the render budget
+ * @param {number}  [opts.budgetMs]
+ * @returns {{ text: string, files: string[], edited: string[], fallbacks: Array<{path,reason}>,
+ *             deletes: string[], skipped: Array<{path,reason}>, headSha: string|null }}
+ *   `files` stays whole-file blocks only, so computeReviewDiff() keeps keying on them.
  */
-function renderFromTree({ repoRoot, testReport } = {}) {
+function renderFromTree({ repoRoot, testReport, contract, stepKey, runGit, now = Date.now, budgetMs = RENDER_BUDGET_MS } = {}) {
   if (!repoRoot) throw new Error('renderFromTree: repoRoot is required');
-  const { changed, deleted } = collectPaths(repoRoot);
-
-  const blocks = [];
-  const included = [];
-  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; }
-    // Structural, and deliberately silent: a symlink is not file content. materialize-diff would
-    // write a REGULAR file holding the link's target bytes, converting it without saying so. Naming
-    // every one of these would also put `node_modules` in the artifact of any repo whose .gitignore
-    // says `node_modules/` — a directory pattern that does not match the symlink (HC-COMM-010-followup-8).
-    if (st.isSymbolicLink() || !st.isFile()) continue;
-    if (st.size > MAX_FILE_BYTES) { skipped.push({ path: rel, reason: `larger than ${MAX_FILE_BYTES} bytes` }); continue; }
-
-    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');
-    const fence = fenceFor(content);
-    const body = content.endsWith('\n') ? content.slice(0, -1) : content;
-    blocks.push(`${fence}file: ${rel}\n${body}\n${fence}`);
-    included.push(rel);
+  const c3 = String(contract) === '3';
+  const stamped = c3 && stepKey === 'step_4';
+  const editMode = stamped;
+  const git = runGit || ((args, opts) => gitOut(repoRoot, args, opts));
+  // The listing runs OUTSIDE the budget, and its failures throw: a timed-out listing caught as "nothing
+  // changed" would send NO CHANGES for a real build.
+  const { changed, deleted, modified, headSha } = listPaths(repoRoot, { runGit });
+  if (c3 && !headSha) {
+    throw new Error('--contract 3 sends region edits anchored on HEAD, and this repository has no commit (no HEAD). '
+      + 'Re-run with --contract 2.');
   }
+  if (stamped && testReport && String(testReport).split('\n').some((l) => HONE_BASE_STAMP_RE.test(l.trim()))) {
+    throw new Error('the test report contains a `<!-- hone-base: … -->` line; remove it — a contract-3 build carries exactly one.');
+  }
+  const modifiedSet = new Set(modified);
+  const start = now();
+
+  const fallbacks = [];
+  const proven = new Map();   // rel → { headText, treeText }
+  const tried = new Map();    // rel → tryEdits() result, computed once per render
 
-  const lines = ['## Changed Files', ''];
-
-  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}`);
-    if (deleted.length) lines.push('');
+  /** @returns {{blocks: string[]}|{reason: string|null}} — reason null: under the cap, whole with nothing to say */
+  function tryEdits(rel, buf) {
+    if (now() - start > budgetMs) return { reason: buf.length > BUNDLE_MAX_PER_FILE_CHARS ? 'budget' : null };
+    let headBuf;
+    try { headBuf = git(['show', `${headSha}:${rel}`], { encoding: 'buffer', timeout: GIT_FILE_TIMEOUT_MS }); } catch { return { reason: 'git' }; }
+    headBuf = Buffer.isBuffer(headBuf) ? headBuf : Buffer.from(String(headBuf), 'utf8');
+    const headText = headBuf.toString('utf8');
+    if (headText.length <= BUNDLE_MAX_PER_FILE_CHARS) return { reason: null };
+    const treeText = buf.toString('utf8');
+    // Byte-exact, not string-exact: invalid UTF-8 decodes to U+FFFD and would "prove" a file the verbs then corrupt.
+    if (!Buffer.from(headText, 'utf8').equals(headBuf) || !Buffer.from(treeText, 'utf8').equals(buf)) return { reason: 'encoding' };
+    if (headText.includes('\r') || treeText.includes('\r')) return { reason: 'cr' };
+    if (!headText.endsWith('\n') || !treeText.endsWith('\n')) return { reason: 'no-final-newline' };
+    let diff;
+    try {
+      // Pinned so no user config changes what is read: only the `@@` ranges are parsed, never git's paths or text.
+      // `:(literal)`: `src/[id].js` is a path, not a glob that also matches `src/i.js`.
+      diff = git(['diff', '-U0', '--no-color', '--no-ext-diff', '--no-textconv', '--src-prefix=a/', '--dst-prefix=b/',
+        headSha, '--', `:(literal)${rel}`], { encoding: 'utf8', timeout: GIT_FILE_TIMEOUT_MS });
+    } catch { return { reason: 'git' }; }
+    const hunks = parseHunkHeaders(diff);
+    if (!hunks.length) return { reason: 'no-hunks' };
+    const built = buildEdits(headText, treeText, hunks, () => now() - start > budgetMs);
+    if (built.reason) return { reason: built.reason };
+    const blocks = built.edits.map((e) => renderEditBlock(rel, e));
+    if (!proveEdits(rel, blocks, headText, treeText)) return { reason: 'proof' };
+    // Edits exist to make the artifact SMALLER. A heavy rewrite renders as OLD plus NEW, about twice the file:
+    // then the whole file is the smaller form, and contract 3 must never be the one that hits the 1 MB cap.
+    if (Buffer.byteLength(blocks.join('\n\n'), 'utf8') >= Buffer.byteLength(wholeBlock(rel, treeText), 'utf8')) return { reason: 'larger' };
+    proven.set(rel, { headText, treeText });
+    return { blocks };
   }
 
-  if (skipped.length) {
-    // Named, not silent: a file that is in the tree and not in the artifact must be visible as a
-    // decision. Kept out of the Changed Files blocks so it can never parse as one.
-    lines.push('### Not included', '');
-    for (const s of skipped) lines.push(`- \`${s.path}\` — ${s.reason}`);
-    lines.push('');
+  // One pass over the tree; `demote` names edited paths the final-artifact proof sent back to whole.
+  function renderOnce(demote) {
+    const blocks = [];
+    const included = [];
+    const edited = [];
+    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 (pathRefusal(rel, { mode: 'egress' })) { 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; }
+      // Structural, and deliberately silent: a symlink is not file content. materialize-diff would
+      // write a REGULAR file holding the link's target bytes, converting it without saying so. Naming
+      // every one of these would also put `node_modules` in the artifact of any repo whose .gitignore
+      // says `node_modules/` — a directory pattern that does not match the symlink (HC-COMM-010-followup-8).
+      if (st.isSymbolicLink() || !st.isFile()) continue;
+      if (st.size > MAX_FILE_BYTES) { skipped.push({ path: rel, reason: `larger than ${MAX_FILE_BYTES} bytes` }); continue; }
+
+      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; }
+
+      if (editMode && modifiedSet.has(rel) && !demote.has(rel)) {
+        if (!tried.has(rel)) {
+          const got = tryEdits(rel, buf);
+          tried.set(rel, got);
+          if (got.reason) fallbacks.push({ path: rel, reason: got.reason });
+        }
+        const got = tried.get(rel);
+        if (got.blocks) { blocks.push(...got.blocks); edited.push(rel); continue; }
+      }
+
+      blocks.push(wholeBlock(rel, buf.toString('utf8')));
+      included.push(rel);
+    }
+
+    const lines = stamped ? [`<!-- hone-base: ${headSha} -->`, '', '## Changed Files', ''] : ['## Changed Files', ''];
+
+    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 && !edited.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.
+      // HC-GF-399: an edits-only build is a build, so `edited` counts here too.
+      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}`);
+      if (deleted.length) lines.push('');
+    }
+
+    if (skipped.length) {
+      // Named, not silent: a file that is in the tree and not in the artifact must be visible as a
+      // decision. Kept out of the Changed Files blocks so it can never parse as one.
+      lines.push('### Not included', '');
+      for (const s of skipped) lines.push(`- \`${s.path}\` — ${s.reason}`);
+      lines.push('');
+    }
+
+    if (testReport) lines.push('### Test run', '', String(testReport).trim(), '');
+
+    return { text: lines.join('\n'), included, edited, skipped };
+  }
+
+  /**
+   * HC-GF-399: the whole artifact, parsed ONCE, so interactions between blocks are caught too. `ok` only when it
+   * parses to exactly what was rendered — these whole files, these deletes, one stamp, no edit for a path that was
+   * not sent as edits (a test report can carry a block) — and every edited path rebuilds its tree bytes. `failing`
+   * names the edited paths to demote: every one of them when the artifact itself is wrong.
+   */
+  function checkArtifact(out) {
+    let p;
+    try { p = extractFileBlocks(out.text); } catch (e) { return { ok: false, failing: out.edited, why: `it does not parse (${e.message})` }; }
+    const parsedFiles = p.files.map((f) => f.path);
+    const why = p.malformed.length ? `an unreadable block for ${p.malformed[0].path}`
+      : parsedFiles.join('\n') !== out.included.join('\n')
+        ? `the whole files read back differently (sent ${listDiff(out.included, parsedFiles)})`
+        : p.deletes.join('\n') !== deleted.join('\n')
+          ? `the deletes read back differently (sent ${listDiff(deleted, p.deletes)})`
+          : p.edits.some((e) => !out.edited.includes(e.path))
+            ? `it carries an edit for ${p.edits.find((e) => !out.edited.includes(e.path)).path}, which was not sent as edits`
+            : countStampsOutsideFences(out.text) !== 1 ? 'it does not carry exactly one hone-base line' : null;
+    if (why) return { ok: false, failing: out.edited, why };
+    const failing = out.edited.filter((rel) => {
+      const { headText, treeText } = proven.get(rel);
+      const mine = p.edits.filter((e) => e.path === rel);
+      try {
+        return applyEdits(headText, mine, rel) !== treeText || mine.some((e) => countOccurrences(treeText, e.oldString) !== 0);
+      } catch { return true; }
+    });
+    return { ok: failing.length === 0, failing, why: failing.length ? `the edits for ${failing[0]} do not rebuild it` : null };
+  }
+
+  let out = renderOnce(new Set());
+  if (editMode) {
+    let verdict = checkArtifact(out);
+    if (!verdict.ok && verdict.failing.length) {
+      for (const rel of verdict.failing) fallbacks.push({ path: rel, reason: 'proof' });
+      out = renderOnce(new Set(verdict.failing));
+      verdict = checkArtifact(out);
+    }
+    if (!verdict.ok) {
+      throw new Error(`from-tree: the rendered artifact does not rebuild the working tree; nothing was sent — ${verdict.why}. `
+        + 'The patch verbs would read it the same way. Re-run with --contract 2 to send every file whole.');
+    }
   }
 
-  if (testReport) lines.push('### Test run', '', String(testReport).trim(), '');
+  return { text: out.text, files: out.included, edited: out.edited, fallbacks, deletes: deleted, skipped: out.skipped, headSha };
+}
 
-  return { text: lines.join('\n'), files: included, deletes: deleted, skipped };
+/**
+ * HC-GF-399: whether a review diff describes the same base as this render. review-diff.js resolves HEAD itself;
+ * if that is not the commit the render was taken against, HEAD moved during the submit and the diff describes a
+ * different base. A render with no sha (a repository with no commit) cannot disagree.
+ */
+function reviewDiffBaseMatches(reviewDiff, rendered) {
+  if (!reviewDiff || !rendered || !rendered.headSha) return true;
+  return reviewDiff.headSha === rendered.headSha;
 }
 
-module.exports = { renderFromTree, _internal: { fenceFor, looksBinary, collectPaths, MAX_FILE_BYTES } };
+module.exports = {
+  renderFromTree,
+  editorContractsFor,
+  reviewDiffBaseMatches,
+  _internal: {
+    fenceFor, looksBinary, collectPaths, listPaths, MAX_FILE_BYTES, resolveHead, isGitTimeout, HONE_BASE_STAMP_RE,
+    parseHunkHeaders, buildEdits, proveEdits, countStampsOutsideFences, MAX_CONTEXT, RENDER_BUDGET_MS,
+  },
+};

package/package.json

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