@syv-ai/rulecast 0.3.0 → 0.4.0

package/dist/{chunk-7KUPYT35.js → chunk-WUFU4LW2.js}

@@ -1,10 +1,10 @@
 import {
-  BACKLOG_HINT,
   DeadlineError,
   LLM_PROVIDERS,
   VERSION,
   compileFilter,
   compileRule,
+  deliveryCost,
   detectorCacheDir,
   diskCache,
   emptyDelivery,
@@ -24,7 +24,7 @@ import {
   sectionRange,
   sectionText,
   templateBindings
-} from "./chunk-HZUATJ53.js";
+} from "./chunk-DQUCE2IK.js";
 
 // src/core/config/load.ts
 import { readFile } from "fs/promises";
@@ -59,6 +59,8 @@ var ruleKeys = {
    */
   scope: z.enum(RULE_SCOPES).optional(),
   refuse_write: z.boolean().optional(),
+  /** false: compiled and listed, selected for nothing. The way to switch a catalog rule off without deleting it. */
+  enabled: z.boolean().optional(),
   detect: z.record(z.unknown()).refine((value) => Object.keys(value).length === 1, "must name exactly one detector").optional(),
   message: z.string().optional(),
   context: z.array(referenceInputSchema).optional(),
@@ -150,13 +152,15 @@ function readConfigData(root) {
 }
 function parseConfig(data) {
   const result = configSchema.safeParse(data);
-  if (!result.success) return { ok: false, message: `${CONFIG_FILE}: ${formatZodError(result.error)}` };
+  if (!result.success) {
+    return { ok: false, message: `${CONFIG_FILE}: ${formatZodError(result.error, { schema: configSchema })}` };
+  }
   return { ok: true, value: result.data };
 }
-async function readManifest(dir) {
-  const loaded = await readYamlFile(path.join(dir, MANIFEST_FILE));
+async function readManifest(dir, file = path.join(dir, MANIFEST_FILE)) {
+  const loaded = await readYamlFile(file);
   if (!loaded.ok) return loaded;
-  if (!Array.isArray(loaded.value)) return { ok: false, message: `${MANIFEST_FILE}: must be a list of rules` };
+  if (!Array.isArray(loaded.value)) return { ok: false, message: `${path.basename(file)}: must be a list of rules` };
   return { ok: true, value: loaded.value };
 }
 
@@ -197,6 +201,7 @@ function debugLogger(stateDir, now = () => /* @__PURE__ */ new Date()) {
 
 // src/core/compile/project.ts
 import { readFile as readFile2 } from "fs/promises";
+import path3 from "path";
 function diagnosticText(diagnostic) {
   const rule = diagnostic.rule ? ` (${diagnostic.rule})` : "";
   return `${diagnostic.source}${rule}: ${diagnostic.message}`;
@@ -274,7 +279,7 @@ async function compile(options) {
       }
       for (const raw of entry.rules) {
         const rule = ruleSchema.safeParse(raw);
-        if (!rule.success) error(CONFIG_FILE, idOf(raw), formatZodError(rule.error));
+        if (!rule.success) error(CONFIG_FILE, idOf(raw), formatZodError(rule.error, { schema: ruleSchema }));
         else await add({ data: rule.data, source: "local", contextRoot: project }, CONFIG_FILE);
       }
       continue;
@@ -311,7 +316,7 @@ async function compile(options) {
     for (const raw of entry.rules) {
       const override = overrideSchema.safeParse(raw);
       if (!override.success) {
-        error(CONFIG_FILE, idOf(raw), formatZodError(override.error));
+        error(CONFIG_FILE, idOf(raw), formatZodError(override.error, { schema: overrideSchema }));
         continue;
       }
       const { id } = override.data;
@@ -322,7 +327,7 @@ async function compile(options) {
       }
       const base = ruleSchema.safeParse(candidates[0]);
       if (!base.success) {
-        error(source, id, `manifest: ${formatZodError(base.error)}`);
+        error(source, id, formatZodError(base.error, { prefix: "manifest", schema: ruleSchema }));
         continue;
       }
       const data2 = { ...base.data, ...override.data };
@@ -337,12 +342,13 @@ async function compile(options) {
   );
   return { root, config, rules, diagnostics };
 }
-async function compileManifest(dir, registry) {
-  const manifest = await readManifest(dir);
+async function compileManifest(dir, registry, file = path3.join(dir, MANIFEST_FILE)) {
+  const source = path3.basename(file);
+  const manifest = await readManifest(dir, file);
   if (!manifest.ok) {
     return {
       rules: [],
-      diagnostics: [{ source: MANIFEST_FILE, rule: null, message: manifest.message, level: "error" }]
+      diagnostics: [{ source, rule: null, message: manifest.message, level: "error" }]
     };
   }
   const diagnostics = [];
@@ -351,18 +357,23 @@ async function compileManifest(dir, registry) {
   for (const raw of manifest.value) {
     const rule = ruleSchema.safeParse(raw);
     if (!rule.success) {
-      diagnostics.push({ source: MANIFEST_FILE, rule: idOf(raw), message: formatZodError(rule.error), level: "error" });
+      diagnostics.push({
+        source,
+        rule: idOf(raw),
+        message: formatZodError(rule.error, { schema: ruleSchema }),
+        level: "error"
+      });
       continue;
     }
     const result = await compileRule({ data: rule.data, source: "local", contextRoot: { dir, label: null } }, context);
     if (typeof result === "string") {
       diagnostics.push({
-        source: MANIFEST_FILE,
+        source,
         rule: rule.data.alias ?? rule.data.id,
         message: result,
         level: "error"
       });
-    } else compiled.push({ rule: result, source: MANIFEST_FILE });
+    } else compiled.push({ rule: result, source });
   }
   const rules = uniqueRules(compiled, diagnostics, (id) => `rule "${id}" is defined more than once`);
   return { rules, diagnostics };
@@ -371,7 +382,7 @@ async function compileManifest(dir, registry) {
 // src/core/detection/select.ts
 function selectDetectorRules(rules, event, files, disabled) {
   return rules.filter(
-    (rule) => isDetectorRule(rule) && rule.stages.includes(event) && !disabled.has(rule.id)
+    (rule) => isDetectorRule(rule) && rule.enabled && rule.stages.includes(event) && !disabled.has(rule.id)
   ).map((rule) => ({ rule, files: files.filter((file) => rule.matches(file)) })).filter((selection) => selection.files.length > 0);
 }
 function rulesOfKind(rules, kind) {
@@ -379,7 +390,7 @@ function rulesOfKind(rules, kind) {
 }
 function selectTouchRules(rules, files, touched, disabled) {
   return rules.filter(
-    (rule) => rule.stages.includes("touch") && !touched.has(rule.id) && !disabled.has(rule.id) && files.some((file) => rule.matches(file))
+    (rule) => rule.enabled && rule.stages.includes("touch") && !touched.has(rule.id) && !disabled.has(rule.id) && files.some((file) => rule.matches(file))
   );
 }
 
@@ -429,7 +440,7 @@ async function checkDetectors(options) {
 import { randomUUID } from "crypto";
 import { existsSync as existsSync2 } from "fs";
 import { mkdir as mkdir2, rename, rm as rm2 } from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 
 // src/core/git.ts
 import { execFile } from "child_process";
@@ -475,10 +486,26 @@ async function fileAtCommit(cwd, commit, file) {
   const result = await git(cwd, ["show", `${commit}:./${file}`]);
   return result.ok ? result.stdout : null;
 }
+async function fileInIndex(cwd, file) {
+  const result = await git(cwd, ["show", `:./${file}`]);
+  return result.ok ? result.stdout : null;
+}
+async function isShallow(cwd) {
+  const result = await git(cwd, ["rev-parse", "--is-shallow-repository"]);
+  return result.ok && result.stdout.trim() === "true";
+}
+var FETCH_HISTORY = "fetch full history (actions/checkout: fetch-depth: 0)";
 async function mergeBase(cwd, ref, other = "HEAD") {
   const result = await git(cwd, ["merge-base", other, ref]);
-  if (!result.ok) throw new Error(`cannot find merge base with ${ref}: ${result.stderr.trim()}`);
-  return result.stdout.trim();
+  if (result.ok) return result.stdout.trim();
+  const shallow = await isShallow(cwd);
+  const resolves = (await git(cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`])).ok;
+  if (!resolves) {
+    throw new Error(`"${ref}" is not a commit here${shallow ? `; this is a shallow clone: ${FETCH_HISTORY}` : ""}`);
+  }
+  if (shallow) throw new Error(`no merge base with ${ref} in a shallow clone: ${FETCH_HISTORY}`);
+  const detail = result.stderr.trim();
+  throw new Error(`no merge base with ${ref}${detail ? `: ${detail}` : ": the histories are unrelated"}`);
 }
 async function changedFilesSince(cwd, commit) {
   const diff = await git(cwd, ["diff", "--name-only", "--relative", "--diff-filter=d", commit]);
@@ -509,7 +536,7 @@ async function changedFilesBetween(cwd, from, to) {
 
 // src/core/session/lock.ts
 import { mkdir, rm, stat } from "fs/promises";
-import path3 from "path";
+import path4 from "path";
 var LockTimeoutError = class extends Error {
 };
 var DEFAULTS = { waitMs: 2e3, staleMs: 5e3, retryMs: 20 };
@@ -517,7 +544,7 @@ function isAlreadyExists(error) {
   return error instanceof Error && error.code === "EEXIST";
 }
 async function withLock(dir, fn, options = DEFAULTS) {
-  const lock = path3.join(dir, ".lock");
+  const lock = path4.join(dir, ".lock");
   await mkdir(dir, { recursive: true });
   const started = Date.now();
   for (; ; ) {
@@ -550,7 +577,7 @@ async function withLock(dir, fn, options = DEFAULTS) {
 
 // src/core/repos/layout.ts
 import { createHash as createHash2 } from "crypto";
-import path4 from "path";
+import path5 from "path";
 import { fileURLToPath } from "url";
 var SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
 var SCP_LIKE = /^[^@/\s]+@([^:/\s]+):(.+)$/;
@@ -558,7 +585,7 @@ function segmentsOf(repoPath) {
   return repoPath.replace(/\/+$/, "").replace(/\.git$/, "").split("/").filter(Boolean);
 }
 function localName(file) {
-  return path4.basename(file.replace(/[\\/]+$/, "")).replace(/\.git$/, "");
+  return path5.basename(file.replace(/[\\/]+$/, "")).replace(/\.git$/, "");
 }
 function parseUrl(url) {
   if (SCHEME.test(url)) {
@@ -585,7 +612,7 @@ function repoSlug(url) {
   return safeSegment(`local_${parsed.name}_${hash}`);
 }
 function repoDir(home, url, rev) {
-  return path4.join(home, "repos", repoSlug(url), safeSegment(rev));
+  return path5.join(home, "repos", repoSlug(url), safeSegment(rev));
 }
 function repoLabel(url, rev) {
   return `${repoName(url)}@${rev}`;
@@ -605,7 +632,7 @@ async function fetchCheckout(url, rev, into) {
   await run(into, ["init", "-q"]);
   await run(into, ["fetch", "-q", "--depth", "1", url, rev]);
   await run(into, ["-c", "advice.detachedHead=false", "checkout", "-q", "FETCH_HEAD"]);
-  await rm2(path5.join(into, ".git"), { recursive: true, force: true });
+  await rm2(path6.join(into, ".git"), { recursive: true, force: true });
 }
 function cachedRepo(home, url, rev) {
   const dir = repoDir(home, url, rev);
@@ -614,12 +641,12 @@ function cachedRepo(home, url, rev) {
 async function ensureRepo(home, url, rev) {
   const dir = repoDir(home, url, rev);
   if (existsSync2(dir)) return dir;
-  const parent = path5.dirname(dir);
+  const parent = path6.dirname(dir);
   await withLock(
     parent,
     async () => {
       if (existsSync2(dir)) return;
-      const temp = path5.join(parent, `.tmp-${randomUUID()}`);
+      const temp = path6.join(parent, `.tmp-${randomUUID()}`);
       try {
         await fetchCheckout(url, rev, temp);
         await rename(temp, dir);
@@ -662,7 +689,21 @@ function fixedRepo(dir, label) {
 }
 
 // src/core/pipeline.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
+import path14 from "path";
+
+// src/core/content.ts
+var WORKTREE = { kind: "worktree" };
+function contentReader(root, source) {
+  switch (source.kind) {
+    case "worktree":
+      return (file) => readSourceFile(root, file);
+    case "index":
+      return (file) => fileInIndex(root, file);
+    case "commit":
+      return (file) => fileAtCommit(root, source.ref, file);
+  }
+}
 
 // src/core/baseline/changes.ts
 import { diffArrays } from "diff";
@@ -734,7 +775,7 @@ function snapshotOf(text) {
 }
 
 // src/core/baseline/baseline.ts
-async function computeChanges(root, files, sources) {
+async function computeChanges(root, files, sources, read = contentReader(root, WORKTREE)) {
   const changes = { sets: /* @__PURE__ */ new Map(), maps: /* @__PURE__ */ new Map(), fromCommit: /* @__PURE__ */ new Map() };
   for (const file of files) {
     if (!sources.snapshots.has(file) && !sources.fallbackCommit) continue;
@@ -745,7 +786,7 @@ async function computeChanges(root, files, sources) {
       before = commitText === null ? null : snapshotOf(commitText);
     }
     if (!before) continue;
-    const current = await readSourceFile(root, file);
+    const current = await read(file);
     if (current === null) continue;
     if (commitText !== null) changes.fromCommit.set(file, commitText);
     const after = snapshotOf(current);
@@ -821,10 +862,59 @@ async function applySizeCeiling(selections, maxBytes, bounded, sizeOf) {
   };
 }
 
+// src/core/suppress.ts
+var ID = RULE_ID.source.slice(1, -1);
+var IGNORE = new RegExp(
+  String.raw`rulecast-ignore:\s*(?<rule>${ID})(?:\s+(?<reason>\S.*?))?\s*(?:\*\/|-->)?\s*$`
+);
+function parseIgnore(line) {
+  const match = IGNORE.exec(line);
+  if (match?.groups === void 0) return null;
+  return { rule: match.groups.rule, reason: match.groups.reason ?? null };
+}
+async function suppress(findings, read) {
+  const result = { findings: [], ignored: [], warnings: [] };
+  if (findings.length === 0) return result;
+  const lines = /* @__PURE__ */ new Map();
+  const linesOf = async (file) => {
+    if (!lines.has(file)) lines.set(file, (await read(file))?.split("\n") ?? null);
+    return lines.get(file);
+  };
+  const warned = /* @__PURE__ */ new Set();
+  for (const finding of findings) {
+    const source = await linesOf(finding.match.file);
+    let ignore = null;
+    let at = 0;
+    for (const line of [finding.match.line, finding.match.line - 1]) {
+      const parsed = line >= 1 ? parseIgnore(source?.[line - 1] ?? "") : null;
+      if (parsed !== null && parsed.rule === finding.rule.id) {
+        ignore = parsed;
+        at = line;
+        break;
+      }
+    }
+    if (ignore === null) {
+      result.findings.push(finding);
+      continue;
+    }
+    if (ignore.reason === null) {
+      const where = `${finding.match.file}:${at}`;
+      if (!warned.has(where)) {
+        warned.add(where);
+        result.warnings.push(`${where}: rulecast-ignore needs a reason after the rule id; the finding was kept`);
+      }
+      result.findings.push(finding);
+      continue;
+    }
+    result.ignored.push({ ...finding, reason: ignore.reason });
+  }
+  return result;
+}
+
 // src/core/detection/run.ts
 var TIMED_OUT = /* @__PURE__ */ Symbol("timed out");
 async function runDetection(input) {
-  const output = { findings: [], errors: [], timedOut: [] };
+  const output = { findings: [], errors: [], timedOut: [], ignored: [], warnings: [] };
   const byKind = /* @__PURE__ */ new Map();
   for (const selection of input.selections) {
     const kind = selection.rule.detector.kind;
@@ -841,7 +931,7 @@ async function runDetection(input) {
   const late = () => Date.now() > deadlineAt;
   const perKind = await Promise.all(
     [...byKind].map(async ([kind, selections]) => {
-      const detector = input.registry.get(kind);
+      const detector = input.detection.registry.get(kind);
       if (!detector) return { status: "error", kind, selections, message: `detector "${kind}" is not registered` };
       try {
         const rules = await Promise.all(
@@ -849,7 +939,7 @@ async function runDetection(input) {
             id: rule.id,
             config: rule.detector.config,
             files,
-            context: await input.contextFor(rule)
+            context: await input.detection.contextFor(rule)
           }))
         );
         const result = await Promise.race([
@@ -857,10 +947,11 @@ async function runDetection(input) {
             event: input.event,
             rules,
             read: input.read,
+            fromDisk: input.fromDisk ?? true,
             changes: input.changes,
-            cache: input.cacheFor(kind),
-            settings: input.settings,
-            cwd: input.root,
+            cache: input.detection.cacheFor(kind),
+            settings: input.detection.settings,
+            cwd: input.detection.root,
             signal: controller.signal,
             deadlineAt
           }),
@@ -908,20 +999,21 @@ async function runDetection(input) {
       if (!failed.has(finding.rule)) output.findings.push({ rule: rulesById.get(finding.rule), match: finding.match });
     }
   }
-  return output;
+  const suppressed = await suppress(output.findings, input.read);
+  return { ...output, ...suppressed };
 }
 
 // src/core/baseline/store.ts
-import path7 from "path";
+import path8 from "path";
 
 // src/core/jsonl.ts
 import { mkdir as mkdir3, open, readFile as readFile3 } from "fs/promises";
-import path6 from "path";
+import path7 from "path";
 var CorruptStoreError = class extends Error {
 };
 async function appendRecords(file, records) {
   if (records.length === 0) return;
-  await mkdir3(path6.dirname(file), { recursive: true });
+  await mkdir3(path7.dirname(file), { recursive: true });
   const handle = await open(file, "a+");
   try {
     await dropPartialRecord(handle);
@@ -973,7 +1065,7 @@ async function readRecords(file) {
 
 // src/core/baseline/store.ts
 function storeFile(sessionDir2) {
-  return path7.join(sessionDir2, "baseline.jsonl");
+  return path8.join(sessionDir2, "baseline.jsonl");
 }
 function encodeLines(lines) {
   return Buffer.from(lines.buffer, lines.byteOffset, lines.byteLength).toString("base64");
@@ -984,8 +1076,8 @@ function decodeLines(encoded) {
   aligned.set(bytes);
   return new Uint32Array(aligned.buffer);
 }
-function startRecord(commit) {
-  return { t: "start", commit };
+function startRecord(commit, configHash2 = null) {
+  return { t: "start", commit, configHash: configHash2 };
 }
 function snapshotRecord(file, snapshot) {
   return { t: "snapshot", file, fileHash: snapshot.fileHash, lines: encodeLines(snapshot.lines) };
@@ -996,29 +1088,37 @@ function fingerprintRecord(file, rule, ranges) {
 async function appendBaseline(sessionDir2, records) {
   await appendRecords(storeFile(sessionDir2), records);
 }
+function mergeFingerprints(into, records) {
+  for (const record of records) {
+    if (record.t !== "fingerprint") continue;
+    const byRule = into.get(record.file) ?? /* @__PURE__ */ new Map();
+    into.set(record.file, byRule);
+    if (!byRule.has(record.rule)) byRule.set(record.rule, record.ranges);
+  }
+  return into;
+}
 async function readBaseline(sessionDir2) {
   const state = { started: false, startCommit: null, snapshots: /* @__PURE__ */ new Map(), fingerprints: /* @__PURE__ */ new Map() };
-  for (const record of await readRecords(storeFile(sessionDir2))) {
+  const records = await readRecords(storeFile(sessionDir2));
+  for (const record of records) {
     if (record.t === "start" && !state.started) {
       state.started = true;
       state.startCommit = record.commit;
+      state.startConfigHash = record.configHash ?? null;
     } else if (record.t === "snapshot" && !state.snapshots.has(record.file)) {
       state.snapshots.set(record.file, { fileHash: record.fileHash, lines: decodeLines(record.lines) });
-    } else if (record.t === "fingerprint") {
-      const byRule = state.fingerprints.get(record.file) ?? /* @__PURE__ */ new Map();
-      state.fingerprints.set(record.file, byRule);
-      if (!byRule.has(record.rule)) byRule.set(record.rule, record.ranges);
     }
   }
+  mergeFingerprints(state.fingerprints, records);
   return state;
 }
 
 // src/core/baseline/record.ts
 async function recordFingerprints(input) {
   if (!input.rules.some((rule) => rule.scope === "container")) return [];
-  const guards = (kind) => input.registry.get(kind)?.guards === true;
+  const guards = (kind) => input.detection.registry.get(kind)?.guards === true;
   let selections = selectDetectorRules(input.rules, input.event, input.files, input.disabled).filter(
-    (selection) => selection.rule.scope === "container" && selection.rule.detector.kind !== "llm" && (input.source === "disk" || guards(selection.rule.detector.kind))
+    (selection) => selection.rule.scope === "container" && input.detection.registry.get(selection.rule.detector.kind)?.metered !== true && (input.source === "disk" || guards(selection.rule.detector.kind))
   );
   if (input.ceiling) {
     const applied = await applySizeCeiling(selections, input.ceiling.maxFileBytes, guards, input.ceiling.sizeOf);
@@ -1026,7 +1126,7 @@ async function recordFingerprints(input) {
   }
   if (selections.length === 0) return [];
   const output = await runDetection({
-    root: input.root,
+    detection: input.detection,
     event: input.event,
     selections,
     // No change set: the baseline content is being measured whole, and there is nothing it is a
@@ -1034,10 +1134,6 @@ async function recordFingerprints(input) {
     // exactly right here.
     changes: /* @__PURE__ */ new Map(),
     read: input.read,
-    registry: input.registry,
-    cacheFor: input.cacheFor,
-    contextFor: input.contextFor,
-    settings: input.settings,
     timeoutMs: input.timeoutMs
   });
   const unmeasured = /* @__PURE__ */ new Set();
@@ -1058,9 +1154,86 @@ async function recordFingerprints(input) {
   return records;
 }
 
+// src/core/baseline/stage.ts
+async function touchRecords(input, state, files) {
+  const records = [];
+  const snapshotted = [];
+  for (const file of files) {
+    if (state.snapshots.has(file)) continue;
+    const text = await readSourceFile(input.root, file);
+    if (text === null) continue;
+    records.push(snapshotRecord(file, snapshotOf(text)));
+    snapshotted.push(file);
+  }
+  if (snapshotted.length === 0) return records;
+  records.push(
+    ...await recordFingerprints({
+      detection: input.detection,
+      files: snapshotted,
+      rules: input.rules,
+      disabled: input.disabled,
+      read: (file) => readSourceFile(input.root, file),
+      event: "edit",
+      source: "disk",
+      timeoutMs: input.limits.editDeadlineMs,
+      ceiling: { maxFileBytes: input.limits.maxFileBytes, sizeOf: (file) => fileBytes(input.root, file) }
+    })
+  );
+  return records;
+}
+async function changesFor(input, event, state, files, read) {
+  let snapshots = state?.snapshots ?? /* @__PURE__ */ new Map();
+  let fallbackCommit = state?.startCommit ?? null;
+  if (event.kind === "verify" && event.baseCommit) {
+    fallbackCommit = event.baseCommit;
+    snapshots = /* @__PURE__ */ new Map();
+  }
+  const changes = await computeChanges(input.root, files, { snapshots, fallbackCommit }, read);
+  const kept = event.kind === "verify" && state !== null && !event.baseCommit ? files.filter((file) => changes.sets.get(file)?.changedLines.length !== 0) : [...files];
+  const fingerprints = new Map(
+    [...state?.fingerprints ?? []].map(([file, byRule]) => [file, new Map(byRule)])
+  );
+  if (event.kind !== "verify" || changes.fromCommit.size === 0) {
+    return { files: kept, changes, fingerprints, records: [] };
+  }
+  const texts = changes.fromCommit;
+  const missing = [...texts.keys()].filter((file) => !fingerprints.has(file));
+  const records = missing.length === 0 ? [] : await recordFingerprints({
+    detection: input.detection,
+    files: missing,
+    rules: input.rules,
+    disabled: input.disabled,
+    read: async (file) => texts.get(file) ?? null,
+    event: "verify",
+    source: "memory",
+    timeoutMs: input.limits.verifyMs
+  });
+  return { files: kept, changes, fingerprints: mergeFingerprints(fingerprints, records), records };
+}
+
 // src/core/delivery/persist.ts
-import { mkdirSync as mkdirSync2, readdirSync, rmSync, writeFileSync as writeFileSync2 } from "fs";
-import path8 from "path";
+import { copyFileSync, existsSync as existsSync3, mkdirSync as mkdirSync2, readdirSync, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import path9 from "path";
+var AGENT_DIR = ".rulecast";
+function agentDir(root) {
+  const dir = path9.join(root, AGENT_DIR);
+  mkdirSync2(dir, { recursive: true });
+  const ignore = path9.join(dir, ".gitignore");
+  if (!existsSync3(ignore)) writeFileSync2(ignore, "# Written by rulecast: files its hooks point an agent at.\n*\n");
+  return dir;
+}
+function copyIntoProject(root, home, file) {
+  const rest = path9.relative(home, file);
+  if (rest.startsWith("..") || path9.isAbsolute(rest)) return null;
+  try {
+    const target = path9.join(agentDir(root), rest);
+    mkdirSync2(path9.dirname(target), { recursive: true });
+    copyFileSync(file, target);
+    return path9.join(AGENT_DIR, rest).split(path9.sep).join("/");
+  } catch {
+    return null;
+  }
+}
 var KEEP = 3;
 var UNLIMITED = { maxMatchesPerRule: Number.MAX_SAFE_INTEGER };
 var safeSegment2 = (value) => value.replace(/[^A-Za-z0-9._-]/g, "_");
@@ -1076,15 +1249,14 @@ function markdown(delivery, now) {
     ""
   ].join("\n");
 }
-function writeOverflow(stateDir, session, delivery, now = /* @__PURE__ */ new Date()) {
+function writeOverflow(dir, session, delivery, now = /* @__PURE__ */ new Date()) {
   const prefix = safeSegment2(session ?? "no-session");
-  const dir = path8.join(stateDir, "deliveries");
-  const file = path8.join(dir, `${prefix}-${now.toISOString().replace(/[:.]/g, "-")}.md`);
+  const file = path9.join(dir, `${prefix}-${now.toISOString().replace(/[:.]/g, "-")}.md`);
   try {
     mkdirSync2(dir, { recursive: true });
     writeFileSync2(file, markdown(delivery, now));
     const mine = readdirSync(dir).filter((name) => name.startsWith(`${prefix}-`)).sort();
-    for (const old of mine.slice(0, Math.max(0, mine.length - KEEP))) rmSync(path8.join(dir, old), { force: true });
+    for (const old of mine.slice(0, Math.max(0, mine.length - KEEP))) rmSync(path9.join(dir, old), { force: true });
     return file;
   } catch {
     return null;
@@ -1102,16 +1274,16 @@ async function resolveRuleContext(resolver, context) {
 }
 function createReferenceResolver(root) {
   const texts = /* @__PURE__ */ new Map();
-  const read = (path11) => {
-    let text = texts.get(path11);
+  const read = (path15) => {
+    let text = texts.get(path15);
     if (!text) {
-      text = readSourceFile(root, path11);
-      texts.set(path11, text);
+      text = readSourceFile(root, path15);
+      texts.set(path15, text);
     }
     return text;
   };
-  const contentOf = async (path11, anchor) => {
-    const text = await read(path11);
+  const contentOf = async (path15, anchor) => {
+    const text = await read(path15);
     if (text === null) return null;
     if (anchor === null) return text.trimEnd();
     const section = sectionRange(text, anchor);
@@ -1123,19 +1295,108 @@ function createReferenceResolver(root) {
       if (content === null) return { spec, found: false };
       return { spec, found: true, content, hash: fnv1a(content), bytes: Buffer.byteLength(content) };
     },
-    async currentHash(path11, anchor) {
-      const content = await contentOf(path11, anchor);
+    async currentHash(path15, anchor) {
+      const content = await contentOf(path15, anchor);
       return content === null ? null : fnv1a(content);
     },
-    async contains(path11, parent, child) {
+    async contains(path15, parent, child) {
       if (parent === null) return true;
       if (child === null) return false;
-      const text = await read(path11);
+      const text = await read(path15);
       return text !== null && sectionContains(text, parent, child);
     }
   };
 }
 
+// src/core/detection/context.ts
+function detectionFor(project, registry, stateDir, resolver) {
+  return {
+    root: project.root,
+    registry,
+    settings: { llm: project.config.llm },
+    cacheFor: (kind) => diskCache(detectorCacheDir(stateDir, kind)),
+    contextFor: (rule) => resolveRuleContext(resolver, rule.context)
+  };
+}
+
+// src/core/detection/scratch.ts
+import { mkdir as mkdir4, mkdtemp, rm as rm3, writeFile } from "fs/promises";
+import path10 from "path";
+async function withScratchTree(root, prefix, entries, fn) {
+  const dir = path10.basename(await mkdtemp(path10.join(root, prefix)));
+  try {
+    for (const [file, content] of entries) {
+      const full = path10.join(root, dir, file);
+      await mkdir4(path10.dirname(full), { recursive: true });
+      await writeFile(full, content);
+    }
+    return await fn(dir);
+  } finally {
+    await rm3(path10.join(root, dir), { recursive: true, force: true });
+  }
+}
+
+// src/core/detection/materialise.ts
+var STAGED_DIR = ".rulecast-staged-";
+async function runDetectionFrom(input, source) {
+  if (source.kind === "worktree") return runDetection(input);
+  const registry = input.detection.registry;
+  const direct = [];
+  const copied = [];
+  for (const selection of input.selections) {
+    const detector = registry.get(selection.rule.detector.kind);
+    const readsContent = detector?.guards === true || detector?.takesContent?.(selection.rule.detector.config) === true;
+    if (readsContent || detector === void 0) direct.push(selection);
+    else copied.push(selection);
+  }
+  const outputs = await Promise.all([
+    direct.length === 0 ? null : runDetection({ ...input, selections: direct, fromDisk: false }),
+    copied.length === 0 ? null : fromScratch(input, copied)
+  ]);
+  return merge(outputs.filter((output) => output !== null));
+}
+async function fromScratch(input, selections) {
+  const entries = /* @__PURE__ */ new Map();
+  for (const file of new Set(selections.flatMap((selection) => selection.files))) {
+    const text = await input.read(file);
+    if (text !== null) entries.set(file, text);
+  }
+  if (entries.size === 0) return { findings: [], errors: [], timedOut: [], ignored: [], warnings: [] };
+  return withScratchTree(input.detection.root, STAGED_DIR, entries, async (dir) => {
+    const prefix = `${dir}/`;
+    const strip = (file) => file.startsWith(prefix) ? file.slice(prefix.length) : file;
+    const output = await runDetection({
+      ...input,
+      selections: selections.map((selection) => ({
+        ...selection,
+        files: selection.files.filter((file) => entries.has(file)).map((file) => prefix + file)
+      })).filter((selection) => selection.files.length > 0),
+      changes: new Map([...input.changes].map(([file, change]) => [prefix + file, change])),
+      // Anything reading through `read` under a scratch path is asking about the real file.
+      read: (file) => input.read(strip(file))
+    });
+    return {
+      findings: output.findings.map(({ rule, match }) => ({ rule, match: { ...match, file: strip(match.file) } })),
+      errors: output.errors.map((error) => ({ ...error, message: error.message.replaceAll(prefix, "") })),
+      timedOut: output.timedOut,
+      ignored: output.ignored.map((ignored) => ({
+        ...ignored,
+        match: { ...ignored.match, file: strip(ignored.match.file) }
+      })),
+      warnings: output.warnings.map((warning) => warning.replaceAll(prefix, ""))
+    };
+  });
+}
+function merge(outputs) {
+  return {
+    findings: outputs.flatMap((output) => output.findings),
+    errors: outputs.flatMap((output) => output.errors),
+    timedOut: outputs.flatMap((output) => output.timedOut),
+    ignored: outputs.flatMap((output) => output.ignored),
+    warnings: outputs.flatMap((output) => output.warnings)
+  };
+}
+
 // src/core/detection/proposal.ts
 function propose(current, intent) {
   if (intent.content !== void 0) {
@@ -1161,8 +1422,8 @@ function propose(current, intent) {
   }
   return { content: content + rest, inserts };
 }
-function isInserted(proposal, match, detector) {
-  if (detector === "path") return true;
+function isInserted(proposal, match, wholeFile) {
+  if (wholeFile) return true;
   const starts = lineStarts(proposal.content);
   const lineStart = starts[match.line - 1];
   if (lineStart === void 0) return false;
@@ -1172,7 +1433,7 @@ function isInserted(proposal, match, detector) {
 }
 
 // src/core/session/decide.ts
-import path9 from "path";
+import path11 from "path";
 
 // src/core/session/state.ts
 function preexistingKey(rule, file) {
@@ -1180,7 +1441,14 @@ function preexistingKey(rule, file) {
 }
 var refusalKey = preexistingKey;
 function emptyWork() {
-  return { edited: [], stopBlocks: /* @__PURE__ */ new Map(), refusals: /* @__PURE__ */ new Map(), disabled: /* @__PURE__ */ new Map(), accessed: /* @__PURE__ */ new Map() };
+  return {
+    edited: [],
+    stopBlocks: /* @__PURE__ */ new Map(),
+    refusals: /* @__PURE__ */ new Map(),
+    disabled: /* @__PURE__ */ new Map(),
+    accessed: /* @__PURE__ */ new Map(),
+    noticed: /* @__PURE__ */ new Set()
+  };
 }
 function emptyContext() {
   return { delivered: [], touched: /* @__PURE__ */ new Set(), preexisting: /* @__PURE__ */ new Set(), warned: /* @__PURE__ */ new Set() };
@@ -1211,6 +1479,9 @@ function foldWork(records) {
       case "disabled":
         if (!state.disabled.has(record.rule)) state.disabled.set(record.rule, record.reason);
         break;
+      case "noticed":
+        state.noticed.add(record.key);
+        break;
     }
   }
   return state;
@@ -1240,15 +1511,10 @@ function foldContext(records) {
 }
 
 // src/core/session/decide.ts
-var ITEM_OVERHEAD = 64;
-var HEADER_OVERHEAD = 128;
-var OVERFLOW_NOTICE = 256;
-var REFERENCE_OVERHEAD = 96;
-var BACKLOG_HEADING = "backlog in files you touched (not from your edit):";
 var WARNING_SHARE = 0.15;
 var moreWarnings = (count) => `\u2026and ${count} more (run rulecast validate)`;
 function locationOf(spec) {
-  return path9.isAbsolute(spec.path) ? { location: spec.path } : {};
+  return path11.isAbsolute(spec.path) ? { location: spec.path } : {};
 }
 function capturesFor(rule, match) {
   const names = templateBindings(rule.message ?? "");
@@ -1311,37 +1577,38 @@ async function isCovered(spec, delivered, resolver) {
   }
   return false;
 }
-async function decide(input) {
+async function assemble(input) {
   const delivery = emptyDelivery();
-  const work = [];
   const context = [];
+  const touches = input.touches ?? [];
+  const state = input.context ?? emptyContext();
   const fresh = input.findings.filter((finding) => finding.status === "new");
   delivery.findings = renderFindings(fresh);
-  const rulesById = new Map(fresh.map(({ rule }) => [rule.id, rule]));
   for (const { rule } of fresh) if (rule.message !== null) delivery.templates[rule.id] = rule.message;
   const summaries = /* @__PURE__ */ new Map();
   for (const { rule, match, status } of input.findings) {
     if (status !== "preexisting") continue;
     const key = preexistingKey(rule.id, match.file);
-    if (input.context.preexisting.has(key)) continue;
+    if (state.preexisting.has(key)) continue;
     const summary = summaries.get(key) ?? { rule: rule.id, file: match.file, count: 0 };
     summary.count++;
     summaries.set(key, summary);
   }
   delivery.preexistingSummary = [...summaries.values()];
-  const unwarned = input.warnings.filter((warning) => !input.context.warned.has(warning.key));
+  const unwarned = (input.warnings ?? []).filter((warning) => !state.warned.has(warning.key));
   delivery.warnings = unwarned.map((warning) => warning.text);
-  delivery.touches = input.touches.map((rule) => rule.id);
-  for (const rule of input.touches) context.push({ t: "touched", rule: rule.id });
-  const delivered = [...input.context.delivered];
-  if (input.agentRead !== null) {
-    const hash = await input.resolver.currentHash(input.agentRead, null);
+  delivery.touches = touches.map((rule) => rule.id);
+  for (const rule of touches) context.push({ t: "touched", rule: rule.id });
+  const delivered = [...state.delivered];
+  const agentRead = input.agentRead ?? null;
+  if (agentRead !== null) {
+    const hash = await input.resolver.currentHash(agentRead, null);
     if (hash !== null) {
-      delivered.push({ path: input.agentRead, anchor: null, hash });
-      context.push({ t: "delivered", path: input.agentRead, anchor: null, hash });
+      delivered.push({ path: agentRead, anchor: null, hash });
+      context.push({ t: "delivered", path: agentRead, anchor: null, hash });
     }
   }
-  const ruleOrder = [...new Map(fresh.map((finding) => [finding.rule.id, finding.rule])).values(), ...input.touches];
+  const ruleOrder = [...new Map(fresh.map((finding) => [finding.rule.id, finding.rule])).values(), ...touches];
   const candidates = [];
   for (const spec of referencesInOrder(ruleOrder)) {
     const resolved = await input.resolver.resolve(spec);
@@ -1358,26 +1625,38 @@ async function decide(input) {
       delivery.references.push({ ref: spec.ref, state: "full", content: resolved.content });
     }
   }
-  const limit = input.maxContextChars;
-  const render = { maxMatchesPerRule: input.maxMatchesPerRule };
-  const complete = {
-    ...delivery,
-    findings: [...delivery.findings],
-    preexistingSummary: [...delivery.preexistingSummary],
-    references: [...delivery.references],
-    warnings: [...delivery.warnings],
+  return { delivery, candidates, fresh, unwarned, touches, context };
+}
+function trim(assembled, limits) {
+  const { candidates, unwarned, touches } = assembled;
+  const delivery = {
+    ...assembled.delivery,
+    findings: [...assembled.delivery.findings],
+    preexistingSummary: [...assembled.delivery.preexistingSummary],
+    references: [...assembled.delivery.references],
+    warnings: [...assembled.delivery.warnings],
     omitted: { findings: [], rules: 0, preexisting: 0 }
   };
+  const context = [];
+  const rulesById = new Map(assembled.fresh.map(({ rule }) => [rule.id, rule]));
+  const limit = limits.maxContextChars;
+  const render = { maxMatchesPerRule: limits.maxMatchesPerRule };
   const byRule = /* @__PURE__ */ new Map();
   for (const finding of delivery.findings) {
     const group = byRule.get(finding.rule);
     if (group === void 0) byRule.set(finding.rule, [finding]);
     else group.push(finding);
   }
-  let used = HEADER_OVERHEAD;
+  const conventions = delivery.references.length > 0 || delivery.preexistingSummary.length > 0;
+  let used = deliveryCost.header(byRule.size, new Set(delivery.findings.map((finding) => finding.file)), conventions) + (delivery.references.length > 0 ? deliveryCost.referencesEnd : 0);
   const fits = (size) => limit === null || used + size <= limit;
   const kept = /* @__PURE__ */ new Map();
-  const lineCost = (ref) => ref.length + REFERENCE_OVERHEAD;
+  const specs = /* @__PURE__ */ new Map();
+  for (const rule of [...rulesById.values(), ...touches]) for (const spec of rule.context) specs.set(spec.ref, spec);
+  const lineCost = (ref) => {
+    const spec = specs.get(ref);
+    return deliveryCost.referenceLine(ref, spec === void 0 ? void 0 : locationOf(spec).location);
+  };
   const resolvedRefs = new Set(delivery.references.map((reference) => reference.ref));
   const charged = /* @__PURE__ */ new Set();
   const orphaned = /* @__PURE__ */ new Set();
@@ -1389,7 +1668,7 @@ async function decide(input) {
     for (const [id, findings] of byRule) {
       const rule = rulesById.get(id);
       const refs = rule === void 0 ? [] : uncharged(rule);
-      const size = measureRuleBlock(id, [findings[0]], delivery.templates[id], render) + refs.reduce((sum, ref) => sum + lineCost(ref), 0);
+      const size = measureRuleBlock(id, [findings[0]], findings, delivery.templates[id], render) + refs.reduce((sum, ref) => sum + lineCost(ref), 0);
       if (used + spent.chars + size > cap) {
         spent.dropped++;
         continue;
@@ -1398,7 +1677,7 @@ async function decide(input) {
       for (const ref of refs) spent.refs.add(ref);
       spent.kept.set(id, [findings[0]]);
     }
-    for (const touch of input.touches) {
+    for (const touch of touches) {
       for (const ref of uncharged(touch)) {
         spent.chars += lineCost(ref);
         spent.refs.add(ref);
@@ -1408,19 +1687,20 @@ async function decide(input) {
   };
   if (limit !== null) {
     let floor = floorWithin(limit);
-    if (floor.dropped > 0) floor = floorWithin(limit - OVERFLOW_NOTICE);
-    used += floor.chars + (floor.dropped > 0 ? OVERFLOW_NOTICE : 0);
+    const notice = deliveryCost.overflowNotice(byRule.size);
+    if (floor.dropped > 0) floor = floorWithin(limit - notice);
+    used += floor.chars + (floor.dropped > 0 ? notice : 0);
     delivery.omitted.rules = floor.dropped;
     for (const [id, findings] of floor.kept) kept.set(id, findings);
     for (const ref of floor.refs) charged.add(ref);
     for (const ref of resolvedRefs) if (!charged.has(ref)) orphaned.add(ref);
   }
-  const warningCost = (text) => text.length + ITEM_OVERHEAD;
+  const warningCost = (text) => deliveryCost.warning(text);
   if (limit === null) {
     for (const warning of unwarned) context.push({ t: "warned", key: warning.key });
   } else {
     const ceiling = Math.max(0, Math.min(Math.floor(limit * WARNING_SHARE), limit - used));
-    let spent = 0;
+    let spent = unwarned.length > 0 ? deliveryCost.warningsFrame : 0;
     let held = 0;
     while (held < unwarned.length && spent + warningCost(unwarned[held].text) <= ceiling) {
       spent += warningCost(unwarned[held].text);
@@ -1439,10 +1719,10 @@ async function decide(input) {
       spent += warningCost(moreWarnings(cut));
       delivery.warnings.push(moreWarnings(cut));
     }
-    used += spent;
+    used += delivery.warnings.length > 0 ? spent : 0;
   }
   for (const { index, resolved } of candidates) {
-    const size = resolved.content.length;
+    const size = deliveryCost.referenceContent(resolved.spec.ref, resolved.content, locationOf(resolved.spec).location);
     if (orphaned.has(resolved.spec.ref)) continue;
     if (!fits(size)) {
       delivery.references[index] = {
@@ -1456,14 +1736,16 @@ async function decide(input) {
     used += size;
     context.push({ t: "delivered", path: resolved.spec.path, anchor: resolved.spec.anchor, hash: resolved.hash });
   }
-  if (delivery.preexistingSummary.length > 0) used += BACKLOG_HEADING.length + BACKLOG_HINT.length + ITEM_OVERHEAD;
+  const frame = delivery.preexistingSummary.length > 0 ? deliveryCost.backlogFrame(delivery.preexistingSummary.length) : 0;
+  if (frame > 0 && !fits(frame)) delivery.preexistingSummary = [];
+  else used += frame;
   const summariesKept = [];
   for (const summary of delivery.preexistingSummary) {
-    if (!fits(summary.rule.length + summary.file.length + ITEM_OVERHEAD)) {
+    if (!fits(deliveryCost.backlogSummary(summary))) {
       delivery.omitted.preexisting++;
       continue;
     }
-    used += summary.rule.length + summary.file.length + ITEM_OVERHEAD;
+    used += deliveryCost.backlogSummary(summary);
     summariesKept.push(summary);
     context.push({ t: "preexisting", rule: summary.rule, file: summary.file });
   }
@@ -1474,9 +1756,9 @@ async function decide(input) {
       added = false;
       for (const [rule, findings] of byRule) {
         const shown = kept.get(rule);
-        if (shown === void 0 || shown.length >= Math.min(findings.length, input.maxMatchesPerRule)) continue;
+        if (shown === void 0 || shown.length >= Math.min(findings.length, limits.maxMatchesPerRule)) continue;
         const template = delivery.templates[rule];
-        const delta = measureRuleBlock(rule, [...shown, findings[shown.length]], template, render) - measureRuleBlock(rule, shown, template, render);
+        const delta = measureRuleBlock(rule, [...shown, findings[shown.length]], findings, template, render) - measureRuleBlock(rule, shown, findings, template, render);
         if (!fits(delta)) continue;
         used += delta;
         shown.push(findings[shown.length]);
@@ -1496,20 +1778,26 @@ async function decide(input) {
     }
     delivery.findings = delivery.findings.filter((finding) => kept.get(finding.rule)?.includes(finding) === true);
   }
-  if (input.stopGate) {
-    const newErrors = fresh.some(({ rule }) => rule.severity === "error");
-    const blocks = input.work.stopBlocks.get(input.agent) ?? 0;
-    if (!newErrors) delivery.stop = "allow";
-    else if (blocks < input.maxBlocks) {
-      delivery.stop = "block";
-      work.push({ t: "stopBlock", agent: input.agent });
-    } else delivery.stop = "capReached";
-    if (delivery.stop === "allow") return { delivery, overflow: null, work, context: [] };
-    if (delivery.stop === "capReached") {
-      return { delivery, overflow: delivery.omitted.rules > 0 ? complete : null, work, context: [] };
-    }
-  }
-  return { delivery, overflow: delivery.omitted.rules > 0 ? complete : null, work, context };
+  return { delivery, overflow: delivery.omitted.rules > 0 ? assembled.delivery : null, context };
+}
+function gate(fresh, work, agent, maxBlocks) {
+  if (!fresh.some(({ rule }) => rule.severity === "error")) return { stop: "allow", work: [] };
+  if ((work.stopBlocks.get(agent) ?? 0) < maxBlocks) return { stop: "block", work: [{ t: "stopBlock", agent }] };
+  return { stop: "capReached", work: [] };
+}
+async function decide(input) {
+  const assembled = await assemble(input);
+  const trimmed = trim(assembled, {
+    maxContextChars: input.maxContextChars,
+    maxMatchesPerRule: input.maxMatchesPerRule
+  });
+  const context = [...assembled.context, ...trimmed.context];
+  if (!input.stopGate) return { delivery: trimmed.delivery, overflow: trimmed.overflow, work: [], context };
+  const gated = gate(assembled.fresh, input.work, input.agent, input.maxBlocks);
+  const delivery = { ...trimmed.delivery, stop: gated.stop };
+  if (gated.stop === "allow") return { delivery, overflow: null, work: gated.work, context: [] };
+  if (gated.stop === "capReached") return { delivery, overflow: trimmed.overflow, work: gated.work, context: [] };
+  return { delivery, overflow: trimmed.overflow, work: gated.work, context };
 }
 
 // src/core/guard.ts
@@ -1519,7 +1807,7 @@ async function guardWrite(input) {
   if (file === void 0 || intent === void 0) return emptyDelivery();
   const rules = input.rules.filter((rule) => rule.refuseWrite && !input.disabled.has(rule.id) && rule.matches(file));
   if (rules.length === 0) return emptyDelivery();
-  const proposal = propose(await readSourceFile(input.root, file), intent);
+  const proposal = propose(await readSourceFile(input.detection.root, file), intent);
   if (proposal === null) {
     input.log(`guard: ${file} could not be reconstructed from the tool call; allowing the write`);
     return emptyDelivery();
@@ -1532,19 +1820,18 @@ async function guardWrite(input) {
   const selections = selectDetectorRules(rules, "edit", [file], input.disabled);
   if (selections.length === 0) return emptyDelivery();
   const output = await runDetection({
-    root: input.root,
+    detection: input.detection,
     event: "edit",
     selections,
     changes: /* @__PURE__ */ new Map(),
     // The proposed file for the one being written; anything else a detector reaches for is real.
-    read: async (name) => name === file ? proposal.content : readSourceFile(input.root, name),
-    registry: input.registry,
-    cacheFor: (kind) => diskCache(detectorCacheDir(input.stateDir, kind)),
-    contextFor: (rule) => resolveRuleContext(input.resolver, rule.context),
-    settings: { llm: input.config.llm },
+    read: async (name) => name === file ? proposal.content : readSourceFile(input.detection.root, name),
     timeoutMs: input.config.timeouts.editDeadlineMs
   });
-  const evidence = output.findings.filter(({ rule, match }) => isInserted(proposal, match, rule.detector.kind));
+  const wholeFile = (kind) => input.detection.registry.get(kind)?.wholeFile === true;
+  const evidence = output.findings.filter(
+    ({ rule, match }) => isInserted(proposal, match, wholeFile(rule.detector.kind))
+  );
   if (evidence.length === 0) return emptyDelivery();
   const spent = (rule) => (input.work.refusals.get(refusalKey(rule, file)) ?? 0) >= input.config.refuseGate.maxRefusals;
   const refusing = evidence.filter(({ rule }) => !spent(rule.id));
@@ -1552,41 +1839,67 @@ async function guardWrite(input) {
     input.log(`guard: ${file} has spent its refusals; allowing the write`);
     return emptyDelivery();
   }
-  const { delivery } = await decide({
-    agent: "main",
+  const assembled = await assemble({
     findings: refusing.map(({ rule, match }) => ({ rule, match, status: "new" })),
-    touches: [],
-    agentRead: null,
-    warnings: [],
-    work: input.work,
-    // An empty context, so the sections come with the refusal even if they were delivered earlier:
-    // the message has to stand on its own, and nothing here is recorded as delivered because the
-    // write it explains never happened.
-    context: emptyContext(),
     resolver: input.resolver,
-    maxBytes: input.config.context.maxBytes,
-    maxBlocks: input.config.stopGate.maxBlocks,
+    maxBytes: input.config.context.maxBytes
+  });
+  const { delivery, context } = trim(assembled, {
     maxContextChars: input.maxContextChars,
-    maxMatchesPerRule: input.config.maxMatchesPerRule,
-    stopGate: false
+    maxMatchesPerRule: input.config.maxMatchesPerRule
   });
+  await input.recordContext(context.filter((record) => record.t === "delivered"));
   await input.record(
     [...new Set(refusing.map(({ rule }) => rule.id))].map((rule) => ({ t: "refused", rule, file }))
   );
   return delivery;
 }
 
+// src/core/session/oversight.ts
+import { createHash as createHash3 } from "crypto";
+import { readFile as readFile4 } from "fs/promises";
+import path12 from "path";
+function notices(input) {
+  const out = [];
+  const configKey = `config:${input.currentConfigHash ?? "gone"}`;
+  if (input.startConfigHash !== null && input.startConfigHash !== input.currentConfigHash && !input.told.has(configKey)) {
+    out.push({
+      key: configKey,
+      text: `rulecast: ${CONFIG_FILE} changed during this session; findings may have been silenced. Review: git diff ${CONFIG_FILE}`
+    });
+  }
+  const keyOf = ({ rule, match }) => `ignore:${rule}:${match.file}:${match.line}`;
+  const added = input.ignored.filter((ignored) => ignored.status === "new" && !input.told.has(keyOf(ignored)));
+  if (added.length > 0) {
+    const sites = added.map(({ rule, match, reason }) => `${match.file}:${match.line} (${rule}: "${reason}")`);
+    const comments = added.length === 1 ? "a rulecast-ignore comment" : `${added.length} rulecast-ignore comments`;
+    out.push({
+      key: added.map(keyOf).join("\n"),
+      text: `rulecast: the agent added ${comments} this session: ${sites.join(", ")}`
+    });
+  }
+  return out;
+}
+async function configHash(root) {
+  try {
+    return createHash3("sha256").update(await readFile4(path12.join(root, CONFIG_FILE))).digest("hex");
+  } catch (error) {
+    if (isNotFound(error)) return null;
+    throw error;
+  }
+}
+
 // src/core/session/session.ts
-import path10 from "path";
+import path13 from "path";
 function safeSegment3(value) {
   const segment = value.replace(/[^A-Za-z0-9._-]/g, "_");
   return /^\.*$/.test(segment) ? `_${segment}` : segment;
 }
 function sessionDir(stateDir, sessionId) {
-  return path10.join(stateDir, "sessions", safeSegment3(sessionId));
+  return path13.join(stateDir, "sessions", safeSegment3(sessionId));
 }
-var workFile = (dir) => path10.join(dir, "work.jsonl");
-var contextFile = (dir, agent) => path10.join(dir, `context.${safeSegment3(agent)}.jsonl`);
+var workFile = (dir) => path13.join(dir, "work.jsonl");
+var contextFile = (dir, agent) => path13.join(dir, `context.${safeSegment3(agent)}.jsonl`);
 async function appendWork(dir, records) {
   await appendRecords(workFile(dir), records);
 }
@@ -1613,7 +1926,7 @@ async function commitSession(dir, agent, decideWith) {
 var SUMMARY_THRESHOLD = 3;
 var DEFAULT_HINT = "rulecast validate";
 function summaryKey(prefix, ids) {
-  const digest = createHash3("sha256").update([...ids].sort().join("\n")).digest("hex").slice(0, 16);
+  const digest = createHash4("sha256").update([...ids].sort().join("\n")).digest("hex").slice(0, 16);
   return `${prefix}:${digest}`;
 }
 function compileWarnings(errors) {
@@ -1636,8 +1949,9 @@ First: ${diagnosticText(errors[0])}`
     }
   ];
 }
-function detectorWarnings(errors) {
-  const text = (error) => `${error.kind} detector failed for ${error.rules.join(", ")}: ${error.message}. Disabled for this session.`;
+function detectorWarnings(errors, scope) {
+  const outcome = scope === "session" ? "Disabled for this session." : "Skipped for this run.";
+  const text = (error) => `${error.kind} detector failed for ${error.rules.join(", ")}: ${error.message}. ${outcome}`;
   const byKind = /* @__PURE__ */ new Map();
   for (const error of errors) {
     const group = byKind.get(error.kind);
@@ -1658,7 +1972,7 @@ function detectorWarnings(errors) {
     const ids = group.flatMap((error) => error.rules);
     summarised.push({
       key: summaryKey(`detector:${kind}`, ids),
-      text: `${ids.length} ${kind} rules were disabled this session \u2014 see debug.log.
+      text: `${ids.length} ${kind} rules ${scope === "session" ? "were disabled this session" : "were skipped in this run"} \u2014 see debug.log.
 First: ${text(group[0])}`
     });
   }
@@ -1705,7 +2019,7 @@ async function runPipeline(options) {
     const dir = session.dir;
     baseline = await readingStore(() => readBaseline(dir), baseline);
     if (session && !baseline.started) {
-      await appendBaseline(dir, [startRecord(await headCommit(root))]);
+      await appendBaseline(dir, [startRecord(await headCommit(root), await configHash(root))]);
       baseline = await readingStore(() => readBaseline(dir), baseline);
     }
   }
@@ -1713,15 +2027,14 @@ async function runPipeline(options) {
   const view = session ? await readingStore(() => openSession(session.dir, session.agent), empty()) : empty();
   const disabled = new Set(view.work.disabled.keys());
   const resolver = createReferenceResolver(root);
+  const detection = detectionFor(project, registry, stateDir, resolver);
   const workRecords = [];
   const relevant = (files) => files.filter((file) => project.rules.some((rule) => rule.matches(file)));
   if (event.kind === "guard") {
     const open2 = session;
     const delivery = await guardWrite({
-      root,
+      detection,
       config,
-      registry,
-      stateDir,
       event,
       rules: project.rules,
       disabled,
@@ -1730,12 +2043,16 @@ async function runPipeline(options) {
       maxContextChars: options.maxContextChars,
       log,
       record: open2 ? (records) => appendWork(open2.dir, records) : async () => {
+      },
+      recordContext: open2 ? (records) => appendContext(open2.dir, open2.agent, records) : async () => {
       }
     });
     return { delivery, failed, deadlineMissed };
   }
   let touches = [];
   let findings = [];
+  let ignored = [];
+  let told = [];
   let agentRead = null;
   if (event.kind === "touch" || event.kind === "edit") {
     touches = selectTouchRules(project.rules, event.files, view.context.touched, disabled);
@@ -1751,96 +2068,55 @@ async function runPipeline(options) {
     const recent = (view.work.accessed.get(session.agent) ?? []).slice(-restoredFiles).reverse();
     touches = selectTouchRules(project.rules, recent, view.context.touched, disabled);
   }
+  const baselineInput = {
+    root,
+    detection,
+    rules: project.rules,
+    disabled,
+    limits: {
+      editDeadlineMs: config.timeouts.editDeadlineMs,
+      verifyMs: config.timeouts.verifyMs,
+      maxFileBytes: config.maxFileBytes
+    }
+  };
   if (event.kind === "touch") {
     if (event.completeRead) agentRead = event.files[0] ?? null;
-    if (session) {
-      const records = [];
-      const snapshotted = [];
-      for (const file of relevant(event.files)) {
-        if (baseline.snapshots.has(file)) continue;
-        const text = await readSourceFile(root, file);
-        if (text === null) continue;
-        records.push(snapshotRecord(file, snapshotOf(text)));
-        snapshotted.push(file);
-      }
-      if (snapshotted.length > 0) {
-        records.push(
-          ...await recordFingerprints({
-            root,
-            files: snapshotted,
-            rules: project.rules,
-            disabled,
-            registry,
-            read: (file) => readSourceFile(root, file),
-            cacheFor: (kind) => diskCache(detectorCacheDir(stateDir, kind)),
-            contextFor: (rule) => resolveRuleContext(resolver, rule.context),
-            settings: { llm: config.llm },
-            event: "edit",
-            source: "disk",
-            timeoutMs: config.timeouts.editDeadlineMs,
-            ceiling: { maxFileBytes: config.maxFileBytes, sizeOf: (file) => fileBytes(root, file) }
-          })
-        );
-      }
-      await appendBaseline(session.dir, records);
-    }
+    if (session) await appendBaseline(session.dir, await touchRecords(baselineInput, baseline, relevant(event.files)));
   }
   if (event.kind === "edit" || event.kind === "verify") {
-    let files = relevant(event.files);
-    let snapshots = session ? baseline.snapshots : /* @__PURE__ */ new Map();
-    let fallbackCommit = session ? baseline.startCommit : null;
+    let requested = relevant(event.files);
     if (event.kind === "edit" && session) {
       await appendWork(
         session.dir,
-        files.map((file) => ({ t: "edited", file }))
+        requested.map((file) => ({ t: "edited", file }))
       );
     }
-    if (event.kind === "verify") {
-      if (event.baseCommit) {
-        fallbackCommit = event.baseCommit;
-        snapshots = /* @__PURE__ */ new Map();
-      }
-      if (event.files.length === 0 && session) files = relevant(view.work.edited);
-    }
-    const baselineChanges = await computeChanges(root, files, { snapshots, fallbackCommit });
+    if (event.kind === "verify" && event.files.length === 0 && session) requested = relevant(view.work.edited);
+    const read = contentReader(root, event.kind === "verify" ? event.content ?? WORKTREE : WORKTREE);
+    const stage = await changesFor(
+      baselineInput,
+      { kind: event.kind, baseCommit: event.baseCommit },
+      session ? baseline : null,
+      requested,
+      read
+    );
+    const { files, changes: baselineChanges, fingerprints } = stage;
     const changes = baselineChanges.sets;
-    if (event.kind === "verify" && session && !event.baseCommit) {
-      files = files.filter((file) => changes.get(file)?.changedLines.length !== 0);
-    }
-    if (event.kind === "verify" && baselineChanges.fromCommit.size > 0) {
-      const texts = baselineChanges.fromCommit;
-      const missing = [...texts.keys()].filter((file) => !baseline.fingerprints.has(file));
-      const records = missing.length === 0 ? [] : await recordFingerprints({
-        root,
-        files: missing,
-        rules: project.rules,
-        disabled,
-        registry,
-        read: async (file) => texts.get(file) ?? null,
-        cacheFor: (kind) => diskCache(detectorCacheDir(stateDir, kind)),
-        contextFor: (rule) => resolveRuleContext(resolver, rule.context),
-        settings: { llm: config.llm },
-        event: "verify",
-        source: "memory",
-        timeoutMs: config.timeouts.verifyMs
-      });
-      for (const record of records) {
-        if (record.t !== "fingerprint") continue;
-        const byRule = baseline.fingerprints.get(record.file) ?? /* @__PURE__ */ new Map();
-        baseline.fingerprints.set(record.file, byRule);
-        byRule.set(record.rule, record.ranges);
-      }
-      if (session && records.length > 0) await appendBaseline(session.dir, records);
-    }
+    if (session && stage.records.length > 0) await appendBaseline(session.dir, stage.records);
     const skip = options.skipDetectorKinds ?? /* @__PURE__ */ new Set();
     let selections = selectDetectorRules(project.rules, event.kind, files, disabled).filter(
       (selection) => !skip.has(selection.rule.detector.kind) && (options.onlyRules?.has(selection.rule.id) ?? true)
     );
-    let overBudget = [];
+    const overBudget = [];
     if (event.kind === "verify") {
-      const budgeted = applyFileBudget("llm", selections, config.llm.maxFilesPerVerify, [...view.work.edited].reverse());
-      selections = budgeted.selections;
-      overBudget = budgeted.skipped;
+      const recent = [...view.work.edited].reverse();
+      for (const kind of new Set(selections.map((selection) => selection.rule.detector.kind))) {
+        const budget = registry.get(kind)?.fileBudget?.(detection.settings);
+        if (budget === void 0) continue;
+        const budgeted = applyFileBudget(kind, selections, budget.max, recent);
+        selections = budgeted.selections;
+        if (budgeted.skipped.length > 0) overBudget.push({ kind, ...budget, skipped: budgeted.skipped });
+      }
     }
     if (event.kind === "edit") {
       const ceiling = await applySizeCeiling(
@@ -1854,35 +2130,54 @@ async function runPipeline(options) {
         log(`over max_file_bytes (${config.maxFileBytes}), not checked on this edit: ${ceiling.skipped.join(", ")}`);
       }
     }
-    const output = await runDetection({
-      root,
-      event: event.kind,
-      selections,
-      changes,
-      read: (file) => readSourceFile(root, file),
-      registry,
-      cacheFor: (kind) => diskCache(detectorCacheDir(stateDir, kind)),
-      contextFor: (rule) => resolveRuleContext(resolver, rule.context),
-      settings: { llm: config.llm },
-      timeoutMs: event.kind === "edit" ? config.timeouts.editDeadlineMs : config.timeouts.verifyMs
-    });
+    const output = await runDetectionFrom(
+      {
+        detection,
+        event: event.kind,
+        selections,
+        changes,
+        read,
+        timeoutMs: event.kind === "edit" ? config.timeouts.editDeadlineMs : config.timeouts.verifyMs
+      },
+      event.kind === "verify" ? event.content ?? WORKTREE : WORKTREE
+    );
     findings = output.findings.map(({ rule, match }) => ({
       rule,
       match,
-      status: classify(match, rule.scope, rule.id, baselineChanges, baseline.fingerprints)
+      status: classify(match, rule.scope, rule.id, baselineChanges, fingerprints)
     }));
     for (const error of output.errors) {
       failed = true;
       log(`${error.kind} detector failed for ${error.rules.join(", ")}: ${error.message}`);
       for (const rule of error.rules) workRecords.push({ t: "disabled", rule, reason: error.message });
     }
-    warnings.push(...detectorWarnings(output.errors));
-    if (overBudget.length > 0) {
+    warnings.push(...detectorWarnings(output.errors, session === null ? "run" : "session"));
+    ignored = output.ignored;
+    if (options.stopGate === true && event.kind === "verify" && session !== null) {
+      told = notices({
+        startConfigHash: baseline.startConfigHash ?? null,
+        currentConfigHash: await configHash(root),
+        ignored: ignored.map(({ rule, match, reason }) => ({
+          rule: rule.id,
+          match,
+          reason,
+          status: classify(match, rule.scope, rule.id, baselineChanges, fingerprints)
+        })),
+        told: view.work.noticed
+      });
+      for (const notice of told) for (const key of notice.key.split("\n")) workRecords.push({ t: "noticed", key });
+    }
+    for (const text of output.warnings) warnings.push({ key: `ignore:${text}`, text });
+    for (const { kind, max, setting, skipped } of overBudget) {
       warnings.push({
-        key: `llm-budget:${overBudget.join(",")}`,
-        text: `llm rules checked ${config.llm.maxFilesPerVerify} files; ${overBudget.length} were not checked: ${overBudget.join(", ")}. Raise llm.max_files_per_verify, or run rulecast run --files on them.`
+        key: `${kind}-budget:${skipped.join(",")}`,
+        text: `${kind} rules checked ${max} files; ${skipped.length} were not checked: ${skipped.join(", ")}. Raise ${setting}, or run rulecast run --files on them.`
       });
     }
+    const hintFor = (kind) => {
+      const hint = registry.get(kind)?.timeoutHint;
+      return hint === void 0 ? "" : ` (${hint})`;
+    };
     for (const timeout of output.timedOut) {
       if (event.kind === "edit") {
         log(`edit deadline passed for ${timeout.kind}: ${timeout.rules.join(", ")}`);
@@ -1893,7 +2188,7 @@ async function runPipeline(options) {
           key: `timeout:${timeout.kind}:${timeout.rules.join(",")}`,
           // Naming the lever matters: a field trial measured a single haiku call on a 135-line file
           // at 89 s against a 60 s default, and "timed out" alone leaves nobody knowing what to do.
-          text: `${timeout.kind} detector timed out after ${config.timeouts.verifyMs} ms for ${timeout.rules.join(", ")}. Raise timeouts.verify_ms${timeout.kind === "llm" ? " (an llm rule on a large file can need 120000 or more)" : ""}.`
+          text: `${timeout.kind} detector timed out after ${config.timeouts.verifyMs} ms for ${timeout.rules.join(", ")}. Raise timeouts.verify_ms${hintFor(timeout.kind)}.`
         });
       }
     }
@@ -1913,17 +2208,30 @@ async function runPipeline(options) {
     maxMatchesPerRule: config.maxMatchesPerRule,
     stopGate: options.stopGate === true && event.kind === "verify" && session !== null
   });
+  const home = path14.dirname(path14.dirname(stateDir));
   const persisted = (decision) => {
     if (decision.overflow !== null) {
-      decision.delivery.overflowPath = writeOverflow(stateDir, event.session?.id ?? null, decision.overflow);
+      let written = null;
+      try {
+        written = writeOverflow(path14.join(agentDir(root), "deliveries"), event.session?.id ?? null, decision.overflow);
+      } catch {
+        written = null;
+      }
+      decision.delivery.overflowPath = written === null ? null : path14.relative(root, written).split(path14.sep).join("/");
+    }
+    for (const reference of decision.delivery.references) {
+      if (reference.location === void 0 || !path14.isAbsolute(reference.location)) continue;
+      const copied = copyIntoProject(root, home, reference.location);
+      if (copied !== null) reference.location = copied;
     }
+    if (told.length > 0) decision.delivery.notices = told.map((notice) => notice.text);
     return decision.delivery;
   };
-  if (!session) return { delivery: persisted(await decide(inputFor(view))), failed, deadlineMissed };
+  if (!session) return { delivery: persisted(await decide(inputFor(view))), failed, deadlineMissed, ignored };
   await appendWork(session.dir, workRecords);
   try {
     const decision = await commitSession(session.dir, session.agent, (state) => decide(inputFor(state)));
-    return { delivery: persisted(decision), failed, deadlineMissed };
+    return { delivery: persisted(decision), failed, deadlineMissed, ignored };
   } catch (error) {
     if (error instanceof CorruptStoreError) {
       log(`session store unreadable: ${error.message}`);
@@ -1932,7 +2240,7 @@ async function runPipeline(options) {
       warnings.push({ key: "lock", text: "session state was locked; delivered without session memory" });
     } else throw error;
     const decision = await decide({ ...inputFor({ work: emptyWork(), context: emptyContext() }), stopGate: false });
-    return { delivery: persisted(decision), failed, deadlineMissed };
+    return { delivery: persisted(decision), failed, deadlineMissed, ignored };
   }
 }
 
@@ -1940,10 +2248,12 @@ export {
   defaultConfig,
   CONFIG_FILE,
   MANIFEST_FILE,
+  readYamlFile,
   readConfigData,
   parseConfig,
   readManifest,
   git,
+  headCommit,
   mergeBase,
   changedFilesSince,
   allFiles,
@@ -1964,14 +2274,16 @@ export {
   diagnosticText,
   compile,
   compileManifest,
+  createReferenceResolver,
   rulesOfKind,
   checkableKinds,
   checkDetectors,
+  detectionFor,
   runDetection,
   cachedRepos,
   fetchingRepos,
   fixedRepo,
-  resolveRuleContext,
-  createReferenceResolver,
+  WORKTREE,
+  withScratchTree,
   runPipeline
 };