@cosmicdrift/kumiko-guards 0.387.0 → 0.389.0

package/README.md

@@ -77,8 +77,9 @@ workspace it runs a tracked `scripts/check-wt.sh` if present, otherwise the
 worktree's own `package.json` scripts `typecheck`, `lint`, `test`, and
 `test:dom` (whichever are declared), directly in the worktree — the parent's
 `bun check` would otherwise check the main checkout instead. There is no
-bypass switch. A `check-wt.sh` that wraps this hook sets `KUMIKO_CHECK_WT=1`
-so the hook does not call it again.
+bypass switch. A `check-wt.sh` that wraps this hook (via `exec` or as a child
+process) is recognised by process ancestry, so the hook does not call it
+again; an exported variable cannot skip it.
 
 Extension point: a tracked, executable `scripts/pre-push-extra.sh` runs
 before the main check in every branch (worktree, parent-scoped, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.387.0",
+  "version": "0.389.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -51,7 +51,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.387.0"
+    "@cosmicdrift/kumiko-framework": "0.389.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -59,6 +59,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.387.0"
+    "@cosmicdrift/kumiko-framework": "0.389.0"
   }
 }

package/src/_lib/agent-docs.ts

@@ -336,14 +336,21 @@ function renderExamplesIndex(recipes: readonly Recipe[]): string {
   );
 }
 
+const RECIPE_SKIPPED_DIRS = new Set(["node_modules", "screenshots", "dist"]);
+const GENERATED_FILE = /\.generated\./;
+
 function listSourceFiles(dir: string, prefix = ""): string[] {
   if (!existsSync(dir)) return [];
   const found: string[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
     if (entry.isDirectory()) {
-      found.push(...listSourceFiles(join(dir, entry.name), rel));
-    } else if (SOURCE_EXTENSIONS.some((extension) => entry.name.endsWith(extension))) {
+      if (!RECIPE_SKIPPED_DIRS.has(entry.name))
+        found.push(...listSourceFiles(join(dir, entry.name), rel));
+    } else if (
+      SOURCE_EXTENSIONS.some((extension) => entry.name.endsWith(extension)) &&
+      !GENERATED_FILE.test(entry.name)
+    ) {
       found.push(rel);
     }
   }
@@ -362,13 +369,11 @@ function renderRecipe(recipe: Recipe): string {
   if (existsSync(readmePath)) {
     parts.push(`## README\n\n${readFileSync(readmePath, "utf-8").replace(/\r\n/g, "\n").trim()}`);
   }
-  const sourceBlocks = listSourceFiles(join(recipe.dir, "src")).map((rel) => {
-    const content = readFileSync(join(recipe.dir, "src", rel), "utf-8")
-      .replace(/\r\n/g, "\n")
-      .trimEnd();
+  const sourceBlocks = listSourceFiles(recipe.dir).map((rel) => {
+    const content = readFileSync(join(recipe.dir, rel), "utf-8").replace(/\r\n/g, "\n").trimEnd();
     const fence = fenceFor(content);
     const language = rel.endsWith(".tsx") ? "tsx" : "ts";
-    return `### src/${rel}\n\n${fence}${language}\n${content}\n${fence}`;
+    return `### ${rel}\n\n${fence}${language}\n${content}\n${fence}`;
   });
   if (sourceBlocks.length > 0) parts.push(`## Source files\n\n${sourceBlocks.join("\n\n")}`);
   return finishFile(`${RECIPES_REL}/${recipe.slug}`, parts.join("\n\n"));

package/src/_lib/guards-doc.ts

@@ -34,10 +34,13 @@ function headerComment(source: string): string {
   return body.join("\n");
 }
 
+// Abbreviations that end in a period but not the sentence.
+const SENTENCE_END_RE = /(?<!\be\.g|\bi\.e|\bresp|\bz\. B|\bvs|\betc)\.(\s|$)/;
+
 function purposeOf(source: string): string {
   const paragraph = headerComment(source).split(/\n\s*\n/)[0] ?? "";
   const flat = paragraph.replace(/\s+/g, " ").trim();
-  const sentenceEnd = flat.search(/\.(\s|$)/);
+  const sentenceEnd = flat.search(SENTENCE_END_RE);
   const sentence = sentenceEnd === -1 ? flat : flat.slice(0, sentenceEnd + 1);
   return sentence.replace(/\|/g, "\\|") || "-";
 }

package/src/_lib/roots.ts

@@ -183,14 +183,18 @@ function isDerivedAppFallback(root: RepoRoot): boolean {
   return root.manifestSource === "derived" && root.kind === "app";
 }
 
-/** The repo of the nearest `kumiko.json` at or above `start`, which is the app root in a git tree that holds several. */
-function nearestManifestRepo(start: string): RepoRoot | undefined {
+/**
+ * The repo of the nearest `kumiko.json` at or above `start`, which is the app root in a git tree
+ * that holds several. The walk stops at the git toplevel, so a foreign `kumiko.json` further up
+ * (workspace parent, home dir) never captures a repo that has none of its own.
+ */
+function nearestManifestRepo(start: string, stopAt: string | undefined): RepoRoot | undefined {
   for (let curr = start; ; curr = dirname(curr)) {
     if (existsSync(join(curr, REPO_MANIFEST_FILE))) {
       const repo = repoAt(curr);
       if (repo) return repo;
     }
-    if (curr === dirname(curr)) return undefined;
+    if (curr === stopAt || curr === dirname(curr)) return undefined;
   }
 }
 
@@ -210,9 +214,9 @@ function nearestManifestRepo(start: string): RepoRoot | undefined {
  */
 export function findLocalRepo(cwd: string = process.cwd()): RepoRoot | undefined {
   const start = resolve(cwd);
-  const fromManifest = nearestManifestRepo(start);
-  if (fromManifest) return fromManifest;
   const toplevel = gitToplevelOf(start);
+  const fromManifest = nearestManifestRepo(start, toplevel);
+  if (fromManifest) return fromManifest;
   const fromGit = toplevel !== undefined ? repoAt(toplevel) : undefined;
   if (fromGit) return fromGit;
   let fallback: RepoRoot | undefined;

package/src/_lib/run-slots.ts

@@ -1,11 +1,20 @@
-import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import {
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
 const DEFAULT_SLOTS = 2;
 const POLL_INTERVAL_MS = 1000;
 const PIDLESS_ORPHAN_AGE_MS = 60_000;
 // Upper bound against pid reuse after SIGKILL/OOM: a reused pid would otherwise hold the slot forever.
-const MAX_SLOT_AGE_MS = 15 * 60_000;
+// The slot mtime is never refreshed, so this must exceed the longest legitimate guard run.
+const MAX_SLOT_AGE_MS = 2 * 60 * 60_000;
 const PID_FILE = "pid";
 
 type Environment = Readonly<Record<string, string | undefined>>;
@@ -31,13 +40,19 @@ export function resolveGuardSlotCount(environment: Environment): number {
   return Number(raw);
 }
 
+function errorCode(error: unknown): string {
+  return error instanceof Error && "code" in error && typeof error.code === "string"
+    ? error.code
+    : "unknown";
+}
+
 function defaultIsPidAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
     return true;
   } catch (error) {
     // EPERM means the process exists but belongs to another user.
-    return error instanceof Error && "code" in error && error.code === "EPERM";
+    return errorCode(error) === "EPERM";
   }
 }
 
@@ -73,12 +88,6 @@ function isOrphanedSlot(
   return ageMs > PIDLESS_ORPHAN_AGE_MS;
 }
 
-function errorCode(error: unknown): string {
-  return error instanceof Error && "code" in error && typeof error.code === "string"
-    ? error.code
-    : "unknown";
-}
-
 function tryClaimSlot(slotPath: string, pid: number): boolean {
   try {
     mkdirSync(slotPath);
@@ -148,6 +157,25 @@ function defaultSlotsDir(): string {
   return uid === undefined ? "/tmp/kumiko-guard-slots" : `/tmp/kumiko-guard-slots-${uid}`;
 }
 
+// The default dir lives in a shared /tmp: another local user could pre-create it (or swap in a
+// symlink) to hold slots forever or redirect the pid write.
+function assertPrivateOwnDirectory(dir: string): void {
+  const uid = process.getuid?.();
+  // skip: no uid to compare against on this platform.
+  if (uid === undefined) return;
+  const stats = lstatSync(dir);
+  if (
+    stats.isSymbolicLink() ||
+    !stats.isDirectory() ||
+    stats.uid !== uid ||
+    (stats.mode & 0o077) !== 0
+  ) {
+    throw Object.assign(new Error(`${dir} is not a private directory owned by the current user`), {
+      code: "EUNSAFE",
+    });
+  }
+}
+
 export function acquireGuardRunSlot(options: GuardRunSlotOptions = {}): () => void {
   const slotCount = resolveGuardSlotCount(options.environment ?? process.env);
   if (slotCount === 0) return () => {};
@@ -164,7 +192,8 @@ export function acquireGuardRunSlot(options: GuardRunSlotOptions = {}): () => vo
   for (;;) {
     let slotPath: string | undefined;
     try {
-      mkdirSync(slotsDir, { recursive: true });
+      mkdirSync(slotsDir, { recursive: true, mode: 0o700 });
+      assertPrivateOwnDirectory(slotsDir);
       slotPath = claimFreeSlot(slotsDir, slotCount, pid, isPidAlive, now);
     } catch (error) {
       // A throttle must never block the push: fail open.

package/src/_lib/security-audit.ts

@@ -35,6 +35,7 @@ export type SecurityEvaluation = {
   readonly blocking: AuditAdvisory[];
   readonly warnings: AuditAdvisory[];
   readonly suppressed: AuditAdvisory[];
+  readonly usedExceptions: SecurityException[];
   readonly counts: Record<Severity, number>;
 };
 
@@ -90,12 +91,20 @@ function matchesAdvisory(exceptionAdvisory: string, advisoryId: string, url: str
 function findSecurityException(
   advisory: AuditAdvisory,
   exceptions: readonly SecurityException[],
+  nowMs: number,
 ): SecurityException | undefined {
-  return exceptions.find(
+  const matching = exceptions.filter(
     (ex) =>
       matchesAdvisory(ex.advisory, advisory.advisoryId, advisory.url) &&
       (ex.package === "*" || matchesPackageName(ex.package, advisory.package)),
   );
+  // An expired earlier entry (e.g. bundled) must not shadow a valid later one (e.g. repo-level).
+  return matching.find((ex) => isSecurityExceptionActive(ex, nowMs)) ?? matching[0];
+}
+
+// isExceptionValid() treats a missing expiry as "forever valid", which is wrong for security: such an exception would suppress a critical permanently.
+function isSecurityExceptionActive(exception: SecurityException, nowMs: number): boolean {
+  return Boolean(exception.expires) && isExceptionValid(exception.expires, nowMs).valid;
 }
 
 export function evaluateSecurity(
@@ -107,18 +116,16 @@ export function evaluateSecurity(
   const blocking: AuditAdvisory[] = [];
   const warnings: AuditAdvisory[] = [];
   const suppressed: AuditAdvisory[] = [];
+  const usedExceptions = new Set<SecurityException>();
 
   for (const advisory of advisories) {
     counts[advisory.severity] += 1;
-    const exception = findSecurityException(advisory, exceptions);
-    // isExceptionValid() treats a missing expiry as "forever valid", which is wrong for security: such an exception would suppress a critical permanently.
-    const covered =
-      exception !== undefined &&
-      Boolean(exception.expires) &&
-      isExceptionValid(exception.expires, nowMs).valid;
+    const exception = findSecurityException(advisory, exceptions, nowMs);
+    const covered = exception !== undefined && isSecurityExceptionActive(exception, nowMs);
 
     if (covered) {
       suppressed.push(advisory);
+      usedExceptions.add(exception);
     } else if (FAIL_SEVERITIES.has(advisory.severity)) {
       blocking.push(advisory);
     } else if (advisory.severity === "moderate") {
@@ -126,7 +133,7 @@ export function evaluateSecurity(
     }
   }
 
-  return { blocking, warnings, suppressed, counts };
+  return { blocking, warnings, suppressed, usedExceptions: [...usedExceptions], counts };
 }
 
 /** True when `bytes` starts with the gzip magic header (1f 8b). */

package/src/changes.json

@@ -1,4 +1,54 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "Guard against hand-made event and membership SQL in tests",
+    "detail": "Flags INSERT INTO / UPDATE kumiko_events and CREATE TABLE read_tenant_memberships in test files. Seed through append() or runSeedWritesAt() and unsafeCreateEntityTable with seedRow instead. Perf bulk seeds and the ordering tests that hold a transaction open are allowlisted."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "pre-push re-entry detection no longer an env switch",
+    "detail": "Before delegating to a tracked scripts/check-wt.sh the hook records its own PID in KUMIKO_CHECK_WT_OWNER and treats a run as re-entry only when that PID is an ancestor of the current process, whether check-wt.sh execs or spawns the hook. KUMIKO_CHECK_WT=1 is ignored, so it cannot skip check-wt.sh; wrappers that still set it need no change."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Complexity hard cap 40, thin-wrapper guard skips typed table slots",
+    "detail": "A function above complexity 40 in the repo's own files fails the complexity guard, independent of the complexity baseline and of the complexity-budget tag, also with --no-baseline. The thin-wrapper guard skips a function that is a value of an object literal with a declared type or a satisfies check, inline or referenced by name, because the table fixes its signature.",
+    "migration": "Split every function above complexity 40 before the bump; the complexity-budget tag and the baseline do not cover it. `bun check-complexity.ts --all --no-baseline` lists them under \"Above hard cap\"."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Complexity hard cap, --all, file-size threshold 1200",
+    "detail": "Functions with complexity above 60 are a violation in the repo's own files, independent of the complexity baseline and of the complexity-budget tag, also with --no-baseline. The report lists them in their own section. `bun check-complexity.ts --all` prints all hotspots in the standalone run, --write-baseline and --no-baseline. The file-size guard now freezes files above 1200 lines instead of 2000.",
+    "migration": "Consumer repos without a complexity baseline get a hard error for functions above complexity 60; split them. File size stays a warning there without a baseline; with one, files between 1200 and 2000 lines count as new hits until `--write-baseline` is run."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Harden guards infrastructure (pre-push scan range, slot dir, root walk)",
+    "detail": "The pre-push secret scan covers every pushed ref instead of HEAD. The guard slot directory is created 0700 and ignored when not private; slot max age is 2 h. findLocalRepo no longer picks up a kumiko.json above the git root. Runtime-isolation keeps web/dev/ files as client."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Guards report fewer false results",
+    "detail": "The import-extensions guard now also checks import types, mock.module and template-literal specifiers. The comment-issue-ref-only guard no longer treats file names like round2.ts as plan labels. The direct-entity-writes guard recognises r.entity registrations with a constant or shorthand name, reports direct writes on package catalog tables even when the scope has no own ES tables, keeps receiver text on one line and names the installed kumiko-guards bin in its catalog rewrite hint. The app-feature-structure guard no longer tells dev/ and scripts/ files to move under web/, and the bundled license exceptions drop the stale first-party and create-kumiko-app entries."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Dependency exceptions, timeout and boundary guards no longer miss or invent findings",
+    "detail": "A renewed license or security exception now wins over an expired earlier one, license exceptions must match the package license and a real semver range, and only exceptions that suppressed an advisory block on near expiry. The test-timeouts guard also flags union-typed and untyped timeout arguments, the renderer-boundaries guard covers headless and live imports, import-extensions ignores real .js files without a .ts sibling, and the generated agent examples now include bin, e2e, seeds and scripts files."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Guards --explain uses the injectable project builder",
+    "detail": "runGuardsCli builds the explain project through the same buildProject dependency as the check run, which lets tests assert that --explain takes no guard run slot without parsing the whole repository."
+  },
   {
     "version": "0.387.0",
     "type": "improvement",

package/src/check-complexity.ts

@@ -21,12 +21,14 @@
  *
  * Opt-out: `// kumiko-lint-ignore complexity-budget <reason>` on the function
  * line, the line above, or (for JSDoc-documented functions) the line above
- * the JSDoc block.
+ * the JSDoc block. The opt-out does NOT hold above HARD_COMPLEXITY_CAP: such a
+ * function in the repo's own files always fails, regardless of baseline or tag.
  *
  * Usage:
  *   bun guards/check-complexity.ts                  # compare against baseline
  *   bun guards/check-complexity.ts --write-baseline # rewrite baseline
  *   bun guards/check-complexity.ts --no-baseline    # skip comparison
+ *   bun guards/check-complexity.ts --all            # list every hotspot, not the first 30
  */
 
 import * as path from "node:path";
@@ -58,6 +60,7 @@ const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$)/;
 
 const COMPLEXITY_THRESHOLD = 15;
 const MAX_REPORTED = 30;
+export const HARD_COMPLEXITY_CAP = 40;
 const BUDGET_TAG = "kumiko-lint-ignore complexity-budget";
 
 const FUNCTION_KINDS = [
@@ -152,26 +155,49 @@ export function computeComplexity(fn: Node): number {
   return complexity;
 }
 
-export function collectHotspots(
+export interface FunctionMetric extends Hotspot {
+  budgetTagged: boolean;
+}
+
+// Single walk per file: complexity is computed once and feeds both the
+// hotspot list and the hard cap.
+export function collectFunctionMetrics(
   sf: SourceFile,
   roots: readonly RepoRoot[] = resolveRepoRoots(),
-): Hotspot[] {
+): FunctionMetric[] {
   const file = relFromRepoRoot(sf.getFilePath(), roots);
-  const hotspots: Hotspot[] = [];
+  const metrics: FunctionMetric[] = [];
   for (const kind of FUNCTION_KINDS) {
     for (const fn of sf.getDescendantsOfKind(kind)) {
       const complexity = computeComplexity(fn);
       if (complexity < COMPLEXITY_THRESHOLD) continue;
-      if (hasBudgetTag(fn)) continue;
-      hotspots.push({
+      metrics.push({
         file,
         line: fn.getStartLineNumber(),
         name: functionName(fn),
         complexity,
+        budgetTagged: hasBudgetTag(fn),
       });
     }
   }
-  return hotspots;
+  return metrics;
+}
+
+export function hotspotsOf(metrics: readonly FunctionMetric[]): Hotspot[] {
+  return metrics
+    .filter((m) => !m.budgetTagged)
+    .map(({ file, line, name, complexity }) => ({ file, line, name, complexity }));
+}
+
+export function capBreachesOf(metrics: readonly FunctionMetric[]): FunctionMetric[] {
+  return metrics.filter((m) => m.complexity > HARD_COMPLEXITY_CAP && isLocalFinding(m));
+}
+
+export function collectHotspots(
+  sf: SourceFile,
+  roots: readonly RepoRoot[] = resolveRepoRoots(),
+): Hotspot[] {
+  return hotspotsOf(collectFunctionMetrics(sf, roots));
 }
 
 const BASELINE_FILE = ".kumiko-complexity-baseline.json";
@@ -199,26 +225,37 @@ function scan(
   roots: readonly RepoRoot[] = resolveRepoRoots(),
 ): {
   hotspots: Hotspot[];
+  capBreaches: FunctionMetric[];
   scanned: number;
 } {
-  const hotspots: Hotspot[] = [];
+  const metrics: FunctionMetric[] = [];
   let scanned = 0;
   for (const sf of files) {
     if (EXCLUDE.test(sf.getFilePath())) continue;
     scanned++;
-    hotspots.push(...collectHotspots(sf, roots));
+    metrics.push(...collectFunctionMetrics(sf, roots));
   }
-  hotspots.sort((a, b) => b.complexity - a.complexity);
-  return { hotspots, scanned };
+  const hotspots = hotspotsOf(metrics).sort((a, b) => b.complexity - a.complexity);
+  const capBreaches = capBreachesOf(metrics).sort((a, b) => b.complexity - a.complexity);
+  return { hotspots, capBreaches, scanned };
 }
 
-function report(hotspots: readonly Hotspot[], scanned: number): void {
+function report(
+  hotspots: readonly Hotspot[],
+  scanned: number,
+  capBreaches: readonly FunctionMetric[],
+  reportLimit: number,
+): void {
   console.log(`Complexity Check: ${scanned} files checked.`);
   console.log(`  Hotspots (complexity >= ${COMPLEXITY_THRESHOLD}): ${hotspots.length}`);
+  console.log(`  Above hard cap (complexity > ${HARD_COMPLEXITY_CAP}): ${capBreaches.length}`);
+  for (const b of capBreaches) {
+    console.log(`    CAP ${b.file}:${b.line}  ${b.name}()  complexity=${b.complexity}`);
+  }
   if (hotspots.length === 0) {
     console.log("  Nothing to report.");
   } else {
-    const shown = hotspots.slice(0, MAX_REPORTED);
+    const shown = hotspots.slice(0, reportLimit);
     for (const h of shown) {
       console.log(`    ${h.file}:${h.line}  ${h.name}()  complexity=${h.complexity}`);
     }
@@ -231,12 +268,25 @@ function report(hotspots: readonly Hotspot[], scanned: number): void {
   }
 }
 
+type Ratchet = ReturnType<typeof baselineRatchet>;
+
 const complexityBaseline = baselineRatchet({
   file: path.join(ROOT, BASELINE_FILE),
   formatVersion: BASELINE_FORMAT_VERSION,
   unit: "Complexity-Hotspot(s)",
 });
 
+function capViolations(capBreaches: readonly FunctionMetric[]): GuardViolation[] {
+  return capBreaches.map((b) => ({
+    file: b.file,
+    line: b.line,
+    neverFrozen: true,
+    message:
+      `${b.name}() has complexity ${b.complexity}, above the hard cap of ${HARD_COMPLEXITY_CAP}. ` +
+      `A "${BUDGET_TAG}" tag and the baseline do not apply above the cap — split the function.`,
+  }));
+}
+
 // `scan` sorts by complexity descending, so the first hit for a file is its
 // worst function — the one the violation should point at, not whichever
 // hotspot happens to come first in the file.
@@ -244,9 +294,9 @@ export function resolveHotspotLine(hotspots: readonly Hotspot[], file: string):
   return hotspots.find((h) => h.file === file)?.line ?? 1;
 }
 
-function checkBaseline(scanned: readonly Hotspot[]): GuardViolation[] {
+function checkBaseline(scanned: readonly Hotspot[], ratchet: Ratchet): GuardViolation[] {
   const hotspots = localHotspots(scanned);
-  return complexityBaseline.check(
+  return ratchet.check(
     countHotspotsByFile(hotspots),
     `Split the function, or allow it with "// ${BUDGET_TAG} <reason>".`,
     {
@@ -256,18 +306,21 @@ function checkBaseline(scanned: readonly Hotspot[]): GuardViolation[] {
   );
 }
 
-function analyse(
+export function analyse(
   files: readonly SourceFile[],
   roots: readonly RepoRoot[],
   compareBaseline: boolean,
+  options: { ratchet?: Ratchet; reportLimit?: number } = {},
 ): GuardOutcome {
-  const { hotspots, scanned } = scan(files, roots);
-  report(hotspots, scanned);
+  const { ratchet = complexityBaseline, reportLimit = MAX_REPORTED } = options;
+  const { hotspots, capBreaches, scanned } = scan(files, roots);
+  report(hotspots, scanned, capBreaches, reportLimit);
+  const hardViolations = capViolations(capBreaches);
   if (!compareBaseline) {
     console.log("  Baseline comparison skipped (--no-baseline).");
-    return { violations: [] };
+    return { violations: hardViolations };
   }
-  return { violations: checkBaseline(hotspots) };
+  return { violations: [...hardViolations, ...checkBaseline(hotspots, ratchet)] };
 }
 
 export const guard: AstGuard = {
@@ -279,8 +332,8 @@ export const guard: AstGuard = {
   hint: 'after a deliberate change: `kumiko-guards guards --write-baseline --guard="Complexity Check"`',
   run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true),
   writeBaseline: (files) => {
-    const { hotspots, scanned } = scan(files);
-    report(hotspots, scanned);
+    const { hotspots, capBreaches, scanned } = scan(files);
+    report(hotspots, scanned, capBreaches, MAX_REPORTED);
     complexityBaseline.write(countHotspotsByFile(localHotspots(hotspots)));
   },
 };
@@ -290,17 +343,23 @@ export const guard: AstGuard = {
 // silently rewrite the baseline.
 if (import.meta.main) {
   const args = process.argv.slice(2);
+  const reportLimit = args.includes("--all") ? Number.POSITIVE_INFINITY : MAX_REPORTED;
   if (args.includes("--write-baseline")) {
     const project = buildSharedProject([guard]);
-    const { hotspots, scanned } = scan(filesForGuard(project, guard));
-    report(hotspots, scanned);
+    const { hotspots, capBreaches, scanned } = scan(filesForGuard(project, guard));
+    report(hotspots, scanned, capBreaches, reportLimit);
     complexityBaseline.write(countHotspotsByFile(localHotspots(hotspots)));
     process.exit(0);
   }
   if (args.includes("--no-baseline")) {
     const project = buildSharedProject([guard]);
-    analyse(filesForGuard(project, guard), resolveRepoRoots(), false);
-    process.exit(0);
+    const { violations } = analyse(filesForGuard(project, guard), resolveRepoRoots(), false, {
+      reportLimit,
+    });
+    process.exit(violations.length > 0 ? 1 : 0);
   }
-  runStandalone(guard);
+  runStandalone({
+    ...guard,
+    run: (files, roots = resolveRepoRoots()) => analyse(files, roots, true, { reportLimit }),
+  });
 }

package/src/check-licenses.ts

@@ -107,14 +107,30 @@ export function loadLicenseExceptions(
   });
 }
 
+function normalizeLicenseId(license: string): string {
+  return license.replace(/[()]/g, "").trim().toUpperCase();
+}
+
+function exceptionMatchesPackage(e: LicenseException, pkg: InstalledPackage): boolean {
+  if (!matchesPackageName(e.package, pkg.name)) return false;
+  // A package without a license field has nothing to contradict the recorded license.
+  if (pkg.license !== null && normalizeLicenseId(e.license) !== normalizeLicenseId(pkg.license)) {
+    return false;
+  }
+  return (
+    e.version === "*" || e.version === pkg.version || Bun.semver.satisfies(pkg.version, e.version)
+  );
+}
+
+// A renewed repo exception must win over an expired bundled one for the same package, so prefer a
+// still-valid match and only fall back to an expired one for the "expired" hint.
 function findException(
   pkg: InstalledPackage,
   exceptions: readonly LicenseException[],
+  nowMs: number,
 ): LicenseException | undefined {
-  return exceptions.find((e) => {
-    if (!matchesPackageName(e.package, pkg.name)) return false;
-    return e.version === "*" || e.version === pkg.version || /^[\^~]/.test(e.version);
-  });
+  const matching = exceptions.filter((e) => exceptionMatchesPackage(e, pkg));
+  return matching.find((e) => isExceptionValid(e.expires, nowMs).valid) ?? matching[0];
 }
 
 function splitExpression(expr: string, operator: "OR" | "AND"): string[] {
@@ -132,9 +148,10 @@ function matchesDenylist(license: string): boolean {
 export function judgeLicense(
   pkg: InstalledPackage,
   exceptions: readonly LicenseException[],
+  nowMs: number = Date.now(),
 ): Verdict {
   const license = pkg.license;
-  const exception = findException(pkg, exceptions);
+  const exception = findException(pkg, exceptions, nowMs);
   if (!license) return { kind: "unknown", raw: null, exception };
 
   const andParts = splitExpression(license, "AND");
@@ -181,7 +198,7 @@ export function evaluateLicenses(
   exceptions: readonly LicenseException[],
   nowMs: number = Date.now(),
 ): LicenseEvaluation {
-  const judged = packages.map((pkg) => ({ pkg, verdict: judgeLicense(pkg, exceptions) }));
+  const judged = packages.map((pkg) => ({ pkg, verdict: judgeLicense(pkg, exceptions, nowMs) }));
   const blocked = judged.filter(
     ({ verdict }) => verdict.kind !== "ok" && !hasValidException(verdict, nowMs),
   );

package/src/check-security.ts

@@ -157,7 +157,8 @@ export async function runSecurityCheck(options: {
   const advisories: AuditAdvisory[] = parseAuditReport(raw);
 
   const evaluation = evaluateSecurity(advisories, exceptions, nowMs);
-  const expiringUrgent = findExpiringSoon(exceptions, EXPIRY_BLOCK_DAYS, nowMs);
+  // Only exceptions that suppressed an advisory in this run block; unused bundled ones must not break consumer CI.
+  const expiringUrgent = findExpiringSoon(evaluation.usedExceptions, EXPIRY_BLOCK_DAYS, nowMs);
   printReport(evaluation, exceptions, expiringUrgent, nowMs);
 
   if (options.reportOnly) return 0;