@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/chat_history.ts

@@ -46,6 +46,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { _entry_tokens_estimate } from './memory_lookup.js';
 
 import { load_agent_settings } from './_lib/agent_settings.js';
+import { readHookStdin } from './hooks/hook_stdin.js';
 
 export const DEFAULT_FILE = 'agents/runtime/.agent-chat-history';
 export const DEFAULT_SETTINGS_FILE = '.agent-settings.yml';
@@ -2303,11 +2304,7 @@ function _cmd_rotate(argv: string[]): number {
 }
 
 function _readStdin(): string {
-    try {
-        return fs.readFileSync(0, 'utf-8');
-    } catch {
-        return '';
-    }
+    return readHookStdin();
 }
 
 export function main(argv: string[] = process.argv.slice(2)): number {
@@ -2354,7 +2351,13 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     }
 }
 
+// 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;
     }

package/src/scripts/check_artefact_count_messaging.ts

@@ -58,7 +58,11 @@ export const SURFACES: readonly string[] = [
     // watched this file. Added 2026-07-25 so a hand-typed count here fails CI.
     'docs/distribution/registries.md',
     'site/src/content/docs/index.mdx',
-    'site/src/content/docs/claims.md',
+    // NOT site/src/content/docs/claims.md — it is gitignored generated output
+    // (site/sync-docs.mjs copies docs/CLAIMS.md into it), and docs/CLAIMS.md is
+    // already checked above. Watching the copy added no coverage and turned a
+    // stale LOCAL artefact into a red gate, while CI passed because the file is
+    // absent there. A gate must judge repo content, not untracked local state.
 ];
 
 /** kind → canonical-count resolver. "governed rules" is the canonical total

package/src/scripts/check_augment_description_cap.ts

@@ -6,10 +6,10 @@
  * Ported from the retired Python `src/scripts/check_augment_description_cap.py` (ADR-200,
  * Phase 4 / Wave 4c). The CLI contract is pinned — no flags, exit
  * codes (0 pass, 1 over-cap), stdout/stderr split, byte-identical finding
- * messages, same scan scope (`.agent-src.uncondensed/rules/*.md`) and file
+ * messages, same scan scope (`src/rules/*.md`) and file
  * ordering. Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
  *
- * For every `type: auto` rule under `.agent-src.uncondensed/rules/`,
+ * For every `type: auto` rule under `src/rules/`,
  * fail CI when the frontmatter `description:` exceeds DESC_CAP chars.
  *
  * Why: Augment injects each auto-rule's description into the
@@ -17,7 +17,7 @@
  * analysis showed this channel consuming 25 % of the workspace-guidelines
  * ceiling. Capping descriptions guards future drift.
  *
- * Source of truth: `.agent-src.uncondensed/rules/`. The condensed
+ * Source of truth: `src/rules/`. The condensed
  * projection is regenerated; the source dictates what ships.
  *
  * Exit codes: 0 = pass, 1 = at least one rule over cap.
@@ -31,7 +31,12 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 // Mirrors the Python `Path(__file__).resolve().parent.parent.parent`.
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-const RULES_DIR = path.join(REPO_ROOT, '.agent-src.uncondensed', 'rules');
+// Retargeted 2026-07-29: pointed at the tree emptied by the ADR-051 flat-`src/`
+// migration, so this gate printed "All 0 auto-rule descriptions ≤ 150 chars." and
+// exited 0 while wired into CI — the count sat in its own output the whole time.
+// Retargeting surfaced 16 real cap violations (98 auto-rules, max 189); all 16
+// were shortened under an explicit operator review that kept every matching term.
+const RULES_DIR = path.join(REPO_ROOT, 'src', 'rules');
 const DESC_CAP = 150;
 
 const _FM_LINE_RE = /^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/;
@@ -103,6 +108,12 @@ export function main(): number {
         }
     }
 
+    // Gate-coverage contract (src/config/gate-coverage.yml): emitted BEFORE the
+    // pass/fail branch. Coverage and verdict are different questions — a gate that
+    // found real violations still scanned its corpus, and reporting the count only
+    // on the success path would make it look 'silent' to check_gate_coverage.
+    process.stdout.write(`scanned: ${String(checked)}\n`);
+
     if (failures.length) {
         process.stderr.write(
             `❌  ${failures.length} auto-rule description(s) exceed ${DESC_CAP} chars:\n\n`,

package/src/scripts/check_backstop_debt.ts

@@ -7,18 +7,27 @@
  * and had been, invisibly, because no workflow ran them. A rule declared a
  * backstop; the backstop existed; the backstop was red; nothing said so.
  *
- * Those failures are pre-existing debt, not regressions from the wiring change,
- * and fixing eleven framework-leakage spots plus eighteen source-confidentiality
- * hits is a different piece of work with a different reviewer. Folding them in
- * would make one PR unreviewable and would mix "make the gate run" with "clean up
- * what the gate found".
- *
  * So the established pattern applies — the one the decision-homing work already
  * uses and the council endorsed: **baseline the legacy, enforce the boundary.**
  * Each gate's current finding count is committed. The count may fall freely; it
  * may not rise. New violations fail, existing debt is visible and counted, and
  * nothing is silently tolerated.
  *
+ * **The baseline is now 0 across all five gates.** The 37 findings were cleared
+ * in a follow-up pass, so this file no longer records debt — it holds the line at
+ * zero. Keeping the ratchet after the cleanup is the point: it is what stops the
+ * counts creeping back, and the mechanism is identical whether the baseline is 37
+ * or 0.
+ *
+ * Worth recording, because it changes how the next such number should be read:
+ * roughly two thirds of the 37 were never violations. `CREDITS.md` was flagged
+ * for the license-required attribution that `source-confidentiality` explicitly
+ * exempts. A checklist row naming five ecosystems on ONE line read as
+ * PHP-specific because only the PHP family carried a plain-language window hint.
+ * An archived acceptance criterion was flagged for the source names it quotes in
+ * order to assert their absence. Wiring a gate proves that it runs; it does not
+ * prove its findings are real. That takes reading them one at a time.
+ *
  * What this deliberately is NOT: a `continue-on-error` step. That is a WARN
  * wearing a gate's clothes, and removing exactly that confusion is why this
  * workflow exists.
@@ -112,12 +121,12 @@ function main(argv: string[]): number {
             JSON.stringify(
                 {
                     _doc:
-                        'Pre-existing findings in rule backstops that were red when they were first ' +
-                        'wired into CI — they had been failing invisibly because no workflow ran them. ' +
-                        'Counts may FALL freely; a rise fails the build. This is debt made visible, ' +
-                        'not debt tolerated: every number here is a rule whose declared backstop is ' +
-                        'currently not clean. Regenerate with --write-baseline only when the change ' +
-                        'is deliberate.',
+                        'Per-gate finding counts for the rule backstops wired into CI by ' +
+                        'rule-backstops.yml. Counts may FALL freely; a rise fails the build. These ' +
+                        'gates were red on arrival (37 findings) because no workflow had ever run ' +
+                        'them; that debt is now cleared and the baseline holds the line at 0. A ' +
+                        'non-zero number here is a rule whose declared backstop is not currently ' +
+                        'clean. Regenerate with --write-baseline only when the change is deliberate.',
                     gates: Object.fromEntries(measured.map((m) => [m.script, { rule: m.rule, findings: m.findings }])),
                     total: measured.reduce((a, m) => a + m.findings, 0),
                 },
@@ -172,7 +181,8 @@ function main(argv: string[]): number {
         process.stderr.write('❌  rule-backstop debt ratchet:\n');
         for (const r of regressions) process.stderr.write(`    · ${r}\n`);
         process.stderr.write(
-            '    These gates are already failing on pre-existing debt; the ratchet only forbids ADDING to it.\n',
+            '    The baseline is 0 — these gates are clean, so a rise is a NEW violation, not inherited debt.\n' +
+                '    Fix the finding, or re-baseline with --write-baseline if the change is deliberate.\n',
         );
         return 1;
     }

package/src/scripts/check_bundle_path_leakage.ts

@@ -0,0 +1,343 @@
+#!/usr/bin/env tsx
+/**
+ * Guard against build-machine path leakage in the tracked install bundle.
+ *
+ * road-to-feedback-9.2.0-followups Phase 4.1. Three 9.1 commits
+ * (f8752443b, 5933bf1a9, f30adb5a1) each rebuilt `dist/install/install.mjs`
+ * solely to strip a leaked build-environment path esbuild had baked into its
+ * per-module `// <path>` boundary comments: a worktree-relative `../../../
+ * node_modules/...` hop, a repo-relative `../agent-config/node_modules/...`
+ * hop, and a full `/Users/<name>/.../node_modules/...` absolute path. Each
+ * fix was a manual rebuild-and-diff after the fact; this guard makes the
+ * class fail the build instead, so a future leak cannot merge silently.
+ *
+ * Every pattern below is scoped to avoid flagging legitimate bundle content:
+ * the bundle's own emitted runtime strings use relative forms only (e.g.
+ * `"./node_modules/@event4u/agent-config/plugin/agent-config"`, a real
+ * consumer-facing plugin-manifest path), and esbuild's per-module registry
+ * keys are bare `node_modules/<pkg>/...` (no leading `/` or `../`) — neither
+ * shape trips any pattern here.
+ *
+ *   - `macos-linux-home`             — absolute `/Users/<name>/…` or
+ *     `/home/<name>/…`, i.e. a real machine's home directory. Requires at
+ *     least one path segment after the username so a bare `/Users/` or
+ *     `/home/` mention (unlikely, but not impossible in prose) does not
+ *     match on its own.
+ *   - `private-or-opt-root`          — an absolute `/private/…` (macOS's
+ *     `/var` → `/private/var` realpath) or `/opt/…` (common CI-runner tool
+ *     root, e.g. GitHub Actions' hostedtoolcache) path.
+ *   - `windows-drive`                — an absolute Windows path (`C:\…`).
+ *   - `worktree-path`                — a `.claude/worktrees/…` path. This
+ *     package's own git-worktree convention (`worktree-lifecycle` skill) —
+ *     it can never legitimately appear in a shipped consumer artifact.
+ *   - `parent-relative-node-modules`  — any `../`-escaping path that reaches
+ *     a `node_modules/` directory, however many hops or intermediate
+ *     segments (`../../../node_modules/…`, `../agent-config/node_modules/…`).
+ *     A legitimate bundled module reference never needs to climb out of the
+ *     repo root via string literals — node's own resolution algorithm
+ *     handles that internally, not via baked-in `../` path text.
+ *   - `absolute-node-modules`         — any OTHER absolute path (not already
+ *     caught by the three rules above) reaching a `node_modules/` directory.
+ *     The negative lookbehind excludes `./node_modules/…` and mid-identifier
+ *     slashes so a legitimate relative reference is never flagged.
+ *   - `absolute-sourcemap`           — a `sourceMappingURL=` comment pointing
+ *     at an absolute path instead of a bundle-relative filename (the shape
+ *     `.map` files should always use — see `dist/install/*.js.map`, whose
+ *     `sources` field is repo-relative, e.g. `../../src/install/atomic.ts`).
+ *
+ * Usage:
+ *     tsx src/scripts/check_bundle_path_leakage.ts
+ *     tsx src/scripts/check_bundle_path_leakage.ts --quiet
+ *     tsx src/scripts/check_bundle_path_leakage.ts <file> [<file> ...]
+ *
+ * Exit codes: 0 = clean, 1 = leak found, 2 = usage error.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+
+// Tracked directories that may hold a build-generated bundle. Only
+// `dist/install/` is force-included in `.gitignore` today (`!/dist/install/`);
+// `dist/hooks/` and `dist/mcp/` are listed defensively in case a future
+// change tracks them too — `git ls-files` on an untracked directory returns
+// nothing, so listing an as-yet-untracked root here is always safe.
+const BUNDLE_ROOTS: readonly string[] = ['dist/install', 'dist/hooks', 'dist/mcp'];
+
+interface LeakPattern {
+    readonly name: string;
+    readonly re: RegExp;
+    readonly hint: string;
+}
+
+// Every regex carries the `g` flag (all hits scanned, not just the first)
+// and excludes `\s'"` )` from its "rest of the path" class so a match never
+// swallows past the end of a quoted string / comment / parenthesized call.
+const LEAK_PATTERNS: readonly LeakPattern[] = [
+    {
+        name: 'macos-linux-home',
+        re: /\/(?:Users|home)\/[^/\s'"`)]+\/[^\s'"`)]*/g,
+        hint: 'rebuild from a clean, non-worktree checkout after a fresh `npm ci`',
+    },
+    {
+        name: 'private-or-opt-root',
+        re: /(?:^|[^\w.])\/(?:private|opt)\/[^\s'"`)]*/g,
+        hint: 'rebuild in a plain (non-macOS-symlinked, non-CI-tool-cache) tree',
+    },
+    {
+        name: 'windows-drive',
+        re: /\b[A-Za-z]:\\[^\s'"`)]*/g,
+        hint: 'rebuild on a POSIX runner — the published bundle must not carry a Windows path',
+    },
+    {
+        name: 'worktree-path',
+        re: /\.claude\/worktrees\/[^\s'"`)]*/g,
+        hint: 'rebuild from the primary checkout, not a `.claude/worktrees/` git worktree',
+    },
+    {
+        name: 'parent-relative-node-modules',
+        re: /\.\.\/(?:[^\s'"`)]*\/)*node_modules\//g,
+        hint: 'esbuild resolved a dependency outside the repo root (foreign/symlinked node_modules) — rebuild after `npm ci` inside the repo',
+    },
+    {
+        name: 'absolute-node-modules',
+        re: /(?<![.\w/])\/(?:[^\s'"`)]*\/)*node_modules\//g,
+        hint: 'an absolute path reached a node_modules directory — rebuild from a repo-relative tree',
+    },
+    {
+        name: 'absolute-sourcemap',
+        re: /sourceMappingURL=(?:\/|[A-Za-z]:\\)[^\s'"`)]*/g,
+        hint: 'the sourcemap comment must reference a bundle-relative filename, not an absolute path',
+    },
+];
+
+interface Hit {
+    readonly file: string;
+    readonly pattern: string;
+    readonly line: number;
+    readonly snippet: string;
+}
+
+const MAX_SNIPPET = 140;
+const MAX_HITS_SHOWN_PER_GROUP = 5;
+
+/**
+ * Redact the username segment of a `/Users/<name>/…`, `/home/<name>/…`, or
+ * `C:\Users\<name>\…` match before it reaches a log line — the machine
+ * username is incidental PII, not the point of the finding (the finding is
+ * "an absolute path leaked", not "whose machine it was").
+ */
+function mask_snippet(raw: string): string {
+    const masked = raw
+        .replace(/(\/(?:Users|home)\/)[^/\s'"`)]+/, '$1<masked>')
+        .replace(/(:\\Users\\)[^\\'"`)]+/i, '$1<masked>');
+    return masked.length > MAX_SNIPPET ? `${masked.slice(0, MAX_SNIPPET)}…` : masked;
+}
+
+/** 1-based line number of a character offset, mirroring the other check_* scripts' style. */
+function line_of(text: string, index: number): number {
+    let line = 1;
+    for (let i = 0; i < index; i += 1) {
+        if (text.charCodeAt(i) === 0x0a) line += 1;
+    }
+    return line;
+}
+
+/**
+ * Pure scan core: every pattern hit in `content`, tagged with the (already
+ * relative) file path the caller supplies. No filesystem or git access —
+ * tests drive this directly with synthetic strings.
+ */
+function scan_content(relPath: string, content: string): Hit[] {
+    const hits: Hit[] = [];
+    for (const pattern of LEAK_PATTERNS) {
+        pattern.re.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = pattern.re.exec(content))) {
+            hits.push({
+                file: relPath,
+                pattern: pattern.name,
+                line: line_of(content, m.index),
+                snippet: mask_snippet(m[0]),
+            });
+            // Zero-width safety net (none of the patterns above can match
+            // empty, but this mirrors the other check_* scripts' loop guard).
+            if (pattern.re.lastIndex === m.index) pattern.re.lastIndex += 1;
+        }
+    }
+    return hits;
+}
+
+function _git(args: readonly string[]): string {
+    const res = spawnSync('git', [...args], {
+        cwd: REPO,
+        encoding: 'utf-8',
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    return res.stdout ?? '';
+}
+
+function _splitlines(text: string): string[] {
+    return text.split('\n').filter((l) => l.length > 0);
+}
+
+/** Every tracked path under the bundle roots, deduped and sorted. */
+function tracked_bundle_files(): string[] {
+    const seen = new Set<string>();
+    for (const root of BUNDLE_ROOTS) {
+        for (const rel of _splitlines(_git(['ls-files', root]))) {
+            seen.add(rel);
+        }
+    }
+    return [...seen].sort();
+}
+
+/**
+ * Scan one file from disk. Binary / non-UTF-8 content is skipped (a bundle
+ * artifact is always text; a decode failure means this isn't one).
+ */
+function scan_file(relPath: string): Hit[] {
+    // `--file` args accept both repo-relative (the `git ls-files` default
+    // target list) and absolute paths (ad hoc / test use) — never silently
+    // resolve an already-absolute path underneath REPO.
+    const abs = path.isAbsolute(relPath) ? relPath : path.join(REPO, relPath);
+    let text: string;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(abs));
+    } catch {
+        return [];
+    }
+    return scan_content(relPath, text);
+}
+
+function scan_files(relPaths: readonly string[]): Hit[] {
+    const hits: Hit[] = [];
+    for (const rel of relPaths) hits.push(...scan_file(rel));
+    return hits;
+}
+
+function format_report(hits: readonly Hit[]): string {
+    const groups = new Map<string, Hit[]>();
+    for (const hit of hits) {
+        const key = `${hit.file}::${hit.pattern}`;
+        const group = groups.get(key);
+        if (group) group.push(hit);
+        else groups.set(key, [hit]);
+    }
+    const lines: string[] = [
+        '❌  check_bundle_path_leakage: build-machine path leakage in the tracked bundle:',
+    ];
+    for (const [key, group] of groups) {
+        const [file, patternName] = key.split('::') as [string, string];
+        const pattern = LEAK_PATTERNS.find((p) => p.name === patternName);
+        lines.push(`    ${file} [${patternName}] (${group.length} occurrence(s))`);
+        for (const hit of group.slice(0, MAX_HITS_SHOWN_PER_GROUP)) {
+            lines.push(`        line ${hit.line}: ${hit.snippet}`);
+        }
+        if (group.length > MAX_HITS_SHOWN_PER_GROUP) {
+            lines.push(`        (+${group.length - MAX_HITS_SHOWN_PER_GROUP} more)`);
+        }
+        if (pattern) lines.push(`        → ${pattern.hint}`);
+    }
+    return lines.join('\n');
+}
+
+interface Options {
+    quiet: boolean;
+    files: string[];
+}
+
+/** Thrown instead of calling `process.exit` directly, so `main()` stays testable. */
+class ExitCode extends Error {
+    code: number;
+    constructor(code: number) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+
+function parse_args(argv: readonly string[]): Options {
+    const opts: Options = { quiet: false, files: [] };
+    for (const arg of argv) {
+        if (arg === '--quiet') {
+            opts.quiet = true;
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write(
+                'usage: check_bundle_path_leakage.ts [--quiet] [<file> ...]\n',
+            );
+            throw new ExitCode(0);
+        } else if (arg.startsWith('--')) {
+            process.stderr.write(
+                `❌  check_bundle_path_leakage: unrecognized argument: ${arg}\n`,
+            );
+            throw new ExitCode(2);
+        } else {
+            opts.files.push(arg);
+        }
+    }
+    return opts;
+}
+
+function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const opts = parse_args(argv);
+    const targets = opts.files.length > 0 ? opts.files : tracked_bundle_files();
+    const hits = scan_files(targets);
+
+    if (hits.length > 0) {
+        process.stderr.write(`${format_report(hits)}\n`);
+        return 1;
+    }
+
+    if (!opts.quiet) {
+        process.stdout.write(
+            `✅  check_bundle_path_leakage: no build-machine path leakage ` +
+                `(${targets.length} tracked bundle file(s) scanned).\n`,
+        );
+    }
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    try {
+        process.exit(main());
+    } catch (exc) {
+        if (exc instanceof ExitCode) {
+            process.exit(exc.code);
+        }
+        throw exc;
+    }
+}
+
+export {
+    REPO,
+    BUNDLE_ROOTS,
+    LEAK_PATTERNS,
+    MAX_SNIPPET,
+    MAX_HITS_SHOWN_PER_GROUP,
+    mask_snippet,
+    scan_content,
+    scan_file,
+    scan_files,
+    tracked_bundle_files,
+    format_report,
+    parse_args,
+    main,
+    ExitCode,
+};
+export type { Hit, LeakPattern, Options };