@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/_lib/runtime_wiring_checks.ts

@@ -0,0 +1,430 @@
+/**
+ * Runtime-wiring checks for `agent-config doctor`.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 2, Steps 2-5. The gate
+ * estate checks ARTIFACTS — is the rule written, is the projection byte-exact,
+ * does the manifest parse. Nothing checked whether the wiring is LIVE: whether
+ * the settings resolver returns anything, whether the router artifact parses,
+ * whether each registered hook resolves to something executable, and whether an
+ * inherited git-discovery variable is silently re-pointing every gate at another
+ * repository.
+ *
+ * All four are REPORTS. `doctor` writes nothing and always exits zero, so a
+ * check here returns a verdict and never a refusal — the point is that a
+ * disabled or mis-wired estate becomes VISIBLE, not that a diagnostic starts
+ * failing builds. A gate that wanted to refuse would belong in the gate estate.
+ *
+ * Extracted into `_lib/` rather than added to `cmd_doctor.ts` for a stated
+ * reason: that file is 3,700 lines and `check_source_size_budget` counts every
+ * line above 1,500, so four checks written inline would be charged against a
+ * budget while the same code in a new module is free. The seam is also what
+ * makes them unit-testable without booting the CLI.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+
+import { parse as parseYaml } from 'yaml';
+
+import { inheritedGitOverrides } from './repo_root.js';
+
+/** The verdict shape `cmd_doctor` renders. Mirrors its internal `Dict` rows. */
+export interface WiringCheck {
+    id: string;
+    /**
+     * The four the doctor's own report contract publishes. `info` was a fifth
+     * here for one commit and is gone: the MCP `doctor_report` tool asserts the
+     * published union, so a fifth value that never reached that contract failed
+     * the tool's shape test rather than appearing in a report. A vocabulary a
+     * consumer cannot receive is not a vocabulary.
+     */
+    status: 'ok' | 'warn' | 'fail' | 'skipped';
+    message: string;
+    remedy: string;
+}
+
+/**
+ * Step 2 — the settings resolver returns something, and WHICH FILE won.
+ *
+ * The cascade is user-global then project, last write winning. Nearly twenty
+ * rules in this suite tell an agent to read `.agent-settings.yml` to learn
+ * whether a feature is on, and every one of them is wrong about a key set on
+ * another layer. Reporting the winning FILE per key is the part that makes the
+ * check worth running — a value alone cannot be argued with.
+ */
+export function checkSettingsResolution(
+    iterOverrides: () => Iterable<[string, unknown, string]>,
+): WiringCheck {
+    let pairs: [string, unknown, string][];
+    try {
+        pairs = [...iterOverrides()];
+    } catch (e) {
+        return {
+            id: 'settings-resolution',
+            status: 'fail',
+            message: `settings cascade did not resolve: ${e instanceof Error ? e.message : String(e)}`,
+            remedy: 'check the YAML in every layer `agent-config settings:get <key>` reports',
+        };
+    }
+    if (pairs.length === 0) {
+        return {
+            id: 'settings-resolution',
+            // `skipped`, not `ok`: the cascade RESOLVED and there was nothing
+            // in it, which is a check that had nothing to inspect rather than a
+            // check that passed. Reporting `ok` here would read as "settings
+            // resolved fine" on a tree where no setting exists at all — the
+            // same conflation the reach check exists to remove elsewhere.
+            status: 'skipped',
+            message:
+                'settings cascade resolves, and NO layer sets any key — every read falls to the ' +
+                'template default. That is a valid state, not a failure: a fresh project has no settings.',
+            remedy: '',
+        };
+    }
+    // Last writer wins, which is the resolver's own rule — so the winning file
+    // is the LAST occurrence of a key, not the first.
+    const winner = new Map<string, string>();
+    for (const [key, , file] of pairs) winner.set(key, file);
+    const byFile = new Map<string, number>();
+    for (const file of winner.values()) byFile.set(file, (byFile.get(file) ?? 0) + 1);
+    const summary = [...byFile.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([f, n]) => `${path.basename(f)}=${String(n)}`)
+        .join(' · ');
+    return {
+        id: 'settings-resolution',
+        status: 'ok',
+        message: `${String(winner.size)} key(s) resolved across ${String(byFile.size)} layer(s) — ${summary}`,
+        remedy: '',
+    };
+}
+
+/**
+ * Step 3 — the router artifact exists, PARSES, and reports its rule count.
+ *
+ * Parsing is the half that matters. A router file that exists but does not parse
+ * fails silently at load: the host reads no rules and behaves like a tree with
+ * none, which is indistinguishable from a correctly minimal configuration.
+ */
+export function checkRouterArtifact(repoRoot: string, rel = 'dist/router.json'): WiringCheck {
+    const abs = path.join(repoRoot, rel);
+    if (!fs.existsSync(abs)) {
+        return {
+            id: 'router-artifact',
+            status: 'warn',
+            message: `${rel} is absent — no rule router is deployed`,
+            remedy: 'task generate-tools',
+        };
+    }
+    let doc: unknown;
+    try {
+        doc = JSON.parse(fs.readFileSync(abs, 'utf8'));
+    } catch (e) {
+        return {
+            id: 'router-artifact',
+            status: 'fail',
+            message: `${rel} exists but does NOT parse: ${e instanceof Error ? e.message : String(e)}`,
+            remedy: 'task generate-tools (a present-but-unparseable router loads as zero rules)',
+        };
+    }
+    const rules = _routerRuleCount(doc);
+    if (rules === 0) {
+        return {
+            id: 'router-artifact',
+            status: 'warn',
+            message: `${rel} parses and carries ZERO rules — a router with no rules routes nothing`,
+            remedy: 'task generate-tools',
+        };
+    }
+    return { id: 'router-artifact', status: 'ok', message: `${rel} parses · ${String(rules)} rule(s)`, remedy: '' };
+}
+
+/** Count routed rules across whichever shape the artifact uses. */
+export function _routerRuleCount(doc: unknown): number {
+    if (doc === null || typeof doc !== 'object') return 0;
+    const d = doc as Record<string, unknown>;
+    if (Array.isArray(d['rules'])) return d['rules'].length;
+    let n = 0;
+    for (const v of Object.values(d)) {
+        if (Array.isArray(v)) n += v.length;
+        else if (v !== null && typeof v === 'object') n += _routerRuleCount(v);
+    }
+    return n;
+}
+
+export interface HookProbe {
+    id: string;
+    script: string;
+    resolves: boolean;
+    ms: number | null;
+}
+
+/**
+ * Step 4 — every registered hook resolves to a real file, with its cost.
+ *
+ * Cost is reported PER HOOK rather than as a total, because a latency
+ * regression is only actionable where it is incurred: a 300 ms total tells you
+ * nothing, while one 280 ms concern names itself.
+ *
+ * `probe` defaults to a real invocation with `--help`, which every dispatcher
+ * entry point accepts and which does no work. Injectable so the unit tests do
+ * not spawn 53 processes.
+ */
+export function checkHookResolution(
+    repoRoot: string,
+    manifestRel = 'src/scripts/hook_manifest.yaml',
+    probe: ((script: string) => number | null) | null = null,
+): { check: WiringCheck; probes: HookProbe[] } {
+    const abs = path.join(repoRoot, manifestRel);
+    if (!fs.existsSync(abs)) {
+        return {
+            check: {
+                id: 'hook-resolution',
+                status: 'fail',
+                message: `${manifestRel} is absent — the hook estate cannot be enumerated`,
+                remedy: 'restore the manifest; every hook is registered from it',
+            },
+            probes: [],
+        };
+    }
+    let concerns: Record<string, { script?: unknown }>;
+    try {
+        const doc = parseYaml(fs.readFileSync(abs, 'utf8')) as { concerns?: unknown };
+        concerns = (doc.concerns ?? {}) as Record<string, { script?: unknown }>;
+    } catch (e) {
+        return {
+            check: {
+                id: 'hook-resolution',
+                status: 'fail',
+                message: `${manifestRel} does not parse: ${e instanceof Error ? e.message : String(e)}`,
+                remedy: 'fix the manifest YAML',
+            },
+            probes: [],
+        };
+    }
+    const probes: HookProbe[] = [];
+    for (const [id, c] of Object.entries(concerns)) {
+        const script = typeof c.script === 'string' ? c.script : '';
+        const resolves = script !== '' && fs.existsSync(path.join(repoRoot, script));
+        probes.push({ id, script, resolves, ms: resolves && probe !== null ? probe(script) : null });
+    }
+    const broken = probes.filter((p) => !p.resolves);
+    if (broken.length > 0) {
+        return {
+            check: {
+                id: 'hook-resolution',
+                status: 'fail',
+                message:
+                    `${String(broken.length)} of ${String(probes.length)} registered hook(s) do NOT resolve to a file: ` +
+                    broken.map((b) => b.id).join(', '),
+                remedy: 'a registered hook with no script silently no-ops every session — fix the path or drop the entry',
+            },
+            probes,
+        };
+    }
+    const timed = probes.filter((p) => p.ms !== null).sort((a, b) => (b.ms ?? 0) - (a.ms ?? 0));
+    const slowest = timed.length > 0 ? ` · slowest ${timed[0]!.id} ${String(timed[0]!.ms)}ms` : '';
+    return {
+        check: {
+            id: 'hook-resolution',
+            status: 'ok',
+            message: `${String(probes.length)} registered hook(s), all resolving${slowest}`,
+            remedy: '',
+        },
+        probes,
+    };
+}
+
+/** A real `--help` invocation, timed. `null` when it cannot be measured. */
+export function probeHookCost(repoRoot: string, script: string): number | null {
+    const started = Date.now();
+    const r = spawnSync(process.execPath, [path.join(repoRoot, 'scripts-run'), script, '--help'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        timeout: 10_000,
+    });
+    if (r.error) return null;
+    return Date.now() - started;
+}
+
+/**
+ * Step 5 — an inherited git-discovery variable.
+ *
+ * The recorded failure: a git hook exports `GIT_DIR` into every child, so a gate
+ * run inside one resolves against whatever that points at — inside a worktree,
+ * the parent checkout. The gate runs, reads the wrong tree, and PASSES. Nothing
+ * about the output says which repository answered.
+ *
+ * Reported as a warning rather than a failure because the variable is legitimate
+ * where git itself set it; what it is not is invisible.
+ */
+export function checkInheritedGitEnv(env: NodeJS.ProcessEnv = process.env): WiringCheck {
+    const found = inheritedGitOverrides(env);
+    if (found.length === 0) {
+        return {
+            id: 'inherited-git-env',
+            status: 'ok',
+            message: 'no git discovery override in the environment — git resolves from the working directory',
+            remedy: '',
+        };
+    }
+    return {
+        id: 'inherited-git-env',
+        status: 'warn',
+        message:
+            `${String(found.length)} git discovery override(s) inherited: ` +
+            found.map((f) => `${f.name}=${f.value}`).join(' · ') +
+            ' — every git call in this process answers for THAT repository, not the working directory',
+        remedy:
+            'unset them before running a gate from inside a git hook (`env -u GIT_DIR -u GIT_WORK_TREE …`), ' +
+            'or resolve the root with _lib/repo_root.ts, which refuses instead of guessing',
+    };
+}
+
+/**
+ * The four runtime-wiring runners, as one table.
+ *
+ * Returned as a map rather than registered inline at each of `cmd_doctor`'s TWO
+ * runner tables: written there it is ~20 lines duplicated, and every line of
+ * that file above 1,500 is charged by `check_source_size_budget`. One factory,
+ * two spreads.
+ */
+/** The four ids, in render order. Spread into `cmd_doctor`'s two id registries. */
+export const WIRING_CHECK_IDS = ['settings-resolution', 'router-artifact', 'hook-resolution', 'inherited-git-env', 'hooks-kill-switch'] as const;
+
+
+/**
+ * The estate kill switch, reported so a DISABLED estate is visible.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 1 Step 7's second clause,
+ * which could not be satisfied until the Phase 2 diagnostic existed. The flag
+ * itself has been implemented since Phase 1; what was missing is that a session
+ * running with every guard switched off looked exactly like one running with
+ * them all armed.
+ *
+ * ONLY the exact value `1` disarms, and the check mirrors that rather than
+ * guessing: a truthy-ish test would report `=0` as disabled, which is the
+ * opposite of what it means.
+ */
+export function checkHooksDisabled(env: NodeJS.ProcessEnv = process.env): WiringCheck {
+    const raw = env['AGENT_CONFIG_DISABLE_HOOKS'];
+    if (raw !== '1') {
+        return {
+            id: 'hooks-kill-switch',
+            status: 'ok',
+            message:
+                raw === undefined || raw === ''
+                    ? 'AGENT_CONFIG_DISABLE_HOOKS is not set — the hook estate is armed'
+                    : `AGENT_CONFIG_DISABLE_HOOKS=${raw} — only the exact value "1" disarms, so the estate is armed`,
+            remedy: '',
+        };
+    }
+    return {
+        id: 'hooks-kill-switch',
+        status: 'warn',
+        message:
+            'AGENT_CONFIG_DISABLE_HOOKS=1 — EVERY hook and shim in this environment is disabled. ' +
+            'A run under this flag enforces nothing, and without this line it would look identical ' +
+            'to one with the whole estate armed.',
+        remedy: 'unset AGENT_CONFIG_DISABLE_HOOKS (it is intended for one command, not a session)',
+    };
+}
+
+export function wiringRunners(opts: {
+    packageRoot: string;
+    iterOverrides: () => Iterable<[string, unknown, string]>;
+}): Record<string, () => WiringCheck> {
+    return {
+        'settings-resolution': () => checkSettingsResolution(opts.iterOverrides),
+        'router-artifact': () => checkRouterArtifact(opts.packageRoot),
+        // Per-hook COST is not probed on the default path: it spawns one process
+        // per registered concern (53 today), turning a read-only diagnostic into
+        // a multi-second one. `probeHookCost` is exported for a caller that wants it.
+        'hook-resolution': () => checkHookResolution(opts.packageRoot).check,
+        'inherited-git-env': () => checkInheritedGitEnv(),
+        'hooks-kill-switch': () => checkHooksDisabled(),
+    };
+}
+
+/**
+ * Managed hook wiring (single-surface model): the deterministic hook matrix
+ * must be registered in ~/.claude/settings.json AND the dispatch target
+ * (`agent-config` binary) must resolve on PATH. Both halves are required —
+ * hooks without a binary silently no-op every session.
+ */
+export interface HookWiringDeps {
+    which: (bin: string) => string | null;
+    packageRoot: string;
+    homeDir: string;
+    buildMatrix: (manifestPath: string) => Record<string, unknown>;
+    managedSignature: string;
+    pluginInstalled: () => boolean;
+}
+
+export function checkHookWiring(deps: HookWiringDeps): WiringCheck {
+    const claude = deps.which('claude');
+    if (claude === null) {
+        return {
+            id: 'hook-wiring',
+            status: 'skipped',
+            message: 'Claude Code CLI not on PATH — hook-wiring check not applicable',
+            remedy: '',
+        };
+    }
+    const settings_path = path.join(deps.homeDir, '.claude', 'settings.json');
+    let missing: string[];
+    try {
+        const matrix = deps.buildMatrix(path.join(deps.packageRoot, 'src', 'scripts', 'hook_manifest.yaml'));
+        const settings = fs.existsSync(settings_path)
+            ? (JSON.parse(fs.readFileSync(settings_path, 'utf8')) as Record<string, unknown>)
+            : {};
+        const hooks = ((settings['hooks'] ?? {}) as Record<string, unknown>) || {};
+        missing = Object.keys(matrix).filter((ev) => {
+            const groups = hooks[ev];
+            if (!Array.isArray(groups)) return true;
+            return !JSON.stringify(groups).includes(deps.managedSignature);
+        });
+    } catch (e) {
+        return {
+            id: 'hook-wiring',
+            status: 'fail',
+            message: `cannot evaluate managed hooks: ${String(e)}`,
+            remedy: 'fix ~/.claude/settings.json (invalid JSON?), then agent-config refresh --global',
+        };
+    }
+    const binary_ok = deps.which('agent-config') !== null;
+    if (missing.length === 0 && binary_ok) {
+        return {
+            id: 'hook-wiring',
+            status: 'ok',
+            message: 'managed hooks registered in ~/.claude/settings.json; dispatch binary on PATH',
+            remedy: '',
+        };
+    }
+    if (missing.length > 0 && deps.pluginInstalled()) {
+        return {
+            id: 'hook-wiring',
+            status: 'warn',
+            message:
+                `managed hooks missing for: ${missing.join(', ')} — currently carried by the ` +
+                'installed plugin (deprecated surface)',
+            remedy: 'agent-config refresh --global (writes the managed settings.json block)',
+        };
+    }
+    const parts: string[] = [];
+    if (missing.length > 0) parts.push(`managed hooks missing for: ${missing.join(', ')}`);
+    if (!binary_ok) parts.push('`agent-config` not on PATH (hooks would silently no-op)');
+    if (parts.length === 0) {
+        // hooks complete, binary missing was the only issue → covered above.
+        parts.push('`agent-config` not on PATH');
+    }
+    return {
+        id: 'hook-wiring',
+        status: 'fail',
+        message: parts.join('; '),
+        remedy: binary_ok
+            ? 'agent-config refresh --global'
+            : 'npm install -g @event4u/agent-config, then agent-config refresh --global',
+    };
+}

package/src/scripts/_lib/skill_catalogue.ts

@@ -93,7 +93,17 @@ export function resolveSkillsRoot(workspaceRoot: string): string | null {
     for (const candidate of DEFAULT_CATALOGUE_ROOTS) {
         const abs = path.join(workspaceRoot, candidate);
         try {
-            if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) return abs;
+            if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) continue;
+            // NON-EMPTY, and that qualifier is the whole fix. `.claude/skills`
+            // is a gitignored projection, so in a fresh worktree it EXISTS and
+            // holds nothing — and an empty root resolved as a match makes the
+            // ranker report an empty catalogue as an empty RESULT, which is the
+            // silent failure `road-to-inbox-harvest-2026-08-f-skill-selection-evidence`
+            // is about, arriving through a second door. Measured in that run: a
+            // worktree that had never run `generate-tools` ranked zero skills
+            // and exited 0 on a task that scores 47 against `src/skills`.
+            if (fs.readdirSync(abs).length === 0) continue;
+            return abs;
         } catch {
             // Unreadable candidate is not a match; try the next.
         }

package/src/scripts/_lib/source_digest.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env tsx
+/**
+ * source_digest — keyed digests for the source deny set
+ * (`road-to-source-silence` Phase 1.1).
+ *
+ * ## The problem
+ *
+ * `external_sources_denylist.json` publishes, in plaintext in a public
+ * repository, 65 names of the harvest sources it exists to hide. The list IS
+ * the disclosure. Phase 1's answer is to stop shipping the names: the tracked
+ * config carries **HMAC-SHA256 digests**, the readable master lives in a
+ * gitignored private file, and a build step derives one from the other.
+ *
+ * ## Why keyed and not a plain hash
+ *
+ * The candidate space is public repository slugs — a few million entries,
+ * enumerable in minutes. An unsalted SHA-256 of a slug is a lookup, not a
+ * secret. The construction is therefore keyed: without the key a digest is not
+ * reversible by dictionary attack, and with the key the gate matches exactly as
+ * a name list would.
+ *
+ * ## STATUS: DORMANT. This ships ALONGSIDE the plaintext gate, not instead of it.
+ *
+ * AI council 2026-08-28 (blocker `where-the-key-lives`), 2/2 convergent:
+ * shipping this as a REPLACEMENT is net-negative, because the half an agent can
+ * build is precisely the half that enforces nothing. Provisioning the CI
+ * secret, generating production digests, deleting the tracked plaintext deny
+ * array, and switching CI to strict mode are **one atomic maintainer change**;
+ * splitting them leaves the gate either failing every run for want of a key or
+ * silently degraded to warn mode, which is the exact failure the roadmap exists
+ * to remove.
+ *
+ * So: the plaintext `deny` array stays in force and is not deleted, and
+ * `deny_digests` ships EMPTY. When it is empty this module does no work at all.
+ * The cutover recipe is in `docs/maintainers/source-deny-digests.md`.
+ */
+
+import * as crypto from 'node:crypto';
+
+/** Environment variable carrying the HMAC key (CI secret / local `.env`). */
+export const KEY_ENV = 'SOURCE_DENY_KEY';
+
+/** Environment variable that makes a missing key fatal instead of dormant. */
+export const STRICT_ENV = 'SOURCE_DENY_STRICT';
+
+/** Exit code for "strict mode asked for, key absent". Never 0 — see Phase 1.2. */
+export const EXIT_NO_KEY = 3;
+
+/**
+ * Fold a candidate to its comparison form.
+ *
+ * Lowercase, every separator run (`-`, `_`, `.`, `/`, whitespace) collapsed to a
+ * single `-`, edges trimmed. `Foo_Bar`, `foo.bar`, `foo/bar` and `FOO - BAR` all
+ * reach the same digest, so a source cannot be smuggled past the set by
+ * re-punctuating its name.
+ */
+export function normalise(token: string): string {
+    return token
+        .toLowerCase()
+        .replace(/[\s._/\\-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+
+/** HMAC-SHA256 of the normalised token, lowercase hex. */
+export function digest(token: string, key: string): string {
+    if (!key) throw new Error('empty digest key');
+    return crypto.createHmac('sha256', key).update(normalise(token), 'utf-8').digest('hex');
+}
+
+/** A digest as it must appear in the config. */
+export const DIGEST_RE = /^[0-9a-f]{64}$/;
+
+/** Word-ish runs a source name could occupy. */
+const WORD_RE = /[A-Za-z0-9][A-Za-z0-9._-]{2,80}/g;
+
+/**
+ * The candidate tokens on one line.
+ *
+ * A digest cannot be regex-matched, so the line is tokenised and each candidate
+ * hashed. Three shapes are produced per word run: the run itself, the run
+ * joined to its right-hand neighbour across a `/` (the `owner/repo` form), and
+ * the same across a `-`. That is a deliberate ceiling: an attribution spread
+ * over more than two adjacent tokens is not caught, and the module docstring of
+ * `source_shape.ts` says the same thing about its own classes — a floor, not a
+ * proof.
+ */
+export function candidateTokens(line: string): string[] {
+    const words: string[] = [];
+    WORD_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    const spans: Array<{ text: string; end: number; start: number }> = [];
+    while ((m = WORD_RE.exec(line)) !== null) {
+        spans.push({ text: m[0], start: m.index, end: m.index + m[0].length });
+    }
+    for (let i = 0; i < spans.length; i += 1) {
+        const cur = spans[i] as { text: string; end: number; start: number };
+        words.push(cur.text);
+        const next = spans[i + 1];
+        if (!next) continue;
+        const between = line.slice(cur.end, next.start);
+        if (between === '/' || between === '-') words.push(`${cur.text}${between}${next.text}`);
+    }
+    return words;
+}
+
+/**
+ * A digest matcher over one deny set. Memoises per normalised token, so the
+ * per-line cost is a Map lookup once a token has been seen anywhere in the run.
+ */
+export class DigestMatcher {
+    private readonly set: ReadonlySet<string>;
+    private readonly key: string;
+    private readonly memo = new Map<string, boolean>();
+
+    constructor(digests: readonly string[], key: string) {
+        this.set = new Set(digests.map((d) => d.toLowerCase()));
+        this.key = key;
+    }
+
+    /** Is this raw token in the deny set? */
+    has(token: string): boolean {
+        const norm = normalise(token);
+        if (norm.length < 3) return false;
+        const cached = this.memo.get(norm);
+        if (cached !== undefined) return cached;
+        const hit = this.set.has(digest(norm, this.key));
+        this.memo.set(norm, hit);
+        return hit;
+    }
+
+    /** The denied tokens on one line, deduplicated, normalised form. */
+    hits(line: string): string[] {
+        const out = new Set<string>();
+        for (const t of candidateTokens(line)) if (this.has(t)) out.add(normalise(t));
+        return [...out];
+    }
+
+    get size(): number {
+        return this.set.size;
+    }
+}
+
+export interface DigestModeVerdict {
+    /** Digest matching is active this run. */
+    active: boolean;
+    /** Digests present in the config. */
+    digests: number;
+    /** Set, but the key is missing. */
+    keyMissing: boolean;
+    /** Strict mode was requested. */
+    strict: boolean;
+    /** One line for stdout/stderr. Empty when there is nothing to say. */
+    message: string;
+}
+
+/**
+ * Decide what digest matching does this run — the loud-when-keyless contract
+ * from Phase 1.2.
+ *
+ * | digests | key | strict | verdict |
+ * |---|---|---|---|
+ * | none | — | no | dormant, silent (today's shipped state) |
+ * | none | — | yes | **fatal**: strict asked for and there is nothing to enforce |
+ * | some | absent | no | **loud warning**, matching skipped — never silently green |
+ * | some | absent | yes | **fatal** (`EXIT_NO_KEY`) |
+ * | some | present | — | active |
+ */
+export function digestMode(opts: {
+    digests: readonly string[];
+    key: string | undefined;
+    strict: boolean;
+}): DigestModeVerdict {
+    const n = opts.digests.length;
+    const key = opts.key ?? '';
+    if (n === 0) {
+        return {
+            active: false,
+            digests: 0,
+            keyMissing: false,
+            strict: opts.strict,
+            message: opts.strict
+                ? `${STRICT_ENV} is set but the config carries no deny_digests — strict mode has ` +
+                  'nothing to enforce. Run the digest build step before enabling strict mode.'
+                : '',
+        };
+    }
+    if (key === '') {
+        return {
+            active: false,
+            digests: n,
+            keyMissing: true,
+            strict: opts.strict,
+            message:
+                `⚠️  ${String(n)} deny digest(s) present but ${KEY_ENV} is unset — digest matching ` +
+                'is SKIPPED this run. This run did NOT check the hashed deny set. Set ' +
+                `${KEY_ENV} (CI secret / local .env) to enforce it.`,
+        };
+    }
+    return { active: true, digests: n, keyMissing: false, strict: opts.strict, message: '' };
+}