@event4u/agent-config 14.19.0 → 14.20.0

package/dist/cli/mcp/telemetry.js

@@ -0,0 +1,227 @@
+/**
+ * Call telemetry for the stdio-lite MCP server (roadmap step 4.1).
+ *
+ * WHY THIS EXISTS. Before it, `grep -rn 'telemetry|collector|record'
+ * src/cli/mcp/*.ts` was empty: the two lite tools were invisible, so every
+ * statement about whether the lite surface is used at all was an assumption.
+ * One row per `tools/call` turns that into a reading — including a zero, which
+ * is a result.
+ *
+ * THREE CONSTRAINTS THE ROADMAP SET, AND HOW EACH IS MET.
+ *
+ * - **No second sink.** Rows go to the sink that already collects MCP
+ *   `tools/call` records, `agents/runtime/mcp-telemetry/calls.jsonl`, through
+ *   the same `record_call` the kernel server uses. Nothing new is created.
+ * - **No new consent gate.** The switch is the EXISTING
+ *   `telemetry.artifact_engagement.enabled` key, default `false`. No key is
+ *   introduced, so a consumer who has not opted into telemetry does not
+ *   acquire a new thing to opt out of.
+ * - **One row per call, none when off.** `recordLiteCall` is the only writer
+ *   and returns `null` without touching the filesystem when the gate is off.
+ *
+ * PRIVACY BY CONSTRUCTION. Two fields are caller-influenced and both are
+ * clamped at the boundary. `host` is resolved against a CLOSED vocabulary; an
+ * unrecognised client name becomes `other`, never the string the client sent.
+ * `tool_name` is caller-supplied on the wire — a client may call
+ * `tools/call` with ANY name — so a name outside a conservative identifier
+ * shape is recorded as `other_tool` rather than stored verbatim. Without that
+ * clamp the sink would accept a path or a secret as a tool name and this
+ * report would print it. The record therefore has no field capable of carrying
+ * free-form text, and there is no scrubbing pass that could fail because there
+ * is nothing to scrub. The client-install hash comes from the kernel collector
+ * unchanged.
+ *
+ * NEVER THROWS. Telemetry must not break the wire surface; every path here
+ * either records or returns `null`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { record_call } from '../../scripts/mcp_server/telemetry.js';
+/** Transport label for this surface — distinguishes it from the kernel server. */
+export const LITE_TRANSPORT = 'stdio-lite';
+/** The settings key that gates every row. Deliberately an EXISTING key. */
+export const LITE_TELEMETRY_SETTING = 'telemetry.artifact_engagement.enabled';
+/**
+ * The closed host vocabulary.
+ *
+ * Membership is what makes the field non-identifying: a value is either one of
+ * these literals, `other`, or `unknown`. It is matched against the MCP
+ * `clientInfo.name` a client sends at `initialize`, lower-cased, with `_` and
+ * spaces folded to `-`; a name that merely CONTAINS one of these is resolved to
+ * it, because clients ship names like `claude-code-cli` and `Cursor (0.42)`.
+ */
+export const KNOWN_HOSTS = [
+    'claude-code',
+    'claude-desktop',
+    'cursor',
+    'windsurf',
+    'cline',
+    'gemini-cli',
+    'copilot',
+    'augment',
+    'aider',
+    'codex',
+    'roocode',
+    'continue',
+    'kilocode',
+    'zed',
+    'jetbrains',
+    'kiro',
+    'opencode',
+    'trae',
+    'warp',
+];
+/** No `initialize` seen yet, or it carried no client name. */
+export const HOST_UNKNOWN = 'unknown';
+/** A client name that is not in the closed vocabulary. Never the raw string. */
+export const HOST_OTHER = 'other';
+/**
+ * Resolve a client-supplied name onto the closed vocabulary.
+ *
+ * Longest match first, so `claude-desktop` is not swallowed by a shorter
+ * sibling and `claude-code` wins over a bare `claude` substring.
+ */
+export function normalizeHost(clientName) {
+    if (typeof clientName !== 'string')
+        return HOST_UNKNOWN;
+    const folded = clientName.trim().toLowerCase().replace(/[_\s]+/g, '-');
+    if (folded === '')
+        return HOST_UNKNOWN;
+    const byLength = [...KNOWN_HOSTS].sort((a, b) => b.length - a.length);
+    for (const known of byLength) {
+        if (folded === known || folded.includes(known))
+            return known;
+    }
+    return HOST_OTHER;
+}
+/**
+ * The shape a tool name must have to be stored verbatim.
+ *
+ * Conservative on purpose: MCP tool names are identifiers, so anything with a
+ * separator, whitespace, or unusual length is not a tool name that this surface
+ * could ever serve — it is caller-supplied text, and text is what must not
+ * reach the store.
+ */
+const TOOL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
+/** A caller-supplied name that is not identifier-shaped. Never the raw string. */
+export const TOOL_OTHER = 'other_tool';
+/**
+ * Clamp a wire tool name onto a storable one.
+ *
+ * A name this surface actually serves always passes; an unknown but
+ * identifier-shaped name passes too, because that is the latent-demand signal
+ * the store exists to carry. Everything else becomes `other_tool`.
+ */
+export function normalizeToolName(name, isLiteTool) {
+    if (typeof name !== 'string' || name === '')
+        return '';
+    if (isLiteTool)
+        return name;
+    return TOOL_NAME_RE.test(name) ? name : TOOL_OTHER;
+}
+/** `str.strip()` on both ends, matching the sibling settings peeks in `src/cli`. */
+function _strip(s) {
+    return s.replace(/^[ \t\r\f\v]+/, '').replace(/[ \t\r\f\v]+$/, '');
+}
+/**
+ * Read `telemetry.artifact_engagement.enabled` from a project settings file.
+ *
+ * A deliberately small nested-key peek over the YAML subset this package's own
+ * settings files are written in — the same shape `workspace_crypto.isEnabled`
+ * and `workspace_analytics` already use in `src/cli`, and for the same reason:
+ * the lite server must stay pure-Node with no YAML dependency.
+ *
+ * Every failure resolves to `false`. Missing file, unreadable file, missing
+ * section, missing key and an unparseable value are all indistinguishable and
+ * all mean OFF — the default-off doctrine the engagement collector states for
+ * itself.
+ */
+export function liteTelemetryEnabled(settingsPath) {
+    const p = settingsPath ?? path.join(process.cwd(), '.agent-settings.yml');
+    let text;
+    try {
+        text = fs.readFileSync(p, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    // Track the two nesting levels the key needs: `telemetry:` at column 0,
+    // then `artifact_engagement:` beneath it, then `enabled:` beneath that.
+    let inTelemetry = false;
+    let inSection = false;
+    let sectionIndent = -1;
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.replace(/[ \t\r\f\v]+$/, '');
+        if (line === '' || _strip(line).startsWith('#'))
+            continue;
+        const indent = line.length - line.replace(/^ +/, '').length;
+        const body = _strip(line);
+        if (indent === 0) {
+            inTelemetry = body === 'telemetry:';
+            inSection = false;
+            sectionIndent = -1;
+            continue;
+        }
+        if (!inTelemetry)
+            continue;
+        if (!inSection) {
+            if (body === 'artifact_engagement:') {
+                inSection = true;
+                sectionIndent = indent;
+            }
+            continue;
+        }
+        // Left the section — a sibling key at or above its indent closes it.
+        if (indent <= sectionIndent) {
+            inSection = body === 'artifact_engagement:';
+            if (inSection)
+                sectionIndent = indent;
+            continue;
+        }
+        if (body.startsWith('enabled:')) {
+            const value = _strip(body.slice('enabled:'.length)).toLowerCase();
+            return value === 'true' || value === 'yes' || value === 'on';
+        }
+    }
+    return false;
+}
+/**
+ * Classify one lite `tools/call`.
+ *
+ * `implemented` — a lite tool ran. `stub` — the name is not on this surface, so
+ * the `not_implemented` envelope was returned, which is exactly the condition
+ * the kernel collector defines that outcome for. The lite server cannot
+ * distinguish "in the kernel catalogue but absent here" from "in no catalogue
+ * at all", so it never claims `latent_demand`: the kernel server owns that
+ * distinction, and guessing it here would put an unearned claim in the store.
+ */
+export function classifyLiteOutcome(isLiteTool) {
+    return isLiteTool ? 'implemented' : 'stub';
+}
+/**
+ * Append exactly one row for one `tools/call`, or nothing.
+ *
+ * Returns the record written, or `null` when the gate is off or the write
+ * failed. Never throws.
+ */
+export function recordLiteCall(options) {
+    const { toolName, isLiteTool, host, consumerRoot, settingsPath } = options;
+    const stored = normalizeToolName(toolName, isLiteTool);
+    if (stored === '')
+        return null;
+    try {
+        if (!liteTelemetryEnabled(settingsPath))
+            return null;
+        return record_call({
+            tool_name: stored,
+            outcome: classifyLiteOutcome(isLiteTool),
+            transport: LITE_TRANSPORT,
+            consumer_root: consumerRoot,
+            host,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/cli-delegate/{chunk-GZTMRYCN.js → chunk-C6IPZRDA.js}

@@ -21,6 +21,8 @@ import {
   is_ancestor,
   load_inventory,
   manifest_path,
+  printResiduals,
+  probeHostCapabilities,
   read_manifest,
   reap_stale,
   reap_tagged_orphans,
@@ -28,7 +30,7 @@ import {
   save_inventory,
   upsert_tool,
   write_manifest
-} from "./chunk-PMEKGDED.js";
+} from "./chunk-PI2GU3DP.js";
 import {
   check_version,
   classify_mismatch,
@@ -398,16 +400,82 @@ function is_claude_builtin_name(slug) {
 import * as fs from "node:fs";
 import * as path from "node:path";
 var MCP_SERVER_KEY = "agent-config";
-var MCP_BRIDGE_ENTRY = {
-  mcpServers: {
-    [MCP_SERVER_KEY]: {
-      command: "npx",
-      args: ["-y", "@event4u/agent-config", "mcp-server"]
+var MCP_PACKAGE_NAME = "@event4u/agent-config";
+function mcpBridgeEntry(packageRoot) {
+  const version = readPackageVersion(packageRoot);
+  const spec = version === null ? MCP_PACKAGE_NAME : `${MCP_PACKAGE_NAME}@${version}`;
+  return {
+    mcpServers: {
+      [MCP_SERVER_KEY]: {
+        command: "npx",
+        args: ["-y", spec, "mcp-server"]
+      }
     }
+  };
+}
+function readPackageVersion(packageRoot) {
+  try {
+    const raw = fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8");
+    const v = JSON.parse(raw).version;
+    return typeof v === "string" && v.trim() !== "" ? v : null;
+  } catch {
+    return null;
   }
-};
+}
 function makeEnsureMcpBridge(mergeJsonFile) {
-  return (projectRoot, force) => mergeJsonFile(path.join(projectRoot, ".mcp.json"), MCP_BRIDGE_ENTRY, force, ".mcp.json");
+  return (projectRoot, force, packageRoot = projectRoot) => mergeJsonFile(
+    path.join(projectRoot, ".mcp.json"),
+    mcpBridgeEntry(packageRoot),
+    force,
+    ".mcp.json"
+  );
+}
+var MCP_PROJECT_CONFIG = {
+  "claude-code": { hostId: "claude", relPath: ".mcp.json" },
+  cursor: { hostId: "cursor", relPath: ".cursor/mcp.json" },
+  "gemini-cli": { hostId: "gemini", relPath: ".gemini/settings.json" }
+};
+function mcpRegistrationTargets(tools, readsConfig) {
+  const out = [];
+  for (const [toolId, spec] of Object.entries(MCP_PROJECT_CONFIG)) {
+    if (toolId === "claude-code") continue;
+    if (!tools.has(toolId)) continue;
+    if (!readsConfig(spec.hostId)) continue;
+    out.push({ toolId, hostId: spec.hostId, relPath: spec.relPath });
+  }
+  return out;
+}
+function makeEnsureMcpRegistrations(mergeJsonFile) {
+  return (projectRoot, force, packageRoot, targets) => {
+    const merged = {};
+    for (const t of targets) {
+      merged[t.toolId] = mergeJsonFile(
+        path.join(projectRoot, ...t.relPath.split("/")),
+        mcpBridgeEntry(packageRoot),
+        force,
+        t.relPath
+      );
+    }
+    return merged;
+  };
+}
+function readsProjectMcpConfig(hostId) {
+  return probeHostCapabilities(hostId).reads_project_mcp_config;
+}
+function registerMcpHosts(mergeJsonFile, projectRoot, force, packageRoot, tools, into, readsConfig = readsProjectMcpConfig) {
+  const ensure = makeEnsureMcpRegistrations(mergeJsonFile);
+  const claude = MCP_PROJECT_CONFIG["claude-code"];
+  if (tools.has("claude-code") && claude !== void 0) {
+    const merged = ensure(projectRoot, force, packageRoot, [
+      { toolId: "claude-code", hostId: claude.hostId, relPath: claude.relPath }
+    ]);
+    (into["claude-code"] ??= []).push(...merged["claude-code"] ?? []);
+  }
+  for (const [toolId, keys] of Object.entries(
+    ensure(projectRoot, force, packageRoot, mcpRegistrationTargets(tools, readsConfig))
+  )) {
+    (into[toolId] ??= []).push(...keys);
+  }
 }
 function projectionModeOf(raw) {
   return raw === "scoped" ? "scoped" : raw === "tiered" ? "tiered" : "legacy-all";
@@ -6804,11 +6872,9 @@ function _main_project_install(opts, project_root, parsed_tools, is_first_run) {
       ...ensure_augment_bridge(project_root, opts.force)
     ];
     if (_is_tool_enabled(tools, "claude-code")) {
-      merged_keys_by_tool["claude-code"] = [
-        ...ensure_claude_bridge(project_root, opts.force),
-        ...ensure_mcp_bridge(project_root, opts.force)
-      ];
+      merged_keys_by_tool["claude-code"] = ensure_claude_bridge(project_root, opts.force);
     }
+    registerMcpHosts(merge_json_file, project_root, opts.force, package_root, tools, merged_keys_by_tool);
     if (_is_tool_enabled(tools, "cursor")) {
       merged_keys_by_tool["cursor"] = ensure_cursor_bridge(project_root, opts.force);
     }
@@ -6902,6 +6968,7 @@ function _main_project_install(opts, project_root, parsed_tools, is_first_run) {
       );
       process2.stdout.write("\n");
     }
+    printResiduals(tools, state.QUIET);
     if (_is_tool_enabled(tools, "claude-code")) {
       const team_hint = _team_setup_hint_line(project_root);
       if (team_hint !== null) {

package/dist/cli-delegate/{chunk-CYH5SP6M.js → chunk-I6RHFQEG.js}

@@ -25,6 +25,7 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath as fileURLToPath2, pathToFileURL } from "node:url";
 
 // src/scripts/_lib/security_lint.ts
+import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -41,7 +42,7 @@ var DEFAULT_SCAN_ROOTS = [
   "dist/agent-src"
 ];
 var _EXAMPLE_PATH = /(^|\/)(docs|evals|tests?|fixtures?)(\/|$)|example|template|sample|\/_template/i;
-var _PRAGMA = /<!--\s*security-lint:\s*allow\s+([A-Za-z0-9_-]+)\s+"([^"]+)"\s*-->/g;
+var _PRAGMA = /<!--\s*security-lint:\s*allow\s+([A-Za-z0-9_-]+)\s+"([^"]+)"((?:\s+sha256:[0-9a-f]{64})*)\s*-->/g;
 var _FENCE = /^(\s*)(`{3,}|~{3,})\s*([A-Za-z0-9_-]*)\s*$/;
 var SEVERITY_RANK = { LOW: 1, MED: 2, HIGH: 3 };
 var Finding = class {
@@ -87,6 +88,10 @@ function is_example_path(rel_path) {
 function path_weight(rel_path) {
   return is_example_path(rel_path) ? 0.25 : 1;
 }
+var PROJECTION_PREFIX = "dist/agent-src/";
+function source_identity(rel) {
+  return rel.startsWith(PROJECTION_PREFIX) ? `src/${rel.slice(PROJECTION_PREFIX.length)}` : rel;
+}
 var ScannedFile = class {
   path;
   // absolute or as-given path
@@ -97,8 +102,10 @@ var ScannedFile = class {
   in_any_fence;
   pragmas;
   // check id → reason
+  /** check id → the sha256 fingerprints that pragma accepts. Empty = unbound. */
+  pragma_hashes;
   weight;
-  constructor(pathArg, rel, lines, in_example_fence, in_any_fence, pragmas, weight) {
+  constructor(pathArg, rel, lines, in_example_fence, in_any_fence, pragmas, weight, pragma_hashes = {}) {
     this.path = pathArg;
     this.rel = rel;
     this.lines = lines;
@@ -106,10 +113,74 @@ var ScannedFile = class {
     this.in_any_fence = in_any_fence;
     this.pragmas = pragmas;
     this.weight = weight;
+    this.pragma_hashes = pragma_hashes;
   }
   pragma_allows(check) {
     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) {
+    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) {
+    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}
+${source_identity(this.rel)}
+${normalized}`, "utf-8").digest("hex");
+  }
+  /** Drop the findings this file's BOUND pragma for `check` accepts. */
+  filter_bound_pragma(check, findings) {
+    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 = {}) {
     const skip_example_fence = opts.skip_example_fence ?? true;
@@ -200,11 +271,18 @@ function scan_file(filePath) {
     }
   }
   const pragmas = {};
+  const pragmaHashes = {};
   for (const text of lines) {
     _PRAGMA.lastIndex = 0;
     let m;
     while ((m = _PRAGMA.exec(text)) !== null) {
-      pragmas[m[1]] = m[2];
+      const check = m[1];
+      pragmas[check] = m[2];
+      const hashes = (m[3] ?? "").match(/sha256:([0-9a-f]{64})/g) ?? [];
+      pragmaHashes[check] = [
+        ...pragmaHashes[check] ?? [],
+        ...hashes.map((h) => h.slice("sha256:".length))
+      ];
       if (m.index === _PRAGMA.lastIndex) {
         _PRAGMA.lastIndex += 1;
       }
@@ -217,7 +295,29 @@ function scan_file(filePath) {
     in_example,
     in_any,
     pragmas,
-    path_weight(rel)
+    path_weight(rel),
+    pragmaHashes
+  );
+}
+function scan_path(filePath, base) {
+  const sf = scan_file(filePath);
+  let rel;
+  const baseResolved = path.resolve(base);
+  const fileResolved = path.resolve(filePath);
+  if (fileResolved === baseResolved || fileResolved.startsWith(baseResolved + path.sep)) {
+    rel = path.relative(baseResolved, fileResolved).split(path.sep).join("/");
+  } else {
+    rel = path.basename(filePath);
+  }
+  return new ScannedFile(
+    sf.path,
+    rel,
+    sf.lines,
+    sf.in_example_fence,
+    sf.in_any_fence,
+    sf.pragmas,
+    path_weight(rel),
+    sf.pragma_hashes
   );
 }
 function _rglobSorted(base) {
@@ -253,9 +353,9 @@ function _pathCmp(a, b) {
   if (pa.length > pb.length) return 1;
   return 0;
 }
-function* iter_corpus(roots = DEFAULT_SCAN_ROOTS, exts = [".md"]) {
+function* iter_corpus(roots = DEFAULT_SCAN_ROOTS, exts = [".md"], scanBase = ROOT) {
   for (const root of roots) {
-    const base = path.join(ROOT, root);
+    const base = path.join(scanBase, root);
     if (!fs.existsSync(base)) {
       continue;
     }
@@ -267,11 +367,27 @@ function* iter_corpus(roots = DEFAULT_SCAN_ROOTS, exts = [".md"]) {
         continue;
       }
       if (st.isFile() && exts.includes(path.extname(p))) {
-        yield scan_file(p);
+        yield scan_path(p, scanBase);
       }
     }
   }
 }
+var LEGACY_PRAGMA_CHECK = "legacy-pragma";
+function legacy_pragma_finding(sf, check) {
+  return new Finding(
+    sf.rel,
+    0,
+    LEGACY_PRAGMA_CHECK,
+    "LOW",
+    `unbound \`security-lint: allow ${check}\` pragma suppresses this whole file \u2014 it accepts whatever the matched text is later changed to say. Bind it with \`sha256:<hex>\` per accepted match.`,
+    sf.weight
+  );
+}
+var CHILD_SCANNED_PREFIX = "scanned: ";
+function report_child_scanned(count) {
+  process.stderr.write(`${CHILD_SCANNED_PREFIX}${String(count)}
+`);
+}
 function report(findings, opts) {
   const check_label = opts.check_label;
   if (findings.length === 0) {
@@ -647,9 +763,11 @@ function _cpName(cp) {
   return n !== void 0 ? n : "<unnamed>";
 }
 function _scan(sf) {
-  if (sf.pragma_allows(CHECK)) {
-    return [];
+  const pragmaForm = sf.pragma_form(CHECK);
+  if (pragmaForm === "legacy") {
+    return [legacy_pragma_finding(sf, CHECK)];
   }
+  const finish = (hits) => pragmaForm === "bound" ? sf.filter_bound_pragma(CHECK, hits) : hits;
   const out = [];
   for (const [lineno, text] of sf.iter_lines({ skip_example_fence: true })) {
     let vs_run = 0;
@@ -687,7 +805,7 @@ function _scan(sf) {
       );
     }
   }
-  return out;
+  return finish(out);
 }
 var _BINARY_EXT = /* @__PURE__ */ new Set([
   "png",
@@ -848,7 +966,7 @@ function _sanitize(filePath) {
   return out;
 }
 function _argError(msg) {
-  process.stderr.write("usage: lint_hidden_unicode [-h] [--json] [--fix]\n");
+  process.stderr.write("usage: lint_hidden_unicode [-h] [--json] [--fix] [--root DIR]\n");
   process.stderr.write(`lint_hidden_unicode: error: ${msg}
 `);
   process.exit(2);
@@ -856,14 +974,27 @@ function _argError(msg) {
 function parse_args(argv) {
   const out = { json: false, fix: false };
   const extra = [];
+  let rootPending = false;
   for (const a of argv) {
+    if (rootPending) {
+      out.root = a;
+      rootPending = false;
+      continue;
+    }
     if (a === "-h" || a === "--help") {
-      process.stdout.write("usage: lint_hidden_unicode [-h] [--json] [--fix]\n");
+      process.stdout.write("usage: lint_hidden_unicode [-h] [--json] [--fix] [--root DIR]\n");
       process.exit(0);
     } else if (a === "--json") {
       out.json = true;
     } else if (a === "--fix") {
       out.fix = true;
+    } else if (a === "--root" || a.startsWith("--root=")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) {
+        out.root = a.slice(eq + 1);
+      } else {
+        rootPending = true;
+      }
     } else {
       extra.push(a);
     }
@@ -875,10 +1006,11 @@ function parse_args(argv) {
 }
 function main(argv = null) {
   const args = parse_args(argv ?? process.argv.slice(2));
+  const scanBase = args.root === void 0 ? ROOT : path2.resolve(args.root);
   const findings = [];
   const flagged = /* @__PURE__ */ new Set();
   let corpusFiles = 0;
-  for (const sf of iter_corpus()) {
+  for (const sf of iter_corpus(DEFAULT_SCAN_ROOTS, [".md"], scanBase)) {
     corpusFiles += 1;
     const hits = _scan(sf);
     for (const h of hits) {
@@ -903,7 +1035,7 @@ function main(argv = null) {
     }
     throw exc;
   }
-  const sourceFiles = _eligibleSourceFiles();
+  const sourceFiles = args.root === void 0 ? _eligibleSourceFiles() : [];
   for (const h of _scanSourceControlBytes(sourceFiles)) {
     findings.push(h);
   }
@@ -922,6 +1054,9 @@ function main(argv = null) {
 `);
     }
   }
+  if (args.json) {
+    report_child_scanned(corpusFiles + (sourceFiles === null ? 0 : sourceFiles.length));
+  }
   if (args.json) {
     const payload = py_json_dumps_indent2(findings.map((f) => f.toDict()));
     process.stdout.write(payload + "\n");
@@ -2298,7 +2433,7 @@ function queryIndex(indexPath, keys, types) {
 }
 
 // src/scripts/learning_sidecar.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import * as fs6 from "node:fs";
 import * as path6 from "node:path";
 import process4 from "node:process";
@@ -2314,7 +2449,7 @@ function _parseTsMs(ts) {
   return Number.isNaN(t) ? null : t;
 }
 function _bodyHash(body) {
-  return createHash("sha256").update(body.trim().toLowerCase()).digest("hex").slice(0, 12);
+  return createHash2("sha256").update(body.trim().toLowerCase()).digest("hex").slice(0, 12);
 }
 function _globSignalFiles(dir) {
   let names;