@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/_lib/exec_evidence.ts

@@ -0,0 +1,251 @@
+/**
+ * `exec:` evidence — the ledger form that re-derives its own claim.
+ *
+ * The other three evidence forms are existence checks: a file is present, a
+ * substring is present, a URL carries a date. None of them can tell a live
+ * claim from a stale one. A ledger entry reading "the suite is green" whose
+ * pointer resolves to a report nobody regenerated stays `backed` forever.
+ *
+ * `exec:<command> -> 0` closes that: the command runs again and its exit code
+ * carries the verdict. Three properties make it safe enough to run in CI, and
+ * all three are the parts that get dropped when this is rebuilt from memory:
+ *
+ *  1. The allowlist is a set of **argv prefix tuples**, never a regex over a
+ *     command string. A regex over shell text is the classic bypass; a tuple
+ *     compared against parsed argv has nothing to hide behind.
+ *  2. Every argument *after* the matched prefix is re-checked — for shell
+ *     metacharacters and for repo escape — including the right-hand side of
+ *     `--flag=value`. Without that split, `--rootdir=/etc` clears an allowlist
+ *     that only ever looked at the flag name.
+ *  3. Execution is `spawnSync` with an argv array and no shell, confined to the
+ *     repo root, and gated to CI. Locally the caller reports UNVERIFIED rather
+ *     than running anything — see `exec_allowed_here()`.
+ *
+ * Scope limit, stated rather than discovered later: this form only covers
+ * claims whose exit code *is* the verdict. A claim resting on a paid model run,
+ * a stochastic benchmark, or a prose contract cannot use it, and is recorded as
+ * unfalsifiable-by-machine instead of quietly omitted.
+ */
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+/** Marker that opens the fourth evidence form. */
+export const EXEC_PREFIX = 'exec:';
+
+/**
+ * Allowlisted argv prefixes. Each entry is matched element-by-element against
+ * the parsed argv — `["skill_eval_coverage"]` admits
+ * `skill_eval_coverage --check` but not `skill_eval_coverage; rm -rf /`,
+ * because the latter never parses into that shape.
+ *
+ * All but one are this repo's own scripts, run through `scripts-run`. That is a
+ * deliberately narrower surface than a general test-runner allowlist: these are
+ * deterministic, model-free, and already run in CI for other reasons.
+ */
+export const ALLOWLIST_PREFIXES: readonly (readonly string[])[] = [
+    ['skill_eval_coverage'],
+    ['domain_soundness_status'],
+    ['check_artefact_count_messaging'],
+    ['check_enforcement_coverage'],
+    ['check_token_regression'],
+    ['lint_agent_security'],
+    ['measure_lexical_ranking'],
+    ['vitest', 'run'],
+];
+
+/** Shell metacharacters plus the control bytes used to smuggle a second command. */
+const UNSAFE_CHARS = new Set(['&', ';', '|', '>', '<', '`', '$', '\n', '\r', '\0']);
+
+const WINDOWS_ABSOLUTE = /^[A-Za-z]:[\\/]/;
+
+/** Commands that are not repo scripts and must not be routed through scripts-run. */
+const NON_SCRIPT_PREFIXES = new Set(['vitest']);
+
+export interface ExecPointer {
+    /** The command as written in the ledger, e.g. `skill_eval_coverage --check`. */
+    command: string;
+    /** The exit code the claim asserts. */
+    expected: number;
+}
+
+export interface ExecOutcome {
+    /** `true` only when the command ran AND matched the asserted exit code. */
+    verified: boolean;
+    /** `true` when the command ran and disagreed — a real finding, not a skip. */
+    mismatch: boolean;
+    /** Human-readable verdict for the report. */
+    reason: string;
+}
+
+/**
+ * Parse `exec:<command> -> <code>`. Accepts `->` and the `→` the docs render.
+ * Returns null when `raw` is not an exec pointer at all, so callers can fall
+ * through to the path/URL forms.
+ */
+export function parse_exec_pointer(raw: string): ExecPointer | { error: string } | null {
+    const ev = raw.trim();
+    if (!ev.startsWith(EXEC_PREFIX)) return null;
+
+    const body = ev.slice(EXEC_PREFIX.length).trim();
+    const arrow = body.match(/\s*(?:->|→)\s*(\d+)\s*$/);
+    if (!arrow) return { error: 'exec pointer missing the `-> <exit-code>` suffix' };
+
+    const command = body.slice(0, arrow.index).trim();
+    if (!command) return { error: 'exec pointer has an empty command' };
+
+    return { command, expected: Number(arrow[1]) };
+}
+
+/**
+ * Split a command into argv without invoking a shell. Deliberately minimal: no
+ * quote handling, no expansion, no substitution. Anything that would *need*
+ * those is rejected by `args_are_safe` anyway, so supporting them would only
+ * widen the surface.
+ */
+export function split_argv(command: string): string[] {
+    return command.split(/\s+/).filter((t) => t.length > 0);
+}
+
+/** Does argv start with an allowlisted prefix? */
+export function command_is_allowlisted(argv: string[]): boolean {
+    return ALLOWLIST_PREFIXES.some(
+        (prefix) => argv.length >= prefix.length && prefix.every((tok, i) => argv[i] === tok),
+    );
+}
+
+/** Would this argument reach outside the repo? */
+function targets_outside_repo(candidate: string): boolean {
+    if (candidate.startsWith('/')) return true;
+    if (WINDOWS_ABSOLUTE.test(candidate)) return true;
+    if (candidate === '..' || candidate.startsWith('../')) return true;
+    return candidate.includes('/../');
+}
+
+/**
+ * Re-check every argument after the allowlisted prefix.
+ *
+ * The `--flag=value` split is the part worth keeping: an allowlist that only
+ * inspects the token as written treats `--rootdir=/etc` as a flag and lets the
+ * path through. Here the right-hand side is extracted and checked on its own.
+ */
+export function args_are_safe(argv: string[]): boolean {
+    for (const arg of argv.slice(1)) {
+        for (const ch of arg) {
+            if (UNSAFE_CHARS.has(ch)) return false;
+        }
+        const eq = arg.indexOf('=');
+        const candidate = arg.startsWith('-') && eq !== -1 ? arg.slice(eq + 1) : arg;
+        if (candidate && targets_outside_repo(candidate)) return false;
+    }
+    return true;
+}
+
+/**
+ * Static validation — everything checkable without running anything.
+ *
+ * Split out from `run_exec_evidence` on purpose: a malformed or non-allowlisted
+ * command is a defect in the *ledger*, so it must fail on a laptop too. Only
+ * the re-execution half is environment-dependent. Returns null when the pointer
+ * is well-formed and admissible, else the reason.
+ */
+export function exec_static_error(pointer: ExecPointer): string | null {
+    const argv = split_argv(pointer.command);
+    if (argv.length === 0) return 'exec pointer has an empty command';
+    if (!command_is_allowlisted(argv)) {
+        return `exec command \`${pointer.command}\` is not in the deterministic allowlist`;
+    }
+    if (!args_are_safe(argv)) {
+        return `exec command \`${pointer.command}\` carries a suspicious argument`;
+    }
+    return null;
+}
+
+/**
+ * May this environment execute evidence commands?
+ *
+ * CI only. A consumer's checkout never re-runs a claim's command — the upstream
+ * package's ledger is not the consumer's business, and "runs in the repository
+ * root with full filesystem access" is a property to confine, not to trust.
+ */
+export function exec_allowed_here(env: NodeJS.ProcessEnv = process.env): boolean {
+    if (env.AGENT_CONFIG_EXEC_EVIDENCE === '1') return true; // maintainer opt-in, one run
+    return env.CI === 'true' || env.CI === '1';
+}
+
+/** Build the real argv: repo scripts go through `scripts-run`, others run directly. */
+function resolve_runner(argv: string[], repo: string): { file: string; args: string[] } {
+    const head = argv[0] as string;
+    if (NON_SCRIPT_PREFIXES.has(head)) {
+        return { file: path.join(repo, 'node_modules', '.bin', head), args: argv.slice(1) };
+    }
+    return {
+        file: path.join(repo, 'scripts-run'),
+        args: [`src/scripts/${head}`, ...argv.slice(1)],
+    };
+}
+
+/**
+ * Run an allowlisted evidence command and compare its exit code to the claim.
+ *
+ * Never throws: every failure path returns an `ExecOutcome` so one bad pointer
+ * cannot take down the whole ledger check. `mismatch` distinguishes "ran and
+ * disagreed" (a finding) from "could not run" (a skip) — collapsing those two
+ * is how a verifier turns into a rubber stamp.
+ */
+export function run_exec_evidence(pointer: ExecPointer, repo: string, timeoutMs = 300_000): ExecOutcome {
+    const argv = split_argv(pointer.command);
+
+    if (argv.length === 0) {
+        return { verified: false, mismatch: false, reason: 'UNVERIFIED: empty command' };
+    }
+    if (!command_is_allowlisted(argv)) {
+        return {
+            verified: false,
+            mismatch: false,
+            reason: `UNVERIFIED: \`${pointer.command}\` is not in the deterministic allowlist`,
+        };
+    }
+    if (!args_are_safe(argv)) {
+        return {
+            verified: false,
+            mismatch: false,
+            reason: `UNVERIFIED: \`${pointer.command}\` carries a suspicious argument`,
+        };
+    }
+
+    const { file, args } = resolve_runner(argv, repo);
+    const result = spawnSync(file, args, {
+        cwd: repo,
+        encoding: 'utf-8',
+        timeout: timeoutMs,
+        shell: false,
+    });
+
+    if (result.error) {
+        return {
+            verified: false,
+            mismatch: false,
+            reason: `UNVERIFIED: could not execute \`${pointer.command}\` (${result.error.message})`,
+        };
+    }
+    if (result.status === null) {
+        return {
+            verified: false,
+            mismatch: false,
+            reason: `UNVERIFIED: \`${pointer.command}\` was killed (timeout or signal)`,
+        };
+    }
+    if (result.status !== pointer.expected) {
+        return {
+            verified: false,
+            mismatch: true,
+            reason: `evidence mismatch — claim asserts exit ${pointer.expected}, \`${pointer.command}\` exited ${result.status}`,
+        };
+    }
+    return {
+        verified: true,
+        mismatch: false,
+        reason: `verified \`${pointer.command}\` (exit ${result.status})`,
+    };
+}

package/src/scripts/_lib/fixtures/secret-detector/negatives.txt

@@ -0,0 +1,15 @@
+# secret-detector negative fixtures — all benign, must not flag high/medium.
+api_key = "changeme"
+api_key = "xxxxxxxxxxxxxxxx"
+password = "your-password-here"
+build commit d41d8cd98f00b204e9800998ecf8427e5f1a2b3c
+request id 550e8400-e29b-41d4-a716-446655440000
+bundle integrity 3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b
+data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAElFTkSuQmCC
+API_KEY=your-key-here
+aws_key = "AKIAZ4Q7WXYT2H9RVBKL"  # secret-allow
+aws docs example AKIAIOSFODNN7EXAMPLE
+stripe_key = "sk_test_placeholder"
+token = "[REDACTED]"
+password = "********"
+checksum sha512-VGhpcyBpcyBub3QgYSBzZWNyZXQgYXQgYWxsIGp1c3QgYSBkaWdlc3Q=

package/src/scripts/_lib/fixtures/secret-detector/positives.txt

@@ -0,0 +1,15 @@
+# secret-detector positive fixtures — every value below is FAKE, do not use.
+# Line format: <kind-label>|<fake-secret>
+aws|AKIA1234567890ABCDEF
+github|ghp_0123456789abcdefghijklmnopqrstuvwxyz
+stripe|sk_live_0123456789abcdefABCDEF
+google|AIza0123456789abcdefghijklmnopqrstuvwxy
+slack|xoxb-0123456789-abcdefABCDEF
+pem|-----BEGIN RSA PRIVATE KEY-----
+jwt|eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+dburl|postgres://dbuser:s3cr3tpass@db.internal:5432/app
+assignment|api_key = "s3cr3tV4lu3Abc123"
+github-fine-grained|github_pat_11ABCDEFG0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
+env-db-password|DB_PASSWORD=q7Xp2Vr9kLm4Nt8wYz3BdF6h
+env-api-key|API_KEY=Zr4tK9pQx2Wm7Vn3Jb8LcD5f
+dburl-mysql|mysql://svc:P4ssw0rdXyz789@10.0.0.12:3306/prod

package/src/scripts/_lib/install_drift.ts

@@ -0,0 +1,194 @@
+/**
+ * Installer drift report (measurement only, never a gate).
+ *
+ * Compares the sha256 hashes recorded in a project's
+ * `agents/installed-tools.lock` manifest (`kind: 'deployed'` file entries —
+ * written by the installer at deploy time, see `install.ts`'s `_file_entry`)
+ * against the current on-disk content of those same files. A mismatch means
+ * a framework-authoritative file was locally modified since the last
+ * install/upgrade; a missing file means it was deleted. This measures the
+ * "consumers edit framework-authoritative files" premise — it never repairs,
+ * never blocks, and has no opinion on whether drift is good or bad. See
+ * `report_install_drift.ts` (the standalone CLI, always exits 0) and
+ * `install.ts`'s global-install upgrade path (prints the report and
+ * proceeds with the redeploy regardless of what it finds).
+ *
+ * Deliberately does NOT reuse `installed_tools.read_manifest()`: that
+ * module's manual v1/v2 parser silently drops nested `tools[].files[]`
+ * entries on read (documented divergence in that module's header) — exactly
+ * the data this report needs. This module parses the manifest YAML directly
+ * with the `yaml` package (a real dependency of this package, already used
+ * by dozens of sibling scripts) so `sha256` values are read faithfully. It
+ * still reuses `installed_tools.manifest_path()` for path resolution + the
+ * `AGENT_CONFIG_INSTALLED_TOOLS` env override, so there is exactly one place
+ * that decides "where is the manifest".
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+
+import { manifest_path, type EnvMap } from "./installed_tools.js";
+
+export type DriftStatus = "modified" | "missing";
+
+export interface DriftEntry {
+  /** Tool id the entry is recorded under (`tools[].name` in the manifest). */
+  tool_id: string;
+  /** Resolved on-disk path (absolute when the recorded path was absolute). */
+  path: string;
+  status: DriftStatus;
+  recorded_sha256: string;
+  /** `null` when the file is missing entirely (status === 'missing'). */
+  current_sha256: string | null;
+}
+
+/** Expand a leading `~`, mirroring the sibling helper in `installed_tools.ts`. */
+function expanduser(p: string): string {
+  if (p === "~") {
+    return os.homedir();
+  }
+  if (p.startsWith("~/") || (process.platform === "win32" && p.startsWith("~\\"))) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+/** Resolve a manifest-recorded path against the project root (mirrors `cmd_doctor.ts`'s `_resolve_path`). */
+function resolve_entry_path(project_root: string, raw: string): string {
+  const p = expanduser(raw);
+  return path.isAbsolute(p) ? p : path.join(project_root, p);
+}
+
+function sha256_of_file(p: string): string | null {
+  try {
+    return crypto.createHash("sha256").update(fs.readFileSync(p)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the project manifest and return one entry per `kind: 'deployed'` file
+ * whose current on-disk sha256 differs from the recorded value, or which no
+ * longer exists.
+ *
+ * Returns `null` when there is no manifest at all (or it fails to parse) —
+ * distinct from `[]`, which means the manifest was read fine and nothing has
+ * drifted. Never throws.
+ */
+export function collect_drift(project_root: string, env?: EnvMap | null): DriftEntry[] | null {
+  const target = manifest_path(project_root, env);
+
+  let text: string;
+  try {
+    text = fs.readFileSync(target, "utf-8");
+  } catch {
+    return null;
+  }
+
+  let data: unknown;
+  try {
+    data = parseYaml(text, { version: "1.1" });
+  } catch {
+    return null;
+  }
+  if (typeof data !== "object" || data === null) {
+    return null;
+  }
+  const tools = (data as Record<string, unknown>)["tools"];
+  if (!Array.isArray(tools)) {
+    // Manifest parsed fine, just carries no tools — that is "clean", not
+    // "no manifest".
+    return [];
+  }
+
+  const out: DriftEntry[] = [];
+  for (const tool of tools) {
+    if (typeof tool !== "object" || tool === null) {
+      continue;
+    }
+    const t = tool as Record<string, unknown>;
+    const tool_id = t["name"] === undefined ? "" : String(t["name"]);
+    const files = t["files"];
+    if (!Array.isArray(files)) {
+      continue;
+    }
+    for (const entry of files) {
+      if (typeof entry !== "object" || entry === null) {
+        continue;
+      }
+      const e = entry as Record<string, unknown>;
+      if (e["kind"] !== "deployed") {
+        continue;
+      }
+      const recorded_sha256 = e["sha256"];
+      if (typeof recorded_sha256 !== "string" || recorded_sha256 === "") {
+        continue;
+      }
+      const raw_path = e["path"];
+      if (typeof raw_path !== "string" || raw_path === "") {
+        continue;
+      }
+
+      const resolved = resolve_entry_path(project_root, raw_path);
+      if (!fs.existsSync(resolved)) {
+        out.push({
+          tool_id,
+          path: resolved,
+          status: "missing",
+          recorded_sha256,
+          current_sha256: null,
+        });
+        continue;
+      }
+      const current = sha256_of_file(resolved);
+      if (current === recorded_sha256) {
+        continue;
+      }
+      out.push({
+        tool_id,
+        path: resolved,
+        status: "modified",
+        recorded_sha256,
+        current_sha256: current,
+      });
+    }
+  }
+
+  out.sort((a, b) => {
+    if (a.tool_id !== b.tool_id) {
+      return a.tool_id < b.tool_id ? -1 : 1;
+    }
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+  });
+  return out;
+}
+
+/**
+ * Human-readable report body — one line per drifted file plus a summary
+ * line, or an explicit "clean"/"no manifest" line. Never throws.
+ */
+export function format_drift_report(entries: DriftEntry[] | null): string {
+  if (entries === null) {
+    return "Installer drift: no installed-tools manifest found — nothing to report.\n";
+  }
+  if (entries.length === 0) {
+    return "Installer drift: no local modifications detected in framework-authoritative files.\n";
+  }
+
+  const lines: string[] = [];
+  for (const e of entries) {
+    const label = e.status === "missing" ? "missing " : "modified";
+    lines.push(`  ${label}  [${e.tool_id}]  ${e.path}`);
+  }
+  const modified = entries.filter((e) => e.status === "modified").length;
+  const missing = entries.filter((e) => e.status === "missing").length;
+  lines.push("");
+  lines.push(
+    `Installer drift: ${entries.length} framework-authoritative file(s) locally modified ` +
+      `since the last install (${modified} modified, ${missing} missing).`,
+  );
+  return lines.join("\n") + "\n";
+}

package/src/scripts/_lib/kernel_rules.ts

@@ -0,0 +1,46 @@
+/**
+ * The locked kernel set — one definition, imported everywhere.
+ *
+ * These nine rules are the Iron-Law floor (`docs/contracts/kernel-membership.md`
+ * § 4). Before this module the list existed three times — in
+ * `check_kernel_rule_bundle.ts`, `iron_law_sha.ts`, and `measure_rule_budget.ts`
+ * — two of them carrying a "kept in sync with …" comment, which is the standard
+ * way a list drifts: the comment records an intention, nothing enforces it.
+ *
+ * Membership is a governance decision, not a convenience. Adding or removing an
+ * entry changes what may never be overridden, what the prefix-stability snapshot
+ * covers, and what the one-kernel-rule-per-PR gate applies to. Change it here,
+ * once, and let every consumer follow.
+ */
+
+/** Kernel rule ids, stem form (no extension), in stable sorted order. */
+export const KERNEL_RULE_IDS: readonly string[] = [
+    'agent-authority',
+    'ask-when-uncertain',
+    'commit-policy',
+    'direct-answers',
+    'language-and-tone',
+    'no-cheap-questions',
+    'non-destructive-by-default',
+    'scope-control',
+    'verify-before-complete',
+] as const;
+
+/** Same set, `.md` filename form — what path-matching consumers compare against. */
+export const KERNEL_RULE_FILENAMES: ReadonlySet<string> = new Set(
+    KERNEL_RULE_IDS.map((id) => `${id}.md`),
+);
+
+/** Set form of the stems, for membership tests that key on the id. */
+export const KERNEL_RULE_ID_SET: ReadonlySet<string> = new Set(KERNEL_RULE_IDS);
+
+/**
+ * True when `name` names a kernel rule, in either stem or `.md` form.
+ *
+ * Accepts a bare id, a filename, or a path ending in either — callers hold the
+ * name in all three shapes and should not each re-derive the normalisation.
+ */
+export function is_kernel_rule(name: string): boolean {
+    const base = name.replace(/\\/g, '/').split('/').pop() ?? name;
+    return KERNEL_RULE_ID_SET.has(base.replace(/\.md$/, ''));
+}