@event4u/agent-config 9.9.0 → 9.10.0

package/src/scripts/_lib/preservation_migration.ts

@@ -0,0 +1,291 @@
+/**
+ * Preservation-conformance verifier for safety-floor rule edits.
+ *
+ * `check_safety_floor_untouched` blocks every edit to the four safety-floor
+ * rules. That is right for substantive edits and wrong for a P4 migration, which
+ * moves lookup material into a `load_context:` target without losing anything.
+ * This module decides which one a diff is — by CHECKING, never by trusting a
+ * label, a commit message, or a contributor's word. A migration that cannot be
+ * proven conformant is treated as substantive and blocked (fail-closed).
+ *
+ * The contract it enforces is `preservation-guard`'s: every paragraph, list
+ * item, and fenced block from the source survives — either still in the rule
+ * (telegraph condensation is allowed, so matching is fuzzy) or verbatim in one
+ * of the rule's declared `load_context:` targets (a migration is a move, so
+ * matching there is near-exact). Iron Law sections are stricter still: their
+ * headings must survive at the same level and their fenced blocks byte-for-byte.
+ *
+ * Pure functions over strings — no git, no fs — so the whole decision is unit
+ * testable without manufacturing commits. That absence is why the guard it
+ * serves shipped inert for months.
+ */
+
+/** A structural unit of a markdown body: heading, paragraph, list item, or fence. */
+export interface Unit {
+    kind: 'heading' | 'paragraph' | 'list-item' | 'fence';
+    /** Heading depth (1-6) for `heading`, else 0. */
+    level: number;
+    /** Raw text as it appeared, minus the trailing newline. */
+    raw: string;
+    /** Normalised form used for comparison. */
+    norm: string;
+}
+
+/** Strip frontmatter; return the body. */
+export function strip_frontmatter(text: string): string {
+    const m = /^---\n[\s\S]*?\n---\n/.exec(text);
+    return m === null ? text : text.slice(m[0].length);
+}
+
+/** `load_context:` targets declared in a rule's frontmatter, in order. */
+export function load_context_targets(text: string): string[] {
+    const fm = /^---\n([\s\S]*?)\n---\n/.exec(text);
+    if (fm === null) return [];
+    const out: string[] = [];
+    let inBlock = false;
+    for (const line of fm[1]!.split('\n')) {
+        if (/^load_context:\s*$/.test(line)) {
+            inBlock = true;
+            continue;
+        }
+        if (inBlock) {
+            const item = /^\s*-\s+(.+?)\s*$/.exec(line);
+            if (item !== null) {
+                out.push(item[1]!.replace(/^["']|["']$/g, ''));
+                continue;
+            }
+            if (/^\S/.test(line)) inBlock = false;
+        }
+    }
+    return out;
+}
+
+/**
+ * Normalise a unit for comparison.
+ *
+ * Deliberately blind to the three things a legitimate migration changes and
+ * nothing else: heading depth (an H2 becomes an H3 under a host section), link
+ * targets (relative paths are rewritten for the new location), and whitespace.
+ * Everything that carries obligation — words, emphasis, negations — is compared
+ * as written.
+ */
+export function normalise(raw: string): string {
+    return raw
+        .replace(/^#{1,6}\s+/gm, '') // heading depth
+        .replace(/\]\([^)]*\)/g, ']()') // link targets
+        .replace(/^\s*[-*+]\s+/gm, '') // list markers
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
+/** Split a markdown body into structural units. Fenced blocks stay intact. */
+export function parse_units(body: string): Unit[] {
+    const lines = body.split('\n');
+    const units: Unit[] = [];
+    let para: string[] = [];
+
+    const flush = (): void => {
+        if (para.length === 0) return;
+        const raw = para.join('\n');
+        if (raw.trim() !== '') units.push({ kind: 'paragraph', level: 0, raw, norm: normalise(raw) });
+        para = [];
+    };
+
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i]!;
+        const fence = /^(\s*)(`{3,}|~{3,})/.exec(line);
+        if (fence !== null) {
+            flush();
+            const marker = fence[2]!;
+            const block = [line];
+            i += 1;
+            while (i < lines.length) {
+                block.push(lines[i]!);
+                if (lines[i]!.trimStart().startsWith(marker)) break;
+                i += 1;
+            }
+            const raw = block.join('\n');
+            units.push({ kind: 'fence', level: 0, raw, norm: raw.replace(/\s+$/gm, '') });
+            continue;
+        }
+        const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (heading !== null) {
+            flush();
+            units.push({
+                kind: 'heading',
+                level: heading[1]!.length,
+                raw: line,
+                norm: normalise(line),
+            });
+            continue;
+        }
+        const item = /^\s*[-*+]\s+/.test(line) || /^\s*\d+\.\s+/.test(line);
+        if (item) {
+            flush();
+            units.push({ kind: 'list-item', level: 0, raw: line, norm: normalise(line) });
+            continue;
+        }
+        if (line.trim() === '') {
+            flush();
+            continue;
+        }
+        para.push(line);
+    }
+    flush();
+    return units;
+}
+
+/** Dice coefficient over character bigrams — cheap, order-sensitive enough. */
+export function similarity(a: string, b: string): number {
+    if (a === b) return 1;
+    if (a.length < 2 || b.length < 2) return a === b ? 1 : 0;
+    const grams = (s: string): Map<string, number> => {
+        const m = new Map<string, number>();
+        for (let i = 0; i < s.length - 1; i += 1) {
+            const g = s.slice(i, i + 2);
+            m.set(g, (m.get(g) ?? 0) + 1);
+        }
+        return m;
+    };
+    const ga = grams(a);
+    const gb = grams(b);
+    let overlap = 0;
+    for (const [g, n] of ga) overlap += Math.min(n, gb.get(g) ?? 0);
+    return (2 * overlap) / (a.length - 1 + b.length - 1);
+}
+
+/** A unit still present in the rule after telegraph condensation. */
+const KEPT_IN_RULE = 0.6;
+/** A unit moved into a context file — a move, so near-verbatim. */
+const MOVED_TO_CONTEXT = 0.9;
+
+export interface Finding {
+    code:
+        | 'iron-law-heading-lost'
+        | 'iron-law-fence-changed'
+        | 'passage-lost'
+        | 'unexplained-addition';
+    detail: string;
+}
+
+/** Units belonging to an Iron Law section (heading matches, until the next same-or-shallower heading). */
+export function iron_law_units(units: readonly Unit[]): Unit[] {
+    const out: Unit[] = [];
+    let depth: number | null = null;
+    for (const u of units) {
+        if (u.kind === 'heading') {
+            if (/^(the\s+)?iron\s+law/i.test(u.norm)) {
+                depth = u.level;
+                out.push(u);
+                continue;
+            }
+            if (depth !== null && u.level <= depth) depth = null;
+        }
+        if (depth !== null) out.push(u);
+    }
+    return out;
+}
+
+export interface VerifyInput {
+    /** Rule file content before the change. */
+    base_rule: string;
+    /** Rule file content after the change. */
+    head_rule: string;
+    /** Declared `load_context` target path → content AFTER the change. */
+    head_contexts: ReadonlyMap<string, string>;
+    /** Same targets, content BEFORE — so only ADDED context text counts as a landing site. */
+    base_contexts: ReadonlyMap<string, string>;
+}
+
+/**
+ * Decide whether a safety-floor rule edit is a preservation-conforming
+ * migration. Returns [] when it is; otherwise every reason it is not.
+ */
+export function verify_migration(input: VerifyInput): Finding[] {
+    const findings: Finding[] = [];
+    const baseUnits = parse_units(strip_frontmatter(input.base_rule));
+    const headUnits = parse_units(strip_frontmatter(input.head_rule));
+
+    // ── Iron Law: headings survive at depth, fences survive byte-for-byte ──
+    const baseIron = iron_law_units(baseUnits);
+    const headIron = iron_law_units(headUnits);
+    for (const u of baseIron) {
+        if (u.kind === 'heading') {
+            const hit = headIron.some((h) => h.kind === 'heading' && h.norm === u.norm && h.level === u.level);
+            if (!hit) {
+                findings.push({
+                    code: 'iron-law-heading-lost',
+                    detail: `${u.raw.trim()} — must survive verbatim at the same level`,
+                });
+            }
+        } else if (u.kind === 'fence') {
+            const hit = headIron.some((h) => h.kind === 'fence' && h.raw === u.raw);
+            if (!hit) {
+                findings.push({
+                    code: 'iron-law-fence-changed',
+                    detail: `fenced block under ${u.raw.split('\n')[0] ?? ''} changed — Iron Law fences are byte-exact`,
+                });
+            }
+        }
+    }
+
+    // ── Landing sites: only text ADDED to a DECLARED context counts ──
+    //
+    // The declared set is re-derived here from the rule's own frontmatter rather
+    // than trusted from the caller. A migration is only legitimate into a file
+    // the rule actually points readers at; dropping a passage into some other
+    // file leaves it unreachable from the rule and is a loss, not a move.
+    const declared = load_context_targets(input.head_rule);
+    const isDeclared = (p: string): boolean =>
+        declared.some((rel) => p === rel || p.endsWith(`/${rel}`));
+    const landing: string[] = [];
+    for (const [path, head] of input.head_contexts) {
+        if (!isDeclared(path)) continue;
+        const before = new Set(parse_units(strip_frontmatter(input.base_contexts.get(path) ?? '')).map((u) => u.norm));
+        for (const u of parse_units(strip_frontmatter(head))) {
+            if (!before.has(u.norm)) landing.push(u.norm);
+        }
+    }
+
+    // ── Every base unit survives: in the rule (fuzzy) or in a context (near-exact) ──
+    const headNorms = headUnits.map((u) => u.norm);
+    const usedHead = new Set<number>();
+    for (const u of baseUnits) {
+        let bestIdx = -1;
+        let best = 0;
+        for (let i = 0; i < headNorms.length; i += 1) {
+            if (usedHead.has(i)) continue;
+            const s = similarity(u.norm, headNorms[i]!);
+            if (s > best) {
+                best = s;
+                bestIdx = i;
+            }
+        }
+        if (best >= KEPT_IN_RULE) {
+            usedHead.add(bestIdx);
+            continue;
+        }
+        const moved = landing.some((l) => similarity(u.norm, l) >= MOVED_TO_CONTEXT);
+        if (!moved) {
+            findings.push({
+                code: 'passage-lost',
+                detail: `${u.kind}: ${u.raw.trim().slice(0, 90)}… — not kept in the rule and not found in any declared load_context target`,
+            });
+        }
+    }
+
+    // ── Nothing genuinely new in the rule: a migration only removes ──
+    for (let i = 0; i < headUnits.length; i += 1) {
+        if (usedHead.has(i)) continue;
+        const u = headUnits[i]!;
+        const back = baseUnits.some((b) => similarity(b.norm, u.norm) >= KEPT_IN_RULE);
+        if (!back) {
+            findings.push({
+                code: 'unexplained-addition',
+                detail: `${u.kind}: ${u.raw.trim().slice(0, 90)}… — new content in a safety-floor rule is a substantive edit, not a migration`,
+            });
+        }
+    }
+
+    return findings;
+}

package/src/scripts/_lib/retrieval_sanitize.ts

@@ -3,8 +3,8 @@
  * (road-to-retrieval-substrate-hardening B6).
  *
  * Corpus content — especially user-ingested knowledge chunks under
- * `agents/memory/knowledge/` — flows into the agent context via `retrieve_v1`
- * / `memory_get_v1`. An attacker (or a compromised ingested source) can embed
+ * `agents/memory/knowledge/` — flows into the agent context on the retrieval
+ * read surfaces. An attacker (or a compromised ingested source) can embed
  * hidden-instruction vectors (bidi controls, zero-width chars, Unicode Tag
  * block) or control-char noise that the model may act on — the untrusted-input
  * / lethal-trifecta injection surface. This floor strips those vectors from
@@ -15,12 +15,49 @@
  * layer + unbounded length; visible content is the agent's to read as data.
  * Codepoint classes are shared with `lint_hidden_unicode` (one source of truth
  * for what counts as a hidden-instruction vector).
+ *
+ * WHERE IT ACTUALLY RUNS — measured end-to-end, not asserted. Keep this list
+ * honest: an earlier version of this header named surfaces by intent, and the
+ * legacy-envelope gap below went unnoticed for exactly that reason. Every
+ * claim here is backed by a probe row in
+ * `agents/evidence/reports/sanitize-floor-wiring.md`:
+ *
+ *   - `retrieve_v1()`     — yes (`memory_lookup.ts` calls `sanitize_entry`)
+ *   - `memory_get_v1()`   — yes (same)
+ *   - MCP `memory_lookup` / `memory_get` tools — inherited from the two above
+ *   - `retrieve()` / `retrieve_with_meta()` — yes, since the S0.0 wiring fix;
+ *     before it they emitted every vector intact, and so did the CLI default
+ *     (`--envelope legacy`), which is the path the rules document
+ *   - inter-agent channels (`ai_team` / `ai_council` model replies) — the
+ *     inbound parse choke point only; the subagent boundary itself is a HOST
+ *     primitive this package cannot reach (see the report, § S0.0b)
+ *
+ * Anything not on that list is uncovered. Do not widen the list without a
+ * probe row to back it.
  */
 import { _classify } from '../lint_hidden_unicode.js';
+import { TOKEN_RE, classifyToken } from './confusables.js';
 
 /** Hard per-field length cap — bounds a runaway/adversarial body. */
 export const MAX_FIELD_CHARS = 8192;
 
+/**
+ * Invisible fillers — render as blank but are not whitespace, so they sit in
+ * neither the zero-width nor the bidi set and survived the original floor
+ * (measured: `agents/evidence/reports/encoding-channel-coverage.md` row 18).
+ *
+ * These are the ONLY channel Phase 1 chose to strip rather than flag: invisible
+ * by nature, with no legitimate role in this corpus, so folding them into the
+ * existing invisible set carries no corruption risk. Every other uncovered
+ * channel is a flag, because rewriting visible text can corrupt legitimate
+ * content.
+ */
+const _INVISIBLE_FILLERS: ReadonlySet<number> = new Set([
+    0x3164, // HANGUL FILLER
+    0x115f, // HANGUL CHOSEONG FILLER
+    0x1160, // HANGUL JUNGSEONG FILLER
+]);
+
 /** True for a C0/C1 control char that is NOT a benign whitespace (\t, \n). */
 function _isStrippableControl(cp: number): boolean {
     if (cp === 0x09 || cp === 0x0a) return false; // keep tab + newline
@@ -42,11 +79,138 @@ export function sanitize_text(s: string): string {
         if (cp === undefined) continue;
         if (_classify(cp) !== null) continue; // hidden-instruction vector → drop
         if (_isStrippableControl(cp)) continue; // control-char noise → drop
+        if (_INVISIBLE_FILLERS.has(cp)) continue; // blank-but-not-whitespace → drop
         out += ch;
     }
     return out.length > MAX_FIELD_CHARS ? out.slice(0, MAX_FIELD_CHARS) : out;
 }
 
+// ---------------------------------------------------------------------------
+// Visible-layer scanner — FLAG ONLY, never rewrites
+// ---------------------------------------------------------------------------
+//
+// `sanitize_text` strips the invisible layer. This reports the VISIBLE layer,
+// which the floor deliberately does not touch: folding a confusable to a Latin
+// skeleton, or NFKC-normalising a math-alphanumeric run, corrupts any body that
+// legitimately contains mixed script, CJK punctuation, or a ligature. Phase 1
+// measured each channel and chose flag-not-rewrite for every one of these:
+// `agents/evidence/reports/encoding-channel-coverage.md` § Disposition.
+//
+// Deterministic and pure: no model call, no network, no I/O. Safe to run in CI
+// and on a request path.
+//
+// Not scanned, deliberately, with the reason recorded so it is not mistaken for
+// an oversight:
+//   - confusable whitespace (NBSP, figure space) — pervasive in real prose
+//   - HTML/XML entities — decoding them would CREATE the payload
+//   - nested multibase (base64) — legitimate throughout this repo; semantic,
+//     not structural
+//   - structured-data key ordering — not a codepoint channel at all, and
+//     reordering keys would break the byte-identical v1 envelope contract
+//   - word-order permutation — carrier text with legitimate word order is
+//     indistinguishable from permuted text without semantics
+
+/** Codepoint thresholds — a run is the signal; a single occurrence is not. */
+const _VS_RUN_MIN = 3;
+const _COMBINING_RUN_MIN = 5;
+
+export interface EncodingFinding {
+    /** Stable channel id, matching the frozen corpus labels. */
+    readonly channel: string;
+    /** Why it fired, with the concrete evidence (codepoint or token). */
+    readonly detail: string;
+}
+
+function _isVariationSelector(cp: number): boolean {
+    return (cp >= 0xfe00 && cp <= 0xfe0f) || (cp >= 0xe0100 && cp <= 0xe01ef);
+}
+
+function _isCombiningMark(cp: number): boolean {
+    return cp >= 0x0300 && cp <= 0x036f;
+}
+
+/**
+ * Report visible-layer encoding signals in a string. Never mutates it.
+ *
+ * The confusable signature is NOT reimplemented here — it is the shared
+ * `classifyToken` from `_lib/confusables.ts`, the single definition this
+ * package's authoring-time linter also uses, so the two surfaces cannot drift
+ * apart on what counts as a homoglyph.
+ */
+export function scan_encoding_findings(s: string): EncodingFinding[] {
+    const out: EncodingFinding[] = [];
+
+    // Longest run of variation selectors / combining marks anywhere in the
+    // string. A run is what distinguishes steganography from legitimate use:
+    // U+FE0F is the emoji presentation selector and diacritics are normal in
+    // many languages, so a single occurrence is never the signal.
+    let vsRun = 0;
+    let vsMax = 0;
+    let cmRun = 0;
+    let cmMax = 0;
+    let hasMathAlnum = false;
+    let hasFullwidth = false;
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (cp === undefined) continue;
+        if (_isVariationSelector(cp)) {
+            vsRun += 1;
+            vsMax = Math.max(vsMax, vsRun);
+        } else {
+            vsRun = 0;
+        }
+        if (_isCombiningMark(cp)) {
+            cmRun += 1;
+            cmMax = Math.max(cmMax, cmRun);
+        } else {
+            cmRun = 0;
+        }
+        if (cp >= 0x1d400 && cp <= 0x1d7ff) hasMathAlnum = true;
+        if (cp >= 0xff01 && cp <= 0xff5e) hasFullwidth = true;
+    }
+    if (vsMax >= _VS_RUN_MIN) {
+        out.push({
+            channel: 'variation-selector-run',
+            detail: `variation-selector run x${vsMax} (steganography signature)`,
+        });
+    }
+    if (cmMax >= _COMBINING_RUN_MIN) {
+        out.push({
+            channel: 'combining-mark-run',
+            detail: `combining-mark run x${cmMax} on one base character`,
+        });
+    }
+    if (hasMathAlnum) {
+        out.push({
+            channel: 'math-alphanumeric',
+            detail: 'Mathematical Alphanumeric Symbols used as letters (U+1D400–1D7FF)',
+        });
+    }
+    if (hasFullwidth) {
+        out.push({
+            channel: 'fullwidth-forms',
+            detail: 'Halfwidth/Fullwidth Forms used as ASCII letters (U+FF01–FF5E)',
+        });
+    }
+
+    // Mixed-script confusable tokens — shared signature, one table in the tree.
+    for (const m of s.matchAll(TOKEN_RE)) {
+        const verdict = classifyToken(m[0]);
+        if (verdict !== null) {
+            const script = verdict.startsWith('latin+greek') ? 'greek' : 'cyrillic';
+            out.push({ channel: `confusable-${script}`, detail: `${m[0]} — ${verdict}` });
+        }
+    }
+
+    // Punycode / IDN in a text-expected field. Flagged, never rewritten:
+    // `xn--` labels are valid DNS and rewriting one would break a real link.
+    for (const m of s.matchAll(/\bxn--[a-z0-9-]+/gi)) {
+        out.push({ channel: 'punycode-idn', detail: `punycode label ${m[0]}` });
+    }
+
+    return out;
+}
+
 /**
  * Return a shallow copy of a retrieval entry with every string value (and
  * one level of string-array values) sanitized. Non-string values pass through

package/src/scripts/_lib/scan_scope.ts

@@ -0,0 +1,115 @@
+/**
+ * Scan-scope assertions — "a gate that read nothing did not pass".
+ *
+ * WHY THIS EXISTS (audit 2026-07-29, `agents/settings/contexts/gates-that-cannot-fail.md`):
+ * ADR-051 moved the source container and a later commit deleted `packages/`.
+ * Fourteen `lint_*`/`check_*` gates kept a hardcoded literal path, and every
+ * one of them treats a missing directory as "nothing to check" — so they exit 0
+ * and print a green checkmark while scanning zero files. Their own output said
+ * so (`0 file(s) scanned`, `0 name(s) checked`, `0 declarer(s)`); nothing ever
+ * asserted on the number.
+ *
+ * Two shapes cover the whole class:
+ *
+ * - **Corpus gates** walk a root and check N units → {@link assertScanned}.
+ *   Zero units is a failure unless the gate declares a justified `allowEmpty`.
+ * - **Watch-list gates** (diff-based, no corpus to count) name specific files
+ *   they guard → {@link assertWatchlistResolves}. A watch list that resolves to
+ *   nothing on disk means the guard is watching phantoms.
+ *
+ * Both throw {@link DeadScopeError}; callers map it to a non-zero exit. The
+ * point is that the failure is LOUD and names the root, so the next path
+ * migration cannot silently disarm a gate again.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Raised when a gate's scope is empty — it cannot have checked anything. */
+export class DeadScopeError extends Error {
+    readonly gate: string;
+
+    constructor(gate: string, message: string) {
+        super(message);
+        this.name = 'DeadScopeError';
+        this.gate = gate;
+    }
+}
+
+export interface ScannedOptions {
+    /** Gate name, for the error message (e.g. `lint_namespace`). */
+    gate: string;
+    /** How many units the gate actually examined. */
+    scanned: number;
+    /** Plural noun for the unit — `file(s)`, `name(s)`, `declarer(s)`. */
+    units: string;
+    /** The root(s) the gate walked, repo-relative, for the error message. */
+    roots: readonly string[];
+    /**
+     * Justification for legitimately scanning zero. Supply ONLY when an empty
+     * corpus is a real, expected state (an optional consumer surface that may
+     * genuinely be absent) — never to silence a moved root. The string is the
+     * reason and is printed, so it is reviewable in a diff.
+     */
+    allowEmpty?: string;
+}
+
+/**
+ * Assert a corpus gate examined at least one unit.
+ *
+ * @throws {DeadScopeError} when `scanned === 0` and no `allowEmpty` reason is given.
+ */
+export function assertScanned(opts: ScannedOptions): void {
+    if (opts.scanned > 0) {
+        return;
+    }
+    if (opts.allowEmpty !== undefined && opts.allowEmpty.trim() !== '') {
+        return;
+    }
+    const roots = opts.roots.length > 0 ? opts.roots.join(', ') : '(no root declared)';
+    throw new DeadScopeError(
+        opts.gate,
+        `${opts.gate}: scanned 0 ${opts.units} under ${roots} — the scan scope is ` +
+            'dead or the root moved. A gate that read nothing has not passed. ' +
+            'Repoint the root (prefer the shared resolver in _lib/agent_src.ts), ' +
+            'or declare a justified `allowEmpty` reason if an empty corpus is genuinely expected.',
+    );
+}
+
+export interface WatchlistOptions {
+    /** Gate name, for the error message. */
+    gate: string;
+    /** Repo-relative candidate paths the gate guards. */
+    candidates: readonly string[];
+    /** Absolute repo root the candidates resolve against. */
+    repoRoot: string;
+}
+
+/**
+ * Assert a watch-list gate's targets exist on disk, and return the ones that do.
+ *
+ * A diff-based guard has no corpus to count: it compares changed paths against
+ * a fixed list. If that list resolves to nothing, the guard reports "clean"
+ * forever — the exact shape of the `check_safety_floor_untouched` defect, which
+ * announced `4 rules guarded` while guarding none.
+ *
+ * @returns the subset of `candidates` that exist.
+ * @throws {DeadScopeError} when none of them exist.
+ */
+export function assertWatchlistResolves(opts: WatchlistOptions): string[] {
+    const resolved = opts.candidates.filter((rel) => {
+        try {
+            return fs.statSync(path.join(opts.repoRoot, rel)).isFile();
+        } catch {
+            return false;
+        }
+    });
+    if (resolved.length === 0) {
+        throw new DeadScopeError(
+            opts.gate,
+            `${opts.gate}: none of its ${opts.candidates.length} guarded path(s) exist ` +
+                `under ${opts.repoRoot} — the guard is watching phantoms and can never fire. ` +
+                `Checked: ${opts.candidates.join(', ')}`,
+        );
+    }
+    return resolved;
+}