@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/hooks/dispatch_hook.ts

@@ -52,7 +52,8 @@ import {
   setHookStdinOverride,
   clearHookStdinOverride,
 } from "./hook_stdin.js";
-import { emitFor, type PermissionDecision, type Severity } from "./host_semantics.js";
+import { emitFor, writeStdout, type PermissionDecision, type Severity } from "./host_semantics.js";
+import { collectUserNotice, type NoticeBatch } from "./user_notice.js";
 import { _concern_permission_verdict, _payload_tool_name, _permission_for } from "./permission_gate.js";
 export { _concern_permission_verdict, _payload_tool_input, _payload_tool_name, _permission_for, _working_tree_root } from "./permission_gate.js";
 import { _concern_body_classes, applyPayloadFields, planPayloadShapes } from "./payload_stub.js";
@@ -1264,6 +1265,7 @@ export function main(argv?: string[]): number {
   // stdout-injection; harmless surfacing elsewhere). All other events keep
   // the swallow-stdout contract unchanged.
   const context_blocks: string[] = [];
+  const notices: NoticeBatch = []; // `hooks/user_notice.ts`, never model context
   // Per-concern message for the host emission (P0.1). Kept OUT of
   // feedback_entries on purpose: that record is written to disk with a
   // fixed-field schema (PII-exclusion-by-construction), and a concern's raw
@@ -1376,6 +1378,7 @@ export function main(argv?: string[]): number {
     ) {
       context_blocks.push(injected((reply["context"] as string).trim()));
     }
+    collectUserNotice(notices, concern, reply, injected);
     feedback_entries.push({
       concern: String(concern["name"]),
       exit_code: rc,
@@ -1402,9 +1405,6 @@ export function main(argv?: string[]): number {
   writeConcernTimings(String(envelope["event"] ?? ""), String(envelope["platform"] ?? ""), timing_samples);
   _write_feedback(envelope, session_id, feedback_entries, final_rc, started_at);
   _record_rule_trips(envelope, feedback_entries);
-  if (context_blocks.length > 0 && final_rc === EXIT_ALLOW) {
-    process.stdout.write(context_blocks.join("\n\n") + "\n");
-  }
 
   // P0.1 host-semantics translation. The internal ladder (0/1/2) is written to
   // the feedback dir verbatim above — that record is unchanged. What leaves the
@@ -1427,9 +1427,8 @@ export function main(argv?: string[]): number {
     final_rc,
     _permission_for(args.event, envelope, final_rc, permission_verdicts),
   );
-  if (emission.stdout) {
-    process.stdout.write(emission.stdout);
-  }
+  const context_out = context_blocks.length > 0 && final_rc === EXIT_ALLOW ? context_blocks.join("\n\n") + "\n" : "";
+  writeStdout(args.platform, args.event, context_out, emission, notices, session_id, (s) => process.stdout.write(s));
   if (emission.stderr) {
     process.stderr.write(emission.stderr);
   }

package/src/scripts/hooks/host_semantics.ts

@@ -35,6 +35,7 @@
  */
 
 import { blockExitFor, DEFAULT_SURFACE, loadHostLowering, surfaceRow, verifiedPlatforms } from "./host_lowering.js";
+import { hostShowsUserNotice, writeNoticeReceipts, type NoticeBatch } from "./user_notice.js";
 
 /** Internal severity, mirroring dispatch_hook's EXIT_ALLOW / BLOCK / WARN. */
 export type Severity = "allow" | "warn" | "block";
@@ -133,6 +134,77 @@ export function claudeAdditionalContext(event: string, text: string): string {
     })}\n`;
 }
 
+function isObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Compose the dispatcher's stdout from its three parts: plain `session_start`
+ * context, the native emission, and a user-addressed notice.
+ *
+ * Without a notice — or on a host with no verified user field — this is the
+ * old output byte for byte: context, then emission. With one, the host parses
+ * stdout as JSON only when the whole of it is one object, so the parts are
+ * MERGED as structures, never concatenated as text: the emission's object is
+ * kept, context joins its `hookSpecificOutput.additionalContext`, and the
+ * notice joins `systemMessage`. Plain context is accepted on `session_start`
+ * only, and an emission that is not one JSON object is never reinterpreted —
+ * in either case the notice is dropped and the old output stands.
+ */
+export function withUserNotice(
+    platform: string,
+    event: string,
+    context: string,
+    emission: string,
+    notice: string,
+): string {
+    const legacy = context + emission;
+    const text = notice.trim();
+    if (!text || !hostShowsUserNotice(platform) || !usesNativeEmission(platform)) return legacy;
+    if (context.trim() && event !== "session_start") return legacy;
+    let reply: Record<string, unknown> = {};
+    if (emission.trim()) {
+        try {
+            reply = JSON.parse(emission) as Record<string, unknown>;
+        } catch {
+            return legacy;
+        }
+        if (!isObject(reply)) return legacy;
+    }
+    // A field this merge would extend must already have the type it extends.
+    const hsoIn = reply["hookSpecificOutput"];
+    if (hsoIn !== undefined && !isObject(hsoIn)) return legacy;
+    if (![reply["systemMessage"], hsoIn?.["additionalContext"]].every((v) => v === undefined || typeof v === "string")) return legacy;
+    const join = (a: unknown, b: string, sep: string): string => (typeof a === "string" && a ? `${a}${sep}${b}` : b);
+    if (context.trim()) {
+        const hso = hsoIn ?? { hookEventName: nativeEventName(platform, event) };
+        reply["hookSpecificOutput"] = { ...hso, additionalContext: join(hso["additionalContext"], context.trim(), "\n\n") };
+    }
+    reply["systemMessage"] = join(reply["systemMessage"], text, "\n");
+    return `${JSON.stringify(reply)}\n`;
+}
+
+/**
+ * Write the dispatcher's whole stdout — `withUserNotice` over its parts — and
+ * only then a receipt for each notice that is actually in what was written: a
+ * write that throws leaves no receipt, and a dropped notice leaves none, so its
+ * concern says it again instead of counting it as shown. The notice rides only
+ * on exit 0, because the host parses stdout only then.
+ */
+export function writeStdout(
+    platform: string,
+    event: string,
+    context: string,
+    emission: Emission,
+    notices: NoticeBatch,
+    sessionId: string,
+    write: (text: string) => unknown,
+): void {
+    const out = withUserNotice(platform, event, context, emission.stdout, emission.exit === 0 ? notices.map((n) => n.text).join("\n") : "");
+    if (out) write(out);
+    if (notices.length > 0 && out !== context + emission.stdout) writeNoticeReceipts(notices, sessionId);
+}
+
 /**
  * A host permission verdict for a `pre_tool_use` call.
  *

package/src/scripts/hooks/lazy_concern.ts

@@ -76,6 +76,10 @@ export const LAZY_CONCERNS: Readonly<Record<string, { readonly chunk: string; re
             chunk: 'code_graph_refresh.chunk.cjs',
             source: 'code_graph_refresh_hook',
         }),
+        'src/scripts/update_notice_hook.ts': Object.freeze({
+            chunk: 'update_notice.chunk.cjs',
+            source: path.join('..', 'update_notice_hook'),
+        }),
     });
 
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;

package/src/scripts/hooks/user_notice.ts

@@ -0,0 +1,105 @@
+/**
+ * The user-addressed channel: text a concern hands the dispatcher for the HUMAN,
+ * which the host shows in its own UI and never adds to model context.
+ *
+ * WHY IT EXISTS. Every channel the dispatcher had addressed the model
+ * (`additional_context`, `context`) or went to stderr, and every host runs the
+ * dispatcher on pipes — so a concern with something to tell the user had no
+ * path that reached them. `update-notice` was refused registration for exactly
+ * that: bound, it would have said nothing anywhere.
+ *
+ * Claude Code documents a `systemMessage` field on every hook event, "Display a
+ * message to the user", read off the 2.1.310 binary on 2026-10-24. It is the
+ * only host this package has verified a user-addressed field on, so the set
+ * below is one host wide; an unlisted host gets nothing rather than a guess.
+ *
+ * loss_class: ephemeral-lossy
+ *
+ * A notice longer than USER_NOTICE_MAX_CHARS loses its tail, deliberately: the
+ * text is for the user's UI and never reaches the model, and a notice is a few
+ * lines by contract, so nothing recovers the cut part.
+ */
+
+import * as fs from 'node:fs';
+
+import { write_atomic } from '../_lib/fs_atomic.js';
+import { write_target } from '../_lib/user_global_paths.js';
+
+/** The concern reply key a notification concern puts its user-facing text under. */
+export const USER_NOTICE_KEY = 'user_notice';
+
+/** The reply key naming this one notice, echoed into its receipt and never shown. */
+export const USER_NOTICE_ID_KEY = 'notice_id';
+
+/** Longest notice the dispatcher forwards, in Unicode code points; a notice is a few lines, never a document. */
+export const USER_NOTICE_MAX_CHARS = 1000;
+
+/** Hosts with a verified field that shows text to the user and not to the model. */
+export const USER_NOTICE_HOSTS: ReadonlySet<string> = new Set(['claude']);
+
+export function hostShowsUserNotice(platform: unknown): boolean {
+    return typeof platform === 'string' && USER_NOTICE_HOSTS.has(platform);
+}
+
+/**
+ * The notices one dispatch kept, each with the concern it came from, in
+ * manifest order. One entry carries both, so the text that is emitted and the
+ * concern that gets a receipt can never come apart.
+ */
+export type NoticeBatch = Array<{ readonly concern: string; readonly text: string; readonly id: string }>;
+
+/**
+ * Only a `notification` concern may address the user: no other effect was
+ * reviewed for it. The text is cleaned, then capped by code point so a pair is
+ * never split, and kept only if something is left to show.
+ */
+export function collectUserNotice(
+    batch: NoticeBatch,
+    concern: Record<string, unknown>,
+    reply: Record<string, unknown>,
+    clean: (text: string) => string,
+): void {
+    const notice = reply[USER_NOTICE_KEY];
+    if (concern['effect'] !== 'notification' || typeof notice !== 'string') return;
+    const text = Array.from(clean(notice.trim())).slice(0, USER_NOTICE_MAX_CHARS).join('').trim();
+    const id = reply[USER_NOTICE_ID_KEY];
+    if (text) batch.push({ concern: String(concern['name']), text, id: typeof id === 'string' ? id.slice(0, 64) : '' });
+}
+
+/**
+ * A delivery receipt: the dispatcher writes one per concern whose notice it
+ * actually put into host output, naming the session and the notice's own id.
+ * A concern that must not count a notice as shown until it was handed to the
+ * host reads it on its next run and matches the id it handed over; anything the
+ * dispatcher dropped leaves no receipt for that id, so the concern says it again.
+ */
+export interface NoticeReceipt {
+    readonly session_id: string;
+    readonly notice_id: string;
+    readonly at: string;
+}
+
+function receiptPath(concern: string): string {
+    return write_target(`user-notice-${concern}.delivered`);
+}
+
+export function writeNoticeReceipts(batch: NoticeBatch, sessionId: string): void {
+    for (const { concern, id } of batch) {
+        try {
+            write_atomic(receiptPath(concern), JSON.stringify({ session_id: sessionId, notice_id: id, at: new Date().toISOString() }));
+        } catch {
+            // no receipt → the concern repeats its notice, which is the safe direction
+        }
+    }
+}
+
+export function readNoticeReceipt(concern: string): NoticeReceipt | null {
+    try {
+        const o = JSON.parse(fs.readFileSync(receiptPath(concern), 'utf-8')) as Record<string, unknown>;
+        return typeof o['session_id'] === 'string' && typeof o['notice_id'] === 'string' && typeof o['at'] === 'string'
+            ? { session_id: o['session_id'], notice_id: o['notice_id'], at: o['at'] }
+            : null;
+    } catch {
+        return null;
+    }
+}

package/src/scripts/lint_harvest_provenance.ts

@@ -30,7 +30,13 @@
  *   4. Pinning — `source_ref` carries a revision or is explicitly opaque; a
  *      bare URL is rejected because it cannot be re-verified later.
  *   5. Orphan citations — every `<!-- harvest:<id> -->` marker under the
- *      scanned roots resolves to a ledger row.
+ *      scanned roots resolves to a row in either ledger.
+ *   6. Mechanism decisions — `provenance/mechanisms.jsonl`, the source-free
+ *      decision ledger: a closed shape with no source id, pin or locator
+ *      (council O5), adopt|adapt carrying existing `realised_in` paths, reject
+ *      carrying a reason, gap|deferred carrying a roadmap or `open`. A
+ *      mechanism may repeat — the ledger is append-only and a later row
+ *      supersedes an earlier one.
  *
  * An EMPTY ledger with zero markers is a legitimate pass and is reported as
  * such on stdout. A gate that scans nothing and exits green silently is
@@ -57,6 +63,7 @@ const _HERE = path.dirname(_FILE);
 // src/scripts/lint_harvest_provenance.ts → two levels up is the repo root.
 const REPO = path.resolve(_HERE, '..', '..');
 const LEDGER_REL = 'provenance/harvests.jsonl';
+const MECHANISMS_REL = 'provenance/mechanisms.jsonl';
 
 /** Roots scanned for citation markers. Markdown-bearing authored surfaces. */
 export const CITATION_SCAN_ROOTS: readonly string[] = [
@@ -102,11 +109,23 @@ export interface HarvestRecord {
     readonly verdict: 'adopt' | 'adapt';
 }
 
+export interface MechanismRecord {
+    readonly mechanism_id: string;
+    readonly verdict: 'adopt' | 'adapt' | 'reject' | 'already' | 'gap' | 'deferred';
+    readonly realised_in?: readonly string[];
+    readonly roadmap?: string;
+    readonly decided_at: string;
+    readonly reason?: string;
+    readonly reopen_if?: string;
+}
+
 export interface Finding {
     /** Ledger line number, or 0 for findings that belong to no single row. */
     readonly line: number;
-    readonly rule: 'schema' | 'uniqueness' | 'dead-row' | 'pinning' | 'orphan-citation';
+    readonly rule: 'schema' | 'uniqueness' | 'dead-row' | 'pinning' | 'orphan-citation' | 'verdict-requirement';
     readonly message: string;
+    /** The ledger the line number refers to; absent means the harvest ledger. */
+    readonly ledger?: string;
 }
 
 function isValidCalendarDate(s: string): boolean {
@@ -227,6 +246,100 @@ export function validateRecord(raw: unknown, line: number, repoRoot: string): Fi
     return findings;
 }
 
+const MECHANISM_FIELDS = ['mechanism_id', 'verdict', 'realised_in', 'roadmap', 'decided_at', 'reason', 'reopen_if'] as const;
+const MECHANISM_REQUIRED = ['mechanism_id', 'verdict', 'decided_at'] as const;
+const MECHANISM_VERDICTS: ReadonlySet<string> = new Set(['adopt', 'adapt', 'reject', 'already', 'gap', 'deferred']);
+
+/** `rel` (with an optional `:<line>`) is a repo-relative path that exists; else the finding. */
+function repoPathFinding(rel: string, field: string, line: number, repoRoot: string): Finding | null {
+    const bare = stripLineSuffix(rel);
+    const resolved = path.resolve(repoRoot, bare);
+    if (bare.trim() === '' || path.isAbsolute(bare) || !(resolved === repoRoot || resolved.startsWith(repoRoot + path.sep))) {
+        return { line, rule: 'schema', message: `${field} '${rel}' must be a repo-relative path inside the repo`, ledger: MECHANISMS_REL };
+    }
+    if (!fs.existsSync(resolved)) {
+        return { line, rule: 'dead-row', message: `${field} '${bare}' does not exist — the decision points at nothing`, ledger: MECHANISMS_REL };
+    }
+    return null;
+}
+
+/** Validate one `mechanisms.jsonl` row: closed and source-free, then the per-verdict requirement. */
+export function validateMechanismRecord(raw: unknown, line: number, repoRoot: string): Finding[] {
+    const at = (rule: Finding['rule'], message: string): Finding => ({ line, rule, message, ledger: MECHANISMS_REL });
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return [at('schema', 'record is not a JSON object')];
+    const rec = raw as Record<string, unknown>;
+    const findings: Finding[] = [];
+
+    for (const k of Object.keys(rec)) {
+        if ((MECHANISM_FIELDS as readonly string[]).includes(k)) continue;
+        findings.push(
+            at(
+                'schema',
+                /source|pin|locator/.test(k)
+                    ? `field '${k}' links a source to a mechanism — the tracked decision ledger is source-free (council O5); it belongs in the local lineage ledger`
+                    : `unexpected field '${k}' — the ledger schema is closed to [${MECHANISM_FIELDS.join(', ')}]`,
+            ),
+        );
+    }
+    for (const k of MECHANISM_REQUIRED) if (!(k in rec)) findings.push(at('schema', `missing required field '${k}'`));
+
+    if ('mechanism_id' in rec && (typeof rec.mechanism_id !== 'string' || !HARVEST_ID_RE.test(rec.mechanism_id))) {
+        findings.push(at('schema', `mechanism_id must be a kebab-case slug, got ${JSON.stringify(rec.mechanism_id)}`));
+    }
+    if ('decided_at' in rec && !(typeof rec.decided_at === 'string' && isValidCalendarDate(rec.decided_at))) {
+        findings.push(at('schema', `decided_at must be an ISO-8601 date (YYYY-MM-DD), got ${JSON.stringify(rec.decided_at)}`));
+    }
+    for (const k of ['reason', 'reopen_if'] as const) {
+        if (k in rec && (typeof rec[k] !== 'string' || (rec[k] as string).trim().length < EVIDENCE_MIN_LENGTH)) {
+            findings.push(at('schema', `${k} must be at least ${EVIDENCE_MIN_LENGTH} characters`));
+        }
+    }
+    const realised = rec.realised_in;
+    if (realised !== undefined && (!Array.isArray(realised) || realised.length === 0 || realised.some((r) => typeof r !== 'string'))) {
+        findings.push(at('schema', 'realised_in must be a non-empty list of repo-relative paths'));
+    } else if (Array.isArray(realised)) {
+        for (const r of realised as string[]) {
+            const f = repoPathFinding(r, 'realised_in', line, repoRoot);
+            if (f) findings.push(f);
+        }
+    }
+    if ('roadmap' in rec) {
+        if (typeof rec.roadmap !== 'string') findings.push(at('schema', "roadmap must be a repo-relative path or 'open'"));
+        else if (rec.roadmap !== 'open') {
+            const f = repoPathFinding(rec.roadmap, 'roadmap', line, repoRoot);
+            if (f) findings.push(f);
+        }
+    }
+
+    const verdict = rec.verdict;
+    if ('verdict' in rec && (typeof verdict !== 'string' || !MECHANISM_VERDICTS.has(verdict))) {
+        findings.push(at('schema', `verdict must be one of [${[...MECHANISM_VERDICTS].join(', ')}], got ${JSON.stringify(verdict)}`));
+    } else if ((verdict === 'adopt' || verdict === 'adapt') && realised === undefined) {
+        findings.push(at('verdict-requirement', `verdict '${verdict}' needs realised_in — an adoption that lives nowhere is not one`));
+    } else if (verdict === 'reject' && !('reason' in rec)) {
+        findings.push(at('verdict-requirement', "verdict 'reject' needs a reason — a rejection without one is re-litigated on every round"));
+    } else if ((verdict === 'gap' || verdict === 'deferred') && !('roadmap' in rec)) {
+        findings.push(at('verdict-requirement', `verdict '${verdict}' needs a roadmap that owns it, or 'open'`));
+    }
+    return findings;
+}
+
+/** Parse + validate every mechanism row. Repeats are allowed: a later row supersedes. */
+export function lintMechanismsText(
+    text: string,
+    repoRoot: string,
+): { readonly records: MechanismRecord[]; readonly findings: Finding[] } {
+    const { parsed, findings: parseFindings } = parseLedgerText(text);
+    const findings: Finding[] = parseFindings.map((f) => ({ ...f, ledger: MECHANISMS_REL }));
+    const records: MechanismRecord[] = [];
+    for (const { line, value } of parsed) {
+        const f = validateMechanismRecord(value, line, repoRoot);
+        findings.push(...f);
+        if (f.length === 0) records.push(value as MechanismRecord);
+    }
+    return { records, findings };
+}
+
 // ─── ledger parsing ──────────────────────────────────────────────────────────
 
 export interface ParsedLine {
@@ -371,18 +484,19 @@ export function collectPersonaSources(repoRoot: string, personaRoot = 'src/agent
     return citations;
 }
 
-/** Every citation must resolve to a ledger row. */
+/** Every citation must resolve to a row in either ledger. */
 export function findOrphanCitations(
     citations: readonly Citation[],
     records: readonly HarvestRecord[],
+    mechanisms: readonly MechanismRecord[] = [],
 ): Finding[] {
-    const known = new Set(records.map((r) => r.harvest_id));
+    const known = new Set([...records.map((r) => r.harvest_id), ...mechanisms.map((m) => m.mechanism_id)]);
     return citations
         .filter((c) => !known.has(c.id))
         .map((c) => ({
             line: 0,
             rule: 'orphan-citation' as const,
-            message: `${c.file} cites harvest '${c.id}', which has no row in ${LEDGER_REL}`,
+            message: `${c.file} cites harvest '${c.id}', which has no row in ${LEDGER_REL} or ${MECHANISMS_REL}`,
         }));
 }
 
@@ -422,6 +536,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     // the run would report a clean green over a file that no longer exists.
     try {
         assertWatchlistResolves({ gate: 'lint_harvest_provenance', candidates: [LEDGER_REL], repoRoot: REPO });
+        assertWatchlistResolves({ gate: 'lint_harvest_provenance', candidates: [MECHANISMS_REL], repoRoot: REPO });
     } catch (exc) {
         if (exc instanceof DeadScopeError) {
             process.stderr.write(`❌  ${exc.message}\n`);
@@ -432,9 +547,11 @@ export function main(argv: string[] = process.argv.slice(2)): number {
 
     const text = fs.readFileSync(ledgerPath, 'utf-8');
     const { records, findings } = lintLedgerText(text, REPO);
+    const mechText = fs.readFileSync(path.join(REPO, MECHANISMS_REL), 'utf-8');
+    const { records: mechanisms, findings: mechFindings } = lintMechanismsText(mechText, REPO);
     const citations = [...collectCitations(REPO), ...collectPersonaSources(REPO)];
-    const orphans = findOrphanCitations(citations, records);
-    const allFindings = [...findings, ...orphans];
+    const orphans = findOrphanCitations(citations, records, mechanisms);
+    const allFindings = [...findings, ...mechFindings, ...orphans];
 
     // Per-target completeness accounting over the two populations this gate
     // reasons about: the ledger's own rows, and the citations that point at
@@ -444,7 +561,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     // failure the success message above already tries to talk its way out of in
     // prose. The ledger states it structurally instead.
     const ledger = new GateLedger('lint_harvest_provenance');
-    const known = new Set(records.map((r) => r.harvest_id));
+    const known = new Set([...records.map((r) => r.harvest_id), ...mechanisms.map((m) => m.mechanism_id)]);
     // The row population is every PARSED ledger line, not `records`: a row that
     // fails validation or uniqueness is `continue`d and never reaches `records`,
     // so planning `records` would plan exactly the rows that passed and account
@@ -452,8 +569,11 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     // 100 %. Lines are the stable key; a Finding already carries one.
     const { parsed } = parseLedgerText(text);
     const badLines = new Set(findings.filter((f) => f.line > 0).map((f) => f.line));
+    const { parsed: mechParsed } = parseLedgerText(mechText);
+    const badMechLines = new Set(mechFindings.filter((f) => f.line > 0).map((f) => f.line));
     ledger.plan([
         ...parsed.map((r) => `row:${String(r.line)}`),
+        ...mechParsed.map((r) => `mechanism:${String(r.line)}`),
         ...citations.map((c) => `citation:${c.id}@${c.file}`),
     ]);
     for (const r of parsed) {
@@ -461,6 +581,11 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         if (badLines.has(r.line)) ledger.fail(id, 'ledger-row finding');
         else ledger.complete(id);
     }
+    for (const r of mechParsed) {
+        const id = `mechanism:${String(r.line)}`;
+        if (badMechLines.has(r.line)) ledger.fail(id, 'mechanism-row finding');
+        else ledger.complete(id);
+    }
     for (const c of citations) {
         const id = `citation:${c.id}@${c.file}`;
         if (known.has(c.id)) ledger.complete(id);
@@ -470,7 +595,8 @@ export function main(argv: string[] = process.argv.slice(2)): number {
 
     if (allFindings.length > 0) {
         for (const f of allFindings) {
-            const at = f.line > 0 ? `${LEDGER_REL}:${f.line}` : LEDGER_REL;
+            const file = f.ledger ?? LEDGER_REL;
+            const at = f.line > 0 ? `${file}:${f.line}` : file;
             process.stderr.write(`❌  ${at}: [${f.rule}] ${f.message}\n`);
         }
         process.stderr.write(
@@ -484,7 +610,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         // that does not distinguish "nothing to check" from "everything checked"
         // is the failure mode this repo has already paid for once.
         process.stdout.write(
-            `✅  lint_harvest_provenance: ${records.length} ledger row(s) OK · ` +
+            `✅  lint_harvest_provenance: ${records.length} ledger row(s) OK · ${mechanisms.length} mechanism row(s) OK · ` +
             `${citations.length} citation(s) resolved across ${CITATION_SCAN_ROOTS.length} scanned root(s)` +
             `${records.length === 0 && citations.length === 0 ? ' — ledger is empty and nothing cites it, which is a legitimate pass' : ''}\n`,
         );
@@ -514,4 +640,4 @@ if (_isCliEntry()) {
     }
 }
 
-export { REPO, LEDGER_REL, ExitCode };
+export { REPO, LEDGER_REL, MECHANISMS_REL, ExitCode };