backpass 0.1.0

package/src/commands/scan.js

@@ -0,0 +1,90 @@
+import { discoverTranscripts } from "../discovery/index.js";
+import { color, info, json, out } from "../logger.js";
+
+/** Shared by every command that needs the transcript set. */
+export async function discoverForRun(ctx) {
+  const { repo, config, strict } = ctx;
+  const result = await discoverTranscripts({ repo, config, strict });
+  if (ctx.limit && result.transcripts.length > ctx.limit) {
+    result.truncated = result.transcripts.length - ctx.limit;
+    result.transcripts = result.transcripts.slice(0, ctx.limit);
+  }
+  return result;
+}
+
+function ago(ms) {
+  if (!ms) return "-";
+  const days = Math.floor((Date.now() - ms) / 86_400_000);
+  if (days <= 0) return "today";
+  if (days === 1) return "1d ago";
+  return `${days}d ago`;
+}
+
+export async function cmdScan(ctx) {
+  const { transcripts, perHarness, truncated } = await discoverForRun(ctx);
+
+  if (ctx.flags.json) {
+    json({ repo: ctx.repo.name, perHarness, transcripts });
+    return 0;
+  }
+
+  out(`${ctx.repo.name} · ${ctx.repo.worktrees.length} worktree(s) · since ${ctx.config.discovery.since}`);
+  out("");
+
+  const rows = [["HARNESS", "SCANNED", "MATCHED", "SELF", "CACHED", "NOTE"]];
+  for (const [harness, stats] of Object.entries(perHarness)) {
+    rows.push([
+      harness,
+      String(stats.scanned),
+      String(stats.matched),
+      String(stats.self || 0),
+      String(stats.cached),
+      stats.error ? `unreadable: ${stats.error}` : "",
+    ]);
+  }
+  out(table(rows));
+  const selfTotal = Object.values(perHarness).reduce((n, s) => n + (s.self || 0), 0);
+  if (selfTotal) out(color.dim(`  SELF = backpass's own loss / gradient-descent sessions, excluded from the corpus`));
+  out("");
+
+  const byTier = { 1: 0, 2: 0, 3: 0 };
+  for (const t of transcripts) byTier[t.association.tier] += 1;
+  out(
+    `${transcripts.length} transcript(s) associated with this repo · ` +
+      `tier1 ${byTier[1]} (exact) · tier2 ${byTier[2]} (remote) · tier3 ${byTier[3]} (best-effort)`,
+  );
+  if (byTier[3] && !ctx.strict) out(color.dim("  re-run with --strict to exclude the best-effort tier"));
+  if (truncated) out(color.dim(`  --limit ${ctx.limit} is hiding ${truncated} more transcript(s)`));
+  out("");
+
+  const preview = transcripts.slice(0, 25);
+  const detail = [["HARNESS", "SESSION", "WHEN", "SIZE", "TIER", "HOW"]];
+  for (const t of preview) {
+    detail.push([
+      t.harness,
+      t.nativeId.slice(0, 12),
+      ago(t.mtimeMs),
+      t.bytes ? `${Math.round(t.bytes / 1024)}KB` : "-",
+      `t${t.association.tier}`,
+      t.association.reason,
+    ]);
+  }
+  out(table(detail));
+  if (transcripts.length > preview.length) {
+    info(color.dim(`  ... and ${transcripts.length - preview.length} more`));
+  }
+  return 0;
+}
+
+export function table(rows) {
+  const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => String(r[i] ?? "").length)));
+  return rows
+    .map((row, rowIndex) => {
+      const line = row
+        .map((cell, i) => String(cell ?? "").padEnd(widths[i]))
+        .join("  ")
+        .trimEnd();
+      return rowIndex === 0 ? color.dim(line) : line;
+    })
+    .join("\n");
+}

package/src/commands/status.js

@@ -0,0 +1,143 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { color, json, out } from "../logger.js";
+import { resolveMemoryFiles } from "../memory.js";
+import { loadSkills, resolveOverflowTarget } from "../skills.js";
+import { budgetBar, budgetStatus, formatTokens } from "../tokens.js";
+import { table } from "./scan.js";
+import { DEFAULT_EFFORT } from "../config.js";
+import { candidateKey, isProbeEntryFresh } from "../agents.js";
+
+export async function cmdStatus(ctx) {
+  const { repo, config } = ctx;
+  const state = config.state;
+
+  const resolved = resolveMemoryFiles(repo.root, config.memoryFiles);
+  const files = resolved.all;
+  const evidence = state.listEvidence();
+  const counts = { ok: 0, failed: 0, skipped: 0 };
+  for (const e of evidence) counts[e.status] = (counts[e.status] || 0) + 1;
+
+  const cache = state.readScanCache();
+  const summary = state.readSummary();
+  const proposal = state.readProposal();
+  const rejections = state.readRejections();
+  const overflow = resolveOverflowTarget(repo.root, config.skillsDir);
+  const skills = loadSkills(repo.root, overflow.dir);
+
+  const budgets = files.map((file) => ({
+    path: file.path,
+    ...budgetStatus(file.text, null, config.budgetTokens),
+    instructions: file.units.length,
+    pointerTo: resolved.pointers.includes(file) ? resolved.primary.path : null,
+    separate: resolved.separate.includes(file),
+  }));
+
+  if (ctx.flags.json) {
+    json({
+      repo: repo.name,
+      budgets,
+      evidence: counts,
+      scanCacheEntries: Object.keys(cache.entries).length,
+      summary: summary ? { analyzedSessions: summary.analyzedSessions, totals: summary.totals } : null,
+      proposal: proposal ? { generatedAt: proposal.generatedAt, edits: proposal.edits.length } : null,
+      rejections: Object.keys(rejections.entries).length,
+      skills: skills.length,
+    });
+    return 0;
+  }
+
+  out(`${color.bold(repo.name)} ${color.dim(repo.root)}`);
+  out("");
+
+  out(color.dim("BUDGET (always-loaded)"));
+  if (!budgets.length) out("  no memory file found");
+  for (const b of budgets) {
+    if (b.pointerTo) {
+      out(`  ${b.path.padEnd(14)} ${color.dim(`pointer to ${b.pointerTo}`)}`);
+      continue;
+    }
+    const state_ =
+      (b.withinBudget ? "" : color.red(` ${b.over} OVER`)) +
+      (b.separate ? color.yellow(" separate - not optimized") : "");
+    out(
+      `  ${b.path.padEnd(14)} ${budgetBar(b)} ${formatTokens(b.current)} / ${formatTokens(b.capTokens)} tok` +
+        ` · ${b.instructions} instructions${state_}`,
+    );
+  }
+  if (skills.length) {
+    const skillTokens = skills.reduce((n, s) => n + s.bodyTokens, 0);
+    const descTokens = skills.reduce((n, s) => n + s.descriptionTokens, 0);
+    out(
+      color.dim(
+        `  overflow: ${skills.length} skill(s) in ${overflow.dir} · ${formatTokens(skillTokens)} tok on trigger, ` +
+          `${formatTokens(descTokens)} tok always loaded`,
+      ),
+    );
+  }
+  out("");
+
+  out(color.dim("CACHE"));
+  out(`  scan cache      ${Object.keys(cache.entries).length} file(s) fingerprinted`);
+  out(
+    `  evidence        ${counts.ok || 0} ok · ${counts.skipped || 0} skipped · ${color.red(String(counts.failed || 0))} failed`,
+  );
+  if (summary) {
+    out(
+      `  gradients       ${summary.analyzedSessions} session(s) · ${summary.totals.positive}+ ` +
+        `${summary.totals.negative}- · ${summary.totals.gapClusters} gap cluster(s)`,
+    );
+  }
+  out(`  rejections      ${Object.keys(rejections.entries).length} remembered`);
+  out("");
+
+  if (counts.failed) {
+    out(color.dim("FAILED TRANSCRIPTS (retried on the next run)"));
+    const rows = [["HARNESS", "SESSION", "ERROR"]];
+    for (const e of evidence.filter((x) => x.status === "failed").slice(0, 10)) {
+      rows.push([e.transcript.harness, String(e.transcript.id).slice(-12), String(e.error).slice(0, 60)]);
+    }
+    out(table(rows));
+    out("");
+  }
+
+  out(color.dim("PROPOSAL"));
+  if (!proposal) {
+    out("  none yet - run `backpass`");
+  } else {
+    out(`  generated       ${proposal.generatedAt}`);
+    out(
+      `  edits           ${proposal.edits.length}${proposal.violations?.length ? color.red(" (failed its gates)") : ""}`,
+    );
+    const surface = path.join(state.applyDir, "apply.html");
+    if (fs.existsSync(surface)) out(color.dim(`  surface         ${surface}`));
+    if (!proposal.violations?.length && proposal.edits.length) out("  review with `backpass apply`");
+  }
+
+  out("");
+  out(color.dim("MODELS"));
+  for (const role of ["analysis", "synthesis"]) out(`  ${role.padEnd(10)}      ${describeRole(config, role)}`);
+  return 0;
+}
+
+/**
+ * The pick for a role without probing: a pinned agent as configured, otherwise the
+ * ladder with whatever the probe cache already knows. `status` must stay instant.
+ */
+function describeRole(config, role) {
+  const pinned = config.agents.pinned(role);
+  const effort = config[role].effort || DEFAULT_EFFORT[role];
+  if (pinned) {
+    return `${pinned.agent}${pinned.model ? `/${pinned.model}` : ""} (effort ${effort}, ${pinned.reason})`;
+  }
+  const cache = config.state.readProbeCache();
+  for (const candidate of config.agents.ladder(role)) {
+    const entry = cache.entries[candidateKey(candidate)];
+    if (!isProbeEntryFresh(entry)) continue;
+    if (entry.verdict === "ok") {
+      return `${candidate.agent}/${entry.resolvedModel || candidate.model} (effort ${effort}, auto - probed ${entry.checkedAt.slice(0, 16).replace("T", " ")})`;
+    }
+  }
+  return color.dim(`auto - ${config.agents.ladder(role).length} candidates, none probed yet (effort ${effort})`);
+}

package/src/commands/usage.js

@@ -0,0 +1,25 @@
+import { describeUsage } from "../acpx.js";
+import { color, out } from "../logger.js";
+
+/**
+ * Print the model-usage accounting for a run, one line per pass that actually made
+ * calls: tier-1 (the per-transcript analysis pass) then tier-2 (synthesis). This is the
+ * only place that prints these lines - `run` and `propose` both end in `printProposal`,
+ * and `analyze` prints just its own tier through the same helper - so the accounting
+ * appears exactly once, in order, before the apply hint.
+ *
+ * A pass that made no calls this run (all evidence cached, or analysis ran in an earlier
+ * command) prints nothing rather than a meaningless "n/a"; a pass whose harness returned
+ * no usage says so by name (see `describeUsage`).
+ *
+ * @param {{ tier1?: import("../acpx.js").UsageRecord[], tier2?: import("../acpx.js").UsageRecord[] }} usage
+ */
+export function printUsage({ tier1 = [], tier2 = [] } = {}) {
+  const lines = [
+    ["tier-1", describeUsage(tier1)],
+    ["tier-2", describeUsage(tier2)],
+  ].filter(([, text]) => text);
+  if (!lines.length) return;
+  out("");
+  for (const [tier, text] of lines) out(color.dim(`  ${tier} tokens: ${text}`));
+}

package/src/config.js

@@ -0,0 +1,249 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+import { UserError, warn } from "./logger.js";
+
+export const CONFIG_FILENAME = ".backpassrc.json";
+export const STATE_DIRNAME = ".backpass";
+
+export const ALL_HARNESSES = ["claude", "codex", "pi", "opencode", "grok", "cursor"];
+/** Cursor IDE is deferred to v1.1 and only ever runs behind --include-cursor-ide. */
+export const OPT_IN_HARNESSES = ["cursor-ide"];
+
+/**
+ * The ordered candidate ladders behind the auto-pick (ordered-defaults design, section 8.2).
+ * Each rung is one model id served by several harnesses in preference order; rungs are
+ * flattened model-outer / harness-inner, and the first candidate that is installed,
+ * authenticated, and serves the model wins. Model ids are the bare ids the vendors use;
+ * per-harness spellings (`openai-codex/...`, `openai/...`, `xai/...`) are resolved at
+ * probe time against what the adapter advertises - never hard-coded. Ladders live in
+ * config so a user can reorder or shorten them in `.backpassrc.json` without a release.
+ */
+export const DEFAULT_LADDERS = {
+  analysis: [
+    { model: "gpt-5.6-luna", agents: ["pi", "opencode", "codex"] },
+    { model: "claude-sonnet-5", agents: ["claude"] },
+    { model: "grok-4.6", agents: ["pi", "opencode", "grok"] },
+  ],
+  synthesis: [
+    { model: "gpt-5.6-sol", agents: ["pi", "opencode", "codex"] },
+    { model: "claude-opus-5", agents: ["claude"] },
+    { model: "grok-4.6", agents: ["pi", "opencode", "grok"] },
+  ],
+};
+
+/** Applied to a role whenever no layer set an effort, auto-picked or pinned. */
+export const DEFAULT_EFFORT = { analysis: "medium", synthesis: "high" };
+
+/** What `--no-auto-agent` pins: the pre-ladder fixed defaults. */
+export const LEGACY_DEFAULT_AGENTS = { analysis: "codex", synthesis: "claude" };
+
+export const DEFAULT_CONFIG = {
+  memoryFiles: ["AGENTS.md", "CLAUDE.md"],
+  budgetTokens: 5000,
+  skillsDir: ".agents/skills",
+  /** `null` means adaptive: see `effectiveMaxEdits` in proposal.js. An integer pins it. */
+  maxEditsPerRun: null,
+  minGapEvidence: 2,
+  /**
+   * Gap observations accumulate across runs in `.backpass/gap-ledger.json` so the
+   * `minGapEvidence` bar counts distinct sessions over time, not per run. A session's
+   * observations retire past this age (a duration like 90d, `all` to never expire).
+   */
+  gapLedgerMaxAge: "90d",
+  /**
+   * Cap on transcripts analyzed per run; past it a recency-weighted sample is drawn
+   * (`src/sample.js`). `0` or "all" disables the cap. `sampleHalfLife` is the age at
+   * which a transcript's sampling weight halves; `seed` makes the sample reproducible.
+   */
+  maxTranscripts: 100,
+  sampleHalfLife: "14d",
+  seed: null,
+  /**
+   * `agent: null` means auto-pick from `ladders[role]`; `effort: null` means
+   * `DEFAULT_EFFORT[role]`. Setting `agent` pins the role and skips the ladder.
+   */
+  analysis: { agent: null, model: null, effort: null },
+  synthesis: { agent: null, model: null, effort: null },
+  autoAgent: true,
+  ladders: DEFAULT_LADDERS,
+  discovery: {
+    harnesses: ALL_HARNESSES,
+    since: "30d",
+    worktreeGlobs: [],
+    minUserTurns: 2,
+    includeCursorIde: false,
+  },
+  jobs: 4,
+  timeoutSeconds: 300,
+  promptRetries: 1,
+  /** Live progress ink set: "auto" queries the terminal background, or force "dark" / "light". */
+  theme: "auto",
+};
+
+function userConfigPath() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(base, "backpass", "config.json");
+}
+
+function readJsonIfPresent(file) {
+  if (!fs.existsSync(file)) return null;
+  let value;
+  try {
+    value = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (err) {
+    throw new UserError(`${file} is not valid JSON: ${err.message}`);
+  }
+  if (!isPlainObject(value)) {
+    throw new UserError(`${file} must contain a JSON object`);
+  }
+  return value;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function deepMerge(base, override) {
+  if (!isPlainObject(override)) return override === undefined ? base : override;
+  const result = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) continue;
+    result[key] = isPlainObject(base[key]) ? deepMerge(base[key], value) : value;
+  }
+  return result;
+}
+
+/**
+ * Parse a duration like `30d`, `12h`, `90m` into milliseconds.
+ * `all` / `0` disables the cutoff.
+ */
+export function parseSince(since) {
+  if (since === null || since === undefined || since === "all" || since === "0") return null;
+  const match = String(since)
+    .trim()
+    .match(/^(\d+)\s*([dhwm])$/i);
+  if (!match) {
+    throw new UserError(`invalid --since value "${since}"`, "use forms like 30d, 12h, 2w, 90m, or all");
+  }
+  const n = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const ms = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 }[unit];
+  return n * ms;
+}
+
+/** Normalize a user-facing cap: `0`, `all`, null, or undefined disables it. */
+export function parseMaxTranscripts(value, flag = "maxTranscripts") {
+  if (value === null || value === undefined || value === "all" || value === "0" || value === 0) return null;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new UserError(
+      `${flag} must be a non-negative integer or "all" (got "${value}")`,
+      'use a positive integer, or 0 / "all" to analyze every transcript',
+    );
+  }
+  return n;
+}
+
+export function sinceCutoff(since, now = Date.now()) {
+  const window = parseSince(since);
+  return window === null ? null : now - window;
+}
+
+function validate(config) {
+  if (!Array.isArray(config.memoryFiles) || config.memoryFiles.length === 0) {
+    throw new UserError("config.memoryFiles must be a non-empty array");
+  }
+  if (!Number.isFinite(config.budgetTokens) || config.budgetTokens <= 0) {
+    throw new UserError("config.budgetTokens must be a positive number");
+  }
+  if (config.maxEditsPerRun !== null && (!Number.isInteger(config.maxEditsPerRun) || config.maxEditsPerRun <= 0)) {
+    throw new UserError("config.maxEditsPerRun must be a positive integer, or null for the adaptive cap");
+  }
+  if (!Number.isInteger(config.minGapEvidence) || config.minGapEvidence < 1) {
+    throw new UserError("config.minGapEvidence must be an integer >= 1");
+  }
+  config.maxTranscripts = parseMaxTranscripts(config.maxTranscripts, "config.maxTranscripts");
+  try {
+    parseSince(config.gapLedgerMaxAge);
+  } catch {
+    throw new UserError(`config.gapLedgerMaxAge must be a duration like 90d or all (got "${config.gapLedgerMaxAge}")`);
+  }
+  if (parseSince(config.sampleHalfLife) === null) {
+    throw new UserError(`config.sampleHalfLife must be a duration like 14d (got "${config.sampleHalfLife}")`);
+  }
+  if (config.seed !== null && !Number.isInteger(config.seed)) {
+    throw new UserError("config.seed must be an integer or null");
+  }
+  if (!Number.isInteger(config.jobs) || config.jobs < 1) {
+    throw new UserError("config.jobs must be an integer >= 1");
+  }
+  for (const role of ["analysis", "synthesis"]) {
+    if (config[role].model && !config[role].agent) {
+      throw new UserError(
+        `config.${role}.model is set but config.${role}.agent is not`,
+        `set --${role}-agent too, or leave both unset to auto-pick from the ladder`,
+      );
+    }
+    const ladder = config.ladders?.[role];
+    if (!Array.isArray(ladder) || ladder.length === 0) {
+      throw new UserError(`config.ladders.${role} must be a non-empty array of { model, agents } rungs`);
+    }
+    for (const rung of ladder) {
+      if (!rung || typeof rung.model !== "string" || !Array.isArray(rung.agents) || !rung.agents.length) {
+        throw new UserError(`config.ladders.${role} rungs must look like { "model": "<id>", "agents": ["<harness>"] }`);
+      }
+    }
+  }
+  if (!["auto", "dark", "light"].includes(config.theme)) {
+    throw new UserError(`config.theme must be "auto", "dark", or "light" (got "${config.theme}")`);
+  }
+  const known = new Set([...ALL_HARNESSES, ...OPT_IN_HARNESSES]);
+  for (const h of config.discovery.harnesses) {
+    if (!known.has(h)) {
+      warn(`unknown harness "${h}" in config.discovery.harnesses - ignoring`);
+    }
+  }
+  config.discovery.harnesses = config.discovery.harnesses.filter((h) => known.has(h));
+  parseSince(config.discovery.since);
+  return config;
+}
+
+/**
+ * Layered config: defaults < ~/.config/backpass/config.json < <repo>/.backpassrc.json < CLI flags.
+ */
+export function loadConfig(repoRoot, overrides = {}) {
+  const merged = [
+    readJsonIfPresent(userConfigPath()),
+    readJsonIfPresent(path.join(repoRoot, CONFIG_FILENAME)),
+    overrides,
+  ].reduce((acc, layer) => (layer ? deepMerge(acc, layer) : acc), DEFAULT_CONFIG);
+
+  const config = structuredClone(merged);
+  if (config.discovery.includeCursorIde && !config.discovery.harnesses.includes("cursor-ide")) {
+    config.discovery.harnesses = [...config.discovery.harnesses, "cursor-ide"];
+  }
+  return validate(config);
+}
+
+export function repoConfigPath(repoRoot) {
+  return path.join(repoRoot, CONFIG_FILENAME);
+}
+
+/** The subset written by `backpass init` - defaults stay implicit so upgrades reach users. */
+export function initialConfig() {
+  return {
+    memoryFiles: ["AGENTS.md"],
+    budgetTokens: DEFAULT_CONFIG.budgetTokens,
+    skillsDir: DEFAULT_CONFIG.skillsDir,
+    // maxEditsPerRun stays unset so the adaptive cap applies; set it to pin a number.
+    minGapEvidence: DEFAULT_CONFIG.minGapEvidence,
+    maxTranscripts: DEFAULT_CONFIG.maxTranscripts,
+    // Agents stay unset so the ladder auto-pick keeps applying to initialized repos.
+    analysis: { agent: null, model: null, effort: null },
+    synthesis: { agent: null, model: null, effort: null },
+    discovery: { harnesses: ALL_HARNESSES, since: "30d", worktreeGlobs: [], minUserTurns: 2 },
+    jobs: DEFAULT_CONFIG.jobs,
+  };
+}