@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/lint_framework_leakage.ts

@@ -148,19 +148,19 @@ const CROSS_STACK_HINTS: Record<string, string[]> = {
     ruby: ['\\bRails\\b', '\\bbin/rails\\b', '\\bGemfile\\b', '\\bbundle exec\\b'],
     python: ['\\bDjango\\b', '\\bFastAPI\\b', '\\bFlask\\b', '\\bpoetry\\b',
         '\\buv (add|sync|run|pip)\\b', '\\bvenv\\b', '\\bPydantic\\b', '\\bJinja\\b',
-        'docs\\.python\\.org'],
+        'docs\\.python\\.org', '\\bPython\\b'],
     node: ['\\bExpress\\b', '\\bNext\\.?js\\b', '\\bNode\\.?js\\b', '\\bnpx\\b',
         '\\bvitest\\b', '\\bjest\\b', '\\beslint\\b', '\\bprettier\\b',
         '\\bReact\\b', '\\bVue\\b', '\\bNestJS\\b', '\\bTypeScript\\b',
         '\\btsc\\b', '\\bzod\\b', '\\bPrisma\\b', '\\bTailwind\\b',
         '\\bTurborepo\\b', '\\bclass-validator\\b', '\\bInertia\\b',
         '\\bJSX\\b', '\\bNx\\b',
-        '\\.tsx?\\b', 'typescriptlang\\.org'],
+        '\\.tsx?\\b', 'typescriptlang\\.org', '\\bTS\\b', '\\bJS\\b'],
     go: ['\\bgo (test|build|run|mod)\\b', '\\bgolangci-lint\\b', '\\bGoLand\\b',
         '\\bGolang\\b', '\\bgo\\.dev\\b'],
     rust: ['\\bcargo (test|build|run|check|fmt|clippy|add|update)\\b',
         '\\bClippy\\b', '\\brustfmt\\b', '\\bCargo\\.toml\\b',
-        'rust-lang\\.org'],
+        'rust-lang\\.org', '\\bRust\\b'],
     dotnet: ['\\bdotnet (test|build|run|add|restore)\\b', '\\b\\.NET\\b'],
     java: ['\\bSpring\\b', '\\bmvn (test|clean|install|package)\\b',
         '\\bgradle\\b', '\\bMaven\\b'],
@@ -168,6 +168,20 @@ const CROSS_STACK_HINTS: Record<string, string[]> = {
     // are hit patterns; these are window-only hints so a JS/Python hit next
     // to plain-language PHP mentions self-suppresses as cross-stack docs.
     php: ['\\bvendor/', '\\bPHP\\b'],
+    // Bare LANGUAGE names (Python / Rust / TS / JS above) are the same class of
+    // window-only hint the `php` family already had, and their absence was an
+    // asymmetry, not a policy: a checklist row naming "PHP typed properties +
+    // declare(strict_types=1), TS strict, Python type hints, Go / Rust" — five
+    // ecosystems on ONE line, the rule's textbook "multi-stack peers" case —
+    // matched the PHP hit pattern and found no cross-stack hint, because only
+    // PHP had a plain-language entry. So the linter flagged the exact shape
+    // framework-neutrality documents as allowed.
+    //
+    // `\bGo\b` is deliberately NOT added. These hints SUPPRESS, so an
+    // over-broad one hides real leakage — and "go to" / "go ahead" would fire
+    // constantly in prose. Golang / `go test|build|run|mod` / go.dev stay the
+    // Go signals; a Go-only line with none of those is not self-evidently
+    // cross-stack anyway.
     // Polyglot-runner pseudo-family: a Taskfile/Makefile mention marks the
     // window as multi-stack tooling documentation (runner files are
     // ecosystem-neutral by definition).

package/src/scripts/lint_framework_leakage_allowlist.json

@@ -116,6 +116,38 @@
         185
       ],
       "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "lines": [
+        228,
+        231,
+        239,
+        243
+      ],
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/image-editing/SKILL.md",
+      "lines": [
+        48
+      ],
+      "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
+    },
+    {
+      "file": "src/skills/image-generation/SKILL.md",
+      "lines": [
+        45
+      ],
+      "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
+    },
+    {
+      "file": "src/skills/prompt-engineering-image/SKILL.md",
+      "lines": [
+        74,
+        115
+      ],
+      "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     }
   ]
 }

package/src/scripts/lint_governed_writes.ts

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+/**
+ * lint_governed_writes — flag direct filesystem writes to protected
+ * ledger/governance surfaces that bypass the sanctioned write path.
+ *
+ * Scans: src/scripts/**\/*.ts (excluding *.test.ts and the atomic-write
+ * primitive itself, _lib/fs_atomic.ts, which is the sanctioned layer this
+ * lint measures bypasses of).
+ *
+ * Protected surfaces (each carries its own write policy):
+ *   - docs/CLAIMS.md (claims ledger) — `always-forbidden`: ANY direct
+ *     fs write/append call referencing this path is a violation; the
+ *     ledger is only ever mutated via `write_atomic` from
+ *     `src/scripts/_lib/fs_atomic.ts` (which this lint does not scan, and
+ *     whose call name — `write_atomic` — never matches the banned-call
+ *     patterns below, so a compliant writer is naturally clean).
+ *   - agents/memory/intake/ (append-only signal JSONL) — `append-only`:
+ *     an APPEND call (appendFileSync / fs.promises.appendFile /
+ *     createWriteStream with an `'a'` flag) is the sanctioned operation;
+ *     only a REWRITE call is a violation.
+ *   - agents/runtime/state/audit/ (append-only audit-log-v1 JSONL) —
+ *     `append-only`, same split as above.
+ *
+ * Banned call shapes (rewrite family): fs.writeFileSync(),
+ * fs.promises.writeFile(), fs.createWriteStream() without an append flag —
+ * each also matched via a bare destructured import (writeFileSync(...)).
+ * Banned call shapes (append family, sanctioned on append-only surfaces,
+ * always a violation on always-forbidden surfaces): fs.appendFileSync(),
+ * fs.promises.appendFile(), fs.createWriteStream() with `{ flags: 'a' }`.
+ *
+ * A call only counts against a surface when the surface's path fragment
+ * appears as a string/template literal INSIDE that call's own argument
+ * list (matched by balanced-paren scanning, so multi-line call arguments
+ * are captured) — a path built up through an unrelated variable (no
+ * literal in the call's own arguments) is not flagged; that is a known,
+ * deliberate scope limit of a static, zero-runtime-cost lint.
+ *
+ * Inline-ignore: add a comment on the same or previous line:
+ *   lint-governed-writes-disable-next-line [-- reason]
+ *   lint-governed-writes-disable-line [-- reason]
+ *   lint-governed-writes-disable-file [-- reason]  (top of file)
+ *
+ * Exit codes: 0 = clean, 2 = findings present, 1 = internal error.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(_HERE, "..", "..");
+export const SCRIPTS_DIR = path.join(REPO_ROOT, "src", "scripts");
+
+// ---------------------------------------------------------------------------
+// Protected surfaces
+// ---------------------------------------------------------------------------
+type SurfacePolicy = "always-forbidden" | "append-only";
+
+interface ProtectedSurface {
+  id: string;
+  fragment: string;
+  policy: SurfacePolicy;
+}
+
+// No canonical bench-report index file was found under src/scripts at
+// authoring time (no writer builds a single "bench index" registry path) —
+// see the lint's own docstring history / task report. If one is added
+// later, append it here with the matching policy.
+const PROTECTED_SURFACES: ProtectedSurface[] = [
+  { id: "claims-ledger", fragment: "docs/CLAIMS.md", policy: "always-forbidden" },
+  { id: "memory-intake", fragment: "agents/memory/intake/", policy: "append-only" },
+  { id: "audit-log", fragment: "agents/runtime/state/audit/", policy: "append-only" },
+];
+
+// ---------------------------------------------------------------------------
+// Banned call-shape patterns
+// ---------------------------------------------------------------------------
+type CallFamily = "rewrite" | "append" | "stream";
+
+interface CallPattern {
+  name: string;
+  family: CallFamily;
+  source: string; // regex source, compiled fresh per exec loop (stateful lastIndex)
+}
+
+const CALL_PATTERNS: CallPattern[] = [
+  { name: "fs.writeFileSync", family: "rewrite", source: "\\b(?:fs\\.)?writeFileSync\\s*\\(" },
+  { name: "fs.promises.writeFile", family: "rewrite", source: "\\bfs\\.promises\\.writeFile\\s*\\(" },
+  { name: "fs.appendFileSync", family: "append", source: "\\b(?:fs\\.)?appendFileSync\\s*\\(" },
+  { name: "fs.promises.appendFile", family: "append", source: "\\bfs\\.promises\\.appendFile\\s*\\(" },
+  { name: "fs.createWriteStream", family: "stream", source: "\\b(?:fs\\.)?createWriteStream\\s*\\(" },
+];
+
+const APPEND_FLAG_RE = /flags\s*:\s*['"]a['"]/;
+
+interface Finding {
+  file: string;
+  line: number;
+  surface: string;
+  call: string;
+  policy: SurfacePolicy;
+  snippet: string;
+}
+
+// ---------------------------------------------------------------------------
+// Balanced-paren call-argument extraction
+// ---------------------------------------------------------------------------
+/**
+ * Given the index of the opening `(` of a call, return the substring from
+ * that `(` through its matching `)` (inclusive) — the call's full argument
+ * list, spanning multiple lines when the call is formatted that way.
+ * String/template literals are tracked so a stray paren inside a quoted
+ * value never desyncs the depth count.
+ */
+function extractCallArgsRegion(content: string, openParenIdx: number): string {
+  let depth = 0;
+  let inString: string | null = null;
+  let escaped = false;
+  for (let i = openParenIdx; i < content.length; i++) {
+    const ch = content[i] as string;
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === inString) {
+        inString = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      inString = ch;
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+    } else if (ch === ")") {
+      depth--;
+      if (depth === 0) {
+        return content.slice(openParenIdx, i + 1);
+      }
+    }
+  }
+  return content.slice(openParenIdx);
+}
+
+function lineOfIndex(content: string, idx: number): number {
+  let line = 1;
+  for (let i = 0; i < idx; i++) {
+    if (content[i] === "\n") line++;
+  }
+  return line;
+}
+
+// ---------------------------------------------------------------------------
+// Inline-ignore parsing (mirrors lint_output_slop's convention)
+// ---------------------------------------------------------------------------
+type IgnoreScope = "file" | "line" | "next-line";
+interface Ignore {
+  scope: IgnoreScope;
+  lineNum?: number;
+}
+
+function parseIgnores(lines: string[]): Ignore[] {
+  const ignores: Ignore[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (/lint-governed-writes-disable-file/i.test(line)) {
+      ignores.push({ scope: "file" });
+    }
+    if (/lint-governed-writes-disable-line/i.test(line)) {
+      ignores.push({ scope: "line", lineNum: i + 1 });
+    }
+    if (/lint-governed-writes-disable-next-line/i.test(line)) {
+      ignores.push({ scope: "next-line", lineNum: i + 2 });
+    }
+  }
+  return ignores;
+}
+
+function isIgnored(ignores: Ignore[], lineNum: number): boolean {
+  for (const ig of ignores) {
+    if (ig.scope === "file") return true;
+    if (ig.scope === "line" && ig.lineNum === lineNum) return true;
+    if (ig.scope === "next-line" && ig.lineNum === lineNum) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Per-file scanning
+// ---------------------------------------------------------------------------
+export function scanContent(content: string, relFile: string): Finding[] {
+  const findings: Finding[] = [];
+  const lines = content.split("\n");
+  const ignores = parseIgnores(lines);
+
+  for (const pat of CALL_PATTERNS) {
+    const re = new RegExp(pat.source, "g");
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(content)) !== null) {
+      const openParenIdx = m.index + m[0].length - 1;
+      const region = extractCallArgsRegion(content, openParenIdx);
+
+      let kind: "rewrite" | "append";
+      if (pat.family === "stream") {
+        kind = APPEND_FLAG_RE.test(region) ? "append" : "rewrite";
+      } else {
+        kind = pat.family;
+      }
+
+      const lineNum = lineOfIndex(content, m.index);
+      if (isIgnored(ignores, lineNum)) continue;
+
+      for (const surface of PROTECTED_SURFACES) {
+        if (!region.includes(surface.fragment)) continue;
+        const isViolation =
+          surface.policy === "always-forbidden" ||
+          (surface.policy === "append-only" && kind === "rewrite");
+        if (!isViolation) continue;
+
+        findings.push({
+          file: relFile,
+          line: lineNum,
+          surface: surface.id,
+          call: pat.name,
+          policy: surface.policy,
+          snippet: (lines[lineNum - 1] ?? "").trim().slice(0, 160),
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// File discovery
+// ---------------------------------------------------------------------------
+const EXCLUDED_RELATIVE_FILES = new Set<string>(["_lib/fs_atomic.ts"]);
+
+function* walkTsFiles(dir: string, root: string): Generator<string> {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name === "dist") continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkTsFiles(full, root);
+      continue;
+    }
+    if (!entry.name.endsWith(".ts")) continue;
+    if (entry.name.endsWith(".test.ts")) continue;
+    const rel = path.relative(root, full).split(path.sep).join("/");
+    if (EXCLUDED_RELATIVE_FILES.has(rel)) continue;
+    yield full;
+  }
+}
+
+/** Scan every eligible `.ts` file under `scriptsDir`. */
+export function scanScriptsDir(scriptsDir: string): Finding[] {
+  const findings: Finding[] = [];
+  for (const file of walkTsFiles(scriptsDir, scriptsDir)) {
+    let content: string;
+    try {
+      content = fs.readFileSync(file, "utf-8");
+    } catch {
+      continue;
+    }
+    const rel = path.relative(scriptsDir, file).split(path.sep).join("/");
+    findings.push(...scanContent(content, rel));
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    process.stdout.write(
+      "usage: lint_governed_writes [--json] [--quiet]\n" +
+        "  Flags direct fs write/append calls to protected ledger/governance\n" +
+        "  surfaces (docs/CLAIMS.md, agents/memory/intake/, agents/runtime/state/audit/)\n" +
+        "  that bypass the sanctioned atomic-write layer or the append-only contract.\n" +
+        "  Exit 2 on any finding, 0 clean.\n",
+    );
+    return 0;
+  }
+
+  const jsonMode = argv.includes("--json");
+  const quiet = argv.includes("--quiet");
+
+  const findings = scanScriptsDir(SCRIPTS_DIR);
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify(findings, null, 2) + "\n");
+    return findings.length > 0 ? 2 : 0;
+  }
+
+  if (findings.length === 0) {
+    if (!quiet) {
+      process.stdout.write(
+        "✅  lint_governed_writes: clean — no direct writes to protected surfaces found.\n",
+      );
+    }
+    return 0;
+  }
+
+  for (const f of findings) {
+    process.stdout.write(
+      `❌  ${f.file}:${f.line} [${f.surface}/${f.policy}] ${f.call} — ${f.snippet}\n`,
+    );
+  }
+  process.stdout.write(
+    `\nlint_governed_writes: ${findings.length} finding(s). Route the write through ` +
+      "write_atomic (src/scripts/_lib/fs_atomic.ts) or the surface's sanctioned append " +
+      "call, or use lint-governed-writes-disable-next-line -- reason.\n",
+  );
+  return 2;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention — importing this
+// module for its exports, e.g. from a test, never triggers a CLI run).
+if (process.argv[1] !== undefined) {
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+    if (here === argv1) {
+      process.exit(main());
+    }
+  } catch {
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+      process.exit(main());
+    }
+  }
+}

package/src/scripts/lint_hidden_unicode.ts

@@ -30,6 +30,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import * as sl from './_lib/security_lint.js';
@@ -261,6 +262,191 @@ export function _scan(sf: sl.ScannedFile): sl.Finding[] {
     return out;
 }
 
+// ---------------------------------------------------------------------------
+// Source-file pass — raw C0 control bytes make a text file INVISIBLE to tools
+// ---------------------------------------------------------------------------
+//
+// The `.md` corpus pass above defends the model's eyes. This pass defends the
+// *reviewer's* and the *gate's* eyes, which is a different failure.
+//
+// A raw control byte (NUL above all) in a text-intended source file makes
+// `file(1)`, `grep`, and every tool that sniffs for binary content classify the
+// file as binary and SKIP IT SILENTLY. A linter grepping such a file reads
+// nothing and reports clean; an agent gathering evidence concludes the code
+// does not exist. That is indistinguishable from a pass, which is the point.
+//
+// Discovered the hard way: `road-to-runtime-encoding-hardening` was authored on
+// the premise that `memory_lookup.ts` had "zero imports" and that the sanitize
+// floor therefore ran nowhere. The file simply carried a raw NUL as a composite
+// map-key separator, so `grep` never read it. The premise was a measurement
+// artifact. See `agents/evidence/reports/nul-byte-source-census.md`.
+//
+// Precision by construction — this pass flags ONLY raw C0 controls, never the
+// invisible/confusable classes `_scan` owns. In a `.ts` file a real bidi or
+// zero-width codepoint is usually a deliberate test fixture or a regex
+// character class (this repo has several, legitimately), so flagging those here
+// would demand an allowlist that grows until the gate is worthless. A raw
+// control byte has NO legitimate use in text-intended source: the language
+// escape (`\0`, `\x01`) compiles to the identical runtime string and keeps the
+// file readable by tools. The fix is always available, so the false-positive
+// rate is structurally zero rather than merely low.
+
+/** Extensions whose content is legitimately binary — never flagged. */
+const _BINARY_EXT: ReadonlySet<string> = new Set([
+    'png', 'jpg', 'jpeg', 'gif', 'ico', 'webp', 'avif', 'bmp', 'tiff',
+    'pdf', 'woff', 'woff2', 'ttf', 'otf', 'eot',
+    'zip', 'gz', 'tgz', 'bz2', 'xz', 'zst', '7z', 'rar',
+    'wasm', 'mp3', 'mp4', 'wav', 'ogg', 'webm', 'mov', 'avi',
+    'so', 'dylib', 'dll', 'node', 'a', 'o', 'exe',
+    'jar', 'class', 'pyc', 'pyo',
+    'db', 'sqlite', 'sqlite3', 'bin', 'dat',
+    'docx', 'xlsx', 'pptx', 'doc', 'xls', 'ppt', 'odt', 'ods', 'odp',
+]);
+
+/**
+ * Generated trees — skipped, because this is an AUTHORING rule.
+ *
+ * `dist/` and the per-tool projections are outputs of `src/` (see the
+ * `source-of-truth` rule: a projection is never edited by hand). Flagging a
+ * control byte there would point the author at a file they must not touch, and
+ * `dist/install/*.mjs` is a bundler artifact whose bytes are not even
+ * hand-authorable. Fix the source; the projection follows on `task sync`.
+ */
+const _GENERATED_PREFIXES: readonly string[] = [
+    'dist/',
+    '.augment/',
+    '.claude/',
+    '.cursor/',
+    '.clinerules/',
+    // Verbatim captured tool output, not authored text. These are RECORDINGS:
+    // escaping a control byte inside one would falsify the record it exists to
+    // preserve. If a capture needs to stay grep-readable, the fix is to escape
+    // at capture time — never to edit the artifact afterwards.
+    'agents/evidence/analysis/',
+    // The frozen hostile-encoding corpus. Its positives ARE raw control
+    // characters — that is the thing under test, so flagging them would demand
+    // escaping the fixtures and thereby delete the test. The corpus has its own,
+    // stronger integrity controls: a sha256 freeze plus a scope-guard test that
+    // is itself falsified by an out-of-scope fixture. Excluded here because it
+    // is DATA, on the same principle as the captures above.
+    'internal/bench/corpora/encoding-channels/',
+];
+
+function _isGenerated(rel: string): boolean {
+    return _GENERATED_PREFIXES.some((p) => rel.startsWith(p));
+}
+
+/**
+ * True for a raw control CODEPOINT that is not benign whitespace.
+ *
+ * Codepoints, not bytes, and that distinction is the whole point. A first cut
+ * of this pass tested bytes ≤ 0x1F and let two classes through: DEL (U+007F,
+ * a single byte above the range) and the C1 controls (U+0080–009F, which encode
+ * to a two-byte UTF-8 sequence containing no byte ≤ 0x1F). Both make `file(1)`
+ * and git classify a file as binary — `tests/scripts/retrieval_sanitize.test.ts`
+ * carried U+007F and U+009F, rendered as `Bin` in `git diff`, unreviewable on a
+ * PR, and passed the byte-level check. A gate that misses the thing it exists to
+ * catch is the failure this whole roadmap is about, so the range now matches
+ * `_classify`'s: C0 + DEL + C1, minus tab / LF / CR.
+ */
+function _isRawControlCodepoint(cp: number): boolean {
+    if (cp === 0x09 || cp === 0x0a || cp === 0x0d) return false;
+    return cp <= 0x1f || (cp >= 0x7f && cp <= 0x9f);
+}
+
+function _extensionOf(rel: string): string {
+    const base = rel.slice(rel.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    return dot <= 0 ? '' : base.slice(dot + 1).toLowerCase();
+}
+
+/** Tracked files, or `null` when git is unavailable (then the pass no-ops). */
+function _trackedFiles(): string[] | null {
+    const res = spawnSync('git', ['ls-files', '-z'], {
+        cwd: sl.ROOT,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (res.status !== 0 || res.stdout === null) return null;
+    return res.stdout
+        .toString('utf-8')
+        .split('\0')
+        .filter((p) => p !== '');
+}
+
+/**
+ * Tracked files this pass is responsible for — text-intended, non-generated.
+ *
+ * Exported so a green run can state HOW MANY files it actually read. A check
+ * that reports "clean" without naming its scope is indistinguishable from a
+ * check whose scope matched nothing, which is the failure class this repo has
+ * already been bitten by.
+ */
+export function _eligibleSourceFiles(): string[] | null {
+    const tracked = _trackedFiles();
+    if (tracked === null) return null;
+    return tracked.filter((rel) => !_isGenerated(rel) && !_BINARY_EXT.has(_extensionOf(rel)));
+}
+
+/**
+ * Flag raw C0 control bytes in every tracked, text-intended file.
+ *
+ * `files` is injectable so the regression test can assert a synthetic NUL is
+ * caught — without that assertion there is no way to know this pass can still
+ * fail, which is the failure mode the whole check exists to prevent.
+ */
+export function _scanSourceControlBytes(files: readonly string[] | null = null): sl.Finding[] {
+    const tracked = files ?? _eligibleSourceFiles();
+    if (tracked === null) return [];
+    const out: sl.Finding[] = [];
+    for (const rel of tracked) {
+        // Re-applied here, not only in `_eligibleSourceFiles`: the exclusions
+        // are a property of the CHECK, so an explicit `files` list (a caller, a
+        // test) can never widen the scan past what the check is willing to
+        // claim. `_eligibleSourceFiles` exists to count, not to be the gate.
+        if (_isGenerated(rel)) continue;
+        if (_BINARY_EXT.has(_extensionOf(rel))) continue;
+        let data: Buffer;
+        try {
+            data = fs.readFileSync(path.join(sl.ROOT, rel));
+        } catch {
+            continue; // deleted, unreadable, or a submodule pointer
+        }
+        // A file that is not valid UTF-8 is binary regardless of its extension
+        // (an extensionless fixture, say) — not this check's business.
+        try {
+            new TextDecoder('utf-8', { fatal: true }).decode(data);
+        } catch {
+            continue;
+        }
+        // Iterate CODEPOINTS (the string is already known-valid UTF-8 here), so
+        // DEL and the C1 range are visible — see `_isRawControlCodepoint`.
+        let line = 1;
+        for (const ch of data.toString('utf-8')) {
+            const cp = ch.codePointAt(0);
+            if (cp === undefined) continue;
+            if (cp === 0x0a) {
+                line += 1;
+                continue;
+            }
+            if (!_isRawControlCodepoint(cp)) continue;
+            const hex = cp.toString(16).toUpperCase().padStart(2, '0');
+            out.push(
+                new sl.Finding(
+                    rel,
+                    line,
+                    CHECK,
+                    'HIGH',
+                    `raw control character U+${hex} in a text source — makes ` +
+                        'grep/file(1)/git treat this file as binary and skip it ' +
+                        'silently; use the language escape (e.g. \\0, \\x7F) instead',
+                    1.0,
+                ),
+            );
+        }
+    }
+    return out;
+}
+
 export function _sanitize(filePath: string): string {
     const raw = fs.readFileSync(filePath, 'utf-8');
     let cleaned = '';
@@ -323,6 +509,28 @@ export function main(argv: readonly string[] | null = null): number {
         }
     }
 
+    // Second pass — raw control bytes in text-intended SOURCE files, which the
+    // `.md` corpus above does not cover. Deliberately not folded into
+    // `iter_corpus`: different scope (all tracked text files, not the `.md`
+    // corpus) and a narrower codepoint set (C0 only). `--fix` does not touch
+    // these — rewriting a source file's bytes is the author's call, and the
+    // finding names the escape to use.
+    const sourceFiles = _eligibleSourceFiles();
+    for (const h of _scanSourceControlBytes(sourceFiles)) {
+        findings.push(h);
+    }
+    if (!args.json) {
+        // State the scope on every run. A bare "clean" cannot be told apart
+        // from a pass whose file list was empty.
+        const n = sourceFiles === null ? 0 : sourceFiles.length;
+        process.stdout.write(
+            sourceFiles === null
+                ? '  source pass: SKIPPED — `git ls-files` unavailable, 0 files read for raw control bytes\n'
+                : `  source pass: ${n} tracked text file(s) read for raw C0 control bytes ` +
+                      '(generated trees + verbatim captures excluded)\n',
+        );
+    }
+
     if (args.fix) {
         // sorted(flagged) — by path string.
         for (const p of [...flagged].sort()) {
@@ -342,7 +550,13 @@ export function main(argv: readonly string[] | null = null): number {
     return sl.report(findings, { check_label: 'hidden-unicode' });
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }