@hone-ai/cli 1.41.0 → 1.42.0

package/lib/context-reserve.js

@@ -31,7 +31,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { remedyFor, partitionSafePaths, tokenOf, isSafeToken } = require('./hard-pause-remedy');
 const { parseIncludeTarget } = require('./include-paths');
-const { isSecretPath } = require('./bundle-context');
+const { pathRefusal, structuralRefusal } = require('./path-refusal');
 const { isBatchId } = require('./run-target');
 
 /** The start of the reason a re-served run is killed with. The loop reads it back to find the new batch. */
@@ -67,18 +67,6 @@ function hardPauseRequest(run) {
   return remedy && remedy.stepKey === at[1] ? remedy : null;
 }
 
-// Credential-looking names the bundler's own refusal (isSecretPath) does not cover: a public half of a key pair,
-// key containers, anything the author named a secret or a credential.
-const SECRET_LOOKING = [/(^|[._-])id_(rsa|dsa|ecdsa|ed25519)/i, /\.(key|pfx|jks|keystore|p8)$/i, /(secret|credential)/i];
-
-/** Why a path is not a plain relative path, or null. `file` has no `:line` or `:symbol` suffix. */
-function structuralRefusal(file) {
-  if (typeof file !== 'string' || file === '') return 'empty';
-  if (/^[-/~]/.test(file)) return 'absolute, home-relative or option-like';
-  if (/[\\\0]/.test(file)) return 'not a plain relative path';
-  if (file.split('/').some((s) => s === '' || s === '.' || s === '..')) return 'not a plain relative path';
-  return null;
-}
 
 /**
  * Why the CONTENT of a path (a plain file path, no `:line`) must not be sent to a model, or null: the three
@@ -87,11 +75,7 @@ function structuralRefusal(file) {
  * @param {string} file
  */
 function contentRefusal(file) {
-  const plain = structuralRefusal(file);
-  if (plain) return plain;
-  if (isSecretPath(file) || SECRET_LOOKING.some((re) => re.test(path.posix.basename(file)))) return 'looks like a credential file';
-  if (file.split('/').some((s) => s.startsWith('.'))) return 'a hidden file or directory';
-  return null;
+  return pathRefusal(file, { mode: 'content' });
 }
 
 /**

package/lib/default-api.js

@@ -0,0 +1,109 @@
+'use strict';
+/**
+ * HC-GF-396: the one place the CLI decides which Hone API host it talks to.
+ *
+ * The old compiled default, https://api.hone.ai, sits on a domain the owner does not hold (it is listed
+ * for sale), so whoever buys it could receive every adopter's Bearer token and admin key. The default
+ * is now the Railway host production already serves, and every source of an API URL — `--api`,
+ * `HONE_API`, `~/.honerc` `api` — goes through `resolveApiUrl()`, which refuses a retired host however
+ * it is spelled (case, port, path, trailing dot, subdomain) and refuses anything that is not an
+ * http(s) URL.
+ *
+ * Design: docs/architecture/HC-GF-396-default-api-host.md. Copies of DEFAULT_API that cannot require
+ * this file (the server, files installed into adopter repos) are held equal to it by
+ * tests/regression/HC-GF-396-default-api-agreement.test.js.
+ */
+
+const DEFAULT_API = 'https://hone-server-production.up.railway.app';
+const RETIRED_HOSTS = ['hone.ai'];
+
+/**
+ * Classify one candidate value.
+ * Returns { ok: true, value, hostname } for a usable http(s) URL on a host that is not retired,
+ * { ok: false, reason: 'retired', hostname } for a retired host, and { ok: false, reason: 'invalid' }
+ * for anything that does not parse or is not http(s). `hostname` is lower-cased with one trailing
+ * dot removed; it is the only part of the value any message may print.
+ */
+function classifyApiUrl(value) {
+  if (typeof value !== 'string') return { ok: false, reason: 'invalid' };
+  let u;
+  try { u = new URL(value.trim()); } catch { return { ok: false, reason: 'invalid' }; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return { ok: false, reason: 'invalid' };
+  let hostname = u.hostname.toLowerCase();
+  if (hostname.endsWith('.')) hostname = hostname.slice(0, -1);
+  if (!hostname) return { ok: false, reason: 'invalid' };
+  const retired = RETIRED_HOSTS.some((h) => hostname === h || hostname.endsWith(`.${h}`));
+  if (retired) return { ok: false, reason: 'retired', hostname };
+  return { ok: true, value: value.trim(), hostname };
+}
+
+/** The hostname of a URL for display, or a fixed placeholder when it does not parse. */
+function apiHostname(value) {
+  try { return new URL(value).hostname; } catch { return '(unparseable URL)'; }
+}
+
+const SOURCE_LABEL = { env: 'HONE_API', rc: '~/.honerc "api"' };
+
+function describeRefusal(label, verdict) {
+  return verdict.reason === 'retired'
+    ? `${label} names ${verdict.hostname}, a retired host that is no longer a Hone server`
+    : `${label} is not a valid http(s) URL`;
+}
+
+// One warning per process: stdout carries the MCP stdio transport, and a command that resolves the
+// URL twice should not print the same warning twice.
+let _warned = false;
+function _resetWarningForTests() { _warned = false; }
+
+const present = (v) => v !== undefined && v !== null && v !== '';
+
+/**
+ * Resolve the API base URL. Order: `flag` (only `hone init --api`) → `env` (HONE_API) → `rc`
+ * (~/.honerc api) → DEFAULT_API.
+ *
+ * A retired or invalid `flag` is an error: the result carries `error` and no `apiUrl`, and the caller
+ * exits 2 without sending anything. A retired or invalid `env` or `rc` counts as UNSET, so resolution
+ * falls through to the next source, and one warning naming the hostname only goes to stderr.
+ *
+ * @returns {{ apiUrl: string|null, source: 'flag'|'env'|'rc'|'default', error?: string }}
+ */
+function resolveApiUrl({ flag, env, rc } = {}, { warn = (m) => process.stderr.write(`${m}\n`) } = {}) {
+  if (present(flag)) {
+    const v = classifyApiUrl(flag);
+    if (v.ok) return { apiUrl: v.value, source: 'flag' };
+    return {
+      apiUrl: null,
+      source: 'flag',
+      error: `${describeRefusal('--api', v)}. Omit --api to use the default, ${DEFAULT_API}.`,
+    };
+  }
+  const refused = [];
+  for (const [source, value] of [['env', env], ['rc', rc]]) {
+    if (!present(value)) continue;
+    const v = classifyApiUrl(value);
+    if (v.ok) {
+      if (refused.length) _warnOnce(refused, source, v.hostname, warn);
+      return { apiUrl: v.value, source };
+    }
+    refused.push(describeRefusal(SOURCE_LABEL[source], v));
+  }
+  if (refused.length) _warnOnce(refused, 'default', apiHostname(DEFAULT_API), warn);
+  return { apiUrl: DEFAULT_API, source: 'default' };
+}
+
+function _warnOnce(refused, source, hostname, warn) {
+  if (_warned) return;
+  _warned = true;
+  const using = source === 'default' ? `the default host ${hostname}` : `${SOURCE_LABEL[source]} (${hostname})`;
+  warn(`Warning: ${refused.join('; ')}, so it is ignored. Using ${using}. ` +
+    'Fix it with hone init --api <url>, or unset HONE_API.');
+}
+
+module.exports = {
+  DEFAULT_API,
+  RETIRED_HOSTS,
+  classifyApiUrl,
+  resolveApiUrl,
+  apiHostname,
+  _resetWarningForTests,
+};

package/lib/editor-park.js

@@ -27,14 +27,20 @@ function isEditorParked(status) {
 /**
  * The parked-state copy (ux-copy pass, 2026-09-05): what happened, where it is,
  * the two ways forward (editor MCP tools / CLI verbs), and the closing step.
+ *
+ * The submit command depends on the contract step-instruction is served, which this copy is printed
+ * before: `--file` is refused under contracts 2 and 3. So it shows each form beside the contract it
+ * belongs to and sends the operator to the one step-instruction prints, never to a lone `--file`.
  */
 function editorParkedGuidance(runId, stepKey, agent) {
   const a = agent ? ` (${agent})` : '';
   return [
     `⏸ Parked for your editor at ${stepKey}${a} — this step runs in your editor AI, not on Hone.`,
-    `  In Claude Code:  call hone_step_instruction, build the step there, then hone_submit_step.`,
+    `  In Claude Code:  call hone_step_instruction, build the step there, then hone_submit_step as it says.`,
     `  From the CLI:    hone step-instruction ${runId}`,
-    `                   … build … then: hone submit-step ${runId} ${stepKey} --file out.md`,
+    `                   … build … then submit with the command it prints for its contract:`,
+    `                     contract 2 or 3: hone submit-step ${runId} ${stepKey} --from-tree --contract <2|3>`,
+    `                     contract 1:      hone submit-step ${runId} ${stepKey} --file out.md`,
     `  When submitted:  hone run-story ${runId} --approve ${stepKey}`,
     `  Guide: docs/runbooks/editor-mode.md`,
   ].join('\n');

package/lib/materialize-diff.js

@@ -35,7 +35,7 @@ const path = require('node:path');
  * 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, EDIT_BLOCK_RE, EDIT_OPEN_RE, EDIT_SPLIT_RE, DELETE_RE } = require('./block-grammar');
+const { FILE_BLOCK_RE, EDIT_BLOCK_RE, EDIT_OPEN_RE, EDIT_SPLIT_RE, DELETE_RE, fileBlockSpans, matchesOutside } = require('./block-grammar');
 
 /**
  * The line-anchored closer necessarily absorbs the newline that terminates the
@@ -106,11 +106,13 @@ function parseBlocksIn(scope) {
   // HC-GF-109: EVERY edit block for a path, in order. This loop used to keep the first and drop the rest ("first edit
   // wins") while the code-builder prompt asks for `edit:` on a file changed in a few places, so 12 of 24 stored edit
   // blocks never reached the patch, and verify-patch type-checked a settings.py missing four of its five edits.
+  // HC-GF-404: an edit opener or DELETE: line inside a whole file's content is that file's data.
+  const inFile = fileBlockSpans(scope);
   const edits = [];
   const malformed = [];
   const editKeys = new Set();
   const parsedAt = new Set();
-  for (const m of scope.matchAll(EDIT_BLOCK_RE)) {
+  for (const m of matchesOutside(EDIT_BLOCK_RE, scope, inFile)) {
     parsedAt.add(m.index);
     const rel = normalizeRepoPath(m[2]);  // HC-GF-290: m[1] is the fence now
     if (!rel) continue;
@@ -126,14 +128,14 @@ function parseBlocksIn(scope) {
     editKeys.add(key);
     edits.push(edit);
   }
-  for (const m of scope.matchAll(EDIT_OPEN_RE)) {
+  for (const m of matchesOutside(EDIT_OPEN_RE, scope, inFile)) {
     if (parsedAt.has(m.index)) continue;
     const rel = normalizeRepoPath(m[1]);
     if (rel && !seen.has(rel)) malformed.push({ path: rel, reason: 'no closing fence' });
   }
 
   const deletes = [];
-  for (const m of scope.matchAll(DELETE_RE)) {
+  for (const m of matchesOutside(DELETE_RE, scope, inFile)) {
     const rel = normalizeRepoPath(m[1]);
     if (rel && !deletes.includes(rel)) deletes.push(rel);
   }
@@ -272,19 +274,20 @@ function countOccurrences(hay, needle) {
 /**
  * Assemble one unified diff from parsed blocks — the SHARED materialization used
  * by check-patch, verify-patch, and emit-pr (HC-019n-followup-27 de-triplicated
- * what was three copies of this loop). Whole-file blocks, region edits, and
- * deletes all resolve to git-authored hunks.
+ * what was three copies of this loop). Whole-file blocks and region edits resolve
+ * to git-authored hunks; a delete is a hand-built removal hunk, headed as `git diff` heads one.
  *
  * Injected primitives keep it testable without a real repo:
  *   - runGitDiff(origArg, candidatePath) → { stdout, code }  (git diff --no-index)
  *   - readFile(repoRelPath) → string|null                    (real full file, or null)
  *   - exists(repoRelPath) → boolean
  *   - tmpFile(contents) → { path, cleanup }                  (write a temp candidate)
+ *   - fileMode(repoRelPath) → '100644'|'100755'|null         (optional; a deletion's mode line, 100644 when absent)
  *
  * @returns {{ diff: string, partCount: number }}
  * @throws {MaterializeError} from the region-edit apply path
  */
-function buildDiff(blocks, { runGitDiff, readFile, exists, tmpFile }) {
+function buildDiff(blocks, { runGitDiff, readFile, exists, tmpFile, fileMode }) {
   const parts = [];
 
   // HC-GF-109: an edit block that could not be read is work that would otherwise vanish from the patch. Refuse the whole
@@ -335,15 +338,22 @@ function buildDiff(blocks, { runGitDiff, readFile, exists, tmpFile }) {
     } finally { t.cleanup(); }
   }
 
-  // 3. Deletions — a whole-file removal hunk against the real file on disk.
+  // 3. Deletions — a whole-file removal hunk against the real file on disk, headed as `git diff` heads one.
+  //    Without the `deleted file mode` line git apply reads `+++ /dev/null` as a new file at `dev/null`: it deletes
+  //    the file AND leaves `dev/null` in the tree, which emit-pr's `git add -A` then commits.
   for (const del of blocks.deletes || []) {
     if (!exists(del)) continue;
     const body = readFile(del);
     if (body == null) continue;
-    const lines = body.replace(/\n$/, '').split('\n');
-    parts.push(
-      `diff --git a/${del} b/${del}\n--- a/${del}\n+++ /dev/null\n` +
-      `@@ -1,${lines.length} +0,0 @@\n` + lines.map(l => `-${l}`).join('\n') + '\n');
+    const mode = (fileMode && fileMode(del)) || '100644';
+    let part = `diff --git a/${del} b/${del}\ndeleted file mode ${mode}\n`;
+    if (body !== '') {
+      const lines = body.replace(/\n$/, '').split('\n');
+      part += `--- a/${del}\n+++ /dev/null\n` +
+        `@@ -1,${lines.length} +0,0 @@\n` + lines.map(l => `-${l}`).join('\n') + '\n' +
+        (body.endsWith('\n') ? '' : '\\n');
+    }
+    parts.push(part);
   }
 
   return { diff: parts.join(''), partCount: parts.length };
@@ -434,7 +444,7 @@ function ensureTrailingNewline(s) {
  * stays side-effect-free to import for the pure-function unit tests.
  *
  * @param {{cwd?: string}} [o]
- * @returns {{ exists: Function, readFile: Function, tmpFile: Function, runGitDiff: Function }}
+ * @returns {{ exists: Function, readFile: Function, fileMode: Function, tmpFile: Function, runGitDiff: Function }}
  */
 function nodeMaterializeIO({ cwd = process.cwd() } = {}) {
   const fs = require('node:fs');
@@ -448,6 +458,9 @@ function nodeMaterializeIO({ cwd = process.cwd() } = {}) {
       const abs = p.resolve(cwd, rel);
       return fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
     },
+    fileMode: (rel) => {
+      try { return (fs.statSync(p.resolve(cwd, rel)).mode & 0o111) ? '100755' : '100644'; } catch { return null; }
+    },
     tmpFile: (contents) => {
       // 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++}`);
@@ -493,6 +506,12 @@ function headMaterializeIO({ cwd = process.cwd(), rev = 'HEAD' } = {}) {
     ...base,
     exists: (rel) => { try { execFileSync('git', ['cat-file', '-e', `${rev}:${rel}`], opts); return true; } catch { return false; } },
     readFile: show,
+    fileMode: (rel) => {
+      try {
+        const m = execFileSync('git', ['ls-tree', '--full-tree', rev, '--', rel], { ...opts, encoding: 'utf8' }).split(' ')[0];
+        return /^100(644|755)$/.test(m) ? m : null;
+      } catch { return null; }
+    },
     runGitDiff: (origArg, candPath) => {
       if (origArg === '/dev/null') return base.runGitDiff(origArg, candPath);
       const body = show(origArg);

package/lib/mcp-tools.js

@@ -14,6 +14,7 @@ const fsSync = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { privateTempFile } = require('./private-temp');
+const { resolveApiUrl } = require('./default-api'); // HC-GF-396
 
 // Resolve the CLI binary. Default `hone` (the installed bin); overridable for tests
 // / non-global installs via HONE_CLI_BIN (e.g. a path to hone-cli.js run with node).
@@ -32,7 +33,8 @@ function readHoneConfig() {
   let rc = {};
   try { rc = JSON.parse(fsSync.readFileSync(path.join(os.homedir(), '.honerc'), 'utf8')) || {}; } catch { rc = {}; }
   const token = process.env.HONE_TOKEN || rc.token || null;
-  const apiUrl = process.env.HONE_API || rc.api || 'https://api.hone.ai';
+  // HC-GF-396: same resolver as getConfig(); its one warning goes to stderr, never the stdio transport.
+  const { apiUrl } = resolveApiUrl({ env: process.env.HONE_API, rc: rc.api });
   return { apiUrl, hasToken: !!token };
 }
 
@@ -164,7 +166,8 @@ async function stepInstruction({ runId, cwd } = {}) {
   if (!runId) return { isError: true, detail: 'runId is required' };
   const bad = refused([{ label: 'runId', kind: 'runId', value: String(runId) }]);
   if (bad) return bad;
-  const r = await runHone(['step-instruction', String(runId), '--format', 'json'], { cwd });
+  // Through _internal, as submitStep is, so the served-contract wording is tested without spawning `hone`.
+  const r = await module.exports._internal.runHone(['step-instruction', String(runId), '--format', 'json'], { cwd });
   if (r.error) return { isError: true, detail: r.error };
   const data = parseLastJson(r.stdout);
   return {
@@ -173,8 +176,12 @@ async function stepInstruction({ runId, cwd } = {}) {
     stepKey: data ? data.stepKey : null,
     contractVersion: data ? data.contractVersion : null,
     exitCode: r.exitCode,
+    // HC-GF-399: the submit the SERVED contract asks for. submitStep defaults contractVersion to '1', so under 2 and 3
+    // the agent must be told to pass fromTree and the version, or its submission is refused.
     detail: data
-      ? `instruction for ${data.stepKey} (contract ${data.contractVersion}) — execute it and call hone_submit_step with the complete output`
+      ? (String(data.contractVersion) === '1'
+        ? `instruction for ${data.stepKey} (contract 1) — execute it and call hone_submit_step with the complete output`
+        : `instruction for ${data.stepKey} (contract ${data.contractVersion}) — write the files with your own tools, then call hone_submit_step with fromTree: true and contractVersion: '${data.contractVersion}'`)
       : (r.stderr || r.stdout || 'could not fetch instruction').slice(0, 500),
   };
 }
@@ -199,6 +206,11 @@ async function submitStep({ runId, stepKey, output, contractVersion = '1', fromT
   if (!fromTree && !hasOutput) {
     return { isError: true, detail: 'output is required (the complete step output text), or set fromTree' };
   }
+  // HC-GF-399: as the CLI refuses `--contract 3` without `--from-tree` — region edits proven against HEAD exist
+  // only in a render from the tree.
+  if (String(contractVersion) === '3' && !fromTree) {
+    return { isError: true, detail: 'contract 3 is a from-tree contract: write the files with your own tools and set fromTree: true' };
+  }
   // Before the temp file: a refused id writes nothing.
   const bad = refused([
     { label: 'runId', kind: 'runId', value: String(runId) },
@@ -486,14 +498,14 @@ const TOOLS = [
   },
   {
     name: 'hone_step_instruction',
-    description: 'Fetch the editor-mode instruction for a Hone run that is awaiting the editor (execution.mode: editor). Read-only. Execute the returned instruction in THIS session, then call hone_submit_step with the complete output.',
+    description: 'Fetch the editor-mode instruction for a Hone run that is awaiting the editor (execution.mode: editor). Read-only. Execute the returned instruction in THIS session, then call hone_submit_step the way its result says: with the complete output under contract 1, or with fromTree: true and its contractVersion under contracts 2 and 3.',
     readOnly: true,
     inputSchema: { type: 'object', properties: { runId: { type: 'string' } }, required: ['runId'] },
     handler: stepInstruction,
   },
   {
     name: 'hone_submit_step',
-    description: "Submit the editor-executed output for a Hone step that was fetched via hone_step_instruction. The output enters Hone's NORMAL gate + verification flow (judged by real test execution, not trust).",
+    description: "Submit the editor-executed output for a Hone step that was fetched via hone_step_instruction. Pass the contractVersion it was served; under contracts 2 and 3 set fromTree: true instead of output. The output enters Hone's NORMAL gate + verification flow (judged by real test execution, not trust).",
     readOnly: false,
     inputSchema: {
       type: 'object',

package/lib/path-refusal.js

@@ -0,0 +1,79 @@
+'use strict';
+/**
+ * path-refusal.js — HC-GF-398: the CLI's one path classifier, with two named modes.
+ *
+ * There used to be two, and they disagreed. `isSecretPath()` (bundle-context) decided what is sent as whole
+ * content unasked — the step_4 `--from-tree` artifact, the bundle, the review diff — and `contentRefusal()`
+ * (context-reserve) decided what an agent may request. Only the second knew `*.key`, `*.pfx`, `*.jks`,
+ * `*.keystore` and `*.p8`, so a changed `keys/deploy.key` was refused as context and sent whole as a build
+ * artifact.
+ *
+ *   egress   what is never sent as whole content unasked. The credential basenames plus the five key-container
+ *            extensions. A template (`.example`, `.sample`, `.template`, `.dist`) is exempt here, and only here.
+ *            It stays narrow on purpose: a false positive silently drops a real change from the PR, so a name
+ *            that merely says "secret" (`src/secret-manager.js`) or a hidden path (`.github/workflows/ci.yml`)
+ *            is sent.
+ *   content  what an agent may not read. Egress, plus the wide rules: any name with secret or credential in
+ *            it, an unanchored `id_rsa`-style name, any hidden file or directory, and a path that is not a
+ *            plain relative path. It is built from egress, so it refuses everything egress refuses.
+ *
+ * Requires only `path`: bundle-context and tree-artifact load it, and tree-artifact's dependency list is kept
+ * small on purpose. The exported names avoid the words the call-site search treats as a held value.
+ */
+
+const path = require('path');
+
+const MODES = Object.freeze(['egress', 'content']);
+
+// Egress: matched on the basename, so a nested `config/.env` is caught too.
+const EGRESS_BASENAMES = [
+  /^\.env($|\.)/i, /^secrets?\./i, /\.pem$/i, /\.p12$/i, /(^|[._-])id_(rsa|dsa|ecdsa|ed25519)$/i,
+  /\.(key|pfx|jks|keystore|p8)$/i,
+];
+const TEMPLATE_SUFFIX = /\.(example|sample|template|dist)$/i;
+
+// Content only: credential-looking names egress deliberately sends.
+const WIDE_BASENAMES = [/(^|[._-])id_(rsa|dsa|ecdsa|ed25519)/i, /\.(key|pfx|jks|keystore|p8)$/i, /(secret|credential)/i];
+
+const CREDENTIAL = 'looks like a credential file';
+
+function basenameOf(p) {
+  return path.posix.basename(String(p || '').replace(/\\/g, '/'));
+}
+
+function egressRefusal(p) {
+  const base = basenameOf(p);
+  if (TEMPLATE_SUFFIX.test(base)) return null;
+  return EGRESS_BASENAMES.some((re) => re.test(base)) ? CREDENTIAL : null;
+}
+
+/** Why a path is not a plain relative path, or null. `file` has no `:line` or `:symbol` suffix. */
+function structuralRefusal(file) {
+  if (typeof file !== 'string' || file === '') return 'empty';
+  if (/^[-/~]/.test(file)) return 'absolute, home-relative or option-like';
+  if (/[\\\0]/.test(file)) return 'not a plain relative path';
+  if (file.split('/').some((s) => s === '' || s === '.' || s === '..')) return 'not a plain relative path';
+  return null;
+}
+
+function contentModeRefusal(file) {
+  const plain = structuralRefusal(file);
+  if (plain) return plain;
+  if (egressRefusal(file) || WIDE_BASENAMES.some((re) => re.test(path.posix.basename(file)))) return CREDENTIAL;
+  if (file.split('/').some((s) => s.startsWith('.'))) return 'a hidden file or directory';
+  return null;
+}
+
+/**
+ * Why `p` is refused in `mode`, or null.
+ * @param {string} p  a repository-relative path, no `:line` suffix
+ * @param {{mode: 'egress'|'content'}} opts  required; an unknown or missing mode throws
+ * @returns {string|null}
+ */
+function pathRefusal(p, { mode } = {}) {
+  if (mode === 'egress') return egressRefusal(p);
+  if (mode === 'content') return contentModeRefusal(p);
+  throw new Error(`pathRefusal: unknown mode ${JSON.stringify(mode)}; expected one of ${MODES.join(', ')}`);
+}
+
+module.exports = { pathRefusal, structuralRefusal, MODES };