backpass 0.1.10 → 0.1.12

package/README.md

@@ -143,16 +143,30 @@ Calculating loss costs one call per transcript, so the set is capped first: past
 everything. Each transcript's weight halves every `sampleHalfLife` (default 14d), and the
 sample is drawn without replacement, so recent sessions are almost always kept and old
 ones stay represented in proportion. When this happens the run says so on stderr
-(`discovered 340 transcript(s), analyzing a recency-weighted sample of 100`); pass
-`--max-transcripts all` to analyze every transcript, or `--seed <n>` to reproduce a sample.
+(`discovered 340 transcript(s), analyzing a recency-weighted sample of 100`).
+
+The draw is deterministic and sticky: it is derived from each transcript's own durable
+identity, not from a fresh random seed, so rerunning does not trigger a fresh draw that
+randomly reshuffles the sample and wastes model calls. Existing transcripts keep their
+draws as the corpus grows, while new sessions compete for room on the same footing. Recency
+weights still evolve as transcripts age, so the selected set can change over time. Pass
+`--max-transcripts all` to analyze every transcript, or `--seed <n>` to draw a different,
+equally reproducible sample.
 
 Each distilled trace goes to a cheap model with the memory file and a rubric. It returns
 strict JSON: which instructions helped, which were violated, and what mistakes no current
-instruction covers.
+instruction covers. Every negative carries a class - `harm` (following the instruction
+caused damage), `non-compliance` (the agent ignored it), or `irrelevant` - because those
+argue for opposite fates: harm argues against an instruction, non-compliance argues for
+reinforcing it. Every gap carries a domain - `project` for this repository's own
+engineering, `orchestration` for the task-management layer around the session - and the
+analysis is shown the ledger's open gaps so it can cite an existing gap id instead of
+coining a paraphrase of it.
 
 **Every claim must carry a verbatim quote.** Quoteless items are discarded - the single
-most important defence against a model confabulating influence. Negative evidence (a
-visible violation) is weighted highest.
+most important defence against a model confabulating influence. Negative evidence is
+weighted highest, but its class determines what it supports: non-compliance supports
+reinforcement, while only harm supports removal.
 
 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
@@ -163,12 +177,24 @@ broken." Evidence files that are not refreshed remain on disk but are excluded w
 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
-
-Evidence is grouped by instruction, giving each one a positive/negative count and a
-**relevance** figure: the share of analyzed sessions in which it mattered at all. Duplicate
-gaps across sessions are clustered, and clusters seen in fewer than `minGapEvidence`
-sessions (default 2) are dropped. One bad session never rewrites the weights.
+### 4. Aggregate gradients - and one judged consolidation call
+
+Evidence is grouped by instruction, giving each one a positive/negative count, a count of
+distinct sessions with harm-class negatives, and a **relevance** figure: the share of
+analyzed sessions in which it mattered at all. Duplicate gaps across sessions are
+clustered, and clusters seen in fewer than `minGapEvidence` sessions (default 2) are
+dropped. One bad session never rewrites the weights.
+
+Whether two sightings are one gap is a judgment call, not a word-overlap score - models
+paraphrase, and a paraphrase that fails a lexical match would hide real recurrence.
+Identity is judged twice: the quote-anchored analysis turn cites an existing gap id when
+it sees a gap already on the books, and, when at least two open entries exist, one bounded
+consolidation call sees the full open gap set and merges entries that describe the same
+mistake. That second judgment is what lets two sightings of a brand-new gap in the same
+run's parallel fan-out corroborate. A failed consolidation call degrades the run to
+lexical identity and says so; it never aborts. Orchestration-domain gaps are counted and
+reported but never cluster: mistakes about the task harness around a session do not
+become instructions in the project's memory file.
 
 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
@@ -204,6 +230,12 @@ Then mechanical gates run, and they are not negotiable:
   is a violation, so is an edit that names no change
 - new instructions need evidence from `minGapEvidence` distinct sessions (an edit that
   only adds text is a new instruction, whatever the model calls it)
+- removing an instruction outright needs harm-class negatives from `minGapEvidence`
+  distinct sessions - non-compliance never counts, because a rule that was skipped needs
+  reinforcement, not deletion (a change that only deletes text outside an extraction is a
+  removal, whatever the model calls it)
+- an extraction preserves every line it removes in the skills it creates; a deletion is
+  never part of an extract
 - every edit carries a verbatim quote
 - the post-edit file must fit the budget, measured on the staged file
 
@@ -212,6 +244,10 @@ Neighbouring removals are merged into one measured change, and a merged change c
 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.
+The measurement splits a contiguous removal at an extraction-vs-deletion boundary when
+both resulting changes can be anchored safely, so accepting the extraction does not
+silently accept the deletion beside it. If either change cannot be anchored uniquely, it
+keeps the merged change rather than guessing.
 
 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
@@ -415,6 +451,7 @@ CLI flags on top:
   "gapLedgerMaxAge": "90d",
   "maxTranscripts": 100,
   "sampleHalfLife": "14d",
+  "seed": null,
   "analysis": { "agent": null, "model": null, "effort": null },
   "synthesis": { "agent": null, "model": null, "effort": null },
   "ladders": {
@@ -447,7 +484,7 @@ Everything mutable lives in `.backpass/`, kept out of git via the repo's local e
 ```
 .backpass/
   scan-cache.json        collect-samples verdicts by path + mtime + size
-  evidence/<id>.json     per-transcript loss
+  evidence/<identity>.json per-transcript loss
   evidence-summary.json  aggregated gradients
   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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpass",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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

@@ -6,9 +6,11 @@ import { distill } from "./distill.js";
 import { readTranscript } from "./discovery/index.js";
 import { renderInstructionIndex } from "./memory.js";
 import { renderPrompt } from "./prompts.js";
+import { renderOpenGapIndex } from "./gap-ledger.js";
 import { evidenceKey, isEvidenceFresh, safeFileName } from "./state.js";
 import { emitProgress } from "./progress.js";
 import { UserError, color, info, warn } from "./logger.js";
+import { transcriptIdentity } from "./transcript.js";
 
 /**
  * Stage 1 of the pipeline (design section 3): one cheap model call per transcript,
@@ -32,6 +34,9 @@ function noteOnce(note) {
   warn(note);
 }
 
+/** Negative evidence carries one of these classes; anything else is dropped as unjudged. */
+export const NEGATIVE_CLASSES = ["harm", "non-compliance", "irrelevant"];
+
 /** Evidence items without a verbatim quote are dropped - the rubric's central rule. */
 export function sanitizeEvidence(parsed) {
   const clean = { positive: [], negative: [], gaps: [], usedRawTranscript: Boolean(parsed?.usedRawTranscript) };
@@ -42,23 +47,33 @@ export function sanitizeEvidence(parsed) {
   for (const key of ["positive", "negative"]) {
     for (const item of Array.isArray(parsed[key]) ? parsed[key] : []) {
       if (!hasQuote(item) || typeof item.instruction !== "string") continue;
-      clean[key].push({
+      const entry = {
         instruction: item.instruction.trim(),
         moment: String(item.moment ?? "").slice(0, 80),
         effect: String(item.effect ?? "").slice(0, 400),
         quote: item.quote.trim().slice(0, 600),
-      });
+      };
+      // The class is what keeps "the agent skipped the rule" from being read as "the
+      // rule caused harm" downstream. Only an explicit judged value is kept; records
+      // from before the field existed simply carry none, and none never counts as harm.
+      if (key === "negative" && NEGATIVE_CLASSES.includes(item.class)) entry.class = item.class;
+      clean[key].push(entry);
     }
   }
 
   for (const item of Array.isArray(parsed.gaps) ? parsed.gaps : []) {
     if (!hasQuote(item) || typeof item.proposedInstruction !== "string") continue;
-    clean.gaps.push({
+    const gap = {
       mistake: String(item.mistake ?? "").slice(0, 400),
       proposedInstruction: item.proposedInstruction.trim().slice(0, 400),
       recurrenceRisk: ["high", "medium", "low"].includes(item.recurrenceRisk) ? item.recurrenceRisk : "medium",
       quote: item.quote.trim().slice(0, 600),
-    });
+      domain: item.domain === "orchestration" ? "orchestration" : "project",
+    };
+    if (typeof item.matchesGap === "string" && /^[0-9a-f]{16}$/.test(item.matchesGap.trim())) {
+      gap.matchesGap = item.matchesGap.trim();
+    }
+    clean.gaps.push(gap);
   }
 
   return clean;
@@ -80,10 +95,10 @@ export function transcriptLabel(transcript) {
 }
 
 function promptPathFor(state, transcript) {
-  return path.join(state.applyDir, "..", "prompts", `${safeFileName(transcript.id)}.md`);
+  return path.join(state.applyDir, "..", "prompts", `${safeFileName(transcriptIdentity(transcript))}.md`);
 }
 
-async function analyzeOne({ transcript, memoryFile, config, repo, slot = 0 }) {
+async function analyzeOne({ transcript, memoryFile, config, repo, slot = 0, openGapIndex = "(none yet)" }) {
   const raw = await readTranscript(transcript);
   const distilled = distill(raw.events, {
     ...transcript,
@@ -119,6 +134,7 @@ async function analyzeOne({ transcript, memoryFile, config, repo, slot = 0 }) {
   const prompt = renderPrompt("analysis", {
     MEMORY_PATH: memoryFile.path,
     INSTRUCTION_INDEX: renderInstructionIndex(memoryFile),
+    OPEN_GAPS: openGapIndex,
     TRACE: distilled.trace,
   });
 
@@ -197,7 +213,7 @@ export async function analyzeTranscripts({ transcripts, memoryFile, config, repo
   const priorHashes = new Set();
 
   for (const transcript of transcripts) {
-    const existing = state.readEvidence(transcript.id);
+    const existing = state.readEvidence(transcript);
     if (!force && isEvidenceFresh(existing, transcript, memoryHash)) {
       summary.cached += 1;
       continue;
@@ -241,6 +257,10 @@ export async function analyzeTranscripts({ transcripts, memoryFile, config, repo
       `${pick.model ? ` (${pick.model})` : ""}${pick.effort ? ` effort=${pick.effort}` : ""} at jobs=${config.jobs}`,
   );
 
+  // Rendered once per run: the ledger's open gaps, so each analysis can cite an existing
+  // gap id instead of coining a paraphrase of it (`matchesGap` in the reply schema).
+  const openGapIndex = renderOpenGapIndex(state.readGapLedger(), memoryFile.path);
+
   let done = 0;
   const evidenceTotals = { positive: 0, negative: 0, gaps: 0 };
   await pool(pending, config.jobs, async (transcript, _index, slot) => {
@@ -248,6 +268,7 @@ export async function analyzeTranscripts({ transcripts, memoryFile, config, repo
       transcript: {
         harness: transcript.harness,
         id: transcript.id,
+        identity: transcriptIdentity(transcript),
         path: transcript.path,
         mtimeMs: transcript.mtimeMs,
         bytes: transcript.bytes,
@@ -269,14 +290,14 @@ export async function analyzeTranscripts({ transcripts, memoryFile, config, repo
     });
 
     try {
-      const result = await analyzeOne({ transcript, memoryFile, config, repo, slot });
+      const result = await analyzeOne({ transcript, memoryFile, config, repo, slot, openGapIndex });
       if (result.status === "skipped") {
         summary.skipped += 1;
-        state.writeEvidence(transcript.id, { ...base, status: "skipped", reason: result.reason });
+        state.writeEvidence(transcript, { ...base, status: "skipped", reason: result.reason });
       } else {
         summary.analyzed += 1;
         summary.usage.push(result.usage);
-        state.writeEvidence(transcript.id, {
+        state.writeEvidence(transcript, {
           ...base,
           status: "ok",
           stats: result.distilled.stats,
@@ -292,7 +313,7 @@ export async function analyzeTranscripts({ transcripts, memoryFile, config, repo
       // Per-transcript fail-soft: recorded, listed by `backpass status`, retried next run.
       summary.failed += 1;
       warn(`${transcript.harness} ${transcriptLabel(transcript)}: ${err.message}`);
-      state.writeEvidence(transcript.id, { ...base, status: "failed", error: err.message });
+      state.writeEvidence(transcript, { ...base, status: "failed", error: err.message });
     } finally {
       done += 1;
       emitProgress("analyze:tick", {

package/src/apply/lavish.js

@@ -26,7 +26,10 @@ export function injectPayload(template, payload, toolVersion) {
     .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>`);
+  // A function replacer, not a string one: a string second argument to `replace` treats
+  // `$&`, `` $` ``, `$'`, and `$$` in it as replacement patterns, and `tag` embeds
+  // untrusted proposal text that can contain any of those sequences verbatim.
+  return template.replace("</head>", () => `${tag}\n</head>`);
 }
 
 export function renderApplySurface(proposal, state, toolVersion) {

package/src/cli.js

@@ -87,9 +87,9 @@ COLLECT SAMPLES
   --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
+  --max-transcripts <n>    cap per run; past it a recency-weighted sticky sample
                            is analyzed. 0 or "all" disables the cap          [100]
-  --seed <n>               make the transcript sample reproducible
+  --seed <n>               draw a different reproducible transcript sample
 
 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,
@@ -109,7 +109,7 @@ MODELS (two-tier: cheap analysis, smart synthesis - all through acpx)
 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]
+  --min-gap-evidence <n>   sessions needed to add or remove instruction [2]
   --memory-file <path>     memory file to optimize (repeatable)
   --skills-dir <path>      where skill extractions are written          [.agents/skills]
 

package/src/commands/bootstrap.js

@@ -8,7 +8,7 @@ import { ProposalViolation } from "../proposal.js";
 import { synthesizeProposal } from "../synthesize.js";
 import { budgetBar, formatTokens } from "../tokens.js";
 import { discoverForRun } from "./scan.js";
-import { foldForRun, printProposal } from "./propose.js";
+import { accountForConsolidationUsage, foldForRun, printProposal } from "./propose.js";
 
 /**
  * Bootstrap: the default run when the repo has no memory file at all.
@@ -41,6 +41,7 @@ export async function bootstrapRun(ctx, deps = {}) {
   const discover = deps.discover || discoverForRun;
   const analyze = deps.analyze || analyzeTranscripts;
   const synthesize = deps.synthesize || synthesizeProposal;
+  const fold = deps.fold || foldForRun;
   const { canonical, pointer } = bootstrapTargets(config.memoryFiles);
 
   const { transcripts, perHarness } = await discover(ctx);
@@ -101,7 +102,7 @@ export async function bootstrapRun(ctx, deps = {}) {
       `${result.summary.skipped} too short · ${result.summary.failed} failed`,
   );
 
-  const folded = await foldForRun(ctx, memoryFile, memoryHash);
+  const folded = await fold(ctx, memoryFile, memoryHash);
   config.state.writeSummary(folded);
   emitProgress("fold:done", {
     instructions: folded.instructions.length,
@@ -121,6 +122,7 @@ export async function bootstrapRun(ctx, deps = {}) {
       transcripts,
       runNote: BOOTSTRAP_RUN_NOTE,
     });
+    accountForConsolidationUsage(proposal, folded);
     const decisions = Object.fromEntries(proposal.edits.map((e) => [e.id, "accepted"]));
     const applied = applyDecisions({ proposal, decisions, repo, state: config.state, config });
     proposal.appliedAt = new Date().toISOString();

package/src/commands/propose.js

@@ -1,3 +1,4 @@
+import { consolidateGapLedger } from "../consolidate.js";
 import { foldEvidence } from "../fold.js";
 import { ledgerGapObservations, pruneGapLedger, recordGapObservations } from "../gap-ledger.js";
 import { synthesizeProposal } from "../synthesize.js";
@@ -33,14 +34,32 @@ export async function foldForRun(ctx, memoryFile, memoryHash) {
 
   const ledger = state.readGapLedger();
   recordGapObservations(ledger, relevant);
+  // Consolidate after recording, so the pass sees this run's sightings too: two
+  // sessions coining the same brand-new gap in one parallel fan-out can only line up
+  // here. One bounded judged call; a failure degrades to lexical identity and the run
+  // continues. Prune afterwards so a merged-then-covered gap retires as one entry.
+  const consolidation = await consolidateGapLedger({
+    ledger,
+    memoryPath: memoryFile.path,
+    config: ctx.config,
+    repo: ctx.repo,
+  });
   pruneGapLedger(ledger, { memoryFile, memoryPath: memoryFile.path, maxAge: gapLedgerMaxAge });
   state.writeGapLedger(ledger);
 
-  return foldEvidence(relevant, {
+  const summary = foldEvidence(relevant, {
     minGapEvidence,
     memoryFile,
     gapObservations: ledgerGapObservations(ledger, memoryFile.path),
   });
+  summary.consolidation = consolidation;
+  return summary;
+}
+
+export function accountForConsolidationUsage(proposal, summary) {
+  if (summary.consolidation?.usage) {
+    proposal.usage = [summary.consolidation.usage, ...(proposal.usage || [])];
+  }
 }
 
 export async function runProposal(ctx, precomputed = null) {
@@ -78,6 +97,7 @@ export async function runProposal(ctx, precomputed = null) {
     transcripts,
   });
 
+  accountForConsolidationUsage(proposal, summary);
   config.state.writeProposal(proposal);
   return { proposal, summary, memoryFile: file };
 }

package/src/config.js

@@ -53,9 +53,10 @@ export const DEFAULT_CONFIG = {
    */
   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.
+   * Cap on transcripts analyzed per run; past it a deterministic, 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` selects a different reproducible
+   * sample.
    */
   maxTranscripts: 100,
   sampleHalfLife: "14d",

package/src/consolidate.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { execOneShot, extractJson, sessionPrompt, usageRecord } from "./acpx.js";
+import { mergeGapEntries } from "./gap-ledger.js";
+import { renderPrompt } from "./prompts.js";
+import { warn } from "./logger.js";
+
+/**
+ * Pre-synthesis gap consolidation: one bounded model call that sees the full open gap
+ * set for the memory file and merges entries that are paraphrases of one gap.
+ *
+ * This is the second half of gap identity. The first half - the analysis turn citing an
+ * existing gap id (`matchesGap`) - covers a sighting that arrives AFTER its partner is
+ * already on the books. It cannot cover two sightings of a brand-new gap landing in the
+ * same run's parallel fan-out: neither analysis saw the other's entry, so both coin one.
+ * Consolidation runs after this run's observations are recorded and before the fold
+ * clusters, so those same-run paraphrases still corroborate.
+ *
+ * Judgment is required here by design: word-bigram similarity cannot recognize a real
+ * paraphrase (measured on a production ledger: 89 entries containing at least six
+ * multi-session gaps, highest cross-session score 0.34 against the 0.45 bar). The model
+ * is asked only "same gap or not", the merge itself is mechanical (`mergeGapEntries`),
+ * unknown ids and malformed groups are dropped, and a session is never double-counted
+ * however the entries merge. Strict admission is untouched: merging changes how
+ * sightings line up, never how many distinct sessions a proposal needs.
+ *
+ * Exactly one call per run, and only when at least two entries exist. Failure is
+ * fail-soft with a warning: the run degrades to lexical identity (the pre-consolidation
+ * behavior), it never aborts - the next run re-judges the same open entries.
+ */
+
+/** Ledger entries below this count never need a call; nothing could merge. */
+const MIN_ENTRIES = 2;
+
+let callCounter = 0;
+
+function renderEntries(entries) {
+  return entries
+    .map((entry) => {
+      const sessions = Object.keys(entry.sessions).length;
+      const mistake = firstMistake(entry);
+      return (
+        `[${entry.id}] (sessions=${sessions}) ${entry.proposedInstruction}` +
+        (mistake ? `\n    mistake: ${mistake}` : "")
+      );
+    })
+    .join("\n");
+}
+
+function firstMistake(entry) {
+  for (const obs of Object.values(entry.sessions)) {
+    const flat = String(obs.mistake || "")
+      .replace(/\s+/g, " ")
+      .trim();
+    if (flat) return flat.length > 160 ? `${flat.slice(0, 160)}...` : flat;
+  }
+  return "";
+}
+
+/**
+ * Run the consolidation call and apply the merges to `ledger` in place.
+ * Returns `{ merged, usage }`, `{ skipped }`, or `{ failed }` - never throws for a
+ * model-side failure, because a run without consolidation is still a valid run.
+ */
+export async function consolidateGapLedger({ ledger, memoryPath, config, repo }) {
+  const entries = Object.values(ledger.entries).filter((e) => e.memoryPath === memoryPath);
+  if (entries.length < MIN_ENTRIES) return { skipped: "fewer than two open gaps" };
+  if (!config.agents) return { skipped: "no agent resolver" };
+
+  const prompt = renderPrompt("consolidate", { GAP_ENTRIES: renderEntries(entries) });
+  const promptFile = path.join(config.state.root, "prompts", "consolidate-gaps.md");
+  fs.mkdirSync(path.dirname(promptFile), { recursive: true });
+  fs.writeFileSync(promptFile, prompt);
+
+  let ranWith = null;
+  let result;
+  try {
+    result = await config.agents.withFallthrough("analysis", async (pick) => {
+      ranWith = pick.agent;
+      const call = {
+        agent: pick.agent,
+        model: pick.model,
+        promptFile,
+        cwd: repo.root,
+        timeoutSeconds: config.timeoutSeconds,
+        promptRetries: config.promptRetries,
+      };
+      if (!pick.effort) return execOneShot(call);
+      callCounter += 1;
+      return sessionPrompt({
+        ...call,
+        effort: pick.effort,
+        sessionName: `backpass-consolidate-${process.pid}-${callCounter}`,
+      });
+    });
+  } catch (err) {
+    warn(`gap consolidation failed (${err.message}); continuing with lexical gap identity for this run`);
+    return { failed: err.message };
+  }
+
+  const parsed = extractJson(result.text);
+  if (!parsed || !Array.isArray(parsed.merges)) {
+    warn("gap consolidation returned no parseable merge list; continuing with lexical gap identity for this run");
+    return { failed: "no parseable merge list", usage: usageRecord(ranWith, result) };
+  }
+
+  const merged = mergeGapEntries(ledger, parsed.merges);
+  return { merged, usage: usageRecord(ranWith, result) };
+}

package/src/diff.js

@@ -161,7 +161,7 @@ export function rawHunks(ops) {
  * Occurrences may overlap (a run of identical lines): counting them non-overlapping
  * would call a window unique while the first match sits somewhere else entirely.
  */
-function countOccurrences(haystack, needle) {
+export function countOccurrences(haystack, needle) {
   if (!needle) return 0;
   let count = 0;
   let at = haystack.indexOf(needle);
@@ -178,7 +178,7 @@ function countOccurrences(haystack, needle) {
  * newline *before* it instead. Both sides of a hunk share tail-ness (the suffix after the
  * change is identical), so `find` and `replace` built this way splice cleanly.
  */
-function span(lines, start, end) {
+export function span(lines, start, end) {
   if (end <= start) return "";
   const body = lines.slice(start, end).join("\n");
   if (end === lines.length) return `${start > 0 ? "\n" : ""}${body}`;

package/src/discovery/index.js

@@ -12,6 +12,7 @@ import { isSelfSession } from "./self.js";
 import { sinceCutoff } from "../config.js";
 import { emitProgress } from "../progress.js";
 import { warn } from "../logger.js";
+import { transcriptIdentity } from "../transcript.js";
 
 export const ADAPTERS = {
   claude,
@@ -52,6 +53,7 @@ export async function discoverTranscripts({ repo, config, strict = false, harnes
   const cache = config.state.readScanCache();
 
   const transcripts = [];
+  const identities = new Set();
   const perHarness = {};
   let cacheDirty = false;
 
@@ -82,15 +84,20 @@ export async function discoverTranscripts({ repo, config, strict = false, harnes
               cacheDirty = true;
             },
           });
-      transcripts.push(...found);
-      stats.matched = found.length;
+      const unique = found.filter((transcript) => {
+        if (identities.has(transcript.identity)) return false;
+        identities.add(transcript.identity);
+        return true;
+      });
+      transcripts.push(...unique);
+      stats.matched = unique.length;
       emitProgress("discover:harness:done", {
         harness,
         scanned: stats.scanned,
         cached: stats.cached,
         matched: stats.matched,
         self: stats.self,
-        tiers: tierCounts(found),
+        tiers: tierCounts(unique),
       });
     } catch (err) {
       stats.error = err.message;
@@ -197,7 +204,7 @@ function discoverFiles(adapter, { repo, config, cutoffMs, strict, stats, cache,
 }
 
 function toTranscript(adapter, row, association, id) {
-  return {
+  const transcript = {
     harness: adapter.name,
     id: `${adapter.name}-${id}`,
     nativeId: id,
@@ -213,6 +220,8 @@ function toTranscript(adapter, row, association, id) {
     association,
     extra: row.extra || {},
   };
+  transcript.identity = transcriptIdentity(transcript);
+  return transcript;
 }
 
 /** Read one transcript through its adapter and normalize it to distiller events. */