@hone-ai/cli 1.33.0 → 1.35.0

package/lib/materialize-diff.js

@@ -22,22 +22,20 @@
 const path = require('node:path');
 
 /**
- * A ```file:<path> fenced block, capturing the path and the verbatim body.
- * Info-string tolerant: ```file:foo, ``` file: foo, ```FILE:foo all match.
+ * The block grammar — `file:` and `edit:` blocks, the OLD/NEW split, `DELETE:` lines — lives in
+ * block-grammar.js, a byte-identical copy of the server's, so the CLI that applies a build and the
+ * server that stores it read the same blocks (HC-GF-290). Its comments carry the history: HC-GF-022
+ * (an empty block), HC-GF-127 (a longer fence for a `file:`), HC-GF-109 (a framed edit body) and
+ * HC-GF-290 (a longer fence for an `edit:`).
  *
- * HC-GF-022: the closing fence is anchored to its OWN LINE (`^...$` under /m).
- * The previous form spelled the terminator `\r?\n``` `, which REQUIRED a newline
- * between the opener and the closer and so could not match an EMPTY block. On a
- * legitimately empty file (`flowforge/core/__init__.py` — every Python package
- * has one) the body then swallowed its own closing fence, matched the NEXT
- * block's opening fence as its terminator, and consumed it: the empty file was
- * written containing a literal ``` `, and the following file — 2,888 bytes of
- * pipeline logic — vanished from the diff entirely. `check-patch` reported
- * "applies cleanly", because the diff git built from the surviving blocks was
- * perfectly valid. Line-anchoring is also strictly better for a body that
- * contains an indented or info-tagged fence of its own.
+ * A `file:` block (HC-019n-followup-23) is a whole file. An `edit:` block (HC-019n-followup-27) is for
+ * a file too big to bundle whole (>25K chars, truncated/windowed): step_4 never saw the whole file,
+ * so it emits a unique OLD anchor from the excerpt it WAS shown and its NEW replacement, framed with
+ * conflict markers. The CLI applies OLD→NEW to the REAL full file on disk and lets git build the
+ * diff — so the count stays git's, exactly as for whole-file blocks. See
+ * .github/pipeline/HC-019n-followup-27/architect.md.
  */
-const FILE_BLOCK_RE = /^[ \t]*```[ \t]*file[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?\n([\s\S]*?)^[ \t]*```[ \t]*\r?$/gim;
+const { FILE_BLOCK_RE, EDIT_BLOCK_RE, EDIT_OPEN_RE, EDIT_SPLIT_RE, DELETE_RE } = require('./block-grammar');
 
 /**
  * The line-anchored closer necessarily absorbs the newline that terminates the
@@ -49,39 +47,6 @@ function blockBody(raw) {
   return String(raw == null ? '' : raw).replace(/\r?\n$/, '');
 }
 
-/**
- * A ```edit:<path> fenced block — HC-019n-followup-27. For a file too big to
- * bundle whole (>25K chars, truncated/windowed), step_4 cannot emit a whole-file
- * block (it never saw the whole file). Instead it emits a REGION edit: a unique
- * OLD anchor (from the excerpt it WAS shown) and its NEW replacement, framed with
- * conflict markers. The CLI applies OLD→NEW to the REAL full file on disk and
- * lets git build the diff — so the count stays git's, exactly as for whole-file
- * blocks. See .github/pipeline/HC-019n-followup-27/architect.md.
- */
-const EDIT_BLOCK_RE = new RegExp(
-  '^[ \\t]*```[ \\t]*edit[ \\t]*:[ \\t]*([^\\n`]+?)[ \\t]*\\r?\\n(' +
-    // HC-GF-109: a framed body ends at the fence after its `>>>>>>> NEW` line, so a NEW holding a fence line of its own
-    // (a docstring example, a Markdown file) is not cut short, and it never runs on into the next block.
-    '<{3,}[ \\t]*OLD[ \\t]*\\r?\\n(?:(?!^[ \\t]*```[ \\t]*(?:file|edit)[ \\t]*:)[\\s\\S])*?^>{3,}[ \\t]*NEW[ \\t]*\\r?\\n' +
-    // Anything else runs to the first fence line, and extractFileBlocks reports it as malformed.
-    '|(?:(?!^[ \\t]*```)[\\s\\S])*?' +
-  ')^[ \\t]*```[ \\t]*\\r?$',
-  'gim');
-
-/** HC-GF-109: the opening line of an edit block, whether or not the block parses — compared, so none is lost. */
-const EDIT_OPEN_RE = /^[ \t]*```[ \t]*edit[ \t]*:[ \t]*([^\n`]+?)[ \t]*\r?$/gim;
-
-/**
- * The OLD/NEW split inside an edit block. `<<<<<<< OLD` … `=======` … `>>>>>>> NEW`.
- * Whitespace after the marker word is tolerated; the bodies are captured verbatim
- * (indentation is part of the anchor). An empty NEW deletes the anchor (HC-GF-109) — it used to
- * fail this split, and the block was skipped without a word.
- */
-const EDIT_SPLIT_RE = /^<{3,}[ \t]*OLD[ \t]*\r?\n([\s\S]*?)\r?\n={3,}[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?>{3,}[ \t]*NEW[ \t]*\r?$/m;
-
-/** A `DELETE: <path>` line inside the ## Changed Files section. */
-const DELETE_RE = /^[ \t]*DELETE:[ \t]*(\S.*?)[ \t]*$/gim;
-
 /**
  * Typed error for the region-edit apply path, so a consumer can map it to a
  * distinct exit code and a message that tells step_4 how to fix its anchor.
@@ -108,15 +73,15 @@ class MaterializeError extends Error {
  *   reason: string|null
  * }}
  */
-function extractFileBlocks(output) {
-  const text = String(output || '');
+/**
+ * HC-GF-191: the parser, over an ALREADY-SCOPED string. Split out so the same reading can be run
+ * twice — once over the mandated section, and once over the whole artifact when that section
+ * turned out to hold nothing. It used to compute its own scope, which made "what did the scope
+ * cost us?" a question no caller could ask.
+ */
+function parseBlocksIn(scope) {
   const empty = { files: [], edits: [], deletes: [], malformed: [], noChanges: false, reason: null };
 
-  // Scope everything to the ## Changed Files section if present, so a code
-  // sample elsewhere in the prose is never mistaken for an intended file.
-  const secIdx = text.search(/^##\s+Changed Files/im);
-  const scope = secIdx === -1 ? text : text.slice(secIdx);
-
   // Honest no-op, same shape as the followup-19 NO CHANGES escape. A NO CHANGES
   // declaration only counts when there is NO file AND NO edit block to apply.
   const hasBlock = (FILE_BLOCK_RE.test(scope) || EDIT_OPEN_RE.test(scope));
@@ -129,11 +94,12 @@ function extractFileBlocks(output) {
   const files = [];
   const seen = new Set();
   for (const m of scope.matchAll(FILE_BLOCK_RE)) {
-    const rel = normalizeRepoPath(m[1]);
+    // HC-GF-127: m[1] is the fence itself now, so the path and body moved to m[2]/m[3].
+    const rel = normalizeRepoPath(m[2]);
     if (!rel) continue;            // rejected (traversal/absolute) — see below
     if (seen.has(rel)) continue;   // first block wins on a dup path
     seen.add(rel);
-    files.push({ path: rel, contents: blockBody(m[2]) });
+    files.push({ path: rel, contents: blockBody(m[3]) });
   }
 
   // HC-019n-followup-27: region edits for files too big to bundle whole.
@@ -146,10 +112,10 @@ function extractFileBlocks(output) {
   const parsedAt = new Set();
   for (const m of scope.matchAll(EDIT_BLOCK_RE)) {
     parsedAt.add(m.index);
-    const rel = normalizeRepoPath(m[1]);
+    const rel = normalizeRepoPath(m[2]);  // HC-GF-290: m[1] is the fence now
     if (!rel) continue;
     if (seen.has(rel)) continue;   // a whole-file block wins
-    const split = EDIT_SPLIT_RE.exec(m[2]);
+    const split = EDIT_SPLIT_RE.exec(m[3]);
     if (!split) {                  // no OLD/NEW markers: reported, and buildDiff refuses the patch
       malformed.push({ path: rel, reason: 'no <<<<<<< OLD / ======= / >>>>>>> NEW markers' });
       continue;
@@ -212,6 +178,49 @@ function applyEdit(fileContents, oldString, newString, repoPath) {
   return src.slice(0, idx) + String(newString) + src.slice(idx + anchor.length);
 }
 
+/**
+ * HC-GF-265 — the two-index diagnosis. BYTE-IDENTICAL to the copy in
+ * server/src/services/carry-forward.js (the server cannot require the CLI package, so the
+ * wording is restated, not imported); parity is pinned by
+ * tests/regression/HC-GF-265-diagnosis-message-parity.test.js.
+ */
+function destroyedAnchorSuffix(j, k, total) {
+  return `Edit ${j} of ${total} rewrote this anchor: it matched before edit ${j} was applied and not after. `
+    + `Merge edits ${j} and ${k} into ONE edit whose OLD is the text as it stands before either change.`;
+}
+
+/**
+ * HC-GF-265 — which EARLIER edit destroyed edit k's anchor. Returns a 0-based index, or null.
+ *
+ * Runs only on the failure path, so an accept/reject outcome cannot change: nothing is
+ * pre-checked. Edit ORDER is load-bearing (HC-GF-109, run 1a8940af), so the earlier edits are
+ * REPLAYED over the original base rather than matched against it — which is why run 011f04c7,
+ * where two edits share an OLD first line and both apply, is never touched.
+ *
+ * null means "today's message": the anchor matched at no stage of the replay (the HC-GF-222 shape,
+ * explicitly out of scope), the anchor is empty, or no earlier edit stopped it matching. An anchor
+ * absent from the ORIGINAL file is still replayed: an earlier edit may have inserted it (HC-GF-109). Never fabricates
+ * a pair. The LAST >0→0 transition wins: if edit j destroys the anchor and a later edit
+ * re-inserts it, the culprit is the edit after the re-insertion, not j.
+ */
+function diagnoseDestroyedAnchor(baseContents, edits, k) {
+  const anchor = String((edits[k] && edits[k].oldString) || '');
+  if (!anchor || k < 1) return null;
+  let cur = String(baseContents);
+  let lastBreak = null;
+  for (let j = 0; j < k; j++) {
+    let next;
+    try {
+      next = applyEdit(cur, edits[j].oldString, edits[j].newString, '');
+    } catch {
+      return lastBreak;   // replay diverged — report only what is established, never a guess
+    }
+    if (countOccurrences(cur, anchor) > 0 && countOccurrences(next, anchor) === 0) lastBreak = j;
+    cur = next;
+  }
+  return lastBreak;
+}
+
 /**
  * HC-GF-109 — apply every region edit for ONE file, as one change.
  *
@@ -229,9 +238,21 @@ function applyEdit(fileContents, oldString, newString, repoPath) {
  * @throws {MaterializeError} code 'anchor_not_found' | 'anchor_ambiguous'
  */
 function applyEdits(fileContents, edits, repoPath) {
-  let out = String(fileContents);
+  const base = String(fileContents);
+  let out = base;
   edits.forEach((e, i) => {
-    out = applyEdit(out, e.oldString, e.newString, edits.length > 1 ? `${repoPath} (edit ${i + 1} of ${edits.length})` : repoPath);
+    const where = edits.length > 1 ? `${repoPath} (edit ${i + 1} of ${edits.length})` : repoPath;
+    try {
+      out = applyEdit(out, e.oldString, e.newString, where);
+    } catch (err) {
+      // HC-GF-265: only the not-found case is diagnosed. `anchor_ambiguous` already names the
+      // edit and is out of scope (HC-GF-109 pins its message), so it is rethrown untouched.
+      if (!(err instanceof MaterializeError) || err.code !== 'anchor_not_found') throw err;
+      const j = diagnoseDestroyedAnchor(base, edits, i);
+      if (j === null) throw err;
+      throw new MaterializeError('anchor_not_found',
+        `${err.message} ${destroyedAnchorSuffix(j + 1, i + 1, edits.length)}`);
+    }
   });
   return out;
 }
@@ -417,7 +438,6 @@ function ensureTrailingNewline(s) {
  */
 function nodeMaterializeIO({ cwd = process.cwd() } = {}) {
   const fs = require('node:fs');
-  const os = require('node:os');
   const p = require('node:path');
   const { execFileSync } = require('node:child_process');
   const { gitEnv } = require('./git-env');
@@ -429,9 +449,10 @@ function nodeMaterializeIO({ cwd = process.cwd() } = {}) {
       return fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
     },
     tmpFile: (contents) => {
-      const tp = p.join(os.tmpdir(), `hone-mat-${process.pid}-${Date.now()}-${n++}`);
-      fs.writeFileSync(tp, contents);
-      return { path: tp, cleanup: () => { try { fs.unlinkSync(tp); } catch { /* best-effort */ } } };
+      // HC-GF-304: its own directory, not a name in the shared one that another local user can predict and plant.
+      const t = require('./private-temp').privateTempFile('hone-mat', `candidate-${n++}`);
+      fs.writeFileSync(t.file, contents);
+      return { path: t.file, cleanup: t.remove };
     },
     runGitDiff: (origArg, candPath) => {
       let stdout = '', code = 0;
@@ -493,6 +514,51 @@ function hasMaterializableWork(blocks) {
     (blocks.deletes || []).length > 0 || (blocks.malformed || []).length > 0;
 }
 
+
+/**
+ * Read the file / edit / delete blocks an agent emitted.
+ *
+ * Scoped to `## Changed Files` when that heading exists, so a code sample elsewhere in the prose
+ * is never mistaken for an intended file — the guard is right and is kept.
+ *
+ * HC-GF-191: what the guard could not survive is the heading arriving AFTER the blocks. On run
+ * 44a0c69f the builder emitted a complete implementation under `## Implementation Code` and then a
+ * `## Changed Files` SUMMARY below it, so the slice began past every block: 0 files, 0 edits, and
+ * 0 malformed. verify-patch reported "produced no file changes to verify" for a finished build,
+ * with nothing anywhere saying a section had been skipped.
+ *
+ * The fallback is narrow on purpose. It fires ONLY when the scoped section yields nothing, so
+ * wherever the mandated section holds real blocks there is nothing to confuse them with and the
+ * scope still wins. And it is never silent: `scopeFallback` plus a reason name the deviation,
+ * because a guard that quietly changes what it read is precisely how this defect reached a run.
+ *
+ * @param {string} output raw agent artifact
+ * @returns {{files: Array, edits: Array, deletes: Array, malformed: Array, noChanges: boolean,
+ *            reason: string|null, scopeFallback?: boolean}}
+ */
+function extractFileBlocks(output) {
+  const text = String(output || '');
+  const secIdx = text.search(/^##\s+Changed Files/im);
+  if (secIdx === -1) return parseBlocksIn(text);
+
+  const scoped = parseBlocksIn(text.slice(secIdx));
+  if (hasMaterializableWork(scoped) || scoped.noChanges) return scoped;
+
+  // The mandated section held nothing. Before calling that "no changes", look at the whole
+  // artifact — the difference between "there is nothing to apply" and "what there is, is
+  // somewhere else" is the difference between an honest no-op and a lost build.
+  const whole = parseBlocksIn(text);
+  if (!hasMaterializableWork(whole)) return scoped;
+
+  return {
+    ...whole,
+    scopeFallback: true,
+    reason: 'blocks were found OUTSIDE the `## Changed Files` section and read from the whole '
+      + 'artifact instead. The code-builder contract puts them under that heading; emitting them '
+      + 'above it (or under another heading) would otherwise be read as "no changes".',
+  };
+}
+
 module.exports = {
   extractFileBlocks,
   normalizeRepoPath,
@@ -503,6 +569,10 @@ module.exports = {
   headMaterializeIO,
   applyEdit,
   applyEdits,
+  // HC-GF-265: exported so the resolved pair is asserted by BEHAVIOUR and so the wording can be
+  // compared against carry-forward.js's copy directly, not inferred from a message regex.
+  destroyedAnchorSuffix,
+  diagnoseDestroyedAnchor,
   hasMaterializableWork,
   EDIT_OPEN_RE,
   countOccurrences,

package/lib/mcp-tools.js

@@ -164,18 +164,39 @@ async function stepInstruction({ runId, cwd } = {}) {
 // hone_submit_step — submit editor-executed output (HC-COMM-010 B3). Output
 // travels via a temp file (1MB-class payloads must not ride argv); the file
 // is best-effort deleted after the shell-out.
-async function submitStep({ runId, stepKey, output, contractVersion = '1', cwd } = {}) {
+async function submitStep({ runId, stepKey, output, contractVersion = '1', fromTree = false, testReport, cwd } = {}) {
   if (!runId) return { isError: true, detail: 'runId is required' };
   if (!stepKey) return { isError: true, detail: 'stepKey is required' };
-  if (typeof output !== 'string' || output.trim() === '') {
-    return { isError: true, detail: 'output is required (the complete step output text)' };
+
+  // HC-GF-130: DELEGATE the from-tree render to the CLI rather than rendering here and submitting
+  // the result with `--file`. That is what shipped in HC-GF-091, and HC-GF-092's guard — which
+  // refuses `--contract 2` without `--from-tree` — turned the one caller that HAD built from the
+  // tree away. The guard reads the flag, not the provenance, so the adopter's primary path was
+  // blocked while the CLI fallback worked. Delegating also removes a second producer of the same
+  // artifact, which is the shape HC-GF-127 had to unpick across three parsers.
+  const hasOutput = typeof output === 'string' && output.trim() !== '';
+  if (fromTree && hasOutput) {
+    return { isError: true, detail: 'pass output OR fromTree, not both: they are two different claims about where the build is' };
   }
-  const tmp = path.join(os.tmpdir(), `hone-editor-output-${Date.now()}-${process.pid}.txt`);
-  try {
+  if (!fromTree && !hasOutput) {
+    return { isError: true, detail: 'output is required (the complete step output text), or set fromTree' };
+  }
+
+  const base = ['submit-step', String(runId), String(stepKey), '--contract', String(contractVersion), '--format', 'json'];
+  let tmp = null;
+  if (fromTree) {
+    base.push('--from-tree');
+    // Never invented: an absent report stays absent, the same rule the CLI and the prompt carry.
+    if (typeof testReport === 'string' && testReport.trim() !== '') base.push('--test-report', testReport);
+  } else {
+    // Output travels via a temp file — 1MB-class payloads must not ride argv.
+    tmp = path.join(os.tmpdir(), `hone-editor-output-${Date.now()}-${process.pid}.txt`);
     fsSync.writeFileSync(tmp, output, 'utf8');
-    const r = await runHone(
-      ['submit-step', String(runId), String(stepKey), '--file', tmp, '--contract', String(contractVersion), '--format', 'json'],
-      { cwd });
+    base.push('--file', tmp);
+  }
+
+  try {
+    const r = await module.exports._internal.runHone(base, { cwd });
     if (r.error) return { isError: true, detail: r.error };
     const data = parseLastJson(r.stdout);
     return {
@@ -188,7 +209,7 @@ async function submitStep({ runId, stepKey, output, contractVersion = '1', cwd }
         : (r.stderr || r.stdout || 'submission failed').slice(0, 500),
     };
   } finally {
-    try { fsSync.unlinkSync(tmp); } catch { /* best-effort cleanup */ }
+    if (tmp) { try { fsSync.unlinkSync(tmp); } catch { /* best-effort cleanup */ } }
   }
 }
 
@@ -432,10 +453,12 @@ const TOOLS = [
       properties: {
         runId: { type: 'string' },
         stepKey: { type: 'string' },
-        output: { type: 'string' },
+        output: { type: 'string', description: 'The complete step output text. Omit when fromTree is true.' },
         contractVersion: { type: 'string', default: '1' },
+        fromTree: { type: 'boolean', default: false, description: 'HC-GF-091: render the artifact from the working tree against HEAD — write the files with your own tools first, then submit. Removes the single-response output ceiling.' },
+        testReport: { type: 'string', description: 'With fromTree: your test-run report, carried verbatim. Omit if you did not run them; it is never invented for you.' },
       },
-      required: ['runId', 'stepKey', 'output'],
+      required: ['runId', 'stepKey'],
     },
     handler: submitStep,
   },
@@ -455,4 +478,6 @@ module.exports = {
   killWorkflow,
   runStory, status, verifyPatch, checkPatch, showStep, approve, emitPr, verifyPr, agentEval, derive, sync, doctor,
   runHone, parseRunStarted, parseLastJson, honeBin, readHoneConfig, TOOLS,
+  // HC-GF-130: exposed so a test can observe the argv handed to the CLI without running it.
+  _internal: { runHone },
 };

package/lib/pipeline-config.js

@@ -388,6 +388,47 @@ function readExecutionMode(repoRoot) {
   return DEFAULT_EXECUTION_MODE;
 }
 
+/**
+ * HC-GF-097: the execution mode AS WRITTEN, beside the normalized one. `readExecutionMode` maps any
+ * value it does not know to 'server', which is the right default for a run an operator is
+ * watching — and the wrong one for an unattended overnight batch, where "server" is a guess about a
+ * typo nobody will see. queue-stories refuses `--overnight` on an unrecognised mode, so it has to
+ * be able to tell `mode: edtior` from no `mode:` at all. Same candidate order as readExecutionMode.
+ *
+ * @param {string} repoRoot
+ * @returns {{ raw: string|null, mode: 'server'|'editor', recognized: boolean }}
+ *   raw is null when no config declares a mode (the default is a recognised state).
+ */
+function readExecutionModeRaw(repoRoot) {
+  const none = { raw: null, mode: DEFAULT_EXECUTION_MODE, recognized: true };
+  if (!repoRoot || typeof repoRoot !== 'string') return none;
+  const candidates = [
+    path.join(repoRoot, '.pipeline-config.yml'),
+    path.join(repoRoot, '.github/.pipeline-config.yml'),
+  ];
+  for (const p of candidates) {
+    if (!fs.existsSync(p)) continue;
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
+    let parsed;
+    try {
+      const yaml = require('js-yaml');
+      parsed = yaml.load(raw);
+    } catch { continue; }
+    if (!parsed || typeof parsed !== 'object') continue;
+    const block = parsed.execution;
+    if (!block || typeof block !== 'object') continue;
+    if (block.mode === undefined) continue;
+    const written = String(block.mode == null ? '' : block.mode);
+    return {
+      raw: written,
+      mode: normalizeExecutionMode(block.mode),
+      recognized: EXECUTION_MODES.includes(written.toLowerCase().trim()),
+    };
+  }
+  return none;
+}
+
 // ── HC-019n-followup-34: closed-loop verification gate ────────────────────────
 // The CLI verbs (verify-patch/verify-pr) EXECUTE and report a verdict to the
 // server. `verification.gate` controls what the server does with it:
@@ -542,7 +583,147 @@ function readAgentEvalConfig(repoRoot) {
   return { targets: [] };
 }
 
+
+// ── HC-GF-169: the adopter-declared scratch datastore ────────────────────────────────────────
+//
+// `.pipeline-config.yml` had no data-layer concept, so no step could validate behaviour needing
+// stored state — which is most of an adopter's backend. The contract is the one `ci.local_command`
+// already uses: Hone cannot know their datastore, so the adopter declares it and the CLI executes
+// it adopter-side, where `verify-patch` already runs with their credentials.
+//
+// THE GUARD IS THE LOAD-BEARING PART. Seeding test rows into a customer's production database is
+// the worst outcome this design can produce, so `verify` is REQUIRED whenever commands are declared
+// and the assertion reads the LIVE CONNECTION, never the URL. A URL can spell `_sandbox` and point
+// anywhere — DNS, a pooler, a tunnel, an overridden PGDATABASE.
+//
+// HC-GF-183, learned from the first live run: THE DATABASE AND THE VERIFY TABLE MUST ALREADY
+// EXIST. The probe runs BEFORE `create` — deliberately, because proving a target is scratch has to
+// precede writing to it — so there is nothing for it to read on a fresh database. That makes
+// `create` responsible for the TABLES, not the database: an adopter writing `create: createdb foo`
+// is refused on their first run with nothing explaining why. Provision the database itself once,
+// out of band, then let `create` build the schema inside it.
+//
+// And `reset` must leave the sandbox PROBEABLE. The CLI runs `reset` then `create` as the teardown
+// (see cli/lib/sandbox-lifecycle.js) precisely so a reset that drops the schema cannot brick the
+// next run — which is exactly what happened the first time this was declared against a real
+// database.
+//
+// Wired since HC-GF-171: verify-patch probes, guards, seeds and tears down.
+const SANDBOX_COMMAND_KEYS = Object.freeze(['create', 'migrate', 'reset']);
+
+/**
+ * @param {string} repoRoot
+ * @returns {null | {create: string|null, migrate: string|null, reset: string|null,
+ *                   capabilities: string[], verify: {database: string, table: string, max_rows: number}}}
+ * @throws when a sandbox declares commands without a usable `verify` block.
+ */
+function readSandboxConfig(repoRoot) {
+  if (!repoRoot || typeof repoRoot !== 'string') return null;
+  for (const p of [path.join(repoRoot, '.pipeline-config.yml'),
+                   path.join(repoRoot, '.github/.pipeline-config.yml')]) {
+    if (!fs.existsSync(p)) continue;
+    let parsed;
+    try { parsed = require('js-yaml').load(fs.readFileSync(p, 'utf8')); } catch { continue; }
+    const block = parsed && typeof parsed === 'object' ? parsed.sandbox : null;
+    if (!block || typeof block !== 'object') continue;
+
+    const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+    const commands = {};
+    for (const k of SANDBOX_COMMAND_KEYS) commands[k] = str(block[k]);
+    const declaresWork = SANDBOX_COMMAND_KEYS.some(k => commands[k]);
+
+    const v = block.verify && typeof block.verify === 'object' ? block.verify : null;
+    // HC-GF-171: `probe` is the command that PRODUCES the evidence `assertScratchTarget` demands.
+    // Carried through here, required at ENGAGEMENT (see cli/lib/sandbox-lifecycle.js) rather than
+    // at parse time: a declaration missing it is incomplete, not malformed, and the refusal is far
+    // more useful at the moment the sandbox would have fired — it can name what to add.
+    const verify = v && str(v.database) && str(v.table) && Number.isFinite(Number(v.max_rows))
+      ? { database: str(v.database), table: str(v.table), max_rows: Number(v.max_rows),
+          probe: str(v.probe) }
+      : null;
+
+    if (declaresWork && !verify) {
+      throw new Error(
+        `${p}: sandbox declares ${SANDBOX_COMMAND_KEYS.filter(k => commands[k]).join('/')} but no `
+        + 'usable `verify` block (needs database, table and max_rows). Without it the CLI cannot '
+        + 'prove the target is scratch before writing to it, and an optional guard on this action '
+        + 'is worse than no feature.');
+    }
+    if (!declaresWork && !verify) return null;
+
+    const capabilities = Array.isArray(block.capabilities)
+      ? block.capabilities.map(str).filter(Boolean) : [];
+
+    // HC-GF-192: `test` is the command that READS the sandbox, and `env` is what it reads the
+    // connection from. Carried here and required at ENGAGEMENT, for the same reason `probe` is: a
+    // declaration missing them is incomplete rather than malformed, and the refusal is far more
+    // useful at the moment the sandbox would have fired, where it can name what to add.
+    //
+    // Shape is checked in the plan, not here — `env: DATABASE_URL=…` is valid YAML (a string) and
+    // an invalid env map, and refusing it next to the other engagement refusals keeps one place
+    // that decides whether this sandbox can be used.
+    const test = str(block.test);
+    // Passed through UNVALIDATED, deliberately. An earlier draft tested the type here and then
+    // returned `block.env` on both branches — a guard that read like validation and changed no
+    // outcome, which is the shape this whole chain keeps finding. The real check is
+    // `plainStringMap` in sandbox-lifecycle.js, where a bad `env` becomes a refusal that names the
+    // fix; duplicating it here would mean two places deciding, and eventually disagreeing.
+    const env = block.env === undefined ? null : block.env;
+
+    return { ...commands, capabilities, verify, test, env };
+  }
+  return null;
+}
+
+/**
+ * Refuse unless the LIVE connection proves the target is scratch.
+ *
+ * @param {{database: string, table: string, max_rows: number}} verify  what the adopter declared
+ * @param {{database?: string, rows?: number, url?: string}} probe      what the SERVER reported
+ * @throws when the probe is absent, incomplete, names another database, or the target is populated.
+ */
+function assertScratchTarget(verify, probe) {
+  if (!verify || typeof verify !== 'object') {
+    throw new Error('sandbox verify block missing — refusing to treat any target as scratch');
+  }
+  if (!probe || typeof probe !== 'object') {
+    throw new Error('no live probe — refusing to write. "Could not check" is not "checked and '
+      + 'found nothing"; run the probe or stop.');
+  }
+  // `probe.url` is deliberately ignored. It is accepted only so a caller passing it for logging
+  // cannot mistake this for a check of it.
+  const live = typeof probe.database === 'string' ? probe.database.trim() : null;
+  if (!live) {
+    throw new Error('the probe reported no database name — refusing. The name must come from the '
+      + 'server (e.g. `SELECT current_database()`), not from the connection string.');
+  }
+  if (live !== verify.database) {
+    throw new Error(
+      `refusing to write: the live connection reports database "${live}", but the sandbox declares `
+      + `"${verify.database}". A connection string can spell the sandbox name and still point `
+      + 'elsewhere.');
+  }
+  // A real NUMBER, not something that coerces to one. `Number(null)`, `Number('')`,
+  // `Number(false)` and `Number([])` are all 0, so a probe that reported nothing would read as an
+  // empty database and be allowed — the exact "could not check treated as checked" this refuses.
+  if (typeof probe.rows !== 'number' || !Number.isFinite(probe.rows)) {
+    throw new Error(`refusing to write to "${live}": no row count was probed `
+      + `(got ${JSON.stringify(probe.rows)}). A name match alone is not proof — a restored copy of `
+      + 'production can carry the scratch name.');
+  }
+  const rows = probe.rows;
+  if (rows > verify.max_rows) {
+    throw new Error(
+      `refusing to write to "${live}": ${verify.table} holds ${rows} rows, above the declared `
+      + `ceiling of ${verify.max_rows}. This looks like real data.`);
+  }
+  return true;
+}
+
 module.exports = {
+  readSandboxConfig,
+  assertScratchTarget,
+  SANDBOX_COMMAND_KEYS,
   readSourceDirs,
   readCodebaseDefaults,
   readCIConfigDetails,
@@ -551,6 +732,7 @@ module.exports = {
   EDITOR_MODE_CONSENT_NOTE,
   normalizeExecutionMode,
   readExecutionMode,
+  readExecutionModeRaw,
   readStoryClassifierConfig,
   KNOWN_THRESHOLD_KEYS,
   readCIGateConfig,

package/lib/private-temp.js

@@ -0,0 +1,34 @@
+'use strict';
+/**
+ * private-temp.js — HC-GF-304. A temp file no other process can share.
+ *
+ * check-patch, verify-patch and emit-pr named their diff `os.tmpdir()/hone-<verb>-${Date.now()}.diff`. Two of
+ * them started in the same millisecond on one machine (two worktrees, the MCP server beside the CLI, the
+ * regression suite's parallel files) wrote the SAME path, so one applied, verified or committed the other's
+ * patch. On the runner it was caught applying HC-GF-077's `src/app.js` diff inside HC-GF-098's test repository.
+ * A verify-patch that reads another run's diff can report a pass for a patch that is not its run's, and under
+ * `verification_gate: enforce` that pass approves step_4.
+ *
+ * A clock is not an identity. `fs.mkdtempSync` creates a new directory with a random suffix, atomically, with
+ * mode 0700, so the file inside it belongs to exactly one invocation whatever the time, and nobody else can
+ * plant or replace it.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+/**
+ * @param {string} prefix  names the owner in the directory, e.g. 'hone-emit'
+ * @param {string} name    the file's name inside its private directory, e.g. 'patch.diff'
+ * @returns {{ file: string, remove: () => void }}  `remove` deletes the directory and never throws
+ */
+function privateTempFile(prefix, name) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+  return {
+    file: path.join(dir, name),
+    remove: () => { try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ } },
+  };
+}
+
+module.exports = { privateTempFile };