backpass 0.1.0

package/src/redact.js

@@ -0,0 +1,36 @@
+/**
+ * Distilled traces are handed to a model the user configured, but they are still built
+ * from raw session logs. Obvious secret shapes are redacted before that happens
+ * (design section 9, privacy). This is a coarse net, not a guarantee: it catches the
+ * common token formats and `KEY=value` assignments that show up in shell transcripts.
+ */
+
+const PATTERNS = [
+  [/\b(sk-ant-[A-Za-z0-9_-]{16,})/g, "ANTHROPIC_KEY"],
+  [/\b(sk-proj-[A-Za-z0-9_-]{16,})/g, "OPENAI_KEY"],
+  [/\b(sk-or-v1-[A-Za-z0-9_-]{16,})/g, "OPENROUTER_KEY"],
+  [/\b(sk-[A-Za-z0-9]{32,})/g, "API_KEY"],
+  [/\b(gh[pousr]_[A-Za-z0-9]{16,})/g, "GITHUB_TOKEN"],
+  [/\b(xox[abposr]-[A-Za-z0-9-]{10,})/g, "SLACK_TOKEN"],
+  [/\b(AKIA[0-9A-Z]{16})\b/g, "AWS_ACCESS_KEY_ID"],
+  [/\b(eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})/g, "JWT"],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "PRIVATE_KEY"],
+  [
+    /\b([A-Za-z0-9_]*(?:SECRET|TOKEN|PASSWORD|PASSWD|API_?KEY|ACCESS_?KEY)[A-Za-z0-9_]*)\s*[=:]\s*["']?([^\s"']{8,})["']?/gi,
+    "ASSIGNMENT",
+  ],
+];
+
+export function redact(text) {
+  if (!text) return text;
+  let out = String(text);
+  for (const [pattern, label] of PATTERNS) {
+    out = out.replace(pattern, (match, first, second) => {
+      if (label !== "ASSIGNMENT") return `[redacted:${label}]`;
+      // A specific pattern above may already have replaced the value; keep its label.
+      if (typeof second === "string" && second.startsWith("[redacted")) return match;
+      return `${first}=[redacted]`;
+    });
+  }
+  return out;
+}

package/src/repo.js

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+import { UserError } from "./logger.js";
+
+function git(args, cwd) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+
+function realpathOrSelf(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * Normalize a git remote to a comparable identity.
+ *
+ *   git@github.com:kunchenguid/backpass.git  ->  github.com/kunchenguid/backpass
+ *   https://github.com/kunchenguid/backpass  ->  github.com/kunchenguid/backpass
+ *   /Users/kun/src/backpass                  ->  /users/kun/src/backpass  (local path remote)
+ */
+export function normalizeRemote(remote) {
+  if (!remote) return null;
+  let s = String(remote).trim();
+  if (!s) return null;
+  s = s.replace(/^[a-z+]+:\/\//i, "");
+  s = s.replace(/^[^/@]+@/, "");
+  s = s.replace(/:(?=[^/])/, "/");
+  s = s.replace(/\.git\/?$/i, "");
+  s = s.replace(/\/+$/, "");
+  return s.toLowerCase() || null;
+}
+
+/** Worktree paths for the repo, realpath-normalized (design section 2.1, tier 1). */
+function listWorktrees(root) {
+  let raw;
+  try {
+    raw = git(["worktree", "list", "--porcelain"], root);
+  } catch {
+    return [realpathOrSelf(root)];
+  }
+  const paths = [];
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("worktree ")) paths.push(realpathOrSelf(line.slice("worktree ".length)));
+  }
+  if (!paths.length) paths.push(realpathOrSelf(root));
+  return [...new Set(paths)];
+}
+
+function listRemotes(root) {
+  let raw;
+  try {
+    raw = git(["remote", "-v"], root);
+  } catch {
+    return [];
+  }
+  const out = new Set();
+  for (const line of raw.split("\n")) {
+    const url = line.split(/\s+/)[1];
+    const norm = normalizeRemote(url);
+    if (norm) out.add(norm);
+  }
+  return [...out];
+}
+
+/**
+ * Ensure `line` is present in this repo's *local* git exclude file
+ * (`.git/info/exclude`) - never a tracked file the user owns. The path is
+ * resolved via `git rev-parse --git-path info/exclude` rather than assumed,
+ * since in a worktree or submodule `.git` is a file, not a directory, and
+ * `info/exclude` lives in the shared common git dir. Idempotent: a line
+ * already present is left alone.
+ *
+ * Returns `{ status: "added" | "present" | "no-git", path? }`.
+ */
+export function ensureLocalExclude(root, line) {
+  let excludePath;
+  try {
+    excludePath = git(["rev-parse", "--git-path", "info/exclude"], root);
+  } catch {
+    return { status: "no-git" };
+  }
+  const resolved = path.isAbsolute(excludePath) ? excludePath : path.join(root, excludePath);
+
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  const current = fs.existsSync(resolved) ? fs.readFileSync(resolved, "utf8") : "";
+  if (current.split("\n").some((l) => l.trim() === line)) {
+    return { status: "present", path: resolved };
+  }
+  const separator = current && !current.endsWith("\n") ? "\n" : "";
+  fs.appendFileSync(resolved, `${separator}${line}\n`);
+  return { status: "added", path: resolved };
+}
+
+/**
+ * Repo identity used by every discovery adapter.
+ * `commonDir` distinguishes worktrees of the same repository.
+ */
+export function resolveRepo(cwd = process.cwd()) {
+  let root;
+  try {
+    root = git(["rev-parse", "--show-toplevel"], cwd);
+  } catch {
+    throw new UserError("not inside a git repository", "backpass runs per-repo; cd into a repo and retry");
+  }
+  const realRoot = realpathOrSelf(root);
+  return {
+    root,
+    realRoot,
+    name: path.basename(realRoot),
+    worktrees: listWorktrees(root),
+    remotes: listRemotes(root),
+  };
+}

package/src/sample.js

@@ -0,0 +1,99 @@
+import { parseMaxTranscripts, parseSince } from "./config.js";
+import { color, info } from "./logger.js";
+
+/**
+ * Recency-weighted capping of the discovered transcript set.
+ *
+ * Analysis costs one model call per transcript, so a repo with a long history (or a
+ * `--since all` run) needs a bound. A plain "newest N" cut would silently erase the
+ * older history; instead, when discovery exceeds `maxTranscripts` we draw a weighted
+ * sample WITHOUT replacement where each transcript's weight decays exponentially with
+ * its age: weight = 2^(-age / halfLife). Recent sessions are almost always kept, old
+ * ones are still represented in proportion to their weight.
+ *
+ * Sampling uses the Efraimidis-Spirakis one-pass scheme: key = -ln(u) / weight with
+ * u ~ U(0, 1), keep the N smallest keys. That is exactly weighted sampling without
+ * replacement (an exponential race with rate = weight), needs no rejection loop, and is
+ * O(n log n). The RNG is a seedable splitmix32 so runs are reproducible with `--seed`.
+ *
+ * This module is pure: it never touches the cache, so evidence for a sampled transcript
+ * is reused by the analyzer exactly as before.
+ */
+
+export const DEFAULT_SAMPLE_HALF_LIFE = "14d";
+
+/** splitmix32: small, seedable, and uniform enough for sampling keys. */
+export function seededRandom(seed) {
+  let state = Number(seed) >>> 0 || 0x9e3779b9;
+  return () => {
+    state = (state + 0x9e3779b9) | 0;
+    let t = state ^ (state >>> 16);
+    t = Math.imul(t, 0x21f0aaad);
+    t ^= t >>> 15;
+    t = Math.imul(t, 0x735a2d97);
+    t ^= t >>> 15;
+    return (t >>> 0) / 4294967296;
+  };
+}
+
+/** Epoch ms a transcript is dated to: the session start, else the file mtime. */
+export function transcriptTime(transcript) {
+  const at = Number(transcript.startedAt);
+  if (Number.isFinite(at) && at > 0) return at;
+  const mtime = Number(transcript.mtimeMs);
+  return Number.isFinite(mtime) && mtime > 0 ? mtime : null;
+}
+
+/** 2^(-age / halfLife), clamped so an undated or ancient transcript still has a chance. */
+export function recencyWeight(transcript, { now, halfLifeMs }) {
+  const at = transcriptTime(transcript);
+  if (at === null) return 1e-9;
+  const age = Math.max(0, now - at);
+  return Math.max(1e-9, Math.pow(2, -age / halfLifeMs));
+}
+
+/**
+ * Weighted sample without replacement of `count` transcripts. Returns the kept
+ * transcripts in their original (newest-first) order so downstream output is stable.
+ */
+/**
+ * @param {object[]} transcripts
+ * @param {number | null} count
+ * @param {{ seed?: number, now?: number, halfLife?: string }} [options]
+ */
+export function sampleTranscripts(
+  transcripts,
+  count,
+  { seed, now = Date.now(), halfLife = DEFAULT_SAMPLE_HALF_LIFE } = {},
+) {
+  if (count === null || transcripts.length <= count) return transcripts;
+  const random = seededRandom(seed ?? Math.floor(Math.random() * 0xffffffff));
+  const halfLifeMs = parseSince(halfLife) ?? Infinity;
+  const keyed = transcripts.map((transcript, index) => {
+    const u = random() || Number.EPSILON;
+    return { index, key: -Math.log(u) / recencyWeight(transcript, { now, halfLifeMs }) };
+  });
+  keyed.sort((a, b) => a.key - b.key);
+  const kept = new Set(keyed.slice(0, count).map((k) => k.index));
+  return transcripts.filter((_, index) => kept.has(index));
+}
+
+/**
+ * Apply the configured cap to a discovery result, reporting it on stderr when sampling
+ * actually happened. Under the cap the set passes through untouched and nothing is
+ * printed.
+ */
+export function capTranscripts(result, config, { now = Date.now() } = {}) {
+  const cap = parseMaxTranscripts(config.maxTranscripts);
+  const discovered = result.transcripts.length;
+  if (cap === null || discovered <= cap) return result;
+  const sampled = sampleTranscripts(result.transcripts, cap, {
+    seed: config.seed ?? undefined,
+    now,
+    halfLife: config.sampleHalfLife,
+  });
+  info(
+    `${color.yellow("·")} discovered ${discovered} transcript(s), analyzing a recency-weighted sample of ${sampled.length} (--max-transcripts)`,
+  );
+  return { ...result, transcripts: sampled, sampledFrom: discovered };
+}

package/src/skills.js

@@ -0,0 +1,207 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { estimateTokens } from "./tokens.js";
+
+/**
+ * Skills as overflow (design section 7).
+ *
+ * A skill's description IS its when-useful condition: the description is always loaded
+ * and cheap, the body is free until the trigger fires. That makes extraction the release
+ * valve for the always-loaded budget - a 640-token procedure that matters in 4% of
+ * sessions becomes a 35-token description line.
+ *
+ * The placement rule the synthesis prompt encodes:
+ *
+ *                    | trigger detectable | trigger not detectable
+ *   broad (>=20%)    | memory file        | memory file (must be ambient)
+ *   narrow           | SKILL              | deletion candidate
+ */
+
+export const BROAD_RELEVANCE_THRESHOLD = 0.2;
+
+/** Read the existing skills so synthesis can tune a description instead of duplicating it. */
+export function loadSkills(repoRoot, skillsDir) {
+  const root = path.join(repoRoot, skillsDir);
+  if (!fs.existsSync(root)) return [];
+
+  const skills = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  for (const entry of entries) {
+    const file = entry.isDirectory()
+      ? path.join(root, entry.name, "SKILL.md")
+      : entry.name.endsWith(".md")
+        ? path.join(root, entry.name)
+        : null;
+    if (!file || !fs.existsSync(file)) continue;
+    let text;
+    try {
+      text = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const frontmatter = parseFrontmatter(text);
+    skills.push({
+      name: frontmatter.name || entry.name.replace(/\.md$/, ""),
+      description: frontmatter.description || "",
+      path: path.relative(repoRoot, file),
+      bodyTokens: estimateTokens(text),
+      descriptionTokens: estimateTokens(frontmatter.description || ""),
+    });
+  }
+
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Minimal YAML frontmatter reader: only `key: value` and folded multi-line values. */
+export function parseFrontmatter(text) {
+  const match = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!match) return {};
+  const result = {};
+  let currentKey = null;
+  for (const line of match[1].split("\n")) {
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (kv) {
+      currentKey = kv[1];
+      result[currentKey] = kv[2].trim().replace(/^["']|["']$/g, "");
+    } else if (currentKey && /^\s+\S/.test(line)) {
+      result[currentKey] = `${result[currentKey]} ${line.trim()}`.trim();
+    }
+  }
+  return result;
+}
+
+export function renderSkillIndex(skills) {
+  if (!skills.length) return "(no skills directory found in this repo)";
+  return skills
+    .map(
+      (s) =>
+        `- ${s.name} (${s.bodyTokens} tok body, ${s.descriptionTokens} tok description) :: ${s.description || "(no description)"}`,
+    )
+    .join("\n");
+}
+
+/** Serialize a skill draft to the common SKILL.md shape. */
+export function renderSkillFile(skill) {
+  const description = skill.description.replace(/\n+/g, " ").trim();
+  // Generated skills are reference material that fires on its description, never a
+  // slash-command: mark them non-invocable and internal so harnesses keep them out of
+  // the user-facing command list.
+  const frontmatter = [
+    `name: ${skill.name}`,
+    `description: ${description}`,
+    "user-invocable: false",
+    "metadata:",
+    "  internal: true",
+  ].join("\n");
+  return `---\n${frontmatter}\n---\n\n${skill.body.trim()}\n`;
+}
+
+/**
+ * The budget arithmetic that makes extraction worth it, reported per edit:
+ * "-1,900 tok always-loaded, +140 tok description".
+ */
+export function extractionBudgetEffect(edit) {
+  if (edit.kind !== "extract" || !edit.skill) return null;
+  const pairs = Array.isArray(edit.hunks) ? edit.hunks : [edit];
+  const removedFromMemory = pairs.reduce((sum, p) => sum + estimateTokens(p.find) - estimateTokens(p.replace), 0);
+  const descriptionCost = estimateTokens(edit.skill.description);
+  return {
+    alwaysLoadedDelta: -removedFromMemory,
+    descriptionCost,
+    net: descriptionCost - removedFromMemory,
+    skillBodyTokens: estimateTokens(edit.skill.body),
+  };
+}
+
+/** Where agents actually auto-load skills from: the AGENTS.md convention. */
+export const CANONICAL_SKILLS_DIR = ".agents/skills";
+/** Claude reads this path; it is kept as a symlink into the canonical dir, never a copy. */
+export const CLAUDE_SKILLS_LINK = ".claude/skills";
+export const CLAUDE_SKILLS_LINK_TARGET = path.posix.join("..", CANONICAL_SKILLS_DIR);
+
+/**
+ * Pick the directory skill extractions target.
+ *
+ * Skills only pay off if the harness loads them, so the answer is the canonical
+ * `.agents/skills` (mirrored to `.claude/skills` by symlink) unless the user explicitly
+ * configured another directory that already exists. The bare `skills/` dir is an
+ * installer/public convention that no harness auto-loads, so it is never auto-detected -
+ * it is only honored when named in the config. Resolution is read-only; the layout is
+ * created at write time (`ensureSkillsLayout`), which keeps every pre-apply stage
+ * side-effect free.
+ */
+export function resolveOverflowTarget(repoRoot, skillsDir = CANONICAL_SKILLS_DIR) {
+  const warnings = [];
+  const claude = inspectClaudeSkillsLink(repoRoot);
+  if (claude.state === "dir") warnings.push(claudeSkillsDirWarning());
+
+  const explicit = skillsDir && skillsDir !== CANONICAL_SKILLS_DIR && skillsDir !== CLAUDE_SKILLS_LINK;
+  if (explicit && fs.existsSync(path.join(repoRoot, skillsDir))) {
+    return { kind: "skills", dir: skillsDir, warnings };
+  }
+  return { kind: "skills", dir: CANONICAL_SKILLS_DIR, warnings };
+}
+
+function claudeSkillsDirWarning() {
+  return (
+    `${CLAUDE_SKILLS_LINK} is a real directory, not a symlink to ${CLAUDE_SKILLS_LINK_TARGET}; ` +
+    `left untouched. Claude will not see skills written to ${CANONICAL_SKILLS_DIR} until you ` +
+    `merge it in and replace it with the symlink (ln -s ${CLAUDE_SKILLS_LINK_TARGET} ${CLAUDE_SKILLS_LINK}).`
+  );
+}
+
+function inspectClaudeSkillsLink(repoRoot) {
+  let stat;
+  try {
+    stat = fs.lstatSync(path.join(repoRoot, CLAUDE_SKILLS_LINK));
+  } catch {
+    return { state: "missing" };
+  }
+  if (stat.isSymbolicLink()) return { state: "symlink" };
+  if (stat.isDirectory()) return { state: "dir" };
+  return { state: "other" };
+}
+
+/**
+ * Create the canonical skills dir and the `.claude/skills -> ../.agents/skills` symlink
+ * so both harness families load the same files with no duplication. An existing
+ * `.claude/skills` is never clobbered: a symlink (to anywhere) is left as is, and a real
+ * directory is reported so the user can merge it by hand.
+ */
+export function ensureSkillsLayout(repoRoot) {
+  const created = [];
+  const warnings = [];
+  const canonical = path.join(repoRoot, CANONICAL_SKILLS_DIR);
+  if (!fs.existsSync(canonical)) {
+    fs.mkdirSync(canonical, { recursive: true });
+    created.push(CANONICAL_SKILLS_DIR);
+  }
+
+  const claude = inspectClaudeSkillsLink(repoRoot);
+  if (claude.state === "missing") {
+    const link = path.join(repoRoot, CLAUDE_SKILLS_LINK);
+    fs.mkdirSync(path.dirname(link), { recursive: true });
+    fs.symlinkSync(CLAUDE_SKILLS_LINK_TARGET, link, "dir");
+    created.push(`${CLAUDE_SKILLS_LINK} -> ${CLAUDE_SKILLS_LINK_TARGET}`);
+  } else if (claude.state === "dir") {
+    warnings.push(claudeSkillsDirWarning());
+  }
+  return { created, warnings };
+}
+
+/** Write an accepted skill extraction to disk, setting up the load layout on first use. */
+export function writeSkill(repoRoot, skill) {
+  const inCanonical = skill.path === CANONICAL_SKILLS_DIR || skill.path.startsWith(`${CANONICAL_SKILLS_DIR}/`);
+  const layout = inCanonical ? ensureSkillsLayout(repoRoot) : { created: [], warnings: [] };
+  const target = path.join(repoRoot, skill.path);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, renderSkillFile(skill));
+  return { target, ...layout };
+}

package/src/state.js

@@ -0,0 +1,202 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+import { STATE_DIRNAME } from "./config.js";
+import { warn } from "./logger.js";
+import { ensureLocalExclude } from "./repo.js";
+
+/** The line every command writes to the repo's local git exclude for the state dir. */
+export const STATE_EXCLUDE_LINE = `${STATE_DIRNAME}/`;
+
+/**
+ * All mutable run state lives in a `.backpass/` directory, kept out of git via the
+ * repo's local exclude (`.git/info/exclude`, written idempotently by `ensure()` on every
+ * command, so a plain `backpass` run with no prior `init` is excluded too) rather than
+ * the tracked `.gitignore`:
+ *
+ *   scan-cache.json        path+mtime+size -> association verdict (design section 2.2)
+ *   evidence/<id>.json     per-transcript tier-1 analysis output (design section 3)
+ *   evidence-summary.json  folded evidence (stage 2)
+ *   proposal.json          latest tier-2 synthesis (stage 3)
+ *   rejections.json        edits the human rejected, and the evidence weight behind them
+ *   gap-ledger.json        gap observations by gap and session, accumulated across runs (src/gap-ledger.js)
+ *   agent-probe-cache.json TTL'd availability/auth verdicts per agent|model (src/agents.js)
+ *   prompts/               the exact prompts of the last run, one file per model turn
+ *   synthesis/             the staging copy the synthesis agent edits natively (src/workspace.js)
+ *   apply/                 the rendered Lavish apply surface
+ */
+export class State {
+  constructor(repoRoot) {
+    this.root = path.join(repoRoot, STATE_DIRNAME);
+    this.evidenceDir = path.join(this.root, "evidence");
+    this.applyDir = path.join(this.root, "apply");
+    this.scanCachePath = path.join(this.root, "scan-cache.json");
+    this.summaryPath = path.join(this.root, "evidence-summary.json");
+    this.proposalPath = path.join(this.root, "proposal.json");
+    this.rejectionsPath = path.join(this.root, "rejections.json");
+    this.gapLedgerPath = path.join(this.root, "gap-ledger.json");
+    this.probeCachePath = path.join(this.root, "agent-probe-cache.json");
+  }
+
+  /**
+   * Creates the state dir and excludes it from git in the same step. The exclude is
+   * local-only and fail-soft: a non-git directory is silently left alone.
+   */
+  ensure() {
+    fs.mkdirSync(this.evidenceDir, { recursive: true });
+    fs.mkdirSync(this.applyDir, { recursive: true });
+    this.exclude = ensureLocalExclude(path.dirname(this.root), STATE_EXCLUDE_LINE);
+    return this;
+  }
+
+  readJsonFile(file, fallback) {
+    if (!fs.existsSync(file)) return fallback;
+    try {
+      return JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch (err) {
+      warn(`discarding corrupt state file ${path.relative(process.cwd(), file)}: ${err.message}`);
+      return fallback;
+    }
+  }
+
+  writeJsonFile(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+    fs.renameSync(tmp, file);
+  }
+
+  readScanCache() {
+    const cache = this.readJsonFile(this.scanCachePath, null);
+    return cache && cache.version === 1 ? cache : { version: 1, entries: {} };
+  }
+
+  writeScanCache(cache) {
+    this.writeJsonFile(this.scanCachePath, cache);
+  }
+
+  evidencePath(transcriptId) {
+    return path.join(this.evidenceDir, `${safeFileName(transcriptId)}.json`);
+  }
+
+  readEvidence(transcriptId) {
+    return this.readJsonFile(this.evidencePath(transcriptId), null);
+  }
+
+  writeEvidence(transcriptId, evidence) {
+    this.writeJsonFile(this.evidencePath(transcriptId), evidence);
+  }
+
+  listEvidence() {
+    if (!fs.existsSync(this.evidenceDir)) return [];
+    return fs
+      .readdirSync(this.evidenceDir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => this.readJsonFile(path.join(this.evidenceDir, f), null))
+      .filter(Boolean);
+  }
+
+  readSummary() {
+    return this.readJsonFile(this.summaryPath, null);
+  }
+
+  writeSummary(summary) {
+    this.writeJsonFile(this.summaryPath, summary);
+  }
+
+  readProposal() {
+    return this.readJsonFile(this.proposalPath, null);
+  }
+
+  writeProposal(proposal) {
+    this.writeJsonFile(this.proposalPath, proposal);
+  }
+
+  readRejections() {
+    const value = this.readJsonFile(this.rejectionsPath, null);
+    return value && value.version === 1 ? value : { version: 1, entries: {} };
+  }
+
+  writeRejections(rejections) {
+    this.writeJsonFile(this.rejectionsPath, rejections);
+  }
+
+  /** Fail-soft: a missing or corrupt ledger starts empty and is rebuilt from this run's evidence. */
+  readGapLedger() {
+    const value = this.readJsonFile(this.gapLedgerPath, null);
+    return value && value.version === 1 && value.entries && typeof value.entries === "object"
+      ? value
+      : { version: 1, entries: {} };
+  }
+
+  writeGapLedger(ledger) {
+    this.writeJsonFile(this.gapLedgerPath, ledger);
+  }
+
+  readProbeCache() {
+    const value = this.readJsonFile(this.probeCachePath, null);
+    return value && value.version === 1 ? value : { version: 1, acpxVersion: null, entries: {} };
+  }
+
+  writeProbeCache(cache) {
+    this.writeJsonFile(this.probeCachePath, cache);
+  }
+}
+
+export function safeFileName(id) {
+  return String(id)
+    .replace(/[^A-Za-z0-9._-]/g, "_")
+    .slice(0, 120);
+}
+
+export function sha256(text) {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+/**
+ * Cache key for a transcript's analysis: the transcript's own content signature plus
+ * the memory-file hash it was judged against. Either changing invalidates the evidence.
+ */
+export function evidenceKey(transcript, memoryHash) {
+  return `${transcript.mtimeMs}:${transcript.bytes}:${memoryHash}`;
+}
+
+/**
+ * Only a successful analysis is worth caching. A `failed` entry is retried, and a
+ * `skipped` entry is re-derived because the skip decision depends on configuration
+ * (`minUserTurns`) rather than on the model - recomputing it costs one local file read.
+ */
+export function isEvidenceFresh(evidence, transcript, memoryHash) {
+  if (!evidence || evidence.status !== "ok") return false;
+  return evidence.key === evidenceKey(transcript, memoryHash);
+}
+
+/**
+ * A rejected edit stays rejected until materially new evidence arrives - the design's
+ * replacement for a DEFER button (captain tweak 3). "Materially new" means the edit is
+ * backed by strictly more transcripts than when it was turned down.
+ */
+export function rejectionKey(edit) {
+  const body = Array.isArray(edit.hunks)
+    ? edit.hunks.map((h) => `${h.find}\u0000${h.replace}`).join("\u0001")
+    : `${edit.find || ""}\u0000${edit.replace || ""}`;
+  return sha256([edit.kind, edit.file, body].join(" ")).slice(0, 16);
+}
+
+export function isSuppressedByRejection(edit, rejections) {
+  const prior = rejections.entries[rejectionKey(edit)];
+  if (!prior) return false;
+  return (edit.transcripts || 0) <= (prior.transcripts || 0);
+}
+
+export function recordRejection(edit, rejections, at = new Date().toISOString()) {
+  rejections.entries[rejectionKey(edit)] = {
+    kind: edit.kind,
+    file: edit.file,
+    title: edit.title,
+    transcripts: edit.transcripts || 0,
+    rejectedAt: at,
+  };
+  return rejections;
+}