backpass 0.1.6 → 0.1.8

package/README.md

@@ -166,9 +166,9 @@ a sighting retires once the memory file gains an instruction that covers it, and
 sightings expire after `gapLedgerMaxAge` (default 90d). Until a gap corroborates it stays
 out of the proposal entirely.
 
-### 5. Gradient descent - one session, native edits
+### 5. Gradient descent - native edits
 
-A single high-reasoning session turns the aggregated gradients into concrete edits: ADD,
+A high-reasoning synthesis run turns the aggregated gradients into concrete edits: ADD,
 REMOVE, REWRITE, or EXTRACT→SKILL. The agent does not describe edits for backpass to
 splice in - it makes them, with its harness's own file tools, in a **staging copy** of the
 memory file under `.backpass/synthesis/` (the repo itself is read-only to it, for
@@ -189,10 +189,31 @@ Then mechanical gates run, and they are not negotiable:
 - every edit carries a verbatim quote
 - the post-edit file must fit the budget, measured on the staged file
 
-A violation triggers a re-prompt naming the exact breach (at most two). If those also
-fail, backpass **fails loudly** and saves the rejected proposal. It never silently
-truncates. A harness that writes past the staging copy into the repo is an error, never
-an apply.
+An extraction is the created `SKILL.md` plus the memory-file change that pays for it.
+Neighbouring removals are merged into one measured change, and a merged change cannot be
+accepted in halves - so when several sections leave together, their skills arrive as one
+extract with several skills, which is one honest accept/reject decision. Skills whose
+removals were measured separately stay separate decisions, and bundling them is refused.
+
+A malformed answer or gate violation triggers a re-prompt naming the exact breach (at
+most two). If those also fail, backpass **fails loudly** and preserves the latest parseable
+rejected proposal, if one was produced. It never silently truncates. A harness that writes
+past the staging copy into the repo is an error, never an apply.
+
+Not every annotate turn is an answer, and the three cases are kept apart because they call
+for different things:
+
+- **the agent edited the copy again** - the ids it was given no longer describe the files.
+  It is shown the fresh measurement and answers again; this costs no re-prompt.
+- **the turn came back empty** - the harness returned success with no text at all. Nothing
+  was said, so there is nothing to correct: the annotation is retried once in a **new**
+  session, since the accumulated context of the old one is the likeliest cause.
+- **the turn returned text** - malformed JSON or a gate violation uses an annotation
+  attempt and can trigger a re-prompt. Only a parseable, gate-rejected answer writes a
+  rejected proposal, stamped with the attempt that produced it.
+
+When a run does fail, the advice it prints comes from the condition it ended on. Run
+`backpass propose` again to start a fresh synthesis.
 
 Token deltas shown to you are measured by backpass from the actual text - never taken from
 the model's own arithmetic.
@@ -249,7 +270,26 @@ edit is not proposed again unless materially new evidence arrives.
 The live budget gauge is not just a readout. Apply rechecks the accepted subset against
 the same budget gate as synthesis: stay under the cap, or shrink if the file is already
 over. An incompatible set writes nothing and does not record rejections, so you can pick
-a compatible set and try again.
+a compatible set and try again. If the run shrinks the file but leaves it above the cap,
+that is progress, not a failure: it is written, and the remaining overage is printed.
+
+Apply preflights every accepted edit before writing. The proposal was measured against one
+exact version of your memory file, so apply first checks the file still exists and is still
+that version. If it was removed or changed since - you pulled, edited it by hand, or another
+agent did - the edits no longer describe what is on disk, so nothing is written and you are
+told to run `backpass` again to re-propose against the current file. Within a run every file
+is composed from one version: it takes every accepted edit or none of them. Apply also
+refuses the whole write if any created skill target already exists or two accepted paths
+resolve to the same file.
+
+Skills and non-memory files are written only after every edit has composed, with the memory
+file committed last. A later write failure rolls back files, skills, and loading-layout
+entries created earlier in that round. If another process changes a committed file before
+rollback reaches it, apply leaves that change untouched and reports the rollback conflict.
+
+For compatibility, proposals created by older backpass versions that do not contain a
+memory-file hash skip the freshness check. Regenerate such a proposal before applying it if
+the repository may have changed.
 
 ```sh
 backpass apply --no-ui     # same decision, in the terminal
@@ -335,9 +375,10 @@ backpass \
   --synthesis-agent claude --synthesis-model claude-opus-5 --synthesis-effort high
 ```
 
-`--no-auto-agent` pins the pre-ladder defaults (codex / claude). If an adapter does not
-advertise reasoning effort, backpass says so in the run report rather than pretending it
-applied.
+`--no-auto-agent` pins the pre-ladder defaults (codex / claude). Model and effort
+overrides are scoped to that Backpass invocation, so they never rewrite your harness
+defaults. If an adapter has no proven overlay, backpass stops rather than pretending it
+applied, except OpenCode effort which is skipped with a report note.
 
 ### Configuration
 
@@ -388,7 +429,7 @@ Everything mutable lives in `.backpass/`, kept out of git via the repo's local e
   scan-cache.json        collect-samples verdicts by path + mtime + size
   evidence/<id>.json     per-transcript loss
   evidence-summary.json  aggregated gradients
-  proposal.json          the latest gradient-descent step
+  proposal.json          the latest parseable gradient-descent step (absent if none was produced)
   synthesis/             the staging copy the gradient-descent agent edited (memory file + skills)
   prompts/               the exact prompts of the last run
   agent-probe-cache.json which harnesses were available and logged in, and when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpass",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "packageManager": "pnpm@11.5.0",
   "description": "Gradient descent for your agent memory - analyzes past agent session transcripts and proposes evidence-backed edits to AGENTS.md / CLAUDE.md",
   "type": "module",

package/src/acpx.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 
-import { warn } from "./logger.js";
+import { UserError, warn } from "./logger.js";
 import { runCapture } from "./subprocess.js";
+import { prepareHarnessInvocation } from "./harness-invoke.js";
 import * as piStore from "./discovery/adapters/pi.js";
 import { readJsonl } from "./discovery/adapters/shared.js";
 
@@ -32,13 +33,13 @@ export function acpxAgentName(agent) {
 }
 
 /**
- * The session config-option id each adapter uses for reasoning effort. There is no
- * shared ACP name for it and `acpx status` does not expose config options, so this
- * small table is measured (see the ordered-defaults design report) rather than
- * derived. Adapters absent here (grok, opencode) advertise no effort option at all;
- * effort is then skipped with a report note, never silently.
+ * The session config-option id each adapter uses for reasoning effort when that
+ * `set` is session-local. Pi is absent: ACP `set thought_level` rewrites
+ * `~/.pi/agent/settings.json`, so Pi effort is process `--thinking` instead
+ * (`src/harness-invoke.js`). Grok uses process `--reasoning-effort`. OpenCode
+ * has no overlay; effort is skipped with a report note, never silently.
  */
-export const EFFORT_OPTION_KEYS = { codex: "reasoning_effort", claude: "effort", pi: "thought_level" };
+export const EFFORT_OPTION_KEYS = { codex: "reasoning_effort", claude: "effort" };
 
 export function effortOptionKey(agent) {
   return EFFORT_OPTION_KEYS[agent] || null;
@@ -60,7 +61,7 @@ export class AcpxError extends Error {
 
 /**
  * @param {string[]} args
- * @param {{ timeoutMs?: number, cwd?: string, input?: string }} [options]
+ * @param {{ timeoutMs?: number, cwd?: string, input?: string, env?: NodeJS.ProcessEnv }} [options]
  */
 function run(args, options = {}) {
   return runCapture(ACPX_BIN, args, options);
@@ -170,6 +171,52 @@ function baseArgs({ cwd, model, timeoutSeconds, approveReads, approveAll = false
   return args;
 }
 
+function invocationAgentArgs(invocation, agent) {
+  return invocation.acpxAgentCommand ? ["--agent", invocation.acpxAgentCommand] : [acpxAgentName(agent)];
+}
+
+async function verifyHarnessInvocation(invocation, cwd) {
+  if (!invocation.requiredBuiltinAgent) return;
+  const args = [...(cwd ? ["--cwd", cwd] : []), "config", "show", "--format", "json"];
+  const result = await run(args, { timeoutMs: 10_000, cwd, env: invocation.env });
+  if (result.code !== 0) {
+    throw new UserError(
+      `cannot verify acpx adapter configuration for ${invocation.requiredBuiltinAgent}: ${firstLine(result.stderr) || `exit ${result.code}`}`,
+      "upgrade acpx or omit the model and effort override",
+    );
+  }
+
+  let config;
+  try {
+    config = JSON.parse(result.stdout);
+  } catch {
+    throw new UserError(
+      `cannot verify acpx adapter configuration for ${invocation.requiredBuiltinAgent}: config show returned invalid JSON`,
+      "upgrade acpx or omit the model and effort override",
+    );
+  }
+
+  if (
+    !config ||
+    typeof config !== "object" ||
+    Array.isArray(config) ||
+    !config.agents ||
+    typeof config.agents !== "object"
+  ) {
+    throw new UserError(
+      `cannot verify acpx adapter configuration for ${invocation.requiredBuiltinAgent}: config show omitted the resolved agents map`,
+      "upgrade acpx or omit the model and effort override",
+    );
+  }
+
+  if (Object.prototype.hasOwnProperty.call(config.agents, invocation.requiredBuiltinAgent)) {
+    throw new UserError(
+      `cannot safely apply model or effort overrides because acpx agents.${invocation.requiredBuiltinAgent} replaces the proven built-in adapter`,
+      `remove the agents.${invocation.requiredBuiltinAgent} replacement or omit the model and effort override`,
+    );
+  }
+}
+
 /** `acpx --version`, used to key the probe cache. Null when acpx is missing. */
 export async function acpxVersion({ timeoutMs = 10_000 } = {}) {
   const result = await run(["--version"], { timeoutMs });
@@ -230,6 +277,7 @@ export async function probeSession({ agent, sessionName, cwd = undefined, timeou
 export async function execOneShot({
   agent,
   model = null,
+  effort = null,
   promptFile,
   cwd,
   timeoutSeconds = 300,
@@ -237,42 +285,56 @@ export async function execOneShot({
   approveReads = true,
   suppressReads = true,
 }) {
+  const invocation = prepareHarnessInvocation({ agent, model, effort });
   const args = [
-    ...baseArgs({ cwd, model, timeoutSeconds, approveReads, suppressReads }),
+    ...baseArgs({ cwd, model: invocation.acpxModel, timeoutSeconds, approveReads, suppressReads }),
     "--prompt-retries",
     String(promptRetries),
-    acpxAgentName(agent),
+    ...invocationAgentArgs(invocation, agent),
     "exec",
     "--file",
     promptFile,
   ];
 
   const startedAt = Date.now();
-  const result = await run(args, { timeoutMs: (timeoutSeconds + 30) * 1000, cwd });
-  if (result.spawnError && result.spawnError.code === "ENOENT") throw notFoundError(result);
-  if (result.timedOut) {
-    throw new AcpxError(`acpx ${agent} exec timed out after ${timeoutSeconds}s`, result);
-  }
-  if (result.code !== 0) {
-    throw new AcpxError(`acpx ${agent} exec failed (exit ${result.code})`, result);
-  }
+  try {
+    await verifyHarnessInvocation(invocation, cwd);
+    if (effort && invocation.setEffortKey) {
+      throw new UserError(
+        `${agent} cannot apply invocation-scoped effort=${effort} in an exec one-shot`,
+        "use a named session or omit the effort override",
+      );
+    }
+    const result = await run(args, { timeoutMs: (timeoutSeconds + 30) * 1000, cwd, env: invocation.env });
+    if (result.spawnError && result.spawnError.code === "ENOENT") throw notFoundError(result);
+    if (result.timedOut) {
+      throw new AcpxError(`acpx ${agent} exec timed out after ${timeoutSeconds}s`, result);
+    }
+    if (result.code !== 0) {
+      throw new AcpxError(`acpx ${agent} exec failed (exit ${result.code})`, result);
+    }
 
-  const combined = `${result.stdout}\n${result.stderr}`;
-  const usage = parseTokenLine(combined) ?? recoverUsageFromStore({ agent, promptFile, cwd, startedAt });
-  return { text: stripAcpxNoise(result.stdout), usage, raw: result.stdout };
+    const combined = `${result.stdout}\n${result.stderr}`;
+    const usage = parseTokenLine(combined) ?? recoverUsageFromStore({ agent, promptFile, cwd, startedAt });
+    return { text: stripAcpxNoise(result.stdout), usage, raw: result.stdout, notes: invocation.notes };
+  } finally {
+    invocation.dispose();
+  }
 }
 
 /**
  * A named session that stays open across turns (design section 5).
  *
- * Reasoning effort is a session config option on every adapter that has one, and
- * `exec` cannot set it - so any call that wants effort applied goes through a session.
- * Synthesis also needs more than one turn in the same context: the agent edits the
- * staging copy, then annotates the changes backpass measured. Adapters that do not
- * advertise an effort option skip that step with a report line - never silently.
+ * Model and effort are applied as invocation-scoped overlays (`src/harness-invoke.js`),
+ * never by rewriting persistent harness defaults. `exec` cannot carry process-level
+ * effort for every harness, so an effortful call still goes through a session when
+ * the overlay needs one. Synthesis also needs more than one turn in the same context:
+ * the agent edits the staging copy, then annotates the changes backpass measured.
+ * OpenCode alone skips its unsupported effort overlay with a report line. Every other
+ * requested overlay without a proven mechanism stops rather than pretending it applied.
  *
  * Resolves to the handle, or throws an `AcpxError` (`unsupported: true` when the adapter
- * has no session support at all, which `sessionPrompt` turns into an exec fallback).
+ * has no session support; `sessionPrompt` only falls back when it can preserve the requested overlays).
  *
  * @returns {Promise<{ notes: string[],
  *   prompt: (options: { promptFile: string, timeoutSeconds?: number, promptRetries?: number,
@@ -281,11 +343,33 @@ export async function execOneShot({
  *   close: () => Promise<void> }>}
  */
 export async function openSession({ agent, model = null, effort = null, sessionName, cwd }) {
-  const notes = [];
-  const acpxAgent = acpxAgentName(agent);
-  const created = await run([acpxAgent, "sessions", "new", "--name", sessionName], { timeoutMs: 60_000, cwd });
-  if (created.spawnError && created.spawnError.code === "ENOENT") throw notFoundError(created);
+  const invocation = prepareHarnessInvocation({ agent, model, effort });
+  const notes = [...invocation.notes];
+  const acpxAgentArgs = invocationAgentArgs(invocation, agent);
+  const runOpts = { timeoutMs: 60_000, cwd, env: invocation.env };
+  try {
+    await verifyHarnessInvocation(invocation, cwd);
+  } catch (err) {
+    invocation.dispose();
+    throw err;
+  }
+  const created = await run(
+    [
+      ...(invocation.acpxModel ? ["--model", invocation.acpxModel] : []),
+      ...acpxAgentArgs,
+      "sessions",
+      "new",
+      "--name",
+      sessionName,
+    ],
+    runOpts,
+  );
+  if (created.spawnError && created.spawnError.code === "ENOENT") {
+    invocation.dispose();
+    throw notFoundError(created);
+  }
   if (created.code !== 0) {
+    invocation.dispose();
     // An auth or spawn failure must surface as such so the caller can fall through.
     if (classifyAcpxFailure(created)) {
       throw new AcpxError(`acpx ${agent} session create failed: ${firstLine(created.stderr)}`, created);
@@ -306,27 +390,23 @@ export async function openSession({ agent, model = null, effort = null, sessionN
   const close = async () => {
     if (closed) return;
     closed = true;
-    const result = await run([acpxAgent, "sessions", "close", sessionName], { timeoutMs: 30_000, cwd });
+    const result = await run([...acpxAgentArgs, "sessions", "close", sessionName], {
+      timeoutMs: 30_000,
+      cwd,
+      env: invocation.env,
+    });
     if (result.code !== 0) warn(`could not close acpx session ${sessionName}`);
+    invocation.dispose();
   };
 
   try {
-    if (model) {
-      const set = await run([acpxAgent, "-s", sessionName, "set", "model", model], { timeoutMs: 60_000, cwd });
+    if (effort && invocation.setEffortKey) {
+      const set = await run([...acpxAgentArgs, "-s", sessionName, "set", invocation.setEffortKey, effort], runOpts);
       if (set.code !== 0) {
-        if (classifyAcpxFailure(set) === "model-unavailable") {
-          throw new AcpxError(`acpx ${agent} rejected model ${model}: ${firstLine(set.stderr)}`, set);
-        }
-        notes.push(`could not set model=${model} on ${agent}: ${firstLine(set.stderr)}`);
-      }
-    }
-    if (effort) {
-      const key = effortOptionKey(agent);
-      const set = key
-        ? await run([acpxAgent, "-s", sessionName, "set", key, effort], { timeoutMs: 60_000, cwd })
-        : null;
-      if (!set || set.code !== 0) {
-        notes.push(`${agent} does not advertise a reasoning-effort option; ran without effort=${effort}`);
+        throw new AcpxError(
+          `acpx ${agent} could not apply invocation-scoped effort=${effort}: ${firstLine(set.stderr) || `exit ${set.code}`}`,
+          set,
+        );
       }
     }
   } catch (err) {
@@ -348,13 +428,13 @@ export async function openSession({ agent, model = null, effort = null, sessionN
       ...baseArgs({ cwd, model: null, timeoutSeconds, approveReads, approveAll, suppressReads }),
       "--prompt-retries",
       String(promptRetries),
-      acpxAgent,
+      ...acpxAgentArgs,
       "-s",
       sessionName,
       "--file",
       promptFile,
     ];
-    const result = await run(args, { timeoutMs: (timeoutSeconds + 30) * 1000, cwd });
+    const result = await run(args, { timeoutMs: (timeoutSeconds + 30) * 1000, cwd, env: invocation.env });
     if (result.timedOut) throw new AcpxError(`acpx ${agent} session prompt timed out after ${timeoutSeconds}s`, result);
     if (result.code !== 0) throw new AcpxError(`acpx ${agent} session prompt failed (exit ${result.code})`, result);
 
@@ -384,8 +464,9 @@ function subtractUsage(current, previous) {
 
 /**
  * One prompt through a short-lived named session: open, prompt, close. The analysis
- * pass uses this whenever an effort is configured. An adapter without session support
- * falls back to a one-shot `exec`, and says so.
+ * pass uses this whenever an effort is configured. Without session support, it falls
+ * back to one-shot `exec` only when that preserves the requested overlays; otherwise it
+ * stops with actionable guidance. OpenCode effort remains the explicit reported skip.
  */
 export async function sessionPrompt({
   agent,
@@ -404,11 +485,20 @@ export async function sessionPrompt({
     session = await openSession({ agent, model, effort, sessionName, cwd });
   } catch (err) {
     if (!(err instanceof AcpxError) || !err.unsupported) throw err;
+    if (effort && (agent === "claude" || agent === "codex")) {
+      throw new UserError(
+        `${agent} cannot apply invocation-scoped effort=${effort} because its acpx adapter does not support sessions`,
+        "upgrade acpx or omit the effort override",
+      );
+    }
     const notes = [`session unsupported for ${agent}; fell back to exec one-shot`];
-    if (effort) notes.push(`${agent} cannot set effort without a session; ran without effort=${effort}`);
+    if (effort && agent === "opencode") {
+      notes.push(`${agent} does not advertise a reasoning-effort option; ran without effort=${effort}`);
+    }
     const fallback = await execOneShot({
       agent,
       model,
+      effort: agent === "opencode" ? null : effort,
       promptFile,
       cwd,
       timeoutSeconds,

package/src/analyze.js

@@ -8,7 +8,7 @@ import { renderInstructionIndex } from "./memory.js";
 import { renderPrompt } from "./prompts.js";
 import { evidenceKey, isEvidenceFresh, safeFileName } from "./state.js";
 import { emitProgress } from "./progress.js";
-import { color, info, warn } from "./logger.js";
+import { UserError, color, info, warn } from "./logger.js";
 
 /**
  * Stage 1 of the pipeline (design section 3): one cheap model call per transcript,
@@ -137,8 +137,8 @@ async function analyzeOne({ transcript, memoryFile, config, repo, slot = 0 }) {
       timeoutSeconds: config.timeoutSeconds,
       promptRetries: config.promptRetries,
     };
-    // Effort is a session config option, so an effortful analysis call needs a
-    // (fresh, per-transcript) session; without effort the plain one-shot is cheaper.
+    // Route effortful calls through a fresh per-transcript session so each harness's
+    // invocation-scoped overlay or safe fallback is applied; otherwise one-shot is cheaper.
     if (!pick.effort) return execOneShot(call);
     callCounter += 1;
     return sessionPrompt({
@@ -265,6 +265,7 @@ export async function analyzeTranscripts({ transcripts, memoryFile, config, repo
         emitProgress("analyze:evidence", { ...evidenceTotals });
       }
     } catch (err) {
+      if (err instanceof UserError) throw err;
       // Per-transcript fail-soft: recorded, listed by `backpass status`, retried next run.
       summary.failed += 1;
       warn(`${transcript.harness} ${transcriptLabel(transcript)}: ${err.message}`);

package/src/apply/terminal.js

@@ -2,6 +2,7 @@ import readline from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 
 import { UserError, color } from "../logger.js";
+import { editSkills } from "../skills.js";
 import { formatTokens } from "../tokens.js";
 
 /**
@@ -51,10 +52,10 @@ export function renderEdit(edit, index, total) {
   out.push("");
   out.push(renderDiff(edit));
 
-  if (edit.kind === "extract" && edit.skill) {
+  for (const skill of edit.kind === "extract" ? editSkills(edit) : []) {
     out.push("");
-    out.push(color.dim(`  new skill: ${edit.skill.path}`));
-    out.push(color.dim(`  description: ${edit.skill.description}`));
+    out.push(color.dim(`  new skill: ${skill.path}`));
+    out.push(color.dim(`  description: ${skill.description}`));
   }
 
   if (edit.evidence?.length) {