@de-otio/repo-aegis-core 0.2.0

package/src/regex-safety.test.ts

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import {
+  validatePattern,
+  validatePatterns,
+  getRegexBackend,
+  setRegexBackendForTesting,
+} from "./regex-safety.js";
+
+describe("validatePattern", () => {
+  it("accepts ordinary patterns", () => {
+    assert.equal(validatePattern("acme-corp").ok, true);
+    assert.equal(validatePattern("\\d{12}").ok, true);
+    assert.equal(validatePattern("[a-z]+@example\\.com").ok, true);
+  });
+
+  it("rejects empty patterns", () => {
+    const r = validatePattern("");
+    assert.equal(r.ok, false);
+    assert.match(r.reason!, /empty/);
+  });
+
+  it("rejects non-string input", () => {
+    const r = validatePattern(undefined as unknown as string);
+    assert.equal(r.ok, false);
+  });
+
+  it("rejects syntactically invalid regex", () => {
+    const r = validatePattern("(unclosed");
+    assert.equal(r.ok, false);
+    assert.match(r.reason!, /invalid regex/);
+  });
+
+  it("rejects patterns over the length cap", () => {
+    const r = validatePattern("a".repeat(2049));
+    assert.equal(r.ok, false);
+    assert.match(r.reason!, /exceeds|length/i);
+  });
+
+  it("accepts patterns just under the length cap", () => {
+    const r = validatePattern("a".repeat(2000));
+    assert.equal(r.ok, true);
+  });
+});
+
+describe("validatePatterns", () => {
+  it("splits valid and invalid patterns", () => {
+    const r = validatePatterns(["acme-corp", "(unclosed", "\\d+"]);
+    assert.equal(r.valid.length, 2);
+    assert.equal(r.invalid.length, 1);
+    assert.equal(r.invalid[0]!.pattern, "(unclosed");
+  });
+
+  it("returns empty when all patterns are valid", () => {
+    const r = validatePatterns(["a", "b", "c"]);
+    assert.equal(r.valid.length, 3);
+    assert.equal(r.invalid.length, 0);
+  });
+
+  it("returns empty when no patterns provided", () => {
+    const r = validatePatterns([]);
+    assert.equal(r.valid.length, 0);
+    assert.equal(r.invalid.length, 0);
+  });
+});
+
+describe("validatePatterns({ strict: true })", () => {
+  it("accepts ordinary patterns", () => {
+    const r = validatePatterns(["acme-corp", "\\d{12}"], { strict: true });
+    assert.equal(r.valid.length, 2);
+    assert.equal(r.invalid.length, 0);
+  });
+
+  it("rejects syntactically invalid regex without spawning", () => {
+    const r = validatePatterns(["(unclosed"], { strict: true });
+    assert.equal(r.invalid.length, 1);
+    assert.match(r.invalid[0]!.reason, /invalid regex/);
+  });
+
+  it("rejects patterns over the length cap without spawning", () => {
+    const r = validatePatterns(["a".repeat(3000)], { strict: true });
+    assert.equal(r.invalid.length, 1);
+    assert.match(r.invalid[0]!.reason, /exceeds/);
+  });
+
+  it("flags catastrophic-backtracking patterns via subprocess", () => {
+    // Classic ReDoS shape: nested unbounded quantifier with a literal
+    // that the all-'a' stress input cannot satisfy, forcing the regex
+    // engine to try every possible split.
+    const r = validatePatterns(["^(a+)+b$"], { strict: true });
+    assert.equal(r.invalid.length, 1, `expected the pattern to be rejected; got valid=${JSON.stringify(r.valid)}`);
+    assert.match(r.invalid[0]!.reason, /catastrophic|timed out|>/i);
+  });
+
+  it("returns empty for empty input without spawning", () => {
+    const r = validatePatterns([], { strict: true });
+    assert.equal(r.valid.length, 0);
+    assert.equal(r.invalid.length, 0);
+  });
+
+  it("preserves order across mixed valid/invalid input", () => {
+    const r = validatePatterns(
+      ["acme-corp", "(bad", "\\d+", ""],
+      { strict: true },
+    );
+    assert.deepEqual(r.valid, ["acme-corp", "\\d+"]);
+    assert.equal(r.invalid.length, 2);
+  });
+
+  it("reports trailing patterns when subprocess is killed mid-batch", () => {
+    // Strict-batch truncation contract: if the worker subprocess hangs on
+    // a catastrophic pattern and gets SIGTERMed, we must still report the
+    // patterns it never got to. The first pattern is fine and should be
+    // valid, the second is catastrophic-backtracking and should be in
+    // invalid (with a "timed out" or "catastrophic" reason), and the
+    // third — which the subprocess likely never reached — must also be
+    // reported (most likely as "produced no result" if truncation
+    // occurred mid-batch).
+    const r = validatePatterns(
+      ["acme-corp", "^(a+)+b$", "\\d{12}"],
+      { strict: true },
+    );
+
+    // The first pattern is well-formed; it should always come back valid.
+    assert.ok(
+      r.valid.includes("acme-corp"),
+      `expected first pattern to validate; got valid=${JSON.stringify(r.valid)}`,
+    );
+
+    // The catastrophic pattern must end up in the invalid bucket with a
+    // reason that names the failure mode.
+    const cata = r.invalid.find(x => x.pattern === "^(a+)+b$");
+    assert.ok(cata, `expected ^(a+)+b$ in invalid; got invalid=${JSON.stringify(r.invalid)}`);
+    assert.match(cata!.reason, /timed out|catastrophic|>/i);
+
+    // The third pattern is well-formed *but* may have been trampled by
+    // the kill-on-timeout. It must show up in *one* of the result sets:
+    // valid (if the worker got that far before timeout), or invalid with
+    // a "no result" / "timed out" reason (if truncation hit it).
+    const reported =
+      r.valid.includes("\\d{12}") ||
+      r.invalid.some(x => x.pattern === "\\d{12}");
+    assert.ok(
+      reported,
+      `third pattern must be reported in valid or invalid; ` +
+        `valid=${JSON.stringify(r.valid)} invalid=${JSON.stringify(r.invalid)}`,
+    );
+
+    // Total accounting: every input pattern must show up exactly once
+    // across the two buckets.
+    assert.equal(r.valid.length + r.invalid.length, 3);
+  });
+});
+
+describe("getRegexBackend", () => {
+  after(() => setRegexBackendForTesting(null));
+
+  it("returns 're2' or 'in-process' depending on optional dep availability", () => {
+    setRegexBackendForTesting(null);
+    const backend = getRegexBackend();
+    assert.ok(
+      backend === "re2" || backend === "in-process",
+      `unexpected backend: ${backend}`,
+    );
+  });
+
+  it("respects setRegexBackendForTesting override", () => {
+    setRegexBackendForTesting("in-process");
+    assert.equal(getRegexBackend(), "in-process");
+    setRegexBackendForTesting("re2");
+    assert.equal(getRegexBackend(), "re2");
+    setRegexBackendForTesting(null);
+  });
+
+  it("validatePattern accepts ordinary patterns under both backends", () => {
+    setRegexBackendForTesting("in-process");
+    assert.equal(validatePattern("acme-corp").ok, true);
+    setRegexBackendForTesting("re2");
+    assert.equal(validatePattern("acme-corp").ok, true);
+    setRegexBackendForTesting(null);
+  });
+
+  it("validatePattern falls back to time-budget when re2 rejects (e.g. lookahead)", () => {
+    // Lookahead is a re2-incompatible feature. Whether re2 is installed
+    // or not, validatePattern must still accept this pattern because
+    // the scanner uses native RegExp, which supports lookahead.
+    setRegexBackendForTesting("re2");
+    const r = validatePattern("foo(?=bar)");
+    assert.equal(r.ok, true, `expected lookahead pattern to validate; reason=${r.reason}`);
+    setRegexBackendForTesting(null);
+  });
+});

package/src/regex-safety.ts

@@ -0,0 +1,349 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+
+export interface PatternValidationResult {
+  ok: boolean;
+  reason?: string;
+}
+
+export type RegexBackend = "re2" | "in-process" | "subprocess";
+
+// Probe `re2` once at module load via `createRequire` so we keep
+// validatePattern fully sync. `re2` is an optionalDependency: install
+// failures (no native build toolchain) leave us on the in-process
+// fallback, which still provides best-effort ReDoS detection.
+const _require = createRequire(import.meta.url);
+interface Re2Constructor {
+  new (pattern: string, flags?: string): { test(s: string): boolean };
+}
+let re2Ctor: Re2Constructor | null = null;
+let re2Probed = false;
+function probeRe2(): Re2Constructor | null {
+  if (re2Probed) return re2Ctor;
+  re2Probed = true;
+  try {
+    const mod = _require("re2") as Re2Constructor | { default: Re2Constructor };
+    re2Ctor =
+      typeof mod === "function"
+        ? mod
+        : "default" in mod
+        ? mod.default
+        : (mod as unknown as Re2Constructor);
+  } catch {
+    re2Ctor = null;
+  }
+  return re2Ctor;
+}
+
+let forcedBackend: RegexBackend | null = null;
+
+/**
+ * Test-only override. Forces {@link getRegexBackend} and
+ * {@link validatePattern} to use a specific backend regardless of which
+ * backends are installed. Pass `null` to clear. Production callers must
+ * not use this.
+ *
+ * @internal
+ */
+export function setRegexBackendForTesting(backend: RegexBackend | null): void {
+  forcedBackend = backend;
+}
+
+/**
+ * Report which regex backend repo-aegis is using for *additional*
+ * pattern-safety validation:
+ *
+ * - `"re2"`: the optional `re2` dependency is installed. Patterns that
+ *   compile cleanly in re2 are provably safe from catastrophic
+ *   backtracking (re2's hybrid NFA/DFA evaluator is linear-time by
+ *   construction). For patterns that re2 can't parse (lookahead /
+ *   look-behind / backreferences are unsupported in re2), validation
+ *   falls back to the `"in-process"` time-budget heuristic.
+ * - `"in-process"`: re2 is unavailable; the in-process timer fires
+ *   after the test completes (best-effort, may exceed budget).
+ *   {@link validatePatterns} `{ strict: true }` upgrades to
+ *   `"subprocess"` for the duration of that call.
+ * - `"subprocess"`: only returned by {@link getRegexBackend} when set
+ *   via {@link setRegexBackendForTesting}; otherwise an internal
+ *   detail of {@link validatePatterns}.
+ *
+ * Note: re2 affects *validation*, not the scanner's regex engine. The
+ * scanner still uses Node's native RegExp because the marker patterns
+ * may legitimately use lookahead constructs that re2 doesn't support.
+ */
+export function getRegexBackend(): RegexBackend {
+  if (forcedBackend !== null) return forcedBackend;
+  return probeRe2() !== null ? "re2" : "in-process";
+}
+
+const MAX_PATTERN_LENGTH = 2048;
+const MAX_COMBINED_BYTES = 128 * 1024;
+const REDOS_STRESS_LENGTH = 1000;
+const REDOS_TIMEOUT_MS = 100;
+const STRICT_BATCH_TIMEOUT_MS = 5000;
+
+/**
+ * Validate a single regex pattern for use as a marker.
+ *
+ * Checks:
+ * 1. Compiles as a JavaScript RegExp without throwing.
+ * 2. Length <= 2048 chars.
+ * 3. Backtracking-bound test against `'a'.repeat(1000)` completes within 100ms.
+ *    Catastrophic-backtracking patterns (e.g., `(a+)+$`) hang here and are
+ *    rejected as ReDoS-suspected.
+ *
+ * Run at `render` time; bad patterns must not reach the hot path of `check`.
+ *
+ * @internal Prefer {@link validatePatterns} (which can run strict,
+ * subprocess-backed validation that is preemptable on catastrophic
+ * backtracking). This single-pattern, in-process helper is exposed for
+ * intra-repo callers that already pre-validate adversary-trust boundaries
+ * but is not part of the supported public API.
+ */
+export function validatePattern(pattern: string): PatternValidationResult {
+  if (typeof pattern !== "string" || pattern.length === 0) {
+    return { ok: false, reason: "empty pattern" };
+  }
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    return { ok: false, reason: `pattern exceeds ${MAX_PATTERN_LENGTH} characters` };
+  }
+  try {
+    new RegExp(pattern, "i");
+  } catch (err) {
+    return { ok: false, reason: `invalid regex: ${(err as Error).message}` };
+  }
+  // Backend-dependent ReDoS check.
+  const backend = getRegexBackend();
+  if (backend === "re2") {
+    const Re2 = probeRe2();
+    if (Re2 !== null) {
+      try {
+        new Re2(pattern, "i");
+        // re2 compile succeeded → linear-time evaluation guaranteed.
+        return { ok: true };
+      } catch {
+        // re2 rejected (typically: pattern uses lookahead/lookbehind/
+        // backreferences which re2 doesn't support). Fall through to
+        // the in-process timer — the pattern is still valid for the
+        // scanner's RegExp engine, just not provably safe under re2.
+      }
+    }
+  }
+  // Synchronous in-process timing check. Best-effort: see SECURITY
+  // WARNING on isInTimeBudget. Worker-based watchdog adds startup
+  // overhead disproportionate to per-pattern cost; for marker-list sizes
+  // we expect (tens to low hundreds of patterns) the in-process check
+  // is fine for trusted-by-policy operator input.
+  if (!isInTimeBudget(pattern, REDOS_STRESS_LENGTH, REDOS_TIMEOUT_MS)) {
+    return {
+      ok: false,
+      reason:
+        `pattern took >${REDOS_TIMEOUT_MS}ms on stress input ` +
+        `(possible catastrophic backtracking; consider re-anchoring)`,
+    };
+  }
+  return { ok: true };
+}
+
+export interface ValidatePatternsOptions {
+  /**
+   * If true, run the backtracking-bound test in a subprocess that can be
+   * preemptively killed on timeout. Catches catastrophic-backtracking
+   * patterns that the in-process timer can only detect after-the-fact.
+   * Adds ~50-200ms of process-spawn overhead for the whole batch.
+   * Default: false (use the in-process timer).
+   */
+  strict?: boolean;
+}
+
+/**
+ * Validate a list of patterns. Returns split valid/invalid.
+ *
+ * With `strict: true`, runs the backtracking-bound check in a subprocess
+ * that can be preemptively killed if any pattern hangs the regex engine.
+ * Recommended for `render` and other one-time-cost paths; not for the
+ * per-scan hot path.
+ */
+export function validatePatterns(
+  patterns: string[],
+  opts: ValidatePatternsOptions = {},
+): { valid: string[]; invalid: { pattern: string; reason: string }[] } {
+  if (opts.strict) {
+    return validatePatternsStrict(patterns);
+  }
+  const valid: string[] = [];
+  const invalid: { pattern: string; reason: string }[] = [];
+  for (const p of patterns) {
+    const r = validatePattern(p);
+    if (r.ok) valid.push(p);
+    else invalid.push({ pattern: p, reason: r.reason ?? "unknown" });
+  }
+  return { valid, invalid };
+}
+
+/**
+ * Subprocess-backed strict validation. Spawns a child node process that
+ * runs each pattern's stress test sequentially, streaming a one-line
+ * JSON result per pattern. If the parent kills the child by timeout,
+ * the partial output identifies which pattern was in flight.
+ */
+function validatePatternsStrict(
+  patterns: string[],
+): { valid: string[]; invalid: { pattern: string; reason: string }[] } {
+  if (patterns.length === 0) return { valid: [], invalid: [] };
+
+  // First pass: catch syntax + length errors in-process so we don't
+  // pay process-spawn cost for them.
+  const valid: string[] = [];
+  const invalid: { pattern: string; reason: string }[] = [];
+  const toCheckRedos: string[] = [];
+  for (const p of patterns) {
+    if (typeof p !== "string" || p.length === 0) {
+      invalid.push({ pattern: p, reason: "empty pattern" });
+      continue;
+    }
+    if (p.length > MAX_PATTERN_LENGTH) {
+      invalid.push({
+        pattern: p,
+        reason: `pattern exceeds ${MAX_PATTERN_LENGTH} characters`,
+      });
+      continue;
+    }
+    try {
+      new RegExp(p, "i");
+    } catch (err) {
+      invalid.push({ pattern: p, reason: `invalid regex: ${(err as Error).message}` });
+      continue;
+    }
+    toCheckRedos.push(p);
+  }
+
+  if (toCheckRedos.length === 0) {
+    return { valid, invalid };
+  }
+
+  const script = `
+const fs = require('fs');
+const input = JSON.parse(fs.readFileSync(0, 'utf8'));
+const { patterns, stressLength, perPatternBudgetMs } = input;
+const stress = 'a'.repeat(stressLength);
+for (let i = 0; i < patterns.length; i++) {
+  const p = patterns[i];
+  const start = Date.now();
+  let outcome;
+  try {
+    new RegExp(p, 'i').test(stress);
+    const elapsed = Date.now() - start;
+    if (elapsed > perPatternBudgetMs * 10) {
+      outcome = { i, ok: false, reason:
+        'pattern took >' + perPatternBudgetMs + 'ms on stress input ' +
+        '(possible catastrophic backtracking; consider re-anchoring)' };
+    } else {
+      outcome = { i, ok: true };
+    }
+  } catch (err) {
+    outcome = { i, ok: false, reason: 'invalid regex: ' + err.message };
+  }
+  process.stdout.write(JSON.stringify(outcome) + '\\n');
+}
+`;
+  const result = spawnSync(process.execPath, ["-e", script], {
+    input: JSON.stringify({
+      patterns: toCheckRedos,
+      stressLength: REDOS_STRESS_LENGTH,
+      perPatternBudgetMs: REDOS_TIMEOUT_MS,
+    }),
+    encoding: "utf8",
+    timeout: STRICT_BATCH_TIMEOUT_MS,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+
+  // Parse partial stdout (one JSON object per line).
+  const seenResults = new Map<number, PatternValidationResult>();
+  for (const line of (result.stdout ?? "").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const obj = JSON.parse(line) as { i: number; ok: boolean; reason?: string };
+      seenResults.set(obj.i, { ok: obj.ok, reason: obj.reason });
+    } catch {
+      /* skip malformed line */
+    }
+  }
+
+  const timedOut = result.signal === "SIGTERM" || result.signal === "SIGKILL";
+
+  for (let i = 0; i < toCheckRedos.length; i++) {
+    const p = toCheckRedos[i]!;
+    const r = seenResults.get(i);
+    if (r) {
+      if (r.ok) valid.push(p);
+      else invalid.push({ pattern: p, reason: r.reason ?? "unknown" });
+    } else {
+      // No result for this pattern: either the worker died on this
+      // pattern (likeliest culprit on timeout) or output was truncated.
+      const reason = timedOut
+        ? "strict validation timed out on this pattern (likely catastrophic backtracking)"
+        : "strict validation produced no result";
+      invalid.push({ pattern: p, reason });
+    }
+  }
+  return { valid, invalid };
+}
+
+/**
+ * Validate that a combined alternation regex is within the size cap.
+ * Used by render and the deny-set computation as a safety net.
+ */
+export function validateCombinedSize(combined: string): PatternValidationResult {
+  if (Buffer.byteLength(combined, "utf8") > MAX_COMBINED_BYTES) {
+    return {
+      ok: false,
+      reason: `combined regex exceeds ${MAX_COMBINED_BYTES} bytes`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * SECURITY WARNING — adversary input.
+ *
+ * `isInTimeBudget` (and therefore the non-strict {@link validatePattern}
+ * default that calls it) is **not** a preemptive ReDoS guard. Node's
+ * regex engine has no timeout; this function runs the pattern in-process
+ * against a stress input and measures wall-clock elapsed time *after* it
+ * returns. A genuinely catastrophic pattern can hang the event loop for
+ * seconds-to-minutes before the timer reading even runs, during which
+ * nothing else in the process makes progress.
+ *
+ * As a consequence, the non-strict {@link validatePattern} **must not**
+ * be called on adversary-controlled input. Use it only for marker
+ * patterns the operator has authored (registry / `engagements.yaml`),
+ * which are trusted-by-policy.
+ *
+ * For any path that takes pattern strings from outside that trust
+ * boundary — third-party config, network input, future MCP tool input —
+ * use the strict mode of {@link validatePatterns} (`{ strict: true }`),
+ * which spawns a subprocess that the parent can preemptively kill on
+ * timeout via `SIGTERM`/`SIGKILL`.
+ */
+function isInTimeBudget(pattern: string, stressLength: number, budgetMs: number): boolean {
+  // Best-effort time-bounded check. Node has no preemptive regex timeout, so
+  // we rely on the regex engine being well-behaved enough that 'a'-fuzzing
+  // against a pathological pattern still returns within seconds (not hours).
+  // For genuinely catastrophic patterns this may exceed the budget by a
+  // small multiple, which is still survivable. The check exists to flag
+  // patterns that show signs of being problematic; it does not guarantee
+  // safety against an adversary who controls pattern input.
+  const re = new RegExp(pattern, "i");
+  const stress = "a".repeat(stressLength);
+  const start = Date.now();
+  try {
+    re.test(stress);
+  } catch {
+    return false;
+  }
+  const elapsed = Date.now() - start;
+  return elapsed <= budgetMs * 10; // generous: 10x to account for noisy CI
+}

package/src/registry-mutate.test.ts

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { describe, it, before, after, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { addMarkerPattern, addMarkerPatterns } from "./registry-mutate.js";
+import {
+  EngagementNotFoundError,
+  PatternValidationError,
+} from "./exceptions.js";
+
+let tmp: string;
+let home: string;
+let registryPath: string;
+
+const STUB = `\
+schemaVersion: 2
+always_block: []
+engagements:
+  - id: foo-corp
+    name: Foo Corp
+    started: 2026-01-01
+    markers: [\\bfoo\\b]
+  - id: bar-co
+    name: Bar Co
+    started: 2026-01-15
+    markers: []
+`;
+
+before(() => {
+  tmp = mkdtempSync(join(tmpdir(), "repo-aegis-registry-mutate-"));
+  home = join(tmp, "home");
+  registryPath = join(home, "engagements.yaml");
+});
+
+after(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  rmSync(home, { recursive: true, force: true });
+  mkdirSync(join(home, "markers"), { recursive: true });
+  mkdirSync(join(home, "state"), { recursive: true });
+  writeFileSync(registryPath, STUB);
+  process.env["REPO_AEGIS_HOME"] = home;
+});
+
+describe("addMarkerPattern — happy path", () => {
+  it("appends a single pattern and renders markers", () => {
+    const result = addMarkerPattern("bar-co", "\\bbar-co\\b", { registryPath });
+    assert.deepEqual(result.added, ["\\bbar-co\\b"]);
+    assert.deepEqual(result.skipped, []);
+    const reg = readFileSync(registryPath, "utf8");
+    assert.match(reg, /\\bbar-co\\b/);
+  });
+
+  it("idempotent — re-adding the same pattern is a no-op", () => {
+    addMarkerPattern("bar-co", "\\bbar-co\\b", { registryPath });
+    const r2 = addMarkerPattern("bar-co", "\\bbar-co\\b", { registryPath });
+    assert.deepEqual(r2.added, []);
+    assert.deepEqual(r2.skipped, ["\\bbar-co\\b"]);
+  });
+});
+
+describe("addMarkerPatterns — bulk add", () => {
+  it("appends multiple patterns with mixed new/duplicate handling", () => {
+    addMarkerPattern("bar-co", "\\bbar-co\\b", { registryPath });
+    const result = addMarkerPatterns(
+      "bar-co",
+      ["\\bbar-co\\b", "\\bbar\\.example\\b", "\\bBC-[0-9]+\\b"],
+      { registryPath },
+    );
+    assert.equal(result.added.length, 2);
+    assert.equal(result.skipped.length, 1);
+    assert.ok(result.added.includes("\\bbar\\.example\\b"));
+    assert.ok(result.added.includes("\\bBC-[0-9]+\\b"));
+  });
+});
+
+describe("addMarkerPatterns — error paths", () => {
+  it("throws EngagementNotFoundError for unknown id", () => {
+    assert.throws(
+      () => addMarkerPattern("nonexistent", "\\bfoo\\b", { registryPath }),
+      EngagementNotFoundError,
+    );
+  });
+
+  it("throws PatternValidationError on invalid regex", () => {
+    assert.throws(
+      () => addMarkerPattern("foo-corp", "(?<unclosed", { registryPath }),
+      PatternValidationError,
+    );
+  });
+
+  it("validates ALL patterns before mutating any", () => {
+    // First pattern good, second bad — registry must be unchanged.
+    const before = readFileSync(registryPath, "utf8");
+    assert.throws(
+      () =>
+        addMarkerPatterns("bar-co", ["\\bgood\\b", "(?<bad"], { registryPath }),
+      PatternValidationError,
+    );
+    const after = readFileSync(registryPath, "utf8");
+    assert.equal(before, after);
+  });
+});
+
+describe("addMarkerPatterns — [SEC M-3] lock scope", () => {
+  it("two parallel calls on different engagements both succeed without lost updates", async () => {
+    // Run two adds concurrently — using Promise.all as a parallel-ish
+    // proxy. The lock is sync (withLockSync), so they will serialise via
+    // proper-lockfile. Asserting both sets land is the correctness goal.
+    const a = Promise.resolve().then(() =>
+      addMarkerPatterns("foo-corp", ["\\bnew-foo\\b"], { registryPath }),
+    );
+    const b = Promise.resolve().then(() =>
+      addMarkerPatterns("bar-co", ["\\bnew-bar\\b"], { registryPath }),
+    );
+    const [ra, rb] = await Promise.all([a, b]);
+    assert.deepEqual(ra.added, ["\\bnew-foo\\b"]);
+    assert.deepEqual(rb.added, ["\\bnew-bar\\b"]);
+    const reg = readFileSync(registryPath, "utf8");
+    assert.match(reg, /\\bnew-foo\\b/);
+    assert.match(reg, /\\bnew-bar\\b/);
+  });
+});