backpass 0.1.0

package/src/apply/lavish.js

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { UserError, color, info, warn } from "../logger.js";
+
+/**
+ * The apply surface (captain decision 4).
+ *
+ * A static HTML template ships in the package. The CLI injects exactly one JSON payload
+ * as `window.__BACKPASS_PROPOSAL__` and serves the result through `lavish-axi`, so the
+ * review surface is instant, deterministic, and identical every run - no model
+ * regenerates it. Decisions come back as one structured vector through `lavish-axi poll`.
+ */
+
+const TEMPLATE = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "templates", "apply.html");
+
+export const LAVISH_BIN = process.env.BACKPASS_LAVISH_BIN || "lavish-axi";
+
+/** Inline a JSON payload safely: `</script>` inside data must not close the tag. */
+export function injectPayload(template, payload, toolVersion) {
+  const json = JSON.stringify({ ...payload, toolVersion })
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+  const tag = `<script>window.__BACKPASS_PROPOSAL__ = ${json};</script>`;
+  if (!template.includes("</head>")) return `${tag}\n${template}`;
+  return template.replace("</head>", `${tag}\n</head>`);
+}
+
+export function renderApplySurface(proposal, state, toolVersion) {
+  if (!fs.existsSync(TEMPLATE)) {
+    throw new UserError(`apply template missing at ${TEMPLATE}`, "reinstall backpass");
+  }
+  const html = injectPayload(fs.readFileSync(TEMPLATE, "utf8"), proposal, toolVersion);
+  const target = path.join(state.applyDir, "apply.html");
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, html);
+  return target;
+}
+
+function runLavish(args, { inherit = false } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(LAVISH_BIN, args, { stdio: inherit ? "inherit" : ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    if (!inherit) {
+      child.stdout.on("data", (d) => {
+        stdout += d;
+      });
+      child.stderr.on("data", (d) => {
+        stderr += d;
+      });
+    }
+    child.on("error", (err) => resolve({ code: null, stdout, stderr, spawnError: err }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+/**
+ * Parse the decision vector the surface queues back:
+ *   `BACKPASS_DECISIONS e1=accepted e2=rejected e3=accepted`
+ * Parsing is tolerant because the text travels through a human-facing comment box.
+ */
+export function parseDecisions(text, editIds) {
+  const decisions = {};
+  const pattern = /\b(e\d+)\s*=\s*(accepted|rejected|accept|reject)\b/gi;
+  let match = pattern.exec(text || "");
+  while (match) {
+    const id = match[1].toLowerCase();
+    if (editIds.includes(id)) {
+      decisions[id] = match[2].toLowerCase().startsWith("accept") ? "accepted" : "rejected";
+    }
+    match = pattern.exec(text || "");
+  }
+  return Object.keys(decisions).length ? decisions : null;
+}
+
+export async function openApplySurface(file) {
+  const result = await runLavish([file]);
+  if (result.spawnError && result.spawnError.code === "ENOENT") {
+    throw new UserError(
+      `${LAVISH_BIN} not found on PATH`,
+      "install lavish-axi, or run `backpass apply --no-ui` for the terminal fallback",
+    );
+  }
+  if (result.code !== 0) {
+    throw new UserError(`${LAVISH_BIN} failed to open the apply surface`, result.stderr.trim().slice(0, 400));
+  }
+  const url = /(https?:\/\/\S+)/.exec(`${result.stdout}\n${result.stderr}`);
+  return url ? url[1] : null;
+}
+
+/**
+ * Long-poll for the human's decision vector. `lavish-axi poll` blocks until the reviewer
+ * sends feedback, so this is intentionally a foreground wait.
+ */
+export async function pollDecisions(file, editIds) {
+  info(
+    `${color.dim("waiting for your decisions in the browser (Ctrl-C to abort; nothing is written until you send)")}`,
+  );
+
+  for (;;) {
+    const result = await runLavish(["poll", file]);
+    if (result.spawnError) {
+      throw new UserError(`${LAVISH_BIN} poll failed: ${result.spawnError.message}`);
+    }
+    const text = `${result.stdout}\n${result.stderr}`;
+    if (result.code !== 0) {
+      throw new UserError("lavish-axi poll exited unexpectedly", text.trim().slice(0, 400));
+    }
+
+    const decisions = parseDecisions(text, editIds);
+    if (decisions) return decisions;
+
+    if (/session\s+(ended|closed)/i.test(text)) {
+      warn("review session ended without a decision vector - nothing applied");
+      return null;
+    }
+    // Feedback that was not a decision vector (a comment, a layout report): keep waiting.
+    info(`${color.dim("received feedback without a decision vector; still waiting")}`);
+  }
+}
+
+export async function closeApplySurface(file) {
+  await runLavish(["end", file]);
+}

package/src/apply/terminal.js

@@ -0,0 +1,119 @@
+import readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+import { UserError, color } from "../logger.js";
+import { formatTokens } from "../tokens.js";
+
+/**
+ * The `--no-ui` fallback: the same ACCEPT/REJECT decision, one edit at a time, for
+ * machines with no browser (or reviewers who would rather stay in the terminal).
+ */
+
+/** Measured edits carry display lines per hunk; a legacy edit shows its find/replace. */
+export function diffLinesOf(edit) {
+  if (Array.isArray(edit.hunks)) {
+    return edit.hunks.flatMap((hunk, i) => [...(i > 0 ? [{ type: "gap", text: "" }] : []), ...(hunk.lines || [])]);
+  }
+  return [
+    ...(edit.find || "")
+      .split("\n")
+      .filter(Boolean)
+      .map((text) => ({ type: "del", text })),
+    ...(edit.replace || "")
+      .split("\n")
+      .filter(Boolean)
+      .map((text) => ({ type: "ins", text })),
+  ];
+}
+
+function renderDiff(edit) {
+  const lines = [];
+  for (const line of diffLinesOf(edit)) {
+    if (line.type === "del") lines.push(color.red(`  - ${line.text}`));
+    else if (line.type === "ins") lines.push(color.green(`  + ${line.text}`));
+    else if (line.type === "gap") lines.push(color.dim("  ..."));
+    else lines.push(color.dim(`    ${line.text}`));
+  }
+  return lines.join("\n");
+}
+
+export function renderEdit(edit, index, total) {
+  const out = [];
+  const kind = edit.kind === "extract" ? "EXTRACT -> SKILL" : edit.kind.toUpperCase();
+  const delta = edit.deltaTokens || 0;
+  const deltaText = `${delta > 0 ? "+" : ""}${formatTokens(delta)} tok${edit.targetsMemoryFile ? "" : " (not always-loaded)"}`;
+
+  out.push("");
+  out.push(`${color.bold(`[${index + 1}/${total}] ${kind}`)}  ${color.dim(deltaText)}`);
+  out.push(`  ${edit.title}`);
+  out.push(`  ${color.dim(`file: ${edit.file}`)}`);
+  if (edit.rationale) out.push(`  ${color.dim(edit.rationale)}`);
+  out.push("");
+  out.push(renderDiff(edit));
+
+  if (edit.kind === "extract" && edit.skill) {
+    out.push("");
+    out.push(color.dim(`  new skill: ${edit.skill.path}`));
+    out.push(color.dim(`  description: ${edit.skill.description}`));
+  }
+
+  if (edit.evidence?.length) {
+    out.push("");
+    out.push(color.dim(`  evidence (${edit.transcripts} transcript(s)):`));
+    for (const quote of edit.evidence.slice(0, 4)) {
+      const mark = quote.polarity === "positive" ? color.green("+") : color.red("-");
+      out.push(`    ${mark} "${quote.text.replace(/\s+/g, " ").slice(0, 200)}"`);
+      out.push(`      ${color.dim(quote.source)}`);
+    }
+  }
+
+  return out.join("\n");
+}
+
+export async function reviewInTerminal(proposal) {
+  if (!stdin.isTTY) {
+    throw new UserError(
+      "terminal review needs an interactive terminal (stdin is not a TTY)",
+      "run `backpass apply` without --no-ui to review in the browser, or use --dry-run to see the proposal",
+    );
+  }
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  const decisions = {};
+  // Ctrl-D at a prompt closes the interface; treat it as "quit", never as a hang.
+  let closed = false;
+  rl.on("close", () => {
+    closed = true;
+  });
+
+  try {
+    console.error(
+      `\n${color.bold("backpass apply")} ${color.dim(
+        `· ${proposal.repo.name} · ${proposal.memoryFile.path} · ${proposal.edits.length} proposed edit(s)`,
+      )}`,
+    );
+    console.error(
+      color.dim(
+        `budget: ${formatTokens(proposal.budget.current)} -> ${formatTokens(proposal.budget.projected)} / ${formatTokens(
+          proposal.budget.capTokens,
+        )} tok if all accepted`,
+      ),
+    );
+
+    for (const [index, edit] of proposal.edits.entries()) {
+      console.error(renderEdit(edit, index, proposal.edits.length));
+      let answer = "";
+      while (!["a", "r", "q"].includes(answer)) {
+        const reply = await rl.question(`\n  ${color.cyan("[a]ccept / [r]eject / [q]uit")} > `).catch(() => null);
+        if (reply === null || closed) return null;
+        answer = reply.trim().toLowerCase().slice(0, 1);
+      }
+      if (answer === "q") return null;
+      decisions[edit.id] = answer === "a" ? "accepted" : "rejected";
+    }
+
+    return decisions;
+  } finally {
+    rl.close();
+  }
+}

package/src/apply/writer.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { applyEdit } from "../proposal.js";
+import { budgetStatus } from "../tokens.js";
+import { recordRejection } from "../state.js";
+import { writeSkill } from "../skills.js";
+
+/**
+ * The only place in backpass that writes to the repo.
+ *
+ * Everything upstream is read-only analysis; a run only changes the weights here, after
+ * a human accepted specific edits. Writes are grouped per file so a memory file is
+ * rewritten once, atomically, rather than edit by edit.
+ */
+export function applyDecisions({ proposal, decisions, repo, state, config, dryRun = false }) {
+  const accepted = proposal.edits.filter((e) => decisions[e.id] === "accepted");
+  const rejected = proposal.edits.filter((e) => decisions[e.id] === "rejected");
+
+  const byFile = new Map();
+  const results = {
+    written: [],
+    skills: [],
+    failed: [],
+    warnings: [],
+    accepted: accepted.length,
+    rejected: rejected.length,
+  };
+
+  for (const edit of accepted) {
+    if (!byFile.has(edit.file)) byFile.set(edit.file, []);
+    byFile.get(edit.file).push(edit);
+  }
+
+  for (const [relative, edits] of byFile) {
+    const absolute = path.join(repo.root, relative);
+    if (!fs.existsSync(absolute)) {
+      results.failed.push({ file: relative, error: "file does not exist" });
+      continue;
+    }
+
+    const before = fs.readFileSync(absolute, "utf8");
+    let text = before;
+    const applied = [];
+
+    for (const edit of edits) {
+      try {
+        text = applyEdit(text, edit);
+        applied.push(edit.id);
+      } catch (err) {
+        results.failed.push({ file: relative, edit: edit.id, error: err.message });
+      }
+    }
+
+    if (text === before) continue;
+
+    const budget = relative === proposal.memoryFile.path ? budgetStatus(before, text, config.budgetTokens) : null;
+
+    if (!dryRun) fs.writeFileSync(absolute, text);
+    results.written.push({ file: relative, edits: applied, budget, dryRun });
+  }
+
+  for (const edit of accepted) {
+    if (edit.kind !== "extract" || !edit.skill) continue;
+    try {
+      const layout = dryRun ? { created: [], warnings: [] } : writeSkill(repo.root, edit.skill);
+      results.skills.push({ path: edit.skill.path, dryRun, created: layout.created });
+      for (const w of layout.warnings) if (!results.warnings.includes(w)) results.warnings.push(w);
+    } catch (err) {
+      results.failed.push({ file: edit.skill.path, edit: edit.id, error: err.message });
+    }
+  }
+
+  // Rejections are remembered so the same edit is not re-proposed without new evidence.
+  if (!dryRun && rejected.length) {
+    const rejections = state.readRejections();
+    for (const edit of rejected) recordRejection(edit, rejections);
+    state.writeRejections(rejections);
+  }
+
+  return results;
+}
+
+/**
+ * Seed a repo that has no memory file: the canonical file plus the pointer. Each file
+ * is created only if absent - bootstrap never overwrites, so a pre-existing file (say a
+ * CLAUDE.md the user wrote while a run was in flight) is reported, not replaced.
+ */
+export function writeBootstrapFiles(repoRoot, files) {
+  const results = { written: [], skipped: [] };
+  for (const { path: relative, text } of files) {
+    const absolute = path.join(repoRoot, relative);
+    if (fs.existsSync(absolute)) {
+      results.skipped.push({ file: relative, reason: "already exists" });
+      continue;
+    }
+    fs.writeFileSync(absolute, text, { flag: "wx" });
+    results.written.push({ file: relative, bytes: Buffer.byteLength(text, "utf8") });
+  }
+  return results;
+}

package/src/bootstrap.js

@@ -0,0 +1,74 @@
+import path from "node:path";
+
+import { parseMemoryUnits } from "./memory.js";
+import { sha256 } from "./state.js";
+import { estimateTokens } from "./tokens.js";
+
+/**
+ * The starter memory file backpass seeds when a repo has none.
+ *
+ * Bootstrap = a minimal skeleton + the normal backward pass. The skeleton is deliberately
+ * tiny (purpose, an empty `## Learnings` section, a self-governance section): every
+ * starter line is paid on every session, so nothing generic is pre-filled. What the
+ * repo's own transcripts teach is layered on top by the same analyze -> fold ->
+ * synthesize pipeline a normal run uses, with this text standing in as the "current
+ * weights"; evidence-backed entries land under `## Learnings`.
+ *
+ * The canonical file is AGENTS.md; CLAUDE.md is the `@AGENTS.md` pointer so both harness
+ * families read one source of truth. Writing happens in `src/apply/writer.js`.
+ */
+
+export const CANONICAL_MEMORY_FILE = "AGENTS.md";
+export const POINTER_MEMORY_FILE = "CLAUDE.md";
+
+/** The convention's two-line pointer form; `isPointerTo` recognizes it round-trip. */
+export function renderPointer(target = CANONICAL_MEMORY_FILE) {
+  return `<!-- Points Claude at ${target} via import; edit ${target}, not this file. -->\n@${target}\n`;
+}
+
+/**
+ * What a bootstrap creates for a config: the canonical file is the first configured
+ * memory file (a user override still wins), and CLAUDE.md becomes a pointer to it unless
+ * CLAUDE.md itself is the canonical file.
+ */
+export function bootstrapTargets(memoryFiles) {
+  const canonical = memoryFiles[0] || CANONICAL_MEMORY_FILE;
+  const pointer =
+    path.basename(canonical) === POINTER_MEMORY_FILE && path.dirname(canonical) === "." ? null : POINTER_MEMORY_FILE;
+  return { canonical, pointer };
+}
+
+export const MAINTAINING_SECTION = `## Maintaining this file
+
+Keep this file for knowledge useful to almost every future agent session in this project.
+Do not repeat what the codebase already shows; point to the authoritative file or command instead.
+Prefer rewriting or pruning existing entries over appending new ones.
+When updating this file, preserve this bar for all agents and keep entries concise.
+`;
+
+/** Render the default AGENTS.md for a repo. Deterministic for a given checkout. */
+export function renderStarterMemory({ repo }) {
+  return `# Project agent memory
+
+${repo.name}: this file is the always-loaded memory for agents working in this repo.
+It is kept short on purpose - every line here is paid on every session.
+
+## Learnings
+
+- None recorded yet. backpass adds evidence-backed entries here from real sessions.
+
+${MAINTAINING_SECTION}`;
+}
+
+/** An in-memory memory file object in the shape `readMemoryFile` returns, never on disk. */
+export function starterMemoryFile(repo, relativePath = CANONICAL_MEMORY_FILE) {
+  const text = renderStarterMemory({ repo });
+  return {
+    path: relativePath,
+    absolute: path.join(repo.root, relativePath),
+    text,
+    hash: `sha256:${sha256(text).slice(0, 16)}`,
+    tokens: estimateTokens(text),
+    units: parseMemoryUnits(text),
+  };
+}

package/src/cli.js

@@ -0,0 +1,261 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+
+import { UserError, fail, setQuiet } from "./logger.js";
+import { loadConfig, parseMaxTranscripts } from "./config.js";
+import { resolveRepo } from "./repo.js";
+import { State } from "./state.js";
+import { AgentResolver } from "./agents.js";
+
+import { cmdInit } from "./commands/init.js";
+import { cmdScan } from "./commands/scan.js";
+import { cmdAnalyze } from "./commands/analyze.js";
+import { cmdPropose } from "./commands/propose.js";
+import { cmdApply } from "./commands/apply.js";
+import { cmdStatus } from "./commands/status.js";
+import { cmdRun } from "./commands/run.js";
+
+const PKG = JSON.parse(
+  fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"),
+);
+
+export const VERSION = PKG.version;
+
+/** @type {import("node:util").ParseArgsOptionsConfig} */
+const OPTIONS = {
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" },
+  quiet: { type: "boolean", short: "q" },
+  json: { type: "boolean" },
+
+  since: { type: "string" },
+  harness: { type: "string" },
+  jobs: { type: "string" },
+  strict: { type: "boolean" },
+  "include-cursor-ide": { type: "boolean" },
+
+  budget: { type: "string" },
+  "max-edits": { type: "string" },
+  "max-transcripts": { type: "string" },
+  seed: { type: "string" },
+  "min-gap-evidence": { type: "string" },
+  "memory-file": { type: "string", multiple: true },
+  "skills-dir": { type: "string" },
+
+  "analysis-agent": { type: "string" },
+  "analysis-model": { type: "string" },
+  "analysis-effort": { type: "string" },
+  "synthesis-agent": { type: "string" },
+  "synthesis-model": { type: "string" },
+  "synthesis-effort": { type: "string" },
+
+  "dry-run": { type: "boolean" },
+  "no-ui": { type: "boolean" },
+  "no-auto-agent": { type: "boolean" },
+  force: { type: "boolean" },
+  limit: { type: "string" },
+  theme: { type: "string" },
+};
+
+const HELP = `backpass v${VERSION} - gradient descent for your agent memory
+
+A backward pass over AGENTS.md / CLAUDE.md: it finds the agent sessions that ran in this
+repo, reads what actually happened in them, and proposes evidence-backed edits to the
+memory file - under a token budget, gated by you.
+
+USAGE
+  backpass [command] [options]
+
+COMMANDS
+  (none)     the full pass: collect samples → calculate loss → aggregate gradients →
+             gradient descent. Never writes.
+  scan       collect samples only: which transcripts belong to this repo, and how we know
+  analyze    calculate loss: one cheap model call per new transcript (tier 1)
+  propose    aggregate gradients, then gradient descent: one high-reasoning call
+             turning the aggregated evidence into edits (tier 2)
+  apply      review the proposal and write the accepted edits (the only writer)
+  status     cache state, evidence counts, and the budget bar
+  init       write .backpassrc.json and exclude .backpass/ via .git/info/exclude
+
+COLLECT SAMPLES
+  --since <dur>            only sessions newer than this (30d, 12h, 2w, all)  [30d]
+  --harness <a,b>          limit to these harnesses
+                           (claude, codex, pi, opencode, grok, cursor)
+  --strict                 deterministic associations only (tiers 1 and 2)
+  --include-cursor-ide     also scan the Cursor IDE store (best-effort, v1.1 preview)
+  --limit <n>              analyze at most N transcripts this run (newest first)
+  --max-transcripts <n>    cap per run; past it a recency-weighted random sample
+                           is analyzed. 0 or "all" disables the cap          [100]
+  --seed <n>               make the transcript sample reproducible
+
+MODELS (two-tier: cheap analysis, smart synthesis - all through acpx)
+  By default each pass auto-picks the first harness in its ladder that is installed,
+  logged in, and serves the model (a ~1.5s zero-token probe per candidate, cached):
+    analysis   gpt-5.6-luna via pi, opencode, codex  >  claude-sonnet-5 via claude  >  grok-4.6 via pi, opencode, grok
+    synthesis  gpt-5.6-sol  via pi, opencode, codex  >  claude-opus-5  via claude  >  grok-4.6 via pi, opencode, grok
+  Setting an agent pins that pass and skips its ladder.
+  --analysis-agent <a>     acpx agent for the per-transcript pass       [auto]
+  --analysis-model <id>    model id for the analysis pass (needs --analysis-agent)
+  --analysis-effort <e>    reasoning effort, when the adapter advertises it  [medium]
+  --synthesis-agent <a>    acpx agent for the final proposal pass       [auto]
+  --synthesis-model <id>   model id for the synthesis pass (needs --synthesis-agent)
+  --synthesis-effort <e>   reasoning effort for synthesis               [high]
+  --no-auto-agent          skip the ladders and pin codex / claude (the pre-0.2 defaults)
+  --jobs <n>               parallel analysis calls                      [4]
+
+BUDGET AND SHAPE
+  --budget <tokens>        always-loaded budget per memory file         [5000]
+  --max-edits <n>          edits per run - the learning rate            [adaptive]
+  --min-gap-evidence <n>   sessions needed before a new instruction     [2]
+  --memory-file <path>     memory file to optimize (repeatable)
+  --skills-dir <path>      where skill extractions are written          [.agents/skills]
+
+APPLY
+  --no-ui                  terminal accept/reject instead of the Lavish surface
+  --dry-run                show what would be written, write nothing
+  --force                  re-analyze transcripts that already have fresh evidence,
+                           and re-probe agents instead of trusting the probe cache
+
+OTHER
+  --theme <mode>           live progress ink set: auto, dark, or light    [auto]
+  --json                   machine-readable output on stdout
+  -q, --quiet              suppress progress output (also disables the live view)
+  -h, --help               this help
+  -v, --version            print version
+
+The default run renders a live progress view on an interactive terminal. It draws
+to stderr only and falls back to plain lines when piped, in CI, under NO_COLOR,
+or below 60 columns - stdout and --json output are identical either way.
+
+EXAMPLES
+  backpass                                  a full run, ending with a proposal
+  backpass scan --since 7d --strict         what would be collected, deterministic only
+  backpass --synthesis-agent claude --synthesis-model claude-opus-5
+  backpass apply --no-ui                    review and write from the terminal
+`;
+
+/** Map CLI flags onto the config shape so one merge order covers every layer. */
+function overridesFrom(values) {
+  const overrides = { discovery: {}, analysis: {}, synthesis: {} };
+
+  if (values.since) overrides.discovery.since = values.since;
+  if (values.harness) {
+    overrides.discovery.harnesses = values.harness
+      .split(",")
+      .map((h) => h.trim())
+      .filter(Boolean);
+  }
+  if (values["include-cursor-ide"]) overrides.discovery.includeCursorIde = true;
+  if (values.jobs) overrides.jobs = toInt(values.jobs, "--jobs");
+  if (values.budget) overrides.budgetTokens = toInt(values.budget, "--budget");
+  if (values["max-edits"]) overrides.maxEditsPerRun = toInt(values["max-edits"], "--max-edits");
+  if (values["max-transcripts"] !== undefined) {
+    overrides.maxTranscripts = parseMaxTranscripts(values["max-transcripts"], "--max-transcripts");
+  }
+  if (values.seed !== undefined) overrides.seed = toSeed(values.seed);
+  if (values["min-gap-evidence"]) {
+    overrides.minGapEvidence = toInt(values["min-gap-evidence"], "--min-gap-evidence");
+  }
+  if (values["memory-file"]?.length) overrides.memoryFiles = values["memory-file"];
+  if (values["skills-dir"]) overrides.skillsDir = values["skills-dir"];
+  if (values.theme) overrides.theme = values.theme;
+
+  if (values["analysis-agent"]) overrides.analysis.agent = values["analysis-agent"];
+  if (values["analysis-model"]) overrides.analysis.model = values["analysis-model"];
+  if (values["analysis-effort"]) overrides.analysis.effort = values["analysis-effort"];
+  if (values["synthesis-agent"]) overrides.synthesis.agent = values["synthesis-agent"];
+  if (values["synthesis-model"]) overrides.synthesis.model = values["synthesis-model"];
+  if (values["synthesis-effort"]) overrides.synthesis.effort = values["synthesis-effort"];
+  if (values["no-auto-agent"]) overrides.autoAgent = false;
+
+  for (const key of ["discovery", "analysis", "synthesis"]) {
+    if (!Object.keys(overrides[key]).length) delete overrides[key];
+  }
+  return overrides;
+}
+
+function toInt(value, flag) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0) throw new UserError(`${flag} must be a positive integer (got "${value}")`);
+  return n;
+}
+
+function toSeed(value) {
+  const n = Number(value);
+  if (!Number.isInteger(n)) throw new UserError(`--seed must be an integer (got "${value}")`);
+  return n;
+}
+
+const COMMANDS = {
+  init: cmdInit,
+  scan: cmdScan,
+  analyze: cmdAnalyze,
+  propose: cmdPropose,
+  apply: cmdApply,
+  status: cmdStatus,
+  run: cmdRun,
+};
+
+export async function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+  } catch (err) {
+    fail(err.message);
+    console.error("\nRun `backpass --help` for the full option list.");
+    return 2;
+  }
+
+  const { values, positionals } = parsed;
+
+  if (values.help) {
+    console.log(HELP);
+    return 0;
+  }
+  if (values.version) {
+    console.log(VERSION);
+    return 0;
+  }
+  setQuiet(values.quiet);
+
+  const commandName = positionals[0] || "run";
+  const command = COMMANDS[commandName];
+  if (!command) {
+    fail(`unknown command "${commandName}"`);
+    console.error("\nRun `backpass --help` for the command list.");
+    return 2;
+  }
+
+  try {
+    const repo = resolveRepo(process.cwd());
+    const config = loadConfig(repo.root, overridesFrom(values));
+    config.state = new State(repo.root).ensure();
+    config.agents = new AgentResolver(config, {
+      state: config.state,
+      cwd: repo.root,
+      bypassCache: Boolean(values.force),
+    });
+
+    const ctx = {
+      repo,
+      config,
+      flags: values,
+      positionals: positionals.slice(1),
+      version: VERSION,
+      strict: Boolean(values.strict),
+      limit: values.limit ? toInt(values.limit, "--limit") : null,
+    };
+
+    return (await command(ctx)) ?? 0;
+  } catch (err) {
+    if (err instanceof UserError) {
+      fail(err.message);
+      if (err.hint) console.error(`  ${err.hint}`);
+      return 1;
+    }
+    fail(err.stack || err.message);
+    return 1;
+  }
+}