backpass 0.1.8 → 0.1.10

package/README.md

@@ -84,7 +84,7 @@ backpass reads the local transcript stores of seven harnesses directly. No API,
 | -------------- | ---------------------------------------------- | --------------------------------------------------- |
 | **claude**     | `~/.claude/projects/<munged-cwd>/<uuid>.jsonl` | per-line `cwd`                                      |
 | **codex**      | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | `cwd` + recorded `git.repository_url`               |
-| **pi**         | `~/.pi/agent/sessions/<escaped-cwd>/*.jsonl`   | session-header `cwd`                                |
+| **pi**         | standalone and BB-managed Pi JSONL stores      | session-header `cwd`                                |
 | **opencode**   | `~/.local/share/opencode/opencode.db` (sqlite) | `session.directory`                                 |
 | **grok**       | `~/.grok/sessions/<encoded-cwd>/<uuid>/`       | `summary.json` `cwd` + `git_remotes`                |
 | **cursor CLI** | `~/.cursor/chats/<md5(cwd)>/<uuid>/`           | `meta.json` `cwd`                                   |
@@ -95,6 +95,12 @@ relocated config dir does not hide its sessions. The variable is read from backp
 environment: if you reach that profile through an alias that only prefixes `claude`, set it
 for the backpass run too (`CLAUDE_CONFIG_DIR=~/.claude-work backpass`, or export it).
 
+Pi collection covers standalone sessions under `~/.pi/agent/sessions/` and BB-managed Pi
+sessions under `~/.bb/pi-bridge-sessions/`. It also honors `PI_CODING_AGENT_DIR`,
+`PI_CODING_AGENT_SESSION_DIR`, `BB_DATA_DIR`, and `BB_PI_BRIDGE_SESSION_DIR` when they are
+set in backpass's environment. When roots overlap, backpass scans every applicable layout
+and reads each JSONL file once.
+
 Hermes collection includes CLI and ACP sessions only. Gateway, cron, and WhatsApp sessions
 are excluded because their recorded cwd belongs to the shared gateway process, not a project.
 
@@ -148,9 +154,14 @@ instruction covers.
 most important defence against a model confabulating influence. Negative evidence (a
 visible violation) is weighted highest.
 
-Results are cached per transcript, keyed to both the transcript's content _and_ the memory
-file's hash: edit the weights and the evidence correctly re-computes; change nothing and
-the next run is free.
+Results are cached per transcript, keyed to both the transcript's content _and_ the effective
+memory-file set hash: edit the weights and the evidence correctly re-computes; change nothing
+and the next run is free. A memory-file edit therefore reanalyzes without `--force` - that is
+not a cache miss, it is the cache doing its job - and the run says so on stderr, naming the
+old and new hash, so a "0 reused" line reads as "the file changed" rather than "reuse is
+broken." Evidence files that are not refreshed remain on disk but are excluded while their
+hash is stale. They become eligible again if the memory-file set returns to that hash;
+evidence for transcripts included in the new analysis is replaced with fresh judgments.
 
 ### 4. Aggregate gradients - deterministic, no model
 
@@ -159,6 +170,13 @@ Evidence is grouped by instruction, giving each one a positive/negative count an
 gaps across sessions are clustered, and clusters seen in fewer than `minGapEvidence`
 sessions (default 2) are dropped. One bad session never rewrites the weights.
 
+Only evidence judged against the _current_ memory-file set hash is folded into a proposal. A
+transcript that fell out of this run's sample - the time window, `maxTranscripts`, or the
+transcript itself being gone - can leave an older evidence file on disk under a hash the
+memory-file set no longer has; that file is left untouched, but it does not count toward this
+run's session total or instruction scores, or add a gap observation, until it is current
+again.
+
 Those sessions are counted across runs, not per run: every gap sighting is kept in
 `.backpass/gap-ledger.json` by gap and session, so a gap seen in one session today and in
 another session next week graduates on the later run. The same session never counts twice,
@@ -277,8 +295,10 @@ Apply preflights every accepted edit before writing. The proposal was measured a
 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
+told to run `backpass` again to re-propose against the current file. That rerun reanalyzes
+transcripts against the file that exists now; it does not reuse the stale judgments behind
+the refused proposal. 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpass",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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/analyze.js

@@ -185,7 +185,16 @@ async function pool(items, limit, worker) {
 export async function analyzeTranscripts({ transcripts, memoryFile, config, repo, memoryHash, force = false }) {
   const state = config.state;
   const pending = [];
-  const summary = { total: transcripts.length, cached: 0, analyzed: 0, skipped: 0, failed: 0, usage: [] };
+  const summary = {
+    total: transcripts.length,
+    cached: 0,
+    analyzed: 0,
+    skipped: 0,
+    failed: 0,
+    usage: [],
+    staleMemoryHash: 0,
+  };
+  const priorHashes = new Set();
 
   for (const transcript of transcripts) {
     const existing = state.readEvidence(transcript.id);
@@ -193,9 +202,23 @@ export async function analyzeTranscripts({ transcripts, memoryFile, config, repo
       summary.cached += 1;
       continue;
     }
+    // Distinguish "no prior evidence" from "prior evidence exists, but it was judged
+    // against a memory-file set that no longer matches" - a re-analysis here, not a miss.
+    if (existing?.status === "ok" && existing.memoryHash && existing.memoryHash !== memoryHash) {
+      summary.staleMemoryHash += 1;
+      priorHashes.add(existing.memoryHash);
+    }
     pending.push(transcript);
   }
 
+  if (summary.staleMemoryHash) {
+    info(
+      `${color.yellow("·")} ${summary.staleMemoryHash} transcript(s) have evidence from a previous ` +
+        `memory-file set (${[...priorHashes].join(", ")} -> ${memoryHash}); that evidence is stale, not ` +
+        `missing, and reuse resumes once this pass re-judges it against the current memory-file set`,
+    );
+  }
+
   if (!pending.length) {
     emitProgress("analyze:start", { pending: 0, cached: summary.cached, total: transcripts.length, jobs: config.jobs });
     emitProgress("analyze:done", summary);

package/src/apply/writer.js

@@ -76,7 +76,8 @@ function memoryFileSnapshot(proposal, repo) {
         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.`,
+          `Run \`backpass\` to re-propose against the current repository - that pass reanalyzes transcripts ` +
+          `against the file that exists now, it does not reuse the judgments behind this proposal.`,
       },
     };
   }
@@ -94,7 +95,8 @@ function memoryFileSnapshot(proposal, repo) {
       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}.`,
+        `against the current ${relative} - that pass reanalyzes transcripts against the new file, it does ` +
+        `not reuse the stale judgments behind this proposal.`,
     },
   };
 }

package/src/commands/bootstrap.js

@@ -1,7 +1,8 @@
 import { analyzeTranscripts } from "../analyze.js";
 import { applyDecisions, writeBootstrapFiles } from "../apply/writer.js";
 import { bootstrapTargets, renderPointer, starterMemoryFile } from "../bootstrap.js";
-import { color, info, json, out, warn } from "../logger.js";
+import { UserError, color, info, json, out, warn } from "../logger.js";
+import { resolveMemoryFiles } from "../memory.js";
 import { emitProgress } from "../progress.js";
 import { ProposalViolation } from "../proposal.js";
 import { synthesizeProposal } from "../synthesize.js";
@@ -52,14 +53,25 @@ export async function bootstrapRun(ctx, deps = {}) {
   const seed = [{ path: canonical, text: starter.text }];
   if (pointer) seed.push({ path: pointer, text: renderPointer(canonical) });
   const seeded = writeBootstrapFiles(repo.root, seed);
+  const resolved = resolveMemoryFiles(repo.root, config.memoryFiles);
   for (const w of seeded.written) info(`${color.green("·")} wrote ${w.file}`);
   for (const s of seeded.skipped) warn(`${s.file} ${s.reason} - left untouched`);
 
+  const canonicalSkipped = seeded.skipped.some((entry) => entry.file === canonical);
+  if (canonicalSkipped || resolved.primary?.path !== starter.path || resolved.primary?.text !== starter.text) {
+    throw new UserError(
+      `${canonical} changed while backpass was bootstrapping it`,
+      "run `backpass` again to analyze the memory file that now exists",
+    );
+  }
+  const memoryFile = resolved.primary;
+  const memoryHash = resolved.hash;
+
   emitProgress("memory", {
-    path: starter.path,
-    tokens: starter.tokens,
+    path: memoryFile.path,
+    tokens: memoryFile.tokens,
     budget: config.budgetTokens,
-    units: starter.units.length,
+    units: memoryFile.units.length,
   });
 
   const result = {
@@ -78,10 +90,10 @@ export async function bootstrapRun(ctx, deps = {}) {
 
   result.summary = await analyze({
     transcripts,
-    memoryFile: starter,
+    memoryFile,
     config,
     repo,
-    memoryHash: starter.hash,
+    memoryHash,
     force: Boolean(ctx.flags.force),
   });
   info(
@@ -89,7 +101,7 @@ export async function bootstrapRun(ctx, deps = {}) {
       `${result.summary.skipped} too short · ${result.summary.failed} failed`,
   );
 
-  const folded = await foldForRun(ctx, starter);
+  const folded = await foldForRun(ctx, memoryFile, memoryHash);
   config.state.writeSummary(folded);
   emitProgress("fold:done", {
     instructions: folded.instructions.length,
@@ -102,7 +114,7 @@ export async function bootstrapRun(ctx, deps = {}) {
 
   try {
     const { proposal } = await synthesize({
-      memoryFile: starter,
+      memoryFile,
       summary: folded,
       config,
       repo,

package/src/commands/propose.js

@@ -15,11 +15,21 @@ import { discoverForRun } from "./scan.js";
  * prune what the current file now covers or what aged out (after recording, because the
  * evidence files that fed an expired sighting are still on disk and would re-add it),
  * then cluster from the ledger.
+ *
+ * Evidence is also filtered to `memoryHash`: a transcript's evidence file is rewritten
+ * every time it is re-analyzed against a changed memory file, but a transcript that fell
+ * out of this run's sample (window, cap, or discovery drift) leaves its last evidence file
+ * on disk under whatever hash it was last judged against. That leftover file is real and
+ * reusable the moment its transcript is re-analyzed - or immediately, if the memory file's
+ * bytes return to that hash - but folding it into *this* proposal would score it against
+ * an instruction index it was never judged against (aliases are positional) and inflate
+ * `analyzedSessions` with a session this run never touched. Nothing is migrated, rewritten,
+ * or deleted here - only excluded from this run's fold.
  */
-export async function foldForRun(ctx, memoryFile) {
+export async function foldForRun(ctx, memoryFile, memoryHash) {
   const { state, minGapEvidence, gapLedgerMaxAge } = ctx.config;
   const evidence = state.listEvidence();
-  const relevant = evidence.filter((e) => e.memoryPath === memoryFile.path);
+  const relevant = evidence.filter((e) => e.memoryPath === memoryFile.path && e.memoryHash === memoryHash);
 
   const ledger = state.readGapLedger();
   recordGapObservations(ledger, relevant);
@@ -39,11 +49,11 @@ export async function runProposal(ctx, precomputed = null) {
   // 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 { file, hash } = precomputed || primaryMemoryFile(repo, config);
   const transcripts = precomputed?.transcripts || (await discoverForRun(ctx)).transcripts;
 
   const foldStarted = Date.now();
-  const summary = await foldForRun(ctx, file);
+  const summary = await foldForRun(ctx, file, hash);
   config.state.writeSummary(summary);
   emitProgress("fold:done", {
     instructions: summary.instructions.length,

package/src/discovery/adapters/pi.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 
 import {
@@ -13,7 +14,9 @@ import {
 } from "./shared.js";
 
 /**
- * pi: ~/.pi/agent/sessions/<escaped-cwd>/<ISO-ts>_<uuid>.jsonl
+ * Pi writes standalone sessions under
+ * `~/.pi/agent/sessions/<escaped-cwd>/<ISO-ts>_<uuid>.jsonl`. BB's Pi bridge writes the
+ * same JSONL shape directly under `<bb-data-dir>/pi-bridge-sessions/`.
  *
  * Line 1 is `{type:"session", cwd, id}`. Entries form a parent/child tree but arrive in
  * order, so a linear read is faithful. `model_change` / `thinking_level_change` records
@@ -26,13 +29,69 @@ export function storeRoot() {
   return home(".pi", "agent", "sessions");
 }
 
+function expandEnvPath(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  if (trimmed === "~") return home();
+  if (trimmed.startsWith("~/")) return path.join(home(), trimmed.slice(2));
+  return path.resolve(trimmed);
+}
+
+function realpathOrResolve(value) {
+  try {
+    return fs.realpathSync(value);
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+function storeSpecs() {
+  const specs = [
+    { path: storeRoot(), direct: false, nested: true },
+    { path: home(".bb", "pi-bridge-sessions"), direct: true, nested: false },
+  ];
+  const piAgentDir = expandEnvPath(process.env.PI_CODING_AGENT_DIR);
+  if (piAgentDir) specs.push({ path: path.join(piAgentDir, "sessions"), direct: false, nested: true });
+  const piSessionDir = expandEnvPath(process.env.PI_CODING_AGENT_SESSION_DIR);
+  if (piSessionDir) specs.push({ path: piSessionDir, direct: true, nested: false });
+  const bbDataDir = expandEnvPath(process.env.BB_DATA_DIR);
+  if (bbDataDir) specs.push({ path: path.join(bbDataDir, "pi-bridge-sessions"), direct: true, nested: false });
+  const bridgeDir = expandEnvPath(process.env.BB_PI_BRIDGE_SESSION_DIR);
+  if (bridgeDir) specs.push({ path: bridgeDir, direct: true, nested: false });
+
+  const unique = new Map();
+  for (const spec of specs) {
+    const key = realpathOrResolve(spec.path);
+    const existing = unique.get(key);
+    if (existing) {
+      existing.direct ||= spec.direct;
+      existing.nested ||= spec.nested;
+    } else {
+      unique.set(key, spec);
+    }
+  }
+  return [...unique.values()];
+}
+
+export function storeRoots() {
+  return storeSpecs().map((spec) => spec.path);
+}
+
 export function enumerate() {
   const out = [];
-  for (const dir of listDirs(storeRoot())) {
-    for (const file of listFiles(dir, ".jsonl")) {
+  const seen = new Set();
+  for (const spec of storeSpecs()) {
+    const files = [
+      ...(spec.direct ? listFiles(spec.path, ".jsonl") : []),
+      ...(spec.nested ? listDirs(spec.path).flatMap((dir) => listFiles(dir, ".jsonl")) : []),
+    ];
+    for (const file of files) {
+      const key = realpathOrResolve(file);
+      if (seen.has(key)) continue;
+      seen.add(key);
       const stat = statOrNull(file);
       if (!stat) continue;
-      out.push({ key: file, path: file, mtimeMs: stat.mtimeMs, bytes: stat.size });
+      out.push({ key, path: file, mtimeMs: stat.mtimeMs, bytes: stat.size });
     }
   }
   return out;