@event4u/agent-config 14.18.0 → 14.20.0

package/src/scripts/_lib/release_position.ts

@@ -0,0 +1,96 @@
+/**
+ * Where a release may START — the branch it may run from, and whether a dirty
+ * working tree is tolerated there.
+ *
+ * Its own module because `release.ts` sits 456 lines over the 1500-line source
+ * ratchet, so growing it is a gate failure by construction. `_lib/` is where
+ * `release_highlights.ts` and `release_material.ts` already put the predicates
+ * the pipeline and its gates share.
+ */
+
+export interface PositionVerdict {
+    proceed: boolean;
+    /** Printed before the run continues. Never a refusal. */
+    notice?: string;
+    /** Printed on refusal (no trailing newline). */
+    message?: string;
+}
+
+/**
+ * Where a release may START, resolved as a pure verdict (no I/O, so it is
+ * unit-testable — same shape as `confirmGate`).
+ *
+ * THE DEADLOCK THIS REMOVES.
+ *
+ * `guard_release_curation` refuses BETWEEN step 2 and step 3: step 1 has
+ * already created and checked out `release/{target}`, step 2 has already
+ * written the bump, the changelog section and every regenerated derived file,
+ * and nothing is committed yet. Its message says to curate the head and re-run
+ * `task release`. Measured on 14.19.0, neither re-run reached step 1:
+ *
+ *   - `task release`            → `release must run from 'main'` (this check)
+ *   - `task release --resume`   → `working tree is not clean` (this check)
+ *
+ * So the guard prescribed a remedy the preflight refused, in both spellings,
+ * and the only way through was to hand-craft the `release: X.Y.Z` commit the
+ * pipeline makes for itself one step later.
+ *
+ * `docs/release-runbook.md` already claimed this was closed on 2026-09-03 and
+ * the drill pins `plain-run-reuses-an-existing-branch` for it. Both were true
+ * of the fix that landed — in `checkout_release_branch`, which is STEP 1. The
+ * preflight runs before step 1, so from the release branch the run never
+ * arrived at the code that had been repaired. The claim was not wrong about
+ * step 1; it was wrong that step 1 was reachable from that position.
+ *
+ * Why `release/{target}` is a legitimate start, with or without `--resume`:
+ *
+ * It is the position the pipeline itself leaves behind. `--resume` remains
+ * meaningful for what it was always for — skipping a COMMIT, a PR, a tag or a
+ * Release that already exists — and the `!resume` tag-exists check in
+ * `preflight` still refuses a plain re-run of an already-tagged version.
+ *
+ * Why a dirty tree is accepted THERE and nowhere else:
+ *
+ * On `release/{target}` the dirt is this pipeline's own step-2 output, and
+ * step 3 sweeps it with `git add -A` regardless. Refusing it can therefore
+ * only ever fire against the tool's own state. On `main` the same tree is an
+ * operator's unrelated work about to be swept into a release commit, so the
+ * refusal stays exactly as it was. The accepted files are PRINTED rather than
+ * absorbed silently, and `check_release_pr_shape` still refuses anything
+ * outside the version-bump allowlist on the resulting PR — two nets under the
+ * one place this relaxes.
+ */
+export function preflightPosition(opts: {
+    branch: string;
+    mainBranch: string;
+    releaseBranch: string;
+    porcelain: string;
+}): PositionVerdict {
+    const { branch, mainBranch, releaseBranch, porcelain } = opts;
+    if (branch !== mainBranch && branch !== releaseBranch) {
+        return {
+            proceed: false,
+            message:
+                `release must run from '${mainBranch}' or '${releaseBranch}', ` +
+                `currently on '${branch}'`,
+        };
+    }
+    if (!porcelain.trim()) {
+        return { proceed: true };
+    }
+    if (branch === mainBranch) {
+        return { proceed: false, message: 'working tree is not clean; commit or stash first' };
+    }
+    return {
+        proceed: true,
+        notice:
+            `working tree is not clean, and on '${releaseBranch}' that is this pipeline's own ` +
+            'step-2 output — step 3 commits it with `git add -A`. Files that will be swept ' +
+            'into the release commit:\n' +
+            porcelain
+                .split('\n')
+                .filter((l) => l.trim())
+                .map((l) => `      ${l}`)
+                .join('\n'),
+    };
+}

package/src/scripts/_lib/review_skipped_record.ts

@@ -34,6 +34,7 @@
  */
 export type MutationMeasure = 'exact' | 'capped_approximation';
 
+import { appliedIds } from './audit_field_provenance.js';
 import type { NoFreeForm } from './runtime_journal.js';
 import { type PrivacyClass } from './privacy_class.js';
 
@@ -55,6 +56,20 @@ export interface ReviewSkippedInput {
     /** Stable id (ULID, UUID, or content hash); caller supplies. */
     id: string;
     work_id?: string | undefined;
+    /**
+     * Stable rule ids the run ACTUALLY carried. Absent means `[]`, an honest
+     * absence — this writer observes a review that did NOT happen, so it
+     * usually has no rules observation to offer in either direction.
+     *
+     * It wrote the literal `['delegation-policy']` on every line until
+     * 2026-09-07, which made the whole audit stream's most frequent "pattern" a
+     * property of the writer. See `_lib/audit_field_provenance.ts` for the
+     * measurement, and note the difference from `skills_applied` below: that
+     * field is OMITTED because audit-log-v1 lets absence mean "not recorded",
+     * while `rules_applied` is mandatory on every line and `[]` is how absence
+     * is spelled there.
+     */
+    rules_applied?: string[] | null | undefined;
 }
 
 export interface BuiltReviewSkippedLine {
@@ -102,7 +117,8 @@ export function buildReviewSkippedLine(input: ReviewSkippedInput): BuiltReviewSk
         risk_class: input.diff_lines >= HIGH_RISK_DIFF_LINES ? 'high' : 'medium',
         memory: { asks: 0, hits: 0 },
         verify: { claims: 0, first_try_passes: 0 },
-        rules_applied: ['delegation-policy'],
+        // COMPUTED, never a producer constant.
+        rules_applied: appliedIds(input.rules_applied),
         // MANDATORY on every audit line, same as the orchestration producer.
         privacy_class: PRODUCER_PRIVACY_CLASS,
         // `skills_applied` is OMITTED here, deliberately and not by oversight.

package/src/scripts/_lib/runtime_journal.ts

@@ -174,6 +174,8 @@ import type { DatabaseSync } from 'node:sqlite';
 import { current_branch, git_common_dir, git_dir } from './git_common_dir.js';
 import type { TerminalState } from './outcome_envelope.js';
 import { readRunTerminalState, RUN_TERMINAL_STATES } from './outcome_vocabularies.js';
+import { addColumnIfMissing } from './sqlite_schema.js';
+import { readSurface, type Surface } from './surface.js';
 import {
     isSqliteAvailableSync,
     loadSqliteSync,
@@ -408,6 +410,14 @@ export interface JournalEvent {
     at: string;
     /** Bounded identifier: the hook or command name. Never free text. */
     capability: string;
+    /**
+     * IDE / CLI / cloud dimension of the dispatch. Closed vocabulary, and
+     * almost always `unknown`: no host observed here sends a distinguishing
+     * marker and the detector refuses to infer one. Recorded anyway because
+     * "did this come from the surface the lattice assumed" has no answer at
+     * all while the field is absent.
+     */
+    surface: Surface;
     /** Imported from `outcome_envelope.ts`; null until an episode terminates. */
     terminal_state: TerminalState | null;
     /** Repo-relative locator for the return. Never an absolute path. */
@@ -447,6 +457,7 @@ export const JOURNAL_RECORD_KEYS = Object.freeze([
     'worktree_id',
     'at',
     'capability',
+    'surface',
     'terminal_state',
     'return_ref',
     'verification_ref',
@@ -759,6 +770,7 @@ function createSchema(db: DatabaseSync): void {
             worktree_id TEXT NOT NULL,
             at TEXT NOT NULL,
             capability TEXT NOT NULL,
+            surface TEXT NOT NULL DEFAULT 'unknown',
             terminal_state TEXT,
             return_ref TEXT,
             verification_ref TEXT,
@@ -767,6 +779,9 @@ function createSchema(db: DatabaseSync): void {
             amends_seq INTEGER
         )`,
     );
+    // A pre-existing row takes the default, which is the honest value: that
+    // dispatch was never asked what surface it came from.
+    addColumnIfMissing(db, 'journal_event', 'surface', "TEXT NOT NULL DEFAULT 'unknown'");
     db.exec('CREATE INDEX IF NOT EXISTS idx_event_episode ON journal_event(repository_id, episode_id, seq)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_event_session ON journal_event(repository_id, session_id, seq)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_event_task ON journal_event(repository_id, task_id)');
@@ -984,6 +999,8 @@ export interface RecordEventInput {
     prompt_id?: string | null;
     episode_id?: string | null;
     terminal_state?: TerminalState | null;
+    /** Closed vocabulary; anything else (including absent) records `unknown`. */
+    surface?: Surface | null;
     return_ref?: string | null;
     verification_ref?: string | null;
     consumption?: Consumption | null;
@@ -1057,6 +1074,10 @@ export function recordEvent(h: JournalHandle, input: RecordEventInput): JournalE
         worktree_id,
         at,
         capability: input.capability,
+        // Tolerant by design: a surface this build cannot place is `unknown`,
+        // never a throw. The field answers "which surface" and must not be able
+        // to fail a write that would otherwise have succeeded.
+        surface: readSurface(input.surface),
         terminal_state: input.terminal_state ?? null,
         return_ref: requireRef('return_ref', input.return_ref),
         verification_ref: requireRef('verification_ref', input.verification_ref),
@@ -1070,9 +1091,9 @@ export function recordEvent(h: JournalHandle, input: RecordEventInput): JournalE
             `INSERT INTO journal_event
              (event, episode_id, session_id, task_id, prompt_id, boundary_status,
               boundary_rule_version, repository_id, worktree_id, at, capability,
-              terminal_state, return_ref, verification_ref, consumption, retain_until,
-              amends_seq)
-             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+              surface, terminal_state, return_ref, verification_ref, consumption,
+              retain_until, amends_seq)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         )
         .run(
             row.event,
@@ -1086,6 +1107,7 @@ export function recordEvent(h: JournalHandle, input: RecordEventInput): JournalE
             row.worktree_id,
             row.at,
             row.capability,
+            row.surface,
             row.terminal_state,
             row.return_ref,
             row.verification_ref,
@@ -1111,6 +1133,7 @@ function toEvent(r: Record<string, unknown>): JournalEvent {
         worktree_id: String(r['worktree_id']),
         at: String(r['at']),
         capability: String(r['capability']),
+        surface: readSurface(r['surface']),
         // Tolerant, not a cast: a value this build cannot place reads as null.
         terminal_state: readRunTerminalState(r['terminal_state']),
         return_ref: (r['return_ref'] as string | null) ?? null,

package/src/scripts/_lib/runtime_wiring_checks.ts

@@ -28,6 +28,10 @@ import process from 'node:process';
 import { parse as parseYaml } from 'yaml';
 
 import { inheritedGitOverrides } from './repo_root.js';
+import {
+    checkHostPermissionSettings,
+    defaultHostPermissionDeps,
+} from './host_permission_checks.js';
 
 /** The verdict shape `cmd_doctor` renders. Mirrors its internal `Dict` rows. */
 export interface WiringCheck {
@@ -291,7 +295,7 @@ export function checkInheritedGitEnv(env: NodeJS.ProcessEnv = process.env): Wiri
  * 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;
+export const WIRING_CHECK_IDS = ['settings-resolution', 'router-artifact', 'hook-resolution', 'inherited-git-env', 'hooks-kill-switch', 'host-permission-settings'] as const;
 
 
 /**
@@ -333,6 +337,7 @@ export function checkHooksDisabled(env: NodeJS.ProcessEnv = process.env): Wiring
 
 export function wiringRunners(opts: {
     packageRoot: string;
+    projectRoot: string;
     iterOverrides: () => Iterable<[string, unknown, string]>;
 }): Record<string, () => WiringCheck> {
     return {
@@ -344,6 +349,12 @@ export function wiringRunners(opts: {
         'hook-resolution': () => checkHookResolution(opts.packageRoot).check,
         'inherited-git-env': () => checkInheritedGitEnv(),
         'hooks-kill-switch': () => checkHooksDisabled(),
+        // The host's own permission settings, which decide how often a call is
+        // confirmed. It lives with this family rather than its own because
+        // `checkHookWiring` below already reads the same `~/.claude/settings.json`
+        // for the same host — the question is the same surface, one key over.
+        'host-permission-settings': () =>
+            checkHostPermissionSettings(defaultHostPermissionDeps(opts.projectRoot)),
     };
 }
 

package/src/scripts/_lib/security_lint.ts

@@ -13,8 +13,12 @@
 //      skipped by every check. Grep-auditable, scoped to the block.
 //   2. Confidence weighting — a match in a doc / example / template / evals
 //      file scores at 0.25x; below the FAIL threshold it is a WARN.
-//   3. Per-file pragma — `<!-- security-lint: allow <check> "<reason>" -->`
-//      anywhere in the file suppresses one check for that file.
+//   3. Bound pragma — `<!-- security-lint: allow <check> "<reason>" sha256:<hex> -->`
+//      anywhere in the file suppresses ONE check for the specific evidence whose
+//      fingerprint is listed. Repeat `sha256:<hex>` once per accepted match. The
+//      unbound form (no hash) still suppresses the whole file and reports itself
+//      as a `legacy-pragma` finding, because a key lookup with no content
+//      binding accepts whatever that line is later changed to say.
 //
 // There is no global allowlist — that is the rejected pattern.
 //
@@ -27,6 +31,7 @@
 //   - `report()` reproduces the glyphs (🔴 / ⚠️), the `(-rank, path, line)`
 //     sort, the weight note `(weight 0.25)`, and every printed string verbatim.
 
+import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -61,11 +66,18 @@ export const DEFAULT_SCAN_ROOTS: readonly string[] = [
 const _EXAMPLE_PATH =
     /(^|\/)(docs|evals|tests?|fixtures?)(\/|$)|example|template|sample|\/_template/i;
 
-//   Python: re.compile(r'<!--\s*security-lint:\s*allow\s+(?P<check>[\w-]+)\s+"(?P<reason>[^"]+)"\s*-->')
+// Grammar: `<!-- security-lint: allow <check> "<reason>" [sha256:<hex>]... -->`
 // JS `\w` is ASCII-only by default (matches Python re's `[\w-]` for the ASCII
 // check ids used here). Global flag so finditer-style iteration works.
+//
+// The hash group is OPTIONAL and repeatable. Optional because the unbound form
+// must keep working — a grammar change that invalidates every existing pragma
+// at once turns a hardening into an outage, and the migration is what removes
+// the unbound population, not the parser. Repeatable because one file can
+// legitimately carry several accepted matches of the same check, and a single
+// hash would force either a second pragma line or a whole-file fallback.
 const _PRAGMA =
-    /<!--\s*security-lint:\s*allow\s+([A-Za-z0-9_-]+)\s+"([^"]+)"\s*-->/g;
+    /<!--\s*security-lint:\s*allow\s+([A-Za-z0-9_-]+)\s+"([^"]+)"((?:\s+sha256:[0-9a-f]{64})*)\s*-->/g;
 
 //   Python: re.compile(r"^(\s*)(`{3,}|~{3,})\s*([\w-]*)\s*$")
 const _FENCE = /^(\s*)(`{3,}|~{3,})\s*([A-Za-z0-9_-]*)\s*$/;
@@ -136,6 +148,21 @@ export function path_weight(rel_path: string): number {
     return is_example_path(rel_path) ? 0.25 : 1.0;
 }
 
+const PROJECTION_PREFIX = 'dist/agent-src/';
+
+/**
+ * Fold a projected path back onto the source it was copied from.
+ *
+ * `dist/agent-src/` is a byte-for-byte copy of `src/` with paths rewritten
+ * (ADR-201), so an artifact and its projection are the same artifact for the
+ * purpose of "which evidence did a human accept". Two identities would mean two
+ * fingerprints for one accepted line, and only one of them could be written
+ * into the pragma the projection copies verbatim.
+ */
+export function source_identity(rel: string): string {
+    return rel.startsWith(PROJECTION_PREFIX) ? `src/${rel.slice(PROJECTION_PREFIX.length)}` : rel;
+}
+
 /** A file pre-split into lines with a fence/pragma mask the linters reuse. */
 export class ScannedFile {
     path: string; // absolute or as-given path
@@ -145,6 +172,8 @@ export class ScannedFile {
     in_example_fence: boolean[];
     in_any_fence: boolean[];
     pragmas: Record<string, string>; // check id → reason
+    /** check id → the sha256 fingerprints that pragma accepts. Empty = unbound. */
+    pragma_hashes: Record<string, readonly string[]>;
     weight: number;
 
     constructor(
@@ -155,6 +184,7 @@ export class ScannedFile {
         in_any_fence: boolean[],
         pragmas: Record<string, string>,
         weight: number,
+        pragma_hashes: Record<string, readonly string[]> = {},
     ) {
         this.path = pathArg;
         this.rel = rel;
@@ -163,12 +193,82 @@ export class ScannedFile {
         this.in_any_fence = in_any_fence;
         this.pragmas = pragmas;
         this.weight = weight;
+        this.pragma_hashes = pragma_hashes;
     }
 
     pragma_allows(check: string): boolean {
         return Object.prototype.hasOwnProperty.call(this.pragmas, check);
     }
 
+    /**
+     * Which form of pragma this file carries for `check`.
+     *
+     * `absent`  — no pragma; scan normally.
+     * `legacy`  — a pragma with no fingerprint. Suppresses the whole file, as it
+     *             always did, and says so: a key lookup accepts whatever the
+     *             line is later changed to say, which is the defect being paid
+     *             down, not a mode anybody should choose.
+     * `bound`   — a pragma listing fingerprints. Suppresses exactly the matches
+     *             whose evidence hashes to one of them; anything else survives.
+     */
+    pragma_form(check: string): 'absent' | 'legacy' | 'bound' {
+        if (!this.pragma_allows(check)) return 'absent';
+        return (this.pragma_hashes[check] ?? []).length > 0 ? 'bound' : 'legacy';
+    }
+
+    /**
+     * The fingerprint one finding's evidence hashes to.
+     *
+     * WHAT IS HASHED, and each part earns its place:
+     *   check id      — the same line may legitimately be accepted for one check
+     *                   and not another.
+     *   rel path      — the location IDENTITY. Not the line NUMBER: an unrelated
+     *                   insert above would otherwise break every pragma in the
+     *                   file, and a suppression that breaks on unrelated edits
+     *                   gets deleted rather than re-derived. A `dist/agent-src/`
+     *                   path folds to its `src/` original first, because the
+     *                   projection is byte-exact by contract (ADR-201) and
+     *                   carries the pragma verbatim — without the fold, every
+     *                   migrated pragma would suppress the source and leave its
+     *                   own copy flagged, which is a gate that reds on a file
+     *                   nobody may edit.
+     *   matched line, — the evidence. ASCII whitespace runs collapse so a reflow
+     *   normalized      does not invalidate the binding, `sha256:<hex>` tokens are
+     *                   removed, and NOTHING else is stripped: the zero-width
+     *                   characters this suite hunts are exactly what a wider
+     *                   normalizer would erase.
+     *
+     * WHY THE HASH TOKENS COME OUT. A pragma's own reason string can be the
+     * matched evidence — two in this tree are, because they quote the very
+     * phrases their check detects in order to explain themselves. Without this
+     * the fingerprint would have to be computed over a line that already
+     * contains it, which has no fixed point: writing the hash changes the line,
+     * which changes the hash. Stripping the tokens makes the fingerprint stable
+     * under the act of recording it, and costs nothing elsewhere — a `sha256:`
+     * token in ordinary prose is not evidence of anything a linter here checks.
+     *
+     * Deliberately NOT the whole file: incidental content elsewhere would make
+     * every unrelated edit re-fire the pragma, which is the noise that produces
+     * blanket suppressions.
+     */
+    evidence_fingerprint(finding: Finding): string {
+        const text = finding.line > 0 ? (this.lines[finding.line - 1] ?? '') : '';
+        const normalized = text
+            .replace(/\s*sha256:[0-9a-f]{64}/g, '')
+            .replace(/[ \t]+/g, ' ')
+            .trim();
+        return createHash('sha256')
+            .update(`${finding.check}\n${source_identity(this.rel)}\n${normalized}`, 'utf-8')
+            .digest('hex');
+    }
+
+    /** Drop the findings this file's BOUND pragma for `check` accepts. */
+    filter_bound_pragma(check: string, findings: readonly Finding[]): Finding[] {
+        const accepted = new Set(this.pragma_hashes[check] ?? []);
+        if (accepted.size === 0) return [...findings];
+        return findings.filter((f) => !accepted.has(this.evidence_fingerprint(f)));
+    }
+
     /** Yield [lineno, text] honouring the fence masks (mirrors iter_lines). */
     *iter_lines(
         opts: { skip_example_fence?: boolean; skip_any_fence?: boolean } = {},
@@ -286,11 +386,21 @@ export function scan_file(filePath: string): ScannedFile {
     // Pragmas are explicit, grep-auditable opt-out markers — honour them
     // anywhere in the file.
     const pragmas: Record<string, string> = {};
+    const pragmaHashes: Record<string, readonly string[]> = {};
     for (const text of lines) {
         _PRAGMA.lastIndex = 0;
         let m: RegExpExecArray | null;
         while ((m = _PRAGMA.exec(text)) !== null) {
-            pragmas[m[1] as string] = m[2] as string;
+            const check = m[1] as string;
+            pragmas[check] = m[2] as string;
+            const hashes = (m[3] ?? '').match(/sha256:([0-9a-f]{64})/g) ?? [];
+            // Union across repeated pragmas for one check rather than replace:
+            // two lines each accepting one match is a legitimate spelling, and
+            // a last-one-wins read would silently drop the first.
+            pragmaHashes[check] = [
+                ...(pragmaHashes[check] ?? []),
+                ...hashes.map((h) => h.slice('sha256:'.length)),
+            ];
             if (m.index === _PRAGMA.lastIndex) {
                 _PRAGMA.lastIndex += 1;
             }
@@ -305,6 +415,7 @@ export function scan_file(filePath: string): ScannedFile {
         in_any,
         pragmas,
         path_weight(rel),
+        pragmaHashes,
     );
 }
 
@@ -330,6 +441,7 @@ export function scan_path(filePath: string, base: string): ScannedFile {
         sf.in_any_fence,
         sf.pragmas,
         path_weight(rel),
+        sf.pragma_hashes,
     );
 }
 
@@ -379,12 +491,23 @@ function _pathCmp(a: string, b: string): number {
 }
 
 /** Yield ScannedFile for every matching file under the given roots. */
+/**
+ * Walk a corpus.
+ *
+ * `scanBase` exists for the bounded-root mode every child linter now carries
+ * (`--root DIR`): the roots stay relative, the base they resolve against moves.
+ * Absent, it is the package root and the walk is exactly what it always was —
+ * `scan_path(p, ROOT)` computes the same `rel` and the same `path_weight` as the
+ * `scan_file(p)` this used to call, so a flagless run reads the identical corpus
+ * with identical finding paths.
+ */
 export function* iter_corpus(
     roots: readonly string[] = DEFAULT_SCAN_ROOTS,
     exts: readonly string[] = ['.md'],
+    scanBase: string = ROOT,
 ): Generator<ScannedFile> {
     for (const root of roots) {
-        const base = path.join(ROOT, root);
+        const base = path.join(scanBase, root);
         if (!fs.existsSync(base)) {
             continue;
         }
@@ -396,12 +519,61 @@ export function* iter_corpus(
                 continue;
             }
             if (st.isFile() && exts.includes(path.extname(p))) {
-                yield scan_file(p);
+                yield scan_path(p, scanBase);
             }
         }
     }
 }
 
+/**
+ * The prefix a child linter uses to publish what it inspected, under `--json`.
+ *
+ * WHY STDERR, AND WHY ONLY UNDER `--json`. Under `--json` a child's STDOUT is a
+ * findings array with one consumer — `lint_agent_security`, which parses it.
+ * A count printed there would corrupt the payload. Stderr is free on that path
+ * and already carries the dead-scope diagnostic, so the umbrella reads the
+ * count from the same stream it would read a failure on.
+ *
+ * The umbrella SUMS these across its five children and publishes the total as
+ * its own `scanned:` line. The sum counts artifact INSPECTIONS, not distinct
+ * artifacts: a file in more than one child's corpus is counted once per child
+ * that read it. That is deliberate and is the stronger collapse detector — a
+ * distinct-union count would stay high when one child's corpus moved, as long
+ * as another child still covered those paths, which is exactly the failure
+ * `gate-coverage.yml` exists to catch.
+ */
+/** The check id an unbound pragma reports itself under. */
+export const LEGACY_PRAGMA_CHECK = 'legacy-pragma';
+
+/**
+ * The finding an unbound pragma emits about itself.
+ *
+ * LOW, so it never blocks: the unbound form is legal and this is a
+ * migration signal, not a violation. It is a FINDING rather than a printed
+ * aside so it travels every path the linters already have — the human report,
+ * the `--json` payload the umbrella aggregates, and the SARIF file — without
+ * a second reporting channel that only one of them reads.
+ */
+export function legacy_pragma_finding(sf: ScannedFile, check: string): Finding {
+    return new Finding(
+        sf.rel,
+        0,
+        LEGACY_PRAGMA_CHECK,
+        'LOW',
+        `unbound \`security-lint: allow ${check}\` pragma suppresses this whole file — ` +
+            'it accepts whatever the matched text is later changed to say. Bind it with ' +
+            '`sha256:<hex>` per accepted match.',
+        sf.weight,
+    );
+}
+
+export const CHILD_SCANNED_PREFIX = 'scanned: ';
+
+/** Publish a child linter's inspected count on stderr. See {@link CHILD_SCANNED_PREFIX}. */
+export function report_child_scanned(count: number): void {
+    process.stderr.write(`${CHILD_SCANNED_PREFIX}${String(count)}\n`);
+}
+
 /**
  * Print findings grouped by severity; return an exit code.
  *