backpass 0.1.6 → 0.1.8

package/src/apply/writer.js

@@ -1,19 +1,28 @@
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 
 import { applyEdit, projectWithDecisions } from "../proposal.js";
-import { budgetGateKind, budgetStatus } from "../tokens.js";
+import { memoryTextHash } from "../memory.js";
+import { budgetGateKind, budgetStatus, formatTokens } from "../tokens.js";
 import { recordRejection } from "../state.js";
-import { writeSkill } from "../skills.js";
+import {
+  CANONICAL_SKILLS_DIR,
+  CLAUDE_SKILLS_LINK,
+  editSkills,
+  ensureSkillsLayout,
+  removeOwnedSkillPaths,
+  writeSkill,
+} from "../skills.js";
 
-function acceptedSubsetBudgetFailure({ proposal, accepted, repo, capTokens }) {
+function acceptedSubsetBudgetFailure({ proposal, accepted, repo, capTokens, memoryText }) {
   if (!accepted.length) return null;
 
   const relative = proposal.memoryFile.path;
   const absolute = path.join(repo.root, relative);
-  if (!fs.existsSync(absolute)) return null;
+  if (memoryText === null && !fs.existsSync(absolute)) return null;
 
-  const before = fs.readFileSync(absolute, "utf8");
+  const before = memoryText ?? fs.readFileSync(absolute, "utf8");
   const { budget } = projectWithDecisions(
     before,
     accepted,
@@ -41,14 +50,136 @@ function acceptedSubsetBudgetFailure({ proposal, accepted, repo, capTokens }) {
   return null;
 }
 
+/**
+ * Freshness before mutation.
+ *
+ * Every hunk was cut from one exact image of the memory file, and the proposal records
+ * that image's hash. If the file has disappeared or changed since - an upstream merge,
+ * a hand edit, another agent - then the hunks describe text that may no longer exist, and the ones
+ * that still happen to match would leave the file half-descended: part of a shrink plan
+ * applied against a file the plan was never measured against. So the run is refused
+ * before it writes anything, and the fix is to re-measure, not to salvage.
+ *
+ * A proposal saved before this field existed carries no hash and is left alone.
+ */
+function memoryFileSnapshot(proposal, repo) {
+  const expected = proposal.memoryFile?.hash;
+  const relative = proposal.memoryFile?.path;
+  if (!relative) return { text: null };
+
+  const absolute = path.join(repo.root, relative);
+  if (!fs.existsSync(absolute)) {
+    if (!expected) return { text: null };
+    return {
+      text: null,
+      failure: {
+        file: relative,
+        error:
+          `${relative} no longer exists, so its edits no longer describe the file on disk; nothing was written. ` +
+          `Run \`backpass\` to re-propose against the current repository.`,
+      },
+    };
+  }
+
+  const text = fs.readFileSync(absolute, "utf8");
+  if (!expected) return { text };
+
+  const observed = memoryTextHash(text);
+  if (observed === expected) return { text };
+
+  return {
+    text,
+    failure: {
+      file: relative,
+      error:
+        `${relative} changed after this proposal was made (${expected} -> ${observed}), so its edits ` +
+        `no longer describe the file on disk; nothing was written. Run \`backpass\` to re-propose ` +
+        `against the current ${relative}.`,
+    },
+  };
+}
+
+function overBudgetWarning(relative, budget) {
+  return (
+    `${relative} is still ${formatTokens(budget.over)} tokens over the ${formatTokens(budget.capTokens)}-token ` +
+    "budget; run `backpass` again for the next shrink step"
+  );
+}
+
+function atomicReplace(target, text) {
+  const temp = path.join(path.dirname(target), `.${path.basename(target)}.backpass-${randomUUID()}`);
+  const mode = fs.statSync(target).mode & 0o7777;
+  let fd;
+  let ownership;
+  try {
+    fd = fs.openSync(temp, "wx");
+    const stat = fs.fstatSync(fd);
+    ownership = [{ absolute: temp, identity: { dev: stat.dev, ino: stat.ino } }];
+    fs.fchmodSync(fd, mode);
+    fs.writeFileSync(fd, text);
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(temp, target);
+    return { absolute: target, identity: ownership[0].identity, text };
+  } catch (err) {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // Preserve the original write error.
+      }
+    }
+    removeOwnedSkillPaths(ownership ?? []);
+    throw err;
+  }
+}
+
+function commitStillCurrent(commit) {
+  let stat;
+  try {
+    stat = fs.lstatSync(commit.absolute);
+    if (stat.dev !== commit.identity.dev || stat.ino !== commit.identity.ino) return false;
+    return fs.readFileSync(commit.absolute, "utf8") === commit.text;
+  } catch {
+    return false;
+  }
+}
+
+function absentParentDirectories(root, files) {
+  const directories = new Set();
+  for (const file of files) {
+    for (let current = path.dirname(file); current !== root; current = path.dirname(current)) {
+      if (!fs.existsSync(current)) directories.add(current);
+    }
+  }
+  return [...directories].sort((a, b) => b.length - a.length);
+}
+
+function removeEmptyDirectories(directories) {
+  for (const directory of directories) {
+    try {
+      fs.rmdirSync(directory);
+    } catch {
+      continue;
+    }
+  }
+}
+
 /**
  * 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. The accepted subset is rechecked with the same
- * cap/shrink budget gate as the full proposal (`budgetGateKind`); a failing subset
- * returns with no writes and no rejection ledger. Writes are grouped per file so a
- * memory file is rewritten once, atomically, rather than edit by edit.
+ * a human accepted specific edits. Five gates run before the first byte is written:
+ * the memory file must still be the file the proposal was measured against
+ * (`memoryFileSnapshot`), the accepted subset must clear the same cap/shrink budget gate as
+ * the full proposal (`budgetGateKind`), every accepted edit for a file must compose
+ * against that file's single pre-write image, every created skill target must still be
+ * absent, and accepted paths must resolve to distinct targets. Any of them failing writes
+ * nothing and records no rejection.
+ *
+ * A file is therefore applied all at once or not at all. Skills are written only after
+ * every accepted edit has composed, and before the files that reference them.
  */
 export function applyDecisions({ proposal, decisions, repo, state, config, dryRun = false }) {
   const accepted = proposal.edits.filter((e) => decisions[e.id] === "accepted");
@@ -65,11 +196,22 @@ export function applyDecisions({ proposal, decisions, repo, state, config, dryRu
     rejectionsRecorded: false,
   };
 
+  let memoryText = null;
+  if (accepted.length || rejected.length) {
+    const snapshot = memoryFileSnapshot(proposal, repo);
+    if (snapshot.failure) {
+      results.failed.push(snapshot.failure);
+      return results;
+    }
+    memoryText = snapshot.text;
+  }
+
   const budgetFailure = acceptedSubsetBudgetFailure({
     proposal,
     accepted,
     repo,
     capTokens: config.budgetTokens,
+    memoryText,
   });
   if (budgetFailure) {
     results.failed.push(budgetFailure);
@@ -81,6 +223,11 @@ export function applyDecisions({ proposal, decisions, repo, state, config, dryRu
     byFile.get(edit.file).push(edit);
   }
 
+  // Compose first, write later. Each file's accepted edits are applied to one immutable
+  // image of that file; only a set that composes completely earns a write.
+  const planned = [];
+  const landed = new Set();
+
   for (const [relative, edits] of byFile) {
     const absolute = path.join(repo.root, relative);
     if (!fs.existsSync(absolute)) {
@@ -88,35 +235,198 @@ export function applyDecisions({ proposal, decisions, repo, state, config, dryRu
       continue;
     }
 
-    const before = fs.readFileSync(absolute, "utf8");
+    const before =
+      relative === proposal.memoryFile?.path && memoryText !== null ? memoryText : fs.readFileSync(absolute, "utf8");
     let text = before;
     const applied = [];
+    const failures = [];
 
     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 });
+        failures.push({ file: relative, edit: edit.id, error: err.message });
+      }
+    }
+
+    if (failures.length) {
+      results.failed.push(...failures);
+      if (applied.length) {
+        results.failed.push({
+          file: relative,
+          error: `${relative} was left unchanged: a file takes every accepted edit or none of them`,
+        });
       }
+      continue;
     }
 
     if (text === before) continue;
+    planned.push({ relative, absolute, before, text, applied });
+    for (const id of applied) landed.add(id);
+  }
+
+  const plannedTargets = new Map();
+  const resolvedPlanned = [];
+  for (const item of planned) {
+    let resolved;
+    try {
+      resolved = fs.realpathSync(item.absolute);
+    } catch (err) {
+      results.failed.push({ file: item.relative, error: `${item.relative} could not be resolved: ${err.message}` });
+      continue;
+    }
+    const existing = plannedTargets.get(resolved);
+    if (existing) {
+      results.failed.push({
+        file: item.relative,
+        error: `${item.relative} resolves to the same target as ${existing.relative}; nothing was written`,
+      });
+      continue;
+    }
+    const resolvedItem = { ...item, resolved };
+    plannedTargets.set(resolved, resolvedItem);
+    resolvedPlanned.push(resolvedItem);
+  }
 
+  if (results.failed.length) return results;
+
+  // Skills go in before the memory file. A skill nothing points at yet is inert, while a
+  // memory file pointing at a skill that is not there is actively wrong - so if a skill
+  // cannot be written, the files that would reference it are left alone.
+  const plannedSkills = [];
+  const skillPaths = new Set();
+  for (const edit of accepted) {
+    if (edit.kind !== "extract" || !landed.has(edit.id)) continue;
+    for (const skill of editSkills(edit)) {
+      const absolute = path.join(repo.root, skill.path);
+      if (skillPaths.has(skill.path) || fs.existsSync(absolute)) {
+        results.failed.push({
+          file: skill.path,
+          edit: edit.id,
+          error: `${skill.path} already exists; nothing was written`,
+        });
+      }
+      skillPaths.add(skill.path);
+      plannedSkills.push({ edit, skill });
+    }
+  }
+  if (results.failed.length) return results;
+
+  const canonical = plannedSkills.find(
+    ({ skill }) => skill.path === CANONICAL_SKILLS_DIR || skill.path.startsWith(`${CANONICAL_SKILLS_DIR}/`),
+  );
+  const createdDirectoryCandidates = absentParentDirectories(repo.root, [
+    ...plannedSkills.map(({ skill }) => path.join(repo.root, skill.path)),
+    ...(canonical ? [path.join(repo.root, CLAUDE_SKILLS_LINK)] : []),
+  ]);
+  const skillFailures = [];
+  const ownedSkillPaths = [];
+  for (const { edit, skill } of plannedSkills) {
+    try {
+      const layout = dryRun
+        ? { created: [], warnings: [] }
+        : writeSkill(repo.root, skill, { exclusive: true, ensureLayout: false });
+      results.skills.push({ path: skill.path, dryRun, created: layout.created });
+      if (!dryRun) {
+        ownedSkillPaths.push(...("ownership" in layout && Array.isArray(layout.ownership) ? layout.ownership : []));
+      }
+      for (const w of layout.warnings) if (!results.warnings.includes(w)) results.warnings.push(w);
+    } catch (err) {
+      skillFailures.push({ file: skill.path, edit: edit.id, error: err.message });
+    }
+  }
+
+  const rollbackSkills = () => {
+    const { removed, conflicts } = removeOwnedSkillPaths(ownedSkillPaths);
+    removeEmptyDirectories(createdDirectoryCandidates);
+    results.skills = [];
+    const removedPaths = removed.map((item) => item.relative).filter(Boolean);
+    if (removedPaths.length) {
+      results.failed.push({
+        error: `rolled back skill paths written earlier in this round: ${removedPaths.join(", ")}`,
+      });
+    }
+    for (const item of conflicts) {
+      results.failed.push({
+        file: item.relative,
+        error: `${item.relative} rollback conflict: the skill changed after this apply wrote it; left untouched`,
+      });
+    }
+  };
+
+  if (skillFailures.length) {
+    results.failed.push(...skillFailures);
+    rollbackSkills();
+    for (const { relative } of planned) {
+      results.failed.push({
+        file: relative,
+        error: `${relative} was left unchanged: its edits point at a skill that could not be written`,
+      });
+    }
+    return results;
+  }
+
+  const orderedPlanned = [...resolvedPlanned].sort((a, b) => {
+    const aMemory = a.relative === proposal.memoryFile.path;
+    const bMemory = b.relative === proposal.memoryFile.path;
+    return Number(aMemory) - Number(bMemory);
+  });
+  const committed = [];
+  const rollbackCommitted = () => {
+    for (const written of [...committed].reverse()) {
+      if (!commitStillCurrent(written.commit)) {
+        results.failed.push({
+          file: written.relative,
+          error: `${written.relative} rollback conflict: the file changed after this apply wrote it; left untouched`,
+        });
+        continue;
+      }
+      try {
+        atomicReplace(written.commit.absolute, written.before);
+      } catch (rollbackError) {
+        results.failed.push({
+          file: written.relative,
+          error: `${written.relative} could not be rolled back: ${rollbackError.message}`,
+        });
+      }
+    }
+    results.written = [];
+  };
+  for (const item of orderedPlanned) {
+    const { relative, resolved, before, text, applied } = item;
     const budget = relative === proposal.memoryFile.path ? budgetStatus(before, text, config.budgetTokens) : null;
 
-    if (!dryRun) fs.writeFileSync(absolute, text);
+    let commit = null;
+    try {
+      if (!dryRun) commit = atomicReplace(resolved, text);
+    } catch (err) {
+      results.failed.push({
+        file: relative,
+        error: `${relative} could not be written: ${err.message}`,
+      });
+      rollbackCommitted();
+      rollbackSkills();
+      return results;
+    }
+    committed.push({ ...item, commit });
     results.written.push({ file: relative, edits: applied, budget, dryRun });
+
+    // Shrinking over several runs is the design, so this is a heading, not a failure.
+    if (budget && !budget.withinBudget) results.warnings.push(overBudgetWarning(relative, budget));
   }
 
-  for (const edit of accepted) {
-    if (edit.kind !== "extract" || !edit.skill) continue;
+  if (!dryRun && canonical) {
     try {
-      const layout = dryRun ? { created: [], warnings: [] } : writeSkill(repo.root, edit.skill);
-      results.skills.push({ path: edit.skill.path, dryRun, created: layout.created });
+      const layout = ensureSkillsLayout(repo.root);
+      const result = results.skills.find(({ path: skillPath }) => skillPath === canonical.skill.path);
+      result.created = [...new Set([...result.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 });
+      results.failed.push({ file: CLAUDE_SKILLS_LINK, edit: canonical.edit.id, error: err.message });
+      rollbackCommitted();
+      rollbackSkills();
+      return results;
     }
   }
 

package/src/cli.js

@@ -74,7 +74,7 @@ COMMANDS
              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
+  propose    aggregate gradients, then high-reasoning gradient descent
              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
@@ -99,10 +99,10 @@ MODELS (two-tier: cheap analysis, smart synthesis - all through acpx)
   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]
+  --analysis-effort <e>    one-off reasoning effort, when supported          [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]
+  --synthesis-effort <e>   one-off 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]
 

package/src/commands/apply.js

@@ -10,8 +10,8 @@ import { budgetBar, formatTokens } from "../tokens.js";
  *
  * By default it serves the shipped static template through lavish-axi and waits for one
  * structured decision vector; `--no-ui` keeps the same ACCEPT/REJECT decision in the
- * terminal. `applyDecisions` revalidates the accepted subset against the budget before
- * writing; a failing set records no rejections.
+ * terminal. `applyDecisions` owns the pre-write freshness, budget, and composition gates;
+ * a failing gate records no rejections.
  */
 export async function cmdApply(ctx) {
   const { config, repo } = ctx;

package/src/commands/propose.js

@@ -35,6 +35,10 @@ export async function foldForRun(ctx, memoryFile) {
 
 export async function runProposal(ctx, precomputed = null) {
   const { repo, config } = ctx;
+  // Starting a new proposal run invalidates the previous result immediately. Discovery,
+  // folding, and agent resolution can all fail before synthesis starts; none of those
+  // failures may leave an older proposal available to apply as if it came from this run.
+  config.state.clearProposal();
   const { file } = precomputed || primaryMemoryFile(repo, config);
   const transcripts = precomputed?.transcripts || (await discoverForRun(ctx)).transcripts;
 
@@ -113,6 +117,60 @@ export function printProposal(proposal, { applied = false, analysisUsage = [] }
   out("Review and apply with `backpass apply` (nothing has been written).");
 }
 
+/** True when a violation is about the always-loaded budget rather than the annotation. */
+const isBudgetViolation = (v) => /-token budget/.test(v);
+const isEditCapViolation = (v) => /per-run cap is \d+/.test(v);
+
+/**
+ * What to actually try next, read off the condition the run ended on.
+ *
+ * The old advice - a stronger model, a bigger budget, a higher edit cap - was printed for
+ * every failure, including the ones where the model never spoke and the ones where the
+ * budget was never the constraint. Each terminal condition has a different repair.
+ */
+export function synthesisFailureHint(err) {
+  if (err.reason === "empty") {
+    return "the synthesis harness returned no text, so nothing about the model, the budget, or the edit cap was the constraint; run `backpass propose` again to start a fresh synthesis session";
+  }
+  if (err.reason === "unparseable") {
+    return "the model answered but not with a JSON object; run `backpass propose` again, or pin a different harness with --synthesis-agent";
+  }
+  if (err.reason === "editing") {
+    return "the agent kept rewriting the staging copy instead of describing it; run `backpass propose` again to start fresh";
+  }
+  const violations = err.violations || [];
+  if (violations.some(isBudgetViolation)) {
+    return "the edit set did not clear the budget gate: raise --budget, or let the shrink continue over more runs";
+  }
+  if (violations.some(isEditCapViolation)) {
+    return "the annotation proposed more edits than the per-run learning rate allows: raise --max-edits, or re-run and let the next pass take the rest";
+  }
+  return "the gates above are what the next synthesis must satisfy; run `backpass propose` again";
+}
+
+/**
+ * Report a synthesis that ended without a valid proposal: loudly, and about the turn that
+ * actually ended it (design section 6).
+ *
+ * The saved proposal and the terminal condition can be from different turns - a run whose
+ * last turn was empty leaves the rejected proposal of an earlier one on disk - so the
+ * provenance is printed rather than letting the older violations read as this turn's.
+ */
+export function printSynthesisFailure(err, state) {
+  info("");
+  for (const violation of err.violations) info(`  ${color.red("x")} ${violation}`);
+  info("");
+  if (!err.saved) {
+    info(color.dim("  no proposal was saved: no annotation turn produced one"));
+    return;
+  }
+  info(color.dim(`  the rejected proposal was saved to ${state.proposalPath}`));
+  if (err.reason !== "gates") {
+    info(color.dim(`  it is from annotation attempt ${err.saved.attempt}, not the turn above, and it lists:`));
+    for (const violation of err.saved.violations) info(color.dim(`    - ${violation}`));
+  }
+}
+
 export async function cmdPropose(ctx) {
   try {
     const { proposal } = await runProposal(ctx);
@@ -124,12 +182,8 @@ export async function cmdPropose(ctx) {
     return 0;
   } catch (err) {
     if (err instanceof ProposalViolation) {
-      // Loud failure, never silent truncation (design section 6).
-      info("");
-      for (const violation of err.violations) info(`  ${color.red("x")} ${violation}`);
-      info("");
-      info(color.dim(`  the rejected proposal was saved to ${ctx.config.state.proposalPath}`));
-      throw new UserError(err.message, "try a stronger synthesis model, or raise --budget / --max-edits");
+      printSynthesisFailure(err, ctx.config.state);
+      throw new UserError(err.message, synthesisFailureHint(err));
     }
     throw err;
   }

package/src/commands/run.js

@@ -2,7 +2,7 @@ import { UserError, color, info, json, out } from "../logger.js";
 import { ProposalViolation } from "../proposal.js";
 import { runAnalysis } from "./analyze.js";
 import { bootstrapJson, bootstrapRun, printBootstrap } from "./bootstrap.js";
-import { printProposal, runProposal } from "./propose.js";
+import { printProposal, printSynthesisFailure, runProposal, synthesisFailureHint } from "./propose.js";
 import { budgetBar, formatTokens } from "../tokens.js";
 import { startTui } from "../tui/index.js";
 import { resolveMemoryFiles } from "../memory.js";
@@ -10,7 +10,7 @@ import { resolveMemoryFiles } from "../memory.js";
 /**
  * The default command: one full backward pass.
  *
- *   discover -> distill -> analyze (cheap, fanned out) -> fold -> synthesize (one big call)
+ *   discover -> distill -> analyze (cheap, fanned out) -> fold -> synthesize (high-reasoning turns)
  *
  * It never writes - with one exception: a repo with no memory file at all is
  * bootstrapped (`./bootstrap.js`), which only ever creates files. Otherwise applying
@@ -31,6 +31,8 @@ export async function cmdRun(ctx) {
       )}`,
     );
 
+    config.state.clearProposal();
+
     if (!resolveMemoryFiles(repo.root, config.memoryFiles).primary) {
       const result = await bootstrapRun(ctx);
       tui?.stop();
@@ -82,11 +84,8 @@ export async function cmdRun(ctx) {
   } catch (err) {
     tui?.stop();
     if (err instanceof ProposalViolation) {
-      info("");
-      for (const violation of err.violations) info(`  ${color.red("x")} ${violation}`);
-      info("");
-      info(color.dim(`  the rejected proposal was saved to ${config.state.proposalPath}`));
-      throw new UserError(err.message, "try a stronger synthesis model, or raise --budget / --max-edits");
+      printSynthesisFailure(err, config.state);
+      throw new UserError(err.message, synthesisFailureHint(err));
     }
     throw err;
   } finally {